自定义业务错误码体系设计

任务小笔记/26年/07-13：花掌柜与花卉宝改版/问题.md

@@ -54,3 +54,5 @@
 mallApp 店铺首页如何能点击秒杀商品时，进入到商品详情还是呈现秒杀商品信息
 
 
+#### cursor 支付问题
+hi, cursor 团队，我在使用您的产品时，支付方面碰支付问题。我的帐户是订阅帐户，但在第三支付把自动扣款关闭，因而到期时就没法正常扣款。但最近，我又开始启用此帐户，于是就手动付款，但却碰到支付后显示是非pro 用户，于是进行二次付款才能使用。重置日是今天，但我付款日到现在没30天，且我已经付了两次 60$/月，请帮忙追踪下这个问题。我的帐户是 shishaoqi2011@gmail.com。附件有我的支付凭证。

任务小笔记/26年/07-28：花卉宝错误码设计/错误码设计.md

@@ -0,0 +1,130 @@
+#### 计划需求指令：
+@app-mall/controllers/GroupBuyController.php: 135行的代码，会返回自主定义的错误码，但项目里没有这方面的一个整体规划，请给一套方案设计方案出来。
+
+@app-mall/controllers/GroupBuyController.php: 135行的代码对应的前端页面是 mallApp/src/pages/groupBuy/detail.vue，如果在此页面下，接收到后端返回 6001（或整体设计后的新码），则可以按需求做独自业务处理。
+
+#### AI的计划输出
+---
+name: 自定义业务错误码体系设计
+overview: 为项目建立一套统一的自定义业务错误码（bizCode）规划与命名常量管理机制，并以 GroupBuyController 的 6001 为首个落地案例，同步打通前端 mallApp 识别该业务码的框架。
+
+---
+## 背景
+
+`util::error($code, $msg, $data)`（[common/components/util.php:302](common/components/util.php)）已经存在，但项目里裸用的自定义 code 目前只有两类：`-1`（多处用作"静默业务失败"，前端 resolve 不 toast）和 `6001`（[app-mall/controllers/GroupBuyController.php:135](app-mall/controllers/GroupBuyController.php)，唯一一个"正经"业务码，但是随手定的数字，没有号段规划、没有常量、没有文档）。
+
+前端拦截器 [luch-request_0.0.7/request.js:188-222](front-end/mallApp/src/plugins/luch-request_0.0.7/request.js) 里 `code` 的语义目前是写死的几个分支：`1` 成功、`0` 失败(toast+reject)、`-1` 静默业务失败(resolve)、`2` 登录态失效。其余任何 code（包括 6001）都会落进 `else` 分支：既弹全局 toast 又 reject，页面完全拿不到 `code` 做区分处理。这就是"6001 传到前端后没法单独处理"的根因。
+
+## 方案设计
+
+### 1. Code 分层规则（向后兼容，不改变现有保留码语义）
+
+- `1` 成功、`0` 通用失败(toast)、`2` 登录态失效、`-10` 未登录 —— 维持不变。
+- `-1` 维持作为历史遗留的"静默业务码"（继续兼容 `ProductClass` 限购、`ChatController` 校验失败等已有调用）。
+- **新增约定：`code >= 1000` 均为"业务码"（bizCode）**，前端统一按 `-1` 的方式处理（resolve、不弹全局 toast），交由具体页面 `res.code === xxx` 判断后做专属逻辑。之后任何新业务码只要 `>= 1000`，都不需要再改一次拦截器。
+
+### 2. 业务码号段规划（新建 [common/components/errCode.php](common/components/errCode.php)）
+
+集中管理业务码常量 + 文档注释，按模块预留号段（每段 1000 个号）：
+
+- 1000-1999 通用/公共
+- 2000-2999 用户/客户（登录、绑定、注册）
+- 3000-3999 商品/库存
+- 4000-4999 订单/交易
+- 5000-5999 结算/资金
+- 6000-6999 营销活动（拼团、优惠券、砍价……）—— `6001` 正好落在此区间，**保留原值不变**，只是补上命名和文档
+- 7000-7999 IM/客服
+- 8000-8999 物流/配送
+- 9000-9999 预留
+
+文件里以类常量形式登记每个码的含义、触发场景、对应前端页面，例如：
+
+```php
+class errCode
+{
+    /**
+     * 客户在当前门店暂无绑定关系（hd 表无记录）
+     * 场景：GroupBuyController::actionDetail
+     * 前端：mallApp/src/pages/groupBuy/detail.vue
+     */
+    const GROUP_BUY_HD_NOT_BOUND = 6001;
+}
+```
+
+之后新增业务码的规范：在对应号段追加常量 + 注释，Controller 里用 `util::error(errCode::XXX, $msg)` 代替裸数字。
+
+### 3. 落地 GroupBuyController
+
+[app-mall/controllers/GroupBuyController.php:135](app-mall/controllers/GroupBuyController.php) 引入 `use common\components\errCode;`，把：
+
+```php
+util::error(6001, '客户暂无关联此店');
+```
+
+替换为：
+
+```php
+util::error(errCode::GROUP_BUY_HD_NOT_BOUND, '客户暂无关联此店');
+```
+
+值不变，行为不变，只是消除魔法数字。
+
+### 4. 前端拦截器打通 `>=1000` 静默通道
+
+[request.js](front-end/mallApp/src/plugins/luch-request_0.0.7/request.js) 在 `code == -1` 分支后新增一支：
+
+```js
+} else if (response.data.code && response.data.code >= 1000) {
+    // 自定义业务码（见 common/components/errCode.php 号段规划）
+    // 不弹全局 toast、不 reject，交给页面自行判断 code 处理
+    resolve(response.data)
+}
+```
+
+（仅改动 mallApp 的拦截器；hdApp/ghsApp 若以后有类似诉求，可复用同一套 `>=1000` 约定，但本次不代为修改。）
+
+### 5. 前端新增业务码常量文件
+
+新建 `front-end/mallApp/src/constant/errCode.js`（风格对齐现有 [constant/storageKeys.js](front-end/mallApp/src/constant/storageKeys.js)）：
+
+```js
+/** 与后端 common/components/errCode.php 对应的业务错误码 */
+
+// 拼团：客户在当前门店暂无绑定关系
+export const GROUP_BUY_HD_NOT_BOUND = 6001
+```
+
+### 6. detail.vue 接入识别框架（仅打通框架，不实现具体产品逻辑）
+
+在 [detail.vue](front-end/mallApp/src/pages/groupBuy/detail.vue) `init()` 方法里，`if (this.groupBuyId) { const res = results[0]; ... }` 分支中，在判断 `res.code === 1` 之前插入：
+
+```js
+if (res.code === GROUP_BUY_HD_NOT_BOUND) {
+  this.handleHdNotBound(res)
+  return
+}
+```
+
+新增占位方法：
+
+```js
+/**
+ * 处理"客户暂无关联此店"业务码（GROUP_BUY_HD_NOT_BOUND）
+ * TODO: 具体引导登录/绑定关系的产品交互待定，目前仅做识别与占位
+ */
+handleHdNotBound(res) {
+  this.$msg(res.msg || '客户暂无关联此店')
+}
+```
+
+顶部新增 `import { GROUP_BUY_HD_NOT_BOUND } from '@/constant/errCode'`。
+
+由于第 4 步已让 code>=1000 走 resolve，此前 `.catch(() => { uni.hideLoading() })` 不会再吞掉 6001 这个场景，改为在 `.then()` 里被正确识别。
+
+## 涉及文件一览
+
+- 新建 `common/components/errCode.php`
+- 修改 `app-mall/controllers/GroupBuyController.php`
+- 修改 `front-end/mallApp/src/plugins/luch-request_0.0.7/request.js`
+- 新建 `front-end/mallApp/src/constant/errCode.js`
+- 修改 `front-end/mallApp/src/pages/groupBuy/detail.vue`