diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..c9ad555 --- /dev/null +++ b/.github/copilot-instructions.md @@ -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 --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` diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index bb6dfcd..526a204 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -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