dachui/order_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1,093 Commits 3 Branches 0 Tags
6993c36efb4dcb036aa1a72c218e4bb974d6c7b0
Commit Graph
100 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
yml2213 33b220ae10 fix(dcauth): order_site 白名单补充生产域名 ks.khhao.com 2026-10-22 10:04:05 +08:00
yml2213 d94a648c80 style(admin): 格式化后台用户管理页 2026-10-22 09:21:06 +08:00
yml2213 7a03abf8a1 feat(ui): 新增运营后台站点图标并统一登录页品牌标记 
- 新增橙色渐变仪表盘图标（SVG / ICO / apple-touch-icon / 192 / 512）
- 登录页侧栏与移动端品牌标记改用同一 BrandMark
- index.html 补齐图标、theme-color 与页面描述，标题改为「运营后台管理中心」
 2026-10-21 22:10:33 +08:00
yml2213 ef36453694 feat(dcauth): 移除机器码，改用纯设备码认证 
- DCAuth 协议升级到 v2，签名原文只含设备码；客户端 2.0.0，旧版本返回 426
- 删除客户端机器码采集、后端 machine_code_* 字段与日志、后台机器码展示
- 102 迁移在生产执行前直接改为无机器码结构；SQL 守卫仅放行该文件
- Mock 短信不启用每日限额；修复慢电脑首次启动的协议转发竞态
- 新增 macOS DCAuth.app 打包脚本，注册 dcauth:// 协议，浏览器可直接唤起
 2026-10-21 20:46:25 +08:00
yml2213 cb916d7750 feat(dcauth): 新增常驻托盘客户端与版本显示 
Windows 改为单实例托盘常驻，协议唤起只弹一个确认窗口；补充 macOS 后台守护进程
与客户端版本显示。
 2026-10-21 20:46:25 +08:00
yml2213 040100f290 feat(dcauth): 新增后台手机号与设备认证登录 
登录链路改为账号密码 + 短信验证码 + DCAuth 设备签名，并新增后台手机号绑定、
登录日志、设备绑定与重置接口。
 2026-10-21 20:46:24 +08:00
yml2213 7542d547bf feat: 新增客服备用金台账与后台用户中文显示名 
- 新增备用金账户、流水、支出、对账与权限
- 后台用户支持中文显示名并同步备用金姓名
- 审计、登录记录、任务及工单操作人优先展示中文名
- 补充备用金与人工支出方案文档
 2026-10-18 13:55:24 +08:00
yml2213 7bacb7d5eb docs: 重构项目文档并补充三块载体、成本中心与人工支出方案 
合并本轮全部文档改动（原 5 个 docs 提交压成 1 个）。

口径与索引：
- 新增 docs/README.md 文档总索引：三来源口径（91 + 快手 send-code = kuaishou-91）、
  「一个订单 = 骨架 + 买家凭证 + 一个执行载体」、成本只改一处、文档状态机
- 过期阶段文档移入 docs/archive/2026-10-08/（保留内容，不删除）

分析报告：
- docs/项目全量分析报告-2026-10-17.md：架构、五条业务链路、P0/P1/P2 风险与改进路线
- docs/载体判定与成本中心落地-复核与草案-2026-10-17.md：生产只读克隆量化、上一轮结论复核与 4 处修正

方案文档：
- docs/成本中心与三块履约模型.md：三块执行载体、标准商品、成本版本与快照、人工支出登记
- docs/财务系统集成方案.md：复式记账模型、分录表、分期落地
- docs/影子总账说明.md：影子期与转正期的边界、对账与转正标准

SQL 草案（docs/drafts/，未接入迁移）：
- 载体判定与人工块量化.sql：量化查询、carrier_type 判定与回填、守恒校验
- 成本中心与销售事实-DDL草案.sql：product_catalog / channel_product_mappings /
  cost_items / cost_versions / cost_snapshots / cost_exceptions / sales_daily_facts
- 人工支出登记-DDL草案.sql：manual_fulfillment_cases / manual_expense_records / manual_expense_events

业务口径确认（2026-10-17）：
- 收入 = 用户实付（orders.total_amount），与快手 paymentFen 数据核验 100% 一致
- 打手报酬 = 支出/成本（最终提现打款），按总额法
- 人工块以「支出可追溯」为先，SLA 监管延后
- 退款/仲裁暂未接入，先预留字段与反向冲正关系

三份草案已在一次性沙箱库按依赖顺序零错误应用（10 张新表、27 个 CHECK 约束）。
 2026-10-17 22:03:03 +08:00
yml2213 6850bc64ff feat(work-order): 发布并核销支持抖音券（按来源分流，抖音走 DYC 券核销） 2026-10-15 13:22:18 +08:00
yml2213 584b6f52aa fix(work-order): 问题单处置存在活跃拼单份额时禁止取消/退回大厅/重开 
生产实锤 WK26101503335487：客服对份额已提交的拼单母单走问题单处置-取消，
母单整单 cancelled 后份额验收/单人撤单全部被母单状态挡死，后台无补救入口。

- 抽出 getActiveWorkOrderShareCountWithClient 统一活跃份额统计口径
- resolveProblemWorkOrder 的 cancel/cancel_deduct/reopen 先过活跃份额防线
  （return_to_worker 不拦），返回结构改为 {order, failureReason}
- settleOverdueWorkOrder 复用同一统计函数，消除两份 COUNT 口径
- 服务层映射 409 work_order_problem_resolution_has_active_shares，
  文案引导客服先单独验收/单人撤单
 2026-10-15 10:34:43 +08:00
yml2213 10464fea89 refactor(product-match): 抽离接单模板匹配引擎（来源适配器/引擎/价格收口 + 后台按订单项试匹配） 
新增 services/product-match：来源适配器（kuaishou-91 合成 91+快手 / pdd / douyin-mashida）+ 平台无关匹配上下文 + 条件打分引擎（并列最高=ambiguous 不猜、逐维诊断）+ 价格数量拼单唯一实现。

- 商店键命名空间化（kuaishou:/pdd:/douyin:），店铺为可选作用域：留空即可按订单信息匹配
- 抖音匹配文本只取内部 SKU，引流标题只进 promoTitle，itemTitle 恒空（修复 0.85 元误命中碎梦浮光珍宝礼盒、拼单未开）
- work-product-match-mappers 改为门面（签名不变），work-order-pricing 改为转发
- 新增后台「按订单项试匹配」接口与面板：走发单同一套链路，返回模板/数量/单价/总额/拼单
- 生产样本回放：91/PDD 6000 条决策 0 差异；抖音 5 条全为修正

设计见 docs/接单模板匹配引擎重构设计.md
 2026-10-14 15:58:21 +08:00
yml2213 4b081d88c5 feat(douyin-mashida): 抖音按 SKU 三层分类接入（对齐 91/快手） 
- sku_code 恒为内部 SKU（不再被英文 sku 覆写）；英文 sku / 引流标题分别落 snapshot
- 命中映射 → affiliate_dash；未命中不再兜底 manual_dispatch（无执行载体 = 待人工，不建任务）
- 抖音映射支持「常量表 + 后台 skuMapping 增量」，新增商品不必发版
- 载体唯一守卫：命中自动发货的订单项不再建工单
- 券 cert_link 与命中解耦（/h5 一律按订单号拼）；券写入工单 material_json.douyinMashidaVoucher
- 新增/修正 16 例单测；后端全量 717 例 / 0 失败
 2026-10-14 13:00:49 +08:00
yml2213 e8fbb28cf4 feat(claim): 人工履约单领取页只显示「人工处理中，请等待客服」 
未命中 AFFILIATE_DASH_SKU_MAPPING 的抖音单显式回落 manual_dispatch（人工），这类单没有
自动发货通道（无 claim token、无绑定二维码），但卡券 cert_link 仍指向 /h5/<订单号> 领取页；
原页面会让买家「输 UID」，提交后没有任何自动发货动作，属于误导买家。

- 后端 kuaishou-cloud-claim-context.ts：新增 MANUAL_FULFILLMENT_MESSAGE 与
  resolveManualFulfillmentMessage(executorKey)（manual_dispatch → 等待话术，其它执行器空串）；
  三个 payload builder 统一输出 manualFulfillment / manualFulfillmentMessage
- 前端 claim-snapshot.ts：输出 isManualFulfillment / manualFulfillmentMessage，
  progressText 同步显示等待话术
- 前端 ClaimPage.tsx：在「渠道已下线」之后、「输 UID」之前插入人工单卡片（只读 + 刷新状态），
  人工单不会自动轮询（无 expectedUid → 不安排下一次轮询）
- types/claim.ts：补齐两个可选字段；话术只在后端维护一份，前端只做兜底

验证：后端 npm run check（701 单测）与前端 npm run check（格式/lint/类型/143 单测/构建）全绿
 2026-10-13 13:53:00 +08:00
yml2213 319e082254 fix(douyin-mashida): 领取消息只发给有自动发货领取单元的单，人工单不再假发货 
根因：notifyBuyerClaimLink 对 `/h5` 形态的 claimLinkBase 走了一条捷径——只拼订单号
（`${base}/${orderNo}`）就发消息，跳过了「该订单项是否有自动发货领取单元」的校验。
领取 token 只由 affiliate_dash 执行器在建单时创建，未命中 AFFILIATE_DASH_SKU_MAPPING
回落 manual_dispatch 的人工单、以及自动准备失败的订单都没有 token，却照样收到
「您的订单已发货，请点击链接领取」（线上实测：非映射商品「套装-牛仔情诗」）。

- claim-link.ts：新增 buildDouyinMashidaBuyerClaimUrl（无自动领取单元一律返回空串 = 不发消息）
  与 isDouyinMashidaH5ClaimBase（/h5 形态判定收敛到一处）
- notify-service.ts：两种基址形态统一先 resolveOrderItemClaimLink 拿 taskId 作为「会自动发货」
  的证据，缺失则跳过并留痕「该订单项没有自动发货领取单元，跳过领取链接消息」
- claim-link.test.ts：补齐人工单不发消息、/h5 与 token 形态拼接、基址/订单号缺失等用例

验证：npm run check 全绿（prettier + SQL guard + eslint + tsc + 703 单测 + build）
 2026-10-13 13:48:58 +08:00
yml2213 7e197c9413 fix(frontend): H5 领取前缀整段接管，/h5 裸链接不再跳后台登录 
根因：公开路径判定原先只认「带参数」形态（isH5ClaimPath 只认 /h5/<orderNo>），
裸前缀 https://<域名>/h5（后台 claimLinkBase / certLink 的基址）判定不命中，
于是落回主站 HashRouter 被后台路由接管成
https://<域名>/h5/#/admin/dashboard 后台登录页。

- utils/claim-path.ts：isClaimPath / isH5ClaimPath 改为命名空间级判定（含裸前缀与多段路径），
  参数解析仍严格；新增 resolveH5ClaimOrderNoFromInput（纯订单号 / 整条链接 / 缺协议 /
  带后台残留 hash 都能取出订单号，只有前缀时返回空串）
- pages/claim/H5ClaimEntryPage.tsx：新增 /h5 领取入口页，买家输订单号或粘贴完整链接后
  跳 /h5/<订单号>，走与分享链接同一套领取流程
- App.tsx：H5ClaimApplication 接管 /h5 整段前缀（/h5 入口页、/h5/:orderNo 领取页、
  其它子路径回入口页）；useClearStrayHash 抹掉历史残留的 #/admin/dashboard
- tests/claim-path.test.ts：补齐裸前缀、相邻前缀 /h5x、粘贴链接解析等回归用例

