# 杜康好客 · 业务知识库

> **版本**：基于 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-企业微信对接)

---

## 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 瓶）**；总部物流 **到付**；订单佣金归总部 |
| **现场提货** | 隐藏入口（推广码场景）；支付后直接 **已完成** 并发权益 |

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

### 2.3 好客权益与核销

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

### 2.4 门店发现

- 门店列表 / 详情 / 搜索 / 省市区筛选
- C 端仅展示 **营业中（OPEN）** 门店
- 支持「立即核销」跳转出码

### 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/第三方日志 |
| 管理 | 权限分配；系统设置；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 自动推单**（选已注册承运商，首期小飞侠）或 **自管**（手工填运单号 + 查询链接模板） |
| 仓配管理 | 注册第三方履约接口；启用后仓库才可选 |

规则摘要：

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

---

## 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 财务日常 SOP（建议）

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

---

## 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 配送自动完成 | 联调自动推进配送状态 |
| 门店自动审核通过 | 录店免人工审（试点） |

标注「即时」的项保存后写入运行配置即可生效；「需重启」项改完需重启 API。

### 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. 企业微信对接和说明

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

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

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

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

### 17.2 与总部客服角色的协作

1. 用户企微会话说明问题并提供订单号  
2. HQ **客服** 在用户/订单/工单中心建单或处理  
3. 需研发介入时，客服创建 **技术支持工单** 等待超管评审  
4. 退款/补发结果回传用户（短信或会话）  

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

| 能力 | 是否企微 | 配置位置 |
|------|----------|----------|
| 企微微信客服链接 | 是 | 代码常量 / `VITE_CS_WECOM_URL` |
| 服务号 OAuth / 支付 | 否（微信开放平台/商户） | 系统设置 → 微信 |
| 小程序登录支付与首页素材 | 否 | 系统设置 → 微信 / 微信小程序 |
| 微信绑定查询 | 否 | HQ「微信绑定」页（OpenID/UnionID 多端身份） |

### 17.4 运营注意

- 更换客服链接时同步改 shared-types 默认值或各端环境变量并重新发布前端  
- 客服账号权限与会话分配在企业微信管理后台维护，本系统不托管企微通讯录  
- 工作时间话术与 PRD OPT-012 对齐（上线后 3 日内更新）  

---

## 附录 A · 端职责矩阵

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

## 附录 B · 相关文档

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

## 附录 C · 变更说明

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