Skip to main content

[项目名称] — Project Spec

文档编号： PRJ-YYYY-XXX
状态： Draft / In Review / Approved / In Progress / Done
版本： v0.1
创建日期： YYYY-MM-DD
最后更新： YYYY-MM-DD
Owner： @姓名
审阅人： Tom（产品）/ e50u（技术）/ kzzs（协调）

TL;DR​

三句话内说清楚：做什么、为什么、怎么判断成功。

做什么： 一句话描述
为什么： 业务价值或痛点
成功标准： 关键指标

1. 背景与问题​

1.1 背景​

描述现状、数据支撑、业务场景。避免主观判断，用事实说话。

  • 当前状况：
  • 数据佐证：（如有，列出相关指标/数量级）
  • 问题触发：

1.2 问题陈述​

用"用户视角"描述痛点，而非解决方案。

主要问题：
当 [用户/角色] 尝试 [完成某事] 时，遇到 [问题/阻碍]，导致 [影响/后果]。

次要问题：​

1.3 不做这个项目的代价​

如果不做，会发生什么？量化代价有助于排优先级。

2. 目标与非目标​

2.1 目标（Goals）​

SMART 原则：Specific / Measurable / Achievable / Relevant / Time-bound

#目标成功指标截止日期
G1
G2

2.2 非目标（Non-Goals）​

明确写出本次不做的事，避免范围蔓延。

  • 本期不包含：
  • 未来可能做，但不在本次范围：

2.3 假设与约束​

类型描述
假设
约束
依赖

3. 用户与场景​

3.1 目标用户​

角色描述核心诉求

3.2 核心使用场景（User Stories）​

格式：作为 [角色]，我希望 [做某事]，以便 [获得价值]

  • 作为 [角色]，我希望 [做某事]，以便 [获得价值]
  • 作为 [角色]，我希望 [做某事]，以便 [获得价值]

4. 技术方案​

4.1 方案概览​

简述整体技术思路，选择该方案的理由，以及被否定的备选方案。

选定方案：

否定的备选方案：

备选方案否定原因

4.2 系统架构​

文字描述或 ASCII 图，说明主要组件、数据流向、外部依赖。

[Client] → [API Gateway] → [Service A] → [DB]
                        ↘ [Service B] → [Cache]

关键组件：

组件职责技术选型

4.3 数据库设计​

仅列出本期新增或修改的表。已有表只描述改动。

新增表：table_name​

字段类型可空默认值说明
idbigintNauto主键，自增
created_atbigintN创建时间（Unix 秒）
updated_atbigintN更新时间（Unix 秒）

索引：

  • idx_xxx_yyy ON (field_a, field_b)

表关系：

  • this_table.user_id → users.id

已有表变更：table_name​

变更类型字段说明
ADD
MODIFY

4.4 API 接口定义​

定义本期新增接口的契约。已有接口如有修改需注明 Breaking Change。

Base URL： /v1/

POST /v1/xxx​

描述： 创建 xxx

Request Body：

{
  "field_a": "string, required, 最大64字符",
  "field_b": 0
}

Response 200：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 1
  }
}

错误码：

code说明
1001参数校验失败
1002xxx 不存在

GET /v1/xxx/:id​

继续列出其他接口...

4.5 非功能性需求（NFR）​

维度要求备注
性能P99 响应时间 < Xms
并发QPS ≥ X
可用性99.9% uptime
数据安全敏感字段加密存储
兼容性向后兼容，无 Breaking Change

4.6 安全考量​

明确潜在的安全风险和对应措施。

风险点措施
身份认证JWT + 签名验证
权限控制RBAC，接口级鉴权
输入校验所有入参 validator 校验，防注入
敏感数据日志脱敏，不明文存储

4.7 风险与应对​

#风险描述概率影响应对措施Owner
R1高/中/低高/中/低
R2

5. 实施计划​

5.1 阶段划分​

阶段内容工期产出物
Phase 1X 天
Phase 2X 天

5.2 任务拆解​

每个任务对应一个可独立合并的 MR，关联 AC 编号。

Phase 1：

  • [BE] 任务描述 → 关联 AC-001, AC-002（预计 Xh）
  • [BE] 任务描述 → 关联 AC-003（预计 Xh）
  • [DB] Migration: 新增 xxx 表（预计 Xh）

Phase 2：

  • [BE] 任务描述 → 关联 AC-004（预计 Xh）

标签约定：[BE] 后端 / [FE] 前端 / [DB] 数据库 / [INFRA] 基础设施 / [TEST] 测试

5.3 回滚方案​