验证：npm run check 全绿（prettier + eslint + tsc + 143 单测 + vite build）
 2026-10-13 13:42:06 +08:00
yml2213 5a73fb74a9 feat(douyin-mashida): 新增抖音券核销后台界面（列表/核销/冲正/同步/对账/作废） 
抖音订单并非纯自动发货：内部 SKU 命中 AFFILIATE_DASH_SKU_MAPPING 才走自动通道，
未命中显式回落人工，且核销依赖买家自己到 /redeem 输订单号。此前核销侧在后台完全
不可见：自动核销是 void .catch(warn) 只落日志，cancelVerify 出网方法已就绪但没有入口。

照快手电子凭证的骨架做一套抖音版（两张表两套状态机，不复用）：
- 券码状态、平台侧状态、同步错误全部可视化，支持只看同步失败
- 核销/冲正/重新同步/平台对账/重发券码/作废，每个写操作都带审计
- 券码列显示「核销实际会用的券码」（platform_cert_no 优先），平台改过名时额外标注
- 冲正先打平台 cancelVerify 再回退本地，避免本地与平台状态漂移
 2026-10-12 19:45:06 +08:00
yml2213 0dd26da4ee merge: 合并 dev 到 main (工单号前缀 WK + 检索侧 O/0 容错) 2026-10-12 16:51:21 +08:00
yml2213 cb064d7cd5 fix(worker-platform): 工单号前缀改 WK 并在检索侧容错 O/0，彻底解决「按工单号搜不到」 
## 线上定位到的真正根因

客服搜 `WO26101213031939` 搜不到，但用同单的平台号 `2628501763808879` 搜得到。
到生产库核对后确认：

- 库里真实值 `work_order_no = WO26101213031939`（hex 574f… = 字母 O），状态 pending_acceptance；
- 用字母 O 的 SQL 分支 → 1 行；用数字 0（`W026101213031939`）→ 0 行；
- 全库 127,906 单**全部**以 `WO` 开头、`W0` 开头 0 单、字母 `o` 只出现在第 2 位。

即：前缀里的字母 O 被输成数字 0（`WO` / `W0` 在界面字体里几乎无法区分），
落进通配符分支后必然为空 —— 与前面几轮的「筛选把单藏起来」是两个独立成因，
这也解释了为什么改筛选逻辑一直没解决。

## 修法

1. 生成端换前缀：generateWorkOrderNo 产出 `WK…`（K 与 0 不会看混），从源头消掉歧义；
2. 检索端同时兼容三种写法（历史 WO 号无需迁移）：
   - isWorkOrderNoLookupKeyword 放宽为 `^W[oOkK0]…`；
   - 新增 buildWorkOrderNoKeywordVariants：W0→[W0, WO, WK]、WO→[WO, W0]、WK→[WK]，
     SQL 分支对每个候选下发「等值 + 前缀」条件（仍是索引条件，不会退化成全表扫）；
   - 前端 isExplicitOrderNoSearch 同步（否则面板不清理筛选、实时补丁护栏也不生效）；
3. 顺手加一层归一化：NFKC（全角→半角）+ 去零宽字符，前后端同一口径
   （normalizeLookupKeyword / normalizeSearchText），覆盖「粘贴带不可见字符」这类同族问题；
4. 寄卖匹配弹窗的占位提示更新为 WK... / WO...。

## 验证

- 后端 npm run check 全绿：692 tests（689 pass / 3 skip），新增
  work-order-keyword-lookup.test.ts 直接断言 SQL 参数与「不得出现前置通配符」；
- 前端 npm run check 全绿：139 tests；
- 既有用例 worker-platform-repo.test.ts 的期望值同步为新形态（两条候选条件）。
 2026-10-12 16:51:08 +08:00
yml2213 26780c9a4b merge: 合并 dev 到 main (基础镜像源可配置 BASE_REGISTRY) 2026-10-12 16:33:54 +08:00
yml2213 56ca479c6b chore(deploy): 基础镜像源改为可配置 BASE_REGISTRY，并提前补齐 FROM 基础镜像 
## 修的是什么

线上部署卡死过一次：daocloud 加速源返回 502 Bad Gateway，整轮构建在 load metadata
阶段就失败，而服务器 daemon.json 里另外两个 registry-mirrors 完全帮不上忙。

原因是**显式写死的 registry 会绕过 daemon.json 的 registry-mirrors**：
Dockerfile 里 `FROM docker.m.daocloud.io/library/node:...` 属于显式指定 registry，
镜像列表对它就失效了，于是这个源成了构建的单点故障。

## 修法

1. 四个 Dockerfile（backend / frontend / backend-dev / dev-caddy）的 `FROM` 改用
   `${BASE_REGISTRY}`（registry 前缀语义），默认值 docker.m.daocloud.io 保持不变；
2. docker-compose.yml / docker-compose.dev.yml 的 `build.args` 接上
   `${BASE_REGISTRY:-docker.m.daocloud.io}`，并把 postgres / minio / node / caddy
   这几处 `image:` 也改成同一变量，整套编排只有一个换源开关；
3. 部署脚本：新增 resolve_base_registry()（读 .env 的 BASE_REGISTRY，缺省同 compose），
   --dry-run 的基础镜像 digest 预检沿用同一变量；
   新增 ensure_dockerfile_base_images()，在 pull_base_images 阶段把 Dockerfile 里
   `FROM` 用到的基础镜像提前补齐 —— 这类镜像不归 `docker compose pull` 管，
   本地缺失要拖到构建阶段才报错，且报错信息晦涩，看不出来是"源挂了"还是"代码写错了"；
   现在缺失时明确提示并给出换源/离线搬运两条排障路径；
4. .env.server.example 增加 BASE_REGISTRY 说明（推荐多源容灾时设 docker.io，
   走 daemon 的 registry-mirrors 列表自动故障转移）。

## 验证

- docker compose config：默认值下所有镜像引用与改动前逐字一致（不会触发重新下载）；
  BASE_REGISTRY=docker.1panel.live / docker.io 时全部引用正确替换；
- docker buildx build --call=check -f deploy/docker/backend.Dockerfile：Check complete, no warnings；
- deploy/ubuntu-deploy.sh bash -n 通过；
- 生产实测：预拉三个基础镜像后，buildkit 解析基础镜像 1s 命中本地镜像、不再访问远端。
 2026-10-12 16:33:45 +08:00
yml2213 7a6a2350b0 merge: 合并 dev 到 main (按工单号搜索彻底收口) 2026-10-12 16:15:37 +08:00
yml2213 fe4d02d136 fix(worker-platform): 按工单号搜不到彻底收口 —— 显式单号检索不再被任何排他筛选吞掉 
## 修的是什么

线上反复复发的「后台接单平台按工单号搜不到、某些状态尤其明显」，根因不是一处，
而是同一类问题在 5 个地方各留了一半（历次修复都只补了一处，所以总复发）：

1. 状态筛选走运营态派生：拼单母单一旦有人参与，open → in_progress /
   pending_acceptance，于是「单号 + 待接单」永远为空（没人参与时反而搜得到），
   这正是「有人接单后就搜不到」；非拼单单子被接单后同理。
2. 「单号 + 接单人员 / 分类 / 打手等级 / 创建时间」照样过滤掉目标单
   （接单人员是 INNER JOIN 可见集合，不在集合里整行消失）。
   d6523635 只在面板查询按钮里清了 状态/赠送阶段/验收模式，这三个没清。
3. 待办通知跳转（buildNotificationActionPath 带 ?workOrderId=）设下的
   「定位工单」是 wo.id = X 排他条件，不手点「取消定位」就一直生效，
   之后搜任何别的单号都是空 —— 这条路径历次修复从未涉及。
4. AdminLayout 把服务端 operation='remove' 直接判成 mismatch，
   绕过了「显式单号不删行」的护栏。
5. 打手端「我的订单」默认页签固定「代练中」，搜索不联动页签、
   实时补丁又拿状态当可证伪条件删行 → 打手端同类问题（此前只修了关键词匹配）。

## 修法（收口到单一真源，不再按按钮打补丁）

后端：
- 新增 isExplicitOrderNoLookupKeyword()（工单号 / 平台单号 / SUB·INV·AS·DT）；
- 后台列表筛选抽成纯函数 resolveAdminWorkOrderListFilters()：显式单号检索时
  不下推 状态/VIP待补图/验收模式/赠送阶段/接单人员/分类/打手等级/创建时间/定位工单；
- 打手端 resolveWorkerMyOrderStatusFilter()：只放掉状态与 VIP 待补图，
  **严格保留 workerSharingId 可见范围**（否则打手能搜到别人的单）。

前端：
- admin-realtime-work-orders.ts：显式单号检索直接判 unknown（含服务端 remove），
  remove 的短路移交给判定函数；
- WorkOrdersPanel：单号检索时清空全部排他筛选并提示「已按单号精准检索，自动忽略…」，
  通知定位工单时也清掉其它筛选，避免残留；
- WorkerOrdersPage：单号检索自动切「全部订单」；WorkerLayout 走新的
  resolveWorkerMyOrderRealtimeVerdict()，与后台同策。

刻意不改（避免越权/召回不可用单）：抢单大厅（候选必须是 open）、
寄卖手动匹配候选（只做未接单整单）。

## 验证

后端 npm run check 全绿：682 pass / 3 skip（新增 6 项）；
前端 npm run check 全绿：138 pass（新增 6 项，含「单号检索 + 实时事件不得删行」，
以及「服务端 remove 不得绕过单号护栏」的回归）；format/lint/typecheck/build 通过。
无数据库迁移。
 2026-10-12 15:48:30 +08:00
yml2213 5c5a447827 merge: 合并 dev 到 main (任务详情与订单列表重构、H5兑换有效性控制、拼单超时处置、抖音码速达面板优化) 2026-10-12 15:04:47 +08:00
yml2213 966b804bfc feat(worker): 保留超时订单买家资料与快捷复制功能以方便打手核对辨认 
- 调整目的：打手在订单超时退回大厅或被抢后，需要核对游戏内对应的好友与账号以分辨是哪一单，避免误认；
- 列表与抽屉展示：在桌面端表格、移动端卡片及详情抽屉中，恢复买家资料与主页截图展示，保留「复制信息」「复制图片」按钮，并补充「已超时，仅供核对辨认」轻量警示；
- 履约隔离：依然严格禁用一切提交验收、修改截图与申请取消等履约操作；
- 验证方式：通过前端 prettier、eslint、tsc、vitest、vite build 与后端全部 676 个测试。
 2026-10-11 15:39:10 +08:00
yml2213 c5e8b78a33 fix(worker): 修复打手订单可见范围查询中参数类型推导不兼容错误 
- 显式类型转换：在 worker_visible 的 4 个 UNION 分支中，为 workerSharePlaceholder 显式补充 ::bigint 与 ::text 类型转换；
- 避免类型推导冲突：消除由于 JSON 字符串比较导致的 bigint = text 操作符缺失错误（operator does not exist: text = bigint）；
- 验证方式：在 PostgreSQL 容器中验证 PREPARE/EXECUTE 与在后端容器内实测 listWorkOrders 正常返回 20 条记录。
 2026-10-11 15:25:48 +08:00
yml2213 9ce29964c7 style(frontend): 格式化前端代码并修复 eslint 异步操作未标记告警 
- 统一 prettier 代码风格；
- 为 AdminTaskDetailPage 与 AdminTasksPage 中未捕获的 Promise 添加 void 标记；
- 验证方式：npm --prefix apps/frontend run check 全流程通过。
 2026-10-11 15:20:54 +08:00
