refactor: 重构文档结构与环境配置，统一研发工单命名

1. 更新 .env 配置文件，替换原有云同步变量为 API 目标配置 2. 调整 publish-linux.ps1 中的文档路径，使用研发工单目录 3. 重构项目文档目录：将原 v1.2.0-tasks 迁移为研发工单-v1.2.0 目录，统一术语为"研发工单"替代"任务" 4. 更新 README.md 与各 PRD 文档的术语对照表，明确业务实体与研发工作项的区分 5. 新增多个研发工单文档，覆盖搜索、云同步、Linux 打包等模块 6. 删除旧的任务拆分文档，统一使用新的研发工单体系
2026-06-14 00:58:26 +08:00
parent a7ba814833
commit d81aa06681
18 changed files with 162 additions and 112 deletions
@@ -0,0 +1,49 @@
+# 05 - 云同步（基础可用）：客户端配置与同步工作流
+
+> 术语：本工单文件归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。
+
+## 目标（PRD 约束）
+
+- 首次启用同步时，用户需要**手动填写服务端地址**（例如 `https://example.com`），并允许后续在设置中修改
+- 客户端对地址格式做基础校验，并在保存时提示可达性/证书异常等风险信息
+- 用户登录成功后，从服务端获取该用户 Todo 数据并更新到前端展示
+
+## 范围（建议最小闭环）
+
+- "同步设置"入口与界面（服务端地址、登录、同步开关）
+- 地址校验与风险提示
+- 登录后拉取 Todo 数据并刷新 UI
+- 与本地数据的关系（v1.2.0 建议先做到"服务端为准/或本地为准"的单一策略，避免引入复杂冲突解决）
+
+## 依赖
+
+- 依赖 `04-*` 提供可用的服务端接口（至少登录 + 获取 Todo 数据 + 获取安全策略）
+- 与 `03-*`（Search）互不影响，可并行
+
+## 关键交互与状态
+
+需要定义并贯穿实现的状态机（至少包含）：
+- 未配置服务端地址
+- 已配置未登录
+- 已登录（可同步）
+- 同步中/同步失败/同步成功（含失败原因）
+
+## 实施步骤（建议）
+
+1. 增加"同步设置"UI
+   - 放置在主界面可发现位置（例如顶部右侧设置按钮/侧边栏）
+2. 服务端地址配置
+   - 基础校验：`https?://`、host 合法性、尾部 `/` 处理规则
+   - 保存时探测：尝试请求服务端健康检查或登录端点（并提示证书异常/不可达等）
+3. 登录与凭据存储策略（与 `06-*` 协同）
+   - 在允许落盘场景下可持久化 token/会话
+   - 在禁止落盘场景下仅保留内存会话（退出即失效）
+4. 登录后拉取 Todo 数据
+   - 拉取成功后更新前端 Todo 列表
+   - 拉取失败给出可理解提示，并允许重试
+
+## 验收标准
+
+- 首次启用同步必须先配置服务端地址；地址非法时不可保存并提示原因
+- 保存地址时能提示"不可达/证书异常"等风险信息（至少能区分：成功、失败、存在风险但可继续）
+- 登录后能从服务端拉取 Todo 数据并展示在主界面