docs/backend-requirements-wallet-favorites.md

@@ -0,0 +1,133 @@
+# 后端需求与核对文档：钱包登录 + 收藏
+
+> 面向后端（`Arkie-Library-Backend`）。
+> 本文是在前端审计「登录 + 收藏」bug 与 UI 重设计时，对后端现有实现的逐条核对，以及由此产生的后端待办。
+>
+> **核心结论：后端目前几乎已经满足前端全部需求。本次重设计与 bug 修复基本是纯前端工作。后端真正需要新增的只有少量「可选项」，外加几处需要确认的契约。请不要把已完成的功能再派一遍。**
+
+日期：2026-06-02
+相关分支：`terry-wallet-login`
+
+---
+
+## 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 全部为前端工作，无需后端介入。

docs/superpowers/specs/2026-06-02-wallet-login-favorites-redesign-design.md

@@ -0,0 +1,183 @@
+# 钱包登录 + 收藏：重设计与 Bug 修复 设计文档
+
+日期：2026-06-02
+分支：`terry-wallet-login`
+范围：登录弹窗、Header/菜单钱包入口、收藏按钮、我的收藏页面、收藏入口
+关联：
+- 需求简报 `.unipi/docs/generated/2026-06-01-wallet-favorites-ui-redesign-requirements.md`
+- 后端核对 `docs/backend-requirements-wallet-favorites.md`
+
+---
+
+## 1. 目标
+
+把已上线的「钱包登录 + 收藏」从「功能能跑但设计未完善、桌面/手机均有 bug」提升到完成度合格：
+
+1. 修复登录流程中的真实功能 bug（强制切链、桌面误导、手机死路）。
+2. 按已批准的极简原则重做登录弹窗。
+3. 补齐完全缺失的「我的收藏」入口。
+4. 打磨收藏按钮状态与收藏页（移动端筛选、空/错误/不可用状态）。
+
+**关键事实**：经核对后端，钱包认证、TokenPocket 扫码、收藏接口（筛选/排序/分页/可用性/计数）均已实现并符合契约。**本次为纯前端工作**，后端仅需确认 CORS（见后端文档 §2.1）。
+
+---
+
+## 2. 登录架构（决策已定）
+
+三条路径共存，但 UI 上分主次：
+
+| 路径 | 用途 | UI 位置 |
+|---|---|---|
+| `window.ethereum` 注入登录 | 桌面插件 / 钱包内置浏览器 | **主路径** |
+| TokenPocket 自写扫码（deep link + 轮询） | 中国稳定扫码 | 「其他方式」折叠区 |
+| RainbowKit / WalletConnect | MetaMask / imToken 扫码兜底 | 「其他方式」折叠区 |
+
+**决策**：保留并**真正接上** RainbowKit（当前为未被调用的死代码）。
+**前置项**：需在环境变量配置有效的 `VITE_WALLETCONNECT_PROJECT_ID`（当前默认 `ark-library-dev-only` 无效）。WalletConnect 兜底在部分中国网络不稳定，UI 需提示。
+
+签名验证链无关（后端 EIP-191 personal_sign recover，消息不引用任何链）。
+
+---
+
+## 3. Bug 修复清单（前端）
+
+| # | 严重度 | 问题 | 修复 |
+|---|---|---|---|
+| B1 | 🟠 | 每次登录强制切 BNB 链（`ensureBnbChain`），多一个换网络弹窗，常见失败点 | 删除强制切链；`personal_sign` 不需要链 |
+| B2 | 🟠 | 桌面弹窗摆 3 个钱包按钮，点 TP/imToken 误弹「请安装」 | 桌面只留 1 个主操作「使用浏览器钱包登录」 |
+| B3 | 🟠 | 桌面无扫码（TP 扫码被包在仅手机分支） | 扫码移入桌面「其他方式」 |
+| B4 | 🟠 | 手机「打开钱包 App」是死路：无反馈、App 未装无兜底 | 加跳转反馈 + 未安装兜底（提示去下载） |
+| B5 | 🔴 | RainbowKit 整套加载但从未被登录流程调用 | 真正接成「其他方式」扫码兜底 |
+| B6 | 🔴 | 全站无「我的收藏」入口，页面只能手敲 URL | 加 3 处入口（见 §5） |
+| B7 | 🔴 | 钱包下拉只有地址 + 断开 | 下拉加「我的收藏」 |
+| B8 | 🟡 | 收藏 token 过期只弹失败 toast | 401 时自动登出并引导重新登录 |
+| B9 | 🟡 | `isMobileDevice` 把触屏 Mac/iPad 判为手机 | 收紧检测，避免桌面被推进 App 跳转流 |
+| B10 | 🟡 | 收藏页加载失败无重试 | 错误态加重试按钮 |
+| B11 | 🟡 | WalletConnect projectId 默认无效值 | 用 env，缺失时禁用扫码兜底并提示 |
+
+---
+
+## 4. 登录弹窗设计
+
+### 4.1 桌面版
+
+结构（自上而下）：
+1. 标题「连接钱包」
+2. 说明「签名仅用于验证钱包地址，不会发起交易，也不需要 Gas」
+3. **主按钮**「使用浏览器钱包登录」（金色）→ `window.ethereum` 注入流程
+4. 辅助说明「请使用已安装钱包插件的浏览器，例如 MetaMask」
+5. 折叠「其他登录方式」（**默认折叠**），展开后：
+   - TokenPocket 扫码（第一项，中国常用）
+   - MetaMask / imToken 扫码（WalletConnect，附不稳定提示）
+6. 关闭按钮
+7. 错误区（红色）
+
+### 4.2 手机版
+
+结构：
+1. 标题「连接钱包」+ 说明「请在钱包 App 中打开本站并签名登录，无交易、无 Gas」
+2. 若检测到注入钱包：**「使用当前钱包登录」**主按钮
+3. 否则：分组「打开钱包 App」+ 三个按钮（TokenPocket / MetaMask / imToken），带品牌图标
+   - 点按尝试 deep link；未跳转/未安装 → 提示去下载（**不再死路**，修 B4）
+4. 折叠「其他方式（扫码）」默认折叠
+5. 关闭按钮 + 错误区
+
+### 4.3 通用
+- 钱包按钮配品牌彩色图标。
+- 多语言预留文字长度（en/zh-CN/zh-TW/ko/ja/vi/id/ms），按钮不溢出。
+- 弹窗在手机上可滚动、不被遮挡。
+
+---
+
+## 5. 钱包入口与收藏入口
+
+### 5.1 Header 钱包入口
+- 未登录：`Connect Wallet / 连接钱包` 主按钮（桌面右侧 / 手机菜单内）。
+- 已登录：短地址 `0x12…ab34` + 绿点；点击展开下拉。
+
+### 5.2 钱包下拉（已登录，修 B7）
+顺序：完整地址 → **♥ 我的收藏**（新增）→ 断开连接。
+
+### 5.3 「我的收藏」入口策略：**始终显示（方案 B）**
+- 桌面钱包下拉、手机菜单中**始终**显示「我的收藏」入口。
+- 未登录点击 → 落到 `/favorites` 的「连接钱包查看收藏」引导页（现状已有，保留）。
+- 手机菜单导航项中加「♥ 我的收藏」。
+
+### 5.4 收藏按钮触发登录（保留现状逻辑）
+未登录点 ♥ → 打开登录弹窗 → 登录成功后自动补上本次收藏（`pendingAfterLogin` 已实现）。
+
+---
+
+## 6. 收藏按钮（`FavoriteButton`）
+
+四态，一眼可分：
+- 未收藏：空心 ♡，低对比底。
+- 已收藏：实心 ♥，品牌金填充。
+- 加载中：转圈（`LoaderCircle`）。
+- 请求中：禁用 + 降透明。
+
+行为：
+- 点击 `preventDefault + stopPropagation`，不误触进详情（已实现，保留）。
+- 增加点击微动效（`active:scale`）。
+- 乐观更新，失败回滚 + 错误 toast（已实现，保留）。
+
+摆放：推荐卡 / 最新 / 热门 / 内容流 / 收藏页卡片右上角，不挡主内容、不与下载/预览混淆。
+
+---
+
+## 7. 我的收藏页面 `/favorites`
+
+### 7.1 未登录
+图标 + 标题 + 说明 + 「连接钱包」CTA（现状已有，保留视觉打磨）。
+
+### 7.2 已登录
+- **桌面**筛选一行：搜索 + 排序 + 分类 + 搜索按钮（现状保留）。
+- **移动端**：搜索框单独一行；排序/分类收进**「筛选抽屉」**，解决现状 4 控件挤压（新增）。
+- 列表：收藏资源卡（封面/标题/描述/分类/类型/更新时间/收藏数/收藏按钮）。
+- 分页：上一页/下一页 + 页码（现状保留）。
+- 「清除筛选」当存在筛选时显示。
+
+### 7.3 状态
+- **不可用/下架**：黄边 + 「不可用」标 + 不可点进详情 + 保留移除按钮（后端 `availability` 已支持）。
+- **空状态**：区分「还没有收藏」与「筛选无结果」，后者给清除筛选入口。
+- **错误**：加载失败提示 +（新增）**重试按钮**（修 B10）。
+- **加载**：4 张 skeleton，布局不跳。
+
+排序选项：最近收藏 / 最近发布 / 热门（后端 `favorited_at`/`published_at`/`hot` 已支持）。
+
+---
+
+## 8. 多语言
+所有新增/改动文案覆盖 8 语言（en、zh-CN、zh-TW、ko、ja、vi、id、ms），key 写入 `src/locales/*`。移动端按钮预留长文本。
+
+---
+
+## 9. 验收清单
+
+登录：
+- [ ] 桌面弹窗只有 1 个主操作；扫码在折叠区。
+- [ ] 手机可打开 TP/MetaMask/imToken；未安装有兜底。
+- [ ] 登录不再强制切链。
+- [ ] RainbowKit 真正接通（projectId 有效时）；无效时扫码兜底禁用并提示。
+- [ ] 已登录显示短地址，可断开。
+
+收藏：
+- [ ] 钱包下拉、手机菜单均有「我的收藏」入口（始终显示）。
+- [ ] 收藏按钮四态清楚，不与卡片点击冲突。
+- [ ] 未登录点收藏 → 引导登录 → 自动补收藏。
+- [ ] token 过期自动登出并引导重登。
+
+收藏页：
+- [ ] 桌面一行筛选；移动端筛选抽屉。
+- [ ] 不可用/空/错误(含重试)/骨架屏 完整。
+- [ ] Desktop 与 mobile 均验证。
+
+质量门槛（实现后）：`npx tsc --noEmit`、`npm run format:check`、`npm test` 全绿。
+
+---
+
+## 10. 不做（YAGNI）
+- 服务端登出 / token 撤销（保持无状态 JWT）。
+- ENS、链上读取、交易。
+- 收藏分组/文件夹、批量操作（本期不做）。
+- 收藏 `q` 全文索引优化（数据量小，暂不做）。