生产实测: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>
56 lines
4.3 KiB
Markdown
56 lines
4.3 KiB
Markdown
# 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`
|