liuyun 5492184211 chore: init workspace from DDD template

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-10-13 13:19:26 +08:00

4.5 KiB

Raw Blame History

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 无后缀）

顺序（读取即构建顺序）：

层序：SH → FE → BE
FE 内端序：FE → AD
页序按 PRD 编号；块序 .01 → .02 …

目录命名：功能块目录带序号，如 specs/frontend/<端>/<页面>/03-<功能块>/。

例子：SH-DM（数据模型，最前）· FE-<端码>-<页面>.<块>（前端功能块）· BE-<实体码>（后端域）

6. 铁律

需求文档（PRD）是约束/规范的唯一权威，原型仅作视觉参考；PRD 冲突以全局规范为准。
数据库 schema 是字段一致性的唯一锚点：SH-DM 字段字典先行，前后端 spec 引用同一字段名，禁止各自命名。
前端先行 + Mock：前端对 Mock 验收，后端对 SH-AC 契约实现。
字段/接口变更先改 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 验收编号

4.5 KiB Raw Blame History Unescape Escape