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`、`