Files

T

jacy 205c1110c2 feat(ops): add client error reporting API and frontend hooks

Collect mini-user/shop/partner JS errors via POST /common/client-errors, persist logs, and push fatal/error to WeCom.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-02 16:27:08 +08:00

39 KiB

Raw Blame History

杜康好客 · 业务知识库

版本：基于 V3.0 PRD 与当前四端实现整理
事实源：杜康好客-v3-PRD.md
实现验收：杜康好客-v3编码手册.md
用途：新人上手、运营培训、客服/财务/开发协作说明（非需求变更文档）

1. 整体概述

1.1 产品定位

杜康好客是杜康酒业 O2O 平台，核心链路为：

购酒 → 发放等额好客权益 → 合作餐饮门店核销（酒 + 餐）

商业模型：

环节	说明
总部	供酒、开城、商品、审核、结算打款、售后
城市合伙人	分销拓店、辖区经营、佣金对账
门店	核销好客权益，按核销额 60% 结算
C 端用户	买酒得 1:1 权益，到店核销消费

成本与分润锚点（不可偏离）：

酒水成本约售价 3 折
门店结算 = 核销金额 × 60%
单合伙人「订单佣金 + 核销佣金」≤ 订单金额 5%（默认订单 0% + 核销 3%）
权益：支付成功赠送订单实付 1:1，永久有效
权益额口径：benefit_amount ?? price
核销码 Redis TTL：3 分钟

1.2 四端职责一览

端	形态	主要职责
用户端	微信小程序（联调可用 H5 `h5-user`）	浏览购酒、支付、履约/提货、权益出码、找店核销、售后/发票、客服
门店端	H5（`h5-shop`）	扫码/手机号核销、核销记录、营业状态、子账号、结算提现
合伙人端	H5（`h5-partner`）	拓店三步录入、辖区订单/数据、负责人复核、月账对账、代下单
总部 HQ	WebAdmin（`admin-web`）	开城/商品/门店审核、订单履约、财务打款、发票/工单、权益、系统配置

签约主体：山西领势酒业有限责任公司。

试点城市：郑州。配送：同城小飞侠；跨城总部物流到付。

1.3 五条业务主闭环

购酒履约 ──► 已完成 + 权益 1:1
权益核销 ──► 扣减权益 + 门店账本×60% + 核销佣金
拓店入驻 ──► 审核 + 试核销 ──► 营业中 C 端可见
售后工单 ──► 总部审 + 仓/合伙人协同 ──► 补发/退款
结算提现 ──► T+1 出账 / 未出账可提 ──► 总部审后打款

1.4 技术骨架（便于协作）

API：/api/v1，响应 { code, message, data }
单体 NestJS：server/dukang-api
共享契约：packages/shared-types；纯规则：packages/domain
统一 UI 主色：杜康红 #8B1E1E～#A12828；权益金 #C4A35A

2. 用户小程序端

PRD 交付形态为 微信小程序；仓库中 apps/mini-user 为小程序端，apps/h5-user 为 H5 联调过渡。

2.1 导航与账号

四 Tab：首页 / 订单（或权益相关入口）/ 门店 / 我的（以实际小程序 Tab 为准）
无感登录 + 7 天免登；确认下单可提示绑定手机号（可选、不强制）
仅微信支付；待付款锁单 30 分钟未付自动取消

2.2 购酒与履约

场景	规则摘要
同城	已开城城市；起购 ≥2 瓶；免运费；小飞侠/仓配履约；送达后确认或 24h 自动完成
跨城	未开通城市；起购 ≥1 箱（6 瓶）；总部物流到付；订单佣金归总部
现场提货	隐藏入口（推广码场景）；起购 ≥2 瓶（同同城起购）；支付后直接已完成并发权益

订单列表 Tab（V3）：待付款 | 已付款 | 已完成。

2.3 好客权益与核销

支付成功发放实付金额 1:1 权益，永久有效
「我的 / 好客权益」查看余额与明细
出码核销：码有效期 3 分钟；核销前展示规则弹窗（附件一）
也可到店报手机号由门店发起核销

2.4 门店发现

门店列表 / 详情 / 搜索 / 省市区筛选
C 端仅展示 营业中（OPEN） 门店
营业时间支持 1 段或 2 段（如 09:00-22:00 或 09:00-14:00，17:00-21:00）
入驻可选填 人均费用，用户端门店列表/详情展示
支持「立即核销」跳转出码

门店状态（三态）：

状态	含义	C 端	门店端
OPEN	营业中	可见可核销	可切为临时闭店
PAUSED	临时闭店	不可见	可恢复营业
CLOSED	永久关闭	不可见	不可自行开启；需总部/合伙人处理

2.5 售后、发票与增长

