# 拆解计划：管理端抽离 + API 转 Gin（API 路径不变、无缝切换） ## 目标与原则 - **管理端**：从当前 Next 单体中抽离为独立前端项目（SPA），所有请求使用**可配置 baseUrl**，**API 路径与现网完全一致**（如 `/api/orders`、`/api/admin/withdrawals`），便于先对接到现有 Next，后续一键切到 Gin。 - **小程序**：不改动；仅在未来切换后端时修改 `baseUrl` 指向 Gin。 - **后端**：先仍由当前 Next 提供 API；第二阶段用 **Gin** 重写全部接口，**路径、方法、请求/响应体与现有 Next API 保持一致**，实现无缝切换。 --- ## 阶段一：管理端抽离（独立前端） ### 1.1 产出物 - 新仓库或新目录：**soul-admin**（独立 SPA） - 技术栈：React 18 + TypeScript + Vite 5 + React Router 6 + Tailwind CSS 4 + Radix UI（与现有一致）+ Zustand + 统一 API 封装（baseUrl 来自 env） ### 1.2 API 基地址规范（必须 100% 遵守） - 环境变量：`VITE_API_BASE_URL`（如开发 `http://localhost:3006`，生产 `https://soul.quwanzhi.com`）。 - 所有请求统一为：`${VITE_API_BASE_URL}${path}`，其中 **path 与现网完全一致**，例如： - `/api/admin`（GET 鉴权 / POST 登录） - `/api/admin/logout`（POST） - `/api/orders`（GET） - `/api/db/users`（GET/POST/DELETE） - `/api/admin/withdrawals`（GET/POST） - 等等（见下方完整清单）。 - 禁止在管理端项目内写死域名或写死 `/api/...` 相对路径（相对路径仅在请求封装内与 baseUrl 拼接）。 ### 1.3 管理端页面与 API 对照表（迁移时逐项核对） | 管理端页面 | 使用的 API（路径保持不变） | |------------|----------------------------| | 登录 `/admin/login` | POST `/api/admin`（登录）、GET `/api/admin`（鉴权） | | 布局/侧栏 | GET `/api/admin`（鉴权）、POST `/api/admin/logout`（退出） | | 数据概览 `/admin` | GET `/api/db/users`、GET `/api/orders` | | 订单管理 `/admin/orders` | GET `/api/orders`、GET `/api/db/users` | | 用户管理 `/admin/users` | GET `/api/db/users`、DELETE `/api/db/users?id=xxx`、POST `/api/db/users`、GET `/api/db/users/referrals?userId=xxx` | | 交易中心 `/admin/distribution` | GET `/api/admin/distribution/overview`、GET `/api/db/users`、GET `/api/orders`、GET `/api/db/distribution`、GET `/api/admin/withdrawals`、POST `/api/admin/withdrawals`（审核/打款） | | 提现管理 `/admin/withdrawals` | GET `/api/admin/withdrawals?status=xxx`、POST `/api/admin/withdrawals`（审核/打款） | | 内容管理 `/admin/content` | GET `/api/db/book?action=read&id=xxx`、POST `/api/db/book`、POST `/api/upload`、GET `/api/search?q=xxx`、GET `/api/db/book?action=export`、POST `/api/db/init` | | 章节管理 `/admin/chapters` | GET `/api/admin/chapters`、POST `/api/admin/chapters`、PUT `/api/admin/chapters`、DELETE `/api/admin/chapters` | | 推广设置 `/admin/referral-settings` | GET `/api/db/config?key=referral_config`、POST `/api/db/config` | | 系统设置 `/admin/settings` | GET `/api/db/config`、POST `/api/db/settings`、POST `/api/db/config`（多次）、GET `/api/db/config`（验证） | | 站点/支付/二维码 `/admin/site`、`/admin/payment`、`/admin/qrcodes` | 依赖 `useStore().fetchSettings()` → GET `/api/config`；若另有保存逻辑需按实际请求补全 | | 找伙伴配置 `/admin/match` | GET `/api/db/config?key=match_config`、POST `/api/db/config` | 说明：`/api/db/settings` 在当前 Next 中未见对应 route，若 Next 未实现则 Gin 阶段需实现该路径并与管理端约定请求/响应体。 ### 1.4 迁移清单（执行顺序）— Phase 1 已完成 **已完成**：独立项目 `soul-admin/` 已创建，所有请求通过 `src/api/client.ts` 使用 `VITE_API_BASE_URL` + 与现网一致的 path，API 路径未做任何改动。 1. 创建 soul-admin 项目（Vite + React + TS + Tailwind + React Router）。 2. 配置 `VITE_API_BASE_URL`，实现统一请求封装（如 `src/api/client.ts`），所有 `fetch` 使用 `baseUrl + path`，path 与上表一致。 3. 迁移 `app/admin/layout.tsx` → 管理端布局与侧栏；鉴权请求 GET `/api/admin`、POST `/api/admin/logout` 走封装。 4. 迁移 `app/admin/login/page.tsx` → 登录页，POST `/api/admin` 走封装。 5. 按上表逐页迁移：`page.tsx`、`loading.tsx`（可改为本地 loading 状态），替换 `fetch('/api/...')` 为封装后的请求（路径不变）。 6. 迁移管理端用到的 `components/ui/*` 及 `components/admin/*`（若有）；迁移 `lib/store.ts` 中管理端会用到的部分，且其中 `fetch` 改为使用 baseUrl 封装。 7. 移除对 `next/link`、`next/navigation` 的依赖，改用 React Router 的 `Link`、`useNavigate`、`useLocation`；路由表与现有 `/admin/*` 一一对应。 8. 验收：独立启动管理端，`VITE_API_BASE_URL=http://localhost:3006`，登录、各页数据加载、提现/订单等操作均正常，且浏览器网络请求 path 与现网一致。 --- ## 阶段二：API 转 Gin（路径不变、无缝切换） ### 2.1 产出物 - 新仓库或新目录：**soul-server**（Gin 项目，Go 1.25.7）。 - 所有对外 HTTP 路径与 Next 时期**完全一致**，请求方法、Query、Body、响应 JSON 结构与现有接口保持一致（以便管理端与小程序的 baseUrl 仅改域名/端口即可）。 ### 2.2 完整 API 路径清单（73 个 Route → 路径规范） 以下为当前 `app/api` 下 route 与路径的对应关系，Gin 需逐条实现，路径不可改。 | 序号 | 路径 | 方法 | 说明 | |------|------|------|------| | 1 | /api/admin | GET, POST | 鉴权 / 登录 | | 2 | /api/admin/logout | POST | 退出 | | 3 | /api/admin/chapters | GET, POST, PUT, DELETE | 后台章节 | | 4 | /api/admin/content | (见 content) | 后台内容 | | 5 | /api/admin/distribution/overview | GET | 分销概览 | | 6 | /api/admin/payment | (依实现) | 后台支付配置 | | 7 | /api/admin/referral | (依实现) | 后台推荐 | | 8 | /api/admin/withdrawals | GET, POST | 提现列表与审核 | | 9 | /api/auth/login | POST | C 端登录 | | 10 | /api/auth/reset-password | POST | 重置密码 | | 11 | /api/book/all-chapters | GET | 全部章节 | | 12 | /api/book/chapter/:id | GET | 单章 | | 13 | /api/book/chapters | GET, POST, PUT, DELETE | 章节 CRUD | | 14 | /api/book/hot | GET | 热门 | | 15 | /api/book/latest-chapters | GET | 最新章节 | | 16 | /api/book/stats | GET | 统计 | | 17 | /api/book/search | GET | 搜索 | | 18 | /api/book/sync | POST | 同步 | | 19 | /api/config | GET | 前端配置 | | 20 | /api/content | GET | 内容 | | 21 | /api/ckb/join | POST | CKB 加入 | | 22 | /api/ckb/match | POST | CKB 匹配 | | 23 | /api/ckb/sync | POST | CKB 同步 | | 24 | /api/cron/sync-orders | GET/POST | 定时同步订单 | | 25 | /api/cron/unbind-expired | GET/POST | 定时解绑 | | 26 | /api/db/book | GET, POST | 书/内容 | | 27 | /api/db/chapters | GET | 章节 | | 28 | /api/db/config | GET, POST | 系统配置 | | 29 | /api/db/distribution | GET | 分销数据 | | 30 | /api/db/init | POST | 初始化 | | 31 | /api/db/migrate | POST | 迁移 | | 32 | /api/db/users | GET, POST, DELETE | 用户 | | 33 | /api/db/users/referrals | GET | 用户推荐列表 | | 34 | /api/distribution | GET | 分销 | | 35 | /api/distribution/auto-withdraw-config | GET, POST | 自动提现配置 | | 36 | /api/distribution/messages | GET, POST | 消息 | | 37 | /api/documentation/generate | POST | 文档生成 | | 38 | /api/match/config | GET, POST | 找伙伴配置 | | 39 | /api/match/users | GET | 匹配用户 | | 40 | /api/menu | GET | 菜单 | | 41 | /api/miniprogram/login | POST | 小程序登录 | | 42 | /api/miniprogram/pay | POST | 小程序支付 | | 43 | /api/miniprogram/pay/notify | POST | 支付回调 | | 44 | /api/miniprogram/phone | POST | 手机号 | | 45 | /api/miniprogram/qrcode | GET | 二维码 | | 46 | /api/orders | GET | 订单列表 | | 47 | /api/payment/alipay/notify | POST | 支付宝回调 | | 48 | /api/payment/callback | GET/POST | 支付回调 | | 49 | /api/payment/create-order | POST | 创建订单 | | 50 | /api/payment/methods | GET | 支付方式 | | 51 | /api/payment/query | GET | 查询订单 | | 52 | /api/payment/status/:orderSn | GET | 订单状态 | | 53 | /api/payment/verify | POST | 核销 | | 54 | /api/payment/wechat/notify | POST | 微信支付回调 | | 55 | /api/payment/wechat/transfer/notify | POST | 微信转账回调 | | 56 | /api/referral/bind | POST | 绑定推荐码 | | 57 | /api/referral/data | GET | 分销数据 | | 58 | /api/referral/visit | POST | 推荐访问 | | 59 | /api/search | GET | 搜索 | | 60 | /api/sync | POST | 同步 | | 61 | /api/upload | POST | 上传 | | 62 | /api/user/addresses | GET, POST | 地址列表与新增 | | 63 | /api/user/addresses/:id | GET, PUT, DELETE | 地址单条 | | 64 | /api/user/check-purchased | GET | 是否已购 | | 65 | /api/user/profile | GET, POST | 用户资料 | | 66 | /api/user/purchase-status | GET | 购买状态 | | 67 | /api/user/reading-progress | GET, POST | 阅读进度 | | 68 | /api/user/track | GET | 行为轨迹 | | 69 | /api/user/update | POST | 更新用户 | | 70 | /api/wechat/login | POST | 微信登录 | | 71 | /api/withdraw | POST | 申请提现 | | 72 | /api/withdraw/records | GET | 提现记录 | | 73 | /api/withdraw/pending-confirm | GET | 待确认提现 | 说明：部分路径在 Next 中为同一 route 多方法（如 GET/POST），Gin 需按现有行为实现；带 `:id`、`:orderSn` 为路径参数，与 Next 动态段一致。 ### 2.3 Gin 实现顺序建议 1. 基础设施：Go 1.25.7、Gin、GORM、MySQL、env 配置、CORS、日志。 2. 鉴权：复刻现有 Cookie 或改为 JWT（若改 JWT，管理端需同步改为带 Authorization 头）；小程序 openid/session 逻辑与现网一致。 3. 按「管理端必需」优先：`/api/admin`、`/api/admin/logout`、`/api/db/*`、`/api/orders`、`/api/admin/withdrawals`、`/api/admin/distribution/overview`、`/api/admin/chapters`、`/api/config`、`/api/db/config`、`/api/db/settings`（若现网无则按管理端调用约定实现）。 4. 再实现小程序与 C 端所需：`/api/miniprogram/*`、`/api/wechat/*`、`/api/user/*`、`/api/book/*`、`/api/referral/*`、`/api/payment/*`、`/api/withdraw/*` 等。 5. 最后：定时任务对应接口、文档生成等。 ### 2.4 无缝切换检查清单 - [ ] 管理端 `VITE_API_BASE_URL` 改为 Gin 地址后，登录、各页请求均 200，数据与 Next 时期一致。 - [ ] 小程序 `baseUrl` 改为 Gin 地址后，登录、支付、提现、推荐等流程正常。 - [ ] 所有 73 个路径在 Gin 中均有实现，且请求/响应与现网兼容（可做契约测试或对比脚本）。 --- ## 附录：当前 Next 中 route 文件与路径映射（供 Gin 对照） ``` app/api/admin/route.ts → /api/admin app/api/admin/logout/route.ts → /api/admin/logout app/api/admin/chapters/route.ts → /api/admin/chapters app/api/admin/content/route.ts → /api/admin/content app/api/admin/distribution/overview/route.ts → /api/admin/distribution/overview app/api/admin/payment/route.ts → /api/admin/payment app/api/admin/referral/route.ts → /api/admin/referral app/api/admin/withdrawals/route.ts → /api/admin/withdrawals app/api/auth/login/route.ts → /api/auth/login app/api/auth/reset-password/route.ts → /api/auth/reset-password app/api/book/all-chapters/route.ts → /api/book/all-chapters app/api/book/chapter/[id]/route.ts → /api/book/chapter/:id app/api/book/chapters/route.ts → /api/book/chapters app/api/book/hot/route.ts → /api/book/hot app/api/book/latest-chapters/route.ts → /api/book/latest-chapters app/api/book/stats/route.ts → /api/book/stats app/api/book/search/route.ts → /api/book/search app/api/book/sync/route.ts → /api/book/sync app/api/config/route.ts → /api/config app/api/content/route.ts → /api/content app/api/ckb/join/route.ts → /api/ckb/join app/api/ckb/match/route.ts → /api/ckb/match app/api/ckb/sync/route.ts → /api/ckb/sync app/api/cron/sync-orders/route.ts → /api/cron/sync-orders app/api/cron/unbind-expired/route.ts → /api/cron/unbind-expired app/api/db/book/route.ts → /api/db/book app/api/db/chapters/route.ts → /api/db/chapters app/api/db/config/route.ts → /api/db/config app/api/db/distribution/route.ts → /api/db/distribution app/api/db/init/route.ts → /api/db/init app/api/db/migrate/route.ts → /api/db/migrate app/api/db/users/route.ts → /api/db/users app/api/db/users/referrals/route.ts → /api/db/users/referrals app/api/distribution/route.ts → /api/distribution app/api/distribution/auto-withdraw-config/route.ts → /api/distribution/auto-withdraw-config app/api/distribution/messages/route.ts → /api/distribution/messages app/api/documentation/generate/route.ts → /api/documentation/generate app/api/match/config/route.ts → /api/match/config app/api/match/users/route.ts → /api/match/users app/api/menu/route.ts → /api/menu app/api/miniprogram/login/route.ts → /api/miniprogram/login app/api/miniprogram/pay/route.ts → /api/miniprogram/pay app/api/miniprogram/pay/notify/route.ts → /api/miniprogram/pay/notify app/api/miniprogram/phone/route.ts → /api/miniprogram/phone app/api/miniprogram/qrcode/route.ts → /api/miniprogram/qrcode app/api/orders/route.ts → /api/orders app/api/payment/alipay/notify/route.ts → /api/payment/alipay/notify app/api/payment/callback/route.ts → /api/payment/callback app/api/payment/create-order/route.ts → /api/payment/create-order app/api/payment/methods/route.ts → /api/payment/methods app/api/payment/query/route.ts → /api/payment/query app/api/payment/status/[orderSn]/route.ts → /api/payment/status/:orderSn app/api/payment/verify/route.ts → /api/payment/verify app/api/payment/wechat/notify/route.ts → /api/payment/wechat/notify app/api/payment/wechat/transfer/notify/route.ts → /api/payment/wechat/transfer/notify app/api/referral/bind/route.ts → /api/referral/bind app/api/referral/data/route.ts → /api/referral/data app/api/referral/visit/route.ts → /api/referral/visit app/api/search/route.ts → /api/search app/api/sync/route.ts → /api/sync app/api/upload/route.ts → /api/upload app/api/user/addresses/route.ts → /api/user/addresses app/api/user/addresses/[id]/route.ts → /api/user/addresses/:id app/api/user/check-purchased/route.ts → /api/user/check-purchased app/api/user/profile/route.ts → /api/user/profile app/api/user/purchase-status/route.ts → /api/user/purchase-status app/api/user/reading-progress/route.ts → /api/user/reading-progress app/api/user/track/route.ts → /api/user/track app/api/user/update/route.ts → /api/user/update app/api/wechat/login/route.ts → /api/wechat/login app/api/withdraw/route.ts → /api/withdraw app/api/withdraw/records/route.ts → /api/withdraw/records app/api/withdraw/pending-confirm/route.ts → /api/withdraw/pending-confirm ``` 注意：当前项目中没有 `app/api/db/settings/route.ts`，管理端系统设置页调用了 POST `/api/db/settings`。若 Next 未实现，Gin 需新增该路径并约定 body/response 与前端一致。