From 299a891d2dcfe2e6a39824686ff582275e49150b Mon Sep 17 00:00:00 2001 From: Alex-larget <33240357+Alex-larget@users.noreply.github.com> Date: Thu, 26 Feb 2026 20:31:40 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=BC=80=E5=8F=91=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E8=B0=83=E6=95=B4=E5=9B=A2=E9=98=9F=E8=A7=92?= =?UTF-8?q?=E8=89=B2=E5=8F=8A=E5=85=B6=E6=8A=80=E8=83=BD=E6=8F=8F=E8=BF=B0?= =?UTF-8?q?=EF=BC=8C=E6=98=8E=E7=A1=AE=E5=90=84=E8=A7=92=E8=89=B2=E7=9A=84?= =?UTF-8?q?=E8=B4=A3=E4=BB=BB=E4=B8=8E=E5=8D=8F=E4=BD=9C=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E3=80=82=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84?= =?UTF-8?q?=EF=BC=8C=E7=A1=AE=E4=BF=9D=E5=BC=80=E5=8F=91=E9=A3=8E=E6=A0=BC?= =?UTF-8?q?=E4=B8=80=E8=87=B4=E6=80=A7=EF=BC=8C=E5=A2=9E=E5=BC=BA=E7=BB=8F?= =?UTF-8?q?=E9=AA=8C=E5=BA=93=E5=8A=9F=E8=83=BD=EF=BC=8C=E6=94=AF=E6=8C=81?= =?UTF-8?q?=E7=BB=8F=E9=AA=8C=E5=90=B8=E6=94=B6=E4=B8=8E=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=8D=87=E7=BA=A7=E6=B5=81=E7=A8=8B=E3=80=82=E5=88=A0=E9=99=A4?= =?UTF-8?q?=E4=B8=8D=E5=86=8D=E4=BD=BF=E7=94=A8=E7=9A=84=E8=A7=84=E5=88=99?= =?UTF-8?q?=E6=96=87=E4=BB=B6=EF=BC=8C=E7=AE=80=E5=8C=96=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84=EF=BC=8C=E6=8F=90=E5=8D=87=E5=9B=A2=E9=98=9F?= =?UTF-8?q?=E5=8D=8F=E4=BD=9C=E6=95=88=E7=8E=87=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/README.md | 34 ++++--- .cursor/docs/三角色边界定义.md | 2 +- .cursor/docs/开发团队职责定义.md | 6 +- .cursor/rules/api-reliability.mdc | 70 --------------- .cursor/rules/assistant-xiaofeng.mdc | 38 ++------ .cursor/rules/product-manager.mdc | 4 +- .cursor/rules/soul-admin-boundary.mdc | 7 +- .cursor/rules/soul-api-boundary.mdc | 41 --------- .cursor/rules/soul-api-coding.mdc | 90 ------------------- .cursor/rules/soul-api.mdc | 75 ++++++++++++++++ .cursor/rules/soul-change-checklist.mdc | 2 +- .cursor/rules/soul-miniprogram-boundary.mdc | 7 +- .cursor/rules/soul-project-boundary.mdc | 68 ++++++-------- .cursor/skills/SKILL-API开发.md | 2 +- .../SKILL-Next全栈拆解为前后端分离与小程序.md | 2 +- .cursor/skills/SKILL-三端架构与框架分析.md | 2 +- .cursor/skills/SKILL-变更关联检查.md | 2 +- .cursor/skills/SKILL-角色流程控制.md | 2 +- 开发文档/列表标准与角色分工.md | 2 +- 19 files changed, 146 insertions(+), 310 deletions(-) delete mode 100644 .cursor/rules/api-reliability.mdc delete mode 100644 .cursor/rules/soul-api-boundary.mdc delete mode 100644 .cursor/rules/soul-api-coding.mdc create mode 100644 .cursor/rules/soul-api.mdc diff --git a/.cursor/README.md b/.cursor/README.md index f962e8a9..d60ca0c0 100644 --- a/.cursor/README.md +++ b/.cursor/README.md @@ -33,18 +33,18 @@ --- -## 快速决策 +## 快速决策（必须 Read = 使用 Read 工具读取完整内容） -| 编辑/场景 | 加载 | -|-----------|------| -| miniprogram/ | SKILL-小程序开发 + soul-miniprogram-boundary | -| soul-admin/ | SKILL-管理端开发 + soul-admin-boundary | -| soul-api/ | SKILL-API开发 + soul-api-boundary、soul-api-coding | -| 开发文档/1、需求/、临时需求池/ | SKILL-产品经理 | -| 小橙、橙子、讨论完毕、记录、同步文档 | SKILL-助理橙子-文档同步 | -| 吸收经验、升级 skills | 助理橙子：经验入库 + 升级 Skill | -| 跨端功能开发 | SKILL-角色流程控制（流程图见 docs/角色协同流程图.html） | -| 变更完成 | 必过 SKILL-变更关联检查 + soul-change-checklist | +| 编辑/场景 | 必须 Read 的 Skill | 自动加载的 Rule | +|-----------|-------------------|----------------| +| miniprogram/ | `SKILL-小程序开发.md` | soul-miniprogram-boundary | +| soul-admin/ | `SKILL-管理端开发.md` | soul-admin-boundary | +| soul-api/ | `SKILL-API开发.md` | soul-api | +| 开发文档/1、需求/、临时需求池/ | `SKILL-产品经理.md` | product-manager | +| 小橙、橙子、讨论完毕、记录、同步文档 | `SKILL-助理橙子-文档同步.md` | assistant-xiaofeng | +| 吸收经验、升级 skills | `SKILL-助理橙子-文档同步.md`（经验入库章节） | assistant-xiaofeng | +| 跨端功能开发 | `SKILL-角色流程控制.md` | - | +| 变更完成 | `SKILL-变更关联检查.md` | soul-change-checklist | --- @@ -52,15 +52,13 @@ | 规则 | 生效范围 | 用途 | |------|----------|------| -| soul-project-boundary | `**` | 总入口、防互窜、会话自检 | +| soul-project-boundary | `**`（alwaysApply） | 项目组成、核心原则、会话自检 | | soul-change-checklist | miniprogram、soul-admin、soul-api | 变更后必过 | -| assistant-xiaofeng | 触发词 | 小橙：文档同步、经验升级 | +| assistant-xiaofeng | 触发词 | 小橙触发器 → SKILL-助理橙子-文档同步 | | soul-miniprogram-boundary | miniprogram/** | 只调 /api/miniprogram/* | | soul-admin-boundary | soul-admin/** | 只调 /api/admin/*、/api/db/* | -| soul-api-boundary | soul-api/**/*.go | 路由按使用方归类 | -| soul-api-coding | soul-api/**/*.go | GORM、Model、响应规范 | -| product-manager | 开发文档/1、需求/、临时需求池/ | 产品经理 | -| api-reliability | next-project/** | 仅 next-project 参考 | +| soul-api | soul-api/**/*.go | 路由边界 + 编码规范（合并版） | +| product-manager | 开发文档/1、需求/、临时需求池/ | 产品经理 glob 触发 | --- @@ -72,7 +70,7 @@ |------|----------|------------| | 小程序开发工程师 | SKILL-小程序开发 | 三端架构 → API开发 → 变更关联检查 | | 管理端开发工程师 | SKILL-管理端开发 | 三端架构 → API开发 → 变更关联检查 | -| 后端开发 | SKILL-API开发 | soul-api-coding → 三端架构 → 变更关联检查 → MySQL直接操作 | +| 后端开发 | SKILL-API开发 | soul-api 规范 → 三端架构 → 变更关联检查 → MySQL直接操作 | | 产品经理 | SKILL-产品经理 | 需求汇总、运营与变更 | | 助理橙子 | SKILL-助理橙子-文档同步 | - | diff --git a/.cursor/docs/三角色边界定义.md b/.cursor/docs/三角色边界定义.md index 39bd6612..894345db 100644 --- a/.cursor/docs/三角色边界定义.md +++ b/.cursor/docs/三角色边界定义.md @@ -140,7 +140,7 @@ |----------|------|--------|----------| | miniprogram/** | 小程序开发工程师 | soul-miniprogram-boundary | SKILL-小程序开发.md | | soul-admin/** | 管理端开发工程师 | soul-admin-boundary | SKILL-管理端开发.md | -| soul-api/** | 后端开发 | soul-api-boundary、soul-api-coding | SKILL-API开发.md | +| soul-api/** | 后端开发 | soul-api | SKILL-API开发.md | --- diff --git a/.cursor/docs/开发团队职责定义.md b/.cursor/docs/开发团队职责定义.md index 9338bbf2..e6ed1030 100644 --- a/.cursor/docs/开发团队职责定义.md +++ b/.cursor/docs/开发团队职责定义.md @@ -47,7 +47,7 @@ | **源码** | soul-api/internal/router、handler、model、wechat、config | | **路由** | 按使用方挂 miniprogram / admin / db / payment | | **主 Skill** | SKILL-API开发.md | -| **辅助** | soul-api-coding → 三端架构 → 变更关联检查 → MySQL直接操作 | +| **辅助** | soul-api 规范 → 三端架构 → 变更关联检查 → MySQL直接操作 | | **协同** | SKILL-角色流程控制.md（跨端时） | --- @@ -80,7 +80,7 @@ |------|----------|------------|------------| | 小程序开发工程师 | SKILL-小程序开发 | 三端架构、API开发、变更关联检查 | 角色流程控制 | | 管理端开发工程师 | SKILL-管理端开发 | 三端架构、API开发、变更关联检查 | 角色流程控制 | -| 后端开发 | SKILL-API开发 | soul-api-coding、三端架构、变更关联检查、MySQL直接操作 | 角色流程控制 | +| 后端开发 | SKILL-API开发 | soul-api 规范、三端架构、变更关联检查、MySQL直接操作 | 角色流程控制 | | 产品经理 | SKILL-产品经理 | 需求汇总、运营与变更 | - | | 助理橙子 | SKILL-助理橙子-文档同步 | - | - | @@ -101,7 +101,7 @@ |----------|----------|------| | 编辑 miniprogram/** | 小程序开发工程师 | SKILL-小程序开发 + soul-miniprogram-boundary | | 编辑 soul-admin/** | 管理端开发工程师 | SKILL-管理端开发 + soul-admin-boundary | -| 编辑 soul-api/** | 后端开发 | SKILL-API开发 + soul-api-boundary、soul-api-coding | +| 编辑 soul-api/** | 后端开发 | SKILL-API开发 + soul-api | | 编辑 开发文档/1、需求/、临时需求池/ | 产品经理 | SKILL-产品经理 | | 说 小橙、橙子、讨论完毕、记录、同步文档 | 助理橙子 | SKILL-助理橙子-文档同步 | diff --git a/.cursor/rules/api-reliability.mdc b/.cursor/rules/api-reliability.mdc deleted file mode 100644 index d72b86ff..00000000 --- a/.cursor/rules/api-reliability.mdc +++ /dev/null @@ -1,70 +0,0 @@ ---- -description: next-project API 稳定性与提现规范（仅 next-project 参考，soul-api 为 Go 不适用） -globs: ["next-project/**/*"] -alwaysApply: false ---- - -# API 稳定性与提现模块开发规范（next-project） - -**适用范围**：本规则仅适用于 **next-project**（Next.js + lib/db.ts）。当前线上后端为 **soul-api**（Go + GORM），不涉及 `query()`、`toArray`、`ensureTableExists`，请勿在 soul-api 中套用本规则。 - -## 核心原则 - -在 **next-project** 中开发 API（尤其是涉及财务和管理后台的接口）时，必须遵守以下稳定性规则，以防止常见的 JavaScript 运行时错误。 - -## 1. 数据库查询安全性 (防御 `undefined.length`) - -**问题背景**：`lib/db.ts` 中的 `query()` 在网络波动或表不存在时可能返回 `undefined`。 - -**要求**： - -- 所有调用 `query()` 的结果必须经过 `toArray` 处理。 -- 在 API 文件顶部定义 `toArray` 辅助函数： -```typescript -function toArray(x: any): T[] { - if (x == null) return []; - if (Array.isArray(x)) return x; - return [x]; -} -``` -- 使用方式：`const rows = toArray(await query(sql))`。 - -## 2. 数据库自愈 (Self-Healing Tables) - -**要求**： - -- 在 `GET` 接口逻辑开始前，必须调用 `ensureTableExists()` 函数。 -- 确保核心表（如 `withdrawals`）在查询前已存在，避免 `Table 'xxx' doesn't exist` 导致的 500 错误。 - -## 3. 提现模块状态映射 - -**映射标准**： - -- **数据库存值**：`pending` (待处理), `processing` (处理中), `success` (成功), `failed` (失败) -- **前端显示值**：`pending`, `processing`, `completed` (已完成), `rejected` (已拒绝) -- **转换逻辑**： -```typescript -const displayStatus = dbStatus === 'success' ? 'completed' : (dbStatus === 'failed' ? 'rejected' : dbStatus); -``` - -## 4. 财务字段处理 - -- **金额转换**：从数据库读取的 `decimal` 类型必须经过 `parseFloat()` 转换后再进行数学运算。 -- **配置归一化**：分成比例字段（如 `distributorShare`）必须兼容 `90` 和 `0.9` 两种存值： -```typescript -let rate = Number(val); -if (rate >= 1) rate = rate / 100; // 将 90 转为 0.9 -``` - -## 5. 管理后台列表必备字段 - -所有管理后台的 API 必须包含以下映射字段以支持通用 UI 组件： - -- `user_name` 或 `userNickname`: 展示用户名称。 -- `userAvatar`: 展示头像（若无，前端需展示首字母）。 -- `status`: 统一后的显示状态。 -- `amount`: 格式化后的数字金额。 - -## 6. 调试模式 - -- 遇到顽固 500 错误时，优先采用“最小化接口法”：移除所有业务逻辑，仅返回 `{success: true, data: []}`，确认通路正常后再分步加回代码。 diff --git a/.cursor/rules/assistant-xiaofeng.mdc b/.cursor/rules/assistant-xiaofeng.mdc index 695520e9..e73ab9b2 100644 --- a/.cursor/rules/assistant-xiaofeng.mdc +++ b/.cursor/rules/assistant-xiaofeng.mdc @@ -1,40 +1,16 @@ --- -description: 小橙/橙子/橙橙/🍊 - 开发团队文档同步与经验升级助理 +description: 小橙/橙子/橙橙/🍊 - 文档同步与经验升级助理 globs: ["**"] alwaysApply: false --- -# 小橙（橙子/橙橙/🍊）- 开发团队文档同步与经验升级助理 +# 小橙触发器 -## 角色定义 +当用户提及**小橙、橙子、橙橙、🍊**，或说**「讨论完毕」「记录一下」「同步到开发文档」「吸收经验」「升级 skills」**时： -**小橙**（橙子、橙橙、🍊）是开发团队文档同步与经验升级助理。以下任一表述均可唤醒：小橙、橙子、橙橙、🍊、「讨论完毕」「记录一下」「同步到开发文档」「吸收经验」「升级 skills」等。讨论告一段落需要沉淀时，以小橙身份执行文档同步；用户说「吸收经验」「升级 skills」时，执行经验入库并升级对应 Skill。 +**必须使用 Read 工具读取 `.cursor/skills/SKILL-助理橙子-文档同步.md` 的完整内容**，然后严格按其流程执行。 -## 执行时机 +### 行为摘要（供模型快速理解，完整流程以 SKILL 文件为准） -- 用户明确要求记录/同步/更新开发文档 -- 讨论完成、需求确认、方案定稿后，用户希望沉淀到文档 -- 功能开发完成、需求变更后，需更新项目状态 - -## 执行动作 - -1. **记录讨论要点**：提炼本次讨论的结论、决策、待办 -2. **更新开发文档**：按内容类型写入对应文档 -3. **保持文档一致**：确保 需求汇总、运营与变更、临时需求池 等相互引用一致 -4. **经验吸收与 Skills 升级**（当用户说「吸收经验」「升级 skills」时）：提炼经验 → 写入 `.cursor/经验库/` → 更新对应 `.cursor/skills/SKILL-xxx.md` - -## 文档更新映射 - -| 内容类型 | 目标文档 | 更新方式 | -|----------|----------|----------| -| 需求/功能变更 | `开发文档/1、需求/需求汇总.md` | 需求清单新增/更新行 | -| 近期讨论、项目状态 | `开发文档/10、项目管理/运营与变更.md` | 第五部分或新增「近期讨论」节 | -| 技术方案、待实现 | `临时需求池/` 或 `开发文档/8、部署/` | 新建或更新对应分析/说明文档 | -| 项目推进、里程碑 | `开发文档/10、项目管理/项目落地推进表.md` | 第十二节或对应阶段 | -| 经验沉淀、Skills 升级 | `.cursor/经验库/` | 经验清单索引 + 更新对应 Skill | - -## 输出格式 - -- 更新文档时保留原有结构，增量追加或按表头更新 -- 每条记录含：日期、描述、状态、备注 -- 技术分析类文档放在 `临时需求池/` 或 `开发文档/8、部署/`，便于后续实施时引用 +1. **文档同步**：从对话中提炼结论/待办/变更 → 写入 `开发文档/1、需求/需求汇总.md`、`开发文档/10、项目管理/运营与变更.md`、`临时需求池/` 等对应文档 +2. **经验入库**：提炼经验 → 写入 `.cursor/经验库/经验清单.md` → 更新对应 `.cursor/skills/SKILL-xxx.md` diff --git a/.cursor/rules/product-manager.mdc b/.cursor/rules/product-manager.mdc index 360c3f0e..374e2f21 100644 --- a/.cursor/rules/product-manager.mdc +++ b/.cursor/rules/product-manager.mdc @@ -6,6 +6,6 @@ alwaysApply: false # 产品经理 -当编辑 **开发文档/1、需求/**、**临时需求池/**、**开发文档/10、项目管理/** 时，推断当前角色为**产品经理**，加载 **SKILL-产品经理.md**。 +当编辑 **开发文档/1、需求/**、**临时需求池/**、**开发文档/10、项目管理/** 时，推断当前角色为**产品经理**。 -职责：需求分析、需求文档、验收标准、与开发协调。 +**必须使用 Read 工具读取 `.cursor/skills/SKILL-产品经理.md` 的完整内容**，然后按其规范执行需求分析、文档编写、验收标准制定。 diff --git a/.cursor/rules/soul-admin-boundary.mdc b/.cursor/rules/soul-admin-boundary.mdc index 255dc306..26a1f98c 100644 --- a/.cursor/rules/soul-admin-boundary.mdc +++ b/.cursor/rules/soul-admin-boundary.mdc @@ -24,9 +24,10 @@ alwaysApply: false - 仅修改 **soul-admin/** 内文件（含 src/pages、src/components、src/api、src/layouts 等）。 - 不在此处实现小程序逻辑；不在此处编写 soul-api 的 Go 代码或 miniprogram 的 WXML/WXSS/JS。 -## 参考 +## Skill 加载（必须执行） -- 代码风格、业务逻辑与 API 对接细节见 **.cursor/skills/SKILL-管理端开发.md**。 -- 接口实现与路由分组见 soul-api 的 `.cursor/rules/soul-api-coding.mdc` 与 **.cursor/skills/SKILL-API开发.md**。 +**必须使用 Read 工具读取 `.cursor/skills/SKILL-管理端开发.md` 的完整内容**，按其规范进行开发。该 Skill 包含代码风格、业务逻辑、API 对接细节等完整约定。 + +接口实现与路由分组的规范在 `.cursor/rules/soul-api.mdc`（编辑 soul-api 时自动加载）。 违反上述路径或职责边界即视为「互窜」，需纠正后再提交。 diff --git a/.cursor/rules/soul-api-boundary.mdc b/.cursor/rules/soul-api-boundary.mdc deleted file mode 100644 index 7339b3a2..00000000 --- a/.cursor/rules/soul-api-boundary.mdc +++ /dev/null @@ -1,41 +0,0 @@ ---- -description: soul-api 路由与使用方边界，防止管理端与小程序接口互窜 -globs: soul-api/**/*.go -alwaysApply: false ---- - -# soul-api 开发边界（防互窜） - -在 **soul-api/** 下新增、优化或编辑 Go 代码（尤其是路由与 handler）时，必须遵守以下约束： - -## 路由按使用方归类（强制） - -**新增接口时，必须先判断使用方（小程序 / 管理端 / 两端共用），再决定挂到哪个 Group。禁止写「通用路径」让两端混用。** - -- **仅管理端用的接口**：只挂在 `admin` 或 `db` 组（`/api/admin/*`、`/api/db/*`），**不得**在 `miniprogram` 组注册。 -- **仅小程序用的接口**：只挂在 `miniprogram` 组（`/api/miniprogram/*`），**不得**仅在 admin/db 下注册而让小程序去调 `/api/xxx`。 -- **两端共用的接口**：在 `api` 下挂一份，并在 `miniprogram` 组内用同一 handler 再挂一遍，保证小程序统一走 `/api/miniprogram/xxx`；handler 注释中标明使用方（如「小程序-提现记录」「管理端-提现列表」）。 - -**重要**：即使业务逻辑完全相同，**也必须按使用方做路径区分**。例如 VIP 相关接口，若小程序和管理端都要用，应提供： -- 管理端：`/api/admin/vip/*` 或 `/api/db/vip/*` -- 小程序：`/api/miniprogram/vip/*`（可复用同一 handler，但路径必须显式挂到 miniprogram 组） - -不得仅提供 `/api/vip/*` 让两端共用，违反项目边界约定。 - -## 禁止行为 - -- 禁止在 `miniprogram` 组挂仅管理端调用的接口（如后台审核、DB 初始化）。 -- 禁止在 `admin`/`db` 组挂小程序专属逻辑（如 wx code 登录、小程序码生成），除非该逻辑同时以「管理端可用的形式」在 admin 下提供。 -- 禁止在 handler 内混用「管理端路径」与「小程序路径」的语义（如根据 path 分支写两套业务而不按使用方拆 handler/路由）。 - -## 目录与职责 - -- 路由注册仅在 **internal/router** 中修改；handler 在 **internal/handler**；model 在 **internal/model**；配置在 **internal/config**；微信/支付在 **internal/wechat**。 -- 新增接口流程：先确定使用方（小程序 / 管理端 / 共用） → 再决定挂到哪个 Group → 再实现或修改 handler。 - -## 参考 - -- 完整编码规范与 GORM/响应约定见 **.cursor/rules/soul-api-coding.mdc**。 -- 归纳与对接要点见 **.cursor/skills/SKILL-API开发.md**。 - -违反上述路由归类或职责边界即视为「互窜」，需纠正后再提交。 diff --git a/.cursor/rules/soul-api-coding.mdc b/.cursor/rules/soul-api-coding.mdc deleted file mode 100644 index c08aca39..00000000 --- a/.cursor/rules/soul-api-coding.mdc +++ /dev/null @@ -1,90 +0,0 @@ ---- -description: soul-api 编码风格与规范（GORM、依赖使用、项目约定） -globs: soul-api/**/*.go -alwaysApply: false ---- - -# soul-api 编码规范 - -## 1. 数据访问：优先 ORM（GORM） - -- **一律使用 GORM 进行数据读写**，通过 `database.DB()` 获取 `*gorm.DB`，操作集中在 `internal/model` 中定义的模型上。 -- **禁止**在 handler 中手写 `db.Exec("INSERT ...")`、`db.Raw("SELECT ...")` 等裸 SQL，除非满足下方「例外」。 -- 常规 CRUD 必须用 GORM 链式 API： - - 查询：`db.Where(...).First/Find/Count`、`db.Preload`、`db.Select`、`db.Order`、`db.Pluck`（单列）、`db.Joins`（关联） - - 写入：`db.Create`、`db.Save`、`db.Model(...).Updates(map/struct)`、`db.Where(...).Delete` - - 原子更新：用 `gorm.Expr`，例如 `Update("pending_earnings", gorm.Expr("pending_earnings + ?", delta))`，而不是多行 Raw/Exec。 -- **事务（必用）**：涉及多表写入（如支付回调、分佣、订单+用户同时更新）必须用 `db.Transaction(func(tx *gorm.DB) error { ... })` 包裹，避免部分成功导致数据不一致。 -- **Preload**：列表返回关联数据（如 orders 带 user）时，优先用 `db.Preload("User").Find(&orders)` 或 `db.Joins` 减少 N+1；无 GORM 关联定义时可用 `Joins` 或 `Where("id IN ?", ids).Find(&users)` 批量查。 -- **Pluck**：仅需单列时用 `db.Model(&Order{}).Where(...).Pluck("product_id", &ids)`，不写 Raw。 -- **Scopes**：复杂或重复的查询条件可抽成 `func(db *gorm.DB) *gorm.DB` 的 Scopes，便于复用。 -- **例外**（允许少量 Raw/Exec）： - - 单条复杂统计 SQL 且用 GORM 表达冗长时，可用 `db.Raw(...).Scan(&struct)`，并加简短注释说明原因。 - - 必须用原生 SQL 的原子多列更新（如多字段 `SET a=a+?, b=b+?`）可保留 `db.Exec`，其余尽量改为 `Model().Update(Expr(...))`。 - -## 2. Model 与表结构 - -- 所有表对应结构体放在 `internal/model`，文件名与业务一致（如 `user.go`、`order.go`）。 -- 结构体必须包含： - - `gorm` 标签：`column`、`primaryKey`、`type` 等； - - `json` 标签：对外 API 字段用小写驼峰（如 `openId`）； - - 实现 `TableName() string` 返回表名（若表名与默认规则不一致）。 -- 不对外暴露的字段用 `json:"-"`（如 `SessionKey`、`PurchasedSections`）。 - -## 3. 依赖物尽其用 - -- **Gin**：入参用 `c.ShouldBindJSON(&req)` + `binding` 标签做校验；统一用 `c.JSON(status, gin.H{...})` 或结构体返回；路由按功能挂在 `router.Setup` 的对应 Group（如 `/admin` 用 `middleware.AdminAuth()`）。 - - **binding 标签**：`required`、`min=N`、`max=N`、`len=N`、`email`、`gte`、`lte` 等（go-playground/validator）；金额可用 `binding:"required,gte=0"`，手机号可用 `binding:"required,len=11"`。 -- **GORM**：能用链式条件、Scopes、Preload、Pluck、Joins 完成的，不写 Raw；多表写入必须用 `db.Transaction`。 -- **配置**：仅通过 `internal/config` 的 `config.Load()` 读环境变量；业务代码不直接 `os.Getenv`；新配置项加到 `Config` 结构体并在 `Load()` 中解析。 -- **中间件**：安全头用 `middleware.Secure()`，跨域用 `cors`，限流用 `middleware.NewRateLimiter(...).Middleware()`；新路由按需挂到已有或新 Group，避免重复造轮子。 -- **微信/支付**：小程序、支付、转账相关统一走 `internal/wechat` 封装（PowerWeChat），handler 只做参数与结果转换。 -- **JWT**：管理端鉴权用 `internal/auth` 的 `IssueAdminJWT`、`ParseAdminJWT`、`GetAdminJWTFromRequest`，不手写 token 解析。 -- **godotenv**：配置加载在 `config.Load()` 内完成，业务代码不直接调。 -- **Redis**：当前为间接依赖（PowerWeChat 引入），未直接使用；若需分布式缓存或限流，可显式引入并统一封装，避免各处散落。 - -## 4. 接口按使用方归类（小程序 vs 管理端） - -新增或修改接口时，**必须先明确使用方**，再挂到对应路由组，避免混用： - -| 使用方 | 路由组 | 路径前缀 | 鉴权 | -|--------|--------|----------|------| -| **管理端** | `admin := api.Group("/admin")` | `/api/admin/...` | `middleware.AdminAuth()` | -| **管理端（数据/配置）** | `db := api.Group("/db")` | `/api/db/...` | `middleware.AdminAuth()` | -| **小程序** | `miniprogram := api.Group("/miniprogram")` | `/api/miniprogram/...` | 按接口需要（如 token） | -| **两端共用** | 在 `api` 下挂通用路径，并在 `miniprogram` 下挂同 path | `/api/xxx` 与 `/api/miniprogram/xxx` | 各自鉴权 | - -**规则：** - -- **仅管理端用的接口**：只挂在 `admin` 或 `db` 下，不要出现在 `miniprogram`。 -- **仅小程序用的接口**：只挂在 `miniprogram` 下（如登录、支付、提现、小程序专属配置等）。 -- **两端共用的接口**：在 `router.go` 里两处都注册同一 handler：先写在 `api` 的对应区块（如「推荐」「用户」），再在 `// ----- 小程序组 -----` 里用 `miniprogram.GET/POST(... path, handler.XXX)` 挂一遍，保证小程序统一走 `/api/miniprogram/xxx`。 -- handler 注释和路由注释中标明使用方，例如：`// GET /api/miniprogram/withdraw/records 小程序-提现记录`、`// GET /api/admin/withdrawals 管理端-提现列表`。 - -**工程师必守：即使业务逻辑完全相同，也必须按使用方做路径区分。** 例如 VIP 相关接口（status、profile、members 等），若小程序和管理端都要用： -- 管理端：`/api/admin/vip/*` 或 `/api/db/vip/*` -- 小程序：`/api/miniprogram/vip/*`（可复用同一 handler，但路径必须显式挂到 miniprogram 组） - -禁止仅提供 `/api/vip/*` 等「通用路径」让两端混用，违反项目边界。 - -**管理端列表接口返回约定**：列表类接口（如 withdrawals、orders、users）的响应应包含 soul-admin 通用展示所需字段：`user_name` 或 `userNickname`、`userAvatar`、`status`、`amount`（金额用数字）。提现状态：数据库存值 `pending`/`processing`/`success`/`failed`，前端展示可映射 `success`→`completed`、`failed`→`rejected`。 - -## 5. 目录与包约定 - -- `cmd/server/main.go`：入口，只做 config/database/wechat/router 的初始化与启停。 -- `internal/handler`：HTTP 处理函数，只做绑定、校验、调 DB/wechat、写响应；不写复杂业务逻辑时可暂时放在 handler，逻辑变复杂时再抽到 `internal/service`。 -- `internal/router`：注册路由与中间件，不写业务逻辑；新增路由时按「4. 接口按使用方归类」决定挂到 admin / db / miniprogram 或 api+miniprogram。 -- `internal/database`：仅提供 `Init(dsn)` 与 `DB() *gorm.DB`。 -- 新增接口时：先确定**使用方（小程序 / 管理端 / 共用）** → 再确定路由与 Group → 在对应 handler 中实现，数据库操作用 GORM + model。 - -## 6. 响应与错误 - -- 统一约定：成功 `gin.H{"success": true, "data": ...}` 或 `"message": "..."`；失败 `gin.H{"success": false, "error": "..."}`。 -- 不吞掉错误：DB/wechat 返回的 `err` 必须处理，并向前端返回明确错误信息或日志。 -- HTTP 状态码：业务错误可用 200 + `success: false`（与现网一致）；需要明确表达「未授权/禁止」时用 401/403。 - -## 7. 代码风格 - -- 遵循 `gofmt`，提交前保持格式一致。 -- 包内命名：导出函数用 PascalCase，内部用 camelCase；与接口语义一致（如 `ReferralBind`、`GetPublicDBConfig`）。 -- 注释：公开 handler 或复杂逻辑处写清用途（如 `// POST /api/referral/bind 推荐码绑定`）。 diff --git a/.cursor/rules/soul-api.mdc b/.cursor/rules/soul-api.mdc new file mode 100644 index 00000000..400b8426 --- /dev/null +++ b/.cursor/rules/soul-api.mdc @@ -0,0 +1,75 @@ +--- +description: soul-api 路由边界 + 编码规范（合并版，防互窜 + GORM/Gin/响应约定） +globs: soul-api/**/*.go +alwaysApply: false +--- + +# soul-api 开发规范 + +> **Skill 加载**：编辑 soul-api 代码时，**必须使用 Read 工具读取 `.cursor/skills/SKILL-API开发.md` 的完整内容**，该 Skill 包含业务对接、与前端边界协同等补充约定。本规则侧重编码规范与路由边界。 + +## 1. 路由按使用方归类（强制） + +新增或修改接口必须**先明确使用方**，再挂到对应路由组： + +| 使用方 | 路由组 | 路径前缀 | 鉴权 | +|--------|--------|----------|------| +| 管理端 | `admin` / `db` | `/api/admin/…`、`/api/db/…` | `middleware.AdminAuth()` | +| 小程序 | `miniprogram` | `/api/miniprogram/…` | 按接口需要 | +| 两端共用 | `api` 下 + `miniprogram` 下各挂一遍 | `/api/xxx` 与 `/api/miniprogram/xxx` | 各自鉴权 | + +即使业务逻辑相同，也必须按使用方做路径区分。禁止仅提供 `/api/vip/*` 等通用路径让两端混用。 + +### 禁止行为 + +- 禁止在 `miniprogram` 组挂仅管理端调用的接口（后台审核、DB 初始化等）。 +- 禁止在 `admin`/`db` 组挂小程序专属逻辑（wx code 登录、小程序码生成等）。 +- 禁止在 handler 内混用管理端/小程序路径语义（根据 path 分支写两套业务而不按使用方拆 handler/路由）。 + +handler 注释标明使用方，如 `// GET /api/miniprogram/withdraw/records 小程序-提现记录`。 + +管理端列表接口需包含：`user_name`/`userNickname`、`userAvatar`、`status`、`amount`。提现状态 DB 存 `pending`/`processing`/`success`/`failed`。 + +## 2. 数据访问：优先 GORM + +- 通过 `database.DB()` 获取 `*gorm.DB`，操作集中在 `internal/model` 的模型上。 +- 常规 CRUD 必须用链式 API（`Where/First/Find/Create/Save/Updates/Delete`）。 +- 原子更新用 `gorm.Expr`，如 `Update("pending_earnings", gorm.Expr("pending_earnings + ?", delta))`。 +- 多表写入必须用 `db.Transaction(func(tx *gorm.DB) error { ... })`。 +- 用 `Preload`/`Joins` 减少 N+1；仅需单列时用 `Pluck`；重复条件抽 Scopes。 +- 禁止 handler 中手写 `db.Exec/db.Raw`，除非：复杂统计 SQL 用 GORM 表达冗长（须加注释）；原子多列 SET。 + +## 3. Model 与表结构 + +- 结构体放 `internal/model`，文件名与业务一致。 +- 必须包含 `gorm` 标签（column/primaryKey/type）+ `json` 标签（小写驼峰）。 +- 不对外暴露的字段用 `json:"-"`。 +- 实现 `TableName() string`（若表名与默认不一致）。 + +## 4. 依赖物尽其用 + +- **Gin**：入参 `c.ShouldBindJSON` + `binding` 标签校验；统一 `c.JSON` 返回。 +- **配置**：仅通过 `internal/config` 的 `config.Load()` 读环境变量，不直接 `os.Getenv`。 +- **中间件**：安全头 `middleware.Secure()`，跨域 `cors`，限流 `middleware.NewRateLimiter`。 +- **微信/支付**：统一走 `internal/wechat`（PowerWeChat），handler 只做参数与结果转换。 +- **JWT**：管理端鉴权用 `internal/auth` 的 `IssueAdminJWT`/`ParseAdminJWT`/`GetAdminJWTFromRequest`。 + +## 5. 目录与包约定 + +- `cmd/server/main.go`：入口，只做初始化与启停。 +- `internal/handler`：HTTP 处理函数，绑定→校验→调 DB/wechat→写响应。逻辑复杂时抽到 `internal/service`。 +- `internal/router`：注册路由与中间件，不写业务逻辑。 +- `internal/database`：仅提供 `Init(dsn)` 与 `DB()`。 +- 新增接口流程：确定使用方 → 确定路由 Group → 实现 handler + GORM model。 + +## 6. 响应与错误 + +- 成功：`gin.H{"success": true, "data": ...}` 或 `"message": "..."`。 +- 失败：`gin.H{"success": false, "error": "..."}`。 +- 不吞错误：DB/wechat 的 `err` 必须处理并返回。 +- HTTP 状态码：业务错误可用 200 + `success: false`；未授权/禁止用 401/403。 + +## 7. 代码风格 + +- 遵循 `gofmt`；导出函数 PascalCase，内部 camelCase。 +- 公开 handler 或复杂逻辑处写清用途注释。 diff --git a/.cursor/rules/soul-change-checklist.mdc b/.cursor/rules/soul-change-checklist.mdc index a8e1a4e2..a464fce7 100644 --- a/.cursor/rules/soul-change-checklist.mdc +++ b/.cursor/rules/soul-change-checklist.mdc @@ -30,6 +30,6 @@ alwaysApply: false - **每次**在 miniprogram、soul-admin、soul-api 内完成一轮修改后，**先过一遍上表 + 二**，再视为本次变更完成。 - 若本次变更涉及多端（例如小程序新功能 + 管理端配置页），应在同一次任务内一并完成或明确记录未做项，避免漏改。 -- 更详细的「如何做关联检查、以领域为单位思考」见 **.cursor/skills/SKILL-变更关联检查.md**。 +- 更详细的检查流程：**必须使用 Read 工具读取 `.cursor/skills/SKILL-变更关联检查.md` 的完整内容**，按其「以领域为单位思考」的方法逐项确认。 未通过上述检查即提交视为可能漏改，需补全后再提交。 diff --git a/.cursor/rules/soul-miniprogram-boundary.mdc b/.cursor/rules/soul-miniprogram-boundary.mdc index 41482b78..79f457d1 100644 --- a/.cursor/rules/soul-miniprogram-boundary.mdc +++ b/.cursor/rules/soul-miniprogram-boundary.mdc @@ -21,9 +21,10 @@ alwaysApply: false - 仅修改 **miniprogram/** 内文件（含 pages、components、utils、app.js 等）。 - 不在此处实现或引用管理端逻辑；不在此处编写 soul-api 的 Go 代码或 soul-admin 的 React 代码。 -## 参考 +## Skill 加载（必须执行） -- 代码风格、业务逻辑与 API 对接细节见 **.cursor/skills/SKILL-小程序开发.md**。 -- 接口实现与路由分组见 soul-api 的 `.cursor/rules/soul-api-coding.mdc` 与 **.cursor/skills/SKILL-API开发.md**。 +**必须使用 Read 工具读取 `.cursor/skills/SKILL-小程序开发.md` 的完整内容**，按其规范进行开发。该 Skill 包含代码风格、业务逻辑、API 对接细节等完整约定。 + +接口实现与路由分组的规范在 `.cursor/rules/soul-api.mdc`（编辑 soul-api 时自动加载）。 违反上述路径或职责边界即视为「互窜」，需纠正后再提交。 diff --git a/.cursor/rules/soul-project-boundary.mdc b/.cursor/rules/soul-project-boundary.mdc index 916e6d8f..f12dddbd 100644 --- a/.cursor/rules/soul-project-boundary.mdc +++ b/.cursor/rules/soul-project-boundary.mdc @@ -1,58 +1,44 @@ --- -description: Soul 创业派对项目整体边界与 Skill 索引，防止子项目互窜；含会话启动自检 +description: Soul 创业派对项目整体边界、角色推断与 Skill 加载（alwaysApply） globs: ["**"] alwaysApply: true --- -# Soul 创业派对 - 项目边界与开发约束 +# Soul 创业派对 - 项目边界 -## 会话启动自检（新 Cursor 打开本项目时优先执行） +## 会话自检 -当新的 Cursor 会话打开本项目时，**先进行自检**，确保仅沿用本项目的开发风格与配置： - -1. **Rules 与 Skills 范围**：仅使用本项目 `.cursor/rules/` 与 `.cursor/skills/` 下的规则与技能；不套用与本项目无关的全局或其它项目的 rules/skills（如存客宝AI、React 转 Vue、Next 全栈拆分等与本项目无关的能力）。 -2. **开发风格**：按**团队角色**（小程序开发工程师/管理端开发工程师/后端开发/产品经理/助理橙子）遵守对应 boundary 与 Skill；Skills 索引按角色驱动，见 `.cursor/README.md` 第二节；API 路径、路由分组、变更检查清单等均以本规则为准。 -3. **配置参数**：baseUrl、鉴权方式、路由前缀（`/api/miniprogram/*`、`/api/admin/*`、`/api/db/*`）等以项目内实际配置为准，不引入外部项目的默认值或约定。 -4. **清理无关项**：若发现会话上下文中存在与本项目无关的 rules 或 skills 引用，应忽略或排除，仅以本项目 `.cursor` 为准。 - -自检通过后，再按「项目组成」「防互窜原则」「开发时」执行后续开发。 - ---- +仅沿用本项目 `.cursor/` 下的 rules、skills、配置；忽略与本项目无关的全局 rules/skills。 ## 项目组成 -| 子项目 | 目录 | 用途 | 后端对接 | -|--------------|---------------|--------------------------|------------| -| 小程序 | miniprogram/ | 微信原生小程序 C 端 | soul-api | -| 管理端 | soul-admin/ | React 管理后台 | soul-api | -| API 后端 | soul-api/ | Go + Gin + GORM 接口服务 | - | -| 预览/参考 | next-project/ | 仅预览，非当前线上后端 | 不依赖 | +| 子项目 | 目录 | 用途 | 后端对接 | +|--------|------|------|----------| +| 小程序 | miniprogram/ | 微信原生小程序 C 端 | soul-api | +| 管理端 | soul-admin/ | React 管理后台 | soul-api | +| API 后端 | soul-api/ | Go + Gin + GORM 接口服务 | - | +| 预览/参考 | next-project/ | 仅预览，非线上 | 不依赖 | -- **线上约定**：小程序与管理端均只对接 **soul-api**；next-project 不参与当前线上联调与部署。 +## 核心原则 -## 防互窜原则 +- 小程序只调 `/api/miniprogram/*`；管理端只调 `/api/admin/*`、`/api/db/*`；禁止混用。 +- 变更完成必过 **soul-change-checklist.mdc** + 读取 `.cursor/skills/SKILL-变更关联检查.md`。 -1. **小程序**：只调 `/api/miniprogram/*`；不调 `/api/admin/*`、`/api/db/*`。详见 **soul-miniprogram-boundary.mdc** 与 **.cursor/skills/SKILL-小程序开发.md**。 -2. **管理端**：只调 `/api/admin/*`、`/api/db/*` 等管理端路径；不调 `/api/miniprogram/*`。详见 **soul-admin-boundary.mdc** 与 **.cursor/skills/SKILL-管理端开发.md**。 -3. **soul-api**：按使用方挂路由（admin/db vs miniprogram）；不在 miniprogram 组挂管理端专用接口，不在 admin/db 组挂小程序专属接口。详见 **soul-api-boundary.mdc**、**soul-api-coding.mdc** 与 **.cursor/skills/SKILL-API开发.md**。 -4. **next-project**：仅参考用；新增/优化功能以 miniprogram、soul-admin、soul-api 为准。详见 **.cursor/skills/SKILL-next-project仅预览.md**。 +## 角色推断与 Skill 加载（必须执行） -## 开发时 +根据当前编辑的目录，**必须使用 Read 工具读取对应的主 Skill 文件完整内容**，然后按其规范执行开发： -**角色推断**：根据当前编辑目录推断当前角色，加载对应主 Skill（Skills 索引按角色驱动，见 `.cursor/README.md` 第二节速查表）。 +| 编辑目录 | 推断角色 | 必须 Read 的主 Skill 文件 | +|----------|----------|---------------------------| +| miniprogram/ | 小程序开发工程师 | `.cursor/skills/SKILL-小程序开发.md` | +| soul-admin/ | 管理端开发工程师 | `.cursor/skills/SKILL-管理端开发.md` | +| soul-api/ | 后端开发 | `.cursor/skills/SKILL-API开发.md` | +| 开发文档/1、需求/、临时需求池/ | 产品经理 | `.cursor/skills/SKILL-产品经理.md` | -| 编辑目录 | 推断角色 | 必遵守 | 必参考主 Skill | -|----------|----------|--------|----------------| -| miniprogram/ | 小程序开发工程师 | soul-miniprogram-boundary | SKILL-小程序开发.md | -| soul-admin/ | 管理端开发工程师 | soul-admin-boundary | SKILL-管理端开发.md | -| soul-api/ | 后端开发 | soul-api-boundary、soul-api-coding | SKILL-API开发.md | -| 开发文档/1、需求/、临时需求池/ | 产品经理 | - | SKILL-产品经理.md | -| 说 小橙、橙子、讨论完毕 | 助理橙子 | assistant-xiaofeng | SKILL-助理橙子-文档同步.md | +| 场景触发词 | 必须 Read 的 Skill 文件 | +|------------|-------------------------| +| 小橙、橙子、讨论完毕、记录、同步文档 | `.cursor/skills/SKILL-助理橙子-文档同步.md` | +| 吸收经验、升级 skills | `.cursor/skills/SKILL-助理橙子-文档同步.md`（经验入库章节） | +| 跨端功能开发 | `.cursor/skills/SKILL-角色流程控制.md` | -| 场景 | 动作 | -|------|------| -| 涉及「该接口给谁用」 | 先确定使用方再写/改代码，避免路径混用 | -| **跨端功能开发** | 加载 **SKILL-角色流程控制.md**，按协同流程执行 | -| **变更完成准备提交** | **必过** **soul-change-checklist.mdc** + **SKILL-变更关联检查.md**，未过即视为漏改 | -| **小橙/橙子/橙橙/🍊、讨论完毕、记录、同步文档** | 加载 **SKILL-助理橙子-文档同步.md**，以小橙身份更新开发文档 | -| **吸收经验、升级 skills、记录经验** | 助理橙子执行经验入库（`.cursor/经验库/`）+ 升级对应 Skill | +**注意**：「必须 Read」= 使用 Read 工具读取文件完整内容后执行，不可跳过或仅凭记忆。 diff --git a/.cursor/skills/SKILL-API开发.md b/.cursor/skills/SKILL-API开发.md index 63c764bd..476d13aa 100644 --- a/.cursor/skills/SKILL-API开发.md +++ b/.cursor/skills/SKILL-API开发.md @@ -4,7 +4,7 @@ description: Soul 创业派对后端 API 开发规范。在 soul-api/ 下编辑 --- # Soul 创业派对 - API 开发 Skill（soul-api） -当你在 **soul-api/** 目录下新增、优化或编辑 Go 代码时，必须遵循本 Skill。本 Skill 与 `.cursor/rules/soul-api-coding.mdc` 一致并做归纳，重点强调「按使用方归类路由」和「与 miniprogram / soul-admin 的边界」，防止接口互窜。 +当你在 **soul-api/** 目录下新增、优化或编辑 Go 代码时，必须遵循本 Skill。本 Skill 与 `.cursor/rules/soul-api.mdc` 一致并做归纳，重点强调「按使用方归类路由」和「与 miniprogram / soul-admin 的边界」，防止接口互窜。 --- diff --git a/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md b/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md index 9b52d37b..b581f8a0 100644 --- a/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md +++ b/.cursor/skills/SKILL-Next全栈拆解为前后端分离与小程序.md @@ -170,7 +170,7 @@ next-project/ 拆解完成后，开发约束以本仓库为准： -- **soul-api**：遵守 soul-api-coding.mdc、SKILL-API开发.md +- **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 diff --git a/.cursor/skills/SKILL-三端架构与框架分析.md b/.cursor/skills/SKILL-三端架构与框架分析.md index eb2ab280..a9e614c4 100644 --- a/.cursor/skills/SKILL-三端架构与框架分析.md +++ b/.cursor/skills/SKILL-三端架构与框架分析.md @@ -201,7 +201,7 @@ soul-api/ - **soul-miniprogram-boundary**：miniprogram 只调 `/api/miniprogram/*` - **soul-admin-boundary**：soul-admin 只调 `/api/admin/*`、`/api/db/*` -- **soul-api-boundary**：路由按使用方分组 +- **soul-api**：路由按使用方分组 + 编码规范 - **SKILL-小程序开发**：小程序请求、scene、支付等约定 - **SKILL-管理端开发**：管理端 client、auth 约定 - **SKILL-API开发**：soul-api 编码规范 diff --git a/.cursor/skills/SKILL-变更关联检查.md b/.cursor/skills/SKILL-变更关联检查.md index a6eaf162..b025efa1 100644 --- a/.cursor/skills/SKILL-变更关联检查.md +++ b/.cursor/skills/SKILL-变更关联检查.md @@ -83,7 +83,7 @@ description: Soul 创业派对变更关联检查。miniprogram/soul-admin/soul-a ## 5. 与其它约定配合 -- **路径与使用方**：仍遵守 soul-miniprogram-boundary、soul-admin-boundary、soul-api-boundary（谁调哪组接口、谁挂哪条路由）。后端工程师新增接口时，必须先判断使用方，再挂到对应 Group；即使逻辑完全相同，也必须按使用方做路径区分，禁止通用路径混用。 +- **路径与使用方**：仍遵守 soul-miniprogram-boundary、soul-admin-boundary、soul-api（谁调哪组接口、谁挂哪条路由）。后端工程师新增接口时，必须先判断使用方，再挂到对应 Group；即使逻辑完全相同，也必须按使用方做路径区分，禁止通用路径混用。 - **业务逻辑图/文档**：若项目内有「业务代码逻辑图」或架构说明，本次变更若影响模块/接口/数据流，建议同步更新该图或文档，便于新 Agent 或新人快速了解当前状态。 本 Skill 与 **soul-change-checklist.mdc** 一起用，可系统化减少「只改一端、其它端漏改」的问题。 diff --git a/.cursor/skills/SKILL-角色流程控制.md b/.cursor/skills/SKILL-角色流程控制.md index 7ccdeb13..ef7ac212 100644 --- a/.cursor/skills/SKILL-角色流程控制.md +++ b/.cursor/skills/SKILL-角色流程控制.md @@ -14,7 +14,7 @@ description: Soul 创业派对开发协同流程。小程序开发工程师、 |------|----------|----------|--------------| | **小程序开发工程师** | miniprogram/ | 微信原生小程序 C 端功能，只调 `/api/miniprogram/*` | **SKILL-小程序开发.md**：WXML/WXSS/JS、app.request、scene 编解码、权限与支付约定 | | **管理端开发工程师** | soul-admin/ | React 管理后台，只调 `/api/admin/*`、`/api/db/*` | **SKILL-管理端开发.md**：React + Vite + Tailwind、client.ts、Radix UI、鉴权与列表约定 | -| **后端开发** | soul-api/ | Go + Gin + GORM 接口服务，按使用方挂 miniprogram / admin / db 路由 | **SKILL-API开发.md**、soul-api-coding.mdc：GORM、Gin、路由分组、响应格式 | +| **后端开发** | soul-api/ | Go + Gin + GORM 接口服务，按使用方挂 miniprogram / admin / db 路由 | **SKILL-API开发.md**、soul-api.mdc：GORM、Gin、路由分组、响应格式 | **开发风格约定**：各角色在各自端内开发时，**必须**按上表对应的 Skill 与 boundary 执行，保持代码风格、目录结构、命名与接口约定一致。不得跨路径调用（详见 soul-project-boundary）。 diff --git a/开发文档/列表标准与角色分工.md b/开发文档/列表标准与角色分工.md index bd419bf6..75bc3ddf 100644 --- a/开发文档/列表标准与角色分工.md +++ b/开发文档/列表标准与角色分工.md @@ -70,7 +70,7 @@ **错误**：失败时返回 `{ "success": false, "error": "..." }`，管理端据此展示错误条。 -**参考**：`.cursor/skills/SKILL-API开发.md`、`soul-api-boundary.mdc` +**参考**：`.cursor/skills/SKILL-API开发.md`、`soul-api.mdc` ---