tangweijie 3eccab2cf9 docs: 文档治理统一 — AGENTS.md 生命周期规则 + 模块归档 + DDL 修正

1. AGENTS.md 更新
   - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节
   - water-backend: 更新协作引用（建设期/建成后、evidence 模块化）

2. specs/ 重复合并
   - 006-reminder-event-design 合并入 003-rev006-reminder-event-design
   - 001-rev004-accounting 删除冗余 data-model.md + contracts/
   - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/

3. evidence 按模块归档
   - 35 个 REV-004 文件归入 evidence/rev004-accounting/
   - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/
   - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录

4. guides/ 清理
   - 14 个 REV004_*.md 移入 evidence/rev004-accounting/

5. 遗留文件处理
   - docs/research/ 归档到 Archive/06_Migration_Plans/
   - backend-check detached worktrees 清理

6. 交叉引用修复
   - 006-reminder-event-design → 003-rev006-reminder-event-design
   - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_

7. DB 设计文档修正（01_Database_Design.md）
   - biz_invoice 明确为开票配置表，非发票记录表
   - 新增 biz_invoice_record 为发票申请/结果主表
   - 新增 biz_charge_invoice_rel 账单-发票关联说明
   - REV-005 承接口径表名全部修正

8. 发票审计证据
   - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md

2026-06-16 11:47:16 +08:00

14 KiB

Raw Blame History

AGENTS.md

Workspace Coordination

本仓库现在是 water-workspace 下的文档总控仓，默认作为正式规格、计划、任务、验收与治理台账的单一入口。

邻接仓库

../water-backend/：后端实现仓，默认主开发分支为 develop
../water-frontend/：前端实现仓，默认主开发分支为 develop

启动规则

需要运行 /speckit.specify、/speckit.plan、/speckit.tasks、正式文档修订、治理台账更新、验收结论汇总时，必须从 water-docs 根目录启动代理。
需要检查正式规格、计划、任务、基线、evidence 时，以 water-docs/specs/ 与 water-docs/docs/ 为准。
未经用户明确要求，不在本仓库直接修改 ../water-backend/ 或 ../water-frontend/ 中的业务代码。

多仓协作规则

本仓库中的 .specify/ 是唯一正式流程入口，backend/frontend 不复制第二套 .specify/。
backend/frontend 仓内实现结论，必须回写到本仓库的正式文档或 specs/ 工件，不能仅停留在代码仓口头说明。
重要 feature 默认记录代码基线：
- backend commit SHA
- frontend commit SHA
- 验证日期

Worktree 约定

推荐在 ../worktrees/ 下按 feature 建立平铺 worktree：
- docs-<feature>
- backend-<feature>
- frontend-<feature>
- verify-<feature>
文档 lane 只改 water-docs
backend lane 只改 water-backend
frontend lane 只改 water-frontend
verify lane 负责样本、日志、验收结论和基线固定

specs/ 与 docs/design/ 生命周期

本仓库维护两套文档体系，有明确的「一次性 ↔ 持续维护」分工。

specs/ — 过程工件（建设期蓝图，建成后封存）

specs/<编号>-<feature>/ 是 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 类代理）在本仓库中的工作方式。

项目定位

本仓库是 福建水务营收系统 的技术文档仓库，目标是形成可直接用于评审、交付与实施参考的设计资料。

当前工作重点不是编写业务代码，而是维护和优化文档体系。

在未被用户明确要求的情况下，优先执行以下工作：

优化现有 Markdown 设计文档
对齐概要设计、详细设计、数据库设计、接口设计之间的口径
校正章节结构、术语、编号、图表、引用路径和归档关系
基于现有资料补全文档，不随意臆造业务规则或技术细节

仓库结构

/
├── 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/                             # 辅助基础设施

当前文档组织原则

主文档优先

优先维护以下主文档，不要轻易再创建新的平行版本：

docs/design/01_Overview/03_Summary_Design.md：概要设计主文档
docs/design/02_Detailed_Design/01_Detailed_Design.md：详细设计主文档
docs/design/03_Technical_Design/01_Database_Design.md：数据库设计主文档
docs/design/03_Technical_Design/03_Interface_Design.md：接口设计主文档
docs/design/03_Technical_Design/04_Security_Design.md：安全设计主文档
docs/design/03_Technical_Design/05_Deployment_Design.md：部署设计主文档

如果已有主文档可以承载内容，优先编辑现有文件，而不是新增"新-xxx""最终版""修订版"之类文件。

Archive 仅作归档

docs/design/04_Appendix/Archive/ 下的内容默认视为历史资料、原始附件、操作手册或数据字典来源：

可引用
可核对
可整理路径
不作为新的正式交付主稿直接编辑替代，除非用户明确要求

图片与附件成组维护

移动或重构归档资料时，必须同时检查：

同名 Markdown 与 _images/ 目录是否一起迁移
图片相对路径是否仍然有效
文档中的内部链接是否需要同步修正

工作前必做检查

在修改任何正式文档前，优先查看：

docs/design/00_Management/01_Project_Progress.md
docs/design/00_Management/02_Delivery_Standards.md
docs/design/00_Management/03_Task_Checklist.md
与本次任务直接相关的目标文档

如果任务涉及结构性调整，还应同步查看：

docs/design/00_Management/04_Writing_Guide.md
docs/guides/ 下相关说明

文档编写与修改规则

语言与风格

全部正式文档内容使用中文
技术名词、框架名、代码标识符保留原文
风格要求专业、克制、可交付，避免口语化和宣传化表述
不写与当前项目无关的泛化模板内容

