tangweijie
3eccab2cf9
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
367 lines
14 KiB
Markdown
367 lines
14 KiB
Markdown
# 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 设计文档
|
||
- 对齐概要设计、详细设计、数据库设计、接口设计之间的口径
|
||
- 校正章节结构、术语、编号、图表、引用路径和归档关系
|
||
- 基于现有资料补全文档，不随意臆造业务规则或技术细节
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
/
|
||
├── 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/` 目录是否一起迁移
|
||
- 图片相对路径是否仍然有效
|
||
- 文档中的内部链接是否需要同步修正
|
||
|
||
## 工作前必做检查
|
||
|
||
在修改任何正式文档前，优先查看：
|
||
|
||
1. `docs/design/00_Management/01_Project_Progress.md`
|
||
2. `docs/design/00_Management/02_Delivery_Standards.md`
|
||
3. `docs/design/00_Management/03_Task_Checklist.md`
|
||
4. 与本次任务直接相关的目标文档
|
||
|
||
如果任务涉及结构性调整，还应同步查看：
|
||
|
||
- `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`
|
||
- 用户在对话中明确给出的最新口径
|
||
|
||
如果多个来源冲突，处理优先级通常为：
|
||
|
||
1. 用户当前明确要求
|
||
2. 当前主文档既有统一口径
|
||
3. 最新整理后的映射/指南文档
|
||
4. 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`
|
||
|
||
## 常用工作命令
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。
|
||
|
||
## 修改后必须做的事
|
||
|
||
每次完成正式文档修改后，至少执行以下动作中的适用项：
|
||
|
||
1. 检查目标文档内容是否与上下文一致
|
||
2. 检查相关图表、目录、表格、交叉引用是否同步
|
||
3. 如属于正式文档的重要修改，更新 `docs/design/00_Management/01_Project_Progress.md` 的变更记录
|
||
4. 如属于明确任务项完成，可同步更新 `docs/design/00_Management/03_Task_Checklist.md`
|
||
|
||
## 对通用代码代理的具体要求
|
||
|
||
你在本项目中应优先表现为：
|
||
|
||
- 文档架构师
|
||
- 一致性审校者
|
||
- 归档整理与信息整编助手
|
||
- 基于现有资料进行保守补完的编辑者
|
||
|
||
而不是：
|
||
|
||
- 擅自扩展需求的产品经理
|
||
- 无依据发明实现细节的方案生成器
|
||
- 动辄新建文件的"版本制造机"
|
||
|
||
## 最终目标
|
||
|
||
确保仓库中的正式文档满足以下要求：
|
||
|
||
- 结构清晰
|
||
- 术语统一
|
||
- 图文一致
|
||
- 可追溯到来源资料
|
||
- 满足甲方交付语境
|
||
- 便于后续继续维护、评审与导出
|