能力	说明
售后工单	四类型：仅退款 / 破损补发 / 破损退货 / 退货退款
发票	个人/企业 × 普票/专票组合申请
客服	电话客服 + 企业微信在线客服（见 §17）
推广码	扫码进小程序归因合伙人/渠道
问卷与评价	成交后问卷（无权益激励）；核销后门店评价

2.6 SKU 价格锚点（酒祖杜康）

商品	瓶价	箱价(6瓶)
国标特级 10 · 53°	¥128	¥768
国标特级 15 · 53°	¥168	¥1008
国标特级 20 · 53°	¥298	¥1788
国标特级 30 · 53°	¥498	¥2988

3. 门店端

App：apps/h5-shop，微信内置浏览器 H5。

3.1 账号模型

角色	权限
主账号	核销、子账号管理、营业状态、提现、本店全量记录
店员子账号	仅核销 + 本店核销记录
一号多店	同一手机号可作多家店主账号；登录时选店；7 天免登记住上次门店

主账号来源：入驻第三步「负责人手机号」，每店仅一个主账号。

3.2 核销操作

首页大按钮进入核销页
扫码通道：扫描用户核销码
手机号通道：输入用户手机号 + 核销金额 → 发短信验证码 → 验证成功后直接核销（同页完成）
核销成功：权益扣减、门店账本记入 核销额 × 60%、短信通知用户
今日汇总可在首页查看

弱网兜底：网络类失败重试；连续失败可拍照提交总部人工补核销（业务错误如码过期、余额不足不计入失败次数）。

3.3 记录、结算与提现

核销记录筛选：今日 / 7 日 / 1 月 / 全部
到账金额展示按 ×60%
T+1 自然日出账（法定节假日顺延）
未出账金额可申请提现（受 FIN 护栏：白名单、单日上限等）
结算异议：核销后 3 个工作日内附凭证提出

3.4 营业状态

门店三态：营业中 / 临时闭店 / 永久关闭。门店端仅可在营业中 ↔ 临时闭店之间切换；总部设为永久关闭后，门店端不可自行开启。仅营业中门店对 C 端可见。

4. 合伙人端

App：apps/h5-partner。

4.1 角色与权限

角色	菜单与能力
管理员	拓店、经营看板、订单/权益/工单、财务对账、子账号、代下单等
推广员	仅门店入驻 + 查看自己提交的店（须在管辖范围内）

数据 平级隔离：全城/区域合伙人不可互查对方数据。手机号中间 4 位脱敏。

4.2 管辖类型

类型	范围	限制
全城合伙人	该城未被区域占用的区县	每城最多 1 名
区域合伙人	总部勾选的区县	每城可多名；同一区县不可重复

4.3 拓店

三步录入 → 负责人复核 → 总部审核 → 试核销 100 元 → 正式入驻（详见 §9 开店流程）。

4.4 经营与财务

首页三卡、排行、订单/权益/工单列表
佣金快照可下钻（支付时落库，比例变更仅影响新单/新核销）
本合伙人 T+30 月账单：独立确认、独立打款（无上下级二次分账）
Wave 3：代下单、管仓只读协同

4.5 佣金归属（摘要）

同城订单佣金：收货区县 → 区域合伙人 → 否则全城合伙人 → 再无归总部
跨城订单佣金：归总部
核销佣金：归核销门店所属合伙人
推广码：主要用于归因统计；现场提货「有码归码」例外

5. HQ 总部后台

App：apps/admin-web。登录：账号密码或短信验证码。菜单按 角色权限 裁剪。

5.1 角色总览

系统内置角色（HQ_ADMIN_ROLES）：

角色	代码	定位
超级管理员	`SUPER_ADMIN`	全权限；权限分配；技术支持工单评审
运营	`OPS`	商品/开城/门店/订单/配送/推广/权益日常运营
财务	`FINANCE`	账单打款、发票、酒厂账户、订单与结算核对
客服	`CUSTOMER_SERVICE`	用户/订单查询、售后工单、发票协助

说明：系统 无独立「开发」角色码。开发相关工作通过 技术支持工单 状态机完成：各角色可提单 → 超管评审 → 进入开发/测试/通过。下文「开发」指该协作职能。

权限可按角色默认值配置，也可按账号叠加个性化权限（权限分配 页，仅超管）。

5.2 运营（OPS）

默认可见模块（摘要）：概览、用户、微信绑定、商品（含详情模板）、订单、推广码、门店、开城（城市/合伙人/仓库/仓配）、好客权益、配送单、工单中心、技术支持、发票、OSS、日志、小程序展示配置等。

日常工作：

事项	菜单入口	要点
开城与仓配	开城 → 城市 / 合伙人 / 仓库 / 仓配管理	见 §8
商品上架	商品 → 商品列表 / 详情模板	见 §6
门店审核	门店 → 门店列表	通过/驳回；试核销协同
订单履约	订单	同城推单、跨城/无仓填单、现场提货单查看
推广与活动	推广码	见 §7
权益运维	好客权益	券/流水/核销记录/待处理核销
配送跟踪	配送单	运单号维护、小飞侠联调
内容资源	OSS 资源库	图片等素材

