fix(product-v2): 创建产品基础信息 agencyId 未持久化 (#1822 → PR #1823)

changelogs/2026-05/07_fix_product_basic_save_agency_id_missing.md

@@ -0,0 +1,66 @@
+# fix(product-v2): 创建产品基础信息 agencyId 未持久化致 INSERT 失败
+
+**PR**: [#1823](https://git.1814.love:8443/wx/HL/pulls/1823) **Issue**: [#1822](https://git.1814.love:8443/wx/HL/issues/1822) **合并**: 2026-05-07
+
+通知对象: 无前端配合(后端 VO 加字段, 前端原本就在传)
+
+---
+
+## 现象
+
+正式环境 admin.1814.love 创建产品: 填完基础信息点保存 → 弹 `字段【agency_id】未填写，请填写后重试`。前端实际已传 `agencyId="2051922156798779394"`,但被后端丢弃。重现率 100%。所有创建新产品的路径全部失败。
+
+```
+POST /admin/product/item/basic
+Body: {"name":"wx","productType":"CUSTOM","agencyId":"2051922156798779394",...}
+响应: {"code":400,"message":"字段【agency_id】未填写，请填写后重试","success":false}
+```
+
+## 根因
+
+`ProductBasicSaveReqVO` 没有 `agencyId` 字段:
+
+1. 前端 body 含 `agencyId="2051922156798779394"`
+2. Jackson 反序列化丢弃(VO 无字段接收)
+3. `ProductBasicService.doCreate` line 344 `BeanUtil.toBean(req, ProductDO.class)` → `product.agencyId = null`
+4. INSERT 违反 `V20260507_001__product_agency_id_not_null.sql` 加的 `agency_id BIGINT NOT NULL`
+5. MySQL 抛 `Field 'agency_id' doesn't have a default value`
+6. `GlobalExceptionHandler.FIELD_NO_DEFAULT` 翻译为「字段【agency_id】未填写」
+
+时间线: V20260506_001 加列 → V20260506_006 软删行回填 → **V20260507_001 NOT NULL = 引爆点**
+
+## 后端修了什么
+
+1. `ProductBasicSaveReqVO` 加字段:
+   ```java
+   @NotNull(message = "所属旅行社公司不能为空")
+   @ApiModelProperty(value = "所属旅行社公司ID（必填，关联 travel_agency.agency_id）", required = true)
+   private Long agencyId;
+   ```
+2. `ProductBasicService.saveBasic` 加更新兜底,前端漏传时保留原值不破坏已有归属(业务规则: agency 绑定 mchId 不可空)。
+
+## 前端无需改动
+
+`POST /admin/product/item/basic` 接口签名/请求体/响应 VO 0 改动。前端原本就在传 `agencyId`,本次只是后端补上接收。
+
+## 部署依赖
+
+无 nacos / SQL / 第三方配置变更。直接部署即生效(本 PR 不涉及 V*.sql, 不依赖 Flyway)。
+
+## 受影响范围
+
+- 创建 CORE/GROUP/CUSTOM 三类产品(`POST /admin/product/item/basic` productId=null 路径) — 修复后正常落库
+- 编辑现有产品 — 加兜底防漏传覆盖,无回归
+- 已有数据 — 不受影响(V20260506_001/006 已回填存量)
+- gateway 路由 `/admin/product/**` 已存在(`application.yml` line 173-174),未改
+
+## 验证
+
+- 单测 23/23 全绿(新增 2 条: 创建带 agencyId 持久化正确 / 更新缺 agencyId 保留原值)
+- 本地 round-trip 跳过(本地 phpStudy MySQL/RocketMQ 今日重启炸 4 次, timebox 切兜底)
+- 测试服 round-trip 等部署后实测
+- 正式部署交运维管理员
+
+## 已识别但未处理
+
+`ProductSaveReqVO` 同样缺 agencyId, 被 `ProductBasicService.createProduct(ProductSaveReqVO)` (line 123) 使用, 但主代码 0 调用 = 死代码(只测试在调)。建议下个 PR 单独删除, 避免本 BUG fix PR 范围扩散。