SPEC-011 云端同步身份模型与契约实现差距¶
本文用途:移交开发。
🔴 服务端 API 契约不在本文 —— 它在 SPEC-004-phase3-api-contract,那份已经完整 (12 个端点,含请求/响应体、鉴权、幂等、速率限制)。本文不重复它,只补三件它没有的: ① 通道 A 的存在 ② 契约与实现的差距 ③ 身份绑定的落地说明。
全部 file:line 为 2026-08-31 在 main@13f945c 实测核实。
0. 一句话结论¶
身份绑定不是待设计的新问题,是契约早已写定、实现漏了一半。
SPEC-004-phase3-api-contract §0.2 明确规定 X-Client-Id 可以是
anonymous-uuid 或 logged-in-user-id,session_token 有两个来源
(已登录复用既有 token / 匿名注册)。实现只做了匿名那条。
1. 两套通道并存(SPEC-004 契约未覆盖通道 A)¶
flowchart TD
A[扩展] --> B[通道A · 已上线]
A --> C[通道B · 服务端未上线]
B --> D[web.laifaxin.com<br/>/api/ext/search/data-sync]
C --> E[cloud.laifaxin.com/api/v1<br/>SPEC-004 契约]
D --> F[身份 = 产品账号<br/>uid + accesstoken]
E --> G[身份 = 匿名<br/>clientId 恒定]
| 通道 A(活的) | 通道 B(未上线) | |
|---|---|---|
| 入口 | apiSearchDataSync → /api/ext/search/data-sync (src/api/search.ts:13) |
cloud-sync-client.ts 9 个端点 |
| base | web.laifaxin.com(src/utils/common.ts:12) |
cloud.laifaxin.com/api/v1(cloud-sync-client.ts:11) |
| 鉴权 | local:accesstoken + uid(src/api/request.tsx:13-14) |
匿名 clientId → token |
| 触发 | 每 10 秒轮询(cloud-data-sync.tsx:80) |
手动 / 定时,默认关 |
| 启用条件 | uid 非空 且 mapDataSync 且 mapVipValid(:52 :68) |
enableCloudSync,默认 false(storage-data.ts:253) |
| 数据 | 搜索结果行 | ContactPool / DomainState / ContributionLedger |
🔴 两条通道之间没有任何代码关联。 这是 SPEC-004 契约设计时未纳入考虑的既成事实。
2. 契约与实现的差距(移交开发的核心清单)¶
2.1 端点覆盖:契约 12 个,实现 9 个¶
| 端点 | 契约 | 实现 |
|---|---|---|
/health /anonymous/register |
有 | 有 |
/contact-pool/{upload,query,since} |
有 | 有 |
/domain-state/{upload,list} |
有 | 有 |
/contribution/{log,balance} |
有 | 有 |
/me |
有 | 缺 |
/contribution/history |
有 | 缺 |
/leaderboard |
有(标 Phase 3.5 可选) | 缺 |
实现没有越界端点(实现有、契约无 = 0)。
🔴 /me 的缺失最关键:它是契约里「当前用户信息(实名 OR 匿名)」的端点,
响应含 isAnonymous 字段 —— 正是身份绑定的核心。没有它,客户端无从知道自己当前算谁。
2.2 身份:契约两条来源,实现只做了一条¶
| 契约(§0.2) | 实现 | 出处 |
|---|---|---|
X-Client-Id: <anonymous-uuid 或 logged-in-user-id> |
无条件传匿名 clientId | cloud-sync-client.ts:126 |
| session_token 来源 1:已登录 → 复用既有 token | 未实现:全文零处读 accesstoken / StorageKey.uid |
grep 零命中 |
| session_token 来源 2:匿名注册 | 已实现 | :222-241 |
2.3 版本号两处硬编码¶
| 位置 | 值 | 应为 |
|---|---|---|
cloud-sync-client.ts:125 |
X-Client-Version: '0.10.95' |
manifest 版本 |
cloud-sync-client.ts:229 |
register body version: '0.10.95' |
同上 |
当前版本 0.10.124。服务端若按 version 做灰度或兼容判断,会一直看到 0.10.95。
3. 身份割裂的后果(P1-12 展开)¶
3.1 登出不清匿名身份¶
auth-provider.tsx clearAuth() 只清 StorageKey.uid + StorageKey.accesstoken
cloud-sync-client.ts local:cloudSync:{token,clientId,userId}
无任何清理路径(全仓 grep clearToken/resetCloudSync 零命中)
后果链(服务端未上线故尚未发生,一上线即成立):
- 用户 A 登录 → 通道 B 用 clientId
X注册得anonymousUserId = U1→ 数据挂 U1 - A 登出 → uid/accesstoken 清空,clientId 仍是 X
- 用户 B 在同一台机器登录 → 仍是 clientId
X→ 仍是 U1 - B 的数据与 A 的混在同一匿名身份下
3.2 首次同步并发注册竞态(P1-14)¶
cloud-sync-orchestrator.ts:292-296 三路并发调 ensureAuth();
ensureAuth() 的「检查—注册—写入」三步非原子(cloud-sync-client.ts:222-241),
三路可各自注册,最终 token / userId 落成互不匹配的组合。
4. 客户端改造清单(可逐条验收)¶
| # | 改什么 | 对应 | 验收 |
|---|---|---|---|
| 1 | 按契约 §0.2 补「已登录复用既有 token」分支;X-Client-Id 登录后传 uid |
P1-12 | 登录态下请求头 X-Client-Id = uid |
| 2 | clearAuth() 同时清 local:cloudSync:* |
P1-12 | 登出后 clientId 轮换 |
| 3 | 实现 GET /me,用 isAnonymous 判定当前身份 |
本文新增 | 客户端能自陈当前算谁 |
| 4 | ensureAuth() 加互斥或幂等保护 |
P1-14 | 三路并发后 token/userId 匹配 |
| 5 | writeCloudRecords 补邮箱质量防线(dedup / lowercase / broken) |
P1-02 | 脏邮箱不进云端 |
| 6 | markUploaded 按服务端逐条 accepted/rejected 处理 |
P1-11 | 被拒条目不标已上传 |
| 7 | 云端拉取不覆盖本地待上传记录 | P1-15 | 待上传行保留上传资格 |
| 8 | 被拒条目退避,不永久占据 FIFO 队首 | P1-16 | 队列可推进 |
| 9 | writeContactRecord 与 existing 取并集 |
P1-20 | 本地结果不覆盖云端共识 |
| 10 | 版本号改读 manifest(两处) | 本文新增 | 请求头与 body 带真实版本 |
5. 服务端侧必须确认的¶
契约已写的不重复问,这里只列契约没写死、而客户端修复依赖它的:
/contact-pool/upload是否逐条返回 accepted/rejected?—— 第 6 条改造依赖它。- 被拒条目是否携带原因?—— 第 8 条退避策略依赖它。
- 同一
logged-in-user-id在多台设备上的 clientId 如何归并? - 用户从匿名转为登录时,此前匿名身份下的数据如何处理?(见 §6 决策)
6. 待 Tony 拍板(收窄为两条)¶
决策 1、3 是真取舍;原先以为要拍的「要不要绑定」已由契约 §0.2 回答,不再需要重拍。
- 决策 1:两套通道的归宿 —— 并存 / 通道 B 上线后接管 / 明确分层永不合并
- 决策 2:登出时已上传的匿名数据归属 —— 留在匿名身份下 / 标记孤儿 / 允许下次登录认领
这两条不定,本 spec 停在 draft,不进开发。 第 4 节改造清单里,第 4-10 条不依赖这两个决策,可以先做。
7. 关联¶
- SPEC-004-phase3-api-contract —— 服务端 API 契约(权威源,本文不重复)
- SPEC-010-current-defect-triage §8-4 与 Phase 4 七个前置
- cloud-sync-architecture —— 架构 wiki