tangweijie
aba7071723
将项目约束正式落到 .specify/memory/constitution.md，并同步更新 plan、spec、tasks、checklist、agent 模板，使 Speckit 工作流默认遵循文档单一真源、范围收敛、Archive 隔离与校验闭环。
101 lines
7.5 KiB
Markdown
101 lines
7.5 KiB
Markdown
<!--
|
||
Sync Impact Report
|
||
Version change: template -> 1.0.0
|
||
Modified principles:
|
||
- 模板占位原则 1 -> I. 主文档单一真源
|
||
- 模板占位原则 2 -> II. 范围交集优先
|
||
- 模板占位原则 3 -> III. Archive 隔离与可追溯
|
||
- 模板占位原则 4 -> IV. 一致性优先于扩写
|
||
- 模板占位原则 5 -> V. 校验与台账闭环
|
||
Added sections:
|
||
- 文档与资料约束
|
||
- 执行流程与质量门禁
|
||
Removed sections:
|
||
- 无
|
||
Templates requiring updates:
|
||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/plan-template.md
|
||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/spec-template.md
|
||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/tasks-template.md
|
||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/checklist-template.md
|
||
- ✅ updated /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/agent-file-template.md
|
||
- ✅ checked /Volumes/Dpan/github/fujian_water_biz_doc/.specify/templates/constitution-template.md
|
||
- ✅ checked /Volumes/Dpan/github/fujian_water_biz_doc/README.md
|
||
- ✅ checked /Volumes/Dpan/github/fujian_water_biz_doc/AGENTS.md
|
||
Follow-up TODOs:
|
||
- `.specify/templates/commands/` 目录不存在，本次无命令模板需要同步。
|
||
-->
|
||
# 福建水务营收系统 Constitution
|
||
|
||
## Core Principles
|
||
|
||
### I. 主文档单一真源
|
||
正式内容 MUST 优先落在既有主文档中维护：`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`。若既有主文档可以承载内容，任何规格、计划、任务或实施说明 MUST 引导回主文档修订，不得默认创建“新版本”“最终版”“修订版”等平行正式稿。
|
||
|
||
Rationale：本仓库的首要目标是形成可评审、可交付、可持续维护的正式文档体系；平行稿会直接破坏单一真源。
|
||
|
||
### II. 范围交集优先
|
||
新增或补完的功能、模块、接口、外部系统与约束 MUST 先落在当前范围基线内。范围判断 MUST 以 `docs/design/01_Overview/03_Summary_Design.md` 与 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 的交集收敛：两者均覆盖可直接推进；仅一方覆盖 MUST 标记“需确认”；两者均未覆盖 MUST 视为超范围并停止扩写。
|
||
|
||
Rationale：当前项目以“对齐既有设计、保守补完”为主，不以新需求发散为目标。
|
||
|
||
### III. Archive 隔离与可追溯
|
||
`docs/design/04_Appendix/Archive/` MUST 作为来源、核对与归档区使用，默认不作为正式主稿直接改写替代。引用 Archive 内容时 MUST 回写到 P0/P1 正式文档后再作为正式结论输出。迁移归档资料时，Markdown 文件与同名 `_images/` 目录 MUST 成组维护，引用路径 MUST 同步修复，来源关系 MUST 可追溯。
|
||
|
||
Rationale：Archive 的价值在于追溯与核对，而不是替代正式交付口径。
|
||
|
||
### IV. 一致性优先于扩写
|
||
所有修改 MUST 优先保证系统名称、数据库口径、模块编号、接口编号、图表、链接和术语的一致性。正式系统名称 MUST 使用“福建水务营收系统”；接口编号 MUST 与模块编号区分并优先采用 `IF-` 前缀；图表 MUST 优先使用 Mermaid 并与正文一致；仓库内引用 MUST 使用相对路径。无依据时 MUST 先修正结构和一致性，不得为了“完整”而臆造实现细节、代码、DDL 或伪代码。
|
||
|
||
Rationale：对当前仓库而言，不一致比不完整更容易导致评审和实施偏差。
|
||
|
||
### V. 校验与台账闭环
|
||
每次正式文档变更后 MUST 执行与改动范围匹配的最小校验，并在适用时回写管理台账。单文件修订至少 MUST 执行 `make validate-file FILE=<目标文件>`；涉及链接、目录或跨文档引用时 MUST 执行 `make check-links`；涉及图表时 MUST 执行 `make validate-mermaid`；重要治理或结构变更 MUST 更新 `docs/design/00_Management/01_Project_Progress.md`，明确任务完成时 SHOULD 同步更新 `docs/design/00_Management/03_Task_Checklist.md`。
|
||
|
||
Rationale：本仓库的交付价值依赖“文档可读 + 链接有效 + 图文一致 + 台账可追踪”的闭环，而不是仅完成局部文字编辑。
|
||
|
||
## 文档与资料约束
|
||
|
||
- 正式文档内容 MUST 使用中文；技术术语、框架名、代码标识符可保留原文。
|
||
- 文档层级 MUST 与抽象粒度匹配：概要设计讲边界与结构，详细设计讲流程/规则/接口/数据，技术专项讲数据库/接口/安全/部署等专题。
|
||
- Speckit 产物若用于本仓库，MUST 默认把“文档修订”视为交付对象，而非默认生成软件代码结构。
|
||
- 需求、计划、任务、检查清单 MUST 明确来源文档、影响文档、验收方式与是否涉及台账更新。
|
||
- 未经用户明确要求，规格与计划 MUST 避免把实现代码、数据库脚本、部署脚本、压测指标或测试细节写成默认必交付项。
|
||
|
||
## 执行流程与质量门禁
|
||
|
||
1. 开始任何正式文档任务前，执行者 MUST 先阅读：
|
||
- `docs/design/00_Management/01_Project_Progress.md`
|
||
- `docs/design/00_Management/02_Delivery_Standards.md`
|
||
- `docs/design/00_Management/03_Task_Checklist.md`
|
||
- 与任务直接相关的目标文档
|
||
2. 结构性调整任务还 MUST 额外阅读：
|
||
- `docs/design/00_Management/04_Writing_Guide.md`
|
||
- `docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`
|
||
- `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`
|
||
- `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`
|
||
3. 计划文档 MUST 在“Constitution Check”中显式检查：主文档归属、范围基线、Archive 使用方式、一致性影响、校验与台账动作。
|
||
4. 任务文档 MUST 将“目标文档修订”“链接/图表校验”“台账同步”列为显式任务，而不是隐含工作。
|
||
5. 质量门禁最低要求 MUST 满足：断链数量为 0、Mermaid 语法错误为 0、平行正式稿新增数量为 0、关键口径冲突数量为 0。
|
||
|
||
## Governance
|
||
|
||
本 Constitution 高于 `.specify/` 下其他模板中的默认假设；若模板、计划或任务与本 Constitution 冲突，MUST 以本 Constitution 为准并同步修订模板。
|
||
|
||
修订流程如下：
|
||
1. 先基于当前主文档、治理文档与必要的 Archive 来源形成修订草案。
|
||
2. 在修订草案中明确版本变更类型，并说明是 MAJOR、MINOR 还是 PATCH 及其依据。
|
||
3. 同步检查 `.specify/templates/`、`README.md`、`AGENTS.md` 及相关运行指导文档是否仍与宪法一致；若不一致，MUST 在同一轮修订中更新或显式记录 pending 项。
|
||
4. 所有规格、计划、任务与检查清单在生成或更新时 MUST 执行一次合规复核，确认满足五项核心原则。
|
||
|
||
版本策略如下：
|
||
- MAJOR：移除核心原则、重定义治理边界、改变单一真源或范围控制方式。
|
||
- MINOR：新增原则、增加新的强制门禁或新增治理章节。
|
||
- PATCH：纯措辞澄清、错别字修正、非语义调整。
|
||
|
||
合规复核要求如下：
|
||
- 每份计划 MUST 记录 Constitution Check。
|
||
- 每份任务清单 MUST 能映射到目标文档、校验动作与台账动作。
|
||
- 每次重要变更完成后 MUST 在结果摘要中说明修改文件、校验结果、剩余风险与后续建议。
|
||
|
||
**Version**: 1.0.0 | **Ratified**: 2026-03-13 | **Last Amended**: 2026-03-13
|