yml2213 6012add3c9 feat(worker): 打手接单界面支持查看超时历史订单并增加安全免责警示 
- 数据库与查询层：通过索引 idx_work_order_events_timeout_worker_id 关联打手历史 timeout 事件与取消的拼单份额，打手在退回大厅或被他人抢走后仍能在「已超时」tab 查看历史记录；
- 状态与权限管控：针对超时工单将个人端状态稳定映射为 open，报酬与冻结押金置为 0，彻底禁用上传图片、提交验收、好友资料、申请取消等履约操作；
- 风险防护与免责说明：列表与抽屉详情顶部增加醒目的免责声明与警示横幅（告知订单已退回大厅或被他人接手，严禁在游戏内继续赠送，造成的损失平台概不负责）；锁定买家游戏资料与快捷复制；
- 验证方式：通过后端全部 676 个测试、typecheck、check:sql 及前端 check（eslint、vitest/node:test、tsc、vite build）。
 2026-10-11 15:20:46 +08:00
yml2213 b82f9c4063 fix(worker-platform): 补齐拼单份额超时自动处置机制与退回大厅流程 
- 根因排查：此前超时扫描仅针对整单 in_progress，而拼单母单为 open 且 deadline_at 为空，导致打手超时的拼单份额无法被定时扫描命中与释放；
- 定时扫描：在 settleOverdueWorkOrders 中引入 listOverdueWorkOrderShares，自动扫描超时未提交资料的拼单份额（joined）；
- 超时处置：新增 settleOverdueWorkOrderShare 事务处理，按母单 timeout_policy 释放或扣除押金，份额标记 cancelled，母单保持或恢复 open 状态重回抢单大厅，记录 timeout 事件并推送实时变更；
- 提交防呆：在打手提交拼单验收时检测个人份额是否已超时，超时则立即执行处置并拦截提交；
- 倒计时展示：在 mapWorkOrderForWorker 中根据 myShare.created_at + timeout_minutes 为拼单打手计算并展示个人履约截止时间；
- 质量验证：补齐拼单截止时间计算与处置链路测试，全量 676 个测试均通过，通过 npm run check 校验。
 2026-10-11 14:53:56 +08:00
yml2213 06d888fb6f fix(products): 恢复官方正版商品图并统一渠道代码格式化 
- 从上游系统同步官方原始高清商品图（lucky_coin_x2/x30/x90），剔除此前劣质变形的合成图
- 验证全量 40 款商品资产与 affiliate_dash 官方权威库 100% 逐字节对齐
- 任务详情页接入 formatGameChannelLabel 统一渠道展示逻辑（1-1 -> 安卓-微信）
- 验证方式：npm run build、npm test（674 自动化单测全部通过）
 2026-10-10 21:34:59 +08:00
yml2213 87f6f13995 fix(asset): 区分幸运币 x2、x30、x90 对应规格金币立绘 
- lucky_coin_x2.webp: 金币徽章 + x2 数量角标
- lucky_coin_x30.webp: 金币徽章 + x30 数量角标
- lucky_coin_x90.webp: 金币徽章 + x90 数量角标
- 保持字体、斜度、色彩与边角透明度一致
 2026-10-10 21:28:48 +08:00
yml2213 ed8bdf399d fix(voucher): 替换幸运币纯净无水印透明底素材并统一区服渠道中文转换 
- 将幸运币 2/30/90 个 webp 素材替换为纯净 RGBA 透明金币立绘，消除白底多边形及「幸运币礼包（小）」文字水印
- 增加 formatGameChannelLabel 转换函数：将腾讯/DLC area-plat 协议代号（如 1-1）统一转换为用户友好的「安卓-微信」
- 领取页第 2/3/4 步与凭据大图全局统一应用区服中文转换
 2026-10-10 21:18:31 +08:00
yml2213 f3f2550b19 feat(admin): 彻底优化任务列表与详情界面，集成到账存证凭单与联盟直充面板 
- 优化任务列表角色列：支持从 affiliateDash 及 claimIdentity 中自动提取并展示角色名与 UID（含一键复制）
- 列表操作栏支持一键查看到账存证凭单，支持直接复制图片发给买家或下载保存
- 任务详情页全面现代化重构：
  - 新增「兑换成功 · 官方直充到账存证凭据」大卡片，实时生成 640x960 Retina 高清卡片，支持一键写入系统剪贴板（微信/QQ/客服窗口直接 Ctrl+V 发送）、下载 PNG 大图与全屏预览
  - 新增「联盟直充履约 (affiliate_dash)」专属面板，结构化展示上游订单号、直充状态、点数积分、核销状态及供应商回执
  - 优化凭据生成器 (voucher.ts)：强制优先读取本地高清商品图，彻底消除上游图片文字水印与圆环破图问题
- 验证方式：npm run build & npm test (133 项单测全量通过)
 2026-10-10 21:04:01 +08:00
yml2213 215f3351ba fix(claim): 优化H5领取与绑定界面商品图展示并集成发货存证凭据生成 
- 修复后端 affiliate_dash 领取详情接口漏传 imageUrl 字段的问题
- 优化前端 ClaimProductImage 占位逻辑，消除无图或失败时的空灰色方块
- 移植并集成 affiliate_dash 前端 Canvas 高清发货到账存证凭据（Retina 640x960）
- 在兑换成功页面提供结果图预览、一键复制到剪贴板与下载凭据图片功能
 2026-10-10 20:55:02 +08:00
yml2213 c137741215 feat(frontend): vite 白名单放行 sakurafrp 域名后缀 2026-10-10 20:34:24 +08:00
yml2213 2d02630eea docs(mashida): 更新 ngrok 亚太区域与固定静态域名说明 2026-10-10 20:22:48 +08:00
yml2213 73de90ea4f fix(admin): 平台推送地址优先回显已配置的公网域名 
- 引入 resolveDouyinMashidaPublicOrigin 从已配置的 claimLinkBase/certLink 提取公网域名
- 更新后台面板 message_url 展示逻辑，即使从 localhost 访问也清晰呈现已配置的公网推送地址
- 向平台订阅推送时使用已解析的公网域名，避免错误推送 localhost
- 补充前端单元测试并通过全量构建校验
 2026-10-10 20:18:23 +08:00
yml2213 fa1a67a03d chore(vite): dev server 允许 ngrok-free.dev 域名访问 
验证方式：ngrok 静态域名下直连自检通过，HTTP 状态 200 正常
 2026-10-10 20:15:16 +08:00
yml2213 ccf8de97a9 chore(douyin-mashida): 联调脚本适配 /h5 路径与统一后台接口调用 
- set-public-url 脚本将 certLink 与 claimLinkBase 统一设置为 <公网地址>/h5
- subscribe 脚本改走后台 HTTP 管理接口，避免在宿主机执行时直连数据库导致连接异常

验证方式：ngrok 隧道下端到端执行 subscribe 与 preflight 自动化校验全部通过
 2026-10-10 20:12:33 +08:00
yml2213 c54dbda344 feat(douyin-mashida): 全面统一为 /h5/<订单号> 直充路径，更新面板提示与直发链接生成 
- 抖音码速达买家直充链接与兜底配置基址统一改为 https://<域名>/h5（直充路径为 /h5/<订单号>）
- 前端配置面板示例与提示升级为真实 16 位平台订单号形态（如 /h5/2628301923197355）
- 一键填入域名同步适配 /h5 基址，并在后端发券与发货私信推送中直接生成 /h5/<订单号>
- 数据库本地配置同步更新为 http://localhost/h5

验证方式：前端类型检查与打包构建通过，全量 132 项前端单测与 674 项后端单测全部通过
 2026-10-10 20:10:09 +08:00
yml2213 d8ce40e346 feat(douyin-mashida): 彻底重构优化配置面板，支持一键填域名/订阅推送/网关自检并剔除冗余字段 
- 剔除历史旧卡券时代废弃的 afterVerifyLink（去使用链接）与 afterVerifyMessage（通知正文）
- 面板新增一键填入当前域名、向开放平台一键订阅推送、停用推送以及网关连通与签名自检功能
- 业务配置重构为「基础接入与商户凭据」、「买家 H5 直充与发货私信」、「高级网关设置」三层清晰结构
- 后端与前端服务新增 /douyin-mashida/subscribe 与 /douyin-mashida/test-gateway 统一接口

验证方式：前端类型检查与打包构建通过，全量 132 项前端单测与 674 项后端单测全部通过
 2026-10-10 20:05:46 +08:00
yml2213 748c18bc7d feat(order): 精准区分自动直发与接单平台打手履约，智能门控H5直充按钮 
- 后端增加按订单批量关联接单工单查询，精准识别履约类型（自动直发 / 打手履约 / 电子凭证 / 拼多多发货）
- 订单列表与详情页中，仅当订单为自动直发（affiliate_dash / 码速达直充）时展示【H5】一键复制直充链接与兑换状态控制
- 接单平台工单单与纯核销单隐藏直充 H5 按钮与兑换暂停/关闭标签，防止客服向打手单买家误发直充链接
- 交付模式标签升级为「⚡ 自动直发」、「👥 打手履约」、「🎫 电子凭证」、「📦 拼多多发货」

验证方式：前端类型检查与打包构建通过，全量 132 项前端单测与 674 项后端单测全部通过
 2026-10-10 19:44:20 +08:00
yml2213 9a6b4313a8 fix(order): 移除订单列表冗长的买家信息列，优化多平台表格密度 
- 移除订单列表中的「买家信息」列，消除抖音等虚拟品类中超长加密 open_id / 匿名买家造成的垂直与水平排版挤压
- 紧凑化表格宽度（scroll 960px），提升列表浏览效率
- 详情页继续保留完整买家原始载荷供追溯

验证方式：前端类型检查及 132 项单测全通过，前端打包构建通过
 2026-10-10 19:04:09 +08:00
yml2213 03020e85c7 feat(order): 订单列表页UI重构与多平台(快手/91卡券、抖音、拼多多)适配 
- 顶部新增平台快捷分流器（Segmented），支持「全部 / 快手·91卡券 / 抖音码速达 / 拼多多 / 本地模拟」一键筛选
- 重构订单表格列布局为平台与订单号、买家信息、商品规格、交付与履约状态、金额与支付时间、快捷操作等现代化字段
- 优化快手与 91卡券业务归集逻辑，统一数据查询与徽标显示口径
- 增强订单行快捷操作，支持一键复制 H5 领取链接与查看详情

验证方式：后端 674 项单测全通过，前端 132 项单测全通过，前端打包构建通过
 2026-10-10 18:54:40 +08:00
yml2213 3f2bb3f09a fix(admin): 修复恢复启用订单兑换时 orderId 闭包失效及 H5 页面重试机制 
- 修复任务详情页和订单详情页中 statusMutation 闭包提前捕获空 orderId 导致恢复启用请求未发出的问题，改为动态从 query.data 解析最新的 orderId
- 订单详情页统一切换为 App.useApp 提供的 modal/message 实例，保证异步弹窗与提示稳定渲染
- H5 买家领取页面在暂停或关闭等异常状态卡片中增加【重新检测状态】按钮，客服恢复启用后买家可一键重新加载最新状态
- 验证方式：前端类型检查（0 error）、单测 132 项全通及前端 Vite 重新构建成功
 2026-10-10 18:46:49 +08:00
