- 新增 .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>
3.6 KiB
3.6 KiB
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)。
新增下游渠道时的步骤
- 取一单真实报文,确认
TagValue形态:是否*_plaintext;取号响应Order.ExtraJson.extField7是否含outPlatformOrderNo - 密文渠道才需要加进
DISTRIBUTE_CHANNEL_PLATFORM;明文不用加(已统一走 TB) - 确认「平台 + 快递编码」在
external_print_express_interfaces里唯一命中(platform_code + custom_code;custom_code重复会让resolveByCode返回 null,报「未绑定模板」) backend/test/app/lib/dgjOrderPlatformRule.test.js补用例(密文 → 目标平台、明文 →TB)- 同步更新
店管家取号-旧系统提取.md§4.2 换算表 / §4.2.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