dukang/杜康好客-知识库.md

# 杜康好客 · 业务知识库

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

---

## 目录

1. [整体概述](#1-整体概述)
2. [用户小程序端](#2-用户小程序端)
3. [门店端](#3-门店端)
4. [合伙人端](#4-合伙人端)
5. [HQ 总部后台](#5-hq-总部后台)
6. [商品上传与详情模板](#6-商品上传与详情模板)
7. [活动的创建](#7-活动的创建)
8. [开城流程](#8-开城流程)
9. [开店流程](#9-开店流程)
10. [订单处理](#10-订单处理)
11. [财务模块](#11-财务模块)
12. [发票模块](#12-发票模块)
13. [工单模块](#13-工单模块)
14. [配送单](#14-配送单)
15. [好客权益](#15-好客权益)
16. [系统设置](#16-系统设置)
17. [企业微信对接](#17-企业微信对接)（含 [§17.6 运营告警 Webhook](#176-运营告警-webhook群机器人)）

---

## 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 核销操作

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

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

### 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 开店流程](#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`（唯一）、名称、描述、香型  
- 详情长图列表、建议张数  
- 故事标题/正文  
- 卖点列表（图标名、标题、描述）  
- 排序、状态（启用/停用）  

**推荐操作流**：

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

---

## 7. 活动的创建

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

### 7.1 推广码创建

路径：**推广码**。

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

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

### 7.2 活动执行要点

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

权益发放规则活动期仍遵循 **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 同城订单

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

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

### 10.3 跨城订单

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

### 10.4 线下（现场）提货

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

### 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（建议）

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

---

## 12. 发票模块

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

### 12.1 类型组合

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

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

### 12.2 状态

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

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

### 12.3 HQ 处理步骤

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

---

## 13. 工单模块

工单分两类，勿混淆。

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

路径：**工单 → 工单中心**。

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

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

### 13.2 技术支持工单

路径：**工单 → 技术支持**。见 [§5.5](#55-开发技术支持工单协作)。

与售后工单权限分离：`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. 企业微信对接

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

1. **C 端在线客服链接**（用户进人工会话）  
2. **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 并绑定模型，则走语言模型（可带知识库）；否则回复「帮助」文案。暂仅支持 **文本**。

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

#### 启用步骤（运营/研发）

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

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

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

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

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

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

### 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`，再同步本文件与编码手册。