Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/district-state-update-mcp-design.md
T

177 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 站点状态修改工具 district.state.update — MCP 设计文档
- 需求:REQ-20261117-0008
- 工具:`district.state.update`(kind=write,category=admin)
- 数据源:m0 `district`(站点主表)+ m0 `district_strategy`(站点策略表)+ m2 `asset_info`(资产联动)
- 对标老接口:`POST /district/setDistrictAttribute`(`DistrictController.java:780-892`,xiaoqu-franchisee)
## 1. 背景
运营需要修改站点状态(测试/履约/演示/撤机)。老系统通过「设置站点属性」页面走
`setDistrictAttribute` 完成,该接口同时承担销售类型、耗材价格、账期、SKU 等多个字段的更新,
是一个多字段共用的写接口。本工具只抽取其中**站点状态 + 三个日期**这一个语义,做成单职责的
研发/运营写工具:零行级权限,只绑研发专用 scope 6。
## 2. 表结构与老接口行为
### 2.1 district(m0)
| 列 | 说明 |
|---|---|
| id | 站点 id |
| district_name | 站点名称(可重名) |
| district_number | 站点编号 |
| modify_id / modify_time | 最后修改人 / 修改时间 |
| soft_delete | 0 正常 |
### 2.2 district_strategy(m0,一个站点一条策略,老代码 `district_id + soft_delete=0 limit 1`)
| 列 | 说明 |
|---|---|
| district_state | 站点状态:0测试 / 1履约 / 2演示 / 3撤机 |
| test_date | 测试日期(LocalDate) |
| honour_date | 履约日期(LocalDate) |
| weaning_date | 撤机日期(LocalDate) |
| modify_id / modify_time | 最后修改人 / 修改时间 |
### 2.3 老接口 setDistrictAttribute 的状态相关逻辑(DistrictController.java:819-856)
1. `BeanUtils.copyProperties(input, districtStrategy)`:input 的同名字段(含 null)覆盖到 strategy,
只 set modify_time(**漏写 modify_id**)。因此未传的非目标日期列可能被清空。
2. **资产联动**(:828-853):仅当旧 state 非 null 且与新 state 不等、且新 state < 3(非撤机)时:
- 查 m2 `asset_info`(district_id,soft_delete=0);
- 只处理 `asset_status ∈ {1测试, 2履约}` 的资产;
- 新 state 为 0(测试)或 2(演示)→ `asset_status = 1(测试)`;
- 新 state 为 1(履约)→ `asset_status = 2(履约)`;
- 撤机(3)不动资产;
- 资产只 set assetStatus,**不写 modify_id/modify_time**。
3. 同接口还更新 district 主表 modify_id/modify_time(:800-802)。
4. 状态与日期**没有强制对应校验**:老接口允许只改日期不改状态、改状态不带日期。
5. strategy 不存在时,老接口在 :828 直接触发 NPE;本工具改为明确报错,不自动创建。
### 2.4 调研结论
- 老接口是多字段共用,没有独立的"只改状态"入口;本工具收窄语义并补齐校验。
- 资产联动是老系统的既有业务规则(演示/测试站点的固定资产视为测试资产,履约站点视为履约资产),
不做联动会造成站点状态与资产状态不一致。
- 本地实体变更(遵循"实体拷贝到本地包"约定):
- `me.iiv.agent.entity.m0.District` 补 `district_number`、`modify_id`、`modify_time`;
- 已有 `me.iiv.agent.entity.m0.DistrictStrategy` 物理表实体补状态、日期和修改字段;
`DistrictDistrictStrategy` 是 `district_district_strategy` **视图**实体,不能写;
- 新增 `me.iiv.agent.entity.m2.AssetInfo`(仅本工具所需列)。
## 3. 工具契约
### 3.1 入参
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| districtName | string | 条件必填 | 站点名称,**精确匹配** `district_name`(soft_delete=0)。与 districtNumber 至少传一个 |
| districtNumber | string | 条件必填 | 站点编号,**精确匹配** `district_number`(soft_delete=0)。与 districtName 至少传一个 |
| districtState | int | 是 | 目标状态:0测试 / 1履约 / 2演示 / 3撤机 |
| testDate | string(yyyy-MM-dd) | state=0 必填 | 测试日期 |
| honourDate | string(yyyy-MM-dd) | state=1 必填 | 履约日期 |
| weaningDate | string(yyyy-MM-dd) | state=3 必填 | 撤机日期 |
校验规则:
1. `districtName` / `districtNumber` 都未传 → `INVALID_ARGUMENT`「站点名称与站点编号至少传一个」。
2. 两个都传:分别解析,必须指向**同一个** district.id,否则 `INVALID_ARGUMENT` 报两边各自命中。
3. 名称匹配多条(重名站点)→ `INVALID_ARGUMENT`,报错附候选 `id(编号)` 列表,引导改用编号。
4. 名称/编号无匹配 → `NOT_FOUND_OR_FORBIDDEN`「站点不存在」。
5. 编号匹配多条 → `DATA_INTEGRITY_ERROR`,不静默选一条。
6. `districtState` 非法值 → `INVALID_ARGUMENT`。
7. 目标状态所需日期缺失、不是 `yyyy-MM-dd` 或不是合法日历日期 → `INVALID_ARGUMENT`。
8. state=2(演示)携带任何日期参数 → `INVALID_ARGUMENT`「修改为演示状态不需要携带日期」。
9. 目标状态与当前状态相同 → `INVALID_ARGUMENT`「站点当前已是 xx 状态」,防止无意义覆盖日期。
10. `district_strategy` 不存在(district_id + soft_delete=0 查不到)→ `DATA_INTEGRITY_ERROR`
「站点策略记录不存在」,不自动创建。
11. state=0/1/3 时,非目标日期入参不写入;只更新目标状态对应的日期列。
### 3.2 行为
1. 解析站点 → 查 strategy → 校验(上述规则)。
2. 在 m0 事务中先更新 `district_strategy`:`district_state` + 目标状态对应的那一个日期列 +
`modify_id`(token 用户 id)+ `modify_time`;其余两个日期列保持原值不动。
3. 在同一 m0 事务中更新 `district` 主表 `modify_id`/`modify_time`;任一影响行数不是 1 即回滚 m0。
4. m0 提交后执行 m2 **资产联动**:
- 触发条件:新旧 state 不等且新 state < 3(同状态已在前置校验拒绝);
- 范围:该站点 `asset_info`(soft_delete=0)中 `asset_status ∈ {1, 2}` 的资产;
- 映射:新 state 0/2 → asset_status=1;新 state 1 → asset_status=2;
- 联动资产补写 modify_id/modify_time;
- m0/m2 跨库不做分布式事务;m2 失败时报错并落审计,已提交的 m0 不回滚。
5. `GuardedToolCallback` 自动向 svc `audit_log` 落调用审计(用户、token、工具、入参摘要、结果、耗时);
业务日志记录站点、新旧状态、联动资产数和 request_id。
### 3.3 返回
```json
{
"districtId": 2803,
"districtName": "测试望京SOHO",
"districtNumber": "xxx",
"before": { "districtState": 0, "districtStateText": "测试", "testDate": "2026-01-01", "honourDate": null, "weaningDate": null },
"after": { "districtState": 1, "districtStateText": "履约", "testDate": "2026-01-01", "honourDate": "2026-11-17", "weaningDate": null },
"linkedAssetCount": 12,
"requestId": "uuid"
}
```
## 4. 权限与 scope
- 零行级权限,门禁完全靠 scope。
- **prod 只绑研发专用 scope 6(code=code)**;dev 绑测试专用 scope(seed-dev.sql 的
kind=write 自动绑定段已覆盖)。不绑任何业务 scope(1/2/3/5)。
- 仅用户委托 Token;服务身份 Token 在工具内再次拒绝,确保 modify_id 可追溯。
## 5. 决策与实施结论
2026-11-18 按用户「继续开发」指示,采用原设计建议值实施。
| # | 决策点 | 结论 |
|---|---|---|
| 1 | 资产联动是否复刻 | **复刻**;联动资产补写 modify 列 |
| 2 | 同名站点 | **报错附候选 `id(编号)` 列表**,引导用编号 |
| 3 | 同状态重复修改 | **报错拒绝**,防止误覆盖日期 |
| 4 | state=2 携带日期 | **报错拒绝** |
| 5 | 非目标状态的历史日期列 | **保留原值不动**,修复老接口 copyProperties 可能清空日期的问题 |
| 6 | strategy 不存在 | **报错**,不自动创建 |
## 6. 与老系统差异汇总
| 差异 | 说明 |
|---|---|
| 语义收窄 | 只改状态+日期,不碰老接口的销售类型/耗材/账期/SKU |
| 状态-日期强校验 | 老接口不校验;本工具按目标状态强制必填对应日期、演示拒收日期 |
| 同状态拒绝 | 老接口允许重复写;本工具拒绝 |
| 历史日期保留 | 老接口 copyProperties 会用 null 覆盖;本工具只写目标日期列 |
| strategy 补写 modify_id | 老接口只写 modify_time |
| 联动资产补写 modify_id/modify_time | 老接口不写 |
| m0 写入事务 | strategy 与 district 审计字段在同一 m0 事务中更新 |
| 名称/编号双路径解析+重名拒绝 | 老接口只按 id 入参 |
## 7. 测试要点
1. 参数校验:两定位参数全空 / state 非法 / 缺对应日期 / 演示带日期 / 日期格式非法。
2. 解析:名称唯一命中 / 名称重名报候选 / 编号命中 / 两参一致与不一致 / 不存在。
3. 守卫:服务 Token 拒绝;同状态拒绝;strategy 不存在。
4. 写路径:各状态迁移的日期列写入正确、其余日期列不动、modify_id/modify_time 写入。
5. 资产联动:state<3 时 asset_status∈{1,2} 的资产被正确映射(0/2→1、1→2),
asset_status∈{0,3} 的不动;state=3 完全不动资产;联动资产 modify 列写入。
6. district 主表 modify 列更新;m0 第二步失败时回滚且不联动资产。
7. 工具注册元数据与真实 MCP 调用的 scope、audit_log 审计。
## 8. 上线步骤(按 AGENTS.md 标准流程)
实现 → 单测 → `./mvnw clean package` 全绿 → 测试环境(test-up.sh + scopeCode=test)写冒烟
(真实站点改状态+改回、DB 复核恢复)→ push main → remote-deploy → 确认 ToolSyncService 新增
→ prod 绑 scope_tool(6, tool_id)(INSERT IGNORE)→ 生产只读核验(tools/list 可见、错误路径用例)
→ ai-proj 收尾(released + 实施记录)。
## 9. 生产上线记录(2026-11-18)
- 功能提交:`435e9bd14b76156f7c0a254fca59b4ca2dc1948d`,已推送 `origin/main`。
- 发布:`./deploy/deploy.sh remote-deploy` 成功;全量 576 个测试通过,生产 pid `3475488`,本地与生产 jar SHA-256 均为 `41a2375580e97a97c3904b5f8c2a0fd8d39898201ceaab5a65e46ec4f31224b4`。
- 注册与权限:`ToolSyncService` 新增 1 个工具,prod tool id `75`;`scope_tool` 唯一有效绑定为 scope `6`(code=`code`,研发专用)。
- 生产只读核验:公网未认证 `/mcp` 返回 401;真实 MCP 握手后 `tools/list` 共 75 个工具且本工具可见;不存在站点编号返回 `NOT_FOUND_OR_FORBIDDEN`,审计落为用户 812 的预期 error。未修改任何生产站点或资产。