dukang/docs/杜康好客-v3编码手册.md

杜康好客 · V3 编码手册（交付业务版）

事实源：杜康好客-v3-PRD.md · 审计：杜康好客-v3-现状对照.md
佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）· 活动图（v4.0.2）· 周结算与预付款（v4.0.9）· HQ 概览（v4.0.14 / v4.0.15）：杜康好客-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

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。

企微 API 插件（v3.5.17 / MCP v3.5.18）：实例在 HQ「企微机器人 → API 插件」维护；共用 Header X-Api-Key。REST GET /api/v1/wecom/plugin/* 与 MCP POST /api/v1/wecom/plugin/mcp（Streamable HTTP 无状态）并存；MCP 按权限自动 tools/list。经营指标含新增门店（newStores）；门店搜索含经营数据；支持门店/信息/套餐审核对照只读查询；支持按合伙人查关联用户/门店/订单（from/to 时间筛选）。

HQ 列表（v3.5.9）：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）与列宽（拖表头）存 hq_account.list_column_prefs。主展示列下划线，点击进编辑或详情。门店列表「累计核销好客权益」= 该店 RedeemRecord.amount 合计。用户列表昵称只读（点击进详情）；双击「备注」离开即保存（hq_remark）；列表手机号不脱敏。

HQ 门店账号子账号：GET /admin/store-accounts/:id 详情含 staff；POST /admin/store-accounts/:id/staff · PUT /admin/store-accounts/:id/staff/:staffId · DELETE /admin/store-accounts/:id/staff/:staffId。仅主账号可挂子账号（不可多级）；storeIds 必须是主账号已绑定门店；创建默认 ACTIVE、角色默认收银员、权限默认核销+记录；改登录手机解绑微信。门店端自管仍走 GET/POST/PUT/DELETE /shop/staff。

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 侧栏：概览→用户→商品→订单→开城→门店→财务→好客权益→配送单→工单→发票，其余运营/工具项随后，系统设置最后。C 端门店「核销N次」由系统设置功能开关 SHOW_STORE_REDEEM_COUNT 控制（默认开）。

用户日志端（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 填收款账户。HQ GET /admin/partners/:id/assoc/qrcode 下载裸关联码 PNG（与「下载活动图」合成海报分开）。

合伙人周结算（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。