101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
# Spec 约定（Spec Conventions）
|
||
|
||
投云长护系统 openspec spec 的**组织、粒度、编号**唯一权威约定。
|
||
**新会话、新 change 必须严格遵守，违反即返工。**
|
||
|
||
## 1. 需求权威
|
||
|
||
- **需求文档（PRD）是约束/规范的唯一权威**，位于 `docs/requirements/`：
|
||
- docs/requirements/*.md
|
||
- **原型仅作视觉参考**，约束/规范一律以 PRD 为准。
|
||
- **PRD 内部冲突时，以全局规范文档（PRD-00 全局规范）为准**。
|
||
|
||
## 2. 技术栈
|
||
|
||
待定（占位，后续在 PRD 中明确）
|
||
|
||
## 3. spec 三层结构
|
||
|
||
```
|
||
specs/
|
||
├── shared/ ← 跨前后端公共契约（粘合剂）
|
||
│ ├── platform/ 全局规范（设计令牌/文案/URL 契约/隐私红线）
|
||
│ ├── data-model/ 数据模型（实体 + 枚举 + 状态机 = 字段字典）
|
||
│ └── api-contract/ API 契约（endpoint + 请求/响应 shape）
|
||
├── frontend/ ← 前端 spec（Mock 独立验收）
|
||
│ └── <各端目录> ← `BE` 后端 / `FE` 前端 / `AD` 后台
|
||
└── backend/ ← 后端 spec（API 独立验收）
|
||
└── <各实体/域目录> ← 待定
|
||
```
|
||
|
||
## 4. 粒度规则
|
||
|
||
- **前端**：细到「功能块」级。一个 spec = 一个可独立验收的功能单元，锚定 PRD 的
|
||
「元素定义表」（1 个元素或一组强相关元素）。每页保留一个薄「页面级 spec」作容器
|
||
（定位/导航/布局/流转）。
|
||
- 判断标准：这个块能不能**独立验收、独立打勾**。能就拆，不能就合；简单页不强拆。
|
||
- 同一页面 PC 与移动可合并为同一 spec（布局差异写在 spec 内部）。
|
||
- **后端**：按实体/域（待定）。
|
||
- **共享**：platform / data-model / api-contract 三个。
|
||
|
||
## 5. 编号规则
|
||
|
||
格式：`<层>-<端/域>-<页面/实体>[.<功能块>]`
|
||
|
||
| 段 | 取值 |
|
||
|---|---|
|
||
| 层 | `SH` shared / `FE` frontend / `BE` backend |
|
||
| 端(FE) | `BE` 后端 / `FE` 前端 / `AD` 后台 |
|
||
| 域(BE) | 待定 |
|
||
| 域(SH) | `PLT` platform / `DM` data-model / `AC` api-contract |
|
||
| 页面(FE) | 沿用 PRD 编号去 `P-` 前缀 |
|
||
| 功能块 | `.01` `.02` …（页面级 spec 无后缀） |
|
||
|
||
**顺序（读取即构建顺序）**：
|
||
1. 层序：`SH` → `FE` → `BE`
|
||
2. FE 内端序：`FE` → `AD`
|
||
3. 页序按 PRD 编号；块序 `.01` → `.02` …
|
||
|
||
**目录命名**：功能块目录带序号，如 `specs/frontend/<端>/<页面>/03-<功能块>/`。
|
||
|
||
**例子**：`SH-DM`（数据模型，最前）· `FE-<端码>-<页面>.<块>`（前端功能块）· `BE-<实体码>`（后端域）
|
||
|
||
## 6. 铁律
|
||
|
||
1. **需求文档（PRD）是约束/规范的唯一权威，原型仅作视觉参考**；PRD 冲突以全局规范为准。
|
||
2. **数据库 schema 是字段一致性的唯一锚点**：`SH-DM` 字段字典先行，前后端 spec 引用同一字段名，禁止各自命名。
|
||
3. **前端先行 + Mock**：前端对 Mock 验收，后端对 `SH-AC` 契约实现。
|
||
4. **字段/接口变更先改 `shared/`，再改对应 spec**。
|
||
|
||
## 7. 构建顺序（Phase）
|
||
|
||
- **Phase 0 地基**：`sources/` 脚手架 + `shared/` 三层 spec（含 DB 设计）+ Mock
|
||
- **Phase 1 前端**：各端按 Mock 驱动实现
|
||
- **Phase 2 后端**：按 `SH-AC` 契约实现
|
||
- **Phase 3 联调与上线**：切真实 API → 端到端验证 → 上线
|
||
|
||
## 8. spec 文档结构（四段式，每个 spec 必含）
|
||
|
||
**每个 spec 是独立开发单元**：可独立开发、独立测试、独立交付。文档必须含以下四段：
|
||
|
||
### ① 模块边界（Scope）
|
||
- 包含什么功能 / **不包含什么功能**（明确列出「非目标」，防范围蔓延）
|
||
- 依赖声明：本 spec 引用哪些 `SH-*`（字段名 → data-model、接口 → api-contract、全局规则 → platform）
|
||
|
||
### ② 核心场景（Scenarios）
|
||
- 用 **WHEN / THEN / AND** 格式，覆盖**正常路径 + 异常路径**
|
||
- 与 openspec 原生 `#### Scenario:` 格式对齐
|
||
|
||
### ③ 数据结构（Data）
|
||
按层适配：
|
||
|
||
| 层 | 数据结构内容 |
|
||
|---|---|
|
||
| 前端 FE | 组件 Props（props 名 / 类型 / 必填 / 默认值 / 约束）+ 页面状态 |
|
||
| 后端 BE | 实体字段 + DTO（请求/响应字段、类型、校验约束）+ 状态机 |
|
||
| 共享 SH | data-model = 字段字典（实体/枚举/状态机）；api-contract = 接口 shape |
|
||
|
||
### ④ 验收标准（Acceptance）
|
||
- **ACCEPTANCE Checklist，可勾选**（`- [ ]` 形式）
|
||
- 每条对应一个可验证行为，锚定 PRD 的 `AC-xx` 验收编号
|