- 平台层新增 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>
54 lines
4.2 KiB
Markdown
54 lines
4.2 KiB
Markdown
# 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`
|