跳转至

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 零命中)

后果链(服务端未上线故尚未发生,一上线即成立):

  1. 用户 A 登录 → 通道 B 用 clientId X 注册得 anonymousUserId = U1 → 数据挂 U1
  2. A 登出 → uid/accesstoken 清空,clientId 仍是 X
  3. 用户 B 在同一台机器登录 → 仍是 clientId X → 仍是 U1
  4. 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. 服务端侧必须确认的

契约已写的不重复问,这里只列契约没写死、而客户端修复依赖它的:

  1. /contact-pool/upload 是否逐条返回 accepted/rejected?—— 第 6 条改造依赖它。
  2. 被拒条目是否携带原因?—— 第 8 条退避策略依赖它。
  3. 同一 logged-in-user-id 在多台设备上的 clientId 如何归并?
  4. 用户从匿名转为登录时,此前匿名身份下的数据如何处理?(见 §6 决策)

6. 待 Tony 拍板(收窄为两条)

决策 1、3 是真取舍;原先以为要拍的「要不要绑定」已由契约 §0.2 回答,不再需要重拍。

  • 决策 1:两套通道的归宿 —— 并存 / 通道 B 上线后接管 / 明确分层永不合并
  • 决策 2:登出时已上传的匿名数据归属 —— 留在匿名身份下 / 标记孤儿 / 允许下次登录认领

这两条不定,本 spec 停在 draft,不进开发。 第 4 节改造清单里,第 4-10 条不依赖这两个决策,可以先做。

7. 关联