以"对齐现状"为第一原则

所有修改必须优先对齐以下事实来源：

当前仓库中的正式设计文档
docs/design/04_Appendix/Archive/ 中的需求、手册、历史设计、数据字典
docs/guides/BACKEND_CURRENT_STATUS.md
docs/guides/BACKEND_TABLE_MAPPING.md
用户在对话中明确给出的最新口径

如果多个来源冲突，处理优先级通常为：

用户当前明确要求
当前主文档既有统一口径
最新整理后的映射/指南文档
Archive 历史资料

如发现冲突且无法自行判定，应先说明冲突点，再继续修改。

不要过度发挥

不要凭空补充不存在的子系统、模块、接口、表
不要为了"显得完整"加入大量无依据的实现细节
不要默认加入大段代码示例、部署脚本、DDL、伪代码，除非用户明确要求
不要创建多余术语体系；优先沿用仓库现有命名

保持文档层级匹配

不同层级文档应保持抽象粒度一致：

概要设计：讲清结构、边界、模块职责、关键接口与部署原则
详细设计：讲清模块职责、流程、数据、接口、规则、约束
技术专项：按数据库、接口、安全、部署等主题展开，不与主文档冲突

不要把详细设计内容硬塞进概要设计，也不要把概要性表述替代详细设计。

关键一致性约束

项目名称

统一使用：

福建水务营收系统

除引用原始资料外，不要混用"营业收费系统""数智营收管理系统""客户服务平台"等作为正式系统名称。

数据库口径

若当前正式文档已统一到国产数据库方案，应优先保持与主文档一致；发现历史文档残留旧口径时，应按正式主文档修正，而不是反向改回历史版本。

模块编号与接口编号

涉及编号时遵循现有正式文档口径：

模块编号与接口编号必须可区分
接口编号优先采用带 IF- 前缀的形式
不擅自发明新的编号规则
修改某一处编号时，要检查同文档相关表格、目录、图表、正文描述是否同步

图表规范

所有正式图表优先使用 Mermaid
图表必须与正文一致，不能"图一套、文一套"
Mermaid 节点命名尽量避免容易导致解析异常的写法
调整图表时，同时检查导出可用性和可读性

引用与链接

仓库内文档使用相对路径
修改目录后应同步修复引用
若引用 Archive 内容，尽量引用整理后的稳定路径

修改策略

适合直接修改的情形

术语统一
标题结构优化
章节顺序调整
表格字段对齐
图表与正文一致性修复
历史路径修复
主文档补充遗漏内容

需要先谨慎核对的情形

子系统拆分或合并
模块编号体系变更
数据库选型口径变化
大规模改写接口定义
归档目录重构
删除已有正式内容

遇到上述改动时，应先阅读相关文档上下文，避免只改一处导致全仓库不一致。

Markdown 与 Marksman 工作流说明

本仓库的 Markdown 编辑与交叉引用检查可配合 Marksman 使用，以提升标题跳转、链接补全、引用检查与重命名体验。

适用场景

维护多篇 Markdown 设计文档之间的相对链接
检查标题锚点、文内链接、跨文档引用是否有效
在编辑器内进行标题跳转、引用查找与重命名
维护以仓库根目录为工作区的文档导航体验

工作区约定

仓库根目录中的 .marksman.toml 用于标记 Marksman 工作区根
如需稳定的跨文档能力，应从仓库根目录打开项目
Markdown 文档应优先使用相对路径链接，并保持标题命名稳定

代理协作要求

当任务涉及 Markdown 链接修复、标题锚点检查、跨文档引用核对时，优先结合 Marksman 能力开展排查
若本机已安装 marksman，可直接用于工作区检查与编辑器集成
若本机未安装 marksman，应明确提示安装要求，而不是假设相关能力已经存在
如需环境自检，可优先使用仓库脚本：scripts/check-marksman.sh

安装建议

macOS：brew install marksman
Rust：cargo install marksman

使用提示

命令行查看帮助：marksman --help
作为语言服务运行：marksman server
若 macOS 阻止二进制运行，可执行： xattr -d com.apple.quarantine "$(command -v marksman)"

编辑器说明

Zed 项目配置可通过 .zed/settings.json 为 Markdown 启用 Marksman
若编辑器未正确识别工作区，优先确认仓库根目录存在 .marksman.toml

常用工作命令

make help
make validate
make validate-file FILE=<filename>
make check-mermaid
make validate-mermaid
make check-links
make export-word
make export-pdf
make export-html
make unified-export
npm run check:marksman
npm run marksman:help
npm run marksman:server

如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。

修改后必须做的事

每次完成正式文档修改后，至少执行以下动作中的适用项：

检查目标文档内容是否与上下文一致
检查相关图表、目录、表格、交叉引用是否同步
如属于正式文档的重要修改，更新 docs/design/00_Management/01_Project_Progress.md 的变更记录
如属于明确任务项完成，可同步更新 docs/design/00_Management/03_Task_Checklist.md

对通用代码代理的具体要求

你在本项目中应优先表现为：

文档架构师
一致性审校者
归档整理与信息整编助手
基于现有资料进行保守补完的编辑者

而不是：

擅自扩展需求的产品经理
无依据发明实现细节的方案生成器
动辄新建文件的"版本制造机"

最终目标

确保仓库中的正式文档满足以下要求：

结构清晰
术语统一
图文一致
可追溯到来源资料
满足甲方交付语境
便于后续继续维护、评审与导出

14 KiB Raw Blame History Unescape Escape