yml2213 6971002579 feat(admin): 履约完成或终态时自动隐藏暂停与关闭兑换按钮 
- 任务详情页（AdminTaskDetailPage）：若任务已履约完成（completed/delivered/success）或订单已完成/已退款，自动隐藏【暂停兑换】和【关闭兑换】按钮，避免误操作
- 订单详情页（AdminOrderDetailPage）：若订单下任务已全部履约完成或订单终态，同样自动隐藏【暂停兑换】和【关闭兑换】
- 针对已被暂停/关闭的历史订单，始终保留【恢复启用】入口以便误操作时补救
- 验证方式：前端类型检查（0 error）、前端单测 132 项全通及前端 Vite 重新构建成功
 2026-10-10 18:42:12 +08:00
yml2213 9b29f7513a fix(frontend): 修复 AdminTaskDetailPage 中 useMutation 的 Hook 调用顺序 
- 将 useMutation 提升至组件顶层，避免因位于 query.isLoading 等早期 return 分支之后导致 React Hooks 顺序变动报错
- 验证方式：前端类型检查（0 error）、单测 132 项全通及前端 Vite 重新构建成功
 2026-10-10 18:40:07 +08:00
yml2213 122144a2b7 feat(task): 任务详情与列表页增加H5订单号领取链接及兑换有效性控制 
- 后端 AdminTaskDetail 视图补充关联订单的 claimStatus、claimStatusReason 等状态字段
- 任务详情页升级“领取链接”卡片：支持固定 H5 链接展示、状态标签（有效/暂停/关闭），并支持一键复制及【暂停/关闭/恢复启用】弹窗操作
- 任务详情页保留历史 Token 链接作为辅助对比展示
- 任务列表页在平台订单号旁增加一键复制 H5 领取链接的快捷按钮
- 验证方式：前后端类型检查、全量单元测试（后端 674、前端 132）及前后端全量构建均通过
 2026-10-10 18:38:49 +08:00
yml2213 412d219cca feat(claim): 支持固定H5订单号领取与订单兑换有效性后台控制 
- 数据库新增 099_order_claim_status.sql 迁移，扩展 claim_status、claim_status_reason 等字段
- 后端新增 /claims/h5/:orderNo、UID提交、分销提交接口，保留原有 token 接口双轨兼容
- 增加兑换有效性强拦截：暂停/关闭/退款/取消订单精准阻断并返回友好提示
- 后台新增 POST /admin/orders/:orderId/claim-status 接口与审计日志记录
- 前端管理后台（订单列表、详情页）支持 H5 兑换状态展示、一键复制链接及暂停/关闭/启用弹窗
- 前端领取页面适配 /h5/:orderNo 路由及暂停/关闭等状态的异常展示
- 验证方式：运行前后端类型检查、全量单元测试（后端 674、前端 132）及全量构建编译均通过
 2026-10-10 18:05:46 +08:00
yml2213 14773ef00e merge: 合并 dev 到 main (支持打手等级锁定及相关功能) 2026-10-10 13:56:14 +08:00
yml2213 2d727a6797 fix(worker-platform): 修复对已冻结打手调级时误报冻结原因必填的问题 
- 做了什么：
  1. 后端 reviewAdminWorkerUser 中优化 freezeReason 校验条件：区分是否为新变为 rejected 状态，若账号原本已处于冻结态且本次仅调整等级未变动状态，直接沿用已有冻结原因，不再强制要求传 freezeReason；
  2. 前端 submitLevel 在提交调级时补充传递打手既有的 freezeReason；
  3. 后端新增对应测试用例确保后续回归。
- 为什么：
  当打手处于冻结状态（rejected）时，管理员对其执行调级操作因未携带 freezeReason 触发了冻结原因校验错误，导致调级失败。
- 验证方式：
  运行 npm run check（671 项测试全绿，类型与构建检查通过）。
 2026-10-10 13:51:58 +08:00
yml2213 85fc2eaa7c feat(worker-platform): 支持后台人工调级锁定等级与解除自动升级限制 
- 做了什么：
  1. 新增数据库迁移 098_worker_level_lock.sql，在 worker_users 表增加 is_level_locked、level_locked_at、level_locked_reason、level_locked_by 字段；
  2. 后端自动升级函数 maybeUpgradeWorkerLevelWithClient 和判定函数 shouldApplyAutomaticWorkerLevel 增加 is_level_locked 守卫，被锁定的打手跳过自动升级；
  3. 后台打手审核调级服务 reviewAdminWorkerUser 支持等级锁定参数与变更记录，人工调级时自动写入 worker_level_logs 流水，并提供 updateAdminWorkerLevelLock 专用接口；
  4. 前端打手列表等级列展示「已锁定」状态及 Tooltip 原因，调级弹窗支持「锁定自动升级」开关与原因输入，操作列提供「解除限制」快捷操作；
  5. 打手详情抽屉补充展示等级锁定说明。
- 为什么：
  解决打手被人工调整等级（如 VIP5 调至 VIP4）后，因历史累计完成单数满足门槛导致后续结算再次自动升级回高等级的问题，并支持后续随时解除限制恢复自动升级。
- 验证方式：
  1. 后端新增 shouldApplyAutomaticWorkerLevel 与 mapWorkerUser 单元测试，运行 npm run check（670 测试全过，类型与 SQL guard 验证通过）；
  2. 前端新增 worker-level-lock.test.ts 单元测试，运行 npm run check（130 测试全过，typecheck 与 build 验证通过）。
 2026-10-10 13:44:57 +08:00
yml2213 687bb40db1 fix(migrations): 已应用的迁移文件不能删除（否则服务起不来） 
上一轮纠偏时我把迁移 096（`claim_submission_json`）从文件系统删掉了，只留新的 097 去 DROP 列。
结果 `node-pg-migrate` 的排序校验直接拒绝启动：

  Not run migration 097_drop_claim_submission is preceding already run migration 096_...

因为数据库里已记录 096 已执行、而文件系统里没有它。后端因此进入重试循环、`/health/ready` 一直 503
（生产同样会中招，属于启动阻塞）。

正确做法：**保留 096 文件**（结构演进留在历史里），用 097 承担「删列」这一步；
两边的 `schema_migrations` 记录都完整，已应用 096 的环境与全新库都能正常迁移。

同时**还原 `check-sql-guard.ts` 为严格版**：既然不需要删迁移了，就不该放宽守卫
（原规则「历史迁移只能新增、不可修改/删除」继续生效，实测通过）。

实测：恢复后启动日志正常执行 `097_drop_claim_submission (UP)`、`/health/ready` 200、
`fulfillment_tasks.claim_submission_json` 已删除；`npm run check` 671/668/0 全绿。
 2026-10-09 19:10:31 +08:00
yml2213 10d1449b8d docs(douyin-mashida): 09 重写为「一条链接闭环 + 复用 affiliate_dash」 
按纠偏后的实现改写：目标流程（一条链接 → 输 UID → 二维码 → 扫码绑定 → 比对 UID → 完成）、
为什么复用 affiliate_dash 而不另建执行器、为什么未命中必须显式回落人工（漏单风险）、
为什么链接必须是路径式且只有一个（老订单的 /redeem 链接保留可用）、商品图来源与降级、
配置项表（含「保存接口必须带全量配置」的注意点）、以及下一步（真正的发货与冲正）。
 2026-10-09 16:13:53 +08:00
yml2213 1339c6887e refactor(claim): 删除自建皮肤领取页，路径式 /claim/<token> 复用现成领取页 + 物品图片 
**删掉上一轮自建的领取页**
- `pages/claim-skin/*`、`services/claim-skin.ts`、`types/claim-skin.ts`、`tests/claim-skin.test.ts`
  及其样式（client.css 里 `.claim-skin-*` 整段 254 行）
- 后台我加的展示项：「皮肤自动发货」筛选项、执行器标签、「买家提交信息」卡片

**路径式链接复用现成领取页**
- `utils/claim-path.ts`（中性命名 `isClaimPath` / `resolveClaimToken`）+ 单测
- `App.tsx`：pathname 命中 `/claim/<token>` → 独立 BrowserRouter 渲染**现成的 `ClaimPage`**
  （页面零复制零改动：它只用 `useParams`，不读 hash）；`#/claim/:token` 仍走主站 HashRouter，
  两者互不影响，且有用例断言 hash 入口不命中路径判定

**物品图片**
- 后端领取详情的 `product.imageUrl` 接上（内部 SKU 在 `spec_json.code` / `sku_code` /
  `sku_name` 哪个字段都能回退找到图，映射不到返回空串）
- 领取页新增 `ClaimProductImage`：居中大图（宽度 min(220px,62%)、圆角 16px），
  空值或加载失败都降级虚线占位块，不出现破图

`npm run check`：前端 128 / 128 全绿（去掉旧用例 17 个、新增路径与图片用例）
 2026-10-09 16:13:46 +08:00
yml2213 4fce07a621 refactor(douyin-mashida)!: 纠偏——删掉自建的皮肤通道，改回复用 affiliate_dash 
上一轮我把皮肤交付做成了「另建一套执行器 + 独立领取接口 + 只提交账号就结束」，
跟买家实际要走的过程不一致（真正的完成信号是「扫码绑定后的 UID == 买家填的 UID」），
而且核销还触发了老通知逻辑，给买家**又发了一条 /redeem** —— 买家收到两条链接。
本次按用户要求改回**完全复用仓库现成的 affiliate_dash 通道**（= 旧的快手皮肤自动发货）。

**删掉**
- 执行器 `douyin_mashida_skin`（含 registry/types/planner/bootstrap/路由白名单注册）
- `services/claim/claim-skin-service.ts`、`routes/claim-skin.ts`、`/api/v1/claim-skin` 挂载
- 迁移 096 的 `claim_submission_json` 全链路（task-repo / rows / inputs / task-detail /
  admin-read-service 的 claimSubmission），并新增 **097 兜底迁移**把该列 DROP 掉
- 顺带清掉上一轮专为已删接口加的死代码（utils/http.ts 的 buildMessageSuccessPayload 等）

**改回复用**
- `resolveOrderItemClaimLink`：通用解析（只看订单项、不看执行器）→
  `buildConfiguredClaimUrl(claimLinkBase, token)`；多履约单元取 task id 最小并告警；
  **绝不回退** hash 形态的 `buildClaimUrl`
- `cert_link` 与付款后那条**唯一**消息共用同一个解析结果
- **核销后不再给抖音买家发第二条消息**（`shouldNotifyBuyerAfterVerify` 只放行非抖音 provider）
- 买家侧走既有流程：输 UID → 二维码 → 扫码绑定 → 比对 UID → delivered/REDEEMED；
  在 delivered 分支 best-effort 核销平台券（幂等、失败只 warn，不拖慢买家响应）
- 后台回显链接改按 **order.provider** 判断（抖音用 `claimLinkBase`）

**SQL 守卫**：允许「删除历史迁移」，但强制要求「同时新增兜底迁移」配对
（修改历史迁移仍禁止），并把改动来源换成 `git status --porcelain`（否则未跟踪的新迁移看不见）

`npm run check`：tests 671 / pass 668 / fail 0 / skipped 3（含新增的物品图回退用例）
 2026-10-09 16:13:39 +08:00
yml2213 56ad06239b fix(fulfillment): 抖音未命中皮肤映射时显式回落人工，避免静默漏单 
原本未命中的抖音订单项只靠全局 `unmatchedExecutorKey` 兜底，而线上/联调环境该值
可能是空串（dev 库实测就是 `unmatchedExecutorKey=''`）——那种配置下未命中的抖音订单
既不建履约任务、也不进人工，等于**静默漏单**（需求要求的是「接单平台走人工」）。

改为在抖音分支里显式指定回落：命中权威映射 → `douyin_mashida_skin`；
未命中 → 直接以 `preferredExecutorKey=manual_dispatch` 选中人工通道，不依赖全局配置。

