From c8f0024046b7a8bbc03d3c70c40a9c70080cabbf Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Wed, 11 Mar 2026 19:12:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5METER=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E6=A8=A1=E6=9D=BF=E4=B8=8E=E6=8E=A5=E5=8F=A3=E8=BF=BD?= =?UTF-8?q?=E6=BA=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../00_Management/01_Project_Progress.md | 1 + .../design/00_Management/03_Task_Checklist.md | 9 ++ .../02_Detailed_Design/14_METER_Detailed.md | 123 +++++++++++++++++- 3 files changed, 129 insertions(+), 4 deletions(-) diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 7bd860c..6656b86 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -114,6 +114,7 @@ > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。 +| 2026-03-11 | `14_METER_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/14_METER_Detailed.md` 执行与 REV/CS 同步的结构化补完：1）新增“表务模块统一约束”与“接口与数据追溯矩阵”；2）为 `METER-001~METER-004` 补充核心数据、接口映射与落地边界；3）为 `METER-002` 增加工单处理流程图；4）为 `METER-004` 补充关键规则，明确 IoT 数据进入营收开账链路前的校验与异常处理边界。 | 用户要求继续同步分模块正文模板，提升表务模块评审可读性与跨文档追溯一致性。 | 正面影响，表务模块从简要提纲升级为可交付的结构化详细设计，设备档案、工单、库存、物联网接入与营收系统的协同边界更清晰，可降低联调与后续维护中的口径偏差。 | | 2026-03-11 | `13_CS_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/13_CS_Detailed.md` 执行与 REV 同步的结构化补完：1）新增“客户服务模块统一约束”与“接口与数据追溯矩阵”；2）为 `CS-001~CS-007` 全模块补充“接口映射”；3）补充 `CS-005`、`CS-006` 核心数据与各模块落地边界；4）为 `CS-003`、`CS-007` 增加支付相关流程图，强化渠道侧到营收侧的协同链路表达。 | 用户要求继续将“统一约束 + 追溯矩阵 + 接口映射”模板同步到 `13_CS_Detailed.md`。 | 正面影响，客户服务模块文档结构与营收模块保持一致，接口追溯与评审路径更清晰；渠道受理与 `SYS-002/008/009/010` 协同边界明确，可降低后续改稿与联调阶段的口径偏差。 | | 2026-03-11 | `12_REV_Detailed` 设计补完（结构化增强） | 补完 `docs/design/02_Detailed_Design/12_REV_Detailed.md`：1）新增“营收模块统一约束”章节；2）新增“接口与数据追溯矩阵”，统一 `REV-001~REV-009` 对应 `IF-REV-*` 与核心数据域；3）为各 REV 模块补充“接口映射”段落；4）补齐 `REV-009` 缺失的“接口映射 + 落地边界”；5）为 `REV-004/005/006/008` 增加流程图，强化评审可读性与协同边界说明。 | 用户要求补完 `12_REV_Detailed.md`，并提升评审可交付性与跨文档追溯效率。 | 正面影响，营收模块正文从“说明型”提升为“可追溯、可评审、可维护”结构；接口、数据、协同边界更清晰，减少详细设计与接口/数据库专题之间的理解偏差。 | | 2026-03-11 | `docs/design` P2 优化（Archive 标签化与抽检自动化） | 完成 P2 持续优化：1）新增 `scripts/generate-archive-tag-index.sh` 并生成 `docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md`，对 Archive 文档按“来源/用途/可信级别”标签化；2）新增 `scripts/ai-weekly-audit-diff.sh` 并输出 `docs/design/00_Management/14_AI_Audit_Diff_Latest.md` 差异清单；3）在 `Makefile` 接入 `archive-tag-index` 与 `ai-audit-diff` 命令；4）同步更新 `12_AI_Weekly_Audit_Template.md`、`04_Appendix/README.md`、`00_Management/README.md`、`scripts/README.md` 的入口说明。 | 用户要求执行 P2 优化清单，需把“标签化 + 自动化”从规划项落地为可执行资产。 | 正面影响，Archive 资料从“目录分类”升级为“可检索标签资产”；AI 抽检从人工记录升级为脚本化差异输出，周检可复用、可对比、可追踪，后续持续治理成本显著降低。 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 686f396..db28924 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -138,6 +138,15 @@ ## ✅ 最新完成任务 (持续更新) +### 📋 `14_METER_Detailed` 模板同步补完 + +- [x] **完成表务模块结构与追溯增强** ✅ (2026-03-11) + - [x] 新增“表务模块统一约束”章节，明确设备档案、库存、IoT 与营收协同边界 ✅ + - [x] 新增“接口与数据追溯矩阵”，覆盖 `METER-001~METER-004` 的接口与数据域映射 ✅ + - [x] 为 `METER-001~METER-004` 全模块补充核心数据、接口映射与落地边界 ✅ + - [x] 为 `METER-002` 增加工单处理流程图，提升工单闭环表达 ✅ + - [x] 为 `METER-004` 补充关键规则，明确 IoT 数据校验与异常处理口径 ✅ + ### 📋 `13_CS_Detailed` 模板同步补完 - [x] **完成客户服务模块结构与追溯增强** ✅ (2026-03-11) diff --git a/docs/design/02_Detailed_Design/14_METER_Detailed.md b/docs/design/02_Detailed_Design/14_METER_Detailed.md index 776eb2c..d90a7a1 100644 --- a/docs/design/02_Detailed_Design/14_METER_Detailed.md +++ b/docs/design/02_Detailed_Design/14_METER_Detailed.md @@ -14,6 +14,8 @@ retrieval_priority: P1 - [文档定位](#sec-position) - [表务详细设计正文](#sec-content) + - [表务模块统一约束](#sec-meter-rules) + - [接口与数据追溯矩阵](#sec-meter-trace) - [METER-001 表务基础管理](#mod-meter-001) - [METER-002 表务工单管理](#mod-meter-002) - [METER-003 仓储与生命周期管理](#mod-meter-003) @@ -29,6 +31,29 @@ retrieval_priority: P1 # 表务详细设计 + + +## 表务模块统一约束 + +1. 表务模块负责水表档案、状态、库存、工单与物联网接入，账单生成仍归属 `SYS-002` 营收主流程。 +2. 水表状态变更必须通过表务工单、出入库动作或报装装表流程驱动，不允许绕过业务过程直接改写生命周期状态。 +3. 换表、移表、拆表、复装完成后，必须同步客户绑定关系、安装位置和最新表计状态，避免档案与现场状态不一致。 +4. 库存、出入库、报废等动作必须具备批次追溯与操作留痕，满足审计与责任界定要求。 +5. 远传抄表与设备告警数据进入 `SYS-002` 后，必须先完成校验和异常判断，再进入抄表开账链路。 + + + +## 接口与数据追溯矩阵 + +> 说明：接口字段以 `../03_Technical_Design/03_Interface_Design.md` 为准，数据库口径以 `../03_Technical_Design/01_Database_Design.md` 为准。 + +| METER 模块 | 关键接口 | 核心数据域（摘要） | 主要协同对象 | +|---|---|---|---| +| METER-001 表务基础管理 | `IF-METER-001` | `biz_meter`、`biz_meter_model`、`biz_meter_caliber`、`biz_meter_range` | 营收、报装 | +| METER-002 表务工单管理 | `IF-METER-002` | `biz_meter_log`、`biz_process`、`biz_process_transfer` | 移动作业、工单流转 | +| METER-003 仓储与生命周期管理 | `IF-METER-003` | `biz_meter_in_out`、`biz_meter_in_out_rel`、`biz_meter` | 仓储管理端 | +| METER-004 物联网接入与数据同步 | `IF-METER-004` | `biz_meter_read`、`biz_reading_data`、`biz_last_reading` | IoT 平台、营收开账 | + ## METER-001 表务基础管理 @@ -43,6 +68,25 @@ retrieval_priority: P1 - 设备状态覆盖在库、在用、待检、故障、报废等。 - 与客户、水表工单、抄表记录形成关联闭环。 +### 核心数据 + +- `biz_meter`：水表主档。 +- `biz_meter_model`：水表型号。 +- `biz_meter_caliber`：水表口径。 +- `biz_meter_range`：水表量程。 +- `biz_last_reading`：最近有效读数状态。 + +### 接口映射 + +- `IF-METER-001`：查询水表档案、状态与生命周期信息。 +- `IF-REV-001`：客户侧查询场景复用表计关联信息。 + +### 落地边界 + +- **已落地**：水表主档、型号、口径、量程、状态等基础档案对象。 +- **部分落地**：证书、检定批次、厂家深度评价等附属对象可能由扩展字段或附件承载。 +- **文档先行**：复杂设备健康评分与预测性维护不作为当前已实现能力表述。 + ## METER-002 表务工单管理 @@ -51,12 +95,42 @@ retrieval_priority: P1 处理换表、移表、拆表、复装、校表、稽查、维修等表务工单。 +### 业务流程 + +```mermaid +flowchart TD + A[创建表务工单] --> B[派发现场任务] + B --> C[现场处理并采集结果] + C --> D[回写旧表/新表信息] + D --> E[更新水表状态与客户绑定] + E --> F[写入过程日志与附件] + F --> G[工单办结] +``` + ### 关键设计 1. 工单类型决定必填字段、处理流程和附件要求。 2. 换表工单需同时记录旧表拆除信息与新表安装信息。 3. 表务工单完成后同步更新水表档案与客户绑定关系。 +### 核心数据 + +- `biz_meter_log`：表务过程留痕。 +- `biz_process`：工单流程主表。 +- `biz_process_transfer`：转办与流转记录。 +- `biz_meter`：表计状态回写对象。 + +### 接口映射 + +- `IF-METER-002`：换表、移表、校表、维修等处理结果提交。 +- `IF-CS-006`：客户渠道办理结果与表务工单协同。 + +### 落地边界 + +- **已落地**：表务工单过程留痕、流程流转与状态回写能力。 +- **部分落地**：不同工单类型的细化节点主要依赖流程配置，不一定全部存在独立业务表。 +- **文档先行**：复杂多部门并行会签和跨区域协同不宣称为当前独立实现模块。 + ## METER-003 仓储与生命周期管理 @@ -65,12 +139,28 @@ retrieval_priority: P1 管理新表入库、领用、出库、退库、报废及全生命周期追踪。 +### 关键设计 + +1. 库存动作以批次和明细双层结构记录，支持领用、退库、报废等全过程追溯。 +2. 水表生命周期状态与库存动作联动更新，避免“账上在库、现场在用”不一致。 +3. 报废、退库等高风险动作需保留审批或责任人留痕。 + ### 核心数据 -- `biz_meter_log` -- `biz_meter_in_out` -- `biz_meter_in_out_rel` -- `biz_meter` +- `biz_meter_in_out`：出入库主表。 +- `biz_meter_in_out_rel`：出入库明细关系。 +- `biz_meter_log`：库存与生命周期动作留痕。 +- `biz_meter`：生命周期状态主对象。 + +### 接口映射 + +- `IF-METER-003`：领用、退库、报废等库存动作处理。 + +### 落地边界 + +- **已落地**：出入库主明细、生命周期状态回写、动作留痕。 +- **部分落地**：仓位优化、库龄分析等能力可能通过报表层实现，而非独立业务对象。 +- **文档先行**：跨仓调拨优化和自动补货策略仅保留设计方向。 @@ -93,3 +183,28 @@ flowchart TD F --> H[参与开账] G --> I[人工复核处理] ``` + +### 关键规则 + +1. 远传抄表结果必须校验设备标识、采集时间、读数合法性和重复上送情况。 +2. 异常读数、离线状态、设备告警需区分业务异常与设备异常两类处理。 +3. 校验通过的有效读数进入抄表开账链路，异常结果需保留人工复核入口。 + +### 核心数据 + +- `biz_meter_read`：抄表任务或状态承接对象。 +- `biz_reading_data`：远传读数数据。 +- `biz_last_reading`：最新有效读数。 +- `biz_meter`：设备状态与参数关联对象。 + +### 接口映射 + +- `IF-METER-004`：远传抄表、告警与状态同步接收。 +- `IF-EXT-009`：IoT/集抄平台数据接入协同。 +- `IF-REV-004`、`IF-REV-005`：校验通过后进入抄表提交与开账流程。 + +### 落地边界 + +- **已落地**：远传数据接入、基础校验、异常标记与读数同步。 +- **部分落地**：复杂设备诊断与厂家私有协议适配更多由外部 IoT 平台承载。 +- **文档先行**：边缘计算、实时控制指令等能力不作为当前正式实现口径。