oms/.github/copilot-instructions.md
liufumingren 69c272d260 feat(dgj): 1688 淘宝分销单(thyny)换算成淘宝取号
生产实测: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>
2026-11-09 20:16:53 +08:00

56 lines
4.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`)。
### 新增下游渠道时的步骤
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` 后提交
## 店管家店铺的两个来源
`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`