- 平台层新增 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>
4.2 KiB
4.2 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后提交
店管家店铺的两个来源
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