dukang/.workbuddy/memory/2026-08-12.md

2026-08-12 工作记录

杜康好客 · 三项功能需求落地（dev_jacy 分支）

需求1：管理端用户列表增加好客权益金额列

• 后端 server/dukang-api/src/modules/ops/admin-users.service.ts：
  • 新增常量 BENEFIT_STAT_STATUSES = ['ACTIVE','USED_UP']、UserBenefitStat 类型、EMPTY_BENEFIT_STAT、toAmount()。
  • list() / detail() 均调用新增私有方法 loadBenefitStats(userIds)，用 benefitCoupon.groupBy({ by:['userId'], where:{status:{in:[...BENEFIT_STAT_STATUSES]}}, _sum:{totalAmount,usedAmount,balance} }) 批量聚合，避免 N+1。
  • mapAdminUserRow 增加 benefit 参数并展开到返回对象。统计口径与 C 端 listCoupons 一致（排除 VOID）。
• 前端 apps/admin-web/src/lib/api.ts：AdminUserRow 增加 benefitTotalAmount?/benefitUsedAmount?/benefitBalance?: number。
• 前端 apps/admin-web/src/pages/UsersPage.tsx：新增「剩余权益/已用权益/累计权益」三列（右对齐、可排序，scroll x 改为 1830），详情抽屉 Descriptions 增加「好客权益」项。

需求2：管理端门店入驻合同支持多图上传

• 新建共享工具 server/dukang-api/src/common/store-media/contract-urls.util.ts：MAX_CONTRACT_FILES=20、normalizeContractUrls(urls?, legacy?)、contractMediaType(url)（.pdf→FILE 否则 IMAGE）。
• 后端 admin-stores.service.ts：import 上述工具；create（645 行）/ update（451 行）路径由单条 contractUrl 改为遍历建立多条 bizType:'CONTRACT' 记录（sortOrder:i、mediaType 按扩展名判定）。
• DTO admin-mutate.dto.ts：contractUrl?:string 标记 @deprecated，新增 contractUrls?:string[]（@IsArray @IsString({each:true}) @ArrayMaxSize(20)）。
• 前端 apps/admin-web/src/lib/storeCreate.ts：StoreCreateForm.contractUrl?:string → contractUrls?:string[]。
• MultiImageUpload.tsx：新增 isPdf()、FilePdfOutlined、PDF 缩略图卡片、buttonText prop。
• StoresPage.tsx：编辑抽屉 + 创建 step1 表单均改用 MultiImageUpload（name=contractUrls, maxCount=20, accept=image/*,.pdf, buttonText="批量上传合同"），回显/保存 payload 改为 contractUrls:string[]。

需求3：合伙人 H5 门店入驻合同支持多图上传

发布流水线（同一会话，22:45 后）

完整跑通 dukang-release 标准流程：dev_jacy → push → merge dev → merge main → 发生产。

• 提交 8805335 feat(ops,store,partner): 用户权益列 + 门店合同多图上传（13 文件，356+/59-）
• dev_jacy push → origin/dev_jacy(8805335)
• merge dev_jacy→dev → 491f03e，push origin/dev
• merge dev→main → 4a0e184，push origin/main
• deploy/deploy-prod.sh -- --skip-db（无 Prisma schema 变更，故 --skip-db）→ DEPLOY_EXIT=0，==> 发版完成 (production)
• 生产 PM2 全 online：dukang-api(8090) / admin-web / h5-partner / h5-shop / h5-user；健康检查 api:200 mini-user(h5):200；版本记录 commit=4a0e184

踩坑/注意

• git checkout main 时本机工作树出现 server/dukang-api 大量 D（误删）假象：实为 sandbox 下 checkout 未刷新工作树，非仓库损坏。用 git checkout -f main 重新填充即恢复；origin/main 始终正确（ls-remote 核对 4a0e184）。
• 提交/合并后 git status 报 "ahead of origin by N" 为本地 tracking ref 陈旧，非真实分歧（ls-remote 已核对远程三分支均含本次提交）。
• 仅提交 13 个需求文件 + 新建 server/dukang-api/src/common/store-media/，已排除 .workbuddy/ 与 fix_acl.ps1。
• 发布命令在 sandbox 下直接运行 SSH 部署成功（未强制禁用沙箱）。
• apps/h5-partner/src/lib/storeDraft.ts：StoreDraftForm.contractUrl:string → contractUrls:string[]；defaultStoreForm 改为 contractUrls:[]；新增 MAX_CONTRACT_COUNT=20；normalizeStoreDraftForm 新增 contractUrls 计算（兼容旧 contractUrl 迁移为数组，去重限 20）；validateStoreStep2 参数/校验改为 contractUrls，不足 1 张返回「请上传签约合同」。
• MultiOssUploadField.tsx：新增 accept?、unit? props，isPdf()，PDF 缩略图卡片。
• StoreCreatePage.tsx：签约合同区块 OssUploadField → MultiOssUploadField（value=form.contractUrls ?? [], maxCount=MAX_CONTRACT_COUNT, unit="个", accept="image/*,.pdf"）；提交体 contractUrl → contractUrls，新增 const contractUrls = Array.from(new Set(...)).slice(0, MAX_CONTRACT_COUNT)；envPhotoUrls slice 上限由 3 改为 20。修正了渲染块误用未定义变量 contractUrls（已改为从 form 读取）。

验证

• 后端 npx tsc --noEmit（server/dukang-api）通过，exit 0。
• admin-web / h5-partner 使用 git stash 基线对比法：本次改动未引入任何新类型错误（现存错误均为预存在基线问题：css module 声明、import.meta.env、过期 config 类型、TabLayout end、staff staffRole 等）。
• 向后兼容：旧 contractUrl 字段保留并标记 deprecated，H5 草稿旧数据自动迁移；避免破坏现有 API 客户端。