85 lines
9.4 KiB
Markdown
85 lines
9.4 KiB
Markdown
# 杜康好客 · V3 编码手册（交付业务版）
|
||
|
||
> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)
|
||
> **佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）· 活动图（v4.0.2）· 周结算与预付款（v4.0.9）· HQ 概览（v4.0.14 / v4.0.15）**：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。
|
||
> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。
|
||
|
||
## 1. 交付目标（六条）
|
||
|
||
C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAdmin 运营 · 后端支付/配送/结算/审计 · 主链路冒烟+边界测试。
|
||
|
||
## 2. 分工
|
||
|
||
| 负责人 | 范围 |
|
||
|--------|------|
|
||
| jacy-dukang | 全部 apps、packages、server 模块、Prisma（2026-07 起代管 B+D） |
|
||
| ~~刘景尧~~ | ~~h5-shop/partner、store/redeem~~（暂停） |
|
||
|
||
**四端**：C=`mini-user`/h5-user · 门店=h5-shop · 合伙人=h5-partner · 总部=**admin-web**（`/admin/*`，`HQ_WEB`）。
|
||
|
||
**边界**：apps 只 HTTP+shared-types；跨模块只 inject exported Service；枚举/DTO→shared-types；纯规则→domain。
|
||
|
||
**日志**：见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)
|
||
|
||
## 3. 核销规则（V3）
|
||
|
||
| 入口 | 入参 | 上限 |
|
||
|------|------|------|
|
||
| 直接核销 | `{ amount }` | ≤ 全部 ACTIVE 权益总余额（FIFO） |
|
||
| 单据核销 | `{ couponId, amount }` | ≤ 该单据可用金额 |
|
||
|
||
- Redis 码 TTL **3 分钟**；确认时二次校验 + 券 version 乐观锁
|
||
- 成功写：`user_redeem_record` · `common_event(BENEFIT_LEDGER)` · `store_payout(PENDING)`
|
||
- 绑定门店则仅该店可确认；`OPEN` 门店；暂停/关闭不可核销
|
||
- UI 无「单次 ¥500」文案
|
||
|
||
## 4. 业务闭环（摘要）
|
||
|
||
| 链路 | 关键节点 |
|
||
|------|----------|
|
||
| C 购酒 | 登录→开城商品→起购(提货2/同城2/跨城6=1箱，城市配置)→支付→权益1:1→出码/核销→评价 |
|
||
| 门店 | 登录→扫码确认→记录→store_payout T+1 |
|
||
| 合伙人 | 拓店三步→HQ审核→辖区订单/账单 |
|
||
| HQ | 开城/商品/审核/订单/权益/核销/结算/工单 |
|
||
|
||
**HQ 权限（v3.5.8）**：生效 =（角色 ∪ 追加）− 撤销。城市范围绑在账号上（空=全国；「城市门店服务」必须勾城）。门店 API 按 `cityIds` 强制过滤。城市门店服务可新增分类、不可删除；概览按权限与城市范围裁剪。
|
||
|
||
**HQ 概览（v4.0.14 / v4.0.15）**：`GET /admin/dashboard/analytics` 支持日/周/月/季/年分桶；默认窗口为上一档起点～今天。全局筛城市+时间；日期快捷上周/上月/上季度；总量/增量单选分开展示。改粒度不改日期。查询右侧可下载当前折线图 PDF（不含 KPI/待办）。v4.0.15 起为多张全宽折线图：总量=桶末日存量，增量=桶内新增；用户线=推广码/关联合伙人/活动，门店线=关联合伙人，订单线=用户/关联合伙人/商品，核销线=门店/关联合伙人，合伙人单线。订单与核销同时出笔数和金额。关联合伙人=`assoc_partner_account_id`；活动=关联合伙人当前活动图。「查看」只带全局城市与日期。无权限模块后端不算不返回。时间按北京日历。
|
||
|
||
**HQ 企微报告（v3.5.15）**：企微机器人下「报告」与「消息推送」分开。日报/周报/月报各配 Webhook 与发送时刻；走群机器人 markdown。账期截在发送日北京 0 点（前一天 24 点），不含发送当天：日报=昨日存量+当日新增；周报/月报=上一自然周/月期末存量+本期新增。用户=有效未合并；合伙人=主账号；订单金额=已付 `payAmount`（`paidAt`）；核销=`RedeemRecord`。
|
||
|
||
**HQ 列表（v3.5.9）**：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）与列宽（拖表头）存 `hq_account.list_column_prefs`。主展示列下划线，点击进编辑或详情。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表昵称只读（点击进详情）；双击「备注」离开即保存（`hq_remark`）；列表手机号不脱敏。
|
||
|
||
**C 端（v3.5.10）**：门店详情无顶栏分享按钮。同城送提示取开城仓库绑定承运商的 `delivery_hint_html`（`GET /catalog/local-deliveries`，按收货市是否开城）；空则回退「同城配送，预计24小时内送到」。在线客服优先 `wx.openCustomerServiceChat`（`CUSTOMER_SERVICE_WECOM_URL` + `WECOM_CORP_ID`）；未配 CorpID 回退小程序原生客服。
|
||
|
||
**起购（v3.5.11）**：现场提货 / 同城 / 跨城阈值在城市 `pickup_min_qty` / `local_min_qty` / `cross_min_qty`（瓶当量）。承运商「起送瓶数」只用于物流计价，不拦下单。
|
||
|
||
**订单大屏（v3.5.12）**：循环 BGM；右上角「播放 BGM」开关（需点击才出声）；成交撒花时压低背景音。HQ 日志 / 订单状态流转 / 用户行为时间线展示中文（存储码不变）。删除门店分类后列表不再自动补种默认树（「同步默认分类」才补）。HQ 侧栏：概览→用户→商品→订单→开城→门店→财务→好客权益→配送单→工单→发票，其余运营/工具项随后，**系统设置最后**。
|
||
|
||
**用户日志端（v3.5.14）**：`order_submit` / `pay_success` 的 `clientApp` 取 JWT（小程序 `USER_MINI`）；微信支付回调沿用该订单已有埋点，缺省小程序。禁止再写死 `USER_H5`。
|
||
|
||
**HQ 门店账单打款凭证**：确认打款 / 提现通过可填 `paymentRef`，并可上传照片（`paymentProofUrls`，OSS `PAYMENT_PROOF`，最多 9 张）。详情与 T+1 导出展示。
|
||
|
||
**活动图（v4.0.2 / v4.0.7）**：规则见 v4-PRD §6。表 `activity_poster`；HQ `GET/POST/PUT/DELETE /admin/activity-posters`（权限 `activity_posters`）；合伙人 `GET /partner/activity-posters` · `GET/PUT /partner/activity-posters/selection`（写入 `partner_account.activity_poster_id`）· `GET /partner/activity-posters/:id/image`（合成本人关联码）。`GET /partner/assoc` 返回 `activityPosterId`（**子账号强制为空**）。码栏百分比相对图宽。子账号可进用户管理、下载纯关联码，无活动图入口。v4.0.7：HQ `GET /admin/activity-posters/:id/image?partnerId=` 单张合成 PNG；`POST /admin/activity-posters/:id/partner-pack` `{ partnerIds }` 流式 zip（仅勾选，测试号/无码 skip）。城市合伙人快链 `/activity-posters?partnerId=`。不预生成缓存图、不批量调微信补码。
|
||
|
||
**合伙人关联与订单佣金（v4.0.1 / v4.0.9）**：规则见 v4-PRD。`user_user.assoc_partner_account_id` 首次扫码锁定；`user_order.partner_account_id_at_pay` 仅关联或代下单显式选择写入（禁止区县解析）。`partner_bill_item` 分酒单 / 核销两段。合伙人备注独立表 `partner_user_note`（勿写 `hq_remark`）。`POST /user/partner-assoc/bind` · `POST /user/partner-assoc/touch`（未登录可计已扫码）· `GET /partner/assoc`（`scanCount` + `userCount`；子账号无 `activityPosterId`）· `GET /partner/assoc/stats`（关联用户 / 当前关联用户已付购酒单，本日/本月）· `GET /partner/assoc/users?keyword&sort`（合伙人侧返回 `partnerRemark`，不返回 `hqRemark`；主账号与子账号均可）· `GET /partner/assoc/users/:userId/orders` · `GET /partner/assoc/orders` · `PUT /partner/assoc/users/:userId/remark` · HQ `GET /admin/users` 支持 `keyword`、`assocPartnerAccountId`（`none` / `any` / 主账号 ID）· `GET /admin/orders` 支持 `assocPartnerAccountId`（筛本单快照，`none`=无快照）· `PUT /admin/users/:id/assoc`（权限 `users_partner_assoc`）改绑/解绑 · 开城合伙人关联用户快链 `/users?assocPartnerAccountId=` · `PUT /admin/partners/:id` 改费率用 `Decimal(toFixed(4))`。子账号创建默认 `ACTIVE`。主账号 `PUT /partner/me/bank` 填收款账户。
|
||
|
||
**合伙人周结算（v4.0.9）**：每周一 08:00 生成上一自然周账单。`GET /partner/settlement/cycle` 账期与出账日；`GET /partner/settlement/preview` 本周一至今预付款预估。零元账单 HQ 可见待审核、不可发送、合伙人端不可见。历史月账不回刷。
|
||
|
||
## 5. 验收用例（必过）
|
||
|
||
**主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30…
|
||
**后台 8 项**：商品/门店/订单/权益/核销/工单/日志/财务。
|
||
**开发计划任务**：状态 `TODO` 待开发 / `IN_PROGRESS` 开发中 / `DEVELOPED` 已开发 / `RELEASED` 已上线 / `STOPPED` 已停止；版本状态含 `STOPPED` 已停止，关联任务随版本同步（仅当全部关联版本已停止时任务才为已停止）。任务列表「来源工单」链到 `/tickets/support?id=`。
|
||
**财务账单日**：出账当天北京日历日（门店/酒厂 `billDate`；物流账期按北京自然月；合伙人周账按北京自然周，周一 08:00 出上周）。禁止 `toISOString().slice(0,10)` 或服务器本地 `Date` 午夜当账单日。酒厂应付为 0 仍出账（展示无需打款）。合伙人零元账单不同步给合伙人端。
|
||
|
||
## 6. 技术债（摘要）
|
||
|
||
P0：旧文档¥500 · lint 占位 · smoke 窄覆盖
|
||
P1：DTO 不全 · 跨模块 prisma · 真实短信/配送
|
||
P2：mini-hq vs admin-web 重叠
|
||
|
||
## 7. 版本与波次
|
||
|
||
规则变更先改 **v3-PRD**。Wave 1/2/3 见 PRD §9。
|