diff --git a/AGENTS.md b/AGENTS.md index 2967ee1..ce3a5b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,6 +36,55 @@ - frontend lane 只改 `water-frontend` - verify lane 负责样本、日志、验收结论和基线固定 +## specs/ 与 docs/design/ 生命周期 + +本仓库维护两套文档体系，有明确的「一次性 ↔ 持续维护」分工。 + +### specs/ — 过程工件（建设期蓝图，建成后封存） + +`specs/<编号>-/` 是 feature 建设阶段的工作台，每个目录包含： + +- `spec.md`：功能规格（一次性，建成后不维护） +- `plan.md`：实施计划（一次性） +- `tasks.md`：任务拆分（一次性） +- `research.md`：调研记录（一次性） +- `verification.md`：验收记录（建成后封存） +- `data-model.md`：建设期数据模型草稿。建成后正式维护口已移交 `docs/design/03_Technical_Design/01_Database_Design.md` +- `contracts/`：建设期接口契约草稿。建成后正式维护口已移交 `docs/design/03_Technical_Design/03_Interface_Design.md` + +**规则**： +- `spec.md` / `plan.md` / `tasks.md` / `research.md` / `verification.md` 在 feature 建设期间活跃编辑，建成后封存不再修改。 +- `data-model.md` 和 `contracts/` 是临时草稿，feature 建成后数据模型和接口的唯一真源是 `docs/design/` 下的主文档。 +- 禁止在两个体系里并行维护同一份数据模型或接口定义。 +- 禁止创建同一个 feature 的多个 spec 目录（如 `003` 和 `006` 都是 REV-006），发现重复必须合并。 + +### docs/design/ — 正式交付文档（唯一真源，持续维护） + +`docs/design/` 是正式交付的「建成物」描述，所有模块的最终定义收敛在此： + +- `02_Detailed_Design/12_REV_Detailed.md`：REV 模块的功能描述唯一真源 +- `03_Technical_Design/01_Database_Design.md`：表结构的唯一真源 +- `03_Technical_Design/03_Interface_Design.md`：接口定义的唯一真源 + +**规则**：feature 建成后，所有后续维护、修订、查阅原则上以 `docs/design/` 为准，`specs/` 只作为历史追溯参考。 + +### docs/evidence/ — 验证证据（按模块组织） + +证据文件按模块分子目录存放： + +- `docs/evidence/rev004-accounting/` +- `docs/evidence/rev005-invoice/` +- `docs/evidence/rev006-reminder/` +- `docs/evidence/rev007-statistics/` + +禁止在 `docs/evidence/` 根目录平铺散文件。新证据必须归入对应模块子目录。 + +### docs/guides/ — 系统级指南 + +`docs/guides/` 只保留系统级指南（如 Speckit 工作流、系统能力地图、后端现状等）。模块专项操作指南归入 `docs/evidence/<模块>/`。 + +--- + 本文件用于指导通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。 ## 项目定位 @@ -55,18 +104,19 @@ ```text / -├── docs/design/00_Management/ # 项目管理、进度跟踪、交付规范、编写指南 -├── docs/design/01_Overview/ # 总体设计：系统概述、系统架构、概要设计、系统图谱 -├── docs/design/02_Detailed_Design/ # 详细设计：主详设、模块设计、CA 安装设计 -├── docs/design/03_Technical_Design/ # 技术专项：数据库、表结构、接口、安全、部署、加密 -├── docs/design/04_Appendix/ # 附录与归档资料 -├── .claude/ # Claude Code 相关配置 -├── .omc/ # 项目记忆与代理状态 -├── .zed/ # Zed 项目配置 -├── assets/ # 图片、模板等静态资源 -├── docs/ # 研究资料、映射文档、使用指南 -├── scripts/ # 文档处理与导出脚本 -└── infra/ # 辅助基础设施 +├── specs/ # 过程工件：feature 建设期蓝图，建成后封存 +├── docs/design/00_Management/ # 项目管理、进度跟踪、交付规范、编写指南 +├── docs/design/01_Overview/ # 总体设计：系统概述、系统架构、概要设计、系统图谱 +├── docs/design/02_Detailed_Design/ # 详细设计：主详设、模块设计（功能描述唯一真源） +├── docs/design/03_Technical_Design/ # 技术专项：数据库、接口、安全、部署（表结构/接口定义唯一真源） +├── docs/design/04_Appendix/ # 附录与归档资料 +├── docs/evidence/ # 验证证据（按模块分子目录） +├── docs/guides/ # 系统级指南 +├── .claude/ # Claude Code 相关配置 +├── .codex/ # Codex 相关配置 +├── assets/ # 图片、模板等静态资源 +├── scripts/ # 文档处理与导出脚本 +└── infra/ # 辅助基础设施 ``` ## 当前文档组织原则 @@ -82,7 +132,7 @@ - `docs/design/03_Technical_Design/04_Security_Design.md`：安全设计主文档 - `docs/design/03_Technical_Design/05_Deployment_Design.md`：部署设计主文档 -如果已有主文档可以承载内容，**优先编辑现有文件，而不是新增“新-xxx”“最终版”“修订版”之类文件**。 +如果已有主文档可以承载内容，**优先编辑现有文件，而不是新增"新-xxx""最终版""修订版"之类文件**。 ### Archive 仅作归档 @@ -124,7 +174,7 @@ - 风格要求专业、克制、可交付，避免口语化和宣传化表述 - 不写与当前项目无关的泛化模板内容 -### 以“对齐现状”为第一原则 +### 以"对齐现状"为第一原则 所有修改必须优先对齐以下事实来源： @@ -146,7 +196,7 @@ ### 不要过度发挥 - 不要凭空补充不存在的子系统、模块、接口、表 -- 不要为了“显得完整”加入大量无依据的实现细节 +- 不要为了"显得完整"加入大量无依据的实现细节 - 不要默认加入大段代码示例、部署脚本、DDL、伪代码，除非用户明确要求 - 不要创建多余术语体系；优先沿用仓库现有命名 @@ -168,7 +218,7 @@ **福建水务营收系统** -除引用原始资料外，不要混用“营业收费系统”“数智营收管理系统”“客户服务平台”等作为正式系统名称。 +除引用原始资料外，不要混用"营业收费系统""数智营收管理系统""客户服务平台"等作为正式系统名称。 ### 数据库口径 @@ -186,7 +236,7 @@ ### 图表规范 - 所有正式图表优先使用 Mermaid -- 图表必须与正文一致，不能“图一套、文一套” +- 图表必须与正文一致，不能"图一套、文一套" - Mermaid 节点命名尽量避免容易导致解析异常的写法 - 调整图表时，同时检查导出可用性和可读性 @@ -302,7 +352,7 @@ npm run marksman:server - 擅自扩展需求的产品经理 - 无依据发明实现细节的方案生成器 -- 动辄新建文件的“版本制造机” +- 动辄新建文件的"版本制造机" ## 最终目标 diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 91da61c..4cf0bb6 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -118,15 +118,15 @@ | 2026-03-26 | 方案二整体部署方案独立成文 | 1）新增 `docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md`，将已采纳 PostgreSQL 16 方案二后的整体部署方案独立成文；2）结合当前前后端分层部署形态，补齐应用、数据库、中间件、静态存储的一体化部署结构；3）新增软件拓扑图、网络拓扑图、主机角色划分、资源配置建议、网络需求和端口访问建议；4）在 `07_PostgreSQL16_DR_Resource_Application.md` 增加独立文档引用说明，在技术专项目录增加入口。 | 用户明确要求不要仅在 `07` 文档内保留方案二内容，而是需要形成独立文件，并作为已采纳数据库方案后的整体部署方案提交评审。 | 正面影响，数据库资源申请专题与整体部署方案实现职责分离；后续甲方可分别评审“数据库容灾资源申请”和“系统整体部署方案”，减少口径混杂并提升部署审批的可读性。 | | 2026-04-02 | 方案二整体部署文档按网络图口径对齐 | 1）将 `docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md` 的网络分区口径统一为“办公区 / 公网区域 / 互联网区DMZ / 内网区”；2）将 `Nginx` 入口、业务应用节点、`SFTP/FTP` 文件交换服务器的部署区域说明统一调整为与评审图一致；3）同步修正网络拓扑图、访问链路、带宽/端口、资源角色及结论段落中的命名与边界表述。 | 用户提供最新部署图，要求正式文档向图片口径靠拢，消除 `内网 Nginx`、应用区/DMZ、办公区等描述不一致问题。 | 正面影响，整体部署方案的图文一致性显著提升，便于甲方按统一网络边界和主机分区口径开展安全评审与资源审批。 | -| 2026-04-03 | REV-004 全量账务领域设计骨架落地 | 1）新增 `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md`，将“完整承载旧系统账务业务”的目标建模路线落为单一设计底稿；2）统一旧系统账务对象、目标分层、正式业务实体、关系图、目标表设计骨架、迁移与兼容策略、逐步细化计划；3）明确该文档作为后续正式主文档回写前的统一骨架，不与现有 `REV-004` 一期 spec 冲突。 | 用户提出当前目标不是“一期最小闭环”，而是“新系统完整承载旧系统账务业务”，需要先搭建设计骨架再逐步细化并统一口径。 | 正面影响，后续关于账务实体、台账迁移、查询兼容、审批流和数据库设计的讨论有了统一底稿，可显著降低“继续沿用一期口径”和“直接机械平移旧表”之间的反复摇摆。 | +| 2026-04-03 | REV-004 全量账务领域设计骨架落地 | 1）新增 `docs/evidence/rev004-accounting/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md`，将“完整承载旧系统账务业务”的目标建模路线落为单一设计底稿；2）统一旧系统账务对象、目标分层、正式业务实体、关系图、目标表设计骨架、迁移与兼容策略、逐步细化计划；3）明确该文档作为后续正式主文档回写前的统一骨架，不与现有 `REV-004` 一期 spec 冲突。 | 用户提出当前目标不是“一期最小闭环”，而是“新系统完整承载旧系统账务业务”，需要先搭建设计骨架再逐步细化并统一口径。 | 正面影响，后续关于账务实体、台账迁移、查询兼容、审批流和数据库设计的讨论有了统一底稿，可显著降低“继续沿用一期口径”和“直接机械平移旧表”之间的反复摇摆。 | | 2026-04-03 | REV-004 详设正式回写首批收口（RWB-01） | 1）按 `RWB-01` 规则生成正式详设快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-01/2026-04-03-RWB-01-12_REV_Detailed.md`，基线对应 docs 仓 commit `9d2ecf1`；2）重写 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-004 账务处理` 章节，改为“当前正式边界 + 全量目标边界”双层写法，并纳入全量账务对象、审批分层、迁移承接和现状/目标边界；3）保持 `IF-REV-007` 当前统一入口事实，不将目标态误写为已全部落地实现。 | 用户同意从回写准备进入 `RWB-01`，要求先把 `12_REV_Detailed.md` 中 `REV-004` 正式详设改写为可承接全量账务领域的正式入口。 | 正面影响，`REV-004` 正式详设已从“一期五类场景”提升为“可承接全量账务对象的正式入口”，为后续数据库设计、接口设计与迁移专题回写建立了稳定锚点，同时保留了现状/目标分层表达，降低将目标态误判为当前实现的风险。 | | 2026-04-03 | REV-004 数据库专项正式回写首批收口（RWB-02） | 1）按 `RWB-02` 规则生成数据库专项快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-02/2026-04-03-RWB-02-01_Database_Design.md`，基线对应 docs 仓 commit `9d2ecf1`；2）更新 `docs/design/03_Technical_Design/01_Database_Design.md` 中 `SYS-002 开账、收费与票据表`、`biz_operat_log*`、历史台账迁移口径、索引关注点与归档补充，将 `REV-004` 从“一期不新增细表”扩展为“统一骨架 + 目标对象 + 查询投影 / 历史映射”的数据库专项口径；3）正式命名 `AccountingWorkflowRef` 与 `AccountingLegacyMapping` 为目标数据库承接对象，但仍保持“待补字段关注点”写法，不误写成已落地真实表。 | 用户同意进入 `RWB-02` 正式回写，要求先把数据库专项调整为能够承接全量账务领域的正式数据库设计入口。 | 正面影响，数据库专项已从“只描述现有骨架表”提升为“同时约束统一骨架、目标对象、历史映射和查询投影”的正式口径，为后续接口设计回写和实现落表讨论建立了稳定边界，同时避免把目标对象误判为已全部物理落地。 | | 2026-04-03 | REV-004 接口专项正式回写首批收口（RWB-03） | 1）按 `RWB-03` 规则生成接口专项快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-03/2026-04-03-RWB-03-03_Interface_Design.md`，基线对应 docs 仓 commit `9d2ecf1`；2）更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-007`、其请求/响应参数、数据对象与表口径、历史查询与迁移校验接口口径、实现状态说明，将 `REV-004` 从“一期五类场景统一入口”扩展为“当前统一入口 + 全量账务对象承接边界 + 历史查询分层”的正式接口口径；3）保持专属接口仍为后续方向，不误写成当前 backend 已完整落地能力。 | 用户同意进入 `RWB-03` 正式回写，要求先把接口专项调整为能够承接全量账务领域的正式接口设计入口。 | 正面影响，接口专项已从“一期统一处理接口说明”提升为“统一入口、对象承接边界、历史查询出口、实现状态分层”并存的正式口径，为后续总体设计回写和实现拆接口讨论建立了稳定约束，同时避免把目标专属接口误判为当前既成事实。 | | 2026-04-03 | REV-004 总体摘要正式回写收口（RWB-04） | 1）按 `RWB-04` 规则生成总体摘要快照 `docs/design/04_Appendix/Archive/08_Formal_Doc_Snapshots/RWB-04/2026-04-03-RWB-04-03_Summary_Design.md`，基线对应 docs 仓 commit `9d2ecf1`；2）更新 `docs/design/01_Overview/03_Summary_Design.md` 中总体接口定义、营收业务系统外部接口、营收核心模块群概述、模块列表与 `REV-004` 模块摘要，使 REV-004 从“一期五类处理摘要”收敛为“当前统一入口 + 全量账务对象目标边界”的概要口径；3）继续保留当前已落地事实与目标设计边界分层表达，不将专属接口或独立对象实现写成已全部落地。 | 用户同意进入 `RWB-04`，要求完成 REV-004 全量账务领域在总体摘要层的正式收口。 | 正面影响，概要、详设、数据库、接口四层文档现已围绕 REV-004 形成一致口径；后续再讨论实现拆分、迁移验收与对象落表时，可直接基于统一的正式文档体系推进，显著降低跨层级表述不一致风险。 | -| 2026-04-03 | REV-004 实现分发清单与 Agent 交接模板落地 | 1）新增 `docs/guides/REV004_IMPLEMENTATION_HANDOFF.md`，将 REV-004 全量账务领域的后端、前端、联调任务拆分为可直接分发的实现清单；2）同步整理对象范围、统一入口约束、历史只读/映射层边界、建议任务包与给其他 Agent 的提示模板；3）保持该文档定位为实现交接指南，不替代正式设计真源。 | 用户需要一份可直接分发给前后端实现 Agent 的功能清单和对应需求，用于后续协作执行。 | 正面影响，后续多 Agent 协作不再需要重复从正式文档中人工提炼任务；实现范围、分工边界与交接提示可直接复用，降低理解偏差和重复沟通成本。 | -| 2026-04-07 | REV-004 前端实现正式 handoff 落地 | 1）新增 `docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md`，将已批准的 REV-004 前端实现方案转为正式交接文档；2）明确本轮仅覆盖管理后台，不纳入微网厅/客户端实现；3）补齐四张正式执行表：页面清单、路由清单、通用组件清单、lane ownership 清单，并固化 `../water-frontend` 目录下的 `omx team` 执行边界。 | 用户要求把已达成共识的 REV-004 前端实现计划转为正式 handoff Markdown，并细化为可直接执行的正式表格。 | 正面影响，前端实现协作从“计划草案”升级为“执行交接文档”；后续在 `water-frontend` 中可直接按页面清单、路由清单、组件清单和 lane ownership 推进，降低前端实现阶段的范围漂移和分工冲突。 | -| 2026-04-07 | REV-004 前端 team prompts 落地 | 1）新增 `docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md`，将 leader 启动提示与 Lane A~F 执行 prompt 固化为可直接用于 `../water-frontend` 的 `omx team` 文本；2）保持本轮范围仅覆盖管理后台，不纳入微网厅/客户端实现；3）同步固化启动顺序、lane 职责边界与最终统一输出要求。 | 用户要求直接生成可在前端目录执行的 `omx team` prompts，用于下一步正式启动多 lane 实现。 | 正面影响，前端执行已从“交接文档阶段”进入“可直接开干的 prompt 阶段”；leader 与各 lane 不再需要临时编写任务说明，可直接按固定文本启动团队执行，降低启动成本与分工歧义。 | -| 2026-04-07 | REV-004 前端 team prompts 落地 | 1）新增 `docs/guides/REV004_FRONTEND_TEAM_PROMPTS.md`，将 leader 启动提示与 Lane A~F 执行 prompt 固化为可直接用于 `../water-frontend` 的 `omx team` 文本；2）保持本轮范围仅覆盖管理后台，不纳入微网厅/客户端实现；3）同步固化启动顺序、lane 职责边界与最终统一输出要求。 | 用户要求直接生成可在前端目录执行的 `omx team` prompts，用于下一步正式启动多 lane 实现。 | 正面影响，前端执行已从“交接文档阶段”进入“可直接开干的 prompt 阶段”；leader 与各 lane 不再需要临时编写任务说明，可直接按固定文本启动团队执行，降低启动成本与分工歧义。 | +| 2026-04-03 | REV-004 实现分发清单与 Agent 交接模板落地 | 1）新增 `docs/evidence/rev004-accounting/REV004_IMPLEMENTATION_HANDOFF.md`，将 REV-004 全量账务领域的后端、前端、联调任务拆分为可直接分发的实现清单；2）同步整理对象范围、统一入口约束、历史只读/映射层边界、建议任务包与给其他 Agent 的提示模板；3）保持该文档定位为实现交接指南，不替代正式设计真源。 | 用户需要一份可直接分发给前后端实现 Agent 的功能清单和对应需求，用于后续协作执行。 | 正面影响，后续多 Agent 协作不再需要重复从正式文档中人工提炼任务；实现范围、分工边界与交接提示可直接复用，降低理解偏差和重复沟通成本。 | +| 2026-04-07 | REV-004 前端实现正式 handoff 落地 | 1）新增 `docs/evidence/rev004-accounting/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md`，将已批准的 REV-004 前端实现方案转为正式交接文档；2）明确本轮仅覆盖管理后台，不纳入微网厅/客户端实现；3）补齐四张正式执行表：页面清单、路由清单、通用组件清单、lane ownership 清单，并固化 `../water-frontend` 目录下的 `omx team` 执行边界。 | 用户要求把已达成共识的 REV-004 前端实现计划转为正式 handoff Markdown，并细化为可直接执行的正式表格。 | 正面影响，前端实现协作从“计划草案”升级为“执行交接文档”；后续在 `water-frontend` 中可直接按页面清单、路由清单、组件清单和 lane ownership 推进，降低前端实现阶段的范围漂移和分工冲突。 | +| 2026-04-07 | REV-004 前端 team prompts 落地 | 1）新增 `docs/evidence/rev004-accounting/REV004_FRONTEND_OMX_TEAM_PROMPTS.md`，将 leader 启动提示与 Lane A~F 执行 prompt 固化为可直接用于 `../water-frontend` 的 `omx team` 文本；2）保持本轮范围仅覆盖管理后台，不纳入微网厅/客户端实现；3）同步固化启动顺序、lane 职责边界与最终统一输出要求。 | 用户要求直接生成可在前端目录执行的 `omx team` prompts，用于下一步正式启动多 lane 实现。 | 正面影响，前端执行已从“交接文档阶段”进入“可直接开干的 prompt 阶段”；leader 与各 lane 不再需要临时编写任务说明，可直接按固定文本启动团队执行，降低启动成本与分工歧义。 | +| 2026-04-07 | REV-004 前端 team prompts 落地 | 1）新增 `docs/evidence/rev004-accounting/REV004_FRONTEND_TEAM_PROMPTS.md`，将 leader 启动提示与 Lane A~F 执行 prompt 固化为可直接用于 `../water-frontend` 的 `omx team` 文本；2）保持本轮范围仅覆盖管理后台，不纳入微网厅/客户端实现；3）同步固化启动顺序、lane 职责边界与最终统一输出要求。 | 用户要求直接生成可在前端目录执行的 `omx team` prompts，用于下一步正式启动多 lane 实现。 | 正面影响，前端执行已从“交接文档阶段”进入“可直接开干的 prompt 阶段”；leader 与各 lane 不再需要临时编写任务说明，可直接按固定文本启动团队执行，降低启动成本与分工歧义。 | | 2026-03-18 | REV-005 统计模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 为 `T055`、`T060`、`T061`、`T062`、`T063` 新增可直接填写的样本记录模板；2）将 SC-001 ~ SC-004 的建议统计口径细化为表格字段与待补说明，避免后续只剩抽象待办；3）保持“模板已补齐但实际统计结果仍待联调/测试环境补录”的真实状态，不虚构样本结果。 | 用户继续推进 REV-005，希望把剩余统计类待办进一步收敛成可执行模板，便于后续直接补录真实样本而不是重新设计统计格式。 | 正面影响，REV-005 当前已具备统一的统计与日志抽样记录模板；后续补 `T055`、`T060 ~ T063` 时可直接按模板填充真实环境数据，减少再次整理验证文档结构的成本。 | | 2026-03-18 | REV-005 verify 执行入口补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 补齐 `/business/invoice/apply`、`/query`、`/query/compensate`、`/write-back`、`/customer/query`、`/customer/download`、`/customer/push`、`/invalidate`、`/red-ink` 的最小请求模板；2）继续补齐 `T055`、`T060 ~ T063` 的执行命令草稿与样本采集顺序，明确仅作为测试/联调环境占位模板，真实地址、鉴权信息、业务主键与统计结果均待后续替换和回填；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“替换真实环境参数即可执行”的状态。 | 用户继续推进 REV-005，希望不要停留在抽象验证建议，而是把剩余 verify 工作推进到可直接执行、可直接补样本的程度。 | 正面影响，REV-005 当前已具备统一的验证入口、请求模板、命令草稿与采样顺序；后续在测试或联调环境中可直接替换参数发起请求并回填 `T055`、`T060 ~ T063` 的真实结果，减少重复梳理接口和命令的成本。 | @@ -146,8 +146,8 @@ | 2026-03-16 | REV-005 后台发票申请与校验闭环（US1） | 1）在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台发票申请入口；2）在 `service/invoice/InvoiceServiceImpl.java` 实现客户、客户开票信息、账单与税率校验，确保仅已收费未开票账单允许申请；3）补齐 `applicationNo` 或 `custId + chargeIds` 幂等控制、申请单号生成与申请记录落库；4）执行 `mvn -f backend/sw-business/pom.xml -pl sw-business-server -am -DskipTests compile` 最小编译验证并通过。 | 用户要求继续推进 REV-005 implement，优先完成后台发票申请、开票校验与 US1 收尾，不中断当前实现链路。 | 正面影响，REV-005 已形成“后台申请入口 + 关键校验 + 幂等受理 + 最小编译验证”闭环，后续可在此基础上继续推进 SYS-008 调用、开票结果回写、账单状态联动与电子发票推送下载能力。 | | 2026-03-12 | OMX 任务路由样例落地 | 1）新增 `docs/design/00_Management/17_OMX_Task_Routing_Examples.md`，给出 `REV-004`、`REV-003` 与正式文档修订三类任务的 leader / explorer / executor / verifier 分工模板；2）补充各 lane 的提示词模板、推荐执行顺序与不建议的并行方式；3）更新 `00_Management/README.md` 收录该文档入口。 | 用户希望在治理层之外，再拿到针对当前项目可以直接复用的多 Agent 分工模板，而不是只看抽象原则。 | 正面影响，OMX 从“有规则”变成“可直接照着分工执行”；后续在 `REV-004`、`REV-003` 等闭环中可直接套用 lane 拆分，减少 leader 临时编排成本。 | | 2026-03-12 | OMX 多 Agent 治理层落地 | 1）在根 `AGENTS.md` 中新增 OMX 多 Agent 协作补充，明确分层 AGENTS、任务路由矩阵、写冲突规则、范围控制基线与 worktree/tmux 约定；2）新增 `backend/AGENTS.md`，固化 backend 开发边界、最小实现策略与 BPM 接入规则；3）新增 `docs/design/04_Appendix/Archive/AGENTS.md`，明确 Archive 默认只读与来源回写规则；4）新增 `docs/design/00_Management/16_OMX_Multi_Agent_Guide.md`，统一 leader / writer / executor / verifier 分工与协作拓扑；5）更新 `00_Management/README.md` 收录新指南入口。 | 用户明确准备采用 `oh-my-codex` 进行多 Agent 开发，需要对现有 AGENTS 体系做分层化和路由化改造，避免现有规则在 Team Mode 下失效。 | 正面影响，当前项目从“单 agent 规则完备”提升为“多 agent 可控协作”；后续接入 OMX 时，目录级职责、写权限边界、范围基线与会话约定已经成型，可显著降低并发改稿和多 worker 写冲突风险。 | -| 2026-03-12 | REV-004 一期执行手册与 worktree/tmux 启动脚本落地 | 1）新增 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将 `REV-004` 一期的范围、现状差距、最小改动方案、任务拆解、Codex Prompt 与验收清单固化为可执行手册；2）新增 `scripts/start-backend-codex-session.sh`，支持在 `backend/` 上创建或复用 worktree，并拉起 `tmux + codex` 三窗口开发会话；3）更新 `scripts/README.md` 记录脚本用途。 | 用户要求不仅给建议，还要把“如何规划执行、如何进入 worktree、如何在 tmux 场景下协作”落成可直接使用的资产。 | 正面影响，开发启动动作从“口头建议”变为“可复制执行”；后续围绕 `REV-004/REV-003/REV-008` 的闭环开发可直接复用该脚本和手册，降低 worktree、tmux、Codex 协作的起步成本与操作偏差。 | -| 2026-03-13 | REV-004 一期范围正式文档收敛（US1） | 1）更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，将 REV-004 一期范围收敛为水量调整、金额调整、退款、冲正、坏账申请五类场景，并明确共性能力优先顺序、排除项与审批边界；2）重写 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将其从 backend 执行导向收敛为正式文档修订执行手册；3）同步 `docs/design/01_Overview/03_Summary_Design.md` 与 `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md` 的范围摘要与追溯说明；4）执行目标文档 `make validate-file` 与 `make check-links` 校验并通过。 | 用户要求在 implement 阶段先完成 REV-004 一期正式文档范围收敛，不把 backend 代码实现写成本轮已完成内容。 | 正面影响，REV-004 一期边界、验收入口与追溯关系已在正式文档体系内闭环，后续 US2/US3 可直接在稳定范围上继续对齐接口、数据库与台账，不再受早期执行手册偏代码导向表述干扰。 | +| 2026-03-12 | REV-004 一期执行手册与 worktree/tmux 启动脚本落地 | 1）新增 `docs/evidence/rev004-accounting/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将 `REV-004` 一期的范围、现状差距、最小改动方案、任务拆解、Codex Prompt 与验收清单固化为可执行手册；2）新增 `scripts/start-backend-codex-session.sh`，支持在 `backend/` 上创建或复用 worktree，并拉起 `tmux + codex` 三窗口开发会话；3）更新 `scripts/README.md` 记录脚本用途。 | 用户要求不仅给建议，还要把“如何规划执行、如何进入 worktree、如何在 tmux 场景下协作”落成可直接使用的资产。 | 正面影响，开发启动动作从“口头建议”变为“可复制执行”；后续围绕 `REV-004/REV-003/REV-008` 的闭环开发可直接复用该脚本和手册，降低 worktree、tmux、Codex 协作的起步成本与操作偏差。 | +| 2026-03-13 | REV-004 一期范围正式文档收敛（US1） | 1）更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，将 REV-004 一期范围收敛为水量调整、金额调整、退款、冲正、坏账申请五类场景，并明确共性能力优先顺序、排除项与审批边界；2）重写 `docs/evidence/rev004-accounting/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将其从 backend 执行导向收敛为正式文档修订执行手册；3）同步 `docs/design/01_Overview/03_Summary_Design.md` 与 `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md` 的范围摘要与追溯说明；4）执行目标文档 `make validate-file` 与 `make check-links` 校验并通过。 | 用户要求在 implement 阶段先完成 REV-004 一期正式文档范围收敛，不把 backend 代码实现写成本轮已完成内容。 | 正面影响，REV-004 一期边界、验收入口与追溯关系已在正式文档体系内闭环，后续 US2/US3 可直接在稳定范围上继续对齐接口、数据库与台账，不再受早期执行手册偏代码导向表述干扰。 | | 2026-03-18 | 完成全仓旧模块编号残留审计 | 1）新增 `docs/design/00_Management/18_Old_Module_Number_Audit.md`，对 `docs/design`、`docs/guides`、`specs` 中的 `METER-004`、`INST-004`、`INST-005` 及相关旧模块语义进行全仓审计；2）将命中项分为“必须修”“可保留历史描述”“Archive 原始资料”“合法保留的接口编号/子能力表达”四类；3）更新 `docs/design/00_Management/README.md` 收录审计清单入口。 | 用户要求执行全仓旧编号残留审计，明确哪些需要继续修、哪些应作为历史资料保留。 | 正面影响，后续旧编号治理从“按检索临时判断”转为“按清单分类处理”；正式文档、管理台账与 Archive 的处理边界更加清晰。 | | 2026-03-18 | 旧模块编号残留收口与追溯链接修正 | 1）更新 `docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md`，将文档定位从旧 `INST-004` 修正为 `INST-002 工程管理` 下的“合同签署与电子签章能力”专项补充；2）修正 `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` 中 `INST-002`、`INST-003` 的章节锚点，确保跳转与当前三段式模块结构一致；3）复核 `docs/design/01_Overview/03_Summary_Design.md` 的主口径章节，确认残留 `IF-METER-004`、`IF-INST-004/005` 均为接口编号而非旧模块编号。 | 用户要求继续收口“旧编号视为错误”的相关正式文档，并区分必须修项与可保留历史描述。 | 正面影响，正式文档层的模块编号、追溯入口与专项补充挂接关系进一步统一，评审和检索时不会再因旧 `INST-004/005` 模块语义误跳转。 | | 2026-03-18 | 基于整体架构图补齐模块清单并对齐详细设计承接关系 | 1）新增 `docs/design/01_Overview/05_Module_Inventory.md`，将整体架构图中的分层、子系统、模块与当前详设承接关系整理为统一清单；2）更新 `docs/design/01_Overview/README.md` 与 `docs/design/02_Detailed_Design/README.md`，明确该清单作为模块枚举与承接核对入口；3）更新 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 与 `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md`，补充架构图模块清单与当前详设之间的映射说明，明确 `WECHAT-*`、`MOBILE-*`、`WORK-*` 等模块当前按业务域正文或协同能力承接。 | 用户要求根据 `output/preview/福建水务营收系统整体架构图.html` 形成模块清单，并以此为基线对齐 `02_Detailed_Design` 目录。 | 正面影响，架构图中的模块枚举与详细设计现状之间建立了稳定映射，后续评审时可直接判断“哪些模块已有正文、哪些是协同承接、哪些仍停留在架构层列示”，减少按图追文时的歧义。 | @@ -340,7 +340,7 @@ ### 2026-03-18 更新 -- 完成 `REV-006` Speckit feature `006-reminder-event-design` 的 implement 阶段文档收口，统一 `12_REV_Detailed.md`、`03_Interface_Design.md` 与治理台账口径。 +- 完成 `REV-006` Speckit feature `003-rev006-reminder-event-design` 的 implement 阶段文档收口，统一 `12_REV_Detailed.md`、`03_Interface_Design.md` 与治理台账口径。 - `REV-006` 正式业务接口编号确定为 `IF-REV-013`，不再复用 `IF-REV-009`；催缴结果状态统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态。 - 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接，不新增同名在线主表；停复水在本轮仅保留联动边界、处置引用和追溯关系。 - 启动并完成 `REV-007` Speckit feature `004-rev007-revenue-statistics-design` 的 `specify -> plan -> tasks` 工件链，形成统计主题、维度、指标、`IF-REV-010` 与数据库承接口径的正式设计基线。 @@ -353,7 +353,7 @@ ### 2026-03-19 更新 -- 完成 `REV-006` 当前轮次治理文档二次对齐：在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”判断，并补记 `specs/006-reminder-event-design/` 工件基线与后续研发切入建议。 +- 完成 `REV-006` 当前轮次治理文档二次对齐：在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”判断，并补记 `specs/003-rev006-reminder-event-design/` 工件基线与后续研发切入建议。 - 同步回写 `03_Task_Checklist.md` 与本进度文档，补充本轮 implement 阶段的治理动作、验证动作与台账一致性说明，避免将文档收口误写为 backend 已实现。 ### 2026-03-24 更新 diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 00ef94b..51870ff 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -196,7 +196,7 @@ ### 📋 REV-004 执行资产落地 - [x] **完成 REV-004 一期执行手册与启动脚本落地** ✅ (2026-03-12) - - [x] 新增 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，固化范围、最小改动方案、任务拆解与验收清单 ✅ + - [x] 新增 `docs/evidence/rev004-accounting/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，固化范围、最小改动方案、任务拆解与验收清单 ✅ - [x] 新增 `scripts/start-backend-codex-session.sh`，支持 backend worktree + tmux + Codex 启动 ✅ - [x] 在 `scripts/README.md` 登记启动脚本用途 ✅ - [x] 在 `01_Project_Progress.md` 记录本次执行资产落地 ✅ @@ -571,7 +571,7 @@ - [x] 更新 `docs/design/03_Technical_Design/01_Database_Design.md`，明确历史只读保留策略、最小查询字段与处置引用边界 ✅ - [x] 更新 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md` 与本任务清单，完成 implement 阶段治理回写 ✅ - [x] **完成 REV-006 implement 阶段治理文档二次对齐** ✅ (2026-03-19) - - [x] 在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”，并补记 `specs/006-reminder-event-design/` 工件基线 ✅ + - [x] 在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”，并补记 `specs/003-rev006-reminder-event-design/` 工件基线 ✅ - [x] 在 `01_Project_Progress.md` 更正 REV-006 feature 编号与本轮治理回写记录，避免误导为 backend 已实现 ✅ - [x] 在治理任务建议中补充 `make validate-file`、`make check-links`、`make validate-mermaid` 与台账同步动作 ✅ diff --git a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md index 08cc9ba..da56e56 100644 --- a/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md +++ b/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md @@ -130,7 +130,7 @@ | `REV-003` 营业收费 | 部分实现 | 建议围绕“柜台班结”“红冲历史查询”等缺口拆小 feature | | `REV-004` 账务处理 | 已实现 | 以规则收口、二期扩展或历史台账映射为主 | | `REV-005` 发票与税务处理 | 已实现 | 以验收归档和细粒度对象补证为主 | -| `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks` 工件并形成 `specs/006-reminder-event-design/` 基线；当前进入 `implement` 阶段文档收口与台账同步，backend 仍未见明确催缴/通知业务实现骨架。 | +| `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks` 工件并形成 `specs/003-rev006-reminder-event-design/` 基线；当前进入 `implement` 阶段文档收口与台账同步，backend 仍未见明确催缴/通知业务实现骨架。 | | `REV-007` 统计分析 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks`，当前进入 `implement` 阶段的正式文档收口与治理同步。 | | `REV-008` 代收与银行业务 | 已实现 | 以跨系统口径收口和扩展台账补证为主 | | `REV-009` 业务参数配置 | 已实现 | 以参数边界收口和治理能力补充为主 | @@ -152,7 +152,7 @@ | `REV-003` | 是 | `rev003-redflush-history-query` | 中 | 聚焦红冲历史查询与台账承接 | | `REV-004` | 否 | `rev004-adjustment-followup` | 中 | 仅在补二期或精细对象时使用 | | `REV-005` | 否 | `rev005-detail-reconciliation` | 中 | 仅在补发票细表/批次缺口时使用 | -| `REV-006` | 是 | `rev006-reminder-event-design` | 最高 | 已完成 `spec/plan/research/data-model/contracts/quickstart/tasks` 工件链，当前重点为按 `IF-REV-013` 四态口径推进正式文档 implement 收口并形成后续研发切入点。 | +| `REV-006` | 是 | `rev003-rev006-reminder-event-design` | 最高 | 已完成 `spec/plan/research/data-model/contracts/quickstart/tasks` 工件链，当前重点为按 `IF-REV-013` 四态口径推进正式文档 implement 收口并形成后续研发切入点。 | | `REV-006` | 是 | `rev006-notice-result-writeback` | 高 | 可作为 `REV-006` 拆分子 feature | | `REV-007` | 是 | `rev007-revenue-statistics-design` | 高 | 已启动并完成第一轮设计工件，当前建议继续收口正式文档并形成后续研发切入点 | | `REV-007` | 是 | `rev007-channel-analysis-query` | 中 | 适合作为统计分析子 feature | @@ -233,13 +233,13 @@ - 标题：`SYS-002：补齐催缴事件与通知协同设计` - 对应需求：`SYS002-REQ-011` -- feature：`rev006-reminder-event-design`（治理映射名：`sys002-reminder-event-design`） +- feature：`rev003-rev006-reminder-event-design`（治理映射名：`sys002-reminder-event-design`） - 优先级：`高` - 当前实现状态：`未见实现` - Story 描述： - 目标：补齐欠费催缴对象生成、通知触发、通知结果回写与催缴追踪闭环。 - 事实来源：`12_REV_Detailed.md` 中 REV-006、`03_Interface_Design.md` 中 `IF-EXT-008`。 - - 当前判断：当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架；但本轮已完成 `specs/006-reminder-event-design/` 工件链，并在正式文档中统一 `IF-REV-013`、四态状态集、历史只读查询口径和停复水联动边界。 + - 当前判断：当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架；但本轮已完成 `specs/003-rev006-reminder-event-design/` 工件链，并在正式文档中统一 `IF-REV-013`、四态状态集、历史只读查询口径和停复水联动边界。 - 验收要点：明确催缴触发时机、催缴对象筛选条件、通知方式、回写字段、四态状态语义与失败重试机制。 - 推荐 Task： - `T-011-01` 对齐催缴业务场景、触发条件与对象筛选规则 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index e0d52f6..683f4ad 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -1144,17 +1144,18 @@ retrieval_priority: P0 | `biz_collection` | `code`, `cust_id`, `charge_id`, `collection_status` | 托收主表 | | `biz_withholding` | `code`, `cust_id`, `charge_id`, `withholding_status` | 代扣主表 | -### biz_invoice / biz_invoice_taxrate (发票主表与税率表) +### biz_invoice / biz_invoice_record / biz_invoice_taxrate（开票配置表 / 发票记录表 / 税率表） | 表名 | 关键字段 | 说明 | | :--- | :--- | :--- | -| `biz_invoice` | `code`, `cust_id`, `charge_id`, `invoice_status`, `invoice_amount` | 发票主表，统一承接申请单号、账单关联、受理号、开票结果与电子票地址等核心状态 | +| `biz_invoice` | `supplier`, `limit`, `auto_invoice`, `invoice_type`, `status` | 开票配置表（供应商、限额、自动开票开关）| +| `biz_invoice_record` | `application_no`, `cust_id`, `invoice_status`, `invoice_amount` | 发票申请/记录主表，统一承接申请单号、账单关联、受理号、开票结果与电子票地址等核心状态 | | `biz_invoice_taxrate` | `tax_code`, `tax_name`, `tax_rate`, `status` | 税率基础配置 | #### REV-005 发票承接口径 | 对象 | 已有字段 | 待补字段 | 仅快照/历史只读字段 | | :--- | :--- | :--- | :--- | -| `biz_invoice` 发票申请/结果主对象 | `code`、`cust_id`、`charge_id`、`invoice_status`、`invoice_amount` | `application_no`、`sys_request_no`、`invoice_type`、`invoice_title`、`tax_no`、`email`、`mobile`、`source_channel`、`fail_reason`、`invoice_code`、`invoice_number`、`file_url`、`last_try_time`、`next_try_time`、`try_count`、`push_status`、`charge_ids_snapshot`、`charge_bind_status`、作废原因/备注、红冲原因/备注、原票/红票关联标识、作废/红冲申请来源、补偿查询/结果回写上下文 | 旧开票批次号、旧配置版本号、旧平台扩展回执 | +| `biz_invoice_record` 发票申请/结果主对象 | `code`、`cust_id`、`charge_id`、`invoice_status`、`invoice_amount` | `application_no`、`sys_request_no`、`invoice_type`、`invoice_title`、`tax_no`、`email`、`mobile`、`source_channel`、`fail_reason`、`invoice_code`、`invoice_number`、`file_url`、`last_try_time`、`next_try_time`、`try_count`、`push_status`、`charge_ids_snapshot`、`charge_bind_status`、作废原因/备注、红冲原因/备注、原票/红票关联标识、作废/红冲申请来源、补偿查询/结果回写上下文 | 旧开票批次号、旧配置版本号、旧平台扩展回执 | | `biz_cust_invoice` 客户开票信息 | `cust_id`、`invoice_title`、`tax_no`、`email`、`mobile` | 企业/个人抬头类型、默认推送方式等扩展属性按后续实现补齐 | 旧抬头版本、历史修改快照 | | `biz_invoice_taxrate` 税率配置 | `tax_code`、`tax_name`、`tax_rate`、`status` | 税率生效区间、适用票种范围等扩展控制字段 | 旧税率版本快照 | | 账单-发票关系快照 | 当前主模型通过 `biz_invoice` 与 `biz_charge*` 关联承接 | `charge_ids_snapshot`、账单集合来源、客户侧身份匹配结果、操作留痕标识 | 旧营业账开票关系表、旧发票明细表 | @@ -1180,7 +1181,7 @@ retrieval_priority: P0 | 开账记录、特殊开账 | `biz_charge`、`biz_charge_detail`、`biz_operat_log*` | 统一纳入营业账主表与明细表，特殊开账按来源类型、业务类型、依据说明留痕，不单设平行“特殊开账表” | 在线保留 | | 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账新发生业务 | `biz_charge*` + 留痕骨架 + 目标对象语义 | 新发生业务优先走统一骨架承接，数据库文档保留目标对象命名和待补字段组，但不误写为已全部落地物理表 | 在线保留 | | 柜台收费、实时收费、代收代扣 | `biz_collection`、`biz_withholding`、`bk_transaction*`、`bk_withholding_*` | 统一纳入收费主模型与渠道交易模型，柜台班结/实时收费日志按交易结果和操作留痕归并 | 在线保留 | -| 发票申请、开票结果、票据税率 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` | 统一纳入发票主表、税率表和客户开票信息，不为旧“营业账开票表”机械复制新在线表 | 在线保留 | +| 发票申请、开票结果、票据税率 | `biz_invoice_record`（业务记录）、`biz_invoice`（开票配置）、`biz_invoice_taxrate`、`biz_cust_invoice` | 统一纳入发票主表、税率表和客户开票信息，不为旧“营业账开票表”机械复制新在线表 | 在线保留 | | 微网厅业务字段、页面配置、微信参数 | `biz_business_types`、`biz_business_datas`、`biz_page_settings*`、`biz_parameter_settings`、`sys_wechat_app_settings` | 统一归并为业务类型、页面配置和渠道参数模型 | 在线保留 | | 办理附件、电子档案 | `biz_content`、`biz_content_attach` | 当前新增与迁移后新增资料统一按资料主表与附件表承接 | 在线保留 | diff --git a/docs/research/migration/01_Document_Structure_Migration_Plan.md b/docs/design/04_Appendix/Archive/06_Migration_Plans/01_Document_Structure_Migration_Plan.md similarity index 100% rename from docs/research/migration/01_Document_Structure_Migration_Plan.md rename to docs/design/04_Appendix/Archive/06_Migration_Plans/01_Document_Structure_Migration_Plan.md diff --git a/docs/evidence/counter-settle-unsettled-filter-bugfix-2026-06-09.md b/docs/evidence/bugfix/counter-settle-unsettled-filter-bugfix-2026-06-09.md similarity index 100% rename from docs/evidence/counter-settle-unsettled-filter-bugfix-2026-06-09.md rename to docs/evidence/bugfix/counter-settle-unsettled-filter-bugfix-2026-06-09.md diff --git a/docs/evidence/bugfix/frontend/frontend-expect-cli-test-framework-2026-06-08.md b/docs/evidence/bugfix/frontend/frontend-expect-cli-test-framework-2026-06-08.md new file mode 100644 index 0000000..d4569e6 --- /dev/null +++ b/docs/evidence/bugfix/frontend/frontend-expect-cli-test-framework-2026-06-08.md @@ -0,0 +1,354 @@ +# 前端 Expect CLI 测试框架接入记录 + +日期：2026-06-08 + +## 范围 + +本记录对应 `water-frontend` 仓库新增 `expect-cli` 浏览器测试框架入口，用于在现有 Playwright 与 `node:test` 测试之外，提供 agent 驱动的浏览器测试能力。 + +## 前端基线 + +- 仓库：`water-frontend` +- 工作目录：`/Volumes/Dpan/github/water-workspace/water-frontend` +- 分支：`develop` +- 基础提交：`35fb598c9059b0ea933de533892a0473512ad662` +- 状态：测试框架接入已在工作区实现，尚未提交 + +## 实现内容 + +- 新增开发依赖：`expect-cli@^0.1.3` +- 新增脚本： + - `pnpm test:expect` + - `pnpm test:expect:smoke` + - `pnpm test:expect:watch` + - `pnpm test:expect:acceptance` +- 新增 runner：`tools/expect/run-expect.mjs` + - 默认目标地址为 `http://localhost:18080` + - 支持 `EXPECT_BASE_URL` 覆盖目标地址 + - 本地服务不可达时自动启动 `pnpm dev` + - 复用已有本地服务时不接管其生命周期 + - 支持 `--no-dev-server` 禁止自动启动 +- 新增验收场景库：`tests/expect/revenue-bugfix-clear-scope/scenarios.json` + - 覆盖 `#78`、`#39`、`#50`、`#53`、`#58/#59`、`#69/#76` 和基础回归。 + - 场景来源为 `docs/superpowers/plans/2026-06-08-revenue-bugfix-clear-scope-acceptance-test.md`。 + - 使用环境占位符表达测试账号、客户和业务数据，不在前端仓硬编码 live 数据。 +- 新增验收场景加载模块：`tools/expect/acceptance-scenarios.mjs` + - 验收指令默认使用严格黑盒规约：正式验收计划为 oracle，不以源码、路由、store、API 封装或既有自动化测试作为通过依据。 + - 通过标准固定为 `PASS / FAIL / BLOCKED`，缺数据、缺权限或业务状态不足时必须标记 `BLOCKED`。 +- 新增验收数据预检： + - `acceptance` 运行前检查场景所需环境变量。 + - 缺少测试账号、客户或业务记录时直接输出 `BLOCKED` 并以退出码 `2` 结束，不启动浏览器，不使用占位符继续测试。 +- 新增 runner/场景单元测试： + - `tests/expect/revenueBugfixAcceptanceScenarios.test.mjs` + - `tests/expect/runExpectRunnerArgs.test.mjs` +- 新增使用说明：`tests/expect/README.md` + +## 验证命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --check tools/expect/run-expect.mjs +node --check tools/expect/acceptance-scenarios.mjs +node tools/expect/run-expect.mjs --help +pnpm exec expect tui --help +node -e "const pkg=require('./package.json'); console.log(pkg.scripts['test:expect']); console.log(pkg.scripts['test:expect:smoke']); console.log(pkg.scripts['test:expect:watch']); console.log(pkg.devDependencies['expect-cli'])" +node --test tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/runExpectRunnerArgs.test.mjs +pnpm test:expect:acceptance -- --list +pnpm test:expect:acceptance -- rev-bugfix-39-counter-prepay-settlement +``` + +## 验证结果 + +- runner 语法检查：通过。 +- 验收场景加载模块语法检查：通过。 +- runner 帮助输出：通过，显示 `test:expect`、`test:expect:smoke`、`test:expect:watch` 用法及 `EXPECT_BASE_URL` 等环境变量。 +- `expect-cli` 本地可执行性：通过，`pnpm exec expect tui --help` 成功输出 CLI 参数说明。 +- `package.json` 脚本解析：通过，`test:expect`、`test:expect:smoke`、`test:expect:watch`、`test:expect:acceptance` 均指向 `tools/expect/run-expect.mjs`，开发依赖版本为 `^0.1.3`。 +- 验收场景单元测试：通过，8 项通过、0 项失败。 +- 验收场景列表命令：通过，列出 7 个场景及各自 requiredData。 +- 严格数据预检：通过。执行 `pnpm test:expect:acceptance -- rev-bugfix-39-counter-prepay-settlement` 时，由于未提供 `EXPECT_TEST_CASHIER_A_USERNAME` 和 `EXPECT_TEST_CUSTOMER_C4`，命令输出 `BLOCKED` 并以退出码 `2` 结束，未启动浏览器。 +- `typecheck/vue-tsc`：按用户要求未继续执行，后续本项不作为该接入任务的默认验证。 +- 浏览器实际 smoke：未执行。本次完成框架接入、验收场景库和 CLI 可用性验证；真实业务验收需要测试环境提供 C1-C5、收费员 A/B、审批账号、水价模板、未结账/已结账记录等数据后运行。 + +## 使用入口 + +```bash +pnpm test:expect +pnpm test:expect:smoke +pnpm test:expect:watch -- -m "test the flow you changed" +pnpm test:expect:acceptance -- --list +pnpm test:expect:acceptance -- rev-bugfix-53-prepaid-deduction +pnpm test:expect:acceptance -- all +EXPECT_BASE_URL=http://localhost:18081 pnpm test:expect +``` + +## 重新测试记录：2026-06-08 严格验收重跑 + +### 触发背景 + +前端工作区新增了红冲记录页面的时间范围默认时间处理： + +- `src/views/operatingCharges/redReversalRecord/index.vue` +- `tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs` + +### 执行命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +pnpm test:expect:acceptance -- all +pnpm test:expect:acceptance -- rev-bugfix-58-59-red-reversal-record +node --test tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs +node --test tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/runExpectRunnerArgs.test.mjs +``` + +### 结果 + +- 严格全量验收：`BLOCKED`。当前 shell 未提供 `EXPECT_TEST_*` 测试账号、客户和业务记录数据，runner 未启动浏览器，未使用占位符继续测试。 +- `#58/#59` 红冲记录严格验收：`BLOCKED`。缺少： + - `EXPECT_TEST_CASHIER_A_USERNAME` + - `EXPECT_TEST_SETTLED_COUNTER_RECORD` +- 代码契约验证：通过，`tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs` 共 5 项通过、0 项失败。 +- Expect 场景/runner 单元测试：通过，8 项通过、0 项失败。 +- `typecheck/vue-tsc`：未执行。 + +### 结论 + +本次只确认了红冲记录代码契约和 Expect 严格验收框架本身仍可用。正式黑盒业务验收未通过也未失败，状态为 `BLOCKED`，需要提供测试账号、客户和已结账可红冲记录后重新执行。 + +## 收费与账务闭环场景库接入：2026-06-08 + +### 范围 + +基于 `/Volumes/Dpan/github/water-workspace/docs` 中收费、结账、预存抵扣业务资料，以及 `../water-docs/specs/001-rev004-accounting/` 中账务处理一期口径，新增前端 `expect-cli` 可执行场景 suite： + +- `tests/expect/revenue-accounting-closures/scenarios.json` +- `tests/expect/revenue-accounting-closures/README.md` + +### 场景 + +初版纳入 12 条场景： + +- P0 小闭环： + - `revenue-charge-normal-payment` + - `revenue-charge-no-arrears-topup` + - `revenue-charge-prepay-zero-confirm` + - `revenue-charge-prepay-partial-deduction` + - `revenue-charge-prepay-full-deduction` +- P0 跨页面大闭环： + - `closure-charge-to-settlement` + - `closure-prepay-charge-to-settlement` + - `closure-settlement-to-red-reversal-record` +- P1 账务处理小闭环： + - `accounting-unsold-split-submit` + - `accounting-unsold-bad-debt-submit` + - `accounting-unsold-price-diff-submit` + - `accounting-unsold-penalty-remission-submit` + +### 工具调整 + +- `tools/expect/acceptance-scenarios.mjs` 支持多 suite 加载。 +- 场景引用支持： + - `revenue-accounting-closures:all` + - `revenue-accounting-closures:` + - 全局唯一场景可直接使用 `` +- `requiredData` 扩展到账务和收费闭环数据键，例如 `customerArrears`、`customerNoArrears`、`unsoldBillCustomer` 等。 + +### 验证命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --test tests/expect/revenueAccountingClosureScenarios.test.mjs tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/runExpectRunnerArgs.test.mjs +node --check tools/expect/acceptance-scenarios.mjs +node --check tools/expect/run-expect.mjs +pnpm test:expect:acceptance -- --list +pnpm test:expect:acceptance -- revenue-accounting-closures:closure-charge-to-settlement +``` + +### 结果 + +- 多 suite 场景加载、schema、requiredData 映射、prompt 生成测试：通过，15 项通过、0 项失败。 +- runner 语法检查：通过。 +- 场景列表命令：通过，可列出 bugfix suite 和 `revenue-accounting-closures` suite。 +- 严格业务执行：`pnpm test:expect:acceptance -- revenue-accounting-closures:closure-charge-to-settlement` 返回 `BLOCKED`，缺少 `EXPECT_TEST_CASHIER_A_USERNAME` 与 `EXPECT_TEST_CUSTOMER_ARREARS`，未启动浏览器，不作为失败或通过。 +- `typecheck/vue-tsc`：未执行。 + +## 验证记录：2026-06-08 收费与账务闭环 suite + +### 执行命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --check tools/expect/acceptance-scenarios.mjs +node --check tools/expect/run-expect.mjs +node --test tests/expect/revenueAccountingClosureScenarios.test.mjs tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/runExpectRunnerArgs.test.mjs +node --test tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs +pnpm test:expect:acceptance -- --list +pnpm test:expect:acceptance -- revenue-accounting-closures:all +pnpm test:expect:acceptance -- revenue-accounting-closures:closure-charge-to-settlement +``` + +### 结果 + +- runner 语法检查：通过。 +- Expect 场景/runner 单元测试：通过，15 项通过、0 项失败。 +- 营收缺陷代码契约测试：通过，5 项通过、0 项失败。 +- 场景列表：通过，列出 `revenue-bugfix-clear-scope` 与 `revenue-accounting-closures` 两个 suite。 +- `revenue-accounting-closures:all`：`BLOCKED`。缺少收费员、欠费客户、无欠费客户、预存余额客户、已结账红冲记录、管理员和未销账单客户等测试数据。 +- `revenue-accounting-closures:closure-charge-to-settlement`：`BLOCKED`。缺少： + - `EXPECT_TEST_CASHIER_A_USERNAME` + - `EXPECT_TEST_CUSTOMER_ARREARS` +- 浏览器黑盒业务执行：未启动。阻塞发生在 requiredData 预检阶段，符合严格验收规则。 +- `typecheck/vue-tsc`：未执行。 + +## 验证记录：2026-06-08 Expect runner 与页面 smoke 重跑 + +### 触发背景 + +前端工作区继续调整了 Expect runner 可执行性，并对红冲记录页的红冲时间范围默认时间进行了补充： + +- `tools/expect/run-expect.mjs` +- `tests/expect/runExpectRunnerArgs.test.mjs` +- `src/views/operatingCharges/redReversalRecord/index.vue` +- `tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs` + +### 工具调整 + +- `tools/expect/run-expect.mjs` 改为优先调用本地 `node_modules/.bin/expect`，避免 `pnpm exec expect` 在当前工作区触发隐式 `pnpm install`。 +- runner 增加 `EXPECT_BIN` 覆盖入口，便于特殊环境指定 Expect 可执行文件。 +- runner 过滤 npm/pnpm 转发参数中的独立 `--` 分隔符，修复 `pnpm test:expect:acceptance -- ` 被 Expect 识别为多余位置参数的问题。 + +### 执行命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --test tests/expect/runExpectRunnerArgs.test.mjs +node --test tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/revenueAccountingClosureScenarios.test.mjs +node --test tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs +corepack pnpm@9.15.9 test:expect:acceptance -- --list +source /tmp/revenue-acceptance-env.sh +corepack pnpm@9.15.9 test:expect:acceptance -- rev-bugfix-50-cashier-filter --target unstaged --timeout 120000 --verbose +./node_modules/.bin/eslint tools/expect/run-expect.mjs tests/expect/runExpectRunnerArgs.test.mjs tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs src/views/operatingCharges/redReversalRecord/index.vue +corepack pnpm@9.15.9 ts:check +NODE_OPTIONS=--max-old-space-size=16384 corepack pnpm@9.15.9 ts:check +corepack pnpm@9.15.9 build:dev +``` + +### 结果 + +- runner 单元测试：通过，5 项通过、0 项失败。 +- Expect 场景加载测试：通过，12 项通过、0 项失败。 +- 营收缺陷代码契约测试：通过，5 项通过、0 项失败。 +- 场景列表命令：通过。需使用 `corepack pnpm@9.15.9`；当前 shell 的全局 `pnpm@11.5.1` 会在脚本执行前尝试清理并重装 `node_modules`，无 TTY 时退出。 +- `rev-bugfix-50-cashier-filter` 严格黑盒验收：`BLOCKED`。requiredData 环境变量已提供，但 Expect 启动 Codex ACP 后返回 `401 Unauthorized`，提示当前 Codex agent 未认证或 API key 无效；未进入浏览器业务步骤，不可判定 `PASS` 或 `FAIL`。 +- 页面 smoke（Playwright fallback）：通过登录默认租户 `福建水投集团`、用户 `admin` 后访问真实菜单路由： + - `/operatingCharges/counterCheckout`：页面标题为 `营业收费管理系统 - 柜台结账`，未出现 404，无 failed network request；截图在 `water-frontend/test-results/counter-checkout-smoke.png`。 + - `/operatingCharges/redReversalRecord`：页面标题为 `营业收费管理系统 - 红冲记录`，查询区显示 `红冲时间`，表格显示柜台红冲记录字段，无 failed network request；截图在 `water-frontend/test-results/red-reversal-record-smoke.png`。 +- 页面 smoke 备注：运行时存在既有 Vue/router warning，包括未解析菜单组件 `system/userformconfig/index`、`pay/demo/transfer/index`，以及 `inject() can only be used inside setup()` 等；未在本次范围内修复。 +- focused ESLint：通过。 +- `ts:check`：失败。默认堆内存运行先 OOM；增大到 16G 后完成但暴露 repo-wide 既有 TypeScript 错误，涉及 mall statistics、BPM designer、pay views、system views、settings 等大量非本次修改文件。本结果不作为本次改动通过项。 +- `build:dev`：通过，输出 `Build successful. Please see dist directory`。构建期间仍有既有 Vite CJS deprecation warning、SVG symbolId warning、Rollup PURE annotation warning。 + +### 结论 + +Expect runner 的本地执行入口和 pnpm 参数转发问题已修复并由单元测试覆盖。`rev-bugfix-50-cashier-filter` 严格黑盒验收当前阻塞于 Codex ACP 认证，状态为 `BLOCKED`；页面级 fallback smoke 只证明页面可登录访问和基础渲染，不替代正式黑盒业务验收。 + +## 修复记录：2026-06-08 Expect runner 完整收敛 + +### 触发背景 + +上一轮验证后仍有三个仓库内可控问题： + +- 当前 shell 的全局 `pnpm@11.5.1` 与 `node_modules/.modules.yaml` 中的 `pnpm@9.15.9` 布局不一致，未 pin 时会触发脚本前置安装/清理风险。 +- runner 自动启动 dev server 时仍通过 `pnpm dev`，在 pnpm 版本不一致时可能复现同类问题。 +- `tests/expect` 场景中存在 `/operating-charges/...` 旧路由元数据，而当前真实菜单路由为 `/operatingCharges/...`。 +- Expect 调用 Codex ACP 认证失败时输出原始栈，不够符合严格验收的 `BLOCKED` 语义。 + +### 实现内容 + +- `package.json` 新增 `packageManager: pnpm@9.15.9`。 +- `tools/expect/run-expect.mjs`： + - dev server 启动改为直接调用本地 `node_modules/vite/bin/vite.js --mode dev`。 + - 保留 `EXPECT_DEV_SERVER_BIN` 用于特殊环境覆盖。 + - 捕获 Expect 输出并识别 Codex ACP `401 Unauthorized` / `AcpProviderUnauthenticatedError`，转为清晰 `BLOCKED` 输出和退出码 `2`。 +- `tests/expect/revenue-bugfix-clear-scope/scenarios.json`： + - 为 bugfix 场景补充真实页面路由元数据。 +- `tests/expect/revenue-accounting-closures/scenarios.json`： + - 将收费、结账、红冲场景的旧路由更新为 `/operatingCharges/counterCharging`、`/operatingCharges/counterCheckout`、`/operatingCharges/redReversalRecord`。 +- `tests/expect/runExpectRunnerArgs.test.mjs`、`tests/expect/revenueBugfixAcceptanceScenarios.test.mjs`、`tests/expect/revenueAccountingClosureScenarios.test.mjs` 补充回归测试覆盖上述行为。 + +### 执行命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --test tests/expect/runExpectRunnerArgs.test.mjs +node --test tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/revenueAccountingClosureScenarios.test.mjs +node --test tests/expect/runExpectRunnerArgs.test.mjs tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/revenueAccountingClosureScenarios.test.mjs +node --test tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs +./node_modules/.bin/eslint tools/expect/run-expect.mjs tools/expect/acceptance-scenarios.mjs tests/expect/runExpectRunnerArgs.test.mjs tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/revenueAccountingClosureScenarios.test.mjs tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs src/views/operatingCharges/redReversalRecord/index.vue +pnpm test:expect:acceptance -- --list +pnpm test:expect:acceptance -- revenue-accounting-closures:closure-charge-to-settlement +source /tmp/revenue-acceptance-env.sh +pnpm test:expect:acceptance -- rev-bugfix-50-cashier-filter --target unstaged --timeout 120000 --verbose +pnpm build:dev +``` + +### 结果 + +- runner 单测：通过，9 项通过、0 项失败。 +- Expect 场景测试：通过，14 项通过、0 项失败。 +- 合并执行 Expect runner/场景测试：通过，23 项通过、0 项失败。 +- 营收缺陷契约测试：通过，5 项通过、0 项失败。 +- focused ESLint：通过。 +- `pnpm test:expect:acceptance -- --list`：通过，可在 plain `pnpm` 下列出两个 suite 的场景。 +- `pnpm test:expect:acceptance -- revenue-accounting-closures:closure-charge-to-settlement`：按 requiredData 预检返回 `BLOCKED`，缺少 `EXPECT_TEST_CASHIER_A_USERNAME` 与 `EXPECT_TEST_CUSTOMER_ARREARS`，退出码 `2`。 +- `pnpm test:expect:acceptance -- rev-bugfix-50-cashier-filter --target unstaged --timeout 120000 --verbose`：requiredData 已提供，但 Codex ACP 认证失败，runner 输出清晰 `BLOCKED: Codex ACP authentication failed before browser acceptance steps ran...`，退出码 `2`，未再输出原始 ACP 栈。 +- `pnpm build:dev`：通过，输出 `Build successful. Please see dist directory`。构建期间仍存在既有 Vite CJS deprecation warning、SVG symbolId warning、Rollup PURE annotation warning。 + +### 结论 + +本次已将仓库内可控问题收敛：pnpm 版本、runner 启动路径、场景路由元数据、Codex ACP 认证失败语义均已有自动化测试覆盖。严格黑盒业务验收仍取决于外部 Codex ACP 认证状态；认证未完成时应按 `BLOCKED` 处理，不应判定业务 `PASS` 或 `FAIL`。 + +## 本地 Playwright smoke 入口：2026-06-08 无 ACP 场景 + +### 触发背景 + +用户本机没有 Codex ACP 认证，`pnpm test:expect:acceptance -- rev-bugfix-50-cashier-filter` 只能得到 `BLOCKED`，无法进入浏览器业务步骤。为保证前端页面链路仍可在本地验证，本次新增不依赖 ACP 的 Playwright smoke runner。 + +### 实现内容 + +- `package.json` 新增 `test:revenue:smoke`，执行 `node tools/revenue/run-local-smoke.mjs`。 +- `tools/revenue/run-local-smoke.mjs`： + - 默认读取 `/tmp/revenue-acceptance-env.sh`，支持 `REVENUE_SMOKE_ENV_FILE` 覆盖。 + - 使用 `EXPECT_BASE_URL`、`EXPECT_TEST_ADMIN_USERNAME`、`EXPECT_TEST_ADMIN_PASSWORD` 等本机环境变量登录本地前端代理 `/admin-api/system/auth/login`。 + - 自动复用或启动本地 Vite dev server。 + - 访问 `/operatingCharges/counterCheckout` 与 `/operatingCharges/redReversalRecord`，检查页面标题/关键文案、登录状态、not-found 状态，并输出截图。 + - 对登录不可达、认证被拒等数据/环境问题输出 `BLOCKED`，退出码 `2`。 + - 修复两个 runner 稳定性问题：`SmokeBlockedError` TDZ、业务流水号包含 `404` 时误判为 404 页。 +- `tests/revenue-bugs/revenueLocalSmokeRunner.test.mjs` 覆盖 env 解析、默认配置、页面清单、BLOCKED 输出、404 误判和超时 helper。 + +### 执行命令 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --test tests/revenue-bugs/revenueLocalSmokeRunner.test.mjs +pnpm test:revenue:smoke +node --test tests/revenue-bugs/revenueLocalSmokeRunner.test.mjs tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs +node --test tests/expect/runExpectRunnerArgs.test.mjs tests/expect/revenueBugfixAcceptanceScenarios.test.mjs tests/expect/revenueAccountingClosureScenarios.test.mjs +pnpm exec eslint tools/revenue/run-local-smoke.mjs tests/revenue-bugs/revenueLocalSmokeRunner.test.mjs +pnpm build:dev +``` + +### 结果 + +- 本地 smoke runner 单测：通过，9 项通过、0 项失败。 +- 本地页面 smoke：通过。 + - `/operatingCharges/counterCheckout`：登录用户 `admin`，页面显示 `未结账`、`已结账`、`收费员`；截图为 `water-frontend/test-results/counter-checkout-local-smoke.png`。 + - `/operatingCharges/redReversalRecord`：页面显示 `红冲记录`、`红冲时间`、`收费员`；截图为 `water-frontend/test-results/red-reversal-record-local-smoke.png`。 +- 营收缺陷契约测试 + 本地 runner 单测：通过，14 项通过、0 项失败。 +- Expect runner/场景测试：通过，23 项通过、0 项失败。 +- focused ESLint：通过。 +- `pnpm build:dev`：通过，输出 `Build successful. Please see dist directory`。构建期间仍存在既有 Vite CJS deprecation warning、SVG symbolId warning、Rollup PURE annotation warning。 + +### 结论 + +本地前端页面链路现在可以通过 `pnpm test:revenue:smoke` 在无 ACP 的机器上执行。该入口证明登录、动态菜单路由、页面基础渲染和截图可用；它不替代 `expect-cli` 严格黑盒验收，也不验证 #50 收费员 A/B 业务数据筛选结果。严格业务验收仍需 ACP、其他可用 agent，或人工按正式验收计划执行。 diff --git a/docs/evidence/frontend-form-create-native-tag-guard-2026-06-05.md b/docs/evidence/bugfix/frontend/frontend-form-create-native-tag-guard-2026-06-05.md similarity index 100% rename from docs/evidence/frontend-form-create-native-tag-guard-2026-06-05.md rename to docs/evidence/bugfix/frontend/frontend-form-create-native-tag-guard-2026-06-05.md diff --git a/docs/evidence/bugfix/frontend/frontend-payment-method-account-address-required-2026-06-09.md b/docs/evidence/bugfix/frontend/frontend-payment-method-account-address-required-2026-06-09.md new file mode 100644 index 0000000..a3640bd --- /dev/null +++ b/docs/evidence/bugfix/frontend/frontend-payment-method-account-address-required-2026-06-09.md @@ -0,0 +1,56 @@ +# 客户缴费方式开户地址前端必填校验修复验证记录 + +日期：2026-06-09 + +## 问题现象 + +客户资料页面修改缴费方式时，前端代扣/托收表单展示了“开户地址”字段，但未做必填校验；提交到后端后，后端在保存代扣或托收资料时返回“开户地址不能为空”。 + +## 结论 + +本问题应由前端补齐校验。原因是后端代扣、托收资料保存对象均将 `accountAddress` 定义为必填字段，客户缴费方式修改链路会复用这两个保存对象。 + +## 修复范围 + +仓库：`../water-frontend` + +基线：`35aa0fbb` + +修改文件： + +- `src/views/custData/custInfo/components/PayMethodForm.vue` +- `src/views/custData/custCreate/components/WithHold.vue` +- `src/views/custData/custInfo/components/PayMethodForm.contract.test.mjs` + +## 修复内容 + +- 客户详情“缴费方式”弹窗： + - 托收资料 `collectionFormRules` 增加 `accountAddress` 必填。 + - 代扣资料 `withHoldingFormRules` 增加 `accountAddress` 必填。 +- 新户建档代扣弹窗： + - `formRules` 增加 `accountAddress` 必填。 +- 补充 node:test 契约测试，锁定上述规则。 + +## 验证命令与结果 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +node --test src/views/custData/custInfo/components/PayMethodForm.contract.test.mjs +``` + +结果：通过。 + +- `tests 2` +- `pass 2` +- `fail 0` + +```bash +cd /Volumes/Dpan/github/water-workspace/water-frontend +git diff --check -- src/views/custData/custInfo/components/PayMethodForm.vue src/views/custData/custCreate/components/WithHold.vue src/views/custData/custInfo/components/PayMethodForm.contract.test.mjs +``` + +结果：通过，无空白错误。 + +## 备注 + +当前前端仓库存在其他未提交的 expect 相关改动，本次未触碰。 diff --git a/docs/evidence/revenue-bugfix-clear-scope-frontend-2026-06-08.md b/docs/evidence/bugfix/frontend/revenue-bugfix-clear-scope-frontend-2026-06-08.md similarity index 100% rename from docs/evidence/revenue-bugfix-clear-scope-frontend-2026-06-08.md rename to docs/evidence/bugfix/frontend/revenue-bugfix-clear-scope-frontend-2026-06-08.md diff --git a/docs/evidence/bugfix/frontend/yw-business-flows-expect-cases-2026-06-09.md b/docs/evidence/bugfix/frontend/yw-business-flows-expect-cases-2026-06-09.md new file mode 100644 index 0000000..d0a05e9 --- /dev/null +++ b/docs/evidence/bugfix/frontend/yw-business-flows-expect-cases-2026-06-09.md @@ -0,0 +1,115 @@ +# YW 业务流程 Expect 验收用例编制记录（2026-06-09） + +## 背景 + +根据用户在 2026-06-09 提供的 5 条业务测试用例，前端仓新增 Expect 黑盒验收场景 suite： + +- `yw-business-flows:yw-01`：手工建档 +- `yw-business-flows:yw-02`：册本调整 +- `yw-business-flows:yw-03`：抄表录入 +- `yw-business-flows:yw-04`：复核开账 +- `yw-business-flows:yw-05`：柜台收费 + +前端实现位置： + +- `../water-frontend/tests/expect/yw-business-flows/scenarios.json` +- `../water-frontend/tests/expect/ywBusinessFlowsScenarios.test.mjs` +- `../water-frontend/tools/expect/acceptance-scenarios.mjs` +- `../water-frontend/tests/expect/README.md` + +## 执行入口 + +```bash +pnpm test:expect:acceptance -- yw-business-flows:all +pnpm test:expect:acceptance -- yw-business-flows:yw-01 +pnpm test:expect:acceptance -- yw-05 +``` + +## 测试数据要求 + +新增场景使用以下测试数据环境变量： + +- `EXPECT_TEST_NEW_CUSTOMER_ARCHIVE` +- `EXPECT_TEST_AVAILABLE_METER` +- `EXPECT_TEST_INVOICE_PROFILE` +- `EXPECT_TEST_ARCHIVED_CUSTOMER` +- `EXPECT_TEST_TARGET_METER_BOOK` +- `EXPECT_TEST_METER_READ_CUSTOMER` +- `EXPECT_TEST_METER_READING_VALUE` +- `EXPECT_TEST_REVIEWABLE_METER_READ_RECORD` +- `EXPECT_TEST_BILLABLE_METER_READ_RECORD` +- `EXPECT_TEST_CHARGED_CUSTOMER` + +并复用： + +- `EXPECT_TEST_ADMIN_USERNAME` +- `EXPECT_TEST_CASHIER_A_USERNAME` + +缺少上述数据时，runner 必须在启动浏览器前返回 `BLOCKED`，不得使用占位符或编造业务记录继续执行。 + +## 验证结果 + +已执行目录契约与 runner 数据门禁验证： + +```bash +node --test tests/expect/ywBusinessFlowsScenarios.test.mjs +``` + +结果：`pass 6 / fail 0`。 + +```bash +pnpm test:expect:acceptance -- --list +``` + +结果：命令退出码 `0`，`yw-business-flows:yw-01` 至 `yw-business-flows:yw-05` 均已列出。 + +```bash +pnpm test:expect:acceptance -- yw-05 --no-dev-server +``` + +结果：命令退出码 `2`，按预期返回： + +- `BLOCKED: missing required acceptance test data for yw-05.` +- 缺少 `EXPECT_TEST_CASHIER_A_USERNAME` +- 缺少 `EXPECT_TEST_CHARGED_CUSTOMER` + +```bash +pnpm test:expect:acceptance -- yw-business-flows:all --no-dev-server +``` + +结果：命令退出码 `2`，按预期返回 `BLOCKED`，缺少全部 5 条 YW 用例所需的账号、客户、册本、水表、抄表、复核开账与柜台收费测试数据。 + +```bash +node --test tests/expect/*.test.mjs +``` + +结果：`pass 30 / fail 0`。 + +### 真实浏览器验收尝试（2026-06-09 12:00 CST） + +```bash +pnpm test:expect:acceptance -- yw-business-flows:all --no-dev-server --timeout 1800000 +``` + +结果：命令退出码 `1`，未形成 `PASS` 业务验收结论。 + +- 已启动真实浏览器并进入 `yw-business-flows:yw-01` 手工建档场景。 +- 浏览器侧可见记录显示已登录并访问 `http://localhost:18080/custData/custCreate`。 +- 运行过程中产生的主要证据： + - `/tmp/expect-artifacts/playwright/page@8c120c0eebb660ecda33437a218d685a.webm` + - `/tmp/expect-artifacts/playwright-results/result-*.json` + - `.expect/logs.md` +- ACP rollout 日志显示：用例在 `yw-01` 内部反复处理 Element Plus 下拉选择器，后续浏览器 transport 关闭。 +- Expect 最终报错： + - `ACP stream inactivity timeout` + - `Streaming failed: Agent produced no output for 180s.` +- 本次运行未进入 `yw-02` 至 `yw-05` 的业务执行阶段。 +- 本次运行中测试数据环境变量虽然已设置，但部分值存在乱码；agent 曾使用自行构造的可读测试数据继续填写。按黑盒验收规则，这不能作为有效 `PASS` 证据。 + +本次真实浏览器验收结论：`BLOCKED` / `FAIL-RUNNER`。阻断原因为 Expect ACP/browser transport 超时，且测试数据可读性不足；业务功能本身尚不能据此判定通过或失败。 + +## 当前结论 + +测试用例已编制为可执行 Expect 黑盒验收场景，目录加载、提示词生成和数据缺失拦截均通过。 + +截至本记录，真实浏览器业务验收已尝试执行，但未形成有效业务通过结论；当前阻断点为测试数据可读性不足与 Expect ACP/browser transport 超时。真实业务场景结论当前仍为 `BLOCKED`，不是 `PASS`。 diff --git a/docs/evidence/bugfix/revenue-bugfix-clear-scope-2026-06-08.md b/docs/evidence/bugfix/revenue-bugfix-clear-scope-2026-06-08.md new file mode 100644 index 0000000..cb8bbd2 --- /dev/null +++ b/docs/evidence/bugfix/revenue-bugfix-clear-scope-2026-06-08.md @@ -0,0 +1,178 @@ +# 营收明确缺陷第一批修复验证记录 + +日期：2026-06-08 + +## 修复范围 + +- #78 水价调整失败后重试闭环 +- #39 柜台预存缴费进入结账 +- #50 柜台结账收费员筛选 +- #53 预存抵扣校验 +- #58/#59 柜台红冲记录查询 +- #69/#76 待审批账务调整文案 + +## 后端基线 + +- 仓库：water-backend +- Worktree：backend-revenue-bugfix-clear-scope +- 提交：`ba136759b1925789cb0adc18105d00d6928add59` + +## 前端基线 + +- 仓库：water-frontend +- Worktree：frontend-revenue-bugfix-clear-scope +- 提交：`5f7ad7754473541483b26efa324419eb7a5d1a3b` + +## 验证命令与结果 + +### 后端 targeted tests + +```bash +cd /Volumes/Dpan/github/water-workspace/worktrees/backend-revenue-bugfix-clear-scope +mvn -pl sw-business/sw-business-server -Dtest=PriceTemplateServiceImplTest,PriceTemplateAdjustmentLockRedisDAOTest,CounterSettleApplicationServiceImplTest,ChargeServiceImplCounterPrepayTest test +``` + +结果：通过。 + +- Surefire 汇总：`Tests run: 26, Failures: 0, Errors: 0, Skipped: 0` +- Maven 结果：`BUILD SUCCESS` +- 备注：执行期间存在既有 Maven model warning、Mockito dynamic-agent warning；`PriceTemplateServiceImplTest` 中有一段业务代码捕获后记录的 NPE 栈日志，但测试结果为 0 failures / 0 errors。 + +### 后端 compile + +```bash +cd /Volumes/Dpan/github/water-workspace/worktrees/backend-revenue-bugfix-clear-scope +mvn -pl sw-business/sw-business-server -DskipTests compile +``` + +结果：通过。 + +- Maven 结果：`BUILD SUCCESS` + +### 前端 contract test + +```bash +cd /Volumes/Dpan/github/water-workspace/worktrees/frontend-revenue-bugfix-clear-scope +node --test tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs +``` + +结果：通过。 + +- Node test 汇总：`tests 5`, `pass 5`, `fail 0` + +### 前端 settings contract regression + +```bash +cd /Volumes/Dpan/github/water-workspace/worktrees/frontend-revenue-bugfix-clear-scope +node --test tests/settings/priceTemplateAdjustmentErrorHandling.test.mjs +``` + +结果：通过。 + +- Node test 汇总：`tests 3`, `pass 3`, `fail 0` + +### 前端 type check + +```bash +pnpm ts:check +``` + +结果：未完成，不作为通过项。 + +- 首次执行长时间无诊断输出后以 `[ELIFECYCLE] Command failed.` 退出。 +- 随后按用户明确指令停止继续运行 `vue-tsc` / `pnpm ts:check`。 +- 已终止残留 `vue-tsc` 进程。 + +### 前端 build + +```bash +cd /Volumes/Dpan/github/water-workspace/worktrees/frontend-revenue-bugfix-clear-scope +pnpm build:dev +``` + +结果：通过。 + +- 输出：`Build successful. Please see dist directory` +- 备注：构建期间存在既有 Vite CJS deprecation warning、SVG icon symbolId warning、Rollup PURE annotation warning。 + +## 备注 + +- 前端 worktree 中存在未跟踪 `test-results/*.png` 截图产物，本次未提交。 +- 本轮未处理 #70 和 #9。#70 需抓包确认提交字段；#9 需产品确认抄表状态规则。 + +## Jenkins 构建修复补充记录（2026-06-09） + +### 问题定位 + +- Jenkins `sw-system-cloud-dev-pipeline` 在 `sw-business-server` 编译阶段报出 `*DORef` 缺失、Lombok getter/setter/log 缺失以及 `CounterSettleApplicationServiceImpl.isChargePaymentRecord(...)` 重复定义。 +- 本地复现确认：`PrestorageBpmCallbackService` 已存在 `@Slf4j`，`log` 缺失不是独立代码问题，而是编译异常导致注解处理未完成后的级联报错。 +- 修复 `CounterSettleApplicationServiceImpl` 中重复的 `isChargePaymentRecord(PaymentRecordDO)` 后，`target/generated-sources/annotations` 重新生成 `*DORef.java`，Lombok 相关报错消失。 +- 同一提交引入的 `Collection::stream` 代码缺少 `java.util.Collection` 导入，补齐后编译闭环通过。 + +### 后端修复范围 + +- 仓库：`../water-backend` +- 分支：`develop` +- 基线：`8e42a5123` +- 修改文件：`sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/countersettle/CounterSettleApplicationServiceImpl.java` + +### 验证命令与结果 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-backend +mvn -pl sw-business/sw-business-server -am -DskipTests compile +``` + +结果：通过。 + +- Maven 结果：`BUILD SUCCESS` +- 说明：用于确认注解处理恢复，`*DORef` 生成文件重新出现。 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-backend +mvn clean package -DskipTests -T 1C -pl sw-dependencies,sw-framework,sw-gateway,sw-server,sw-module-system,sw-module-infra,sw-module-bpm,sw-module-pay,sw-module-report,sw-business,sw-business-bank,sw-module-member -am +``` + +结果：通过。 + +- Maven 结果：`BUILD SUCCESS` +- 耗时：`01:13 min (Wall Clock)` +- 备注：执行期间仍存在既有 Maven model warning、MapStruct unmapped target warning、Mockito `MockBean` deprecation warning；均未导致构建失败。 + +## Jenkins 构建修复收敛记录（2026-06-09 10:35） + +### 修复收敛结论 + +- 已确认 `8e42a5123 fix: configure sw-common annotation processors` 不是本次 Jenkins 编译失败的根因修复。 +- 已将 `sw-framework/sw-common/pom.xml` 恢复到 `8e42a5123` 之前的注解处理器版本配置，避免保留错误方向的 POM 改动。 +- 最终保留的真实修复为： + - 删除 `CounterSettleApplicationServiceImpl` 中重复定义的 `isChargePaymentRecord(PaymentRecordDO)`。 + - 补齐同文件中 `Collection::stream` 所需的 `java.util.Collection` import。 + +### 后端最终修复范围 + +- 仓库：`../water-backend` +- 分支：`develop` +- 修复前基线：`8e42a5123` +- 后端修复提交：`86203127eeb27fcb1ff8228a89a77eb3a3325c57` +- 修改文件： + - `sw-framework/sw-common/pom.xml` + - `sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/countersettle/CounterSettleApplicationServiceImpl.java` + +### 最终验证命令与结果 + +```bash +cd /Volumes/Dpan/github/water-workspace/water-backend +mvn clean package -DskipTests -T 1C -pl sw-dependencies,sw-framework,sw-gateway,sw-server,sw-module-system,sw-module-infra,sw-module-bpm,sw-module-pay,sw-module-report,sw-business,sw-business-bank,sw-module-member -am +``` + +结果：通过。 + +- Maven 结果：`BUILD SUCCESS` +- 耗时：`01:15 min (Wall Clock)` +- 完成时间：`2026-06-09T10:35:31+08:00` +- 关键模块结果： + - `sw-common`: `SUCCESS` + - `sw-business-server`: `SUCCESS` + - `sw-server`: `SUCCESS` +- 备注：验证命令使用 `-DskipTests`，本次结论覆盖编译与打包；测试执行被跳过。 diff --git a/docs/evidence/2026-06-10-prestore-test-results.md b/docs/evidence/rev004-accounting/2026-06-10-prestore-test-results.md similarity index 100% rename from docs/evidence/2026-06-10-prestore-test-results.md rename to docs/evidence/rev004-accounting/2026-06-10-prestore-test-results.md diff --git a/docs/guides/REV004_ACCOUNTING_ADJUST_API_DELTA.md b/docs/evidence/rev004-accounting/REV004_ACCOUNTING_ADJUST_API_DELTA.md similarity index 100% rename from docs/guides/REV004_ACCOUNTING_ADJUST_API_DELTA.md rename to docs/evidence/rev004-accounting/REV004_ACCOUNTING_ADJUST_API_DELTA.md diff --git a/docs/guides/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md b/docs/evidence/rev004-accounting/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md similarity index 100% rename from docs/guides/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md rename to docs/evidence/rev004-accounting/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md diff --git a/docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md b/docs/evidence/rev004-accounting/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md similarity index 100% rename from docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md rename to docs/evidence/rev004-accounting/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md diff --git a/docs/guides/REV004_CURRENT_TRUTH_MATRIX.md b/docs/evidence/rev004-accounting/REV004_CURRENT_TRUTH_MATRIX.md similarity index 100% rename from docs/guides/REV004_CURRENT_TRUTH_MATRIX.md rename to docs/evidence/rev004-accounting/REV004_CURRENT_TRUTH_MATRIX.md diff --git a/docs/guides/REV004_DICT_BINDING_MATRIX.md b/docs/evidence/rev004-accounting/REV004_DICT_BINDING_MATRIX.md similarity index 100% rename from docs/guides/REV004_DICT_BINDING_MATRIX.md rename to docs/evidence/rev004-accounting/REV004_DICT_BINDING_MATRIX.md diff --git a/docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md b/docs/evidence/rev004-accounting/REV004_FORMAL_TABLE_STATUS_MATRIX.md similarity index 100% rename from docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md rename to docs/evidence/rev004-accounting/REV004_FORMAL_TABLE_STATUS_MATRIX.md diff --git a/docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md b/docs/evidence/rev004-accounting/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md similarity index 100% rename from docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md rename to docs/evidence/rev004-accounting/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md diff --git a/docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md b/docs/evidence/rev004-accounting/REV004_FRONTEND_OMX_TEAM_PROMPTS.md similarity index 100% rename from docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md rename to docs/evidence/rev004-accounting/REV004_FRONTEND_OMX_TEAM_PROMPTS.md diff --git a/docs/guides/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md b/docs/evidence/rev004-accounting/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md similarity index 100% rename from docs/guides/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md rename to docs/evidence/rev004-accounting/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md diff --git a/docs/guides/REV004_FRONTEND_QA_DEBUG_NOTICE.md b/docs/evidence/rev004-accounting/REV004_FRONTEND_QA_DEBUG_NOTICE.md similarity index 100% rename from docs/guides/REV004_FRONTEND_QA_DEBUG_NOTICE.md rename to docs/evidence/rev004-accounting/REV004_FRONTEND_QA_DEBUG_NOTICE.md diff --git a/docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md b/docs/evidence/rev004-accounting/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md similarity index 100% rename from docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md rename to docs/evidence/rev004-accounting/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md diff --git a/docs/guides/REV004_IMPLEMENTATION_HANDOFF.md b/docs/evidence/rev004-accounting/REV004_IMPLEMENTATION_HANDOFF.md similarity index 100% rename from docs/guides/REV004_IMPLEMENTATION_HANDOFF.md rename to docs/evidence/rev004-accounting/REV004_IMPLEMENTATION_HANDOFF.md diff --git a/docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md b/docs/evidence/rev004-accounting/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md similarity index 100% rename from docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md rename to docs/evidence/rev004-accounting/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md diff --git a/docs/guides/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md b/docs/evidence/rev004-accounting/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md similarity index 100% rename from docs/guides/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md rename to docs/evidence/rev004-accounting/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md diff --git a/docs/evidence/rev004-accounting-adjust-first-batch-dev-entry-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-accounting-adjust-first-batch-dev-entry-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-accounting-adjust-first-batch-dev-entry-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-accounting-adjust-first-batch-dev-entry-2026-04-15.md diff --git a/docs/evidence/rev004-accounting-adjust-standard-layer-bootstrap-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-accounting-adjust-standard-layer-bootstrap-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-accounting-adjust-standard-layer-bootstrap-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-accounting-adjust-standard-layer-bootstrap-2026-04-15.md diff --git a/docs/evidence/rev004-accounting-adjust-standard-layer-code-bootstrap-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-accounting-adjust-standard-layer-code-bootstrap-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-accounting-adjust-standard-layer-code-bootstrap-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-accounting-adjust-standard-layer-code-bootstrap-2026-04-15.md diff --git a/docs/evidence/rev004-accountlog-action-wiring-notes-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountlog-action-wiring-notes-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountlog-action-wiring-notes-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountlog-action-wiring-notes-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-dict-ui-consistency-summary-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-dict-ui-consistency-summary-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-dict-ui-consistency-summary-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-dict-ui-consistency-summary-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-final-review-summary-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-final-review-summary-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-final-review-summary-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-final-review-summary-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-gap-remediation-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-gap-remediation-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-gap-remediation-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-gap-remediation-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md similarity index 71% rename from docs/evidence/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md index 8df446e..84499ad 100644 --- a/docs/evidence/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md +++ b/docs/evidence/rev004-accounting/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md @@ -198,6 +198,49 @@ - `soldSubmit_shouldWritePendingOperatLog` - `soldBatchRevoke_shouldWriteRevokeLogForPendingSyntheticRecord` - `logPrestorage_shouldClearChargePaymentAndIncreaseTargetDeposit` + +## 2026-06-05 sw-business-server 启动循环修复验证 + +### 问题现象 +- 环境：`root@192.168.10.130`，容器 `sw-business-server` +- 现象：容器反复重启，Docker healthcheck 一度显示 healthy，但应用日志持续出现 `Application run failed` +- 关键异常： + - `Error creating bean with name 'prestorageAdjustBpmApiImpl'` + - `Error creating bean with name 'prestorageBpmCallbackService'` + - `BeanCurrentlyInCreationException: Error creating bean with name 'custServiceImpl'` + - `custServiceImpl` 已以 raw version 注入 `chargeServiceImpl`、`waterUseSchemeServiceImpl`、`exceedWaterUseSchemeServiceImpl`、`custWaterSchemeRelServiceImpl`，随后又被 AOP 包装，Spring 拒绝混用 raw bean 与 proxy bean + +### 修复策略 +- 保留既有 `spring.main.allow-circular-references=true` 配置；该配置只能允许普通循环依赖，不能解决 raw bean 被代理包装后的不一致问题。 +- 对异常中明确点名的 4 个 `CustService` 注入点增加 `@Lazy`： + - `ChargeServiceImpl.custService` + - `WaterUseSchemeServiceImpl.custService` + - `ExceedWaterUseSchemeServiceImpl.custService` + - `CustWaterSchemeRelServiceImpl.custService` +- 新增回归测试 `CustServiceCircularDependencyContractTest`，约束上述 4 个注入点必须使用 lazy proxy。 + +### 本次验证 +- RED 验证： + - 命令：`mvn -pl sw-business/sw-business-server -am -Dtest=CustServiceCircularDependencyContractTest -Dsurefire.failIfNoSpecifiedTests=false test` + - 结果：测试按预期失败，失败点为 `ChargeServiceImpl.custService must be @Lazy` +- GREEN 验证： + - 命令：`mvn -pl sw-business/sw-business-server -am -Dtest=CustServiceCircularDependencyContractTest -Dsurefire.failIfNoSpecifiedTests=false test` + - 结果：BUILD SUCCESS，`1 tests / 0 failures / 0 errors / 0 skipped` +- 打包验证： + - 命令：`mvn -pl sw-business/sw-business-server -am -DskipTests package` + - 结果：BUILD SUCCESS，生成 `sw-business/sw-business-server/target/sw-business-server.jar` +- 远端部署验证： + - 上传 jar 到 `/projects/sw-cloud/sw-business-server/target/sw-business-server.jar` + - 远端执行：`cd /projects/sw-cloud && docker compose build sw-business-server && docker compose up -d sw-business-server` + - 结果：镜像 `sw-cloud-sw-business-server` 重建成功，容器 `sw-business-server` 重新创建并启动 +- 远端运行验证： + - 日志出现：`Tomcat started on port 48090`、`nacos registry, DEFAULT_GROUP business-server 192.168.10.130:48090 register finished`、`Started BusinessApplication in 42.77 seconds` + - 最近启动日志未再出现 `Application run failed`、`BeanCurrentlyInCreationException`、`Error creating bean with name` + - HTTP 验证：`curl http://127.0.0.1:48090/actuator/health` 返回 `{"status":"UP"}`，HTTP 200 + +### 遗留风险 +- `docker-compose.yml` 中 `sw-business-server` healthcheck 当前检查 `http://localhost:48080`，而业务应用实际监听 `48090`；该 healthcheck 会把其他服务返回的 HTTP 200 / 404 JSON 误判为业务健康。建议后续改为 `http://localhost:48090/actuator/health`。 +- 当前修复是最小断环修复；长期更优方向是拆分 `CustServiceImpl` 的查询能力与写能力，减少跨业务 service 之间的双向依赖。 - `logRevoke_shouldRestoreChargePaymentAndRollbackTransferredDeposit` - `logProcess_shouldReturnUpdatedProcessSummary` - `logAttachments_shouldReturnUnresolvedAttachmentRef` @@ -420,3 +463,112 @@ ### 影响 - `prestorage` 查询/提交流程/撤销/流程查看/附件查看 这一组链路现在都已有真实库证据 - 剩余缺口进一步收敛到：字典 label / UI 文案一致性、边角筛选条件穷尽、UI 编排级验证 + +## 2026-06-05 远端启动修复后真实 HTTP/BPM 闭环验证 + +### 环境 +- 后端：`192.168.10.130`，`sw-business-server` 端口 `48090`，gateway 端口 `48080` +- 前端代理：本地 Vite `http://127.0.0.1:18080/admin-api` -> gateway +- 数据库：`192.168.10.130:5436/sw_system` +- 测试数据：`00_reset.sql` + `01_dict_seed.sql` + `10_prestorage_seed.sql` + +### 启动与健康检查 +- `sw-business-server` 重新构建部署后日志出现 `Started BusinessApplication` +- `curl http://192.168.10.130:48090/actuator/health` 返回 `{"status":"UP"}` +- `curl http://192.168.10.130:48080/actuator/health` 返回 `{"status":"UP"}` + +### 真实接口链路 +1. 登录 +- `POST /admin-api/system/auth/login` +- `tenant-id: 1` +- 返回 `code=0`，获得 `accessToken` + +2. 预存退款：保存 -> BPM 审批 -> 自动执行 -> 查询回看 +- `POST /admin-api/business/accounting-adjust/prestorage-save` +- 请求核心字段： + - `custCode=REV004_IT_SRC` + - `refundAmount=10.00` + - `applicant=接口闭环测试人` + - `attachmentRefs=[real-api-proof-1]` +- 保存返回： + - `adjustmentNo=REV004-PRF-900001-20260605101623` + - `resultStatus=PENDING_APPROVAL` + - `approvalStatus=PENDING_APPROVAL` + - `writeBackStatus=PENDING` + - `resultObjectNo=8d8af605-6084-11f1-8df9-5ad978d7f8ab` +- BPM 待办： + - `GET /admin-api/bpm/task/list-by-process-instance-id?processInstanceId=8d8af605-6084-11f1-8df9-5ad978d7f8ab` + - taskId=`8da3600e-6084-11f1-8df9-5ad978d7f8ab` +- 审批： + - `PUT /admin-api/bpm/task/approve` + - 返回 `code=0,data=true` +- 回看： + - `GET /admin-api/business/accounting-adjust/prestorage-process` + - `resultStatus=SUCCESS` + - `approvalStatus=APPROVED` + - `writeBackStatus=UPDATED` + - `processState=UPDATED` + - `latestMessage=BPM审批通过后自动执行预存退款` +- DB 断言： + - `biz_account(900001).deposit=90.00` + - `biz_prestorage_adjust.business_status=COMPLETED` + - `biz_prestorage_payment_relation` 写入 `payment_record_id=159` + +3. 预存转账：保存 -> BPM 审批 -> 自动执行 -> 查询回看 +- `POST /admin-api/business/accounting-adjust/prestorage-save` +- 请求核心字段： + - `custCode=REV004_IT_SRC` + - `targetCustCode=REV004_IT_TGT` + - `transferAmount=30.00` + - `applicant=接口闭环转账人` + - `attachmentRefs=[real-api-transfer-proof]` +- 保存返回： + - `adjustmentNo=REV004-PTR-900001-20260605102121` + - `resultStatus=PENDING_APPROVAL` + - `approvalStatus=PENDING_APPROVAL` + - `writeBackStatus=PENDING` + - `resultObjectNo=3e231762-6085-11f1-8df9-5ad978d7f8ab` +- BPM 审批： + - taskId=`3e2401cb-6085-11f1-8df9-5ad978d7f8ab` + - `PUT /admin-api/bpm/task/approve` 返回 `code=0,data=true` +- 回看： + - `GET /admin-api/business/accounting-adjust/prestorage-process` + - `resultStatus=SUCCESS` + - `approvalStatus=APPROVED` + - `writeBackStatus=UPDATED` + - `latestMessage=BPM审批通过后自动执行预存转账` + - `prestorage-page` 中 `workOrderStatus=2 / adjustmentType=2 / targetCustCode=REV004_IT_TGT / remainingAmount=60.00` +- DB 断言： + - `biz_account(900001).deposit=60.00` + - `biz_account(900004).deposit=30.00` + +### 本次联调发现并处理的问题 +- 首次 BPM 审批退款失败，`/admin-api/bpm/task/approve` 返回 `code=500` +- 服务端根因： + - `ERROR: relation "biz_prestorage_payment_relation_seq" does not exist` + - 表 DDL 使用 `BIGSERIAL`，实际 sequence 为 `biz_prestorage_payment_relation_id_seq` + - Java 实体 `PrestoragePaymentRelationDO` 原标注 `@KeySequence("biz_prestorage_payment_relation_seq")` +- 临时环境修复： + - 远端库补齐兼容 sequence：`biz_prestorage_payment_relation_seq` +- 代码修复： + - `PrestoragePaymentRelationDO` 改为 `@KeySequence("biz_prestorage_payment_relation_id_seq")` + - 新增 `PrestoragePaymentRelationSequenceContractTest` 锁定注解与 DDL sequence 名一致 + +### 本次本地验证 +- `mvn -pl sw-business/sw-business-server -am -DskipTests compile` + - 结果：BUILD SUCCESS +- `javap` 反射核验： + - `PrestoragePaymentRelationDO` 当前产物中的 `@KeySequence` 为 `biz_prestorage_payment_relation_id_seq` +- 受既有测试编译问题影响，单测命令 `mvn -pl sw-business/sw-business-server -Dtest=PrestoragePaymentRelationSequenceContractTest test` 未能进入目标测试： + - 阻塞点：`MeterInOutServiceImplTest` 引用缺失的 `METER_IN_MODEL_CALIBER_MISMATCH` 与 `METER_IMPORT_MODEL_CALIBER_MISMATCH_MSG` + +### 2026-06-05 本地 targeted contract test 复核 +- 命令： + - `mvn -pl sw-business/sw-business-server -am -Dtest=CustServiceCircularDependencyContractTest,PrestoragePaymentRelationSequenceContractTest -Dsurefire.failIfNoSpecifiedTests=false test` +- 结果： + - `BUILD SUCCESS` + - `CustServiceCircularDependencyContractTest`: 1 tests / 0 failures / 0 errors / 0 skipped + - `PrestoragePaymentRelationSequenceContractTest`: 1 tests / 0 failures / 0 errors / 0 skipped +- 说明： + - `-Dsurefire.failIfNoSpecifiedTests=false` 用于 reactor 前置模块无匹配 `-Dtest` 用例时继续执行到 `sw-business-server` + - 本次复核覆盖四处 `CustService` 懒加载注入 contract 与 `biz_prestorage_payment_relation_id_seq` 注解 contract diff --git a/docs/evidence/rev004-accountprocess-interface-truth-matrix-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-interface-truth-matrix-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-interface-truth-matrix-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-interface-truth-matrix-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-page-label-audit-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-page-label-audit-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-page-label-audit-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-page-label-audit-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-real-wiring-cleanup-2026-06-05.md b/docs/evidence/rev004-accounting/rev004-accountprocess-real-wiring-cleanup-2026-06-05.md similarity index 100% rename from docs/evidence/rev004-accountprocess-real-wiring-cleanup-2026-06-05.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-real-wiring-cleanup-2026-06-05.md diff --git a/docs/evidence/rev004-accountprocess-split-adjust-brief-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-accountprocess-split-adjust-brief-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-accountprocess-split-adjust-brief-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-split-adjust-brief-2026-04-14.md diff --git a/docs/evidence/rev004-accountprocess-split-adjust-gap-summary-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-accountprocess-split-adjust-gap-summary-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-accountprocess-split-adjust-gap-summary-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-split-adjust-gap-summary-2026-04-14.md diff --git a/docs/evidence/rev004-accountprocess-ui-element-matrix-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-ui-element-matrix-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-ui-element-matrix-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-ui-element-matrix-2026-04-13.md diff --git a/docs/evidence/rev004-accountprocess-ui-orchestration-checklist-2026-04-13.md b/docs/evidence/rev004-accounting/rev004-accountprocess-ui-orchestration-checklist-2026-04-13.md similarity index 100% rename from docs/evidence/rev004-accountprocess-ui-orchestration-checklist-2026-04-13.md rename to docs/evidence/rev004-accounting/rev004-accountprocess-ui-orchestration-checklist-2026-04-13.md diff --git a/docs/evidence/rev004-bad-debt-formal-table-dev-db-apply-2026-04-17.md b/docs/evidence/rev004-accounting/rev004-bad-debt-formal-table-dev-db-apply-2026-04-17.md similarity index 100% rename from docs/evidence/rev004-bad-debt-formal-table-dev-db-apply-2026-04-17.md rename to docs/evidence/rev004-accounting/rev004-bad-debt-formal-table-dev-db-apply-2026-04-17.md diff --git a/docs/evidence/rev004-latefee-batch-contract-formalization-implementation-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-latefee-batch-contract-formalization-implementation-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-latefee-batch-contract-formalization-implementation-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-latefee-batch-contract-formalization-implementation-2026-04-14.md diff --git a/docs/evidence/rev004-latefee-daily-rule-confirmation-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-latefee-daily-rule-confirmation-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-latefee-daily-rule-confirmation-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-latefee-daily-rule-confirmation-2026-04-15.md diff --git a/docs/evidence/rev004-latefee-formal-table-db-blocker-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-latefee-formal-table-db-blocker-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-latefee-formal-table-db-blocker-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-latefee-formal-table-db-blocker-2026-04-15.md diff --git a/docs/evidence/rev004-latefee-formal-table-deploy-sql-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-latefee-formal-table-deploy-sql-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-latefee-formal-table-deploy-sql-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-latefee-formal-table-deploy-sql-2026-04-15.md diff --git a/docs/evidence/rev004-latefee-formal-table-dev-db-apply-2026-04-15.md b/docs/evidence/rev004-accounting/rev004-latefee-formal-table-dev-db-apply-2026-04-15.md similarity index 100% rename from docs/evidence/rev004-latefee-formal-table-dev-db-apply-2026-04-15.md rename to docs/evidence/rev004-accounting/rev004-latefee-formal-table-dev-db-apply-2026-04-15.md diff --git a/docs/evidence/rev004-latefee-legacy-structure-gap-summary-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-latefee-legacy-structure-gap-summary-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-latefee-legacy-structure-gap-summary-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-latefee-legacy-structure-gap-summary-2026-04-14.md diff --git a/docs/evidence/rev004-prestorage-bpm-db-apply-2026-04-24.md b/docs/evidence/rev004-accounting/rev004-prestorage-bpm-db-apply-2026-04-24.md similarity index 100% rename from docs/evidence/rev004-prestorage-bpm-db-apply-2026-04-24.md rename to docs/evidence/rev004-accounting/rev004-prestorage-bpm-db-apply-2026-04-24.md diff --git a/docs/evidence/rev004-prestorage-bpm-deployed-integration-check-2026-04-24.md b/docs/evidence/rev004-accounting/rev004-prestorage-bpm-deployed-integration-check-2026-04-24.md similarity index 100% rename from docs/evidence/rev004-prestorage-bpm-deployed-integration-check-2026-04-24.md rename to docs/evidence/rev004-accounting/rev004-prestorage-bpm-deployed-integration-check-2026-04-24.md diff --git a/docs/evidence/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md b/docs/evidence/rev004-accounting/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md similarity index 100% rename from docs/evidence/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md rename to docs/evidence/rev004-accounting/rev004-prestorage-formal-table-dev-db-apply-2026-04-16.md diff --git a/docs/evidence/rev004-prestorage-strict-formal-first-2026-04-17.md b/docs/evidence/rev004-accounting/rev004-prestorage-strict-formal-first-2026-04-17.md similarity index 100% rename from docs/evidence/rev004-prestorage-strict-formal-first-2026-04-17.md rename to docs/evidence/rev004-accounting/rev004-prestorage-strict-formal-first-2026-04-17.md diff --git a/docs/evidence/rev004-prestorage-submit-dev-call-2026-04-23.md b/docs/evidence/rev004-accounting/rev004-prestorage-submit-dev-call-2026-04-23.md similarity index 100% rename from docs/evidence/rev004-prestorage-submit-dev-call-2026-04-23.md rename to docs/evidence/rev004-accounting/rev004-prestorage-submit-dev-call-2026-04-23.md diff --git a/docs/evidence/rev004-price-diff-formal-table-dev-db-apply-2026-04-17.md b/docs/evidence/rev004-accounting/rev004-price-diff-formal-table-dev-db-apply-2026-04-17.md similarity index 100% rename from docs/evidence/rev004-price-diff-formal-table-dev-db-apply-2026-04-17.md rename to docs/evidence/rev004-accounting/rev004-price-diff-formal-table-dev-db-apply-2026-04-17.md diff --git a/docs/evidence/rev004-redink-formal-table-dev-db-apply-2026-04-17.md b/docs/evidence/rev004-accounting/rev004-redink-formal-table-dev-db-apply-2026-04-17.md similarity index 100% rename from docs/evidence/rev004-redink-formal-table-dev-db-apply-2026-04-17.md rename to docs/evidence/rev004-accounting/rev004-redink-formal-table-dev-db-apply-2026-04-17.md diff --git a/docs/evidence/rev004-split-adjust-current-state-comparison-summary-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-split-adjust-current-state-comparison-summary-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-split-adjust-current-state-comparison-summary-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-split-adjust-current-state-comparison-summary-2026-04-14.md diff --git a/docs/evidence/rev004-split-adjust-execution-design-draft-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-split-adjust-execution-design-draft-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-split-adjust-execution-design-draft-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-split-adjust-execution-design-draft-2026-04-14.md diff --git a/docs/evidence/rev004-split-adjust-formalization-implementation-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-split-adjust-formalization-implementation-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-split-adjust-formalization-implementation-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-split-adjust-formalization-implementation-2026-04-14.md diff --git a/docs/evidence/rev004-split-adjust-water-first-mvp-design-2026-04-14.md b/docs/evidence/rev004-accounting/rev004-split-adjust-water-first-mvp-design-2026-04-14.md similarity index 100% rename from docs/evidence/rev004-split-adjust-water-first-mvp-design-2026-04-14.md rename to docs/evidence/rev004-accounting/rev004-split-adjust-water-first-mvp-design-2026-04-14.md diff --git a/docs/evidence/rev004-writtenoff-formal-table-dev-db-apply-2026-04-17.md b/docs/evidence/rev004-accounting/rev004-writtenoff-formal-table-dev-db-apply-2026-04-17.md similarity index 100% rename from docs/evidence/rev004-writtenoff-formal-table-dev-db-apply-2026-04-17.md rename to docs/evidence/rev004-accounting/rev004-writtenoff-formal-table-dev-db-apply-2026-04-17.md diff --git a/docs/evidence/rev005-invoice/2026-06-16-invoice-document-audit.md b/docs/evidence/rev005-invoice/2026-06-16-invoice-document-audit.md new file mode 100644 index 0000000..1c9b478 --- /dev/null +++ b/docs/evidence/rev005-invoice/2026-06-16-invoice-document-audit.md @@ -0,0 +1,129 @@ +# REV-005 发票业务流 — 文档审计报告 + +**审计日期**: 2026-06-16 +**审计范围**: `water-docs/specs/002-rev005-invoice-flow/` + `docs/design/` 主文档 + `water-backend` 代码（worktree `backend-rev005`） +**审计目标**: 评估发票相关文档的完整性、一致性和可追溯性 + +--- + +## 1. 审计总览 + +| 维度 | 结论 | +|------|------| +| 规格完整性 | ✅ 完备 | +| 正式设计一致性 | ⚠️ 轻微偏差（状态定义 6 vs 4 态） | +| 接口契约覆盖 | ✅ 完备 | +| 数据模型覆盖 | ✅ 完备（正式版在 DB 设计中，specs 草稿已删除） | +| 代码实现对应 | ✅ 59/65 任务完成，6 项为验证任务 | +| 前端设计覆盖 | ✅ 有独立前端设计文档（866 行） | +| 验证证据 | ❌ 8 项验证任务未完成 | + +--- + +## 2. 文档地图 + +``` +specs/002-rev005-invoice-flow/ +├── spec.md ✅ 有 +├── plan.md ✅ 有 +├── tasks.md ✅ 有（65 项，59 完成） +├── research.md ✅ 有 +├── quickstart.md ✅ 有 +├── verification.md ⚠️ 有，但 8 个验证任务未完成 +└── frontend-finance-design.md ✅ 有（2026-05-12 新增） + +docs/design/ (正式主文档) +├── 02_Detailed_Design/12_REV_Detailed.md ✅ REV-005 章节完整 +├── 03_Technical_Design/01_Database_Design.md ✅ biz_invoice 表覆盖 +└── 03_Technical_Design/03_Interface_Design.md ✅ IF-REV-008/009 定义完整 + +docs/evidence/rev005-invoice/ 📭 空（尚无证据入库） +``` + +--- + +## 3. 发现 + +### 3.1 状态定义差异（中风险） + +**问题**：`12_REV_Detailed.md` 定义了 6 个发票状态（`SUBMITTED`、`PENDING`、`SUCCESS`、`FAIL`、`INVALID`、`RED_INK`），但 `InvoiceController` 代码中实现了 `invalidate` 和 `red-ink` 两个独立端点，而 `InvoiceDO` 中的 `invoiceStatus` 字段是否支持这 6 态尚未在代码层确认。 + +**影响**：作废/红冲是二期补齐的功能，需确认 `biz_invoice` 表的 `invoice_status` 枚举已包含 `INVALID` 和 `RED_INK`，否则运行时会抛异常。 + +**建议**：检查 `InvoiceStatusEnum`（如存在）或 `biz_invoice` 的 DDL 确认枚举覆盖。 + +### 3.2 验证证据缺失（低风险） + +`specs/002-rev005-invoice-flow/verification.md` 中 8 个验证任务未完成： + +| 编号 | 内容 | 阻塞点 | +|------|------|--------| +| T022 | 重复申请、部分开票拒绝的样本 | 需联调环境 | +| T033 | SYS-008 不可用、超时等异常样本 | 需联调环境 | +| T044 | 回写/查询/下载/推送成功率统计 | 需联调环境 | +| T055 | 作废/红冲运行态日志样本 | 需联调环境 | +| T060-T063 | SC-001~SC-004 性能指标采样 | 需测试环境 | + +**影响**：不影响功能实现，但会影响验收签字。 + +**建议**：在提测前集中补齐，可安排在联调阶段同步采集。 + +### 3.3 接口路径不一致（低风险） + +| 定义位置 | 路径 | +|----------|------| +| `specs/002/contracts/if-rev-008.md`（已删除） | `/api/invoice/apply`（假设） | +| `03_Interface_Design.md` | `/business/invoice/apply` | +| `InvoiceController.java` | `/business/invoice/apply`（`@RequestMapping("/business/invoice")` + `@PostMapping("/apply")`） | + +正式接口设计和代码实现路径一致（`/business/invoice/apply`）。specs 里的旧契约已删除，不存在冲突。✅ 无问题。 + +### 3.4 前端设计文档状态（观察项） + +`frontend-finance-design.md` 是 2026-05-12 新增的，晚于主设计文档（2026-03-19）。它是独立于后端设计文档的前端实现补充，目前状态为"作为前端实现输入"。 + +**影响**：`water-frontend` 尚未同步确认是否已按照此文档实现。 + +**建议**：下一步在 `water-frontend` 的 AGENTS.md 或对应 spec 中确认前端实现进度。 + +### 3.5 数据模型一致性（已解决） + +此前 `specs/002/` 存在独立的 `data-model.md` 和 `contracts/` 目录，与正式设计文档有内容重叠。本次审计已删除冗余草稿，数据模型以 `01_Database_Design.md` 为准，接口以 `03_Interface_Design.md` 为准。 + +--- + +## 4. FR 覆盖矩阵 + +| FR | 描述 | 设计文档 | 代码 | 状态 | +|----|------|---------|------|------| +| FR-001 | 后台发票申请接口 | ✅ | ✅ `POST /apply` | 已实现 | +| FR-002 | 校验账单状态 | ✅ | ✅ `InvoiceServiceImpl` | 已实现 | +| FR-003 | 校验客户开票信息 | ✅ | ✅ | 已实现 | +| FR-004 | 校验开票限额 | ⚠️ 设计中提及但未详细展开 | ❓ 待确认 | 部分 | +| FR-005 | 生成发票申请记录 | ✅ | ✅ `biz_invoice_record` | 已实现 | +| FR-006 | 调用 SYS-008 | ✅ | ✅ `InvoicePlatformClient` | 已实现 | +| FR-007 | 定时查询兜底 | ✅ | ✅ `InvoiceCompensateJob` | 已实现 | +| FR-008 | 更新发票状态 | ✅ | ✅ | 已实现 | +| FR-009 | 发票-账单关联 | ✅ | ✅ `biz_charge_invoice_rel` | 已实现 | +| FR-010 | 客户侧查询/下载/推送 | ✅ | ✅ 3 个端点 | 已实现 | +| FR-011 | 操作日志 | ✅ | ⚠️ 部分方法有日志 | 部分 | +| FR-012 | 作废入口 | ✅ | ✅ `POST /invalidate` | 已实现 | +| FR-013 | 红冲入口 | ✅ | ✅ `POST /red-ink` | 已实现 | +| FR-014 | 终态保护与结果回写 | ✅ | ✅ | 已实现 | + +**关键发现**：FR-004（开票限额）在设计文档中提及但未明确限额来源（配置表？固定值？），代码层待确认。FR-011（操作日志）在关键动作上有日志，但完整度待验证。 + +--- + +## 5. 建议优先级 + +| 优先级 | 建议 | +|--------|------| +| **P0** | 确认 `biz_invoice` 的 `invoiceStatus` 枚举是否包含 `INVALID` 和 `RED_INK`，避免作废/红冲端点运行时报错 | +| **P1** | 明确开票限额校验逻辑（FR-004）：从配置表读取还是硬编码，限额是单笔还是累计 | +| **P1** | 联调阶段集中采集 T022/T033/T044/T055/T060-T063 的验证样本 | +| **P2** | 确认 `water-frontend` 对 `frontend-finance-design.md` 的实现进度 | + +--- + +审计结论：REV-005 发票业务流的文档体系基本完备，设计文档、接口契约、数据模型和代码实现高度对齐。主要风险点是作废/红冲状态枚举的代码层覆盖确认，以及 8 项验证样本的补充。 diff --git a/docs/evidence/revenue-bugfix-clear-scope-2026-06-08.md b/docs/evidence/revenue-bugfix-clear-scope-2026-06-08.md deleted file mode 100644 index 171cc69..0000000 --- a/docs/evidence/revenue-bugfix-clear-scope-2026-06-08.md +++ /dev/null @@ -1,101 +0,0 @@ -# 营收明确缺陷第一批修复验证记录 - -日期：2026-06-08 - -## 修复范围 - -- #78 水价调整失败后重试闭环 -- #39 柜台预存缴费进入结账 -- #50 柜台结账收费员筛选 -- #53 预存抵扣校验 -- #58/#59 柜台红冲记录查询 -- #69/#76 待审批账务调整文案 - -## 后端基线 - -- 仓库：water-backend -- Worktree：backend-revenue-bugfix-clear-scope -- 提交：`ba136759b1925789cb0adc18105d00d6928add59` - -## 前端基线 - -- 仓库：water-frontend -- Worktree：frontend-revenue-bugfix-clear-scope -- 提交：`5f7ad7754473541483b26efa324419eb7a5d1a3b` - -## 验证命令与结果 - -### 后端 targeted tests - -```bash -cd /Volumes/Dpan/github/water-workspace/worktrees/backend-revenue-bugfix-clear-scope -mvn -pl sw-business/sw-business-server -Dtest=PriceTemplateServiceImplTest,PriceTemplateAdjustmentLockRedisDAOTest,CounterSettleApplicationServiceImplTest,ChargeServiceImplCounterPrepayTest test -``` - -结果：通过。 - -- Surefire 汇总：`Tests run: 26, Failures: 0, Errors: 0, Skipped: 0` -- Maven 结果：`BUILD SUCCESS` -- 备注：执行期间存在既有 Maven model warning、Mockito dynamic-agent warning；`PriceTemplateServiceImplTest` 中有一段业务代码捕获后记录的 NPE 栈日志，但测试结果为 0 failures / 0 errors。 - -### 后端 compile - -```bash -cd /Volumes/Dpan/github/water-workspace/worktrees/backend-revenue-bugfix-clear-scope -mvn -pl sw-business/sw-business-server -DskipTests compile -``` - -结果：通过。 - -- Maven 结果：`BUILD SUCCESS` - -### 前端 contract test - -```bash -cd /Volumes/Dpan/github/water-workspace/worktrees/frontend-revenue-bugfix-clear-scope -node --test tests/revenue-bugs/revenueBugfixClearScope.contract.test.mjs -``` - -结果：通过。 - -- Node test 汇总：`tests 5`, `pass 5`, `fail 0` - -### 前端 settings contract regression - -```bash -cd /Volumes/Dpan/github/water-workspace/worktrees/frontend-revenue-bugfix-clear-scope -node --test tests/settings/priceTemplateAdjustmentErrorHandling.test.mjs -``` - -结果：通过。 - -- Node test 汇总：`tests 3`, `pass 3`, `fail 0` - -### 前端 type check - -```bash -pnpm ts:check -``` - -结果：未完成，不作为通过项。 - -- 首次执行长时间无诊断输出后以 `[ELIFECYCLE] Command failed.` 退出。 -- 随后按用户明确指令停止继续运行 `vue-tsc` / `pnpm ts:check`。 -- 已终止残留 `vue-tsc` 进程。 - -### 前端 build - -```bash -cd /Volumes/Dpan/github/water-workspace/worktrees/frontend-revenue-bugfix-clear-scope -pnpm build:dev -``` - -结果：通过。 - -- 输出：`Build successful. Please see dist directory` -- 备注：构建期间存在既有 Vite CJS deprecation warning、SVG icon symbolId warning、Rollup PURE annotation warning。 - -## 备注 - -- 前端 worktree 中存在未跟踪 `test-results/*.png` 截图产物，本次未提交。 -- 本轮未处理 #70 和 #9。#70 需抓包确认提交字段；#9 需产品确认抄表状态规则。 diff --git a/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md b/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md index 99a59ea..4d8f6d1 100644 --- a/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md +++ b/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md @@ -328,7 +328,7 @@ REV-004 先统一账务状态、留痕、原交易校验口径 - `specs/001-rev004-accounting/` - `specs/002-rev005-invoice-flow/` -- `specs/003-rev006-reminder-event-design/` +- `specs/003-rev003-rev006-reminder-event-design/` - `specs/004-rev007-revenue-statistics-design/` - `docs/design/00_Management/01_Project_Progress.md` - `docs/design/00_Management/03_Task_Checklist.md` diff --git a/docs/superpowers/plans/2026-06-08-arrearage-reminder-frontend.md b/docs/superpowers/plans/2026-06-08-arrearage-reminder-frontend.md new file mode 100644 index 0000000..e4bab19 --- /dev/null +++ b/docs/superpowers/plans/2026-06-08-arrearage-reminder-frontend.md @@ -0,0 +1,626 @@ +# 催缴登记 (Arrearage Reminder) 前端对接 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 将两个前端页面（欠费催缴池 + 催缴记录）从 mock 数据切换到真实后端 API，包括 API 层补齐、催缴表单对接、汇总统计、导出功能。 + +**Architecture:** 后端 9 个接口均已就绪 (`POST /create`, `GET /page`, `GET /pending-page`, `GET /get`, `GET /detail-list`, `POST /batch-create`, `GET /pending-summary`, `GET /pending-export`, `GET /pending-detail-export`)。前端按 "API 层 → 催缴表单 → 欠费池页面 → 催缴记录页面" 的顺序逐层对接，每层完成后可独立验证。 + +**Tech Stack:** Vue 3, TypeScript, Element Plus, Axios (`@/config/axios`), pnpm + +--- + +## File Structure + +### API layer +- Modify: `../water-frontend/src/api/collectionManage/arrears/index.ts` + - 新增所有请求/响应 VO 类型 + 7 个缺失的 API 方法 + +### Components +- Modify: `../water-frontend/src/views/collectionManage/arrears/components/RemindForm.vue` + - 对接 `batchCreate` API，接收父组件传入的选中行数据 + +### Views +- Modify: `../water-frontend/src/views/collectionManage/arrears/index.vue` + - 汇总统计条对接 `getPendingSummary`、导出对接 `getPendingExportList`、催缴按钮传递选中数据给 RemindForm +- Modify: `../water-frontend/src/views/collectionManage/collectionRecord/index.vue` + - 列表对接 `getPage`、详情展开对接 `getDetailList`、导出对接后端（如有对应接口） + - 查询表单字段对齐 `ArrearageReminderPageReqVO` + +--- + +### Task 1: 补齐 API 层 — 类型定义与全部接口方法 + +**Files:** +- Modify: `../water-frontend/src/api/collectionManage/arrears/index.ts` + +- [ ] **Step 1: 添加所有 VO 类型定义和 API 方法** + +```typescript +import request from '@/config/axios' +import download from '@/utils/download' + +// ========== 请求 VO ========== + +export interface ArrearagePendingPageReqVO { + pageNo: number + pageSize: number + deptId?: number + code?: string + name?: string + address?: string + mobile?: string + custStates?: number[] + custType?: number + billMonthStart?: number + billMonthEnd?: number + meterReaderId?: number + bookCode?: string + arrearsCountMin?: number + arrearsCountMax?: number + arrearsAmountMin?: number + arrearsAmountMax?: number + remindFilter?: string +} + +export interface ArrearageReminderPageReqVO { + pageNo: number + pageSize: number + custId?: number + reminderUser?: string + reminderType?: number + reminderReason?: number + reminderResult?: number +} + +export interface ArrearageReminderCreateReqVO { + custId: number + chargeIds: number[] + reminderType: number + reminderReason: number + reminderResult: number + reminderUser: string + reminderTemplate?: number + remark?: string +} + +export interface ArrearageReminderBatchCreateReqVO { + customers: { + custId: number + chargeIds: number[] + }[] + reminderType: number + reminderReason: number + reminderResult: number + reminderUser: string + reminderTemplate?: number + remark?: string +} + +// ========== 响应 VO ========== + +export interface ArrearagePendingPageRespVO { + custId: number + custCode: string + custName: string + custAddress: string + meterCaliber: string + waterNature: string + arrearsCount: number + waterVolume: number + totalAmount: number + penaltyAmount: number + receivableAmount: number + billAmount: number + accountMonthRange: string + custStatus: string + prestoreAmount: number + mobile: string + isRemindedThisMonth: boolean + agreementNo: string + contractNo: string + details: ArrearagePendingChargeDetailRespVO[] +} + +export interface ArrearagePendingChargeDetailRespVO { + chargeId: number + billMonth: string + lastReading: number + currentReading: number + waterVolume: number + billAmount: number + penaltyAmount: number + readingDate: string +} + +export interface ArrearagePendingSummaryRespVO { + custCount: number + arrearsCount: number + waterVolume: number + billAmount: number + penaltyAmount: number + totalAmount: number + receivableAmount: number +} + +export interface ArrearageReminderPageRespVO { + id: number + custId: number + custCode: string + custName: string + reminderType: number + reminderReason: number + reminderUser: string + remark: string + reminderTemplate: number + completeTime: string + pushState: number + pushResults: string + reminderResult: number + batchStamp: string + totalBillWater: number + totalExtendedAmount: number + totalLateFee: number + deposit: number + mobile: string + createTime: string + updateTime: string +} + +export interface ArrearageReminderRespVO extends ArrearageReminderPageRespVO {} + +export interface ArrearageReminderDetailRespVO { + id: number + arrearageReminderId: number + chargeId: number + lateFee: number + createTime: string + updateTime: string +} + +export interface ArrearageReminderCreateRespVO { + id: number + detailCount: number +} + +export interface ArrearageReminderBatchCreateRespVO { + successCount: number + failCount: number + successItems: { custId: number; reminderId: number; detailCount: number }[] + failItems: { custId: number; reason: string }[] +} + +// ========== API 方法 ========== + +export const ArrearsApi = { + // 待催欠费池 + getPendingPage: async (params: ArrearagePendingPageReqVO) => { + return await request.get<{ list: ArrearagePendingPageRespVO[]; total: number }>({ + url: '/business/arrearage-reminder/pending-page', + params + }) + }, + + getPendingSummary: async (params: ArrearagePendingPageReqVO) => { + return await request.get({ + url: '/business/arrearage-reminder/pending-summary', + params + }) + }, + + // 催缴登记 CRUD + create: async (data: ArrearageReminderCreateReqVO) => { + return await request.post({ + url: '/business/arrearage-reminder/create', + data + }) + }, + + batchCreate: async (data: ArrearageReminderBatchCreateReqVO) => { + return await request.post({ + url: '/business/arrearage-reminder/batch-create', + data + }) + }, + + getPage: async (params: ArrearageReminderPageReqVO) => { + return await request.get<{ list: ArrearageReminderPageRespVO[]; total: number }>({ + url: '/business/arrearage-reminder/page', + params + }) + }, + + get: async (id: number) => { + return await request.get({ + url: '/business/arrearage-reminder/get', + params: { id } + }) + }, + + getDetailList: async (reminderId: number) => { + return await request.get({ + url: '/business/arrearage-reminder/detail-list', + params: { reminderId } + }) + }, + + // 导出 + exportPending: async (params: ArrearagePendingPageReqVO) => { + const res = await request.download({ + url: '/business/arrearage-reminder/pending-export', + params + }) + download.response(res, '待催欠费客户.xlsx') + }, + + exportPendingDetail: async (params: ArrearagePendingPageReqVO) => { + const res = await request.download({ + url: '/business/arrearage-reminder/pending-detail-export', + params + }) + download.response(res, '待催欠费明细.xlsx') + } +} +``` + +- [ ] **Step 2: 验证 API 层编译** + +Run: `cd ../water-frontend && npx vue-tsc --noEmit src/api/collectionManage/arrears/index.ts 2>&1 | head -20` +Expected: No type errors + +--- + +### Task 2: RemindForm 对接 batchCreate API + +**Files:** +- Modify: `../water-frontend/src/views/collectionManage/arrears/components/RemindForm.vue` + +- [ ] **Step 1: 重写 RemindForm 脚本，接收选中行 props 并调 batchCreate** + +将 `