需求清单
这里记录三方飞牛应用项目的正式需求。需求文档描述“要解决什么问题、涉及哪些范围以及如何验收”；具体实现方案放在对应的详细计划中。
需求与计划的边界
需求和计划不是同一份文档的重复版本：
- 需求文档记录完整的需求范围，包括已经完成、正在规划、待验证以及暂未排期的功能。
- 计划文档只记录已经进入当前实施阶段的功能，负责说明具体实现、交互、验证和发布方式。
- 需求中的 P2 或“后续计划”可以保留在需求清单中，但未正式进入计划前，不得出现在计划的阶段任务、详细交互、完成状态或测试清单中。
- 需求范围发生变化时，先更新需求文档；确认进入实施后，再在对应计划中增加任务并记录变更。
- 需求验收完成后，需求文档和计划文档都要更新状态；只有在目标环境完成验收后，才能标记为“已完成”。
文档关系如下：
text
需求提出
└─ 需求文档：范围、优先级、状态、验收条件
└─ 进入计划
└─ 计划文档：架构、交互、实现、测试、发布
└─ 目标环境验收
└─ 回写需求和计划的完成状态需求文档规范
文件位置和命名
需求文档统一放在 docs/requirements/，文件名使用：
text
FNOS-###-需求主题.md规则：
- 编号前缀使用需求主编号
FNOS-###，并在项目范围内保持唯一、连续。 - 需求主题使用简短、明确的中文或英文短语，概括需求的核心对象和目标；英文或多词名称使用短横线连接。
- 名称概括需求目标，不使用“修改”“临时”“test”等无法表达范围的名称。
- 日期不写入文件名前缀，需求正式确认或开始记录的日期保留在 Frontmatter 和元信息表中。
示例：
text
docs/requirements/FNOS-001-app-runtime-settings.md
docs/requirements/FNOS-002-package-install-flow.mdFrontmatter、标题和元信息
文档必须包含 title 和 description，一级标题与 title 保持一致：
yaml
---
title: FNOS-001 应用运行设置统一
description: 为需要运行参数的 fnOS FPK 应用补齐应用设置入口。
---
# FNOS-001 应用运行设置统一一级标题后使用元信息表，字段固定为：
| 字段 | 要求 |
|---|---|
| 需求编号 | 使用 FNOS-###，同一需求的功能使用 FNOS-###-## |
| 提出日期 | 使用需求正式确认或开始记录的日期，格式为 YYYY-MM-DD |
| 需求状态 | 使用状态徽章，表示整个需求的当前阶段 |
| 关联计划 | 已进入计划时链接到对应计划；未排期时写明“暂未进入计划” |
固定章节和内容要求
每篇需求文档按以下顺序编写，章节名称保持一致：
- 需求背景与目标：说明现状、问题、用户或宿主环境，以及本需求要达到的结果。
- 需求目标：用短句列出可判断的目标，不写具体代码实现。
- 涉及范围：用表格列出应用、插件、公共模块、目录或外部项目及其职责。
- 功能列表：列出用户可感知或可验收的功能。
- 交互和行为约束：记录文案、入口、权限、宿主差异和必须保持的行为。
- 不在本次范围内：明确不修改的源码、数据、平台能力和未承诺的兼容场景。
- 验收条件与完成状态：按优先级写验收条件，并用状态看板汇总阶段进度。
- 变更记录：追加需求范围、状态或验收规则的变化。
功能编号、优先级和状态
功能列表至少使用以下列：
| 编号 | 优先级 | 功能 | 用户行为 | 状态 |
|---|---|---|---|---|
| FNOS-###-01 | P0/P1/P2 | 可验收的功能名称 | 用户如何使用以及预期结果 | 状态徽章或状态文字 |
编号规则：
- 需求主编号在项目范围内递增，例如 FNOS-001。
- 功能编号继承主编号，例如 FNOS-001-01、FNOS-001-02。
- 历史需求整合后，以整合文档中的新编号为准；旧编号从现行文档和清单中移除，不再继续引用。
优先级含义：
| 优先级 | 含义 |
|---|---|
| P0 | 应用的运行基线，未完成会影响核心可用性 |
| P1 | 当前需求确定要实现的主要功能，可在 P0 稳定后实施 |
| P2 | 已记录但尚未进入当前实施阶段的扩展需求 |
统一状态含义：
| 状态 | 使用条件 |
|---|---|
| 已完成 | 代码、必要构建和目标环境验收均已完成 |
| 待完成 | 已有代码或本地验证，但目标环境尚未验收完成 |
| 规划中 | 已确认要实现，但实现尚未完成；通常已进入计划 |
| 待验证 | 依赖 SDK、fnOS 宿主接口等技术事实，需验证后才能确定实现方式 |
| 待确认 | 需求边界或交互方式尚未确认，未进入当前计划 |
| 后续计划 | 需求已登记，但尚未进入当前计划；不得在计划文档中展开实现任务 |
状态看板应优先使用 VitePress Badge，例如：
md
<Badge type="warning" text="待完成" />验收和状态规则
- 每个 P0/P1 功能必须有对应的验收条件，验收条件应描述可观察结果，而不是“代码已提交”。
- 涉及 fnOS NAS、权限、主题事件或 FPK 安装的功能，必须把真实 NAS 验收列为完成条件。
- 本地调试通过但尚未在目标 NAS 环境验证时，状态使用“待完成”，不能写“已完成”。
- 验收条件与完成状态中先按阶段说明验收条件，再用状态看板汇总当前状态和下一步。
- 状态变化必须追加到变更记录，不能只修改徽章而隐藏历史状态。
路径约束
需求和计划中不得写入指向开发者本机的绝对路径，需要引用仓库内容时使用仓库根相对路径或文档路由别名。完整的禁止形式和替代写法见 SDD 规格驱动维护规范 的「路径约束」一节。
fnOS 设备端路径（TRIM_* 变量、install_dep_apps 声明的跨应用运行时目录）属于部署契约，可以出现，但应注明它指向目标 NAS 而非开发机。
需求变更和历史整合
- 需求变更在原文档追加变更记录，不通过删除旧内容隐藏范围变化。
- 新增功能先加入需求文档并标记优先级和状态；只有确认进入实施后，才同步到计划文档。
- 历史需求整合后，整合文档作为当前唯一版本，重新使用当前有效编号；已迁移的历史 Markdown 内容应删除或停止作为现行入口维护。
- 需求清单只维护规范和当前整合结果，不复制应用或插件的实现说明。
当前需求文档
暂无现行需求文档。新增需求按上面的规范建立 docs/requirements/FNOS-###-需求主题.md，并在本表登记；确认进入实施后再同步到详细计划。