5.3 财务（FINANCE）

默认可见模块（摘要）：概览、订单、门店、开城、财务三账单、好客权益、技术支持、发票、日志、酒厂银行账户设置。

日常工作：

事项	菜单入口	要点
门店结算打款	财务 → 门店账单	T+1 账期；确认打款 / 批量打款；导出
合伙人佣金	财务 → 合伙人账单	月账确认与打款
酒厂往来	财务 → 酒厂账单	与酒厂账户对照
物流对账	财务 → 物流对账	按承运商月结；充值/挂账
发票开具	发票管理	2 个工作日 SLA；回传 PDF/图片
收款账户	系统设置 → 酒厂银行账户	户名/开户行/账号

5.4 客服（CUSTOMER_SERVICE）

默认可见模块（摘要）：概览、用户、订单、工单中心、技术支持、发票、日志。

日常工作：

事项	说明
查用户/订单	协助定位支付、履约、权益问题
售后工单	受理用户四类型工单；同意/驳回；协同仓与合伙人
发票协助	代查申请状态、催办开票
弱网补核销	处理门店提交的待处理核销单（与运营/权益模块协同）
技术支持提单	将系统缺陷/建议提给超管评审

5.5 开发（技术支持工单协作）

入口：工单 → 技术支持（权限键 tech_support）。

步骤	操作人	状态
创建	运营/财务/客服/超管等有权限账号	`待评审`
评审通过 / 驳回	超级管理员	通过 → `开发`；驳回 → `已驳回`（需填写原因）
开发完成	有权限账号（通常超管/指定开发协作者）	`开发` → `测试`
测试通过	有权限账号	`测试` → `通过`

工单类型：BUG / 建议 / 其他。
用途：产品缺陷、体验建议、技术支持请求的闭环留痕，与 售后工单中心（用户订单售后）相互独立。

5.6 超级管理员

全部业务菜单
权限分配：按角色 / 按账号配置权限目录
HQ 账户：创建与维护总部账号
技术支持工单评审
系统设置 全部分组（功能开关、短信、微信、OSS、部署等）
企微机器人（与系统设置并列；总开关仍在功能开关）

5.7 HQ 菜单地图（速查）

分组	页面
概览	Dashboard
用户 / 微信绑定	用户列表；OpenID/UnionID 多端身份
商品	商品列表；详情模板
订单 / 推广码	全量订单；推广码与归因用户
门店	列表、分类、账户、资源
开城	城市、城市合伙人、仓库、仓配管理
财务	门店账单、合伙人账单、酒厂账单、物流对账
好客权益	权益券、流水、核销记录、待处理核销、核销调试
配送单	列表；小飞侠联调
工单	工单中心；技术支持
发票	发票管理
资源 / 日志	OSS；用户/商户/合伙人/HQ/第三方日志
企微机器人	多实例 Bot 配置（长连接指令助手，可绑语言模型与知识库，见 §17）
语言模型	DeepSeek / OpenAI / 通义 / 自定义 API；非超管仅见自己的配置且只能改是否生效
知识库	上传/粘贴文档，供企微机器人 AI 检索
管理	权限分配；系统设置；HQ 账户

6. 商品上传与详情模板

6.1 商品列表（运营）

路径：商品 → 商品列表。

创建/编辑字段要点：

字段	说明
SKU / 69 码	商品编码与条码
名称 / 副标题 / 香型 / 规格	展示信息
售价 `price`	用户支付价
权益额 `benefitAmount`	默认可与售价一致；规则为 `benefit_amount ?? price`
主图 / 轮播图 / 详情长图	OSS 上传
故事标题与正文、卖点特色	详情页文案结构
是否允许现场提货	`allowOnSitePickup`
状态 / 排序	上架与列表顺序

营销规则：支付成功按实付 1:1 发放好客权益（总部「营销规则」口径，与商品权益额配合）。

6.2 详情模板

路径：商品 → 详情模板。

用途：把「故事 + 卖点 + 详情长图」沉淀为可复用模板，新建/编辑商品时 套用模板，再按 SKU 微调图片与文案。

模板字段：

模板编码 code（唯一）、名称、描述、香型
详情长图列表、建议张数
故事标题/正文
卖点列表（图标名、标题、描述）
排序、状态（启用/停用）

推荐操作流：

先在「详情模板」建好品牌统一长图与话术
商品表单中选择模板一键填充
替换该 SKU 专属主图/轮播后上架

7. 活动的创建

本期「活动」主要落在 推广码 与 现场提货/品鉴 场景，而非独立营销中台。

7.1 推广码创建

路径：推广码。

