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

> **2026-08-30** · ops / common / store / admin-web / h5-partner  
> **主题**：HQ 活动图模板（底图 + 方形码栏 + 文案）；合伙人下载时合成本人关联码；所选图写入库并作为用户管理主图

需求事实源：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md) §6

---

## 1. 版本目标

| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | HQ 活动图管理 | 需求 | 上传底图、拖拽方形码栏、手填文案、排序、上下架、删除 |
| 2 | 合伙人下载 | 需求 | 主账号列表已上架图；复制文案；服务端把关联码贴进码栏后返回 PNG |
| 3 | 微信保存 | 需求 | 下载失败则预览 + 长按保存（复用关联码下载） |
| 4 | 选择持久化 | 需求 | 单选立即写入 `partner_account.activity_poster_id`；用户管理主图跟选择走，下次登录仍显示 |

**不做**：AI 出图/出文案；子账号码；C 端/门店端；预生成每人缓存图。

---

## 2. 规则

见 v4-PRD §6。码栏百分比相对图宽；合入码 = 主合伙人关联码。列表第一项「无」= 只用关联码。下架/删除后回退为关联码。

---

## 3. 变更面

- 表 [`activity_poster`](../server/dukang-api/prisma/schema.prisma)；SQL [`migrate-activity-poster-v402.sql`](../server/dukang-api/prisma/migrate-activity-poster-v402.sql) · [`migrate-partner-activity-poster-pref-v402.sql`](../server/dukang-api/prisma/migrate-partner-activity-poster-pref-v402.sql)
- `ResourceBizType` 增 `ACTIVITY_POSTER`
- HQ：`/admin/activity-posters` CRUD + 状态；权限 `activity_posters`（超管全量；运营默认含此项，存量 OPS 角色需执行 SQL 或在权限分配中勾选）
- 合伙人：`GET /partner/activity-posters` · `GET/PUT /partner/activity-posters/selection` · `GET /partner/activity-posters/:id/image`
- `partner_account.activity_poster_id` 记所选活动图；`GET /partner/assoc` 返回 `activityPosterId`
- admin-web：`/activity-posters` 列表 + 拖拽码栏编辑器
- h5-partner：中心 / 用户管理入口 → `/center/activity-posters`；用户管理主图按选择展示合成图或关联码

---

## 4. 验收

- HQ 上传后可拖出方形栏并保存；改位置/尺寸后合伙人下载落点一致
- 文案保存后合伙人可一键复制
- 下架图不出现在合伙人列表
- 合成图为本人关联码；无码时明确报错
- 浏览器可下载 PNG；微信内可长按保存
- 子账号无入口
- 合伙人单选活动图后立即写入 `partner_account.activity_poster_id`；用户管理主图跟选择走，重新登录仍显示