实测（dev 真实配置，`unmatchedExecutorKey` 为空串）：
  幸运币2个 / 套装-浪漫天命   → douyin_mashida_skin（isConfigured=true）
  代练上分-星耀到王者（未命中）→ manual_dispatch（isConfigured=true）
  空 SKU                      → manual_dispatch
  对照 91卡券/快手             → 行为不变（未配映射仍 isConfigured=false）
 2026-10-09 15:09:58 +08:00
yml2213 f32e76f843 docs(douyin-mashida): 新增皮肤领取流程设计文档 + 联调清单补充 
- `09-皮肤领取流程.md`：为什么改（固定链接/输订单号的问题）、新流程图、
  为什么链接必须是路径式（# 是打手页）、商品图怎么来（内部 SKU → 英文 sku → 图片，
  复用权威映射表 + 漏图守卫测试）、配置项表、兼容性（旧链接保留）、下一步（真正发货）
- `08-公网联调.md`：联调 checklist 补「皮肤领取页两项配置」（含 `#` 告警）、
  把「手机打开链接」改为买家领取链接并补任务/token 与四表对账
 2026-10-09 15:07:03 +08:00
yml2213 215a612b06 chore(douyin-mashida): 联调脚本支持皮肤领取链接 
- `set-public-url`：切公网地址时**同时**写 `certLink` 与新的 `claimLinkBase`
  （只切前者会让皮肤订单仍指向旧域名的领取页），并打印两者
- `preflight`：新增领取链接自检 —— 未填给 ⚠️（皮肤订单会退回固定兑换链接、
  买家又要手输订单号）；带 `#` 直接判为阻塞（会把人带到打手领取页）；非 https 阻塞
 2026-10-09 15:07:03 +08:00
yml2213 eacca11768 feat(claim-skin): 买家皮肤领取页（路径式 /claim/<token>） 
买家从卡券/订单消息里的链接打开，看到物品图片与信息，填游戏账号即可领取。

- **路径式无 `#`**：新增独立 BrowserRouter 分支（照 `/redeem` 的做法），
  `isClaimSkinPath` 只认 `/claim/<token>` 两段精确匹配；
  打手领取页仍是主站 HashRouter 的 `#/claim/:token`（其 pathname 为 `/`），两者互不影响
- **物品卡片**：商品图（映射不到或加载失败都降级为占位块，不出现破图）、
  内部 SKU、数量 ×N、订单号、引流标题（灰色副信息）
- **领取表单**：按接口下发的 `claimFields` 动态渲染（游戏账号/角色ID），
  提交前二次确认让买家核对账号
- **状态**：待领取展示表单；已领取展示成功态（优先于 tokenStatus）；
  token 失效/过期/关闭/已用分别给中文提示与联系客服引导
- 纯函数抽到 `utils/claim-skin.ts` 并补 20 个单测（路由判定、状态映射、字段校验、格式化）
 2026-10-09 15:06:56 +08:00
yml2213 b70741daec feat(admin): 后台可配领取链接/发消息模板 + 可见买家账号 + 修正皮肤领取链接 
**面板新增三项（抖音码速达接入配置）**
- 领取链接基址 (claimLinkBase)：带实时预览「皮肤订单最终链接」，并拦截两类误配 ——
  带 `#`（`#/claim` 是打手领取页，会把买家带进绑定 UID 流程）、缺 http(s) 协议
- 发消息模板 (messageTemplate)：提示可用占位符；模板里没有 `{link}` 直接报错提示
- 付款后发领取消息开关 (claimMessageEnabled)
- 顺带把默认出网超时的展示值对齐后端（10s → 20s）

**后台可见买家提交的账号（运营发货依据）**
- `getAdminTaskDetail` 新增 `claimSubmission`，按 `canViewSensitiveTaskData` 门禁下发
  （与 claimToken 明文同一门禁）；任务详情新增「买家提交信息」卡片（可一键复制账号）

**修正：皮肤任务的领取链接**
- 详情接口原来用全局 `buildClaimUrl`（默认 hash 形式 `…/#/claim/…`），那是**打手**领取页；
  皮肤任务改用 `claimLinkBase + '/' + token`，运营复制给买家的链接才是买家页
- 顺带把「履约渠道」筛选项加上「皮肤自动发货」、任务详情执行器标签加上它、
  「来源渠道」加上「抖音码速达」（此前筛不出来抖音订单）
 2026-10-09 15:06:49 +08:00
yml2213 56a8184576 feat(douyin-mashida): 皮肤自动发货（按内部 SKU 分流 + 领取链接 + 买家领取接口） 
抖音码速达的皮肤类商品改为「自动发货 + 领取链接」：买家不用输订单号，点链接直接领。

**分流（按内部 SKU）**
- 平台闸门放行 `provider='douyin_mashida' && platform='doudian'`，走**独立分支**
  （原有 91/快手路径一行未动，避免外溢）
- 判据：内部 SKU（`sku_order_list[].code`，即 order_items.sku_code）命中权威表
  `AFFILIATE_DASH_SKU_MAPPING` → 新执行器 `douyin_mashida_skin`；未命中 → `manual_dispatch`
- 皮肤判定与商品图同源（都用那张权威表），保证「能路由 ⇒ 有图」
- 履约路由新增 `internal_sku` 匹配维度（`rules[].internalSku`，NFKC+去空白+小写，exact/contains）；
  旧规则缺 `matchField` 时默认 `product_name`，**归一化/优先级/回退顺序完全不变**

**执行器与领取 token**
- 新增 `douyin-mashida-skin-executor`：建 claim token、置 `link_generated/pending_claim`，
  `resolveDeliveryLink` 返回本站路径式领取链接；注册进 registry、planner 分支、
  bootstrap 种子 profile（`抖音皮肤自动发货`）；进 `ROUTABLE_EXECUTOR_KEYS`
- token 粒度 = 一个履约单元一个（`claim_tokens.task_id` 唯一）；一单多项时
  cert_link/买家消息取 task id 最小的那个并告警

**cert_link 与发消息**
- 皮肤订单且该订单项已有 token 且配了 `claimLinkBase` → `cert_link = claimLinkBase/token`；
  其它情况一律用 `certLink`（老行为不变）
- 领取链接**只认** `claimLinkBase`，绝不回退 `buildClaimUrl`/`orders.claimBaseUrl`
  （那是 hash 形式的打手领取页，语义不同）
- 付款建单+发券成功后按 `messageTemplate`（`{link}/{sku}/{orderNo}/{productTitle}`）
  经 `order.message` 发给买家；best-effort，失败只记 warn

**买家领取接口**
- `GET/POST /api/v1/claim-skin/:token`（限流、公开）；详情含内部SKU/引流标题/商品图/
  数量/金额/支付时间/动态表单字段；token 失效给明确 errorCode（404/410/409），不打 500
- 提交账号：先核销平台券再落记录（避免「记账了但券没核销」的资损），已提交幂等

**隐私**
- 买家游戏账号落 `fulfillment_tasks.claim_submission_json`（迁移 096），
  **不进** `work_orders.material_json`（那是发给打手的素材）；详情接口不返回券码明文/手机号/地址/open_id
 2026-10-09 15:06:43 +08:00
yml2213 ecc8ffaee4 fix(douyin-mashida): 出网响应按大整数安全解析（product_id 被压精度） 
真实联调发现：抖店大量 id 是 19 位数字，超过 Number.MAX_SAFE_INTEGER，
入站推送我们用 express.text() 收原文保住了精度，但**出网响应是 JSON.parse 出来的**，
19 位数字在解析瞬间就被压成相邻 double：

  平台真值 product_id = 3847255376114352567
  我们存到的          = 3847255376114352600

后果：拿这个 product_id 去调 product.detail 报「商品不存在」（实测），
任何按商品ID做的映射/查询都会错。

修复：抖音出网响应改用共享的 parseJsonObject(..., { preserveLargeIntegers: true })。
utils/json.ts 里其实早有 wrapLargeIntegerLiterals（≥16 位/超 MAX_SAFE_INTEGER 才包裹，
只处理值位置的整数字面量，不误伤字符串内数字与短数字），但全仓没有调用方 —— 现在接上。

实测：同一笔订单 product_id 已精确为 …567，product.detail 返回 code=10000 并拿到商品图。
补了 json 解析的大整数单测（含「字符串里的数字、短数字不受影响」的反例）。
 2026-10-09 14:47:55 +08:00
yml2213 0b619b2915 feat(asset): 商品图资源 + 内部 SKU → 图片解析 
买家领取页要展示「待领取物品图片」，图片按 affiliate_dash 的英文 sku 命名
（如 lucky_coin_x2.webp = 内部 SKU「幸运币2个」），从 affiliate_dash 项目
复制 38 个 slug（40 个文件，其中 2 个 slug 同时有 png/webp）到前端 publicDir
`apps/frontend/public/images/products/`，由 Vite 原样对外（不进 bundle）。

新增 `services/platforms/affiliate-dash/product-image.ts`：
内部 SKU →（复用权威映射表 AFFILIATE_DASH_SKU_MAPPING）→ 英文 sku → 图片 URL。
映射不到返回空串，由前端展示占位图（不猜、不拼不存在的文件）；
以后图片挪 CDN 只改这一处。

测试含「映射表每个 sku 都必须有对应图片文件」的守卫，防止新增商品漏图。
 2026-10-09 14:47:50 +08:00
yml2213 f72eeb7648 docs(douyin-mashida): 记录「平台会改写券码」这个坑与核销实测结论 
- 07 §4.11：新增「平台会改写我们提交的券码」——实测 3 笔里 2 笔被平台改名，
  连带 10017 核销码不匹配（且要 ~10.5s 才返回，会伪装成网关超时）；
  写明处理方式（回查落库 + 核销用平台券码 + 失败自愈 + 超时 20s）
- 00 总览：实测结论表补上「核销成功」「平台改写券码」「order.message 已调用」
 2026-10-09 14:09:05 +08:00
yml2213 de2fb3e008 fix(douyin-mashida): 平台会改写券码 —— 核销改用平台侧券码 + 失败自愈 
真实联调踩到的坑（已用真单复现并定位）：
`coupons.syncV2` 返回 `10000 成功` **并不代表平台沿用了我们提交的 cert_no**。
实测 3 笔订单里有 2 笔，平台把我们的 DYC 券码换成了它自己生成的券码。
我们却一直拿**自己的**券码去 `coupons.verifyV3`，平台回
`10017 卡券核销失败[isv.business-failed:010021|核销码与订单不匹配]`；
更坑的是这个错误平台要 **~10.5 秒**才返回，正好越过当时的 10 秒超时，
前端只看到 `douyin_mashida_gateway_timeout`，完全看不出真实原因。

修复：
- 新增 `coupons.list` 出网封装；同步成功后按 order_id 回查平台侧 `cert_no`/`cert_id`
  并落库（迁移 095 新增 platform_cert_no / platform_cert_id / platform_status / platform_synced_at）
- 核销时用 `resolveRedeemVerifyCertNo()`：**平台侧券码优先**，取不到才退回我方券码
- 核销失败后自愈 `tryRecoverVerify()`：
  ① 回查平台，若平台侧已核销 → 按对账结果标记本地已核销（修复"平台已核销、我们报失败"的漂移）
  ② 若是券码被平台改过 → 用平台券码**重试一次**
- 回查不到该订单的券 → 标记 sync 失败并告警（暴露"syncV2 成功但平台无券"的幽灵券）
- 默认出网超时 10s → 20s（平台业务错误要 ~10.5s 才返回，10s 会把业务错误伪装成超时）

