全新项目启动与交付基线（通用版） 链接到标题

1. 文档定位 链接到标题

本文适用于以下场景：

• 从零建设一个新产品或新系统；
• 将原型、脚本、人工流程或验证版升级为正式系统；
• 多个前后端应用、异步任务、外部数据源共同参与的复杂项目；
• 对正确性、可追溯性、性能或发布稳定性有明确要求的项目；
• 包含规则引擎、算法、AI、大模型或其他非确定性执行单元的项目。

本文不是一套要求“先写完所有文档再编码”的瀑布流程。它只要求在正式开发前，冻结那些一旦变更就会引发跨模块、跨应用或跨数据层返工的高耦合决策；其余细节应通过最小垂直切片快速验证和迭代。

本文中的约束级别：

• 必须：不满足时不得进入下一阶段；
• 应当：默认执行，确有理由不执行时需要记录决策；
• 可选：根据项目规模、风险和成本选择。

2. 核心原则 链接到标题

2.1 少写说明文档，多建立可执行合同 链接到标题

架构图和说明文档只能帮助理解，不能保证实现一致。关键约束应尽量转化为可以被工具验证的合同：

• 产品验收矩阵；
• 领域状态迁移测试；
• OpenAPI、RPC IDL 或消息 Schema；
• DDL、数据字典和 Schema Version；
• 错误码和失败分类；
• Golden Dataset 或确定性验收样本；
• 性能预算和容量阈值；
• CI、集成测试和发布门禁。

2.2 先冻结高耦合决策，再实现最小闭环 链接到标题

编码前不需要确定所有页面细节和内部实现，但必须明确：

1. 系统解决什么问题，不解决什么问题；
2. 每个核心概念的含义和不变量；
3. 应用与模块的职责边界；
4. 接口、事件、状态和数据的权威合同；
5. 正确结果如何判断；
6. 生产容量、延迟、成本和可用性约束；
7. 第一条端到端链路如何验收。

随后只实现一条最小但真实的垂直链路，即 Walking Skeleton，再逐步扩展覆盖面。

2.3 业务结果与技术执行状态必须分离 链接到标题

系统必须区分：

• 业务判断结果，例如通过、不通过、不可判定；
• 技术执行状态，例如成功、失败、跳过、超时；
• 规则适用性，例如适用、不适用、条件不足；
• 流程状态，例如待执行、运行中、已完成、部分失败、已取消。

禁止用业务上的“无问题”掩盖技术执行失败，也禁止因为技术执行完成就直接认定业务处理成功。

2.4 默认选择少量部署单元和清晰模块边界 链接到标题

全新项目不等于必须拆分大量微服务。默认建议采用模块化单体或少量部署组，通过模块、端口和依赖规则保证边界。

只有满足以下条件之一时，才考虑拆出新的独立部署单元：

• 需要独立扩缩容；
• 存在明确的安全或网络边界；
• 由不同团队独立发布和维护；
• 资源模型明显不同；
• 故障隔离收益能够覆盖部署复杂度。

2.5 并行化实现不能并行化事实源 链接到标题

适合并行的工作：

• 只读审计；
• 独立模块实现；
• 测试补充；
• 文档和数据核对；
• 不共享合同的页面或适配器。

不适合无协调并行的工作：

• DDL 和领域模型；
• 公共 API 和消息协议；
• 状态机；
• 核心算法或规则合同；
• 公共组件和跨应用基础类；
• 初始化数据和版本迁移。

这些内容必须指定唯一负责人、变更顺序和集成验证人。

3. 最小项目基线包 链接到标题

一个新项目在正式开发前，应至少产出以下七类内容。内容可以很短，但必须明确、版本化并有负责人。

docs/
  00-project-charter.md           # 项目目标、范围、非目标、成功指标
  01-domain-contract.md           # 领域词典、不变量、状态机
  02-system-context.md            # 系统边界、职责矩阵、核心时序
  03-data-and-capacity.md          # 数据分类、ERD、容量与访问模式
  04-acceptance-and-test-plan.md   # 验收矩阵、样本、测试层级和门禁
  05-release-runbook.md            # 环境、发布、回滚和故障处理
  adr/                             # 只记录高影响、难逆转的决策

contracts/
  api/                             # OpenAPI、RPC IDL
  events/                          # MQ/Event Schema
  schemas/                         # 数据、配置或算法输入输出 Schema

项目较小时可以合并文件，但不能省略对应决策。

4. Phase 0：项目启动与范围冻结 链接到标题

4.1 项目章程 链接到标题

项目章程必须回答：

4.2 场景优先级 链接到标题

所有功能按以下方式分层：

