AI 数据目录人工审核
generated.php 由 php app/mcp/cli/catalog.php --write 扫描后台全部接口生成，只是盘点。
本目录下每个 *.php 文件返回 [资源标识 => 条目]，覆盖自动判断，决定 AI 能否查询、怎么查询。
资源标识就是后台权限点写法，如 tcm.diagnosis/lists。
条目字段
| 字段 | 说明 |
|---|---|
status |
open 开放 / pending 待整改（必须写 reason）/ excluded 不开放（必须写 reason） |
reason |
未开放的原因，会展示给使用者和模型 |
name |
中文名称（菜单名称不清楚时填写） |
note |
口径说明，如“按预约日期统计，不含已取消” |
kind |
覆盖自动识别：list 列表 / detail 单条详情 / report 统计或其他查询 |
params_allow |
允许的查询参数及中文说明 ['patient_name' => '患者姓名（模糊）']；不填则用扫描到的参数减去禁用参数 |
forbid |
额外禁用的参数（会扩大数据范围的开关等），全局禁用见 Catalog::GLOBAL_FORBID |
force |
固定参数，如 ['apply_data_scope' => 1]、['only_archived' => 1] |
guard |
详情类必填：'builtin'（接口自身已做逐条权限校验，需在注释写明函数）、['callable' => [类::class, '方法'], 'args' => ['id', 'admin_id', 'admin_info']]（调用已有校验函数，返回 true 放行）、['via' => '列表资源标识', 'filter' => '参数名', 'match' => 'id']（用列表的数据范围判断） |
handler |
控制器里夹带写操作时改为直接调 Logic：['logic' => [类::class, '方法'], 'args' => ['params', 'admin_id', 'admin_info'], 'validate' => [验证器::class, '场景'], 'error' => [类::class, 'getError']] |
http |
只读但必须 POST 的接口填 'POST' |
perm |
权限点与资源标识不同时填写（如子接口复用页面权限） |
perm_fallback |
自身权限点在部分环境未登记时的替代权限点（按顺序取第一个已登记的），如 ['stats.yejiStats/tabLeaderboard', 'fans/yeji']；自身已登记时不生效 |
timeout |
单条 SQL 超时秒数（默认 10，最大 60），只给后台本身就放宽了执行时间的重型统计 |
开放门槛（全部满足才可 open）
- 只读：调用链不写业务表（运行时在只读事务里执行，写库会直接报错并回滚）；
- 不调用外部接口（企微、腾讯 IM、物流、短信等），或可用固定参数避开；
- 数据范围与后台页面一致；后台本身不做数据范围的，在
note里写明“对有权限的账号返回全量”； - 详情类有逐条权限校验（
guard）； - 不返回凭据（各类密钥、令牌、证书），配置类接口一律
excluded； - 去掉会扩大范围的参数（
forbid），分页由 MCP 统一控制。
运行时还会检查权限点是否已在菜单登记；未登记（且 perm_fallback 里也没有已登记的替代项）的资源即使写了 open 也按“待整改”处理。