场景 `scene`	用途
线上链接	H5/小程序落地链接归因
现场提货	线下提货隐藏入口；有码则订单佣金归码所属方
合伙人渠道	合伙人拓客统计
活动品鉴	品鉴会等活动场次
其他	自定义

创建时填写：名称、场景、备注、归属用户（可选）等；系统生成码值、落地 URL、二维码。可查看扫码次数、订单数、转化率、归因用户列表。

7.2 活动执行要点

HQ 创建「活动品鉴」或「现场提货」推广码并下载二维码
现场物料投放；用户扫码进入小程序完成绑定归因
现场提货订单支付后直接完成并发权益
后台在推广码详情核对扫码/成交数据

权益发放规则活动期仍遵循 1:1 实付，不额外叠加激励问卷权益。

8. 开城流程

路径：开城菜单。

8.1 步骤总览

① 新增城市（省市区划 + 启用）
    ↓
② 配置城市合伙人（全城 / 区域 + 佣金比例）
    ↓
③ 配置仓库（可选，一城多仓）
    ↓
④ 仓配管理注册承运商（小飞侠等）并绑定仓库履约方式
    ↓
⑤ 该城 C 端按「同城」规则下单；未开城走「跨城」

8.2 城市

选择省份/城市区划，填写城市名称与编码
状态启用后，用户定位命中该城即走同城履约与起购规则
城市详情可查看门店数、订单数、合伙人绑定、仓库列表

8.3 城市合伙人

在城市下创建或绑定合伙人账号
配置管辖：全城 or 勾选区县（区县互斥）
配置订单佣金比例、核销佣金比例（合计 ≤ 5%）
可管理合伙人子账号（管理员/推广员）

8.4 仓库与仓配

配置	说明
仓库	名称、地址、联系人；管仓方 = 总部直派或关联合伙人（每仓最多 1 名）
履约方式	API 自动推单（选已注册承运商，首期小飞侠）或自管（手工填运单号 + 查询链接模板）
仓配管理	注册第三方履约接口；启用后仓库才可选；配置银行账户/结算/计价
大单拦截	同城 ≥10 箱不自动推小飞侠，订单标「大单待确认」，总部确认推单或自配送

规则摘要：

同城有仓：按仓配置自动推单或自管填单
同城无仓 / 跨城：总部传统快递填单
佣金归属与仓无关；仓用于履约与工单协同

9. 开店流程

对齐《门店签约 SOP》与 PRD 拓店闭环。

9.1 录入主体

合伙人端：三步向导录入（主路径）
HQ 门店列表：总部也可代建/补录（需选择开城合伙人与匹配开城城市）

9.2 三步录入

步骤	内容
1. 基础信息	门头展示名、执照全称；筛选条件参考（面积≥200㎡、客单价≥60、包房≥5 等）
2. 证照与照片	证照/合同/门店照片；附件一结构化规则
3. 结算信息	法人收款或授权书 + 银行卡；短信校验

一号多店：手机号已关联其他店时需确认后继续。

9.3 状态流转

暂存
  → 待负责人复核
  → 待总部审核
  → 审核通过（待试核销）
  → 试核销固定 100 元成功
  → 正式入驻 + 短信通知
  → 营业中（C 端可见）

HQ 可在门店详情 通过 / 驳回（驳回需原因）
系统开关 AUTO_APPROVE_STORE 开启时，合伙人录店可自动审核通过（联调/试点用）
营业状态由门店主账号或 HQ 调整

9.4 HQ 门店相关页

门店列表：审核、营业状态、详情
门店分类 / 门店账户 / 门店资源：分类标签、账号与媒体资源维护

10. 订单处理

路径：订单（HQ）；用户端「我的订单」；合伙人端「订单中心」。

10.1 状态机

待付款 ──支付成功──► 已付款 ──履约完成 / 确认收货 / 24h 自动──► 已完成
   └─ 30 分钟未付 → 取消

支付成功即发放权益；履约完成不重复发券。

10.2 同城订单

用户定位/收货在已开城城市，数量满足 ≥2 瓶
支付成功 → 订单「已付款」
有仓且 API 承运商：系统自动推小飞侠等配送单
有仓自管：管仓方/总部手工填运单号
无仓：总部在订单详情走传统快递填单
送达后用户确认，或超时 24h 自动完成

HQ 订单详情可查看收货地址、仓信息、配送单、权益券与核销分摊、佣金快照等。

10.3 跨城订单

收货城市未开城；数量 ≥1 箱
确认页提示物流到付
支付成功后由总部传统快递填单发货
订单佣金归总部

10.4 线下（现场）提货

用户通过「现场提货」推广码等隐藏入口下单
支付成功 → 订单直接 已完成 + 权益到账
HQ / 合伙人可在订单列表按配送类型或推广码筛选核对
有现场推广码：订单佣金归码所属；无码归总部

