Arkie-Library-Frontend/docs/backend-requirements-wallet-favorites.md

后端需求与核对文档：钱包登录 + 收藏

面向后端（Arkie-Library-Backend）。 本文是在前端审计「登录 + 收藏」bug 与 UI 重设计时，对后端现有实现的逐条核对，以及由此产生的后端待办。

核心结论：后端目前几乎已经满足前端全部需求。本次重设计与 bug 修复基本是纯前端工作。后端真正需要新增的只有少量「可选项」，外加几处需要确认的契约。请不要把已完成的功能再派一遍。

日期：2026-06-02（2026-06-02 更新：新增 §0.5 部署阻塞） 相关分支：terry-wallet-login

---

0.5 🔴 关键阻塞：线上后端是旧版本，收藏与 TokenPocket 端点未部署

源码（Arkie-Library-Backend）里这些端点都有；但当前线上 / dev 代理指向的后端（https://ark-library.com/apnew）是旧构建，下列路由全部 404。 前端已就绪，但收藏与 TokenPocket 扫码登录在生产上无法工作，直到后端把含这些路由的版本部署上线。 这正是用户实测「收藏用不了、扫码登录用不了」的根因。

curl 实证（经 vite dev 代理打到线上后端，2026-06-02）：

端点	方法	实测状态	结论
/api/auth/wallet/nonce	POST	200	✅ 已部署
/api/auth/wallet/verify	POST	400（入参错误）	✅ 已部署
/api/auth/wallet/me	GET	401（需鉴权）	✅ 已部署
/api/auth/wallet/tp-login-request	POST	404	❌ 未部署
/api/auth/wallet/tp-result	GET	404	❌ 未部署
/api/auth/wallet/tp-callback	POST	404	❌ 未部署
/api/me/favorites	GET	404（应为 401）	❌ 未部署
/api/me/favorites/ids	GET	404	❌ 未部署
/api/me/favorites/{id}	POST	404	❌ 未部署

后端动作（必做，按优先级最高）：

1. 部署包含 favorites（internal/handlers/favorites.go）+ TokenPocket（internal/handlers/wallet_tp.go）路由的后端版本（cmd/server/main.go 已注册这些路由）。
2. 为 TokenPocket 登录设置 PUBLIC_BASE_URL（buildTokenPocketSignURL 需要它生成回调 URL，否则 tp-login-request 会 500）。
3. 确保 wallet_tp_login_requests / user_favorites 等表已迁移（EnsureWalletAuthSchema 会建表）。

复测命令：curl -s -o /dev/null -w "%{http_code}" -X POST https://ark-library.com/apnew/api/auth/wallet/tp-login-request -d '{}' 应返回 200（且 body 的 qrUrl 形如 tpoutside://pull.activity?param=...）。

---

0. 一句话给后端

钱包认证、TokenPocket 扫码、收藏列表/筛选/分页/可用性，都已实现且符合前端契约。 下面 §1 是「已完成、勿动」的核对；§2 是「真正可能要后端做的事」；§3 是「前端会改但与后端无关，别误接」。

---

1. 已实现并符合前端契约（✅ 无需改动）

逐条核对自后端源码（internal/handlers/wallet_auth.go、wallet_tp.go、favorites.go、public.go、cmd/server/main.go）。

1.1 钱包认证

端点	状态	说明
POST /api/auth/wallet/nonce	✅	返回 {nonce, message}，message 含一次性码，写入 wallet_auth_nonces，TTL 15 分钟
POST /api/auth/wallet/verify	✅	EIP-191 personal_sign 验签恢复地址，签发 JWT
GET /api/auth/wallet/me	✅	Bearer JWT → {wallet, role:"user"}

关键事实（对前端 bug 很重要）：

• 验签完全链无关。 recoverPersonalSign 只做 EIP-191 文本哈希恢复，不校验任何 chainId。签名消息文案是 "ARK Database — wallet sign-in … Sign this message to log in. No transaction or gas fee."，不引用任何链。 → 因此前端登录时强制切到 BNB 链（ensureBnbChain）是多余的，删除它不影响后端。这是一项纯前端修复。
• JWT：HS256，有效期 30 天（SignUserWallet(..., 30*24h)），无状态。
• nonce 用后即删，过期自动清理。

1.2 TokenPocket 扫码登录

