177 lines
10 KiB
Markdown
177 lines
10 KiB
Markdown
# 站点状态修改工具 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。未修改任何生产站点或资产。
|