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

10 KiB
Raw Blame History

站点状态修改工具 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 返回

{
  "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。未修改任何生产站点或资产。