4.9 KiB
4.9 KiB
杜康好客 · v3.5.6 开发文档
2026-08-23 · admin-web / API
主题：HQ 运营与财务体验增强（任务导出、核销/账单银行信息、工单图片、权限、审核全屏）
1. 版本目标
- 开发计划 任务列表支持导出 Markdown / DOCX / Excel / PDF。
- 好客权益 · 核销详情 展示核销门店收款账户（户名/账号/开户行）。
- 门店账单 保留「已打款」「已结算」文案，用颜色与类型标签区分；页头说明两类终态含义。
- 财务四页（门店/合伙人/酒厂/物流）统一展示收款账户与打款凭证；确认打款可填凭证号。
- 技术支持 → 开发任务 审批创建任务时带入工单图片；新建任务支持上传图片。
- 运营权限 去掉调试模块（核销调试、小飞侠联调），仅超级管理员可见。
- 门店审核对比 支持全屏查看详情。
不做：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_refpartner_bill.payment_refwinery_bill.payment_reflogistics_bill.payment_refdev_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
- 门店审核对比可全屏；图片放大可预览