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

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

需求事实源：[`杜康好客-v4-PRD.md`](./杜康好客-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`
- [ ] 未勾选时导出按钮禁用；不做隐式全量
- [ ] 底图过大被拒绝；打包期间不调用微信补码