10.5 订单详情查阅清单

查阅项	用途
订单号 / 状态 / 金额 / 运费	对账与客服
收货人、省市区、详细地址	履约改址（规则允许时）
定位/IP 辅助信息	风控与同城判断留痕
商品行、权益额	发券核对
配送类型与运单	同城/跨城/现场
关联权益券与核销记录	售后与财务
佣金归属快照	合伙人结算

11. 财务模块

路径：财务。

11.1 门店账单

来源：门店核销 → 结算额 = 核销额 × 60% → T+1 出账形成账期
列表字段：账单号、账期日、核销笔数/金额、结算比例、应打款、状态（未打款/已打款）
操作：查看明细、确认打款、批量打款、导出 Excel
提现申请：门店发起 → 总部审核 → 打至入驻收款账户
试点护栏：未出账提现白名单、单店单日上限（默认 ¥5,000）、工作日 T+0 审完预警

11.2 合伙人账单

订单佣金（支付成功快照）+ 核销佣金（核销时按占比释放）
独立月账、独立确认、独立打款
比例变更只影响新业务，历史账单展示快照

11.3 酒厂账单

总部与酒厂供货/回款往来核对
打款对照 系统设置 → 酒厂银行账户 中的户名、开户行、账号

11.4 物流对账

按快递/仓配承运商（小飞侠等）汇总月度物流费
承运商在 开城 → 仓配管理 配置：银行账户、结算方式（充值扣款 / 挂账月结）、计价标准
小飞侠默认：2 瓶 6 元，加一瓶 +2 元，6 瓶一箱 14 元
前期充值：在「物流对账」汇总页充值；生成月账单时余额充足则自动扣款
后期挂账：月账单确认后打款至承运商银行账户

11.5 财务日常 SOP（建议）

每日核对门店「未打款」账单与核销记录
处理门店提现申请并在账期内标记打款
月结合伙人账单并完成打款确认
月结物流承运商账单（充值余额或挂账打款）
同步发票开具与退款工单对资金影响
异常走技术支持或售后工单留痕

12. 发票模块

路径：发票管理。用户端亦可发起申请。

12.1 类型组合

抬头	票种
个人 `PERSONAL`	增值税普通发票
企业 `ENTERPRISE`	增值税普通发票 / 增值税专用发票

企业专票通常需税号、地址电话、开户行及账号等。

12.2 状态

状态	说明
`PENDING` 待开票	用户或 HQ 已提交
`ISSUED` 已开票	HQ 上传发票文件回传
`REJECTED` 已驳回	信息有误等

SLA：2 个工作日内处理；超时可在列表以逾期标识预警。

12.3 HQ 处理步骤

按状态筛选待开票
打开详情核对订单号、金额、抬头、邮箱/手机
开具后上传 PDF/图片至 OSS，执行「开票回传」
或驳回并备注原因
亦可由客服/财务代用户创建申请（需订单号）

13. 工单模块

工单分两类，勿混淆。

13.1 售后工单中心（用户订单）

路径：工单 → 工单中心。

类型	总部决策	通过后动作
仅退款	同意/驳回	原路退款
破损补发	同意/驳回	负责仓配送+取回；通知管仓合伙人
破损退货	同意/驳回	负责仓取回 → 退款
退货退款	同意/驳回	通知归属合伙人 + 负责仓取回 → 退款

另有系统 ALERT 异常类工单。
用户从已付款及之后订单发起；客服也可在 HQ 代建。处理全程留痕，协同阶段需仓/合伙人确认。

13.2 技术支持工单

路径：工单 → 技术支持。见 §5.5。

与售后工单权限分离：tickets vs tech_support。

14. 配送单

路径：配送单 → 配送单列表（及「小飞侠联调」）。

14.1 列表与查询

可按订单号、承运商 provider、运单号筛选。字段含：订单号、provider、运单号、第三方单号、订单状态、收货人、更新时间。

14.2 处理动作

查看关联订单与收货信息
编辑承运商、运单号、第三方单号（自管仓/传统快递补录）
API 自动推单失败时，人工改状态或重填运单作为兜底
小飞侠联调页：对接调试推单、状态回调、取送拍照等

14.3 与订单的关系

配送单从属于订单履约；同城目标 24h；用户确认收货或超时自动完成后订单进入「已完成」。跨城到付同样在配送单/订单详情维护运单信息。

15. 好客权益

路径：好客权益。

15.1 核心规则

规则	值
发放	支付成功，实付 × 1:1
有效期	永久
直接核销	`0 < amount ≤ 全部 ACTIVE 权益总余额`
带单据核销	`0 < amount ≤ 该单据可用金额`
出码 TTL	3 分钟
试核销	固定 100 元（拓店）

15.2 HQ 子模块