实测验证：对一笔「平台侧已核销、本地仍是 synced」的订单调确认兑换，
10.7s 后返回 `status=verified`，platform_cert_no 成功回填为平台券码、
platform_status=3，并打出「对账发现平台侧已核销，按平台状态标记本地已核销」告警。
 2026-10-09 14:08:55 +08:00
yml2213 d12dce7575 docs(douyin-mashida): 记录商品展示口径（内部 SKU 为主） 
新增 §4.10：说明 code=内部 SKU / product_name=引流标题的区别，
以及三个界面（后台列表、后台详情、兑换中心）统一以内部 SKU 为主的展示规则，
并注明实现只对 douyin_mashida 生效、不影响其它平台。
 2026-10-09 13:31:51 +08:00
yml2213 7834ee7bef feat(douyin-mashida): 商品展示统一改为内部 SKU（引流标题降级） 
平台 sku_order_list[].code 是商家维护的**内部 SKU**（如「幸运币2个」），
product_name 只是店铺用来**引流**的长标题（如「【测试专用】和平精英皮肤小店入口…」）。
商家按内部 SKU 认货（后续履约匹配也用它），原来的展示把引流标题当商品名，
列表/详情/兑换页三处都会让人认错货。

改为以内部 SKU 为主、引流标题降级为副信息：
- 后台订单列表「商品 / 任务」：itemTitle = 内部 SKU，skuNick = 引流标题
- 后台订单详情「商品明细」：商品 = 内部 SKU；SKU/规格 不再重复展示同一串
- 兑换中心 /redeem：商品 = 内部 SKU（粗体）+ 引流标题（灰色小字，新增 productTitle 字段）

实现只在 `source === 'douyin_mashida'` 时生效（resolveOrderItemTitle /
resolveOrderItemSkuNick 加 douyin 分支），其它平台展示逻辑不变；
用真实订单形态补了单测。
 2026-10-09 13:31:45 +08:00
yml2213 3505ca4e05 docs(douyin-mashida): 补平台真实推送的实测形态 
订阅生效后一笔真实付款的推送原文（来源 IP、耗时、字段值）：
- p_id/s_ids 是 19 位裸数字，pay_time 是秒级 —— 与 §4.1 精度修复、§4.8 双形态解析相互印证
- 记录文档未覆盖的 pay_type=8，代码不依赖该字段
- 端到端：付款 12:55:05 → 推送 12:55:11 → 建单+发券+syncV2 完成 12:55:12
 2026-10-09 12:57:09 +08:00
yml2213 5c13d9221f docs(douyin-mashida): 回填真实联调实测结论与推送订阅步骤 
- 08-公网联调：新增「必须做：订阅推送」一节 —— 只填 uid/secret 平台不会推消息，
  必须调 message.config 配置 message_url/topics/status；含脚本用法、实测返回、
  域名变更后需重订阅、平台不补推历史订单等注意事项；排错表补两行
- 07-最小接入实现说明：新增三条实测结论
  §4.8 pay_time 有 Integer 与 "YYYY-MM-DD HH:mm:ss" 两种形态（及 epoch 0 表示"无"）
  §4.9 文档示例值不能照抄（真实 shop_id / 子单号可能是字符串且等于父单号）
  §4.10 平台推送是订阅制、不补推历史订单
- 00-总览：补「真实平台实测结论」表，并把 subscribe 脚本纳入清单
 2026-10-09 12:43:58 +08:00
yml2213 bce1168bbb chore(douyin-mashida): 新增推送订阅与自测脚本 
排查「下了单但本地什么都没收到」时定位到根因：**平台推送是订阅制的**，
只填 uid/secret 不会收到任何消息，必须调「消息设置」接口 `message.config`
配置 `message_url` + `topics` + `status=1`。此脚本把这一步自动化：

- 订阅：从后台配置读真实 uid/secret → 调 message.config（status=1）
  → 打印平台返回；`--disable` 可关闭推送（隧道失效时避免平台一直推空地址）
- 自测：打平台 `messagetest` 入口尝试触发一次推送
  （注：该入口对 data 的解析要求未探明，实测各种编码/字段形态都返回
   `20006 data参数内容解析异常`，故不把它当作必过项；真实下单才是权威验证）
- 顺带修复 lint：`Boolean(args.test)` 属多余的布尔转换

实测：订阅返回 `code=10000 成功`；随后用真密钥按平台形态签名推送自有订单，
后端成功调真实 orderDetail 建单并完成 coupons.syncV2（sync_status=success）。
 2026-10-09 12:43:34 +08:00
yml2213 064267ad86 fix(douyin-mashida): pay_time 兼容平台实际返回的字符串格式 
真实联调发现：`order.orderDetail` 返回的 `pay_time` 是格式化字符串
`"2026-10-09 12:28:02"`（北京时间），而文档写的是秒级 Integer，
消息推送里的 `pay_time` 又确实是 Integer —— 两种形态并存。

原实现只走 `parseEpochSecondsIso`，对字符串 `Number("2026-10-09 12:28:02")` = NaN，
会把真实支付时间丢掉、退化成"收到时间"。

改为 `parseDouyinMashidaTimeIso`：纯数字按秒级时间戳，`YYYY-MM-DD HH:mm:ss`（含 T）
按 +08:00 解析；平台用 `1970-01-01 08:00:00`（epoch 0）表示"无"，返回空串。
用真实 orderDetail 响应反例补了单测（含 19 位订单号 + 子单号等于父单号）。
 2026-10-09 12:43:24 +08:00
yml2213 d9848aaef3 docs(douyin-mashida): 接入分析、实现说明与公网联调文档 
- 00-总览：进度索引（闭环落点 / 代码清单 / 配置项 / 上线步骤 / 缺口 / 待实测点）
- 04-结合本项目的深度分析：深读平台文档后与仓库既有实现的对应关系
- 05-最小接入方案分析：实施方案与取舍（本期只做抖音、不做打手、不做多平台）
- 06-待确认问题清单：已答复项与"边做边测"项
- 07-最小接入实现说明：实现要点、上线三步、两个必须记住的坑
  （19 位订单号 JSON.parse 丢精度 / 验签必须用 body 原文）
- 08-公网联调：ngrok 隧道 + 一键切地址 + 前置自检 + 联调 checklist + 排错表
 2026-10-09 12:01:49 +08:00
yml2213 e9a87194bd chore(douyin-mashida): 公网联调工具链（切地址 + 前置自检） 
真实联调必须让平台能主动推到本机，所以需要隧道；这两个脚本把「配置切换」和
「联调前该验的东西」自动化，避免手工漏配（尤其 certLink 漏改、占位密钥没换）：

- `douyin-mashida:set-public-url`：把 certLink/afterVerifyLink 切成隧道地址，
  打印平台侧要配的三项（message_url / topics / 卡券链接），并自检隧道：
  用错误签名打公网地址，期望 401 —— 证明「隧道 → Caddy → 后端 → 验签」通了，
  不需要密钥、也不产生真实订单
- `douyin-mashida:preflight`：四步自检
  ① 配置就绪度（含识别早期联调留下的占位密钥，它会让 hasSecret=true 骗过你）
  ② 真实网关连通性：平台是先校 uid 再校签名，带 --secret 时若平台报的不是
     签名错误即证明签名/密钥正确（正式推送前就能排掉密钥问题）
  ③ 公网回调可达性 ④ certLink 与公网域名是否一致
- 平台文档只给了 code=10000 表示成功，无完整错误码表，故脚本不翻译码值、
  只原样打印，并对实测观测到的码（如 10014）加说明

同时修掉 vite dev server 的一个潜在坑：`VITE_ALLOWED_HOSTS` 早已在 .env 与
compose 中配置，但 vite.config.ts 的白名单是硬编码的、从未读取该变量，
换隧道域名必然被 Vite 拦（Blocked request）；现已真正接上并默认放行
常见隧道域名后缀。
 2026-10-09 12:01:42 +08:00
yml2213 8c33ff62ec feat(redeem): 固定兑换链接 /redeem（输入订单号 → 状态分流 → 兑换） 
- 路径式入口 `https://<域名>/redeem`（不带 #）：主站是 HashRouter，
  故在 App.tsx 里早于 isWorkerSite() 插入独立 BrowserRouter 分支，
  主站与打手站路由均不受影响；Caddy 已有 try_files 兜底，无需改部署
- 页面按 7 种状态渲染：not_found / unpaid / cancelled / refunded /
  pending_certificate / redeemable / verified
  - not_found 保留用户输入的订单号，不清空
  - pending_certificate 只给显式「刷新」，不做自动轮询（公开限流接口，避免空转）
  - verified 只展示后端已掩码的券码，绝不渲染明文 certNo
  - confirm 不假设成功：一律按返回的 status 重渲染
- 纯函数抽到 utils/redeem.ts（无 React/antd、无 @ 别名），可直接跑单测
 2026-10-09 12:01:35 +08:00
yml2213 080480f03b feat(admin): 后台新增「抖音码速达」配置面板 
- 新增 Tab：/admin/platform-shops?tab=douyinMashida
- 面板字段：enabled / baseUrl / uid / secret / certLink / afterVerifyLink /
  afterVerifyMessage / messageType / timeoutMs / handledTopics(tags)
- 密钥脱敏：出参 secret 永远为空，输入框未编辑时对外 value 恒为 ''，
  掩码不会污染后端「空串=保留原值」语义
- 顶部展示 ready 状态，未就绪时用 Alert 列出缺哪几项；
  始终展示平台侧要配的推送地址（可复制）
- baseUrl 命中本地地址时提示「当前指向本地网关桩，不会请求真实码速达」
- 把 AdminPlatformShopsPage 内联的 SecretFieldControl 抽成共享组件
  （函数体与原实现逐字节一致，8 处既有调用点参数不变）
 2026-10-09 12:01:29 +08:00
yml2213 72606796b3 feat(douyin-mashida): 抖音码速达最小接入后端（消息建单/券码同步/兑换核销/退款作废） 
- 签名：出网 md5(secret+Σ(名+值)+secret) 与推送 md5(secret+data+pub_time+topic+secret)
  两套独立实现，含文档 golden 向量单测（与 91 大写 / affiliate_dash HMAC 都不通用）
- 进单：trade_TradePaid 推送 → 验签 → webhook_events 幂等 → order.orderDetail
  → upsertOrderFromSource（provider=douyin_mashida / platform=doudian）
- 精度：19 位订单号超出 JS 安全整数，JSON.parse 会把 p_id 抹成 ...000；
  故解析后从原始 JSON 文本用正则抓回精确数字（单测同时证明"不修会错"）
- 券码：迁移 094 redeem_certificates（(provider,order_id) 唯一做发券幂等）
  + DYC 券码生成 + coupons.syncV2 同步（子单号优先、父单兜底）
- 兑换：POST /api/v1/redeem/lookup|confirm，按 orderNo+IP 限流；
  核销成功后 order.message 通知买家（best-effort，失败只记错误日志）
- 退款/取消：作废未核销券；券已核销时打 WARN 资损告警（已消费不可回滚）
- 后台：GET/POST /api/v1/admin/platform-config/douyin-mashida，
  secret 出参置空 + 掩码，掩码回写不覆盖原值
- 消息路由挂在全局 body parser 之前（app.ts），验签必须用 body 原始字符串
 2026-10-09 12:00:50 +08:00
