194 lines
8.3 KiB
Markdown
194 lines
8.3 KiB
Markdown
---
|
||
name: soul-next-split
|
||
description: Next.js 全栈拆解为前后端分离+小程序。soul-api、soul-admin、miniprogram 目标架构。Use when 拆解项目, 前后端分离, Next 全栈.
|
||
---
|
||
# Next.js 全栈项目拆解为前后端分离 + 小程序
|
||
|
||
当你有类似 **next-project** 的 Next.js 全栈项目（app/api + app/view + app/admin），需要拆解为**前后端分离 + 小程序**架构时，使用本 Skill。本 Skill 基于 next-project 实际代码结构归纳，目标架构参考本仓库的 soul-api、soul-admin、miniprogram。
|
||
|
||
---
|
||
|
||
## 1. 何时使用本 Skill
|
||
|
||
- 有 Next.js 全栈项目（API 路由 + 用户端页面 + 管理端页面）
|
||
- 需要拆分为：**独立后端 API** + **管理端前端** + **微信小程序**（可选保留 Web 用户端）
|
||
- 后续会有类似项目需要按同一模式拆解
|
||
|
||
---
|
||
|
||
## 2. 原项目结构识别（以 next-project 为例）
|
||
|
||
```
|
||
next-project/
|
||
├── app/
|
||
│ ├── api/ # API 路由（后端逻辑）
|
||
│ │ ├── admin/ # 管理端接口
|
||
│ │ ├── miniprogram/ # 小程序专属接口（登录、支付、二维码等）
|
||
│ │ ├── user/ # 用户相关（profile、addresses、purchase-status）
|
||
│ │ ├── payment/ # 支付、回调
|
||
│ │ ├── referral/ # 推荐、绑定
|
||
│ │ ├── db/ # 数据/配置（管理端）
|
||
│ │ ├── book/ # 书籍、章节
|
||
│ │ ├── ckb/ # 找伙伴等业务
|
||
│ │ └── ...
|
||
│ ├── view/ # 用户端 Web 页面（C 端）
|
||
│ │ ├── my/ # 个人中心、推荐、地址、购买记录
|
||
│ │ ├── match/ # 找伙伴
|
||
│ │ ├── login/
|
||
│ │ └── ...
|
||
│ └── admin/ # 管理端页面
|
||
│ ├── layout.tsx
|
||
│ ├── users/
|
||
│ ├── withdrawals/
|
||
│ └── ...
|
||
├── lib/
|
||
│ ├── db.ts # 数据库（mysql2）
|
||
│ ├── payment/ # 支付逻辑
|
||
│ ├── wechat-transfer.ts # 微信转账
|
||
│ ├── store.ts # Zustand 状态
|
||
│ └── ...
|
||
└── components/
|
||
```
|
||
|
||
**关键点**：API 与页面同域，view/admin 通过 `fetch('/api/...')` 调用；小程序需单独对接，路径需与小程序约定一致。
|
||
|
||
---
|
||
|
||
## 3. 目标架构（前后端分离 + 小程序）
|
||
|
||
| 原 next-project 部分 | 拆分后 | 技术栈 | 框架类型 |
|
||
|---------------------|--------|--------|----------|
|
||
| **app/api/** 全部逻辑 | **soul-api**（独立后端） | Go + Gin + GORM | Go HTTP 服务 |
|
||
| **app/admin/** 页面 | **soul-admin**（管理端前端） | React + Vite + Tailwind | H5 Web SPA |
|
||
| **用户端** | **miniprogram**（微信小程序） | 微信原生 WXML/WXSS/JS | 微信原生小程序 |
|
||
| **app/view/**（可选） | 可废弃或改为独立 SPA | 若保留：React/Vue + Vite | H5 Web SPA |
|
||
|
||
**框架与语法约束**：拆解时必须按各端框架选用对应语法——小程序用小程序语法（WXML/WXSS、wx.*）、H5 用 H5（React/Vue）、UniApp 用 UniApp 配套风格。详见 **SKILL-三端架构与框架分析.md**。
|
||
|
||
**接口约定**：
|
||
- 管理端：`/api/admin/*`、`/api/db/*`、`/api/orders` 等
|
||
- 小程序：`/api/miniprogram/*`（登录、支付、书籍、用户、提现等）
|
||
- 路径与 next-project 的 `app/api` 对应，仅 baseUrl 改为 soul-api 地址
|
||
|
||
---
|
||
|
||
## 4. 拆解流程 Checklist
|
||
|
||
```
|
||
阶段1: 分析
|
||
- [ ] 列出 app/api 下所有 route.ts，按使用方分类（admin / miniprogram / 共用）
|
||
- [ ] 识别 lib/ 中数据库、支付、微信等依赖
|
||
- [ ] 记录 API 路径与请求/响应格式（便于迁移时保持一致）
|
||
|
||
阶段2: 创建后端（soul-api）
|
||
- [ ] 初始化 Go 项目，GORM + Gin
|
||
- [ ] 按模块迁移 handler（auth、user、payment、referral、admin、miniprogram）
|
||
- [ ] 路由按使用方挂到 admin / db / miniprogram 组
|
||
- [ ] 数据库用 GORM model，JSON 用 camelCase
|
||
|
||
阶段3: 创建管理端（soul-admin）
|
||
- [ ] React + Vite，API 客户端封装（get/post/put/del）
|
||
- [ ] 迁移 app/admin 页面，fetch 改为调用 soul-api
|
||
- [ ] 鉴权用 JWT（Authorization: Bearer）
|
||
|
||
阶段4: 小程序对接
|
||
- [ ] 小程序 baseUrl 指向 soul-api
|
||
- [ ] 所有请求走 /api/miniprogram/*（与 soul-api 的 miniprogram 组一致）
|
||
- [ ] 登录、支付、书籍、用户、提现等接口路径与 next-project 的 app/api/miniprogram 对应
|
||
|
||
阶段5: 验证与收尾
|
||
- [ ] 管理端、小程序分别联调 soul-api
|
||
- [ ] 废弃或保留 app/view（若保留需改为调用 soul-api）
|
||
- [ ] 更新文档与 Rules/Skills
|
||
```
|
||
|
||
---
|
||
|
||
## 5. API 迁移对照（next-project → soul-api）
|
||
|
||
| next-project 路径 | soul-api 路径 | 使用方 |
|
||
|------------------|---------------|--------|
|
||
| /api/admin, /api/admin/logout | /api/admin, /api/admin/logout | 管理端 |
|
||
| /api/admin/withdrawals, users, ... | /api/admin/* | 管理端 |
|
||
| /api/db/users, config, chapters | /api/db/* | 管理端 |
|
||
| /api/miniprogram/login | /api/miniprogram/login | 小程序 |
|
||
| /api/miniprogram/pay, pay/notify | /api/miniprogram/pay, pay/notify | 小程序 |
|
||
| /api/miniprogram/phone, qrcode | /api/miniprogram/phone, qrcode | 小程序 |
|
||
| /api/user/profile, addresses | /api/miniprogram/user/* | 小程序 |
|
||
| /api/book/all-chapters, chapter/[id] | /api/miniprogram/book/* | 小程序 |
|
||
| /api/referral/bind, visit, data | /api/miniprogram/referral/* | 小程序 |
|
||
| /api/ckb/join, match | /api/miniprogram/ckb/* | 小程序 |
|
||
| /api/payment/* (回调) | /api/payment/* 或 /api/miniprogram/pay/notify | 后端回调 |
|
||
|
||
**原则**：小程序统一走 `/api/miniprogram/*`，管理端走 `/api/admin/*`、`/api/db/*`，避免混用。
|
||
|
||
---
|
||
|
||
## 6. 数据与依赖迁移要点
|
||
|
||
### 6.1 数据库
|
||
|
||
- **next-project**：`lib/db.ts` + mysql2，`query(sql, params)` 裸 SQL
|
||
- **soul-api**：GORM，`database.DB()`，model 在 `internal/model`
|
||
- **迁移**：将 `query` 调用改为 GORM 链式 API；复杂统计可保留 `db.Raw().Scan()`
|
||
|
||
### 6.2 支付与微信
|
||
|
||
- **next-project**：`lib/payment/`、`lib/wechat-transfer.ts`
|
||
- **soul-api**：`internal/wechat/` 封装，handler 只做参数转换
|
||
- **迁移**：微信登录、支付、转账逻辑迁入 `internal/wechat`，PowerWeChat 或官方 API
|
||
|
||
### 6.3 配置
|
||
|
||
- **next-project**：`process.env.*`、`lib/db` 内配置
|
||
- **soul-api**：`internal/config` 的 `Load()`，`.env` 读取
|
||
|
||
---
|
||
|
||
## 7. 前端迁移要点
|
||
|
||
### 7.1 管理端（app/admin → soul-admin）
|
||
|
||
- **原**：`fetch('/api/admin', { credentials: 'include' })`，同域
|
||
- **现**：`get('/api/admin')`，baseUrl 指向 soul-api，header 带 `Authorization: Bearer <token>`
|
||
- **鉴权**：登录后存 token，401 跳转登录页
|
||
|
||
### 7.2 小程序（新建或已有 miniprogram）
|
||
|
||
- **原**：若 next-project 曾作小程序后端，则小程序调 next-project 的 `/api/miniprogram/*`
|
||
- **现**：baseUrl 改为 soul-api，路径保持 `/api/miniprogram/*`
|
||
- **请求**：统一 `getApp().request(url, options)`，自动带 token
|
||
|
||
### 7.3 用户端 Web（app/view，可选）
|
||
|
||
- 若**废弃**：用户仅通过小程序使用
|
||
- 若**保留**：改为独立 SPA，fetch 指向 soul-api，路径需与 soul-api 提供的接口一致（可能需在 soul-api 增加非 miniprogram 的公开接口）
|
||
|
||
---
|
||
|
||
## 8. 与现有项目 Rules/Skills 的配合
|
||
|
||
拆解完成后，开发约束以本仓库为准：
|
||
|
||
- **soul-api**：遵守 soul-api.mdc、SKILL-API开发.md
|
||
- **soul-admin**：遵守 soul-admin-boundary、SKILL-管理端开发.md
|
||
- **miniprogram**：遵守 soul-miniprogram-boundary、SKILL-小程序开发.md
|
||
- **next-project**：仅作参考，见 SKILL-next-project仅预览.md
|
||
|
||
---
|
||
|
||
## 9. 后续类似项目
|
||
|
||
遇到新的 Next.js 全栈项目需拆解时：
|
||
|
||
1. **先分析**：按「2. 原项目结构识别」梳理 api、view、admin、lib
|
||
2. **再规划**：按「3. 目标架构」确定后端、管理端、小程序、用户端 Web 的归属
|
||
3. **按 Checklist**：执行「4. 拆解流程」
|
||
4. **按对照表**：迁移 API 时参考「5. API 迁移对照」
|
||
5. **按要点**：数据、支付、前端迁移参考「6」「7」
|
||
|
||
---
|
||
|
||
**创建时间**：2026-02
|
||
**参考项目**：next-project、soul-api、soul-admin、miniprogram
|