• P0 主闭环：没有它，系统没有业务价值；
• P1 完整性：主闭环可用后补齐；
• P2 平台化：配置化、运营化、自动化扩展；
• 明确不做：当前版本不进入设计和实现。

如果 V1 同时包含主业务闭环、运营配置平台、复杂任务调度、动态规则、完整管理后台和多种外部集成，应重新评估它是否仍然属于 MVP。

4.3 权威事实源矩阵 链接到标题

同一类事实只能有一个权威源。其他材料只能引用它，不能复制后独立演进。

4.4 Phase 0 退出条件 链接到标题

• P0 场景和非目标已经确认；
• 成功指标可以被度量；
• 每类事实有且只有一个权威源；
• 所有 P0 歧义已经解决，或明确安排验证实验；
• 产品、技术、质量和发布责任人已经确定。

5. Phase 1：领域、边界与合同冻结 链接到标题

5.1 领域词典 链接到标题

每个核心名词至少定义：

• 唯一名称和业务含义；
• 唯一标识；
• 生命周期；
• 与其他实体的数量关系；
• 创建、修改和终止条件；
• 是否需要版本化；
• 是否属于业务事实、执行状态或派生结果。

应重点消除以下歧义：

• 同一概念多个名称；
• 同一名称多个含义；
• 业务状态和执行状态混用；
• 配置、版本和运行快照混用；
• 错误、异常、问题、缺陷等概念边界不清。

5.2 不变量 链接到标题

不变量是无论经过哪条流程都必须成立的业务约束，例如：

• 发布后的版本不可原地修改；
• 同一幂等键只能产生一个业务结果；
• 每个执行单元最终必须进入唯一终态；
• 技术失败不能被记录为业务成功；
• 派生结果必须能够追溯到输入版本和执行版本；
• 任何状态迁移都必须记录操作者、时间和原因。

不变量应进入测试，而不是只写在说明文档中。

5.3 状态机 链接到标题

每个长流程至少定义：

• 初始状态；
• 合法迁移；
• 终态；
• 超时和租约；
• 重试与最大次数；
• 取消和补偿；
• 并发写入规则；
• 部分失败语义；
• 人工恢复入口。

建议将状态拆成三层：

流程状态：PENDING / RUNNING / SUCCEEDED / PARTIAL_FAILED / FAILED / CANCELLED
执行状态：SUCCESS / ERROR / TIMEOUT / SKIPPED
业务结果：由具体领域定义，例如 PASS / FAIL / NOT_JUDGABLE

5.4 系统边界和职责矩阵 链接到标题

对每个应用或模块记录：

通用推荐架构：

flowchart LR
    Client["客户端"] --> Access["接入层 / BFF"]
    Access --> Control["业务控制面"]
    Control --> Store["事务数据存储"]
    Control --> Outbox["Outbox / 消息队列"]
    Outbox --> Worker["Worker / 数据面"]
    Worker --> Provider["外部数据源或服务"]
    Worker --> Engine["规则、算法或处理引擎"]
    Worker --> Result["结果与审计存储"]
    Result --> Access

该图表达职责关系，不代表必须拆成多个微服务。

5.5 API、事件和错误合同 链接到标题

接口合同至少包含：

• 请求和响应字段语义；
• 必填性、默认值和枚举；
• 幂等键；
• 鉴权上下文和可信字段来源；
• 超时和重试责任方；
• 分页方式；
• 错误码、是否可重试和用户提示；
• 版本兼容期和废弃流程。

长任务应优先采用异步协议：

提交请求 -> 返回 operation_id/task_id -> 查询或订阅进度 -> 获取最终结果

禁止让同步 HTTP 超时承担长任务完成语义。

大数据列表应默认采用“有界过滤条件 + cursor”，谨慎使用总数查询和 offset 深分页。

5.6 Phase 1 退出条件 链接到标题

• 核心领域词典和不变量已确认；
• 所有长流程有状态机；
• 应用和模块职责无重叠或空白；
• P0 API、事件和错误码已经形成机器可读合同；
• 幂等、超时、重试、取消和部分失败语义已经明确；
• 关键合同存在自动化校验。

6. 数据模型与容量基线 链接到标题

6.1 数据分类 链接到标题

所有数据先分类，再决定存储：

6.2 每张表的准入问题 链接到标题

新增表或大字段前必须回答：

1. 谁写入？
2. 谁读取？
3. 读取场景和查询条件是什么？
4. 为什么不能由现有权威数据计算得到？
5. 数据是否重复，哪一份是权威源？
6. 保留多久，如何清理？
7. 日增量和三年规模是多少？
8. 唯一键、分区键和主要索引是什么？
9. 是否需要审计、回放或重算？
10. 删除它会损失什么能力？