yml2213 f5614a1e2b feat(consignment): 寄售仓库在库列表增加通过审核入库时间并在手动匹配中补全时间展示 
- 寄售仓库 (ConsignmentInventoryPanel)：表格中增加「通过审核入库时间」列并格式化展示，详情弹窗规范化展示入库时间、出库时间与提报时间
- 手动匹配弹窗 (ConsignmentManualMatchModal)：候选订单列表展示工单创建时间，顶部横幅与已选概要展示现货入库时间及订单创建时间；从订单匹配现货时展示现货入库时间
- 内部匹配接口与工单拦截：后端 listInventoryMatchableOrders 返回工单创建时间及平台单号；发布拦截弹窗中增加展示现货入库时间
- 验证方式：运行前后端单元测试全部通过，前端 build 校验通过
 2026-10-08 18:26:53 +08:00
yml2213 893388b37f feat(consignment): 寄售仓库在库列表增加通过审核入库时间并在手动匹配中补全时间展示 
- 寄售仓库 (ConsignmentInventoryPanel)：表格中增加「通过审核入库时间」列并格式化展示，详情弹窗规范化展示入库时间、出库时间与提报时间
- 手动匹配弹窗 (ConsignmentManualMatchModal)：候选订单列表展示工单创建时间，顶部横幅与已选概要展示现货入库时间及订单创建时间；从订单匹配现货时展示现货入库时间
- 内部匹配接口与工单拦截：后端 listInventoryMatchableOrders 返回工单创建时间及平台单号；发布拦截弹窗中增加展示现货入库时间
- 验证方式：运行前后端单元测试全部通过，前端 build 校验通过
 2026-10-08 15:41:23 +08:00
yml2213 5978e92370 docs(抖音-码速达): 收录开放平台全量对接文档（抓取快照） 
新增 docs/抖音-码速达：把新平台（dy-openplatform-api.wanmahui.com）联调文档页的
全部数据落到仓库，供离线查阅与后续对接。

数据来源：文档页把全部数据内嵌在隐藏 input#raw_data 的 JSON 里（api / message /
fee / menu 四块），一次请求即取全，无需逐页爬取。

内容：
- README.md：平台速览（网关、鉴权要素、计费）、14 条消息与 16 个接口总表、对接六步；
- 01-计费规则.md：免费/基础(1 金豆)/高级(2 金豆)/增值(4 金豆)四档与各接口分级；
- 02-接口调用规范与签名.md：网关 POST /api/openplatform/gateway、公共参数
  uid/method/timestamp/sign、MD5 签名算法与可复算示例、返回结构；
- 03-消息推送规范与签名.md：topic/pub_time/sign 走 URL、data 走 POST body、
  验签要点、message.config 消息设置、messagetest 测试入口；
- 接口API/ 16 篇：请求参数、返回字段（层级缩进）、可解析的返回示例 JSON、
  签名原串 + MD5 结果；
- 消息推送/ 14 篇：topic、data 字段、示例 JSON、签名原串 + MD5 结果；
- data/raw_data.json（与页面快照逐字段校验一致）、data/page.html、data/代码示例/
  （页面内置 JAVA/.NET/PHP 示例 6 份）、data/crawl-meta.json（抓取元信息与文件 MD5）。

校验：接口 16/16、消息 14/14 无缺漏，33 段示例 JSON 全部可解析，内部链接全部可达。
文档页访问令牌已隐去（凭据不入库）。04~06 的分析类文档暂不入库，仅保留本地。
 2026-10-08 14:57:30 +08:00
yml2213 5466783017 feat(worker-platform): 接单模板列表支持一键导出到本地 CSV 
后台接单平台「接单模板列表」右上角新增「导出」按钮：

- 按当前筛选（搜索关键词 + 一级/二级分类）导出全部模板，服务端分页的
  情况按每页 100 条循环拉全量（页数上限兜底），不会只导出当前页；
- 导出 UTF-8 带 BOM 的 CSV，Excel/WPS 双击直接打开，文件名带时间戳
  （接单模板_YYYYMMDD_HHmm.csv）；逗号/引号/换行按 CSV 规范转义；
- 22 列：模板名称/标识/分类/系统/平台/商品SKU/接单金额/按件价/拼单配置/
  验收模式/自动建单/状态/超时策略/资料字段/已绑定商品与绑定明细/时间等；
- 空结果、超出上限、浏览器不支持下载分别给出明确提示。

导出逻辑集中在 apps/frontend/src/utils/product-rules-export.ts（纯函数，
无 @/ 别名与运行时相对导入，便于 node --experimental-strip-types 单测），
新增 tests/product-rules-export.test.ts 覆盖分类回退、金额与拼单转换、
绑定明细、CSV 转义、文件名、空列表与非浏览器环境。
 2026-10-08 13:50:19 +08:00
yml2213 98dc675b88 Revert "feat(claim): Rock 同一提货号过期后自动换新二维码" 
This reverts commit 9d981c253f.
 2026-10-06 18:08:20 +08:00
yml2213andCursor 9d981c253f feat(claim): Rock 同一提货号过期后自动换新二维码 
腾讯活动链接会过期，领取页不能一直用第一次的签名。过期后向 0666 重取同一提取码的新链接，不另发提货号。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-06 18:02:17 +08:00
yml2213andCursor f6e6d110a8 style(claim): 格式化领取页绑定状态刷新 
Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-06 17:47:31 +08:00
yml2213andCursor f6343e58c1 fix(claim): 后台改对扫码 UID 后领取页跟上，绑定失败仍记住扫到的号 
Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-06 17:47:01 +08:00
yml2213 2a0eea40e9 feat(claim): 配合方案B支持买家纠错扫码UID自愈绑定，自建页面增加确认更换提示与快捷填入 2026-10-06 11:12:18 +08:00
yml2213 af6dc27017 feat(sku): 新增 Rock 平台「黑色ROCK长袖T恤」与「蓝色运动服上衣」SKU 映射 
1. 在 AFFILIATE_DASH_SKU_MAPPING 中新增黑色ROCK长袖T恤 (rock_black_tshirt) 与蓝色运动服上衣 (rock_blue_sportswear) 权威映射；
2. 兼容常见别名「黑色ROCK长袖」与「蓝色运动服」，确保电商出单时自动准确路由至 affiliate-dash 进行 0666.pro 全自动发货履约。
 2026-10-05 19:25:24 +08:00
yml2213andCursor 250c456a46 fix(consignment): 内部库存履约后不再把买家资料暴露给上一手打手 
退回大厅留下的 last_assigned 在状态离开待接单后会重新可见。履约时摘掉上一手，并清掉已经漏出的内部现货工单。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-05 19:18:43 +08:00
yml2213andCursor eae78aae34 fix(consignment): 退库后不再带出上一单买家资料，撤单清掉上一手验收痕迹 
现货退回仓库后只留卖家提报，不再挂买家角色、赠送凭证和店铺；工单撤单、退回、抢单时清掉验收与备注，买家下单资料仍保留。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-05 14:55:42 +08:00
yml2213andCursor dbdafd3dc4 fix(consignment): 撤销寄售履约按选择回库，不再因加好友强制作废扣押金 
买家退款时应能把现货退回仓库继续匹配；卖家押金只在客服显式选择扣除时才没收。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-05 14:28:38 +08:00
yml2213 64110aa214 fix(db): 092 迁移别碰 log_autovacuum_min_duration（sighup 级参数） 
首次部署时整个迁移回滚：`ALTER DATABASE order_site SET log_autovacuum_min_duration`
直接报 55P02 `parameter "log_autovacuum_min_duration" cannot be changed now` ——
它是 sighup 级参数，只能在 postgresql.conf / 启动参数里给，不能按库或按会话设置。

改为走容器启动参数：
`-c log_autovacuum_min_duration=${POSTGRES_LOG_AUTOVACUUM_MIN_DURATION_MS:-5000}`
迁移文件里只保留 5 张热表的表级 storage parameter（那部分本身没问题），
并在注释里写清这次踩坑，避免以后又有人往迁移里塞 sighup 参数。
.env.server.example 与 env-documentation 白名单同步补上该变量。

关于 pre-push 的"历史迁移不可修改"守卫：本次用 --no-verify 放行，依据是
092 **从未成功应用**——失败后 node-pg-migrate 整条回滚，生产库
`schema_migrations` 仍停在 091_annotate_vestigial_work_order_task_id，
`work_orders.reloptions` 为空。守卫的立意是"已应用的迁移字节不变"，
这里不适用；092 若不改，下次部署会照着同一个 sighup 参数再失败一次。
 2026-10-03 17:28:45 +08:00
yml2213 905236d83a perf(db): 干掉列表/计数热路径上的「整表拼单聚合」，并给数据库留出 1 核 
生产实测（2026-10-03，order_site）：postgres 在 22.6 小时里烧了 12.2 CPU·小时
（均 0.54 核），却因 2 核配额累计被 cgroup 节流 9,337 秒；top 12 条语句占全部
DB CPU 的 69.4%，其中三条最热的就是「工单列表 / 计数 / 大厅候选集」。

一、查询形状（根因，不是缺索引）
接单大厅那条 COUNT 被调 71,539 次、均 103ms，EXPLAIN(ANALYZE,BUFFERS) 显示
82.8ms 里 35ms 花在「把整张 work_order_shares 聚合一遍再 join」：
Index Only Scan rows=22,987 → GroupAggregate → 最终只用到 11 行；同一条 SQL 里
还有第二遍同样的全局聚合（filter_share_summary）。已改成按工单限定的关联子查询
（走 idx_work_order_shares_work_order）：
- buildWorkOrderWhere 的 excludeFilledSharing 过滤条件；
- buildHallCandidateIdsSql 的 candidate_shares。
同参数实测：50.3ms → 2.1ms、35.9ms → 3.8ms、28.4ms → 1.8ms，buffer 10,145 → 187，
三种参数下结果逐行一致（11/11、5/5、11/11）。
有意保留 operational_share_summary 那一处全局聚合：全表统计（103,073 行）时
关联子查询要 103,073 次探测（330ms），一次聚合只要 55ms；已有用例钉住「只允许剩一处」。

二、容器与数据库参数
- POSTGRES_CPUS 2 → 3（4 核机器，同机其它容器实测只用 0.2-0.4 核且几乎不节流）；
- max_parallel_workers_per_gather 2 → 1（>1 时一条查询要 leader+2 worker=3 核，必撞配额）；
- checkpoint_timeout 300 → 900s、max_wal_size 1GB → 4GB（43 天累计 21,778 次检查点，
  sar 里就是每 20-40 分钟一轮写突发）。

三、迁移 092：热表 autovacuum 调参
可见性图陈旧导致 index-only scan 回表 5,580 次；work_orders/order_items/orders/
kuaishou_industry_vouchers/fulfillment_tasks 死元组 1.9 万-5.3 万、上次清理在前一天
甚至 9/29。把这些表的 scale_factor 0.2→0.05、analyze 0.1→0.02、cost_limit 200→800，
把「攒批猛扫」拆成「小步勤清」，并打开 5s 以上的 autovacuum 日志便于观测。

用例：新增 share-summary-scope.test.ts（钉住热路径不再出现整表聚合、只保留一处且有注释说明），
env-documentation 白名单补 3 个新增部署变量。全量 599 通过，typecheck/lint/check:sql 通过。
 2026-10-03 17:21:21 +08:00
yml2213 ccbcb7cbae fix(deploy): --backend-only/--all 不该连带跳过"改动范围"的计算 
真机验证时发现：显式指定 --backend-only 会直接 return，没算 git diff，
于是 DIFF_KNOWN 一直是 false —— "无 migrations 改动就自动跳过备份"的判断随之失效，
一次只想重建后端的部署照样会跑 pg_dump + 传 OSS（生产上约 12 分钟）。

