oms/.github/copilot-instructions.md
liufumingren 9a0f826d1b feat(dgj): 我的店铺支持同步商品与拉取订单(按 ShopId / SelectShopId 归属)
- listProducts:my_shop 用 SelectShopId=ShopId + SelectPlatformType,域名按 PlatformType 推导;缺 ShopId 明确报错
- listOrders:my_shop 用 LogicOrder.ShopId(Contract=in)过滤,本地按 row.ShopId 校验归属,不再带 UpFxUserId
- 订单 CreateTime 上界补 .999,对齐平台「待打订单」页抓包
- resolveTemplateTargets 按来源分支:自营店直接用 PlatformType 作为模板接口 platformType
- orderSyncTask 查询店铺补 external_source,避免按商家口径误拉
- 前端:我的店铺不展示/不刷新「所在区」,拉单提示按来源说明;ShopItem 增加 external_source
- 测试:补 ShopId 过滤报文、时间窗上界、buildProductForm 归属口径;文档同步 4.2.1.1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-09 03:06:53 +08:00

55 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` 的订单按 `LogicOrder.ShopId`、商品按 `SelectShopId` 取数(**不能**沿用商家 `FxUserId`,
那是账号自己)。`orderSyncTask` 查店铺时必须带上 `external_source`,否则会按错误口径拉单。
细节见 `店管家取号-旧系统提取.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`