功能规格说明书：<产品名>¶

版本：v0.1 日期：作者：<姓名 / AI Agent> 状态：draft / review / approved 关联：user-story.csv、user-story-details.md、schedule.md

约定：每个功能需求使用显式锚点，供 CSV 的 spec_ref 引用，例如： <a id="fr-001"></a> 后接 ### FR-001 用户登录。

1. 背景与问题¶

1.1 背景¶

<描述业务背景、现状、为什么现在要做。>

1.2 问题¶

<用可观察的事实描述问题，而不是解决方案。>

问题 1：<...>
问题 2：<...>

1.3 机会¶

<解决这个问题能带来什么价值。>

2. 目标与非目标¶

2.1 目标¶

G1：<可衡量的目标>
G2：<...>

2.2 成功指标¶

指标	当前	目标	测量方式
<指标>	<基线>	<目标>	<方法>

2.3 非目标（明确不做）¶

NG1：<...>
NG2：<...>

非目标不是“以后可能做”，而是“本期明确不做”。它用于防止范围蔓延。

3. 用户与角色¶

角色	描述	核心诉求	权限概要
<角色 A>	<...>	<...>	<...>
<角色 B>	<...>	<...>	<...>

3.1 权限矩阵¶

操作	角色 A	角色 B	角色 C
查看	✅	✅	✅
创建	✅	✅	❌
修改	✅	仅自己的	❌
删除	✅	❌	❌
管理成员	✅	❌	❌

4. 核心用户旅程¶

4.1 主旅程¶

用户打开产品
  → 登录
  → 进入工作台
  → 选择/创建项目
  → 创建任务
  → 分配给成员
  → 成员收到通知
  → 更新状态
  → 完成

4.2 异常旅程¶

登录失败：<...>
无权限：<...>
网络失败：<...>
数据为空：<...>
并发冲突：<...>

5. 功能需求（FR）¶

FR-001 <功能名>¶

描述：<系统应……>

规则：

<可测试的规则>
<...>

输入：

字段	类型	必填	约束
<字段>	<类型>	是/否	<约束>

输出：

成功：<状态码、数据结构>
失败：<错误码、提示>

异常：

场景	错误码	HTTP 状态码	用户提示
<场景>		<4xx>	<提示>

权限：<谁能做>

审计：<记录什么>

可观测性：<日志/指标>

FR-002 <功能名>¶

（重复上述结构）

6. 非功能需求（NFR）¶

类别	要求	可测试的写法
性能	<...>	P95 < 300ms（100 并发）
可用性	<...>	月度 ≥ 99.9%
安全	<...>	所有对象级权限在后端校验
隐私	<...>	日志不含密码/令牌/身份证
可观测性	<...>	每个请求有 request_id
兼容性	<...>	Chrome/Safari/Edge 最近两个大版本
可访问性	<...>	关键流程可键盘完成，对比度 ≥ 4.5:1
国际化	<...>	文案集中管理，支持中英文

7. 数据实体与关系¶

User 1 ──── N ProjectMember N ──── 1 Project
                                      │
                                      └── 1 ──── N Task
                                                    │
                                                    └── 1 ──── N Comment

实体	说明	关键字段	生命周期
User	用户	id, email, display_name, status	创建/禁用/删除
Project	项目	id, tenant_id, name, status	创建/归档/删除
Task	任务	id, project_id, title, status, due_date	创建/完成/删除
Comment	评论	id, task_id, author_id, body	创建/编辑/删除
AuditLog	审计	id, actor_id, action, resource	只追加

7.1 状态机¶

Task.status:
  todo ──► in_progress ──► done
    ▲           │
    └───────────┘

规则：

允许回退，但记录审计。
已完成任务修改状态需要管理员权限。
并发更新使用乐观锁 version。

8. 权限模型¶

租户级：用户只能访问所属租户。
项目级：admin / member / viewer。
对象级：任务、评论、附件都校验项目成员身份。
后端必须校验；前端隐藏按钮只是体验。

8.1 越权检查清单¶

非成员访问项目 → 403
viewer 创建任务 → 403
跨租户访问 → 404/403
修改他人任务 → 按规则
删除非自己创建的数据 → 按规则

9. 错误与异常处理¶

9.1 统一错误格式¶

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "标题不能为空",
    "request_id": "01J...",
    "details": { "field": "title" }
  }
}

9.2 错误码¶

错误码	含义	HTTP
VALIDATION_ERROR	参数校验失败	400
UNAUTHORIZED	未认证	401
FORBIDDEN	无权限	403
NOT_FOUND	资源不存在	404
CONFLICT	状态冲突	409
RATE_LIMITED	限流	429
INTERNAL_ERROR	内部错误	500

9.3 异常场景¶

网络超时：<重试/提示>
第三方失败：<降级/提示>
数据库不可用：<503/重试>
并发冲突：<409/提示刷新>
数据为空：<空状态>

10. 验收标准¶

10.1 功能验收¶

10.2 非功能验收¶

性能达标
安全扫描无高危
日志/指标可用
可访问性达标

10.3 验收方式¶

单元/集成测试；
Chrome MCP E2E + 截图；
Word 报告人工走查；
生产环境验证。

11. 范围之外¶

<功能/平台/集成>
<...>

任何新增需求必须走变更流程（CR），并重新评估排期。

12. 假设与待确认问题¶

12.1 假设¶

编号	假设	影响	确认人
A-001	<...>	<...>	<...>

12.2 待确认问题¶

编号	问题	负责人	截止日期	状态
Q-001	<...>	<...>	<...>	open

13. 成功指标与上线计划¶

指标	目标	测量
<...>	<...>	<...>

上线计划：

灰度范围：<...>
回滚条件：<...>
观察期：<...>

14. 范围确认¶

确认人：<姓名>
确认日期：
确认内容：P0/P1 范围、非目标、验收标准、排期
结论：通过 / 有条件通过 / 不通过
备注：<...>