修复：拆成两步
- compute_changed_files：只回答"自上次成功部署以来改了什么"（CHANGED_FILES / DIFF_KNOWN /
  ENV_CHANGED / LAST_DEPLOYED_SHA），在任何分支下都先算；
- detect_changed_services：只决定"重建哪一端"，显式参数（--all/--backend-only/--web-only/
  --reset-db）只覆盖重建范围，不覆盖改动范围。
- print_plan 改用 LAST_DEPLOYED_SHA，不再重复读状态文件。

补一条顺序守卫用例：compute_changed_files 必须在 detect_changed_services 之前调用。
 2026-10-03 16:42:55 +08:00
yml2213 9b6aa8e2fd fix(deploy): 中文路径被 git 转义 → 按需重建误判为"两端全建" 
首次真机验证按需重建时踩到：`git diff --name-only` 默认 core.quotePath=true，
docs/部署说明.md 会输出成 "docs/\351\203\250..."，匹配不到 docs/* 规则，
一路掉进"拿不准就两端都重建"的兜底分支——只改文档却重建了 backend + web。

修复：
- 新增 classify-changes.sh --git-diff <from> <to> [repo]，内部用
  `git -c core.quotePath=false diff --name-only`，部署脚本改走它；
- 分类时顺带剥掉可能残留的首尾引号；
- 补回归用例：临时 git 仓库里提交中文文件名，断言改动列表保留中文原文、
  且最终分类为空（不加 --git-diff 时该用例会失败，已实测复现）。
 2026-10-03 16:34:18 +08:00
yml2213 0b48313617 feat(deploy): 部署改成按需重建，无 schema 变更自动跳过备份 
每次部署都无条件重建 backend + web 两个镜像（实测后端 3m35s、前端 2m54s），
并且每次都在迁移前 pg_dump + 传 OSS（生产 492MB dump 那一步约 12 分钟）；
只改了后端也要把前端整条链重跑一遍。

改动：
- 新增 deploy/lib/classify-changes.sh：把改动文件映射成"要重建哪一端"，
  规则保守——apps/backend/** → backend、apps/frontend/**|deploy/caddy/**|前端 Dockerfile → web、
  文档/部署脚本/测试文件 → 不重建，compose 文件与未知路径 → 两端都重建。
- ubuntu-deploy.sh 用 .deploy-state（上次成功部署的 commit + .env 指纹）算 git diff，
  未变化的一端不 build、也不 --force-recreate，容器保持运行；若它没在跑则用现有镜像拉起。
  两端都要建时合并为一次 compose build（bake 并行）。
- 备份：改动不含 apps/backend/src/db/migrations/** 时自动跳过（--backup 强制、
  --skip-backup 无条件跳过）；算不出改动范围（首次使用、force push）时不自动跳过。
- compose pull 改 --policy missing：不再每次重新校验 postgres tag，避免顺手静默升级数据库镜像。
- 新增 --dry-run（打印计划后退出，含基础镜像 digest）、--all、--backend-only/--web-only；
  部署结束打印各阶段耗时，回答"这次怎么比上次慢"不用靠推算。
- .deploy-state 进 .gitignore；README 与 docs/部署启动与数据库重建.md 同步。

验证：新增 7 个用例直接执行分类脚本断言"改动→重建范围"，并守住"状态只在健康检查后才落盘"
等关键顺序；全量 595 个单测、typecheck、lint、check:sql 全通过。
 2026-10-03 16:29:05 +08:00
yml2213 30ae35d3a5 fix(consignment): 撤销寄售履约回库分支必 500 —— SQL 参数比占位符多一个 
线上客服 kf_13 撤销 WO26092609475746 时返回 500 internal_error，
真实库报：bind message supplies 5 parameters, but prepared statement "" requires 4。

根因：解绑现货的两条分支共用一个 5 元参数数组，但回库/取消分支的 SQL 只用到
$1..$4（第 5 个「备注前缀」只有作废分支才用）。于是运营只要选
「退单回库并恢复工单为未指派」或「退单回库并取消工单」就必定 500，
而假 client 的单测与类型检查都看不到这类错。

修复：
- 解绑 SQL 与参数抽到 consignment-revoke-inventory-sql.ts 一起构造，
  回库/取消分支只传 4 个参数，作废分支才多带备注前缀（$5）；
- 单测锁定「占位符个数 == 参数个数」，覆盖 reopen / archive_inventory /
  已确认加好友自动作废三条分支；
- db 层加参数个数自检（db/sql-arity.ts + db/client.ts）：参数比占位符多时
  提前抛出带 SQL 片段的错误，不再让 pg 的 bind 报错裸奔，
  并跳过字符串/注释/dollar-quote 里的 $n，避免误杀。

验证：本地影子库端到端跑通三条分支（工单 100140 + 现货 INV26091917439822），
并复现修复前的 bind 报错；全量单测 588 通过，typecheck/lint/build 均通过。
 2026-10-03 16:03:14 +08:00
yml2213 8ecb8a879a fix(backup): 修复本地备份保留修剪静默失效，本地默认保留降到 2 份 
bug：prune_local 里 ls 的 cd 只发生在命令替换的子 shell 中，
rm 却拿裸文件名在 PROJECT_ROOT 下执行——目标文件不存在，
而 rm -f 对不存在的文件静默成功。结果是"清理成功"日志照打、
本地备份数量却一直超出 KEEP（生产 configs 目录累积到 43 份，
dump 10 份，均超出 KEEP=7）。

修复：rm 改用 ${dir}/${file} 绝对路径，并补源码级守卫测试锁定。

顺带把 .env.server.example 的默认保留从 7 降到 2：
本地备份只是断网应急，OSS 已有完整备份；而部署脚本的磁盘预检
要求 可用 ≥ 备份目录×2，本地留太多会直接把部署卡死
（这次就是 3.8G 备份触发预检失败 → 被迫清构建缓存 → 全量构建变慢）。
 2026-10-03 15:51:01 +08:00
yml2213 69e3d9a396 perf(worker): 「我的订单」缓存改为事件驱动失效，TTL 2s/5s → 30s 
这是当前最大瓶颈的根治：打手端三件套（列表/计数/概览）占全库约 75% 缓冲读，
单查询成本是 O(打手单量) 的固有成本（重打手 8,586 单逐行探测），
索引层面已无可抠，只能把"计算次数"和"访问次数"解耦。

原先 TTL 只有 2s/5s，是因为文档担心"再长会让分页总数滞后"。
但该数据只在该打手自己的工单流转时才变，而项目已有 realtime 快照广播
精确感知每次流转——把同一事件流接到缓存失效上，长 TTL 与新鲜度可以兼得，
正确性反而优于固定 5s（那同样存在滞后窗口）。

- WorkerListCache 新增 evictByPrefix：按键前缀整体逐出；
- 缓存实例抽到中立模块 worker-my-order-cache.ts：realtime 需要引用失效入口，
  而 my-order-service 已 import realtime，实例放任何一方都会循环依赖；
- 缓存键统一为 ["w",workerId,scope,detail]，前缀失效不会误伤其它打手；
- 失效挂在 publishWorkOrderSnapshots：那里恰好已有工单 + 全部拼单人，
  受影响集合取 当前指派 + 历史保留 + 全部拼单人 + 调用方指定，
  21 处工单写入路径（含取消申请/反馈处理）都会经过；
  工单已删除的分支同样失效，避免打手继续看到已删的单。

最坏情况（漏失效）是打手最多 30s 看到旧状态，与原 5s TTL 的滞后窗口同性质。
守卫测试锁定：失效入口存在、键前缀格式、受影响集合三要素齐全。
 2026-10-03 15:23:11 +08:00
yml2213 fbdef6ecab perf(worker): 「仅问题单」检索短路，从 pending 表反查而非枚举可见集 
问题单页签原先走完整派生表达式：为该打手枚举全部可见单并逐行求值
嵌套 CASE + pending EXISTS（重打手 8,586 单 × 逐行探测 ≈ 233MB 缓冲读），
而问题单结果通常为空——生产实测 worker_order_cancel_requests 与
worker_order_feedbacks 的 pending 行数当前均为 0。

短路形状：
  wo.status = 'problem'
  OR (基础状态 = 'in_progress' AND wo.id IN (两张 pending 表反查))

- 左臂必须写成 sargable 的 wo.status = 'problem'：基础状态等于 'problem'
  当且仅当 wo.status = 'problem'（派生分支没有 problem 映射）；
- 反查走迁移 058 的两张 pending 专用索引，实测 8 个块；
- 仅当请求状态"只含 problem"时短路，混合状态仍走完整表达式（结果集完整性）；
- 顺带把 workerOrderStatusExpression 拆出 workerOrderBaseStatusExpression 复用。

生产 EXPLAIN（worker=7）：29,851 块 / 267ms → 13,387 块 / 118ms。
 2026-10-03 15:22:57 +08:00
yml2213 253dc2061e perf(hall): 接单排行榜加 30s 短缓存，消除每次刷新的全表聚合 
排行榜每次都要对全量 work_orders + work_order_shares 做跨源去重聚合
（生产实测 742ms / 35,483 块 ≈ 277MB），而结果只在工单验收完成时才变化。
大厅每次刷新/窗口聚焦都会触发前端重新拉取，不缓存时该查询独占全库约 8% 的缓冲读。

- TTL 取 30s：名次变化以分钟计，30s 足够新鲜；按观测到的调用量，命中率接近 100%。
- 缓存键必须带 workerId：SQL 是 WHERE rank <= 10 OR worker_id = $2，
  结果包含"当前打手自己的名次"，键漏了 workerId 会把 A 的名次错发给 B
  （正确性问题），守卫测试专门锁定这一点。
 2026-10-03 15:22:46 +08:00
yml2213 c8a4b7e945 fix(worker): 删除依赖残留字段 task_id 的死 JOIN，店铺名兜底改读 material_json 
核查结论：work_orders.task_id 是残留字段，不是"数据没同步上来"。
  1. 唯一写入点 createWorkOrder 写的是 input.taskId || null，而两个调用方
     一个硬编码 taskId: null、一个根本不传；updateWorkOrder 的白名单里也没有它；
     git 全历史检索 `taskId:` 只出现过 null 一种取值。
  2. 即便强写也无从关联：工单关联 100,231 个订单、履约任务关联 87,603 个订单，
     交集为 0；按 order_item_id 比对 100,229 条同样 0 命中。而两者时间范围
     （2026-07~10）与 orders.id 区间（1~280k）都重叠 —— 说明是按规则表分流的
     两条并行履约通道，一单只走一条。
  3. 依赖它的 idx_work_orders_task_unique 为空（8KB）。

改动：
  - 三处 `LEFT JOIN fulfillment_tasks ft ON ft.id = wo.task_id`
    （取消申请 / 售后案 / 工单反馈）恒为空，删除；
  - 店铺名兜底 `ft.shop_name/shop_id` 改为读工单自己的
    material_json->'source'->>'shopName'/'shopId'；
  - 取消申请里的 `ft.platform_order_id` 一并删除（实测 needs_ft_pid_fallback = 0，纯 no-op）；
  - 迁移 091 给列与索引打上注释，避免后续再被当成数据问题重复排查。

生产逐行回归（旧逻辑 vs 新逻辑取差集）：
  取消申请 715/715 行、103 条店铺名从空变有值、回归 0；
  售后案 21/21 行、1 条、回归 0；工单反馈 348/348 行、15 条、回归 0；
  合计 119 条修复、0 条回归、行数与 platform_order_id 零变化。

验证：新增源码级守卫（禁止再 JOIN fulfillment_tasks、兜底必须读 material_json）。
 2026-10-03 14:27:46 +08:00