logan
9304b0e98c
- 重写 AGENTS：浏览器只站+文档、操作走 ./run.sh gui；目录以现仓 src/src-tauri/server 为准 - docs/sdd-template.md 填成与 Shell/DB 同款短模板；sdd-agents/CLAUDE 指向它与 specs - 新增 docs/architecture.md（两套壳、数据流、安全三底线）与 docs/README 索引 - HANDTEST/README 去掉用 :5173 当工作台的旧手测口径
54 lines
3.7 KiB
Markdown
54 lines
3.7 KiB
Markdown
# SDD 流程与规格索引
|
|
|
|
SDD 是 Software Design Document（软件设计文档）；本项目以版本化设计契约驱动开发。需求说明“做什么”，设计说明“如何实现”，测试证据说明“是否做到”。
|
|
|
|
## 分级与最小产物
|
|
|
|
按最高影响定级，不以代码行数定级。
|
|
|
|
| 级别 | 范围 | 实施前产物 |
|
|
| --- | --- | --- |
|
|
| S0 | 文案、格式、无行为变化的文档纠错 | 明确范围和检查方式，无需单独规格 |
|
|
| S1 | 恢复已批准行为的缺陷修复、契约内重构 | 任务记录中的问题、依据、不变量、验收步骤 |
|
|
| S2 | 新功能、API/IPC/配置/数据模型及跨模块行为变更 | 使用 [_template.md](_template.md) 创建或修订功能规格并评审 |
|
|
| S3 | 权限、安全、迁移、删除数据、生产部署 | S2 + 风险、兼容、审计/观测（按产品边界）、发布与恢复方案 |
|
|
|
|
规格保存在 `docs/specs/<domain>/<slug>.md`。持续开发同一能力时修订已有规格，不重复创建。小功能可将需求与设计分节写在同一文件；大型需求可单独成文并引用。不适用项写明原因。
|
|
|
|
## 工作流与权限
|
|
|
|
1. 调研：读取实际代码、适用规则、测试和未提交改动；区分事实、假设、提案。
|
|
2. 需求：定义范围、非目标、用户场景、FR/NFR 及 AC；未知指标标待确认。
|
|
3. 设计：明确边界、接口、数据、失败路径与测试预期，再评审。
|
|
4. 实现：依据已批准版本实施，允许自主选择契约内实现细节。
|
|
5. 验证：将每条 AC 映射至实现位置和测试证据，记录未运行项。
|
|
6. 交付：报告差异、结果和剩余问题，不把构建成功等同功能验收。
|
|
|
|
S2/S3 的业务行为和契约在实施前需要明确批准依据。已有明确授权覆盖该设计版本与范围时，记录原授权，不重复询问。Agent 不得将“需求看起来清楚”视为自行批准新设计的依据。
|
|
阻塞问题只暂停依赖它的实现，其他调研、设计和独立工作可继续。
|
|
|
|
## 版本与状态
|
|
|
|
- 设计状态：Draft → In Review → Approved → Superseded。
|
|
- 实现状态单独记录：Not Started / In Progress / Implemented / Verified。
|
|
- 批准记录包含版本、批准人、日期和可追溯依据；模板不预填批准人。
|
|
- 冻结代表版本受控。改变接口、数据语义、权限或验收预期时，先记录旧/新差异及影响，新版本重新评审；批准旧版本不等于批准新版本。
|
|
- 现有代码只能作为“待评审现状基线”，不能直接标为已批准设计。
|
|
- 文档更正但不改变契约时记录更正即可；不得借文档修订掩盖实现偏差。
|
|
|
|
## 契约归属与完成条件
|
|
|
|
SDD 明确接口、Schema、迁移及依赖锁文件的权威路径和版本，不复制多份字段表。当前代码与设计冲突时先判断是缺陷还是设计变更；不能自动以代码覆盖设计。
|
|
仓库规范不覆盖适用的系统/工具限制；后续明确用户指令导致契约变化时应同步修订，不静默执行旧设计。
|
|
|
|
测试场景和预期结果在实现前定义，测试代码可随实现完成。覆盖受影响的成功、边界、失败、权限和兼容行为。
|
|
所有 AC 有通过证据且实现与契约一致，才可标 Verified。Blocked/Not Run 不算通过；记录命令/环境/日期或人工步骤及结果，不能仅写“已检查”。
|
|
本文件是工作约定，不代表已启用 CI 或分支保护；需要强制禁止合并时须另行配置仓库门禁。
|
|
|
|
## 规格索引
|
|
|
|
当前仅建立流程与模板，尚无已批准功能规格。
|
|
|
|
| 规格 | 版本 | 设计状态 | 实现状态 | 批准依据 |
|
|
| --- | --- | --- | --- | --- |
|