如果无法回答读取方和保留策略，默认不新增。

6.3 容量模型 链接到标题

编码前至少估算：

日新增量
峰值 QPS / TPS
单条平均与最大大小
在线保留天数
主查询时间范围
单任务最大处理量
单次批量大小
外部服务限流
计算、存储和第三方调用成本

容量约束必须进入接口和数据模型。例如底层按时间分区时，上层任务和分页协议也必须携带时间范围，不能等到性能优化阶段再补。

6.4 原始数据、快照和派生结果 链接到标题

通用建议：

• 原始大对象优先保存来源指针、哈希和必要元数据；
• 需要重放时保存一份权威快照，不在多张表和多个 JSON 字段重复复制；
• 派生结果记录输入版本、配置版本和执行器版本；
• 明确哪些结果可以覆盖，哪些记录只能追加；
• 清理策略、归档策略和恢复能力必须成对设计。

6.5 数据门禁 链接到标题

• DDL 可以在目标数据库版本上全量初始化；
• Migration 可以从上一版本升级且可验证；
• 数据字典与 DDL 一致；
• 所有大表有容量、分区和清理策略；
• 所有唯一键和幂等键存在数据库级约束；
• 没有无法说明读取方的表和大字段；
• 核心查询有 Explain 或等价执行计划验证。

7. 非功能需求基线 链接到标题

非功能需求不是上线前的“优化项”。会影响接口、状态机和数据结构的约束必须前置。

7.1 性能与成本 链接到标题

至少定义：

• 关键接口 p95、p99；
• 单任务最大耗时；
• 单处理单元最大耗时；
• 目标吞吐；
• 最大并发；
• 外部调用次数和成本预算；
• 扩容后吞吐是否应线性提升；
• 降级时允许损失什么，不允许损失什么。

7.2 可靠性 链接到标题

至少定义：

• 可用性目标；
• RPO、RTO；
• 幂等策略；
• 重试分类；
• 死信或失败队列；
• 租约和失联恢复；
• 对账任务；
• 部分失败和人工恢复。

7.3 可观测性 链接到标题

核心链路应统一携带：

trace_id
request_id / operation_id
task_id / item_id
entity_id
provider_request_id
executor_version

最低指标集：

• 队列等待时间；
• 各阶段 p95、p99；
• 成功、失败、超时、跳过数量；
• 重试和死信数量；
• 外部 Provider 错误率；
• 数据完整率；
• 单任务资源和第三方成本；
• 长时间未推进任务数量；
• 大数据源扫描量和返回量。

日志必须能够回答“在哪一阶段、处理哪个对象、使用哪个版本、因为什么失败”，不能只打印最终异常。

7.4 安全与权限 链接到标题

在不阻塞首个功能闭环的前提下，以下基础约束必须在联调和发布前完成：

• 用户身份只来自可信接入层；
• 服务间使用独立身份；
• 权限按动作设计，不只按页面设计；
• 密钥通过 Secret、密钥系统或受控配置管理；
• 日志、测试报告和会话不得输出密钥、Cookie 和完整敏感数据；
• 数据库 DDL、读、写账号分权；
• 审计记录包含操作者、动作、对象、时间和结果。

8. Phase 2：单条真实链路 Walking Skeleton 链接到标题

8.1 目标 链接到标题

Walking Skeleton 不是 Mock 演示，而是一条真实、可追踪、可重复执行的最小业务闭环：

真实输入
  -> 真实接入接口
  -> 真实业务状态机
  -> 真实存储
  -> 至少一个真实外部依赖或代表性替身
  -> 真实执行
  -> 可查询结果
  -> 用户可见输出

8.2 必须覆盖 链接到标题

• 一条正常路径；
• 一条业务不满足路径；
• 一条技术失败路径；
• 重复提交；
• 超时或重试；
• 状态恢复；
• 全链路 Trace；
• 数据可回查；
• 结果可由验收样本判断。

8.3 退出条件 链接到标题

• 重复执行结果幂等；
• 没有永久停留在中间状态的对象；
• 技术错误不会被记为业务成功；
• 每一步都有结构化日志和指标；
• 输入、配置、执行器和输出版本可追溯；
• 一键执行测试可以重复得到相同结论；
• 失败后存在自动或人工恢复方式。

Walking Skeleton 通过前，不应同时铺开全部页面、规则、Provider 和后台配置能力。

9. Phase 3：代表集、全链路与性能验收 链接到标题

9.1 分层样本 链接到标题

建议建立三层样本：

