跳转至

社区共享接口并入来发信主 API

给服务端开发的实现清单。 客户端 v0.10.95 已按 SPEC-004 完整实现, 本文只说「并入主 API 后有什么不同」+ 需要实现哪几个端点。

一、为什么并

现在的社区共享(SPEC-004) 来发信主 API
域名 cloud.laifaxin.com/api/v1 ggdt.laifaxin.com
路径风格 RESTful(GET /contact-pool/query) /api/ext/<模块>/<动作>,全 POST
鉴权 Authorization: Bearer <token> header uid + accesstoken
身份 可匿名(anonymous-uuid) 必须登录
实现状态 服务端 0 行代码 双方都在跑

并的三个理由:

  1. 两套鉴权 = 两套账号体系。 用户已经登录来发信账号(VIP 到期日就显示在扩展顶栏), 再给他一个匿名身份是多余的。
  2. 贡献度账本天然属于账号。 匿名的贡献度换设备就没了 —— 而贡献度是这个功能的激励内核。
  3. 少一个域名 = 少一套部署 / 证书 / 限流 / 监控。

✅ 二、匿名身份:砍掉(Tony 2026-09-17 拍板)

「匿名砍掉」

⇒ 下面的端点清单按「已砍」执行,服务端不需要实现匿名身份表、 匿名 token 签发、匿名转实名迁移。少一套身份体系。

原始权衡记录如下(供日后回看这个决定的依据):

原始权衡

SPEC-004 设计了匿名参与(不登录也能贡献和查池)。并入主 API 后这条路没了。

保留匿名 砍掉(建议)
服务端工作量 多 2 个端点 + 一套匿名身份表 + 匿名转实名的迁移逻辑 ——
贡献度 匿名的换设备就丢 跟账号走
现实 这个扩展本来就要登录才能用 与现状一致

⚠️ 置信度:「扩展必须登录」这一点我是从代码推的(顶栏显示 VIP 到期日、有账号 popover、 主 API 全部要 uid + accesstoken)。如果实际上有「不登录也能采」的路径,这个判断要改。

建议砍。 下面的清单按「砍掉」写。

三、要实现的 8 个端点

