# Spec 约定（Spec Conventions）

通用系统管理脚手架 openspec spec 的**组织、粒度、编号**唯一权威约定。
**新会话、新 change 必须严格遵守，违反即返工。**

## 1. 需求权威

- **需求文档（PRD）是约束/规范的唯一权威**，位于 `docs/requirements/`：
  - docs/requirements/*.md
- **原型仅作视觉参考**，约束/规范一律以 PRD 为准。
- **PRD 内部冲突时，以全局规范文档（PRD-00 全局规范）为准**。

## 2. 技术栈

待定（TODO：待技术选型后补充）

## 3. spec 三层结构

```
specs/
├── shared/                    ← 跨前后端公共契约（粘合剂）
│   ├── platform/              全局规范（设计令牌/文案/URL 契约/隐私红线）
│   ├── data-model/            数据模型（实体 + 枚举 + 状态机 = 字段字典）
│   └── api-contract/          API 契约（endpoint + 请求/响应 shape）
├── frontend/                  ← 前端 spec（Mock 独立验收）
│   └── <各端目录>            ← `BE` 后端 / `FE` 前端 / `AD` 管理后台（待定）
└── backend/                   ← 后端 spec（API 独立验收）
    └── <各实体/域目录>        ← `USER` 用户 / `ROLE` 角色 / `PERM` 权限 / `ORG` 组织（待定）
```

## 4. 粒度规则

- **前端**：细到「功能块」级。一个 spec = 一个可独立验收的功能单元，锚定 PRD 的
  「元素定义表」（1 个元素或一组强相关元素）。每页保留一个薄「页面级 spec」作容器
  （定位/导航/布局/流转）。
  - 判断标准：这个块能不能**独立验收、独立打勾**。能就拆，不能就合；简单页不强拆。
  - 同一页面 PC 与移动可合并为同一 spec（布局差异写在 spec 内部）。
- **后端**：按实体/域（`USER` 用户 / `ROLE` 角色 / `PERM` 权限 / `ORG` 组织（待定））。
- **共享**：platform / data-model / api-contract 三个。

## 5. 编号规则

格式：`<层>-<端/域>-<页面/实体>[.<功能块>]`

| 段 | 取值 |
|---|---|
| 层 | `SH` shared / `FE` frontend / `BE` backend |
| 端(FE) | `BE` 后端 / `FE` 前端 / `AD` 管理后台（待定） |
| 域(BE) | `USER` 用户 / `ROLE` 角色 / `PERM` 权限 / `ORG` 组织（待定） |
| 域(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` 验收编号