oms/.github/copilot-instructions.md
liufumingren c27ea5a789 feat(shop): 店管家接入「我的店铺」第二来源,支持拉取店铺并绑定货主
- 平台层新增 listShopSources() / resolveShopScope() 契约,来源由平台实现声明,控制器与前端不写死
- 店管家实现 my_shop 来源:POST /partner/LoadMyShopList 店铺列表(授权状态、平台、名称过滤)并归一化
- 新增 GET /api/external-print-accounts/:id/shop-sources;店铺列表接口支持 ?source=
- 店铺创建支持 source,写入 shops.external_source;编码 dgj-{账号ID}-{来源}-{ShopId},默认来源不加来源段
- 新增迁移 shops.external_source(默认 agent);刷新所在区只处理默认来源,避免自营店被误判解绑而自动禁用
- my_shop 的拉单/拉商品暂时明确拒绝,防止按账号 FxUserId 拉到上游其它数据(下一步接入)
- 前端「店铺列表」弹窗支持来源切换,展示平台、授权状态与服务到期时间
- 补充单元测试与文档(店管家取号-旧系统提取 §4.2.1.1)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-09 02:42:24 +08:00

4.2 KiB
Raw Blame History

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 后提交

店管家店铺的两个来源

shops.external_source 区分 agent(平台商家,LoadMyAgentList,订单按商家 FxUserId 归属) 与 my_shop(我的店铺,LoadMyShopList,订单按 ShopId 归属)。来源清单由 PrintPlatformService.listShopSources() 声明,控制器/前端不写死。 my_shop 目前只支持店铺导入,listOrders / listProducts 会明确报「暂未支持」, 避免按账号 FxUserId 拉到别人的数据。细节见 店管家取号-旧系统提取.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