所有端点: - 方法:POST(跟现有 /api/ext/* 一致,即使语义是查询) - 鉴权:header uid + accesstoken,与 /api/ext/search/* 完全一致 - 响应:{ success: boolean, data: {...} },与现有一致 - 幂等:上传类带 header Idempotency-Key: <uuid>,服务端去重、重复请求返回首次结果

# 路径 用途 频率
1 /api/ext/pool/contact-upload 抓到 contact 后批量上传 客户端 30s debounce 批量
2 /api/ext/pool/contact-query 抓之前批量查命中(≤100 hash/次) 每批网站抓取前
3 /api/ext/pool/contact-since 增量拉取(预热本地缓存) 启动时 + 按需
4 /api/ext/pool/domain-upload 上传本地观察到的域名状态 5min debounce
5 /api/ext/pool/domain-list 拉云端权威域名状态 启动 + 每小时
6 /api/ext/pool/contribution-log 上报本地行为(挣/耗贡献度) 实时
7 /api/ext/pool/contribution-balance 查余额 打开设置页
8 /api/ext/pool/contribution-history 查流水 用户点开时

🔴 客户端现状 ↔ 服务端待实现(v0.10.202 补 · 给开发对照用)

Tony 问「数据池的 api 有哪些」。左边是客户端此刻真的在调的 (src/utils/cloud-sync-client.ts,已实现且跑得通,只是打不到服务端), 右边是并入来发信后要实现的。对照表比两份清单有用 —— 开发照着右边做, 客户端只改路径前缀和鉴权头,业务逻辑一行不动。

# 客户端现在调的 方法 鉴权 ⇒ 服务端要实现
1 /contact-pool/upload POST Bearer /api/ext/pool/contact-upload
2 /contact-pool/query POST Bearer /api/ext/pool/contact-query
3 /contact-pool/since GET + query Bearer /api/ext/pool/contact-since(改 POST + body)
4 /domain-state/upload POST Bearer /api/ext/pool/domain-upload
5 /domain-state/list GET + query Bearer /api/ext/pool/domain-list(改 POST + body)
6 /contribution/log POST Bearer /api/ext/pool/contribution-log
7 /contribution/balance GET Bearer /api/ext/pool/contribution-balance
8 /health GET 无 /api/ext/pool/health(含 minClientVersion)
9 /anonymous/register POST 无 🔴 不实现 —— 见下方「砍匿名的连带」

⚠️ 不鉴权的端点有两个,不是一个(v0.10.203 对抗审 terra 指出, 上一版这里写成「/health 是唯一公开端点」——错的, cloud-sync-client.ts:281 的 /anonymous/register 同样 authRequired: false)。

/health 返回 minClientVersion,服务端用它做「强制升级」的闸。 并入时这条别漏,否则老客户端永远没法被劝退。

🔴🔴 砍匿名的连带:客户端现在还在调一个将不存在的端点

本文开头写了「匿名已砍」(Tony 拍板),服务端不实现 /anonymous/register。 但 客户端的 ensureAuth()(cloud-sync-client.ts:271-290)现在就在调它 —— 没有 token 时先去注册一个匿名身份,拿到 token 才继续。

⇒ 服务端上线后,如果客户端这段不改: ensureAuth() 永远拿不到 token → 整个数据池功能一次都跑不起来, 而且失败在最外层,用户只会看到「同步没反应」,看不出是身份这一步断的。

这不是服务端的活,是客户端必须同批改的:

现在 并入后
无 token ⇒ POST /anonymous/register 换一个 直接用已登录账号的 uid + accesstoken
token 存 local:cloudSync:token 不再需要这个 key(登录态由来发信主客户端管)
有 anonymousUserId 概念 没有了,userId 就是真实用户 id

⇒ 实施顺序:客户端改 ensureAuth 必须早于或同批于服务端上线, 否则就是「服务端做好了,客户端还在敲一扇不存在的门」。

(这条是砍匿名那次决策没交代的连带,v0.10.203 补。)

⚠️ 上表第 8 条与上面「8 个端点」清单不是同一组: 上面那组把 contribution-history 算进去了,而客户端现在还没有调它(流水页未做); /health 则反过来 —— 客户端在调,上面那组没列。 真实的服务端工作量:8 个要实现的端点 (上表 1-8)+ contribution-history(客户端还没调,可延后); 第 9 行 /anonymous/register 不实现,但它逼出一条客户端必改项,见下。

🔴 「统一同步概览」缺一个接口(v0.10.202)

Tony 问「是不是……下边就是一个同步概览?」。 现在只有数据池那半有概览(Contact 数据池 / 贡献度账本 / 云端域名缓存), 「云端数据同步」(自己的采集结果备份)那半没有 —— 因为客户端没有任何接口 能问「我在云端备份了多少条」。

⇒ 要做统一概览,需要第 10 个端点:

# 路径 用途
10 /api/ext/pool/backup-stats 查当前账号的云端备份条数(商家 / 官网 / 邮箱 / 手机,按 syncTags 分组)

没有它,概览只能显示一半,那比不显示更容易让人误解成「另一半是 0」。

可选第 9 个:/api/ext/pool/leaderboard(排行榜)—— 它不影响功能闭环,第一版可以不做。

每个端点的 payload / response

完全照抄 SPEC-004-phase3-api-contract,只改三处:

  1. GET + query string → POST + body
  2. 去掉 Authorization 头,改用 uid + accesstoken
  3. response 里的 userId 从 anon-abc123 变成真实用户 id

契约里每个端点的 Request/Response JSON 都是完整的,直接拿。

砍掉的两个 + 一个不能砍(v0.10.205 订正)

🔴 上一版这一节标题写「砍掉的两个」,表里却列了 3 行, 而且 /health 在这里被判「砍掉」、在上方对照表里又写着「要实现」—— 同一份文档里自相矛盾(对抗审 dshf X_CLAIM 指出)。逐条订正:

原端点 处置 理由
POST /anonymous/register 砍 砍掉匿名身份(Tony 拍板)。⚠️ 但客户端 ensureAuth() 现在还在调它,见上方「砍匿名的连带」
GET /me 砍 apiAccountCurrent() 已有,不重复造
GET /health 🔴 不能砍 上一版的理由是「主 API 一直在跑,不需要单独探活」——这个理由只覆盖了探活。它还返回 minClientVersion,那是强制升级的闸:服务端靠它告诉老客户端「你该更新了」。主 API 能不能 ping 通,回答不了「这个版本还让不让用」。砍了它,老客户端永远劝不退。

⇒ 真实处置:砍 2 个(anonymous/register、me),保留 /health。

四、服务端要注意的三件

1. contact-query 是扣费接口

命中一条扣 1 贡献度(queryCost),未命中不扣。 ⇒ 它必须先查余额再返回,余额不足时返回什么要定: 拒绝查询?还是允许透支?这条要你拍。

2. consensus 需要多客户端独立上报才有意义

契约里 consensus(0-1)= N 个客户端独立报告同一结果的强度。 第一版如果只有你自己在用,这个值恒为 1 —— 可以先返回固定值,但别让客户端据它做判断。

3. 幂等键的保存期

Idempotency-Key 要存多久?建议 24 小时: 客户端的重试窗口远小于这个,而无限期保存会让表无限长。

五、客户端改动量

改什么 量
cloud-sync-client.ts 的 getBaseUrl() + apiFetch() 改走 umiRequest ~1 小时
删 ensureAuth() / refreshAuth() 的匿名分支 ~1 小时
10 个 api* 函数改路径与方法 ~1 小时
设置页「云端 API 地址」字段废弃(并入主 API 后没有自建余地) ~0.5 小时
测试跟进 ~2 小时

合计半天到一天。 服务端做完我这边接线很快。

⚠️ 连带:cloudSyncBaseUrl 这个设置项废弃后, v0.10.181 为它建的那套 https 判据(cloud-sync-url.ts + 发送点关口)也一起退休。 那是对的 —— 它当初存在就是因为用户能填任意地址。