样本必须版本化，记录来源、输入快照、预期结果、允许误差和变更原因。

9.2 测试层级 链接到标题

静态检查和模块边界
  -> 单元测试
  -> 状态机与合同测试
  -> 数据库和外部适配器集成测试
  -> 单条 Walking Skeleton
  -> 代表集端到端测试
  -> 浏览器产品验收
  -> 性能、容量和故障注入
  -> 发布集回归

9.3 全链路成功的定义 链接到标题

禁止只用 HTTP 200、任务完成或进程退出码判断成功。全链路验收至少校验：

• 流程终态正确；
• 所有适用执行单元都有唯一结果；
• 没有隐藏的 Provider、脚本或异步消费错误；
• 必填上下文完整；
• 数据库行数、唯一性和状态守恒正确；
• 业务结果与预期一致；
• 错误分类和 reason_code 正确；
• 耗时、吞吐和成本在预算内；
• 日志、指标和审计完整。

9.4 测试环境要求 链接到标题

• 测试数据库必须可重复初始化；
• 每次执行使用干净数据集或唯一运行隔离标识；
• 测试依赖缺失必须失败，禁止静默跳过核心合同；
• Mock 只用于单元测试，发布验收使用真实依赖或经过证明的高保真替身；
• 测试脚本与运行期脚本必须分目录管理；
• 测试报告应机器可读，并能阻断 CI 或发布。

10. Phase 4：发布与运行门禁 链接到标题

10.1 发布前检查 链接到标题

• P0 产品验收全部通过；
• API 和消息消费者合同测试通过；
• DDL/Migration 已在目标数据库验证；
• 代表集和发布集通过；
• 无隐藏失败和异常中间状态；
• 性能、容量和成本满足预算；
• 配置差异已审查；
• 告警、看板和对账任务已就绪；
• 灰度和回滚方案已演练；
• 三端或多应用版本兼容矩阵已确认；
• 发布负责人和观察窗口已明确。

10.2 多仓库发布清单 链接到标题

跨仓库项目应使用同一份发布 Manifest：

release_id: example-v1
contracts_version: v1
database_schema_version: 202601010001
applications:
  - name: frontend
    branch: feature/example-v1
    commit: <commit>
  - name: backend
    branch: feature/example-v1
    commit: <commit>
  - name: worker
    branch: feature/example-v1
    commit: <commit>
acceptance_report: <artifact>
rollback_runbook: <artifact>

示例只表达结构，真实 Manifest 不应存放密钥。

10.3 发布后的观察 链接到标题

发布后必须关注：

• 新版本请求量和错误率；
• 队列积压和任务停滞；
• 数据库扫描量、慢查询和容量增长；
• 外部 Provider 错误率；
• 业务结果分布是否突变；
• 新旧版本结果差异；
• 人工反馈和回滚触发条件。

11. 变更治理 链接到标题

11.1 冻结不等于禁止变更 链接到标题

需求和架构可以变化，但必须按影响范围更新权威源：

提出变更
  -> 识别受影响的领域、API、数据、算法和验收样本
  -> 记录 ADR 或变更说明
  -> 先修改合同和兼容策略
  -> 修改实现
  -> 执行回归
  -> 发布新版本

禁止先修改实现，再通过补文档解释现状。

11.2 必须记录 ADR 的决策 链接到标题

• 应用拆分或合并；
• 数据存储位置和分区策略；
• 权威算法或规则执行源；
• 长任务协议和消息语义；
• 状态机重大变化；
• 兼容性破坏；
• 外部 Provider 的替换；
• 影响性能、成本或安全边界的决策。

11.3 ADR 最小模板 链接到标题

# ADR-NNN：决策标题

## 状态
Proposed / Accepted / Superseded

## 背景
为什么需要决策，当前约束是什么。

## 决策
选择什么方案。

## 备选方案
考虑过哪些方案，为什么没有选择。

## 影响
对 API、数据、运行、成本、测试和迁移的影响。

## 验证与回滚
如何证明决策有效，失败时如何撤销。

12. 并行开发与智能体协作规范 链接到标题

12.1 任务拆分 链接到标题

每个并行任务必须明确：

• 目标和完成标准；
• 所有文件或模块；
• 允许修改的合同；
• 禁止修改的共享区域；
• 依赖的版本和前置任务；
• 验证命令；
• 集成负责人。

12.2 合同所有权 链接到标题

同一时间，下列内容只能有一个修改负责人：

• 领域核心模型；
• 公共接口；
• 数据库 Schema；
• 消息协议；
• 状态机；
• 核心执行算法；
• 公共基础设施类。

其他执行者可以审查和提出建议，但不能同时提交相互竞争的实现。

