diff --git a/杜康好客-知识库.md b/杜康好客-知识库.md new file mode 100644 index 0000000..165594f --- /dev/null +++ b/杜康好客-知识库.md @@ -0,0 +1,815 @@ +# 杜康好客 · 业务知识库 + +> **版本**：基于 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`，再同步本文件与编码手册。