dukang/docs/杜康好客-v4.0.7-开发文档.md

杜康好客 · v4.0.7 开发文档

2026-09-01 · ops / store / admin-web
主题：HQ 城市合伙人页活动图快链；指定一张活动图为单个或勾选的主合伙人合成关联码并下载（单张 PNG / zip）

需求事实源：杜康好客-v4-PRD.md §6

---

1. 版本目标

#	任务	类型	交付
1	快链	需求	城市合伙人列表/详情/顶栏跳转活动图页（?partnerId=）
2	单个下载	需求	行操作、详情抽屉、活动图页「为该合伙人下载」；弹窗选已上架活动图 → PNG
3	勾选导出	需求	列表勾选主合伙人 → 选活动图 → zip（仅已勾选，非隐式全量）

不做：预生成每人缓存图；批量调微信补码；按每人当前所选活动图分别出图；BullMQ 异步包。

---

2. 规则

• 合入码 = 主合伙人已有 OSS 关联码。无码则单张报错、zip 写入 _skipped.txt。不在本路径调用 getwxacodeunlimit。
• HQ 指定 一张 已上架活动图，贴进所有目标合伙人。
• zip 仅含请求体 partnerIds；测试号（isTest）跳过。
• 底图最长边 ≤ 2500 且宽×高 ≤ 4e6，超限报错。
• Sharp 合成并发 1；底图只下载一次；zip 流式写出。

---

3. 变更面

• HQ：GET /admin/activity-posters/:id/image?partnerId= · POST /admin/activity-posters/:id/partner-pack { partnerIds }；权限 activity_posters
• admin-web：城市合伙人快链 / 勾选导出 / 弹窗选图；活动图页 ?partnerId= 上下文下载
• nginx：partner-pack 路径 proxy_buffering off + proxy_read_timeout 120s
• archiver 依赖

无 Prisma 迁移。

---

4. 验收

• 城市合伙人「活动图」列、详情、顶栏快链进入活动图页；带 partnerId 时可「为该合伙人下载」
• 行内/详情「下载活动图」弹窗选已上架图，得到该人合成 PNG；无关联码明确报错
• 勾选 N 人导出 zip，文件名含城市/公司或姓名/id；缺码与测试号进 _skipped.txt
• 未勾选时导出按钮禁用；不做隐式全量
• 底图过大被拒绝；打包期间不调用微信补码