12.3 每轮并行后的统一验收 链接到标题

并行任务完成后必须进行一次统一集成：

1. 检查合同是否漂移；
2. 合并和解决冲突；
3. 执行完整构建；
4. 执行合同和状态机测试；
5. 执行代表集回归；
6. 更新进度、决策和风险；
7. 关闭已完成的执行单元。

13. 常见反模式 链接到标题

13.1 文档很多，但没有准入门槛 链接到标题

表现：方案反复评审，编码后仍持续讨论接口、DDL 和边界。

改进：为每个阶段定义退出条件，未通过不得扩大实现范围。

13.2 把验证版直接当正式系统设计 链接到标题

表现：Mock、临时字段、简化状态和单机假设进入正式实现。

改进：明确验证版只证明哪些假设；正式实现只继承验证结论，不继承临时代码和数据模型。

13.3 流程跑完就算成功 链接到标题

表现：任务成功，但内部调用失败、数据为空或结果不可判定。

改进：验收必须同时校验流程状态、技术执行、业务结果和数据守恒。

13.4 先存所有数据，后续再清理 链接到标题

表现：相同原始内容在事件表、快照和 JSON 字段中重复保存。

改进：先确定权威原始数据、重放需求和保留期，只保存一份必要快照。

13.5 把生产环境当集成测试环境 链接到标题

表现：接口、DDL、依赖和核心逻辑在部署后才首次组合验证。

改进：在发布前构建与生产拓扑接近的集成环境，并执行自动化门禁。

13.6 性能问题全部后置 链接到标题

表现：大表分区键、分页协议和外部限流到上线前才纳入设计。

改进：优化可以后置，容量约束和访问模式不能后置。

13.7 通过新增兜底掩盖合同错误 链接到标题

表现：输入缺失、状态异常或协议错误时不断增加默认值和旧逻辑兼容。

改进：全新项目应修正权威合同和数据源，禁止保留相互矛盾的语义。

13.8 依赖聊天记录交接项目状态 链接到标题

表现：新任务需要复制大量历史结论，事实和完成状态难以确认。

改进：维护项目章程、ADR、合同版本、验收报告和发布 Manifest，聊天只用于推动工作，不作为长期事实源。

14. 项目启动总检查表 链接到标题

14.1 编码前 链接到标题

• 项目目标、P0 范围和非目标明确；
• 成功指标可度量；
• 权威事实源矩阵完成；
• 领域词典和不变量完成；
• 核心状态机完成；
• 系统边界和职责矩阵完成；
• P0 API、事件和错误合同完成；
• 数据分类、ERD 和容量模型完成；
• 非功能预算完成；
• 单条验收样本和预期结果完成；
• 环境、配置和密钥管理方式明确；
• 关键 ADR 已接受。

14.2 扩大开发范围前 链接到标题

• 单条 Walking Skeleton 通过；
• 正常、业务不满足和技术失败路径均已验证；
• 状态无悬挂；
• 重复执行幂等；
• 全链路可观测；
• 数据可回查；
• 合同和 Schema 自动测试通过。

14.3 联调前 链接到标题

• 代表集已经建立；
• 数据库可重复初始化；
• 外部依赖和限流策略明确；
• 三端消费者合同测试通过；
• 测试脚本和运行期脚本分离；
• 核心依赖缺失不会被静默跳过；
• 错误码、日志和指标可以定位具体阶段。

14.4 发布前 链接到标题

• 产品验收矩阵通过；
• 发布集或 Golden Dataset 通过；
• 性能、容量和成本预算通过；
• 无隐藏失败和异常终态；
• 数据迁移和兼容性验证通过；
• 灰度、回滚和对账方案通过；
• 版本 Manifest 完整；
• 监控、告警和观察窗口就绪；
• 敏感凭据未进入代码、日志、报告和聊天交接材料。

15. 最终判断标准 链接到标题

一个项目是否真正具备进入下一阶段的条件，不看已经写了多少代码或文档，而看以下问题是否能明确回答：

1. 我们正在交付的最小业务闭环是什么？
2. 谁定义产品、领域、接口、数据和算法的最终事实？
3. 任意失败发生时，系统会进入什么状态，如何恢复？
4. 任意结果能否追溯到输入、配置和执行版本？
5. 真实数据量和真实依赖下，系统是否仍然成立？
6. 自动化测试能否识别“流程成功但内部失败”的假绿？
7. 多应用、多仓库和并行开发是否共享同一套合同？
8. 发布失败时是否可以快速发现、停止和回滚？

如果这些问题不能被合同、测试或运行证据回答，项目就还没有形成可靠的交付基线。