页面	用途
权益券	按券号/用户/状态查询；查看余额、来源订单商品；详情含核销汇总与记录；支持人工发放（运营补偿）
流水	发放/扣减等账本流水审计
核销记录	全门店核销明细；结算额核对
待处理核销	弱网拍照等人工业务单；T+0 补核销
核销调试	联调/排障工具

15.3 处理原则

补发券、作废、补核销必须留备注与操作日志
退款类售后需同步评估是否回收未使用权益（按工单审批结果执行）
门店结算与核销记录交叉核对，避免重复入账

16. 系统设置模块

路径：系统设置。按分组授权（非超管可能只见部分 Tab）。
敏感基础设施（数据库、JWT、端口等）仅存服务器 .env，不在本页维护。

16.1 功能开关

配置项	作用
Mock 短信	不发真实短信；验证码入库可查
Mock 支付	关闭且商户参数齐全时走真实 JSAPI
Mock 微信授权	关闭且 AppID/Secret 齐全时走真实微信
Mock 配送自动完成	联调自动推进配送状态
门店自动审核通过	录店免人工审（试点）
启用企微机器人长连接	总开关；开启后连接 HQ「企微机器人」中已启用实例（见 §17）

标注「即时」的项保存后写入运行配置即可生效；「需重启」项改完需重启 API。
企微 Bot 的 BotID/Secret 不在系统设置里配置，改在独立菜单 企微机器人。

16.2 短信

签名、默认模板、核销确认模板、代下单模板
阿里云 AccessKey（密钥类需重启）
Mock 开启时可在页内查看最近验证码列表

16.3 微信

服务号 AppID/Secret
小程序 AppID/Secret
商户号、证书序列号、商户私钥、APIv3 密钥、平台证书
支付回调 URL

用于登录授权、JSAPI/小程序支付、回调验签。

16.4 微信小程序展示

首页轮播图（建议 15:8，最多 8 张）
首页底部图（建议 15:4）
上传后需点击保存。

16.5 对象存储 OSS

AccessKey、Bucket、Region、Endpoint、CDN 域名、上传前缀、凭证有效期、单文件大小上限等。商品图、发票文件、门店证照均依赖此配置。

16.6 应用链接

C 端 H5 落地页（推广码二维码链接前缀）
腾讯位置服务 Key（逆地理/热力图等）

16.7 发布部署

Webhook URL / Secret，供发版流水线回调（与 @dukang-release 发布流程配合）。

16.8 酒厂银行账户

户名、开户银行、支行、账号——财务打款对照。

16.9 相关管理页

页面	说明
权限分配	角色默认权限 + 账号额外权限
HQ 账户	创建总部登录账号并指定角色
日志	用户/商户/合伙人/HQ 操作日志、第三方调用日志

17. 企业微信对接

本节区分两套能力，勿混用：

C 端在线客服链接（用户进人工会话）
HQ 企微智能机器人（内部同事用指令操作业务；命令式，不依赖大语言模型）

17.1 在线客服（微信客服 / 企微客服）

C 端「联系客服 → 在线客服」跳转企业微信 微信客服 链接，在微信内打开后进入原生客服会话。

项	说明
默认链接	配置于 `packages/shared-types` 的 `CUSTOMER_SERVICE_WECOM_URL`
前端覆盖	H5 可用环境变量 `VITE_CS_WECOM_URL`
电话兜底	`CUSTOMER_SERVICE_PHONE`（如 400 热线）
使用限制	须在微信内打开；需用户点击手势触发

小程序端优先使用小程序客服能力；非微信环境提示拨打电话。

17.2 HQ 企微机器人（智能机器人长连接）

入口：HQ → 企微机器人（权限键 wecom_bots）。
技术通道：企业微信「智能机器人」长连接 SDK；产品名带「智能」，本系统实现为 关键词/指令路由，不必接入 AI 语言模型即可生效。

配置字段

字段	说明
名称	会话内展示用名称
角色	客服 / 技术支持 / 团队助手 / 自定义（决定默认权限）
BotID / Secret	企微管理后台创建智能机器人后下发；每实例一对
头像	OSS 上传（可选）
欢迎语	进入会话时推送（可选）
权限	可勾选能力；创建时按角色带出默认值，可改
启用 AI 问答	未匹配指令时调用绑定的语言模型
语言模型	选自 HQ「语言模型」中已生效配置（非超管仅能选自己创建的）
知识库	选自 HQ「知识库」；检索片段注入模型上下文
启用	关闭则不建立长连接

保存后可用页内 重载连接，或依赖总开关变更后的自动重载。每个已启用 Bot 同时仅保持 1 条 长连接。

语言模型与知识库（与企微同级菜单）

