diff --git a/changelogs/2026-04/2026-04-20_bug-batch-fixes.md b/changelogs/2026-04/2026-04-20_bug-batch-fixes.md new file mode 100644 index 0000000..df89d51 --- /dev/null +++ b/changelogs/2026-04/2026-04-20_bug-batch-fixes.md @@ -0,0 +1,131 @@ +# 第一期 BUG 批量修复（4-20 部署） + +**日期**：2026-04-20 +**PR**：#956、#957、#958、#959、#960 + gateway #966、ddl hotfix #965/#967 + +本批次共修复 9 个后端 BUG 并部署测试环境，同时列出 6 个纯前端 BUG 需前端同学跟进。 + +--- + +## ✅ 后端已修（前端大多无需改动） + +### BUG 11 — 价格日历报 "month: 月份格式错误"（前端无感） +`@Pattern` 正则从 `\d{4}-\d{2}` 放宽为 `\d{4}-(0?[1-9]|1[0-2])`，后端 `YearMonth.parse(month, "yyyy-M")` 容错。 +**前端**：传 `month=2026-5` 或 `2026-05` 都可，**自动兼容**。 + +### BUG 16 — "数据操作违反约束"不给字段信息 +`GlobalExceptionHandler` 对 `DataIntegrityViolationException` 5 种模式关键字匹配： +- `Column 'xxx' cannot be null` → `字段 【xxx】 不能为空` +- `Data too long for column 'xxx'` → `字段 【xxx】 长度超限` +- `Duplicate entry ... for key 'xxx'` → `数据重复，索引: xxx` +- `Unknown column 'xxx'` → `数据库字段 【xxx】 不存在（schema drift）` +- 外键失败 → `外键约束失败：关联数据不存在` + +**前端**：错误 message 字段更友好，可直接透传给用户。 + +### BUG 17 — 小蒙马上架报 "至少需要1个未来有效价格" +`ProductValidationService.validatePublish` 按 `productType` 分流： +- CORE/CUSTOM → 走 `product_price_calendar` 校验（原逻辑） +- GROUP → 走 `group_tour_batch.adult_price` 校验（匹配"班期表价格"语义） + +**前端**：无改动。小蒙马产品上架流程可正常走通。 + +### BUG 3 — 小蒙马小程序详情 startPrice=null 导致预订按钮灰 +`MpProductDetailAssembler` 同步分流。GROUP 产品走 `groupTourBatchService.findMinAdultPriceFuture`。 + +**前端**：无改动。小蒙马产品详情 `startPrice` 现在会正确返回班期最低成人价。 + +### BUG 7 — 里程自动计算偏短 +根因： +1. 白名单只认 SCENIC/ACTIVITY/HOTEL，自定义节点被静默过滤 +2. 集合地/解散地坐标从未参与 + +修复： +- `AmapDrivingService.COORD_NODE_TYPES` 重构：新增 `BYO_COORD_NODE_TYPES={CUSTOM,NOTE,TRANSPORT,PHOTOGRAPHY,FREE}`，自带 lng/lat 才参与 +- `ItineraryAutoCalculator.autoCalculateDailyMileage` 入参加 `List`，按 dayNumber 抽 gather/dismissal 透传 + +**前端**：`DailyMileageCalcReqVO` 新增可选字段： +- `NodeRef.lng/lat`（BigDecimal 可空，BYO 节点带坐标才参与计算） +- `DayNodes.gatherPlace/dismissalPlace`（Object 可空，同高德行政区 JSON `{name,adcode,center,level}`） + +**前端 TODO**：行程编排页保存"计算里程"接口时，把每天的 `gatherPlace`/`dismissalPlace` 和各节点的 `lng/lat` 一并传，里程会更准确。不传也向下兼容。 + +### BUG 9 — 添加/编辑景区保存报 500 +schema drift：Entity 有 `photographyGuide` 字段，DB 无 `photography_guide` 列。 +修复：DDL 加列（独立迁移脚本 `sql/alter_scenic_spot_add_photography_guide.sql`，测试环境已执行）。 + +**前端**：无改动。景区创建/编辑接口正常。 + +### BUG 13 — 定制师看不见自己建的主题 +`ProductLineService.saveLine` 创建分支加 `setCreatedBy` 兜底：若请求头缺 `X-Admin-Id` → 抛 `BusinessException("未识别到管理员身份")`，避免 `createdBy` 落 NULL。 + +**前端**：管理端创建产品线时**务必确保** HTTP 请求头带 `X-Admin-Id`（或 `Authorization: Bearer ` 让后端从中提取）。 + +### BUG 14 — 新建产品版本后小程序端看不到（缓存） +`ProductHelperService.registerAfterCommitInternal` 的 afterCommit 回调改调 `evictAllMpCache`，除产品详情缓存外，额外清： +- `mp:product-line:detail:*`（产品线详情） +- `mp:products-by-line:*`（产品线下产品列表） + +**前端**：无改动。新建/上架/下架产品后小程序端立即可见，不再需要等 10 分钟缓存过期。 + +### BUG 18 — 产品线封面改了小程序端不更新 +`ProductLineService.saveLine/deleteLine` 加 afterCommit 清缓存（同 BUG 14 的 evictAllMpCache 无参版）。 + +**前端**：无改动。产品线封面/描述改动立即在小程序端可见。 + +--- + +## 🔵 需前端跟进的 BUG + +### BUG 1 — 主题页产品名错（前端取字段错误） +现状：主题页显示"6 天 5 晚 · 亲子游"，应为后台配置的 `name="带孩子，看一次真正的草原。"`。 + +**后端确认**：`MpProductService:387-399` 的 `name` 字段取自 `product.name`，值正确。**前端取错了字段**（可能把 `subtitle` 或拼接字符串当标题）。 + +**前端 TODO**：确认主题页产品标题读的是 `product.name` 而非 `subtitle` 或其他拼接逻辑。 + +### BUG 2 — 产品详情页第一屏没有标签 +后端 `MpProductDetailRespVO.tags` 字段存在，DB 实际数据都有（如 `["亲子", "研学", "摄影"]`）。测试环境已查明：DB 数据完整，后端正确返回。**前端未渲染**。 + +**前端 TODO**：检查产品详情首屏的 tags 渲染逻辑。 + +### BUG 5 — 用户端第二页面卡片缺 icon +`BrandCard` DTO 只有 `title/subtitle/coverUrl`，**无 `iconUrl` 字段**。 + +**前端 TODO + 确认**：前端是否**必需**独立的 icon 字段（而非复用 coverUrl 缩略图）？ +- 如确需：后端需改 common-core DTO（影响全服务重部署，成本高），请明确反馈 +- 如可不加：复用 coverUrl 即可 + +### BUG 6 — 发布产品弹窗仍报"未配置实际用车车型" +测试 jar 反编译已验证 PR #932 的新文案已生效。**浏览器缓存问题**。 + +**前端 TODO / 用户**：Ctrl+Shift+R 硬刷后重试。 + +### BUG 8 — 资源库添加酒店区域分类无法使用 +后端 `HotelQueryRequest` 无 `district` 筛选字段，无"按 city 列 district"字典接口。 + +**前端 TODO**：在 F12 Network 看这个下拉实际调的是哪个接口（带什么参数），反馈后再判断是否需要后端补接口。 + +### BUG 12 — 每日集合地/解散地不用必填 +后端 `ProductItinerarySaveReqVO.DayItem.gatherPlace/dismissalPlace` 是 `Object` 且无任何校验注解，**后端不强制必填**。前端 `*` 号只是 UI 装饰。 + +**前端 TODO**：去掉这两个字段 UI 上的 `*` 号。副作用：空集合地时后端不生成首尾路线点和线路概览（已 null-safe 不报错）。 + +### BUG 19 — 产品选定金比例后小程序没返回定金金额 +后端 `product_basic` 表有 `deposit_ratio` 和 `deposit_amount` 列，`MpProductDetailRespVO.depositRatio`/`depositAmount` 字段存在，`MpProductService.calculateQuote` 完整计算定金。**测试环境验证后端字段完整**。 + +**前端 TODO**：小程序端检查是否正确解析/展示 `depositRatio` 和 `depositAmount` 两个字段。 + +--- + +## DDL 执行清单（生产部署前运维参考） + +| 脚本 | 库 | 必要性 | +|---|---|---| +| `sql/alter_scenic_spot_add_photography_guide.sql` | hl_resource_service | BUG 9 必须 | +| `sql/alter_product_route_info_add_map_mode.sql` | hl_product_service | BUG 10 必须 | +| `sql/alter_product_supplies_add_from_combo_id.sql` | hl_product_service | BUG 15 可选（审计用） | +| `sql/supplies_schema.sql`（新增 supplies_combo+item 两张表） | hl_resource_service | BUG 15 必须 | +| `hl-order-service-v2/sql/migrations/20260420_bug20_early_bird_multi_plan.sql` | hl_order_service_v2 | BUG 20 必须 | + +**部署顺序**：先 DDL → 再重启相关服务。 diff --git a/changelogs/2026-04/2026-04-20_early-bird-multi-plan.md b/changelogs/2026-04/2026-04-20_early-bird-multi-plan.md new file mode 100644 index 0000000..436338d --- /dev/null +++ b/changelogs/2026-04/2026-04-20_early-bird-multi-plan.md @@ -0,0 +1,145 @@ +# 早鸟优惠改造：产品 1:N 多方案 + 阶梯文案（BUG 20） + +**日期**：2026-04-20 +**PR**：#964 + hotfix #967 +**影响**：管理端早鸟优惠管理页 + 小程序产品详情页 + 下单报价 + +--- + +## 业务变化 + +### 1. 一个产品可绑定多个早鸟方案 + +**改造前**：产品 1:1 方案。管理端创建第 2 个绑定同一产品的方案报错「以下产品已绑定其他早鸟计划，不能重复绑定」。 + +**改造后**：产品 1:N。可以配阶梯： +- 2 人打 9 折 (`minPeople=2, maxPeople=2, discountType=PERCENT, discountPercent=90`) +- 3-5 人打 85 折 (`minPeople=3, maxPeople=5, discountType=PERCENT, discountPercent=85`) +- 6 人及以上打 8 折 (`minPeople=6, maxPeople=null, discountType=PERCENT, discountPercent=80`) + +报价时后端按订单人数自动匹配最优方案，落 `order_discount` 表。 + +### 2. 优惠类型扩展（3 种） + +`discount_type` 字段新增： + +| 值 | 含义 | 示例 | 需填字段 | +|---|---|---|---| +| `AMOUNT_TOTAL`（**默认**） | 整单立减 | 整单减 500 元 | `discountAmount` | +| `AMOUNT_PER_PERSON` | 每人立减 | 每人减 100 元 | `discountAmount` | +| `PERCENT` | 按比例打折 | 8 折 | `discountPercent` (0-100) | + +**⚠️ 重要：老数据默认为 `AMOUNT_TOTAL`**（历史上运营侧约定 `discountAmount=500` 即整单立减 500，所以迁移时存量数据全部回正为 `AMOUNT_TOTAL`）。 + +--- + +## 接口变化 + +### 1. 创建/更新方案（兼容老调用，新字段可选） + +**`POST /admin/order/early-bird`** +**`PUT /admin/order/early-bird/{planId}`** + +`EarlyBirdPlanSaveReqVO` 新增字段： + +```ts +{ + "planName": "阶梯档 3-5 人 85 折", + "startDate": "2026-04-01", + "endDate": "2026-12-31", + "enabled": true, + "productIds": [123456], + + // 老字段 + "minPeople": 3, + "discountAmount": 0, // AMOUNT_TOTAL/PER_PERSON 必填；PERCENT 可为 null + + // 新字段 + "maxPeople": 5, // NEW 最高人数(含)，不传=不限 + "discountType": "PERCENT", // NEW 默认 AMOUNT_TOTAL + "discountPercent": 85, // NEW PERCENT 时必填 (0 totalPeople >= l.minPeople && (l.maxPeople == null || totalPeople <= l.maxPeople)) + ``` +2. 匹配到方案时，提示文案可参考：`"您当前 N 人，命中 '${peopleRangeText} ${discountText}'"` +3. 可顺带提示"更优档位"：若 `ladder` 里有 `minPeople > totalPeople` 且折扣更大的，提示"满 X 人可享 Y" + +--- + +## 兼容性 + +- 老数据：全部默认 `discount_type=AMOUNT_TOTAL`，行为不变（整单立减） +- 老接口：`EarlyBirdPlanSaveReqVO` 新字段全部可选，旧版管理端提交不传也可 +- 老订单：已支付订单不回溯，`order_discount` 持久化的 `discount_amount` 不变 +- 废弃但保留：`earlyBirdText/earlyBirdPlanName/earlyBirdDiscount` 三个老字段继续下发（值按新逻辑计算），下个大版本下架 diff --git a/changelogs/2026-04/2026-04-20_product-map-amap-auto.md b/changelogs/2026-04/2026-04-20_product-map-amap-auto.md new file mode 100644 index 0000000..2d54610 --- /dev/null +++ b/changelogs/2026-04/2026-04-20_product-map-amap-auto.md @@ -0,0 +1,141 @@ +# 产品地图支持高德自动生成（BUG 10） + +**日期**：2026-04-20 +**PR**：#962 +**影响**：管理端产品编辑 Step3（路线地图）+ 小程序产品详情页 + +--- + +## 业务变化 + +运营反馈：定制路线没人有时间做线路图。期望一键用高德自动生成路径图。 + +**能力**：产品地图新增 3 模式，互斥： + +| mapMode | 含义 | route_map_url | +|---|---|---| +| `UPLOAD`（默认，老数据行为） | 手动上传图片 | 前端上传后的 OSS URL | +| `AMOUNT_AUTO` | 高德根据行程坐标自动生成 | 后端生成、上传后的 OSS URL | +| `NONE` | 隐藏该模块（小程序不展示） | 可保留或清空 | + +--- + +## 新增接口 + +### 1. `POST /admin/product/item/{id}/map/generate-by-amap` + +**一键触发**：后端取产品行程所有坐标（首天 `gatherPlace.center` → 每天 SCENIC/ACTIVITY/HOTEL 节点 → 末天 `dismissalPlace.center`），调高德静态地图 API，下载 PNG 后落 OSS，写回 `routeMapUrl` + `mapMode=AMAP_AUTO`。 + +**请求**（全部可选，均有默认值）： +```ts +{ + "size": "750*500", // 可选，默认 750*500 + "scale": 2 // 可选，默认 2（高清） +} +``` + +**响应**： +```ts +{ + "mapUrl": "https://oss.../product-route-map/....png", + "mapMode": "AMAP_AUTO", + "pointCount": 8, + "generatedAt": "2026-04-20T12:34:56" +} +``` + +**异常场景**： +- 坐标 < 2 个 → 400 `行程坐标不足，无法生成地图，请先完善行程` +- 高德返回非图片 → 400 `高德地图生成失败: <错误详情>` +- OSS 上传失败 → 500 +- 幂等：10 秒内重复调用会被拦截（`@Idempotent(10)`） + +### 2. `PUT /admin/product/item/{id}/map/mode` + +**切换地图模式**。 + +**请求**： +```ts +{ + "mapMode": "NONE", // @Pattern: NONE|AMAP_AUTO|UPLOAD + "clearMapUrl": false // 可选，true 时同时清空 routeMapUrl +} +``` + +**响应**：`{"code":200,"message":"地图模式切换成功"}` + +### 3. 老接口 `PUT /admin/product/item/{id}/route` 扩展 + +`ProductRouteSaveReqVO` 新增： +```ts +{ + "routeMapUrl": "...", + "mapMode": "UPLOAD" // NEW 可选，前端手动上传后可一并传 UPLOAD +} +``` + +手动上传流程不变：前端走现有 `/admin/file/upload/token` 拿预签名 URL → 上传 OSS → 回填 `routeMapUrl`，顺带把 `mapMode` 设为 `UPLOAD`。 + +--- + +## 小程序详情页字段扩展 + +`MpProductDetailRespVO` 新增： +```ts +{ + "routeMapUrl": "...", + "mapMode": "UPLOAD" // NEW NONE/AMAP_AUTO/UPLOAD +} +``` + +**管理端详情 VO `ProductDetailRespVO.RouteInfoVO`** 新增 3 字段： +```ts +{ + "mapMode": "AMAP_AUTO", + "mapGeneratedAt": "2026-04-20T12:34:56", + "mapAmapSnapshot": { // 高德生成快照，用于展示"最近生成时间" + "points": [...], + "size": "750*500", + "scale": 2, + "generatedAt": "..." + } +} +``` + +**Internal VO**（供订单服务 / mp 聚合服务 Feign 使用）也同步加了 `mapMode`：`InternalProductDetailVO.RouteInfoVO`、`InternalMpCustomProductDetailVO`、`MpProductDetailInternalVO`。 + +--- + +## 前端 TODO + +### 管理端产品编辑 Step3 +1. "路线地图"模块顶部加 **3 选 1 切换**： + - 🙈 隐藏（`NONE`）→ 下方模块折叠 + - 🗺️ 高德自动生成（`AMAP_AUTO`）→ 显示"用高德生成"按钮 + - 📤 手动上传（`UPLOAD`）→ 显示上传组件 +2. 切换模式调 `PUT /map/mode` +3. "用高德生成"按钮调 `POST /map/generate-by-amap`，成功后回显 URL + "最近生成于 X" 提示 +4. 手动上传提示文案：**建议图片 ≤ 2MB，尺寸 4:3 或 3:2，格式 jpg/png**（后端目前不强校验，靠前端提示） +5. 编辑页可显示"行程已更新，建议重新生成地图"（若 `mapGeneratedAt < product.updateTime`） + +### 小程序产品详情页 +1. 读 `mapMode` 判断： + - `NONE` → 不渲染地图模块 + - `AMAP_AUTO` / `UPLOAD` → 渲染 `routeMapUrl` +2. 支持 `routeMapUrl` 为空时兜底隐藏 + +--- + +## 部署前置（已在测试环境完成，生产部署前运维注意） + +- [ ] Nacos `hl-product-service-v2-dev.yml` / `-prod.yml` 需配置 `amap.web-service-key`（与现有 AmapDrivingService 共用同一个 key） +- [ ] OSS 存储类 `product-route-map` groupKey 权限放通 +- [ ] 先 DDL 后重启服务（`sql/alter_product_route_info_add_map_mode.sql`） + +--- + +## 兼容性 + +- 老数据：`product_route_info.map_mode` 默认 `UPLOAD`，已有图片保留，小程序端展示不变 +- 老接口：`ProductRouteSaveReqVO.mapMode` 可选，不传走原路径 +- 老前端：不读 `mapMode` 也能工作（`routeMapUrl` 字段语义未变） diff --git a/changelogs/2026-04/2026-04-20_supplies-combo.md b/changelogs/2026-04/2026-04-20_supplies-combo.md new file mode 100644 index 0000000..0066b15 --- /dev/null +++ b/changelogs/2026-04/2026-04-20_supplies-combo.md @@ -0,0 +1,145 @@ +# 备品组合功能（BUG 15） + +**日期**：2026-04-20 +**PR**：#963 + gateway 路由 hotfix #966 +**影响**：管理端备品管理（新菜单）+ 产品编辑 Step3 + +--- + +## 业务变化 + +运营反馈备品单选操作繁琐，常用备品组合（如"亲子研学基础包"=N 个备品打包）每次新建产品都要重复选。 + +**改造**：支持"备品组合"实体。一个组合 = N 个备品。产品编辑时可引用组合 ID，后端保存时自动展开合并到 supplies。 + +**展开规则**：同 `suppliesResourceId` 的，**前端手工项优先**（手工传 quantity/unitPrice 覆盖组合项）。自定义项（`suppliesResourceId=null`）不参与去重全保留。 + +--- + +## 新增接口：`/admin/supplies-combo/*` + +| Method | Path | 说明 | 注解 | +|---|---|---|---| +| POST | `/admin/supplies-combo` | 创建组合 | @Idempotent(5s) | +| PUT | `/admin/supplies-combo/{comboId}` | 编辑（主信息+明细整体替换） | @Lock4j | +| DELETE | `/admin/supplies-combo/{comboId}` | 软删 | @Lock4j | +| GET | `/admin/supplies-combo/page?pageNum=1&pageSize=10&name=xx&status=ENABLED` | 分页 | — | +| GET | `/admin/supplies-combo/{comboId}` | 详情（含 items 展开） | — | +| GET | `/admin/supplies-combo/enabled` | 下拉框（List，不分页，仅 ENABLED） | — | +| PUT | `/admin/supplies-combo/{comboId}/toggle-status` | 启用/禁用切换 | @Lock4j | + +### 创建/编辑请求 VO + +```ts +{ + "name": "亲子研学基础包", // @NotBlank, @Size(max=128) + "description": "适用 3-8 岁儿童", // @Size(max=512) + "status": "ENABLED", // ENABLED/DISABLED + "sortOrder": 0, + "items": [ // @NotEmpty, 1-50 个 + { "suppliesId": 123, "quantity": 2, "sortOrder": 0 }, + { "suppliesId": 456, "quantity": 1, "sortOrder": 1 } + ] +} +``` + +校验： +- `items.suppliesId` 去重（同组合不能重复加） +- 每个 `suppliesId` 必须存在于 `supplies_item` 表且 `status=1`（启用中的备品） + +### 响应 VO（详情） + +```ts +{ + "comboId": "2046079787104866306", + "name": "亲子研学基础包", + "description": "...", + "status": "ENABLED", + "sortOrder": 0, + "itemCount": 2, // 明细数量（列表也有） + "items": [ // 详情才返回，列表为 null + { + "id": "1001", "suppliesId": "123", "quantity": 2, "sortOrder": 0, + "suppliesName": "睡袋", // 从 supplies_item 回填 + "categoryCode": "OUTDOOR", + "billingType": "PER_PERSON", + "basePrice": 50.00 + }, + ... + ], + "createdBy": 1, "createdAt": "...", "updatedAt": "..." +} +``` + +### 下拉 VO（enabled） + +```ts +[ + { "comboId": "123", "name": "亲子研学基础包", "itemCount": 5 }, + { "comboId": "456", "name": "摄影出行包", "itemCount": 3 } +] +``` + +--- + +## 产品 Step3 保存扩展 + +### `PUT /admin/product/item/{id}/route` 请求 VO + +`ProductRouteSaveReqVO` 新增： + +```ts +{ + // 老字段 + "supplies": [ + { "suppliesResourceId": 123, "suppliesName": "睡袋", "quantity": 2, ... } + ], + + // 新字段 + "supplyComboIds": [789, 790] // NEW 可选，引用的备品组合 ID 列表 +} +``` + +**后端展开逻辑**（前端无感）： +1. 读 `supplyComboIds` 调内部 Feign 批量查组合展开 +2. 合并到 `supplies`：同 `suppliesResourceId` 手工优先（保留前端 quantity/unitPrice） +3. 自定义项（`suppliesResourceId=null`）不参与去重 +4. 展开项会被打上 `fromComboId`（DB 层面审计用） + +`SuppliesItem` 内部类新增字段（前端无需传，后端审计）： + +```ts +{ + ... + "fromComboId": null // NEW 来源组合ID，NULL=单品，非空=组合展开 +} +``` + +--- + +## 前端 TODO + +### 1. 原生 BUG 排查 +运营反馈"备品栏点击后选项框一直存在、单选很麻烦"。推断是产品编辑 Step3 `SuppliesPicker` 组件的下拉关闭逻辑问题，请前端同学排查。 + +### 2. 新菜单：备品组合管理 +在"备品管理"菜单同组新建"备品组合管理"： +- 列表页：分页 + 名称搜索 + 启用状态筛选 +- 新建/编辑：表单含名称/描述/状态/排序 + 备品多选 + 每个备品的数量 +- 启停按钮 +- 删除按钮（软删） + +### 3. 产品编辑 Step3 增强 +- 备品区块加"从组合选择"按钮 +- 点击后弹出下拉选组合（调 `/admin/supplies-combo/enabled`） +- 用户选中后把 `comboId` 追加到 `supplyComboIds` 字段 +- 保存时和 `supplies` 一起提交 +- 可视化：展开后的备品列表（后端返回的）可以标出"来自组合"徽标（读 `fromComboId`） + +--- + +## 兼容性 + +- 老数据：产品表 `product_supplies.from_combo_id` 默认 NULL +- 老产品保存（前端不传 `supplyComboIds`）：行为零变化 +- 老接口：`ProductRouteSaveReqVO.supplies` 字段保留不动