oms/.github/copilot-instructions.md
liufumingren ccf021c422 docs: 记项目记忆:分销单明文/密文规则 + 新增渠道处理步骤
- 新增 .github/copilot-instructions.md(项目记忆,AI 助手每次会话都会读到):
  基本约定(测试/发布/提交规范、生产只读排查)、店管家分销单明文 vs 密文规则、
  新增下游渠道的处理步骤、常见排查入口(取号/明细匹配/发货回传)
- 店管家取号-旧系统提取.md 新增 §4.2.6「新增下游分销渠道怎么加(明文/密文)」:
  判定依据(TagValue 是否 _plaintext、extField7 是否含 outPlatformOrderNo)、
  改哪里(DISTRIBUTE_CHANNEL_PLATFORM / isPlaintextDistributeChannel)、
  模板唯一性检查(platform_code + custom_code)、单测与文档同步、实测佐证

背景:明文分销单(douyin_plaintext 等)在店管家没有原单信息,抖店/快手面单会被拒
(ErrCode=15002),已统一按淘宝(菜鸟)出号;后续新增渠道按这套流程处理。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-08 19:28:37 +08:00

3.6 KiB
Raw Blame History

OMS 项目说明(给 AI 助手)

基本约定

  • 目录:backend/(Egg.js + Sequelize + MySQL)、frontend/(Vue3 + Element Plus + Vite)、tools/(发布工具)
  • 后端测试:cd backend && npx egg-bin test [test/...];Lint:cd backend && npx eslint <文件>
  • 前端校验:cd frontend && npx vue-tsc --noEmit、npx vite build
  • 迁移:cd backend && npx sequelize-cli db:migrate(本地库 127.0.0.1:3307/oms,测试也连它)
  • 提交:每次改动都要提交。commit message 用中文,用 create 工具写文件后 git commit -F <file> --no-verify (PowerShell here-string 写中文会丢失;PS5.1 的 Set-Content -Encoding utf8 会加 BOM 导致 Node 语法错误)
  • 生产:后端 /www/wwwroot/oms.gztbyc.com/api(v1/v2 蓝绿,nginx → 6091),发布 cd tools && npm run deploy (会自动跑迁移)。生产只读排查用 ssh + shared-config/.env 里的 MYSQL_*,写操作必须先问用户

店管家(dgj)分销单:明文 vs 密文(重要)

1688 单的 Tags / OrderTags 里 Tag=OutChannel 的 TagValue 有成对写法:

形态 例子 含义 出号平台
密文 douyin、kuaishou 订单带下游原单信息(取号响应 Order.ExtraJson.extField7 里有 outPlatformOrderNo / outShopId / 加密收件人) 抖音小店 DYXD / 快手 KS
明文 douyin_plaintext、kuaishou_plaintext、thyny_plaintext… 店管家侧没有原单信息(extField7 为空),抖店/快手电子面单必被拒(ErrCode=15002 非抖店订单,无法使用抖音电子面单取号打印) 淘宝 TB(菜鸟面单)

换算在 backend/app/lib/printPlatform/dgj.js 的 normalizeOrder:DISTRIBUTE_CHANNEL_PLATFORM(douyin→DYXD、kuaishou→KS) 只对密文生效;*_plaintext 一律 TB(isPlaintextDistributeChannel);未映射的非明文渠道 → OTHER;无渠道 → TB。 渠道原值留痕在 extend_props.distribute_channel。订单域名永远按原始平台算(1688 → fxali.dgjapp.com)。

新增下游渠道时的步骤

  1. 取一单真实报文,确认 TagValue 形态:是否 *_plaintext;取号响应 Order.ExtraJson.extField7 是否含 outPlatformOrderNo
  2. 密文渠道才需要加进 DISTRIBUTE_CHANNEL_PLATFORM;明文不用加(已统一走 TB)
  3. 确认「平台 + 快递编码」在 external_print_express_interfaces 里唯一命中(platform_code + custom_code; custom_code 重复会让 resolveByCode 返回 null,报「未绑定模板」)
  4. backend/test/app/lib/dgjOrderPlatformRule.test.js 补用例(密文 → 目标平台、明文 → TB)
  5. 同步更新 店管家取号-旧系统提取.md §4.2 换算表 / §4.2.6
  6. npx egg-bin test test/app/lib/dgjOrderPlatformRule.test.js 后提交

常见排查入口

  • 取号失败:平台原始返回在 waybill_fetch_records.raw_response,可读原因由 DgjService.describeWaybillError 写进 error_message(形如 ErrMsg(ErrCode=…))
  • 想对照「我们实际发给平台的取号报文」:DgjService.buildExpressPrintOrder(row, { templateId, expressCode }) (expressPrint 内部用的同一个函数;取号记录里只有平台回显,没有请求体)
  • 规格错乱 / 明细匹配不上:lib/shopProductMatch.js 口径 = 平台规格ID → 店管家规格编码(outer_sku_code, 1688 单的 SkuId 是商品标题)→ 只有完全没有规格信息时才按商品ID取一条
  • 发货回传的 dbname 必须用 waybill_fetch_records.dbname(取号记录),不能用模板记录的 dbname