# 作用域-工具绑定启动同步（ScopeToolSyncService）

## 背景

新 MCP 工具部署后，必须绑到调用方使用的 `scope_tool` 记录，否则调用会返回
`PERMISSION_DENIED：该 token 的作用域不包含工具 [...]`。

此前这一步是**管理员手工执行 SQL**，问题：
1. 容易遗漏（2026-10-21：新增的 `hardware.statistics.query` 与用纸类工具部署后一直不可用）；
2. 无法随代码评审，变更不可追溯；
3. 每个环境（test/operation/xiaoqu-ai/sync）都要重复操作。

## 方案

启动时读取配置 `mcp.scope-tool-bindings`，幂等写入 `scope_tool`：

```yaml
mcp:
  scope-tool-bindings: ${MCP_SCOPE_TOOL_BINDINGS:sync=tool.a,tool.b}
```

- 多条绑定用 `;` 分隔，同一条内多个工具用 `,` 分隔
- 格式：`scopeCode=toolName1,toolName2`
- 执行顺序在 `ToolSyncService`（工具注册）之后（`@Order(2)`）

## 安全约束

| 约束 | 说明 |
|---|---|
| 只新增，不删除 | 不触碰管理员手工配置的其他绑定 |
| 能力变更可评审 | 绑定写在 `application-prod.yml` / 环境变量，随代码 diff 审查 |
| 失败不阻断启动 | 作用域或工具不存在时记 WARN 并跳过 |
| 显式声明 | 默认值即"CRM 同步所需 4 个工具"，不含其他能力 |

## 测试

`ScopeToolSyncServiceTest`：
1. 解析：`;` 分隔、空白忽略、缺 `=` 忽略
2. 幂等：已存在的绑定不重复插入
3. 容错：作用域不存在时跳过且不抛异常

## 运维

开通新工具只需改配置并重新部署；启动日志会打印
`scope-tool binding 新增 scope=... tool=...`，可直接核对。