# 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`）

1. 只读：调用链不写业务表（运行时在只读事务里执行，写库会直接报错并回滚）；
2. 不调用外部接口（企微、腾讯 IM、物流、短信等），或可用固定参数避开；
3. 数据范围与后台页面一致；后台本身不做数据范围的，在 `note` 里写明“对有权限的账号返回全量”；
4. 详情类有逐条权限校验（`guard`）；
5. 不返回凭据（各类密钥、令牌、证书），配置类接口一律 `excluded`；
6. 去掉会扩大范围的参数（`forbid`），分页由 MCP 统一控制。

运行时还会检查权限点是否已在菜单登记；未登记（且 `perm_fallback` 里也没有已登记的替代项）的资源即使写了 `open` 也按“待整改”处理。