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

46 lines
3.6 KiB
Markdown
Raw 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` | 订单带下游原单信息(取号响应 `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`