社区共享接口并入来发信主 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 行代码 | 双方都在跑 |
并的三个理由:
- 两套鉴权 = 两套账号体系。 用户已经登录来发信账号(VIP 到期日就显示在扩展顶栏), 再给他一个匿名身份是多余的。
- 贡献度账本天然属于账号。 匿名的贡献度换设备就没了 —— 而贡献度是这个功能的激励内核。
- 少一个域名 = 少一套部署 / 证书 / 限流 / 监控。
✅ 二、匿名身份:砍掉(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,只改三处:
GET + query string→POST + body- 去掉
Authorization头,改用uid+accesstoken - 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 + 发送点关口)也一起退休。
那是对的 —— 它当初存在就是因为用户能填任意地址。