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>
This commit is contained in:
liufumingren 2026-11-08 19:28:37 +08:00
parent 6587e9b937
commit ccf021c422
2 changed files with 66 additions and 0 deletions

45
.github/copilot-instructions.md vendored Normal file
View File

@ -0,0 +1,45 @@
# 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`

View File

@ -570,6 +570,27 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
沿用旧口径的坑:老数据里 `shop_products.outer_sku_id` 可能是 `SpecId`,与明细的 `SkuId` 对不上;
重新同步商品会按 `SkuId` 就地改键(同商品同规格名唯一命中),之后重匹配即可命中。
#### 4.2.6 新增下游分销渠道怎么加(明文 / 密文)
分销渠道散落在 `Tags` / `OrderTags` 的 `OutChannel.TagValue` 里,**同一渠道有成对写法**:
密文(`douyin`、`kuaishou`)+ 明文(`douyin_plaintext`、`kuaishou_plaintext`、`thyny_plaintext`…)。
新增平台/渠道按下面这套走:
| 步骤 | 做什么 | 怎么判定 |
|---|---|---|
| 1 | 抓一单真实报文,确认 `TagValue` 形态 | 明文一定以 `_plaintext` 结尾;密文是纯渠道名 |
| 2 | 看取号响应里 `Order.ExtraJson.extField7` 是否带原单信息 | 有 `outPlatformOrderNo` / `outShopId` / `encryptReceiver*` → 密文单,可用下游电子面单;空串 → 明文单,只能用淘宝(菜鸟)面单 |
| 3 | 密文渠道:加进 `DISTRIBUTE_CHANNEL_PLATFORM`(`lib/printPlatform/dgj.js`);明文不用加 | 明文统一由 `isPlaintextDistributeChannel` 判到 `TB` |
| 4 | 确认「平台 + 快递编码」唯一命中模板 | `external_print_express_interfaces` 里 `platform_code + custom_code` 必须唯一(重复会让 `resolveByCode` 返回 null → 报「未绑定模板」) |
| 5 | 补单测 + 更新本文 §4.2 换算表 | `test/app/lib/dgjOrderPlatformRule.test.js`:密文 → 目标平台、明文 → `TB` |
**判定依据(实测 2026-11-08)**:同一店铺(7398588)、同一模板(12360764 抖店韵达)、
同一收件人区域下,密文单 `dgj-10000289308826` 取号成功,明文单 `dgj-10000289308857`
被平台拒绝 `ErrCode=15002 非抖店订单,无法使用抖音电子面单取号打印`;两者差别只在
`Order.ExtraJson.extField7`(成功单有 `outPlatformOrderNo`,失败单是 `""`)。
另外店管家 UI 对明文单的打印弹窗默认模板是「【菜鸟】国内邮政小包一联3」(我们库里 TB 平台的 13873834),
`LoadWaybillAccountDetailInfo` 也用 `expressCode=POSTB` —— 说明平台自己就把明文单按淘宝/菜鸟处理。
### 4.3 模板校验:`POST /TemplateSet/CheckTemplateAvaliable`
```json