生产实测:1688 单的 `OutChannel=thyny`(密文淘宝分销单,订单号形如 5127404439433014429) 没有进渠道映射表,落库成了「其他(OTHER)」,取号时匹配不到菜鸟模板 (2 单:dgj-10000290937711 等)。业务确认 thyny 就是淘宝分销渠道。 - DISTRIBUTE_CHANNEL_PLATFORM 增加 thyny → TB - 单测:密文 thyny → TB / 淘宝;未识别渠道改用 chaoshibianli → OTHER(thyny 已有映射) - 文档 §4.2 换算表、§4.2.6「已确认的渠道映射」、.github/copilot-instructions.md 同步 存量:这 2 单重新拉单即从 OTHER 变成淘宝,可用 YUNDA(TB → 12362952 菜鸟韵达一联4)取号。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
4.3 KiB
4.3 KiB
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、thyny |
订单带下游原单信息(取号响应 Order.ExtraJson.extField7 里有 outPlatformOrderNo / outShopId / 加密收件人) |
抖音小店 DYXD / 快手 KS / 淘宝 TB |
| 明文 | douyin_plaintext、kuaishou_plaintext、thyny_plaintext… |
店管家侧没有原单信息(extField7 为空),抖店/快手电子面单必被拒(ErrCode=15002 非抖店订单,无法使用抖音电子面单取号打印) |
淘宝 TB(菜鸟面单) |
换算在 backend/app/lib/printPlatform/dgj.js 的 normalizeOrder:DISTRIBUTE_CHANNEL_PLATFORM
(douyin→DYXD、kuaishou→KS、thyny→TB)只对密文生效;*_plaintext 一律 TB(isPlaintextDistributeChannel);
未映射的非明文渠道 → OTHER;无渠道 → TB。
渠道原值留痕在 extend_props.distribute_channel。订单域名永远按原始平台算(1688 → fxali.dgjapp.com)。
新增下游渠道时的步骤
- 取一单真实报文,确认
TagValue形态:是否*_plaintext;取号响应Order.ExtraJson.extField7是否含outPlatformOrderNo - 密文渠道才需要加进
DISTRIBUTE_CHANNEL_PLATFORM;明文不用加(已统一走 TB) - 确认「平台 + 快递编码」在
external_print_express_interfaces里唯一命中(platform_code + custom_code;custom_code重复会让resolveByCode返回 null,报「未绑定模板」) backend/test/app/lib/dgjOrderPlatformRule.test.js补用例(密文 → 目标平台、明文 →TB)- 同步更新
店管家取号-旧系统提取.md§4.2 换算表 / §4.2.6 npx egg-bin test test/app/lib/dgjOrderPlatformRule.test.js后提交
店管家店铺的两个来源
shops.external_source 区分 agent(平台商家,LoadMyAgentList,订单按商家 FxUserId 归属)
与 my_shop(我的店铺,LoadMyShopList,订单按 ShopId 归属)。来源清单由
PrintPlatformService.listShopSources() 声明,控制器/前端不写死。
my_shop 的订单按 LogicOrder.ShopId、商品按 SelectShopId 取数(不能沿用商家 FxUserId,
那是账号自己)。orderSyncTask 查店铺时必须带上 external_source,否则会按错误口径拉单。
细节见 店管家取号-旧系统提取.md §4.2.1.1。
常见排查入口
- 取号失败:平台原始返回在
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