From 96c8695ff3c5f0151292baf3074afa99a55ea8ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B9=98=E9=A3=8E?= Date: Tue, 24 Feb 2026 12:17:33 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=92=8C=E4=BB=A3=E7=A0=81=E8=A7=84=E8=8C=83=EF=BC=8C?= =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E4=BC=9A=E8=AF=9D=E5=90=AF=E5=8A=A8=E8=87=AA?= =?UTF-8?q?=E6=A3=80=E8=AF=B4=E6=98=8E=EF=BC=8C=E5=BC=BA=E5=8C=96=20GORM?= =?UTF-8?q?=20=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83=EF=BC=8C=E7=A1=AE?= =?UTF-8?q?=E4=BF=9D=E6=95=B0=E6=8D=AE=E4=B8=80=E8=87=B4=E6=80=A7=E5=92=8C?= =?UTF-8?q?=E6=9F=A5=E8=AF=A2=E6=95=88=E7=8E=87=E3=80=82=E5=85=B7=E4=BD=93?= =?UTF-8?q?=E6=94=B9=E5=8A=A8=E5=8C=85=E6=8B=AC=EF=BC=9A=E5=9C=A8=20README?= =?UTF-8?q?.md=20=E4=B8=AD=E6=B7=BB=E5=8A=A0=E4=BC=9A=E8=AF=9D=E5=90=AF?= =?UTF-8?q?=E5=8A=A8=E8=87=AA=E6=A3=80=E5=86=85=E5=AE=B9=EF=BC=9B=E5=9C=A8?= =?UTF-8?q?=20soul-api-coding.mdc=20=E4=B8=AD=E8=A1=A5=E5=85=85=E4=BA=8B?= =?UTF-8?q?=E5=8A=A1=E3=80=81Preload=E3=80=81Pluck=20=E5=92=8C=20Scopes=20?= =?UTF-8?q?=E7=9A=84=E4=BD=BF=E7=94=A8=E8=A6=81=E6=B1=82=EF=BC=9B=E5=9C=A8?= =?UTF-8?q?=20soul-project-boundary.mdc=20=E4=B8=AD=E6=98=8E=E7=A1=AE?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E9=A3=8E=E6=A0=BC=E5=92=8C=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E5=8F=82=E6=95=B0=E7=9A=84=E7=BA=A6=E6=9D=9F=EF=BC=9B=E5=9C=A8?= =?UTF-8?q?=E7=9B=B8=E5=85=B3=20handler=20=E4=B8=AD=E4=BC=98=E5=8C=96?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E5=BA=93=E6=9F=A5=E8=AF=A2=EF=BC=8C=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=20GORM=20=E7=9A=84=E9=93=BE=E5=BC=8F=E8=B0=83?= =?UTF-8?q?=E7=94=A8=E6=9B=BF=E4=BB=A3=E8=A3=B8=20SQL=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/README.md | 10 +- .../SKILL-Next全栈拆解为前后端分离与小程序.md | 14 +- .cursor/skills/SKILL-三端架构与框架分析.md | 208 ++++++++++++++++++ .cursor/skills/SKILL-变更关联检查.md | 6 + 4 files changed, 228 insertions(+), 10 deletions(-) create mode 100644 .cursor/skills/SKILL-三端架构与框架分析.md diff --git a/.cursor/README.md b/.cursor/README.md index 99a340ce..cafeeb3c 100644 --- a/.cursor/README.md +++ b/.cursor/README.md @@ -26,15 +26,17 @@ | 编辑目录 | 主 Skill | 辅助 Skill | |----------|----------|------------| -| miniprogram/ | SKILL-小程序开发.md | SKILL-API开发.md（接口约定）、SKILL-变更关联检查.md（改完过清单） | -| soul-admin/ | SKILL-管理端开发.md | SKILL-API开发.md、SKILL-变更关联检查.md | -| soul-api/ | SKILL-API开发.md | soul-api-coding.mdc（编码细节）、SKILL-变更关联检查.md | +| miniprogram/ | SKILL-小程序开发.md | SKILL-三端架构与框架分析.md（框架/语法）、SKILL-API开发.md、SKILL-变更关联检查.md | +| soul-admin/ | SKILL-管理端开发.md | SKILL-三端架构与框架分析.md、SKILL-API开发.md、SKILL-变更关联检查.md | +| soul-api/ | SKILL-API开发.md | soul-api-coding.mdc、SKILL-三端架构与框架分析.md、SKILL-变更关联检查.md | | next-project/ | SKILL-next-project仅预览.md | api-reliability.mdc（若改 Next API） | -**拆解项目时**：有类似 next-project 的 Next.js 全栈项目需拆为前后端分离 + 小程序时，使用 **SKILL-Next全栈拆解为前后端分离与小程序.md**。 +**拆解项目时**：有类似 next-project 的 Next.js 全栈项目需拆为前后端分离 + 小程序时，使用 **SKILL-Next全栈拆解为前后端分离与小程序.md**；拆解前必读 **SKILL-三端架构与框架分析.md**（小程序/H5/UniApp 语法与框架约束）。 **变更时**：无论改哪端，改完都需过 **soul-change-checklist.mdc**，并参考 **SKILL-变更关联检查.md**。 +**Skills 迭代**：Skills 会随 bug 修复与项目演进持续升级。修 bug 时若发现规则、流程或约定有遗漏或错误，应同步更新对应 Skill，避免同类问题复现。 + --- ## 三、无冲突、无顺序依赖 diff --git a/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md b/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md index 3c0cf71e..44d88e58 100644 --- a/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md +++ b/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md @@ -52,12 +52,14 @@ next-project/ ## 3. 目标架构（前后端分离 + 小程序） -| 原 next-project 部分 | 拆分后 | 技术栈 | -|---------------------|--------|--------| -| **app/api/** 全部逻辑 | **soul-api**（独立后端） | Go + Gin + GORM | -| **app/admin/** 页面 | **soul-admin**（管理端前端） | React + Vite + Tailwind | -| **用户端** | **miniprogram**（微信小程序） | 微信原生 WXML/JS | -| **app/view/**（可选） | 可废弃或改为独立 SPA | 若保留：React/Vue + Vite | +| 原 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` 等 diff --git a/.cursor/skills/SKILL-三端架构与框架分析.md b/.cursor/skills/SKILL-三端架构与框架分析.md new file mode 100644 index 00000000..65294f79 --- /dev/null +++ b/.cursor/skills/SKILL-三端架构与框架分析.md @@ -0,0 +1,208 @@ +# Soul 创业派对 - 三端架构与框架分析 + +本 Skill 分析当前项目（miniprogram、soul-admin、soul-api）的源码框架、类型与拆解约束。**拆解或迁移类似项目时，必须按各端框架选用对应语法**：小程序用小程序语法、H5 用 H5、UniApp 用 UniApp 配套风格。 + +--- + +## 1. 三端总览（忽略 next-project） + +| 端 | 目录 | 框架/类型 | 技术栈 | +|----|------|-----------|--------| +| **小程序** | miniprogram/ | 微信原生小程序 | WXML、WXSS、JS、app.json | +| **管理端** | soul-admin/ | H5（Web SPA） | React + Vite + TypeScript + Tailwind | +| **后端 API** | soul-api/ | Go 服务 | Gin + GORM + MySQL | + +--- + +## 2. 小程序（miniprogram） + +### 2.1 框架类型 + +- **类型**：**微信原生小程序**（非 UniApp、非 Taro、非 mpvue） +- **语法约束**：必须使用微信官方小程序语法，不能混用 Vue/React 写法 + +### 2.2 目录与文件约定 + +``` +miniprogram/ +├── app.js # 入口，globalData、request、login、logout +├── app.json # 页面配置、tabBar、window +├── app.wxss # 全局样式 +├── pages/ # 页面：每页 4 个文件 +│ └── xxx/ +│ ├── xxx.js # 逻辑 +│ ├── xxx.json # 页面配置 +│ ├── xxx.wxml # 模板（类 HTML，非 HTML） +│ └── xxx.wxss # 样式（类 CSS，非 CSS） +├── components/ # 自定义组件（.js/.json/.wxml/.wxss） +├── custom-tab-bar/ # 自定义 tabBar +└── utils/ # 工具（scene.js、payment.js、util.js） +``` + +### 2.3 语法要点（拆解时不可混用） + +| 场景 | 正确（微信原生） | 错误（勿用） | +|------|------------------|--------------| +| 模板 | ``, ``, `wx:if`, `wx:for` | `
`, `v-if`, `*ngIf` | +| 样式 | `.wxss`，`rpx` 单位 | `px` 为主、Vue scoped | +| 数据绑定 | `{{data}}`，`data-*` | `v-model`、`@click` | +| 事件 | `bindtap`, `catchtap` | `@click`、`(click)` | +| 请求 | `wx.request` 或 `getApp().request()` | `axios`、`fetch`（需封装） | +| 存储 | `wx.getStorageSync` / `wx.setStorageSync` | `localStorage` | +| 路由 | `wx.navigateTo`, `wx.switchTab` | `router.push` | + +### 2.4 API 调用约定 + +- **baseUrl**：`app.js` 的 `globalData.baseUrl`（如 `https://soulapi.quwanzhi.com`） +- **路径**：统一 `/api/miniprogram/*`，与 soul-api 的 miniprogram 组一致 +- **请求**：`getApp().request(url, { method, data, silent })` +- **鉴权**：`Authorization: Bearer `，token 存 `wx.getStorageSync('token')` + +### 2.5 若改为 UniApp/Taro + +- **UniApp**：需用 `.vue`、`uni.xxx` API、条件编译 `#ifdef MP-WEIXIN` +- **Taro**：需用 React/JSX、`Taro.xxx` API +- **拆解时**：先确认目标框架，再按该框架的语法迁移，**不可在原微信原生项目中混入 Vue/React 组件** + +--- + +## 3. 管理端（soul-admin） + +### 3.1 框架类型 + +- **类型**：**H5 Web SPA**（React 单页应用，运行于浏览器） +- **语法约束**：React + JSX + TypeScript，非 Vue、非 Angular + +### 3.2 目录与文件约定 + +``` +soul-admin/ +├── src/ +│ ├── main.tsx # 入口 +│ ├── App.tsx +│ ├── api/ +│ │ ├── client.ts # 统一 request/get/post/put/del +│ │ └── auth.ts # admin_token 存取 +│ ├── layouts/ +│ │ └── AdminLayout.tsx +│ ├── pages/ # 页面组件 +│ │ ├── login/ +│ │ ├── dashboard/ +│ │ ├── chapters/ +│ │ └── ... +│ ├── components/ +│ │ ├── ui/ # 基础 UI（button、input、dialog 等） +│ │ └── modules/ # 业务模块 +│ └── lib/ +│ └── utils.ts +├── vite.config.ts +├── tailwind.config.* +└── package.json +``` + +### 3.3 技术栈与语法 + +| 层级 | 技术 | 说明 | +|------|------|------| +| 框架 | React 18 | 函数组件 + Hooks | +| 构建 | Vite 6 | 开发/打包 | +| 语言 | TypeScript | 类型约束 | +| 样式 | Tailwind CSS 4 | 原子类 | +| UI 组件 | Radix UI | 无障碍、可定制 | +| 状态 | Zustand | 轻量状态管理 | +| 路由 | react-router-dom 6 | 前端路由 | + +### 3.4 API 调用约定 + +- **baseUrl**：`VITE_API_BASE_URL` 或默认 `https://soulapi.quwanzhi.com` +- **路径**：`/api/admin/*`、`/api/db/*`、`/api/orders` 等（与 soul-api 管理端路由一致） +- **封装**：`get/post/put/del` 来自 `@/api/client` +- **鉴权**：`Authorization: Bearer `，token 存 `localStorage` + +### 3.5 若改为 Vue/其他 + +- **Vue 3**：需用 `.vue`、`