shizhongqi/huahuibao_document @ 864bd387b34354e329b6bf70e04e4599cde9559c

计划需求指令：

@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）已经存在，但项目里裸用的自定义 code 目前只有两类：-1（多处用作"静默业务失败"，前端 resolve 不 toast）和 6001（app-mall/controllers/GroupBuyController.php:135，唯一一个"正经"业务码，但是随手定的数字，没有号段规划、没有常量、没有文档）。

前端拦截器 luch-request_0.0.7/request.js:188-222 里 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）

集中管理业务码常量 + 文档注释，按模块预留号段（每段 1000 个号）：

1000-1999 通用/公共
2000-2999 用户/客户（登录、绑定、注册）
3000-3999 商品/库存
4000-4999 订单/交易
5000-5999 结算/资金
6000-6999 营销活动（拼团、优惠券、砍价……）—— 6001 正好落在此区间，保留原值不变，只是补上命名和文档
7000-7999 IM/客服
8000-8999 物流/配送
9000-9999 预留

文件里以类常量形式登记每个码的含义、触发场景、对应前端页面，例如：

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 引入 use common\components\errCode;，把：

util::error(6001, '客户暂无关联此店');

替换为：

util::error(errCode::GROUP_BUY_HD_NOT_BOUND, '客户暂无关联此店');

值不变，行为不变，只是消除魔法数字。

4. 前端拦截器打通 `>=1000` 静默通道

request.js 在 code == -1 分支后新增一支：

} 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）：

/** 与后端 common/components/errCode.php 对应的业务错误码 */

// 拼团：客户在当前门店暂无绑定关系
export const GROUP_BUY_HD_NOT_BOUND = 6001

6. detail.vue 接入识别框架（仅打通框架，不实现具体产品逻辑）

在 detail.vue init() 方法里，if (this.groupBuyId) { const res = results[0]; ... } 分支中，在判断 res.code === 1 之前插入：

if (res.code === GROUP_BUY_HD_NOT_BOUND) {
  this.handleHdNotBound(res)
  return
}

新增占位方法：

/**
 * 处理"客户暂无关联此店"业务码（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

错误码设计.md 5.9 KB History Raw