每个阶段上线后，如何回滚。

  • Phase 1 回滚： docker rollback + Migration rollback VXX__down.sql
  • Phase 2 回滚：

6. 验收标准（AC）​

格式规范（BDD Gherkin）：

AC-XXX: [简短标题]
Given  [前置状态/条件]
When   [用户操作 / 系统行为]
Then   [期望结果，包含具体值/状态码/数据变化]

质量要求：

  • ✅ 每条 AC 必须独立可验证，结果明确（含状态码、字段值等）
  • ✅ 覆盖正常路径 + 边界条件 + 异常路径
  • ❌ 禁止模糊描述："功能正常""体验更好""性能提升"
  • ❌ 禁止功能描述代替行为描述："支持用户登录"

AC-001：[功能点名称 - 正常路径]​

Given  用户已完成认证，持有有效 JWT Token
When   用户发送 POST /v1/xxx，Body 包含合法参数 { field_a: "test", field_b: 1 }
Then   返回 HTTP 200
       Response body: { "code": 0, "data": { "id": [非空 bigint] } }
       数据库 table_xxx 中新增一条记录，field_a = "test"
字段值
验证方式自动（集成测试）
优先级P0
负责人

AC-002：[功能点名称 - 参数校验]​

Given  用户已完成认证
When   用户发送 POST /v1/xxx，Body 中 field_a 为空字符串
Then   返回 HTTP 400
       Response body: { "code": 1001, "msg": "field_a 不能为空" }
       数据库无新增记录
字段值
验证方式自动（单元测试）
优先级P1
负责人

AC-003：[功能点名称 - 权限控制]​

Given  请求未携带 JWT Token 或 Token 已过期
When   用户发送任意需认证接口
Then   返回 HTTP 401
       Response body: { "code": 4001, "msg": "unauthorized" }
字段值
验证方式自动（集成测试）
优先级P0
负责人

继续添加 AC-004, AC-005...

覆盖清单（完成前确认）：

  • 所有核心功能的 Happy Path
  • 参数边界值（空/最大/非法类型）
  • 未认证/越权访问
  • 并发/幂等性（如适用）
  • 数据不存在的 404 场景

7. RACI 矩阵​

任务/决策Tom（产品）e50u（技术顾问）kzzs（协调）开发 Agent
需求确认与范围锁定A/RCII
技术方案评审CA/RII
API 契约确认CA/RIC
DoD Gate 三方复核RRRI
开发执行ICAR
QA 验收IA/RII
测试环境部署IIA/RI
最终交付确认A/RCCI

R = Responsible（执行）A = Accountable（决策负责）C = Consulted（咨询）I = Informed（知会）

8. DoD Gate — 三方复核清单​

进入开发前，Tom / e50u / kzzs 三方必须逐项确认。任一方否决则退回修改。

需求质量​

  • TL;DR 准确概括项目
  • 背景有数据支撑，问题陈述无歧义
  • 目标可衡量，非目标已明确列出
  • User Story 覆盖核心场景

技术质量​

  • 架构方案已评审，无遗漏组件
  • 数据库设计合理，索引策略已考虑
  • API 契约完整（入参/出参/错误码）
  • 非功能性需求（性能/安全）已定义
  • 回滚方案可执行

AC 质量​

  • AC 覆盖所有任务拆解项
  • 每条 AC 独立可验证，有明确期望值
  • 覆盖正常路径、边界条件、异常路径
  • AC 编号与任务拆解已关联

可执行性​

  • 任务已拆解到独立 MR 粒度
  • 工期估算合理（含 buffer）
  • 依赖已识别，风险有应对措施

三方签字：

角色姓名结论日期
产品（Tom）✅ 通过 / ❌ 退回
技术顾问（e50u）✅ 通过 / ❌ 退回
协调（kzzs）✅ 通过 / ❌ 退回

退回原因（如有）：

9. 时间线​

YYYY-MM-DD  Spec 完成，进入 DoD Gate 评审
YYYY-MM-DD  三方复核通过，开发启动
YYYY-MM-DD  Phase 1 完成，部署测试环境
YYYY-MM-DD  Phase 2 完成，QA 验收开始
YYYY-MM-DD  验收通过，测试环境交付

10. 监控与告警​

上线后如何确认系统健康，以及告警阈值。

指标正常范围告警阈值告警渠道
接口错误率< 0.1%> 1%Telegram
P99 响应时间< Xms> XmsTelegram

11. 附录​

  • 参考文档：
  • 相关 MR/Issue：
  • 会议记录：
  • 变更历史：
版本日期修改人变更说明
v0.1YYYY-MM-DD初稿