fnvtk/soul-yongping
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
28ad08da841db9feb030d38c1cebca52ed812e4e
soul-yongping/.cursor/skills/next-split/SKILL.md

8.3 KiB
Raw Blame History

name, description
name description
soul-next-split 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