模块	权限键	规则摘要
语言模型	`llm_configs`	可选 DeepSeek / OpenAI / 通义千问 / 自定义 OpenAI 兼容 API。超级管理员可看改删全部；其他 HQ 只能看到自己创建的配置，创建后仅能改「是否生效」，不能改 Key/模型等，也不能删除
知识库	`knowledge_bases`	粘贴正文或上传 `.txt/.md` 等文本；非超管仅管理自己创建的库

企微侧流程：先建语言模型（并测试）→ 建知识库并上传文档 → 机器人表单开启 AI 并绑定。指令仍优先；仅未匹配时走模型。

总开关

系统设置 → 功能开关 → 启用企微机器人长连接（WECOM_AIBOT_ENABLED）。
总开关关闭时，即使 HQ 里已配置 Bot，也不连企微。

预置角色与默认权限

角色	默认权限	典型用途
客服机器人	创建售后工单；查用户（短信验证）；查快递	客服在企微会话内快速建单、核身份、跟物流
技术支持机器人	创建技术支持工单；查看开发进度	内部提单 BUG/建议、查工单状态
团队助手	查询使用手册	按关键词答运营/协作常识（摘自知识库摘要）
自定义	无（自行勾选）	组合权限

权限目录：ticket.create · user.view_sms · delivery.view · support_ticket.create · support_ticket.progress · handbook.query。

常用指令（会话内发文本）

通用：帮助 · 状态

