soul-yongping/开发文档/2、架构/拆解计划_管理端抽离与API转Gin.md

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