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

54 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`