权限	指令示例
售后工单	`工单 <订单号> <类型> [备注]`（类型：仅退款 / 破损补发 / 破损退货 / 退货退款）
查用户	`查用户 <手机号>` → `验证 <验证码>`（验证通过后返回用户摘要）
查快递	`快递 <订单号\|运单号>`
技术支持提单	`提单 <BUG\|建议\|其他> <标题> [
开发进度	`进度`（最近）· `进度 <工单号>`
使用手册	`手册`（目录）· `手册 <关键词>`（如：开城、核销、订单）

未匹配指令时：若已启用 AI 并绑定模型，则走语言模型（可带知识库）；否则回复「帮助」文案。暂仅支持文本。

接语言模型是可选增强，不是长连接生效的前提；纯指令机器人仍可独立使用。

启用步骤（运营/研发）

企业微信管理后台创建「智能机器人」，取得 BotID、Secret
HQ「企微机器人」创建实例，填名称/角色/凭证/权限并启用
系统设置打开 启用企微机器人长连接
在企微中把机器人加到会话，发送 帮助 验证
改配置或凭证后点 重载连接（或重启 API）

说明：不接大模型也能完成指令表能力。开启 AI + 知识库后，可用自然语言问答；写操作（建单等）仍建议走固定指令。

17.3 与总部客服 / 技术支持的协作

人工客服链路（C 端用户）

用户通过在线客服链接进入企微/微信客服会话，说明问题并提供订单号
HQ 客服在用户/订单/工单中心处理，或经 客服机器人 用指令建售后工单
需研发介入时，在 HQ 或经 技术支持机器人 创建技术支持工单，超管评审
退款/补发结果回传用户（短信或会话）

内部同事：优先用对应角色机器人发指令，减少反复进后台翻页；敏感查用户仍须短信验证码。

17.4 微信生态相关（易混淆对照）

能力	是否企微	配置位置
C 端微信客服链接	是（客服入口）	代码常量 / `VITE_CS_WECOM_URL`
HQ 企微智能机器人	是（长连接指令助手）	HQ「企微机器人」+ 功能开关总开关
服务号 OAuth / 支付	否（微信开放平台/商户）	系统设置 → 微信
小程序登录支付与首页素材	否	系统设置 → 微信 / 微信小程序
微信绑定查询	否	HQ「微信绑定」页（OpenID/UnionID 多端身份）

17.5 运营注意

更换 C 端客服链接时同步改 shared-types 默认值或各端环境变量并重新发布前端
企微侧客服账号、机器人可见范围、会话分配在 企业微信管理后台 维护；本系统不托管企微通讯录
Bot Secret 仅 HQ 创建/编辑时写入，列表不回明文；泄露后应在企微后台重置并更新 HQ 配置后重载
工作时间话术与 PRD OPT-012 对齐（上线后 3 日内更新）

17.6 运营告警 Webhook（群机器人）

与 §17.2 智能机器人长连接（会话内指令）不同：本能力用企业微信 群机器人 Webhook 单向推送异常，不依赖 BotID/Secret。

配置项	说明
`WECOM_ALERT_ENABLED`	总开关（HQ 功能开关可改；亦可写 `.env`）
`WECOM_ALERT_WEBHOOK_URL`	群机器人 Webhook 完整 URL，仅服务器 `.env`，勿提交仓库
`WECOM_ALERT_ENV_LABEL`	消息前缀环境名（local / staging / production）

启用步骤：企微群 → 添加群机器人 → 复制 Webhook → 写入服务器环境变量 → 打开 WECOM_ALERT_ENABLED。

类别	典型触发
API	未捕获异常 / HTTP ≥500 / Prisma 已知错误
支付	金额 `<1` 或 `>5000` 元；1 分钟尝试 `>3`；1 分钟失败 `>5`；回调失败；金额不一致
核销	金额 `<1` 或 `>1000` 元；1 分钟尝试 `>3`；1 分钟失败 `>5`；弱网达阈值；新建补核销待办
订单	超时未关待付款；待发货 >24h；配送中 >48h（每 5 分钟扫描）
运维	MySQL/Redis 探活失败；结算 Cron 失败；新建售后/技术支持工单
客户端	`POST /api/v1/common/client-errors`：`fatal`→P0、`error`→P1；`warn` 只记日志/落库不推群

客户端报错上报

项	说明
接口	`POST /api/v1/common/client-errors`（可匿名；带 JWT 时附带用户身份）
Body	`level`（fatal/error/warn）、`category`（js_error / unhandled_rejection / api_error / network / render / bridge / other）、`message`、可选 `stack` / `pagePath` / `clientApp` / `extra`
日志	Nest `Logger` 打 `[client_error]`；并写入 `log_user_analytics`（`event_name=client_error`）
企微	仅 `fatal`/`error`；同指纹 10 分钟去重
前端	mini-user、`h5-shop`、`h5-partner` 启动时 `installClientErrorReporting()`：全局 `error` / `unhandledrejection`（mini-user 另挂 Taro 钩子）

告警经 Redis 去重（同指纹默认 10 分钟内不重复推）；只通知、不拦截交易与核销。Webhook key 泄露时在企微后台重置机器人并更新 .env。

附录 A · 端职责矩阵

能力	用户端	门店端	合伙人端	总部端
下单/支付/权益	●		代下单	代下单
核销	出码	●	看记录	看全量
拓店	看门店	改营业	●录入	●审核
工单	●发起	查看	查看	●决策
结算提现		●	对账确认	●审打款
推广码/问卷/评价	●	被评价	看数据	配置/看板

附录 B · 相关文档

文档	用途
`杜康好客-v3-PRD.md`	唯一需求事实源
`杜康好客-v3-现状对照.md`	已完成 / 缺口审计
`杜康好客-v3编码手册.md`	实现与验收
`杜康好客-v3-城市仓库与日志架构.md`	开城/仓/日志技术说明
`AGENTS.md` / `conventions.md`	工程协作与模块边界
`pages/ROUTE_MAP.md`	原型屏与路由对照

附录 C · 变更说明

本知识库用于培训与协作，不替代 PRD。若业务规则变更，须先改 杜康好客-v3-PRD.md，再同步本文件与编码手册。

39 KiB Raw Blame History Unescape Escape

杜康好客 · 业务知识库

目录

1. 整体概述

1.1 产品定位

1.2 四端职责一览

1.3 五条业务主闭环

1.4 技术骨架（便于协作）

2. 用户小程序端

2.1 导航与账号

2.2 购酒与履约

2.3 好客权益与核销

2.4 门店发现

2.5 售后、发票与增长

2.6 SKU 价格锚点（酒祖杜康）

3. 门店端

3.1 账号模型

3.2 核销操作

3.3 记录、结算与提现

3.4 营业状态

4. 合伙人端

4.1 角色与权限

4.2 管辖类型

4.3 拓店

4.4 经营与财务

4.5 佣金归属（摘要）

5. HQ 总部后台

5.1 角色总览

5.2 运营（OPS）

5.3 财务（FINANCE）

5.4 客服（CUSTOMER_SERVICE）

5.5 开发（技术支持工单协作）

5.6 超级管理员

5.7 HQ 菜单地图（速查）

6. 商品上传与详情模板

6.1 商品列表（运营）

6.2 详情模板

7. 活动的创建

7.1 推广码创建

7.2 活动执行要点

8. 开城流程

8.1 步骤总览

8.2 城市

8.3 城市合伙人

8.4 仓库与仓配

9. 开店流程

9.1 录入主体

9.2 三步录入

9.3 状态流转

9.4 HQ 门店相关页

10. 订单处理

10.1 状态机

10.2 同城订单

10.3 跨城订单

10.4 线下（现场）提货

10.5 订单详情查阅清单

11. 财务模块

11.1 门店账单

11.2 合伙人账单

11.3 酒厂账单

11.4 物流对账

11.5 财务日常 SOP（建议）

12. 发票模块

12.1 类型组合

12.2 状态

12.3 HQ 处理步骤

13. 工单模块

13.1 售后工单中心（用户订单）

13.2 技术支持工单

14. 配送单

14.1 列表与查询

14.2 处理动作

14.3 与订单的关系

15. 好客权益

15.1 核心规则

15.2 HQ 子模块

15.3 处理原则

16. 系统设置模块

16.1 功能开关

16.2 短信

39 KiB

Raw Blame History