80 lines
4.6 KiB
Markdown
80 lines
4.6 KiB
Markdown
|
# NEX Docus – 规格驱动开发（SDD）中心
|
|||
|
|
|
|||
|
|
本目录是 NEX Docus **规格驱动的开发中心**（Spec-Driven Development）。它把「产品意图 → 架构决策 → 功能规格 → 实施任务 → 验证证据」放进同一条可追踪链路，并作为团队讨论、开发与验收的**唯一真相源（single source of truth）**。
|
|||
|
|
|
|||
|
|
## 文档结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
docs/sdd/
|
|||
|
|
├── README.md # 入口、状态与工作流（本文件）
|
|||
|
|
├── governance.md # 编号、审批、变更与追踪规则
|
|||
|
|
├── archive.md # 遗留文档归档说明（整合/弃置追踪）
|
|||
|
|
├── product/
|
|||
|
|
│ ├── vision.md # 产品愿景、用户与边界
|
|||
|
|
│ ├── principles.md # 产品与工程原则
|
|||
|
|
│ └── roadmap.md # 阶段性路线图
|
|||
|
|
├── architecture/
|
|||
|
|
│ ├── overview.md # 当前架构方向与系统边界
|
|||
|
|
│ ├── constraints.md # 已知约束与待决事项
|
|||
|
|
│ ├── standards/
|
|||
|
|
│ │ ├── README.md # 代码结构规范索引
|
|||
|
|
│ │ ├── code-structure-standards.md # 代码结构规范（整合自 docs/）
|
|||
|
|
│ │ └── code-structure-audit-2026-04-08.md # 结构审计记录（整合自 docs/）
|
|||
|
|
│ └── decisions/
|
|||
|
|
│ ├── README.md # ADR 索引与规则
|
|||
|
|
│ └── ADR-0001-*.md # 持久架构决策（逐条一文件）
|
|||
|
|
├── integrations/
|
|||
|
|
│ ├── mcp.md # MCP Streamable HTTP 接入（含详细使用文档）
|
|||
|
|
│ └── git.md # 项目 Git 仓库集成
|
|||
|
|
├── releases/
|
|||
|
|
│ ├── README.md # 公开版本与资产索引
|
|||
|
|
│ ├── v0.9.6.md # v0.9.6 历史升级记录（整合自 docs/）
|
|||
|
|
│ └── v0.9.9.md # 当前基线发布（对齐 git）
|
|||
|
|
└── specs/
|
|||
|
|
├── README.md # 功能规格索引
|
|||
|
|
├── _template/ # 新规格模板
|
|||
|
|
└── DV-NNNN-short-name/ # 一个功能或变更单元（spec/design/tasks/verification）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 当前状态（Status）
|
|||
|
|
|
|||
|
|
- **SDD 文档状态**：基线（Baseline）· 对齐 git 当前版本 v0.9.9
|
|||
|
|
- **适用代码基线**：当前仓库（backend + frontend + docker-compose 部署）
|
|||
|
|
- **规格覆盖**：11 个功能单元（DV-0001 ~ DV-0011）；价值主张 PO-1~5；架构决策 ADR-0001~0008
|
|||
|
|
- **已知整改项**：见 governance「开放问题」与各规格 tasks.md 中的“待整改/待决”标记（如敏感日志脱敏 TS-12、Compose v2 官方化 TS-13）
|
|||
|
|
- **版本基线**：以 git 为准（当前 v0.9.9；见 releases/README.md 与 v0.9.9.md 版本对齐说明；代码字段 1.0.0 为遗留占位）
|
|||
|
|
|
|||
|
|
## 如何使用本中心（工作流）
|
|||
|
|
|
|||
|
|
### 读者
|
|||
|
|
| 角色 | 入口 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 产品/方案 | `product/vision.md`、`product/roadmap.md` |
|
|||
|
|
| 架构评审 | `architecture/overview.md`、`architecture/standards/README.md`、`architecture/decisions/README.md` |
|
|||
|
|
| 功能负责人 | `specs/README.md` → 对应 `DV-NNNN/spec.md` |
|
|||
|
|
| 开发 | `DV-NNNN/design.md` + `tasks.md` |
|
|||
|
|
| 测试/验收 | `DV-NNNN/verification.md` |
|
|||
|
|
| 发布 | `releases/README.md` |
|
|||
|
|
| 遗留文档去向 | `archive.md` |
|
|||
|
|
|
|||
|
|
### 作者（新增/改功能）
|
|||
|
|
1. 在 `governance.md` 读取编号规则，申请下一个规格编号（DV-NNNN）与 ADR 编号。
|
|||
|
|
2. 复制 `specs/_template/` 到 `specs/DV-NNNN-short-name/`，先写 `spec.md`（为什么、做什么）。
|
|||
|
|
3. 评审通过后写 `design.md`；实现过程中维护 `tasks.md` 勾选切片。
|
|||
|
|
4. 完成后在 `verification.md` 登记验收证据，并回填 `specs/README.md` 索引。
|
|||
|
|
5. 涉及跨文件刚性承诺（ADR）变更的，走 `architecture/decisions` 审批。
|
|||
|
|
|
|||
|
|
### 最小变更（bug 修复）
|
|||
|
|
- 若属于既有 DV 规格范围：直接在该单元 `tasks.md` 追加切片并更新 `verification.md`。
|
|||
|
|
- 若超出所有现有范围：新建 DV 规格。
|
|||
|
|
|
|||
|
|
## 与外部文档的关系
|
|||
|
|
|
|||
|
|
SDD 中心**汇总并指向**仓库既有的详细材料，而非重复复制全部内容：
|
|||
|
|
- 数据库细节 → 仓库根 `DATABASE.md`（SDD 只保留 ER 概览与规格化的链路表）
|
|||
|
|
- 部署运维 → `DEPLOY.md`、`README_DOCKER.md`、`CHANGELOG_DEPLOY.md`（及已并入的 docs/DOCKER_DOCS_SETUP 历史，见 archive.md）
|
|||
|
|
- 历史变更 → `docs/UPGRADE_v0.9.6.md`、`docs/MIGRATION.md`（已整合/弃置，见 archive.md）
|
|||
|
|
- 结构规范 → `architecture/standards/`（原 docs/code-structure-* 已迁入）
|
|||
|
|
|
|||
|
|
> 本中心是入口与追踪层；具体逐表 DDL、逐配置项说明等细节仍以被指向的源文档为准。
|