88 lines
5.5 KiB
Markdown
88 lines
5.5 KiB
Markdown
# 阶段 ① 需求与规格（Requirement & Spec）
|
||
|
||
> **定义**：把用户意图变成一份"实现者（人或 agent）无需猜"的规格文档。规格完备的标志是：实现者不发明任何决策就能把改动做出来。
|
||
> **输入**：需求描述 / issue / 用户反馈 / 变更请求。
|
||
> **输出**：规格文档（按下方 7 段结构 + BR/E/AC 编号）。
|
||
> **进入下一阶段（② 架构设计）**：六道完备性门全部通过。
|
||
|
||
---
|
||
|
||
## 1. 要求（Requirements）
|
||
|
||
### 1.1 进入条件
|
||
- 需求来源明确（谁提的、要解决什么问题、对哪些角色生效）。
|
||
- 明确本轮范围 vs 明确不在本轮范围（out-of-scope 与 in-scope 同等重要）。
|
||
- 单一交付面还是多交付面已确认（web / Electron 主进程 / 硬件网关 / 设置面板……每个交付面都会让规格多一段）。
|
||
|
||
### 1.2 完成条件（DoD）
|
||
- [ ] 七段结构齐全（多交付面则第 3 段重复），每个领域术语都进术语表
|
||
- [ ] 每条业务规则 `BR-xx` 可测试（能说清"什么输入让它过、什么输入让它挂"）
|
||
- [ ] 每条规则隐含的失败路径都有 `E-xx`，异常"用户可见消息 ↔ 后端错误码"绑定
|
||
- [ ] 每条 `BR-xx` / `E-xx` 至少被一条 `AC-xx` 引用；验收含正常/异常/边界三类用例
|
||
- [ ] 无阻塞当前迭代的未决问题（或已把阻塞规则移出范围）
|
||
- [ ] 决策记录（Decision Record）已写明已定决策与被否掉的替代方案
|
||
|
||
---
|
||
|
||
## 2. 规则（Rules）
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-1.1 | 行为必须有 id：业务规则 `BR-01`…，异常场景 `E-01`…，验收标准 `AC-01`…。散文式描述不能进入规格。 |
|
||
| R-1.2 | id 只追加不重排；规则废弃时标记 withdrawn 并保留编号（提交、测试、评审已引用旧 id）。编号按规格独立，不全局递增。 |
|
||
| R-1.3 | 每条 `BR-*` 只对应**一个**实现点。一条规则要碰三条无关代码路径 = 它其实是三条规则。 |
|
||
| R-1.4 | 每条 `E-*` 必须绑定"各受影响面展示给用户的消息"与"产生它的后端错误码"，前后端不能静默漂移。 |
|
||
| R-1.5 | 每条 `AC-*` 用 `Given / When / Then` 三元组，且引用它覆盖的 `BR-*`/`E-*` id。无验收引用的规则/异常 = 未验证，阻塞进入实现。 |
|
||
| R-1.6 | 未决定的事项显式标记（`needs-decision` / open question，带 owner 与期限），禁止用"貌似合理的编造值"填空。 |
|
||
| R-1.7 | 截图/线框图只表达布局，不替代规则：不得用截图当 spec，除非它同时写清状态转换与权限。 |
|
||
| R-1.8 | 反模式禁止：只写 happy path（§5/§6 才是实现风险所在）、把字段类型当业务规则（`BR-*` 描述系统**要决定什么**，不是**存什么**）、整段照抄他项目（可复用段清单，内容必须基于本目标事实重写）。 |
|
||
|
||
---
|
||
|
||
## 3. 输出规范
|
||
|
||
### 3.1 规格文档结构（7 段；每多一个交付面，第 3 段重复一次 → 8/9 段）
|
||
|
||
```text
|
||
1. Requirement Overview 业务背景、in-scope / out-of-scope、受影响角色、术语表
|
||
2. Data Model & Interface 新增/变更的表（列类型、可空性）、服务契约、公开端点（请求/响应形状）、枚举、消息/事件载荷
|
||
Contract
|
||
3. Surface Specification 每个交付面：页面骨架、组件粒度、每个有状态视图的状态机、动作列表（含守卫权限）
|
||
4. Business Rules 编号 BR-01…，每条一条可测试语句
|
||
5. Exception Scenarios 编号 E-01…，触发条件 + 各面用户可见消息 + 后端错误码
|
||
6. Acceptance Criteria 编号 AC-01…，按角色分组，Given/When/Then，覆盖正常/异常/边界
|
||
7. Open Questions & 未决项（owner + needed-by）+ 已定决策与被否方案
|
||
Decision Record
|
||
```
|
||
|
||
> 参考模板：`vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md`（前端表面）、`backend-service-spec.md`（多交付面）、`mobile-app-spec.md`（离线/权限/版本）。**复用结构，不复用表名/端点/阈值/角色名。**
|
||
|
||
### 3.2 六道完备性门（任一不过，禁止进入实现）
|
||
|
||
| 门 | 判定 |
|
||
|---|---|
|
||
| **Term gate 术语门** | 规则中每个领域术语都在术语表里 |
|
||
| **Contract gate 契约门** | 表面展示/提交的每个字段都在 §2 里有类型，每个枚举值都列出 |
|
||
| **Rule gate 规则门** | 每条 `BR-*` 可测试（评审者能说出"输入 X 通过、输入 Y 失败"） |
|
||
| **Exception gate 异常门** | 每条规则隐含的失败路径都有 `E-*`；静默失败是规格缺陷，不是实现细节 |
|
||
| **Coverage gate 覆盖门** | 每条 `BR-*`/`E-*` 至少被一条 `AC-*` 引用；验收含至少一个边界用例 |
|
||
| **Decision gate 决策门** | 本轮范围内没有未决问题阻塞规则；要么移出范围，要么解决 |
|
||
|
||
### 3.3 交付物清单
|
||
- 规格文档（本地草稿放 `docs/plans/`，**不入库**，见 `.gitignore`；需入库的规格随 PR 放 `docs/` 对应目录，命名 `<日期>-<主题>-spec.md`）
|
||
- （可选）给 UI 需求的面：指向 [04-ui-spec.md](04-ui-spec.md) 的表面规格拆分
|
||
|
||
---
|
||
|
||
## 4. 轻量路径（小改动）
|
||
|
||
- 一行修复 / 文案 / 纯内部重构：规格可缩为 PR 描述中的"范围 + BR/AC 各 1-3 条"，但 id 与可追溯要求不变。
|
||
- 无法写清验收标准的改动 = 规格未完成，不得进实现。
|
||
|
||
---
|
||
|
||
## 5. 相关文档
|
||
|
||
- 阶段 ② [02-architecture.md](02-architecture.md)、阶段 ④ [04-ui-spec.md](04-ui-spec.md)
|
||
- 规格→实现→验证的流程闭环定义见 [README.md](README.md) 全景
|