SDD 规格驱动维护规范
本仓库采用轻量 Specification-Driven Development(SDD)维护模式。需求规格是“做什么以及什么结果算完成”,实施计划是“怎么做以及如何验证”,代码和测试不能替代规格,目标环境验收不能被本地构建结果替代。
规范入口
| 内容 | 唯一维护入口 |
|---|---|
| 需求规格 | docs/requirements/ |
| 实施计划 | docs/plans/ |
| 测试用例集 | docs/testing/,文件命名 FNOS-###-test-cases.md |
| 真实环境验收证据 | docs/validation/ |
| 应用和插件面向用户说明 | docs/ 下的应用/插件文档 |
| 跨需求架构决策 | docs/decisions/,仅在计划中的决策章节不足以表达时使用 |
| 转换踩坑与经验教训 | docs/development/1panel-conversion-lessons.md,记录实际发生并已修复的问题(规约的补充说明,规则本身以规约为准) |
不新建与 requirements/、plans/ 重复的 specs/ 或 stories/ 目录。apps/*/README.md 和 plugins/*/README.md 保留作历史或兼容参考,不作为现行需求和面向用户文档的权威入口。
测试用例与验收证据的分工
docs/testing/ 和 docs/validation/ 是两类不同产物,不能互相替代:
| 维度 | docs/testing/ | docs/validation/ |
|---|---|---|
| 回答的问题 | 应该验证什么、怎么验证、预期结果是什么 | 在某台真实设备上实际验证的结果是什么 |
| 产生时机 | 实现前或实现中,按需求验收条件设计 | 实现并构建完成后,在目标 fnOS NAS 上执行 |
| 内容 | 用例编号(<功能 ID>-TEST-##)、前置条件、步骤、预期结果、适用环境 | 设备与环境元信息、实际步骤与结果、日志与截图、结论与遗留问题 |
| 是否可复现 | 可被任何人按步骤重跑 | 一次性证据,绑定具体设备、版本和日期 |
| 失败时的用途 | 暴露规格歧义和覆盖缺口 | 暴露真实环境差异和发布阻断项 |
规则:
- 用例编号遵循「追踪 ID」一节的
<功能 ID>-TEST-##,与需求功能和验收条件一一对应;不写只覆盖实现细节、无法回溯到验收条件的用例。 - 用例通过只说明设计与本地验证成立;不能用它勾掉验收条件,也不能代替目标环境结论。
- 目标环境执行后,结论写入
docs/validation/,并在回写需求/计划状态时同时引用用例编号和证据编号。 - 本地可自动化的部分(
pnpm run check、pnpm run lint、bash -n、fnpack build)应在用例里写成可执行命令,不要只写「人工确认」。
变更分类
| 变更类型 | 必需产物 | 最低验证 |
|---|---|---|
| 新功能、用户行为、权限、数据、网关或插件契约变化 | 需求规格 + 实施计划 + 验收条件 | 代码/测试 + 文档构建;涉及 fnOS 时必须真实 NAS 验收 |
| 现有功能行为修复 | 原需求变更记录 + 计划调整;影响较大时新增需求 | 回归测试和对应环境验证 |
| 安全、依赖、构建或发布变化 | 变更说明 + 风险/回滚 + 校验结果 | 受影响的构建、安装、升级或安全检查 |
| 仅文档、格式或内部重命名 | 变更说明 | git diff --check 和 pnpm run build -- --docs |
标准流程
提出变更
├─ 记录或新增需求规格
├─ 评审范围、优先级和验收条件
├─ 建立对应实施计划和任务追踪
├─ 编码并补齐测试/构建验证
├─ 在目标 fnOS NAS 完成功能验收
├─ 写入验收证据并回写需求/计划状态
└─ 关联版本、变更记录和回滚方式未进入计划的 P2、后续计划和未确认能力不得出现在当前计划的阶段任务、详细交互、完成状态或测试清单中。
追踪 ID
新增 P0/P1 功能建议形成以下链路:
| 对象 | 格式 | 示例 |
|---|---|---|
| 需求功能 | FNOS-###-## | FNOS-001-10 |
| 验收条件 | <功能 ID>-AC-## | FNOS-001-10-AC-01 |
| 计划任务 | PLAN-FNOS-###-T##-## | PLAN-FNOS-001-T10-01 |
| 测试场景 | <功能 ID>-TEST-## | FNOS-001-10-TEST-01 |
| 环境证据 | <功能 ID>-ENV-## | FNOS-001-10-ENV-01 |
每个 P0/P1 功能至少要能从需求追踪到验收条件、计划任务、测试和目标环境结论。计划文档可以维护追踪矩阵,不复制需求正文。
状态规则
已完成:代码、必要构建和目标环境验收全部完成。待完成:代码或本地验证完成,但目标环境尚未验收。规划中:已进入计划,尚未完成实现。待验证:依赖 SDK、宿主、权限的事实确认。待确认:需求边界尚未确认,未进入计划。后续计划:已登记但未进入当前计划。
状态变化必须追加到需求或计划的变更记录,不能只修改徽章。
路径约束
仓库内所有被跟踪文件禁止写入指向开发者本机的绝对路径。这类路径换一台机器或换一个 CI runner 就失效,且会把个人目录结构带进版本库。需要引用仓库内的文件时,改用相对路径或仓库别名。
禁止的形式包括:
- 用户主目录:
/Users/<name>/...、/home/<name>/...,以及~展开后的绝对路径。 - 机器专属的工具安装位置:
/opt/homebrew/...(Apple Silicon Homebrew)这类只在某台个人机器上成立的路径。 - 个人临时目录:
/private/tmp/...、/var/folders/...。 - Windows 盘符路径:
C:\...、/mnt/c/...。
通用系统位置不受此限制。/usr/local/bin、/usr/bin、/etc/... 在 CI runner 和目标设备上语义稳定,CI 安装步骤、安装文档指引和 fnOS 设备端脚本可以继续使用。
替代写法:
| 场景 | 写法 |
|---|---|
| 引用仓库内文件 | 仓库根相对路径,例如 tooling/fn-os-apps-cli/src/index.ts |
| 脚本内定位同目录文件 | 基于脚本位置推导,例如 "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" |
| 文档内页面互链 | VitePress 路由别名,例如 /development/sdd-workflow |
| 本机工具 | 依赖 PATH 解析(配置项留空或写工具名),不要写死安装目录 |
例外:fnOS 部署契约要求的设备端路径不是本机路径,允许保留。典型是生命周期脚本中的 TRIM_* 变量,以及官方运行时文档规定的跨应用运行时引用(例如 install_dep_apps = python312 之后在 cmd/install_callback 中设置 /var/apps/python312/target/bin)。这类路径指向目标 NAS,在开发机上本来就不存在,写绝对路径是契约要求。使用时应在注释中说明它指向 fnOS 设备环境,避免被误认为本机路径。
PR 检查清单
- [ ] 已填写变更类型、需求编号和计划编号;纯文档/格式变更已说明豁免原因。
- [ ] 新增或修改的用户行为有可观察的验收条件。
- [ ] 计划只包含已进入实施阶段的功能。
- [ ] 已运行与改动相关的插件测试、构建、
pnpm run check -- --sdd和pnpm run build -- --docs。 - [ ] 涉及 fnOS 权限、宿主、FPK 安装或升级的功能已记录真实 NAS 验收状态。
- [ ] 已说明数据影响、敏感信息、升级兼容和回滚方式。
- [ ] 需求、计划和验证记录中的链接与追踪 ID有效。
- [ ] 改动中没有开发者本机绝对路径;设备端路径已注明指向 fnOS 环境。
例外规则
依赖升级、构建修复和紧急安全修复可以不新增完整用户需求,但必须在 PR 和变更记录中说明原因、影响、验证和回滚方式。紧急修复完成后,应在下一个维护周期补齐受到影响的需求或决策记录。