10 KiB
10 KiB
站点状态修改工具 district.state.update — MCP 设计文档
- 需求:REQ-20261117-0008
- 工具:
district.state.update(kind=write,category=admin) - 数据源:m0
district(站点主表)+ m0district_strategy(站点策略表)+ m2asset_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)
BeanUtils.copyProperties(input, districtStrategy):input 的同名字段(含 null)覆盖到 strategy, 只 set modify_time(漏写 modify_id)。因此未传的非目标日期列可能被清空。- 资产联动(: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。
- 查 m2
- 同接口还更新 district 主表 modify_id/modify_time(:800-802)。
- 状态与日期没有强制对应校验:老接口允许只改日期不改状态、改状态不带日期。
- 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 必填 | 撤机日期 |
校验规则:
districtName/districtNumber都未传 →INVALID_ARGUMENT「站点名称与站点编号至少传一个」。- 两个都传:分别解析,必须指向同一个 district.id,否则
INVALID_ARGUMENT报两边各自命中。 - 名称匹配多条(重名站点)→
INVALID_ARGUMENT,报错附候选id(编号)列表,引导改用编号。 - 名称/编号无匹配 →
NOT_FOUND_OR_FORBIDDEN「站点不存在」。 - 编号匹配多条 →
DATA_INTEGRITY_ERROR,不静默选一条。 districtState非法值 →INVALID_ARGUMENT。- 目标状态所需日期缺失、不是
yyyy-MM-dd或不是合法日历日期 →INVALID_ARGUMENT。 - state=2(演示)携带任何日期参数 →
INVALID_ARGUMENT「修改为演示状态不需要携带日期」。 - 目标状态与当前状态相同 →
INVALID_ARGUMENT「站点当前已是 xx 状态」,防止无意义覆盖日期。 district_strategy不存在(district_id + soft_delete=0 查不到)→DATA_INTEGRITY_ERROR「站点策略记录不存在」,不自动创建。- state=0/1/3 时,非目标日期入参不写入;只更新目标状态对应的日期列。
3.2 行为
- 解析站点 → 查 strategy → 校验(上述规则)。
- 在 m0 事务中先更新
district_strategy:district_state+ 目标状态对应的那一个日期列 +modify_id(token 用户 id)+modify_time;其余两个日期列保持原值不动。 - 在同一 m0 事务中更新
district主表modify_id/modify_time;任一影响行数不是 1 即回滚 m0。 - 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 不回滚。
GuardedToolCallback自动向 svcaudit_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. 测试要点
- 参数校验:两定位参数全空 / state 非法 / 缺对应日期 / 演示带日期 / 日期格式非法。
- 解析:名称唯一命中 / 名称重名报候选 / 编号命中 / 两参一致与不一致 / 不存在。
- 守卫:服务 Token 拒绝;同状态拒绝;strategy 不存在。
- 写路径:各状态迁移的日期列写入正确、其余日期列不动、modify_id/modify_time 写入。
- 资产联动:state<3 时 asset_status∈{1,2} 的资产被正确映射(0/2→1、1→2), asset_status∈{0,3} 的不动;state=3 完全不动资产;联动资产 modify 列写入。
- district 主表 modify 列更新;m0 第二步失败时回滚且不联动资产。
- 工具注册元数据与真实 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 个测试通过,生产 pid3475488,本地与生产 jar SHA-256 均为41a2375580e97a97c3904b5f8c2a0fd8d39898201ceaab5a65e46ec4f31224b4。 - 注册与权限:
ToolSyncService新增 1 个工具,prod tool id75;scope_tool唯一有效绑定为 scope6(code=code,研发专用)。 - 生产只读核验:公网未认证
/mcp返回 401;真实 MCP 握手后tools/list共 75 个工具且本工具可见;不存在站点编号返回NOT_FOUND_OR_FORBIDDEN,审计落为用户 812 的预期 error。未修改任何生产站点或资产。