ShaoHua
5.0 KiB
5.0 KiB
04 - 云同步（基础可用）：服务端基础能力
目标（PRD 约束）
- 支持用户级任务数据同步/读取（用户隔离）
- 提供基于角色/权限的访问控制（RBAC）
- 对高风险操作支持二次认证（能力以服务端实现为准）
- 下发“可控落盘”配置（服务端配置驱动）
范围（建议最小闭环）
- 认证（登录/会话）
- 任务数据 API（按用户隔离）
- 配置下发 API（是否允许落盘、终端可信度/会话策略等）
- RBAC 最小落地（至少能区分“允许同步/禁止同步”或“只读/读写”）
- 二次认证最小落地（至少覆盖“启用/关闭同步、切换账号、调整落盘策略”等高风险操作的接口）
依赖
- 与
05-*（客户端）可并行推进，但需要尽早冻结 API 契约（字段名/响应结构/错误码）
接口契约（需要在实现前先写清楚）
v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结字段名/错误码）。
通用约定
- Base URL：由客户端配置（例如
https://{host}:{port}） - 认证：
Authorization: Bearer {accessToken} - 错误响应（统一结构）：
{ "code": "ERROR_CODE", "message": "Human readable message." }
错误码
UNAUTHORIZED：未登录或会话失效FORBIDDEN：权限不足（RBAC / 策略拒绝）SECOND_FACTOR_REQUIRED：需要二次认证（step-up）BAD_REQUEST：请求参数不合法NOT_FOUND：资源不存在
Auth
-
初始化管理员（仅当系统尚无云用户时允许一次）：
POST /auth/bootstrap- Body：
{ "userName": "admin", "password": "..." } - 200：成功；403：已初始化或不允许
-
登录：
POST /auth/login- Body：
{ "userName": "admin", "password": "..." } - 200：
{ accessToken, expiresAtUtc, userId, role, permissions[] }
-
二次认证（step-up，v1.2.0 最小实现为“复用登录口令进行再认证”）：
POST /auth/step-up- Header：
Authorization: Bearer ... - Body：
{ "password": "..." } - 200：
{ stepUpExpiresAtUtc }
Tasks
- 获取当前用户任务全量：
GET /tasks- Header：
Authorization: Bearer ... - 权限：
tasks:read - 200：
CloudTaskItem[]
Sync
- 上传/同步（增删改后返回最新全量）：
POST /sync- Header：
Authorization: Bearer ... - 权限：
sync:write - 二次认证：必需（否则返回
SECOND_FACTOR_REQUIRED） - Body：
{
"upserts": [
{ "id": 1, "title": "A", "priority": 1, "isCompleted": false, "parentTaskId": null },
{ "id": null, "title": "New", "priority": 1, "isCompleted": false, "parentTaskId": null }
],
"deletes": [2, 3]
}
- 200：
{
"serverTimeUtc": "2026-04-06T17:39:30.0281279Z",
"tasks": [ /* CloudTaskItem[] */ ]
}
Security Policy
- 获取安全策略（服务端下发）：
GET /security/policy- Header：
Authorization: Bearer ... - 权限：
policy:read - 200：
{
"allowPersist": true,
"allowSync": true,
"requireSecondFactorFor": ["sync:write", "policy:write"]
}
- 更新安全策略（高风险操作）：
PUT /security/policy- Header：
Authorization: Bearer ... - 权限：
policy:write - 二次认证：必需（否则返回
SECOND_FACTOR_REQUIRED） - Body：
{ "allowPersist": false, "allowSync": false }
关键实现点（建议）
详细实现方案请参考：06.1-CloudSync-服务端安全设计方案.md
- 用户隔离
- 服务端所有读写必须绑定当前登录用户上下文
- 权限模型（RBAC）
- 定义最小角色：例如
user、admin - 定义最小权限：例如
tasks:read、tasks:write、sync:enable
- 定义最小角色：例如
- 二次认证
- 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现“二次口令”）
- 能力不足时必须返回明确错误，使客户端可提示用户
- 落盘策略下发
- 支持按用户或按会话/终端下发
- 默认策略建议为“允许落盘”，便于可用性；但需支持“禁止落盘”
验收标准
- 使用不同用户登录后获取任务，数据严格隔离
- 未授权角色/权限访问受限接口会被拒绝（错误响应可被客户端识别）
- 能返回安全策略配置（至少包含
allowPersist），并可通过配置切换行为
当前实现说明（v1.2.0）
- 数据隔离：
Tasks表新增UserId外键，云端 API 的所有读写按当前会话用户隔离；本地模式使用固定的local用户 ID（不影响既有 Dynamic API）。 - RBAC：内置
admin / user / readonly / nosync角色与权限映射；并叠加SecurityPolicies.AllowSync作为“是否允许同步写入”的策略开关。 - 二次认证：通过
POST /auth/step-up将会话提升到 step-up 状态；POST /sync与PUT /security/policy会强制要求 step-up。