更新项目文档和代码规范，增加会话启动自检说明，强化 GORM 使用规范，确保数据一致性和查询效率。具体改动包括：在 README.md 中添加会话启动自检内容；在 soul-api-coding.mdc 中补充事务、Preload、Pluck 和 Scopes 的使用要求；在 soul-project-boundary.mdc 中明确开发风格和配置参数的约束；在相关 handler 中优化数据库查询，使用 GORM 的链式调用替代裸 SQL。

2026-02-24 12:17:33 +08:00
parent 5f09416377
commit 96c8695ff3
4 changed files with 228 additions and 10 deletions
--- 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，避免同类问题复现。
+
 ---

 ## 三、无冲突、无顺序依赖
--- 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` 等
--- a/.cursor/skills/SKILL-三端架构与框架分析.md
+++ 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 语法要点（拆解时不可混用）
+
+| 场景 | 正确（微信原生） | 错误（勿用） |
+|------|------------------|--------------|
+| 模板 | `<view>`, `<text>`, `wx:if`, `wx:for` | `<div>`, `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>`，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 <admin_token>`，token 存 `localStorage`
+
+### 3.5 若改为 Vue/其他
+
+- **Vue 3**：需用 `.vue`、`<script setup>`、`ref`/`reactive`、Vue Router
+- **拆解时**：管理端为 H5，必须用 Web 技术栈（React/Vue/Angular 等），**不可用小程序 WXML/WXSS**
+
+---
+
+## 4. 后端 API（soul-api）
+
+### 4.1 框架类型
+
+- **类型**：**Go HTTP 服务**
+- **语法约束**：Go 1.x、Gin、GORM
+
+### 4.2 目录与文件约定
+
+```
+soul-api/
+├── cmd/server/main.go
+├── internal/
+│   ├── config/         # 配置加载
+│   ├── database/       # GORM 连接
+│   ├── model/          # 数据模型
+│   ├── handler/        # 业务处理
+│   ├── router/         # 路由注册
+│   ├── middleware/     # 中间件
+│   ├── auth/           # 鉴权（JWT、Session）
+│   └── wechat/         # 微信登录、支付、转账
+└── go.mod
+```
+
+### 4.3 路由分组（按使用方）
+
+| 分组 | 路径前缀 | 使用方 | 鉴权 |
+|------|----------|--------|------|
+| 管理端 | `/api/admin` | soul-admin | AdminAuth JWT |
+| 数据库/配置 | `/api/db` | soul-admin | AdminAuth |
+| 小程序 | `/api/miniprogram` | miniprogram | 部分需 token |
+| 公开 | `/api/config`、`/api/db/config` | 小程序/管理端 | 无 |
+
+### 4.4 响应格式
+
+- 统一：`{ "success": true, "data": {...} }` 或 `{ "success": false, "message": "..." }`
+- JSON 字段：camelCase
+
+---
+
+## 5. 拆解时的框架与类型选择
+
+### 5.1 决策表
+
+| 目标端 | 框架类型 | 语法/风格 | 示例 |
+|--------|----------|-----------|------|
+| 微信小程序 | 微信原生 | WXML、WXSS、wx.* | 当前 miniprogram |
+| 微信小程序 | UniApp | .vue、uni.*、条件编译 | 多端统一时 |
+| 微信小程序 | Taro | React/JSX、Taro.* | React 技术栈时 |
+| H5 管理端 | React + Vite | TSX、Tailwind、Radix | 当前 soul-admin |
+| H5 管理端 | Vue 3 + Vite | .vue、Composition API | Vue 技术栈时 |
+| H5 用户端 | 同上 | 同 H5 管理端 | 若保留 Web 用户端 |
+| 后端 | Go + Gin | handler、model、router | 当前 soul-api |
+| 后端 | Node + Express | route、controller | 若沿用 Node |
+
+### 5.2 拆解 Checklist（按框架）
+
+```
+□ 确定各端框架类型（小程序原生/UniApp/Taro、H5 React/Vue、后端 Go/Node）
+□ 小程序：使用对应框架语法（原生→wxml/wxss，UniApp→.vue，Taro→JSX）
+□ 管理端：使用 H5 技术栈（React/Vue），不可用小程序语法
+□ API：路径与鉴权方式与各端 client 约定一致
+□ 字段变更：同步考虑 model、handler、前端类型定义
+```
+
+---
+
+## 6. 与现有 Rules/Skills 的配合
+
+- **soul-miniprogram-boundary**：miniprogram 只调 `/api/miniprogram/*`
+- **soul-admin-boundary**：soul-admin 只调 `/api/admin/*`、`/api/db/*`
+- **soul-api-boundary**：路由按使用方分组
+- **SKILL-小程序开发**：小程序请求、scene、支付等约定
+- **SKILL-管理端开发**：管理端 client、auth 约定
+- **SKILL-API开发**：soul-api 编码规范
+
+---
+
+**创建时间**：2026-02  
+**适用**：拆解、迁移、新增端时，按框架类型选用正确语法
--- a/.cursor/skills/SKILL-变更关联检查.md
+++ b/.cursor/skills/SKILL-变更关联检查.md
@@ -81,3 +81,9 @@
 - **业务逻辑图/文档**：若项目内有「业务代码逻辑图」或架构说明，本次变更若影响模块/接口/数据流，建议同步更新该图或文档，便于新 Agent 或新人快速了解当前状态。

 本 Skill 与 **soul-change-checklist.mdc** 一起用，可系统化减少「只改一端、其它端漏改」的问题。
+
+---
+
+## 6. 迭代说明
+
+Skills 会随 bug 修复与项目演进持续升级。修 bug 时若发现本 Skill 中的规则、流程或关联检查项有遗漏或错误，应同步更新本 Skill，避免同类问题复现。详见 `.cursor/README.md` 中「Skills 迭代」。