doc:输出1.2.0版本需求文档

2026-04-07 00:21:15 +08:00
parent 141b3112a4
commit 18d37fdd24
13 changed files with 485 additions and 45 deletions
@@ -0,0 +1,51 @@
+# 04 - 云同步（基础可用）：服务端基础能力
+
+## 目标（PRD 约束）
+
+- 支持用户级任务数据同步/读取（用户隔离）
+- 提供基于角色/权限的访问控制（RBAC）
+- 对高风险操作支持二次认证（能力以服务端实现为准）
+- 下发“可控落盘”配置（服务端配置驱动）
+
+## 范围（建议最小闭环）
+
+- 认证（登录/会话）
+- 任务数据 API（按用户隔离）
+- 配置下发 API（是否允许落盘、终端可信度/会话策略等）
+- RBAC 最小落地（至少能区分“允许同步/禁止同步”或“只读/读写”）
+- 二次认证最小落地（至少覆盖“启用/关闭同步、切换账号、调整落盘策略”等高风险操作的接口）
+
+## 依赖
+
+- 与 `05-*`（客户端）可并行推进，但需要尽早冻结 API 契约（字段名/响应结构/错误码）
+
+## 接口契约（需要在实现前先写清楚）
+
+建议输出一份“云同步 API 契约”并固化到 docs（便于客户端对接）。至少包含：
+- 登录：`POST /auth/login`（或等效）
+- 获取用户任务：`GET /tasks`（或等效，支持增量/版本号是加分项，但 v1.2.0 可先全量）
+- 上传/同步：`POST /sync`（或按任务粒度的增删改接口）
+- 获取安全配置：`GET /security/policy`
+  - 返回字段至少包含：`allowPersist`（是否允许落盘）
+  - 可扩展：`deviceTrust`、`sessionTtl`、`requireSecondFactorFor` 等
+
+## 关键实现点（建议）
+
+1. 用户隔离
+   - 服务端所有读写必须绑定当前登录用户上下文
+2. 权限模型（RBAC）
+   - 定义最小角色：例如 `user`、`admin`
+   - 定义最小权限：例如 `tasks:read`、`tasks:write`、`sync:enable`
+3. 二次认证
+   - 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现“二次口令”）
+   - 能力不足时必须返回明确错误，使客户端可提示用户
+4. 落盘策略下发
+   - 支持按用户或按会话/终端下发
+   - 默认策略建议为“允许落盘”，便于可用性；但需支持“禁止落盘”
+
+## 验收标准
+
+- 使用不同用户登录后获取任务，数据严格隔离
+- 未授权角色/权限访问受限接口会被拒绝（错误响应可被客户端识别）
+- 能返回安全策略配置（至少包含 `allowPersist`），并可通过配置切换行为
+