更新

2026-09-24 09:45:44 +08:00
parent dbf474ddd7
commit bd22e5f476
38 changed files with 19152 additions and 0 deletions
@@ -0,0 +1,32 @@
+# 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'` |
+
+## 开放门槛（全部满足才可 `open`）
+
+1. 只读：调用链不写业务表（运行时在只读事务里执行，写库会直接报错并回滚）；
+2. 不调用外部接口（企微、腾讯 IM、物流、短信等），或可用固定参数避开；
+3. 数据范围与后台页面一致；后台本身不做数据范围的，在 `note` 里写明“对有权限的账号返回全量”；
+4. 详情类有逐条权限校验（`guard`）；
+5. 不返回凭据（各类密钥、令牌、证书），配置类接口一律 `excluded`；
+6. 去掉会扩大范围的参数（`forbid`），分页由 MCP 统一控制。
+
+运行时还会检查权限点是否已在菜单登记；未登记的资源即使写了 `open` 也按“待整改”处理。