端点	状态
POST /api/auth/wallet/tp-login-request	✅ 生成 actionId/nonce/message/qrUrl，写 wallet_tp_login_requests
POST /api/auth/wallet/tp-callback	✅ 钱包回调写入签名，校验 callbackToken
GET /api/auth/wallet/tp-result?actionId=	✅ 轮询返回 pending/completed/expired/failed

→ 前端把扫码从「手机端」挪到「桌面端」只是 UI 位置调整，后端无需改动。

1.3 收藏

端点	状态	支持的能力
GET /api/me/favorites	✅	q（title/description/body_text/tag ILIKE）、category(slug)、sort(favorited_at/published_at/hot)、includeUnavailable(默认 true)、page/limit(≤100)、返回 total、tags、favoriteCount、availability
GET /api/me/favorites/ids?resourceIds=	✅	批量查询收藏状态
POST /api/me/favorites/{id}	✅	加收藏，返回 {ok,resourceId,favorited,favoriteCount}
DELETE /api/me/favorites/{id}	✅	取消收藏，favorite_count 不低于 favorite_base_count

关键事实：

• 下架资源可用性已支持。 scanFavoriteItem 会把 status!='published' 或 is_public=false 的资源标为 availability:"unavailable"，且默认 includeUnavailable=true 仍返回。→ 前端「不可用资源卡片」逻辑后端已就绪。
• sort=hot 定义 = download_count + favorite_count + share_count 降序。
• 鉴权失败统一返回 401。

---

2. 真正可能需要后端做的事

按优先级。除 2.1 外多为可选/按产品决定。

2.1 【需确认】CORS 允许前端源 + Authorization 头

前端通过 apiBase 调 /api/me/favorites，并带 Authorization: Bearer <jwt>。 若前端与 API 不同源，需确认 CORS 允许：

• 来源：前端正式域名（及预览/本地开发源）
• 方法：GET, POST, DELETE
• 请求头：Authorization, Content-Type

动作：确认现有 CORS 配置覆盖以上；若 apiBase 同源则可忽略。

2.2 【可选】服务端登出 / Token 失效

现状：JWT 无状态，前端「断开连接」只清本地 localStorage，旧 token 在 30 天内仍有效。

若产品需要「真正的远程登出 / 失效被盗 token」，后端需引入二选一：

• token 版本号（用户级 token_version，签发与校验时比对）；或
• token 黑名单（jti 撤销表）

默认建议：第一版不做，保持无状态。仅在有安全需求时再做。

2.3 【可选】缩短或可配置 JWT 有效期

现为固定 30 天。若希望更安全或可配置，可将 TTL 提为环境变量（如 USER_JWT_TTL）。

默认建议：30 天对「只验证地址、无资产操作」的场景可接受，可暂不动。

2.4 【按产品决定】MetaMask / imToken 扫码兜底（WalletConnect/Reown）

如果前端最终保留 WalletConnect 扫码路径：后端无需任何改动——/verify 接受任何 personal_sign 签名，与连接方式无关。 此项列出只为说明「即便前端接了 WalletConnect，也不产生后端工作」。

2.5 【可选打磨】收藏列表 q 搜索性能

当前 q 用多列 ILIKE '%..%'，数据量大时无法走索引。量级变大后可考虑 pg_trgm 或全文索引。

默认建议：当前数据量下不必做，记录备查。

---

3. 前端会改、但与后端无关（请勿误派给后端）

这些是本次 bug/重设计的主体，全部在前端完成，不涉及后端：

1. 删除登录时强制切 BNB 链（ensureBnbChain）—— 验签链无关（见 §1.1）。
2. 桌面登录弹窗简化为「使用浏览器钱包登录」单一主操作；扫码降级为「其他方式」。
3. 扫码从手机端挪到桌面端。
4. 手机端「打开钱包 App」死路修复（反馈、未安装兜底）。
5. 移除/收敛未被登录流程使用的 RainbowKit/WalletConnect 装配（纯前端依赖与体积问题）。
6. 全站「我的收藏」入口缺失（导航 / 手机菜单 / 钱包下拉加入口）。
7. 收藏按钮状态视觉、收藏页筛选区移动端密度、空/错误状态打磨。
8. token 过期时前端自动登出并引导重新登录（消费后端已返回的 401，无需后端改）。

---

4. 给后端的「确认清单」

• §2.1 CORS 是否已允许前端源 + Authorization 头？（唯一可能的必做项）
• 是否需要 §2.2 服务端登出/撤销？（默认否）
• 是否需要 §2.3 可配置 JWT TTL？（默认否，维持 30 天）
• 知悉：§3 全部为前端工作，无需后端介入。