fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7b2123dfe5343eb68dfd8431f56dab2b3518e492
soul-yongping/开发文档/2、架构/拆解计划_管理端抽离与API转Gin.md
乘风 7b2123dfe5 打好基版
2026-02-09 15:09:29 +08:00

16 KiB
Raw Blame History

拆解计划：管理端抽离 + 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 与前端一致。