# 杜康好客 · v3.5.6 开发文档

> **2026-08-23** · admin-web / API  
> **主题**：HQ 运营与财务体验增强（任务导出、核销/账单银行信息、工单图片、权限、审核全屏）

---

## 1. 版本目标

1. **开发计划** 任务列表支持导出 Markdown / DOCX / Excel / PDF。
2. **好客权益 · 核销详情** 展示核销门店收款账户（户名/账号/开户行）。
3. **门店账单** 保留「已打款」「已结算」文案，用颜色与类型标签区分；页头说明两类终态含义。
4. **财务四页**（门店/合伙人/酒厂/物流）统一展示收款账户与打款凭证；确认打款可填凭证号。
5. **技术支持 → 开发任务** 审批创建任务时带入工单图片；新建任务支持上传图片。
6. **运营权限** 去掉调试模块（核销调试、小飞侠联调），仅超级管理员可见。
7. **门店审核对比** 支持全屏查看详情。

**不做**：C 端 / 合伙人 / 门店端改动；不升小程序版本号。

---

## 2. 功能清单

### 2.1 开发计划任务导出

| # | 项 | 说明 |
|---|----|------|
| 1 | API | `POST /api/v1/admin/dev-plan/tasks/export` |
| 2 | 范围 | `scope=filter` 按筛选；`scope=selected` 仅勾选 `ids` |
| 3 | 格式 | `markdown` / `docx` / `xlsx` / `pdf` |
| 4 | 列 | 任务编号、类型、状态、内容、关联工单、创建人、创建时间、完成时间、附件 |
| 5 | 权限 | `dev_plan` |

### 2.2 核销详情 · 门店收款账户

| # | 项 | 说明 |
|---|----|------|
| 6 | API | `GET /admin/redeem-records/:id` 增加 `store.primaryAccount` |
| 7 | UI | `RedeemRecordDetailDescriptions` 增加「收款账户」区块 |

### 2.3 门店账单状态区分

| 类型 | 终态 | 颜色 | 含义 |
|------|------|------|------|
| T+1 出账 | 已打款 | 绿 | HQ 确认已对公打款 |
| 手动提现 | 已结算 | 青 | HQ 审核通过并完成结算 |

两类单据终态枚举均为 `PAID`，故文案不同；本版不改文案，仅强化视觉区分。

### 2.4 财务四页 · 银行卡打款信息

| 页 | 收款账户来源 | 打款凭证 |
|----|-------------|----------|
| 门店账单 | 主 `StoreAccount` | `StoreBill.paymentRef`（T+1）；提现沿用 `StoreWithdrawRequest` |
| 合伙人账单 | `PartnerAccount` | `PartnerBill.paymentRef` |
| 酒厂账单 | `WINERY_BANK_*` 系统配置 | `WineryBill.paymentRef` |
| 物流对账 | `FulfillmentProvider` | `LogisticsBill.paymentRef`（挂账模式） |

列表 / 详情 / 导出均展示户名、账号、开户行（及酒厂开户银行）；确认打款弹窗可选填凭证号。

### 2.5 工单 → 任务图片

| # | 项 | 说明 |
|---|----|------|
| 8 | DB | `dev_plan_task.attachment_urls` JSON |
| 9 | 审批创建 | 默认拷贝工单 `attachmentUrls` |
| 10 | 新建任务 | `DevPlanTasksPage` 支持 `OssUpload` |

### 2.6 运营去掉调试模块

| 菜单 | 路由 | 新权限键 |
|------|------|----------|
| 核销调试 | `/redeem/debug` | `benefit_debug` |
| 小飞侠联调 | `/deliveries/xiaofeixia` | `deliveries_debug` |

仅 `SUPER_ADMIN` 默认拥有；调试 API 同步鉴权。

### 2.7 门店审核全屏

`StorePackageAuditsPage` 套餐对比 / 信息变更 Drawer 支持「全屏查看」切换 `width=100%`；全屏时图片放大。

---

## 3. Prisma 迁移

- `store_bill.payment_ref`
- `partner_bill.payment_ref`
- `winery_bill.payment_ref`
- `logistics_bill.payment_ref`
- `dev_plan_task.attachment_urls`

脚本：`prisma/migrate-finance-payment-ref-v356.sql`、`prisma/migrate-dev-plan-attachments-v356.sql`

---

## 4. 发版步骤

| 步骤 | 动作 |
|------|------|
| 1 | `pnpm install`（新增 `docx`） |
| 2 | 执行 Prisma 迁移 |
| 3 | `pnpm build`（API + admin-web） |
| 4 | 发 `dukang-api` + `admin-web` |

---

## 5. 关键路径

| 域 | 路径 |
|----|------|
| 任务导出 | `server/.../dev-plan/admin-dev-plan-export.util.ts` |
| 核销详情 | `admin-redeem.service.ts` + `RedeemRecordDetailDescriptions.tsx` |
| 门店账单 | `StoreBillsPage.tsx` + `settlement.service.ts` |
| 合伙人/酒厂/物流 | `PartnerBillsPage` / `WineryBillsPage` / `LogisticsBillsPage` |
| 工单图片 | `dev-plan.service.ts` + `SupportTicketsPage.tsx` + `DevPlanTasksPage.tsx` |
| 权限 | `hq-permissions.ts` + `AdminLayout.tsx` |
| 审核全屏 | `StorePackageAuditsPage.tsx` + `StorePackageAuditPanel.tsx` |

---

## 6. 验收清单

- [ ] 开发计划：勾选/筛选导出 md/docx/xlsx/pdf，中文正常
- [ ] 核销详情：有主账户时展示户名/账号/开户行
- [ ] 门店账单：T+1「已打款」绿色、提现「已结算」青色；类型 Tag 醒目
- [ ] 财务四页：列表/详情/导出含收款账户；确认打款可填凭证；已打款后可见凭证
- [ ] 工单审批创建任务：图片带入；新建任务可上传图
- [ ] 运营账号无「核销调试」「小飞侠联调」菜单；直链 403
- [ ] 门店审核对比可全屏；图片放大可预览