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

249 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 拆解计划：管理端抽离 + 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 与前端一致。
Reference in New Issue View Git Blame Copy Permalink