` → 空行 / `` → `**` / `` → `- ` / `` → 换行 等 -- 命中前 **8709 处** → 命中后 **57 处**(全部字符串字面量,如 AuthController/FileService 返回 HTML 模板,必须保留) -- **0 处在注释里**(grep -v 字符串验证) -- 改动 **1589 文件**,**+8764 -8764 完全对称**(纯字符替换,业务代码 0 改动,字节码不变) -- mvn compile 24 模块全绿(javadoc 严格检查通过) -- mvn test 7629 测试,17 失败全部 baseline 与本工单无关(ArchUnit / OrderDetailIntegrationTest H2 schema) - ---- - -## 二、累计成果(Round 1 + 2 + 3 + Backlog R4) - -| 维度 | R1 | R2 | R3 | **R4 Backlog** | 累计 | -|------|-----|-----|-----|---------------|------| -| 工单 | #2841-#2844 | #2849 | #2851 | **#2852/#2854/#2855/#2856/#2857** | **11 张** | -| PR | #2845-#2848 | #2850 | #2853 | **#2858-#2862** | **11 张** | -| 净行数 | -1359 | +311 | -130 | **+0(HTML 0)/+839(其他 4)** | ~净 **-340 行** | -| HOUSE 评分 | C+ → A- | A- | A | **A**(无 HOUSE 改动) | C+ → **A** | -| 整体评分 | A- | A | A+ | **A+**(纪律完结) | **A+** | - ---- - -## 三、测试服验证 - -| 服务 | 部署 commit | uptime | 验证 | -|------|------------|--------|------| -| hl-user-service | dev-v3 含 5 PR | 待部署 | 待验 | -| hl-product-service-v2 | dev-v3 含 5 PR | 待部署 | 待验 | -| hl-order-service-v2 | dev-v3 含 5 PR | 待部署 | 待验 | -| hl-order-service-v3 | dev-v3 含 5 PR | 待部署(SSH restart) | 待验 | -| hl-fleet-service | dev-v3 含 5 PR | 待部署 | 待验 | -| hl-mp-service | dev-v3 含 5 PR | 待部署 | 待验 | - -**Round 3 QA 全流程报告**:9 链路全 PASS / 0 BLOCKER / 0 WARN(dev-v3 b352b3036 测试,本批 5 PR 是纯重构,QA 结果同等可信) - ---- - -## 四、留尾 backlog(独立后续工单,**本轮明确不做**) - -- AdminUserService 红线 5 三期(剩余跨聚合 Mapper,如有) -- MpTripDetailVO Object → List 真实数据回归 → /@qa 工单 -- HOUSE FLEET vehicle_plan Feign 接通后补 DRIVER 通知三件套 -- MaterialCategory ↔ Permission 双 @Lazy 抽 PermissionGate -- EquipmentTemplateService ↔ ProductLineService 双 @Lazy 抽 ProductEquipmentBindingService -- 720000/798000 段位上移 CommonErrorCode -- Long ID @JsonSerialize Mixin 全局 - ---- - -## 五、关联 - -- 工单: #2852 / #2854 / #2855 / #2856 / #2857(全部 closed) -- PR: #2858 / #2859 / #2860 / #2861 / #2862(全部 squash merged) -- Round 4(backlog 集中清理)来源: 用户 5 月 22 日"继续任务"清单 diff --git a/changelogs-v2/2026-05/22_2863-2865_QA-D+QA-E-bugs_PR2864-2866.md b/changelogs-v2/2026-05/22_2863-2865_QA-D+QA-E-bugs_PR2864-2866.md deleted file mode 100644 index 1c9b12b..0000000 --- a/changelogs-v2/2026-05/22_2863-2865_QA-D+QA-E-bugs_PR2864-2866.md +++ /dev/null @@ -1,146 +0,0 @@ -# QA-D 文档驱动 + QA-E 字段反查发现 4 个 P0/P1 真实 bug 修复 - -> **服务**: hl-gateway + hl-order-service-v3 -> **PR**: #2864 / #2866 -> **Issue**: #2863 / #2865 -> **日期**: 2026-05-22 -> **影响**: **5 个原本经网关 404 的 v3 接口现在通了** + **list/detail 字段静默不一致 2 bug 修复** - ---- - -## ⚠️ 关键变化(前端必读) - -### 1. 🔴 订单列表 `tags` 字段类型变更(breaking change,**前端必须同步改 hl-ui**) - -**之前**:`tags` = `string[]` 如 `['VIP', '高净值']` -**之后**:`tags` = `Array<{name, type, color}>` 富对象数组(与 detail 端 `main.tags` 完全一致) - -**影响**:`/v3/admin/order` 列表 list[].tags 类型变更。**前端用 `tags.join(',')` 字符串操作会 NPE**,必须改为 `tags.map(t => t.name).join(',')`。 - -**示例**: -```js -// 之前 -order.tags // ['VIP', '高净值'] -order.tags[0] // 'VIP' - -// 之后 -order.tags // [{name: 'VIP', type: 'level', color: '#FF0000'}, ...] -order.tags[0].name // 'VIP' -order.tags[0].color // 用于显示标签底色 -``` - -### 2. 🟡 订单详情 `main.orderNo` + `main.teamNo` 字段新增 - -**之前**:`/v3/admin/order/{id}` detail.main 只有 `displayOrderNo`,无 `orderNo` 和 `teamNo` -**之后**:detail.main 同时返 `orderNo` + `teamNo` + `displayOrderNo` 三个字段 - -**影响**:前端可从详情页直接拿原始 `orderNo` 用于搜索/精确比对/退款关联/合同关联,不需要反解 `displayOrderNo`。 - -**何时出现差异**:成团后 `displayOrderNo = "{orderNo}-T{teamNo}"`,之前前端从详情页拿不到原始 orderNo;改后两个字段都有。 - -### 3. 🟢 5 个原本经网关 404 的 v3 接口现在通了 - -**之前**:这 5 个 admin/internal 接口经网关访问 100% 404(gateway 缺路由),前端从未能调过 -**之后**:网关补路由后,接口可正常调用(401 / 200 等正常响应) - -| 接口前缀 | Controller | -|----------|-----------| -| `/v3/admin/complaint/**` | AdminComplaintController | -| `/v3/admin/review/**` | AdminReviewController | -| `/v3/internal/review/**` | InternalReviewController | -| `/v3/internal/mp/review/**` | InternalMpReviewController | -| `/v3/internal/house/**` | HouseInternalAssignmentController | - -### 4. 🟡 `/admin/order/{id}/status-log` 改为 `/v3/admin/order/{id}/status-log` - -**之前**:`AdminOrderStatusLogController` `@RequestMapping("/admin/order")` 没 v3 前缀,被 v2 路由抢截 100% 404 -**之后**:改为 `/v3/admin/order`,与 v3 命名规范一致 - -**影响**:前端如果调过 `/admin/order/{id}/status-log` 会 404(原本也 404,没人调过),改后用 `/v3/admin/order/{id}/status-log`。 - ---- - -## 一、改动概览 - -### PR #2864 — 修 gateway 6 路由(Closes #2863) -- gateway `application.yml` line 205 `order-service-v3` 路由 Path 末尾追加 5 个 path -- `AdminOrderStatusLogController` `@RequestMapping("/admin/order")` → `/v3/admin/order` -- `AdminOrderStatusLogControllerTest` 3 处 mockMvc 路径同步改 `/v3` 前缀 -- 3 文件 +6 -6 lines -- 测试:GatewayRouteAuditTest 1/1 + AdminOrderStatusLogControllerTest 3/3 全绿 - -### PR #2866 — 修 2 个静默字段 bug(Closes #2865) -- BUG-1: `OrderMainVO` 补 `orderNo` + `teamNo` 字段,Converter 同步映射 -- BUG-2: list `tags` 类型 `List` → `List` 富对象(复用 detail 端 TagVO) -- `OrderInfoConverter.toTagVO` 提升 public static,list/detail 共用映射器 -- `OrderService.listOrders` 批量聚合 `Map>` 去 N+1 -- 6 文件 +179 -9 lines -- 新增 5 单测(OrderInfoConverterTest 3 + OrderServiceTest 2) -- 测试:113 直接相关 0 failures(89 service + 24 converter) - ---- - -## 二、QA 测试覆盖说明 - -本次 4 个 QA agent 并行覆盖 dev-v3 近 5 天 wx 提交全量: - -| Agent | 范围 | 结果 | -|-------|------|------| -| **QA-A** HOUSE 模块全量 | 46 测试点 | 42 PASS / 4 WARN(数据稀疏)/ 0 FAIL / 0 BLOCKER | -| **QA-B** 订单/traveler/agency/合同/tag-library | 53 项 | 51 PASS / 2 WARN(doc-vs-code 错误码)/ 0 BLOCKER | -| **QA-C** 通知/字典/mp/fleet | 40 URL | 全 PASS / 0 BLOCKER | -| **QA-D** 文档驱动业务流端到端 | 8 业务链 + 4 反例 + 6 规则 | 找出 **2 个 P0 BLOCKER**(gateway 路由 5 缺 + 1 冲突) | -| **QA-E** 字段语义反查(API cross-check + DB SELECT) | 10 对接口比对 | 找出 **2 个真实静默 bug**(tags shape / orderNo 丢失) | - ---- - -## 三、测试服验证 - -| 服务 | 部署 commit | uptime | 验证 | -|------|------------|--------|------| -| hl-gateway | dev-v3 含 #2864 | 部署完毕 | 6 路径 HTTP 200 通(无 404) | -| hl-order-service-v3 | dev-v3 含 #2864+#2866 | 部署完毕 | detail.main.orderNo + list[0].tags 富对象待 mmg 复测 | - ---- - -## 四、5 天 wx 提交累计成果(全部 PR 总览) - -| Round | 工单 | PR | 主题 | 净行数 | -|-------|------|-----|------|--------| -| R1 review | #2841-#2844 | #2845-#2848 | 反过度设计 + 简洁可读 | -1359 | -| R2 收尾 | #2849 | #2850 | 7 项可现做项 + Lock4j 100503 | +311 | -| R3 收尾 | #2851 | #2853 | TokenService 灰度 + PiiMaskUtil 三合一 + 小童 | -130 | -| R4 Backlog | #2852/#2854/#2855/#2856/#2857 | #2858-#2862 | HTML 清零 1589 文件 + BFF Facade + 红线 5 + MoneyUtil + Service+Impl | 净 -340 | -| **QA 真测发现** | **#2863/#2865** | **#2864/#2866** | **gateway 6 路由 + list/detail 2 静默 bug** | **+185 -15** | -| **合计** | **13 工单** | **13 PR** | | **净 -1348 行** | - -整体评分:**A+ 维持**(QA 真测 4+1 agent 全覆盖,5 个静默 bug 已修)。 - ---- - -## 五、hotfix #2881(回滚 PR #2864 引入的回归) - -QA 真测验证 PR #2864 时发现 `/v3/admin/order/{id}/status-log` 返 500 Ambiguous handler。PR #2864 误把 wx 故意写的 `AdminOrderStatusLogController @RequestMapping("/admin/order")`(被 v2 抢截 404,设计上的"隐藏入口",PRP § 9 R13)改成 `/v3/admin/order`,反而与 OrderController 早就存在的同 URL 端点撞冲突。 - -**hotfix PR #2881 (#2880)**: -- AdminOrderStatusLogController 路径回滚 `/v3/admin/order` → `/admin/order`(故意 404 设计) -- AdminOrderStatusLogControllerTest 3 处 mockMvc 同步回滚 -- javadoc 加大量警告注释 + 历史教训("严禁改 v3 前缀,会与 OrderController 撞 URL") - -**保留 PR #2864 其他改动**:gateway 5 路由追加(complaint/review/internal-review/internal-mp-review/internal-house)是真 bug 修复,保留。 - -**最终验证**(部署后): -- `/v3/admin/order/{id}/status-log` code=200,真返 `List` 1 条(occurredAt/operator/action/fromStatus/toStatus/amount 6 字段) -- `/admin/order/{id}/status-log` code=404 维持设计 - -## 六、关联 - -- 工单: #2863 / #2865 / #2880(全部 closed) -- PR: #2864 / #2866 / #2881(全部 squash merged) -- QA 报告: - - `.tmp/qa-house-report.txt`(QA-A 46 项) - - `.tmp/qa-ord-report.txt`(QA-B 53 项) - - `.tmp/qa-msg-report.txt`(QA-C 40 项) - - `.tmp/qa-doc-chain-report.txt`(QA-D 8 业务链) - - `.tmp/qa-cross-check-report.txt`(QA-E 10 字段对比 + DB 反查) -- memory 升级:P0 #16(新 admin Controller 必同步改 gateway 路由)第 5 次复发,强化 reminder diff --git a/changelogs-v2/2026-05/22_2867-2868_订单详情枚举统一+service-standard修复-修改接口-管理后台.md b/changelogs-v2/2026-05/22_2867-2868_订单详情枚举统一+service-standard修复-修改接口-管理后台.md deleted file mode 100644 index 66e7aa5..0000000 --- a/changelogs-v2/2026-05/22_2867-2868_订单详情枚举统一+service-standard修复-修改接口-管理后台.md +++ /dev/null @@ -1,298 +0,0 @@ -# [修改接口·管理后台] 订单详情枚举统一 + service-standard 修复 (#2867 #2868) - -> **PR**: #2869 #2874 | **服务**: hl-order-service-v3 | **更新时间**: 2026-05-22 - -## 1. 接口背景 - -本次修复合并两个 PR，均针对订单详情页管理后台接口的静默 bug： - -- **PR #2869（Issue #2868）枚举统一 + null 兑底**：contractStatus / insuranceStatus 两个字段历史上枚举値定义不完整（少了中间过渡态和 NONE 初始态），且在订单还未进入合同/保险流程时后端直接返回 null，前端字典无法匹配导致显示空白或"未知"。本次统一枚举値集并将 null 兑底为 "NONE"。 - -- **PR #2874（Issue #2867）service-standard Tab 修复**：hasServiceStandard 字段原来只判断快照记录是否存在（行存在即返回 true），未校验反序列化是否成功、itinerary 是否非空，导致前端收到 hasServiceStandard=true 后调 GET /service-standard 接口却收到 data=null 的矛盾。根因是快照 itinerary 字段类型 List 与源头 List 不匹配，反序列化失败被静默吞掉。 - -## 2. 变更清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 订单详情 | GET | `/v3/admin/order/{id}` | 修改接口 | contractStatus/insuranceStatus 枚举统一；hasServiceStandard 判定逻辑修复 | -| 2 | 合同&保险 Tab | GET | `/v3/admin/order/{id}/contract-insurance` | 修改接口 | contractStatus/insuranceStatus 枚举统一，null 兑底为 NONE | -| 3 | 服务标准 Tab | GET | `/v3/admin/order/{id}/service-standard` | 修改接口（行为修复） | 原来 data 永远 null；现在能正常返回完整数据 | - -## 3. 接口详情 - -### 3.1 GET /v3/admin/order/{id} —— 订单详情 - -- **使用场景**：管理后台订单详情页首次加载，获取订单主信息 -- **认证**：需要管理后台 JWT（Bearer token），role=ADMIN -- **幂等性**：是（只读） -- **限流**：无 - -**本次变更字段**： -- `data.main.contractStatus`：枚举値扩展（4→6 値），null → `"NONE"` -- `data.main.insuranceStatus`：枚举値扩展（4→5 値），null → `"NONE"` -- `data.main.hasServiceStandard`：判定逻辑修复（见 §9） - -### 3.2 GET /v3/admin/order/{id}/contract-insurance —— 合同&保险 Tab - -- **使用场景**：管理后台订单详情页切换到 "合同&保险" Tab 时调用 -- **认证**：需要管理后台 JWT（Bearer token），role=ADMIN -- **幂等性**：是（只读） -- **限流**：无 - -**本次变更字段**： -- `data.contract.contractStatus`：枚举値扩展（4→6 値），null → `"NONE"` -- `data.insurance.insuranceStatus`：枚举値扩展（4→5 値），null → `"NONE"` - -### 3.3 GET /v3/admin/order/{id}/service-standard —— 服务标准 Tab - -- **使用场景**：管理后台订单详情页切换到 "服务标准" Tab 时调用；应在 `hasServiceStandard=true` 时才调此接口 -- **认证**：需要管理后台 JWT（Bearer token），role=ADMIN -- **幂等性**：是（只读） -- **限流**：无 - -**本次变更**：行为修复。修复前 data 永远为 null；修复后在有效快照时返回完整结构。 - -## 4. 接口入参 - -### 4.1 路径参数 - -三个接口入参相同，无变化。 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `id` | Long（String） | 是 | 订单 ID（snowflake，JSON 传 String 防精度丢失） | - -### 4.2 请求体字段 - -三个接口均为 GET，无请求体。 - -## 5. 出参（响应） - -### 5.1 GET /v3/admin/order/{id} —— 变更字段 - -| 字段路径 | 类型 | 说明 | -|----------|------|------| -| `data.main.contractStatus` | String（枚举） | 合同状态，见 §6.1。**本次扩展枚举値 + null 兑底** | -| `data.main.insuranceStatus` | String（枚举） | 保险状态，见 §6.2。**本次扩展枚举値 + null 兑底** | -| `data.main.hasServiceStandard` | Boolean | 是否有服务标准快照。**本次修复判定逻辑** | - -### 5.2 GET /v3/admin/order/{id}/contract-insurance —— 变更字段 - -| 字段路径 | 类型 | 说明 | -|----------|------|------| -| `data.contract.contractStatus` | String（枚举） | 合同状态，见 §6.1。**本次扩展枚举値 + null 兑底** | -| `data.insurance.insuranceStatus` | String（枚举） | 保险状态，见 §6.2。**本次扩展枚举値 + null 兑底** | - -### 5.3 GET /v3/admin/order/{id}/service-standard —— ServiceStandardVO（完整） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `data.itinerary` | List | 行程列表，元素格式："Day{n} {title}"，如 "Day1 抵达成都"。**修复前恒为 null，修复后正常返回** | -| `data.notice` | String | 出行须知。可为 null | -| `data.refundPolicy` | String | 退款政策说明。可为 null | - -当订单无服务标准快照时（`hasServiceStandard=false`），整个 `data` 为 null。 - -## 6. 枚举 / 数据字典 - -### 6.1 contractStatus（合同状态） - -**所属字段**：`data.main.contractStatus`（OrderMainVO）、`data.contract.contractStatus`（ContractInsuranceVO）| **类型**：`String` - -| 値 | 中文 | 说明 | -|----|------|------| -| `NONE` | 无合同 | 订单尚未进入签约流程（修复前此状态返回 null） | -| `GENERATING` | 生成中 | 合同正在后台生成 | -| `GENERATED` | 已生成 | 合同已生成，待客户签署 | -| `SIGNED` | 已签署 | 客户已完成签署 | -| `VOIDED` | 已作废 | 合同已作废 | -| `RESIGNING` | 重签中 | 合同正在重新发起签署 | - -**修复前仅有4 値**：PENDING / GENERATED / SIGNED / VOIDED（PENDING 已废弃，NONE / GENERATING / RESIGNING 为本次新增枚举値） - -### 6.2 insuranceStatus（保险状态） - -**所属字段**：`data.main.insuranceStatus`（OrderMainVO）、`data.insurance.insuranceStatus`（ContractInsuranceVO）| **类型**：`String` - -| 値 | 中文 | 说明 | -|----|------|------| -| `NONE` | 无保险 | 订单尚未进入投保流程（修复前此状态返回 null） | -| `ISSUING` | 投保中 | 保险正在后台出单 | -| `ISSUED` | 已出单 | 保险已成功出单 | -| `CANCELLED` | 已取消 | 保险已取消 | -| `FAILED` | 出单失败 | 保险出单失败 | - -**修复前仅有4 値**：PENDING / ACTIVE / FAILED / CANCELLED（旧値已废弃重命名，全部替换为上表5 値） - -## 7. 错误码 - -本次修复无新增错误码。 - -| code | 含义 | 触发场景 | -|------|------|----------| -| `200` | 成功 | 正常响应 | -| `1000400` | 参数异常 | 路径参数 `id` 格式错误 | -| `1000404` | 订单不存在 | 指定 id 的订单不存在或已删除 | -| `1000403` | 无权限 | 非管理员 token 访问 | - -## 8. 示例 - -### 8.1 典型成功 —— 新建订单 contractStatus 返 NONE（修复前返 null） - -**请求**： - -``` -GET /v3/admin/order/1921234567890123456 -Authorization: Bearer -``` - -**响应**： - -```json -{ - "code": 200, - "data": { - "main": { - "orderId": "1921234567890123456", - "orderNo": "ORD20260522001", - "contractStatus": "NONE", - "insuranceStatus": "NONE", - "hasServiceStandard": false - } - }, - "message": "ok", - "success": true -} -``` - -> 修复前：contractStatus: null，insuranceStatus: null，前端字典无法匹配显示空白。 - -### 8.2 边界情况 —— service-standard 接口有快照时返完整数据（修复前永远 null） - -**请求**： - -``` -GET /v3/admin/order/1921234567890123456/service-standard -Authorization: Bearer -``` - -**响应（修复后）**： - -```json -{ - "code": 200, - "data": { - "itinerary": [ - "Day1 抵达成都，入住民宿", - "Day2 前往峨眉山景区", - "Day3 返程" - ], - "notice": "请携带身份证原件，到达后联系导游", - "refundPolicy": "出发7天以上全额退款，7天内收取50%手续费" - }, - "message": "ok", - "success": true -} -``` - -**响应（修复前）**： - -```json -{ - "code": 200, - "data": null, - "message": "ok", - "success": true -} -``` - -### 8.3 业务失败 —— hasServiceStandard=false 时 service-standard 返 data=null（正常行为） - -**场景说明**：订单未绑定产品行程快照，调 service-standard 接口返 data=null 是正常行为。 - -**请求**： - -``` -GET /v3/admin/order/1921111111111111111/service-standard -Authorization: Bearer -``` - -**响应**： - -```json -{ - "code": 200, - "data": null, - "message": "ok", - "success": true -} -``` - -## 9. 业务边界 - -**hasServiceStandard 判定逻辑（修复后）**： - -同时满足以下三个条件，`hasServiceStandard` 才返回 `true`： -1. 订单关联的产品行程快照记录存在 -2. 快照 JSON 反序列化成功（无类型错误） -3. 快照中 `itinerary` 字段非空（至少有1天行程） - -任意一个条件不满足，`hasServiceStandard` 返回 `false`，此时调 `GET /service-standard` 将返回 `data=null`。 - -**contractStatus / insuranceStatus 兑底规则**： -- 订单刚创建、尚未发起签约/投保时，两个字段返回 "NONE"（修复前返回 null） -- 字段値随后端状态机流转更新，不需要前端轮询，刷新页面即可获取最新値 - -## 10. 修改前后对比 - -### 10.1 字段级对比 - -| 字段 | 修复前 | 修复后 | -|------|--------|--------| -| `contractStatus`（初始态） | null | "NONE" | -| `contractStatus`（枚举集合） | PENDING / GENERATED / SIGNED / VOIDED（4 値，含PENDING已废弃） | NONE / GENERATING / GENERATED / SIGNED / VOIDED / RESIGNING（6 値） | -| `insuranceStatus`（初始态） | null | "NONE" | -| `insuranceStatus`（枚举集合） | PENDING / ACTIVE / FAILED / CANCELLED（4 値，均已废弃重命名） | NONE / ISSUING / ISSUED / CANCELLED / FAILED（5 値） | -| `hasServiceStandard` | 只判断快照行存在，partial 快照也返 true | 快照存在 + 反序列化成功 + itinerary 非空，三条件全满足才返 true | -| GET /service-standard data | 永远为 null（反序列化失败被吐） | 有效快照时返回完整 {itinerary, notice, refundPolicy} | - -### 10.2 行为级对比 - -| 行为 | 修复前 | 修复后 | -|------|--------|--------| -| 新建订单合同/保险状态 | 返回 null，前端字典无法匹配 | 返回 "NONE"，字典正常匹配显示"无合同"/"无保险" | -| hasServiceStandard=true 但 Tab 内容空 | 会出现（快照反序列化失败时） | 不再出现；hasServiceStandard=true 一定能拿到有效数据 | -| insuranceStatus 枚举 ACTIVE / PENDING | 后端可能返回这两个値 | 后端不再返回，统一替换为新枚举値集合 | - -## 11. 影响评估 / 回滚 - -### 11.1 影响评估 - -- **是否破坏向后兼容**：是（枚举値重命名）。旧字典如只有 PENDING / ACTIVE（保险）或 PENDING（合同）等旧値，遇到新値会显示 "未知"。 -- **前端是否必须同步上线**：建议同步更新枚举字典（§6.1 和 §6.2 完整値表）再上线；若前端能容忍旧値显示 "未知" 可先不同步。 - -### 11.2 回滚方案 - -- **回滚方式**：revert PR #2869 / PR #2874，重新打包部署 hl-order-service-v3 -- **回滚后影响**：contractStatus / insuranceStatus 恢复返回 null 和旧枚举値；service-standard Tab 恢复返回 null - -## 12. 注意事项 - -- **枚举字典必须更新**：旧前端字典仅有4 値/4 値（含已废弃的 PENDING / ACTIVE），遇到新枚举値（如 NONE / GENERATING / RESIGNING / ISSUING / ISSUED）会显示 "未知"。请按 §6.1 和 §6.2 完整値表更新本地枚举字典。 -- **旧枚举値已废弃**：contractStatus 的 PENDING、insuranceStatus 的 PENDING 和 ACTIVE 后端不再返回，前端字典保留无害但不会再出现。 -- **service-standard workaround 清理**：如果前端之前针对 hasServiceStandard=true 但 data=null 的矛盾做过兑底处理（如显示固定占位文案、屏蔽Tab），修复后可以移除该 workaround。 - -## 13. 关联 / 联系人 - -### 13.1 链接 - -- **Issue（枚举统一）**: [#2868](https://git.1814.love:8443/wx/HL/issues/2868) -- **Issue（service-standard 修复）**: [#2867](https://git.1814.love:8443/wx/HL/issues/2867) -- **PR（枚举统一）**: [#2869](https://git.1814.love:8443/wx/HL/pulls/2869) -- **PR（service-standard 修复）**: [#2874](https://git.1814.love:8443/wx/HL/pulls/2874) -- **Merge commit（枚举统一）**: [bb4c41969](https://git.1814.love:8443/wx/HL/commit/bb4c41969) -- **Merge commit（service-standard 修复）**: [442fdf089](https://git.1814.love:8443/wx/HL/commit/442fdf089) - -### 13.2 联系人 - -- **后端负责人**: @yst diff --git a/changelogs-v2/2026-05/22_2894-2896_R5-bugs_PR2900-2902.md b/changelogs-v2/2026-05/22_2894-2896_R5-bugs_PR2900-2902.md deleted file mode 100644 index f248889..0000000 --- a/changelogs-v2/2026-05/22_2894-2896_R5-bugs_PR2900-2902.md +++ /dev/null @@ -1,113 +0,0 @@ -# R5 真测发现 + 修复:PII 应急脱敏 + 配房 BLOCKER + 6 P1 - -> **服务**: hl-order-service-v3 -> **PR**: #2900 / #2901 / #2902 -> **Issue**: #2894 / #2895 / #2896 -> **日期**: 2026-05-22 -> **影响**: **🔴 前端 breaking change(traveler 字段改名)** + 配房链路恢复 + 订单详情补字段 + 金额格式统一 - ---- - -## ⚠️ 关键变化(前端 mmg 必读) - -### 1. 🔴 traveler VO 字段改名(breaking change,**前端必同步改 hl-ui**) - -| 旧字段 | 新字段 | 值格式 | -|--------|--------|--------| -| `idNo` | **`idCardMasked`** | `220***********1234`(17 字符变长星) | -| `phone` | **`phoneMasked`** | `138****2046`(11 字符固定星) | -| `emergencyPhone` | **`emergencyPhoneMasked`** | `139****5678` | - -**适用接口**: -- `GET /v3/admin/order/{id}/traveler/list` 列表 -- `GET /v3/admin/order/{id}` 详情 `overview.travelers` -- traveler 智能解析 dry-run 输出 - -**前端如有 `traveler.idNo` / `traveler.phone` 引用必须改为 `traveler.idCardMasked` / `traveler.phoneMasked`**。 - -### 2. 🟢 订单详情新增 transportPlans + itinerary 字段(BUG-3 修) - -`GET /v3/admin/order/{id}` 顶层 data 新增: -- `transportPlans: List`(大交通列表) -- `itinerary: OrderItineraryRespVO`(行程) - -**前端可直接用**(原本就缺,现在补上)。 - -### 3. 🟢 订单金额字段格式统一 2 位小数 - -之前 `totalAmount=3105.0`(1 位)/ `refundAmount=0.00`(2 位)不一致,**统一改为 2 位小数**: -- `OrderListItemVO` / `OrderMainVO`:5 字段(totalAmount/paidAmount/balanceAmount/depositAmount/singleRoomSurcharge)走 `OrderAmountUtil.to2()` -- Refund Converter 走 `MoneyUtil.formatYuan()` - -**前端如对 `3105.0` 字符串做精确匹配会出问题**,改用 `parseFloat` 或宽松匹配。 - -### 4. 🟢 5 个原本经网关 503/500 的 v3 接口现在通了 - -- `POST /v3/admin/order/hotel-requirements/{rid}/assignments`(原 JSON 500)→ **200** -- `GET /v3/admin/house/staff`(原 504)→ 3s 内返(Feign timeout 收紧 + fallback) -- `GET /v3/admin/contract/{id}`(原 500 BadSqlGrammarException)→ **200** - ---- - -## 一、3 PR 改动 - -### PR #2900 PII 应急脱敏(Closes #2894) -- traveler 3 字段改名(`*Masked` 后缀) + Converter 全 SensitiveDataUtil.maskXxx() 包装 -- TravelerSmartParseService.buildDryRunVO 同步脱敏 -- 6 新单测 + 红线 PII 不泄漏断言,128 traveler 测试 0 failure -- **后续独立工单**:DB TypeHandler 加密(order_traveler+fleet_driver 明文存储)+ audit_log 接入 - -### PR #2901 BLOCKER 修复(Closes #2895) -- BLOCKER-1 配房 500:删 `@JsonDeserialize(using = LongDeserializer)` 错误用法 → 用原生 Long -- BLOCKER-2 house/staff 504:houseStaffFeignClient 单独 connectTimeout=2s + readTimeout=3s,触发现有 fallback 返空 -- 5 新单测 29/29 全绿 -- **经验入 memory**:雪花 Long 字段禁 @JsonDeserialize(LongDeserializer) - -### PR #2902 6 P1(Closes #2896) -- P1-1 contract_status_log 缺 4 BaseDO 列 → V20260522_001.sql 补 -- P1-2 OrderDetailVO 补 transportPlans + itinerary + Service 聚合 -- P1-3 OrderAmountUtil.to2 统一 2 位小数 + RefundConverter 走 MoneyUtil -- P1-4 inquiry_message.dayNumber → V20260522_002.sql + DO + Service 真实写入 -- P1-5 INVENTORY_CHECK op_log operator_name → AdminContextUtil.getRealName 兜底 -- P1-6 HouseGrabServiceImpl 双写 house_claim_history(opType/fromUserId/toUserId/reason) -- 180 直接相关测试 0 failure - ---- - -## 二、QA R5 真测全量发现(5 agent 累计 22 bug) - -| Agent | 方法 | 发现 | -|-------|------|------| -| **R5-F HOUSE 深度** | 5 业务链端到端 + 11 DB 反查 + 2 真并发 | 2 BLOCKER + 3 P1(已修)| -| **R5-G 订单生命周期** | 5 业务链 + 12 DB 反查 + RateLimiter 实测 | 1 P0 + 3 P1 + 3 P2/P3(P0/P1 已修)| -| **R5-H 通知字典** | 6 业务链 + 7 DB 反查 | 全 PASS,环境性 504 已处理 | -| **R5-I fleet+tag+大交通** | 6 业务链 + 8 DB 反查 + 17 错误码命中 | 1 P0 + 1 mock(P0 应急已修)| - ---- - -## 三、测试服验证 - -| 服务 | commit | 状态 | -|------|--------|------| -| hl-gateway | dev-v3 含 #2900-2902 | 已部署 | -| hl-order-service-v3 | dev-v3 含 #2900-2902 + Flyway V20260522_001/002 | 已部署(双实例 8086+8186) | - ---- - -## 四、留尾(独立工单 backlog) - -- DB TypeHandler 加密迁移(order_traveler + fleet_driver phone/id_card 明文存储) -- audit_log 接入 admin path decrypt -- HouseModuleBoundaryTest ArchUnit 违规独立 PR 治理 -- TagLibraryIntegrationTest ApplicationContext 问题独立排查 -- user-service `/internal/user/admin/house-staff` 真实实装(H07 占位) -- `house_claim_history` 表 @Deprecated 标记,前端历史轨迹切 T9 op_log 后下线本期双写 - ---- - -## 五、关联 - -- 工单:#2894 / #2895 / #2896(全部 closed) -- PR:#2900 / #2901 / #2902(全部 squash merged) -- QA 报告:`.tmp/qa-r5{f,g,h,i}-*-report.txt`(共 4 份) -- memory 升级:`feedback_snowflake-long-no-jackson-deserializer.md`(雪花 Long 禁 @JsonDeserialize(LongDeserializer)) diff --git a/changelogs-v2/2026-05/23_2935_R6-bugs_PR2937.md b/changelogs-v2/2026-05/23_2935_R6-bugs_PR2937.md deleted file mode 100644 index 24cd07f..0000000 --- a/changelogs-v2/2026-05/23_2935_R6-bugs_PR2937.md +++ /dev/null @@ -1,65 +0,0 @@ -# R6 真测发现 + 修复:insurance 翻页 + refund review PARTIAL 静默错位 - -> **服务**: hl-order-service-v3 -> **PR**: #2937 -> **Issue**: #2935 -> **日期**: 2026-05-23 -> **影响**: 1 P0 + 1 P1 + 1 P2(其中 P2 是更深的静默业务错位 bug) - ---- - -## ⚠️ 关键变化(前端 mmg) - -### 1. 🔴 退款审批 PARTIAL **必传 approvedAmount**(behavior change) - -**之前**:`POST /v3/admin/refund/review {decision: "PARTIAL"}` 不传 `approvedAmount` → Service fallback 到 `calculatedAmount/paidAmount`,**PARTIAL 被静默当 APPROVED 全额处理**(语义错位 bug) -**之后**:必返 `code=530403 REFUND_REVIEW_PARTIAL_AMOUNT_REQUIRED "PARTIAL 审批必须传 approvedAmount"` - -**前端如果有 PARTIAL 审批漏传 approvedAmount 的场景必须补传**,否则会被 530403 拒绝。 - -### 2. 🟢 `/v3/admin/insurance/products` 翻页边界返 400 - -**之前**:`page=0` → 500 IndexOutOfBoundsException / `pageSize=10000` 不拒 -**之后**:`page=0` → 400 / `pageSize > 100` → 400(与其他 7/8 list 接口一致) - ---- - -## 改动 - -### P0+P1 R6L: AdminInsuranceController.listProducts 翻页校验缺失 -- 新建 `InsuranceProductListReqVO` 继承 `PageParam`(`page @Min(1)` + `pageSize @Min(1) @Max(100)`,含 `isOverseas` 字段) -- Controller 改 `@Valid InsuranceProductListReqVO req`,@PageParam 注解直接拦截非法 -- 与其余 7 接口风格一致 - -### P2 R6M: AdminRefundController.review PARTIAL 静默错位修复 -- **R6-M 报告误判为 NPE**,实际是更隐蔽的语义错位 bug: - - Service 层映射后枚举 APPROVE/REJECT 丢失 PARTIAL 信息 - - approvedAmount=null 时 fallback 到 calculatedAmount/paidAmount - - 实际行为:PARTIAL 被静默当 APPROVED 全额退款 — **业务静默 bug** -- 修:Controller 持有原 decision 枚举,前置校验 `decision=PARTIAL && approvedAmount=null` → 抛 `BusinessException(530403)` -- 错误码 530403 `REFUND_REVIEW_PARTIAL_AMOUNT_REQUIRED` 在 `OrderRefundErrorCode:127` 已存在(设计预留实现遗漏),复用 - -## 验证 - -- 50 直接相关测试 0 failure -- 3 新单测: - - `listProducts_pageNum_zero_returns400` - - `listProducts_pageSize_over100_returns400` - - `review_PARTIAL_without_approvedAmount_throws530403`(断言 `refundReviewService.review` `never()` 被调,Service 完全没接到错误数据) - -## R6 累计测试发现(4 agent) - -| Agent | 维度 | 结果 | -|-------|------|------| -| R6-J | 状态机异常 | 22 反例全走业务码 0 BUG + 3 UX 文案改进 | -| R6-K | 并发竞态 | 5 @Lock4j + 4 @Idempotent + 1 死锁实测 0 BUG(R5-G RateLimiter 5 阈值误判 → 实际 10)| -| R6-L | 翻页边界 | 8 接口 × 18 维度 = 144 点 84.7% 通过,1 P0 + 1 P1 | -| R6-M | ErrorCode | 22 类 ~265 总数 50+ 真触发 段位合规 100%,1 P2 | - -5 文件 +87 -8 + 1 新 VO。 - -## 关联 - -- 工单 #2935(closed) -- PR #2937(squash merged) -- R6 报告 `.tmp/qa-r6{j,k,l,m}-*-report.txt`(共 4 份) diff --git a/changelogs-v2/2026-05/23_2940_R7-error-response_PR2948.md b/changelogs-v2/2026-05/23_2940_R7-error-response_PR2948.md deleted file mode 100644 index d22f1e5..0000000 --- a/changelogs-v2/2026-05/23_2940_R7-error-response_PR2948.md +++ /dev/null @@ -1,121 +0,0 @@ -# R7 真测发现 + 修复:网关错误响应规范化(5 项 CRITICAL+HIGH) - -> **服务**: hl-gateway + hl-user-service + hl-common-core + hl-common-web(全模块共依赖) -> **PR**: #2948 -> **Issue**: #2940 -> **日期**: 2026-05-23 -> **影响**: **🔴 错误响应格式变更 + Result 新增 traceId 字段 + X-Trace-Id 响应头** - ---- - -## ⚠️ 关键变化(前端 mmg 必读) - -### 1. 🔴 不存在路径返 Result JSON,**不再返 HTML 静态页** - -**之前**:`https://web.test.1814.love:9443/nonexistent-foo` → 网关 fallback 漏到前端 vue 静态页(返完整 HTML),API 调用方 JSON.parse 爆 SyntaxError -**之后**:返 `{code: 404, message: "接口不存在: GET /nonexistent-foo", success: false, data: null, traceId: "xxx"}` - -**前端如果有 try/catch 期望 HTML 响应的代码必须改为 JSON 处理**。 - -### 2. 🟢 Result 类新增 `traceId` 字段(向后兼容) - -所有响应(成功 + 错误)的 `data` 字段同级新增 `traceId`: -```json -{ - "code": 200, - "message": "成功", - "data": {...}, - "success": true, - "traceId": "a1b2c3d4e5f6g7h8" // 新增,16 字符短 UUID -} -``` - -- 旧客户端不识别 traceId 字段不影响(忽略未知字段) -- 新客户端可记录 traceId 用于线上排查问题(给后端报错时附 traceId 加速定位) - -### 3. 🟢 错误响应必含 `X-Trace-Id` 响应头 - -``` -HTTP/1.1 200 OK -X-Trace-Id: a1b2c3d4e5f6g7h8 -Content-Type: application/json -``` - -前端可统一读取(axios interceptor 等)。 - -### 4. 🟡 鉴权错误响应规范化 - -**之前**:`Authorization` 缺失 → 网关返手拼 JSON `{code:401, message:"Missing or invalid Authorization header"}` 缺 `success` 字段 + 英文 -**之后**:返 4 字段全 + 中文 message: -```json -{ - "code": 401, - "message": "缺少有效的 Authorization 头", - "success": false, - "data": null, - "traceId": "..." -} -``` - -5 处中文化: -- "Missing or invalid Authorization header" → "缺少有效的 Authorization 头" -- "Invalid token" → "Token 无效" -- "Token expired or revoked" → "Token 已过期或被撤销" -- "Unknown token type" → "Token 类型未知" -- "请使用小程序端接口" 保留 - ---- - -## 改动概览 - -### 1) CRITICAL R7Q-B6 网关 catch-all -- 新建 `GlobalErrorWebExceptionHandler @Order(-2)` 优先于 Spring Boot 默认 `-1` -- NotFoundException → code=404 + 中文"接口不存在" -- 上游异常 → code=500/对应 status + 中文 - -### 2) HIGH R7Q-B1 JwtAuthFilter -- 注入 ObjectMapper + 抽 `writeErrorResponse(exchange, code, message)` 统一写出 -- 5 处 forbidden/unauthorized 改 `Result.error(code, message)`(自带 success=false) -- 5 处英文 message 中文化 - -### 3) HIGH R7Q-B5 TokenInterceptor -- 注入 ObjectMapper + `writeError(request, response, code, message)` 统一 -- 5 处 `response.getWriter().write("{...}")` 改 `objectMapper.writeValueAsString(Result.error(...))` - -### 4) HIGH R7Q-B2 NoHandlerFoundException 确认已生效 -- `hl-common-log/GlobalExceptionHandler.java:255` 已注册 -- `hl-common-web/HlMvcDefaultsEnvironmentPostProcessor` 已注 `spring.mvc.throw-exception-if-no-handler-found=true` + `spring.web.resources.add-mappings=false` - -### 5) HIGH R7Q-B9 X-Trace-Id 全链路 -- `Result.java` 新增 `traceId` 字段 -- `TraceIdFilter`(gateway,@Order(-200))无请求头时生成 16 字符短 UUID + 注入下游请求头 + 响应头 -- `TraceIdResponseFilter`(hl-common-web)后端服务读请求头 → MDC + 响应头,filter 结束清 MDC 防线程池串数据 -- JwtAuthFilter / TokenInterceptor / GlobalErrorWebExceptionHandler 错误响应同步注入 X-Trace-Id - ---- - -## R7 完整测试覆盖(4 agent) - -| Agent | 维度 | 发现 | -|-------|------|------| -| R7-N Swagger 三角 | 71 Controller / 360 端点 / 311 VO / 3095 字段 | 1 P0(#2880 设计不修)+ 4 P1 + 4 P2,47% 缺 @ApiOperation(留 backlog)| -| R7-O Long 精度 | 333 VO 文件 / 440 Long 字段 / 18+ 真测接口 | **0 BUG**(全局 NumberSerializer 完备)| -| R7-P 序列化 | 30+ 接口 4 维度 | 6 bug 全 v2 老代码(留 backlog)| -| R7-Q 错误响应 | 57 错误场景 | **1 CRITICAL + 4 HIGH + 3 MEDIUM + 1 LOW**(本工单修 5 项)| - -## 测试 - -20 新单测,5 模块 mvn test 全绿(common-core 484 + common-web 18 + common-log 68 + gateway 11 + user 2486)。 - -13 文件 +876 -32 lines。 - -## 留尾(独立 backlog,本工单不做) -- R7N 47% 端点缺 @ApiOperation(168/360) -- R7-P 6 v2 老代码 status/Boolean Integer 化 -- R7-Q MEDIUM 3 项:@Valid 缺字段名 / 415 兜底 500 / enum deserialize 吞异常 -- R7-Q LOW:6 条 ErrorCode 纯英文(ContractErrorCode 3 + SettlementErrorCode 3) - -## 关联 -- 工单 #2940(closed after PR merged) -- PR #2948(squash merged) -- R7 4 报告:`.tmp/qa-r7{n,o,p,q}-*-report.txt` diff --git a/changelogs-v2/2026-05/26_2988_v3精选评价source-sourceLabel对齐_PR3054.md b/changelogs-v2/2026-05/26_2988_v3精选评价source-sourceLabel对齐_PR3054.md deleted file mode 100644 index 838f16a..0000000 --- a/changelogs-v2/2026-05/26_2988_v3精选评价source-sourceLabel对齐_PR3054.md +++ /dev/null @@ -1,49 +0,0 @@ -# 二期 v3 精选评价补 source / sourceLabel(对齐一期 #2988) - -> **服务**: hl-order-service-v3 + hl-product-service-v2 -> **PR**: #3054(配套 dev→dev-v3 同步 #3050) -> **Issue**: #2988(一期同步到二期 v3) -> **日期**: 2026-05-26 -> **影响**: 🟢 二期 v3 环境精选评价新增填充评价来源字段(契约字段一期 #2988 已加,本次仅二期环境行为对齐,**向后兼容**) - ---- - -## ⚠️ 关键变化(前端 mmg 必读) - -### 二期 v3 环境:产品详情精选评价现返回「评价来源」 - -产品详情接口响应里 `reviewSummary.topReview` 节点下,现正确返回两个来源字段: - -```json -{ - "reviewSummary": { - "avgScore": 4.8, - "totalCount": 120, - "topReview": { - "reviewId": 123, - "nickname": "张三", - "content": "...", - "score": 5, - "source": "MINIPROGRAM", // 评价来源枚举 - "sourceLabel": "小程序" // 来源中文(字典 review_source) - } - } -} -``` - -- `source`:评价来源枚举 —— `MINIPROGRAM`=小程序 / `YOUZAN`=有赞(字典 `review_source`) -- `sourceLabel`:来源中文名,来自字典 `review_source` 的 `dict_label`(运维改字典即时生效,无需重启) - -### 行为说明 - -- **之前**:二期 v3 环境下这两字段恒为 `null`(v3 评价表无 source 列、链路未填充) -- **之后**:正常返回小程序/有赞来源 - -字段本身一期 #2988 早已加入并上线(一期环境已可用)。**前端若已按一期 #2988 接入了 source/sourceLabel,二期环境无需任何改动**,本次只是把二期 v3 的填充行为对齐到一期。 - ---- - -## 📌 备注 - -- 本次改动已合并 dev-v3(PR #3054),但**截至发稿尚未部署到测试服验证**(应需求方要求提前同步)。前端在二期测试环境实际联调前,请先确认 hl-order-service-v3 / hl-product-service-v2 已部署该版本。 -- 后端实现:v3 评价表补 `source` 列(独立库 hl_order_service_v3,V20260526_001)+ `sourceLabel` 复用字典动态获取,与一期口径一致。 diff --git a/changelogs-v2/2026-05/27_3090_HOUSE文档代码对齐-加急错误码+staff结构+分页_PR3096.md b/changelogs-v2/2026-05/27_3090_HOUSE文档代码对齐-加急错误码+staff结构+分页_PR3096.md deleted file mode 100644 index addf127..0000000 --- a/changelogs-v2/2026-05/27_3090_HOUSE文档代码对齐-加急错误码+staff结构+分页_PR3096.md +++ /dev/null @@ -1,44 +0,0 @@ -# 二期 v3 HOUSE 文档-代码对齐：加急错误码迁移 + staff 响应结构 + 分页一致性 - -> **服务**: hl-order-service-v3 -> **PR**: #3096 -> **Issue**: #3090 -> **日期**: 2026-05-27 -> **影响**: 🟡 加急(escalate)错误码值变更(前端错误码映射需同步) + 转单候选员工接口响应结构变更 + 分页行为修复(向后兼容) - ---- - -## ⚠️ 关键变化(前端 mmg 必读) - -### 1. 询房加急(escalate)4 个错误码迁移：`808280-808283` → `808815-808818` - -`POST /v3/admin/order/inquiry/{inquiryId}/escalate`(§3.6 加急/催办)相关的 4 个业务错误码，按 API 文档 §11.8 规定从 **808280-808283 段迁移到 808815-808818 段**。 - -- **message 中文文案不变**(动态返回)。 -- 前端**若按数字 code 做错误提示映射**：请把这 4 个码从 `8082xx` 更新为 `8088xx`。 -- 前端**若直接展示 `message` 字段**：无需任何改动。 - -### 2. 转单候选员工 staff 响应结构：裸数组 → `{list,total}` - -`GET /v3/admin/house/staff` 出参从裸数组改为带分页包装，对齐文档 §6.6： - -```jsonc -// 之前 -"data": [ {...}, {...} ] -// 之后 -"data": { "list": [ {...} ], "total": 12 } -``` - -前端请改读 `data.list` / `data.total`。 -（注：该接口数据源依赖 user-service H07 工单，当前返回空列表 `{list:[],total:0}`，**结构已就位**，待 H07 上线后有数据。） - -### 3. 「我的接单」分页一致性修复(行为修复，无需前端改动) - -`GET /v3/admin/order/grab-pool/my-claims/hotel` 带筛选条件(keyword / 出行日 等)时，`total` 与 `list` 现在保持一致。原实现是 SQL 分页后再内存过滤，导致带筛选时 total 偏大、跨页漏数据，现已下沉到 SQL。前端分页页数/条数将更准确。 - ---- - -## 📌 备注 - -- 已部署测试服(dev-v3)并经真 admin token API 验证：staff 返 `{list,total}` 结构正确、加急接口路径连通(返 HOUSE 错误码)。 -- 加急错误码 808815-818 的具体触发场景由后端单测覆盖，需真实询房数据触发；前端按上述 code 段更新映射即可。 diff --git a/changelogs-v2/2026-05/27_3101-3105_FLEET-H5网关路由+PII加密+契约补齐_PR3102-3104-3106.md b/changelogs-v2/2026-05/27_3101-3105_FLEET-H5网关路由+PII加密+契约补齐_PR3102-3104-3106.md deleted file mode 100644 index e789b5b..0000000 --- a/changelogs-v2/2026-05/27_3101-3105_FLEET-H5网关路由+PII加密+契约补齐_PR3102-3104-3106.md +++ /dev/null @@ -1,69 +0,0 @@ -# 二期 v3 FLEET 车务：H5 入职接口可达 + 司机 PII 加密 + 车辆/司机契约补齐 - -> **服务**: hl-fleet-service + hl-gateway -> **PR**: #3102 / #3104 / #3106 -> **Issue**: #3101 / #3103 / #3105 -> **日期**: 2026-05-27 -> **影响**: 🟡 H5 司机自助入职接口现可通过网关访问 + 车辆/司机列表新增字段 + 批量导入响应结构变更 + submit 入参字段名澄清(司机 PII 加密对前端透明) - ---- - -## ⚠️ 关键变化(前端 mmg 必读) - -### 1. 【重要】H5 司机自助入职接口现可通过网关访问(原 404) - -之前网关缺 `/app/h5/**` 路由，下列 4 个 H5 端点过网关一律 404，现已补齐可正常调用： - -- `GET /app/h5/driver-onboard/init` -- `POST /app/h5/driver-onboard/ocr/{step}`(multipart 上传) -- `POST /app/h5/driver-onboard/submit/new` -- `POST /app/h5/driver-onboard/submit/renew` - -鉴权：H5 端走**自带 onboard token**(query/form 参数，由后端 H5OnboardService 自校验)，**不需要 admin JWT**。坏 token 返 `data.tokenValid=false`(不报错)。 - -### 2. 车辆列表新增字段 - -`GET /admin/fleet/vehicles/page` 的 `records[]` 现包含： -- `typeKey` / `typeName`：车型大类(LEFT JOIN 车型库带出) -- `regDate`：注册日期 - -### 3. 司机列表新增字段 - -`GET /admin/fleet/drivers/page` 的 `records[]` 现包含： -- `licenseType` / `licenseExpire`：驾照类型 / 到期日 -- `totalOrders` / `avgRating` / `lastOrderAt`：接单数 / 评分 / 最近接单(业务流水模块上线前为默认 `0`/`0.00`/`null`) - -### 4. 批量导入响应结构变更 + 去重行为 - -**车辆导入** `POST /admin/fleet/vehicles/import` 出参： -```jsonc -// 之前: { total, success, failed, errorRows[] } -// 之后: -{ "totalRows": 10, "insertedCount": 7, "updatedCount": 2, "errorCount": 1, - "errors": [ { "row": 5, "plate": "蒙A12345", "msg": "..." } ] } -``` -**司机导入** `POST /admin/fleet/drivers/import` 出参： -```jsonc -{ "totalRows": 10, "insertedCount": 7, "renewedCount": 2, "errorCount": 1, - "errors": [ { "row": 5, "name": "张三", "msg": "..." } ] } -``` -**去重行为**：车牌(车辆)/身份证(司机)**已存在的行现执行 UPDATE**(原为报错计入失败)，不存在则 INSERT。 - -### 5. H5 新司机提交入参字段名澄清(文档笔误修正) - -`POST /app/h5/driver-onboard/submit/new` 入参用： -- `idCard`(**不是** `idCardNo`) -- `preferredCategory`(**不是** `preferredTypeKey`) - -代码一直是这两个名，是文档示例写错；文档已更正。前端按 `idCard` / `preferredCategory` 传参。 - -### 6. 司机敏感字段加密(后端透明，前端无需改动) - -身份证 / 手机 / 驾照号 / 紧急联系电话改为**加密存储**。接口响应仍按原样**脱敏返回**(如 `idCard: "110***********2468"`)，与之前一致，**前端无感知**。 - ---- - -## 📌 备注 - -- **已部署测试服(dev-v3)并经真 admin token + 真实数据 API 验证全绿**：车辆列表 typeName/typeKey/regDate 正确填充(真实 MySQL JOIN)、身份证密文存储 + 加密后按身份证去重命中 + 读路径脱敏正常、司机列表 5 个新字段齐全、`/app/h5` 路由连通。 -- 司机 PII 仅接通加密通道；测试库 #3104 前的存量明文司机均为软删数据，不影响。 diff --git a/changelogs-v2/2026-05/27_3115_HOUSE配房写主链真机修复-提交改价定稿_PR3117.md b/changelogs-v2/2026-05/27_3115_HOUSE配房写主链真机修复-提交改价定稿_PR3117.md deleted file mode 100644 index 19894c1..0000000 --- a/changelogs-v2/2026-05/27_3115_HOUSE配房写主链真机修复-提交改价定稿_PR3117.md +++ /dev/null @@ -1,37 +0,0 @@ -# 二期 v3 HOUSE 房务：配房写主链真机阻断修复（提交 / 改价 / 最终确认） - -> **服务**: hl-order-service-v3 -> **PR**: #3117 -> **Issue**: #3115 -> **日期**: 2026-05-27 -> **影响**: 🟡 配房三个核心写接口（提交配房 / 改单条配房 / 最终确认）此前真机一律失败，现已修复并测试服真机验证通过。**接口路径与出入参字段无任何变化**，前端无需改代码，可正常联调配房写流程。 - ---- - -## 背景 - -真机 API 测试（真 admin token 经网关 + 真实订单数据）发现配房「提交 → 改价 → 最终确认」三个写接口此前 100% 失败（单测 mock 能过、真机全挂），现修复。 - -## 受影响接口（仅"从报错变为可用"，契约不变） - -### 1. `POST /v3/admin/order/hotel-requirements/{requirementId}/assignments`（§2.2 提交配房） -- 之前：当所选酒店在 resource 无协议价时，返回 `400 字段【proto_price】未填写`，配房无法落库。 -- 现在：正常 200 落库。协议价/结算方式/付款模式/酒店名在主数据缺失（H04 接通前）时存 NULL，待回填，**不影响提交**。 -- 出参结构不变：`{ successCount, failCount, items:[{dayNumber, familyIndex, assignmentId, arrange}] }`。 - -### 2. `PUT /v3/admin/order/assignments/{id}`（§2.3 改单条配房） -- 之前：返回 `500`（服务器内部错误，乐观锁拦截器缺失）。 -- 现在：正常 200，`sellPrice` 改后 `totalCost` 自动重算、`version` 自增。 - -### 3. `POST /admin/house/assignments/requirements/{requirementId}/finalize`（§2.7 最终确认） -- 之前：闸口校验通过后仍返回 `400 字段【operator_name】未填写`，需求卡在 PROCESSING 无法定稿。 -- 现在：正常 200，需求推进到 `DONE`，返回 `{ newStatus:"DONE", finalizedAt }`。 - -## 真机验证（测试服双实例已部署） - -完整链路 claim → 提交配房(3 晚) → 改价 → 询房发起/回填 → 最终确认 → 删配房 全部 200 通过；need/requirement 正确流转到 DONE。 - -## 不在本次范围（仍为占位，依赖后续工单，前端先按空处理） - -- §2.1 候选源、§2.0 订单详情聚合 order 子对象、§6.1 酒店列表、§6.6 staff 列表：依赖 H04(product-v2/OrderService Feign) / resource 主数据 / H07(user-service)，暂为空/占位。 -- §2.5 房间分配「写」入口（家庭维度 assignRooms）当前无对外端点，§2.5 GET 的逐日 `assignments` 暂为空（另行评估是否补端点）。 diff --git a/changelogs-v2/2026-05/28_3142_新建订单选主题接口-下单选品接通真实接口_PR3155.md b/changelogs-v2/2026-05/28_3142_新建订单选主题接口-下单选品接通真实接口_PR3155.md deleted file mode 100644 index 926a650..0000000 --- a/changelogs-v2/2026-05/28_3142_新建订单选主题接口-下单选品接通真实接口_PR3155.md +++ /dev/null @@ -1,97 +0,0 @@ -# 二期 v3：新建订单向导「选主题/选产品」接通真实接口（替换 mockProducts.js） - -> **服务**: hl-product-service-v2（+ hl-order-service-v3 内部统计） -> **PR**: #3155 -> **Issue**: #3142 -> **日期**: 2026-05-28 -> **影响**: 🟡 新建订单页 `order-v2/new` 第 1 步「选主题」可改用真接口；第 2 步「选产品」用已有接口；地区筛选删除 - ---- - -## ⚠️ 关键变化（前端 mmg 必读） - -`order-v2/new` 第 1、2 步当前用 `src/views/order-v2/new/_shared/mockProducts.js` 写死假数据。现可替换为真实接口。 - -### 1. 第 1 步「选主题」— 新增接口 - -``` -GET /admin/product/line/order-picker -``` -- 无 query 参数，**不分页**，按排序号升序返回 -- 仅返回「**启用(ACTIVE) + 在售(该产品线下挂≥1个已上架产品)**」的主题 -- **数据权限**：和产品管理一致——超管看全部、核心(CORE)/小蒙马(GROUP)主题全员可见、私人定制(CUSTOM)仅创建人本人可见。**地区(region)筛选不需要,产品线无此字段,请删掉那排 chips。** - -返回结构： -```jsonc -{ - "code": 200, - "data": [ - { - "lineId": 2056937785918369794, // 主题ID(雪花,前端按字符串透传) - "name": "测试核心产品", // 主题名 - "description": "...", // 描述(原 mock 的 desc/tagline 都用它) - "coverImageUrl": "https://...", // 真实封面图(替代 mock 的 emoji cover + coverColor) - "productType": "CORE", // CORE=核心 / GROUP=小蒙马 - "skuCount": 6, // 该主题下已上架产品的档位总数(原 mock 的 skuCount) - "fromPrice": 3105.00, // 起价/人(已上架产品最低成人起价;未设价为 null,请显示 ¥-- 或灰) - "hot": true // 热门标识 = 该主题近90天下单量较多(前30%且>0) - } - ] -} -``` - -字段映射建议（mock → 真接口）： -- `id` → `lineId`（字符串透传，勿 Number()） -- `cover`/`coverColor`（emoji 装饰）→ 改用 `coverImageUrl` 真实图；如仍要色块可前端按 lineId 取色 -- `region`/`regionKey` → **删除**（无后端字段，地区 chips 去掉） -- `tagline` → 并入 `description` 或省略 -- `skuCount` / `fromPrice` / `hot` → 同名直取 -- 顶部统计「在售主题数」= 列表长度；「SKU总数」= Σ`skuCount`；「最低人均」= min(`fromPrice`) - -### 2. 第 2 步「选产品」— 新增专用接口（PR #3164 / #3159，已测试服验证） - -> 注：原先说复用 `/admin/product/item/list`，但 SKU 卡还要「热销」「发团日期」两个字段，通用列表没有；为不拖慢产品管理列表，**改为新建专用选产品 picker**（与选主题对称）。**前端 Step2 改调下面这个**，不要用 `/item/list`。 - -``` -GET /admin/product/item/order-picker?lineId={lineId}&page=1&pageSize=20&keyword= -``` -- `lineId` 必填（选定主题的 `lineId`）；只返该产品线**已上架**产品+档位；返回 `PageResult`（`data.records[]` + `data.total`） -- 数据权限同选主题（@DataScope：超管全部 / CORE·GROUP 全员 / CUSTOM 仅本人） -- 下单提交的 `productId + tierSeq` 从这里取（雪花 `productId` 按字符串透传，勿 Number()） - -返回 `records[]` 实测字段（与 Step2 SKU 卡片元素映射）： -```jsonc -{ - "productId": 2043595351268519937, // 产品ID(字符串透传) - "name": "6天5晚旷野版", // 卡片大标题 - "subtitle": "装甲车穿越·帐篷营地…", // 副标题 - "tags": ["亲子","露营"], // 标签行 - "tripDays": 6, "tripNights": 5, // "6天5晚" - "coverImageUrl": "https://...", - "startPrice": 10.00, // 产品级最低起价(可能 null → 显示 ¥--) - "tierPrices": [ // 档位数组(档次过滤 chips = 去重 tierName) - {"tierSeq":1, "tierName":"舒适", "tierDescription":"…", "startPrice":10.00}, - {"tierSeq":2, "tierName":"豪华", "tierDescription":"…", "startPrice":null} - ], - "hot": true, // 【新】热销徽标 = 该产品近90天下单量较多(本主题内前30%且>0) - "nextSaleDate": "2026-07-01" // 【新】发团日期 = 价格日历/班期里最近的未来可售日(无可售为 null) -} -``` - -**SKU 卡渲染**：mock 里每张卡=一个产品的一个档位；真实是一个产品(`productId`)含多档位(`tierPrices[]`)。 -建议按「产品 × 档位」平铺成卡（每个 `tierPrices[i]` 一张卡），卡上： -- 档位标签 ← `tierPrices[i].tierName`（"尊享档/挑战档"） -- 价格 ← `tierPrices[i].startPrice`（**null 显示 ¥-- / 灰**，别显示 0） -- 「热销」徽标 ← 产品级 `hot`（同一产品的各档位卡都显示） -- 「发团日期」← `nextSaleDate`（最近可售日；null 则不显示该行） -- 提交带 `productId` + `tierPrices[i].tierSeq` - -### 3. 提交（不变） -`POST /v3/admin/order`，入参 `productId` + `tierSeq` 等，已就绪。 - ---- - -## 验证 -测试服 `web.test.1814.love:9443` 真 admin token 实测： -- 选主题 `line/order-picker`：返 9 个在售主题(库内 ACTIVE 29 → 在售 9 精确吻合)，字段齐全，主题级 hot 跨服务统计生效 -- 选产品 `item/order-picker`：HTTP 200，字段齐全；产品级 `hot`（热门线下 4 产品命中 1 个 hot=true）、`nextSaleDate`（价格日历最近可售日，如 2026-07-01）均生效 diff --git a/changelogs-v2/2026-05/28_3147_产品服务标准模块-模板总则+每日提醒+订单Tab_PR3157.md b/changelogs-v2/2026-05/28_3147_产品服务标准模块-模板总则+每日提醒+订单Tab_PR3157.md deleted file mode 100644 index c44d270..0000000 --- a/changelogs-v2/2026-05/28_3147_产品服务标准模块-模板总则+每日提醒+订单Tab_PR3157.md +++ /dev/null @@ -1,142 +0,0 @@ -# 二期 v3：产品「服务标准」模块 — 模板总则(分组+条目) + 每日特别提醒 + 订单 Tab 富展示 - -> **服务**: hl-product-service-v2 + hl-order-service-v3 -> **PR**: #3157（+ hotfix #3163） -> **Issue**: #3147 -> **日期**: 2026-05-28 -> **影响**: 🟢 新增能力，全部向后兼容（旧订单 Tab 自动降级，不报错） -> **状态**: ✅ 测试服 9443 全链路实测通过（模板 CRUD → 产品绑定 → 创单冻结 → 订单 Tab） - ---- - -## 背景 - -「出团服务说明书」需要比原来 `notice.title + 一段富文本` 更丰富的结构：**多分组**（一、出团注意事项…）+ **编号条目**（标题/说明/联系人）+ **每日特别提醒**。本期在产品侧**新建**「服务标准」模块，创单冻结进订单快照，订单/小程序/PDF 读快照展示。 - -前端需做：① 模板编辑器（分组/条目增删）② 产品 Step5 绑定下拉 ③ 行程 Step2 每日「特别提醒」录入 ④ 订单/小程序服务标准 Tab 富展示 ⑤ 行程单/签单 PDF。 - ---- - -## 一、产品侧：服务标准模板管理（新增 admin 接口） - -路径前缀 `/admin/product/service-standard-template`（已被现有 `/admin/product/**` 网关路由覆盖）。 - -### 1. 分页 -``` -GET /admin/product/service-standard-template/page?pageNo=1&pageSize=10&name=&status= -``` -返回 `PageResult`（`data.records[]` + `data.total`），按 sortOrder/id 升序。 - -### 2. 详情 -``` -GET /admin/product/service-standard-template/{id} -``` - -### 3. 保存（id 空=新增 / 非空=修改） -``` -POST /admin/product/service-standard-template -``` -请求体： -```jsonc -{ - "id": null, // 修改时传(字符串透传雪花ID) - "name": "草原出团服务说明书", // 必填 - "intro": "出团前请仔细阅读…", // 顶部提示语(截图绿色提示条) - "applicableScope": "全部跟团客户", // 适用对象 - "sections": [ // 必填:分组+条目 - { - "title": "一、出行服务", // 分组标题(必填) - "items": [ - { "title": "接送站服务", "content": "提供机场/车站免费接送", "contact": "客服 400-xxx" } - ] - } - ], - "isDefault": false, - "sortOrder": 0, - "status": "ENABLED" // 留空默认 ENABLED；ENABLED=启用/DISABLED=停用 -} -``` -返回 `data` = 模板ID（**字符串透传，勿 Number()**）。 - -### 4. 删除（软删，已绑定产品不受影响） -``` -DELETE /admin/product/service-standard-template/{id} -``` - -### 5. 下拉（Step5 绑定用，仅启用项，不分页） -``` -GET /admin/product/service-standard-template/enabled -``` -返回 `data: [ { "id": "...", "name": "草原出团服务说明书" } ]`（只 id+name）。 - ---- - -## 二、产品 Step5 补充信息：绑定模板（纯引用） - -`PUT /admin/product/item/{id}/supplement` 请求体**新增**字段： -```jsonc -{ "serviceStandardTemplateId": 2059839696602615809 } // 字符串透传；解绑传 null -``` -保存后产品详情回显该 ID；用上面的 `/enabled` 下拉选。 - -> **私人定制例外**：私人定制(CUSTOM)产品「完成设计」时会把当时模板内容**冻结快照**进产品，之后改模板不影响该产品；核心/小蒙马为纯引用（改模板后续新订单实时跟随）。前端无需特殊处理，知悉即可。 - ---- - -## 三、产品 Step2 行程：每日「特别提醒」 - -`PUT /admin/product/item/{id}/itinerary` 的每个 `DayItem` **新增**字段： -```jsonc -{ - "dayNumber": 1, - "serviceTips": [ // 本日特别提醒(可空) - { "title": "本日特别提醒", "content": "今日海拔较高,备好抗高反药" } - ] -} -``` -保存后行程回显该天的 `serviceTips`。 - ---- - -## 四、订单详情「服务标准」Tab 响应升级 - -``` -GET /v3/admin/order/{id}/service-standard -``` -（小程序端经 hl-mp BFF 聚合，结构一致） - -`data` **新增** `serviceStandard` + `dayTips` 两块；保留原 `itinerary`、`refundPolicy`；原 `notice` 字段**废弃**（恒 null，请改用 `serviceStandard`）： -```jsonc -{ - "itinerary": ["Day1 …","Day2 …"], // 保留:行程天纲 - "notice": null, // 废弃,勿再用 - "refundPolicy": { /* 原结构保留 */ }, - "serviceStandard": { // 新:服务标准总则 - "intro": "出团前请仔细阅读…", - "applicableScope": "全部跟团客户", - "sections": [ - { "title": "一、出行服务", - "items": [ { "title": "接送站服务", "content": "…", "contact": "客服 400-xxx" } ] } - ] - }, - "dayTips": [ // 新:每日特别提醒(按天) - { "dayNumber": 1, "dayTitle": "Day1 抵达-接机", - "tips": [ { "title": "本日特别提醒", "content": "今日海拔较高…" } ] } - ] -} -``` - -### 向后兼容（重要） -- **本次升级前已下单的旧订单**：`serviceStandard` 返回 `null`、`dayTips` 返回 `[]`（快照里没有新结构，已实测降级不报错）。前端渲染需判空：`serviceStandard` 为 null 时不画总则区，`dayTips` 为空时不画每日提醒。 -- 升级后、且产品已绑模板/配每日提醒的**新订单**才有完整数据（已实测）。 - ---- - -## 字段约定 -- 所有雪花 ID（模板 id、serviceStandardTemplateId）**按字符串透传，勿 Number()**。 -- `sections` / `serviceTips` / `tips` 为空时分别返回 `[]` 或字段缺省，渲染需判空。 - ---- - -## 验证 -测试服 9443 已用真 admin token 全链路实测：模板 CRUD/下拉 → 产品绑定 → 行程每日提醒 → 创单冻结快照 → 订单 Tab 返回结构化 serviceStandard + dayTips（中文非 null）→ 旧订单降级不报错。 diff --git a/changelogs-v2/2026-05/28_HOUSE完备性_日历4状态+抢单productType+待办生产者全齐_PR3180-3200-3202.md b/changelogs-v2/2026-05/28_HOUSE完备性_日历4状态+抢单productType+待办生产者全齐_PR3180-3200-3202.md deleted file mode 100644 index 3269781..0000000 --- a/changelogs-v2/2026-05/28_HOUSE完备性_日历4状态+抢单productType+待办生产者全齐_PR3180-3200-3202.md +++ /dev/null @@ -1,64 +0,0 @@ -# 二期 v3 房务管家：日历 4 状态点 + 抢单池 productType + 待办生产者全齐（含取消→退订） - -> **服务**: hl-order-service-v3 -> **PR**: #3180、#3200、#3202(hotfix) -> **Issue**: #3179、#3188 -> **日期**: 2026-05-28 -> **影响**: 🟡 房务管家「日历视图 / 抢单池 / 待办 Tab」数据更完整；接口路径与字段结构**不变**，仅字段从恒空/恒 0 变为真实值、待办 Tab 新增几类会真正产生的待办 - ---- - -## 总览（前端 mmg 必读） - -继上一批房务接口真实化后，本批补齐房务管家剩余的完备性缺口。**接口路径、字段结构均不变**，前端可据此把对应 UI 由"空态/恒 0"切到真实渲染。 - ---- - -## 1. 日历视图 4 状态点真实化（§2.6）— PR #3180 - -`GET /admin/house/calendar?month=YYYY-MM&scope=mine|all` - -此前每天 / 汇总只有"进行中(inProgress)"有真实计数，"待配房(pending) / 询房中(inquiry) / 异常(exception)"恒为 0。现已全部按真实状态聚合： - -- **待配房 pending**：未被房务抢单的需求（按订单出发日落格） -- **询房中 inquiry**：有 PENDING 询房的订单 -- **异常 exception**：有 OPEN 异常类待办（换酒店 / 退订 / 询房超时等）的订单 -- **进行中 inProgress**：已配房且不在以上桶 - -`summary.{inProgress,pending,inquiry,exception}` 与每天 `statusDots[]`（含 label/count/color）均返真实值。优先级：异常 > 询房中 > 待配房 > 进行中。 - -## 2. 抢单池 productType 接通（§1.1）— PR #3180 - -`GET /v3/admin/order/grab-pool/hotel-requirements` - -- 列表项 `productType`（CORE/GROUP/CUSTOM）、`productNo` 此前恒 null，现经产品服务真实返回（如 `productType=CORE`、`productNo=C260520001`）。 -- `productType` 作为**查询筛选项现已生效**（按产品类型过滤抢单池）。 -- 上游产品服务查不到 / 降级时该字段如实 null，不报错。 - -## 3. 待办 Tab 生产者全齐（§4.1 / §3.4）— PR #3180 + #3200 - -`GET /v3/admin/order/todos` —— 此前部分待办类型只有"消费/RESOLVE"没有"生产者"，对应 Tab 永远空。现补齐，7 类待办均会真正产生： - -| 待办类型 | 何时产生（新增/原有） | -|---|---| -| `SWAP_HOTEL` 换酒店 | **新增**：酒店回填**拒单**时自动产（#3180）；换酒店完成后自动 RESOLVE | -| `INVENTORY_CHECK_OVERDUE` 核房超期 | **新增**：每日巡检 Job 扫到酒店快照过期自动产（#3180）；核房后自动 RESOLVE | -| `REFUND` 退订 | **新增**：订单**确认后取消**（房务已配房锁酒店）时自动产，归属原接单房务（#3200）；详见下 | -| `INQUIRY_TIMEOUT` 询房超时 / `INQUIRY_ESCALATED` 询房加急 / `RETURN_TO_HK` 退回房务 | 原有，不变 | - -> 注：`UNDELIVERED` 为历史遗留类型（其"询房 4h 无回复"语义已由 `INQUIRY_TIMEOUT` 承接），不再单独产生。 - -## 4. 订单取消 → 退订待办 + 待办清理（§1.3 / §4）— PR #3200（hotfix #3202） - -订单取消后房务侧的联动此前未生效（监听链路缺陷），现已接通： - -- 订单取消时，该订单房务侧"配房前置工作"类 OPEN 待办（换酒店/询房超时/核房超期等）**自动 RESOLVE**（取消后这些已无意义）。 -- 若取消时**房务已配房锁酒店**，自动产一条 `REFUND` 待办，归属原接单房务（无归属则广播），提示其处理酒店退订/释放。`reason` 取订单取消原因。 -- 业务规则确认：小蒙马(GROUP)库存在**下单时**扣减、其他产品无库存 —— 配房环节不涉及库存扣减/恢复。 - ---- - -## 验证 -以上全部已合并 dev-v3 + 测试服双实例部署，并经真机验证：日历 4 状态点真实计数、抢单池 productType 真实返回、酒店拒单产换酒店待办、订单取消产退订待办（取消订单 → SWAP_HOTEL 待办 RESOLVED + REFUND 待办 OPEN 归属原房务）。无接口路径/字段结构变更。 - -如需任一接口完整响应样例或字段疑问，回我即可。 diff --git a/changelogs-v2/2026-05/28_HOUSE批量_房务管家配房酒店员工城市真实化+房间分配写端点_PR3152-3154-3176-3178.md b/changelogs-v2/2026-05/28_HOUSE批量_房务管家配房酒店员工城市真实化+房间分配写端点_PR3152-3154-3176-3178.md deleted file mode 100644 index 343f09e..0000000 --- a/changelogs-v2/2026-05/28_HOUSE批量_房务管家配房酒店员工城市真实化+房间分配写端点_PR3152-3154-3176-3178.md +++ /dev/null @@ -1,87 +0,0 @@ -# 二期 v3 房务管家：配房/酒店/员工/城市等接口接通真实数据 + 新增房间分配写端点 - -> **服务**: hl-order-service-v3（+ resource / user-service 内部接口） -> **PR**: #3152、#3153、#3154、#3176、#3178 -> **Issue**: #3148、#3149、#3150、#3156、#3172、#3177 -> **日期**: 2026-05-28 -> **影响**: 🟡 房务管家（HOUSE）一批此前返空/null/桩的接口已接通真实数据；新增"房间分配写"端点；均已测试服双实例部署 + 真机验证 - ---- - -## ⚠️ 总览（前端 mmg 必读） - -房务管家相关接口此前多处因依赖未落地而返「空列表 / null 字段 / 占位」。现已跨 order-v3 / resource / user-service 三服务接通真实逻辑并真机验证。**接口路径、字段结构均不变**，只是**字段从空/占位变为真实值**，前端可据此把对应 UI 由"空状态"切到真实渲染。逐项如下。 - ---- - -## 1. 新增：房间分配写端点（§2.5）— PR #3152 - -此前只有 `GET .../rooms`（按家庭分组查），**没有写入端点**，导致逐日 `assignments` 恒空。现补： - -``` -POST /v3/admin/order/assignments/{assignmentId}/rooms -``` -- 幂等 + 分布式锁保护（重复提交安全） -- 请求体： -```jsonc -{ - "rooms": [ - { - "roomGroupNo": "F1", // 家庭/房间组号 - "travelerCount": 2, // 该房入住人数 - "travelerNames": "张三,李四", // 入住人姓名(逗号分隔) - "bedType": "double", // 床型 - "remark": "可选备注" - } - ] -} -``` -- 返回 `{ successCount, items:[{id, roomGroupNo, bedType, travelerCount}] }` -- 写入后 `GET /v3/admin/order/orders/{orderId}/rooms` 的逐日 `assignments` 即非空（含床型/人数明细） - ---- - -## 2. 酒店列表 / 详情接通真实数据（§6.1 / §6.2）— PR #3153 - -`GET /v3/admin/house/hotels`（列表）与 `GET /v3/admin/house/hotels/{hotelId}`（详情 4 Tab）此前走 Fallback 返空，现接 resource 真实主数据： - -- **§6.1 列表**：返真实酒店（测试库 39 家），字段 `city/cityName/level/settleType/paymentMode/protoPrice/roomTypes/status` 等齐全 - - `settleType` 字典 `hotel_settle_type`：`cash` 现付 / `sign` 签单 / `company` 公司付款 - - `paymentMode` 字典 `hotel_payment_mode`：`prepay` 预付款 / `cash` 现结 / `monthly` 月结 -- **§6.2 详情**：`basic`（基础信息）/ `roomTypes`（房型，含 `protoPrice` + `facilities` 设施数组）/ `priceCalendar30d`（未来 30 天价格日历）/ `recentCheckLog`（核房记录）四 Tab 均返真实数据 - -> 注：测试库酒店主数据已回填（结算/付款/协议价/房型价格），便于联调；正式环境以 resource 实际维护的数据为准。 - ---- - -## 3. 转单候选员工接通（§6.6）— PR #3154 + #3178 - -`GET /v3/admin/house/staff` 此前 user-service 无对应接口返空，现接通： - -- user-service 新增房务员工接口，按**房务角色**筛选：`house_keeper`(房务) / `house_lead`(房务组长) -- 返回 `{ list:[{ userId, name, avatar, online, superAdmin, activeCount }], total }` -- **`activeCount`（在跟订单数）口径**（#3178 修正）：为该员工**当前仍持有的活跃配房需求数**（精确口径），不再是历史 CLAIM 次数近似 —— 转单选人时的负载/上限判断更准确 - ---- - -## 4. 行程城市接通（§1.5 / §2.0）— PR #3176 - -此前 `cities` / `days[].city` 恒为 null。现按各天酒店反查城市接通： - -- **§1.5 我的接单** `GET /v3/admin/order/grab-pool/my-claims/hotel`：列表项 `cities` 返该单**行程去重城市数组**（如 `["呼伦贝尔市","兴安盟"]`） -- **§2.0 订单详情** `GET /admin/house/orders/{orderId}`：`requirement.current.days[].city` 及行程日历 `itinerary[].cityCode/cityName` 返**中文城市名** -- 数据缺失（酒店未维护城市 / 查询降级）时该字段如实 null，不报错 - ---- - -## 5. 转单接收人姓名真实化（§1.3）— PR #3178 - -转单后归属人姓名（`claimer_name`，体现在我的接单 / 详情归属人）此前为占位 `user-{id}`，现解析为**真实员工姓名**（经房务员工接口反查；查不到时退回 `user-{id}` 兜底，不影响转单成功）。 - ---- - -## 验证 - -以上全部已合并 dev-v3 + 测试服双实例滚动部署，并经真机（真 admin token，过网关 9443/本地 8080）验证：房间分配写→查 assignments 非空、酒店列表/详情字段齐全、员工列表真实、cities/city 中文城市、转单后 claimer_name 为真名。无接口路径/字段结构变更，前端按上述把对应 UI 从空态切真实渲染即可。 - -如需任一接口的完整响应样例，或字段有疑问，回我即可。 diff --git a/changelogs-v2/2026-05/29_服务标准_模板改表结构6字段+点位实时取资源_PR3254-3255-3256.md b/changelogs-v2/2026-05/29_服务标准_模板改表结构6字段+点位实时取资源_PR3254-3255-3256.md deleted file mode 100644 index 95a3df2..0000000 --- a/changelogs-v2/2026-05/29_服务标准_模板改表结构6字段+点位实时取资源_PR3254-3255-3256.md +++ /dev/null @@ -1,70 +0,0 @@ -# 二期 v3 服务标准重构：模板条目改表结构补 6 字段 + 行程点位服务标准实时取资源 - -> **服务**: hl-product-service-v2 / hl-resource-service / hl-order-service-v3 -> **PR**: #3254(模板改表结构)、#3255(点位取资源)、#3256(迁移 hotfix) -> **Issue**: #3253、#3250 -> **日期**: 2026-05-29 -> **影响**: 🟡 服务标准这一页分两块都有字段变化，前端需按 6 字段渲染模板条目 + 在行程点位渲染新的 `serviceStandard` - ---- - -## 总览（前端 mmg 必读） - -服务标准（出团服务说明书）这页分**两块**，本次都动了字段： - -1. **模板块**（模板标题/提示语/分组[出团注意事项·退费说明·温馨提示]+条目）——条目字段补全为 6 字段。 -2. **行程点位块**（每个酒店/景点/活动/服务点位下那段服务标准）——改为**实时从资源取**。 - -两块**正交**：模板块=出团总则类，点位块=资源自带。已测试服部署 + 验证。 - ---- - -## 1. 服务标准模板条目：3 字段 → 6 字段（#3254） - -接口路径不变：`/admin/product/service-standard-template`（create/update/detail/page），**响应形状仍是 `sections[].items[]`**。仅条目字段变化： - -| 字段 | 说明 | 备注 | -|---|---|---| -| `title` | 主文案 | 必填 | -| `content` | 正文 | 可空 | -| `remark` | 备注/灰色二级说明 | 新增 | -| `color` | 文案颜色 `#RRGGBB` | 新增 | -| `contactName` | 联系人（如「房务·舒馨」） | 新增 | -| `phone` | 手机号（如 15391131404） | 新增 | - -- **旧 `contact` 字段移除**（拆成 `contactName` + `phone`）。 -- `color` 校验：必须 `#RRGGBB` 格式；**无值传 `null` 或空串 `""` 均可**（PR #3257 起空串也放行，仍拒 `red` 等非法值）。 -- 后端存储由 JSON 列改为关系表（对前端无感，API 形状不变）。 -- ✅ 模板详情/列表 RespVO 已返 **`statusLabel`**（`ENABLED→启用` / `DISABLED→停用`，PR #3257 起），前端可直接渲染中文，无需自行映射（与装备建议对齐）。 - -> **补充更新（PR #3257）**：上面两条「⚠️ 无 statusLabel」「空串会 400」的遗留已修复——`statusLabel` 现已返回；`color` 空串现已放行。 - -## 2. 订单详情「服务标准」Tab 同步 6 字段（#3254） - -`GET /v3/admin/order/{orderId}/detail/service-standard` 的 `serviceStandard.sections[].items[]` 同步上述 6 字段（快照仍冻结，只是字段变多）。 - -## 3. 行程点位服务标准：实时从资源取（#3255） - -`GET /v3/admin/order/{orderId}/itinerary/full` → `days[].nodes[]` **新增 `serviceStandard` 字段**： - -- 值**实时按 `resourceId` 从资源（酒店/景点/活动/服务）拉取**，**不冻快照**——运营改了资源的服务标准，**老订单详情同步更新**。 -- 资源查不到 / 调用降级时该字段 `null`，不报错。 -- 前端在每个点位下渲染这段 `serviceStandard`（区别于点位的电话/联系人）。 - -## 4. 资源新增「服务标准」字段（#3255） - -酒店/景点/活动/服务 4 类资源新增 `serviceStandard` 字段（admin 编辑表单需加该输入框，最长 10000）： - -- 酒店：`GET/PUT /admin/hotel/item/{id}` 已含 `serviceStandard` -- 景点/活动/服务 admin create/update/detail 同步含该字段 - ---- - -## 验证（测试服 dev-v3 已部署 + 实测） - -- 模板 6 字段 admin E2E：创建（含 color/remark/contactName/phone）→ 详情回显，6 字段逐项 round-trip 通过；非法 color「red」被 400 拦截；多分组（2 组）正确。 -- 资源 `serviceStandard`：hotel 详情接口已含该字段（DB 列 + 内部批量详情已接通）。 -- 点位 `NodeVO.serviceStandard`：字段已上线，实时拉取 + 资源缺失降级 null 逻辑已单测覆盖。 -- 三服务（resource/product-v2/order-v3）测试服双实例已部署。 - -如需任一接口完整响应样例，回我即可。 diff --git a/changelogs-v2/2026-05/30_3272_资源退费说明CRUD模块_PR3273.md b/changelogs-v2/2026-05/30_3272_资源退费说明CRUD模块_PR3273.md deleted file mode 100644 index 9a4040f..0000000 --- a/changelogs-v2/2026-05/30_3272_资源退费说明CRUD模块_PR3273.md +++ /dev/null @@ -1,296 +0,0 @@ -# 二期 v3：资源退费说明 CRUD 模块（给司机行程单展示用） - -> **服务**: hl-resource-service -> **PR**: #3273 -> **Issue**: #3272 -> **日期**: 2026-05-30 -> **影响**: 🟢 新增能力。给运营在景区/活动详情下"维护退费说明"提供 CRUD 接口；最终用于行程单 PDF 渲染 + 核单 Step 5 录入对账。本期**仅交付资源服务端**，后续 PR 接入产品快照 + PDF + 核单。 - ---- - -## 总览（前端 mmg 必读） - -每个景区（SCENIC）和活动（ACTIVITY）资源都可以挂一份"退费说明"，包含资源级备注 + 多条退费明细（标题/金额/单位/备注/生效期）。 - -**界面**：景区 / 活动列表行加一个按钮 → 弹窗里调本期 3 个接口做 CRUD。 - -**接口前缀**：`/admin/refund-note`（**无 `/v3/` 前缀**，因 resource-service 沿用一期路径风格；消费方仍是二期 v3 管理后台）。 - -**本期不做**：行程单 PDF 渲染、产品 ProductDetailVO 注入 refundNote、订单 OrderProductSnapshotContent 反序列化、核单 Step 5 录入对接。这些留后续 PR。 - ---- - -## 接口清单（3 个） - -### 1. 查询单资源的退费说明 - -``` -GET /admin/refund-note?resourceType=SCENIC&resourceId=12345 -``` - -**入参**（query） - -| 字段 | 类型 | 必填 | 枚举 | 说明 | -|---|---|---|---|---| -| `resourceType` | string | ✅ | `SCENIC` / `ACTIVITY` | 资源类型 | -| `resourceId` | long | ✅ | - | 资源 ID（字符串透传雪花）| - -**返回** - -```jsonc -{ - "code": 200, - "data": { // 未配置时直接返 null,前端按 null 隐藏弹窗内容 - "noteId": "20596378108368322580", // 雪花 ID 字符串透传 - "resourceType": "SCENIC", - "resourceId": "12345", - "intro": "苔藓为赠送项目，不退费", - "items": [ - { - "title": "成人未参加", - "amount": 44.00, - "unitLabel": "/人", // 展示文案，给人看 - "settleScope": "PER_PERSON", // 结算粒度枚举，给规则引擎用 - "remark": "", - "effectiveFrom": null, // yyyy-MM-dd - "effectiveTo": null - }, - ... - ], - "createTime": "2026-05-30 10:15:00", - "updateTime": "2026-05-30 10:15:00" - } -} -``` - -**枚举** - -- `settleScope`： - - `PER_PERSON` 按人结算（默认） - - `PER_TEAM` 按团结算（如寻龙诀 100/团 整团一次性） - - `PER_VEHICLE` 按车辆结算（如卡丁车 2 人/辆，按辆数乘单价） - -**注意**：`unitLabel`（"/人" / "/团" / "/辆"）和 `settleScope` **职责不同**： -- 卡丁车场景：`unitLabel="/人"`（给客户看是 120/人）+ `settleScope=PER_VEHICLE`（引擎按车辆数乘单价） -- 两个字段独立维护，前端展示用 `unitLabel`，未来规则引擎用 `settleScope`。 - ---- - -### ⚡ 更新（2026-06-01 PR #3291）：settleScope 字典化 + 出参补 settleScopeLabel 中文 - -后端**已落字典 + 接口出参直接返中文**，前端**不用自己维护英文→中文映射**。两种用法二选一： - -#### 用法 A：直接用出参的 `settleScopeLabel`（展示场景推荐） - -`GET /admin/refund-note` 返回的 `items[]` 每条**新增 `settleScopeLabel` 字段**： - -```jsonc -"items": [ - { - "title": "成人未参加", - "settleScope": "PER_PERSON", - "settleScopeLabel": "按人", // 🆕 后端字典拼装,直接展示 - ... - } -] -``` - -**列表 / 详情 UI 直接 `{{ item.settleScopeLabel }}` 渲染**即可，无需自己映射。 - -#### 用法 B：调字典接口拉下拉框选项（编辑场景推荐） - -管理后台编辑退费规则时，需要下拉框让运营选"按人/按团/按车"。调统一字典接口： - -```http -GET /internal/dict/data?dictType=order_refund_settle_scope -Authorization: Bearer - -→ Result>: -[ - { "dictValue": "PER_PERSON", "dictLabel": "按人", "sortOrder": 10 }, - { "dictValue": "PER_TEAM", "dictLabel": "按团", "sortOrder": 20 }, - { "dictValue": "PER_VEHICLE", "dictLabel": "按车", "sortOrder": 30 } -] -``` - -- 下拉框 `option.label = dictLabel`，`option.value = dictValue` -- 提交时 `req.items[].settleScope = dictValue`（提交 `settleScopeLabel` 后端会忽略，label 由后端拼） -- 建议前端**全局缓存字典 5-10 分钟**避免高频请求；如果有统一字典组件直接复用 - -#### 容错（前端可忽略） - -- 字典服务异常 / 字典数据缺失 → `settleScopeLabel = null`，前端展示 fallback 用 `settleScope` 英文原值即可 -- 字典文案后续改了（如"按人" → "按人头"）→ **运维改 sys_dict_data + 清 Redis 缓存即生效**，后端无需重启，前端无需发版 - -#### 字典元信息 - -| 项 | 值 | -|---|---| -| `dict_type` | `order_refund_settle_scope` | -| `dict_name` | 退费明细结算粒度 | -| 字典数据 | PER_PERSON→按人 / PER_TEAM→按团 / PER_VEHICLE→按车 | -| 字典存储 | `hl_user_service.sys_dict_data` | -| 缓存 key | `cache:dict:data:order_refund_settle_scope` | - -### 2. 保存（upsert 整块） - -``` -PUT /admin/refund-note -``` - -**入参**（body） - -```jsonc -{ - "resourceType": "SCENIC", - "resourceId": 12345, - "intro": "苔藓为赠送项目，不退费", - "items": [ - { - "title": "成人未参加", // 必填 - "amount": 44.00, // 必填，>= 0（赠送项填 0） - "unitLabel": "/人", // 默认 "/人"，可省略 - "settleScope": "PER_PERSON", // 默认 "PER_PERSON"，可省略 - "remark": "", - "effectiveFrom": null, - "effectiveTo": null - } - ] -} -``` - -**约束** - -- `resourceType`：必须是 `SCENIC` / `ACTIVITY` -- `resourceId`：**必须在 scenic_spot / activity 表存在且未软删**，否则返 390805 "关联资源不存在" -- `items`：至少 1 条，最多 50 条 -- `items[].amount`：>= 0（赠送项目填 0） -- `items[].settleScope`：必须是上述 3 枚举之一（null 时默认 PER_PERSON） -- `items[].effectiveFrom` <= `items[].effectiveTo`（同时存在时） - -**返回** - -```jsonc -{ "code": 200, "data": "20596378108368322580" } // 落库后的 noteId（字符串透传） -``` - -**语义**：upsert——按 (resourceType, resourceId) 找现有记录，有则**整块覆盖**（不做 item 级 diff），无则 insert。 - -### 3. 软删整份 - -``` -DELETE /admin/refund-note?resourceType=SCENIC&resourceId=12345 -``` - -**入参**：同 GET。 -**返回**：`{ "code": 200, "data": true }`（不存在或已软删返 false，不报错）。 - -软删用主键自身写 deleted_at，UNIQUE KEY 永不撞键，支持同资源无限次"删→重建"。 - ---- - -## 错误码（段位 39080x） - -| code | 错误信息 | -|---|---| -| 390801 | 退费明细金额必须 ≥ 0 | -| 390802 | 退费明细生效起日不能晚于止日 | -| 390803 | 退费明细结算粒度非法: {0} | -| 390804 | 退费说明资源类型非法: {0} | -| 390805 | 关联资源不存在: type={0}, id={1} | - -非业务错误（参数校验失败）走通用 400。 - ---- - -## 业务边界 - -- **资源类型**：一期仅 `SCENIC` + `ACTIVITY`，其他资源（餐饮/酒店/物资等）有各自退订/退款政策，不复用本结构。 -- **一份生效**：同资源同时刻只有一份生效的退费说明（DB 唯一键 `(resource_type, resource_id, deleted_at)` 保证）。 -- **关联校验**：保存时校验 resourceId 在主资源表存在，防孤儿数据。 -- **资源软删后**：本退费说明仍存在但孤儿（查不到对应资源），不主动清理；运营侧需手动删除。 - ---- - -## 数据示例（典型） - -### 白桦林（4 条规则） - -```jsonc -{ - "resourceType": "SCENIC", "resourceId": 12345, - "intro": "苔藓为赠送项目, 不退费", - "items": [ - {"title": "儿童/学生/无证件未参加", "amount": 15, "unitLabel": "/人", "settleScope": "PER_PERSON"}, - {"title": "免票座电瓶车", "amount": 30, "unitLabel": "/人", "settleScope": "PER_PERSON"}, - {"title": "白桦林未参加", "amount": 44, "unitLabel": "/人", "settleScope": "PER_PERSON"}, - {"title": "桦树皮画未参加", "amount": 50, "unitLabel": "/人", "settleScope": "PER_PERSON", "remark": "仅儿童"} - ] -} -``` - -### 寻龙诀（按团结算） - -```jsonc -{ - "resourceType": "ACTIVITY", "resourceId": 99999, - "items": [ - {"title": "寻龙诀未参加", "amount": 100, "unitLabel": "/团", "settleScope": "PER_TEAM"} - ] -} -``` - -### 卡丁车（按车结算，文案 /人） - -```jsonc -{ - "resourceType": "ACTIVITY", "resourceId": 88888, - "items": [ - {"title": "卡丁车未骑", "amount": 120, "unitLabel": "/人", "settleScope": "PER_VEHICLE", - "remark": "2 人/辆共享单价"} - ] -} -``` - -### 套娃（时间窗口） - -```jsonc -{ - "resourceType": "SCENIC", "resourceId": 77777, - "items": [ - {"title": "老人只看大马戏", "amount": 65, "settleScope": "PER_PERSON"}, - {"title": "6/25 后没去或免票", "amount": 165, "settleScope": "PER_PERSON", - "effectiveFrom": "2026-06-25", "effectiveTo": null} - ] -} -``` - ---- - -## 影响评估 - -- **后端**：仅 hl-resource-service 新增 1 张表 `resource_refund_note` + 3 个 admin 接口，对其他业务零影响。 -- **DB**：Flyway `V20260529_002__create_resource_refund_note.sql` 自动建表，重启服务后生效。 -- **前端**：新增弹窗 UI（建议在景区 / 活动详情页加按钮 → 弹窗 CRUD），完全独立的新页面，老页面不影响。 - ---- - -## 注意事项 - -1. 雪花 ID 透传为字符串（`noteId` / `resourceId`），前端**不要 `Number()`**。 -2. 资源软删后的退费说明不会自动清理，运营侧需先删退费说明再删资源（否则成孤儿数据）。 -3. 同资源不可有 2 份生效退费说明（DB 唯一键约束）。 -4. 删除是软删，可同资源重建；不支持物理删除。 - ---- - -## 关联 - -- **Issue**: [#3272](https://git.1814.love:8443/wx/HL/issues/3272) -- **PR**: [#3273](https://git.1814.love:8443/wx/HL/pulls/3273) - feat(resource): 新增资源退费说明 CRUD 模块 -- **Commit**: [ffae5ab90](https://git.1814.love:8443/wx/HL/commit/ffae5ab90) -- **后续 PR**（不在本期）： - - 产品服务 `ProductDetailVO.NodeItem.refundNote` 注入（参考 #3147 serviceStandard 模式） - - 订单 `OrderProductSnapshotContent` 加 refundNote 反序列化（10 行） - - 行程单 PDF 渲染退费表（订单 v3 + PDF 服务） - - 核单 Step 5 录入半结构化对接（可选） diff --git a/changelogs-v2/2026-05/30_3283_订单状态字段补中文名_PR3284.md b/changelogs-v2/2026-05/30_3283_订单状态字段补中文名_PR3284.md deleted file mode 100644 index e853eff..0000000 --- a/changelogs-v2/2026-05/30_3283_订单状态字段补中文名_PR3284.md +++ /dev/null @@ -1,149 +0,0 @@ -# 二期 v3：订单 orderStatus / flowStatus 字段补 label 中文映射 - -> **服务**: hl-order-service-v3 -> **PR**: #3284 -> **Issue**: #3283 -> **日期**: 2026-05-30 -> **影响**: 🟢 **非破坏性**新增字段。前端从前自行映射 `AWAITING_PROFILE → "待补全信息"` 等，现在后端直接给。老字段 `orderStatus` / `flowStatus`（英文枚举）保留不动，新增 `orderStatusName` / `flowStatusName` 中文 label 同时返回。 - ---- - -## 总览（前端 mmg 必读） - -订单列表 / 详情 / 创建响应里的 `orderStatus` 和 `flowStatus` 字段历史上**只返英文枚举**（`CUSTOMIZING` / `AWAITING_PROFILE` 等），前端要查表自行翻译。本期后端直接拼好中文 label 返回，前端**直接用 `xxxStatusName` 字段展示**即可。 - -旧字段保留，前端老逻辑零改动。 - ---- - -## 接口清单（3 个响应增字段） - -### 1. 订单列表 - -``` -GET /v3/admin/order -``` - -**响应** `data.records[].xxx` 新增 2 字段： - -```jsonc -{ - "orderStatus": "CUSTOMIZING", - "orderStatusName": "定制中", // 🆕 中文名 - "flowStatus": "AWAITING_PROFILE", - "flowStatusName": "待补全信息" // 🆕 中文名 -} -``` - -### 2. 订单详情 - -``` -GET /v3/admin/order/{id}/detail -``` - -**响应** `data.main` 同样新增 2 字段： - -```jsonc -"main": { - "orderStatus": "TRAVELLING", - "orderStatusName": "出行中", // 🆕 - "flowStatus": "TRAVELLING", - "flowStatusName": "出行中" // 🆕 -} -``` - -### 3. 创建订单响应 - -``` -POST /v3/admin/order -``` - -**响应** `data` 新增 1 字段（`orderStatusName` 早期已有，本期补 `flowStatusName`）： - -```jsonc -{ - "orderStatus": "PENDING_PAY", - "orderStatusName": "待支付", - "flowStatus": "AWAITING_PAY", - "flowStatusName": "待支付" // 🆕 -} -``` - ---- - -## 状态枚举完整对照表 - -### `orderStatus`（粗状态 6 个） - -| 枚举值 | 中文名 | -|---|---| -| `PENDING_PAY` | 待支付 | -| `CUSTOMIZING` | 定制中 | -| `PENDING_DEPARTURE` | 待出行 | -| `TRAVELLING` | 出行中 | -| `COMPLETED` | 已完成 | -| `CANCELLED` | 已取消 | - -### `flowStatus`（细状态 16 个） - -| 枚举值 | 中文名 | -|---|---| -| `AWAITING_PAY` | 待支付 | -| `AWAITING_PROFILE` | 待补全信息 | -| `AWAITING_HOTEL_SUBMIT` | 待提交房型 | -| `AWAITING_HOTEL_CLAIM` | 待抢房 | -| `HOTEL_IN_PROGRESS` | 房控处理中 | -| `HOTEL_NEED_ADJUST` | 房控需调整 | -| `AWAITING_VEHICLE_SUBMIT` | 待提交用车 | -| `VEHICLE_IN_PROGRESS` | 车控处理中 | -| `VEHICLE_NEED_ADJUST` | 车控需调整 | -| `PENDING_CONFIRM` | 待确认 | -| `PENDING_DEPARTURE` | 待出行 | -| `TRAVELLING` | 出行中 | -| `PENDING_REVIEW` | 待核单 | -| `REVIEWING` | 核单中 | -| `SETTLED` | 已结算 | -| `COMPLETED` | 已完成 | -| `CANCELLED` | 已取消 | - -> ⚠️ **注意**：本 PR 后紧跟的 PR #3286 改了其中 2 个 label —— `待提交房型 → 待提交配房需求`、`待提交用车 → 待配车需求`。**实际部署后看到的是 PR #3286 的新文案**，前端如果按这俩老文案做字符串硬比较需要更新（详见 PR #3286 changelog）。 - ---- - -## 容错（前端可忽略） - -- 后端拿到 null 或未知枚举（历史脏数据）会回退：返回原值而不是抛 500，前端不会看到"待x"等乱码。 -- 即便后端返回原英文枚举值（如未知 `XXXXX`），前端展示也能落 fallback。 - ---- - -## 业务边界 - -- 老字段 `orderStatus` / `flowStatus` 保留英文枚举（**契约不变**） -- 仅新增 `orderStatusName` / `flowStatusName` 中文 -- 前端**老逻辑零改动**也能跑（旧字段还在） -- 改成展示 `xxxStatusName` 后，前端不需要自己维护英文 → 中文映射表 - ---- - -## 影响评估 - -- **后端**：仅 hl-order-service-v3 改了 5 个文件（3 VO + Converter + OrderService），无 DB 改动，重启服务后生效。 -- **前端**：可选改造——把硬编码映射表删掉，直接用 `xxxStatusName`。改不改都不影响功能。 -- **mp 端**：本 PR 暂未改 `OrderLookupMpService`（仍是 mock 假数据），真业务化时一起补。 - ---- - -## 注意事项 - -1. 如果你的前端代码有硬编码的英文→中文映射表（如 `{ AWAITING_PROFILE: "待补全信息" }`），建议删掉，改用 `flowStatusName` 字段，避免后端枚举改了文案前端跟不上。 -2. 文案的"权威源"是后端枚举（`OrderStatus` / `OrderFlowStatus`），运营如果要求改文案直接改后端，前端无感跟随。 - ---- - -## 关联 - -- **Issue**: [#3283](https://git.1814.love:8443/wx/HL/issues/3283) -- **PR**: [#3284](https://git.1814.love:8443/wx/HL/pulls/3284) - fix(order-v3): orderStatus/flowStatus 补 label 中文映射 -- **Commit**: [cb85f0f76](https://git.1814.love:8443/wx/HL/commit/cb85f0f76) -- **接续 PR**: [#3286](https://git.1814.love:8443/wx/HL/pulls/3286) - feat(order-v3): 8 步步骤条字段 + 修 2 文案（紧接本 PR，建议一起看） diff --git a/changelogs-v2/2026-05/30_3285_订单接口加8步步骤条字段_PR3286.md b/changelogs-v2/2026-05/30_3285_订单接口加8步步骤条字段_PR3286.md deleted file mode 100644 index 596797e..0000000 --- a/changelogs-v2/2026-05/30_3285_订单接口加8步步骤条字段_PR3286.md +++ /dev/null @@ -1,204 +0,0 @@ -# 二期 v3：订单接口加 flowStep / flowStepTotal / flowDisplayText 步骤条字段 + 修 2 个文案 - -> **服务**: hl-order-service-v3 -> **PR**: #3286 -> **Issue**: #3285 -> **日期**: 2026-05-30 -> **影响**: 🟡 **非破坏性**新增字段 + **文案修订**。前端从前自己拼 `"1/8 · 待补全信息"`，现在后端直接给 `flowStep` / `flowStepTotal` / `flowDisplayText` 三字段，前端拿着就显示。同时修了 2 个枚举 label 文案。 - ---- - -## 总览（前端 mmg 必读） - -接续 PR #3284（status label 中文），本期把"订单步骤条"所需数据全部下沉到后端： - -```jsonc -{ - "flowStep": 1, // 🆕 当前步序号 0=待支付前, 1-8=进行中, null=终态/未知 - "flowStepTotal": 8, // 🆕 总步数固定 8 - "flowDisplayText": "待补全信息" // 🆕 中文文案,只中文不带"X/8 · ",前端按需自拼 -} -``` - -前端从前的 `currentStep / totalSteps + 自己映射中文` 逻辑全部可删，直接用本期 3 字段。 - -**同时**：修了 2 个 `OrderFlowStatus` 枚举 label 文案（影响 `flowStatusName` 字段返回）： - -| 枚举值 | 旧文案 | 新文案 | -|---|---|---| -| `AWAITING_HOTEL_SUBMIT` | 待提交房型 | **待提交配房需求** | -| `AWAITING_VEHICLE_SUBMIT` | 待提交用车 | **待配车需求** | - ---- - -## 接口清单（3 个响应增字段） - -### 1. 订单列表 - -``` -GET /v3/admin/order -``` - -**响应** `data.records[].xxx` 在 PR #3284 基础上再加 3 字段： - -```jsonc -{ - "orderStatus": "CUSTOMIZING", - "orderStatusName": "定制中", - "flowStatus": "AWAITING_PROFILE", - "flowStatusName": "待补全信息", - "flowStep": 1, // 🆕 - "flowStepTotal": 8, // 🆕 - "flowDisplayText": "待补全信息" // 🆕 -} -``` - -### 2. 订单详情 - -``` -GET /v3/admin/order/{id}/detail -``` - -**响应** `data.main` 同样加 3 字段（位置和列表相同）。 - -### 3. 创建订单响应 - -``` -POST /v3/admin/order -``` - -**响应** 加 3 字段；创单初态固定： - -```jsonc -{ - "flowStep": 0, - "flowStepTotal": 8, - "flowDisplayText": "待支付" -} -``` - ---- - -## 8 步映射表（16 → 8） - -**优先级**：`orderStatus` 终态 > `flowStatus` 步骤映射 - -| 触发条件 | `flowStep` | `flowDisplayText` | -|---|---|---| -| `orderStatus = CANCELLED` | `null` | "已取消" | -| `orderStatus = COMPLETED` | `null` | "已完成" | -| `flowStatus = AWAITING_PAY` | `0` | "待支付" | -| `flowStatus = AWAITING_PROFILE` | `1` | "待补全信息" | -| `flowStatus = AWAITING_HOTEL_SUBMIT` | `2` | **"待提交配房需求"** | -| `flowStatus = AWAITING_HOTEL_CLAIM` | `2` | "待抢房" | -| `flowStatus = HOTEL_IN_PROGRESS` | `2` | "房控处理中" | -| `flowStatus = HOTEL_NEED_ADJUST` | `2` | "房控需调整" | -| `flowStatus = AWAITING_VEHICLE_SUBMIT` | `3` | **"待配车需求"** | -| `flowStatus = VEHICLE_IN_PROGRESS` | `3` | "车控处理中" | -| `flowStatus = VEHICLE_NEED_ADJUST` | `3` | "车控需调整" | -| `flowStatus = PENDING_CONFIRM` | `4` | "待确认" | -| `flowStatus = PENDING_DEPARTURE` | `5` | "待出行" | -| `flowStatus = TRAVELLING` | `6` | "出行中" | -| `flowStatus = PENDING_REVIEW` | `7` | "待核单" | -| `flowStatus = REVIEWING` | `8` | "核单中" | -| `flowStatus = SETTLED` | `8` | "已结算" | - -**说明**： - -- 配房 4 个并行子态（`AWAITING_HOTEL_SUBMIT` / `_CLAIM` / `HOTEL_IN_PROGRESS` / `_NEED_ADJUST`）都归到 step 2 -- 配车 3 个并行子态都归到 step 3 -- `REVIEWING` 和 `SETTLED` 都归到 step 8（结算后整体收尾） -- `CANCELLED` / `COMPLETED` 是终态，不在 8 步串行里，`flowStep` 返 null -- 未知 / 历史脏数据：`flowStep=null`, `flowDisplayText=` 原英文值（fallback 不抛错） - ---- - -## 前端如何用（推荐） - -### 推荐方式 1：只显示 `flowDisplayText`（最简单） - -```html -{{ order.flowDisplayText }} - -``` - -### 推荐方式 2：进度条 + 中文（拼分子分母） - -```html - - {{ order.flowStep }}/{{ order.flowStepTotal }} · {{ order.flowDisplayText }} - - - {{ order.flowDisplayText }} - - -``` - -### 推荐方式 3：步骤条 UI（按 flowStep 高亮） - -如果有 8 段步骤条 UI 组件，按 `flowStep` 高亮当前段： - -```jsonc -const stepNames = ["待支付", "补全信息", "配房需求", "配车需求", - "确认", "出行准备", "出行", "核单"]; -// 用 flowStep 高亮 stepNames[flowStep - 1] -``` - ---- - -## 文案变更详情（重点关注） - -| 字段 | 旧值 | 新值 | -|---|---|---| -| `flowStatusName`（PR #3284 字段）| "待提交房型" | "待提交配房需求" | -| `flowStatusName` | "待提交用车" | "待配车需求" | -| `flowDisplayText`（本 PR 字段）| - | 同上 | - -**前端需要确认的事**： - -1. 如果有按 **"待提交房型"** / **"待提交用车"** 老文案做字符串硬比较（如 `if (status === "待提交房型")`），需要改成新文案或改用枚举值比较。 -2. 如果只是 **展示**（不做逻辑判断），无需改动——文案直接显示新值即可。 - -我们后端搜了一遍**未发现**前端这个老文案的硬比较，但前端代码后端看不到，**请前端 mmg 自己 grep 确认**。 - ---- - -## 容错（前端可忽略） - -- `flowStatus` 是历史脏数据（枚举里没有）→ `flowStep = null`, `flowDisplayText = 原始值` -- `orderStatus = null` → `flowStep = null`, `flowDisplayText = "未知"` -- 前端按 `flowStep === null` 判断终态/未知，按 `flowDisplayText` 兜底展示，绝不会拿到空字符串。 - ---- - -## 业务边界 - -- 老字段 `flowStatus` / `flowStatusName` 保留（契约不变） -- 仅新增 3 字段 + 修订 2 个枚举 label 文案 -- 8 步是**前端展示概念**，后端的 `OrderFlowStatus` 仍是 16 个细状态（DB 落地不变） -- 步骤条只是**展示视角**的简化，业务逻辑仍按 16 个 `flowStatus` 跑 - ---- - -## 影响评估 - -- **后端**：hl-order-service-v3 改了 7 个文件（枚举 + Converter + 3 VO + Service + 测试），无 DB 改动，重启服务后生效。 -- **前端**：可选改造——把"1/8"拼接逻辑改用后端 3 字段。改不改都不影响功能（老逻辑还能跑）。 -- **mp 端**：本 PR 暂未改 mp（mock service），真业务化时一并补。 - ---- - -## 注意事项 - -1. **文案修订是契约变更**：如果前端按老文案做字符串硬比较，必须改。展示用的话无影响。 -2. **flowStep 可能为 null**：终态（已取消/已完成/历史脏数据）时为 null，前端按 null 处理"不显示分子"或"显示终态文案"。 -3. **创单后立即调列表**：会看到 `flowStep=0` + `flowDisplayText="待支付"`，符合"还没开始走流程"语义。 - ---- - -## 关联 - -- **Issue**: [#3285](https://git.1814.love:8443/wx/HL/issues/3285) -- **PR**: [#3286](https://git.1814.love:8443/wx/HL/pulls/3286) - feat(order-v3): 订单接口加 8 步步骤条字段 + 修 2 个文案 -- **Commit**: [fd533fdaa](https://git.1814.love:8443/wx/HL/commit/fd533fdaa) -- **前置 PR**: [#3284](https://git.1814.love:8443/wx/HL/pulls/3284) - status label 中文（建议一起看） diff --git a/changelogs-v2/2026-05/30_3294_服务标准条目6字段进快照修复_PR3295.md b/changelogs-v2/2026-05/30_3294_服务标准条目6字段进快照修复_PR3295.md deleted file mode 100644 index 59377ab..0000000 --- a/changelogs-v2/2026-05/30_3294_服务标准条目6字段进快照修复_PR3295.md +++ /dev/null @@ -1,81 +0,0 @@ -# 二期 v3：修复服务标准条目 remark/color/contactName/phone 四字段下单时丢失（恒为 null） - -> **服务**: hl-order-service-v3 -> **PR**: #3295 -> **Issue**: #3294 -> **日期**: 2026-06-01 -> **影响**: 🟢 **缺陷修复**，无契约变更。订单详情「服务标准」Tab 的条目，此前 `remark` / `color` / `contactName` / `phone` 四字段因后端缺陷恒为 `null`，本次修复后**新建订单**会正确返回这四个字段的真实值。响应结构不变，前端无需改代码，原本就该读这四字段的渲染逻辑现在能拿到数据。 - ---- - -## 总览（前端 mmg 必读） - -接续 PR #3254/#3255/#3256（服务标准模板改 6 字段），那一期把产品侧服务标准升级到 6 字段条目，但**下单写订单快照的中间环节漏跟进**： - -订单详情服务标准来自下单时冻结的产品快照（`order_product_snapshot`）。该快照由订单服务接收产品 Feign 数据后整体序列化，但订单侧接收用的 VO 还停留在旧 3 字段（`title` / `content` / `contact`），导致产品发来的 `remark` / `color` / `contactName` / `phone` 在反序列化时被静默丢弃，冻进快照只剩 `title` + `content`。 - -**结果**：所有订单详情服务标准 Tab 的条目这 4 个字段恒为 `null`。本次补齐订单侧 VO 字段，使整条服务标准 6 字段完整进快照。 - ---- - -## 受影响接口（响应行为修正，无字段增减） - -``` -GET /v3/admin/order/{id}/service-standard -``` - -**响应** `data.serviceStandard.sections[].items[]` 条目，6 字段修复前后对比： - -```jsonc -// 修复前（4 字段恒 null） -{ - "title": "专业司机", - "content": "持有A1驾照,8年以上驾龄", - "remark": null, // ❌ 恒 null - "color": null, // ❌ 恒 null - "contactName": null, // ❌ 恒 null - "phone": null // ❌ 恒 null -} - -// 修复后（新建订单） -{ - "title": "专业司机", - "content": "持有A1驾照,8年以上驾龄", - "remark": "仅限指定时段", // ✅ - "color": "#FF6600", // ✅ - "contactName": "李师傅", // ✅ - "phone": "13800000000" // ✅ -} -``` - -字段名、类型、嵌套层级**完全不变**，仅是原本恒 null 的值现在有了真实数据。 - ---- - -## 重要边界：只对「新建订单」生效 - -- 快照是**下单时间点的冻结值**，修复部署前已生成的历史订单快照仍只有 `title` + `content`，这 4 字段对老订单仍为 `null`（不回填，符合快照语义）。 -- 修复部署后**新建**的订单，服务标准 6 字段完整。 -- 前端渲染需对这 4 字段做 `null` 容错（老订单仍可能为 null），有值即展示。 - ---- - -## 测试服验证（已通过） - -部署 dev-v3 后端到端实测：建含 6 字段服务标准模板的产品订单 → `GET .../service-standard` 与 DB 快照 `snapshot_content` 双查，6 字段（含 remark/color/contactName/phone）全部正确返回。 - ---- - -## 影响评估 - -- **后端**：hl-order-service-v3 改 1 个传输 VO（`ProductDetailVO.ServiceStandard.Item` 补 4 字段、删废弃 `contact`）+ 1 个端到端回归测试。无 DB 改动，重启生效。 -- **前端**：无需改代码，原服务标准 Tab 条目渲染逻辑现在能拿到 4 个新字段值。 -- **mp 端**：本次未涉及。 - ---- - -## 关联 - -- **Issue**: [#3294](https://git.1814.love:8443/wx/HL/issues/3294) -- **PR**: [#3295](https://git.1814.love:8443/wx/HL/pulls/3295) - fix(order-v3): 补齐服务标准条目 6 字段，使下单快照完整冻结 -- **前置**: PR #3254/#3255/#3256（服务标准模板改 6 字段） diff --git a/changelogs-v2/2026-05/30_3307_退费说明接入产品订单快照+网关路由修复_PR3308-3312.md b/changelogs-v2/2026-05/30_3307_退费说明接入产品订单快照+网关路由修复_PR3308-3312.md deleted file mode 100644 index 51b6f8c..0000000 --- a/changelogs-v2/2026-05/30_3307_退费说明接入产品订单快照+网关路由修复_PR3308-3312.md +++ /dev/null @@ -1,85 +0,0 @@ -# 二期 v3：退费说明接入产品详情/订单快照 + 修复 /admin/refund-note 网关路由 404 - -> **服务**: hl-resource-service / hl-product-service-v2 / hl-order-service-v3 / hl-gateway -> **PR**: #3308（接入）+ #3312（hotfix） -> **Issue**: #3307 / #3311 -> **日期**: 2026-06-01 -> **影响**: 🟢 新增能力 + 🔴 **修复 #3272 退费说明 admin CRUD 经网关 404 完全不可用**。前端现可正常调 `/admin/refund-note` 维护退费说明；退费说明已接入产品行程节点聚合并在下单时冻进订单快照。 - ---- - -## 一、前端必读：`/admin/refund-note` 现在可达了（之前 404） - -#3272 交付了「资源退费说明 CRUD」（景区/活动维护退费明细），但**漏配网关路由**，导致 `/admin/refund-note` 经网关一直返： - -```json -{"code":404,"message":"接口不存在: /admin/refund-note"} -``` - -本次已补网关路由。**前端原本对着 #3272 文档写的退费说明 CRUD 弹窗，现在能真正调通了**。三个接口（与 #3272 文档一致，无变化）： - -``` -GET /admin/refund-note?resourceType=SCENIC&resourceId=12345 查 -PUT /admin/refund-note upsert 整块 -DELETE /admin/refund-note?resourceType=SCENIC&resourceId=12345 软删 -``` - -测试服已实测三个方法经网关全通（200）。仅 `SCENIC` / `ACTIVITY` 两类资源支持。 - ---- - -## 二、退费说明接入产品行程节点 + 订单快照（后端能力） - -行程节点绑定 SCENIC/ACTIVITY 资源时，产品详情聚合会回填该资源的退费说明；**下单时随产品详情整体冻进 `order_product_snapshot`**，锁定退费条款（资源后改不影响老订单）。 - -冻结结构（订单产品快照 `itinerary[].nodes[].refundNote`）： - -```jsonc -{ - "refundNote": { - "intro": "苔藓为赠送项目, 不退费", - "items": [ - { - "title": "成人未参加", - "amount": 44.00, - "unitLabel": "/人", - "settleScope": "PER_PERSON", - "settleScopeLabel": "按人", // 字典中文,冻结即定格 - "remark": "凭票退", - "effectiveFrom": null, - "effectiveTo": null - } - ] - } -} -``` - -仅 SCENIC/ACTIVITY 节点、且资源配过退费说明时才有值，其余节点 / 未配置为 `null`。 - ---- - -## 三、暂未做（前端注意） - -**订单详情「行程安排 Tab」暂不展示退费说明**。原因：订单 `order_itinerary_node` 表当前下单时不物化（仅后台手动编辑写入），退费说明冻在 `order_product_snapshot` JSON 里。要在行程 Tab 逐节点展示，需后续补「快照→节点叠加」或「下单物化行程」，**不在本期**。本期只保证：①退费说明 admin CRUD 可用 ②退费说明已正确冻进订单快照（数据已锁定，前端展示链路待后续 PR）。 - ---- - -## 四、踩坑修复（hotfix #3312） - -测试服建单实测发现退费说明进快照恒 null，直查资源接口暴露 **500 ClassCastException**：`JacksonTypeHandler` 反序列化 JSON 列 `List` 时泛型擦除，运行期元素是 `LinkedHashMap`，用 `List` 流式处理时 lambda 入口被插 CHECKCAST 在转换前就崩。已改 `List` + `BeanUtil` 兼容（#3272 Converter 同源潜伏 bug 一并修），并补 `LinkedHashMap` 模拟单测锁回归。对前端无感，仅说明为何要 hotfix。 - ---- - -## 五、影响评估 - -- **后端**：资源(DTO+批量查+ClassCast 修)、产品(节点回填)、订单(快照 VO)、网关(路由)；hl-common ResourceDetailDTO 加 refundNote 字段（非破坏） -- **前端**：可立即接入 `/admin/refund-note` CRUD（之前 404 不可用）；订单详情退费说明展示等后续 PR -- **存量订单**：仅新建订单冻结退费说明（快照语义），老订单不回填 - ---- - -## 关联 - -- **Issue**: [#3307](https://git.1814.love:8443/wx/HL/issues/3307) / [#3311](https://git.1814.love:8443/wx/HL/issues/3311) -- **PR**: [#3308](https://git.1814.love:8443/wx/HL/pulls/3308)（接入）/ [#3312](https://git.1814.love:8443/wx/HL/pulls/3312)（hotfix + 网关路由） -- **前置**: [#3273](https://git.1814.love:8443/wx/HL/pulls/3273)（#3272 退费说明 CRUD 模块） diff --git a/changelogs-v2/2026-06/01_3313_景区是否收费-修改接口-管理后台.md b/changelogs-v2/2026-06/01_3313_景区是否收费-修改接口-管理后台.md deleted file mode 100644 index aaa1599..0000000 --- a/changelogs-v2/2026-06/01_3313_景区是否收费-修改接口-管理后台.md +++ /dev/null @@ -1,280 +0,0 @@ -# 景区管理新增「是否收费」字段 - -- **端类型**：管理后台 -- **变更类型**：修改接口 -- **日期**：2026-06-01 -- **Issue**：[#3313](https://git.1814.love:8443/wx/HL/issues/3313) -- **PR**：[#3314](https://git.1814.love:8443/wx/HL/pulls/3314) -- **Commit**：[62bd9be](https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b) -- **后端负责人**：腰苏图（yst@1814.love） - ---- - -## ① 接口背景 - -景区资源新增「是否收费」属性，用于在管理后台创建/编辑景区时标记该景区是否需要游客付费（如收取门票费）。该字段同步透出到列表和详情接口，便于运营人员在列表页一眼识别收费/免费景区。字典来源 `sys_yes_no`，后端已配置，前端无需额外配置。 - ---- - -## ② 变更清单 - -| 接口 | 方法 | 路径 | 变更内容 | -|------|------|------|----------| -| 创建景区 | POST | `/admin/scenic/spot` | 入参新增 `isCharged`（Integer，默认 0） | -| 编辑景区 | PUT | `/admin/scenic/spot/{scenicId}` | 入参新增 `isCharged`（Integer，可选） | -| 景区详情 | GET | `/admin/scenic/spot/{scenicId}` | 出参新增 `isCharged` + `isChargedLabel` | -| 景区列表 | GET | `/admin/scenic/spots` | 出参新增 `isCharged` + `isChargedLabel` | - -所有变更均为**向后兼容新增字段**，不涉及字段改名或删除。 - ---- - -## ③ 接口详情 - -| 项目 | 说明 | -|------|------| -| **认证方式** | 管理后台 JWT Token，请求头 `Authorization: Bearer {token}` | -| **幂等性** | POST 创建非幂等；PUT 更新幂等（相同 scenicId 可重复调用） | -| **限流** | 无单独限流配置，走网关全局限流 | -| **权限** | 管理员角色，普通前端用户无访问权限 | - ---- - -## ④ 接口入参 - -### 4.1 路径参数 / Query 参数 - -**PUT `/admin/scenic/spot/{scenicId}`** - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| scenicId | Long | 是 | 景区 ID（路径参数） | - -**GET `/admin/scenic/spots`**（列表，原有参数不变，无新增查询参数） - -### 4.2 请求体字段（新增字段，含于已有请求体中） - -**POST `/admin/scenic/spot`**（`ScenicSpotCreateReqVO`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 | - -**PUT `/admin/scenic/spot/{scenicId}`**（`ScenicSpotUpdateReqVO`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 | - ---- - -## ⑤ 出参字段 - -### GET `/admin/scenic/spot/{scenicId}` 详情（`ScenicSpotVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - -### GET `/admin/scenic/spots` 列表（`ScenicSpotListVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - ---- - -## ⑥ 枚举 / 数据字典 - -### sys_yes_no 字典（后端已配置，前端无需维护） - -| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 | -|--------------------|-----------------------------|------| -| 1 | 是 | 该景区收费 | -| 0 | 否 | 该景区免费 | - -> `isChargedLabel` 由后端查字典自动翻译，前端可直接展示。若字典配置缺失（不正常情况），该字段返回 null。 - ---- - -## ⑦ 错误码 - -| 错误码 | HTTP 状态 | 场景 | -|--------|-----------|------| -| 400 | 400 | `isCharged` 传入非 0/1 的值（如 2、-1），Bean Validation 失败 | -| 401 | 401 | 未登录或 Token 失效 | -| 403 | 403 | 无管理员权限 | -| 404 | 404 | 景区 ID 不存在或已删除 | - ---- - -## ⑧ 示例 - -### 8.1 典型成功 — 创建收费景区 - -**请求** -``` -POST /admin/scenic/spot -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "呼伦贝尔大草原景区", - "province": "内蒙古自治区", - "city": "呼伦贝尔市", - "cityName": "呼伦贝尔", - "longitude": 119.758, - "latitude": 49.215, - "isCharged": 1 -} -``` - -**响应** -```json -{ - "code": 200, - "msg": "成功", - "data": { - "scenicId": "1900123456789000001", - "name": "呼伦贝尔大草原景区", - "isCharged": 1, - "isChargedLabel": "是", - "status": 0 - } -} -``` - -### 8.2 边界情况 — 不传 isCharged（使用默认值 0） - -**请求** -``` -POST /admin/scenic/spot -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "某免费公园", - "province": "内蒙古自治区", - "city": "呼伦贝尔市", - "cityName": "呼伦贝尔", - "longitude": 119.700, - "latitude": 49.200 -} -``` - -**响应**（isCharged 默认为 0） -```json -{ - "code": 200, - "msg": "成功", - "data": { - "scenicId": "1900123456789000002", - "name": "某免费公园", - "isCharged": 0, - "isChargedLabel": "否", - "status": 0 - } -} -``` - -### 8.3 业务失败 — isCharged 传入越界值 - -**请求** -``` -POST /admin/scenic/spot -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "测试景区", - "isCharged": 2 -} -``` - -**响应**（400 参数校验失败） -```json -{ - "code": 400, - "msg": "是否收费取值范围为0或1", - "data": null -} -``` - ---- - -## ⑨ 业务边界 - -**适用场景**： -- 创建新景区时，可设置是否收费标记（不传默认不收费） -- 编辑已有景区时，可随时修改是否收费状态（传 null 或不传则保持原值不变） -- 列表和详情页均可展示该字段，用于运营人员快速判断景区性质 - -**不适用场景**： -- 该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理） -- 不用于权限控制，仅作展示属性 - -**特殊边界**： -- 历史存量景区（PR #3314 上线前创建的）`isCharged` 默认为 0（否），`isChargedLabel` 返回 "否" -- PUT 编辑时若不传 `isCharged` 字段，该字段值保持不变（不会被清零） -- `isChargedLabel` 为 null 时属于字典配置异常，前端可用 `isCharged` 值自行映射（1→"是"，0→"否"）兜底 - ---- - -## ⑩ 修改前后对比 - -### 字段级对比 - -**入参（POST 创建 / PUT 编辑）** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，可选，默认 0（Create），可 null（Update） | - -**出参（详情 + 列表）** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 | -| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null | - -### 行为级对比 - -| 行为 | 变更前 | 变更后 | -|------|--------|--------| -| 创建景区 | 无收费标记 | 可设置 isCharged，默认 0 | -| 列表展示 | 无收费信息 | 新增 isCharged + isChargedLabel | -| 详情展示 | 无收费信息 | 新增 isCharged + isChargedLabel | - ---- - -## ⑪ 影响评估 / 回滚 - -**破坏兼容性**：无，新增字段均为可选，现有调用代码无需修改即可正常运行。 - -**前端同步上线**： -- 创建/编辑表单：可选接入 `isCharged` 开关/选择器，不接入则默认 0 -- 列表/详情页：可选展示 `isChargedLabel`，不展示也不影响功能 - -**回滚方案**： -- 若需回滚，执行 `ALTER TABLE scenic_spot DROP COLUMN is_charged;` 并回退服务部署 -- 前端零改动时回滚对前端无感 - ---- - -## ⑫ 注意事项 - -1. `isChargedLabel` 依赖字典 `sys_yes_no` 配置，后端已配置好，前端**不需要**维护字典表 -2. 列表接口返回 `isChargedLabel` 纯粹为展示便利，前端也可用 `isCharged` 值自行映射（1→"是"，0→"否"） -3. PUT 编辑时 `isCharged` 不传（null）表示不修改，区别于传 `0`（明确设置为否） -4. 历史数据库存量记录 `is_charged` 列已通过 DDL 添加默认值 0，无历史数据问题 - ---- - -## ⑬ 关联 / 联系人 - -- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3313](https://git.1814.love:8443/wx/HL/issues/3313) -- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3314](https://git.1814.love:8443/wx/HL/pulls/3314) -- **Commit**：[https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b](https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b) -- **后端负责人**：腰苏图（企微 / yst@1814.love） diff --git a/changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md b/changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md deleted file mode 100644 index 699bd54..0000000 --- a/changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md +++ /dev/null @@ -1,291 +0,0 @@ -# 餐厅管理新增「是否收费」字段 - -- **端类型**：管理后台 -- **变更类型**：修改接口 -- **日期**：2026-06-01 -- **Issue**：[#3317](https://git.1814.love:8443/wx/HL/issues/3317) -- **PR**：[#3318](https://git.1814.love:8443/wx/HL/pulls/3318) -- **Commit**：[3ad5860](https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804) -- **后端负责人**：腰苏图（yst@1814.love） - ---- - -## ① 接口背景 - -餐厅资源新增「是否收费」属性，用于在管理后台创建/编辑餐厅时标记该餐厅是否需要游客付费。该字段同步透出到列表和详情接口，便于运营人员在列表页一眼识别收费/免费餐厅。字典来源 `sys_yes_no`，后端已配置，前端无需额外配置。 - ---- - -## ② 变更清单 - -| 接口 | 方法 | 路径 | 变更内容 | -|------|------|------|----------| -| 创建餐厅 | POST | `/admin/restaurant/item` | 入参新增 `isCharged`（Integer，默认 0） | -| 更新餐厅 | PUT | `/admin/restaurant/item/{restaurantId}` | 入参新增 `isCharged`（Integer，可选） | -| 餐厅详情 | GET | `/admin/restaurant/item/{restaurantId}` | 出参新增 `isCharged` + `isChargedLabel` | -| 餐厅列表 | GET | `/admin/restaurant/items` | 出参新增 `isCharged` + `isChargedLabel` | - -所有变更均为**向后兼容新增字段**，不涉及字段改名或删除。 - ---- - -## ③ 接口详情 - -| 项目 | 说明 | -|------|------| -| **认证方式** | 管理后台 JWT Token，请求头 `Authorization: Bearer {token}` | -| **幂等性** | POST 创建非幂等；PUT 更新幂等（相同 restaurantId 可重复调用） | -| **限流** | 无单独限流配置，走网关全局限流 | -| **权限** | 管理员角色，普通前端用户无访问权限 | - ---- - -## ④ 接口入参 - -### 4.1 路径参数 / Query 参数 - -**PUT `/admin/restaurant/item/{restaurantId}`** - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| restaurantId | Long | 是 | 餐厅 ID（路径参数） | - -**GET `/admin/restaurant/items`**（列表，原有参数不变，无新增查询参数） - -### 4.2 请求体字段（新增字段，含于已有请求体中） - -**POST `/admin/restaurant/item`**（`RestaurantCreateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 | - -**PUT `/admin/restaurant/item/{restaurantId}`**（`RestaurantUpdateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 | - ---- - -## ⑤ 出参字段 - -### GET `/admin/restaurant/item/{restaurantId}` 详情（`RestaurantVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - -### GET `/admin/restaurant/items` 列表（`RestaurantListVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - ---- - -## ⑥ 枚举 / 数据字典 - -### sys_yes_no 字典（后端已配置，前端无需维护） - -| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 | -|--------------------|-----------------------------|------| -| 1 | 是 | 该餐厅收费 | -| 0 | 否 | 该餐厅免费 | - -> `isChargedLabel` 由后端查字典自动翻译，前端可直接展示。若字典配置缺失（不正常情况），该字段返回 null，前端建议展示"-"或不显示。 - ---- - -## ⑦ 错误码 - -| 错误码 | HTTP 状态 | 场景 | -|--------|-----------|------| -| 400 | 400 | `isCharged` 传入非 0/1 的值（如 2、-1），Bean Validation 失败 | -| 401 | 401 | 未登录或 Token 失效 | -| 403 | 403 | 无管理员权限 | -| 404 | 404 | 餐厅 ID 不存在或已删除 | - ---- - -## ⑧ 示例 - -### 8.1 典型成功 — 创建收费餐厅 - -**请求** -``` -POST /admin/restaurant/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "云端藏餐", - "categoryCode": "TIBETAN", - "province": "西藏自治区", - "city": "拉萨市", - "cityName": "拉萨", - "longitude": 91.132, - "latitude": 29.660, - "isCharged": 1 -} -``` - -**响应** -```json -{ - "code": 200, - "msg": "成功", - "data": { - "restaurantId": "1927000000000001", - "name": "云端藏餐", - "isCharged": 1, - "isChargedLabel": "是", - "status": 0, - ... - } -} -``` - -### 8.2 边界情况 — 不传 isCharged（使用默认值 0） - -**请求** -``` -POST /admin/restaurant/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "免费体验餐厅", - "categoryCode": "CHINESE", - "province": "西藏自治区", - "city": "拉萨市", - "cityName": "拉萨", - "longitude": 91.100, - "latitude": 29.650 - // isCharged 字段不传 -} -``` - -**响应**（isCharged 默认为 0） -```json -{ - "code": 200, - "msg": "成功", - "data": { - "restaurantId": "1927000000000002", - "name": "免费体验餐厅", - "isCharged": 0, - "isChargedLabel": "否", - "status": 0, - ... - } -} -``` - -### 8.3 业务失败 — isCharged 传入越界值 - -**请求** -``` -POST /admin/restaurant/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "测试餐厅", - "categoryCode": "CHINESE", - "province": "西藏自治区", - "city": "拉萨市", - "cityName": "拉萨", - "longitude": 91.100, - "latitude": 29.650, - "isCharged": 2 -} -``` - -**响应**（400 参数校验失败） -```json -{ - "code": 400, - "msg": "是否收费取值范围为0或1", - "data": null -} -``` - ---- - -## ⑨ 业务边界 - -**适用场景**： -- 创建新餐厅时，可设置是否收费标记（不传默认不收费） -- 编辑已有餐厅时，可随时修改是否收费状态（传 null 或不传则保持原值不变） -- 列表和详情页均可展示该字段，用于运营人员快速判断餐厅性质 - -**不适用场景**： -- 该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理） -- 不用于权限控制，仅作展示属性 - -**特殊边界**： -- 历史存量餐厅（PR #3318 上线前创建的）`isCharged` 默认为 0（否），`isChargedLabel` 返回 "否" -- PUT 更新时若不传 `isCharged` 字段，该字段值保持不变（不会被清零） -- `isChargedLabel` 为 null 时属于字典配置异常，业务上可展示 "-" 兜底 - ---- - -## ⑩ 修改前后对比 - -### 字段级对比 - -**入参（POST 创建 / PUT 更新）** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，可选，默认 0（Create），可 null（Update） | - -**出参（详情 + 列表）** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 | -| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null | - -### 行为级对比 - -| 行为 | 变更前 | 变更后 | -|------|--------|--------| -| 创建餐厅 | 无收费标记 | 可设置 isCharged，默认 0 | -| 列表展示 | 无收费信息 | 新增 isCharged + isChargedLabel | -| 详情展示 | 无收费信息 | 新增 isCharged + isChargedLabel | - ---- - -## ⑪ 影响评估 / 回滚 - -**破坏兼容性**：无，新增字段均为可选，现有调用代码无需修改即可正常运行。 - -**前端同步上线**： -- 创建/编辑表单：可选接入 `isCharged` 开关/选择器，不接入则默认 0 -- 列表/详情页：可选展示 `isChargedLabel`，不展示也不影响功能 - -**回滚方案**： -- 若需回滚，执行 `ALTER TABLE restaurant DROP COLUMN is_charged;` 并回退服务部署 -- 前端零改动时回滚对前端无感 - ---- - -## ⑫ 注意事项 - -1. `isChargedLabel` 依赖字典 `sys_yes_no` 配置，后端已配置好，前端**不需要**维护字典表 -2. 列表接口返回 `isChargedLabel` 纯粹为展示便利，前端也可用 `isCharged` 值自行映射（1→"是"，0→"否"） -3. PUT 更新时 `isCharged` 不传（null）表示不修改，区别于传 `0`（明确设置为否） -4. 历史数据库存量记录 `is_charged` 列已通过 DDL 添加默认值 0，无历史数据问题 - ---- - -## ⑬ 关联 / 联系人 - -- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3317](https://git.1814.love:8443/wx/HL/issues/3317) -- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3318](https://git.1814.love:8443/wx/HL/pulls/3318) -- **Commit**：[https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804](https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804) -- **后端负责人**：腰苏图（企微 / yst@1814.love） diff --git a/changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md b/changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md deleted file mode 100644 index 8f490bd..0000000 --- a/changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md +++ /dev/null @@ -1,282 +0,0 @@ -# 酒店管理新增「是否收费」字段 - -- **端类型**：管理后台 -- **变更类型**：修改接口 -- **日期**：2026-06-01 -- **Issue**：[#3325](https://git.1814.love:8443/wx/HL/issues/3325) -- **PR**：[#3326](https://git.1814.love:8443/wx/HL/pulls/3326) -- **Commit**：[58afda7](https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c) -- **后端负责人**：腰苏图（yst@1814.love） - ---- - -## ① 接口背景 - -酒店资源新增「是否收费」属性，用于在管理后台创建/编辑酒店时标记该酒店是否需要游客付费。该字段同步透出到列表和详情接口，便于运营人员在列表页一眼识别收费/免费酒店。字典来源 `sys_yes_no`，后端已配置，前端无需额外配置。 - ---- - -## ② 变更清单 - -| 接口 | 方法 | 路径 | 变更内容 | -|------|------|------|----------| -| 创建酒店 | POST | `/admin/hotel/item` | 入参新增 `isCharged`（Integer，默认 0） | -| 更新酒店 | PUT | `/admin/hotel/item/{hotelId}` | 入参新增 `isCharged`（Integer，可选） | -| 酒店详情 | GET | `/admin/hotel/item/{hotelId}` | 出参新增 `isCharged` + `isChargedLabel` | -| 酒店列表 | GET | `/admin/hotel/items` | 出参新增 `isCharged` + `isChargedLabel` | - -所有变更均为**向后兼容新增字段**，不涉及字段改名或删除。 - ---- - -## ③ 接口详情 - -| 项目 | 说明 | -|------|------| -| **认证方式** | 管理后台 JWT Token，请求头 `Authorization: Bearer {token}` | -| **幂等性** | POST 创建非幂等；PUT 更新幂等（相同 hotelId 可重复调用） | -| **限流** | 无单独限流配置，走网关全局限流 | -| **权限** | 管理员角色，普通前端用户无访问权限 | - ---- - -## ④ 接口入参 - -### 4.1 路径参数 / Query 参数 - -**PUT `/admin/hotel/item/{hotelId}`** - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| hotelId | Long | 是 | 酒店 ID（路径参数） | - -**GET `/admin/hotel/items`**（列表，原有参数不变，无新增查询参数） - -### 4.2 请求体字段（新增字段，含于已有请求体中） - -**POST `/admin/hotel/item`**（`HotelCreateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 | - -**PUT `/admin/hotel/item/{hotelId}`**（`HotelUpdateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 | - ---- - -## ⑤ 出参字段 - -### GET `/admin/hotel/item/{hotelId}` 详情（`HotelVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - -### GET `/admin/hotel/items` 列表（`HotelListVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - ---- - -## ⑥ 枚举 / 数据字典 - -### sys_yes_no 字典（后端已配置，前端无需维护） - -| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 | -|--------------------|-----------------------------|------| -| 1 | 是 | 该酒店收费 | -| 0 | 否 | 该酒店免费 | - -> `isChargedLabel` 由后端查字典自动翻译，前端可直接展示。若字典配置缺失（不正常情况），该字段返回 null。 - ---- - -## ⑦ 错误码 - -| 错误码 | HTTP 状态 | 场景 | -|--------|-----------|------| -| 400 | 400 | `isCharged` 传入非 0/1 的值（如 2、-1），Bean Validation 失败 | -| 401 | 401 | 未登录或 Token 失效 | -| 403 | 403 | 无管理员权限 | -| 404 | 404 | 酒店 ID 不存在或已删除 | - ---- - -## ⑧ 示例 - -### 8.1 典型成功 — 创建收费酒店 - -**请求** -``` -POST /admin/hotel/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "丽江悦榕庄", - "hotelType": "HOTEL", - "address": "束河古镇悦榕路1号", - "longitude": 100.2134, - "latitude": 26.8721, - "isCharged": 1 -} -``` - -**响应** -```json -{ - "code": 200, - "msg": "成功", - "data": { - "hotelId": "1928000000000001", - "name": "丽江悦榕庄", - "isCharged": 1, - "isChargedLabel": "是", - "status": 0 - } -} -``` - -### 8.2 边界情况 — 不传 isCharged（使用默认值 0） - -**请求** -``` -POST /admin/hotel/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "团队免费住宿点", - "hotelType": "HOSTEL", - "address": "丽江古城区某路1号", - "longitude": 100.2200, - "latitude": 26.8800 -} -``` - -**响应**（isCharged 默认为 0） -```json -{ - "code": 200, - "msg": "成功", - "data": { - "hotelId": "1928000000000002", - "name": "团队免费住宿点", - "isCharged": 0, - "isChargedLabel": "否", - "status": 0 - } -} -``` - -### 8.3 业务失败 — isCharged 传入越界值 - -**请求** -``` -POST /admin/hotel/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "测试酒店", - "hotelType": "HOTEL", - "address": "测试地址", - "longitude": 100.0, - "latitude": 26.0, - "isCharged": 2 -} -``` - -**响应**（400 参数校验失败） -```json -{ - "code": 400, - "msg": "是否收费取值范围为0或1", - "data": null -} -``` - ---- - -## ⑨ 业务边界 - -**适用场景**： -- 创建新酒店时，可设置是否收费标记（不传默认不收费） -- 编辑已有酒店时，可随时修改是否收费状态（传 null 或不传则保持原值不变） -- 列表和详情页均可展示该字段，用于运营人员快速判断酒店性质 - -**不适用场景**： -- 该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理） -- 不用于权限控制，仅作展示属性 - -**特殊边界**： -- 历史存量酒店（PR #3326 上线前创建的）`isCharged` 默认为 0（否），`isChargedLabel` 返回 "否" -- PUT 更新时若不传 `isCharged` 字段，该字段值保持不变（不会被清零） -- `isChargedLabel` 为 null 时属于字典配置异常，非正常情况 - ---- - -## ⑩ 修改前后对比 - -### 字段级对比 - -**入参（POST 创建 / PUT 更新）** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，可选，默认 0（Create），可 null（Update） | - -**出参（详情 + 列表）** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 | -| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null | - -### 行为级对比 - -| 行为 | 变更前 | 变更后 | -|------|--------|--------| -| 创建酒店 | 无收费标记 | 可设置 isCharged，默认 0 | -| 列表展示 | 无收费信息 | 新增 isCharged + isChargedLabel | -| 详情展示 | 无收费信息 | 新增 isCharged + isChargedLabel | - ---- - -## ⑪ 影响评估 / 回滚 - -**破坏兼容性**：无，新增字段均为可选，现有调用代码无需修改即可正常运行。 - -**前端同步上线**： -- 创建/编辑表单：可选接入 `isCharged` 开关/选择器，不接入则默认 0 -- 列表/详情页：可选展示 `isChargedLabel`，不展示也不影响功能 - -**回滚方案**： -- 若需回滚，执行 `ALTER TABLE hotel DROP COLUMN is_charged;` 并回退服务部署 -- 前端零改动时回滚对前端无感 - ---- - -## ⑫ 注意事项 - -1. `isChargedLabel` 依赖字典 `sys_yes_no` 配置，后端已配置好，前端**不需要**维护字典表 -2. 列表接口返回 `isChargedLabel` 纯粹为展示便利，前端也可用 `isCharged` 值自行映射（1→"是"，0→"否"） -3. PUT 更新时 `isCharged` 不传（null）表示不修改，区别于传 `0`（明确设置为否） -4. 历史数据库存量记录 `is_charged` 列已通过 DDL 添加默认值 0，无历史数据问题 - ---- - -## ⑬ 关联 / 联系人 - -- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3325](https://git.1814.love:8443/wx/HL/issues/3325) -- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3326](https://git.1814.love:8443/wx/HL/pulls/3326) -- **Commit**：[https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c](https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c) -- **后端负责人**：腰苏图（企微 / yst@1814.love） diff --git a/changelogs-v2/2026-06/01_3331_活动物资是否收费-修改接口-管理后台.md b/changelogs-v2/2026-06/01_3331_活动物资是否收费-修改接口-管理后台.md deleted file mode 100644 index 81499d5..0000000 --- a/changelogs-v2/2026-06/01_3331_活动物资是否收费-修改接口-管理后台.md +++ /dev/null @@ -1,321 +0,0 @@ -# 游玩项目（活动）+ 备品（物资）新增「是否收费」字段 - -- **端类型**：管理后台 -- **变更类型**：修改接口 -- **日期**：2026-06-01 -- **Issue**：[#3331](https://git.1814.love:8443/wx/HL/issues/3331) -- **PR**：[#3334](https://git.1814.love:8443/wx/HL/pulls/3334) -- **Commit**：[5da05a3](https://git.1814.love:8443/wx/HL/commit/5da05a324813cf8109d35c521c5e7bb9719627be) -- **后端负责人**：腰苏图（yst@1814.love） - ---- - -## ① 接口背景 - -游玩项目（活动）和备品（物资）两个资源域同步新增「是否收费」属性，用于在管理后台创建/编辑时标记该资源是否需要游客付费。该字段同步透出到各自的列表和详情接口，便于运营人员在列表页快速识别收费/免费资源。字典来源 `sys_yes_no`，后端已配置，前端无需额外配置。 - ---- - -## ② 变更清单 - -### 游玩项目（ActivityController `/admin/activity`） - -| 接口 | 方法 | 路径 | 变更内容 | -|------|------|------|----------| -| 创建游玩项目 | POST | `/admin/activity/item` | 入参新增 `isCharged`（Integer，默认 0） | -| 更新游玩项目 | PUT | `/admin/activity/item/{activityId}` | 入参新增 `isCharged`（Integer，可选） | -| 游玩项目详情 | GET | `/admin/activity/item/{activityId}` | 出参新增 `isCharged` + `isChargedLabel` | -| 游玩项目列表 | GET | `/admin/activity/items` | 出参新增 `isCharged` + `isChargedLabel` | - -### 备品（SuppliesController `/admin/supplies`） - -| 接口 | 方法 | 路径 | 变更内容 | -|------|------|------|----------| -| 创建备品 | POST | `/admin/supplies/item` | 入参新增 `isCharged`（Integer，默认 0） | -| 更新备品 | PUT | `/admin/supplies/item/{suppliesId}` | 入参新增 `isCharged`（Integer，可选） | -| 备品详情 | GET | `/admin/supplies/item/{suppliesId}` | 出参新增 `isCharged` + `isChargedLabel` | -| 备品列表 | GET | `/admin/supplies/items` | 出参新增 `isCharged` + `isChargedLabel` | - -所有变更均为**向后兼容新增字段**，不涉及字段改名或删除。 - ---- - -## ③ 接口详情 - -| 项目 | 说明 | -|------|------| -| **认证方式** | 管理后台 JWT Token，请求头 `Authorization: Bearer {token}` | -| **幂等性** | POST 创建非幂等；PUT 更新幂等（相同 activityId / suppliesId 可重复调用） | -| **限流** | 无单独限流配置，走网关全局限流 | -| **权限** | 管理员角色，普通前端用户无访问权限 | - ---- - -## ④ 接口入参 - -### 4.1 路径参数 / Query 参数 - -**PUT `/admin/activity/item/{activityId}`** - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| activityId | Long | 是 | 游玩项目 ID（路径参数） | - -**PUT `/admin/supplies/item/{suppliesId}`** - -| 参数名 | 类型 | 必填 | 说明 | -|--------|------|------|------| -| suppliesId | Long | 是 | 备品 ID（路径参数） | - -**GET `/admin/activity/items`** 和 **GET `/admin/supplies/items`**（列表，原有 Query 参数不变，无新增查询参数） - -### 4.2 请求体字段（新增字段） - -**POST `/admin/activity/item`**（`ActivityCreateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 | - -**PUT `/admin/activity/item/{activityId}`**（`ActivityUpdateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 | - -**POST `/admin/supplies/item`**（`SuppliesCreateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 | - -**PUT `/admin/supplies/item/{suppliesId}`**（`SuppliesUpdateRequest`，新增字段） - -| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 | -|--------|------|------|----------|--------|------| -| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 | - ---- - -## ⑤ 出参字段 - -### GET `/admin/activity/item/{activityId}` 详情（`ActivityVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - -### GET `/admin/activity/items` 列表（`ActivityListVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - -### GET `/admin/supplies/item/{suppliesId}` 详情（`SuppliesVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - -### GET `/admin/supplies/items` 列表（`SuppliesListVO`，新增字段） - -| 字段名 | 类型 | 说明 | 可能为 null | -|--------|------|------|-------------| -| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） | -| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） | - ---- - -## ⑥ 枚举 / 数据字典 - -### sys_yes_no 字典（后端已配置，前端无需维护） - -| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 | -|--------------------|-----------------------------|------| -| 1 | 是 | 该资源收费 | -| 0 | 否 | 该资源免费 | - -> `isChargedLabel` 由后端查字典自动翻译，前端可直接展示。若字典配置缺失（不正常情况），该字段返回 null。 - ---- - -## ⑦ 错误码 - -| 错误码 | HTTP 状态 | 场景 | -|--------|-----------|------| -| 400 | 400 | `isCharged` 传入非 0/1 的值（如 2、-1），Bean Validation 失败，msg="是否收费取值范围为0或1" | -| 401 | 401 | 未登录或 Token 失效 | -| 403 | 403 | 无管理员权限 | -| 404 | 404 | 资源 ID 不存在或已删除 | - ---- - -## ⑧ 示例 - -### 8.1 典型成功 — 创建收费游玩项目 - -**请求** -``` -POST /admin/activity/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "高原骑马体验", - "categoryCode": "OUTDOOR", - "isCharged": 1 -} -``` - -**响应** -```json -{ - "code": 200, - "msg": "成功", - "data": { - "activityId": "1929000000000001", - "name": "高原骑马体验", - "categoryCode": "OUTDOOR", - "isCharged": 1, - "isChargedLabel": "是", - "status": 0 - } -} -``` - -### 8.2 边界情况 — 创建备品时不传 isCharged（默认 0） - -**请求** -``` -POST /admin/supplies/item -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "登山杖", - "categoryCode": "OUTDOOR_GEAR", - "billingType": "PER_ITEM", - "basePrice": 25.00 -} -``` - -**响应**（isCharged 默认为 0） -```json -{ - "code": 200, - "msg": "成功", - "data": { - "suppliesId": "1929000000000002", - "name": "登山杖", - "billingType": "PER_ITEM", - "isCharged": 0, - "isChargedLabel": "否", - "status": 0 - } -} -``` - -### 8.3 业务失败 — isCharged 传入越界值 - -**请求** -``` -PUT /admin/activity/item/1929000000000001 -Authorization: Bearer {admin_token} -Content-Type: application/json - -{ - "name": "高原骑马体验", - "isCharged": 2 -} -``` - -**响应**（400 参数校验失败） -```json -{ - "code": 400, - "msg": "是否收费取值范围为0或1", - "data": null -} -``` - ---- - -## ⑨ 业务边界 - -**适用场景**： -- 创建/编辑游玩项目或备品时，可设置是否收费标记（不传默认不收费） -- 列表和详情页均展示该字段，供运营人员快速识别资源收费属性 - -**不适用场景**： -- 该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理） -- 不用于权限控制，仅作展示属性 - -**特殊边界**： -- 历史存量游玩项目和备品（PR #3334 上线前创建的）`isCharged` 默认为 0，`isChargedLabel` 返回 "否" -- PUT 更新时若不传 `isCharged` 字段（null），该字段值保持不变（不会被清零），区别于传 `0`（明确设置为否） -- `isChargedLabel` 为 null 时属于字典配置异常，非正常情况 - ---- - -## ⑩ 修改前后对比 - -### 字段级对比 - -**入参（POST 创建 / PUT 更新）—— 游玩项目和备品相同** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，可选，默认 0（Create），null 不修改（Update） | - -**出参（详情 + 列表）—— 游玩项目和备品相同** - -| 字段名 | 变更前 | 变更后 | -|--------|--------|--------| -| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 | -| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null | - -### 行为级对比 - -| 行为 | 变更前 | 变更后 | -|------|--------|--------| -| 创建游玩项目 / 备品 | 无收费标记 | 可设置 isCharged，默认 0 | -| 列表展示 | 无收费信息 | 新增 isCharged + isChargedLabel | -| 详情展示 | 无收费信息 | 新增 isCharged + isChargedLabel | - ---- - -## ⑪ 影响评估 / 回滚 - -**破坏兼容性**：无，新增字段均为可选，现有调用代码无需修改即可正常运行。 - -**前端同步上线**： -- 创建/编辑表单：可选接入 `isCharged` 开关/选择器，不接入则默认提交 0（不收费） -- 列表/详情页：可选展示 `isChargedLabel`，不展示也不影响功能 - -**回滚方案**： -- 若需回滚，分别执行以下 DDL 并回退服务部署： - - `ALTER TABLE activity DROP COLUMN is_charged;` - - `ALTER TABLE supplies_item DROP COLUMN is_charged;` -- 前端零改动时回滚对前端无感 - ---- - -## ⑫ 注意事项 - -1. `isChargedLabel` 依赖字典 `sys_yes_no` 配置，后端已配置好，前端**不需要**维护字典表 -2. 列表接口返回 `isChargedLabel` 纯粹为展示便利，前端也可用 `isCharged` 值自行映射（1→"是"，0→"否"） -3. PUT 更新时 `isCharged` 不传（null）表示不修改，区别于传 `0`（明确设置为否） -4. 游玩项目和备品两个域的字段命名、类型、字典完全一致，调用逻辑相同 -5. 历史数据库存量记录 `is_charged` 列已通过 DDL 添加默认值 0，无历史数据问题 - ---- - -## ⑬ 关联 / 联系人 - -- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3331](https://git.1814.love:8443/wx/HL/issues/3331) -- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3334](https://git.1814.love:8443/wx/HL/pulls/3334) -- **Commit**：[https://git.1814.love:8443/wx/HL/commit/5da05a324813cf8109d35c521c5e7bb9719627be](https://git.1814.love:8443/wx/HL/commit/5da05a324813cf8109d35c521c5e7bb9719627be) -- **后端负责人**：腰苏图（企微 / yst@1814.love） diff --git a/changelogs-v2/2026-06/02_3354_订单服务标准-退费说明修复.md b/changelogs-v2/2026-06/02_3354_订单服务标准-退费说明修复.md deleted file mode 100644 index 78c60bb..0000000 --- a/changelogs-v2/2026-06/02_3354_订单服务标准-退费说明修复.md +++ /dev/null @@ -1,58 +0,0 @@ -# 订单详情「服务标准」Tab 退费说明（refundNotes）修复——现可正确返回数据 - -- **端类型**：管理后台 -- **变更类型**：缺陷修复（接口结构不变，仅恢复数据流） -- **日期**：2026-06-02 -- **Issue**：[#3354](https://git.1814.love:8443/wx/HL/issues/3354) -- **PR**：[#3355](https://git.1814.love:8443/wx/HL/pulls/3355) -- **Commit**：[db61c2d](https://git.1814.love:8443/wx/HL/commit/db61c2da1193be0e0954dacdfd8f154e3ba5d912) -- **后端负责人**：wx - ---- - -## ① 背景 - -订单详情「服务标准」Tab 接口（`GET /v3/admin/order/{id}/service-standard`，#3340 已上线的聚合结构）中，`refundNotes`（退费说明）字段此前一直返回空数组，即使绑定资源已配置退费说明。 - -根因是**资源退费说明根本存不进库**：资源服务自定义的字段自动填充处理器只填一期命名字段（createdAt/updatedAt），漏填二期命名字段（createTime），导致退费说明保存接口报错（create_time 不能为空），全表 0 条存活记录 → 下单冻快照时节点 `refundNote` 恒 null → 服务标准 Tab 退费说明永远为空。 - -本次修复后端自动填充处理器，退费说明可正常保存并随订单快照冻结。 - ---- - -## ② 变更清单 - -**接口结构无任何变化**（`refundNotes` 字段在 #3340 已定义）。修复后行为： - -| 接口 | 方法 | 路径 | 变更内容 | -|------|------|------|----------| -| 订单服务标准 | GET | `/v3/admin/order/{id}/service-standard` | `refundNotes` 现对「绑定了退费说明的 SCENIC/ACTIVITY 行程节点」正确返回数据（修复前恒为空） | - -`refundNotes[]` 结构（不变，复述）： - -``` -refundNotes: [ - { - sourceName, // 来源点位名称，如「呼和诺尔草原旅游区」 - intro, // 退费说明备注 - items: [ - { title, amount, unitLabel, settleScope, settleScopeLabel, remark, effectiveFrom, effectiveTo } - ] - } -] -``` - -测试服实测（订单 2061673442020651009）：`refundNotes` = 呼和诺尔草原旅游区 → [成人未参加 ¥44 /人（按人）, 整团未到 ¥100 /团（按团）]，`settleScopeLabel` 字典中文已正确解析。 - ---- - -## ③ 前端动作 - -**无需改动**。#3340 前端已对接 `refundNotes` 结构，仅需知悉：之前看到的退费说明为空是后端缺陷，现已修复，对已配置退费说明的资源会正常返回。 - ---- - -## ④ 备注 - -- 同一 Tab 的「出团注意事项」（`notices`）能否有数据，取决于**产品是否配置了「服务标准模板」**（产品域 Step5 补充信息配置项）。当前测试库暂无产品配置该模板，故 `notices` 仍为空；这属于数据配置，非接口缺陷，与本次修复无关。 -- 「行程」（`itinerary`）一直正常。 diff --git a/changelogs-v2/2026-06/02_3363_订单服务标准接口返回成品数据+notices加title-修改接口-管理后台.md b/changelogs-v2/2026-06/02_3363_订单服务标准接口返回成品数据+notices加title-修改接口-管理后台.md deleted file mode 100644 index e060d5d..0000000 --- a/changelogs-v2/2026-06/02_3363_订单服务标准接口返回成品数据+notices加title-修改接口-管理后台.md +++ /dev/null @@ -1,182 +0,0 @@ -# 二期 v3：订单详情「服务标准」Tab 接口返回真实成品数据 + notices 新增 title 字段 - -> **服务**: hl-order-service-v3（产品侧 hl-product-service-v2 配合改造，前端无感） -> **端**: 管理后台 -> **接口**: `GET /v3/admin/order/{id}/service-standard`（订单详情 - 服务标准 Tab） -> **类型**: ✏️ 修改接口（出参 `notices[]` 新增 `title` 字段 + 接口由恒空改为返回真实成品） -> **日期**: 2026-06-02 -> **关联**: Issue #3363 / PR #3364（前序 #3340 建接口、#3353 改只读快照） - ---- - -## 一句话结论 - -1. 该接口此前对**所有订单恒返 `data: null`**（产品侧没生产服务标准成品）。本次产品侧补上生产端，**新下单的订单**会返回完整服务标准成品（标题 / 简介 / 服务承诺 / 行程 / 退费说明）。 -2. 出参 `notices[]`（服务承诺条目）**每条新增 `title` 字段**。 - -> ⚠️ 仅对**部署之后新创建**的订单生效。部署前的老订单仍返 `null`（其快照未冻入成品）。开发阶段老订单可忽略。 - ---- - -## 出参结构（完整，自包含） - -`data` 类型 `ServiceStandardVO`，`data` 为 `null` 表示该订单无服务标准成品。 - -| 字段 | 类型 | 说明 | 可空 | -|---|---|---|---| -| `title` | string | 标题，固定为 `"出团服务标准·" + 产品名`；产品名为空时退化为 `"出团服务标准"` | 否 | -| `subtitle` | string | 副标题 | **本期恒 null** | -| `intro` | string | 服务标准简介 | 是（产品未配服务标准模板时为 null） | -| `notices` | NoticeItem[] | 服务承诺条目（扁平，无分组） | 是（无源时为空数组 `[]`） | -| `itinerary` | DayVO[] | 行程逐天列表 | 是（无行程时空数组） | -| `refundNotes` | RefundNoteGroup[] | 退费说明分组（按行程节点聚合） | 是（无退费说明时空数组） | - -### NoticeItem（服务承诺条目） - -| 字段 | 类型 | 说明 | 可空 | -|---|---|---|---| -| `title` | string | **本次新增**。条目主文案标题（如「专业司机」） | 是 | -| `content` | string | 正文（如「持有 A1 驾照，8 年以上驾龄」） | 是 | -| `remark` | string | 备注 / 灰色二级说明 | 是 | -| `color` | string | 文案颜色 `#RRGGBB` | 是 | -| `contactName` | string | 联系人 | 是 | -| `phone` | string | 手机号 | 是 | - -### DayVO（行程天） - -| 字段 | 类型 | 说明 | 可空 | -|---|---|---|---| -| `dayNumber` | integer | 天序号（从 1 起） | 否 | -| `dayTitle` | string | 天标题（如「第一天-接机」） | 是 | -| `remark` | string | 当天备注 | **本期恒 null** | -| `itineraryNode` | ItineraryNode[] | 当天点位列表 | 是 | - -### ItineraryNode（行程点位） - -| 字段 | 类型 | 说明 | 可空 | -|---|---|---|---| -| `nodeName` | string | 点位名称（如「呼和诺尔草原旅游区」「早餐」） | 否 | -| `description` | string | 点位描述 | 是 | -| `contactName` | string | 联系人 | **本期恒 null** | -| `phone` | string | 手机号 | **本期恒 null** | - -### RefundNoteGroup（退费说明分组） - -| 字段 | 类型 | 说明 | 可空 | -|---|---|---|---| -| `sourceName` | string | 来源点位名称（取行程节点名） | 否 | -| `intro` | string | 退费说明备注（如「苔藓为赠送项目，不退费」） | 是 | -| `items` | RefundItem[] | 退费明细列表 | 是 | - -### RefundItem（退费明细条目） - -| 字段 | 类型 | 说明 | 可空 | -|---|---|---|---| -| `title` | string | 展示标题（如「成人未参加」） | 是 | -| `amount` | number | 退费金额（赠送项目为 0） | 是 | -| `unitLabel` | string | 展示文案：`/人` `/团` `/辆` | 是 | -| `settleScope` | string | 结算粒度枚举（见下） | 是 | -| `settleScopeLabel` | string | 结算粒度中文（冻结即定格） | 是 | -| `remark` | string | 备注 | 是 | -| `effectiveFrom` | string(date) | 规则生效起日，`null` = 无限制 | 是 | -| `effectiveTo` | string(date) | 规则生效止日，`null` = 无限制 | 是 | - ---- - -## 枚举 / 数据字典 - -### settleScope（结算粒度） - -| 枚举值 | settleScopeLabel（中文） | 配套 unitLabel | -|---|---|---| -| `PER_PERSON` | 按人 | /人 | -| `PER_TEAM` | 按团 | /团 | -| `PER_VEHICLE` | 按车 | /辆 | - -> `settleScopeLabel` 在下单时随快照冻结，定格当时字典中文，资源后改不影响老订单。 - ---- - -## 请求示例 - -``` -GET /v3/admin/order/2061762043987247105/service-standard -Authorization: Bearer {adminToken} -``` - -## 响应示例（真实，测试服 dev-v3 实测） - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "title": "出团服务标准·测试核心产品-单档-固定订金", - "subtitle": null, - "intro": "全程贴心服务保障", - "notices": [ - { - "title": "专业司机", - "content": "持有A1驾照,8年以上驾龄", - "remark": "仅限指定时段", - "color": "#FF6600", - "contactName": "李师傅", - "phone": "13800000000" - } - ], - "itinerary": [ - { - "dayNumber": 1, - "dayTitle": "第一天-接机", - "remark": null, - "itineraryNode": [ - { "nodeName": "海拉尔接机", "description": null, "contactName": null, "phone": null }, - { "nodeName": "早餐", "description": "含(酒店)", "contactName": null, "phone": null } - ] - } - ], - "refundNotes": [ - { - "sourceName": "呼和诺尔草原旅游区", - "intro": "苔藓为赠送项目，不退费", - "items": [ - { - "title": "成人未参加", "amount": 44.0, "unitLabel": "/人", - "settleScope": "PER_PERSON", "settleScopeLabel": "按人", - "remark": "凭票退", "effectiveFrom": null, "effectiveTo": null - }, - { - "title": "整团未到", "amount": 100.0, "unitLabel": "/团", - "settleScope": "PER_TEAM", "settleScopeLabel": "按团", - "remark": null, "effectiveFrom": null, "effectiveTo": null - } - ] - } - ] - } -} -``` - -## 响应示例（老订单 / 无成品） - -```json -{ "code": 200, "message": "成功", "success": true, "data": null } -``` - ---- - -## 业务边界 / 注意事项 - -- `data: null` 是合法返回，表示该订单无服务标准成品（部署前老订单 / 产品未配服务标准）。 -- `intro`、`notices` 来源于产品「服务标准模板」：产品未绑模板时，`intro` 为 `null`、`notices` 为 `[]`，但 `title` / `itinerary` / `refundNotes`（有各自数据源时）仍正常返回。 -- `subtitle`、`DayVO.remark`、`ItineraryNode.contactName/phone` 本期固定为 `null`（预留字段）。 -- 成品在下单时随产品快照整体冻结，资源 / 产品后续修改不影响已下单订单。 - ---- - -## 关联 - -- Issue: https://git.1814.love:8443/wx/HL/issues/3363 -- PR: https://git.1814.love:8443/wx/HL/pulls/3364 -- 前序: #3340（建接口）/ #3353（改只读快照） diff --git a/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md b/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md deleted file mode 100644 index c431c72..0000000 --- a/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md +++ /dev/null @@ -1,155 +0,0 @@ -# 二期 v3：订单进度模型重构 —— 派生线性 6 步 + 嵌套 progressStepper - -> **服务**: hl-order-service-v3 ｜ **端**: 管理后台 -> **接口**: `GET /v3/admin/order`（列表）、`GET /v3/admin/order/{id}`（详情）、`POST /v3/admin/order`（创建） -> **Issue**: #3365 / #3368 ｜ **PR**: #3366（扁平）+ #3369（嵌套） -> **日期**: 2026-06-03 -> **影响**: ⚠️ **破坏性**——删字段 + 改结构。订单进度展示统一为「派生线性 6 步 + 嵌套 progressStepper」。 - ---- - -## 一、背景 - -订单进度此前两套打架：列表用 8 步 `flowStep`，详情用 10 节点 `progressStepper`，同一订单两页进度刻度对不上。本次统一为**派生双层模型**（底层一份数据派生两视图），并修正了核单/结算判定 bug。 - ---- - -## 二、变更清单 - -| 变更 | 说明 | -|---|---| -| ❌ 删 `flowItems` | 列表不再返回 | -| ❌ 删 `progress`("X/8") | 列表不再返回 | -| 🔄 `flowStep` 语义改 | 8 步指针 → **线性 6 步**当前步序号 | -| 🔄 `flowStepTotal` | 8 → **6** | -| 🆕 `flowStepCode` | 当前步英文枚举（列表+详情） | -| 🆕 `flowStepStatus` | 当前步状态（列表+详情） | -| 🆕 `currentSubFlows`（列表） | 当前步=资源准备时的 4 子流程数组 | -| 🔄 `progressStepper`（详情） | 扁平 9 节点 → **嵌套 6 主节点**，加 `code`/`isCurrent`/`subFlows`，删 `parallel` | - -> `orderStatus`/`orderStatusName`/`flowStatus`/`flowStatusName` **不变**。 - ---- - -## 三、出参字段（进度部分） - -### 列表 `GET /v3/admin/order`（`data.records[]`，当前步散字段） - -| 字段 | 类型 | 说明 | -|---|---|---| -| `flowStep` | Integer | 当前第几步（1-6；待支付=0；已取消=null） | -| `flowStepTotal` | Integer | 总步数，固定 **6** | -| `flowStepCode` | String | 当前步英文枚举（见枚举表） | -| `flowDisplayText` | String | 当前步中文名 | -| `flowStepStatus` | String | 当前步状态：`DONE`/`PROCESSING`/`WAITING` | -| `currentSubFlows` | Array\ | **仅当前步=资源准备时非空**，否则 `null` | - -### 详情 `GET /v3/admin/order/{id}`（`data.main`） - -列表那 6 个散字段**全有**，外加完整 `progressStepper`： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `progressStepper` | Array\ | 完整 6 主节点（嵌套） | - -**Node 结构**：`step`(Integer) / `code`(String) / `name`(String) / `status`(String) / `isCurrent`(Boolean) / `subFlows`(Array\，仅资源准备非空) -**SubFlow 结构**：`code`(String) / `name`(String) / `status`(String) / `label`(String) - ---- - -## 四、枚举 / 数据字典 - -### 主步 `code`（6 步） - -| code | name | 完成判定 | -|---|---|---| -| `PROFILE` | 补全信息 | 已支付 | -| `RESOURCE` | 资源准备 | 配房完成（降级，见业务边界） | -| `CONFIRM` | 确认 | 订单已确认 | -| `DEPART` | 出行 | 已出行 | -| `REVIEW` | 核单 | 已核单 | -| `SETTLE` | 结算 | 已结算 | - -### 子流程 `code`（资源准备下，4 条） - -| code | name | -|---|---| -| `HOTEL` | 配房 | -| `VEHICLE` | 配车 | -| `GUIDE` | 领队 | -| `PHOTOGRAPHER` | 摄影 | - -### `status`（主步 + 子流程通用） - -| status | 含义 | -|---|---| -| `DONE` | 已完成 | -| `PROCESSING` | 处理中 | -| `WAITING` | 待开始 | - -### `flowStep` 序号 - -`0`=待支付（步骤条未开始）｜`1-6`=对应主步｜`null`=已取消（前端不画进度条） - ---- - -## 五、示例 - -### 列表（定制中、配房完成、配车进行中） - -```jsonc -{ - "orderStatus": "CUSTOMIZING", "orderStatusName": "定制中", - "flowStep": 2, "flowStepTotal": 6, - "flowStepCode": "RESOURCE", "flowDisplayText": "资源准备", "flowStepStatus": "PROCESSING", - "currentSubFlows": [ - {"code":"HOTEL","name":"配房","status":"DONE","label":"已完成"}, - {"code":"VEHICLE","name":"配车","status":"PROCESSING","label":"处理中"}, - {"code":"GUIDE","name":"领队","status":"WAITING","label":"待开始"}, - {"code":"PHOTOGRAPHER","name":"摄影","status":"WAITING","label":"待开始"} - ] -} -``` - -### 详情 progressStepper（同一订单） - -```jsonc -"progressStepper": [ - {"step":1,"code":"PROFILE","name":"补全信息","status":"DONE","isCurrent":false,"subFlows":null}, - {"step":2,"code":"RESOURCE","name":"资源准备","status":"PROCESSING","isCurrent":true,"subFlows":[ - {"code":"HOTEL","name":"配房","status":"DONE","label":"已完成"}, - {"code":"VEHICLE","name":"配车","status":"PROCESSING","label":"处理中"}, - {"code":"GUIDE","name":"领队","status":"WAITING","label":"待开始"}, - {"code":"PHOTOGRAPHER","name":"摄影","status":"WAITING","label":"待开始"} - ]}, - {"step":3,"code":"CONFIRM","name":"确认","status":"WAITING","isCurrent":false,"subFlows":null}, - {"step":4,"code":"DEPART","name":"出行","status":"WAITING","isCurrent":false,"subFlows":null}, - {"step":5,"code":"REVIEW","name":"核单","status":"WAITING","isCurrent":false,"subFlows":null}, - {"step":6,"code":"SETTLE","name":"结算","status":"WAITING","isCurrent":false,"subFlows":null} -] -``` - -### 已取消订单 - -```jsonc -{ "flowStep": null, "flowStepCode": null, "flowDisplayText": "已取消", - "flowStepStatus": null, "currentSubFlows": null } -// 详情 progressStepper 返回空数组 [] -``` - ---- - -## 六、业务边界 / 前端注意 - -1. **当前步两个口子都能拿**：列表用 `flowStep`；详情用 `isCurrent==true` 的节点（和 `flowStep` 指向同一步）。 -2. **⚠️ 降级现状**：资源准备步现**只判配房**——配车/领队/摄影的子状态回写链路尚未接通，所以 `VEHICLE` 子流程恒 `PROCESSING`、`GUIDE`/`PHOTOGRAPHER` 恒 `WAITING`，暂不会变 `DONE`。资源准备只要配房 `DONE` 即整步完成。回写接通后会纳入 4 线全 DONE。 -3. **⚠️ 进度展示请用 `flowStep`/`flowDisplayText`，不要用 `flowStatusName`**——`flowStatus` 在"定制中"阶段恒为 `AWAITING_PROFILE`（待补全信息）不流转，用它展示进度会一直显示"待补全信息"，不准。 -4. `currentSubFlows`/`subFlows` 只在资源准备步有值，其余步为 `null`，前端渲染需判空。 - ---- - -## 七、关联 - -- **Issue**: [#3365](https://git.1814.love:8443/wx/HL/issues/3365)、[#3368](https://git.1814.love:8443/wx/HL/issues/3368) -- **PR**: [#3366](https://git.1814.love:8443/wx/HL/pulls/3366)（派生 6 步 + 修 reviewStatus bug）、[#3369](https://git.1814.love:8443/wx/HL/pulls/3369)（嵌套 progressStepper） -- **设计文档**: ORDER-STATE-MACHINE V1.1 §2.2、API-SPEC v5.56 diff --git a/changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md b/changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md deleted file mode 100644 index 7bb7d02..0000000 --- a/changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md +++ /dev/null @@ -1,124 +0,0 @@ -# 【需求·管理后台】资源默认收费 + 收费=否禁价格日历 + 退费说明接入（景区 / 活动 / 酒店） - -> PR: #3392 #3395（工单 #3389） 服务: hl-resource-service | 更新时间: 2026-06-03 -> 存放目录: changelogs-v2/2026-06/ 影响范围: 管理后台「资源管理 / 景区·游玩项目·酒店」编辑页 -> 状态: 已合并 dev-v3 + 测试服部署双实例 + API 实测通过 - -## ⚠️ 关键说明 - -来自景区编辑页的 3 点反馈，后端已处理（部分是前端没接已实现的接口）： - -1. **默认收费**：景区 / 游玩项目 / 酒店新建时「是否收费」默认改为 **收费(1)**。前端开关初始态请置为「收费」开。 -2. **收费=否 → 没有价格日历**：前端在「是否收费=否」时**隐藏价格日历区**；后端已加兜底——给收费=否的景区 / 活动设价会被拒（错误码 **390901**）。 -3. **价格日历不做合并接口**：基本信息与价格日历仍是两个接口，前端保存时**分两次调**（先存基本信息，再批量设价）。 -4. **退费说明**：后端早已实现（`/admin/refund-note`，覆盖景区+活动），**前端编辑页缺这块 UI**，本文补齐接口契约请接入。 - -服务资源 ServiceItem 的「是否收费」是 `isPaid`+真实定价语义（另有定价校验），**不在本次默认收费范围**，保持现状。 - -## 1. 默认收费（景区 / 活动 / 酒店） - -新建资源不传 `isCharged` 时，后端默认 **1=收费**；前端显式传 `0` 仍尊重为「否」。 - -| 资源 | 字段 | 新建接口 | 默认值 | -|------|------|---------|--------| -| 景区 Scenic | `isCharged` | POST `/admin/scenic/spot` | 1=收费 | -| 游玩项目 Activity | `isCharged` | POST `/admin/activity/item` | 1=收费 | -| 酒店 Hotel | `isCharged` | POST `/admin/hotel/item` | 1=收费 | - -前端动作：新建表单「是否收费」开关初始置「收费(开)」。编辑回显仍读后端返回的 `isCharged`。 - -## 2. 收费=否 → 无价格日历 - -### 2.1 前端 -「是否收费=否」时**隐藏价格日历区**（不展示、不允许设价）。 - -### 2.2 后端兜底（防脏数据） -对收费=否（`isCharged=0`）的景区 / 活动调批量设价接口，后端直接拒绝： - -```bash -# 收费=否的景区设价 → 被拦截 -curl -X PUT -H "Authorization: Bearer " -H "Content-Type: application/json" \ - -d '{"startDate":"2026-07-01","endDate":"2026-07-03","costPrice":100,"status":1}' \ - "https://api.test.1814.love:9443/admin/scenic/spot/{scenicId}/prices" -``` - -响应（测试服实测）： - -```json -{ "code": 390901, "message": "资源未设为收费，不可设置价格日历" } -``` - -- 仅拦**批量设价** `PUT /spot/{id}/prices`；查询、改可售状态、清除价格不受影响。 -- 酒店价格日历是 room-type 级，本期不做后端兜底，前端按 2.1 隐藏即可。 - -## 3. 价格日历保存方式（分两次调，不合并接口） - -经确认**不新增合并接口**。前端编辑保存时分两次调用现有接口： - -1. 先存基本信息：`PUT /admin/scenic/spot/{scenicId}` -2. 再批量设价：`PUT /admin/scenic/spot/{scenicId}/prices`（仅在收费=是时调） - -## 4. 退费说明接入（景区 / 活动） - -> ⚠️ **本节已废弃（2026-06-03 更新）**：退费说明**已改为融合进资源编辑接口**（不再走独立 `/admin/refund-note`），并扩展支持**服务 SERVICE**。前端请按新 changelog `03_3406_退费说明融合进资源编辑接口-景区活动服务-管理后台.md` 接入，**勿按下方独立接口接**。下方内容仅作历史留存。 - -后端模块早已上线（PR #3273 等），前端编辑页缺 UI，请接入。仅覆盖 **SCENIC / ACTIVITY** 两类。 - -### 4.1 接口表 - -| 操作 | 方法 / 路径 | 参数 | -|------|------------|------| -| 查询 | GET `/admin/refund-note` | query: `resourceType`(SCENIC/ACTIVITY) + `resourceId`。未配置返 `data:null`（不报错） | -| 保存(upsert) | PUT `/admin/refund-note` | body: RefundNoteSaveReqVO（按 resourceType+resourceId upsert 整块） | -| 删除(软删) | DELETE `/admin/refund-note` | query: `resourceType` + `resourceId`（幂等，未配置也返 code:200 data:false） | - -### 4.2 保存请求体（RefundNoteSaveReqVO） - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| resourceType | String | 是 | SCENIC / ACTIVITY | -| resourceId | Long | 是 | 关联资源 ID | -| intro | String | 否 | 资源级备注（≤255 字），如「苔藓为赠送项目，不退费」 | -| items | List | 是 | 退费明细，至少 1 条、最多 50 条 | - -items[] 每项（RefundNoteItemVO）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| title | String | 是 | 展示标题，如「成人未参加」 | -| amount | BigDecimal | 是 | 退费金额（赠送项目填 0） | -| unitLabel | String | 否 | 展示文案 /人 /团 /辆 | -| settleScope | String | 否 | 结算粒度 PER_PERSON / PER_TEAM / PER_VEHICLE | -| settleScopeLabel | String | — | 结算粒度中文名（出参后端拼，入参可省） | -| remark | String | 否 | 备注，如「仅限儿童」 | -| effectiveFrom | LocalDate | 否 | 规则生效起日（null=无限制） | -| effectiveTo | LocalDate | 否 | 规则生效止日（null=无限制） | - -### 4.3 示例 - -```bash -# 查询景区退费说明 -curl -H "Authorization: Bearer " \ - "https://api.test.1814.love:9443/admin/refund-note?resourceType=SCENIC&resourceId=3001000000000000019" - -# 保存 -curl -X PUT -H "Authorization: Bearer " -H "Content-Type: application/json" \ - -d '{ - "resourceType": "SCENIC", - "resourceId": 3001000000000000019, - "intro": "苔藓为赠送项目，不退费", - "items": [ - {"title":"成人未参加","amount":44.00,"unitLabel":"/人","settleScope":"PER_PERSON","remark":"仅限成人"} - ] - }' \ - "https://api.test.1814.love:9443/admin/refund-note" -``` - -查询响应（RefundNoteRespVO）：`noteId / resourceType / resourceId / intro / items[] / createTime / updateTime`，`noteId` 字符串透传防精度丢失，`settleScopeLabel` 后端回填中文。 - -## 5. 前端动作清单 - -1. 景区 / 活动 / 酒店新建表单「是否收费」开关默认置「收费」。 -2. 「是否收费=否」时隐藏价格日历区（编辑页 + 新建页）。 -3. 保存仍分两次调（基本信息 + 价格日历），价格日历仅收费=是时调。 -4. 景区 / 活动编辑页接入「退费说明」模块（GET/PUT/DELETE `/admin/refund-note`）。 diff --git a/changelogs-v2/2026-06/03_3390_图标库模块-新增接口-管理后台+小程序.md b/changelogs-v2/2026-06/03_3390_图标库模块-新增接口-管理后台+小程序.md deleted file mode 100644 index da42bbf..0000000 --- a/changelogs-v2/2026-06/03_3390_图标库模块-新增接口-管理后台+小程序.md +++ /dev/null @@ -1,559 +0,0 @@ -# 【新增接口·管理后台 + 小程序】图标库模块 11 接口（全模块首次推送 changelog） - -> **PR**: #3396（模块主体）+ #3398 / #3399（mp 端点公开化）+ #3401（上线后审计加固） -> **服务**: hl-user-service | **更新时间**: 2026-06-03 -> -> **存放目录**: `changelogs-v2/2026-06/` -> **影响范围**: 管理后台「图标库」管理页（分类 + 图标 CRUD + SVG 上传解析）；小程序 / 前端 图标渲染（公开只读查询） - ---- - -## ⚠️ 关键说明 - -图标库是后台统一维护的一套 SVG 图标，结构类似数据字典：一级「图标分类」(`icon_category`) + 二级「图标项」(`icon_item`)，图标项归属某分类编码 `categoryCode`。 - -**SVG 直接存库（不走 OSS）**：图标内容是 SVG 字符串，直存数据库 `svg_content`（MEDIUMTEXT，单图标后端限 256KB）。前端拿到 `svgContent` 直接渲染。 - -**新增图标分两步**：先调 §3.5 `POST /admin/icon/parse-svg` 上传 `.svg` 文件，后端读成字符串并做安全校验后**只返回字符串、不落库**；前端拿到 `svgContent` 再连同 `color` / `size` 等填进保存表单调 §3.6 `POST /admin/icon/item` 保存。 - -**mp 查询公开无需 token**：§3.10 / §3.11 是 UI 参考数据（同字典），无需登录即可访问，只返回 `status=ACTIVE` 的分类与图标，且分类被禁用时其图标也不再返回。 - -**SVG 安全校验**：上传 / 保存的 SVG 经服务端 XXE-safe 解析校验，拒绝含 ` -``` - ---- - -## 关联字典 - -| 字典类型 | 说明 | 用途 | -|---------|------|------| -| room_category | 房型分类：STANDARD-标准间, DELUXE-豪华间, SUITE-套房, FAMILY-家庭房 | 房型列表展示 | -| bed_type | 床型：KING-大床, TWIN-双床, TATAMI-榻榻米 | 房型列表展示 | -| window_type | 窗户：WITH_WINDOW-有窗, NO_WINDOW-无窗, SKYLIGHT-天窗 | 房型列表展示 | - ---- - -## 删掉的字段 - -当前弹窗中的"房间数量"字段应该**删除**——后端按家庭分配，每个家庭一间房，不需要单独设置数量。如果一个家庭需要2间房，就添加2行同样的家庭。 - ---- - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-03/2026-03-20_0908_97d461c_feat.md b/changelogs/2026-03/2026-03-20_0908_97d461c_feat.md deleted file mode 100644 index 66f2be7..0000000 --- a/changelogs/2026-03/2026-03-20_0908_97d461c_feat.md +++ /dev/null @@ -1,137 +0,0 @@ -# 接口变更记录 — 2026-03-20 09:08 - -> **提交** `97d461c` · **作者** wx · **时间** 2026-03-20 09:08:43 +0800 -> -> feat: 法大大合同平台 + 订单超时通知 + 第二期需求文档 + 软著材料 - -## 变更总览 - -- **合同服务** - - ContractCallback (+1) -- **小程序聚合服务** - - MpOrder (+1) -- **订单服务** - - InternalMpOrder (+1) - ---- - -## 合同服务 - -### ContractCallback - -> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「【回调接口】合同回调」** - -### 🆕 `POST` /contract/callback/fadada — 法大大合同状态回调 - -> 接收法大大电子合同平台的签署状态回调。签署完成/撤销/拒签时法大大推送事件到此接口 - -**响应** `ResponseEntity` - ---- - -## 小程序聚合服务 - -### MpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 订单接口」** - -### 🆕 `POST` /mp/order/{orderId}/urge — 催单 - -> 提醒定制师尽快处理订单内部流程，通过企业微信发送消息。每个订单2小时内只能催一次 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result` - ---- - -## 订单服务 - -### InternalMpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序订单（Feign调用）」** - -### 🆕 `POST` /internal/mp/order/{orderId}/urge — 催单 - -> 用户催单，通过企微消息提醒定制师尽快处理订单内部流程。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 用户服务 - -#### ✏️ TravelerRequest - - - ✏️ `birthday`: 说明 "出生日期（必填，后端根据此字段自动判断人员类型）" → "出生日期（后端根据此字段自动判断人员类型，未传则默认ADULT）" - -### 订单服务 - -#### ✏️ CreateOrderRequest - - - ✏️ `birthday`: 说明 "出生日期（必填，后端根据此字段自动判断人员类型）" → "出生日期（后端根据此字段自动判断人员类型，未传则默认ADULT）" - - -📁 全部变更文件 (点击展开) - -``` -M CLAUDE.md -M docs/CLAUDE_WORKFLOW/README.md -A "docs/architecture/\346\210\277\347\256\241\346\234\215\345\212\241\346\236\266\346\236\204\350\256\276\350\256\241.md" -A "docs/architecture/\347\254\254\344\272\214\346\234\237\346\236\266\346\236\204\346\200\273\350\247\210.md" -A "docs/architecture/\350\275\246\351\230\237\346\234\215\345\212\241\346\236\266\346\236\204\350\256\276\350\256\241.md" -A docs/mindmap-v1.27-extracted.md -A "docs/requirements/\345\217\270\346\234\272\347\253\257\345\274\202\345\270\270\345\244\204\347\220\206\344\270\216\346\213\222\345\215\225\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\345\217\270\346\234\272\347\253\257\346\240\270\345\277\203\346\265\201\347\250\213\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\345\217\270\346\234\272\347\256\241\347\220\206\344\270\216\346\216\210\346\235\203\347\237\251\351\230\265\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\346\210\277\347\256\241\345\220\216\345\217\260v1.27\344\274\230\345\214\226\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\346\210\277\347\256\241\346\234\215\345\212\241\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\346\216\222\347\217\255\344\270\216\346\224\266\345\205\245\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\346\264\276\345\215\225\350\260\203\345\272\246\346\250\241\345\235\227\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\346\266\210\346\201\257\345\256\232\344\275\215\344\270\216\345\272\224\346\200\245\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\347\254\254\344\272\214\346\234\237\347\273\237\344\270\200\346\225\260\346\215\256\345\255\227\345\205\270.md" -A "docs/requirements/\350\257\204\345\210\206\344\270\216\345\237\271\350\256\255\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\350\260\203\345\272\246\345\244\247\347\233\230\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\350\267\257\345\206\265\351\242\204\350\255\246\347\263\273\347\273\237\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\350\275\246\350\276\206\347\256\241\347\220\206\345\215\207\347\272\247\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/requirements/\350\275\246\351\230\237\347\274\226\347\273\204\344\270\216\345\215\217\345\220\214\350\260\203\345\272\246\351\234\200\346\261\202\350\247\204\346\240\274.md" -A "docs/zzq/01-\347\224\263\350\257\267\346\235\220\346\226\231\346\270\205\345\215\225.md" -A "docs/zzq/02-\350\272\253\344\273\275\350\257\201\346\230\216/\350\257\267\345\234\250\346\255\244\346\224\276\345\205\245\350\272\253\344\273\275\350\257\201\346\230\216\346\235\220\346\226\231.txt" -A "docs/zzq/03-\346\272\220\344\273\243\347\240\201.txt" -A "docs/zzq/04-\350\275\257\344\273\266\350\257\264\346\230\216\344\271\246.md" -A docs/zzq/generate_source_code.py -M hl-common/src/main/java/com/hulalv/common/exception/GlobalExceptionHandler.java -M hl-contract-service/src/main/java/com/hulalv/contract/config/ContractPlatformProperties.java -M hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java -A hl-contract-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaApiClient.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaContractPlatform.java -A hl-contract-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaSignatureUtil.java -M hl-contract-service/src/main/java/com/hulalv/contract/service/ContractCallbackService.java -M hl-contract-service/src/main/java/com/hulalv/contract/service/ContractService.java -A hl-contract-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaApiClientTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaContractPlatformTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaSignatureUtilTest.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/service/NotificationEventHelper.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java -M nacos-config/hl-contract-service-dev.yml -A scripts/gen_copyright_pdf.py -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-20_1127_508b792_feat.md b/changelogs/2026-03/2026-03-20_1127_508b792_feat.md deleted file mode 100644 index bc319e1..0000000 --- a/changelogs/2026-03/2026-03-20_1127_508b792_feat.md +++ /dev/null @@ -1,111 +0,0 @@ -# 接口变更记录 — 2026-03-20 11:27 - -> **提交** `508b792` · **作者** wx · **时间** 2026-03-20 11:27:32 +0800 -> -> feat: 小程序酒店详情返回房型列表 + 新增房型详情接口 - -## 变更总览 - -- **小程序聚合服务** - - MpHotel (+1) -- **资源服务** - - InternalMpHotel (+1) - ---- - -## 小程序聚合服务 - -### MpHotel - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 酒店接口」** - -### 🆕 `GET` /mp/hotel/room-type/{roomTypeId} — 房型详情 - -> 获取房型完整信息，包含封面、轮播图、视频等素材URL，以及床型、面积、设施等详细信息。 - -**参数** - - - `{roomTypeId}` (`Long`) — 路径参数：房型ID - -**响应** `Result>` - ---- - -## 资源服务 - -### InternalMpHotel - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「【内部接口】小程序酒店（Feign调用）」** - -### 🆕 `GET` /internal/mp/hotel/room-type/{roomTypeId} — C端房型详情 - -> 【仅限内部Feign调用】供mp-service获取房型完整详情，包含封面、轮播图、视频等素材URL。 - -**关联字典**： -- room_category：房型分类 -- bed_type：床型 -- window_type：窗户类型 -- bathroom_type：卫浴类型 -- room_facility：房间设施 - -**参数** - - - `{roomTypeId}` (`Long`) — 路径参数：房型ID - -**响应** `Result` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `roomTypeId` | `String` | 房型ID | -| `hotelId` | `String` | 所属酒店ID | -| `name` | `String` | 房型名称 | -| `roomCategory` | `String` | 房型分类 | -| `roomArea` | `BigDecimal` | 房间面积（平方米） | -| `bedType` | `String` | 床型 | -| `bedCount` | `Integer` | 床位数量 | -| `bedSize` | `String` | 床尺寸 | -| `maxOccupancy` | `Integer` | 最多入住人数 | -| `floorInfo` | `String` | 楼层信息 | -| `windowType` | `String` | 窗型 | -| `bathroomType` | `String` | 卫浴类型 | -| `roomFacilities` | `String` | 房间设施（JSON） | -| `basePrice` | `BigDecimal` | 基础成本价（元） | -| `totalRooms` | `Integer` | 总房间数 | -| `description` | `String` | 房型描述 | -| `coverMaterialId` | `String` | 封面素材ID | -| `coverUrl` | `String` | 封面图URL | -| `bannerMaterialIds` | `List` | 横幅素材ID列表 | -| `bannerUrls` | `List` | 横幅图URL列表 | -| `videoMaterialId` | `String` | 视频素材ID | -| `videoUrl` | `String` | 视频URL | -| `sortOrder` | `Integer` | 排序权重 | -| `status` | `Integer` | 状态：0=禁用 1=启用 | -| `approvalNo` | `String` | 审批单号 | -| `pendingStatus` | `Integer` | 待审批目标状态 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ HotelVO - - - 🆕 `roomTypes` (`List`) — 房型列表（C端详情返回，仅包含已启用房型） - - -📁 全部变更文件 (点击展开) - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpResourceFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpResourceFeignFallbackFactory.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/InternalMpHotelController.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/HotelVO.java -M nacos-config/hl-contract-service-dev.yml -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-20_1641_f59d78d_refactor_pri.md b/changelogs/2026-03/2026-03-20_1641_f59d78d_refactor_pri.md deleted file mode 100644 index 67d6eae..0000000 --- a/changelogs/2026-03/2026-03-20_1641_f59d78d_refactor_pri.md +++ /dev/null @@ -1,50 +0,0 @@ -# 接口变更记录 — 2026-03-20 16:41 - -> **提交** `f59d78d` · **作者** wx · **时间** 2026-03-20 16:41:03 +0800 -> -> refactor: 移除定价模式(pricingMode)字段，价格统一在价格日历中设置 - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ PricingRequest - - - ❌ ~~`pricingMode`~~ (`String`) — 定价模式：AUTO=根据行程资源价格自动计算 MANUAL=手动在价格日历设置每日价格 CUSTOM=定制产品整单定价 - - ✏️ `profitMode`: 说明 "利润模式（AUTO模式下生效）：FIXED=在成本基础上加固定金额 PERCENT=在成本基础上按百分比加价" → "利润模式：FIXED=在成本基础上加固定金额 PERCENT=在成本基础上按百分比加价" - - ✏️ `customTotalPrice`: 说明 "定制产品总价（CUSTOM定价模式下使用，代表整单总价）" → "定制产品总价（CUSTOM/ROUTE产品使用，代表整单总价）" - -#### ✏️ ProductPricingVO - - - ❌ ~~`pricingMode`~~ (`String`) — 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 - - ✏️ `customTotalPrice`: 说明 "定制产品总价（CUSTOM模式下使用）" → "定制产品总价（CUSTOM/ROUTE产品使用）" - -### 小程序聚合服务 - -#### ✏️ MpCustomProductDetailVO - - - ❌ ~~`pricingMode`~~ (`String`) — 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 - - -📁 全部变更文件 (点击展开) - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductPricing.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductPricingService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductPricingServiceTest.java -A sql/remove_pricing_mode.sql -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-20_1645_297ce93_feat.md b/changelogs/2026-03/2026-03-20_1645_297ce93_feat.md deleted file mode 100644 index 5564e55..0000000 --- a/changelogs/2026-03/2026-03-20_1645_297ce93_feat.md +++ /dev/null @@ -1,379 +0,0 @@ -# 接口变更记录 — 2026-03-20 16:45 - -> **提交** `297ce93` · **作者** wx · **时间** 2026-03-20 16:45:40 +0800 -> -> feat: 订单自动保险+合同 + 产品合同/保险字段 + 房间升级预览 + 订单价差服务 - -## 变更总览 - -- **产品服务** - - InternalProduct (+1) -- **保险服务** - - InternalInsurance (+1) -- **合同服务** - - InternalContract (+2) -- **订单服务** - - AdminOrder (+1, 改1) - - InternalPaymentOrder (+1) -- **资源服务** - - InternalResourcePrice (+1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### 🆕 `GET` /internal/product/{productId}/automation-config - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**响应** `Result` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceSchemeId` | `Long` | | -| `contractPlatform` | `String` | | -| `contractTemplateCode` | `String` | | -| `contractMode` | `String` | | -| `signatoryMode` | `Integer` | | -| `agencyCode` | `String` | | -| `disputeResolution` | `Integer` | | -| `supplementaryClause` | `String` | | -| `transactorName` | `String` | | -| `transactorPhone` | `String` | | -| `productName` | `String` | | -| `destinationCity` | `String` | | -| `departureCity` | `String` | | -| `tripDays` | `Integer` | | -| `tripNights` | `Integer` | | - ---- - -## 保险服务 - -### InternalInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「【内部接口】保险（Feign调用）」** - -### 🆕 `POST` /internal/insurance/auto-purchase — 按方案自动投保(内部调用) - -> 内部服务间调用。根据保险方案自动为订单所有出行人投保： - -**响应** `Result` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `boolean` | 是否全部成功 | -| `purchasedCount` | `int` | 成功投保段数 | -| `failedCount` | `int` | 失败段数 | -| `failureReason` | `String` | 失败原因（部分失败或全部失败时返回第一个错误） | - ---- - -## 合同服务 - -### InternalContract - -> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「【内部接口】合同（Feign调用）」** - -### 🆕 `POST` /internal/contract/create — 创建合同（内部调用） - -> 内部服务调用创建合同，adminId固定为0表示系统自动创建。返回contractId和status - -**请求体** `CreateContractRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `contractType` | `String` | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `platform` | `String` | 合同平台（字典：contract_platform）: 12301-全国旅游监管平台, FADADA-法大大, ESIGN-e签宝, TENCENT_ESS-腾讯电子签。不传则根据模板自动确定 | -| `templateCode` | `String` | 模板编码 | -| `agencyCode` | `String` | 旅行社编号（可选，默认使用配置值） | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `destination` | `String` | 目的地 | -| `routeName` | `String` | 线路名称 | -| `days` | `Integer` | 行程天数 | -| `nights` | `Integer` | 住宿晚数 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `departureCity` | `String` | 出发城市 | -| `groupId` | `String` | 团号 | -| `signatoryName` | `String` | 签署人姓名 | -| `signatoryPhone` | `String` | 签署人电话 | -| `signatoryIdNumber` | `String` | 签署人证件号码 | -| `signingPlace` | `String` | 签约地点 | -| `adultCost` | `BigDecimal` | 成人费用 | -| `childCost` | `BigDecimal` | 儿童费用 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `supplementaryClause` | `String` | 补充约定内容 | -| `vehicleModel` | `String` | 车型名称(产品快照) | -| `travelers` | `List` | 出行人列表 | -| `name` | `String` | 姓名 | -| `gender` | `String` | 性别: male/female | -| `age` | `Integer` | 年龄 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `health` | `String` | 健康信息 | - -**响应** `Result>` - -### 🆕 `POST` /internal/contract/report — 报备合同（内部调用） - -> 内部服务调用报备合同（同步模式），adminId固定为0表示系统自动创建。返回contractId和status - -**请求体** `ReportContractRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `contractType` | `String` | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `platform` | `String` | 合同平台（字典：contract_platform）: 12301-全国旅游监管平台, FADADA-法大大, ESIGN-e签宝, TENCENT_ESS-腾讯电子签 | -| `templateCode` | `String` | 模板编码 | -| `agencyCode` | `String` | 旅行社编号 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `destination` | `String` | 目的地 | -| `routeName` | `String` | 线路名称 | -| `days` | `Integer` | 行程天数 | -| `nights` | `Integer` | 住宿晚数 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `departureCity` | `String` | 出发城市 | -| `groupId` | `String` | 团号 | -| `signatoryName` | `String` | 签署人姓名 | -| `signatoryPhone` | `String` | 签署人电话 | -| `signatoryIdNumber` | `String` | 签署人证件号码 | -| `signingPlace` | `String` | 签约地点 | -| `adultCost` | `BigDecimal` | 成人费用 | -| `childCost` | `BigDecimal` | 儿童费用 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `supplementaryClause` | `String` | 补充约定内容 | - -**响应** `Result>` - ---- - -## 订单服务 - -### AdminOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「管理端订单接口」** - -### 🆕 `POST` /admin/order/{orderId}/hotel-assignment/preview — 配房升级差价预览 - -> 预览配房时的房型升级差价（不创建记录）。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `details` | `List` | 各天差价明细 | -| `totalDiff` | `BigDecimal` | 差价合计（正数=需补款，负数=可退款） | -| `direction` | `String` | 差价方向：UPGRADE=升级加价, DOWNGRADE=降级减价, SAME=价格不变, MIXED=部分升级部分降级 | -| `description` | `String` | 描述 | -| `familyIndex` | `Integer` | 家庭序号 | -| `date` | `String` | 日期 | -| `defaultRoomTypeId` | `Long` | 产品默认房型ID | -| `defaultRoomTypeName` | `String` | 产品默认房型名称 | -| `assignedRoomTypeId` | `Long` | 实际分配房型ID | -| `assignedRoomTypeName` | `String` | 实际分配房型名称 | -| `defaultPrice` | `BigDecimal` | 默认房型当天单价 | -| `assignedPrice` | `BigDecimal` | 实际房型当天单价 | -| `dayDiff` | `BigDecimal` | 当天差价 | -| `direction` | `String` | 差价方向 | -| `remark` | `String` | 备注 | - -### ✏️ `GET` /admin/order/{orderId}/available-hotels — 配房可选酒店列表 - -- 参数: orderId(Long) → orderId(Long), dayIndex(Integer) - -### InternalPaymentOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】订单-支付/合同/保险（Feign调用）」** - -### 🆕 `GET` /internal/order/{orderId}/travelers — 获取订单出行人列表(供保险服务调用) - -> 内部服务间调用。返回订单下所有出行人的基本信息（姓名、证件号、性别、生日、手机号）， - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result>>` - ---- - -## 资源服务 - -### InternalResourcePrice - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「【内部接口】资源价格（Feign调用）」** - -### 🆕 `GET` /internal/resource/prices/standard-room-type/{hotelId} - -**参数** - - - `{hotelId}` (`Long`) — 路径参数 - -**响应** `Result` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductCreateRequest - - - 🆕 `insuranceSchemeId` (`Long`) — 保险方案ID - - 🆕 `contractPlatform` (`String`) — 合同平台(12301/FADADA) - - 🆕 `contractTemplateCode` (`String`) — 合同模板编码 - - 🆕 `contractMode` (`String`) — 签约模式(STANDARD/SYNC) - - 🆕 `signatoryMode` (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - 🆕 `agencyCode` (`String`) — 旅行社编码 - - 🆕 `disputeResolution` (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - 🆕 `supplementaryClause` (`String`) — 补充条款 - - 🆕 `transactorName` (`String`) — 经办人姓名 - - 🆕 `transactorPhone` (`String`) — 经办人电话 - -#### ✏️ ProductListVO - - - 🆕 `insuranceSchemeId` (`String`) — 保险方案ID - - 🆕 `contractPlatform` (`String`) — 合同平台(12301/FADADA) - - 🆕 `contractTemplateCode` (`String`) — 合同模板编码 - - 🆕 `contractMode` (`String`) — 签约模式(STANDARD/SYNC) - - 🆕 `signatoryMode` (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - 🆕 `agencyCode` (`String`) — 旅行社编码 - - 🆕 `disputeResolution` (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - 🆕 `supplementaryClause` (`String`) — 补充条款 - - 🆕 `transactorName` (`String`) — 经办人姓名 - - 🆕 `transactorPhone` (`String`) — 经办人电话 - -#### ✏️ ProductSaveRequest - - - 🆕 `insuranceSchemeId` (`Long`) — 保险方案ID - - 🆕 `contractPlatform` (`String`) — 合同平台(12301/FADADA) - - 🆕 `contractTemplateCode` (`String`) — 合同模板编码 - - 🆕 `contractMode` (`String`) — 签约模式(STANDARD/SYNC) - - 🆕 `signatoryMode` (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - 🆕 `agencyCode` (`String`) — 旅行社编码 - - 🆕 `disputeResolution` (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - 🆕 `supplementaryClause` (`String`) — 补充条款 - - 🆕 `transactorName` (`String`) — 经办人姓名 - - 🆕 `transactorPhone` (`String`) — 经办人电话 - -#### ✏️ ProductUpdateRequest - - - 🆕 `insuranceSchemeId` (`Long`) — 保险方案ID - - 🆕 `contractPlatform` (`String`) — 合同平台(12301/FADADA) - - 🆕 `contractTemplateCode` (`String`) — 合同模板编码 - - 🆕 `contractMode` (`String`) — 签约模式(STANDARD/SYNC) - - 🆕 `signatoryMode` (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - 🆕 `agencyCode` (`String`) — 旅行社编码 - - 🆕 `disputeResolution` (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - 🆕 `supplementaryClause` (`String`) — 补充条款 - - 🆕 `transactorName` (`String`) — 经办人姓名 - - 🆕 `transactorPhone` (`String`) — 经办人电话 - -#### ✏️ ProductVO - - - 🆕 `insuranceSchemeId` (`String`) — 保险方案ID - - 🆕 `contractPlatform` (`String`) — 合同平台(12301/FADADA) - - 🆕 `contractTemplateCode` (`String`) — 合同模板编码 - - 🆕 `contractMode` (`String`) — 签约模式(STANDARD/SYNC) - - 🆕 `signatoryMode` (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - 🆕 `agencyCode` (`String`) — 旅行社编码 - - 🆕 `disputeResolution` (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - 🆕 `supplementaryClause` (`String`) — 补充条款 - - 🆕 `transactorName` (`String`) — 经办人姓名 - - 🆕 `transactorPhone` (`String`) — 经办人电话 - -### 保险服务 - -#### 🆕 AutoPurchaseRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅行订单ID | -| `schemeId` | `Long` | 保险方案ID | - -### 订单服务 - -#### ✏️ HotelAssignmentRequest - - - 🆕 `hotelId` (`Long`) — 酒店ID - - 🆕 `roomTypeId` (`Long`) — 房型ID - - 🆕 `date` (`String`) — 日期(yyyy-MM-dd)，单天 - - 🆕 `remark` (`String`) — 当天备注 - - 🆕 `upgradePrice` (`BigDecimal`) — 手动覆盖升级差价（null=使用系统计算值，仅当房型与产品默认不同时有效） - - ❌ ~~`checkInDate`~~ (`String`) — 入住日期(yyyy-MM-dd) - - ❌ ~~`checkOutDate`~~ (`String`) — 退房日期(yyyy-MM-dd) - - ✏️ `assignments`: 说明 "酒店分配列表" → "酒店分配列表（按天粒度，每天每个家庭一条记录）" - - ✏️ `roomType`: 说明 "房型" → "房型名称" - - -📁 全部变更文件 (点击展开) - -``` -M docs/CLAUDE_WORKFLOW/README.md -A docs/requirements/order-auto-insurance-contract.md -M hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/dto/AutoPurchaseRequest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/feign/OrderInsuranceFeignClient.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/vo/AutoPurchaseResultVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/config/WebMvcConfig.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/HotelAssignmentRequest.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ResourcePriceFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ResourcePriceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/NotificationEventHelper.java -A hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderItineraryEditService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderPriceDiffService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -A hl-order-service/src/main/java/com/hulalv/order/vo/RoomUpgradePreviewVO.java -M hl-order-service/src/test/java/com/hulalv/order/constant/OrderConstantsTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderPriceDiffServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderTodoServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundPolicyServiceTest.java -A hl-product-service/src/main/java/com/hulalv/product/config/MapOrNullDeserializer.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -A hl-product-service/src/main/java/com/hulalv/product/vo/ProductAutomationConfigVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourcePriceController.java -A sql/product_automation_fields.sql -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-20_2357_fa78a82_feat_orderId.md b/changelogs/2026-03/2026-03-20_2357_fa78a82_feat_orderId.md deleted file mode 100644 index e8dc349..0000000 --- a/changelogs/2026-03/2026-03-20_2357_fa78a82_feat_orderId.md +++ /dev/null @@ -1,27 +0,0 @@ -# 接口变更记录 — 2026-03-20 23:57 - -> **提交** `fa78a82` · **作者** wx · **时间** 2026-03-20 23:57:54 +0800 -> -> feat: 投保接口支持orderId自动填充出行人和日期 + 修复节点类型计数 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 保险服务 - -#### ✏️ PurchaseInsuranceRequest - - - ✏️ `startDate`: 说明 "保障开始日期" → "保障开始日期(传orderId时自动从订单获取)" - - ✏️ `endDate`: 说明 "保障结束日期" → "保障结束日期(传orderId时自动从订单获取)" - - ✏️ `insuredPersons`: 说明 "被保人列表(至少1人)" → "被保人列表(传orderId时自动从订单出行人获取)" - - -📁 全部变更文件 (点击展开) - -``` -M hl-insurance-service/src/main/java/com/hulalv/insurance/dto/PurchaseInsuranceRequest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -M hl-product-service/src/test/java/com/hulalv/product/constant/ProductConstantsTest.java -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-20_accommodation_save_guide.md b/changelogs/2026-03/2026-03-20_accommodation_save_guide.md deleted file mode 100644 index c26d128..0000000 --- a/changelogs/2026-03/2026-03-20_accommodation_save_guide.md +++ /dev/null @@ -1,262 +0,0 @@ -# 住宿安排保存：前端实现指南（BUG修复） - -**日期**: 2026-03-20 -**类型**: 前端BUG修复指南 -**影响模块**: 产品管理 → 住宿安排 - ---- - -## 问题描述 - -住宿安排页面： -1. **一个家庭保存多个房型保存不上**（如：家庭1 → 大床房 + 普通标间） -2. **第二个家庭的房型也保存不上** - -**原因**：后端的住宿数据模型是 **每条记录 = 一个酒店 + 一个房型**，前端需要为每个房型单独调用接口保存。 - ---- - -## 后端数据模型 - -`product_day_hotel` 表结构（每条记录 = 一个房型分配）： - -| 字段 | 说明 | -|------|------| -| id | 记录ID | -| productId | 产品ID | -| dayNumber | 第几天 | -| hotelId | 酒店ID | -| hotelName | 酒店名称 | -| roomTypeId | **房型ID**（每条记录一个房型） | -| roomTypeName | 房型名称 | -| roomCount | 房间数量 | -| familyIds | 所属家庭ID数组 JSON | - -**关键**：同一天、同一家庭、同一酒店可以有多条记录（不同房型），每个房型是独立的一条记录。 - -### 数据示例 - -家庭1 住香格里拉（大床房1间 + 标间1间）= **2条记录**： - -``` -记录1: hotelId=香格里拉, roomTypeId=大床房, roomCount=1, familyIds=["家庭1"] -记录2: hotelId=香格里拉, roomTypeId=标间, roomCount=1, familyIds=["家庭1"] -``` - -家庭2 住海棠酒店（标间1间）= **1条记录**： - -``` -记录3: hotelId=海棠酒店, roomTypeId=标间, roomCount=1, familyIds=["家庭2"] -``` - ---- - -## 后端接口清单 - -### 1. 添加住宿（每个房型调一次） - -``` -POST /admin/product/item/{productId}/day/{dayNumber}/hotel -``` - -请求体： -```json -{ - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": "3002000000000000013", - "roomTypeName": "大床房", - "roomCount": 1, - "familyIds": ["2034467435683393537"] -} -``` - -### 2. 更新住宿 - -``` -PUT /admin/product/hotel/{id} -``` - -### 3. 删除住宿 - -``` -DELETE /admin/product/hotel/{id} -``` - -### 4. 查询某天的住宿列表 - -``` -GET /admin/product/item/{productId}/day/{dayNumber}/hotels -``` - -响应： -```json -{ - "code": 200, - "data": [ - { - "id": "2034468900841975809", - "dayNumber": 1, - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": "3002000000000000013", - "roomTypeName": "大床房", - "roomCount": 1, - "familyIds": ["2034467435683393537"], - "familyRoomConfig": null - }, - { - "id": "2034817340914429954", - "dayNumber": 1, - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": "3002000000000000014", - "roomTypeName": "普通标间", - "roomCount": 1, - "familyIds": ["2034467435683393537"], - "familyRoomConfig": null - } - ] -} -``` - ---- - -## 前端实现方案 - -### 页面数据结构 - -前端页面按「家庭 → 酒店 → 房型列表」组织，但后端是扁平的（每个房型一条记录）。需要做转换： - -```js -// 前端UI数据结构（按家庭分组） -const uiData = { - familyId: '2034467435683393537', - hotelId: '2023714929877450753', - hotelName: '呼伦贝尔香格里拉大酒店', - roomTypes: [ - { roomTypeId: '3002000000000000013', roomTypeName: '大床房', roomCount: 1 }, - { roomTypeId: '3002000000000000014', roomTypeName: '普通标间', roomCount: 1 } - ] -} - -// 需要转换为后端的扁平结构（每个房型一条记录） -const apiRequests = uiData.roomTypes.map(rt => ({ - hotelId: uiData.hotelId, - hotelName: uiData.hotelName, - roomTypeId: rt.roomTypeId, - roomTypeName: rt.roomTypeName, - roomCount: rt.roomCount, - familyIds: [uiData.familyId] -})) -``` - -### 保存逻辑（推荐：增量模式） - -```js -async function saveAccommodation(productId, dayNumber, familyId, hotelId, hotelName, roomTypes) { - // 1. 查询当前该天已有的住宿记录 - const { data: existing } = await request.get( - `/admin/product/item/${productId}/day/${dayNumber}/hotels` - ) - - // 2. 筛选出属于当前家庭的已有记录 - const familyExisting = existing.filter(h => - h.familyIds && h.familyIds.includes(familyId) - ) - - // 3. 对比：哪些要删、哪些要更新、哪些要新增 - const existingMap = new Map(familyExisting.map(h => [h.roomTypeId, h])) - - for (const rt of roomTypes) { - const old = existingMap.get(rt.roomTypeId) - if (old) { - // 已存在 → 更新 - await request.put(`/admin/product/hotel/${old.id}`, { - hotelId, hotelName, - roomTypeId: rt.roomTypeId, - roomTypeName: rt.roomTypeName, - roomCount: rt.roomCount, - familyIds: [familyId] - }) - existingMap.delete(rt.roomTypeId) - } else { - // 不存在 → 新增 - await request.post( - `/admin/product/item/${productId}/day/${dayNumber}/hotel`, - { - hotelId, hotelName, - roomTypeId: rt.roomTypeId, - roomTypeName: rt.roomTypeName, - roomCount: rt.roomCount, - familyIds: [familyId] - } - ) - } - } - - // 4. 剩余的旧记录 → 删除（用户已移除的房型） - for (const [, old] of existingMap) { - await request.delete(`/admin/product/hotel/${old.id}`) - } -} -``` - -### 加载回显逻辑 - -```js -async function loadAccommodation(productId, dayNumber, families) { - // 1. 查询该天所有住宿记录（扁平） - const { data: hotels } = await request.get( - `/admin/product/item/${productId}/day/${dayNumber}/hotels` - ) - - // 2. 按家庭ID分组 - const familyHotelMap = {} - for (const family of families) { - familyHotelMap[family.familyId] = [] - } - - for (const hotel of hotels) { - const fids = hotel.familyIds || [] - for (const fid of fids) { - if (!familyHotelMap[fid]) familyHotelMap[fid] = [] - familyHotelMap[fid].push(hotel) - } - } - - // 3. 按家庭+酒店分组，合并同酒店的多个房型 - for (const [familyId, hotelRecords] of Object.entries(familyHotelMap)) { - const hotelGrouped = {} - for (const h of hotelRecords) { - if (!hotelGrouped[h.hotelId]) { - hotelGrouped[h.hotelId] = { - hotelId: h.hotelId, - hotelName: h.hotelName, - roomTypes: [] - } - } - hotelGrouped[h.hotelId].roomTypes.push({ - id: h.id, // 后端记录ID，更新/删除时需要 - roomTypeId: h.roomTypeId, - roomTypeName: h.roomTypeName, - roomCount: h.roomCount - }) - } - // hotelGrouped 就是该家庭的UI展示数据 - } -} -``` - ---- - -## 总结 - -| 操作 | 接口 | 说明 | -|------|------|------| -| 添加房型 | `POST .../day/{dayNumber}/hotel` | **每个房型调一次**，同一酒店不同房型 = 多次调用 | -| 更新房型 | `PUT .../hotel/{id}` | 按记录ID更新 | -| 删除房型 | `DELETE .../hotel/{id}` | 用户移除某个房型时调用 | -| 查询回显 | `GET .../day/{dayNumber}/hotels` | 返回扁平列表，前端按 familyIds + hotelId 分组展示 | - -**核心要点**：后端是扁平的（每个房型一条记录），前端需要做 UI分组结构 ↔ 扁平记录 的转换。 diff --git a/changelogs/2026-03/2026-03-20_available_hotels_dayindex.md b/changelogs/2026-03/2026-03-20_available_hotels_dayindex.md deleted file mode 100644 index fdb2e72..0000000 --- a/changelogs/2026-03/2026-03-20_available_hotels_dayindex.md +++ /dev/null @@ -1,90 +0,0 @@ -# 配房可选酒店接口增加 dayIndex 参数 - -**日期**: 2026-03-20 -**类型**: 接口变更（不兼容） -**影响模块**: 订单管理 → 配房 - ---- - -## 变更说明 - -`GET /admin/order/{orderId}/available-hotels` 接口新增**必填参数** `dayIndex`，因为每天行程的酒店可能不同，配房需要按天查询可选酒店。 - -### 变更前 - -``` -GET /admin/order/{orderId}/available-hotels -``` -返回所有天的快照酒店，不区分行程天。 - -### 变更后 - -``` -GET /admin/order/{orderId}/available-hotels?dayIndex=2 -``` -只返回指定行程天的快照酒店标注。 - ---- - -## 接口定义 - -### `GET /admin/order/{orderId}/available-hotels` - -#### 请求参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 是 | 订单ID（路径参数） | -| dayIndex | Integer | **是** | 行程第几天（从1开始，Query参数） | - -#### 响应格式 - -```json -{ - "code": 200, - "data": [ - { - "hotelId": "2033911514863382529", - "hotelName": "恩和瓦西里民宿", - "inSnapshot": true - }, - { - "hotelId": "2033911514863382530", - "hotelName": "额尔古纳大酒店", - "inSnapshot": false - } - ] -} -``` - -#### 响应字段说明 - -| 字段 | 类型 | 说明 | -|------|------|------| -| hotelId | String | 酒店ID | -| hotelName | String | 酒店名称 | -| inSnapshot | Boolean | 是否在该天产品快照中（true=该天行程已安排的酒店，应优先选择） | - -- `inSnapshot=true` 的酒店排在前面 -- 同时返回所有启用酒店供选择 - ---- - -## 前端改动要点 - -配房弹窗中选择酒店时，调用此接口需传当前正在配的那一天的 `dayIndex`： - -```js -// 示例：配第2天的房间 -const res = await request.get(`/admin/order/${orderId}/available-hotels`, { - params: { dayIndex: 2 } -}) -``` - -**注意**：`dayIndex` 从 **1** 开始，对应行程的第1天、第2天... - ---- - -## 同步修复：产品保存报错 - -`refundPolicyIds` 字段兼容前端传空数组 `[]` 的情况（之前只接受对象 `{}`，传 `[]` 会返回400）。现在传 `[]` 等价于 `null`，不影响保存。 diff --git a/changelogs/2026-03/2026-03-20_comprehensive_frontend_guide.md b/changelogs/2026-03/2026-03-20_comprehensive_frontend_guide.md deleted file mode 100644 index 2010116..0000000 --- a/changelogs/2026-03/2026-03-20_comprehensive_frontend_guide.md +++ /dev/null @@ -1,624 +0,0 @@ -# 综合前端对接指南 — 产品自动化配置 + 保险 + 合同 + 配房 + 配车 - -> **日期**: 2026-03-20 -> **后端状态**: ✅ 已完成，可直接对接 -> **涉及服务**: hl-product-service、hl-order-service、hl-insurance-service、hl-contract-service、hl-resource-service - ---- - -## 一、整体变更说明 - -### 核心改动 - -1. **产品新增10个保险+合同配置字段**（创建时必填）：产品绑定保险方案和合同配置 -2. **订单支付后自动投保+自动签约**：出行人补全后系统自动完成，无需管理员手动操作 -3. **去掉「确认订单」步骤**：原6步待办缩减为5步，`CONFIRM_ORDER` 已删除 -4. **`PROCESSING` 流程状态已删除**：`PENDING_INFO` 直接跳到 `PENDING_INSURANCE` -5. **配房改为按天粒度**：每天每个家庭一条记录，新增房型升级差价自动计算 -6. **配房升级差价预览**：提交配房前可预览差价明细 - -### 新的订单内部流程 - -``` -支付成功 → 创建5个待办 → 出行人补全 → 系统自动确认订单 - → 自动投保（按产品绑定的保险方案） ← INSURANCE待办自动完成 - → 自动签约（按产品绑定的合同配置） ← CONTRACT待办等签署回调完成 - → 手动配房 (ARRANGE_ROOM) - → 手动配车 (ARRANGE_VEHICLE) - → 手动确认清单 (CONFIRM_CHECKLIST) -``` - -**容错**：自动投保/签约失败时，待办保持 PENDING，管理员可手动处理。 - ---- - -## 二、破坏性变更（前端必须适配） - -### 1. 待办类型变更 - -| 原 todoType | 原序号 | 新 todoType | 新序号 | 说明 | -|-------------|--------|-------------|--------|------| -| CONFIRM_ORDER | 1 | **已删除** | - | 不再需要手动确认 | -| INSURANCE | 2 | INSURANCE | 1 | 可被系统自动完成 | -| CONTRACT | 3 | CONTRACT | 2 | 可被系统自动完成 | -| ARRANGE_ROOM | 4 | ARRANGE_ROOM | 3 | 手动 | -| ARRANGE_VEHICLE | 5 | ARRANGE_VEHICLE | 4 | 手动 | -| CONFIRM_CHECKLIST | 6 | CONFIRM_CHECKLIST | 5 | 手动 | - -**前端注意**： -- 不要 hardcode `CONFIRM_ORDER` 的判断 -- 待办序号已变化（INSURANCE 从 2 变为 1） -- INSURANCE/CONTRACT 待办可能被系统自动完成，展示时注意区分 - -### 2. processStatus 变更 - -| 原流程 | 新流程 | -|--------|--------| -| PENDING_INFO → **PROCESSING** → PENDING_INSURANCE → ... | PENDING_INFO → PENDING_INSURANCE → ... | - -`PROCESSING` 状态已删除，相关状态标签/过滤条件需要去掉。 - -**有效的 processStatus 值**： -`PENDING_INFO` / `PENDING_INSURANCE` / `PENDING_CONTRACT` / `PENDING_ROOM` / `PENDING_VEHICLE` / `PENDING_FINANCE` / `READY` / `INTERNAL_CONFIRMED` - -### 3. 配房接口破坏性变更 - -从「按日期区间」改为「按天粒度」，详见下方配房章节。 - ---- - -## 三、产品服务 — 新增保险与合同配置 - -### 页面布局建议 - -在产品编辑页基本信息之后增加「保险与合同配置」区域： - -``` -┌─────────────────────────────────────────┐ -│ 保险与合同配置 │ -├─────────────────────────────────────────┤ -│ 保险方案：[下拉选择] ← GET /admin/insurance/scheme/list │ -│ │ -│ 合同平台：[12301 ▼] / [法大大 ▼] │ -│ 合同模板：[下拉选择] ← GET /admin/contract/templates │ -│ 签约模式：[电子签约 ▼] / [线下报备 ▼] │ -│ 签署模式：[短信 ▼] / [现场 ▼] / [线下 ▼] │ -│ 旅行社： [下拉选择] ← GET /admin/insurance/entities │ -│ 争议解决：[仲裁 ▼] / [诉讼 ▼] │ -│ 经办人姓名：[________] │ -│ 经办人电话：[________] │ -│ 补充条款：[________________] (可选) │ -└─────────────────────────────────────────┘ -``` - -### 接口 1：创建产品（新增必填字段） - -``` -POST /admin/product -``` - -**新增请求字段**（所有字段必填，`supplementaryClause` 除外）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| insuranceSchemeId | Long | 是 | 保险方案ID，从 `GET /admin/insurance/scheme/list` 获取 | -| contractPlatform | String | 是 | 合同平台：`12301`（全国旅游监管平台）/ `FADADA`（法大大） | -| contractTemplateCode | String | 是 | 合同模板编码，从 `GET /admin/contract/templates` 获取 | -| contractMode | String | 是 | 签约模式：`STANDARD`（电子签约）/ `SYNC`（线下报备） | -| signatoryMode | Integer | 是 | 签署模式：`1`=短信签署 / `2`=现场签署 / `3`=线下签署 | -| agencyCode | String | 是 | 旅行社编码，从 `GET /admin/insurance/entities` 获取 | -| disputeResolution | Integer | 是 | 争议解决方式：`1`=仲裁 / `2`=诉讼 | -| supplementaryClause | String | 否 | 合同补充条款 | -| transactorName | String | 是 | 经办人姓名 | -| transactorPhone | String | 是 | 经办人电话 | - -### 接口 2：编辑产品（新增可选字段） - -``` -PUT /admin/product/{productId} -``` - -同上 10 个字段，**全部可选**（不传则不更新）。 - -### 接口 3：统一保存产品（新增字段） - -``` -POST /admin/product/save -``` - -同上 10 个字段，创建时必填，更新时可选。 - -### 接口 4：产品详情响应（新增返回字段） - -``` -GET /admin/product/{productId} -``` - -**响应新增字段**（ProductVO 和 ProductListVO 均返回）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| insuranceSchemeId | String | 保险方案ID | -| contractPlatform | String | 合同平台：`12301` / `FADADA` | -| contractTemplateCode | String | 合同模板编码 | -| contractMode | String | 签约模式：`STANDARD` / `SYNC` | -| signatoryMode | Integer | 签署模式：1/2/3 | -| agencyCode | String | 旅行社编码 | -| disputeResolution | Integer | 争议解决方式：1/2 | -| supplementaryClause | String | 补充条款 | -| transactorName | String | 经办人姓名 | -| transactorPhone | String | 经办人电话 | - -### 下拉数据源接口 - -#### 保险方案列表（产品编辑页下拉） - -``` -GET /admin/insurance/scheme/list -``` - -**使用场景**：产品编辑页「保险方案」下拉选择。 - -**响应示例**： -```json -{ - "code": 200, - "data": [ - { - "id": "1901234567890", - "name": "国内5天标准保障", - "description": "覆盖5天国内行程的基础保障方案", - "isOverseas": false, - "status": "ACTIVE", - "segments": [ - { - "segmentIndex": 1, - "insuranceProductId": "100", - "planId": "200", - "startDayOffset": 0, - "endDayOffset": 4 - } - ] - } - ] -} -``` - -#### 合同模板列表（产品编辑页下拉） - -``` -GET /admin/contract/templates -``` - -**使用场景**：产品编辑页「合同模板」下拉选择。 - -**响应示例**： -```json -{ - "code": 200, - "data": [ - { - "templateCode": "TOURAGE_STANDARD", - "templateName": "国内旅游标准合同", - "platform": "12301", - "mode": "STANDARD" - } - ] -} -``` - -#### 合同平台列表（产品编辑页下拉） - -``` -GET /admin/contract/platforms -``` - -**使用场景**：产品编辑页「合同平台」下拉选择。 - -#### 旅行社列表（产品编辑页下拉） - -``` -GET /admin/insurance/entities -``` - -**使用场景**：产品编辑页「旅行社」下拉选择（agencyCode 使用此列表中的 code 值）。 - -**响应示例**： -```json -{ - "code": 200, - "data": [ - { - "code": "HLNMG", - "companyName": "内蒙古呼籁国际旅行社有限公司" - } - ] -} -``` - ---- - -## 四、保险服务 — 手动配置保险 - -订单保险在正常流程中会自动完成（支付后系统自动投保），但管理员也可以手动操作。手动配保险有两种方式： - -### 页面布局建议 - -``` -┌─────────────────────────────────────────┐ -│ 保险配置 │ -├─────────────────────────────────────────┤ -│ ● 选择保险方案（推荐） │ -│ [方案下拉] → 预览 → 确认投保 │ -│ │ -│ ○ 按天手动配置 │ -│ 保险产品：[下拉] │ -│ 保险计划：[下拉] │ -│ 开始日期：[____] 结束日期：[____] │ -│ [试算保费] [确认投保] │ -└─────────────────────────────────────────┘ -``` - -### 方式一：选择保险方案投保（推荐） - -#### 步骤1：选择方案 → 预览 - -``` -POST /admin/insurance/scheme/preview-apply -``` - -**使用场景**：管理员选择保险方案后，预览投保效果（各段日期、保费明细）。 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| schemeId | Long | 是 | 保险方案ID（从方案列表获取） | -| orderId | Long | 是 | 订单ID（自动获取出行日期和人数） | - -**响应**：返回各段的日期范围、计划信息、单人保费、总保费、日期间隙警告。 - -#### 步骤2：确认后逐段投保 - -确认后前端按预览结果中的各段信息，逐段调用 purchase 接口（参考方式二）。 - -### 方式二：按天手动投保 - -#### 接口 1：查询保险产品列表 - -``` -GET /admin/insurance/products?isOverseas=false -``` - -**使用场景**：按天手动投保时，选择保险产品。 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| isOverseas | Boolean | 否 | 是否境外保险，默认 false | -| page | Integer | 否 | 页码 | -| pageSize | Integer | 否 | 每页条数 | - -#### 接口 2：查询保险计划列表 - -``` -GET /admin/insurance/products/{productId}/plans -``` - -**使用场景**：选择保险产品后，查看该产品下的保险计划及费率。 - -#### 接口 3：保费试算 - -``` -POST /admin/insurance/trial-price -``` - -**使用场景**：选择计划和日期后，试算保费（不下单）。 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| planId | Long | 是 | 保险计划ID | -| startDate | String | 是 | 保障开始日期 yyyy-MM-dd | -| endDate | String | 是 | 保障结束日期 yyyy-MM-dd | -| insuredCount | Integer | 是 | 被保人数 | - -#### 接口 4：确认投保 - -``` -POST /admin/insurance/purchase -``` - -**使用场景**：确认投保，创建保险订单。 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 否 | 关联的旅行订单ID | -| planId | Long | 是 | 保险计划ID | -| startDate | String | 是 | 保障开始日期 yyyy-MM-dd | -| endDate | String | 是 | 保障结束日期 yyyy-MM-dd | -| insuredPersons | Array | 是 | 被保人列表（至少1人） | -| insuredPersons[].name | String | 是 | 姓名 | -| insuredPersons[].idCardType | String | 否 | 证件类型：`ID_CARD`/`PASSPORT`/`OTHER`，默认 ID_CARD | -| insuredPersons[].idCardNo | String | 是 | 证件号 | -| insuredPersons[].birthday | String | 是 | 出生日期 yyyy-MM-dd | -| insuredPersons[].gender | String | 是 | 性别：`MALE`/`FEMALE` | -| entityCode | String | 否 | 投保公司编码，默认使用系统默认主体 | - -**响应**：`List`，每条包含保险单号、状态、被保人信息等。 - -### 保险查询与管理接口 - -| # | 接口 | 方法 | 路径 | 说明 | -|---|------|------|------|------| -| 1 | 按订单查保险 | GET | `/admin/insurance/orders/by-order/{orderId}` | 查询订单关联的保险单列表 | -| 2 | 保险保障详情 | GET | `/admin/insurance/coverage/{orderId}` | 查询订单保险保障（含被保人详情） | -| 3 | 保险订单详情 | GET | `/admin/insurance/orders/{id}` | 单条保险订单详情 | -| 4 | 退保 | POST | `/admin/insurance/cancel/{id}` | 退保（管理员手动退保） | -| 5 | 下载保单 | GET | `/admin/insurance/policy/{id}/download` | 下载保单PDF（Base64） | -| 6 | 分享保单 | POST | `/admin/insurance/share-policy` | 分享保单给用户 | -| 7 | 账户余额 | GET | `/admin/insurance/balance` | 查询保游网账户余额 | -| 8 | 在线充值 | POST | `/admin/insurance/recharge` | 保游网在线充值 | - ---- - -## 五、合同服务 — 手动配置合同 - -订单合同在正常流程中会自动完成（支付后系统自动发起签约），但管理员也可以手动操作。 - -### 接口 1：创建合同（电子签约模式 STANDARD） - -``` -POST /admin/contract/create -``` - -**使用场景**：手动创建合同，发送签署短信给游客。合同签署完成后 CONTRACT 待办自动完成。 - -**请求体**：CreateContractRequest（字段较多，参见 Knife4j 文档） - -### 接口 2：报备合同（线下报备模式 SYNC） - -``` -POST /admin/contract/report -``` - -**使用场景**：线下签约后报备合同，报备成功 CONTRACT 待办自动完成。 - -### 合同查询与管理接口 - -| # | 接口 | 方法 | 路径 | 说明 | -|---|------|------|------|------| -| 1 | 合同列表 | GET | `/admin/contract/list` | 分页查询，支持按订单/状态/旅行社筛选 | -| 2 | 合同详情 | GET | `/admin/contract/{id}` | 单条合同详情 | -| 3 | 按订单查合同 | GET | `/admin/contract/by-order/{orderId}` | 查询订单关联的所有合同（含已作废） | -| 4 | 订单有效合同 | GET | `/admin/contract/active-by-order/{orderId}` | 获取订单最新有效合同 | -| 5 | 刷新合同状态 | GET | `/admin/contract/{id}/status` | 从平台同步最新签署状态 | -| 6 | 作废合同 | POST | `/admin/contract/{id}/invalidate` | 作废合同（可重新签约） | -| 7 | 重发签署短信 | POST | `/admin/contract/{id}/resend-sms` | 重发签署短信（STANDARD模式） | -| 8 | 上传已签署PDF | POST | `/admin/contract/{id}/upload-pdf` | 上传线下签署的PDF（SYNC模式） | -| 9 | 合同模板列表 | GET | `/admin/contract/templates` | 可用合同模板（下拉选择） | -| 10 | 合同平台列表 | GET | `/admin/contract/platforms` | 可用合同平台 | -| 11 | 旅行社列表 | GET | `/admin/contract/agencies` | 可用旅行社 | - -### 合同状态字典（contract_status） - -| 值 | 中文 | 说明 | -|----|------|------| -| CREATED | 已创建 | 合同已创建，待发起签署 | -| SIGNING | 签署中 | 已发送签署短信，等待签署 | -| SIGNED | 已签署 | 合同已签署完成 | -| UPLOADED | 已上传 | 已上传签署PDF（SYNC模式） | -| REPORTED | 已报备 | 已向平台报备（SYNC模式） | -| INVALID | 已作废 | 合同已作废 | - ---- - -## 六、配房 — 按天粒度 + 房型升级差价 - -### 破坏性变更 - -配房接口从「按家庭+日期区间」改为「按天按家庭」粒度。**`checkInDate` 和 `checkOutDate` 字段已删除**，改用 `date` 单天日期。 - -### 接口 1：配房升级差价预览（新增） - -``` -POST /admin/order/{orderId}/hotel-assignment/preview -``` - -**使用场景**：选择酒店和房型后，提交前预览房型升级差价。前端根据返回的差价信息展示给用户确认。 - -**请求体**：同分配酒店信息接口 - -**响应**：`RoomUpgradePreviewVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| details | Array | 各天差价明细（仅有差价的天） | -| details[].familyIndex | Integer | 家庭序号 | -| details[].date | String | 日期 | -| details[].defaultRoomTypeId | Long | 产品默认房型ID | -| details[].defaultRoomTypeName | String | 产品默认房型名称 | -| details[].assignedRoomTypeId | Long | 实际分配房型ID | -| details[].assignedRoomTypeName | String | 实际分配房型名称 | -| details[].defaultPrice | BigDecimal | 默认房型当天单价 | -| details[].assignedPrice | BigDecimal | 实际房型当天单价 | -| details[].dayDiff | BigDecimal | 当天差价（正=补款，负=退款） | -| details[].direction | String | `UPGRADE` / `DOWNGRADE` / `SAME` | -| details[].remark | String | 备注 | -| totalDiff | BigDecimal | 差价合计 | -| direction | String | `UPGRADE` / `DOWNGRADE` / `SAME` / `MIXED` | -| description | String | 差价描述（如「共 2 天有差价，合计 +400.00」） | - -**响应示例**： -```json -{ - "code": 200, - "data": { - "details": [ - { - "familyIndex": 1, - "date": "2026-04-01", - "defaultRoomTypeId": 2002, - "defaultRoomTypeName": "标间", - "assignedRoomTypeId": 2001, - "assignedRoomTypeName": "豪华大床房", - "defaultPrice": 300.00, - "assignedPrice": 500.00, - "dayDiff": 200.00, - "direction": "UPGRADE", - "remark": "需要加床" - } - ], - "totalDiff": 200.00, - "direction": "UPGRADE", - "description": "共 1 天有差价，合计 +200.00" - } -} -``` - -### 接口 2：分配酒店信息（破坏性变更） - -``` -PUT /admin/order/{orderId}/hotel-assignment -``` - -**使用场景**：为订单按天按家庭分配具体酒店房间。每天每个家庭一条记录。 - -**请求体**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| assignments | Array | 是 | 酒店分配列表（按天按家庭，每天每个家庭一条） | -| assignments[].familyIndex | Integer | 是 | 家庭序号 | -| assignments[].hotelId | Long | 是 | 酒店ID | -| assignments[].hotelName | String | 是 | 酒店名称 | -| assignments[].roomTypeId | Long | 是 | 房型ID | -| assignments[].roomType | String | 是 | 房型名称 | -| assignments[].date | String | 是 | 单天日期 `yyyy-MM-dd`（**替代原 checkInDate/checkOutDate**） | -| assignments[].remark | String | 否 | 当天备注（新增） | -| assignments[].upgradePrice | BigDecimal | 否 | 手动覆盖升级差价（null=使用系统计算值） | - -**删除的字段**：`checkInDate`、`checkOutDate` - -**房型升级逻辑（自动触发）**： -- 分配的 roomTypeId 与产品默认房型不同 → 自动计算差价 -- CORE产品（快照中 roomTypeId 为 null）→ 默认基准为该酒店的标间（STANDARD） -- 差价 = 新房型日价格 - 默认房型日价格（来自价格日历） -- `upgradePrice` 可手动覆盖系统计算的差价 -- **定制师操作**：差价自动确认，直接调整订单总售价 -- **其他角色操作**：差价设为「待确认」临时加到尾款，通知定制师确认 - -**请求示例**： -```json -{ - "assignments": [ - { - "familyIndex": 1, - "hotelId": 1001, - "hotelName": "呼伦贝尔大酒店", - "roomTypeId": 2001, - "roomType": "豪华大床房", - "date": "2026-04-01", - "remark": "需要加床" - }, - { - "familyIndex": 1, - "hotelId": 1001, - "hotelName": "呼伦贝尔大酒店", - "roomTypeId": 2001, - "roomType": "豪华大床房", - "date": "2026-04-02", - "remark": "" - }, - { - "familyIndex": 2, - "hotelId": 1001, - "hotelName": "呼伦贝尔大酒店", - "roomTypeId": 2002, - "roomType": "标间", - "date": "2026-04-01", - "remark": "" - } - ] -} -``` - -**响应**：`Result` - -### 接口 3：查询可用酒店列表 - -``` -GET /admin/order/{orderId}/available-hotels?dayIndex=1 -``` - -**使用场景**：配房时根据行程天数查询可选酒店（产品快照中的酒店优先排序）。 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| dayIndex | Integer | 是 | 行程第几天（1开始） | - -### 推荐交互流程 - -``` -选择酒店+房型 → 填写每天备注 → 点击「预览差价」 - → 调用 POST preview 接口 - → 展示差价明细（可修改 upgradePrice） - → 点击「确认配房」→ 调用 PUT hotel-assignment -``` - ---- - -## 七、配车 - -### 接口：分配车辆信息 - -``` -PUT /admin/order/{orderId}/vehicle-assignment -``` - -**使用场景**：为订单分配具体车辆和司机信息。 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| vehicleModel | String | 是 | 车型（如「别克GL8」） | -| vehicleBrand | String | 是 | 品牌（如「别克」） | -| plateNumber | String | 否 | 车牌号 | -| driverName | String | 否 | 司机姓名 | -| driverPhone | String | 否 | 司机电话 | - -**响应**：`Result` - ---- - -## 八、尾款调整汇总（字段增强） - -``` -GET /admin/order/{orderId}/itinerary/balance-summary -``` - -**使用场景**：订单详情页展示尾款调整明细，包含行程编辑和房型升级产生的差价。 - -**响应新增字段**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| confirmedAdjustment | BigDecimal | 已确认的调整金额（已计入总售价） | -| pendingAdjustment | BigDecimal | 待确认的调整金额（临时，待定制师确认） | -| totalAdjustment | BigDecimal | 合计（已确认 + 待确认） | -| details[].confirmStatus | String | `CONFIRMED`（已确认）或 `PENDING_CONFIRM`（待确认） | - -**页面展示**： -- 展示「已确认调整」和「待确认调整（临时）」两个金额 -- 待确认项标记为临时状态，提示「待定制师确认」 - ---- - -## 九、枚举/字典值汇总 - -| 字段 | 可选值 | 说明 | -|------|--------|------| -| contractPlatform | `12301` / `FADADA` | 合同平台 | -| contractMode | `STANDARD` / `SYNC` | 签约模式：电子签约 / 线下报备 | -| signatoryMode | `1` / `2` / `3` | 签署模式：1=短信 / 2=现场 / 3=线下 | -| disputeResolution | `1` / `2` | 争议解决：1=仲裁 / 2=诉讼 | -| todoType | `INSURANCE` / `CONTRACT` / `ARRANGE_ROOM` / `ARRANGE_VEHICLE` / `CONFIRM_CHECKLIST` | 待办类型（CONFIRM_ORDER 已删除） | -| processStatus | `PENDING_INFO` / `PENDING_INSURANCE` / `PENDING_CONTRACT` / `PENDING_ROOM` / `PENDING_VEHICLE` / `PENDING_FINANCE` / `READY` / `INTERNAL_CONFIRMED` | 内部流程状态（PROCESSING 已删除） | -| contract_status | `CREATED` / `SIGNING` / `SIGNED` / `UPLOADED` / `REPORTED` / `INVALID` | 合同状态 | -| upgradeDirection | `UPGRADE` / `DOWNGRADE` / `SAME` / `MIXED` | 房型升级方向 | -| confirmStatus | `CONFIRMED` / `PENDING_CONFIRM` | 尾款调整确认状态 | diff --git a/changelogs/2026-03/2026-03-20_contract_scheme.md b/changelogs/2026-03/2026-03-20_contract_scheme.md deleted file mode 100644 index 0ec9066..0000000 --- a/changelogs/2026-03/2026-03-20_contract_scheme.md +++ /dev/null @@ -1,181 +0,0 @@ -# 合同方案 + 产品合同配置改版 + 支付前出行人校验 - -## 功能说明 - -### 1. 合同方案管理（新增） -合同配置改为"合同方案"模式（与保险方案一致），产品只需选择一个合同方案ID。 - -### 2. 产品合同配置改版（破坏性变更） -产品上原来的 9 个合同字段（contractPlatform, contractTemplateCode, contractMode, signatoryMode, agencyCode, disputeResolution, supplementaryClause, transactorName, transactorPhone）已全部删除，替换为单个 `contractSchemeId` 字段。 - -### 3. 支付前出行人校验规则变更 -- **预约产品**（isBooking=true）：定金支付不要求出行人，全款/尾款要求出行人齐全 -- **非预约产品**（isBooking=false）：所有支付类型都要求出行人齐全 - -### 4. HTTP 200 统一化 -所有接口只要请求能到达服务器，HTTP状态码一律返回200，业务错误在响应体Result中返回。 - ---- - -## 合同方案接口清单 - -### 查询启用的合同方案列表（下拉选择用） -- **GET** `/admin/contract/scheme/list` -- **响应**：`Result>` - -### 查询全部合同方案列表（管理页面用） -- **GET** `/admin/contract/scheme/list-all` -- **响应**：`Result>` - -### 获取合同方案详情 -- **GET** `/admin/contract/scheme/{schemeId}` -- **响应**：`Result` - -### 创建合同方案 -- **POST** `/admin/contract/scheme` -- **请求体**：`ContractSchemeRequest` -- **响应**：`Result` - -### 更新合同方案 -- **PUT** `/admin/contract/scheme/{schemeId}` -- **请求体**：`ContractSchemeRequest` -- **响应**：`Result` - -### 切换方案启用/停用状态 -- **PUT** `/admin/contract/scheme/{schemeId}/toggle-status` -- **响应**：`Result` - -### 删除合同方案 -- **DELETE** `/admin/contract/scheme/{schemeId}` -- **响应**：`Result` - ---- - -## ContractSchemeRequest 参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| name | String | 是 | 方案名称，如"标准国内电子签约方案" | -| description | String | 否 | 方案描述 | -| contractPlatform | String | 是 | 合同平台：`12301`（全国旅游监管平台）/ `FADADA`（法大大） | -| contractTemplateCode | String | 是 | 合同模板编码，如 `TOURAGE_STANDARD` | -| contractMode | String | 是 | 签约模式：`STANDARD`（电子签约）/ `SYNC`（线下报备） | -| signatoryMode | Integer | 是 | 签署模式：`1`=短信签署 `2`=现场签署 `3`=线下签署 | -| agencyCode | String | 是 | 旅行社编码 | -| disputeResolution | Integer | 是 | 争议解决方式：`1`=仲裁 `2`=诉讼 | -| supplementaryClause | String | 否 | 补充条款 | -| transactorName | String | 是 | 经办人姓名 | -| transactorPhone | String | 是 | 经办人电话 | -| sortOrder | Integer | 否 | 排序（越小越靠前） | - -## ContractSchemeVO 响应 - -| 字段 | 类型 | 说明 | -|------|------|------| -| schemeId | String | 方案ID | -| name | String | 方案名称 | -| description | String | 方案描述 | -| contractPlatform | String | 合同平台：12301/FADADA | -| contractTemplateCode | String | 合同模板编码 | -| contractMode | String | 签约模式：STANDARD/SYNC | -| signatoryMode | Integer | 签署模式：1=短信 2=现场 3=线下 | -| agencyCode | String | 旅行社编码 | -| disputeResolution | Integer | 争议解决方式：1=仲裁 2=诉讼 | -| supplementaryClause | String | 补充条款 | -| transactorName | String | 经办人姓名 | -| transactorPhone | String | 经办人电话 | -| sortOrder | Integer | 排序 | -| status | String | 状态：ACTIVE/INACTIVE | -| createTime | DateTime | 创建时间 | - ---- - -## 产品接口变更（破坏性变更） - -### 产品创建/更新/保存接口 - -**删除的字段**（以下字段不再使用）： -- ~~contractPlatform~~ -- ~~contractTemplateCode~~ -- ~~contractMode~~ -- ~~signatoryMode~~ -- ~~agencyCode~~ -- ~~disputeResolution~~ -- ~~supplementaryClause~~ -- ~~transactorName~~ -- ~~transactorPhone~~ - -**新增的字段**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| contractSchemeId | Long | 是（创建时） | 合同方案ID，从 `/admin/contract/scheme/list` 获取 | - -### 产品详情接口 - -**响应变更**： -- 删除 9 个合同字段 -- 新增 `contractSchemeId`（String类型） - ---- - -## 页面布局建议 - -### 合同方案管理页面 -路径建议：系统管理 → 合同方案管理（类似保险方案管理） -- 列表页：方案名称、合同平台、签约模式、旅行社、状态、操作（编辑/启停/删除） -- 新建/编辑弹窗：ContractSchemeRequest 的所有字段 - -### 产品编辑页面 — 合同配置区域改版 - -**原来**（9个表单项）： -``` -合同平台 * [12301] [法大大] -合同模板 * [下拉选择] -签约模式 * [电子签约] [线下报备] -签署模式 * [短信签署] [现场签署] [线下签署] -旅行社 * [下拉选择] -争议解决方式 * [仲裁] [诉讼] -补充条款 [文本框] -经办人姓名 * [文本框] -经办人电话 * [文本框] -``` - -**现在**（1个下拉选择）： -``` -合同方案 * [请选择合同方案 ▼] -``` -下拉数据来源：`GET /admin/contract/scheme/list`（返回启用的方案列表） - ---- - -## 调用示例 - -### 创建合同方案 -```json -POST /admin/contract/scheme -{ - "name": "标准国内电子签约方案", - "contractPlatform": "12301", - "contractTemplateCode": "TOURAGE_STANDARD", - "contractMode": "STANDARD", - "signatoryMode": 1, - "agencyCode": "L-NMG-100001", - "disputeResolution": 1, - "transactorName": "张三", - "transactorPhone": "13800138000", - "sortOrder": 0 -} -``` - -### 产品创建（使用合同方案ID） -```json -POST /admin/product -{ - "name": "冰雪3.0南线", - "productType": "CORE", - "insuranceSchemeId": 123456789, - "contractSchemeId": 987654321, - ... -} -``` diff --git a/changelogs/2026-03/2026-03-20_contract_scheme_updates.md b/changelogs/2026-03/2026-03-20_contract_scheme_updates.md deleted file mode 100644 index b4f1bed..0000000 --- a/changelogs/2026-03/2026-03-20_contract_scheme_updates.md +++ /dev/null @@ -1,170 +0,0 @@ -# 接口变更记录 — 2026-03-20（合同方案 + 模板筛选） - -> **类型** feature + fix - ---- - -## 一、合同方案管理菜单已添加 - -"合同管理"下新增"合同方案"子菜单，排在合同列表前面。 - ---- - -## 二、合同模板接口支持按平台筛选 - -### `GET` /admin/contract/templates - -新增可选参数 `platform`，前端根据合同方案表单中选择的"合同平台"传值，实现模板联动筛选。 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `platform` | String | 否 | 合同平台：`12301`=全国旅游监管平台，`FADADA`=法大大。不传则返回全部 | - -**前端调整**： -- 合同方案新增/编辑表单中，选择"合同平台"后，调用 `/admin/contract/templates?platform=12301` 或 `?platform=FADADA` 刷新合同模板下拉列表 -- 切换平台时需清空已选的合同模板 - ---- - -## 三、合同方案 — 旅行社改为非必填 - -### 变更说明 - -`ContractSchemeRequest` 中 `agencyCode`（旅行社编码）从**必填**改为**可选**。 - -**业务逻辑**：不填旅行社时，创建合同时会根据订单支付的商户号自动匹配对应公司的旅行社。 - -### `POST` /admin/contract/scheme — 创建合同方案 -### `PUT` /admin/contract/scheme/{schemeId} — 更新合同方案 - -| 字段 | 变更 | 说明 | -|------|------|------| -| `agencyCode` | 必填 → **可选** | 不填则根据订单支付商户号自动匹配旅行社 | - -**前端调整**： -- "旅行社"字段去掉必填星号 `*` -- 可以保留下拉选择，但允许不选 -- 表单提交时不再校验旅行社必填 - ---- - -## 四、合同方案管理接口一览 - -以下接口用于"合同管理 → 合同方案"页面： - -### `GET` /admin/contract/scheme/list-all — 全部方案列表（管理页面） - -**响应**：`Result>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `schemeId` | String | 方案ID | -| `name` | String | 方案名称 | -| `description` | String | 方案描述 | -| `contractPlatform` | String | 合同平台：`12301`/`FADADA` | -| `contractTemplateCode` | String | 合同模板编码 | -| `contractMode` | String | 签约模式：`STANDARD`=电子签约，`SYNC`=线下报备 | -| `signatoryMode` | Integer | 签署模式：1=短信签署，2=现场签署，3=线下签署 | -| `agencyCode` | String | 旅行社编码（可能为空） | -| `disputeResolution` | Integer | 争议解决方式：1=仲裁，2=诉讼 | -| `supplementaryClause` | String | 补充条款 | -| `transactorName` | String | 经办人姓名 | -| `transactorPhone` | String | 经办人电话 | -| `sortOrder` | Integer | 排序 | -| `status` | String | 状态：`ACTIVE`/`INACTIVE` | - -### `GET` /admin/contract/scheme/list — 启用方案列表（产品配置下拉） - -只返回 `status=ACTIVE` 的方案，用于产品编辑页"合同方案"下拉选择。 - -### `POST` /admin/contract/scheme — 创建方案 - -**请求参数**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `name` | String | 是 | 方案名称 | -| `description` | String | 否 | 方案描述 | -| `contractPlatform` | String | 是 | 合同平台：`12301`/`FADADA` | -| `contractTemplateCode` | String | 是 | 合同模板编码（从模板列表接口获取） | -| `contractMode` | String | 是 | 签约模式：`STANDARD`/`SYNC` | -| `signatoryMode` | Integer | 是 | 签署模式：1/2/3 | -| `agencyCode` | String | **否** | 旅行社编码（不填则自动匹配） | -| `disputeResolution` | Integer | 是 | 争议解决方式：1=仲裁，2=诉讼 | -| `supplementaryClause` | String | 否 | 补充条款 | -| `transactorName` | String | 是 | 经办人姓名 | -| `transactorPhone` | String | 是 | 经办人电话 | -| `sortOrder` | Integer | 否 | 排序（默认0） | - -### `PUT` /admin/contract/scheme/{schemeId} — 更新方案 - -请求参数同创建。 - -### `PUT` /admin/contract/scheme/{schemeId}/toggle-status — 切换启用/停用 - -### `DELETE` /admin/contract/scheme/{schemeId} — 删除方案 - ---- - -## 五、合同方案响应新增回显字段 + 字段别名 - -### 变更说明 - -合同方案响应（`ContractSchemeVO`）新增以下字段，解决**编辑回显**和**字段命名统一**问题： - -| 新增字段 | 类型 | 说明 | -|----------|------|------| -| `templateCode` | String | 合同模板编码（与 `contractTemplateCode` **相同值**，方便前端统一使用 `templateCode` 绑定下拉） | -| `contractTemplateName` | String | 合同模板名称（回显用，如"国内旅游合同-标准版"） | -| `agencyName` | String | 旅行社名称（回显用，如"内蒙古呼籁国际旅行社有限公司"） | - -### 保存时字段兼容 - -保存（创建/更新）时，**`contractTemplateCode` 和 `templateCode` 都接受**。前端可以统一用 `templateCode` 作为合同模板下拉的 `value` 字段。 - -```json -// 以下两种写法等价： -{ "contractTemplateCode": "A00001", ... } -{ "templateCode": "A00001", ... } -``` - -### 前端使用方式 - -1. **模板下拉绑定**：用 `templateCode` 作为下拉的 `v-model` 绑定值 -2. **编辑回显**：方案详情返回的 `templateCode` 可直接匹配模板列表的 `templateCode` -3. **模板名称显示**：列表页可直接用 `contractTemplateName` 显示模板名称，无需额外查询 -4. **旅行社名称显示**：列表页可用 `agencyName` 显示旅行社名称 - -### 完整响应示例 - -```json -{ - "schemeId": "123456789", - "name": "标准国内电子签约方案", - "contractPlatform": "12301", - "contractTemplateCode": "A00001", - "templateCode": "A00001", - "contractTemplateName": "国内旅游合同-标准版", - "contractMode": "STANDARD", - "signatoryMode": 1, - "agencyCode": "agency_hlgj", - "agencyName": "内蒙古呼籁国际旅行社有限公司", - "disputeResolution": 1, - "transactorName": "张三", - "transactorPhone": "13800138000", - "sortOrder": 0, - "status": "ACTIVE" -} -``` - ---- - -## 前端重点调整总结 - -| 页面 | 调整项 | -|------|--------| -| 合同方案新增/编辑表单 | "旅行社"去掉必填星号，允许不选 | -| 合同方案新增/编辑表单 | "合同模板"下拉根据选择的"合同平台"联动筛选，调用 `/admin/contract/templates?platform=xxx` | -| 合同方案新增/编辑表单 | 切换合同平台时清空已选的合同模板 | -| 合同方案新增/编辑表单 | 模板下拉 `v-model` 绑定 `templateCode`（保存和回显统一使用此字段） | -| 合同方案列表页 | 可用 `contractTemplateName` 和 `agencyName` 直接显示名称 | diff --git a/changelogs/2026-03/2026-03-20_gateway_room_type_fix.md b/changelogs/2026-03/2026-03-20_gateway_room_type_fix.md deleted file mode 100644 index 2644ce8..0000000 --- a/changelogs/2026-03/2026-03-20_gateway_room_type_fix.md +++ /dev/null @@ -1,28 +0,0 @@ -# 接口变更记录 — 2026-03-20 - -> **提交** `9e002e6` · **类型** bugfix -> -> fix: Gateway白名单补充房型详情接口路径 - -## 问题说明 - -小程序房型详情接口 `GET /mp/hotel/room-type/{roomTypeId}` 返回 **404**。 - -**原因**：Gateway 的 `JwtAuthFilter` 白名单遗漏了 `/mp/hotel/room-type/*` 路径，导致请求被 JWT 认证拦截。 - -## 修复内容 - -- Gateway `JwtAuthFilter` 白名单新增 `/mp/hotel/room-type/*` - -## 前端影响 - -- **无需任何修改**，接口路径、参数、响应格式不变 -- 修复部署后 `GET /mp/hotel/room-type/{roomTypeId}` 即可正常调用（无需登录token） - -## 关联接口 - -| 方法 | 路径 | 说明 | 是否需要登录 | -|------|------|------|-------------| -| GET | `/mp/hotel/room-type/{roomTypeId}` | 房型详情 | **否**（公开接口） | - -> 接口详细字段定义见 `2026-03-20_1127_508b792_feat.md` diff --git a/changelogs/2026-03/2026-03-20_hotel_assignment_upgrade.md b/changelogs/2026-03/2026-03-20_hotel_assignment_upgrade.md deleted file mode 100644 index 30cc60c..0000000 --- a/changelogs/2026-03/2026-03-20_hotel_assignment_upgrade.md +++ /dev/null @@ -1,176 +0,0 @@ -# 配房接口升级 — 按天粒度 + 房型升级差价自动计算 - -> 日期：2026-03-20 | 涉及服务：hl-order-service、hl-resource-service - -## 功能说明 - -配房接口从「按家庭+日期区间」改为「按天按家庭」粒度，每天可填备注。同时新增**房型升级差价自动计算**：如果配房时选的房型与产品默认不同（CORE产品默认标间），系统自动算出差价，临时加到尾款中，等定制师确认后正式生效。 - ---- - -## 接口变更清单 - -### 1. 分配酒店信息（**破坏性变更**） - -``` -PUT /admin/order/{orderId}/hotel-assignment -``` - -**请求体变更**：assignments 数组结构改为按天粒度 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| assignments | Array | 是 | 酒店分配列表（按天按家庭，每天每个家庭一条） | -| assignments[].familyIndex | Integer | 是 | 家庭序号 | -| assignments[].hotelId | Long | **是（新增）** | 酒店ID | -| assignments[].hotelName | String | 是 | 酒店名称 | -| assignments[].roomTypeId | Long | **是（新增）** | 房型ID | -| assignments[].roomType | String | 是 | 房型名称 | -| assignments[].date | String | **是（新增，替代 checkInDate/checkOutDate）** | 单天日期，格式 `yyyy-MM-dd` | -| assignments[].remark | String | 否（新增） | 当天备注 | -| assignments[].upgradePrice | BigDecimal | 否（新增） | 手动覆盖升级差价（null=使用系统计算值） | - -**删除的字段**：`checkInDate`、`checkOutDate` - -**示例请求**： -```json -{ - "assignments": [ - { - "familyIndex": 1, - "hotelId": 1001, - "hotelName": "呼伦贝尔大酒店", - "roomTypeId": 2001, - "roomType": "豪华大床房", - "date": "2026-04-01", - "remark": "需要加床" - }, - { - "familyIndex": 1, - "hotelId": 1001, - "hotelName": "呼伦贝尔大酒店", - "roomTypeId": 2001, - "roomType": "豪华大床房", - "date": "2026-04-02", - "remark": "" - }, - { - "familyIndex": 2, - "hotelId": 1001, - "hotelName": "呼伦贝尔大酒店", - "roomTypeId": 2002, - "roomType": "标间", - "date": "2026-04-01", - "remark": "" - } - ] -} -``` - -**房型升级逻辑（自动触发）**： -- 如果分配的 roomTypeId 与产品快照中该天默认房型不同 → 自动计算差价 -- CORE产品（快照中 roomTypeId 为 null）→ 默认基准为该酒店的标间（STANDARD） -- 差价 = 新房型日价格 - 默认房型日价格（来自价格日历） -- `upgradePrice` 可手动覆盖系统计算的差价 -- **定制师操作**：差价自动确认，直接调整订单总售价 -- **其他角色操作**：差价设为「待确认」临时加到尾款，通知定制师确认 - -**响应**：无变化，`Result` - ---- - -### 2. 配房升级差价预览（**新增接口**） - -``` -POST /admin/order/{orderId}/hotel-assignment/preview -``` - -**说明**：预览配房的房型升级差价（不创建任何记录），前端可在用户提交配房前展示差价信息。 - -**请求体**：同分配酒店信息接口 - -**响应**：`Result` - -| 字段 | 类型 | 说明 | -|------|------|------| -| details | Array | 各天差价明细（仅有差价的天） | -| details[].familyIndex | Integer | 家庭序号 | -| details[].date | String | 日期 | -| details[].defaultRoomTypeId | Long | 产品默认房型ID | -| details[].defaultRoomTypeName | String | 产品默认房型名称 | -| details[].assignedRoomTypeId | Long | 实际分配房型ID | -| details[].assignedRoomTypeName | String | 实际分配房型名称 | -| details[].defaultPrice | BigDecimal | 默认房型当天单价 | -| details[].assignedPrice | BigDecimal | 实际房型当天单价 | -| details[].dayDiff | BigDecimal | 当天差价（正=补款，负=退款） | -| details[].direction | String | UPGRADE / DOWNGRADE / SAME | -| details[].remark | String | 备注 | -| totalDiff | BigDecimal | 差价合计 | -| direction | String | UPGRADE / DOWNGRADE / SAME / MIXED | -| description | String | 差价描述 | - -**示例响应**： -```json -{ - "code": 200, - "data": { - "details": [ - { - "familyIndex": 1, - "date": "2026-04-01", - "defaultRoomTypeId": 2002, - "defaultRoomTypeName": "标间", - "assignedRoomTypeId": 2001, - "assignedRoomTypeName": "豪华大床房", - "defaultPrice": 300.00, - "assignedPrice": 500.00, - "dayDiff": 200.00, - "direction": "UPGRADE", - "remark": "需要加床" - } - ], - "totalDiff": 200.00, - "direction": "UPGRADE", - "description": "共 1 天有差价，合计 +200.00" - } -} -``` - ---- - -### 3. 尾款调整汇总（**字段增强**） - -``` -GET /admin/order/{orderId}/itinerary/balance-summary -``` - -**响应新增字段**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| confirmedAdjustment | BigDecimal | **新增** — 已确认的调整金额（已计入总售价） | -| pendingAdjustment | BigDecimal | **新增** — 待确认的调整金额（临时，待定制师确认） | -| totalAdjustment | BigDecimal | 合计（已确认 + 待确认） | -| details[].confirmStatus | String | **新增** — `CONFIRMED` 或 `PENDING_CONFIRM` | - ---- - -## 页面影响 - -### 配房页面 -1. **数据结构改造**：从日期区间改为按天列表，每天一条记录 -2. **新增字段**：每天增加备注输入框（remark） -3. **房型选择联动**：选择房型后，调用 preview 接口展示差价 -4. **差价展示**：如果有差价，在提交前展示差价明细和合计，支持手动修改 upgradePrice -5. **提交**：PUT hotel-assignment 时传入完整按天列表 - -### 订单详情页 — 尾款区域 -1. 展示「已确认调整」和「待确认调整（临时）」两个金额 -2. 待确认项标记为临时状态，提示「待定制师确认」 - -### 推荐交互流程 -``` -选择酒店+房型 → 填写每天备注 → 点击「预览差价」 - → 展示差价明细（可修改 upgradePrice） - → 点击「确认配房」→ 调用 PUT hotel-assignment -``` diff --git a/changelogs/2026-03/2026-03-20_mp_traveler_edit_cascade.md b/changelogs/2026-03/2026-03-20_mp_traveler_edit_cascade.md deleted file mode 100644 index ff507a7..0000000 --- a/changelogs/2026-03/2026-03-20_mp_traveler_edit_cascade.md +++ /dev/null @@ -1,51 +0,0 @@ -# 接口变更记录 — 2026-03-20（小程序出行人修改级联处理） - -> **类型** feature - ---- - -## 功能说明 - -小程序端用户可以在**行程开始前**随时修改出行人信息。修改后系统自动执行以下流程： - -1. **退保** — 作废已购买的保险单 -2. **作废合同** — 作废已签署/已创建的合同 -3. **重置待办** — INSURANCE、CONTRACT 待办回到待处理 -4. **流程状态回退** — processStatus 回退到 `PENDING_INSURANCE` -5. **自动重新投保+签约** — 如果订单已付款，系统自动用新出行人信息重新投保和签约 - -## 使用的接口（无变更） - -### `PUT` /mp/order/{orderId}/edit — 小程序编辑订单 - -请求参数不变： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `departureDate` | String(日期) | 出发日期（可选） | -| `travelers` | Array | 出行人列表（可选，传则全量替换） | - -出行人对象： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `name` | String | 是 | 姓名 | -| `idCardType` | String | 是 | 证件类型：`ID_CARD`/`PASSPORT`/`OTHER` | -| `idCardNo` | String | 是 | 证件号 | -| `phone` | String | 否 | 手机号 | -| `gender` | Integer | 否 | 性别：1=男，2=女 | -| `birthday` | String(日期) | 否 | 出生日期 | -| `travelerType` | String | 否 | 类型：`ADULT`/`CHILD`/`BABY` | -| `nationality` | String | 否 | 国籍（默认中国） | -| `emergencyContact` | String | 否 | 紧急联系人 | -| `emergencyPhone` | String | 否 | 紧急联系人电话 | - -## 前端注意事项 - -| 项目 | 说明 | -|------|------| -| **可编辑状态** | 待支付、已付定金、已全额支付、已确认、待付尾款、待出行 | -| **不可编辑状态** | 旅行中、已完成、已取消、退款中、已退款 | -| **修改后的提示** | 修改出行人后，如果订单已付款，告知用户"系统正在重新处理保险和合同" | -| **全量替换** | 传 `travelers` 时是全量替换，请传所有出行人（不是增量修改） | -| **自动重新处理** | 后端自动退保→重新投保、作废合同→重新签约，前端无需额外调用 | diff --git a/changelogs/2026-03/2026-03-20_notification_template_fix.md b/changelogs/2026-03/2026-03-20_notification_template_fix.md deleted file mode 100644 index 8dd9d06..0000000 --- a/changelogs/2026-03/2026-03-20_notification_template_fix.md +++ /dev/null @@ -1,83 +0,0 @@ -# 通知模板修正 + 订单详情字段补全 - -> **类型**: fix -> **日期**: 2026-03-20 -> **涉及服务**: hl-order-service、hl-mp-service -> **后端状态**: ✅ 已完成并部署 - ---- - -## 一、小程序订单详情接口新增字段 - -### GET `/mp/order/{orderId}` 订单详情 - -响应新增以下字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| surchargeAmount | BigDecimal | 费用增加总额（如升级房型补差价） | -| surcharges | List | 费用增加项列表（同优惠项 discounts 结构对称） | -| displayStatus | String | 展示状态（前端主要使用此字段展示订单状态） | -| displayStatusLabel | String | 展示状态中文标签 | -| transportSegments | List | 交通段列表（大交通信息） | -| sharerOpenid | String | 分享者openid | - -### displayStatus 枚举值 - -| 值 | 标签 | 说明 | -|----|------|------| -| PENDING_PAY | 待支付 | 订单创建未支付 | -| DEPOSIT_PAID | 已付定金 | 定金已支付 | -| PAID | 已支付 | 全款已支付 | -| CONFIRMED | 已确认 | 订单已确认 | -| PENDING_BALANCE | 待付尾款 | 等待用户支付尾款 | -| PENDING_DEPARTURE | 待出发 | 内部流程完成，等待出发 | -| TRAVELLING | 出行中 | 行程进行中 | -| COMPLETED | 已完成 | 行程结束 | -| CANCELLED | 已取消 | 订单已取消 | -| REFUNDING | 退款中 | 退款处理中 | -| REFUNDED | 已退款 | 退款完成 | - -### surcharges 列表项结构 - -| 字段 | 类型 | 说明 | -|------|------|------| -| surchargeId | String | 费用增加项ID | -| orderId | String | 订单ID | -| surchargeName | String | 费用增加项名称（如"升级房型补差价"） | -| surchargeAmount | BigDecimal | 金额 | -| createTime | DateTime | 创建时间 | - -### 前端使用建议 - -- **订单状态展示**：优先使用 `displayStatus` + `displayStatusLabel`，而非 `status` -- **金额汇总区域**：新增"费用增加"行 - ``` - 总价: ¥3000.00 - 优惠: -¥100.00 - 增加: +¥200.00 ← 新增（surchargeAmount > 0 时显示） - 定金: ¥1000.00 - 尾款: ¥2100.00 - ``` -- **费用增加项列表**：在优惠项列表下方展示 surcharges 列表 - ---- - -## 二、通知消息内容修正 - -所有通知模板（站内信/短信/订阅消息/公众号）内容已优化，**前端无需改动**，后端自动生效。 - -以下是修正的内容汇总（仅供参考，前端不需要处理模板内容）： - -| 事件 | 修正前问题 | 修正后 | -|------|-----------|--------| -| 定金支付成功 | 缺出发日期 | 补充出发日期 + 尾款提示 | -| 全款支付成功 | 缺出发日期 | 补充出发日期 | -| 订单已取消 | 变量名不匹配，reason显示为空 | 修正变量名，正确显示取消原因 | -| 退款已申请 | 缺退款金额 | 补充退款金额 | -| 退款被驳回 | 变量名不匹配，原因显示为空 | 修正变量名，正确显示驳回原因 | -| 行程已修改 | 变量名不匹配 | 修正变量名 | -| 房型/车型已变更 | 变量名不匹配 | 修正变量名 | -| 修改已确认 | 模板内容为空 | 补全模板 | -| 级联失效通知 | 变量名不匹配 | 修正变量名 | -| 所有金额 | 缺 ¥ 符号 | 统一加 ¥ 前缀 | diff --git a/changelogs/2026-03/2026-03-20_order_auto_insurance_contract.md b/changelogs/2026-03/2026-03-20_order_auto_insurance_contract.md deleted file mode 100644 index d4d3ad1..0000000 --- a/changelogs/2026-03/2026-03-20_order_auto_insurance_contract.md +++ /dev/null @@ -1,247 +0,0 @@ -# 订单自动化：产品绑定保险方案+合同配置，支付后自动投保+签约 - -> 日期：2026-03-20 | 涉及服务：hl-product-service、hl-order-service、hl-insurance-service、hl-contract-service - -## 功能说明 - -### 核心变更 - -1. **产品新增保险+合同配置字段（必填）**：创建/编辑产品时必须绑定保险方案和合同配置 -2. **订单支付后自动投保+签约**：出行人补全后系统自动完成保险和合同，无需管理员手动操作 -3. **去掉"待确认订单"步骤**：原6步待办缩减为5步，CONFIRM_ORDER 不再存在 -4. **保险手动配置支持按天配置或直接选方案**：管理员可手动按天投保（purchase 接口），也可直接选方案自动投保 - -### 新的订单内部流程 - -``` -支付成功 → 创建5个待办 → 出行人补全 → 系统自动确认订单 - → 自动投保（按产品绑定的保险方案） ← INSURANCE待办自动完成 - → 自动签约（按产品绑定的合同配置） ← CONTRACT待办等签署回调完成 - → 手动配房 (ARRANGE_ROOM) - → 手动配车 (ARRANGE_VEHICLE) - → 手动确认清单 (CONFIRM_CHECKLIST) -``` - -**容错**：自动投保/签约失败时，待办保持 PENDING，管理员可手动处理。管理员也可手动退保/作废合同后重新操作。 - ---- - -## 接口变更清单 - -### 一、产品服务 - -#### 1. 创建产品（新增必填字段） - -``` -POST /admin/product -``` - -**新增请求字段**（所有字段必填，supplementaryClause 除外）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| insuranceSchemeId | Long | 是 | 保险方案ID，从保险方案列表获取 | -| contractPlatform | String | 是 | 合同平台：`12301`（全国旅游监管平台）/ `FADADA`（法大大） | -| contractTemplateCode | String | 是 | 合同模板编码，从合同模板列表获取 | -| contractMode | String | 是 | 签约模式：`STANDARD`（电子签约）/ `SYNC`（线下报备） | -| signatoryMode | Integer | 是 | 签署模式：`1`=短信 / `2`=现场 / `3`=线下 | -| agencyCode | String | 是 | 旅行社编码，从保险投保主体列表获取 | -| disputeResolution | Integer | 是 | 争议解决方式：`1`=仲裁 / `2`=诉讼 | -| supplementaryClause | String | 否 | 合同补充条款 | -| transactorName | String | 是 | 经办人姓名 | -| transactorPhone | String | 是 | 经办人电话 | - -#### 2. 编辑产品（新增可选字段） - -``` -PUT /admin/product/{productId} -``` - -同上 10 个字段，全部可选（不传则不更新）。 - -#### 3. 统一保存产品（新增字段） - -``` -POST /admin/product/save -``` - -同上 10 个字段，创建时必填，更新时可选。 - ---- - -### 二、保险服务 - -#### 已有接口（手动配置保险） - -**方式一：按天手动投保**（purchase 接口，按具体的计划+日期段投保） - -``` -POST /admin/insurance/purchase -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 否 | 关联的旅行订单ID | -| planId | Long | 是 | 保险计划ID（从产品计划列表获取） | -| startDate | String | 是 | 保障开始日期 yyyy-MM-dd | -| endDate | String | 是 | 保障结束日期 yyyy-MM-dd | -| insuredPersons | Array | 是 | 被保人列表（至少1人） | -| insuredPersons[].name | String | 是 | 姓名 | -| insuredPersons[].idCardType | String | 否 | 证件类型：`ID_CARD`/`PASSPORT`/`OTHER`，默认ID_CARD | -| insuredPersons[].idCardNo | String | 是 | 证件号 | -| insuredPersons[].birthday | String | 是 | 出生日期 yyyy-MM-dd | -| insuredPersons[].gender | String | 是 | 性别：`MALE`/`FEMALE` | -| entityCode | String | 否 | 投保公司编码，默认使用系统默认主体 | - -**方式二：选择保险方案投保**（preview → 确认 → 自动按段投保） - -步骤1：预览方案 - -``` -POST /admin/insurance/scheme/preview-apply -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| schemeId | Long | 是 | 保险方案ID | -| orderId | Long | 是 | 订单ID（自动获取出行日期和人数） | - -返回各段的日期范围、计划信息、单人保费、总保费、日期间隙警告。 - -步骤2：确认后逐段调用 purchase 接口（参考方式一） - -**保险方案列表**（产品编辑页下拉使用）： - -``` -GET /admin/insurance/scheme/list -``` - -返回所有启用的保险方案列表（schemeId + name + description + isOverseas + 段列表）。 - -**保险产品/计划列表**（按天手动投保时使用）： - -``` -GET /admin/insurance/products?isOverseas=false -GET /admin/insurance/products/{productId}/plans -``` - -**保费试算**： - -``` -POST /admin/insurance/trial-price -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| planId | Long | 是 | 保险计划ID | -| startDate | String | 是 | yyyy-MM-dd | -| endDate | String | 是 | yyyy-MM-dd | -| insuredCount | Integer | 是 | 被保人数 | - ---- - -### 三、合同服务 - -**合同模板列表**（产品编辑页下拉使用）： - -``` -GET /admin/contract/templates -``` - -返回可用的合同模板列表（templateCode + templateName + platform + mode）。 - -**投保主体/旅行社列表**（产品编辑页下拉使用）： - -``` -GET /admin/insurance/entities -``` - -返回投保公司主体列表（code + companyName）。agencyCode 使用此列表中的 code 值。 - ---- - -### 四、订单服务 - -#### 待办定义变更（**破坏性变更**） - -| 原 todoType | 原序号 | 新 todoType | 新序号 | 说明 | -|-------------|--------|-------------|--------|------| -| CONFIRM_ORDER | 1 | **已删除** | - | 不再需要手动确认 | -| INSURANCE | 2 | INSURANCE | 1 | 自动完成（系统投保成功后） | -| CONTRACT | 3 | CONTRACT | 2 | 自动完成（合同签署回调后） | -| ARRANGE_ROOM | 4 | ARRANGE_ROOM | 3 | 手动 | -| ARRANGE_VEHICLE | 5 | ARRANGE_VEHICLE | 4 | 手动 | -| CONFIRM_CHECKLIST | 6 | CONFIRM_CHECKLIST | 5 | 手动 | - -#### processStatus 变更 - -| 原流程 | 新流程 | -|--------|--------| -| PENDING_INFO → **PROCESSING** → PENDING_INSURANCE → ... | PENDING_INFO → PENDING_INSURANCE → ... | - -`PROCESSING` 状态已删除，`PENDING_INFO` 直接跳到 `PENDING_INSURANCE`。 - -#### 前端需要注意 - -1. **待办列表不再有 CONFIRM_ORDER 类型**：前端不要 hardcode "CONFIRM_ORDER" 的判断 -2. **工作台待办序号变化**：INSURANCE 现在是 seq=1（原来是2），以此类推 -3. **processStatus 没有 PROCESSING 了**：相关状态标签/过滤条件需要去掉 -4. **INSURANCE/CONTRACT 待办可能被系统自动完成**：前端展示时注意区分系统完成和手动完成 - ---- - -## 页面布局建议 - -### 产品编辑页 — 新增"保险与合同配置"区域 - -建议放在产品基本信息之后，行程安排之前： - -``` -┌─────────────────────────────────────────┐ -│ 保险与合同配置 │ -├─────────────────────────────────────────┤ -│ 保险方案：[下拉选择] ← GET /admin/insurance/scheme/list │ -│ │ -│ 合同平台：[12301 ▼] / [法大大 ▼] │ -│ 合同模板：[下拉选择] ← GET /admin/contract/templates │ -│ 签约模式：[电子签约 ▼] / [线下报备 ▼] │ -│ 签署模式：[短信 ▼] / [现场 ▼] / [线下 ▼] │ -│ 旅行社： [下拉选择] ← GET /admin/insurance/entities │ -│ 争议解决：[仲裁 ▼] / [诉讼 ▼] │ -│ 经办人姓名：[________] │ -│ 经办人电话：[________] │ -│ 补充条款：[________________] (可选) │ -└─────────────────────────────────────────┘ -``` - -### 订单详情页 — 保险手动操作 - -管理员手动配保险时有两种方式： - -``` -┌─────────────────────────────────────────┐ -│ 保险配置 │ -├─────────────────────────────────────────┤ -│ ● 选择保险方案（推荐） │ -│ [方案下拉] → 预览 → 确认投保 │ -│ │ -│ ○ 按天手动配置 │ -│ 保险产品：[下拉] │ -│ 保险计划：[下拉] │ -│ 开始日期：[____] 结束日期：[____] │ -│ [试算保费] [确认投保] │ -└─────────────────────────────────────────┘ -``` - ---- - -## 枚举/字典值 - -| 字段 | 可选值 | 说明 | -|------|--------|------| -| contractPlatform | `12301` / `FADADA` | 合同平台 | -| contractMode | `STANDARD` / `SYNC` | 签约模式 | -| signatoryMode | `1` / `2` / `3` | 1=短信签署, 2=现场签署, 3=线下签署 | -| disputeResolution | `1` / `2` | 1=仲裁, 2=诉讼 | -| todoType | `INSURANCE` / `CONTRACT` / `ARRANGE_ROOM` / `ARRANGE_VEHICLE` / `CONFIRM_CHECKLIST` | 待办类型（CONFIRM_ORDER 已删除） | -| processStatus | `PENDING_INFO` / `PENDING_INSURANCE` / `PENDING_CONTRACT` / `PENDING_ROOM` / `PENDING_VEHICLE` / `PENDING_FINANCE` / `READY` / `INTERNAL_CONFIRMED` | 内部流程状态（PROCESSING 已删除） | diff --git a/changelogs/2026-03/2026-03-20_order_surcharge.md b/changelogs/2026-03/2026-03-20_order_surcharge.md deleted file mode 100644 index 9df00da..0000000 --- a/changelogs/2026-03/2026-03-20_order_surcharge.md +++ /dev/null @@ -1,145 +0,0 @@ -# 订单费用增加项（surcharge） - -## 功能说明 - -新增"费用增加项"功能，与现有"优惠项"（discount）对称： -- **优惠项**：减少尾款（-¥） -- **费用增加项**：增加尾款（+¥），如升级房型补差价、加座费等 - -### 权限限制 -- **优惠项**：任意管理员可操作 -- **费用增加项**：仅该订单的**定制师本人**或**超级管理员(SUPER_ADMIN)**可操作 - -### 金额计算变更（破坏性变更） -- **尾款** = 总价 - 定金 - 优惠总额 + **费用增加总额** -- **全款** = 总价 - 优惠总额 + **费用增加总额** - ---- - -## 接口清单 - -### 添加费用增加项 -- **POST** `/admin/order/{orderId}/surcharge` -- **权限**：定制师本人 或 SUPER_ADMIN -- **请求体**：`SurchargeRequest` -- **响应**：`Result` - -### 修改费用增加项 -- **PUT** `/admin/order/{orderId}/surcharge/{surchargeId}` -- **权限**：定制师本人 或 SUPER_ADMIN -- **请求体**：`SurchargeRequest` -- **响应**：`Result` - -### 删除费用增加项 -- **DELETE** `/admin/order/{orderId}/surcharge/{surchargeId}` -- **权限**：定制师本人 或 SUPER_ADMIN -- **响应**：`Result` - ---- - -## SurchargeRequest 参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| surchargeName | String | 是 | 费用增加项名称，如"升级房型补差价" | -| surchargeAmount | BigDecimal | 是 | 费用增加金额，必须大于0 | - -## OrderSurcharge 响应 - -| 字段 | 类型 | 说明 | -|------|------|------| -| surchargeId | String | 费用增加项ID | -| orderId | String | 订单ID | -| surchargeName | String | 费用增加项名称 | -| surchargeAmount | BigDecimal | 费用增加金额 | -| createTime | DateTime | 创建时间 | - ---- - -## 订单详情/列表接口变更 - -### OrderDetailVO 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| surchargeAmount | BigDecimal | 费用增加总额（缓存汇总值） | -| surcharges | List\ | 费用增加项列表 | - -### OrderListVO 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| surchargeAmount | BigDecimal | 费用增加总额 | - -### balanceAmount 计算变更 - -原来：`balanceAmount = totalPrice - depositAmount - discountAmount` -现在：`balanceAmount = totalPrice - depositAmount - discountAmount + surchargeAmount` - ---- - -## 页面布局建议 - -### 订单详情页 — 费用区域 - -在现有"优惠项"区域下方新增"费用增加项"区域： - -``` -优惠项 - ├ 会员折扣 -¥100.00 [编辑] [删除] ← 任意管理员可操作 - └ [+ 添加优惠项] - -费用增加项 - ├ 升级房型补差价 +¥200.00 [编辑] [删除] ← 仅定制师/超管可操作 - └ [+ 添加费用增加项] ← 仅定制师/超管可见 - -金额汇总 - 总价: ¥3000.00 - 优惠: -¥100.00 - 增加: +¥200.00 - 定金: ¥1000.00 - 尾款: ¥2100.00 (3000 - 1000 - 100 + 200) -``` - -### 权限判断 - -前端需要根据当前登录用户判断是否显示"添加/编辑/删除"费用增加项的按钮： -- 当前用户 `roleKey === 'SUPER_ADMIN'` → 显示 -- 当前用户 `adminId === order.customizerId` → 显示 -- 其他情况 → 隐藏按钮 - ---- - -## 调用示例 - -### 添加费用增加项 -```json -POST /admin/order/1234567890/surcharge -{ - "surchargeName": "升级房型补差价", - "surchargeAmount": 200.00 -} -``` - -### 修改费用增加项 -```json -PUT /admin/order/1234567890/surcharge/9876543210 -{ - "surchargeName": "升级豪华房型补差价", - "surchargeAmount": 300.00 -} -``` - -### 删除费用增加项 -``` -DELETE /admin/order/1234567890/surcharge/9876543210 -``` - -### 错误响应示例（权限不足） -```json -{ - "code": 500, - "message": "仅超级管理员或该订单的定制师可操作费用增加项", - "data": null -} -``` diff --git a/changelogs/2026-03/2026-03-20_pricing_cleanup.md b/changelogs/2026-03/2026-03-20_pricing_cleanup.md deleted file mode 100644 index 94e96dc..0000000 --- a/changelogs/2026-03/2026-03-20_pricing_cleanup.md +++ /dev/null @@ -1,165 +0,0 @@ -# 接口变更记录 — 2026-03-20（定价字段精简 + 保险校验） - -> **类型** refactor + feature -> -> 定价配置精简（移除6个冗余字段）+ 保险方案天数校验 + 保险费自动回填 - ---- - -## 一、定价配置字段精简 - -### 1. 移除 `maxGroupSize`（最多成团人数） - -**原因**：业务上只需要"成团人数"一个概念，不需要区分最少/最多。 - -**前端需要调整**： -- 定价规则页面：移除"最多成团"输入框，只保留"成团人数"（字段 `minGroupSize`） -- `minGroupSize` 语义变为"成团人数"，不再是"最少成团" - -| 字段 | 变更 | 说明 | -|------|------|------| -| ~~`maxGroupSize`~~ | **已移除** | 请求和响应都不再有此字段 | -| `minGroupSize` | **含义变更** | 现在代表"成团人数"（原为"最少成团人数"） | - -### 2. 移除4个未使用的价格体系字段 - -**原因**：这4个字段从未参与任何价格计算逻辑，只是存储和展示，属于冗余数据。 - -| 移除的字段 | 原含义 | 说明 | -|-----------|--------|------| -| ~~`singleRoomDiff`~~ | 单房差 | **已移除** | -| ~~`adultExtraBed`~~ | 成人加床 | **已移除** | -| ~~`childNoBed`~~ | 儿童不占床 | **已移除** | -| ~~`companionPrice`~~ | 陪同价 | **已移除** | - -**保留的价格字段**（实际参与计算）： - -| 字段 | 含义 | 说明 | -|------|------|------| -| `childWithBed` | 儿童占床价 | 保留，参与儿童价计算 | -| `childDiscountPercent` | 儿童折扣百分比 | 保留，参与儿童价计算 | -| `babyPrice` | 婴儿价 | 保留，参与婴儿价计算 | -| `insuranceFee` | 保险费 | 保留，参与成本计算 | -| `mealBudget` | 餐费预算 | 保留 | -| `extraCostPerPerson` | 每人额外成本 | 保留 | - -### 受影响的接口 - -#### `POST` /admin/product/item/{productId}/pricing — 保存定价规则 - -**请求参数变更**： - -| 字段 | 变更 | -|------|------| -| ~~`maxGroupSize`~~ | **已移除** | -| ~~`singleRoomDiff`~~ | **已移除** | -| ~~`adultExtraBed`~~ | **已移除** | -| ~~`childNoBed`~~ | **已移除** | -| ~~`companionPrice`~~ | **已移除** | - -#### `GET` /admin/product/item/{productId}/pricing — 获取定价规则 - -**响应变更**：同上5个字段从响应中移除。 - -#### 小程序端 — 定制产品详情 - -`MpCustomProductDetailVO.PricingItem` 同步移除以上5个字段。 - ---- - -## 二、保险方案天数校验 - -### 功能说明 - -产品选择保险方案时，系统会校验保险方案的**适用行程天数**是否与产品**行程天数**一致。不一致时拒绝保存。 - -### 保险方案列表新增字段 - -#### `GET` /admin/insurance/scheme — 保险方案列表 - -响应新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `totalDays` | Integer | 适用行程天数（根据保障段自动计算） | - -### 产品保存时校验逻辑 - -- 创建/编辑产品时，如果设置了 `insuranceSchemeId`，系统自动调用保险服务校验 -- 如果保险方案的 `totalDays` 与产品行程天数不匹配，返回错误提示：`保险方案「{方案名}」适用{N}天行程，但本产品行程为{M}天，请选择匹配的方案` - ---- - -## 三、保险费自动回填 - -### 功能说明 - -产品选择保险方案后，系统自动计算每人保险费并回填到定价配置的 `insuranceFee` 字段。 - -### 新增接口：保险费预览 - -#### `GET` /admin/product/item/{productId}/pricing/insurance-fee-preview - -**用途**：前端选择保险方案时实时预览保险费，不保存。 - -**请求参数**： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `schemeId` | Long | 是 | 保险方案ID | - -**响应**：`Result` - -```json -{ - "code": 200, - "data": { - "schemeId": "1234567890", - "schemeName": "测试3日方案", - "totalDays": 3, - "tripDays": 3, - "perPersonPremium": 45.00 - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `schemeId` | String | 保险方案ID | -| `schemeName` | String | 方案名称 | -| `totalDays` | Integer | 方案适用天数 | -| `tripDays` | Integer | 产品行程天数 | -| `perPersonPremium` | BigDecimal | 每人保险费（元） | - -**错误场景**： -- 产品不存在 → 404 -- 保险服务不可用 → 500（"保险服务暂不可用"） -- 天数不匹配 → 400（提示不匹配原因） - -### 自动回填逻辑 - -产品保存（创建/编辑）时： -1. 如果设置了 `insuranceSchemeId`，自动调用保险服务获取每人保险费 -2. 校验天数匹配（不匹配则报错） -3. 自动将 `perPersonPremium` 写入 `ProductPricing.insuranceFee` -4. 前端定价页面的"保险费"字段会自动更新为计算值（仍可手动修改） - ---- - -## 数据库变更 - -```sql --- 1. 移除 maxGroupSize -ALTER TABLE product_pricing DROP COLUMN max_group_size; - --- 2. 保险方案新增 totalDays -ALTER TABLE insurance_scheme ADD COLUMN total_days INT DEFAULT NULL COMMENT '适用行程天数'; - --- 3. 移除4个未使用的定价字段 -ALTER TABLE product_pricing DROP COLUMN single_room_diff; -ALTER TABLE product_pricing DROP COLUMN adult_extra_bed; -ALTER TABLE product_pricing DROP COLUMN child_no_bed; -ALTER TABLE product_pricing DROP COLUMN companion_price; -``` - -已在本地和测试环境执行完毕。 diff --git a/changelogs/2026-03/2026-03-20_remove_pricing_mode.md b/changelogs/2026-03/2026-03-20_remove_pricing_mode.md deleted file mode 100644 index afe52aa..0000000 --- a/changelogs/2026-03/2026-03-20_remove_pricing_mode.md +++ /dev/null @@ -1,57 +0,0 @@ -# 接口变更记录 — 2026-03-20 - -> **提交** `f59d78d` · **类型** refactor -> -> refactor: 移除定价模式(pricingMode)字段，价格统一在价格日历中设置 - -## 变更说明 - -**定价规则接口**中移除了 `pricingMode` 字段（原值 AUTO/MANUAL/CUSTOM）。 - -**原因**：`pricingMode` 是冗余字段，业务逻辑实际由价格日历中的 `costAutoCalc`（逐日控制自动/手动计算）和产品类型 `productType` 控制，`pricingMode` 从未参与任何业务判断。 - -## 前端需要调整 - -### 定价规则页面（产品编辑 → 定价规则） - -| 操作 | 说明 | -|------|------| -| **移除** "定价模式" 选择器 | 原来的 AUTO/手动定价/自定义 三选一控件，**直接删除** | -| **保留** 利润模式 | FIXED（固定金额）/ PERCENT（百分比加价），不变 | -| **保留** 其他所有字段 | 成团人数、价格体系（单房差、儿童价等）、支付方式，不变 | - -### 接口变更 - -#### `POST` /admin/product/item/{productId}/pricing — 保存定价规则 - -**请求参数变更**： - -| 字段 | 变更 | 说明 | -|------|------|------| -| ~~`pricingMode`~~ | **已移除** | 不再需要传此字段 | -| `profitMode` | 不变 | FIXED/PERCENT | -| 其他字段 | 不变 | — | - -#### `GET` /admin/product/item/{productId}/pricing — 获取定价规则 - -**响应变更**： - -| 字段 | 变更 | 说明 | -|------|------|------| -| ~~`pricingMode`~~ | **已移除** | 响应中不再返回此字段 | - -### 价格设置方式（无变化） - -价格统一在**价格日历**中设置，支持两种方式： -1. **自动测算**：点击"测算预览"或"自动计算成本"按钮，系统根据行程资源价格+利润参数自动算出成本和售价 -2. **手动填写**：直接在日历中手动输入每日的成人售价/成本价、儿童售价/成本价 - -每个日期的 `costAutoCalc` 标志控制该日期是自动还是手动，与原来的逻辑完全一致。 - -## 数据库变更 - -```sql -ALTER TABLE product_pricing DROP COLUMN pricing_mode; -``` - -已在本地和测试环境执行完毕。 diff --git a/changelogs/2026-03/2026-03-20_todo_display_fix.md b/changelogs/2026-03/2026-03-20_todo_display_fix.md deleted file mode 100644 index 8819820..0000000 --- a/changelogs/2026-03/2026-03-20_todo_display_fix.md +++ /dev/null @@ -1,46 +0,0 @@ -# 待办事项显示修正：使用 todoLabel 而非 todoType - -> **类型**: fix -> **日期**: 2026-03-20 -> **涉及页面**: 管理端 - 订单详情页 - 待办事项区域 - ---- - -## 问题 - -待办事项区域显示了英文编码（如 `INSURANCE`、`CONTRACT`、`ARRANGE_ROOM`），应该显示中文标签。 - -## 原因 - -前端使用了 `todoType` 字段（英文编码）来展示，应该使用 `todoLabel` 字段（中文标签）。 - -## 修正方式 - -订单详情接口 `todos` 数组中每个待办对象包含以下字段： - -| 字段 | 类型 | 用途 | 示例 | -|------|------|------|------| -| todoType | String | 编码（用于逻辑判断，**不要用于显示**） | `INSURANCE` | -| todoLabel | String | 中文标签（**用于页面展示**） | `待配置保险` | -| status | String | 状态编码 | `PENDING` / `COMPLETED` | -| sequence | Integer | 排序序号 | 1, 2, 3, 4, 5 | - -### todoType → todoLabel 对照表 - -| todoType | todoLabel | -|----------|-----------| -| INSURANCE | 待配置保险 | -| CONTRACT | 待签订合同 | -| ARRANGE_ROOM | 待安排住宿 | -| ARRANGE_VEHICLE | 待安排车辆 | -| CONFIRM_CHECKLIST | 待确认清单 | -| PROCESS_REFUND | 紧急：需退款处理 | - -### 前端改动 - -将待办事项显示的字段从 `todo.todoType` 改为 `todo.todoLabel`： - -```diff -- {{ todo.todoType }} -+ {{ todo.todoLabel }} -``` diff --git a/changelogs/2026-03/2026-03-21_0909_573e671_fix.md b/changelogs/2026-03/2026-03-21_0909_573e671_fix.md deleted file mode 100644 index dcf810e..0000000 --- a/changelogs/2026-03/2026-03-21_0909_573e671_fix.md +++ /dev/null @@ -1,93 +0,0 @@ -# 接口变更记录 — 2026-03-21 09:09 - -> **提交** `573e671` · **作者** wx · **时间** 2026-03-21 09:09:39 +0800 -> -> fix: 新增管理端获取订单出行人接口 GET /admin/order/{orderId}/travelers - -## 变更总览 - -- **订单服务** - - AdminOrder (+4) - ---- - -## 订单服务 - -### AdminOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「管理端订单接口」** - -### 🆕 `GET` /admin/order/{orderId}/travelers — 获取订单出行人列表 - -> 返回指定订单的所有出行人信息，用于保险投保时自动填充被保人。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderTravelerId` | `Long` | 出行人记录ID | -| `orderId` | `Long` | 订单ID | -| `name` | `String` | 出行人姓名 | -| `idCardType` | `String` | 证件类型（字典：id_card_type） | -| `idCardNo` | `String` | 证件号码（加密存储） | -| `phone` | `String` | 手机号码（加密存储） | -| `gender` | `Integer` | 性别（字典：gender） | -| `birthday` | `LocalDate` | 出生日期 | -| `travelerType` | `String` | 出行人类型（字典：traveler_type） | -| `nationality` | `String` | 国籍 | -| `emergencyContact` | `String` | 紧急联系人姓名 | -| `emergencyPhone` | `String` | 紧急联系人电话（加密存储） | -| `email` | `String` | 邮箱地址 | -| `deletedAt` | `LocalDateTime` | 删除时间（软删除） | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 🆕 `POST` /admin/order/{orderId}/surcharge — 添加费用增加项 - -> 为订单添加费用增加项（如升级房型补差价、加座费等）。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**请求体** `SurchargeRequest` - -**响应** `Result` - -### 🆕 `PUT` /admin/order/{orderId}/surcharge/{surchargeId} — 修改费用增加项 - -> 修改已添加的费用增加项名称或金额，修改后自动重算订单尾款金额。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - - `{surchargeId}` (`Long`) — 路径参数：费用增加项ID - -**请求体** `SurchargeRequest` - -**响应** `Result` - -### 🆕 `DELETE` /admin/order/{orderId}/surcharge/{surchargeId} — 删除费用增加项 - -> 删除已添加的费用增加项，删除后自动重算订单尾款金额。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - - `{surchargeId}` (`Long`) — 路径参数：费用增加项ID - -**响应** `Result` - ---- - - -📁 全部变更文件 (点击展开) - -``` -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-21_0919_957312d_fix.md b/changelogs/2026-03/2026-03-21_0919_957312d_fix.md deleted file mode 100644 index cf46063..0000000 --- a/changelogs/2026-03/2026-03-21_0919_957312d_fix.md +++ /dev/null @@ -1,32 +0,0 @@ -# 接口变更记录 — 2026-03-21 09:19 - -> **提交** `957312d` · **作者** wx · **时间** 2026-03-21 09:19:54 +0800 -> -> fix: 产品订单逻辑优化（多角色审查） - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpProductQuoteVO - - - 🆕 `stock` (`Integer`) — 该日期剩余库存（null表示不限） - - 🆕 `available` (`Boolean`) — 该日期是否可订（库存>0或不限库存） - - -📁 全部变更文件 (点击展开) - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductQuoteVO.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-21_1705_72433fa_fix.md b/changelogs/2026-03/2026-03-21_1705_72433fa_fix.md deleted file mode 100644 index a759220..0000000 --- a/changelogs/2026-03/2026-03-21_1705_72433fa_fix.md +++ /dev/null @@ -1,45 +0,0 @@ -# 接口变更记录 — 2026-03-21 17:05 - -> **提交** `72433fa` · **作者** wx · **时间** 2026-03-21 17:05:19 +0800 -> -> fix: 自动投保部分失败时回滚已成功段,防止半覆盖 - -## 变更总览 - -- **订单服务** - - 🆕 InternalAutoProcess (+2 接口) - ---- - -## 订单服务 - -### 🆕 新增: InternalAutoProcess - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】自动化处理（运维用）」** - -### 📌 `POST` /internal/order/{orderId}/auto-process — 触发自动化处理（确认+投保+签约） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result` - -### 📌 `POST` /internal/order/{orderId}/auto-reprocess — 触发重新投保签约（跳过确认） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result` - ---- - - -📁 全部变更文件 (点击展开) - -``` -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -A hl-order-service/src/main/java/com/hulalv/order/controller/InternalAutoProcessController.java -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-21_code_quality_fixes.md b/changelogs/2026-03/2026-03-21_code_quality_fixes.md deleted file mode 100644 index abadf4f..0000000 --- a/changelogs/2026-03/2026-03-21_code_quality_fixes.md +++ /dev/null @@ -1,54 +0,0 @@ -# 代码质量修复（多模块） - -**日期**: 2026-03-21 -**服务**: hl-order-service, hl-user-service, hl-payment-service, hl-file-service, hl-contract-service, hl-mp-service, hl-product-service, hl-insurance-service -**类型**: Bug修复 + 性能优化 - ---- - -## 变更说明 - -本次修复了多模块的代码级 bug，均为后端内部逻辑优化，**不影响现有接口的请求/响应格式**。 - -### 修复清单 - -| 模块 | 修复内容 | -|------|---------| -| hl-order-service | BigDecimal.equals→compareTo 修复价格比较精度问题 | -| hl-order-service | GROUP下单报价 NPE 防护（quoteInfo.get() 空值处理） | -| hl-order-service | 订单号升级：毫秒精度+6位随机数，防碰撞 | -| hl-order-service | 自动投保/签约方案ID类型安全转换 | -| hl-order-service | GROUP下单出发日期已过校验 | -| hl-user-service | AdminAuthService 6处 NPE 防护（会话数据提取） | -| hl-payment-service | 日期查询参数格式校验（400替代500） | -| hl-file-service | 文件统计空值防护 | -| hl-contract-service | userId 类型安全转换 | -| hl-mp-service | 产品列表 GROUP 团期获取从串行改为并行（性能优化） | -| hl-product-service | 车辆绑定异常信息不泄露技术细节 | -| hl-insurance-service | 投保公司主体错误提示不泄露用户输入 | - -### 前端无需改动 - -以上修复均为后端内部逻辑，现有接口行为不变。 - ---- - -## 第二批修复（并发安全+幂等性+深层防护） - -| 模块 | 修复内容 | -|------|---------| -| hl-product-service | PriceCalendarService: new Thread() → CompletableFuture.runAsync() | -| hl-order-service | OrderExpiryJob: 分布式锁 TTL 4min → 5min（不短于任务间隔） | -| hl-order-service | OrderExpiryConsumer: 新增 Redis 幂等性检查 | -| hl-order-service | BatchDisbandConsumer: batchId 安全类型转换 | -| hl-order-service | GROUP下单 batchInfo 字段 null 防护 | -| hl-order-service | refundPolicyId 4处安全转换 | -| hl-order-service | contactPhone.substring 越界防护 | -| hl-order-service | Map.of() NPE 防护（STATUS_LABELS 查询前 null 检查） | -| hl-insurance-service | InsuranceOrderService STATUS_LABELS null 防护 | -| hl-contract-service | ContractService STATUS_LABELS null 防护 | -| 全项目 | ((Number) map.get()).xxxValue() → instanceof 检查（15处） | - -### 测试统计 - -15 模块 3598 测试全绿，0 回归。 diff --git a/changelogs/2026-03/2026-03-21_insurance_purchase_auto_fill.md b/changelogs/2026-03/2026-03-21_insurance_purchase_auto_fill.md deleted file mode 100644 index 5aa3a2f..0000000 --- a/changelogs/2026-03/2026-03-21_insurance_purchase_auto_fill.md +++ /dev/null @@ -1,97 +0,0 @@ -# 投保接口支持自动填充（orderId） - -**日期**: 2026-03-21 -**服务**: hl-insurance-service -**类型**: 功能增强 - ---- - -## 功能说明 - -`POST /admin/insurance/purchase` 投保接口现在支持传 `orderId` 自动从订单获取出行人和行程日期，无需手动填写 `startDate`、`endDate`、`insuredPersons`。 - -**之前**：必须手动传 planId + startDate + endDate + insuredPersons（完整被保人列表） -**现在**：只需传 planId + orderId，其余自动从订单获取 - ---- - -## 接口清单 - -| 方法 | 路径 | 说明 | 变更 | -|------|------|------|------| -| POST | /admin/insurance/purchase | 投保下单 | `startDate`/`endDate`/`insuredPersons` 变为可选 | - ---- - -## 详细定义 - -### POST /admin/insurance/purchase - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 否 | 关联旅行订单ID。**传了则自动从订单获取出行人和日期** | -| planId | Long | **是** | 保险计划ID | -| startDate | LocalDate | 否 | 保障开始日期。传orderId时自动取订单出发日期 | -| endDate | LocalDate | 否 | 保障结束日期。传orderId时自动按出发日期+行程天数计算 | -| insuredPersons | List | 否 | 被保人列表。传orderId时自动从订单出行人获取 | -| entityCode | String | 否 | 投保公司主体编码，不填用默认主体 | -| remark | String | 否 | 备注 | - -#### 两种调用方式 - -**方式一：通过订单自动填充（推荐）** -```json -{ - "orderId": "2034961514288623617", - "planId": "2026279738275856390" -} -``` -系统自动从订单获取： -- 出行人 → 被保人 -- 出发日期 → 保障开始日期 -- 出发日期 + 行程天数 - 1 → 保障结束日期 - -**方式二：手动传全部参数（仍然支持）** -```json -{ - "planId": "2026279738275856390", - "startDate": "2026-05-01", - "endDate": "2026-05-05", - "insuredPersons": [ - { - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "110101199001011234", - "birthday": "1990-01-01", - "gender": "MALE", - "phone": "13800138000" - } - ] -} -``` - -#### 错误提示 - -| 场景 | 错误信息 | -|------|----------| -| 订单无出行人 | "无法获取订单出行人信息，请确认订单已添加出行人" | -| 出行人缺少姓名或证件号 | "订单无有效出行人（缺少姓名或证件号）" | -| 订单未设置出发日期 | "订单未设置出发日期，无法自动确定保障开始日期" | -| 订单未设置行程天数 | "订单未设置行程天数，无法自动确定保障结束日期" | - ---- - -## 前端使用场景 - -### 保险管理页 - 手动投保 -1. 选择订单 → 获得 orderId -2. 选择保险计划 → 获得 planId -3. 调用 `POST /admin/insurance/purchase`，只传 `{ orderId, planId }` -4. 无需再填写出行人信息和日期 - -### 注意事项 -- 订单必须已确认（CONFIRMED/PENDING_BALANCE/PENDING_DEPARTURE/TRAVELLING） -- 订单必须有出行人且出行人信息完整（姓名+证件号） -- 订单必须有出发日期和行程天数 diff --git a/changelogs/2026-03/2026-03-21_orderNo_fix.md b/changelogs/2026-03/2026-03-21_orderNo_fix.md deleted file mode 100644 index 1eb7b08..0000000 --- a/changelogs/2026-03/2026-03-21_orderNo_fix.md +++ /dev/null @@ -1,24 +0,0 @@ -# 订单号格式回退20位 - -**日期**: 2026-03-21 -**服务**: hl-order-service -**类型**: Bug修复 - ---- - -## 问题 - -订单号之前从20位改为25位（毫秒精度），导致微信支付接口报错"商户订单号错误"。原因是微信支付 `out_trade_no` 限制最长32位，订单号25位加上支付类型后缀 `-DEPOSIT-V99` 最长达37位，超限。 - -## 修复 - -订单号回退为20位：`HL` + 秒级时间戳(14位) + 4位随机数。 - -| | 修复前 | 修复后 | -|---|--------|--------| -| 示例 | HL2026032114580490720445 (25位) | HL202603211458041234 (20位) | -| out_trade_no 最长 | 25+12=37位 (超限) | 20+12=32位 (刚好) | - -## 前端影响 - -订单号展示区域确保支持20位即可（与之前一致）。 diff --git a/changelogs/2026-03/2026-03-21_order_logic_optimization.md b/changelogs/2026-03/2026-03-21_order_logic_optimization.md deleted file mode 100644 index e888868..0000000 --- a/changelogs/2026-03/2026-03-21_order_logic_optimization.md +++ /dev/null @@ -1,46 +0,0 @@ -# 产品订单逻辑优化 - -**日期**: 2026-03-21 -**服务**: hl-order-service, hl-mp-service -**类型**: 逻辑优化 - ---- - -## 变更说明 - -### 1. 报价接口返回库存信息 - -`POST /mp/product/{productId}/quote` 报价结果新增两个字段： - -| 新增字段 | 类型 | 说明 | -|---------|------|------| -| stock | Integer | 该日期剩余库存（null表示不限库存） | -| available | Boolean | 该日期是否可订（库存>=总人数或无库存限制） | - -**前端使用建议**： -- `available=false` 时禁用"立即下单"按钮，显示"该日期已售罄" -- `stock` 较少时显示"仅剩 N 位"提示 - -### 2. 早鸟优惠后支付金额自动同步 - -之前：早鸟优惠更新了 `finalPrice`，但 `fullPayment.amount` 和 `depositPayment` 仍按原价 - -现在：早鸟优惠后自动重算： -- `fullPayment.amount` = 优惠后价格 -- `depositPayment.depositAmount` = 优惠后价格 × 定金比例 -- `depositPayment.balanceAmount` = 优惠后价格 - 定金 - -### 3. 订单号格式升级 - -| | 旧格式 | 新格式 | -|---|--------|--------| -| 示例 | HL202603211234561234 | HL2026032112345612312345 | -| 长度 | 20位 | 25位 | -| 时间精度 | 秒级（14位） | 毫秒级（17位） | -| 随机位数 | 4位 | 6位 | - -**前端影响**：订单号展示区域需确保支持 25 位长度。 - -### 4. GROUP团期出发日期校验 - -新增：团期出发日期已过时，禁止用户报名，返回错误"该团期出发日期已过，无法报名"。 diff --git a/changelogs/2026-03/2026-03-21_order_travelers_api.md b/changelogs/2026-03/2026-03-21_order_travelers_api.md deleted file mode 100644 index 6261074..0000000 --- a/changelogs/2026-03/2026-03-21_order_travelers_api.md +++ /dev/null @@ -1,97 +0,0 @@ -# 新增：获取订单出行人接口 - -**日期**: 2026-03-21 -**服务**: hl-order-service -**类型**: 新增接口 - ---- - -## 功能说明 - -新增管理端独立获取订单出行人接口，用于保险投保页面自动填充被保人信息。 - ---- - -## 接口清单 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | /admin/order/{orderId}/travelers | 获取指定订单的出行人列表 | - ---- - -## 详细定义 - -### GET /admin/order/{orderId}/travelers - -#### 请求参数 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| orderId | path | Long | 是 | 订单ID | - -#### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "orderTravelerId": "2034962583668371457", - "orderId": "2034961514288623617", - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "152125199101022016", - "phone": "13800138000", - "gender": 1, - "birthday": "1991-01-02", - "travelerType": "ADULT", - "nationality": "中国", - "emergencyContact": "李四", - "emergencyPhone": "13800138001", - "email": null, - "createTime": "2026-03-20 19:57:42" - } - ] -} -``` - -#### 响应字段说明 - -| 字段 | 类型 | 说明 | -|------|------|------| -| orderTravelerId | String | 出行人ID | -| orderId | String | 订单ID | -| name | String | 姓名 | -| idCardType | String | 证件类型（字典：id_card_type）ID_CARD/PASSPORT/OTHER | -| idCardNo | String | 证件号码 | -| phone | String | 手机号（可能为null） | -| gender | Integer | 性别（字典：gender）1=男 0=女 | -| birthday | String | 出生日期 yyyy-MM-dd | -| travelerType | String | 出行人类型（字典：traveler_type）ADULT/CHILD/BABY | -| nationality | String | 国籍 | -| emergencyContact | String | 紧急联系人 | -| emergencyPhone | String | 紧急联系电话 | - ---- - -## 使用场景 - -### 保险投保页面 - 自动填充被保人 - -1. 用户输入关联订单ID -2. 调用 `GET /admin/order/{orderId}/travelers` 获取出行人列表 -3. 将出行人信息映射为被保人（姓名、证件号、性别、生日） -4. 自动填充到被保人列表，无需手动添加 - -### 字段映射（出行人 → 被保人） - -| 出行人字段 | 被保人字段 | -|-----------|-----------| -| name | name | -| idCardType | idCardType | -| idCardNo | idCardNo | -| gender（1=男→MALE, 0=女→FEMALE） | gender | -| birthday | birthday | -| phone | phone | diff --git a/changelogs/2026-03/2026-03-21_product_order_improvement.md b/changelogs/2026-03/2026-03-21_product_order_improvement.md deleted file mode 100644 index ca8aed1..0000000 --- a/changelogs/2026-03/2026-03-21_product_order_improvement.md +++ /dev/null @@ -1,56 +0,0 @@ -# 产品与订单模块改进 - -**日期**: 2026-03-21 -**服务**: hl-product-service, hl-order-service -**类型**: 功能增强 - ---- - -## 功能说明 - -### 1. 团期报名截止自动关闭 - -团期（GROUP 产品）超过报名截止日期后，系统每小时自动扫描，将 ENROLLING/CONFIRMED 状态的过期团期自动关闭为 CLOSED。 - -**前端影响**：无需改动。过期团期不再显示"可报名"状态，`batchStatus` 会变为 `CLOSED`。 - ---- - -### 2. 尾款到期自动取消 - -定金模式（DEPOSIT）订单，如果距出发日期不足 3 天仍未付尾款，系统每天凌晨自动取消订单。 - -**前端影响**：无需改动。订单状态会变为 `CANCELLED`，`cancelReason` 为"尾款未在出发前3天付清，系统自动取消"。建议在待付尾款页面增加倒计时提示。 - ---- - -### 3. 出发日期变更自动重新计价 - -管理员修改订单出发日期后，系统自动基于新日期的价格日历重新计算售价。 - -**前端影响**： -- 订单详情页的 `totalPrice` 可能因日期变更而更新 -- 时间线（timeline）中会记录价格变动详情，如："售价已更新: 5980.00 → 6280.00（+300.00）" -- 如果价格偏差超过 50%，不会自动更新，时间线记录"价格偏差超过50%，未自动更新，请手动核查" - ---- - -## 接口变更 - -**本次无接口变更**。以上功能均为后端定时任务和内部逻辑增强，不影响现有接口的请求/响应格式。 - -已有接口行为变化： - -| 接口 | 变化说明 | -|------|---------| -| GET /admin/product/item/{productId}/batch/list | 过期团期 batchStatus 会自动变为 CLOSED | -| GET /mp/order/{orderId} | 尾款逾期订单 status 会自动变为 CANCELLED | -| PUT /admin/order/{orderId}/edit | 修改出发日期后 totalPrice 可能自动更新 | - ---- - -## 注意事项 - -- 尾款截止默认 3 天（出发前 3 天），后续可配置 -- 价格自动更新有 50% 偏差保护，超出不会自动改价 -- 团期关闭后不可恢复报名，需重新创建团期 diff --git a/changelogs/2026-03/2026-03-22_2115_e6589b1_security_API.md b/changelogs/2026-03/2026-03-22_2115_e6589b1_security_API.md deleted file mode 100644 index d062125..0000000 --- a/changelogs/2026-03/2026-03-22_2115_e6589b1_security_API.md +++ /dev/null @@ -1,745 +0,0 @@ -# 接口变更记录 — 2026-03-22 21:15 - -> **提交** `e6589b1` · **作者** wx · **时间** 2026-03-22 21:15:06 +0800 -> -> security: 全项目API安全校验加固（16个微服务，258个文件） - -## 变更总览 - -- **产品服务** - - Pricing (+1) -- **保险服务** - - AdminInsurance (+1) - - InternalInsurance (+1) -- **合同服务** - - AdminContract (改1) - - InternalContract (+1) -- **文件服务** - - MpFile (+1, 改1) -- **订单服务** - - AdminAlbum (+1) - - AdminEarlyBird (+1, 改1) - - AdminInvoice (+1) - - AdminOrderConfig (+1) - - AdminOrder (+1, 改1) - - AdminOrderItinerary (+1) - - AdminOrderTodo (+1) - - AdminRefund (+1, 改1) - - AdminRefundPolicy (+1) - - AdminWorkOrder (+1, 改1) - - InternalAlbum (+1) - - InternalAutoProcess (+1) - - InternalDashboard (+1) - - InternalDesignerOrder (+1, 改1) - - InternalEarlyBird (+1) - - InternalInvoice (+1) - - InternalMpOrder (+1) - - InternalMpTrip (+1) - - InternalOrderStats (+1) - - InternalOrderTraveler (+1) - - InternalPaymentOrder (+1) - - MpOrder (+1) - - MpWeather (+1) - ---- - -## 产品服务 - -### Pricing - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「定价与费用管理」** - -### 🆕 `GET` /admin/product/item/{productId}/insurance-fee-preview — 预览保险方案费用 - -> 根据产品行程天数和选定的保险方案，计算人均保险费。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `schemeId` (`Long`) — 查询参数：保险方案ID - -**响应** `Result>` - ---- - -## 保险服务 - -### AdminInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「保险管理」** - -### 🆕 `POST` /admin/insurance/purchase-by-scheme — 按方案自动投保(schemeId+orderId) - -> 根据保险方案自动为订单所有出行人投保。系统自动从订单获取出行人信息和行程日期，按方案各段配置逐段投保。 - -**请求体** `AutoPurchaseRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅行订单ID | -| `schemeId` | `Long` | 保险方案ID | - -**响应** `Result` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `boolean` | 是否全部成功 | -| `purchasedCount` | `int` | 成功投保段数 | -| `failedCount` | `int` | 失败段数 | -| `failureReason` | `String` | 失败原因（部分失败或全部失败时返回第一个错误） | - -### InternalInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「【内部接口】保险（Feign调用）」** - -### 🆕 `GET` /internal/insurance/scheme/{schemeId}/premium — 获取保险方案信息(内部调用) - -> 内部服务间调用。返回方案的适用天数和人均保费，用于产品保存时校验天数匹配并自动填充保险费。 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数：方案ID - - `tripDays` (`int`) — 查询参数：行程天数 - -**响应** `Result>` - ---- - -## 合同服务 - -### AdminContract - -> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「合同管理」** - -### ✏️ `GET` /admin/contract/templates — 合同模板列表 - -- 参数: 无 → platform(String) - -### InternalContract - -> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「【内部接口】合同（Feign调用）」** - -### 🆕 `GET` /internal/contract/scheme/{schemeId}/config — 获取合同方案配置(内部调用) - -> 供 order-service 自动签约时获取方案的完整合同配置 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result>` - ---- - -## 文件服务 - -### MpFile - -> 📖 **接口文档**: [http://192.168.100.236:8091/doc.html](http://192.168.100.236:8091/doc.html) → 标签 **「C端文件上传」** - -### 🆕 `GET` /mp/file/mp/file - -### ✏️ `GET` /mp/file/preview-by-url — 文件在线预览 - -- 参数: url(String) → 无 - ---- - -## 订单服务 - -### AdminAlbum - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「管理端相册接口」** - -### 🆕 `GET` /admin/order/admin/order - -### AdminEarlyBird - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「早鸟优惠计划管理」** - -### 🆕 `GET` /admin/order/early-bird/admin/order/early-bird - -### ✏️ `GET` /admin/order/early-bird/list — 早鸟优惠计划列表 - -- 参数: page(int), pageSize(int) → page(int) - -### AdminInvoice - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.3 发票管理」** → 标签 **「发票管理」** - -### 🆕 `GET` /admin/invoice/admin/invoice - -### AdminOrderConfig - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「订单配置接口」** - -### 🆕 `GET` /admin/order/config/admin/order/config - -### AdminOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「管理端订单接口」** - -### 🆕 `GET` /admin/order/admin/order - -### ✏️ `GET` /admin/order/{orderId}/available-hotels — 配房可选酒店列表 - -- 参数: orderId(Long), dayIndex(Integer) → orderId(Long) - -### AdminOrderItinerary - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「管理端订单行程编辑」** - -### 🆕 `GET` /admin/order/{orderId}/itinerary/admin/order/{orderId}/itinerary - -### AdminOrderTodo - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「订单待办接口」** - -### 🆕 `GET` /admin/order/admin/order - -### AdminRefund - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「退款管理」** - -### 🆕 `GET` /admin/order/refund/admin/order/refund - -### ✏️ `GET` /admin/order/refund/list — 退款申请列表 - -- 参数: status(String), page(int), pageSize(int) → status(String), page(int) - -### AdminRefundPolicy - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「退款政策管理」** - -### 🆕 `GET` /admin/order/refund-policy/admin/order/refund-policy - -### AdminWorkOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「工单管理」** - -### 🆕 `GET` /admin/order/work-order/admin/order/work-order - -### ✏️ `GET` /admin/order/work-order/list — 工单列表 - -- 参数: status(String), type(String), priority(String), orderNo(String), assigneeAdminId(Long), page(int), pageSize(int) → status(String), type(String), priority(String), orderNo(String), assigneeAdminId(Long), page(int) - -### InternalAlbum - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序相册（Feign调用）」** - -### 🆕 `GET` /internal/mp/album/internal/mp/album - -### InternalAutoProcess - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】自动化处理（运维用）」** - -### 🆕 `GET` /internal/order/internal/order - -### InternalDashboard - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】工作台统计（Feign调用）」** - -### 🆕 `GET` /internal/order/dashboard/internal/order/dashboard - -### InternalDesignerOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】定制师订单（Feign调用）」** - -### 🆕 `GET` /internal/order/internal/order - -### ✏️ `GET` /internal/order/designer-list — 定制师订单列表 - - -**响应变更** `OrderListVO`: - - - 🆕 `surchargeAmount` (`BigDecimal`) — 费用增加总额 -- 参数: customizerId(Long), page(int), pageSize(int), status(String), keyword(String) → customizerId(Long), page(int), status(String), keyword(String) - -### InternalEarlyBird - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】早鸟优惠（Feign调用）」** - -### 🆕 `GET` /internal/mp/early-bird/internal/mp/early-bird - -### InternalInvoice - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序发票（Feign调用）」** - -### 🆕 `GET` /internal/mp/invoice/internal/mp/invoice - -### InternalMpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序订单（Feign调用）」** - -### 🆕 `GET` /internal/mp/order/internal/mp/order - -### InternalMpTrip - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序行程（Feign调用）」** - -### 🆕 `GET` /internal/mp/trip/internal/mp/trip - -### InternalOrderStats - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「内部-订单统计」** - -### 🆕 `GET` /internal/mp/order/internal/mp/order - -### InternalOrderTraveler - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】订单出行人（Feign调用）」** - -### 🆕 `GET` /internal/order/traveler/internal/order/traveler - -### InternalPaymentOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】订单-支付/合同/保险（Feign调用）」** - -### 🆕 `GET` /internal/order/internal/order - -### MpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「C端订单接口」** - -### 🆕 `GET` /mp/order/mp/order - -### MpWeather - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「内部天气接口(Feign)」** - -### 🆕 `GET` /internal/mp/weather/internal/mp/weather - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ PricingRequest - - - ❌ ~~`adultExtraBed`~~ (`BigDecimal`) — 成人加床费 - - ❌ ~~`childNoBed`~~ (`BigDecimal`) — 儿童不占床价（暂未使用，预留字段） - - ❌ ~~`singleRoomDiff`~~ (`BigDecimal`) — 单房差 - - ❌ ~~`companionPrice`~~ (`BigDecimal`) — 陪同人员价格 - - ❌ ~~`maxGroupSize`~~ (`Integer`) — 最大成团人数（CORE/GROUP产品用） - - ✏️ `minGroupSize`: 说明 "最小成团人数（CORE/GROUP产品用，影响均摊成本计算）" → "成团人数（影响均摊成本计算）" - -#### ✏️ ProductAutomationConfigVO - - - 🆕 `contractSchemeId` (`Long`) - - ❌ ~~`contractPlatform`~~ (`String`) - - ❌ ~~`contractTemplateCode`~~ (`String`) - - ❌ ~~`contractMode`~~ (`String`) - - ❌ ~~`signatoryMode`~~ (`Integer`) - - ❌ ~~`agencyCode`~~ (`String`) - - ❌ ~~`disputeResolution`~~ (`Integer`) - - ❌ ~~`supplementaryClause`~~ (`String`) - - ❌ ~~`transactorName`~~ (`String`) - - ❌ ~~`transactorPhone`~~ (`String`) - -#### ✏️ ProductCreateRequest - - - 🆕 `contractSchemeId` (`Long`) — 合同方案ID - - ❌ ~~`refundPolicyId`~~ (`String`) — 退款政策ID（已废弃，用refundPolicyIds替代） - - ❌ ~~`contractPlatform`~~ (`String`) — 合同平台(12301/FADADA) - - ❌ ~~`contractTemplateCode`~~ (`String`) — 合同模板编码 - - ❌ ~~`contractMode`~~ (`String`) — 签约模式(STANDARD/SYNC) - - ❌ ~~`signatoryMode`~~ (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - ❌ ~~`agencyCode`~~ (`String`) — 旅行社编码 - - ❌ ~~`disputeResolution`~~ (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - ❌ ~~`supplementaryClause`~~ (`String`) — 补充条款 - - ❌ ~~`transactorName`~~ (`String`) — 经办人姓名 - - ❌ ~~`transactorPhone`~~ (`String`) — 经办人电话 - -#### ✏️ ProductListVO - - - 🆕 `contractSchemeId` (`String`) — 合同方案ID - - ❌ ~~`contractPlatform`~~ (`String`) — 合同平台(12301/FADADA) - - ❌ ~~`contractTemplateCode`~~ (`String`) — 合同模板编码 - - ❌ ~~`contractMode`~~ (`String`) — 签约模式(STANDARD/SYNC) - - ❌ ~~`signatoryMode`~~ (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - ❌ ~~`agencyCode`~~ (`String`) — 旅行社编码 - - ❌ ~~`disputeResolution`~~ (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - ❌ ~~`supplementaryClause`~~ (`String`) — 补充条款 - - ❌ ~~`transactorName`~~ (`String`) — 经办人姓名 - - ❌ ~~`transactorPhone`~~ (`String`) — 经办人电话 - -#### ✏️ ProductPricingVO - - - ❌ ~~`adultExtraBed`~~ (`BigDecimal`) — 成人加床费 - - ❌ ~~`childNoBed`~~ (`BigDecimal`) — 儿童不占床价 - - ❌ ~~`singleRoomDiff`~~ (`BigDecimal`) — 单房差 - - ❌ ~~`companionPrice`~~ (`BigDecimal`) — 陪同人员价格 - - ❌ ~~`maxGroupSize`~~ (`Integer`) — 最大成团人数 - - ✏️ `minGroupSize`: 说明 "最小成团人数" → "成团人数" - -#### ✏️ ProductSaveRequest - - - 🆕 `contractSchemeId` (`Long`) — 合同方案ID - - ❌ ~~`refundPolicyId`~~ (`String`) — 退款政策ID（已废弃，用refundPolicyIds替代） - - ❌ ~~`contractPlatform`~~ (`String`) — 合同平台(12301/FADADA) - - ❌ ~~`contractTemplateCode`~~ (`String`) — 合同模板编码 - - ❌ ~~`contractMode`~~ (`String`) — 签约模式(STANDARD/SYNC) - - ❌ ~~`signatoryMode`~~ (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - ❌ ~~`agencyCode`~~ (`String`) — 旅行社编码 - - ❌ ~~`disputeResolution`~~ (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - ❌ ~~`supplementaryClause`~~ (`String`) — 补充条款 - - ❌ ~~`transactorName`~~ (`String`) — 经办人姓名 - - ❌ ~~`transactorPhone`~~ (`String`) — 经办人电话 - -#### ✏️ ProductUpdateRequest - - - 🆕 `contractSchemeId` (`Long`) — 合同方案ID - - ❌ ~~`refundPolicyId`~~ (`String`) — 退款政策ID（已废弃，用refundPolicyIds替代） - - ❌ ~~`contractPlatform`~~ (`String`) — 合同平台(12301/FADADA) - - ❌ ~~`contractTemplateCode`~~ (`String`) — 合同模板编码 - - ❌ ~~`contractMode`~~ (`String`) — 签约模式(STANDARD/SYNC) - - ❌ ~~`signatoryMode`~~ (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - ❌ ~~`agencyCode`~~ (`String`) — 旅行社编码 - - ❌ ~~`disputeResolution`~~ (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - ❌ ~~`supplementaryClause`~~ (`String`) — 补充条款 - - ❌ ~~`transactorName`~~ (`String`) — 经办人姓名 - - ❌ ~~`transactorPhone`~~ (`String`) — 经办人电话 - -#### ✏️ ProductVO - - - 🆕 `contractSchemeId` (`String`) — 合同方案ID - - ❌ ~~`refundPolicyId`~~ (`String`) — 退款政策ID（已废弃，用refundPolicyIds替代） - - ❌ ~~`refundPolicyName`~~ (`String`) — 退款政策名称（已废弃） - - ❌ ~~`contractPlatform`~~ (`String`) — 合同平台(12301/FADADA) - - ❌ ~~`contractTemplateCode`~~ (`String`) — 合同模板编码 - - ❌ ~~`contractMode`~~ (`String`) — 签约模式(STANDARD/SYNC) - - ❌ ~~`signatoryMode`~~ (`Integer`) — 签署模式(1=短信/2=现场/3=线下) - - ❌ ~~`agencyCode`~~ (`String`) — 旅行社编码 - - ❌ ~~`disputeResolution`~~ (`Integer`) — 争议解决方式(1=仲裁/2=诉讼) - - ❌ ~~`supplementaryClause`~~ (`String`) — 补充条款 - - ❌ ~~`transactorName`~~ (`String`) — 经办人姓名 - - ❌ ~~`transactorPhone`~~ (`String`) — 经办人电话 - -### 保险服务 - -#### ✏️ InsuranceSchemeVO - - - 🆕 `totalDays` (`Integer`) — 适用行程天数 - -### 公共模块 - -#### ✏️ OrderPayInfoDTO - - - 🆕 `surchargeAmount` (`BigDecimal`) — 费用增加总额 - -### 合同服务 - -#### ✏️ ContractCallbackPayload - - - 🆕 `timestamp` (`Long`) — 时间戳（Unix秒） - -### 小程序聚合服务 - -#### ✏️ MpCustomProductDetailVO - - - ❌ ~~`adultExtraBed`~~ (`BigDecimal`) — 成人加床费 - - ❌ ~~`childNoBed`~~ (`BigDecimal`) — 儿童不占床价 - - ❌ ~~`singleRoomDiff`~~ (`BigDecimal`) — 单房差 - - ❌ ~~`companionPrice`~~ (`BigDecimal`) — 陪同人员价格 - - ❌ ~~`maxGroupSize`~~ (`Integer`) — 最大成团人数 - - ✏️ `minGroupSize`: 说明 "最小成团人数" → "成团人数" - -#### ✏️ MpOrderDetailVO - - - 🆕 `surchargeAmount` (`BigDecimal`) — 费用增加总额 - - 🆕 `surcharges` (`List>`) — 费用增加项列表 - - 🆕 `displayStatus` (`String`) — 展示状态（前端主要使用此字段展示） - - 🆕 `displayStatusLabel` (`String`) — 展示状态标签 - - 🆕 `transportSegments` (`List>`) — 交通段列表 - - 🆕 `sharerOpenid` (`String`) — 分享者openid - -### 订单服务 - -#### ✏️ OrderDetailVO - - - 🆕 `surchargeAmount` (`BigDecimal`) — 费用增加总额 - - 🆕 `surcharges` (`List`) — 费用增加项列表 - -#### ✏️ RefundPolicyRequest - - - ❌ ~~`refundType`~~ (`String`) — 退款类型（字典：refund_type）DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) - - ❌ ~~`isDefault`~~ (`Boolean`) — 是否为默认政策（产品未绑定退款政策时使用默认政策） - -#### ✏️ RefundPolicyVO - - - ❌ ~~`refundType`~~ (`String`) — 退款类型（字典：refund_type）DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) - - ❌ ~~`isDefault`~~ (`Boolean`) — 是否为默认政策 - -### 评价服务 - -#### ✏️ CreateReviewRequest - - - ✏️ `content`: 说明 "评价内容(10-500字)" → "评价内容(10-5000字)" - - -📁 全部变更文件 (点击展开) - -``` -M hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java -M hl-common/src/main/java/com/hulalv/common/dto/PaymentRefundRequest.java -M hl-common/src/main/java/com/hulalv/common/exception/GlobalExceptionHandler.java -M hl-contract-service/src/main/java/com/hulalv/contract/constant/ContractConstants.java -M hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java -M hl-contract-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java -M hl-contract-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java -M hl-contract-service/src/main/java/com/hulalv/contract/dto/ContractCallbackPayload.java -M hl-contract-service/src/main/java/com/hulalv/contract/dto/CreateContractRequest.java -M hl-contract-service/src/main/java/com/hulalv/contract/dto/ReportContractRequest.java -M hl-contract-service/src/main/java/com/hulalv/contract/service/ContractCallbackService.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractCallbackServiceTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -M hl-file-service/src/main/java/com/hulalv/file/controller/MpFileController.java -M hl-file-service/src/main/java/com/hulalv/file/service/FileService.java -M hl-gateway/src/main/java/com/hulalv/gateway/filter/JwtAuthFilter.java -M hl-gateway/src/main/java/com/hulalv/gateway/filter/RateLimitFilter.java -M hl-guide-service/src/main/java/com/hulalv/guide/dto/ArticleCreateRequest.java -M hl-guide-service/src/main/java/com/hulalv/guide/dto/ArticleUpdateRequest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/dto/PurchaseInsuranceRequest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/dto/RechargeRequest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/dto/TrialPriceRequest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/entity/InsuranceScheme.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceSchemeService.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/vo/InsuranceSchemeVO.java -M hl-material-service/src/main/java/com/hulalv/material/dto/MaterialUploadConfirmRequest.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialService.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialTagService.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpCommonController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpCustomizeController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInvoiceController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpMessageController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpPaymentController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTravelerController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpUserController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWishController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpCheckinRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpFeedbackRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpFootprintAddRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpInvoiceApplyRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpLoginBySmsRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpPaymentPrepayRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpProductQuoteRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpRefundAppealRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpRefundApplyRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpReviewCreateRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpSmsSendRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpTravelerRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpUpdateOrderRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpUserProfileUpdateRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpWechatLoginRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpWishCreateRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminAlbumController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminEarlyBirdController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminInvoiceController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderConfigController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderItineraryController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTodoController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminRefundPolicyController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminWorkOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalAutoProcessController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalDashboardController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalDesignerOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpTripController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTravelerController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminCancelRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminOrderQueryRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminRefundReviewRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AlbumFileAddRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateWorkOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/ExecuteAppealRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/InvoiceApplyRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/ItineraryAddNodeRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/ItinerarySkipRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/ItineraryUndoRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/ProcessWorkOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RecordBalanceRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RefundAppealRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RefundPolicyRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RequestUnlockRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RoomTypeChangeRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/TransportSegmentRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/UpdateDepositRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/VehicleAssignmentRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/VehicleTypeChangeRequest.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderInfo.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderTimeline.java -M hl-order-service/src/main/java/com/hulalv/order/entity/RefundPolicy.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/NotificationEventHelper.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCacheService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTimelineService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTravelerService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApprovalPollingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundPolicyService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/RefundPolicyVO.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundApplicationServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundPolicyServiceTest.java -M hl-payment-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java -M hl-payment-service/src/main/java/com/hulalv/payment/dto/RefundRequest.java -M hl-payment-service/src/main/java/com/hulalv/payment/service/PaymentService.java -M hl-payment-service/src/main/java/com/hulalv/payment/service/RefundService.java -M hl-payment-service/src/test/java/com/hulalv/payment/service/PaymentServiceTest.java -M hl-payment-service/src/test/java/com/hulalv/payment/service/RefundServiceTest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/BookingTermsRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/CustomFeeRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/FormulaStepRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/FormulaTestRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/NodeUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductStatusRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/WarmTipsRequest.java -M hl-product-service/src/main/java/com/hulalv/product/engine/FormulaEngineConfig.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductPricing.java -M hl-product-service/src/main/java/com/hulalv/product/service/FormulaStepService.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductAutomationConfigVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/CostCalculationServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/FormulaStepServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/GroupTourBatchServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductPricingServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductStatusServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/PriceCalendarSetRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/dto/CostItemCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/dto/CostItemQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/dto/CostItemUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/PriceCalendarSetRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/RoomTypeCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/RoomTypeUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/PriceCalendarSetRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicSpotCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicSpotQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicSpotUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/PriceCalendarSetRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/ServiceCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/ServiceQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/ServiceUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/PriceCalendarSetRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffBatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/SuppliesCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/SuppliesQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/SuppliesUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/PriceCalendarSetRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleBatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleUpdateRequest.java -M hl-review-service/src/main/java/com/hulalv/review/dto/CreateReviewRequest.java -M hl-review-service/src/main/java/com/hulalv/review/dto/RejectRequest.java -M hl-task-service/src/main/java/com/hulalv/task/dto/CreateBoardRequest.java -M hl-task-service/src/main/java/com/hulalv/task/dto/CreateCommentRequest.java -M hl-task-service/src/main/java/com/hulalv/task/dto/CreateTaskRequest.java -M hl-task-service/src/main/java/com/hulalv/task/dto/UpdateTaskRequest.java -M hl-user-service/src/main/java/com/hulalv/user/controller/AuthController.java -M hl-user-service/src/main/java/com/hulalv/user/controller/SysJobController.java -M hl-user-service/src/main/java/com/hulalv/user/dto/AdminLoginRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/AgreementRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/BannerRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/ContactRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/CreateAdminRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/CreateDictDataRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/CreateDictTypeRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/CreateJobRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/CreateMenuRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/CreateRoleRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/ExploreCategoryResourceRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/FaqItemRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/LoginRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TopicRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TwoFaVerifyRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateAdminRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateDictDataRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateDictTypeRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateJobRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateMenuRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateProfileRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/UpdateRoleRequest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/WechatBindRequest.java -M hl-user-service/src/main/java/com/hulalv/user/interceptor/TokenInterceptor.java -M hl-user-service/src/main/java/com/hulalv/user/service/SysJobService.java -M hl-user-service/src/main/java/com/hulalv/user/service/UserMessageService.java -M hl-user-service/src/test/java/com/hulalv/user/service/SysJobServiceTest.java -``` - \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-22_api_security_hardening.md b/changelogs/2026-03/2026-03-22_api_security_hardening.md deleted file mode 100644 index 5b83de7..0000000 --- a/changelogs/2026-03/2026-03-22_api_security_hardening.md +++ /dev/null @@ -1,87 +0,0 @@ -# API 安全校验加固 - -**日期**: 2026-03-22 -**影响范围**: 全部 16 个微服务 -**类型**: 安全加固（纯后端，不影响正常业务流程） - ---- - -## 对前端的影响 - -### 核心结论：正常使用不受影响 - -本次改动只增加了输入校验，**不改变任何接口路径、参数名、响应格式**。只要前端传入的数据在合理范围内（正常业务操作都是），完全不受影响。 - -### 可能触发 400 错误的场景（之前不会报错，现在会） - -以下情况会返回 `400 Bad Request`，附带具体的校验错误信息： - -#### 1. 字符串超长 -所有 DTO 的字符串字段现在有长度限制： -- 名称类字段：最长 50-100 字符 -- 描述/备注：最长 500-2000 字符 -- 富文本内容：最长 10000-100000 字符 -- URL 字段：最长 500-1000 字符 - -**前端建议**：如果有 `` 或富文本编辑器，建议前端也加上 `maxlength` 限制，避免用户输入超长内容后提交失败。 - -#### 2. 数值范围 -- 所有金额字段：不允许负数（`@DecimalMin("0")`） -- 分页 `pageSize`：最大 100（超过自动截断为 100） -- 评分 `rating`：必须 1-5 -- 人数字段：`adultCount >= 1`，`childCount >= 0` - -#### 3. 列表数量限制 -- 出行人 `travelers`：最多 50 人 -- 图片列表 `images`：最多 9-20 张 -- 视频列表 `videos`：最多 3 个 -- 标签列表 `tags`：最多 20-50 个 - -#### 4. 枚举字段格式 -以下字段现在必须严格匹配指定值： -- `refundType`：只能是 `FULL` 或 `PARTIAL` -- `action`（退款审核）：只能是 `APPROVE` 或 `REJECT` -- `sortDir`：只能是 `asc` 或 `desc` - -#### 5. 小程序端 DTO 校验 -所有小程序 API（`/mp/**`）现在启用了 `@Valid` 校验： -- `phone`：必须匹配 `^1\d{10}$`（11位手机号） -- `code`（登录码）：不能为空 -- `content`（评价/反馈）：不能为空，最长 2000-5000 字 - ---- - -## 不影响前端的后端内部加固 - -以下改动完全在后端内部，前端无感知： - -| 加固项 | 说明 | -|--------|------| -| 退款并发锁 | Redis 分布式锁防止重复退款 | -| 法大大回调签名验证 | HMAC-SHA256 签名校验 | -| 资源状态修改角色校验 | 仅 SUPER_ADMIN 可直接改状态 | -| 定时任务 Bean 白名单 | 防止执行非授权代码 | -| 文件预览 XSS 防护 | OSS 域名白名单 + HTML 转义 | -| 限流器 IP 防伪造 | 优先使用 X-Real-IP | -| 2FA 端点限流 | 5次/分钟/IP | -| 退款/支付角色校验 | 需要 ADMIN/SUPER_ADMIN/FINANCE 角色 | -| 折扣上限 | 折扣不能等于总价（防 100% 免单） | -| 支付幂等 | Redis 防重复提交 | -| 公式引擎沙箱 | 关键词黑名单 + 循环上限 | - ---- - -## 400 错误响应格式 - -校验失败时返回格式不变： -```json -{ - "code": 400, - "message": "参数校验失败", - "data": { - "fieldName": "具体的错误提示（中文）" - } -} -``` - -**前端建议**：如果尚未统一处理 400 错误，建议在请求拦截器中对 400 状态码做 toast 提示，展示 `data` 中的第一条错误信息。 diff --git a/changelogs/2026-03/2026-03-22_balance_proof_upload.md b/changelogs/2026-03/2026-03-22_balance_proof_upload.md deleted file mode 100644 index be67a13..0000000 --- a/changelogs/2026-03/2026-03-22_balance_proof_upload.md +++ /dev/null @@ -1,66 +0,0 @@ -# 尾款凭证上传功能 — 前端缺少入口 - -**日期**: 2026-03-22 -**页面**: 订单详情 -**类型**: 前端功能缺失 - ---- - -## 问题 - -订单详情页没有"上传尾款凭证"的按钮，管理员无法记录线下收取的尾款。 - -## 后端接口（已就绪） - -### 记录尾款（线下收取） -``` -PUT /admin/order/{orderId}/record-balance -``` - -**请求体**： -```json -{ - "proofUrl": "https://xxx.oss.aliyuncs.com/proof/xxx.jpg", // 选填：支付凭证图片URL - "remark": "客户微信转账" // 选填：备注 -} -``` - -**前置条件**：订单状态为 `CONFIRMED`（已确认）或 `PENDING_DEPARTURE`（待出发） - -**调用后效果**： -- 订单状态变为 `PENDING_DEPARTURE`（待出发） -- `balance_proof_url` 保存凭证图片 -- 时间线记录"管理员确认收到尾款" - -### 设置尾款支付方式 -``` -PUT /admin/order/{orderId}/balance-pay-method?balancePayMethod=OFFLINE -``` -可选值：`ONLINE`（线上支付）/ `OFFLINE`（线下收取） - -## 前端实现建议 - -### 显示时机 -订单状态为 `CONFIRMED`（已确认）且 `paymentMode = DEPOSIT`（定金模式）时，在订单详情页显示"尾款"区域。 - -### UI 布局 -``` -┌─ 尾款信息 ──────────────────────────────┐ -│ 尾款金额：¥8,950.00（总价 - 已付定金） │ -│ 支付方式：○ 线上支付 ● 线下收取 │ -│ │ -│ [上传凭证] ← 点击上传图片（调文件服务） │ -│ 备注：[________________] │ -│ │ -│ [确认收到尾款] │ -└─────────────────────────────────────────┘ -``` - -### 操作流程 -1. 管理员选择"线下收取" -2. 上传凭证图片（调 `POST /admin/file/upload-token` 获取上传凭证 → 上传到 OSS → 拿到 URL） -3. 点击"确认收到尾款" → 调 `PUT /admin/order/{orderId}/record-balance` -4. 刷新订单详情 - -### 已有凭证回显 -订单详情返回的 `balanceProofUrl` 字段如果有值，显示已上传的凭证图片。 diff --git a/changelogs/2026-03/2026-03-22_hotel_assignment_display_bug.md b/changelogs/2026-03/2026-03-22_hotel_assignment_display_bug.md deleted file mode 100644 index 0cc48bd..0000000 --- a/changelogs/2026-03/2026-03-22_hotel_assignment_display_bug.md +++ /dev/null @@ -1,52 +0,0 @@ -# 配房数据保存成功但未回显 - -**日期**: 2026-03-22 -**页面**: 订单详情 → 配房信息 -**类型**: 前端 BUG - ---- - -## 问题 - -管理端配房保存后提示"成功"，但刷新页面后配房数据没有回显，仍显示空的配房表单。 - -## 后端确认 - -- 数据库 `order_info.hotel_assignments` 字段 **已有数据**（1105字节 JSON） -- 订单详情接口 `GET /admin/order/{orderId}` 返回的 `hotelAssignments` 字段 **包含完整数据** -- 保存接口 `PUT /admin/order/{orderId}/hotel-assignment` 返回 200 - -## 返回数据格式 - -`hotelAssignments` 是一个 JSON 字符串（String类型），内容是数组： - -```json -[ - { - "familyIndex": 1, - "hotelId": "2029926129876320258", - "hotelName": "海拉尔嘉世豪酒店", - "roomTypeId": "2029944763138936833", - "roomType": "标准间", - "date": "2026-03-23", - "remark": "001", - "upgradePrice": null - }, - { - "familyIndex": 1, - "hotelId": "2029926129876320258", - "hotelName": "海拉尔嘉世豪酒店", - "roomTypeId": "2029944763138936833", - "roomType": "标准间", - "date": "2026-03-24", - "remark": "002", - "upgradePrice": null - } -] -``` - -## 前端需要排查 - -1. **保存后是否重新调了详情接口？** 保存成功后需要重新 `GET /admin/order/{orderId}` 刷新数据 -2. **是否正确解析了 hotelAssignments？** 该字段是 JSON 字符串，需要 `JSON.parse()` 后按 `date` 分组渲染到对应天数 tab -3. **配房弹窗打开时是否读取了已有数据？** 打开弹窗时应从订单详情的 `hotelAssignments` 回填已配置的酒店/房型 diff --git a/changelogs/2026-03/2026-03-22_insurance_module_guide.md b/changelogs/2026-03/2026-03-22_insurance_module_guide.md deleted file mode 100644 index 8641ef1..0000000 --- a/changelogs/2026-03/2026-03-22_insurance_module_guide.md +++ /dev/null @@ -1,399 +0,0 @@ -# 保险模块前端对接完整指南 - -**日期**: 2026-03-22 -**模块**: 保险管理（hl-insurance-service） -**类型**: 前端对接指南 - ---- - -## 一、核心概念（必须理解） - -保险模块有 **两层** 概念，搞混会导致字段传错： - -### 第一层：第三方保险目录（只读，不可编辑） - -来自保游网 API 同步，管理员只能查看，不能修改。 - -``` -InsuranceProduct（保险产品） ← 比如"保游未来星研学旅行保险" - └── InsurancePlan（保险计划） ← 比如"20万计划""30万计划""50万计划" - └── InsuranceRate（费率） ← 比如"1天=5元""4-7天=15元" -``` - -**前端使用场景**： -- "保险产品"页面展示产品列表 -- 编辑方案时，选择"保险产品"下拉 → 联动加载该产品的"保险计划"下拉 - -### 第二层：自定义方案模板（可编辑） - -管理员创建的投保模板，关联到订单上使用。 - -``` -InsuranceScheme（保险方案） ← 比如"6日行程保险方案" - └── InsuranceSchemeSegment（保险段） ← 比如"第1-3天低风险段""第4-6天高风险段" - ├── productId → 引用哪个保险产品 - └── planId → 引用哪个保险计划 -``` - -**关键区别**： -- **Product/Plan** = 保险公司提供的产品目录（同步来的，不能改） -- **Scheme/Segment** = 我们自己组装的方案模板（可以自由创建/编辑） -- 一个方案可以有多个段，每段可以用不同的产品和计划 - ---- - -## 二、方案编辑页面字段说明 - -### 方案基本信息 - -| 字段 | API字段名 | 类型 | 必填 | 说明 | -|------|----------|------|------|------| -| 方案名称 | `name` | String | ✅ | 最长100字符 | -| 产品类型 | `isOverseas` | Boolean | ✅ | `false`=境内，`true`=境外 | -| 方案描述 | `description` | String | ❌ | 最长500字符 | -| 排序 | `sortOrder` | Integer | ❌ | `>= 0` | - -### 保险段配置（segments 数组） - -| 字段 | API字段名 | 类型 | 必填 | 说明 | -|------|----------|------|------|------| -| 段名称 | `segmentName` | String | ❌ | 如"低风险段""高风险段" | -| **保险产品** | `productId` | **Long** | ✅ | 选择哪个保险产品（下拉选） | -| **保险计划** | `planId` | **Long** | ✅ | 选择该产品下的哪个计划（联动下拉） | -| 起始天 | `dayOffsetStart` | Integer | ✅ | **从1开始**，1=出发当天 | -| 结束天 | `dayOffsetEnd` | Integer | ✅ | **必须 >= 起始天**，如6日行程最后一段填6 | -| 排序 | `sortOrder` | Integer | ❌ | `>= 0`，段内排序 | - -### ⚠️ 重点：dayOffsetEnd 不要传 -1 - -之前代码中 `-1` 表示"到行程最后一天"，但前端编辑时请直接填实际天数。例如： - -``` -6日行程保险方案： - 第1段：起始天=1，结束天=3（覆盖第1-3天） - 第2段：起始天=4，结束天=6（覆盖第4-6天）← 填6，不要填-1 -``` - -### ⚠️ 重点：productId 和 planId 的联动 - -1. 用户选择"保险产品"下拉时 → 调用 `GET /admin/insurance/products/{productId}/plans` 获取该产品的计划列表 -2. 用户再从计划列表中选择"保险计划" -3. 保存时传 `productId` + `planId`（都是 Long 类型的 ID，不是名称字符串） - -**常见错误**：把 productName 当 productId 传了，或者没有联动清空 planId - ---- - -## 三、接口清单 - -### 3.1 保险产品（只读） - -#### 产品列表 -``` -GET /admin/insurance/products?page=1&pageSize=20&isOverseas=false -``` -响应： -```json -{ - "code": 200, - "data": { - "list": [ - { - "productId": 2026279733947334657, - "productName": "保游未来星研学旅行保险", - "companyName": "中国人寿", - "isOverseas": false, - "minDays": 1, - "maxDays": 365, - "status": "ON_SALE" - } - ], - "total": 10, "page": 1, "pageSize": 20 - } -} -``` - -#### 产品计划及费率（联动下拉用） -``` -GET /admin/insurance/products/{productId}/plans -``` -响应： -```json -{ - "code": 200, - "data": [ - { - "planId": 2026295680158437378, - "planName": "20万计划", - "securityList": "<table>...</table>", - "rates": [ - { "rateId": 1, "dayRange": "1", "premium": 5.00 }, - { "rateId": 2, "dayRange": "2-3", "premium": 8.00 }, - { "rateId": 3, "dayRange": "4-7", "premium": 15.00 } - ] - }, - { - "planId": 2026295681706135562, - "planName": "30万计划", - "rates": [...] - } - ] -} -``` - -#### 同步产品数据（手动触发） -``` -POST /admin/insurance/sync-products -``` - -### 3.2 保险方案 CRUD - -#### 方案列表（管理页面用） -``` -GET /admin/insurance/scheme/list-all -``` -响应： -```json -{ - "code": 200, - "data": [ - { - "schemeId": 100001, - "name": "6日行程保险方案", - "description": "6天行程全覆盖：第1-3天低风险+第4-6天高风险", - "isOverseas": false, - "sortOrder": 15, - "totalDays": 6, - "status": "ACTIVE", - "segmentCount": 2, - "segments": [ - { - "segmentId": 200011, - "segmentName": "低风险段", - "dayOffsetStart": 1, - "dayOffsetEnd": 3, - "productId": 2026279733947334657, - "productName": "保游未来星研学旅行保险", - "planId": 2026295680158437378, - "planName": "20万计划", - "sortOrder": 0 - }, - { - "segmentId": 200012, - "segmentName": "高风险段", - "dayOffsetStart": 4, - "dayOffsetEnd": 6, - "productId": 2026279733947334657, - "productName": "保游未来星研学旅行保险", - "planId": 2026295681706135562, - "planName": "30万计划", - "sortOrder": 1 - } - ] - } - ] -} -``` - -#### 活跃方案列表（下拉选择用，如订单页选方案） -``` -GET /admin/insurance/scheme/list -``` -仅返回 `status=ACTIVE` 的方案。 - -#### 方案详情 -``` -GET /admin/insurance/scheme/{schemeId} -``` - -#### 创建方案 -``` -POST /admin/insurance/scheme -Content-Type: application/json - -{ - "name": "6日行程保险方案", - "description": "6天行程全覆盖：第1-3天低风险+第4-6天高风险", - "isOverseas": false, - "sortOrder": 15, - "segments": [ - { - "segmentName": "低风险段", - "dayOffsetStart": 1, - "dayOffsetEnd": 3, - "productId": 2026279733947334657, - "planId": 2026295680158437378, - "sortOrder": 0 - }, - { - "segmentName": "高风险段", - "dayOffsetStart": 4, - "dayOffsetEnd": 6, - "productId": 2026279733947334657, - "planId": 2026295681706135562, - "sortOrder": 1 - } - ] -} -``` - -#### 更新方案（全量替换 segments） -``` -PUT /admin/insurance/scheme/{schemeId} -``` -请求体同创建。**注意：segments 是全量替换，不是增量。前端保存时要把所有段都传回去。** - -#### 切换启用/停用 -``` -PUT /admin/insurance/scheme/{schemeId}/toggle-status -``` - -#### 删除方案 -``` -DELETE /admin/insurance/scheme/{schemeId} -``` - -### 3.3 保险订单 - -#### 订单列表 -``` -GET /admin/insurance/orders?page=1&pageSize=20&orderId=xxx&status=INSURED -``` -status 可选值：`PENDING`(待出单) / `INSURED`(已承保) / `CANCELLED`(已退保) / `FAILED`(投保失败) - -#### 订单详情（含被保人列表） -``` -GET /admin/insurance/orders/{insuranceOrderId} -``` - -#### 按旅行订单查询保险单 -``` -GET /admin/insurance/orders/by-order/{orderId} -``` - -#### 查询订单保险保障全貌 -``` -GET /admin/insurance/coverage/{orderId} -``` - -### 3.4 投保操作 - -#### 保费试算 -``` -POST /admin/insurance/trial-price -{ - "planId": 2026295680158437378, - "startDate": "2026-04-01", - "endDate": "2026-04-06", - "insuredCount": 5 -} -``` -响应： -```json -{ - "code": 200, - "data": { - "totalPremium": 75.00, - "unitPremium": 15.00, - "tripDays": 6, - "insuredCount": 5 - } -} -``` - -#### 按方案自动投保（推荐） -``` -POST /admin/insurance/purchase-by-scheme -{ - "orderId": 123456, - "schemeId": 100001 -} -``` - -#### 预览方案应用效果（投保前先看） -``` -POST /admin/insurance/scheme/preview-apply -{ - "schemeId": 100001, - "orderId": 123456 -} -``` -响应包含每段的实际日期、预估保费、是否跳过及原因。 - -#### 手动投保（指定计划） -``` -POST /admin/insurance/purchase -{ - "orderId": 123456, - "planId": 2026295680158437378, - "entityCode": "hh_nmg" -} -``` -传了 orderId 会自动从订单获取出行人和日期，不需要再传 insuredPersons。 - -#### 退保 -``` -POST /admin/insurance/cancel/{insuranceOrderId} -``` - -### 3.5 其他 - -#### 账户余额 -``` -GET /admin/insurance/balance -``` - -#### 在线充值 -``` -POST /admin/insurance/recharge -{ "money": 1000, "payType": 33 } -``` -payType: 11=支付宝扫码, 33=微信扫码 - -#### 下载保单PDF -``` -GET /admin/insurance/policy/{insuranceOrderId}/download -``` -返回 Base64 编码的 PDF 字符串。 - ---- - -## 四、页面交互建议 - -### 方案编辑页 - -``` -┌─────────────────────────────────────────────┐ -│ 方案名称 * [____________] │ -│ 产品类型 * ○ 境内 ○ 境外 │ -│ 方案描述 [________________________] │ -│ 排序 [0] ─ + │ -│ │ -│ 保险段配置 [+ 添加保险段] │ -│ ┌──────────────────────────────────────┐ │ -│ │ 第1段 ↑ ↓ 移除 │ │ -│ │ 段名称 [低风险段] │ │ -│ │ 保险产品* [保游未来星研学旅行保险 ▼] │ ← 下拉，数据来自 GET /products │ -│ │ 保险计划* [20万计划 ▼] │ ← 联动下拉，数据来自 GET /products/{id}/plans │ -│ │ 起始天* [1] ─ + 结束天* [3] ─ + │ │ -│ │ 排序 [0] ─ + │ │ -│ └──────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────┐ │ -│ │ 第2段 ↑ ↓ 移除 │ │ -│ │ 段名称 [高风险段] │ │ -│ │ 保险产品* [保游未来星研学旅行保险 ▼] │ │ -│ │ 保险计划* [30万计划 ▼] │ │ -│ │ 起始天* [4] ─ + 结束天* [6] ─ + │ │ -│ │ 排序 [1] ─ + │ │ -│ └──────────────────────────────────────┘ │ -│ [取消] [保存] │ -└─────────────────────────────────────────────┘ -``` - -### 交互要点 - -1. **保险产品下拉**：页面加载时调 `GET /admin/insurance/products?pageSize=100` 一次性加载 -2. **保险计划联动**：选择产品后调 `GET /admin/insurance/products/{productId}/plans`，清空已选的计划 -3. **编辑回显**：从 `GET /admin/insurance/scheme/{id}` 拿到 segments，每段的 `productId` 和 `planId` 用于回显下拉选中状态，`productName` 和 `planName` 用于显示文字 -4. **起始天/结束天**：`<el-input-number :min="1">`，结束天 `:min` 动态绑定为该段起始天 -5. **保存提交**：segments 全量提交，每段必须包含 `productId`(Long) 和 `planId`(Long) diff --git a/changelogs/2026-03/2026-03-22_insurance_scheme_frontend_fix.md b/changelogs/2026-03/2026-03-22_insurance_scheme_frontend_fix.md deleted file mode 100644 index 85e6428..0000000 --- a/changelogs/2026-03/2026-03-22_insurance_scheme_frontend_fix.md +++ /dev/null @@ -1,45 +0,0 @@ -# 保险方案编辑页 — 结束天显示为 -1 的处理 - -**日期**: 2026-03-22 -**页面**: 保险管理 → 保险方案 → 编辑方案 -**类型**: 前端展示优化 - ---- - -## 问题描述 - -保险方案编辑弹窗中，第2段的"结束天"显示为 `-1`，看起来像数据错误，但实际上 **`-1` 是后端约定的特殊值，表示"到行程最后一天"**。 - -数据库中 `day_offset_end = -1` 表示该段覆盖到行程结束，后端投保时会自动用方案的 `total_days` 替换 `-1`。 - -## 前端需要处理 - -### 1. 编辑表单中展示 -1 的处理 - -**方式A（推荐）**：将"结束天"改为下拉或单选： -- 选项1: 输入具体天数（`<el-input-number :min="起始天"`） -- 选项2: "到行程结束"（提交时传 `-1`） - -**方式B（简单）**：在结束天输入框旁显示提示文字： -- 当值为 `-1` 时，显示"（到最后一天）" -- `<el-input-number>` 的 `:min` 设为 `-1`（允许 -1 这个特殊值） - -### 2. 列表中展示 -如果列表展示了结束天，`-1` 应显示为"最后一天"或替换为方案的 `totalDays` 值。 - -### 3. 其他表单校验仍建议加上 -- 起始天：`>= 1` -- 排序：`>= 0` -- 结束天为正数时：`>= 起始天` - -## 数据说明 - -当前所有多段方案的最后一段 `day_offset_end` 都是 `-1`，这是**正常数据，不需要修改数据库**： - -| 方案 | 第1段结束天 | 第2段结束天 | -|------|-----------|-----------| -| 4日行程 | 2 | -1（=4） | -| 5日行程 | 2 | -1（=5） | -| 6日行程 | 3 | -1（=6） | -| 7日行程 | 3 | -1（=7） | -| 8日行程 | 4 | -1（=8） | diff --git a/changelogs/2026-03/2026-03-22_merchant_balance_fix.md b/changelogs/2026-03/2026-03-22_merchant_balance_fix.md deleted file mode 100644 index fbc148e..0000000 --- a/changelogs/2026-03/2026-03-22_merchant_balance_fix.md +++ /dev/null @@ -1,28 +0,0 @@ -# 修复商户号随机平均分配计数不准 - -**日期**: 2026-03-22 -**服务**: hl-order-service -**类型**: fix - ---- - -## 问题描述 - -订单取消/退款后，Redis 中的商户活跃订单计数没有递减（只有创建时递增），导致被取消订单多的商户号计数虚高，新订单全部分配到另一个商户号，随机平均分配失效。 - -## 修复内容 - -订单进入终态（取消/退款）时，自动递减对应商户号的 Redis 计数，覆盖以下5个场景： - -| 场景 | 触发方式 | -|------|----------| -| 用户取消待支付订单 | 小程序端取消 | -| 管理员取消订单 | 管理端操作 | -| 系统超时自动取消 | 支付超时 | -| 团期散团批量取消 | 管理端散团 | -| 退款成功 | 微信支付回调 | -| 管理员手动变更状态为已取消 | 管理端状态变更 | - -## 前端影响 - -无接口变更，纯后端逻辑修复。新创建的订单会更均匀地分配到不同商户号。 diff --git a/changelogs/2026-03/2026-03-22_order_status_guide.md b/changelogs/2026-03/2026-03-22_order_status_guide.md deleted file mode 100644 index e019626..0000000 --- a/changelogs/2026-03/2026-03-22_order_status_guide.md +++ /dev/null @@ -1,112 +0,0 @@ -# 订单状态说明 - -## 三个状态字段 - -| 字段 | 说明 | 前端用途 | -|------|------|---------| -| `displayStatus` | C端显示状态 | **小程序Tab筛选 + 状态文字展示** | -| `status` | 订单状态 | 管理后台展示 + 判断可用操作 | -| `processStatus` | 内部流程状态 | 仅管理后台，展示办理进度 | - ---- - -## 一、C端显示状态 `displayStatus`（小程序直接用这个） - -后端已算好，前端**不需要自己映射**，直接读 `displayStatus` 字段即可。 - -| 值 | 中文标签 | 说明 | -|----|---------|------| -| `PENDING_PAY` | 待支付 | 未付款 | -| `PENDING_DEPARTURE` | 待出行 | 已付款，等出发（含定金已付、全款已付、已确认、待付尾款） | -| `TRAVELLING` | 出行中 | 旅行进行中 | -| `PENDING_REVIEW` | 待评价 | 行程结束，未评价 | -| `COMPLETED` | 已完成 | 行程结束，已评价 | -| `AFTER_SALE` | 售后 | 退款中 / 已退款 | -| `CANCELLED` | 已取消 | 已取消 | - -**小程序订单列表Tab建议**：全部 / 待支付 / 待出行 / 出行中 / 待评价 / 售后 - ---- - -## 二、订单状态 `status`（管理后台用） - -| 值 | 中文标签 | -|----|---------| -| `PENDING_PAY` | 待支付 | -| `DEPOSIT_PAID` | 已付定金 | -| `PAID` | 已全额支付 | -| `CONFIRMED` | 已确认 | -| `PENDING_BALANCE` | 待付尾款 | -| `PENDING_DEPARTURE` | 待出行 | -| `TRAVELLING` | 旅行中 | -| `COMPLETED` | 已完成 | -| `CANCELLED` | 已取消 | -| `REFUNDING` | 退款中 | -| `REFUNDED` | 已退款 | - -### 状态流转 - -``` -全款：待支付 → 已全额支付 → 已确认 → 待出行 → 旅行中 → 已完成 -定金：待支付 → 已付定金 → 已确认 → 待付尾款 → 待出行 → 旅行中 → 已完成 - -退款：任何已付款状态 → 退款中 → 已退款 -取消：待支付 / 已付定金 → 已取消（用户可取消） -``` - -### 按状态可用的操作按钮 - -| status | 用户可操作 | 管理员可操作 | -|--------|-----------|-------------| -| `PENDING_PAY` | 去支付、取消 | 取消 | -| `DEPOSIT_PAID` | 取消、申请退款 | 确认、取消 | -| `PAID` | 申请退款 | 确认、取消 | -| `CONFIRMED` | 申请退款 | 取消 | -| `PENDING_BALANCE` | 付尾款、申请退款 | 取消 | -| `PENDING_DEPARTURE` | 申请退款 | 取消 | -| `TRAVELLING` | — | — | -| `COMPLETED` | 评价、申请退款 | — | -| `CANCELLED` | — | — | -| `REFUNDING` | — | — | -| `REFUNDED` | — | — | - ---- - -## 三、内部流程状态 `processStatus`（仅管理后台） - -订单确认后，内部按顺序办理，前端可做进度条展示。 - -| 值 | 中文标签 | 步骤 | -|----|---------|------| -| `PENDING_INFO` | 待补全信息 | 1 | -| `PENDING_INSURANCE` | 待配保险 | 2 | -| `PENDING_CONTRACT` | 待签合同 | 3 | -| `PENDING_ROOM` | 待配房 | 4 | -| `PENDING_VEHICLE` | 待配车 | 5 | -| `PENDING_FINANCE` | 待核算 | 6 | -| `READY` | 就绪 | 7 | -| `INTERNAL_CONFIRMED` | 内部已确认 | 8 | - -流程顺序：1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 - ---- - -## 四、支付模式 `paymentMode` - -| 值 | 中文 | 说明 | -|----|------|------| -| `FULL` | 全款 | 一次付清 | -| `DEPOSIT` | 定金+尾款 | 先付定金，后付尾款 | - ---- - -## 五、字典对照 - -以上状态对应的字典 `dict_type`： - -| 字典类型 | 说明 | -|---------|------| -| `order_status` | 订单状态（11个值） | -| `order_display_status` | C端显示状态（7个值） | -| `order_process_status` | 内部流程状态（8个值） | -| `payment_mode` | 支付模式（2个值） | diff --git a/changelogs/2026-03/2026-03-22_product_scheme_validation.md b/changelogs/2026-03/2026-03-22_product_scheme_validation.md deleted file mode 100644 index 766718e..0000000 --- a/changelogs/2026-03/2026-03-22_product_scheme_validation.md +++ /dev/null @@ -1,40 +0,0 @@ -# 产品保险/合同方案验证调整 - -**日期**: 2026-03-22 -**服务**: hl-product-service -**类型**: fix + enhancement - ---- - -## 功能说明 - -调整产品保险方案和合同方案的验证时机： - -1. **创建产品（草稿）时**：`insuranceSchemeId` 和 `contractSchemeId` 改为**可选**，不再强制必填 -2. **核心产品/小蒙马上架前**：校验必须已配置保险方案和合同方案，否则上架失败 -3. **定制产品完成前**（DRAFT → COMPLETED）：校验必须已配置保险方案和合同方案，否则完成失败 - -## 影响接口 - -### POST /admin/product （创建产品） - -**变更**：`insuranceSchemeId` 和 `contractSchemeId` 从必填改为可选 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| insuranceSchemeId | Long | 否（原为是） | 保险方案ID，上架/完成前必须配置 | -| contractSchemeId | Long | 否（原为是） | 合同方案ID，上架/完成前必须配置 | - -### PUT /admin/product/{productId}/status （状态变更） - -**变更**：新增上架/完成前的方案校验 - -- **核心产品/小蒙马** 变更为 `PUBLISHED` 时，校验 `insuranceSchemeId` 和 `contractSchemeId` 非空 -- **定制产品** 变更为 `COMPLETED` 时，校验 `insuranceSchemeId` 和 `contractSchemeId` 非空 -- 校验失败返回错误信息，如：`上架校验不通过: 保险方案不能为空; 合同方案不能为空` - -## 前端注意事项 - -- 产品编辑页保存草稿时，保险方案和合同方案可以留空 -- 点击「上架」或定制产品点击「完成」时，后端会校验这两个字段 -- 建议前端在上架/完成按钮点击前做前置校验提示，提升用户体验 diff --git a/changelogs/2026-03/2026-03-22_refund_policy_simplify.md b/changelogs/2026-03/2026-03-22_refund_policy_simplify.md deleted file mode 100644 index 458ec4b..0000000 --- a/changelogs/2026-03/2026-03-22_refund_policy_simplify.md +++ /dev/null @@ -1,106 +0,0 @@ -# 退款政策简化 + 预订须知必填校验 - -## 日期 -2026-03-22 - ---- - -## 一、退款政策管理简化 - -### 变更说明 -退款政策现在**直接绑定到产品**，不再区分退款类型，不再有默认政策概念。 - -### 删除的字段 - -| 接口 | 删除字段 | 说明 | -|------|---------|------| -| 退款政策列表/详情 VO | `refundType` | 不再区分定金/全款/尾款类型 | -| 退款政策列表/详情 VO | `isDefault` | 不再有默认政策概念 | -| 退款政策创建/修改请求 | `refundType` | 同上 | -| 退款政策创建/修改请求 | `isDefault` | 同上 | -| 产品详情 VO | `refundPolicyId` | 已废弃，用 refundPolicyIds | -| 产品详情 VO | `refundPolicyName` | 已废弃 | - -### 退款政策列表页（退款管理 > 退款政策） - -**需要删除的列：** -- ~~退款类型~~ -- ~~生效开始~~ -- ~~生效结束~~ -- ~~默认~~ - -**保留的列：** -- 政策名称 -- 规则数（规则条数） -- 状态（启用/禁用） -- 创建时间 -- 操作 - -### 退款政策创建/修改表单 - -**需要删除的字段：** -- ~~退款类型（DEPOSIT/BALANCE/FULL 下拉）~~ -- ~~是否默认（开关）~~ - -**保留的字段：** -- 政策名称（必填） -- 备注（选填） -- 退款规则列表（必填，每条规则包含：距出发天数 + 退款比例%） - -### 接口无变化 -- `GET /admin/order/refund-policy/list` — 退款政策列表 -- `GET /admin/order/refund-policy/enabled` — 启用的政策列表（产品设计选择用） -- `GET /admin/order/refund-policy/{policyId}` — 政策详情 -- `POST /admin/order/refund-policy` — 创建政策 -- `PUT /admin/order/refund-policy/{policyId}` — 修改政策 -- `DELETE /admin/order/refund-policy/{policyId}` — 删除政策（不再限制"默认不能删"） -- `PUT /admin/order/refund-policy/{policyId}/toggle?enabled=true/false` — 启用/禁用 - ---- - -## 二、产品退款政策绑定（按支付方式映射） - -### `refundPolicyIds` 字段格式（Map，不变） - -```json -{ - "refundPolicyIds": { - "FULL": "3", - "DEPOSIT": "1", - "BALANCE": "4" - } -} -``` - -- key = 支付类型：`FULL`（全款）、`DEPOSIT`（定金）、`BALANCE`（尾款） -- value = 退款政策ID（从 `GET /admin/order/refund-policy/enabled` 获取） -- 退款政策本身不再区分类型，任何政策都可以绑定到任何支付类型 - -### 退款政策与支付方式的关系 - -| 支付方式 | 需要配置的退款政策 | -|---------|------------------| -| 全款支付 (FULL) | FULL | -| 定金+尾款 (DEPOSIT) | DEPOSIT + BALANCE | - -**上架/完成时自动校验**：系统根据产品的支付方式（`product_pricing.payment_type`）检查 `refundPolicyIds` 中是否配置了对应的退款政策。缺少则校验不通过。 - ---- - -## 三、产品上架/完成新增必填校验 - -以下字段在**上架（PUBLISHED）**和**定制完成（COMPLETED）**时必须填写，否则校验不通过： - -| 字段 | 说明 | 选择来源 | -|------|------|---------| -| `bookingTermsId` | 预订条款 | `GET /admin/product/booking-terms/enabled` | -| `refundPolicyIds` | 退款政策（按支付方式映射） | `GET /admin/order/refund-policy/enabled` | -| `warmTipsId` | 温馨提示 | `GET /admin/product/warm-tips/enabled` | -| `insuranceSchemeId` | 保险方案 | 已有 | -| `contractSchemeId` | 合同方案 | 已有 | - ---- - -## 四、所有产品改为预约产品 - -所有产品的 `isBooking` 已设为 `true`（预约产品）。产品列表"预约"列应全部显示"是"。 diff --git a/changelogs/2026-03/2026-03-22_status_reference.md b/changelogs/2026-03/2026-03-22_status_reference.md deleted file mode 100644 index 1a5961e..0000000 --- a/changelogs/2026-03/2026-03-22_status_reference.md +++ /dev/null @@ -1,236 +0,0 @@ -# 全局状态枚举参考（小程序 + 管理端） - -**日期**: 2026-03-22 -**类型**: 参考文档 - ---- - -## 一、订单状态（order_status） - -后端字段：`status`，共 11 个值。 - -| 值 | 中文 | 说明 | -|----|------|------| -| `PENDING_PAY` | 待支付 | 下单后未支付 | -| `DEPOSIT_PAID` | 已付定金 | 定金模式已付定金 | -| `PAID` | 已全额支付 | 全款模式已付全款 | -| `CONFIRMED` | 已确认 | 管理员/系统确认订单 | -| `PENDING_BALANCE` | 待付尾款 | 定金模式，待付尾款 | -| `PENDING_DEPARTURE` | 待出行 | 内部流程全部就绪 | -| `TRAVELLING` | 旅行中 | 出发日自动切换 | -| `COMPLETED` | 已完成 | 行程结束自动切换 | -| `CANCELLED` | 已取消 | 用户/管理员/系统取消 | -| `REFUNDING` | 退款中 | 退款申请已提交 | -| `REFUNDED` | 已退款 | 退款到账 | - -### 状态流转 - -``` -PENDING_PAY → DEPOSIT_PAID / PAID / CANCELLED -DEPOSIT_PAID → CONFIRMED / REFUNDING -PAID → CONFIRMED / REFUNDING -CONFIRMED → PENDING_BALANCE / PENDING_DEPARTURE / REFUNDING -PENDING_BALANCE → PENDING_DEPARTURE / REFUNDING -PENDING_DEPARTURE → TRAVELLING / REFUNDING -TRAVELLING → COMPLETED -COMPLETED → REFUNDING -REFUNDING → REFUNDED -``` - ---- - -## 二、小程序展示状态（order_display_status） - -后端字段：`displayStatus`，简化为 7 个 Tab 用值。 - -| 值 | 中文 | 对应的内部状态 | -|----|------|---------------| -| `PENDING_PAY` | 待支付 | PENDING_PAY | -| `PENDING_DEPARTURE` | 待出行 | DEPOSIT_PAID, PAID, CONFIRMED, PENDING_BALANCE, PENDING_DEPARTURE | -| `TRAVELLING` | 出行中 | TRAVELLING | -| `PENDING_REVIEW` | 待评价 | COMPLETED（未评价） | -| `COMPLETED` | 已完成 | COMPLETED（已评价） | -| `AFTER_SALE` | 售后 | REFUNDING, REFUNDED | -| `CANCELLED` | 已取消 | CANCELLED | - ---- - -## 三、内部流程状态（process_status） - -后端字段：`processStatus`，订单确认后的 7 步内部工作流。 - -| 值 | 中文 | 步骤 | -|----|------|------| -| `PENDING_INFO` | 待补全信息 | 0（初始） | -| `PENDING_INSURANCE` | 待配保险 | 1 | -| `PENDING_CONTRACT` | 待签合同 | 2 | -| `PENDING_ROOM` | 待配房 | 3 | -| `PENDING_VEHICLE` | 待配车 | 4 | -| `PENDING_FINANCE` | 待核算 | 5 | -| `READY` | 就绪 | 6（流程完成） | -| `INTERNAL_CONFIRMED` | 内部已确认 | 特殊 | - -### 流转顺序 - -``` -PENDING_INFO → PENDING_INSURANCE → PENDING_CONTRACT → PENDING_ROOM → PENDING_VEHICLE → PENDING_FINANCE → READY -``` - ---- - -## 四、支付交易状态（payment_status） - -后端字段：`PaymentTransaction.status` - -| 值 | 中文 | 说明 | -|----|------|------| -| `PENDING` | 待支付 | 预下单已创建 | -| `SUCCESS` | 支付成功 | 微信回调确认 | -| `CLOSED` | 已关闭 | 交易关闭 | -| `FAILED` | 支付失败 | 支付异常 | - -### 支付类型（pay_type） - -| 值 | 中文 | -|----|------| -| `FULL` | 全款 | -| `DEPOSIT` | 定金 | -| `BALANCE` | 尾款 | - -### 交易方式（trade_type） - -| 值 | 中文 | -|----|------| -| `JSAPI` | 小程序支付 | -| `H5` | H5支付 | - -### 商户号 - -| mchId | 别名 | 中文 | -|-------|------|------| -| `1106110439` | hulai | 呼籁 | -| `1246532201` | shanhe | 山河 | -| `1684769133` | wenlu | 文旅 | - ---- - -## 五、退款状态 - -### 退款交易状态（refund_status） - -| 值 | 中文 | -|----|------| -| `PENDING` | 退款中 | -| `SUCCESS` | 退款成功 | -| `FAILED` | 退款失败 | -| `ABNORMAL` | 退款异常 | - -### 退款申请状态（refund_application_status） - -| 值 | 中文 | 说明 | -|----|------|------| -| `PENDING` | 待审核 | 用户提交退款申请 | -| `APPROVED` | 已通过 | 管理员审核通过 | -| `REJECTED` | 已拒绝 | 管理员驳回 | -| `REFUNDING` | 退款中 | 已发起微信退款 | -| `REFUNDED` | 已退款 | 退款到账 | -| `CANCELLED` | 已撤回 | 用户撤回申请 | -| `APPEALING` | 申诉中 | 用户对驳回发起申诉 | -| `APPEAL_APPROVED` | 申诉通过 | 申诉审核通过 | -| `APPEAL_REJECTED` | 申诉驳回 | 申诉被驳回 | - -### 退款类型（refund_type） - -| 值 | 中文 | -|----|------| -| `DEPOSIT` | 定金 | -| `BALANCE` | 尾款 | -| `FULL` | 全款 | - ---- - -## 六、保险状态（insurance_status） - -后端字段：`InsuranceOrder.status` - -| 值 | 中文 | -|----|------| -| `PENDING` | 待出单 | -| `INSURED` | 已承保 | -| `CANCELLED` | 已退保 | -| `FAILED` | 投保失败 | - ---- - -## 七、合同状态（contract_status） - -后端字段：`Contract.status` - -| 值 | 中文 | 说明 | -|----|------|------| -| `PENDING` | 待生成 | 合同记录已创建 | -| `GENERATED` | 已生成 | 合同文件已生成 | -| `SIGNING` | 签署中 | 等待用户签署 | -| `SIGNED` | 已签署 | 双方签署完成 | -| `VOIDING` | 作废中 | 发起作废 | -| `VOIDED` | 已作废 | 合同已作废 | -| `REPORTED` | 已上报 | 合同已上报12301 | -| `UPLOADED` | 已上传 | 合同已上传至平台 | - ---- - -## 八、产品状态（product_status） - -后端字段：`Product.status` - -| 值 | 中文 | 说明 | -|----|------|------| -| `DRAFT` | 草稿 | 新建/编辑中 | -| `PENDING_REVIEW` | 待审核 | 提交审批 | -| `REVIEWED` | 已审核 | 审批通过 | -| `REJECTED` | 已驳回 | 审批驳回 | -| `PUBLISHED` | 已上架 | 小程序可见 | -| `UNPUBLISHED` | 已下架 | 小程序不可见 | -| `COMPLETED` | 已完成 | 定制产品完成设计 | -| `ORDERED` | 已下单 | 定制产品已下单 | - -### 产品类型（product_type） - -| 值 | 中文 | -|----|------| -| `CORE` | 核心产品 | -| `ROUTE` | 路书产品 | -| `CUSTOM` | 私人定制 | -| `GROUP` | 小蒙马拼团 | - ---- - -## 九、待办状态（todo_status） - -| 值 | 中文 | -|----|------| -| `PENDING` | 待处理 | -| `COMPLETED` | 已完成 | -| `CANCELLED` | 已取消 | - -### 待办类型（todo_type） - -| 值 | 步骤 | 中文 | 负责角色 | -|----|------|------|----------| -| `INSURANCE` | 1 | 待配置保险 | 定制师 | -| `CONTRACT` | 2 | 待签订合同 | 定制师 | -| `ARRANGE_ROOM` | 3 | 待安排住宿 | 房务 | -| `ARRANGE_VEHICLE` | 4 | 待安排车辆 | 车务 | -| `CONFIRM_CHECKLIST` | 5 | 待确认清单 | 定制师 | -| `PROCESS_REFUND` | 紧急 | 需退款处理 | - | - ---- - -## 十、发票状态（invoice_status） - -| 值 | 中文 | -|----|------| -| `PENDING` | 待开票 | -| `ISSUED` | 已开票 | -| `FAILED` | 开票失败 | -| `VOIDED` | 已作废 | diff --git a/changelogs/2026-03/2026-03-22_vehicle_assignment_fields.md b/changelogs/2026-03/2026-03-22_vehicle_assignment_fields.md deleted file mode 100644 index 7afcdf4..0000000 --- a/changelogs/2026-03/2026-03-22_vehicle_assignment_fields.md +++ /dev/null @@ -1,29 +0,0 @@ -# 配车接口字段说明 - -**日期**: 2026-03-22 -**接口**: `PUT /admin/order/{orderId}/vehicle-assignment` -**问题**: 前端报错 "vehicleModel: 车型不能为空; vehicleBrand: 品牌不能为空" - ---- - -## 原因 - -前端选择了车型下拉（选到了车型ID），但提交时没有传 `vehicleModel` 和 `vehicleBrand` 字段。 - -## 请求体必传字段 - -```json -{ - "vehicleModel": "小蒙马车（5座）", // 必填：车型名称（从车辆列表选中项中取） - "vehicleBrand": "蒙古马", // 必填：品牌（从车辆列表选中项中取） - "plateNumber": "222", // 选填：车牌号 - "driverName": "2222", // 选填：司机姓名 - "driverPhone": "22222" // 选填：司机电话 -} -``` - -## 前端处理方式 - -选择车型下拉时，从选中的车辆数据中取出 `vehicleModel`（车型名称）和 `vehicleBrand`（品牌），一起放到提交的请求体中。不能只传车型ID。 - -车辆列表接口 `GET /admin/order/{orderId}/available-vehicles` 返回的每项数据都包含 `vehicleModel` 和 `vehicleBrand` 字段。 diff --git a/changelogs/2026-03/2026-03-23_1607_9b7b524_fix_12.md b/changelogs/2026-03/2026-03-23_1607_9b7b524_fix_12.md deleted file mode 100644 index ff300ce..0000000 --- a/changelogs/2026-03/2026-03-23_1607_9b7b524_fix_12.md +++ /dev/null @@ -1,407 +0,0 @@ -# 接口变更记录 — 2026-03-23 16:07 - -> **提交** `9b7b524` · **作者** wx · **时间** 2026-03-23 16:07:31 +0800 -> -> fix: 订单全流程测试修复（12项） - -## 变更总览 - -- **合同服务** - - AdminContract (+1) - - 🆕 AdminContractScheme (+7 接口) -- **小程序聚合服务** - - MpOrder (+1) -- **订单服务** - - InternalMpOrder (+1) - ---- - -## 合同服务 - -### AdminContract - -> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「合同管理」** - -### 🆕 `POST` /admin/contract/create-by-scheme — 按方案创建合同（简化） - -> 只需传orderId和schemeId，后端自动从订单获取出行人、日期、联系人等数据，结合合同方案配置创建合同。 - -**响应** `Result<ContractDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `supplementaryClause` | `String` | 补充约定内容 | -| `travelers` | `List<TravelerVO>` | 出行人列表 | -| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 | -| `travelerId` | `Long` | 出行人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `isSigner` | `Boolean` | 是否签署人 | -| `logId` | `Long` | 日志ID | -| `oldStatus` | `String` | 旧状态 | -| `newStatus` | `String` | 新状态 | -| `source` | `String` | 变更来源 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: AdminContractScheme - -> 📖 **接口文档**: [http://192.168.100.236:8095/doc.html](http://192.168.100.236:8095/doc.html) → 标签 **「合同方案管理」** - -### 📌 `GET` /admin/contract/scheme/list — 查询启用的合同方案列表 - -> 供产品配置时下拉选择使用，只返回启用状态的方案 - -**响应** `Result<List<ContractSchemeVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/scheme/list-all — 查询全部合同方案列表 - -> 管理页面使用，包含停用的方案 - -**响应** `Result<List<ContractSchemeVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/scheme/{schemeId} — 获取合同方案详情 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/scheme — 创建合同方案 - -**请求体** `ContractSchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码 | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码(可选，不填则根据订单支付商户号自动匹配旅行社) | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款(可选) | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序(越小越靠前) | - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/contract/scheme/{schemeId} — 更新合同方案 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**请求体** `ContractSchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码 | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码(可选，不填则根据订单支付商户号自动匹配旅行社) | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款(可选) | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序(越小越靠前) | - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/contract/scheme/{schemeId}/toggle-status — 切换方案启用/停用状态 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/contract/scheme/{schemeId} — 删除合同方案 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -## 小程序聚合服务 - -### MpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 订单接口」** - -### 🆕 `PUT` /mp/order/{orderId}/remark — 添加/修改订单备注 - -> 用户在订单详情页添加或修改备注。备注对管理端可见。 -请求体：{"remark": "备注内容"} - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -## 订单服务 - -### InternalMpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序订单（Feign调用）」** - -### 🆕 `PUT` /internal/mp/order/{orderId}/remark — 添加/修改订单备注 - -> 用户在订单详情页添加或修改备注内容 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result<Void>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpOrderDetailVO - - - 🆕 `hotelAssignmentDetails` (`List<Map<String, Object>>`) — 酒店分配详情（按家庭分组，含封面图） - - ✏️ `hotelAssignments`: 说明 "酒店分配信息JSON" → "酒店分配信息JSON（原始数据）" - -### 订单服务 - -#### ✏️ AdminUpdateOrderRequest - - - 🆕 `customizerId` (`Long`) — 定制师ID（切换定制师） - -#### 🆕 HotelAssignmentVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `familyIndex` | `Integer` | 家庭序号（从1开始） | -| `familyLabel` | `String` | 家庭标签（如：家庭1、家庭2） | -| `days` | `List<DayAssignment>` | 每天的住宿分配列表 | -| `date` | `String` | 日期（yyyy-MM-dd） | -| `hotelId` | `Long` | 酒店ID | -| `hotelName` | `String` | 酒店名称 | -| `hotelCoverUrl` | `String` | 酒店封面图URL（从产品快照提取，可能为空） | -| `roomTypeId` | `Long` | 房型ID | -| `roomType` | `String` | 房型名称 | -| `roomTypeCoverUrl` | `String` | 房型封面图URL（从产品快照提取，可能为空） | -| `roomCount` | `Integer` | 房间数量 | -| `remark` | `String` | 备注 | - -#### ✏️ OrderDetailVO - - - 🆕 `productTypeLabel` (`String`) — 产品类型中文标签（CORE=核心产品, CUSTOM=私人定制, GROUP=小蒙马, ROUTE=路书产品） - - 🆕 `pendingUpgradeAmount` (`BigDecimal`) — 待确认差价总额（配房/配车升级未确认的差价） - - 🆕 `paymentModeLabel` (`String`) — 支付模式中文标签（DEPOSIT=定金+尾款, FULL=全款） - - 🆕 `hotelAssignmentDetails` (`List<HotelAssignmentVO>`) — 酒店分配详情（按家庭分组，含封面图） - - ✏️ `hotelAssignments`: 说明 "酒店分配信息JSON" → "酒店分配信息JSON（原始数据）" - -#### 🆕 SurchargeRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `surchargeName` | `String` | 费用增加项名称 | -| `surchargeAmount` | `BigDecimal` | 费用增加金额 | - -#### ✏️ VehicleAssignmentRequest - - - ✏️ `vehicleBrand`: 说明 "品牌" → "品牌（选填，不传则从车型名称中提取）" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-contract-service/src/main/java/com/hulalv/contract/config/ContractPlatformProperties.java -M hl-contract-service/src/main/java/com/hulalv/contract/constant/ContractConstants.java -M hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java -A hl-contract-service/src/main/java/com/hulalv/contract/controller/AdminContractSchemeController.java -A hl-contract-service/src/main/java/com/hulalv/contract/dto/ContractSchemeRequest.java -A hl-contract-service/src/main/java/com/hulalv/contract/entity/ContractScheme.java -M hl-contract-service/src/main/java/com/hulalv/contract/feign/OrderContractFeignClient.java -A hl-contract-service/src/main/java/com/hulalv/contract/job/ContractStatusRefreshJob.java -A hl-contract-service/src/main/java/com/hulalv/contract/mapper/ContractSchemeMapper.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/ContractApplyParam.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/ContractPlatform.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaContractPlatform.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/tourage/TourageApiClient.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/tourage/TourageContractPlatform.java -A hl-contract-service/src/main/java/com/hulalv/contract/service/ContractSchemeService.java -M hl-contract-service/src/main/java/com/hulalv/contract/service/ContractService.java -A hl-contract-service/src/main/java/com/hulalv/contract/vo/ContractSchemeVO.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/ContractPlatformFactoryTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaContractPlatformTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/tourage/TourageContractPlatformTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java -A hl-order-service/src/main/java/com/hulalv/order/dto/SurchargeRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/VehicleAssignmentRequest.java -A hl-order-service/src/main/java/com/hulalv/order/entity/OrderSurcharge.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderTimeline.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderTodo.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderTraveler.java -M hl-order-service/src/main/java/com/hulalv/order/job/DepartureReminderJob.java -A hl-order-service/src/main/java/com/hulalv/order/mapper/OrderSurchargeMapper.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderItineraryEditService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderPriceDiffService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -A hl-order-service/src/main/java/com/hulalv/order/service/OrderSurchargeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -A hl-order-service/src/main/java/com/hulalv/order/vo/HotelAssignmentVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -A hl-product-service/src/main/java/com/hulalv/product/feign/InsuranceSchemeFallbackFactory.java -A hl-product-service/src/main/java/com/hulalv/product/feign/InsuranceSchemeFeignClient.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-23_1833_6ab08e4_fix_11.md b/changelogs/2026-03/2026-03-23_1833_6ab08e4_fix_11.md deleted file mode 100644 index f9b9d71..0000000 --- a/changelogs/2026-03/2026-03-23_1833_6ab08e4_fix_11.md +++ /dev/null @@ -1,118 +0,0 @@ -# 接口变更记录 — 2026-03-23 18:33 - -> **提交** `6ab08e4` · **作者** wx · **时间** 2026-03-23 18:33:21 +0800 -> -> fix: 订单模块业务逻辑审查修复（11项） - -## 变更总览 - -- **订单服务** - - InternalRefund (+1) - ---- - -## 订单服务 - -### InternalRefund - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】退款（Feign调用）」** - -### 🆕 `POST` /internal/mp/order/{orderId}/direct-appeal — 直接申诉退款 - -> 用户对退款政策计算的金额不满意，跳过退款申请直接发起申诉。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**请求体** `RefundAppealRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `appealReason` | `String` | 申诉原因 | -| `appealAmount` | `BigDecimal` | 申诉退款金额 | - -**响应** `Result<RefundApplicationVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `applicationId` | `Long` | 申请ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单号 | -| `productName` | `String` | 产品名称 | -| `refundType` | `String` | 退款类型（字典：refund_type） | -| `reasonId` | `Long` | 退款原因ID | -| `reasonText` | `String` | 退款原因 | -| `reasonDetail` | `String` | 补充说明 | -| `paidAmount` | `BigDecimal` | 已付金额 | -| `calculatedAmount` | `BigDecimal` | 计算退款金额 | -| `actualAmount` | `BigDecimal` | 实际退款金额 | -| `policyId` | `Long` | 退款政策ID | -| `policyName` | `String` | 退款政策名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `daysBeforeDept` | `Integer` | 距出发天数 | -| `refundRatio` | `Integer` | 退款比例（百分比） | -| `status` | `String` | 退款状态（字典：refund_status） | -| `statusLabel` | `String` | 退款状态标签（字典：refund_status 翻译） | -| `reviewAdminId` | `Long` | 审批管理员ID | -| `reviewAdminName` | `String` | 审批管理员姓名 | -| `reviewRemark` | `String` | 审批备注 | -| `reviewedAt` | `LocalDateTime` | 审批时间 | -| `appealReason` | `String` | 申诉原因 | -| `appealAmount` | `BigDecimal` | 申诉退款金额 | -| `approvalNo` | `String` | 审批编号 | -| `appealStatus` | `Integer` | 申诉状态: 1-处理中 2-通过 3-驳回 | -| `appealStatusLabel` | `String` | 申诉状态标签 | -| `appealedAt` | `LocalDateTime` | 申诉时间 | -| `refundedAt` | `LocalDateTime` | 退款完成时间 | -| `refundTypeLabel` | `String` | 退款类型标签（字典：refund_type 翻译） | -| `applicantType` | `String` | 申请人类型（USER/ADMIN） | -| `applicantId` | `Long` | 申请人ID | -| `applicantName` | `String` | 申请人姓名 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 订单服务 - -#### ✏️ MpOrderListVO - - - 🆕 `refundAmount` (`BigDecimal`) — 实际退款金额 - -#### ✏️ OrderDetailVO - - - 🆕 `mchName` (`String`) — 商户名称 - - 🆕 `refundPolicy` (`RefundPolicyVO`) — 退款政策（含政策名称和退款规则列表） - -#### ✏️ OrderListVO - - - 🆕 `mchName` (`String`) — 商户名称 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RefundApplyRequest.java -M hl-order-service/src/main/java/com/hulalv/order/job/DepartureReminderJob.java -M hl-order-service/src/main/java/com/hulalv/order/service/NotificationEventHelper.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -M hl-order-service/src/test/java/com/hulalv/order/constant/OrderConstantsTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderTodoServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundApplicationServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-23_1902_8b444a8_fix.md b/changelogs/2026-03/2026-03-23_1902_8b444a8_fix.md deleted file mode 100644 index ba2e0a5..0000000 --- a/changelogs/2026-03/2026-03-23_1902_8b444a8_fix.md +++ /dev/null @@ -1,139 +0,0 @@ -# 接口变更记录 — 2026-03-23 19:02 - -> **提交** `8b444a8` · **作者** wx · **时间** 2026-03-23 19:02:42 +0800 -> -> fix: 退款金额显示+操作记录详细化+直接申诉+申诉金额校验 - -## 变更总览 - -- **保险服务** - - InternalInsurance (+1) -- **小程序聚合服务** - - MpRefund (+1) - ---- - -## 保险服务 - -### InternalInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「【内部接口】保险（Feign调用）」** - -### 🆕 `GET` /internal/insurance/coverage/{orderId} — 查询订单保险保障(含被保人详情,内部调用) - -> 内部服务间调用。返回订单维度的保险保障汇总信息，包含每份保单的被保人明细。用于小程序端按出行人展示保险信息。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<InsuranceCoverageVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅行订单ID | -| `orderCount` | `Integer` | 保险单数量 | -| `insuranceOrders` | `List<InsuranceOrderDetailVO>` | 保险订单详情列表(含被保人) | - ---- - -## 小程序聚合服务 - -### MpRefund - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 退款接口」** - -### 🆕 `POST` /mp/order/refund/{orderId}/direct-appeal — 直接申诉退款 - -> 用户对退款政策计算的金额不满意，跳过退款申请直接发起申诉。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**请求体** `MpRefundAppealRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `appealReason` | `String` | 申诉原因 | -| `appealAmount` | `BigDecimal` | 申诉退款金额 | -| `evidence` | `List<String>` | 申诉凭证图片URL列表 | - -**响应** `Result<MpRefundDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `applicationId` | `Long` | 退款申请ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单号 | -| `productName` | `String` | 产品名称 | -| `refundType` | `String` | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -| `refundTypeLabel` | `String` | 退款类型中文标签 | -| `reasonId` | `Long` | 退款原因ID | -| `reasonText` | `String` | 退款原因 | -| `reasonDetail` | `String` | 补充说明 | -| `paidAmount` | `BigDecimal` | 已付金额 | -| `calculatedAmount` | `BigDecimal` | 计算退款金额 | -| `actualAmount` | `BigDecimal` | 实际退款金额（审核后确定） | -| `policyId` | `Long` | 退款政策ID | -| `policyName` | `String` | 退款政策名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `daysBeforeDept` | `Integer` | 距出发天数 | -| `refundRatio` | `Integer` | 退款比例（百分比） | -| `status` | `String` | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -| `statusLabel` | `String` | 退款状态中文标签 | -| `reviewAdminId` | `Long` | 审批管理员ID | -| `reviewAdminName` | `String` | 审批管理员姓名 | -| `reviewRemark` | `String` | 审批备注 | -| `reviewedAt` | `LocalDateTime` | 审批时间 | -| `appealReason` | `String` | 申诉原因 | -| `appealAmount` | `BigDecimal` | 申诉退款金额 | -| `approvalNo` | `String` | 审批编号（企微OA审批编号） | -| `appealStatus` | `Integer` | 申诉状态: 1-处理中, 2-通过, 3-驳回 | -| `autoRefundDeadline` | `LocalDateTime` | 自动退款截止时间 | -| `appealStatusLabel` | `String` | 申诉状态中文标签 | -| `appealedAt` | `LocalDateTime` | 申诉时间 | -| `refundedAt` | `LocalDateTime` | 退款完成时间 | -| `applicantType` | `String` | 申请人类型: USER(用户)/ADMIN(管理员) | -| `applicantId` | `Long` | 申请人ID | -| `applicantName` | `String` | 申请人姓名 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpOrderDetailVO - - - 🆕 `refundPolicy` (`Map<String, Object>`) — 退款政策（含政策名称和退款规则列表） - -#### ✏️ MpOrderListItemVO - - - 🆕 `refundAmount` (`BigDecimal`) — 实际退款金额 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpRefundAppealRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderListItemVO.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderTraveler.java -M hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderPriceDiffService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-payment-service/src/main/java/com/hulalv/payment/constant/PaymentConstants.java -M hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-23_1918_a8ff0a3_security.md b/changelogs/2026-03/2026-03-23_1918_a8ff0a3_security.md deleted file mode 100644 index 164428f..0000000 --- a/changelogs/2026-03/2026-03-23_1918_a8ff0a3_security.md +++ /dev/null @@ -1,50 +0,0 @@ -# 接口变更记录 — 2026-03-23 19:18 - -> **提交** `a8ff0a3` · **作者** wx · **时间** 2026-03-23 19:18:30 +0800 -> -> security: 新增代码安全审计修复（10项） - -## 变更总览 - -- **小程序聚合服务** - - MpInsurance (+1) - ---- - -## 小程序聚合服务 - -### MpInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 保险接口」** - -### 🆕 `GET` /mp/insurance/policy/{insuranceOrderId}/download — 下载单张保单PDF - -> 根据保险订单ID下载单张保单PDF，返回Base64编码。 - -**参数** - - - `{insuranceOrderId}` (`Long`) — 路径参数：保险订单ID - -**响应** `Result<String>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpInsuranceController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpRefundAppealRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpInsuranceFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpInsuranceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/HotelAssignmentRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RefundAppealRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/VehicleAssignmentRequest.java -M hl-order-service/src/main/java/com/hulalv/order/job/DepartureReminderJob.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-23_2042_896c7a9_feat_UR.md b/changelogs/2026-03/2026-03-23_2042_896c7a9_feat_UR.md deleted file mode 100644 index 8f4f357..0000000 --- a/changelogs/2026-03/2026-03-23_2042_896c7a9_feat_UR.md +++ /dev/null @@ -1,36 +0,0 @@ -# 接口变更记录 — 2026-03-23 20:42 - -> **提交** `896c7a9` · **作者** wx · **时间** 2026-03-23 20:42:44 +0800 -> -> feat: 管理端文件预览接口（通过URL） - -## 变更总览 - -- **文件服务** - - File (+1) - ---- - -## 文件服务 - -### File - -> 📖 **接口文档**: [http://192.168.100.236:8091/doc.html](http://192.168.100.236:8091/doc.html) → 标签 **「文件管理」** - -### 🆕 `GET` /admin/file/preview-by-url — 通过URL预览文件 - -> 传入完整的OSS文件URL，流式输出原始文件内容（与/{fileId}/preview效果一致）。 - -**响应** `void` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-file-service/src/main/java/com/hulalv/file/config/WebMvcConfig.java -M hl-file-service/src/main/java/com/hulalv/file/controller/FileController.java -M hl-gateway/src/main/java/com/hulalv/gateway/filter/JwtAuthFilter.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-23_2307_4773ed2_fix_agencyCode.md b/changelogs/2026-03/2026-03-23_2307_4773ed2_fix_agencyCode.md deleted file mode 100644 index b641be9..0000000 --- a/changelogs/2026-03/2026-03-23_2307_4773ed2_fix_agencyCode.md +++ /dev/null @@ -1,45 +0,0 @@ -# 接口变更记录 — 2026-03-23 23:07 - -> **提交** `4773ed2` · **作者** wx · **时间** 2026-03-23 23:07:20 +0800 -> -> fix: 自动签约agencyCode空值修复 + 行程列表状态补全 + 安全审计修复（6项） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 合同服务 - -#### ✏️ CreateContractRequest - - - 🆕 `mchId` (`String`) — 微信支付商户号（用于自动匹配旅行社） - - ✏️ `agencyCode`: 说明 "旅行社编号（可选，默认使用配置值）" → "旅行社编号（可选，不传则按商户号匹配，仍无则用默认值）" - -#### ✏️ ReportContractRequest - - - 🆕 `mchId` (`String`) — 微信支付商户号（用于自动匹配旅行社） - - ✏️ `agencyCode`: 说明 "旅行社编号" → "旅行社编号（可选，不传则按商户号匹配，仍无则用默认值）" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-common/src/main/java/com/hulalv/common/aspect/OperationLogAspect.java -M hl-contract-service/src/main/java/com/hulalv/contract/config/WebMvcConfig.java -M hl-contract-service/src/main/java/com/hulalv/contract/dto/CreateContractRequest.java -M hl-contract-service/src/main/java/com/hulalv/contract/dto/ReportContractRequest.java -M hl-contract-service/src/main/java/com/hulalv/contract/platform/tourage/TourageContractPlatform.java -M hl-contract-service/src/main/java/com/hulalv/contract/service/ContractSchemeService.java -M hl-contract-service/src/main/java/com/hulalv/contract/service/ContractService.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/tourage/TourageContractPlatformTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -M hl-file-service/src/main/java/com/hulalv/file/service/FileService.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/config/WebMvcConfig.java -M hl-monitor-service/src/main/java/com/hulalv/monitor/config/WebMvcConfig.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -M hl-task-service/src/main/java/com/hulalv/task/config/WebMvcConfig.java -M hl-transport-service/src/main/java/com/hulalv/transport/config/WebMvcConfig.java -M hl-user-service/src/main/java/com/hulalv/user/config/WebMvcConfig.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-23_admin_file_preview.md b/changelogs/2026-03/2026-03-23_admin_file_preview.md deleted file mode 100644 index acb85e6..0000000 --- a/changelogs/2026-03/2026-03-23_admin_file_preview.md +++ /dev/null @@ -1,47 +0,0 @@ -# 管理端文件预览接口使用说明 - -**日期**: 2026-03-23 - ---- - -## 接口 - -``` -GET /admin/file/preview-by-url?url=编码后的完整OSS_URL -``` - -**无需登录**（已排除认证） - -## 正确使用方式 - -**这个接口返回的是 HTML 页面，不是 JSON。前端不能用 fetch/axios 调用。** - -### 方式1：新窗口打开（推荐） -```javascript -const previewUrl = `/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`; -window.open(previewUrl, '_blank'); -``` - -### 方式2：iframe 嵌入 -```html -<iframe :src="`/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`" - width="100%" height="600px" /> -``` - -### 方式3：弹窗内 iframe -```javascript -// 弹窗打开时设置 iframe src -dialogVisible.value = true; -iframeSrc.value = `/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`; -``` - -## 支持的文件类型 -- PDF：内嵌 PDF.js 渲染 -- 图片：直接 img 标签显示 -- Office 文档：跳转在线预览服务 - -## 如果需要原始二进制流（img src 等场景） -``` -GET /admin/file/stream-by-url?url=编码后的URL -``` -返回原始文件内容，适合 `<img src="">` 或 `<video src="">` 直接引用。 diff --git a/changelogs/2026-03/2026-03-23_admin_file_preview_v2.md b/changelogs/2026-03/2026-03-23_admin_file_preview_v2.md deleted file mode 100644 index ac7021d..0000000 --- a/changelogs/2026-03/2026-03-23_admin_file_preview_v2.md +++ /dev/null @@ -1,37 +0,0 @@ -# 管理端文件预览接口（更新） - -**日期**: 2026-03-23 -**类型**: 接口更新 - ---- - -## 接口 - -``` -GET /admin/file/preview-by-url?url=编码后的完整OSS_URL -``` - -**无需登录，无需 token。** - -## 返回内容 - -直接返回**原始文件二进制流**（与 `/{fileId}/preview` 一致）： -- PDF → Content-Type: application/pdf -- 图片 → Content-Type: image/jpeg 等 -- 其他 → 对应 MIME 类型 - -## 前端使用 - -```javascript -// iframe 嵌入（推荐，PDF和图片都能直接显示） -<iframe :src="`/api/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`" - width="100%" height="600px" /> - -// 或新窗口打开 -window.open(`/api/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`) - -// 或 img 标签（仅图片） -<img :src="`/api/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`" /> -``` - -**注意**：url 参数必须 `encodeURIComponent` 编码。 diff --git a/changelogs/2026-03/2026-03-23_balance_button_fix_urgent.md b/changelogs/2026-03/2026-03-23_balance_button_fix_urgent.md deleted file mode 100644 index 1abb51d..0000000 --- a/changelogs/2026-03/2026-03-23_balance_button_fix_urgent.md +++ /dev/null @@ -1,35 +0,0 @@ -# 【紧急】尾款凭证按钮不显示 - 条件需更新 - -**日期**: 2026-03-23 -**页面**: 订单详情页 -**类型**: 前端修复 - ---- - -## 问题 - -尾款凭证按钮不显示。原因：后端状态流转已改，定金模式清单确认后订单状态是 `PENDING_BALANCE`（不再是 `CONFIRMED`），但前端还在用旧条件判断。 - -## 修复 - -把当前条件： - -```js -// ❌ 旧条件（不再适用） -o.paymentMode === 'DEPOSIT' && - ((o.status === 'CONFIRMED' && o.processStatus === 'READY') || - o.status === 'PENDING_DEPARTURE') -``` - -改为： - -```js -// ✅ 新条件 -o.paymentMode === 'DEPOSIT' && - !o.balanceProofUrl && - ['PENDING_BALANCE', 'PENDING_DEPARTURE', 'TRAVELLING'].includes(o.status) -``` - -## 测试订单 - -`HL202603222254548349`，当前状态 `PENDING_BALANCE`，改完条件后应能看到按钮。 diff --git a/changelogs/2026-03/2026-03-23_balance_proof_button_condition.md b/changelogs/2026-03/2026-03-23_balance_proof_button_condition.md deleted file mode 100644 index 3eba263..0000000 --- a/changelogs/2026-03/2026-03-23_balance_proof_button_condition.md +++ /dev/null @@ -1,85 +0,0 @@ -# 尾款凭证上传功能（后端已完成，前端需实现） - -**日期**: 2026-03-23 -**页面**: 订单详情页 -**类型**: 新功能 - ---- - -## 后端改了什么 - -定金模式订单，清单确认完成后，订单状态不再直接跳到 `PENDING_DEPARTURE`（待出行），而是先进入 **`PENDING_BALANCE`（待付尾款）**，上传凭证/记录尾款后才转为 `PENDING_DEPARTURE`。 - -状态流转变化： -``` -旧：CONFIRMED(READY) ──记录尾款──→ PENDING_DEPARTURE -新：CONFIRMED(READY) ──清单确认──→ PENDING_BALANCE ──记录尾款──→ PENDING_DEPARTURE -``` - -## 前端需要实现 - -### 1. 显示"上传尾款凭证"按钮 - -显示条件： -```js -const showBalanceProofBtn = - order.paymentType === 'DEPOSIT' - && !order.balanceProofUrl - && ['PENDING_BALANCE', 'PENDING_DEPARTURE', 'TRAVELLING'].includes(order.status); -``` - -建议放在订单详情页**金额明细区域**的"尾款"行旁边，或作为顶部操作按钮。 - -### 2. 点击按钮弹窗 - -弹窗内容： -| UI元素 | 说明 | -|--------|------| -| 标题 | "记录尾款收取" | -| 尾款金额（只读展示） | 从订单详情取 `balanceAmount` 字段，格式 ¥xxxx.xx | -| 上传凭证（图片上传） | 调用文件上传接口获取 OSS URL，非必填 | -| 备注（文本框） | 最多500字，非必填 | -| 确认按钮 | 调用记录尾款接口 | - -### 3. 已上传凭证展示 - -当 `order.balanceProofUrl` 有值时，在尾款金额旁显示凭证图片（可点击放大查看）。 - -## 接口定义 - -### 记录尾款 - -``` -PUT /admin/order/{orderId}/record-balance -``` - -请求体（JSON）： -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| proofUrl | String | 否 | 支付凭证图片URL（先通过文件上传接口上传到OSS，把返回的URL传这里） | -| remark | String | 否 | 备注，最多500字 | - -成功响应： -```json -{ "code": 200, "message": "success", "data": null } -``` - -调用成功后刷新订单详情（状态会从 `PENDING_BALANCE` 变为 `PENDING_DEPARTURE`）。 - -### 订单详情中相关字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| status | String | 订单状态，`PENDING_BALANCE` = 待付尾款 | -| paymentType | String | 支付模式，`DEPOSIT` = 定金+尾款 | -| balanceProofUrl | String | 尾款凭证URL，null表示未上传 | -| balanceAmount | BigDecimal | 尾款金额（后端已计算好） | -| balancePayMethod | String | 尾款支付方式：`ONLINE`=线上微信支付，`OFFLINE`=线下转账 | - -## 状态中文标签 - -| status | 中文标签 | -|--------|---------| -| `PENDING_BALANCE` | 待付尾款 | -| `PENDING_DEPARTURE` | 待出行 | -| `TRAVELLING` | 出行中 | diff --git a/changelogs/2026-03/2026-03-23_balance_proof_display.md b/changelogs/2026-03/2026-03-23_balance_proof_display.md deleted file mode 100644 index 334a07e..0000000 --- a/changelogs/2026-03/2026-03-23_balance_proof_display.md +++ /dev/null @@ -1,28 +0,0 @@ -# 订单详情展示尾款凭证 - -**日期**: 2026-03-23 -**页面**: 订单详情页 → 金额明细区域 -**类型**: 前端新增 - ---- - -## 说明 - -上传尾款凭证后，订单详情接口已返回 `balanceProofUrl` 字段，但前端没有展示。 - -## 后端已返回的字段 - -订单详情接口 `GET /admin/order/{orderId}` 响应中： - -| 字段 | 类型 | 说明 | -|------|------|------| -| balanceProofUrl | String | 尾款凭证图片URL，null=未上传 | -| balanceAmount | BigDecimal | 尾款金额 | -| balancePayMethod | String | 尾款支付方式：ONLINE / OFFLINE | - -## 前端展示建议 - -在金额明细区域的"尾款"行： - -- **凭证未上传**（`balanceProofUrl` 为 null）：显示尾款金额 + 上传按钮（条件见之前的 changelog） -- **凭证已上传**（`balanceProofUrl` 有值）：尾款金额旁显示"凭证"链接或缩略图，点击可放大查看图片 diff --git a/changelogs/2026-03/2026-03-23_balance_proof_optional.md b/changelogs/2026-03/2026-03-23_balance_proof_optional.md deleted file mode 100644 index ef38f55..0000000 --- a/changelogs/2026-03/2026-03-23_balance_proof_optional.md +++ /dev/null @@ -1,27 +0,0 @@ -# 尾款凭证图片应为选填 - -**日期**: 2026-03-23 -**页面**: 订单详情 → 尾款收取 -**类型**: 前端 BUG - ---- - -## 问题 - -"确认收到尾款"按钮要求必须上传凭证图片才能提交，但后端 `proofUrl` 是选填字段。 - -## 后端接口 - -``` -PUT /admin/order/{orderId}/record-balance -{ - "proofUrl": "https://...", // 选填：凭证图片URL - "remark": "客户微信转账" // 选填：备注 -} -``` - -两个字段都是选填。请求体可以为空 `{}`，也可以只传 remark。 - -## 前端修复 - -去掉凭证图片的必填校验，允许不上传图片直接确认收款。 diff --git a/changelogs/2026-03/2026-03-23_checklist_lock_ui.md b/changelogs/2026-03/2026-03-23_checklist_lock_ui.md deleted file mode 100644 index 58768d2..0000000 --- a/changelogs/2026-03/2026-03-23_checklist_lock_ui.md +++ /dev/null @@ -1,45 +0,0 @@ -# 已锁单订单禁止编辑（前端需处理） - -**日期**: 2026-03-23 20:00 -**紧急程度**: 高 - ---- - -## 问题 - -当 `checklistConfirmed = true`（已锁单）时，管理端仍能打开编辑面板尝试修改订单，后端会拒绝但体验不好。 - -## 前端需要做 - -当订单详情返回 `checklistConfirmed = true` 时： - -1. **隐藏/禁用**以下按钮： - - 编辑订单 - - 配房（编辑） - - 配车（编辑） - - 优惠管理 - - 附加费管理 - - 更换定制师 - -2. **显示"申请修改"按钮**（已有）：点击弹出输入解锁原因 → 调用 `POST /admin/order/{orderId}/request-unlock` - -3. **锁单标识**：`processStatusLabel` 字段会返回 **"已锁单"**（仅当 checklistConfirmed=true 时） - -## 判断逻辑 - -```javascript -const isLocked = orderDetail.checklistConfirmed === true - -if (isLocked) { - // 隐藏编辑按钮，显示"申请修改"按钮 -} else { - // 正常显示编辑按钮 -} -``` - -## 后端保障 - -即使前端未做禁用，后端所有编辑接口都会检查锁单状态，返回： -```json -{ "code": 400, "message": "订单已锁定（确认清单已完成），如需修改请先申请解锁" } -``` diff --git a/changelogs/2026-03/2026-03-23_chinese_labels.md b/changelogs/2026-03/2026-03-23_chinese_labels.md deleted file mode 100644 index f359c6a..0000000 --- a/changelogs/2026-03/2026-03-23_chinese_labels.md +++ /dev/null @@ -1,32 +0,0 @@ -# 【BUG】订单详情页英文枚举值需要中文显示 - -## 问题 -订单详情 API 返回了大量英文枚举值，页面直接显示英文。以下是需要处理的字段： - -## 后端会修复（补充 xxxLabel 字段） - -### 已有 Label 但值是英文的（后端 bug） -| 字段 | 当前值 | 应该显示 | -|------|--------|---------| -| timeline[].actionLabel | `CHECKLIST_CONFIRMED` | 确认清单 | -| timeline[].actionLabel | `EDIT_CONFIRMED` | 确认修改 | -| timeline[].actionLabel | `TODO_COMPLETED` | 待办完成 | -| timeline[].actionLabel | `PAYMENT_SUCCESS` | 支付成功 | -| timeline[].actionLabel | `ROOM_UPGRADE` | 房型升级 | - -### 缺少 Label 字段（后端会补充） -| 字段 | 示例值 | 中文 | 新增Label字段 | -|------|--------|------|-------------| -| productType | CORE | 核心产品 | productTypeLabel | -| paymentMode | DEPOSIT | 定金+尾款 | paymentModeLabel | -| todos[].todoType | INSURANCE | 投保 | todoTypeLabel | -| todos[].status | PENDING | 待处理 | - (前端已有) | -| todos[].assigneeRoleKey | CUSTOMIZER | 定制师 | assigneeRoleLabel | -| travelers[].idCardType | ID_CARD | 身份证 | idCardTypeLabel | -| travelers[].travelerType | ADULT | 成人 | travelerTypeLabel | -| timeline[].operatorType | ADMIN/USER/SYSTEM | 管理员/用户/系统 | operatorTypeLabel | -| contracts[].contractType | TOUR | 旅游合同 | contractTypeLabel | -| contracts[].mode | STANDARD | 电子签约 | modeLabel | - -## 前端处理建议 -优先使用 `xxxLabel` 字段显示，如果没有 label 字段，前端做本地映射。后端会尽快补充所有缺失的 label。 diff --git a/changelogs/2026-03/2026-03-23_contract_button_rules.md b/changelogs/2026-03/2026-03-23_contract_button_rules.md deleted file mode 100644 index a574194..0000000 --- a/changelogs/2026-03/2026-03-23_contract_button_rules.md +++ /dev/null @@ -1,16 +0,0 @@ -# 【BUG】合同操作按钮显示规则 - -## 现象 -已签署、作废中状态的合同没有"刷新状态"按钮，无法从12301平台同步最新状态。 - -## 正确的按钮显示规则 - -| 状态 | 刷新状态 | 重发短信 | 作废 | -|------|---------|---------|------| -| GENERATED（已生成） | ✅ | ✅ | ✅ | -| SIGNING（签署中） | ✅ | ✅ | ✅ | -| SIGNED（已签署） | ✅ | ❌ | ✅（需确认） | -| VOIDING（作废中） | ✅ | ❌ | ❌ | -| VOIDED（已作废） | ❌ | ❌ | ❌ | - -**简单规则：除了 VOIDED（已作废），都显示"刷新状态"按钮。** diff --git a/changelogs/2026-03/2026-03-23_contract_scheme_bug.md b/changelogs/2026-03/2026-03-23_contract_scheme_bug.md deleted file mode 100644 index e7091c9..0000000 --- a/changelogs/2026-03/2026-03-23_contract_scheme_bug.md +++ /dev/null @@ -1,57 +0,0 @@ -# 【BUG】合同方案选择弹窗 + 小程序补全信息 - -## 1. 合同方案选择弹窗 — 值绑定问题 - -**现象**：订单详情 → 手动签署 → 选择合同方案弹窗，下拉框显示了"全国旅游监管平台"，但仍然报红"请选择合同方案"，无法提交。 - -**原因**：下拉框 `v-model` 绑定的 value 可能是空值或类型不匹配。 - -**排查重点**： -- `GET /admin/contract/scheme/list` 返回的 schemeId 是 **字符串**（如 `"3"`），不是数字 -- 下拉选项的 value 必须用 `item.schemeId`（字符串），不要用 `Number(item.schemeId)` -- 表单校验 rules 如果用了 `type: 'number'`，改为 `type: 'string'` - -**接口返回示例**： -```json -{ - "code": 200, - "data": [ - { - "schemeId": "1", - "name": "标准电子签约方案（博华测试）冬季小团", - "contractPlatform": "12301", - "contractMode": "STANDARD", - "status": "ACTIVE" - }, - { - "schemeId": "3", - "name": "全国旅游监管平台", - "contractPlatform": "12301", - "contractMode": "STANDARD", - "agencyCode": "hulai", - "status": "ACTIVE" - } - ] -} -``` - -**注意**：`schemeId` 是字符串类型（Long序列化为String），El-Select 的 value 绑定要对应字符串。 - ---- - -## 2. 小程序补全信息 — 不应阻塞 - -**现象**：小程序用户补全出行人信息时偶现"服务不可用"。 - -**说明**： -- 补全出行人调用 `PUT /mp/order/{orderId}/edit`，这个接口只做数据保存 -- 保险投保和合同签约是**后端异步执行**的（`@Async`），不会阻塞补全请求 -- 如果前端在补全后**同步**调用了保险或合同相关接口，可能导致超时 -- **正确做法**：补全信息后只等 editOrder 返回，保险/合同状态通过订单详情的 `processStatus` 轮询即可 - -**processStatus 流转**： -``` -PENDING_INFO（待补全）→ PENDING_INSURANCE（投保中）→ PENDING_CONTRACT（签约中）→ PENDING_VEHICLE（待派车） -``` - -补全成功后 processStatus 会从 `PENDING_INFO` 变为 `PENDING_INSURANCE`，之后自动推进。前端只需轮询订单详情看 processStatus 变化。 diff --git a/changelogs/2026-03/2026-03-23_contract_scheme_clause_echo.md b/changelogs/2026-03/2026-03-23_contract_scheme_clause_echo.md deleted file mode 100644 index 7a95d75..0000000 --- a/changelogs/2026-03/2026-03-23_contract_scheme_clause_echo.md +++ /dev/null @@ -1,18 +0,0 @@ -# 【BUG】合同方案编辑 - 补充条款下拉没回显 - -## 现象 - -编辑合同方案时，补充条款的下拉选择（如"夏季小团"、"冬季小团"）切换后，下方的文本区域内容没有正确回显/联动。 - -## 排查建议 - -补充条款下拉是前端本地维护的预设模板，切换时需要同步更新 `supplementaryClause` 文本框的值。 - -`GET /admin/contract/scheme/{schemeId}` 返回的 `supplementaryClause` 是纯文本，不包含下拉选项标识。前端需要自己根据内容匹配到预设模板，或者加一个额外字段标记当前选中的模板。 - -## 后端接口说明 - -合同方案的 `supplementaryClause` 字段就是纯文本，保存什么内容合同就用什么内容。后端不区分"夏季"、"冬季"模板。 - -- **保存方案**：`PUT /admin/contract/scheme/{schemeId}`，请求体中 `supplementaryClause` 传入最终文本 -- **创建合同**：`POST /admin/contract/create-by-scheme`，自动使用方案中的 `supplementaryClause` diff --git a/changelogs/2026-03/2026-03-23_create_by_scheme.md b/changelogs/2026-03/2026-03-23_create_by_scheme.md deleted file mode 100644 index 41ad108..0000000 --- a/changelogs/2026-03/2026-03-23_create_by_scheme.md +++ /dev/null @@ -1,62 +0,0 @@ -# 合同创建简化接口 + agency 级别凭证 - -## 功能说明 - -### 1. 新增简化合同创建接口（重要） -前端只需传 `orderId` 和 `schemeId`，后端自动从订单获取出行人、日期、联系人、费用等信息，结合合同方案配置完成合同创建。 - -**替代原来的 `/admin/contract/create`**（需要传几十个字段），新接口大幅简化前端工作量。 - -### 2. STANDARD 模式支持旅行社独立凭证 -每家旅行社现在使用自己的 appId/signKey 调用 12301 API，不再共用全局测试凭证。 - ---- - -## 接口定义 - -### 按方案创建合同（简化版） - -- **POST** `/admin/contract/create-by-scheme` -- **请求体**： -```json -{ - "orderId": "2035929978981564417", - "schemeId": "3" -} -``` -- **参数说明**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | String | 是 | 订单ID | -| schemeId | String | 是 | 合同方案ID（从 `GET /admin/contract/scheme/list` 获取） | - -- **响应**：`Result<ContractDetailVO>`（与 `/admin/contract/create` 完全一致） - -### 后端自动填充的数据 - -| 数据 | 来源 | -|------|------| -| 出行人列表 | 订单出行人 | -| 出发日期/返回日期 | 订单 | -| 联系人姓名/电话 | 订单 | -| 合同金额 | 订单总价 | -| 线路名称 | 产品名称 | -| 签署人 | 第一个有手机号的出行人 | -| 模板编码/签署模式/旅行社/争议解决/补充条款 | 合同方案 | - -### 使用流程 - -``` -1. GET /admin/contract/scheme/list → 获取可用方案列表（下拉用） -2. 用户选择一个方案 -3. POST /admin/contract/create-by-scheme → { orderId, schemeId } -4. 合同创建完成，返回合同详情 -``` - -### 注意事项 - -- 根据方案的 `contractMode` 自动选择标准签约(STANDARD)或线下报备(SYNC) -- 如果订单已有有效合同，会报错"该订单已有有效电子合同" -- 出行人必须已补全，否则报错 -- `schemeId` 是字符串类型（Long 序列化），El-Select value 要对应字符串 diff --git a/changelogs/2026-03/2026-03-23_direct_appeal_api.md b/changelogs/2026-03/2026-03-23_direct_appeal_api.md deleted file mode 100644 index a6f5678..0000000 --- a/changelogs/2026-03/2026-03-23_direct_appeal_api.md +++ /dev/null @@ -1,66 +0,0 @@ -# 新增：直接申诉退款接口 - -**日期**: 2026-03-23 -**模块**: C端退款 - ---- - -## 业务场景 - -用户查看退款预览 → 对系统计算的退款金额不满意 → 跳过退款申请，直接发起申诉填写期望金额。 - -## 新接口 - -### 直接申诉退款 -``` -POST /mp/order/refund/{orderId}/direct-appeal -``` - -**请求体**： -```json -{ - "appealReason": "退款金额不合理，要求全额退款", // 必填 - "appealAmount": 5700.00, // 必填，期望退款金额（不能超过已付金额） - "evidence": ["https://oss.../proof1.jpg"] // 选填，凭证图片列表（最多9张） -} -``` - -**响应**：返回退款申请详情（状态为 APPEALING） - -**校验规则**： -- `appealAmount` 必填，必须 > 0，**不能超过已付金额** -- 订单必须在可退款状态（DEPOSIT_PAID/PAID/CONFIRMED/PENDING_BALANCE/PENDING_DEPARTURE） -- 不能重复提交（已有进行中的退款申请时拒绝） - -## 退款流程（完整） - -``` -用户操作退款 → 查看退款预览（GET /mp/order/refund/{orderId}/refund-preview） - ├── 满意 → 提交退款申请（POST /mp/order/refund/{orderId}/refund） → 等待审批 - └── 不满意 → 直接申诉（POST /mp/order/refund/{orderId}/direct-appeal） → 企微OA审批 -``` - -## 页面交互建议 - -退款预览页底部： -``` -┌────────────────────────────────┐ -│ 系统计算退款金额: ¥3,000.00 │ -│ 退款比例: 60%（出发前3天） │ -│ │ -│ [申请退款] [不满意？直接申诉] │ -└────────────────────────────────┘ -``` - -点击"直接申诉" → 弹窗/页面填写期望金额+申诉原因+上传凭证 → 提交 - -## 已有接口（无变化） - -- `GET /mp/order/refund/{orderId}/refund-preview` — 退款金额预览 -- `POST /mp/order/refund/{orderId}/refund` — 提交退款申请 -- `POST /mp/order/refund/refund/{applicationId}/appeal` — 退款被拒后申诉 -- `GET /mp/order/refund/{orderId}/refund-detail` — 退款详情 - -## MpRefundAppealRequest 字段更新 - -`appealAmount` 已改为**必填**（之前文档缺失，现已补充） diff --git a/changelogs/2026-03/2026-03-23_hotel_upgrade_price_bug.md b/changelogs/2026-03/2026-03-23_hotel_upgrade_price_bug.md deleted file mode 100644 index 04d20bd..0000000 --- a/changelogs/2026-03/2026-03-23_hotel_upgrade_price_bug.md +++ /dev/null @@ -1,39 +0,0 @@ -# 【BUG】配房差价确认弹窗的差价值没传到后端 - -## 现象 -配房差价确认弹窗中管理员修改了差价（如改为100），但提交后后端使用的是系统计算值（-380），管理员手动修改的值没有生效。 - -## 原因 -`PUT /admin/order/{orderId}/hotel-assignment` 请求体中，每个 assignment 的 `upgradePrice` 字段没有传值（为 null），导致后端使用系统自动计算的差价。 - -## 修复方式 -配房差价确认弹窗中，用户修改的差价值需要设置到对应 assignment 的 `upgradePrice` 字段中。 - -### 请求体示例 -```json -{ - "assignments": [ - { - "hotelId": "2029926129876320258", - "hotelName": "海拉尔嘉世豪酒店", - "roomTypeId": "2029944763138936834", - "roomType": "豪华大床房", - "date": "2026-03-27", - "familyIndex": 1, - "upgradePrice": 100.00 - }, - { - "hotelId": "2029926129876320258", - "roomTypeId": "2029944763138936833", - "roomType": "标准间", - "date": "2026-03-24", - "familyIndex": 1, - "upgradePrice": null - } - ] -} -``` - -- `upgradePrice` 有值：使用管理员指定的差价 -- `upgradePrice` 为 null：使用系统计算的差价（新房型价格 - 原房型价格） -- 只有房型与产品默认不同的天才需要设置 diff --git a/changelogs/2026-03/2026-03-23_insurance_card_group_by_policy.md b/changelogs/2026-03/2026-03-23_insurance_card_group_by_policy.md deleted file mode 100644 index b3e0413..0000000 --- a/changelogs/2026-03/2026-03-23_insurance_card_group_by_policy.md +++ /dev/null @@ -1,53 +0,0 @@ -# 保险保障区域：按保单合并展示，不要按被保人拆卡片 - -**日期**: 2026-03-23 -**页面**: 订单详情 → 保险保障 -**类型**: 前端 BUG - ---- - -## 问题 - -当前每个被保人显示为一个独立的保单卡片。2个保险方案 × 2个被保人 = 4张卡片，实际应该只有2张。 - -## 正确的展示 - -每个**保单**（`InsuranceOrderDetailVO`）显示为一张卡片，卡片内列出所有被保人。 - -后端返回的数据结构： -```json -[ - { - "insuranceOrderId": 123, - "productName": "保游未来星研学旅行保险", - "planName": "30万计划", - "totalPremium": 2, - "startDate": "2026-03-26", - "endDate": "2026-03-28", - "status": "INSURED", - "insuredPersons": [ - { "name": "王五", "idCardNo": "6230****9779" }, - { "name": "王骁", "idCardNo": "1521****5216" } - ] - }, - { - "insuranceOrderId": 456, - "productName": "保游未来星研学旅行保险", - "planName": "20万计划", - "totalPremium": 1.5, - "startDate": "2026-03-23", - "endDate": "2026-03-25", - "status": "INSURED", - "insuredPersons": [ - { "name": "王五", "idCardNo": "6230****9779" }, - { "name": "王骁", "idCardNo": "1521****5216" } - ] - } -] -``` - -## 修复 - -遍历保险列表时，以 `insuranceOrderId` 为维度渲染卡片，每张卡片内用 `v-for` 遍历 `insuredPersons` 列出所有被保人。 - -**不要**以被保人为维度遍历渲染卡片。 diff --git a/changelogs/2026-03/2026-03-23_insurance_pdf_api.md b/changelogs/2026-03/2026-03-23_insurance_pdf_api.md deleted file mode 100644 index bb585c0..0000000 --- a/changelogs/2026-03/2026-03-23_insurance_pdf_api.md +++ /dev/null @@ -1,102 +0,0 @@ -# 保单PDF完整URL（OSS直链） - -**日期**: 2026-03-23 19:40 -**影响**: 管理端 + 小程序端 -**已部署**: 测试服务器 ✅ - ---- - -## 核心变更：保单现在有完整的 `.pdf` OSS链接 - -每份保险保单投保成功后，系统自动下载PDF并上传到OSS，保存为 `policyPdfUrl` 字段。 - -**URL示例**: `https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/insurance/policy/2026/03/23/policy_2036026235003478018.pdf` - -前端直接用这个URL打开/下载PDF即可，**不需要调Base64接口**。 - ---- - -## 管理端 - -### 保险保障接口（已有） -``` -GET /admin/insurance/coverage/{orderId} -``` - -返回的 `insuranceOrders[]` 每条新增 `policyPdfUrl` 字段： - -```json -{ - "insuranceOrders": [ - { - "insuranceOrderId": "2036026309016166401", - "productName": "保游未来星研学旅行保险", - "planName": "30万计划", - "extPolicyNo": "11209006600506820271", - "startDate": "2026-04-03", - "endDate": "2026-04-05", - "status": "INSURED", - "policyPdfUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/insurance/policy/2026/03/23/policy_2036026309016166401.pdf" - } - ] -} -``` - -### 前端展示建议 -在每个保险卡片上加 **"查看保单"** 按钮： -```javascript -window.open(item.policyPdfUrl) // 直接打开PDF -``` - ---- - -## 小程序端 - -### 订单详情出行人保险数据 - -订单详情 `travelers[].insurancePolicies[]` 每条包含： - -| 字段 | 类型 | 说明 | -|------|------|------| -| insuranceOrderId | String | 保险订单ID | -| productName | String | 保险产品名称 | -| planName | String | 保险计划名称 | -| extPolicyNo | String | 保单号 | -| startDate | String | 保障开始日期 | -| endDate | String | 保障结束日期 | -| status | String | INSURED=已承保, CANCELLED=已退保 | -| statusLabel | String | 中文状态 | -| totalPremium | String | 保费 | -| **policyPdfUrl** | **String** | **保单PDF的OSS完整链接（.pdf结尾，直接可访问）** | -| policyPdfApi | String | 备用：Base64下载接口路径 | - -### 小程序展示建议 - -出行人信息下方展示保单卡片，点击"查看保单"用 `wx.downloadFile` + `wx.openDocument`： - -```javascript -wx.downloadFile({ - url: item.policyPdfUrl, - success(res) { - wx.openDocument({ filePath: res.tempFilePath, fileType: 'pdf' }) - } -}) -``` - -### 一个出行人多份保单 - -一个出行人可能有多份保单（覆盖不同日期段），`insurancePolicies` 是数组，按保障期间展示即可： - -``` -米明光 -├── 保游未来星研学旅行保险 20万计划 -│ 保障期间：2026-03-31 ~ 2026-04-02 [查看保单] -└── 保游未来星研学旅行保险 30万计划 - 保障期间：2026-04-03 ~ 2026-04-05 [查看保单] -``` - ---- - -## 旧数据 - -所有历史保单的PDF已补传完成，`policyPdfUrl` 已全部填充。 diff --git a/changelogs/2026-03/2026-03-23_order_fixes_batch2.md b/changelogs/2026-03/2026-03-23_order_fixes_batch2.md deleted file mode 100644 index 00b71b7..0000000 --- a/changelogs/2026-03/2026-03-23_order_fixes_batch2.md +++ /dev/null @@ -1,140 +0,0 @@ -# 订单功能修复与增强（第二批） - -**日期**: 2026-03-23 18:50 -**影响服务**: hl-order-service, hl-insurance-service, hl-user-service, hl-payment-service -**已部署**: 测试服务器 ✅ - ---- - -## 1. 出行人保险保单展示（新功能） - -订单详情接口的 `travelers` 数组中，每个出行人新增 `insurancePolicies` 字段，包含该出行人的所有保险保单。一个人多份保单会合并在数组中。 - -### 数据结构 - -```json -{ - "travelers": [ - { - "name": "米明光", - "insurancePolicies": [ - { - "insuranceOrderId": "2035907623051735042", - "productName": "畅游神州境内游（旅行社专享）", - "planName": "经济版", - "extPolicyNo": "11209006600506819432", - "startDate": "2026-03-24", - "endDate": "2026-03-26", - "status": "INSURED", - "statusLabel": "已承保", - "totalPremium": "1.50" - }, - { - "insuranceOrderId": "2035907674989801474", - "productName": "畅游神州境内游（旅行社专享）", - "planName": "经济版", - "extPolicyNo": "11209006600506819433", - "startDate": "2026-03-27", - "endDate": "2026-03-29", - "status": "INSURED", - "statusLabel": "已承保", - "totalPremium": "2.00" - } - ] - } - ] -} -``` - -### insurancePolicies 字段说明 - -| 字段 | 类型 | 说明 | -|------|------|------| -| insuranceOrderId | String | 保险订单ID | -| productName | String | 保险产品名称 | -| planName | String | 保险计划名称 | -| extPolicyNo | String | 保单号 | -| startDate | String | 保障开始日期 | -| endDate | String | 保障结束日期 | -| status | String | 状态：INSURED=已承保, CANCELLED=已退保 | -| statusLabel | String | 状态中文标签 | -| totalPremium | String | 保费金额 | - -### 前端展示建议 - -小程序出行人信息区域，每个人下面展示其保单卡片： -- 保障期间：2026-03-24 ~ 2026-03-26 -- 保单号：11209006600506819432 -- 状态：已承保 -- 多份保单纵向排列 - ---- - -## 2. 订单内部状态"已锁单" - -`processStatus = PENDING_FINANCE` 的标签从"待核算"改为 **"已锁单"**。 - -字典 `order_process_status` 中 `PENDING_FINANCE` 的 `dict_label` 已同步更新。 - ---- - -## 3. 商户号显示公司全名 - -订单详情新增 `mchName` 字段，返回商户公司全名： - -| mchId | mchName | -|-------|---------| -| 1106110439 | 内蒙古呼籁国际旅行社有限公司 | -| 1246532201 | 内蒙古呼籁山河国际旅行社有限公司 | -| 1684769133 | 内蒙古呼籁文旅投资开发集团有限公司 | - -**前端需改**：商户号选择器和订单详情展示用 `mchName` 代替 `mchId`。 - ---- - -## 4. 退款类型校验修复 - -小程序退定金报错已修复。`refundType` 现在支持： -- `FULL` - 全额退款 -- `PARTIAL` - 部分退款 -- `DEPOSIT` - 退定金 -- `BALANCE` - 退尾款 - ---- - -## 5. 退款金额为0直接完成 - -退款审批通过但金额为0时，不再调微信退款接口（微信不支持退0元），直接标记为"已退款"。 - ---- - -## 6. 已锁单订单用户修改出行人自动解锁 - -已锁单（清单确认后）的订单，如果用户在小程序修改了出行人或出发日期： -- 自动解锁订单 -- 触发级联（退保+作废合同） -- 重走内部流程（重新投保→签约→配房→配车→确认清单→锁单） - ---- - -## 7. 解锁申请通知（短信+站内消息） - -管理员调用 `POST /admin/order/{orderId}/request-unlock` 申请修改时，系统自动： -- 发站内消息给用户 -- 发短信提醒用户确认 - -用户在小程序确认后调用 `POST /internal/mp/order/{orderId}/approve-unlock` 完成解锁。 - ---- - -## 8. 定制师列表只展示有企微的 - -`GET /admin/order/todo/customizer-list` 现在只返回绑定了企业微信的定制师。 - -**前端需改**：下拉展示用 `wechatName` 字段（企微姓名），提交用 `adminId`。 - ---- - -## 9. 尾款支付方式默认线下转账 - -新创建的订单 `balancePayMethod` 默认为 `OFFLINE`（线下转账），无需手动设置。 diff --git a/changelogs/2026-03/2026-03-23_pdf_preview_frontend_fix.md b/changelogs/2026-03/2026-03-23_pdf_preview_frontend_fix.md deleted file mode 100644 index 7b8ffc3..0000000 --- a/changelogs/2026-03/2026-03-23_pdf_preview_frontend_fix.md +++ /dev/null @@ -1,49 +0,0 @@ -# 保单PDF预览"暂不支持在线预览"— 前端渲染问题 - -**日期**: 2026-03-23 -**类型**: 前端 BUG - ---- - -## 问题 - -保单 PDF 预览弹窗显示"该文件类型暂不支持在线预览"，但后端已正确返回 539KB 的 PDF 二进制流。 - -## 对比 - -| 场景 | 接口 | 大小 | 结果 | -|------|------|------|------| -| 素材PDF（能预览） | `/{fileId}/preview` | 1815KB | ✅ PDF预览组件正常渲染 | -| 保单PDF（不能预览） | `/preview-by-url?url=` | 539KB | ❌ 显示"暂不支持" | - -两个接口返回的都是 PDF 二进制流（Content-Type: application/pdf），后端没区别。 - -## 原因 - -前端对 `/{fileId}/preview` 用了 PDF 预览组件（如 pdf.js），但对 `preview-by-url` 没有走相同的渲染逻辑。 - -## 修复方式（任选一种） - -### 方式1：iframe 直接显示（最简单） -```javascript -// 弹窗内用 iframe，浏览器原生支持 PDF 渲染 -<iframe - :src="`/api/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`" - width="100%" - height="600px" - style="border: none;" -/> -``` - -### 方式2：复用现有 PDF 预览组件 -```javascript -// 把 preview-by-url 的 URL 当作 pdf src 传给已有的 PDF 预览组件 -const pdfSrc = `/api/admin/file/preview-by-url?url=${encodeURIComponent(ossUrl)}`; -// 传给 pdf-preview 组件，和 /{fileId}/preview 一样处理 -``` - -### 方式3：直接用 OSS URL -保单 PDF 存在公开读的 OSS 上，也可以直接用 OSS URL： -```javascript -<iframe :src="ossUrl" width="100%" height="600px" /> -``` diff --git a/changelogs/2026-03/2026-03-23_pending_upgrade_amount.md b/changelogs/2026-03/2026-03-23_pending_upgrade_amount.md deleted file mode 100644 index b334e9d..0000000 --- a/changelogs/2026-03/2026-03-23_pending_upgrade_amount.md +++ /dev/null @@ -1,28 +0,0 @@ -# 配房差价不再立即计入总售价 + 新增待确认差价字段 - -## 变更说明 - -### 1. 配房升级差价不再立即修改总售价 -之前配房时如果有房型升级差价，会立即加到订单 `totalPrice` 中。现在改为： -- 差价记录创建为 `PENDING_CONFIRM` 状态 -- **不修改 totalPrice** -- 等定制师确认后再正式计入 - -### 2. 订单详情新增 `pendingUpgradeAmount` 字段 -订单详情接口返回新增字段，用于前端展示待确认的差价总额。 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `pendingUpgradeAmount` | BigDecimal | 待确认差价总额（null=无待确认差价） | - -### 前端展示建议 -在金额明细区域，如果 `pendingUpgradeAmount` 不为 null 且不为 0： -``` -总售价：¥5700.00 -待确认差价：+¥100.00（未确认） ← 新增，用橙色/黄色标识 -已付：¥0.01 -尾款：¥5699.99 -``` - -### 3. 配房超时问题已修复 -之前配房时确认差价弹窗提交后会卡住超时（MySQL锁冲突），已修复。 diff --git a/changelogs/2026-03/2026-03-23_scheme_agency_echo.md b/changelogs/2026-03/2026-03-23_scheme_agency_echo.md deleted file mode 100644 index dd24517..0000000 --- a/changelogs/2026-03/2026-03-23_scheme_agency_echo.md +++ /dev/null @@ -1,22 +0,0 @@ -# 【BUG】合同方案编辑 - 旅行社字段未回显 - -## 现象 -编辑合同方案时，旅行社下拉框显示"不填则根据支付商户号自动匹配"（placeholder），没有回显已保存的 agencyCode 值。保存后 agencyCode 被清空导致 500 错误。 - -## 后端已修复 -更新方案时如果 agencyCode 未传值，保留原值不覆盖（不再报 500）。 - -## 前端需修复 -编辑合同方案时，旅行社下拉框应回显 `agencyCode` 和 `agencyName` 字段。 - -`GET /admin/contract/scheme/{schemeId}` 返回示例： -```json -{ - "schemeId": "3", - "agencyCode": "hulai", - "agencyName": "内蒙古呼籁国际旅行社有限公司", - ... -} -``` - -旅行社选项列表从 `GET /admin/contract/agencies` 获取，用 `code` 匹配回显。 diff --git a/changelogs/2026-03/2026-03-23_three_frontend_issues.md b/changelogs/2026-03/2026-03-23_three_frontend_issues.md deleted file mode 100644 index b94aed2..0000000 --- a/changelogs/2026-03/2026-03-23_three_frontend_issues.md +++ /dev/null @@ -1,69 +0,0 @@ -# 三个前端展示问题 - -**日期**: 2026-03-23 - ---- - -## 1. 操作记录需要显示时间 - -**页面**: 订单详情 → 操作记录 -**问题**: 操作记录列表没有显示时间 - -后端每条 timeline 记录都有 `createTime` 字段（格式：`2026-03-23 10:33:20`），前端需要展示出来。 - -建议格式： -``` -系统自动投保成功 -system · 系统 · 2026-03-23 10:33 -``` - -## 2. 交通信息保存接口 - -**页面**: 订单详情 → 交通信息 -**接口已就绪**，无需后端改动。 - -### 保存交通信息 -``` -PUT /admin/order/{orderId}/transport -{ - "segments": [ - { - "transportType": "FLIGHT", // 必填：FLIGHT=航班, TRAIN=火车 - "transportNo": "CA1234", // 航班号/车次号 - "departStation": "北京首都T3", // 出发站 - "arriveStation": "海拉尔东山", // 到达站 - "departTime": "2026-03-24T08:00:00", // 出发时间 - "arriveTime": "2026-03-24T11:30:00", // 到达时间 - "remark": "去程", // 备注 - "sortOrder": 1 // 排序 - } - ] -} -``` - -### 查询交通信息 -``` -GET /admin/order/{orderId}/transport -``` - -### 关联字典 -`transport_type`：FLIGHT=航班, TRAIN=火车 - -### 注意 -- 每次保存是**全量替换**（先删后增），前端需要把所有交通段都传回去 -- 时间字段用 ISO 8601 格式（`yyyy-MM-ddTHH:mm:ss`） - -## 3. 保险状态显示错误 - -**页面**: 订单详情 → 保险保障 -**问题**: 保险实际状态是"已承保"(INSURED)，前端显示"已退保" - -请检查前端是否正确读取了 `insurances[].status` 字段并用 `statusLabel` 显示。后端返回的数据： -```json -{ - "status": "INSURED", - "statusLabel": "已承保" -} -``` - -直接用 `statusLabel` 字段显示即可。 diff --git a/changelogs/2026-03/2026-03-23_timeline_seconds.md b/changelogs/2026-03/2026-03-23_timeline_seconds.md deleted file mode 100644 index aaa3d8f..0000000 --- a/changelogs/2026-03/2026-03-23_timeline_seconds.md +++ /dev/null @@ -1,15 +0,0 @@ -# 操作记录时间显示精确到秒 - -**日期**: 2026-03-23 20:00 - ---- - -## 问题 - -订单详情的操作记录（时间线）时间只显示到分钟（如 `2026-03-23 19:53`），同一分钟内多条记录无法区分先后顺序。 - -## 前端需改 - -时间线的 `createTime` 格式化从 `YYYY-MM-DD HH:mm` 改为 **`YYYY-MM-DD HH:mm:ss`**。 - -后端返回的时间已精确到秒（如 `2026-03-23 19:53:12`），前端只需调整格式化即可。 diff --git a/changelogs/2026-03/2026-03-23_todo_cascade_fix.md b/changelogs/2026-03/2026-03-23_todo_cascade_fix.md deleted file mode 100644 index c43e630..0000000 --- a/changelogs/2026-03/2026-03-23_todo_cascade_fix.md +++ /dev/null @@ -1,78 +0,0 @@ -# 待办显示修复 + 定制师列表 + 尾款默认值 - -**日期**: 2026-03-23 16:35 -**影响服务**: hl-order-service, hl-user-service -**已部署**: 测试服务器 ✅ - ---- - -## 1. 行程编辑确认不再触发全面重置（BUG修复） - -**问题**: 确认房型升级等行程编辑时，错误触发了全面级联重置（退保险、作废合同、清除配房配车、重置所有待办），导致待办显示不对。 - -**修复后行为**: -- **房型升级/行程编辑确认** → 只回退到待配房，保留保险和合同，保留已有配房配车数据 -- **出行人变更** → 退保险+作废合同，重置到待配保险 -- **出发日期变更** → 全面重置（退保+作废+清房车+清住宿） - -**前端无需改动**，待办接口返回数据自动正确。 - ---- - -## 2. 更换定制师列表：只展示有企微的定制师 - -**接口**: `GET /admin/order/todo/customizer-list` - -**变更**: 现在只返回绑定了企业微信的定制师（过滤掉没有企微的管理员账号）。 - -**前端需改**: 下拉列表展示请用 `wechatName` 字段（企微姓名），不要用 `adminId`。 - -### 返回字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| adminId | Long | 管理员ID（提交时传这个） | -| username | String | 用户名 | -| avatarUrl | String | 头像 | -| **wechatName** | **String** | **企微姓名（下拉展示用这个）** | -| wechatUserid | String | 企微用户ID | - -### 下拉展示建议 - -``` -侯玉凤（定制师） -米明光（定制师） -... -``` - -用 `wechatName` 展示，选中后提交 `adminId`。 - ---- - -## 3. 尾款支付方式默认线下转账 - -**变更**: 新创建的订单 `balancePayMethod` 默认值改为 `OFFLINE`（线下转账）。 - -**前端影响**: -- "设置尾款支付方式"弹窗可以改为只在需要切换为在线支付时才弹出 -- 或者直接按 `balancePayMethod` 字段回显当前值，默认已经是"线下转账" - ---- - -## 4. 申请修改（解锁）功能确认 - -后端已实现，接口如下： - -### 管理员申请解锁 -- **接口**: `POST /admin/order/{orderId}/request-unlock` -- **请求体**: `{ "reason": "解锁原因" }` -- **效果**: 发送通知给C端用户，等待用户确认 - -### C端用户同意解锁 -- **接口**: `POST /internal/mp/order/{orderId}/approve-unlock`（小程序端调用） -- **效果**: 订单解锁，管理员可重新编辑 - -### 前端需要做 -1. 点击"提交申请"调用 `request-unlock` 接口 -2. 小程序端收到通知后展示确认弹窗，用户同意后调用 `approve-unlock` -3. 管理员端刷新后可以继续编辑 diff --git a/changelogs/2026-03/2026-03-23_vehicle_assignment_display.md b/changelogs/2026-03/2026-03-23_vehicle_assignment_display.md deleted file mode 100644 index 640d8db..0000000 --- a/changelogs/2026-03/2026-03-23_vehicle_assignment_display.md +++ /dev/null @@ -1,35 +0,0 @@ -# 配车数据保存成功但编辑弹窗未回显 - -**日期**: 2026-03-23 -**页面**: 订单详情 → 配车信息 → 编辑弹窗 -**类型**: 前端 BUG - ---- - -## 问题 - -配车保存成功后，车辆安排区域显示了司机和电话，但"车型"和"车牌号"显示为 `-`。打开编辑弹窗时所有字段为空，没有回填已保存的数据。 - -## 后端确认 - -订单详情接口返回的 `vehicleInfo` 字段包含完整数据（JSON字符串）： - -```json -{ - "vehicleModel": "小蒙马车（5座）", - "vehicleBrand": null, - "plateNumber": "4444", - "driverName": "4", - "driverPhone": "44" -} -``` - -## 前端需要修复 - -1. **车辆安排区域**：从 `vehicleInfo` 解析显示车型和车牌号（当前只显示了司机和电话） -2. **编辑弹窗打开时**：读取 `vehicleInfo` 回填所有字段（车型下拉选中、车牌号、司机姓名、司机电话、备注） -3. **注意**：`vehicleInfo` 是 JSON 字符串，需要 `JSON.parse()` 后使用 - -## vehicleBrand 已改为选填 - -之前 `vehicleBrand`（品牌）是必填，已改为选填。前端不传也不会报错。 diff --git a/changelogs/2026-03/2026-03-23_vehicle_select_display_fix.md b/changelogs/2026-03/2026-03-23_vehicle_select_display_fix.md deleted file mode 100644 index 6dbdcd8..0000000 --- a/changelogs/2026-03/2026-03-23_vehicle_select_display_fix.md +++ /dev/null @@ -1,36 +0,0 @@ -# 配车弹窗车型下拉回显为ID，应显示名称 - -**日期**: 2026-03-23 -**页面**: 订单详情 → 配车信息 → 编辑弹窗 -**类型**: 前端 BUG - ---- - -## 问题 - -配车编辑弹窗打开后，"选择车型"下拉框显示的是车型ID（如 `2028150422439420000`），不是车型名称。 - -## 原因 - -后端 `vehicleInfo.vehicleModel` 存的是**车型名称**（如"小蒙马车"），不是车型ID。 - -当前后端返回的 `vehicleInfo` 格式： -```json -{ - "vehicleModel": "小蒙马车", - "vehicleBrand": "", - "plateNumber": null, - "driverName": "4", - "driverPhone": "44" -} -``` - -## 前端修复 - -编辑弹窗回填车型时，应该用 `vehicleInfo.vehicleModel`（名称）去匹配车型列表，找到对应的选项选中。 - -不要直接把 `vehicleModel` 当作ID绑定到 `el-select` 的 `v-model`。 - -两种修法： -1. 如果下拉框 value 绑的是 ID：打开弹窗时用名称从车型列表中查找对应的 ID，再设给 v-model -2. 如果下拉框 value 可以改为名称：直接用 `vehicleModel` 名称作为 value diff --git a/changelogs/2026-03/2026-03-24_1434_50e2536_refactor.md b/changelogs/2026-03/2026-03-24_1434_50e2536_refactor.md deleted file mode 100644 index dad5d7f..0000000 --- a/changelogs/2026-03/2026-03-24_1434_50e2536_refactor.md +++ /dev/null @@ -1,266 +0,0 @@ -# 接口变更记录 — 2026-03-24 14:34 - -> **提交** `50e2536` · **作者** wx · **时间** 2026-03-24 14:34:21 +0800 -> -> refactor: 资源管理去除草稿状态，只保留上架/下架二态 - -## 变更总览 - -### ⚠️ 一句话：所有资源模块的 status 字段，去掉「草稿」，只剩「上架/下架」 - -| 原来 | 现在 | -|------|------| -| 0 = 草稿 | 0 = **下架** | -| 1 = 上架 | 1 = 上架（不变） | -| 2 = 下架 | **删除，不再使用** | - -### 前端要改的地方 - -1. **状态筛选下拉框**：去掉「草稿」选项，只留「下架(0)」和「上架(1)」 -2. **状态标签显示**：`status=0` 原来显示「草稿」→ 现在显示「**下架**」 -3. **删掉 status=2 的逻辑**：如果代码里有处理 `status=2` 的地方，直接删 -4. **上下架按钮传值**：只传 `0`（下架）或 `1`（上架），不再传 `2` - -### 涉及的资源模块（全部9个，改法一样） - -景区、游玩项目、酒店（含房型）、车辆、额外服务、人员、餐厅、额外费用、备品 - -### 补充说明 - -数据库里实际从来没有 status=2 的数据，之前代码也只用 0 和 1。这次只是把 API 文档统一了。**不需要做数据迁移。** - ---- - -## 📦 其他数据对象变更（自动生成的 diff 详情） - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ ActivityListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ActivityQueryRequest - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ActivityStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ ActivityVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ApprovalSubmitRequest - - - ✏️ `targetStatus`: 说明 "目标状态：1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ CostItemListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ CostItemQueryRequest - - - ✏️ `status`: 说明 "状态筛选：0=草稿 1=上架 2=下架" → "状态筛选：0=下架 1=上架" - -#### ✏️ CostItemVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ HotelListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ HotelQueryRequest - - - ✏️ `status`: 说明 "状态筛选：0=草稿 1=上架 2=下架" → "状态筛选：0=下架 1=上架" - -#### ✏️ HotelStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ HotelVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ RestaurantListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ RestaurantQueryRequest - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ RestaurantStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ RestaurantUpdateRequest - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ RestaurantVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ RoomTypeStatusRequest - - - ✏️ `status`: 说明 "状态：0=禁用 1=启用" → "状态：0=下架 1=上架" - -#### ✏️ RoomTypeVO - - - ✏️ `status`: 说明 "状态：0=禁用 1=启用" → "状态：0=下架 1=上架" - -#### ✏️ ScenicSpotListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ScenicSpotQueryRequest - - - ✏️ `status`: 说明 "状态筛选：0=草稿 1=上架 2=下架" → "状态筛选：0=下架 1=上架" - -#### ✏️ ScenicSpotUpdateRequest - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ScenicSpotVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ScenicStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ ServiceItemListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ServiceItemVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ ServiceQueryRequest - - - ✏️ `status`: 说明 "状态筛选：0=草稿 1=上架 2=下架" → "状态筛选：0=下架 1=上架" - -#### ✏️ ServiceStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ StaffListVO - - - ✏️ `status`: 说明 "状态：0=禁用 1=启用" → "状态：0=下架 1=上架" - -#### ✏️ StaffQueryRequest - - - ✏️ `status`: 说明 "状态筛选：0=禁用 1=启用" → "状态筛选：0=下架 1=上架" - -#### ✏️ StaffStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ StaffVO - - - ✏️ `status`: 说明 "状态：0=禁用 1=启用" → "状态：0=下架 1=上架" - -#### ✏️ SuppliesListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ SuppliesQueryRequest - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ SuppliesStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -#### ✏️ SuppliesUpdateRequest - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ SuppliesVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ VehicleModelListVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ VehicleModelVO - - - ✏️ `status`: 说明 "状态：0=草稿 1=上架 2=下架" → "状态：0=下架 1=上架" - -#### ✏️ VehicleQueryRequest - - - ✏️ `status`: 说明 "状态筛选：0=草稿 1=上架 2=下架" → "状态筛选：0=下架 1=上架" - -#### ✏️ VehicleStatusRequest - - - ✏️ `status`: 说明 "目标状态：0=草稿 1=上架 2=下架" → "目标状态：0=下架 1=上架" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ApprovalSubmitRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/dto/CostItemQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/vo/CostItemListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/vo/CostItemVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/RoomTypeController.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/ApprovalSubmitRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/RoomTypeStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/HotelListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/HotelVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/RoomTypeVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/controller/RestaurantController.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/ApprovalSubmitRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/RestaurantUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/vo/RestaurantVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/controller/ScenicSpotController.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ApprovalSubmitRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicSpotCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicSpotQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicSpotUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/ScenicStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/vo/ScenicSpotListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/vo/ScenicSpotVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/controller/ServiceItemController.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/ApprovalSubmitRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/ServiceQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/ServiceStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/vo/ServiceItemListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/vo/ServiceItemVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/vo/StaffListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/vo/StaffVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/controller/SuppliesController.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/ApprovalSubmitRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/SuppliesQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/SuppliesStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/SuppliesUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/vo/SuppliesListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/vo/SuppliesVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/controller/VehicleModelController.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleStatusRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/vo/VehicleModelListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/vo/VehicleModelVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-24_1554_f794175_fix.md b/changelogs/2026-03/2026-03-24_1554_f794175_fix.md deleted file mode 100644 index aa0f364..0000000 --- a/changelogs/2026-03/2026-03-24_1554_f794175_fix.md +++ /dev/null @@ -1,79 +0,0 @@ -# 接口变更记录 — 2026-03-24 15:54 - -> **提交** `f794175` · **作者** wx · **时间** 2026-03-24 15:54:33 +0800 -> -> fix: 保险服务余额查询超时优化 + 充值接口废弃标记 - -## 变更总览 - -- **保险服务** - - AdminInsurance (+1, 名1) - - InternalInsurance (+2) - ---- - -## 保险服务 - -### AdminInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「保险管理」** - -### 🆕 `POST` /admin/insurance/upload-missing-pdfs — 补传旧保单PDF到OSS - -> 将所有已承保但未上传PDF的保单，异步下载PDF并上传到OSS。用于历史数据迁移。 - -**响应** `Result<Integer>` - -### 接口名称更新 - -| 方法 | 路径 | 原名称 → 新名称 | -| --- | --- | --- | -| `GET` | `/admin/insurance/recharge-url` | 获取保游网充值链接(旧接口,保留兼容) → **获取保游网充值链接(已废弃)** | - -### InternalInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「【内部接口】保险（Feign调用）」** - -### 🆕 `GET` /internal/insurance/policy/{id}/download — 下载单张保单PDF(内部调用) - -> 内部服务间调用。从保游网下载指定保险订单的电子保单PDF，以Base64编码返回。 - -**参数** - - - `{insuranceOrderId}` (`Long`) — 路径参数：保险订单ID - -**响应** `Result<String>` - -### 🆕 `POST` /internal/insurance/upload-missing-pdfs — 补传旧保单PDF到OSS(内部调用) - -**响应** `Result<Integer>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 保险服务 - -#### ✏️ InsuranceOrderVO - - - 🆕 `policyPdfUrl` (`String`) — 保单PDF的OSS链接（.pdf结尾，可直接访问） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-insurance-service/pom.xml -M hl-insurance-service/src/main/java/com/hulalv/insurance/config/RestTemplateConfig.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/constant/InsuranceConstants.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/entity/InsuranceOrder.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/BaoyouApiClient.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/service/PolicyPdfUploadService.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/vo/InsuranceOrderVO.java -M hl-insurance-service/src/test/java/com/hulalv/insurance/service/BaoyouApiClientTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-24_1745_90d8f9f_feat_51.md b/changelogs/2026-03/2026-03-24_1745_90d8f9f_feat_51.md deleted file mode 100644 index c004426..0000000 --- a/changelogs/2026-03/2026-03-24_1745_90d8f9f_feat_51.md +++ /dev/null @@ -1,81 +0,0 @@ -# 接口变更记录 — 2026-03-24 17:45 - -> **提交** `90d8f9f` · **作者** wx · **时间** 2026-03-24 17:45:04 +0800 -> -> feat: 发票功能补全单元测试(51个) + 修复3个BUG - -## 变更总览 - -- **订单服务** - - InternalInvoice (+1) - - InternalOrderStats (-2) - ---- - -## 订单服务 - -### InternalInvoice - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序发票（Feign调用）」** - -### 🆕 `POST` /internal/mp/invoice/reissue — 发票换开 - -> 已开发票更换抬头信息（如个人改企业、更换公司名称等）。 - -**响应** `Result<InvoiceVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `String` | 发票ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单号 | -| `amount` | `String` | 金额 | -| `titleType` | `String` | 抬头类型（personal=个人/company=企业） | -| `invoiceTitle` | `String` | 发票抬头 | -| `taxNumber` | `String` | 税号 | -| `email` | `String` | 接收邮箱 | -| `invoiceType` | `String` | 发票类型 | -| `invoiceContent` | `String` | 发票内容 | -| `status` | `String` | 发票状态 | -| `fileUrl` | `String` | 发票文件URL | -| `failReason` | `String` | 失败原因 | -| `contactPhone` | `String` | 联系电话 | -| `remark` | `String` | 备注信息 | -| `bankName` | `String` | 开户行（企业发票） | -| `bankAccount` | `String` | 银行账号（企业发票） | -| `companyAddress` | `String` | 企业地址（企业发票） | -| `companyPhone` | `String` | 企业电话（企业发票） | -| `invoiceNo` | `String` | 发票号码 | -| `issuedAt` | `LocalDateTime` | 开票时间 | -| `issuedBy` | `String` | 开票操作人ID | -| `userId` | `String` | 用户ID | -| `originalInvoiceId` | `String` | 原发票ID(换开时关联) | -| `reissueCount` | `Integer` | 换开次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -**关联字典** - -- `invoice_title_type`（抬头类型，请求/返回字段titleType）：PERSONAL=个人, COMPANY=企业 -- `invoice_status`（发票状态，返回字段status）：PENDING=待开票, ISSUED=已开票, FAILED=开票失败, VOIDED=已作废 - -### InternalOrderStats - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「内部-订单统计」** - -### ❌ ~~`GET` /internal/mp/order/internal/mp/order~~ - -### ❌ ~~`POST` /internal/mp/order/invoice/reissue — 发票换开~~ - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalInvoiceController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderStatsController.java -M hl-order-service/src/main/java/com/hulalv/order/service/InvoiceService.java -A hl-order-service/src/test/java/com/hulalv/order/service/InvoiceServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-24_insurance_recharge_upgrade.md b/changelogs/2026-03/2026-03-24_insurance_recharge_upgrade.md deleted file mode 100644 index e0cddde..0000000 --- a/changelogs/2026-03/2026-03-24_insurance_recharge_upgrade.md +++ /dev/null @@ -1,91 +0,0 @@ -# 保险模块：充值功能升级 + 余额查询优化 - -> 日期：2026-03-24 | 服务：hl-insurance-service | 提交：f794175 - ---- - -## 一、充值功能升级（前端必改） - -### 背景 -保游网充值网站 `www.51baoy.com/recharge` **已关闭**，原来的"充值"按钮（调用 `GET /recharge-url` 获取静态链接跳转）已无法使用。 - -后端已实现在线充值API，前端需要改为调用新接口。 - -### 旧接口（已废弃） -``` -GET /admin/insurance/recharge-url -``` -> 返回 null，不要再用 - -### 新接口 - -``` -POST /admin/insurance/recharge -Content-Type: application/json -``` - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| money | String | 是 | 充值金额（元），如 "100.00" | -| payType | Integer | 是 | 支付方式：**11**=支付宝扫码，**33**=微信扫码 | -| backUrl | String | 否 | 支付完成后回调地址（可选） | - -#### 请求示例 -```json -{ - "money": "500.00", - "payType": 11, - "backUrl": "" -} -``` - -#### 响应示例 -```json -{ - "code": 200, - "data": { - "payType": 11, - "payUrl": "https://...", - "formHtml": "<form>...</form>" - } -} -``` - -- `payType=11`（支付宝）：返回 `formHtml`，前端渲染为支付页面 -- `payType=33`（微信）：返回 `payUrl`，前端生成二维码展示 - -### 前端改动建议 - -**保险产品页面** `/insurance/products` 的"充值"按钮： - -1. 点击弹出充值弹窗（el-dialog） -2. 弹窗内容： - - 金额输入框（必填，数字） - - 支付方式选择（支付宝/微信，默认支付宝） -3. 确认后调用 `POST /admin/insurance/recharge` -4. 根据 payType 展示结果： - - 支付宝：新窗口打开 formHtml - - 微信：弹窗展示二维码（用 `qrcode` 库将 payUrl 转二维码） -5. 支付完成后刷新余额 - ---- - -## 二、余额查询优化（前端无需改动） - -| 优化项 | 之前 | 现在 | -|--------|------|------| -| 超时时间 | 最长65秒（token 60s + balance 5s） | 最长10秒（token 5s + balance 5s） | -| 缓存 | 无，每次进页面都调保游网 | Redis缓存5分钟 | -| 保游网故障时 | 前端卡死 | 快速返回 null，显示"--" | - -**前端无需改动**，接口响应格式不变。 - ---- - -## 三、保游网API认证故障（非我方问题） - -保游网测试环境 `testapi.51baoy.com` 的 `GetAccessToken` 接口返回500错误（ASP.NET内部异常），导致"同步产品"功能暂时不可用。 - -**这是保游网服务器问题**，已有的产品数据不受影响。客服电话：4001-882-892。 diff --git a/changelogs/2026-03/2026-03-24_traveler_gender_string.md b/changelogs/2026-03/2026-03-24_traveler_gender_string.md deleted file mode 100644 index 333ac4d..0000000 --- a/changelogs/2026-03/2026-03-24_traveler_gender_string.md +++ /dev/null @@ -1,70 +0,0 @@ -# 出行人性别字段类型变更：Integer → String（匹配字典） - -> 日期：2026-03-24 -> 影响范围：小程序出行人模块、订单出行人模块 -> 关联字典：`gender` - -## 变更说明 - -出行人相关接口的 `gender` 字段从 `Integer` 改为 `String`，与字典 `gender` 的 `dict_value` 保持一致。 - -**之前**：`gender` 返回 Integer（如 `1`），前端用字典匹配时类型不一致导致报错 -**现在**：`gender` 返回 String（如 `"1"`），可直接与字典 `dict_value` 匹配 - -## 字典值对照 - -| dict_value (String) | dict_label | 说明 | -|---------------------|------------|------| -| `"1"` | 男 | — | -| `"2"` | 女 | — | - -## 受影响接口 - -### 小程序 - 出行人接口 - -| 接口 | 方法 | 路径 | -|------|------|------| -| 添加出行人 | POST | `/mp/user/traveler` | -| 出行人列表 | GET | `/mp/user/traveler` | -| 出行人详情 | GET | `/mp/user/traveler/{id}` | -| 更新出行人 | PUT | `/mp/user/traveler/{id}` | - -**请求参数变更**： -```json -{ - "gender": "1" // 之前是 Integer 1，现在是 String "1" -} -``` - -**响应字段变更**： -```json -{ - "gender": "1" // 之前是 Integer 1，现在是 String "1" -} -``` - -### 订单 - 创建订单（出行人信息） - -| 接口 | 方法 | 路径 | -|------|------|------| -| 创建订单 | POST | `/mp/order` | - -**travelers 数组中的 gender 字段**： -```json -{ - "travelers": [ - { - "name": "张三", - "gender": "1", // String，不再是 Integer - "idCardType": "ID_CARD", - "idCardNo": "110101199001011234" - } - ] -} -``` - -## 前端适配要点 - -1. **提交时**：`gender` 传 String 类型（`"1"` 或 `"2"`），不要传 Integer -2. **展示时**：返回值已经是 String，可直接用字典 `dict_value` 匹配显示中文标签 -3. **编辑回显**：`gender` 是 String，选择器绑定值直接用即可，无需类型转换 diff --git a/changelogs/2026-03/2026-03-25_1054_7926905_feat.md b/changelogs/2026-03/2026-03-25_1054_7926905_feat.md deleted file mode 100644 index 0e92f37..0000000 --- a/changelogs/2026-03/2026-03-25_1054_7926905_feat.md +++ /dev/null @@ -1,43 +0,0 @@ -# 接口变更记录 — 2026-03-25 10:54 - -> **提交** `7926905` · **作者** wx · **时间** 2026-03-25 10:54:41 +0800 -> -> feat: 行程详情接口改造 — 集成相册、评价、进度统计 - -## 变更总览 - -- **评价服务** - - InternalReview (+1) - ---- - -## 评价服务 - -### InternalReview - -> 📖 **接口文档**: [http://192.168.100.236:8097/doc.html](http://192.168.100.236:8097/doc.html) → 标签 **「【内部接口】评价统计（Feign调用）」** - -### 🆕 `GET` /internal/review/order/{orderId}/summary — 订单评价摘要(行程详情用) - -> 返回订单的产品评价摘要信息，无评价返回null - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-order-service/src/main/java/com/hulalv/order/feign/ReviewFeignClient.java -A hl-order-service/src/main/java/com/hulalv/order/feign/ReviewFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -M hl-order-service/src/test/java/com/hulalv/order/service/TripServiceTest.java -M hl-review-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java -M hl-review-service/src/main/java/com/hulalv/review/service/ReviewService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1240_6d105cb_feat.md b/changelogs/2026-03/2026-03-25_1240_6d105cb_feat.md deleted file mode 100644 index 7aafc7c..0000000 --- a/changelogs/2026-03/2026-03-25_1240_6d105cb_feat.md +++ /dev/null @@ -1,131 +0,0 @@ -# 接口变更记录 — 2026-03-25 12:40 - -> **提交** `6d105cb` · **作者** wx · **时间** 2026-03-25 12:40:43 +0800 -> -> feat: 保险选择性投保 + 出行人线下投保备注 - -## 变更总览 - -- **保险服务** - - AdminInsurance (+4) - - InternalInsurance (+1) - ---- - -## 保险服务 - -### AdminInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「保险管理」** - -### 🆕 `POST` /admin/insurance/order/{orderId}/selective-purchase — 选择部分出行人投保 - -> 自动投保失败后，管理员可选择部分出行人手动在线投保（如排除不满1岁婴儿）。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<AutoPurchaseResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `boolean` | 是否全部成功 | -| `purchasedCount` | `int` | 成功投保段数 | -| `failedCount` | `int` | 失败段数 | -| `failureReason` | `String` | 失败原因（部分失败或全部失败时返回第一个错误） | - -### 🆕 `POST` /admin/insurance/order/{orderId}/traveler-note — 添加出行人保险备注 - -> 为不能在线投保的出行人添加备注（如不满1岁婴儿标记为线下投保）。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -### 🆕 `DELETE` /admin/insurance/order/{orderId}/traveler-note/{noteId} — 删除出行人保险备注 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - - `{noteId}` (`Long`) — 路径参数：备注ID - -**响应** `Result<Void>` - -### 🆕 `GET` /admin/insurance/order/{orderId}/traveler-coverage — 查询出行人保险覆盖状态 - -> 返回订单每个出行人的保险状态： - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -### InternalInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「【内部接口】保险（Feign调用）」** - -### 🆕 `GET` /internal/insurance/fully-covered/{orderId} — 检查保险是否全覆盖-含线下备注(内部调用) - -> 考虑在线保单+线下投保备注，判断是否所有出行人都有保险覆盖 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - - `travelerCount` (`int`) — 查询参数：出行人数 - -**响应** `Result<Boolean>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 保险服务 - -#### 🆕 SelectivePurchaseRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 保险方案ID | -| `travelerIds` | `List<Long>` | 要投保的出行人ID列表 | - -#### 🆕 TravelerCoverageVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `travelerId` | `String` | 出行人ID | -| `name` | `String` | 姓名 | -| `birthday` | `LocalDate` | 出生日期 | -| `age` | `Integer` | 年龄 | -| `travelerType` | `String` | 出行人类型：ADULT/CHILD | -| `coverageStatus` | `String` | 保险覆盖状态：ONLINE_INSURED=在线已投保, OFFLINE_NOTED=线下已备注, NOT_COVERED=未投保 | -| `policies` | `List<Map<String, Object>>` | 在线保单列表（coverageStatus=ONLINE_INSURED时有值） | -| `noteId` | `String` | 线下备注ID（coverageStatus=OFFLINE_NOTED时有值） | -| `noteType` | `String` | 线下备注类型 | -| `noteRemark` | `String` | 线下备注说明（coverageStatus=OFFLINE_NOTED时有值） | - -#### 🆕 TravelerNoteRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `travelerId` | `Long` | 出行人ID | -| `travelerName` | `String` | 出行人姓名 | -| `noteType` | `String` | 备注类型：OFFLINE=线下投保, SKIP=跳过, OTHER=其他 | -| `remark` | `String` | 备注说明 | - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/dto/SelectivePurchaseRequest.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/dto/TravelerNoteRequest.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/entity/InsuranceTravelerNote.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/mapper/InsuranceTravelerNoteMapper.java -M hl-insurance-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -A hl-insurance-service/src/main/java/com/hulalv/insurance/vo/TravelerCoverageVO.java -A sql/insurance_traveler_note.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1317_a299187_refactor_In.md b/changelogs/2026-03/2026-03-25_1317_a299187_refactor_In.md deleted file mode 100644 index a350057..0000000 --- a/changelogs/2026-03/2026-03-25_1317_a299187_refactor_In.md +++ /dev/null @@ -1,51 +0,0 @@ -# 接口变更记录 — 2026-03-25 13:17 - -> **提交** `a299187` · **作者** wx · **时间** 2026-03-25 13:17:49 +0800 -> -> refactor: 性别字段规范化 Integer→String（字典gender 1=男 2=女） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpTravelerRequest - - - ✏️ `gender`: 类型 `Integer` → `String` - -#### ✏️ MpTravelerVO - - - ✏️ `gender`: 类型 `Integer` → `String`, 说明 "性别: 1=男, 2=女" → "性别，关联字典gender：1=男, 2=女" - -### 用户服务 - -#### ✏️ TravelerRequest - - - ✏️ `gender`: 类型 `Integer` → `String` - -### 订单服务 - -#### ✏️ CreateOrderRequest - - - ✏️ `gender`: 类型 `Integer` → `String` - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpTravelerRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpTravelerVO.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderTraveler.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderTravelerServiceTest.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java -M hl-user-service/src/main/java/com/hulalv/user/entity/Traveler.java -M hl-user-service/src/main/java/com/hulalv/user/service/TravelerService.java -M hl-user-service/src/main/java/com/hulalv/user/service/UserService.java -M hl-user-service/src/test/java/com/hulalv/user/service/TravelerServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1319_4466a02_feat_API.md b/changelogs/2026-03/2026-03-25_1319_4466a02_feat_API.md deleted file mode 100644 index c7c7513..0000000 --- a/changelogs/2026-03/2026-03-25_1319_4466a02_feat_API.md +++ /dev/null @@ -1,78 +0,0 @@ -# 接口变更记录 — 2026-03-25 13:19 - -> **提交** `4466a02` · **作者** wx · **时间** 2026-03-25 13:19:08 +0800 -> -> feat: 天气服务迁移至和风天气API（支持经纬度查询） - -## 变更总览 - -- **小程序聚合服务** - - MpTrip (改1) - - MpWeather (改2) -- **订单服务** - - MpWeather (改2) - ---- - -## 小程序聚合服务 - -### MpTrip - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 行程接口」** - -### ✏️ `GET` /mp/trip/weather — 天气查询（经纬度） - -- 接口名称: ~~天气查询~~ → **天气查询（经纬度）** -- 参数: city(String) → longitude(BigDecimal), latitude(BigDecimal) - -### MpWeather - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 天气接口」** - -### ✏️ `GET` /mp/weather/live — 根据经纬度获取实况天气 - -- 接口名称: ~~获取指定城市实况天气~~ → **根据经纬度获取实况天气** -- 参数: city(String) → longitude(BigDecimal), latitude(BigDecimal) - -### ✏️ `GET` /mp/weather/forecast — 根据经纬度获取天气预报 - -- 接口名称: ~~获取指定城市天气预报~~ → **根据经纬度获取天气预报** -- 参数: city(String) → longitude(BigDecimal), latitude(BigDecimal) - ---- - -## 订单服务 - -### MpWeather - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「内部天气接口(Feign)」** - -### ✏️ `GET` /internal/mp/weather/live — 根据经纬度获取实况天气 - -- 接口名称: ~~获取指定城市实况天气~~ → **根据经纬度获取实况天气** -- 参数: city(String) → longitude(BigDecimal), latitude(BigDecimal) - -### ✏️ `GET` /internal/mp/weather/forecast — 根据经纬度获取天气预报 - -- 接口名称: ~~获取指定城市天气预报~~ → **根据经纬度获取天气预报** -- 参数: city(String) → longitude(BigDecimal), latitude(BigDecimal) - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-common/src/main/java/com/hulalv/common/config/FeignRetryConfig.java -A hl-common/src/main/java/com/hulalv/common/weather/QWeatherClient.java -M hl-common/src/main/java/com/hulalv/common/weather/WeatherInfo.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpTripController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWeatherController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/config/WeatherConfig.java -M hl-order-service/src/main/java/com/hulalv/order/controller/MpWeatherController.java -M hl-order-service/src/main/java/com/hulalv/order/job/DepartureReminderJob.java -M hl-order-service/src/main/java/com/hulalv/order/service/WeatherService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1320_9958c4f_feat.md b/changelogs/2026-03/2026-03-25_1320_9958c4f_feat.md deleted file mode 100644 index 4e6f4ee..0000000 --- a/changelogs/2026-03/2026-03-25_1320_9958c4f_feat.md +++ /dev/null @@ -1,33 +0,0 @@ -# 接口变更记录 — 2026-03-25 13:20 - -> **提交** `9958c4f` · **作者** wx · **时间** 2026-03-25 13:20:22 +0800 -> -> feat: 订单状态显示优化 + 锁单扩展 + 级联处理精细化 + 产品上架校验 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 订单服务 - -#### ✏️ MpOrderListVO - - - 🆕 `checklistConfirmed` (`Boolean`) — 是否已锁单（清单确认后锁定） - -#### ✏️ OrderListVO - - - 🆕 `checklistConfirmed` (`Boolean`) — 是否已锁单（清单确认后锁定） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderItineraryEditService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1358_96c4b97_feat.md b/changelogs/2026-03/2026-03-25_1358_96c4b97_feat.md deleted file mode 100644 index 69ba7a3..0000000 --- a/changelogs/2026-03/2026-03-25_1358_96c4b97_feat.md +++ /dev/null @@ -1,324 +0,0 @@ -# 接口变更记录 — 2026-03-25 13:58 - -> **提交** `96c4b97` · **作者** wx · **时间** 2026-03-25 13:58:29 +0800 -> -> feat: 订单交通信息（接送站）— 对接飞常准航班/火车实时动态 - -## 变更总览 - -- **hl-transport-service** - - 🆕 InternalTransport (+2 接口) -- **小程序聚合服务** - - 🆕 MpOrderTransport (+2 接口) -- **订单服务** - - 🆕 AdminOrderTransport (+5 接口) - - 🆕 InternalOrderTransport (+2 接口) - ---- - -## hl-transport-service - -### 🆕 新增: InternalTransport - -### 📌 `GET` /internal/transport/flight — 按航班号查询航班动态 - -**参数** - - - `flightNo` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<FlightVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `flightNo` | `String` | 航班号 | -| `airline` | `String` | 航空公司名称 | -| `category` | `String` | 航班属性：国内/国际/地区 | -| `departAirportCode` | `String` | 出发机场三字码 | -| `arriveAirportCode` | `String` | 到达机场三字码 | -| `departAirport` | `String` | 出发机场名称 | -| `arriveAirport` | `String` | 到达机场名称 | -| `departCity` | `String` | 出发城市 | -| `arriveCity` | `String` | 到达城市 | -| `planDepartTime` | `String` | 计划起飞时间（yyyy-MM-dd HH:mm:ss） | -| `planArriveTime` | `String` | 计划到达时间（yyyy-MM-dd HH:mm:ss） | -| `actualDepartTime` | `String` | 实际起飞时间（yyyy-MM-dd HH:mm:ss） | -| `actualArriveTime` | `String` | 实际到达时间（yyyy-MM-dd HH:mm:ss） | -| `status` | `String` | 航班状态：计划/起飞/到达/延误/取消/返航/备降等 | -| `stopFlag` | `String` | 是否经停：0不经停，1经停1次，n经停n次 | -| `shareFlag` | `String` | 是否共享航班：0否，1是 | -| `shareFlightNo` | `String` | 共享航班号（实际承运航班号） | -| `departTerminal` | `String` | 出发航站楼 | -| `arriveTerminal` | `String` | 到达航站楼 | -| `boardGate` | `String` | 登机口 | -| `arriveExit` | `String` | 到达出口 | -| `departTimezone` | `String` | 出发时区偏移（秒） | -| `arriveTimezone` | `String` | 到达时区偏移（秒） | - -### 📌 `GET` /internal/transport/train — 按车次查询火车动态 - -**参数** - - - `trainNo` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<TrainVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `trainNo` | `String` | 车次 | -| `departStation` | `String` | 出发车站 | -| `arriveStation` | `String` | 到达车站 | -| `shutdown` | `String` | 是否停运：0否，1是 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `estimatedDepartTime` | `String` | 预计出发时间 | -| `estimatedArriveTime` | `String` | 预计到达时间 | -| `actualDepartTime` | `String` | 实际出发时间 | -| `actualArriveTime` | `String` | 实际到达时间 | -| `departStatus` | `String` | 出发状态：计划/正点/晚点/出发 | -| `arriveStatus` | `String` | 到达状态：计划/正点/晚点/到达 | -| `duration` | `Integer` | 运行时长（分钟） | -| `stops` | `List<TrainStopVO>` | 经停站列表 | - ---- - -## 小程序聚合服务 - -### 🆕 新增: MpOrderTransport - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「小程序-订单交通信息」** - -### 📌 `GET` /mp/order/{orderId}/transports — 查看订单交通信息（含实时动态） - -> 返回订单的去程/回程交通信息，自动从飞常准查询实时航班/火车状态 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `POST` /mp/order/{orderId}/transport — 填写交通信息 - -> 用户填写去程/回程的航班或火车信息。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<Map<String, Object>>` - ---- - -## 订单服务 - -### 🆕 新增: AdminOrderTransport - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「订单交通信息（接送站）」** - -### 📌 `GET` /admin/order/admin/order - -### 📌 `POST` /admin/order/{orderId}/transport — 添加交通信息 - -> 为订单添加去程/回程的航班或火车信息，用于安排接送站。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**请求体** `OrderTransportRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | - -**响应** `Result<OrderTransportVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transportId` | `String` | 交通信息ID | -| `orderId` | `String` | 订单ID | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | -| `createdByType` | `String` | 填写人类型：ADMIN/USER | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `actualDepartTime` | `String` | 实际/预计出发时间 | -| `actualArriveTime` | `String` | 实际/预计到达时间 | -| `liveStatus` | `String` | 状态（如：计划/起飞/到达/延误/晚点） | -| `extraInfo` | `Map<String, String>` | 航班额外信息：航站楼/登机口/出口等 | - -### 📌 `PUT` /admin/order/transport/{transportId} — 编辑交通信息 - -**参数** - - - `{transportId}` (`Long`) — 路径参数：交通信息ID - -**请求体** `OrderTransportRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | - -**响应** `Result<OrderTransportVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transportId` | `String` | 交通信息ID | -| `orderId` | `String` | 订单ID | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | -| `createdByType` | `String` | 填写人类型：ADMIN/USER | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `actualDepartTime` | `String` | 实际/预计出发时间 | -| `actualArriveTime` | `String` | 实际/预计到达时间 | -| `liveStatus` | `String` | 状态（如：计划/起飞/到达/延误/晚点） | -| `extraInfo` | `Map<String, String>` | 航班额外信息：航站楼/登机口/出口等 | - -### 📌 `DELETE` /admin/order/transport/{transportId} — 删除交通信息 - -**参数** - - - `{transportId}` (`Long`) — 路径参数：交通信息ID - -**响应** `Result<Void>` - -### 📌 `GET` /admin/order/{orderId}/transports — 查询订单交通信息（含实时动态） - -> 返回订单的去程/回程交通信息，自动从飞常准API查询实时航班/火车状态。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<List<OrderTransportVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transportId` | `String` | 交通信息ID | -| `orderId` | `String` | 订单ID | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | -| `createdByType` | `String` | 填写人类型：ADMIN/USER | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `actualDepartTime` | `String` | 实际/预计出发时间 | -| `actualArriveTime` | `String` | 实际/预计到达时间 | -| `liveStatus` | `String` | 状态（如：计划/起飞/到达/延误/晚点） | -| `extraInfo` | `Map<String, String>` | 航班额外信息：航站楼/登机口/出口等 | - -### 🆕 新增: InternalOrderTransport - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】订单交通信息（Feign调用）」** - -### 📌 `GET` /internal/order/transport/{orderId} — 查询订单交通信息（含实时动态） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<List<OrderTransportVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transportId` | `String` | 交通信息ID | -| `orderId` | `String` | 订单ID | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | -| `createdByType` | `String` | 填写人类型：ADMIN/USER | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `actualDepartTime` | `String` | 实际/预计出发时间 | -| `actualArriveTime` | `String` | 实际/预计到达时间 | -| `liveStatus` | `String` | 状态（如：计划/起飞/到达/延误/晚点） | -| `extraInfo` | `Map<String, String>` | 航班额外信息：航站楼/登机口/出口等 | - -### 📌 `POST` /internal/order/transport/{orderId} — 添加交通信息（小程序用户） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result<OrderTransportVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transportId` | `String` | 交通信息ID | -| `orderId` | `String` | 订单ID | -| `legType` | `String` | 行程段：OUTBOUND=去程接站, RETURN=回程送站 | -| `transportType` | `String` | 交通类型：FLIGHT=航班, TRAIN=火车 | -| `transportNo` | `String` | 航班号或车次 | -| `departureStation` | `String` | 出发站/机场 | -| `arrivalStation` | `String` | 到达站/机场 | -| `travelDate` | `LocalDate` | 乘坐日期 | -| `remark` | `String` | 备注 | -| `createdByType` | `String` | 填写人类型：ADMIN/USER | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `actualDepartTime` | `String` | 实际/预计出发时间 | -| `actualArriveTime` | `String` | 实际/预计到达时间 | -| `liveStatus` | `String` | 状态（如：计划/起飞/到达/延误/晚点） | -| `extraInfo` | `Map<String, String>` | 航班额外信息：航站楼/登机口/出口等 | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderTransportController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java -A hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderTransportController.java -A hl-order-service/src/main/java/com/hulalv/order/controller/InternalOrderTransportController.java -A hl-order-service/src/main/java/com/hulalv/order/dto/OrderTransportRequest.java -A hl-order-service/src/main/java/com/hulalv/order/entity/OrderTransport.java -A hl-order-service/src/main/java/com/hulalv/order/feign/TransportFeignClient.java -A hl-order-service/src/main/java/com/hulalv/order/feign/TransportFeignFallbackFactory.java -A hl-order-service/src/main/java/com/hulalv/order/mapper/OrderTransportMapper.java -A hl-order-service/src/main/java/com/hulalv/order/service/OrderTransportService.java -A hl-order-service/src/main/java/com/hulalv/order/vo/OrderTransportVO.java -A hl-transport-service/src/main/java/com/hulalv/transport/controller/InternalTransportController.java -A sql/order_transport.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1416_4991f6f_feat.md b/changelogs/2026-03/2026-03-25_1416_4991f6f_feat.md deleted file mode 100644 index f3ec5bc..0000000 --- a/changelogs/2026-03/2026-03-25_1416_4991f6f_feat.md +++ /dev/null @@ -1,68 +0,0 @@ -# 接口变更记录 — 2026-03-25 14:16 - -> **提交** `4991f6f` · **作者** wx · **时间** 2026-03-25 14:16:25 +0800 -> -> feat: 行程天自由增删 + 自动反写tripDays - -## 变更总览 - -- **产品服务** - - Itinerary (+2) - ---- - -## 产品服务 - -### Itinerary - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「行程管理」** - -### 🆕 `POST` /admin/product/item/{productId}/day — 追加行程天 - -> 在行程末尾追加一天，自动更新产品的 tripDays 和 tripNights。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**请求体** `ItineraryDayRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayTitle` | `String` | 天标题 | -| `routeSummary` | `String` | 路线概览 | - -**响应** `Result<ItineraryDayVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayId` | `String` | 行程天ID | -| `dayNumber` | `Integer` | 天数编号 | -| `dayTitle` | `String` | 天标题 | -| `routeSummary` | `String` | 路线概览 | -| `nodes` | `List<ItineraryNodeVO>` | 行程节点列表 | -| `hotels` | `List<DayHotelVO>` | 当日酒店列表 | -| `restaurants` | `List<DiningOptionVO>` | 当日用餐列表 | - -### 🆕 `DELETE` /admin/product/item/{productId}/day/{dayNumber} — 删除行程天 - -> 删除指定天的行程（含该天的所有节点和住宿），后续天数自动重新编号。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `{dayNumber}` (`Integer`) — 路径参数：天数编号 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/ItineraryController.java -M hl-product-service/src/main/java/com/hulalv/product/service/ItineraryDayService.java -M hl-product-service/src/test/java/com/hulalv/product/service/ItineraryDayServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1506_29d70a3_fix.md b/changelogs/2026-03/2026-03-25_1506_29d70a3_fix.md deleted file mode 100644 index bf8793e..0000000 --- a/changelogs/2026-03/2026-03-25_1506_29d70a3_fix.md +++ /dev/null @@ -1,33 +0,0 @@ -# 接口变更记录 — 2026-03-25 15:06 - -> **提交** `29d70a3` · **作者** wx · **时间** 2026-03-25 15:06:42 +0800 -> -> fix: 素材父分类点击显示所有子分类素材 + 新增批量导出接口 - -## 变更总览 - -- **素材服务** - - Material (+1) - ---- - -## 素材服务 - -### Material - -> 📖 **接口文档**: [http://192.168.100.236:8094/doc.html](http://192.168.100.236:8094/doc.html) → 标签 **「素材管理」** - -### 🆕 `POST` /admin/material/export — 批量导出素材 - -> 根据选中的素材ID列表，返回每个素材的下载链接信息（名称+OSS URL）。 - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1535_1c33587_feat.md b/changelogs/2026-03/2026-03-25_1535_1c33587_feat.md deleted file mode 100644 index e957ff0..0000000 --- a/changelogs/2026-03/2026-03-25_1535_1c33587_feat.md +++ /dev/null @@ -1,31 +0,0 @@ -# 接口变更记录 — 2026-03-25 15:35 - -> **提交** `1c33587` · **作者** wx · **时间** 2026-03-25 15:35:27 +0800 -> -> feat: 行程节点支持推荐餐厅列表 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ NodeCreateRequest - - - 🆕 `recommendedRestaurants` (`List<RecommendedRestaurant>`) — 推荐餐厅列表（在行程节点中展示附近推荐餐厅） - - 🆕 `restaurantId` (`String`) — 餐厅ID（来自资源服务） - - 🆕 `restaurantName` (`String`) — 餐厅名称 - - 🆕 `coverUrl` (`String`) — 封面图URL - - 🆕 `mealType` (`String`) — 餐次：早餐/午餐/晚餐 - - 🆕 `priceInfo` (`String`) — 价格信息 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/NodeUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/service/ItineraryNodeService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ItineraryNodeVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_1613_a2ca518_fix_DIN.md b/changelogs/2026-03/2026-03-25_1613_a2ca518_fix_DIN.md deleted file mode 100644 index 5ef5445..0000000 --- a/changelogs/2026-03/2026-03-25_1613_a2ca518_fix_DIN.md +++ /dev/null @@ -1,27 +0,0 @@ -# 接口变更记录 — 2026-03-25 16:13 - -> **提交** `a2ca518` · **作者** wx · **时间** 2026-03-25 16:13:23 +0800 -> -> fix: 推荐餐厅改为独立节点类型DINING_RECOMMEND - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ NodeCreateRequest - - - ✏️ `nodeType`: 说明 "节点类型：TRANSPORT(交通)/SCENIC(景区)/RESTAURANT(餐厅)/ACTIVITY(活动)/PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义)/SERVICE(服务)/NOTE(备注)" → "节点类型：TRANSPORT(交通)/SCENIC(景区)/RESTAURANT(餐厅)/ACTIVITY(活动)/PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义)/SERVICE(服务)/NOTE(备注)/DINING_RECOMMEND(推荐餐厅)" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/service/ItineraryNodeService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ItineraryNodeVO.java -M hl-product-service/src/test/java/com/hulalv/product/constant/ProductConstantsTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-25_custom_hotel_draft_no_validate.md b/changelogs/2026-03/2026-03-25_custom_hotel_draft_no_validate.md deleted file mode 100644 index 0ea8cdb..0000000 --- a/changelogs/2026-03/2026-03-25_custom_hotel_draft_no_validate.md +++ /dev/null @@ -1,26 +0,0 @@ -# 定制产品住宿：草稿状态不再强制选房型 - -> 定制产品（CUSTOM）添加/编辑住宿时，草稿状态允许不选房型，非草稿状态才校验。 - ---- - -## 变更说明 - -| 接口 | 说明 | -|------|------| -| `POST /admin/product/item/{productId}/day/{dayNumber}/hotel` | 添加住宿 | -| `PUT /admin/product/hotel/{id}` | 编辑住宿 | - -**之前**：定制产品任何时候都必须指定 roomTypeId，不传报错「定制产品必须指定房型」 - -**现在**： -- 产品状态为 **DRAFT（草稿）**：roomTypeId 可以不传，允许先保存酒店再选房型 -- 产品状态为 **非草稿**（提交审核/已发布等）：仍然必须指定 roomTypeId - -## 前端注意 - -前端无需改动逻辑，只是草稿状态下不传 roomTypeId 不会再报错了。 - -## 涉及服务 - -需重启：**hl-product-service** diff --git a/changelogs/2026-03/2026-03-25_insurance_selective_purchase.md b/changelogs/2026-03/2026-03-25_insurance_selective_purchase.md deleted file mode 100644 index 92c235f..0000000 --- a/changelogs/2026-03/2026-03-25_insurance_selective_purchase.md +++ /dev/null @@ -1,113 +0,0 @@ -# 保险选择性投保 + 出行人线下投保备注 - -> 自动投保失败时（如婴儿不满1岁），支持选择部分出行人在线投保，并为不可投保的出行人添加线下投保备注。 - ---- - -## 一、新增接口 - -### 1.1 选择部分出行人投保 - -``` -POST /admin/insurance/order/{orderId}/selective-purchase -``` - -**请求体**： -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| schemeId | Long | 是 | 保险方案ID | -| travelerIds | Long[] | 是 | 要投保的出行人ID列表 | - -**响应**：同 `AutoPurchaseResultVO`（success, purchasedCount, failedCount, failureReason） - -**使用场景**：自动投保失败后，排除不满1岁的婴儿，只选能投保的出行人。 - -### 1.2 添加出行人保险备注 - -``` -POST /admin/insurance/order/{orderId}/traveler-note -``` - -**请求体**： -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| travelerId | Long | 是 | 出行人ID | -| travelerName | String | 否 | 出行人姓名 | -| noteType | String | 是 | OFFLINE=线下投保, SKIP=跳过, OTHER=其他 | -| remark | String | 否 | 备注说明，如"不满1岁，线下购买太平洋保险" | - -**响应**：InsuranceTravelerNote 对象 - -**注意**：同一出行人重复调用会更新已有备注（upsert）。 - -### 1.3 删除出行人保险备注 - -``` -DELETE /admin/insurance/order/{orderId}/traveler-note/{noteId} -``` - -### 1.4 查询出行人保险覆盖状态 - -``` -GET /admin/insurance/order/{orderId}/traveler-coverage -``` - -**响应**： -```json -[ - { - "travelerId": "123", - "name": "张三", - "birthday": "1990-01-01", - "age": 36, - "travelerType": "ADULT", - "coverageStatus": "ONLINE_INSURED", - "policies": [{ "policyNo": "xxx", "startDate": "2026-04-29", "endDate": "2026-05-04" }] - }, - { - "travelerId": "456", - "name": "小宝宝", - "birthday": "2025-10-01", - "age": 0, - "travelerType": "CHILD", - "coverageStatus": "OFFLINE_NOTED", - "noteId": "789", - "noteType": "OFFLINE", - "noteRemark": "不满1岁，线下购买太平洋保险" - }, - { - "travelerId": "789", - "name": "李四", - "coverageStatus": "NOT_COVERED" - } -] -``` - -**coverageStatus 枚举**： -| 值 | 说明 | -|----|------| -| ONLINE_INSURED | 在线已投保（含保单详情） | -| OFFLINE_NOTED | 线下已备注（含备注内容） | -| NOT_COVERED | 未投保 | - ---- - -## 二、使用流程 - -``` -1. 自动投保失败（如有不满1岁婴儿） -2. 调用 GET /traveler-coverage 查看每个出行人状态 -3. 对能投保的出行人：POST /selective-purchase（传 travelerIds） -4. 对不能投保的出行人：POST /traveler-note（noteType=OFFLINE + remark） -5. 再次调用 /traveler-coverage 确认全部覆盖 -``` - ---- - -## 三、涉及服务 - -需重启：**hl-insurance-service** - -## 四、数据库变更 - -新增表 `insurance_traveler_note`（DDL: `sql/insurance_traveler_note.sql`），测试环境已执行。 diff --git a/changelogs/2026-03/2026-03-25_invoice_full_api.md b/changelogs/2026-03/2026-03-25_invoice_full_api.md deleted file mode 100644 index 7dae05c..0000000 --- a/changelogs/2026-03/2026-03-25_invoice_full_api.md +++ /dev/null @@ -1,396 +0,0 @@ -# 发票模块完整 API 文档（管理端 + 小程序端） - -> 发票功能：用户对已支付订单申请开票 → 管理员审核开票 → 用户下载电子发票。支持换开（最多3次） - ---- - -## 一、状态流转 - -``` -用户申请 → PENDING（待开票） - ├─ 管理员开票完成 → ISSUED（已开票） - └─ 管理员标记失败 → FAILED（开票失败）→ 管理员重新开票 → ISSUED -ISSUED → 用户换开 → 原发票 VOIDED（已作废）+ 新发票 PENDING -ISSUED → 管理员作废 → VOIDED -``` - -## 二、关联字典 - -| 字典 dict_type | 说明 | 枚举值 | -|---|---|---| -| `invoice_status` | 发票状态 | `PENDING`=待开票, `ISSUED`=已开票, `FAILED`=开票失败, `VOIDED`=已作废 | -| `invoice_title_type` | 抬头类型 | `PERSONAL`=个人, `COMPANY`=企业 | - -## 三、通用响应结构 InvoiceVO - -所有发票接口返回的数据结构（管理端直接返回 `InvoiceVO`，小程序端经 Feign 透传为 `Map<String, Object>`，字段相同）： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `id` | String | 发票ID | -| `orderId` | String | 订单ID | -| `orderNo` | String | 订单编号 | -| `amount` | String | 发票金额（元） | -| `titleType` | String | 抬头类型：`PERSONAL`=个人 / `COMPANY`=企业（字典 `invoice_title_type`） | -| `invoiceTitle` | String | 发票抬头（个人姓名或企业名称） | -| `taxNumber` | String | 纳税人识别号（企业发票有值） | -| `email` | String | 接收邮箱 | -| `invoiceType` | String | 发票类型，固定为"电子普通发票" | -| `invoiceContent` | String | 发票内容，固定为"明细" | -| `status` | String | 发票状态（字典 `invoice_status`） | -| `fileUrl` | String | 发票文件URL（已开票后有值） | -| `failReason` | String | 开票失败原因（失败时有值） | -| `contactPhone` | String | 联系电话 | -| `remark` | String | 备注信息 | -| `bankName` | String | 开户行（企业发票） | -| `bankAccount` | String | 银行账号（企业发票） | -| `companyAddress` | String | 企业地址（企业发票） | -| `companyPhone` | String | 企业电话（企业发票） | -| `invoiceNo` | String | 发票号码（已开票后有值） | -| `issuedAt` | String | 开票时间，格式 `yyyy-MM-dd HH:mm:ss` | -| `issuedBy` | String | 开票操作人（管理员ID） | -| `userId` | String | 申请用户ID | -| `originalInvoiceId` | String | 原发票ID（换开时有值，指向被作废的原发票） | -| `reissueCount` | Integer | 换开次数（0~3） | -| `createdAt` | String | 申请时间 | -| `updatedAt` | String | 更新时间 | - ---- - -## 四、小程序端接口（C端用户） - -> 网关路径前缀：`/mp/invoice` -> 需要用户登录（携带 Authorization: Bearer token） - -### 4.1 申请开票 - -``` -POST /mp/invoice/apply -``` - -**使用场景**：用户在订单详情页点击「申请发票」，填写开票信息后提交 - -**请求参数** (JSON Body)： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `orderId` | String | ✅ | 订单ID | -| `invoiceTitle` | String | ✅ | 发票抬头（个人姓名/企业名称），最长100字 | -| `titleType` | String | 否 | 抬头类型，默认 `PERSONAL`。可选：`PERSONAL`=个人, `COMPANY`=企业 | -| `taxNumber` | String | 企业必填 | 纳税人识别号，最长30位。`titleType=COMPANY` 时必填 | -| `email` | String | 否 | 接收邮箱（邮箱格式校验），最长100字 | -| `contactPhone` | String | 否 | 联系电话，最长20位 | -| `remark` | String | 否 | 备注信息，最长500字 | -| `bankName` | String | 否 | 开户行（企业发票选填），最长100字 | -| `bankAccount` | String | 否 | 银行账号（企业发票选填），最长30位 | -| `companyAddress` | String | 否 | 企业地址（企业发票选填），最长200字 | -| `companyPhone` | String | 否 | 企业电话（企业发票选填），最长20位 | - -**响应**：`Result<InvoiceVO>`（见第三节） - -**校验规则**： -- 订单必须属于当前用户 -- 订单状态须为：已支付 / 已确认 / 待出发 / 旅行中 / 已完成 / 已付定金 -- 同一订单不可重复申请（已有待开票或已开票的发票时拒绝） -- 开票金额自动取订单实付金额（`paidAmount`），如无则取总价（`totalPrice`） -- 发票类型固定「电子普通发票」，内容固定「明细」 - -**调用示例**： -```json -// 个人发票 -{ - "orderId": "1902000000000001", - "invoiceTitle": "张三", - "titleType": "PERSONAL", - "email": "zhangsan@example.com", - "contactPhone": "13800138000" -} - -// 企业发票 -{ - "orderId": "1902000000000001", - "invoiceTitle": "呼伦贝尔XX旅行社有限公司", - "titleType": "COMPANY", - "taxNumber": "91150000MA00000X00", - "email": "finance@company.com", - "bankName": "中国银行海拉尔支行", - "bankAccount": "1234567890123456789", - "companyAddress": "呼伦贝尔市海拉尔区XX路XX号", - "companyPhone": "0470-1234567" -} -``` - ---- - -### 4.2 发票详情（按发票ID） - -``` -GET /mp/invoice/{id} -``` - -**使用场景**：从发票列表点进详情页 - -**路径参数**： - -| 参数 | 类型 | 说明 | -|---|---|---| -| `id` | Long | 发票ID | - -**响应**：`Result<InvoiceVO>` - -**校验规则**：只能查看自己的发票 - ---- - -### 4.3 通过订单ID查询发票 - -``` -GET /mp/invoice/order/{orderId} -``` - -**使用场景**：订单详情页判断是否已开票。返回 `data=null` 表示未开票，可显示「申请发票」按钮 - -**路径参数**： - -| 参数 | 类型 | 说明 | -|---|---|---| -| `orderId` | Long | 订单ID | - -**响应**：`Result<InvoiceVO>`（未开票时 `data` 为 `null`） - ---- - -### 4.4 发票换开 - -``` -POST /mp/invoice/{invoiceId}/reissue -``` - -**使用场景**：已开票后发现抬头/税号填错，点击「换开发票」修改信息重新开具 - -**路径参数**： - -| 参数 | 类型 | 说明 | -|---|---|---| -| `invoiceId` | Long | 原发票ID | - -**请求参数** (JSON Body)： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `invoiceTitle` | String | ✅ | 新发票抬头，2~100字 | -| `titleType` | String | ✅ | 新抬头类型：`PERSONAL` / `COMPANY` | -| `taxNumber` | String | 企业必填 | 新纳税人识别号 | -| `email` | String | 否 | 新接收邮箱 | - -**响应**：`Result<InvoiceVO>`（返回新创建的发票记录，原发票自动作废） - -**校验规则**： -- 只能对状态为 `ISSUED`（已开票）的发票换开 -- 换开次数上限 **3次**（reissueCount >= 3 时拒绝） -- 企业抬头必须填税号 -- 换开后：原发票状态变为 `VOIDED`，新发票状态为 `PENDING`，`originalInvoiceId` 指向原发票 - -**调用示例**： -```json -{ - "invoiceTitle": "呼伦贝尔XX旅行社有限公司", - "titleType": "COMPANY", - "taxNumber": "91150000MA00000X00", - "email": "finance@company.com" -} -``` - ---- - -## 五、管理端接口（后台管理员） - -> 网关路径前缀：`/admin/invoice` -> 需要管理员登录（携带 Admin-Token） - -### 5.1 上传发票文件 - -``` -POST /admin/invoice/upload -``` - -**使用场景**：管理员在开票前先上传发票PDF/图片文件 - -**请求参数** (form-data)： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `file` | File | ✅ | 发票文件，支持 PDF / JPG / JPEG / PNG，最大 10MB | - -**响应**： -```json -{ - "code": 200, - "message": "success", - "data": { - "fileUrl": "https://oss.xxx.com/invoice/20260325/abc123.pdf" - } -} -``` - ---- - -### 5.2 发票分页列表 - -``` -GET /admin/invoice/page -``` - -**使用场景**：发票管理列表页，支持筛选 - -**请求参数** (Query)： - -| 参数 | 类型 | 必填 | 默认值 | 说明 | -|---|---|---|---|---| -| `status` | String | 否 | - | 按状态筛选（字典 `invoice_status`）：`PENDING` / `ISSUED` / `FAILED` / `VOIDED` | -| `orderNo` | String | 否 | - | 按订单编号模糊搜索 | -| `userId` | Long | 否 | - | 按用户ID筛选 | -| `page` | int | 否 | 1 | 页码（最小1） | -| `pageSize` | int | 否 | 20 | 每页条数（1~100） | - -**响应**： -```json -{ - "code": 200, - "message": "success", - "data": { - "records": [ InvoiceVO, ... ], - "total": 100, - "current": 1, - "size": 20 - } -} -``` - ---- - -### 5.3 发票详情 - -``` -GET /admin/invoice/{id} -``` - -**路径参数**：`id` — 发票ID - -**响应**：`Result<InvoiceVO>` - ---- - -### 5.4 开票完成 - -``` -PUT /admin/invoice/{id}/issue -``` - -**使用场景**：管理员线下开票完成后，上传发票文件并填写发票号码，标记开票完成 - -**路径参数**：`id` — 发票ID - -**请求参数** (JSON Body)： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `fileUrl` | String | ✅ | 发票文件URL（通过 5.1 上传接口获取） | -| `invoiceNo` | String | ✅ | 发票号码（12位数字） | - -**响应**：`Result<InvoiceVO>` - -**校验规则**：只有 `PENDING`（待开票）或 `FAILED`（开票失败）状态的发票可操作 - -**调用示例**： -```json -{ - "fileUrl": "https://oss.xxx.com/invoice/20260325/abc123.pdf", - "invoiceNo": "012345678901" -} -``` - ---- - -### 5.5 开票失败 - -``` -PUT /admin/invoice/{id}/fail -``` - -**使用场景**：发票信息有误，管理员标记失败并填写原因，用户可修正后重新申请 - -**路径参数**：`id` — 发票ID - -**请求参数** (JSON Body)： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `failReason` | String | ✅ | 失败原因 | - -**响应**：`Result<InvoiceVO>` - -**校验规则**：只有 `PENDING`（待开票）状态的发票可操作 - -**调用示例**： -```json -{ - "failReason": "发票抬头与纳税人识别号不匹配，请核实后重新申请" -} -``` - ---- - -### 5.6 作废发票 - -``` -PUT /admin/invoice/{id}/void -``` - -**使用场景**：管理员主动作废已开票的发票 - -**路径参数**：`id` — 发票ID - -**请求参数**：无 - -**响应**：`Result<InvoiceVO>` - -**校验规则**：已作废的发票不可重复作废 - ---- - -## 六、前端页面对接建议 - -### 小程序端页面 - -**订单详情页**： -- 调用 `GET /mp/invoice/order/{orderId}` 判断是否已开票 -- `data=null` → 显示「申请发票」按钮（订单状态需满足条件） -- `data.status=PENDING` → 显示「开票中」 -- `data.status=ISSUED` → 显示「查看发票」+「换开发票」按钮 -- `data.status=FAILED` → 显示失败原因 + 「重新申请」按钮 -- `data.status=VOIDED` → 显示「已作废」 - -**申请开票页**： -- 默认「个人」抬头，切换「企业」后展开额外字段（税号必填 + 开户行/银行账号/地址/电话选填） -- 金额自动显示（不可编辑，由后端计算） - -**发票详情页**： -- 显示全部字段信息 -- `status=ISSUED` 时显示发票文件下载链接（`fileUrl`）和发票号码（`invoiceNo`） -- `status=ISSUED` 且 `reissueCount < 3` 时显示「换开」按钮 - -### 管理端页面 - -**发票列表页**： -- 顶部筛选栏：状态下拉（全部/待开票/已开票/开票失败/已作废）+ 订单号搜索框 -- 列表列：订单号、用户、金额、抬头、状态、申请时间、操作 -- 操作按钮： - - `PENDING` → 「开票」「标记失败」 - - `FAILED` → 「重新开票」 - - `ISSUED` → 「作废」 - - `VOIDED` → 无操作 - -**开票操作**： -1. 先调 `POST /admin/invoice/upload` 上传发票文件 → 拿到 `fileUrl` -2. 再调 `PUT /admin/invoice/{id}/issue` 传入 `fileUrl` + `invoiceNo` diff --git a/changelogs/2026-03/2026-03-25_itinerary_day_add_delete.md b/changelogs/2026-03/2026-03-25_itinerary_day_add_delete.md deleted file mode 100644 index 41ca64f..0000000 --- a/changelogs/2026-03/2026-03-25_itinerary_day_add_delete.md +++ /dev/null @@ -1,37 +0,0 @@ -# 行程天自由增删 + 自动反写天数 - -> 产品行程天数不再写死，支持在行程编辑页面自由追加/删除天数，增删后自动更新 tripDays 和 tripNights。 - ---- - -## 新增接口 - -### 追加行程天 -``` -POST /admin/product/item/{productId}/day -``` - -**请求体**（可选）： -| 字段 | 类型 | 说明 | -|------|------|------| -| dayTitle | String | 当天标题（选填） | -| routeSummary | String | 路线概览（选填） | - -**响应**：ItineraryDayVO（新天的信息） - -**效果**：在末尾追加一天，product.tripDays +1，product.tripNights +1 - -### 删除行程天 -``` -DELETE /admin/product/item/{productId}/day/{dayNumber} -``` - -**效果**： -1. 级联删除该天的所有节点和住宿 -2. 后续天数自动重新编号（如删第2天，原第3天变第2天） -3. product.tripDays -1，product.tripNights -1 -4. 至少保留1天，不能全部删除 - -## 涉及服务 - -需重启：**hl-product-service** diff --git a/changelogs/2026-03/2026-03-25_material_subcategory_fix_export.md b/changelogs/2026-03/2026-03-25_material_subcategory_fix_export.md deleted file mode 100644 index 69ab1dc..0000000 --- a/changelogs/2026-03/2026-03-25_material_subcategory_fix_export.md +++ /dev/null @@ -1,40 +0,0 @@ -# 素材库：父分类查询修复 + 批量导出 + 权限取消 - -> 已部署正式环境 - ---- - -## 一、BUG修复：父分类点击显示所有子分类素材 - -**问题**：点击父分类（如"乌兰山"）时显示空，必须点到叶子分类（冬/夏/秋）才能看到素材。搜索关键词时也受此影响。 - -**修复**：点击父分类时自动查询所有后代子分类的素材。搜索关键词在当前分类范围（含子分类）内生效。 - -**前端无需改动**，传 `subCategoryId` 参数不变，后端自动处理。 - -## 二、新增：批量导出素材 - -``` -POST /admin/material/export -``` - -**请求体**：`[materialId1, materialId2, ...]`（Long 数组，最多200个） - -**响应**： -```json -[ - { - "materialId": "123", - "materialName": "呼伦湖冬", - "fileName": "hulunhu_winter.jpg", - "ossUrl": "https://oss.xxx.com/...", - "fileType": "image" - } -] -``` - -前端拿到 ossUrl 列表后逐个下载即可。 - -## 三、权限取消 - -素材分类不再限制权限，任何角色都可以访问所有分类。 diff --git a/changelogs/2026-03/2026-03-25_node_recommended_restaurants.md b/changelogs/2026-03/2026-03-25_node_recommended_restaurants.md deleted file mode 100644 index c13676b..0000000 --- a/changelogs/2026-03/2026-03-25_node_recommended_restaurants.md +++ /dev/null @@ -1,70 +0,0 @@ -# 新增节点类型 DINING_RECOMMEND（推荐餐厅） - -> 新增行程节点类型 `DINING_RECOMMEND`，一个节点存一组推荐餐厅列表，在行程时间线中作为一个卡片展示多个餐厅。 - ---- - -## 使用方式 - -### 创建推荐餐厅节点 - -``` -POST /admin/product/item/{productId}/day/{dayNumber}/node -``` - -```json -{ - "nodeType": "DINING_RECOMMEND", - "nodeName": "午餐推荐", - "startTime": "12:00", - "recommendedRestaurants": [ - { - "restaurantId": "123456", - "restaurantName": "纳西风味餐厅", - "coverUrl": "https://oss.xxx.com/cover.jpg", - "mealType": "午餐", - "priceInfo": "人均80元" - }, - { - "restaurantId": "789012", - "restaurantName": "藏式火锅", - "coverUrl": "https://oss.xxx.com/cover2.jpg", - "mealType": "午餐", - "priceInfo": "人均120元" - } - ] -} -``` - -### 更新推荐餐厅 - -``` -PUT /admin/product/node/{nodeId} -``` - -传 `recommendedRestaurants` 即可整体替换餐厅列表。 - -### 查询返回 - -`GET /admin/product/item/{productId}/day/{dayNumber}/nodes` 返回的 ItineraryNodeVO 中： - -- `nodeType` = `"DINING_RECOMMEND"` -- `recommendedRestaurants` = 餐厅列表数组 - -| 字段 | 类型 | 说明 | -|------|------|------| -| recommendedRestaurants[].restaurantId | String | 餐厅ID | -| recommendedRestaurants[].restaurantName | String | 餐厅名称 | -| recommendedRestaurants[].coverUrl | String | 封面图 | -| recommendedRestaurants[].mealType | String | 餐次 | -| recommendedRestaurants[].priceInfo | String | 价格信息 | - -**其他节点类型此字段为 null。** - -## 节点类型汇总（11种） - -TRANSPORT / SCENIC / RESTAURANT / ACTIVITY / PHOTOGRAPHY / HOTEL / FREE / CUSTOM / SERVICE / NOTE / **DINING_RECOMMEND** - -## 涉及服务 - -需重启：**hl-product-service** diff --git a/changelogs/2026-03/2026-03-25_order_transport.md b/changelogs/2026-03/2026-03-25_order_transport.md deleted file mode 100644 index a0b1e4d..0000000 --- a/changelogs/2026-03/2026-03-25_order_transport.md +++ /dev/null @@ -1,97 +0,0 @@ -# 订单交通信息（接送站）— 航班/火车实时动态 - -> 为订单添加去程接站/回程送站的航班或火车信息，查询时自动从飞常准API获取实时动态（到达时间、延误状态等）。 - ---- - -## 一、管理端接口 - -### 1.1 添加交通信息 -``` -POST /admin/order/{orderId}/transport -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| legType | String | 是 | OUTBOUND=去程接站, RETURN=回程送站 | -| transportType | String | 是 | FLIGHT=航班, TRAIN=火车 | -| transportNo | String | 是 | 航班号(如CA1234)或车次(如G71) | -| departureStation | String | 否 | 出发站/机场 | -| arrivalStation | String | 否 | 到达站/机场 | -| travelDate | String | 是 | 乘坐日期(yyyy-MM-dd) | -| remark | String | 否 | 备注 | - -### 1.2 编辑交通信息 -``` -PUT /admin/order/transport/{transportId} -``` -请求体同上（所有字段可选更新） - -### 1.3 删除交通信息 -``` -DELETE /admin/order/transport/{transportId} -``` - -### 1.4 查询订单交通信息（含实时动态） -``` -GET /admin/order/{orderId}/transports -``` - ---- - -## 二、小程序端接口 - -### 2.1 填写交通信息 -``` -POST /mp/order/{orderId}/transport -``` -请求体同管理端 - -### 2.2 查看交通信息 -``` -GET /mp/order/{orderId}/transports -``` - ---- - -## 三、响应结构 OrderTransportVO - -| 字段 | 类型 | 说明 | -|------|------|------| -| transportId | String | 交通信息ID | -| orderId | String | 订单ID | -| legType | String | OUTBOUND/RETURN | -| transportType | String | FLIGHT/TRAIN | -| transportNo | String | 航班号或车次 | -| departureStation | String | 出发站 | -| arrivalStation | String | 到达站 | -| travelDate | String | 乘坐日期 | -| remark | String | 备注 | -| createdByType | String | ADMIN=管理员填, USER=用户填 | -| **planDepartTime** | String | 计划出发时间（实时） | -| **planArriveTime** | String | 计划到达时间（实时） | -| **actualDepartTime** | String | 实际/预计出发时间（实时） | -| **actualArriveTime** | String | 实际/预计到达时间（实时） | -| **liveStatus** | String | 状态：计划/起飞/到达/延误/晚点等（实时） | -| **extraInfo** | Map | 额外信息（航站楼/登机口/出口等） | - -**加粗字段**为查询时从飞常准API实时获取，不存数据库。 - ---- - -## 四、使用场景 - -``` -1. 订单确认后，管理员在订单详情填写客人的去程航班/火车 -2. 或者客人自己在小程序"补充信息"时填写 -3. 司机/管理员查看时，自动显示实时到达时间和延误状态 -4. 接站时间有变（延误等），页面自动反映最新状态 -``` - -## 五、涉及服务 - -需重启：**hl-order-service、hl-transport-service、hl-mp-service** - -## 六、数据库变更 - -新增表 `order_transport`（DDL: `sql/order_transport.sql`），测试环境已执行。 diff --git a/changelogs/2026-03/2026-03-25_traveler_age_rules.md b/changelogs/2026-03/2026-03-25_traveler_age_rules.md deleted file mode 100644 index 441742c..0000000 --- a/changelogs/2026-03/2026-03-25_traveler_age_rules.md +++ /dev/null @@ -1,26 +0,0 @@ -# 出行人年龄分类规则 - -> **后端根据出生日期自动计算 travelerType，前端只需展示，不需要计算。** 小程序端和管理端都一样。 - ---- - -## 年龄分类规则（后端自动计算） - -| travelerType | 中文 | 年龄范围 | -|---|---|---| -| `BABY` | 幼童 | 0-3 周岁 | -| `YOUNG_CHILD` | 小童 | 4-6 周岁 | -| `CHILD` | 儿童 | 7-17 周岁 | -| `ADULT` | 成人 | 18 周岁及以上 | - -## 前端注意 - -- **不需要计算** travelerType，后端根据出生日期（birthday）自动赋值 -- 前端只需要**展示**对应的中文标签 -- 小程序端和管理端都是后端返回什么就展示什么 - -## 关联字段 - -- 订单人数统计：`adultCount`、`childCount`、`youngChildCount`、`babyCount`（后端自动统计） -- 出行人实体：`travelerType` 字段（字典：traveler_type） -- 出行人实体：`birthday` 字段（出生日期，前端只需提交这个） diff --git a/changelogs/2026-03/2026-03-25_trip_detail_upgrade.md b/changelogs/2026-03/2026-03-25_trip_detail_upgrade.md deleted file mode 100644 index 18f5e2f..0000000 --- a/changelogs/2026-03/2026-03-25_trip_detail_upgrade.md +++ /dev/null @@ -1,135 +0,0 @@ -# 行程详情接口改造 — 集成相册、评价、进度统计 - -> 行程详情接口 `GET /mp/trip/{orderId}` 增量改造，按三种行程阶段新增字段。**原有字段全部保留不变，纯新增。** - ---- - -## 一、接口信息 - -| 项目 | 说明 | -|------|------| -| 接口路径 | `GET /mp/trip/{orderId}` | -| 涉及服务 | hl-mp-service（BFF）→ hl-order-service → hl-review-service | -| 需重启服务 | hl-order-service、hl-review-service、hl-mp-service | - ---- - -## 二、新增字段（按行程阶段） - -### 2.1 开始前（tripPhase = "BEFORE_START"） - -| 新增字段 | 类型 | 说明 | -|---------|------|------| -| `itinerarySummary` | `Array<Object>` | 行程路线摘要，用于渲染 DAY 卡片列表 | -| `itinerarySummary[].dayNumber` | Integer | 第几天 | -| `itinerarySummary[].dayTitle` | String | 当天标题（如"森林公园休闲"） | -| `itinerarySummary[].dayCoverUrl` | String \| null | 当天封面图URL | - -### 2.2 行程中（tripPhase = "IN_PROGRESS"） - -| 新增字段 | 类型 | 说明 | -|---------|------|------| -| `traveledDistanceKm` | Integer | 已行驶里程（km），含当天 | -| `visitedScenicCount` | Integer | 已到访景点数，含当天 | -| `pendingScenicCount` | Integer | 待到访景点数（未来天数） | -| `todayTitle` | String \| null | 当日行程标题（如"DAY 2 森林公园休闲"中的"森林公园休闲"） | - -### 2.3 已结束（tripPhase = "ENDED"） - -#### 旅拍相册 - -| 新增字段 | 类型 | 说明 | -|---------|------|------| -| `albumStatus` | String | 相册状态：`NONE`=无相册, `GENERATING`=生成中(有文件夹无文件), `READY`=已生成 | -| `albumFolderCount` | Integer | 相册文件夹数 | -| `albumFileCount` | Integer | 相册文件总数（照片+视频） | -| `albumCoverUrl` | String \| null | 相册封面图URL | - -#### 行程评价 - -| 新增字段 | 类型 | 说明 | -|---------|------|------| -| `reviewStatus` | String | 评价状态：`NONE`=未评价, 其他值为评价审核状态（如 `APPROVED`） | -| `reviewId` | String \| null | 评价ID，可用于跳转查看评价详情 | -| `ratingItinerary` | Integer \| null | 行程安排评分(1-5) | -| `ratingAccommodation` | Integer \| null | 住宿安排评分(1-5) | -| `ratingDriver` | Integer \| null | 司机服务评分(1-5) | -| `ratingDining` | Integer \| null | 餐饮质量评分(1-5) | -| `ratingOverall` | Integer \| null | 整体满意度评分(1-5) | -| `ratingLevel` | String \| null | 评价等级：`GOOD`/`MEDIUM`/`BAD` | -| `reviewContent` | String \| null | 评价文字内容 | -| `isReviewed` | Boolean | 是否已评价（兼容旧字段，true=已评价） | - ---- - -## 三、原有字段（不变） - -以下字段保持不变，前端无需修改现有逻辑： - -**通用字段**：orderId, orderNo, productName, productCoverUrl, departureDate, tripDays, tripNights, status, tripPhase, currentDayNumber, countdownDays, countdownHours, dateRange, totalPeople, productDescription, guideName, guidePhone, guideAvatar, guideStaffType, meetingTime, meetingLocation, meetingNodeName, customizerId, customizerName, customizerAvatarUrl, customizerQrUrl, contracts, insurances, itineraryDays, totalScenicCount, totalDistanceKm, avgDailyDistanceKm - -**开始前特有**：warmTips, bookingNotice, suppliesList, cancelPolicy, refundPolicyId - -**行程中特有**：travelTips, todayDayNumber - -**已结束特有**：completedAt - ---- - -## 四、使用场景 - -### 场景1：已结束页面 — 旅拍相册区域 - -``` -if (albumStatus === 'NONE') → 不显示相册区域 -if (albumStatus === 'GENERATING') → 显示"旅拍相册生成中" + 加载动画 -if (albumStatus === 'READY') → 显示"旅拍相册已生成" + albumCoverUrl封面 + "查看相册"按钮 - 点击查看相册 → 跳转相册页面（已有 /mp/album/orders/{orderId}/folders 接口） -``` - -### 场景2：已结束页面 — 行程评价区域 - -``` -if (reviewStatus === 'NONE') → 显示评价入口（星级选择 + "提交评价"按钮） -if (reviewStatus !== 'NONE' && isReviewed) → 显示已提交的评分星级 - ratingOverall → 整体满意度星级 - ratingDriver → 定制师/司机满意度星级 - 点击"查看评价" → 跳转评价详情（用 reviewId） -``` - -### 场景3：已结束页面 — 行程回顾 - -``` -totalDistanceKm → 总里程（如"2485公里"） -avgDailyDistanceKm → 日均里程（如"393公里"） -totalScenicCount → 到访景点数（如"12个"） -``` - -### 场景4：行程中页面 — 顶部进度 - -``` -traveledDistanceKm → 已行驶里程 -visitedScenicCount → 已到访景点 -pendingScenicCount → 待到访景点 -todayTitle → 当日标题（如"森林公园休闲"） -currentDayNumber → 第几天（如 2） -``` - -### 场景5：开始前页面 — 行程路线DAY列表 - -``` -itinerarySummary.forEach(day => { - 渲染卡片：DAY {day.dayNumber} {day.dayTitle} - 背景图：day.dayCoverUrl -}) -``` - ---- - -## 五、注意事项 - -1. 新增字段**仅在对应阶段**返回，其他阶段为 null 或不存在 -2. `isReviewed` 字段保留向后兼容，新代码建议优先使用 `reviewStatus` 判断 -3. 相册相关的增删改接口已有，无需新开发： - - 小程序端查看：`GET /mp/album/orders/{orderId}/folders`、`GET /mp/album/folders/{folderId}/files` - - 后台管理：`POST /admin/order/{orderId}/album/folder`、`POST /admin/order/album/folder/{folderId}/files` diff --git a/changelogs/2026-03/2026-03-26_0909_df01da4_feat.md b/changelogs/2026-03/2026-03-26_0909_df01da4_feat.md deleted file mode 100644 index 33d122a..0000000 --- a/changelogs/2026-03/2026-03-26_0909_df01da4_feat.md +++ /dev/null @@ -1,70 +0,0 @@ -# 接口变更记录 — 2026-03-26 09:09 - -> **提交** `df01da4` · **作者** wx · **时间** 2026-03-26 09:09:46 +0800 -> -> feat: 小蒙马详情页字段补全 + 审批自动通过 + 上架校验优化 - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductCreateRequest - - - 🆕 `ageMin` (`Integer`) — 适合最小年龄 - - 🆕 `ageMax` (`Integer`) — 适合最大年龄 - - 🆕 `ageDescription` (`String`) — 年龄说明文案 - - 🆕 `photographyTags` (`List<String>`) — 摄影标签列表 - - 🆕 `photographyImages` (`List<String>`) — 摄影作品展示图列表 - -#### ✏️ ProductSaveRequest - - - 🆕 `ageMin` (`Integer`) — 适合最小年龄 - - 🆕 `ageMax` (`Integer`) — 适合最大年龄 - - 🆕 `ageDescription` (`String`) — 年龄说明文案 - - 🆕 `photographyTags` (`List<String>`) — 摄影标签列表 - - 🆕 `photographyImages` (`List<String>`) — 摄影作品展示图列表 - -#### ✏️ ProductUpdateRequest - - - 🆕 `ageMin` (`Integer`) — 适合最小年龄 - - 🆕 `ageMax` (`Integer`) — 适合最大年龄 - - 🆕 `ageDescription` (`String`) — 年龄说明文案 - - 🆕 `photographyTags` (`List<String>`) — 摄影标签列表 - - 🆕 `photographyImages` (`List<String>`) — 摄影作品展示图列表 - -#### ✏️ ProductVO - - - 🆕 `batchCount` (`Integer`) — 历史期数（已完成+进行中的批次数） - - 🆕 `reviewApprovalRate` (`String`) — 好评率，如\ - - 🆕 `leaderInfo` (`Map<String, Object>`) — 主领队信息 - - 🆕 `ageMin` (`Integer`) — 适合最小年龄 - - 🆕 `ageMax` (`Integer`) — 适合最大年龄 - - 🆕 `ageDescription` (`String`) — 年龄说明文案 - - 🆕 `photographyTags` (`List<String>`) — 摄影标签列表 - - 🆕 `photographyImages` (`List<String>`) — 摄影作品展示图列表 - - 🆕 `diningHighlights` (`List<Map<String, String>>`) — 餐饮亮点列表[{name,image,subtitle}] - - 🆕 `safetyItems` (`List<Map<String, String>>`) — 安全保障列表[{icon,title,description}] - - 🆕 `priceTiers` (`List<Map<String, Object>>`) — 价格档位表[{label,price}] - - 🆕 `hotelSummary` (`List<Map<String, Object>>`) — 酒店安排汇总（按天去重） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-user-service/src/main/java/com/hulalv/user/controller/InternalApprovalController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1004_e8fded4_feat.md b/changelogs/2026-03/2026-03-26_1004_e8fded4_feat.md deleted file mode 100644 index 5b64f2c..0000000 --- a/changelogs/2026-03/2026-03-26_1004_e8fded4_feat.md +++ /dev/null @@ -1,78 +0,0 @@ -# 接口变更记录 — 2026-03-26 10:04 - -> **提交** `e8fded4` · **作者** wx · **时间** 2026-03-26 10:04:43 +0800 -> -> feat: 产品人员配置增加备选人员 + 领队介绍自动填充 + staff证书标签 - -## 变更总览 - -- **资源服务** - - InternalStaff (+1) - ---- - -## 资源服务 - -### InternalStaff - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「【内部接口】服务人员（Feign调用）」** - -### 🆕 `GET` /internal/staff/batch-detail — 批量获取人员展示详情（领队介绍用） - -**响应** `Result<List<Map<String, Object>>>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductStaffConfigVO - - - 🆕 `staffIds` (`List<String>`) — 备选人员ID列表 - -#### ✏️ ProductVO - - - 🆕 `leaderInfoList` (`List<Map<String, Object>>`) — 领队介绍列表（从人员配置中LEADER类型的备选人员查询，可滚动展示） - - ❌ ~~`leaderInfo`~~ (`Map<String, Object>`) — 主领队信息 - -#### ✏️ StaffConfigRequest - - - 🆕 `staffIds` (`List<String>`) — 备选人员ID列表 - -### 资源服务 - -#### ✏️ StaffCreateRequest - - - 🆕 `certificateTags` (`List<String>`) — 证书标签列表 - -#### ✏️ StaffUpdateRequest - - - 🆕 `certificateTags` (`List<String>`) — 证书标签列表 - -#### ✏️ StaffVO - - - 🆕 `certificateTags` (`List<String>`) — 证书标签列表，如[\ - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/dto/StaffConfigRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductStaffConfig.java -M hl-product-service/src/main/java/com/hulalv/product/feign/StaffFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/feign/StaffFeignFallbackFactory.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStaffConfigService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductStaffConfigVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/entity/Staff.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/vo/StaffVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1043_7d4f79c_feat_ce.md b/changelogs/2026-03/2026-03-26_1043_7d4f79c_feat_ce.md deleted file mode 100644 index 0707e3d..0000000 --- a/changelogs/2026-03/2026-03-26_1043_7d4f79c_feat_ce.md +++ /dev/null @@ -1,44 +0,0 @@ -# 接口变更记录 — 2026-03-26 10:43 - -> **提交** `7d4f79c` · **作者** wx · **时间** 2026-03-26 10:43:22 +0800 -> -> feat: 人员证书改为结构化列表(certificates)，标签和附件一一对应 - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ StaffCreateRequest - - - ✏️ `certificateUrls`: 说明 "资质证书URL列表" → "资质证书URL列表（旧字段，建议用certificates）" - - ✏️ `certificateTags`: 说明 "证书标签列表" → "证书标签列表（旧字段，建议用certificates）" - -#### ✏️ StaffUpdateRequest - - - ✏️ `certificateUrls`: 说明 "资质证书URL列表" → "资质证书URL列表（旧字段，建议用certificates）" - - ✏️ `certificateTags`: 说明 "证书标签列表" → "证书标签列表（旧字段，建议用certificates）" - -#### ✏️ StaffVO - - - ✏️ `certificateUrls`: 说明 "资质证书URL列表" → "资质证书URL列表（旧字段，建议用certificates）" - - ✏️ `certificateTags`: 说明 "证书标签列表，如[\" → "证书标签列表（旧字段，建议用certificates）" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/entity/Staff.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/vo/StaffVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1055_bf0ba21_feat.md b/changelogs/2026-03/2026-03-26_1055_bf0ba21_feat.md deleted file mode 100644 index 28ac061..0000000 --- a/changelogs/2026-03/2026-03-26_1055_bf0ba21_feat.md +++ /dev/null @@ -1,68 +0,0 @@ -# 接口变更记录 — 2026-03-26 10:55 - -> **提交** `bf0ba21` · **作者** wx · **时间** 2026-03-26 10:55:59 +0800 -> -> feat: 安全保障改为模板机制，产品自动继承默认模板 - -## 变更总览 - -- **产品服务** - - 🆕 SafetyTemplate (+5 接口) - ---- - -## 产品服务 - -### 🆕 新增: SafetyTemplate - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「安全保障模板管理」** - -### 📌 `GET` /product/safety-template — 模板列表 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `GET` /product/safety-template/{templateId} — 模板详情 - -**参数** - - - `{templateId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /product/safety-template — 创建模板 - -**请求体** `SafetyTemplateRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `PUT` /product/safety-template/{templateId} — 更新模板 - -**参数** - - - `{templateId}` (`Long`) — 路径参数 - -**请求体** `SafetyTemplateRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `DELETE` /product/safety-template/{templateId} — 删除模板 - -**参数** - - - `{templateId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service/src/main/java/com/hulalv/product/controller/SafetyTemplateController.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -A hl-product-service/src/main/java/com/hulalv/product/entity/SafetyTemplate.java -A hl-product-service/src/main/java/com/hulalv/product/mapper/SafetyTemplateMapper.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1122_ed34f4c_fix_adm.md b/changelogs/2026-03/2026-03-26_1122_ed34f4c_fix_adm.md deleted file mode 100644 index bf87be9..0000000 --- a/changelogs/2026-03/2026-03-26_1122_ed34f4c_fix_adm.md +++ /dev/null @@ -1,74 +0,0 @@ -# 接口变更记录 — 2026-03-26 11:22 - -> **提交** `ed34f4c` · **作者** wx · **时间** 2026-03-26 11:22:12 +0800 -> -> fix: 安全保障模板接口路径加/admin前缀匹配网关路由 - -## 变更总览 - -- **产品服务** - - SafetyTemplate (+5, -5) - ---- - -## 产品服务 - -### SafetyTemplate - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「安全保障模板管理」** - -### 🆕 `GET` /admin/product/safety-template — 模板列表 - -**响应** `Result<List<Map<String, Object>>>` - -### 🆕 `GET` /admin/product/safety-template/{templateId} — 模板详情 - -**参数** - - - `{templateId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - -### 🆕 `POST` /admin/product/safety-template — 创建模板 - -**请求体** `SafetyTemplateRequest` - -**响应** `Result<Map<String, Object>>` - -### 🆕 `PUT` /admin/product/safety-template/{templateId} — 更新模板 - -**参数** - - - `{templateId}` (`Long`) — 路径参数 - -**请求体** `SafetyTemplateRequest` - -**响应** `Result<Map<String, Object>>` - -### 🆕 `DELETE` /admin/product/safety-template/{templateId} — 删除模板 - -**参数** - - - `{templateId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### ❌ ~~`GET` /product/safety-template — 模板列表~~ - -### ❌ ~~`GET` /product/safety-template/{templateId} — 模板详情~~ - -### ❌ ~~`POST` /product/safety-template — 创建模板~~ - -### ❌ ~~`PUT` /product/safety-template/{templateId} — 更新模板~~ - -### ❌ ~~`DELETE` /product/safety-template/{templateId} — 删除模板~~ - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/SafetyTemplateController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1150_a137026_feat_4_group.md b/changelogs/2026-03/2026-03-26_1150_a137026_feat_4_group.md deleted file mode 100644 index ff17dd0..0000000 --- a/changelogs/2026-03/2026-03-26_1150_a137026_feat_4_group.md +++ /dev/null @@ -1,37 +0,0 @@ -# 接口变更记录 — 2026-03-26 11:50 - -> **提交** `a137026` · **作者** wx · **时间** 2026-03-26 11:50:43 +0800 -> -> feat: 订单新增4位团号(groupCode)，LCG混淆年度唯一 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 订单服务 - -#### ✏️ MpOrderListVO - - - 🆕 `groupCode` (`String`) — 4位团号 - -#### ✏️ OrderDetailVO - - - 🆕 `groupCode` (`String`) — 4位团号 - -#### ✏️ OrderListVO - - - 🆕 `groupCode` (`String`) — 4位团号 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-order-service/src/main/java/com/hulalv/order/entity/GroupCodeSequence.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderInfo.java -A hl-order-service/src/main/java/com/hulalv/order/mapper/GroupCodeSequenceMapper.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1305_b23fae1_feat.md b/changelogs/2026-03/2026-03-26_1305_b23fae1_feat.md deleted file mode 100644 index e646bf8..0000000 --- a/changelogs/2026-03/2026-03-26_1305_b23fae1_feat.md +++ /dev/null @@ -1,44 +0,0 @@ -# 接口变更记录 — 2026-03-26 13:05 - -> **提交** `b23fae1` · **作者** wx · **时间** 2026-03-26 13:05:35 +0800 -> -> feat: 酒店管理新增销售电话和合房电话字段 - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ HotelCreateRequest - - - 🆕 `salesPhone` (`String`) — 销售电话 - - 🆕 `roomSharePhone` (`String`) — 合房电话 - -#### ✏️ HotelUpdateRequest - - - 🆕 `salesPhone` (`String`) — 销售电话 - - 🆕 `roomSharePhone` (`String`) — 合房电话 - -#### ✏️ HotelVO - - - 🆕 `salesPhone` (`String`) — 销售电话 - - 🆕 `roomSharePhone` (`String`) — 合房电话 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelController.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/HotelUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/entity/Hotel.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/HotelVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1414_8a5a9e7_feat.md b/changelogs/2026-03/2026-03-26_1414_8a5a9e7_feat.md deleted file mode 100644 index 4b0f695..0000000 --- a/changelogs/2026-03/2026-03-26_1414_8a5a9e7_feat.md +++ /dev/null @@ -1,71 +0,0 @@ -# 接口变更记录 — 2026-03-26 14:14 - -> **提交** `8a5a9e7` · **作者** wx · **时间** 2026-03-26 14:14:54 +0800 -> -> feat: 安全保障改为逐条管理(类似费用不包含)，废弃模板机制 - -## 变更总览 - -- **产品服务** - - 🆕 ProductSafetyItem (+4 接口) - ---- - -## 产品服务 - -### 🆕 新增: ProductSafetyItem - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「产品安全保障项管理」** - -### 📌 `GET` /admin/product/{productId}/safety-item — 列表 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `POST` /admin/product/{productId}/safety-item — 添加 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**请求体** `SafetyItemRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `PUT` /admin/product/{productId}/safety-item/{id} — 更新 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `{id}` (`Long`) — 路径参数 - -**请求体** `SafetyItemRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `DELETE` /admin/product/{productId}/safety-item/{id} — 删除 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service/src/main/java/com/hulalv/product/controller/ProductSafetyItemController.java -A hl-product-service/src/main/java/com/hulalv/product/entity/ProductSafetyItem.java -A hl-product-service/src/main/java/com/hulalv/product/mapper/ProductSafetyItemMapper.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1456_0727271_feat.md b/changelogs/2026-03/2026-03-26_1456_0727271_feat.md deleted file mode 100644 index f7f27e7..0000000 --- a/changelogs/2026-03/2026-03-26_1456_0727271_feat.md +++ /dev/null @@ -1,28 +0,0 @@ -# 接口变更记录 — 2026-03-26 14:56 - -> **提交** `0727271` · **作者** wx · **时间** 2026-03-26 14:56:50 +0800 -> -> feat: 价格档位改为产品级别定义组合+后端自动匹配最低价 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductVO - - - 🆕 `priceTierLabels` (`List<Map<String, Object>>`) — 价格档位组合定义（管理端配置用）[{label,adultCount,childCount}] - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1510_2da9380_feat_admin_s.md b/changelogs/2026-03/2026-03-26_1510_2da9380_feat_admin_s.md deleted file mode 100644 index 76a506a..0000000 --- a/changelogs/2026-03/2026-03-26_1510_2da9380_feat_admin_s.md +++ /dev/null @@ -1,37 +0,0 @@ -# 接口变更记录 — 2026-03-26 15:10 - -> **提交** `2da9380` · **作者** wx · **时间** 2026-03-26 15:10:40 +0800 -> -> feat: 管理端新增 /admin/staff/batch-brief 批量查人员简要信息 - -## 变更总览 - -- **资源服务** - - Staff (+1) - ---- - -## 资源服务 - -### Staff - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「服务人员管理」** - -### 🆕 `GET` /admin/staff/batch-brief — 批量查人员简要信息 - -> 根据ID列表批量查人员简要信息（ID+姓名+类型），用于备选人员回显。 - -**参数** - - - `staffIds` (`String`) — 查询参数：人员ID列表（逗号分隔） - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1513_58e1714_fix_batch-brief_bat.md b/changelogs/2026-03/2026-03-26_1513_58e1714_fix_batch-brief_bat.md deleted file mode 100644 index dcf6246..0000000 --- a/changelogs/2026-03/2026-03-26_1513_58e1714_fix_batch-brief_bat.md +++ /dev/null @@ -1,38 +0,0 @@ -# 接口变更记录 — 2026-03-26 15:13 - -> **提交** `58e1714` · **作者** wx · **时间** 2026-03-26 15:13:58 +0800 -> -> fix: batch-brief加batch-basic别名兼容前端已有调用 - -## 变更总览 - -- **资源服务** - - Staff (+1, -1) - ---- - -## 资源服务 - -### Staff - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「服务人员管理」** - -### 🆕 `GET` /admin/staff — 批量查人员简要信息 - -> 根据ID列表批量查人员简要信息（ID+姓名+类型），用于备选人员回显。 - -**参数** - - - `staffIds` (`String`) — 查询参数：人员ID列表（逗号分隔） - -### ❌ ~~`GET` /admin/staff/batch-brief — 批量查人员简要信息~~ - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/StaffController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-26_1723_6702622_feat_f.md b/changelogs/2026-03/2026-03-26_1723_6702622_feat_f.md deleted file mode 100644 index 9d00bb5..0000000 --- a/changelogs/2026-03/2026-03-26_1723_6702622_feat_f.md +++ /dev/null @@ -1,33 +0,0 @@ -# 接口变更记录 — 2026-03-26 17:23 - -> **提交** `6702622` · **作者** wx · **时间** 2026-03-26 17:23:35 +0800 -> -> feat: 素材删除有引用时提示但支持force=true强制删除 - -## 变更总览 - -- **素材服务** - - Material (改1) - ---- - -## 素材服务 - -### Material - -> 📖 **接口文档**: [http://192.168.100.236:8094/doc.html](http://192.168.100.236:8094/doc.html) → 标签 **「素材管理」** - -### ✏️ `DELETE` /admin/material/{materialId} — 删除素材 - -- 参数: materialId(Long) → materialId(Long), force(boolean) - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_0931_aaf10f5_fix_staff_ID.md b/changelogs/2026-03/2026-03-27_0931_aaf10f5_fix_staff_ID.md deleted file mode 100644 index b2db2a3..0000000 --- a/changelogs/2026-03/2026-03-27_0931_aaf10f5_fix_staff_ID.md +++ /dev/null @@ -1,34 +0,0 @@ -# 接口变更记录 — 2026-03-27 09:31 - -> **提交** `aaf10f5` · **作者** wx · **时间** 2026-03-27 09:31:40 +0800 -> -> fix: staff素材ID解析全面容错 + batch-detail返回完整StaffVO - -## 变更总览 - -- **资源服务** - - InternalStaff (改1) - ---- - -## 资源服务 - -### InternalStaff - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「【内部接口】服务人员（Feign调用）」** - -### ✏️ `GET` /internal/staff/batch-detail — 批量获取人员完整详情（领队介绍用） - -- 接口名称: ~~批量获取人员展示详情（领队介绍用）~~ → **批量获取人员完整详情（领队介绍用）** -- 返回类型: `Result<List<Map<String, Object>>>` → `` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/staff/controller/InternalStaffController.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1026_e18405c_feat.md b/changelogs/2026-03/2026-03-27_1026_e18405c_feat.md deleted file mode 100644 index 8651242..0000000 --- a/changelogs/2026-03/2026-03-27_1026_e18405c_feat.md +++ /dev/null @@ -1,82 +0,0 @@ -# 接口变更记录 — 2026-03-27 10:26 - -> **提交** `e18405c` · **作者** wx · **时间** 2026-03-27 10:26:31 +0800 -> -> feat: 产品新增研学收获模块，设计与安全保障一致 - -## 变更总览 - -- **产品服务** - - 🆕 ProductStudyGain (+4 接口) - ---- - -## 产品服务 - -### 🆕 新增: ProductStudyGain - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「产品研学收获管理」** - -### 📌 `GET` /admin/product/{productId}/study-gain — 列表 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `POST` /admin/product/{productId}/study-gain — 添加 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**请求体** `StudyGainRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `PUT` /admin/product/{productId}/study-gain/{id} — 更新 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `{id}` (`Long`) — 路径参数 - -**请求体** `StudyGainRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `DELETE` /admin/product/{productId}/study-gain/{id} — 删除 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductVO - - - 🆕 `studyGains` (`List<Map<String, String>>`) — 研学收获列表[{icon,title,description}] - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service/src/main/java/com/hulalv/product/controller/ProductStudyGainController.java -A hl-product-service/src/main/java/com/hulalv/product/entity/ProductStudyGain.java -A hl-product-service/src/main/java/com/hulalv/product/mapper/ProductStudyGainMapper.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1044_7e0f189_feat.md b/changelogs/2026-03/2026-03-27_1044_7e0f189_feat.md deleted file mode 100644 index 326bc97..0000000 --- a/changelogs/2026-03/2026-03-27_1044_7e0f189_feat.md +++ /dev/null @@ -1,43 +0,0 @@ -# 接口变更记录 — 2026-03-27 10:44 - -> **提交** `7e0f189` · **作者** wx · **时间** 2026-03-27 10:44:59 +0800 -> -> feat: 团期日历和套餐列表返回定金金额 - -## 变更总览 - -- **产品服务** - - InternalProduct (-1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### ❌ ~~`POST` /internal/product/approval-result — 处理产品审批结果~~ - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ GroupBatchCalendarVO - - - 🆕 `depositAmount` (`BigDecimal`) — 定金金额(元/人)，根据起步价×定金比例计算 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/GroupBatchCalendarVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/GroupTourBatchServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1122_80c3918_fix_combo.md b/changelogs/2026-03/2026-03-27_1122_80c3918_fix_combo.md deleted file mode 100644 index bbdd806..0000000 --- a/changelogs/2026-03/2026-03-27_1122_80c3918_fix_combo.md +++ /dev/null @@ -1,35 +0,0 @@ -# 接口变更记录 — 2026-03-27 11:22 - -> **提交** `80c3918` · **作者** wx · **时间** 2026-03-27 11:22:55 +0800 -> -> fix: 彻底移除小蒙马套餐(combo)概念 - -## 变更总览 - -- **产品服务** - - InternalProduct (-1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### ❌ ~~`GET` /internal/product/batch/{batchId}/combos — 批次套餐列表（内部）~~ - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/test/java/com/hulalv/product/service/GroupTourBatchServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1421_a25a70d_fix_m.md b/changelogs/2026-03/2026-03-27_1421_a25a70d_fix_m.md deleted file mode 100644 index a0b412b..0000000 --- a/changelogs/2026-03/2026-03-27_1421_a25a70d_fix_m.md +++ /dev/null @@ -1,36 +0,0 @@ -# 接口变更记录 — 2026-03-27 14:21 - -> **提交** `a25a70d` · **作者** wx · **时间** 2026-03-27 14:21:00 +0800 -> -> fix: 小程序端新增团期日历接口 /mp/product/{id}/batches/calendar - -## 变更总览 - -- **产品服务** - - MpProduct (+1) - ---- - -## 产品服务 - -### MpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「小程序-产品」** - -### 🆕 `GET` /mp/product/{productId}/batches/calendar — 团期日历（C端） - -> 小蒙马拼团产品的团期日历，返回可报名的团期列表。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1424_0814cd2_fix.md b/changelogs/2026-03/2026-03-27_1424_0814cd2_fix.md deleted file mode 100644 index 8f2a87a..0000000 --- a/changelogs/2026-03/2026-03-27_1424_0814cd2_fix.md +++ /dev/null @@ -1,24 +0,0 @@ -# 接口变更记录 — 2026-03-27 14:24 - -> **提交** `0814cd2` · **作者** wx · **时间** 2026-03-27 14:24:18 +0800 -> -> fix: 新增参与家庭数 + 好评率无评价默认100% - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductVO - - - 🆕 `familyCount` (`Integer`) — 参与家庭数（该产品的总订单数，一个订单=一个家庭） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1428_556bd4f_feat.md b/changelogs/2026-03/2026-03-27_1428_556bd4f_feat.md deleted file mode 100644 index 246d75b..0000000 --- a/changelogs/2026-03/2026-03-27_1428_556bd4f_feat.md +++ /dev/null @@ -1,83 +0,0 @@ -# 接口变更记录 — 2026-03-27 14:28 - -> **提交** `556bd4f` · **作者** wx · **时间** 2026-03-27 14:28:46 +0800 -> -> feat: 摄影跟拍改为分类模式，与安全保障一致 - -## 变更总览 - -- **产品服务** - - 🆕 ProductPhotographyItem (+4 接口) - ---- - -## 产品服务 - -### 🆕 新增: ProductPhotographyItem - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「产品摄影跟拍管理」** - -### 📌 `GET` /admin/product/{productId}/photography-item — 列表 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `POST` /admin/product/{productId}/photography-item — 添加 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - -**请求体** `PhotographyItemRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `PUT` /admin/product/{productId}/photography-item/{id} — 更新 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `{id}` (`Long`) — 路径参数 - -**请求体** `PhotographyItemRequest` - -**响应** `Result<Map<String, Object>>` - -### 📌 `DELETE` /admin/product/{productId}/photography-item/{id} — 删除 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductVO - - - 🆕 `photographyItems` (`List<Map<String, String>>`) — 摄影跟拍项列表[{icon,title,description}]（与安全保障格式一致） - - ✏️ `photographyTags`: 说明 "摄影标签列表" → "摄影标签列表（旧，建议用photographyItems）" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service/src/main/java/com/hulalv/product/controller/ProductPhotographyItemController.java -A hl-product-service/src/main/java/com/hulalv/product/entity/ProductPhotographyItem.java -A hl-product-service/src/main/java/com/hulalv/product/mapper/ProductPhotographyItemMapper.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1622_ceeff91_feat_OA.md b/changelogs/2026-03/2026-03-27_1622_ceeff91_feat_OA.md deleted file mode 100644 index dfe92bf..0000000 --- a/changelogs/2026-03/2026-03-27_1622_ceeff91_feat_OA.md +++ /dev/null @@ -1,36 +0,0 @@ -# 接口变更记录 — 2026-03-27 16:22 - -> **提交** `ceeff91` · **作者** wx · **时间** 2026-03-27 16:22:42 +0800 -> -> feat: 产品上架走企微OA审批 - -## 变更总览 - -- **产品服务** - - InternalProduct (+1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### 🆕 `POST` /internal/product/approval-result — 处理产品审批回调结果 - -> 【仅限内部调用】企微OA审批回调，按thirdNo匹配产品并更新上架状态。 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductStatusServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1657_334bcdc_feat.md b/changelogs/2026-03/2026-03-27_1657_334bcdc_feat.md deleted file mode 100644 index 2342402..0000000 --- a/changelogs/2026-03/2026-03-27_1657_334bcdc_feat.md +++ /dev/null @@ -1,34 +0,0 @@ -# 接口变更记录 — 2026-03-27 16:57 - -> **提交** `334bcdc` · **作者** wx · **时间** 2026-03-27 16:57:30 +0800 -> -> feat: 产品状态和审核状态分离，上下架都走企微审批 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductListVO - - - 🆕 `approvalStatus` (`String`) — 审核状态：NONE/PENDING/PUBLISH_APPROVED/PUBLISH_REJECTED/UNPUBLISH_APPROVED/UNPUBLISH_REJECTED - - ✏️ `status`: 说明 "产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED" → "产品状态：DRAFT=草稿/PUBLISHED=上架/UNPUBLISHED=下架" - -#### ✏️ ProductVO - - - 🆕 `approvalStatus` (`String`) — 审核状态：NONE/PENDING/PUBLISH_APPROVED/PUBLISH_REJECTED/UNPUBLISH_APPROVED/UNPUBLISH_REJECTED - - ✏️ `status`: 说明 "产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED" → "产品状态：DRAFT=草稿/PUBLISHED=上架/UNPUBLISHED=下架" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1811_7a8bfe6_fix_P0_bug_5.md b/changelogs/2026-03/2026-03-27_1811_7a8bfe6_fix_P0_bug_5.md deleted file mode 100644 index 641fee5..0000000 --- a/changelogs/2026-03/2026-03-27_1811_7a8bfe6_fix_P0_bug_5.md +++ /dev/null @@ -1,57 +0,0 @@ -# 接口变更记录 — 2026-03-27 18:11 - -> **提交** `7a8bfe6` · **作者** wx · **时间** 2026-03-27 18:11:22 +0800 -> -> fix: P0业务逻辑bug批量修复（5项） - -## 变更总览 - -- **素材服务** - - InternalMaterial (+1) - ---- - -## 素材服务 - -### InternalMaterial - -> 📖 **接口文档**: [http://192.168.100.236:8094/doc.html](http://192.168.100.236:8094/doc.html) → 标签 **「素材内部接口（Feign调用）」** - -### 🆕 `DELETE` /internal/material/ref/unbind-all — 全量解绑业务实体引用 - -> 删除指定业务实体的所有素材引用，用于业务实体被删除时清理引用数据 - -**参数** - - - `bizType` (`String`) — 查询参数 - - `bizId` (`Long`) — 查询参数 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A "docs/tasks/20260327_fix_P0\344\270\232\345\212\241\351\200\273\350\276\221bug\346\211\271\351\207\217\344\277\256\345\244\215.md" -M hl-callback-service/pom.xml -M hl-callback-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java -M hl-callback-service/src/test/java/com/hulalv/callback/controller/WxCallbackControllerTest.java -M hl-material-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityPriceCalendarService.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/feign/MaterialRefFallbackFactory.java -M hl-resource-service/src/main/java/com/hulalv/resource/feign/MaterialRefFeignClient.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityPriceCalendarServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1826_34415a3_fix.md b/changelogs/2026-03/2026-03-27_1826_34415a3_fix.md deleted file mode 100644 index 44ff75a..0000000 --- a/changelogs/2026-03/2026-03-27_1826_34415a3_fix.md +++ /dev/null @@ -1,43 +0,0 @@ -# 接口变更记录 — 2026-03-27 18:26 - -> **提交** `34415a3` · **作者** wx · **时间** 2026-03-27 18:26:24 +0800 -> -> fix: 小程序产品详情退款政策返回规则文字而非ID - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### 🆕 RefundPolicyBriefVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `policyId` | `Long` | | -| `policyName` | `String` | | -| `rules` | `List<RuleVO>` | | -| `minDays` | `Integer` | | -| `refundRatio` | `Integer` | | - -#### 🆕 RefundPolicyDetailVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `policyName` | `String` | 政策名称 | -| `rules` | `List<String>` | 退款规则文字列表，如['出发前7天及以上取消，退款100%', '出发前3-7天取消，退款50%'] | - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service/src/main/java/com/hulalv/product/feign/RefundPolicyFallbackFactory.java -A hl-product-service/src/main/java/com/hulalv/product/feign/RefundPolicyFeignClient.java -A hl-product-service/src/main/java/com/hulalv/product/feign/vo/RefundPolicyBriefVO.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -A hl-product-service/src/main/java/com/hulalv/product/vo/RefundPolicyDetailVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1827_59ce421_feat.md b/changelogs/2026-03/2026-03-27_1827_59ce421_feat.md deleted file mode 100644 index 47924aa..0000000 --- a/changelogs/2026-03/2026-03-27_1827_59ce421_feat.md +++ /dev/null @@ -1,24 +0,0 @@ -# 接口变更记录 — 2026-03-27 18:27 - -> **提交** `59ce421` · **作者** wx · **时间** 2026-03-27 18:27:17 +0800 -> -> feat: 产品详情新增早鸟优惠文字描述 earlyBirdText - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpProductDetailVO - - - 🆕 `earlyBirdText` (`String`) — 早鸟优惠文字描述(如: 早鸟优惠：满2人立减50元/人) - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/service/ProductAggregationService.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductDetailVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1842_33bb70b_fix.md b/changelogs/2026-03/2026-03-27_1842_33bb70b_fix.md deleted file mode 100644 index 58e6278..0000000 --- a/changelogs/2026-03/2026-03-27_1842_33bb70b_fix.md +++ /dev/null @@ -1,31 +0,0 @@ -# 接口变更记录 — 2026-03-27 18:42 - -> **提交** `33bb70b` · **作者** wx · **时间** 2026-03-27 18:42:23 +0800 -> -> fix: 起售价根据支付模式返回，定金模式返回定金起售价 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ MpProductListVO - - - 🆕 `startPriceLabel` (`String`) — 起步价标签：'起' 或 '定金起' - - ✏️ `startPrice`: 说明 "起步价（来自定价配置）" → "起步价：全款模式=最低售价，定金模式=最低定金额" - -#### ✏️ ProductVO - - - 🆕 `startPriceLabel` (`String`) — 起步价标签：'起' 或 '定金起' - - ✏️ `startPrice`: 说明 "起步价：未来一年价格日历中最低成人售价" → "起步价：全款模式=最低售价，定金模式=最低定金额" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/MpProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1902_3fa229c_fix.md b/changelogs/2026-03/2026-03-27_1902_3fa229c_fix.md deleted file mode 100644 index dd146c4..0000000 --- a/changelogs/2026-03/2026-03-27_1902_3fa229c_fix.md +++ /dev/null @@ -1,31 +0,0 @@ -# 接口变更记录 — 2026-03-27 19:02 - -> **提交** `3fa229c` · **作者** wx · **时间** 2026-03-27 19:02:09 +0800 -> -> fix: 小程序产品列表和详情返回创作者姓名(creatorName) - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ MpProductListVO - - - 🆕 `creatorName` (`String`) — 创作者姓名 - -#### ✏️ ProductVO - - - 🆕 `creatorName` (`String`) — 创作者姓名 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/MpProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-27_1911_9a30a34_feat.md b/changelogs/2026-03/2026-03-27_1911_9a30a34_feat.md deleted file mode 100644 index 7e72470..0000000 --- a/changelogs/2026-03/2026-03-27_1911_9a30a34_feat.md +++ /dev/null @@ -1,83 +0,0 @@ -# 接口变更记录 — 2026-03-27 19:11 - -> **提交** `9a30a34` · **作者** wx · **时间** 2026-03-27 19:11:41 +0800 -> -> feat: 小程序产品详情返回早鸟优惠文案(earlyBirdTexts) - -## 变更总览 - -- **订单服务** - - InternalEarlyBird (+1) - ---- - -## 订单服务 - -### InternalEarlyBird - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】早鸟优惠（Feign调用）」** - -### 🆕 `GET` /internal/mp/early-bird/by-product — 查询产品关联的生效早鸟计划 - -> 根据productId查询当前生效且关联该产品的早鸟计划列表，用于小程序产品详情展示 - -**参数** - - - `productId` (`Long`) — 查询参数 - -**响应** `Result<List<EarlyBirdPlanVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `planId` | `Long` | 计划ID | -| `planName` | `String` | 计划名称 | -| `startDate` | `LocalDate` | 生效开始日期 | -| `endDate` | `LocalDate` | 生效结束日期 | -| `minPeople` | `Integer` | 最低人数 | -| `discountAmount` | `BigDecimal` | 优惠金额 | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | -| `productIds` | `List<Long>` | 适用产品ID列表（空表示适用全部CORE/GROUP产品） | -| `productNames` | `List<String>` | 适用产品名称列表（空表示适用全部） | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### 🆕 EarlyBirdBriefVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `planId` | `Long` | | -| `planName` | `String` | | -| `startDate` | `LocalDate` | | -| `endDate` | `LocalDate` | | -| `minPeople` | `Integer` | | -| `discountAmount` | `BigDecimal` | | - -#### ✏️ ProductVO - - - 🆕 `earlyBirdTexts` (`List<String>`) — 早鸟优惠文案列表，如['早鸟优惠：2人及以上立减200元/人'] - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java -M hl-order-service/src/main/java/com/hulalv/order/service/EarlyBirdPlanService.java -A hl-product-service/src/main/java/com/hulalv/product/feign/EarlyBirdFallbackFactory.java -A hl-product-service/src/main/java/com/hulalv/product/feign/EarlyBirdFeignClient.java -A hl-product-service/src/main/java/com/hulalv/product/feign/vo/EarlyBirdBriefVO.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_1013_2d0e032_fix_ta.md b/changelogs/2026-03/2026-03-30_1013_2d0e032_fix_ta.md deleted file mode 100644 index 69c8dee..0000000 --- a/changelogs/2026-03/2026-03-30_1013_2d0e032_fix_ta.md +++ /dev/null @@ -1,24 +0,0 @@ -# 接口变更记录 — 2026-03-30 10:13 - -> **提交** `2d0e032` · **作者** wx · **时间** 2026-03-30 10:13:18 +0800 -> -> fix: 产品详情每日酒店返回标签(tags) - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ DayHotelVO - - - 🆕 `tags` (`List<String>`) — 酒店标签列表 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/DayHotelVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_1022_0958aea_feat.md b/changelogs/2026-03/2026-03-30_1022_0958aea_feat.md deleted file mode 100644 index 5c7a190..0000000 --- a/changelogs/2026-03/2026-03-30_1022_0958aea_feat.md +++ /dev/null @@ -1,25 +0,0 @@ -# 接口变更记录 — 2026-03-30 10:22 - -> **提交** `0958aea` · **作者** wx · **时间** 2026-03-30 10:22:47 +0800 -> -> feat: 小程序产品详情团期返回服务人员(手机号脱敏) - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ GroupBatchCalendarVO - - - 🆕 `staff` (`List<Map<String, String>>`) — 服务人员列表(含姓名、角色、脱敏手机号) - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/GroupBatchStaffService.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/GroupBatchCalendarVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_1243_22e87da_test_15.md b/changelogs/2026-03/2026-03-30_1243_22e87da_test_15.md deleted file mode 100644 index bae40a2..0000000 --- a/changelogs/2026-03/2026-03-30_1243_22e87da_test_15.md +++ /dev/null @@ -1,588 +0,0 @@ -# 接口变更记录 — 2026-03-30 12:43 - -> **提交** `22e87da` · **作者** wx · **时间** 2026-03-30 12:43:27 +0800 -> -> test: 单元测试覆盖率从15%提升到50%，修复7个真实bug - -## 变更总览 - -- **产品服务** - - 🆕 AdminBookingTermsTest (+0 接口) - - 🆕 AdminWarmTipsTest (+0 接口) - - 🆕 DistrictTest (+0 接口) - - 🆕 FamilyTest (+0 接口) - - 🆕 FormulaTest (+0 接口) - - 🆕 GroupBatchTest (+0 接口) - - 🆕 InternalMpProductTest (+0 接口) - - 🆕 InternalProductTest (+0 接口) - - 🆕 ItineraryTest (+0 接口) - - 🆕 MpProductTest (+0 接口) - - 🆕 PricingTest (+0 接口) - - 🆕 ProductTest (+0 接口) - - 🆕 ProductFolderTest (+0 接口) - - 🆕 ProductLineTest (+0 接口) - - 🆕 ProductPhotographyItemTest (+0 接口) - - 🆕 ProductSafetyItemTest (+0 接口) - - 🆕 ProductStudyGainTest (+0 接口) - - 🆕 QuoteTest (+0 接口) - - 🆕 SafetyTemplateTest (+0 接口) -- **任务服务** - - 🆕 BoardTest (+0 接口) - - 🆕 TaskTest (+0 接口) - - 🆕 WebSocketDocTest (+0 接口) -- **企微回调服务** - - 🆕 MsgAuditCallbackTest (+0 接口) -- **合同服务** - - 🆕 AdminClauseTemplateTest (+0 接口) - - 🆕 AdminContractTest (+0 接口) - - 🆕 AdminContractSchemeTest (+0 接口) - - 🆕 ContractCallbackTest (+0 接口) - - 🆕 InternalContractTest (+0 接口) - - 🆕 InternalMpContractTest (+0 接口) -- **小程序聚合服务** - - 🆕 MpActivityTest (+0 接口) - - 🆕 MpAlbumTest (+0 接口) - - 🆕 MpBadgeTest (+0 接口) - - 🆕 MpBannerTest (+0 接口) - - 🆕 MpCommonTest (+0 接口) - - 🆕 MpConfigTest (+0 接口) - - 🆕 MpContractTest (+0 接口) - - 🆕 MpCustomizeTest (+0 接口) - - 🆕 MpDesignerTest (+0 接口) - - 🆕 MpDictTest (+0 接口) - - 🆕 MpExploreTest (+0 接口) - - 🆕 MpFavoriteTest (+0 接口) - - 🆕 MpFootprintTest (+0 接口) - - 🆕 MpHomeTest (+0 接口) - - 🆕 MpHotelTest (+0 接口) - - 🆕 MpInsuranceTest (+0 接口) - - 🆕 MpInvoiceTest (+0 接口) - - 🆕 MpLikeTest (+0 接口) - - 🆕 MpMessageTest (+0 接口) - - 🆕 MpOrderTest (+0 接口) - - 🆕 MpOrderTransportTest (+0 接口) - - 🆕 MpPaymentTest (+0 接口) - - 🆕 MpProductTest (+0 接口) - - 🆕 MpRefundTest (+0 接口) - - 🆕 MpRestaurantTest (+0 接口) - - 🆕 MpReviewTest (+0 接口) - - 🆕 MpScenicTest (+0 接口) - - 🆕 MpSearchTest (+0 接口) - - 🆕 MpTravelerTest (+0 接口) - - 🆕 MpTripTest (+0 接口) - - 🆕 MpUserTest (+0 接口) - - 🆕 MpWeatherTest (+0 接口) - - 🆕 MpWikiTest (+0 接口) - - 🆕 MpWishTest (+0 接口) -- **支付服务** - - 🆕 AdminPaymentTest (+0 接口) - - 🆕 InternalPaymentTest (+0 接口) - - 🆕 PaymentCallbackTest (+0 接口) -- **攻略服务** - - 🆕 AdminGuideArticleTest (+0 接口) - - 🆕 AdminGuideCategoryTest (+0 接口) - - 🆕 AdminGuideTagTest (+0 接口) - - 🆕 InternalWikiTest (+0 接口) -- **文件服务** - - 🆕 FileTest (+0 接口) -- **用户服务** - - 🆕 AdminAgreementTest (+0 接口) - - 🆕 AdminBannerTest (+0 接口) - - 🆕 AdminContactTest (+0 接口) - - 🆕 AdminCustomerTest (+0 接口) - - 🆕 AdminDesignerTest (+0 接口) - - 🆕 AdminExploreCategoryTest (+0 接口) - - 🆕 AdminFaqTest (+0 接口) - - 🆕 AdminFrontendConfigTest (+0 接口) - - 🆕 AdminProfileTest (+0 接口) - - 🆕 AdminTopicTest (+0 接口) - - 🆕 AdminUserTest (+0 接口) - - 🆕 AuthTest (+0 接口) - - 🆕 FavoriteTest (+0 接口) - - 🆕 FootprintTest (+0 接口) - - 🆕 InternalApprovalTest (+0 接口) - - 🆕 InternalBadgeTest (+0 接口) - - 🆕 InternalBannerTest (+0 接口) - - 🆕 InternalContactTest (+0 接口) - - 🆕 InternalDesignerTest (+0 接口) - - 🆕 InternalExploreCategoryTest (+0 接口) - - 🆕 InternalFaqTest (+0 接口) - - 🆕 InternalFrontendConfigTest (+0 接口) - - 🆕 InternalLikeTest (+0 接口) - - 🆕 InternalLoginLogTest (+0 接口) - - 🆕 InternalMpCommonTest (+0 接口) - - 🆕 InternalMpDictTest (+0 接口) - - 🆕 InternalMpMessageTest (+0 接口) - - 🆕 InternalMpUserTest (+0 接口) - - 🆕 InternalOrderUserTest (+0 接口) - - 🆕 InternalTopicTest (+0 接口) - - 🆕 InternalUserTest2 (+0 接口) - - 🆕 InternalWechatTest (+0 接口) - - 🆕 InternalWishTest (+0 接口) - - 🆕 PublicDictTest (+0 接口) - - 🆕 SysDictTest (+0 接口) - - 🆕 SysJobTest (+0 接口) - - 🆕 SysMenuTest (+0 接口) - - 🆕 SysRoleTest (+0 接口) - - 🆕 TravelerTest (+0 接口) - - 🆕 UserTest (+0 接口) - - 🆕 WechatSyncTest (+0 接口) -- **监控服务** - - 🆕 ApprovalLogTest (+0 接口) - - 🆕 DataRetentionTest (+0 接口) - - 🆕 ErrorLogTest (+0 接口) - - 🆕 InternalLogTest (+0 接口) - - 🆕 LoginLogTest (+0 接口) - - 🆕 MysqlMonitorTest (+0 接口) - - 🆕 NotificationLogTest (+0 接口) - - 🆕 OperationLogTest (+0 接口) - - 🆕 RedisMonitorTest (+0 接口) - - 🆕 RocketMqMonitorTest (+0 接口) - - 🆕 ServiceMonitorTest (+0 接口) -- **素材服务** - - Material (改1) - - 🆕 DictCacheServiceTest (+0 接口) -- **订单服务** - - 🆕 AdminAlbumTest (+0 接口) - - 🆕 AdminEarlyBirdTest (+0 接口) - - 🆕 AdminInvoiceTest (+0 接口) - - 🆕 AdminOrderConfigTest (+0 接口) - - 🆕 AdminOrderTest (+0 接口) - - 🆕 AdminOrderItineraryTest (+0 接口) - - 🆕 AdminOrderTodoTest (+0 接口) - - 🆕 AdminOrderTransportTest (+0 接口) - - 🆕 AdminRefundTest (+0 接口) - - 🆕 AdminRefundPolicyTest (+0 接口) - - 🆕 AdminWorkOrderTest (+0 接口) - - 🆕 InternalAlbumTest (+0 接口) - - 🆕 InternalAutoProcessTest (+0 接口) - - 🆕 InternalDashboardTest (+0 接口) - - 🆕 InternalDesignerOrderTest (+0 接口) - - 🆕 InternalEarlyBirdTest (+0 接口) - - 🆕 InternalInvoiceTest (+0 接口) - - 🆕 InternalMpOrderTest (+0 接口) - - 🆕 InternalMpTripTest (+0 接口) - - 🆕 InternalOrderStatsTest (+0 接口) - - 🆕 InternalOrderTransportTest (+0 接口) - - 🆕 InternalOrderTravelerTest (+0 接口) - - 🆕 InternalPaymentOrderTest (+0 接口) - - 🆕 InternalRefundTest (+0 接口) - - 🆕 MpOrderTest (+0 接口) - - 🆕 MpWeatherTest (+0 接口) -- **评价服务** - - 🆕 AdminReviewTest (+0 接口) - - 🆕 InternalMpReviewTest (+0 接口) - - 🆕 InternalReviewTest (+0 接口) -- **资源服务** - - 🆕 ActivityTest (+0 接口) - - 🆕 ActivityPriceCalendarTest (+0 接口) - - 🆕 ActivityTagTest (+0 接口) - - 🆕 InternalActivityTest (+0 接口) - - 🆕 InternalMpActivityTest (+0 接口) - - 🆕 InternalMpResourceBriefTest (+0 接口) - - 🆕 InternalResourceTest (+0 接口) - - 🆕 InternalResourceDetailTest (+0 接口) - - 🆕 InternalResourcePriceTest (+0 接口) - - 🆕 InternalResourceStatsTest (+0 接口) - - 🆕 CostItemTest (+0 接口) - - 🆕 CostPriceCalendarTest (+0 接口) - - 🆕 InternalCostTest (+0 接口) - - 🆕 HotelTest (+0 接口) - - 🆕 HotelTagTest (+0 接口) - - 🆕 InternalHotelTest (+0 接口) - - 🆕 InternalMpHotelTest (+0 接口) - - 🆕 RoomPriceCalendarTest (+0 接口) - - 🆕 RoomTypeTest (+0 接口) - - 🆕 InternalMpRestaurantTest (+0 接口) - - 🆕 InternalRestaurantTest (+0 接口) - - 🆕 RestaurantTest (+0 接口) - - 🆕 RestaurantTagTest (+0 接口) - - 🆕 InternalMpScenicTest (+0 接口) - - 🆕 InternalScenicTest (+0 接口) - - 🆕 ScenicPriceCalendarTest (+0 接口) - - 🆕 ScenicSeasonTest (+0 接口) - - 🆕 ScenicSpotTest (+0 接口) - - 🆕 ScenicTagTest (+0 接口) - - 🆕 InternalServiceTest (+0 接口) - - 🆕 ServiceItemTest (+0 接口) - - 🆕 ServicePriceCalendarTest (+0 接口) - - 🆕 ServiceTagTest (+0 接口) - - 🆕 InternalStaffTest (+0 接口) - - 🆕 StaffTest (+0 接口) - - 🆕 StaffPriceCalendarTest (+0 接口) - - 🆕 StaffTagTest (+0 接口) - - 🆕 InternalSuppliesTest (+0 接口) - - 🆕 SuppliesTest (+0 接口) - - 🆕 SuppliesTagTest (+0 接口) - - 🆕 InternalVehicleTest (+0 接口) - - 🆕 VehicleModelTest (+0 接口) - - 🆕 VehiclePriceCalendarTest (+0 接口) - - 🆕 VehicleTagTest (+0 接口) - ---- - -## 素材服务 - -### Material - -> 📖 **接口文档**: [http://192.168.100.236:8094/doc.html](http://192.168.100.236:8094/doc.html) → 标签 **「素材管理」** - -### ✏️ `DELETE` /admin/material/{materialId} — 删除素材 - -- 参数: materialId(Long), force(boolean) → materialId(Long) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ ActivityCreateRequest - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -#### ✏️ ActivityListVO - - - ❌ ~~`billingType`~~ (`String`) — 计费方式编码 - -#### ✏️ ActivityQueryRequest - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -#### ✏️ ActivityUpdateRequest - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -#### ✏️ ActivityVO - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M .gitignore -A hl-callback-service/src/test/java/com/hulalv/callback/EntityVoCoverageTest.java -A hl-callback-service/src/test/java/com/hulalv/callback/controller/MsgAuditCallbackControllerTest.java -A hl-common/src/test/java/com/hulalv/common/DtoCoverageTest.java -A hl-common/src/test/java/com/hulalv/common/MqMessageCoverageTest.java -A hl-common/src/test/java/com/hulalv/common/config/JacksonConfigTest.java -A hl-common/src/test/java/com/hulalv/common/exception/GlobalExceptionHandlerTest.java -A hl-common/src/test/java/com/hulalv/common/feign/FallbackFactoryTest.java -A hl-common/src/test/java/com/hulalv/common/result/PageResultTest.java -A hl-common/src/test/java/com/hulalv/common/result/ResultTest.java -A hl-common/src/test/java/com/hulalv/common/util/AmapStaticMapUtilTest.java -A hl-common/src/test/java/com/hulalv/common/util/DistributedLockUtilTest.java -A hl-common/src/test/java/com/hulalv/common/util/IpUtilsTest.java -A hl-common/src/test/java/com/hulalv/common/util/PageUtilTest.java -A hl-common/src/test/java/com/hulalv/common/util/TravelerTypeResolverTest.java -A hl-common/src/test/java/com/hulalv/common/weather/AmapWeatherClientTest.java -A hl-common/src/test/java/com/hulalv/common/weather/QWeatherClientTest.java -A hl-common/src/test/java/com/hulalv/common/weather/WeatherInfoCoverageTest.java -A hl-common/src/test/java/com/hulalv/common/weather/WeatherInfoTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/EntityDtoCoverageTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/constant/ContractConstantsTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/AdminClauseTemplateControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/AdminContractControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/AdminContractSchemeControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/ContractCallbackControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/InternalContractControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/InternalMpContractControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/interceptor/AdminAuthInterceptorTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/job/ContractStatusRefreshJobTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/tourage/TourageContractPlatformTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractCallbackServiceTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/service/ContractSchemeServiceTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/service/SafetyNoticeServiceTest.java -M hl-file-service/src/main/java/com/hulalv/file/config/OssConfig.java -A hl-file-service/src/test/java/com/hulalv/file/EntityDtoCoverageTest.java -A hl-file-service/src/test/java/com/hulalv/file/controller/FileControllerTest.java -A hl-file-service/src/test/java/com/hulalv/file/interceptor/AdminAuthInterceptorTest.java -A hl-file-service/src/test/java/com/hulalv/file/interceptor/UserAuthInterceptorTest.java -A hl-file-service/src/test/java/com/hulalv/file/service/ChunkUploadServiceTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/EntityDtoCoverageTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/AdminGuideArticleControllerTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/AdminGuideCategoryControllerTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/AdminGuideTagControllerTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/InternalWikiControllerTest.java -M hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialService.java -A hl-material-service/src/test/java/com/hulalv/material/EntityDtoCoverageTest.java -A hl-material-service/src/test/java/com/hulalv/material/controller/DictCacheServiceTest.java -A hl-material-service/src/test/java/com/hulalv/material/interceptor/AdminAuthInterceptorTest.java -A hl-material-service/src/test/java/com/hulalv/material/service/ChunkUploadServiceTest.java -M hl-material-service/src/test/java/com/hulalv/material/service/MaterialServiceTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/EntityCoverageTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/ApprovalLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/DataRetentionControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/ErrorLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/InternalLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/LoginLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/MysqlMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/NotificationLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/OperationLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/RedisMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/RocketMqMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/ServiceMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/interceptor/AdminAuthInterceptorTest.java -M hl-mp-service/src/main/java/com/hulalv/mp/service/WeatherService.java -A hl-mp-service/src/test/java/com/hulalv/mp/DtoCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/VoCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpActivityControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpAlbumControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpBadgeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpBannerControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpCommonControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpConfigControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpContractControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpCustomizeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpDesignerControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpDictControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpExploreControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpFavoriteControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpFootprintControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpHomeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpHotelControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpInsuranceControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpInvoiceControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpLikeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpMessageControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpOrderControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpOrderTransportControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpPaymentControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpRefundControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpRestaurantControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpReviewControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpScenicControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpSearchControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpTravelerControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpTripControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpUserControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpWeatherControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpWikiControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpWishControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/feign/FallbackFactoryTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/FootprintAggregationServiceTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/HomeAggregationServiceTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/ProductAggregationServiceTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/service/ResourceMapServiceDeepTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/service/ResourceMapServiceTest.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminAlbumControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminEarlyBirdControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminInvoiceControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderConfigControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderItineraryControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderTodoControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderTransportControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminRefundControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminRefundPolicyControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminWorkOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalAlbumControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalAutoProcessControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalDashboardControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalDesignerOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalEarlyBirdControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalInvoiceControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalMpOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalMpTripControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalOrderStatsControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalOrderTransportControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalOrderTravelerControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalPaymentOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalRefundControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/MpOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/MpWeatherControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/coverage/DtoVoCoverageTest.java -A hl-order-service/src/test/java/com/hulalv/order/coverage/EntityCoverageTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderTodoServiceTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/OrderTransportSegmentServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundApplicationServiceTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/EntityDtoCoverageTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/controller/AdminPaymentControllerTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/controller/InternalPaymentControllerTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/controller/PaymentCallbackControllerTest.java -D hl-product-service/src/main/java/com/hulalv/product/mq/consumer/ProductApprovalConsumer.java -D hl-product-service/src/main/java/com/hulalv/product/service/ApprovalPollingService.java -A hl-product-service/src/test/java/com/hulalv/product/controller/AdminBookingTermsControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/AdminWarmTipsControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/DistrictControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/FamilyControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/FormulaControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/GroupBatchControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/InternalMpProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/InternalProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ItineraryControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/MpProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/PricingControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductFolderControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductLineControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductPhotographyItemControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductSafetyItemControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductStudyGainControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/QuoteControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/SafetyTemplateControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/coverage/DtoVoCoverageTest.java -A hl-product-service/src/test/java/com/hulalv/product/coverage/EntityCoverageTest.java -D hl-product-service/src/test/java/com/hulalv/product/mq/consumer/ProductApprovalConsumerTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/CostCalculationServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/PriceCalendarServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductStatusServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/constant/ActivityConstants.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/entity/Activity.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/service/CostItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/RoomTypeService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSeasonService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/ActivityControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/ActivityTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/InternalActivityControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/InternalMpActivityControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalMpResourceBriefControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceDetailControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourcePriceControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceStatsControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/cost/controller/CostItemControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/cost/controller/CostPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/cost/controller/InternalCostControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/cost/service/CostItemServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/DtoVoCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/EntityCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/HotelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/HotelTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/InternalHotelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/InternalMpHotelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/RoomTypeControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/RoomPriceCalendarServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/RoomTypeServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/InternalRestaurantControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/RestaurantControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/RestaurantTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/restaurant/service/RestaurantServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/InternalMpScenicControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/InternalScenicControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicSeasonControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicSpotControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSeasonServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSpotServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/InternalServiceControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/ServiceItemControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/ServicePriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/ServiceTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/InternalStaffControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/StaffControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/StaffPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/StaffTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/staff/service/StaffServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/supplies/controller/InternalSuppliesControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/supplies/controller/SuppliesControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/supplies/controller/SuppliesTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/supplies/service/SuppliesServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/InternalVehicleControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/VehicleModelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/VehicleTagControllerTest.java -A hl-review-service/src/test/java/com/hulalv/review/EntityDtoCoverageTest.java -A hl-review-service/src/test/java/com/hulalv/review/controller/AdminReviewControllerTest.java -A hl-review-service/src/test/java/com/hulalv/review/controller/InternalMpReviewControllerTest.java -A hl-review-service/src/test/java/com/hulalv/review/controller/InternalReviewControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/EntityDtoCoverageTest.java -A hl-task-service/src/test/java/com/hulalv/task/controller/BoardControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/controller/TaskControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/controller/WebSocketDocControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/interceptor/AdminAuthInterceptorTest.java -A hl-task-service/src/test/java/com/hulalv/task/job/TaskReminderJobTest.java -A hl-task-service/src/test/java/com/hulalv/task/service/BoardEventServiceTest.java -A hl-task-service/src/test/java/com/hulalv/task/service/TaskActivityServiceTest.java -A hl-task-service/src/test/java/com/hulalv/task/service/TaskNotificationServiceTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/constant/TransportConstantsTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/service/FlightServiceTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/service/TrainServiceTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/service/VariFlightApiClientTest.java -M hl-user-service/src/main/java/com/hulalv/user/service/BadgeService.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminAgreementControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminBannerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminContactControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminCustomerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminDesignerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminExploreCategoryControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminFaqControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminFrontendConfigControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminProfileControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminTopicControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminUserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AuthControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/FavoriteControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/FootprintControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalApprovalControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalBadgeControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalBannerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalContactControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalDesignerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalExploreCategoryControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalFaqControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalFrontendConfigControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalLikeControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalLoginLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpCommonControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpDictControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpMessageControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpUserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalOrderUserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalTopicControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalUserControllerTest2.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalWechatControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalWishControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/PublicDictControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysDictControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysJobControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysMenuControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysRoleControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/TravelerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/UserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/WechatSyncControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/DtoVoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/EntityCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/feign/FallbackFactoryTest.java -A hl-user-service/src/test/java/com/hulalv/user/interceptor/TokenInterceptorTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/NotificationTemplateRendererTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/BadgeServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/BannerServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/DesignerServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FaqServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FinanceDashboardServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FrontendConfigServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/InsuranceSyncJobServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/PermissionServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/QuartzJobExecutorTest.java -M pom.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_1248_836cce5_test_15.md b/changelogs/2026-03/2026-03-30_1248_836cce5_test_15.md deleted file mode 100644 index 83e8d66..0000000 --- a/changelogs/2026-03/2026-03-30_1248_836cce5_test_15.md +++ /dev/null @@ -1,588 +0,0 @@ -# 接口变更记录 — 2026-03-30 12:48 - -> **提交** `836cce5` · **作者** wx · **时间** 2026-03-30 12:43:27 +0800 -> -> test: 单元测试覆盖率从15%提升到50%，修复7个真实bug - -## 变更总览 - -- **产品服务** - - 🆕 AdminBookingTermsTest (+0 接口) - - 🆕 AdminWarmTipsTest (+0 接口) - - 🆕 DistrictTest (+0 接口) - - 🆕 FamilyTest (+0 接口) - - 🆕 FormulaTest (+0 接口) - - 🆕 GroupBatchTest (+0 接口) - - 🆕 InternalMpProductTest (+0 接口) - - 🆕 InternalProductTest (+0 接口) - - 🆕 ItineraryTest (+0 接口) - - 🆕 MpProductTest (+0 接口) - - 🆕 PricingTest (+0 接口) - - 🆕 ProductTest (+0 接口) - - 🆕 ProductFolderTest (+0 接口) - - 🆕 ProductLineTest (+0 接口) - - 🆕 ProductPhotographyItemTest (+0 接口) - - 🆕 ProductSafetyItemTest (+0 接口) - - 🆕 ProductStudyGainTest (+0 接口) - - 🆕 QuoteTest (+0 接口) - - 🆕 SafetyTemplateTest (+0 接口) -- **任务服务** - - 🆕 BoardTest (+0 接口) - - 🆕 TaskTest (+0 接口) - - 🆕 WebSocketDocTest (+0 接口) -- **企微回调服务** - - 🆕 MsgAuditCallbackTest (+0 接口) -- **合同服务** - - 🆕 AdminClauseTemplateTest (+0 接口) - - 🆕 AdminContractTest (+0 接口) - - 🆕 AdminContractSchemeTest (+0 接口) - - 🆕 ContractCallbackTest (+0 接口) - - 🆕 InternalContractTest (+0 接口) - - 🆕 InternalMpContractTest (+0 接口) -- **小程序聚合服务** - - 🆕 MpActivityTest (+0 接口) - - 🆕 MpAlbumTest (+0 接口) - - 🆕 MpBadgeTest (+0 接口) - - 🆕 MpBannerTest (+0 接口) - - 🆕 MpCommonTest (+0 接口) - - 🆕 MpConfigTest (+0 接口) - - 🆕 MpContractTest (+0 接口) - - 🆕 MpCustomizeTest (+0 接口) - - 🆕 MpDesignerTest (+0 接口) - - 🆕 MpDictTest (+0 接口) - - 🆕 MpExploreTest (+0 接口) - - 🆕 MpFavoriteTest (+0 接口) - - 🆕 MpFootprintTest (+0 接口) - - 🆕 MpHomeTest (+0 接口) - - 🆕 MpHotelTest (+0 接口) - - 🆕 MpInsuranceTest (+0 接口) - - 🆕 MpInvoiceTest (+0 接口) - - 🆕 MpLikeTest (+0 接口) - - 🆕 MpMessageTest (+0 接口) - - 🆕 MpOrderTest (+0 接口) - - 🆕 MpOrderTransportTest (+0 接口) - - 🆕 MpPaymentTest (+0 接口) - - 🆕 MpProductTest (+0 接口) - - 🆕 MpRefundTest (+0 接口) - - 🆕 MpRestaurantTest (+0 接口) - - 🆕 MpReviewTest (+0 接口) - - 🆕 MpScenicTest (+0 接口) - - 🆕 MpSearchTest (+0 接口) - - 🆕 MpTravelerTest (+0 接口) - - 🆕 MpTripTest (+0 接口) - - 🆕 MpUserTest (+0 接口) - - 🆕 MpWeatherTest (+0 接口) - - 🆕 MpWikiTest (+0 接口) - - 🆕 MpWishTest (+0 接口) -- **支付服务** - - 🆕 AdminPaymentTest (+0 接口) - - 🆕 InternalPaymentTest (+0 接口) - - 🆕 PaymentCallbackTest (+0 接口) -- **攻略服务** - - 🆕 AdminGuideArticleTest (+0 接口) - - 🆕 AdminGuideCategoryTest (+0 接口) - - 🆕 AdminGuideTagTest (+0 接口) - - 🆕 InternalWikiTest (+0 接口) -- **文件服务** - - 🆕 FileTest (+0 接口) -- **用户服务** - - 🆕 AdminAgreementTest (+0 接口) - - 🆕 AdminBannerTest (+0 接口) - - 🆕 AdminContactTest (+0 接口) - - 🆕 AdminCustomerTest (+0 接口) - - 🆕 AdminDesignerTest (+0 接口) - - 🆕 AdminExploreCategoryTest (+0 接口) - - 🆕 AdminFaqTest (+0 接口) - - 🆕 AdminFrontendConfigTest (+0 接口) - - 🆕 AdminProfileTest (+0 接口) - - 🆕 AdminTopicTest (+0 接口) - - 🆕 AdminUserTest (+0 接口) - - 🆕 AuthTest (+0 接口) - - 🆕 FavoriteTest (+0 接口) - - 🆕 FootprintTest (+0 接口) - - 🆕 InternalApprovalTest (+0 接口) - - 🆕 InternalBadgeTest (+0 接口) - - 🆕 InternalBannerTest (+0 接口) - - 🆕 InternalContactTest (+0 接口) - - 🆕 InternalDesignerTest (+0 接口) - - 🆕 InternalExploreCategoryTest (+0 接口) - - 🆕 InternalFaqTest (+0 接口) - - 🆕 InternalFrontendConfigTest (+0 接口) - - 🆕 InternalLikeTest (+0 接口) - - 🆕 InternalLoginLogTest (+0 接口) - - 🆕 InternalMpCommonTest (+0 接口) - - 🆕 InternalMpDictTest (+0 接口) - - 🆕 InternalMpMessageTest (+0 接口) - - 🆕 InternalMpUserTest (+0 接口) - - 🆕 InternalOrderUserTest (+0 接口) - - 🆕 InternalTopicTest (+0 接口) - - 🆕 InternalUserTest2 (+0 接口) - - 🆕 InternalWechatTest (+0 接口) - - 🆕 InternalWishTest (+0 接口) - - 🆕 PublicDictTest (+0 接口) - - 🆕 SysDictTest (+0 接口) - - 🆕 SysJobTest (+0 接口) - - 🆕 SysMenuTest (+0 接口) - - 🆕 SysRoleTest (+0 接口) - - 🆕 TravelerTest (+0 接口) - - 🆕 UserTest (+0 接口) - - 🆕 WechatSyncTest (+0 接口) -- **监控服务** - - 🆕 ApprovalLogTest (+0 接口) - - 🆕 DataRetentionTest (+0 接口) - - 🆕 ErrorLogTest (+0 接口) - - 🆕 InternalLogTest (+0 接口) - - 🆕 LoginLogTest (+0 接口) - - 🆕 MysqlMonitorTest (+0 接口) - - 🆕 NotificationLogTest (+0 接口) - - 🆕 OperationLogTest (+0 接口) - - 🆕 RedisMonitorTest (+0 接口) - - 🆕 RocketMqMonitorTest (+0 接口) - - 🆕 ServiceMonitorTest (+0 接口) -- **素材服务** - - Material (改1) - - 🆕 DictCacheServiceTest (+0 接口) -- **订单服务** - - 🆕 AdminAlbumTest (+0 接口) - - 🆕 AdminEarlyBirdTest (+0 接口) - - 🆕 AdminInvoiceTest (+0 接口) - - 🆕 AdminOrderConfigTest (+0 接口) - - 🆕 AdminOrderTest (+0 接口) - - 🆕 AdminOrderItineraryTest (+0 接口) - - 🆕 AdminOrderTodoTest (+0 接口) - - 🆕 AdminOrderTransportTest (+0 接口) - - 🆕 AdminRefundTest (+0 接口) - - 🆕 AdminRefundPolicyTest (+0 接口) - - 🆕 AdminWorkOrderTest (+0 接口) - - 🆕 InternalAlbumTest (+0 接口) - - 🆕 InternalAutoProcessTest (+0 接口) - - 🆕 InternalDashboardTest (+0 接口) - - 🆕 InternalDesignerOrderTest (+0 接口) - - 🆕 InternalEarlyBirdTest (+0 接口) - - 🆕 InternalInvoiceTest (+0 接口) - - 🆕 InternalMpOrderTest (+0 接口) - - 🆕 InternalMpTripTest (+0 接口) - - 🆕 InternalOrderStatsTest (+0 接口) - - 🆕 InternalOrderTransportTest (+0 接口) - - 🆕 InternalOrderTravelerTest (+0 接口) - - 🆕 InternalPaymentOrderTest (+0 接口) - - 🆕 InternalRefundTest (+0 接口) - - 🆕 MpOrderTest (+0 接口) - - 🆕 MpWeatherTest (+0 接口) -- **评价服务** - - 🆕 AdminReviewTest (+0 接口) - - 🆕 InternalMpReviewTest (+0 接口) - - 🆕 InternalReviewTest (+0 接口) -- **资源服务** - - 🆕 ActivityTest (+0 接口) - - 🆕 ActivityPriceCalendarTest (+0 接口) - - 🆕 ActivityTagTest (+0 接口) - - 🆕 InternalActivityTest (+0 接口) - - 🆕 InternalMpActivityTest (+0 接口) - - 🆕 InternalMpResourceBriefTest (+0 接口) - - 🆕 InternalResourceTest (+0 接口) - - 🆕 InternalResourceDetailTest (+0 接口) - - 🆕 InternalResourcePriceTest (+0 接口) - - 🆕 InternalResourceStatsTest (+0 接口) - - 🆕 CostItemTest (+0 接口) - - 🆕 CostPriceCalendarTest (+0 接口) - - 🆕 InternalCostTest (+0 接口) - - 🆕 HotelTest (+0 接口) - - 🆕 HotelTagTest (+0 接口) - - 🆕 InternalHotelTest (+0 接口) - - 🆕 InternalMpHotelTest (+0 接口) - - 🆕 RoomPriceCalendarTest (+0 接口) - - 🆕 RoomTypeTest (+0 接口) - - 🆕 InternalMpRestaurantTest (+0 接口) - - 🆕 InternalRestaurantTest (+0 接口) - - 🆕 RestaurantTest (+0 接口) - - 🆕 RestaurantTagTest (+0 接口) - - 🆕 InternalMpScenicTest (+0 接口) - - 🆕 InternalScenicTest (+0 接口) - - 🆕 ScenicPriceCalendarTest (+0 接口) - - 🆕 ScenicSeasonTest (+0 接口) - - 🆕 ScenicSpotTest (+0 接口) - - 🆕 ScenicTagTest (+0 接口) - - 🆕 InternalServiceTest (+0 接口) - - 🆕 ServiceItemTest (+0 接口) - - 🆕 ServicePriceCalendarTest (+0 接口) - - 🆕 ServiceTagTest (+0 接口) - - 🆕 InternalStaffTest (+0 接口) - - 🆕 StaffTest (+0 接口) - - 🆕 StaffPriceCalendarTest (+0 接口) - - 🆕 StaffTagTest (+0 接口) - - 🆕 InternalSuppliesTest (+0 接口) - - 🆕 SuppliesTest (+0 接口) - - 🆕 SuppliesTagTest (+0 接口) - - 🆕 InternalVehicleTest (+0 接口) - - 🆕 VehicleModelTest (+0 接口) - - 🆕 VehiclePriceCalendarTest (+0 接口) - - 🆕 VehicleTagTest (+0 接口) - ---- - -## 素材服务 - -### Material - -> 📖 **接口文档**: [http://192.168.100.236:8094/doc.html](http://192.168.100.236:8094/doc.html) → 标签 **「素材管理」** - -### ✏️ `DELETE` /admin/material/{materialId} — 删除素材 - -- 参数: materialId(Long), force(boolean) → materialId(Long) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ ActivityCreateRequest - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -#### ✏️ ActivityListVO - - - ❌ ~~`billingType`~~ (`String`) — 计费方式编码 - -#### ✏️ ActivityQueryRequest - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -#### ✏️ ActivityUpdateRequest - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -#### ✏️ ActivityVO - - - ❌ ~~`billingType`~~ (`String`) — 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M .gitignore -A hl-callback-service/src/test/java/com/hulalv/callback/EntityVoCoverageTest.java -A hl-callback-service/src/test/java/com/hulalv/callback/controller/MsgAuditCallbackControllerTest.java -A hl-common/src/test/java/com/hulalv/common/DtoCoverageTest.java -A hl-common/src/test/java/com/hulalv/common/MqMessageCoverageTest.java -A hl-common/src/test/java/com/hulalv/common/config/JacksonConfigTest.java -A hl-common/src/test/java/com/hulalv/common/exception/GlobalExceptionHandlerTest.java -A hl-common/src/test/java/com/hulalv/common/feign/FallbackFactoryTest.java -A hl-common/src/test/java/com/hulalv/common/result/PageResultTest.java -A hl-common/src/test/java/com/hulalv/common/result/ResultTest.java -A hl-common/src/test/java/com/hulalv/common/util/AmapStaticMapUtilTest.java -A hl-common/src/test/java/com/hulalv/common/util/DistributedLockUtilTest.java -A hl-common/src/test/java/com/hulalv/common/util/IpUtilsTest.java -A hl-common/src/test/java/com/hulalv/common/util/PageUtilTest.java -A hl-common/src/test/java/com/hulalv/common/util/TravelerTypeResolverTest.java -A hl-common/src/test/java/com/hulalv/common/weather/AmapWeatherClientTest.java -A hl-common/src/test/java/com/hulalv/common/weather/QWeatherClientTest.java -A hl-common/src/test/java/com/hulalv/common/weather/WeatherInfoCoverageTest.java -A hl-common/src/test/java/com/hulalv/common/weather/WeatherInfoTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/EntityDtoCoverageTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/constant/ContractConstantsTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/AdminClauseTemplateControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/AdminContractControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/AdminContractSchemeControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/ContractCallbackControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/InternalContractControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/controller/InternalMpContractControllerTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/interceptor/AdminAuthInterceptorTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/job/ContractStatusRefreshJobTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/platform/tourage/TourageContractPlatformTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractCallbackServiceTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/service/ContractSchemeServiceTest.java -M hl-contract-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -A hl-contract-service/src/test/java/com/hulalv/contract/service/SafetyNoticeServiceTest.java -M hl-file-service/src/main/java/com/hulalv/file/config/OssConfig.java -A hl-file-service/src/test/java/com/hulalv/file/EntityDtoCoverageTest.java -A hl-file-service/src/test/java/com/hulalv/file/controller/FileControllerTest.java -A hl-file-service/src/test/java/com/hulalv/file/interceptor/AdminAuthInterceptorTest.java -A hl-file-service/src/test/java/com/hulalv/file/interceptor/UserAuthInterceptorTest.java -A hl-file-service/src/test/java/com/hulalv/file/service/ChunkUploadServiceTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/EntityDtoCoverageTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/AdminGuideArticleControllerTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/AdminGuideCategoryControllerTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/AdminGuideTagControllerTest.java -A hl-guide-service/src/test/java/com/hulalv/guide/controller/InternalWikiControllerTest.java -M hl-material-service/src/main/java/com/hulalv/material/controller/MaterialController.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialService.java -A hl-material-service/src/test/java/com/hulalv/material/EntityDtoCoverageTest.java -A hl-material-service/src/test/java/com/hulalv/material/controller/DictCacheServiceTest.java -A hl-material-service/src/test/java/com/hulalv/material/interceptor/AdminAuthInterceptorTest.java -A hl-material-service/src/test/java/com/hulalv/material/service/ChunkUploadServiceTest.java -M hl-material-service/src/test/java/com/hulalv/material/service/MaterialServiceTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/EntityCoverageTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/ApprovalLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/DataRetentionControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/ErrorLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/InternalLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/LoginLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/MysqlMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/NotificationLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/OperationLogControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/RedisMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/RocketMqMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/controller/ServiceMonitorControllerTest.java -A hl-monitor-service/src/test/java/com/hulalv/monitor/interceptor/AdminAuthInterceptorTest.java -M hl-mp-service/src/main/java/com/hulalv/mp/service/WeatherService.java -A hl-mp-service/src/test/java/com/hulalv/mp/DtoCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/VoCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpActivityControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpAlbumControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpBadgeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpBannerControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpCommonControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpConfigControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpContractControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpCustomizeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpDesignerControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpDictControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpExploreControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpFavoriteControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpFootprintControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpHomeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpHotelControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpInsuranceControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpInvoiceControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpLikeControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpMessageControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpOrderControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpOrderTransportControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpPaymentControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpRefundControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpRestaurantControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpReviewControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpScenicControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpSearchControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpTravelerControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpTripControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpUserControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpWeatherControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpWikiControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpWishControllerTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/feign/FallbackFactoryTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/FootprintAggregationServiceTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/HomeAggregationServiceTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/ProductAggregationServiceTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/service/ResourceMapServiceDeepTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/service/ResourceMapServiceTest.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminAlbumControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminEarlyBirdControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminInvoiceControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderConfigControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderItineraryControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderTodoControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminOrderTransportControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminRefundControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminRefundPolicyControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/AdminWorkOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalAlbumControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalAutoProcessControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalDashboardControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalDesignerOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalEarlyBirdControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalInvoiceControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalMpOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalMpTripControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalOrderStatsControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalOrderTransportControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalOrderTravelerControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalPaymentOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/InternalRefundControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/MpOrderControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/controller/MpWeatherControllerTest.java -A hl-order-service/src/test/java/com/hulalv/order/coverage/DtoVoCoverageTest.java -A hl-order-service/src/test/java/com/hulalv/order/coverage/EntityCoverageTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderTodoServiceTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/OrderTransportSegmentServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundApplicationServiceTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/EntityDtoCoverageTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/controller/AdminPaymentControllerTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/controller/InternalPaymentControllerTest.java -A hl-payment-service/src/test/java/com/hulalv/payment/controller/PaymentCallbackControllerTest.java -D hl-product-service/src/main/java/com/hulalv/product/mq/consumer/ProductApprovalConsumer.java -D hl-product-service/src/main/java/com/hulalv/product/service/ApprovalPollingService.java -A hl-product-service/src/test/java/com/hulalv/product/controller/AdminBookingTermsControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/AdminWarmTipsControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/DistrictControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/FamilyControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/FormulaControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/GroupBatchControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/InternalMpProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/InternalProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ItineraryControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/MpProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/PricingControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductFolderControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductLineControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductPhotographyItemControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductSafetyItemControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/ProductStudyGainControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/QuoteControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/controller/SafetyTemplateControllerTest.java -A hl-product-service/src/test/java/com/hulalv/product/coverage/DtoVoCoverageTest.java -A hl-product-service/src/test/java/com/hulalv/product/coverage/EntityCoverageTest.java -D hl-product-service/src/test/java/com/hulalv/product/mq/consumer/ProductApprovalConsumerTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/CostCalculationServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/PriceCalendarServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductStatusServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/constant/ActivityConstants.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/ActivityController.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/controller/InternalActivityController.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/entity/Activity.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/cost/service/CostItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/RoomTypeService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSeasonService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/ActivityControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/ActivityPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/ActivityTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/InternalActivityControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/activity/controller/InternalMpActivityControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalMpResourceBriefControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceDetailControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourcePriceControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceStatsControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/cost/controller/CostItemControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/cost/controller/CostPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/cost/controller/InternalCostControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/cost/service/CostItemServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/DtoVoCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/EntityCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/HotelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/HotelTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/InternalHotelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/InternalMpHotelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/RoomPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/hotel/controller/RoomTypeControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/RoomPriceCalendarServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/RoomTypeServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/InternalMpRestaurantControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/InternalRestaurantControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/RestaurantControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/restaurant/controller/RestaurantTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/restaurant/service/RestaurantServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/InternalMpScenicControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/InternalScenicControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicSeasonControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicSpotControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/scenic/controller/ScenicTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSeasonServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSpotServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/InternalServiceControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/ServiceItemControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/ServicePriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/service/controller/ServiceTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/InternalStaffControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/StaffControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/StaffPriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/staff/controller/StaffTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/staff/service/StaffServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/supplies/controller/InternalSuppliesControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/supplies/controller/SuppliesControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/supplies/controller/SuppliesTagControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/supplies/service/SuppliesServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/InternalVehicleControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/VehicleModelControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/VehiclePriceCalendarControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/vehicle/controller/VehicleTagControllerTest.java -A hl-review-service/src/test/java/com/hulalv/review/EntityDtoCoverageTest.java -A hl-review-service/src/test/java/com/hulalv/review/controller/AdminReviewControllerTest.java -A hl-review-service/src/test/java/com/hulalv/review/controller/InternalMpReviewControllerTest.java -A hl-review-service/src/test/java/com/hulalv/review/controller/InternalReviewControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/EntityDtoCoverageTest.java -A hl-task-service/src/test/java/com/hulalv/task/controller/BoardControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/controller/TaskControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/controller/WebSocketDocControllerTest.java -A hl-task-service/src/test/java/com/hulalv/task/interceptor/AdminAuthInterceptorTest.java -A hl-task-service/src/test/java/com/hulalv/task/job/TaskReminderJobTest.java -A hl-task-service/src/test/java/com/hulalv/task/service/BoardEventServiceTest.java -A hl-task-service/src/test/java/com/hulalv/task/service/TaskActivityServiceTest.java -A hl-task-service/src/test/java/com/hulalv/task/service/TaskNotificationServiceTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/constant/TransportConstantsTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/service/FlightServiceTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/service/TrainServiceTest.java -A hl-transport-service/src/test/java/com/hulalv/transport/service/VariFlightApiClientTest.java -M hl-user-service/src/main/java/com/hulalv/user/service/BadgeService.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminAgreementControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminBannerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminContactControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminCustomerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminDesignerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminExploreCategoryControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminFaqControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminFrontendConfigControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminProfileControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminTopicControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AdminUserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AuthControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/FavoriteControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/FootprintControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalApprovalControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalBadgeControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalBannerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalContactControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalDesignerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalExploreCategoryControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalFaqControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalFrontendConfigControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalLikeControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalLoginLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpCommonControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpDictControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpMessageControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalMpUserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalOrderUserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalTopicControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalUserControllerTest2.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalWechatControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalWishControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/PublicDictControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysDictControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysJobControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysMenuControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/SysRoleControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/TravelerControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/UserControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/WechatSyncControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/DtoVoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/EntityCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/feign/FallbackFactoryTest.java -A hl-user-service/src/test/java/com/hulalv/user/interceptor/TokenInterceptorTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/NotificationTemplateRendererTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/BadgeServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/BannerServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/DesignerServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FaqServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FinanceDashboardServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FrontendConfigServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/InsuranceSyncJobServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/PermissionServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/QuartzJobExecutorTest.java -M pom.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_1628_4a4db91_fix_resource-servic.md b/changelogs/2026-03/2026-03-30_1628_4a4db91_fix_resource-servic.md deleted file mode 100644 index 8bb7b2b..0000000 --- a/changelogs/2026-03/2026-03-30_1628_4a4db91_fix_resource-servic.md +++ /dev/null @@ -1,57 +0,0 @@ -# 接口变更记录 — 2026-03-30 16:28 - -> **提交** `4a4db91` · **作者** wx · **时间** 2026-03-30 16:28:59 +0800 -> -> fix: resource-service coverMaterialId类型修复 + activity billingType恢复 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ ActivityCreateRequest - - - 🆕 `billingType` (`String`) — 计费类型：PER_PERSON=按人 PER_GROUP=按团 PER_TIME=按次 - -#### ✏️ ActivityListVO - - - 🆕 `billingType` (`String`) — 计费类型：PER_PERSON=按人 PER_GROUP=按团 PER_TIME=按次 - -#### ✏️ ActivityQueryRequest - - - 🆕 `billingType` (`String`) — 计费类型：PER_PERSON=按人 PER_GROUP=按团 PER_TIME=按次 - -#### ✏️ ActivityUpdateRequest - - - 🆕 `billingType` (`String`) — 计费类型：PER_PERSON=按人 PER_GROUP=按团 PER_TIME=按次 - -#### ✏️ ActivityVO - - - 🆕 `billingType` (`String`) — 计费类型：PER_PERSON=按人 PER_GROUP=按团 PER_TIME=按次 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/activity/constant/ActivityConstants.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityQueryRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/ActivityUpdateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/entity/Activity.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/vo/ActivityVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/RoomTypeService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSeasonService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/restaurant/service/RestaurantServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSpotServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_1711_f2bcbb4_fix.md b/changelogs/2026-03/2026-03-30_1711_f2bcbb4_fix.md deleted file mode 100644 index 93c2bd5..0000000 --- a/changelogs/2026-03/2026-03-30_1711_f2bcbb4_fix.md +++ /dev/null @@ -1,152 +0,0 @@ -# 接口变更记录 — 2026-03-30 17:11 - -> **提交** `f2bcbb4` · **作者** wx · **时间** 2026-03-30 17:11:21 +0800 -> -> fix: 全面防御服务器内部错误（扫描前端+后端，83个文件） - -## 变更总览 - -- **小程序聚合服务** - - MpOrder (+1, 改1) - - MpReview (+1, 改2) - - MpSearch (+1, 改1) - ---- - -## 小程序聚合服务 - -### MpOrder - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 订单接口」** - -### 🆕 `GET` /mp/order/mp/order - -### ✏️ `GET` /mp/order/lookup — 通过联系人手机号+姓名查找订单（无需登录） - -- 参数: contactPhone(String), contactName(String) → 无 - -### MpReview - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 评价接口」** - -### 🆕 `GET` /mp/review/mp/review - -### ✏️ `GET` /mp/review/search — 关键词搜索评价(公开) - -- 参数: keyword(String), targetType(String), targetId(Long), page(Integer), pageSize(Integer) → targetType(String), targetId(Long), page(Integer), pageSize(Integer) - -### ✏️ `GET` /mp/review/featured — 精选评价列表(公开) - -- 参数: limit(Integer) → 无 - -### MpSearch - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 搜索接口」** - -### 🆕 `GET` /mp/search/mp/search - -### ✏️ `GET` /mp/search — 搜索产品 - -- 参数: keyword(String), productType(String), page(Integer), pageSize(Integer) → productType(String), page(Integer), pageSize(Integer) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpFeedbackRequest - - - ❌ ~~`images`~~ (`List<String>`) — 图片URL列表 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-file-service/src/main/java/com/hulalv/file/dto/BatchFileRequest.java -M hl-material-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java -M hl-material-service/src/main/java/com/hulalv/material/dto/BatchDeleteRequest.java -M hl-material-service/src/main/java/com/hulalv/material/dto/BatchMaterialIdsRequest.java -M hl-material-service/src/main/java/com/hulalv/material/dto/BatchTagRequest.java -M hl-material-service/src/main/java/com/hulalv/material/dto/RefBatchBindRequest.java -M hl-material-service/src/main/java/com/hulalv/material/dto/RefBatchUnbindRequest.java -M hl-material-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialRefService.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialService.java -M hl-material-service/src/main/java/com/hulalv/material/service/MaterialTagService.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpAlbumController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpContractController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpCustomizeController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFavoriteController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpFootprintController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpMessageController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpFeedbackRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpProductQuoteRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpReviewCreateRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpTravelerRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AlbumFileBatchAddRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/MpUpdateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/RefundAppealRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/UpdateDepositRequest.java -M hl-payment-service/src/main/java/com/hulalv/payment/dto/PrepayRequest.java -M hl-payment-service/src/main/java/com/hulalv/payment/dto/RefundRequest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ItineraryDayRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/NodeCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/feign/dto/BatchMaterialIdsRequest.java -M hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchBindRequest.java -M hl-product-service/src/main/java/com/hulalv/product/feign/dto/RefBatchUnbindRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/BatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/BatchMaterialIdsRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBatchBindRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBatchUnbindRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/controller/HotelTagController.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/BatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/BatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/BatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/BatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffBatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/BatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesTagService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/BatchTagRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/dto/VehicleBatchDeleteRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleTagService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_2213_c5ae7682_refactor_hl-common.md b/changelogs/2026-03/2026-03-30_2213_c5ae7682_refactor_hl-common.md deleted file mode 100644 index 3f5e96d..0000000 --- a/changelogs/2026-03/2026-03-30_2213_c5ae7682_refactor_hl-common.md +++ /dev/null @@ -1,304 +0,0 @@ -# 接口变更记录 — 2026-03-30 22:13 - -> **提交** `c5ae7682` · **作者** wx · **时间** 2026-03-30 22:13:09 +0800 -> -> refactor: hl-common拆分为9个子模块（参考若依RuoYi-Cloud架构） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 公共模块 - -#### ❌ ~~AdminBasicDTO~~ - -#### ❌ ~~ApprovalLogDTO~~ - -#### ❌ ~~ApprovalResultDTO~~ - -#### ❌ ~~ApprovalSubmitDTO~~ - -#### ❌ ~~ApprovalSubmitResultDTO~~ - -#### ❌ ~~DepartmentDTO~~ - -#### ❌ ~~ErrorLogDTO~~ - -#### ❌ ~~ExternalContactEventDTO~~ - -#### ❌ ~~FileBindRefsDTO~~ - -#### ❌ ~~FileUnbindRefsDTO~~ - -#### ❌ ~~NotificationLogDTO~~ - -#### ❌ ~~OperationLogDTO~~ - -#### ❌ ~~OrderPayInfoDTO~~ - -#### ❌ ~~PaymentRefundRequest~~ - -#### ❌ ~~PaymentResultDTO~~ - -#### ❌ ~~RefundResultDTO~~ - -#### ❌ ~~ResourceDetailDTO~~ - -#### ❌ ~~TravelerValidationDTO~~ - -#### ❌ ~~WechatDeptSyncDTO~~ - -#### ❌ ~~WechatMessageDTO~~ - -#### ❌ ~~WechatUserSyncDTO~~ - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-callback-service/pom.xml -A hl-common/hl-common-core/pom.xml -A hl-common/hl-common-core/src/main/java/com/hulalv/common/config/EncryptionConfig.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/config/JacksonConfig.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/constant/HttpHeaderConstants.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/constant/RedisKeyConstants.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ApprovalLogDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ApprovalResultDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ApprovalSubmitDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ApprovalSubmitResultDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/DepartmentDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ErrorLogDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/NotificationLogDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/OperationLogDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/PaymentRefundRequest.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/RefundResultDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/exception/AuthenticationException.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/exception/BusinessException.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/exception/ForbiddenException.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/exception/NotFoundException.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/result/PageResult.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/result/Result.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/util/AesEncryptUtil.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/util/AmapStaticMapUtil.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/util/IpUtils.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/util/SnowflakeIdWorker.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/weather/AmapWeatherClient.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/weather/QWeatherClient.java -A hl-common/hl-common-core/src/main/java/com/hulalv/common/weather/WeatherInfo.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/DtoCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/DtoFieldCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/config/EncryptionConfigTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/config/JacksonConfigTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/result/PageResultTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/result/ResultTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/AesEncryptUtilTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/AmapStaticMapUtilTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/IpUtilsTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/SnowflakeIdWorkerTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/AmapWeatherClientTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/QWeatherClientTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/WeatherInfoCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/WeatherInfoTest.java -A hl-common/hl-common-feign/pom.xml -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/config/FeignRetryConfig.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/config/MonitorFeignConfig.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/ApprovalFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/ApprovalFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/FileFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/FileFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/MonitorFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/MonitorFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/OrderRefundFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/OrderRefundFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/OrderTravelerFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/OrderTravelerFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/PaymentRefundFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/PaymentRefundFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/ProductApprovalFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/ProductApprovalFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/ResourceApprovalFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/ResourceApprovalFeignFallbackFactory.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/UserFeignClient.java -A hl-common/hl-common-feign/src/main/java/com/hulalv/common/feign/UserFeignFallbackFactory.java -A hl-common/hl-common-feign/src/test/java/com/hulalv/common/config/FeignRetryConfigTest.java -A hl-common/hl-common-feign/src/test/java/com/hulalv/common/config/MonitorFeignConfigTest.java -A hl-common/hl-common-feign/src/test/java/com/hulalv/common/feign/FallbackFactoryTest.java -A hl-common/hl-common-log/pom.xml -A hl-common/hl-common-log/src/main/java/com/hulalv/common/annotation/OperationLog.java -A hl-common/hl-common-log/src/main/java/com/hulalv/common/aspect/OperationLogAspect.java -A hl-common/hl-common-log/src/main/java/com/hulalv/common/exception/GlobalExceptionHandler.java -A hl-common/hl-common-log/src/test/java/com/hulalv/common/aspect/OperationLogAspectTest.java -A hl-common/hl-common-log/src/test/java/com/hulalv/common/exception/GlobalExceptionHandlerTest.java -A hl-common/hl-common-mq/pom.xml -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/MqGroupConstants.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/MqTagConstants.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/MqTopicConstants.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/message/NotificationEventMessage.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/message/OrderDepartureMessage.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/message/OrderExpiryMessage.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/message/OrderTripEndMessage.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/message/ResourcePriceChangeMessage.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/message/WechatNotificationMessage.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/producer/MqLogProducer.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/producer/MqNotificationEventProducer.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/producer/MqResourcePriceChangeProducer.java -A hl-common/hl-common-mq/src/main/java/com/hulalv/common/mq/producer/MqWechatNotificationProducer.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/MqMessageCoverageTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/producer/MqLogProducerTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/producer/MqNotificationEventProducerTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/producer/MqResourcePriceChangeProducerTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/producer/MqWechatNotificationProducerTest.java -A hl-common/hl-common-mybatis/pom.xml -A hl-common/hl-common-mybatis/src/main/java/com/hulalv/common/mybatis/EncryptTypeHandler.java -A hl-common/hl-common-mybatis/src/main/java/com/hulalv/common/util/PageUtil.java -A hl-common/hl-common-mybatis/src/test/java/com/hulalv/common/mybatis/EncryptTypeHandlerTest.java -A hl-common/hl-common-mybatis/src/test/java/com/hulalv/common/util/PageUtilTest.java -A hl-common/hl-common-oss/pom.xml -A hl-common/hl-common-redis/pom.xml -A hl-common/hl-common-redis/src/main/java/com/hulalv/common/util/DistributedLockUtil.java -A hl-common/hl-common-redis/src/main/java/com/hulalv/common/util/TravelerTypeResolver.java -A hl-common/hl-common-redis/src/test/java/com/hulalv/common/util/DistributedLockUtilTest.java -A hl-common/hl-common-redis/src/test/java/com/hulalv/common/util/TravelerTypeResolverTest.java -A hl-common/hl-common-security/pom.xml -A hl-common/hl-common-security/src/main/java/com/hulalv/common/util/JwtUtil.java -A hl-common/hl-common-security/src/test/java/com/hulalv/common/util/JwtUtilTest.java -A hl-common/hl-common-web/pom.xml -M hl-common/pom.xml -D hl-common/src/main/java/com/hulalv/common/annotation/OperationLog.java -D hl-common/src/main/java/com/hulalv/common/aspect/OperationLogAspect.java -D hl-common/src/main/java/com/hulalv/common/config/EncryptionConfig.java -D hl-common/src/main/java/com/hulalv/common/config/FeignRetryConfig.java -D hl-common/src/main/java/com/hulalv/common/config/JacksonConfig.java -D hl-common/src/main/java/com/hulalv/common/config/MonitorFeignConfig.java -D hl-common/src/main/java/com/hulalv/common/constant/HttpHeaderConstants.java -D hl-common/src/main/java/com/hulalv/common/constant/RedisKeyConstants.java -D hl-common/src/main/java/com/hulalv/common/dto/AdminBasicDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ApprovalLogDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ApprovalResultDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ApprovalSubmitDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ApprovalSubmitResultDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/DepartmentDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ErrorLogDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ExternalContactEventDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/FileBindRefsDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/FileUnbindRefsDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/NotificationLogDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/OperationLogDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/PaymentRefundRequest.java -D hl-common/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/RefundResultDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/ResourceDetailDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/TravelerValidationDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/WechatDeptSyncDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/WechatMessageDTO.java -D hl-common/src/main/java/com/hulalv/common/dto/WechatUserSyncDTO.java -D hl-common/src/main/java/com/hulalv/common/exception/AuthenticationException.java -D hl-common/src/main/java/com/hulalv/common/exception/BusinessException.java -D hl-common/src/main/java/com/hulalv/common/exception/ForbiddenException.java -D hl-common/src/main/java/com/hulalv/common/exception/GlobalExceptionHandler.java -D hl-common/src/main/java/com/hulalv/common/exception/NotFoundException.java -D hl-common/src/main/java/com/hulalv/common/feign/ApprovalFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/ApprovalFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/FileFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/FileFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/MonitorFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/MonitorFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/OrderRefundFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/OrderRefundFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/OrderTravelerFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/OrderTravelerFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/PaymentRefundFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/PaymentRefundFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/ProductApprovalFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/ProductApprovalFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/ResourceApprovalFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/ResourceApprovalFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/feign/UserFeignClient.java -D hl-common/src/main/java/com/hulalv/common/feign/UserFeignFallbackFactory.java -D hl-common/src/main/java/com/hulalv/common/mq/MqGroupConstants.java -D hl-common/src/main/java/com/hulalv/common/mq/MqTagConstants.java -D hl-common/src/main/java/com/hulalv/common/mq/MqTopicConstants.java -D hl-common/src/main/java/com/hulalv/common/mq/message/NotificationEventMessage.java -D hl-common/src/main/java/com/hulalv/common/mq/message/OrderDepartureMessage.java -D hl-common/src/main/java/com/hulalv/common/mq/message/OrderExpiryMessage.java -D hl-common/src/main/java/com/hulalv/common/mq/message/OrderTripEndMessage.java -D hl-common/src/main/java/com/hulalv/common/mq/message/ResourcePriceChangeMessage.java -D hl-common/src/main/java/com/hulalv/common/mq/message/WechatNotificationMessage.java -D hl-common/src/main/java/com/hulalv/common/mq/producer/MqLogProducer.java -D hl-common/src/main/java/com/hulalv/common/mq/producer/MqNotificationEventProducer.java -D hl-common/src/main/java/com/hulalv/common/mq/producer/MqResourcePriceChangeProducer.java -D hl-common/src/main/java/com/hulalv/common/mq/producer/MqWechatNotificationProducer.java -D hl-common/src/main/java/com/hulalv/common/mybatis/EncryptTypeHandler.java -D hl-common/src/main/java/com/hulalv/common/result/PageResult.java -D hl-common/src/main/java/com/hulalv/common/result/Result.java -D hl-common/src/main/java/com/hulalv/common/util/AesEncryptUtil.java -D hl-common/src/main/java/com/hulalv/common/util/AmapStaticMapUtil.java -D hl-common/src/main/java/com/hulalv/common/util/DistributedLockUtil.java -D hl-common/src/main/java/com/hulalv/common/util/IpUtils.java -D hl-common/src/main/java/com/hulalv/common/util/JwtUtil.java -D hl-common/src/main/java/com/hulalv/common/util/PageUtil.java -D hl-common/src/main/java/com/hulalv/common/util/SnowflakeIdWorker.java -D hl-common/src/main/java/com/hulalv/common/util/TravelerTypeResolver.java -D hl-common/src/main/java/com/hulalv/common/weather/AmapWeatherClient.java -D hl-common/src/main/java/com/hulalv/common/weather/QWeatherClient.java -D hl-common/src/main/java/com/hulalv/common/weather/WeatherInfo.java -D hl-common/src/test/java/com/hulalv/common/DtoCoverageTest.java -D hl-common/src/test/java/com/hulalv/common/DtoFieldCoverageTest.java -D hl-common/src/test/java/com/hulalv/common/MqMessageCoverageTest.java -D hl-common/src/test/java/com/hulalv/common/aspect/OperationLogAspectTest.java -D hl-common/src/test/java/com/hulalv/common/config/EncryptionConfigTest.java -D hl-common/src/test/java/com/hulalv/common/config/FeignRetryConfigTest.java -D hl-common/src/test/java/com/hulalv/common/config/JacksonConfigTest.java -D hl-common/src/test/java/com/hulalv/common/config/MonitorFeignConfigTest.java -D hl-common/src/test/java/com/hulalv/common/exception/GlobalExceptionHandlerTest.java -D hl-common/src/test/java/com/hulalv/common/feign/FallbackFactoryTest.java -D hl-common/src/test/java/com/hulalv/common/mq/producer/MqLogProducerTest.java -D hl-common/src/test/java/com/hulalv/common/mq/producer/MqNotificationEventProducerTest.java -D hl-common/src/test/java/com/hulalv/common/mq/producer/MqResourcePriceChangeProducerTest.java -D hl-common/src/test/java/com/hulalv/common/mq/producer/MqWechatNotificationProducerTest.java -D hl-common/src/test/java/com/hulalv/common/mybatis/EncryptTypeHandlerTest.java -D hl-common/src/test/java/com/hulalv/common/result/PageResultTest.java -D hl-common/src/test/java/com/hulalv/common/result/ResultTest.java -D hl-common/src/test/java/com/hulalv/common/util/AesEncryptUtilTest.java -D hl-common/src/test/java/com/hulalv/common/util/AmapStaticMapUtilTest.java -D hl-common/src/test/java/com/hulalv/common/util/DistributedLockUtilTest.java -D hl-common/src/test/java/com/hulalv/common/util/IpUtilsTest.java -D hl-common/src/test/java/com/hulalv/common/util/JwtUtilTest.java -D hl-common/src/test/java/com/hulalv/common/util/PageUtilTest.java -D hl-common/src/test/java/com/hulalv/common/util/SnowflakeIdWorkerTest.java -D hl-common/src/test/java/com/hulalv/common/util/TravelerTypeResolverTest.java -D hl-common/src/test/java/com/hulalv/common/weather/AmapWeatherClientTest.java -D hl-common/src/test/java/com/hulalv/common/weather/QWeatherClientTest.java -D hl-common/src/test/java/com/hulalv/common/weather/WeatherInfoCoverageTest.java -D hl-common/src/test/java/com/hulalv/common/weather/WeatherInfoTest.java -M hl-contract-service/pom.xml -M hl-file-service/pom.xml -M hl-gateway/pom.xml -M hl-guide-service/pom.xml -M hl-insurance-service/pom.xml -M hl-material-service/pom.xml -M hl-monitor-service/pom.xml -M hl-mp-service/pom.xml -M hl-order-service/pom.xml -M hl-payment-service/pom.xml -M hl-product-service/pom.xml -M hl-resource-service/pom.xml -M hl-review-service/pom.xml -M hl-task-service/pom.xml -M hl-transport-service/pom.xml -M hl-user-service/pom.xml -M pom.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-30_2220_a59cd643_refactor_11_5.md b/changelogs/2026-03/2026-03-30_2220_a59cd643_refactor_11_5.md deleted file mode 100644 index e84a43c..0000000 --- a/changelogs/2026-03/2026-03-30_2220_a59cd643_refactor_11_5.md +++ /dev/null @@ -1,7280 +0,0 @@ -# 接口变更记录 — 2026-03-30 22:20 - -> **提交** `a59cd643` · **作者** wx · **时间** 2026-03-30 22:20:22 +0800 -> -> refactor: 11个微服务合并为5个，运行时12进程降为6进程 - -## 变更总览 - -- **用户服务** - - 🆕 MsgAuditCallback (+2 接口) - - 🆕 WxCallback (+4 接口) - - 🆕 File (+9 接口) - - 🆕 InternalFile (+10 接口) - - 🆕 MpFile (+4 接口) - - 🆕 ApprovalLog (+2 接口) - - 🆕 DataRetention (+1 接口) - - 🆕 ErrorLog (+2 接口) - - 🆕 InternalLog (+5 接口) - - 🆕 LoginLog (+1 接口) - - 🆕 MysqlMonitor (+3 接口) - - 🆕 NotificationLog (+2 接口) - - 🆕 OperationLog (+2 接口) - - 🆕 RedisMonitor (+1 接口) - - 🆕 RocketMqMonitor (+3 接口) - - 🆕 ServiceMonitor (+1 接口) - - 🆕 AdminReview (+6 接口) - - 🆕 InternalMpReview (+10 接口) - - 🆕 InternalReview (+8 接口) - - 🆕 Board (+13 接口) - - 🆕 Task (+13 接口) - - 🆕 WebSocketDoc (+1 接口) - - 🆕 MsgAuditCallbackTest (+0 接口) - - 🆕 WxCallbackTest (+0 接口) - - 🆕 FileTest (+0 接口) - - 🆕 ApprovalLogTest (+0 接口) - - 🆕 DataRetentionTest (+0 接口) - - 🆕 ErrorLogTest (+0 接口) - - 🆕 InternalLogTest (+0 接口) - - 🆕 LoginLogTest (+0 接口) - - 🆕 MysqlMonitorTest (+0 接口) - - 🆕 NotificationLogTest (+0 接口) - - 🆕 OperationLogTest (+0 接口) - - 🆕 RedisMonitorTest (+0 接口) - - 🆕 RocketMqMonitorTest (+0 接口) - - 🆕 ServiceMonitorTest (+0 接口) - - 🆕 AdminReviewTest (+0 接口) - - 🆕 InternalMpReviewTest (+0 接口) - - 🆕 InternalReviewTest (+0 接口) - - 🆕 BoardTest (+0 接口) - - 🆕 TaskTest (+0 接口) - - 🆕 WebSocketDocTest (+0 接口) -- **订单服务** - - 🆕 AdminClauseTemplate (+6 接口) - - 🆕 AdminContract (+14 接口) - - 🆕 AdminContractScheme (+7 接口) - - 🆕 ContractCallback (+2 接口) - - 🆕 InternalContract (+7 接口) - - 🆕 InternalMpContract (+5 接口) - - 🆕 AdminInsurance (+23 接口) - - 🆕 AdminInsuranceScheme (+8 接口) - - 🆕 InternalInsurance (+13 接口) - - 🆕 AdminPayment (+9 接口) - - 🆕 InternalPayment (+5 接口) - - 🆕 PaymentCallback (+3 接口) - - 🆕 AdminClauseTemplateTest (+0 接口) - - 🆕 AdminContractTest (+0 接口) - - 🆕 AdminContractSchemeTest (+0 接口) - - 🆕 ContractCallbackTest (+0 接口) - - 🆕 InternalContractTest (+0 接口) - - 🆕 InternalMpContractTest (+0 接口) - - 🆕 AdminPaymentTest (+0 接口) - - 🆕 InternalPaymentTest (+0 接口) - - 🆕 PaymentCallbackTest (+0 接口) -- **资源服务** - - 🆕 AdminGuideArticle (+8 接口) - - 🆕 AdminGuideCategory (+7 接口) - - 🆕 AdminGuideTag (+6 接口) - - 🆕 InternalWiki (+4 接口) - - 🆕 DictCacheService (+0 接口) - - 🆕 InternalMaterial (+6 接口) - - 🆕 MaterialCategoryPermission (+2 接口) - - 🆕 Material (+20 接口) - - 🆕 MaterialTag (+6 接口) - - 🆕 MpMaterial (+1 接口) - - 🆕 AdminTransport (+7 接口) - - 🆕 InternalTransport (+2 接口) - - 🆕 AdminGuideArticleTest (+0 接口) - - 🆕 AdminGuideCategoryTest (+0 接口) - - 🆕 AdminGuideTagTest (+0 接口) - - 🆕 InternalWikiTest (+0 接口) - - 🆕 DictCacheServiceTest (+0 接口) - ---- - -## 用户服务 - -### 🆕 新增: MsgAuditCallback - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【回调接口】会话内容存档」** - -### 📌 `GET` /callback/msg-audit — 会话内容存档回调URL验证 - -> 企业微信会话内容存档的回调URL验证端点。使用独立的Token/AESKey，在企微后台配置会话存档回调URL时进行验证。 - -**参数** - - - `msgSignature` (`String`) — 查询参数 - - `timestamp` (`String`) — 查询参数 - - `nonce` (`String`) — 查询参数 - - `echostr` (`String`) — 查询参数 - -**响应** `String` - -### 📌 `POST` /callback/msg-audit — 接收会话内容存档事件通知 - -> 企业微信在有新的存档消息时推送事件通知到此端点。通知仅表示'有新消息可拉取'，收到后异步触发消息拉取任务（通过Finance SDK API主动拉取具体内容并存储）。必须5秒内返回'success'。 - -**参数** - - - `msgSignature` (`String`) — 查询参数 - - `timestamp` (`String`) — 查询参数 - - `nonce` (`String`) — 查询参数 - -**响应** `String` - -### 🆕 新增: WxCallback - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【回调接口】企业微信回调」** - -### 📌 `GET` /wx/callback/app — 回调URL验证 - -> 企业微信自建应用的回调URL验证端点。企微在配置回调URL时发送GET请求，需解密echostr并返回明文以完成验证。无需JWT认证，使用企微自有的签名校验机制。 - -**参数** - - - `msgSignature` (`String`) — 查询参数 - - `timestamp` (`String`) — 查询参数 - - `nonce` (`String`) — 查询参数 - - `echostr` (`String`) — 查询参数 - -**响应** `String` - -### 📌 `POST` /wx/callback/app — 接收回调事件 - -> 企业微信自建应用的事件接收端点。接收加密XML格式的事件通知（审批变更、消息等），解密后按事件类型分发：change_contact→通讯录变更，change_external_contact→外部联系人变更，open_approval_change→审批状态变更。必须5秒内返回'success'。 - -**参数** - - - `msgSignature` (`String`) — 查询参数 - - `timestamp` (`String`) — 查询参数 - - `nonce` (`String`) — 查询参数 - -**响应** `String` - -### 📌 `GET` /wx/callback/contacts — 联系人同步URL验证 - -> 企业微信通讯录同步的回调URL验证端点。使用独立的Token/AESKey（与应用回调不同），用于接收通讯录变更事件的回调URL配置验证。 - -**参数** - - - `msgSignature` (`String`) — 查询参数 - - `timestamp` (`String`) — 查询参数 - - `nonce` (`String`) — 查询参数 - - `echostr` (`String`) — 查询参数 - -**响应** `String` - -### 📌 `POST` /wx/callback/contacts — 接收联系人同步事件 - -> 企业微信通讯录变更事件接收端点。接收员工创建/更新/删除、部门变更等事件，解密后转发给ContactChangeHandler处理，同步更新本地管理员数据。必须5秒内返回'success'。 - -**参数** - - - `msgSignature` (`String`) — 查询参数 - - `timestamp` (`String`) — 查询参数 - - `nonce` (`String`) — 查询参数 - -**响应** `String` - -### 🆕 新增: File - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「文件管理」** - -### 📌 `POST` /admin/file/upload/token — 请求上传凭证 - -> 上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求 - -**请求体** `UploadTokenRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileName` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `forcePresigned` | `boolean` | 强制使用预签名URL（跳过STS分片模式） | - -**响应** `Result<UploadTokenVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `uploadMode` | `String` | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `contentType` | `String` | 上传时必须使用的Content-Type（与预签名URL签名一致） | -| `presignedUrl` | `String` | 预签名上传URL | -| `ossKey` | `String` | OSS对象Key | -| `expireAt` | `LocalDateTime` | 过期时间 | -| `stsToken` | `StsTokenInfo` | STS临时凭证 | -| `bucket` | `String` | OSS Bucket名称 | -| `region` | `String` | OSS Region | -| `file` | `FileVO` | 秒传文件信息 | -| `accessKeyId` | `String` | AccessKey ID | -| `accessKeySecret` | `String` | AccessKey Secret | -| `securityToken` | `String` | 安全令牌 | -| `expiration` | `String` | 过期时间 | - -### 📌 `POST` /admin/file/upload/confirm — 确认上传完成 - -> 上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储 - -**请求体** `UploadConfirmRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | - -**响应** `Result<FileVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `fileName` | `String` | 文件名 | -| `fileType` | `String` | 文件类型 | -| `mimeType` | `String` | MIME类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `previewUrl` | `String` | 预览地址 | -| `groupKey` | `String` | 业务分组 | -| `status` | `String` | 文件状态 | -| `refCount` | `Integer` | 引用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/file/list — 文件列表（分页） - -> 支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） -- file_status：文件状态（显示） - -**响应** `Result<IPage<FileVO>>` - -### 📌 `GET` /admin/file/{fileId} — 文件详情 - -> **关联字典**： -- file_type：文件类型（显示） -- file_status：文件状态（显示） - -**参数** - - - `{fileId}` (`Long`) — 路径参数：文件ID - -**响应** `Result<FileVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `fileName` | `String` | 文件名 | -| `fileType` | `String` | 文件类型 | -| `mimeType` | `String` | MIME类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `previewUrl` | `String` | 预览地址 | -| `groupKey` | `String` | 业务分组 | -| `status` | `String` | 文件状态 | -| `refCount` | `Integer` | 引用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/file/{fileId} — 删除文件 - -> 软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理 - -**参数** - - - `{fileId}` (`Long`) — 路径参数：文件ID - -**响应** `Result<Void>` - -### 📌 `GET` /admin/file/{fileId}/refs — 文件引用列表 - -> 查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除 - -**参数** - - - `{fileId}` (`Long`) — 路径参数：文件ID - -**响应** `Result<List<FileRefVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refId` | `String` | 引用ID | -| `fileId` | `String` | 文件ID | -| `bizType` | `String` | 业务类型 | -| `bizId` | `String` | 业务ID | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/file/stats — 存储统计 - -> 返回文件总数、总存储空间、各类型文件占比等统计信息 - -**响应** `Result<FileStatsVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `totalCount` | `Long` | 文件总数 | -| `totalSize` | `Long` | 文件总大小(字节) | -| `countByType` | `Map<String, Long>` | 按类型统计文件数量 | -| `sizeByType` | `Map<String, Long>` | 按类型统计文件大小 | -| `countByGroup` | `Map<String, Long>` | 按分组统计文件数量 | - -### 📌 `GET` /admin/file/{fileId}/preview — 文件内容流式预览 - -> 流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件 - -**参数** - - - `{fileId}` (`Long`) — 路径参数：文件ID - -**响应** `void` - -### 📌 `GET` /admin/file/preview-by-url — 通过URL预览文件 - -> 传入完整的OSS文件URL，返回HTML预览页面（PDF用PDF.js渲染，图片直接展示）。 - -**响应** `void` - -### 🆕 新增: InternalFile - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【内部接口】文件（Feign调用）」** - -### 📌 `POST` /internal/file/bindRefs — 绑定文件到业务实体 - -> 将文件与业务实体建立引用关系（如景区ID+封面图），同一文件可被多个业务实体引用 - -**请求体** `BindRefsRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `bizType` | `String` | 业务类型 | -| `bizId` | `Long` | 业务ID | -| `fileIds` | `List<Long>` | 文件ID列表 | - -**响应** `Result<Void>` - -### 📌 `POST` /internal/file/unbindRefs — 解绑业务实体的所有文件 - -> 删除指定业务类型+业务ID下的所有文件引用关系，常用于业务实体删除时的级联清理 - -**请求体** `UnbindRefsRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `bizType` | `String` | 业务类型 | -| `bizId` | `Long` | 业务ID | - -**响应** `Result<Void>` - -### 📌 `POST` /internal/file/byIds — 批量获取文件信息 - -> 内部服务间调用。根据文件ID列表批量查询文件信息（含OSS URL、文件名、类型等），用于其他服务获取关联文件的详细数据。 - -**请求体** `BatchFileRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileIds` | `List<Long>` | 文件ID列表 | - -**响应** `Result<List<FileVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `fileName` | `String` | 文件名 | -| `fileType` | `String` | 文件类型 | -| `mimeType` | `String` | MIME类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `previewUrl` | `String` | 预览地址 | -| `groupKey` | `String` | 业务分组 | -| `status` | `String` | 文件状态 | -| `refCount` | `Integer` | 引用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /internal/file/upload/token — 内部上传凭证（素材服务调用） - -> 内部服务间调用。素材服务代理调用，为指定管理员生成OSS上传预签名URL和临时凭证，用于素材库的文件上传流程。 - -**参数** - - - `adminId` (`Long`) — 查询参数 - -**请求体** `UploadTokenRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileName` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `forcePresigned` | `boolean` | 强制使用预签名URL（跳过STS分片模式） | - -**响应** `Result<UploadTokenVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `uploadMode` | `String` | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `contentType` | `String` | 上传时必须使用的Content-Type（与预签名URL签名一致） | -| `presignedUrl` | `String` | 预签名上传URL | -| `ossKey` | `String` | OSS对象Key | -| `expireAt` | `LocalDateTime` | 过期时间 | -| `stsToken` | `StsTokenInfo` | STS临时凭证 | -| `bucket` | `String` | OSS Bucket名称 | -| `region` | `String` | OSS Region | -| `file` | `FileVO` | 秒传文件信息 | -| `accessKeyId` | `String` | AccessKey ID | -| `accessKeySecret` | `String` | AccessKey Secret | -| `securityToken` | `String` | 安全令牌 | -| `expiration` | `String` | 过期时间 | - -### 📌 `POST` /internal/file/upload/direct — 内部直接上传文件（服务间调用） - -> 服务间直接上传文件到OSS，跳过预签名流程。返回OSS公开访问URL，适用于后端生成的文件（如路线地图截图） - -**参数** - - - `file` (`MultipartFile`) — 查询参数 - - `groupKey` (`String`) — 查询参数 - -**响应** `Result<String>` - -### 📌 `POST` /internal/file/upload/confirm — 内部确认上传（素材服务调用） - -> 内部服务间调用。素材服务代理调用，确认文件已上传至OSS并创建文件记录。支持MD5去重。 - -**参数** - - - `adminId` (`Long`) — 查询参数 - -**请求体** `UploadConfirmRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | - -**响应** `Result<FileVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `fileName` | `String` | 文件名 | -| `fileType` | `String` | 文件类型 | -| `mimeType` | `String` | MIME类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `previewUrl` | `String` | 预览地址 | -| `groupKey` | `String` | 业务分组 | -| `status` | `String` | 文件状态 | -| `refCount` | `Integer` | 引用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /internal/file/upload/chunk/init — 分片上传-初始化 - -> 大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用complete接口合并 - -**参数** - - - `adminId` (`Long`) — 查询参数 - -**请求体** `ChunkUploadInitRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `filename` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小（字节） | -| `contentType` | `String` | 文件MIME类型 | -| `fileHash` | `String` | 文件MD5哈希（用于去重） | - -**响应** `Result<ChunkUploadInitVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `uploadId` | `String` | 上传ID（OSS multipart uploadId） | -| `chunkSize` | `int` | 推荐分片大小（字节） | -| `fileId` | `String` | 文件ID（file_info记录） | -| `ossKey` | `String` | OSS对象Key | - -### 📌 `POST` /internal/file/upload/chunk — 分片上传-上传分片 - -> 大文件上传第二步：逐个上传分片，返回分片的ETag用于后续合并校验。支持断点续传，已上传的分片无需重传 - -**参数** - - - `uploadId` (`String`) — 查询参数 - - `chunkIndex` (`int`) — 查询参数 - - `chunk` (`MultipartFile`) — 查询参数 - -**响应** `Result<ChunkUploadPartVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `etag` | `String` | 分片ETag（用于合并时校验） | - -### 📌 `POST` /internal/file/upload/chunk/complete — 分片上传-完成合并 - -> 大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建文件记录 - -**请求体** `ChunkUploadCompleteRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `uploadId` | `String` | 上传ID | - -**响应** `Result<FileVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `fileName` | `String` | 文件名 | -| `fileType` | `String` | 文件类型 | -| `mimeType` | `String` | MIME类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `previewUrl` | `String` | 预览地址 | -| `groupKey` | `String` | 业务分组 | -| `status` | `String` | 文件状态 | -| `refCount` | `Integer` | 引用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /internal/file/upload/chunk/cancel — 分片上传-取消 - -> 取消分片上传任务，清理已上传的分片数据和OSS临时文件 - -**请求体** `ChunkUploadCancelRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `uploadId` | `String` | 上传ID | - -**响应** `Result<Void>` - -### 🆕 新增: MpFile - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「C端文件上传」** - -### 📌 `GET` /mp/file/mp/file - -### 📌 `POST` /mp/file/upload — 上传文件（C端用户） - -> 小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar - -**参数** - - - `file` (`MultipartFile`) — 查询参数：上传文件 - - `groupKey` (`String`) — 查询参数：文件分组标识 - -**响应** `Result<FileVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `fileName` | `String` | 文件名 | -| `fileType` | `String` | 文件类型 | -| `mimeType` | `String` | MIME类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件MD5哈希 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `previewUrl` | `String` | 预览地址 | -| `groupKey` | `String` | 业务分组 | -| `status` | `String` | 文件状态 | -| `refCount` | `Integer` | 引用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /mp/file/{fileId}/preview — 文件内容流式预览 - -> 流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。 - -**参数** - - - `{fileId}` (`Long`) — 路径参数：文件ID - -**响应** `void` - -### 📌 `GET` /mp/file/preview-by-url — 文件在线预览 - -> 返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档 - -**响应** `void` - -### 🆕 新增: ApprovalLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「企微审批日志」** - -### 📌 `GET` /admin/monitor/approval-logs — 审批日志分页查询 - -> 查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选 - -**关联字典**： -- approval_sp_status：审批状态（列表筛选+显示） - -**参数** - - - `page` (`int`) — 查询参数：页码 - - `pageSize` (`int`) — 查询参数：每页条数 - - `spStatus` (`Integer`) — 查询参数：审批状态 - - `applyUserName` (`String`) — 查询参数：申请人姓名 - - `spName` (`String`) — 查询参数：审批模板名称 - - `startTime` (`String`) — 查询参数：开始时间 - - `endTime` (`String`) — 查询参数：结束时间 - -**响应** `Result<PageResult<ApprovalLog>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `approvalLogId` | `Long` | 审批日志ID | -| `thirdNo` | `String` | 审批编号 | -| `spName` | `String` | 审批模板名称 | -| `templateId` | `String` | 审批模板ID | -| `spStatus` | `Integer` | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -| `applyUserId` | `String` | 申请人企微UserID | -| `applyUserName` | `String` | 申请人姓名 | -| `applyTime` | `LocalDateTime` | 申请时间 | -| `approvalNodes` | `String` | 审批节点详情(JSON) | -| `notifyNodes` | `String` | 抄送节点详情(JSON) | -| `applyData` | `String` | 申请表单数据(JSON) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/monitor/approval-logs/{id} — 审批日志详情 - -> **关联字典**： -- approval_sp_status：审批状态（显示） - -**参数** - - - `{id}` (`Long`) — 路径参数：日志ID - -**响应** `Result<ApprovalLog>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `approvalLogId` | `Long` | 审批日志ID | -| `thirdNo` | `String` | 审批编号 | -| `spName` | `String` | 审批模板名称 | -| `templateId` | `String` | 审批模板ID | -| `spStatus` | `Integer` | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -| `applyUserId` | `String` | 申请人企微UserID | -| `applyUserName` | `String` | 申请人姓名 | -| `applyTime` | `LocalDateTime` | 申请时间 | -| `approvalNodes` | `String` | 审批节点详情(JSON) | -| `notifyNodes` | `String` | 抄送节点详情(JSON) | -| `applyData` | `String` | 申请表单数据(JSON) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 🆕 新增: DataRetention - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「数据清理」** - -### 📌 `POST` /admin/monitor/data-retention/cleanup — 手动触发数据清理 - -> 仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数 - -**响应** `Result<Map<String, Integer>>` - -### 🆕 新增: ErrorLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「错误日志」** - -### 📌 `GET` /admin/monitor/error-logs — 错误日志分页查询 - -> 查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧 - -**参数** - - - `page` (`int`) — 查询参数：页码 - - `pageSize` (`int`) — 查询参数：每页条数 - - `serviceName` (`String`) — 查询参数：服务名称 - - `exceptionClass` (`String`) — 查询参数：异常类名 - - `startTime` (`String`) — 查询参数：开始时间 - - `endTime` (`String`) — 查询参数：结束时间 - -**响应** `Result<PageResult<ErrorLog>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `errorLogId` | `Long` | 错误日志ID | -| `serviceName` | `String` | 服务名称 | -| `requestUrl` | `String` | 请求URL | -| `requestMethod` | `String` | 请求方法 | -| `requestParams` | `String` | 请求参数(JSON) | -| `adminId` | `Long` | 管理员ID | -| `exceptionClass` | `String` | 异常类名 | -| `exceptionMessage` | `String` | 异常消息 | -| `stackTrace` | `String` | 堆栈跟踪 | -| `ipAddress` | `String` | IP地址 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/monitor/error-logs/{id} — 错误日志详情 - -> 返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。 - -**参数** - - - `{id}` (`Long`) — 路径参数：日志ID - -**响应** `Result<ErrorLog>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `errorLogId` | `Long` | 错误日志ID | -| `serviceName` | `String` | 服务名称 | -| `requestUrl` | `String` | 请求URL | -| `requestMethod` | `String` | 请求方法 | -| `requestParams` | `String` | 请求参数(JSON) | -| `adminId` | `Long` | 管理员ID | -| `exceptionClass` | `String` | 异常类名 | -| `exceptionMessage` | `String` | 异常消息 | -| `stackTrace` | `String` | 堆栈跟踪 | -| `ipAddress` | `String` | IP地址 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: InternalLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【内部接口】日志接收（Feign调用）」** - -### 📌 `POST` /internal/monitor/operation-log — 接收操作日志 - -> 各微服务通过AOP拦截@OperationLog注解的方法，异步发送操作日志到此接口存储 - -**请求体** `OperationLogDTO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adminId` | `Long` | 管理员ID | -| `adminName` | `String` | 管理员名称 | -| `module` | `String` | 操作模块 | -| `description` | `String` | 操作描述 | -| `requestMethod` | `String` | 请求方法 | -| `requestUrl` | `String` | 请求URL | -| `requestParams` | `String` | 请求参数(JSON) | -| `responseCode` | `Integer` | 响应状态码 | -| `responseMsg` | `String` | 响应消息 | -| `ipAddress` | `String` | IP地址 | -| `duration` | `Integer` | 耗时(毫秒) | -| `status` | `Integer` | 状态: 0-成功, 1-失败 | -| `errorMsg` | `String` | 错误信息 | -| `serviceName` | `String` | 服务名称 | - -**响应** `Result<Void>` - -### 📌 `POST` /internal/monitor/error-log — 接收错误日志 - -> 各微服务的GlobalExceptionHandler捕获异常后，异步发送错误日志到此接口存储 - -**请求体** `ErrorLogDTO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `serviceName` | `String` | 服务名称 | -| `requestUrl` | `String` | 请求URL | -| `requestMethod` | `String` | 请求方法 | -| `requestParams` | `String` | 请求参数(JSON) | -| `adminId` | `Long` | 管理员ID | -| `exceptionClass` | `String` | 异常类名 | -| `exceptionMessage` | `String` | 异常消息 | -| `stackTrace` | `String` | 堆栈跟踪 | -| `ipAddress` | `String` | IP地址 | - -**响应** `Result<Void>` - -### 📌 `POST` /internal/monitor/notification-log — 接收通知日志 - -> 通知服务发送消息（短信/站内信/企微等）后，记录发送结果到此接口 - -**请求体** `NotificationLogDTO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `notificationType` | `String` | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -| `userId` | `String` | 员工企微UserID | -| `userName` | `String` | 员工姓名 | -| `externalUserId` | `String` | 外部联系人ID | -| `externalUserName` | `String` | 外部联系人姓名 | -| `messageContent` | `String` | 消息内容 | -| `sendStatus` | `Integer` | 发送状态: 0-成功, 1-失败, 2-已过滤 | -| `failReason` | `String` | 失败原因 | -| `serviceName` | `String` | 来源服务名称 | - -**响应** `Result<Void>` - -### 📌 `POST` /internal/monitor/approval-log — 接收审批日志 - -> 企微回调服务接收审批事件后，发送审批日志到此接口。同一审批单号会更新已有记录（按thirdNo去重） - -**请求体** `ApprovalLogDTO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `thirdNo` | `String` | 审批编号 | -| `spName` | `String` | 审批模板名称 | -| `templateId` | `String` | 审批模板ID | -| `spStatus` | `Integer` | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销 | -| `applyUserId` | `String` | 申请人企微UserID | -| `applyUserName` | `String` | 申请人姓名 | -| `applyTime` | `Long` | 申请时间(Unix时间戳秒) | -| `approvalNodes` | `String` | 审批节点详情(JSON) | -| `notifyNodes` | `String` | 抄送节点详情(JSON) | -| `applyData` | `String` | 申请表单数据(JSON) | - -**响应** `Result<Void>` - -### 📌 `GET` /internal/monitor/notification-log/customer-stats — 获取用户客户统计 - -> 统计指定用户的客户增减数据（新增客户数/流失客户数），用于客户管理看板 - -**参数** - - - `userId` (`String`) — 查询参数 - -### 🆕 新增: LoginLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「登录日志」** - -### 📌 `GET` /admin/monitor/login-logs — 登录日志分页查询 - -> 查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果 - -**关联字典**： -- login_status：登录状态（列表筛选+显示） - -**参数** - - - `page` (`int`) — 查询参数：页码 - - `pageSize` (`int`) — 查询参数：每页条数 - - `adminId` (`Long`) — 查询参数：管理员ID - - `status` (`String`) — 查询参数：状态 - - `startTime` (`String`) — 查询参数：开始时间 - - `endTime` (`String`) — 查询参数：结束时间 - -### 🆕 新增: MysqlMonitor - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「MySQL监控」** - -### 📌 `GET` /admin/monitor/mysql — MySQL实时监控数据 - -> 返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标 - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /admin/monitor/mysql/tables — 表空间列表 - -> 查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库 - -**参数** - - - `schema` (`String`) — 查询参数：数据库名 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `GET` /admin/monitor/mysql/slow-queries — 慢SQL查询统计 - -> 仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等 - -**参数** - - - `limit` (`int`) — 查询参数：返回条数 - - `type` (`String`) — 查询参数：查询类型 - -**响应** `Result<List<Map<String, Object>>>` - -### 🆕 新增: NotificationLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「消息通知日志」** - -### 📌 `GET` /admin/monitor/notification-logs — 消息通知日志分页查询 - -> 查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选 - -**关联字典**： -- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败） - -**参数** - - - `page` (`int`) — 查询参数：页码 - - `pageSize` (`int`) — 查询参数：每页条数 - - `notificationType` (`String`) — 查询参数：通知类型 - - `userName` (`String`) — 查询参数：用户名 - - `sendStatus` (`Integer`) — 查询参数：发送状态 - - `startTime` (`String`) — 查询参数：开始时间 - - `endTime` (`String`) — 查询参数：结束时间 - -**响应** `Result<PageResult<NotificationLog>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `notificationLogId` | `Long` | 通知日志ID | -| `notificationType` | `String` | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -| `userId` | `String` | 员工企微UserID | -| `userName` | `String` | 员工姓名 | -| `externalUserId` | `String` | 外部联系人ID | -| `externalUserName` | `String` | 外部联系人姓名 | -| `messageContent` | `String` | 消息内容 | -| `sendStatus` | `Integer` | 发送状态: 0-成功, 1-失败, 2-已过滤 | -| `failReason` | `String` | 失败原因 | -| `serviceName` | `String` | 来源服务名称 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/monitor/notification-logs/{id} — 消息通知日志详情 - -> 返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。 - -**参数** - - - `{id}` (`Long`) — 路径参数：日志ID - -**响应** `Result<NotificationLog>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `notificationLogId` | `Long` | 通知日志ID | -| `notificationType` | `String` | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -| `userId` | `String` | 员工企微UserID | -| `userName` | `String` | 员工姓名 | -| `externalUserId` | `String` | 外部联系人ID | -| `externalUserName` | `String` | 外部联系人姓名 | -| `messageContent` | `String` | 消息内容 | -| `sendStatus` | `Integer` | 发送状态: 0-成功, 1-失败, 2-已过滤 | -| `failReason` | `String` | 失败原因 | -| `serviceName` | `String` | 来源服务名称 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: OperationLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「操作日志」** - -### 📌 `GET` /admin/monitor/operation-logs — 操作日志分页查询 - -> 查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息 - -**操作状态**：0=成功, 1=失败（非字典，代码常量） - -**参数** - - - `page` (`int`) — 查询参数：页码 - - `pageSize` (`int`) — 查询参数：每页条数 - - `module` (`String`) — 查询参数：模块名称 - - `adminId` (`Long`) — 查询参数：管理员ID - - `status` (`Integer`) — 查询参数：状态 - - `startTime` (`String`) — 查询参数：开始时间 - - `endTime` (`String`) — 查询参数：结束时间 - -**响应** `Result<PageResult<OperationLog>>` - -### 📌 `GET` /admin/monitor/operation-logs/{id} — 操作日志详情 - -> 返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。 - -**参数** - - - `{id}` (`Long`) — 路径参数：日志ID - -**响应** `Result<OperationLog>` - -### 🆕 新增: RedisMonitor - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「Redis监控」** - -### 📌 `GET` /admin/monitor/redis — Redis实时监控数据 - -> 返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标 - -**响应** `Result<Map<String, Object>>` - -### 🆕 新增: RocketMqMonitor - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「RocketMQ监控」** - -### 📌 `GET` /admin/monitor/rocketmq — RocketMQ概览 - -> 返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标 - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /admin/monitor/rocketmq/topics — Topic统计 - -> 返回各Topic的消息量、最新偏移量和消费进度等信息 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `GET` /admin/monitor/rocketmq/consumer-groups — 消费者组统计 - -> 返回各消费者组的消费进度、积压量和在线消费者实例信息 - -**响应** `Result<List<Map<String, Object>>>` - -### 🆕 新增: ServiceMonitor - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「服务监控」** - -### 📌 `GET` /admin/monitor/services — 微服务列表和健康状态 - -> 从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果 - -**响应** `Result<List<Map<String, Object>>>` - -### 🆕 新增: AdminReview - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「管理端-评价审核」** - -### 📌 `GET` /admin/review/list — 评价列表(支持好中差评/有图/有视频筛选) - -> 分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选 - -**关联字典**： -- review_status：评价审核状态（列表筛选+显示） -- rating_level：评价等级（列表筛选+显示） - -**响应** `Result<PageResult<ReviewListVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签 | -| `content` | `String` | 评价内容 | -| `imageCount` | `Integer` | 图片数量 | -| `videoCount` | `Integer` | 视频数量 | -| `status` | `String` | 评价状态 | -| `statusLabel` | `String` | 评价状态标签 | -| `rejectReason` | `String` | 拒绝原因 | -| `auditorName` | `String` | 审核人姓名 | -| `auditedAt` | `LocalDateTime` | 审核时间 | -| `hasReply` | `Boolean` | 是否已回复 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/review/{reviewId} — 评价详情 - -> **关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**参数** - - - `{reviewId}` (`Long`) — 路径参数：评价ID - -**响应** `Result<ReviewVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `String` | 用户ID | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `hasImage` | `Boolean` | 是否有图片 | -| `hasVideo` | `Boolean` | 是否有视频 | -| `imageCount` | `Integer` | 图片数量 | -| `videoCount` | `Integer` | 视频数量 | -| `status` | `String` | 评价状态 | -| `statusLabel` | `String` | 评价状态标签 | -| `machineResult` | `String` | 机审结果 | -| `rejectReason` | `String` | 拒绝原因 | -| `auditorAdminId` | `String` | 审核人ID | -| `auditorName` | `String` | 审核人姓名 | -| `auditedAt` | `LocalDateTime` | 审核时间 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `images` | `List<ReviewImageVO>` | 评价图片列表 | -| `videos` | `List<ReviewVideoVO>` | 评价视频列表 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `imageId` | `String` | 图片ID | -| `imageUrl` | `String` | 图片URL | -| `fileId` | `String` | 文件ID | -| `sortOrder` | `Integer` | 排序序号 | -| `videoId` | `String` | 视频ID | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | -| `fileId` | `String` | 文件ID | -| `sortOrder` | `Integer` | 排序序号 | - -### 📌 `POST` /admin/review/{reviewId}/approve — 通过评价 - -> 审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED - -**参数** - - - `{reviewId}` (`Long`) — 路径参数：评价ID - -**响应** `Result<Void>` - -### 📌 `POST` /admin/review/{reviewId}/reject — 拒绝评价 - -> 审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED - -**参数** - - - `{reviewId}` (`Long`) — 路径参数：评价ID - -**请求体** `RejectRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `rejectReason` | `String` | 拒绝原因 | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/review/{reviewId}/override-approve — 覆盖通过(机器拒绝的) - -> 对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED - -**参数** - - - `{reviewId}` (`Long`) — 路径参数：评价ID - -**响应** `Result<Void>` - -### 📌 `POST` /admin/review/{reviewId}/reply — 回复评价(每条评价仅可回复一次) - -> 管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。 - -**权限**：需管理员登录。 - -**参数** - - - `{reviewId}` (`Long`) — 路径参数：评价ID - -**请求体** `AdminReplyRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `replyContent` | `String` | 回复内容 | - -**响应** `Result<Void>` - -### 🆕 新增: InternalMpReview - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【内部接口】小程序评价（Feign调用）」** - -### 📌 `POST` /internal/mp/review/create — 创建评价(仅针对产品，每个订单仅可评价一次) - -> **关联字典**： -- review_status：评价审核状态（返回字段） -- rating_level：评价等级（返回字段） - -**请求体** `CreateReviewRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `ratings` | `Map<String, Integer>` | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。 | -| `content` | `String` | 评价内容(10-5000字) | -| `images` | `List<ReviewImageItem>` | 评价图片列表（最多9张） | -| `videos` | `List<ReviewVideoItem>` | 评价视频列表（最多3个） | -| `imageUrl` | `String` | 图片URL | -| `fileId` | `Long` | 文件ID | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | -| `fileId` | `Long` | 文件ID | - -**响应** `Result<ReviewVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `String` | 用户ID | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `hasImage` | `Boolean` | 是否有图片 | -| `hasVideo` | `Boolean` | 是否有视频 | -| `imageCount` | `Integer` | 图片数量 | -| `videoCount` | `Integer` | 视频数量 | -| `status` | `String` | 评价状态 | -| `statusLabel` | `String` | 评价状态标签 | -| `machineResult` | `String` | 机审结果 | -| `rejectReason` | `String` | 拒绝原因 | -| `auditorAdminId` | `String` | 审核人ID | -| `auditorName` | `String` | 审核人姓名 | -| `auditedAt` | `LocalDateTime` | 审核时间 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `images` | `List<ReviewImageVO>` | 评价图片列表 | -| `videos` | `List<ReviewVideoVO>` | 评价视频列表 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `imageId` | `String` | 图片ID | -| `imageUrl` | `String` | 图片URL | -| `fileId` | `String` | 文件ID | -| `sortOrder` | `Integer` | 排序序号 | -| `videoId` | `String` | 视频ID | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | -| `fileId` | `String` | 文件ID | -| `sortOrder` | `Integer` | 排序序号 | - -### 📌 `GET` /internal/mp/review/order/{orderId}/reviewed — 检查订单是否已评价 - -> 内部服务间调用。检查指定订单是否已有评价记录，用于小程序端订单详情页控制评价入口的显示。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<Boolean>` - -### 📌 `GET` /internal/mp/review/my — 我的评价列表 - -> **关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**响应** `Result<PageResult<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/mp/review/target — 某目标的已通过评价(公开，支持好中差评/有图/有视频筛选) - -> **关联字典**： -- rating_level：评价等级（筛选+显示） - -**响应** `Result<PageResult<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/mp/review/search — 关键词搜索评价(公开) - -> **关联字典**： -- rating_level：评价等级（显示） - -**参数** - - - `keyword` (`String`) — 查询参数：搜索关键词 - - `targetType` (`String`) — 查询参数：目标类型(可选) - - `targetId` (`Long`) — 查询参数：目标ID(可选) - - `page` (`Integer`) — 查询参数：页码 - - `pageSize` (`Integer`) — 查询参数：每页条数 - -**响应** `Result<PageResult<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/mp/review/featured — 首页精选评价 - -> **关联字典**： -- rating_level：评价等级（显示） - -**参数** - - - `limit` (`Integer`) — 查询参数：数量限制 - -**响应** `Result<List<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/mp/review/order/{orderId}/reviewable-targets — 订单可评价目标列表 - -> 内部服务间调用。返回订单关联的可评价目标（产品、定制师等），用于评价页面选择评价对象。已评价的目标不会重复出现。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<List<Map<String, Object>>>` - -### 📌 `POST` /internal/mp/review/{reviewId}/like — 点赞/取消点赞评价 - -> 内部服务间调用。切换当前用户对评价的点赞状态（toggle），返回最新点赞状态和点赞总数。 - -**参数** - - - `{reviewId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/mp/review/{reviewId}/like/check — 检查是否已点赞 - -> 内部服务间调用。检查当前用户是否已对指定评价点赞，用于小程序端渲染点赞按钮状态。 - -**参数** - - - `{reviewId}` (`Long`) — 路径参数 - -**响应** `Result<Boolean>` - -### 📌 `POST` /internal/mp/review/{reviewId}/sync-like-count — 同步评价点赞数（供通用点赞服务回调） - -> 内部服务间调用。通用点赞服务（user-service）发生点赞变化后回调此接口，同步更新评价表的点赞计数字段。 - -**参数** - - - `{reviewId}` (`Long`) — 路径参数 - - `likeCount` (`int`) — 查询参数 - -**响应** `Result<Void>` - -### 🆕 新增: InternalReview - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【内部接口】评价统计（Feign调用）」** - -### 📌 `GET` /internal/review/target-stats — 目标评价统计(平均分,数量) - -> **关联字典**： -- rating_level：评价等级（统计维度） - -**参数** - - - `targetType` (`String`) — 查询参数 - - `targetId` (`Long`) — 查询参数 - -**响应** `Result<ReviewStatsVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `targetType` | `String` | 评价目标类型 | -| `targetId` | `String` | 评价目标ID | -| `averageRating` | `BigDecimal` | 整体满意度平均分 | -| `avgItinerary` | `BigDecimal` | 行程安排平均分 | -| `avgAccommodation` | `BigDecimal` | 住宿安排平均分 | -| `avgDriver` | `BigDecimal` | 司机服务平均分 | -| `avgDining` | `BigDecimal` | 餐饮质量平均分 | -| `totalCount` | `Integer` | 评价总数 | -| `goodCount` | `Integer` | 好评数 | -| `mediumCount` | `Integer` | 中评数 | -| `badCount` | `Integer` | 差评数 | -| `withImageCount` | `Integer` | 有图评价数 | -| `withVideoCount` | `Integer` | 有视频评价数 | -| `goodRate` | `BigDecimal` | 好评率(百分比, 如 98) | - -### 📌 `GET` /internal/review/target-list — 目标已通过评价列表 - -> **关联字典**： -- rating_level：评价等级（显示） - -**参数** - - - `targetType` (`String`) — 查询参数 - - `targetId` (`Long`) — 查询参数 - - `page` (`Integer`) — 查询参数 - - `pageSize` (`Integer`) — 查询参数 - -**响应** `Result<PageResult<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/review/stats-by-targets — 批量目标评价统计(聚合多个targetId) - -> **关联字典**： -- rating_level：评价等级（统计维度） - -**参数** - - - `targetType` (`String`) — 查询参数 - - `targetIds` (`String`) — 查询参数 - -**响应** `Result<ReviewStatsVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `targetType` | `String` | 评价目标类型 | -| `targetId` | `String` | 评价目标ID | -| `averageRating` | `BigDecimal` | 整体满意度平均分 | -| `avgItinerary` | `BigDecimal` | 行程安排平均分 | -| `avgAccommodation` | `BigDecimal` | 住宿安排平均分 | -| `avgDriver` | `BigDecimal` | 司机服务平均分 | -| `avgDining` | `BigDecimal` | 餐饮质量平均分 | -| `totalCount` | `Integer` | 评价总数 | -| `goodCount` | `Integer` | 好评数 | -| `mediumCount` | `Integer` | 中评数 | -| `badCount` | `Integer` | 差评数 | -| `withImageCount` | `Integer` | 有图评价数 | -| `withVideoCount` | `Integer` | 有视频评价数 | -| `goodRate` | `BigDecimal` | 好评率(百分比, 如 98) | - -### 📌 `GET` /internal/review/reviews-by-targets — 批量目标已通过评价列表(聚合多个targetId) - -> **关联字典**： -- rating_level：评价等级（显示） - -**参数** - - - `targetType` (`String`) — 查询参数 - - `targetIds` (`String`) — 查询参数 - - `page` (`Integer`) — 查询参数 - - `pageSize` (`Integer`) — 查询参数 - -**响应** `Result<PageResult<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/review/product-highlights — 产品精选评价(最高评分+最高点赞+统计) - -> **关联字典**： -- rating_level：评价等级（显示） - -**参数** - - - `productId` (`Long`) — 查询参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/review/customizer-reviews — 定制师已通过评价列表 - -> **关联字典**： -- rating_level：评价等级（筛选+显示） - -**参数** - - - `customizerId` (`Long`) — 查询参数 - - `page` (`Integer`) — 查询参数 - - `pageSize` (`Integer`) — 查询参数 - - `ratingLevel` (`String`) — 查询参数 - -**响应** `Result<PageResult<MpReviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewId` | `String` | 评价ID | -| `orderId` | `String` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像 | -| `reviewType` | `String` | 评论类型 | -| `reviewTypeLabel` | `String` | 评论类型标签 | -| `productType` | `String` | 产品类型 | -| `productTypeLabel` | `String` | 产品类型标签 | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `productCoverUrl` | `String` | 产品封面URL(快照) | -| `productSnapshot` | `String` | 产品快照JSON(来自订单) | -| `ratingItinerary` | `Integer` | 行程安排评分(1-5) | -| `ratingAccommodation` | `Integer` | 住宿安排评分(1-5) | -| `ratingDriver` | `Integer` | 司机服务评分(1-5) | -| `ratingDining` | `Integer` | 餐饮质量评分(1-5) | -| `ratingOverall` | `Integer` | 整体满意度评分(1-5) | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `ratingLevelLabel` | `String` | 评价等级标签: 好评/中评/差评 | -| `content` | `String` | 评价内容 | -| `images` | `List<String>` | 图片URL列表 | -| `videos` | `List<MpReviewVideoVO>` | 视频列表 | -| `adminReply` | `String` | 管理员回复内容 | -| `adminReplyName` | `String` | 回复管理员姓名 | -| `adminReplyAt` | `LocalDateTime` | 回复时间 | -| `likeCount` | `Integer` | 点赞数 | -| `liked` | `Boolean` | 当前用户是否已点赞 | -| `departureDate` | `LocalDate` | 出发日期(冗余自订单) | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `videoUrl` | `String` | 视频URL | -| `coverUrl` | `String` | 视频封面URL | -| `duration` | `Integer` | 视频时长(秒) | - -### 📌 `GET` /internal/review/customizer-review-stats — 定制师评价统计(总数/平均分/好评率) - -> 内部服务间调用。返回指定定制师的评价汇总统计：总评价数、平均评分、好评率等。用于定制师主页展示服务评价。 - -**参数** - - - `customizerId` (`Long`) — 查询参数 - -### 📌 `GET` /internal/review/order/{orderId}/summary — 订单评价摘要(行程详情用) - -> 返回订单的产品评价摘要信息，无评价返回null - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - -### 🆕 新增: Board - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「任务看板管理」** - -### 📌 `GET` /admin/task/boards — 获取可见看板列表 - -> 返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板 - -**响应** `Result<List<BoardVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardId` | `Long` | 看板ID | -| `boardName` | `String` | 看板名称 | -| `description` | `String` | 看板描述 | -| `boardType` | `String` | 看板类型 | -| `deptId` | `Long` | 部门ID | -| `deptName` | `String` | 部门名称 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `statuses` | `List<BoardStatusVO>` | 状态列表 | -| `taskCount` | `int` | 任务总数 | - -### 📌 `GET` /admin/task/board/{boardId} — 看板详情 - -> 返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**响应** `Result<BoardVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardId` | `Long` | 看板ID | -| `boardName` | `String` | 看板名称 | -| `description` | `String` | 看板描述 | -| `boardType` | `String` | 看板类型 | -| `deptId` | `Long` | 部门ID | -| `deptName` | `String` | 部门名称 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `statuses` | `List<BoardStatusVO>` | 状态列表 | -| `taskCount` | `int` | 任务总数 | - -### 📌 `POST` /admin/task/board — 创建自定义看板 - -> 创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。 - -**权限**：需管理员登录。 - -**请求体** `CreateBoardRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardName` | `String` | 看板名称 | -| `description` | `String` | 看板描述 | -| `deptId` | `Long` | 部门ID | -| `memberIds` | `List<Long>` | 成员ID列表 | - -**响应** `Result<BoardVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardId` | `Long` | 看板ID | -| `boardName` | `String` | 看板名称 | -| `description` | `String` | 看板描述 | -| `boardType` | `String` | 看板类型 | -| `deptId` | `Long` | 部门ID | -| `deptName` | `String` | 部门名称 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `statuses` | `List<BoardStatusVO>` | 状态列表 | -| `taskCount` | `int` | 任务总数 | - -### 📌 `PUT` /admin/task/board/{boardId} — 更新看板 - -> 更新看板的名称和描述。仅看板创建者或超级管理员可操作。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**请求体** `UpdateBoardRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardName` | `String` | 看板名称 | -| `description` | `String` | 看板描述 | - -**响应** `Result<BoardVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardId` | `Long` | 看板ID | -| `boardName` | `String` | 看板名称 | -| `description` | `String` | 看板描述 | -| `boardType` | `String` | 看板类型 | -| `deptId` | `Long` | 部门ID | -| `deptName` | `String` | 部门名称 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `statuses` | `List<BoardStatusVO>` | 状态列表 | -| `taskCount` | `int` | 任务总数 | - -### 📌 `DELETE` /admin/task/board/{boardId} — 删除看板 - -> 删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**响应** `Result<Void>` - -### 📌 `GET` /admin/task/board/{boardId}/statuses — 获取看板状态列 - -> 返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**响应** `Result<List<BoardStatusVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `sortOrder` | `Integer` | 排序序号 | -| `isPreset` | `Boolean` | 是否预设状态 | -| `taskCount` | `int` | 该状态下的任务数量 | - -### 📌 `POST` /admin/task/board/{boardId}/status — 创建状态列 - -> 在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。 - -**权限**：需管理员登录且为看板成员。 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**请求体** `CreateStatusRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | - -**响应** `Result<BoardStatusVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `sortOrder` | `Integer` | 排序序号 | -| `isPreset` | `Boolean` | 是否预设状态 | -| `taskCount` | `int` | 该状态下的任务数量 | - -### 📌 `PUT` /admin/task/status/{statusId} — 更新状态列 - -> 更新状态列的名称和颜色。 - -**权限**：需管理员登录且为看板成员。 - -**参数** - - - `{statusId}` (`Long`) — 路径参数：状态列ID - -**请求体** `UpdateStatusRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | - -**响应** `Result<BoardStatusVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `sortOrder` | `Integer` | 排序序号 | -| `isPreset` | `Boolean` | 是否预设状态 | -| `taskCount` | `int` | 该状态下的任务数量 | - -### 📌 `DELETE` /admin/task/status/{statusId} — 删除状态列 - -> 删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务 - -**参数** - - - `{statusId}` (`Long`) — 路径参数：状态列ID - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/task/board/{boardId}/status/sort — 状态列排序 - -> 批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**请求体** `StatusSortRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusIds` | `List<Long>` | 状态ID列表(按排序顺序) | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/task/board/{boardId}/members — 获取看板成员 - -> 返回看板的所有成员列表，包含成员的管理员ID和姓名 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**响应** `Result<List<BoardMemberVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adminId` | `Long` | 管理员ID | -| `username` | `String` | 用户名 | -| `avatarUrl` | `String` | 头像地址 | -| `role` | `String` | 角色: OWNER/MEMBER | -| `joinedAt` | `LocalDateTime` | 加入时间 | - -### 📌 `POST` /admin/task/board/{boardId}/members — 添加成员 - -> 批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - -**请求体** `AddMembersRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adminIds` | `List<Long>` | 管理员ID列表 | - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/task/board/{boardId}/member/{targetAdminId} — 移除成员 - -> 从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己 - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - - `{targetAdminId}` (`Long`) — 路径参数：目标管理员ID - -**响应** `Result<Void>` - -### 🆕 新增: Task - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「任务管理」** - -### 📌 `GET` /admin/task/board/{boardId}/tasks — 获取看板任务(按状态分组) - -> 返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列 - -**关联字典**： -- task_priority：任务优先级（列表筛选+显示） - -**参数** - - - `{boardId}` (`Long`) — 路径参数：看板ID - - `priority` (`String`) — 查询参数：优先级 - - `assigneeId` (`Long`) — 查询参数：负责人ID - -**响应** `Result<List<BoardTasksVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `sortOrder` | `Integer` | 排序序号 | -| `tasks` | `List<TaskVO>` | 该状态下的任务列表 | - -### 📌 `GET` /admin/task/{taskId} — 任务详情 - -> 返回任务完整信息，包含子任务列表、负责人信息、附件列表等 - -**关联字典**： -- task_priority：任务优先级（显示） - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**响应** `Result<TaskVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `taskId` | `Long` | 任务ID | -| `boardId` | `Long` | 看板ID | -| `parentId` | `Long` | 父任务ID | -| `title` | `String` | 任务标题 | -| `description` | `String` | 任务描述 | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `priority` | `String` | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `dueDate` | `LocalDate` | 截止日期 | -| `overdue` | `Boolean` | 是否逾期 | -| `sortOrder` | `Integer` | 排序序号 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | -| `assignees` | `List<AssigneeVO>` | 负责人列表 | -| `subtaskTotal` | `int` | 子任务总数 | -| `subtaskCompleted` | `int` | 已完成子任务数 | -| `subtasks` | `List<SubtaskVO>` | 子任务列表 | - -### 📌 `POST` /admin/task — 创建任务 - -> 在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人 - -**关联字典**： -- task_priority：任务优先级（创建时选择） - -**请求体** `CreateTaskRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `boardId` | `Long` | 看板ID | -| `title` | `String` | 任务标题 | -| `description` | `String` | 任务描述 | -| `statusId` | `Long` | 状态ID | -| `priority` | `String` | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `dueDate` | `LocalDate` | 截止日期 | -| `assigneeIds` | `List<Long>` | 负责人ID列表 | - -**响应** `Result<TaskVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `taskId` | `Long` | 任务ID | -| `boardId` | `Long` | 看板ID | -| `parentId` | `Long` | 父任务ID | -| `title` | `String` | 任务标题 | -| `description` | `String` | 任务描述 | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `priority` | `String` | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `dueDate` | `LocalDate` | 截止日期 | -| `overdue` | `Boolean` | 是否逾期 | -| `sortOrder` | `Integer` | 排序序号 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | -| `assignees` | `List<AssigneeVO>` | 负责人列表 | -| `subtaskTotal` | `int` | 子任务总数 | -| `subtaskCompleted` | `int` | 已完成子任务数 | -| `subtasks` | `List<SubtaskVO>` | 子任务列表 | - -### 📌 `PUT` /admin/task/{taskId} — 更新任务 - -> 更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。 - -**权限**：需管理员登录且为看板成员。 - -**关联字典**： -- task_priority：任务优先级（编辑时选择） - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**请求体** `UpdateTaskRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `title` | `String` | 任务标题 | -| `description` | `String` | 任务描述 | -| `priority` | `String` | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `dueDate` | `LocalDate` | 截止日期 | -| `assigneeIds` | `List<Long>` | 负责人ID列表 | - -**响应** `Result<TaskVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `taskId` | `Long` | 任务ID | -| `boardId` | `Long` | 看板ID | -| `parentId` | `Long` | 父任务ID | -| `title` | `String` | 任务标题 | -| `description` | `String` | 任务描述 | -| `statusId` | `Long` | 状态ID | -| `statusName` | `String` | 状态名称 | -| `statusColor` | `String` | 状态颜色 | -| `priority` | `String` | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `dueDate` | `LocalDate` | 截止日期 | -| `overdue` | `Boolean` | 是否逾期 | -| `sortOrder` | `Integer` | 排序序号 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | -| `assignees` | `List<AssigneeVO>` | 负责人列表 | -| `subtaskTotal` | `int` | 子任务总数 | -| `subtaskCompleted` | `int` | 已完成子任务数 | -| `subtasks` | `List<SubtaskVO>` | 子任务列表 | - -### 📌 `PUT` /admin/task/{taskId}/status — 变更任务状态 - -> 将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件 - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**请求体** `ChangeStatusRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusId` | `Long` | 目标状态ID | - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/task/{taskId}/sort — 任务排序 - -> 更新任务在同一状态列内的排序位置，用于拖拽排序 - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**请求体** `TaskSortRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `statusId` | `Long` | 状态ID | -| `taskIds` | `List<Long>` | 任务ID列表(按排序顺序) | - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/task/{taskId} — 删除任务 - -> 删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。 - -**权限**：需管理员登录且为看板成员。 - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**响应** `Result<Void>` - -### 📌 `POST` /admin/task/{taskId}/subtask — 创建子任务 - -> 在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。 - -**权限**：需管理员登录且为看板成员。 - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**请求体** `CreateSubtaskRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `title` | `String` | 子任务标题 | - -**响应** `Result<SubtaskVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `taskId` | `Long` | 子任务ID | -| `title` | `String` | 子任务标题 | -| `completed` | `Boolean` | 是否已完成 | -| `createdBy` | `Long` | 创建人ID | -| `creatorName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/task/subtask/{subtaskId}/toggle — 切换子任务完成状态 - -> 切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线 - -**参数** - - - `{subtaskId}` (`Long`) — 路径参数：子任务ID - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/task/subtask/{subtaskId} — 删除子任务 - -> 删除指定子任务。 - -**权限**：需管理员登录且为看板成员。 - -**参数** - - - `{subtaskId}` (`Long`) — 路径参数：子任务ID - -**响应** `Result<Void>` - -### 📌 `GET` /admin/task/{taskId}/timeline — 获取任务时间线 - -> 返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列 - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**响应** `Result<List<TimelineItemVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | 条目ID | -| `type` | `String` | 类型: COMMENT/ACTIVITY | -| `adminId` | `Long` | 管理员ID | -| `adminName` | `String` | 管理员姓名 | -| `adminAvatar` | `String` | 管理员头像 | -| `content` | `String` | 内容 | -| `action` | `String` | 操作类型 | -| `oldValue` | `String` | 旧值 | -| `newValue` | `String` | 新值 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/task/{taskId}/comment — 添加评论 - -> 在任务时间线中添加评论，添加后自动通知任务负责人 - -**参数** - - - `{taskId}` (`Long`) — 路径参数：任务ID - -**请求体** `CreateCommentRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `content` | `String` | 评论内容 | - -**响应** `Result<TimelineItemVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | 条目ID | -| `type` | `String` | 类型: COMMENT/ACTIVITY | -| `adminId` | `Long` | 管理员ID | -| `adminName` | `String` | 管理员姓名 | -| `adminAvatar` | `String` | 管理员头像 | -| `content` | `String` | 内容 | -| `action` | `String` | 操作类型 | -| `oldValue` | `String` | 旧值 | -| `newValue` | `String` | 新值 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/task/comment/{commentId} — 删除评论 - -> 仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除 - -**参数** - - - `{commentId}` (`Long`) — 路径参数：评论ID - -**响应** `Result<Void>` - -### 🆕 新增: WebSocketDoc - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「WebSocket \u5B9E\u65F6\u63A8\u9001」** - -### 📌 `GET` /admin/task/board/ws-doc/info — WebSocket \u8FDE\u63A5\u8BF4\u660E - -> ## \u8FDE\u63A5\u4FE1\u606F - -**响应** `Map<String, String>` - ---- - -## 订单服务 - -### 🆕 新增: AdminClauseTemplate - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「补充约定模板管理」** - -### 📌 `GET` /admin/contract/clause-template/list — 获取启用的补充约定模板列表（创建合同用） - -> 返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。 - -**权限**：需管理员登录。 - -**响应** `Result<List<ClauseTemplateVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/clause-template/list-all — 获取全部补充约定模板（管理页用） - -> **关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `Result<List<ClauseTemplateVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/contract/clause-template/{id}/toggle-status — 切换模板启用/停用状态 - -> **关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**参数** - - - `{templateId}` (`Long`) — 路径参数：模板ID - -**响应** `Result<ClauseTemplateVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/clause-template — 创建补充约定模板 - -> 创建合同补充约定的模板，支持变量占位符。创建后默认启用 - -**请求体** `ClauseTemplateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序（升序） | - -**响应** `Result<ClauseTemplateVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/contract/clause-template/{id} — 更新补充约定模板 - -> 更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。 - -**权限**：需管理员登录。 - -**参数** - - - `{templateId}` (`Long`) — 路径参数：模板ID - -**请求体** `ClauseTemplateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序（升序） | - -**响应** `Result<ClauseTemplateVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `content` | `String` | 模板内容 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/contract/clause-template/{id} — 删除补充约定模板 - -> 软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同 - -**参数** - - - `{templateId}` (`Long`) — 路径参数：模板ID - -**响应** `Result<Void>` - -### 🆕 新增: AdminContract - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「合同管理」** - -### 📌 `GET` /admin/contract/platforms — 可用合同平台列表 - -> 返回系统已对接的合同平台列表及可用状态。 - -**响应** `Result<List<ContractPlatformInfo>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `platformName` | `String` | | -| `displayName` | `String` | | -| `available` | `boolean` | | - -### 📌 `GET` /admin/contract/agencies — 可用旅行社列表 - -> 返回系统配置的旅行社列表，创建合同时选择签约旅行社 - -### 📌 `GET` /admin/contract/templates — 合同模板列表 - -> 返回合同平台可用的合同模板列表。可通过platform参数过滤：12301=全国旅游监管平台，FADADA=法大大 - -**参数** - - - `platform` (`String`) — 查询参数：合同平台(可选): 12301/FADADA - -**响应** `Result<List<ContractTemplateVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `platform` | `String` | 签约平台 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 模板状态 | -| `description` | `String` | 模板描述 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/create — 创建合同(标准模式) - -> 标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。 - -**请求体** `CreateContractRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `contractType` | `String` | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `platform` | `String` | 合同平台（字典：contract_platform）: 12301-全国旅游监管平台, FADADA-法大大, ESIGN-e签宝, TENCENT_ESS-腾讯电子签。不传则根据模板自动确定 | -| `templateCode` | `String` | 模板编码 | -| `agencyCode` | `String` | 旅行社编号（可选，不传则按商户号匹配，仍无则用默认值） | -| `mchId` | `String` | 微信支付商户号（用于自动匹配旅行社） | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `destination` | `String` | 目的地 | -| `routeName` | `String` | 线路名称 | -| `days` | `Integer` | 行程天数 | -| `nights` | `Integer` | 住宿晚数 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `departureCity` | `String` | 出发城市 | -| `groupId` | `String` | 团号 | -| `signatoryName` | `String` | 签署人姓名 | -| `signatoryPhone` | `String` | 签署人电话 | -| `signatoryIdNumber` | `String` | 签署人证件号码 | -| `signingPlace` | `String` | 签约地点 | -| `adultCost` | `BigDecimal` | 成人费用 | -| `childCost` | `BigDecimal` | 儿童费用 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `supplementaryClause` | `String` | 补充约定内容 | -| `vehicleModel` | `String` | 车型名称(产品快照) | -| `travelers` | `List<TravelerDTO>` | 出行人列表 | -| `name` | `String` | 姓名 | -| `gender` | `String` | 性别: male/female | -| `age` | `Integer` | 年龄 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `health` | `String` | 健康信息 | - -**响应** `Result<ContractDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `supplementaryClause` | `String` | 补充约定内容 | -| `travelers` | `List<TravelerVO>` | 出行人列表 | -| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 | -| `travelerId` | `Long` | 出行人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `isSigner` | `Boolean` | 是否签署人 | -| `logId` | `Long` | 日志ID | -| `oldStatus` | `String` | 旧状态 | -| `newStatus` | `String` | 新状态 | -| `source` | `String` | 变更来源 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/create-by-scheme — 按方案创建合同（简化） - -> 只需传orderId和schemeId，后端自动从订单获取出行人、日期、联系人等数据，结合合同方案配置创建合同。 - -**响应** `Result<ContractDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `supplementaryClause` | `String` | 补充约定内容 | -| `travelers` | `List<TravelerVO>` | 出行人列表 | -| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 | -| `travelerId` | `Long` | 出行人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `isSigner` | `Boolean` | 是否签署人 | -| `logId` | `Long` | 日志ID | -| `oldStatus` | `String` | 旧状态 | -| `newStatus` | `String` | 新状态 | -| `source` | `String` | 变更来源 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/report — 报备合同(同步模式) - -> 线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。 - -**请求体** `ReportContractRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `contractType` | `String` | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `platform` | `String` | 合同平台（字典：contract_platform）: 12301-全国旅游监管平台, FADADA-法大大, ESIGN-e签宝, TENCENT_ESS-腾讯电子签 | -| `templateCode` | `String` | 模板编码 | -| `agencyCode` | `String` | 旅行社编号（可选，不传则按商户号匹配，仍无则用默认值） | -| `mchId` | `String` | 微信支付商户号（用于自动匹配旅行社） | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `destination` | `String` | 目的地 | -| `routeName` | `String` | 线路名称 | -| `days` | `Integer` | 行程天数 | -| `nights` | `Integer` | 住宿晚数 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `departureCity` | `String` | 出发城市 | -| `groupId` | `String` | 团号 | -| `signatoryName` | `String` | 签署人姓名 | -| `signatoryPhone` | `String` | 签署人电话 | -| `signatoryIdNumber` | `String` | 签署人证件号码 | -| `signingPlace` | `String` | 签约地点 | -| `adultCost` | `BigDecimal` | 成人费用 | -| `childCost` | `BigDecimal` | 儿童费用 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `supplementaryClause` | `String` | 补充约定内容 | - -**响应** `Result<ContractDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `supplementaryClause` | `String` | 补充约定内容 | -| `travelers` | `List<TravelerVO>` | 出行人列表 | -| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 | -| `travelerId` | `Long` | 出行人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `isSigner` | `Boolean` | 是否签署人 | -| `logId` | `Long` | 日志ID | -| `oldStatus` | `String` | 旧状态 | -| `newStatus` | `String` | 新状态 | -| `source` | `String` | 变更来源 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/list — 合同列表 - -> 分页查询合同记录，支持按订单号、合同状态、旅行社筛选 - -**关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**响应** `Result<PageResult<ContractVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/{id} — 合同详情 - -> **关联字典**： -- contract_status：合同状态（显示） - -**参数** - - - `{contractId}` (`Long`) — 路径参数：合同ID - -**响应** `Result<ContractDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `supplementaryClause` | `String` | 补充约定内容 | -| `travelers` | `List<TravelerVO>` | 出行人列表 | -| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 | -| `travelerId` | `Long` | 出行人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `isSigner` | `Boolean` | 是否签署人 | -| `logId` | `Long` | 日志ID | -| `oldStatus` | `String` | 旧状态 | -| `newStatus` | `String` | 新状态 | -| `source` | `String` | 变更来源 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/by-order/{orderId} — 按订单查询合同 - -> 查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（列表显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<List<ContractVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/active-by-order/{orderId} — 获取订单有效合同 - -> 返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<ContractVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/{id}/status — 刷新合同状态(从平台同步) - -> 主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景 - -**参数** - - - `{contractId}` (`Long`) — 路径参数：合同ID - -**响应** `Result<ContractVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/{id}/invalidate — 作废合同 - -> 将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同 - -**参数** - - - `{contractId}` (`Long`) — 路径参数：合同ID - -**响应** `Result<ContractVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/{id}/resend-sms — 重发签署短信 - -> 重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作 - -**参数** - - - `{contractId}` (`Long`) — 路径参数：合同ID - -**响应** `Result<Boolean>` - -### 📌 `POST` /admin/contract/{id}/upload-pdf — 上传已签署PDF(同步模式) - -> 同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备 - -**参数** - - - `{contractId}` (`Long`) — 路径参数：合同ID - - `file` (`MultipartFile`) — 查询参数：签署PDF文件 - -**响应** `Result<ContractVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: AdminContractScheme - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「合同方案管理」** - -### 📌 `GET` /admin/contract/scheme/list — 查询启用的合同方案列表 - -> 供产品配置时下拉选择使用，只返回启用状态的方案 - -**响应** `Result<List<ContractSchemeVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/scheme/list-all — 查询全部合同方案列表 - -> 管理页面使用，包含停用的方案 - -**响应** `Result<List<ContractSchemeVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/contract/scheme/{schemeId} — 获取合同方案详情 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/contract/scheme — 创建合同方案 - -**请求体** `ContractSchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码 | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码(可选，不填则根据订单支付商户号自动匹配旅行社) | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款(可选) | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序(越小越靠前) | - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/contract/scheme/{schemeId} — 更新合同方案 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**请求体** `ContractSchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码 | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码(可选，不填则根据订单支付商户号自动匹配旅行社) | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款(可选) | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序(越小越靠前) | - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/contract/scheme/{schemeId}/toggle-status — 切换方案启用/停用状态 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<ContractSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `String` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `contractPlatform` | `String` | 合同平台: 12301/FADADA | -| `contractTemplateCode` | `String` | 合同模板编码（与模板列表的templateCode一致） | -| `templateCode` | `String` | 合同模板编码（别名，与contractTemplateCode相同值，方便前端统一使用templateCode） | -| `contractTemplateName` | `String` | 合同模板名称（回显用） | -| `contractMode` | `String` | 签约模式: STANDARD(电子签约)/SYNC(线下报备) | -| `signatoryMode` | `Integer` | 签署模式: 1=短信签署 2=现场签署 3=线下签署 | -| `agencyCode` | `String` | 旅行社编码 | -| `agencyName` | `String` | 旅行社名称（回显用） | -| `disputeResolution` | `Integer` | 争议解决方式: 1=仲裁 2=诉讼 | -| `supplementaryClause` | `String` | 补充条款 | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态: ACTIVE/INACTIVE | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/contract/scheme/{schemeId} — 删除合同方案 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 🆕 新增: ContractCallback - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【回调接口】合同回调」** - -### 📌 `POST` /contract/callback/12301 — 12301合同状态回调 - -> 接收12301全国旅游监管平台的合同签署状态回调。出行人签署完成后平台推送状态变更到此接口，自动更新本地合同状态 - -**请求体** `ContractCallbackPayload` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `apiVersion` | `String` | API版本 | -| `data` | `CallbackData` | 回调数据 | -| `sign` | `String` | 签名 | -| `signatoryPhone` | `String` | 签署人手机号 | -| `signatoryIDNumber` | `String` | 签署人证件号码 | -| `state` | `Integer` | 合同状态码 | -| `contractNumber` | `String` | 合同编号 | -| `content` | `String` | 状态描述 | -| `contractType` | `String` | 合同类型 | -| `timestamp` | `Long` | 时间戳（Unix秒） | -| `url` | `CallbackUrl` | 相关URL | -| `signingURL` | `String` | 签署URL | -| `qrCodeURL` | `String` | 二维码URL | -| `fileURL` | `String` | 合同文件URL | - -**响应** `ResponseEntity<String>` - -### 📌 `POST` /contract/callback/fadada — 法大大合同状态回调 - -> 接收法大大电子合同平台的签署状态回调。签署完成/撤销/拒签时法大大推送事件到此接口 - -**响应** `ResponseEntity<String>` - -### 🆕 新增: InternalContract - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】合同（Feign调用）」** - -### 📌 `GET` /internal/contract/by-order/{orderId} — 按订单查询合同(内部调用) - -> **关联字典**： -- contract_status：合同状态（返回字段） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<List<ContractVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /internal/contract/by-orders — 按订单批量查询合同(内部调用) - -> **关联字典**： -- contract_status：合同状态（返回字段） - -**响应** `Result<Map<Long, List<ContractVO>>>` - -### 📌 `GET` /internal/contract/has-signed/{orderId} — 检查订单是否有已签署合同(内部调用) - -> 检查订单是否存在有效签署的合同（SIGNED/REPORTED/UPLOADED状态），用于订单流程中的合同校验 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<Boolean>` - -### 📌 `POST` /internal/contract/create — 创建合同（内部调用） - -> 内部服务调用创建合同，adminId固定为0表示系统自动创建。返回contractId和status - -**请求体** `CreateContractRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `contractType` | `String` | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `platform` | `String` | 合同平台（字典：contract_platform）: 12301-全国旅游监管平台, FADADA-法大大, ESIGN-e签宝, TENCENT_ESS-腾讯电子签。不传则根据模板自动确定 | -| `templateCode` | `String` | 模板编码 | -| `agencyCode` | `String` | 旅行社编号（可选，不传则按商户号匹配，仍无则用默认值） | -| `mchId` | `String` | 微信支付商户号（用于自动匹配旅行社） | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `destination` | `String` | 目的地 | -| `routeName` | `String` | 线路名称 | -| `days` | `Integer` | 行程天数 | -| `nights` | `Integer` | 住宿晚数 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `departureCity` | `String` | 出发城市 | -| `groupId` | `String` | 团号 | -| `signatoryName` | `String` | 签署人姓名 | -| `signatoryPhone` | `String` | 签署人电话 | -| `signatoryIdNumber` | `String` | 签署人证件号码 | -| `signingPlace` | `String` | 签约地点 | -| `adultCost` | `BigDecimal` | 成人费用 | -| `childCost` | `BigDecimal` | 儿童费用 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `supplementaryClause` | `String` | 补充约定内容 | -| `vehicleModel` | `String` | 车型名称(产品快照) | -| `travelers` | `List<TravelerDTO>` | 出行人列表 | -| `name` | `String` | 姓名 | -| `gender` | `String` | 性别: male/female | -| `age` | `Integer` | 年龄 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `health` | `String` | 健康信息 | - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /internal/contract/report — 报备合同（内部调用） - -> 内部服务调用报备合同（同步模式），adminId固定为0表示系统自动创建。返回contractId和status - -**请求体** `ReportContractRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `contractType` | `String` | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `platform` | `String` | 合同平台（字典：contract_platform）: 12301-全国旅游监管平台, FADADA-法大大, ESIGN-e签宝, TENCENT_ESS-腾讯电子签 | -| `templateCode` | `String` | 模板编码 | -| `agencyCode` | `String` | 旅行社编号（可选，不传则按商户号匹配，仍无则用默认值） | -| `mchId` | `String` | 微信支付商户号（用于自动匹配旅行社） | -| `transactorName` | `String` | 经办人姓名 | -| `transactorPhone` | `String` | 经办人电话 | -| `destination` | `String` | 目的地 | -| `routeName` | `String` | 线路名称 | -| `days` | `Integer` | 行程天数 | -| `nights` | `Integer` | 住宿晚数 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `departureCity` | `String` | 出发城市 | -| `groupId` | `String` | 团号 | -| `signatoryName` | `String` | 签署人姓名 | -| `signatoryPhone` | `String` | 签署人电话 | -| `signatoryIdNumber` | `String` | 签署人证件号码 | -| `signingPlace` | `String` | 签约地点 | -| `adultCost` | `BigDecimal` | 成人费用 | -| `childCost` | `BigDecimal` | 儿童费用 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `supplementaryClause` | `String` | 补充约定内容 | - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/contract/scheme/{schemeId}/config — 获取合同方案配置(内部调用) - -> 供 order-service 自动签约时获取方案的完整合同配置 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /internal/contract/invalidate/{orderId} — 按订单作废所有有效合同(级联调用) - -> 订单取消或退款时级联作废该订单下所有有效合同，reason参数记录作废原因 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `reason` (`String`) — 查询参数 - -**响应** `Result<Void>` - -### 🆕 新增: InternalMpContract - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序合同（Feign调用）」** - -### 📌 `GET` /internal/mp/contract/list — 用户合同列表 - -> **关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**参数** - - - `userId` (`Long`) — 查询参数 - - `status` (`String`) — 查询参数 - - `page` (`int`) — 查询参数 - - `pageSize` (`int`) — 查询参数 - -**响应** `Result<PageResult<ContractVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /internal/mp/contract/{id} — 用户合同详情 - -> **关联字典**： -- contract_status：合同状态（显示） - -**参数** - - - `{contractId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result<ContractDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `supplementaryClause` | `String` | 补充约定内容 | -| `travelers` | `List<TravelerVO>` | 出行人列表 | -| `statusLogs` | `List<StatusLogVO>` | 状态变更日志 | -| `travelerId` | `Long` | 出行人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型 | -| `idCardNo` | `String` | 证件号码 | -| `phone` | `String` | 手机号 | -| `isSigner` | `Boolean` | 是否签署人 | -| `logId` | `Long` | 日志ID | -| `oldStatus` | `String` | 旧状态 | -| `newStatus` | `String` | 新状态 | -| `source` | `String` | 变更来源 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /internal/mp/contract/by-order/{orderId} — 按订单查合同（返回最新有效合同） - -> **关联字典**： -- contract_status：合同状态（显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result<ContractVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `contractId` | `Long` | 合同ID | -| `orderId` | `Long` | 订单ID | -| `templateCode` | `String` | 模板编码 | -| `templateName` | `String` | 模板名称 | -| `contractNumber` | `String` | 合同编号 | -| `platform` | `String` | 签约平台 | -| `contractType` | `String` | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -| `mode` | `String` | 签约模式: STANDARD/SYNC | -| `status` | `String` | 合同状态 | -| `statusLabel` | `String` | 合同状态标签 | -| `signUrl` | `String` | 签署URL | -| `qrCodeUrl` | `String` | 二维码URL | -| `fileUrl` | `String` | 合同文件URL | -| `agencyCode` | `String` | 旅行社编号 | -| `travelAgencyName` | `String` | 旅行社名称 | -| `destination` | `String` | 目的地 | -| `departureDate` | `LocalDate` | 出发日期 | -| `returnDate` | `LocalDate` | 返回日期 | -| `totalAmount` | `BigDecimal` | 合同总金额 | -| `touristCount` | `Integer` | 出行人数 | -| `contactName` | `String` | 联系人姓名 | -| `contactPhone` | `String` | 联系人电话 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /internal/mp/contract/by-order/{orderId}/all — 按订单查所有有效合同（TOUR+INSURANCE各一条） - -> **关联字典**： -- contract_status：合同状态（显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -### 📌 `POST` /internal/mp/contract/{contractId}/resend-sms — 重新发送合同签署短信 - -> 内部服务间调用。小程序端用户请求重发签署短信，用于签署链接过期或短信未收到的场景。仅SIGNING状态的合同可操作。 - -**关联字典**： -- contract_status：合同状态（仅SIGNING可操作） - -**参数** - - - `{contractId}` (`Long`) — 路径参数 - -**响应** `Result<Boolean>` - -### 🆕 新增: AdminInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「保险管理」** - -### 📌 `GET` /admin/insurance/products — 保险产品列表 - -> 分页查询已同步的保险产品，支持按是否境外筛选。产品数据来源于保游网同步。 - -**权限**：需管理员登录。 - -**参数** - - - `page` (`Integer`) — 查询参数：页码 - - `pageSize` (`Integer`) — 查询参数：每页条数 - - `isOverseas` (`Boolean`) — 查询参数：是否境外 - -**响应** `Result<PageResult<InsuranceProductVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 保险产品ID | -| `extProductGuid` | `String` | 保游网产品GUID | -| `productName` | `String` | 产品名称 | -| `companyName` | `String` | 保险公司名称 | -| `productType` | `String` | 产品类型 | -| `isOverseas` | `Boolean` | 是否境外产品 | -| `minDays` | `Integer` | 最短保障天数 | -| `maxDays` | `Integer` | 最长保障天数 | -| `minAge` | `Integer` | 最小投保年龄 | -| `maxAge` | `Integer` | 最大投保年龄 | -| `status` | `String` | 产品状态: ACTIVE-已上架, INACTIVE-已下架 | -| `createTime` | `LocalDateTime` | 同步时间 | - -### 📌 `GET` /admin/insurance/products/{id} — 保险产品详情 - -> 返回保险产品完整信息，包含产品名称、保险公司、保障范围、适用地区等。 - -**权限**：需管理员登录。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：保险产品ID - -**响应** `Result<InsuranceProductVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 保险产品ID | -| `extProductGuid` | `String` | 保游网产品GUID | -| `productName` | `String` | 产品名称 | -| `companyName` | `String` | 保险公司名称 | -| `productType` | `String` | 产品类型 | -| `isOverseas` | `Boolean` | 是否境外产品 | -| `minDays` | `Integer` | 最短保障天数 | -| `maxDays` | `Integer` | 最长保障天数 | -| `minAge` | `Integer` | 最小投保年龄 | -| `maxAge` | `Integer` | 最大投保年龄 | -| `status` | `String` | 产品状态: ACTIVE-已上架, INACTIVE-已下架 | -| `createTime` | `LocalDateTime` | 同步时间 | - -### 📌 `GET` /admin/insurance/products/{id}/plans — 保险产品计划及费率 - -> 返回指定保险产品的所有投保计划及对应费率表，包含不同天数区间的保费价格。投保下单前需选择具体计划。 - -**权限**：需管理员登录。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：保险产品ID - -**响应** `Result<List<InsurancePlanVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `planId` | `Long` | 计划ID | -| `productId` | `Long` | 所属产品ID | -| `extPlanGuid` | `String` | 保游网计划GUID | -| `planName` | `String` | 计划名称 | -| `securityList` | `String` | 保障内容(HTML) | -| `rates` | `List<RateVO>` | 费率列表 | -| `rateId` | `Long` | 费率ID | -| `extRateCode` | `String` | 保游网费率编码 | -| `ageRange` | `String` | 适用年龄范围 | -| `dayRange` | `String` | 适用天数范围(如 1, 2, 4-7) | -| `dayType` | `String` | 天数类型: 10-按天, 20-按月, 30-按年 | -| `premium` | `BigDecimal` | 单人保费(元) | - -### 📌 `POST` /admin/insurance/sync-products — 从保游网同步产品数据 - -> 手动触发从保游网API拉取最新保险产品数据（含计划和费率），同步到本地数据库。返回同步的产品数量。 - -**权限**：需管理员登录。 - -**响应** `Result<Integer>` - -### 📌 `GET` /admin/insurance/entities — 投保公司主体列表 - -> 返回系统配置的投保公司主体列表（来自Nacos配置），投保下单时选择以哪个公司主体投保。每个主体包含编码、公司名称和商户ID。 - -**权限**：需管理员登录。 - -**响应** `Result<List<Map<String, String>>>` - -### 📌 `POST` /admin/insurance/purchase-by-scheme — 按方案自动投保(schemeId+orderId) - -> 根据保险方案自动为订单所有出行人投保。系统自动从订单获取出行人信息和行程日期，按方案各段配置逐段投保。 - -**请求体** `AutoPurchaseRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅行订单ID | -| `schemeId` | `Long` | 保险方案ID | - -**响应** `Result<AutoPurchaseResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `boolean` | 是否全部成功 | -| `purchasedCount` | `int` | 成功投保段数 | -| `failedCount` | `int` | 失败段数 | -| `failureReason` | `String` | 失败原因（部分失败或全部失败时返回第一个错误） | - -### 📌 `POST` /admin/insurance/purchase — 投保下单(每人独立保单) - -> **关联字典**： -- gender：性别（被保人信息） -- id_card_type：证件类型（被保人信息） - -**请求体** `PurchaseInsuranceRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 关联旅行订单ID(可选) | -| `planId` | `Long` | 保险计划ID | -| `startDate` | `LocalDate` | 保障开始日期(传orderId时自动从订单获取) | -| `endDate` | `LocalDate` | 保障结束日期(传orderId时自动从订单获取) | -| `insuredPersons` | `List<InsuredPersonDTO>` | 被保人列表(传orderId时自动从订单出行人获取) | -| `entityCode` | `String` | 投保公司主体编码(不填则使用默认主体) | -| `remark` | `String` | 备注 | -| `name` | `String` | 姓名 | -| `idCardNo` | `String` | 证件号码 | -| `birthday` | `LocalDate` | 出生日期 | -| `gender` | `String` | 性别: MALE-男, FEMALE-女 | -| `phone` | `String` | 手机号 | - -**响应** `Result<List<InsuranceOrderDetailVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuredPersons` | `List<InsuredPersonVO>` | 被保人列表 | -| `insuredId` | `Long` | 被保人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型: ID_CARD-身份证, PASSPORT-护照, OTHER-其他 | -| `idCardNo` | `String` | 证件号码 | -| `birthday` | `LocalDate` | 出生日期 | -| `gender` | `String` | 性别: MALE-男, FEMALE-女 | -| `phone` | `String` | 手机号 | -| `isBeneficiary` | `Boolean` | 是否为受益人 | - -### 📌 `POST` /admin/insurance/cancel/{id} — 退保 - -> 对单个保险订单发起退保，调用保游网退保API。退保成功后保险状态变为CANCELLED。 - -**权限**：需管理员登录。 -**注意**：已生效的保单退保可能产生手续费。 - -**关联字典**： -- insurance_status：保险状态（状态流转） - -**参数** - - - `{insuranceOrderId}` (`Long`) — 路径参数：保险订单ID - -**响应** `Result<InsuranceOrderVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceOrderId` | `Long` | 保险订单ID | -| `orderId` | `Long` | 关联旅行订单ID | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `extOrderNo` | `String` | 保游网订单号 | -| `extPolicyNo` | `String` | 保单号 | -| `totalPremium` | `BigDecimal` | 总保费(元) | -| `insuredCount` | `Integer` | 被保人数量 | -| `policyHolderName` | `String` | 投保人姓名(公司名称) | -| `entityCode` | `String` | 投保公司主体编码 | -| `startDate` | `LocalDate` | 保障开始日期 | -| `endDate` | `LocalDate` | 保障结束日期 | -| `status` | `String` | 订单状态: PENDING-待出单, INSURED-已承保, CANCELLED-已退保, FAILED-投保失败 | -| `policyPdfUrl` | `String` | 保单PDF的OSS链接（.pdf结尾，可直接访问） | -| `statusLabel` | `String` | 状态中文标签 | -| `remark` | `String` | 备注 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/insurance/orders — 保险订单列表 - -> **关联字典**： -- insurance_status：保险状态（列表筛选+显示） - -**响应** `Result<PageResult<InsuranceOrderVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceOrderId` | `Long` | 保险订单ID | -| `orderId` | `Long` | 关联旅行订单ID | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `extOrderNo` | `String` | 保游网订单号 | -| `extPolicyNo` | `String` | 保单号 | -| `totalPremium` | `BigDecimal` | 总保费(元) | -| `insuredCount` | `Integer` | 被保人数量 | -| `policyHolderName` | `String` | 投保人姓名(公司名称) | -| `entityCode` | `String` | 投保公司主体编码 | -| `startDate` | `LocalDate` | 保障开始日期 | -| `endDate` | `LocalDate` | 保障结束日期 | -| `status` | `String` | 订单状态: PENDING-待出单, INSURED-已承保, CANCELLED-已退保, FAILED-投保失败 | -| `policyPdfUrl` | `String` | 保单PDF的OSS链接（.pdf结尾，可直接访问） | -| `statusLabel` | `String` | 状态中文标签 | -| `remark` | `String` | 备注 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/insurance/orders/{id} — 保险订单详情(含被保人) - -> **关联字典**： -- insurance_status：保险状态（显示） -- gender：性别（被保人信息显示） -- id_card_type：证件类型（被保人信息显示） - -**参数** - - - `{insuranceOrderId}` (`Long`) — 路径参数：保险订单ID - -**响应** `Result<InsuranceOrderDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuredPersons` | `List<InsuredPersonVO>` | 被保人列表 | -| `insuredId` | `Long` | 被保人ID | -| `name` | `String` | 姓名 | -| `idCardType` | `String` | 证件类型: ID_CARD-身份证, PASSPORT-护照, OTHER-其他 | -| `idCardNo` | `String` | 证件号码 | -| `birthday` | `LocalDate` | 出生日期 | -| `gender` | `String` | 性别: MALE-男, FEMALE-女 | -| `phone` | `String` | 手机号 | -| `isBeneficiary` | `Boolean` | 是否为受益人 | - -### 📌 `GET` /admin/insurance/orders/by-order/{orderId} — 按旅行订单查询保险单 - -> 根据旅行订单ID查询关联的所有保险订单列表。在订单详情页展示保险购买情况。 - -**权限**：需管理员登录。 - -**关联字典**： -- insurance_status：保险状态（列表显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<List<InsuranceOrderVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceOrderId` | `Long` | 保险订单ID | -| `orderId` | `Long` | 关联旅行订单ID | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `extOrderNo` | `String` | 保游网订单号 | -| `extPolicyNo` | `String` | 保单号 | -| `totalPremium` | `BigDecimal` | 总保费(元) | -| `insuredCount` | `Integer` | 被保人数量 | -| `policyHolderName` | `String` | 投保人姓名(公司名称) | -| `entityCode` | `String` | 投保公司主体编码 | -| `startDate` | `LocalDate` | 保障开始日期 | -| `endDate` | `LocalDate` | 保障结束日期 | -| `status` | `String` | 订单状态: PENDING-待出单, INSURED-已承保, CANCELLED-已退保, FAILED-投保失败 | -| `policyPdfUrl` | `String` | 保单PDF的OSS链接（.pdf结尾，可直接访问） | -| `statusLabel` | `String` | 状态中文标签 | -| `remark` | `String` | 备注 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/insurance/coverage/{orderId} — 查询订单保险保障(含被保人详情) - -> 返回订单维度的保险保障汇总信息，包含覆盖人数、保障期间、每位被保人的保单明细。用于订单详情页的保险保障展示。 - -**权限**：需管理员登录。 - -**关联字典**： -- insurance_status：保险状态（显示） -- gender：性别（被保人信息显示） -- id_card_type：证件类型（被保人信息显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<InsuranceCoverageVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅行订单ID | -| `orderCount` | `Integer` | 保险单数量 | -| `insuranceOrders` | `List<InsuranceOrderDetailVO>` | 保险订单详情列表(含被保人) | - -### 📌 `POST` /admin/insurance/trial-price — 保费试算(本地费率) - -> 根据保险计划、投保天数和人数，使用本地同步的费率表试算保费。不调用保游网API，用于投保前的费用预估。 - -**权限**：需管理员登录。 - -**请求体** `TrialPriceRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `planId` | `Long` | 保险计划ID | -| `startDate` | `LocalDate` | 保障开始日期 | -| `endDate` | `LocalDate` | 保障结束日期 | -| `insuredCount` | `Integer` | 被保人数量 | - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /admin/insurance/balance — 查询保游网账户余额 - -> 查询保游网平台的账户余额，用于管理端展示当前可用投保额度。查询失败时返回null（非关键信息，不影响业务）。 - -**权限**：需管理员登录。 - -**响应** `Result<JsonNode>` - -### 📌 `GET` /admin/insurance/policy/{id}/download — 下载保单PDF(Base64) - -> 从保游网下载指定保险订单的电子保单PDF，以Base64编码返回。前端可解码后展示或提供下载。 - -**权限**：需管理员登录。 - -**参数** - - - `{insuranceOrderId}` (`Long`) — 路径参数：保险订单ID - -**响应** `Result<String>` - -### 📌 `GET` /admin/insurance/recharge-url — 获取保游网充值链接(已废弃) - -> **已废弃**：保游网充值网站已关闭。请改用 POST /admin/insurance/recharge 在线充值接口。 - -**权限**：需管理员登录。 - -**响应** `Result<String>` - -### 📌 `POST` /admin/insurance/recharge — 在线充值(调用保游网支付API) - -> 调用保游网在线充值API，生成充值支付链接。支持选择支付方式（支付宝/微信），充值完成后账户余额自动更新。 - -**权限**：需管理员登录。 - -**请求体** `RechargeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `money` | `BigDecimal` | 充值金额（元） | -| `payType` | `Integer` | 支付方式：11=支付宝扫码, 33=微信扫码 | -| `backUrl` | `String` | 同步回调地址（支付宝用） | - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /admin/insurance/upload-missing-pdfs — 补传旧保单PDF到OSS - -> 将所有已承保但未上传PDF的保单，异步下载PDF并上传到OSS。用于历史数据迁移。 - -**响应** `Result<Integer>` - -### 📌 `POST` /admin/insurance/share-policy — 分享保单(合并某出行人所有有效保单PDF,上传OSS返回链接) - -> 合并指定出行人的所有有效保单PDF为一个文件，上传至OSS后返回公开访问链接。用于管理端分享保单给出行人。 - -**权限**：需管理员登录。 - -**请求体** `SharePolicyRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅游订单ID | -| `insuredName` | `String` | 被保人姓名 | -| `insuredIdCardNo` | `String` | 被保人证件号码 | - -**响应** `Result<PolicyShareVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `pdfBase64` | `String` | 合并后的PDF（Base64编码） | -| `personName` | `String` | 被保人姓名 | -| `policyCount` | `int` | 包含的保单数量 | -| `failedCount` | `int` | 下载失败的保单数量（已跳过） | - -### 📌 `POST` /admin/insurance/order/{orderId}/selective-purchase — 选择部分出行人投保 - -> 自动投保失败后，管理员可选择部分出行人手动在线投保（如排除不满1岁婴儿）。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<AutoPurchaseResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `boolean` | 是否全部成功 | -| `purchasedCount` | `int` | 成功投保段数 | -| `failedCount` | `int` | 失败段数 | -| `failureReason` | `String` | 失败原因（部分失败或全部失败时返回第一个错误） | - -### 📌 `POST` /admin/insurance/order/{orderId}/traveler-note — 添加出行人保险备注 - -> 为不能在线投保的出行人添加备注（如不满1岁婴儿标记为线下投保）。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -### 📌 `DELETE` /admin/insurance/order/{orderId}/traveler-note/{noteId} — 删除出行人保险备注 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - - `{noteId}` (`Long`) — 路径参数：备注ID - -**响应** `Result<Void>` - -### 📌 `GET` /admin/insurance/order/{orderId}/traveler-coverage — 查询出行人保险覆盖状态 - -> 返回订单每个出行人的保险状态： - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -### 🆕 新增: AdminInsuranceScheme - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「保险方案模板」** - -### 📌 `GET` /admin/insurance/scheme/list — 活跃方案列表(下拉选择用) - -> 返回所有状态为启用的保险方案模板，用于投保下单时的方案下拉选择。 - -**权限**：需管理员登录。 - -**响应** `Result<List<InsuranceSchemeVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外 | -| `sortOrder` | `Integer` | 排序序号 | -| `totalDays` | `Integer` | 适用行程天数 | -| `status` | `String` | 状态: ACTIVE-启用, INACTIVE-停用 | -| `adminId` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `segmentCount` | `Integer` | 段数量 | -| `segments` | `List<SegmentVO>` | 方案段列表 | -| `segmentId` | `Long` | 段ID | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天 | -| `dayOffsetEnd` | `Integer` | 相对结束天(-1=最后一天) | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `sortOrder` | `Integer` | 段排序序号 | - -### 📌 `GET` /admin/insurance/scheme/list-all — 全部方案列表(管理用) - -> 返回所有保险方案模板（含启用和停用），用于方案管理页面展示和编辑。 - -**权限**：需管理员登录。 - -**响应** `Result<List<InsuranceSchemeVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外 | -| `sortOrder` | `Integer` | 排序序号 | -| `totalDays` | `Integer` | 适用行程天数 | -| `status` | `String` | 状态: ACTIVE-启用, INACTIVE-停用 | -| `adminId` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `segmentCount` | `Integer` | 段数量 | -| `segments` | `List<SegmentVO>` | 方案段列表 | -| `segmentId` | `Long` | 段ID | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天 | -| `dayOffsetEnd` | `Integer` | 相对结束天(-1=最后一天) | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `sortOrder` | `Integer` | 段排序序号 | - -### 📌 `GET` /admin/insurance/scheme/{id} — 方案详情 - -> 返回单个保险方案模板的完整信息，包含方案名称、保险产品关联、天数规则、费率配置等。 - -**权限**：需管理员登录。 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数：方案ID - -**响应** `Result<InsuranceSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外 | -| `sortOrder` | `Integer` | 排序序号 | -| `totalDays` | `Integer` | 适用行程天数 | -| `status` | `String` | 状态: ACTIVE-启用, INACTIVE-停用 | -| `adminId` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `segmentCount` | `Integer` | 段数量 | -| `segments` | `List<SegmentVO>` | 方案段列表 | -| `segmentId` | `Long` | 段ID | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天 | -| `dayOffsetEnd` | `Integer` | 相对结束天(-1=最后一天) | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `sortOrder` | `Integer` | 段排序序号 | - -### 📌 `POST` /admin/insurance/scheme — 创建方案 - -> 创建保险方案模板，配置关联保险产品、投保天数规则和费率。创建后默认启用。 - -**权限**：需管理员登录。 - -**请求体** `InsuranceSchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外: false=境内, true=境外 | -| `sortOrder` | `Integer` | 排序序号（越小越靠前） | -| `segments` | `List<SegmentDTO>` | 保险段列表 | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天(1-based, 1=出发日) | -| `dayOffsetEnd` | `Integer` | 相对结束天(1-based, -1=行程最后一天) | -| `productId` | `Long` | 保险产品ID | -| `planId` | `Long` | 保险计划ID | -| `sortOrder` | `Integer` | 段排序序号 | - -**响应** `Result<InsuranceSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外 | -| `sortOrder` | `Integer` | 排序序号 | -| `totalDays` | `Integer` | 适用行程天数 | -| `status` | `String` | 状态: ACTIVE-启用, INACTIVE-停用 | -| `adminId` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `segmentCount` | `Integer` | 段数量 | -| `segments` | `List<SegmentVO>` | 方案段列表 | -| `segmentId` | `Long` | 段ID | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天 | -| `dayOffsetEnd` | `Integer` | 相对结束天(-1=最后一天) | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `sortOrder` | `Integer` | 段排序序号 | - -### 📌 `PUT` /admin/insurance/scheme/{id} — 更新方案 - -> 更新保险方案模板的配置信息，包括方案名称、关联产品、天数规则、费率等。 - -**权限**：需管理员登录。 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数：方案ID - -**请求体** `InsuranceSchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外: false=境内, true=境外 | -| `sortOrder` | `Integer` | 排序序号（越小越靠前） | -| `segments` | `List<SegmentDTO>` | 保险段列表 | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天(1-based, 1=出发日) | -| `dayOffsetEnd` | `Integer` | 相对结束天(1-based, -1=行程最后一天) | -| `productId` | `Long` | 保险产品ID | -| `planId` | `Long` | 保险计划ID | -| `sortOrder` | `Integer` | 段排序序号 | - -**响应** `Result<InsuranceSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外 | -| `sortOrder` | `Integer` | 排序序号 | -| `totalDays` | `Integer` | 适用行程天数 | -| `status` | `String` | 状态: ACTIVE-启用, INACTIVE-停用 | -| `adminId` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `segmentCount` | `Integer` | 段数量 | -| `segments` | `List<SegmentVO>` | 方案段列表 | -| `segmentId` | `Long` | 段ID | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天 | -| `dayOffsetEnd` | `Integer` | 相对结束天(-1=最后一天) | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `sortOrder` | `Integer` | 段排序序号 | - -### 📌 `PUT` /admin/insurance/scheme/{id}/toggle-status — 切换方案状态(启用/停用) - -> 切换保险方案模板的启用/停用状态。停用后不会出现在投保下单的方案选择列表中。 - -**权限**：需管理员登录。 - -**关联字典**： -- common_status：通用状态（ACTIVE=启用/INACTIVE=停用） - -**参数** - - - `{schemeId}` (`Long`) — 路径参数：方案ID - -**响应** `Result<InsuranceSchemeVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `name` | `String` | 方案名称 | -| `description` | `String` | 方案描述 | -| `isOverseas` | `Boolean` | 是否境外 | -| `sortOrder` | `Integer` | 排序序号 | -| `totalDays` | `Integer` | 适用行程天数 | -| `status` | `String` | 状态: ACTIVE-启用, INACTIVE-停用 | -| `adminId` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `segmentCount` | `Integer` | 段数量 | -| `segments` | `List<SegmentVO>` | 方案段列表 | -| `segmentId` | `Long` | 段ID | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 相对起始天 | -| `dayOffsetEnd` | `Integer` | 相对结束天(-1=最后一天) | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `sortOrder` | `Integer` | 段排序序号 | - -### 📌 `DELETE` /admin/insurance/scheme/{id} — 删除方案(软删除) - -> 软删除保险方案模板。已使用该方案创建的保险订单不受影响。 - -**权限**：需管理员登录。 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数：方案ID - -**响应** `Result<Void>` - -### 📌 `POST` /admin/insurance/scheme/preview-apply — 预览应用方案(解析日期+估算保费) - -> 根据方案模板和行程日期预览投保效果：解析实际投保起止日期、计算每人保费和总保费。用于投保前确认费用。 - -**权限**：需管理员登录。 - -**请求体** `ApplySchemeRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `orderId` | `Long` | 旅行订单ID（用于获取出发/返回日期和出行人数） | -| `departureDate` | `LocalDate` | 出发日期（可选，不传则从订单获取） | -| `returnDate` | `LocalDate` | 返回日期（可选，不传则从订单获取） | -| `insuredCount` | `Integer` | 被保人数量（可选，不传则从订单获取出行人数） | - -**响应** `Result<ApplySchemePreviewVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 方案ID | -| `schemeName` | `String` | 方案名称 | -| `departureDate` | `LocalDate` | 行程出发日期 | -| `returnDate` | `LocalDate` | 行程返回日期 | -| `tripDays` | `Integer` | 行程天数 | -| `insuredCount` | `Integer` | 被保人数量 | -| `totalEstimatedPremium` | `BigDecimal` | 预估总保费(所有段合计) | -| `segments` | `List<ResolvedSegment>` | 解析后的保险段列表 | -| `warnings` | `List<String>` | 警告信息（如日期间隙、重叠、超出行程范围等） | -| `segmentName` | `String` | 段名称 | -| `dayOffsetStart` | `Integer` | 原始起始天偏移 | -| `dayOffsetEnd` | `Integer` | 原始结束天偏移 | -| `resolvedStartDate` | `LocalDate` | 解析后的实际开始日期 | -| `resolvedEndDate` | `LocalDate` | 解析后的实际结束日期 | -| `coverageDays` | `Integer` | 覆盖天数 | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `unitPremium` | `BigDecimal` | 单人保费 | -| `estimatedPremium` | `BigDecimal` | 该段预估总保费(单人保费 x 人数) | -| `skipped` | `Boolean` | 是否被跳过(超出行程范围) | -| `skipReason` | `String` | 跳过原因 | - -### 🆕 新增: InternalInsurance - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】保险（Feign调用）」** - -### 📌 `GET` /internal/insurance/by-order/{orderId} — 按旅行订单查询保险单(内部调用) - -> 内部服务间调用。根据旅行订单ID查询关联的所有保险订单，返回保险状态、保费、保障期间等信息。 - -**关联字典**： -- insurance_status：保险状态（返回字段） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<List<InsuranceOrderVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceOrderId` | `Long` | 保险订单ID | -| `orderId` | `Long` | 关联旅行订单ID | -| `productId` | `Long` | 保险产品ID | -| `productName` | `String` | 保险产品名称 | -| `planId` | `Long` | 保险计划ID | -| `planName` | `String` | 保险计划名称 | -| `extOrderNo` | `String` | 保游网订单号 | -| `extPolicyNo` | `String` | 保单号 | -| `totalPremium` | `BigDecimal` | 总保费(元) | -| `insuredCount` | `Integer` | 被保人数量 | -| `policyHolderName` | `String` | 投保人姓名(公司名称) | -| `entityCode` | `String` | 投保公司主体编码 | -| `startDate` | `LocalDate` | 保障开始日期 | -| `endDate` | `LocalDate` | 保障结束日期 | -| `status` | `String` | 订单状态: PENDING-待出单, INSURED-已承保, CANCELLED-已退保, FAILED-投保失败 | -| `policyPdfUrl` | `String` | 保单PDF的OSS链接（.pdf结尾，可直接访问） | -| `statusLabel` | `String` | 状态中文标签 | -| `remark` | `String` | 备注 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /internal/insurance/by-orders — 按订单批量查询保险单(内部调用) - -> 内部服务间调用。批量查询多个旅行订单的保险订单，返回Map结构（key=订单ID，value=保险单列表），用于订单列表页展示保险状态。 - -**响应** `Result<Map<Long, List<InsuranceOrderVO>>>` - -### 📌 `GET` /internal/insurance/coverage/{orderId} — 查询订单保险保障(含被保人详情,内部调用) - -> 内部服务间调用。返回订单维度的保险保障汇总信息，包含每份保单的被保人明细。用于小程序端按出行人展示保险信息。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - -**响应** `Result<InsuranceCoverageVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅行订单ID | -| `orderCount` | `Integer` | 保险单数量 | -| `insuranceOrders` | `List<InsuranceOrderDetailVO>` | 保险订单详情列表(含被保人) | - -### 📌 `GET` /internal/insurance/coverage-complete/{orderId} — 检查保险是否全覆盖(内部调用) - -> 内部服务间调用。根据出行人数和行程天数计算所需的人日数，与已投保的有效保单覆盖人日数对比，判断保险是否已全覆盖。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - - `travelerCount` (`int`) — 查询参数：出行人数 - - `tripDays` (`int`) — 查询参数：行程天数 - -**响应** `Result<Boolean>` - -### 📌 `GET` /internal/insurance/fully-covered/{orderId} — 检查保险是否全覆盖-含线下备注(内部调用) - -> 考虑在线保单+线下投保备注，判断是否所有出行人都有保险覆盖 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - - `travelerCount` (`int`) — 查询参数：出行人数 - -**响应** `Result<Boolean>` - -### 📌 `POST` /internal/insurance/invalidate/{orderId} — 按订单批量退保(级联失效调用) - -> 内部服务间调用。旅行订单取消或退款时级联调用，将该订单下所有有效保险单批量退保（调用保游网退保API），记录退保原因。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：旅行订单ID - - `reason` (`String`) — 查询参数：退保原因 - -**响应** `Result<Void>` - -### 📌 `GET` /internal/insurance/policy/{id}/download — 下载单张保单PDF(内部调用) - -> 内部服务间调用。从保游网下载指定保险订单的电子保单PDF，以Base64编码返回。 - -**参数** - - - `{insuranceOrderId}` (`Long`) — 路径参数：保险订单ID - -**响应** `Result<String>` - -### 📌 `POST` /internal/insurance/upload-missing-pdfs — 补传旧保单PDF到OSS(内部调用) - -**响应** `Result<Integer>` - -### 📌 `POST` /internal/insurance/share-policy — 分享保单PDF(内部调用,返回base64) - -> 内部服务间调用。合并指定出行人的所有有效保单PDF为一个文件，上传至OSS后返回下载链接和Base64内容，用于小程序端分享保单。 - -**请求体** `SharePolicyRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 旅游订单ID | -| `insuredName` | `String` | 被保人姓名 | -| `insuredIdCardNo` | `String` | 被保人证件号码 | - -**响应** `Result<PolicyShareVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `pdfBase64` | `String` | 合并后的PDF（Base64编码） | -| `personName` | `String` | 被保人姓名 | -| `policyCount` | `int` | 包含的保单数量 | -| `failedCount` | `int` | 下载失败的保单数量（已跳过） | - -### 📌 `GET` /internal/insurance/share-policy-by-order/{orderId} — 按订单获取所有保单PDF(内部调用,合并所有出行人) - -> 内部服务间调用。将指定订单下所有出行人的有效保单PDF合并为一个文件，上传至OSS后返回下载链接，用于订单维度的保单查看。 - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - -**响应** `Result<PolicyShareVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `pdfBase64` | `String` | 合并后的PDF（Base64编码） | -| `personName` | `String` | 被保人姓名 | -| `policyCount` | `int` | 包含的保单数量 | -| `failedCount` | `int` | 下载失败的保单数量（已跳过） | - -### 📌 `POST` /internal/insurance/auto-purchase — 按方案自动投保(内部调用) - -> 内部服务间调用。根据保险方案自动为订单所有出行人投保： - -**响应** `Result<AutoPurchaseResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `boolean` | 是否全部成功 | -| `purchasedCount` | `int` | 成功投保段数 | -| `failedCount` | `int` | 失败段数 | -| `failureReason` | `String` | 失败原因（部分失败或全部失败时返回第一个错误） | - -### 📌 `GET` /internal/insurance/scheme/{schemeId}/premium — 获取保险方案信息(内部调用) - -> 内部服务间调用。返回方案的适用天数和人均保费，用于产品保存时校验天数匹配并自动填充保险费。 - -**参数** - - - `{schemeId}` (`Long`) — 路径参数：方案ID - - `tripDays` (`int`) — 查询参数：行程天数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /internal/insurance/sync-products — 触发保险产品同步(内部调用/定时任务) - -> 内部服务间调用。从保游网API拉取最新保险产品数据（含计划和费率），同步到本地数据库。返回同步的产品数量。 - -**响应** `Result<Integer>` - -### 🆕 新增: AdminPayment - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「支付管理」** - -### 📌 `GET` /admin/payment/admin/payment - -### 📌 `GET` /admin/payment/merchants - -**响应** `Result<List<MerchantVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `mchId` | `String` | 商户号ID | -| `name` | `String` | 商户名称 | - -### 📌 `GET` /admin/payment/list — 商户号列表 - -> 返回所有已配置的微信支付商户号，用于下拉选择 - -**响应** `Result<PageResult<PaymentVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `Long` | 用户ID | -| `mchId` | `String` | 商户号 | -| `outTradeNo` | `String` | 商户订单号 | -| `transactionIdWx` | `String` | 微信支付交易号 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `payType` | `String` | 支付类型: FULL/DEPOSIT/BALANCE | -| `totalAmount` | `BigDecimal` | 交易金额 | -| `status` | `String` | 交易状态 | -| `payTime` | `LocalDateTime` | 支付时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/payment/{transactionId} — 支付交易列表 - -> 分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选 - -**关联字典**： -- payment_mode：支付模式（列表筛选+显示） - -**参数** - - - `{transactionId}` (`Long`) — 路径参数：交易ID - -**响应** `Result<PaymentVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `Long` | 用户ID | -| `mchId` | `String` | 商户号 | -| `outTradeNo` | `String` | 商户订单号 | -| `transactionIdWx` | `String` | 微信支付交易号 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `payType` | `String` | 支付类型: FULL/DEPOSIT/BALANCE | -| `totalAmount` | `BigDecimal` | 交易金额 | -| `status` | `String` | 交易状态 | -| `payTime` | `LocalDateTime` | 支付时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/payment/order/{orderId} — 交易详情 - -> 获取单笔交易的完整信息，包含微信支付流水号 - -**关联字典**： -- payment_mode：支付模式（显示） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<List<PaymentVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `Long` | 用户ID | -| `mchId` | `String` | 商户号 | -| `outTradeNo` | `String` | 商户订单号 | -| `transactionIdWx` | `String` | 微信支付交易号 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `payType` | `String` | 支付类型: FULL/DEPOSIT/BALANCE | -| `totalAmount` | `BigDecimal` | 交易金额 | -| `status` | `String` | 交易状态 | -| `payTime` | `LocalDateTime` | 支付时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/payment/{orderId}/refund — 按订单查询交易 - -> 查询指定订单的所有支付交易记录 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**请求体** `RefundRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `amount` | `BigDecimal` | 退款金额 | -| `reason` | `String` | 退款原因 | - -**响应** `Result<RefundVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refundId` | `Long` | 退款ID | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `mchId` | `String` | 商户号 | -| `outRefundNo` | `String` | 商户退款单号 | -| `refundIdWx` | `String` | 微信退款单号 | -| `refundAmount` | `BigDecimal` | 退款金额 | -| `totalAmount` | `BigDecimal` | 订单总金额 | -| `reason` | `String` | 退款原因 | -| `status` | `String` | 退款状态 | -| `successTime` | `LocalDateTime` | 退款成功时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/payment/{transactionId}/sync — 发起退款 - -> 退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态 - -权限：SUPER_ADMIN、ADMIN、FINANCE - -**参数** - - - `{transactionId}` (`Long`) — 路径参数：交易ID - -**响应** `Result<PaymentVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `Long` | 用户ID | -| `mchId` | `String` | 商户号 | -| `outTradeNo` | `String` | 商户订单号 | -| `transactionIdWx` | `String` | 微信支付交易号 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `payType` | `String` | 支付类型: FULL/DEPOSIT/BALANCE | -| `totalAmount` | `BigDecimal` | 交易金额 | -| `status` | `String` | 交易状态 | -| `payTime` | `LocalDateTime` | 支付时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/payment/refund/{refundId} — 同步支付状态 - -> 主动查询微信支付状态并同步本地数据，适用于回调未到达的场景 - -**参数** - - - `{refundId}` (`Long`) — 路径参数：退款ID - -**响应** `Result<RefundVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refundId` | `Long` | 退款ID | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `mchId` | `String` | 商户号 | -| `outRefundNo` | `String` | 商户退款单号 | -| `refundIdWx` | `String` | 微信退款单号 | -| `refundAmount` | `BigDecimal` | 退款金额 | -| `totalAmount` | `BigDecimal` | 订单总金额 | -| `reason` | `String` | 退款原因 | -| `status` | `String` | 退款状态 | -| `successTime` | `LocalDateTime` | 退款成功时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/payment/refund/order/{orderId} — 退款详情 - -> 获取单笔退款记录的完整信息，包含微信退款单号和退款状态 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<List<RefundVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refundId` | `Long` | 退款ID | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `mchId` | `String` | 商户号 | -| `outRefundNo` | `String` | 商户退款单号 | -| `refundIdWx` | `String` | 微信退款单号 | -| `refundAmount` | `BigDecimal` | 退款金额 | -| `totalAmount` | `BigDecimal` | 订单总金额 | -| `reason` | `String` | 退款原因 | -| `status` | `String` | 退款状态 | -| `successTime` | `LocalDateTime` | 退款成功时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: InternalPayment - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】支付（Feign调用）」** - -### 📌 `GET` /internal/payment/internal/payment - -### 📌 `POST` /internal/payment/prepay - -**参数** - - - `userId` (`Long`) — 查询参数 - -**请求体** `PrepayRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `clientIp` | `String` | 客户端IP（H5支付必填） | - -**响应** `Result<PrepayResponse>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `appId` | `String` | 小程序AppID | -| `timeStamp` | `String` | 时间戳 | -| `nonceStr` | `String` | 随机字符串 | -| `packageVal` | `String` | 预支付交易会话标识 | -| `signType` | `String` | 签名类型 | -| `paySign` | `String` | 支付签名 | -| `h5Url` | `String` | H5支付跳转URL | - -### 📌 `GET` /internal/payment/status/{orderId} — 创建预支付订单 - -> 由BFF层调用，向微信支付API发起预支付请求，返回前端调起支付所需的参数（prepay_id等） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result<PaymentVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `Long` | 用户ID | -| `mchId` | `String` | 商户号 | -| `outTradeNo` | `String` | 商户订单号 | -| `transactionIdWx` | `String` | 微信支付交易号 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `payType` | `String` | 支付类型: FULL/DEPOSIT/BALANCE | -| `totalAmount` | `BigDecimal` | 交易金额 | -| `status` | `String` | 交易状态 | -| `payTime` | `LocalDateTime` | 支付时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /internal/payment/transactions/{orderId} — 查询支付状态 - -> 查询订单的支付状态，含用户权限校验（userId不匹配时拒绝访问） - -**支付状态**：PENDING=待支付, SUCCESS=成功, CLOSED=已关闭, FAILED=失败（非字典，代码常量） - -**参数** - - - `{orderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - -**响应** `Result<List<PaymentVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `userId` | `Long` | 用户ID | -| `mchId` | `String` | 商户号 | -| `outTradeNo` | `String` | 商户订单号 | -| `transactionIdWx` | `String` | 微信支付交易号 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `payType` | `String` | 支付类型: FULL/DEPOSIT/BALANCE | -| `totalAmount` | `BigDecimal` | 交易金额 | -| `status` | `String` | 交易状态 | -| `payTime` | `LocalDateTime` | 支付时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /internal/payment/refund — 订单交易记录列表 - -> 查询指定订单的所有支付交易记录（含支付和退款），含用户权限校验 - -**支付状态**：PENDING=待支付, SUCCESS=成功, CLOSED=已关闭, FAILED=失败（非字典，代码常量） - -**请求体** `PaymentRefundRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `amount` | `String` | 退款金额 | -| `reason` | `String` | 退款原因 | - -**响应** `Result<RefundVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refundId` | `Long` | 退款ID | -| `transactionId` | `Long` | 交易ID | -| `orderId` | `Long` | 订单ID | -| `orderNo` | `String` | 订单编号 | -| `mchId` | `String` | 商户号 | -| `outRefundNo` | `String` | 商户退款单号 | -| `refundIdWx` | `String` | 微信退款单号 | -| `refundAmount` | `BigDecimal` | 退款金额 | -| `totalAmount` | `BigDecimal` | 订单总金额 | -| `reason` | `String` | 退款原因 | -| `status` | `String` | 退款状态 | -| `successTime` | `LocalDateTime` | 退款成功时间 | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: PaymentCallback - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【回调接口】支付回调」** - -### 📌 `GET` /pay/callback/pay/callback - -### 📌 `POST` /pay/callback/notify/{mchId} - -**参数** - - - `{mchId}` (`String`) — 路径参数 - -**响应** `ResponseEntity<Map<String, String>>` - -### 📌 `POST` /pay/callback/refund-notify/{mchId} — 支付成功回调 - -> 微信支付成功后的异步通知回调（无需认证，通过微信签名验证安全性）。验证签名 → 更新支付状态 → 发送MQ消息通知订单服务 - -**参数** - - - `{mchId}` (`String`) — 路径参数 - -**响应** `ResponseEntity<Map<String, String>>` - ---- - -## 资源服务 - -### 🆕 新增: AdminGuideArticle - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「攻略文章管理」** - -### 📌 `GET` /admin/guide/article/list — 文章列表 - -> 分页查询攻略文章，支持按分类、状态、关键词筛选 - -**关联字典**： -- wiki_status：文章状态（列表筛选+显示） - -**响应** `Result<PageResult<GuideArticleListVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `articleId` | `Long` | 文章ID | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `title` | `String` | 标题 | -| `coverUrl` | `String` | 封面URL | -| `summary` | `String` | 摘要 | -| `viewCount` | `Integer` | 浏览量 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=草稿，1=已发布，2=已下架 | -| `isRecommend` | `Integer` | 是否推荐：0=否，1=是 | -| `isTop` | `Integer` | 是否置顶：0=否，1=是 | -| `publishTime` | `LocalDateTime` | 发布时间 | -| `tags` | `List<GuideTagVO>` | 标签列表 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/guide/article/{articleId} — 文章详情 - -> **关联字典**： -- wiki_status：文章状态（显示） - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**响应** `Result<GuideArticleVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `articleId` | `Long` | 文章ID | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `title` | `String` | 标题 | -| `subtitle` | `String` | 副标题 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `bannerMaterialIds` | `List<Long>` | 轮播图素材ID列表 | -| `summary` | `String` | 摘要 | -| `content` | `String` | 正文内容 | -| `authorName` | `String` | 作者名称 | -| `source` | `String` | 来源 | -| `viewCount` | `Integer` | 浏览量 | -| `likeCount` | `Integer` | 点赞数 | -| `favoriteCount` | `Integer` | 收藏数 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=草稿，1=已发布，2=已下架 | -| `isRecommend` | `Integer` | 是否推荐：0=否，1=是 | -| `isTop` | `Integer` | 是否置顶：0=否，1=是 | -| `publishTime` | `LocalDateTime` | 发布时间 | -| `tags` | `List<GuideTagVO>` | 标签列表 | -| `resources` | `List<GuideArticleResourceVO>` | 关联资源列表 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/guide/article — 创建文章 - -> 创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。 - -**权限**：需管理员登录。 - -**关联字典**： -- wiki_status：文章状态（创建后默认DRAFT） - -**请求体** `ArticleCreateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `title` | `String` | 标题 | -| `subtitle` | `String` | 副标题 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `bannerMaterialIds` | `List<Long>` | 轮播图素材ID列表 | -| `summary` | `String` | 摘要 | -| `content` | `String` | 正文内容 | -| `authorName` | `String` | 作者名称 | -| `source` | `String` | 来源 | -| `sortOrder` | `Integer` | 排序（默认0） | -| `tagIds` | `List<Long>` | 标签ID列表 | -| `resources` | `List<ArticleResourceItem>` | 关联资源列表 | -| `resourceType` | `String` | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -| `resourceId` | `Long` | 资源ID | -| `resourceName` | `String` | 资源名称 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<GuideArticleVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `articleId` | `Long` | 文章ID | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `title` | `String` | 标题 | -| `subtitle` | `String` | 副标题 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `bannerMaterialIds` | `List<Long>` | 轮播图素材ID列表 | -| `summary` | `String` | 摘要 | -| `content` | `String` | 正文内容 | -| `authorName` | `String` | 作者名称 | -| `source` | `String` | 来源 | -| `viewCount` | `Integer` | 浏览量 | -| `likeCount` | `Integer` | 点赞数 | -| `favoriteCount` | `Integer` | 收藏数 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=草稿，1=已发布，2=已下架 | -| `isRecommend` | `Integer` | 是否推荐：0=否，1=是 | -| `isTop` | `Integer` | 是否置顶：0=否，1=是 | -| `publishTime` | `LocalDateTime` | 发布时间 | -| `tags` | `List<GuideTagVO>` | 标签列表 | -| `resources` | `List<GuideArticleResourceVO>` | 关联资源列表 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/guide/article/{articleId} — 更新文章 - -> 更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。 - -**权限**：需管理员登录。 - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**请求体** `ArticleUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `title` | `String` | 标题 | -| `subtitle` | `String` | 副标题 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `bannerMaterialIds` | `List<Long>` | 轮播图素材ID列表 | -| `summary` | `String` | 摘要 | -| `content` | `String` | 正文内容 | -| `authorName` | `String` | 作者名称 | -| `source` | `String` | 来源 | -| `sortOrder` | `Integer` | 排序 | -| `tagIds` | `List<Long>` | 标签ID列表 | - -**响应** `Result<GuideArticleVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `articleId` | `Long` | 文章ID | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `title` | `String` | 标题 | -| `subtitle` | `String` | 副标题 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `bannerMaterialIds` | `List<Long>` | 轮播图素材ID列表 | -| `summary` | `String` | 摘要 | -| `content` | `String` | 正文内容 | -| `authorName` | `String` | 作者名称 | -| `source` | `String` | 来源 | -| `viewCount` | `Integer` | 浏览量 | -| `likeCount` | `Integer` | 点赞数 | -| `favoriteCount` | `Integer` | 收藏数 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=草稿，1=已发布，2=已下架 | -| `isRecommend` | `Integer` | 是否推荐：0=否，1=是 | -| `isTop` | `Integer` | 是否置顶：0=否，1=是 | -| `publishTime` | `LocalDateTime` | 发布时间 | -| `tags` | `List<GuideTagVO>` | 标签列表 | -| `resources` | `List<GuideArticleResourceVO>` | 关联资源列表 | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/guide/article/{articleId} — 删除文章 - -> 软删除攻略文章，同时清除文章的标签关联。 - -**权限**：需管理员登录。 - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/guide/article/{articleId}/status — 发布/下架 - -> 切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看 - -**关联字典**： -- wiki_status：文章状态（状态切换） - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**请求体** `StatusRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `status` | `Integer` | 状态值 | - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/guide/article/{articleId}/recommend — 设置推荐 - -> 设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示 - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**请求体** `RecommendRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `isRecommend` | `Integer` | 是否推荐：0=否，1=是 | - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/guide/article/{articleId}/top — 设置置顶 - -> 设置/取消文章置顶。置顶文章在分类列表中始终排在最前面 - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**请求体** `TopRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `isTop` | `Integer` | 是否置顶：0=否，1=是 | - -**响应** `Result<Void>` - -### 🆕 新增: AdminGuideCategory - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「攻略分类管理」** - -### 📌 `GET` /admin/guide/category/list — 分类列表 - -> 返回全部攻略分类（含启用和停用），按排序值升序排列 - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `Result<List<GuideCategoryVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=禁用，1=启用 | -| `articleCount` | `Integer` | 文章数量 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/guide/category/enabled — 启用的分类列表 - -> 仅返回状态为启用的分类，创建文章时用于选择分类 - -**响应** `Result<List<GuideCategoryVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=禁用，1=启用 | -| `articleCount` | `Integer` | 文章数量 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/guide/category — 创建分类 - -> 创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。 - -**权限**：需管理员登录。 - -**请求体** `CategoryCreateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序（默认0） | - -**响应** `Result<GuideCategoryVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=禁用，1=启用 | -| `articleCount` | `Integer` | 文章数量 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/guide/category/{categoryId} — 更新分类 - -> 更新攻略分类的名称、图标、描述等信息。 - -**权限**：需管理员登录。 - -**参数** - - - `{categoryId}` (`Long`) — 路径参数 - -**请求体** `CategoryUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<GuideCategoryVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=禁用，1=启用 | -| `articleCount` | `Integer` | 文章数量 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/guide/category/{categoryId} — 删除分类 - -> 删除分类前需确保分类下无文章，否则删除失败 - -**参数** - - - `{categoryId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/guide/category/{categoryId}/status — 更新分类状态 - -> 启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章 - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**参数** - - - `{categoryId}` (`Long`) — 路径参数 - -**请求体** `StatusRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `status` | `Integer` | 状态值 | - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/guide/category/{categoryId}/sort — 更新分类排序 - -> 更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。 - -**权限**：需管理员登录。 - -**参数** - - - `{categoryId}` (`Long`) — 路径参数 - -**请求体** `CategorySortRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `sortOrder` | `Integer` | 排序值 | - -**响应** `Result<Void>` - -### 🆕 新增: AdminGuideTag - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「攻略标签管理」** - -### 📌 `GET` /admin/guide/tag/managed — 系统标签列表 - -> 返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页 - -**响应** `Result<List<GuideTagVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `Long` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `tagType` | `Integer` | 标签类型：0=系统管理，1=自定义 | -| `useCount` | `Integer` | 使用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/guide/tag/all — 所有标签列表 - -> 返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器 - -**响应** `Result<List<GuideTagVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `Long` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `tagType` | `Integer` | 标签类型：0=系统管理，1=自定义 | -| `useCount` | `Integer` | 使用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/guide/tag — 创建标签 - -> 创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagName` | `String` | 标签名称 | - -**响应** `Result<GuideTagVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `Long` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `tagType` | `Integer` | 标签类型：0=系统管理，1=自定义 | -| `useCount` | `Integer` | 使用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/guide/tag/{tagId} — 更新标签 - -> 更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**参数** - - - `{tagId}` (`Long`) — 路径参数 - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | - -**响应** `Result<GuideTagVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `Long` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `tagType` | `Integer` | 标签类型：0=系统管理，1=自定义 | -| `useCount` | `Integer` | 使用次数 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/guide/tag/{tagId} — 删除标签 - -> 删除标签并自动解除与所有文章的关联关系。 - -**权限**：需管理员登录。 - -**参数** - - - `{tagId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/guide/tag/article/{articleId} — 更新文章标签 - -> 全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签） - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**请求体** `ArticleTagUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagIds` | `List<Long>` | 标签ID列表 | - -**响应** `Result<Void>` - -### 🆕 新增: InternalWiki - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「【内部接口】攻略百科（Feign调用）」** - -### 📌 `GET` /internal/wiki/categories — 查询已启用的攻略分类列表 - -> 内部服务间调用。返回所有状态为启用的攻略分类，供小程序端展示分类导航。 - -**关联字典**： -- common_status：通用状态（仅返回ACTIVE状态的分类） - -**响应** `Result<List<GuideCategoryVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryId` | `Long` | 分类ID | -| `categoryName` | `String` | 分类名称 | -| `icon` | `String` | 图标 | -| `coverMaterialId` | `Long` | 封面素材ID | -| `coverUrl` | `String` | 封面URL | -| `description` | `String` | 描述 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `Integer` | 状态：0=禁用，1=启用 | -| `articleCount` | `Integer` | 文章数量 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /internal/wiki/category/{categoryId}/articles — 分页查询指定分类下的已发布文章 - -> **关联字典**： -- wiki_status：文章状态（返回字段） - -**参数** - - - `{categoryId}` (`Long`) — 路径参数 - - `page` (`Integer`) — 查询参数 - - `pageSize` (`Integer`) — 查询参数 - -**响应** `Result<PageResult<Map<String, Object>>>` - -### 📌 `GET` /internal/wiki/article/{articleId} — 查询已发布文章详情 - -> **关联字典**： -- wiki_status：文章状态（返回字段） - -**参数** - - - `{articleId}` (`Long`) — 路径参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/wiki/recommend-articles — 查询推荐文章列表 - -> 内部服务间调用。返回已发布且标记为推荐的文章列表，用于小程序首页推荐位展示。默认返回5条。 - -**参数** - - - `limit` (`Integer`) — 查询参数 - -**响应** `Result<List<Map<String, Object>>>` - -### 🆕 新增: InternalMaterial - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「素材内部接口（Feign调用）」** - -### 📌 `POST` /internal/material/ref/bind — 绑定引用 - -> 将素材与业务实体建立引用关系（如景区ID+封面图），记录引用类型（COVER/GALLERY/DETAIL等） - -**参数** - - - `adminId` (`Long`) — 查询参数 - -**请求体** `RefBindRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `Long` | 素材ID | -| `bizType` | `String` | 业务类型 | -| `bizId` | `Long` | 业务ID | -| `bizName` | `String` | 业务名称 | -| `usageType` | `String` | 用途类型 | - -**响应** `Result<Void>` - -### 📌 `POST` /internal/material/ref/batch-bind — 批量绑定引用 - -> 批量建立素材与业务实体的引用关系，常用于保存包含多张图片的业务数据 - -**参数** - - - `adminId` (`Long`) — 查询参数 - -**请求体** `RefBatchBindRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refs` | `List<RefBindRequest>` | 引用绑定列表 | - -**响应** `Result<Void>` - -### 📌 `DELETE` /internal/material/ref/unbind — 解绑引用 - -> 删除单个素材与业务实体的引用关系 - -**请求体** `RefUnbindRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `Long` | 素材ID | -| `bizType` | `String` | 业务类型 | -| `bizId` | `Long` | 业务ID | -| `usageType` | `String` | 用途类型 | - -**响应** `Result<Void>` - -### 📌 `DELETE` /internal/material/ref/batch-unbind — 批量解绑引用 - -> 批量删除素材引用关系，常用于业务实体更新时先清除旧引用再绑定新引用 - -**请求体** `RefBatchUnbindRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `refs` | `List<RefUnbindRequest>` | 解绑列表 | - -**响应** `Result<Void>` - -### 📌 `DELETE` /internal/material/ref/unbind-all — 全量解绑业务实体引用 - -> 删除指定业务实体的所有素材引用，用于业务实体被删除时清理引用数据 - -**参数** - - - `bizType` (`String`) — 查询参数 - - `bizId` (`Long`) — 查询参数 - -**响应** `Result<Void>` - -### 📌 `POST` /internal/material/by-ids — 批量查询素材信息 - -> 内部服务间调用。根据素材ID列表批量查询素材信息，用于其他服务获取素材详情（如产品、景区等关联的素材数据）。 - -**请求体** `BatchMaterialIdsRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialIds` | `List<Long>` | 素材ID列表 | - -**响应** `Result<List<MaterialVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: MaterialCategoryPermission - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「素材分类权限管理」** - -### 📌 `GET` /admin/material/category/permissions/{roleCode} — 获取角色的分类权限 - -> 仅超级管理员可操作。返回指定角色可访问的素材分类编码列表 - -**参数** - - - `{roleCode}` (`String`) — 路径参数：角色编码 - -**响应** `Result<List<String>>` - -### 📌 `PUT` /admin/material/category/permissions/{roleCode} — 更新角色的分类权限 - -> 仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表 - -**参数** - - - `{roleCode}` (`String`) — 路径参数：角色编码 - -**请求体** `CategoryPermissionUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryCodes` | `List<String>` | 分类编码列表 | - -**响应** `Result<Void>` - -### 🆕 新增: Material - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「素材管理」** - -### 📌 `POST` /admin/material/upload/token — 获取上传凭证 - -> 上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验 - -**请求体** `MaterialUploadTokenRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryCode` | `String` | 分类编码 | -| `subCategoryId` | `Long` | 子分类ID（文件夹上传时使用） | -| `materialName` | `String` | 素材名称 | -| `filename` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小(字节) | -| `md5` | `String` | 文件MD5 | -| `contentType` | `String` | 文件MIME类型 | - -**响应** `Result<MaterialUploadTokenVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `contentType` | `String` | 上传时必须使用的Content-Type（与预签名URL签名一致） | -| `uploadMode` | `String` | 上传模式: PRESIGNED_URL/STS_MULTIPART | -| `uploadUrl` | `String` | 上传URL | -| `ossKey` | `String` | OSS对象Key | -| `expireAt` | `LocalDateTime` | 过期时间 | -| `stsToken` | `StsTokenInfo` | STS临时凭证 | -| `bucket` | `String` | OSS Bucket名称 | -| `region` | `String` | OSS Region | -| `instantUpload` | `boolean` | 是否秒传 | -| `material` | `MaterialVO` | 秒传时返回的素材信息 | -| `accessKeyId` | `String` | AccessKey ID | -| `accessKeySecret` | `String` | AccessKey Secret | -| `securityToken` | `String` | 安全令牌 | -| `expiration` | `String` | 过期时间 | - -### 📌 `POST` /admin/material/upload/confirm — 确认上传完成 - -> 上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重 - -**关联字典**： -- material_tag：素材标签（上传时可选标签） - -**请求体** `MaterialUploadConfirmRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `description` | `String` | 素材描述 | -| `tagIds` | `List<String>` | 标签ID列表 | - -**响应** `Result<MaterialVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/material/upload/folder — 文件夹上传初始化（创建分类+批量获取凭证） - -> 支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认 - -**请求体** `FolderUploadInitRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryCode` | `String` | 分类编码 | -| `folderPaths` | `List<String>` | 文件夹路径列表（如 [\ | -| `files` | `List<FileItem>` | 文件列表 | -| `folderPath` | `String` | 文件所在文件夹路径（与folderPaths中的路径对应） | -| `filename` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小(字节) | -| `md5` | `String` | 文件MD5 | -| `contentType` | `String` | 文件MIME类型 | -| `materialName` | `String` | 素材名称 | - -**响应** `Result<FolderUploadInitVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `folderCategoryMap` | `Map<String, String>` | 文件夹路径 → 子分类ID 映射 | -| `fileTokens` | `List<FileTokenItem>` | 各文件的上传凭证列表 | -| `filename` | `String` | 文件名 | -| `folderPath` | `String` | 文件夹路径 | -| `materialId` | `String` | 素材ID | -| `uploadUrl` | `String` | 上传URL | -| `uploadMethod` | `String` | 上传方式: PUT/POST | -| `uploadHeaders` | `Map<String, String>` | 上传请求头 | -| `ossKey` | `String` | OSS对象Key | -| `bucket` | `String` | OSS Bucket名称 | -| `region` | `String` | OSS Region | -| `instantUpload` | `Boolean` | 是否秒传（文件已存在） | -| `error` | `String` | 错误信息（该文件获取凭证失败时） | - -### 📌 `POST` /admin/material/upload/chunk/init — 分片上传-初始化 - -> 大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。 - -**权限**：需管理员登录，受角色分类权限限制。 - -**请求体** `ChunkUploadInitRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `filename` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小（字节） | -| `contentType` | `String` | 文件MIME类型 | -| `fileHash` | `String` | 文件MD5哈希（用于去重） | - -**响应** `Result<ChunkUploadInitVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `uploadId` | `String` | 上传ID（OSS multipart uploadId） | -| `chunkSize` | `int` | 推荐分片大小（字节） | -| `fileId` | `String` | 文件ID（file_info记录） | -| `ossKey` | `String` | OSS对象Key | - -### 📌 `POST` /admin/material/upload/chunk — 分片上传-上传分片 - -> 大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。 - -**参数** - - - `uploadId` (`String`) — 查询参数：上传ID - - `chunkIndex` (`int`) — 查询参数：分片索引（从0开始） - - `chunk` (`MultipartFile`) — 查询参数：分片文件 - -**响应** `Result<ChunkUploadPartVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `etag` | `String` | 分片ETag（用于合并时校验） | - -### 📌 `POST` /admin/material/upload/chunk/complete — 分片上传-完成合并 - -> 大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。 - -**请求体** `ChunkUploadCompleteRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `uploadId` | `String` | 上传ID | - -**响应** `Result<MaterialVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/material/upload/chunk/cancel — 分片上传-取消 - -> 取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。 - -**请求体** `ChunkUploadCancelRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `uploadId` | `String` | 上传ID | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/material/list — 素材列表 - -> 分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） - -**响应** `Result<PageResult<MaterialVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/material/{materialId} — 素材详情 - -> 返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。 - -**关联字典**： -- file_type：文件类型（显示） - -**参数** - - - `{materialId}` (`Long`) — 路径参数：素材ID - -**响应** `Result<MaterialVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/material/{materialId} — 更新素材信息 - -> **关联字典**： -- material_tag：素材标签（编辑时选择标签） - -**参数** - - - `{materialId}` (`Long`) — 路径参数：素材ID - -**请求体** `MaterialUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `categoryCode` | `String` | 分类编码 | -| `subCategoryId` | `Long` | 子分类ID（0表示清除子分类） | - -**响应** `Result<MaterialVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/material/{materialId} — 删除素材 - -> 有引用时自动清理引用后删除 - -**参数** - - - `{materialId}` (`Long`) — 路径参数：素材ID - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/material/batch — 批量删除素材 - -> 批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因 - -**请求体** `BatchDeleteRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialIds` | `List<String>` | 素材ID列表 | - -**响应** `Result<BatchDeleteResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `successCount` | `int` | 成功删除数量 | -| `failedItems` | `List<FailedItem>` | 失败项列表 | -| `materialId` | `String` | 素材ID | -| `reason` | `String` | 失败原因 | - -### 📌 `PUT` /admin/material/{materialId}/tags — 更新素材标签 - -> 全量替换单个素材的标签，传入新的标签ID列表 - -**参数** - - - `{materialId}` (`Long`) — 路径参数：素材ID - -**请求体** `MaterialTagUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagIds` | `List<String>` | 标签ID列表 | - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/material/batch/tags — 批量更新标签 - -> 对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除） - -**请求体** `BatchTagRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialIds` | `List<String>` | 素材ID列表 | -| `addTagIds` | `List<String>` | 要添加的标签ID列表 | -| `removeTagIds` | `List<String>` | 要移除的标签ID列表 | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/material/{materialId}/refs — 查看素材引用记录 - -> 查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除 - -**参数** - - - `{materialId}` (`Long`) — 路径参数：素材ID - -**响应** `Result<List<MaterialRefVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `String` | 引用ID | -| `materialId` | `String` | 素材ID | -| `bizType` | `String` | 业务类型 | -| `bizTypeName` | `String` | 业务类型名称 | -| `bizId` | `String` | 业务ID | -| `bizName` | `String` | 业务名称 | -| `usageType` | `String` | 用途类型 | -| `usageTypeName` | `String` | 用途类型名称 | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/material/categories — 获取有权限的分类列表（含素材数量） - -> 返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类 - -**响应** `Result<List<CategoryVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `subCategoryId` | `String` | 子分类ID | -| `parentId` | `String` | 父子分类ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `materialCount` | `Integer` | 素材数量 | -| `children` | `List<CategoryVO>` | 子分类列表 | - -### 📌 `POST` /admin/material/category/sub — 创建子分类 - -> 在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档 - -**请求体** `SubCategoryCreateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `parentCode` | `String` | 根分类编码(scenic/hotel等) | -| `parentId` | `Long` | 父子分类ID(为空则创建在根分类下) | -| `categoryName` | `String` | 子分类名称 | -| `sortOrder` | `Integer` | 排序值 | - -**响应** `Result<CategoryVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `subCategoryId` | `String` | 子分类ID | -| `parentId` | `String` | 父子分类ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `materialCount` | `Integer` | 素材数量 | -| `children` | `List<CategoryVO>` | 子分类列表 | - -### 📌 `PUT` /admin/material/category/sub/{categoryId} — 更新子分类 - -> 更新子分类的名称或排序值。仅有该分类权限的管理员可操作。 - -**参数** - - - `{categoryId}` (`Long`) — 路径参数：子分类ID - -**请求体** `SubCategoryUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryName` | `String` | Subcategory name | -| `sortOrder` | `Integer` | Sort order | - -**响应** `Result<CategoryVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `subCategoryId` | `String` | 子分类ID | -| `parentId` | `String` | 父子分类ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `materialCount` | `Integer` | 素材数量 | -| `children` | `List<CategoryVO>` | 子分类列表 | - -### 📌 `DELETE` /admin/material/category/sub/{categoryId} — 删除子分类 - -> 删除子分类前需确保分类下无素材，否则删除失败 - -**参数** - - - `{categoryId}` (`Long`) — 路径参数：子分类ID - -**响应** `Result<Void>` - -### 📌 `POST` /admin/material/export — 批量导出素材 - -> 根据选中的素材ID列表，返回每个素材的下载链接信息（名称+OSS URL）。 - -### 🆕 新增: MaterialTag - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「素材标签管理」** - -### 📌 `GET` /admin/material/tags — 获取管理标签（标签管理用，分页） - -> 返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。支持按标签名称搜索。 - -**参数** - - - `page` (`int`) — 查询参数：页码（默认1） - - `pageSize` (`int`) — 查询参数：每页条数（默认20） - - `keyword` (`String`) — 查询参数：搜索关键词（按标签名称模糊搜索） - -**响应** `Result<PageResult<MaterialTagVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `String` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `managed` | `Boolean` | 是否系统管理标签 | -| `useCount` | `Integer` | 使用次数 | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/material/tags/all — 获取全部标签（选择器用，含自定义标签） - -> 返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。 - -**响应** `Result<List<MaterialTagVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `String` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `managed` | `Boolean` | 是否系统管理标签 | -| `useCount` | `Integer` | 使用次数 | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/material/tag — 创建管理标签 - -> 创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagName` | `String` | 标签名称 | - -**响应** `Result<MaterialTagVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `String` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `managed` | `Boolean` | 是否系统管理标签 | -| `useCount` | `Integer` | 使用次数 | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `POST` /admin/material/tag/adhoc — 解析自定义标签（按名称查找或创建） - -> 按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagName` | `String` | 标签名称 | - -**响应** `Result<MaterialTagVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `String` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `managed` | `Boolean` | 是否系统管理标签 | -| `useCount` | `Integer` | 使用次数 | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/material/tag/{tagId} — 编辑标签 - -> 更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**参数** - - - `{tagId}` (`Long`) — 路径参数：标签ID - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | - -**响应** `Result<MaterialTagVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tagId` | `String` | 标签ID | -| `tagName` | `String` | 标签名称 | -| `tagColor` | `String` | 标签颜色 | -| `managed` | `Boolean` | 是否系统管理标签 | -| `useCount` | `Integer` | 使用次数 | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/material/tag/{tagId} — 删除标签 - -> 删除标签并自动解除与所有素材的关联关系。 - -**权限**：需管理员登录。 - -**参数** - - - `{tagId}` (`Long`) — 路径参数：标签ID - -**响应** `Result<Void>` - -### 🆕 新增: MpMaterial - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「小程序-素材」** - -### 📌 `GET` /mp/material/miniprogram — 获取小程序分类下的全部素材 - -> 返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等） - -**响应** `Result<List<MaterialVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialId` | `String` | 素材ID | -| `fileId` | `String` | 文件ID | -| `categoryCode` | `String` | 分类编码 | -| `categoryName` | `String` | 分类名称 | -| `subCategoryId` | `String` | 子分类ID | -| `subCategoryName` | `String` | 子分类名称 | -| `categoryPath` | `String` | 完整分类路径（如：攻略管理 / 999 / 888） | -| `materialName` | `String` | 素材名称 | -| `description` | `String` | 素材描述 | -| `fileType` | `String` | 文件类型 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileName` | `String` | 文件名 | -| `ossUrl` | `String` | OSS地址 | -| `thumbnailUrl` | `String` | 缩略图地址 | -| `imageWidth` | `Integer` | 图片宽度 | -| `imageHeight` | `Integer` | 图片高度 | -| `refCount` | `Integer` | 引用次数 | -| `tags` | `List<MaterialTagVO>` | 标签列表 | -| `createdBy` | `String` | 创建人ID | -| `createdByName` | `String` | 创建人姓名 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 🆕 新增: AdminTransport - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「交通查询管理」** - -### 📌 `GET` /admin/transport/flight/by-flight-no — 按航班号查询航班动态 - -**参数** - - - `flightNo` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<FlightVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `flightNo` | `String` | 航班号 | -| `airline` | `String` | 航空公司名称 | -| `category` | `String` | 航班属性：国内/国际/地区 | -| `departAirportCode` | `String` | 出发机场三字码 | -| `arriveAirportCode` | `String` | 到达机场三字码 | -| `departAirport` | `String` | 出发机场名称 | -| `arriveAirport` | `String` | 到达机场名称 | -| `departCity` | `String` | 出发城市 | -| `arriveCity` | `String` | 到达城市 | -| `planDepartTime` | `String` | 计划起飞时间（yyyy-MM-dd HH:mm:ss） | -| `planArriveTime` | `String` | 计划到达时间（yyyy-MM-dd HH:mm:ss） | -| `actualDepartTime` | `String` | 实际起飞时间（yyyy-MM-dd HH:mm:ss） | -| `actualArriveTime` | `String` | 实际到达时间（yyyy-MM-dd HH:mm:ss） | -| `status` | `String` | 航班状态：计划/起飞/到达/延误/取消/返航/备降等 | -| `stopFlag` | `String` | 是否经停：0不经停，1经停1次，n经停n次 | -| `shareFlag` | `String` | 是否共享航班：0否，1是 | -| `shareFlightNo` | `String` | 共享航班号（实际承运航班号） | -| `departTerminal` | `String` | 出发航站楼 | -| `arriveTerminal` | `String` | 到达航站楼 | -| `boardGate` | `String` | 登机口 | -| `arriveExit` | `String` | 到达出口 | -| `departTimezone` | `String` | 出发时区偏移（秒） | -| `arriveTimezone` | `String` | 到达时区偏移（秒） | - -### 📌 `GET` /admin/transport/flight/by-airport — 按机场三字码查询航班动态 - -**参数** - - - `dep` (`String`) — 查询参数 - - `arr` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<FlightVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `flightNo` | `String` | 航班号 | -| `airline` | `String` | 航空公司名称 | -| `category` | `String` | 航班属性：国内/国际/地区 | -| `departAirportCode` | `String` | 出发机场三字码 | -| `arriveAirportCode` | `String` | 到达机场三字码 | -| `departAirport` | `String` | 出发机场名称 | -| `arriveAirport` | `String` | 到达机场名称 | -| `departCity` | `String` | 出发城市 | -| `arriveCity` | `String` | 到达城市 | -| `planDepartTime` | `String` | 计划起飞时间（yyyy-MM-dd HH:mm:ss） | -| `planArriveTime` | `String` | 计划到达时间（yyyy-MM-dd HH:mm:ss） | -| `actualDepartTime` | `String` | 实际起飞时间（yyyy-MM-dd HH:mm:ss） | -| `actualArriveTime` | `String` | 实际到达时间（yyyy-MM-dd HH:mm:ss） | -| `status` | `String` | 航班状态：计划/起飞/到达/延误/取消/返航/备降等 | -| `stopFlag` | `String` | 是否经停：0不经停，1经停1次，n经停n次 | -| `shareFlag` | `String` | 是否共享航班：0否，1是 | -| `shareFlightNo` | `String` | 共享航班号（实际承运航班号） | -| `departTerminal` | `String` | 出发航站楼 | -| `arriveTerminal` | `String` | 到达航站楼 | -| `boardGate` | `String` | 登机口 | -| `arriveExit` | `String` | 到达出口 | -| `departTimezone` | `String` | 出发时区偏移（秒） | -| `arriveTimezone` | `String` | 到达时区偏移（秒） | - -### 📌 `GET` /admin/transport/flight/by-city — 按城市三字码查询航班动态 - -**参数** - - - `depCity` (`String`) — 查询参数 - - `arrCity` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<FlightVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `flightNo` | `String` | 航班号 | -| `airline` | `String` | 航空公司名称 | -| `category` | `String` | 航班属性：国内/国际/地区 | -| `departAirportCode` | `String` | 出发机场三字码 | -| `arriveAirportCode` | `String` | 到达机场三字码 | -| `departAirport` | `String` | 出发机场名称 | -| `arriveAirport` | `String` | 到达机场名称 | -| `departCity` | `String` | 出发城市 | -| `arriveCity` | `String` | 到达城市 | -| `planDepartTime` | `String` | 计划起飞时间（yyyy-MM-dd HH:mm:ss） | -| `planArriveTime` | `String` | 计划到达时间（yyyy-MM-dd HH:mm:ss） | -| `actualDepartTime` | `String` | 实际起飞时间（yyyy-MM-dd HH:mm:ss） | -| `actualArriveTime` | `String` | 实际到达时间（yyyy-MM-dd HH:mm:ss） | -| `status` | `String` | 航班状态：计划/起飞/到达/延误/取消/返航/备降等 | -| `stopFlag` | `String` | 是否经停：0不经停，1经停1次，n经停n次 | -| `shareFlag` | `String` | 是否共享航班：0否，1是 | -| `shareFlightNo` | `String` | 共享航班号（实际承运航班号） | -| `departTerminal` | `String` | 出发航站楼 | -| `arriveTerminal` | `String` | 到达航站楼 | -| `boardGate` | `String` | 登机口 | -| `arriveExit` | `String` | 到达出口 | -| `departTimezone` | `String` | 出发时区偏移（秒） | -| `arriveTimezone` | `String` | 到达时区偏移（秒） | - -### 📌 `GET` /admin/transport/train/by-train-no-stations — 按车次+出发站+到达站查询火车动态 - -**参数** - - - `trainNo` (`String`) — 查询参数 - - `dep` (`String`) — 查询参数 - - `arr` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<TrainVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `trainNo` | `String` | 车次 | -| `departStation` | `String` | 出发车站 | -| `arriveStation` | `String` | 到达车站 | -| `shutdown` | `String` | 是否停运：0否，1是 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `estimatedDepartTime` | `String` | 预计出发时间 | -| `estimatedArriveTime` | `String` | 预计到达时间 | -| `actualDepartTime` | `String` | 实际出发时间 | -| `actualArriveTime` | `String` | 实际到达时间 | -| `departStatus` | `String` | 出发状态：计划/正点/晚点/出发 | -| `arriveStatus` | `String` | 到达状态：计划/正点/晚点/到达 | -| `duration` | `Integer` | 运行时长（分钟） | -| `stops` | `List<TrainStopVO>` | 经停站列表 | - -### 📌 `GET` /admin/transport/train/by-train-no — 按车次查询火车动态（含全部经停站） - -**参数** - - - `trainNo` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<TrainVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `trainNo` | `String` | 车次 | -| `departStation` | `String` | 出发车站 | -| `arriveStation` | `String` | 到达车站 | -| `shutdown` | `String` | 是否停运：0否，1是 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `estimatedDepartTime` | `String` | 预计出发时间 | -| `estimatedArriveTime` | `String` | 预计到达时间 | -| `actualDepartTime` | `String` | 实际出发时间 | -| `actualArriveTime` | `String` | 实际到达时间 | -| `departStatus` | `String` | 出发状态：计划/正点/晚点/出发 | -| `arriveStatus` | `String` | 到达状态：计划/正点/晚点/到达 | -| `duration` | `Integer` | 运行时长（分钟） | -| `stops` | `List<TrainStopVO>` | 经停站列表 | - -### 📌 `GET` /admin/transport/train/by-station — 按出发站+到达站查询火车车次 - -**参数** - - - `dep` (`String`) — 查询参数 - - `arr` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<TrainVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `trainNo` | `String` | 车次 | -| `departStation` | `String` | 出发车站 | -| `arriveStation` | `String` | 到达车站 | -| `shutdown` | `String` | 是否停运：0否，1是 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `estimatedDepartTime` | `String` | 预计出发时间 | -| `estimatedArriveTime` | `String` | 预计到达时间 | -| `actualDepartTime` | `String` | 实际出发时间 | -| `actualArriveTime` | `String` | 实际到达时间 | -| `departStatus` | `String` | 出发状态：计划/正点/晚点/出发 | -| `arriveStatus` | `String` | 到达状态：计划/正点/晚点/到达 | -| `duration` | `Integer` | 运行时长（分钟） | -| `stops` | `List<TrainStopVO>` | 经停站列表 | - -### 📌 `GET` /admin/transport/train/by-city — 按出发城市+到达城市查询火车车次 - -**参数** - - - `depCity` (`String`) — 查询参数 - - `arrCity` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<TrainVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `trainNo` | `String` | 车次 | -| `departStation` | `String` | 出发车站 | -| `arriveStation` | `String` | 到达车站 | -| `shutdown` | `String` | 是否停运：0否，1是 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `estimatedDepartTime` | `String` | 预计出发时间 | -| `estimatedArriveTime` | `String` | 预计到达时间 | -| `actualDepartTime` | `String` | 实际出发时间 | -| `actualArriveTime` | `String` | 实际到达时间 | -| `departStatus` | `String` | 出发状态：计划/正点/晚点/出发 | -| `arriveStatus` | `String` | 到达状态：计划/正点/晚点/到达 | -| `duration` | `Integer` | 运行时长（分钟） | -| `stops` | `List<TrainStopVO>` | 经停站列表 | - -### 🆕 新增: InternalTransport - -> 📖 **接口文档**: [http://192.168.100.236:8082/doc.html](http://192.168.100.236:8082/doc.html) → 标签 **「【内部接口】交通查询（Feign调用）」** - -### 📌 `GET` /internal/transport/flight — 按航班号查询航班动态 - -**参数** - - - `flightNo` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<FlightVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `flightNo` | `String` | 航班号 | -| `airline` | `String` | 航空公司名称 | -| `category` | `String` | 航班属性：国内/国际/地区 | -| `departAirportCode` | `String` | 出发机场三字码 | -| `arriveAirportCode` | `String` | 到达机场三字码 | -| `departAirport` | `String` | 出发机场名称 | -| `arriveAirport` | `String` | 到达机场名称 | -| `departCity` | `String` | 出发城市 | -| `arriveCity` | `String` | 到达城市 | -| `planDepartTime` | `String` | 计划起飞时间（yyyy-MM-dd HH:mm:ss） | -| `planArriveTime` | `String` | 计划到达时间（yyyy-MM-dd HH:mm:ss） | -| `actualDepartTime` | `String` | 实际起飞时间（yyyy-MM-dd HH:mm:ss） | -| `actualArriveTime` | `String` | 实际到达时间（yyyy-MM-dd HH:mm:ss） | -| `status` | `String` | 航班状态：计划/起飞/到达/延误/取消/返航/备降等 | -| `stopFlag` | `String` | 是否经停：0不经停，1经停1次，n经停n次 | -| `shareFlag` | `String` | 是否共享航班：0否，1是 | -| `shareFlightNo` | `String` | 共享航班号（实际承运航班号） | -| `departTerminal` | `String` | 出发航站楼 | -| `arriveTerminal` | `String` | 到达航站楼 | -| `boardGate` | `String` | 登机口 | -| `arriveExit` | `String` | 到达出口 | -| `departTimezone` | `String` | 出发时区偏移（秒） | -| `arriveTimezone` | `String` | 到达时区偏移（秒） | - -### 📌 `GET` /internal/transport/train — 按车次查询火车动态 - -**参数** - - - `trainNo` (`String`) — 查询参数 - - `date` (`String`) — 查询参数 - -**响应** `Result<List<TrainVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `trainNo` | `String` | 车次 | -| `departStation` | `String` | 出发车站 | -| `arriveStation` | `String` | 到达车站 | -| `shutdown` | `String` | 是否停运：0否，1是 | -| `planDepartTime` | `String` | 计划出发时间 | -| `planArriveTime` | `String` | 计划到达时间 | -| `estimatedDepartTime` | `String` | 预计出发时间 | -| `estimatedArriveTime` | `String` | 预计到达时间 | -| `actualDepartTime` | `String` | 实际出发时间 | -| `actualArriveTime` | `String` | 实际到达时间 | -| `departStatus` | `String` | 出发状态：计划/正点/晚点/出发 | -| `arriveStatus` | `String` | 到达状态：计划/正点/晚点/到达 | -| `duration` | `Integer` | 运行时长（分钟） | -| `stops` | `List<TrainStopVO>` | 经停站列表 | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 用户服务 - -#### 🆕 AssigneeVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adminId` | `Long` | 管理员ID | -| `username` | `String` | 用户名 | -| `avatarUrl` | `String` | 头像地址 | -| `wechatName` | `String` | 企微昵称 | - -#### 🆕 ChatMessageVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `msgId` | `String` | 消息ID | -| `fromUser` | `String` | 发送人ID | -| `fromUserName` | `String` | 发送人姓名 | -| `fromUserAvatar` | `String` | 发送人头像 | -| `roomId` | `String` | 群聊ID | -| `msgTime` | `Long` | 消息时间戳 | -| `msgType` | `String` | 消息类型 | -| `content` | `String` | 消息内容 | - -#### 🆕 FileQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileType` | `String` | 文件类型 | -| `groupKey` | `String` | 业务分组 | -| `keyword` | `String` | 搜索关键词 | -| `startDate` | `String` | 开始日期 | -| `endDate` | `String` | 结束日期 | - -#### 🆕 MpReviewQueryRequest - -#### 🆕 ReviewQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `reviewType` | `String` | 评论类型（字典 review_type） | -| `productType` | `String` | 产品类型（字典 review_product_type） | -| `targetType` | `String` | 评价目标类型 | -| `targetId` | `Long` | 评价目标ID | -| `status` | `String` | 评价状态 | -| `ratingLevel` | `String` | 评价等级: GOOD/MEDIUM/BAD | -| `hasImage` | `Boolean` | 是否有图片: true/false | -| `hasVideo` | `Boolean` | 是否有视频: true/false | -| `keyword` | `String` | 搜索关键词 | -| `minRating` | `Integer` | 最低评分(整体满意度) | -| `maxRating` | `Integer` | 最高评分(整体满意度) | - -#### 🆕 ReviewableTargetVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `targetType` | `String` | 评价目标类型 | -| `targetTypeLabel` | `String` | 评价目标类型标签 | -| `targetId` | `String` | 评价目标ID | -| `targetName` | `String` | 评价目标名称 | -| `reviewed` | `boolean` | 是否已评价 | - -#### 🆕 TargetReviewQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `targetType` | `String` | 目标类型 | -| `targetId` | `Long` | 目标ID | -| `ratingLevel` | `String` | 评价等级筛选: GOOD/MEDIUM/BAD | -| `hasImage` | `Boolean` | 是否有图片 | -| `hasVideo` | `Boolean` | 是否有视频 | - -#### 🆕 WechatGroupVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | ID | -| `roomId` | `String` | 企微群聊ID | -| `groupName` | `String` | 群名称 | -| `ownerUserId` | `String` | 群主企微userId | -| `ownerName` | `String` | 群主姓名 | -| `memberCount` | `Integer` | 群成员数 | -| `remark` | `String` | 备注 | -| `recentMessageCount` | `Integer` | 最近消息数 | -| `lastSyncTime` | `LocalDateTime` | 最后同步时间 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -### 订单服务 - -#### 🆕 ContractQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `status` | `String` | 合同状态 | -| `platform` | `String` | 签约平台 | - -#### 🆕 InsuranceQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 关联旅行订单ID | -| `status` | `String` | 订单状态: PENDING-待出单, INSURED-已承保, CANCELLED-已退保, FAILED-投保失败 | - -#### 🆕 PaymentQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderNo` | `String` | 订单编号 | -| `mchId` | `String` | 商户号 | -| `status` | `String` | 支付状态 | -| `tradeType` | `String` | 交易类型: JSAPI/H5 | -| `startDate` | `String` | 开始日期 | -| `endDate` | `String` | 结束日期 | - -#### 🆕 SelectivePurchaseRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `schemeId` | `Long` | 保险方案ID | -| `travelerIds` | `List<Long>` | 要投保的出行人ID列表 | - -#### 🆕 TravelerCoverageVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `travelerId` | `String` | 出行人ID | -| `name` | `String` | 姓名 | -| `birthday` | `LocalDate` | 出生日期 | -| `age` | `Integer` | 年龄 | -| `travelerType` | `String` | 出行人类型：ADULT/CHILD | -| `coverageStatus` | `String` | 保险覆盖状态：ONLINE_INSURED=在线已投保, OFFLINE_NOTED=线下已备注, NOT_COVERED=未投保 | -| `policies` | `List<Map<String, Object>>` | 在线保单列表（coverageStatus=ONLINE_INSURED时有值） | -| `noteId` | `String` | 线下备注ID（coverageStatus=OFFLINE_NOTED时有值） | -| `noteType` | `String` | 线下备注类型 | -| `noteRemark` | `String` | 线下备注说明（coverageStatus=OFFLINE_NOTED时有值） | - -#### 🆕 TravelerNoteRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `travelerId` | `Long` | 出行人ID | -| `travelerName` | `String` | 出行人姓名 | -| `noteType` | `String` | 备注类型：OFFLINE=线下投保, SKIP=跳过, OTHER=其他 | -| `remark` | `String` | 备注说明 | - -### 资源服务 - -#### 🆕 ArticleQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `keyword` | `String` | 关键词（搜索标题/摘要） | -| `categoryId` | `Long` | 分类ID | -| `status` | `Integer` | 状态：0=草稿，1=已发布，2=已下架 | -| `isRecommend` | `Integer` | 是否推荐：0=否，1=是 | -| `isTop` | `Integer` | 是否置顶：0=否，1=是 | -| `orderBy` | `String` | 排序字段：sortOrder/publishTime/viewCount/createdAt（默认createdAt） | -| `orderDir` | `String` | 排序方向：asc/desc（默认desc） | - -#### 🆕 FileBatchIdsRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileIds` | `List<Long>` | 文件ID列表 | - -#### 🆕 FileUploadConfirmRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | - -#### 🆕 FileUploadTokenRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileName` | `String` | 文件名 | -| `fileSize` | `Long` | 文件大小(字节) | -| `fileHash` | `String` | 文件哈希值 | -| `groupKey` | `String` | 分组标识 | -| `forcePresigned` | `boolean` | 是否强制使用预签名URL | - -#### 🆕 FileUploadTokenVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `fileId` | `String` | 文件ID | -| `contentType` | `String` | 文件MIME类型 | -| `uploadMode` | `String` | 上传模式 | -| `presignedUrl` | `String` | 预签名上传URL | -| `ossKey` | `String` | OSS对象Key | -| `expireAt` | `LocalDateTime` | 过期时间 | -| `stsToken` | `StsTokenInfo` | STS临时凭证 | -| `bucket` | `String` | OSS存储桶名称 | -| `region` | `String` | OSS区域 | -| `file` | `FileVO` | 文件信息(秒传时返回) | -| `accessKeyId` | `String` | 访问密钥ID | -| `accessKeySecret` | `String` | 访问密钥Secret | -| `securityToken` | `String` | 安全令牌 | -| `expiration` | `String` | 过期时间 | - -#### 🆕 GuideArticleResourceVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `resourceType` | `String` | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -| `resourceId` | `Long` | 资源ID | -| `resourceName` | `String` | 资源名称 | -| `sortOrder` | `Integer` | 排序 | - -#### 🆕 MaterialQueryRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `categoryCode` | `String` | 分类编码 | -| `subCategoryId` | `Long` | 子分类ID | -| `fileType` | `String` | 文件类型 | -| `tagIds` | `String` | 标签ID列表(逗号分隔) | -| `keyword` | `String` | 搜索关键词 | -| `createdBy` | `Long` | 创建人ID | -| `startDate` | `String` | 开始日期 | -| `endDate` | `String` | 结束日期 | - -#### 🆕 MaterialReviewRequest - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `materialIds` | `List<String>` | 素材ID列表 | - -#### 🆕 TrainStopVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `stationName` | `String` | 车站名称 | -| `arriveTime` | `String` | 到站时间 | -| `departTime` | `String` | 发车时间 | - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A copyright-materials/design_document.pdf -A copyright-materials/source_code.pdf -A docs.zip -A fadada-home.md -A fix_12301_url.py -A fix_agency.py -A fix_stage.py -M hl-order-service/pom.xml -A hl-order-service/src/main/java/com/hulalv/contract/config/ContractPlatformProperties.java -A hl-order-service/src/main/java/com/hulalv/contract/config/MyBatisPlusConfig.java -A hl-order-service/src/main/java/com/hulalv/contract/config/RestTemplateConfig.java -A hl-order-service/src/main/java/com/hulalv/contract/config/WebMvcConfig.java -A hl-order-service/src/main/java/com/hulalv/contract/constant/ContractConstants.java -A hl-order-service/src/main/java/com/hulalv/contract/controller/AdminClauseTemplateController.java -A hl-order-service/src/main/java/com/hulalv/contract/controller/AdminContractController.java -A hl-order-service/src/main/java/com/hulalv/contract/controller/AdminContractSchemeController.java -A hl-order-service/src/main/java/com/hulalv/contract/controller/ContractCallbackController.java -A hl-order-service/src/main/java/com/hulalv/contract/controller/InternalContractController.java -A hl-order-service/src/main/java/com/hulalv/contract/controller/InternalMpContractController.java -A hl-order-service/src/main/java/com/hulalv/contract/dto/ClauseTemplateRequest.java -A hl-order-service/src/main/java/com/hulalv/contract/dto/ContractCallbackPayload.java -A hl-order-service/src/main/java/com/hulalv/contract/dto/ContractQueryRequest.java -A hl-order-service/src/main/java/com/hulalv/contract/dto/ContractSchemeRequest.java -A hl-order-service/src/main/java/com/hulalv/contract/dto/CreateContractRequest.java -A hl-order-service/src/main/java/com/hulalv/contract/dto/ReportContractRequest.java -A hl-order-service/src/main/java/com/hulalv/contract/entity/Contract.java -A hl-order-service/src/main/java/com/hulalv/contract/entity/ContractClauseTemplate.java -A hl-order-service/src/main/java/com/hulalv/contract/entity/ContractScheme.java -A hl-order-service/src/main/java/com/hulalv/contract/entity/ContractStatusLog.java -A hl-order-service/src/main/java/com/hulalv/contract/entity/ContractTemplate.java -A hl-order-service/src/main/java/com/hulalv/contract/entity/ContractTraveler.java -A hl-order-service/src/main/java/com/hulalv/contract/feign/OrderContractFeignClient.java -A hl-order-service/src/main/java/com/hulalv/contract/interceptor/AdminAuthInterceptor.java -A hl-order-service/src/main/java/com/hulalv/contract/job/ContractStatusRefreshJob.java -A hl-order-service/src/main/java/com/hulalv/contract/mapper/ContractClauseTemplateMapper.java -A hl-order-service/src/main/java/com/hulalv/contract/mapper/ContractMapper.java -A hl-order-service/src/main/java/com/hulalv/contract/mapper/ContractSchemeMapper.java -A hl-order-service/src/main/java/com/hulalv/contract/mapper/ContractStatusLogMapper.java -A hl-order-service/src/main/java/com/hulalv/contract/mapper/ContractTemplateMapper.java -A hl-order-service/src/main/java/com/hulalv/contract/mapper/ContractTravelerMapper.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractApplyParam.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractApplyResult.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractPlatform.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractPlatformFactory.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractPlatformInfo.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractPlatformStatus.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractReportParam.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/ContractReportResult.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaApiClient.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaContractPlatform.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/fadada/FadadaSignatureUtil.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/tourage/TourageApiClient.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/tourage/TourageContractPlatform.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/tourage/TourageRequestBuilder.java -A hl-order-service/src/main/java/com/hulalv/contract/platform/tourage/TourageSignatureUtil.java -A hl-order-service/src/main/java/com/hulalv/contract/service/ClauseTemplateService.java -A hl-order-service/src/main/java/com/hulalv/contract/service/ContractCallbackService.java -A hl-order-service/src/main/java/com/hulalv/contract/service/ContractSchemeService.java -A hl-order-service/src/main/java/com/hulalv/contract/service/ContractService.java -A hl-order-service/src/main/java/com/hulalv/contract/service/SafetyNoticeService.java -A hl-order-service/src/main/java/com/hulalv/contract/vo/ClauseTemplateVO.java -A hl-order-service/src/main/java/com/hulalv/contract/vo/ContractDetailVO.java -A hl-order-service/src/main/java/com/hulalv/contract/vo/ContractSchemeVO.java -A hl-order-service/src/main/java/com/hulalv/contract/vo/ContractTemplateVO.java -A hl-order-service/src/main/java/com/hulalv/contract/vo/ContractVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/config/BaoyouApiProperties.java -A hl-order-service/src/main/java/com/hulalv/insurance/config/InsuranceEntityProperties.java -A hl-order-service/src/main/java/com/hulalv/insurance/config/MyBatisPlusConfig.java -A hl-order-service/src/main/java/com/hulalv/insurance/config/RestTemplateConfig.java -A hl-order-service/src/main/java/com/hulalv/insurance/config/WebMvcConfig.java -A hl-order-service/src/main/java/com/hulalv/insurance/constant/InsuranceConstants.java -A hl-order-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceController.java -A hl-order-service/src/main/java/com/hulalv/insurance/controller/AdminInsuranceSchemeController.java -A hl-order-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/ApplySchemeRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/AutoPurchaseRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/InsuranceQueryRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/InsuranceSchemeRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/PurchaseInsuranceRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/RechargeRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/SelectivePurchaseRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/SharePolicyRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/TravelerNoteRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/dto/TrialPriceRequest.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuranceOrder.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsurancePlan.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuranceProduct.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuranceRate.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuranceScheme.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuranceSchemeSegment.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuranceTravelerNote.java -A hl-order-service/src/main/java/com/hulalv/insurance/entity/InsuredPerson.java -A hl-order-service/src/main/java/com/hulalv/insurance/feign/OrderInsuranceFeignClient.java -A hl-order-service/src/main/java/com/hulalv/insurance/interceptor/AdminAuthInterceptor.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuranceOrderMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsurancePlanMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuranceProductMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuranceRateMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuranceSchemeMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuranceSchemeSegmentMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuranceTravelerNoteMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/mapper/InsuredPersonMapper.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/BaoyouApiClient.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceProductSyncService.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceSchemeService.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceSyncScheduler.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/PolicyPdfUploadService.java -A hl-order-service/src/main/java/com/hulalv/insurance/service/PolicyShareService.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/ApplySchemePreviewVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/AutoPurchaseResultVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/InsuranceCoverageVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/InsuranceOrderDetailVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/InsuranceOrderVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/InsurancePlanVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/InsuranceProductVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/InsuranceSchemeVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/PolicyShareVO.java -A hl-order-service/src/main/java/com/hulalv/insurance/vo/TravelerCoverageVO.java -M hl-order-service/src/main/java/com/hulalv/order/OrderServiceApplication.java -A hl-order-service/src/main/java/com/hulalv/payment/config/MyBatisPlusConfig.java -A hl-order-service/src/main/java/com/hulalv/payment/config/WebMvcConfig.java -A hl-order-service/src/main/java/com/hulalv/payment/config/WxPayConfig.java -A hl-order-service/src/main/java/com/hulalv/payment/config/WxPayProperties.java -A hl-order-service/src/main/java/com/hulalv/payment/constant/PaymentConstants.java -A hl-order-service/src/main/java/com/hulalv/payment/controller/AdminPaymentController.java -A hl-order-service/src/main/java/com/hulalv/payment/controller/InternalPaymentController.java -A hl-order-service/src/main/java/com/hulalv/payment/controller/PaymentCallbackController.java -A hl-order-service/src/main/java/com/hulalv/payment/dto/PaymentQueryRequest.java -A hl-order-service/src/main/java/com/hulalv/payment/dto/PrepayRequest.java -A hl-order-service/src/main/java/com/hulalv/payment/dto/PrepayResponse.java -A hl-order-service/src/main/java/com/hulalv/payment/dto/RefundRequest.java -A hl-order-service/src/main/java/com/hulalv/payment/entity/PaymentTransaction.java -A hl-order-service/src/main/java/com/hulalv/payment/entity/RefundRecord.java -A hl-order-service/src/main/java/com/hulalv/payment/feign/OrderPaymentFeignClient.java -A hl-order-service/src/main/java/com/hulalv/payment/feign/OrderPaymentFeignFallbackFactory.java -A hl-order-service/src/main/java/com/hulalv/payment/feign/UserPaymentFeignClient.java -A hl-order-service/src/main/java/com/hulalv/payment/feign/UserPaymentFeignFallbackFactory.java -A hl-order-service/src/main/java/com/hulalv/payment/interceptor/AdminAuthInterceptor.java -A hl-order-service/src/main/java/com/hulalv/payment/mapper/PaymentTransactionMapper.java -A hl-order-service/src/main/java/com/hulalv/payment/mapper/RefundRecordMapper.java -A hl-order-service/src/main/java/com/hulalv/payment/mq/producer/PaymentResultProducer.java -A hl-order-service/src/main/java/com/hulalv/payment/service/PaymentService.java -A hl-order-service/src/main/java/com/hulalv/payment/service/RefundService.java -A hl-order-service/src/main/java/com/hulalv/payment/vo/MerchantVO.java -A hl-order-service/src/main/java/com/hulalv/payment/vo/PaymentVO.java -A hl-order-service/src/main/java/com/hulalv/payment/vo/RefundVO.java -A hl-order-service/src/test/java/com/hulalv/contract/EntityDtoCoverageTest.java -A hl-order-service/src/test/java/com/hulalv/contract/constant/ContractConstantsTest.java -A hl-order-service/src/test/java/com/hulalv/contract/controller/AdminClauseTemplateControllerTest.java -A hl-order-service/src/test/java/com/hulalv/contract/controller/AdminContractControllerTest.java -A hl-order-service/src/test/java/com/hulalv/contract/controller/AdminContractSchemeControllerTest.java -A hl-order-service/src/test/java/com/hulalv/contract/controller/ContractCallbackControllerTest.java -A hl-order-service/src/test/java/com/hulalv/contract/controller/InternalContractControllerTest.java -A hl-order-service/src/test/java/com/hulalv/contract/controller/InternalMpContractControllerTest.java -A hl-order-service/src/test/java/com/hulalv/contract/interceptor/AdminAuthInterceptorTest.java -A hl-order-service/src/test/java/com/hulalv/contract/job/ContractStatusRefreshJobTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/ContractPlatformFactoryTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaApiClientTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaContractPlatformTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/fadada/FadadaSignatureUtilTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/tourage/TourageContractPlatformTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/tourage/TourageRequestBuilderTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/tourage/TourageSignatureUtilTest.java -A hl-order-service/src/test/java/com/hulalv/contract/service/ClauseTemplateServiceTest.java -A hl-order-service/src/test/java/com/hulalv/contract/service/ContractCallbackServiceTest.java -A hl-order-service/src/test/java/com/hulalv/contract/service/ContractSchemeServiceTest.java -A hl-order-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -A hl-order-service/src/test/java/com/hulalv/contract/service/SafetyNoticeServiceTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/constant/InsuranceConstantsTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/service/BaoyouApiClientTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/service/InsuranceOrderServiceTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/service/InsuranceProductSyncServiceTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/service/InsuranceSchemeServiceTest.java -A hl-order-service/src/test/java/com/hulalv/payment/EntityDtoCoverageTest.java -A hl-order-service/src/test/java/com/hulalv/payment/config/WxPayConfigTest.java -A hl-order-service/src/test/java/com/hulalv/payment/constant/PaymentConstantsTest.java -A hl-order-service/src/test/java/com/hulalv/payment/controller/AdminPaymentControllerTest.java -A hl-order-service/src/test/java/com/hulalv/payment/controller/InternalPaymentControllerTest.java -A hl-order-service/src/test/java/com/hulalv/payment/controller/PaymentCallbackControllerTest.java -A hl-order-service/src/test/java/com/hulalv/payment/interceptor/AdminAuthInterceptorTest.java -A hl-order-service/src/test/java/com/hulalv/payment/mq/producer/PaymentResultProducerTest.java -A hl-order-service/src/test/java/com/hulalv/payment/service/PaymentServiceTest.java -A hl-order-service/src/test/java/com/hulalv/payment/service/RefundServiceTest.java -A hl-resource-service/src/main/java/com/hulalv/guide/config/MyBatisPlusConfig.java -A hl-resource-service/src/main/java/com/hulalv/guide/config/WebMvcConfig.java -A hl-resource-service/src/main/java/com/hulalv/guide/constant/GuideConstants.java -A hl-resource-service/src/main/java/com/hulalv/guide/controller/AdminGuideArticleController.java -A hl-resource-service/src/main/java/com/hulalv/guide/controller/AdminGuideCategoryController.java -A hl-resource-service/src/main/java/com/hulalv/guide/controller/AdminGuideTagController.java -A hl-resource-service/src/main/java/com/hulalv/guide/controller/InternalWikiController.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/ArticleCreateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/ArticleQueryRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/ArticleTagUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/ArticleUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/CategoryCreateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/CategorySortRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/CategoryUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/RecommendRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/StatusRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/TagCreateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/TagUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/dto/TopRequest.java -A hl-resource-service/src/main/java/com/hulalv/guide/entity/GuideArticle.java -A hl-resource-service/src/main/java/com/hulalv/guide/entity/GuideArticleResource.java -A hl-resource-service/src/main/java/com/hulalv/guide/entity/GuideCategory.java -A hl-resource-service/src/main/java/com/hulalv/guide/entity/GuideTag.java -A hl-resource-service/src/main/java/com/hulalv/guide/entity/GuideTagRel.java -A hl-resource-service/src/main/java/com/hulalv/guide/interceptor/AdminAuthInterceptor.java -A hl-resource-service/src/main/java/com/hulalv/guide/mapper/GuideArticleMapper.java -A hl-resource-service/src/main/java/com/hulalv/guide/mapper/GuideArticleResourceMapper.java -A hl-resource-service/src/main/java/com/hulalv/guide/mapper/GuideCategoryMapper.java -A hl-resource-service/src/main/java/com/hulalv/guide/mapper/GuideTagMapper.java -A hl-resource-service/src/main/java/com/hulalv/guide/mapper/GuideTagRelMapper.java -A hl-resource-service/src/main/java/com/hulalv/guide/service/GuideArticleService.java -A hl-resource-service/src/main/java/com/hulalv/guide/service/GuideCategoryService.java -A hl-resource-service/src/main/java/com/hulalv/guide/service/GuideTagService.java -A hl-resource-service/src/main/java/com/hulalv/guide/vo/GuideArticleListVO.java -A hl-resource-service/src/main/java/com/hulalv/guide/vo/GuideArticleResourceVO.java -A hl-resource-service/src/main/java/com/hulalv/guide/vo/GuideArticleVO.java -A hl-resource-service/src/main/java/com/hulalv/guide/vo/GuideCategoryVO.java -A hl-resource-service/src/main/java/com/hulalv/guide/vo/GuideTagVO.java -A hl-resource-service/src/main/java/com/hulalv/material/config/MyBatisPlusConfig.java -A hl-resource-service/src/main/java/com/hulalv/material/config/WebMvcConfig.java -A hl-resource-service/src/main/java/com/hulalv/material/constant/MaterialConstants.java -A hl-resource-service/src/main/java/com/hulalv/material/controller/DictCacheService.java -A hl-resource-service/src/main/java/com/hulalv/material/controller/InternalMaterialController.java -A hl-resource-service/src/main/java/com/hulalv/material/controller/MaterialCategoryPermissionController.java -A hl-resource-service/src/main/java/com/hulalv/material/controller/MaterialController.java -A hl-resource-service/src/main/java/com/hulalv/material/controller/MaterialTagController.java -A hl-resource-service/src/main/java/com/hulalv/material/controller/MpMaterialController.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/BatchDeleteRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/BatchMaterialIdsRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/BatchTagRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/CategoryPermissionUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/ChunkUploadCancelRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/ChunkUploadCompleteRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/ChunkUploadInitRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/FolderUploadInitRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/MaterialQueryRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/MaterialReviewRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/MaterialTagUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/MaterialUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/MaterialUploadConfirmRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/MaterialUploadTokenRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/RefBatchBindRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/RefBatchUnbindRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/RefBindRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/RefUnbindRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/SubCategoryCreateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/SubCategoryUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/TagCreateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/dto/TagUpdateRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/entity/Material.java -A hl-resource-service/src/main/java/com/hulalv/material/entity/MaterialCategory.java -A hl-resource-service/src/main/java/com/hulalv/material/entity/MaterialCategoryPermission.java -A hl-resource-service/src/main/java/com/hulalv/material/entity/MaterialRef.java -A hl-resource-service/src/main/java/com/hulalv/material/entity/MaterialTag.java -A hl-resource-service/src/main/java/com/hulalv/material/entity/MaterialTagRel.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/FileServiceClient.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/FileServiceFallbackFactory.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCancelRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadCompleteRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/dto/ChunkUploadInitRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/dto/FileBatchIdsRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/dto/FileUploadConfirmRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/dto/FileUploadTokenRequest.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadInitVO.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/vo/ChunkUploadPartVO.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/vo/FileUploadTokenVO.java -A hl-resource-service/src/main/java/com/hulalv/material/feign/vo/FileVO.java -A hl-resource-service/src/main/java/com/hulalv/material/interceptor/AdminAuthInterceptor.java -A hl-resource-service/src/main/java/com/hulalv/material/mapper/MaterialCategoryMapper.java -A hl-resource-service/src/main/java/com/hulalv/material/mapper/MaterialCategoryPermissionMapper.java -A hl-resource-service/src/main/java/com/hulalv/material/mapper/MaterialMapper.java -A hl-resource-service/src/main/java/com/hulalv/material/mapper/MaterialRefMapper.java -A hl-resource-service/src/main/java/com/hulalv/material/mapper/MaterialTagMapper.java -A hl-resource-service/src/main/java/com/hulalv/material/mapper/MaterialTagRelMapper.java -A hl-resource-service/src/main/java/com/hulalv/material/service/ChunkUploadService.java -A hl-resource-service/src/main/java/com/hulalv/material/service/MaterialCategoryPermissionService.java -A hl-resource-service/src/main/java/com/hulalv/material/service/MaterialCategoryService.java -A hl-resource-service/src/main/java/com/hulalv/material/service/MaterialRefService.java -A hl-resource-service/src/main/java/com/hulalv/material/service/MaterialService.java -A hl-resource-service/src/main/java/com/hulalv/material/service/MaterialTagService.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/BatchDeleteResultVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/CategoryVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/ChunkUploadInitVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/ChunkUploadPartVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/FolderUploadInitVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/MaterialRefVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/MaterialTagVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/MaterialUploadTokenVO.java -A hl-resource-service/src/main/java/com/hulalv/material/vo/MaterialVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/ResourceServiceApplication.java -A hl-resource-service/src/main/java/com/hulalv/transport/config/RestTemplateConfig.java -A hl-resource-service/src/main/java/com/hulalv/transport/config/VariFlightProperties.java -A hl-resource-service/src/main/java/com/hulalv/transport/config/WebMvcConfig.java -A hl-resource-service/src/main/java/com/hulalv/transport/constant/TransportConstants.java -A hl-resource-service/src/main/java/com/hulalv/transport/controller/AdminTransportController.java -A hl-resource-service/src/main/java/com/hulalv/transport/controller/InternalTransportController.java -A hl-resource-service/src/main/java/com/hulalv/transport/interceptor/AdminAuthInterceptor.java -A hl-resource-service/src/main/java/com/hulalv/transport/service/FlightService.java -A hl-resource-service/src/main/java/com/hulalv/transport/service/TrainService.java -A hl-resource-service/src/main/java/com/hulalv/transport/service/VariFlightApiClient.java -A hl-resource-service/src/main/java/com/hulalv/transport/vo/FlightVO.java -A hl-resource-service/src/main/java/com/hulalv/transport/vo/TrainStopVO.java -A hl-resource-service/src/main/java/com/hulalv/transport/vo/TrainVO.java -A hl-resource-service/src/test/java/com/hulalv/guide/EntityDtoCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/controller/AdminGuideArticleControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/controller/AdminGuideCategoryControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/controller/AdminGuideTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/controller/InternalWikiControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/service/GuideArticleServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/service/GuideCategoryServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/service/GuideTagServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/EntityDtoCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/material/VoFeignCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/material/controller/DictCacheServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/interceptor/AdminAuthInterceptorTest.java -A hl-resource-service/src/test/java/com/hulalv/material/service/ChunkUploadServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/service/MaterialCategoryPermissionServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/service/MaterialCategoryServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/service/MaterialRefServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/service/MaterialServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/service/MaterialTagServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/constant/TransportConstantsTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/service/FlightServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/service/TrainServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/service/VariFlightApiClientTest.java -M hl-user-service/pom.xml -A hl-user-service/src/main/java/com/hulalv/callback/config/MyBatisPlusConfig.java -A hl-user-service/src/main/java/com/hulalv/callback/constant/CallbackConstants.java -A hl-user-service/src/main/java/com/hulalv/callback/controller/MsgAuditCallbackController.java -A hl-user-service/src/main/java/com/hulalv/callback/controller/WxCallbackController.java -A hl-user-service/src/main/java/com/hulalv/callback/crypto/WxCryptUtil.java -A hl-user-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java -A hl-user-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java -A hl-user-service/src/main/java/com/hulalv/callback/handler/ApprovalEventHandler.java -A hl-user-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java -A hl-user-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java -A hl-user-service/src/main/java/com/hulalv/callback/mq/producer/ApprovalResultProducer.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/ChatDataPullJob.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/ChatMessageService.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/ContactsTokenService.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/InternalChatMessageController.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditController.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditProperties.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditService.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/MsgAuditTokenService.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/WechatGroupService.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/entity/ChatMessage.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/entity/ChatPullCursor.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/entity/WechatGroup.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/mapper/ChatMessageMapper.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/mapper/ChatPullCursorMapper.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/mapper/WechatGroupMapper.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/sdk/FinanceSdkBridge.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/sdk/WeWorkFinanceSdkJna.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/vo/ChatMessageVO.java -A hl-user-service/src/main/java/com/hulalv/callback/msgaudit/vo/WechatGroupVO.java -A hl-user-service/src/main/java/com/hulalv/file/config/FileConfig.java -A hl-user-service/src/main/java/com/hulalv/file/config/MyBatisPlusConfig.java -A hl-user-service/src/main/java/com/hulalv/file/config/OssConfig.java -A hl-user-service/src/main/java/com/hulalv/file/config/WebMvcConfig.java -A hl-user-service/src/main/java/com/hulalv/file/constant/FileConstants.java -A hl-user-service/src/main/java/com/hulalv/file/controller/FileController.java -A hl-user-service/src/main/java/com/hulalv/file/controller/InternalFileController.java -A hl-user-service/src/main/java/com/hulalv/file/controller/MpFileController.java -A hl-user-service/src/main/java/com/hulalv/file/dto/BatchFileRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/BindRefsRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/ChunkUploadCancelRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/ChunkUploadCompleteRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/ChunkUploadInitRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/FileQueryRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/UnbindRefsRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/UploadConfirmRequest.java -A hl-user-service/src/main/java/com/hulalv/file/dto/UploadTokenRequest.java -A hl-user-service/src/main/java/com/hulalv/file/entity/FileInfo.java -A hl-user-service/src/main/java/com/hulalv/file/entity/FileRef.java -A hl-user-service/src/main/java/com/hulalv/file/interceptor/AdminAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/file/interceptor/UserAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/file/mapper/FileInfoMapper.java -A hl-user-service/src/main/java/com/hulalv/file/mapper/FileRefMapper.java -A hl-user-service/src/main/java/com/hulalv/file/service/ChunkUploadService.java -A hl-user-service/src/main/java/com/hulalv/file/service/FileRefService.java -A hl-user-service/src/main/java/com/hulalv/file/service/FileService.java -A hl-user-service/src/main/java/com/hulalv/file/service/OssService.java -A hl-user-service/src/main/java/com/hulalv/file/vo/ChunkUploadInitVO.java -A hl-user-service/src/main/java/com/hulalv/file/vo/ChunkUploadPartVO.java -A hl-user-service/src/main/java/com/hulalv/file/vo/FileRefVO.java -A hl-user-service/src/main/java/com/hulalv/file/vo/FileStatsVO.java -A hl-user-service/src/main/java/com/hulalv/file/vo/FileVO.java -A hl-user-service/src/main/java/com/hulalv/file/vo/UploadTokenVO.java -A hl-user-service/src/main/java/com/hulalv/monitor/config/MyBatisPlusConfig.java -A hl-user-service/src/main/java/com/hulalv/monitor/config/WebMvcConfig.java -A hl-user-service/src/main/java/com/hulalv/monitor/constant/MonitorConstants.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/ApprovalLogController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/DataRetentionController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/ErrorLogController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/InternalLogController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/MysqlMonitorController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/NotificationLogController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/OperationLogController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/RedisMonitorController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/RocketMqMonitorController.java -A hl-user-service/src/main/java/com/hulalv/monitor/controller/ServiceMonitorController.java -A hl-user-service/src/main/java/com/hulalv/monitor/entity/AlertRecord.java -A hl-user-service/src/main/java/com/hulalv/monitor/entity/AlertRule.java -A hl-user-service/src/main/java/com/hulalv/monitor/entity/ApprovalLog.java -A hl-user-service/src/main/java/com/hulalv/monitor/entity/ErrorLog.java -A hl-user-service/src/main/java/com/hulalv/monitor/entity/NotificationLog.java -A hl-user-service/src/main/java/com/hulalv/monitor/entity/OperationLog.java -A hl-user-service/src/main/java/com/hulalv/monitor/feign/UserServiceClient.java -A hl-user-service/src/main/java/com/hulalv/monitor/interceptor/AdminAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/monitor/mapper/AlertRecordMapper.java -A hl-user-service/src/main/java/com/hulalv/monitor/mapper/AlertRuleMapper.java -A hl-user-service/src/main/java/com/hulalv/monitor/mapper/ApprovalLogMapper.java -A hl-user-service/src/main/java/com/hulalv/monitor/mapper/ErrorLogMapper.java -A hl-user-service/src/main/java/com/hulalv/monitor/mapper/NotificationLogMapper.java -A hl-user-service/src/main/java/com/hulalv/monitor/mapper/OperationLogMapper.java -A hl-user-service/src/main/java/com/hulalv/monitor/mq/consumer/LogConsumer.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/ApprovalLogService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/DataRetentionService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/ErrorLogService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/MysqlMonitorService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/NotificationLogService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/OperationLogService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/RedisMonitorService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/RocketMqMonitorService.java -A hl-user-service/src/main/java/com/hulalv/monitor/service/ServiceMonitorService.java -A hl-user-service/src/main/java/com/hulalv/review/config/AsyncConfig.java -A hl-user-service/src/main/java/com/hulalv/review/config/MyBatisPlusConfig.java -A hl-user-service/src/main/java/com/hulalv/review/config/WebMvcConfig.java -A hl-user-service/src/main/java/com/hulalv/review/constant/ReviewConstants.java -A hl-user-service/src/main/java/com/hulalv/review/controller/AdminReviewController.java -A hl-user-service/src/main/java/com/hulalv/review/controller/InternalMpReviewController.java -A hl-user-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java -A hl-user-service/src/main/java/com/hulalv/review/dto/AdminReplyRequest.java -A hl-user-service/src/main/java/com/hulalv/review/dto/CreateReviewRequest.java -A hl-user-service/src/main/java/com/hulalv/review/dto/MpReviewQueryRequest.java -A hl-user-service/src/main/java/com/hulalv/review/dto/RejectRequest.java -A hl-user-service/src/main/java/com/hulalv/review/dto/ReviewQueryRequest.java -A hl-user-service/src/main/java/com/hulalv/review/dto/TargetReviewQueryRequest.java -A hl-user-service/src/main/java/com/hulalv/review/entity/OrderReview.java -A hl-user-service/src/main/java/com/hulalv/review/entity/OrderReviewImage.java -A hl-user-service/src/main/java/com/hulalv/review/entity/OrderReviewVideo.java -A hl-user-service/src/main/java/com/hulalv/review/entity/ReviewLike.java -A hl-user-service/src/main/java/com/hulalv/review/feign/OrderReviewFeignClient.java -A hl-user-service/src/main/java/com/hulalv/review/feign/OrderReviewFeignFallbackFactory.java -A hl-user-service/src/main/java/com/hulalv/review/feign/ProductReviewFeignClient.java -A hl-user-service/src/main/java/com/hulalv/review/feign/ProductReviewFeignFallbackFactory.java -A hl-user-service/src/main/java/com/hulalv/review/feign/UserReviewFeignClient.java -A hl-user-service/src/main/java/com/hulalv/review/feign/UserReviewFeignFallbackFactory.java -A hl-user-service/src/main/java/com/hulalv/review/interceptor/AdminAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/review/interceptor/UserAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/review/mapper/OrderReviewImageMapper.java -A hl-user-service/src/main/java/com/hulalv/review/mapper/OrderReviewMapper.java -A hl-user-service/src/main/java/com/hulalv/review/mapper/OrderReviewVideoMapper.java -A hl-user-service/src/main/java/com/hulalv/review/mapper/ReviewLikeMapper.java -A hl-user-service/src/main/java/com/hulalv/review/service/ContentModerationService.java -A hl-user-service/src/main/java/com/hulalv/review/service/ReviewService.java -A hl-user-service/src/main/java/com/hulalv/review/vo/MpReviewVO.java -A hl-user-service/src/main/java/com/hulalv/review/vo/ReviewListVO.java -A hl-user-service/src/main/java/com/hulalv/review/vo/ReviewStatsVO.java -A hl-user-service/src/main/java/com/hulalv/review/vo/ReviewVO.java -A hl-user-service/src/main/java/com/hulalv/review/vo/ReviewableTargetVO.java -A hl-user-service/src/main/java/com/hulalv/task/config/AsyncConfig.java -A hl-user-service/src/main/java/com/hulalv/task/config/BoardInitRunner.java -A hl-user-service/src/main/java/com/hulalv/task/config/MyBatisPlusConfig.java -A hl-user-service/src/main/java/com/hulalv/task/config/WebMvcConfig.java -A hl-user-service/src/main/java/com/hulalv/task/config/WebSocketAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/task/config/WebSocketConfig.java -A hl-user-service/src/main/java/com/hulalv/task/constant/ActivityAction.java -A hl-user-service/src/main/java/com/hulalv/task/constant/BoardType.java -A hl-user-service/src/main/java/com/hulalv/task/constant/MemberRole.java -A hl-user-service/src/main/java/com/hulalv/task/constant/TaskPriority.java -A hl-user-service/src/main/java/com/hulalv/task/controller/BoardController.java -A hl-user-service/src/main/java/com/hulalv/task/controller/TaskController.java -A hl-user-service/src/main/java/com/hulalv/task/controller/WebSocketDocController.java -A hl-user-service/src/main/java/com/hulalv/task/dto/AddMembersRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/ChangeStatusRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/CreateBoardRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/CreateCommentRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/CreateStatusRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/CreateSubtaskRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/CreateTaskRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/StatusSortRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/TaskSortRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/UpdateBoardRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/UpdateStatusRequest.java -A hl-user-service/src/main/java/com/hulalv/task/dto/UpdateTaskRequest.java -A hl-user-service/src/main/java/com/hulalv/task/entity/BoardMember.java -A hl-user-service/src/main/java/com/hulalv/task/entity/BoardStatus.java -A hl-user-service/src/main/java/com/hulalv/task/entity/Task.java -A hl-user-service/src/main/java/com/hulalv/task/entity/TaskActivity.java -A hl-user-service/src/main/java/com/hulalv/task/entity/TaskAssignee.java -A hl-user-service/src/main/java/com/hulalv/task/entity/TaskBoard.java -A hl-user-service/src/main/java/com/hulalv/task/entity/TaskComment.java -A hl-user-service/src/main/java/com/hulalv/task/interceptor/AdminAuthInterceptor.java -A hl-user-service/src/main/java/com/hulalv/task/job/TaskReminderJob.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/BoardMemberMapper.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/BoardStatusMapper.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/TaskActivityMapper.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/TaskAssigneeMapper.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/TaskBoardMapper.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/TaskCommentMapper.java -A hl-user-service/src/main/java/com/hulalv/task/mapper/TaskMapper.java -A hl-user-service/src/main/java/com/hulalv/task/service/BoardEventService.java -A hl-user-service/src/main/java/com/hulalv/task/service/BoardMemberService.java -A hl-user-service/src/main/java/com/hulalv/task/service/BoardService.java -A hl-user-service/src/main/java/com/hulalv/task/service/BoardStatusService.java -A hl-user-service/src/main/java/com/hulalv/task/service/TaskActivityService.java -A hl-user-service/src/main/java/com/hulalv/task/service/TaskCommentService.java -A hl-user-service/src/main/java/com/hulalv/task/service/TaskNotificationService.java -A hl-user-service/src/main/java/com/hulalv/task/service/TaskService.java -A hl-user-service/src/main/java/com/hulalv/task/vo/AssigneeVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/BoardMemberVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/BoardStatusVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/BoardTasksVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/BoardVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/SubtaskVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/TaskVO.java -A hl-user-service/src/main/java/com/hulalv/task/vo/TimelineItemVO.java -M hl-user-service/src/main/java/com/hulalv/user/UserServiceApplication.java -A hl-user-service/src/main/java/com/tencent/wework/Finance.java -A hl-user-service/src/test/java/com/hulalv/callback/EntityVoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/callback/controller/MsgAuditCallbackControllerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/controller/WxCallbackControllerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/crypto/WxCryptUtilTest.java -A hl-user-service/src/test/java/com/hulalv/callback/feign/UserServiceClientFallbackTest.java -A hl-user-service/src/test/java/com/hulalv/callback/handler/ApprovalEventHandlerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/handler/ContactChangeHandlerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/handler/ExternalContactHandlerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/mq/producer/ApprovalResultProducerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/msgaudit/ChatDataPullJobTest.java -A hl-user-service/src/test/java/com/hulalv/callback/msgaudit/ChatMessageServiceTest.java -A hl-user-service/src/test/java/com/hulalv/callback/msgaudit/InternalChatMessageControllerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/msgaudit/MsgAuditTokenServiceTest.java -A hl-user-service/src/test/java/com/hulalv/file/EntityDtoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/file/config/FileConfigTest.java -A hl-user-service/src/test/java/com/hulalv/file/config/OssConfigTest.java -A hl-user-service/src/test/java/com/hulalv/file/constant/FileConstantsTest.java -A hl-user-service/src/test/java/com/hulalv/file/controller/FileControllerTest.java -A hl-user-service/src/test/java/com/hulalv/file/interceptor/AdminAuthInterceptorTest.java -A hl-user-service/src/test/java/com/hulalv/file/interceptor/UserAuthInterceptorTest.java -A hl-user-service/src/test/java/com/hulalv/file/service/ChunkUploadServiceTest.java -A hl-user-service/src/test/java/com/hulalv/file/service/FileRefServiceTest.java -A hl-user-service/src/test/java/com/hulalv/file/service/FileServiceTest.java -A hl-user-service/src/test/java/com/hulalv/file/service/OssServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/EntityCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/ApprovalLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/DataRetentionControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/ErrorLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/InternalLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/LoginLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/MysqlMonitorControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/NotificationLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/OperationLogControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/RedisMonitorControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/RocketMqMonitorControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/ServiceMonitorControllerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/interceptor/AdminAuthInterceptorTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/mq/consumer/LogConsumerTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/ApprovalLogServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/DataRetentionServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/ErrorLogServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/MysqlMonitorServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/NotificationLogServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/OperationLogServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/RedisMonitorServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/RocketMqMonitorServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/service/ServiceMonitorServiceTest.java -A hl-user-service/src/test/java/com/hulalv/review/EntityDtoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/review/constant/ReviewConstantsTest.java -A hl-user-service/src/test/java/com/hulalv/review/controller/AdminReviewControllerTest.java -A hl-user-service/src/test/java/com/hulalv/review/controller/InternalMpReviewControllerTest.java -A hl-user-service/src/test/java/com/hulalv/review/controller/InternalReviewControllerTest.java -A hl-user-service/src/test/java/com/hulalv/review/service/ContentModerationServiceTest.java -A hl-user-service/src/test/java/com/hulalv/review/service/ReviewServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/EntityDtoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/task/controller/BoardControllerTest.java -A hl-user-service/src/test/java/com/hulalv/task/controller/TaskControllerTest.java -A hl-user-service/src/test/java/com/hulalv/task/controller/WebSocketDocControllerTest.java -A hl-user-service/src/test/java/com/hulalv/task/interceptor/AdminAuthInterceptorTest.java -A hl-user-service/src/test/java/com/hulalv/task/job/TaskReminderJobTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/BoardEventServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/BoardMemberServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/BoardServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/BoardStatusServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/TaskActivityServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/TaskCommentServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/TaskNotificationServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/service/TaskServiceTest.java -A mastergo_trip_ended_2_zoom.jpg -M pom.xml -A scripts/ai-collab/README.md -A scripts/ai-collab/agent_client.py -A scripts/ai-collab/client_requirements.txt -A scripts/ai-collab/data/ai_collab.db -A scripts/ai-collab/server/agent_manager.py -A scripts/ai-collab/server/config.py -A scripts/ai-collab/server/db.py -A scripts/ai-collab/server/main.py -A scripts/ai-collab/server/requirements.txt -A scripts/ai-collab/server/router_admin.py -A scripts/ai-collab/server/router_agents.py -A scripts/ai-collab/server/router_messages.py -A scripts/ai-collab/server/ws_manager.py -A scripts/ai-collab/web/admin.html -A scripts/ai-collab/web/app.js -A scripts/ai-collab/web/index.html -A scripts/deploy-panel/deploy-panel.sh -A scripts/fix_coordinates.py -A scripts/full_api_test.sh -A scripts/git-auto-pull.py -A scripts/git-auto-pull.vbs -A scripts/import_hotels.py -A scripts/import_restaurants_json.py -A scripts/import_scenic.py -A scripts/import_scenic_json.py -A sql/contract_scheme.sql -A sql/fix_notification_templates.sql -A sql/hulunbuir_scenic_spots_seed.json -A sql/insurance_scheme_total_days.sql -A sql/order_surcharge.sql -A sql/remove_max_group_size.sql -A sql/remove_unused_pricing_fields.sql -A tmp-contract-config.yml -A tmp-dev-contract-updated.yml -A tmp-dev-contract.yml -A tmp_insurance_xls.json -A tmp_login.json -A tmp_login2.json -A tmp_mock_pay.sql -A tmp_order.json -A tmp_prepay.json -A tmp_prepay2.json -A tmp_products.json -A tmp_quote.json -A tmp_token.txt -A trip_ended_2_zoomed.jpg -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_0136_7caf4546_refactor_11.md b/changelogs/2026-03/2026-03-31_0136_7caf4546_refactor_11.md deleted file mode 100644 index 2e060e6..0000000 --- a/changelogs/2026-03/2026-03-31_0136_7caf4546_refactor_11.md +++ /dev/null @@ -1,142 +0,0 @@ -# 接口变更记录 — 2026-03-31 01:36 - -> **提交** `7caf4546` · **作者** wx · **时间** 2026-03-31 01:36:39 +0800 -> -> refactor: 消除11个自调自己的FeignClient，改为本地Service调用 - -## 变更总览 - -- **用户服务** - - LoginLog (改1) - - AdminProfile (改1) - ---- - -## 用户服务 - -### LoginLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「登录日志」** - -### ✏️ `GET` /admin/monitor/login-logs — 登录日志分页查询 - -- 返回类型: `` → `Result<PageResult<LoginLogVO>>` -- 🆕 新增响应类型 `LoginLogVO` - -### AdminProfile - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「个人中心」** - -### ✏️ `GET` /admin/profile/reviews — 我的评价列表 - -- 返回类型: `Result<PageResult<Map<String, Object>>>` → `` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ❌ ~~BatchMaterialIdsRequest~~ - -#### ❌ ~~MaterialVO~~ - -#### ❌ ~~RefBatchBindRequest~~ - -#### ❌ ~~RefBatchUnbindRequest~~ - -#### ❌ ~~RefBindRequest~~ - -#### ❌ ~~RefUnbindRequest~~ - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -D hl-order-service/src/main/java/com/hulalv/contract/feign/OrderContractFeignClient.java -M hl-order-service/src/main/java/com/hulalv/contract/service/ContractCallbackService.java -M hl-order-service/src/main/java/com/hulalv/contract/service/ContractService.java -D hl-order-service/src/main/java/com/hulalv/insurance/feign/OrderInsuranceFeignClient.java -M hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -M hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceSchemeService.java -D hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignClient.java -D hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignFallbackFactory.java -D hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignClient.java -D hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -D hl-order-service/src/main/java/com/hulalv/payment/feign/OrderPaymentFeignClient.java -D hl-order-service/src/main/java/com/hulalv/payment/feign/OrderPaymentFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/payment/service/PaymentService.java -M hl-order-service/src/main/java/com/hulalv/payment/service/RefundService.java -M hl-order-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -M hl-order-service/src/test/java/com/hulalv/insurance/service/InsuranceSchemeServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderCascadeServiceTest.java -M hl-order-service/src/test/java/com/hulalv/payment/service/PaymentServiceTest.java -M hl-order-service/src/test/java/com/hulalv/payment/service/RefundServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/material/dto/BatchMaterialIdsRequest.java -M hl-resource-service/src/main/java/com/hulalv/material/dto/RefBatchBindRequest.java -M hl-resource-service/src/main/java/com/hulalv/material/dto/RefBindRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java -M hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/MaterialRefFallbackFactory.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/MaterialRefFeignClient.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/BatchMaterialIdsRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBatchBindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBatchUnbindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefUnbindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/vo/MaterialVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/RoomTypeService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSeasonService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalMpResourceBriefControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceDetailControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/coverage/DtoVoCoverageTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/HotelServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/RoomTypeServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/restaurant/service/RestaurantServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSeasonServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSpotServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/service/service/ServiceItemServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/staff/service/StaffServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/supplies/service/SuppliesServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/vehicle/service/VehicleModelServiceTest.java -D hl-user-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java -D hl-user-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java -M hl-user-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java -M hl-user-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java -M hl-user-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java -D hl-user-service/src/main/java/com/hulalv/monitor/feign/UserServiceClient.java -D hl-user-service/src/main/java/com/hulalv/review/feign/UserReviewFeignClient.java -D hl-user-service/src/main/java/com/hulalv/review/feign/UserReviewFeignFallbackFactory.java -M hl-user-service/src/main/java/com/hulalv/review/service/ReviewService.java -M hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java -D hl-user-service/src/main/java/com/hulalv/user/feign/DesignerReviewFeignClient.java -D hl-user-service/src/main/java/com/hulalv/user/feign/DesignerReviewFeignFallbackFactory.java -D hl-user-service/src/main/java/com/hulalv/user/feign/NotificationStatsFeignClient.java -D hl-user-service/src/main/java/com/hulalv/user/feign/NotificationStatsFeignFallbackFactory.java -M hl-user-service/src/main/java/com/hulalv/user/service/DesignerDashboardService.java -D hl-user-service/src/test/java/com/hulalv/callback/feign/UserServiceClientFallbackTest.java -M hl-user-service/src/test/java/com/hulalv/callback/handler/ContactChangeHandlerTest.java -M hl-user-service/src/test/java/com/hulalv/callback/handler/ExternalContactHandlerTest.java -M hl-user-service/src/test/java/com/hulalv/monitor/controller/LoginLogControllerTest.java -M hl-user-service/src/test/java/com/hulalv/review/service/ReviewServiceTest.java -M hl-user-service/src/test/java/com/hulalv/user/controller/AdminProfileControllerTest.java -M hl-user-service/src/test/java/com/hulalv/user/feign/FallbackFactoryTest.java -M hl-user-service/src/test/java/com/hulalv/user/service/DesignerDashboardServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_0137_f44dd5dd_refactor_11.md b/changelogs/2026-03/2026-03-31_0137_f44dd5dd_refactor_11.md deleted file mode 100644 index 757e63a..0000000 --- a/changelogs/2026-03/2026-03-31_0137_f44dd5dd_refactor_11.md +++ /dev/null @@ -1,142 +0,0 @@ -# 接口变更记录 — 2026-03-31 01:37 - -> **提交** `f44dd5dd` · **作者** wx · **时间** 2026-03-31 01:36:39 +0800 -> -> refactor: 消除11个自调自己的FeignClient，改为本地Service调用 - -## 变更总览 - -- **用户服务** - - LoginLog (改1) - - AdminProfile (改1) - ---- - -## 用户服务 - -### LoginLog - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「登录日志」** - -### ✏️ `GET` /admin/monitor/login-logs — 登录日志分页查询 - -- 返回类型: `` → `Result<PageResult<LoginLogVO>>` -- 🆕 新增响应类型 `LoginLogVO` - -### AdminProfile - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「个人中心」** - -### ✏️ `GET` /admin/profile/reviews — 我的评价列表 - -- 返回类型: `Result<PageResult<Map<String, Object>>>` → `` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ❌ ~~BatchMaterialIdsRequest~~ - -#### ❌ ~~MaterialVO~~ - -#### ❌ ~~RefBatchBindRequest~~ - -#### ❌ ~~RefBatchUnbindRequest~~ - -#### ❌ ~~RefBindRequest~~ - -#### ❌ ~~RefUnbindRequest~~ - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -D hl-order-service/src/main/java/com/hulalv/contract/feign/OrderContractFeignClient.java -M hl-order-service/src/main/java/com/hulalv/contract/service/ContractCallbackService.java -M hl-order-service/src/main/java/com/hulalv/contract/service/ContractService.java -D hl-order-service/src/main/java/com/hulalv/insurance/feign/OrderInsuranceFeignClient.java -M hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceOrderService.java -M hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceSchemeService.java -D hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignClient.java -D hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignFallbackFactory.java -D hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignClient.java -D hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderAutoProcessingService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -D hl-order-service/src/main/java/com/hulalv/payment/feign/OrderPaymentFeignClient.java -D hl-order-service/src/main/java/com/hulalv/payment/feign/OrderPaymentFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/payment/service/PaymentService.java -M hl-order-service/src/main/java/com/hulalv/payment/service/RefundService.java -M hl-order-service/src/test/java/com/hulalv/contract/service/ContractServiceTest.java -M hl-order-service/src/test/java/com/hulalv/insurance/service/InsuranceSchemeServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderCascadeServiceTest.java -M hl-order-service/src/test/java/com/hulalv/payment/service/PaymentServiceTest.java -M hl-order-service/src/test/java/com/hulalv/payment/service/RefundServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/material/dto/BatchMaterialIdsRequest.java -M hl-resource-service/src/main/java/com/hulalv/material/dto/RefBatchBindRequest.java -M hl-resource-service/src/main/java/com/hulalv/material/dto/RefBindRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalMpResourceBriefController.java -M hl-resource-service/src/main/java/com/hulalv/resource/controller/InternalResourceDetailController.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/MaterialRefFallbackFactory.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/MaterialRefFeignClient.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/BatchMaterialIdsRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBatchBindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBatchUnbindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefBindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/dto/RefUnbindRequest.java -D hl-resource-service/src/main/java/com/hulalv/resource/feign/vo/MaterialVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/RoomTypeService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSeasonService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/service/service/ServiceItemService.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/service/StaffService.java -M hl-resource-service/src/main/java/com/hulalv/resource/supplies/service/SuppliesService.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/service/VehicleModelService.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalMpResourceBriefControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceDetailControllerTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/coverage/DtoVoCoverageTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/HotelServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/RoomTypeServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/restaurant/service/RestaurantServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSeasonServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSpotServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/service/service/ServiceItemServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/staff/service/StaffServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/supplies/service/SuppliesServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/vehicle/service/VehicleModelServiceTest.java -D hl-user-service/src/main/java/com/hulalv/callback/feign/UserServiceClient.java -D hl-user-service/src/main/java/com/hulalv/callback/feign/UserServiceClientFallback.java -M hl-user-service/src/main/java/com/hulalv/callback/handler/ContactChangeHandler.java -M hl-user-service/src/main/java/com/hulalv/callback/handler/ExternalContactHandler.java -M hl-user-service/src/main/java/com/hulalv/monitor/controller/LoginLogController.java -D hl-user-service/src/main/java/com/hulalv/monitor/feign/UserServiceClient.java -D hl-user-service/src/main/java/com/hulalv/review/feign/UserReviewFeignClient.java -D hl-user-service/src/main/java/com/hulalv/review/feign/UserReviewFeignFallbackFactory.java -M hl-user-service/src/main/java/com/hulalv/review/service/ReviewService.java -M hl-user-service/src/main/java/com/hulalv/user/controller/AdminProfileController.java -D hl-user-service/src/main/java/com/hulalv/user/feign/DesignerReviewFeignClient.java -D hl-user-service/src/main/java/com/hulalv/user/feign/DesignerReviewFeignFallbackFactory.java -D hl-user-service/src/main/java/com/hulalv/user/feign/NotificationStatsFeignClient.java -D hl-user-service/src/main/java/com/hulalv/user/feign/NotificationStatsFeignFallbackFactory.java -M hl-user-service/src/main/java/com/hulalv/user/service/DesignerDashboardService.java -D hl-user-service/src/test/java/com/hulalv/callback/feign/UserServiceClientFallbackTest.java -M hl-user-service/src/test/java/com/hulalv/callback/handler/ContactChangeHandlerTest.java -M hl-user-service/src/test/java/com/hulalv/callback/handler/ExternalContactHandlerTest.java -M hl-user-service/src/test/java/com/hulalv/monitor/controller/LoginLogControllerTest.java -M hl-user-service/src/test/java/com/hulalv/review/service/ReviewServiceTest.java -M hl-user-service/src/test/java/com/hulalv/user/controller/AdminProfileControllerTest.java -M hl-user-service/src/test/java/com/hulalv/user/feign/FallbackFactoryTest.java -M hl-user-service/src/test/java/com/hulalv/user/service/DesignerDashboardServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1024_e90a2e21_test_4.md b/changelogs/2026-03/2026-03-31_1024_e90a2e21_test_4.md deleted file mode 100644 index e8da2bd..0000000 --- a/changelogs/2026-03/2026-03-31_1024_e90a2e21_test_4.md +++ /dev/null @@ -1,129 +0,0 @@ -# 接口变更记录 — 2026-03-31 10:24 - -> **提交** `e90a2e21` · **作者** wx · **时间** 2026-03-31 10:24:23 +0800 -> -> test: 补充单元测试提升覆盖率（4个Agent并行） - -## 变更总览 - -- **用户服务** - - 🆕 LoginLogFullTest (+0 接口) - - 🆕 TaskFullTest (+0 接口) - - 🆕 AuthFullTest (+0 接口) - - 🆕 InternalApprovalFullTest (+0 接口) - - 🆕 AdminNotificationTest (+0 接口) -- **订单服务** - - 🆕 AdminInsuranceTest (+0 接口) -- **资源服务** - - 🆕 InternalMaterialTest (+0 接口) - - 🆕 MaterialCategoryPermissionTest (+0 接口) - - 🆕 MaterialTest (+0 接口) - - 🆕 MaterialTagTest (+0 接口) - - 🆕 MpMaterialTest (+0 接口) - - 🆕 InternalMpResourceBriefExpandedTest (+0 接口) - - 🆕 InternalResourceDetailExpandedTest (+0 接口) - - 🆕 InternalResourcePriceExpandedTest (+0 接口) - - 🆕 AdminTransportTest (+0 接口) - - 🆕 InternalTransportTest (+0 接口) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 公共模块 - -#### 🆕 DtoBranchCoverageTest - -#### 🆕 DtoNullFieldCoverageTest - -### 资源服务 - -#### 🆕 TransportVoCoverageTest - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-common/hl-common-core/src/test/java/com/hulalv/common/constant/RedisKeyConstantsTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/dto/DtoBranchCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/dto/DtoNullFieldCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/exception/ExceptionTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/result/PageResultBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/result/ResultBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/QWeatherClientBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/QWeatherClientIntegrationTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/QWeatherClientMockHttpTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/WeatherInfoBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/WeatherInfoNullFieldTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/MqConstantsTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/message/MqMessageBranchTest.java -A hl-common/hl-common-mq/src/test/java/com/hulalv/common/mq/message/MqMessageNullFieldTest.java -A hl-common/hl-common-redis/src/test/java/com/hulalv/common/util/DistributedLockUtilBranchTest.java -A hl-common/hl-common-redis/src/test/java/com/hulalv/common/util/TravelerTypeResolverBranchTest.java -A hl-order-service/src/test/java/com/hulalv/contract/config/ContractPlatformPropertiesTest.java -A hl-order-service/src/test/java/com/hulalv/contract/platform/tourage/TourageApiClientTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/controller/AdminInsuranceControllerTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/coverage/InsuranceEntityDtoCoverageTest.java -A hl-order-service/src/test/java/com/hulalv/insurance/service/PolicyShareServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/coverage/DtoVoCoverageTest.java -M hl-order-service/src/test/java/com/hulalv/order/coverage/EntityCoverageTest.java -A hl-order-service/src/test/java/com/hulalv/order/customize/service/CustomizeRequestServiceTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/NotificationEventHelperTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/OrderAutoProcessingServiceTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/OrderTransportServiceTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/RefundApprovalPollingServiceTest.java -A hl-order-service/src/test/java/com/hulalv/order/service/WeatherServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/coverage/DtoVoCoverageTest.java -M hl-product-service/src/test/java/com/hulalv/product/coverage/EntityCoverageTest.java -A hl-product-service/src/test/java/com/hulalv/product/mq/consumer/ResourcePriceChangeConsumerTest.java -A hl-product-service/src/test/java/com/hulalv/product/service/AmapDistrictServiceTest.java -A hl-product-service/src/test/java/com/hulalv/product/service/AmapDrivingServiceTest.java -A hl-product-service/src/test/java/com/hulalv/product/service/BookingTermsServiceTest.java -A hl-product-service/src/test/java/com/hulalv/product/service/CustomFeeServiceTest.java -A hl-product-service/src/test/java/com/hulalv/product/service/RouteMapServiceTest.java -A hl-product-service/src/test/java/com/hulalv/product/service/WarmTipsServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/DtoVoEqualsCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/guide/interceptor/AdminAuthInterceptorTest.java -M hl-resource-service/src/test/java/com/hulalv/guide/service/GuideArticleServiceTest.java -A hl-resource-service/src/test/java/com/hulalv/material/DtoVoEntityEqualsCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/material/controller/InternalMaterialControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/material/controller/MaterialCategoryPermissionControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/material/controller/MaterialControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/material/controller/MaterialTagControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/material/controller/MpMaterialControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalMpResourceBriefControllerExpandedTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourceDetailControllerExpandedTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/common/controller/InternalResourcePriceControllerExpandedTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/config/Knife4jConfigTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/config/MyBatisPlusConfigTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/config/WebMvcConfigTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/DtoVoEqualsCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/EntityEqualsCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/coverage/RemainingEqualsCoverageTest.java -A hl-resource-service/src/test/java/com/hulalv/resource/interceptor/AdminAuthInterceptorTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/config/WebMvcConfigTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/controller/AdminTransportControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/controller/InternalTransportControllerTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/interceptor/AdminAuthInterceptorTest.java -A hl-resource-service/src/test/java/com/hulalv/transport/vo/TransportVoCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/callback/msgaudit/MsgAuditControllerTest.java -A hl-user-service/src/test/java/com/hulalv/callback/msgaudit/WechatGroupServiceTest.java -A hl-user-service/src/test/java/com/hulalv/monitor/controller/LoginLogControllerFullTest.java -A hl-user-service/src/test/java/com/hulalv/review/service/ContentModerationServiceFullTest.java -M hl-user-service/src/test/java/com/hulalv/review/service/ReviewServiceTest.java -A hl-user-service/src/test/java/com/hulalv/task/controller/TaskControllerFullTest.java -A hl-user-service/src/test/java/com/hulalv/user/config/Knife4jConfigTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/AuthControllerFullTest.java -A hl-user-service/src/test/java/com/hulalv/user/controller/InternalApprovalControllerFullTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/BuilderCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/ComprehensiveEntityCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/DeepEqualsHashCodeTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/CustomPushServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/NotificationConfigServiceTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/NotificationDispatcherTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/controller/AdminNotificationControllerTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/FrontendConfigServiceFullTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1141_b2432512_test.md b/changelogs/2026-03/2026-03-31_1141_b2432512_test.md deleted file mode 100644 index 5a773af..0000000 --- a/changelogs/2026-03/2026-03-31_1141_b2432512_test.md +++ /dev/null @@ -1,260 +0,0 @@ -# 接口变更记录 — 2026-03-31 11:41 - -> **提交** `b2432512` · **作者** wx · **时间** 2026-03-31 11:41:56 +0800 -> -> test: 第二轮补充单元测试提升覆盖率 - -## 变更总览 - -- **产品服务** - - InternalProduct (改1) -- **小程序聚合服务** - - 🆕 MpEdgeCaseTest (+0 接口) - - 🆕 MpCustomizeBranchTest (+0 接口) - - 🆕 MpDesignerBranchTest (+0 接口) - - 🆕 MpLikeBranchTest (+0 接口) - - 🆕 MpProductBranchTest (+0 接口) - - 🆕 MpReviewBranchTest (+0 接口) - - 🆕 MpScenicBranchTest (+0 接口) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### ✏️ `GET` /internal/product/{productId}/simple-quote — 简单报价（内部） - -- 参数: productId(Long), childNeedBed(boolean) → childNeedBed(boolean) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ FamilySaveRequest - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ PricingRequest - - - ❌ ~~`babyPrice`~~ (`BigDecimal`) — 婴儿固定价格（不随日期变化） - - ❌ ~~`childDiscountPercent`~~ (`BigDecimal`) — 小童折扣百分比（小童价=儿童价×此百分比/100，如70表示打7折） - -#### ✏️ ProductCreateRequest - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童人数 - - ❌ ~~`babyCount`~~ (`Integer`) — 婴儿人数 - -#### ✏️ ProductFamilyVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ ProductListVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数（私人定制/路书） - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数（私人定制/路书） - -#### ✏️ ProductPricingVO - - - ❌ ~~`babyPrice`~~ (`BigDecimal`) — 婴儿价 - - ❌ ~~`childDiscountPercent`~~ (`BigDecimal`) — 儿童折扣百分比 - -#### ✏️ ProductSaveRequest - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童人数 - - ❌ ~~`babyCount`~~ (`Integer`) — 婴儿人数 - -#### ✏️ ProductUpdateRequest - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童人数 - - ❌ ~~`babyCount`~~ (`Integer`) — 婴儿人数 - -#### ✏️ ProductVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童人数 - - ❌ ~~`babyCount`~~ (`Integer`) — 婴儿人数 - -#### ✏️ QuoteResultVO - - - ❌ ~~`totalYoungChildCost`~~ (`BigDecimal`) — 小童总成本 - - ❌ ~~`totalYoungChildSellPrice`~~ (`BigDecimal`) — 小童总售价 - - ❌ ~~`totalBabyCost`~~ (`BigDecimal`) — 婴儿总成本 - - ❌ ~~`totalBabySellPrice`~~ (`BigDecimal`) — 婴儿总售价 - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - - ❌ ~~`babyCost`~~ (`BigDecimal`) — 婴儿固定成本 - - ✏️ `personType`: 说明 "人员类型：ADULT/CHILD/YOUNG_CHILD/BABY" → "人员类型：ADULT/CHILD" - -### 公共模块 - -#### 🆕 DtoExtraCoverageTest - -#### 🆕 DtoReflectionEqualsCoverageTest - -### 小程序聚合服务 - -#### ✏️ MpCreateOrderRequest - - - ✏️ `travelerType`: 说明 "出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY）" → "出行人类型（ADULT/CHILD）" - -#### ✏️ MpCustomProductDetailVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - - ❌ ~~`babyPrice`~~ (`BigDecimal`) — 婴儿价 - - ❌ ~~`childDiscountPercent`~~ (`BigDecimal`) — 儿童折扣百分比 - -#### ✏️ MpOrderDetailVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ MpOrderListItemVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ MpPriceCalendarDayVO - - - ❌ ~~`youngChildPrice`~~ (`BigDecimal`) — 幼儿价格 - - ❌ ~~`babyPrice`~~ (`BigDecimal`) — 婴儿价格 - -#### ✏️ MpProductQuoteRequest - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 幼儿数量 - - ❌ ~~`babyCount`~~ (`Integer`) — 婴儿数量 - -#### ✏️ MpProductQuoteVO - - - ❌ ~~`youngChildSellPrice`~~ (`BigDecimal`) — 小童单价（儿童价×折扣比例） - - ❌ ~~`babySellPrice`~~ (`BigDecimal`) — 幼童单价（固定价） - - ❌ ~~`totalYoungChildSellPrice`~~ (`BigDecimal`) — 小童小计 - - ❌ ~~`totalBabySellPrice`~~ (`BigDecimal`) — 幼童小计 - -#### ✏️ MpTravelerRequest - - - ✏️ `travelerType`: 说明 "出行人类型: ADULT/CHILD/YOUNG_CHILD/BABY" → "出行人类型: ADULT/CHILD" - -#### ✏️ MpTravelerVO - - - ✏️ `travelerType`: 说明 "出行人类型: ADULT/CHILD/YOUNG_CHILD/BABY" → "出行人类型: ADULT/CHILD" - -### 用户服务 - -#### ✏️ TravelerRequest - - - ✏️ `travelerType`: 说明 "出行人类型，关联字典traveler_type：ADULT=成人, CHILD=儿童, YOUNG_CHILD=小童, BABY=幼童（无需传入，后端根据birthday自动判断）" → "出行人类型，关联字典traveler_type：ADULT=成人, CHILD=儿童（无需传入，后端根据birthday自动判断）" - -### 订单服务 - -#### ✏️ AdminUpdateOrderRequest - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ MpOrderListVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ OrderDetailVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -#### ✏️ OrderListVO - - - ❌ ~~`youngChildCount`~~ (`Integer`) — 小童数 - - ❌ ~~`babyCount`~~ (`Integer`) — 幼童数 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A cleanup_temp.py -A hl-common/hl-common-core/src/test/java/com/hulalv/common/dto/DtoExtraCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/dto/DtoReflectionEqualsCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/result/ResultExtraCoverageTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/AesEncryptUtilBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/AmapStaticMapUtilBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/util/SnowflakeIdWorkerBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/AmapWeatherClientBranchTest.java -A hl-common/hl-common-core/src/test/java/com/hulalv/common/weather/WeatherInfoExtraCoverageTest.java -M hl-common/hl-common-redis/src/main/java/com/hulalv/common/util/TravelerTypeResolver.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpCreateOrderRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpProductQuoteRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpTravelerRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderListItemVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpPriceCalendarDayVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductQuoteVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpTravelerVO.java -A hl-mp-service/src/test/java/com/hulalv/mp/MpServiceApplicationTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/VoExtraDeepCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/VoFieldDiffCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/VoReflectionEqualsCoverageTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/config/Knife4jConfigTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpControllerEdgeCaseTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpCustomizeControllerBranchTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpDesignerControllerBranchTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpLikeControllerBranchTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerBranchTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpReviewControllerBranchTest.java -A hl-mp-service/src/test/java/com/hulalv/mp/controller/MpScenicControllerBranchTest.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/QuotePreviewRequest.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderInfo.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/DashboardStatsService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -A hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceExtendedTest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductFamily.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductPricing.java -M hl-product-service/src/main/java/com/hulalv/product/service/CostCalculationService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductFamilyService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductPricingService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/QuoteCalculatorService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductFamilyVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/QuoteResultVO.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java -A hl-user-service/src/test/java/com/hulalv/review/service/ReviewServiceFullTest.java -A hl-user-service/src/test/java/com/hulalv/user/coverage/DeepFieldEqualsCoverageTest.java -A hl-user-service/src/test/java/com/hulalv/user/notification/MessageCategoryServiceFullTest.java -A hl-user-service/src/test/java/com/hulalv/user/service/UserServiceFullTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1218_e53397ea_fix_main.md b/changelogs/2026-03/2026-03-31_1218_e53397ea_fix_main.md deleted file mode 100644 index a411484..0000000 --- a/changelogs/2026-03/2026-03-31_1218_e53397ea_fix_main.md +++ /dev/null @@ -1,228 +0,0 @@ -# 接口变更记录 — 2026-03-31 12:18 - -> **提交** `e53397ea` · **作者** wx · **时间** 2026-03-31 12:18:36 +0800 -> -> fix: 恢复被误修改的main代码（保留4种人员类型原有逻辑） - -## 变更总览 - -- **产品服务** - - InternalProduct (改1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### ✏️ `GET` /internal/product/{productId}/simple-quote — 简单报价（内部） - -- 参数: childNeedBed(boolean) → productId(Long), childNeedBed(boolean) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ FamilySaveRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ PricingRequest - - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿固定价格（不随日期变化） - - 🆕 `childDiscountPercent` (`BigDecimal`) — 小童折扣百分比（小童价=儿童价×此百分比/100，如70表示打7折） - -#### ✏️ ProductCreateRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ ProductFamilyVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ ProductListVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数（私人定制/路书） - - 🆕 `babyCount` (`Integer`) — 幼童数（私人定制/路书） - -#### ✏️ ProductPricingVO - - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿价 - - 🆕 `childDiscountPercent` (`BigDecimal`) — 儿童折扣百分比 - -#### ✏️ ProductSaveRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ ProductUpdateRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ ProductVO - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ QuoteResultVO - - - 🆕 `totalYoungChildCost` (`BigDecimal`) — 小童总成本 - - 🆕 `totalYoungChildSellPrice` (`BigDecimal`) — 小童总售价 - - 🆕 `totalBabyCost` (`BigDecimal`) — 婴儿总成本 - - 🆕 `totalBabySellPrice` (`BigDecimal`) — 婴儿总售价 - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - - 🆕 `babyCost` (`BigDecimal`) — 婴儿固定成本 - - ✏️ `personType`: 说明 "人员类型：ADULT/CHILD" → "人员类型：ADULT/CHILD/YOUNG_CHILD/BABY" - -### 小程序聚合服务 - -#### ✏️ MpCreateOrderRequest - - - ✏️ `travelerType`: 说明 "出行人类型（ADULT/CHILD）" → "出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY）" - -#### ✏️ MpCustomProductDetailVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿价 - - 🆕 `childDiscountPercent` (`BigDecimal`) — 儿童折扣百分比 - -#### ✏️ MpOrderDetailVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ MpOrderListItemVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ MpPriceCalendarDayVO - - - 🆕 `youngChildPrice` (`BigDecimal`) — 幼儿价格 - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿价格 - -#### ✏️ MpProductQuoteRequest - - - 🆕 `youngChildCount` (`Integer`) — 幼儿数量 - - 🆕 `babyCount` (`Integer`) — 婴儿数量 - -#### ✏️ MpProductQuoteVO - - - 🆕 `youngChildSellPrice` (`BigDecimal`) — 小童单价（儿童价×折扣比例） - - 🆕 `babySellPrice` (`BigDecimal`) — 幼童单价（固定价） - - 🆕 `totalYoungChildSellPrice` (`BigDecimal`) — 小童小计 - - 🆕 `totalBabySellPrice` (`BigDecimal`) — 幼童小计 - -#### ✏️ MpTravelerRequest - - - ✏️ `travelerType`: 说明 "出行人类型: ADULT/CHILD" → "出行人类型: ADULT/CHILD/YOUNG_CHILD/BABY" - -#### ✏️ MpTravelerVO - - - ✏️ `travelerType`: 说明 "出行人类型: ADULT/CHILD" → "出行人类型: ADULT/CHILD/YOUNG_CHILD/BABY" - -### 用户服务 - -#### ✏️ TravelerRequest - - - ✏️ `travelerType`: 说明 "出行人类型，关联字典traveler_type：ADULT=成人, CHILD=儿童（无需传入，后端根据birthday自动判断）" → "出行人类型，关联字典traveler_type：ADULT=成人, CHILD=儿童, YOUNG_CHILD=小童, BABY=幼童（无需传入，后端根据birthday自动判断）" - -### 订单服务 - -#### ✏️ AdminUpdateOrderRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ MpOrderListVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ OrderDetailVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ OrderListVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-common/hl-common-redis/src/main/java/com/hulalv/common/util/TravelerTypeResolver.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpCreateOrderRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpProductQuoteRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpTravelerRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderListItemVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpPriceCalendarDayVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductQuoteVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpTravelerVO.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/QuotePreviewRequest.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderInfo.java -A hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignClient.java -A hl-order-service/src/main/java/com/hulalv/order/feign/ContractFeignFallbackFactory.java -A hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignClient.java -A hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/DashboardStatsService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductFamily.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductPricing.java -M hl-product-service/src/main/java/com/hulalv/product/feign/InsuranceSchemeFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/feign/MaterialRefFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/feign/ReviewFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/service/CostCalculationService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductFamilyService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductPricingService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/QuoteCalculatorService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductFamilyVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/QuoteResultVO.java -M hl-user-service/src/main/java/com/hulalv/user/dto/TravelerRequest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1300_26ab1bdb_feat.md b/changelogs/2026-03/2026-03-31_1300_26ab1bdb_feat.md deleted file mode 100644 index 61366ca..0000000 --- a/changelogs/2026-03/2026-03-31_1300_26ab1bdb_feat.md +++ /dev/null @@ -1,230 +0,0 @@ -# 接口变更记录 — 2026-03-31 13:00 - -> **提交** `26ab1bdb` · **作者** wx · **时间** 2026-03-31 13:00:15 +0800 -> -> feat: 小童/幼童定价模式扩展，支持百分比或固定价 - -## 变更总览 - -- **产品服务** - - InternalProduct (改1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### ✏️ `GET` /internal/product/{productId}/simple-quote — 简单报价（内部） - -- 参数: childNeedBed(boolean) → productId(Long), childNeedBed(boolean) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ FamilySaveRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ PricingRequest - - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿固定价格（不随日期变化） - - 🆕 `childDiscountPercent` (`BigDecimal`) — 小童折扣百分比（小童价=儿童价×此百分比/100，如70表示打7折） - - 🆕 `youngChildPriceMode` (`String`) — 小童定价模式：PERCENT=按儿童价百分比, FIXED=固定价 - - 🆕 `youngChildFixedPrice` (`BigDecimal`) — 小童固定价格（youngChildPriceMode=FIXED时使用） - - 🆕 `babyPriceMode` (`String`) — 幼童定价模式：PERCENT=按儿童价百分比, FIXED=固定价 - - 🆕 `babyDiscountPercent` (`BigDecimal`) — 幼童折扣百分比（babyPriceMode=PERCENT时使用） - -#### ✏️ ProductCreateRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ ProductFamilyVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ ProductListVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数（私人定制/路书） - - 🆕 `babyCount` (`Integer`) — 幼童数（私人定制/路书） - -#### ✏️ ProductPricingVO - - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿价 - - 🆕 `childDiscountPercent` (`BigDecimal`) — 儿童折扣百分比 - - 🆕 `youngChildPriceMode` (`String`) — 小童定价模式: PERCENT/FIXED - - 🆕 `youngChildFixedPrice` (`BigDecimal`) — 小童固定价格（FIXED模式） - - 🆕 `babyPriceMode` (`String`) — 幼童定价模式: PERCENT/FIXED - - 🆕 `babyDiscountPercent` (`BigDecimal`) — 幼童折扣百分比（PERCENT模式） - -#### ✏️ ProductSaveRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ ProductUpdateRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ ProductVO - - - 🆕 `youngChildCount` (`Integer`) — 小童人数 - - 🆕 `babyCount` (`Integer`) — 婴儿人数 - -#### ✏️ QuoteResultVO - - - 🆕 `totalYoungChildCost` (`BigDecimal`) — 小童总成本 - - 🆕 `totalYoungChildSellPrice` (`BigDecimal`) — 小童总售价 - - 🆕 `totalBabyCost` (`BigDecimal`) — 婴儿总成本 - - 🆕 `totalBabySellPrice` (`BigDecimal`) — 婴儿总售价 - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - - 🆕 `babyCost` (`BigDecimal`) — 婴儿固定成本 - - ✏️ `personType`: 说明 "人员类型：ADULT/CHILD" → "人员类型：ADULT/CHILD/YOUNG_CHILD/BABY" - -### 小程序聚合服务 - -#### ✏️ MpCreateOrderRequest - - - ✏️ `travelerType`: 说明 "出行人类型（ADULT/CHILD）" → "出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY）" - -#### ✏️ MpCustomProductDetailVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿价 - - 🆕 `childDiscountPercent` (`BigDecimal`) — 儿童折扣百分比 - - 🆕 `youngChildPriceMode` (`String`) — 小童定价模式: PERCENT/FIXED - - 🆕 `youngChildFixedPrice` (`BigDecimal`) — 小童固定价格 - - 🆕 `babyPriceMode` (`String`) — 幼童定价模式: PERCENT/FIXED - - 🆕 `babyDiscountPercent` (`BigDecimal`) — 幼童折扣百分比 - -#### ✏️ MpOrderDetailVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ MpOrderListItemVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ MpPriceCalendarDayVO - - - 🆕 `youngChildPrice` (`BigDecimal`) — 幼儿价格 - - 🆕 `babyPrice` (`BigDecimal`) — 婴儿价格 - -#### ✏️ MpProductQuoteRequest - - - 🆕 `youngChildCount` (`Integer`) — 幼儿数量 - - 🆕 `babyCount` (`Integer`) — 婴儿数量 - -#### ✏️ MpProductQuoteVO - - - 🆕 `youngChildSellPrice` (`BigDecimal`) — 小童单价（儿童价×折扣比例） - - 🆕 `babySellPrice` (`BigDecimal`) — 幼童单价（固定价） - - 🆕 `totalYoungChildSellPrice` (`BigDecimal`) — 小童小计 - - 🆕 `totalBabySellPrice` (`BigDecimal`) — 幼童小计 - -#### ✏️ MpTravelerRequest - - - ✏️ `travelerType`: 说明 "出行人类型: ADULT/CHILD" → "出行人类型: ADULT/CHILD/YOUNG_CHILD/BABY" - -#### ✏️ MpTravelerVO - - - ✏️ `travelerType`: 说明 "出行人类型: ADULT/CHILD" → "出行人类型: ADULT/CHILD/YOUNG_CHILD/BABY" - -### 订单服务 - -#### ✏️ AdminUpdateOrderRequest - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ MpOrderListVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ OrderDetailVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -#### ✏️ OrderListVO - - - 🆕 `youngChildCount` (`Integer`) — 小童数 - - 🆕 `babyCount` (`Integer`) — 幼童数 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpCreateOrderRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpProductQuoteRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/dto/MpTravelerRequest.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderListItemVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpPriceCalendarDayVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductQuoteVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpTravelerVO.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminCreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/CreateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/QuotePreviewRequest.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderInfo.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignFallbackFactory.java -M hl-order-service/src/main/java/com/hulalv/order/service/DashboardStatsService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderCascadeService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/TripService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/QuoteController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/FamilySaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/QuoteRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductFamily.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductPricing.java -M hl-product-service/src/main/java/com/hulalv/product/feign/InsuranceSchemeFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/feign/MaterialRefFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/feign/ReviewFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/service/CostCalculationService.java -M hl-product-service/src/main/java/com/hulalv/product/service/PriceCalendarService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductFamilyService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductPricingService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/QuoteCalculatorService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductFamilyVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/QuoteResultVO.java -A sql/young_child_baby_price_mode.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1556_a4283e60_fix_remark.md b/changelogs/2026-03/2026-03-31_1556_a4283e60_fix_remark.md deleted file mode 100644 index d7d5fed..0000000 --- a/changelogs/2026-03/2026-03-31_1556_a4283e60_fix_remark.md +++ /dev/null @@ -1,24 +0,0 @@ -# 接口变更记录 — 2026-03-31 15:56 - -> **提交** `a4283e60` · **作者** wx · **时间** 2026-03-31 15:56:03 +0800 -> -> fix: 字典接口返回增加remark字段，修复小程序无法获取年龄规则 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 用户服务 - -#### ✏️ DictVO - - - 🆕 `remark` (`String`) — 备注（扩展信息，如年龄规则JSON） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-user-service/src/main/java/com/hulalv/user/service/SysDictService.java -M hl-user-service/src/main/java/com/hulalv/user/vo/DictVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1712_f0e82ab9_fix_dict_all_rem.md b/changelogs/2026-03/2026-03-31_1712_f0e82ab9_fix_dict_all_rem.md deleted file mode 100644 index 4ff6f43..0000000 --- a/changelogs/2026-03/2026-03-31_1712_f0e82ab9_fix_dict_all_rem.md +++ /dev/null @@ -1,24 +0,0 @@ -# 接口变更记录 — 2026-03-31 17:12 - -> **提交** `f0e82ab9` · **作者** wx · **时间** 2026-03-31 17:12:07 +0800 -> -> fix: dict/all接口返回remark字段（年龄规则等扩展信息） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 用户服务 - -#### ✏️ DictVO - - - 🆕 `remark` (`String`) — 备注（扩展信息，如年龄规则JSON） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-user-service/src/main/java/com/hulalv/user/service/SysDictService.java -M hl-user-service/src/main/java/com/hulalv/user/vo/DictVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1727_d41d3a72_refactor.md b/changelogs/2026-03/2026-03-31_1727_d41d3a72_refactor.md deleted file mode 100644 index 6ec3625..0000000 --- a/changelogs/2026-03/2026-03-31_1727_d41d3a72_refactor.md +++ /dev/null @@ -1,38 +0,0 @@ -# 接口变更记录 — 2026-03-31 17:27 - -> **提交** `d41d3a72` · **作者** wx · **时间** 2026-03-31 17:27:12 +0800 -> -> refactor: 价格日历接口字段优化（price→adultPrice，4种人员类型命名统一） - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpPriceCalendarDayVO - - - 🆕 `childWithBedFee` (`BigDecimal`) — 儿童占床附加费 - - 🆕 `stock` (`Integer`) — 剩余库存 - - 🆕 `sold` (`Integer`) — 已售数量 - - 🆕 `status` (`Integer`) — 状态：1=可售，0=关闭 - - 🆕 `remark` (`String`) — 备注 - - ❌ ~~`available`~~ (`Boolean`) — 是否可预订 - - ✏️ `childPrice`: 说明 "儿童价格" → "儿童价格（占床）" - - ✏️ `youngChildPrice`: 说明 "幼儿价格" → "小童价格（不占床）" - - ✏️ `babyPrice`: 说明 "婴儿价格" → "幼童价格" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpPriceCalendarDayVO.java -M hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerTest.java -M hl-product-service/src/main/java/com/hulalv/product/service/PriceCalendarService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_1731_79fd9542_feat.md b/changelogs/2026-03/2026-03-31_1731_79fd9542_feat.md deleted file mode 100644 index 3be9650..0000000 --- a/changelogs/2026-03/2026-03-31_1731_79fd9542_feat.md +++ /dev/null @@ -1,46 +0,0 @@ -# 接口变更记录 — 2026-03-31 17:31 - -> **提交** `79fd9542` · **作者** wx · **时间** 2026-03-31 17:31:59 +0800 -> -> feat: 保险方案/合同方案删除和禁用增加产品引用校验 - -## 变更总览 - -- **产品服务** - - InternalProduct (+1) - ---- - -## 产品服务 - -### InternalProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】产品（Feign调用）」** - -### 🆕 `GET` /internal/product/scheme-in-use — 检查方案是否被活跃产品使用 - -> 内部服务间调用，供 order-service 删除/禁用保险方案或合同方案前校验。 - -**参数** - - - `schemeType` (`String`) — 查询参数 - - `schemeId` (`Long`) — 查询参数 - -**响应** `Result<List<String>>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service/src/main/java/com/hulalv/contract/service/ContractSchemeService.java -M hl-order-service/src/main/java/com/hulalv/insurance/service/InsuranceSchemeService.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignClient.java -M hl-order-service/src/main/java/com/hulalv/order/feign/ProductFeignFallbackFactory.java -M hl-order-service/src/test/java/com/hulalv/contract/service/ContractSchemeServiceTest.java -M hl-order-service/src/test/java/com/hulalv/insurance/service/InsuranceSchemeServiceTest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/test/java/com/hulalv/product/controller/InternalProductControllerTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/2026-03-31_2158_af19ec81_fix.md b/changelogs/2026-03/2026-03-31_2158_af19ec81_fix.md deleted file mode 100644 index 5fe681e..0000000 --- a/changelogs/2026-03/2026-03-31_2158_af19ec81_fix.md +++ /dev/null @@ -1,41 +0,0 @@ -# 接口变更记录 — 2026-03-31 21:58 - -> **提交** `af19ec81` · **作者** wx · **时间** 2026-03-31 21:58:35 +0800 -> -> fix: 景区/酒店详情缺审批字段 + 产品列表缺startPrice - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductListVO - - - 🆕 `startPrice` (`BigDecimal`) — 起步价：全款模式=最低售价，定金模式=最低定金额 - - 🆕 `startPriceLabel` (`String`) — 起步价标签：'起' 或 '定金起' - -### 资源服务 - -#### ✏️ HotelVO - - - 🆕 `approvalNo` (`String`) — 审批单号 - - 🆕 `pendingStatus` (`Integer`) — 待审批目标状态 - -#### ✏️ ScenicSpotVO - - - 🆕 `approvalNo` (`String`) — 审批编号（审批中时有值） - - 🆕 `pendingStatus` (`Integer`) — 待审批目标状态 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/vo/HotelVO.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/vo/ScenicSpotVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-03/20_0908_sync.md b/changelogs/2026-03/20_0908_sync.md deleted file mode 100644 index f0e6f97..0000000 --- a/changelogs/2026-03/20_0908_sync.md +++ /dev/null @@ -1,17 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-20 09:09 - -## ℹ️ 新增 (7) - -### 订单服务 - -**新增参数** - -- `GET /admin/order/list` 新增参数 `contactPhone` -- `GET /admin/order/list` 新增参数 `createTimeEnd` -- `GET /admin/order/list` 新增参数 `createTimeStart` -- `GET /admin/order/list` 新增参数 `customizerName` -- `GET /admin/order/list` 新增参数 `departureDateEnd` -- `GET /admin/order/list` 新增参数 `departureDateStart` -- `GET /admin/order/list` 新增参数 `mchId` diff --git a/changelogs/2026-03/20_1127_sync.md b/changelogs/2026-03/20_1127_sync.md deleted file mode 100644 index 7bb9481..0000000 --- a/changelogs/2026-03/20_1127_sync.md +++ /dev/null @@ -1,27 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-20 11:28 - -## ⚠️ Breaking Changes (1) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 订单服务 - -**字段类型变化** - -| 数据对象 | 字段 | 原类型 | 新类型 | -| --- | --- | --- | --- | -| `酒店分配请求` | `assignments` | `单项酒店分配[]` | `单天单家庭酒店分配[]` | - -## ℹ️ 新增 (2) - -### 订单服务 - -**新增接口** - -- 🆕 `POST /admin/order/{orderId}/hotel-assignment/preview` - -**新增参数** - -- `GET /admin/order/{orderId}/available-hotels` 新增参数 `dayIndex` diff --git a/changelogs/2026-03/23_1607_sync.md b/changelogs/2026-03/23_1607_sync.md deleted file mode 100644 index f09b80a..0000000 --- a/changelogs/2026-03/23_1607_sync.md +++ /dev/null @@ -1,13 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-23 16:08 - -## ℹ️ 新增 (1) - -### 字典变更 - -**新增字典项** - -| 字典 | 新增值 | 标签 | -| --- | --- | --- | -| `contract_status`（合同状态） | `PENDING_SIGN` | 待签署 | diff --git a/changelogs/2026-03/23_1902_sync.md b/changelogs/2026-03/23_1902_sync.md deleted file mode 100644 index 469abdb..0000000 --- a/changelogs/2026-03/23_1902_sync.md +++ /dev/null @@ -1,13 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-23 19:03 - -## ℹ️ 新增 (1) - -### 字典变更 - -**字典项标签修改** - -| 字典 | 值 | 原标签 | 新标签 | -| --- | --- | --- | --- | -| `order_process_status`（订单内部流程状态） | `PENDING_FINANCE` | 待核算 | 待确认清单 | diff --git a/changelogs/2026-03/24_1434_sync.md b/changelogs/2026-03/24_1434_sync.md deleted file mode 100644 index 05cd328..0000000 --- a/changelogs/2026-03/24_1434_sync.md +++ /dev/null @@ -1,15 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-24 14:35 - -## ℹ️ 新增 (5) - -### 字典变更 - -**新增字典类型** - -- 🆕 `customize_budget`（预算范围） -- 🆕 `customize_request_status`（定制请求状态） -- 🆕 `customize_request_type`（定制需求类型） -- 🆕 `invoice_status`（发票状态） -- 🆕 `travel_purpose`（旅游目的） diff --git a/changelogs/2026-03/24_1438_resource_status.md b/changelogs/2026-03/24_1438_resource_status.md deleted file mode 100644 index bd6aa11..0000000 --- a/changelogs/2026-03/24_1438_resource_status.md +++ /dev/null @@ -1,41 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-24 14:38 - -## ⚠️ 变更 - 资源管理状态简化 - -### 涉及模块（全部9个资源模块） - -景区、游玩项目、酒店（含房型）、车辆、额外服务、人员、餐厅、额外费用、备品 - -### 变更内容 - -**状态值从三态改为二态：** - -| 原状态 | 新状态 | -|--------|--------| -| 0=草稿 | 0=下架 | -| 1=上架 | 1=上架（不变） | -| 2=下架 | **已移除** | - -**简单说：去掉草稿概念，只剩上架/下架两个状态。** - -### 前端需要调整 - -1. **状态筛选下拉框**：去掉「草稿」选项，改为「下架(0)」和「上架(1)」 -2. **列表/详情状态标签**：`status=0` 显示「下架」（原来显示「草稿」），`status=1` 显示「上架」 -3. **不再需要 status=2**：如果之前有 `status=2` 的处理逻辑，可以删除 -4. **上下架操作按钮**：目标状态只传 `0`（下架）或 `1`（上架），不再传 `2` -5. **审批接口 targetStatus**：同上，只有 `0` 和 `1` - -### 受影响的接口（所有资源模块通用） - -- `GET /admin/{module}/list` — status 参数：`0=下架, 1=上架` -- `PUT /admin/{module}/{id}/status` — status 字段：`0=下架, 1=上架` -- `PUT /admin/{module}/batch/status` — status 字段同上 -- `POST /admin/{module}/{id}/submit-approval` — targetStatus：`0=下架, 1=上架` -- 创建/更新接口的 status 字段同上 - -### 说明 - -代码实际一直只用 0 和 1 两个值（STATUS_OFF=0, STATUS_ON=1），status=2 从未真正使用过。本次只是统一了 API 文档描述，使其与实际逻辑一致。**数据库无变更，不影响已有数据。** diff --git a/changelogs/2026-03/24_1745_sync.md b/changelogs/2026-03/24_1745_sync.md deleted file mode 100644 index ddaf0b4..0000000 --- a/changelogs/2026-03/24_1745_sync.md +++ /dev/null @@ -1,60 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-24 17:46 - -## ⚠️ Breaking Changes (6) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 订单服务 - -**字段删除** - -| 数据对象 | 删除字段 | 原类型 | -| --- | --- | --- | -| `退款政策VO` | ~~`isDefault`~~ | `boolean` | -| `退款政策VO` | ~~`refundType`~~ | `string` | -| `退款政策请求` | ~~`isDefault`~~ | `boolean` | -| `退款政策请求` | ~~`refundType`~~ | `string` | - -**字段类型变化** - -| 数据对象 | 字段 | 原类型 | 新类型 | -| --- | --- | --- | --- | -| `OrderTraveler` | `gender` | `integer(int32)` | `string` | -| `出行人信息` | `gender` | `integer(int32)` | `string` | - -## ℹ️ 新增 (23) - -### 订单服务 - -**新增接口** - -- 🆕 `DELETE /admin/order/{orderId}/surcharge/{surchargeId}` -- 🆕 `GET /admin/order/{orderId}/travelers` -- 🆕 `POST /admin/order/{orderId}/surcharge` -- 🆕 `PUT /admin/order/{orderId}/surcharge/{surchargeId}` - -**新增字段** - -| 数据对象 | 新增字段 | 类型 | -| --- | --- | --- | -| `OrderTimeline` | `actionLabel` | `string` | -| `OrderTimeline` | `operatorTypeLabel` | `string` | -| `OrderTodo` | `assigneeRoleLabel` | `string` | -| `OrderTodo` | `todoTypeLabel` | `string` | -| `OrderTraveler` | `idCardTypeLabel` | `string` | -| `OrderTraveler` | `insurancePolicies` | `Map«string,object»[]` | -| `OrderTraveler` | `travelerTypeLabel` | `string` | -| `管理员修改订单请求` | `customizerId` | `integer(int64)` | -| `管理员订单列表VO` | `checklistConfirmed` | `boolean` | -| `管理员订单列表VO` | `mchName` | `string` | -| `管理员订单列表VO` | `surchargeAmount` | `number` | -| `订单详情VO` | `hotelAssignmentDetails` | `酒店分配详情（按家庭分组）[]` | -| `订单详情VO` | `mchName` | `string` | -| `订单详情VO` | `paymentModeLabel` | `string` | -| `订单详情VO` | `pendingUpgradeAmount` | `number` | -| `订单详情VO` | `productTypeLabel` | `string` | -| `订单详情VO` | `refundPolicy` | `退款政策VO` | -| `订单详情VO` | `surchargeAmount` | `number` | -| `订单详情VO` | `surcharges` | `OrderSurcharge[]` | diff --git a/changelogs/2026-03/25_1212_resource_status_approval.md b/changelogs/2026-03/25_1212_resource_status_approval.md deleted file mode 100644 index f6d82e0..0000000 --- a/changelogs/2026-03/25_1212_resource_status_approval.md +++ /dev/null @@ -1,124 +0,0 @@ -# 资源状态切换：非超管需走审批流程 - -**日期**: 2026-03-25 -**服务**: hl-resource-service -**影响范围**: 所有资源模块（景区、酒店、餐厅、活动、车辆、物资、费用项、服务项、人员）的状态切换开关 - ---- - -## 背景说明 - -当前前端资源列表页的状态 toggle 开关，直接调用了 `PUT /{resource}/{id}/status` 接口。该接口仅限 SUPER_ADMIN 使用，非超管用户操作时会报错 **"仅超级管理员可直接修改状态"**。 - -**后端已有完整的审批接口**，前端需根据用户角色分别调用不同接口： - -| 用户角色 | 行为 | 调用接口 | -|---------|------|---------| -| SUPER_ADMIN | 直接生效 | `PUT /{resource}/{id}/status` | -| 其他角色 | 提交审批 | `POST /{resource}/{id}/submit-approval` | - ---- - -## 各资源审批接口清单 - -| # | 资源 | 审批接口路径 | 方法 | -|---|------|-------------|------| -| 1 | 景区 | `/admin/scenic/spot/{scenicId}/submit-approval` | POST | -| 2 | 酒店 | `/admin/hotel/item/{hotelId}/submit-approval` | POST | -| 3 | 房型 | `/admin/hotel/room-type/{roomTypeId}/submit-approval` | POST | -| 4 | 餐厅 | `/admin/restaurant/item/{restaurantId}/submit-approval` | POST | -| 5 | 活动 | `/admin/activity/item/{activityId}/submit-approval` | POST | -| 6 | 车辆 | `/admin/vehicle/model/{vehicleId}/submit-approval` | POST | -| 7 | 物资 | `/admin/supplies/item/{suppliesId}/submit-approval` | POST | -| 8 | 费用项 | `/admin/cost/item/{costId}/submit-approval` | POST | -| 9 | 服务项 | `/admin/service/item/{serviceId}/submit-approval` | POST | -| 10 | 人员 | `/admin/staff/{staffId}/submit-approval` | POST | - ---- - -## 审批接口详细定义 - -### 使用场景 - -非超管用户在资源列表页点击状态 toggle 时，弹出确认框让用户填写审批理由，然后调用此接口提交企微OA审批。审批通过后状态自动变更。 - -### 请求参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| targetStatus | Integer | 是 | 目标状态：`0`=下架，`1`=上架 | -| reason | String | 是 | 审批理由，不能为空 | - -### 请求示例 - -```json -POST /admin/scenic/spot/123456/submit-approval - -{ - "targetStatus": 1, - "reason": "内容审核完毕，申请上架" -} -``` - -### 响应示例 - -**成功（200）**： -```json -{ - "code": 200, - "message": "success", - "data": { - "spNo": "202603250001" - } -} -``` - -**失败 - 已有审批进行中**： -```json -{ - "code": 400, - "message": "该资源已有审批进行中，请等待审批结果" -} -``` - ---- - -## 前端实现建议 - -``` -状态 Toggle 开关被点击 - │ - ├─ 当前角色 = SUPER_ADMIN ? - │ ├─ 是 → 直接调 PUT /{resource}/{id}/status（现有逻辑不变） - │ └─ 否 ↓ - │ - ├─ 弹出确认框 - │ ┌──────────────────────────────┐ - │ │ 申请 [上架/下架] │ - │ │ │ - │ │ 审批理由： │ - │ │ ┌──────────────────────┐ │ - │ │ │ (textarea) │ │ - │ │ └──────────────────────┘ │ - │ │ │ - │ │ [取消] [提交审批] │ - │ └──────────────────────────────┘ - │ - └─ 调 POST /{resource}/{id}/submit-approval - │ - ├─ 成功 → 提示 "审批已提交，请等待审批结果" - │ toggle 恢复原状态（审批未通过前不变） - └─ 失败 → 提示错误信息，toggle 恢复原状态 -``` - -### 角色判断 - -用户角色已存储在登录 token 中（`X-Admin-Role` header），前端可从本地存储中获取 `role` 字段判断是否为 `SUPER_ADMIN`。 - ---- - -## 注意事项 - -1. **审批期间 toggle 状态不变**：提交审批后资源进入 `PENDING_APPROVAL` 状态，但显示状态不变，等审批通过后自动切换 -2. **不可重复提交**：同一资源有未完成的审批时，再次提交会返回 400 错误 -3. **所有资源模块统一逻辑**：景区、酒店、餐厅、活动等全部适用，前端可封装通用组件 diff --git a/changelogs/2026-03/26_0905_xmm_detail_fields.md b/changelogs/2026-03/26_0905_xmm_detail_fields.md deleted file mode 100644 index 8f966a5..0000000 --- a/changelogs/2026-03/26_0905_xmm_detail_fields.md +++ /dev/null @@ -1,316 +0,0 @@ -# 小蒙马详情页字段补全 + 产品接口优化 - -**日期**: 2026-03-26 -**服务**: hl-product-service -**环境**: 测试环境已部署，需重启: product-service - ---- - -## 一、小蒙马(GROUP)详情页新增字段 - -产品详情接口 `GET /product/{productId}` 和小程序 `GET /internal/mp/product/{productId}` 新增以下字段： - -### 1. 数据统计（自动计算，无需配置） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `batchCount` | Integer | 历史期数（非散团状态的批次数，仅GROUP产品） | -| `hotelSummary` | Array | 住宿安排汇总（连住合并，仅显示连住2晚及以上，仅GROUP产品） | - -`hotelSummary` 每项结构（连续住同一酒店自动合并）： -```json -{ - "dayStart": 3, - "dayEnd": 4, - "hotelId": "3001000000000000005", - "hotelName": "兰其果娃", - "coverUrl": "https://xxx/hotel.jpg", - "roomTypeName": "亲子房", - "nights": 2, - "label": "连住2晚" -} -``` - -**注意**：只住1晚的酒店不会出现在 `hotelSummary` 中（设计图只展示连住）。前端可直接用 `label` 字段显示标签，用 `dayStart`-`dayEnd` 显示日期范围（如 "Day3-4"）。 - -### 2. 年龄说明（后台可配） - -| 字段 | 类型 | 说明 | 示例 | -|------|------|------|------| -| `ageMin` | Integer | 适合最小年龄 | `5` | -| `ageMax` | Integer | 适合最大年龄 | `12` | -| `ageDescription` | String | 年龄说明文案 | `"5-12岁儿童专属，课程按年龄分组"` | - -### 3. 摄影跟拍（后台可配） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `photographyTags` | String[] | 摄影标签 如 `["200+精修照片", "1对1跟拍"]` | -| `photographyImages` | String[] | 摄影作品展示图URL列表 | - -### 4. 餐饮亮点（后台可配） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `diningHighlights` | Array | 餐饮亮点列表 | - -每项结构： -```json -{ - "name": "手把肉", - "coverImage": "https://xxx/cover.jpg", - "subtitle": "蒙古特色必吃", - "detailImages": ["https://xxx/detail1.jpg", "https://xxx/detail2.jpg"] -} -``` -- `coverImage`: 封面图（列表展示，name叠在图上） -- `detailImages`: 详情图列表（点击查看大图） - -### 5. 安全保障（后台可配） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `safetyItems` | Array | 安全保障列表 | - -每项结构： -```json -{ "icon": "insurance", "title": "保险", "description": "中国人保50万，含意外医疗" } -``` - -### 6. 价格档位表（自动计算，无需配置） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `priceTiers` | Array | 价格档位列表（从套餐combo自动取每种组合的最低售价，仅GROUP产品） | - -每项结构： -```json -{ "label": "1大1小", "price": 12800, "adultCount": 1, "childCount": 1 } -``` - -**数据来源**：自动从产品的套餐（GroupBatchCombo）中按 comboCode 分组，取每组跨所有批次的最低 sellPrice。无需后台手动配置。 - ---- - -## 二、推荐餐厅封面图自动补全 - -行程节点中 `DINING_RECOMMEND` 类型的 `recommendedRestaurants` 列表，`coverUrl` 现在会自动从餐厅资源中补全。前端无需改动，原有字段结构不变。 - ---- - -## 三、上架校验优化 - -- 移除了上架时商户号（mchId）的强制校验，不再报"商户号不能为空" -- GROUP（小蒙马）产品上架新增校验：**至少需要1个可报名的团期**（状态为报名中/已确认，且出发日期在未来）。不满足会提示具体原因 - ---- - -## 四、产品人员配置增加备选人员 - -人员配置接口 `POST /product/{productId}/staff-config` 和 `PUT /product/staff-config/{id}` 新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `staffIds` | String[] | 备选人员ID列表（从人员资源中选取） | - -- 数量（quantity）是出行时实际需要的人数，备选人员可以多于此数量 -- 团期创建时从备选池中选人分配 - -### 领队介绍（自动填充，仅GROUP产品） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `leaderInfoList` | Array | 领队详情列表（从人员配置中LEADER类型的staffIds查询） | - -每项结构： -```json -{ - "staffId": "123", - "name": "巴特尔老师", - "avatar": "https://xxx/avatar.jpg", - "title": "首席研学导师 · 蒙古族", - "experience": "10年儿童户外教育经验", - "description": "...", - "certificateTags": ["急救证书", "导游证", "教师资格证"] -} -``` -前端可滚动展示多个领队。 - -### 人员资源新增字段 - -人员资源 `POST /staff` 和 `PUT /staff/{id}` 新增： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `certificateTags` | String[] | 证书标签，如 `["急救证书", "导游证"]` | - ---- - -## 五、预订须知（所有产品类型通用） - -小程序产品详情已返回以下字段（点击展开纯文字内容）： - -| 字段 | 位置 | 说明 | -|------|------|------| -| `product.bookingTermsContent` | ProductVO | 预订条款全文 | -| `product.warmTipsContent` | ProductVO | 温馨提示全文 | -| `refundPolicies` | MpProductDetailVO | 取消政策（按支付方式分组） | - -### 取消政策（退款政策）返回结构 - -`refundPolicies` 按支付方式分组，每个政策新增 `description` 纯文字字段： - -```json -{ - "FULL": { - "policyId": 1, - "policyName": "标准退款政策", - "description": "出发前30天以上取消，退全款；出发前15-30天取消，退80%；出发前15天内取消，不可退", - "rules": [ - { "ruleId": 1, "minDays": 30, "refundRatio": 100 }, - { "ruleId": 2, "minDays": 15, "refundRatio": 80 }, - { "ruleId": 3, "minDays": 0, "refundRatio": 0 } - ] - }, - "DEPOSIT": { ... } -} -``` - -前端可直接用 `description` 展示文字，无需自己拼接规则。按产品的 `pricing.paymentType` 显示对应的退款政策： -- `FULL` → 显示 FULL 的 description -- `DEPOSIT` → 显示 DEPOSIT 和 BALANCE 的 description - ---- - -## 前端对接要点 - -1. **batchCount / hotelSummary / priceTiers / leaderInfoList**: 自动计算字段，无需后台录入，GROUP产品详情自动返回 -2. **年龄/摄影/餐饮/安全**: 需要在管理后台"编辑产品"时配置对应数据，否则返回 null -3. **所有新字段向后兼容**: 未配置时返回 null，不影响已有字段 -4. **保存/更新产品接口同步支持**: `POST /product/save`、`PUT /product/{id}` 都可传入新字段 - ---- - -## 六、人员管理校验增强 - -**服务**: hl-resource-service - -创建/更新人员时，如果填写了 `certificateTags`（证书标签），则 `certificateUrls`（证书文件）不能为空。否则报错： - -> 添加了证书标签，必须同时上传对应的证书文件 - -前端在提交人员表单时，如果用户添加了证书标签但没上传证书文件，建议在前端也做提示拦截。 - ---- - -## 七、人员证书改为结构化列表 - -**服务**: hl-resource-service - -### 新增字段 `certificates`（替代旧的 certificateTags + certificateUrls） - -人员创建/更新接口新增 `certificates` 字段，标签和附件一一对应： - -```json -[ - { "tag": "急救证书", "url": "https://xxx/cert1.jpg" }, - { "tag": "导游证", "url": "https://xxx/cert2.jpg" }, - { "tag": "教师资格证", "url": "https://xxx/cert3.jpg" } -] -``` - -**校验规则**：每项的 `tag` 和 `url` 必须同时存在，缺一报错（如"第1个证书'急救证书'缺少证书附件"）。 - -**兼容**：旧字段 `certificateUrls` / `certificateTags` 保留可用，但建议前端迁移到 `certificates`。 - -**领队介绍**：小程序详情 `leaderInfoList` 中的 `certificateTags` 优先从 `certificates` 提取，同时也返回完整的 `certificates` 列表。 - ---- - -## 八、安全保障改为模板机制 - -**服务**: hl-product-service - -### 模板管理接口 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/product/safety-template` | 模板列表 | -| GET | `/product/safety-template/{id}` | 模板详情 | -| POST | `/product/safety-template` | 创建模板 | -| PUT | `/product/safety-template/{id}` | 更新模板 | -| DELETE | `/product/safety-template/{id}` | 删除模板（默认模板不可删） | - -请求体： -```json -{ - "name": "标准安全保障", - "items": [ - { "icon": "insurance", "title": "保险", "description": "中国人保50万，含意外医疗" }, - { "icon": "vehicle", "title": "车辆", "description": "营运资质、儿童安全座椅、司机驾龄10年" }, - { "icon": "emergency", "title": "应急", "description": "24h客服，医院30分钟可达" } - ], - "isDefault": true -} -``` - -### 产品关联 - -产品保存/更新时可传 `safetyTemplateId` 指定模板。**不传则自动使用默认模板**，定制师无需手动配置。 - -### 详情返回逻辑 - -`safetyItems` 字段填充优先级：产品指定模板 → 产品自身旧数据 → 默认模板。前端无需改动，`safetyItems` 返回格式不变。 - -系统已内置默认模板"标准安全保障"（保险/车辆/应急三项）。 - ---- - -## 九、价格档位改为最近一期可报名团期价格 - -**服务**: hl-product-service - -`priceTiers` 不再取所有团期的最低价，改为只取**最近一期可报名团期**（ENROLLING/CONFIRMED 且出发日期在未来）的 combo 价格。 - -返回格式不变： -```json -[ - { "label": "1大1小", "price": 12800, "adultCount": 1, "childCount": 1 }, - { "label": "1大2小", "price": 15800, "adultCount": 1, "childCount": 2 } -] -``` - -如果没有可报名团期，`priceTiers` 返回 null。 - ---- - -## 十、人员证书上传说明 - -**上传流程**：使用通用文件上传接口，和上传其他图片一样。 - -**步骤**： -1. `POST /file/upload/token` → 获取预签名URL -```json -{ "fileName": "急救证书.jpg", "bizType": "staff" } -``` -2. 用返回的预签名URL上传文件到OSS -3. `POST /file/upload/confirm` → 确认上传，拿到最终URL -4. 将URL填入 `certificates[].url` - -**保存人员时传 certificates 字段**： -```json -{ - "certificates": [ - { "tag": "急救证书", "url": "https://xxx/cert1.jpg" }, - { "tag": "导游证", "url": "https://xxx/cert2.jpg" } - ] -} -``` - -每项 `tag` 和 `url` 必须同时填，缺一报错。旧字段 `certificateTags`/`certificateUrls` 仍可用但建议迁移。 - ---- - -## 补充：行程酒店封面图自动补全 - -行程天的酒店（`itineraryDays[].hotels[].coverUrl`）如果为空，后端会自动从酒店资源的封面素材中补全。前端无需改动。 diff --git a/changelogs/2026-03/26_1109_order_list_perf.md b/changelogs/2026-03/26_1109_order_list_perf.md deleted file mode 100644 index 1b32b8f..0000000 --- a/changelogs/2026-03/26_1109_order_list_perf.md +++ /dev/null @@ -1,19 +0,0 @@ -# 小程序订单列表性能优化 - -**日期**: 2026-03-26 -**服务**: hl-order-service -**类型**: 性能优化（BUG修复） - -## 变更内容 - -小程序订单列表接口（`GET /internal/mp/order/list`）性能优化，响应时间从 ~3秒 降到 ~1秒以内。 - -## 影响范围 - -- **接口**: `GET /api/mp/order/list` -- **返回结构不变**，无需前端修改 -- 纯后端性能优化 - -## 需要操作 - -重启 **hl-order-service** diff --git a/changelogs/2026-03/26_1200_group_code.md b/changelogs/2026-03/26_1200_group_code.md deleted file mode 100644 index 90b2acf..0000000 --- a/changelogs/2026-03/26_1200_group_code.md +++ /dev/null @@ -1,27 +0,0 @@ -# 订单新增4位团号(groupCode) - -**日期**: 2026-03-26 -**服务**: hl-order-service - ---- - -## 新增字段 - -订单列表和详情接口新增 `groupCode` 字段： - -| 字段 | 类型 | 说明 | 示例 | -|------|------|------|------| -| `groupCode` | String(4) | 4位团号，司机/酒店沟通用 | `"9854"` | - -**返回位置**： -- `GET /mp/order/list` → `MpOrderListVO.groupCode` -- `GET /mp/order/{id}` → `MpOrderDetailVO.groupCode`（通过product字段） -- `GET /admin/order/list` → `OrderListVO.groupCode` -- `GET /admin/order/{id}` → `OrderDetailVO.groupCode` - -**生成规则**： -- 4位数字，年度内唯一且不连续（LCG混淆算法） -- 每年1月1日序号重置 -- 创建订单时自动生成，无需前端传参 - -**用途**：司机和酒店之间快速交流的短编号，比完整订单号更方便口头沟通。 diff --git a/changelogs/2026-03/26_1230_product_group_chat.md b/changelogs/2026-03/26_1230_product_group_chat.md deleted file mode 100644 index 4f512ba..0000000 --- a/changelogs/2026-03/26_1230_product_group_chat.md +++ /dev/null @@ -1,29 +0,0 @@ -# 核心产品编辑缺少群聊配置入口 - -**日期**: 2026-03-26 -**类型**: 前端BUG - ---- - -## 问题 - -管理后台设计核心产品时，没有设置群聊相关信息的地方。 - -## 后端已有字段 - -产品保存/更新接口 `POST /admin/product/save`、`PUT /admin/product/{id}` 已支持以下字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `groupChatQrUrl` | String | 群聊二维码URL（小程序展示给用户扫码入群） | -| `groupRoomId` | String | 企微群聊ID（用于会话存档展示实时群消息） | -| `showChatGroup` | Boolean | 是否在小程序显示群聊入口 | - -## 前端需要做 - -在产品编辑表单中增加"群聊设置"区域： -1. **群聊二维码**：图片上传控件 → 存入 `groupChatQrUrl` -2. **企微群聊ID**：文本输入框 → 存入 `groupRoomId` -3. **显示群聊入口**：开关 → 存入 `showChatGroup` - -这三个字段后端已经完整支持读写，只需前端加表单控件。 diff --git a/changelogs/2026-03/26_1300_hotel_phones.md b/changelogs/2026-03/26_1300_hotel_phones.md deleted file mode 100644 index e46c91f..0000000 --- a/changelogs/2026-03/26_1300_hotel_phones.md +++ /dev/null @@ -1,22 +0,0 @@ -# 酒店管理新增销售电话和合房电话 - -**日期**: 2026-03-26 -**服务**: hl-resource-service - ---- - -## 新增字段 - -酒店创建/更新/详情接口新增两个电话字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `salesPhone` | String(20) | 酒店销售电话 | -| `roomSharePhone` | String(20) | 酒店合房电话 | - -**接口**： -- `POST /admin/hotel` 创建酒店 -- `PUT /admin/hotel/{id}` 更新酒店 -- `GET /admin/hotel/{id}` 详情返回 - -前端在酒店编辑表单的联系方式区域，在现有"联系人"和"联系电话"下方增加"销售电话"和"合房电话"两个输入框。 diff --git a/changelogs/2026-03/26_1330_safety_item_crud.md b/changelogs/2026-03/26_1330_safety_item_crud.md deleted file mode 100644 index 34f835e..0000000 --- a/changelogs/2026-03/26_1330_safety_item_crud.md +++ /dev/null @@ -1,81 +0,0 @@ -# 安全保障改为逐条管理（废弃模板机制） - -**日期**: 2026-03-26 -**服务**: hl-product-service - ---- - -## 变更说明 - -安全保障从模板选择改为**逐条增删**，和"费用不包含"一样的操作方式。 - -**废弃**：`/admin/product/safety-template` 模板接口不再使用。 - -## 新增接口 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/{productId}/safety-item` | 列表 | -| POST | `/admin/product/{productId}/safety-item` | 添加 | -| PUT | `/admin/product/{productId}/safety-item/{id}` | 更新 | -| DELETE | `/admin/product/{productId}/safety-item/{id}` | 删除 | - -**请求体**： -```json -{ - "category": "INSURANCE", - "name": "保险", - "description": "中国人保50万，含意外医疗", - "icon": "insurance", - "sortOrder": 1 -} -``` - -## 字典 - -`dict_type = safety_category`（快捷添加用）： - -| dict_value | dict_label | remark（默认描述） | -|------------|------------|-------------------| -| INSURANCE | 保险 | 中国人保50万，含意外医疗 | -| VEHICLE | 车辆 | 营运资质、儿童安全座椅、司机驾龄10年 | -| EMERGENCY | 应急 | 24h客服，医院30分钟可达 | - -## 前端改造 - -产品编辑的"安全保障"区域改为： -1. 顶部快捷按钮从字典 `safety_category` 读取 -2. 点击快捷按钮 → 自动填入 category/name/description → 调 POST 添加 -3. 已添加列表支持编辑描述、调整排序、删除 -4. 去掉模板选择下拉框 - -## 小程序端 - -`safetyItems` 返回格式不变，前端无需改动： -```json -[ - { "icon": "insurance", "title": "保险", "description": "中国人保50万，含意外医疗" } -] -``` - ---- - -## 补充：快捷添加字典 - -字典类型：`safety_category` - -接口：`GET /admin/dict/data/type/safety_category` - -返回数据： - -| dict_value | dict_label | remark | -|------------|------------|--------| -| INSURANCE | 保险 | 中国人保50万，含意外医疗 | -| VEHICLE | 车辆 | 营运资质、儿童安全座椅、司机驾龄10年 | -| EMERGENCY | 应急 | 24h客服，医院30分钟可达 | - -快捷按钮点击时映射： -- `category` ← `dict_value` -- `name` ← `dict_label` -- `description` ← `remark`（默认值，用户可修改） -- `icon` ← `dict_value` 小写（如 `insurance`） diff --git a/changelogs/2026-03/26_1400_staff_config_name.md b/changelogs/2026-03/26_1400_staff_config_name.md deleted file mode 100644 index a170b4c..0000000 --- a/changelogs/2026-03/26_1400_staff_config_name.md +++ /dev/null @@ -1,26 +0,0 @@ -# 人员配置备选人员回显姓名 - -**日期**: 2026-03-26 - ---- - -## 问题 - -编辑人员配置弹窗中，备选人员显示的是 ID（如 1001、1002），应显示人员姓名。 - -## 接口 - -**批量查人员简要信息**：`GET /admin/staff/batch-basic?staffIds=1001,1002` - -返回： -```json -[ - { "staffId": "1001", "name": "巴特尔", "staffType": "GUIDE", "phone": "138xxx" }, - { "staffId": "1002", "name": "王骁", "staffType": "LEADER", "phone": "139xxx" } -] -``` - -## 前端改造 - -1. **回显姓名**：打开编辑弹窗时，根据 `staffIds` 调 `GET /admin/staff/batch-basic?staffIds=1001,1002` 查名字 -2. **选择人员**：调 `GET /admin/staff/list?staffType=GUIDE&status=1` 获取可选人员列表，用下拉多选 diff --git a/changelogs/2026-03/26_1430_transport_and_balance.md b/changelogs/2026-03/26_1430_transport_and_balance.md deleted file mode 100644 index d2deedf..0000000 --- a/changelogs/2026-03/26_1430_transport_and_balance.md +++ /dev/null @@ -1,56 +0,0 @@ -# 收尾款不再改状态 + 交通信息填写入口 - -**日期**: 2026-03-26 -**服务**: hl-order-service - ---- - -## 一、收取尾款不再改变订单状态 - -**修复**：收取尾款后保持当前状态不变（可能在待付尾款/待出行/行程中任一状态收取）。之前会强制变为"待出行"，现已移除。 - ---- - -## 二、交通信息（航班/车次）填写 - -订单详情"行程安排"tab 中的"交通信息"区域显示"暂无交通信息"，需要前端加"添加交通信息"按钮。 - -**后端接口已有**： - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/order/{orderId}/transport` | 添加 | -| PUT | `/admin/order/transport/{transportId}` | 编辑 | -| DELETE | `/admin/order/transport/{transportId}` | 删除 | -| GET | `/admin/order/{orderId}/transports` | 查询（含实时航班动态） | - -**添加请求体**： -```json -{ - "legType": "OUTBOUND", - "transportType": "FLIGHT", - "transportNo": "CA1234", - "departureStation": "上海浦东国际机场", - "arrivalStation": "海拉尔东山机场", - "travelDate": "2026-07-15", - "remark": "T2航站楼" -} -``` - -**字典**： -- `legType`: OUTBOUND=去程接站, RETURN=回程送站 -- `transportType`: FLIGHT=航班, TRAIN=火车 - -**前端需要做**：在"交通信息"区域加"添加交通信息"按钮，弹窗表单包含：行程段（去程/回程）、交通类型（航班/火车）、航班号/车次、出发站、到达站、日期、备注。 - ---- - -## 三、交通信息编辑状态补充 - -**待出行**和**旅行中**状态下，交通信息（接送站）都可以增删改。后端接口无状态限制。 - -前端在订单详情"行程安排"tab 的"交通信息（接送站）"区域，在待出行/旅行中状态下都要显示"添加"按钮和编辑/删除操作。 - -注意区分两个区域： -- **交通信息**：来自产品行程节点，只读展示 -- **交通信息（接送站）**：订单级别，可编辑，用 `/admin/order/{orderId}/transport` 接口 diff --git a/changelogs/2026-03/26_1500_pdf_preview.md b/changelogs/2026-03/26_1500_pdf_preview.md deleted file mode 100644 index 73e4883..0000000 --- a/changelogs/2026-03/26_1500_pdf_preview.md +++ /dev/null @@ -1,30 +0,0 @@ -# 保单PDF预览变成下载的问题 - -**日期**: 2026-03-26 -**类型**: 前端BUG - ---- - -## 问题 - -保单PDF预览弹窗显示"该文件类型暂不支持在线预览"，点击后变成下载。 - -## 原因 - -前端通过 `/admin/file/preview-by-url` 代理预览，dev server 代理可能丢失了 `Content-Type: application/pdf` 和 `Content-Disposition: inline` 响应头。 - -## 解决方案 - -**推荐**：保单PDF已有公网可直接访问的OSS链接（`policyPdfUrl` 字段），前端直接用这个URL预览，不需要经过后端代理： - -```js -// 方案1：新窗口打开（最简单） -window.open(record.policyPdfUrl) - -// 方案2：iframe嵌入弹窗 -<iframe :src="record.policyPdfUrl" style="width:100%;height:80vh" /> -``` - -`policyPdfUrl` 在保险订单详情 `GET /admin/insurance/order/{id}` 和订单详情的 `insurances` 列表中都有返回。 - -如果坚持用 `/admin/file/preview-by-url`，检查前端 dev server 代理配置是否正确转发了 response headers。 diff --git a/changelogs/2026-03/26_1530_price_tiers_readonly.md b/changelogs/2026-03/26_1530_price_tiers_readonly.md deleted file mode 100644 index 2a0837a..0000000 --- a/changelogs/2026-03/26_1530_price_tiers_readonly.md +++ /dev/null @@ -1,109 +0,0 @@ -# 价格档位是自动计算字段，前端不需要手动输入 - -**日期**: 2026-03-26 -**类型**: 前端BUG - ---- - -## 问题 - -产品编辑页出现了"价格档位"手动输入表单（档位名称+价格），这个不应该存在。 - -## 正确逻辑 - -`priceTiers` 是**后端自动计算**的只读字段，数据来源： - -1. 管理端在**团期管理**中配置套餐组合（combo），如"1大1小 ¥12800"、"2大1小 ¥18800" -2. 后端自动取**最近一期可报名团期**的 combo 价格返回给小程序 -3. 前端产品编辑页**不需要**价格档位的输入表单 - -## 前端需要做 - -- **删除**产品编辑页的"价格档位"输入区域 -- 价格档位通过团期管理中的套餐（combo）配置，不在产品基本信息中配置 - ---- - -## 补充：组合在哪里配置 - -人员组合（1大1小、2大1小等）和价格在**团期的套餐管理**中配置： - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/group-batch/{batchId}/combos` | 查看团期套餐列表 | -| POST | `/admin/product/group-batch/{batchId}/combo` | 添加套餐 | -| PUT | `/admin/product/group-batch/combo/{comboId}` | 编辑套餐 | -| DELETE | `/admin/product/group-batch/combo/{comboId}` | 删除套餐 | - -**套餐请求体**： -```json -{ - "comboName": "1大1小", - "comboCode": "1A1C", - "adultCount": 1, - "childCount": 1, - "sellPrice": 12800, - "stock": 20 -} -``` - -**流程**：团期管理 → 选择团期 → 配置套餐组合和价格 → 小程序详情页自动取最近可报名团期的套餐展示 - -产品编辑页的"价格档位"输入框应该去掉，改为提示"价格档位由团期套餐自动生成"。 - ---- - -## 更正：产品级别配置组合，价格后端自动算 - -### 管理端输入 - -产品编辑时配置 `priceTierLabels`（只输组合名称和人数，不输价格）： - -```json -[ - { "label": "1大1小", "adultCount": 1, "childCount": 1 }, - { "label": "1大2小", "adultCount": 1, "childCount": 2 }, - { "label": "2大1小", "adultCount": 2, "childCount": 1 } -] -``` - -通过 `POST /admin/product/save` 或 `PUT /admin/product/{id}` 的 `priceTierLabels` 字段保存。 - -### 小程序展示 - -`priceTiers` 后端根据组合定义，匹配所有可报名团期 combo 的最低售价自动填入 `price`： - -```json -[ - { "label": "1大1小", "adultCount": 1, "childCount": 1, "price": 12800 }, - { "label": "1大2小", "adultCount": 1, "childCount": 2, "price": 15800 }, - { "label": "2大1小", "adultCount": 2, "childCount": 1, "price": 18800 } -] -``` - -### 前端改造 - -产品编辑页的"价格档位"表单改为： -- 输入：档位名称（如"1大1小"）+ 成人数 + 儿童数 -- **不输入价格**（价格由后端从团期combo自动算） -- 回显用 `priceTierLabels` 字段 - ---- - -## 补充：价格档位保存方式 - -价格档位没有独立的保存接口，跟产品一起保存。 - -前端在价格档位区域加个"保存"按钮，点击时调 `POST /admin/product/save`（或 `PUT /admin/product/{id}`），body 中带 `priceTierLabels` 字段： - -```json -{ - "productId": "xxx", - "priceTierLabels": [ - { "label": "1大1小", "adultCount": 1, "childCount": 1 }, - { "label": "2大1小", "adultCount": 2, "childCount": 1 } - ] -} -``` - -和产品其他字段一起提交即可，不需要单独接口。 diff --git a/changelogs/2026-03/26_1600_activity_remove_base_price.md b/changelogs/2026-03/26_1600_activity_remove_base_price.md deleted file mode 100644 index 12163ad..0000000 --- a/changelogs/2026-03/26_1600_activity_remove_base_price.md +++ /dev/null @@ -1,26 +0,0 @@ -# 游玩项目编辑——移除"成本价"和"计费方式"字段 - -**日期**: 2026-03-26 -**类型**: 前端UI调整 -**涉及页面**: 资源管理 → 游玩项目管理 → 编辑/新增弹窗 - ---- - -## 变更说明 - -游玩项目（Activity）编辑表单需移除两个字段： - -1. **成本价**（`basePrice`）— 价格统一在价格日历中管理 -2. **计费方式**（`billingType`）— 不再需要前端选择 - -## 前端需要做的 - -1. **编辑弹窗**：移除"成本价"输入框和"计费方式"下拉框 -2. **新增弹窗**：同样移除这两个字段 -3. 提交请求时不再传 `basePrice` 和 `billingType` 字段（后端会忽略） - -## 说明 - -- 后端 API 不变，这两个字段仍存在于接口中但不再使用 -- 所有活动的成本价格通过 **价格日历**（`activity_price_calendar`）按日期管理 -- 与景区、酒店、车型等资源一致：价格统一走价格日历 diff --git a/changelogs/2026-03/26_1600_batch_staff_candidate.md b/changelogs/2026-03/26_1600_batch_staff_candidate.md deleted file mode 100644 index 6965c49..0000000 --- a/changelogs/2026-03/26_1600_batch_staff_candidate.md +++ /dev/null @@ -1,23 +0,0 @@ -# 团期选人限制在产品备选池中 - -**日期**: 2026-03-26 -**服务**: hl-product-service - ---- - -## 变更 - -团期分配人员时，后端校验所选人员必须在产品人员配置的备选池（`staffIds`）中。 - -**规则**： -- 产品配了备选人员（`staffIds` 不为空）→ 只能从备选池中选，选了池外的人报错 -- 产品没配备选人员 → 不限制，可选任意可用人员（兼容旧数据） - -**报错示例**：`"人员ID 1001 不在产品LEADER备选人员中"` - -## 前端改造 - -团期人员分配弹窗的人员下拉框： -1. 先查产品人员配置 `GET /admin/product/{productId}/staff-config`，取对应角色的 `staffIds` -2. 如果 `staffIds` 不为空 → 下拉只显示备选人员（调 `GET /internal/staff/batch-basic?staffIds=xxx` 查名字） -3. 如果 `staffIds` 为空 → 下拉显示该类型所有可用人员（调 `GET /internal/staff/list-available?staffType=LEADER`） diff --git a/changelogs/2026-03/26_1700_material_batch_delete_toast.md b/changelogs/2026-03/26_1700_material_batch_delete_toast.md deleted file mode 100644 index 58a47f1..0000000 --- a/changelogs/2026-03/26_1700_material_batch_delete_toast.md +++ /dev/null @@ -1,41 +0,0 @@ -# 素材批量删除——提示信息bug修复 - -**日期**: 2026-03-26 -**类型**: 前端bug -**涉及页面**: 素材库 → 批量删除 - ---- - -## 问题 - -批量删除素材时，即使所有素材都因"被引用"而删除失败，前端仍然提示"成功删除 N 个素材"。实际一个都没删成。 - -## 原因 - -后端 `DELETE /admin/material/batch` 返回的是 `BatchDeleteResultVO`，包含： -- `successCount`：实际成功删除的数量 -- `failedItems`：删除失败的列表（含每个素材的失败原因） - -前端没有正确读取这两个字段，可能只看了 HTTP 200 就认为全部成功。 - -## 前端需要修复 - -1. 读取响应中的 `successCount` 和 `failedItems` -2. 如果 `successCount === 0`，提示"删除失败"并展示失败原因 -3. 如果部分成功部分失败，提示"成功删除 X 个，Y 个失败"并展示失败原因 -4. 常见失败原因：`"该素材被N处引用，无法删除"`、`"无删除权限"` - -## 响应示例 - -```json -{ - "code": 200, - "data": { - "successCount": 2, - "failedItems": [ - { "materialId": "123", "reason": "该素材被1处引用，无法删除" }, - { "materialId": "456", "reason": "无删除权限" } - ] - } -} -``` diff --git a/changelogs/2026-03/26_1700_material_force_delete.md b/changelogs/2026-03/26_1700_material_force_delete.md deleted file mode 100644 index e20e85b..0000000 --- a/changelogs/2026-03/26_1700_material_force_delete.md +++ /dev/null @@ -1,23 +0,0 @@ -# 素材删除支持强制删除有引用的素材 - -**日期**: 2026-03-26 -**服务**: hl-material-service - ---- - -## 变更 - -`DELETE /admin/material/{materialId}` 新增 `force` 参数： - -| 参数 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `force` | boolean | false | 强制删除（忽略引用） | - -**行为**： -- `force=false`（默认）：有引用时返回错误 `"该素材被N处引用，不建议删除。如需强制删除请传 force=true"` -- `force=true`：无论是否有引用都删除 - -**前端改造**： -1. 删除素材时先不传 `force`，如果返回引用错误 -2. 弹确认框："该素材被N处引用，确定删除吗？" -3. 用户确认后再调一次 `DELETE /admin/material/{id}?force=true` diff --git a/changelogs/2026-03/26_1800_staff_cover_id.md b/changelogs/2026-03/26_1800_staff_cover_id.md deleted file mode 100644 index 6fcddf0..0000000 --- a/changelogs/2026-03/26_1800_staff_cover_id.md +++ /dev/null @@ -1,23 +0,0 @@ -# 人员管理编辑报500 - -**日期**: 2026-03-26 -**类型**: 前端BUG - ---- - -## 问题 - -编辑人员时报 500 错误。 - -## 原因 - -前端把封面图的 **OSS URL** 传给了 `coverMaterialId` 字段，后端尝试 `Long.parseLong(url)` 报 NumberFormatException。 - -## 修复 - -`coverMaterialId` 应传**素材ID**（纯数字），不是 URL： - -- 正确：`"coverMaterialId": "2030584827892072450"` -- 错误：`"coverMaterialId": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/..."` - -素材 ID 在上传确认接口 `/file/upload/confirm` 返回的 `materialId` 字段中。 diff --git a/changelogs/2026-03/26_1830_price_tier_fix.md b/changelogs/2026-03/26_1830_price_tier_fix.md deleted file mode 100644 index 5372bfc..0000000 --- a/changelogs/2026-03/26_1830_price_tier_fix.md +++ /dev/null @@ -1,18 +0,0 @@ -# 价格档位人数和价格计算问题 - -**日期**: 2026-03-26 - ---- - -## 前端BUG：价格档位人数没联动 - -`priceTierLabels` 保存的成人儿童数全是1，没和组合名对应： - -- "1大2小" 应该是 `adultCount: 1, childCount: 2` -- "2大1小" 应该是 `adultCount: 2, childCount: 1` - -目前都是 `adultCount: 1, childCount: 1`，前端改下联动。 - -## 后端优化：价格从价格日历计算（进行中） - -后端正在改：`priceTiers` 的价格从价格日历的 `adultSellPrice × 成人数 + childSellPrice × 儿童数` 自动算，不再依赖团期套餐（combo）。 diff --git a/changelogs/2026-03/27_0900_staff_save_error.md b/changelogs/2026-03/27_0900_staff_save_error.md deleted file mode 100644 index 569f38e..0000000 --- a/changelogs/2026-03/27_0900_staff_save_error.md +++ /dev/null @@ -1,34 +0,0 @@ -# 人员保存报500的两个问题 - -**日期**: 2026-03-27 - ---- - -## 1. 证书名称必填 - -保存人员时如果 `certificates` 里有图片但没填名称（tag），后端会返回错误： -```json -{"code": 400, "message": "第1个证书有附件但缺少证书名称"} -``` - -前端应展示后端返回的 `message`，不要笼统显示"服务器内部错误"。 - -## 2. coverMaterialId 传错格式 - -`coverMaterialId` 必须传**素材ID**（纯数字），不能传 OSS URL。之前已通知过。 - ---- - -## 3. 再次强调：coverMaterialId 必须传素材ID - -当前报错原因就是这个： -``` -NumberFormatException: For input string: "https://hlgl-test.oss-cn-beijing.aliyuncs.com/..." -``` - -后端 `Long.parseLong(coverMaterialId)` 把 URL 当数字解析报错。 - -**封面图字段**：`coverMaterialId` 传素材库的 materialId（如 `"2030584827892072450"`） -**个人照片字段**：`photoUrls` 传 OSS URL 数组（如 `["https://...jpg"]`） - -这两个字段不一样，别搞混。 diff --git a/changelogs/2026-03/27_0931_sync.md b/changelogs/2026-03/27_0931_sync.md deleted file mode 100644 index 76717f0..0000000 --- a/changelogs/2026-03/27_0931_sync.md +++ /dev/null @@ -1,30 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-27 09:32 - -## ℹ️ 新增 (15) - -### 资源服务 - -**新增接口** - -- 🆕 `GET /admin/staff/batch-basic` -- 🆕 `GET /admin/staff/batch-brief` - -**新增字段** - -| 数据对象 | 新增字段 | 类型 | -| --- | --- | --- | -| `酒店创建请求` | `roomSharePhone` | `string` | -| `酒店创建请求` | `salesPhone` | `string` | -| `酒店更新请求` | `roomSharePhone` | `string` | -| `酒店更新请求` | `salesPhone` | `string` | -| `酒店详情VO` | `roomSharePhone` | `string` | -| `酒店详情VO` | `roomTypes` | `房型详情VO[]` | -| `酒店详情VO` | `salesPhone` | `string` | -| `服务人员创建请求` | `certificateTags` | `string[]` | -| `服务人员创建请求` | `certificates` | `Map«string,string»[]` | -| `服务人员更新请求` | `certificateTags` | `string[]` | -| `服务人员更新请求` | `certificates` | `Map«string,string»[]` | -| `服务人员详情VO` | `certificateTags` | `string[]` | -| `服务人员详情VO` | `certificates` | `Map«string,string»[]` | diff --git a/changelogs/2026-03/27_1029_study_gains_and_staff_details.md b/changelogs/2026-03/27_1029_study_gains_and_staff_details.md deleted file mode 100644 index 5e50478..0000000 --- a/changelogs/2026-03/27_1029_study_gains_and_staff_details.md +++ /dev/null @@ -1,103 +0,0 @@ -# 2026-03-27 产品研学收获 + 备选人员详情 + Staff容错 - -## 一、新增：产品研学收获模块（PR #5） - -与"安全保障"设计完全一致，管理端CRUD + 小程序详情返回。 - -### 管理端接口 - -| 方法 | 路由 | 说明 | -|------|------|------| -| GET | `/admin/product/{productId}/study-gain` | 研学收获列表 | -| POST | `/admin/product/{productId}/study-gain` | 添加研学收获 | -| PUT | `/admin/product/{productId}/study-gain/{id}` | 更新研学收获 | -| DELETE | `/admin/product/{productId}/study-gain/{id}` | 删除研学收获 | - -### 请求体（POST/PUT） - -```json -{ - "category": "马术体验", - "name": "马术体验·培养勇气与平衡感", - "description": "学习马术基本功", - "icon": "horsemanship", - "sortOrder": 1 -} -``` - -### 小程序产品详情新增字段 - -`ProductVO.studyGains`：`[{icon, title, description}]` - -与 `safetyItems` 格式完全一致，前端可直接复用安全保障的渲染组件。 - ---- - -## 二、修复：产品备选人员返回完整信息（PR #4） - -### 变更 - -`ProductVO.staffConfigs` 每项新增 `staffDetails` 字段，包含备选人员的完整信息。 - -### 之前 - -```json -{ - "staffType": "LEADER", - "staffIds": ["1005"], - "staffDetails": null -} -``` - -### 现在 - -```json -{ - "staffType": "LEADER", - "staffIds": ["1005"], - "staffDetails": [ - { - "staffId": "1005", - "name": "刘大山", - "coverUrl": "https://...", - "phone": "13800001005", - "staffType": "LEADER", - "yearsOfExperience": 15, - "rating": 4.9, - "tags": [...], - ...全部StaffVO字段 - } - ] -} -``` - ---- - -## 三、修复：Staff素材ID解析容错（PR #3） - -后端内部修复，前端无需改动。修复了素材ID字段包含非数字时导致500的问题。 - -`/internal/staff/batch-detail` 现在返回完整 StaffVO（之前只返回部分字段）。 - ---- - -## 部署说明 - -需重启：**hl-product-service**、**hl-resource-service** - -测试环境需执行建表SQL： -```sql -CREATE TABLE product_study_gain ( - id BIGINT NOT NULL, - product_id BIGINT NOT NULL, - category VARCHAR(50) NOT NULL, - name VARCHAR(100) NOT NULL, - description VARCHAR(500) DEFAULT NULL, - icon VARCHAR(100) DEFAULT NULL, - sort_order INT DEFAULT 0, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - deleted_at DATETIME DEFAULT NULL, - PRIMARY KEY (id), - KEY idx_product_id (product_id) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; -``` diff --git a/changelogs/2026-03/27_1100_batch_deposit_amount.md b/changelogs/2026-03/27_1100_batch_deposit_amount.md deleted file mode 100644 index ff96642..0000000 --- a/changelogs/2026-03/27_1100_batch_deposit_amount.md +++ /dev/null @@ -1,49 +0,0 @@ -# 2026-03-27 团期定金金额 + 研学收获容错 - -## 一、新增：团期/套餐返回定金金额（PR #7） - -小程序底部栏"订金 ¥3999/人"现在可以根据选择的团期动态显示。 - -### 团期日历接口（已有） - -`GET /internal/product/{productId}/batches/calendar` - -每项新增 `depositAmount` 字段： - -```json -{ - "batchId": "123", - "departureDate": "2026-07-01", - "startingPrice": 12800, - "depositAmount": 3999 -} -``` - -### 套餐列表接口（已有） - -`GET /internal/product/batch/{batchId}/combos` - -每项新增 `depositAmount` 字段： - -```json -{ - "comboId": "456", - "comboName": "1大1小", - "sellPrice": 12800, - "depositAmount": 3999 -} -``` - -### 前端对接 - -1. 用户未选团期时：用产品详情中 `pricing.depositAmount` 显示默认定金 -2. 用户选择团期后：从日历数据 `depositAmount` 更新底部栏 -3. 用户选择套餐后：从combo数据 `depositAmount` 精确显示 - -## 二、修复：研学收获加载容错（PR #6） - -`loadStudyGains` 加了 try-catch，表不存在时不影响产品详情。 - -## 部署说明 - -重启：**hl-product-service** diff --git a/changelogs/2026-03/27_1130_remove_combo.md b/changelogs/2026-03/27_1130_remove_combo.md deleted file mode 100644 index 211e39b..0000000 --- a/changelogs/2026-03/27_1130_remove_combo.md +++ /dev/null @@ -1,19 +0,0 @@ -# 2026-03-27 彻底移除小蒙马套餐(combo) - -## 删除的接口 - -| 接口 | 说明 | -|------|------| -| ~~`GET /internal/product/batch/{batchId}/combos`~~ | **已删除**，不再返回套餐列表 | - -前端如果还在调用此接口会返回404，请移除相关调用。 - -## 变更的接口 - -### 团期日历 `GET /internal/product/{productId}/batches/calendar` - -`startingPrice` 改为从**价格日历**取值（原来从combo取），逻辑不变，字段不变。 - -## 部署说明 - -重启：**hl-product-service** diff --git a/changelogs/2026-03/27_1146_sync.md b/changelogs/2026-03/27_1146_sync.md deleted file mode 100644 index be4dacd..0000000 --- a/changelogs/2026-03/27_1146_sync.md +++ /dev/null @@ -1,11 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-27 11:47 - -## ℹ️ 新增 (1) - -### 字典变更 - -**新增字典类型** - -- 🆕 `study_gain_category`（研学收获分类） diff --git a/changelogs/2026-03/27_1200_study_gain_dict.md b/changelogs/2026-03/27_1200_study_gain_dict.md deleted file mode 100644 index fbec5fc..0000000 --- a/changelogs/2026-03/27_1200_study_gain_dict.md +++ /dev/null @@ -1,42 +0,0 @@ -# 2026-03-27 研学收获分类字典 - -## 新增字典 - -**字典类型**：`study_gain_category`（研学收获分类） - -前端在"研学收获"管理中使用此字典渲染分类下拉，与安全保障的分类下拉用法一致。 - -### 字典数据 - -| dict_value | dict_label | -|------------|------------| -| horsemanship | 马术体验 | -| stargazing | 星空学堂 | -| music | 蒙古音乐 | -| ecology | 草原生态 | -| dairy_diy | 奶制品DIY | -| certificate | 研学证书 | -| folk_culture | 民俗文化 | -| nature_explore | 自然探索 | -| handicraft | 手工制作 | -| history | 历史人文 | - -## 测试环境待执行SQL - -```sql --- 如果type不存在则插入 -INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status, created_at, updated_at) -VALUES (8060, '研学收获分类', 'study_gain_category', 'BUSINESS', 'ACTIVE', NOW(), NOW()); - -INSERT INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status, remark, created_at, updated_at) VALUES -(80611, 'study_gain_category', '马术体验', 'horsemanship', 1, 'ACTIVE', 'success', NOW(), NOW()), -(80612, 'study_gain_category', '星空学堂', 'stargazing', 2, 'ACTIVE', 'info', NOW(), NOW()), -(80613, 'study_gain_category', '蒙古音乐', 'music', 3, 'ACTIVE', 'warning', NOW(), NOW()), -(80614, 'study_gain_category', '草原生态', 'ecology', 4, 'ACTIVE', 'success', NOW(), NOW()), -(80615, 'study_gain_category', '奶制品DIY', 'dairy_diy', 5, 'ACTIVE', 'info', NOW(), NOW()), -(80616, 'study_gain_category', '研学证书', 'certificate', 6, 'ACTIVE', 'warning', NOW(), NOW()), -(80617, 'study_gain_category', '民俗文化', 'folk_culture', 7, 'ACTIVE', 'success', NOW(), NOW()), -(80618, 'study_gain_category', '自然探索', 'nature_explore', 8, 'ACTIVE', 'info', NOW(), NOW()), -(80619, 'study_gain_category', '手工制作', 'handicraft', 9, 'ACTIVE', 'warning', NOW(), NOW()), -(80620, 'study_gain_category', '历史人文', 'history', 10, 'ACTIVE', 'success', NOW(), NOW()); -``` diff --git a/changelogs/2026-03/27_1300_photography_tag_dict.md b/changelogs/2026-03/27_1300_photography_tag_dict.md deleted file mode 100644 index f72f00d..0000000 --- a/changelogs/2026-03/27_1300_photography_tag_dict.md +++ /dev/null @@ -1,26 +0,0 @@ -# 2026-03-27 摄影跟拍标签字典 - -## 新增字典 - -**字典类型**：`photography_tag`（摄影跟拍标签） - -前端在"摄影跟拍"模块的标签选择中使用此字典渲染下拉，与安全保障的分类下拉用法一致。 - -### 字典数据 - -| dict_value | dict_label | -|------------|------------| -| full_follow | 全程跟拍 | -| retouched | 精修底片 | -| drone | 航拍 | -| family_portrait | 亲子写真 | -| travel_mv | 旅拍MV | -| instant_share | 即时分享 | -| ethnic_costume | 民族服饰 | -| starry_sky | 星空摄影 | - -## 前端对接 - -摄影标签改为从字典 `photography_tag` 选择，不再自由输入。 - -无需重启服务，字典API直接返回新数据。 diff --git a/changelogs/2026-03/27_1400_batch_calendar_family_photography.md b/changelogs/2026-03/27_1400_batch_calendar_family_photography.md deleted file mode 100644 index da3d559..0000000 --- a/changelogs/2026-03/27_1400_batch_calendar_family_photography.md +++ /dev/null @@ -1,71 +0,0 @@ -# 2026-03-27 团期日历接口 + 参与家庭数 + 好评率默认 + 摄影跟拍改版 - -## 一、新增：小程序团期日历接口（PR #11） - -原 `/internal/product/{id}/batches/calendar` 是内部接口，前端调会404。 - -**新接口**：`GET /mp/product/{productId}/batches/calendar` - -经网关：`/product/mp/product/{productId}/batches/calendar` - -返回： -```json -[{ - "departureDate": "2026-07-01", - "batchId": "123", - "batchLabel": "七月第一团", - "startingPrice": 12800.00, - "depositAmount": 3999.00, - "enrolledCount": 15, - "remainingSlots": 15, - "isConfirmed": false -}] -``` - -## 二、新增：参与家庭数 + 好评率默认100%（PR #12） - -产品详情 `GET /mp/product/{id}` 新增/修改字段： - -| 字段 | 说明 | 示例 | -|------|------|------| -| `familyCount` | **新增**，参与家庭数（所有团期enrolled_count总和） | `47` | -| `reviewApprovalRate` | **修改**，无评价时默认"100%"，有评价才算实际好评率 | `"100%"` | - -## 三、摄影跟拍改为分类模式（PR #13） - -与安全保障/研学收获完全一致的分类+名称+描述模式。 - -### 管理端接口 - -| 方法 | 路由 | 说明 | -|------|------|------| -| GET | `/admin/product/{productId}/photography-item` | 列表 | -| POST | `/admin/product/{productId}/photography-item` | 添加 | -| PUT | `/admin/product/{productId}/photography-item/{id}` | 更新 | -| DELETE | `/admin/product/{productId}/photography-item/{id}` | 删除 | - -### 请求体 - -```json -{ - "category": "全程跟拍", - "name": "全程跟拍·记录每一个精彩瞬间", - "description": "专业摄影师全程随行跟拍", - "icon": "camera", - "sortOrder": 1 -} -``` - -### 字典 - -分类下拉使用字典 `photography_tag`（已配置） - -### 小程序端 - -产品详情新增 `photographyItems` 字段：`[{icon, title, description}]` - -旧的 `photographyTags`（标签列表）和 `photographyImages`（作品图）保留兼容。 - -## 部署说明 - -重启：**hl-product-service** diff --git a/changelogs/2026-03/27_1421_sync.md b/changelogs/2026-03/27_1421_sync.md deleted file mode 100644 index f638475..0000000 --- a/changelogs/2026-03/27_1421_sync.md +++ /dev/null @@ -1,11 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-27 14:22 - -## ℹ️ 新增 (1) - -### 字典变更 - -**新增字典类型** - -- 🆕 `photography_tag`（摄影跟拍标签） diff --git a/changelogs/2026-03/27_1440_frontend_bugs.md b/changelogs/2026-03/27_1440_frontend_bugs.md deleted file mode 100644 index feac264..0000000 --- a/changelogs/2026-03/27_1440_frontend_bugs.md +++ /dev/null @@ -1,50 +0,0 @@ -# 🐛 前端BUG反馈 — 景区编辑400 + 活动计费方式 - -**日期**: 2026-03-27 14:40 -**类型**: 前端BUG -**紧急程度**: 高（正式环境用户已遇到） - ---- - -## BUG 1：景区编辑保存报 400 - -**现象**：编辑任意景区 → 点"确定"保存 → 提示"请求错误: 400" - -**根因**：前端发送的请求 URL 异常： -``` -PUT /admin/scenic/spot/[object Object] -``` -景区ID没有正确传递，被序列化成了 `[object Object]`。 - -**网关日志证据**（14:32）： -``` -WARN Decoding failed: REQUEST(decodeResult: failure( - java.net.URISyntaxException: Illegal character in path at index 40: - http://localhost:8080/admin/scenic/spot/[object%20Object] -)) -PUT /admin/scenic/spot/[object%20Object] HTTP/1.1 -``` - -**后端状态**：后端无任何报错，请求在网关层就被拒绝了。 - -**排查方向**：检查景区编辑页提交时，`id` 字段是否正确取值。可能是把整个景区对象当 ID 拼到了 URL 里。 - ---- - -## BUG 2：活动编辑页显示"计费方式"必填项 - -**现象**：编辑活动时，表单中出现"计费方式"字段且标记为必填（红框），但该字段无可选项。 - -**说明**：**后端活动模块没有 `billingType`/`billing_type` 字段**。活动只有 `unit`（计量单位）字段，没有计费方式。 - -`billing_type` 只存在于： -- 备品(supplies) -- 增值服务(service) - -活动编辑表单不应该显示"计费方式"，请移除该字段。 - ---- - -## 后端已完成的修复（同步告知） - -已修复资源服务 `bindMaterialRefs` 中素材ID解析崩溃问题（URL当数字解析），9个服务文件全部用 `parseLongSafe` 容错处理，正式环境已部署。 diff --git a/changelogs/2026-03/27_1657_sync.md b/changelogs/2026-03/27_1657_sync.md deleted file mode 100644 index 9b23f9f..0000000 --- a/changelogs/2026-03/27_1657_sync.md +++ /dev/null @@ -1,11 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-27 16:58 - -## ℹ️ 新增 (1) - -### 字典变更 - -**新增字典类型** - -- 🆕 `product_approval_status`（产品审核状态） diff --git a/changelogs/2026-03/27_1700_product_status_refactor.md b/changelogs/2026-03/27_1700_product_status_refactor.md deleted file mode 100644 index e9e57e6..0000000 --- a/changelogs/2026-03/27_1700_product_status_refactor.md +++ /dev/null @@ -1,62 +0,0 @@ -# 2026-03-27 产品状态重构 + 上下架审批 + 价格日历修复 - -## 一、重大变更：产品状态和审核状态分离（PR #23） - -### 产品状态 `status`（简化为3种） - -| 值 | 说明 | -|---|------| -| DRAFT | 草稿 | -| PUBLISHED | 上架 | -| UNPUBLISHED | 下架 | - -**废弃的旧状态**：PENDING_REVIEW、REVIEWED、REJECTED 不再使用 - -### 新增字段 `approvalStatus`（审核状态） - -字典：`product_approval_status` - -| 值 | 说明 | -|---|------| -| NONE | 无审核 | -| PENDING | 审核中 | -| PUBLISH_APPROVED | 上架通过 | -| PUBLISH_REJECTED | 上架驳回 | -| UNPUBLISH_APPROVED | 下架通过 | -| UNPUBLISH_REJECTED | 下架驳回 | - -### 前端状态变更接口 - -`PUT /admin/product/{id}/status`，`targetStatus` 含义： -- `PUBLISHED` → 提交上架审批（企微OA） -- `UNPUBLISHED` → 提交下架审批（企微OA） -- `DRAFT` → 直接改为草稿 - -### 列表和详情都返回 `approvalStatus` - -前端根据 `status` + `approvalStatus` 两个字段显示状态。 - ---- - -## 二、价格日历修复汇总 - -| PR | 修复 | -|----|------| -| #14 | 价格为0不能设为可售 | -| #15 | 库存为0不能设为可售 | -| #16 | 自动计算为0时提示具体缺价格的资源 | -| #17 | GROUP产品无团期也能设价格日历 | -| #18 | resource_type大小写不匹配导致景区活动成本为0 | -| #19 | 餐厅不参与成本计算，跳过RESTAURANT节点 | -| #20 | GROUP无团期时自动计算能正确算出售价 | - -## 三、团期人员严格校验（PR #21） - -团期设置服务人员必须严格按产品配置： -- 类型必须匹配 -- 数量必须匹配 -- 人员必须在备选池内 - -## 部署说明 - -重启：**hl-product-service** diff --git a/changelogs/2026-03/27_1739_frontend_bug_status_path.md b/changelogs/2026-03/27_1739_frontend_bug_status_path.md deleted file mode 100644 index c9d3e0a..0000000 --- a/changelogs/2026-03/27_1739_frontend_bug_status_path.md +++ /dev/null @@ -1,60 +0,0 @@ -# 🐛 前端BUG：产品状态变更请求路径错误（404） - -**日期**: 2026-03-27 -**类型**: 前端BUG -**优先级**: 高 -**影响页面**: 产品列表页（产品管理 → 上架/下架操作） - ---- - -## 问题现象 - -在产品列表页点击上架/下架时，页面提示"请求的资源不存在"，网络面板显示 `status` 请求返回 **404**。 - -## 原因 - -前端请求路径拼错了，多了一层 `/admin`，并且缺少 `/item` 路径段。 - -| | 路径 | -|------|------| -| ❌ 前端当前请求 | `PUT /admin/admin/product/{productId}/status` | -| ✅ 正确路径 | `PUT /admin/product/item/{productId}/status` | - -## 修复方式 - -检查前端代码中产品状态变更的 API 调用，将路径修改为： - -``` -PUT /admin/product/item/{productId}/status -``` - -### 请求参数（Body JSON） - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| status | String | 是 | 目标状态：`PUBLISHED`（上架）/ `UNPUBLISHED`（下架）/ `DRAFT`（撤回草稿） | -| reason | String | 否 | 操作原因（上架/下架审批时的说明） | - -### 请求示例 - -```json -{ - "status": "PUBLISHED", - "reason": "产品信息已完善，申请上架" -} -``` - -### 响应示例 - -```json -{ - "code": 200, - "message": "success", - "data": null -} -``` - -## 备注 - -- 上架和下架现在走企微OA审批流程，提交后状态不会立即变更，需等待审批通过 -- 产品列表新增了「审核状态」列，可查看审批进度 diff --git a/changelogs/2026-03/27_1800_batch_calendar_api_doc.md b/changelogs/2026-03/27_1800_batch_calendar_api_doc.md deleted file mode 100644 index 06248be..0000000 --- a/changelogs/2026-03/27_1800_batch_calendar_api_doc.md +++ /dev/null @@ -1,209 +0,0 @@ -# 接口文档：团期日历数据 - -> **日期**: 2026-03-27 -> **类型**: 📖 接口文档补充（非新增接口，已有接口的完整使用说明） -> **涉及服务**: hl-product-service、hl-mp-service -> **接口状态**: ✅ 已上线可用 - ---- - -## 一、功能说明 - -此接口为 **GROUP（小蒙马拼团）产品** 提供团期日历数据，供小程序端日历选择器展示。 - -**核心能力**： -- 返回指定产品所有**可报名**团期（状态为 ENROLLING 或 CONFIRMED） -- 只返回**今天及以后**的出发日期（历史团期自动过滤） -- 每个团期包含：出发日期、起步价、定金金额、剩余名额、剩余房间数、是否已成团 -- 起步价来源于**价格日历**（product_price_calendar 表的成人售价） -- 定金计算规则：固定金额优先，否则用 `起步价 × 定金比例%`（向上取整） - ---- - -## 二、接口清单 - -| # | 接口 | 方法 | 路径 | 说明 | -|---|------|------|------|------| -| 1 | 团期日历（内部） | GET | `/internal/product/{productId}/batches/calendar` | 服务间调用 | -| 2 | 团期日历（C端） | GET | `/mp/product/{productId}/batches/calendar` | 小程序直接调用（经网关） | - -> 两个接口返回数据完全相同，区别仅在路由层： -> - **内部接口**：hl-mp-service 通过 Feign 调用 hl-product-service -> - **C端接口**：小程序通过网关 `/mp/product/...` 直接请求 - ---- - -## 三、接口详细定义 - -### GET `/mp/product/{productId}/batches/calendar` - -> **前端应调用此路径**（经网关转发），不要直接调用 internal 路径 - -#### 使用场景 -小程序 GROUP 产品详情页，展示**团期日历选择器**，用户选择出发日期后进入报价流程。 - -#### 请求参数 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| productId | path | Long | ✅ | 产品ID（必须是 GROUP 类型产品） | - -#### 请求示例 - -``` -GET /mp/product/1903770276454400001/batches/calendar -``` - -#### 响应示例 - -```json -{ - "code": 200, - "message": "操作成功", - "data": [ - { - "departureDate": "2026-05-01", - "batchId": "1903770276454400101", - "batchLabel": "五一团", - "batchName": "2026年五一黄金周第一批", - "batchStatus": "ENROLLING", - "startingPrice": 12800.00, - "enrolledCount": 15, - "remainingSlots": 15, - "maxRooms": 15, - "bookedRooms": 5, - "remainingRooms": 10, - "isConfirmed": false, - "depositAmount": 3999.00 - }, - { - "departureDate": "2026-05-08", - "batchId": "1903770276454400102", - "batchLabel": "五一加开团", - "batchName": "2026年五一黄金周第二批", - "batchStatus": "CONFIRMED", - "startingPrice": 11800.00, - "enrolledCount": 28, - "remainingSlots": 2, - "maxRooms": 15, - "bookedRooms": 13, - "remainingRooms": 2, - "isConfirmed": true, - "depositAmount": 3540.00 - } - ] -} -``` - ---- - -## 四、响应字段说明 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `departureDate` | String (yyyy-MM-dd) | 出发日期 | -| `batchId` | String | 批次ID（雪花ID字符串） | -| `batchLabel` | String | 批次标签（短名，如"五一团"） | -| `batchName` | String | 批次全称 | -| `batchStatus` | String | 批次状态，见下方枚举 | -| `startingPrice` | BigDecimal | 起步价(元)，来自价格日历的成人售价。**可能为 null**（价格日历未配置时） | -| `enrolledCount` | Integer | 已报名人数 | -| `remainingSlots` | Integer | 剩余名额 = maxParticipants - enrolledCount | -| `maxRooms` | Integer | 总房间数 | -| `bookedRooms` | Integer | 已预订房间数 | -| `remainingRooms` | Integer | 剩余房间数 = maxRooms - bookedRooms | -| `isConfirmed` | Boolean | 是否已成团（batchStatus == "CONFIRMED" 时为 true） | -| `depositAmount` | BigDecimal | 定金金额(元/人)。**可能为 null**（未配置定金且无起步价时） | - ---- - -## 五、枚举/字典值 - -### batchStatus 批次状态（本接口只返回前两种） - -| 值 | 中文 | 说明 | -|----|------|------| -| `ENROLLING` | 报名中 | ✅ 本接口会返回，可正常报名 | -| `CONFIRMED` | 已成团 | ✅ 本接口会返回，已达成团人数，仍可继续报名 | -| `PENDING` | 待开放 | ❌ 不会返回 | -| `FULL` | 已满员 | ❌ 不会返回 | -| `DEPARTED` | 已出发 | ❌ 不会返回 | -| `COMPLETED` | 已完成 | ❌ 不会返回 | -| `CANCELLED` | 已取消 | ❌ 不会返回 | - ---- - -## 六、业务规则 - -1. **过滤条件**：只返回 `batchStatus IN ('ENROLLING', 'CONFIRMED')` 且 `departureDate >= 今天` 的团期 -2. **排序**：按出发日期升序 → 排序号升序 -3. **起步价来源**：从 `product_price_calendar` 表查询对应日期的 `adult_sell_price`，状态必须为 AVAILABLE -4. **定金计算**： - - 如果产品配置了固定定金金额（`deposit_amount > 0`）→ 直接使用 - - 否则用 `起步价 × deposit_ratio / 100`，向上取整（RoundingMode.UP） - - 两者都没有配置时 → depositAmount 为 null -5. **非 GROUP 产品调用此接口**：返回空数组 `[]`（不会报错） - ---- - -## 七、调用位置（后端内部使用情况） - -此接口在后端有 **3 处调用**，前端了解即可： - -| 调用位置 | 场景 | 说明 | -|----------|------|------| -| `MpProductController.java:97` | 产品列表接口 | GROUP 产品列表自动追加 `batches` 字段 | -| `ProductAggregationService.java:174` | 产品详情聚合 | GROUP 产品详情页异步加载团期 | -| `MpProductFeignClient.java:57` | Feign 声明 | hl-mp-service → hl-product-service 的 Feign 调用声明 | - -### 前端调用建议 - -**场景1：产品列表页** -- GROUP 产品列表接口 `GET /mp/product/list` 已自动包含 `batches` 字段（数组），无需单独调用 - -**场景2：产品详情页** -- 产品详情聚合接口 `GET /mp/product/{id}/detail` 已自动包含 `batches` 字段，无需单独调用 - -**场景3：需要单独刷新团期** -- 用户在详情页停留较久需要刷新团期时，可单独调用 `GET /mp/product/{productId}/batches/calendar` - ---- - -## 八、前端实现建议 - -``` -┌─────────────────────────────────────────────┐ -│ 团期日历选择器 │ -│ │ -│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ -│ │ 4/28│ │ 4/29│ │ 4/30│ │ 5/01│ │ 5/02│ │ -│ │ │ │ │ │ │ │五一团│ │ │ │ -│ │ │ │ │ │ │ │¥12800│ │ │ │ -│ │ — │ │ — │ │ — │ │剩15位│ │ — │ │ -│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ -│ │ -│ 选中团期信息： │ -│ ┌──────────────────────────────────────┐ │ -│ │ 五一团 · 2026-05-01出发 │ │ -│ │ 起步价 ¥12,800/人 定金 ¥3,999/人 │ │ -│ │ 剩余 15 名额 · 剩余 10 间房 │ │ -│ │ 🔴 报名中（未成团） │ │ -│ └──────────────────────────────────────┘ │ -│ │ -│ [ 立即报名 ] │ -└─────────────────────────────────────────────┘ -``` - -**展示建议**： -- 日历格子：有团期的日期高亮显示，无团期的日期置灰 -- `isConfirmed = true` → 显示 "已成团" 绿色标签 -- `isConfirmed = false` → 显示 "报名中" 橙色标签 -- `remainingSlots <= 3` → 显示 "仅剩X位" 红色提示 -- `remainingRooms <= 2` → 显示 "房间紧张" 提示 -- `startingPrice` 为 null → 显示 "价格待定" -- `depositAmount` 不为 null → 显示 "定金 ¥xxx/人" -- `batchLabel` 作为日历格子内的短标签显示 - ---- - -*📖 此文档为已有接口的详细说明，无代码变更* diff --git a/changelogs/2026-03/27_1811_sync.md b/changelogs/2026-03/27_1811_sync.md deleted file mode 100644 index d3cd9b9..0000000 --- a/changelogs/2026-03/27_1811_sync.md +++ /dev/null @@ -1,17 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-27 18:12 - -## ⚠️ Breaking Changes (3) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 字典变更 - -**字典项删除** - -| 字典 | 删除值 | 标签 | -| --- | --- | --- | -| `product_status`（产品状态） | ~~`PENDING_REVIEW`~~ | 待审核 | -| `product_status`（产品状态） | ~~`REJECTED`~~ | 已驳回 | -| `product_status`（产品状态） | ~~`REVIEWED`~~ | 已审核 | diff --git a/changelogs/2026-03/27_1820_product_no_type_prefix.md b/changelogs/2026-03/27_1820_product_no_type_prefix.md deleted file mode 100644 index 06a9446..0000000 --- a/changelogs/2026-03/27_1820_product_no_type_prefix.md +++ /dev/null @@ -1,27 +0,0 @@ -# 产品编号按类型区分前缀 - -- **日期**: 2026-03-27 -- **PR**: #25 -- **服务**: hl-product-service -- **类型**: feat - -## 变更内容 - -新建产品时，产品编号前缀按产品类型区分： - -| 产品类型 | 前缀 | 编号示例 | -|---------|------|---------| -| CORE 核心产品 | CP | CP20260327181200725 | -| ROUTE 自驾路书 | RP | RP20260327181200312 | -| CUSTOM 定制产品 | DP | DP20260327181200456 | -| GROUP 小蒙马拼团 | GP | GP20260327181200889 | - -## 前端影响 - -- 产品编号字段（product_no）长度可能多1位（原18位→现19位），前端展示如有截断需调整 -- 已有产品编号（P开头）不受影响 -- 搜索/筛选如果按前缀匹配需注意新前缀 - -## 需要重启 - -- hl-product-service diff --git a/changelogs/2026-03/27_1830_early_bird_text.md b/changelogs/2026-03/27_1830_early_bird_text.md deleted file mode 100644 index aff4c30..0000000 --- a/changelogs/2026-03/27_1830_early_bird_text.md +++ /dev/null @@ -1,35 +0,0 @@ -# 产品详情新增早鸟优惠文字描述 - -- **日期**: 2026-03-27 -- **PR**: #27 -- **服务**: hl-mp-service -- **类型**: feat - -## 变更内容 - -`GET /mp/product/{productId}` 产品详情接口新增字段 `earlyBirdText`。 - -### 新增字段 - -| 字段 | 类型 | 说明 | 示例 | -|------|------|------|------| -| earlyBirdText | String | 早鸟优惠文字描述，无优惠时为null | "早鸟优惠：满2人立减50元/人" | - -### 返回示例 - -```json -{ - "earlyBirdDiscount": 50, - "earlyBirdPlanName": "暑期早鸟", - "earlyBirdText": "早鸟优惠：满2人立减50元/人" -} -``` - -## 前端影响 - -- 新增字段，向后兼容，无需改动即可使用 -- 小程序产品详情页可直接展示 earlyBirdText 文字 - -## 需要重启 - -- hl-mp-service diff --git a/changelogs/2026-03/27_1832_refund_policy_text.md b/changelogs/2026-03/27_1832_refund_policy_text.md deleted file mode 100644 index 79bce18..0000000 --- a/changelogs/2026-03/27_1832_refund_policy_text.md +++ /dev/null @@ -1,63 +0,0 @@ -# 小程序产品详情：退款政策返回规则文字 - -**日期**: 2026-03-27 -**类型**: BUG修复 -**影响服务**: hl-product-service -**影响接口**: `GET /mp/product/{productId}` - ---- - -## 变更说明 - -产品详情接口新增 `refundPolicies` 字段，按支付类型分组返回退款政策的名称和规则文字。 - -原有的 `refundPolicyIds` 字段保持不变（后台管理用）。 - -## 新增字段 - -### refundPolicies - -| 字段 | 类型 | 说明 | -|------|------|------| -| refundPolicies | Map<String, List> | key=支付类型(FULL/DEPOSIT/BALANCE)，value=政策列表 | -| └ policyName | String | 政策名称 | -| └ rules | List<String> | 规则文字列表 | - -### 响应示例（新增部分） - -```json -{ - "refundPolicyIds": { - "DEPOSIT": "1,3,4", - "BALANCE": "1,3,4" - }, - "refundPolicies": { - "DEPOSIT": [ - { - "policyName": "标准退款政策", - "rules": [ - "出发前7天及以上取消，全额退款", - "出发前3天及以上取消，退款50%", - "出发当天取消，不予退款" - ] - } - ], - "BALANCE": [ - { - "policyName": "标准退款政策", - "rules": [ - "出发前7天及以上取消，全额退款", - "出发前3天及以上取消，退款50%", - "出发当天取消，不予退款" - ] - } - ] - } -} -``` - -## 前端使用建议 - -小程序产品详情页「取消政策」部分，直接遍历 `refundPolicies` 展示： -- 按支付类型分区（如"定金退款政策"、"尾款退款政策"） -- 每个政策显示 `policyName` 标题 + `rules` 列表 diff --git a/changelogs/2026-03/27_1849_mp_product_fixes.md b/changelogs/2026-03/27_1849_mp_product_fixes.md deleted file mode 100644 index 5adbc1a..0000000 --- a/changelogs/2026-03/27_1849_mp_product_fixes.md +++ /dev/null @@ -1,59 +0,0 @@ -# 小程序产品接口优化（2项） - -**日期**: 2026-03-27 -**类型**: BUG修复 + 优化 -**影响服务**: hl-product-service -**影响接口**: `GET /mp/product/{productId}`（详情）、`GET /mp/product/list`（列表）、`GET /mp/product/recommend`（推荐） - ---- - -## 1. 团队经验年数所有产品类型都返回 - -之前 `teamExperienceYears` 只有小蒙马(GROUP)产品才返回，现在所有产品类型都返回。 - -值自动从公司成立日期（2005年）计算，当前返回 **21**。 - ---- - -## 2. 起售价根据支付模式返回 - -### 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| startPriceLabel | String | 价格标签：`"起"` 或 `"定金起"` | - -### startPrice 计算逻辑变更 - -| 支付模式 | startPrice | startPriceLabel | -|----------|-----------|----------------| -| FULL（全款） | 最低售价（不变） | `"起"` | -| DEPOSIT（定金+尾款） | 最低售价 × 定金比例（向上取整） | `"定金起"` | - -### 影响范围 - -列表和详情都已修改，返回格式一致。 - -### 响应示例 - -```json -// 全款模式 -{ - "startPrice": 5980, - "startPriceLabel": "起", - "paymentMode": "FULL" -} - -// 定金模式（30%定金） -{ - "startPrice": 1794, - "startPriceLabel": "定金起", - "paymentMode": "DEPOSIT" -} -``` - -### 前端使用建议 - -价格展示拼接方式：`¥${startPrice} ${startPriceLabel}` - -示例效果：`¥5980 起` 或 `¥1794 定金起` diff --git a/changelogs/2026-03/27_1910_creator_name.md b/changelogs/2026-03/27_1910_creator_name.md deleted file mode 100644 index 77f5f78..0000000 --- a/changelogs/2026-03/27_1910_creator_name.md +++ /dev/null @@ -1,30 +0,0 @@ -# 小程序产品接口新增创作者姓名 - -**日期**: 2026-03-27 -**类型**: 新增字段 -**影响服务**: hl-product-service -**影响接口**: 产品列表 + 产品详情（所有小程序端接口） - ---- - -## 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| creatorName | String | 创作者姓名（企微姓名优先，fallback用用户名） | - -列表和详情都返回。 - -### 响应示例 - -```json -{ - "creatorName": "王骁", - "creatorAvatarUrl": "https://...", - "creatorIntro": "深耕呼伦贝尔20年..." -} -``` - -### 前端使用建议 - -产品卡片/详情页展示定制师信息时，用 `creatorName` 显示姓名，搭配 `creatorAvatarUrl`（头像）和 `creatorIntro`（寄语）。 diff --git a/changelogs/2026-03/27_1913_early_bird_text.md b/changelogs/2026-03/27_1913_early_bird_text.md deleted file mode 100644 index 0a92596..0000000 --- a/changelogs/2026-03/27_1913_early_bird_text.md +++ /dev/null @@ -1,36 +0,0 @@ -# 小程序产品详情新增早鸟优惠文案 - -**日期**: 2026-03-27 -**类型**: 新增字段 -**影响服务**: hl-product-service、hl-order-service -**影响接口**: `GET /mp/product/{productId}`（产品详情） - ---- - -## 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| earlyBirdTexts | List<String> | 早鸟优惠文案列表，无优惠时为null | - -### 响应示例 - -```json -{ - "earlyBirdTexts": [ - "2人及以上立减200元/人（2026-04-01至2026-06-30）", - "立减100元/人（2026-05-01至2026-08-31）" - ] -} -``` - -### 文案格式 - -`{人数条件}立减{金额}元/人（{开始日期}至{结束日期}）` - -- 1人即可享受时省略人数条件 -- 无生效的早鸟计划时返回 null - -### 前端使用建议 - -产品详情页价格区域下方展示早鸟优惠标签，遍历 `earlyBirdTexts` 列表逐条显示。 diff --git a/changelogs/2026-03/30_1002_sync.md b/changelogs/2026-03/30_1002_sync.md deleted file mode 100644 index ca1cbc8..0000000 --- a/changelogs/2026-03/30_1002_sync.md +++ /dev/null @@ -1,68 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-30 10:03 - -## ⚠️ Breaking Changes (4) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 小程序聚合服务 - -**字段类型变化** - -| 数据对象 | 字段 | 原类型 | 新类型 | -| --- | --- | --- | --- | -| `出行人请求(新增/修改)` | `gender` | `integer(int32)` | `string` | - -**参数删除** - -- ❌ `GET /mp/trip/weather` 参数 ~~`city`~~ -- ❌ `GET /mp/weather/forecast` 参数 ~~`city`~~ -- ❌ `GET /mp/weather/live` 参数 ~~`city`~~ - -## ℹ️ 新增 (32) - -### 小程序聚合服务 - -**新增接口** - -- 🆕 `GET /mp/custom/detail` -- 🆕 `GET /mp/custom/list` -- 🆕 `GET /mp/custom/product/{productId}` -- 🆕 `GET /mp/custom/products` -- 🆕 `GET /mp/hotel/room-type/{roomTypeId}` -- 🆕 `GET /mp/order/{orderId}/transports` -- 🆕 `POST /mp/custom/submit` -- 🆕 `POST /mp/custom/{requestId}/cancel` -- 🆕 `POST /mp/order/refund/{orderId}/direct-appeal` -- 🆕 `POST /mp/order/{orderId}/transport` -- 🆕 `POST /mp/order/{orderId}/urge` -- 🆕 `PUT /mp/order/{orderId}/remark` - -**新增字段** - -| 数据对象 | 新增字段 | 类型 | -| --- | --- | --- | -| `C端产品详情` | `earlyBirdText` | `string` | -| `C端产品详情` | `refundPolicies` | `object` | -| `产品报价结果` | `available` | `boolean` | -| `产品报价结果` | `stock` | `integer(int32)` | -| `订单列表项` | `refundAmount` | `number` | -| `订单详情` | `displayStatus` | `string` | -| `订单详情` | `displayStatusLabel` | `string` | -| `订单详情` | `hotelAssignmentDetails` | `Map«string,object»[]` | -| `订单详情` | `refundPolicy` | `object` | -| `订单详情` | `sharerOpenid` | `string` | -| `订单详情` | `surchargeAmount` | `number` | -| `订单详情` | `surcharges` | `Map«string,object»[]` | -| `订单详情` | `transportSegments` | `Map«string,object»[]` | -| `退款申诉请求` | `appealAmount` | `number` | - -**新增参数** - -- `GET /mp/trip/weather` 新增参数 `latitude` -- `GET /mp/trip/weather` 新增参数 `longitude` -- `GET /mp/weather/forecast` 新增参数 `latitude` -- `GET /mp/weather/forecast` 新增参数 `longitude` -- `GET /mp/weather/live` 新增参数 `latitude` -- `GET /mp/weather/live` 新增参数 `longitude` diff --git a/changelogs/2026-03/30_1030_contract_2026_upgrade.md b/changelogs/2026-03/30_1030_contract_2026_upgrade.md deleted file mode 100644 index 53fbf87..0000000 --- a/changelogs/2026-03/30_1030_contract_2026_upgrade.md +++ /dev/null @@ -1,42 +0,0 @@ -# 2026版旅游合同对接升级（P0项） - -**日期**: 2026-03-30 -**类型**: 功能升级 -**影响服务**: hl-contract-service -**优先级**: P0（3月31日新规推行） - ---- - -## 变更内容 - -### 1. 投诉电话字段补全 - -- 合同提交12301平台时自动携带投诉电话（4000881814） -- Nacos旅行社配置补全：hulai/qianshou/hulai-wenlu 三家均已配置 -- 新增字段：`complaint.complaintPhone` - -### 2. 安全告知书模块 - -创建合同时自动根据产品名称匹配高风险活动，将安全告知文本追加到合同补充条款中。 - -**预设6个高风险活动告知模板：** - -| 关键词 | 活动 | 风险类型 | -|--------|------|---------| -| 骑马 | 骑马体验 | 跌落/踩踏 | -| 滑草 | 滑草活动 | 摔伤/扭伤 | -| 越野 | 越野车穿越 | 颠簸/侧翻 | -| 篝火 | 篝火晚会 | 烧伤/烫伤 | -| 烧烤 | 河边烧烤 | 溺水/烫伤 | -| UTV | UTV全地形车 | 翻车/碰撞 | - -无匹配时追加通用安全提示（6条基础安全须知）。 - -### 3. 购物/自费项目 - -当前传空数组（表示无购物无自费安排），符合2026版合同规范。 - -## 运维事项 - -- 需同步更新**测试环境和正式环境**的 Nacos 配置（hl-contract-service-dev.yml / hl-contract-service-prod.yml） -- 添加 `complaint-phone` 和 `email` 字段到旅行社配置 diff --git a/changelogs/2026-03/30_1115_early_bird_fix.md b/changelogs/2026-03/30_1115_early_bird_fix.md deleted file mode 100644 index 240dc95..0000000 --- a/changelogs/2026-03/30_1115_early_bird_fix.md +++ /dev/null @@ -1,10 +0,0 @@ -# 早鸟优惠文案修复 - -**日期**: 2026-03-30 -**影响接口**: `GET /mp/product/{productId}` earlyBirdTexts 字段 - -## 修复 - -`立减200元/人` → `立减200元` - -去掉了多余的"/人"后缀。 diff --git a/changelogs/2026-03/30_1130_frontend_material_id_bug.md b/changelogs/2026-03/30_1130_frontend_material_id_bug.md deleted file mode 100644 index 6666301..0000000 --- a/changelogs/2026-03/30_1130_frontend_material_id_bug.md +++ /dev/null @@ -1,48 +0,0 @@ -# 🐛 前端BUG — 资源编辑传素材URL而非素材ID - -**日期**: 2026-03-30 11:30 -**类型**: 前端BUG -**紧急程度**: 高（正式环境所有资源编辑受影响） - ---- - -## 问题现象 - -1. **封面图上传后不显示**：保存成功但重新打开编辑页封面图为空 -2. **横幅图超过4张报500**（已通过后端改字段类型修复，但数据格式仍不对） - -## 根因 - -前端在提交资源编辑（酒店/景区/活动/餐厅等）时，**媒体素材字段传的是 OSS URL 而不是素材ID（数字）**。 - -### 具体表现 - -| 字段 | 应该传 | 实际传 | -|------|--------|--------| -| `coverMaterialId` | `"2036285563975241730"` | `"https://hlgl-test.oss-cn-beijing.aliyuncs.com/prod/material/xxx.jpg"` | -| `bannerMaterialIds` | `["2036285563975241730", "2036285563975241731"]` | `["https://...xxx.jpg", "https://...yyy.jpg"]` | -| `videoMaterialIds` | 同上 | 同上 | - -### 后果 - -- `coverMaterialId`：后端 `parseLongSafe` 解析URL失败返回null → 封面图不保存 -- `bannerMaterialIds`：URL字符串直接存入数据库 → 详情页无法通过素材服务解析出URL → 图片靠前端直接用URL显示，但后端素材引用关系断裂 - -## 修复方向 - -前端素材选择组件（MaterialSelect）返回值应该是**素材ID**，提交表单时传ID数组，而不是URL数组。 - -后端接口定义： -``` -coverMaterialId: String // 素材ID，如 "2036285563975241730" -bannerMaterialIds: List<String> // 素材ID数组 -videoMaterialIds: List<String> // 素材ID数组 -``` - -可参考 Knife4j 文档：`https://api.1814.love/doc.html` - -## 后端已完成的修复 - -- `banner_material_ids` / `video_material_ids` 列类型从 `varchar(512)` 改为 `TEXT`（所有资源表） -- `star_level` 从 `tinyint` 改为 `varchar(32)` -- 所有 `parseLongSafe` 容错（不再500，但数据存不进去） diff --git a/changelogs/2026-03/30_batch_staff.md b/changelogs/2026-03/30_batch_staff.md deleted file mode 100644 index ad09e5f..0000000 --- a/changelogs/2026-03/30_batch_staff.md +++ /dev/null @@ -1,45 +0,0 @@ -# 小程序产品详情团期返回服务人员 - -- **日期**: 2026-03-30 -- **PR**: #35 -- **服务**: hl-product-service -- **类型**: feat - -## 变更内容 - -`GET /mp/product/{productId}` 产品详情接口中，团期(batches)列表新增 `staff` 字段。 - -### 新增字段 - -| 字段路径 | 类型 | 说明 | -|---------|------|------| -| batches[].staff | Array | 服务人员列表 | -| batches[].staff[].staffName | String | 姓名 | -| batches[].staff[].staffRole | String | 角色(GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER) | -| batches[].staff[].staffPhone | String | 脱敏手机号(138****8000) | - -### 返回示例 - -```json -{ - "batches": [ - { - "batchName": "第一期", - "departureDate": "2026-04-15", - "staff": [ - {"staffName": "张导", "staffRole": "GUIDE", "staffPhone": "138****8000"}, - {"staffName": "李摄影", "staffRole": "PHOTOGRAPHER", "staffPhone": "139****9000"} - ] - } - ] -} -``` - -## 前端影响 - -- 新增字段，向后兼容 -- 无人员时 staff 为空数组 - -## 需要重启 - -- hl-product-service diff --git a/changelogs/2026-03/30_early_bird_edit_product_display.md b/changelogs/2026-03/30_early_bird_edit_product_display.md deleted file mode 100644 index c9a0895..0000000 --- a/changelogs/2026-03/30_early_bird_edit_product_display.md +++ /dev/null @@ -1,29 +0,0 @@ -# 前端BUG：早鸟优惠编辑弹窗适用产品显示ID - -- **日期**: 2026-03-30 -- **类型**: 前端bug -- **页面**: 早鸟优惠管理 → 编辑弹窗 - -## 问题 - -编辑早鸟优惠计划时，"适用产品"标签显示产品ID（如 `2036977785322483713`）而非产品名称。 - -## 后端数据（已正确） - -`GET /admin/order/early-bird/{planId}` 返回： - -```json -{ - "productIds": ["2036977785322483713"], - "productNames": ["小蒙马亲子研学营 · 呼伦贝尔"] -} -``` - -- `productIds` 和 `productNames` 是一一对应的 -- 列表页已正确显示产品名称 - -## 前端需要修改 - -编辑弹窗回显适用产品时： -- **标签文字**：用 `productNames[i]` 显示 -- **内部值**：用 `productIds[i]` 作为提交值 diff --git a/changelogs/2026-03/30_fix_early_bird_detail.md b/changelogs/2026-03/30_fix_early_bird_detail.md deleted file mode 100644 index 1df2be2..0000000 --- a/changelogs/2026-03/30_fix_early_bird_detail.md +++ /dev/null @@ -1,27 +0,0 @@ -# 修复：产品详情早鸟优惠字段不返回 - -- **日期**: 2026-03-30 -- **PR**: #31 -- **服务**: hl-mp-service -- **类型**: fix - -## 问题 - -`GET /mp/product/{productId}` 产品详情接口的 earlyBirdDiscount、earlyBirdPlanName、earlyBirdText 始终为 null。 - -## 根因 - -内部调用 `/match` 接口时传 totalPrice=null，被价格校验拦截直接返回 null。 - -## 修复 - -改用 `/by-product` 接口按产品ID+日期+启用状态匹配，不依赖价格参数。 - -## 前端影响 - -- 无接口变更，字段不变 -- 修复后有早鸟计划的产品会正确返回 earlyBirdDiscount、earlyBirdPlanName、earlyBirdText - -## 需要重启 - -- hl-mp-service diff --git a/changelogs/2026-03/30_fix_early_bird_product_name.md b/changelogs/2026-03/30_fix_early_bird_product_name.md deleted file mode 100644 index 5affc18..0000000 --- a/changelogs/2026-03/30_fix_early_bird_product_name.md +++ /dev/null @@ -1,22 +0,0 @@ -# 修复：早鸟优惠适用产品回显ID而非名称 - -- **日期**: 2026-03-30 -- **PR**: #36 -- **服务**: hl-order-service -- **类型**: fix - -## 问题 - -管理端编辑早鸟优惠计划时，"适用产品"显示产品ID而非产品名称。 - -## 根因 - -获取产品名称时字段名写错：`productName` → 应为 `name`（ProductVO 字段名）。 - -## 前端影响 - -- 无接口变更，修复后适用产品会正确显示产品名称 - -## 需要重启 - -- hl-order-service diff --git a/changelogs/2026-03/30_fix_hotel_tags.md b/changelogs/2026-03/30_fix_hotel_tags.md deleted file mode 100644 index 2b9bc3b..0000000 --- a/changelogs/2026-03/30_fix_hotel_tags.md +++ /dev/null @@ -1,34 +0,0 @@ -# 修复：产品详情返回酒店风格标签 - -- **日期**: 2026-03-30 -- **PR**: #33, #34 -- **服务**: hl-resource-service, hl-product-service -- **类型**: fix - -## 问题 - -产品详情接口中酒店没有返回风格标签。 - -## 修复（两个PR） - -1. **PR #33** (hl-resource-service): 内部接口查询 hotel_tag_rel + hotel_tag 表返回实际标签名 -2. **PR #34** (hl-product-service): DayHotelVO 新增 tags 字段，行程构建时从 resourceDetail 填充 - -## 前端影响 - -- `itineraryDays[].hotels[].tags` 新增字段，返回标签名称列表（如 `["豪华体验", "含早餐", "亲子友好"]`） -- 无标签时为 null - -## 返回示例 - -```json -{ - "hotelName": "海拉尔洲际酒店", - "tags": ["豪华体验", "含早餐", "亲子友好"] -} -``` - -## 需要重启 - -- hl-resource-service -- hl-product-service diff --git a/changelogs/2026-03/31_1508_sync.md b/changelogs/2026-03/31_1508_sync.md deleted file mode 100644 index f7c7099..0000000 --- a/changelogs/2026-03/31_1508_sync.md +++ /dev/null @@ -1,72 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-31 15:09 - -## ⚠️ Breaking Changes (16) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 字典变更 - -**字典类型删除** - -- ❌ ~~`apply_role`~~（适用角色） -- ❌ ~~`document_type`~~（证件类型） -- ❌ ~~`test_e2e_chinese_cat`~~（中文分类测试） -- ❌ ~~`test_e2e_custom_cat`~~（custom cat test） -- ❌ ~~`test_e2e_debug_0318`~~（debug dict） -- ❌ ~~`test_e2e_debug_0318b`~~（debug dict 2） - -**字典项删除** - -| 字典 | 删除值 | 标签 | -| --- | --- | --- | -| `activity_category`（游玩项目分类） | ~~`archery_combat`~~ | 射箭搏击 | -| `activity_category`（游玩项目分类） | ~~`campfire_party`~~ | 篝火聚会 | -| `activity_category`（游玩项目分类） | ~~`food_craft`~~ | 美食手作 | -| `activity_category`（游玩项目分类） | ~~`motor_sport`~~ | 机动越野 | -| `activity_category`（游玩项目分类） | ~~`nature_explore`~~ | 自然探索 | -| `activity_category`（游玩项目分类） | ~~`parent_child`~~ | 亲子互动 | -| `activity_category`（游玩项目分类） | ~~`water_sport`~~ | 水上项目 | -| `activity_category`（游玩项目分类） | ~~`winter_sport`~~ | 冬季项目 | - -**字典项状态变更** - -| 字典 | 值 | 原状态 | 新状态 | -| --- | --- | --- | --- | -| `activity_category`（游玩项目分类） | `cultural_experience` | ACTIVE | INACTIVE | -| `activity_category`（游玩项目分类） | `horse_riding` | ACTIVE | INACTIVE | - -## ℹ️ 新增 (20) - -### 字典变更 - -**新增字典项** - -| 字典 | 新增值 | 标签 | -| --- | --- | --- | -| `activity_category`（游玩项目分类） | `ARCHERY_COMBAT` | 射箭搏击 | -| `activity_category`（游玩项目分类） | `CAMPFIRE_PARTY` | 篝火聚会 | -| `activity_category`（游玩项目分类） | `FOOD_CRAFT` | 美食手作 | -| `activity_category`（游玩项目分类） | `MOTOR_SPORT` | 机动越野 | -| `activity_category`（游玩项目分类） | `NATURE_EXPLORE` | 自然探索 | -| `activity_category`（游玩项目分类） | `PARENT_CHILD` | 亲子互动 | -| `activity_category`（游玩项目分类） | `WATER_SPORT` | 水上项目 | -| `activity_category`（游玩项目分类） | `WINTER_SPORT` | 冬季项目 | -| `drive_type`（驱动方式） | `2WD` | 两驱 | -| `drive_type`（驱动方式） | `4WD` | 四驱 | -| `drive_type`（驱动方式） | `AWD` | 全时四驱 | -| `transmission`（变速箱） | `AUTO` | 自动挡 | -| `transmission`（变速箱） | `CVT` | 无级变速 | -| `transmission`（变速箱） | `DCT` | 双离合 | -| `transmission`（变速箱） | `MANUAL` | 手动挡 | -| `transport_type`（交通类型） | `BUS` | 大巴 | -| `transport_type`（交通类型） | `FLIGHT` | 航班 | -| `transport_type`（交通类型） | `SELF_DRIVE` | 自驾 | -| `transport_type`（交通类型） | `TRAIN` | 火车 | - -**字典项标签修改** - -| 字典 | 值 | 原标签 | 新标签 | -| --- | --- | --- | --- | -| `activity_category`（游玩项目分类） | `HORSEBACK` | 骑马体验 | 马术骑行 | diff --git a/changelogs/2026-03/31_feat_young_child_baby_price_mode.md b/changelogs/2026-03/31_feat_young_child_baby_price_mode.md deleted file mode 100644 index 8a3da44..0000000 --- a/changelogs/2026-03/31_feat_young_child_baby_price_mode.md +++ /dev/null @@ -1,65 +0,0 @@ -# 小童/幼童定价模式扩展 - -**日期**: 2026-03-31 -**PR**: #83 -**类型**: feat（新功能） -**影响服务**: hl-product-service, hl-mp-service - ---- - -## 变更说明 - -小童和幼童的定价方式从固定模式改为"百分比 / 固定价"二选一。 - -### 之前 -- 小童：只能按儿童价百分比（`childDiscountPercent`） -- 幼童：只能用固定价（`babyPrice`） - -### 现在 -- 小童：**百分比**或**固定价**，由 `youngChildPriceMode` 控制 -- 幼童：**百分比**或**固定价**，由 `babyPriceMode` 控制 -- 百分比基数统一为**儿童售价** - ---- - -## 新增字段（定价配置接口） - -### POST/PUT `/api/product/internal/{productId}/pricing` - -| 字段 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `youngChildPriceMode` | String | `"PERCENT"` | 小童定价模式：`PERCENT`=按儿童价百分比, `FIXED`=固定价 | -| `youngChildFixedPrice` | BigDecimal | null | 小童固定价格（`FIXED`模式时使用） | -| `babyPriceMode` | String | `"FIXED"` | 幼童定价模式：`PERCENT`=按儿童价百分比, `FIXED`=固定价 | -| `babyDiscountPercent` | BigDecimal | null | 幼童折扣百分比（`PERCENT`模式时使用，如50=儿童价的50%） | - -### GET `/api/product/internal/{productId}/pricing` 响应同步新增以上4个字段 - ---- - -## 前端适配要点 - -### 管理后台 - 定价配置页面 - -1. **小童定价**区域新增切换： - - 百分比模式（默认）：显示 `childDiscountPercent` 输入框（已有） - - 固定价模式：显示 `youngChildFixedPrice` 输入框（新增） - -2. **幼童定价**区域新增切换： - - 固定价模式（默认）：显示 `babyPrice` 输入框（已有） - - 百分比模式：显示 `babyDiscountPercent` 输入框（新增） - -### 小程序端 - -无需改动。价格日历返回的 `youngChildPrice` 和 `babyPrice` 已经是计算后的最终价格。 - ---- - -## 向后兼容 - -- 不传 `youngChildPriceMode`/`babyPriceMode` 时使用默认值，行为与改动前完全一致 -- 已有产品数据无需迁移 - -## 部署注意 - -需要执行 SQL 迁移脚本：`sql/young_child_baby_price_mode.sql` diff --git a/changelogs/2026-03/31_fix_dict_cleanup.md b/changelogs/2026-03/31_fix_dict_cleanup.md deleted file mode 100644 index 8ee79cd..0000000 --- a/changelogs/2026-03/31_fix_dict_cleanup.md +++ /dev/null @@ -1,53 +0,0 @@ -# 字典数据全面清理 - -**日期**: 2026-03-31 -**PR**: #86 -**类型**: fix -**影响服务**: hl-user-service, hl-resource-service - -## 变更内容 - -### 1. 新增3个字典（之前为空） - -| 字典类型 | 说明 | 可选值 | -|----------|------|--------| -| `transport_type` | 交通类型 | `FLIGHT`(航班), `TRAIN`(火车), `BUS`(大巴), `SELF_DRIVE`(自驾) | -| `transmission` | 变速箱 | `AUTO`(自动挡), `MANUAL`(手动挡), `DCT`(双离合), `CVT`(无级变速) | -| `drive_type` | 驱动方式 | `2WD`(两驱), `4WD`(四驱), `AWD`(全时四驱) | - -### 2. 已禁用的字典（不再返回） - -| 字典类型 | 原因 | -|----------|------| -| `document_type` | 冗余，统一使用 `id_card_type` | -| `apply_role` | 冗余，统一使用 `cost_apply_role` | -| 4个 `test_e2e_*` | 测试残留 | - -### 3. activity_category 值变更（重要！） - -所有值统一为 UPPER_CASE，**前端如果有硬编码旧值需要更新**： - -| 旧值 (snake_case) | 新值 (UPPER_CASE) | 标签 | -|-------|-------|------| -| `horse_riding` | → `HORSEBACK` | 马术骑行 | -| `cultural_experience` | → `CULTURAL` | 文化体验 | -| `motor_sport` | → `MOTOR_SPORT` | 机动越野 | -| `water_sport` | → `WATER_SPORT` | 水上项目 | -| `archery_combat` | → `ARCHERY_COMBAT` | 射箭搏击 | -| `food_craft` | → `FOOD_CRAFT` | 美食手作 | -| `nature_explore` | → `NATURE_EXPLORE` | 自然探索 | -| `campfire_party` | → `CAMPFIRE_PARTY` | 篝火聚会 | -| `winter_sport` | → `WINTER_SPORT` | 冬季项目 | -| `parent_child` | → `PARENT_CHILD` | 亲子互动 | - -> 原本已经是 UPPER_CASE 的值不变：OUTDOOR, OUTDOOR_SPORT, ENTERTAINMENT, ANIMAL, EXTREME, EDUCATION, PHOTOGRAPHY, PERFORMANCE, CATERING, DINING - -### 4. contract_status 排序修正 - -`SIGNING`(签署中) 和 `PENDING_SIGN`(待签署) 不再共享 sort=3，已顺延修正。 - -## 前端需要做的事 - -1. **检查是否硬编码了 activity_category 的旧 snake_case 值**，如果有需要改为新的 UPPER_CASE 值 -2. 如果前端是通过字典接口动态获取的，则**无需修改**，刷新缓存即可 -3. 车辆管理表单现在可以使用 `transmission` 和 `drive_type` 字典了 diff --git a/changelogs/2026-03/31_fix_order_detail_500.md b/changelogs/2026-03/31_fix_order_detail_500.md deleted file mode 100644 index 7d66dd3..0000000 --- a/changelogs/2026-03/31_fix_order_detail_500.md +++ /dev/null @@ -1,23 +0,0 @@ -# fix: 订单详情页500错误修复 - -**日期**: 2026-03-31 -**PR**: #95 -**影响服务**: hl-order-service -**影响范围**: 后台管理 - 订单详情页、订单列表中的合同/保险字段 - -## 问题描述 - -订单详情页打开报"服务器内部错误"（500），所有字段显示为空。 - -## 根因 - -服务合并（11→5）后，合同服务和保险服务合并到了 order-service 中。原来通过 Feign 远程调用时，返回的 JSON 会被反序列化为 `Map<String, Object>`；合并后变成本地调用，直接返回 `ContractVO` / `InsuranceOrderVO` 对象，但代码仍然按 Map 遍历，触发 `ClassCastException`。 - -## 修复内容 - -- 用 `ObjectMapper.convertValue()` 将 VO 对象正确转换为 Map -- 涉及4处调用点（单个订单详情 + 批量订单列表） - -## 前端影响 - -**无**。接口返回的数据结构不变，前端无需任何修改。之前报500的订单详情页现在可以正常打开。 diff --git a/changelogs/2026-03/31_fix_price_calendar_simplify.md b/changelogs/2026-03/31_fix_price_calendar_simplify.md deleted file mode 100644 index b0551bc..0000000 --- a/changelogs/2026-03/31_fix_price_calendar_simplify.md +++ /dev/null @@ -1,31 +0,0 @@ -# C端价格日历接口精简 + 产品审批修复 - -- **日期**: 2026-03-31 -- **PR**: #93, #94 -- **类型**: fix / feat -- **影响服务**: hl-product-service - -## 变更内容 - -### 1. 价格日历精简（#93） - -**接口**: `GET /mp/product/{productId}/price-calendar` - -移除 `childWithBedFee` 字段，现在每天只返回 **4个价格**： - -| 字段 | 含义 | -|------|------| -| `adultPrice` | 成人价 | -| `childPrice` | 儿童不占床价 | -| `youngChildPrice` | 小童价 | -| `babyPrice` | 幼童价 | - -### 2. 产品审批回调修复（#94） - -- 恢复 `ProductApprovalConsumer`（MQ消费者），修复企微审批回调链路断裂 -- 新增 `ApprovalPollingService`，每30秒轮询企微API作为兜底 - -## 前端影响 - -- 如果之前有使用 `childWithBedFee` 字段，需要移除相关引用 -- 产品审批状态将正常自动更新，无需前端改动 diff --git a/changelogs/2026-03/31_fix_refund_stuck_refunding.md b/changelogs/2026-03/31_fix_refund_stuck_refunding.md deleted file mode 100644 index 10e2fd0..0000000 --- a/changelogs/2026-03/31_fix_refund_stuck_refunding.md +++ /dev/null @@ -1,22 +0,0 @@ -# fix: 修复退款卡死在REFUNDING状态的问题 - -- **日期**: 2026-03-31 -- **PR**: #76 -- **影响服务**: hl-order-service - -## 变更内容 - -### 后端修复（无接口变更） - -1. **退款事务隔离修复**：`RefundService.createRefund()` 事务传播改为 `REQUIRES_NEW`，修复退款失败时状态无法正确回滚的问题 -2. **新增卡死恢复定时任务**：每120秒自动扫描超过5分钟卡在 REFUNDING 状态的退款申请，恢复为 APPROVED 自动重试 - -### 测试环境数据修复 - -- HL2603-WX-004：退款状态从卡死恢复，将自动重试 -- HL2603-XX-002：0元退款已完成 -- HL2603-SL-001：微信回调丢失，已手动标记完成 - -## 前端影响 - -**无**。纯后端逻辑修复，无接口变更。 diff --git a/changelogs/2026-03/31_refactor_price_calendar_field_rename.md b/changelogs/2026-03/31_refactor_price_calendar_field_rename.md deleted file mode 100644 index 0fccf3a..0000000 --- a/changelogs/2026-03/31_refactor_price_calendar_field_rename.md +++ /dev/null @@ -1,48 +0,0 @@ -# 价格日历接口字段优化（price→adultPrice） - -- **日期**: 2026-03-31 -- **服务**: hl-product-service, hl-mp-service -- **PR**: #91 - -## ⚠️ 破坏性变更 - -### `GET /mp/product/{id}/price-calendar` - -**字段重命名**： -| 旧字段 | 新字段 | 说明 | -|--------|--------|------| -| `price` | `adultPrice` | 成人价格，与其他人员类型命名保持一致 | - -**移除字段**： -- `id` — 价格日历记录ID，前端无需使用 -- `productId` — 已在URL路径中，无需重复返回 -- `dateStr` — 与 `date` 重复 - -**完整响应结构**（每日一条）： -```json -{ - "date": "2026-04-01", - "adultPrice": 3980, - "childPrice": 2980, - "youngChildPrice": 1490, - "babyPrice": 500, - "childWithBedFee": 200, - "stock": 10, - "sold": 2, - "status": 1, - "remark": null -} -``` - -**4种人员类型价格**： -| 字段 | 说明 | -|------|------| -| `adultPrice` | 成人价格 | -| `childPrice` | 儿童价格（占床） | -| `youngChildPrice` | 小童价格（不占床） | -| `babyPrice` | 幼童价格 | - -## 前端需要改动 - -1. 价格日历组件中 `price` 改为 `adultPrice` -2. 移除对 `id`、`productId`、`dateStr` 的依赖（如有） diff --git a/changelogs/2026-03/31_scheme_delete_validation.md b/changelogs/2026-03/31_scheme_delete_validation.md deleted file mode 100644 index c668f01..0000000 --- a/changelogs/2026-03/31_scheme_delete_validation.md +++ /dev/null @@ -1,75 +0,0 @@ -# 保险方案/合同方案 — 支持删除 + 引用校验 - -> **PR** #92 · **日期** 2026-03-31 · **影响服务** hl-order-service, hl-product-service - -## 前端需要做什么 - -保险方案和合同方案的管理页面需要**新增删除按钮**，后端接口已就绪。 - ---- - -## 1. 保险方案删除 - -### `DELETE` /admin/insurance/scheme/{id} - -> 网关路径：`/order/admin/insurance/scheme/{id}` - -**请求**：无 body，路径参数 `id` 为方案ID - -**成功响应**： -```json -{ "code": 200, "data": null } -``` - -**失败响应**（被产品引用时）： -```json -{ "code": 500, "message": "无法删除：以下产品正在使用该保险方案：精品九寨沟5日游、云南大理7日游" } -``` - ---- - -## 2. 合同方案删除 - -### `DELETE` /admin/contract/scheme/{schemeId} - -> 网关路径：`/order/admin/contract/scheme/{schemeId}` - -**请求**：无 body，路径参数 `schemeId` 为方案ID - -**成功响应**： -```json -{ "code": 200, "data": null } -``` - -**失败响应**（被产品引用时）： -```json -{ "code": 500, "message": "无法删除：以下产品正在使用该合同方案：精品九寨沟5日游" } -``` - ---- - -## 3. 禁用校验（已有接口行为变更） - -以下两个已有的**切换状态**接口增加了校验逻辑： - -- `PUT /admin/insurance/scheme/{id}/toggle-status` -- `PUT /admin/contract/scheme/{schemeId}/toggle-status` - -**变更**：从启用→停用时，如果有活跃产品（已上架/已下单/已完成/待审核/已审核）引用该方案，将返回错误： - -```json -{ "code": 500, "message": "无法禁用：以下产品正在使用该保险方案：精品九寨沟5日游" } -``` - -> 启用→停用被阻止时，前端正常展示错误提示即可。 - ---- - -## 4. 前端交互建议 - -| 操作 | 建议 | -|------|------| -| 删除按钮位置 | 方案列表每行操作栏，与编辑/启停按钮并列 | -| 删除确认 | 点击删除前弹二次确认对话框（"确定删除该方案？"） | -| 错误处理 | 删除/禁用失败时，展示后端返回的 message（含引用的产品名） | -| 删除成功 | 刷新列表 | diff --git a/changelogs/2026-04/01_1528_sync.md b/changelogs/2026-04/01_1528_sync.md deleted file mode 100644 index 7c44c10..0000000 --- a/changelogs/2026-04/01_1528_sync.md +++ /dev/null @@ -1,14 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-04-01 15:29 - -## ℹ️ 新增 (2) - -### 字典变更 - -**新增字典项** - -| 字典 | 新增值 | 标签 | -| --- | --- | --- | -| `staff_type`（人员类型） | `LIFE_TEACHER` | 生活老师 | -| `staff_type`（人员类型） | `STUDY_TEACHER` | 研学老师 | diff --git a/changelogs/2026-04/01_fix_product_unpublish_approval_check.md b/changelogs/2026-04/01_fix_product_unpublish_approval_check.md deleted file mode 100644 index c598151..0000000 --- a/changelogs/2026-04/01_fix_product_unpublish_approval_check.md +++ /dev/null @@ -1,16 +0,0 @@ -# fix: 产品下架审批检查误拦截修复 - -- **日期**: 2026-04-01 -- **PR**: #99 -- **影响服务**: hl-product-service - -## 变更内容 - -### 后端修复（无接口变更） - -1. **产品下架误拦截修复**：产品"已上架+审批通过"状态下点击下架，原逻辑仅检查 `approvalNo != null` 就拒绝操作，改为同时检查 `approvalStatus == PENDING`，只有真正在审批中才拦截 -2. **修复范围**：`changeStatus` 和 `submitProductApproval` 两处检查点同步修复 - -## 前端影响 - -**无**。纯后端逻辑修复，无接口变更。修复后"已上架"产品可正常下架。 diff --git a/changelogs/2026-04/01_fix_restaurant_json_empty_string.md b/changelogs/2026-04/01_fix_restaurant_json_empty_string.md deleted file mode 100644 index 96b708a..0000000 --- a/changelogs/2026-04/01_fix_restaurant_json_empty_string.md +++ /dev/null @@ -1,16 +0,0 @@ -# fix: 餐厅JSON字段空字符串导致保存报错 - -- **日期**: 2026-04-01 -- **PR**: #100 -- **影响服务**: hl-resource-service - -## 变更内容 - -### 后端修复（无接口变更） - -1. **餐厅保存约束违反修复**：编辑餐厅时 `featured_menu`、`feature_intro`、`arrangement` 等JSON类型字段传空字符串，MySQL JSON列不接受空字符串报错。空字符串统一转为null处理 -2. **修复范围**：创建和更新方法的3个JSON字符串字段同步修复 - -## 前端影响 - -**无**。纯后端防御性修复，无接口变更。修复后编辑餐厅位置信息不再报错。 diff --git a/changelogs/2026-04/01_fix_staff_gender_validation.md b/changelogs/2026-04/01_fix_staff_gender_validation.md deleted file mode 100644 index b19e47e..0000000 --- a/changelogs/2026-04/01_fix_staff_gender_validation.md +++ /dev/null @@ -1,16 +0,0 @@ -# fix: 服务人员性别校验与字典不一致 - -- **日期**: 2026-04-01 -- **PR**: #102 -- **影响服务**: hl-resource-service - -## 变更内容 - -### 后端修复（无接口变更） - -1. **性别校验修复**：字典定义 gender: 1=男 2=女，但后端 `@Max(1)` 导致选「女」时报错。修正为 `@Min(1) @Max(2)` -2. **修复范围**：StaffCreateRequest 和 StaffUpdateRequest 两个 DTO - -## 前端影响 - -**无**。纯后端校验修复，无接口变更。修复后可正常保存女性服务人员。 diff --git a/changelogs/2026-04/02_1334_sync.md b/changelogs/2026-04/02_1334_sync.md deleted file mode 100644 index 8c59c6e..0000000 --- a/changelogs/2026-04/02_1334_sync.md +++ /dev/null @@ -1,11 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-04-02 13:35 - -## ℹ️ 新增 (1) - -### 字典变更 - -**新增字典类型** - -- 🆕 `product_grade`（产品等级） diff --git a/changelogs/2026-04/0402-product-grade.md b/changelogs/2026-04/0402-product-grade.md deleted file mode 100644 index 8bccb3b..0000000 --- a/changelogs/2026-04/0402-product-grade.md +++ /dev/null @@ -1,133 +0,0 @@ -# 产品版本分组（基于产品线）+ 产品线详情接口 (PR #129-#137) - -> 日期: 2026-04-02 | 服务: hl-product-service, hl-mp-service | 需重启: 是 - -## 功能概述 - -1. **产品版本分组**：同一产品线下的已上架产品自动视为不同版本，列表合并为一张卡片，详情页可切换版本 -2. **产品线详情接口**：一次请求返回产品线信息 + 所有产品摘要 + 第一个产品完整详情 -3. **产品线绑定产品类型**：创建产品线时指定类型，创建产品时按类型筛选产品线 - -## 核心概念 - -- 产品名本身就是版本名（如"呼伦贝尔5天·轻奢版"、"呼伦贝尔5天·高档版"） -- 同一产品线下有 2 个以上已上架产品时，自动返回版本切换选项（`gradeOptions`） -- 产品线只有 1 个产品时，表现和之前完全一样 - ---- - -## 接口变更 - -### 1. 产品列表（C端） -**接口**: `GET /mp/product/list` - -同一产品线的产品只返回一条，附带所有版本选项。 - -**新增返回字段**: -| 字段 | 类型 | 说明 | -|------|------|------| -| `gradeOptions` | Array | 同产品线版本选项，null=独立产品或仅一个版本 | -| `gradeOptions[].productId` | String | 该版本的产品ID | -| `gradeOptions[].name` | String | 产品名（即版本名） | -| `gradeOptions[].startPrice` | Number | 起步价 | -| `gradeOptions[].startPriceLabel` | String | "起" 或 "订金起" | - -**返回示例（有多版本）**: -```json -{ - "productId": "123", - "name": "呼伦贝尔5天·轻奢版", - "gradeOptions": [ - {"productId": "123", "name": "呼伦贝尔5天·轻奢版", "startPrice": 3999, "startPriceLabel": "起"}, - {"productId": "456", "name": "呼伦贝尔5天·高档版", "startPrice": 6999, "startPriceLabel": "起"} - ] -} -``` - -**无版本的产品（不受影响）**: -```json -{ - "productId": "789", - "name": "丽江3天自由行", - "gradeOptions": null -} -``` - -### 2. 产品详情（C端） -**接口**: `GET /mp/product/{productId}` - -product 对象中新增 `gradeOptions`（同上，null=无版本切换）。 - -**切换版本方式**: 用 `gradeOptions` 中其他版本的 `productId` 重新调用此接口。 - -### 3. [新增] 产品线详情 -**接口**: `GET /mp/product/line/{lineId}` -**用途**: 小程序产品线详情页，一次请求加载全部数据 -**返回结构**: -```json -{ - "line": { - "lineId": "123", - "lineName": "呼伦贝尔亲子游", - "productType": "CORE", - "productCount": 2 - }, - "products": [ - // 该产品线下所有已上架产品摘要（不去重） - {"productId": "123", "name": "轻奢版", "startPrice": 3999, ...}, - {"productId": "456", "name": "高档版", "startPrice": 6999, ...} - ], - "defaultProduct": { - // 第一个产品的完整详情（含行程、酒店、评价等聚合数据） - // 结构同 GET /mp/product/{productId} 返回的 product 对象 - } -} -``` - -### 4. 产品线接口变更 -**接口**: `GET /admin/product/line/active` -**新增参数**: `productType`（可选，CORE/GROUP/CUSTOM/ROUTE） -**行为**: 传参时只返回该类型的产品线 + 未绑定类型的产品线 - -**接口**: `POST /admin/product/line`（创建产品线） -**新增请求字段**: `productType`（可选，绑定产品类型） - -**产品线VO新增字段**: `productType` - -### 5. 已删除接口 -- `GET /admin/product/item/grade-groups` — 不再需要 - ---- - -## 前端开发指引 - -### 列表页 -- `gradeOptions != null && gradeOptions.length > 1` 时，显示版本选项 -- 卡片示例: `[轻奢版 ￥3,999起] [高档版 ￥6,999起]`（用 name + startPrice） -- `gradeOptions == null` 的产品照常展示 - -### 详情页 -- `gradeOptions != null && gradeOptions.length > 1` 时，顶部显示版本切换tab -- 当前版本高亮（匹配 productId） -- 点击其他版本 → 用该 productId 重新请求详情 -- 报价/下单用当前 productId - -### 产品线详情页（新页面） -- 调用 `GET /mp/product/line/{lineId}` -- `defaultProduct` 直接渲染产品详情 -- `products` 列表做顶部版本切换tab -- 切换版本时调用 `GET /mp/product/{productId}` 获取新详情 - -### 管理端-创建产品 -- 选择产品类型后，产品线下拉调用 `GET /admin/product/line/active?productType=CORE` -- 创建产品线时可指定 `productType` - ---- - -## DDL -```sql --- 产品线加类型（已执行） -ALTER TABLE product_line ADD COLUMN product_type VARCHAR(16) DEFAULT NULL AFTER name; - --- grade_group_id 已删除（已执行） -``` diff --git a/changelogs/2026-04/0415-mp-detail-fields.md b/changelogs/2026-04/0415-mp-detail-fields.md deleted file mode 100644 index 9467da4..0000000 --- a/changelogs/2026-04/0415-mp-detail-fields.md +++ /dev/null @@ -1,71 +0,0 @@ -# 小程序产品接口字段补全+bug修复 - -**日期**: 2026-04-15 -**服务**: hl-product-service-v2 -**影响**: 小程序端产品相关页面 - ---- - -## 1. MP产品详情 `GET /mp/product/{id}` — 新增字段 - -### 基础信息 -| 字段 | 类型 | 说明 | -|------|------|------| -| `tags` | `List<String>` | 产品标签，如`["亲子","露营"]` | -| `seasons` | `List<String>` | 产品季节，如`["summer"]` | -| `lineId` | `Long` | 产品线ID（面包屑导航用） | -| `lineName` | `String` | 产品线名称 | -| `tiers` | `Array` | 档位列表（行程报价区块），如`[{"tierSeq":1,"tierName":"舒适"}]` | -| `startPrice` | `BigDecimal` | 起步价（未来可售最低成人售价） | - -### 路线概览 -| 字段 | 类型 | 说明 | -|------|------|------| -| `totalMileage` | `BigDecimal` | 总里程(km) | -| `routeDescription` | `String` | 路线描述文本 | - -### 营销内容 -| 字段 | 类型 | 说明 | -|------|------|------| -| `quickUnderstand` | `Object` | 快速理解（JSON对象） | -| `childExperience` | `Object` | 孩子经历 | -| `growthGains` | `Object` | 成长收获 | -| `yearReview` | `Object` | 年度回顾视频 | -| `closing` | `Object` | 写在最后 | - -### 保障须知 -| 字段 | 类型 | 说明 | -|------|------|------| -| `safetyItems` | `Array` | 安全保障项（如`[{"title":"保险","desc":"50万"}]`） | -| `faqItems` | `Array` | FAQ问答 | -| `bookingTermsContent` | `String` | 预订条款内容（HTML） | -| `warmTipsContent` | `String` | 温馨提示内容（HTML） | -| `insuranceNotice` | `String` | 保险告知（INCLUDED/EXCLUDED/OPTIONAL） | -| `equipmentAdvice` | `String` | 装备建议（HTML） | - -### 行程天 `itinerary[].` 新增 -| 字段 | 类型 | 说明 | -|------|------|------| -| `photoUrls` | `List<String>` | 行程天照片列表 | -| `hotels` | `Array` | 每日住宿，`[{"hotelName":"xxx","tierSeq":1}]` | - -### 人群优惠 `crowdBenefit.` 新增 -| 字段 | 类型 | 说明 | -|------|------|------| -| `elderAccommodation` | `String` | 老人住宿（之前遗漏） | - ---- - -## 2. 产品对比接口变更 - -**旧**: `GET /mp/product/compare?ids=1,2,3` -**新**: `POST /mp/product/compare?lineId={产品线ID}` - -传入产品线ID，自动返回该线下所有已上架产品的详情列表，无需前端知道具体产品ID。 - ---- - -## 3. Bug修复 - -- **产品线列表过滤**: `GET /mp/product-line/list` 现在只返回有上架产品的产品线（之前返回所有启用的线，包括空线） -- **网关白名单**: `/mp/product/*/schedules` 和 `/mp/product/*/tier-compare` 已加入JWT跳过列表，无需登录 diff --git a/changelogs/2026-04/0415-product-action-split.md b/changelogs/2026-04/0415-product-action-split.md deleted file mode 100644 index ef68490..0000000 --- a/changelogs/2026-04/0415-product-action-split.md +++ /dev/null @@ -1,101 +0,0 @@ -# 产品状态变更接口拆分 - -**日期**: 2026-04-15 -**服务**: hl-product-service-v2 -**影响**: 管理端产品管理 - ---- - -## 变更概要 - -原 `POST /admin/product/item/{id}/action` 接口拆分为2个独立接口，**前端不再需要传动作码**，后端自动判断。旧接口保留但已废弃。 - ---- - -## 新增接口 - -### 1. 上架/下架切换 - -``` -POST /admin/product/item/{id}/toggle-publish -``` - -**请求体**（可选）: -```json -{ - "remark": "备注原因（可选）" -} -``` - -**后端自动逻辑**: -| 当前状态 | 普通用户 | 超管(SUPER_ADMIN) | -|----------|----------|-------------------| -| 草稿/已驳回/已下架 | 提交上架审批→待审核 | 直接上架→已上架 | -| 已上架 | 申请下架审批→待审核 | 强制下架→已下架 | -| 待审核 | 撤回→草稿 | 撤回→草稿 | - -**审批流程**: 普通用户上架/下架会自动提交企微OA审批，审批通过后自动变更状态，无需前端处理。 - -**响应**: -```json -{ - "code": 200, - "message": "操作成功", - "data": null -} -``` - -### 2. 完成设计（仅定制产品） - -``` -POST /admin/product/item/{id}/complete -``` - -**请求体**（可选）: -```json -{ - "remark": "备注（可选）" -} -``` - -**限制**: 仅 `productType=CUSTOM` 的草稿产品可调用，其他类型返回500。 - -**响应**: -```json -{ - "code": 200, - "message": "完成设计成功", - "data": null -} -``` - ---- - -## 废弃接口 - -### ~~POST /admin/product/item/{id}/action~~ - -**状态**: @Deprecated，暂时保留兼容，后续版本移除。 - -请尽快迁移到上述2个新接口。 - ---- - -## 人群优惠bug修复 - -`GET /admin/product/item/{id}` 返回的 `crowdBenefit` 对象之前只有 `tips` 字段，现在完整返回所有字段： - -```json -{ - "crowdBenefit": { - "childTicket": "HALF_PRICE", - "childAccommodation": "NO_BED", - "childMeal": "HALF", - "elderTicket": "FREE", - "elderAccommodation": "SAME_AS_ADULT", - "tips": "3岁以下免费" - } -} -``` - -**前端无需改动**，之前缺失的字段现在正常返回。 diff --git a/changelogs/2026-04/12_1537_sync.md b/changelogs/2026-04/12_1537_sync.md deleted file mode 100644 index 7327889..0000000 --- a/changelogs/2026-04/12_1537_sync.md +++ /dev/null @@ -1,142 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-04-12 15:38 - -## ⚠️ Breaking Changes (10) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 支付服务 - -**接口删除** - -- ❌ ~~`GET /admin/payment/list`~~ -- ❌ ~~`GET /admin/payment/merchants`~~ -- ❌ ~~`GET /admin/payment/order/{orderId}`~~ -- ❌ ~~`GET /admin/payment/refund/order/{orderId}`~~ -- ❌ ~~`GET /admin/payment/refund/{refundId}`~~ -- ❌ ~~`GET /admin/payment/{transactionId}`~~ -- ❌ ~~`POST /admin/payment/{orderId}/refund`~~ -- ❌ ~~`POST /admin/payment/{transactionId}/sync`~~ - -### 用户服务 - -**字段类型变化** - -| 数据对象 | 字段 | 原类型 | 新类型 | -| --- | --- | --- | --- | -| `Traveler` | `gender` | `integer(int32)` | `string` | -| `出行人请求` | `gender` | `integer(int32)` | `string` | - -## ℹ️ 新增 (99) - -### 支付服务 - -**新增接口** - -- 🆕 `DELETE /admin/product/item/{id}` -- 🆕 `DELETE /admin/product/item/{id}/itinerary/day/{dayNumber}` -- 🆕 `DELETE /admin/product/item/{id}/price-calendar` -- 🆕 `DELETE /admin/product/item/{id}/schedule/{scheduleId}` -- 🆕 `DELETE /admin/product/line/{id}` -- 🆕 `GET /admin/product/booking-terms/enabled` -- 🆕 `GET /admin/product/item/list` -- 🆕 `GET /admin/product/item/{id}` -- 🆕 `GET /admin/product/item/{id}/fee-deduction-preview` -- 🆕 `GET /admin/product/item/{id}/operation-logs` -- 🆕 `GET /admin/product/item/{id}/price-calendar` -- 🆕 `GET /admin/product/item/{id}/schedule/list` -- 🆕 `GET /admin/product/item/{id}/schedule/team` -- 🆕 `GET /admin/product/item/{id}/validate-publish` -- 🆕 `GET /admin/product/line/list` -- 🆕 `GET /admin/product/line/simple-list` -- 🆕 `GET /admin/product/line/{id}` -- 🆕 `GET /admin/product/safety-template/enabled` -- 🆕 `GET /admin/product/warm-tips/enabled` -- 🆕 `GET /mp/product-line/list` -- 🆕 `GET /mp/product-line/{lineId}/products` -- 🆕 `GET /mp/product/compare` -- 🆕 `GET /mp/product/{id}` -- 🆕 `GET /mp/product/{id}/price-calendar` -- 🆕 `GET /mp/product/{id}/schedules` -- 🆕 `GET /mp/product/{id}/tier-compare` -- 🆕 `POST /admin/product/item` -- 🆕 `POST /admin/product/item/{id}/action` -- 🆕 `POST /admin/product/item/{id}/copy` -- 🆕 `POST /admin/product/item/{id}/itinerary/day` -- 🆕 `POST /admin/product/item/{id}/price-calendar/batch` -- 🆕 `POST /admin/product/item/{id}/quote` -- 🆕 `POST /admin/product/item/{id}/schedule` -- 🆕 `POST /admin/product/item/{id}/schedule/batch-create` -- 🆕 `POST /admin/product/item/{id}/schedule/{scheduleId}/cancel` -- 🆕 `POST /admin/product/line` -- 🆕 `POST /mp/product/{id}/quote` -- 🆕 `PUT /admin/product/item/{id}/basic` -- 🆕 `PUT /admin/product/item/{id}/itinerary` -- 🆕 `PUT /admin/product/item/{id}/route` -- 🆕 `PUT /admin/product/item/{id}/schedule` -- 🆕 `PUT /admin/product/item/{id}/schedule/team` -- 🆕 `PUT /admin/product/item/{id}/supplement` -- 🆕 `PUT /admin/product/item/{id}/transfer` - -### 用户服务 - -**新增字段** - -| 数据对象 | 新增字段 | 类型 | -| --- | --- | --- | -| `字典数据项VO` | `remark` | `string` | -| `统一响应结果«Favorite»` | `success` | `boolean` | -| `统一响应结果«Footprint»` | `success` | `boolean` | -| `统一响应结果«List«Traveler»»` | `success` | `boolean` | -| `统一响应结果«List«字典VO»»` | `success` | `boolean` | -| `统一响应结果«Traveler»` | `success` | `boolean` | -| `统一响应结果«Void»` | `success` | `boolean` | -| `统一响应结果«boolean»` | `success` | `boolean` | -| `统一响应结果«分页结果«Favorite»»` | `success` | `boolean` | -| `统一响应结果«分页结果«Footprint»»` | `success` | `boolean` | -| `统一响应结果«用户信息VO»` | `success` | `boolean` | -| `统一响应结果«用户登录响应»` | `success` | `boolean` | -| `统一响应结果«AdminUser»` | `success` | `boolean` | -| `统一响应结果«List«旅行设计师VO»»` | `success` | `boolean` | -| `统一响应结果«Map«string,object»»` | `success` | `boolean` | -| `统一响应结果«分页结果«AdminUser»»` | `success` | `boolean` | -| `统一响应结果«Banner VO»` | `success` | `boolean` | -| `统一响应结果«分页结果«Banner VO»»` | `success` | `boolean` | -| `统一响应结果«分页结果«联系我们 VO»»` | `success` | `boolean` | -| `统一响应结果«联系我们 VO»` | `success` | `boolean` | -| `统一响应结果«分页结果«探索分类 VO»»` | `success` | `boolean` | -| `统一响应结果«探索分类详情 VO»` | `success` | `boolean` | -| `统一响应结果«List«string»»` | `success` | `boolean` | -| `统一响应结果«List«前端配置 VO»»` | `success` | `boolean` | -| `统一响应结果«分页结果«前端配置 VO»»` | `success` | `boolean` | -| `统一响应结果«前端配置 VO»` | `success` | `boolean` | -| `统一响应结果«List«常见问题分类VO»»` | `success` | `boolean` | -| `统一响应结果«List«常见问题条目VO»»` | `success` | `boolean` | -| `统一响应结果«常见问题分类VO»` | `success` | `boolean` | -| `统一响应结果«常见问题条目VO»` | `success` | `boolean` | -| `统一响应结果«分页结果«协议 VO»»` | `success` | `boolean` | -| `统一响应结果«协议 VO»` | `success` | `boolean` | -| `统一响应结果«管理员登录响应»` | `success` | `boolean` | -| `统一响应结果«List«SysRole»»` | `success` | `boolean` | -| `统一响应结果«SysRole»` | `success` | `boolean` | -| `统一响应结果«分页结果«SysRole»»` | `success` | `boolean` | -| `统一响应结果«List«SysMenu»»` | `success` | `boolean` | -| `统一响应结果«SysMenu»` | `success` | `boolean` | -| `统一响应结果«List«SysDictData»»` | `success` | `boolean` | -| `统一响应结果«SysDictData»` | `success` | `boolean` | -| `统一响应结果«SysDictType»` | `success` | `boolean` | -| `统一响应结果«分页结果«SysDictType»»` | `success` | `boolean` | -| `统一响应结果«分页结果«定时任务信息»»` | `success` | `boolean` | -| `统一响应结果«分页结果«定时任务执行日志»»` | `success` | `boolean` | -| `统一响应结果«定时任务信息»` | `success` | `boolean` | -| `统一响应结果«List«Map«string,object»»»` | `success` | `boolean` | -| `统一响应结果«List«WechatDepartment»»` | `success` | `boolean` | -| `统一响应结果«分页结果«WechatUser»»` | `success` | `boolean` | -| `统一响应结果«object»` | `success` | `boolean` | -| `统一响应结果«个人资料VO（角色感知）»` | `success` | `boolean` | -| `统一响应结果«分页结果«Map«string,object»»»` | `success` | `boolean` | -| `统一响应结果«定制师个人资料VO»` | `success` | `boolean` | -| `统一响应结果«定制师工作台VO（重构版）»` | `success` | `boolean` | -| `统一响应结果«分页结果«客户信息VO（管理端）»»` | `success` | `boolean` | -| `统一响应结果«客户信息VO（管理端）»` | `success` | `boolean` | diff --git a/changelogs/2026-04/13_1039_sync.md b/changelogs/2026-04/13_1039_sync.md deleted file mode 100644 index 5be57ef..0000000 --- a/changelogs/2026-04/13_1039_sync.md +++ /dev/null @@ -1,15 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-04-13 10:40 - -## ℹ️ 新增 (3) - -### 字典变更 - -**新增字典项** - -| 字典 | 新增值 | 标签 | -| --- | --- | --- | -| `product_status`（产品状态） | `ORDERED` | 已下单 | -| `product_status`（产品状态） | `PENDING_REVIEW` | 待审核 | -| `product_status`（产品状态） | `REJECTED` | 已驳回 | diff --git a/changelogs/2026-04/13_1811_sync.md b/changelogs/2026-04/13_1811_sync.md deleted file mode 100644 index ae03ebd..0000000 --- a/changelogs/2026-04/13_1811_sync.md +++ /dev/null @@ -1,165 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-04-13 18:12 - -## ⚠️ Breaking Changes (70) - -> **前端必须处理的变更，不处理会导致功能异常** - -### 支付服务 - -**接口删除** - -- ❌ ~~`POST /admin/product/item`~~ -- ❌ ~~`PUT /admin/product/item/{id}/basic`~~ - -**字段删除** - -| 数据对象 | 删除字段 | 原类型 | -| --- | --- | --- | -| `GroupTourBatchDO` | ~~`createBy`~~ | `integer(int64)` | -| `管理端 - Step1 基础信息保存` | ~~`balanceDueDays`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`carouselImages`~~ | `string[]` | -| `管理端 - Step1 基础信息保存` | ~~`childAgeMax`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`childAgeMin`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`contactPhone`~~ | `string` | -| `管理端 - Step1 基础信息保存` | ~~`creatorAvatarUrl`~~ | `string` | -| `管理端 - Step1 基础信息保存` | ~~`creatorIntro`~~ | `string` | -| `管理端 - Step1 基础信息保存` | ~~`customerName`~~ | `string` | -| `管理端 - Step1 基础信息保存` | ~~`customizerId`~~ | `integer(int64)` | -| `管理端 - Step1 基础信息保存` | ~~`defaultDailyStock`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`defaultRoomCount`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`departureDate`~~ | `string(date)` | -| `管理端 - Step1 基础信息保存` | ~~`depositAmount`~~ | `number` | -| `管理端 - Step1 基础信息保存` | ~~`depositRatio`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`diningHighlights`~~ | `object[]` | -| `管理端 - Step1 基础信息保存` | ~~`infantAgeMax`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`infantDefaultPrice`~~ | `number` | -| `管理端 - Step1 基础信息保存` | ~~`isBooking`~~ | `boolean` | -| `管理端 - Step1 基础信息保存` | ~~`maxAdultPerOrder`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`maxChildPerOrder`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`mchId`~~ | `string` | -| `管理端 - Step1 基础信息保存` | ~~`minAdultPerOrder`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`minGroupSize`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`paymentType`~~ | `string` | -| `管理端 - Step1 基础信息保存` | ~~`photographyItems`~~ | `object[]` | -| `管理端 - Step1 基础信息保存` | ~~`safetyItems`~~ | `object[]` | -| `管理端 - Step1 基础信息保存` | ~~`seasons`~~ | `string[]` | -| `管理端 - Step1 基础信息保存` | ~~`showChatGroup`~~ | `boolean` | -| `管理端 - Step1 基础信息保存` | ~~`showReview`~~ | `boolean` | -| `管理端 - Step1 基础信息保存` | ~~`showTripDistance`~~ | `boolean` | -| `管理端 - Step1 基础信息保存` | ~~`showTripTime`~~ | `boolean` | -| `管理端 - Step1 基础信息保存` | ~~`toddlerAgeMax`~~ | `integer(int32)` | -| `管理端 - Step1 基础信息保存` | ~~`version`~~ | `integer(int32)` | -| `管理端 - Step2 行程保存` | ~~`version`~~ | `integer(int32)` | -| `管理端 - Step3 路线与备品保存` | ~~`routeName`~~ | `string` | -| `管理端 - Step3 路线与备品保存` | ~~`staffCostIds`~~ | `integer[]` | -| `管理端 - Step3 路线与备品保存` | ~~`vehicleModelId`~~ | `integer(int64)` | -| `管理端 - Step3 路线与备品保存` | ~~`version`~~ | `integer(int32)` | -| `管理端 - Step5 补充信息保存` | ~~`version`~~ | `integer(int32)` | -| `管理端 - 产品列表项` | ~~`createBy`~~ | `integer(int64)` | -| `管理端 - 产品列表项` | ~~`version`~~ | `integer(int32)` | -| `管理端 - 产品详情` | ~~`createBy`~~ | `integer(int64)` | -| `管理端 - 产品详情` | ~~`creatorAvatarUrl`~~ | `string` | -| `管理端 - 产品详情` | ~~`creatorIntro`~~ | `string` | -| `管理端 - 产品详情` | ~~`customerName`~~ | `string` | -| `管理端 - 产品详情` | ~~`customizerId`~~ | `integer(int64)` | -| `管理端 - 产品详情` | ~~`departureDate`~~ | `string(date)` | -| `管理端 - 产品详情` | ~~`mchId`~~ | `string` | -| `管理端 - 产品详情` | ~~`priceVersion`~~ | `integer(int32)` | -| `管理端 - 产品详情` | ~~`version`~~ | `integer(int32)` | -| `管理端 - 价格日历批量设置` | ~~`version`~~ | `integer(int32)` | -| `管理端 - 产品线详情/列表项` | ~~`createBy`~~ | `integer(int64)` | -| `小程序端 - 产品详情` | ~~`creatorAvatarUrl`~~ | `string` | -| `小程序端 - 产品详情` | ~~`creatorIntro`~~ | `string` | - -**字段重命名** - -| 数据对象 | 原字段 | 新字段 | 类型 | -| --- | --- | --- | --- | -| `GroupTourBatchDO` | ~~`createBy`~~ | `createdBy` | `integer(int64)` | -| `管理端 - Step1 基础信息保存` | ~~`contactPhone`~~ | `category` | `string` | -| `管理端 - Step1 基础信息保存` | ~~`creatorAvatarUrl`~~ | `productType` | `string` | -| `管理端 - Step1 基础信息保存` | ~~`customizerId`~~ | `productId` | `integer(int64)` | -| `管理端 - 产品列表项` | ~~`createBy`~~ | `createdBy` | `integer(int64)` | -| `管理端 - 产品列表项` | ~~`version`~~ | `sortOrder` | `integer(int32)` | -| `管理端 - 产品详情` | ~~`createBy`~~ | `createdBy` | `integer(int64)` | -| `管理端 - 产品详情` | ~~`creatorAvatarUrl`~~ | `category` | `string` | -| `管理端 - 产品详情` | ~~`priceVersion`~~ | `currentStep` | `integer(int32)` | -| `管理端 - 产品线详情/列表项` | ~~`createBy`~~ | `createdBy` | `integer(int64)` | - -**字段类型变化** - -| 数据对象 | 字段 | 原类型 | 新类型 | -| --- | --- | --- | --- | -| `管理端 - Step1 基础信息保存` | `tiers` | `档位项[]` | `规格项[]` | -| `管理端 - 产品线详情/列表项` | `seasons` | `object` | `string[]` | -| `管理端 - 产品线详情/列表项` | `tags` | `object` | `string[]` | - -## ℹ️ 新增 (49) - -### 支付服务 - -**新增接口** - -- 🆕 `POST /admin/product/item/basic` - -**新增字段** - -| 数据对象 | 新增字段 | 类型 | -| --- | --- | --- | -| `GroupBatchStaffDO` | `createdBy` | `integer(int64)` | -| `GroupBatchStaffDO` | `updatedBy` | `integer(int64)` | -| `GroupTourBatchDO` | `createdBy` | `integer(int64)` | -| `GroupTourBatchDO` | `updatedBy` | `integer(int64)` | -| `ProductCrowdBenefitDO` | `createdBy` | `integer(int64)` | -| `ProductCrowdBenefitDO` | `updatedBy` | `integer(int64)` | -| `ProductFeeItemDO` | `createdBy` | `integer(int64)` | -| `ProductFeeItemDO` | `updatedBy` | `integer(int64)` | -| `ProductPriceCalendarDO` | `createdBy` | `integer(int64)` | -| `ProductPriceCalendarDO` | `updatedBy` | `integer(int64)` | -| `ProductRouteInfoDO` | `createdBy` | `integer(int64)` | -| `ProductRouteInfoDO` | `updatedBy` | `integer(int64)` | -| `ProductSupplementDO` | `createdBy` | `integer(int64)` | -| `ProductSupplementDO` | `updatedBy` | `integer(int64)` | -| `ProductSuppliesDO` | `createdBy` | `integer(int64)` | -| `ProductSuppliesDO` | `updatedBy` | `integer(int64)` | -| `管理端 - Step1 基础信息保存` | `category` | `string` | -| `管理端 - Step1 基础信息保存` | `productId` | `integer(int64)` | -| `管理端 - Step1 基础信息保存` | `productType` | `string` | -| `管理端 - 产品列表项` | `category` | `string` | -| `管理端 - 产品列表项` | `createdBy` | `integer(int64)` | -| `管理端 - 产品列表项` | `createdByName` | `string` | -| `管理端 - 产品列表项` | `lineId` | `integer(int64)` | -| `管理端 - 产品列表项` | `lineName` | `string` | -| `管理端 - 产品列表项` | `seasons` | `string[]` | -| `管理端 - 产品列表项` | `sortOrder` | `integer(int32)` | -| `管理端 - 产品列表项` | `startPrice` | `number` | -| `管理端 - 产品列表项` | `subtitle` | `string` | -| `管理端 - 产品列表项` | `tags` | `string[]` | -| `管理端 - 产品列表项` | `tierCount` | `integer(int32)` | -| `管理端 - 产品列表项` | `tripNights` | `integer(int32)` | -| `管理端 - 产品详情` | `category` | `string` | -| `管理端 - 产品详情` | `createdBy` | `integer(int64)` | -| `管理端 - 产品详情` | `currentStep` | `integer(int32)` | -| `管理端 - 产品线详情/列表项` | `createdBy` | `integer(int64)` | -| `管理端 - 产品线详情/列表项` | `productCount` | `integer(int64)` | -| `ProductDayHotelDO` | `createdBy` | `integer(int64)` | -| `ProductDayHotelDO` | `updatedBy` | `integer(int64)` | -| `小程序端 - 产品列表项` | `lineName` | `string` | -| `小程序端 - 产品列表项` | `paymentType` | `string` | -| `小程序端 - 产品列表项` | `seasons` | `string[]` | -| `小程序端 - 产品列表项` | `sortOrder` | `integer(int32)` | -| `小程序端 - 产品列表项` | `startPrice` | `number` | -| `小程序端 - 产品列表项` | `startPriceLabel` | `string` | -| `小程序端 - 产品列表项` | `tags` | `string[]` | -| `小程序端 - 产品列表项` | `tierCount` | `integer(int32)` | -| `小程序端 - 产品列表项` | `tripNights` | `integer(int32)` | - -### 字典变更 - -**新增字典项** - -| 字典 | 新增值 | 标签 | -| --- | --- | --- | -| `vehicle_type`（车型） | `GROUP` | 小蒙马专用 | diff --git a/changelogs/2026-04/2026-04-01_1123_c9427bc0_fix.md b/changelogs/2026-04/2026-04-01_1123_c9427bc0_fix.md deleted file mode 100644 index 5ae24dd..0000000 --- a/changelogs/2026-04/2026-04-01_1123_c9427bc0_fix.md +++ /dev/null @@ -1,28 +0,0 @@ -# 接口变更记录 — 2026-04-01 11:23 - -> **提交** `c9427bc0` · **作者** wx · **时间** 2026-04-01 11:23:29 +0800 -> -> fix: 服务人员性别校验与字典不一致——gender允许1=男2=女 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 资源服务 - -#### ✏️ StaffCreateRequest - - - ✏️ `gender`: 说明 "性别：0=女 1=男" → "性别：1=男 2=女" - -#### ✏️ StaffUpdateRequest - - - ✏️ `gender`: 说明 "性别：0=女 1=男" → "性别：1=男 2=女" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffCreateRequest.java -M hl-resource-service/src/main/java/com/hulalv/resource/staff/dto/StaffUpdateRequest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-01_1209_7ec4bc52_feat.md b/changelogs/2026-04/2026-04-01_1209_7ec4bc52_feat.md deleted file mode 100644 index b21dd22..0000000 --- a/changelogs/2026-04/2026-04-01_1209_7ec4bc52_feat.md +++ /dev/null @@ -1,68 +0,0 @@ -# 接口变更记录 — 2026-04-01 12:09 - -> **提交** `7ec4bc52` · **作者** wx · **时间** 2026-04-01 12:09:08 +0800 -> -> feat: 团队填报——对接全国旅游监管服务平台团队信息同步API - -## 变更总览 - -- **订单服务** - - 🆕 AdminTeamReport (+4 接口) - ---- - -## 订单服务 - -### 🆕 新增: AdminTeamReport - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「团队填报管理」** - -### 📌 `POST` /admin/team-report/sync — 同步团队信息到监管平台 - -**请求体** `SyncRequest` - -**响应** `Result<TeamReportVO>` - -### 📌 `POST` /admin/team-report/cancel — 取消团队 - -**请求体** `CancelRequest` - -**响应** `Result<TeamReportVO>` - -### 📌 `GET` /admin/team-report/status/{orderId} — 查询审核状态（实时从平台查询） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<TeamReportVO>` - -### 📌 `GET` /admin/team-report/{orderId} — 获取同步记录 - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<TeamReportVO>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-gateway/src/main/resources/application.yml -M hl-order-service/src/main/java/com/hulalv/contract/config/WebMvcConfig.java -A hl-order-service/src/main/java/com/hulalv/teamreport/builder/TeamReportRequestBuilder.java -A hl-order-service/src/main/java/com/hulalv/teamreport/client/TeamReportApiClient.java -A hl-order-service/src/main/java/com/hulalv/teamreport/config/TeamReportProperties.java -A hl-order-service/src/main/java/com/hulalv/teamreport/controller/AdminTeamReportController.java -A hl-order-service/src/main/java/com/hulalv/teamreport/entity/TeamReport.java -A hl-order-service/src/main/java/com/hulalv/teamreport/mapper/TeamReportMapper.java -A hl-order-service/src/main/java/com/hulalv/teamreport/service/TeamReportService.java -A hl-order-service/src/test/java/com/hulalv/teamreport/TeamReportApiClientTest.java -A hl-order-service/src/test/java/com/hulalv/teamreport/TeamReportRequestBuilderTest.java -M nacos-config/hl-order-service-dev.yml -A sql/team_report.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-01_1210_team_report_feat.md b/changelogs/2026-04/2026-04-01_1210_team_report_feat.md deleted file mode 100644 index 4d0dc16..0000000 --- a/changelogs/2026-04/2026-04-01_1210_team_report_feat.md +++ /dev/null @@ -1,139 +0,0 @@ -# feat: 团队填报——对接全国旅游监管服务平台团队信息同步API - -- **PR**: #104 -- **服务**: hl-order-service, hl-gateway -- **类型**: 新功能 - ---- - -## 新增接口（4个） - -### 1. 同步团队信息到监管平台 - -``` -POST /admin/team-report/sync -``` - -**请求体**: -```json -{ - "orderId": 1234567890 -} -``` - -**响应**: -```json -{ - "code": 200, - "data": { - "reportId": 1234567890, - "orderId": 1234567890, - "teamId": "HL2603-PP-002", - "agencyCode": "hulai", - "agencyLicense": "L-NMG-100953", - "businessType": 2, - "syncStatus": "SYNCED", - "platformStatus": null, - "platformStatusText": "未知", - "uploadCount": 0, - "errorMsg": null, - "syncedAt": "2026-04-01T12:00:00" - } -} -``` - -**说明**: 根据订单数据自动组装团队信息，上报到12301全国旅游监管服务平台。已同步的订单可重复调用（会更新）。 - ---- - -### 2. 取消团队 - -``` -POST /admin/team-report/cancel -``` - -**请求体**: -```json -{ - "orderId": 1234567890, - "cancelType": 1, - "cancelDesc": "旅行社原因取消" -} -``` - -**cancelType 取值**: 0=游客个人原因, 1=旅行社原因, 2=不可抗因素, 3=其他 - ---- - -### 3. 查询审核状态（实时从平台查询） - -``` -GET /admin/team-report/status/{orderId} -``` - -**说明**: 实时调用12301平台查询团队审核状态。 - ---- - -### 4. 获取同步记录 - -``` -GET /admin/team-report/{orderId} -``` - -**说明**: 获取该订单的团队填报记录。未同步过返回 `data: null`。 - ---- - -## syncStatus 状态 - -| 值 | 含义 | -|---|---| -| PENDING | 待同步 | -| SYNCED | 已同步 | -| FAILED | 同步失败 | -| CANCELLED | 已取消 | - -## platformStatus 平台审核状态 - -| 值 | 含义 | -|---|---| -| 1 | 待提交 | -| 2 | 已提交/已审核 | -| 3 | 审核不通过 | -| 4 | 审核通过 | -| 7 | 待取消 | -| 8 | 已取消 | -| 9 | 已出团 | - ---- - -## 前端对接说明 - -在**订单详情页**的「合同保险」tab → 合同信息区域旁边，新增： - -1. **「同步团队」按钮** — 调用 `POST /admin/team-report/sync { orderId }` - - 有合同信息后展示此按钮 - - 点击后显示同步结果（成功/失败+错误信息） - -2. **同步状态展示** — 调用 `GET /admin/team-report/{orderId}` - - 已同步：显示 syncStatus + platformStatusText - - 未同步：不展示 - -3. **「刷新状态」按钮** — 调用 `GET /admin/team-report/status/{orderId}` - -4. **「取消团队」按钮** — 调用 `POST /admin/team-report/cancel { orderId }` - ---- - -## DDL - -部署前需在 hl_order_service 库执行: -```sql --- sql/team_report.sql -``` - -## 需重启服务 - -- hl-order-service -- hl-gateway diff --git a/changelogs/2026-04/2026-04-01_1230_team_report_form.md b/changelogs/2026-04/2026-04-01_1230_team_report_form.md deleted file mode 100644 index 79f1a0a..0000000 --- a/changelogs/2026-04/2026-04-01_1230_team_report_form.md +++ /dev/null @@ -1,93 +0,0 @@ -# feat: 团队填报改为表单模式——预填/暂存/提交 - -- **PR**: #105（基于 #104） -- **服务**: hl-order-service -- **类型**: 接口变更 - ---- - -## 接口变更 - -原来的 `POST /admin/team-report/sync` **废弃**，改为以下3个接口： - -### 1. 预填表单（从订单自动填充） - -``` -GET /admin/team-report/prefill/{orderId} -``` - -**说明**: 首次调用从订单数据自动填充所有字段；如已有暂存记录，返回上次保存的数据。 - -**响应**: 返回完整的 `TeamReportFormDTO`，包含以下区块： - -| 区块 | 字段 | -|------|------| -| 基础 | orderId, agencyCode, businessType | -| 团队信息 | agencyName, agencyLicense, itineraryName, teamId, dateGo, timeGoHour/Minute, dateBack, timeBackHour/Minute, sourceCity, sourceProvince, destinationCity, destinationProvince, itineraryDay, vehicle, vehicleIn, vehicleOutNums, vehicleInNums, nativeTravelAgency, teamType, peopleNums, childNums, journeyDesc, applicantName, applicantPhone | -| 导游信息 | guides: [{name, cardId, phone, type, isLeader}] | -| 车队信息 | busInfo: [{carId, carComp, driverName, driverPhone}] | -| 行程单 | itineraryList: [{dayNumber, siteNum, date, city, province, journeyDesc, title, isTransit}] | -| 游客名单 | touristList: [{name, pyFamilyName, pyGivenName, dateOfBirth, phoneNum, sex, age, isChild, hrProvince, cardType, cardId, cardValidTo}] | - ---- - -### 2. 暂存表单 - -``` -POST /admin/team-report/save -``` - -**请求体**: 完整的 `TeamReportFormDTO`（和 prefill 返回结构一致） - -**说明**: 保存用户编辑的表单数据，不提交到12301。状态保持 `PENDING`。 - ---- - -### 3. 提交到12301 - -``` -POST /admin/team-report/submit -``` - -**请求体**: 完整的 `TeamReportFormDTO` - -**说明**: 保存表单数据并提交到12301平台。成功后状态变为 `SYNCED`。 - ---- - -### 保留的接口 - -| 接口 | 用途 | -|------|------| -| `GET /admin/team-report/{orderId}` | 获取同步记录（含 formData） | -| `GET /admin/team-report/status/{orderId}` | 实时查询12301审核状态 | -| `POST /admin/team-report/cancel` | 取消团队 | - ---- - -## 前端页面对接 - -参考12301团队信息同步页面，在订单详情新增「同步」tab： - -1. 进入页面 → 调用 `GET /admin/team-report/prefill/{orderId}` 获取预填数据 -2. 用户可编辑所有字段（旅行社主体radio、业务类型radio、团队信息表单、导游/车队/行程可增删行） -3. 底部两个按钮： - - **「暂存」** → `POST /admin/team-report/save` - - **「提交到12301」** → `POST /admin/team-report/submit` -4. 已提交后展示 syncStatus 和 platformStatus - -## 枚举值 - -**businessType**: 2=国内游组团, 6=入境接待, 7=国内接待 -**teamType**: 1=自组自接, 2=包机, 3=专列, 4=其他 -**vehicle**: 1=飞机, 2=火车, 3=轮船, 4=汽车, 5=其它 - -## DDL - -```sql -ALTER TABLE team_report ADD COLUMN form_data JSON NULL COMMENT '表单数据JSON' AFTER upload_count; -``` - -## 需重启 - -- hl-order-service diff --git a/changelogs/2026-04/2026-04-01_1243_421ec547_feat.md b/changelogs/2026-04/2026-04-01_1243_421ec547_feat.md deleted file mode 100644 index ffe0cd1..0000000 --- a/changelogs/2026-04/2026-04-01_1243_421ec547_feat.md +++ /dev/null @@ -1,256 +0,0 @@ -# 接口变更记录 — 2026-04-01 12:43 - -> **提交** `421ec547` · **作者** wx · **时间** 2026-04-01 12:43:52 +0800 -> -> feat: 团队填报改为表单模式——预填/暂存/提交三步流程 - -## 变更总览 - -- **订单服务** - - AdminTeamReport (+3, -1, 名1) - ---- - -## 订单服务 - -### AdminTeamReport - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「团队填报管理」** - -### 🆕 `GET` /admin/team-report/prefill/{orderId} — 预填表单（从订单数据自动填充） - -**参数** - - - `{orderId}` (`Long`) — 路径参数：订单ID - -**响应** `Result<TeamReportFormDTO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `agencyCode` | `String` | 旅行社编码 hulai/qianshou/hulai-wenlu | -| `businessType` | `Integer` | 业务类型 2=国内游组团 6=入境接待 7=国内接待 | -| `agencyName` | `String` | 旅行社名称 | -| `agencyLicense` | `String` | 经营许可证号 | -| `itineraryName` | `String` | 线路名称 | -| `teamId` | `String` | 团号 | -| `dateGo` | `String` | 出发日期 yyyy-MM-dd | -| `timeGoHour` | `String` | 出发时间 HH | -| `timeGoMinute` | `String` | 出发时间 mm | -| `dateBack` | `String` | 返回日期 yyyy-MM-dd | -| `timeBackHour` | `String` | 返回时间 HH | -| `timeBackMinute` | `String` | 返回时间 mm | -| `sourceCity` | `String` | 出发城市 | -| `sourceProvince` | `String` | 出发省份 | -| `destinationCity` | `String` | 前往城市 | -| `destinationProvince` | `String` | 前往省份 | -| `itineraryDay` | `Integer` | 天数 | -| `vehicle` | `Integer` | 出发交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | -| `vehicleIn` | `Integer` | 返回交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | -| `vehicleOutNums` | `String` | 出发班次/车次 | -| `vehicleInNums` | `String` | 返回班次/车次 | -| `nativeTravelAgency` | `String` | 地接社名称 | -| `teamType` | `Integer` | 团队类型 1=自组自接 2=包机 3=专列 4=其他 | -| `peopleNums` | `Integer` | 团队人数 | -| `childNums` | `Integer` | 儿童人数 | -| `journeyDesc` | `String` | 行程总描述 | -| `applicantName` | `String` | 申请人姓名 | -| `applicantPhone` | `String` | 申请人电话 | -| `guides` | `List<GuideInfo>` | 导游列表 | -| `name` | `String` | 导游姓名 | -| `cardId` | `String` | 电子导游证号 | -| `phone` | `String` | 导游电话 | -| `type` | `Integer` | 导游类型 1=全陪 2=地陪 | -| `isLeader` | `Integer` | 是否领队 0=否 1=是 | -| `busInfo` | `List<BusInfo>` | 车队列表 | -| `carId` | `String` | 车牌号 | -| `carComp` | `String` | 所属公司 | -| `driverName` | `String` | 驾驶员姓名 | -| `driverPhone` | `String` | 驾驶员联系电话 | -| `itineraryList` | `List<ItineraryItem>` | 行程列表（按天按站点） | -| `dayNumber` | `Integer` | 第几天 | -| `siteNum` | `Integer` | 当天第几个站点 | -| `date` | `String` | 具体日期 yyyy-MM-dd | -| `city` | `String` | 前往城市 | -| `province` | `String` | 前往省份 | -| `journeyDesc` | `String` | 站点行程描述 | -| `title` | `String` | 站点标题 | -| `isTransit` | `Integer` | 是否过境 0=否 1=是 | -| `touristList` | `List<TouristInfo>` | 游客列表 | -| `name` | `String` | 姓名 | -| `pyFamilyName` | `String` | 姓拼音 | -| `pyGivenName` | `String` | 名拼音 | -| `dateOfBirth` | `String` | 出生日期 yyyy-MM-dd | -| `phoneNum` | `String` | 联系方式 | -| `sex` | `Integer` | 性别 0=男 1=女 | -| `age` | `Integer` | 年龄 | -| `isChild` | `Integer` | 是否儿童 0=否 1=是 | -| `hrProvince` | `String` | 户籍所在省 | -| `cardType` | `Integer` | 证件类型 1=身份证 2=护照 | -| `cardId` | `String` | 证件号码 | -| `cardValidTo` | `String` | 证件有效期至 yyyy-MM-dd | - -### 🆕 `POST` /admin/team-report/save — 暂存表单（不提交到12301） - -**请求体** `TeamReportFormDTO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `agencyCode` | `String` | 旅行社编码 hulai/qianshou/hulai-wenlu | -| `businessType` | `Integer` | 业务类型 2=国内游组团 6=入境接待 7=国内接待 | -| `agencyName` | `String` | 旅行社名称 | -| `agencyLicense` | `String` | 经营许可证号 | -| `itineraryName` | `String` | 线路名称 | -| `teamId` | `String` | 团号 | -| `dateGo` | `String` | 出发日期 yyyy-MM-dd | -| `timeGoHour` | `String` | 出发时间 HH | -| `timeGoMinute` | `String` | 出发时间 mm | -| `dateBack` | `String` | 返回日期 yyyy-MM-dd | -| `timeBackHour` | `String` | 返回时间 HH | -| `timeBackMinute` | `String` | 返回时间 mm | -| `sourceCity` | `String` | 出发城市 | -| `sourceProvince` | `String` | 出发省份 | -| `destinationCity` | `String` | 前往城市 | -| `destinationProvince` | `String` | 前往省份 | -| `itineraryDay` | `Integer` | 天数 | -| `vehicle` | `Integer` | 出发交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | -| `vehicleIn` | `Integer` | 返回交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | -| `vehicleOutNums` | `String` | 出发班次/车次 | -| `vehicleInNums` | `String` | 返回班次/车次 | -| `nativeTravelAgency` | `String` | 地接社名称 | -| `teamType` | `Integer` | 团队类型 1=自组自接 2=包机 3=专列 4=其他 | -| `peopleNums` | `Integer` | 团队人数 | -| `childNums` | `Integer` | 儿童人数 | -| `journeyDesc` | `String` | 行程总描述 | -| `applicantName` | `String` | 申请人姓名 | -| `applicantPhone` | `String` | 申请人电话 | -| `guides` | `List<GuideInfo>` | 导游列表 | -| `name` | `String` | 导游姓名 | -| `cardId` | `String` | 电子导游证号 | -| `phone` | `String` | 导游电话 | -| `type` | `Integer` | 导游类型 1=全陪 2=地陪 | -| `isLeader` | `Integer` | 是否领队 0=否 1=是 | -| `busInfo` | `List<BusInfo>` | 车队列表 | -| `carId` | `String` | 车牌号 | -| `carComp` | `String` | 所属公司 | -| `driverName` | `String` | 驾驶员姓名 | -| `driverPhone` | `String` | 驾驶员联系电话 | -| `itineraryList` | `List<ItineraryItem>` | 行程列表（按天按站点） | -| `dayNumber` | `Integer` | 第几天 | -| `siteNum` | `Integer` | 当天第几个站点 | -| `date` | `String` | 具体日期 yyyy-MM-dd | -| `city` | `String` | 前往城市 | -| `province` | `String` | 前往省份 | -| `journeyDesc` | `String` | 站点行程描述 | -| `title` | `String` | 站点标题 | -| `isTransit` | `Integer` | 是否过境 0=否 1=是 | -| `touristList` | `List<TouristInfo>` | 游客列表 | -| `name` | `String` | 姓名 | -| `pyFamilyName` | `String` | 姓拼音 | -| `pyGivenName` | `String` | 名拼音 | -| `dateOfBirth` | `String` | 出生日期 yyyy-MM-dd | -| `phoneNum` | `String` | 联系方式 | -| `sex` | `Integer` | 性别 0=男 1=女 | -| `age` | `Integer` | 年龄 | -| `isChild` | `Integer` | 是否儿童 0=否 1=是 | -| `hrProvince` | `String` | 户籍所在省 | -| `cardType` | `Integer` | 证件类型 1=身份证 2=护照 | -| `cardId` | `String` | 证件号码 | -| `cardValidTo` | `String` | 证件有效期至 yyyy-MM-dd | - -**响应** `Result<TeamReportVO>` - -### 🆕 `POST` /admin/team-report/submit — 提交到12301平台 - -**请求体** `TeamReportFormDTO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `agencyCode` | `String` | 旅行社编码 hulai/qianshou/hulai-wenlu | -| `businessType` | `Integer` | 业务类型 2=国内游组团 6=入境接待 7=国内接待 | -| `agencyName` | `String` | 旅行社名称 | -| `agencyLicense` | `String` | 经营许可证号 | -| `itineraryName` | `String` | 线路名称 | -| `teamId` | `String` | 团号 | -| `dateGo` | `String` | 出发日期 yyyy-MM-dd | -| `timeGoHour` | `String` | 出发时间 HH | -| `timeGoMinute` | `String` | 出发时间 mm | -| `dateBack` | `String` | 返回日期 yyyy-MM-dd | -| `timeBackHour` | `String` | 返回时间 HH | -| `timeBackMinute` | `String` | 返回时间 mm | -| `sourceCity` | `String` | 出发城市 | -| `sourceProvince` | `String` | 出发省份 | -| `destinationCity` | `String` | 前往城市 | -| `destinationProvince` | `String` | 前往省份 | -| `itineraryDay` | `Integer` | 天数 | -| `vehicle` | `Integer` | 出发交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | -| `vehicleIn` | `Integer` | 返回交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | -| `vehicleOutNums` | `String` | 出发班次/车次 | -| `vehicleInNums` | `String` | 返回班次/车次 | -| `nativeTravelAgency` | `String` | 地接社名称 | -| `teamType` | `Integer` | 团队类型 1=自组自接 2=包机 3=专列 4=其他 | -| `peopleNums` | `Integer` | 团队人数 | -| `childNums` | `Integer` | 儿童人数 | -| `journeyDesc` | `String` | 行程总描述 | -| `applicantName` | `String` | 申请人姓名 | -| `applicantPhone` | `String` | 申请人电话 | -| `guides` | `List<GuideInfo>` | 导游列表 | -| `name` | `String` | 导游姓名 | -| `cardId` | `String` | 电子导游证号 | -| `phone` | `String` | 导游电话 | -| `type` | `Integer` | 导游类型 1=全陪 2=地陪 | -| `isLeader` | `Integer` | 是否领队 0=否 1=是 | -| `busInfo` | `List<BusInfo>` | 车队列表 | -| `carId` | `String` | 车牌号 | -| `carComp` | `String` | 所属公司 | -| `driverName` | `String` | 驾驶员姓名 | -| `driverPhone` | `String` | 驾驶员联系电话 | -| `itineraryList` | `List<ItineraryItem>` | 行程列表（按天按站点） | -| `dayNumber` | `Integer` | 第几天 | -| `siteNum` | `Integer` | 当天第几个站点 | -| `date` | `String` | 具体日期 yyyy-MM-dd | -| `city` | `String` | 前往城市 | -| `province` | `String` | 前往省份 | -| `journeyDesc` | `String` | 站点行程描述 | -| `title` | `String` | 站点标题 | -| `isTransit` | `Integer` | 是否过境 0=否 1=是 | -| `touristList` | `List<TouristInfo>` | 游客列表 | -| `name` | `String` | 姓名 | -| `pyFamilyName` | `String` | 姓拼音 | -| `pyGivenName` | `String` | 名拼音 | -| `dateOfBirth` | `String` | 出生日期 yyyy-MM-dd | -| `phoneNum` | `String` | 联系方式 | -| `sex` | `Integer` | 性别 0=男 1=女 | -| `age` | `Integer` | 年龄 | -| `isChild` | `Integer` | 是否儿童 0=否 1=是 | -| `hrProvince` | `String` | 户籍所在省 | -| `cardType` | `Integer` | 证件类型 1=身份证 2=护照 | -| `cardId` | `String` | 证件号码 | -| `cardValidTo` | `String` | 证件有效期至 yyyy-MM-dd | - -**响应** `Result<TeamReportVO>` - -### ❌ ~~`POST` /admin/team-report/sync — 同步团队信息到监管平台~~ - -### 接口名称更新 - -| 方法 | 路径 | 原名称 → 新名称 | -| --- | --- | --- | -| `GET` | `/admin/team-report/{orderId}` | 获取同步记录 → **获取同步记录（含表单数据）** | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service/src/main/java/com/hulalv/teamreport/builder/TeamReportRequestBuilder.java -M hl-order-service/src/main/java/com/hulalv/teamreport/controller/AdminTeamReportController.java -A hl-order-service/src/main/java/com/hulalv/teamreport/dto/TeamReportFormDTO.java -M hl-order-service/src/main/java/com/hulalv/teamreport/entity/TeamReport.java -M hl-order-service/src/main/java/com/hulalv/teamreport/service/TeamReportService.java -M sql/team_report.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-01_1600_mp_hotel_per_day_bug.md b/changelogs/2026-04/2026-04-01_1600_mp_hotel_per_day_bug.md deleted file mode 100644 index 9659018..0000000 --- a/changelogs/2026-04/2026-04-01_1600_mp_hotel_per_day_bug.md +++ /dev/null @@ -1,46 +0,0 @@ -# bug: 小程序产品详情"查看全部"酒店应只显示当天酒店 - -- **类型**: 前端BUG -- **页面**: 小程序 → 产品详情 → 行程tab → 某天的酒店区域 → "查看全部" - ---- - -## 问题描述 - -DAY 1 的酒店区域点"查看全部"后，应该只显示 DAY 1 的酒店，但目前可能显示了所有天的酒店。 - -## 后端数据说明 - -后端返回的数据**已经按天正确分组**，无需改动。 - -产品详情接口 `GET /mp/product/{productId}` 返回结构： - -```json -{ - "product": { - "itineraryDays": [ - { - "dayNumber": 1, - "dayTitle": "呼伦贝尔我来咯！", - "hotels": [ // ← 这里就是 DAY 1 的酒店，只有当天的 - { - "hotelId": "...", - "hotelName": "嘉世豪酒店", - "coverUrl": "...", - "roomTypeName": "标准间", - "tags": ["四星级"] - } - ] - }, - { - "dayNumber": 2, - "hotels": [...] // ← DAY 2 的酒店 - } - ] - } -} -``` - -## 前端修复方式 - -"查看全部"点击时，只取当前天的 `itineraryDays[dayIndex].hotels` 数组展示，不要合并所有天的酒店。 diff --git a/changelogs/2026-04/2026-04-01_1730_mp_day_hotels_dining.md b/changelogs/2026-04/2026-04-01_1730_mp_day_hotels_dining.md deleted file mode 100644 index 5e952ca..0000000 --- a/changelogs/2026-04/2026-04-01_1730_mp_day_hotels_dining.md +++ /dev/null @@ -1,46 +0,0 @@ -# feat: 小程序查看每日全部酒店/餐厅接口 - -- **PR**: #119 -- **服务**: hl-mp-service, hl-product-service -- **类型**: 新接口 - ---- - -## 新增接口 - -### 1. 获取某天的全部酒店 - -``` -GET /mp/product/{productId}/day/{dayNumber}/hotels -``` - -**参数**: -- `productId` (路径) — 产品ID -- `dayNumber` (路径) — 天数编号，从1开始 - -**响应**: 返回该天所有住宿安排，含酒店名称、封面图、房型、标签等 - ---- - -### 2. 获取某天的全部餐厅 - -``` -GET /mp/product/{productId}/day/{dayNumber}/dining -``` - -**参数**: -- `productId` (路径) — 产品ID -- `dayNumber` (路径) — 天数编号，从1开始 - -**响应**: 返回该天所有餐饮推荐，含餐厅名称、用餐类型(早/午/晚)、描述等 - ---- - -## 使用场景 - -产品详情页行程tab，每天的酒店/餐厅区域点「查看全部」时调用。 - -## 需重启 - -- hl-mp-service -- hl-product-service diff --git a/changelogs/2026-04/2026-04-01_1745_8bd5229e_feat_Redis.md b/changelogs/2026-04/2026-04-01_1745_8bd5229e_feat_Redis.md deleted file mode 100644 index 2a4ab4a..0000000 --- a/changelogs/2026-04/2026-04-01_1745_8bd5229e_feat_Redis.md +++ /dev/null @@ -1,80 +0,0 @@ -# 接口变更记录 — 2026-04-01 17:45 - -> **提交** `8bd5229e` · **作者** wx · **时间** 2026-04-01 17:45:27 +0800 -> -> feat: 小程序全接口Redis缓存+管理端实时清除 - -## 变更总览 - -- **小程序聚合服务** - - 🆕 InternalCache (+2 接口) - ---- - -## 小程序聚合服务 - -### 🆕 新增: InternalCache - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「内部 - 缓存管理」** - -### 📌 `POST` /internal/mp/cache/evict — 按前缀清除缓存 - -**请求体** `EvictRequest` - -**响应** `Result<Void>` - -### 📌 `DELETE` /internal/mp/cache/{resourceType} — 按资源类型清除缓存 - -**参数** - - - `{resourceType}` (`String`) — 路径参数：资源类型: product/scenic/hotel/activity/restaurant/wiki/explore/designer/review/dict/config/common/home/banner - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-common/hl-common-redis/src/main/java/com/hulalv/common/redis/MpCacheEvict.java -A hl-mp-service/src/main/java/com/hulalv/mp/annotation/MpCache.java -A hl-mp-service/src/main/java/com/hulalv/mp/aspect/MpCacheAspect.java -A hl-mp-service/src/main/java/com/hulalv/mp/constant/CacheKeys.java -A hl-mp-service/src/main/java/com/hulalv/mp/controller/InternalCacheController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpActivityController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpBannerController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpCommonController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpConfigController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDesignerController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpDictController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpExploreController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpHotelController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRestaurantController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpReviewController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpScenicController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpSearchController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpWikiController.java -M hl-mp-service/src/main/java/com/hulalv/mp/service/CacheService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductServiceTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductStatusServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/resource/activity/service/ActivityService.java -M hl-resource-service/src/main/java/com/hulalv/resource/hotel/service/HotelService.java -M hl-resource-service/src/main/java/com/hulalv/resource/restaurant/service/RestaurantService.java -M hl-resource-service/src/main/java/com/hulalv/resource/scenic/service/ScenicSpotService.java -M hl-resource-service/src/test/java/com/hulalv/resource/activity/service/ActivityServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/hotel/service/HotelServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/restaurant/service/RestaurantServiceTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/scenic/service/ScenicSpotServiceTest.java -M hl-user-service/src/main/java/com/hulalv/user/service/BannerService.java -M hl-user-service/src/main/java/com/hulalv/user/service/FrontendConfigService.java -M hl-user-service/src/main/java/com/hulalv/user/service/SysDictService.java -M hl-user-service/src/test/java/com/hulalv/user/service/BannerServiceTest.java -M hl-user-service/src/test/java/com/hulalv/user/service/FrontendConfigServiceFullTest.java -M hl-user-service/src/test/java/com/hulalv/user/service/FrontendConfigServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-01_1750_9fbff1d7_feat.md b/changelogs/2026-04/2026-04-01_1750_9fbff1d7_feat.md deleted file mode 100644 index d9fd373..0000000 --- a/changelogs/2026-04/2026-04-01_1750_9fbff1d7_feat.md +++ /dev/null @@ -1,81 +0,0 @@ -# 接口变更记录 — 2026-04-01 17:50 - -> **提交** `9fbff1d7` · **作者** wx · **时间** 2026-04-01 17:50:58 +0800 -> -> feat: 小程序产品详情查看每日全部酒店/餐厅接口 - -## 变更总览 - -- **产品服务** - - InternalMpProduct (+2) -- **小程序聚合服务** - - MpProduct (+2) - ---- - -## 产品服务 - -### InternalMpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】小程序产品（Feign调用）」** - -### 🆕 `GET` /internal/mp/product/day-hotels — 获取某天的全部酒店 - -> 小程序产品详情页「查看全部」酒店用 - -**参数** - - - `productId` (`Long`) — 查询参数 - - `dayNumber` (`Integer`) — 查询参数 - -### 🆕 `GET` /internal/mp/product/day-dining — 获取某天的全部餐厅 - -> 小程序产品详情页「查看全部」餐厅用 - -**参数** - - - `productId` (`Long`) — 查询参数 - - `dayNumber` (`Integer`) — 查询参数 - ---- - -## 小程序聚合服务 - -### MpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 产品接口」** - -### 🆕 `GET` /mp/product/{productId}/day/{dayNumber}/hotels — 获取某天的全部酒店 - -> 产品详情页「查看全部」酒店用，返回指定天数的所有住宿安排 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `{dayNumber}` (`Integer`) — 路径参数：天数编号(从1开始) - -**响应** `Result<List<Map<String, Object>>>` - -### 🆕 `GET` /mp/product/{productId}/day/{dayNumber}/dining — 获取某天的全部餐厅 - -> 产品详情页「查看全部」餐厅用，返回指定天数的所有餐饮推荐 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `{dayNumber}` (`Integer`) — 路径参数：天数编号(从1开始) - -**响应** `Result<List<Map<String, Object>>>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-01_2001_349ec384_fix.md b/changelogs/2026-04/2026-04-01_2001_349ec384_fix.md deleted file mode 100644 index 975ab04..0000000 --- a/changelogs/2026-04/2026-04-01_2001_349ec384_fix.md +++ /dev/null @@ -1,41 +0,0 @@ -# 接口变更记录 — 2026-04-01 20:01 - -> **提交** `349ec384` · **作者** wx · **时间** 2026-04-01 20:01:38 +0800 -> -> fix: 全量测试修复——同步测试用例与代码变更 (14项) - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 小程序聚合服务 - -#### ✏️ MpProductDetailVO - - - ✏️ `earlyBirdText`: 说明 "早鸟优惠文字描述(如: 早鸟优惠：满2人立减50元/人)" → "早鸟优惠文字描述(如: 早鸟优惠：满2人立减50元)" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/service/ProductAggregationService.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductDetailVO.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/ProductAggregationServiceTest.java -M hl-order-service/src/test/java/com/hulalv/teamreport/TeamReportRequestBuilderTest.java -M hl-product-service/src/test/java/com/hulalv/product/constant/ProductConstantsTest.java -M hl-resource-service/src/test/java/com/hulalv/resource/staff/constant/StaffConstantsTest.java -M hl-user-service/src/test/java/com/hulalv/monitor/controller/MysqlMonitorControllerTest.java -M hl-user-service/src/test/java/com/hulalv/monitor/controller/RedisMonitorControllerTest.java -M hl-user-service/src/test/java/com/hulalv/monitor/controller/RocketMqMonitorControllerTest.java -M hl-user-service/src/test/java/com/hulalv/monitor/controller/ServiceMonitorControllerTest.java -M hl-user-service/src/test/java/com/hulalv/user/controller/AdminUserControllerTest.java -M hl-user-service/src/test/java/com/hulalv/user/controller/SysMenuControllerTest.java -M hl-user-service/src/test/java/com/hulalv/user/controller/SysRoleControllerTest.java -M hl-user-service/src/test/java/com/hulalv/user/service/SysDictServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1039_05d9b09f_fix.md b/changelogs/2026-04/2026-04-02_1039_05d9b09f_fix.md deleted file mode 100644 index 7beb4a8..0000000 --- a/changelogs/2026-04/2026-04-02_1039_05d9b09f_fix.md +++ /dev/null @@ -1,206 +0,0 @@ -# 接口变更记录 — 2026-04-02 10:39 - -> **提交** `05d9b09f` · **作者** wx · **时间** 2026-04-02 10:39:29 +0800 -> -> fix: 全局"定金"改为"订金"——统一用字规范 - -## 变更总览 - -- **订单服务** - - AdminOrder (名1) - ---- - -## 订单服务 - -### AdminOrder - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 分组 **「3.1 订单管理」** → 标签 **「管理端订单接口」** - -### 接口名称更新 - -| 方法 | 路径 | 原名称 → 新名称 | -| --- | --- | --- | -| `PUT` | `/admin/order/{orderId}/deposit` | 修改定金金额 → **修改订金金额** | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ GroupBatchCalendarVO - - - ✏️ `depositAmount`: 说明 "定金金额(元/人)，根据起步价×定金比例计算" → "订金金额(元/人)，根据起步价×订金比例计算" - -#### ✏️ MpProductListVO - - - ✏️ `startPrice`: 说明 "起步价：全款模式=最低售价，定金模式=最低定金额" → "起步价：全款模式=最低售价，订金模式=最低订金额" - - ✏️ `startPriceLabel`: 说明 "起步价标签：'起' 或 '定金起'" → "起步价标签：'起' 或 '订金起'" - - ✏️ `paymentMode`: 说明 "支付模式：FULL=全款 DEPOSIT=定金+尾款" → "支付模式：FULL=全款 DEPOSIT=订金+尾款" - -#### ✏️ MpProductQueryRequest - - - ✏️ `paymentMode`: 说明 "支付模式筛选：FULL=全款 DEPOSIT=定金+尾款 null=全部" → "支付模式筛选：FULL=全款 DEPOSIT=订金+尾款 null=全部" - -#### ✏️ PricingRequest - - - ✏️ `profitMode`: 说明 "利润模式：FIXED=在成本基础上加固定金额 PERCENT=在成本基础上按百分比加价" → "利润模式：FIXED=在成本基础上加固订金额 PERCENT=在成本基础上按百分比加价" - - ✏️ `paymentType`: 说明 "支付方式：FULL=全款支付 DEPOSIT=定金+尾款分期支付" → "支付方式：FULL=全款支付 DEPOSIT=订金+尾款分期支付" - - ✏️ `depositRatio`: 说明 "定金比例（百分比，如30代表30%。与depositAmount二选一，优先使用比例）" → "订金比例（百分比，如30代表30%。与depositAmount二选一，优先使用比例）" - - ✏️ `depositAmount`: 说明 "定金金额（固定金额，与depositRatio二选一）" → "订金金额（固订金额，与depositRatio二选一）" - -#### ✏️ ProductPricingVO - - - ✏️ `profitMode`: 说明 "利润模式：FIXED=固定金额 PERCENT=百分比" → "利润模式：FIXED=固订金额 PERCENT=百分比" - - ✏️ `paymentType`: 说明 "支付方式：FULL=全款 DEPOSIT=定金+尾款" → "支付方式：FULL=全款 DEPOSIT=订金+尾款" - - ✏️ `depositRatio`: 说明 "定金比例（百分比）" → "订金比例（百分比）" - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - -#### ✏️ ProductVO - - - ✏️ `paymentMode`: 说明 "支付模式：FULL=全款 DEPOSIT=定金+尾款" → "支付模式：FULL=全款 DEPOSIT=订金+尾款" - - ✏️ `startPrice`: 说明 "起步价：全款模式=最低售价，定金模式=最低定金额" → "起步价：全款模式=最低售价，订金模式=最低订金额" - - ✏️ `startPriceLabel`: 说明 "起步价标签：'起' 或 '定金起'" → "起步价标签：'起' 或 '订金起'" - -### 公共模块 - -#### ✏️ OrderPayInfoDTO - - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - - ✏️ `paymentMode`: 说明 "支付模式: FULL=全款, DEPOSIT=定金+尾款" → "支付模式: FULL=全款, DEPOSIT=订金+尾款" - - ✏️ `isBooking`: 说明 "是否预定产品: true=预定(定金可不填出行人), false=非预定(支付前必须填出行人)" → "是否预定产品: true=预定(订金可不填出行人), false=非预定(支付前必须填出行人)" - -#### ✏️ PaymentResultDTO - - - ✏️ `payType`: 说明 "支付类型: FULL=全款, DEPOSIT=定金, BALANCE=尾款" → "支付类型: FULL=全款, DEPOSIT=订金, BALANCE=尾款" - -### 小程序聚合服务 - -#### ✏️ MpCustomProductDetailVO - - - ✏️ `paymentMode`: 说明 "支付模式：FULL=全款 DEPOSIT=定金+尾款" → "支付模式：FULL=全款 DEPOSIT=订金+尾款" - - ✏️ `profitMode`: 说明 "利润模式：FIXED=固定金额 PERCENT=百分比" → "利润模式：FIXED=固订金额 PERCENT=百分比" - - ✏️ `paymentType`: 说明 "支付方式：FULL=全款 DEPOSIT=定金+尾款" → "支付方式：FULL=全款 DEPOSIT=订金+尾款" - - ✏️ `depositRatio`: 说明 "定金比例（百分比）" → "订金比例（百分比）" - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - -#### ✏️ MpCustomProductListVO - - - ✏️ `paymentMode`: 说明 "支付模式：FULL=全款 DEPOSIT=定金+尾款" → "支付模式：FULL=全款 DEPOSIT=订金+尾款" - -#### ✏️ MpOrderDetailVO - - - ✏️ `depositRatio`: 说明 "定金比例" → "订金比例" - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - - ✏️ `payMethodLabel`: 说明 "支付方式标签（如：微信支付、定金微信+尾款线下）" → "支付方式标签（如：微信支付、订金微信+尾款线下）" - -#### ✏️ MpOrderListItemVO - - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - -#### ✏️ MpProductQuoteVO - - - ✏️ `paymentMode`: 说明 "支付方式: FULL(全额支付) / DEPOSIT(定金+尾款)" → "支付方式: FULL(全额支付) / DEPOSIT(订金+尾款)" - - ✏️ `depositPayment`: 说明 "定金支付信息（仅paymentMode=DEPOSIT时有值）" → "订金支付信息（仅paymentMode=DEPOSIT时有值）" - - ✏️ `depositRatio`: 说明 "定金比例(%)" → "订金比例(%)" - - ✏️ `depositAmount`: 说明 "定金金额（首次需付）" → "订金金额（首次需付）" - -#### ✏️ MpRefundDetailVO - - - ✏️ `refundType`: 说明 "退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款)" → "退款类型: DEPOSIT(订金)/BALANCE(尾款)/FULL(全款)" - -### 订单服务 - -#### ✏️ AdminUpdateOrderRequest - - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - -#### ✏️ MpOrderListVO - - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - - ✏️ `balanceAmount`: 说明 "尾款金额（DEPOSIT模式：总售价-定金-优惠）" → "尾款金额（DEPOSIT模式：总售价-订金-优惠）" - -#### ✏️ OrderDetailVO - - - ✏️ `paymentModeLabel`: 说明 "支付模式中文标签（DEPOSIT=定金+尾款, FULL=全款）" → "支付模式中文标签（DEPOSIT=订金+尾款, FULL=全款）" - - ✏️ `depositRatio`: 说明 "定金比例" → "订金比例" - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - - ✏️ `balanceAmount`: 说明 "尾款金额（总售价-定金）" → "尾款金额（总售价-订金）" - - ✏️ `payMethodLabel`: 说明 "支付方式标签（如：微信支付、定金微信+尾款线下）" → "支付方式标签（如：微信支付、订金微信+尾款线下）" - -#### ✏️ OrderListVO - - - ✏️ `depositAmount`: 说明 "定金金额" → "订金金额" - - ✏️ `balanceAmount`: 说明 "尾款金额（DEPOSIT模式：总售价-定金-优惠）" → "尾款金额（DEPOSIT模式：总售价-订金-优惠）" - -#### ✏️ UpdateDepositRequest - - - ✏️ `amount`: 说明 "定金金额" → "订金金额" - -#### ✏️ UpdateOrderStatusRequest - - - ✏️ `status`: 说明 "目标状态。可选值：PENDING_PAY(待支付)/DEPOSIT_PAID(已付定金)/PAID(已全额支付)/" → "目标状态。可选值：PENDING_PAY(待支付)/DEPOSIT_PAID(已付订金)/PAID(已全额支付)/" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/OrderPayInfoDTO.java -M hl-common/hl-common-core/src/main/java/com/hulalv/common/dto/PaymentResultDTO.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpCustomizeController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpOrderController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpCustomProductListVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderListItemVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpProductQuoteVO.java -M hl-mp-service/src/main/java/com/hulalv/mp/vo/MpRefundDetailVO.java -M hl-mp-service/src/test/java/com/hulalv/mp/VoCoverageTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/VoExtraDeepCoverageTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerBranchTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/ProductAggregationServiceTest.java -M hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java -M hl-order-service/src/main/java/com/hulalv/order/controller/AdminOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalMpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalPaymentOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalRefundController.java -M hl-order-service/src/main/java/com/hulalv/order/controller/MpOrderController.java -M hl-order-service/src/main/java/com/hulalv/order/dto/AdminUpdateOrderRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/UpdateDepositRequest.java -M hl-order-service/src/main/java/com/hulalv/order/dto/UpdateOrderStatusRequest.java -M hl-order-service/src/main/java/com/hulalv/order/entity/OrderInfo.java -M hl-order-service/src/main/java/com/hulalv/order/job/DepartureReminderJob.java -M hl-order-service/src/main/java/com/hulalv/order/service/NotificationEventHelper.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderItineraryEditService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java -M hl-order-service/src/main/java/com/hulalv/order/service/OrderTodoService.java -M hl-order-service/src/main/java/com/hulalv/order/service/RefundApplicationService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/MpOrderListVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderDetailVO.java -M hl-order-service/src/main/java/com/hulalv/order/vo/OrderListVO.java -M hl-order-service/src/main/java/com/hulalv/payment/service/PaymentService.java -M hl-order-service/src/test/java/com/hulalv/order/constant/OrderConstantsTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/NotificationEventHelperTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceExtendedTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/OrderServiceTest.java -M hl-order-service/src/test/java/com/hulalv/order/service/RefundApplicationServiceTest.java -M hl-order-service/src/test/java/com/hulalv/payment/service/PaymentServiceTest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/MpProductController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/PricingController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/MpProductQueryRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductPricingService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/GroupBatchCalendarVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/MpProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -M hl-product-service/src/test/java/com/hulalv/product/service/MpProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1043_cf91698a_feat.md b/changelogs/2026-04/2026-04-02_1043_cf91698a_feat.md deleted file mode 100644 index 228baee..0000000 --- a/changelogs/2026-04/2026-04-02_1043_cf91698a_feat.md +++ /dev/null @@ -1,176 +0,0 @@ -# 接口变更记录 — 2026-04-02 10:43 - -> **提交** `cf91698a` · **作者** wx · **时间** 2026-04-02 10:43:03 +0800 -> -> feat: 产品旅行相册功能——用户授权相册+好评图片聚合 - -## 变更总览 - -- **小程序聚合服务** - - MpAlbum (+1) - - MpProduct (+1) -- **用户服务** - - InternalReview (+1) -- **订单服务** - - InternalAlbum (+2) - ---- - -## 小程序聚合服务 - -### MpAlbum - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 相册接口」** - -### 🆕 `PUT` /mp/album/folder/{folderId}/authorize — 授权/取消授权相册文件夹公开展示 - -> 用户主动授权将相册文件夹分享到产品旅行相册中展示。 - -**参数** - - - `{folderId}` (`Long`) — 路径参数 - - `authorized` (`boolean`) — 查询参数 - -**响应** `Result<Void>` - -### MpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 产品接口」** - -### 🆕 `GET` /mp/product/{productId}/travel-album — 产品旅行相册（分页） - -> 聚合用户授权的订单相册图片 + 好评评价图片，按时间倒序返回。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `page` (`int`) — 查询参数：页码，默认1 - - `size` (`int`) — 查询参数：每页数量，默认20 - -**响应** `Result<MpTravelAlbumVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `photos` | `List<TravelPhotoVO>` | 混合排序后的图片列表（当前页） | -| `total` | `long` | 总图片数（两个来源合计） | -| `page` | `int` | 当前页 | -| `size` | `int` | 每页大小 | -| `albumTotal` | `long` | 相册图片总数 | -| `reviewTotal` | `long` | 评价图片总数 | -| `ossUrl` | `String` | 图片访问URL | -| `thumbnailUrl` | `String` | 缩略图URL | -| `fileType` | `String` | 文件类型: IMAGE/VIDEO | -| `source` | `String` | 来源: ALBUM=订单相册 / REVIEW=用户评价 | -| `authorName` | `String` | 作者名（相册为资源名称，评价为用户昵称） | -| `description` | `String` | 描述 | -| `createdAt` | `LocalDateTime` | 创建时间 | - -**关联字典** - -- `album_file_type`（fileType）：IMAGE=图片, VIDEO=视频 - ---- - -## 用户服务 - -### InternalReview - -> 📖 **接口文档**: [http://192.168.100.236:8081/doc.html](http://192.168.100.236:8081/doc.html) → 标签 **「【内部接口】评价统计（Feign调用）」** - -### 🆕 `GET` /internal/review/product/{productId}/good-review-images — 按产品查好评图片（分页） - -> 用于产品详情页旅行相册模块，返回已审核好评中的图片 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `page` (`Integer`) — 查询参数 - - `size` (`Integer`) — 查询参数 - -**响应** `Result<PageResult<ReviewImageVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `imageUrl` | `String` | 图片URL | -| `userNickname` | `String` | 用户昵称 | -| `userAvatar` | `String` | 用户头像URL | -| `createdAt` | `LocalDateTime` | 创建时间 | - ---- - -## 订单服务 - -### InternalAlbum - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】小程序相册（Feign调用）」** - -### 🆕 `PUT` /internal/mp/album/folder/{folderId}/authorize — 用户授权/取消授权相册文件夹公开展示 - -> 用户在小程序中主动授权将相册分享到产品旅行相册 - -**参数** - - - `{folderId}` (`Long`) — 路径参数 - - `userId` (`Long`) — 查询参数 - - `authorized` (`boolean`) — 查询参数 - -**响应** `Result<Void>` - -### 🆕 `GET` /internal/mp/album/product/{productId}/shared-photos — 按产品查已授权共享的相册图片（分页） - -> 用于产品详情页的旅行相册模块，返回所有用户授权公开的相册图片 - -**参数** - - - `{productId}` (`Long`) — 路径参数 - - `page` (`int`) — 查询参数 - - `size` (`int`) — 查询参数 - -**响应** `Result<PageResult<SharedAlbumPhotoVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `ossUrl` | `String` | 文件访问URL | -| `thumbnailUrl` | `String` | 缩略图URL | -| `fileType` | `String` | 文件类型: IMAGE/VIDEO | -| `resourceName` | `String` | 资源名称(拍摄地点) | -| `description` | `String` | 文件描述 | -| `createdAt` | `LocalDateTime` | 创建时间 | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 订单服务 - -#### ✏️ AlbumFolderVO - - - 🆕 `shareAuthorized` (`Boolean`) — 是否已授权公开展示 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-gateway/src/main/java/com/hulalv/gateway/filter/JwtAuthFilter.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpAlbumController.java -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpAlbumFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpAlbumFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpReviewFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpReviewFeignFallbackFactory.java -A hl-mp-service/src/main/java/com/hulalv/mp/vo/MpTravelAlbumVO.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalAlbumController.java -M hl-order-service/src/main/java/com/hulalv/order/entity/AlbumFolder.java -M hl-order-service/src/main/java/com/hulalv/order/service/AlbumService.java -M hl-order-service/src/main/java/com/hulalv/order/vo/AlbumFolderVO.java -A hl-order-service/src/main/java/com/hulalv/order/vo/SharedAlbumPhotoVO.java -M hl-order-service/src/test/java/com/hulalv/order/service/AlbumServiceTest.java -M hl-user-service/src/main/java/com/hulalv/review/controller/InternalReviewController.java -M hl-user-service/src/main/java/com/hulalv/review/service/ReviewService.java -A hl-user-service/src/main/java/com/hulalv/review/vo/ReviewImageVO.java -M hl-user-service/src/test/java/com/hulalv/review/service/ReviewServiceTest.java -A sql/album_travel_album.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1306_d5c18baa_feat.md b/changelogs/2026-04/2026-04-02_1306_d5c18baa_feat.md deleted file mode 100644 index 5f82fed..0000000 --- a/changelogs/2026-04/2026-04-02_1306_d5c18baa_feat.md +++ /dev/null @@ -1,98 +0,0 @@ -# 接口变更记录 — 2026-04-02 13:06 - -> **提交** `d5c18baa` · **作者** wx · **时间** 2026-04-02 13:06:01 +0800 -> -> feat: 产品等级功能——支持轻奢/高档等级分组 - -## 变更总览 - -- **产品服务** - - Product (+1) - ---- - -## 产品服务 - -### Product - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「产品管理」** - -### 🆕 `GET` /admin/product/item/grade-groups — 查询等级分组列表（管理端选择关联等级产品用） - -**参数** - - - `lineId` (`Long`) — 查询参数：按产品线ID筛选 - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### 🆕 GradeOptionVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `String` | 产品ID | -| `productGrade` | `String` | 等级编码: LIGHT_LUXURY=轻奢, HIGH_END=高档 | -| `productGradeLabel` | `String` | 等级中文标签 | -| `startPrice` | `BigDecimal` | 起步价 | -| `startPriceLabel` | `String` | 起步价标签：'起' 或 '订金起' | - -#### ✏️ MpProductListVO - - - 🆕 `productGrade` (`String`) — 产品等级编码(null=无等级): LIGHT_LUXURY=轻奢, HIGH_END=高档 - - 🆕 `productGradeLabel` (`String`) — 产品等级中文标签 - - 🆕 `gradeGroupId` (`String`) — 等级分组ID(null=独立产品) - - 🆕 `gradeOptions` (`List<GradeOptionVO>`) — 同组所有等级选项(含自己，按gradeSort排序) - -#### ✏️ ProductCreateRequest - - - 🆕 `productGrade` (`String`) — 产品等级: LIGHT_LUXURY=轻奢, HIGH_END=高档(不传=无等级) - - 🆕 `gradeGroupId` (`Long`) — 等级分组ID(关联已有等级产品时传入) - - 🆕 `gradeSort` (`Integer`) — 等级排序(同组内) - -#### ✏️ ProductListVO - - - 🆕 `productGrade` (`String`) — 产品等级编码(null=无等级) - - 🆕 `productGradeLabel` (`String`) — 产品等级中文 - - 🆕 `gradeGroupId` (`String`) — 等级分组ID(null=独立产品) - -#### ✏️ ProductSaveRequest - - - 🆕 `productGrade` (`String`) — 产品等级: LIGHT_LUXURY=轻奢, HIGH_END=高档(不传=无等级) - - 🆕 `gradeGroupId` (`Long`) — 等级分组ID(关联已有等级产品时传入该产品的gradeGroupId，首个等级产品不传) - - 🆕 `gradeSort` (`Integer`) — 等级排序(同组内，越小越靠前) - -#### ✏️ ProductUpdateRequest - - - 🆕 `productGrade` (`String`) — 产品等级: LIGHT_LUXURY=轻奢, HIGH_END=高档(不传=无等级) - - 🆕 `gradeGroupId` (`Long`) — 等级分组ID(关联已有等级产品时传入) - - 🆕 `gradeSort` (`Integer`) — 等级排序(同组内) - -#### ✏️ ProductVO - - - 🆕 `productGrade` (`String`) — 产品等级编码(null=无等级): LIGHT_LUXURY=轻奢, HIGH_END=高档 - - 🆕 `productGradeLabel` (`String`) — 产品等级中文标签 - - 🆕 `gradeGroupId` (`String`) — 等级分组ID(null=独立产品) - - 🆕 `gradeOptions` (`List<GradeOptionVO>`) — 同组所有等级选项(含自己，按gradeSort排序) - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -A hl-product-service/src/main/java/com/hulalv/product/vo/GradeOptionVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/MpProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1402_a1598784_feat.md b/changelogs/2026-04/2026-04-02_1402_a1598784_feat.md deleted file mode 100644 index 4379347..0000000 --- a/changelogs/2026-04/2026-04-02_1402_a1598784_feat.md +++ /dev/null @@ -1,54 +0,0 @@ -# 接口变更记录 — 2026-04-02 14:02 - -> **提交** `a1598784` · **作者** wx · **时间** 2026-04-02 14:02:10 +0800 -> -> feat: 产品线绑定产品类型——创建产品时按类型筛选产品线 - -## 变更总览 - -- **产品服务** - - ProductLine (改1) - ---- - -## 产品服务 - -### ProductLine - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「产品线管理」** - -### ✏️ `GET` /admin/product/line/active — 所有启用的产品线 - - -**响应变更** `ProductLineVO`: - - - 🆕 `productType` (`String`) — 绑定产品类型: CORE/GROUP/CUSTOM/ROUTE(null=未绑定) -- 参数: 无 → productType(String) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ LineCreateRequest - - - 🆕 `productType` (`String`) — 绑定产品类型: CORE=核心产品 GROUP=拼团 CUSTOM=定制 ROUTE=线路 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/ProductLineController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/LineCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductLine.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductLineService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductLineVO.java -M hl-product-service/src/test/java/com/hulalv/product/controller/InternalMpProductControllerTest.java -M hl-product-service/src/test/java/com/hulalv/product/controller/ProductLineControllerTest.java -M hl-product-service/src/test/java/com/hulalv/product/service/ProductLineServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1429_dca8f78c_refactor.md b/changelogs/2026-04/2026-04-02_1429_dca8f78c_refactor.md deleted file mode 100644 index 65e35e0..0000000 --- a/changelogs/2026-04/2026-04-02_1429_dca8f78c_refactor.md +++ /dev/null @@ -1,72 +0,0 @@ -# 接口变更记录 — 2026-04-02 14:29 - -> **提交** `dca8f78c` · **作者** wx · **时间** 2026-04-02 14:29:09 +0800 -> -> refactor: 去掉产品等级概念，用产品名作为版本名 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ GradeOptionVO - - - 🆕 `name` (`String`) — 产品名称（即版本名） - - ❌ ~~`productGrade`~~ (`String`) — 等级编码: LIGHT_LUXURY=轻奢, HIGH_END=高档 - - ❌ ~~`productGradeLabel`~~ (`String`) — 等级中文标签 - -#### ✏️ MpProductListVO - - - ❌ ~~`productGrade`~~ (`String`) — 产品等级编码(null=无等级): LIGHT_LUXURY=轻奢, HIGH_END=高档 - - ❌ ~~`productGradeLabel`~~ (`String`) — 产品等级中文标签 - - ✏️ `gradeGroupId`: 说明 "等级分组ID(null=独立产品)" → "版本分组ID(null=独立产品，有值时同组产品在列表合并)" - - ✏️ `gradeOptions`: 说明 "同组所有等级选项(含自己，按gradeSort排序)" → "同组所有版本选项(含自己)" - -#### ✏️ ProductCreateRequest - - - ❌ ~~`productGrade`~~ (`String`) — 产品等级: LIGHT_LUXURY=轻奢, HIGH_END=高档(不传=无等级) - - ❌ ~~`gradeSort`~~ (`Integer`) — 等级排序(同组内) - - ✏️ `gradeGroupId`: 说明 "等级分组ID(关联已有等级产品时传入)" → "版本分组ID(关联已有版本产品时传入)" - -#### ✏️ ProductListVO - - - ❌ ~~`productGrade`~~ (`String`) — 产品等级编码(null=无等级) - - ❌ ~~`productGradeLabel`~~ (`String`) — 产品等级中文 - - ✏️ `gradeGroupId`: 说明 "等级分组ID(null=独立产品)" → "版本分组ID(null=独立产品)" - -#### ✏️ ProductSaveRequest - - - ❌ ~~`productGrade`~~ (`String`) — 产品等级: LIGHT_LUXURY=轻奢, HIGH_END=高档(不传=无等级) - - ❌ ~~`gradeSort`~~ (`Integer`) — 等级排序(同组内，越小越靠前) - - ✏️ `gradeGroupId`: 说明 "等级分组ID(关联已有等级产品时传入该产品的gradeGroupId，首个等级产品不传)" → "版本分组ID(关联已有版本产品时传入该产品的gradeGroupId，首个版本产品不传)" - -#### ✏️ ProductUpdateRequest - - - ❌ ~~`productGrade`~~ (`String`) — 产品等级: LIGHT_LUXURY=轻奢, HIGH_END=高档(不传=无等级) - - ❌ ~~`gradeSort`~~ (`Integer`) — 等级排序(同组内) - - ✏️ `gradeGroupId`: 说明 "等级分组ID(关联已有等级产品时传入)" → "版本分组ID(关联已有版本产品时传入)" - -#### ✏️ ProductVO - - - ❌ ~~`productGrade`~~ (`String`) — 产品等级编码(null=无等级): LIGHT_LUXURY=轻奢, HIGH_END=高档 - - ❌ ~~`productGradeLabel`~~ (`String`) — 产品等级中文标签 - - ✏️ `gradeGroupId`: 说明 "等级分组ID(null=独立产品)" → "版本分组ID(null=独立产品)" - - ✏️ `gradeOptions`: 说明 "同组所有等级选项(含自己，按gradeSort排序)" → "同组所有版本选项(含自己)" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/constant/ProductConstants.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/GradeOptionVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/MpProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1515_bb42f73e_refactor_gradeGro.md b/changelogs/2026-04/2026-04-02_1515_bb42f73e_refactor_gradeGro.md deleted file mode 100644 index 91e57a8..0000000 --- a/changelogs/2026-04/2026-04-02_1515_bb42f73e_refactor_gradeGro.md +++ /dev/null @@ -1,127 +0,0 @@ -# 接口变更记录 — 2026-04-02 15:15 - -> **提交** `bb42f73e` · **作者** wx · **时间** 2026-04-02 15:15:02 +0800 -> -> refactor: 删除gradeGroupId，用lineId做版本分组 + 产品线详情接口 - -## 变更总览 - -- **产品服务** - - InternalMpProduct (+1) - - Product (-1) -- **小程序聚合服务** - - MpProduct (+1) - ---- - -## 产品服务 - -### InternalMpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】小程序产品（Feign调用）」** - -### 🆕 `GET` /internal/mp/product/line/{lineId}/products — 产品线下所有已上架产品（不做版本去重） - -> 按产品线ID查询所有已上架产品，用于产品线详情页展示。 - -**参数** - - - `{lineId}` (`Long`) — 路径参数 - -**响应** `Result<List<MpProductListVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `String` | 产品ID | -| `productType` | `String` | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 | -| `gradeOptions` | `List<GradeOptionVO>` | 同产品线版本选项(null=独立产品或产品线仅一个产品) | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `departureCity` | `String` | 出发城市 | -| `destinationCity` | `String` | 目的地城市 | -| `tags` | `List<String>` | 产品标签列表 | -| `seasons` | `List<String>` | 适用季节列表(编码) | -| `seasonLabels` | `List<String>` | 适用季节列表(中文) | -| `coverImageUrl` | `String` | 封面图URL | -| `lineName` | `String` | 产品线名称 | -| `startPrice` | `BigDecimal` | 起步价：全款模式=最低售价，订金模式=最低订金额 | -| `startPriceLabel` | `String` | 起步价标签：'起' 或 '订金起' | -| `paymentMode` | `String` | 支付模式：FULL=全款 DEPOSIT=订金+尾款 | -| `routeMapUrl` | `String` | 路径图URL | -| `creatorName` | `String` | 创作者姓名 | -| `creatorAvatarUrl` | `String` | 定制师头像URL | - -### Product - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「产品管理」** - -### ❌ ~~`GET` /admin/product/item/grade-groups — 查询等级分组列表（管理端选择关联等级产品用）~~ - ---- - -## 小程序聚合服务 - -### MpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 产品接口」** - -### 🆕 `GET` /mp/product/line/{lineId} — 产品线详情 - -> 返回产品线信息 + 该线下所有已上架产品摘要 + 第一个产品的完整详情。 - -**参数** - - - `{lineId}` (`Long`) — 路径参数：产品线ID - -**响应** `Result<Map<String, Object>>` - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductCreateRequest - - - ❌ ~~`gradeGroupId`~~ (`Long`) — 版本分组ID(关联已有版本产品时传入) - -#### ✏️ ProductListVO - - - ❌ ~~`gradeGroupId`~~ (`String`) — 版本分组ID(null=独立产品) - -#### ✏️ ProductSaveRequest - - - ❌ ~~`gradeGroupId`~~ (`Long`) — 版本分组ID(关联已有版本产品时传入该产品的gradeGroupId，首个版本产品不传) - -#### ✏️ ProductUpdateRequest - - - ❌ ~~`gradeGroupId`~~ (`Long`) — 版本分组ID(关联已有版本产品时传入) - -#### ✏️ ProductVO - - - ❌ ~~`gradeGroupId`~~ (`String`) — 版本分组ID(null=独立产品) - - ✏️ `gradeOptions`: 说明 "同组所有版本选项(含自己)" → "同产品线版本选项(null=独立产品或产品线仅一个产品)" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java -M hl-product-service/src/main/java/com/hulalv/product/controller/ProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/MpProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductListVO.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1525_fdbff492_feat.md b/changelogs/2026-04/2026-04-02_1525_fdbff492_feat.md deleted file mode 100644 index 3fdc37c..0000000 --- a/changelogs/2026-04/2026-04-02_1525_fdbff492_feat.md +++ /dev/null @@ -1,25 +0,0 @@ -# 接口变更记录 — 2026-04-02 15:25 - -> **提交** `fdbff492` · **作者** wx · **时间** 2026-04-02 15:25:21 +0800 -> -> feat: 管理端价格日历接口返回小童售价和幼童售价（只读计算字段） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ PriceCalendarVO - - - 🆕 `youngChildSellPrice` (`BigDecimal`) — 小童售价（只读，根据定价配置自动计算） - - 🆕 `babySellPrice` (`BigDecimal`) — 幼童售价（只读，根据定价配置自动计算） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/service/PriceCalendarService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/PriceCalendarVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1714_80db9dee_feat_CHILD_MI.md b/changelogs/2026-04/2026-04-02_1714_80db9dee_feat_CHILD_MI.md deleted file mode 100644 index cce12bd..0000000 --- a/changelogs/2026-04/2026-04-02_1714_80db9dee_feat_CHILD_MI.md +++ /dev/null @@ -1,41 +0,0 @@ -# 接口变更记录 — 2026-04-02 17:14 - -> **提交** `80db9dee` · **作者** wx · **时间** 2026-04-02 17:14:21 +0800 -> -> feat: 小童定价新增CHILD_MINUS模式（儿童价减固定金额） - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ PricingRequest - - - 🆕 `youngChildMinusAmount` (`BigDecimal`) — 小童减免金额（youngChildPriceMode=CHILD_MINUS时使用，小童价=儿童价-此金额） - - ✏️ `youngChildPriceMode`: 说明 "小童定价模式：PERCENT=按儿童价百分比, FIXED=固定价" → "小童定价模式：PERCENT=按儿童价百分比, FIXED=固定价, CHILD_MINUS=儿童价减固定金额" - -#### ✏️ ProductPricingVO - - - 🆕 `youngChildMinusAmount` (`BigDecimal`) — 小童减免金额（CHILD_MINUS模式，小童价=儿童价-此金额） - - ✏️ `youngChildPriceMode`: 说明 "小童定价模式: PERCENT/FIXED" → "小童定价模式: PERCENT/FIXED/CHILD_MINUS" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PricingRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/ProductPricing.java -M hl-product-service/src/main/java/com/hulalv/product/service/CostCalculationService.java -M hl-product-service/src/main/java/com/hulalv/product/service/PriceCalendarService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductPricingService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductPricingVO.java -A sql/young_child_minus_mode.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-02_1856_236fb21d_refactor.md b/changelogs/2026-04/2026-04-02_1856_236fb21d_refactor.md deleted file mode 100644 index 3147572..0000000 --- a/changelogs/2026-04/2026-04-02_1856_236fb21d_refactor.md +++ /dev/null @@ -1,117 +0,0 @@ -# 接口变更记录 — 2026-04-02 18:56 - -> **提交** `236fb21d` · **作者** wx · **时间** 2026-04-02 18:56:41 +0800 -> -> refactor: 早鸟优惠改为产品级别关联（产品设计时选择） - -## 变更总览 - -- **订单服务** - - InternalEarlyBird (+2) - ---- - -## 订单服务 - -### InternalEarlyBird - -> 📖 **接口文档**: [http://192.168.100.236:8084/doc.html](http://192.168.100.236:8084/doc.html) → 标签 **「【内部接口】早鸟优惠（Feign调用）」** - -### 🆕 `GET` /internal/mp/early-bird/{planId} — 根据ID获取早鸟计划详情 - -> 供产品服务加载早鸟文案和报价验证使用 - -**参数** - - - `{planId}` (`Long`) — 路径参数 - -**响应** `Result<EarlyBirdPlanVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `planId` | `Long` | 计划ID | -| `planName` | `String` | 计划名称 | -| `startDate` | `LocalDate` | 生效开始日期 | -| `endDate` | `LocalDate` | 生效结束日期 | -| `minPeople` | `Integer` | 最低人数 | -| `discountAmount` | `BigDecimal` | 优惠金额 | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | -| `productIds` | `List<Long>` | 适用产品ID列表（空表示适用全部CORE/GROUP产品） | -| `productNames` | `List<String>` | 适用产品名称列表（空表示适用全部） | - -### 🆕 `GET` /internal/mp/early-bird/{planId}/validate — 验证早鸟计划有效性 - -> 按ID查计划，验证enabled+日期范围+最低人数，有效则返回详情，无效返回null - -**参数** - - - `{planId}` (`Long`) — 路径参数 - - `totalPeople` (`int`) — 查询参数 - -**响应** `Result<EarlyBirdPlanVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `planId` | `Long` | 计划ID | -| `planName` | `String` | 计划名称 | -| `startDate` | `LocalDate` | 生效开始日期 | -| `endDate` | `LocalDate` | 生效结束日期 | -| `minPeople` | `Integer` | 最低人数 | -| `discountAmount` | `BigDecimal` | 优惠金额 | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | -| `productIds` | `List<Long>` | 适用产品ID列表（空表示适用全部CORE/GROUP产品） | -| `productNames` | `List<String>` | 适用产品名称列表（空表示适用全部） | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### 产品服务 - -#### ✏️ ProductCreateRequest - - - 🆕 `earlyBirdPlanId` (`Long`) — 早鸟优惠计划ID - -#### ✏️ ProductSaveRequest - - - 🆕 `earlyBirdPlanId` (`Long`) — 早鸟优惠计划ID - -#### ✏️ ProductUpdateRequest - - - 🆕 `earlyBirdPlanId` (`Long`) — 早鸟优惠计划ID - -#### ✏️ ProductVO - - - 🆕 `earlyBirdPlanId` (`String`) — 早鸟优惠计划ID - - 🆕 `earlyBirdPlanName` (`String`) — 早鸟优惠计划名称 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java -M hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerBranchTest.java -M hl-order-service/src/main/java/com/hulalv/order/controller/InternalEarlyBirdController.java -M hl-order-service/src/main/java/com/hulalv/order/service/EarlyBirdPlanService.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductCreateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductSaveRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/ProductUpdateRequest.java -M hl-product-service/src/main/java/com/hulalv/product/entity/Product.java -M hl-product-service/src/main/java/com/hulalv/product/feign/EarlyBirdFallbackFactory.java -M hl-product-service/src/main/java/com/hulalv/product/feign/EarlyBirdFeignClient.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/vo/ProductVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-03_1045_fix_payment_timeout_and_order.md b/changelogs/2026-04/2026-04-03_1045_fix_payment_timeout_and_order.md deleted file mode 100644 index a8f5763..0000000 --- a/changelogs/2026-04/2026-04-03_1045_fix_payment_timeout_and_order.md +++ /dev/null @@ -1,32 +0,0 @@ -# fix: 支付超时修复 + 订单功能优化 - -**PR**: #145 | **服务**: hl-order-service | **日期**: 2026-04-03 - -## 变更内容 - -### 1. 微信支付SDK超时修复（后端修复，前端无需改动） -- 修复微信预下单请求可能无限阻塞的问题 -- 配置HTTP超时：connect=10s, read=30s, write=15s -- 超时后会返回明确错误信息给前端 - -### 2. 商户号修改限制 -- **仅待支付(PENDING_PAY)状态**的订单可以修改商户号 -- 已支付的订单修改商户号会返回错误：`商户号只能在支付前修改` -- 商户号修改不再记录到订单timeline - -### 3. 订单删除范围扩大 -- **新增**：已取消(CANCELLED)且未支付(paidAmount=0)的订单可以删除 -- 原有：待支付(PENDING_PAY)的订单可以删除 -- 已取消但有已支付金额的订单仍不可删除 - -### 4. 支付提醒短信延迟发送（后端修复，前端无需改动） -- 订单创建时不再立即发送短信 -- 改为创建后10分钟，仍未支付才发送支付提醒短信 -- 订单创建时的站内信/小程序通知不受影响，仍然立即发送 - -## 前端需关注 -- 订单删除按钮：已取消且未支付的订单也应显示删除按钮（之前只有待支付才显示） -- 商户号编辑：已支付订单需禁用商户号选择器，或在编辑失败时处理错误提示 - -## 部署备注 -需重启 `hl-order-service` diff --git a/changelogs/2026-04/2026-04-03_1141_c045ec7a_fix_status_OPE.md b/changelogs/2026-04/2026-04-03_1141_c045ec7a_fix_status_OPE.md deleted file mode 100644 index 4cb606c..0000000 --- a/changelogs/2026-04/2026-04-03_1141_c045ec7a_fix_status_OPE.md +++ /dev/null @@ -1,45 +0,0 @@ -# 接口变更记录 — 2026-04-03 11:41 - -> **提交** `c045ec7a` · **PR** #146 · **作者** wx · **时间** 2026-04-03 11:41:45 +0800 -> -> fix: 价格日历status字段OPEN/AVAILABLE不一致，导致小程序看不到可售日期 - -## 变更总览 - -**纯后端BUG修复，前端无需改动。** - -### 🐛 修复内容 - -价格日历 `status` 字段在后端代码中存在 `"OPEN"` 和 `"AVAILABLE"` 两种值混用，导致： -1. 小程序价格日历接口对旧数据（status="OPEN"）返回 `status=0`（不可售），实际应为可售 -2. `earliestBookingDate` 查不到新设置的可售日期 -3. 起步价计算漏掉部分可售记录 - -**修复后**：所有 API 已兼容两种 status 值，新保存的数据统一归一化为 `"AVAILABLE"`。 - -### 📋 DTO 字段说明更新 - -| DTO | 字段 | 变更 | -|-----|------|------| -| PriceCalendarRequest | `status` | 说明改为 "AVAILABLE=可售 CLOSED=关闭" | -| PriceCalendarBatchRequest | `status` | 同上 | - -> 后端已兼容旧值 `"OPEN"`，前端传 `"OPEN"` 仍可正常工作，会自动转为 `"AVAILABLE"` 保存。 - -### 🔧 需重启服务 - -- **hl-product-service** - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarBatchRequest.java -M hl-product-service/src/main/java/com/hulalv/product/dto/PriceCalendarRequest.java -M hl-product-service/src/main/java/com/hulalv/product/service/GroupTourBatchService.java -M hl-product-service/src/main/java/com/hulalv/product/service/PriceCalendarService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductService.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductStatusService.java -``` -</details> diff --git a/changelogs/2026-04/2026-04-03_1205_fix_order_duplicate.md b/changelogs/2026-04/2026-04-03_1205_fix_order_duplicate.md deleted file mode 100644 index cba450e..0000000 --- a/changelogs/2026-04/2026-04-03_1205_fix_order_duplicate.md +++ /dev/null @@ -1,23 +0,0 @@ -# fix: 订单重复创建——Service层增加业务级去重 - -- **时间**: 2026-04-03 12:05 -- **PR**: #147 -- **影响服务**: hl-order-service - -## 变更内容 - -### BUG修复：订单重复创建 - -**问题**：用户在小程序提交订单后，如果获取支付参数失败，重新点击"提交订单"会创建新的重复订单。 - -**修复**：在创建订单时增加业务级去重——同一用户+同一产品+同一出发日期如果已有待支付订单，直接返回已有订单，不再重复创建。 - -## 前端影响 - -**无需前端改动**。后端行为变化： -- 之前：重复提交会创建新订单 -- 现在：重复提交会返回已有的待支付订单（接口返回格式不变） - -## 需要重启的服务 - -- hl-order-service diff --git a/changelogs/2026-04/2026-04-03_1210_a344a2d8_fix_field_names.md b/changelogs/2026-04/2026-04-03_1210_a344a2d8_fix_field_names.md deleted file mode 100644 index 7007bf2..0000000 --- a/changelogs/2026-04/2026-04-03_1210_a344a2d8_fix_field_names.md +++ /dev/null @@ -1,32 +0,0 @@ -# 接口变更记录 — 2026-04-03 12:10 - -> **提交** `a344a2d8` · **PR** #148 · **作者** wx · **时间** 2026-04-03 12:10 +0800 -> -> fix: 价格日历API返回字段名与小程序前端不匹配(dateStr/price) - -## 变更总览 - -**纯后端修复，前端无需改动。** - -### 🐛 修复内容 - -小程序价格日历接口 `/mp/product/{id}/price-calendar` 返回的字段名与前端 calendar-popup 组件不匹配： -- 前端使用 `item.dateStr` → 后端只返回 `date` -- 前端使用 `item.price` → 后端只返回 `adultPrice` - -导致前端 `availableDates` 始终为空数组，日历无可选日期。 - -### 📋 接口响应变更 - -**GET** `/mp/product/{id}/price-calendar` - -每个日期对象**新增**两个字段（原有字段不变）： - -| 新增字段 | 类型 | 说明 | -|---------|------|------| -| `dateStr` | String | `date` 的别名，格式 yyyy-MM-dd | -| `price` | BigDecimal | `adultPrice` 的别名，成人售价 | - -### 🔧 需重启服务 - -- **hl-product-service** diff --git a/changelogs/2026-04/2026-04-03_1225_6cd9051c_fix_order_no.md b/changelogs/2026-04/2026-04-03_1225_6cd9051c_fix_order_no.md deleted file mode 100644 index b30bd59..0000000 --- a/changelogs/2026-04/2026-04-03_1225_6cd9051c_fix_order_no.md +++ /dev/null @@ -1,27 +0,0 @@ -# 接口变更记录 — 2026-04-03 12:25 - -> **提交** `6cd9051c` · **PR** #150 · **作者** wx · **时间** 2026-04-03 12:25 +0800 -> -> fix: 订单号追加团号后缀，避免微信支付商户订单号冲突 - -## 变更总览 - -**前端无需改动。** - -### 🐛 修复内容 - -测试和正式环境共用同一微信商户号，相同订单号导致微信支付返回 `INVALID_REQUEST "请求重入时，参数与首次请求时不一致"`。 - -### 📋 订单号格式变更 - -| 变更前 | 变更后 | -|--------|--------| -| `HL2604-ZQ-001` | `HL2604-ZQ-001_7790` | - -尾部追加 `_` + 4位团号，确保跨环境唯一。所有创建订单的接口（C端/管理端/GROUP）均已修改。 - -> 前端如果有显示订单号的地方，格式会多出 `_XXXX` 后缀，无需适配。 - -### 🔧 需重启服务 - -- **hl-order-service** diff --git a/changelogs/2026-04/2026-04-07_0919_4d461da5_fix.md b/changelogs/2026-04/2026-04-07_0919_4d461da5_fix.md deleted file mode 100644 index 0434cdb..0000000 --- a/changelogs/2026-04/2026-04-07_0919_4d461da5_fix.md +++ /dev/null @@ -1,59 +0,0 @@ -# 接口变更记录 — 2026-04-07 09:19 - -> **提交** `4d461da5` · **作者** wx · **时间** 2026-04-07 09:19:16 +0800 -> -> fix: 小程序产品线列表接口增加产品类型筛选和分页 - -## 变更总览 - -- **产品服务** - - InternalMpProduct (改1) -- **小程序聚合服务** - - MpProduct (改1) - ---- - -## 产品服务 - -### InternalMpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8085/doc.html](http://192.168.100.236:8085/doc.html) → 标签 **「【内部接口】小程序产品（Feign调用）」** - -### ✏️ `GET` /internal/mp/product/lines — 产品线列表（活跃·分页） - -- 接口名称: ~~产品线列表（活跃）~~ → **产品线列表（活跃·分页）** -- 返回类型: `Result<List<ProductLineVO>>` → `Result<PageResult<ProductLineVO>>` -- 参数: 无 → productType(String), page(Integer), pageSize(Integer) - ---- - -## 小程序聚合服务 - -### MpProduct - -> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 产品接口」** - -### ✏️ `GET` /mp/product/lines — 产品线列表（分页） - -- 接口名称: ~~产品线列表~~ → **产品线列表（分页）** -- 返回类型: `Result<List<Map<String, Object>>>` → `Result<PageResult<Map<String, Object>>>` -- 参数: 无 → productType(String), page(Integer), pageSize(Integer) - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-mp-service/src/main/java/com/hulalv/mp/controller/MpProductController.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignClient.java -M hl-mp-service/src/main/java/com/hulalv/mp/feign/MpProductFeignFallbackFactory.java -M hl-mp-service/src/main/java/com/hulalv/mp/service/HomeAggregationService.java -M hl-mp-service/src/test/java/com/hulalv/mp/controller/MpProductControllerTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/feign/FallbackFactoryTest.java -M hl-mp-service/src/test/java/com/hulalv/mp/service/HomeAggregationServiceTest.java -M hl-product-service/src/main/java/com/hulalv/product/controller/InternalMpProductController.java -M hl-product-service/src/main/java/com/hulalv/product/service/ProductLineService.java -M hl-product-service/src/test/java/com/hulalv/product/controller/InternalMpProductControllerTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-12_1538_273bef51_feat_product-v2_Co.md b/changelogs/2026-04/2026-04-12_1538_273bef51_feat_product-v2_Co.md deleted file mode 100644 index 9cdf4b5..0000000 --- a/changelogs/2026-04/2026-04-12_1538_273bef51_feat_product-v2_Co.md +++ /dev/null @@ -1,1070 +0,0 @@ -# 接口变更记录 — 2026-04-12 15:38 - -> **提交** `273bef51` · **作者** wx · **时间** 2026-04-12 15:38:54 +0800 -> -> feat(product-v2): Controller层（admin/mp分包，44个接口+完整Swagger文档） - -## 变更总览 - -- **hl-product-service-v2** - - 🆕 AdminProduct (+28 接口) - - 🆕 AdminProductLine (+5 接口) - - 🆕 AdminProductTemplate (+3 接口) - - 🆕 MpProduct (+6 接口) - - 🆕 MpProductLine (+2 接口) - ---- - -## hl-product-service-v2 - -### 🆕 新增: AdminProduct - -### 📌 `POST` /admin/product/item — 创建产品 - -> 创建产品草稿，自动生成产品编号（C/G/D+日期+序号），返回产品ID。 - -**请求体** `ProductSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 产品名称（≤30字） | -| `productType` | `String` | 产品类型（字典product_type: CORE=核心产品, GROUP=小蒙马跟团游, CUSTOM=私人定制） | -| `lineId` | `Long` | 产品线ID（从 /admin/product/line/simple-list 下拉获取，私人定制可空） | -| `tripDays` | `Integer` | 行程天数（可选，创建后可在Step1修改） | - -**响应** `Result<Long>` - -### 📌 `PUT` /admin/product/item/{id}/basic — Step1 基础信息保存 - -> 保存产品基础信息。需传version做乐观锁校验，版本不一致返回错误提示刷新。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductBasicSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID（路径参数自动设入，前端不传） | -| `version` | `Integer` | 乐观锁版本号（从详情接口获取，提交时传回做并发校验） | -| `name` | `String` | 产品名称（≤30字） | -| `subtitle` | `String` | 副标题（一句话卖点，≤128字） | -| `introduction` | `String` | 产品简介（富文本HTML） | -| `lineId` | `Long` | 产品线ID（从产品线下拉接口获取，私人定制可空） | -| `tripDays` | `Integer` | 行程天数（≥1，晚数自动=天数-1） | -| `tripNights` | `Integer` | 行程晚数（通常=天数-1，不传自动计算） | -| `tiers` | `List<TierItem>` | 档位列表（JSON数组，如标准/舒适/豪华3档） | -| `seasons` | `List<String>` | 适用季节（字典product_season: spring=春, summer=夏, autumn=秋, winter=冬） | -| `tags` | `List<String>` | 产品标签（字典product_tag，多选） | -| `coverImageUrl` | `String` | 封面图URL | -| `carouselImages` | `List<String>` | 轮播图URL列表（≤10张） | -| `infantAgeMax` | `Integer` | 幼童年龄上限（默认1岁，幼童≤此值免费或特价） | -| `toddlerAgeMax` | `Integer` | 小童年龄上限（默认3岁，幼童<小童<儿童） | -| `childAgeMin` | `Integer` | 儿童年龄下限（默认4岁） | -| `childAgeMax` | `Integer` | 儿童年龄上限（默认12岁，超过按成人算） | -| `infantDefaultPrice` | `BigDecimal` | 幼童默认价（元，0=免费） | -| `isBooking` | `Boolean` | 是否预约产品（true=订金可不填出行人，false=正常下单） | -| `paymentType` | `String` | 支付方式（字典payment_type: FULL=全款支付, DEPOSIT=订金+尾款） | -| `depositRatio` | `Integer` | 订金比例（%，支付方式=DEPOSIT时使用，与固定额二选一） | -| `depositAmount` | `BigDecimal` | 订金固定额（元，支付方式=DEPOSIT时使用，与比例二选一） | -| `balanceDueDays` | `Integer` | 尾款支付期限（天，出发前N天需付清尾款） | -| `defaultDailyStock` | `Integer` | 每日库存默认值（NULL=不限量，用于价格日历预填） | -| `defaultRoomCount` | `Integer` | 默认房间数（小蒙马跟团游用，每个班期的初始房间数） | -| `minGroupSize` | `Integer` | 最低成团人数（0=不限，小蒙马用） | -| `minAdultPerOrder` | `Integer` | 每单最少成人数 | -| `maxAdultPerOrder` | `Integer` | 每单最多成人数 | -| `maxChildPerOrder` | `Integer` | 每单最多儿童数 | -| `showReview` | `Boolean` | 展示用户评价（true=产品详情页显示评价模块） | -| `showChatGroup` | `Boolean` | 展示群聊入口（true=显示加入群聊按钮） | -| `showTripTime` | `Boolean` | 展示行程时间（true=行程天显示起止时间） | -| `showTripDistance` | `Boolean` | 展示行程距离（true=行程天显示里程数） | -| `creatorAvatarUrl` | `String` | 创建者头像URL（产品详情页展示的领队/设计师头像） | -| `creatorIntro` | `String` | 创建者简介（≤512字） | -| `customizerId` | `Long` | 定制师ID（私人定制产品关联的定制师） | -| `customerName` | `String` | 客户姓名（私人定制的客户） | -| `contactPhone` | `String` | 联系电话（加密存储） | -| `departureDate` | `LocalDate` | 出发日期（私人定制的固定出发日期，格式yyyy-MM-dd） | -| `mchId` | `String` | 商户ID（微信支付商户号，多商户时指定） | -| `safetyItems` | `List<Object>` | 安全保障项（JSON数组 [{icon,title,description}]） | -| `photographyItems` | `List<Object>` | 摄影跟拍项（JSON数组 [{name,description}]） | -| `diningHighlights` | `List<Object>` | 餐饮亮点（JSON数组 [{name,description}]） | -| `tierSeq` | `Integer` | 档位序号（1=标准,2=舒适,3=豪华） | -| `tierName` | `String` | 档位名称 | - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/item/{id}/itinerary — Step2 行程整体保存 - -> 整体保存行程天+节点+住宿+路线点。支持新增/更新/删除（EntityDiffUtil对比）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductItinerarySaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 乐观锁版本号 | -| `days` | `List<DayItem>` | 行程天列表 | -| `dayId` | `Long` | 行程天ID(已有则传，新增不传) | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 当日标题 | -| `quoteText` | `String` | 当日金句 | -| `description` | `String` | 行程描述 | -| `coverImageUrl` | `String` | 当日封面图 | -| `breakfast` | `String` | 早餐(HOTEL/CAMP/SPECIAL/SELF) | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `diningRemark` | `String` | 餐饮备注 | -| `dailyMileage` | `BigDecimal` | 当日里程(km) | -| `mileageManualOverride` | `Boolean` | 里程是否手动覆盖 | -| `photoUrls` | `List<String>` | 照片集 | -| `customFields` | `Object` | 自定义概况 | -| `nodes` | `List<NodeItem>` | 活动节点列表 | -| `hotels` | `List<HotelItem>` | 住宿列表 | -| `routePoints` | `List<RoutePointItem>` | 途经路线点列表 | -| `nodeId` | `Long` | 节点ID(已有则传，新增不传) | -| `sortOrder` | `Integer` | 排序 | -| `nodeType` | `String` | 节点类型(SCENIC/ACTIVITY/RESTAURANT/SERVICE/CUSTOM等) | -| `nodeName` | `String` | 节点名称 | -| `resourceType` | `String` | 资源类型 | -| `resourceId` | `Long` | 资源ID | -| `startTime` | `String` | 开始时间(如10:00) | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `images` | `List<String>` | 图片列表 | -| `emojiIcon` | `String` | 图标 | -| `extraData` | `Object` | 扩展数据 | -| `id` | `Long` | 住宿ID(已有则传，新增不传) | -| `tierSeq` | `Integer` | 档位序号(无档位=1) | -| `hotelId` | `Long` | 酒店ID | -| `roomTypeId` | `Long` | 房型ID(私人定制用) | -| `roomCount` | `Integer` | 房间数(私人定制用) | -| `isDefault` | `Boolean` | 是否默认推荐 | -| `sortOrder` | `Integer` | 排序 | -| `resourceId` | `Long` | 资源ID(可空=自定义地点) | -| `name` | `String` | 地点名称 | -| `longitude` | `BigDecimal` | 经度 | -| `latitude` | `BigDecimal` | 纬度 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/itinerary/day — Step2 增加一天 - -> 在行程末尾追加一天，自动编号。返回新天的dayId。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Long>` - -### 📌 `DELETE` /admin/product/item/{id}/itinerary/day/{dayNumber} — Step2 删除一天 - -> 删除指定天序号的行程天，级联删除节点+住宿+路线点，后续天序号自动-1。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `{dayNumber}` (`Integer`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/item/{id}/route — Step3 路线与备品保存 - -> 保存路线总览(1:1)+备品清单(1:N)+额外成本项(1:N)。备品和成本项支持增删改。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductRouteSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 乐观锁版本号 | -| `routeName` | `String` | 路线名称 | -| `routeMapUrl` | `String` | 路线图URL(手动上传) | -| `totalMileage` | `BigDecimal` | 总里程(km) | -| `routeDescription` | `String` | 线路描述 | -| `vehicleModelId` | `Long` | 实际用车车型ID | -| `staffCostIds` | `List<Long>` | 服务人员成本ID列表 | -| `supplies` | `List<SuppliesItem>` | 备品列表 | -| `extraCosts` | `List<FeeItem>` | 额外成本项列表 | -| `id` | `Long` | 备品ID(已有则传，新增不传) | -| `suppliesResourceId` | `Long` | 备品资源ID(可空=自定义) | -| `suppliesName` | `String` | 备品名称 | -| `category` | `String` | 分类 | -| `hasCost` | `Boolean` | 是否涉及成本 | -| `billingType` | `String` | 计费方式(PER_PERSON/PER_QUANTITY) | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `sortOrder` | `Integer` | 排序 | -| `id` | `Long` | 费用项ID(已有则传，新增不传) | -| `resourceType` | `String` | 资源类型 | -| `resourceId` | `Long` | 资源ID | -| `costItemId` | `Long` | 费用项ID | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `daily` | `Boolean` | 是否按天计费 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/price-calendar — Step4 查询价格日历 - -> 按月份查询价格日历。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<ProductPriceCalendarDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | | -| `productId` | `Long` | | -| `tierSeq` | `Integer` | | -| `rangeId` | `Long` | | -| `date` | `LocalDate` | | -| `priceType` | `String` | | -| `adultSellPrice` | `BigDecimal` | | -| `childSellPrice` | `BigDecimal` | | -| `toddlerDiscount` | `BigDecimal` | | -| `infantPrice` | `BigDecimal` | | -| `dailyStock` | `Integer` | | -| `sold` | `Integer` | | - -### 📌 `GET` /admin/product/item/{id}/schedule/list — Step4 班期列表 - -> 查询产品下所有班期。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<GroupTourBatchDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | | -| `productId` | `Long` | | -| `batchNo` | `String` | | -| `batchLabel` | `String` | | -| `batchName` | `String` | | -| `productStockLimit` | `Integer` | | -| `adultPrice` | `BigDecimal` | | -| `childPrice` | `BigDecimal` | | -| `toddlerDiscount` | `BigDecimal` | | -| `infantPrice` | `BigDecimal` | | -| `departureDate` | `LocalDate` | | -| `endDate` | `LocalDate` | | -| `enrollmentDeadline` | `LocalDate` | | -| `maxParticipants` | `Integer` | | -| `enrolledCount` | `Integer` | | -| `maxRooms` | `Integer` | | -| `bookedRooms` | `Integer` | | -| `batchStatus` | `String` | | -| `sortOrder` | `Integer` | | -| `remark` | `String` | | -| `version` | `Integer` | | -| `createBy` | `Long` | | - -### 📌 `POST` /admin/product/item/{id}/price-calendar/batch — Step4 价格日历批量设置 - -> 按日期范围+档位批量设置价格（UPSERT）。已上架产品用priceVersion，草稿用version。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `PriceCalendarBatchReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 版本号(草稿用version/已上架用priceVersion) | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `tierSeq` | `Integer` | 档位序号(默认1) | -| `priceType` | `String` | 价格类型(NORMAL/PEAK/HOLIDAY/SPECIAL) | -| `adultSellPrice` | `BigDecimal` | 成人售价 | -| `childSellPrice` | `BigDecimal` | 儿童售价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童售价(0=免费) | -| `dailyStock` | `Integer` | 每日库存上限(NULL=不限量) | - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/product/item/{id}/price-calendar — Step4 价格日历删除 - -> 按日期范围+档位删除价格日历（物理删除）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `PriceCalendarBatchReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 版本号(草稿用version/已上架用priceVersion) | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `tierSeq` | `Integer` | 档位序号(默认1) | -| `priceType` | `String` | 价格类型(NORMAL/PEAK/HOLIDAY/SPECIAL) | -| `adultSellPrice` | `BigDecimal` | 成人售价 | -| `childSellPrice` | `BigDecimal` | 儿童售价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童售价(0=免费) | -| `dailyStock` | `Integer` | 每日库存上限(NULL=不限量) | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/schedule — Step4 创建班期 - -> 创建新班期，batchId不传。自动生成班期编号、计算结束日期和报名截止日。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID(修改时传) | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `enrollmentDeadline` | `LocalDate` | 报名截止日(默认出发前1天) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数(0=不限) | -| `productStockLimit` | `Integer` | 产品库存上限 | -| `remark` | `String` | 备注 | - -**响应** `Result<Long>` - -### 📌 `DELETE` /admin/product/item/{id}/schedule/{scheduleId} — Step4 删除班期 - -> 删除班期（已有报名订单不允许删除）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `{scheduleId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/item/{id}/schedule — Step4 修改班期 - -> 修改已有班期，batchId在body中传。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID(修改时传) | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `enrollmentDeadline` | `LocalDate` | 报名截止日(默认出发前1天) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数(0=不限) | -| `productStockLimit` | `Integer` | 产品库存上限 | -| `remark` | `String` | 备注 | - -**响应** `Result<Long>` - -### 📌 `POST` /admin/product/item/{id}/schedule/batch-create — Step4 班期批量创建 - -> 按重复模式批量创建班期（最多52个，跨度≤12个月）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleBatchCreateReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `repeatMode` | `String` | 重复模式(WEEKLY/BIWEEKLY/MONTHLY) | -| `dayOfWeek` | `Integer` | 星期几(1=周一...7=周日) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数 | - -**响应** `Result<Integer>` - -### 📌 `POST` /admin/product/item/{id}/schedule/{scheduleId}/cancel — Step4 取消班期 - -> 取消班期（有报名订单则标记为CANCELLING触发退款，无订单直接CANCELLED）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `{scheduleId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/schedule/team — 班期团队查询 - -> 查询指定班期的团队成员列表。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<GroupBatchStaffDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | | -| `batchId` | `Long` | | -| `productId` | `Long` | | -| `staffId` | `Long` | | -| `staffRole` | `String` | | -| `staffName` | `String` | | -| `staffPhone` | `String` | | -| `remark` | `String` | | -| `sortOrder` | `Integer` | | - -### 📌 `PUT` /admin/product/item/{id}/schedule/team — 班期团队保存 - -> 全量保存班期团队成员（全删全插策略，每次传完整列表）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleTeamSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `staffList` | `List<StaffItem>` | 团队成员列表 | -| `staffId` | `Long` | 员工ID | -| `staffRole` | `String` | 员工角色 | -| `staffName` | `String` | 员工名称 | -| `staffPhone` | `String` | 员工电话 | -| `remark` | `String` | 备注 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/quote — 报价计算 - -> 根据出发日期+人数+档位计算总价，返回每日明细。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `QuoteReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `departureDate` | `LocalDate` | 出发日期 | -| `adultCount` | `Integer` | 成人数 | -| `batchId` | `Long` | 班期ID(小蒙马用) | - -**响应** `Result<QuoteResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `totalAdultPrice` | `BigDecimal` | 成人总价 | -| `totalChildPrice` | `BigDecimal` | 儿童总价 | -| `grandTotal` | `BigDecimal` | 总价合计 | -| `dailyDetails` | `List<DailyDetail>` | 每日价格明细 | -| `date` | `String` | 日期 | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | - -### 📌 `PUT` /admin/product/item/{id}/supplement — Step5 补充信息保存 - -> 保存费用包含/不含/自定义项+人群优惠+补充配置（退改/车辆/保险/卖点等）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductSupplementSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 乐观锁版本号 | -| `includedFees` | `List<FeeItem>` | 费用包含列表 | -| `excludedFees` | `List<FeeItem>` | 费用不含列表 | -| `customFees` | `List<FeeItem>` | 自定义费用列表 | -| `feeIgnoredTypes` | `List<String>` | 费用推导已忽略类型 | -| `childTicket` | `String` | 儿童门票优惠(FREE/HALF_PRICE/FULL_PRICE) | -| `childAccommodation` | `String` | 儿童住宿(BED/NO_BED) | -| `childMeal` | `String` | 儿童餐饮(FULL/HALF) | -| `elderTicket` | `String` | 老人门票优惠 | -| `elderAccommodation` | `String` | 老人住宿 | -| `crowdBenefitTips` | `String` | 人群优惠温馨提示 | -| `vehicleModelIds` | `List<Long>` | 展示车型ID列表 | -| `vehicleRuleText` | `String` | 用车规则说明 | -| `refundPolicyIds` | `Object` | 退改政策映射 | -| `bookingTermsId` | `Long` | 预订条款ID | -| `warmTipsId` | `Long` | 温馨提示ID | -| `equipmentAdvice` | `String` | 装备建议(富文本) | -| `insuranceNotice` | `String` | 保险告知(INCLUDED/EXCLUDED/OPTIONAL) | -| `insuranceSchemeId` | `Long` | 保险方案ID | -| `contractSchemeId` | `Long` | 合同方案ID | -| `quickUnderstand` | `Object` | 快速理解 | -| `childExperience` | `Object` | 孩子经历 | -| `growthGains` | `List<Object>` | 成长收获 | -| `id` | `Long` | 费用项ID(已有则传) | -| `feeType` | `String` | 费用类型 | -| `source` | `String` | 来源(AUTO/MANUAL) | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | -| `unitPrice` | `BigDecimal` | 单价(自定义费用) | -| `unit` | `String` | 单位(自定义费用) | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id} — 产品详情 - -> 聚合全部5步数据（主表+基础+行程+路线+价格+补充），用于编辑页回显。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<ProductDetailRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productNo` | `String` | 产品编号 | -| `productType` | `String` | 产品类型 | -| `status` | `String` | 产品状态 | -| `version` | `Integer` | 乐观锁版本号 | -| `priceVersion` | `Integer` | 调价版本号 | -| `createBy` | `Long` | 创建人ID | -| `publishedAt` | `LocalDateTime` | 上架时间 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `lineId` | `Long` | 产品线ID | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `coverImageUrl` | `String` | 封面图 | -| `tiers` | `Object` | 档位列表 | -| `seasons` | `Object` | 产品季节 | -| `tags` | `Object` | 产品标签 | -| `carouselImages` | `Object` | 轮播图 | -| `infantAgeMax` | `Integer` | 幼童年龄上限 | -| `toddlerAgeMax` | `Integer` | 小童年龄上限 | -| `childAgeMin` | `Integer` | 儿童年龄下限 | -| `childAgeMax` | `Integer` | 儿童年龄上限 | -| `isBooking` | `Boolean` | 是否预约产品 | -| `paymentType` | `String` | 支付方式 | -| `depositRatio` | `Integer` | 订金比例 | -| `depositAmount` | `BigDecimal` | 订金固定额 | -| `showReview` | `Boolean` | 展示评价 | -| `creatorAvatarUrl` | `String` | 创建者头像 | -| `creatorIntro` | `String` | 创建者简介 | -| `customizerId` | `Long` | 定制师ID | -| `customerName` | `String` | 客户姓名 | -| `departureDate` | `LocalDate` | 出发日期(定制) | -| `mchId` | `String` | 商户ID | -| `itinerary` | `List<Object>` | 行程天列表 | -| `routeInfo` | `ProductRouteInfoDO` | 路线信息 | -| `supplies` | `List<ProductSuppliesDO>` | 备品列表 | -| `extraCosts` | `List<ProductFeeItemDO>` | 额外成本项 | -| `schedules` | `List<GroupTourBatchDO>` | 班期列表 | -| `includedFees` | `List<ProductFeeItemDO>` | 费用包含 | -| `excludedFees` | `List<ProductFeeItemDO>` | 费用不含 | -| `customFees` | `List<ProductFeeItemDO>` | 自定义费用 | -| `crowdBenefit` | `ProductCrowdBenefitDO` | 人群优惠 | -| `supplement` | `ProductSupplementDO` | 补充配置 | - -### 📌 `GET` /admin/product/item/list — 产品分页列表 - -> 支持按名称关键词/产品类型/产品线/状态筛选。 - -**响应** `Result<PageResult<ProductListRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productNo` | `String` | 产品编号 | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `coverImageUrl` | `String` | 封面图 | -| `tripDays` | `Integer` | 行程天数 | -| `status` | `String` | 产品状态 | -| `version` | `Integer` | 版本号 | -| `createBy` | `Long` | 创建人ID | -| `publishedAt` | `LocalDateTime` | 上架时间 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/product/item/{id} — 删除产品 - -> 级联删除产品+全部子表。仅草稿/已驳回/已下架/已完成状态可删，已上架/待审核需先下架。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/operation-logs — 产品操作记录 - -> 查询产品的全部操作记录（按时间倒序），审计保留不随产品删除。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<ProductOperationLogRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | 记录ID | -| `action` | `String` | 操作类型 | -| `detail` | `String` | 详情/驳回原因 | -| `step` | `String` | 步骤号 | -| `operatorId` | `Long` | 操作人ID | -| `operatorName` | `String` | 操作人名称 | -| `createTime` | `LocalDateTime` | 操作时间 | - -### 📌 `POST` /admin/product/item/{id}/action — 产品状态变更 - -> 通过COLA状态机驱动状态流转。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductActionReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `action` | `String` | 操作动作(SUBMIT_PUBLISH/WITHDRAW/DIRECT_PUBLISH/UNPUBLISH/FORCE_UNPUBLISH/COMPLETE) | -| `remark` | `String` | 备注/驳回原因(可选) | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/copy — 复制产品 - -> 深拷贝产品+全部子表（主表+6张1:1/1:N子表+行程数据），新产品为草稿状态。返回新产品ID。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Long>` - -### 📌 `PUT` /admin/product/item/{id}/transfer — 转让产品 - -> 更换产品创建人（仅超管可操作）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductTransferReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `newCreatorId` | `Long` | 新创建人ID | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/validate-publish — 上架预检 - -> 5级校验：L1基础字段→L2内容完整→L3定价→L4条款→L5资源。返回问题列表，空=全部通过。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<String>>` - -### 📌 `GET` /admin/product/item/{id}/fee-deduction-preview — 费用推导预览 - -> 根据行程节点类型自动推导费用包含项（景区→门票，酒店→住宿等），排除已忽略类型。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<FeeDeductionPreviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `feeType` | `String` | 费用类型标签 | -| `name` | `String` | 费用名称 | -| `source` | `String` | 来源（AUTO=自动推导） | -| `sourceNodeName` | `String` | 来源节点名称 | - -### 🆕 新增: AdminProductLine - -### 📌 `POST` /admin/product/line — 创建/修改产品线 - -**请求体** `ProductLineSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID(修改时传) | -| `name` | `String` | 名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `List<String>` | 适用季节 | -| `tags` | `List<String>` | 标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态(ACTIVE/INACTIVE) | - -**响应** `Result<Long>` - -### 📌 `GET` /admin/product/line/{id} — 产品线详情 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<ProductLineRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `Object` | 适用季节 | -| `tags` | `Object` | 产品线标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态 | -| `createBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/product/line/list — 产品线分页列表 - -**响应** `Result<PageResult<ProductLineRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `Object` | 适用季节 | -| `tags` | `Object` | 产品线标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态 | -| `createBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/product/line/{id} — 删除产品线 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/line/simple-list — 产品线下拉选项 - -**响应** `Result<List<ProductLineDropdownVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | - -### 🆕 新增: AdminProductTemplate - -### 📌 `GET` /admin/product/booking-terms/enabled — 预订条款下拉 - -**响应** `Result<List<BookingTermsVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 条款ID | -| `termsName` | `String` | 条款名称 | - -### 📌 `GET` /admin/product/warm-tips/enabled — 温馨提示下拉 - -**响应** `Result<List<WarmTipsVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 提示ID | -| `tipsName` | `String` | 提示名称 | - -### 📌 `GET` /admin/product/safety-template/enabled — 安全保障模板下拉 - -**响应** `Result<List<SafetyTemplateVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `items` | `String` | 具体条目（JSON） | - -### 🆕 新增: MpProduct - -### 📌 `GET` /mp/product/{id} — 产品详情 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<MpProductDetailRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `coverImageUrl` | `String` | 封面图 | -| `carouselImages` | `List<String>` | 轮播图 | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `itinerary` | `List<DayInfo>` | 行程天列表 | -| `includedFees` | `List<FeeInfo>` | 费用包含 | -| `excludedFees` | `List<FeeInfo>` | 费用不含 | -| `crowdBenefit` | `CrowdBenefitInfo` | 人群优惠 | -| `routeMapUrl` | `String` | 路线图URL | -| `creatorAvatarUrl` | `String` | 创建者头像 | -| `creatorIntro` | `String` | 创建者简介 | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 标题 | -| `description` | `String` | 描述 | -| `coverImageUrl` | `String` | 封面图 | -| `breakfast` | `String` | 早餐 | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `nodes` | `List<NodeInfo>` | 节点列表 | -| `nodeType` | `String` | 节点类型 | -| `nodeName` | `String` | 节点名称 | -| `startTime` | `String` | 开始时间 | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `childTicket` | `String` | 儿童门票 | -| `childAccommodation` | `String` | 儿童住宿 | -| `childMeal` | `String` | 儿童餐饮 | -| `elderTicket` | `String` | 老人门票 | -| `tips` | `String` | 温馨提示 | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | - -### 📌 `GET` /mp/product/{id}/price-calendar — 价格日历 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<MpPriceCalendarRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `days` | `List<CalendarDay>` | 日历列表 | -| `date` | `String` | 日期(yyyy-MM-dd) | -| `priceType` | `String` | 价格类型 | -| `adultPrice` | `BigDecimal` | 成人售价 | -| `childPrice` | `BigDecimal` | 儿童售价 | -| `isSelectable` | `Boolean` | 是否可选(有库存且未过期) | -| `remainStock` | `Integer` | 剩余库存(NULL=不限量) | - -### 📌 `GET` /mp/product/{id}/schedules — 班期列表 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<GroupTourBatchDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | | -| `productId` | `Long` | | -| `batchNo` | `String` | | -| `batchLabel` | `String` | | -| `batchName` | `String` | | -| `productStockLimit` | `Integer` | | -| `adultPrice` | `BigDecimal` | | -| `childPrice` | `BigDecimal` | | -| `toddlerDiscount` | `BigDecimal` | | -| `infantPrice` | `BigDecimal` | | -| `departureDate` | `LocalDate` | | -| `endDate` | `LocalDate` | | -| `enrollmentDeadline` | `LocalDate` | | -| `maxParticipants` | `Integer` | | -| `enrolledCount` | `Integer` | | -| `maxRooms` | `Integer` | | -| `bookedRooms` | `Integer` | | -| `batchStatus` | `String` | | -| `sortOrder` | `Integer` | | -| `remark` | `String` | | -| `version` | `Integer` | | -| `createBy` | `Long` | | - -### 📌 `POST` /mp/product/{id}/quote — C端报价 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `QuoteReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `departureDate` | `LocalDate` | 出发日期 | -| `adultCount` | `Integer` | 成人数 | -| `batchId` | `Long` | 班期ID(小蒙马用) | - -**响应** `Result<QuoteResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `totalAdultPrice` | `BigDecimal` | 成人总价 | -| `totalChildPrice` | `BigDecimal` | 儿童总价 | -| `grandTotal` | `BigDecimal` | 总价合计 | -| `dailyDetails` | `List<DailyDetail>` | 每日价格明细 | -| `date` | `String` | 日期 | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | - -### 📌 `GET` /mp/product/compare — 产品对比 - -**参数** - - - `ids` (`String`) — 查询参数 - -**响应** `Result<List<MpProductDetailRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `coverImageUrl` | `String` | 封面图 | -| `carouselImages` | `List<String>` | 轮播图 | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `itinerary` | `List<DayInfo>` | 行程天列表 | -| `includedFees` | `List<FeeInfo>` | 费用包含 | -| `excludedFees` | `List<FeeInfo>` | 费用不含 | -| `crowdBenefit` | `CrowdBenefitInfo` | 人群优惠 | -| `routeMapUrl` | `String` | 路线图URL | -| `creatorAvatarUrl` | `String` | 创建者头像 | -| `creatorIntro` | `String` | 创建者简介 | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 标题 | -| `description` | `String` | 描述 | -| `coverImageUrl` | `String` | 封面图 | -| `breakfast` | `String` | 早餐 | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `nodes` | `List<NodeInfo>` | 节点列表 | -| `nodeType` | `String` | 节点类型 | -| `nodeName` | `String` | 节点名称 | -| `startTime` | `String` | 开始时间 | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `childTicket` | `String` | 儿童门票 | -| `childAccommodation` | `String` | 儿童住宿 | -| `childMeal` | `String` | 儿童餐饮 | -| `elderTicket` | `String` | 老人门票 | -| `tips` | `String` | 温馨提示 | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | - -### 📌 `GET` /mp/product/{id}/tier-compare — 档位对比 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Map<Integer, List<ProductDayHotelDO>>>` - -### 🆕 新增: MpProductLine - -### 📌 `GET` /mp/product-line/list — 产品线列表 - -**参数** - - - `season` (`String`) — 查询参数 - -**响应** `Result<List<ProductLineDropdownVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | - -### 📌 `GET` /mp/product-line/{lineId}/products — 产品线下产品列表 - -**参数** - - - `{lineId}` (`Long`) — 路径参数 - -**响应** `Result<List<MpProductListRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `coverImageUrl` | `String` | 封面图 | -| `tripDays` | `Integer` | 行程天数 | -| `productType` | `String` | 产品类型 | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductLineController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductTemplateController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/mp/MpProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/mp/MpProductLineController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/interceptor/AdminAuthInterceptor.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-12_1538_ff42bed5_feat_product-v2_VO.md b/changelogs/2026-04/2026-04-12_1538_ff42bed5_feat_product-v2_VO.md deleted file mode 100644 index a27c68b..0000000 --- a/changelogs/2026-04/2026-04-12_1538_ff42bed5_feat_product-v2_VO.md +++ /dev/null @@ -1,602 +0,0 @@ -# 接口变更记录 — 2026-04-12 15:38 - -> **提交** `ff42bed5` · **作者** wx · **时间** 2026-04-12 15:38:39 +0800 -> -> feat(product-v2): VO/DTO层（含完整Swagger注解+字典标注） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### 🆕 BookingTermsVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 条款ID | -| `termsName` | `String` | 条款名称 | - -#### 🆕 FeeDeductionPreviewVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `feeType` | `String` | 费用类型标签 | -| `name` | `String` | 费用名称 | -| `source` | `String` | 来源（AUTO=自动推导） | -| `sourceNodeName` | `String` | 来源节点名称 | - -#### 🆕 ItineraryDayDeleteReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `dayNumber` | `Integer` | 天序号 | - -#### 🆕 MpPriceCalendarReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `month` | `String` | 月份(yyyy-MM) | - -#### 🆕 MpPriceCalendarRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `days` | `List<CalendarDay>` | 日历列表 | -| `date` | `String` | 日期(yyyy-MM-dd) | -| `priceType` | `String` | 价格类型 | -| `adultPrice` | `BigDecimal` | 成人售价 | -| `childPrice` | `BigDecimal` | 儿童售价 | -| `isSelectable` | `Boolean` | 是否可选(有库存且未过期) | -| `remainStock` | `Integer` | 剩余库存(NULL=不限量) | - -#### 🆕 MpProductDetailRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `coverImageUrl` | `String` | 封面图 | -| `carouselImages` | `List<String>` | 轮播图 | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `itinerary` | `List<DayInfo>` | 行程天列表 | -| `includedFees` | `List<FeeInfo>` | 费用包含 | -| `excludedFees` | `List<FeeInfo>` | 费用不含 | -| `crowdBenefit` | `CrowdBenefitInfo` | 人群优惠 | -| `routeMapUrl` | `String` | 路线图URL | -| `creatorAvatarUrl` | `String` | 创建者头像 | -| `creatorIntro` | `String` | 创建者简介 | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 标题 | -| `description` | `String` | 描述 | -| `coverImageUrl` | `String` | 封面图 | -| `breakfast` | `String` | 早餐 | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `nodes` | `List<NodeInfo>` | 节点列表 | -| `nodeType` | `String` | 节点类型 | -| `nodeName` | `String` | 节点名称 | -| `startTime` | `String` | 开始时间 | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `childTicket` | `String` | 儿童门票 | -| `childAccommodation` | `String` | 儿童住宿 | -| `childMeal` | `String` | 儿童餐饮 | -| `elderTicket` | `String` | 老人门票 | -| `tips` | `String` | 温馨提示 | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | - -#### 🆕 MpProductLineQueryReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `tag` | `String` | 标签筛选(可选) | - -#### 🆕 MpProductListRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `coverImageUrl` | `String` | 封面图 | -| `tripDays` | `Integer` | 行程天数 | -| `productType` | `String` | 产品类型 | - -#### 🆕 OperationLogReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `actionCode` | `String` | 操作动作编码 | -| `detail` | `String` | 操作详情 | -| `step` | `String` | 步骤编码 | - -#### 🆕 PriceCalendarBatchReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 版本号(草稿用version/已上架用priceVersion) | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `tierSeq` | `Integer` | 档位序号(默认1) | -| `priceType` | `String` | 价格类型(NORMAL/PEAK/HOLIDAY/SPECIAL) | -| `adultSellPrice` | `BigDecimal` | 成人售价 | -| `childSellPrice` | `BigDecimal` | 儿童售价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童售价(0=免费) | -| `dailyStock` | `Integer` | 每日库存上限(NULL=不限量) | - -#### 🆕 PriceCalendarQueryReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `month` | `String` | 月份(yyyy-MM) | -| `tierSeq` | `Integer` | 档位序号(默认1) | - -#### 🆕 ProductActionReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `action` | `String` | 操作动作(SUBMIT_PUBLISH/WITHDRAW/DIRECT_PUBLISH/UNPUBLISH/FORCE_UNPUBLISH/COMPLETE) | -| `remark` | `String` | 备注/驳回原因(可选) | - -#### 🆕 ProductBasicSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID（路径参数自动设入，前端不传） | -| `version` | `Integer` | 乐观锁版本号（从详情接口获取，提交时传回做并发校验） | -| `name` | `String` | 产品名称（≤30字） | -| `subtitle` | `String` | 副标题（一句话卖点，≤128字） | -| `introduction` | `String` | 产品简介（富文本HTML） | -| `lineId` | `Long` | 产品线ID（从产品线下拉接口获取，私人定制可空） | -| `tripDays` | `Integer` | 行程天数（≥1，晚数自动=天数-1） | -| `tripNights` | `Integer` | 行程晚数（通常=天数-1，不传自动计算） | -| `tiers` | `List<TierItem>` | 档位列表（JSON数组，如标准/舒适/豪华3档） | -| `seasons` | `List<String>` | 适用季节（字典product_season: spring=春, summer=夏, autumn=秋, winter=冬） | -| `tags` | `List<String>` | 产品标签（字典product_tag，多选） | -| `coverImageUrl` | `String` | 封面图URL | -| `carouselImages` | `List<String>` | 轮播图URL列表（≤10张） | -| `infantAgeMax` | `Integer` | 幼童年龄上限（默认1岁，幼童≤此值免费或特价） | -| `toddlerAgeMax` | `Integer` | 小童年龄上限（默认3岁，幼童<小童<儿童） | -| `childAgeMin` | `Integer` | 儿童年龄下限（默认4岁） | -| `childAgeMax` | `Integer` | 儿童年龄上限（默认12岁，超过按成人算） | -| `infantDefaultPrice` | `BigDecimal` | 幼童默认价（元，0=免费） | -| `isBooking` | `Boolean` | 是否预约产品（true=订金可不填出行人，false=正常下单） | -| `paymentType` | `String` | 支付方式（字典payment_type: FULL=全款支付, DEPOSIT=订金+尾款） | -| `depositRatio` | `Integer` | 订金比例（%，支付方式=DEPOSIT时使用，与固定额二选一） | -| `depositAmount` | `BigDecimal` | 订金固定额（元，支付方式=DEPOSIT时使用，与比例二选一） | -| `balanceDueDays` | `Integer` | 尾款支付期限（天，出发前N天需付清尾款） | -| `defaultDailyStock` | `Integer` | 每日库存默认值（NULL=不限量，用于价格日历预填） | -| `defaultRoomCount` | `Integer` | 默认房间数（小蒙马跟团游用，每个班期的初始房间数） | -| `minGroupSize` | `Integer` | 最低成团人数（0=不限，小蒙马用） | -| `minAdultPerOrder` | `Integer` | 每单最少成人数 | -| `maxAdultPerOrder` | `Integer` | 每单最多成人数 | -| `maxChildPerOrder` | `Integer` | 每单最多儿童数 | -| `showReview` | `Boolean` | 展示用户评价（true=产品详情页显示评价模块） | -| `showChatGroup` | `Boolean` | 展示群聊入口（true=显示加入群聊按钮） | -| `showTripTime` | `Boolean` | 展示行程时间（true=行程天显示起止时间） | -| `showTripDistance` | `Boolean` | 展示行程距离（true=行程天显示里程数） | -| `creatorAvatarUrl` | `String` | 创建者头像URL（产品详情页展示的领队/设计师头像） | -| `creatorIntro` | `String` | 创建者简介（≤512字） | -| `customizerId` | `Long` | 定制师ID（私人定制产品关联的定制师） | -| `customerName` | `String` | 客户姓名（私人定制的客户） | -| `contactPhone` | `String` | 联系电话（加密存储） | -| `departureDate` | `LocalDate` | 出发日期（私人定制的固定出发日期，格式yyyy-MM-dd） | -| `mchId` | `String` | 商户ID（微信支付商户号，多商户时指定） | -| `safetyItems` | `List<Object>` | 安全保障项（JSON数组 [{icon,title,description}]） | -| `photographyItems` | `List<Object>` | 摄影跟拍项（JSON数组 [{name,description}]） | -| `diningHighlights` | `List<Object>` | 餐饮亮点（JSON数组 [{name,description}]） | -| `tierSeq` | `Integer` | 档位序号（1=标准,2=舒适,3=豪华） | -| `tierName` | `String` | 档位名称 | - -#### 🆕 ProductDetailRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productNo` | `String` | 产品编号 | -| `productType` | `String` | 产品类型 | -| `status` | `String` | 产品状态 | -| `version` | `Integer` | 乐观锁版本号 | -| `priceVersion` | `Integer` | 调价版本号 | -| `createBy` | `Long` | 创建人ID | -| `publishedAt` | `LocalDateTime` | 上架时间 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `lineId` | `Long` | 产品线ID | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `coverImageUrl` | `String` | 封面图 | -| `tiers` | `Object` | 档位列表 | -| `seasons` | `Object` | 产品季节 | -| `tags` | `Object` | 产品标签 | -| `carouselImages` | `Object` | 轮播图 | -| `infantAgeMax` | `Integer` | 幼童年龄上限 | -| `toddlerAgeMax` | `Integer` | 小童年龄上限 | -| `childAgeMin` | `Integer` | 儿童年龄下限 | -| `childAgeMax` | `Integer` | 儿童年龄上限 | -| `isBooking` | `Boolean` | 是否预约产品 | -| `paymentType` | `String` | 支付方式 | -| `depositRatio` | `Integer` | 订金比例 | -| `depositAmount` | `BigDecimal` | 订金固定额 | -| `showReview` | `Boolean` | 展示评价 | -| `creatorAvatarUrl` | `String` | 创建者头像 | -| `creatorIntro` | `String` | 创建者简介 | -| `customizerId` | `Long` | 定制师ID | -| `customerName` | `String` | 客户姓名 | -| `departureDate` | `LocalDate` | 出发日期(定制) | -| `mchId` | `String` | 商户ID | -| `itinerary` | `List<Object>` | 行程天列表 | -| `routeInfo` | `ProductRouteInfoDO` | 路线信息 | -| `supplies` | `List<ProductSuppliesDO>` | 备品列表 | -| `extraCosts` | `List<ProductFeeItemDO>` | 额外成本项 | -| `schedules` | `List<GroupTourBatchDO>` | 班期列表 | -| `includedFees` | `List<ProductFeeItemDO>` | 费用包含 | -| `excludedFees` | `List<ProductFeeItemDO>` | 费用不含 | -| `customFees` | `List<ProductFeeItemDO>` | 自定义费用 | -| `crowdBenefit` | `ProductCrowdBenefitDO` | 人群优惠 | -| `supplement` | `ProductSupplementDO` | 补充配置 | - -#### 🆕 ProductItinerarySaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 乐观锁版本号 | -| `days` | `List<DayItem>` | 行程天列表 | -| `dayId` | `Long` | 行程天ID(已有则传，新增不传) | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 当日标题 | -| `quoteText` | `String` | 当日金句 | -| `description` | `String` | 行程描述 | -| `coverImageUrl` | `String` | 当日封面图 | -| `breakfast` | `String` | 早餐(HOTEL/CAMP/SPECIAL/SELF) | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `diningRemark` | `String` | 餐饮备注 | -| `dailyMileage` | `BigDecimal` | 当日里程(km) | -| `mileageManualOverride` | `Boolean` | 里程是否手动覆盖 | -| `photoUrls` | `List<String>` | 照片集 | -| `customFields` | `Object` | 自定义概况 | -| `nodes` | `List<NodeItem>` | 活动节点列表 | -| `hotels` | `List<HotelItem>` | 住宿列表 | -| `routePoints` | `List<RoutePointItem>` | 途经路线点列表 | -| `nodeId` | `Long` | 节点ID(已有则传，新增不传) | -| `sortOrder` | `Integer` | 排序 | -| `nodeType` | `String` | 节点类型(SCENIC/ACTIVITY/RESTAURANT/SERVICE/CUSTOM等) | -| `nodeName` | `String` | 节点名称 | -| `resourceType` | `String` | 资源类型 | -| `resourceId` | `Long` | 资源ID | -| `startTime` | `String` | 开始时间(如10:00) | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `images` | `List<String>` | 图片列表 | -| `emojiIcon` | `String` | 图标 | -| `extraData` | `Object` | 扩展数据 | -| `id` | `Long` | 住宿ID(已有则传，新增不传) | -| `tierSeq` | `Integer` | 档位序号(无档位=1) | -| `hotelId` | `Long` | 酒店ID | -| `roomTypeId` | `Long` | 房型ID(私人定制用) | -| `roomCount` | `Integer` | 房间数(私人定制用) | -| `isDefault` | `Boolean` | 是否默认推荐 | -| `sortOrder` | `Integer` | 排序 | -| `resourceId` | `Long` | 资源ID(可空=自定义地点) | -| `name` | `String` | 地点名称 | -| `longitude` | `BigDecimal` | 经度 | -| `latitude` | `BigDecimal` | 纬度 | -| `sortOrder` | `Integer` | 排序 | - -#### 🆕 ProductLineDropdownVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | - -#### 🆕 ProductLinePageReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `keyword` | `String` | 关键词 | -| `status` | `String` | 状态(ACTIVE/INACTIVE) | - -#### 🆕 ProductLineRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `Object` | 适用季节 | -| `tags` | `Object` | 产品线标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态 | -| `createBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -#### 🆕 ProductLineSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID(修改时传) | -| `name` | `String` | 名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `List<String>` | 适用季节 | -| `tags` | `List<String>` | 标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态(ACTIVE/INACTIVE) | - -#### 🆕 ProductListRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productNo` | `String` | 产品编号 | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `coverImageUrl` | `String` | 封面图 | -| `tripDays` | `Integer` | 行程天数 | -| `status` | `String` | 产品状态 | -| `version` | `Integer` | 版本号 | -| `createBy` | `Long` | 创建人ID | -| `publishedAt` | `LocalDateTime` | 上架时间 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -#### 🆕 ProductOperationLogRespVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | 记录ID | -| `action` | `String` | 操作类型 | -| `detail` | `String` | 详情/驳回原因 | -| `step` | `String` | 步骤号 | -| `operatorId` | `Long` | 操作人ID | -| `operatorName` | `String` | 操作人名称 | -| `createTime` | `LocalDateTime` | 操作时间 | - -#### 🆕 ProductPageReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `keyword` | `String` | 关键词(名称/编号) | -| `productType` | `String` | 产品类型(CORE/GROUP/CUSTOM) | -| `lineId` | `Long` | 产品线ID | -| `status` | `String` | 产品状态 | - -#### 🆕 ProductRouteSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 乐观锁版本号 | -| `routeName` | `String` | 路线名称 | -| `routeMapUrl` | `String` | 路线图URL(手动上传) | -| `totalMileage` | `BigDecimal` | 总里程(km) | -| `routeDescription` | `String` | 线路描述 | -| `vehicleModelId` | `Long` | 实际用车车型ID | -| `staffCostIds` | `List<Long>` | 服务人员成本ID列表 | -| `supplies` | `List<SuppliesItem>` | 备品列表 | -| `extraCosts` | `List<FeeItem>` | 额外成本项列表 | -| `id` | `Long` | 备品ID(已有则传，新增不传) | -| `suppliesResourceId` | `Long` | 备品资源ID(可空=自定义) | -| `suppliesName` | `String` | 备品名称 | -| `category` | `String` | 分类 | -| `hasCost` | `Boolean` | 是否涉及成本 | -| `billingType` | `String` | 计费方式(PER_PERSON/PER_QUANTITY) | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `sortOrder` | `Integer` | 排序 | -| `id` | `Long` | 费用项ID(已有则传，新增不传) | -| `resourceType` | `String` | 资源类型 | -| `resourceId` | `Long` | 资源ID | -| `costItemId` | `Long` | 费用项ID | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `daily` | `Boolean` | 是否按天计费 | -| `sortOrder` | `Integer` | 排序 | - -#### 🆕 ProductSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 产品名称（≤30字） | -| `productType` | `String` | 产品类型（字典product_type: CORE=核心产品, GROUP=小蒙马跟团游, CUSTOM=私人定制） | -| `lineId` | `Long` | 产品线ID（从 /admin/product/line/simple-list 下拉获取，私人定制可空） | -| `tripDays` | `Integer` | 行程天数（可选，创建后可在Step1修改） | - -#### 🆕 ProductSupplementSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `version` | `Integer` | 乐观锁版本号 | -| `includedFees` | `List<FeeItem>` | 费用包含列表 | -| `excludedFees` | `List<FeeItem>` | 费用不含列表 | -| `customFees` | `List<FeeItem>` | 自定义费用列表 | -| `feeIgnoredTypes` | `List<String>` | 费用推导已忽略类型 | -| `childTicket` | `String` | 儿童门票优惠(FREE/HALF_PRICE/FULL_PRICE) | -| `childAccommodation` | `String` | 儿童住宿(BED/NO_BED) | -| `childMeal` | `String` | 儿童餐饮(FULL/HALF) | -| `elderTicket` | `String` | 老人门票优惠 | -| `elderAccommodation` | `String` | 老人住宿 | -| `crowdBenefitTips` | `String` | 人群优惠温馨提示 | -| `vehicleModelIds` | `List<Long>` | 展示车型ID列表 | -| `vehicleRuleText` | `String` | 用车规则说明 | -| `refundPolicyIds` | `Object` | 退改政策映射 | -| `bookingTermsId` | `Long` | 预订条款ID | -| `warmTipsId` | `Long` | 温馨提示ID | -| `equipmentAdvice` | `String` | 装备建议(富文本) | -| `insuranceNotice` | `String` | 保险告知(INCLUDED/EXCLUDED/OPTIONAL) | -| `insuranceSchemeId` | `Long` | 保险方案ID | -| `contractSchemeId` | `Long` | 合同方案ID | -| `quickUnderstand` | `Object` | 快速理解 | -| `childExperience` | `Object` | 孩子经历 | -| `growthGains` | `List<Object>` | 成长收获 | -| `id` | `Long` | 费用项ID(已有则传) | -| `feeType` | `String` | 费用类型 | -| `source` | `String` | 来源(AUTO/MANUAL) | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | -| `unitPrice` | `BigDecimal` | 单价(自定义费用) | -| `unit` | `String` | 单位(自定义费用) | -| `sortOrder` | `Integer` | 排序 | - -#### 🆕 ProductTransferReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `newCreatorId` | `Long` | 新创建人ID | - -#### 🆕 QuoteReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `departureDate` | `LocalDate` | 出发日期 | -| `adultCount` | `Integer` | 成人数 | -| `batchId` | `Long` | 班期ID(小蒙马用) | - -#### 🆕 QuoteResultVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `totalAdultPrice` | `BigDecimal` | 成人总价 | -| `totalChildPrice` | `BigDecimal` | 儿童总价 | -| `grandTotal` | `BigDecimal` | 总价合计 | -| `dailyDetails` | `List<DailyDetail>` | 每日价格明细 | -| `date` | `String` | 日期 | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | - -#### 🆕 SafetyTemplateVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `items` | `String` | 具体条目（JSON） | - -#### 🆕 ScheduleBatchCreateReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `repeatMode` | `String` | 重复模式(WEEKLY/BIWEEKLY/MONTHLY) | -| `dayOfWeek` | `Integer` | 星期几(1=周一...7=周日) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数 | - -#### 🆕 ScheduleOperateReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID | - -#### 🆕 ScheduleSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID(修改时传) | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `enrollmentDeadline` | `LocalDate` | 报名截止日(默认出发前1天) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数(0=不限) | -| `productStockLimit` | `Integer` | 产品库存上限 | -| `remark` | `String` | 备注 | - -#### 🆕 ScheduleTeamQueryReqVO - -#### 🆕 ScheduleTeamSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `staffList` | `List<StaffItem>` | 团队成员列表 | -| `staffId` | `Long` | 员工ID | -| `staffRole` | `String` | 员工角色 | -| `staffName` | `String` | 员工名称 | -| `staffPhone` | `String` | 员工电话 | -| `remark` | `String` | 备注 | -| `sortOrder` | `Integer` | 排序 | - -#### 🆕 WarmTipsVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 提示ID | -| `tipsName` | `String` | 提示名称 | - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/BookingTermsVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/FeeDeductionPreviewVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ItineraryDayDeleteReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/OperationLogReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarBatchReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarQueryReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductActionReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductItinerarySaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineDropdownVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLinePageReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductListRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductOperationLogRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductPageReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductRouteSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductSupplementSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductTransferReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/QuoteReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/QuoteResultVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/SafetyTemplateVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleBatchCreateReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleOperateReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleTeamQueryReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleTeamSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/WarmTipsVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpPriceCalendarReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpPriceCalendarRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductDetailRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductLineQueryReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductListRespVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-12_1539_6ea199f7_test_product-v2_35.md b/changelogs/2026-04/2026-04-12_1539_6ea199f7_test_product-v2_35.md deleted file mode 100644 index c2394f4..0000000 --- a/changelogs/2026-04/2026-04-12_1539_6ea199f7_test_product-v2_35.md +++ /dev/null @@ -1,72 +0,0 @@ -# 接口变更记录 — 2026-04-12 15:39 - -> **提交** `6ea199f7` · **作者** wx · **时间** 2026-04-12 15:39:04 +0800 -> -> test(product-v2): 357个单元测试（覆盖率99.3%，源码行级100%） - -## 变更总览 - -- **hl-product-service-v2** - - 🆕 AdminProductTest (+0 接口) - - 🆕 AdminProductLineTest (+0 接口) - - 🆕 AdminProductTemplateTest (+0 接口) - - 🆕 MpProductTest (+0 接口) - - 🆕 MpProductLineTest (+0 接口) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### 🆕 VoCoverageTest - -#### 🆕 VoCoverageTest2 - -#### 🆕 VoCoverageTest3 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service-v2/src/test/java/com/hulalv/product/ProductServiceV2ApplicationTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/config/MyBatisPlusConfigTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductLineControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductTemplateControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/controller/mp/MpProductControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/controller/mp/MpProductLineControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest2.java -A hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest3.java -A hl-product-service-v2/src/test/java/com/hulalv/product/enums/EnumCoverageTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/enums/ProductStatusEnumTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/enums/ProductTypeEnumTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/interceptor/AdminAuthInterceptorTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/DataServiceCoverageTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/GroupBatchStaffServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductCopyServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductDeleteServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductHelperServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductItineraryServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductLineServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductOperationLogServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductPricingServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductQueryServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductRouteServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductStatusServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductSupplementServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductTemplateServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductValidationServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/service/mp/MpProductServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/util/AdminContextUtilTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/util/EntityDiffUtilTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/util/ProductNoGeneratorTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/vo/VoCoverageTest3.java -A hl-product-service-v2/src/test/java/com/hulalv/product/vo/admin/VoCoverageTest.java -A hl-product-service-v2/src/test/java/com/hulalv/product/vo/admin/VoCoverageTest2.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_0936_3461e082_fix_product-v2.md b/changelogs/2026-04/2026-04-13_0936_3461e082_fix_product-v2.md deleted file mode 100644 index b00e65b..0000000 --- a/changelogs/2026-04/2026-04-13_0936_3461e082_fix_product-v2.md +++ /dev/null @@ -1,26 +0,0 @@ -# 接口变更记录 — 2026-04-13 09:36 - -> **提交** `3461e082` · **作者** wx · **时间** 2026-04-13 09:36:44 +0800 -> -> fix(product-v2): 产品列表返回档位数量 + 分页拦截器改用全局starter - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductListRespVO - - - 🆕 `tierCount` (`Integer`) — 档位数量（单一=1，多档=N） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-common/hl-common-core/src/main/java/com/hulalv/common/util/JsonFieldUtil.java -M hl-product-service-v2/src/main/java/com/hulalv/product/config/MyBatisPlusConfig.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductQueryService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductListRespVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_0949_d90dfe18_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_0949_d90dfe18_refactor_product-v2.md deleted file mode 100644 index 212fb31..0000000 --- a/changelogs/2026-04/2026-04-13_0949_d90dfe18_refactor_product-v2.md +++ /dev/null @@ -1,91 +0,0 @@ -# 接口变更记录 — 2026-04-13 09:49 - -> **提交** `d90dfe18` · **作者** wx · **时间** 2026-04-13 09:49:25 +0800 -> -> refactor(product-v2): 合并创建产品和Step1基础信息为一个接口 - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (+1, -2) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### 🆕 `POST` /admin/product/item/basic — Step1 基础信息保存 - -> 创建+更新合一接口。 - -**请求体** `ProductBasicSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID（不传=创建新产品，传了=更新已有产品） | -| `version` | `Integer` | 乐观锁版本号（更新时必传，创建时不传） | -| `productType` | `String` | 产品类型（创建时必传，更新时忽略。字典product_type: CORE=核心产品, GROUP=小蒙马跟团游, CUSTOM=私人定制） | -| `name` | `String` | 产品名称（≤30字） | -| `subtitle` | `String` | 副标题（一句话卖点，≤128字） | -| `introduction` | `String` | 产品简介（富文本HTML） | -| `lineId` | `Long` | 产品线ID（从产品线下拉接口获取，私人定制可空） | -| `tripDays` | `Integer` | 行程天数（≥1，晚数自动=天数-1） | -| `tripNights` | `Integer` | 行程晚数（通常=天数-1，不传自动计算） | -| `tiers` | `List<TierItem>` | 档位列表（JSON数组，如标准/舒适/豪华3档） | -| `seasons` | `List<String>` | 适用季节（字典product_season: spring=春, summer=夏, autumn=秋, winter=冬） | -| `tags` | `List<String>` | 产品标签（字典product_tag，多选） | -| `coverImageUrl` | `String` | 封面图URL | -| `carouselImages` | `List<String>` | 轮播图URL列表（≤10张） | -| `infantAgeMax` | `Integer` | 幼童年龄上限（默认1岁，幼童≤此值免费或特价） | -| `toddlerAgeMax` | `Integer` | 小童年龄上限（默认3岁，幼童<小童<儿童） | -| `childAgeMin` | `Integer` | 儿童年龄下限（默认4岁） | -| `childAgeMax` | `Integer` | 儿童年龄上限（默认12岁，超过按成人算） | -| `infantDefaultPrice` | `BigDecimal` | 幼童默认价（元，0=免费） | -| `isBooking` | `Boolean` | 是否预约产品（true=订金可不填出行人，false=正常下单） | -| `paymentType` | `String` | 支付方式（字典payment_type: FULL=全款支付, DEPOSIT=订金+尾款） | -| `depositRatio` | `Integer` | 订金比例（%，支付方式=DEPOSIT时使用，与固定额二选一） | -| `depositAmount` | `BigDecimal` | 订金固定额（元，支付方式=DEPOSIT时使用，与比例二选一） | -| `balanceDueDays` | `Integer` | 尾款支付期限（天，出发前N天需付清尾款） | -| `defaultDailyStock` | `Integer` | 每日库存默认值（NULL=不限量，用于价格日历预填） | -| `defaultRoomCount` | `Integer` | 默认房间数（小蒙马跟团游用，每个班期的初始房间数） | -| `minGroupSize` | `Integer` | 最低成团人数（0=不限，小蒙马用） | -| `minAdultPerOrder` | `Integer` | 每单最少成人数 | -| `maxAdultPerOrder` | `Integer` | 每单最多成人数 | -| `maxChildPerOrder` | `Integer` | 每单最多儿童数 | -| `showReview` | `Boolean` | 展示用户评价（true=产品详情页显示评价模块） | -| `showChatGroup` | `Boolean` | 展示群聊入口（true=显示加入群聊按钮） | -| `showTripTime` | `Boolean` | 展示行程时间（true=行程天显示起止时间） | -| `showTripDistance` | `Boolean` | 展示行程距离（true=行程天显示里程数） | -| `creatorAvatarUrl` | `String` | 创建者头像URL（产品详情页展示的领队/设计师头像） | -| `creatorIntro` | `String` | 创建者简介（≤512字） | -| `customizerId` | `Long` | 定制师ID（私人定制产品关联的定制师） | -| `customerName` | `String` | 客户姓名（私人定制的客户） | -| `contactPhone` | `String` | 联系电话（加密存储） | -| `departureDate` | `LocalDate` | 出发日期（私人定制的固定出发日期，格式yyyy-MM-dd） | -| `mchId` | `String` | 商户ID（微信支付商户号，多商户时指定） | -| `safetyItems` | `List<Object>` | 安全保障项（JSON数组 [{icon,title,description}]） | -| `photographyItems` | `List<Object>` | 摄影跟拍项（JSON数组 [{name,description}]） | -| `diningHighlights` | `List<Object>` | 餐饮亮点（JSON数组 [{name,description}]） | -| `tierSeq` | `Integer` | 档位序号（1=标准,2=舒适,3=豪华） | -| `tierName` | `String` | 档位名称 | - -**响应** `Result<Long>` - -### ❌ ~~`POST` /admin/product/item — 创建产品~~ - -### ❌ ~~`PUT` /admin/product/item/{id}/basic — Step1 基础信息保存~~ - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductController.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductControllerTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1019_ad71ea10_fix_product-v2.md b/changelogs/2026-04/2026-04-13_1019_ad71ea10_fix_product-v2.md deleted file mode 100644 index 2c460f0..0000000 --- a/changelogs/2026-04/2026-04-13_1019_ad71ea10_fix_product-v2.md +++ /dev/null @@ -1,82 +0,0 @@ -# 接口变更记录 — 2026-04-13 10:19 - -> **提交** `ad71ea10` · **作者** wx · **时间** 2026-04-13 10:19:02 +0800 -> -> fix(product-v2): 产品列表字段补全+create_by→created_by统一 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ MpProductListRespVO - - - 🆕 `tripNights` (`Integer`) — 行程晚数 - - 🆕 `lineName` (`String`) — 产品线名称（前端叫「主题名」） - - 🆕 `tags` (`List<String>`) — 产品标签(如[\ - - 🆕 `seasons` (`List<String>`) — 产品季节(如[\ - - 🆕 `startPrice` (`BigDecimal`) — 起步价(¥X起，最低成人售价) - - 🆕 `startPriceLabel` (`String`) — 起步价展示文案(如\ - - 🆕 `paymentType` (`String`) — 支付方式(FULL=全款, DEPOSIT=订金) - - 🆕 `tierCount` (`Integer`) — 规格数量（前端叫「规格数」，单一=1，多档=N） - - 🆕 `sortOrder` (`Integer`) — 排序号 - - ✏️ `productType`: 说明 "产品类型" → "产品类型(CORE/GROUP/CUSTOM)" - - ✏️ `subtitle`: 说明 "副标题" → "副标题（一句话卖点）" - - ✏️ `coverImageUrl`: 说明 "封面图" → "封面图URL" - -#### ✏️ ProductDetailRespVO - - - 🆕 `createdBy` (`Long`) — 创建人ID - - ❌ ~~`createBy`~~ (`Long`) — 创建人ID - -#### ✏️ ProductLineRespVO - - - 🆕 `createdBy` (`Long`) — 创建人ID - - ❌ ~~`createBy`~~ (`Long`) — 创建人ID - -#### ✏️ ProductListRespVO - - - 🆕 `subtitle` (`String`) — 副标题 - - 🆕 `tripNights` (`Integer`) — 行程晚数 - - 🆕 `lineId` (`Long`) — 产品线ID（前端叫「主题」） - - 🆕 `lineName` (`String`) — 产品线名称（前端叫「主题名」，从产品线表关联查出） - - 🆕 `seasons` (`List<String>`) — 产品季节(JSON数组，如[\ - - 🆕 `tags` (`List<String>`) — 产品标签(JSON数组，如[\ - - 🆕 `startPrice` (`BigDecimal`) — 起步价(已上架产品的最低成人售价，草稿为null) - - 🆕 `sortOrder` (`Integer`) — 排序号 - - 🆕 `createdBy` (`Long`) — 创建人ID - - 🆕 `createdByName` (`String`) — 创建人名称 - - ❌ ~~`createBy`~~ (`Long`) — 创建人ID - - ✏️ `productNo`: 说明 "产品编号" → "产品编号(如C260409001)" - - ✏️ `productType`: 说明 "产品类型" → "产品类型(字典product_type: CORE=核心产品, GROUP=小蒙马, CUSTOM=私人定制)" - - ✏️ `coverImageUrl`: 说明 "封面图" → "封面图URL" - - ✏️ `status`: 说明 "产品状态" → "产品状态(字典product_status)" - - ✏️ `tierCount`: 说明 "档位数量（单一=1，多档=N）" → "档位数量（前端叫「规格数」，单一=1，多档=N，未配置=0）" - - ✏️ `version`: 说明 "版本号" → "版本号(乐观锁)" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/GroupTourBatchDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductLineDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductPricingService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductQueryService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductValidationService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/mp/MpProductService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductListRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductListRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -M hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest2.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductPricingServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductValidationServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/vo/VoCoverageTest3.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1055_17b97d4d_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1055_17b97d4d_refactor_product-v2.md deleted file mode 100644 index f48e57f..0000000 --- a/changelogs/2026-04/2026-04-13_1055_17b97d4d_refactor_product-v2.md +++ /dev/null @@ -1,80 +0,0 @@ -# 接口变更记录 — 2026-04-13 10:55 - -> **提交** `17b97d4d` · **作者** wx · **时间** 2026-04-13 10:55:21 +0800 -> -> refactor(product-v2): 清理原型中不存在的旧字段 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ MpProductDetailRespVO - - - ❌ ~~`creatorAvatarUrl`~~ (`String`) — 创建者头像 - - ❌ ~~`creatorIntro`~~ (`String`) — 创建者简介 - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`minGroupSize`~~ (`Integer`) — 最低成团人数（0=不限，小蒙马用） - - ❌ ~~`minAdultPerOrder`~~ (`Integer`) — 每单最少成人数 - - ❌ ~~`maxAdultPerOrder`~~ (`Integer`) — 每单最多成人数 - - ❌ ~~`maxChildPerOrder`~~ (`Integer`) — 每单最多儿童数 - - ❌ ~~`showChatGroup`~~ (`Boolean`) — 展示群聊入口（true=显示加入群聊按钮） - - ❌ ~~`showTripTime`~~ (`Boolean`) — 展示行程时间（true=行程天显示起止时间） - - ❌ ~~`showTripDistance`~~ (`Boolean`) — 展示行程距离（true=行程天显示里程数） - - ❌ ~~`creatorAvatarUrl`~~ (`String`) — 创建者头像URL（产品详情页展示的领队/设计师头像） - - ❌ ~~`creatorIntro`~~ (`String`) — 创建者简介（≤512字） - - ❌ ~~`customizerId`~~ (`Long`) — 定制师ID（私人定制产品关联的定制师） - - ❌ ~~`customerName`~~ (`String`) — 客户姓名（私人定制的客户） - - ❌ ~~`contactPhone`~~ (`String`) — 联系电话（加密存储） - - ❌ ~~`departureDate`~~ (`LocalDate`) — 出发日期（私人定制的固定出发日期，格式yyyy-MM-dd） - - ❌ ~~`mchId`~~ (`String`) — 商户ID（微信支付商户号，多商户时指定） - - ❌ ~~`safetyItems`~~ (`List<Object>`) — 安全保障项（JSON数组 [{icon,title,description}]） - - ❌ ~~`photographyItems`~~ (`List<Object>`) — 摄影跟拍项（JSON数组 [{name,description}]） - - ❌ ~~`diningHighlights`~~ (`List<Object>`) — 餐饮亮点（JSON数组 [{name,description}]） - - ✏️ `productId`: 说明 "产品ID（不传=创建新产品，传了=更新已有产品）" → "产品ID（不传=创建，传了=更新）" - - ✏️ `productType`: 说明 "产品类型（创建时必传，更新时忽略。字典product_type: CORE=核心产品, GROUP=小蒙马跟团游, CUSTOM=私人定制）" → "产品类型（创建时必传，更新时忽略。CORE=核心产品, GROUP=小蒙马, CUSTOM=私人定制）" - - ✏️ `subtitle`: 说明 "副标题（一句话卖点，≤128字）" → "副标题（≤128字）" - - ✏️ `lineId`: 说明 "产品线ID（从产品线下拉接口获取，私人定制可空）" → "产品线ID（主题ID，CORE/GROUP必传，CUSTOM可空）" - - ✏️ `tripDays`: 说明 "行程天数（≥1，晚数自动=天数-1）" → "行程天数（≥1）" - - ✏️ `tripNights`: 说明 "行程晚数（通常=天数-1，不传自动计算）" → "行程晚数（不传自动=天数-1）" - - ✏️ `tiers`: 说明 "档位列表（JSON数组，如标准/舒适/豪华3档）" → "规格列表（单一档不传或传1个，多档传多个）" - - ✏️ `seasons`: 说明 "适用季节（字典product_season: spring=春, summer=夏, autumn=秋, winter=冬）" → "适用季节（spring/summer/autumn/winter）" - - ✏️ `tags`: 说明 "产品标签（字典product_tag，多选）" → "产品标签（亲子/研学/露营/城记/摄影）" - - ✏️ `infantAgeMax`: 说明 "幼童年龄上限（默认1岁，幼童≤此值免费或特价）" → "幼童年龄上限（默认1岁）" - - ✏️ `toddlerAgeMax`: 说明 "小童年龄上限（默认3岁，幼童<小童<儿童）" → "小童年龄上限（默认3岁）" - - ✏️ `childAgeMax`: 说明 "儿童年龄上限（默认12岁，超过按成人算）" → "儿童年龄上限（默认12岁）" - - ✏️ `isBooking`: 说明 "是否预约产品（true=订金可不填出行人，false=正常下单）" → "是否预约产品（true=订金可不填出行人）" - - ✏️ `paymentType`: 说明 "支付方式（字典payment_type: FULL=全款支付, DEPOSIT=订金+尾款）" → "支付方式（FULL=全款, DEPOSIT=订金+尾款）" - - ✏️ `depositRatio`: 说明 "订金比例（%，支付方式=DEPOSIT时使用，与固定额二选一）" → "订金比例%（DEPOSIT时用，与固定额二选一）" - - ✏️ `depositAmount`: 说明 "订金固定额（元，支付方式=DEPOSIT时使用，与比例二选一）" → "订金固定额（DEPOSIT时用，与比例二选一）" - - ✏️ `balanceDueDays`: 说明 "尾款支付期限（天，出发前N天需付清尾款）" → "尾款期限（出发前N天付清）" - - ✏️ `defaultDailyStock`: 说明 "每日库存默认值（NULL=不限量，用于价格日历预填）" → "每日库存默认值（NULL=不限量）" - - ✏️ `defaultRoomCount`: 说明 "默认房间数（小蒙马跟团游用，每个班期的初始房间数）" → "默认房间数（小蒙马用）" - - ✏️ `showReview`: 说明 "展示用户评价（true=产品详情页显示评价模块）" → "C端展示评价模块" - - ✏️ `tierSeq`: 说明 "档位序号（1=标准,2=舒适,3=豪华）" → "规格序号（1开始递增）" - - ✏️ `tierName`: 说明 "档位名称" → "规格名称" - -#### ✏️ ProductDetailRespVO - - - ❌ ~~`creatorAvatarUrl`~~ (`String`) — 创建者头像 - - ❌ ~~`creatorIntro`~~ (`String`) — 创建者简介 - - ❌ ~~`customizerId`~~ (`Long`) — 定制师ID - - ❌ ~~`customerName`~~ (`String`) — 客户姓名 - - ❌ ~~`departureDate`~~ (`LocalDate`) — 出发日期(定制) - - ❌ ~~`mchId`~~ (`String`) — 商户ID - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductBasicDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductDetailRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1055_f3d4fd83_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1055_f3d4fd83_refactor_product-v2.md deleted file mode 100644 index 328d904..0000000 --- a/changelogs/2026-04/2026-04-13_1055_f3d4fd83_refactor_product-v2.md +++ /dev/null @@ -1,80 +0,0 @@ -# 接口变更记录 — 2026-04-13 10:55 - -> **提交** `f3d4fd83` · **作者** wx · **时间** 2026-04-13 10:55:21 +0800 -> -> refactor(product-v2): 清理原型中不存在的旧字段 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ MpProductDetailRespVO - - - ❌ ~~`creatorAvatarUrl`~~ (`String`) — 创建者头像 - - ❌ ~~`creatorIntro`~~ (`String`) — 创建者简介 - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`minGroupSize`~~ (`Integer`) — 最低成团人数（0=不限，小蒙马用） - - ❌ ~~`minAdultPerOrder`~~ (`Integer`) — 每单最少成人数 - - ❌ ~~`maxAdultPerOrder`~~ (`Integer`) — 每单最多成人数 - - ❌ ~~`maxChildPerOrder`~~ (`Integer`) — 每单最多儿童数 - - ❌ ~~`showChatGroup`~~ (`Boolean`) — 展示群聊入口（true=显示加入群聊按钮） - - ❌ ~~`showTripTime`~~ (`Boolean`) — 展示行程时间（true=行程天显示起止时间） - - ❌ ~~`showTripDistance`~~ (`Boolean`) — 展示行程距离（true=行程天显示里程数） - - ❌ ~~`creatorAvatarUrl`~~ (`String`) — 创建者头像URL（产品详情页展示的领队/设计师头像） - - ❌ ~~`creatorIntro`~~ (`String`) — 创建者简介（≤512字） - - ❌ ~~`customizerId`~~ (`Long`) — 定制师ID（私人定制产品关联的定制师） - - ❌ ~~`customerName`~~ (`String`) — 客户姓名（私人定制的客户） - - ❌ ~~`contactPhone`~~ (`String`) — 联系电话（加密存储） - - ❌ ~~`departureDate`~~ (`LocalDate`) — 出发日期（私人定制的固定出发日期，格式yyyy-MM-dd） - - ❌ ~~`mchId`~~ (`String`) — 商户ID（微信支付商户号，多商户时指定） - - ❌ ~~`safetyItems`~~ (`List<Object>`) — 安全保障项（JSON数组 [{icon,title,description}]） - - ❌ ~~`photographyItems`~~ (`List<Object>`) — 摄影跟拍项（JSON数组 [{name,description}]） - - ❌ ~~`diningHighlights`~~ (`List<Object>`) — 餐饮亮点（JSON数组 [{name,description}]） - - ✏️ `productId`: 说明 "产品ID（不传=创建新产品，传了=更新已有产品）" → "产品ID（不传=创建，传了=更新）" - - ✏️ `productType`: 说明 "产品类型（创建时必传，更新时忽略。字典product_type: CORE=核心产品, GROUP=小蒙马跟团游, CUSTOM=私人定制）" → "产品类型（创建时必传，更新时忽略。CORE=核心产品, GROUP=小蒙马, CUSTOM=私人定制）" - - ✏️ `subtitle`: 说明 "副标题（一句话卖点，≤128字）" → "副标题（≤128字）" - - ✏️ `lineId`: 说明 "产品线ID（从产品线下拉接口获取，私人定制可空）" → "产品线ID（主题ID，CORE/GROUP必传，CUSTOM可空）" - - ✏️ `tripDays`: 说明 "行程天数（≥1，晚数自动=天数-1）" → "行程天数（≥1）" - - ✏️ `tripNights`: 说明 "行程晚数（通常=天数-1，不传自动计算）" → "行程晚数（不传自动=天数-1）" - - ✏️ `tiers`: 说明 "档位列表（JSON数组，如标准/舒适/豪华3档）" → "规格列表（单一档不传或传1个，多档传多个）" - - ✏️ `seasons`: 说明 "适用季节（字典product_season: spring=春, summer=夏, autumn=秋, winter=冬）" → "适用季节（spring/summer/autumn/winter）" - - ✏️ `tags`: 说明 "产品标签（字典product_tag，多选）" → "产品标签（亲子/研学/露营/城记/摄影）" - - ✏️ `infantAgeMax`: 说明 "幼童年龄上限（默认1岁，幼童≤此值免费或特价）" → "幼童年龄上限（默认1岁）" - - ✏️ `toddlerAgeMax`: 说明 "小童年龄上限（默认3岁，幼童<小童<儿童）" → "小童年龄上限（默认3岁）" - - ✏️ `childAgeMax`: 说明 "儿童年龄上限（默认12岁，超过按成人算）" → "儿童年龄上限（默认12岁）" - - ✏️ `isBooking`: 说明 "是否预约产品（true=订金可不填出行人，false=正常下单）" → "是否预约产品（true=订金可不填出行人）" - - ✏️ `paymentType`: 说明 "支付方式（字典payment_type: FULL=全款支付, DEPOSIT=订金+尾款）" → "支付方式（FULL=全款, DEPOSIT=订金+尾款）" - - ✏️ `depositRatio`: 说明 "订金比例（%，支付方式=DEPOSIT时使用，与固定额二选一）" → "订金比例%（DEPOSIT时用，与固定额二选一）" - - ✏️ `depositAmount`: 说明 "订金固定额（元，支付方式=DEPOSIT时使用，与比例二选一）" → "订金固定额（DEPOSIT时用，与比例二选一）" - - ✏️ `balanceDueDays`: 说明 "尾款支付期限（天，出发前N天需付清尾款）" → "尾款期限（出发前N天付清）" - - ✏️ `defaultDailyStock`: 说明 "每日库存默认值（NULL=不限量，用于价格日历预填）" → "每日库存默认值（NULL=不限量）" - - ✏️ `defaultRoomCount`: 说明 "默认房间数（小蒙马跟团游用，每个班期的初始房间数）" → "默认房间数（小蒙马用）" - - ✏️ `showReview`: 说明 "展示用户评价（true=产品详情页显示评价模块）" → "C端展示评价模块" - - ✏️ `tierSeq`: 说明 "档位序号（1=标准,2=舒适,3=豪华）" → "规格序号（1开始递增）" - - ✏️ `tierName`: 说明 "档位名称" → "规格名称" - -#### ✏️ ProductDetailRespVO - - - ❌ ~~`creatorAvatarUrl`~~ (`String`) — 创建者头像 - - ❌ ~~`creatorIntro`~~ (`String`) — 创建者简介 - - ❌ ~~`customizerId`~~ (`Long`) — 定制师ID - - ❌ ~~`customerName`~~ (`String`) — 客户姓名 - - ❌ ~~`departureDate`~~ (`LocalDate`) — 出发日期(定制) - - ❌ ~~`mchId`~~ (`String`) — 商户ID - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductBasicDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductDetailRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1057_17d69b8d_fix_product-v2.md b/changelogs/2026-04/2026-04-13_1057_17d69b8d_fix_product-v2.md deleted file mode 100644 index d937776..0000000 --- a/changelogs/2026-04/2026-04-13_1057_17d69b8d_fix_product-v2.md +++ /dev/null @@ -1,25 +0,0 @@ -# 接口变更记录 — 2026-04-13 10:57 - -> **提交** `17d69b8d` · **作者** wx · **时间** 2026-04-13 10:57:55 +0800 -> -> fix(product-v2): 删除引用已删字段的过时测试类 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ❌ ~~VoCoverageTest~~ - -#### ❌ ~~VoCoverageTest3~~ - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -D hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/vo/VoCoverageTest3.java -D hl-product-service-v2/src/test/java/com/hulalv/product/vo/admin/VoCoverageTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1107_121ebb02_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1107_121ebb02_refactor_product-v2.md deleted file mode 100644 index 0a1273f..0000000 --- a/changelogs/2026-04/2026-04-13_1107_121ebb02_refactor_product-v2.md +++ /dev/null @@ -1,30 +0,0 @@ -# 接口变更记录 — 2026-04-13 11:07 - -> **提交** `121ebb02` · **作者** wx · **时间** 2026-04-13 11:07:28 +0800 -> -> refactor(product-v2): Step1继续清理——删除年龄设置(4字段)+showReview - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`infantAgeMax`~~ (`Integer`) — 幼童年龄上限（默认1岁） - - ❌ ~~`toddlerAgeMax`~~ (`Integer`) — 小童年龄上限（默认3岁） - - ❌ ~~`childAgeMin`~~ (`Integer`) — 儿童年龄下限（默认4岁） - - ❌ ~~`childAgeMax`~~ (`Integer`) — 儿童年龄上限（默认12岁） - - ❌ ~~`showReview`~~ (`Boolean`) — C端展示评价模块 - - ✏️ `infantDefaultPrice`: 说明 "幼童默认价（元，0=免费）" → "幼童默认价（元，0=免费，创建价格区间/班期时自动预填）" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1107_44deca09_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1107_44deca09_refactor_product-v2.md deleted file mode 100644 index 3880f39..0000000 --- a/changelogs/2026-04/2026-04-13_1107_44deca09_refactor_product-v2.md +++ /dev/null @@ -1,30 +0,0 @@ -# 接口变更记录 — 2026-04-13 11:07 - -> **提交** `44deca09` · **作者** wx · **时间** 2026-04-13 11:07:28 +0800 -> -> refactor(product-v2): Step1继续清理——删除年龄设置(4字段)+showReview - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`infantAgeMax`~~ (`Integer`) — 幼童年龄上限（默认1岁） - - ❌ ~~`toddlerAgeMax`~~ (`Integer`) — 小童年龄上限（默认3岁） - - ❌ ~~`childAgeMin`~~ (`Integer`) — 儿童年龄下限（默认4岁） - - ❌ ~~`childAgeMax`~~ (`Integer`) — 儿童年龄上限（默认12岁） - - ❌ ~~`showReview`~~ (`Boolean`) — C端展示评价模块 - - ✏️ `infantDefaultPrice`: 说明 "幼童默认价（元，0=免费）" → "幼童默认价（元，0=免费，创建价格区间/班期时自动预填）" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1113_17d357ab_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1113_17d357ab_refactor_product-v2.md deleted file mode 100644 index e95b7f4..0000000 --- a/changelogs/2026-04/2026-04-13_1113_17d357ab_refactor_product-v2.md +++ /dev/null @@ -1,25 +0,0 @@ -# 接口变更记录 — 2026-04-13 11:13 - -> **提交** `17d357ab` · **作者** wx · **时间** 2026-04-13 11:13:49 +0800 -> -> refactor(product-v2): Step1字段清理——删除infantDefaultPrice - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`infantDefaultPrice`~~ (`BigDecimal`) — 幼童默认价（元，0=免费，创建价格区间/班期时自动预填） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductBasicDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/main/resources/schema.sql -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1129_08cdeaf6_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1129_08cdeaf6_refactor_product-v2.md deleted file mode 100644 index 3a0e264..0000000 --- a/changelogs/2026-04/2026-04-13_1129_08cdeaf6_refactor_product-v2.md +++ /dev/null @@ -1,27 +0,0 @@ -# 接口变更记录 — 2026-04-13 11:29 - -> **提交** `08cdeaf6` · **作者** wx · **时间** 2026-04-13 11:29:57 +0800 -> -> refactor(product-v2): Step1清理defaultRoomCount+修复测试 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`defaultRoomCount`~~ (`Integer`) — 默认房间数（小蒙马用） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductBasicDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/main/resources/schema.sql -M hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest2.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/mp/MpProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1453_e65aa035_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1453_e65aa035_refactor_product-v2.md deleted file mode 100644 index e24d9ce..0000000 --- a/changelogs/2026-04/2026-04-13_1453_e65aa035_refactor_product-v2.md +++ /dev/null @@ -1,25 +0,0 @@ -# 接口变更记录 — 2026-04-13 14:53 - -> **提交** `e65aa035` · **作者** wx · **时间** 2026-04-13 14:53:34 +0800 -> -> refactor(product-v2): ProductLineRespVO用TypeHandler替代Service手动转换 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductLineRespVO - - - ✏️ `seasons`: 类型 `Object` → `List<String>` - - ✏️ `tags`: 类型 `Object` → `List<String>` - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductLineService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineRespVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1537_42544063_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1537_42544063_refactor_product-v2.md deleted file mode 100644 index c0f136a..0000000 --- a/changelogs/2026-04/2026-04-13_1537_42544063_refactor_product-v2.md +++ /dev/null @@ -1,80 +0,0 @@ -# 接口变更记录 — 2026-04-13 15:37 - -> **提交** `42544063` · **作者** wx · **时间** 2026-04-13 15:37:43 +0800 -> -> refactor(product-v2): 去掉全部version乐观锁机制 - -## 变更总览 - -- **hl-product-service-v2** - - ❌ AdminProductTest (-0 接口) - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ PriceCalendarBatchReqVO - - - ❌ ~~`version`~~ (`Integer`) — 版本号(草稿用version/已上架用priceVersion) - -#### ✏️ ProductBasicSaveReqVO - - - ❌ ~~`version`~~ (`Integer`) — 乐观锁版本号（更新时必传，创建时不传） - -#### ✏️ ProductDetailRespVO - - - ❌ ~~`version`~~ (`Integer`) — 乐观锁版本号 - - ❌ ~~`priceVersion`~~ (`Integer`) — 调价版本号 - -#### ✏️ ProductItinerarySaveReqVO - - - ❌ ~~`version`~~ (`Integer`) — 乐观锁版本号 - -#### ✏️ ProductListRespVO - - - ❌ ~~`version`~~ (`Integer`) — 版本号(乐观锁) - -#### ✏️ ProductRouteSaveReqVO - - - ❌ ~~`version`~~ (`Integer`) — 乐观锁版本号 - -#### ✏️ ProductSupplementSaveReqVO - - - ❌ ~~`version`~~ (`Integer`) — 乐观锁版本号 - -#### ❌ ~~VoCoverageTest2~~ - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductController.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductItineraryService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductLineService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductPricingService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductRouteService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductSupplementService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarBatchReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductItinerarySaveReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductListRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductRouteSaveReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductSupplementSaveReqVO.java -D hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductControllerTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest2.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductHelperServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductItineraryServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductLineServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductPricingServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductRouteServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductSupplementServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/vo/admin/VoCoverageTest2.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1614_9a455ad2_feat_product-v2_St.md b/changelogs/2026-04/2026-04-13_1614_9a455ad2_feat_product-v2_St.md deleted file mode 100644 index dadac92..0000000 --- a/changelogs/2026-04/2026-04-13_1614_9a455ad2_feat_product-v2_St.md +++ /dev/null @@ -1,46 +0,0 @@ -# 接口变更记录 — 2026-04-13 16:14 - -> **提交** `9a455ad2` · **作者** wx · **时间** 2026-04-13 16:14:57 +0800 -> -> feat(product-v2): Step1字段对齐原型+category+currentStep - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - 🆕 `category` (`String`) — 产品分类（字典product_category: family=亲子游, honeymoon=蜜月旅行, photography=摄影之旅, experience=深度体验, driving=自驾越野） - - ❌ ~~`seasons`~~ (`List<String>`) — 适用季节（spring/summer/autumn/winter） - - ❌ ~~`carouselImages`~~ (`List<String>`) — 轮播图URL列表（≤10张） - - ❌ ~~`isBooking`~~ (`Boolean`) — 是否预约产品（true=订金可不填出行人） - - ❌ ~~`paymentType`~~ (`String`) — 支付方式（FULL=全款, DEPOSIT=订金+尾款） - - ❌ ~~`depositRatio`~~ (`Integer`) — 订金比例%（DEPOSIT时用，与固定额二选一） - - ❌ ~~`depositAmount`~~ (`BigDecimal`) — 订金固定额（DEPOSIT时用，与比例二选一） - - ❌ ~~`balanceDueDays`~~ (`Integer`) — 尾款期限（出发前N天付清） - - ❌ ~~`defaultDailyStock`~~ (`Integer`) — 每日库存默认值（NULL=不限量） - -#### ✏️ ProductDetailRespVO - - - 🆕 `category` (`String`) — 产品分类(字典product_category) - - 🆕 `currentStep` (`Integer`) — 当前步骤进度（1=基础信息, 2=行程编排, 3=路线与备品, 4=定价管理, 5=补充信息） - -#### ✏️ ProductListRespVO - - - 🆕 `category` (`String`) — 产品分类(字典product_category) - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductQueryService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductListRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1623_07b7b5fb_feat_product-v2.md b/changelogs/2026-04/2026-04-13_1623_07b7b5fb_feat_product-v2.md deleted file mode 100644 index 592fada..0000000 --- a/changelogs/2026-04/2026-04-13_1623_07b7b5fb_feat_product-v2.md +++ /dev/null @@ -1,35 +0,0 @@ -# 接口变更记录 — 2026-04-13 16:23 - -> **提交** `07b7b5fb` · **作者** wx · **时间** 2026-04-13 16:23:35 +0800 -> -> feat(product-v2): 搬迁行政区划搜索接口到v2 - -## 变更总览 - -- **hl-product-service-v2** - - 🆕 District (+1 接口) - ---- - -## hl-product-service-v2 - -### 🆕 新增: District - -### 📌 `GET` /admin/product/district/search — 搜索行政区划（城市/区县/镇） - -> 通过高德地图 API 搜索行政区划，用于产品的出发城市和目的地城市选择。 - -**参数** - - - `keywords` (`String`) — 查询参数：搜索关键词 - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/DistrictController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/AmapDistrictService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1639_66339934_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1639_66339934_refactor_product-v2.md deleted file mode 100644 index b7c386a..0000000 --- a/changelogs/2026-04/2026-04-13_1639_66339934_refactor_product-v2.md +++ /dev/null @@ -1,27 +0,0 @@ -# 接口变更记录 — 2026-04-13 16:39 - -> **提交** `66339934` · **作者** wx · **时间** 2026-04-13 16:39:34 +0800 -> -> refactor(product-v2): Step3删除routeName/vehicleModelId/staffCostIds - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductRouteSaveReqVO - - - ❌ ~~`routeName`~~ (`String`) — 路线名称 - - ❌ ~~`vehicleModelId`~~ (`Long`) — 实际用车车型ID - - ❌ ~~`staffCostIds`~~ (`List<Long>`) — 服务人员成本ID列表 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductRouteService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductRouteSaveReqVO.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductRouteServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1811_2850f7a8_fix_product-v2.md b/changelogs/2026-04/2026-04-13_1811_2850f7a8_fix_product-v2.md deleted file mode 100644 index 45a2376..0000000 --- a/changelogs/2026-04/2026-04-13_1811_2850f7a8_fix_product-v2.md +++ /dev/null @@ -1,32 +0,0 @@ -# 接口变更记录 — 2026-04-13 18:11 - -> **提交** `2850f7a8` · **作者** wx · **时间** 2026-04-13 18:11:34 +0800 -> -> fix(product-v2): 行程酒店名快照补全 + Step1支付字段恢复 + 车辆类型常量 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - 🆕 `isBooking` (`Boolean`) — 是否预约产品（true=订金可不填出行人） - - 🆕 `paymentType` (`String`) — 支付方式（FULL=全款支付, DEPOSIT=订金+尾款） - - 🆕 `depositRatio` (`Integer`) — 订金比例(%，与固定额二选一） - - 🆕 `depositAmount` (`BigDecimal`) — 订金固定额（与比例二选一） - - 🆕 `balanceDueDays` (`Integer`) — 尾款须在出发前N天付清 - - 🆕 `defaultDailyStock` (`Integer`) — 每日库存默认值（NULL=不限量，用于价格日历预填） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service-v2/src/main/java/com/hulalv/product/feign/ResourceHotelFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductItineraryService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductItineraryServiceTest.java -M hl-resource-service/src/main/java/com/hulalv/resource/vehicle/constant/VehicleConstants.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1811_f72ea0da_feat_product-v2.md b/changelogs/2026-04/2026-04-13_1811_f72ea0da_feat_product-v2.md deleted file mode 100644 index 37bfddf..0000000 --- a/changelogs/2026-04/2026-04-13_1811_f72ea0da_feat_product-v2.md +++ /dev/null @@ -1,37 +0,0 @@ -# 接口变更记录 — 2026-04-13 18:11 - -> **提交** `f72ea0da` · **作者** wx · **时间** 2026-04-13 18:11:42 +0800 -> -> feat(product-v2): 新增计算行程总里程接口(高德驾车路线API) - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (+1) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### 🆕 `GET` /admin/product/item/{id}/calculate-mileage — 计算行程总里程 - -> 根据行程途经点坐标调用高德驾车路线规划API自动计算总驾驶里程(km)。需先保存行程(Step2)。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<BigDecimal>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/AmapDrivingService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1820_5f52751f_refactor_product-v2.md b/changelogs/2026-04/2026-04-13_1820_5f52751f_refactor_product-v2.md deleted file mode 100644 index f886c12..0000000 --- a/changelogs/2026-04/2026-04-13_1820_5f52751f_refactor_product-v2.md +++ /dev/null @@ -1,61 +0,0 @@ -# 接口变更记录 — 2026-04-13 18:20 - -> **提交** `5f52751f` · **作者** wx · **时间** 2026-04-13 18:20:07 +0800 -> -> refactor(product-v2): 价格日历改为租费+酒店分类定价（4种人群） - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ MpPriceCalendarRespVO - - - 🆕 `toddlerPrice` (`BigDecimal`) — 小童售价(租费+酒店) - - 🆕 `infantPrice` (`BigDecimal`) — 幼童售价(租费+酒店) - - ✏️ `adultPrice`: 说明 "成人售价" → "成人售价(租费+酒店)" - - ✏️ `childPrice`: 说明 "儿童售价" → "儿童售价(租费+酒店)" - -#### ✏️ PriceCalendarBatchReqVO - - - 🆕 `vehicleAdultPrice` (`BigDecimal`) — 租费-成人售价 - - 🆕 `vehicleChildPrice` (`BigDecimal`) — 租费-儿童售价 - - 🆕 `vehicleToddlerPrice` (`BigDecimal`) — 租费-小童售价 - - 🆕 `vehicleInfantPrice` (`BigDecimal`) — 租费-幼童售价 - - 🆕 `hotelAdultPrice` (`BigDecimal`) — 酒店-成人售价 - - 🆕 `hotelChildPrice` (`BigDecimal`) — 酒店-儿童售价 - - 🆕 `hotelToddlerPrice` (`BigDecimal`) — 酒店-小童售价 - - 🆕 `hotelInfantPrice` (`BigDecimal`) — 酒店-幼童售价 - - ❌ ~~`adultSellPrice`~~ (`BigDecimal`) — 成人售价 - - ❌ ~~`childSellPrice`~~ (`BigDecimal`) — 儿童售价 - - ❌ ~~`toddlerDiscount`~~ (`BigDecimal`) — 小童优惠额(负数) - - ❌ ~~`infantPrice`~~ (`BigDecimal`) — 幼童售价(0=免费) - - ✏️ `priceType`: 说明 "价格类型(NORMAL/PEAK/HOLIDAY/SPECIAL)" → "价格类型(字典price_type: NORMAL=平日, PEAK=旺季, HOLIDAY=节假日, SPECIAL=特价)" - -#### ✏️ QuoteResultVO - - - 🆕 `totalToddlerPrice` (`BigDecimal`) — 小童总价 - - 🆕 `totalInfantPrice` (`BigDecimal`) — 幼童总价 - - 🆕 `toddlerPrice` (`BigDecimal`) — 小童日价(租费+酒店) - - 🆕 `infantPrice` (`BigDecimal`) — 幼童日价(租费+酒店) - - ✏️ `adultPrice`: 说明 "成人价" → "成人日价(租费+酒店)" - - ✏️ `childPrice`: 说明 "儿童价" → "儿童日价(租费+酒店)" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductPriceCalendarDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductPricingService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/mp/MpProductService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarBatchReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/QuoteResultVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpPriceCalendarRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -M hl-product-service-v2/src/main/resources/mapper/ProductPriceCalendarMapper.xml -M hl-product-service-v2/src/main/resources/schema.sql -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductPricingServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/mp/MpProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1910_3f25425f_revert_product-v2.md b/changelogs/2026-04/2026-04-13_1910_3f25425f_revert_product-v2.md deleted file mode 100644 index 7554bcb..0000000 --- a/changelogs/2026-04/2026-04-13_1910_3f25425f_revert_product-v2.md +++ /dev/null @@ -1,60 +0,0 @@ -# 接口变更记录 — 2026-04-13 19:10 - -> **提交** `3f25425f` · **作者** wx · **时间** 2026-04-13 19:10:03 +0800 -> -> revert(product-v2): 回滚价格日历字段改名，保持原结构 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ MpPriceCalendarRespVO - - - ❌ ~~`toddlerPrice`~~ (`BigDecimal`) — 小童售价(租费+酒店) - - ❌ ~~`infantPrice`~~ (`BigDecimal`) — 幼童售价(租费+酒店) - - ✏️ `adultPrice`: 说明 "成人售价(租费+酒店)" → "成人售价" - - ✏️ `childPrice`: 说明 "儿童售价(租费+酒店)" → "儿童售价" - -#### ✏️ PriceCalendarBatchReqVO - - - 🆕 `adultSellPrice` (`BigDecimal`) — 成人售价 - - 🆕 `childSellPrice` (`BigDecimal`) — 儿童售价 - - 🆕 `toddlerDiscount` (`BigDecimal`) — 小童优惠额(负数) - - 🆕 `infantPrice` (`BigDecimal`) — 幼童售价(0=免费) - - ❌ ~~`vehicleAdultPrice`~~ (`BigDecimal`) — 租费-成人售价 - - ❌ ~~`vehicleChildPrice`~~ (`BigDecimal`) — 租费-儿童售价 - - ❌ ~~`vehicleToddlerPrice`~~ (`BigDecimal`) — 租费-小童售价 - - ❌ ~~`vehicleInfantPrice`~~ (`BigDecimal`) — 租费-幼童售价 - - ❌ ~~`hotelAdultPrice`~~ (`BigDecimal`) — 酒店-成人售价 - - ❌ ~~`hotelChildPrice`~~ (`BigDecimal`) — 酒店-儿童售价 - - ❌ ~~`hotelToddlerPrice`~~ (`BigDecimal`) — 酒店-小童售价 - - ❌ ~~`hotelInfantPrice`~~ (`BigDecimal`) — 酒店-幼童售价 - -#### ✏️ QuoteResultVO - - - ❌ ~~`totalToddlerPrice`~~ (`BigDecimal`) — 小童总价 - - ❌ ~~`totalInfantPrice`~~ (`BigDecimal`) — 幼童总价 - - ❌ ~~`toddlerPrice`~~ (`BigDecimal`) — 小童日价(租费+酒店) - - ❌ ~~`infantPrice`~~ (`BigDecimal`) — 幼童日价(租费+酒店) - - ✏️ `adultPrice`: 说明 "成人日价(租费+酒店)" → "成人日价" - - ✏️ `childPrice`: 说明 "儿童日价(租费+酒店)" → "儿童日价" - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductPriceCalendarDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductPricingService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/mp/MpProductService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarBatchReqVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/QuoteResultVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpPriceCalendarRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -M hl-product-service-v2/src/main/resources/mapper/ProductPriceCalendarMapper.xml -M hl-product-service-v2/src/main/resources/schema.sql -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductPricingServiceTest.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/mp/MpProductServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1914_89b08620_feat_product-v2.md b/changelogs/2026-04/2026-04-13_1914_89b08620_feat_product-v2.md deleted file mode 100644 index 0400b18..0000000 --- a/changelogs/2026-04/2026-04-13_1914_89b08620_feat_product-v2.md +++ /dev/null @@ -1,736 +0,0 @@ -# 接口变更记录 — 2026-04-13 19:14 - -> **提交** `89b08620` · **作者** wx · **时间** 2026-04-13 19:14:52 +0800 -> -> feat(product-v2): 搬迁报价公式+温馨提示+预订条款到v2 - -## 变更总览 - -- **hl-product-service-v2** - - 🆕 AdminBookingTerms (+7 接口) - - 🆕 AdminWarmTips (+7 接口) - - 🆕 Formula (+19 接口) - ---- - -## hl-product-service-v2 - -### 🆕 新增: AdminBookingTerms - -### 📌 `GET` /admin/product/booking-terms/list — 预订条款列表 - -> 返回所有预订条款（含禁用），按创建时间倒序 - -**响应** `Result<List<BookingTermsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/booking-terms/enabled — 启用的预订条款列表 - -> 仅返回启用状态的条款，供产品设计时选择 - -**响应** `Result<List<BookingTermsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/booking-terms/{termsId} — 预订条款详情 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - -**响应** `Result<BookingTermsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/booking-terms — 创建预订条款 - -> 创建后默认启用 - -**请求体** `BookingTermsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<BookingTermsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/booking-terms/{termsId} — 修改预订条款 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - -**请求体** `BookingTermsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<BookingTermsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/product/booking-terms/{termsId} — 删除预订条款 - -> 软删除，已绑定的产品不受影响 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/booking-terms/{termsId}/toggle — 启用/禁用预订条款 - -> 禁用后不再出现在产品设计的可选列表中 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - - `enabled` (`boolean`) — 查询参数：是否启用 - -**响应** `Result<Void>` - -### 🆕 新增: AdminWarmTips - -### 📌 `GET` /admin/product/warm-tips/list — 温馨提示列表 - -> 返回所有温馨提示（含禁用），按创建时间倒序 - -**响应** `Result<List<WarmTipsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/warm-tips/enabled — 启用的温馨提示列表 - -> 仅返回启用状态的提示，供产品设计时选择 - -**响应** `Result<List<WarmTipsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/warm-tips/{tipsId} — 温馨提示详情 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - -**响应** `Result<WarmTipsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/warm-tips — 创建温馨提示 - -> 创建后默认启用 - -**请求体** `WarmTipsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<WarmTipsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/warm-tips/{tipsId} — 修改温馨提示 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - -**请求体** `WarmTipsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<WarmTipsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/product/warm-tips/{tipsId} — 删除温馨提示 - -> 软删除，已绑定的产品不受影响 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/warm-tips/{tipsId}/toggle — 启用/禁用温馨提示 - -> 禁用后不再出现在产品设计的可选列表中 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - - `enabled` (`boolean`) — 查询参数：是否启用 - -**响应** `Result<Void>` - -### 🆕 新增: Formula - -### 📌 `GET` /admin/product/formula/group/list — 公式组列表 - -> 获取定价公式组列表，可按产品类型筛选。 - -**参数** - - - `productType` (`String`) — 查询参数 - -**响应** `Result<List<FormulaGroupRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `String` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `GET` /admin/product/formula/group/{groupId} — 公式组详情 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<FormulaGroupRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `String` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `POST` /admin/product/formula/group — 创建公式组 - -**请求体** `FormulaGroupSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型(字典product_type: CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品) | -| `description` | `String` | 描述 | - -**响应** `Result<FormulaGroupRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `String` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `PUT` /admin/product/formula/group/{groupId} — 更新公式组 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**请求体** `FormulaGroupSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型(字典product_type: CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品) | -| `description` | `String` | 描述 | - -**响应** `Result<FormulaGroupRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `String` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `PUT` /admin/product/formula/group/{groupId}/activate — 激活公式组 - -> 激活指定公式组，同时自动停用同产品类型下的其他公式组 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/product/formula/group/{groupId} — 删除公式组 - -> 已激活的公式组不能删除，需先激活其他公式组 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/formula/group/{groupId}/steps — 公式步骤列表 - -> 获取公式组下所有步骤，按执行顺序升序排列 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<List<FormulaStepRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `String` | 公式ID | -| `groupId` | `String` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/formula/step/{formulaId} — 公式步骤详情 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `String` | 公式ID | -| `groupId` | `String` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/formula/step — 创建公式步骤 - -**请求体** `FormulaStepSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量） | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `changeNote` | `String` | 变更说明 | - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `String` | 公式ID | -| `groupId` | `String` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/formula/step/{formulaId} — 更新公式步骤 - -> 更新时自动保存版本快照，可通过版本历史接口查看和回滚 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**请求体** `FormulaStepSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量） | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `changeNote` | `String` | 变更说明 | - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `String` | 公式ID | -| `groupId` | `String` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/formula/step/{formulaId}/toggle — 启用/禁用公式步骤 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/product/formula/step/{formulaId} — 删除公式步骤 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/formula/step/{formulaId}/versions — 公式步骤版本历史 - -> 按版本号倒序返回历史版本列表 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<List<FormulaVersionRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `versionId` | `String` | 版本ID | -| `formulaId` | `String` | 公式ID | -| `versionNum` | `Integer` | 版本号 | -| `expression` | `String` | 表达式 | -| `changeNote` | `String` | 变更说明 | -| `changedBy` | `String` | 变更人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/product/formula/step/{formulaId}/rollback/{versionNum} — 回滚公式步骤到指定版本 - -> 回滚前自动备份当前表达式 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - - `{versionNum}` (`Integer`) — 路径参数 - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `String` | 公式ID | -| `groupId` | `String` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/formula/test — 测试公式执行 - -> 使用自定义变量值测试公式组的执行结果，不影响业务数据 - -**请求体** `FormulaTestReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `variables` | `Map<String, Object>` | 测试变量(变量名->值) | - -**响应** `Result<FormulaTestResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `Boolean` | 是否成功 | -| `errorMessage` | `String` | 错误信息 | -| `stepResults` | `List<StepResult>` | 各步骤执行结果 | -| `finalVariables` | `Map<String, Object>` | 最终变量表 | -| `totalTimeMs` | `Long` | 总耗时(毫秒) | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `outputVar` | `String` | 输出变量名 | -| `outputValue` | `Object` | 输出值 | -| `expression` | `String` | 表达式 | -| `executionTimeMs` | `Long` | 执行耗时(毫秒) | -| `success` | `Boolean` | 是否成功 | -| `errorMessage` | `String` | 错误信息 | - -### 📌 `GET` /admin/product/formula/var/list — 公式变量列表 - -> 获取公式变量列表，可按变量分类筛选（INPUT/INTERMEDIATE/OUTPUT） - -**参数** - - - `category` (`String`) — 查询参数 - -**响应** `Result<List<FormulaVarRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varId` | `String` | 变量ID | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -### 📌 `POST` /admin/product/formula/var — 创建公式变量 - -**请求体** `FormulaVarSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -**响应** `Result<FormulaVarRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varId` | `String` | 变量ID | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -### 📌 `PUT` /admin/product/formula/var/{varId} — 更新公式变量 - -**参数** - - - `{varId}` (`Long`) — 路径参数 - -**请求体** `FormulaVarSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -**响应** `Result<FormulaVarRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varId` | `String` | 变量ID | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -### 📌 `DELETE` /admin/product/formula/var/{varId} — 删除公式变量 - -> 如果有公式步骤引用了该变量，删除后步骤执行时会报错 - -**参数** - - - `{varId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/pom.xml -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminBookingTermsController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminWarmTipsController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/FormulaController.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorCeil10Function.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorMaxFunction.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorSafeFunction.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorSellPriceFunction.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/FormulaEngine.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/FormulaEngineConfig.java -A hl-product-service-v2/src/main/java/com/hulalv/product/engine/PricingContext.java -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/BookingTermsDO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaDO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaGroupDO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaVarDO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaVersionDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/entity/WarmTipsDO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/mapper/BookingTermsMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaGroupMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaVarMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaVersionMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/product/mapper/WarmTipsMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/BookingTermsService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaGroupService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaStepService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaTestService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaVarService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/WarmTipsService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/BookingTermsRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/BookingTermsSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/WarmTipsRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/WarmTipsSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaGroupRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaGroupSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaStepRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaStepSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaTestReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaTestResultVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVarRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVarSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVersionRespVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_1937_b9b1a8fe_fix_product-v2.md b/changelogs/2026-04/2026-04-13_1937_b9b1a8fe_fix_product-v2.md deleted file mode 100644 index 468ed0a..0000000 --- a/changelogs/2026-04/2026-04-13_1937_b9b1a8fe_fix_product-v2.md +++ /dev/null @@ -1,31 +0,0 @@ -# 接口变更记录 — 2026-04-13 19:37 - -> **提交** `b9b1a8fe` · **作者** wx · **时间** 2026-04-13 19:37:39 +0800 -> -> fix(product-v2): 修复模板Controller路由冲突导致启动失败 - -## 变更总览 - -- **hl-product-service-v2** - - AdminProductTemplate (-2) - ---- - -## hl-product-service-v2 - -### AdminProductTemplate - -### ❌ ~~`GET` /admin/product/booking-terms/enabled — 预订条款下拉~~ - -### ❌ ~~`GET` /admin/product/warm-tips/enabled — 温馨提示下拉~~ - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductTemplateController.java -M hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductTemplateControllerTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_2255_0ace7c92_feat_product-v2.md b/changelogs/2026-04/2026-04-13_2255_0ace7c92_feat_product-v2.md deleted file mode 100644 index 2489da8..0000000 --- a/changelogs/2026-04/2026-04-13_2255_0ace7c92_feat_product-v2.md +++ /dev/null @@ -1,56 +0,0 @@ -# 接口变更记录 — 2026-04-13 22:55 - -> **提交** `0ace7c92` · **作者** wx · **时间** 2026-04-13 22:55:29 +0800 -> -> feat(product-v2): 建议售价接口+详情JSON字段修复+审计字段清理 - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (+1) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### 🆕 `GET` /admin/product/item/{id}/suggest-price — 计算建议售价 - -> 根据备品成本+额外成本计算建议售价。如有激活的公式组则通过公式引擎计算。返回成人/儿童单价及成本明细。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<SuggestPriceRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultSuggestPrice` | `BigDecimal` | 成人建议售价(单人) | -| `childSuggestPrice` | `BigDecimal` | 儿童建议售价(单人) | -| `adultCost` | `CostBreakdown` | 成人成本明细 | -| `childCost` | `CostBreakdown` | 儿童成本明细 | -| `formulaApplied` | `Boolean` | 是否使用了公式引擎 | -| `suppliesCost` | `BigDecimal` | 备品成本(按人头) | -| `extraCost` | `BigDecimal` | 额外成本 | -| `totalCost` | `BigDecimal` | 成本合计 | -| `suppliesItems` | `List<CostItem>` | 备品明细 | -| `extraItems` | `List<CostItem>` | 额外成本明细 | -| `name` | `String` | 名称 | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `subtotal` | `BigDecimal` | 小计 | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductController.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductQueryService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/SuggestPriceService.java -A hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/SuggestPriceRespVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-13_product-v2_all_dicts.md b/changelogs/2026-04/2026-04-13_product-v2_all_dicts.md deleted file mode 100644 index 6368805..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_all_dicts.md +++ /dev/null @@ -1,196 +0,0 @@ -# 产品v2全部字典清单 — 2026-04-13 - -> 测试环境字典已全部录入，前端通过字典接口 `GET /admin/dict/data/type/{dictType}` 获取。 -> 以下是产品v2涉及的**全部20个字典**及其完整值列表。 - ---- - -## product_type — 产品类型 - -| 值 | 中文 | 说明 | -|----|------|------| -| CORE | 核心产品 | 标准旅游产品，用价格日历定价 | -| GROUP | 小蒙马 | 跟团游/亲子营，用班期定价 | -| CUSTOM | 私人定制 | 1对1定制，用价格日历定价 | -| ~~ROUTE~~ | ~~自驾路书~~ | v2已废弃，前端不使用 | - -## product_status — 产品状态 - -| 值 | 中文 | 说明 | -|----|------|------| -| DRAFT | 草稿 | 新创建/编辑中 | -| PENDING_REVIEW | 待审核 | 提交上架审批中 | -| PUBLISHED | 已上架 | C端可见 | -| UNPUBLISHED | 已下架 | 主动下架 | -| REJECTED | 已驳回 | 审批被驳回 | -| COMPLETED | 已完成 | 私人定制完成设计 | -| ORDERED | 已下单 | 私人定制已下单 | - -## product_tag — 产品标签 - -| 值 | 中文 | -|----|------| -| 亲子 | 亲子 | -| 研学 | 研学 | -| 露营 | 露营 | -| 城记 | 城记 | -| 摄影 | 摄影 | - -## product_season — 产品季节 - -| 值 | 中文 | -|----|------| -| spring | 春 | -| summer | 夏 | -| autumn | 秋 | -| winter | 冬 | - -## payment_type — 支付方式 - -| 值 | 中文 | -|----|------| -| FULL | 全款支付 | -| DEPOSIT | 订金+尾款 | - -## price_type — 价格类型 - -| 值 | 中文 | 说明 | -|----|------|------| -| NORMAL | 平日 | 默认 | -| PEAK | 旺季 | | -| HOLIDAY | 节假日 | | -| SPECIAL | 特价 | | - -## meal_option — 餐饮选项 - -| 值 | 中文 | -|----|------| -| HOTEL | 含(酒店) | -| CAMP | 含(营地) | -| SPECIAL | 含(特色餐) | -| SELF | 自理 | - -## schedule_status — 班期状态（小蒙马） - -| 值 | 中文 | 说明 | -|----|------|------| -| ENROLLING | 报名中 | 正常接受报名 | -| NEARLY_FULL | 即将满员 | 剩余≤阈值 | -| FULL | 已满 | 无余位 | -| FINISHED | 已结束 | 出发日期已过 | -| CANCELLED | 已取消 | 运营取消 | - -## insurance_notice — 保险告知 - -| 值 | 中文 | -|----|------| -| INCLUDED | 含保险 | -| EXCLUDED | 不含保险 | -| OPTIONAL | 可选升级 | - -## supply_billing — 备品计费方式 - -| 值 | 中文 | -|----|------| -| PER_PERSON | 按人头 | -| PER_QUANTITY | 按数量 | - -## fee_source — 费用来源 - -| 值 | 中文 | 说明 | -|----|------|------| -| AUTO | 自动推导 | 行程资源自动生成 | -| MANUAL | 手动添加 | 运营手动添加 | - -## fee_include_type — 费用包含类型 - -| 值 | 中文 | -|----|------| -| TICKET | 门票 | -| ACCOMMODATION | 住宿 | -| DINING | 餐饮 | -| TRANSPORT | 交通 | -| GUIDE | 导游服务 | -| PHOTOGRAPHY | 旅拍 | - -## fee_exclude_type — 费用不含类型 - -| 值 | 中文 | -|----|------| -| PERSONAL | 个人消费 | -| OPTIONAL | 自费项目 | -| INSURANCE_UPGRADE | 保险升级 | -| OTHER | 其他 | - -## team_role — 团队角色（小蒙马班期用） - -| 值 | 中文 | -|----|------| -| GUIDE | 导游 | -| ASSISTANT_GUIDE | 助理导游 | -| LEADER | 领队 | -| PHOTOGRAPHER | 摄影师 | -| LIFE_TEACHER | 生活老师 | -| STUDY_TEACHER | 研学老师 | -| OTHER | 其他 | - -## tier_name — 档位名称（前端叫「规格」） - -| 值 | 中文 | 说明 | -|----|------|------| -| 舒适 | 舒适 | 预设值，也支持自定义输入 | -| 豪华 | 豪华 | | -| 高端 | 高端 | | -| 轻奢 | 轻奢 | | - -## line_tag — 产品线标签（前端叫「主题标签」） - -| 值 | 中文 | -|----|------| -| 亲子游 | 亲子游 | -| 深度游 | 深度游 | -| 短途 | 短途 | -| 定制 | 定制 | - -## product_node_type — 行程节点类型 - -| 值 | 中文 | -|----|------| -| TRANSPORT | 交通 | -| SCENIC | 景区 | -| RESTAURANT | 餐厅 | -| ACTIVITY | 活动 | -| PHOTOGRAPHY | 拍摄 | -| HOTEL | 住宿 | -| FREE | 自由活动 | -| CUSTOM | 自定义 | -| SERVICE | 服务 | -| NOTE | 备注 | - -## product_grade — 产品档次（旧版用，v2用tier_name替代） - -| 值 | 中文 | -|----|------| -| LIGHT_LUXURY | 轻奢 | -| HIGH_END | 高档 | - -## product_category — 产品分类（旧版用） - -| 值 | 中文 | -|----|------| -| family | 亲子游 | -| honeymoon | 蜜月旅行 | -| photography | 摄影之旅 | -| experience | 深度体验 | -| driving | 自驾越野 | - -## product_approval_status — 审批状态 - -| 值 | 中文 | -|----|------| -| NONE | 无审核 | -| PENDING | 审核中 | -| PUBLISH_APPROVED | 上架通过 | -| PUBLISH_REJECTED | 上架驳回 | -| UNPUBLISH_APPROVED | 下架通过 | -| UNPUBLISH_REJECTED | 下架驳回 | diff --git a/changelogs/2026-04/2026-04-13_product-v2_basic-api-change.md b/changelogs/2026-04/2026-04-13_product-v2_basic-api-change.md deleted file mode 100644 index 8609fd4..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_basic-api-change.md +++ /dev/null @@ -1,104 +0,0 @@ -# 接口变更记录 — 2026-04-13 （重要） - -> **变更类型**：接口路径变更 -> **影响范围**：创建产品 + Step1基础信息保存 -> **测试环境已部署** - ---- - -## Step1 基础信息保存 — 接口变更 - -### 旧接口（已删除，不可用） - -``` -POST /admin/product/item ← 已删除 -PUT /admin/product/item/{id}/basic ← 已删除 -``` - -### 新接口（立即使用） - -``` -POST /admin/product/item/basic -``` - -**一个接口同时支持创建和更新**： -- `productId` **不传** = 创建新产品，返回新productId -- `productId` **传了** = 更新已有产品，返回原productId - -### 创建产品（productId不传） - -```json -// POST /admin/product/item/basic -{ - "productType": "CORE", // 创建时必传: CORE/GROUP/CUSTOM - "name": "额吉的故乡·亲子版", // 必传 - "tripDays": 6, // 可选 - "lineId": 100 // CORE/GROUP必传，CUSTOM可空 -} -``` - -**响应**： -```json -{ - "code": 200, - "message": "成功", - "data": 2043246204711550977 // 新产品ID -} -``` - -### 更新产品（productId传已有ID） - -```json -// POST /admin/product/item/basic -{ - "productId": 2043246204711550977, // 传了就是更新 - "version": 0, // 更新时必传（乐观锁） - "name": "额吉的故乡·亲子版", - "subtitle": "6天5晚草原环线", - "tripDays": 6, - "lineId": 100, - "coverImageUrl": "https://...", - "seasons": ["summer", "autumn"], - "tags": ["亲子", "研学"], - "tiers": [ - {"tierSeq": 1, "tierName": "舒适"}, - {"tierSeq": 2, "tierName": "豪华"} - ], - "paymentType": "FULL", - "showReview": true -} -``` - -**响应**： -```json -{ - "code": 200, - "message": "成功", - "data": 2043246204711550977 // 原产品ID -} -``` - -### 前端使用方式 - -``` -新建产品： - 1. 弹窗填 name + productType + lineId - 2. POST /admin/product/item/basic（不传productId） - 3. 拿到返回的 productId → 跳转编辑页 - -编辑产品： - 1. GET /admin/product/item/{id} 拿详情 + version - 2. 修改字段 - 3. POST /admin/product/item/basic（传productId + version） -``` - ---- - -## 字典补充：payment_type 已恢复 - -`GET /admin/dict/data/type/payment_type` - -| 值 | 中文 | -|----|------| -| FULL | 全款支付 | -| DEPOSIT | 订金+尾款 | diff --git a/changelogs/2026-04/2026-04-13_product-v2_calculate_mileage_api.md b/changelogs/2026-04/2026-04-13_product-v2_calculate_mileage_api.md deleted file mode 100644 index 8a0885d..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_calculate_mileage_api.md +++ /dev/null @@ -1,61 +0,0 @@ -# 产品v2 - 新增自动计算行程总里程接口 - -**日期**: 2026-04-13 -**服务**: product-service-v2 -**类型**: 新增接口 -**PR**: #431 - ---- - -## 新增接口 - -### `GET /admin/product/item/{productId}/calculate-mileage` - -根据行程途经点坐标，调用高德驾车路线规划API自动计算总驾驶里程。 - -**前提条件**: 产品必须已保存行程(Step2)，且行程中至少有2个有效途经点（有经纬度坐标）。 - -**请求参数**: 无（productId在路径中） - -**返回示例**: - -```json -{ - "code": 200, - "data": 1234.5, - "msg": "success" -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| data | BigDecimal | 总里程(km)，保留1位小数 | - -**错误情况**: -- 行程途经点不足2个：返回错误提示 -- 高德API调用失败：返回错误提示 - -## 使用场景 - -Step3"路线与备品"页面，前端可调用此接口获取自动计算的里程值，填充到"总里程"输入框中。 - -**建议交互**: -- 进入Step3时，若总里程为空，自动调一次此接口获取里程 -- 提供"自动计算"按钮，点击时调用此接口刷新里程值 -- 用户仍可手动修改覆盖自动计算的值 - -## 同时修复 - -### 行程酒店名快照补全 - -Step2行程保存时，如果住宿节点(accommodations)传了`resourceId`但没传`hotelName`，后端会自动通过Feign查询酒店名称填充。前端无需改动。 - -### Step1 支付字段恢复 - -`POST /admin/product/item/basic` 请求体恢复以下字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| paymentType | String | 支付方式(字典payment_type: FULL=全款, DEPOSIT=订金+尾款) | -| depositRatio | BigDecimal | 订金比例(0-100)，paymentType=DEPOSIT时必填 | -| depositDeadlineDays | Integer | 尾款截止天数(出发前N天)，paymentType=DEPOSIT时必填 | diff --git a/changelogs/2026-04/2026-04-13_product-v2_category_binding_fix.md b/changelogs/2026-04/2026-04-13_product-v2_category_binding_fix.md deleted file mode 100644 index e3d415a..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_category_binding_fix.md +++ /dev/null @@ -1,52 +0,0 @@ -# 产品v2 - 产品分类(category)字段绑定问题 - -**日期**: 2026-04-13 -**服务**: product-service-v2 -**类型**: 前端修复提醒 - ---- - -## 问题 - -前端"产品类型"选择器（亲子游、蜜月旅行、摄影之旅、深度体验、自驾越野）的值**没有发送到后端**，导致产品分类保存不上。 - -从请求payload截图确认：请求体中有 `productType: "CORE"` 但**没有 `category` 字段**。 - -## 原因 - -后端有两个独立字段： -- `productType` — 产品类型，值为 `CORE`/`GROUP`/`CUSTOM`（核心产品/小蒙马/私人定制） -- `category` — 产品分类，值为字典 `product_category` 的code - -前端的"产品类型"选择器实际对应的是后端的 **`category`** 字段，不是 `productType`。 - -## 前端需要修改 - -### 保存接口 `POST /admin/product/item/basic` - -请求体中增加 `category` 字段： - -```json -{ - "productId": "2043595351268519937", - "productType": "CORE", - "category": "family", // ← 这个字段！"产品类型"选择器的值 - "name": "6天5晚旷野版", - "lineId": "2043595259778166786", - ... -} -``` - -### 字段对照 - -| 前端UI标签 | 后端字段名 | 可选值（字典product_category） | -|-----------|-----------|------| -| 产品类型 | `category` | `family`=亲子游, `honeymoon`=蜜月旅行, `photography`=摄影之旅, `experience`=深度体验, `driving`=自驾越野 | - -### 详情回显 - -`GET /admin/product/item/{productId}` 返回中已包含 `category` 字段，前端读取后设置选择器选中状态即可。 - -## 后端已验证 - -通过API直接发送 `category: "family"` 已确认可以正常保存和回显，后端无需改动。 diff --git a/changelogs/2026-04/2026-04-13_product-v2_category_currentStep.md b/changelogs/2026-04/2026-04-13_product-v2_category_currentStep.md deleted file mode 100644 index 8437a66..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_category_currentStep.md +++ /dev/null @@ -1,75 +0,0 @@ -# 接口变更记录 — 2026-04-13 - -> **变更类型**：新增字段 - ---- - -## 一、新增 category 字段（产品分类） - -### 影响接口 - -| 接口 | 方法 | 字段 | -|------|------|------| -| Step1保存 | POST `/admin/product/item/basic` | 请求参数新增 `category` | -| 产品详情 | GET `/admin/product/item/{id}` | 响应新增 `category` | -| 产品列表 | GET `/admin/product/item/list` | 响应新增 `category` | - -### 字段说明 - -- **字段名**：`category` -- **字典**：`product_category` -- **值**：family=亲子游, honeymoon=蜜月旅行, photography=摄影之旅, experience=深度体验, driving=自驾越野 - -### 前端注意 - -Step1页面的"产品类型"选择器（亲子游/蜜月旅行...）应该绑定 `category` 字段，不是 `productType`。 - -- `productType`：CORE/GROUP/CUSTOM（产品类型，创建时选定不可改） -- `category`：family/honeymoon/...（产品分类，Step1可编辑） - -详情接口已返回 `category: "family"`，前端回显时匹配这个值。 - ---- - -## 二、新增 currentStep 字段（步骤进度） - -产品详情接口 `GET /admin/product/item/{id}` 新增 `currentStep` 字段： - -| 值 | 含义 | -|----|------| -| 1 | 基础信息（仅创建了产品） | -| 2 | 行程编排（有行程天数据） | -| 3 | 路线与备品（有路线/备品数据） | -| 4 | 定价管理（有价格/班期数据） | -| 5 | 补充信息（有费用说明数据） | - -前端用这个字段决定步骤导航栏的状态（当前步/已完成/未到）。 - ---- - -## 三、Step1删除的字段（原型中不存在） - -以下字段已从Step1保存接口删除，前端**不要再传**： - -- ~~seasons~~（季节） -- ~~carouselImages~~（轮播图） -- ~~isBooking~~（预约产品） -- ~~paymentType~~（支付方式） -- ~~depositRatio~~（订金比例） -- ~~depositAmount~~（订金金额） -- ~~balanceDueDays~~（尾款期限） -- ~~defaultDailyStock~~（每日库存） - ---- - -## 四、前端Step1页面需要去掉的UI组件 - -以下字段**后端已删除**，前端传了也会被忽略，请去掉对应的UI组件： - -| UI组件 | 对应字段 | 原因 | -|--------|---------|------| -| 支付类型（全款支付/订金+尾款） | ~~paymentType~~ | 原型Step1没有 | -| 订金设置（固定金额/比例） | ~~depositRatio/depositAmount~~ | 原型Step1没有 | -| 尾款须在出发前N天付清 | ~~balanceDueDays~~ | 尾款时间固定为行程第一天 | -| 每日库存默认值 | ~~defaultDailyStock~~ | 原型Step1没有 | -| 是否预约产品 | ~~isBooking~~ | 原型Step1没有 | diff --git a/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md b/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md deleted file mode 100644 index 9bd116c..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md +++ /dev/null @@ -1,257 +0,0 @@ -# 接口变更记录 — 2026-04-13 - -> **变更类型**：接口合并 + 定价模型说明 -> **在线文档**： -> - 局域网：http://192.168.100.236:8080/doc.html → `1. 管理端 - 产品管理` -> - 公网：https://api.test.1814.love:9443/doc.html（需认证） - ---- - -## 一、创建产品和Step1基础信息合并为一个接口 - -### 旧接口（已删除） - -| 接口 | 说明 | -|------|------| -| ~~POST /admin/product/item~~ | ~~独立创建接口，已删除~~ | -| ~~PUT /admin/product/item/{id}/basic~~ | ~~独立Step1保存，已删除~~ | - -### 新接口 - -**`POST /admin/product/item/basic`** — 创建+更新合一 - -- **productId 不传** = 创建新产品（草稿），返回新 productId -- **productId 传了** = 更新已有产品，返回原 productId - -### 创建时请求示例（productId不传） - -```json -{ - "productType": "CORE", - "name": "额吉的故乡·亲子版", - "tripDays": 6, - "lineId": 100, - "coverImageUrl": "https://...", - "seasons": ["summer"], - "tags": ["亲子"] -} -``` - -- `productType` **创建时必传**（CORE/GROUP/CUSTOM） -- `version` **创建时不传** -- 其他字段可选，创建时可以只传最少信息，也可以一次性填完全部 - -### 更新时请求示例（productId传已有ID） - -```json -{ - "productId": 2043246204711550977, - "version": 0, - "name": "额吉的故乡·亲子版（修改）", - "tripDays": 6, - "lineId": 100, - "coverImageUrl": "https://...", - "seasons": ["summer", "autumn"], - "tags": ["亲子", "研学"], - "tiers": [ - {"tierSeq": 1, "tierName": "舒适"}, - {"tierSeq": 2, "tierName": "豪华"} - ] -} -``` - -- `version` **更新时必传**（从详情接口获取，乐观锁校验） -- `productType` 更新时传了也会被忽略（创建后不可改） - -### 响应 - -```json -{ - "code": 200, - "message": "成功", - "data": 2043246204711550977 -} -``` - -返回 `Long` 类型的产品ID（创建时是新ID，更新时是原ID）。 - ---- - -## 二、定价模型：哪种产品用哪个接口 - -### 核心规则 - -| 产品类型 | 定价模型 | 用户选什么 | 用哪组接口 | -|---------|---------|-----------|-----------| -| **CORE**（核心产品） | 价格日历 | 用户从日历选出发日期 | `price-calendar` 系列 | -| **CUSTOM**（私人定制） | 价格日历 | 同上 | `price-calendar` 系列 | -| **GROUP**（小蒙马） | 班期制 | 用户从班期列表选第N期 | `schedule` 系列 | - -### 前端判断逻辑 - -``` -if (productType === 'CORE' || productType === 'CUSTOM') { - // Step4 显示【价格日历】界面 - // 用 price-calendar 系列接口 -} else if (productType === 'GROUP') { - // Step4 显示【班期管理】界面 - // 用 schedule 系列接口 -} -``` - -### 价格日历接口（CORE / CUSTOM 产品用） - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 查询价格日历 | GET | `/admin/product/item/{id}/price-calendar?month=2026-07&tierSeq=1` | 按月+档位查询 | -| 批量设置价格 | POST | `/admin/product/item/{id}/price-calendar/batch` | 按日期范围设价 | -| 删除价格区间 | DELETE | `/admin/product/item/{id}/price-calendar` | 按日期范围删除 | - -**批量设置请求示例**： - -```json -{ - "productId": 123, - "version": 3, - "startDate": "2026-07-01", - "endDate": "2026-07-31", - "tierSeq": 1, - "priceType": "PEAK", - "adultSellPrice": 4980, - "childSellPrice": 3980, - "toddlerDiscount": -500, - "infantPrice": 0, - "dailyStock": 10 -} -``` - -**价格日历查询响应**： - -```json -[ - { - "id": 1, - "productId": 123, - "tierSeq": 1, - "date": "2026-07-01", - "priceType": "PEAK", - "adultSellPrice": 4980, - "childSellPrice": 3980, - "toddlerDiscount": -500, - "infantPrice": 0, - "dailyStock": 10, - "sold": 2 - } -] -``` - -### 班期接口（GROUP 小蒙马产品用） - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 班期列表 | GET | `/admin/product/item/{id}/schedule/list` | 返回全部班期 | -| 创建班期 | POST | `/admin/product/item/{id}/schedule` | 不传batchId | -| 修改班期 | PUT | `/admin/product/item/{id}/schedule` | 传batchId | -| 删除班期 | DELETE | `/admin/product/item/{id}/schedule/{scheduleId}` | 有订单不可删 | -| 取消班期 | POST | `/admin/product/item/{id}/schedule/{scheduleId}/cancel` | 触发退款 | -| 批量创建 | POST | `/admin/product/item/{id}/schedule/batch-create` | 按重复模式 | -| 班期团队查询 | GET | `/admin/product/item/{id}/schedule/team?batchId=xxx` | 团队成员 | -| 班期团队保存 | PUT | `/admin/product/item/{id}/schedule/team?batchId=xxx` | 全量替换 | - -**创建班期请求示例**： - -```json -{ - "productId": 123, - "batchName": "第1期", - "departureDate": "2026-07-01", - "enrollmentDeadline": "2026-06-30", - "adultPrice": 4980, - "childPrice": 3980, - "toddlerDiscount": -500, - "infantPrice": 0, - "maxParticipants": 20, - "maxRooms": 10, - "productStockLimit": 20 -} -``` - -**班期列表响应**： - -```json -[ - { - "batchId": 456, - "productId": 123, - "batchNo": "B20260701001", - "batchName": "第1期", - "departureDate": "2026-07-01", - "endDate": "2026-07-06", - "enrollmentDeadline": "2026-06-30", - "adultPrice": 4980, - "childPrice": 3980, - "toddlerDiscount": -500, - "infantPrice": 0, - "maxParticipants": 20, - "enrolledCount": 8, - "maxRooms": 10, - "bookedRooms": 4, - "productStockLimit": 20, - "batchStatus": "ENROLLING", - "version": 0 - } -] -``` - -**批量创建班期请求示例**： - -```json -{ - "productId": 123, - "startDate": "2026-07-01", - "endDate": "2026-09-30", - "repeatMode": "WEEKLY", - "dayOfWeek": 1, - "adultPrice": 4980, - "childPrice": 3980, - "maxParticipants": 20, - "maxRooms": 10 -} -``` - -### 价格日历 vs 班期对比 - -| 维度 | 价格日历（CORE/CUSTOM） | 班期（GROUP） | -|------|----------------------|-------------| -| 定价粒度 | 每天独立价格 | 每期一个固定价格 | -| 库存 | 按天（dailyStock=每天可接几单） | 按期（maxParticipants=总人数+maxRooms=总房间数） | -| 档位 | 支持多档（tierSeq区分） | 单一档位 | -| 用户选择 | C端日历选日期 | C端列表选第N期 | -| 团队配置 | 无 | 每期可配领队/摄影师等 | -| 价格类型 | 平日/旺季/节假日/特价（颜色区分） | 无（每期统一价） | - -### 班期状态说明 - -| 状态 | 中文 | 说明 | -|------|------|------| -| ENROLLING | 报名中 | 正常接受报名 | -| NEARLY_FULL | 即将满员 | 剩余房间≤阈值（默认2间） | -| FULL | 已满 | 剩余房间=0 | -| FINISHED | 已结束 | 出发日期已过 | -| CANCELLING | 取消中 | 有订单，退款处理中 | -| CANCELLED | 已取消 | 取消完成 | - ---- - -## 三、后端与前端名词对照 - -| 后端术语 | 后端字段 | 前端术语 | 说明 | -|---------|---------|---------|------| -| 产品线 | lineId / lineName | **主题** | 如"额吉的故乡""草原环线" | -| 产品 | productId / name | **版本** | 如"亲子版""旷野版""舒适版" | -| 档位 | tierSeq / tierName / tierCount | **规格** | 如"舒适""豪华"，tierCount=规格数量 | - -**前端展示映射**： -- 主题列表 → 调 `/admin/product/line/list` -- 版本列表 → 调 `/admin/product/item/list`（tierCount=该版本有几个规格） -- 规格详情 → 在产品详情的 `tiers` 字段中（`[{tierSeq:1, tierName:"舒适"}, {tierSeq:2, tierName:"豪华"}]`） diff --git a/changelogs/2026-04/2026-04-13_product-v2_dict_and_field_fix.md b/changelogs/2026-04/2026-04-13_product-v2_dict_and_field_fix.md deleted file mode 100644 index 855f246..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_dict_and_field_fix.md +++ /dev/null @@ -1,87 +0,0 @@ -# 接口变更记录 — 2026-04-13 - -> **变更类型**：字段补全 + 字典补全 -> **在线文档**： -> - 局域网：http://192.168.100.236:8080/doc.html -> - 公网：https://api.test.1814.love:9443/doc.html - ---- - -## 一、产品列表字段补全 - -管理端产品列表 `GET /admin/product/item/list` 补全了以下字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| productId | Long | 产品ID | -| productNo | String | 产品编号(C260409001) | -| productType | String | 产品类型(CORE/GROUP/CUSTOM) | -| name | String | 产品名称 | -| **subtitle** | String | **副标题（新增）** | -| coverImageUrl | String | 封面图 | -| tripDays | Integer | 行程天数 | -| **tripNights** | Integer | **行程晚数（新增）** | -| **lineId** | Long | **主题ID（新增）** | -| **lineName** | String | **主题名称（新增，关联查询）** | -| status | String | 产品状态 | -| **seasons** | List\<String\> | **产品季节（新增，如["summer","autumn"]）** | -| **tags** | List\<String\> | **产品标签（新增，如["亲子","研学"]）** | -| **tierCount** | Integer | **规格数量（新增，单一=1,多档=N,未配=0）** | -| **startPrice** | BigDecimal | **起步价（新增，最低成人售价）** | -| version | Integer | 版本号 | -| **sortOrder** | Integer | **排序号（新增）** | -| **createdBy** | Long | **创建人ID（字段名从createBy改为createdBy）** | -| **createdByName** | String | **创建人名称（新增）** | -| publishedAt | LocalDateTime | 上架时间 | -| createTime | LocalDateTime | 创建时间 | -| updateTime | LocalDateTime | 更新时间 | - -> **注意**：`createBy` 字段名已改为 `createdBy`，前端需要同步修改。 - ---- - -## 二、字典值完整清单 - -### product_type（产品类型） - -通过字典接口获取：`GET /admin/dict/data/type/product_type` - -| 值 | 中文 | 说明 | -|----|------|------| -| CORE | 核心产品 | 标准旅游产品，用价格日历定价 | -| GROUP | 小蒙马 | 跟团游/亲子营，用班期定价 | -| CUSTOM | 私人定制 | 1对1定制，用价格日历定价 | -| ~~ROUTE~~ | ~~自驾路书~~ | **v2已废弃，不使用** | - -### product_status（产品状态） - -通过字典接口获取：`GET /admin/dict/data/type/product_status` - -| 值 | 中文 | 说明 | -|----|------|------| -| DRAFT | 草稿 | 新创建/编辑中 | -| PENDING_REVIEW | 待审核 | **新增**，提交上架审批中 | -| PUBLISHED | 已上架 | 审批通过，C端可见 | -| UNPUBLISHED | 已下架 | 主动下架或审批下架 | -| REJECTED | 已驳回 | **新增**，审批被驳回 | -| COMPLETED | 已完成 | 私人定制完成设计 | -| ORDERED | 已下单 | **新增**，私人定制已下单 | - -### 其他相关字典 - -| 字典类型 | 获取方式 | 值列表 | -|---------|---------|--------| -| product_node_type | `GET /admin/dict/data/type/product_node_type` | TRANSPORT/SCENIC/RESTAURANT/ACTIVITY/PHOTOGRAPHY/HOTEL/FREE/CUSTOM/SERVICE/NOTE | -| product_grade | `GET /admin/dict/data/type/product_grade` | LIGHT_LUXURY=轻奢, HIGH_END=高档 | -| product_category | `GET /admin/dict/data/type/product_category` | family=亲子游, honeymoon=蜜月, photography=摄影, experience=深度体验, driving=自驾越野 | -| product_approval_status | `GET /admin/dict/data/type/product_approval_status` | NONE/PENDING/PUBLISH_APPROVED/PUBLISH_REJECTED/UNPUBLISH_APPROVED/UNPUBLISH_REJECTED | - ---- - -## 三、名词对照提醒 - -| 后端字段 | 前端叫法 | -|---------|---------| -| lineId / lineName | **主题** | -| productId / name | **版本** | -| tierSeq / tierName / tierCount | **规格** | diff --git a/changelogs/2026-04/2026-04-13_product-v2_dict_fix_notice.md b/changelogs/2026-04/2026-04-13_product-v2_dict_fix_notice.md deleted file mode 100644 index e10fb46..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_dict_fix_notice.md +++ /dev/null @@ -1,37 +0,0 @@ -# 前端问题提醒 — 2026-04-13 - -> **问题**：Step1基础信息页面"产品类型"用错了字典 - ---- - -## 产品类型字典用错了 - -### 当前问题 - -Step1页面的"产品类型"选择器显示的是：`亲子游 / 蜜月旅行 / 摄影之旅 / 深度体验 / 自驾越野` - -这是 `product_category`（产品分类）字典，**不是产品类型**。 - -### 正确字典 - -产品类型应该用 `product_type` 字典： - -| 值 | 中文 | 说明 | -|----|------|------| -| CORE | 核心产品 | 标准旅游产品，用价格日历定价 | -| GROUP | 小蒙马 | 跟团游/亲子营，用班期定价 | -| CUSTOM | 私人定制 | 1对1定制，用价格日历定价 | - -### 两个字典的区别 - -| 字典 | 用途 | 前端对应 | -|------|------|---------| -| `product_type` | 产品类型（CORE/GROUP/CUSTOM） | Step1"产品类型"选择器 | -| `product_category` | 产品分类/标签（亲子游/蜜月等） | **不在Step1使用**，旧版字典 | -| `product_tag` | 产品标签（亲子/研学/露营等） | Step1"产品标签"多选 | - -### 注意 - -产品类型在**创建时选定不可修改**，编辑时应该只读显示。前端判断逻辑： -- `productId`为空（创建）→ 产品类型可选 -- `productId`不为空（编辑）→ 产品类型只读 diff --git a/changelogs/2026-04/2026-04-13_product-v2_frontend_guide.md b/changelogs/2026-04/2026-04-13_product-v2_frontend_guide.md deleted file mode 100644 index 762cf3a..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_frontend_guide.md +++ /dev/null @@ -1,864 +0,0 @@ -# 产品模块v2 — 前端联调指南 - -> **日期**：2026-04-13 -> **服务**：hl-product-service-v2（本地端口 8086 / 测试环境端口 8083） -> **在线文档（Knife4j）**： -> - **测试环境（局域网）**：http://192.168.100.236:8080/doc.html -> - **测试环境（公网）**：https://api.test.1814.love:9443/doc.html （需要登录认证） -> - 左侧下拉选择以下分组： -> - `1. 管理端 - 产品管理` — 产品CRUD、5步保存、价格日历、班期、报价 -> - `2. 管理端 - 产品线管理` — 产品线CRUD -> - `3. 管理端 - 模板管理` — 预订条款、温馨提示 -> - `4. 小程序端 - 产品查询` — C端产品列表、详情、价格日历、报价 -> - `5. 小程序端 - 产品线查询` — C端产品线列表 -> - 本地直连：http://localhost:8086/doc.html -> -> **网关路由**：管理端 `/admin/product/**` → hl-product-service-v2，C端 `/mp/product/**` → hl-product-service-v2 -> **重要**：本模块是全新服务，与旧 hl-product-service 并行运行。所有接口路径相同但路由已切换到v2。 -> **本文档包含全部接口定义**，无需查看其他文件或在线文档。 - ---- - -## 一、整体架构变化 - -### 旧服务 vs 新服务 - -| 维度 | 旧 hl-product-service | 新 hl-product-service-v2 | -|------|----------------------|--------------------------| -| 产品类型 | CORE/GROUP/CUSTOM/ROUTE（4种） | CORE/GROUP/CUSTOM（3种，ROUTE废弃） | -| 保存方式 | 每个字段独立接口 | **5个业务域整体保存**（基础/行程/路线/定价/补充） | -| 定价模型 | 统一价格日历 | **双模型**：价格区间（CORE/CUSTOM）+ 班期（GROUP） | -| 住宿 | 统一 | 支持**多档位**（舒适/豪华/高端等） | -| 人群分档 | 成人/儿童 | **4档**：成人/儿童/小童/幼童 | -| 并发控制 | 无 | **乐观锁**（version字段） | - -### 乐观锁机制（所有保存接口通用） - -``` -1. GET 详情 → 拿到 version 字段 -2. PUT 保存 → 请求体带 version -3. 成功 → version+1（下次保存用新version） -4. 失败(409) → 提示"数据已被其他人修改，请刷新"，重新GET -``` - -> **已上架产品调价**：用 `priceVersion` 而非 `version`（调价不占主version，允许调价和内容编辑互不阻塞） - ---- - -## 二、管理端页面接口对照 - -### 页面1：产品列表 - -``` -┌──────────────────────────────────────────────────────────────┐ -│ [搜索: 名称/编号] [类型▼] [产品线▼] [状态▼] [标签▼] │ -│ [+ 新建产品] │ -├──────────────────────────────────────────────────────────────┤ -│ 封面 │ 名称/编号 │ 类型 │ 产品线 │ 状态 │ 操作 │ -│ ... │ ... │ ... │ ... │ ... │ 编辑/复制/删除│ -└──────────────────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 产品列表 | GET | `/admin/product/item/list` | 分页，支持keyword/productType/lineId/status/tag筛选 | -| 产品线下拉 | GET | `/admin/product/line/simple-list` | 返回 `[{lineId, name, productType}]`，用于筛选和创建 | -| 创建产品 | POST | `/admin/product/item` | 传 name+productType+lineId+tripDays，返回productId | -| 删除产品 | DELETE | `/admin/product/item/{id}` | 需先下架 | -| 复制产品 | POST | `/admin/product/item/{id}/copy` | 返回新productId | -| 状态变更 | PUT | `/admin/product/item/{id}/action` | 传 action 枚举，见下方状态操作表 | -| 操作记录 | GET | `/admin/product/item/{id}/operation-logs` | 分页，查看历史操作 | - -**产品列表请求参数**： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| keyword | String | 否 | 搜索关键词（匹配名称/编号） | -| productType | String | 否 | 产品类型筛选(CORE/GROUP/CUSTOM) | -| lineId | Long | 否 | 产品线ID筛选 | -| status | String | 否 | 状态筛选(DRAFT/PUBLISHED等) | -| tag | String | 否 | 标签筛选 | -| page | Integer | 否 | 页码(默认1) | -| pageSize | Integer | 否 | 每页条数(默认20) | - -**产品列表响应字段**（`PageResult<ProductListRespVO>`中每条）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| productId | Long | 产品ID | -| productNo | String | 产品编号(如C260409001) | -| name | String | 产品名称 | -| productType | String | 产品类型 | -| status | String | 产品状态 | -| coverImageUrl | String | 封面图 | -| tripDays | Integer | 行程天数 | -| lineId | Long | 产品线ID | -| lineName | String | 产品线名称 | -| tags | List\<String\> | 产品标签 | -| startPrice | BigDecimal | 起步价 | -| createBy | Long | 创建人ID | -| createTime | LocalDateTime | 创建时间 | -| publishedAt | LocalDateTime | 上架时间 | - -**创建产品请求**： - -```json -{ - "name": "额吉的故乡·亲子版", - "productType": "CORE", - "lineId": 100, - "tripDays": 6 -} -``` - -**创建产品响应**：`Result<Long>` — 返回新产品ID - -**状态变更请求**： - -```json -{ - "productId": 123, - "action": "SUBMIT_PUBLISH", - "remark": "提交上架" -} -``` - -**状态操作枚举**（action字段）： - -| action值 | 操作 | 前置状态 | 目标状态 | -|----------|------|---------|---------| -| SUBMIT_PUBLISH | 提交上架 | DRAFT | PENDING_REVIEW | -| WITHDRAW | 撤回审批 | PENDING_REVIEW | DRAFT | -| DIRECT_PUBLISH | 直接上架(超管) | DRAFT | PUBLISHED | -| UNPUBLISH | 申请下架 | PUBLISHED | PENDING_REVIEW(下架) | -| FORCE_UNPUBLISH | 强制下架(超管) | PUBLISHED | UNPUBLISHED | -| COMPLETE | 完成设计(定制) | DRAFT | COMPLETED | - ---- - -### 页面2：产品编辑 — Step1 基础信息 - -``` -┌──────────────────────────────────────────────────┐ -│ Step1 Step2 Step3 Step4 Step5 │ -│ ●基础 ○行程 ○路线 ○定价 ○补充 │ -├──────────────────────────────────────────────────┤ -│ 产品名称: [____________] │ -│ 副标题: [____________] │ -│ 产品类型: CORE (只读，创建时选定) │ -│ 产品线: [下拉选择▼] │ -│ 行程天数: [6] 晚数: [5] │ -│ 住宿规格: ○单一 ○多档 → [舒适][豪华][+添加档位] │ -│ 季节: □春 ☑夏 ☑秋 □冬 │ -│ 标签: ☑亲子 ☑研学 □露营 │ -│ 封面图: [上传] │ -│ 轮播图: [上传1] [上传2] ... (≤10张) │ -│ 年龄设置: 幼童≤[1]岁 小童≤[3]岁 儿童[4]-[12]岁│ -│ 幼童默认价: [0]元 │ -│ 支付方式: ○全款 ○订金([30]%/固定[___]元) │ -│ 产品简介: [富文本编辑器] │ -│ [保存] │ -└──────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 获取详情(回显) | GET | `/admin/product/item/{id}` | 返回全部5步数据（`ProductDetailRespVO`），各步骤取对应部分回显 | -| 保存基础信息 | PUT | `/admin/product/item/{id}/basic` | `ProductBasicSaveReqVO`，带version | -| 产品线下拉 | GET | `/admin/product/line/simple-list` | 创建/修改时选产品线 | - -**Step1 基础信息完整字段表**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| version | Integer | ✅ | 乐观锁版本号（从详情接口获取） | -| name | String | ✅ | 产品名称（≤30字） | -| subtitle | String | 否 | 副标题（≤128字） | -| introduction | String | 否 | 产品简介（富文本HTML） | -| lineId | Long | CORE/GROUP必填 | 产品线ID（私人定制可空） | -| tripDays | Integer | ✅ | 行程天数（≥1） | -| tripNights | Integer | 否 | 行程晚数（不传自动=天数-1） | -| tiers | List | 否 | 档位列表 `[{tierSeq:1, tierName:"舒适"}]` | -| seasons | List\<String\> | 否 | 适用季节(spring/summer/autumn/winter) | -| tags | List\<String\> | 否 | 产品标签(亲子/研学/露营等) | -| coverImageUrl | String | 上架必填 | 封面图URL | -| carouselImages | List\<String\> | 否 | 轮播图URL列表（≤10张） | -| infantAgeMax | Integer | 否 | 幼童年龄上限（默认1岁） | -| toddlerAgeMax | Integer | 否 | 小童年龄上限（默认3岁） | -| childAgeMin | Integer | 否 | 儿童年龄下限（默认4岁） | -| childAgeMax | Integer | 否 | 儿童年龄上限（默认12岁） | -| infantDefaultPrice | BigDecimal | 否 | 幼童默认价（元，0=免费） | -| isBooking | Boolean | 否 | 是否预约产品（默认false） | -| paymentType | String | 否 | 支付方式(FULL=全款/DEPOSIT=订金) | -| depositRatio | Integer | 否 | 订金比例%（DEPOSIT时用，与固定额二选一） | -| depositAmount | BigDecimal | 否 | 订金固定额（DEPOSIT时用） | -| balanceDueDays | Integer | 否 | 尾款期限（出发前N天） | -| defaultDailyStock | Integer | 否 | 每日库存默认值（NULL=不限量） | -| defaultRoomCount | Integer | 否 | 默认房间数（小蒙马用） | -| minGroupSize | Integer | 否 | 最低成团人数（小蒙马用） | -| showReview | Boolean | 否 | C端展示评价（默认true） | -| showChatGroup | Boolean | 否 | 展示群聊入口 | -| showTripTime | Boolean | 否 | 展示行程时间 | -| showTripDistance | Boolean | 否 | 展示行程距离 | -| creatorAvatarUrl | String | 否 | 创建者头像URL | -| creatorIntro | String | 否 | 创建者简介（≤512字） | -| customizerId | Long | 否 | 定制师ID（私人定制用） | -| customerName | String | 否 | 客户姓名（私人定制用） | -| contactPhone | String | 否 | 联系电话（私人定制用） | -| departureDate | LocalDate | 否 | 出发日期（私人定制用，格式yyyy-MM-dd） | -| safetyItems | List | 否 | 安全保障项 `[{icon,title,description}]` | -| photographyItems | List | 否 | 摄影跟拍项 `[{name,description}]` | -| diningHighlights | List | 否 | 餐饮亮点 `[{name,description}]` | - -**请求示例**： - -```json -{ - "version": 1, - "name": "额吉的故乡·亲子版", - "subtitle": "6天5晚草原环线", - "tripDays": 6, - "tripNights": 5, - "lineId": 100, - "tiers": [ - {"tierSeq": 1, "tierName": "舒适"}, - {"tierSeq": 2, "tierName": "豪华"} - ], - "seasons": ["summer", "autumn"], - "tags": ["亲子", "研学"], - "coverImageUrl": "https://...", - "carouselImages": ["https://...", "https://..."], - "infantAgeMax": 1, - "toddlerAgeMax": 3, - "childAgeMin": 4, - "childAgeMax": 12, - "infantDefaultPrice": 0, - "paymentType": "FULL", - "showReview": true -} -``` - ---- - -### 页面3：产品编辑 — Step2 行程编排 - -``` -┌──────────────────────────────────────────────────┐ -│ DAY1 DAY2 DAY3 DAY4 DAY5 DAY6 [+添加] │ -├──────┬───────────────────────────────────────────┤ -│ │ 标题: [海拉尔→额尔古纳] │ -│ DAY1 │ 金句: [让草原成为孩子的第一个课堂] │ -│ │ 描述: [富文本] │ -│ │ 封面: [上传] 里程: [290]km │ -│ │ │ -│ │ 途经路线: │ -│ │ [海拉尔] → [莫日格勒河] → [额尔古纳] │ -│ │ │ -│ │ 活动安排: │ -│ │ ☐ 10:00 莫日格勒河观景台 (景区) 60分钟 │ -│ │ ☐ 14:00 骑马体验 (活动) 120分钟 │ -│ │ [+ 从资源库添加] [+ 自定义活动] │ -│ │ │ -│ │ 住宿安排: (多档时按档位Tab切换) │ -│ │ [舒适] 额尔古纳大酒店 │ -│ │ [豪华] 额尔古纳国际酒店 │ -│ │ │ -│ │ 餐饮: 早[酒店▼] 中[自理▼] 晚[特色餐▼] │ -│ │ 照片: [上传1] [上传2] │ -│ │ │ -│ │ [整体保存] │ -└──────┴───────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 获取行程(回显) | GET | `/admin/product/item/{id}` | 从详情中取 `itinerary` 部分 | -| 整体保存行程 | PUT | `/admin/product/item/{id}/itinerary` | **整棵行程树一次提交**，后端用EntityDiffUtil对比增删改 | -| 增加一天 | POST | `/admin/product/item/{id}/itinerary/day` | 追加末尾天，返回dayId | -| 删除一天 | DELETE | `/admin/product/item/{id}/itinerary/day/{dayNumber}` | 级联删节点+住宿+路线点 | -| 费用推导预览 | GET | `/admin/product/item/{id}/fee-deduction-preview` | 根据行程自动推导费用包含，进入Step5前调用 | - -**整体保存请求结构**： - -```json -{ - "productId": 123, - "version": 2, - "days": [ - { - "dayId": null, // 新增不传，已有传ID - "dayNumber": 1, - "dayTitle": "海拉尔→额尔古纳", - "quoteText": "让草原成为孩子的第一个课堂", - "description": "...", - "coverImageUrl": "https://...", - "dailyMileage": 290, - "breakfast": "HOTEL", // HOTEL/CAMP/SPECIAL/SELF - "lunch": "SELF", - "dinner": "SPECIAL", - "photoUrls": ["https://..."], - "nodes": [ - { - "nodeId": null, // 新增不传 - "sortOrder": 1, - "nodeType": "SCENIC", - "nodeName": "莫日格勒河观景台", - "resourceType": "SCENIC_SPOT", - "resourceId": 456, - "startTime": "10:00", - "durationMinutes": 60, - "description": "...", - "images": ["https://..."] - } - ], - "hotels": [ - { - "id": null, - "tierSeq": 1, // 档位序号，单一档=1 - "hotelId": 789, - "roomTypeId": null, // 私人定制才选房型 - "isDefault": true, - "sortOrder": 1 - } - ], - "routePoints": [ - { - "resourceId": 456, - "name": "莫日格勒河", - "longitude": 119.123, - "latitude": 49.456, - "sortOrder": 1 - } - ] - } - ] -} -``` - -> **增删改对比规则**：后端按ID判断——有ID且在提交中=更新，有ID但不在提交中=删除，无ID=新增。前端直接提交当前完整状态，不需要自己标记增删改。 - ---- - -### 页面4：产品编辑 — Step3 路线与备品 - -``` -┌──────────────────────────────────────────────────┐ -│ 路线信息 │ -│ 路线名称: [草原环线体验] │ -│ 路线图: [上传] │ -│ 总里程: [1200] km (自动计算，可手动改) │ -│ 线路描述: [____________] │ -│ │ -│ 备品清单 │ -│ 名称 │ 涉及成本 │ 计费方式 │ 单价 │ 数量 │ -│ 防晒霜SPF50+ │ ☐ │ — │ — │ — │ -│ 一次性雨衣 │ ☑ │ 按人头 │ 5 │ — │ -│ [+ 从资源库选] [+ 自定义] │ -│ │ -│ 全程成本项 │ -│ 实际用车: [车型下拉▼] │ -│ 服务人员: [选择▼] │ -│ 额外费用: [名称] [单价] [数量] [按天☐] │ -│ [保存] │ -└──────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 保存路线与备品 | PUT | `/admin/product/item/{id}/route` | `ProductRouteSaveReqVO`，一次提交全部 | -| 车型下拉 | — | 调资源服务 `/internal/vehicle-model/list` | 从资源模块获取车型列表 | -| 人员下拉 | — | 调资源服务 `/internal/staff/list` | 从资源模块获取人员列表 | -| 备品下拉 | — | 调资源服务 `/internal/supplies/list` | 从资源模块获取备品列表 | - -**路线与备品请求示例**： - -```json -{ - "productId": 123, - "version": 3, - "routeName": "草原环线体验", - "routeMapUrl": "https://...", - "totalMileage": 1200, - "routeDescription": "海拉尔起止，途经莫日格勒河、额尔古纳...", - "vehicleModelId": 10, - "staffCostIds": [20, 21], - "supplies": [ - { - "id": null, - "suppliesResourceId": 30, - "suppliesName": "防晒霜SPF50+", - "category": "防护用品", - "hasCost": false, - "sortOrder": 1 - }, - { - "id": null, - "suppliesResourceId": null, - "suppliesName": "一次性雨衣", - "category": "防护用品", - "hasCost": true, - "billingType": "PER_PERSON", - "unitPrice": 5, - "quantity": null, - "sortOrder": 2 - } - ], - "extraCosts": [ - { - "id": null, - "name": "接机费", - "unitPrice": 200, - "quantity": 1, - "daily": false, - "sortOrder": 1 - } - ] -} -``` - ---- - -### 页面5：产品编辑 — Step4 定价管理 - -#### 核心产品/私人定制 → 价格区间 - -``` -┌──────────────────────────────────────────────────┐ -│ 价格区间列表 │ -│ 日期范围 │ 类型 │ 成人价 │ 儿童价 │ 库存 │ -│ 07.01 - 07.31 │ 旺季 │ 4980 │ 3980 │ 10 │ -│ 08.01 - 08.31 │ 旺季 │ 5280 │ 4280 │ 10 │ -│ 09.01 - 09.30 │ 平日 │ 3980 │ 2980 │ 不限 │ -│ [+ 新增区间] │ -│ │ -│ (多档时每个区间按档位平铺多组价格) │ -│ [保存] │ -└──────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 查询价格日历 | GET | `/admin/product/item/{id}/price-calendar` | 参数 month(yyyy-MM)、tierSeq(档位) | -| 批量设置价格 | POST | `/admin/product/item/{id}/price-calendar/batch` | 按日期范围+档位UPSERT | -| 删除价格区间 | DELETE | `/admin/product/item/{id}/price-calendar` | 按日期范围+档位删除 | -| 报价测算 | POST | `/admin/product/item/{id}/quote` | 输入日期+人数，预览总价 | - -**批量设置请求**： - -```json -{ - "productId": 123, - "version": 3, // 草稿用version，已上架用priceVersion - "startDate": "2026-07-01", - "endDate": "2026-07-31", - "tierSeq": 1, // 档位序号，单一=1 - "priceType": "PEAK", // NORMAL/PEAK/HOLIDAY/SPECIAL - "adultSellPrice": 4980, - "childSellPrice": 3980, - "toddlerDiscount": -500, // 小童优惠额(负数)，小童价=儿童价-|优惠额| - "infantPrice": 0, // 幼童价，0=免费 - "dailyStock": 10 // NULL=不限量 -} -``` - -#### 小蒙马 → 班期管理 - -``` -┌──────────────────────────────────────────────────┐ -│ 班期列表 │ -│ 班期名 │ 出发日 │ 状态 │ 成人价 │ 已报/上限 │ -│ 第1期 │ 07.01 │ 报名中│ 4980 │ 8/20 │ -│ 第2期 │ 07.15 │ 报名中│ 4980 │ 3/20 │ -│ [+ 新增] [批量创建] │ -└──────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 班期列表 | GET | `/admin/product/item/{id}/schedule/list` | 返回全部班期 | -| 创建班期 | POST | `/admin/product/item/{id}/schedule` | `ScheduleSaveReqVO`，不传batchId | -| 修改班期 | PUT | `/admin/product/item/{id}/schedule` | 传batchId | -| 删除班期 | DELETE | `/admin/product/item/{id}/schedule/{scheduleId}` | 有订单不可删 | -| 取消班期 | POST | `/admin/product/item/{id}/schedule/{scheduleId}/cancel` | 有订单触发退款 | -| 批量创建 | POST | `/admin/product/item/{id}/schedule/batch-create` | 按重复模式批量 | -| 团队查询 | GET | `/admin/product/item/{id}/schedule/team?batchId=xxx` | 班期团队成员 | -| 团队保存 | PUT | `/admin/product/item/{id}/schedule/team?batchId=xxx` | 全量替换 | - ---- - -### 页面6：产品编辑 — Step5 补充信息 - -``` -┌──────────────────────────────────────────────────┐ -│ 费用包含 (自动推导+手动编辑) │ -│ ☑ 门票 (自动) │ ☑ 住宿 (自动) │ ☐ 旅拍 (手动) │ -│ │ -│ 费用不含 │ -│ ☑ 个人消费 │ ☑ 自费项目 │ -│ │ -│ 人群优惠 │ -│ 儿童门票: [免票▼] 住宿: [不占床▼] 餐饮: [半额▼]│ -│ 老人门票: [半价▼] 住宿: [同成人▼] │ -│ │ -│ 车辆展示: [选择车型▼] (纯展示) │ -│ 退改政策: [选择模板▼] │ -│ 预订条款: [选择模板▼] │ -│ 装备建议: [富文本] │ -│ 保险告知: ○含 ○不含 ○可选升级 │ -│ │ -│ 产品卖点 │ -│ 快速理解: [富文本+图片] │ -│ 孩子经历: [富文本+图片] │ -│ 成长收获: [探索力] [协作力] [+添加] │ -│ [保存] │ -└──────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 保存补充信息 | PUT | `/admin/product/item/{id}/supplement` | `ProductSupplementSaveReqVO` | -| 费用推导预览 | GET | `/admin/product/item/{id}/fee-deduction-preview` | 根据行程自动计算费用包含 | -| 退改政策模板 | GET | `/admin/product/refund-policy/enabled` | 下拉选择，返回 `[{policyId, policyName}]` | -| 预订条款模板 | GET | `/admin/product/booking-terms/enabled` | 下拉选择，返回 `[{termsId, termsName}]` | -| 温馨提示模板 | GET | `/admin/product/warm-tips/enabled` | 下拉选择，返回 `[{tipsId, tipsName}]` | - -**补充信息请求示例**： - -```json -{ - "productId": 123, - "version": 4, - "includedFees": [ - {"id": null, "feeType": "TICKET", "name": "门票", "source": "AUTO", "description": "含所有景区门票", "sortOrder": 1}, - {"id": null, "feeType": "ACCOMMODATION", "name": "住宿", "source": "AUTO", "sortOrder": 2} - ], - "excludedFees": [ - {"id": null, "feeType": "PERSONAL", "name": "个人消费", "description": "如纪念品、零食等", "sortOrder": 1} - ], - "customFees": [], - "feeIgnoredTypes": [], - "childTicket": "FREE", - "childAccommodation": "NO_BED", - "childMeal": "HALF", - "elderTicket": "HALF_PRICE", - "elderAccommodation": "SAME_AS_ADULT", - "crowdBenefitTips": "12岁以下儿童门票免费", - "vehicleModelIds": [10, 11], - "vehicleRuleText": "5人以下推荐SUV，6-9人推荐商务车", - "bookingTermsId": 1, - "warmTipsId": 1, - "equipmentAdvice": "<p>必备：防晒霜、遮阳帽...</p>", - "insuranceNotice": "INCLUDED", - "insuranceSchemeId": 1, - "contractSchemeId": 1, - "quickUnderstand": {"text": "6天5晚，深入草原腹地...", "images": ["https://..."]}, - "childExperience": {"text": "骑马、射箭、挤牛奶...", "images": ["https://..."]}, - "growthGains": [ - {"dimension": "探索力", "description": "在辽阔草原培养探索精神"}, - {"dimension": "协作力", "description": "团队活动锻炼合作意识"} - ] -} -``` - -**费用推导预览响应**（进入Step5前先调用）： - -```json -[ - {"feeType": "TICKET", "name": "门票", "source": "AUTO", "sourceNodeName": "莫日格勒河观景台"}, - {"feeType": "ACCOMMODATION", "name": "住宿", "source": "AUTO", "sourceNodeName": "额尔古纳大酒店"} -] -``` - ---- - -### 页面7：产品线管理 - -``` -┌──────────────────────────────────────────────────┐ -│ [+ 新增产品线] │ -│ ┌──────┐ ┌──────┐ ┌──────┐ │ -│ │ 封面 │ │ 封面 │ │ 封面 │ │ -│ │ 名称 │ │ 名称 │ │ 名称 │ │ -│ │ 类型 │ │ 类型 │ │ 类型 │ │ -│ └──────┘ └──────┘ └──────┘ │ -└──────────────────────────────────────────────────┘ -``` - -**接口**： - -| 场景 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 产品线列表 | GET | `/admin/product/line/list` | 分页 | -| 创建产品线 | POST | `/admin/product/line` | 见下方请求 | -| 编辑产品线 | PUT | `/admin/product/line/{lineId}` | 同创建 | -| 删除产品线 | DELETE | `/admin/product/line/{lineId}` | 有产品时不可删 | -| 简单列表(下拉) | GET | `/admin/product/line/simple-list` | 返回 `[{lineId, name, productType}]` | - -**产品线创建/编辑请求**： - -```json -{ - "name": "额吉的故乡", - "description": "呼伦贝尔夏季亲子游", - "productType": "CORE", - "coverImageUrl": "https://...", - "seasons": ["summer", "autumn"], - "tags": ["亲子游", "深度游"] -} -``` - -**产品线列表响应字段**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| lineId | Long | 产品线ID | -| name | String | 名称 | -| description | String | 描述 | -| productType | String | 绑定的产品类型 | -| coverImageUrl | String | 封面图 | -| seasons | List\<String\> | 适用季节 | -| tags | List\<String\> | 产品线标签 | -| productCount | Integer | 旗下产品数量 | -| startPrice | BigDecimal | 起步价（旗下已上架产品最低成人价） | -| createTime | LocalDateTime | 创建时间 | - ---- - -## 三、C端（小程序）页面接口对照 - -### 页面1：主题精选页（产品线列表） - -**接口**：`GET /mp/product/line/list` -- 参数：productType(可选)、season(可选)、page、pageSize -- 返回：产品线卡片列表（name, description, coverImageUrl, startPrice, productType, seasons） - -### 页面2：产品列表（产品线下的产品） - -**接口**：`GET /mp/product/list` -- 参数：lineId(产品线ID)、tag(产品标签Tab)、page、pageSize -- 返回：产品卡片列表 - -**产品卡片关键字段**： - -```json -{ - "productId": 123, - "name": "额吉的故乡·亲子版", - "subtitle": "6天5晚草原环线", - "coverImageUrl": "https://...", - "tripDays": 6, - "productType": "CORE", - "tags": ["亲子", "研学"], - "startPrice": 3980, // 起步价(¥X起) - "startPriceLabel": "¥3980起/人" -} -``` - -### 页面3：产品详情页 - -**接口**：`GET /mp/product/{productId}` -- 返回：`MpProductDetailRespVO`（聚合全部展示数据） - -**返回结构**： - -```json -{ - "productId": 123, - "productType": "CORE", - "name": "额吉的故乡·亲子版", - "subtitle": "...", - "coverImageUrl": "...", - "carouselImages": ["...", "..."], - "tripDays": 6, - "tripNights": 5, - "routeMapUrl": "...", - "creatorAvatarUrl": "...", - "creatorIntro": "...", - - "itinerary": [ - { - "dayNumber": 1, - "dayTitle": "海拉尔→额尔古纳", - "description": "...", - "coverImageUrl": "...", - "breakfast": "HOTEL", - "lunch": "SELF", - "dinner": "SPECIAL", - "nodes": [ - { - "nodeType": "SCENIC", - "nodeName": "莫日格勒河观景台", - "startTime": "10:00", - "durationMinutes": 60, - "description": "..." - } - ] - } - ], - - "includedFees": [ - {"feeType": "TICKET", "name": "门票", "source": "AUTO"}, - {"feeType": "ACCOMMODATION", "name": "住宿", "source": "AUTO"} - ], - "excludedFees": [ - {"feeType": "PERSONAL", "name": "个人消费"} - ], - - "crowdBenefit": { - "childTicket": "FREE", - "childAccommodation": "NO_BED", - "childMeal": "HALF", - "elderTicket": "HALF_PRICE", - "tips": "..." - } -} -``` - -### 页面4：价格日历（弹窗） - -**接口**：`GET /mp/product/{productId}/price-calendar` -- 参数：month(yyyy-MM) -- 返回： - -```json -{ - "days": [ - { - "date": "2026-07-01", - "priceType": "PEAK", - "adultPrice": 4980, - "childPrice": 3980, - "isSelectable": true, // 连续N天有价格且有库存 - "remainStock": 8 // null=不限量 - } - ] -} -``` - -### 页面5：报价计算（选日期+人数后） - -**接口**：`POST /mp/product/{productId}/quote` - -**请求**： -```json -{ - "departureDate": "2026-07-01", - "adultCount": 2, - "childCount": 1, - "youngChildCount": 0, - "babyCount": 0, - "batchId": null, // 小蒙马传班期ID - "tierSeq": 1 // 多档时传档位序号 -} -``` - -**响应**： -```json -{ - "totalAdultPrice": 9960, - "totalChildPrice": 3980, - "grandTotal": 13940, - "dailyDetails": [ - {"date": "2026-07-01", "adultPrice": 4980, "childPrice": 3980}, - {"date": "2026-07-02", "adultPrice": 4980, "childPrice": 3980} - ], - "paymentType": "FULL", - "stock": 8, - "available": true -} -``` - -### 页面6：小蒙马班期列表（弹窗） - -**接口**：`GET /mp/product/{productId}/schedule/list` - -**返回**： -```json -[ - { - "batchId": 456, - "batchName": "第1期", - "departureDate": "2026-07-01", - "endDate": "2026-07-06", - "enrollmentDeadline": "2026-06-30", - "batchStatus": "ENROLLING", - "adultPrice": 4980, - "childPrice": 3980, - "maxParticipants": 20, - "enrolledCount": 8, - "maxRooms": 10, - "bookedRooms": 4 - } -] -``` - ---- - -## 四、字典值速查 - -| 字典 | 值 | 中文 | -|------|-----|------| -| product_type | CORE | 核心产品 | -| product_type | GROUP | 小蒙马跟团游 | -| product_type | CUSTOM | 私人定制 | -| product_status | DRAFT | 草稿 | -| product_status | PENDING_REVIEW | 待审核 | -| product_status | PUBLISHED | 已上架 | -| product_status | UNPUBLISHED | 已下架 | -| product_status | REJECTED | 已驳回 | -| product_status | COMPLETED | 已完成(定制) | -| product_status | ORDERED | 已下单(定制) | -| payment_type | FULL | 全款支付 | -| payment_type | DEPOSIT | 订金+尾款 | -| price_type | NORMAL | 平日 | -| price_type | PEAK | 旺季 | -| price_type | HOLIDAY | 节假日 | -| price_type | SPECIAL | 特价 | -| meal_option | HOTEL | 含(酒店) | -| meal_option | CAMP | 含(营地) | -| meal_option | SPECIAL | 含(特色餐) | -| meal_option | SELF | 自理 | -| schedule_status | ENROLLING | 报名中 | -| schedule_status | NEARLY_FULL | 即将满员 | -| schedule_status | FULL | 已满 | -| schedule_status | FINISHED | 已结束 | -| schedule_status | CANCELLED | 已取消 | -| insurance_notice | INCLUDED | 含保险 | -| insurance_notice | EXCLUDED | 不含保险 | -| insurance_notice | OPTIONAL | 可选升级 | - ---- - -## 五、与旧服务的切换说明 - -1. **管理端**：产品管理页面整体切换到v2接口，旧产品管理页面下线 -2. **C端**：小程序的产品列表/详情/报价/下单全部切换到v2接口 -3. **订单服务不改**：订单的Feign调用仍走旧接口（产品v2会兼容旧Feign路径） -4. **旧产品数据清空**：上线后旧产品数据全部删除，从零录入 - ---- - -## 六、联调注意事项 - -1. **所有保存接口都要传version**——忘传会返回400 -2. **行程整体保存**——不是一个节点一个接口，是整棵行程树一次提交（`PUT /itinerary`） -3. **价格区间制vs班期制**——看productType：CORE/CUSTOM用价格日历接口，GROUP用班期接口 -4. **多档位**——tierSeq从1开始递增，单一档位=1。价格日历和住宿都按tierSeq关联 -5. **小童价格特殊**——前端传的是优惠额（负数），实际小童价=儿童价-|优惠额| -6. **C端只展示PUBLISHED产品**——其他状态的产品C端接口不会返回 -7. **HTTP始终返回200**——业务错误通过 `Result.code` 区分，`code=0` 为成功，非0为失败，`msg` 为中文错误信息 -8. **产品详情接口**——GET `/admin/product/item/{id}` 一次返回全部5步数据（基础+行程+路线+价格+补充），前端按当前Step取对应部分回显 diff --git a/changelogs/2026-04/2026-04-13_product-v2_full_update.md b/changelogs/2026-04/2026-04-13_product-v2_full_update.md deleted file mode 100644 index f8955b1..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_full_update.md +++ /dev/null @@ -1,138 +0,0 @@ -# 产品v2 - 4月13日完整更新汇总 - -**日期**: 2026-04-13 -**服务**: product-service-v2 -**类型**: 新增接口 + bug修复 + 模块搬迁 -**PR**: #431, #433, #442, #446-#452 - ---- - -## 一、新增接口 - -### 1. 计算行程总里程 -`GET /admin/product/item/{productId}/calculate-mileage` - -根据行程途经点坐标调用高德驾车路线规划API自动计算总驾驶里程。 - -**返回**: `BigDecimal` 总里程(km)，1位小数 - ---- - -### 2. 计算建议售价 -`GET /admin/product/item/{productId}/suggest-price` - -根据备品成本+额外成本计算建议售价。有激活的公式组时走FormulaEngine计算。 - -**返回示例**: -```json -{ - "adultSuggestPrice": 220.0, - "childSuggestPrice": 70.0, - "formulaApplied": false, - "adultCost": { - "suppliesCost": 70.0, - "extraCost": 150.0, - "totalCost": 220.0, - "suppliesItems": [ - {"name": "防晒霜SPF50+", "unitPrice": 30.0, "quantity": 1, "subtotal": 30.0} - ], - "extraItems": [ - {"name": "骑马延时", "unitPrice": 150.0, "quantity": 1, "subtotal": 150.0} - ] - }, - "childCost": { ... } -} -``` - ---- - -### 3. 报价公式管理（从v1搬迁） -`/admin/product/formula/**` - -| 接口 | 方法 | 说明 | -|------|------|------| -| `/formula/group/list` | GET | 公式组列表 | -| `/formula/group/{groupId}` | GET | 公式组详情 | -| `/formula/group` | POST | 创建公式组 | -| `/formula/group/{groupId}` | PUT | 更新公式组 | -| `/formula/group/{groupId}/activate` | PUT | 激活公式组 | -| `/formula/group/{groupId}` | DELETE | 删除公式组 | -| `/formula/group/{groupId}/steps` | GET | 步骤列表 | -| `/formula/step/{formulaId}` | GET | 步骤详情 | -| `/formula/step` | POST | 创建步骤 | -| `/formula/step/{formulaId}` | PUT | 更新步骤 | -| `/formula/step/{formulaId}/toggle` | PUT | 启用/禁用 | -| `/formula/step/{formulaId}` | DELETE | 删除步骤 | -| `/formula/step/{formulaId}/versions` | GET | 版本历史 | -| `/formula/step/{formulaId}/rollback/{versionNum}` | PUT | 回滚版本 | -| `/formula/test` | POST | 测试执行 | -| `/formula/var/list` | GET | 变量列表 | -| `/formula/var` | POST | 创建变量 | -| `/formula/var/{varId}` | PUT | 更新变量 | -| `/formula/var/{varId}` | DELETE | 删除变量 | - ---- - -### 4. 温馨提示管理（从v1搬迁） -`/admin/product/warm-tips/**` - -| 接口 | 方法 | 说明 | -|------|------|------| -| `/warm-tips/list` | GET | 全部列表 | -| `/warm-tips/enabled` | GET | 启用列表（下拉用） | -| `/warm-tips/{tipsId}` | GET | 详情 | -| `/warm-tips` | POST | 创建 | -| `/warm-tips/{tipsId}` | PUT | 修改 | -| `/warm-tips/{tipsId}` | DELETE | 删除 | -| `/warm-tips/{tipsId}/toggle?enabled=true/false` | PUT | 启用/禁用 | - ---- - -### 5. 预订条款管理（从v1搬迁） -`/admin/product/booking-terms/**` - -接口结构同温馨提示，字段名 `tipsId` → `termsId`，`tipsName` → `termsName` - ---- - -## 二、Bug修复 - -### 1. 产品详情 routeInfo 返回 null（已修） -Step3保存的总里程/线路描述能存入DB但详情接口返回null。原因：SQL返回扁平字段，VO期望嵌套对象。 - -### 2. 详情返回JSON字段格式（已修） -- `photoUrls`: 之前返回 `"[\"url\"]"`（字符串），现在返回 `["url"]`（数组） -- `customFields`: 同上，字符串→对象 -- `images`（节点）: 同上 -- `extraData`（节点）: 同上 - -### 3. 详情返回审计字段（已修） -行程天/节点/住宿/路线点不再返回 `createTime`/`updateTime`/`createdBy`/`updatedBy`/`deletedAt` - -### 4. 行程保存事务失效（已修） -调用行程保存接口报500。原因：自调用@Transactional不生效。 - ---- - -## 三、全接口验证结果 - -| 接口 | 状态 | -|------|------| -| 产品线列表/下拉 | ✅ 200 | -| 产品分页列表 | ✅ 200 (7条) | -| 产品详情(4个产品) | ✅ 200, photoUrls=list, coverImg=Y, 审计字段=clean | -| Step1 基础信息保存 | ✅ 200 | -| Step2 行程保存 | ✅ 200 | -| Step3 路线与备品保存 | ✅ 200 | -| Step4 价格日历批量设置 | ✅ 200 | -| Step4 班期创建/修改/删除 | ✅ 200 | -| Step5 补充信息保存 | ✅ 200 | -| 里程计算 | ✅ 200 | -| 建议售价 | ✅ 200 | -| 报价计算 | ✅ 200 | -| 上架预检(4个) | ✅ 全部PASS | -| 费用推导预览 | ✅ 200 | -| 操作记录 | ✅ 200 | -| 温馨提示CRUD | ✅ 200 | -| 预订条款CRUD | ✅ 200 | -| 报价公式组/步骤/变量 | ✅ 200 | diff --git a/changelogs/2026-04/2026-04-13_product-v2_itinerary_sidebar_binding.md b/changelogs/2026-04/2026-04-13_product-v2_itinerary_sidebar_binding.md deleted file mode 100644 index 40e0ae1..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_itinerary_sidebar_binding.md +++ /dev/null @@ -1,50 +0,0 @@ -# 产品v2 - Step2行程编排左侧边栏数据绑定问题 - -**日期**: 2026-04-13 -**服务**: product-service-v2 -**类型**: 前端修复提醒 - ---- - -## 问题 - -Step2行程编排页面，左侧DAY列表全部显示"未命名"和"0活动·0km"，但右侧主内容区已正确显示行程数据（标题、描述、活动节点、餐饮安排等）。 - -## 原因 - -左侧边栏组件没有从接口返回数据中读取对应字段。 - -## 后端返回数据结构（已确认正确） - -`GET /admin/product/item/{productId}` 返回的 `itinerary` 数组中每个天对象： - -```json -{ - "dayId": "2043611210854596610", - "dayNumber": 1, - "dayTitle": "海拉尔集合", // ← 左侧DAY标题应读这个 - "description": "抵达海拉尔，入住酒店，领队接站", - "quoteText": "让草原的风，吹散一切疲惫", - "dailyMileage": 120, // ← 左侧里程应读这个 - "breakfast": "SELF", - "lunch": "SELF", - "dinner": "HOTEL", - "nodes": [ // ← 左侧活动数 = nodes.length - {"nodeId": "xxx", "nodeName": "海拉尔机场接站", "nodeType": "SERVICE", ...}, - {"nodeId": "xxx", "nodeName": "入住酒店", "nodeType": "HOTEL", ...}, - {"nodeId": "xxx", "nodeName": "自由探索海拉尔", "nodeType": "FREE", ...} - ], - "hotels": [...], - "routePoints": [...] -} -``` - -## 前端需要修改 - -左侧DAY列表每项应绑定： - -| 显示内容 | 数据来源 | -|---------|---------| -| DAY标题（当前显示"未命名"） | `itinerary[i].dayTitle` | -| 活动数（当前显示"0活动"） | `itinerary[i].nodes.length` | -| 里程（当前显示"0km"） | `itinerary[i].dailyMileage`（单位km，可能为null） | diff --git a/changelogs/2026-04/2026-04-13_product-v2_line_json_fix.md b/changelogs/2026-04/2026-04-13_product-v2_line_json_fix.md deleted file mode 100644 index 31454f9..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_line_json_fix.md +++ /dev/null @@ -1,33 +0,0 @@ -# 接口变更记录 — 2026-04-13 - -> **变更类型**：BUG修复 -> **影响接口**：产品线分页列表、产品线详情 - ---- - -## 产品线 seasons/tags 返回格式修复 - -### 问题 - -产品线列表和详情接口的 `seasons` 和 `tags` 字段返回的是 JSON 字符串而非数组： - -```json -// 修复前（错误） -"seasons": "[\"spring\", \"summer\", \"autumn\", \"winter\"]", -"tags": "[\"自驾\", \"高原\", \"摄影\", \"可亲\"]" - -// 修复后（正确） -"seasons": ["spring", "summer", "autumn", "winter"], -"tags": ["自驾", "高原", "摄影", "可亲"] -``` - -### 影响接口 - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/line/list` | 产品线分页列表 | -| GET | `/admin/product/line/{lineId}` | 产品线详情 | - -### 修复状态 - -代码已修复，等待下次部署生效。 diff --git a/changelogs/2026-04/2026-04-13_product-v2_list_add_tierCount.md b/changelogs/2026-04/2026-04-13_product-v2_list_add_tierCount.md deleted file mode 100644 index 90cb910..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_list_add_tierCount.md +++ /dev/null @@ -1,84 +0,0 @@ -# 接口变更记录 — 2026-04-13 - -> **变更类型**：字段新增 -> **影响接口**：`GET /admin/product/item/list` -> **在线文档**： -> - 局域网：http://192.168.100.236:8080/doc.html → `1. 管理端 - 产品管理` -> - 公网：https://api.test.1814.love:9443/doc.html（需认证） - ---- - -## 产品列表新增 `tierCount` 字段 - -产品分页列表接口响应中**新增 `tierCount` 字段**，表示该产品的档位数量。 - -### 接口信息 - -- **方法**：`GET /admin/product/item/list` -- **用途**：管理端产品分页列表 - -### 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `tierCount` | `Integer` | 档位数量。单一档位=1，多档=N（如舒适+豪华=2） | - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "total": 514, - "records": [ - { - "productId": 2043246204711550977, - "productNo": "C2604121836", - "productType": "CORE", - "name": "额吉的故乡·亲子版", - "coverImageUrl": "https://...", - "tripDays": 6, - "status": "PUBLISHED", - "version": 3, - "tierCount": 2, - "createBy": 1002, - "publishedAt": "2026-04-12T16:33:51", - "createTime": "2026-04-12T16:29:40", - "updateTime": "2026-04-12T16:33:51" - } - ] - } -} -``` - -### 使用场景 - -产品列表卡片上展示档位信息，如「2个档位」或档位标签「舒适/豪华」。`tierCount=1` 时可不展示（单一档位无需区分）。 - ---- - -## 同步修复：分页问题已修复 - -之前产品列表 `total` 返回0、一次返回全部数据的问题已修复（PR #325）。现在分页正常：`total` 返回正确总数，`records` 只返回当前页数据。 - ---- - -## 补充说明：创建产品 vs Step1 基础信息 - -这是**两个接口**，使用场景不同： - -| 接口 | 方法 | 路径 | 用途 | -|------|------|------|------| -| 创建产品 | POST | `/admin/product/item` | 弹窗中填最少信息（名称+类型+产品线+天数），快速创建草稿拿到productId | -| Step1保存 | PUT | `/admin/product/item/{id}/basic` | 进入编辑页后，保存全部基础信息（37个字段） | - -**前端使用流程**： -1. 点「新建产品」→ 弹窗填4个字段 → 调 `POST /admin/product/item` → 拿到 `productId` -2. 自动跳转到编辑页 Step1 → 填写完整信息 → 调 `PUT /admin/product/item/{id}/basic` - -两个接口的请求体不同： -- 创建：`ProductSaveReqVO`（name, productType, lineId, tripDays） -- Step1：`ProductBasicSaveReqVO`（37个字段，含version乐观锁） - -**不需要调两次保存同样的信息**——创建只是"开个头"拿ID，Step1才是真正保存基础信息。 diff --git a/changelogs/2026-04/2026-04-13_product-v2_remove_version.md b/changelogs/2026-04/2026-04-13_product-v2_remove_version.md deleted file mode 100644 index 92e86b2..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_remove_version.md +++ /dev/null @@ -1,59 +0,0 @@ -# 接口变更记录 — 2026-04-13 （重要） - -> **变更类型**：字段删除 -> **影响范围**：所有保存接口 - ---- - -## 去掉version字段，前端不再需要传 - -### 删除的字段 - -以下接口的请求参数中 `version` 字段已删除，**前端不需要传version了**： - -| 接口 | 方法 | 路径 | -|------|------|------| -| Step1 基础信息保存 | POST | `/admin/product/item/basic` | -| Step2 行程保存 | PUT | `/admin/product/item/{id}/itinerary` | -| Step3 路线与备品保存 | PUT | `/admin/product/item/{id}/route` | -| Step4 价格日历批量设置 | POST | `/admin/product/item/{id}/price-calendar/batch` | -| Step4 价格日历删除 | DELETE | `/admin/product/item/{id}/price-calendar` | -| Step5 补充信息保存 | PUT | `/admin/product/item/{id}/supplement` | - -### 响应中也删除了version - -- 产品列表 `GET /admin/product/item/list` — 不再返回 `version` 字段 -- 产品详情 `GET /admin/product/item/{id}` — 不再返回 `version` 和 `priceVersion` 字段 - -### Step1返回值恢复为Long - -```json -// POST /admin/product/item/basic 响应 -{ - "code": 200, - "message": "成功", - "data": 2043574976048476162 // 产品ID（Long） -} -``` - -之前改成了返回 `{productId, version}` 的Map，现在恢复为直接返回 `Long` 类型的产品ID。 - -### 同时变更：产品线删除加了关联校验 - -`DELETE /admin/product/line/{lineId}` — 如果产品线下有产品（版本），返回错误提示，不允许删除。 - ---- - -## 补充：productId返回类型说明 - -Step1接口 `POST /admin/product/item/basic` 返回的 `data` 是 Long 类型的产品ID，但经过全局Jackson序列化后**自动转为字符串**（防止JS精度丢失）： - -```json -{ - "code": 200, - "message": "成功", - "data": "2043595307274436609" // 字符串，不是数字 -} -``` - -前端直接用这个字符串做后续请求的productId参数即可。 diff --git a/changelogs/2026-04/2026-04-13_product-v2_step3_cleanup.md b/changelogs/2026-04/2026-04-13_product-v2_step3_cleanup.md deleted file mode 100644 index dff5ca5..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_step3_cleanup.md +++ /dev/null @@ -1,29 +0,0 @@ -# 接口变更记录 — 2026-04-13 - -> **变更类型**：字段删除 + 新增接口 + BUG修复 - ---- - -## 一、Step3 路线与备品保存 — 删除3个字段 - -`PUT /admin/product/item/{id}/route` 删除以下字段，前端不要传： - -| 字段 | 原因 | -|------|------| -| ~~routeName~~（路线名称） | 不需要 | -| ~~vehicleModelId~~（实际用车车型ID） | 改到Step5车辆展示，加类型标记 | -| ~~staffCostIds~~（服务人员成本ID列表） | 改到团期管理 | - -## 二、新增接口：行政区划搜索 - -`GET /admin/product/district/search?keywords=海拉尔` - -从旧产品服务搬迁到v2，接口路径不变。返回匹配的城市/区县/镇列表。 - -## 三、BUG修复：Step2/3/4/5保存报400 - -之前删version字段时残留了`@NotNull`校验注解，导致4个保存接口报400。已修复： -- Step2 行程保存 -- Step3 路线与备品保存 -- Step4 价格日历批量设置 -- Step5 补充信息保存 diff --git a/changelogs/2026-04/2026-04-13_product-v2_total_mileage_auto_calc.md b/changelogs/2026-04/2026-04-13_product-v2_total_mileage_auto_calc.md deleted file mode 100644 index 282f02e..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_total_mileage_auto_calc.md +++ /dev/null @@ -1,55 +0,0 @@ -# 产品v2 - 总里程自动累加逻辑 - -**日期**: 2026-04-13 -**服务**: product-service-v2 -**类型**: 前端功能提醒 - ---- - -## 需求 - -Step3"路线与备品"页面的**总里程**应自动累加各天里程，同时允许手动修改覆盖。 - -## 逻辑 - -``` -总里程 = SUM(每天的 dailyMileage) -``` - -- 默认自动累加 Step2 各天的 `dailyMileage` 值（可能为 null，按 0 处理） -- 用户可手动修改总里程，修改后不再自动覆盖（或提供重置按钮恢复自动计算） - -## 相关字段 - -| 位置 | 字段 | 说明 | -|------|------|------| -| Step2 行程天 | `itinerary[].dailyMileage` | 每日里程(km)，可能为null | -| Step3 路线总览 | `totalMileage` | 总里程(km)，保存时传给后端 | - -## 数据来源 - -`GET /admin/product/item/{productId}` 返回： - -```json -{ - "itinerary": [ - {"dayNumber": 1, "dailyMileage": null}, - {"dayNumber": 2, "dailyMileage": 120}, - {"dayNumber": 3, "dailyMileage": 160}, - {"dayNumber": 4, "dailyMileage": 200}, - {"dayNumber": 5, "dailyMileage": 220}, - {"dayNumber": 6, "dailyMileage": 200} - ], - "routeInfo": { - "totalMileage": 900, - "routeDescription": "...", - "routeMapUrl": "..." - } -} -``` - -自动计算：120 + 160 + 200 + 220 + 200 = **900 km** - -## 保存 - -`PUT /admin/product/item/{productId}/route` 请求体中 `totalMileage` 传最终值（不管是自动算的还是手动改的），后端只存不算。 diff --git a/changelogs/2026-04/2026-04-13_product-v2_vehicle_auto_match.md b/changelogs/2026-04/2026-04-13_product-v2_vehicle_auto_match.md deleted file mode 100644 index 1afc5d1..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_vehicle_auto_match.md +++ /dev/null @@ -1,34 +0,0 @@ -# 产品v2 - 车辆自动匹配规则变更 - -**日期**: 2026-04-13 -**服务**: product-service-v2 / resource-service -**类型**: 需求变更 - ---- - -## 变更内容 - -产品不再手动选择车辆，改为按产品类型自动匹配计价用车。 - -### 匹配规则 - -| 产品类型(productType) | 自动匹配车辆 | vehicle_type | -|----------------------|-------------|-------------| -| CORE（核心产品） | 专用车 | CORE_PRODUCT | -| CUSTOM（私人定制） | 专用车 | CORE_PRODUCT | -| GROUP（小蒙马） | 小蒙马车 | GROUP | - -### 字典更新（vehicle_type） - -新增/启用了两个值： - -| dict_value | dict_label | 说明 | -|-----------|-----------|------| -| CORE_PRODUCT | 核心产品专用 | 原已存在但未启用，现已启用 | -| GROUP | 小蒙马专用 | 新增 | - -### 前端影响 - -1. **产品编辑页**：不再需要"选择车辆"相关UI，产品不存 vehicleModelId -2. **车型管理页**：车型分类下拉新增了"核心产品专用"和"小蒙马专用"两个选项 -3. **价格计算**：后端根据 productType 自动查找对应 vehicle_type 的启用车辆，前端无需传车辆信息 diff --git a/changelogs/2026-04/2026-04-13_product-v2_version_flow.md b/changelogs/2026-04/2026-04-13_product-v2_version_flow.md deleted file mode 100644 index 3869066..0000000 --- a/changelogs/2026-04/2026-04-13_product-v2_version_flow.md +++ /dev/null @@ -1,37 +0,0 @@ -# 接口使用提醒 — 2026-04-13 - -> **问题**：保存行程/路线/补充信息时报"数据已被其他人修改" -> **原因**：version版本号不匹配 - ---- - -## version版本号使用规则 - -每次保存操作都会让version+1。前端**必须始终使用最新的version**。 - -### 正确流程 - -``` -1. 创建产品（POST /admin/product/item/basic，不传version） - → 返回 productId - → 此时数据库 version=1（创建+保存基础信息各+1） - -2. 获取详情（GET /admin/product/item/{id}） - → 拿到最新 version（如1） - -3. 保存行程（PUT /admin/product/item/{id}/itinerary） - → 传 version=1（从详情拿到的） - → 成功后 version 变成 2 - -4. 保存路线（PUT /admin/product/item/{id}/route） - → 传 version=2 - → 成功后 version 变成 3 - -5. 以此类推... -``` - -### 关键点 - -- **每次保存前先获取详情拿最新version**，或者保存成功后前端本地version+1 -- **不能固定传version=0**，那是创建时的初始值，创建完就变了 -- 版本冲突时前端应提示用户刷新页面重新编辑 diff --git a/changelogs/2026-04/2026-04-14_0003_18951827_fix_product-v2_Ste.md b/changelogs/2026-04/2026-04-14_0003_18951827_fix_product-v2_Ste.md deleted file mode 100644 index 330c772..0000000 --- a/changelogs/2026-04/2026-04-14_0003_18951827_fix_product-v2_Ste.md +++ /dev/null @@ -1,25 +0,0 @@ -# 接口变更记录 — 2026-04-14 00:03 - -> **提交** `18951827` · **作者** wx · **时间** 2026-04-14 00:03:25 +0800 -> -> fix(product-v2): Step1缺少seasons/carouselImages字段+创建时字段丢失 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductBasicSaveReqVO - - - 🆕 `carouselImages` (`List<String>`) — 轮播图URL列表 - - 🆕 `seasons` (`List<String>`) — 产品季节（字典product_season: spring/summer/autumn/winter） - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_0015_eb0ad987_fix_product-v2.md b/changelogs/2026-04/2026-04-14_0015_eb0ad987_fix_product-v2.md deleted file mode 100644 index 02775d2..0000000 --- a/changelogs/2026-04/2026-04-14_0015_eb0ad987_fix_product-v2.md +++ /dev/null @@ -1,32 +0,0 @@ -# 接口变更记录 — 2026-04-14 00:15 - -> **提交** `eb0ad987` · **作者** wx · **时间** 2026-04-14 00:15:12 +0800 -> -> fix(product-v2): 详情接口补全Step1基础扩展+Step5补充配置+人群优惠字段 - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ ProductDetailRespVO - - - 🆕 `balanceDueDays` (`Integer`) — 尾款截止天数 - - 🆕 `defaultDailyStock` (`Integer`) — 每日库存默认值 - - 🆕 `defaultRoomCount` (`Integer`) — 默认房间数 - - ❌ ~~`infantAgeMax`~~ (`Integer`) — 幼童年龄上限 - - ❌ ~~`toddlerAgeMax`~~ (`Integer`) — 小童年龄上限 - - ❌ ~~`childAgeMin`~~ (`Integer`) — 儿童年龄下限 - - ❌ ~~`childAgeMax`~~ (`Integer`) — 儿童年龄上限 - - ❌ ~~`showReview`~~ (`Boolean`) — 展示评价 - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductQueryService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_0035_d82992d7_refactor_product-v2.md b/changelogs/2026-04/2026-04-14_0035_d82992d7_refactor_product-v2.md deleted file mode 100644 index ba4651f..0000000 --- a/changelogs/2026-04/2026-04-14_0035_d82992d7_refactor_product-v2.md +++ /dev/null @@ -1,54 +0,0 @@ -# 接口变更记录 — 2026-04-14 00:35 - -> **提交** `d82992d7` · **作者** wx · **时间** 2026-04-14 00:35:19 +0800 -> -> refactor(product-v2): 代码审核修复(VO ID类型+事务+Controller规范) - -## 变更总览 - - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### ✏️ FormulaGroupRespVO - - - ✏️ `groupId`: 类型 `String` → `Long` - -#### ✏️ FormulaStepRespVO - - - ✏️ `formulaId`: 类型 `String` → `Long` - - ✏️ `groupId`: 类型 `String` → `Long` - -#### ✏️ FormulaVarRespVO - - - ✏️ `varId`: 类型 `String` → `Long` - -#### ✏️ FormulaVersionRespVO - - - ✏️ `versionId`: 类型 `String` → `Long` - - ✏️ `formulaId`: 类型 `String` → `Long` - - ✏️ `changedBy`: 类型 `String` → `Long` - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminBookingTermsController.java -M hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminWarmTipsController.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/BookingTermsService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaGroupService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaStepService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaVarService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/WarmTipsService.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaGroupRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaStepRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVarRespVO.java -M hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVersionRespVO.java -M hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/FormulaGroupServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_0945_f3151227_refactor_product-v2.md b/changelogs/2026-04/2026-04-14_0945_f3151227_refactor_product-v2.md deleted file mode 100644 index a6484b3..0000000 --- a/changelogs/2026-04/2026-04-14_0945_f3151227_refactor_product-v2.md +++ /dev/null @@ -1,2343 +0,0 @@ -# 接口变更记录 — 2026-04-14 09:45 - -> **提交** `f3151227` · **作者** wx · **时间** 2026-04-14 09:45:04 +0800 -> -> refactor(product-v2): 包名com.hulalv.product→com.hulalv(去掉product子包) - -## 变更总览 - -- **hl-product-service-v2** - - 🆕 AdminBookingTerms (+7 接口) - - 🆕 AdminProduct (+30 接口) - - 🆕 AdminProductLine (+5 接口) - - 🆕 AdminProductTemplate (+1 接口) - - 🆕 AdminWarmTips (+7 接口) - - 🆕 District (+1 接口) - - 🆕 Formula (+19 接口) - - 🆕 MpProduct (+6 接口) - - 🆕 MpProductLine (+2 接口) - - ❌ AdminBookingTerms (-7 接口) - - ❌ AdminProductLine (-5 接口) - - ❌ AdminProductTemplate (-1 接口) - - ❌ AdminWarmTips (-7 接口) - - ❌ District (-1 接口) - - ❌ Formula (-19 接口) - - ❌ MpProduct (-6 接口) - - ❌ MpProductLine (-2 接口) - - 🆕 AdminProductLineTest (+0 接口) - - 🆕 AdminProductTemplateTest (+0 接口) - - 🆕 MpProductTest (+0 接口) - - 🆕 MpProductLineTest (+0 接口) - - ❌ AdminProductLineTest (-0 接口) - - ❌ AdminProductTemplateTest (-0 接口) - - ❌ MpProductTest (-0 接口) - - ❌ MpProductLineTest (-0 接口) - ---- - -## hl-product-service-v2 - -### 🆕 新增: AdminBookingTerms - -### 📌 `GET` /admin/product/booking-terms/list — 预订条款列表 - -> 返回所有预订条款（含禁用），按创建时间倒序 - -**响应** `Result<List<BookingTermsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/booking-terms/enabled — 启用的预订条款列表 - -> 仅返回启用状态的条款，供产品设计时选择 - -**响应** `Result<List<BookingTermsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/booking-terms/{termsId} — 预订条款详情 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - -**响应** `Result<BookingTermsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/booking-terms — 创建预订条款 - -> 创建后默认启用 - -**请求体** `BookingTermsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<BookingTermsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/booking-terms/{termsId} — 修改预订条款 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - -**请求体** `BookingTermsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<BookingTermsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 预订条款ID | -| `termsName` | `String` | 条款名称 | -| `content` | `String` | 条款内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/product/booking-terms/{termsId} — 删除预订条款 - -> 软删除，已绑定的产品不受影响 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/booking-terms/{termsId}/toggle — 启用/禁用预订条款 - -> 禁用后不再出现在产品设计的可选列表中 - -**参数** - - - `{termsId}` (`Long`) — 路径参数：预订条款ID - - `enabled` (`boolean`) — 查询参数：是否启用 - -**响应** `Result<Void>` - -### 🆕 新增: AdminProduct - -### 📌 `POST` /admin/product/item/basic — Step1 基础信息保存 - -> 创建+更新合一接口。 - -**请求体** `ProductBasicSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID（不传=创建，传了=更新） | -| `productType` | `String` | 产品类型（创建时必传，更新时忽略。CORE=核心产品, GROUP=小蒙马, CUSTOM=私人定制） | -| `category` | `String` | 产品分类（字典product_category: family=亲子游, honeymoon=蜜月旅行, photography=摄影之旅, experience=深度体验, driving=自驾越野） | -| `name` | `String` | 产品名称（≤30字） | -| `subtitle` | `String` | 副标题（≤128字） | -| `introduction` | `String` | 产品简介（富文本HTML） | -| `lineId` | `Long` | 产品线ID（主题ID，CORE/GROUP必传，CUSTOM可空） | -| `tripDays` | `Integer` | 行程天数（≥1） | -| `tripNights` | `Integer` | 行程晚数（不传自动=天数-1） | -| `isBooking` | `Boolean` | 是否预约产品（true=订金可不填出行人） | -| `paymentType` | `String` | 支付方式（FULL=全款支付, DEPOSIT=订金+尾款） | -| `depositRatio` | `Integer` | 订金比例(%，与固定额二选一） | -| `depositAmount` | `BigDecimal` | 订金固定额（与比例二选一） | -| `balanceDueDays` | `Integer` | 尾款须在出发前N天付清 | -| `defaultDailyStock` | `Integer` | 每日库存默认值（NULL=不限量，用于价格日历预填） | -| `tiers` | `List<TierItem>` | 规格列表（单一档不传或传1个，多档传多个） | -| `tags` | `List<String>` | 产品标签（亲子/研学/露营/城记/摄影） | -| `coverImageUrl` | `String` | 封面图URL | -| `carouselImages` | `List<String>` | 轮播图URL列表 | -| `seasons` | `List<String>` | 产品季节（字典product_season: spring/summer/autumn/winter） | -| `tierSeq` | `Integer` | 规格序号（1开始递增） | -| `tierName` | `String` | 规格名称 | - -**响应** `Result<Long>` - -### 📌 `PUT` /admin/product/item/{id}/itinerary — Step2 行程整体保存 - -> 整体保存行程天+节点+住宿+路线点。支持新增/更新/删除（EntityDiffUtil对比）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductItinerarySaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `days` | `List<DayItem>` | 行程天列表 | -| `dayId` | `Long` | 行程天ID(已有则传，新增不传) | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 当日标题 | -| `quoteText` | `String` | 当日金句 | -| `description` | `String` | 行程描述 | -| `coverImageUrl` | `String` | 当日封面图 | -| `breakfast` | `String` | 早餐(HOTEL/CAMP/SPECIAL/SELF) | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `diningRemark` | `String` | 餐饮备注 | -| `dailyMileage` | `BigDecimal` | 当日里程(km) | -| `mileageManualOverride` | `Boolean` | 里程是否手动覆盖 | -| `photoUrls` | `List<String>` | 照片集 | -| `customFields` | `Object` | 自定义概况 | -| `nodes` | `List<NodeItem>` | 活动节点列表 | -| `hotels` | `List<HotelItem>` | 住宿列表 | -| `routePoints` | `List<RoutePointItem>` | 途经路线点列表 | -| `nodeId` | `Long` | 节点ID(已有则传，新增不传) | -| `sortOrder` | `Integer` | 排序 | -| `nodeType` | `String` | 节点类型(SCENIC/ACTIVITY/RESTAURANT/SERVICE/CUSTOM等) | -| `nodeName` | `String` | 节点名称 | -| `resourceType` | `String` | 资源类型 | -| `resourceId` | `Long` | 资源ID | -| `startTime` | `String` | 开始时间(如10:00) | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `images` | `List<String>` | 图片列表 | -| `emojiIcon` | `String` | 图标 | -| `extraData` | `Object` | 扩展数据 | -| `id` | `Long` | 住宿ID(已有则传，新增不传) | -| `tierSeq` | `Integer` | 档位序号(无档位=1) | -| `hotelId` | `Long` | 酒店ID | -| `roomTypeId` | `Long` | 房型ID(私人定制用) | -| `roomCount` | `Integer` | 房间数(私人定制用) | -| `isDefault` | `Boolean` | 是否默认推荐 | -| `sortOrder` | `Integer` | 排序 | -| `resourceId` | `Long` | 资源ID(可空=自定义地点) | -| `name` | `String` | 地点名称 | -| `longitude` | `BigDecimal` | 经度 | -| `latitude` | `BigDecimal` | 纬度 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/itinerary/day — Step2 增加一天 - -> 在行程末尾追加一天，自动编号。返回新天的dayId。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Long>` - -### 📌 `DELETE` /admin/product/item/{id}/itinerary/day/{dayNumber} — Step2 删除一天 - -> 删除指定天序号的行程天，级联删除节点+住宿+路线点，后续天序号自动-1。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `{dayNumber}` (`Integer`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/item/{id}/route — Step3 路线与备品保存 - -> 保存路线总览(1:1)+备品清单(1:N)+额外成本项(1:N)。备品和成本项支持增删改。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductRouteSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `routeMapUrl` | `String` | 路线图URL(手动上传) | -| `totalMileage` | `BigDecimal` | 总里程(km) | -| `routeDescription` | `String` | 线路描述 | -| `supplies` | `List<SuppliesItem>` | 备品列表 | -| `extraCosts` | `List<FeeItem>` | 额外成本项列表 | -| `id` | `Long` | 备品ID(已有则传，新增不传) | -| `suppliesResourceId` | `Long` | 备品资源ID(可空=自定义) | -| `suppliesName` | `String` | 备品名称 | -| `category` | `String` | 分类 | -| `hasCost` | `Boolean` | 是否涉及成本 | -| `billingType` | `String` | 计费方式(PER_PERSON/PER_QUANTITY) | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `sortOrder` | `Integer` | 排序 | -| `id` | `Long` | 费用项ID(已有则传，新增不传) | -| `resourceType` | `String` | 资源类型 | -| `resourceId` | `Long` | 资源ID | -| `costItemId` | `Long` | 费用项ID | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `daily` | `Boolean` | 是否按天计费 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/price-calendar — Step4 查询价格日历 - -> 按月份查询价格日历。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<ProductPriceCalendarDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | | -| `productId` | `Long` | | -| `tierSeq` | `Integer` | | -| `rangeId` | `Long` | | -| `date` | `LocalDate` | | -| `priceType` | `String` | | -| `adultSellPrice` | `BigDecimal` | | -| `childSellPrice` | `BigDecimal` | | -| `toddlerDiscount` | `BigDecimal` | | -| `infantPrice` | `BigDecimal` | | -| `dailyStock` | `Integer` | | -| `sold` | `Integer` | | - -### 📌 `GET` /admin/product/item/{id}/schedule/list — Step4 班期列表 - -> 查询产品下所有班期。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<GroupTourBatchDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | | -| `productId` | `Long` | | -| `batchNo` | `String` | | -| `batchLabel` | `String` | | -| `batchName` | `String` | | -| `productStockLimit` | `Integer` | | -| `adultPrice` | `BigDecimal` | | -| `childPrice` | `BigDecimal` | | -| `toddlerDiscount` | `BigDecimal` | | -| `infantPrice` | `BigDecimal` | | -| `departureDate` | `LocalDate` | | -| `endDate` | `LocalDate` | | -| `enrollmentDeadline` | `LocalDate` | | -| `maxParticipants` | `Integer` | | -| `enrolledCount` | `Integer` | | -| `maxRooms` | `Integer` | | -| `bookedRooms` | `Integer` | | -| `batchStatus` | `String` | | -| `sortOrder` | `Integer` | | -| `remark` | `String` | | -| `version` | `Integer` | | - -### 📌 `POST` /admin/product/item/{id}/price-calendar/batch — Step4 价格日历批量设置 - -> 按日期范围+档位批量设置价格（UPSERT）。已上架产品用priceVersion，草稿用version。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `PriceCalendarBatchReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `tierSeq` | `Integer` | 档位序号(默认1) | -| `priceType` | `String` | 价格类型(字典price_type: NORMAL=平日, PEAK=旺季, HOLIDAY=节假日, SPECIAL=特价) | -| `adultSellPrice` | `BigDecimal` | 成人售价 | -| `childSellPrice` | `BigDecimal` | 儿童售价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童售价(0=免费) | -| `dailyStock` | `Integer` | 每日库存上限(NULL=不限量) | - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/product/item/{id}/price-calendar — Step4 价格日历删除 - -> 按日期范围+档位删除价格日历（物理删除）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `PriceCalendarBatchReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `tierSeq` | `Integer` | 档位序号(默认1) | -| `priceType` | `String` | 价格类型(字典price_type: NORMAL=平日, PEAK=旺季, HOLIDAY=节假日, SPECIAL=特价) | -| `adultSellPrice` | `BigDecimal` | 成人售价 | -| `childSellPrice` | `BigDecimal` | 儿童售价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童售价(0=免费) | -| `dailyStock` | `Integer` | 每日库存上限(NULL=不限量) | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/schedule — Step4 创建班期 - -> 创建新班期，batchId不传。自动生成班期编号、计算结束日期和报名截止日。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID(修改时传) | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `enrollmentDeadline` | `LocalDate` | 报名截止日(默认出发前1天) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数(0=不限) | -| `productStockLimit` | `Integer` | 产品库存上限 | -| `remark` | `String` | 备注 | - -**响应** `Result<Long>` - -### 📌 `DELETE` /admin/product/item/{id}/schedule/{scheduleId} — Step4 删除班期 - -> 删除班期（已有报名订单不允许删除）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `{scheduleId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/item/{id}/schedule — Step4 修改班期 - -> 修改已有班期，batchId在body中传。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID(修改时传) | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `LocalDate` | 出发日期 | -| `enrollmentDeadline` | `LocalDate` | 报名截止日(默认出发前1天) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `toddlerDiscount` | `BigDecimal` | 小童优惠额(负数) | -| `infantPrice` | `BigDecimal` | 幼童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数(0=不限) | -| `productStockLimit` | `Integer` | 产品库存上限 | -| `remark` | `String` | 备注 | - -**响应** `Result<Long>` - -### 📌 `POST` /admin/product/item/{id}/schedule/batch-create — Step4 班期批量创建 - -> 按重复模式批量创建班期（最多52个，跨度≤12个月）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleBatchCreateReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `startDate` | `LocalDate` | 开始日期 | -| `endDate` | `LocalDate` | 结束日期 | -| `repeatMode` | `String` | 重复模式(WEEKLY/BIWEEKLY/MONTHLY) | -| `dayOfWeek` | `Integer` | 星期几(1=周一...7=周日) | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `maxRooms` | `Integer` | 总房间数 | - -**响应** `Result<Integer>` - -### 📌 `POST` /admin/product/item/{id}/schedule/{scheduleId}/cancel — Step4 取消班期 - -> 取消班期（有报名订单则标记为CANCELLING触发退款，无订单直接CANCELLED）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `{scheduleId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/schedule/team — 班期团队查询 - -> 查询指定班期的团队成员列表。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<GroupBatchStaffDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | | -| `batchId` | `Long` | | -| `productId` | `Long` | | -| `staffId` | `Long` | | -| `staffRole` | `String` | | -| `staffName` | `String` | | -| `staffPhone` | `String` | | -| `remark` | `String` | | -| `sortOrder` | `Integer` | | - -### 📌 `PUT` /admin/product/item/{id}/schedule/team — 班期团队保存 - -> 全量保存班期团队成员（全删全插策略，每次传完整列表）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ScheduleTeamSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `staffList` | `List<StaffItem>` | 团队成员列表 | -| `staffId` | `Long` | 员工ID | -| `staffRole` | `String` | 员工角色 | -| `staffName` | `String` | 员工名称 | -| `staffPhone` | `String` | 员工电话 | -| `remark` | `String` | 备注 | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/suggest-price — 建议售价 - -> 根据出发日期+档位，汇总行程天数内价格日历单价+备品+额外成本，返回成人/儿童建议售价。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - - `departureDate` (`String`) — 查询参数 - - `tierSeq` (`Integer`) — 查询参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /admin/product/item/{id}/quote — 报价计算 - -> 根据出发日期+人数+档位计算总价，返回每日明细。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `QuoteReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `departureDate` | `LocalDate` | 出发日期 | -| `adultCount` | `Integer` | 成人数 | -| `batchId` | `Long` | 班期ID(小蒙马用) | - -**响应** `Result<QuoteResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `totalAdultPrice` | `BigDecimal` | 成人总价 | -| `totalChildPrice` | `BigDecimal` | 儿童总价 | -| `grandTotal` | `BigDecimal` | 总价合计 | -| `dailyDetails` | `List<DailyDetail>` | 每日价格明细 | -| `date` | `String` | 日期 | -| `adultPrice` | `BigDecimal` | 成人日价 | -| `childPrice` | `BigDecimal` | 儿童日价 | - -### 📌 `PUT` /admin/product/item/{id}/supplement — Step5 补充信息保存 - -> 保存费用包含/不含/自定义项+人群优惠+补充配置（退改/车辆/保险/卖点等）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductSupplementSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `includedFees` | `List<FeeItem>` | 费用包含列表 | -| `excludedFees` | `List<FeeItem>` | 费用不含列表 | -| `customFees` | `List<FeeItem>` | 自定义费用列表 | -| `feeIgnoredTypes` | `List<String>` | 费用推导已忽略类型 | -| `childTicket` | `String` | 儿童门票优惠(FREE/HALF_PRICE/FULL_PRICE) | -| `childAccommodation` | `String` | 儿童住宿(BED/NO_BED) | -| `childMeal` | `String` | 儿童餐饮(FULL/HALF) | -| `elderTicket` | `String` | 老人门票优惠 | -| `elderAccommodation` | `String` | 老人住宿 | -| `crowdBenefitTips` | `String` | 人群优惠温馨提示 | -| `vehicleModelIds` | `List<Long>` | 展示车型ID列表 | -| `vehicleRuleText` | `String` | 用车规则说明 | -| `refundPolicyIds` | `Object` | 退改政策映射 | -| `bookingTermsId` | `Long` | 预订条款ID | -| `warmTipsId` | `Long` | 温馨提示ID | -| `equipmentAdvice` | `String` | 装备建议(富文本) | -| `insuranceNotice` | `String` | 保险告知(INCLUDED/EXCLUDED/OPTIONAL) | -| `insuranceSchemeId` | `Long` | 保险方案ID | -| `contractSchemeId` | `Long` | 合同方案ID | -| `quickUnderstand` | `Object` | 快速理解 | -| `childExperience` | `Object` | 孩子经历 | -| `growthGains` | `List<Object>` | 成长收获 | -| `id` | `Long` | 费用项ID(已有则传) | -| `feeType` | `String` | 费用类型 | -| `source` | `String` | 来源(AUTO/MANUAL) | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | -| `unitPrice` | `BigDecimal` | 单价(自定义费用) | -| `unit` | `String` | 单位(自定义费用) | -| `sortOrder` | `Integer` | 排序 | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/calculate-mileage — 计算行程总里程 - -> 根据行程途经点坐标调用高德驾车路线规划API自动计算总驾驶里程(km)。需先保存行程(Step2)。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<BigDecimal>` - -### 📌 `GET` /admin/product/item/{id}/suggest-price — 计算建议售价 - -> 根据备品成本+额外成本计算建议售价。如有激活的公式组则通过公式引擎计算。返回成人/儿童单价及成本明细。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<SuggestPriceRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultSuggestPrice` | `BigDecimal` | 成人建议售价(单人) | -| `childSuggestPrice` | `BigDecimal` | 儿童建议售价(单人) | -| `adultCost` | `CostBreakdown` | 成人成本明细 | -| `childCost` | `CostBreakdown` | 儿童成本明细 | -| `formulaApplied` | `Boolean` | 是否使用了公式引擎 | -| `suppliesCost` | `BigDecimal` | 备品成本(按人头) | -| `extraCost` | `BigDecimal` | 额外成本 | -| `totalCost` | `BigDecimal` | 成本合计 | -| `suppliesItems` | `List<CostItem>` | 备品明细 | -| `extraItems` | `List<CostItem>` | 额外成本明细 | -| `name` | `String` | 名称 | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `subtotal` | `BigDecimal` | 小计 | - -### 📌 `GET` /admin/product/item/{id} — 产品详情 - -> 聚合全部5步数据（主表+基础+行程+路线+价格+补充），用于编辑页回显。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<ProductDetailRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productNo` | `String` | 产品编号 | -| `productType` | `String` | 产品类型 | -| `category` | `String` | 产品分类(字典product_category) | -| `status` | `String` | 产品状态 | -| `currentStep` | `Integer` | 当前步骤进度（1=基础信息, 2=行程编排, 3=路线与备品, 4=定价管理, 5=补充信息） | -| `createdBy` | `Long` | 创建人ID | -| `publishedAt` | `LocalDateTime` | 上架时间 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `lineId` | `Long` | 产品线ID | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `coverImageUrl` | `String` | 封面图 | -| `tiers` | `Object` | 档位列表 | -| `seasons` | `Object` | 产品季节 | -| `tags` | `Object` | 产品标签 | -| `carouselImages` | `Object` | 轮播图 | -| `isBooking` | `Boolean` | 是否预约产品 | -| `paymentType` | `String` | 支付方式 | -| `depositRatio` | `Integer` | 订金比例 | -| `depositAmount` | `BigDecimal` | 订金固定额 | -| `balanceDueDays` | `Integer` | 尾款截止天数 | -| `defaultDailyStock` | `Integer` | 每日库存默认值 | -| `defaultRoomCount` | `Integer` | 默认房间数 | -| `itinerary` | `List<Object>` | 行程天列表 | -| `routeInfo` | `ProductRouteInfoDO` | 路线信息 | -| `supplies` | `List<ProductSuppliesDO>` | 备品列表 | -| `extraCosts` | `List<ProductFeeItemDO>` | 额外成本项 | -| `schedules` | `List<GroupTourBatchDO>` | 班期列表 | -| `includedFees` | `List<ProductFeeItemDO>` | 费用包含 | -| `excludedFees` | `List<ProductFeeItemDO>` | 费用不含 | -| `customFees` | `List<ProductFeeItemDO>` | 自定义费用 | -| `crowdBenefit` | `ProductCrowdBenefitDO` | 人群优惠 | -| `supplement` | `ProductSupplementDO` | 补充配置 | - -### 📌 `GET` /admin/product/item/list — 产品分页列表 - -> 支持按名称关键词/产品类型/产品线/状态筛选。 - -**响应** `Result<PageResult<ProductListRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productNo` | `String` | 产品编号(如C260409001) | -| `productType` | `String` | 产品类型(字典product_type: CORE=核心产品, GROUP=小蒙马, CUSTOM=私人定制) | -| `category` | `String` | 产品分类(字典product_category) | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `coverImageUrl` | `String` | 封面图URL | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `lineId` | `Long` | 产品线ID（前端叫「主题」） | -| `lineName` | `String` | 产品线名称（前端叫「主题名」，从产品线表关联查出） | -| `status` | `String` | 产品状态(字典product_status) | -| `seasons` | `List<String>` | 产品季节(JSON数组，如[\ | -| `tags` | `List<String>` | 产品标签(JSON数组，如[\ | -| `tierCount` | `Integer` | 档位数量（前端叫「规格数」，单一=1，多档=N，未配置=0） | -| `startPrice` | `BigDecimal` | 起步价(已上架产品的最低成人售价，草稿为null) | -| `sortOrder` | `Integer` | 排序号 | -| `createdBy` | `Long` | 创建人ID | -| `createdByName` | `String` | 创建人名称 | -| `publishedAt` | `LocalDateTime` | 上架时间 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/product/item/{id} — 删除产品 - -> 级联删除产品+全部子表。仅草稿/已驳回/已下架/已完成状态可删，已上架/待审核需先下架。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/operation-logs — 产品操作记录 - -> 查询产品的全部操作记录（按时间倒序），审计保留不随产品删除。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<ProductOperationLogRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | 记录ID | -| `action` | `String` | 操作类型 | -| `detail` | `String` | 详情/驳回原因 | -| `step` | `String` | 步骤号 | -| `operatorId` | `Long` | 操作人ID | -| `operatorName` | `String` | 操作人名称 | -| `createTime` | `LocalDateTime` | 操作时间 | - -### 📌 `POST` /admin/product/item/{id}/action — 产品状态变更 - -> 通过COLA状态机驱动状态流转。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductActionReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `action` | `String` | 操作动作(SUBMIT_PUBLISH/WITHDRAW/DIRECT_PUBLISH/UNPUBLISH/FORCE_UNPUBLISH/COMPLETE) | -| `remark` | `String` | 备注/驳回原因(可选) | - -**响应** `Result<Void>` - -### 📌 `POST` /admin/product/item/{id}/copy — 复制产品 - -> 深拷贝产品+全部子表（主表+6张1:1/1:N子表+行程数据），新产品为草稿状态。返回新产品ID。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Long>` - -### 📌 `PUT` /admin/product/item/{id}/transfer — 转让产品 - -> 更换产品创建人（仅超管可操作）。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `ProductTransferReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `newCreatorId` | `Long` | 新创建人ID | - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/item/{id}/validate-publish — 上架预检 - -> 5级校验：L1基础字段→L2内容完整→L3定价→L4条款→L5资源。返回问题列表，空=全部通过。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<String>>` - -### 📌 `GET` /admin/product/item/{id}/fee-deduction-preview — 费用推导预览 - -> 根据行程节点类型自动推导费用包含项（景区→门票，酒店→住宿等），排除已忽略类型。 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<FeeDeductionPreviewVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `feeType` | `String` | 费用类型标签 | -| `name` | `String` | 费用名称 | -| `source` | `String` | 来源（AUTO=自动推导） | -| `sourceNodeName` | `String` | 来源节点名称 | - -### 🆕 新增: AdminProductLine - -### 📌 `POST` /admin/product/line — 创建/修改产品线 - -**请求体** `ProductLineSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID(修改时传) | -| `name` | `String` | 名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `List<String>` | 适用季节 | -| `tags` | `List<String>` | 标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态(ACTIVE/INACTIVE) | - -**响应** `Result<Long>` - -### 📌 `GET` /admin/product/line/{id} — 产品线详情 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<ProductLineRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `List<String>` | 适用季节 | -| `tags` | `List<String>` | 产品线标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态 | -| `productCount` | `Long` | 产品数量 | -| `createdBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `GET` /admin/product/line/list — 产品线分页列表 - -**响应** `Result<PageResult<ProductLineRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | -| `productType` | `String` | 绑定产品类型 | -| `description` | `String` | 描述 | -| `seasons` | `List<String>` | 适用季节 | -| `tags` | `List<String>` | 产品线标签 | -| `coverImageUrl` | `String` | 封面图 | -| `sortOrder` | `Integer` | 排序 | -| `status` | `String` | 状态 | -| `productCount` | `Long` | 产品数量 | -| `createdBy` | `Long` | 创建人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `DELETE` /admin/product/line/{id} — 删除产品线 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/line/simple-list — 产品线下拉选项 - -**响应** `Result<List<ProductLineDropdownVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | - -### 🆕 新增: AdminProductTemplate - -### 📌 `GET` /admin/product/safety-template/enabled — 安全保障模板下拉 - -**响应** `Result<List<SafetyTemplateVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `templateId` | `Long` | 模板ID | -| `name` | `String` | 模板名称 | -| `items` | `String` | 具体条目（JSON） | - -### 🆕 新增: AdminWarmTips - -### 📌 `GET` /admin/product/warm-tips/list — 温馨提示列表 - -> 返回所有温馨提示（含禁用），按创建时间倒序 - -**响应** `Result<List<WarmTipsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/warm-tips/enabled — 启用的温馨提示列表 - -> 仅返回启用状态的提示，供产品设计时选择 - -**响应** `Result<List<WarmTipsRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/warm-tips/{tipsId} — 温馨提示详情 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - -**响应** `Result<WarmTipsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/warm-tips — 创建温馨提示 - -> 创建后默认启用 - -**请求体** `WarmTipsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<WarmTipsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/warm-tips/{tipsId} — 修改温馨提示 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - -**请求体** `WarmTipsSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `remark` | `String` | 备注 | - -**响应** `Result<WarmTipsRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 温馨提示ID | -| `tipsName` | `String` | 提示名称 | -| `content` | `String` | 提示内容（富文本） | -| `enabled` | `Boolean` | 是否启用 | -| `remark` | `String` | 备注 | -| `createdBy` | `Long` | 创建人ID | -| `createdAt` | `LocalDateTime` | 创建时间 | -| `updatedAt` | `LocalDateTime` | 更新时间 | - -### 📌 `DELETE` /admin/product/warm-tips/{tipsId} — 删除温馨提示 - -> 软删除，已绑定的产品不受影响 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - -**响应** `Result<Void>` - -### 📌 `PUT` /admin/product/warm-tips/{tipsId}/toggle — 启用/禁用温馨提示 - -> 禁用后不再出现在产品设计的可选列表中 - -**参数** - - - `{tipsId}` (`Long`) — 路径参数：温馨提示ID - - `enabled` (`boolean`) — 查询参数：是否启用 - -**响应** `Result<Void>` - -### 🆕 新增: District - -### 📌 `GET` /admin/product/district/search — 搜索行政区划（城市/区县/镇） - -> 通过高德地图 API 搜索行政区划，用于产品的出发城市和目的地城市选择。 - -**参数** - - - `keywords` (`String`) — 查询参数：搜索关键词 - -### 🆕 新增: Formula - -### 📌 `GET` /admin/product/formula/group/list — 公式组列表 - -> 获取定价公式组列表，可按产品类型筛选。 - -**参数** - - - `productType` (`String`) — 查询参数 - -**响应** `Result<List<FormulaGroupRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `GET` /admin/product/formula/group/{groupId} — 公式组详情 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<FormulaGroupRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `POST` /admin/product/formula/group — 创建公式组 - -**请求体** `FormulaGroupSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型(字典product_type: CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品) | -| `description` | `String` | 描述 | - -**响应** `Result<FormulaGroupRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `PUT` /admin/product/formula/group/{groupId} — 更新公式组 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**请求体** `FormulaGroupSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型(字典product_type: CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品) | -| `description` | `String` | 描述 | - -**响应** `Result<FormulaGroupRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `groupCode` | `String` | 公式组编码 | -| `groupName` | `String` | 公式组名称 | -| `productType` | `String` | 适用产品类型 | -| `description` | `String` | 描述 | -| `isActive` | `Boolean` | 是否激活 | -| `version` | `Integer` | 版本号 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `stepCount` | `Integer` | 步骤数量 | - -### 📌 `PUT` /admin/product/formula/group/{groupId}/activate — 激活公式组 - -> 激活指定公式组，同时自动停用同产品类型下的其他公式组 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/product/formula/group/{groupId} — 删除公式组 - -> 已激活的公式组不能删除，需先激活其他公式组 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/formula/group/{groupId}/steps — 公式步骤列表 - -> 获取公式组下所有步骤，按执行顺序升序排列 - -**参数** - - - `{groupId}` (`Long`) — 路径参数 - -**响应** `Result<List<FormulaStepRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `Long` | 公式ID | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `GET` /admin/product/formula/step/{formulaId} — 公式步骤详情 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `Long` | 公式ID | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/formula/step — 创建公式步骤 - -**请求体** `FormulaStepSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量） | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `changeNote` | `String` | 变更说明 | - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `Long` | 公式ID | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/formula/step/{formulaId} — 更新公式步骤 - -> 更新时自动保存版本快照，可通过版本历史接口查看和回滚 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**请求体** `FormulaStepSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量） | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `changeNote` | `String` | 变更说明 | - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `Long` | 公式ID | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `PUT` /admin/product/formula/step/{formulaId}/toggle — 启用/禁用公式步骤 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `DELETE` /admin/product/formula/step/{formulaId} — 删除公式步骤 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 📌 `GET` /admin/product/formula/step/{formulaId}/versions — 公式步骤版本历史 - -> 按版本号倒序返回历史版本列表 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - -**响应** `Result<List<FormulaVersionRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `versionId` | `Long` | 版本ID | -| `formulaId` | `Long` | 公式ID | -| `versionNum` | `Integer` | 版本号 | -| `expression` | `String` | 表达式 | -| `changeNote` | `String` | 变更说明 | -| `changedBy` | `Long` | 变更人ID | -| `createTime` | `LocalDateTime` | 创建时间 | - -### 📌 `PUT` /admin/product/formula/step/{formulaId}/rollback/{versionNum} — 回滚公式步骤到指定版本 - -> 回滚前自动备份当前表达式 - -**参数** - - - `{formulaId}` (`Long`) — 路径参数 - - `{versionNum}` (`Integer`) — 路径参数 - -**响应** `Result<FormulaStepRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `formulaId` | `Long` | 公式ID | -| `groupId` | `Long` | 公式组ID | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `executionOrder` | `Integer` | 执行顺序 | -| `expression` | `String` | 表达式 | -| `outputVar` | `String` | 输出变量名 | -| `inputVars` | `String` | 输入变量(逗号分隔) | -| `description` | `String` | 描述 | -| `isEnabled` | `Boolean` | 是否启用 | -| `createTime` | `LocalDateTime` | 创建时间 | -| `updateTime` | `LocalDateTime` | 更新时间 | - -### 📌 `POST` /admin/product/formula/test — 测试公式执行 - -> 使用自定义变量值测试公式组的执行结果，不影响业务数据 - -**请求体** `FormulaTestReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `groupId` | `Long` | 公式组ID | -| `variables` | `Map<String, Object>` | 测试变量(变量名->值) | - -**响应** `Result<FormulaTestResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `success` | `Boolean` | 是否成功 | -| `errorMessage` | `String` | 错误信息 | -| `stepResults` | `List<StepResult>` | 各步骤执行结果 | -| `finalVariables` | `Map<String, Object>` | 最终变量表 | -| `totalTimeMs` | `Long` | 总耗时(毫秒) | -| `stepCode` | `String` | 步骤编码 | -| `stepName` | `String` | 步骤名称 | -| `outputVar` | `String` | 输出变量名 | -| `outputValue` | `Object` | 输出值 | -| `expression` | `String` | 表达式 | -| `executionTimeMs` | `Long` | 执行耗时(毫秒) | -| `success` | `Boolean` | 是否成功 | -| `errorMessage` | `String` | 错误信息 | - -### 📌 `GET` /admin/product/formula/var/list — 公式变量列表 - -> 获取公式变量列表，可按变量分类筛选（INPUT/INTERMEDIATE/OUTPUT） - -**参数** - - - `category` (`String`) — 查询参数 - -**响应** `Result<List<FormulaVarRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varId` | `Long` | 变量ID | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -### 📌 `POST` /admin/product/formula/var — 创建公式变量 - -**请求体** `FormulaVarSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -**响应** `Result<FormulaVarRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varId` | `Long` | 变量ID | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -### 📌 `PUT` /admin/product/formula/var/{varId} — 更新公式变量 - -**参数** - - - `{varId}` (`Long`) — 路径参数 - -**请求体** `FormulaVarSaveReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -**响应** `Result<FormulaVarRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `varId` | `Long` | 变量ID | -| `varName` | `String` | 变量名 | -| `varType` | `String` | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING | -| `category` | `String` | 变量分类：INPUT/INTERMEDIATE/OUTPUT | -| `description` | `String` | 描述 | -| `defaultValue` | `String` | 默认值 | -| `productTypes` | `List<String>` | 适用产品类型列表 | - -### 📌 `DELETE` /admin/product/formula/var/{varId} — 删除公式变量 - -> 如果有公式步骤引用了该变量，删除后步骤执行时会报错 - -**参数** - - - `{varId}` (`Long`) — 路径参数 - -**响应** `Result<Void>` - -### 🆕 新增: MpProduct - -### 📌 `GET` /mp/product/{id} — 产品详情 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<MpProductDetailRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `coverImageUrl` | `String` | 封面图 | -| `carouselImages` | `List<String>` | 轮播图 | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `itinerary` | `List<DayInfo>` | 行程天列表 | -| `includedFees` | `List<FeeInfo>` | 费用包含 | -| `excludedFees` | `List<FeeInfo>` | 费用不含 | -| `crowdBenefit` | `CrowdBenefitInfo` | 人群优惠 | -| `routeMapUrl` | `String` | 路线图URL | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 标题 | -| `description` | `String` | 描述 | -| `coverImageUrl` | `String` | 封面图 | -| `breakfast` | `String` | 早餐 | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `nodes` | `List<NodeInfo>` | 节点列表 | -| `nodeType` | `String` | 节点类型 | -| `nodeName` | `String` | 节点名称 | -| `startTime` | `String` | 开始时间 | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `childTicket` | `String` | 儿童门票 | -| `childAccommodation` | `String` | 儿童住宿 | -| `childMeal` | `String` | 儿童餐饮 | -| `elderTicket` | `String` | 老人门票 | -| `tips` | `String` | 温馨提示 | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | - -### 📌 `GET` /mp/product/{id}/price-calendar — 价格日历 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<MpPriceCalendarRespVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `days` | `List<CalendarDay>` | 日历列表 | -| `date` | `String` | 日期(yyyy-MM-dd) | -| `priceType` | `String` | 价格类型 | -| `adultPrice` | `BigDecimal` | 成人售价 | -| `childPrice` | `BigDecimal` | 儿童售价 | -| `isSelectable` | `Boolean` | 是否可选(有库存且未过期) | -| `remainStock` | `Integer` | 剩余库存(NULL=不限量) | - -### 📌 `GET` /mp/product/{id}/schedules — 班期列表 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<List<GroupTourBatchDO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | | -| `productId` | `Long` | | -| `batchNo` | `String` | | -| `batchLabel` | `String` | | -| `batchName` | `String` | | -| `productStockLimit` | `Integer` | | -| `adultPrice` | `BigDecimal` | | -| `childPrice` | `BigDecimal` | | -| `toddlerDiscount` | `BigDecimal` | | -| `infantPrice` | `BigDecimal` | | -| `departureDate` | `LocalDate` | | -| `endDate` | `LocalDate` | | -| `enrollmentDeadline` | `LocalDate` | | -| `maxParticipants` | `Integer` | | -| `enrolledCount` | `Integer` | | -| `maxRooms` | `Integer` | | -| `bookedRooms` | `Integer` | | -| `batchStatus` | `String` | | -| `sortOrder` | `Integer` | | -| `remark` | `String` | | -| `version` | `Integer` | | - -### 📌 `POST` /mp/product/{id}/quote — C端报价 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**请求体** `QuoteReqVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `departureDate` | `LocalDate` | 出发日期 | -| `adultCount` | `Integer` | 成人数 | -| `batchId` | `Long` | 班期ID(小蒙马用) | - -**响应** `Result<QuoteResultVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `totalAdultPrice` | `BigDecimal` | 成人总价 | -| `totalChildPrice` | `BigDecimal` | 儿童总价 | -| `grandTotal` | `BigDecimal` | 总价合计 | -| `dailyDetails` | `List<DailyDetail>` | 每日价格明细 | -| `date` | `String` | 日期 | -| `adultPrice` | `BigDecimal` | 成人日价 | -| `childPrice` | `BigDecimal` | 儿童日价 | - -### 📌 `GET` /mp/product/compare — 产品对比 - -**参数** - - - `ids` (`String`) — 查询参数 - -**响应** `Result<List<MpProductDetailRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productType` | `String` | 产品类型 | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `introduction` | `String` | 产品简介 | -| `coverImageUrl` | `String` | 封面图 | -| `carouselImages` | `List<String>` | 轮播图 | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `itinerary` | `List<DayInfo>` | 行程天列表 | -| `includedFees` | `List<FeeInfo>` | 费用包含 | -| `excludedFees` | `List<FeeInfo>` | 费用不含 | -| `crowdBenefit` | `CrowdBenefitInfo` | 人群优惠 | -| `routeMapUrl` | `String` | 路线图URL | -| `dayNumber` | `Integer` | 天序号 | -| `dayTitle` | `String` | 标题 | -| `description` | `String` | 描述 | -| `coverImageUrl` | `String` | 封面图 | -| `breakfast` | `String` | 早餐 | -| `lunch` | `String` | 午餐 | -| `dinner` | `String` | 晚餐 | -| `nodes` | `List<NodeInfo>` | 节点列表 | -| `nodeType` | `String` | 节点类型 | -| `nodeName` | `String` | 节点名称 | -| `startTime` | `String` | 开始时间 | -| `durationMinutes` | `Integer` | 时长(分钟) | -| `description` | `String` | 描述 | -| `childTicket` | `String` | 儿童门票 | -| `childAccommodation` | `String` | 儿童住宿 | -| `childMeal` | `String` | 儿童餐饮 | -| `elderTicket` | `String` | 老人门票 | -| `tips` | `String` | 温馨提示 | -| `name` | `String` | 名称 | -| `description` | `String` | 说明 | - -### 📌 `GET` /mp/product/{id}/tier-compare — 档位对比 - -**参数** - - - `{id}` (`Long`) — 路径参数 - -**响应** `Result<Map<Integer, List<ProductDayHotelDO>>>` - -### 🆕 新增: MpProductLine - -### 📌 `GET` /mp/product-line/list — 产品线列表 - -**参数** - - - `season` (`String`) — 查询参数 - -**响应** `Result<List<ProductLineDropdownVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `name` | `String` | 产品线名称 | - -### 📌 `GET` /mp/product-line/{lineId}/products — 产品线下产品列表 - -**参数** - - - `{lineId}` (`Long`) — 路径参数 - -**响应** `Result<List<MpProductListRespVO>>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `productType` | `String` | 产品类型(CORE/GROUP/CUSTOM) | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题（一句话卖点） | -| `coverImageUrl` | `String` | 封面图URL | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `lineName` | `String` | 产品线名称（前端叫「主题名」） | -| `tags` | `List<String>` | 产品标签(如[\ | -| `seasons` | `List<String>` | 产品季节(如[\ | -| `startPrice` | `BigDecimal` | 起步价(¥X起，最低成人售价) | -| `startPriceLabel` | `String` | 起步价展示文案(如\ | -| `paymentType` | `String` | 支付方式(FULL=全款, DEPOSIT=订金) | -| `tierCount` | `Integer` | 规格数量（前端叫「规格数」，单一=1，多档=N） | -| `sortOrder` | `Integer` | 排序号 | - -### ❌ 删除: AdminBookingTerms - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/admin/product/booking-terms/list`~~ | ~~预订条款列表~~ | -| ~~`GET`~~ | ~~`/admin/product/booking-terms/enabled`~~ | ~~启用的预订条款列表~~ | -| ~~`GET`~~ | ~~`/admin/product/booking-terms/{termsId}`~~ | ~~预订条款详情~~ | -| ~~`POST`~~ | ~~`/admin/product/booking-terms`~~ | ~~创建预订条款~~ | -| ~~`PUT`~~ | ~~`/admin/product/booking-terms/{termsId}`~~ | ~~修改预订条款~~ | -| ~~`DELETE`~~ | ~~`/admin/product/booking-terms/{termsId}`~~ | ~~删除预订条款~~ | -| ~~`PUT`~~ | ~~`/admin/product/booking-terms/{termsId}/toggle`~~ | ~~启用/禁用预订条款~~ | - -### ❌ 删除: AdminProductLine - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`POST`~~ | ~~`/admin/product/line`~~ | ~~创建/修改产品线~~ | -| ~~`GET`~~ | ~~`/admin/product/line/{id}`~~ | ~~产品线详情~~ | -| ~~`GET`~~ | ~~`/admin/product/line/list`~~ | ~~产品线分页列表~~ | -| ~~`DELETE`~~ | ~~`/admin/product/line/{id}`~~ | ~~删除产品线~~ | -| ~~`GET`~~ | ~~`/admin/product/line/simple-list`~~ | ~~产品线下拉选项~~ | - -### ❌ 删除: AdminProductTemplate - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/admin/product/safety-template/enabled`~~ | ~~安全保障模板下拉~~ | - -### ❌ 删除: AdminWarmTips - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/admin/product/warm-tips/list`~~ | ~~温馨提示列表~~ | -| ~~`GET`~~ | ~~`/admin/product/warm-tips/enabled`~~ | ~~启用的温馨提示列表~~ | -| ~~`GET`~~ | ~~`/admin/product/warm-tips/{tipsId}`~~ | ~~温馨提示详情~~ | -| ~~`POST`~~ | ~~`/admin/product/warm-tips`~~ | ~~创建温馨提示~~ | -| ~~`PUT`~~ | ~~`/admin/product/warm-tips/{tipsId}`~~ | ~~修改温馨提示~~ | -| ~~`DELETE`~~ | ~~`/admin/product/warm-tips/{tipsId}`~~ | ~~删除温馨提示~~ | -| ~~`PUT`~~ | ~~`/admin/product/warm-tips/{tipsId}/toggle`~~ | ~~启用/禁用温馨提示~~ | - -### ❌ 删除: District - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/admin/product/district/search`~~ | ~~搜索行政区划（城市/区县/镇）~~ | - -### ❌ 删除: Formula - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/admin/product/formula/group/list`~~ | ~~公式组列表~~ | -| ~~`GET`~~ | ~~`/admin/product/formula/group/{groupId}`~~ | ~~公式组详情~~ | -| ~~`POST`~~ | ~~`/admin/product/formula/group`~~ | ~~创建公式组~~ | -| ~~`PUT`~~ | ~~`/admin/product/formula/group/{groupId}`~~ | ~~更新公式组~~ | -| ~~`PUT`~~ | ~~`/admin/product/formula/group/{groupId}/activate`~~ | ~~激活公式组~~ | -| ~~`DELETE`~~ | ~~`/admin/product/formula/group/{groupId}`~~ | ~~删除公式组~~ | -| ~~`GET`~~ | ~~`/admin/product/formula/group/{groupId}/steps`~~ | ~~公式步骤列表~~ | -| ~~`GET`~~ | ~~`/admin/product/formula/step/{formulaId}`~~ | ~~公式步骤详情~~ | -| ~~`POST`~~ | ~~`/admin/product/formula/step`~~ | ~~创建公式步骤~~ | -| ~~`PUT`~~ | ~~`/admin/product/formula/step/{formulaId}`~~ | ~~更新公式步骤~~ | -| ~~`PUT`~~ | ~~`/admin/product/formula/step/{formulaId}/toggle`~~ | ~~启用/禁用公式步骤~~ | -| ~~`DELETE`~~ | ~~`/admin/product/formula/step/{formulaId}`~~ | ~~删除公式步骤~~ | -| ~~`GET`~~ | ~~`/admin/product/formula/step/{formulaId}/versions`~~ | ~~公式步骤版本历史~~ | -| ~~`PUT`~~ | ~~`/admin/product/formula/step/{formulaId}/rollback/{versionNum}`~~ | ~~回滚公式步骤到指定版本~~ | -| ~~`POST`~~ | ~~`/admin/product/formula/test`~~ | ~~测试公式执行~~ | -| ~~`GET`~~ | ~~`/admin/product/formula/var/list`~~ | ~~公式变量列表~~ | -| ~~`POST`~~ | ~~`/admin/product/formula/var`~~ | ~~创建公式变量~~ | -| ~~`PUT`~~ | ~~`/admin/product/formula/var/{varId}`~~ | ~~更新公式变量~~ | -| ~~`DELETE`~~ | ~~`/admin/product/formula/var/{varId}`~~ | ~~删除公式变量~~ | - -### ❌ 删除: MpProduct - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/mp/product/{id}`~~ | ~~产品详情~~ | -| ~~`GET`~~ | ~~`/mp/product/{id}/price-calendar`~~ | ~~价格日历~~ | -| ~~`GET`~~ | ~~`/mp/product/{id}/schedules`~~ | ~~班期列表~~ | -| ~~`POST`~~ | ~~`/mp/product/{id}/quote`~~ | ~~C端报价~~ | -| ~~`GET`~~ | ~~`/mp/product/compare`~~ | ~~产品对比~~ | -| ~~`GET`~~ | ~~`/mp/product/{id}/tier-compare`~~ | ~~档位对比~~ | - -### ❌ 删除: MpProductLine - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`GET`~~ | ~~`/mp/product-line/list`~~ | ~~产品线列表~~ | -| ~~`GET`~~ | ~~`/mp/product-line/{lineId}/products`~~ | ~~产品线下产品列表~~ | - ---- - -## 📦 其他数据对象变更 - -> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应 - -### hl-product-service-v2 - -#### 🆕 BookingTermsVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `termsId` | `Long` | 条款ID | -| `termsName` | `String` | 条款名称 | - -#### 🆕 ItineraryDayDeleteReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `dayNumber` | `Integer` | 天序号 | - -#### 🆕 MpPriceCalendarReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `month` | `String` | 月份(yyyy-MM) | - -#### 🆕 MpProductLineQueryReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `lineId` | `Long` | 产品线ID | -| `tag` | `String` | 标签筛选(可选) | - -#### 🆕 OperationLogReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `actionCode` | `String` | 操作动作编码 | -| `detail` | `String` | 操作详情 | -| `step` | `String` | 步骤编码 | - -#### 🆕 PriceCalendarQueryReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `month` | `String` | 月份(yyyy-MM) | -| `tierSeq` | `Integer` | 档位序号(默认1) | - -#### 🆕 ProductLinePageReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `keyword` | `String` | 关键词 | -| `status` | `String` | 状态(ACTIVE/INACTIVE) | - -#### 🆕 ProductPageReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `keyword` | `String` | 关键词(名称/编号) | -| `productType` | `String` | 产品类型(CORE/GROUP/CUSTOM) | -| `lineId` | `Long` | 产品线ID | -| `status` | `String` | 产品状态 | - -#### 🆕 ProductSaveReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 产品名称（≤30字） | -| `productType` | `String` | 产品类型（字典product_type: CORE=核心产品, GROUP=小蒙马跟团游, CUSTOM=私人定制） | -| `lineId` | `Long` | 产品线ID（从 /admin/product/line/simple-list 下拉获取，私人定制可空） | -| `tripDays` | `Integer` | 行程天数（可选，创建后可在Step1修改） | - -#### 🆕 ScheduleOperateReqVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `batchId` | `Long` | 班期ID | - -#### 🆕 ScheduleTeamQueryReqVO - -#### 🆕 WarmTipsVO - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `tipsId` | `Long` | 提示ID | -| `tipsName` | `String` | 提示名称 | - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -A hl-product-service-v2/src/main/java/com/hulalv/ProductServiceV2Application.java -A hl-product-service-v2/src/main/java/com/hulalv/config/Knife4jConfig.java -A hl-product-service-v2/src/main/java/com/hulalv/config/WebMvcConfig.java -A hl-product-service-v2/src/main/java/com/hulalv/constant/ProductConstants.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminBookingTermsController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductLineController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductTemplateController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminWarmTipsController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/DistrictController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/admin/FormulaController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/mp/MpProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/mp/MpProductLineController.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/AviatorCeil10Function.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/AviatorMaxFunction.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/AviatorSafeFunction.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/AviatorSellPriceFunction.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/FormulaEngine.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/FormulaEngineConfig.java -A hl-product-service-v2/src/main/java/com/hulalv/engine/PricingContext.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/BookingTermsDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/GroupBatchStaffDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/GroupTourBatchDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/PricingFormulaDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/PricingFormulaGroupDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/PricingFormulaVarDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/PricingFormulaVersionDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductBasicDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductCrowdBenefitDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductDayHotelDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductFeeItemDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductItineraryDayDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductItineraryNodeDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductLineDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductOperationLogDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductPriceCalendarDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductRouteInfoDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductRoutePointDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductSupplementDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/ProductSuppliesDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/SafetyTemplateDO.java -A hl-product-service-v2/src/main/java/com/hulalv/entity/WarmTipsDO.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/BatchStatusEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/FeeCategoryEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/LineStatusEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/NodeTypeEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/PriceTypeEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/ProductActionEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/ProductStatusEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/ProductTypeEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/RepeatModeEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/enums/StepEnum.java -A hl-product-service-v2/src/main/java/com/hulalv/feign/ResourceHotelFeignClient.java -A hl-product-service-v2/src/main/java/com/hulalv/feign/ResourcePriceFeignClient.java -A hl-product-service-v2/src/main/java/com/hulalv/interceptor/AdminAuthInterceptor.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/BookingTermsMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/GroupBatchStaffMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/GroupTourBatchMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/PricingFormulaGroupMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/PricingFormulaMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/PricingFormulaVarMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/PricingFormulaVersionMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductBasicMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductCrowdBenefitMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductDayHotelMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductFeeItemMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductItineraryDayMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductItineraryNodeMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductLineMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductOperationLogMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductPriceCalendarMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductRouteInfoMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductRoutePointMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductSupplementMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductSuppliesMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/SafetyTemplateMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/mapper/WarmTipsMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/ProductServiceV2Application.java -D hl-product-service-v2/src/main/java/com/hulalv/product/config/Knife4jConfig.java -D hl-product-service-v2/src/main/java/com/hulalv/product/config/WebMvcConfig.java -D hl-product-service-v2/src/main/java/com/hulalv/product/constant/ProductConstants.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminBookingTermsController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductLineController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductTemplateController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminWarmTipsController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/DistrictController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/FormulaController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/mp/MpProductController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/mp/MpProductLineController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorCeil10Function.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorMaxFunction.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorSafeFunction.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/AviatorSellPriceFunction.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/FormulaEngine.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/FormulaEngineConfig.java -D hl-product-service-v2/src/main/java/com/hulalv/product/engine/PricingContext.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/BookingTermsDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/GroupBatchStaffDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/GroupTourBatchDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaGroupDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaVarDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/PricingFormulaVersionDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductBasicDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductCrowdBenefitDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductDayHotelDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductFeeItemDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductItineraryDayDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductItineraryNodeDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductLineDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductOperationLogDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductPriceCalendarDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductRouteInfoDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductRoutePointDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductSupplementDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/ProductSuppliesDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/SafetyTemplateDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/entity/WarmTipsDO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/BatchStatusEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/FeeCategoryEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/LineStatusEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/NodeTypeEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/PriceTypeEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/ProductActionEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/ProductStatusEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/ProductTypeEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/RepeatModeEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/enums/StepEnum.java -D hl-product-service-v2/src/main/java/com/hulalv/product/feign/ResourceHotelFeignClient.java -D hl-product-service-v2/src/main/java/com/hulalv/product/interceptor/AdminAuthInterceptor.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/BookingTermsMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/GroupBatchStaffMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/GroupTourBatchMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaGroupMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaVarMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/PricingFormulaVersionMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductBasicMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductCrowdBenefitMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductDayHotelMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductFeeItemMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductItineraryDayMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductItineraryNodeMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductLineMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductOperationLogMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductPriceCalendarMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductRouteInfoMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductRoutePointMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductSupplementMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/ProductSuppliesMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/SafetyTemplateMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/mapper/WarmTipsMapper.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/AmapDistrictService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/AmapDrivingService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/BookingTermsService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaGroupService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaStepService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaTestService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/FormulaVarService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/GroupBatchStaffService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/GroupTourBatchService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductBasicService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductCopyService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductCrowdBenefitService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductDayHotelService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductDeleteService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductFeeItemService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductHelperService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductItineraryDayService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductItineraryNodeService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductItineraryService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductLineService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductOperationLogService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductPriceCalendarService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductQueryService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductRouteInfoService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductRoutePointService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductRouteService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductStatusService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductSupplementDataService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductSupplementService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductSuppliesService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductTemplateService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductValidationService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/SuggestPriceService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/WarmTipsService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/mp/MpProductService.java -D hl-product-service-v2/src/main/java/com/hulalv/product/statemachine/ProductStateMachineConfig.java -D hl-product-service-v2/src/main/java/com/hulalv/product/statemachine/ProductStatusContext.java -D hl-product-service-v2/src/main/java/com/hulalv/product/util/AdminContextUtil.java -D hl-product-service-v2/src/main/java/com/hulalv/product/util/EntityDiffUtil.java -D hl-product-service-v2/src/main/java/com/hulalv/product/util/ProductNoGenerator.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/BookingTermsRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/BookingTermsSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/BookingTermsVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/FeeDeductionPreviewVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ItineraryDayDeleteReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/OperationLogReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarBatchReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/PriceCalendarQueryReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductActionReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductBasicSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductDetailRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductItinerarySaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineDropdownVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLinePageReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductLineSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductListRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductOperationLogRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductPageReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductRouteSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductSupplementSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ProductTransferReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/QuoteReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/QuoteResultVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/SafetyTemplateVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleBatchCreateReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleOperateReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleTeamQueryReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/ScheduleTeamSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/SuggestPriceRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/WarmTipsRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/WarmTipsSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/WarmTipsVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaGroupRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaGroupSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaStepRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaStepSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaTestReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaTestResultVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVarRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVarSaveReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/admin/formula/FormulaVersionRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpPriceCalendarReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpPriceCalendarRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductDetailRespVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductLineQueryReqVO.java -D hl-product-service-v2/src/main/java/com/hulalv/product/vo/mp/MpProductListRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/AmapDistrictService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/AmapDrivingService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/BookingTermsService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/FormulaGroupService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/FormulaStepService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/FormulaTestService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/FormulaVarService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/GroupBatchStaffService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/GroupTourBatchService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductBasicService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductCopyService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductCrowdBenefitService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductDayHotelService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductDeleteService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductFeeItemService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductHelperService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductItineraryDayService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductItineraryNodeService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductItineraryService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductLineService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductOperationLogService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductPriceCalendarService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductPricingService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductQueryService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductRouteInfoService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductRoutePointService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductRouteService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductStatusService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductSupplementDataService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductSupplementService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductSuppliesService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductTemplateService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductValidationService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/SuggestPriceService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/admin/WarmTipsService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/mp/MpProductService.java -A hl-product-service-v2/src/main/java/com/hulalv/statemachine/ProductStateMachineConfig.java -A hl-product-service-v2/src/main/java/com/hulalv/statemachine/ProductStatusContext.java -A hl-product-service-v2/src/main/java/com/hulalv/util/AdminContextUtil.java -A hl-product-service-v2/src/main/java/com/hulalv/util/EntityDiffUtil.java -A hl-product-service-v2/src/main/java/com/hulalv/util/ProductNoGenerator.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/BookingTermsRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/BookingTermsSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/BookingTermsVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/FeeDeductionPreviewVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ItineraryDayDeleteReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/OperationLogReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/PriceCalendarBatchReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/PriceCalendarQueryReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductActionReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductBasicSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductDetailRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductItinerarySaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductLineDropdownVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductLinePageReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductLineRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductLineSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductListRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductOperationLogRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductPageReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductRouteSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductSupplementSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductTransferReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/QuoteReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/QuoteResultVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/SafetyTemplateVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ScheduleBatchCreateReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ScheduleOperateReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ScheduleSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ScheduleTeamQueryReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ScheduleTeamSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/SuggestPriceRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/WarmTipsRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/WarmTipsSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/WarmTipsVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaGroupRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaGroupSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaStepRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaStepSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaTestReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaTestResultVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaVarRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaVarSaveReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/formula/FormulaVersionRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/mp/MpPriceCalendarReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/mp/MpPriceCalendarRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/mp/MpProductDetailRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/mp/MpProductLineQueryReqVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/mp/MpProductListRespVO.java -M hl-product-service-v2/src/main/resources/mapper/ProductMapper.xml -M hl-product-service-v2/src/main/resources/mapper/ProductPriceCalendarMapper.xml -A hl-product-service-v2/src/test/java/com/hulalv/ProductServiceV2ApplicationTest.java -A hl-product-service-v2/src/test/java/com/hulalv/controller/admin/AdminProductLineControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/controller/admin/AdminProductTemplateControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/controller/mp/MpProductControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/controller/mp/MpProductLineControllerTest.java -A hl-product-service-v2/src/test/java/com/hulalv/engine/FormulaEngineTest.java -A hl-product-service-v2/src/test/java/com/hulalv/entity/EntityCoverageTest3.java -A hl-product-service-v2/src/test/java/com/hulalv/enums/EnumCoverageTest.java -A hl-product-service-v2/src/test/java/com/hulalv/enums/ProductStatusEnumTest.java -A hl-product-service-v2/src/test/java/com/hulalv/enums/ProductTypeEnumTest.java -A hl-product-service-v2/src/test/java/com/hulalv/interceptor/AdminAuthInterceptorTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/ProductServiceV2ApplicationTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductLineControllerTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/controller/admin/AdminProductTemplateControllerTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/controller/mp/MpProductControllerTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/controller/mp/MpProductLineControllerTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/engine/FormulaEngineTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/entity/EntityCoverageTest3.java -D hl-product-service-v2/src/test/java/com/hulalv/product/enums/EnumCoverageTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/enums/ProductStatusEnumTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/enums/ProductTypeEnumTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/interceptor/AdminAuthInterceptorTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/AmapDrivingServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/BookingTermsServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/DataServiceCoverageTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/FormulaGroupServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/FormulaStepServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/FormulaTestServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/FormulaVarServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/GroupBatchStaffServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductBasicServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductCopyServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductDeleteServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductHelperServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductItineraryServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductLineServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductOperationLogServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductQueryServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductRouteServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductStatusServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductSupplementServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductTemplateServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductValidationServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/WarmTipsServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/mp/MpProductServiceTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/util/AdminContextUtilTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/util/EntityDiffUtilTest.java -D hl-product-service-v2/src/test/java/com/hulalv/product/util/ProductNoGeneratorTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/AmapDrivingServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/BookingTermsServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/DataServiceCoverageTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/FormulaGroupServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/FormulaStepServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/FormulaTestServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/FormulaVarServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/GroupBatchStaffServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductBasicServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductCopyServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductDeleteServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductHelperServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductItineraryServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductLineServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductOperationLogServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductPricingServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductQueryServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductRouteServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductStatusServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductSupplementServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductTemplateServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/ProductValidationServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/admin/WarmTipsServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/service/mp/MpProductServiceTest.java -A hl-product-service-v2/src/test/java/com/hulalv/util/AdminContextUtilTest.java -A hl-product-service-v2/src/test/java/com/hulalv/util/EntityDiffUtilTest.java -A hl-product-service-v2/src/test/java/com/hulalv/util/ProductNoGeneratorTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_0951_0918a293_fix_product-v2.md b/changelogs/2026-04/2026-04-14_0951_0918a293_fix_product-v2.md deleted file mode 100644 index 6734ac9..0000000 --- a/changelogs/2026-04/2026-04-14_0951_0918a293_fix_product-v2.md +++ /dev/null @@ -1,62 +0,0 @@ -# 接口变更记录 — 2026-04-14 09:51 - -> **提交** `0918a293` · **作者** wx · **时间** 2026-04-14 09:51:58 +0800 -> -> fix(product-v2): 删除包重命名后残留的旧product目录 - -## 变更总览 - -- **hl-product-service-v2** - - ❌ AdminProduct (-30 接口) - ---- - -## hl-product-service-v2 - -### ❌ 删除: AdminProduct - -| 方法 | 路径 | 接口名称 | -| --- | --- | --- | -| ~~`POST`~~ | ~~`/admin/product/item/basic`~~ | ~~Step1 基础信息保存~~ | -| ~~`PUT`~~ | ~~`/admin/product/item/{id}/itinerary`~~ | ~~Step2 行程整体保存~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/itinerary/day`~~ | ~~Step2 增加一天~~ | -| ~~`DELETE`~~ | ~~`/admin/product/item/{id}/itinerary/day/{dayNumber}`~~ | ~~Step2 删除一天~~ | -| ~~`PUT`~~ | ~~`/admin/product/item/{id}/route`~~ | ~~Step3 路线与备品保存~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/price-calendar`~~ | ~~Step4 查询价格日历~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/schedule/list`~~ | ~~Step4 班期列表~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/price-calendar/batch`~~ | ~~Step4 价格日历批量设置~~ | -| ~~`DELETE`~~ | ~~`/admin/product/item/{id}/price-calendar`~~ | ~~Step4 价格日历删除~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/schedule`~~ | ~~Step4 创建班期~~ | -| ~~`DELETE`~~ | ~~`/admin/product/item/{id}/schedule/{scheduleId}`~~ | ~~Step4 删除班期~~ | -| ~~`PUT`~~ | ~~`/admin/product/item/{id}/schedule`~~ | ~~Step4 修改班期~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/schedule/batch-create`~~ | ~~Step4 班期批量创建~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/schedule/{scheduleId}/cancel`~~ | ~~Step4 取消班期~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/schedule/team`~~ | ~~班期团队查询~~ | -| ~~`PUT`~~ | ~~`/admin/product/item/{id}/schedule/team`~~ | ~~班期团队保存~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/suggest-price`~~ | ~~建议售价~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/quote`~~ | ~~报价计算~~ | -| ~~`PUT`~~ | ~~`/admin/product/item/{id}/supplement`~~ | ~~Step5 补充信息保存~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/calculate-mileage`~~ | ~~计算行程总里程~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/suggest-price`~~ | ~~计算建议售价~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}`~~ | ~~产品详情~~ | -| ~~`GET`~~ | ~~`/admin/product/item/list`~~ | ~~产品分页列表~~ | -| ~~`DELETE`~~ | ~~`/admin/product/item/{id}`~~ | ~~删除产品~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/operation-logs`~~ | ~~产品操作记录~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/action`~~ | ~~产品状态变更~~ | -| ~~`POST`~~ | ~~`/admin/product/item/{id}/copy`~~ | ~~复制产品~~ | -| ~~`PUT`~~ | ~~`/admin/product/item/{id}/transfer`~~ | ~~转让产品~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/validate-publish`~~ | ~~上架预检~~ | -| ~~`GET`~~ | ~~`/admin/product/item/{id}/fee-deduction-preview`~~ | ~~费用推导预览~~ | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -D hl-product-service-v2/src/main/java/com/hulalv/product/controller/admin/AdminProductController.java -D hl-product-service-v2/src/main/java/com/hulalv/product/feign/ResourcePriceFeignClient.java -D hl-product-service-v2/src/main/java/com/hulalv/product/service/admin/ProductPricingService.java -D hl-product-service-v2/src/test/java/com/hulalv/product/service/admin/ProductPricingServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_1006_74d7d89f_fix_product-v2.md b/changelogs/2026-04/2026-04-14_1006_74d7d89f_fix_product-v2.md deleted file mode 100644 index 5d1388b..0000000 --- a/changelogs/2026-04/2026-04-14_1006_74d7d89f_fix_product-v2.md +++ /dev/null @@ -1,33 +0,0 @@ -# 接口变更记录 — 2026-04-14 10:06 - -> **提交** `74d7d89f` · **作者** wx · **时间** 2026-04-14 10:06:46 +0800 -> -> fix(product-v2): 删除重复的suggestPrice方法导致Ambiguous mapping - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (改1) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### ✏️ `GET` /admin/product/item/{id}/suggest-price — 建议售价 - -- 接口名称: ~~计算建议售价~~ → **建议售价** -- 返回类型: `Result<SuggestPriceRespVO>` → `Result<Map<String, Object>>` -- ❌ 移除响应类型 `SuggestPriceRespVO` -- 参数: id(Long) → id(Long), departureDate(String), tierSeq(Integer) - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_1025_36079720_fix_product-v2.md b/changelogs/2026-04/2026-04-14_1025_36079720_fix_product-v2.md deleted file mode 100644 index 8f06759..0000000 --- a/changelogs/2026-04/2026-04-14_1025_36079720_fix_product-v2.md +++ /dev/null @@ -1,250 +0,0 @@ -# 接口变更记录 — 2026-04-14 10:25 - -> **提交** `36079720` · **作者** wx · **时间** 2026-04-14 10:18:01 +0800 -> -> fix(product-v2): 清理未使用注入+重复import - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (改27) - - AdminProductLine (改2) - - Formula (改15) - - MpProduct (改6) - - MpProductLine (改2) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### ✏️ `PUT` /admin/product/item/{id}/itinerary — Step2 行程整体保存 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/itinerary/day — Step2 增加一天 - -- 参数: id(Long) → id(Long) - -### ✏️ `DELETE` /admin/product/item/{id}/itinerary/day/{dayNumber} — Step2 删除一天 - -- 参数: id(Long), dayNumber(Integer) → id(Long), dayNumber(Integer) - -### ✏️ `PUT` /admin/product/item/{id}/route — Step3 路线与备品保存 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/price-calendar — Step4 查询价格日历 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/schedule/list — Step4 班期列表 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/price-calendar/batch — Step4 价格日历批量设置 - -- 参数: id(Long) → id(Long) - -### ✏️ `DELETE` /admin/product/item/{id}/price-calendar — Step4 价格日历删除 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/schedule — Step4 创建班期 - -- 参数: id(Long) → id(Long) - -### ✏️ `DELETE` /admin/product/item/{id}/schedule/{scheduleId} — Step4 删除班期 - -- 参数: id(Long), scheduleId(Long) → id(Long), scheduleId(Long) - -### ✏️ `PUT` /admin/product/item/{id}/schedule — Step4 修改班期 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/schedule/batch-create — Step4 班期批量创建 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/schedule/{scheduleId}/cancel — Step4 取消班期 - -- 参数: id(Long), scheduleId(Long) → id(Long), scheduleId(Long) - -### ✏️ `GET` /admin/product/item/{id}/schedule/team — 班期团队查询 - -- 参数: id(Long) → id(Long) - -### ✏️ `PUT` /admin/product/item/{id}/schedule/team — 班期团队保存 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/suggest-price — 建议售价 - -- 参数: id(Long), departureDate(String), tierSeq(Integer) → id(Long), departureDate(String), tierSeq(Integer) - -### ✏️ `POST` /admin/product/item/{id}/quote — 报价计算 - -- 参数: id(Long) → id(Long) - -### ✏️ `PUT` /admin/product/item/{id}/supplement — Step5 补充信息保存 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/calculate-mileage — 计算行程总里程 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id} — 产品详情 - -- 参数: id(Long) → id(Long) - -### ✏️ `DELETE` /admin/product/item/{id} — 删除产品 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/operation-logs — 产品操作记录 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/action — 产品状态变更 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /admin/product/item/{id}/copy — 复制产品 - -- 参数: id(Long) → id(Long) - -### ✏️ `PUT` /admin/product/item/{id}/transfer — 转让产品 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/validate-publish — 上架预检 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /admin/product/item/{id}/fee-deduction-preview — 费用推导预览 - -- 参数: id(Long) → id(Long) - -### AdminProductLine - -### ✏️ `GET` /admin/product/line/{id} — 产品线详情 - -- 参数: id(Long) → id(Long) - -### ✏️ `DELETE` /admin/product/line/{id} — 删除产品线 - -- 参数: id(Long) → id(Long) - -### Formula - -### ✏️ `GET` /admin/product/formula/group/list — 公式组列表 - -- 参数: productType(String) → productType(String) - -### ✏️ `GET` /admin/product/formula/group/{groupId} — 公式组详情 - -- 参数: groupId(Long) → groupId(Long) - -### ✏️ `PUT` /admin/product/formula/group/{groupId} — 更新公式组 - -- 参数: groupId(Long) → groupId(Long) - -### ✏️ `PUT` /admin/product/formula/group/{groupId}/activate — 激活公式组 - -- 参数: groupId(Long) → groupId(Long) - -### ✏️ `DELETE` /admin/product/formula/group/{groupId} — 删除公式组 - -- 参数: groupId(Long) → groupId(Long) - -### ✏️ `GET` /admin/product/formula/group/{groupId}/steps — 公式步骤列表 - -- 参数: groupId(Long) → groupId(Long) - -### ✏️ `GET` /admin/product/formula/step/{formulaId} — 公式步骤详情 - -- 参数: formulaId(Long) → formulaId(Long) - -### ✏️ `PUT` /admin/product/formula/step/{formulaId} — 更新公式步骤 - -- 参数: formulaId(Long) → formulaId(Long) - -### ✏️ `PUT` /admin/product/formula/step/{formulaId}/toggle — 启用/禁用公式步骤 - -- 参数: formulaId(Long) → formulaId(Long) - -### ✏️ `DELETE` /admin/product/formula/step/{formulaId} — 删除公式步骤 - -- 参数: formulaId(Long) → formulaId(Long) - -### ✏️ `GET` /admin/product/formula/step/{formulaId}/versions — 公式步骤版本历史 - -- 参数: formulaId(Long) → formulaId(Long) - -### ✏️ `PUT` /admin/product/formula/step/{formulaId}/rollback/{versionNum} — 回滚公式步骤到指定版本 - -- 参数: formulaId(Long), versionNum(Integer) → formulaId(Long), versionNum(Integer) - -### ✏️ `GET` /admin/product/formula/var/list — 公式变量列表 - -- 参数: category(String) → category(String) - -### ✏️ `PUT` /admin/product/formula/var/{varId} — 更新公式变量 - -- 参数: varId(Long) → varId(Long) - -### ✏️ `DELETE` /admin/product/formula/var/{varId} — 删除公式变量 - -- 参数: varId(Long) → varId(Long) - -### MpProduct - -### ✏️ `GET` /mp/product/{id} — 产品详情 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /mp/product/{id}/price-calendar — 价格日历 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /mp/product/{id}/schedules — 班期列表 - -- 参数: id(Long) → id(Long) - -### ✏️ `POST` /mp/product/{id}/quote — C端报价 - -- 参数: id(Long) → id(Long) - -### ✏️ `GET` /mp/product/compare — 产品对比 - -- 参数: ids(String) → ids(String) - -### ✏️ `GET` /mp/product/{id}/tier-compare — 档位对比 - -- 参数: id(Long) → id(Long) - -### MpProductLine - -### ✏️ `GET` /mp/product-line/list — 产品线列表 - -- 参数: season(String) → season(String) - -### ✏️ `GET` /mp/product-line/{lineId}/products — 产品线下产品列表 - -- 参数: lineId(Long) → lineId(Long) - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductController.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductLineController.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/FormulaController.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/mp/MpProductController.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/mp/MpProductLineController.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_1040_fix_amap_business_exception.md b/changelogs/2026-04/2026-04-14_1040_fix_amap_business_exception.md deleted file mode 100644 index 3d53522..0000000 --- a/changelogs/2026-04/2026-04-14_1040_fix_amap_business_exception.md +++ /dev/null @@ -1,25 +0,0 @@ -# fix(product-v2): 计算里程接口500错误修复 - -- **PR**: #480 -- **服务**: hl-product-service-v2 -- **类型**: bug修复 - -## 问题 - -`GET /admin/product/item/{id}/calculate-mileage` 接口在产品未保存行程途经点时返回500，前端只能看到"服务器内部错误"，无法得知具体原因。 - -## 修复内容 - -将 `AmapDrivingService` 中的异常类型从 `IllegalArgumentException`/`RuntimeException` 改为 `BusinessException`，前端现在能看到具体错误提示： - -| 场景 | 修复前提示 | 修复后提示 | -|------|-----------|-----------| -| 途经点不足2个 | 服务器内部错误 | 行程途经点不足2个，无法计算里程，请先保存行程(Step2) | -| 有效坐标不足 | 服务器内部错误 | 有效途经点(含经纬度)不足2个，无法计算里程 | -| 高德API调用失败 | 服务器内部错误 | 里程计算失败: 具体原因 | - -## 前端影响 - -- **无接口变更**，接口入参和成功返回值不变 -- 失败时 `code` 从 `500` 变为业务错误码，`message` 字段包含具体中文提示，前端可直接展示给用户 -- 建议前端在调用失败时用 `message` 字段做 toast 提示 diff --git a/changelogs/2026-04/2026-04-14_1100_6a9ec7ce_feat_product-v2.md b/changelogs/2026-04/2026-04-14_1100_6a9ec7ce_feat_product-v2.md deleted file mode 100644 index 863df9e..0000000 --- a/changelogs/2026-04/2026-04-14_1100_6a9ec7ce_feat_product-v2.md +++ /dev/null @@ -1,145 +0,0 @@ -# 接口变更记录 — 2026-04-14 11:00 - -> **提交** `6a9ec7ce` · **作者** wx · **时间** 2026-04-14 11:00:15 +0800 -> -> feat(product-v2): 实现10个internal接口 + order-v2 Feign改指v2 - -## 变更总览 - -- **hl-product-service-v2** - - 🆕 InternalProduct (+10 接口) - ---- - -## hl-product-service-v2 - -### 🆕 新增: InternalProduct - -### 📌 `GET` /internal/product/{productId}/detail — 产品详情（内部） - -> 不过滤状态，供订单创建时获取产品快照 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/product/{productId}/automation-config — 保险/合同配置 - -> 返回保险方案ID、合同方案ID、预订条款ID、温馨提示ID - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/product/{productId}/simple-quote — 简单报价 - -> 根据日期和人数计算各人群单价和总价 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `adultCount` (`int`) — 查询参数 - - `childCount` (`int`) — 查询参数 - - `youngChildCount` (`int`) — 查询参数：小童数 - - `babyCount` (`int`) — 查询参数：幼童数 - - `childNeedBed` (`boolean`) — 查询参数：儿童是否需要加床 - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /internal/product/{productId}/deduct-stock — 扣库存 - -> 乐观锁扣减，库存不足返回错误 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `count` (`int`) — 查询参数 - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/{productId}/restore-stock — 恢复库存 - -> 取消/退款时恢复已扣库存 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `count` (`int`) — 查询参数 - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/batch/{batchId}/enroll — 报名入团 - -> 乐观锁扣减人数+房间名额，名额不足返回错误 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - - `peopleCount` (`int`) — 查询参数 - - `roomCount` (`int`) — 查询参数 - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/batch/{batchId}/unenroll — 取消报名 - -> 取消/退款时回退人数和房间名额 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - - `peopleCount` (`int`) — 查询参数 - - `roomCount` (`int`) — 查询参数 - -**响应** `Result<Void>` - -### 📌 `GET` /internal/product/batch/{batchId}/info — 团期信息 - -> 获取班期详细信息 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<Map<String, Object>>` - -### 📌 `GET` /internal/product/batch/{batchId}/quote — 团期报价 - -> 根据人数和房间数计算团期报价 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - - `adultCount` (`int`) — 查询参数 - - `childCount` (`int`) — 查询参数 - - `roomCount` (`int`) — 查询参数 - -**响应** `Result<Map<String, Object>>` - -### 📌 `POST` /internal/product/{productId}/custom-status — 定制产品状态变更 - -> 内部触发产品状态变更（通过COLA状态机） - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `status` (`String`) — 查询参数 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service-v2/src/main/java/com/hulalv/shared/feign/ProductFeignClient.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/internal/InternalProductController.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/GroupTourBatchMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductPriceCalendarMapper.java -A hl-product-service-v2/src/main/java/com/hulalv/service/internal/InternalProductService.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_1124_cdad0c87_feat_product-v2.md b/changelogs/2026-04/2026-04-14_1124_cdad0c87_feat_product-v2.md deleted file mode 100644 index 7a510df..0000000 --- a/changelogs/2026-04/2026-04-14_1124_cdad0c87_feat_product-v2.md +++ /dev/null @@ -1,191 +0,0 @@ -# 接口变更记录 — 2026-04-14 11:24 - -> **提交** `cdad0c87` · **作者** wx · **时间** 2026-04-14 11:00:15 +0800 -> -> feat(product-v2): 实现10个internal接口(VO返回) + order-v2 Feign改指v2 - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (改1) - - 🆕 InternalProduct (+6 接口) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### ✏️ `GET` /admin/product/item/{id}/suggest-price — 建议售价 - -- 返回类型: `Result<Map<String, Object>>` → `Result<ResourceSuggestPriceRespVO>` -- 🆕 新增响应类型 `ResourceSuggestPriceRespVO` - -**响应变更** `ResourceSuggestPriceRespVO`: - - - 🆕 `adultPrice` (`BigDecimal`) — 成人建议售价(含酒店) - - 🆕 `childPrice` (`BigDecimal`) — 儿童建议售价(不含酒店) - - 🆕 `resourceCost` (`BigDecimal`) — 资源成本(景区+活动+服务) - - 🆕 `hotelCost` (`BigDecimal`) — 酒店成本 - - 🆕 `suppliesCost` (`BigDecimal`) — 备品成本 - - 🆕 `extraCost` (`BigDecimal`) — 额外成本 - - 🆕 `tripDays` (`Integer`) — 行程天数 - - 🆕 `costDetails` (`List<Map<String, Object>>`) — 成本明细列表 - -### 🆕 新增: InternalProduct - -### 📌 `GET` /internal/product/internal/product - -### 📌 `GET` /internal/product/{productId}/detail — 获取产品详情（内部） - -> 不过滤状态，供order-service创建订单时获取快照。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<InternalProductDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `productType` | `String` | 产品类型(CORE/GROUP/CUSTOM) | -| `category` | `String` | 产品分类(family/honeymoon/photography/experience/driving) | -| `status` | `String` | 产品状态(DRAFT/PUBLISHED等) | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `coverImageUrl` | `String` | 封面图URL | -| `lineId` | `Long` | 产品线ID | -| `tiers` | `Object` | 档位列表JSON | -| `seasons` | `Object` | 适用季节 | -| `tags` | `Object` | 产品标签 | -| `carouselImages` | `Object` | 轮播图JSON | -| `itinerary` | `List<Object>` | 行程天列表 | - -### 📌 `GET` /internal/product/{productId}/simple-quote — 简单报价（内部） - -> 从价格日历取售价乘以人数，返回各人群小计和总价。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `childNeedBed` (`boolean`) — 查询参数：儿童加床 - -**响应** `Result<InternalSimpleQuoteVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultPrice` | `BigDecimal` | 成人单价 | -| `childPrice` | `BigDecimal` | 儿童单价 | -| `toddlerPrice` | `BigDecimal` | 小童单价 | -| `infantPrice` | `BigDecimal` | 幼童单价 | -| `adultCount` | `Integer` | 成人数量 | -| `childCount` | `Integer` | 儿童数量 | -| `youngChildCount` | `Integer` | 小童数量 | -| `babyCount` | `Integer` | 幼童数量 | -| `adultTotal` | `BigDecimal` | 成人小计 | -| `childTotal` | `BigDecimal` | 儿童小计 | -| `toddlerTotal` | `BigDecimal` | 小童小计 | -| `infantTotal` | `BigDecimal` | 幼童小计 | -| `totalPrice` | `BigDecimal` | 总价 | -| `paymentType` | `String` | 支付方式(FULL/DEPOSIT) | -| `depositRatio` | `Integer` | 订金比例(%) | -| `depositAmount` | `BigDecimal` | 订金金额 | -| `stock` | `Integer` | 剩余库存 | - -### 📌 `GET` /internal/product/{productId}/automation-config — 获取自动化配置（内部） - -> 供order-service创建订单时获取保险方案、合同配置和支付方式。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<InternalAutomationConfigVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceSchemeId` | `Long` | 保险方案ID | -| `contractSchemeId` | `Long` | 合同方案ID | -| `bookingTermsId` | `Long` | 预订条款ID | -| `warmTipsId` | `Long` | 温馨提示ID | -| `paymentType` | `String` | 支付方式(FULL/DEPOSIT) | -| `depositRatio` | `Integer` | 订金比例(%) | -| `depositAmount` | `BigDecimal` | 订金固定额 | - -### 📌 `GET` /internal/product/batch/{batchId}/info — 获取班期信息（内部） - -> 供order-service创建订单时获取班期快照。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<InternalBatchInfoVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | 班期ID | -| `productId` | `Long` | 产品ID | -| `batchNo` | `String` | 班期编号 | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `String` | 出发日期 | -| `endDate` | `String` | 结束日期 | -| `enrollmentDeadline` | `String` | 报名截止日 | -| `batchStatus` | `String` | 班期状态(ENROLLING/CONFIRMED/FULL等) | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `enrolledCount` | `Integer` | 已报名人数 | -| `remainingSlots` | `Integer` | 剩余名额 | -| `maxRooms` | `Integer` | 最大房间数 | -| `bookedRooms` | `Integer` | 已预订房间数 | -| `remainingRooms` | `Integer` | 剩余房间数 | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | - -### 📌 `GET` /internal/product/batch/{batchId}/quote — 班期报价（内部） - -> 供order-service获取GROUP产品按人数/房间的报价。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<InternalBatchQuoteVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultPrice` | `BigDecimal` | 成人单价 | -| `childPrice` | `BigDecimal` | 儿童单价 | -| `adultCount` | `Integer` | 成人数量 | -| `childCount` | `Integer` | 儿童数量 | -| `roomCount` | `Integer` | 房间数量 | -| `adultTotal` | `BigDecimal` | 成人小计 | -| `childTotal` | `BigDecimal` | 儿童小计 | -| `grandTotal` | `BigDecimal` | 总价 | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service-v2/src/main/java/com/hulalv/shared/feign/ProductFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/internal/InternalProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/feign/ResourceDetailFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/GroupTourBatchMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductPriceCalendarMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/service/admin/AmapDrivingService.java -M hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductPricingService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/internal/InternalProductService.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ResourceSuggestPriceRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalAutomationConfigVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalBatchInfoVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalBatchQuoteVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalProductDetailVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalSimpleQuoteVO.java -M hl-product-service-v2/src/test/java/com/hulalv/service/admin/AmapDrivingServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_1135_0eb66fcb_feat_product-v2.md b/changelogs/2026-04/2026-04-14_1135_0eb66fcb_feat_product-v2.md deleted file mode 100644 index 398b762..0000000 --- a/changelogs/2026-04/2026-04-14_1135_0eb66fcb_feat_product-v2.md +++ /dev/null @@ -1,191 +0,0 @@ -# 接口变更记录 — 2026-04-14 11:35 - -> **提交** `0eb66fcb` · **作者** wx · **时间** 2026-04-14 11:00:15 +0800 -> -> feat(product-v2): 实现10个internal接口(VO返回) + order-v2 Feign改指v2 - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (改1) - - 🆕 InternalProduct (+6 接口) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### ✏️ `GET` /admin/product/item/{id}/suggest-price — 建议售价 - -- 返回类型: `Result<Map<String, Object>>` → `Result<ResourceSuggestPriceRespVO>` -- 🆕 新增响应类型 `ResourceSuggestPriceRespVO` - -**响应变更** `ResourceSuggestPriceRespVO`: - - - 🆕 `adultPrice` (`BigDecimal`) — 成人建议售价(含酒店) - - 🆕 `childPrice` (`BigDecimal`) — 儿童建议售价(不含酒店) - - 🆕 `resourceCost` (`BigDecimal`) — 资源成本(景区+活动+服务) - - 🆕 `hotelCost` (`BigDecimal`) — 酒店成本 - - 🆕 `suppliesCost` (`BigDecimal`) — 备品成本 - - 🆕 `extraCost` (`BigDecimal`) — 额外成本 - - 🆕 `tripDays` (`Integer`) — 行程天数 - - 🆕 `costDetails` (`List<Map<String, Object>>`) — 成本明细列表 - -### 🆕 新增: InternalProduct - -### 📌 `GET` /internal/product/internal/product - -### 📌 `GET` /internal/product/{productId}/detail — 获取产品详情（内部） - -> 不过滤状态，供order-service创建订单时获取快照。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<InternalProductDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `productType` | `String` | 产品类型(CORE/GROUP/CUSTOM) | -| `category` | `String` | 产品分类(family/honeymoon/photography/experience/driving) | -| `status` | `String` | 产品状态(DRAFT/PUBLISHED等) | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `coverImageUrl` | `String` | 封面图URL | -| `lineId` | `Long` | 产品线ID | -| `tiers` | `Object` | 档位列表JSON | -| `seasons` | `Object` | 适用季节 | -| `tags` | `Object` | 产品标签 | -| `carouselImages` | `Object` | 轮播图JSON | -| `itinerary` | `List<Object>` | 行程天列表 | - -### 📌 `GET` /internal/product/{productId}/simple-quote — 简单报价（内部） - -> 从价格日历取售价乘以人数，返回各人群小计和总价。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `childNeedBed` (`boolean`) — 查询参数：儿童加床 - -**响应** `Result<InternalSimpleQuoteVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultPrice` | `BigDecimal` | 成人单价 | -| `childPrice` | `BigDecimal` | 儿童单价 | -| `toddlerPrice` | `BigDecimal` | 小童单价 | -| `infantPrice` | `BigDecimal` | 幼童单价 | -| `adultCount` | `Integer` | 成人数量 | -| `childCount` | `Integer` | 儿童数量 | -| `youngChildCount` | `Integer` | 小童数量 | -| `babyCount` | `Integer` | 幼童数量 | -| `adultTotal` | `BigDecimal` | 成人小计 | -| `childTotal` | `BigDecimal` | 儿童小计 | -| `toddlerTotal` | `BigDecimal` | 小童小计 | -| `infantTotal` | `BigDecimal` | 幼童小计 | -| `totalPrice` | `BigDecimal` | 总价 | -| `paymentType` | `String` | 支付方式(FULL/DEPOSIT) | -| `depositRatio` | `Integer` | 订金比例(%) | -| `depositAmount` | `BigDecimal` | 订金金额 | -| `stock` | `Integer` | 剩余库存 | - -### 📌 `GET` /internal/product/{productId}/automation-config — 获取自动化配置（内部） - -> 供order-service创建订单时获取保险方案、合同配置和支付方式。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<InternalAutomationConfigVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceSchemeId` | `Long` | 保险方案ID | -| `contractSchemeId` | `Long` | 合同方案ID | -| `bookingTermsId` | `Long` | 预订条款ID | -| `warmTipsId` | `Long` | 温馨提示ID | -| `paymentType` | `String` | 支付方式(FULL/DEPOSIT) | -| `depositRatio` | `Integer` | 订金比例(%) | -| `depositAmount` | `BigDecimal` | 订金固定额 | - -### 📌 `GET` /internal/product/batch/{batchId}/info — 获取班期信息（内部） - -> 供order-service创建订单时获取班期快照。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<InternalBatchInfoVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | 班期ID | -| `productId` | `Long` | 产品ID | -| `batchNo` | `String` | 班期编号 | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `String` | 出发日期 | -| `endDate` | `String` | 结束日期 | -| `enrollmentDeadline` | `String` | 报名截止日 | -| `batchStatus` | `String` | 班期状态(ENROLLING/CONFIRMED/FULL等) | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `enrolledCount` | `Integer` | 已报名人数 | -| `remainingSlots` | `Integer` | 剩余名额 | -| `maxRooms` | `Integer` | 最大房间数 | -| `bookedRooms` | `Integer` | 已预订房间数 | -| `remainingRooms` | `Integer` | 剩余房间数 | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | - -### 📌 `GET` /internal/product/batch/{batchId}/quote — 班期报价（内部） - -> 供order-service获取GROUP产品按人数/房间的报价。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<InternalBatchQuoteVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultPrice` | `BigDecimal` | 成人单价 | -| `childPrice` | `BigDecimal` | 儿童单价 | -| `adultCount` | `Integer` | 成人数量 | -| `childCount` | `Integer` | 儿童数量 | -| `roomCount` | `Integer` | 房间数量 | -| `adultTotal` | `BigDecimal` | 成人小计 | -| `childTotal` | `BigDecimal` | 儿童小计 | -| `grandTotal` | `BigDecimal` | 总价 | - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service-v2/src/main/java/com/hulalv/shared/feign/ProductFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/internal/InternalProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/feign/ResourceDetailFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/GroupTourBatchMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductPriceCalendarMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/service/admin/AmapDrivingService.java -M hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductPricingService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/internal/InternalProductService.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ResourceSuggestPriceRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalAutomationConfigVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalBatchInfoVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalBatchQuoteVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalProductDetailVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalSimpleQuoteVO.java -M hl-product-service-v2/src/test/java/com/hulalv/service/admin/AmapDrivingServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_1139_acf4d1e0_feat_product-v2.md b/changelogs/2026-04/2026-04-14_1139_acf4d1e0_feat_product-v2.md deleted file mode 100644 index 8fc5ae2..0000000 --- a/changelogs/2026-04/2026-04-14_1139_acf4d1e0_feat_product-v2.md +++ /dev/null @@ -1,246 +0,0 @@ -# 接口变更记录 — 2026-04-14 11:39 - -> **提交** `acf4d1e0` · **作者** wx · **时间** 2026-04-14 11:00:15 +0800 -> -> feat(product-v2): 实现10个internal接口(VO返回) + order-v2 Feign改指v2 - -## 变更总览 - -- **hl-product-service-v2** - - AdminProduct (改1) - - 🆕 InternalProduct (+11 接口) - ---- - -## hl-product-service-v2 - -### AdminProduct - -### ✏️ `GET` /admin/product/item/{id}/suggest-price — 建议售价 - -- 返回类型: `Result<Map<String, Object>>` → `Result<ResourceSuggestPriceRespVO>` -- 🆕 新增响应类型 `ResourceSuggestPriceRespVO` - -**响应变更** `ResourceSuggestPriceRespVO`: - - - 🆕 `adultPrice` (`BigDecimal`) — 成人建议售价(含酒店) - - 🆕 `childPrice` (`BigDecimal`) — 儿童建议售价(不含酒店) - - 🆕 `resourceCost` (`BigDecimal`) — 资源成本(景区+活动+服务) - - 🆕 `hotelCost` (`BigDecimal`) — 酒店成本 - - 🆕 `suppliesCost` (`BigDecimal`) — 备品成本 - - 🆕 `extraCost` (`BigDecimal`) — 额外成本 - - 🆕 `tripDays` (`Integer`) — 行程天数 - - 🆕 `costDetails` (`List<Map<String, Object>>`) — 成本明细列表 - -### 🆕 新增: InternalProduct - -### 📌 `GET` /internal/product/internal/product - -### 📌 `GET` /internal/product/{productId}/detail — 获取产品详情（内部） - -> 不过滤状态，供order-service创建订单时获取快照。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<InternalProductDetailVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `productId` | `Long` | 产品ID | -| `name` | `String` | 产品名称 | -| `subtitle` | `String` | 副标题 | -| `productType` | `String` | 产品类型(CORE/GROUP/CUSTOM) | -| `category` | `String` | 产品分类(family/honeymoon/photography/experience/driving) | -| `status` | `String` | 产品状态(DRAFT/PUBLISHED等) | -| `tripDays` | `Integer` | 行程天数 | -| `tripNights` | `Integer` | 行程晚数 | -| `coverImageUrl` | `String` | 封面图URL | -| `lineId` | `Long` | 产品线ID | -| `tiers` | `Object` | 档位列表JSON | -| `seasons` | `Object` | 适用季节 | -| `tags` | `Object` | 产品标签 | -| `carouselImages` | `Object` | 轮播图JSON | -| `itinerary` | `List<Object>` | 行程天列表 | - -### 📌 `GET` /internal/product/{productId}/simple-quote — 简单报价（内部） - -> 从价格日历取售价乘以人数，返回各人群小计和总价。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `childNeedBed` (`boolean`) — 查询参数：儿童加床 - -**响应** `Result<InternalSimpleQuoteVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultPrice` | `BigDecimal` | 成人单价 | -| `childPrice` | `BigDecimal` | 儿童单价 | -| `toddlerPrice` | `BigDecimal` | 小童单价 | -| `infantPrice` | `BigDecimal` | 幼童单价 | -| `adultCount` | `Integer` | 成人数量 | -| `childCount` | `Integer` | 儿童数量 | -| `youngChildCount` | `Integer` | 小童数量 | -| `babyCount` | `Integer` | 幼童数量 | -| `adultTotal` | `BigDecimal` | 成人小计 | -| `childTotal` | `BigDecimal` | 儿童小计 | -| `toddlerTotal` | `BigDecimal` | 小童小计 | -| `infantTotal` | `BigDecimal` | 幼童小计 | -| `totalPrice` | `BigDecimal` | 总价 | -| `paymentType` | `String` | 支付方式(FULL/DEPOSIT) | -| `depositRatio` | `Integer` | 订金比例(%) | -| `depositAmount` | `BigDecimal` | 订金金额 | -| `stock` | `Integer` | 剩余库存 | - -### 📌 `GET` /internal/product/{productId}/automation-config — 获取自动化配置（内部） - -> 供order-service创建订单时获取保险方案、合同配置和支付方式。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - -**响应** `Result<InternalAutomationConfigVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `insuranceSchemeId` | `Long` | 保险方案ID | -| `contractSchemeId` | `Long` | 合同方案ID | -| `bookingTermsId` | `Long` | 预订条款ID | -| `warmTipsId` | `Long` | 温馨提示ID | -| `paymentType` | `String` | 支付方式(FULL/DEPOSIT) | -| `depositRatio` | `Integer` | 订金比例(%) | -| `depositAmount` | `BigDecimal` | 订金固定额 | - -### 📌 `GET` /internal/product/batch/{batchId}/info — 获取班期信息（内部） - -> 供order-service创建订单时获取班期快照。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<InternalBatchInfoVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `batchId` | `Long` | 班期ID | -| `productId` | `Long` | 产品ID | -| `batchNo` | `String` | 班期编号 | -| `batchName` | `String` | 班期名称 | -| `departureDate` | `String` | 出发日期 | -| `endDate` | `String` | 结束日期 | -| `enrollmentDeadline` | `String` | 报名截止日 | -| `batchStatus` | `String` | 班期状态(ENROLLING/CONFIRMED/FULL等) | -| `maxParticipants` | `Integer` | 最大参与人数 | -| `enrolledCount` | `Integer` | 已报名人数 | -| `remainingSlots` | `Integer` | 剩余名额 | -| `maxRooms` | `Integer` | 最大房间数 | -| `bookedRooms` | `Integer` | 已预订房间数 | -| `remainingRooms` | `Integer` | 剩余房间数 | -| `adultPrice` | `BigDecimal` | 成人价 | -| `childPrice` | `BigDecimal` | 儿童价 | - -### 📌 `GET` /internal/product/batch/{batchId}/quote — 班期报价（内部） - -> 供order-service获取GROUP产品按人数/房间的报价。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - -**响应** `Result<InternalBatchQuoteVO>` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `adultPrice` | `BigDecimal` | 成人单价 | -| `childPrice` | `BigDecimal` | 儿童单价 | -| `adultCount` | `Integer` | 成人数量 | -| `childCount` | `Integer` | 儿童数量 | -| `roomCount` | `Integer` | 房间数量 | -| `adultTotal` | `BigDecimal` | 成人小计 | -| `childTotal` | `BigDecimal` | 儿童小计 | -| `grandTotal` | `BigDecimal` | 总价 | - -### 📌 `POST` /internal/product/{productId}/deduct-stock — 扣减库存（内部） - -> 乐观锁扣减价格日历库存。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `date` (`String`) — 查询参数：日期(yyyy-MM-dd) - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/{productId}/restore-stock — 恢复库存（内部） - -> 订单取消/过期时恢复库存。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `date` (`String`) — 查询参数：日期(yyyy-MM-dd) - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/batch/{batchId}/enroll — 报名入团（内部） - -> 乐观锁报名。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - - `roomCount` (`int`) — 查询参数：预订房间数 - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/batch/{batchId}/unenroll — 取消报名（内部） - -> 归还名额和房间。 - -**参数** - - - `{batchId}` (`Long`) — 路径参数：班期ID - - `roomCount` (`int`) — 查询参数：归还房间数 - -**响应** `Result<Void>` - -### 📌 `POST` /internal/product/{productId}/custom-status — 变更定制产品状态（内部） - -> 仅CUSTOM类型。 - -**参数** - - - `{productId}` (`Long`) — 路径参数：产品ID - - `status` (`String`) — 查询参数：目标状态 - -**响应** `Result<Void>` - ---- - -<details> -<summary>📁 全部变更文件 (点击展开)</summary> - -``` -M hl-order-service-v2/src/main/java/com/hulalv/shared/feign/ProductFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/controller/admin/AdminProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/controller/internal/InternalProductController.java -A hl-product-service-v2/src/main/java/com/hulalv/feign/ResourceDetailFeignClient.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/GroupTourBatchMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/mapper/ProductPriceCalendarMapper.java -M hl-product-service-v2/src/main/java/com/hulalv/service/admin/AmapDrivingService.java -M hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductPricingService.java -A hl-product-service-v2/src/main/java/com/hulalv/service/internal/InternalProductService.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ResourceSuggestPriceRespVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalAutomationConfigVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalBatchInfoVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalBatchQuoteVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalProductDetailVO.java -A hl-product-service-v2/src/main/java/com/hulalv/vo/internal/InternalSimpleQuoteVO.java -M hl-product-service-v2/src/test/java/com/hulalv/service/admin/AmapDrivingServiceTest.java -``` -</details> \ No newline at end of file diff --git a/changelogs/2026-04/2026-04-14_product-v2_batch_update.md b/changelogs/2026-04/2026-04-14_product-v2_batch_update.md deleted file mode 100644 index 52ce01b..0000000 --- a/changelogs/2026-04/2026-04-14_product-v2_batch_update.md +++ /dev/null @@ -1,126 +0,0 @@ -# 产品v2 - 批量更新汇总 (4/13-4/14) - -**日期**: 2026-04-14 -**服务**: product-service-v2, hl-starter-mybatis -**类型**: 新增接口 + Bug修复 + 模块搬迁 -**PR**: #431, #433, #442, #446, #447, #448, #449, #450, #451, #457, #472, #474 - ---- - -## 一、新增接口 - -### 1. 计算行程总里程 -`GET /admin/product/item/{productId}/calculate-mileage` - -根据行程途经点坐标调用高德驾车路线规划API自动计算总驾驶里程。 - -**返回**: -```json -{"code": 200, "data": 690.2} -``` -- data: 总里程(km)，保留1位小数 -- 前提：产品需先保存行程(Step2)，至少2个有效途经点 - -**建议交互**: Step3页面提供"自动计算里程"按钮，调此接口填充总里程输入框。 - ---- - -### 2. 温馨提示管理（从v1搬迁） -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/warm-tips/list` | 全部列表（含禁用） | -| GET | `/admin/product/warm-tips/enabled` | 启用列表（下拉选择用） | -| GET | `/admin/product/warm-tips/{tipsId}` | 详情 | -| POST | `/admin/product/warm-tips` | 创建 | -| PUT | `/admin/product/warm-tips/{tipsId}` | 修改 | -| DELETE | `/admin/product/warm-tips/{tipsId}` | 删除（软删） | -| PUT | `/admin/product/warm-tips/{tipsId}/toggle?enabled=true/false` | 启用/禁用 | - -**请求体**(创建/修改): -```json -{"tipsName": "草原游温馨提示", "content": "<p>富文本内容</p>", "remark": "备注"} -``` - ---- - -### 3. 预订条款管理（从v1搬迁） -接口结构与温馨提示完全一致，路径前缀改为 `/admin/product/booking-terms`，字段名改为 `termsId`/`termsName`。 - ---- - -### 4. 报价公式管理（从v1搬迁） - -#### 公式组 -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/formula/group/list?productType=CORE` | 公式组列表 | -| GET | `/admin/product/formula/group/{groupId}` | 详情 | -| POST | `/admin/product/formula/group` | 创建 | -| PUT | `/admin/product/formula/group/{groupId}` | 修改 | -| PUT | `/admin/product/formula/group/{groupId}/activate` | 激活（排他） | -| DELETE | `/admin/product/formula/group/{groupId}` | 删除 | - -#### 公式步骤 -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/formula/group/{groupId}/steps` | 步骤列表 | -| GET | `/admin/product/formula/step/{formulaId}` | 步骤详情 | -| POST | `/admin/product/formula/step` | 创建步骤 | -| PUT | `/admin/product/formula/step/{formulaId}` | 修改步骤 | -| PUT | `/admin/product/formula/step/{formulaId}/toggle` | 启用/禁用 | -| DELETE | `/admin/product/formula/step/{formulaId}` | 删除 | -| GET | `/admin/product/formula/step/{formulaId}/versions` | 版本历史 | -| PUT | `/admin/product/formula/step/{formulaId}/rollback/{versionNum}` | 回滚版本 | - -#### 公式变量 -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/formula/var/list?category=INPUT` | 变量列表 | -| POST | `/admin/product/formula/var` | 创建变量 | -| PUT | `/admin/product/formula/var/{varId}` | 修改变量 | -| DELETE | `/admin/product/formula/var/{varId}` | 删除 | - -#### 公式测试 -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/product/formula/test` | 测试执行 | - ---- - -## 二、Bug修复 - -### 1. 产品详情 routeInfo 返回null（已修复） -**原因**: SQL JOIN返回扁平的totalMileage/routeDescription/routeMapUrl字段，但VO期望嵌套routeInfo对象，BeanUtil无法自动映射。 -**影响**: Step3保存的总里程/线路描述回显为空。 -**现在**: routeInfo正常返回嵌套对象。 - -### 2. 详情接口返回数据清理（已修复） -- **routePoints**: 去掉了createTime/updateTime/createdBy等审计字段，只返回`id/resourceId/name/longitude/latitude/sortOrder` -- **nodes/hotels/days**: 同样去掉审计字段 -- **JSON字段反序列化**: photoUrls/customFields/images/extraData从JSON字符串正确转为对象/数组 - -### 3. supplement JSON字段双重转义（已修复） -**原因**: quickUnderstand/childExperience/growthGains等JSON字段以String存储，Jackson序列化时双重转义。 -**方案**: 新增全局`JsonObjectTypeHandler`，Entity字段改为Object + `@TableField(typeHandler)`，自动在DB和Java间转换JSON。 -**影响**: 前端之前收到的是转义字符串`"{\"title\":\"xxx\"}"`,现在收到正常JSON对象`{"title":"xxx"}`。 - -### 4. 行程保存事务不生效（已修复） -**原因**: saveItinerary()自调用doSaveItinerary()，Spring AOP代理不拦截，@Transactional无效。 -**影响**: 保存行程时报"Transaction synchronization is not active"。 -**现在**: 通过@Lazy setter注入自身代理解决。 - -### 5. 无效住宿记录过滤（已修复） -**原因**: 前端传空住宿对象`{}`时后端直接插入，导致hotel_name=NULL显示"未知"。 -**现在**: 新增住宿必须有hotelId才插入。 - -### 6. 模板Controller路由冲突（已修复） -AdminProductTemplateController的`/booking-terms/enabled`和`/warm-tips/enabled`已迁移到独立Controller，旧方法已删除。 - ---- - -## 三、前端注意事项 - -1. **报价公式/温馨提示/预订条款页面**: 接口已从v1迁移到v2，路径不变，无需前端改动 -2. **Step3里程**: 可调用`GET /{id}/calculate-mileage`自动计算填充 -3. **supplement字段**: quickUnderstand/childExperience/growthGains现在返回JSON对象而非字符串，如果前端之前有`JSON.parse()`处理需要去掉 -4. **routePoints**: 字段减少了，只有`id/resourceId/name/longitude/latitude/sortOrder` diff --git a/changelogs/2026-04/2026-04-14_product-v2_daily_summary.md b/changelogs/2026-04/2026-04-14_product-v2_daily_summary.md deleted file mode 100644 index 8197722..0000000 --- a/changelogs/2026-04/2026-04-14_product-v2_daily_summary.md +++ /dev/null @@ -1,95 +0,0 @@ -# 产品v2 - 今日变更汇总 (2026-04-14) - -**日期**: 2026-04-14 -**服务**: product-service-v2 -**类型**: 新增接口 + bug修复 + 模块搬迁 - ---- - -## 一、新增接口 - -### 1. 计算行程总里程 -- `GET /admin/product/item/{productId}/calculate-mileage` -- 根据行程途经点调用高德驾车路线API自动计算里程(km) -- 返回: `{"code":200, "data": 690.2}` -- 前端建议: Step3页面提供"自动计算"按钮调此接口填充总里程 - -### 2. 温馨提示管理 `/admin/product/warm-tips/**` -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | /list | 全部列表(含禁用) | -| GET | /enabled | 启用的列表(下拉用) | -| GET | /{tipsId} | 详情 | -| POST | / | 创建 | -| PUT | /{tipsId} | 修改 | -| DELETE | /{tipsId} | 删除(软删) | -| PUT | /{tipsId}/toggle?enabled=true/false | 启用/禁用 | - -### 3. 预订条款管理 `/admin/product/booking-terms/**` -接口结构同温馨提示，字段: termsId/termsName/content/enabled/remark - -### 4. 报价公式管理 `/admin/product/formula/**` -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | /group/list?productType= | 公式组列表 | -| GET | /group/{groupId} | 公式组详情 | -| POST | /group | 创建公式组 | -| PUT | /group/{groupId} | 更新公式组 | -| PUT | /group/{groupId}/activate | 激活公式组 | -| DELETE | /group/{groupId} | 删除公式组 | -| GET | /group/{groupId}/steps | 步骤列表 | -| GET | /step/{formulaId} | 步骤详情 | -| POST | /step | 创建步骤 | -| PUT | /step/{formulaId} | 更新步骤 | -| PUT | /step/{formulaId}/toggle | 启用/禁用步骤 | -| DELETE | /step/{formulaId} | 删除步骤 | -| GET | /step/{formulaId}/versions | 版本历史 | -| PUT | /step/{formulaId}/rollback/{versionNum} | 回滚 | -| POST | /test | 测试公式执行 | -| GET | /var/list?category= | 变量列表 | -| POST | /var | 创建变量 | -| PUT | /var/{varId} | 更新变量 | -| DELETE | /var/{varId} | 删除变量 | - -**注意**: 公式相关RespVO中ID字段类型为Long(不是String) - ---- - -## 二、Bug修复 - -### 1. 产品详情routeInfo返回null (已修) -- 原因: SQL返回扁平字段(totalMileage/routeDescription/routeMapUrl)，VO是嵌套对象，BeanUtil无法映射 -- 修复: 手动组装routeInfo/supplement/crowdBenefit嵌套对象 - -### 2. 行程子数据返回多余审计字段 (已修) -- 原因: nodes/hotels/routePoints直接返回DO对象，包含createTime/updatedBy等 -- 修复: 返回前去掉BaseDO字段，JSON字段(images/extraData/photoUrls)正确反序列化 - -### 3. Step1创建时多个字段丢失 (已修) -- 原因: doCreate方法只set了name/productType/lineId/tripDays，漏了subtitle/category/introduction/seasons/carouselImages等 -- 修复: 补全全部字段 - -### 4. 行程保存事务不生效 (已修) -- 原因: saveItinerary()自调用doSaveItinerary()绕过AOP代理 -- 修复: @Lazy setter注入自身代理 - ---- - -## 三、前端注意事项 - -### Step1 基础信息 -- `seasons`和`carouselImages`现在能正常保存和返回了 -- `balanceDueDays`(尾款截止天数)字段**不需要展示**，尾款在行程中由领队收取，前端隐藏"尾款须在出发前N天付清"输入框 - -### Step2 行程编排 -- routePoints返回字段精简为: `id/resourceId/name/longitude/latitude/sortOrder` (无审计字段) -- nodes的`images`和`extraData`已从JSON字符串反序列化为对象 -- days的`photoUrls`和`customFields`同样已反序列化 - -### Step3 路线与备品 -- `GET /{productId}/calculate-mileage` 可用于自动计算里程 - -### Step5 补充信息 -- 详情返回中`supplement`和`crowdBenefit`现在是嵌套对象(之前是null) -- `supplement`包含: quickUnderstand/childExperience/growthGains/insuranceNotice/equipmentAdvice/refundPolicyIds/feeIgnoredTypes/vehicleModelIds -- `crowdBenefit`包含: tips diff --git a/changelogs/2026-04/2026-04-14_product-v2_remove_deposit_deadline.md b/changelogs/2026-04/2026-04-14_product-v2_remove_deposit_deadline.md deleted file mode 100644 index b854e92..0000000 --- a/changelogs/2026-04/2026-04-14_product-v2_remove_deposit_deadline.md +++ /dev/null @@ -1,26 +0,0 @@ -# 前端修复 - 去掉"尾款须在出发前N天付清"显示 - -**日期**: 2026-04-14 -**类型**: 前端修复 -**优先级**: P1 - ---- - -## 问题 - -Step1 基础信息页面，选择"订金+尾款"支付方式时，页面始终显示"尾款须在出发前 7 天付清"。 - -## 原因 - -后端 v2 已移除 `depositDeadlineDays` 字段： -- 数据库 `product_basic` 表没有此列 -- 详情接口返回中不包含此字段 -- 前端代码中硬编码了默认值 7 - -## 修复方式 - -前端去掉"尾款须在出发前 X 天付清"这一行输入框，或改为：当接口返回中不含 `depositDeadlineDays` 字段时不显示。 - -## 验证 - -`GET /admin/product/item/{id}` 返回的 JSON 中搜索 `depositDeadlineDays`，确认不存在该 key。 diff --git a/changelogs/2026-04/2026-04-14_product-v2_simple_list_for_order.md b/changelogs/2026-04/2026-04-14_product-v2_simple_list_for_order.md deleted file mode 100644 index 2a96be0..0000000 --- a/changelogs/2026-04/2026-04-14_product-v2_simple_list_for_order.md +++ /dev/null @@ -1,108 +0,0 @@ -# 接口变更记录 — 2026-04-14 - -> **变更类型**：新增接口 + 废弃旧接口 -> **影响模块**：订单创建 → 选择商品弹窗 -> **在线文档**： -> - 局域网：http://192.168.100.236:8080/doc.html → `1. 管理端 - 产品管理` -> - 公网：https://api.test.1814.love:9443/doc.html（需认证） - ---- - -## 新增「商品选择列表」接口（订单创建用） - -订单创建时「选择商品」弹窗原来调的是 `GET /admin/order/product/page`（404，后端从未实现）。现在由产品服务提供专用轻量接口。 - -### 旧接口（废弃，404） - -``` -GET /admin/order/product/page ← 删掉，不要再调 -``` - -### 新接口 - -``` -GET /admin/product/item/simple-list -``` - -### 请求参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| keyword | String | 否 | 搜索关键词（匹配产品名称） | -| pageNo | Integer | 否 | 页码，默认1 | -| pageSize | Integer | 否 | 每页条数，默认50 | - -> 不需要传 productType / status 等参数，后端固定只返回**已上架**产品。 - -### 响应字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| productId | Long | 产品ID | -| productNo | String | 产品编号（如 C260409001） | -| name | String | 产品名称 | -| tripDays | Integer | 行程天数 | -| lineName | String | 产品线名称（LEFT JOIN 查出） | - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "records": [ - { - "productId": 2043895196659171329, - "productNo": "C260409001", - "name": "呼伦贝尔5日深度游", - "tripDays": 5, - "lineName": "呼伦贝尔经典线" - } - ], - "total": 12, - "page": 1, - "pageSize": 50 - } -} -``` - -### 前端改动清单 - -**文件**：`src/api/order.js` 第555-556行 - -```javascript -// 旧 -export function getOrderProductPage(params) { - return http.get('/order/product/page', params) -} - -// 新 -export function getOrderProductPage(params) { - return http.get('/product/item/simple-list', params) -} -``` - -**参数名映射**（需同步修改调用处）： - -| 旧参数 | 新参数 | -|--------|--------| -| name | keyword | -| page | pageNo | -| limit | pageSize | - -**响应字段映射**（需同步修改弹窗组件）： - -| 旧字段 | 新字段 | -|--------|--------| -| res.list | res.records | -| row.id | row.productId | - -涉及的 Vue 文件：`src/views/order/components/OrderEditModal.vue` 第525-531行、第542行。 - ---- - -## 关联信息 - -- Issue：#500 -- PR：#501 diff --git a/changelogs/2026-04/2026-04-15_product-v2_design-revamp-8items.md b/changelogs/2026-04/2026-04-15_product-v2_design-revamp-8items.md deleted file mode 100644 index 6212b57..0000000 --- a/changelogs/2026-04/2026-04-15_product-v2_design-revamp-8items.md +++ /dev/null @@ -1,190 +0,0 @@ -# 产品设计页面改版（8项改进） - -- **日期**: 2026-04-15 -- **服务**: hl-product-service-v2, hl-gateway -- **PR**: #602 -- **Issue**: #601 -- **类型**: feat (新功能) - -## 概述 - -产品设计页面（Step2行程/Step3路线/Step5补充）和小程序详情页的一组改进，涉及8项需求。 - ---- - -## 1. 行程节点名可自定义 - -保存行程时，`nodeName` 由前端自定义（用户可改），`resourceName` 由后端自动填充资源原名快照，互不影响。 - -**行为变更**： -- `PUT /admin/product/item/{id}/itinerary` 保存时自动通过Feign查资源名填充 `resourceName` -- 前端传什么 `nodeName` 就存什么，改名不影响资源库 - -**响应字段**： -| 字段 | 说明 | -|------|------| -| `nodeName` | 展示名称（可自定义） | -| `resourceName` | 资源原名快照（自动填充，不可改） | - ---- - -## 2. 每日行程距离计算接口 - -### 新增接口 - -``` -GET /admin/product/item/{productId}/daily-mileage -``` - -按天计算每日驾车距离（含酒店坐标），调用高德驾车路线规划API。 - -**响应示例**： -```json -{ - "code": 200, - "data": [ - {"dayNumber": 1, "mileage": 280.5}, - {"dayNumber": 2, "mileage": 195.3}, - {"dayNumber": 3, "mileage": 320.1} - ] -} -``` - ---- - -## 3. 行程线路名称 - -### GET /mp/product/{id} 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `routeName` | String | 路线名称（如"草原环线体验"） | - -### PUT /admin/product/item/{id}/route（Step3保存）新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `routeName` | String | 路线名称 | - ---- - -## 4. 集合地/出发地/解散地 - -### ⚠️ 保存位置：Step2 行程编排（不是Step3） - -⚠️ **出发地已删除**（与集合地相同），只保留集合地+解散地。 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `gatherPlace` | String | 集合地（高德行政区搜索到镇级） | -| `dismissalPlace` | String | 解散地（高德行政区搜索到镇级） | - -这2个字段在以下接口中可读写： -- **`PUT /admin/product/item/{id}/itinerary`（Step2保存，主入口）** — 可单独传这2个字段不传days -- `PUT /admin/product/item/{id}/route`（Step3保存，也可设置） -- `GET /admin/product/item/{id}`（管理端详情，在routeInfo中） -- `GET /mp/product/{id}`（小程序详情） - ---- - -## 5. 产品卖点改为选择节点 - -`quickUnderstand` 字段结构变更（后端仍为JSON存取，无接口变化）： - -**旧结构**：`{text: "富文本", images: [...]}` - -**新结构**： -```json -[ - { - "nodeId": 12345, - "nodeName": "白桦林景区", - "nodeType": "SCENIC", - "image": "https://...", - "description": "走进白桦林..." - } -] -``` - -前端在Step5选择行程中的景区/游玩项目节点，按新结构传即可。后端原样存取。 - ---- - -## 6. 行程保障模板（全新CRUD） - -### 新增接口 - -| 方法 | URL | 说明 | -|------|-----|------| -| POST | `/admin/travel-guarantee-template` | 创建/更新模板 | -| DELETE | `/admin/travel-guarantee-template/{id}` | 删除模板 | -| GET | `/admin/travel-guarantee-template/list` | 全部模板列表（含禁用） | -| GET | `/admin/travel-guarantee-template/enabled` | 启用模板下拉（Step5选择用） | -| GET | `/admin/travel-guarantee-template/{id}` | 模板详情 | - -**创建/更新请求体**： -```json -{ - "templateId": null, - "name": "标准行程保障", - "items": [ - {"icon": "shield", "title": "无忧退改", "description": "出发前7天全额退款"}, - {"icon": "users", "title": "5人专属团队", "description": "定制+管家+摄影+领队+客服"}, - {"icon": "clock", "title": "24小时客服", "description": "200位真实客服即时响应"}, - {"icon": "badge", "title": "旅行社责任险100万", "description": "正规资质全程投保"}, - {"icon": "heart", "title": "全程纯玩无购物", "description": "无强制消费无隐形购物点"} - ], - "isDefault": false -} -``` - -**Step5补充信息保存** 新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `guaranteeTemplateId` | Long | 行程保障模板ID | - -**小程序详情** 新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `guaranteeItems` | Array | 行程保障项（自动解析模板内容） | - ---- - -## 7. 线路概览自动生成 - -保存行程（Step2）后，自动根据各天的景区/活动节点名称生成线路概览文本，写入 `routeDescription`。 - -**生成格式示例**： -``` -Day1 海拉尔/额尔古纳 | Day2 呼籁营地/牧云山顶 | Day3 白桦林/恩和 | Day4-5 满洲里/返程 -``` - -连续天节点相同时自动合并（如Day4-5）。 - ---- - -## 8. 评价取真实数据 - -### GET /mp/product/{id} 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `reviewSummary` | Object | 评价摘要（从评价服务实时获取） | - -`reviewSummary` 结构（由评价服务 `/internal/review/product-highlights` 返回）： -```json -{ - "avgScore": 4.9, - "totalCount": 296, - "topReview": { - "content": "超赞的行程！呼籁营地安静私密...", - "nickname": "小明同学", - "reviewTime": "2026-03" - }, - "tags": ["安静私密", "孩子玩疯了", "管家贴心", "强烈推荐"] -} -``` - -评价服务不可用时该字段为null，不影响其他数据。 diff --git a/changelogs/2026-04/2026-04-15_product-v2_detail_blocks.md b/changelogs/2026-04/2026-04-15_product-v2_detail_blocks.md deleted file mode 100644 index d73d813..0000000 --- a/changelogs/2026-04/2026-04-15_product-v2_detail_blocks.md +++ /dev/null @@ -1,143 +0,0 @@ -# 产品详情页自定义区块（GROUP产品专用） - -- **日期**: 2026-04-15 -- **服务**: hl-product-service-v2 -- **PR**: #584 -- **类型**: feat (新功能) - -## 概述 - -GROUP（小蒙马）产品的小程序详情页支持后台自定义设计，不再使用自动生成的页面。通过独立接口保存/读取一个大JSON，存储页面区块配置。 - -## 新增接口 - -### 1. 获取详情页区块 - -``` -GET /admin/product/item/{productId}/detail-blocks -``` - -**响应示例**（未设置时data为null）： -```json -{ - "code": 200, - "data": [ - { - "id": "block_1", - "type": "hero", - "visible": true, - "data": { - "backgroundImage": "", - "brandTitle": "小 蒙 马 · XIAOMENGMA", - "mainTitle": "趁童年尚好\n陪孩子去草原撒个欢", - "subtitle": "呼伦贝尔 · 6天5夜亲子游学", - "videoUrl": "https://xxx.mp4", - "videoDuration": "" - }, - "style": { - "height": 440, - "overlayGradient": ["#00000005", "#000000BB"] - } - }, - { - "id": "block_2", - "type": "experiences", - "visible": true, - "data": { - "icon": "baby", - "title": "这些事，值得带孩子来一趟", - "subtitle": "听风、画云、策马、寻迹，每一程都是成长", - "items": [ - { - "id": "item_1", - "image": "", - "icon": "music", - "title": "听 · 草原专属之声", - "description": "围坐草原，聆听马头琴与长调" - } - ] - }, - "style": { - "background": "#FFF7ED", - "padding": [32, 20], - "gap": 16 - } - } - ] -} -``` - -### 2. 保存详情页区块 - -``` -PUT /admin/product/item/{productId}/detail-blocks -Content-Type: application/json -``` - -**请求体**： -```json -{ - "detailBlocks": [ - { - "id": "block_xxx", - "type": "hero|experiences|faq|yearReview|leaderIntro|photographer|safety", - "visible": true, - "data": { ... }, - "style": { ... } - } - ] -} -``` - -**响应**： -```json -{ - "code": 200, - "message": "详情页区块保存成功" -} -``` - -## 已有接口变更 - -### 管理端产品详情 - -``` -GET /admin/product/item/{productId} -``` - -响应新增字段： -| 字段 | 类型 | 说明 | -|------|------|------| -| `detailBlocks` | Array/null | 小程序详情页自定义区块JSON，仅GROUP产品使用 | - -### 小程序端产品详情 - -``` -GET /mp/product/{productId} -``` - -响应新增字段： -| 字段 | 类型 | 说明 | -|------|------|------| -| `detailBlocks` | Array/null | GROUP产品返回自定义区块数组，CORE产品为null | - -## 区块类型说明 - -| type | 说明 | -|------|------| -| `hero` | 首屏大图/视频区 | -| `experiences` | 体验亮点列表 | -| `faq` | 常见问答 | -| `yearReview` | 年度回顾视频 | -| `leaderIntro` | 领队介绍 | -| `photographer` | 跟拍摄影师介绍 | -| `safety` | 安全保障 | - -区块结构由前端页面设计器定义，后端只负责整体存取，不校验内部结构。 - -## 注意事项 - -- 保存接口为**整体覆盖**，每次传完整的区块数组 -- `visible` 字段控制区块是否在小程序端展示 -- 仅GROUP产品使用此功能，CORE/CUSTOM产品该字段为null -- 数据库字段为 `MEDIUMTEXT`，支持大JSON存储 diff --git a/changelogs/2026-04/2026-04-15_product-v2_room-count-auto-and-tier-price.md b/changelogs/2026-04/2026-04-15_product-v2_room-count-auto-and-tier-price.md deleted file mode 100644 index 37be5d7..0000000 --- a/changelogs/2026-04/2026-04-15_product-v2_room-count-auto-and-tier-price.md +++ /dev/null @@ -1,68 +0,0 @@ -# 小蒙马房间数自动计算 + 多档位最低价 - -- **日期**: 2026-04-15 -- **服务**: hl-product-service-v2 -- **PR**: #595, #596 -- **类型**: feat (新功能) - -## 概述 - -1. 行程设计中的住宿房间数自动取最小值作为班期默认房间数，不再需要班期里单独传 -2. 多档位产品详情返回各档位各自的最低价 - -## 功能1：房间数自动计算 - -### 行为变更 - -- **保存行程（Step2）时**，后端自动计算各天住宿（档位1）的最小 `roomCount`，写入 `defaultRoomCount` - - 例：D1=8间、D2=9间、D3=8间 → `defaultRoomCount = 8` -- **创建班期时**，如果 `maxRooms` 未传或传0，自动使用 `defaultRoomCount` - - 批量创建班期同样适用 -- 如果手动传了 `maxRooms > 0`，仍以手动值为准 - -### 接口影响 - -无新增接口。现有接口行为变更： - -**PUT /admin/product/item/{id}/itinerary**（Step2 保存行程） -- 保存后自动更新 `defaultRoomCount` - -**POST /admin/product/item/{id}/schedule**（创建班期） -- `maxRooms` 为空或0时自动取 `defaultRoomCount` - -**POST /admin/product/item/{id}/schedule/batch-create**（批量创建班期） -- 同上 - -## 功能2：多档位最低价 - -### GET /mp/product/{id} 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `tierPrices` | Array/null | 各档位起步价，仅多档位产品返回 | - -`tierPrices` 数组元素结构： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `tierSeq` | Integer | 档位序号 | -| `tierName` | String | 档位名称 | -| `startPrice` | BigDecimal | 该档位未来可售最低成人售价 | - -### 响应示例 - -```json -{ - "startPrice": 7980.0, - "tierPrices": [ - {"tierSeq": 1, "tierName": "精选", "startPrice": 7980.0}, - {"tierSeq": 2, "tierName": "臻享", "startPrice": 9980.0} - ] -} -``` - -### 规则 - -- `startPrice` 保留为全局最低价（向后兼容） -- `tierPrices` 仅多档位产品返回，单档位产品为 `null` -- 每个档位的 `startPrice` 独立计算（未来日期 + 售价>0 的最低值） diff --git a/changelogs/2026-04/2026-04-15_product-v2_room-type-name-and-mq-sync.md b/changelogs/2026-04/2026-04-15_product-v2_room-type-name-and-mq-sync.md deleted file mode 100644 index 0784d8f..0000000 --- a/changelogs/2026-04/2026-04-15_product-v2_room-type-name-and-mq-sync.md +++ /dev/null @@ -1,61 +0,0 @@ -# 产品住宿返回房型名称 + 酒店/房型名称MQ自动同步 - -- **日期**: 2026-04-15 -- **服务**: hl-resource-service, hl-product-service-v2 -- **PR**: #590, #591 -- **类型**: fix + feat - -## 概述 - -修复产品详情中住宿只返回酒店名称、不返回房型名称的问题。同时新增MQ机制，资源服务修改酒店/房型名称后自动同步到产品侧快照。 - -## 已有接口变更 - -### 管理端产品详情 - -``` -GET /admin/product/item/{productId} -``` - -行程天中的住宿项（hotels）新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `roomTypeName` | String | 房型名称（之前只有roomTypeId没有名称） | - -### 小程序端产品详情 - -``` -GET /mp/product/{productId} -``` - -行程天中的住宿项（itinerary[].hotels[]）新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `roomTypeId` | Long | 房型ID | -| `roomTypeName` | String | 房型名称 | -| `roomCount` | Integer | 房间数 | - -### 小程序端档位对比 - -``` -GET /mp/product/{productId}/tier-compare -``` - -住宿项新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `roomTypeName` | String | 房型名称 | - -## 行为变更（无需前端改动） - -- 资源服务修改酒店名称 → 产品侧 `hotelName` 快照**自动同步更新** -- 资源服务修改房型名称 → 产品侧 `roomTypeName` 快照**自动同步更新** -- 同步完成后自动清除受影响产品的小程序端缓存 - -## 注意事项 - -- 已保存的产品需要**重新保存行程（Step2）**才会首次填充 `roomTypeName` -- 首次填充后，后续名称变更由MQ自动同步，无需重新保存 diff --git a/changelogs/2026-04/2026-04-16_mp-day-detail-api.md b/changelogs/2026-04/2026-04-16_mp-day-detail-api.md deleted file mode 100644 index 472b01c..0000000 --- a/changelogs/2026-04/2026-04-16_mp-day-detail-api.md +++ /dev/null @@ -1,78 +0,0 @@ -# 小程序每日行程详情接口 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #675 -- **类型**: feat (新接口) - -## 新增接口 - -``` -GET /mp/product/{productId}/day/{dayNumber} -``` - -返回指定天的完整行程详情，用于小程序每日详情页。 - -### 参数 - -| 参数 | 类型 | 说明 | -|------|------|------| -| `productId` | Long | 产品ID（路径参数） | -| `dayNumber` | Integer | 天序号，从1开始（路径参数） | - -### 响应字段 - -| 字段 | 类型 | 说明 | 对应原型 | -|------|------|------|---------| -| `dayNumber` | Integer | 天序号 | DAY 2 | -| `dayTitle` | String | 标题 | | -| `quoteText` | String | 每日金句 | 引用文字 | -| `description` | String | 描述 | | -| `coverImageUrl` | String | 封面图 | 顶部大图 | -| `gatherPlace` | Object | 集合地 {name,adcode,center,level} | | -| `dismissalPlace` | Object | 解散地（目的地） | 今日概况·目的地 | -| `dailyMileage` | BigDecimal | 当日里程(km) | 290km | -| `dailyDuration` | Integer | 当日驾车时长(分钟) | 约3.5小时 | -| `breakfast` | String | 早餐 | 今日概况·餐饮 | -| `lunch` | String | 午餐 | | -| `dinner` | String | 晚餐 | | -| `diningRemark` | String | 餐饮备注 | 含BBQ | -| `photoUrls` | List | 实拍照片 | 实拍照片区块 | -| `routePoints` | List | 途经路线 [{name, sortOrder}] | 海拉尔→呼籁营地→额尔古纳 | -| `nodes` | List | 节点列表 | 行程详情 + 今日体验 | -| `hotels` | List | 住宿列表 | 按档位分组展示 | - -### nodes[] 字段 - -| 字段 | 说明 | 用途 | -|------|------|------| -| `nodeType` | SCENIC/ACTIVITY/RESTAURANT/TRANSPORT等 | 行程详情用全部，今日体验只取ACTIVITY | -| `nodeName` | 节点名称 | 呼籁营地、牧云山顶 | -| `startTime` | 开始时间 | 上午、下午 | -| `durationMinutes` | 时长(分钟) | | -| `description` | 描述 | 节点下方的详细文字 | - -### hotels[] 字段 - -| 字段 | 说明 | -|------|------| -| `hotelName` | 酒店名称 | -| `tierSeq` | 档位序号（前端按此分组：1=舒适 2=高档） | -| `roomTypeName` | 房型名称 | -| `roomCount` | 房间数 | - -### 错误码 - -| 场景 | code | message | -|------|------|---------| -| 产品不存在/未上架 | 404 | 产品不存在或已下架 | -| 天序号不存在 | 404 | 行程天不存在: DayN | - -### 前端展示对照 - -- **途经路线**：`routePoints[].name` 用 " → " 连接 -- **里程时长**：`dailyMileage` + `dailyDuration`（分钟→"约X.X小时"） -- **今日概况·餐饮**：拼接 `breakfast/lunch/dinner`（HOTEL=含/SELF=自理/SPECIAL=特色）+ `diningRemark` -- **今日概况·目的地**：`dismissalPlace.name` -- **住宿分组**：按 `tierSeq` 分组展示 -- **今日体验**：筛选 `nodes[]` 中 `nodeType=ACTIVITY` 的项 diff --git a/changelogs/2026-04/2026-04-16_mp-day-detail-fields.md b/changelogs/2026-04/2026-04-16_mp-day-detail-fields.md deleted file mode 100644 index 168290e..0000000 --- a/changelogs/2026-04/2026-04-16_mp-day-detail-fields.md +++ /dev/null @@ -1,55 +0,0 @@ -# 小程序每日详情字段补全 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #669, #671 -- **类型**: feat - -## 概述 - -小程序产品详情 `GET /mp/product/{id}` 的行程天（`itinerary[]`）补全所有每日详情页所需字段。 - -## itinerary[] 完整字段清单 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `dayNumber` | Integer | 天序号 | -| `dayTitle` | String | 标题 | -| `quoteText` | String | 每日金句 | -| `description` | String | 描述 | -| `coverImageUrl` | String | 封面图 | -| `gatherPlace` | Object | 集合地 {name,adcode,center,level} | -| `dismissalPlace` | Object | 解散地 {name,adcode,center,level} | -| `dailyMileage` | BigDecimal | 当日里程(km) | -| `dailyDuration` | Integer | 当日驾车时长(分钟) | -| `breakfast` | String | 早餐(HOTEL/CAMP/SPECIAL/SELF) | -| `lunch` | String | 午餐 | -| `dinner` | String | 晚餐 | -| `diningRemark` | String | 餐饮备注 | -| `photoUrls` | List | 实拍照片 | -| `routePoints` | List | 途经路线 [{name, sortOrder}] | -| `nodes` | List | 节点列表 [{nodeType, nodeName, startTime, durationMinutes, description}] | -| `hotels` | List | 住宿列表 [{hotelName, tierSeq, roomTypeId, roomTypeName, roomCount}] | - -## 新增字段（本次PR） - -| 字段 | 说明 | -|------|------| -| `quoteText` | 每日金句 | -| `diningRemark` | 餐饮备注 | -| `dailyMileage` | 当日里程 | -| `dailyDuration` | 当日驾车时长 | -| `routePoints` | 途经路线（自动生成） | - -## 前端每日详情页数据对照 - -| 展示区块 | 数据来源 | -|---------|---------| -| 途经路线（海拉尔→呼籁营地→额尔古纳） | `routePoints[].name` 用 " → " 连接 | -| 290km · 约3.5小时 | `dailyMileage` + `dailyDuration`（分钟→小时格式化） | -| 金句引用 | `quoteText` | -| 行程详情（节点列表） | `nodes[]` | -| 实拍照片 | `photoUrls[]` | -| 今日概况（里程/餐饮/目的地） | `dailyMileage` / `breakfast,lunch,dinner` / `dismissalPlace.name` | -| 住宿（按档位分组） | `hotels[]` 按 `tierSeq` 分组 | -| 今日体验 | `nodes[]` 中 `nodeType=ACTIVITY` 的项 | diff --git a/changelogs/2026-04/2026-04-16_mp-hotel-detail-apis.md b/changelogs/2026-04/2026-04-16_mp-hotel-detail-apis.md deleted file mode 100644 index a52f092..0000000 --- a/changelogs/2026-04/2026-04-16_mp-hotel-detail-apis.md +++ /dev/null @@ -1,188 +0,0 @@ -# 小程序端酒店详情3个接口 + HotelInfo补tierName + 退款政策 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2, hl-gateway -- **PR**: #684 -- **类型**: feat - -## 一、每日住宿补充 tierName - -`GET /mp/product/{id}` 和 `GET /mp/product/{id}/day/{dayNumber}` 的 `hotels[]` 新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `tierName` | String | 档位名称（如"舒适"、"高档"） | - -前端可直接用 `tierName` 显示档位标签，不再需要从 `tiers` 中按 `tierSeq` 匹配。 - ---- - -## 二、3个新接口（酒店详情 / 房型列表 / 房型详情） - -### 1. 产品某天住宿详情 - -``` -GET /mp/product/{id}/day/{dayNumber}/hotels -``` - -**参数**: 产品ID + 天序号（1开始） - -**响应**（按档位分组）: - -```json -{ - "dayNumber": 1, - "tiers": [ - { - "tierSeq": 1, - "tierName": "舒适", - "hotels": [ - { - "hotelId": 2023714929877450753, - "name": "呼伦贝尔香格里拉大酒店", - "hotelType": "HOTEL", - "starLevel": "FIVE", - "province": "内蒙古", - "city": "呼伦贝尔", - "district": "海拉尔区", - "address": "河东新区...", - "longitude": 119.736, - "latitude": 49.212, - "coverUrl": "https://oss.xxx/cover.jpg", - "bannerUrls": ["https://oss.xxx/1.jpg"], - "facilities": "{\"wifi\":true,\"parking\":true}", - "highlights": "{\"items\":[\"草原景观房\"]}", - "description": "五星级草原度假酒店...", - "checkInTime": "14:00", - "checkOutTime": "12:00", - "checkInNotes": "需携带身份证", - "tags": ["五星级", "草原景观"], - "roomTypeId": 3002000000000000013, - "roomTypeName": "豪华大床房", - "roomCount": 2 - } - ] - }, - { - "tierSeq": 2, - "tierName": "高档", - "hotels": [...] - } - ] -} -``` - -### 2. 酒店房型列表 - -``` -GET /mp/product/hotel/{hotelId}/room-types -``` - -**参数**: 酒店ID - -**响应**: - -```json -{ - "hotelId": 2023714929877450753, - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypes": [ - { - "roomTypeId": 3002000000000000013, - "name": "豪华大床房", - "roomCategory": "KING", - "bedType": "KING_BED", - "maxOccupancy": 2, - "coverUrl": "https://oss.xxx/room-cover.jpg" - }, - { - "roomTypeId": 2023727403196502017, - "name": "标准双床房", - "roomCategory": "STANDARD", - "bedType": "TWIN_BED", - "maxOccupancy": 2, - "coverUrl": null - } - ] -} -``` - -### 3. 房型详情 - -``` -GET /mp/product/room-type/{roomTypeId} -``` - -**参数**: 房型ID - -**响应**: - -```json -{ - "roomTypeId": 3002000000000000013, - "hotelId": 2023714929877450753, - "name": "豪华大床房", - "roomCategory": "KING", - "roomArea": 35.0, - "bedType": "KING_BED", - "bedCount": 1, - "bedSize": "1.8m", - "maxOccupancy": 2, - "floorInfo": "8-15层", - "windowType": "FLOOR_WINDOW", - "bathroomType": "PRIVATE", - "roomFacilities": "{\"minibar\":true,\"bathtub\":true}", - "description": "草原景观豪华大床房...", - "coverUrl": "https://oss.xxx/room-cover.jpg", - "bannerUrls": ["https://oss.xxx/r1.jpg", "https://oss.xxx/r2.jpg"], - "videoUrl": null -} -``` - -### 接口说明 - -- 3个接口均**无需登录**（已加入网关JWT白名单） -- 接口1的酒店详情通过Feign调资源服务获取，未绑定资源时用快照名称兜底 -- 接口2从酒店详情中提取房型列表（仅返回已启用房型） - ---- - -## 三、退款政策字段 - -### 管理端 Step5 保存 - -`PUT /admin/product/item/{id}/supplement` 新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `refundPolicyId` | Long | 退款政策ID（从 `GET /admin/order/refund-policy/enabled` 下拉框选择） | - -根据产品支付类型选择对应退款政策（全款退款 / 定金退款）。 - -### 小程序端 - -`GET /mp/product/{id}` 新增字段： - -```json -{ - "refundPolicy": { - "policyName": "全款默认退款政策", - "rules": [ - { "minDays": 15, "refundRatio": 100 }, - { "minDays": 7, "refundRatio": 80 }, - { "minDays": 3, "refundRatio": 50 }, - { "minDays": 0, "refundRatio": 20 } - ] - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `refundPolicy` | Object | 退款政策（未配置时为null） | -| `refundPolicy.policyName` | String | 政策名称 | -| `refundPolicy.rules` | List | 退款规则列表 | -| `refundPolicy.rules[].minDays` | Integer | 距出发最少天数 | -| `refundPolicy.rules[].refundRatio` | Integer | 退款比例（百分比0-100） | - -含义：出发前≥15天退100%，≥7天退80%，≥3天退50%，<3天退20%。 diff --git a/changelogs/2026-04/2026-04-16_mp-hotel-list-by-day-tier.md b/changelogs/2026-04/2026-04-16_mp-hotel-list-by-day-tier.md deleted file mode 100644 index 3a489b9..0000000 --- a/changelogs/2026-04/2026-04-16_mp-hotel-list-by-day-tier.md +++ /dev/null @@ -1,110 +0,0 @@ -# 小程序端 — 按天+档位查看酒店列表 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **类型**: 使用指南 - -## 接口 - -``` -GET /mp/product/{id}/day/{dayNumber}/hotels -``` - -**无需登录**，已加入网关白名单。 - -## 参数 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| id | path | Long | 是 | 产品ID | -| dayNumber | path | Integer | 是 | 天序号（从1开始） | - -## 响应示例 - -```json -{ - "code": 200, - "data": { - "dayNumber": 1, - "tiers": [ - { - "tierSeq": 1, - "tierName": "舒适", - "hotels": [ - { - "hotelId": 2023714929877450753, - "name": "海拉尔洲际酒店", - "hotelType": "HOTEL", - "starLevel": "FIVE", - "province": "内蒙古", - "city": "呼伦贝尔", - "district": "海拉尔区", - "address": "河东新区...", - "longitude": 119.736, - "latitude": 49.212, - "coverUrl": "https://oss.xxx/cover.jpg", - "bannerUrls": ["https://oss.xxx/1.jpg", "https://oss.xxx/2.jpg"], - "facilities": "{\"wifi\":true,\"parking\":true}", - "highlights": "{\"items\":[\"草原景观房\"]}", - "description": "五星级草原度假酒店...", - "checkInTime": "14:00", - "checkOutTime": "12:00", - "checkInNotes": "需携带身份证", - "tags": ["五星级", "草原景观"], - "roomTypeId": 3002000000000000013, - "roomTypeName": "豪华大床房", - "roomCount": 2 - } - ] - }, - { - "tierSeq": 2, - "tierName": "高档", - "hotels": [ - { - "hotelId": 2023714929877450800, - "name": "呼伦贝尔香格里拉大酒店", - "coverUrl": "https://oss.xxx/cover2.jpg", - "roomTypeName": "行政套房", - "roomCount": 2 - } - ] - } - ] - } -} -``` - -## 字段说明 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `tiers` | List | 按档位分组的酒店列表 | -| `tiers[].tierSeq` | Integer | 档位序号（1=舒适，2=高档等） | -| `tiers[].tierName` | String | 档位名称 | -| `tiers[].hotels` | List | 该档位下的酒店列表 | -| `hotels[].hotelId` | Long | 酒店ID | -| `hotels[].name` | String | 酒店名称 | -| `hotels[].hotelType` | String | 住宿类型（字典hotel_type: HOTEL/HOMESTAY/RESORT/CAMPSITE） | -| `hotels[].starLevel` | String | 星级（字典hotel_star: THREE/FOUR/FIVE/BOUTIQUE） | -| `hotels[].coverUrl` | String | 封面图URL | -| `hotels[].bannerUrls` | List\<String\> | 横幅图URL列表 | -| `hotels[].address` | String | 详细地址 | -| `hotels[].longitude` | BigDecimal | 经度 | -| `hotels[].latitude` | BigDecimal | 纬度 | -| `hotels[].facilities` | String | 设施配置（JSON） | -| `hotels[].highlights` | String | 酒店亮点（JSON） | -| `hotels[].description` | String | 酒店描述 | -| `hotels[].checkInTime` | String | 入住时间 | -| `hotels[].checkOutTime` | String | 退房时间 | -| `hotels[].tags` | List\<String\> | 标签列表 | -| `hotels[].roomTypeId` | Long | 绑定的房型ID | -| `hotels[].roomTypeName` | String | 绑定的房型名称 | -| `hotels[].roomCount` | Integer | 房间数 | - -## 前端使用场景 - -1. **每日行程页 → 点击"住宿"区块** → 调此接口获取当天酒店详情 -2. 单档位产品：`tiers` 只有1个元素，直接展示 `hotels` -3. 多档位产品：用 tab 切换档位，按 `tierSeq` 展示对应 `hotels` -4. 点击某个酒店 → 可继续调 `GET /mp/product/hotel/{hotelId}/room-types` 查看房型列表 diff --git a/changelogs/2026-04/2026-04-16_mp-node-resource-detail.md b/changelogs/2026-04/2026-04-16_mp-node-resource-detail.md deleted file mode 100644 index 0161cfa..0000000 --- a/changelogs/2026-04/2026-04-16_mp-node-resource-detail.md +++ /dev/null @@ -1,46 +0,0 @@ -# 节点返回绑定资源详情 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #678 -- **类型**: feat - -## 概述 - -小程序产品详情和每日详情接口中，节点（`nodes[]`）现在返回绑定资源的详细信息。 - -## nodes[] 新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `resourceName` | String | 资源原名 | -| `resourceCover` | String | 资源封面图URL | -| `resourceImages` | List | 资源图片列表 | -| `resourceAddress` | String | 资源地址 | -| `resourceDescription` | String | 资源简介 | -| `resourceTags` | List | 资源标签列表 | - -## 响应示例 - -```json -{ - "nodes": [{ - "nodeType": "SCENIC", - "nodeName": "呼籁营地", - "resourceName": "呼籁营地", - "startTime": "上午", - "description": "这片草原只有呼籁自己的团队...", - "resourceCover": "https://oss.xxx/cover.jpg", - "resourceImages": ["https://oss.xxx/1.jpg", "https://oss.xxx/2.jpg"], - "resourceAddress": "内蒙古自治区呼伦贝尔市...", - "resourceDescription": "专属营地，安静私密...", - "resourceTags": ["自然风光", "亲子", "露营"] - }] -} -``` - -## 说明 - -- 通过Feign批量查资源服务，一次调用补全所有节点 -- 节点未绑定资源（`resourceId=null`）时，资源字段全部为null -- 影响接口：`GET /mp/product/{id}` 和 `GET /mp/product/{id}/day/{dayNumber}` diff --git a/changelogs/2026-04/2026-04-16_node-emoji-icon.md b/changelogs/2026-04/2026-04-16_node-emoji-icon.md deleted file mode 100644 index bd2cee1..0000000 --- a/changelogs/2026-04/2026-04-16_node-emoji-icon.md +++ /dev/null @@ -1,41 +0,0 @@ -# 行程节点图标字段 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **类型**: 前端适配说明 - -## 说明 - -行程节点的 `emojiIcon` 字段已全链路支持，无需后端改动。 - -### 管理端 Step2 保存 - -`PUT /admin/product/item/{id}/itinerary` 的 `nodes[]` 中传 `emojiIcon`： - -```json -{ - "nodes": [{ - "nodeName": "呼籁旅拍", - "nodeType": "ACTIVITY", - "emojiIcon": "📷", - "description": "每人精修5张+全家福，底片全送", - "sortOrder": 1 - }, { - "nodeName": "营地BBQ", - "nodeType": "ACTIVITY", - "emojiIcon": "🍖", - "description": "专属营地自助烧烤", - "sortOrder": 2 - }] -} -``` - -### 小程序端 - -`GET /mp/product/{id}` 和 `GET /mp/product/{id}/day/{dayNumber}` 的 `nodes[]` 中返回 `emojiIcon`： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `emojiIcon` | String | 节点图标（emoji或图标名） | - -用于「今日体验」区块每个活动前面的图标展示。未设置时为null。 diff --git a/changelogs/2026-04/2026-04-16_product-v2_auto-route-points.md b/changelogs/2026-04/2026-04-16_product-v2_auto-route-points.md deleted file mode 100644 index 8064cec..0000000 --- a/changelogs/2026-04/2026-04-16_product-v2_auto-route-points.md +++ /dev/null @@ -1,47 +0,0 @@ -# 途经路线自动生成 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #614 -- **类型**: feat (新功能) - -## 概述 - -保存行程（Step2）时，自动按天生成途经路线点。前端无需手动维护 `routePoints`。 - -## 行为 - -保存行程后，后端自动为每天生成途经路线： - -``` -集合地 → 景区/活动节点1 → 景区/活动节点2 → ... → 解散地 -``` - -- 每天都有独立的途经路线 -- 每天的首位是产品的**集合地**（`gatherPlace`） -- 每天的末位是产品的**解散地**（`dismissalPlace`） -- 中间是当天的景区（SCENIC）和活动（ACTIVITY）节点名称 -- 全删全插策略，每次保存行程自动重新生成 - -## 前端注意 - -- **不需要手动传 `routePoints`**，保存行程后自动生成 -- 管理端详情中每天的 `routePoints` 会自动有值 -- 前端可以在行程天中展示途经路线标签（如：海拉尔 → 呼籁营地 → 额尔古纳） -- 需要先设置集合地/解散地（Step2的 `gatherPlace`/`dismissalPlace`），否则首尾没有 - -## 响应示例 - -```json -{ - "itinerary": [{ - "dayNumber": 1, - "routePoints": [ - {"name": "海拉尔", "sortOrder": 1}, - {"name": "莫日格勒河观景台", "sortOrder": 2}, - {"name": "呼籁营地", "sortOrder": 3}, - {"name": "海拉尔", "sortOrder": 4} - ] - }] -} -``` diff --git a/changelogs/2026-04/2026-04-16_product-v2_daily-duration-and-menu.md b/changelogs/2026-04/2026-04-16_product-v2_daily-duration-and-menu.md deleted file mode 100644 index 9fedd26..0000000 --- a/changelogs/2026-04/2026-04-16_product-v2_daily-duration-and-menu.md +++ /dev/null @@ -1,43 +0,0 @@ -# 每日驾车时长自动计算 + 行程保障菜单 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #615 -- **类型**: feat - -## 1. 每日驾车时长自动计算 - -保存行程（Step2）时，自动通过高德API计算每天的**里程(km)** 和 **驾车时长(分钟)**，写入行程天表。 - -### 行程天新增字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `dailyMileage` | BigDecimal | 当日驾车里程(km)，自动计算 | -| `dailyDuration` | Integer | 当日驾车时长(分钟)，自动计算 | - -- 保存行程后自动触发，无需前端额外调用 -- `mileageManualOverride=true` 的天不会被自动覆盖 -- 计算失败不影响行程保存 - -### 前端展示 - -小程序端每日行程可展示如：`290km · 约3.5小时` - -换算规则：`dailyDuration` 是分钟，前端自行格式化（如 151分钟 → "约2.5小时"） - -### GET /admin/product/item/{id}/daily-mileage 响应更新 - -```json -[ - {"dayNumber": 1, "mileage": 166.3, "duration": 151}, - {"dayNumber": 2, "mileage": 314.2, "duration": 276}, - {"dayNumber": 3, "mileage": 700.0, "duration": 579} -] -``` - -## 2. 行程保障菜单 - -后台「产品管理」下新增「行程保障」菜单，排在「温馨提示」之后。 - -对应接口：`/admin/travel-guarantee-template/**`（CRUD已在之前的changelog中说明） diff --git a/changelogs/2026-04/2026-04-16_product-v2_gather-dismiss-per-day.md b/changelogs/2026-04/2026-04-16_product-v2_gather-dismiss-per-day.md deleted file mode 100644 index 27c32f3..0000000 --- a/changelogs/2026-04/2026-04-16_product-v2_gather-dismiss-per-day.md +++ /dev/null @@ -1,78 +0,0 @@ -# 集合地/解散地迁移到每日行程 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #617 -- **类型**: refactor (破坏性变更) - -## ⚠️ 破坏性变更 - -`gatherPlace` 和 `dismissalPlace` 从**产品级**迁移到**每日行程天级**。 - -### 之前（已废弃） - -``` -PUT /admin/product/item/{id}/itinerary -{ - "gatherPlace": "海拉尔", ← 产品级，已删除 - "dismissalPlace": "海拉尔", ← 产品级，已删除 - "days": [...] -} -``` - -### 现在 - -⚠️ **字段类型改为JSON对象**（存高德行政区搜索返回的完整数据） - -``` -PUT /admin/product/item/{id}/itinerary -{ - "days": [{ - "dayNumber": 1, - "gatherPlace": { - "name": "海拉尔区", - "adcode": "150702", - "center": "119.736279,49.212189", - "level": "district" - }, - "dismissalPlace": { - "name": "额尔古纳市", - "adcode": "150784", - "center": "120.180506,50.243102", - "level": "city" - }, - "dayTitle": "D1", - "nodes": [...] - }, { - "dayNumber": 2, - "gatherPlace": {"name": "额尔古纳市", "adcode": "150784", "center": "120.18,50.24", "level": "city"}, - "dismissalPlace": {"name": "满洲里市", "adcode": "150781", "center": "117.45,49.59", "level": "city"}, - ... - }] -} -``` - -### 管理端详情响应 - -`GET /admin/product/item/{id}` 的 `itinerary[]` 中每天包含： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `gatherPlace` | Object | 当日集合地 `{name, adcode, center, level}` | -| `dismissalPlace` | Object | 当日解散地 `{name, adcode, center, level}` | -| `dailyMileage` | BigDecimal | 当日里程(km)，自动计算 | -| `dailyDuration` | Integer | 当日驾车时长(分钟)，自动计算 | - -### 小程序端详情响应 - -`GET /mp/product/{id}` 的 `itinerary[]` 中每天同样包含 `gatherPlace`/`dismissalPlace`/`dailyMileage`/`dailyDuration`。 - -**产品级不再有这两个字段。** - -### Step3路线与备品 - -`PUT /admin/product/item/{id}/route` 也不再有 `gatherPlace`/`dismissalPlace`。 - -### 途经路线自动生成 - -每天的途经路线格式：`当天集合地 → 景区/活动节点 → 当天解散地` diff --git a/changelogs/2026-04/2026-04-16_product-v2_node-name-editable.md b/changelogs/2026-04/2026-04-16_product-v2_node-name-editable.md deleted file mode 100644 index f071ebc..0000000 --- a/changelogs/2026-04/2026-04-16_product-v2_node-name-editable.md +++ /dev/null @@ -1,50 +0,0 @@ -# 行程节点名称可自定义编辑 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **类型**: 前端适配提醒 - -## 说明 - -后端已支持行程节点名称自定义。前端需要做的改动： - -### Step2 行程编排 - 活动安排 - -将节点名称从**只读文本**改为**可编辑输入框**。 - -当前状态：节点名（如"莫日格勒河观景台"、"草原骑马体验"）是只读的，从资源库选择后不能改。 - -改为：用户可以修改节点展示名称，比如把"莫日格勒河观景台"改为"莫日格勒河·日出观景"。 - -### 后端字段说明 - -| 字段 | 说明 | 前端操作 | -|------|------|---------| -| `nodeName` | 展示名称 | **可编辑**，用户改什么存什么 | -| `resourceName` | 资源原名快照 | 后端自动填充，前端不传 | -| `resourceId` | 关联资源ID | 从资源库选择时带过来 | - -### 前端展示规则 - -**`nodeName` 有值显示 `nodeName`，没值则 fallback 显示 `resourceName`。** - -- 从资源库新选一个节点时：`nodeName` 默认用资源名，用户可以改 -- 用户清空 `nodeName` 时：传空或不传，前端显示 `resourceName`（资源原名） - -### 保存请求示例 - -```json -{ - "days": [{ - "nodes": [{ - "nodeId": 12345, - "nodeName": "莫日格勒河·日出观景", - "nodeType": "SCENIC", - "resourceId": 3001000000000000019, - "sortOrder": 1 - }] - }] -} -``` - -`nodeName` 传用户编辑后的值。后端会根据 `resourceId` 自动查资源原名存入 `resourceName`，两个字段互不影响。 diff --git a/changelogs/2026-04/2026-04-16_product-v2_quote-fix-and-tier-desc.md b/changelogs/2026-04/2026-04-16_product-v2_quote-fix-and-tier-desc.md deleted file mode 100644 index 969bbbf..0000000 --- a/changelogs/2026-04/2026-04-16_product-v2_quote-fix-and-tier-desc.md +++ /dev/null @@ -1,81 +0,0 @@ -# 报价逻辑修复 + 档位描述字段 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **PR**: #638, #661 -- **类型**: fix + feat - -## 1. 报价逻辑修复（⚠️ 重要） - -### 问题 - -报价接口把价格日历的每日价格逐天累加，导致总价 = 单价 × 人数 × 行程天数（错误）。 - -### 修复 - -取**出发日期当天的一口价** × 人数（和旧版一致）。 - -### 响应变更 - -`POST /admin/product/item/{id}/quote` 和 `POST /mp/product/{id}/quote` - -**新增字段**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `adultUnitPrice` | BigDecimal | 成人单价（出发日一口价） | -| `childUnitPrice` | BigDecimal | 儿童单价（出发日一口价） | - -**删除字段**： - -| 字段 | 说明 | -|------|------| -| `dailyDetails` | 不再返回每日明细（一口价不需要） | - -**响应示例**： -```json -{ - "adultUnitPrice": 4999.0, - "childUnitPrice": 3499.0, - "totalAdultPrice": 9998.0, - "totalChildPrice": 3499.0, - "grandTotal": 13497.0 -} -``` - -计算公式：`totalAdultPrice = adultUnitPrice × adultCount` - -## 2. 档位描述字段 - -产品的 `tiers` JSON结构新增 `tierDescription` 字段。 - -**旧结构**： -```json -[{"tierSeq": 1, "tierName": "轻奢"}, {"tierSeq": 2, "tierName": "高端"}] -``` - -**新结构**： -```json -[ - {"tierSeq": 1, "tierName": "轻奢", "tierDescription": "精选三星酒店，舒适出行"}, - {"tierSeq": 2, "tierName": "高端", "tierDescription": "五星酒店+专车接送，尊享体验"} -] -``` - -后端纯JSON存取，无需改代码。前端在Step1基础信息的规格列表中，每个档位加一个描述输入框即可。 - -## 3. routeSummary 线路概览摘要 - -新增字段 `routeSummary`，保存行程(Step2)时自动生成。 - -格式：`{首天集合地}起止·全程约{总里程}公里·日均不超{日均最大里程取整百}公里` - -示例：`海拉尔起止·全程约1200公里·日均不超400公里` - -- 管理端详情：`routeInfo.routeSummary` -- 小程序详情：`routeSummary` -- `routeDescription`（线路描述）不再自动覆盖，完全由用户手动填写 - -## 4. guaranteeTemplateId 修复 - -Step5补充信息保存接口现在正确支持 `guaranteeTemplateId` 字段，详情也正确返回。 diff --git a/changelogs/2026-04/2026-04-16_product-v2_route-overview-display.md b/changelogs/2026-04/2026-04-16_product-v2_route-overview-display.md deleted file mode 100644 index 88aaff5..0000000 --- a/changelogs/2026-04/2026-04-16_product-v2_route-overview-display.md +++ /dev/null @@ -1,84 +0,0 @@ -# 线路概览展示所需字段汇总 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2 -- **类型**: 前端适配说明 - -## 原型展示 - -``` -线 路 概 览 -草原环线体验 ← routeName -海拉尔起止·全程约1200公里·日均不超300公里 ← 前端拼接 -``` - -## 数据来源 - -| 展示内容 | 数据来源 | 接口字段 | -|---------|---------|---------| -| "草原环线体验" | 路线名称 | `routeName` (产品级) | -| "海拉尔起止" | 首天集合地 + 末天解散地 | `itinerary[0].gatherPlace.name` + `itinerary[last].dismissalPlace.name` | -| "全程约1200公里" | 总里程 | `totalMileage` (产品级) | -| "日均不超300公里" | 每日里程最大值 | `max(itinerary[].dailyMileage)` | - -### 每日行程展示 - -``` -DAY 2 -海拉尔 → 呼籁营地 → 莫日格勒河 → 额尔古纳 -290km · 约3.5小时 -``` - -| 展示内容 | 数据来源 | 接口字段 | -|---------|---------|---------| -| 途经路线 | 自动生成 | `itinerary[].routePoints[].name` 用 " → " 连接 | -| "290km" | 当日里程 | `itinerary[].dailyMileage` | -| "约3.5小时" | 当日驾车时长 | `itinerary[].dailyDuration`（分钟，前端格式化） | -| 集合地 | 当日 | `itinerary[].gatherPlace` (JSON: {name,adcode,center,level}) | -| 解散地 | 当日 | `itinerary[].dismissalPlace` (JSON: {name,adcode,center,level}) | - -### 时长格式化建议 - -`dailyDuration` 是分钟数，前端格式化示例： -- 151分钟 → "约2.5小时" -- 276分钟 → "约4.5小时" -- 30分钟以下 → "约30分钟" - ---- - -## 行程保障展示 - -原型中「行程保障」区块（无忧退改、5人专属团队、24小时客服等）的数据来源： - -| 接口 | 字段 | 说明 | -|------|------|------| -| `GET /mp/product/{id}` | `guaranteeItems` | 行程保障项数组，自动解析模板 | - -`guaranteeItems` 结构： -```json -[ - {"icon": "shield", "title": "无忧退改", "description": "出发前7天无条件全额退款..."}, - {"icon": "users", "title": "5人专属服务团队", "description": "定制师、房务管家..."}, - {"icon": "clock", "title": "24小时客服响应", "description": "行前、行中、行后..."}, - {"icon": "badge", "title": "旅行社责任险100万", "description": "正规旅行社资质..."}, - {"icon": "car", "title": "全程纯玩无购物", "description": "无强制消费..."} -] -``` - -### 前端操作流程 - -1. **管理端 Step5 补充信息**：选择行程保障模板（`guaranteeTemplateId`） -2. **小程序端**：从 `guaranteeItems` 直接渲染列表 - -### 模板管理 - -- 菜单：产品管理 → 行程保障 -- CRUD接口：`/admin/travel-guarantee-template/**`（详见Knife4j「产品服务-模板管理」分组） - -⚠️ 如果 `guaranteeItems` 为null，说明产品还没关联模板，需要在Step5中设置。 - -## 注意 - -- `gatherPlace`/`dismissalPlace` 需要重新保存行程(Step2)才有值 -- `dailyMileage`/`dailyDuration` 保存行程时自动计算 -- 所有数据在管理端详情和小程序端详情中均返回 diff --git a/changelogs/2026-04/2026-04-16_tier-desc-insurance-filter.md b/changelogs/2026-04/2026-04-16_tier-desc-insurance-filter.md deleted file mode 100644 index b9c25a0..0000000 --- a/changelogs/2026-04/2026-04-16_tier-desc-insurance-filter.md +++ /dev/null @@ -1,51 +0,0 @@ -# 档位描述 + 保险方案按天数筛选 - -- **日期**: 2026-04-16 -- **服务**: hl-product-service-v2, hl-order-service-v2 -- **PR**: #667 -- **类型**: feat - -## 1. 档位描述字段 - -### Step1 基础信息保存 - -`tiers` 规格列表新增 `tierDescription` 字段： - -```json -{ - "tiers": [ - {"tierSeq": 1, "tierName": "轻奢", "tierDescription": "精选三星酒店，舒适出行"}, - {"tierSeq": 2, "tierName": "高端", "tierDescription": "五星酒店+专车接送，尊享体验"} - ] -} -``` - -### 小程序详情 - -`tierPrices[]` 也返回 `tierDescription`： - -```json -{ - "tierPrices": [ - {"tierSeq": 1, "tierName": "轻奢", "tierDescription": "精选三星酒店", "startPrice": 3980}, - {"tierSeq": 2, "tierName": "高端", "tierDescription": "五星酒店", "startPrice": 5980} - ] -} -``` - -## 2. 保险方案按行程天数筛选 - -### GET /admin/insurance/scheme/list 新增参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `totalDays` | Integer | 否 | 行程天数，传了则只返回匹配的方案 | - -**示例**： -``` -GET /admin/insurance/scheme/list?totalDays=6 -``` - -只返回 `totalDays=6` 的启用方案。不传则返回全部（向后兼容）。 - -**前端操作**：选择保险方案下拉框时，传当前产品的 `tripDays` 作为 `totalDays` 参数。 diff --git a/changelogs/2026-04/2026-04-17-admin-product-detail-safeguard-tier-price.md b/changelogs/2026-04/2026-04-17-admin-product-detail-safeguard-tier-price.md deleted file mode 100644 index f44734e..0000000 --- a/changelogs/2026-04/2026-04-17-admin-product-detail-safeguard-tier-price.md +++ /dev/null @@ -1,123 +0,0 @@ -# 管理端产品详情 扩展 档位起步价 + Step5 模板展开字段 - -- **日期**: 2026-04-17 -- **服务**: hl-product-service-v2（端口 8083） -- **PR**: https://git.1814.love:8443/wx/HL/pulls/763 -- **Issue**: https://git.1814.love:8443/wx/HL/issues/760 -- **类型**: feat（非破坏性扩展，纯字段新增） -- **影响**: 管理端产品编辑/查看页可直接拿到起步价与 Step5 补充模板展开内容，无需二次查模板接口 - -## 变更类型 - -**非破坏性扩展**：对已有接口 `GET /admin/product/item/{id}` 的响应体新增若干字段。 -- 所有老字段不变、含义不变、类型不变 -- 旧前端客户端忽略新字段即可继续运行 -- 无需迁移 - -## 受影响接口 - -### `GET /admin/product/item/{id}` - -管理端产品详情接口。**签名与请求参数不变**。响应 VO `ProductDetailRespVO` 新增以下字段。 - -## 新增字段清单 - -### Step4 价格/班期 区块（3 个字段） - -| 字段 | 类型 | 含义 | 可能为 null 的情况 | -|------|------|------|-------------------| -| `startPrice` | BigDecimal | 起步价（未来可售最低成人售价） | 没有未来可售价格日历时为 `null` | -| `tierPrices` | `List<TierPriceInfo>` | 各档位起步价（管理端即使单档产品也会返回） | 全部档位价格已过期时为 `[]`（空数组，不是 null） | -| `priceCalendars` | `List<PriceCalendarRespVO>` | 价格日历全量回显（含已过期、含零价，不做过滤） | 从未配置价格日历时为 `[]` | - -> **管理端 vs 小程序端**：小程序端通常会过滤掉过期与零价，管理端此处返回全量，方便后台编辑/校对。 - -### Step5 补充信息 区块（5 个字段，模板 ID 自动展开） - -前端无需再发 GET 模板详情请求，后端已根据 `supplement.xxxTemplateId` / `supplement.xxxId` 展开内容： - -| 字段 | 类型 | 含义 | 展开自 | 可能为 null 的情况 | -|------|------|------|--------|-------------------| -| `guaranteeItems` | Object/Array（透传 JSON） | 行程保障项 | `supplement.guaranteeTemplateId` 对应模板的 `items` JSON | `guaranteeTemplateId` 为 null 或模板不存在时为 `null` | -| `safetyItems` | Object/Array（透传 JSON） | 安全保障项 | `supplement.safetyTemplateId` 对应模板的 `items` JSON | `safetyTemplateId` 为 null 或模板不存在时为 `null` | -| `faqItems` | Object/Array（透传 JSON） | FAQ 问答 | `supplement.faqTemplateId` 对应模板的 `items` JSON | `faqTemplateId` 为 null 或模板不存在时为 `null` | -| `bookingTermsContent` | String | 预订条款内容（富文本） | `supplement.bookingTermsId` 对应的 `content` | `bookingTermsId` 为 null 或记录不存在时为 `null` | -| `warmTipsContent` | String | 温馨提示内容（富文本） | `supplement.warmTipsId` 对应的 `content` | `warmTipsId` 为 null 或记录不存在时为 `null` | - -> **设计原则**：若对应 ID 为 null，后端不会查询无意义的数据，直接回空。 - -## 内部类结构：`TierPriceInfo` - -`tierPrices` 数组的元素结构： - -```json -{ - "tierSeq": 1, - "tierName": "标准档", - "tierDescription": "标间 / 四人桌", - "startPrice": 2980.00 -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `tierSeq` | Integer | 档位序号（1、2、3…） | -| `tierName` | String | 档位名称 | -| `tierDescription` | String | 档位描述（房型/餐标等） | -| `startPrice` | BigDecimal | 该档位未来可售最低成人售价 | - -## 响应示例（节选，只展示新增部分） - -```json -{ - "code": 200, - "data": { - "productId": 1001, - "name": "呼伦贝尔6日游", - - "startPrice": 2980.00, - "tierPrices": [ - { "tierSeq": 1, "tierName": "标准档", "tierDescription": "标间", "startPrice": 2980.00 }, - { "tierSeq": 2, "tierName": "豪华档", "tierDescription": "大床房", "startPrice": 3480.00 } - ], - "priceCalendars": [ - { "date": "2026-05-01", "tierSeq": 1, "adultPrice": 2980.00, "childPrice": 1980.00, "stock": 20 } - ], - - "supplement": { - "guaranteeTemplateId": 11, - "safetyTemplateId": 12, - "faqTemplateId": 13, - "bookingTermsId": 21, - "warmTipsId": 22 - }, - "guaranteeItems": [ { "title": "全程WIFI", "desc": "..." } ], - "safetyItems": [ { "title": "随车医药箱", "desc": "..." } ], - "faqItems": [ { "q": "可以加床吗？", "a": "可以，需付费" } ], - "bookingTermsContent": "<p>下单后 24 小时内完成支付...</p>", - "warmTipsContent": "<p>请携带身份证原件...</p>" - } -} -``` - -## 使用建议 - -| 场景 | 推荐字段 | -|------|---------| -| 列表页/卡片展示"起步价￥xxx" | `startPrice` | -| 编辑页档位 tab 切换展示各档起价 | `tierPrices` | -| 价格日历编辑/核对（含过期、含零价） | `priceCalendars` | -| Step5 预览页面渲染"行程保障/安全保障/FAQ" | `guaranteeItems` / `safetyItems` / `faqItems` | -| Step5 预览页面渲染"预订条款/温馨提示"富文本 | `bookingTermsContent` / `warmTipsContent` | - -> 编辑模板 ID 选择时仍然使用 `supplement.xxxTemplateId` / `supplement.xxxId` 字段；本次新增的展开字段仅用于展示。 - -## 迁移建议 - -**无需迁移**。纯新增字段，老字段与老行为完全保持。 - -## 后端需重启的服务 - -- **hl-product-service-v2**（端口 8083） - -拉最新 `dev` 分支后重启该服务即可生效，其它服务不受影响。 diff --git a/changelogs/2026-04/2026-04-17_breaking_price-calendar-validation.md b/changelogs/2026-04/2026-04-17_breaking_price-calendar-validation.md deleted file mode 100644 index c5cea71..0000000 --- a/changelogs/2026-04/2026-04-17_breaking_price-calendar-validation.md +++ /dev/null @@ -1,239 +0,0 @@ -# ⚠️ 破坏性变更：价格日历批量接口字段强校验 - -> **类型**: 🔴 **BREAKING CHANGE（破坏性变更，老前端会 400）** -> **服务**: hl-product-service-v2（端口 8083） -> **接口**: `POST /admin/product/item/{id}/price-calendar/batch` -> **Issue**: #747 -> **PR**: #748（已合并到 dev） -> **Commit**: `c311e6ee` -> **日期**: 2026-04-17 -> **影响范围**: 管理后台 Step4 定价管理 — 批量设置价格 - ---- - -## 🚨 一句话摘要（最重要） - -**3 个字段从「兜底默认值」升级为「强校验必传」。老前端如果不传 `childSellPrice` / `tierSeq` / `priceType` 会直接返回 400，无法保存价格日历。前端必须同步升级表单必填校验。** - ---- - -## 一、原漏洞（测试服实测） - -测试服（升级前）存在以下脏数据写入漏洞： - -| # | 用例 | 原行为（❌ 漏洞） | -|---|------|------------------| -| 1 | `childSellPrice` 缺失 / 为 null | 允许保存（儿童价变 null，前端列表显示空） | -| 2 | `tierSeq=99`（产品实际只有 5 档） | 允许保存（脏数据，点查详情无法匹配档位） | -| 3 | `priceType=XXX`（非字典枚举值） | 允许保存（污染字典） | -| 4 | `adultSellPrice=0` 或负数 | 允许保存（0 元购，业务事故） | -| 5 | `startDate > endDate` | 允许保存（生成 0 条价格但 200） | - -## 二、根因 - -`PriceCalendarBatchSaveReqVO` 对三个关键字段只做了「空值给默认值」的兜底处理，未使用 `@NotNull / @NotBlank / @Pattern`；Service 层也未校验 `tierSeq` 是否在产品实际档位范围内。 - -## 三、修复后行为（本地经网关实测） - -| 用例 | HTTP | 响应 message | -|------|------|--------------| -| T1 正常请求 | **200** | `价格日历设置成功` | -| T2 缺 `childSellPrice` | **400** | `childSellPrice: 儿童售价不能为空` | -| T3 `tierSeq=99`（5 档产品） | **500** | `档位序号99不存在，本产品只有5档` | -| T4 `adultSellPrice=0` | **400** | `adultSellPrice: 成人售价必须大于0` | -| T5 `priceType=XXX` | **400** | `priceType: 价格类型必须是 NORMAL/PEAK/HOLIDAY/SPECIAL 之一` | -| T6 `startDate > endDate` | **500** | `开始日期不能晚于结束日期` | - ---- - -## 四、接口契约 - -### 4.1 接口签名（未变） - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/product/item/{id}/price-calendar/batch` | 批量设置某档位某日期区间的价格 | - -### 4.2 请求体字段校验矩阵 - -| 字段 | 类型 | 必填 | 校验规则 | 说明 | -|------|------|------|----------|------| -| `startDate` | String (yyyy-MM-dd) | ✅ | `@NotNull` | 区间开始日期（含） | -| `endDate` | String (yyyy-MM-dd) | ✅ | `@NotNull` + Service 校验 `endDate ≥ startDate` | 区间结束日期（含） | -| `tierSeq` | Integer | ✅ | 🔴 新：`@NotNull + @Min(1)` + Service 校验 `tierSeq ≤ 产品实际档位数` | 档位序号（1 起），多档位产品必传 | -| `priceType` | String | ✅ | 🔴 新：`@NotBlank + @Pattern(NORMAL\|PEAK\|HOLIDAY\|SPECIAL)` | 价格类型字典值 | -| `adultSellPrice` | BigDecimal | ✅ | 🔴 加强：`@NotNull + @DecimalMin("0.01")` | 成人售价，必须 > 0 | -| `childSellPrice` | BigDecimal | ✅ | 🔴 新：`@NotNull + @DecimalMin("0.01")` | 儿童售价，必须 > 0 | -| `toddlerDiscount` | BigDecimal | 否 | — | 幼童价格调整（可负数，如 -500 表示减 500） | -| `infantPrice` | BigDecimal | 否 | — | 婴儿价格 | -| `dailyStock` | Integer | 否 | — | 每日库存 | - -### 4.3 🔴 破坏性变更对比表（前端必改） - -| 字段 | 升级前（老行为） | 升级后（新强校验） | 前端必须动作 | -|------|------------------|---------------------|--------------| -| `childSellPrice` | 可不传 / 可为 null → 落库 null | `@NotNull + @DecimalMin(0.01)` | **必须让用户填写并提交** | -| `tierSeq` | 可不传 → 后端默认 1 | `@NotNull + @Min(1)` + 不能超过产品档位数 | **必须传当前选中 tab 的 tierSeq** | -| `priceType` | 可不传 → 后端默认 NORMAL | `@NotBlank + @Pattern` 只能是 NORMAL/PEAK/HOLIDAY/SPECIAL | **必须传字典枚举值（表单下拉默认 NORMAL）** | -| `adultSellPrice` | `@NotNull`（允许 0） | `@NotNull + @DecimalMin(0.01)`（不能为 0 或负） | **表单校验 > 0** | - ---- - -## 五、完整请求 / 响应示例 - -### 5.1 请求体（合法） - -```json -POST /admin/product/item/2045018534152478721/price-calendar/batch -Content-Type: application/json - -{ - "startDate": "2026-11-01", - "endDate": "2026-11-05", - "tierSeq": 3, - "priceType": "NORMAL", - "adultSellPrice": 3515, - "childSellPrice": 1175, - "toddlerDiscount": -500, - "infantPrice": 500, - "dailyStock": 20 -} -``` - -### 5.2 成功响应（200） - -```json -{ - "code": 200, - "message": "价格日历设置成功", - "data": null, - "success": true -} -``` - -### 5.3 失败响应 — @Valid 校验失败（400） - -缺 `childSellPrice`： - -```json -{ - "code": 400, - "message": "childSellPrice: 儿童售价不能为空", - "data": null, - "success": false -} -``` - -`adultSellPrice=0`： - -```json -{ - "code": 400, - "message": "adultSellPrice: 成人售价必须大于0", - "data": null, - "success": false -} -``` - -`priceType=XXX`： - -```json -{ - "code": 400, - "message": "priceType: 价格类型必须是 NORMAL/PEAK/HOLIDAY/SPECIAL 之一", - "data": null, - "success": false -} -``` - -### 5.4 失败响应 — Service 业务校验失败（500，BusinessException） - -`tierSeq=99`（产品只有 5 档）： - -```json -{ - "code": 500, - "message": "档位序号99不存在，本产品只有5档", - "data": null, - "success": false -} -``` - -`startDate > endDate`： - -```json -{ - "code": 500, - "message": "开始日期不能晚于结束日期", - "data": null, - "success": false -} -``` - -> ⚠️ 前端展示错误时：**400 和 500 都要弹 toast 显示 `message`**，不能只处理 200。 - ---- - -## 六、前端应配合改进的 4 条（P1） - -### 1. 保存按钮置灰（多档位产品） - -多档位产品（`tiers.length > 1`）的「确认添加」/「保存」按钮： - -- **所有档位 tab 必须都填完「成人售价 + 儿童售价」才允许点击** -- 任一档位缺价 → 按钮禁用 + 提示「请完成所有档位的定价」 - -### 2. 切 tab 时 inline 校验 - -用户在档位 tab A 填了一半想切到 tab B： - -- 当前 tab 的 `adultSellPrice` 或 `childSellPrice` 未填 → 禁止切走 + 弹提示「请先填完当前档位的必填项」 -- 避免用户切走后忘了回来，最后提交时才发现少档位 - -### 3. 服务端 400 / 500 错误高亮 - -- 400 错误的 `message` 格式为 `{fieldName}: {中文说明}`，可按冒号切分定位到具体字段 → 表单红框高亮 -- 500 业务异常（如「档位序号99不存在，本产品只有5档」）直接 toast 显示 message，前端无需猜测语义 -- 若后续有多档聚合校验，异常消息可能形如 `档位【舒适】缺少儿童售价` — 可用正则 `/【(.+?)】/` 提取档位名，滚动到对应 tab - -### 4. 单档位产品同样校验 - -`tiers.length === 1` 的产品也必须校验「成人售价 + 儿童售价」非空非 0，不能因为没 tab 就放行。 - ---- - -## 七、字典速查 — `priceType` 枚举 - -| 值 | 中文 | 说明 | -|----|------|------| -| `NORMAL` | 平日 | 默认值（工作日通用） | -| `PEAK` | 旺季 | 节假日 / 旅游旺季 | -| `HOLIDAY` | 节假日 | 法定节假日 | -| `SPECIAL` | 特殊日 | 大促 / 特价 | - -前端下拉框硬编码这 4 个选项即可（或走字典接口 `/admin/dict-data/type/price_type`）。 - ---- - -## 八、重启提示 - -- 需要重启：`hl-product-service-v2`（端口 8083） -- 部署方式：通过 Deploy Panel 重新部署最新 jar（测试服 `192.168.100.160`） - ---- - -## 九、合并信息 - -| 项目 | 值 | -|------|-----| -| Issue | #747 | -| PR | #748 | -| 合并 commit | `c311e6ee` | -| 目标分支 | `dev` | -| 服务 | `hl-product-service-v2` | - ---- - -## 十、优先级 - -🔴 **P0 破坏性** — 老前端发版后如果不同步改，会让「批量设置价格」整条链路 400 失败，定价流程完全走不通。**前端必须在后端发版前或同步发版，别拖。** diff --git a/changelogs/2026-04/2026-04-17_daily-mileage-refactor.md b/changelogs/2026-04/2026-04-17_daily-mileage-refactor.md deleted file mode 100644 index c92a0ed..0000000 --- a/changelogs/2026-04/2026-04-17_daily-mileage-refactor.md +++ /dev/null @@ -1,194 +0,0 @@ -# 每日行程里程接口重构：GET 改 POST，前端传节点顺序实时试算 - -> **服务**: hl-product-service-v2 (端口 8083，经网关 8080) -> **PR**: #744 -> **Issue**: #737 -> **提交**: `7143671a` -> **日期**: 2026-04-17 -> **类型**: refactor (破坏性变更) -> **影响范围**: 管理端产品编辑 Step3「路线设计」 - ---- - -## ⚠️ 破坏性变更（Breaking Change）⚠️ - -**旧的 `GET /admin/product/item/{id}/daily-mileage` 接口已删除**，前端必须切换到新的 `POST` 接口，否则页面上的里程/时长数据将无法获取。 - ---- - -## 改动概述 - -每日行程距离/时长的计算接口，由"后端从 DB 读取已保存的节点"改为"前端把当前编辑态的节点顺序传过来"，使得 **Step3 路线设计过程中即可实时试算，不再依赖必须先保存 Step2**。 - ---- - -## 使用场景变化 - -| 场景 | 旧方案 | 新方案 | -|------|--------|--------| -| 触发时机 | 必须先保存 Step2 行程，再点按钮查询 | Step3 路线设计过程中随时触发 | -| 数据来源 | 后端从 DB 按产品 ID 读取已保存节点 | 前端将"编辑态"节点顺序传给后端 | -| 前端体验 | 改了顺序必须保存才能看新距离 | 拖动节点后立即可试算 | - ---- - -## 旧接口（已删除） - -| 方法 | 路径 | -|------|------| -| ~~GET~~ | ~~`/admin/product/item/{id}/daily-mileage`~~ | - -旧接口无请求体，后端从 DB 读取。**调用会返回 404/405，请立即切换**。 - ---- - -## 新接口 - -| 方法 | 路径 | -|------|------| -| POST | `/admin/product/item/{id}/daily-mileage` | - -**路径参数**： -- `id`：产品 ID（`Long`，Path Variable），保持与其他接口一致；当前后端不依赖它从 DB 读节点，仅用于日志/鉴权上下文 - -**请求体**：`DailyMileageCalcReqVO` - ---- - -## 请求体字段表 - -### 顶层：`DailyMileageCalcReqVO` - -| 字段 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------| -| `days` | `List<Day>` | 是 | `@NotEmpty`，**最多 30 天**（`@Size(max=30)`） | 按天分组的节点列表 | - -### `days[]`：`Day`（每日行程） - -| 字段 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------| -| `dayNumber` | `Integer` | 是 | ≥1 | 天序号（1,2,3...），与响应中的 `dayNumber` 对应 | -| `nodes` | `List<Node>` | 是 | `@NotEmpty`，**单日最多 50 个**（`@Size(max=50)`） | 该天的节点列表，**按驾车顺序** | - -### `days[].nodes[]`：`Node`（节点） - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `nodeType` | `String` | 是 | 节点类型，见下方「节点类型处理规则」 | -| `resourceId` | `Long` | 是 | 资源 ID，对应资源服务主键 | - ---- - -## 节点类型处理规则 - -**只有以下 5 种"有坐标"的节点会被计算距离**： - -| nodeType | 说明 | -|----------|------| -| `SCENIC` | 景点 | -| `ACTIVITY` | 活动 | -| `HOTEL` | 酒店 | -| `RESTAURANT` | 餐厅 | -| `SERVICE` | 服务/服务区 | - -**以下类型会被静默忽略**（传了也不报错，但不参与计算）： - -| nodeType | 说明 | -|----------|------| -| `TRANSPORT` | 交通段 | -| `PHOTOGRAPHY` | 拍摄/打卡 | -| `FREE` | 自由活动 | -| `CUSTOM` | 自定义 | -| `NOTE` | 备注 | - -前端可以放心把整天的节点全部传过来，后端会自行过滤。 - ---- - -## 响应字段表 - -**响应结构不变**：`Result<List<DailyMileageVO>>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `dayNumber` | `Integer` | 天序号，与请求中的 `dayNumber` 一一对应 | -| `mileage` | `BigDecimal` | 里程，单位：**公里(km)**，保留 1 位小数 | -| `duration` | `Integer` | 驾车时长，单位：**分钟(min)** | - ---- - -## 请求示例 - -```http -POST /admin/product/item/123/daily-mileage -Content-Type: application/json -``` - -```json -{ - "days": [ - { - "dayNumber": 1, - "nodes": [ - { "nodeType": "SCENIC", "resourceId": 3001 }, - { "nodeType": "ACTIVITY", "resourceId": 5001 }, - { "nodeType": "RESTAURANT", "resourceId": 6001 }, - { "nodeType": "HOTEL", "resourceId": 7001 } - ] - }, - { - "dayNumber": 2, - "nodes": [ - { "nodeType": "HOTEL", "resourceId": 7001 }, - { "nodeType": "SCENIC", "resourceId": 3002 }, - { "nodeType": "SERVICE", "resourceId": 8001 }, - { "nodeType": "SCENIC", "resourceId": 3003 } - ] - } - ] -} -``` - ---- - -## 响应示例 - -```json -{ - "code": 0, - "data": [ - { "dayNumber": 1, "mileage": 52.3, "duration": 78 }, - { "dayNumber": 2, "mileage": 143.7, "duration": 195 } - ], - "msg": "" -} -``` - ---- - -## 前端使用建议（Step3 路线设计实时试算） - -1. **触发时机**：用户在 Step3 拖动/增删节点后（推荐 debounce 300~500ms 再请求），或点击"重新计算里程"按钮 -2. **数据来源**：直接用前端当前"编辑态"的节点顺序组装请求体，**不需要先保存草稿** -3. **渲染**：按 `dayNumber` 匹配回请求中的每一天，展示 `mileage` 公里 + `duration` 分钟 -4. **类型过滤**：无需前端过滤节点类型，整天节点直接传即可 -5. **空值处理**：如果某一天节点都没有坐标（例如全是 FREE/CUSTOM），后端会返回 `mileage=0, duration=0` - ---- - -## 校验约束汇总 - -| 规则 | 违反时错误码 | -|------|-------------| -| `days` 不能为空 | 400 参数校验失败 | -| `days` 最多 30 天 | 400 参数校验失败 | -| `days[].nodes` 不能为空 | 400 参数校验失败 | -| `days[].nodes` 单日最多 50 个 | 400 参数校验失败 | - ---- - -## 需要重启的服务 - -**hl-product-service-v2**（端口 8083，经网关 8080）—— 通过 Deploy Panel 重新部署最新 jar。 - -前端测试前请确认该服务已重启。 diff --git a/changelogs/2026-04/2026-04-17_fix_product-simple-list-500.md b/changelogs/2026-04/2026-04-17_fix_product-simple-list-500.md deleted file mode 100644 index 96b97e4..0000000 --- a/changelogs/2026-04/2026-04-17_fix_product-simple-list-500.md +++ /dev/null @@ -1,161 +0,0 @@ -# 修复 商品选择列表接口 500 错误 - -- **日期**: 2026-04-17 -- **服务**: hl-product-service-v2（端口 8083） -- **类型**: BUG 修复（非破坏性） -- **前端影响**: **无需改动** - ---- - -## 修复说明 - -### 现象 - -调用订单创建「选择商品」弹窗的商品列表接口时，**100% 返回 500**： - -```json -{ - "code": 500, - "message": "服务器内部错误", - "data": null, - "success": false -} -``` - -该接口一上线就无法使用，前端弹窗里产品列表始终为空。 - -### 根因 - -Mapper 使用 `selectAll(ProductDO.class)` 把 `ProductDO` 所有字段映射到 VO。其中： - -- 实体 `ProductDO.tiers` 是 **String 类型（存 JSON 字符串）** -- VO `ProductSimpleItemRespVO.tiers` 是 **`List<TierItem>`（结构化列表）** - -MyBatis-Plus Join 在构造 ResultMap 阶段发现同名字段类型不一致，抛 `IllegalStateException`，整个请求返回 500。 - -### 修复方式 - -Mapper 改为**显式 selectFields**，只映射基础字段；`tiers` 字段由 Service 层单独查 `ProductTierDO` 表并解析为结构化列表再塞回 VO。 - -对前端而言：**接口路径、请求参数、响应结构完全不变**，原来调不通的接口现在正常返回数据。 - ---- - -## 接口信息 - -### 请求 - -``` -GET /admin/product/item/simple-list -``` - -**Header**: - -``` -Authorization: Bearer {token} -tenant-id: {租户ID} -``` - -### 查询参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| productType | String | 否 | 产品类型（`CORE`=核心产品，`GROUP`=小蒙马），不传=全部 | -| keyword | String | 否 | 搜索关键词（匹配产品名称） | -| pageNo | Integer | 否 | 页码，默认 1 | -| pageSize | Integer | 否 | 每页条数，默认 50 | - -> 后端固定只返回**已上架**（status=PUBLISHED）的产品，前端不需要传 status。 - -### 响应字段 - -外层（`data`）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| records | Array | 产品列表 | -| total | Long | 总数 | - -`records` 数组中每一项： - -| 字段 | 类型 | 说明 | -|------|------|------| -| productId | Long | 产品ID（JSON 序列化为字符串防精度丢失） | -| productNo | String | 产品编号（如 `C260416002`） | -| name | String | 产品名称 | -| tripDays | Integer | 行程天数 | -| lineName | String | 所属产品线名称（LEFT JOIN 查出） | -| tiers | Array | 该产品的档位列表（可能为空数组） | - -`tiers` 数组中每一项（档位）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| tierSeq | Integer | 档位序号（1 开始） | -| tierName | String | 档位名称（如 `舒适`、`豪华`） | -| tierDescription | String | 档位描述，可能为空字符串 | - ---- - -## 完整请求示例 - -``` -GET /admin/product/item/simple-list?productType=CORE&pageNo=1&pageSize=20 -Authorization: Bearer eyJxxx... -tenant-id: 1 -``` - -## 完整响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "records": [ - { - "productId": "2044704111294672897", - "productNo": "C260416002", - "name": "嗨冰雪3.0南线（6天5晚）", - "tripDays": 6, - "lineName": "嗨冰雪", - "tiers": [ - { "tierSeq": 1, "tierName": "舒适", "tierDescription": "" }, - { "tierSeq": 2, "tierName": "豪华", "tierDescription": "" } - ] - } - ], - "total": 5 - }, - "success": true -} -``` - ---- - -## 前端无需改动 - -> 🟢 **该修复纯属后端 Bug 修复，前端不需要任何调整。** -> -> - 接口路径：**不变** -> - 请求参数：**不变** -> - 响应字段结构：**不变** -> - 错误码/成功码：**不变** -> -> 此前调用此接口拿到 500 的地方，现在可以正常拿到数据；已经写好的调用代码无需修改。 - -如果之前前端为了"兼容 500"加过 try/catch 降级逻辑，可以保留，不会有副作用。 - ---- - -## 重启服务 - -- `hl-product-service-v2`（端口 8083） - ---- - -## 关联信息 - -- **Issue**: #745 -- **PR**: #746（已合并到 dev） -- **Commit**: `cfd901e5` diff --git a/changelogs/2026-04/2026-04-17_frontend-bug_step2-hotel-tiers.md b/changelogs/2026-04/2026-04-17_frontend-bug_step2-hotel-tiers.md deleted file mode 100644 index ed6b98c..0000000 --- a/changelogs/2026-04/2026-04-17_frontend-bug_step2-hotel-tiers.md +++ /dev/null @@ -1,155 +0,0 @@ -# 前端 Bug 通知 — Step2 行程编排「住宿安排」档位显示错乱 - -- **日期**: 2026-04-17 -- **类型**: 前端 Bug 修复指南（**不涉及后端代码改动，后端无需重启**） -- **涉及端**: 管理后台 hl-ui（产品编辑页 Step2） -- **后端服务**: hl-product-service-v2（**仅作接口说明，代码不变**） - ---- - -## 一、问题描述 - -在产品编辑页 Step2「行程编排」→「住宿安排」tab 中： - -- **预期**：显示 5 个档位 tab，名称依次为 `经济 / 舒适 / 轻奢 / 高端 / 豪华`（与 Step1 基础信息配置的 5 档一致） -- **实际**：只显示 **2 个档位 tab**，且名称为 `经奢 / 高端` —— 其中 **"经奢" 这个词在后端任何地方都不存在** - -**复现路径**： -- 环境：测试服 `192.168.100.236` -- 产品 ID：`2045018534152478721` -- 页面：产品编辑 → Step2 行程编排 → 住宿安排 - ---- - -## 二、根因分析（后端已核实） - -### 1. 后端返回的数据是完整正确的 - -调用 `GET /admin/product/item/{id}` 返回 `data.tiers` **完整包含 5 档**，每档都有 `tierSeq` / `tierName` / `tierDescription` 字段，数据无问题。 - -### 2. "经奢" 不是后端字典 - -在整个后端项目（包括 schema.sql、字典表、常量、VO、代码注释）`grep "经奢"` **零匹配**。该字符串**必然是前端代码内写死的**。 - -### 3. itinerary 内 hotels 只有部分档位是业务正常 - -后端 `data.itinerary[*].hotels` 里 `tierSeq` 只出现 `1` 和 `2`，是**用户在 Step2 只给档位 1、2 录入了酒店**的真实业务状态（业务允许不录满全部档位，不是 bug）。 - -前端**不应该**从 `itinerary[*].hotels` 反推档位 tab 列表 —— 这会导致：未录入酒店的档位 tab 直接消失；而一旦索引/字段错位，还会出现 "经奢" 这种幻觉档位名。 - ---- - -## 三、后端接口数据结构（示例） - -接口：`GET /admin/product/item/{id}` - -```json -{ - "code": 0, - "data": { - "id": 2045018534152478721, - "name": "示例产品", - - "tiers": [ - {"tierSeq": 1, "tierName": "经济", "tierDescription": "快捷酒店/双床标间"}, - {"tierSeq": 2, "tierName": "舒适", "tierDescription": "四星酒店/河景房"}, - {"tierSeq": 3, "tierName": "轻奢", "tierDescription": "五星酒店/高级套房"}, - {"tierSeq": 4, "tierName": "高端", "tierDescription": "精品度假酒店/江景套房"}, - {"tierSeq": 5, "tierName": "豪华", "tierDescription": "奢华度假庄园/别墅"} - ], - - "itinerary": [ - { - "dayNumber": 1, - "hotels": [ - {"tierSeq": 1, "hotelId": 111, "hotelName": "某快捷酒店"}, - {"tierSeq": 2, "hotelId": 222, "hotelName": "某四星酒店"} - ] - }, - { - "dayNumber": 2, - "hotels": [] - } - ] - } -} -``` - -字段说明： - -| 字段 | 含义 | 说明 | -|------|------|------| -| `data.tiers` | **档位定义列表**（权威来源） | Step1 基础信息配置，**档位 tab 列表必须用它** | -| `data.tiers[*].tierSeq` | 档位序号 | 1/2/3/4/5 | -| `data.tiers[*].tierName` | 档位中文名 | 经济/舒适/轻奢/高端/豪华 | -| `data.tiers[*].tierDescription` | 档位描述 | 档位下方的说明文字 | -| `data.itinerary[*].hotels` | 某一天的酒店安排 | 按档位可能部分录入，**允许为空数组** | -| `data.itinerary[*].hotels[*].tierSeq` | 该酒店归属的档位 | 用于过滤到对应档位 tab 下展示 | - ---- - -## 四、前端正确渲染逻辑 - -### 1. 档位 tab 列表 - -**严格使用 `data.tiers`**： - -```js -// 正确 -const tierTabs = data.tiers; // 5 档齐全，顺序按 tierSeq - -// 错误 —— 会导致未录酒店的档位消失 -const tierTabs = uniqBy(flatMap(data.itinerary, d => d.hotels), 'tierSeq'); -``` - -### 2. 档位名称 - -**一律用 `tier.tierName` 字段**，禁止前端写死档位名数组： - -```js -// 正确 -<Tab label={tier.tierName} /> - -// 错误 —— 极易出现 "经奢" 这种幻觉 -const TIER_NAMES = ['经济', '经奢', '轻奢', '高端', '豪华']; // 第 2 项就是错的 -<Tab label={TIER_NAMES[tier.tierSeq - 1]} /> -``` - -### 3. 每档下的酒店 - -按当前选中档位的 `tierSeq` 过滤： - -```js -const hotelsOfCurrentTier = day.hotels.filter(h => h.tierSeq === currentTierSeq); -``` - -### 4. 空档位保留 tab，内容区显示空状态 - -即使某档位下 `hotels` 全部为空，**tab 仍然要显示**，内容区渲染空状态提示（如"该档位暂未配置酒店，点击添加"），**禁止隐藏 tab**。 - ---- - -## 五、排查步骤建议 - -1. **全前端代码 grep `经奢`** → 应能定位到写死的字符串来源，删除或修正为从 `tiers` 取值 -2. **定位 Step2 住宿 tab 的数据源**：检查是否从 `itinerary[*].hotels` 聚合 `tierSeq` 推导档位 —— 如是，改为从 `data.tiers` 取 -3. **检查档位名枚举数组**：搜 `['经济'` / `['经济','` 等关键词，排查是否有写死的档位名数组写反 -4. **检查字典调用**：Step2 档位名是否误用了其他字典（如把酒店星级字典当档位用） - ---- - -## 六、验收标准（前端修完后自测） - -- [ ] 产品 `2045018534152478721` Step2「住宿安排」tab **严格显示 5 个档位**，名称依次等于 Step1：`经济 / 舒适 / 轻奢 / 高端 / 豪华` -- [ ] 档位 3（轻奢）、4（高端）、5（豪华）下未录酒店时，**tab 仍然显示**，内容区呈现空状态而非 tab 消失 -- [ ] 档位 1（经济）、2（舒适）下能正确看到已录入的酒店 -- [ ] **全前端代码 grep 不到「经奢」这个字符串** -- [ ] 其他已发布产品随机抽查 2 个，Step2 住宿 tab 档位数与 Step1 配置完全一致 - ---- - -## 七、影响范围 - -- **后端**：无变更，不需要重启服务 -- **前端**：仅 Step2「住宿安排」tab 的档位渲染逻辑修复 -- **数据**：无需订正，线上数据是正确的，仅前端展示错误 diff --git a/changelogs/2026-04/2026-04-17_frontend-bug_step4-pricing-tier-tabs.md b/changelogs/2026-04/2026-04-17_frontend-bug_step4-pricing-tier-tabs.md deleted file mode 100644 index cfaf6d1..0000000 --- a/changelogs/2026-04/2026-04-17_frontend-bug_step4-pricing-tier-tabs.md +++ /dev/null @@ -1,153 +0,0 @@ -# 前端 Bug 通知 — Step4 定价管理 顶部档位 Tab 只显示已有价格的档位 - -- **日期**: 2026-04-17 -- **类型**: 前端 Bug 修复指南（**不涉及后端代码改动，后端无需重启**） -- **涉及端**: 管理后台 hl-ui（产品编辑页 Step4 定价管理） -- **后端服务**: hl-product-service-v2（**后端已核实数据完全正确，无需改动**） - ---- - -## 一、问题描述 - -在产品编辑页 Step4「定价管理」顶部档位切换区域： - -- **预期**：显示产品 Step1 配置的**全部档位 tab**（例如 5 档：`经济 / 舒适 / 轻奢 / 高端 / 豪华`），每个档位都有独立 tab 可点击切换，用户可以给任何档位添加价格 -- **实际**：**只显示已有价格数据的档位 tab**。若用户只给其中 1 档（如"舒适"）设置过价格，顶部就只显示 1 个灰色 tag「舒适」，其他 4 档没有 tab → **用户无法切换到那 4 档去添加价格**，定价页陷入"单档死循环" - -**复现路径**： -- 环境：测试服 `192.168.100.160` -- 产品 ID：`2045018534152478721` -- 页面：产品编辑 → Step4 定价管理 -- 前置：Step1 配置了 5 档（经济/舒适/轻奢/高端/豪华），且只对其中某 1 档设置过价格 - -**截图现象**： -- 顶部只有 1 个 tag「舒适」（对应 tierSeq=2 的价格记录） -- 价格列表显示 ¥7,777 / ¥3,333 / ¥500 / ¥500 -- **其他 4 个档位的 tab 完全缺失** - ---- - -## 二、根因分析（后端已核实无误） - -### 1. 后端接口返回数据 100% 正确 - -调用 `GET /admin/product/item/2045018534152478721`，响应： -```json -{ - "code": 200, - "data": { - "tiers": [ - { "tierSeq": 1, "tierName": "经济", "tierDescription": "快捷酒店/双床标间" }, - { "tierSeq": 2, "tierName": "舒适", "tierDescription": "四星酒店/河景房" }, - { "tierSeq": 3, "tierName": "轻奢", "tierDescription": "五星酒店/高级套房" }, - { "tierSeq": 4, "tierName": "高端", "tierDescription": "精品度假酒店/江景套房" }, - { "tierSeq": 5, "tierName": "豪华", "tierDescription": "奢华度假庄园/别墅" } - ] - } -} -``` - -调用 `GET /admin/product/item/2045018534152478721/price-calendar?month=2026-04`，返回 30 条记录，全部 `tierSeq=2`（对应"舒适"档用户历史设置的价格）。 - -所以： -- 顶部显示「舒适」✓ **与 DB 真实数据完全对应**（DB 里只有 tierSeq=2 的记录） -- 其他档位没 tab 是因为 DB 里没有对应 tierSeq 的价格记录 - -### 2. Bug 所在代码 - -**文件**：`src/views/product/edit/components/steps/PricingStep.vue` - -**问题代码**（大约 218-227 行，顶部档位切换 NButtonGroup 渲染处）： -```vue -<NButtonGroup v-if="isDual" size="small"> - <NButton - v-for="seq in detectedTierSeqs" <!-- ❌ 错！只遍历已有价格的档位 --> - :key="seq" - :type="currentTierSeq === seq ? 'primary' : 'default'" - @click="currentTierSeq = seq" - > - {{ getTierLabel(seq) }} - </NButton> -</NButtonGroup> -``` - -相关变量定义（大约 39-43 行）： -```js -const tiers = computed(() => store.productData.tiers || []) // Step1 配置的全部档位（5 档） -const isDual = computed(() => tiers.value.length > 1 || detectedTierSeqs.value.length > 1) -const currentTierSeq = ref(1) -const detectedTierSeqs = ref([]) // 从价格日历数据中反向检测到的档位 -``` - -`detectedTierSeqs` 在 `loadCalendar` 里从已有价格数据反向 collect（大约 106 行）： -```js -const seqs = [...new Set(rawCalendarData.map(d => d.tierSeq).filter(Boolean))].sort() -detectedTierSeqs.value = seqs -``` - -→ 当 DB 里只有 tierSeq=2 的记录，`detectedTierSeqs = [2]` → 顶部只渲染 1 个 tab 「舒适」。 - ---- - -## 三、修复方案（前端改动） - -### 核心改动 -**顶部档位 tab 应遍历 `tiers`（Step1 配置的全部档位），而不是 `detectedTierSeqs`（从数据反推的档位）**。 - -### 具体修改 - -**文件**：`src/views/product/edit/components/steps/PricingStep.vue` - -**改法**（`v-for` 的集合从 `detectedTierSeqs` 改为 `tiers`）： -```vue -<NButtonGroup v-if="isDual" size="small"> - <NButton - v-for="tier in tiers" - :key="tier.tierSeq" - :type="currentTierSeq === tier.tierSeq ? 'primary' : 'default'" - @click="currentTierSeq = tier.tierSeq" - > - {{ tier.tierName || `档位${tier.tierSeq}` }} - </NButton> -</NButtonGroup> -``` - -### 同步注意 -1. **`isDual` 判断条件保留**：保持 `tiers.value.length > 1 || detectedTierSeqs.value.length > 1`（某些老数据可能没 tiers 但有价格，兜底用 detectedTierSeqs 判 isDual） -2. **`currentTierSeq` 初始化**：建议在 `loadCalendar` 之后做一次校正，如果 `currentTierSeq` 不在 `tiers` 列表里，fallback 到 `tiers[0].tierSeq`，避免默认的 `ref(1)` 在"档位 1 没配置"的产品上访问不到对应价格 -3. **`filterAndAggregate` 过滤条件**：当前判断 `detectedTierSeqs.length > 1` 才 filter，改后建议改成 `tiers.length > 1`（因为切换 tab 是按 Step1 档位切，不按检测出来的档位切） -4. **无需修改 `PriceIntervalEditor.vue`**：该组件里 `tierOptions` 已经是 `store.productData.tiers` 动态生成（弹窗内 5 个档位按钮显示正常） - -### 回归测试点 -- 多档产品（tiers=5）且只给 1 档配过价格 → 顶部应显示 5 个 tab，可自由切换 -- 多档产品且 5 档都配过价格 → 顶部 5 个 tab，每个切换后显示对应档位的价格区间 -- 单档产品（tiers=1）→ 顶部不显示 NButtonGroup（isDual=false） -- 切换档位 tab 后： - - 价格区间列表过滤显示该档位的数据 - - 新增/编辑价格区间时默认 tierSeq = 当前选中的 tab（不是硬编码的 1） - - 删除价格时 `deletePriceCalendar(..., { tierSeq: currentTierSeq.value })` 能正确删除 - ---- - -## 四、后端是否有配合改动 - -**无**。 - -后端数据结构、接口行为、字段定义**完全不变**。本 bug 是纯前端渲染逻辑问题。 - ---- - -## 五、相关接口清单（不变，仅作参考） - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/product/item/{id}` | 产品详情（返回完整 tiers 列表） | -| GET | `/admin/product/item/{id}/price-calendar?month=YYYY-MM` | 查询某月价格日历（返回含 tierSeq 的价格记录列表） | -| POST | `/admin/product/item/{id}/price-calendar/batch` | 批量设置价格（请求体含 tierSeq） | -| DELETE | `/admin/product/item/{id}/price-calendar` | 按 tierSeq + 日期范围删除价格 | - ---- - -## 六、优先级 - -**P1** — 此 bug 会让多档产品的定价流程完全走不通（除了第一次创建时设置的档位外，其余档位永远加不了价格）。建议尽快修复。 diff --git a/changelogs/2026-04/2026-04-17_frontend-hint_vehicle-select-hide-base-price.md b/changelogs/2026-04/2026-04-17_frontend-hint_vehicle-select-hide-base-price.md deleted file mode 100644 index cdef658..0000000 --- a/changelogs/2026-04/2026-04-17_frontend-hint_vehicle-select-hide-base-price.md +++ /dev/null @@ -1,54 +0,0 @@ -# 前端提示：产品编辑「添加车型」弹窗不要展示 basePrice（元/天） - -> **服务**: 无后端改动 -> **日期**: 2026-04-17 -> **类型**: 前端展示建议（非接口变更） -> **涉及页面**: 管理端产品编辑 → 补充信息 → 车辆配置 → 点击「添加车型」后的搜索弹窗 - ---- - -## 现象 - -当前弹窗里,每个候选车型项右侧显示 `5座 · 元/天 · 已添加`,但"元/天"前的价格数字经常是空白（因为 `basePrice` 字段为 null 或 0）,页面只剩孤零零的"元/天"后缀,对用户毫无信息量。 - -## 原因 - -弹窗数据源是 `GET /admin/vehicle/models/all?status=1`（`VehicleModelListVO`）,该 VO 里包含 `basePrice`（基础日租价）字段,前端当前把它拼成 `xxx 元/天` 渲染。 - -但在**产品编辑→车辆配置**这个场景里: - -- 产品保存时只传 `vehicleModelIds`（车型 ID 列表）,**完全不涉及价格**（参考 `ProductSupplementSaveReqVO#vehicleModelIds`） -- 产品报价/订单结算时的车辆成本,走的是**车型自己的价格日历**（`vehicle_price_calendar`）按出发日期查,和列表 VO 里的 `basePrice` 无关 -- `basePrice` 只是车型管理页维护的"参考日租价",很多车型根本没填 - -换句话说:这个场景**既不需要 basePrice,也不应该让用户误以为产品定价会用这个数**。 - -## 建议前端修改 - -### 方案 A（推荐,改动最小） - -在「添加车型」弹窗的候选项渲染里,**整体移除价格列（含"元/天"后缀）**,只保留: - -``` -[封面图] 车型名称 5座 [已添加/添加] -``` - -### 方案 B（更稳妥） - -价格列只在 `basePrice != null && basePrice > 0` 时才展示,为空/为 0 时隐藏整个价格片段（含"元/天"后缀）。 - ---- - -## 后端不变 - -- `VehicleModelListVO` 保持现状,`basePrice` 字段仍返回（车型管理列表页、下拉参考展示等其他场景可能在用） -- 接口签名/响应结构/字典全部不变 -- 无需重启任何服务 - -## 其他用到 basePrice 的地方（前端需自行排查） - -如果前端还有其他地方从这个接口读 `basePrice` 来展示,请一并按"是否与产品定价相关"判断: - -- **车型管理列表页** — 展示 `basePrice` 合理,保留 -- **车型下拉选择（如路线配置选车辆）** — 与定价无关,建议同样隐藏 -- **产品详情里展示已配置车型** — 与定价无关,建议隐藏 diff --git a/changelogs/2026-04/2026-04-17_mp-config-refactor_contact-faq-agreement.md b/changelogs/2026-04/2026-04-17_mp-config-refactor_contact-faq-agreement.md deleted file mode 100644 index 9add4d1..0000000 --- a/changelogs/2026-04/2026-04-17_mp-config-refactor_contact-faq-agreement.md +++ /dev/null @@ -1,300 +0,0 @@ -# 小程序配置模块重构：联系我们 / 常见问题 / 协议政策 - -> **服务**: hl-user-service (端口 8081) -> **PR**: https://git.1814.love:8443/wx/HL/pulls/773 -> **Issue**: https://git.1814.love:8443/wx/HL/issues/766 -> **日期**: 2026-04-17 -> **影响范围**: 管理端三大配置模块（联系我们 / 常见问题 / 协议政策）的所有写接口和大部分读接口 - ---- - -## 背景 - -小程序配置模块历史遗留问题较多： -- Status 字段混用 Integer(0/1) 与 String（"启用/停用"） -- VO 命名不统一：`FaqCategoryVO` / `AgreementRequest` 等不符合团队规范 -- 协议政策每类型应只有一条记录，但历史接口允许多记录 CRUD，数据可能出现同类型多条 -- 没有字典校验 / 条件必填 / 幂等 / 富文本 XSS 过滤，业务错常见 500 - -本次整改按团队规范重构三个模块，统一 VO 命名、字段类型、错误码、安全策略。 - -## 字段统一变更（全三模块） - -### Status 字段：Integer → String - -| 旧值 | 新值 | -|------|------| -| `1` | `"ACTIVE"` | -| `0` | `"INACTIVE"` | - -影响所有请求体 / 响应体中的 `status` / `enabled` 字段，前端请求与展示都需切换成大写英文常量。 - -数据库迁移由 DDL 完成（幂等 SQL，已在 PR 中附带）。 - -### 业务错误码：500 → 400 - -字典值非法、条件校验失败、资源不存在等业务错从 `code=500` 改为 `code=400`，并附中文消息。HTTP 始终 200，前端按 `code` 区分。 - -### 写接口全部加 @Idempotent - -9 个写接口启用幂等控制（3~5 秒窗口），前端连点 / 重试会被返： - -```json -{ - "code": 429, - "success": false, - "message": "请勿重复提交" -} -``` - -改 body 后可再次提交。 - -### 富文本 XSS 过滤（后端自动处理） - -以下字段提交时后端自动清洗 `<script>` / `<iframe>` / `on*` 事件属性等危险标签： -- `Contact.content` -- `FaqItem.answer` -- `Agreement.content` - -前端展示时可直接 `v-html` 渲染，无需额外过滤。 - ---- - -## Contact（联系我们） - -### 字段重命名 - -| 旧字段 | 新字段 | 说明 | -|--------|--------|------| -| `title` | `name` | 渠道名称 | -| `icon` | `iconUrl` | 图标 URL | - -### 字典校验 `channelType` - -| 值 | 说明 | 必填的关联字段 | -|----|------|----------------| -| `ABOUT` | 关于我们 | `content`（富文本介绍）必填 | -| `ONLINE_CS` | 在线客服 | `value`（链接/账号）必填 | -| `PHONE` | 客服电话 | `value`（电话号码）必填 | - -非上述 3 值 → `code=400` + "渠道类型不支持"。 - -### 接口清单 - -#### 管理端 - -| 方法 | 路径 | 说明 | 变更 | -|------|------|------|------| -| POST | `/admin/contact` | 创建 | **Body 结构变更**：原 `ContactRequest` 废弃，改为 `ContactSaveReqVO`（字段见下） | -| PUT | `/admin/contact/{id}` | 修改 | 同上，Body 用 `ContactSaveReqVO`（id 由路径传） | -| DELETE | `/admin/contact/{id}` | 删除 | 签名不变 | -| GET | `/admin/contact/{id}` | 详情 | 响应用 `ContactRespVO`（字段重命名） | -| GET | `/admin/contact/page` | 分页 | 响应项为 `ContactRespVO` | -| GET | `/admin/contact/channel-types/enabled` | **新增**：渠道类型下拉 | `List<Map<value,label>>` | - -#### `ContactSaveReqVO`（请求） - -```json -{ - "channelType": "ABOUT", // 必填。ABOUT / ONLINE_CS / PHONE - "name": "关于呼籁", // 必填。旧名 title - "iconUrl": "https://...", // 选填。旧名 icon - "value": null, // ABOUT 可空；ONLINE_CS/PHONE 必填 - "content": "<p>...</p>", // ABOUT 必填；其他可空。富文本 XSS 过滤 - "sortOrder": 1, // 选填 - "status": "ACTIVE" // 选填，默认 ACTIVE -} -``` - -#### `ContactRespVO`（响应） - -```json -{ - "id": 1, - "channelType": "ABOUT", - "name": "关于呼籁", // 旧名 title - "iconUrl": "https://...", // 旧名 icon - "value": null, - "content": "<p>...</p>", - "sortOrder": 1, - "status": "ACTIVE", // 旧为 Integer 0/1 - "createTime": "2026-04-17 10:00:00", - "updateTime": "2026-04-17 10:00:00" -} -``` - ---- - -## Faq（常见问题） - -### 分类（Category） - -| 方法 | 路径 | 说明 | 变更 | -|------|------|------|------| -| POST | `/admin/faq/categories` | 创建分类 | Body 改为 `FaqCategorySaveReqVO`（原 `FaqCategoryRequest` 废弃） | -| PUT | `/admin/faq/categories/{id}` | 修改分类 | 同上 | -| DELETE | `/admin/faq/categories/{id}` | 删除分类 | **新增业务校验**：分类下有条目时 `code=400` + "该分类下仍有常见问题，无法删除" | -| GET | `/admin/faq/categories/{id}` | 详情 | 响应 `FaqCategoryRespVO` | -| GET | `/admin/faq/categories/page` | 分页 | 响应 `FaqCategoryRespVO` | -| GET | `/admin/faq/categories/enabled` | **新增**：分类下拉 | `List<Map<value,label>>`，只返回 ACTIVE | - -#### `FaqCategorySaveReqVO` - -```json -{ - "name": "预订须知", - "sortOrder": 1, - "status": "ACTIVE" -} -``` - -### 条目（Item） - -| 方法 | 路径 | 说明 | 变更 | -|------|------|------|------| -| POST | `/admin/faq/items` | 创建条目 | Body 改为 `FaqItemSaveReqVO`（原 `FaqItemRequest` 废弃） | -| PUT | `/admin/faq/items/{id}` | 修改条目 | 同上 | -| DELETE | `/admin/faq/items/{id}` | 删除 | 签名不变 | -| GET | `/admin/faq/items/{id}` | 详情 | 响应 `FaqItemRespVO` | -| GET | `/admin/faq/items/page` | 分页 | 响应 `FaqItemRespVO` | - -#### `FaqItemSaveReqVO` - -```json -{ - "categoryId": 1, // 必填，必须是存在且 ACTIVE 的分类 - "question": "如何退订?", - "answer": "<p>...</p>", // 富文本，XSS 过滤 - "sortOrder": 1, - "status": "ACTIVE" -} -``` - -> 若 `categoryId` 指向不存在 / 已停用的分类 → `code=400`。 - -### VO 命名调整（前端 TypeScript 定义需要改） - -| 旧类型 | 新类型 | -|--------|--------| -| `FaqCategoryVO` | `FaqCategoryRespVO` | -| `FaqItemVO` | `FaqItemRespVO` | -| `FaqCategoryRequest` | `FaqCategorySaveReqVO` | -| `FaqItemRequest` | `FaqItemSaveReqVO` | - ---- - -## Agreement（协议政策） - -**核心变化**：每个 `type` 只有一条记录（saveByType 模式），废弃多记录 CRUD。 - -### 废弃接口（前端必须下线） - -| 方法 | 路径 | 处理 | -|------|------|------| -| ~~POST~~ | ~~`/admin/agreement`~~ | **删除**。改用 `/save-by-type` | -| ~~PUT~~ | ~~`/admin/agreement/{id}`~~ | **删除**。改用 `/save-by-type` | -| ~~DELETE~~ | ~~`/admin/agreement/{id}`~~ | **删除**。协议不允许删除，只能停用或覆盖 | - -### 新接口 - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/agreement/save-by-type` | 按类型保存：该 type 不存在则创建，存在则覆盖（幂等） | -| GET | `/admin/agreement/by-type/{type}` | 按类型查询，type 参数为字典值 | -| GET | `/admin/agreement/list` | 返回所有启用协议（简要列表） | - -### 字典 `agreement_type` - -| 值 | 说明 | -|----|------| -| `USER_AGREEMENT` | 用户协议 | -| `PRIVACY_POLICY` | 隐私政策 | - -非上述两值 → `code=400` + "协议类型不支持"。 - -### 旧类型迁移（DDL 完成） - -| 旧值 | 新值 / 处理 | -|------|-------------| -| `user` | `USER_AGREEMENT` | -| `privacy` | `PRIVACY_POLICY` | -| `travel` | 软删（`deleted_at` 设置） | -| `refund` | 软删（`deleted_at` 设置） | - -### `AgreementSaveReqVO`（请求） - -```json -{ - "type": "USER_AGREEMENT", // 必填。USER_AGREEMENT / PRIVACY_POLICY - "title": "用户协议", // 必填 - "content": "<p>...</p>", // 必填，XSS 过滤 - "updateDate": "2026-04-17", // 必填，LocalDate - "sortOrder": 1 // 选填 -} -``` - -> 原 `AgreementRequest` 废弃。 - -### `AgreementRespVO`（响应） - -```json -{ - "id": 1, - "type": "USER_AGREEMENT", - "title": "用户协议", - "content": "<p>...</p>", - "updateDate": "2026-04-17", // 新增字段：LocalDate - "sortOrder": 1, - "status": "ACTIVE", - "createTime": "2026-04-17 10:00:00", - "updateTime": "2026-04-17 10:00:00" -} -``` - ---- - -## 前端适配清单 - -### 必须改 - -- [ ] **所有模块**：请求体 / 响应体 `status` 字段由 `Integer(0/1)` 换为 `String("ACTIVE"/"INACTIVE")` -- [ ] **Contact**：请求体字段 `title → name`、`icon → iconUrl`，响应同步 -- [ ] **Contact**：新建/编辑表单中 `channelType` 切换时，校验关联字段必填逻辑（ABOUT→content，ONLINE_CS/PHONE→value） -- [ ] **Contact**：渠道类型改用 `/admin/contact/channel-types/enabled` 下拉接口，不要写死前端枚举 -- [ ] **Faq**：分类下拉改用 `/admin/faq/categories/enabled` -- [ ] **Faq**：删除分类时处理"分类下有条目"的 400 错误提示 -- [ ] **Faq**：TypeScript 类型改名 `FaqCategoryVO → FaqCategoryRespVO` 等 -- [ ] **Agreement**：三个废弃接口全部下线，统一改用 `/save-by-type` -- [ ] **Agreement**：表单类型下拉只保留 `USER_AGREEMENT` / `PRIVACY_POLICY`，清除 `travel` / `refund` -- [ ] **Agreement**：响应 VO 新字段 `updateDate`，列表需要展示（建议列） -- [ ] **全局**：业务错处理从 `code === 500` 改为 `code === 400`（500 留给真正的系统异常） -- [ ] **全局**：连点/重试按钮要处理 429 "请勿重复提交" - -### 无需改 - -- 列表/详情接口路径不变（除 Agreement 删除的 3 个） -- 富文本字段不用在前端做 XSS 过滤（后端处理了） - ---- - -## 部署步骤（后端已完成，前端配合验证） - -由用户/测试服务器管理员在测试环境执行： - -1. 执行 DDL：`sql/mp_config_refactor_v2.sql`（hl_user_service 库，幂等可重跑） -2. 清 Redis 缓存：`redis-cli DEL hl:menu:tree:* hl:dict:*` -3. 重启 `hl-user-service` -4. 管理员重新登录加载新菜单 - ---- - -## 向后兼容性 - -| 场景 | 兼容性 | -|------|--------| -| 旧前端继续发 Integer status | ❌ **不兼容**。会触发 `@Pattern` 校验返回 400 | -| 旧前端继续用 `title`/`icon` 字段名 | ❌ **不兼容**。响应 VO 不再返这两个字段 | -| 旧前端调 `POST/PUT/DELETE /admin/agreement` | ❌ **不兼容**。接口已删除，404 | -| 旧前端不传 `channelType` 必填字段 | ❌ 400 + 中文消息 | - -**前端必须随本 PR 同步更新**，否则管理端会出现大面积报错。 diff --git a/changelogs/2026-04/2026-04-17_order-v2_add_tier_seq.md b/changelogs/2026-04/2026-04-17_order-v2_add_tier_seq.md deleted file mode 100644 index be32a62..0000000 --- a/changelogs/2026-04/2026-04-17_order-v2_add_tier_seq.md +++ /dev/null @@ -1,45 +0,0 @@ -# 接口变更记录 — 2026-04-17 - -> **服务** hl-order-service-v2 · **类型** feat · **说明** 创建订单/报价预览新增档位参数 - -## 变更总览 - -- **hl-order-service-v2** - - AdminOrder: 创建订单、报价预览新增必填参数 `tierSeq` - - MpOrder: C端创建订单新增必填参数 `tierSeq` - ---- - -## hl-order-service-v2 - -### AdminOrder - -### ✏️ `POST` /admin/order — 创建订单(定制师代下单) - -**请求变更** `AdminOrderSaveReqVO`: - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| 🆕 `tierSeq` | `Integer` | ✅ 是 | 档位序号（最小值1） | - -### ✏️ `POST` /admin/order/quote — 报价预览 - -**请求变更** `QuotePreviewReqVO`: - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| 🆕 `tierSeq` | `Integer` | ✅ 是 | 档位序号（最小值1） | - -### MpOrder（C端/内部） - -### ✏️ `POST` /internal/mp-order/create — C端创建订单 - -**请求变更** `MpOrderSaveReqVO`: - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| 🆕 `tierSeq` | `Integer` | ✅ 是 | 档位序号（最小值1） | - ---- - -> ⚠️ **前端注意**: 创建订单和报价预览接口 `tierSeq` 为必填，不传会返回 400 校验错误。无档位产品传 `1`。 diff --git a/changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md b/changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md deleted file mode 100644 index 16b4a40..0000000 --- a/changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md +++ /dev/null @@ -1,316 +0,0 @@ -# C端订单详情页接口变更 — 2026-04-17 - -> **服务** hl-order-service-v2（端口8094）· **类型** feat -> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) -> **前端实际请求前缀**: `GET /mp/order/`（mp-service 需同步新增 BFF 转发层） - ---- - -## 一、已改接口（1个） - -### ✏️ `GET /mp/order/{orderId}` — 订单详情 - -**请求参数**：不变（路径参数 orderId） - -**返回值变更**：整体结构从 `OrderDetailVO` 改为 `MpOrderDetailVO` - -#### 新增字段 - -| 字段 | 类型 | 必有 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `serviceItems` | `List` | ✅ | 服务包含摘要列表，每项含 type/title/summary/clickable | 见下方 | -| `notIncluded` | `String` | 否 | 不含说明 | `"往返大交通、个人消费"` | -| `priceBreakdown` | `Object` | 否 | 价格明细（新订单有值，历史订单null） | 见下方 | -| `balancePayMethodLabel` | `String` | 否 | 尾款方式标签 | `"落地后由领队收取"` | -| `refundProgress` | `Object` | 否 | 退款进度（退款中/已取消时有值） | 见下方 | -| `tripProgress` | `Object` | 否 | 行程进度（仅行程中状态有值） | 见下方 | -| `invoiceStatus` | `String` | ✅ | 发票状态 | `"AFTER_TRIP"` | -| `productTypeLabel` | `String` | ✅ | 产品类型中文 | `"核心产品"` | - -#### 删除的字段（前端不再使用） - -`totalCost`, `surchargeAmount`, `pendingUpgradeAmount`, `depositRatio`, `balanceProofUrl`, `balancePayMethod`, `remark`, `checklistConfirmed`, `unlockRequestedAt`, `confirmedAt`, `readyAt`, `creatorAdminId`, `creatorName`, `mchId`, `mchName`, `sharerOpenid`, `productSnapshot`, `expiryMinutes`, `timeline`, `processStatus`, `processStatusLabel`, `discountReason`, `discounts`, `surcharges`, `transportSegments`, `roomInfo`, `hotelAssignments`, `hotelAssignmentDetails`, `vehicleInfo`, `refundPolicy`, `refundPolicyId`, `contactName`, `contactPhone` - -#### 保留不变的字段 - -`orderId`, `orderNo`, `groupCode`, `productId`, `productName`, `productCoverUrl`, `productType`, `departureDate`, `returnDate`, `tripDays`, `tripNights`, `adultCount`, `childCount`, `youngChildCount`, `babyCount`, `createTime`, `status`, `statusLabel`, `displayStatus`, `displayStatusLabel`, `cancelReason`, `cancelledAt`, `completedAt`, `expiryTime`, `totalPrice`, `depositAmount`, `balanceAmount`, `paidAmount`, `paymentType`, `paymentTypeLabel`, `paidAt`, `payMethodLabel`, `discountAmount`, `refundAmount`, `contracts`, `insurances`, `travelers`, `todos`, `reviewed`, `customizerId`, `customizerName`, `customizerAvatarUrl`, `customizerQrUrl` - ---- - -## 二、新增接口（6个弹窗） - -> 用户点击 `serviceItems` 列表中某项时按需调用，不需要在详情页一次性请求。 -> 每个接口都需要传 userId（mp-service 从 token 中获取后透传）。 - -### 🆕 `GET /mp/order/{orderId}/tickets` — 门票清单 - -**请求参数**：路径参数 `orderId` - -**返回值** `MpTicketListVO`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `hint` | `String` | 顶部提示语 | -| `items` | `List` | 门票列表 | -| `items[].seq` | `Integer` | 序号（1开始） | -| `items[].scenicName` | `String` | 景点名称 | -| `items[].coverUrl` | `String` | 景点封面图（可能为空） | -| `items[].dayNumber` | `Integer` | 第几天 | -| `items[].originalPrice` | `BigDecimal` | 门票原价/人（可能为null） | -| `items[].included` | `Boolean` | 是否已含 | -| `totalValue` | `BigDecimal` | 门票总价值/人（可能为null） | -| `footerText` | `String` | 底部文案 | - -**响应示例**： -```json -{ - "code": 200, - "data": { - "hint": "以下景点门票已包含在套餐内，无需另购", - "items": [ - { "seq": 1, "scenicName": "莫日格勒河", "coverUrl": null, "dayNumber": 2, "originalPrice": 80.00, "included": true }, - { "seq": 2, "scenicName": "根河湿地", "coverUrl": null, "dayNumber": 3, "originalPrice": 120.00, "included": true } - ], - "totalValue": 200.00, - "footerText": "全部已含·无需再付" - } -} -``` - ---- - -### 🆕 `GET /mp/order/{orderId}/hotels` — 住宿清单 - -**请求参数**：路径参数 `orderId` - -**返回值** `MpHotelListVO`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `hint` | `String` | 顶部提示语（如"5晚精选当地酒店"） | -| `items` | `List` | 酒店列表 | -| `items[].hotelName` | `String` | 酒店名称 | -| `items[].coverUrl` | `String` | 酒店封面图（可能为空） | -| `items[].dayNumber` | `Integer` | 第几天入住 | -| `items[].hotelType` | `String` | 酒店类型（如"5星"/"特色民宿"，可能为空） | -| `items[].roomType` | `String` | 房型（如"大床房"，可能为空） | -| `footerNote` | `String` | 底部备注 | - -**响应示例**： -```json -{ - "code": 200, - "data": { - "hint": "5晚精选当地酒店", - "items": [ - { "hotelName": "海拉尔铂尔曼大酒店", "coverUrl": null, "dayNumber": 1, "hotelType": "", "roomType": "大床房" } - ], - "footerNote": "实际入住酒店以出行前确认为准" - } -} -``` - ---- - -### 🆕 `GET /mp/order/{orderId}/meals` — 餐饮清单 - -**请求参数**：路径参数 `orderId` - -**返回值** `MpMealListVO`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `hint` | `String` | 顶部提示语（如"已含5早8正餐"） | -| `specialMeals` | `List` | 特色正餐列表 | -| `specialMeals[].dayNumber` | `Integer` | 第几天 | -| `specialMeals[].mealName` | `String` | 餐名 | -| `specialMeals[].mealType` | `String` | 餐型（午餐/晚餐） | -| `specialMeals[].description` | `String` | 菜品描述 | -| `stats` | `Object` | 餐饮统计 | -| `stats.breakfast` | `String` | 早餐统计（如"5餐·酒店自助"） | -| `stats.specialDinner` | `String` | 特色正餐统计（如"3餐"） | -| `stats.regularDinner` | `String` | 日常正餐统计（如"5餐·当地特色餐厅"） | -| `footerNote` | `String` | 底部备注 | - -**响应示例**： -```json -{ - "code": 200, - "data": { - "hint": "已含1早2正餐", - "specialMeals": [ - { "dayNumber": 2, "mealName": "手把肉宴", "mealType": "午餐", "description": "含奶茶/手把肉" } - ], - "stats": { "breakfast": "1餐·酒店自助", "specialDinner": "1餐", "regularDinner": "1餐·当地特色餐厅" }, - "footerNote": "对食物有过敏请提前告知领队" - } -} -``` - ---- - -### 🆕 `GET /mp/order/{orderId}/vehicle` — 用车详情 - -**请求参数**：路径参数 `orderId` - -**返回值** `MpVehicleDetailVO`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `hint` | `String` | 顶部提示语 | -| `vehicleName` | `String` | 车型名称 | -| `coverUrl` | `String` | 车型图片（可能为空） | -| `description` | `String` | 车型描述/特点（可能为空） | -| `matchRule` | `String` | 匹配规则说明 | - -**响应示例**： -```json -{ - "code": 200, - "data": { - "hint": "一家一车不拼团·全程同一辆车", - "vehicleName": "商务车", - "coverUrl": null, - "description": "", - "matchRule": "匹配规则：根据出行人数自动配车" - } -} -``` - ---- - -### 🆕 `GET /mp/order/{orderId}/guide` — 领队详情 - -**请求参数**：路径参数 `orderId` - -**返回值** `MpGuideInfoVO`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 姓名（可能为null） | -| `avatarUrl` | `String` | 头像（可能为null） | -| `role` | `String` | 角色标签（固定"主领队"或"领队"） | -| `phone` | `String` | 电话（可能为null） | -| `remark` | `String` | 简介（可能为null） | - -> ⚠️ 产品服务快照扩展完成前，除 `role` 外所有字段可能为 null - ---- - -### 🆕 `GET /mp/order/{orderId}/photographer` — 摄影详情 - -**请求参数**：路径参数 `orderId` - -**返回值** `MpPhotographerInfoVO`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `name` | `String` | 姓名（可能为null） | -| `avatarUrl` | `String` | 头像（可能为null） | -| `role` | `String` | 角色标签（固定"摄影师"） | -| `phone` | `String` | 电话（可能为null） | -| `remark` | `String` | 简介（可能为null） | - -> ⚠️ 同领队，产品服务快照扩展完成前字段可能为 null - ---- - -## 三、新增结构体详细说明 - -### serviceItems（服务包含摘要） - -详情接口返回的 `serviceItems` 是一个数组，每项代表一个服务类别： - -```json -[ - { "type": "HOTEL", "title": "住宿", "summary": "5晚精选当地酒店", "clickable": true }, - { "type": "MEAL", "title": "餐饮", "summary": "5早 8正餐", "clickable": true }, - { "type": "VEHICLE", "title": "用车", "summary": "专属车辆 + 司机", "clickable": true }, - { "type": "GUIDE", "title": "领队", "summary": "全程陪同", "clickable": true }, - { "type": "PHOTOGRAPHER", "title": "摄影", "summary": "全程跟拍 + 精修照片", "clickable": true }, - { "type": "TICKET", "title": "门票", "summary": "4处景点门票", "clickable": true }, - { "type": "INSURANCE", "title": "保险", "summary": "旅行意外险", "clickable": false } -] -``` - -`clickable=true` 时点击应调用对应弹窗接口：`type=HOTEL` → `GET /mp/order/{orderId}/hotels`，以此类推。 - -### priceBreakdown（价格明细） - -```json -{ - "items": [ - { "label": "成人", "unitPrice": 2300.00, "quantity": 2, "amount": 4600.00 }, - { "label": "儿童", "unitPrice": 1800.00, "quantity": 1, "amount": 1800.00 } - ], - "subtotal": 6400.00, - "discounts": [ - { "tag": "早鸟优惠", "description": "提前30天", "amount": -400.00 } - ], - "totalDiscount": -400.00, - "totalPayable": 6000.00 -} -``` - -> ⚠️ 仅新创建的订单有值，历史订单为 null，前端需做空判断 - -### refundProgress（退款进度） - -```json -{ - "steps": [ - { "title": "提交退款申请", "description": "用户发起退款", "status": "COMPLETED", "time": "2026-06-25T16:32:00" }, - { "title": "商家审核中", "description": "客服正在审核您的退款申请", "status": "ACTIVE", "time": null }, - { "title": "退款处理", "description": "原路退回您的微信账户", "status": "PENDING", "time": null }, - { "title": "退款到账", "description": "预计1-3个工作日", "status": "PENDING", "time": null } - ], - "currentStep": 1, - "refundAmount": 1000.00, - "refundMethod": null, - "refundArrivalTime": null -} -``` - -step.status 取值：`COMPLETED`=已完成 / `ACTIVE`=进行中 / `PENDING`=待处理 - -> ⚠️ 仅退款中/已取消且有退款时有值，其他状态为 null - -### tripProgress（行程进度） - -```json -{ - "currentDay": 2, - "totalDays": 6, - "progressPercent": 33, - "todayDestination": "莫日格勒河" -} -``` - -> ⚠️ 仅行程中(displayStatus=TRAVELLING)状态有值，其他状态为 null - -### invoiceStatus 取值 - -| 值 | 说明 | -| --- | --- | -| `ISSUED` | 已开票 | -| `PENDING` | 开票中 | -| `NOT_ISSUED` | 未开票（已完成订单可申请） | -| `AFTER_TRIP` | 出行后可开 | - ---- - -## 四、mp-service BFF 层需同步新增 - -以上6个弹窗接口目前在 order-service-v2 的 `/internal/mp/order/` 路径下已就绪。 -mp-service（hl-mp-service）需要新增对应的 BFF 转发层，路径映射如下： - -| 前端调用 | mp-service 转发到 | -| --- | --- | -| `GET /mp/order/{orderId}/tickets` | `GET /internal/mp/order/{orderId}/tickets?userId=xxx` | -| `GET /mp/order/{orderId}/hotels` | `GET /internal/mp/order/{orderId}/hotels?userId=xxx` | -| `GET /mp/order/{orderId}/meals` | `GET /internal/mp/order/{orderId}/meals?userId=xxx` | -| `GET /mp/order/{orderId}/vehicle` | `GET /internal/mp/order/{orderId}/vehicle?userId=xxx` | -| `GET /mp/order/{orderId}/guide` | `GET /internal/mp/order/{orderId}/guide?userId=xxx` | -| `GET /mp/order/{orderId}/photographer` | `GET /internal/mp/order/{orderId}/photographer?userId=xxx` | - -> mp-service 从用户 token 中提取 userId，作为查询参数透传给 order-service。 diff --git a/changelogs/2026-04/2026-04-17_product-v2-error-message-humanize.md b/changelogs/2026-04/2026-04-17_product-v2-error-message-humanize.md deleted file mode 100644 index f29d750..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2-error-message-humanize.md +++ /dev/null @@ -1,159 +0,0 @@ -# 文案优化：产品服务错误提示批量人性化（去英文状态码/去内部ID） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #765 -> **Issue**: #764 -> **日期**: 2026-04-17 -> **影响范围**: 管理端产品删除/编辑/价格配置/班期管理 + 小程序端报价/库存扣减/报名 的错误提示文案 -> **前置 PR**: #762（2026-04-17_refund-policy-error-message-humanize.md） - ---- - -## 背景 - -延续 #762 的思路,对 `hl-product-service-v2` 里其他对用户可见的 `BusinessException` / `NotFoundException` 文案做一轮批量改造,避免向普通运营展示: - -1. **英文状态码**(`PUBLISHED` / `PENDING_REVIEW` / `DRAFT` 等) -2. **内部主键 ID**(`productId=2045018xxx` / `batchId=xxx` 等) -3. **开发术语**(如"调用此接口") - -技术 ID 全部下沉到 `log.warn` 供后端排查,不再污染用户 toast。 - -## 改动范围 - -**只改异常消息文案与服务端日志**,校验规则、接口签名、返回结构、HTTP code 全部不变。 -前端**无需改造**,toast 显示新文案即可。 - ---- - -## 文案前后对照 - -### 产品删除/编辑状态校验 - -| 场景 | 旧文案 | 新文案 | -|------|--------|--------| -| 已上架产品删除 | `当前状态不允许删除: PUBLISHED` | `当前状态「已上架」不允许删除` | -| 已下单产品编辑 | `当前状态不允许编辑: ORDERED` | `当前状态「已下单」不允许编辑` | -| 待审核产品编辑 | `当前状态不允许编辑: PENDING_REVIEW` | `当前状态「待审核」不允许编辑` | - -状态码→中文映射表(通过新增的 `ProductStatusEnum.nameOfOrCode` 容错方法): - -| code | 中文 | -|------|------| -| DRAFT | 草稿 | -| PENDING_REVIEW | 待审核 | -| PUBLISHED | 已上架 | -| UNPUBLISHED | 已下架 | -| REJECTED | 已驳回 | -| COMPLETED | 已完成 | -| ORDERED | 已下单 | -| `null` / 空 | 未知 | -| 未知值 | 原值回显(降级) | - -### 价格日历/成人售价 - -| 场景 | 旧文案 | 新文案 | -|------|--------|--------| -| 价格日历缺失 | `日期 xxx 档位1 未设置价格日历（产品ID=2045018xxx）` | `日期 xxx 档位1 未设置价格日历,请先配置价格` | -| 成人售价未设置 | `日期 xxx 档位1 的成人售价未设置（产品ID=2045018xxx）` | `日期 xxx 档位1 的成人售价未设置,请先配置价格` | - -### 班期管理 - -| 场景 | 旧文案 | 新文案 | -|------|--------|--------| -| 班期不存在(查询/删除/修改/取消/配员) | `班期不存在: 20450185xxx` | `班期不存在或已删除` | - -### 库存与报名(InternalProductService,被 order-service-v2 Feign 调用) - -| 场景 | 旧文案 | 新文案 | -|------|--------|--------| -| 库存扣减失败 | `库存不足或日期不存在, productId=xxx, date=2026-05-10` | `该日期库存不足或未开放,请重新选择出发日期` | -| 报名入团失败 | `报名失败（名额不足或房间不足）, batchId=xxx` | `报名失败,该班期剩余名额或房间不足` | -| 非定制产品调用 | `仅定制产品可调用此接口, productId=xxx` | `该操作仅支持定制类产品` | - ---- - -## 接口影响(均无签名变化) - -| 接口 | 变化 | -|------|------| -| `DELETE /admin/product/item/{id}` | 错误 `message` 文案变更 | -| `PUT /admin/product/item/{id}/*`(所有编辑类接口) | 状态拒绝文案变更 | -| `POST /admin/product/price-calendar/batch` | 价格相关文案变更 | -| `POST/PUT/DELETE /admin/product/schedule/*` | 班期不存在文案变更 | -| `POST /admin/product/schedule/team/*` | 班期不存在文案变更 | -| `POST /internal/product/simple-quote` | 成人售价文案变更 | -| `POST /internal/product/deduct-stock` | 库存扣减失败文案变更 | -| `POST /internal/product/enroll-batch` | 报名失败文案变更 | -| `POST /internal/product/custom/change-status` | 非定制产品文案变更 | - -HTTP 状态码、`code`、JSON 结构均保持原样。 - ---- - -## 保留未改的文案 - -以下文案**主动保留**,因为它们不属于"不友好"范畴: - -1. **公式编辑器**(FormulaGroupService / FormulaStepService / FormulaVarService) - - 例如:`公式组编码已存在: {code}` / `变量名已存在: {name}` - - 原因:公式编辑功能的使用者是技术人员,编码本身就是用户自己输入的值,回显是必要上下文 -2. **纯中文/数字约束类** - - `请填写【轻奢】正价的成人售价` — 档位名+价格类型 label 均为中文 - - `档位序号99不存在,本产品只有5档` — 数字是必要定位信息 - - `该班期已有3个报名订单,不允许删除` — 数字为必要业务信息 - - `批量创建跨度不能超过12个月` - - `小童优惠额不能超过儿童售价` - ---- - -## 排查信息的去向 - -所有移除的 ID/代码都下沉到 `log.warn`,后端排查时通过日志+时间戳即可定位: - -``` -WARN ProductDeleteService - 产品当前状态不允许删除: productId=1001, status=PUBLISHED -WARN ProductHelperService - 产品当前状态不允许编辑: productId=1001, status=ORDERED -WARN ProductPricingService - 价格日历未设置: productId=1001, date=2026-05-10, tierSeq=1 -WARN ProductPricingService - 成人售价未设置: productId=1001, date=2026-05-10, tierSeq=1 -WARN ProductPricingService - 班期不存在(删除): productId=1001, batchId=8001 -WARN GroupBatchStaffService - 班期不存在(操作员工): productId=1001, batchId=8001 -WARN InternalProductService - 库存扣减失败: productId=1001, date=2026-05-10, count=2 -WARN InternalProductService - 报名入团失败: batchId=8001, people=2, rooms=1 -WARN InternalProductService - 非定制产品调用定制产品状态变更: productId=1001, productType=CORE -``` - ---- - -## 前端适配建议 - -- **无需改代码**:直接显示后端返回 `message` 即可 -- 如果之前对 error message 做过字符串匹配/正则提取 `productId=...`、`batchId=...`、英文状态码等,需要移除相关逻辑 —— 新消息不含这些 -- 状态码中文展示(如果前端自己有映射表)可以沿用本 changelog 顶部的对照表 - ---- - -## 单元测试 - -- `ProductStatusEnumTest` — 新增 3 个用例(合法/null/未知),共 11 个全部通过 -- `ProductHelperServiceTest` — 强化「checkEditable PUBLISHED/PENDING_REVIEW」用例断言:必须含中文状态名、必须不含英文码 -- `ProductDeleteServiceTest` — 强化「deleteProduct PUBLISHED」用例断言:必须含「已上架」、必须不含 `PUBLISHED` -- `GroupBatchStaffServiceTest` — 强化「queryTeam 班期不存在」用例断言:必须含「班期不存在或已删除」、必须不含 batchId -- 受影响测试合计 98/98 通过(覆盖 7 个测试类) - ---- - -## 部署 - -- 仅需重启 `hl-product-service-v2`(端口 8083 + 8183) -- 无 DDL 变更 -- 无配置变更 - ---- - -## 向后兼容性 - -- ✅ 接口签名、响应结构、HTTP code 完全不变 -- ✅ 前端可不改代码直接升级 -- ✅ `ProductStatusEnum.nameOfOrCode` 容错降级(未知状态码原值回显,新状态加入枚举前不会挂) -- ⚠️ 如果前端之前解析过错误消息中的 `productId=` / `batchId=` / 英文状态码,需要移除相关逻辑 diff --git a/changelogs/2026-04/2026-04-17_product-v2_daily-mileage-step5-validation.md b/changelogs/2026-04/2026-04-17_product-v2_daily-mileage-step5-validation.md deleted file mode 100644 index 140c21c..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2_daily-mileage-step5-validation.md +++ /dev/null @@ -1,177 +0,0 @@ -# 修复：daily-mileage 节点过滤 & Step5 上架预检必填校验 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #754 -> **Issue**: #751 -> **日期**: 2026-04-17 -> **影响范围**: Step2 行程编排里程试算、Step5 补充信息上架预检 - ---- - -## 问题 1（P1 阻塞）：Step2 行程编排「计算每日里程」接口 400 - -### 现象 -前端在 Step2 行程编排点"下一步"，后端对节点列表里 `resourceId` 为空的自由活动节点返回： - -```json -{ - "code": 400, - "message": "days[0].nodes[1].resourceId: resourceId不能为空" -} -``` - -### 根因 -`DailyMileageCalcReqVO.NodeRef.resourceId` 挂了 `@NotNull`，但业务上 `FREE/NOTE/TRANSPORT/CUSTOM/PHOTOGRAPHY` 等节点本就不需要 resourceId（它们没有对应的景区/活动/酒店资源）。 - -### 修复 -- 移除 `@NotNull` 和 `required=true` -- 接口层面接受任何节点类型传入；Service 层按节点类型白名单自动过滤，不抛错 - ---- - -## 问题 2（业务规则）：距离计算节点范围收窄 + 酒店去重 - -### 业务规则 -每日驾车距离/时间计算只取：**景区（SCENIC）+ 游玩项目（ACTIVITY）+ 当天第一个酒店（HOTEL）**。 - -### 规则前后对比 - -| 节点类型 | 旧逻辑 | 新逻辑 | -|----------|--------|--------| -| SCENIC | ✅ 参与 | ✅ 参与 | -| ACTIVITY | ✅ 参与 | ✅ 参与 | -| HOTEL | ✅ 全部参与 | ⚠️ **每天只保留 sortOrder 最小的那 1 个** | -| RESTAURANT | ✅ 参与 | ❌ **不参与** | -| SERVICE | ✅ 参与 | ❌ **不参与** | -| TRANSPORT / FREE / CUSTOM / NOTE / PHOTOGRAPHY | ❌ 不参与 | ❌ 不参与（无变化） | - -举例：当天节点序列 `景区1 → 餐厅 → 景区2 → 酒店A → 酒店B → 活动1` -- 旧：6 点参与 → `dist(景1→餐→景2→店A→店B→活1)` -- 新：4 点参与 → `dist(景1→景2→店A→活1)`（餐厅/酒店B 过滤） - -### 影响接口 -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/product/item/{id}/daily-mileage` | Step3 实时试算（前端传节点序列） | -| GET | `/admin/product/item/{id}/mileage` | 总里程（基于保存后的节点） | -| GET | `/admin/product/item/{id}/daily-mileage-saved` | 基于保存后节点的按天里程 | - -### 请求/响应契约 -**请求字段（无变化，仅校验收紧/放宽）**： -```json -{ - "days": [ - { - "dayNumber": 1, - "nodes": [ - {"nodeType": "SCENIC", "resourceId": 3001}, - {"nodeType": "FREE"}, // resourceId 可空 - {"nodeType": "RESTAURANT", "resourceId": 4001}, - {"nodeType": "HOTEL", "resourceId": 5001}, - {"nodeType": "HOTEL", "resourceId": 5002} // 同日第二个酒店 → 过滤 - ] - } - ] -} -``` - -**响应结构（无变化）**： -```json -{ - "code": 200, - "success": true, - "data": [ - {"dayNumber": 1, "mileage": 42.35, "duration": 3600} - ] -} -``` - -### 字段规范 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `days[].dayNumber` | Integer | 天序号，从 1 开始 | -| `days[].nodes[].nodeType` | String | 节点类型（字典 `product_node_type`）：`SCENIC / ACTIVITY / HOTEL / RESTAURANT / SERVICE / TRANSPORT / FREE / CUSTOM / NOTE` | -| `days[].nodes[].resourceId` | Long | **只在 SCENIC/ACTIVITY/HOTEL 时必填**；其他节点允许为空 | - ---- - -## 问题 3：Step5 上架预检补必填校验 - -### 现象 -产品 Step5 补充信息里的「保险方案」「合同方案」「行程保障模板」即使没选，**`validatePublish` 也不报 issue**，导致产品能被提交上架但实际缺字段。 - -### 修复 -在 **`GET /admin/product/item/{id}/validate-publish`** 的 L4 条款校验阶段，新增 3 条 issue： - -| 条件 | 新增 issue 文案 | -|------|-----------------| -| `insuranceNotice` ∈ `{INCLUDED, OPTIONAL}` 且 `insuranceSchemeId == null` | `"保险方案未选择"` | -| `contractSchemeId == null`（不论保险类型） | `"合同方案未选择"` | -| `guaranteeTemplateId == null`（不论保险类型） | `"行程保障模板未选择"` | - -### 响应示例（缺字段时） - -```json -{ - "code": 200, - "success": true, - "data": [ - "保险方案未选择", - "合同方案未选择", - "行程保障模板未选择" - ] -} -``` - -### 保存草稿接口保持宽松 -- `PUT /admin/product/item/{id}/supplement` **不新增校验** —— 继续允许分步填写（空字段能保存） -- 校验只发生在**上架预检**阶段 - -### 字典 insurance_notice - -| Code | 说明 | -|------|------| -| `INCLUDED` | 含保险（必选保险方案） | -| `OPTIONAL` | 可选保险（必选保险方案） | -| `EXCLUDED` | 不含保险（可不选保险方案） | - ---- - -## 前端适配 - -### Step2 行程编排 -- **无需改动**。前端传原样节点序列即可；后端自动按节点类型过滤不参与计算的节点。 -- 旧行为："自由活动"节点进入里程接口时 400 —— 已修复，不再会出现。 - -### Step3 实时里程试算 -- 如果前端之前有"过滤掉餐厅/服务"的代码，**可以去除**（后端已处理）。不去除也无影响（重复过滤 = 过滤）。 - -### Step5 上架预检 -- 前端调 `validate-publish` 时，错误列表里会**新出现**如下 3 个文案，请前端错误映射里补上： - - `"保险方案未选择"` - - `"合同方案未选择"` - - `"行程保障模板未选择"` -- 表现为"点上架 → 后端返回这些 issue → 前端提示用户去 Step5 补充"。 - ---- - -## 单元测试 - -- `AmapDrivingServiceTest`: 21 条（含"同日多酒店取首"、"餐厅/服务过滤"、"跨天多酒店各自取首"三条新增） -- `ProductValidationServiceTest`: 14 条（含 insuranceScheme / contractScheme / guaranteeTemplate 缺失各 1 条） - -## 测试环境验证 - -`api.test.1814.love:9443` 实测通过： - -| 用例 | 结果 | -|------|------| -| `POST /daily-mileage` 混入 FREE 节点 | 200 ✅ | -| `POST /daily-mileage` 同日 3 个 HOTEL | 200（按规则只取首个）✅ | -| `POST /daily-mileage` 含 RESTAURANT+SERVICE | 200（已过滤）✅ | -| `GET /validate-publish` 缺 3 字段 | 3 条 issue ✅ | - -## 重启提示 - -需要重启 `hl-product-service-v2`（端口 8083 + 8183）—— 通过 Deploy Panel 重新部署最新 jar。 diff --git a/changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md b/changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md deleted file mode 100644 index 6b07f9b..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2_detail_snapshot_fields_done.md +++ /dev/null @@ -1,119 +0,0 @@ -# product-v2 产品详情接口扩展快照字段（完成） - -- **日期**: 2026-04-17 -- **服务**: hl-product-service-v2（含 hl-common-core / hl-resource-service 配合） -- **PR**: https://git.1814.love:8443/wx/HL/pulls/742 -- **Issue**: https://git.1814.love:8443/wx/HL/issues/741 -- **影响**: C端订单详情页 6 个服务详情弹窗所需字段已可从订单快照直接读取 - -## 接口 - -### `GET /internal/product/{productId}/detail` - -- **签名不变**，新增字段向前兼容 -- **新增可选 query 参数**：`date=yyyy-MM-dd`（出发日期，匹配班期员工；为空时 staff=[]） - -## 新增/扩展字段 - -### 1. `itinerary[].nodes[]`（NodeItem）新增 4 字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `coverUrl` | String | 资源封面图URL | -| `description` | String | 资源描述 | -| `price` | BigDecimal | 单价（暂传null，后续门票定价体系落地再补） | -| `tags` | String[] | 资源标签（如"5A景区"、"网红打卡"） | - -### 2. 根级新增 `hotels[]`（HotelItem） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `hotelId` | Long | 酒店ID | -| `hotelName` | String | 酒店名称 | -| `roomType` | String | 房型名称 | -| `coverUrl` | String | 酒店封面图URL | -| `hotelType` | String | 酒店类型（"5星"/"特色民宿"/"蒙古包"） | - -> 产品全部住宿按 `hotelId` 去重（多日连住的酒店只出现一次）。 - -### 3. 根级新增 `restaurants[]`（RestaurantItem） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `restaurantId` | Long | 餐厅ID | -| `restaurantName` | String | 餐厅名称 | -| `mealType` | String | 餐别（暂传null，后续补） | -| `description` | String | 菜品描述（如"含奶茶/手把肉/烤包子"） | - -> 从行程节点 `nodeType=RESTAURANT` 按 `resourceId` 去重。 - -### 4. 根级新增 `staff[]`（StaffItem） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `staffRole` | String | 员工角色（LEADER/PHOTOGRAPHER/DRIVER） | -| `staffName` | String | 员工姓名 | -| `staffPhone` | String | 员工电话 | -| `avatarUrl` | String | 头像URL（员工档案未建时为null） | -| `remark` | String | 备注/简介 | - -> 按 `productId + date` 匹配班期，查询 `group_batch_staff`。 -> `date` 为空或无匹配班期时 `staff=[]`。 - -## 调用示例 - -``` -GET /internal/product/1001/detail?date=2026-05-01 -``` - -```json -{ - "code": 200, - "data": { - "productId": 1001, - "name": "呼伦贝尔5日游", - "itinerary": [ - { - "dayId": 10, - "dayNumber": 1, - "dayTitle": "第一天", - "nodes": [ - { - "nodeId": 101, - "nodeType": "SCENIC", - "nodeName": "莫日格勒河", - "resourceId": 2001, - "coverUrl": "https://oss/scenic.jpg", - "description": "天下第一曲水...", - "price": null, - "tags": ["5A景区", "网红打卡"] - } - ] - } - ], - "hotels": [ - { "hotelId": 4001, "hotelName": "草原酒店", "roomType": "标间", - "coverUrl": "https://oss/hotel.jpg", "hotelType": "5星" } - ], - "restaurants": [ - { "restaurantId": 3001, "restaurantName": "蒙古包餐厅", - "mealType": null, "description": "含奶茶/手把肉/烤包子" } - ], - "staff": [ - { "staffRole": "LEADER", "staffName": "张领队", - "staffPhone": "13800001111", "avatarUrl": null, "remark": "10年带团经验" } - ] - } -} -``` - -## 兼容性 - -- **所有新增字段向前兼容**，订单服务侧未改之前不受影响（旧客户端忽略新字段） -- 接口URL与请求参数不变（`date` 为可选新增） -- 下游订单服务侧序列化为 `product_snapshot` 存库，消费端按需读取 - -## 相关改动 - -- `hl-common-core` 的 `ResourceDetailDTO` 新增 `hotelType` 字段 -- `hl-resource-service` 的 `/internal/mp/resource/batch-details` 返回酒店时填充 `hotelType` diff --git a/changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md b/changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md deleted file mode 100644 index 24ea2e7..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md +++ /dev/null @@ -1,157 +0,0 @@ -# 小程序产品详情/列表接口新增支付模式字段 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #715 -> **日期**: 2026-04-17 -> **影响范围**: 小程序端产品详情 + 产品列表 - ---- - -## 一、变更说明 - -小程序端产品详情接口和产品列表接口新增支付模式相关字段，前端可据此展示"全款支付"或"订金+尾款"的支付方式提示。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|---------|------| -| 1 | 产品详情(C端) | GET | `/mp/product/{id}` | 响应新增字段 | 新增 paymentType/depositRatio/depositAmount | -| 2 | 产品线下产品列表 | GET | `/mp/product/list-by-line` | 响应新增字段 | 新增 paymentType | - ---- - -## 三、接口详情 - -### 1. 产品详情 `GET /mp/product/{id}` - -**响应新增字段**（在原有响应基础上新增，其他字段不变）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `paymentType` | String | 支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款 | -| `depositRatio` | Integer | 订金比例(%)，仅 DEPOSIT 时有值，如 `30` 表示30% | -| `depositAmount` | BigDecimal | 订金固定额，仅 DEPOSIT 时有值，如 `2000.00` | - -**响应示例（仅展示新增部分）**： - -```json -{ - "code": 0, - "data": { - "productId": 1001, - "name": "呼伦贝尔亲子5日游", - "paymentType": "DEPOSIT", - "depositRatio": 30, - "depositAmount": null, - "startPrice": 3980.00 - } -} -``` - -**全款产品示例**： - -```json -{ - "code": 0, - "data": { - "productId": 1002, - "name": "三亚蜜月7日游", - "paymentType": "FULL", - "depositRatio": null, - "depositAmount": null, - "startPrice": 5980.00 - } -} -``` - -### 2. 产品列表 `GET /mp/product/list-by-line` - -**响应新增字段**（列表每项新增）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `paymentType` | String | 支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款 | - -**响应示例**： - -```json -{ - "code": 0, - "data": [ - { - "productId": 1001, - "name": "呼伦贝尔亲子5日游", - "paymentType": "DEPOSIT", - "startPrice": 3980.00, - "tierCount": 2 - }, - { - "productId": 1002, - "name": "三亚蜜月7日游", - "paymentType": "FULL", - "startPrice": 5980.00, - "tierCount": 1 - } - ] -} -``` - ---- - -## 四、枚举/字典值 - -### paymentType 支付方式 - -| 值 | 中文 | 说明 | -|----|------|------| -| `FULL` | 全款 | 一次性支付全部金额（默认值） | -| `DEPOSIT` | 订金+尾款 | 先付订金，出发前补尾款 | - ---- - -## 五、业务规则 - -1. **默认值**：未设置支付方式的产品默认返回 `"FULL"` -2. **订金模式**：`paymentType=DEPOSIT` 时，`depositRatio`（百分比）和 `depositAmount`（固定金额）二选一有值 - - `depositRatio=30` 表示订金为总价的30% - - `depositAmount=2000.00` 表示订金固定2000元 - - 两者都有时以 `depositAmount`（固定额）优先 -3. **全款模式**：`paymentType=FULL` 时，`depositRatio` 和 `depositAmount` 均为 `null` - ---- - -## 六、前端实现建议 - -### 产品详情页 - 支付方式提示 - -``` -+---------------------------+ -| 价格区域 | -| 起步价: 3980/人 | -| 支付方式: 订金30% + 尾款 | <-- paymentType=DEPOSIT 时显示 -+---------------------------+ -``` - -**展示逻辑**： -- `paymentType === "FULL"` → 不显示或显示"全款支付" -- `paymentType === "DEPOSIT"` → 显示"订金X% + 尾款"或"订金¥X + 尾款" - - 优先用 `depositAmount`：`"订金¥2000 + 尾款"` - - 无固定额用 `depositRatio`：`"订金30% + 尾款"` - -### 产品列表卡片 - 支付标签 - -``` -+---------------------------+ -| [封面图] | -| 呼伦贝尔亲子5日游 | -| ¥3980起 [订金预订] | <-- paymentType=DEPOSIT 时显示标签 -+---------------------------+ -``` - ---- - -## 七、重启服务 - -需要重启 **hl-product-service-v2**（端口 8083） diff --git a/changelogs/2026-04/2026-04-17_product-v2_quote-crowd-prices-and-tiers.md b/changelogs/2026-04/2026-04-17_product-v2_quote-crowd-prices-and-tiers.md deleted file mode 100644 index c61be0b..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2_quote-crowd-prices-and-tiers.md +++ /dev/null @@ -1,215 +0,0 @@ -# 算价/档位/定金系列变更 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #718, #720, #722, #724 -> **日期**: 2026-04-17 -> **影响范围**: 小程序算价、管理端算价、管理端下单产品选择、小程序档位对比 - ---- - -## 一、变更总览 - -| # | 主题 | PR | -|---|------|----| -| 1 | 固定定金算价按总人头 × 单价 | #718 | -| 2 | 管理端下单产品选择列表补档位 + 新增档位下拉接口 | #720 | -| 3 | 算价接口补全4类人员单价/小计（成人/儿童/小童/幼童） | #722 | -| 4 | 小程序档位对比响应补充档位名称 tierName | #724 | - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|---------|------| -| 1 | 小程序算价 | POST | `/mp/product/quote` | 响应字段语义 + 新增字段 | 固定定金按总人头×单价；新增4类人员单价/小计 | -| 2 | 管理端算价 | POST | `/admin/product/item/quote` | 响应新增字段 | 新增4类人员单价/小计 | -| 3 | 商品选择列表 | GET | `/admin/product/item/simple-list` | 响应新增字段 | 新增 `tiers` 档位数组 | -| 4 | 产品档位下拉 | GET | `/admin/product/item/{productId}/tiers` | **新增接口** | 下单选档位用 | -| 5 | 小程序档位对比 | GET | `/mp/product/{id}/tier-compare` | 响应新增字段 | 每组新增 `tierName` | - ---- - -## 三、接口详情 - -### 1. 小程序算价 `POST /mp/product/quote` - -**响应完整字段**（新增 4 类人员细分）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `adultUnitPrice` | BigDecimal | 成人单价 | -| `childUnitPrice` | BigDecimal | 儿童单价 | -| **`toddlerUnitPrice`** | BigDecimal | 🆕 小童单价 = max(儿童价 + 小童优惠额, 0) | -| **`infantUnitPrice`** | BigDecimal | 🆕 幼童单价（0=免费） | -| `totalAdultPrice` | BigDecimal | 成人小计 | -| `totalChildPrice` | BigDecimal | 儿童小计 | -| **`totalToddlerPrice`** | BigDecimal | 🆕 小童小计 | -| **`totalInfantPrice`** | BigDecimal | 🆕 幼童小计 | -| `grandTotal` | BigDecimal | 总价（4类小计之和，**旧版只含成人+儿童**） | -| `paymentType` | String | `FULL` / `DEPOSIT` | -| `depositRatio` | Integer | 订金比例(%)，仅比例定金 | -| `depositAmount` | BigDecimal | 订金金额（⚠️ 固定定金语义变更见下方） | -| `balanceAmount` | BigDecimal | 尾款金额 | - -**⚠️ 固定定金算法变更（#718）**： - -产品设置"订金固定额"时，之前返回的 `depositAmount` 是单人额度（不随人数变），导致前端显示与实际收款不符。 - -- **旧**：`depositAmount = product.depositAmount` -- **新**：`depositAmount = product.depositAmount × (adultCount + childCount + toddlerCount + infantCount)` -- 若乘出金额 > `grandTotal`，取 `grandTotal` 兜底（防止 balance 为负） -- 比例定金逻辑**不变**（仍按 `grandTotal × ratio%`） - -**示例**（固定定金 500/人，2成人+1儿童+1幼童，grandTotal=13498）： - -```json -{ - "code": 200, - "data": { - "adultUnitPrice": 4999.00, - "childUnitPrice": 3500.00, - "toddlerUnitPrice": 0, - "infantUnitPrice": 0, - "totalAdultPrice": 9998.00, - "totalChildPrice": 3500.00, - "totalToddlerPrice": 0, - "totalInfantPrice": 0, - "grandTotal": 13498.00, - "paymentType": "DEPOSIT", - "depositAmount": 2000.00, // 500 × 4人 - "balanceAmount": 11498.00 - } -} -``` - ---- - -### 2. 管理端算价 `POST /admin/product/item/quote` - -响应新增字段与小程序端一致（`toddlerUnitPrice` / `infantUnitPrice` / `totalToddlerPrice` / `totalInfantPrice`），`grandTotal` 同步包含 4 类。 - ---- - -### 3. 商品选择列表 `GET /admin/product/item/simple-list` - -**请求参数**（无变化）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| productType | String | 否 | CORE / GROUP / CUSTOM | -| keyword | String | 否 | 名称/编号模糊 | -| pageNo / pageSize | Integer | 是 | 分页 | - -**响应新增字段**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| **`tiers`** | Array | 🆕 档位列表（tierSeq / tierName / tierDescription） | - -**响应示例**： - -```json -{ - "code": 200, - "data": { - "records": [ - { - "productId": 2043246204711550977, - "productNo": "C260409001", - "name": "额吉的故乡·亲子版", - "tripDays": 6, - "lineName": "草原环线", - "tiers": [ - {"tierSeq": 1, "tierName": "标准档", "tierDescription": "三星酒店"}, - {"tierSeq": 2, "tierName": "豪华档", "tierDescription": "四星酒店升级"} - ] - } - ], - "total": 10, - "page": 1, - "pageSize": 50 - } -} -``` - -**使用场景**：下单搜索产品时，前端直接展示"有几档/具体档位"，避免再次请求。 - ---- - -### 4. 产品档位下拉 `GET /admin/product/item/{productId}/tiers` 🆕 - -**场景**：下单弹窗内选档位用。算价接口需要 `tierSeq` 参数，前端必须先让用户选档位。 - -**请求**：路径参数 `productId` - -**响应**： - -```json -{ - "code": 200, - "data": [ - {"tierSeq": 1, "tierName": "标准档", "tierDescription": "三星酒店"}, - {"tierSeq": 2, "tierName": "豪华档", "tierDescription": "四星酒店升级"} - ] -} -``` - -**异常**：产品不存在 → `code=404`，`message="产品不存在: xxx"` - ---- - -### 5. 小程序档位对比 `GET /mp/product/{id}/tier-compare` - -**响应变化**：`tiers[].tierName` 🆕 新增字段。 - -```json -{ - "code": 200, - "data": { - "tiers": [ - { - "tierSeq": 1, - "tierName": "标准档", // 🆕 - "hotels": [...] - }, - { - "tierSeq": 2, - "tierName": "豪华档", // 🆕 - "hotels": [...] - } - ] - } -} -``` - ---- - -## 四、前端适配指南 - -### 小程序端 -1. **算价展示**：渲染 4 类人员的单价和小计；固定定金产品场景下 `depositAmount` 现在会随人数变化 -2. **档位对比页**：用 `tiers[].tierName` 作为卡片标题（此前只能显示"档位1"之类） - -### 管理端 -1. **下单产品选择弹窗**：`simple-list` 响应里直接拿 `tiers` 展示档位数；选中产品后用 `GET /{productId}/tiers` 渲染档位下拉 -2. **算价展示**：渲染 4 类人员单价/小计 - ---- - -## 五、重启提示 - -**需要重启的服务**：`hl-product-service-v2`（端口 8083） - -不涉及 DB DDL，仅代码变更；字段注释有更新（`deposit_amount` COMMENT），但不影响运行时。 - ---- - -## 六、关联 Issue/PR - -| Issue | PR | 主题 | -|-------|-----|------| -| #717 | #718 | 固定定金按人数计算 | -| #719 | #720 | simple-list 补档位 + 档位下拉接口 | -| #721 | #722 | 算价补全 4 类人员单价 | -| #723 | #724 | 档位对比补 tierName | diff --git a/changelogs/2026-04/2026-04-17_product-v2_quote-deposit-tierseq.md b/changelogs/2026-04/2026-04-17_product-v2_quote-deposit-tierseq.md deleted file mode 100644 index c95df2b..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2_quote-deposit-tierseq.md +++ /dev/null @@ -1,161 +0,0 @@ -# 算价接口补充订金尾款 + 档位参数 + 数据校验 - -> **服务**: hl-product-service-v2 (端口 8083) + hl-order-service-v2 (端口 8084) -> **PR**: #716 -> **日期**: 2026-04-17 -> **影响范围**: 小程序端算价、内部算价、订单创建 - ---- - -## 一、变更说明 - -1. **小程序算价接口**新增订金/尾款金额返回，前端可直接展示"支付订金 ¥X / 尾款 ¥X" -2. **内部算价接口**新增 `tierSeq` 档位参数，支持多档位差异报价 -3. **订单创建**全链路透传 `tierSeq`，创建订单时按用户选择的档位算价 -4. **数据校验**：产品ID不存在、档位不存在、价格为0 均返回明确错误 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|---------|------| -| 1 | C端报价 | POST | `/mp/product/{id}/quote` | 响应新增字段 | 新增 paymentType/depositAmount/balanceAmount | -| 2 | 内部简单报价 | GET | `/internal/product/{id}/simple-quote` | 请求新增参数 | 新增 tierSeq 参数 | -| 3 | C端创建订单 | POST | `/internal/order/mp/create` | 请求新增字段 | 新增 tierSeq | -| 4 | 管理端创建订单 | POST | `/admin/order/create` | 请求新增字段 | 新增 tierSeq | -| 5 | 管理端报价预览 | POST | `/admin/order/quote` | 请求新增字段 | 新增 tierSeq | - ---- - -## 三、接口详情 - -### 1. C端报价 `POST /mp/product/{id}/quote` - -**请求参数**（无变化，tierSeq 已有）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| departureDate | String | 是 | 出发日期，格式 yyyy-MM-dd | -| adultCount | Integer | 是 | 成人数（≥1） | -| childCount | Integer | 否 | 儿童数，默认0 | -| tierSeq | Integer | 否 | 档位序号，默认1 | - -**响应新增字段**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `paymentType` | String | 支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款 | -| `depositRatio` | Integer | 订金比例(%)，仅 DEPOSIT 时有值 | -| `depositAmount` | BigDecimal | 订金金额，仅 DEPOSIT 时有值 | -| `balanceAmount` | BigDecimal | 尾款金额，仅 DEPOSIT 时有值 | - -**DEPOSIT产品响应示例**： - -```json -{ - "code": 200, - "data": { - "adultUnitPrice": 4999.0, - "childUnitPrice": 3499.0, - "totalAdultPrice": 9998.0, - "totalChildPrice": 3499.0, - "grandTotal": 13497.0, - "paymentType": "DEPOSIT", - "depositRatio": 30, - "depositAmount": 4049.10, - "balanceAmount": 9447.90 - } -} -``` - -**FULL产品响应示例**： - -```json -{ - "code": 200, - "data": { - "grandTotal": 9998.0, - "paymentType": "FULL", - "depositRatio": null, - "depositAmount": null, - "balanceAmount": null - } -} -``` - -### 2. C端/管理端创建订单 - 新增 tierSeq - -**请求新增字段**（MpOrderSaveReqVO / AdminOrderSaveReqVO）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `tierSeq` | Integer | 否 | 档位序号，默认1。多档位产品需传入用户选择的档位 | - -**请求示例**： - -```json -{ - "productId": 2042826067407925249, - "departureDate": "2026-07-01", - "adultCount": 2, - "childCount": 1, - "tierSeq": 2, - "contactName": "张三", - "contactPhone": "13800138000" -} -``` - ---- - -## 四、错误码新增 - -| 场景 | code | message 示例 | -|------|------|-------------| -| 产品不存在(MP) | 404 | 产品不存在或已下架 | -| 产品不存在(内部) | 404 | 产品不存在: 999 | -| 档位不存在 | 404 | 日期 2026-07-01 档位99 未设置价格日历（产品ID=xxx） | -| 日期无价格 | 404 | 日期 2030-01-01 档位1 未设置价格日历（产品ID=xxx） | -| 成人售价为0 | 500 | 日期 2026-07-01 档位1 的成人售价未设置（产品ID=xxx） | - ---- - -## 五、前端实现建议 - -### 支付按钮区域 - -``` -paymentType === "DEPOSIT" 时： -+---------------------------+ -| 支付订金 ¥4,049 | <-- depositAmount -| 尾款 ¥9,448 落地后由领队收取 | <-- balanceAmount -+---------------------------+ - -paymentType === "FULL" 时： -+---------------------------+ -| 立即支付 ¥13,497 | <-- grandTotal -+---------------------------+ -``` - -### 多档位选择 - -用户切换档位时，重新调用 `/mp/product/{id}/quote`，传入对应 `tierSeq`，刷新价格展示。 - ---- - -## 六、数据库变更 - -```sql --- order_info 表新增档位字段 -ALTER TABLE order_info ADD COLUMN tier_seq INT DEFAULT 1 COMMENT '档位序号(默认1)' AFTER room_count; -``` - ---- - -## 七、重启服务 - -需要重启： -- **hl-product-service-v2**（端口 8083） -- **hl-order-service-v2**（端口 8084） - -测试环境需同步执行上述 DDL。 diff --git a/changelogs/2026-04/2026-04-17_product-v2_toggle-publish-aop-fix.md b/changelogs/2026-04/2026-04-17_product-v2_toggle-publish-aop-fix.md deleted file mode 100644 index 0ca232c..0000000 --- a/changelogs/2026-04/2026-04-17_product-v2_toggle-publish-aop-fix.md +++ /dev/null @@ -1,38 +0,0 @@ -# 修复：产品上架/下架切换接口 500 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #726 -> **Issue**: #725 -> **日期**: 2026-04-17 -> **影响范围**: 管理端产品上架/下架操作 - ---- - -## 现象（前端感知） - -点击产品「上架」/「下架」按钮后，后端返回 `{"code":500, "message":"服务器内部错误"}`，操作失败。 - -## 根因 - -`ProductStatusService.togglePublish` 内部调用 `this.doTogglePublishInTx(...)` 是 Spring AOP 自调用，绕过代理，`@Transactional` 注解失效 → 方法内的 `registerAfterCommit` 拿不到事务上下文，抛 `IllegalStateException: Transaction synchronization is not active`。 - -## 修复 - -- `@Lazy` setter 注入自身代理 `self` -- `togglePublish` 改用 `self.doTogglePublishInTx(...)` 走 AOP 代理，`@Transactional` 生效 - -## 接口契约 - -**无变化**。仅修复原本应该 200 却误返 500 的 bug，接口路径/参数/响应结构未变动。 - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/product/item/{id}/toggle-publish` | 上架/下架切换（修复后正常 200） | - -## 前端适配 - -**无需改动**。原本的调用代码现在能正常工作。 - -## 重启提示 - -需要重启 `hl-product-service-v2`（端口 8083）—— 通过 Deploy Panel 重新部署最新 jar。 diff --git a/changelogs/2026-04/2026-04-17_refund-policy-apply-pay-type.md b/changelogs/2026-04/2026-04-17_refund-policy-apply-pay-type.md deleted file mode 100644 index 207e81c..0000000 --- a/changelogs/2026-04/2026-04-17_refund-policy-apply-pay-type.md +++ /dev/null @@ -1,241 +0,0 @@ -# 新增：退款政策按产品支付类型（FULL/DEPOSIT/BOTH）过滤 - -> **服务**: hl-order-service-v2 (端口 8094) + hl-product-service-v2 (端口 8083) -> **PR**: #755 -> **Issue**: #752 -> **日期**: 2026-04-17 -> **影响范围**: 管理端退款政策下拉、产品 Step5 预订须知保存、产品上架预检 - ---- - -## 背景 - -Step5 预订须知的「退款政策下拉」与产品 Step1 的 `paymentType` 无关联：定金产品也能选到"全款退款政策"，语义错位，订单退款计算时可能走错规则。 - -## 设计要点 - -- `refund_policy` 表新增 `apply_pay_type` 字段（复用字典 `payment_type`，扩容 `BOTH` 枚举值） -- 下拉接口加可选 `payType` 参数按类型过滤；**不传 = 全量返回**（老前端页面兼容不改） -- 保存 supplement 时后端做硬校验：不匹配直接拦截 -- 上架预检 `validate-publish` 也做一次匹配校验（防止 refund_policy 被改过后绕过） - ---- - -## 字段扩展 - -### `RefundPolicyVO` / `RefundPolicyRequest` / Feign `RefundPolicyDTO` 全部新增字段 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `applyPayType` | String | 否 | 适用支付类型（字典 `payment_type`：`FULL`=全款 / `DEPOSIT`=定金 / `BOTH`=两者均可）。创建时未传默认 `BOTH` | - -### 字典 `payment_type`（本次扩容 BOTH） - -| Code | 说明 | 用途 | -|------|------|------| -| `FULL` | 全款 | 产品支付类型 + 退款政策适用类型 | -| `DEPOSIT` | 定金 | 产品支付类型 + 退款政策适用类型 | -| `BOTH` | 两者均可 | **仅用于退款政策**，表示对 FULL/DEPOSIT 产品均适用 | - -> 注意：`product_basic.payment_type` 只会是 `FULL` 或 `DEPOSIT`；`BOTH` 只出现在 `refund_policy.apply_pay_type`。 - ---- - -## 接口变更 - -### 1. 退款政策下拉（加可选过滤参数） - -**`GET /admin/order/refund-policy/enabled`** - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `payType` | String | 否 | 产品支付类型。仅允许 `FULL` / `DEPOSIT`（传 `BOTH` 会报 400） | - -**过滤规则**： -- 不传 → 返回全部启用政策（向后兼容） -- `payType=FULL` → 返回 `apply_pay_type ∈ {FULL, BOTH}` 的政策 -- `payType=DEPOSIT` → 返回 `apply_pay_type ∈ {DEPOSIT, BOTH}` 的政策 -- `payType=INVALID` 或其他值 → `code=400` + `message="支付类型仅支持 FULL/DEPOSIT"` - -**响应示例**： -```json -{ - "code": 200, - "success": true, - "data": [ - { - "policyId": 2, - "policyName": "全款默认退款政策", - "enabled": true, - "applyPayType": "FULL", - "remark": "全款退款默认策略", - "rules": [ - {"ruleId": "...", "minDays": 7, "refundRatio": 100}, - {"ruleId": "...", "minDays": 3, "refundRatio": 50}, - {"ruleId": "...", "minDays": 1, "refundRatio": 0} - ] - } - ] -} -``` - -### 2. 退款政策详情 / 列表 / 批量 - -这几个接口**不变签名**，但响应 VO 自动带出 `applyPayType` 字段： - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/order/refund-policy/{policyId}` | 详情 | -| GET | `/admin/order/refund-policy/page` | 管理端列表 | -| GET | `/internal/order/refund-policy/batch?policyIds=...` | Feign 批量（产品服务内部调用） | - -### 3. 退款政策创建 / 修改 - -**`POST /admin/order/refund-policy` / `PUT /admin/order/refund-policy/{policyId}`** - -Body 新增可选字段： -```json -{ - "policyName": "我的退款政策", - "applyPayType": "FULL", // 可选：FULL/DEPOSIT/BOTH；不传兜底 BOTH - "enabled": true, - "remark": "...", - "rules": [...] -} -``` - -- 校验：`@Pattern(^(FULL|DEPOSIT|BOTH)$)` -- 未传时服务端默认写 `BOTH` -- 更新时**无条件覆盖**（如果只传了 policyName 未传 applyPayType，会被覆盖为 `BOTH`。如需保留原值，前端编辑时务必把原 `applyPayType` 回传） - -### 4. 产品补充信息保存 —— 新增前置阻断 - -**`PUT /admin/product/item/{id}/supplement`** - -Body 不变，但**前置校验**：传入的 `refundPolicyId` 的 `applyPayType` 必须与产品 `paymentType` 匹配。不匹配直接拦截： - -```json -{ - "code": 500, - "success": false, - "message": "退款政策支付类型不匹配:产品为 DEPOSIT,政策仅适用于 FULL。请选择匹配的退款政策(productId=xxx, refundPolicyId=xxx)" -} -``` - -匹配规则： -| 产品 paymentType | 政策 applyPayType | 结果 | -|------------------|-------------------|------| -| FULL | FULL | ✅ 放行 | -| FULL | DEPOSIT | ❌ 阻断 | -| FULL | BOTH | ✅ 放行 | -| DEPOSIT | FULL | ❌ 阻断 | -| DEPOSIT | DEPOSIT | ✅ 放行 | -| DEPOSIT | BOTH | ✅ 放行 | -| 任意 | `refundPolicyId=null` | ✅ 放行（允许草稿不选） | -| paymentType 未填 | 任意 | ✅ 放行（草稿阶段） | - -特殊异常： -- 传了 `refundPolicyId` 但政策不存在/已停用 → `"所选退款政策不存在或已停用"` -- 订单服务 Feign 不可达 → `"退款政策服务暂时不可用,请稍后重试"` - -### 5. 产品上架预检 —— 新增匹配校验 - -**`GET /admin/product/item/{id}/validate-publish`** - -响应 issues 列表里**可能新增**： -``` -"退款政策支付类型不匹配:产品为 DEPOSIT,政策仅适用于 FULL。请选择匹配的退款政策(productId=..., refundPolicyId=...)" -``` - -防止：运营改了 `refund_policy.apply_pay_type` 后，已绑定的产品上架时绕过前置校验。 - ---- - -## 前端适配（重要） - -### Step5 预订须知页 - -1. **进入 Step5 时**：用产品当前 `paymentType` 拉下拉 - ``` - GET /admin/order/refund-policy/enabled?payType=FULL - ``` - -2. **Step1 `paymentType` 切换时**：**清空当前 `refundPolicyId` 并重拉下拉**（否则前端缓存的旧下拉项可能已不匹配新支付类型，保存时 500 报错） - -3. **老前端兼容**：如果暂不改造，`GET /enabled` 不传 payType 会返回全量政策，用户选错类型时保存接口会 500 拦截并给出中文错误消息 —— 不会写脏数据。 - -### 退款政策管理页 - -1. **列表**：表格新增一列展示 `applyPayType`（FULL/DEPOSIT/BOTH） -2. **新建/编辑表单**：新增单选项 `applyPayType`，默认 `BOTH` -3. **编辑时**：如果拿到政策详情后用户只改了其他字段未改 applyPayType，**必须把原值一起回传**，否则会被 `BOTH` 覆盖 - -### 字典值中文映射 - -```js -const applyPayTypeMap = { - FULL: '仅全款产品', - DEPOSIT: '仅定金产品', - BOTH: '全款/定金均可' -}; -``` - ---- - -## 部署步骤（DDL + 代码） - -### DDL（必须先于代码部署） - -```sql --- 1) 新增字段 + 索引 -ALTER TABLE refund_policy - ADD COLUMN apply_pay_type VARCHAR(32) NOT NULL DEFAULT 'BOTH' - COMMENT '适用支付类型(字典payment_type: FULL=全款/DEPOSIT=定金/BOTH=两者均可)' - AFTER enabled; -ALTER TABLE refund_policy ADD INDEX idx_rp_apply_pay_type (apply_pay_type, enabled); - --- 2) 人工确认 policy_id 后再执行 --- SELECT policy_id, policy_name FROM refund_policy WHERE deleted_at IS NULL; -UPDATE refund_policy SET apply_pay_type = 'DEPOSIT' WHERE policy_id IN (<定金默认_ID>) AND deleted_at IS NULL; -UPDATE refund_policy SET apply_pay_type = 'FULL' WHERE policy_id IN (<全款默认_ID>) AND deleted_at IS NULL; --- 其他历史政策保持 BOTH -``` - -> **注意**：订单 v2 服务连的是 `hl_order_service_v2` 数据库，**不是** `hl_order_service`（后者是 legacy 老服务）。 - -### 重启服务 -- `hl-order-service-v2`（端口 8094 + 8194） -- `hl-product-service-v2`（端口 8083 + 8183）—— 因为新增了 Validator + saveSupplement 前置调用 - ---- - -## 单元测试 - -- `RefundQueryServiceTest`: 25 条（含按 payType 过滤、create/update 默认 BOTH） -- `AdminRefundPolicyControllerTest`: 6 条（含 /enabled 无参 + 带 FULL 参数两路分流） -- `ProductRefundPolicyValidatorTest`: 12 条（匹配矩阵 FULL/DEPOSIT/BOTH + Feign 异常 + 政策不存在） -- `ProductValidationServiceTest`: 6 条（含退款政策不匹配生成 issue） - -## 测试环境验证 - -`api.test.1814.love:9443` 实测通过： - -| 用例 | 结果 | -|------|------| -| `/enabled` 无参 | 返回 2 条 + `applyPayType` 字段 ✅ | -| `/enabled?payType=FULL` | 只返"全款默认" ✅ | -| `/enabled?payType=DEPOSIT` | 只返"定金默认" ✅ | -| `/enabled?payType=INVALID` | code=400 + 中文消息 ✅ | -| DEPOSIT 产品 + FULL 政策 | 阻断 ✅ | -| DEPOSIT 产品 + DEPOSIT 政策 | 放行 ✅ | -| FULL 产品 + DEPOSIT 政策 | 阻断 ✅ | - ---- - -## 向后兼容性 - -- ✅ 老前端不传 `payType` → 全量返回（页面不改可跑） -- ✅ 老前端创建政策不传 `applyPayType` → 服务端默认 `BOTH` -- ✅ Feign `batchGetPolicies` 响应自动带出新字段（Jackson 默认忽略未知字段） -- ✅ DDL `NOT NULL DEFAULT 'BOTH'` → 现有数据零阻断 -- ⚠️ 老前端编辑政策不传 `applyPayType` → **会被覆盖为 BOTH**（如不希望丢原值，前端编辑时需要把详情里的 applyPayType 一起回传） diff --git a/changelogs/2026-04/2026-04-17_refund-policy-error-message-humanize.md b/changelogs/2026-04/2026-04-17_refund-policy-error-message-humanize.md deleted file mode 100644 index 8155fb3..0000000 --- a/changelogs/2026-04/2026-04-17_refund-policy-error-message-humanize.md +++ /dev/null @@ -1,122 +0,0 @@ -# 文案优化：退款政策校验错误提示人性化（去技术代码/去ID） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #762 -> **Issue**: #761 -> **日期**: 2026-04-17 -> **影响范围**: 管理端产品 Step5 保存 + 产品上架预检时,退款政策不匹配/不存在的错误提示文案 -> **前置 PR**: #755（2026-04-17_refund-policy-apply-pay-type.md） - ---- - -## 背景 - -前置 PR（#755）接入退款政策与产品支付类型的匹配校验后,错误提示对普通运营不友好： - -旧： -``` -退款政策支付类型不匹配:产品为 DEPOSIT,政策仅适用于 FULL。请选择匹配的退款政策(productId=2045018534152478721, refundPolicyId=2) -``` - -问题： -1. 带 `FULL`/`DEPOSIT` 英文代码,非技术用户看不懂 -2. 带 `productId`/`refundPolicyId` 内部主键,对用户毫无意义且污染 toast -3. 不告诉用户"哪条"退款政策不对,只能靠记 - -## 改动范围 - -**只改异常消息文案与服务端日志**,校验规则、接口签名、返回结构、HTTP code 全部不变。 - -前端**无需改造**,已对接的 toast 显示新文案即可。 - ---- - -## 文案对照 - -### 场景 1：不匹配（最常见） - -| 产品 paymentType | 政策 applyPayType | 新提示 | -|---|---|---| -| DEPOSIT | FULL (有政策名「全款默认」) | `退款政策「全款默认」仅适用于全款产品,当前产品为定金,不匹配。请重新选择退款政策` | -| FULL | DEPOSIT (有政策名「定金退款」) | `退款政策「定金退款」仅适用于定金产品,当前产品为全款,不匹配。请重新选择退款政策` | -| DEPOSIT | FULL (政策名缺失/null) | `所选退款政策仅适用于全款产品,当前产品为定金,不匹配。请重新选择退款政策` | - -- 支付类型代码 `FULL`/`DEPOSIT` → 中文「全款」/「定金」 -- 政策带名称时展示 `退款政策「xxx」`,方便用户定位具体政策 -- 政策名为空时降级为 `所选退款政策` -- 不再暴露 `productId`/`refundPolicyId` - -### 场景 2：政策不存在/已停用 - -- 旧：`所选退款政策不存在或已停用: productId=xxx, refundPolicyId=xxx` -- 新：`所选退款政策不存在或已停用,请重新选择` - -### 场景 3：订单服务 Feign 不可达 - -- 不变：`退款政策服务暂时不可用,请稍后重试` - ---- - -## 排查信息的去向 - -`productId`/`refundPolicyId` 从用户可见消息中移除,但仍通过 `log.warn` 写入后端日志供排查： - -``` -WARN ProductRefundPolicyValidator - 退款政策支付类型不匹配: - productId=1001, productPayType=DEPOSIT, refundPolicyId=8001, policyPayType=FULL - -WARN ProductRefundPolicyValidator - 退款政策不存在或已停用: - productId=1001, refundPolicyId=8001 -``` - ---- - -## 接口影响（均无签名变化） - -| 接口 | 变化 | -|------|------| -| `PUT /admin/product/item/{id}/supplement` | 错误 `message` 文案变更 | -| `GET /admin/product/item/{id}/validate-publish` | `issues` 列表中该类文案变更 | - -HTTP 状态码、`code`、结构均保持原样。 - ---- - -## 前端适配建议 - -- **无需改代码**：直接显示后端返回 `message` 即可 -- 如果之前对消息内容做过字符串匹配（比如正则提取 `productId=...`),需要移除相关逻辑 —— 新消息不含 ID -- 字典值中文映射（如列表展示时用）仍沿用 #755 changelog 提供的： - ```js - const applyPayTypeMap = { - FULL: '仅全款产品', - DEPOSIT: '仅定金产品', - BOTH: '全款/定金均可' - }; - ``` - ---- - -## 单元测试 - -`ProductRefundPolicyValidatorTest` 13/13 全部通过： - -- 原 12 条覆盖匹配矩阵（FULL/DEPOSIT/BOTH + Feign 异常 + 政策不存在）全部更新断言为中文文案 -- 新增「政策名为空时降级为所选退款政策」用例 -- 新增 `hasMessageNotContaining` 兜底断言：不再出现 `FULL`/`DEPOSIT`/productId/refundPolicyId - ---- - -## 部署 - -- 仅需重启 `hl-product-service-v2`（端口 8083 + 8183） -- 无 DDL 变更 -- 无配置变更 - ---- - -## 向后兼容性 - -- ✅ 接口签名、响应结构、HTTP code 完全不变 -- ✅ 前端可不改代码直接升级 -- ⚠️ 如果前端此前解析过错误消息中的 `productId=...`,需移除相关逻辑 diff --git a/changelogs/2026-04/2026-04-18-product-price-calendar-frontend-bug.md b/changelogs/2026-04/2026-04-18-product-price-calendar-frontend-bug.md deleted file mode 100644 index 15c2d20..0000000 --- a/changelogs/2026-04/2026-04-18-product-price-calendar-frontend-bug.md +++ /dev/null @@ -1,223 +0,0 @@ -# 前端 Bug 通知 — Step4 定价管理 新增价格区间不回显（前端只刷当前月） - -- **日期**: 2026-04-18 -- **类型**: 前端 Bug 修复指南（**不涉及后端代码改动，后端无需重启**） -- **涉及端**: 管理后台 hl-ui（产品编辑页 Step4 定价管理） -- **后端服务**: hl-product-service-v2（**后端已核实数据完全正确，无需改动**） -- **优先级**: P2 -- **关联任务**: backend 仓库 `docs/tasks/20260418_修复_产品定价新增价格区间不回显.md` - ---- - -## 一、问题描述 - -在产品编辑页 Step4「定价管理」tab 中： - -- **预期**：在已有 2026-04 平日价区间的情况下，新增一段不同月份（如 2026-05-07 → 2026-05-17）的价格区间，点"确认添加"后列表应立即回显新增区间 -- **实际**：点"确认添加"后**列表只显示原来 4 月那一条**，新增的 5 月区间**没有出现**，看起来"加不上" - -**复现路径**： -- 环境：测试服 `192.168.100.160` -- 产品 ID：`2045345825172639746`（游牧的森林-短途版，CORE 草稿） -- 页面：产品编辑 → Step4 定价管理 → 选"轻奢"档位 tab -- 前置：已有 2026-04-01 → 2026-04-30 平日价（成人 ¥4105 / 儿童 ¥1865） -- 操作：点 +添加区间 → 填 2026-05-07 → 2026-05-17 / 平日 / 轻奢 / 成人 ¥4725 / 儿童 ¥1725 → 确认添加 -- 结果：列表里看不到新加的 5 月区间 - ---- - -## 二、根因分析（后端已实证核实） - -### 1. 后端 POST 已成功写入 DB（实证 1：服务日志） - -测试环境 `hl-product-service-v2` 日志（`/opt/hulalv/logs/services/hl-product-service-v2/hl-product-service-v2-8083.log`）： - -``` -12:40:40 价格日历批量设置成功, productId=2045345825172639746, 日期范围=2026-05-02-2026-05-22, 记录数=21 -12:41:17 价格日历批量设置成功, productId=2045345825172639746, 日期范围=2026-05-09-2026-05-10, 记录数=2 -``` - -后端**全程零 ERROR / 零 WARN**，所有 batch 写入返回 200 成功。 - -### 2. DB 真实有 5 月数据（实证 2：数据库） - -`hl_product_service.product_price_calendar` 表实际记录： - -| range_id | 月份 | tier_seq | 日期范围 | 成人/儿童 | 条数 | deleted_at | -|----------|------|----------|----------|-----------|------|------------| -| 2045361705738719233 | 2026-04 | 1 | 4/1-4/30 | 4105/1865 | 30 | NULL | -| 2045361802451058689 | 2026-04 | 2 | 4/1-4/30 | 7777/1000 | 30 | NULL | -| 2045361847678160898 | 2026-05 | 2 | 5/2-5/22 | 4865/1865 | 21 | NULL | -| 2045362006457733121 | 2026-05 | 1 | 5/9-5/10 | 4695/1695 | 2 | NULL | - -5 月数据真实存在、未被软删。 - -### 3. 前端只 GET 当前月份（实证 3：网关访问日志） - -`hl-gateway-8080.log` 关键序列（保存 5 月区间前后）： - -``` -12:40:40.125 POST .../price-calendar/batch ← 写入 5/2-5/22 ✓ -12:40:40.379 GET .../price-calendar?month=2026-04 ← 刷新只查 4 月 ❌ -12:41:17.981 POST .../price-calendar/batch ← 写入 5/9-5/10 ✓ -12:41:18.239 GET .../price-calendar?month=2026-04 ← 刷新只查 4 月 ❌ -``` - -**整个会话前端从未发起 `month=2026-05` 的 GET 请求** → 后端有数据但前端从不拉取。 - -### 真因 - -前端 Step4 定价管理「保存价格区间」的成功回调里，只刷新当前选中月份的数据。当用户新增的区间落在**当前选中月之外的月份**（包括跨月、纯异月）时： -- POST batch 已正确入库 -- 但 GET 只请求当前月，新月份的数据不在响应里 -- 列表自然回显不出来 - -非后端 bug，**纯前端刷新策略问题**。 - ---- - -## 三、涉及接口契约（不变，仅供前端 AI 自包含参考） - -### 1. 批量保存价格区间 - -| 项 | 值 | -|----|----| -| 方法 | POST | -| 路径 | `/admin/product/item/{productId}/price-calendar/batch` | -| 鉴权 | 管理后台 token | - -**Request Body**（关键字段）： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `startDate` | string `yyyy-MM-dd` | 是 | 区间起始日 | -| `endDate` | string `yyyy-MM-dd` | 是 | 区间结束日 | -| `tierSeq` | int | 是 | 档位序号（1=经济 / 2=舒适 / 3=轻奢 / 4=高端 / 5=豪华） | -| `priceType` | string | 是 | `WEEKDAY` 平日 / `WEEKEND` 周末 / `HOLIDAY` 节假日 | -| `adultSellPrice` | decimal(12,2) | 是 | 成人售价 | -| `childSellPrice` | decimal(12,2) | 是 | 儿童售价 | -| `subChildDiscount` | decimal(12,2) | 否 | 小童优惠额 | -| `infantPrice` | decimal(12,2) | 否 | 幼童价 | -| `dailyStock` | int | 否 | 每日库存 | - -**Response**： -```json -{ - "code": 200, - "data": { - "rangeId": 2045361847678160898, - "recordCount": 21 - } -} -``` - -> 关键：响应里返回的 `rangeId` 可用于精确识别本次落库的区间，便于前端定位需要刷新哪些月。 - -### 2. 按月查询价格日历 - -| 项 | 值 | -|----|----| -| 方法 | GET | -| 路径 | `/admin/product/item/{productId}/price-calendar?month=yyyy-MM` | - -按月返回该月**全部档位**所有日期的明细（不按 tierSeq 过滤）。 - -**Response**： -```json -{ - "code": 200, - "data": [ - { - "date": "2026-05-07", - "tierSeq": 3, - "rangeId": 2045361847678160898, - "priceType": "WEEKDAY", - "adultSellPrice": 4725.00, - "childSellPrice": 1725.00, - "subChildDiscount": null, - "infantPrice": null, - "dailyStock": null - } - ] -} -``` - ---- - -## 四、前端修复建议（任选其一） - -### 方案 A（最小改动，推荐） - -保存成功后，根据**本次保存的区间起止日期**，计算覆盖的月份集合（同月 1 个，跨月 N 个），逐月 GET 并 merge 到本地状态。 - -伪代码： -```js -async function onBatchSaved(payload) { - // payload 是刚提交的请求体：{ startDate, endDate, tierSeq, ... } - const startMonth = payload.startDate.slice(0, 7); // "2026-05" - const endMonth = payload.endDate.slice(0, 7); // "2026-05" - const months = enumerateMonths(startMonth, endMonth); // ["2026-05"] 或跨月 ["2026-05","2026-06"] - - // 同时 fetch 当前选中月（保留原有视图刷新） - if (!months.includes(currentMonth.value)) months.push(currentMonth.value); - - const results = await Promise.all( - months.map(m => api.getPriceCalendar(productId, m)) - ); - // 把所有月份的明细合并到本地状态，按区间聚合显示 - mergeIntoLocalState(results.flatMap(r => r.data)); -} -``` - -并且，**保存成功后建议自动把月份选择器切换到新区间的起始月**（`startDate.slice(0,7)`），这样用户能立即看到刚加的区间，不用手动切月。 - -### 方案 B（粗暴但稳） - -保存成功后，无脑刷新「当前月 ± 6 个月」共 13 个月（或业务可见范围全部月份），用 `Promise.all` 批量 GET 后聚合。请求多但实现简单，适合日历视图用户经常切月的场景。 - -### 方案 C（最稳妥） - -保存成功后： -1. 清空本地所有缓存 -2. 把月份选择器切到 `payload.startDate.slice(0, 7)` -3. 触发该月份的 GET 拉取 - -用户视觉上"跳到新区间所在月"，能立即看到新数据。请求最少（只 1 次），但前端要做一次月份切换动画。 - -### 三方案对比 - -| 方案 | 请求数 | UX | 实现复杂度 | 推荐度 | -|------|--------|----|------------|--------| -| A | 1~N（按跨月数） | 留在原月 + 数据合并 | 低 | ★★★★★ | -| B | ~13 | 留在原月 + 全量刷新 | 极低 | ★★★ | -| C | 1 | 跳到新月 | 低 | ★★★★ | - ---- - -## 五、回归测试点（前端修完后自测） - -- [ ] 当前选中 4 月，新增 5 月区间，确认添加后能立即在列表/日历中看到新区间 -- [ ] 当前选中 5 月，新增 4 月区间，同上能立即看到 -- [ ] 跨月新增（如 5/28 → 6/3），确认添加后两个月的数据都能看到 -- [ ] 同月新增（4 月内 4/15 → 4/20），确认添加后能立即看到 -- [ ] 多次连续新增不同月的区间，每次都能立即回显 -- [ ] 新增成功后，月份选择器切换到任意月，数据都正确 - ---- - -## 六、后端是否有配合改动 - -**无**。 - -后端代码、接口路径、字段定义、返回结构、写入读取行为**完全不变**。**后端不会发版本，测试环境无需重启服务**。 - ---- - -## 七、可选优化（前端讨论后再决定，本次不做） - -如果前端觉得"逐月 GET 合并"太繁琐，后端可以增加一个新接口（不影响现有接口）： - -- `GET /admin/product/item/{productId}/price-calendar/ranges` —— 按 `range_id` 聚合返回区间列表（含 startDate/endDate/tierSeq/priceType/adultSellPrice/childSellPrice），不分月，一次拉完所有区间 -- 或者给现有 `GET .../price-calendar` 增加 `startDate` / `endDate` 可选参数支持任意日期范围查询 - -如有需求请前端在本 changelog 评论或单独提工单，后端再评估排期。**本次不强制做，前端先按方案 A/B/C 之一修即可解决问题**。 diff --git a/changelogs/2026-04/2026-04-18-resource-pagination-and-search-fixes.md b/changelogs/2026-04/2026-04-18-resource-pagination-and-search-fixes.md deleted file mode 100644 index 827c72f..0000000 --- a/changelogs/2026-04/2026-04-18-resource-pagination-and-search-fixes.md +++ /dev/null @@ -1,211 +0,0 @@ -# 资源模块分页与搜索修复（素材 limit 参数 + 活动/餐厅/服务按城市搜索） - -- **日期**: 2026-04-18 -- **服务**: hl-resource-service（端口 8082） -- **类型**: BUG 修复（非破坏性，向后兼容） -- **优先级**: P2 -- **前端影响**: **无需改代码**，但会有"分页不再多算空页 / 搜索匹配范围扩大"的观感变化 -- **关联 PR**: #798、#806 -- **关联 Issue**: #797、#804 - ---- - -## 总览 - -本次合并两个修复到 dev，都在 `hl-resource-service`： - -| PR | 影响接口 | 问题 | 修复 | -|---|---|---|---| -| #798 | `GET /admin/material/list` | 前端传 `?limit=12` 后端不识别，始终按默认 `pageSize=20` 返回 | `pageSize` 字段追加 `@JsonAlias("limit")`，并新增 `setLimit` setter | -| #806 | `GET /admin/activity/items`、`GET /admin/restaurant/items`、`GET /admin/service/items` | `keyword` 只匹配名称/描述/亮点，搜"呼伦贝尔"等城市名匹配不到 | `keyword` like 条件扩展到省/市/区（或地址）字段 | - -> ⚠️ `GET /admin/scenic/spots`（景区列表）**未改动**，保持原行为（按用户要求）。 - ---- - -## 修复一：素材列表支持 `limit` 参数（PR #798） - -### 影响接口 - -``` -GET /admin/material/list -``` - -### 现象对比 - -**修复前**： - -``` -请求: GET /admin/material/list?page=1&limit=12&categoryCode=product&fileType=image -响应: { "data": { "records": [...共 20 条...], "total": 56, "page": 1, "pageSize": 20 } } -``` - -- 前端本来就在传 `?limit=12`，但后端字段名叫 `pageSize`，不识别 `limit`，直接走默认值 20 -- 前端计算 `总页数 = ceil(total / limit) = ceil(56 / 12) = 5`，但实际后端按 pageSize=20 返回 → 真实页数只有 3 -- 用户点到第 4、5 页 → `records` 为空数组，体验是"后面几页是空的" - -**修复后**： - -``` -请求: GET /admin/material/list?page=1&limit=12&categoryCode=product&fileType=image -响应: { "data": { "records": [...共 12 条...], "total": 56, "page": 1, "pageSize": 12 } } -``` - -- `limit` 被后端识别，`pageSize` 回传为请求的 `limit` 值 -- 前端分页控件算出的页数与后端实际页数一致，不再出现空页 - -**行为保持不变**： - -- 前端如果传 `?pageSize=15` → 后端仍按 15 处理（原行为） -- 同时传 `?pageSize=20&limit=12` → 以 `limit=12` 为准（`@JsonAlias` 会覆盖同名字段，不建议前端同时传） -- 不传任何分页参数 → 默认 `pageSize=20` - -### 前端适配 - -- **无需改代码**。前端本来就传 `limit`，之前是无效参数，现在生效 -- **观感变化**：分页器的页数显示可能"变少了"，那是因为之前的页数是虚高的；真实数据没变 -- 若前端之前为了兼容"后面是空页"写过判断（如跳到最后一页发现是空就回退），可以保留，不会有副作用 - -### 接口契约 - -**请求**： - -``` -GET /admin/material/list?page=1&limit=12&categoryCode=product&fileType=image -Authorization: Bearer {token} -tenant-id: {租户ID} -``` - -常用查询参数： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| page | Integer | 否 | 页码，默认 1 | -| pageSize / limit | Integer | 否 | 每页条数，默认 20；**两个名字后端都认**，推荐 `pageSize` | -| categoryCode | String | 否 | 素材分类码（例：`product`） | -| fileType | String | 否 | 文件类型（例：`image`） | - -**响应**： - -```json -{ - "code": 200, - "message": "成功", - "data": { - "records": [ /* 素材对象列表 */ ], - "total": 56, - "page": 1, - "pageSize": 12 - }, - "success": true -} -``` - ---- - -## 修复二：活动/餐厅/服务列表 `keyword` 支持省市区模糊搜索（PR #806） - -### 影响接口 - -| 接口 | 模块 | 说明 | -|------|------|------| -| `GET /admin/activity/items` | 游玩项目 | 活动列表（按 keyword / cityKeyword 检索） | -| `GET /admin/restaurant/items` | 餐厅 | 餐厅列表 | -| `GET /admin/service/items` | 服务 | 服务项列表 | - -> `GET /admin/scenic/spots`（景区）**未改**，保持原行为。 - -### 现象对比 - -**修复前**（以 activity 为例）： - -``` -请求: GET /admin/activity/items?keyword=呼伦贝尔&page=1&pageSize=20 -响应: { "data": { "records": [], "total": 0, ... } } ← 0 条 -``` - -- `keyword` 只 like 匹配 `name` / `description` / `highlights` 三个字段 -- 如果一条活动名字叫"草原骑马"、描述里没写"呼伦贝尔"，就算它 city 是"呼伦贝尔"，也搜不到 - -**修复后**： - -``` -请求: GET /admin/activity/items?keyword=呼伦贝尔&page=1&pageSize=20 -响应: { "data": { "records": [...呼伦贝尔下面的活动...], "total": 18, ... } } -``` - -- `keyword` like 匹配范围扩大到 **名称 + 描述 + 亮点 + 省 + 市 + 区** -- 搜"海拉尔"、"内蒙古"、"额尔古纳"等都会命中对应地名的记录 - -### 各接口的 keyword 匹配字段 - -| 接口 | 修复前 keyword 匹配字段 | 修复后 keyword 匹配字段 | -|------|-------------------------|-------------------------| -| `/admin/activity/items` | name, description, highlights | name, description, highlights, **province, city, district** | -| `/admin/restaurant/items` | name, description, highlights | name, description, highlights, **province, city, district** | -| `/admin/service/items` | name, description, highlights | name, description, highlights, **province, city, address** *(service_item 表无 district 字段,用 address 代替)* | - -### 与 `cityKeyword` 的关系 - -- `cityKeyword` 是三个接口已有的**独立参数**，仍然只按 city 字段模糊匹配 -- 前端若同时传 `keyword` 和 `cityKeyword`，两者是 **AND** 组合（都要满足），行为不变 -- 建议前端保持现有用法不动；单独搜框用 `keyword` 即可覆盖绝大多数场景 - -### 前端适配 - -- **无需改代码**。`keyword` 参数名、类型、返回结构完全不变 -- **观感变化**：同一个 keyword 在活动/餐厅/服务列表里可能比以前多返回一些结果（因为多匹配了省/市/区字段），这是预期内的 -- 若前端文案里显式写了"按名称/描述搜索"，建议改成更宽松的"按名称、描述、地点搜索"（可选，非强制） - -### 接口契约（以 activity 为例，另两个类似） - -**请求**： - -``` -GET /admin/activity/items?keyword=呼伦贝尔&page=1&pageSize=20 -Authorization: Bearer {token} -tenant-id: {租户ID} -``` - -常用查询参数（均为可选）： - -| 参数 | 类型 | 说明 | -|------|------|------| -| keyword | String | 关键词（**本次扩展**：名称/描述/亮点/省/市/区） | -| cityKeyword | String | 仅按城市匹配（未变） | -| page | Integer | 页码，默认 1 | -| pageSize | Integer | 每页条数，默认 20 | - -**响应结构**：保持原样，不赘述。 - ---- - -## 向后兼容性 - -- ✅ 接口路径、请求参数名、响应字段结构、HTTP code、业务 code **完全不变** -- ✅ 前端已有代码无需任何修改 -- ✅ 景区接口未动 -- ⚠️ 两个修复会带来"分页页数更准"和"搜索结果变多"的观感变化，属于预期行为 - ---- - -## 重启服务 - -> **仅需重启** `hl-resource-service`（端口 8082） - -- **测试环境**：通过 Deploy Panel 重启（参考 `memory/deploy-panel.md`） -- **正式环境**：本次**先不上正式** -- **DDL 变更**：无 -- **配置变更**：无 - ---- - -## 关联信息 - -| 项 | 值 | -|---|---| -| PR #798 | fix(resource): 素材列表分页兼容前端 limit 参数 → dev | -| PR #806 | fix(resource): 活动/餐厅/服务列表 keyword 支持省市区模糊搜索 → dev | -| Issue #797 | 素材列表 limit 参数不生效导致分页虚高 | -| Issue #804 | 活动/餐厅/服务按城市名搜索匹配不到 | -| 服务 | hl-resource-service（8082） | diff --git a/changelogs/2026-04/2026-04-18_banner-link-target-type-tag.md b/changelogs/2026-04/2026-04-18_banner-link-target-type-tag.md deleted file mode 100644 index 1c8d9ec..0000000 --- a/changelogs/2026-04/2026-04-18_banner-link-target-type-tag.md +++ /dev/null @@ -1,90 +0,0 @@ -# 轮播图"链接目标"产品类型 Tag 前端修复指引（后端零改动） - -- **日期**: 2026-04-18 -- **PR**: 无（后端无代码改动，纯前端 BUG） -- **状态**: 后端字段早已就绪，仅需前端消费 - ---- - -## 背景 - -管理端"轮播图管理"编辑/列表页，链接类型 = "产品详情"时： -- 当前：`[产品] 小蒙马·呼伦贝尔亲子研学5日营`（Tag 硬编码"产品"二字，不区分核心/小蒙马） -- 期望：`[小蒙马] 小蒙马·呼伦贝尔亲子研学5日营` 或 `[核心] xxx` - -## 后端状态：零改动，契约已齐备 - -1. **轮播图详情接口** `GET /admin/banner/{id}`（`hl-user-service`）： - - 响应 VO `BannerVO` 已包含 `linkTargetType`（CORE / GROUP / null） - - `BannerService.enrichLinkTargetType()` 在 list / get / create / update 四条路径批量回填（走 `ProductTypeFeignClient.batchProductType` 批量查产品 productType，Feign 降级留空不阻塞） - - 已验证：返回 JSON 里 `linkTargetType` 为英文常量 `CORE` / `GROUP` - -2. **产品 picker 列表接口** `GET /product/item/list`（`hl-product-service-v2` 的 `AdminProductController`）： - - 响应 VO `ProductListRespVO` 已包含 `productType`（CORE / GROUP / CUSTOM） - - 前端 picker 选中产品时可直接从 `row.productType` 读值 - -## 前端需要做的修改 - -### 1. `hl-ui/src/views/mp-config/home/banner/EditModal.vue` - -- **`formData` 加字段**（约第 337-353 行） - ```js - linkTargetType: '' // CORE / GROUP / null - ``` - -- **`fillFormData()` 回显时取字段**（约第 435-453 行） - ```js - linkTargetType: data.linkTargetType || '' - ``` - -- **`handleLinkTypeChange` / `clearLinkTarget` 清空时同步清 `linkTargetType`** - -- **`linkResourceTag` 计算属性改为动态**（原第 333-335 行硬编码 Map）： - - `linkType === 'PRODUCT'` → 读 `formData.linkTargetType`，用字典 `product_type` 取 label（CORE→"核心"、GROUP→"小蒙马"） - - `linkType === 'PRODUCT_LINE'` → 同理走字典（若有产品线类型字典） - - 其他类型（ARTICLE/URL/MINI_PAGE/NONE）保留原 `LINK_RESOURCE_MAP` - -- **`handlePickLinkTarget` 选中产品后**：同步把 `row.productType` 写入 `formData.linkTargetType` - -### 2. `hl-ui/src/views/mp-config/home/banner/index.vue` - -- 表格"链接类型"列（约第 84-92 行 `linkTypeMap` + 第 147-152 行渲染）： - - `PRODUCT` 行改读 `row.linkTargetType` 走字典 `product_type` 渲染；字段缺失时兜底显示"产品" - - 其他类型维持不变 - -### 3. 字典使用建议 - -用 `dictStore.getDictOptions('product_type')` 拿中文 label，避免硬编码"核心/小蒙马"字面量。字典已配置： -``` -product_type: - CORE → 核心 - GROUP → 小蒙马 -``` - -## 回归验证清单 - -| 场景 | 期望 | -|------|------| -| 编辑 linkType=PRODUCT + 目标产品 productType=CORE | Tag 显示"核心" | -| 编辑 linkType=PRODUCT + 目标产品 productType=GROUP | Tag 显示"小蒙马" | -| 新建 linkType=PRODUCT + picker 选 CORE 产品 | Tag 实时变"核心"，保存后回显仍"核心" | -| 列表页 linkType=PRODUCT + productType=GROUP 数据 | 列显示"小蒙马" | -| `linkTargetType` 为 null（历史脏数据） | Tag 兜底显示"产品"，不崩 | - -## 重启范围 - -无。后端零改动，**不需要重启任何服务**。 - ---- - -## 📌 澄清补注（2026-04-18 晚追加） - -管理者此前曾在对话里提到"前端反馈不填报错"并准备派人查后端校验 —— **这是看错任务导致的误报，与本轮播图 Tag 任务无关**。 - -本任务范围严格限定： -- 后端零改动 -- 前端仅修 `EditModal.vue` / `index.vue` 的 Tag 渲染 + `formData.linkTargetType` 消费链路 -- 不涉及保存接口必填校验调整 - -如前端 AI 此前就"不填报错"做过改动，请忽略该上下文，以本文件为准。 - diff --git a/changelogs/2026-04/2026-04-18_e2e-frontend-bugs-report.md b/changelogs/2026-04/2026-04-18_e2e-frontend-bugs-report.md deleted file mode 100644 index 90b85b1..0000000 --- a/changelogs/2026-04/2026-04-18_e2e-frontend-bugs-report.md +++ /dev/null @@ -1,127 +0,0 @@ -# 【前端 BUG 反馈】产品线 + 版本创建流程 E2E 测试 - -- **日期**: 2026-04-18 -- **类型**: BUG 反馈（前端） -- **来源**: 定制师角色 E2E 自动化测试 `D:/work2/HL/test/e2e_run.py` + 后续 5 步版本表单探索 -- **测试环境**: https://192.168.100.160:9527 -- **后端无改动** - ---- - -## 背景 - -Claude 以定制师角色在测试后台完整走了：登录 → 切角色 → 新建两条产品线（核心/私人定制）→ 在核心产品线下完整提交审核 1 个版本 → 在私人定制线下创建版本但被 BUG-3 阻塞停留草稿。 - -后端接口全部正常，核心版本最终提交成功（产品编号 `C260418003`，状态"待审核"）。以下 3 个 BUG 均为前端 UI/交互问题，请前端同事评估修复。 - ---- - -## 🔴 BUG-3 [P0]：Step 2 行程编排 — 切换天数重置已填字段 - -### 现象 - -在 DAY N 填完 集合地/解散地/酒店/活动/封面图/照片集 后，点左侧 DAY N+1 切走，再切回 DAY N，部分字段被**清空**： - -- **核心产品（CORE）**：解散地、封面图 丢失 -- **小蒙马（GROUP）**：解散地、封面图、活动、酒店 全丢 - -### 重现步骤 - -1. 进入"新增版本" → 走到 Step 2 行程编排 -2. DAY 1 填完 7 个字段（标题 / 集合地 / 解散地 / 描述 / 酒店 / 活动 / 照片集） -3. 点左侧 "DAY 2" 标签 -4. DAY 2 也填完 -5. 点回 "DAY 1" -6. 观察：DAY 1 的解散地变成"搜索解散地"占位符，封面图变成"请选择封面图" - -### 影响 - -用户常见操作模式"逐天填 + 最后回头核查"完全不可用。必须严格按"倒序填 DAY 3 → DAY 2 → DAY 1 且不回切"这种反直觉顺序，否则无法通过 Step 2 校验。 - -### 可能原因（猜测） - -- Vue 组件 `v-if` 而非 `v-show` 导致切走后子组件销毁 -- DAY 切换时没 emit 保存而是直接替换 model -- Selection 组件（解散地、封面图选择器）的 v-model 可能绑在了 ref 而非持久化 store - -### 期望 - -切换 DAY 保留所有已填字段，不需要手动保存。 - -### 严重度 - -**P0**——直接阻塞定制师创建行程的常规操作。 - -### 证据截图（测试机） - -`D:/work2/HL/test/shots/custom-day1-refilled.png` — 补填 DAY 1 后仍显示"请至少添加1项活动/1家酒店" - ---- - -## 🟡 BUG-4 [P1]：Step 4 价格区间 — 金额输入框未清空默认值导致拼接 - -### 现象 - -点击"成人价" n-input-number 后 type `"1280"`，最终保存显示 **¥2,401,280**（预期 ¥1,280）。儿童价 type `"880"` 保存显示 ¥240,880。 - -### 重现步骤 - -1. Step 4 定价管理 → 添加区间 → 选日期范围 → 点"确认" -2. 点击"成人价"输入框 -3. 直接键盘输入 "1280"（不做任何清空） -4. 点"确认添加" -5. 观察列表显示 "¥2,401,280" - -### 可能原因 - -- `n-input-number` 打开时 input 里已有默认值（例如来自 `product_line.default_adult_price` 或产品类型默认值 "240"），点击不会自动全选 -- 用户的 type 被当作在光标位置插入 - -### 期望 - -- 点击输入框时自动全选当前值（focus → select all） -- 或：初始默认为空，用户主动输入 - -### 严重度 - -**P1**——非程序崩溃，但用户若不注意会严重错填价格造成业务风险（"240" + 用户打 "1280" → 超过 200 万的团费）。 - -### 证据截图 - -`D:/work2/HL/test/shots/core-step4-section-added.png` - ---- - -## 🟢 BUG-1 [P3]：产品线卡片封面图缺失 - -### 现象 - -新建产品线（主题）的表单只有 名称 / 主题类型 / 描述 三个字段，没有封面图上传入口；列表卡片也没有任何封面图区域，仅文字展示。 - -### 期望 - -至少给默认占位图；或在新增/编辑表单增加封面图上传字段。 - -### 严重度 - -P3（不影响功能，UI 信息展示不完整） - -### 证据截图 - -`D:/work2/HL/test/shots/14-theme-list-final.png` - ---- - -## 可选：自动化测试脚本 - -存放位置：`D:/work2/HL/test/`。前端同事若需要快速复现 BUG-3/BUG-4，可参考 `fill_day.py`（按天填 7 字段）和 `fill_step4_v2.py`（价格区间）。脚本基于 CDP 接管 Chrome 9222 调试端口。 - ---- - -## 后端说明 - -- 所有后端接口（`/admin/product/line/*`, `/admin/product/edit`, 等）在 E2E 过程中工作正常 -- 核心产品版本最终通过所有后端校验成功提交审核 -- BUG-3/BUG-4/BUG-1 均为**前端展示/交互层**问题，后端无需改动 - -以上问题请前端团队酌情排期，优先级顺序：BUG-3 > BUG-4 > BUG-1。 diff --git a/changelogs/2026-04/2026-04-18_home-menu-banner-productline.md b/changelogs/2026-04/2026-04-18_home-menu-banner-productline.md deleted file mode 100644 index f525eba..0000000 --- a/changelogs/2026-04/2026-04-18_home-menu-banner-productline.md +++ /dev/null @@ -1,83 +0,0 @@ -# 首页第二屏菜单 + 轮播图绑定产品线 - -- **日期**: 2026-04-18 -- **PR**: [#815](https://git.1814.love:8443/wx/HL/pulls/815) (Closes #814) -- **状态**: 已合并 + 测试环境 DB/服务全部就绪 - ---- - -## 1. 管理端新增菜单（前端需对接） - -### sys_menu INSERT - -| menu_id | menu_name | parent_id | path | component | type | permission_code | -|---------|-----------|-----------|------|-----------|------|-----------------| -| 1108 | 首页第二屏 | 991 (首页配置) | `/mp-config/home/screen2` | `/mp-config/home/screen2` | M | `home:screen2:list` | -| 1109 | 编辑首页第二屏 | 1108 | - | - | B | `home:screen2:edit` | - -### 前端需要做的 -- 新建路由 `/mp-config/home/screen2` 对应组件/页面 -- 页面内表单字段对接 PR #811 的 `GET/PUT /admin/home-config/brand-story` 接口 -- 发布按钮调用 `PUT` 时 `publish=true`；草稿按钮 `publish=false` - ---- - -## 2. 轮播图新增 `PRODUCT_LINE` 跳转类型 - -### 字典扩展 - -``` -dict_type: banner_link_type -新增: {dict_label: "产品线", dict_value: "PRODUCT_LINE", sort_order: 6} -``` - -现完整字典值： - -| label | value | 备注 | -|-------|-------|------| -| 产品详情 | PRODUCT | link_id = product_id | -| 文章详情 | ARTICLE | link_id = article_id | -| 外部链接 | URL | link_url 填 https 链接 | -| 小程序页面 | MINI_PAGE | link_url 填 miniprogram 路径 | -| 无跳转 | NONE | - | -| **产品线** | **PRODUCT_LINE** | **link_id = product_line_id**（新增） | - -### 后端已支持 - -- `BannerService.VALID_LINK_TYPES` 已加 `PRODUCT_LINE` -- 保存接口 `POST /admin/banner` 和 `PUT /admin/banner/{id}` 接受 `linkType: "PRODUCT_LINE"` -- 测试环境验证： - ``` - POST /admin/banner {"linkType":"PRODUCT_LINE","linkId":"9999",...} - → 200 成功，linkType=PRODUCT_LINE 原样保存 - ``` - -### 前端需要做的 - -- 轮播图管理页（`/mp-config/home/banner`）表单的"跳转类型"下拉加一个 `产品线` -- 选中"产品线"时：`link_id` 字段变为"产品线选择器"（调用产品线列表接口 `GET /admin/product-line/enabled` 或类似） -- 小程序端渲染轮播图时：`link_type === "PRODUCT_LINE"` → 跳转到产品线详情页/主题列表页 - ---- - -## 3. 测试环境验证 - -- 菜单 INSERT：已执行，测试服务器 `sys_menu.menu_id IN (1108,1109)` + `sys_role_menu` 关联 `role_id=7` 到位 -- 字典 INSERT：已执行，`sys_dict_data.banner_link_type=PRODUCT_LINE` 到位 -- `user-service` 已滚动部署新代码（两实例 8081/8181） -- API 验证：`POST /admin/banner linkType=PRODUCT_LINE` ✅ 保存成功 - ---- - -## 4. 生产部署需要做的 - -- 跑 SQL `sql/menu_home_screen2_and_banner_product_line_20260418.sql`（幂等） -- 重新部署 `hl-user-service`（Java 代码有改动） - ---- - -## 5. 关联 - -- PR #811 主需求：小程序首页第二屏品牌故事+主题卡片 -- PR #813 Gateway 路由补齐 -- PR #815 菜单 + 轮播图 PRODUCT_LINE（本 PR） diff --git a/changelogs/2026-04/2026-04-18_home-screen2-config.md b/changelogs/2026-04/2026-04-18_home-screen2-config.md deleted file mode 100644 index f5d20c4..0000000 --- a/changelogs/2026-04/2026-04-18_home-screen2-config.md +++ /dev/null @@ -1,233 +0,0 @@ -# 小程序首页第二屏配置 - 品牌故事 + 主题卡片入口 - -- **日期**: 2026-04-18 -- **PR**: [#811](https://git.1814.love:8443/wx/HL/pulls/811) (Closes #810) -- **服务**: hl-user-service (8081) + hl-mp-service (8085) -- **状态**: 已合并到 dev，待测试环境部署 - ---- - -## 背景 - -小程序首页分两屏： -- 第一屏：Hero 大图/轮播（现有 `sys_banner`，不变） -- **第二屏（本次新增）**：品牌故事文案 + 大主图 + 2 张主题卡片入口 - -原型节点：`用户端页面(5).pen / M57M7 首页 / Screen2 plwfj` - ---- - -## 1. 管理端接口（Admin） - -### 1.1 查询品牌故事（含草稿） - -``` -GET /admin/home-config/brand-story -Authorization: Bearer <admin token> -``` - -**响应** `Result<AdminBrandStoryRespVO>`： -```json -{ - "code": 200, - "data": { - "id": "2045369223068311553", - "title": "每一条线路，我们都亲自走过。", - "subtitle": null, - "description": "整个呼伦贝尔...", - "coverUrl": "https://cdn.example.com/home/team-photo.jpg", - "coverMaskType": "WHITE_TOP", - "version": 1, - "status": "ACTIVE", - "createTime": "2026-04-18 13:09:59", - "updateTime": "2026-04-18 13:09:59", - "createdBy": "1002", - "updatedBy": "1002", - "createdByName": null, - "updatedByName": null - }, - "success": true -} -``` - -**字段说明**： - -| 字段 | 类型 | 说明 | -|-----|------|-----| -| id | String | 主键（雪花ID，JS 精度防护用 String） | -| title | String | 主标题，支持 \n 换行 | -| subtitle | String? | 副标题（预留，当前可为 null） | -| description | String | 描述文案 | -| coverUrl | String? | 主图 URL（草稿可空；发布时必填） | -| coverMaskType | String | 蒙层类型：`WHITE_TOP`=上白下透 / `NONE`=无 | -| version | Integer | 版本号，publish 每次 +1 | -| status | String | `DRAFT`=草稿 / `ACTIVE`=已发布 / `ARCHIVED`=已归档 | -| createdBy/updatedBy | String | 操作人 adminId（String 防 JS 精度） | - -**语义**： -- 返回当前**最新**一条非删除记录（按 id 降序，包含 DRAFT） -- 管理端打开页面即可编辑当前状态，不管是草稿还是已发布 -- 无数据时返回 `data: null`（首次部署时可能出现） - ---- - -### 1.2 保存或发布品牌故事 - -``` -PUT /admin/home-config/brand-story -Authorization: Bearer <admin token> -Content-Type: application/json -``` - -**请求体** `AdminBrandStorySaveReqVO`： -```json -{ - "id": null, - "title": "每一条线路，我们都亲自走过。", - "subtitle": null, - "description": "整个呼伦贝尔...", - "coverUrl": "https://cdn.example.com/home/team-photo.jpg", - "coverMaskType": "WHITE_TOP", - "publish": true -} -``` - -**字段校验**： - -| 字段 | 校验 | 说明 | -|-----|-----|-----| -| id | 选填 | 有值=更新指定记录，null=新建 | -| title | @NotBlank, @Length(max=100) | 必填 | -| subtitle | @Length(max=200) | 选填 | -| description | @NotBlank, @Length(max=1000) | 必填 | -| coverUrl | @NotBlank, @URL(protocol="https") | 必填（只接受 https 链接） | -| coverMaskType | @NotBlank | 必填，值同上 | -| publish | Boolean | `true`=直接发布（归档旧 ACTIVE，新记录设为 ACTIVE）；`false`=保存草稿 | - -**行为**： -- `publish=false`：`saveDraft` 插入/更新 `status=DRAFT` 记录 -- `publish=true`：`publish` 先 `archiveAllActive()` 把当前 ACTIVE 改 ARCHIVED，再插入 ACTIVE 新记录；`@Lock4j` 防并发；自动 evict Redis 缓存 - -**响应** `Result<Void>`：`{"code":200, "message":"成功", "data":null, "success":true}` - -**幂等保护**：`@Idempotent(timeout=5, keyPrefix="admin-brand-story")`，5 秒内重复请求返回缓存结果。 - -**审计**：`@OperationLog("发布小程序首页第二屏品牌故事")`，操作日志自动写入。 - ---- - -## 2. 小程序端接口（MP） - -### 2.1 获取首页第二屏数据（聚合） - -``` -GET /mp/home-config/screen2 -``` - -**不需要 token**（Gateway 设为 `X-Auth-Level=SKIP`，匿名可访问）。 - -**响应** `Result<MpHomeScreen2VO>`： -```json -{ - "code": 200, - "data": { - "brandStory": { - "title": "每一条线路，我们都亲自走过。", - "subtitle": null, - "description": "整个呼伦贝尔...", - "coverUrl": "https://cdn.example.com/home/team-photo.jpg", - "coverMaskType": "WHITE_TOP" - }, - "topics": [ - { - "id": "XXXX", - "title": "季节之旅", - "subtitle": "夏/秋/冬三季体验", - "coverUrl": "https://cdn.example.com/topics/season.jpg", - "linkType": "PRODUCT_LIST", - "linkTarget": "theme=SEASON" - } - ] - }, - "success": true -} -``` - -**字段说明**： - -| 字段 | 类型 | 说明 | -|-----|------|-----| -| brandStory | Object? | 品牌故事块，无数据时为 null | -| brandStory.title | String | 主标题，支持 \n 换行 | -| brandStory.subtitle | String? | 副标题 | -| brandStory.description | String | 描述 | -| brandStory.coverUrl | String? | 主图 URL | -| brandStory.coverMaskType | String | 蒙层类型 `WHITE_TOP`/`NONE` | -| topics | Array | 主题卡片列表（按 sort_order 升序） | -| topics[].id | String | 主题 ID | -| topics[].title | String | 卡片标题 | -| topics[].subtitle | String? | 卡片副标题 | -| topics[].coverUrl | String | 卡片封面图 | -| topics[].linkType | String | 跳转类型，如 `PRODUCT_LIST` / `TOPIC_DETAIL` | -| topics[].linkTarget | String | 跳转目标（路径/ID/参数） | - -**关键**：响应**不包含** `fromFallback` 字段（内部 Feign 协议字段，VO 层已过滤）。 - ---- - -## 3. 缓存策略 - -| 项 | 值 | -|---|---| -| Key | `home:screen2:mp:{env}`（env=dev/test/prod） | -| TTL | 30 分钟（1800s） | -| 空值 TTL | 60 秒（防穿透） | -| Evict 触发 | brand PUT / topic CUD 任一发生 | - -**前端渲染建议**：小程序可本地缓存 5 分钟减少重复请求；发现数据变化再 pull。 - ---- - -## 4. 错误处理 - -所有错误走项目统一错误码，HTTP **始终 200**，业务码在 `code` 字段： - -| code | 含义 | 常见场景 | -|------|------|---------| -| 200 | 成功 | — | -| 400 | 参数校验失败 | title 缺失 / coverUrl 非 https | -| 401 | 未登录 | admin token 过期 | -| 403 | 无权限 | 非 admin 访问 `/admin/**` | -| 409 | 状态冲突 | 禁止 ACTIVE → DRAFT 回退 | -| 500 | 服务器错误 | DB/Redis 异常 | - ---- - -## 5. 管理端前端需要做的 - -1. **页面**：首页配置 / 第二屏 -2. **表单字段**：title / subtitle / description / coverUrl（走素材库 system 分类上传） / coverMaskType（下拉 WHITE_TOP/NONE） -3. **操作按钮**：`保存草稿` (publish=false) / `立即发布` (publish=true，需二次确认弹窗) -4. **首次打开**：调 GET 接口，有数据则回填表单，无数据则空表单 -5. **发布后提示**：调 GET 验证 status=ACTIVE，提示"发布成功，小程序缓存最多 30 分钟后生效" - ---- - -## 6. 小程序前端需要做的 - -1. **首页渲染**：调 `GET /mp/home-config/screen2` -2. **数据位置**： - - `brandStory.coverUrl` 作为第二屏大图背景（375×497 区） - - `brandStory.title` + `brandStory.description` 浮于大图之上（位置 x=20, y=50 参考原型） - - `topics` 渲染为 2 个横向卡片（位置 x=20, y=520, 335×220 参考原型） -3. **空态**：`brandStory=null` 时第二屏隐藏；`topics=[]` 时卡片区隐藏 -4. **shimmer/skeleton**：请求中显示骨架屏 - ---- - -## 7. 变更影响 - -- **现有 `/admin/banner/*` 接口**：**不变**（第一屏轮播独立） -- **现有 `/mp/banner/active` 接口**：**不变** -- **现有 `/admin/topic/*` 接口**：**不变**（本期复用 sys_topic，不动表结构） -- **TopicService 新增方法**：仅内部调用，不暴露接口 diff --git a/changelogs/2026-04/2026-04-18_home-screen2-remove-card-link.md b/changelogs/2026-04/2026-04-18_home-screen2-remove-card-link.md deleted file mode 100644 index 043146f..0000000 --- a/changelogs/2026-04/2026-04-18_home-screen2-remove-card-link.md +++ /dev/null @@ -1,110 +0,0 @@ -# 小程序首页第二屏 - 主题卡片去掉"链接类型"字段 - -- **日期**: 2026-04-18 -- **PR**: [#829](https://git.1814.love:8443/wx/HL/pulls/829) (Closes #828) -- **类型**: 契约变更（减字段） -- **状态**: 已合并到 dev + 测试环境部署中 - -> 本次改动紧随同日的 [#823 首页第二屏 v2](./2026-04-18_home-screen2-v2.md)。v2 设计的"卡片链接跳转"能力产品决定取消，卡片回归纯展示。 - ---- - -## 受影响接口 - -### 管理端 -- `PUT /admin/home-config/brand-story`（保存品牌故事） -- `GET /admin/home-config/brand-story`（查询品牌故事） - -### 小程序端 -- `GET /mp/home-config/screen2`（首页第二屏聚合） - -## 删除字段（每张卡片 `cards[i]`） - -| 字段 | 类型 | 原含义 | -|---|---|---| -| ~~`linkType`~~ | String | 链接类型（NONE/PRODUCT/PRODUCT_LINE/ARTICLE/URL/MINI_PAGE） | -| ~~`linkTarget`~~ | String | 链接目标（产品/产品线 ID / URL / 小程序页面路径） | -| ~~`linkTargetType`~~ | String | 响应回填的产品类型（CORE/GROUP） | - -## 保留字段（每张卡片 `cards[i]`） - -| 字段 | 类型 | 说明 | -|---|---|---| -| `title` | String | 卡片标题（必填，≤100 字符） | -| `subtitle` | String | 卡片副标题（可选，≤200 字符） | -| `coverUrl` | String | 封面图 URL（必填，https CDN 直链，≤500 字符） | - -## 请求示例（PUT /admin/home-config/brand-story） - -```json -{ - "title": "每一条线路，我们都亲自走过。", - "subtitle": null, - "description": "整个呼伦贝尔...", - "coverUrl": "https://cdn.hulalv.com/home/brand.jpg", - "cards": [ - { - "title": "季节之旅", - "subtitle": "夏·秋·冬三季体验", - "coverUrl": "https://cdn.hulalv.com/cards/1.jpg" - }, - { - "title": "亲子研学", - "subtitle": "边玩边学·深度体验", - "coverUrl": "https://cdn.hulalv.com/cards/2.jpg" - } - ], - "publish": true -} -``` - -## 响应示例（GET /mp/home-config/screen2） - -```json -{ - "code": 200, - "data": { - "brandStory": { - "title": "每一条线路，我们都亲自走过。", - "description": "...", - "coverUrl": "https://cdn.hulalv.com/home/brand.jpg" - }, - "cards": [ - { - "title": "季节之旅", - "subtitle": "夏·秋·冬三季体验", - "coverUrl": "https://cdn.hulalv.com/cards/1.jpg" - } - ] - } -} -``` - -## 前端 Action - -### 管理端（必改） -1. 移除卡片编辑区底部"链接类型 *"下拉框组件 -2. 移除卡片编辑区"链接目标"相关组件（如产品选择器 / URL 输入框 / 小程序页面选择） -3. 请求体中 `cards[i]` 不再传 `linkType` / `linkTarget` - -### 小程序端（必改） -1. 主题卡片点击事件去除（卡片不再支持跳转） -2. 如果之前读了 `cards[i].linkType` / `.linkTarget` / `.linkTargetType` 的逻辑，一并删除 - -## 向后兼容说明 - -- DB 存量数据中的 JSON 字段 `linkType/linkTarget/linkTargetType` 不删，反序列化时被后端 `@JsonIgnoreProperties(ignoreUnknown=true)` 安全忽略 -- 前端如果旧请求仍传了这三个字段，后端也会被 `@JsonIgnoreProperties(ignoreUnknown=true)` 忽略（不会 400） -- 但**不推荐继续传**，清理前端代码更彻底 - -## 校验规则变化 - -| 字段 | 变化 | -|---|---| -| `cards[i].linkType` | 原 `@NotBlank + @Pattern(NONE/PRODUCT/PRODUCT_LINE/ARTICLE/URL/MINI_PAGE)` → **字段删除** | -| `cards[i].linkTarget` | 原 `@Length(max=500)` → **字段删除** | -| `cards` 数组 | 保留 `@Size(max=2)` | - -## 回归验证 - -部署后调 `GET /mp/home-config/screen2`，确认 `data.cards[i]` 只包含 title / subtitle / coverUrl 即可。 diff --git a/changelogs/2026-04/2026-04-18_home-screen2-v2.md b/changelogs/2026-04/2026-04-18_home-screen2-v2.md deleted file mode 100644 index df4bfe4..0000000 --- a/changelogs/2026-04/2026-04-18_home-screen2-v2.md +++ /dev/null @@ -1,180 +0,0 @@ -# 小程序首页第二屏 v2 - 去蒙层 + 内嵌卡片 + 类型校验 - -- **日期**: 2026-04-18 -- **PR**: [#823](https://git.1814.love:8443/wx/HL/pulls/823) (Closes #822) -- **状态**: 已合并 + 测试环境 DDL/服务全就绪 + E2E 通过 - ---- - -## 变更概览 - -1. 删 `coverMaskType` 字段（全链路） -2. 品牌故事内嵌 2 张主题卡片（`cards` 数组，最多 2 张） -3. 修 PR #811 缓存失效 bug -4. 链接目标（产品/产品线）只允许 **CORE/GROUP** 类型，响应加 `linkTargetType` - ---- - -## 1. Admin `PUT /admin/home-config/brand-story` 请求体变更 - -### 删除字段 -- ~~`coverMaskType`~~ - -### 新增字段 -- `cards`: `BrandCard[]`（最多 2 张） - -```json -{ - "title": "每一条线路，我们都亲自走过。", - "subtitle": null, - "description": "整个呼伦贝尔...", - "coverUrl": "https://cdn.1814.love/home/team-photo.jpg", - "publish": true, - "cards": [ - { - "title": "季节之旅", - "subtitle": "夏·秋·冬三季体验", - "coverUrl": "https://cdn.1814.love/cards/season.jpg", - "linkType": "PRODUCT_LINE", - "linkTarget": "2045004175602868226" - }, - { - "title": "亲子研学", - "subtitle": "边玩边学·深度体验", - "coverUrl": "https://cdn.1814.love/cards/study.jpg", - "linkType": "NONE", - "linkTarget": "" - } - ] -} -``` - -**BrandCard 字段**: - -| 字段 | 类型 | 必填 | 说明 | -|-----|------|------|-----| -| title | String | ✓ | 标题（如"季节之旅"） | -| subtitle | String | - | 副标题 | -| coverUrl | String | ✓ | 背景图 URL（必须 https） | -| linkType | String | ✓ | NONE/PRODUCT/PRODUCT_LINE/ARTICLE/URL/MINI_PAGE | -| linkTarget | String | - | 跳转目标（id 或 url） | - -### 业务校验 - -- `cards` 最多 2 张（`@Size(max=2)`） -- **PRODUCT/PRODUCT_LINE 时 linkTarget 对应的产品/产品线类型必须是 `CORE` 或 `GROUP`**，其他类型返回： - -```json -{"code":500, "message":"卡片只能关联核心或小蒙马类型的产品/产品线", "data":null, "success":false} -``` - ---- - -## 2. Admin/MP GET 响应新增 - -### 响应结构 -- Admin `GET /admin/home-config/brand-story` 返回的 `data` 里，`coverMaskType` 字段**已移除**，新增 `cards` -- MP `GET /mp/home-config/screen2` 返回 `data.cards`（原 `data.topics` **移除**） - -```json -{ - "code": 200, - "data": { - "brandStory": { - "title": "每一条线路，我们都亲自走过。", - "subtitle": null, - "description": "...", - "coverUrl": "..." - }, - "cards": [ - { - "title": "季节之旅", - "subtitle": "夏·秋·冬三季体验", - "coverUrl": "...", - "linkType": "PRODUCT_LINE", - "linkTarget": "2045004175602868226", - "linkTargetType": "CORE" - }, - ... - ] - }, - "success": true -} -``` - -**`linkTargetType`** 字段说明： -- `CORE` / `GROUP` / `null` -- 仅 PRODUCT/PRODUCT_LINE 类型时填充，其他返 null -- 批量回填（Feign 调 product-v2 一次性批查），避免 N+1 - ---- - -## 3. 轮播图 `/admin/banner` 变更 - -### 请求（保存） -- linkType=PRODUCT/PRODUCT_LINE 时后端校验 linkId 的 productType 必须 CORE/GROUP，否则返： -``` -{"code":500, "message":"轮播图只能关联核心或小蒙马类型的产品/产品线", ...} -``` - -### 响应 -- BannerVO 新增 `linkTargetType` 字段（CORE/GROUP/null） -- 列表查询也批量回填，前端展示"核心"/"小蒙马"标签不用二次查询 - ---- - -## 4. MP 缓存 - -- Key: `home:screen2:mp:{env}` -- TTL 30 分钟 -- **修复**: PR #811 发布后不失效的 bug 已修（`HomeBrandStoryService.publish()` 现在真正调用 `evictAfterCommit()`） - ---- - -## 5. 前端改造清单 - -### 管理端 (hl-ui) - -1. **品牌故事表单**： - - 删除"蒙层类型"下拉 - - 新增"主题卡片"section，固定 2 张子表单（每张：标题/副标题/背景图/跳转类型/跳转目标） - - 跳转类型选择器选中 PRODUCT/PRODUCT_LINE 时，目标选择器**只显示 `productType=CORE` 或 `GROUP`** 的产品/产品线 - - 展示页可读取 `linkTargetType` 显示标签（"核心"/"小蒙马"） - -2. **轮播图表单 (`/mp-config/home/banner`)**： - - 选择器同上：只显示 CORE/GROUP - - 列表页展示 `linkTargetType` 标签（当 linkType=PRODUCT/PRODUCT_LINE） - -### 小程序端 - -- 首页第二屏渲染： - - `data.brandStory` 是主文案块 - - `data.cards` 是 2 张卡片（如原来的 `data.topics` 结构，但字段略不同） - - 卡片点击按 `linkType` + `linkTarget` 跳转 - ---- - -## 6. 产品/产品线选择器接口 - -前端选择器可用现有接口过滤 `productType`，或调新内部接口（如果暴露到管理端）： - -- 管理端已有 `GET /admin/product-line/enabled`（列表接口）— 按 `productType` filter -- 如需求进一步精确，可联系后端加 `GET /admin/product-line/enabled?productTypes=CORE,GROUP` - ---- - -## 7. 测试环境验证 - -- [x] DDL 已跑（sys_home_brand_story 无 cover_mask_type，有 cards JSON） -- [x] E2E: PUT cards → MP GET 立即可见（缓存 evict 生效） -- [x] E2E: cards linkType=PRODUCT_LINE linkTarget=假 id → 抛业务异常 "卡片只能关联核心或小蒙马类型的产品/产品线" -- [x] Admin GET 响应无 coverMaskType，MP GET 响应 `cards` 替代 `topics` - ---- - -## 8. 关联 PR - -- #811 首页第二屏 v1 -- #813 Gateway 路由补丁 -- #815 菜单 + 轮播图 PRODUCT_LINE 字典 -- **#823 本 PR (v2)** diff --git a/changelogs/2026-04/2026-04-18_mp-config-module-frontend-guide.md b/changelogs/2026-04/2026-04-18_mp-config-module-frontend-guide.md deleted file mode 100644 index bb2599c..0000000 --- a/changelogs/2026-04/2026-04-18_mp-config-module-frontend-guide.md +++ /dev/null @@ -1,410 +0,0 @@ -# 小程序配置模块对接方案 - -> 模块：小程序配置 (Banner 首页配置 / 我的页面配置 / 协议政策 / FAQ) -> 后端服务：hl-user-service（Admin + Internal）+ hl-mp-service（小程序透传） -> 文档日期：2026-04-18 -> 适用：dev 分支当前代码（PR #773 整改后） - ---- - -## 0. 通用约定（必读） - -### 0.1 响应包装 `Result<T>` -```json -{ - "code": 200, // 200=成功；非 200=业务异常（HTTP 始终 200） - "message": "成功", - "data": { ... } -} -``` -**所有接口 HTTP 状态码始终是 200**，业务成败看 `code`。401 = 未登录/Token 过期；403 = 无权限；500 = 业务/系统异常。 - -### 0.2 分页响应 `PageResult<T>` -```json -{ "records": [...], "total": 0, "page": 1, "pageSize": 20 } -``` -分页请求统一字段：`page`（默认 1，≥1）、`pageSize`（默认 20，1~100）。 - -### 0.3 Long ID 序列化 -所有 Long 类型 ID 通过 `@JsonSerialize(ToStringSerializer)` 序列化为 **字符串**（防 JS 大数精度丢失）。前端接收/回传统一按字符串处理。 - -### 0.4 富文本 XSS 过滤 -`content`/`answer` 字段后端会经 `XssUtils` 过滤： -- 禁用：`<script>` `<iframe>` `<img>` `on*` 事件属性 -- 允许：常规标签 + 样式属性 -- Agreement.content 单字段最大 100KB；Faq.answer 最大 10KB - -### 0.5 幂等保护 -管理端 POST/PUT 接口大多带 `@Idempotent(timeout=5)`：5 秒内同参数请求会被拦截。前端**无需自行去重**。 - -### 0.6 小程序端缓存 -所有 `/mp/**` 接口使用 `@MpCache` 缓存 1800s（30 分钟）。**管理端修改后小程序最多 30 分钟生效**，无主动失效机制。 - -### 0.7 端口/路由 -| 类型 | 路径前缀 | 说明 | -|---|---|---| -| 管理端 | `/admin/...` | 走 gateway → hl-user-service，需 ADMIN Token | -| 小程序 | `/mp/...` | 走 gateway → hl-mp-service → Feign → hl-user-service，需 USER Token（部分公开） | -| 内部 | `/internal/...` | 服务间 Feign 专用，**外部访问被网关拦截**（403） | - ---- - -## 1. Banner 首页配置（轮播图） - -### 1.1 业务说明 -首页顶部轮播位（图片或视频），支持时间窗、链接跳转（产品/景点/活动/H5/小程序内页）、排序。 - -### 1.2 数据库表 `sys_banner` -关键字段： -| 列 | 类型 | 说明 | -|---|---|---| -| id | BIGINT | 雪花 ID | -| title / subtitle | VARCHAR | 标题/副标题 | -| media_type | VARCHAR(20) | IMAGE / VIDEO（字典 banner_media_type）| -| image_url / video_url | VARCHAR(500) | 资源 URL | -| material_id | BIGINT | 素材库关联 ID | -| tags | VARCHAR(200) | 标签，逗号分隔 | -| link_type | VARCHAR(20) | 字典 banner_link_type | -| link_id / link_url / link_target_name | VARCHAR | 跳转参数 | -| sort_order | INT | 越小越前 | -| status | INT | 0=下线 1=上线（**注意：本表 status 是整数，与其他表的字符串不同**）| -| start_time / end_time | DATETIME | 上下线时间窗 | -| create_time / update_time / deleted_at | DATETIME | 审计 + 软删 | - -### 1.3 管理端接口（前缀 `/admin/banner`） - -| 方法 | 路径 | 入参 | 返参 | -|---|---|---|---| -| GET | `/admin/banner` | Query: page, pageSize, keyword, status | `Result<PageResult<BannerVO>>` | -| GET | `/admin/banner/{id}` | Path: id | `Result<BannerVO>` | -| POST | `/admin/banner` | Body: BannerRequest | `Result<BannerVO>` | -| PUT | `/admin/banner/{id}` | Path: id + Body: BannerRequest | `Result<BannerVO>` | -| DELETE | `/admin/banner/{id}` | Path: id | `Result<Void>` | - -⚠️ Banner 模块的请求体类名是 `BannerRequest`（历史遗留，未按 `XxxSaveReqVO` 规范）。 - -### 1.4 BannerRequest 字段（创建+更新合一） - -| 字段 | 类型 | 必填 | 校验/字典 | 说明 | -|---|---|---|---|---| -| title | String | ✅ | @NotBlank, ≤100 | 标题 | -| subtitle | String | | ≤200 | 副标题 | -| mediaType | String | | banner_media_type, ≤20 | IMAGE / VIDEO | -| imageUrl | String | ✅ | @NotBlank, ≤500 | 图片或视频封面 URL | -| videoUrl | String | | ≤500 | 视频 URL（mediaType=VIDEO 时有效）| -| materialId | Long | | | 素材库 ID（关联）| -| tags | String | | ≤200 | 逗号分隔标签 | -| linkType | String | | banner_link_type, ≤20 | 跳转类型，见字典 | -| linkId | String | | ≤50 | 跳转目标 ID（PRODUCT/SCENIC 等用）| -| linkUrl | String | | ≤500 | 外部 URL（WEBVIEW/PAGE 用）| -| linkTargetName | String | | ≤100 | 跳转名称（后台展示用）| -| sortOrder | Integer | | | 排序，越小越前 | -| status | Integer | | 0/1 | 0=下线，1=上线 | -| startTime | LocalDateTime | | ISO 8601 | 展示开始时间 | -| endTime | LocalDateTime | | ISO 8601 | 展示结束时间 | - -### 1.5 BannerVO 返回字段 -含上述全部字段 + `id`(String)、`createdAt`、`tags`(返回时为 `List<String>` 已拆好)。 - -### 1.6 小程序端接口（前缀 `/mp/banner`） - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `/mp/banner/active` | 公开接口（无需登录），返回当前生效的轮播列表，缓存 30 分钟 | - -返回：`Result<List<BannerVO>>`（结构同管理端 BannerVO，已按 `sortOrder` 升序，已过滤 `status=1` 且在 `startTime~endTime` 时间窗内的）。 - ---- - -## 2. 我的页面配置 - Contact（联系我们 / 关于我们） - -### 2.1 业务说明 -"我的"页面联系方式区块。三种渠道： -- **ABOUT**：关于我们（用 `content` 富文本） -- **ONLINE_CS**：在线客服（用 `value` 存 URL） -- **PHONE**：电话咨询（用 `value` 存电话号） - -### 2.2 数据库表 `sys_contact` -| 列 | 类型 | 说明 | -|---|---|---| -| id | BIGINT | 雪花 ID | -| channel_type | VARCHAR(32) | 字典 contact_channel_type | -| name | VARCHAR(100) | 标签文案 | -| subtitle | VARCHAR(200) | 副标题（保留字段，前端可不展示）| -| icon_url | VARCHAR(500) | 图标 URL（来自素材库 SYSTEM 分类）| -| value | VARCHAR(500) | 渠道值（URL/电话）| -| content | TEXT | 富文本（仅 ABOUT 用）| -| sort_order | INT | 排序 | -| status | VARCHAR(32) | ACTIVE / INACTIVE | -| create_time/update_time/created_by/updated_by/deleted_at | | 审计 + 软删 | - -### 2.3 管理端接口（前缀 `/admin/contact`） - -| 方法 | 路径 | 入参 | 返参 | -|---|---|---|---| -| GET | `/admin/contact` | Query: ContactPageReqVO | `Result<PageResult<ContactRespVO>>` | -| GET | `/admin/contact/{id}` | Path: id | `Result<ContactRespVO>` | -| POST | `/admin/contact` | Body: ContactSaveReqVO | `Result<Long>`（返回新 ID）| -| PUT | `/admin/contact/{id}` | Path: id + Body: ContactSaveReqVO | `Result<Void>` | -| DELETE | `/admin/contact/{id}` | Path: id | `Result<Void>` | -| GET | `/admin/contact/channel-types/enabled` | — | `Result<List<{value,label}>>` 渠道下拉框 | - -### 2.4 ContactPageReqVO 查询字段 -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| page / pageSize | Integer | | 见 0.2 | -| keyword | String | | 模糊匹配 name/value | -| status | String | | ACTIVE/INACTIVE 不传=全部 | -| channelType | String | | ABOUT/ONLINE_CS/PHONE 不传=全部 | - -### 2.5 ContactSaveReqVO 字段（创建+更新合一） -| 字段 | 类型 | 必填 | 校验/字典 | 说明 | -|---|---|---|---|---| -| id | Long | | | 不传=创建，传=更新 | -| channelType | String | ✅ | @NotBlank, ≤32, contact_channel_type | ABOUT/ONLINE_CS/PHONE | -| name | String | ✅ | @NotBlank, ≤100 | 标签文案 | -| subtitle | String | | ≤200 | 副标题 | -| iconUrl | String | | ≤500 | 图标 URL | -| value | String | | ≤500 | 渠道值（ABOUT 可空）| -| content | String | | ≤50000 | 富文本，仅 ABOUT 用 | -| sortOrder | Integer | | | 排序，默认 0 | - -### 2.6 ContactRespVO 返回字段 -全字段 + `status`（字典）、`createTime`、`updateTime`。 - -### 2.7 小程序端接口（前缀 `/mp/common`） - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `/mp/common/contact` | 返回全部 ACTIVE 联系方式列表，按 sortOrder 升序，缓存 30 分钟 | - -返回：`Result<List<MpContactRespVO>>`，字段： -| 字段 | 类型 | 说明 | -|---|---|---| -| id | String | | -| channelType | String | ABOUT/ONLINE_CS/PHONE | -| name | String | | -| iconUrl | String | | -| value | String | | -| content | String | 富文本（ABOUT 才有）| -| sortOrder | Integer | | - -> **小程序端不返回** subtitle/status/创建时间，瘦身处理。 - ---- - -## 3. 我的页面配置 - FAQ（常见问题） - -### 3.1 业务说明 -两级结构：分类 → 条目。小程序"帮助中心"按分类聚合展示。 - -### 3.2 数据库表 -- `sys_faq_category`：分类（id / name / sort_order / status / 审计） -- `sys_faq_item`：条目（id / category_id / question / answer / sort_order / status / 审计） - -### 3.3 管理端接口 - 分类（前缀 `/admin/faq/categories`） - -| 方法 | 路径 | 入参 | 返参 | -|---|---|---|---| -| GET | `/admin/faq/categories` | — | `Result<List<FaqCategoryRespVO>>` 含全部（含停用），带 itemCount | -| GET | `/admin/faq/categories/enabled` | — | `Result<List<{value,label}>>` 仅启用，下拉框用 | -| GET | `/admin/faq/categories/{id}` | Path: id | `Result<FaqCategoryRespVO>` | -| POST | `/admin/faq/categories` | Body: FaqCategorySaveReqVO | `Result<FaqCategoryRespVO>` | -| PUT | `/admin/faq/categories/{id}` | Path + Body | `Result<FaqCategoryRespVO>` | -| PUT | `/admin/faq/categories/{id}/status` | Path + Query: status=ACTIVE/INACTIVE | `Result<Void>` | -| DELETE | `/admin/faq/categories/{id}` | Path: id | `Result<Void>` 软删，**前置校验：分类下不能有条目** | - -### 3.4 管理端接口 - 条目（前缀 `/admin/faq/items`） - -| 方法 | 路径 | 入参 | 返参 | -|---|---|---|---| -| GET | `/admin/faq/items` | Query: FaqItemPageReqVO | `Result<PageResult<FaqItemRespVO>>` | -| GET | `/admin/faq/items/{id}` | Path: id | `Result<FaqItemRespVO>` | -| POST | `/admin/faq/items` | Body: FaqItemSaveReqVO | `Result<FaqItemRespVO>` | -| PUT | `/admin/faq/items/{id}` | Path + Body | `Result<FaqItemRespVO>` | -| PUT | `/admin/faq/items/{id}/status` | Path + Query: status=ACTIVE/INACTIVE | `Result<Void>` | -| DELETE | `/admin/faq/items/{id}` | Path: id | `Result<Void>` 软删 | - -### 3.5 VO 字段 - -**FaqCategorySaveReqVO** -| 字段 | 类型 | 必填 | 校验 | -|---|---|---|---| -| id | Long | | 不传=创建 | -| name | String | ✅ | @NotBlank, ≤50 | -| sortOrder | Integer | | | - -**FaqCategoryRespVO**：id(String) / name / sortOrder / status / statusLabel / itemCount / createTime / updateTime - -**FaqItemPageReqVO** -| 字段 | 类型 | 说明 | -|---|---|---| -| page / pageSize | Integer | | -| categoryId | Long | 可选，按分类筛 | -| keyword | String | 模糊匹配 question | -| status | String | ACTIVE/INACTIVE | - -**FaqItemSaveReqVO** -| 字段 | 类型 | 必填 | 校验 | -|---|---|---|---| -| id | Long | | 不传=创建 | -| categoryId | Long | ✅ | @NotNull | -| question | String | ✅ | @NotBlank, ≤200 | -| answer | String | ✅ | @NotBlank, ≤10000，富文本 XSS 过滤 | -| sortOrder | Integer | | | - -**FaqItemRespVO**：id(String) / categoryId(String) / categoryName / question / answer / sortOrder / status / statusLabel / createTime / updateTime - -### 3.6 小程序端接口 - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `/mp/common/faq` | 返回全部启用 FAQ（按分类嵌套），缓存 30 分钟 | - -返回：`Result<List<MpFaqCategoryRespVO>>` -- `MpFaqCategoryRespVO`：`id`(String) / `name` / `items`（条目列表） -- `MpFaqItemRespVO`：`id`(String) / `question` / `answer` - -> **小程序端只返回启用的分类和条目**，按 sortOrder 升序。 - ---- - -## 4. 协议政策 - Agreement - -### 4.1 业务说明 -法律协议，按 `type` 唯一（每类型最多一条记录）。前端"用户协议"、"隐私政策"链接打开。 -**UPSERT 模式**：管理端只有保存接口（按 type 自动判断创建/更新），无独立 DELETE。 - -### 4.2 数据库表 `sys_agreement` -| 列 | 类型 | 说明 | -|---|---|---| -| agreement_id | BIGINT | 雪花 ID | -| type | VARCHAR(64) | **UNIQUE**，字典 mp_agreement_type | -| title | VARCHAR(100) | 标题 | -| content | MEDIUMTEXT | 正文，HTML 富文本 | -| update_date | DATE | 显式更新日期，C 端副标题用 | -| version | VARCHAR | 版本号（保留字段，默认 1.0）| -| status | VARCHAR(32) | ACTIVE/INACTIVE | -| sort_order | INT | 排序 | -| create_time/update_time/created_by/updated_by/deleted_at | | 审计 + 软删 | - -### 4.3 管理端接口（前缀 `/admin/agreement`） - -| 方法 | 路径 | 入参 | 返参 | -|---|---|---|---| -| GET | `/admin/agreement/page` | Query: AgreementPageReqVO | `Result<IPage<AgreementRespVO>>` | -| GET | `/admin/agreement/{id}` | Path: id | `Result<AgreementRespVO>` | -| GET | `/admin/agreement/type/{type}` | Path: type | `Result<AgreementRespVO>` 按 type 取，编辑页用 | -| POST | `/admin/agreement/save-by-type` | Body: AgreementSaveReqVO | `Result<Void>` UPSERT，幂等 | - -> **没有 DELETE 接口**。下线请改 status=INACTIVE。 - -### 4.4 AgreementSaveReqVO 字段 -| 字段 | 类型 | 必填 | 校验/字典 | -|---|---|---|---| -| type | String | ✅ | @NotBlank, @Pattern `^(USER_AGREEMENT|PRIVACY_POLICY)$`, mp_agreement_type | -| title | String | ✅ | @NotBlank, ≤100 | -| content | String | ✅ | @NotBlank, ≤100000（100KB），HTML 富文本，XSS 白名单过滤 | -| updateDate | LocalDate | | 不传默认今天 | -| sortOrder | Integer | | 默认 0 | - -### 4.5 AgreementRespVO 返回字段 -id(String) / type / typeLabel / title / content / version / updateDate / sortOrder / status / statusLabel / createTime / updateTime / createdBy(String) / updatedBy(String) - -### 4.6 小程序端接口（前缀 `/mp/common`） - -| 方法 | 路径 | 说明 | -|---|---|---| -| GET | `/mp/common/agreement/{type}` | 取指定类型协议详情（含正文），缓存 30 分钟 | -| GET | `/mp/common/agreement/list` | 取全部 ACTIVE 协议列表（**不含 content**，轻量），缓存 30 分钟 | - -**MpAgreementDetailVO**（详情接口）：type / title / content / version / updateDate / updateTime -**MpAgreementSimpleVO**（列表接口）：type / title / version / updateDate / updateTime - ---- - -## 5. 字典完整清单 - -### 5.1 `banner_media_type` -| value | label | -|---|---| -| IMAGE | 图片 | -| VIDEO | 视频 | - -### 5.2 `banner_link_type` -| value | label | -|---|---| -| NONE | 无跳转 | -| PRODUCT | 产品详情 | -| SCENIC | 景点详情 | -| ACTIVITY | 活动详情 | -| HOTEL | 酒店详情 | -| PAGE | 小程序页面 | -| WEBVIEW | H5 外链 | - -> 说明：linkType=PRODUCT/SCENIC/ACTIVITY/HOTEL 时，`linkId` 必填（资源 ID）。linkType=WEBVIEW/PAGE 时，`linkUrl` 必填。 - -### 5.3 `contact_channel_type` -| value | label | 用法 | -|---|---|---| -| ABOUT | 关于我们 | `content` 存富文本 | -| ONLINE_CS | 在线客服 | `value` 存 URL | -| PHONE | 电话咨询 | `value` 存电话号 | - -### 5.4 `mp_agreement_type` -| value | label | -|---|---| -| USER_AGREEMENT | 用户协议 | -| PRIVACY_POLICY | 隐私政策 | - -### 5.5 `common_status` -| value | label | -|---|---| -| ACTIVE | 启用 | -| INACTIVE | 停用 | - -> 适用：sys_contact / sys_faq_category / sys_faq_item / sys_agreement 的 status 字段。 -> **特例**：`sys_banner.status` 是整数 0/1（0=下线，1=上线），与本字典不同，不要混淆。 - ---- - -## 6. 前端对接 Checklist - -### 管理端 -- [ ] 列表/详情页直接调 `/admin/...`，使用 ADMIN Token -- [ ] 表单字段按本文档 SaveReqVO 严格对齐（必填项、长度限制） -- [ ] 字典下拉用各模块的 `/enabled` 接口（不要硬编码） -- [ ] Long 类型 ID 接收/回传统一按字符串处理 -- [ ] 富文本编辑器输出 HTML，后端会过滤危险标签 -- [ ] 5 秒内同参数提交会被幂等拦截（无需自行去重） -- [ ] 软删除后该数据列表自动消失（无需特殊处理） - -### 小程序端 -- [ ] 调 `/mp/...` 接口，使用 USER Token（部分公开如 `/mp/banner/active` 可不传） -- [ ] **缓存 30 分钟**：管理端改完后小程序最多 30 分钟生效，前端体验需告知用户 -- [ ] Banner/FAQ 已按 sortOrder 排好，前端按返回顺序展示即可 -- [ ] FAQ 返回结构是嵌套的（分类→条目数组），可直接渲染分组列表 -- [ ] Agreement 详情页用 `/mp/common/agreement/{type}` 取 content；列表（如登录页同意勾选）用 `/list` 节省流量 - ---- - -## 7. 已知坑/注意事项 - -1. **status 字段两种格式**：sys_banner 是 0/1 整数；其他三表（contact/faq/agreement）是 ACTIVE/INACTIVE 字符串。前端列表筛选时勿混。 -2. **Banner 用 BannerRequest 类名**（历史遗留），不是 BannerSaveReqVO。 -3. **FAQ 删除分类有前置校验**：分类下有条目时返回业务异常 `code=500`，需先清空条目。 -4. **Agreement 不能删**：只能 status=INACTIVE 软下线。 -5. **小程序端 30 分钟缓存**无主动失效机制，灰度调试期建议用临时账号清测试用户的 Redis Key。 -6. **OperatorHolder 已修复**（PR #777）：所有写操作的 `created_by/updated_by` 现在能正确填入操作人 ID（之前是 NULL）。 - ---- - -## 8. 联系/反馈 - -后端代码位置： -- Admin Controller：`hl-user-service/src/main/java/com/hulalv/user/controller/Admin{Banner,Contact,Faq,Agreement}Controller.java` -- Internal Controller：`hl-user-service/src/main/java/com/hulalv/user/controller/Internal{Banner,Contact,Faq,MpCommon}Controller.java` -- MP Controller：`hl-mp-service/src/main/java/com/hulalv/mp/controller/Mp{Banner,Common}Controller.java` -- VO：`hl-user-service/src/main/java/com/hulalv/user/vo/{admin,mp}/` - -如有字段缺失或行为不符，**直接反馈到本仓库 Issue**（带接口路径 + 实际响应 + 期望响应）。 diff --git a/changelogs/2026-04/2026-04-18_mp-group-product-list.md b/changelogs/2026-04/2026-04-18_mp-group-product-list.md deleted file mode 100644 index ec16d82..0000000 --- a/changelogs/2026-04/2026-04-18_mp-group-product-list.md +++ /dev/null @@ -1,338 +0,0 @@ -# 小程序端 - 新增小蒙马产品全部列表接口 - -- **日期**: 2026-04-18 -- **PR**: [#847](https://git.1814.love:8443/wx/HL/pulls/847) (Closes #843) -- **类型**: FEATURE -- **状态**: 已合并到 dev + 测试环境部署中 -- **服务**: hl-mp-service + hl-product-service-v2 - ---- - -## 一、功能说明 - -### 业务场景 -小程序「**小蒙马专题页**」需要一次性铺满展示**全部已上架的小蒙马（GROUP）产品**： - -- 不分页（瀑布流/卡片墙一屏看全） -- 每个产品卡片要直接显示**最近的可售团期**（出发日期、起步价、剩余名额） -- 支持关键词模糊搜索（产品名 / 副标题 / 标签） - -### 设计要点 - -| 维度 | 设计 | 说明 | -|------|------|------| -| **是否分页** | 否 | hard cap 100 条（业务上小蒙马产品总数远 < 100，专题页一次性渲染） | -| **排序** | `sort_order ASC, product_id DESC` | 运营通过 `sort_order` 控制置顶；同序号按新产品在前 | -| **缓存** | 服务端 600s TTL | `@MpCache(prefix="product:group:list:", ttl=600)`，发布/下架后 10 分钟内生效 | -| **batches 注入** | 与 `/mp/product/list` **完全一致** | 复用 `injectBatchesForGroupItems` 私有方法，并行 Feign 调用，单个失败不影响整体 | -| **productId 类型** | String | `@JsonSerialize(ToStringSerializer)` 防 JS 雪花 ID 精度丢失 | -| **详情接口** | **零改动** | 直接复用 `GET /mp/product/{productId}`（详见下方"重要提示"） | -| **N+1 防护** | 4 步批量查询 | basic 列表 + paymentType 批量 + 起步价日历批量 + lineName 批量 | -| **权限** | OPTIONAL | 无需登录即可访问 | - ---- - -## 二、变更接口清单 - -| # | 方法 | 路径 | 说明 | 鉴权 | 缓存 | -|---|------|------|------|------|------| -| 1 | GET | `/mp/product/group/list` | 小蒙马产品全部列表（不分页 + batches） | OPTIONAL | 600s | - ---- - -## 三、接口详细定义 - -### 1. 小蒙马产品全部列表 - -``` -GET /mp/product/group/list -``` - -#### 鉴权 -- **OPTIONAL**：登录与未登录均可访问，逻辑无差异 -- 已加入网关白名单，可直接调用 - -#### 请求参数 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `keyword` | query | String | 否 | 模糊搜索关键词（匹配产品名/副标题/标签） | - -#### 请求示例 - -``` -GET /mp/product/group/list -GET /mp/product/group/list?keyword=亲子 -``` - -#### 完整响应示例 - -```json -{ - "code": 200, - "message": "success", - "data": [ - { - "productId": "120000000000001", - "productType": "GROUP", - "name": "草原星空亲子3日游", - "subtitle": "8人精品小团·1对1管家", - "coverImageUrl": "https://oss.example.com/cover.jpg", - "tripDays": 3, - "tripNights": 2, - "lineName": "亲子草原", - "tags": ["亲子", "星空"], - "seasons": ["summer", "autumn"], - "startPrice": 3980.00, - "startPriceLabel": "¥3980起/人", - "paymentType": "DEPOSIT", - "sortOrder": 10, - "batches": [ - { - "batchId": "9001000000000001", - "departureDate": "2026-05-01", - "batchLabel": "五一团", - "batchName": "草原星空亲子3日游 5月1日团", - "batchStatus": "ENROLLING", - "startingPrice": 3980.00, - "enrolledCount": 6, - "remainingSlots": 2, - "isConfirmed": false - }, - { - "batchId": "9001000000000002", - "departureDate": "2026-05-15", - "batchLabel": "5月中旬团", - "batchName": "草原星空亲子3日游 5月15日团", - "batchStatus": "CONFIRMED", - "startingPrice": 3980.00, - "enrolledCount": 8, - "remainingSlots": 0, - "isConfirmed": true - } - ] - }, - { - "productId": "120000000000002", - "productType": "GROUP", - "name": "呼伦贝尔大环线4日游", - "subtitle": "深度纯玩·全程5星住宿", - "coverImageUrl": "https://oss.example.com/cover2.jpg", - "tripDays": 4, - "tripNights": 3, - "lineName": "呼伦贝尔环线", - "tags": ["纯玩", "5星"], - "seasons": ["summer"], - "startPrice": 5680.00, - "startPriceLabel": "¥5680起/人", - "paymentType": "FULL", - "sortOrder": 20, - "batches": [] - } - ] -} -``` - -> **空数据**：当不存在已上架 GROUP 产品时，`data` 返回 `[]`（**不是 null**）。 -> **batches 为空**：某产品当前无可售团期时，该产品的 `batches` 返回 `[]`。 - -#### 响应字段说明 - -| 字段 | 类型 | 必有 | 说明 | -|------|------|------|------| -| `data[].productId` | **String** | 是 | 产品ID（**字符串**，由后端 `ToStringSerializer` 序列化，前端**禁止用 Number 接收**） | -| `data[].productType` | String | 是 | 产品类型，固定值 `GROUP`（小蒙马） | -| `data[].name` | String | 是 | 产品名称 | -| `data[].subtitle` | String | 否 | 副标题/卖点（一行短文案） | -| `data[].coverImageUrl` | String | 否 | 封面图 URL（OSS CDN 地址） | -| `data[].tripDays` | Integer | 是 | 行程天数 | -| `data[].tripNights` | Integer | 是 | 行程晚数 | -| `data[].lineName` | String | 否 | 产品线（主题）名称 | -| `data[].tags` | List\<String\> | 否 | 标签数组（如 `["亲子","星空"]`） | -| `data[].seasons` | List\<String\> | 否 | 适合季节数组，字典 `product_season` | -| `data[].startPrice` | BigDecimal | 否 | 起步价（元，未来日期最低成人售价） | -| `data[].startPriceLabel` | String | 否 | 起步价文案（用于卡片标价，如 `¥3980起/人`） | -| `data[].paymentType` | String | 是 | 支付方式，字典 `payment_type` | -| `data[].sortOrder` | Integer | 否 | 运营排序号（值越小越靠前） | -| `data[].batches` | List\<Object\> | 是 | **可售团期列表（即使为空也返回 `[]`）**，结构见下表 | - -#### `batches[]` 字段说明（与 `/mp/product/list` 完全一致） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `batches[].batchId` | String/Long | 团期 ID（与 v1 团期接口一致，建议用 String 接收） | -| `batches[].departureDate` | String | 出发日期 `yyyy-MM-dd`（**列表已按出发日期升序**） | -| `batches[].batchLabel` | String | 团期标签（如 `五一团` `暑假首发` 等运营自定义） | -| `batches[].batchName` | String | 团期完整名称 | -| `batches[].batchStatus` | String | 团期状态，字典 `batch_status` | -| `batches[].startingPrice` | BigDecimal | 团期起步价（元） | -| `batches[].enrolledCount` | Integer | 已报名人数 | -| `batches[].remainingSlots` | Integer | 剩余名额 | -| `batches[].isConfirmed` | Boolean | 是否已成团 | - ---- - -## 四、重要提示给前端 - -### 1. 详情接口零改动 — 直接复用现有接口 - -> **不要再问"小蒙马是不是要专属详情接口"，没有，也不需要。** - -``` -GET /mp/product/{productId} -``` - -这个接口**已经支持 GROUP 产品**，会自动注入 `batches` 字段（详情接口 notes 已写明）。 - -**前端动作**： -- 列表页：调用 `GET /mp/product/group/list` 拿到 productId -- 详情页：直接 `GET /mp/product/{productId}`（productId 用 String 拼接，**不要 parseInt**） -- 详情返回结构与现有产品详情完全一致，GROUP 产品的 `batches` 字段在 detail VO 中已存在 - -### 2. productId 必须用 String 处理 - -后端 VO 字段： - -```java -@JsonSerialize(using = ToStringSerializer.class) -private Long productId; -``` - -序列化结果：`"productId": "120000000000001"` （**带引号的字符串**） - -前端**禁止**： - -```javascript -// ❌ 错误：JS Number 最大安全整数 2^53，会精度丢失 -const id = Number(item.productId); - -// ✅ 正确：直接用 String -const id = item.productId; -fetch(`/mp/product/${id}`); -``` - -### 3. 与 `/mp/product/list?productType=GROUP` 的差异 - -| 维度 | `/mp/product/list?productType=GROUP` | `/mp/product/group/list` | -|------|--------------------------------------|--------------------------| -| 分页 | 有（page+pageSize） | **无**（hard cap 100） | -| 返回结构 | `Result<PageResult<Map>>` | `Result<List<Map>>` | -| 字段 | 通用产品字段 + batches | 同左（一致） | -| 缓存 key | `product:list:` | `product:group:list:` | -| 适用场景 | 通用列表（带筛选/分页） | **小蒙马专题页一次性铺满** | - -> **建议**：专题页用 `/mp/product/group/list`；通用列表（首页、搜索）继续用 `/mp/product/list`。 - ---- - -## 五、缓存说明 - -- **服务端缓存**：`@MpCache(prefix="product:group:list:", ttl=600)` -- **TTL**：600 秒（10 分钟） -- **缓存粒度**：按 `keyword` 区分，无 keyword 与有 keyword 是不同的 cache key -- **失效时机**：依赖自然过期（10 分钟内运营发布/下架的产品不会立即可见） -- **前端缓存建议**：列表数据可在小程序端短期缓存（如 30 秒），下拉刷新时强制清缓存 - ---- - -## 六、字典对照 - -### `product_type`（产品类型） - -| 值 | 中文 | 说明 | -|----|------|------| -| `CORE` | 核心产品 | 主推标准产品 | -| `ROUTE` | 自驾路书 | 自驾游线路 | -| `CUSTOM` | 私人定制 | 1对1定制行程 | -| `GROUP` | **小蒙马** | **本接口固定返回此类型** | - -### `batch_status`（团期状态） - -| 值 | 中文 | UI 建议 | -|----|------|---------| -| `ENROLLING` | 报名中 | 显示绿色标签 + 剩余名额 | -| `CONFIRMED` | 已成团 | 显示蓝色标签"已成团" | -| `FULL` | 已满员 | 显示灰色标签 + 禁用报名按钮 | -| `CLOSED` | 已关闭 | 显示灰色标签 + 隐藏 CTA | - -### `payment_type`（支付方式） - -| 值 | 中文 | -|----|------| -| `FULL` | 全额支付 | -| `DEPOSIT` | 订金 + 尾款 | - -### `product_season`（适合季节） - -| 值 | 中文 | -|----|------| -| `spring` | 春季 | -| `summer` | 夏季 | -| `autumn` | 秋季 | -| `winter` | 冬季 | - ---- - -## 七、前端实现建议 - -### 推荐：瀑布流 / 卡片墙 - -``` -┌──────────────────────── 小蒙马专题页 ────────────────────────┐ -│ [搜索框 keyword] │ -│ │ -│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ -│ │ [封面图] │ │ [封面图] │ │ [封面图] │ │ -│ │ 草原星空亲子3日 │ │ 呼伦贝尔大环线 │ │ 阿尔山雪国5日 │ │ -│ │ 8人精品小团 │ │ 深度纯玩 │ │ 冬季限定 │ │ -│ │ #亲子 #星空 │ │ #纯玩 #5星 │ │ #雪景 │ │ -│ │ ¥3980起/人 │ │ ¥5680起/人 │ │ ¥6280起/人 │ │ -│ │ ────────────── │ │ ────────────── │ │ ────────────── │ │ -│ │ 最近团期： │ │ 最近团期： │ │ 最近团期： │ │ -│ │ • 5/1 报名中(2) │ │ • 5/8 报名中(5) │ │ • 12/20 报名中 │ │ -│ │ • 5/15 已成团 │ │ │ │ │ │ -│ └────────────────┘ └────────────────┘ └────────────────┘ │ -└──────────────────────────────────────────────────────────────┘ -``` - -### 卡片渲染要点 - -1. **顶部图区**：`coverImageUrl`，建议固定宽高比（如 16:10） -2. **标题区**：`name`（粗体）+ `subtitle`（小字灰色） -3. **标签区**：`tags` 取前 2-3 个，超出折叠 -4. **价格区**：用 `startPriceLabel` 直接渲染（已带 `¥` 和 `起/人` 后缀） -5. **团期区**：`batches` 取前 2 条展示（按出发日期升序），显示 `departureDate` + 状态标签 + 剩余名额 -6. **空团期**：`batches=[]` 时显示"暂无可售团期"或灰显 - -### 跳转详情 - -```javascript -// 卡片点击 -function onCardTap(item) { - // productId 必须用 String 拼接 - wx.navigateTo({ url: `/pages/product/detail?id=${item.productId}` }); -} - -// 详情页加载 -function loadDetail(id) { - // 直接复用现有详情接口，无需任何改动 - return request.get(`/mp/product/${id}`); -} -``` - ---- - -## 八、回归验证 - -测试环境部署完成后，前端可通过以下方式验证： - -``` -GET https://api.test.1814.love/mp/product/group/list -``` - -**预期**： -- HTTP 200 -- `data` 为数组（即使为空也是 `[]`） -- 每个 item 的 `productType === "GROUP"` -- 每个 item 的 `productId` 是带引号的 String -- GROUP 产品有可售团期时 `batches.length > 0`，否则 `batches === []` diff --git a/changelogs/2026-04/2026-04-18_mp-hotel-room-cover-fix.md b/changelogs/2026-04/2026-04-18_mp-hotel-room-cover-fix.md deleted file mode 100644 index cd6367c..0000000 --- a/changelogs/2026-04/2026-04-18_mp-hotel-room-cover-fix.md +++ /dev/null @@ -1,52 +0,0 @@ -# 小程序住宿详情 - 房型封面图 null 问题修复 - -- **日期**: 2026-04-18 -- **PR**: [#825](https://git.1814.love:8443/wx/HL/pulls/825) (Closes #824) -- **类型**: BUG FIX -- **状态**: 已合并到 dev + 测试环境部署中 - ---- - -## 影响接口 - -- `GET /mp/hotel/{hotelId}` (C 端住宿详情) - -## 现象 - -调用住宿详情返回的 `roomTypes` 数组中，**每个房型的 `coverUrl` 都是 null**（其他字段正常）。 - -```json -{ - "code": 200, - "data": { - "hotelId": "2023714929877450753", - "roomTypes": [ - { - "roomTypeId": "...", - "name": "豪华大床房", - "coverUrl": null, // 错误：应为 https://.../cover.jpg - "bannerUrls": [], // 错误：应为图片 URL 数组 - "videoUrl": null // 错误：应为视频 URL - } - ] - } -} -``` - -## 根因（仅供参考，前端无需关注） - -`RoomTypeService.listRoomTypes` 手动补救 `coverUrl` 时用 String 类型的 `coverMaterialId` 去查 `Map<Long, String>`，Java `HashMap.get` 不做类型转换导致永远返回 null。`banner/video` 的 materialId 同样未纳入批量查询。 - -## 修复后行为 - -- `roomTypes[i].coverUrl`：有封面素材时返回 https CDN URL -- `roomTypes[i].bannerUrls`：有横幅素材时返回 URL 数组（无素材的条目已 filter） -- `roomTypes[i].videoUrl`：有视频素材时返回 URL - -## 前端 Action - -**无需改代码**。后端修复后直接生效。 - -## 回归验证 - -测试环境部署完成后，调用 `GET /mp/hotel/{任一已上架酒店ID}` 检查 `roomTypes[0].coverUrl` 非 null 即可。 diff --git a/changelogs/2026-04/2026-04-18_mp-order-service-detail-and-vo-upgrade.md b/changelogs/2026-04/2026-04-18_mp-order-service-detail-and-vo-upgrade.md deleted file mode 100644 index d0856e1..0000000 --- a/changelogs/2026-04/2026-04-18_mp-order-service-detail-and-vo-upgrade.md +++ /dev/null @@ -1,574 +0,0 @@ -# 小程序订单 - 服务详情弹窗接口 + MpOrderDetailVO 字段强类型化 - -- **日期**: 2026-04-18 -- **PR**: - - [#818](https://git.1814.love:8443/wx/HL/pulls/818) MpOrderDetailVO 6 字段强类型化 - - [#853](https://git.1814.love:8443/wx/HL/pulls/853) 补 6 个服务详情透传 - - [#856](https://git.1814.love:8443/wx/HL/pulls/856) 独立 Controller + Swagger 分组 -- **类型**: FEATURE + REFACTOR -- **状态**: 已合并到 dev + 测试环境部署中 -- **服务**: hl-mp-service + hl-order-service-v2 - ---- - -## 一、本次变更汇总 - -### 1. 订单详情 VO 字段强类型化（🔵 前端体验提升，无 Breaking） - -`MpOrderDetailVO`（下单 / 详情 / 编辑 三接口共用返回结构）中的 6 个字段，**字段名完全不变**，仅 JSON Schema 由 `Map<String, Object>` / `List<Map<String, Object>>` 升级为**强类型 VO**。前端 TS 类型提示/自动补全可直接受益。 - -| 字段 | 旧类型 | 新类型 | -|------|--------|--------| -| `priceBreakdown` | `object` (Map) | `MpPriceBreakdownVO` | -| `serviceItems` | `object[]` (List<Map>) | `MpServiceItemVO[]` | -| `tripProgress` | `object` (Map) | `MpTripProgressVO` | -| `refundProgress` | `object` (Map) | `MpRefundProgressVO` | -| `travelers` | `object[]` | `MpTravelerVO[]` | -| `todos` | `object[]` | `MpOrderTodoVO[]` | - -### 2. 新增 6 个服务详情弹窗接口（🟢 新功能） - -订单详情页 `serviceItems` 列表里每个条目点击后的弹窗数据源，此前前端调不到，现已对外开放。 - -独立 **Swagger 分组**：`C端 - 订单接口 - 服务包含`（knife4j 左侧菜单）。 - ---- - -## 二、变更接口清单 - -| # | 方法 | 路径 | 说明 | 鉴权 | 缓存 | -|---|------|------|------|------|------| -| 1 | POST | `/mp/order/create` | 创建订单（返回结构升级） | REQUIRED | 否 | -| 2 | GET | `/mp/order/{orderId}` | 订单详情（返回结构升级） | REQUIRED | 否 | -| 3 | PUT | `/mp/order/{orderId}/edit` | 用户编辑订单（返回结构升级） | REQUIRED | 否 | -| 4 | GET | `/mp/order/{orderId}/tickets` | 【新增】门票清单 | REQUIRED | 否 | -| 5 | GET | `/mp/order/{orderId}/hotels` | 【新增】住宿清单 | REQUIRED | 否 | -| 6 | GET | `/mp/order/{orderId}/meals` | 【新增】餐饮清单 | REQUIRED | 否 | -| 7 | GET | `/mp/order/{orderId}/vehicle` | 【新增】用车详情 | REQUIRED | 否 | -| 8 | GET | `/mp/order/{orderId}/guide` | 【新增】领队详情 | REQUIRED | 否 | -| 9 | GET | `/mp/order/{orderId}/photographer` | 【新增】摄影师详情 | REQUIRED | 否 | - ---- - -## 三、订单创建接口（返回结构升级） - -``` -POST /mp/order/create -``` - -### 请求（未变化） - -```json -{ - "productId": "1760000000000001", - "departureDate": "2026-05-01", - "groupBatchId": "1760000000000002", - "tierSeq": 1, - "adultCount": 2, - "childCount": 0, - "youngChildCount": 0, - "babyCount": 0, - "childNeedBed": false, - "roomCount": 1, - "contactName": "张三", - "contactPhone": "13800138000", - "remark": "希望安排靠窗", - "sharerOpenid": "wx_xxxxx" -} -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `productId` | String | 是 | 产品ID | -| `departureDate` | String(yyyy-MM-dd) | 否 | 出发日期；GROUP 产品可不传（从团期取） | -| `groupBatchId` | String | 条件必填 | GROUP 产品必填 | -| `tierSeq` | Integer | 是 | 档位序号，≥1 | -| `adultCount` | Integer | 是 | 成人数，默认 1，≥1 | -| `childCount` | Integer | 否 | 儿童数，≥0 | -| `youngChildCount` | Integer | 否 | 小童数，≥0 | -| `babyCount` | Integer | 否 | 幼童数，≥0 | -| `childNeedBed` | Boolean | 否 | 儿童是否需要床位 | -| `roomCount` | Integer | 否 | 房间数（GROUP 默认 1） | -| `contactName` | String | 是 | 联系人姓名，≤50 字 | -| `contactPhone` | String | 是 | 联系人电话，≤20 字 | -| `remark` | String | 否 | 备注，≤500 字 | -| `sharerOpenid` | String | 否 | 分享人 openid，≤64 字 | - -### 返回（结构升级） - -> **⚠️ 关键**：`POST /mp/order/create`、`GET /mp/order/{id}`、`PUT /mp/order/{id}/edit` 三个接口返回结构**完全一致**，均为 `MpOrderDetailVO`。前端可共用一套类型定义 + 渲染组件。 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "orderId": "2045450312813043713", - "orderNo": "HL20260418183211-6560", - "groupCode": "6560", - "productId": "2045424500610125825", - "productName": "E2E-核心版本-V1", - "productSubtitle": "去草原看日出", - "productCoverUrl": "https://cdn.example.com/cover.jpg", - "productType": "CORE", - "productTypeLabel": "核心产品", - "departureDate": "2026-05-10", - "returnDate": "2026-05-12", - "tripDays": 3, - "tripNights": 2, - "adultCount": 1, - "childCount": 0, - "youngChildCount": 0, - "babyCount": 0, - "createTime": "2026-04-18 18:32:12", - - "status": "PENDING_PAY", - "statusLabel": "待支付", - "displayStatus": "PENDING_PAY", - "displayStatusLabel": "待支付", - "expiryTime": "2026-04-18 20:32:12", - - "totalPrice": 2401280.00, - "paidAmount": 0.00, - "depositAmount": 500.00, - "balanceAmount": 2400780.00, - "paymentType": "DEPOSIT", - "paymentTypeLabel": "订金+尾款", - "payMethodLabel": "微信支付", - "balancePayMethodLabel": "落地后由领队收取", - - "priceBreakdown": { - "items": [ - { "label": "成人", "unitPrice": 2300.00, "quantity": 1, "amount": 2300.00 } - ], - "subtotal": 2300.00, - "discounts": [], - "totalDiscount": 0.00, - "totalPayable": 2300.00 - }, - - "serviceItems": [ - { "type": "HOTEL", "title": "住宿", "summary": "2 晚精选当地酒店", "clickable": true }, - { "type": "MEAL", "title": "餐饮", "summary": "含早餐 2 次 + 特色正餐 1 次", "clickable": true }, - { "type": "VEHICLE", "title": "用车", "summary": "小蒙马车 1 辆", "clickable": true } - ], - "notIncluded": "往返呼伦贝尔大交通、个人消费", - - "tripProgress": null, - "refundProgress": null, - "travelers": [], - "todos": [], - - "contractStatus": "NONE", - "contractStatusLabel": "无合同", - "insuranceStatus": "NONE", - "insuranceStatusLabel": "无保险", - "invoiceStatus": "AFTER_TRIP", - "invoiceStatusLabel": "出行后开", - "reviewed": false, - - "customizerId": "1001", - "customizerName": "admin", - "customizerAvatarUrl": null, - "customizerQrUrl": null, - - "refundPolicy": { - "policyId": 1, - "policyName": "标准退款", - "rules": [] - } - }, - "success": true -} -``` - -### `MpOrderDetailVO` 重点字段类型说明 - -#### priceBreakdown - 价格明细 - -```typescript -interface MpPriceBreakdownVO { - items: MpPriceLineItemVO[]; // 按人群类型的单价明细 - subtotal: number; // 小计（优惠前） - discounts: MpDiscountLineItemVO[];// 优惠明细列表 - totalDiscount: number; // 已优惠总额（负数） - totalPayable: number; // 应付总额 -} - -interface MpPriceLineItemVO { - label: string; // "成人" / "儿童" 等 - unitPrice: number; - quantity: number; - amount: number; -} - -interface MpDiscountLineItemVO { - tag: string; // "早鸟" - description: string; // "提前30天" - amount: number; // 负数 -} -``` - -#### serviceItems - 服务包含摘要 - -```typescript -interface MpServiceItemVO { - type: 'HOTEL' | 'MEAL' | 'VEHICLE' | 'GUIDE' | 'PHOTOGRAPHER' | 'TICKET' | 'INSURANCE'; - title: string; // "住宿" - summary: string; // "2 晚精选当地酒店" - clickable: boolean; // 是否可点击查看详情弹窗（对应下面 6 个弹窗接口） -} -``` - -> 当 `clickable === true` 时，点击该条目调用对应的 `/mp/order/{orderId}/{tickets|hotels|meals|vehicle|guide|photographer}` 接口拉取弹窗详情。映射关系： -> - HOTEL → `/hotels` -> - MEAL → `/meals` -> - VEHICLE → `/vehicle` -> - GUIDE → `/guide` -> - PHOTOGRAPHER → `/photographer` -> - TICKET → `/tickets` - -#### tripProgress - 行程进度 - -```typescript -interface MpTripProgressVO { - currentDay: number; // 当前第几天 - totalDays: number; // 总天数 - progressPercent: number; // 进度百分比（0-100） - todayDestination: string; // 今日目的地 -} -``` - -> **仅行程中状态有值**，其他状态该字段为 `null`（且因 `@JsonInclude(NON_NULL)` 过滤，可能不在 JSON 中出现）。 - -#### refundProgress - 退款进度 - -```typescript -interface MpRefundProgressVO { - steps: MpRefundStepVO[]; // 4 步时间线 - currentStep: number; // 当前活跃步骤索引（0-based） - refundAmount: number; - refundMethod: string; // 例 "原路返回·微信" - refundArrivalTime: string | null; // 已到账才有值 -} - -interface MpRefundStepVO { - title: string; // "提交申请" - description: string; - status: 'COMPLETED' | 'ACTIVE' | 'PENDING'; - time: string | null; // PENDING 时为 null -} -``` - -#### travelers - 出行人列表 - -```typescript -interface MpTravelerVO { - travelerId: number; - name: string; - travelerType: string; // ADULT/CHILD/YOUNG_CHILD/BABY - travelerTypeLabel: string; // "成人" 等中文 - idCardType: string; // ID_CARD/PASSPORT - idCardTypeLabel: string; // "身份证" 等中文 - idCardNo: string; - gender: string; - birthday: string; - phone: string; - nationality: string; - emergencyContact: string; - emergencyPhone: string; - email: string; -} -``` - -#### todos - 待办列表 - -```typescript -interface MpOrderTodoVO { - todoId: number; - todoType: string; - todoTypeLabel: string; - todoLabel: string; - sequence: number; - status: string; - assigneeRoleKey: string; - assigneeRoleLabel: string; - completedAt: string | null; - createTime: string; - blocked: boolean; - blockedReason: string | null; -} -``` - ---- - -## 四、服务详情弹窗接口（6 个新增） - -所有接口签名一致： -- **方法**: GET -- **鉴权**: `Authorization: Bearer {mp-token}`（用户登录态） -- **Path Var**: `orderId` (Long) -- **Query**: 无 -- **失败降级**: 订单服务不可用时返回 `{"code":500, "message":"订单服务不可用，请稍后重试"}` - -### 1. 门票清单 - -``` -GET /mp/order/{orderId}/tickets -``` - -```json -{ - "code": 200, - "data": { - "items": [ - { - "seq": 1, - "scenicName": "莫日格勒河", - "coverUrl": "https://cdn.example.com/scenic/1.jpg", - "dayNumber": 2, - "originalPrice": 80.00, - "included": true - } - ], - "scenicCount": 14, - "totalValue": 340.00 - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `items[]` | MpTicketItemVO[] | 门票列表 | -| `items[].seq` | Integer | 序号 | -| `items[].scenicName` | String | 景点名称 | -| `items[].coverUrl` | String | 景点封面图 | -| `items[].dayNumber` | Integer | 第几天 | -| `items[].originalPrice` | BigDecimal | 门票原价/人 | -| `items[].included` | Boolean | 是否已包含在套餐内 | -| `scenicCount` | Integer | 景点数量 | -| `totalValue` | BigDecimal | 门票总价值/人（快照有 price 才有值） | - -### 2. 住宿清单 - -``` -GET /mp/order/{orderId}/hotels -``` - -```json -{ - "code": 200, - "data": { - "items": [ - { - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "coverUrl": "https://cdn.example.com/hotel/1.jpg", - "assignmentDate": "2026-05-10", - "roomType": "大床房" - } - ], - "nightCount": 2, - "roomTypeStats": [ - { "roomType": "大床房", "count": 1 } - ] - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `items[]` | MpHotelItemVO[] | 每晚酒店列表（按入住日期升序） | -| `items[].hotelId` | Long | 酒店ID | -| `items[].hotelName` | String | 酒店名称 | -| `items[].coverUrl` | String | 酒店封面（产品服务扩展后可用） | -| `items[].assignmentDate` | String(yyyy-MM-dd) | 入住日期 | -| `items[].roomType` | String | 房型 | -| `nightCount` | Integer | 总晚数 | -| `roomTypeStats[]` | MpRoomTypeStatVO[] | 按房型统计 | -| `roomTypeStats[].roomType` | String | 房型 | -| `roomTypeStats[].count` | Integer | 房间数 | - -### 3. 餐饮清单 - -``` -GET /mp/order/{orderId}/meals -``` - -```json -{ - "code": 200, - "data": { - "specialMeals": [ - { - "dayNumber": 2, - "mealName": "蒙古包午餐·手把肉宴", - "mealType": "午餐", - "description": "含奶茶/手把肉/烤包子" - } - ], - "stats": { - "breakfastCount": 2, - "specialDinnerCount": 1, - "regularDinnerCount": 3 - } - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `specialMeals[]` | MpMealItemVO[] | 特色正餐列表（含描述的餐） | -| `specialMeals[].dayNumber` | Integer | 第几天 | -| `specialMeals[].mealName` | String | 餐名 | -| `specialMeals[].mealType` | String | 餐型：早餐/午餐/晚餐 | -| `specialMeals[].description` | String | 菜品描述 | -| `stats.breakfastCount` | Integer | 早餐数量 | -| `stats.specialDinnerCount` | Integer | 特色正餐数量（有描述的） | -| `stats.regularDinnerCount` | Integer | 日常正餐数量 | - -### 4. 用车详情 - -``` -GET /mp/order/{orderId}/vehicle -``` - -```json -{ - "code": 200, - "data": { - "vehicleType": "小蒙马车", - "vehicleCount": 1, - "coverUrl": "https://cdn.example.com/vehicle/xiaomma.jpg", - "plateNumber": "蒙E12345", - "driverName": "张师傅", - "driverPhone": "138****5678", - "matched": true - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `vehicleType` | String | 车型名称 | -| `vehicleCount` | Integer | 车辆数 | -| `coverUrl` | String | 车型封面（产品服务扩展后可用） | -| `plateNumber` | String | 车牌号（**仅出行前后可见**，其他时间为空） | -| `driverName` | String | 司机姓名 | -| `driverPhone` | String | 司机电话（脱敏） | -| `matched` | Boolean | 是否已匹配车辆 | - -### 5. 领队详情 - -``` -GET /mp/order/{orderId}/guide -``` - -```json -{ - "code": 200, - "data": { - "staffId": "5001", - "name": "巴特尔", - "avatarUrl": "https://cdn.example.com/avatar/5001.jpg", - "role": "LEADER", - "roleLabel": "领队", - "phone": "138****5678", - "remark": "10 年草原线路经验，会蒙语", - "assigned": true - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `staffId` | Long | 员工ID | -| `name` | String | 姓名 | -| `avatarUrl` | String | 头像（员工档案扩展后可用） | -| `role` | String | 角色代码 | -| `roleLabel` | String | 角色中文 | -| `phone` | String | 电话（脱敏） | -| `remark` | String | 备注/简介 | -| `assigned` | Boolean | 是否已分配 | - -### 6. 摄影师详情 - -``` -GET /mp/order/{orderId}/photographer -``` - -响应字段与领队详情完全一致，`role` 为 `"PHOTOGRAPHER"`、`roleLabel` 为 `"摄影师"`。 - ---- - -## 五、前端接入建议 - -### Swagger 入口 - -- **mp-service 独立**: http://localhost:8085/doc.html （本地开发） -- **网关聚合**: http://localhost:8080/doc.html → 切到 `hl-mp-service` -- **测试环境**: https://api.test.1814.love/doc.html → 切到 `hl-mp-service` - -左侧菜单新增分组：**「C端 - 订单接口 - 服务包含」**，6 个弹窗接口在该分组下。 - -### 订单详情页渲染建议 - -```javascript -async function openOrderDetail(orderId) { - const detail = await request.get(`/mp/order/${orderId}`); - - // 1. 渲染基础信息（orderNo/产品/金额/状态/时间轴） - renderHeader(detail.data); - - // 2. 价格明细 - 用 priceBreakdown.items / discounts 渲染 - renderPriceBreakdown(detail.data.priceBreakdown); - - // 3. 服务包含列表 - detail.data.serviceItems.forEach(item => { - renderServiceCard(item, { - onClick: item.clickable ? () => openServiceDetail(orderId, item.type) : null - }); - }); -} - -// 类型到接口路径的映射 -const SERVICE_DETAIL_API = { - HOTEL: 'hotels', MEAL: 'meals', VEHICLE: 'vehicle', - GUIDE: 'guide', PHOTOGRAPHER: 'photographer', TICKET: 'tickets' -}; - -async function openServiceDetail(orderId, type) { - const path = SERVICE_DETAIL_API[type]; - if (!path) return; // 非 clickable 类型（如 INSURANCE） - const data = await request.get(`/mp/order/${orderId}/${path}`); - showServiceDialog(type, data.data); -} -``` - ---- - -## 六、回归验证 - -测试环境部署完成后，用 mp token 依次调用： - -```bash -# 1. 拿个已绑定的订单详情，确认 6 个强类型字段结构 -curl "https://api.test.1814.love/mp/order/{orderId}" \ - -H "Authorization: Bearer {mp-token}" - -# 2. 6 个弹窗接口（对应 serviceItems 里 clickable=true 的条目） -for path in tickets hotels meals vehicle guide photographer; do - curl "https://api.test.1814.love/mp/order/{orderId}/$path" \ - -H "Authorization: Bearer {mp-token}" -done -``` - -**预期**： -- 订单详情返回的 `priceBreakdown` 是对象而非无结构 Map，`serviceItems` 是结构化数组 -- 6 个弹窗接口均返回 `code=200` + 对应 VO 结构，不再出现 403 或路径不存在 - ---- - -## 七、不兼容变更 - -**无**。字段名与语义保持不变，仅 JSON Schema 类型由 Map 升级为结构化对象；Jackson 反序列化对旧的"对象不定键"消费方式零影响。 diff --git a/changelogs/2026-04/2026-04-18_order-v2_detail-tier-info.md b/changelogs/2026-04/2026-04-18_order-v2_detail-tier-info.md deleted file mode 100644 index 4f679d1..0000000 --- a/changelogs/2026-04/2026-04-18_order-v2_detail-tier-info.md +++ /dev/null @@ -1,103 +0,0 @@ -# 订单 v2 详情接口补齐档位信息（tierSeq / tierName / tierDescription） - -- **日期**: 2026-04-18 -- **PR**: [#878](https://git.1814.love:8443/wx/HL/pulls/878) -- **类型**: FIX（字段补齐，🟢 非 Breaking，只加不改） -- **状态**: 已合并到 dev + 待测试环境部署 -- **服务**: hl-order-service-v2 + hl-mp-service（BFF 镜像） - ---- - -## 一、背景 - -订单 v2 的三个详情接口此前返回的 VO 中 **没有档位信息**（产品线下多档位场景，如「标准档 / 舒适档 / 豪华档」），导致订单详情页无法展示用户购买的具体档位名称，只能看到总价。 - -数据层已经齐全（`order_info.tier_seq` + `product_snapshot.tiers` JSON 都存得好好的），纯粹是响应 VO 层遗漏。本次仅补齐 VO 字段 + 装配层填充，数据源零改动。 - ---- - -## 二、新增字段（三字段一致，分别加在三个 VO 中） - -| 字段 | 类型 | 说明 | 示例 | -|------|------|------|------| -| `tierSeq` | `Integer` | 档位序号，默认 `1` | `2` | -| `tierName` | `String` | 档位名称 | `"舒适档"` | -| `tierDescription` | `String` | 档位描述 | `"升级双早+SPA"` | - -容错：老订单如果 `productSnapshot` 结构老、`tiers` 数组不存在或找不到对应 `tierSeq`，`tierName / tierDescription` 返回 `null`（`tierSeq` 仍返回）。前端请按需兜底显示（可用 `tierSeq` 数字或「默认档」占位）。 - ---- - -## 三、影响接口清单 - -| # | 方法 | 路径 | 返回 VO | 说明 | -|---|------|------|---------|------| -| 1 | GET | `/admin/order/{orderId}` | `OrderDetailVO` | 管理端订单详情 | -| 2 | POST | `/admin/order/create` | `OrderDetailVO` | 管理端下单回显 | -| 3 | GET | `/mp/order/{orderId}` | `MpOrderDetailVO`（BFF 镜像） | 小程序订单详情 | -| 4 | POST | `/mp/order/create`（经 BFF 透传） | `MpOrderDetailVO` | 小程序下单回显 | -| 5 | PUT | `/mp/order/{orderId}/edit`（经 BFF 透传） | `MpOrderDetailVO` | 小程序订单编辑回显 | - -内部 Feign 接口（`/internal/mp/order/*`）同步增加字段，BFF 和 order-service 字段完全对齐。 - ---- - -## 四、前端对接建议 - -### 管理端 -- 订单详情页 / 订单列表点详情时，`tierName` 作为「档位」列展示（如「舒适档」） -- 如果 `tierName` 为 `null`（老订单），可展示 `"档位 ${tierSeq}"` 或「默认档」 - -### 小程序 -- 订单详情页主信息区新增「档位」一行 -- 「再次下单 / 复制订单」场景中，`tierSeq` 可用于预选档位 - -### 响应结构示例（以 `GET /mp/order/{orderId}` 为例） - -```json -{ - "code": 0, - "data": { - "orderId": "1234567890", - "orderNo": "HL20260418001", - "productName": "稻城亚丁6日游", - "tierSeq": 2, - "tierName": "舒适档", - "tierDescription": "升级双早+SPA", - "totalAmount": "3999.00", - "createTime": "2026-04-18 12:00:00" - } -} -``` - ---- - -## 五、非变更项 - -- ❌ 不改任何旧字段的类型、名称、含义 -- ❌ 不改请求参数 -- ❌ 不动老 v1 `hl-order-service`（仍在下线流程中） -- ❌ 不改订单表结构（`tier_seq` 列已存在） - ---- - -## 六、测试 - -- 单元测试 71 通过（TierInfoResolver 15 个边界用例 + QueryService +3 + Assembler +4） -- 编译：order-v2 + mp-service 全通过 -- 端到端：测试环境部署后由 QA 实测管理端 / 小程序三条链路 - ---- - -## 七、重启 - -本次变更合并后，测试环境需重启： -- `hl-order-service-v2` -- `hl-mp-service`（BFF 镜像 VO 同步增字段，Feign 反序列化需新 class） - ---- - -## 八、风险 - -- 迁移前老订单的 `productSnapshot` 结构若不同 → `tierName / tierDescription` 返回 `null`（已容错），前端兜底展示 -- 字段顺序：BFF 镜像 `MpOrderDetailVO` 与 order-service 内部 VO 字段一致（「基础信息」段末尾，紧跟 `createTime`） diff --git a/changelogs/2026-04/2026-04-18_product-v2_datascope-permission.md b/changelogs/2026-04/2026-04-18_product-v2_datascope-permission.md deleted file mode 100644 index 18336ad..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_datascope-permission.md +++ /dev/null @@ -1,184 +0,0 @@ -# 产品/产品线数据权限切面 @DataScope - -**合并时间**：2026-04-18 -**PR**：https://git.1814.love:8443/wx/HL/pulls/849 -**Issue**：#839 -**影响范围**：`hl-product-service-v2` 管理端 37 个 `/admin/product/**` 和 `/admin/product/line/**` 接口 -**前端需同步**：✅ 是（VO 新增 canEdit/isOwner + 403/404 语义 + 部分接口响应条数变化） - ---- - -## 一、权限规则（必读） - -### 1.1 CORE 产品 / GROUP 产品（小蒙马） / CORE 产品线 / GROUP 产品线 -- **所有拥有"产品管理"菜单权限的管理员都可查看**列表和详情（不限创建人） -- **只有创建人可操作**（编辑 / 删除 / 上下架 / 复制 / 班期 / 价格日历 / 行程 / 详情区块等所有写接口） -- 非创建人试图调写接口 → `code=403 message="无操作权限"` - -### 1.2 CUSTOM 产品 / CUSTOM 产品线（私人定制） -- **只有创建人可见**（列表返回自动过滤；非创建人按 ID 查详情 → `code=404`） -- **只有创建人可操作** -- 其他管理员（非超管）**完全不知道别人 CUSTOM 产品的存在** - -### 1.3 SUPER_ADMIN（超级管理员） -- **所有产品/产品线都可看、都可操作**（不受 1.1 / 1.2 限制） -- 详情返回里 `canEdit=true`（恒真） -- 但 `isOwner` 仍按真实 created_by 比对（**超管不自动算创建人**） - -### 1.4 未登录 / Token 失效 -- `code=401` 拒绝（即使 Nacos 开关 `hl.data-scope.enabled=false` 关闭切面也拒绝） - -### 1.5 分享 URL（CUSTOM 产品给客户看） -- 走 `/mp/**` → Feign → `/internal/**` 链路，**完全不经过本切面** -- 客户端无 adminId，不受数据权限影响 - ---- - -## 二、响应字段新增（3 个 VO） - -### 2.1 `ProductListRespVO`（列表接口 `GET /admin/product/item/list`） -```json -{ - "productId": 1001, - "productType": "CUSTOM", - "name": "草原深度定制", - "createdBy": 1002, - ... // 其他原有字段 - "canEdit": true, // ← 新增 - "isOwner": true // ← 新增 -} -``` - -### 2.2 `ProductDetailRespVO`（详情接口 `GET /admin/product/item/{id}`） -同 2.1，新增 `canEdit` + `isOwner`。 - -### 2.3 `ProductLineRespVO`（产品线列表 / 详情） -```json -{ - "lineId": 501, - "name": "呼伦贝尔经典", - "productType": "CORE", - "createdBy": 1001, - ... // 其他原有字段 - "canEdit": false, // ← 新增 - "isOwner": false // ← 新增 -} -``` - -### 2.4 字段语义（所有 3 个 VO 都适用） - -| 字段 | 类型 | 语义 | 超管下取值 | -|------|------|------|-----------| -| `canEdit` | Boolean（非 null） | 当前登录管理员是否可编辑该记录 | 恒 `true` | -| `isOwner` | Boolean（非 null） | 当前登录管理员是否为该记录创建人（`created_by == adminId`） | 按真实 `created_by` 判断，不开后门 | - -**前端使用建议**： -- 编辑按钮 / 删除按钮 / 上下架按钮：`v-if="row.canEdit"` 或灰化（`disabled="!row.canEdit"`） -- 展示"我创建的" Tag：`v-if="row.isOwner"` -- **不要**单独用 `isOwner` 判断按钮可用（超管时 `isOwner=false` 但应能操作 → 用 `canEdit` 判断才对） - -### 2.5 不加字段的接口 -- `ProductSimpleListVO`（`GET /admin/product/item/simple-list`）— 下拉用，不返 -- `ProductLineDropdownVO` / simple-list — 下拉用，不返 - ---- - -## 三、错误码 / 响应码变化 - -| 场景 | 之前 | 现在 | -|------|------|------| -| 未带 Token / Token 失效 | 401 | **401**（不变） | -| 非超管按 ID 查他人 CUSTOM 详情 | 200 + 数据 | **404 `"资源不存在或无权限"`** | -| 非超管编辑他人 CORE/GROUP/CUSTOM 任一写操作 | 200（数据被改） | **403 `"无操作权限"`** | -| 非超管列表返回其他定制师的 CUSTOM | 返回 | **不返回**（total 也减少） | - -**前端错误处理建议**： -- 404：统一弹 "资源不存在或无权限，请刷新列表" -- 403：统一弹 "您没有操作此产品的权限" - ---- - -## 四、受影响接口清单（37 个） - -### 4.1 `AdminProductController`（`/admin/product/item/**`）33 个 -- **列表查询**：`GET /list`、`GET /simple-list` -- **详情**：`GET /{id}`、`GET /{id}/price-calendar`、`GET /{id}/schedule/list`、`GET /{id}/schedule/team`、`GET /{id}/suggest-price`、`GET /{id}/supplement`、`GET /{id}/calculate-mileage`、`GET /{id}/detail-blocks`、`GET /{id}/operation-logs`、`GET /{id}/validate-publish`、`GET /{id}/fee-deduction-preview`、`GET /{productId}/tiers` -- **写操作**（行级校验）： - - `PUT /{id}/itinerary`、`POST /{id}/itinerary/day`、`DELETE /{id}/itinerary/day/{dayNumber}` - - `PUT /{id}/route`、`POST /{id}/price-calendar/batch`、`DELETE /{id}/price-calendar` - - `POST /{id}/schedule`、`DELETE /{id}/schedule/{scheduleId}`、`PUT /{id}/schedule`、`POST /{id}/schedule/batch-create`、`POST /{id}/schedule/{scheduleId}/cancel`、`PUT /{id}/schedule/team` - - `POST /{id}/quote`、`PUT /{id}/supplement`、`POST /{id}/daily-mileage` - - `PUT /{id}/detail-blocks`、`POST /{id}/toggle-publish`、`POST /{id}/complete`、`POST /{id}/action`（@Deprecated）、`DELETE /{id}` -- **不加切面，Service 层做权限**： - - `POST /basic`（创建+更新合一，更新分支 Service 层 assertCanWrite） - - `POST /{id}/copy`（Service 层 assertCanRead，允许任何"可见者"复制；R9 规则） - - `PUT /{id}/transfer`（Service 层仅超管可操作） - -### 4.2 `AdminProductLineController`（`/admin/product/line/**`）4 个 -- `GET /list`、`GET /simple-list`（按产品线 product_type 过滤） -- `GET /item/{id}`（ROW_CHECK） -- `DELETE /item/{id}`（ROW_CHECK） -- `POST /item`（创建+更新合一，更新分支 Service 层 assertCanWrite） - ---- - -## 五、服务端配置（运维关注） - -### 5.1 Nacos 灰度开关 -```yaml -# hl-product-service-v2-dev.yml / -prod.yml -hl: - data-scope: - enabled: true # 总开关；false 时切面不过滤（401 校验仍生效） - reject-status: 404 # 越权访问响应码（CUSTOM 不泄露存在性） - log-level: warn # 越权日志级别 -``` - -### 5.2 数据库迁移（上线前 DBA 执行） -```sql --- 1. 补齐 created_by NULL 数据（防 R3 行级校验误伤） -UPDATE product SET created_by=1, updated_by=COALESCE(updated_by, 1) -WHERE created_by IS NULL AND deleted_at IS NULL; - -UPDATE product_line SET created_by=1, updated_by=COALESCE(updated_by, 1) -WHERE created_by IS NULL AND deleted_at IS NULL; - --- 2. 补齐 product_line.product_type NULL 数据 -UPDATE product_line SET product_type='CORE' -WHERE (product_type IS NULL OR product_type='') AND deleted_at IS NULL; - --- 3. 组合索引 -ALTER TABLE product - ADD INDEX idx_type_creator_deleted (product_type, created_by, deleted_at); -ALTER TABLE product_line - ADD INDEX idx_type_creator (product_type, created_by); -``` - -详见 `hl-product-service-v2/src/main/resources/db/migration/V20260418__data_scope_created_by_backfill.sql`。 - ---- - -## 六、部署影响 - -需要**重启 hl-product-service-v2**。其他服务无影响（/mp/**、/internal/**、前端静态资源均未变）。 - ---- - -## 七、设计文档 - -完整需求 / 评审 / 架构 / 测试报告详见 PR 关联的任务文档 `docs/tasks/20260418_设计_产品线与产品数据权限.md`（1600+ 行）。 - ---- - -## 八、本地验证摘录（smoke test 结果） - -| 测试场景 | 预期 | 实际 | -|---------|------|------| -| 超管列表 /item/list | total=7396 全 canEdit=true | ✅ | -| CUSTOMIZER 列表 | total=7394（自动过滤 2 条他人 CUSTOM） | ✅ | -| CUSTOMIZER 查他人 CUSTOM 详情 | code=404 | ✅ | -| CUSTOMIZER 查他人 CORE 详情 | code=200, canEdit=false, isOwner=false | ✅ | -| CUSTOMIZER 删他人 CORE | code=403 | ✅ | -| CUSTOMIZER 删他人 CUSTOM | code=403 | ✅ | -| 超管查 CUSTOM 详情 | code=200, canEdit=true, isOwner=false（超管不开后门） | ✅ | -| 无 Token | code=401 | ✅ | diff --git a/changelogs/2026-04/2026-04-18_product-v2_deposit-mutex-validation.md b/changelogs/2026-04/2026-04-18_product-v2_deposit-mutex-validation.md deleted file mode 100644 index 12889c5..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_deposit-mutex-validation.md +++ /dev/null @@ -1,112 +0,0 @@ -# 产品编辑 订金设置 固定金额/比例 严格互斥 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #819 -> **Issue**: #816 -> **日期**: 2026-04-18 -> **影响范围**: 产品编辑 Step1 基础信息 → 订金设置 - ---- - -## 一、变更说明 - -此前后端未对订金"固定金额"和"比例"做互斥校验，允许两字段同时有值写入数据库；下单报价时按「固定额 > 0 优先」的逻辑处理，导致比例字段在同时有值时永远不生效，产生脏数据。 - -现在后端强制两字段**任意时刻最多只有一个有值**： - -1. 同时提交两个字段（都 > 0）→ 后端 **400 拒绝**，返回提示"订金固定金额与比例互斥，只能填写其中一个" -2. 保存时若 `depositAmount` 有值 → 数据库 `deposit_ratio` 显式置 NULL -3. 保存时若 `depositRatio` 有值 → 数据库 `deposit_amount` 显式置 NULL -4. 两者都为 null（或 0）→ 合法（视为全款模式 PaymentType=FULL） - ---- - -## 二、前端必须配合 - -**切换 tab 时清空对方字段再提交**，否则后端直接拒绝： - -| 前端场景 | 必须提交的 payload | -|---------|-------------------| -| 用户选"固定金额"填 500 | `{ "depositAmount": 500, "depositRatio": null }` | -| 用户从"固定金额"切到"比例"填 10% | `{ "depositAmount": null, "depositRatio": 10 }` | -| 用户选"全款支付"（无订金） | `{ "paymentType": "FULL", "depositAmount": null, "depositRatio": null }` | -| ❌ 错误示例（会被 400） | `{ "depositAmount": 500, "depositRatio": 10 }` | - -**关键点**：切换 tab 时**必须把对方字段在提交前 reset 成 null**，不要只是隐藏输入框。前端 state 里残留另一方的历史值会让后端拒绝。 - ---- - -## 三、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|---------|------| -| 1 | 保存产品基础信息 | POST | `/admin/product-basic/save` | 请求体新增校验 | `depositAmount`/`depositRatio` 不得同时 > 0 | - ---- - -## 四、接口详情 - -### 1. 保存产品基础信息 `POST /admin/product-basic/save` - -**VO**: `ProductBasicSaveReqVO` - -**相关字段**（字段本身没改，**校验行为改了**）： - -| 字段 | 类型 | 必填 | 说明 | 变化 | -|------|------|------|------|------| -| `paymentType` | String | 是 | 支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款 | 无 | -| `depositAmount` | BigDecimal | 否 | 订金固定金额（元/人），与 `depositRatio` **互斥** | 互斥校验 | -| `depositRatio` | Integer | 否 | 订金比例(%)，与 `depositAmount` **互斥** | 互斥校验 | - -**互斥规则**： -- `depositAmount` 和 `depositRatio` 任意时刻最多只有一个 > 0 -- 两者都 null / 都 0 → 合法 -- 其中一个有值，另一个必须为 null 或 0 - -**违反互斥的错误响应**： - -```json -{ - "code": 400, - "message": "depositMutex: 订金固定金额与比例互斥，只能填写其中一个", - "success": false, - "data": null -} -``` - ---- - -## 五、数据库行为 - -保存成功后数据库 `product_basic` 表： - -| 前端提交 | `deposit_amount` 列 | `deposit_ratio` 列 | -|---------|--------------------|--------------------| -| `depositAmount=500, depositRatio=null` | `500.00` | `NULL` | -| `depositAmount=null, depositRatio=10` | `NULL` | `10` | -| 都为 null | `NULL` | `NULL` | - -即使前端不传"对方字段"，后端也会**显式 SET NULL**，不会保留数据库里的历史残留值。 - ---- - -## 六、下单/报价逻辑未变 - -下单报价（`InternalProductService.fillPaymentInfo`）规则保持不变： - -``` -paymentType = 'DEPOSIT' 时： - if depositAmount > 0: 使用固定金额 - else if depositRatio > 0: depositAmount = totalPrice × depositRatio / 100 - else: depositAmount = 0 -``` - -因为现在产品保存阶段已经保证了两字段互斥，下单阶段永远走其中一条分支，不会再出现"两个都有值但比例被忽略"的脏数据场景。 - ---- - -## 七、影响范围 - -- 仅影响**管理后台产品编辑**的订金设置表单 -- 小程序端 C 端算价、订单创建、订单详情等接口**零影响** -- 历史数据（已经同时有两字段值的产品）：后端读取逻辑不变，仍按固定额优先，不会异常。下次编辑保存时才会触发互斥校验 diff --git a/changelogs/2026-04/2026-04-18_product-v2_publish-validation-order-detail-deps.md b/changelogs/2026-04/2026-04-18_product-v2_publish-validation-order-detail-deps.md deleted file mode 100644 index f0129b4..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_publish-validation-order-detail-deps.md +++ /dev/null @@ -1,227 +0,0 @@ -# fix(product-v2): 上架校验补齐订单详情依赖字段(7 类新校验) + 订单详情字段补齐 - -> **服务**: hl-product-service-v2 (端口 8083) + hl-order-service-v2 (端口 8084) -> **PR**: #854 https://git.1814.love:8443/wx/HL/pulls/854 -> **Issue**: #846 -> **Merge commit**: `a77c4505` -> **日期**: 2026-04-18 -> **影响范围**: -> - 管理端【产品上架】预检 + 上架接口(校验规则收紧,可能 400) -> - 小程序【订单详情】弹窗(住宿/用车/餐饮/领队 4 处补齐字段) - ---- - -## 一、背景 - -排查发现产品 v2 上架前校验 `ProductValidationService` 原本只做 11 项基础字段校验,对**订单详情 6 个弹窗(门票/住宿/餐饮/用车/领队/摄影)**所需要的关键字段覆盖不全,导致: -- 产品能上架,但用户下单后订单详情字段空白、统计恒为 0、Feign 返回 404 降级 -- 订金配置不完整,下单时 `depositAmount` 落 null -- GROUP 产品可能没班期或班期无领队,订单详情领队弹窗永远"未分配" - -本 PR 同时修复: -1. **P0x3 + P1x4 = 7 类新增上架校验**(收紧规则,老产品可能上不了架) -2. **订单详情依赖的 Feign 快照字段补齐**(5 项 VO 字段补强 + 1 个 internal 接口新增) - ---- - -## 二、上架校验收紧(P0 + P1 共 7 条) - -### 变更接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | -|---|------|------|------|----------| -| 1 | 上架预检 | GET | `/admin/product/{id}/validate-publish` | 返回 issues 列表新增 7 类错误提示 | -| 2 | 上架/下架切换 | POST | `/admin/product/{id}/toggle-publish` | 上架动作先跑 validatePublish,有 issues 则 400 拒绝 | - -### 新增 7 条校验规则 - -| # | 等级 | 触发条件 | 错误提示文案(示例) | -|---|------|---------|---------------------| -| 1 | P0 | `payment_type=DEPOSIT` 时 `depositAmount>0` 和 `depositRatio∈[1,99]` 都没填 | `订金支付方式(payment_type=DEPOSIT)必须配置订金金额(>0)或订金比例(1-99)` | -| 2 | P0 | `payment_type=DEPOSIT` 时 `balance_due_days` 为 null | `订金支付方式(payment_type=DEPOSIT)必须配置尾款到期天数 balance_due_days` | -| 3 | P0 | 行程节点缺少 `HOTEL` 类型 | `缺少酒店节点，订单详情住宿弹窗将为空` | -| 3 | P0 | 行程节点缺少 `RESTAURANT` 类型 | `缺少餐饮节点，订单详情餐饮弹窗将为空` | -| 3 | P0 | 行程节点 `SCENIC` + `ACTIVITY` 合计 = 0 | `缺少景点/活动节点，订单详情门票/活动弹窗将为空` | -| 4 | P1 | SCENIC 节点 `resourceId` 为 null | `SCENIC 景点节点(nodeId=X 名称=Y)缺少 resourceId，订单门票弹窗将无法显示封面/原价` | -| 5 | P1 | `tripNights ≥ 1` 且 非自理早餐(`breakfast ≠ SELF`)天数占比 < 70% | `餐饮配置不足：行程共 N 晚，至少 M 天早餐应该非自理(SELF)，当前仅 K 天非自理，订单详情'已含早餐数'统计将不准确` | -| 6 | P1 | `product_route_info.vehicle_model_id` 为 null | `路线总览未配置实际用车车型(product_route_info.vehicle_model_id)，订单用车弹窗将无法展示车型信息` | -| 7 | P1 | `product_type=GROUP` 且 `group_tour_batch` 为空 | `GROUP(小蒙马)产品至少需要 1 个班期(group_tour_batch)，否则订单领队弹窗将永远为空` | -| 7 | P1 | `product_type=GROUP` 某班期 `group_batch_staff` 中没有 `staff_role=LEADER` 成员 | `班期(batchNo=X batchId=Y)缺少 LEADER 角色成员，订单详情领队弹窗将显示'未分配'` | - -### 校验接口响应示例 - -**成功(全部通过)**: -```json -{ - "code": 0, - "success": true, - "message": "操作成功", - "data": [] -} -``` - -**失败(上架预检返回多条 issues)**: -```json -{ - "code": 0, - "success": true, - "message": "操作成功", - "data": [ - "订金支付方式(payment_type=DEPOSIT)必须配置订金金额(>0)或订金比例(1-99)", - "缺少酒店节点，订单详情住宿弹窗将为空", - "SCENIC 景点节点(nodeId=1234 名称=额尔古纳湿地)缺少 resourceId，订单门票弹窗将无法显示封面/原价", - "GROUP(小蒙马)产品至少需要 1 个班期(group_tour_batch)，否则订单领队弹窗将永远为空" - ] -} -``` - -**toggle-publish 触发上架失败时**(HTTP 仍 200,`code` 为业务错误码): -```json -{ - "code": 400, - "success": false, - "message": "上架前校验失败：缺少酒店节点...；路线总览未配置实际用车车型...", - "data": null -} -``` - -### 前端必须配合的改动 - -#### 1. 产品编辑页「上架前」先调 `/validate-publish` 给出整改清单 - -原型建议:点"上架"按钮前先 GET `/admin/product/{id}/validate-publish`,拿到 `data: []` 则允许上架,否则展示 issues 清单供运营整改后再试。 - -```js -// 推荐流程 -const res = await GET(`/admin/product/${id}/validate-publish`); -if (res.data.length === 0) { - await POST(`/admin/product/${id}/toggle-publish`, { remark: '...' }); -} else { - // 弹出整改清单,每行是一条中文错误提示 - showIssuesModal(res.data); -} -``` - -#### 2. 展示多条错误 - -`toggle-publish` 失败时后端的 `message` 会把所有 issues 用 `；` 拼接,前端可以按 `；` 切分展示,或者优先用 `validate-publish` 拿结构化列表。 - ---- - -## 三、兼容性风险(前端 + 运营重点关注) - -### 老产品可能上不了架 - -以下情况产品会被拒绝上架,需要运营**先补数据**: - -| 场景 | 解决 | -|------|------| -| 产品只有 NOTE/CUSTOM/TRANSPORT/FREE 节点 | 至少补 1 个 SCENIC/ACTIVITY + 1 个 HOTEL + 1 个 RESTAURANT 节点 | -| 老 DEPOSIT 产品只填了 `depositAmount`/`depositRatio` 没填 `balanceDueDays` | 编辑页补填尾款到期天数 | -| 老 GROUP 产品没建班期 | 至少创建 1 个班期 | -| 老 GROUP 产品班期没绑定领队 | 每个班期至少加 1 个 `staff_role=LEADER` 的成员 | -| 所有行程早餐都是 SELF(自理) | 至少 70% 的天早餐改成非 SELF(如 HOTEL/CAMP/SPECIAL) | -| SCENIC 景点节点只填了名称没关联景区资源 | 编辑节点绑定 `resourceId` | -| 路线总览没选实际车型 | 路线总览页选车型 | - -### 早餐 70% 校验严格度说明 - -- 5 天行程(`tripNights=4`):至少 `⌈4 × 0.7⌉ = 3` 天早餐非 SELF -- 6 天行程(`tripNights=5`):至少 `⌈5 × 0.7⌉ = 4` 天早餐非 SELF -- 7 天行程(`tripNights=6`):至少 `⌈6 × 0.7⌉ = 5` 天早餐非 SELF(只能有 1 天 SELF) - -前端表单要能保存 `SELF/HOTEL/CAMP/SPECIAL` 四种早餐类型,上架校验才能放行。 - -### 已上架产品不会受影响 - -**只有在「上架」动作时(`toggle-publish` 切到 PUBLISHED)才校验**,已经处于上架状态的老产品没动它,下架再上架才会触发。 - ---- - -## 四、订单详情字段补齐(小程序 MP 端) - -### 变更接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 订单详情 | GET | `/mp/order/{orderId}/detail` | 响应字段扩展 | 4 个弹窗 VO 字段补全,数据从产品快照取 | - -具体定位到订单详情 VO 层次: - -#### 1) `MpHotelItemVO`(订单住宿弹窗项)新增字段 - -| 字段 | 类型 | 可空 | 说明 | -|------|------|------|------| -| `hotelType` | String | 是 | 酒店类型(5星/特色民宿/蒙古包等),资源服务降级时可能为 null | - -#### 2) `MpVehicleDetailVO`(订单用车弹窗)新增字段 - -| 字段 | 类型 | 可空 | 说明 | -|------|------|------|------| -| `coverUrl` | String | 是 | 车型封面图 URL(资源服务暂未提供,预留 null) | -| `seatCount` | Integer | 是 | 座位数(来自产品快照 `vehicleModels.seatCount`) | -| `vehicleCategory` | String | 是 | 车辆分类,字典 `vehicle_type`:`CAR`=小轿车 / `SUV`=越野车 / `VAN`=商务车 / `BUS`=大巴 / `MINIBUS`=中巴 | -| `driverYearsRequired` | String | 是 | 驾龄要求(资源服务暂未提供,预留 null) | -| `features` | List\<String\> | 是 | 配置/亮点列表(资源服务暂未提供,预留空数组) | - -#### 3) `MpMealStatsVO.breakfastCount`(订单餐饮统计)行为修复 - -**旧行为**:`breakfastCount` 永远返回 `0`,因为产品 v2 快照没下发 `mealType` 字段,订单 `OrderMealAssignmentService` 无法区分早午晚餐。 - -**新行为**:产品快照补齐 `nodes[].mealType`(`BREAKFAST`/`LUNCH`/`DINNER`) 后,订单端按餐别分桶计数,`breakfastCount` 真实反映"产品内置多少餐早餐"。前端展示文案"已含 N 早"不用改,数值正确即可。 - -#### 4) GROUP 产品订单详情【领队/摄影】弹窗不再永远"未分配" - -**旧行为**:订单服务调 `productFeignClient.getBatchStaff(batchId)` 永远 404,`fallback` 返空 list → 所有 GROUP 订单领队/摄影弹窗显示"未分配"。 - -**新行为**:产品服务新增了 `GET /internal/product/schedule/{batchId}/staff` internal endpoint(详情见后端 changelog),订单服务能拿到真实的班期成员,按 `staffRole` 过滤展示领队/摄影/司机。 - -### 前端展示建议 - -#### 订单住宿弹窗 -原型上要求在酒店名下显示【5 星】【特色民宿】【蒙古包】标签 → 直接用 `hotelType`,为 null 则不展示标签。 - -#### 订单用车弹窗 -原型字段对照: -- "车型名":`vehicleType` -- "座位数":`seatCount`(null → "—") -- "车辆类型":翻译 `vehicleCategory` 字典(null → "—") -- "驾龄要求":`driverYearsRequired`(null → "—"或隐藏) -- "车辆配置":`features`(空数组 → 隐藏) - ---- - -## 五、下单/报价逻辑 - -本 PR **不改下单/报价核心逻辑**,只改: -- 上架阶段收紧校验(卡在 `toggle-publish`) -- 订单详情 `VO` 补字段(从已有产品快照多读几个字段) - -C 端已下单的历史订单,订单详情读的是创建时序列化的 `product_snapshot`,老订单没有新字段,仍会是 null。**仅新下的订单会有完整字段**。 - ---- - -## 六、不受影响的接口 - -- 小程序首页/列表/产品详情:零影响 -- 产品创建/编辑/复制/下架:零影响 -- 产品报价 `/admin/product/item/{id}/quote`:零影响 -- 价格日历 `/admin/product/item/{id}/price-calendar/*`:零影响 - ---- - -## 七、受影响服务 + 重启提示 - -本次需要**同时重启** 2 个服务: -- `hl-product-service-v2`(8083):新增校验 + 新增 internal endpoint -- `hl-order-service-v2`(8084):VO 字段扩展 + Feign 快照反序列化新字段 - -测试环境重启顺序:先 product-service-v2,再 order-service-v2(order 依赖 product 的 internal 接口)。 - ---- - -## 八、相关链接 - -- Issue: https://git.1814.love:8443/wx/HL/issues/846 -- PR: https://git.1814.love:8443/wx/HL/pulls/854 -- Merge commit: `a77c4505` diff --git a/changelogs/2026-04/2026-04-18_product-v2_schedule-max-participants-optional.md b/changelogs/2026-04/2026-04-18_product-v2_schedule-max-participants-optional.md deleted file mode 100644 index 56ea902..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_schedule-max-participants-optional.md +++ /dev/null @@ -1,61 +0,0 @@ -# 班期保存 - 最大参与人数 改为非必填（反转 2026-04-18 上一版 changelog） - -**日期**: 2026-04-18 -**PR**: #865 → 合并到 dev，已部署测试环境 -**Issue**: #862 -**影响端**: 管理后台 Web (hl-ui-admin) -**影响接口**: -- `POST /admin/product/item/{id}/schedule` (Step4 创建班期) -- `PUT /admin/product/item/{id}/schedule` (Step4 修改班期) -- `POST /admin/product/item/{id}/schedule/batch-create` (Step4 班期批量创建) - -## ⚠️ 反转上一版 -本 changelog 反转 `2026-04-18_product-v2_schedule-max-participants-required.md`（PR #861）。产品侧确认：**班期定价页的"最大人数"按用户交互本意就是非必填**（不填=不限）。上一版把 `@NotNull` 补强的方向是错的，本次撤回。 - -## 行为变化 - -| 字段 | 前端是否必填 | 不传时后端行为 | 说明 | -|---|---|---|---| -| `maxParticipants`（最大人数）| **否** | 兜底写 DB 为 `0`（0=不限） | 报名/库存校验对 `0=不限` 不再恒拒 | -| `maxRooms`（最大房间数）| **否，前端不传** | 后端自动取 `product_basic.default_room_count`（每天最少房间数，行程 Step2 自动算好）；无 default 则 0=不限 | 行为无变化，本次明确文档化 | -| `productStockLimit`（库存上限）| **否** | 写 DB `NULL`（不限） | 行为无变化，本次明确文档化 | - -三者前端表单均**不要标红星**，不要做 required 校验。 - -## 请求体示例（最小体） - -```json -POST /admin/product/item/{id}/schedule -{ - "departureDate": "2027-06-01", - "adultPrice": 2999.00, - "childPrice": 1999.00 -} -``` - -上面请求合法返回 200，DB 存 `max_participants=0 / max_rooms=<default_room_count 或 0> / product_stock_limit=NULL`。 - -## 下游接口（/internal/batch-info）联动 - -`InternalProductService.getBatchInfo` 回传字段 `remainingSlots`： -- 当班期 `maxParticipants <= 0`（不限）：`remainingSlots = Integer.MAX_VALUE`（2147483647） -- 否则：`remainingSlots = maxParticipants - enrolledCount` - -下游（订单服务）若展示"剩余名额"，建议判断 `>= Integer.MAX_VALUE` 时显示"不限"而非具体数字。 - -## DB DDL（已在测试环境应用） - -```sql -ALTER TABLE group_tour_batch - MODIFY COLUMN max_participants INT(11) NOT NULL DEFAULT 0 - COMMENT '最大参与人数(0=不限)'; -``` - -## 不影响 - -- 字段名、字段类型不变 -- `ScheduleRespVO` / `MpScheduleRespVO` 返回结构不变 -- 其他字段校验规则不变 -- 订单名额扣减逻辑：`maxParticipants > 0` 时仍按原逻辑控卡 - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-18_product-v2_schedule-max-participants-required.md b/changelogs/2026-04/2026-04-18_product-v2_schedule-max-participants-required.md deleted file mode 100644 index 168ddfa..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_schedule-max-participants-required.md +++ /dev/null @@ -1,36 +0,0 @@ -# 班期保存 - 最大参与人数 强制必填校验 - -**日期**: 2026-04-18 -**PR**: #861 → 合并到 dev -**影响端**: 管理后台 Web (hl-ui-admin) -**影响接口**: -- `POST /admin/product/item/{id}/schedule` (Step4 创建班期) -- `PUT /admin/product/item/{id}/schedule` (Step4 修改班期) -- `POST /admin/product/item/{id}/schedule/batch-create` (Step4 班期批量创建) - -## 背景 - -测试反馈：保存班期时填了价格、班期名、出发日，**没填最大参与人数**，后端报错"数据操作违反约束，请检查输入"——容易让运营误以为是价格问题。 - -根因是 `ScheduleSaveReqVO.maxParticipants` 缺 `@NotNull` 校验，NULL 直接打到 SQL（`group_tour_batch.max_participants` 是 NOT NULL 列），DB 抛异常被全局兜底为模糊消息。 - -## 行为变化 - -| 场景 | 修复前 | 修复后 | -|---|---|---| -| `maxParticipants` 不传或传 null | `{"code":400,"message":"数据操作违反约束，请检查输入"}` | `{"code":400,"message":"最大参与人数不能为空"}` | -| `maxParticipants` 传具体数字 | 200 入库 | 200 入库（无变化） | - -## 前端建议 - -`maxParticipants` 字段在表单上加 **required + 数字校验**，避免提交空值再被后端打回。文档中 `ApiModelProperty(required=true)` 一直存在，本次只是把 runtime 校验补齐。 - -`ScheduleBatchCreateReqVO`（批量创建）同步加了 `@NotNull`，前端表单一致处理。 - -## 不影响 - -- 字段名、字段类型、字段语义不变 -- 其他字段校验规则不变 -- 业务流程（Step4 班期生命周期）不变 - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-18_product-v2_status-name-and-toggle-reason.md b/changelogs/2026-04/2026-04-18_product-v2_status-name-and-toggle-reason.md deleted file mode 100644 index 1ab1637..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_status-name-and-toggle-reason.md +++ /dev/null @@ -1,177 +0,0 @@ -# fix(product-v2): 产品列表状态中文化 + 上下架理由必填 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #821 -> **Issue**: #820 -> **Merge commit**: `adc86652` -> **日期**: 2026-04-18 -> **影响范围**: 管理端产品列表/详情状态展示 + 产品上架/下架接口 - ---- - -## 一、背景 - -本次修复两个 BUG： - -### BUG-1：产品列表状态徽标出现英文 `PENDING_REVIEW` -- 产品版本卡片上，仅 `PENDING_REVIEW` 状态显示英文，其它状态（`PUBLISHED→已上架`、`DRAFT→草稿` 等）显示正常 -- 根因：后端 `ProductListRespVO` / `ProductDetailRespVO` 只返状态 code（例：`PENDING_REVIEW`），前端本地字典遗漏该条目 → 降级显示裸英文 -- 违反项目硬规则「所有展示数据用中文」 - -### BUG-2：产品上架/下架接口缺少"理由"必填校验 -- 旧行为：`POST /admin/product/item/{id}/toggle-publish` 的 `remark` 字段可选，前端不传也能通过 -- 风险：上下架是关键业务操作，没有理由 → 无法追溯审计，`product_operation_log` 里 `detail` 为空 -- 现改为 **必填**，并在后端强制非空校验 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|---------|------| -| 1 | 产品列表 | GET | `/admin/product/item/list` | 响应新增字段 | 新增 `statusName: string`（中文名） | -| 2 | 产品详情 | GET | `/admin/product/item/{id}` | 响应新增字段 | 新增 `statusName: string`（中文名） | -| 3 | 产品上架/下架 | POST | `/admin/product/item/{id}/toggle-publish` | **破坏性变更** | Request body `remark` 由可选改为**必填** | - -> ⚠️ `POST /admin/product/item/{id}/complete`（完成设计）接口**不在本次变更范围**，其 `remark` 字段**仍为可选**，前端无需改动。 - ---- - -## 三、接口详情 - -### 1. 产品列表 `GET /admin/product/item/list` - -响应结构新增 `statusName` 字段： - -```json -{ - "code": 0, - "data": { - "list": [ - { - "id": 1001, - "name": "xxx 亲子游", - "status": "PENDING_REVIEW", - "statusName": "待审核", - "...": "其他字段不变" - } - ], - "total": 10 - } -} -``` - -### 2. 产品详情 `GET /admin/product/item/{id}` - -响应结构新增 `statusName` 字段（用法同上）： - -```json -{ - "code": 0, - "data": { - "id": 1001, - "status": "PUBLISHED", - "statusName": "已上架", - "...": "其他字段不变" - } -} -``` - -### 3. 产品上架/下架 `POST /admin/product/item/{id}/toggle-publish` - -**Request body**： - -```json -{ - "remark": "根据市场部决议下架调整" -} -``` - -| 字段 | 类型 | 必填 | 说明 | 变化 | -|------|------|------|------|------| -| `remark` | String | **是** | 上架/下架理由（非空、非纯空白） | **由可选改为必填** | - -**违反必填的错误响应**： - -- 场景 A：body 完全为空 / 不传 body - -```json -{ - "code": 400, - "message": "请求数据格式错误，请检查参数是否正确" -} -``` - -- 场景 B：`remark` 为空字符串或纯空白 - -```json -{ - "code": 400, - "message": "remark: 上架/下架操作必须填写理由" -} -``` - ---- - -## 四、状态枚举字典对照 - -`status` code 字段**保持不变**，前端仍可用其做逻辑判断。如需展示中文，**推荐直接读 `statusName`**；若坚持本地字典，请确保以下条目齐全： - -| status (code) | statusName (中文) | -|---------------|------------------| -| `DRAFT` | 草稿 | -| `PENDING_REVIEW` | 待审核 | -| `PUBLISHED` | 已上架 | -| `UNPUBLISHED` | 已下架 | -| `REJECTED` | 已驳回 | -| `COMPLETED` | 已完成 | -| `ORDERED` | 已下单 | - ---- - -## 五、前端必须配合 - -### 改动 1：列表/详情展示 - -- **推荐**：展示位直接读 `statusName` -- **或者**：保留本地字典，但必须补齐上表所有 7 个条目（特别是之前漏的 `PENDING_REVIEW`、`UNPUBLISHED`、`REJECTED`、`COMPLETED`、`ORDERED`） -- `status` 字段继续用于前端逻辑判断（按钮 disabled、tab 过滤等），**不要**用 `statusName` 做逻辑 - -### 改动 2：上架/下架弹框 - -- 点击「上架」/「下架」按钮时弹出对话框，包含**必填**的理由输入框（如 `<textarea>`） -- 前端本地校验：空字符串/纯空白禁止提交，给出友好提示 -- 请求 body 结构： - -```json -{ "remark": "用户输入的理由文本" } -``` - -### 兼容性警告 - -- 旧代码如直接调用 `toggle-publish` 不带 body / remark 为空 → 现在会被后端 400 拒绝 -- 请同步检查所有调用 `toggle-publish` 的地方，确保都已加上理由输入 UI - ---- - -## 六、未受影响接口（明确说明） - -- `POST /admin/product/item/{id}/complete`（完成设计）：`remark` **仍可选**，与本次变更无关，**前端无需改动** -- 其他产品管理接口（创建、编辑、删除、审核等）零影响 -- 小程序端接口零影响 - ---- - -## 七、重启提示 - -- **仅需重启** `hl-product-service-v2`（端口 8083） -- 测试环境由服务器管理员通过 Deploy Panel 部署最新 jar -- 本地由 Claude 手动重启 - ---- - -## 八、相关链接 - -- Issue: https://git.1814.love:8443/wx/HL/issues/820 -- PR: https://git.1814.love:8443/wx/HL/pulls/821 -- Merge commit: `adc86652` diff --git a/changelogs/2026-04/2026-04-18_product-v2_step5-merge-team-config.md b/changelogs/2026-04/2026-04-18_product-v2_step5-merge-team-config.md deleted file mode 100644 index db27471..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_step5-merge-team-config.md +++ /dev/null @@ -1,115 +0,0 @@ -# 第5步补充信息保存接口 - 融合「团队配置」，下线独立班期团队保存接口 - -**日期**: 2026-04-18 -**PR**: #873 → 已合并到 dev，待部署测试环境 -**Issue**: #871 -**影响端**: 管理后台 Web (hl-ui-admin) -**影响接口**: -- `PUT /admin/product/item/{id}/supplement` — 新增 `scheduleTeams` 字段 -- `PUT /admin/product/item/{id}/schedule/team` — **下线**（删除 PUT 方法；GET 同路径仍保留做团队查询） - -## 背景 - -产品编辑第5步「团队与须知」页面左侧菜单新增「团队配置」，按班期（第1期…第N期）tab 切换，每个班期维护一组团队成员（领队/司机/摄影师等）。 - -此前页面保存需要并发触发两个请求： -- 第5步补充信息 → `PUT /admin/product/item/{id}/supplement` -- 每个班期的团队成员 → `PUT /admin/product/item/{id}/schedule/team` - -本次改造将班期团队保存融合进第5步补充信息接口，**前端一次请求**即可保存整个第5步。 - -## 接口变化 - -### 1. `PUT /admin/product/item/{id}/supplement` 请求体新增字段 - -新增顶级字段 `scheduleTeams: List<ScheduleTeamItem>`，每项结构： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `batchId` | Long | 是 | 班期ID（需属于当前产品，否则报"班期不属于该产品"） | -| `members` | List<StaffItem> | 否 | 团队成员列表；**空数组 `[]` = 清空该班期团队** | - -`StaffItem` 结构与旧 `PUT /schedule/team` 请求体中的 `staffList` 项完全一致： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `staffId` | Long | 员工ID（可选） | -| `staffRole` | String | 员工角色：LEADER=领队, PHOTOGRAPHER=摄影师, DRIVER=司机, OTHER=其他 | -| `staffName` | String | 员工名称 | -| `staffPhone` | String | 员工电话 | -| `remark` | String | 备注 | -| `sortOrder` | Integer | 排序 | - -### 2. `PUT /admin/product/item/{id}/schedule/team` 下线 - -Controller 方法 `saveScheduleTeam` 已删除，发送 `PUT` 请求到此路径会得到 Spring `HttpRequestMethodNotSupportedException`（项目统一包装成 `{code:500, message:"服务器内部错误"}`；HTTP 仍返 200）。 - -**前端请删除对该接口的所有调用**，改为在第5步整体保存时通过 `scheduleTeams` 字段一并提交。 - -### 3. `GET /admin/product/item/{id}/schedule/team?batchId=xxx` 保留 - -团队查询接口保持不变。第5步页面打开时仍按班期拉取现有团队成员用于渲染。 - -## 空值语义（重要） - -| `scheduleTeams` 取值 | 后端行为 | -|---|---| -| `null`（字段不传）| 不修改任何班期的团队（用于前端分步保存草稿场景） | -| `[]`（空数组）| 不修改任何班期的团队 | -| `[{batchId:1, members:[...]}]` | 仅全量替换 `batchId=1` 的团队成员（全删全插） | -| `[{batchId:1, members:[]}]` | 清空 `batchId=1` 的团队成员 | -| `[{batchId:1,...}, {batchId:2,...}]` | 按班期逐个全删全插 | - -## 请求体示例 - -```json -PUT /admin/product/item/2044306857534636034/supplement -Content-Type: application/json - -{ - "includedFees": [...], - "excludedFees": [...], - "customFees": [...], - "childTicket": "FREE", - "insuranceNotice": "INCLUDED", - "refundPolicyId": 1001, - "scheduleTeams": [ - { - "batchId": 9001, - "members": [ - { "staffName": "张领队", "staffRole": "LEADER", "staffPhone": "13800000000", "sortOrder": 1 }, - { "staffName": "李司机", "staffRole": "DRIVER", "staffPhone": "13900000000", "sortOrder": 2 } - ] - }, - { - "batchId": 9002, - "members": [] - } - ] -} -``` - -上例： -- `batchId=9001` 的团队全量替换为 2 名成员 -- `batchId=9002` 的团队清空 -- 未出现在 `scheduleTeams` 里的其他班期团队不受影响 - -## 事务语义 - -第5步的费用 / 人群优惠 / 补充配置 / 所有班期团队**共用同一数据库事务**。任何一个班期保存失败（例如 `batchId` 不属于当前产品），整个第5步保存全部回滚——不会出现"补充信息保存成功但某些班期团队没写入"的中间状态。 - -## 前端迁移清单 - -- [ ] 移除所有 `PUT /admin/product/item/{id}/schedule/team` 的调用 -- [ ] 第5步保存时把各班期的团队成员列表聚合到 `scheduleTeams` 数组里一并提交 -- [ ] 团队查询（`GET /schedule/team`）保持原样调用 -- [ ] 错误提示注意：跨产品 batchId 会报"班期不属于该产品"，产品草稿状态错误会报既有的"产品不可编辑" - -## 不影响 - -- 第5步其他字段（费用 / 人群优惠 / 车辆 / 保险 / 须知 / 卖点 / 营销内容）结构完全不变 -- 团队成员表 `group_batch_staff` 结构不变 -- DB 无 DDL 变更 -- `GroupBatchStaffRespVO`、内部 Feign 接口不变（订单服务读取团队成员的接口不受影响） - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-18_product-v2_toddler-discount-normalize-and-tierseq-hardening.md b/changelogs/2026-04/2026-04-18_product-v2_toddler-discount-normalize-and-tierseq-hardening.md deleted file mode 100644 index fe47f49..0000000 --- a/changelogs/2026-04/2026-04-18_product-v2_toddler-discount-normalize-and-tierseq-hardening.md +++ /dev/null @@ -1,194 +0,0 @@ -# fix(product-v2): 小童优惠0归一化null + 价格日历tierSeq拆箱加固 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #827 -> **Issue**: #826 -> **Merge commit**: `d9d808cf7594` -> **日期**: 2026-04-18 -> **影响范围**: 管理端产品价格日历（批量保存/按月查询）+ 报价计算 - ---- - -## 一、背景 - -本次处理两类问题： - -### BUG-3：小童优惠（toddlerDiscount）保存为 0 的语义歧义 -- 现象：前端表单 `toddlerDiscount` 字段初始绑定为 `0`，用户不填也会传 `0`，后端照实存成 `0.00` -- 语义问题：`0` 有两种解读 ——「0 元优惠（就是没优惠）」 vs 「没设置优惠（未填）」，容易让后台回显/审核人员误会 -- 根因实证：后端本身对 null 和 0 的处理是正确的（DB 允许 NULL，查询按实际值回显），问题发生在前端默认值 -- **本次决策（方案 A）**：后端兜底归一化，`toddlerDiscount=0` 入库时自动转成 `NULL` -- `infantPrice=0` **不做归一化**，因为「幼童价=0」=「幼童免费」是合法业务语义，不能误伤 - -### NPE 加固：Integer tierSeq 拆箱风险 -- 分析员代码走查发现两处 `Integer == int` 自动拆箱点： - - `ProductPricingService.calculateQuote`（L473）：若某条 `product_price_calendar.tier_seq` 为 NULL，报价会直接 500 NPE - - `PriceCalendarAggregator`（L81）：原有 `!= null` 守卫实际拆箱安全，但为一致性一并改写 -- 改用 `java.util.Objects.equals(a, b)` 规避拆箱 - -### BUG-4（暂挂）：前端报告「小蒙马设计价格日历 500」 -- 测试环境实证：两个 GROUP 产品（`2044306857534636034`、`2043696114145644545`）的价格日历/报价/班期相关全部接口均 200 -- 历史服务日志已滚动丢失，无法追溯原始 500 堆栈 -- 本次先部署 NPE 加固，降低再次出现拆箱 500 的概率；若复现可抓新堆栈再精准定位 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|---------|------| -| 1 | 批量保存价格日历 | POST | `/admin/product/item/{id}/price-calendar/batch` | 入库逻辑变更 | `toddlerDiscount=0` 后端自动归一化为 `NULL`；`infantPrice=0` 保留不变 | -| 2 | 按月查询价格日历 | GET | `/admin/product/item/{id}/price-calendar?month=YYYY-MM&tierSeq=X` | 回显值可能变化 | 原存 `0` 的 `toddlerDiscount` 本次保存后回显为 `null`（未动存量） | - -> 报价接口 `POST /admin/product/item/{id}/quote` 和建议价 `GET /admin/product/item/{id}/suggest-price` 路由不变、入参出参不变，仅内部加固了 tierSeq 拆箱。 - ---- - -## 三、接口详情 - -### 1. 批量保存价格日历 `POST /admin/product/item/{id}/price-calendar/batch` - -**请求 body 字段未变**（本次只改后端落库逻辑）： - -| 字段 | 类型 | 必填 | 说明 | 本次行为变化 | -|------|------|------|------|-------------| -| `toddlerDiscount` | BigDecimal | 否 | 小童优惠额（元/人） | ⚠️ 传 `0` 后端自动转 `NULL` 入库；传正数/负数保持 | -| `infantPrice` | BigDecimal | 否 | 幼童价（元/人） | 无变化，`0` 保持 `0`（=免费） | -| 其他字段 | - | - | - | 无变化 | - -**落库行为对照表**： - -| 前端传入 | DB `toddler_discount` 列 | DB `infant_price` 列 | -|---------|--------------------------|----------------------| -| `toddlerDiscount=0, infantPrice=0` | `NULL` ✅ | `0.00` ✅ | -| `toddlerDiscount=50, infantPrice=100` | `50.00` | `100.00` | -| 两字段都不传 | `NULL` | `NULL` | -| `toddlerDiscount=-500` | `-500.00`（不动负数） | - | - -### 2. 按月查询价格日历 `GET /admin/product/item/{id}/price-calendar` - -响应结构未变，仅 `toddlerDiscount` 字段可能为 `null`： - -```json -{ - "code": 0, - "data": [ - { - "priceDate": "2026-06-01", - "tierSeq": 1, - "adultSellPrice": 1500.00, - "childSellPrice": 1200.00, - "infantPrice": 0.00, - "toddlerDiscount": null - } - ] -} -``` - ---- - -## 四、前端影响与必须配合 - -### 影响 1：`toddlerDiscount` 回读值可能从 `0` 变成 `null` - -如果前端当前代码这样用： - -```js -// ❌ 旧写法（只判 0） -if (form.toddlerDiscount === 0) { /* 视为未设置 */ } - -// ❌ 旧写法（只判 null） -if (form.toddlerDiscount == null) { /* 视为未设置 */ } -``` - -请改为： - -```js -// ✅ 推荐：两者都视为"未设置/0 优惠" -if (form.toddlerDiscount == null || form.toddlerDiscount === 0) { - // 显示为空输入框 / 文案"未设置优惠" -} -``` - -**语义上 null 和 0 都表示「不减免」，对报价计算（后端 `calculateQuote` 已 `!= null ? x : ZERO` 兜底）零影响**。前端只需保证展示和编辑回填不出 bug。 - -### 影响 2：`infantPrice` 无变化 - -- `infantPrice=0` 合法且保留（= 幼童免费） -- 前端逻辑沿用原有判断，**不要**跟着 `toddlerDiscount` 一起归一化 - -### 影响 3：根治建议（可选） - -建议前端同步修复表单默认值：`toddlerDiscount` 初始值由 `0` 改为 `null/undefined`，避免"未填"被序列化成 `0`。后端归一化已做兜底，前端改不改都能用。 - ---- - -## 五、NPE 加固说明 - -### 加固点 1：`ProductPricingService.calculateQuote` - -原代码（存在拆箱 NPE）： - -```java -int tierSeq = req.getTierSeq() != null ? req.getTierSeq() : ProductConstants.DEFAULT_TIER_SEQ; -// ↓ p.getTierSeq() 为 null 时自动拆箱 → NullPointerException -.filter(p -> p.getTierSeq() == tierSeq) -``` - -现代码： - -```java -Integer tierSeq = req.getTierSeq() != null ? req.getTierSeq() : ProductConstants.DEFAULT_TIER_SEQ; -.filter(p -> Objects.equals(p.getTierSeq(), tierSeq)) -``` - -**影响**：若 DB `product_price_calendar.tier_seq` 历史脏数据有 `NULL` 行，过去调用 `POST /admin/product/item/{id}/quote` 会 500 NPE；**现在改为正常业务异常 `NotFoundException`（查不到对应档位价格）**，HTTP 仍返 200，`Result.code` 为业务错误码。 - -### 加固点 2：`PriceCalendarAggregator` - -原代码有 `!= null` 守卫，拆箱实际安全，但为一致性改写成 `Objects.equals`，降低后续维护误改风险。 - ---- - -## 六、BUG-4 仍在排查（前端请补充信息） - -前端同事反馈的「小蒙马设计价格日历 500」本次**未能在测试环境复现**： - -- 两个 GROUP 产品全部相关接口实测 200 -- 历史日志已丢失，无法还原原始堆栈 - -**请前端同事补充以下信息，才能精准定位**： - -1. **完整接口 URL + HTTP method**（例如 `POST /admin/product/item/123/price-calendar/batch`） -2. **产品 ID** -3. **操作步骤**：「设计价格日历」具体在编辑页第几步、点了哪个按钮、是否涉及档位切换/班期绑定 -4. **请求 payload**（从浏览器 DevTools Network 复制 Request body） -5. **响应 body**（如能截到 500 的完整响应） - -本次部署已经加固 2 处可能的 NPE 拆箱点，如果再次复现 500，可以从新日志抓到更清晰的堆栈，再做针对性修复。 - ---- - -## 七、未受影响接口（明确说明） - -- 产品创建/编辑/审核/上架下架（`/admin/product-basic/*`、`/admin/product/item/{id}/toggle-publish` 等）：零影响 -- 报价接口 `POST /admin/product/item/{id}/quote`：路由/入参/出参不变，仅内部 NPE 加固 -- 建议价 `GET /admin/product/item/{id}/suggest-price`：零影响 -- 班期管理 `/admin/product/item/{id}/schedule/*`：零影响 -- 小程序端全部接口：零影响 - ---- - -## 八、受影响服务 + 重启提示 - -- **仅需重启** `hl-product-service-v2`（端口 8083） -- 测试环境已通过 Deploy Panel 完成部署（commit `d9d808cf7594`） -- 正式环境尚未部署 - ---- - -## 九、相关链接 - -- Issue: https://git.1814.love:8443/wx/HL/issues/826 -- PR: https://git.1814.love:8443/wx/HL/pulls/827 -- Merge commit: `d9d808cf7594` diff --git a/changelogs/2026-04/2026-04-18_review_featured-cache.md b/changelogs/2026-04/2026-04-18_review_featured-cache.md deleted file mode 100644 index fbaa7a9..0000000 --- a/changelogs/2026-04/2026-04-18_review_featured-cache.md +++ /dev/null @@ -1,48 +0,0 @@ -# /mp/review/featured 精选评价接口加 Redis 缓存 - -**日期**: 2026-04-18 -**PR**: #869 → 合并到 dev,已部署测试环境 -**Issue**: #867 -**影响端**: 小程序 (hl-ui-mp) -**影响接口**: -- `GET /mp/review/featured?limit=N` (公开,精选评价列表) - -## 行为变化(对前端透明) - -接口响应速度提升:首次请求查库后写缓存,后续 10 分钟内直接命中 Redis。前端无需任何改动。 - -- **首次请求**:查库 + 写缓存,响应时间与原先一致 -- **二次请求**:Redis 命中,响应时间显著下降(预计 <50ms) -- **审核后**:管理员 approve / reject / overrideApprove 任一操作后,精选评价缓存立即失效(事务 afterCommit),下次请求重新落库 - -## limit 参数归一化 - -为防止恶意遍历 limit 撑爆缓存 key,MP 层对 limit 做了归一: - -| 传入 | 归一后 | 说明 | -|---|---|---| -| null / 不传 | 5 | 默认值 | -| <= 0 | 5 | 非法回落 | -| 1~20 | 原值 | 正常区间 | -| > 20 | 5 | 超出回落 | - -**前端注意**:常用 limit 建议固定为 `5` 或 `10`,避免在 URL 中频繁变动 limit 造成缓存穿透。 - -## 不影响 - -- 返回字段、响应结构、排序规则完全不变 -- `MpReviewVO` 字段不变 -- 其他 `/mp/review/**` 接口不变 - -## 实现要点(供前端参考排障) - -- Redis Key: `review:featured:limit:{limit}`(仅 limit 为 key 一部分,其他参数不参与缓存) -- TTL: 600s ± 60s 随机抖动;空结果 60s -- 失效触发: `POST /admin/review/{id}/approve` / `.../reject` / `.../override-approve` 审核完成后清缓存 - -## 已知未修项(另开工单) - -1. MP 层 `@MpCache` aspect 泛型反序列化 bug(影响全站,需单独排查) -2. DB `order_review` 表 `rating_avg` 复合索引优化(DDL 级) - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-19_banner-cache-evict-fix.md b/changelogs/2026-04/2026-04-19_banner-cache-evict-fix.md deleted file mode 100644 index c0b1293..0000000 --- a/changelogs/2026-04/2026-04-19_banner-cache-evict-fix.md +++ /dev/null @@ -1,72 +0,0 @@ -# fix(user,mp): 轮播图修改后小程序立即生效（修缓存不清导致最长 30min 延迟） - -> **服务**: hl-user-service + hl-mp-service -> **PR**: #891 -> **Issue**: #888 -> **Merge commit**: 已合并到 dev -> **日期**: 2026-04-19 -> **影响范围**: 管理端修改轮播图后小程序实时性 -> **前端是否需要改动**: **无需改动**（后端行为修复，前端原调用继续工作且立即可见新数据） - ---- - -## 一、背景 - -管理端 `PUT /admin/banner/{id}` 修改轮播图保存成功后，小程序端 `GET /mp/banner/active` 仍返回旧数据，最长 30 分钟才自动更新。 - -**前端影响**：如果之前前端有以下 workaround，**现在可以移除**： -- 强制刷新页面、二次请求、轮询轮播图接口 -- "保存后等一会儿"的用户提示 - ---- - -## 二、变更接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | 前端改动 | -|---|------|------|------|---------|---------| -| 1 | 新建/修改/删除轮播图 | POST/PUT/DELETE | `/admin/banner` `/admin/banner/{id}` | **行为修复**：保存立即生效 | 无需 | -| 2 | 小程序轮播图列表 | GET | `/mp/banner/active` | 缓存 TTL 由 30min 降到 5min | 无需 | - -两个接口的请求/响应结构**完全不变**。 - ---- - -## 三、修复说明 - -两层原因叠加导致 bug： - -1. **代码层**：`BannerService.create/update/delete` 在 `@Transactional` 事务体内调用缓存清理，事务提交前存在时间窗口，并发读请求把旧数据写回 `mp:banner:active` 开启新 30min TTL -2. **配置层**：测试环境 Nacos 把 `hl-mp-service-test.yml` 的 `redis.database` 配成 `1`，而 user/resource 服务未显式配置（默认 DB 0），跨 DB 导致 `MpCacheEvict` 一直清不到 mp 缓存 - -**已修**： -- 代码：evict 移到 `TransactionSynchronization.afterCommit()` 回调；TTL 30min → 5min（兜底） -- 配置：Nacos `hl-mp-service-test.yml` 的 `redis.database: 1` 改为 `0`，与其他服务对齐 - ---- - -## 四、前端行动项 - -**无需任何改动**。清理历史 workaround 的列表： - -| 可移除的 workaround | 原因 | -|--------------------|------| -| 保存轮播图后调用 `refresh()` / 延迟 2 秒重拉 | 后端已立即清缓存 | -| 本地存储一份"乐观更新"轮播图 | 不再必要 | -| "请稍后刷新"类 toast 提示 | 可改为"保存成功" | - ---- - -## 五、测试环境已验证 - -端到端实测（2026-04-19 01:35）： - -```bash -# 步骤 1：PUT banner/5 title="嗨冰雪" → code=200 -# 步骤 2：GET /mp/banner/active → "嗨冰雪" ✓ -# 步骤 3：PUT banner/5 title="嗨冰雪(V2验证)" → code=200 -# 步骤 4：GET /mp/banner/active → "嗨冰雪(V2验证)" ✓ 立即生效 -# 步骤 5：PUT 回滚 title="嗨冰雪" → code=200 -# 步骤 6：GET /mp/banner/active → "嗨冰雪" ✓ -``` - -后端团队下一步计划：同类"事务内清缓存 + 跨 DB"隐患还存在于 SysDict/FrontendConfig/Hotel/Activity/Scenic/Restaurant 6 个 Service，将以批量 PR 统一抽 `CacheEvictAfterCommit` 公共工具类解决。前端同样**无需改动**。 diff --git a/changelogs/2026-04/2026-04-19_cache-evict-all-admin-interfaces.md b/changelogs/2026-04/2026-04-19_cache-evict-all-admin-interfaces.md deleted file mode 100644 index 8e6be77..0000000 --- a/changelogs/2026-04/2026-04-19_cache-evict-all-admin-interfaces.md +++ /dev/null @@ -1,64 +0,0 @@ -# refactor: 字典/配置/酒店/活动/景点/餐厅等管理端修改后小程序立即生效 - -> **服务**: hl-user-service + hl-resource-service + hl-mp-service -> **PR**: #894 + #896 -> **Issue**: #892 + #893 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **无需改动**（后端行为修复，原调用继续工作且立即可见新数据） - ---- - -## 一、背景 - -继 PR #891 修好轮播图缓存问题后，排查发现项目内还有 6 个 Service 存在相同反模式。本次批量修复让以下对外接口都支持"管理端修改立即生效"： - -- `/admin/dict/type/*`、`/admin/dict/data/*` → `/mp/dict/*` -- `/admin/frontend-config/*` → `/mp/config/*` -- `/admin/hotel/*` → `/mp/hotel/*` -- `/admin/activity/*` → `/mp/activity/*` -- `/admin/scenic/*` → `/mp/scenic/*` -- `/admin/restaurant/*` → `/mp/restaurant/*` - -**前端可清理的历史 workaround**： -- 保存后刷新页面 / 二次请求 / 延迟拉取 -- 本地"乐观更新"对应数据 -- "请稍后刷新"类 toast 提示 - ---- - -## 二、变更接口清单 - -| # | 接口组 | 变更类型 | 前端改动 | -|---|-------|---------|---------| -| 1 | `/admin/dict/type/*` 、 `/admin/dict/data/*` CUD | 行为修复：保存立即生效 | 无需 | -| 2 | `/mp/dict/*` | 缓存 TTL 30min → 5min | 无需 | -| 3 | `/admin/frontend-config/*` CUD | 行为修复：保存立即生效 | 无需 | -| 4 | `/mp/config/*` | 缓存 TTL 30min → 5min | 无需 | -| 5 | `/admin/hotel/*`、`/admin/activity/*`、`/admin/scenic/*`、`/admin/restaurant/*` CUD 及批量操作 | 行为修复：保存立即生效；**原本批量操作漏清缓存的 bug 也修复** | 无需 | -| 6 | `/mp/hotel/*`、`/mp/activity/*`、`/mp/scenic/*`、`/mp/restaurant/*` | 无变化（TTL 已合理） | 无需 | - -**请求/响应结构完全不变**。 - ---- - -## 三、修复说明 - -1. 抽公共工具 `CacheEvictAfterCommit`，把缓存清理统一推迟到事务提交后 -2. 6 个 Service 所有写方法改用这个工具 -3. Dict/Config 过长的读端 TTL 从 30 分钟降到 5 分钟（兜底） -4. 顺带修复 resource 4 个 Service 的 `batchUpdateStatus/batchDelete` 原本**根本没清缓存**的 bug - -## 四、前端行动项 - -**无需任何代码改动**。可评估清理以下历史 workaround： - -| 可移除的 workaround | 原因 | -|--------------------|------| -| 字典列表保存后手动刷新 | 缓存立即失效 | -| 配置改完调 `refresh()` 二次拉取 | 同上 | -| 酒店/活动/景点/餐厅列表保存后 setTimeout 重拉 | 同上 | -| "请稍后刷新"类 toast | 可改为"保存成功" | - -## 五、测试环境已验证 - -改 banner title → MP `/mp/banner/active` 立即返回新值（同一 pattern，其他 Service 沿用）。 diff --git a/changelogs/2026-04/2026-04-19_early-bird-plan-product-unique.md b/changelogs/2026-04/2026-04-19_early-bird-plan-product-unique.md deleted file mode 100644 index fe27cb5..0000000 --- a/changelogs/2026-04/2026-04-19_early-bird-plan-product-unique.md +++ /dev/null @@ -1,81 +0,0 @@ -# refactor: 早鸟计划保存强制"一产品一早鸟"唯一约束 - -> **服务**: hl-order-service-v2 -> **PR**: #929 -> **Issue**: #917 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **建议改动错误展示**（新增约束冲突错误，需前端友好展示） - ---- - -## 一、背景 - -一个产品同时只能绑定一个早鸟优惠计划（业务规则）。之前 DB 无唯一约束，Service 也不校验，运营可重复绑定同一产品到多个计划，导致 `matchPlan` 命中不确定。 - -本次从 **Service 层 + DB 索引** 两道防线强制约束。 - -## 二、变更接口 - -| 方法 | 路径 | 变更类型 | -|------|------|---------| -| POST | `/admin/order/early-bird` | 新增业务约束校验 | -| PUT | `/admin/order/early-bird/{id}` | 同上 | - -## 三、新增约束行为 - -**保存前校验**：请求体 `productIds` 中任意产品已被其他早鸟计划绑定 → 直接返回 `code=500` + 明细消息（`BusinessException`，HTTP 200 + body.code=500）。 - -编辑时会自动排除当前计划 ID，即编辑同一计划仍使用原产品不算冲突。 - -## 四、错误响应示例 - -### 冲突场景 - -```json -POST /admin/order/early-bird -{ - "planName": "五一早鸟", - "discountAmount": 100.00, - "minPeople": 2, - "startDate": "2026-05-01", - "endDate": "2026-05-15", - "productIds": [2045345825172639746, 2045345825172639747] -} - -// 响应（产品 2045345825172639746 已被其他计划绑定） -{ - "code": 500, - "message": "以下产品已绑定其他早鸟计划，不能重复绑定：游牧的森林-短途版(产品ID=2045345825172639746, 已关联计划ID=2045586012523864065)", - "data": null, - "success": false -} -``` - -- 多个冲突会用 `; ` 分隔列出 -- 消息含产品名（Feign 失败时退化为 "产品[ID]" 占位）+ 产品 ID + 占用的计划 ID - -### 编辑同一计划的产品（不算冲突） - -```json -PUT /admin/order/early-bird/2045586012523864065 -{ - "planName": "默认早鸟优惠", - "productIds": [2045345825172639746] // 同一计划原本就绑的产品 -} -// 响应: 200 OK -``` - -## 五、前端改动建议 - -1. **错误提示展示**：后端返回的错误消息已自带产品名/ID/冲突计划 ID，前端直接用 `message` 字段展示即可 -2. **可选优化**：前端在选择 "适用产品" 时，可先调 `GET /admin/order/early-bird` 列表接口收集已占用的产品 ID，在下拉框禁用或标灰提示"已被计划 XX 占用" -3. **编辑时**：保持原绑定的产品不算冲突，前端无需特殊处理 - -## 六、兼容性 - -- 之前一个产品绑多个计划的脏数据在生产环境由运维按 `sql/migrations/20260419_917_early_bird_product_unique.sql` 清洗（默认保留最早一条） -- 本地 / 测试环境已完成 DDL 迁移，本地 DB 若存在重复数据请运行脚本中【审计】+【清洗】SQL 后再拉代码 - -## 七、关联 - -- 后端 changelog: `2026-04-19_early-bird-product-unique-ddl.md`（含 DDL 迁移细节） diff --git a/changelogs/2026-04/2026-04-19_early-bird-vo-align.md b/changelogs/2026-04/2026-04-19_early-bird-vo-align.md deleted file mode 100644 index 1025e7c..0000000 --- a/changelogs/2026-04/2026-04-19_early-bird-vo-align.md +++ /dev/null @@ -1,69 +0,0 @@ -# fix(order-v2): 早鸟优惠接口字段名对齐前端（保存不再报"不能为空"） - -> **服务**: hl-order-service-v2 -> **PR**: #911 -> **Issue**: #910 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **无需改动**（后端 VO 字段名已对齐前端现有调用） - ---- - -## 现象 -早鸟优惠计划管理页（`/order/early-bird`）新增/编辑计划填完所有字段点提交，后端报： -``` -name: 计划名称不能为空; discountPerPerson: 优惠金额不能为空 -``` - -## 根因 -后端 VO 字段名和前端、Entity、DB 列三方都不一致： - -| UI 标签 | 前端字段 | 旧后端 VO | Entity/DB | -|--------|---------|-----------|-----------| -| 计划名称 | `planName` | `name` ❌ | `plan_name` | -| 优惠金额 | `discountAmount` | `discountPerPerson` ❌ | `discount_amount` | -| 备注 | `remark` | `description` ❌ | `remark` | - -**只有后端 VO 是"异类"**，前端、Entity、DB 都用 `planName/discountAmount/remark`。 - -## 修复 - -### 受影响接口（请求/响应结构变化） - -| 方法 | 路径 | 变更 | -|------|------|------| -| POST | `/admin/order/early-bird` | Request body 字段改名 | -| PUT | `/admin/order/early-bird/{id}` | 同上 | -| GET | `/admin/order/early-bird/{id}` | Response body 字段改名 | -| GET | `/admin/order/early-bird` | Response records 字段改名 | - -### 字段映射 - -| 旧字段（已废弃）| 新字段（正在用） | -|---------------|----------------| -| `name` | `planName` | -| `discountPerPerson` | `discountAmount` | -| `description` | `remark` | -| `productType`（Request+Response） | **已删除**（0 调用僵尸字段） | - -## 前端行动项 - -**无需改动**。前端本来就传 `planName/discountAmount/remark`（后端之前用错字段名才导致 bug）。 - -## 测试环境验证 - -```bash -POST /admin/order/early-bird -body: {"planName":"默认早鸟优惠","discountAmount":100.00,"minPeople":1,"startDate":"2026-04-01","endDate":"2026-05-31","remark":"测试"} - -响应: -{"code":200,"data":{"planId":"...","planName":"默认早鸟优惠","discountAmount":100.0,"remark":"测试",...}} -``` - -反向验证（不传 planName）： -``` -错误消息: "planName: 计划名称不能为空"（字段名正确反映前端字段） -``` - -## 相关 - -- 后续跟进：列表接口 `GET /admin/order/early-bird` 有一个独立的 400 问题（Issue 已建，与本 PR 无关） diff --git a/changelogs/2026-04/2026-04-19_earlybird-product-names-echo.md b/changelogs/2026-04/2026-04-19_earlybird-product-names-echo.md deleted file mode 100644 index 1341b34..0000000 --- a/changelogs/2026-04/2026-04-19_earlybird-product-names-echo.md +++ /dev/null @@ -1,86 +0,0 @@ -# fix: 早鸟计划接口 VO 加 productNames / products 字段（解决列表显示"全部产品"、编辑页显示 ID 问题） - -> **服务**: hl-order-service-v2 -> **PR**: #925 -> **Issue**: #916 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **无需改动**（前端代码本来就期望这两个字段，之前是后端未返回导致 fallback） - ---- - -## 一、背景 - -管理端早鸟计划页面之前存在两个 bug： -- **列表页**"适用产品"列显示"全部产品"（误导，实际已绑产品） -- **编辑弹窗**"适用产品"tag 显示产品 ID（如 `2045345825172639746`） - -根因：后端 `EarlyBirdPlanVO` 只返 `productIds: List<Long>` 不带产品名，前端拿不到名字做 fallback。 - -## 二、变更接口 - -所有返回 `EarlyBirdPlanVO` 的接口均受益： - -| 方法 | 路径 | 变更类型 | -|------|------|---------| -| GET | `/admin/order/early-bird/{id}` | 响应新增字段 | -| POST | `/admin/order/early-bird` | 同上 | -| PUT | `/admin/order/early-bird/{id}` | 同上 | -| GET | `/admin/order/early-bird` (列表/分页) | 响应 records 新增字段 | - -（其他如 `/admin/order/early-bird/{id}/validate` `/match` 等同样收益） - -## 三、新增字段 - -```json -{ - "planId": "2045586012523864065", - "planName": "默认早鸟优惠", - "discountAmount": 100.00, - "minPeople": 1, - "productIds": ["2045345825172639746"], - "productNames": ["游牧的森林-短途版"], // ← 新增，列表列用 - "products": [ // ← 新增，编辑弹窗 tag 用 - {"productId": "2045345825172639746", "name": "游牧的森林-短途版"} - ] -} -``` - -字段约定： -- `productNames` 与 `productIds` **下标对齐** -- 产品被删除时，对应位置填 `"产品[ID]已删除"`（而非 "全部产品" 误导） -- Feign 查失败时，全部填占位字符串 -- 空的 productIds 保持空数组（前端按原逻辑显示 "全部产品"） - -## 四、前端行动项 - -**无需改代码**。以下是预期的前端渲染逻辑（已跟代码对齐）： - -```js -// 列表页 -{ label: '适用产品', render: row => row.productNames?.length ? row.productNames.join('、') : '全部产品' } - -// 编辑弹窗（优先用 products 结构化字段） -const tags = row.products?.length - ? row.products - : row.productIds?.map(id => ({ productId: id, name: String(id) })) // fallback -``` - -修复后列表会直接显示 `"游牧的森林-短途版"`，编辑弹窗 tag 显示产品名称。 - -## 五、测试环境已验证 - -```bash -GET /admin/order/early-bird/2045586012523864065 -→ { - "code":200, - "data":{ - "productIds":["2045345825172639746"], - "productNames":["游牧的森林-短途版"], - "products":[{"productId":"2045345825172639746","name":"游牧的森林-短途版"}] - } - } -``` - -## 六、相关 Issue -- Issue #912 早鸟列表 GET `?page=...` 返 "参数类型错误: orderId" 仍待修（与本 PR 无关） -- Issue #917 一产品一早鸟唯一约束 仍待修 diff --git a/changelogs/2026-04/2026-04-19_mp-banner-active-link-target.md b/changelogs/2026-04/2026-04-19_mp-banner-active-link-target.md deleted file mode 100644 index 8db655c..0000000 --- a/changelogs/2026-04/2026-04-19_mp-banner-active-link-target.md +++ /dev/null @@ -1,118 +0,0 @@ -# 小程序首页 Banner - 响应新增 linkTarget 嵌套对象 - -- **日期**: 2026-04-19 -- **PR**: [#890](https://git.1814.love:8443/wx/HL/pulls/890) (Closes #889) -- **类型**: FEATURE -- **状态**: 已合并到 dev + 测试环境部署完成 -- **服务**: hl-user-service + hl-product-service-v2 -- **接口**: `GET /mp/banner/active` -- **兼容性**: **向后兼容**（仅新增字段，旧字段全部保留） - ---- - -## 一、背景 - -小程序拿到 `/mp/banner/active` 列表后，当用户点到某条 Banner，前端还要再发一次产品/产品线详情请求才能展示封面、季节、产品类型，白屏等待感明显。 - -后端一把返回 Banner 展示所需的关联目标轻量信息，前端零二次请求。 - ---- - -## 二、响应新增字段 - -### 顶层新增 `linkTarget` - -Banner 列表每个元素在原有字段基础上新增： - -```jsonc -{ - "id": "1", - "title": "小蒙马亲子专题", - "imageUrl": "https://cdn.example.com/banner1.jpg", - "linkType": "PRODUCT_LINE", - "linkId": "1001", - "linkTargetType": "GROUP", // 保留,兼容旧前端 - "linkTargetName": "小蒙马亲子", // 保留,admin 填的展示名 - - // ⬇⬇⬇ 新增嵌套对象 - "linkTarget": { - "type": "PRODUCT_LINE", - "id": 1001, - "name": "小蒙马亲子", - "subtitle": null, - "coverImageUrl": "https://cdn.example.com/line-cover.jpg", - "productType": "GROUP", - "seasons": ["spring", "summer"], - "lineId": null - } -} -``` - -### `linkTarget` 字段明细 - -| 字段 | 类型 | 说明 | 产品线 | 产品 | -|------|------|------|--------|------| -| `type` | string | `PRODUCT` \| `PRODUCT_LINE` | ✅ | ✅ | -| `id` | long | 目标 ID（产品 ID 或产品线 ID） | ✅ | ✅ | -| `name` | string | 名称 | ✅ | ✅ | -| `subtitle` | string \| null | 副标题 | null | ✅ | -| `coverImageUrl` | string \| null | 封面图 URL | ✅ | ✅ | -| `productType` | string | `CORE` / `GROUP` / `CUSTOM` | ✅ | ✅ | -| `seasons` | string[] | 适用季节，字典 `product_season`：`spring` / `summer` / `autumn` / `winter`（**小写**） | ✅ | ✅ | -| `lineId` | long \| null | 所属产品线 ID | null | ✅ | - -### `linkTarget=null` 的情况 - -以下场景 `linkTarget` 整体为 `null`，前端按「无卡片详情可展示」处理即可（原有字段 `title` / `imageUrl` / `linkType` / `linkId` 照常渲染和跳转）： - -- `linkType` 不是 `PRODUCT` 或 `PRODUCT_LINE`（例如 `SCENIC` / `PAGE` / `WEBVIEW` / `NONE`） -- 关联目标已被删除或下架 -- 后端 Feign 降级（产品服务短暂不可用） - ---- - -## 三、前端集成建议 - -### 卡片展示 - -```js -// 列表渲染时 -banners.forEach(banner => { - const target = banner.linkTarget; - if (target) { - // 可直接用 target.name / target.coverImageUrl / target.seasons 渲染副卡 - renderTargetCard({ - cover: target.coverImageUrl, - title: target.name, - subtitle: target.subtitle, - tags: target.seasons, // ['SPRING', 'SUMMER'] - }); - } else { - // 仅渲染 Banner 主图,点击跳 linkType + linkId - } -}); -``` - -### 季节文案映射（前端字典） - -```js -const SEASON_LABEL = { - spring: '春季', - summer: '夏季', - autumn: '秋季', - winter: '冬季', -}; -// target.seasons.map(s => SEASON_LABEL[s]) → ['春季', '夏季'] -``` - -### 跳转路径 - -跳转规则**不变**：继续用外层的 `linkType` + `linkId` 决定跳转目标路由。`linkTarget` 只用于 Banner 上的视觉展示。 - ---- - -## 四、其它说明 - -- **旧字段全部保留**：`linkType` / `linkId` / `linkTargetType` / `linkTargetName` 行为不变，前端原有兼容逻辑不用动 -- **缓存**：Banner 列表带 30 分钟 Redis 缓存 + 事务提交后自动 evict，管理员改完 Banner 小程序下次拉取就能看到最新 `linkTarget` -- **admin 管理端接口未受影响**：banner 创建/编辑/列表接口未变（admin 只用 `linkTargetType` 做合法性提示，不返回 `linkTarget`） diff --git a/changelogs/2026-04/2026-04-19_mp-custom-migrate-to-product-service-v2.md b/changelogs/2026-04/2026-04-19_mp-custom-migrate-to-product-service-v2.md deleted file mode 100644 index 5f0cc0c..0000000 --- a/changelogs/2026-04/2026-04-19_mp-custom-migrate-to-product-service-v2.md +++ /dev/null @@ -1,69 +0,0 @@ -# CUSTOM 定制模块迁移到 hl-product-service-v2 - -**日期**: 2026-04-19 -**PR**: [#895](https://git.1814.love:8443/wx/HL/pulls/895)（v2+order+user 基础设施）+ [#897](https://git.1814.love:8443/wx/HL/pulls/897)（gateway 切路由）→ dev → 测试环境 -**影响端**: 小程序 (hl-ui-mp) -**部署服务**: hl-order-service-v2 + hl-product-service-v2 + hl-user-service + hl-gateway - -## 总体变化（对前端**完全透明**） - -小程序 `/mp/custom/**` 7 个接口的后端实现从 `hl-mp-service` 迁移到 `hl-product-service-v2`。**接口路径、请求参数、响应字段完全保持兼容**（通过 v2 端新 `MpCustomizeController` 7 个 endpoint 1:1 适配 + 镜像 DTO 字段 1:1 对齐实现）。 - -## 受影响的 7 个接口 - -| 路径 | 功能 | 鉴权 | -|---|---|---| -| `POST /mp/custom/submit` | 提交定制需求 | 登录 | -| `GET /mp/custom/list?page=&pageSize=` | 我的定制需求列表（分页） | 登录 | -| `GET /mp/custom/detail?id=` | 定制需求详情 | 登录 | -| `POST /mp/custom/{requestId}/cancel` | 取消定制需求 | 登录 | -| `GET /mp/custom/product/{productId}` | 已完成定制产品详情 | 免登录 | -| `GET /mp/custom/products` | 我的已完成定制产品列表（按手机号+定制需求聚合） | 登录 | -| `GET /mp/custom/products/all?page=&pageSize=` | 全部已完成定制产品分页浏览 | 免登录 | - -## 字段/结构一致性保证 - -- 所有 Long ID 用 String 序列化（防 JS 精度丢失）— 与原 mp-service 行为一致 -- 所有 BigDecimal 金额用 String 序列化 — 不变 -- 日期格式 `yyyy-MM-dd HH:mm:ss` — 不变 -- 分页结构 `{records, total, page, pageSize}` — 不变 -- 定制需求字段：id / userId / status / travelPurpose / requestType / departureDate / returnDate / days / adultCount / childCount / budget / destination / requirements / contactName / contactPhone / designerId / designerName / designerAvatar / reply / replyAt / createdAt / updatedAt — **全部一致** -- 定制产品字段：复用原有 `MpCustomProductDetailVO` / `MpCustomProductListVO` 字段设计 - -## 修复（顺便） - -本次迁移**顺便修复了数据丢失级 bug**：定制需求提交（POST /mp/custom/submit）之前丢失 7 个字段未映射到数据库（`requestType` / `startDate` / `endDate` / `days` / `childCount` / `contactPhone` / `contactName`），迁移后这些字段正确持久化。**此前提交的定制需求可能缺这些字段，后续提交正常**。 - -## 不影响 - -- 接口路径、请求参数、响应字段结构、HTTP code、业务码完全不变 -- mp 端 VO（`MpCustomProductDetailVO` / `MpCustomProductListVO` 等）字段不变 -- 鉴权流程不变（`X-User-Id` header 透传） - -## 需要前端做的事 - -**无需任何代码改动**。如发现具体接口异常请反馈 productId/requestId/参数。 - -## 后端实现要点（供前端排障参考） - -- gateway 路由：`Path=/mp/product/**,/mp/product-line/**,/mp/custom/**` 统一走 `hl-product-service-v2` -- v2 新建 `MpCustomizeController` + `MpCustomizeAggregatorService` 编排 3 个下游 Feign： - - `CustomizeOrderFeignClient`（调 hl-order-service-v2 customize_request） - - `CustomizeUserProfileFeignClient`（调 hl-user-service 拿手机号） - - 复用 v2 已有 `InternalMpCustomProductService`（PR #883）+ `RefundPolicyFeignClient` -- 手机号 PII 4 层防御：VO Javadoc 约束 + 自建 RateLimiter(100 QPS/phone) + Hutool DesensitizedUtil 日志脱敏 + 越权校验 -- 42 单测（7 + 14 order-v2 + 12 v2 + 9 user-service）全过 - -## 测试环境实测 - -```bash -curl https://api.test.1814.love:9443/mp/custom/products/all?page=1&pageSize=2 -# HTTP 200, 返回 2 条真实 CUSTOM 产品, 字段结构与旧接口 1:1 一致 -``` - -## 已知未修项（独立工单） - -1. order-v2 admin 端 `CustomizeRequestVO` 字段名错（travelCount / budgetRange / remark / replyContent）与 DB + mp 端不一致，为避免破坏 admin 前端**暂保留**，待独立工单专项修复 -2. mp-service 的 `MpCustomizeController` 已成死代码（路由不经过），将通过 PR-3 单独清理（24h 稳定期后） - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-19_mp-custom-products-all-list-interface.md b/changelogs/2026-04/2026-04-19_mp-custom-products-all-list-interface.md deleted file mode 100644 index d71ed3c..0000000 --- a/changelogs/2026-04/2026-04-19_mp-custom-products-all-list-interface.md +++ /dev/null @@ -1,128 +0,0 @@ -# 小程序新增「全部已完成定制产品列表」接口 - -**日期**: 2026-04-19 -**PR**: [#870](https://git.1814.love:8443/wx/HL/pulls/870) (BFF) + [#883](https://git.1814.love:8443/wx/HL/pulls/883) (后端 v2) + [#886](https://git.1814.love:8443/wx/HL/pulls/886) (回归修复) -**影响端**: 小程序 (hl-ui-mp) -**状态**: 已部署测试环境，curl 200 + 真实数据验证通过 - -## 用途 - -面向**所有小程序用户的浏览入口**，展示定制师设计完成的全部定制产品（不限当前用户），用作**案例参考 / 灵感来源**。区别于已有 `/mp/custom/products`（仅展示**当前登录用户**的已完成定制产品）。 - -## 接口 - -| 项 | 值 | -|---|---| -| **URL** | `GET /mp/custom/products/all` | -| **鉴权** | **不需要登录**（与 `/mp/custom/product/{id}` 详情一致） | -| **参数** | `page`(默认 1) / `pageSize`(默认 20, 上限 100) | -| **返回** | `Result<PageResult<MpCustomProductListVO>>` | - -## 请求示例 - -``` -GET /mp/custom/products/all?page=1&pageSize=20 -``` - -## 响应示例（实测） - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "total": 2, - "page": 1, - "pageSize": 20, - "records": [ - { - "productId": "2045390643479412737", - "productType": "CUSTOM", - "name": "测试定制wx-01", - "subtitle": "", - "tripDays": 2, - "tripNights": 1, - "departureCity": null, - "destinationCity": null, - "tags": ["露营"], - "coverImageUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/xxx.jpg", - "startPrice": null, - "paymentMode": null, - "routeMapUrl": null, - "creatorAvatarUrl": null - }, - { - "productId": "2043696016590327809", - "productType": "CUSTOM", - "name": "7天6晚草原VIP私定", - "subtitle": "专属行程·私人管家·全程越野车·星空别墅", - "tripDays": 7, - "tripNights": 6, - "tags": ["定制","深度体验","草原"], - "coverImageUrl": "https://...", - "startPrice": null, - "paymentMode": null, - "routeMapUrl": null, - "creatorAvatarUrl": null - } - ] - } -} -``` - -## 字段说明 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `productId` | String | 产品 ID（雪花 ID 字符串化防 JS 精度丢失，**必须当字符串处理**） | -| `productType` | String | 字典 `product_type`：固定 `CUSTOM`=定制产品 | -| `name` | String | 产品名称 | -| `subtitle` | String | 副标题（可空） | -| `tripDays` | Integer | 行程天数 | -| `tripNights` | Integer | 行程晚数 | -| `departureCity` | String? | 出发城市（v2 当前可能 null） | -| `destinationCity` | String? | 目的地城市（v2 当前可能 null） | -| `tags` | String[] | 标签数组（如 ["定制","草原"]） | -| `coverImageUrl` | String | 封面图 URL | -| `startPrice` | String? | 起步价（BigDecimal 字符串化，**当前 null** — 后续接入起步价计算） | -| `paymentMode` | String? | 字典 `payment_mode`：FULL=全款 / DEPOSIT=订金+尾款（**当前 null** — 后续接入） | -| `routeMapUrl` | String? | 路书地图 URL（可空） | -| `creatorAvatarUrl` | String? | 定制师头像 URL（**当前 null** — 后续接入） | - -## 过滤逻辑（后端固定） - -- `productType = 'CUSTOM'` -- `status IN ('COMPLETED', 'ORDERED')`（已完成设计 / 已下单） -- 软删除过滤 -- 按 `update_time DESC` 排序（最近完成优先） - -## 边界 - -- `pageSize` 上限 100（超出自动截到 100） -- `page < 1` 自动设为 1 -- 无数据返回 `records: []` + `total: 0`，不抛异常 - -## 关联接口 - -- `GET /mp/custom/product/{productId}` 详情（已存在，免登录）— 拿到 productId 后查详情 -- `GET /mp/custom/products` 我的已完成定制（已存在，需登录）— 区别于本接口 - -## 部分字段当前为 null 的说明 - -`startPrice` / `paymentMode` / `creatorAvatarUrl` 等字段当前可能返 null。原因：v2 后端这一轮迁移按"严格不编造"原则，跨表聚合字段（起步价 / 支付模式 / 头像）尚未实现，按设计标记 NULL。**后续 PR 会补齐**，前端可先按 null 兼容处理（不展示 / 占位）。 - -## 不影响 - -- 已有 `/mp/custom/products`（我的已完成定制）行为不变 -- 已有 `/mp/custom/product/{id}` 详情行为不变 -- 列表接口完全独立，无副作用 - -## 测试环境验证 - -```bash -curl https://api.test.1814.love:9443/mp/custom/products/all?page=1&pageSize=3 -# HTTP 200, 返回 2 条真实 CUSTOM 产品 -``` - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-19_mp-feign-migrate-to-product-service-v2.md b/changelogs/2026-04/2026-04-19_mp-feign-migrate-to-product-service-v2.md deleted file mode 100644 index 4569a34..0000000 --- a/changelogs/2026-04/2026-04-19_mp-feign-migrate-to-product-service-v2.md +++ /dev/null @@ -1,82 +0,0 @@ -# mp-service Feign 切换到 hl-product-service-v2 - -**日期**: 2026-04-19 -**PR**: [#883](https://git.1814.love:8443/wx/HL/pulls/883) + [#884](https://git.1814.love:8443/wx/HL/pulls/884) + [#872](https://git.1814.love:8443/wx/HL/pulls/872) → dev → 测试环境 -**影响端**: 小程序 (hl-ui-mp) -**部署服务**: hl-product-service-v2 + hl-mp-service - -## 总体变化（对前端基本透明） - -旧的 hl-product-service v1 已下线，所有小程序 `/mp/product/*` 和 `/mp/custom/*` 接口的后端实现切换到 hl-product-service-v2。**接口路径、请求参数、响应字段完全保持兼容**（通过 v2 端 22 个 internal endpoint 1:1 适配实现）。 - -## 受影响接口（22 个） - -### 产品基础查询 -- `GET /mp/product/list` -- `GET /mp/product/{productId}` -- `POST /mp/product/{productId}/quote` -- `GET /mp/product/lines` -- `GET /mp/product/line/{lineId}/products` -- `GET /mp/product/recommend` -- `GET /mp/product/{productId}/price-calendar` -- `GET /mp/product/earliest-booking-date` -- `GET /mp/product/{productId}/simple-quote` -- `GET /mp/product/{productId}/group-quote` -- `GET /mp/product/{productId}/batches/calendar` -- `GET /mp/product/batch/{batchId}/combos` -- `GET /mp/product/batch-brief?ids=...` -- `GET /mp/product/designer-published-ids?createBy=...` -- `GET /mp/product/designer-stats`（两个路径） - -### 行程子资源 -- `GET /mp/product/day-hotels?productId=...&dayNumber=...` -- `GET /mp/product/day-dining?productId=...&dayNumber=...` - -### 定制产品 -- `GET /mp/custom/product/{productId}` -- `GET /mp/custom/products`（按当前用户 + 手机号聚合） -- `GET /mp/custom/products/all`（全部已完成定制产品分页浏览，PR #870 新增） - -## 4 个**降级**接口（v2 数据模型缺失，前端注意可能拿到空数据） - -| 接口 | 原因 | 当前行为 | 后续 | -|---|---|---|---| -| `GET /mp/product/batch/{batchId}/combos` | v2 无 combos 概念 | 返回空列表 + 后端 log.warn | 待评估是否补 | -| `GET /mp/product/day-dining` | v2 无 product_day_dining 表 | 返回空列表 + 后端 log.warn | 后续 PR 建表+迁移 | -| `GET /mp/custom/products`（按手机号路径） | v2 ProductDO 无 contactPhone 字段 | 按手机号分支返空（按定制需求关联分支仍工作）| 后续 PR ALTER 字段 | -| `GET /mp/product/recommend` | 无推荐算法 | 按 sort_order + create_time DESC 返已上架产品 | 后续接入推荐模型 | - -**前端排查建议**：上述 4 个接口出现"空数据"属于**已知降级行为**，不算 bug。优先看其他正常接口。 - -## 字段一致性保证 - -- 所有 Long ID 用 `String` 序列化（防 JS 精度丢失）— 与原 v1 行为一致 -- 所有 BigDecimal 金额用 `String` 序列化（DECIMAL(12,2)）— 与原 v1 行为一致 -- 日期格式 `yyyy-MM-dd HH:mm:ss` — 不变 -- 分页结构 `{records, total, page, pageSize}` — 不变 - -## 不影响 - -- 接口路径、请求参数、响应字段结构、HTTP code、业务码完全不变 -- mp 端 VO（`MpProductDetailVO` / `MpCustomProductDetailVO` / `MpCustomProductListVO` 等）不变 -- 已有 token / 鉴权流程不变 - -## 需要前端做的事 - -**无需任何代码改动**。如发现具体接口异常请反馈对应 productId/参数。 - -## 后端实现要点（供前端排障参考） - -- `MpProductFeignClient.@FeignClient(name=...)`: `hl-product-service` → `hl-product-service-v2` -- 22 个 endpoint 路径与 v2 实现严格 1:1 对齐 -- 5 个新 v2 controller：`InternalMpProductController` / `InternalMpProductReportController` / `InternalMpProductDayController` / `InternalMpCustomProductController` / `InternalMpDesignerController` -- v2 端 44 单测全过 - -## 已知未修项 - -1. v2 缺 contactPhone 字段（custom-by-phone 降级） -2. v2 缺 product_day_dining 表（day-dining 降级） -3. v2 缺 batch_combo 表（batch-combos 降级） -4. 推荐算法待接入 - -🤖 Generated with [Claude Code](https://claude.com/claude-code) diff --git a/changelogs/2026-04/2026-04-19_mp-order-has-refund-field.md b/changelogs/2026-04/2026-04-19_mp-order-has-refund-field.md deleted file mode 100644 index a591f4f..0000000 --- a/changelogs/2026-04/2026-04-19_mp-order-has-refund-field.md +++ /dev/null @@ -1,190 +0,0 @@ -# 小程序订单 - 新增 hasRefund 语法糖字段 - -- **日期**: 2026-04-19 -- **PR**: [#879](https://git.1814.love:8443/wx/HL/pulls/879) (Closes #875) -- **类型**: FEATURE -- **状态**: 已合并到 dev + 测试环境部署中 -- **服务**: hl-mp-service + hl-order-service-v2 - ---- - -## 一、为什么加这个字段 - -前端在订单列表/订单详情/我的订单等多处场景都需要判断 **"这个订单是否涉及退款"**，此前只能用原始字段组合推导： - -```js -// 旧: 前端自己拼判断 -const hasRefund = - ['REFUNDING', 'REFUNDED'].includes(order.status) || - (order.refundAmount != null && Number(order.refundAmount) > 0); -``` - -问题： -- 多处重复写这段逻辑，容易漏写/写错 -- `CANCELLED` 状态不能只看 status，得再看 `refundAmount`（未付款取消 → 无退款；已付款取消 → 走退款流程） - -后端统一派生，前端一个字段判空： - -```js -// 新: 一个字段搞定 -if (order.hasRefund) { ... } -``` - ---- - -## 二、后端派生规则（**前端只需知道结果，规则仅供参考**） - -``` -hasRefund = (status in [REFUNDING, REFUNDED]) || (refundAmount > 0) -``` - -| 订单状态 | refundAmount | `hasRefund` | -|---|---|---| -| PENDING_PAY | — | `false` | -| DEPOSIT_PAID / PAID / CONFIRMED / PENDING_BALANCE / PENDING_DEPARTURE / TRAVELLING | null/0 | `false` | -| COMPLETED | null/0 | `false` | -| COMPLETED | > 0（有部分退款） | `true` | -| CANCELLED | null/0（未付款取消） | `false` | -| CANCELLED | > 0（已付款取消走退款） | `true` | -| REFUNDING | — | `true` | -| REFUNDED | — | `true` | - ---- - -## 三、变更接口清单 - -| # | 方法 | 路径 | 影响 | -|---|------|------|------| -| 1 | POST | `/mp/order/create` | 返回的 `MpOrderDetailVO` 新增 `hasRefund` | -| 2 | GET | `/mp/order/{orderId}` | 同上 | -| 3 | PUT | `/mp/order/{orderId}/edit` | 同上 | -| 4 | GET | `/mp/order/list` | 返回的 `records[]` 每项 `MpOrderListItemVO` 新增 `hasRefund` | -| 5 | GET | `/mp/order/upcoming` | 同上（列表结构） | -| 6 | GET | `/mp/order/lookup` | 同上（列表结构） | - ---- - -## 四、字段定义 - -### `MpOrderDetailVO.hasRefund` - -| 属性 | 值 | -|---|---| -| 类型 | `Boolean` | -| 位置 | `MpOrderDetailVO` 根字段 | -| 序列化 | **字段级 `@JsonInclude(ALWAYS)`**，覆盖类级 NON_NULL，**无论 true/false 都返回** | -| 空值可能 | 无（后端必派生非 null 值） | - -### `MpOrderListItemVO.hasRefund` - -| 属性 | 值 | -|---|---| -| 类型 | `Boolean` | -| 位置 | 列表每条记录根字段 | -| 序列化 | 类级默认 | -| 空值可能 | 无（后端必派生非 null 值） | - ---- - -## 五、响应示例对比 - -### 前 - -```json -{ - "code": 200, - "data": { - "orderId": "2045...", - "status": "CANCELLED", - "statusLabel": "已取消", - "refundAmount": 1000.00 - } -} -``` - -前端判断：`hasRefund = 'CANCELLED' === 'REFUNDING' || ... || Number(1000) > 0` → `true` - -### 后 - -```json -{ - "code": 200, - "data": { - "orderId": "2045...", - "status": "CANCELLED", - "statusLabel": "已取消", - "refundAmount": 1000.00, - "hasRefund": true - } -} -``` - -前端判断：`order.hasRefund` → `true` - ---- - -## 六、前端迁移建议 - -### 推荐：新代码直接用 `hasRefund` - -```js -// 订单卡片角标 -<span v-if="order.hasRefund" class="badge-refund"> - {{ order.statusLabel }} -</span> - -// 订单详情"退款信息"区块展示 -<div v-if="order.hasRefund"> - <h3>退款进度</h3> - <!-- refundProgress / refundAmount / refundPolicy 等 --> -</div> -``` - -### 兼容：旧组合判断不会失效 - -现有"status + refundAmount"组合判断仍然正确，**不强制迁移**。但建议新功能/重构时改用 `hasRefund`，减少重复逻辑。 - -### ⚠️ 不要改成这样 - -```js -// ❌ 不要这样写，会在 false 时误判为 undefined -if (order.hasRefund === undefined) { ... } - -// ✅ 直接布尔判断即可 -if (order.hasRefund) { ... } -if (!order.hasRefund) { ... } -``` - ---- - -## 七、回归验证 - -测试环境部署完成后，用 mp token 调用： - -```bash -# 1. 未付款订单(应 hasRefund=false) -curl "https://api.test.1814.love/mp/order/{pendingPayOrderId}" \ - -H "Authorization: Bearer {mp-token}" \ - | jq '.data | {status, refundAmount, hasRefund}' - -# 2. 已取消已退款订单(应 hasRefund=true) -curl "https://api.test.1814.love/mp/order/{cancelledWithRefundOrderId}" \ - -H "Authorization: Bearer {mp-token}" \ - | jq '.data | {status, refundAmount, hasRefund}' - -# 3. 列表(每条记录都应有 hasRefund) -curl "https://api.test.1814.love/mp/order/list?page=1&pageSize=10" \ - -H "Authorization: Bearer {mp-token}" \ - | jq '.data.records[] | {orderId, status, hasRefund}' -``` - -**预期**： -- 所有 3 个场景返回的 JSON 中 `hasRefund` 字段都存在（不管 true/false） -- 未付款/未退款订单：`hasRefund: false` -- REFUNDING/REFUNDED 或 `refundAmount > 0` 订单：`hasRefund: true` - ---- - -## 八、不兼容变更 - -**无**。纯新增字段，前端不读不受影响；旧的 `status` / `refundAmount` / `refundProgress` 字段全部保留，语义不变。 diff --git a/changelogs/2026-04/2026-04-19_mp-order-insurance-popup-and-improvements.md b/changelogs/2026-04/2026-04-19_mp-order-insurance-popup-and-improvements.md deleted file mode 100644 index b12b4b8..0000000 --- a/changelogs/2026-04/2026-04-19_mp-order-insurance-popup-and-improvements.md +++ /dev/null @@ -1,238 +0,0 @@ -# 小程序订单 - 保险弹窗接口 + hotels/serviceItems 字段修复 - -- **日期**: 2026-04-19 -- **PR**: - - [#885](https://git.1814.love:8443/wx/HL/pulls/885) hotels coverUrl 回填 - - [#936](https://git.1814.love:8443/wx/HL/pulls/936) 保险弹窗 + clickable=true + 过滤 CANCELLED + 被保人 -- **类型**: FEATURE + BUGFIX -- **状态**: 已合并到 dev + 测试环境部署中 -- **服务**: hl-mp-service + hl-order-service-v2 - ---- - -## 一、接口变更清单 - -| # | 方法 | 路径 | 变更类型 | 影响位置 | 变更内容 | -|---|------|------|---------|---------|---------| -| 1 | GET | `/mp/order/{orderId}/insurance` | 🟢 **新增接口** | — | 保险详情弹窗 | -| 2 | GET | `/mp/order/{orderId}/hotels` | 🔴 **出参修复** | `data.items[].coverUrl` | 已分配路径此前硬编码 null, 现从产品快照反查返回图片 URL | -| 3 | POST `/mp/order/create`<br>GET `/mp/order/{id}`<br>PUT `/mp/order/{id}/edit` | 🔴 **出参字段值变化** | `data.serviceItems[type=INSURANCE].clickable` | 此前 INCLUDED 时返回 false, 现统一返回 true | - -所有接口**入参无变化**。 - ---- - -## 二、接口详情 - -### 1. 🟢 新增: `GET /mp/order/{orderId}/insurance` - -保险详情弹窗数据。 - -#### 鉴权 -- Header: `Authorization: Bearer {mp-token}` -- 订单必须属于当前用户, 否则返回 `code=403` - -#### 路径参数 -| 参数 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `orderId` | path | Long | 是 | 订单 ID | - -#### Query 参数 -无。 - -#### Request Body -无。 - -#### 响应 Schema - -```typescript -{ - code: number; // 200 成功 / 403 无权 / 404 订单不存在 - message: string; - data: MpInsuranceDetailVO | null; // 订单无保险时为 null - success: boolean; -} - -interface MpInsuranceDetailVO { - // ===== 方案基础信息 ===== - schemeId: string; // 方案 ID (String 防 JS 大数丢精度) - schemeName: string; // 方案名 - description: string | null; // 方案描述 - isOverseas: boolean; // 境内/境外 - totalDays: number; // 适用行程天数 - notice: 'INCLUDED' | 'OPTIONAL'; // INCLUDED=必含, OPTIONAL=可选 - - // ===== 保障分段(方案配置, 与订单无关) ===== - segments: CoverageSegment[]; - - // ===== 投保记录(订单付款后才有) ===== - policies: PolicyItem[]; -} - -interface CoverageSegment { - segmentName: string; // 分段名 "低风险"/"高风险" - dayOffsetStart: number; // 起始天(1 起) - dayOffsetEnd: number; // 结束天(-1 表示最后一天) - productName: string; // 保险产品名 - planName: string; // 保障计划名 -} - -interface PolicyItem { - insuranceOrderId: string; // 保险订单 ID (String, 用于下载单张保单) - policyNo: string; // 保单号 - productName: string; - planName: string; - premium: number; // 保费(元) - insuredCount: number; // 被保人数 - coverageStartDate: string; // 起保日 yyyy-MM-dd - coverageEndDate: string; // 截止日 - status: 'PENDING' | 'INSURING' | 'INSURED' | 'FAILED'; // CANCELLED 不返回 - statusLabel: string; // 状态中文 - insuredPersons: InsuredPerson[]; -} - -interface InsuredPerson { - name: string; // 姓名 - idCardType: 'ID_CARD' | 'PASSPORT'; - idCardNo: string; // 证件号(后端已脱敏: 110***********1234) - birthday: string; // 生日 yyyy-MM-dd - gender: 'MALE' | 'FEMALE'; - phone: string; // 手机号(后端已脱敏: 138****5678) -} -``` - -#### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "schemeId": "2028762847782060034", - "schemeName": "测试3日方案", - "description": null, - "isOverseas": false, - "totalDays": 3, - "notice": "INCLUDED", - "segments": [ - { "segmentName": "低风险", "dayOffsetStart": 1, "dayOffsetEnd": 2, - "productName": "山河令(太保山东新)", "planName": "10万计划" }, - { "segmentName": "高风险", "dayOffsetStart": 3, "dayOffsetEnd": 3, - "productName": "平安保游万里行马术专属保险(互联网)", "planName": "计划一" } - ], - "policies": [ - { - "insuranceOrderId": "9100000000001001", - "policyNo": "BY202604190001", - "productName": "山河令(太保山东新)", - "planName": "10万计划", - "premium": 50.00, - "insuredCount": 2, - "coverageStartDate": "2026-05-28", - "coverageEndDate": "2026-05-29", - "status": "INSURED", - "statusLabel": "已承保", - "insuredPersons": [ - { "name": "张三", "idCardType": "ID_CARD", - "idCardNo": "110***********2222", "birthday": "1990-01-01", - "gender": "MALE", "phone": "138****8001" }, - { "name": "李四", "idCardType": "ID_CARD", - "idCardNo": "110***********3333", "birthday": "1995-02-02", - "gender": "FEMALE", "phone": "138****8002" } - ] - } - ] - }, - "success": true -} -``` - -#### 几种特殊返回 - -| 场景 | 返回 | -|------|------| -| 订单不存在 | `code=404, data=null, message="订单不存在"` | -| 订单不属于当前用户 | `code=403, data=null, message="无权查看此订单"` | -| 订单未配保险 (`insuranceNotice=EXCLUDED`) 或无 INSURANCE 服务项 | `code=200, data=null` | -| 订单配了保险但**未付款** | `code=200, data.policies=[]` (只有方案+分段, 无保单) | -| 订单已付款, 正在投保中 | `code=200, data.policies` 含 `status=PENDING` 或 `INSURING` 的条目 | -| 一订单多保单 (分段投保 / 退保重保) | `code=200, data.policies` 返回多条, **CANCELLED 已过滤不返回** | -| 方案在数据库被删 | `code=200, data=null` (兜底) | - ---- - -### 2. 🔴 修复: `GET /mp/order/{orderId}/hotels` - -#### 变更位置 -出参 `data.items[].coverUrl` - -#### 变更前 -已分配路径 (订单已确认实际入住酒店时) 返回: -```json -{ - "items": [ - { "hotelId": "xxx", "hotelName": "某酒店", "coverUrl": null, - "assignmentDate": "2026-05-28", "roomType": "大床房", "hotelType": "HOTEL" } - ] -} -``` - -#### 变更后 -```json -{ - "items": [ - { "hotelId": "xxx", "hotelName": "某酒店", - "coverUrl": "https://cdn.../hotel-cover.jpg", - "assignmentDate": "2026-05-28", "roomType": "大床房", "hotelType": "HOTEL" } - ] -} -``` - -#### 变更原因 -订单分配表 `order_hotel_assignment` 不存 coverUrl, 此前硬编码 null. 现按 hotelId 从产品快照 `hotels[]` 里反查图片 URL. 未分配路径行为不变. - -#### 其他字段 -无变化 (`hotelId`/`hotelName`/`assignmentDate`/`roomType`/`hotelType` 及同级 `nightCount`/`roomTypeStats` 均无改动)。 - ---- - -### 3. 🔴 字段值变化: `serviceItems[type=INSURANCE].clickable` - -#### 影响接口 -- `POST /mp/order/create` 返回 `data.serviceItems` -- `GET /mp/order/{orderId}` 返回 `data.serviceItems` -- `PUT /mp/order/{orderId}/edit` 返回 `data.serviceItems` - -#### 变更位置 -`data.serviceItems` 数组中 `type === 'INSURANCE'` 的元素的 `clickable` 字段。 - -#### 变更前 - -| `insuranceNotice` | `clickable` | -|---|---| -| `EXCLUDED` | 条目不返回 | -| `INCLUDED` (必含保险) | **false** | -| `OPTIONAL` (可选加保) | true | - -#### 变更后 - -| `insuranceNotice` | `clickable` | -|---|---| -| `EXCLUDED` | 条目不返回 (不变) | -| `INCLUDED` | **true** (与 OPTIONAL 统一) | -| `OPTIONAL` | true (不变) | - -#### 变更原因 -新增了保险弹窗接口 `/mp/order/{id}/insurance` 后, INCLUDED 也有点击交互需求 (查看方案 + 保单列表), 不再需要前端禁用这个条目。 - -#### 历史订单 -在本次改动之前已下单的订单, `order_service_item` 表里固化的 `clickable` 仍是原值 (可能 false), 新下单的订单起是 true。如果需要批量修正历史数据, 可提 Issue 加补偿脚本。 - ---- - -## 三、不兼容变更 - -**无**。 -- 新增接口: 老前端不调用不影响 -- hotels `coverUrl`: 从 null 变为有值, 前端原本 null 态处理代码仍然正确 -- `clickable`: 从 false 变为 true 只是让条目变可点, 旧代码不点它也不会出错 diff --git a/changelogs/2026-04/2026-04-19_mp-product-all-custom-followup.md b/changelogs/2026-04/2026-04-19_mp-product-all-custom-followup.md deleted file mode 100644 index 774b58a..0000000 --- a/changelogs/2026-04/2026-04-19_mp-product-all-custom-followup.md +++ /dev/null @@ -1,95 +0,0 @@ -# fix(product-v2): /mp/product/** 全量补 CUSTOM 支持（#900 follow-up） - -> **服务**: hl-product-service-v2 -> **PR**: #903（接续 #900） -> **Issue**: #901 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **可能需要，视前端是否已调 B 类接口**（详见下文） - ---- - -## 一、背景 - -PR #900 只修了 `/mp/product/{id}` 主详情，其他 5 个 `/mp/product/{id}/**` 子接口对 CUSTOM 产品仍 404。本 PR 一次性收口 `/mp/product/**` 下所有子接口的 CUSTOM 支持。 - ---- - -## 二、变更接口（10 个子接口分 3 类处理） - -### A 类 - 行为修复：放行 CUSTOM（1 个） - -| 接口 | 方法 | 路径 | 新行为 | -|------|------|------|-------| -| 日酒店详情 | GET | `/mp/product/{id}/day/{dayNumber}/hotels` | CUSTOM + COMPLETED/ORDERED 放行返回 200 | - -### B 类 - 行为修复：明确拒绝 CUSTOM（4 个） - -业务上 CUSTOM 产品是一口价、无班期、无多档位，这些接口本来就不适用。原来模糊 404，现在改为**明确业务异常**： - -| 接口 | 方法 | 路径 | CUSTOM 产品新响应 | -|------|------|------|------------------| -| 价格日历 | GET | `/mp/product/{id}/price-calendar?month=xxx` | `{"code":500,"message":"定制产品不支持本接口","success":false}` | -| 班期 | GET | `/mp/product/{id}/schedules` | 同上 | -| 档位对比 | GET | `/mp/product/{id}/tier-compare` | 同上 | -| 算价 | POST | `/mp/product/{id}/quote` | 同上 | - -> **注**：`code=500` 是项目 BusinessException 的默认业务码，HTTP 状态仍是 200。前端应按 `message="定制产品不支持本接口"` 字面识别，不要按 `code` 跳转错误页。 - -### C 类 - 无变化（5 个） - -- `/mp/product/{id}` (PR #900 已修) -- `/mp/product/{id}/day/{dayNumber}` (PR #900 已修) -- `/mp/product/hotel/**`、`/mp/product/room-type/**`（产品无关） -- `/mp/product/compare`（自然过滤） - ---- - -## 三、前端行动项 - -### 如果前端**没有**对 CUSTOM 产品调用 B 类接口：无需改动 - -### 如果前端**有**调用： - -**推荐**：前端详情页按产品 productType 隐藏/禁用无意义的入口： -- CUSTOM 产品详情页 **不渲染**：价格日历 / 班期列表 / 档位对比 tab / 立即报价按钮 -- CUSTOM 产品只展示：基本信息、行程、每日酒店、描述、图集 - -**兜底**：如果没法按 productType 前置判断，收到 `message="定制产品不支持本接口"` 时静默降级，不要弹全局错误。 - -### 清理历史 workaround - -| 可清理 | 原因 | -|--------|------| -| 对 `/mp/product/{id}/day/{n}/hotels` 的 CUSTOM 特殊兜底 | 现已正常返回 | -| CUSTOM 产品详情页对主接口 404 的全局兜底 | PR #900 已修 | - ---- - -## 四、完整状态可见性矩阵 - -| productType | status | 详情/日酒店 | 日历/班期/档位/算价 | -|-------------|--------|------------|---------------------| -| CORE / GROUP | DRAFT/PENDING_REVIEW | 404 | 404 | -| CORE / GROUP | PUBLISHED | **200** | **200** | -| CUSTOM | DRAFT/PENDING_REVIEW | 404 | 404 | -| CUSTOM | COMPLETED/ORDERED | **200**（本次修复） | **500 "定制产品不支持本接口"**（本次明确拒） | - ---- - -## 五、测试环境已验证 - -CUSTOM 产品 `2045390643479412737`（7天6晚草原VIP私定）： -``` -GET /tier-compare → 500 "定制产品不支持本接口" ✓ -GET /price-calendar → 500 "定制产品不支持本接口" ✓ -GET /schedules → 500 "定制产品不支持本接口" ✓ -POST /quote → 500 "定制产品不支持本接口" ✓ -GET /day/1/hotels → 200（含 dayNumber/tiers）✓ -``` - -CORE 产品 `2045424500610125825`： -``` -GET /price-calendar → 200 ✓ -GET /tier-compare → 200 ✓ -GET /schedules → 200 ✓ -``` diff --git a/changelogs/2026-04/2026-04-19_mp-product-custom-allow-all-revert-903.md b/changelogs/2026-04/2026-04-19_mp-product-custom-allow-all-revert-903.md deleted file mode 100644 index f92fcd8..0000000 --- a/changelogs/2026-04/2026-04-19_mp-product-custom-allow-all-revert-903.md +++ /dev/null @@ -1,94 +0,0 @@ -# fix(product-v2): /mp/product/** 4 接口对 CUSTOM 全量放行（撤销 PR #903 的拒绝） - -> **服务**: hl-product-service-v2 -> **PR**: #906（撤销 #903 的 B 类拦截） -> **Issue**: #905 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **可能需要回退 #903 引入的兜底逻辑** - ---- - -## ⚠️ 关键变化 - -前一版 changelog（#903）说 4 个接口会对 CUSTOM 产品返回 `{"code":500,"message":"定制产品不支持本接口"}`。**这个判断是错的，现已撤销**。 - -定制产品（CUSTOM + COMPLETED/ORDERED）现在走和核心/小蒙马产品**完全一样**的 4 个子接口。 - ---- - -## 一、背景 - -#903 把 4 个接口对 CUSTOM 产品定性为"不支持"是业务误判。DB 实证推翻： - -| 维度 | CUSTOM 产品 `2043696016590327809` | CUSTOM 产品 `2045390643479412737` | -|------|-----------------|-----------------| -| 档位 | 1 档 | 2 档（轻奢/高端）| -| price_calendar 记录 | 62 条 | 92 条 | -| group_tour_batch 班期 | 2 条 | 0 条 | -| day_hotel 记录 | 6 条 | 同上 | - -定制产品在 DB 里具备与 CORE/GROUP 完全一致的 4 类数据结构。底层 `ProductPricingService.calculateQuote` 等对 productType 零硬依赖。 - ---- - -## 二、受影响接口（全部放行） - -| 接口 | CUSTOM + COMPLETED/ORDERED | CUSTOM + DRAFT/PENDING | -|------|---------------------------|------------------------| -| `GET /mp/product/{id}` | 200 | 404 | -| `GET /mp/product/{id}/day/{n}/hotels` | 200 | 404 | -| `GET /mp/product/{id}/price-calendar?month=xxx` | **200** | 404 | -| `GET /mp/product/{id}/schedules` | **200**（无班期返 `[]`） | 404 | -| `GET /mp/product/{id}/tier-compare` | **200** | 404 | -| `POST /mp/product/{id}/quote` | **200** | 404 | - -**前面 3 行加粗的是本次新放行**，其余行为不变（包括 #898/#900 修的主详情和日酒店）。 - ---- - -## 三、前端行动项 - -### 如果前端按 #903 的 changelog 做过兜底，需要回退 - -| 可移除的 #903 遗产 | 原因 | -|--------------------|------| -| CUSTOM 产品详情页隐藏价格日历 tab | 现已正常返回 | -| CUSTOM 产品隐藏班期列表 | 现已正常返回（可能为空数组） | -| CUSTOM 产品隐藏档位对比 tab | 现已正常返回 | -| CUSTOM 产品隐藏"立即报价"按钮 | 现已正常返回 | -| 收到 `message="定制产品不支持本接口"` 的静默降级分支 | 不再出现此消息 | - -### 推荐前端逻辑（统一版） - -CUSTOM 和 CORE/GROUP 产品详情页**可以共用同一套**请求和渲染逻辑，不再按 productType 分流。 - -### 空数据兜底 - -`/schedules` 对未维护班期的 CUSTOM 产品返回 `data: []`（语义 = 按预约/无固定出团日期），前端应正常处理空列表 UI。 - ---- - -## 四、测试环境已验证 - -CUSTOM 产品 `2045390643479412737`（测试定制wx-01）： -``` -GET /price-calendar?month=2026-04 → 200 + days 数组（adultPrice 等完整） ✓ -GET /tier-compare → 200 + tiers 数据 ✓ -GET /schedules → 200 + [] （该产品未维护班期） ✓ -POST /quote → 200 + 成功 ✓ -``` - -CUSTOM 产品 `2043696016590327809`（7天6晚草原VIP私定）： -``` -GET /schedules → 200 + 2 条班期 ✓ -``` - ---- - -## 五、相关历史 - -| PR | Issue | 说明 | -|----|-------|------| -| #900 | #898 | 首次放行 `/mp/product/{id}` 主详情 | -| #903 | #901 | **误判**把 4 个子接口对 CUSTOM 定性为"不支持"（已被本 PR 撤销）| -| **#906** | **#905** | **撤销 #903，4 个接口全量放行 CUSTOM**（本次）| diff --git a/changelogs/2026-04/2026-04-19_mp-product-detail-hotel-cover.md b/changelogs/2026-04/2026-04-19_mp-product-detail-hotel-cover.md deleted file mode 100644 index 39f2426..0000000 --- a/changelogs/2026-04/2026-04-19_mp-product-detail-hotel-cover.md +++ /dev/null @@ -1,173 +0,0 @@ -# 小程序产品详情 - 住宿信息补酒店封面图 / 类型 / 城市 - -- **日期**: 2026-04-19 -- **Commit**: [2625331f](https://git.1814.love:8443/wx/HL/commit/2625331f) (分支 `fix/0419-business-hotfixes`，批量 PR 待合) -- **类型**: FIX -- **状态**: 已 commit + push，待批量 PR 合入 dev + 部署测试环境 -- **服务**: hl-product-service-v2（端口 8083，通过网关暴露 `/mp/product/**`） - ---- - -## 一、为什么加这三个字段 - -原型（`小蒙马.pen` → `S6-住宿安排`）的每晚住宿卡片结构： - -``` -┌────────┬──────────────────────┐ -│ │ 第N晚·城市名（小标签） │ -│ 封面图 │ 酒店名称（粗体） │ -│ 100x100│ 一句话描述 │ -└────────┴──────────────────────┘ -``` - -此前后端返回的 `HotelInfo` **只有 hotelName + 档位字段**，前端拿不到封面图 URL、酒店类型（五星/四星等）、酒店所在城市，小程序端显示为空白图位。 - -根因：`MpProductDetailAssembler.fetchResourceDetails(...)` 原先只收集 `nodeType=HOTEL` 节点的 hotelId 去批量查 `ResourceDetailDTO`，而 `product_day_hotel` 表里的 hotelId **从未进入批量查参数**，所以 HotelInfo 始终拿不到酒店详情。 - ---- - -## 二、变更接口清单 - -| # | 方法 | 路径 | 影响 | -|---|------|------|------| -| 1 | GET | `/mp/product/{id}` | 返回的 `itinerary[].hotels[]` 每项新增 `coverUrl` / `hotelType` / `city` 三字段 | - -**其他接口**（如 `/mp/product/{id}/day/{dayNumber}/hotels` 住宿详情弹窗）已有 `coverUrl`，**不变**。 - ---- - -## 三、字段定义 - -### `MpProductDetailRespVO.HotelInfo` 新增字段 - -| 字段 | 类型 | 说明 | 示例 | 可能为 null | -|---|---|---|---|---| -| `coverUrl` | String | 酒店封面图 URL（来自资源服务的酒店 cover） | `"https://oss.1814.love/hotel/9001/cover.jpg"` | ✅ 当酒店资源未配封面或 Feign 异常时为 null | -| `hotelType` | String | 酒店类型（字典 `hotel_type`：`FIVE_STAR` / `FOUR_STAR` / `BOUTIQUE` / `HOMESTAY` / ...） | `"FIVE_STAR"` | ✅ 可能为 null | -| `city` | String | 酒店所在城市 | `"海拉尔"` | ✅ 可能为 null | - -### 既有字段（不变） - -`hotelName` / `tierSeq` / `tierName` / `roomTypeId` / `roomTypeName` / `roomCount`。 - -此外，本次修复顺带加强了 `hotelName` 的补齐语义：当资源服务返回了 `name`，**会覆盖 DB 快照字段**（更新鲜），快照只作为 Feign 降级时的兜底。 - ---- - -## 四、响应示例对比 - -### 前 - -```json -{ - "code": 200, - "data": { - "productId": 1001, - "name": "小蒙马·呼伦贝尔5日", - "itinerary": [{ - "dayNumber": 1, - "hotels": [{ - "hotelName": "海拉尔精选酒店", - "tierSeq": 1, - "tierName": "标准", - "roomTypeName": "大床房", - "roomCount": 1 - }] - }] - } -} -``` - -### 后 - -```json -{ - "code": 200, - "data": { - "productId": 1001, - "name": "小蒙马·呼伦贝尔5日", - "itinerary": [{ - "dayNumber": 1, - "hotels": [{ - "hotelName": "海拉尔精选酒店", - "tierSeq": 1, - "tierName": "标准", - "roomTypeName": "大床房", - "roomCount": 1, - "coverUrl": "https://oss.1814.love/hotel/9001/cover.jpg", - "hotelType": "FIVE_STAR", - "city": "海拉尔" - }] - }] - } -} -``` - ---- - -## 五、前端渲染建议 - -原型 `S6-住宿安排` 每日住宿卡片： - -```html -<div class="hotel-card" v-for="hotel in day.hotels"> - <!-- 左侧 100x100 封面图 --> - <image - class="hotel-cover" - :src="hotel.coverUrl || DEFAULT_HOTEL_COVER" - mode="aspectFill" /> - - <!-- 右侧文字信息 --> - <view class="hotel-info"> - <text class="hotel-city">第{{ day.dayNumber }}晚·{{ hotel.city }}</text> - <text class="hotel-name">{{ hotel.hotelName }}</text> - <!-- 房型/档位信息 --> - <text class="hotel-room">{{ hotel.tierName }} · {{ hotel.roomTypeName }}</text> - </view> -</div> -``` - -### ⚠️ 容错要求 - -- `coverUrl` / `hotelType` / `city` **三个字段均可能为 null**（Feign 失败 / 酒店资源未配封面 / 老数据没录入城市），前端务必做 null/空字符串判断： - - `coverUrl` 为空时显示默认占位图（避免整个卡片布局错乱） - - `city` 为空时可以只显示"第N晚" - - `hotelType` 用于可选的类型标签展示，为空时整个标签隐藏即可 - ---- - -## 六、不兼容变更 - -**无**。纯新增字段，前端不读不受影响；既有字段（`hotelName` / 档位 / 房型）全部保留，语义不变。 - ---- - -## 七、运维注意事项（⚠️ 发布后必做） - -本接口有 **5 分钟 Redis 缓存**（key 前缀 `mp:product:detail:`）。测试 / 生产部署 `hl-product-service-v2` 后**必须清一次缓存**，否则 C 端最长 5 分钟内仍返回旧缓存（无封面图）： - -```bash -# 测试环境（192.168.100.236 或 1.182.108.58） -redis-cli -h <redis_host> -p 6379 --scan --pattern 'mp:product:detail:*' | xargs -r redis-cli -h <redis_host> -p 6379 del - -# 或者粗暴重启服务强制清本地进程缓存（Redis 不会自动失效） -``` - ---- - -## 八、回归验证 - -测试环境部署完成后： - -```bash -# 选一个小蒙马 GROUP 产品的 productId -curl "https://api.test.1814.love/mp/product/{productId}" \ - -H "Authorization: Bearer {mp-token}" \ - | jq '.data.itinerary[0].hotels[0] | {hotelName, coverUrl, hotelType, city}' -``` - -**预期**：三个新字段都在响应 JSON 中出现；若酒店资源已配封面，`coverUrl` 为完整 http(s) URL；`city` / `hotelType` 应与后台管理端该酒店的配置一致。 - -如果 `coverUrl` 仍为 null： -1. 先确认 Redis 缓存已清（见第七节） -2. 再排查酒店资源是否在资源服务后台配了封面图（管理端 → 酒店管理 → 编辑 → 封面图） diff --git a/changelogs/2026-04/2026-04-19_mp-product-support-custom.md b/changelogs/2026-04/2026-04-19_mp-product-support-custom.md deleted file mode 100644 index 183c0b8..0000000 --- a/changelogs/2026-04/2026-04-19_mp-product-support-custom.md +++ /dev/null @@ -1,69 +0,0 @@ -# fix(product-v2): /mp/product/{id} 支持定制产品(CUSTOM) - -> **服务**: hl-product-service-v2 -> **PR**: #900 -> **Issue**: #898 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **无需改动**（后端行为修复，前端原调用方式继续有效） - ---- - -## 一、背景 - -前端小程序调 `GET /mp/product/{id}` 查询定制产品详情时一直返回 `code=404 "产品不存在或已下架"`。例如 `GET /mp/product/2043696016590327809`（定制产品"7天6晚草原VIP私定"）。 - -**根因（后端侧）**：原接口硬校验 `status=PUBLISHED`，但定制产品（`productType=CUSTOM`）的状态流转是 `DRAFT → COMPLETED → ORDERED`，根本不经过 PUBLISHED。 - -**前端感知**：定制产品详情页进不去、白屏、或者前端做过类似"CUSTOM 改调 `/mp/custom/product/{id}`"的 workaround。 - ---- - -## 二、变更接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | 前端改动 | -|---|------|------|------|---------|---------| -| 1 | 小程序产品详情 | GET | `/mp/product/{id}` | **行为修复**：CUSTOM 产品不再 404，返回完整详情 | 无需 | -| 2 | 定制产品专属详情 | GET | `/mp/custom/product/{id}` | 无变化 | 无需 | - -**请求/响应结构完全不变**，仅扩大了状态白名单。 - ---- - -## 三、状态可见性矩阵（修复后） - -| productType | status | `/mp/product/{id}` 返回 | -|-------------|--------|------------------------| -| CORE / GROUP | DRAFT / PENDING_REVIEW / COMPLETED | 404 | -| CORE / GROUP | PUBLISHED | 200 完整详情 | -| **CUSTOM** | DRAFT / PENDING_REVIEW | 404 | -| **CUSTOM** | **COMPLETED / ORDERED** | **200 完整详情（本次修复）** | - ---- - -## 四、前端行动项 - -**无需任何代码改动**。可评估清理以下历史 workaround： - -| 可移除的 workaround | 原因 | -|--------------------|------| -| 根据 productType 分发调用 `/mp/product/{id}` 或 `/mp/custom/product/{id}` | 现在 `/mp/product/{id}` 统一支持所有 productType | -| CUSTOM 产品详情页特殊 catch 404 显示"产品不存在"文案 | 后端已正确返回 | -| 任何针对"定制产品详情不可用"的 UI 兜底 | 不再必要 | - -**保留**：`/mp/custom/product/{id}` 仍是定制产品的专属入口（带 refund policies enrich 等特化逻辑），适合"已完成定制"详情场景继续用。 - ---- - -## 五、测试环境已验证 - -``` -GET /mp/product/2043696016590327809 (CUSTOM + COMPLETED) → 200 "7天6晚草原VIP私定" ✓ -GET /mp/product/2045424500610125825 (CORE + PUBLISHED) → 200 "E2E-核心版本-V1" ✓ -GET /mp/product/2045486260364996609 (任意 + DRAFT) → 404 ✓ -``` - ---- - -## 六、响应字段 - -与原 `MpProductDetailRespVO` 完全一致，不新增/删除/改名任何字段。CUSTOM 产品组装时，无相关数据的子表字段（如班期、价格日历）自然为 null/空集。 diff --git a/changelogs/2026-04/2026-04-19_mp-tier-compare-hotel-cover.md b/changelogs/2026-04/2026-04-19_mp-tier-compare-hotel-cover.md deleted file mode 100644 index 28e5cee..0000000 --- a/changelogs/2026-04/2026-04-19_mp-tier-compare-hotel-cover.md +++ /dev/null @@ -1,146 +0,0 @@ -# 小程序档位对比 - 住宿补酒店封面图 / 类型 / 城市 - -- **日期**: 2026-04-19 -- **PR**: [#923](https://git.1814.love:8443/wx/HL/pulls/923) (squash merge → dev, `0e029c38`) -- **类型**: FIX -- **状态**: 已合并到 dev + 测试环境部署完成 + API 验证通过 -- **服务**: hl-product-service-v2（端口 8083） -- **关联**: PR #913 姊妹修复（主详情已修，本 PR 覆盖档位对比） - ---- - -## 一、为什么加这三个字段 - -PR #913 修复了 `GET /mp/product/{id}` 主详情的住宿封面图缺失（每日住宿卡左侧 100x100 封面图位）。但档位对比接口 `GET /mp/product/{id}/tier-compare` 的 `tiers[].hotels[]` 同样没返回 `coverUrl/hotelType/city`，前端档位对比画面展示酒店时封面依然空白。 - -根因：`MpProductService.tierCompare(...)` 组装 `HotelItem` 时**只做 `BeanUtil.toBean` 从 `ProductDayHotelDO` 快照拷贝**，未调 `resourceDetailFeignClient.batchDetails(...)` 取酒店资源详情（与主详情修复前症状一致）。 - ---- - -## 二、变更接口清单 - -| # | 方法 | 路径 | 影响 | -|---|------|------|------| -| 1 | GET | `/mp/product/{id}/tier-compare` | 返回的 `tiers[].hotels[]` 每项新增 `coverUrl` / `hotelType` / `city` 三字段 | - ---- - -## 三、字段定义 - -### `MpTierCompareRespVO.HotelItem` 新增字段 - -| 字段 | 类型 | 说明 | 示例 | 可能为 null | -|---|---|---|---|---| -| `coverUrl` | String | 酒店封面图 URL（来自资源服务 cover） | `"https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/xxx.jpg"` | ✅ 酒店资源未配封面或 Feign 异常 | -| `hotelType` | String | 酒店类型（字典 `hotel_type`：`FIVE_STAR` / `FOUR_STAR` / `BOUTIQUE` / `HOMESTAY` / ...） | `"FIVE_STAR"` | ✅ 可能为 null | -| `city` | String | 酒店所在城市 | `"呼伦贝尔市"` | ✅ 可能为 null | - -### 既有字段（语义不变） - -`id` / `productId` / `dayId` / `dayNumber` / `tierSeq` / `hotelId` / `hotelName` / `roomTypeId` / `roomTypeName` / `roomCount` / `isDefault` / `sortOrder`。 - ---- - -## 四、响应示例对比 - -### 前 - -```json -{ - "code": 200, - "data": { - "tiers": [{ - "tierSeq": 1, - "tierName": "标准", - "hotels": [{ - "dayNumber": 1, - "hotelId": 9001, - "hotelName": "呼伦贝尔香格里拉大酒店", - "tierSeq": 1 - }] - }] - } -} -``` - -### 后 - -```json -{ - "code": 200, - "data": { - "tiers": [{ - "tierSeq": 1, - "tierName": "标准", - "hotels": [{ - "dayNumber": 1, - "hotelId": 9001, - "hotelName": "呼伦贝尔香格里拉大酒店", - "tierSeq": 1, - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/4be257ef92d0b76e401792e2f445c96d.jpg", - "hotelType": "HOTEL", - "city": "呼伦贝尔市" - }] - }] - } -} -``` - ---- - -## 五、和主详情一致性保证 - -与 PR #913 的主详情修复**字段顺序和兜底逻辑完全一致**（开发验收员已核对）： - -| 点 | 做法 | -|---|---| -| `resourceMap` 的 key | `"HOTEL:" + hotelId` | -| 字段覆盖顺序 | `cover` → `hotelType` → `city` → `name` | -| null 值策略 | `dto == null` / 各字段 null 一律**保留 `BeanUtil` 快照**，不强制覆盖 | -| Feign 异常 | `try/catch` → `resourceMap = Map.of()` + `log.warn` | -| 批量 Feign | 一次 `batchDetails(null, hotelIds, null, null, null)`，非 N+1 | - -**前端不会出现同一个酒店在主详情和档位对比接口中 `coverUrl` 值不一致的情况。** - ---- - -## 六、前端容错要求 - -与 `2026-04-19_mp-product-detail-hotel-cover.md` 完全一致：三个字段**均可能为 null**，务必做判空： - -- `coverUrl` 为空 → 显示默认占位图 -- `city` 为空 → 不显示地理位置标签 -- `hotelType` 为空 → 不显示类型标签 - ---- - -## 七、不兼容变更 - -**无**。纯新增字段，既有字段全部保留语义不变。 - ---- - -## 八、运维注意事项 - -本接口有 **5 分钟 Redis 缓存**（key 前缀 `mp:product:tier-compare:`）。测试环境已在本次部署时清理过；生产部署时**务必再清一次**，否则 C 端最长 5 分钟内仍返回旧数据： - -```bash -redis-cli --scan --pattern 'mp:product:tier-compare:*' | xargs -r redis-cli del -``` - ---- - -## 九、回归验证 - -测试环境已验证（productId=2044306857534636034）： - -```bash -curl -sk "http://127.0.0.1:8080/mp/product/2044306857534636034/tier-compare" \ - -H "Authorization: Bearer {token}" \ - | jq '.data.tiers[].hotels[] | {hotelName, coverUrl, hotelType, city}' -``` - -**实测结果**： -- 呼伦贝尔香格里拉大酒店 → `coverUrl` 真实 OSS URL、`city=呼伦贝尔市` -- 海拉尔海棠酒店 → `coverUrl` 真实 OSS URL、`city=呼伦贝尔市` -- 三个新字段键均存在，均有真实值（非 null） diff --git a/changelogs/2026-04/2026-04-19_product-detail-earlybird-tip.md b/changelogs/2026-04/2026-04-19_product-detail-earlybird-tip.md deleted file mode 100644 index f12f69d..0000000 --- a/changelogs/2026-04/2026-04-19_product-detail-earlybird-tip.md +++ /dev/null @@ -1,56 +0,0 @@ -# feat: 产品详情自动生成早鸟优惠文案字段 earlyBirdTip - -> **服务**: hl-product-service-v2 -> **PR**: #918 -> **Issue**: #915 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **展示新字段** - ---- - -## 一、新增字段 - -管理端 + 小程序端产品详情接口**新增** `earlyBirdTip: String` 字段： - -| 接口 | 方法 | 路径 | 新字段 | -|------|------|------|--------| -| 管理端产品详情 | GET | `/admin/product/item/{id}` | `earlyBirdTip: String` | -| 小程序端产品详情 | GET | `/mp/product/{id}` | `earlyBirdTip: String` | - -**其他字段不变**。 - -## 二、字段语义 - -后端根据产品绑定的生效早鸟优惠计划**自动生成**的营销文案字符串。 - -### 生成规则 -- 正常格式：`满 {minPeople} 人订单总价优惠 {discountAmount} 元` -- `minPeople=null/0` 降级：`订单总价优惠 {discountAmount} 元` -- 金额自动去除小数尾零：`100.00 → 100`、`99.50 → 99.5` -- 未绑定 / 早鸟过期 / 早鸟禁用 / Feign 异常 → **`null`**（前端不渲染） - -### 业务约束 -一个产品**最多绑定一个**早鸟优惠计划（1-1 关系，由 order-v2 保证，Issue #917 跟进）。 - -## 三、前端建议展示位置 - -营销区块 / 价格区块附近，高亮展示。例如： -```html -<div v-if="product.earlyBirdTip" class="early-bird-banner"> - 🎉 {{ product.earlyBirdTip }} -</div> -``` - -## 四、测试环境验证 - -| 场景 | 结果 | -|------|------| -| 产品绑定 55 元/2 人早鸟 | `"满 2 人订单总价优惠 55 元"` ✓ | -| 产品未绑定早鸟 | `null` ✓ | - -两端完全对称，行为一致。 - -## 五、相关 Issues（顺带跟进，非本 PR） - -- Issue #916 早鸟编辑页适用产品回显 ID 而非名称 -- Issue #917 强制"一产品一早鸟"唯一约束 diff --git a/changelogs/2026-04/2026-04-19_product-v2_list-filter-and-publish-validation-fix.md b/changelogs/2026-04/2026-04-19_product-v2_list-filter-and-publish-validation-fix.md deleted file mode 100644 index e5768df..0000000 --- a/changelogs/2026-04/2026-04-19_product-v2_list-filter-and-publish-validation-fix.md +++ /dev/null @@ -1,100 +0,0 @@ -# fix(product-v2): 产品列表多值筛选 + 小蒙马上架校验四项修复 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #881 -> **Issue**: #876 / #877 -> **Merge commit**: `406afb28` -> **日期**: 2026-04-19 -> **影响范围**: 管理端产品列表筛选 + 上架预检接口行为 -> **前端是否需要改动**: **无需改动**（前端继续按原方式调用即可，行为自动变正常） - ---- - -## 一、背景 - -本次修复两个 BUG： - -### BUG-1：产品列表 productType 多值筛选失效（返回空） -- 前端传 `GET /admin/product/item/list?status=PUBLISHED&productType=CORE,GROUP` 时返回空 -- 实际测试环境 DB 有 9 条符合条件的产品 -- 根因：后端 VO 字段是 `String`，Spring 把 `"CORE,GROUP"` 当字面值绑定，SQL 变成 `WHERE product_type = 'CORE,GROUP'` → 零结果 -- **如果前端之前有 "只传单值 productType" 或"前端本地过滤多值" 的 workaround，现在可以删掉** - -### BUG-2：小蒙马（GROUP）产品上架预检 4 条过时/错误提示 -- `GET /admin/product/item/{id}/validate-publish` 对 GROUP 产品返回 4 条与实际配置不符的错误 -- 根因：代码未跟进需求变更，校验逻辑查了错的表 / 未按产品类型分流 -- **前端展示这些错误文案的弹窗/列表无需改动**，后端校验逻辑变严谨后这些错误自然消失 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 前端改动 | -|---|------|------|------|---------|---------| -| 1 | 产品列表 | GET | `/admin/product/item/list` | **Query 参数 `productType` 支持多值**（原单值） | 无需（原传法继续工作） | -| 2 | 产品下拉列表 | GET | `/admin/product/item/simple-list` | 同上 | 无需 | -| 3 | 产品上架预检 | GET | `/admin/product/item/{id}/validate-publish` | **行为修复**（响应结构不变） | 无需 | - ---- - -## 三、接口详情 - -### 1. `GET /admin/product/item/list` 和 `/simple-list` - -`productType` 参数从 **String** 变为 **List<String>**，同时保持**向下兼容**，支持三种传参写法： - -| 写法 | 语义 | 后端解析结果 | -|------|------|-------------| -| `productType=CORE` | 单值 | `["CORE"]` → `WHERE product_type IN ('CORE')` | -| `productType=CORE,GROUP` | 逗号分隔 | `["CORE","GROUP"]` → `WHERE product_type IN ('CORE','GROUP')` | -| `productType=CORE&productType=GROUP` | 多值重复 key | `["CORE","GROUP"]` → `WHERE product_type IN ('CORE','GROUP')` | -| 不传 | 全部类型 | 无 productType 过滤条件 | - -Axios / fetch 默认行为下传 `params: { productType: 'CORE,GROUP' }` 或 `params: { productType: ['CORE', 'GROUP'] }` 都会被后端正确识别。 - -**前端实际修复效果**： -- 原：`?productType=CORE,GROUP` → `total: 0`（bug） -- 现：`?productType=CORE,GROUP` → `total: 9`（正确返回 CORE + GROUP 全部符合条件的产品） - -### 2. `GET /admin/product/item/{id}/validate-publish` - -**响应结构不变**，仅修复校验逻辑不再产生以下 4 条**已过时**的错误提示： - -| # | 不再出现的文案 | 修复说明 | -|---|---------------|---------| -| 1 | `订金支付方式(payment_type=DEPOSIT)必须配置尾款到期天数 balance_due_days` | 需求已取消，校验代码已删除 | -| 2 | `缺少酒店节点，订单详情住宿弹窗将为空` | v2 酒店独立到 `product_day_hotel` 表，校验改查这个表 | -| 3 | `缺少餐饮节点，订单详情餐饮弹窗将为空` | v2 餐饮写在 `product_itinerary_day.breakfast/lunch/dinner`，校验改扫描三餐字段 | -| 4 | `路线总览未配置实际用车车型(product_route_info.vehicle_model_id)，订单用车弹窗将无法展示车型信息` | 小蒙马（GROUP）按 `vehicle_type` 自动匹配专用车，此校验仅对 CORE/CUSTOM 生效 | - -对**酒店/餐饮/车型仍然确实缺配置**的产品，新的校验会继续报错（以新的文案），前端展示无需调整。 - -保留/新增的典型错误文案参考： - -- `所有行程日餐饮均自理，订单详情餐饮弹窗将为空`（取代老的"缺少餐饮节点"） -- `缺少酒店配置，订单详情住宿弹窗将为空`（取代老的"缺少酒店节点"） - ---- - -## 四、前端行动项 - -1. **产品列表多值筛选**：如果前端有以下 workaround，可以移除： - - 前端循环调用 `productType=CORE` + `productType=GROUP` 再合并 - - 前端本地过滤（全量拉取后 `.filter`） - - 隐藏多选框强制单选 -2. **上架预检错误展示**：无需改动。测试环境验证小蒙马产品 `id=2044306857534636034` 现在点"发布"应该能直接上架。 -3. **其他产品类型**：CORE/CUSTOM 的上架预检行为**与此前完全一致**，车型校验仍生效。 - ---- - -## 五、测试环境已验证 - -```bash -# Bug 1 验证 -GET /admin/product/item/list?status=PUBLISHED&productType=CORE,GROUP -→ { code: 200, data: { total: 9, records: [...9 条...] } } - -# Bug 2 验证 -GET /admin/product/item/2044306857534636034/validate-publish -→ { code: 200, data: [] } -``` diff --git a/changelogs/2026-04/2026-04-19_schedule-max-participants-required.md b/changelogs/2026-04/2026-04-19_schedule-max-participants-required.md deleted file mode 100644 index 8be56d0..0000000 --- a/changelogs/2026-04/2026-04-19_schedule-max-participants-required.md +++ /dev/null @@ -1,75 +0,0 @@ -# fix: 小蒙马班期保存 maxParticipants 改为必填字段 - -> **服务**: hl-product-service-v2 -> **PR**: #927 -> **Issue**: #859 -> **日期**: 2026-04-19 -> **前端是否需要改动**: **需要改动**（之前允许不传或传 null，现在必须显式传数字；0=不限） - ---- - -## 一、背景 - -测试环境反馈前端保存班期时缺传 `maxParticipants` 会收到模糊的"违反约束"报错，用户无法分辨是哪个字段出问题。 - -后端之前 `ScheduleSaveReqVO.maxParticipants` 只用 `@ApiModelProperty(required=true)` 做了文档标记，Bean Validation 层未强制校验，结果 null 一路打到 SQL 层才报错。 - -## 二、变更接口 - -| 方法 | 路径 | 变更类型 | -|------|------|---------| -| POST | `/admin/product/item/{id}/schedule` | 请求体字段校验收紧 | -| POST | `/admin/product/item/{id}/schedule/batch-create` | 同上 | - -## 三、字段约束变化 - -| 字段 | 之前 | 现在 | 允许值 | -|------|------|------|--------| -| `maxParticipants` | 可不传 / null（后端兜底 0） | **必传** | 0=不限；>0=上限人数 | - -## 四、错误响应示例 - -### 缺传 maxParticipants - -```json -POST /admin/product/item/123/schedule -{ - "batchName": "五一特别团", - "departureDate": "2026-05-01", - "adultPrice": 5160, - "childPrice": 4580 -} - -// 响应（之前是 "数据操作违反约束，请检查输入"，歧义） -{ - "code": 400, - "message": "最大参与人数不能为空", - "success": false -} -``` - -### 正常请求 - -```json -POST /admin/product/item/123/schedule -{ - "batchName": "五一特别团", - "departureDate": "2026-05-01", - "adultPrice": 5160, - "childPrice": 4580, - "maxParticipants": 30, // 必填 - "maxRooms": 15 // 可选，默认取行程最少房间数 -} -``` - -## 五、前端改动建议 - -1. **班期创建/编辑表单**：`maxParticipants` 输入框加前端必填校验，避免到后端才被拦下 -2. **批量创建表单**：同上 -3. **提示文案**：如果字段空值，提示"最大参与人数不能为空，0 表示不限人数" - -## 六、兼容性 - -- 前端原本填写 0 或具体数字的调用方不受影响 -- 前端如有"不填=不限"的历史 UX，需改成"显式填 0=不限" -- 后端 Service 层 null→0 兜底代码保留作为双保险，但实际不会再走到 diff --git a/changelogs/2026-04/2026-04-20-cityselect-tag-stringify-bug.md b/changelogs/2026-04/2026-04-20-cityselect-tag-stringify-bug.md deleted file mode 100644 index 169ea2c..0000000 --- a/changelogs/2026-04/2026-04-20-cityselect-tag-stringify-bug.md +++ /dev/null @@ -1,254 +0,0 @@ -# fix(前端): CitySelect 集合地/解散地下拉显示 JSON 字符串而非城市名 - -- **类型**: BUG（前端） -- **优先级**: P1（核心产品编辑功能体验严重异常） -- **影响端**: 管理后台（hl-ui） -- **后端是否需改动**: ❌ 不需要。DB / API 数据完全正确，本次修复仅前端 -- **是否影响保存**: ❌ 不影响。保存数据完全正确，仅显示层 BUG，前端可放心修 -- **任务文件**: `D:/work2/HL/docs/tasks/20260420_修复_行程开始结束下拉显示JSON.md` -- **报 BUG 时间**: 2026-04-20（wx 截图反馈） - ---- - -## 一、现象描述 - -### 触发路径 -管理后台 → **产品编辑** → **行程编排** → **任意 DAY**（截图为 DAY 3「莫日格勒河之旅」） - -页面 URL 示例：`http://192.168.100.160:9527/product/edit?id=2045018534152478721` - -### 字段名说明（重要：截图标签 ≠ 代码字段名 ≠ 设计文档名） - -| 截图上显示 | 设计文档 / 业务术语 | 前端 v-model | 后端字段 | DB 列 | -|-----------|---------------------|-------------|---------|-------| -| **开始** | 集合地 | `gatherPlace` | `gatherPlace` | `gather_place` | -| **结束** | 解散地 | `dismissalPlace` | `dismissalPlace` | `dismissal_place` | - -> 即截图所说的「开始 / 结束」就是「集合地 / 解散地」就是 `gatherPlace / dismissalPlace`。三套名字完全等价。 - -### 错误现象 -两个下拉框（CitySelect 实例）的**已选中显示文本**直接渲染成了 JSON 字符串： - -``` -{"name":"黑山头镇","level"... -{"name":"海拉尔区","level"... -``` - -### 期望现象 -应该只显示城市名，例如： -- 「黑山头镇」或 fullPath「内蒙古自治区/呼伦贝尔市/额尔古纳市/黑山头镇」 -- 「海拉尔区」或 fullPath「内蒙古自治区/呼伦贝尔市/海拉尔区」 - -### 对照参考（同 DAY 内显示正常的元素） -- 同一 DAY 的 **「途经路线」** 显示正常：黑山头镇 → 白桦林景区 → 莫日格勒河 → 海拉尔区 -- 这部分走的是 `<span>{{ pt.name }}</span>` 直接渲染（`RouteTagBar.vue` 行 70-82），**不经过 n-select**，所以不会触发本 BUG。 - ---- - -## 二、根因分析（前端 BUG，已通过三尺定位确认） - -### 三尺数据验证 -1. **DB 真值**（`hl_product_service.product_itinerary_day` 表）✅ 数据合法： - ```json - {"name":"黑山头镇","level":"street","adcode":"150784","fullPath":"内蒙古自治区/呼伦贝尔市/额尔古纳市/黑山头镇","levelName":"镇"} - ``` -2. **API 响应**（GET `/admin/product/item/{id}`）✅ 原样返回 dict（`JsonObjectTypeHandler` 自动反序列化为 `LinkedHashMap`），契约一致。 -3. **前端渲染**（`CitySelect.vue` + `n-select` `tag` 模式）❌ **BUG 在此** - -### 直接 BUG 文件 -**文件**：`D:/work2/hl-ui/src/components/CitySelect.vue` - -**关键代码段**： - -```js -// 行 58-64：n-select 的 value 永远是 stringify 字符串 -const currentValue = computed(() => { - if (!props.value) return null - if (props.nameOnly) return props.value || null - return JSON.stringify(props.value) // → '{"name":"黑山头镇","level":...}' -}) - -// 行 143-161：watch immediate，仅当 options 为空时注入 1 项 -watch(() => props.value, (newVal) => { - if (newVal && options.value.length === 0) { - options.value = [{ - label: formatLabel(newVal), - value: JSON.stringify(newVal), - tip: newVal, - }] - } -}, { immediate: true }) -``` - -**模板**（行 164-180）： -```html -<n-select - :value="currentValue" <!-- '{"name":"黑山头镇",...}' --> - :options="options" - filterable remote tag <!-- ⚠️ 关键：tag 模式 --> - :filter="() => true" - ... -/> -``` - -### 根因机制（n-select tag 模式 + watch 时序竞态） -1. n-select 启用 `tag` 模式后，若传入的 `value`（已是 stringify 后的 JSON 串）在初次渲染时**尚未在 `options` 中匹配到**，会把 value 字符串本身**当作"用户已创建的标签"**渲染出来，并**缓存该标签**。 -2. `watch` 虽然 `immediate: true` 注入 option，但因 `props.value` 在 setup 阶段可能为 null（store 异步加载详情数据）→ watch 跳过 → options 为空。 -3. 后续 store 注入数据触发 watch 再补 option 时，**n-select 已经把"未匹配 value"渲染成 stringify 标签了**，并不会回头重新匹配 label。 - -### 直接证据链 -- DAY 3 `dismissalPlace.name` 是「海拉尔区」→ 截图显示 `{"name":"海拉尔区","level"...` -- 截图字符串 = `JSON.stringify(props.value)` 的前缀，与代码逻辑完全吻合 -- 同 DAY 的 `routePoints` 走 span 渲染，正常显示城市名 - -### 同组件其他用法是否受影响 -- **`searchForm.cityName`**（restaurant 搜索栏）：使用 `nameOnly` 模式，**不受影响** -- **`RouteTagBar.vue` 中的 gather/dismissal**：完整 dict 模式，**受影响** - ---- - -## 三、修复方案（前端 AI 三选一） - -### 方案 A（⭐ 推荐，根治 + 改动最小） - -**操作**：删 `D:/work2/hl-ui/src/components/CitySelect.vue` **行 176** 的 `tag` 属性。 - -```diff - <n-select - :value="currentValue" - :options="options" - ... - filterable - remote -- tag - :filter="() => true" - @search="handleSearch" - @update:value="handleChange" - /> -``` - -**效果**： -- n-select 进入"严格枚举"模式，找不到 option 时显示 placeholder 而不是把 value 当 tag 渲染。 -- watch 行 143-161 保留（保证刷新页面时 options 至少有当前 value 一项），覆盖回显场景。 - -**风险点**： -- 原 `tag` 用于让用户在搜索结果之外手动输入新城市；但本组件 `searchDistrict` 已通过 `?keywords=` 远程搜（高德 API 覆盖全国行政区划），业务上**不需要 tag**。 -- 如担心兜底，走方案 B 或 C。 - ---- - -### 方案 B（最小侵入，保留 tag 能力） - -把 watch 改为同步 `watchEffect`，并保证 options 在每次 `props.value` 变化时**强制覆盖**（去掉 `length === 0` 短路条件）： - -```js -import { watchEffect } from 'vue' - -watchEffect(() => { - const v = props.value - if (!v) return - if (props.nameOnly) { - options.value = [{ label: v, value: v }] - } else { - const stringified = JSON.stringify(v) - const exists = options.value.some(o => o.value === stringified) - if (!exists) { - options.value = [ - { label: formatLabel(v), value: stringified, tip: v }, - ...options.value - ] - } - } -}) -``` - -**效果**： -- 保证 `props.value` 一变化（包括 store 异步注入），option 立即对齐，n-select 能匹配到 label，不走 tag 字符串渲染分支。 - -**风险点**： -- 仍依赖 n-select 内部"是否已渲染过 tag"的状态机。在某些极端时序下（首帧 value 已注入但 options 尚未更新到 DOM）仍可能有 1 帧闪烁。 - ---- - -### 方案 C（兼容性最好，不动任何业务逻辑） - -n-select 增加 `:render-tag` 自定义渲染函数，强制把 tag 显示成 `props.value.fullPath || props.value.name`，与 options.label 一致。 - -```html -<n-select - ... - :render-tag="renderTag" -/> -``` - -```js -import { h } from 'vue' - -function renderTag({ option }) { - // option.tip 是 watch 注入时存的原始 dict - const dict = option.tip || (typeof option.value === 'string' ? safeParse(option.value) : null) - if (!dict) return option.label || option.value - return h('span', null, dict.fullPath || dict.name) -} - -function safeParse(s) { - try { return JSON.parse(s) } catch { return null } -} -``` - -**效果**： -- 即使 n-select 把未匹配 value 当 tag 渲染，自定义 renderTag 也能保证显示文本是城市名。 - -**风险点**： -- naive-ui 的 `render-tag` API 行为在不同版本可能略有差异（建议先看一眼当前使用的 naive-ui 版本文档）。 - ---- - -## 四、验收标准（修完请前端自查） - -- [ ] 进入产品编辑页（任意已有 gather_place 的产品，例如 `http://192.168.100.160:9527/product/edit?id=2045018534152478721`），DAY 3「开始 / 结束」下拉框显示城市名（不再是 JSON 字符串） -- [ ] 切换不同 DAY，每个 DAY 的「开始 / 结束」均正常显示 -- [ ] 点开下拉框，远程搜索其他城市仍可正常切换 -- [ ] 切换后保存产品，重新打开编辑页，回显的城市仍正确 -- [ ] restaurant 搜索栏的城市筛选（CitySelect nameOnly 模式）功能未受影响 - ---- - -## 五、影响面 - -- **同组件复用点**： - - `searchForm.cityName`（restaurant 搜索栏，nameOnly 模式）→ 不受影响 - - `RouteTagBar.vue` 中的 gather / dismissal → **受影响** -- **受影响产品数**：所有 `gather_place` / `dismissal_place` 不为空的产品的编辑页均中招。 -- **是否影响保存**：**不影响**。store 里 `productData.itinerary[i].gatherPlace` 仍是后端返回的合法 dict，保存时 `transformToSaveDays`（行 460-470）原样回传，**保存数据正确**。仅"显示"层 BUG。 -- **是否影响校验**：不影响。校验 `day.gatherPlace?.name`（ItineraryStep.vue 行 32）能拿到 name。 - ---- - -## 六、后端附加提醒（非阻塞，不需要本次修，记录在册） - -`hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductItinerarySaveReqVO.java` 行 40 / 44： - -```java -@ApiModelProperty(value = "集合地(高德行政区JSON)", required = true, notes = "{name,adcode,center,level}") -private Object gatherPlace; - -@ApiModelProperty(value = "解散地(高德行政区JSON)", required = true, notes = "{name,adcode,center,level}") -private Object dismissalPlace; -``` - -**问题**：`notes` 注释里写的字段集 `{name,adcode,center,level}` 与 DB / API 实际字段集 `{name,level,adcode,fullPath,levelName}` 不一致： -- 多了 `fullPath` / `levelName` -- 少了 `center` - -**建议**：等本次前端 BUG 修复确认无问题后，下个批次同步注释为 `{name,level,adcode,fullPath,levelName}` 并明确"此字段透传，至少包含 `name` 用于显示"。本次不动。 - ---- - -## 七、参考文件路径 - -- 受影响组件：`D:/work2/hl-ui/src/components/CitySelect.vue`（第 176 行 `tag` 是元凶） -- 调用方：`D:/work2/hl-ui/src/views/product/edit/components/itinerary/RouteTagBar.vue` 行 48-66 -- store：`D:/work2/hl-ui/src/store/productEdit.js#loadDetail` 行 255-335 / `transformToSaveDays` 行 460-470 -- 后端 VO：`D:/work2/HL/hl-product-service-v2/src/main/java/com/hulalv/vo/admin/ProductItinerarySaveReqVO.java` -- 任务文件（含完整三尺定位）：`D:/work2/HL/docs/tasks/20260420_修复_行程开始结束下拉显示JSON.md` diff --git a/changelogs/2026-04/2026-04-20-dict-color-product-tag.md b/changelogs/2026-04/2026-04-20-dict-color-product-tag.md deleted file mode 100644 index 190a485..0000000 --- a/changelogs/2026-04/2026-04-20-dict-color-product-tag.md +++ /dev/null @@ -1,198 +0,0 @@ -# 字典加颜色字段 + 产品线主题标签字典化（前端要改） - -**日期**：2026-04-20 -**PR**：#1017（Closes Issue #1016） -**合并到 dev commit**：0dc2cb8c -**后端服务**：hl-user-service（实质改动）+ hl-product-service-v2（仅 VO 注释完善） -**影响**：管理端「字典管理」表单 + 「产品线/主题」编辑弹窗 - ---- - -## 为什么变 - -两件事一起做： - -1. **字典数据项加 `color` 字段**：`sys_dict_data` 全局加可选 hex 颜色值，方便所有字典（不只是 product_tag）都能配色 -2. **产品线（主题）的「标签」从自由输入改为字典选择**：使用 `product_tag` 字典，标签存 dict_value（英文 code），展示用 dict_label（中文）+ color（颜色渲染） - -> 后端「字典管理 CRUD + 产品线 VO 注释」全部就绪，**`product_tag` 字典本身的数据由 wx 在字典管理页录入，本次不预置业务数据**。 - ---- - -## 接口契约变化 - -### 1. 字典 CRUD —— 新增 `color` 字段 - -**类型**：`string | null`，hex 格式 `#RGB` / `#RRGGBB` / `#RRGGBBAA`，可为空字符串 -**校验**：后端正则 `^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$|^$`，传 `red` / `#XYZ` 等非 hex 会被 400 拒绝 - -#### POST /admin/dict/data - -```jsonc -{ - "dictType": "product_tag", - "dictLabel": "亲子游", - "dictValue": "PARENT_CHILD", - "icon": "🏖️", - "color": "#FF5722", // ⭐ 新增可选 - "sortOrder": 10, - "remark": "亲子主题标签" -} -``` - -#### PUT /admin/dict/data/{id} - -```jsonc -{ - "dictLabel": "亲子游", - "color": "#FF5722" // ⭐ 新增可选；不传则不覆盖 -} -``` - -> PUT 语义：字段缺失 = 不改；传 `null` = 不改；传空字符串 `""` = 清空 - -#### GET 类接口 —— 响应新增 `color` - -| Method | Path | 变化 | -|---|---|---| -| GET | `/admin/dict/data/{id}` | 响应新增 `color`（NULL 时省略） | -| GET | `/admin/dict/data/{dictType}` | 响应每项新增 `color`（NULL 时省略） | -| GET | `/admin/dict/all` | 响应每项新增 `color`（NULL 时省略） | -| GET | `/dict/all`（公开，无需 token） | `dataList[].color`（NULL 时省略） | - -**重要**：`color` 用了 `@JsonInclude(NON_NULL)`，**老字典 / 没配色的字典项响应里不会有 `color` 这个 key**，前端解构时记得用可选链 / 默认值，不要 `data.color.toUpperCase()` 这种硬解构。 - -#### `/dict/all` 公开接口响应样例 - -```jsonc -{ - "code": 200, - "data": [ - { - "dictType": "product_tag", - "dictName": "产品标签", - "dataList": [ - { - "dictValue": "PARENT_CHILD", - "dictLabel": "亲子游", - "icon": "🏖️", - "color": "#FF5722", // ⭐ 配了色就有 - "sort": 1, - "remark": null - }, - { - "dictValue": "SELF_DRIVE", - "dictLabel": "自驾", - "icon": null, - // ⭐ 没配色就没有 color 字段（NON_NULL） - "sort": 2, - "remark": null - } - ] - } - ] -} -``` - ---- - -### 2. 产品线 VO（无字段类型变化，仅注释完善） - -| 文件 | 字段 | 改动 | -|---|---|---| -| `ProductLineSaveReqVO.tags` | `List<String>` | 注释从「标签」改为「标签(product_tag字典的dict_value英文code列表，无数量上限，可为空)」+ example=`PARENT_CHILD,SELF_DRIVE` | -| `ProductLineRespVO.tags` | `List<String>` | 注释从「产品线标签」改为「产品线标签(product_tag字典的dict_value英文code列表，可为空)」+ example=`PARENT_CHILD,SELF_DRIVE` | - -**接口签名 0 变化**：`POST /admin/product/line` / `PUT /admin/product/line/{lineId}` / `GET /admin/product/line/{lineId}` 的 `tags` 字段类型仍是 `string[]`，前端字段类型不需要改，**只是语义换了**： - -- 旧语义：自由文本数组（用户随便输入） -- 新语义：`product_tag` 字典的 **dict_value（英文 code）** 数组 - -后端**不强制校验** tags 必须在 product_tag 字典中（兼容老数据 + 留前端逐步迁移空间）。 - ---- - -## 前端要做的事 - -### 1. 字典管理页 —— CRUD 表单加「颜色值」输入 - -- 在 `dictLabel` / `icon` 旁边加一个「颜色值」输入框 -- 推荐控件：**ColorPicker**（最佳）；或简单 hex 文本框（placeholder：`#FF5722`，可为空） -- **校验**：前端可不做（后端会校验），但建议加 hex 正则提示提升体验 -- 列表展示：在 dictLabel 旁渲染一个小色块（`<span style="background:{color}">`），无 color 时不渲染或灰色占位 - -### 2. dict store —— 自动透传，无需改代码 - -- `useDictStore` 内部按 `/dict/all` 整个对象塞入，每个 dataItem 多一个 `color` key 自动透传给业务页面 -- `getDictOptions(dictType)` 返回的每项都会带 `color`（如果配了） -- 业务侧使用：`option.color || '#999'`（默认色逻辑由前端决定） - -### 3. 产品线（主题）编辑弹窗 —— 标签控件改造 - -**这是本次最大的前端改造点。** 文件位置参考：`hl-ui/src/views/product-v2/line/index.vue:312` 附近。 - -**控件替换**： - -- 旧：`n-dynamic-tags`（用户自由输入字符串） -- 新：`n-select` 多选模式，options 来自 `useDictStore().getDictOptions('product_tag')` - -```js -// 伪代码示意 -const tagOptions = computed(() => - dictStore.getDictOptions('product_tag').map(item => ({ - label: item.dictLabel, // 中文展示 - value: item.dictValue, // 英文 code 入库 - color: item.color, // 用于自定义渲染 - })) -) -``` - -**多选无上限**（沿用现有自由度）。 - -**自定义渲染**（重点）： - -- `n-select` 的 `render-tag` / `render-label` slot 用 `option.color` 给 chip 上色 -- 卡片展示标签也按 color 渲染（`hl-ui/src/views/product-v2/line/index.vue:125-136` 那块卡片标签 chip） - -```vue -<n-tag :color="{ color: option.color || '#999', textColor: '#fff' }"> - {{ option.label }} -</n-tag> -``` - -### 4. 老数据兼容（关键） - -现有 `product_line.tags` 里很可能存的是老的**自由文本**（中文随手输入），不是字典 code： - -- **不要把 tags 里不在 product_tag 字典里的值过滤掉** —— 这会悄悄丢数据 -- **建议展示**：老 tag 值在 n-select 里按字符串原样回填（`v-model:value` 数组里塞进去），找不到对应 option 时按文本展示，灰色提示「已下架/未识别标签」 -- 用户保存时引导用户从 product_tag 字典里重新选，保存后老值就被覆盖 - -后端**保存时不校验** tags 必须在字典中，所以前端就算把老中文文本一起传上来也不会被拒。 - ---- - -## 兼容性 / 不影响的地方 - -- **老字典 color 为 null 时**：`/dict/all` 响应里就没有 `color` 这个 key（NON_NULL），前端按"无 color = 默认色（建议 #999 灰）"处理即可 -- **老 product_line.tags 自由文本仍可显示**：n-select 多选模式可以容纳"不在 options 里的值"（按 NaiveUI 文档 `tag` 模式或回退到字符串展示） -- **mp 端产品线展示**：当前 mp 端 `MpProductLineVO` **没有 tags 字段**，本次也不加。如果以后小程序要展示标签 + 颜色，等明确需求再做 - ---- - -## 不在本次范围 - -- ❌ **不预置 product_tag 字典数据**：交付能力，wx 在字典管理页手动录入业务标签项 -- ❌ **不做老 product_line.tags 数据迁移**：现存自由文本由用户后续手工编辑替换 -- ❌ **不动 ProductDO 的 tags 字段**（产品本身的 tags 走另一个 product_tag 字典使用，已是单选，见 [2026-04-20_product-tag-single-select.md](./2026-04-20_product-tag-single-select.md)）—— 本次只动「产品线/主题」的 tags -- ❌ **不动 mp 端**：`/mp/product/line/*` 接口 tags 不返回，零前端改造影响 - ---- - -## 验证 - -- ✅ 测试环境 hl-user-service 已部署（commit 0dc2cb8c） -- ✅ POST /admin/dict/data 带 `color` 字段保存成功 -- ✅ GET /dict/all 配过 color 的项响应带 color，未配的项无 color key -- ✅ POST /admin/dict/data 传 `color: "red"` 返回 400 校验错误 -- ⏳ 前端 dict 管理页加 ColorPicker + 产品线弹窗改 n-select 后，wx 在字典管理页录入 product_tag 字典项 diff --git a/changelogs/2026-04/2026-04-20_admin-product-list-tier-prices.md b/changelogs/2026-04/2026-04-20_admin-product-list-tier-prices.md deleted file mode 100644 index 0e65417..0000000 --- a/changelogs/2026-04/2026-04-20_admin-product-list-tier-prices.md +++ /dev/null @@ -1,207 +0,0 @@ -# feat: 管理端产品列表 `/admin/product/item/list` 响应新增 `tierPrices` 档位价格摘要 - -- **日期**: 2026-04-20 -- **PR**: [#955](https://git.1814.love:8443/wx/HL/pulls/955) (Closes #954) -- **类型**: FEATURE（响应新增字段，无破坏性变更） -- **服务**: hl-product-service-v2 -- **前端是否需要改动**: **建议改动**（管理端产品列表新增"档位摘要"列展示） - ---- - -## 一、为什么加这个字段 - -管理端产品管理列表此前每行只能看到： -- `tierCount`（档位总数） -- `startPrice`（产品起步价 = 所有档位最低） - -但运营在列表里需要快速判断**每个档位是否已定价**、**哪个档位起步价多少**，否则要点进详情页一个个看，效率低。 - -本次新增 `tierPrices` 字段：**列表页保留无价档位**（startPrice=null），让前端可以一眼看出"档位待定价"的状态。 - ---- - -## 二、变更接口清单 - -| # | 方法 | 路径 | 影响 | -|---|------|------|------| -| 1 | GET | `/admin/product/item/list` | 响应 `records[]` 每项新增 `tierPrices` 字段（数组） | - -**其他接口不变**： -- `GET /admin/product/{id}`（产品详情）：**行为零变化**。详情接口的 `tierPrices` **仍剔除无价档位**，与本次列表接口语义不同（见第五节）。 -- 既有的 `tierCount` / `startPrice` 字段保留，不受影响。 - ---- - -## 三、字段定义 - -### 新增 `tierPrices`（数组） - -每个产品记录新增 `tierPrices: TierPriceItem[]`，结构： - -| 字段 | 类型 | 说明 | 可能为 null | -|------|------|------|-------------| -| `tierSeq` | Integer | 档位序号（从 1 起） | 否 | -| `tierName` | String | 档位名称（如"经济档"/"舒适档"/"豪华档"） | 否 | -| `tierDescription` | String | 档位描述（产品配置时填写） | 是（未填即 null） | -| `startPrice` | BigDecimal | **该档位**未来日期的最低售价；**无价档位返回 null** | **是** ⚠️ | - -### 既有字段（保留，不变） - -| 字段 | 说明 | -|------|------| -| `tierCount` | 档位总数（包含无价档位） | -| `startPrice` | 产品起步价（所有档位中最低；CORE/CUSTOM 取自 `product_price_calendar`，GROUP 同详情口径） | - ---- - -## 四、响应示例对比 - -### 前 - -```json -{ - "code": 200, - "data": { - "total": 25, - "records": [ - { - "id": 1001, - "name": "小蒙马·呼伦贝尔5日", - "productType": "GROUP", - "tierCount": 3, - "startPrice": 4580.00 - } - ] - } -} -``` - -### 后 - -```json -{ - "code": 200, - "data": { - "total": 25, - "records": [ - { - "id": 1001, - "name": "小蒙马·呼伦贝尔5日", - "productType": "GROUP", - "tierCount": 3, - "startPrice": 4580.00, - "tierPrices": [ - { - "tierSeq": 1, - "tierName": "经济档", - "tierDescription": "标准住宿+常规交通", - "startPrice": 4580.00 - }, - { - "tierSeq": 2, - "tierName": "舒适档", - "tierDescription": "四星住宿+商务车", - "startPrice": 5160.00 - }, - { - "tierSeq": 3, - "tierName": "豪华档", - "tierDescription": "五星住宿+豪华车", - "startPrice": null - } - ] - } - ] - } -} -``` - -> 第 3 个档位 "豪华档" 未配价格 → `startPrice: null`，前端可展示为"档位待定价"。 - ---- - -## 五、列表 vs 详情语义差异（重要） - -| 接口 | 无价档位（startPrice=null）处理 | -|---|---| -| **列表 `/admin/product/item/list`**（本次） | **保留**，`startPrice=null`，便于运营在列表里识别 | -| **详情 `/admin/product/{id}`**（不变） | **剔除**，`tierPrices` 中只保留有价档位 | - -> 这个差异是设计意图：详情页面向"已成型可售产品"，列表页面向"运营治理"。 - ---- - -## 六、GROUP 类型的特别说明 - -| 产品类型 | 列表 `tierPrices[].startPrice` 数据源 | -|---|---| -| `CORE` / `CUSTOM` | `product_price_calendar` 表（按档位 + 日期取未来最低） | -| `GROUP`（小蒙马） | 仍走 `product_price_calendar`，**与详情接口口径一致** | - -⚠️ **已知偏差**：GROUP 真实成交价存在 `group_tour_batch.adult_price`（班期表），与日历价可能存在差异。这是已知问题，本次不修复，保持与详情接口同口径以避免列表/详情数字不一致。 - ---- - -## 七、前端使用建议 - -### 推荐：列表新增"档位摘要"列 - -```vue -<el-table-column label="档位摘要" min-width="240"> - <template #default="{ row }"> - <div v-for="t in row.tierPrices" :key="t.tierSeq" class="tier-line"> - <span class="tier-name">{{ t.tierName }}</span> - <span v-if="t.startPrice != null" class="tier-price"> - 起 ¥{{ t.startPrice }} - </span> - <el-tag v-else type="warning" size="small">待定价</el-tag> - </div> - </template> -</el-table-column> -``` - -### ⚠️ 容错要求 - -- `tierPrices[].startPrice` **可能为 null**（无价档位），必须做 null 判断后再格式化金额，避免 `undefined.toFixed()` 报错 -- `tierDescription` 可能为 null，渲染时做空值兜底 -- `tierPrices` 数组本身不会为 null（无档位时为空数组 `[]`） - ---- - -## 八、不兼容变更 - -**无**。纯新增字段，前端不读不受影响；既有 `tierCount` / `startPrice` 字段保留，含义与之前完全一致。 - ---- - -## 九、回归验证 - -测试环境部署完成后，用管理端 token 调用： - -```bash -# 1. 列表接口检查 tierPrices 字段存在 -curl "https://api.test.1814.love/admin/product/item/list?pageNo=1&pageSize=10" \ - -H "Authorization: Bearer {admin-token}" \ - | jq '.data.records[0] | {id, name, tierCount, startPrice, tierPrices}' - -# 预期：tierPrices 字段存在；数组长度 == tierCount；含无价档位时 startPrice=null - -# 2. 详情接口对比（应仍剔除无价档位） -curl "https://api.test.1814.love/admin/product/{id}" \ - -H "Authorization: Bearer {admin-token}" \ - | jq '.data.tierPrices' - -# 预期：详情接口的 tierPrices 长度 ≤ 列表接口（剔除了无价档位） - -# 3. GROUP 产品（小蒙马）口径核对 -curl "https://api.test.1814.love/admin/product/item/list?productType=GROUP&pageNo=1&pageSize=5" \ - -H "Authorization: Bearer {admin-token}" \ - | jq '.data.records[] | {id, productType, tierPrices}' - -# 预期：GROUP 产品的 tierPrices[].startPrice 与详情接口一致（同走 product_price_calendar） -``` - -**预期**： -- 列表新字段 `tierPrices` 必出现 -- 无价档位 `startPrice: null` 而非被剔除 -- 与详情接口语义差异符合第五节说明 diff --git a/changelogs/2026-04/2026-04-20_bug-batch-fixes.md b/changelogs/2026-04/2026-04-20_bug-batch-fixes.md deleted file mode 100644 index df89d51..0000000 --- a/changelogs/2026-04/2026-04-20_bug-batch-fixes.md +++ /dev/null @@ -1,131 +0,0 @@ -# 第一期 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<DayItem>`，按 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 <token>` 让后端从中提取）。 - -### 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_dict-icon-field.md b/changelogs/2026-04/2026-04-20_dict-icon-field.md deleted file mode 100644 index 6c3d1f0..0000000 --- a/changelogs/2026-04/2026-04-20_dict-icon-field.md +++ /dev/null @@ -1,121 +0,0 @@ -# 字典数据项新增 icon 图标字段 - -**日期**：2026-04-20 -**PR**：#994（Closes #993） -**影响**：管理端字典管理页、所有使用字典的展示组件 - ---- - -## 为什么变 - -`sys_dict_data` 原先只有 `dict_label` / `dict_value` / `sort_order` / `remark`，部分业务场景（如活动分类、房型、状态等级）希望能给字典项配图标用于前端可视化（活动卡片角标、状态彩色 Dot、Tab 图标等）。本次加一个 `icon` 字段（TEXT，允许为空），字典 CRUD 和所有读取接口全部透传。 - -## 接口契约变化 - -### 新字段 - -所有字典数据项（`DictDataVO` 及 Entity 序列化）新增： - -```ts -{ - "icon": "https://cdn.example.com/icons/camp.png" | null -} -``` - -**类型**：`string | null`（可为 URL、emoji、base64 data URL，旧数据默认 `null`） - -### 受影响接口 - -| Method | Path | 变化 | -|---|---|---| -| POST | `/admin/dict/data` | **请求体**新增可选 `icon`；**响应**新增 `icon` | -| PUT | `/admin/dict/data/{id}` | **请求体**新增可选 `icon`（不传则不覆盖）；**响应**新增 `icon` | -| GET | `/admin/dict/data/{id}` | 响应新增 `icon` | -| GET | `/admin/dict/data/{dictType}` | 响应每项新增 `icon` | -| GET | `/admin/dict/all` | 响应每项新增 `icon` | -| GET | `/dict/all`（公开，无需 token） | 响应每项 `dataList[].icon` | - -> `/internal/mp/**` 是服务间 Feign 内部接口，前端不直接调用，此处略。 - -### 响应样例 - -```jsonc -// GET /admin/dict/all -{ - "code": 200, - "data": [ - { - "dictType": "activity_billing_type", - "dictName": "计费方式", - "dataList": [ - { - "dictValue": "PER_PERSON", - "dictLabel": "按人", - "icon": "https://cdn.example.com/icons/per-person.png", // ⭐ 新增 - "sort": 1, - "remark": null - }, - { - "dictValue": "PER_GROUP", - "dictLabel": "按组/团", - "icon": null, // 旧数据默认 null - "sort": 2, - "remark": null - } - ] - } - ] -} -``` - -```jsonc -// POST /admin/dict/data 请求体 -{ - "dictType": "activity_category", - "dictLabel": "骑马", - "dictValue": "HORSEBACK", - "icon": "https://cdn.example.com/icons/horse.png", // ⭐ 可选 - "sortOrder": 10, - "remark": "骑马体验项目" -} -``` - -```jsonc -// PUT /admin/dict/data/{id} 请求体（只传要改的字段；不传 icon 不覆盖） -{ - "icon": "emoji:🏕" -} -``` - ---- - -## 前端改造建议 - -### 管理端 —— 字典管理页 - -- **字典项创建/编辑弹窗**：在 `dictLabel` 旁新增「图标」输入框 - - 建议 placeholder："图标 URL / emoji / base64 data URL，可为空" - - 不做正则校验（后端 TEXT，无上限），由用户自己把控 - - 提交时 `icon` 传空字符串即落库空串；不想改就别带这个字段（PUT 语义是"字段缺失 = 不改"） -- **字典数据列表**：在 dictLabel 右侧展示一个小图标预览（URL 就 `<img>`，emoji 就文本，base64 就 `<img>`），null 留空 - -### 小程序端 / 管理端业务页 - -- 调 `/dict/all` 或 `/admin/dict/all` 时，每个 `dataList[].icon` 都能拿到 -- 展示组件里按 `icon != null` 条件渲染，比如： - - 分类 Tab：`icon ? <img src=icon /> : null` + `label` - - 状态 Badge：`icon` 可以是 emoji 或彩色圆点 URL -- icon 内容不固定，前端按它的形态（http(s) URL / emoji 文本 / `data:image/...` base64）自适应渲染即可 - ---- - -## 不影响的接口 - -- `/admin/dict/type` 相关（字典类型 CRUD / 分页） -- 现有响应结构中已有的字段全部保持，只是**每个字典数据项多一个 `icon` 字段** -- 旧数据 `icon = null`，前端没做处理也不会报错，但展示上就没图标 - -## 缓存 - -- 后端字典缓存（Redis，5min TTL）会在字典数据 CRUD 后通过 `CacheEvictAfterCommit` 自动清，icon 更新后下一次读就能拿到新值（最坏延迟 = 事务提交 + 单次请求） -- 前端 `/dict/all` 通常也有本地缓存，建议管理端配置 icon 后引导用户 F5 或重新拉一次字典 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 deleted file mode 100644 index 436338d..0000000 --- a/changelogs/2026-04/2026-04-20_early-bird-multi-plan.md +++ /dev/null @@ -1,145 +0,0 @@ -# 早鸟优惠改造：产品 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<v<100) - "priority": 0 // NEW 同区间多命中决胜，默认 0 -} -``` - -### 2. 响应 VO 新增字段 - -`EarlyBirdPlanVO`（列表/详情）新增后端拼好的**文案字段**： - -```ts -{ - "peopleRangeText": "3-5 人", // NEW 例："2 人"/"3-5 人"/"6 人及以上" - "discountText": "85 折", // NEW 例："9 折"/"每人立减 100 元"/"整单立减 500 元" - // ... 其他 4 个新业务字段（maxPeople/discountType/discountPercent/priority） -} -``` - -前端可直接用 `peopleRangeText` 和 `discountText` 做展示，无需自己拼。 - -### 3. 不再校验产品唯一 - -`POST /admin/order/early-bird` 去掉 `以下产品已绑定其他早鸟计划，不能重复绑定` 校验。同一 `productId` 可出现在任意多个方案。 - -### 4. 小程序产品详情页新增字段 - -**`GET /mp/product/item/{id}`** 响应 `MpProductDetailRespVO` 新增： - -```ts -{ - "earlyBirdTip": "最低 8 折起（共 3 档早鸟方案）", // 无人数上下文的概览文案，无绑定=null - "earlyBirdLadder": [ // 早鸟阶梯（按 min_people 升序） - { - "planId": "123", - "peopleRangeText": "2 人", - "discountText": "9 折", - "startDate": "2026-04-01", - "endDate": "2026-12-31" - }, - { "planId": "124", "peopleRangeText": "3-5 人", "discountText": "85 折", ... }, - { "planId": "125", "peopleRangeText": "6 人及以上", "discountText": "8 折", ... } - ] -} -``` - -前端可按 ladder 画阶梯图。老字段 `earlyBirdTip` 语义微调为「概览性描述」，不再只拿第 1 个方案。 - -### 5. 小程序下单按人数本地匹配 - -前端可用 `earlyBirdLadder` 按用户选择的人数本地计算匹配档位，展示「您当前 X 人，命中 'Y 人 Z 折'；满 M 人可升级到 'N 折'」提示。 - ---- - -## 前端 TODO - -### 管理端早鸟优惠管理页 -1. 方案编辑表单加 **4 个新输入项**： - - 最高人数（数字，可空=不限） - - 优惠类型（单选：整单立减/每人立减/按比例打折），默认**整单立减** - - 折扣率（0-100，仅"按比例打折"时启用） - - 优先级（数字，默认 0） -2. 原"优惠金额 discountAmount"改为仅在"整单立减/每人立减"时启用 -3. 产品绑定改为**多选 tag**（去掉 1:1 限制，可一个产品绑多个方案） -4. 建议加"阶梯预览"区块显示该产品当前所有方案的覆盖情况，帮肉眼核对重叠/漏洞 -5. 列表展示：用后端返回的 `peopleRangeText + discountText` 直接显示，不用前端拼 - -### 小程序产品详情页 -1. 读 `earlyBirdLadder` 画阶梯图（3 档示意） -2. `earlyBirdTip` 作为默认概览展示（如"最低 8 折起"） -3. 老字段 `earlyBirdText`、`earlyBirdPlanName`、`earlyBirdDiscount` 废弃（值可能为 null 或第 1 档概览），请改读 `earlyBirdLadder[0]` - -### 小程序下单页 -1. 用户选完人数 + 日期后本地按 `earlyBirdLadder` 匹配： - ``` - match = ladder.find(l => 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_early-bird-order-level-multi-ladder.md b/changelogs/2026-04/2026-04-20_early-bird-order-level-multi-ladder.md deleted file mode 100644 index a092076..0000000 --- a/changelogs/2026-04/2026-04-20_early-bird-order-level-multi-ladder.md +++ /dev/null @@ -1,110 +0,0 @@ -# 早鸟优惠多档 + 订单级立减（小程序产品详情） - -**日期**：2026-04-20 -**PR**：无（纯文档更正，代码语义一直是订单立减） -**影响**：小程序产品详情页 早鸟展示 - ---- - -## 核心结论（给前端的一句话） - -`/mp/product/detail` 的 `earlyBirdLadder` 字段**已经支持「一个产品多档早鸟」**，每档的折扣语义是**订单总立减**（不是每人减），可以直接按阶梯画。 - ---- - -## 业务语义（最重要） - -早鸟优惠 = **订单总立减固定金额**，**不是**每人立减。 - -### 举例 - -- 满 3 人订单立减 **300 元**（订单总价减 300，不论 3 人还是 30 人） -- 满 4 人订单立减 **500 元** - -这在 `earlyBirdLadder` 里是**两个 item**，前端按 `minPeople` 升序画阶梯： - -```jsonc -// GET /mp/product/detail?productId=xxx -{ - "earlyBirdTip": "最低订单总价优惠 300 元（共 2 档早鸟方案）", // 概览，首屏标签用 - "earlyBirdLadder": [ - { - "planId": 1001, - "planName": "满3人早鸟", - "minPeople": 3, - "maxPeople": 3, // 档位上限（含），下一档 4 人以上不归它管 - "peopleRangeText": "3 人", - "discountText": "满 3 人订单总价优惠 300 元", // ⭐ 订单级立减 - "startDate": "2026-04-01", - "endDate": "2026-12-31" - }, - { - "planId": 1002, - "planName": "满4人早鸟", - "minPeople": 4, - "maxPeople": null, // null = 不限上限 - "peopleRangeText": "4 人及以上", - "discountText": "满 4 人订单总价优惠 500 元", - "startDate": "2026-04-01", - "endDate": "2026-12-31" - } - ] -} -``` - -## 字段清单 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `earlyBirdTip` | `String` | 概览文案（无人数上下文），无绑定返 `null` | -| `earlyBirdLadder` | `List<EarlyBirdLadderItem>` | 阶梯数组，按 `minPeople` 升序，无绑定返 `[]` | -| `earlyBirdLadder[].planId` | `Long` | 早鸟计划 ID | -| `earlyBirdLadder[].planName` | `String` | 计划名（管理端命名，展示可选） | -| `earlyBirdLadder[].minPeople` | `Integer` | 最低人数（含）| -| `earlyBirdLadder[].maxPeople` | `Integer\|null` | 最高人数（含），null 表示不限 | -| `earlyBirdLadder[].peopleRangeText` | `String` | 人数区间文案，如 "3-5 人" / "4 人及以上" | -| `earlyBirdLadder[].discountText` | `String` | **订单总立减**文案，如 "满 3 人订单总价优惠 300 元" | -| `earlyBirdLadder[].startDate` | `LocalDate` | 下单日期窗口起 | -| `earlyBirdLadder[].endDate` | `LocalDate` | 下单日期窗口止 | - -## 前端展示建议 - -### 产品详情 —— 早鸟阶梯卡片 - -``` -🐦 早鸟优惠 最低订单总价优惠 300 元 -┌─────────────────────────────────┐ -│ 3 人 -300 元 │ ← earlyBirdLadder[0] -│ 4 人及以上 -500 元 │ ← earlyBirdLadder[1] -└─────────────────────────────────┘ -生效：2026-04-01 至 2026-12-31 -``` - -- 用 `peopleRangeText` + `discountText` 拼行 -- 如果只想展示金额不展示文案，从 `discountText` 里正则抽数字即可，但直接用 `discountText` 最稳（后端拼好的） - -### 下单前匹配 - -- 下单时按选中人数 `n`，在 `earlyBirdLadder` 里找第一个满足 `minPeople ≤ n ≤ (maxPeople ?? ∞)` 的 item -- 展示"预计优惠 X 元"给用户，X 直接取这一档的金额（不再乘人数） -- 最终折扣以后端订单接口返回的 `OrderDiscount` 为准（前端只做预估展示） - -## 不是（防误读） - -- ❌ 不是"每人立减 X 元"—— 之前 Entity 注释里 `"优惠金额（元/人）"` 是过期文档，实际金额计算在 `OrderFinanceService.tryApplyEarlyBirdDiscount` 里**没有乘人数** -- ❌ 不是"订单总价按折扣比例打折"—— 是固定金额直减 -- ❌ 不是"每个人都减 X 元"—— 订单总价减一次 X 元 - -## 单选 / 多档的关系 - -- 一个产品可以绑定**多个**早鸟计划（通过 `product_early_bird_plan` 关联表） -- 每个计划一档，前端合并展示成阶梯 -- 运营侧在管理端配置：每档的 `minPeople` + `discountAmount` + 生效日期 - -## 已知注释问题（后端会修，不影响接口） - -- `EarlyBirdPlan.java:25` 注释 "元/人" 会改成 "订单总立减金额（元）" -- `EarlyBirdPlanDTO.java:25` 注释会明确 "订单优惠金额" -- `EarlyBirdLadderItemDTO.java:31` 示例会从 "每人立减 100 元" 改为 "订单总价优惠 300 元" - -前端**不用等这个 PR**，接口响应结构不变，语义本来就是订单立减。 diff --git a/changelogs/2026-04/2026-04-20_hotel-district-filter.md b/changelogs/2026-04/2026-04-20_hotel-district-filter.md deleted file mode 100644 index 78f71d6..0000000 --- a/changelogs/2026-04/2026-04-20_hotel-district-filter.md +++ /dev/null @@ -1,238 +0,0 @@ -# 管理端酒店 - 区/县筛选能力（`district` 字段 + 字典接口） - -- **日期**: 2026-04-20 -- **PR**: [#984](https://git.1814.love:8443/wx/HL/pulls/984) (Closes #982) + [#988](https://git.1814.love:8443/wx/HL/pulls/988)（补 HotelListVO.district） -- **类型**: FEATURE + BUGFIX（补齐后端能力，修复管理端区/县筛选不可用） -- **服务**: hl-resource-service（`/admin/hotel/**`） -- **前端是否需要改动**: **需要改动**（两处：资源管理-酒店列表顶栏、产品编辑-HotelPickerModal） - ---- - -## 一、背景 - -管理端两处区/县筛选当前不可用： - -| # | 入口 | 前端现状 | -|---|------|---------| -| 1 | 资源管理 - 酒店列表页 | 顶栏只有城市文本输入框，没有区/县下拉 | -| 2 | 产品编辑 - 添加酒店弹窗（`HotelPickerModal.vue`） | 有区/县下拉，但选项是从已加载的 hotelList 的 `city` distinct 伪造（逻辑错误：city 和 district 不是同一维度），选中后还把值当 `city` 参数传 | - -根因：后端 `HotelQueryRequest` 缺 `district` 字段（即便前端传了也会被忽略），也没有字典接口给前端做下拉数据源。 - -本次后端补齐两件事，让前端可以正常按区/县筛选。 - ---- - -## 二、变更接口 - -| # | 方法 | 路径 | 变更类型 | -|---|------|------|---------| -| 1 | GET | `/admin/hotel` | **新增** `district` 查询参数（可选，精确匹配） | -| 2 | GET | `/admin/hotel/districts` | **新增接口**：按 city 列出该城市下已上架酒店的 distinct 区/县列表 | - ---- - -## 三、接口 1：列表查询新增 `district` 参数 - -### 请求参数变化 - -| 参数 | 类型 | 之前 | 现在 | 说明 | -|------|------|------|------|------| -| `city` | String | 可选 | 可选（不变） | 城市精确匹配（模糊匹配走 `cityKeyword`） | -| `district` | String | ❌ 不存在 | **新增，可选** | 区/县精确匹配（最大 32 字符） | -| 其他参数 | — | 不变 | 不变 | `keyword` / `cityKeyword` / `hotelType` / `starLevel` / `status` / `tagId` / `tagIds` / `sortBy` / `sortDir` / `page` / `pageSize` 等全部不变 | - -### 调用示例 - -```js -// 原用法：只按城市筛选（兼容，不变） -GET /admin/hotel?city=海拉尔&page=1&pageSize=20 - -// 新用法：city + district 组合筛选 -GET /admin/hotel?city=海拉尔&district=海拉尔区&page=1&pageSize=20 -``` - -### 兼容性 - -老前端不传 `district` 完全兼容，行为不变。 - ---- - -## 四、接口 2：新增 区/县 字典接口 - -### 签名 - -``` -GET /admin/hotel/districts?city={city} -``` - -### 请求参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `city` | String | **可选** | 城市精确匹配；不传则返所有已上架酒店的 distinct district | - -### 响应结构 - -```json -{ - "code": 200, - "data": [ - { "value": "海拉尔区", "label": "海拉尔区" }, - { "value": "陈巴尔虎旗", "label": "陈巴尔虎旗" }, - { "value": "额尔古纳市", "label": "额尔古纳市" } - ] -} -``` - -`value` 和 `label` 都是区/县名称，按区/县名称升序。 - -### 数据来源 - -- 表：`hotel` -- SQL 等价： -```sql -SELECT DISTINCT district FROM hotel -WHERE status = 1 - AND deleted_at IS NULL - AND district IS NOT NULL - AND district != '' - [AND city = ?] -ORDER BY district ASC -``` - -### 过滤规则 - -- 只返"已上架"酒店（`status = 1`）的 district -- 已软删除的酒店不计入 -- district 为 `NULL` 或空字符串的被过滤 -- `city` 传空 → 跨城市聚合；`city` 传值 → 只看该城市 - ---- - -## 五、前端改造建议 - -### 场景 A：产品编辑 - HotelPickerModal.vue - -**改动点**： -1. 删除 L66-69 从 `hotelList` 里 distinct `city` 伪造 `areaOptions` 的代码 -2. 改为调 `GET /admin/hotel/districts?city=xxx` 拉取下拉数据（建议在选中 city 时触发） -3. 选中区/县后，查询参数名从 `city` 改为 **`district`**（`city` 由 city 选择器单独负责） - -```js -// 区/县选项加载（city 变化时触发） -async function loadAreaOptions(city) { - if (!city) { areaOptions.value = []; return } - const res = await request({ - url: '/admin/hotel/districts', - method: 'GET', - data: { city } - }) - areaOptions.value = res.data // [{ value, label }] -} - -// 查询酒店（修正参数名） -const params = { - city: cityFilter.value, // 城市 - district: areaFilter.value, // 🆕 区/县，之前错用 city - keyword: keyword.value, - page: 1, - pageSize: 20 -} -``` - -### 场景 B：资源管理 - 酒店列表页 - -**改动点**： -1. 顶栏 `city` 输入框右侧加"区/县"级联下拉 -2. city 改变时 reset 区/县并重新拉字典 -3. 查询参数同步传 `district` - ---- - -## 六、列表响应新增 district 字段 - -`GET /admin/hotel/items` 的 records 每一项新增 `district` 字段，前端表格可直接展示区/县列。其他字段保持不变。 - -```json -{ - "hotelId": "3001000000000000001", - "name": "XXX 酒店", - "city": "呼伦贝尔市", - "district": "海拉尔区", // 🆕 新增 - "hotelType": "HOTEL", - "starLevel": "FIVE_STAR", - // ... 其他字段不变 -} -``` - -## 七、响应 VO - -### `HotelDistrictOptionVO` - -```java -{ - "value": "海拉尔区", // 区/县名称（与 label 相同） - "label": "海拉尔区" // 区/县名称 -} -``` - -简单键值对，便于直接丢到 Element UI / Ant Design 的下拉组件。 - ---- - -## 八、不兼容变更 - -**无**。列表接口只是新增可选参数，字典接口是全新路径，老前端零影响。 - ---- - -## 九、回归验证（已在测试环境实测） - -- ✅ `/admin/hotel/districts` 无 city → 返 4 个值 -- ✅ `/admin/hotel/districts?city=呼伦贝尔市` → 返 3 个值（city 精确匹配生效） -- ✅ `/admin/hotel/items` records 37/39 含 district 字段（2 个脏数据是 null 属正常） -- ✅ `/admin/hotel/items?district=海拉尔区` → 8 条过滤生效 - ---- - -## 十、自行验证 - -测试环境部署完成后，用 admin token 验证： - -```bash -# 取 token -TOKEN=$(curl -s "https://api.test.1814.love/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"test_admin","password":"Test@2026"}' | jq -r .data.token) - -# 1. 字典接口（带 city） -curl "https://api.test.1814.love/admin/hotel/districts?city=海拉尔" \ - -H "Authorization: Bearer $TOKEN" | jq . - -# 2. 字典接口（不带 city，跨城市聚合） -curl "https://api.test.1814.love/admin/hotel/districts" \ - -H "Authorization: Bearer $TOKEN" | jq '.data | length' - -# 3. 列表接口带 district -curl "https://api.test.1814.love/admin/hotel?city=海拉尔&district=海拉尔区&page=1&pageSize=5" \ - -H "Authorization: Bearer $TOKEN" | jq '.data.records[] | {name, city, district}' - -# 4. 列表接口老用法（不带 district，兼容验证） -curl "https://api.test.1814.love/admin/hotel?city=海拉尔&page=1&pageSize=5" \ - -H "Authorization: Bearer $TOKEN" | jq '.data.total' -``` - -**预期**： -- 场景 1：返回该城市下已上架酒店的 distinct district 列表 -- 场景 2：返回所有城市聚合后的 distinct district -- 场景 3：返回该城市该区的酒店 -- 场景 4：行为与改动前完全一致 - ---- - -## 十一、不涉及的 - -- **小程序端（`/internal/mp/hotel/**`）不变**：本次只改管理端，小程序端若后续要区/县筛选走独立 PR -- **DB schema 不变**：`hotel.district VARCHAR(32)` 本来就有 -- **字典维护页不需要新建**：数据源是 distinct 查实际酒店数据，不是独立字典表 diff --git a/changelogs/2026-04/2026-04-20_mp-banner-active-top-level-seasons.md b/changelogs/2026-04/2026-04-20_mp-banner-active-top-level-seasons.md deleted file mode 100644 index 439f09b..0000000 --- a/changelogs/2026-04/2026-04-20_mp-banner-active-top-level-seasons.md +++ /dev/null @@ -1,43 +0,0 @@ -# /mp/banner/active 响应顶层新增 seasons 字段 - -**日期**: 2026-04-20 -**PR**: #1003 -**服务**: hl-user-service - -## 改动 -`BannerVO` 顶层新增 `seasons: List<String>`： -- banner 绑定产品（linkType=PRODUCT）→ 继承 `product.seasons` -- banner 绑定产品线（linkType=PRODUCT_LINE）→ 继承 `product_line.seasons` -- 其他绑定类型（URL/PAGE/NONE/...）或目标被删 → `seasons=null` - -## 响应示例 -```json -{ - "id": "...", - "title": "2026 草原夏令营", - "linkType": "PRODUCT", - "linkId": "2044306857534636034", - "seasons": ["summer", "winter"], // 新增：顶层 - "linkTarget": { - "type": "PRODUCT", - "name": "...", - "seasons": ["summer", "winter"] // 原已存在：嵌套 - } -} -``` - -## 前端建议 -- **推荐**：直接读 `banner.seasons`（顶层），便于按季节筛选 -- 如需更多目标信息（name/coverImageUrl）继续从 `banner.linkTarget` 取 - -## 存量数据 -**纯运行时继承**，不存 DB。banner 表无 seasons 列。每次请求根据 linkType/linkId 即时从产品/产品线 seasons 回填。 - -## 缓存 -Redis `banner:active:list:v3`（TTL 5 分钟）。之前版本 `v2` 被 bump 抛弃，确保旧 VO 结构不回吐。管理端新增/修改/删除 banner 时异步清缓存。 - -## 验证（测试环境） -``` -banner 1: linkType=PRODUCT seasons=["summer","winter"] -banner 2: linkType=PRODUCT_LINE seasons=["summer"] -``` diff --git a/changelogs/2026-04/2026-04-20_mp-book-button-disabled-frontend-bug.md b/changelogs/2026-04/2026-04-20_mp-book-button-disabled-frontend-bug.md deleted file mode 100644 index e2bc630..0000000 --- a/changelogs/2026-04/2026-04-20_mp-book-button-disabled-frontend-bug.md +++ /dev/null @@ -1,69 +0,0 @@ -# 小程序"预订"按钮灰 — 后端已返正确字段，前端需排查本地判定逻辑 - -**日期**: 2026-04-20 -**服务**: hl-product-service-v2 -**类型**: 前端 bug 排查提示（后端无改动） - -## 现象 -产品 `游牧的森林-短途版`（productId=`2045345825172639746`，CORE 2 档 轻奢/高端，`status=PUBLISHED`）在小程序详情页"预订"按钮**始终为灰色**，即使价格日历已配置。 - -## 三尺实证结论（后端完全正常） - -### 1. DB 价格日历已配置 -| tier_seq | tierName | min_date | max_date | 条数 | -|---|---|---|---|---| -| 1 | 轻奢 | 2026-04-01 | 2026-05-10 | 32 | -| 2 | 高端 | 2026-04-01 | 2026-05-22 | 51 | - -全档位都有价的日期从 `2026-04-20` 开始（查询执行日 = 2026-04-20）。 - -### 2. 后端接口 `/mp/product/{id}` 返回 -``` -isBooking : True ← 是否预约产品（原语义：订金可不填出行人，true=允许） -startPrice : 4105 ← 起步价（未来可售最低成人售价） -tierPrices : [ - { tierSeq: 1, tierName: 轻奢, startPrice: 4105 }, - { tierSeq: 2, tierName: 高端, startPrice: 4865 } -] -productType : CORE -``` -所有字段均为合法值，无 null / <=0 情况。 - -### 3. 新接口 `/mp/product/{id}/earliest-available-date` -（本次 PR #991 新增，已部署） -对全档位都有价的判定：`HAVING COUNT(DISTINCT tier_seq) >= tierCount` - -对该产品应返回： -```json -{ - "date": "2026-04-20", - "available": true, - "daysFromToday": 0 -} -``` - -## 前端需要做的 - -按钮灰的判定**不应**基于 isBooking（原意是"订金规则"，不是"是否可订"）。建议改为： - -1. **（推荐）** 调 `GET /mp/product/{id}/earliest-available-date`，`available === true` 才点亮按钮 -2. 或至少校验 `startPrice > 0 && tierPrices?.length > 0` -3. **不要**用 `status === 'PUBLISHED'`，因为 mp 详情响应体里没有 status 字段 - -## 参考字段语义（勿混用） - -| 字段 | 原语义 | 说明 | -| --- | --- | --- | -| `isBooking` | 是否预约产品 | true=订金可不填出行人 / false=全款前必须填出行人。**不是"是否可订"** | -| `startPrice` | 起步价 | 未来可售最低成人售价 | -| `tierPrices[].startPrice` | 档位起步价 | 各档位最低成人售价 | -| （新）`earliest-available-date.available` | 全档位是否有可售日期 | true=整产品可订 | - -## 已验证 -- `curl https://api.test.1814.love:9443/mp/product/2045345825172639746` → `isBooking:true, startPrice:4105` -- `GET /mp/product/{id}/earliest-available-date` 已部署（PR #991） - -## 建议排查前端 -- 是否读取了已废弃的 `saleStatus` / `onSale` 之类字段（当前后端未返） -- 是否在打包时写死了 `bookable=false` 的本地 mock -- 是否存在小程序端 storage 缓存（`wx.clearStorage` 后重试） diff --git a/changelogs/2026-04/2026-04-20_mp-deposit-amount-auto-compute.md b/changelogs/2026-04/2026-04-20_mp-deposit-amount-auto-compute.md deleted file mode 100644 index 4cb70e0..0000000 --- a/changelogs/2026-04/2026-04-20_mp-deposit-amount-auto-compute.md +++ /dev/null @@ -1,50 +0,0 @@ -# mp 产品详情新增 depositAmount 自动计算（含档位级） - -**日期**: 2026-04-20 -**服务**: hl-product-service-v2 -**PR**: #996 - -## 背景 -`GET /mp/product/{id}` 在 `paymentType=DEPOSIT, depositRatio=10` 时返回 `depositAmount=null`。因为管理端的 ratio/amount 互斥（配比例会清空固定金额），mp 端此前直接透传 null，小程序需要定金的具体金额来展示"定金 ¥xxx"和点亮预订按钮。 - -## 后端新行为 - -### 产品级 `depositAmount` -- `paymentType=DEPOSIT` 且 `depositAmount=null` 且 `depositRatio ∈ [1,100]` 时： - `depositAmount = startPrice × depositRatio / 100`（2 位小数，HALF_UP） -- `paymentType=FULL` → `depositAmount` 始终 null -- 管理端配了固定 `depositAmount` 时直接使用，不重算 - -### 档位级 `tierPrices[].depositAmount`（新字段） -`MpProductDetailRespVO.TierPriceInfo` 新增： -```json -{ - "tierSeq": 1, - "tierName": "轻奢", - "tierDescription": "自由之旅", - "startPrice": 4105, - "depositAmount": 410.5 // 新增 -} -``` -各档按本档 `startPrice × ratio / 100` 独立计算；管理端配固定金额时各档统一取该金额。 - -## 验证（测试环境产品 2045345825172639746） -``` -paymentType: DEPOSIT -depositRatio: 10 -depositAmount: 410.5 (= 4105 × 10%) -startPrice: 4105 -tierPrices: - - tierSeq=1 startPrice=4105 depositAmount=410.5 - - tierSeq=2 startPrice=4865 depositAmount=486.5 -``` - -## 前端建议 -- 展示产品总体定金：直接用 `data.depositAmount` -- 选中某档位时：用 `tierPrices[i].depositAmount` -- 判断定金模式：`data.paymentType === 'DEPOSIT' && data.depositAmount != null` - -## 兼容 -- 非定金产品（FULL）：depositAmount 仍为 null -- GROUP 类型（小蒙马）：无 tierPrices，depositAmount 直接按 startPrice 计算 -- 管理端固定金额模式：不受影响 diff --git a/changelogs/2026-04/2026-04-20_mp-earliest-available-date-and-full-tier.md b/changelogs/2026-04/2026-04-20_mp-earliest-available-date-and-full-tier.md deleted file mode 100644 index 9cf4946..0000000 --- a/changelogs/2026-04/2026-04-20_mp-earliest-available-date-and-full-tier.md +++ /dev/null @@ -1,65 +0,0 @@ -# 小程序新增"最近可售日期"接口 + 全档位可售判定 - -**日期**: 2026-04-20 -**服务**: hl-product-service-v2 -**PR**: #991 -**类型**: 新增接口 + 后端字段语义收紧 - -## 新增接口 - -### `GET /mp/product/{id}/earliest-available-date` -返回该产品从今天起的最近**全档位可售**日期（多档位产品要求该日所有档位都已配置成人价）。 - -**请求**： -- Path: `id` (Long) 产品ID -- 需要 mp token - -**响应**： -```json -{ - "code": 200, - "message": "成功", - "data": { - "date": "2026-04-20", - "available": true, - "daysFromToday": 0 - }, - "success": true -} -``` - -**字段说明**： -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `date` | `LocalDate` | 最近全档位可售日期（无可售时 null） | -| `available` | `Boolean` | `date != null` | -| `daysFromToday` | `Integer` | 距今天数（无可售时 null） | - -**判定规则**： -```sql -SELECT date FROM product_price_calendar -WHERE product_id = ? AND date >= today AND adult_sell_price > 0 -GROUP BY date -HAVING COUNT(DISTINCT tier_seq) >= tierCount(productId) -ORDER BY date ASC LIMIT 1 -``` -- `tierCount` = `product.tiers` JSON 数组长度 -- 单档产品 `tierCount<=1` 退化为"任一未来日有成人价" - -## 后端字段语义调整 - -### `MpProductDetailRespVO.isBooking` 判定收紧 -**之前**: `isBooking = (status == PUBLISHED)` -**现在**: `isBooking = (status == PUBLISHED) && (最近全档位可售日期 != null)` - -> 背景：isBooking 原意为"是否预约产品（订金可不填出行人）"，今天已复用为"是否可订"。若多档产品未配齐所有档位价格，则认为该产品不可订，按钮应置灰。 - -## 前端建议接入方式 - -1. 进入产品详情页时调 `/mp/product/{id}/earliest-available-date`，`available=true` 才点亮"预订"按钮。 -2. 选日历时可将 `date` 作为最小可选日期。 -3. 判断按钮状态**不要**用 `status` 字段（mp 详情响应体里没有）。 - -## 已部署 -- 测试环境已部署，hl-product-service-v2 双实例（8083/8183）均生效。 -- 验证产品 `2045345825172639746` 返 `isBooking:true, startPrice:4105`，全档位最近可售日 `2026-04-20`。 diff --git a/changelogs/2026-04/2026-04-20_mp-product-category-field.md b/changelogs/2026-04/2026-04-20_mp-product-category-field.md deleted file mode 100644 index b565acd..0000000 --- a/changelogs/2026-04/2026-04-20_mp-product-category-field.md +++ /dev/null @@ -1,74 +0,0 @@ -# /mp 产品详情 & 列表补 `category` 字段 - -**日期**: 2026-04-20 -**PR**: #1010 -**服务**: hl-product-service-v2 - -## 背景 -管理端可以给产品配「产品分类」（`产品分类 *`：亲子游 / 蜜月旅行 / 摄影之旅 / 深度体验 / 自驾越野），保存后 DB 里 `product.category` 有值；但小程序详情 + 卡片列表拿不到这个字段，无法按分类展示或筛选。 - -## 改动 -在下列两个响应 VO 顶层加 `category: string`（字典 `product_category`）： - -| 接口 | VO | -|------|----| -| `GET /mp/product/{id}` | `MpProductDetailRespVO.category` | -| `GET /mp/product-line/{lineId}/products` | `MpProductListRespVO.category`（每项） | - -## 字典 product_category -| 值 | 中文 | -|-----|------| -| `family` | 亲子游 | -| `honeymoon` | 蜜月旅行 | -| `photography` | 摄影之旅 | -| `experience` | 深度体验 | -| `driving` | 自驾越野 | - -未配置的老产品 `category=null`，前端按空兜底即可。 - -## 响应示例 - -### `GET /mp/product/2045345825172639746` -```json -{ - "code": 200, - "data": { - "productId": "2045345825172639746", - "productType": "CORE", - "category": "photography", // 新增 - "name": "游牧的森林-短途版", - "subtitle": "呼伦贝尔南线4天3晚秋色短途版", - "...": "..." - } -} -``` - -### `GET /mp/product-line/{lineId}/products` -```json -{ - "code": 200, - "data": [ - { - "productId": "2042549263955648513", - "productType": "CORE", - "category": "photography", // 新增 - "name": "测试核心产品", - "...": "..." - } - ] -} -``` - -## 已有能力（未变化） -- `GET /mp/product-line/{lineId}/products?category=photography` —— `category` 筛选参数之前已经支持，本次只补响应字段。 - -## 缓存 -- `mp:product:detail:{id}`、`mp:products-by-line:{lineId}[:cat:{category}]` -- 部署时异步清过一次；旧结构 JSON 不含 `category`，反序列化不会报错（只是取到 null），TTL 5–10 分钟内自愈。 - -## 存量数据 -**无需迁移**。`product.category` 已长期存在于 DB。之前只是响应未透出。 - -## 前端建议 -- 直接从顶层读 `banner_card_item.category` / `product_detail.category` -- 无值时按「未分类」显示或不展示标签 diff --git a/changelogs/2026-04/2026-04-20_mp-review-target-id-optional.md b/changelogs/2026-04/2026-04-20_mp-review-target-id-optional.md deleted file mode 100644 index 35eaa09..0000000 --- a/changelogs/2026-04/2026-04-20_mp-review-target-id-optional.md +++ /dev/null @@ -1,137 +0,0 @@ -# 小程序评价 - `/mp/review/target` 接口 targetId 改为可选（支持"全部评论"页） - -- **日期**: 2026-04-20 -- **PR**: [#951](https://git.1814.love:8443/wx/HL/pulls/951) (Closes #949) -- **类型**: FEATURE（兼容性增强，请求参数收紧 → 放宽） -- **服务**: hl-user-service（review 模块合并在 user 库 / user 服务，路由 `/mp/review/**`） -- **前端是否需要改动**: **无强制改动**（旧调用方式继续可用），新页面"全部评论"可直接复用本接口 - ---- - -## 一、背景 - -小程序新增"全部评论"列表页：在某个 `targetType`（产品 / 攻略 / 酒店 / 景点 / ...）下展示**全部已通过审核的评价**，不限定具体的目标对象 ID。 - -原接口 `GET /mp/review/target` 此前要求 `targetId` 必填，前端无法用同一个接口实现"全部评论"页，只能等后端再开一个新接口或自己拼。 - -本次后端把 `targetId` 由必填改为可选，**同接口同时支持两种语义**，前端不用再要新接口。 - ---- - -## 二、变更接口 - -| # | 方法 | 路径 | 变更类型 | -|---|------|------|---------| -| 1 | GET | `/mp/review/target` | 请求参数 `targetId` 由必填改为可选；响应结构不变 | - ---- - -## 三、请求参数变化 - -| 参数 | 类型 | 之前 | 现在 | 说明 | -|------|------|------|------|------| -| `targetType` | String | **必填** | **必填**（不变） | 评价目标类型，字典 `review_target_type`（如 `PRODUCT` / `STRATEGY` / `HOTEL` / `SCENIC` / ...） | -| `targetId` | Long | **必填** | **可选** | 不传 → 返回该 targetType 下所有已通过评价；传 → 按该 ID 过滤（行为不变） | -| `pageNo` / `pageSize` | Integer | 可选（分页默认值） | 同左 | 不变 | - ---- - -## 四、行为对照 - -| 调用方式 | 返回内容 | -|---|---| -| `GET /mp/review/target?targetType=PRODUCT&targetId=1001` | 商品 1001 的全部已通过评价（**行为完全不变**） | -| `GET /mp/review/target?targetType=PRODUCT` | 全部商品的所有已通过评价（**新支持**） | -| `GET /mp/review/target`（缺 targetType） | 仍返回参数校验错误（targetType 仍必填） | - ---- - -## 五、响应结构（不变） - -`PageResult<MpReviewVO>`，字段沿用既有结构： - -```json -{ - "code": 200, - "data": { - "total": 128, - "records": [ - { - "id": 9001, - "targetType": "PRODUCT", - "targetId": 1001, - "userId": 88, - "nickname": "***", - "avatar": "https://...", - "rating": 5, - "content": "服务很好，下次还来", - "images": ["https://..."], - "createTime": "2026-04-15 12:30:00" - } - ] - } -} -``` - -> 字段名、类型、嵌套结构与原接口**完全一致**，前端拿到的 records 结构无变化。 - ---- - -## 六、前端使用建议 - -### 场景 A：商品/攻略详情页"评价"模块（旧场景） - -**不用改**。原本就传 `targetType + targetId`，行为不变。 - -### 场景 B：小程序"全部评论"列表页（新场景） - -```js -// 全部商品评论（按 targetType 过滤） -const res = await request({ - url: '/mp/review/target', - method: 'GET', - data: { - targetType: 'PRODUCT', // 必填 - pageNo: 1, - pageSize: 20 - // targetId 不传 - } -}); -// res.data.records 即整个 targetType 下的所有评价 -``` - -### ⚠️ 注意 - -- `targetType` 仍**必填**，不传会被参数校验拦截 -- 不传 `targetId` 时，返回的 records 里每条都有自己的 `targetId`，前端可据此跳到对应详情 -- 评价审核状态过滤（已通过 / 待审核）逻辑后端处理，前端无感 - ---- - -## 七、不兼容变更 - -**无**。仅放宽请求参数约束（必填 → 可选），既有调用方式继续按原语义工作。 - ---- - -## 八、回归验证 - -测试环境部署完成后，用 mp token 调用： - -```bash -# 1. 旧用法（带 targetId）行为不变 -curl "https://api.test.1814.love/mp/review/target?targetType=PRODUCT&targetId=1001&pageNo=1&pageSize=10" \ - -H "Authorization: Bearer {mp-token}" \ - | jq '.data | {total, sample: .records[0]}' - -# 2. 新用法（不带 targetId，全部评论） -curl "https://api.test.1814.love/mp/review/target?targetType=PRODUCT&pageNo=1&pageSize=10" \ - -H "Authorization: Bearer {mp-token}" \ - | jq '.data | {total, sample: .records[0]}' - -# 3. 缺 targetType（应报参数错误） -curl "https://api.test.1814.love/mp/review/target?pageNo=1&pageSize=10" \ - -H "Authorization: Bearer {mp-token}" -``` - -**预期**：场景 1 与改动前一致；场景 2 返回的 total 应 ≥ 场景 1；场景 3 返回参数校验错误。 diff --git a/changelogs/2026-04/2026-04-20_mp-schedules-filter-expired.md b/changelogs/2026-04/2026-04-20_mp-schedules-filter-expired.md deleted file mode 100644 index e0808bb..0000000 --- a/changelogs/2026-04/2026-04-20_mp-schedules-filter-expired.md +++ /dev/null @@ -1,25 +0,0 @@ -# mp 班期接口过滤过期 + 出发前 1 天自动报名结束 - -**日期**: 2026-04-20 -**PR**: #999 -**接口**: `GET /mp/product/{id}/schedules` - -## 改动 - -1. **过滤过期班期**：响应中不再包含 `departureDate < 今天` 的班期 -2. **出发前 1 天自动报名结束**：保留班期中，若 `departureDate <= today + 1 天`（含当天和前一天），后端将 `batchStatus` 覆盖为 `"FINISHED"` - -## 业务语义 -- 出发前 1 天停止报名（行业通用规则） -- 避免前端展示已发团或即将发团（<1天）的班期为"可报名"状态 - -## 验证 -测试产品 `2044306857534636034`： -- DB 有 6 条班期（含 1 条 `2026-04-19` 已过期） -- 接口返 5 条，过期班期已过滤 -- 其余班期 `departureDate=2026-07-xx` 距今 74+ 天，保持原状态 `ENROLLING` - -## 前端注意 -- 不再需要自己在列表上按 departureDate 过滤 -- 判断"是否可报名"继续用 `batchStatus === 'ENROLLING'`（或 NEARLY_FULL），**无需再判日期** -- 5 分钟 Redis 缓存，部署后按 TTL 自然过期 diff --git a/changelogs/2026-04/2026-04-20_order-v2_admin-assignment-get.md b/changelogs/2026-04/2026-04-20_order-v2_admin-assignment-get.md deleted file mode 100644 index 6a61072..0000000 --- a/changelogs/2026-04/2026-04-20_order-v2_admin-assignment-get.md +++ /dev/null @@ -1,137 +0,0 @@ -# 管理端订单车辆/酒店分配独立 GET 接口 — 2026-04-20 - -> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** PR #1009 / #1018 -> **使用场景**：管理端订单详情 · 行程安排 Tab · 懒加载车辆/酒店分配数据 - ---- - -## 一、新增接口（2 个） - -### 🆕 `GET /admin/order/{orderId}/vehicle-assignment` — 查询车辆分配列表 - -**功能**：行程安排 Tab 懒加载。司机电话默认脱敏返回（如 `138****1234`）。订单不存在返回业务异常。 - -**请求参数**： - -| 参数 | 位置 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | --- | -| `orderId` | Path | `Long` | ✅ | 订单ID | - -**返回值** `Result<List<VehicleAssignmentVO>>`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `assignmentId` | `Long` | 分配ID | -| `orderId` | `Long` | 订单ID | -| `vehicleType` | `String` | 车型名称（如"丰田普拉多"） | -| `vehicleCount` | `Integer` | 车辆数 | -| `plateNumber` | `String` | 车牌号（如"蒙A·A1234"） | -| `driverName` | `String` | 司机姓名 | -| `driverPhone` | `String` | 司机电话（脱敏，如 `138****1234`） | -| `remark` | `String` | 备注 | -| `createTime` | `LocalDateTime` | 创建时间 | - -**响应示例**： - -```json -{ - "code": 200, - "data": [ - { - "assignmentId": 900001, - "orderId": 700001, - "vehicleType": "丰田普拉多", - "vehicleCount": 1, - "plateNumber": "蒙A·A1234", - "driverName": "李师傅", - "driverPhone": "138****1234", - "remark": null, - "createTime": "2026-04-20 10:00:00" - } - ] -} -``` - ---- - -### 🆕 `GET /admin/order/{orderId}/hotel-assignment` — 查询酒店分配列表 - -**功能**：行程安排 Tab 懒加载。按家庭/日期返回结构化酒店分配。订单不存在返回业务异常。 - -**请求参数**： - -| 参数 | 位置 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | --- | -| `orderId` | Path | `Long` | ✅ | 订单ID | - -**返回值** `Result<List<HotelAssignmentDetailVO>>`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `assignmentId` | `Long` | 分配ID | -| `orderId` | `Long` | 订单ID | -| `familyIndex` | `Integer` | 家庭序号（从1开始） | -| `hotelId` | `Long` | 酒店ID（资源服务） | -| `hotelName` | `String` | 酒店名称 | -| `roomTypeId` | `Long` | 房型ID（资源服务） | -| `roomType` | `String` | 房型名称 | -| `assignmentDate` | `LocalDate` | 分配日期 | -| `upgradePrice` | `BigDecimal` | 手动覆盖升级差价（null=使用系统计算） | -| `remark` | `String` | 备注 | - -**响应示例**： - -```json -{ - "code": 200, - "data": [ - { - "assignmentId": 800001, - "orderId": 700001, - "familyIndex": 1, - "hotelId": 500001, - "hotelName": "海拉尔铂尔曼大酒店", - "roomTypeId": 500101, - "roomType": "豪华大床房", - "assignmentDate": "2026-07-01", - "upgradePrice": null, - "remark": null - } - ] -} -``` - ---- - -## 二、与已有接口关系 - -| 接口 | 作用 | 状态 | -| --- | --- | --- | -| `PUT /admin/order/{orderId}/hotel-assignment` | 按天按家庭分配酒店 | 已有（未变） | -| `POST /admin/order/{orderId}/hotel-assignment/preview` | 升级差价预览 | 已有（未变） | -| 新增的两个 `GET` | 独立查询，供列表懒加载 | 本期新增 | - -订单详情接口 `GET /admin/order/{orderId}` 原有 `hotelAssignmentDetails` / `vehicleInfo` 等字段保持不变；新增的独立 GET 用于避免一次性加载全量订单详情时拉取重量级分配数据。 - ---- - -## 三、数据库变更 - -**无**。底层 `order_hotel_assignment` / `order_vehicle_assignment` 表未改。 - ---- - -## 四、错误码 - -HTTP 始终返回 200，错误码在 `Result.code` 中。 - -| code | 触发 | 说明 | -| --- | --- | --- | -| 200 | 正常 | 成功（无分配数据返回空列表） | -| 400 | 订单不存在 | `BusinessException` | - ---- - -## 五、关联 - -- PR: [wx/HL#1018](https://git.1814.love:8443/wx/HL/pulls/1018) diff --git a/changelogs/2026-04/2026-04-20_order-v2_arrival.md b/changelogs/2026-04/2026-04-20_order-v2_arrival.md deleted file mode 100644 index cb8705e..0000000 --- a/changelogs/2026-04/2026-04-20_order-v2_arrival.md +++ /dev/null @@ -1,119 +0,0 @@ -# 到达信息接口新增 — 2026-04-20 - -> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #990 / PR #992 + Issue #998 / PR #1000 -> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) / hl-resource-service(8082) -> **前端实际请求前缀**: `/mp/order/{orderId}/arrival`（5 接口）+ `/mp/transport/{flight|train}`（2 接口） - ---- - -## 一、能力概述 - -订单出行前/后，用户可填写接送机信息。一个订单可分**多个批次**（每批一套交通方案 + 多个出行人），天然支持"一家分两批到达"。覆盖原型 8 个到达弹窗： - -| 原型节点 | 功能 | 主要接口 | -| --- | --- | --- | -| 6pfmI | 填写到达·单批 | `POST /arrival` | -| uq0UL | 分批到达列表 | `GET /arrival` + `POST /arrival/batch` | -| K2s5H | 添加批次弹窗 | `POST /arrival` | -| L4xYN | 已识别航班回显 | `GET /transport/flight` → `POST /arrival` | -| oVMYy | 选择航班 | `GET /transport/flight` | -| AQ21V | 空态 | `GET /transport/flight`（结果空） | -| amizC | 手动填写 | `POST /arrival`（最小字段） | -| Bf9jC | 添加人员 | （出行人接口，另 Issue） | - ---- - -## 二、接口清单 - -鉴权：user token（登录态） - -| 方法 | 路径 | 用途 | -| --- | --- | --- | -| GET | `/mp/order/{orderId}/arrival` | 查全量批次（按方向分组） | -| POST | `/mp/order/{orderId}/arrival` | 新增一个批次 | -| POST | `/mp/order/{orderId}/arrival/batch` | 一次性提交多个批次（全量替换，空数组=清空） | -| PUT | `/mp/order/{orderId}/arrival/plan/{planId}` | 修改批次（全量覆盖） | -| DELETE | `/mp/order/{orderId}/arrival/plan/{planId}` | 删除批次 | -| GET | `/mp/transport/flight?flightNo=&date=` | 按航班号+日期查航班动态 | -| GET | `/mp/transport/train?trainNo=&date=` | 按车次号+日期查火车动态 | - ---- - -## 三、请求体 - -```jsonc -{ - "direction": "ARRIVAL", // ARRIVAL 到达 / DEPARTURE 离开 - "transportType": "FLIGHT", // FLIGHT / TRAIN / SELF_DRIVE - "transportNo": "CZ6255", - "carrier": "南方航空", - "departStation": "北京首都T3", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "selfDrivePeriod": "AFTERNOON", // MORNING / AFTERNOON / EVENING - "selfDriveEta": "2026-07-10 15:30:00", - "remark": "带小孩,需婴儿座椅", - "travelerIds": [10001, 10002] -} -``` - -**字段必填矩阵**（前端表单校验对齐）： - -| 字段 | ARRIVAL + FLIGHT/TRAIN | DEPARTURE + FLIGHT/TRAIN | SELF_DRIVE | -| --- | --- | --- | --- | -| transportNo | ✅ | ✅ | — | -| arriveStation | ✅ | 选 | — | -| arriveTime | ✅ | 选 | — | -| departStation | 选 | ✅ | — | -| departTime | 选 | ✅ | — | -| carrier | 选 | 选 | — | -| selfDrivePeriod | — | — | ✅ | -| travelerIds | ✅（≥1） | ✅（≥1） | ✅（≥1） | - -原则：**司机接机只看到达、送机只看出发**。amizC 手动填只 4 字段就是这个设计。 - ---- - -## 四、响应体 - -```jsonc -{ - "code": 200, - "data": { - "orderId": "2046159434324783106", // String 防大数精度丢失 - "arrivals": [ // ARRIVAL 批次列表 - { - "planId": "2046165477229555714", - "direction": "ARRIVAL", - "directionLabel": "到达", - "transportType": "FLIGHT", - "transportTypeLabel": "飞机", - "transportNo": "CZ6255", - "arriveStation": "海拉尔东山", - "arriveTime": "2026-07-10 15:30:00", - "creatorType": "USER", - "travelers": [ - {"travelerId": "10001", "name": "张三", "travelerType": "ADULT"}, - {"travelerId": "10002", "name": "李四", "travelerType": "ADULT"} - ] - } - ], - "departures": [] // DEPARTURE 批次列表，同结构 - } -} -``` - -约定： - -- **所有 ID 是 String**（雪花 ID 防大数精度丢失） -- 未传字段返回 `null`，列表空返回 `[]` -- 时间统一 `yyyy-MM-dd HH:mm:ss` -- 所有枚举字段配 `xxxLabel` 中文标签 - ---- - -## 五、关联 - -- Issue: [wx/HL#990](https://git.1814.love:8443/wx/HL/issues/990) / [wx/HL#998](https://git.1814.love:8443/wx/HL/issues/998) -- PR: [wx/HL#992](https://git.1814.love:8443/wx/HL/pulls/992) / [wx/HL#1000](https://git.1814.love:8443/wx/HL/pulls/1000)（均已合并到 dev） diff --git a/changelogs/2026-04/2026-04-20_order-v2_mp-order-traveler.md b/changelogs/2026-04/2026-04-20_order-v2_mp-order-traveler.md deleted file mode 100644 index 580a24a..0000000 --- a/changelogs/2026-04/2026-04-20_order-v2_mp-order-traveler.md +++ /dev/null @@ -1,132 +0,0 @@ -# 订单出行人 MP 端 CRUD 接口新增 — 2026-04-20 - -> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #1020 / PR #1022 -> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) -> **前端实际请求前缀**: `/mp/order/{orderId}/traveler`（4 个接口） - ---- - -## 一、能力概述 - -给小程序端补齐**订单出行人** CRUD 能力，对应原型 **L4xYN 乘坐人员勾选列表**、**Bf9jC 添加人员弹窗**。 - -| 原型节点 | 功能 | 主要接口 | -| --- | --- | --- | -| L4xYN pplList | 乘坐人员勾选列表 | `GET /mp/order/{orderId}/traveler` | -| Bf9jC | 添加人员弹窗 | `POST /mp/order/{orderId}/traveler` | -| Bf9jC（编辑） | 修改出行人 | `PUT /mp/order/{orderId}/traveler/{travelerId}` | -| Bf9jC（删除） | 删除出行人 | `DELETE /mp/order/{orderId}/traveler/{travelerId}` | - -**注意区分两套"出行人"模型**： - -| 维度 | 路径 | 说明 | -| --- | --- | --- | -| 用户常用出行人 | `/mp/user/traveler/*` | user-service 管，已有 | -| **订单出行人**（本次新增） | `/mp/order/{orderId}/traveler/*` | order-v2 的 `order_traveler` 表 | - ---- - -## 二、接口清单 - -鉴权：user token（登录态） - -| 方法 | 路径 | 用途 | -| --- | --- | --- | -| GET | `/mp/order/{orderId}/traveler` | 查某订单的出行人列表 | -| POST | `/mp/order/{orderId}/traveler` | 新增出行人到某订单 | -| PUT | `/mp/order/{orderId}/traveler/{travelerId}` | 修改出行人（字段为 null 保持原值不变） | -| DELETE | `/mp/order/{orderId}/traveler/{travelerId}` | 删除出行人 | - ---- - -## 三、请求体（`MpOrderTravelerSaveReqVO`） - -```jsonc -{ - "name": "张三", // 必填，≤50 字 - "idCardType": "ID_CARD", // 字典 id_card_type - "idCardNo": "110101199001011234", // 必填 - "phone": "13800000000", - "gender": "1", // 1=男 2=女 - "birthday": "1990-01-01", - "travelerType": "ADULT", // 默认 ADULT，字典 traveler_type - "nationality": "中国", - "emergencyContact": "李四", - "emergencyPhone": "13900000000", - "email": "zhangsan@example.com" -} -``` - -**字典取值**： -- `idCardType`: `ID_CARD` 身份证 / `PASSPORT` 护照 / `HK_MACAO_PASS` 港澳通行证 / `TAIWAN_PASS` 台湾通行证 / `OTHER` 其他 -- `travelerType`: `ADULT` 成人 / `CHILD` 儿童 / `YOUNG_CHILD` 幼儿 / `BABY` 婴儿 - -**后端自动处理**： -- 身份证（18 位）自动解析 `birthday` + `gender`（前端可不传） -- 同订单证件号重复检查（重复抛业务错误） - ---- - -## 四、响应体 - -### 列表 `GET` 响应 - -```jsonc -{ - "code": 200, - "data": [ - { - "travelerId": 10001, // Long，注：未强制 String（现有约定） - "name": "张三", - "travelerType": "ADULT", - "travelerTypeLabel":"成人", - "idCardType": "ID_CARD", - "idCardTypeLabel": "身份证", - "idCardNo": "110101199001011234", - "gender": "1", - "birthday": "1990-01-01", - "phone": "13800000000", - "nationality": "中国", - "emergencyContact": "李四", - "emergencyPhone": "13900000000", - "email": "zhangsan@example.com" - } - ] -} -``` - -### 新增/修改返回 - -返回单个对象（同列表元素结构）。 - -### 删除返回 - -```jsonc -{ "code": 200, "data": null } -``` - -### 约定 - -- 所有枚举字段都配 `xxxLabel` 中文标签 -- 空数据返回 `[]`，不是 `null` -- 时间格式统一 `yyyy-MM-dd`（出生日期）/ `yyyy-MM-dd HH:mm:ss`（含时间字段） - ---- - -## 五、前端接入建议 - -**L4xYN 乘坐人员勾选列表**： -1. 打开页面 → `GET /mp/order/{orderId}/traveler` 拉取订单已有出行人 -2. 用户勾选 → 把 travelerId 传给**到达信息**接口的 `travelerIds` 字段 - -**Bf9jC 添加人员弹窗**： -1. 可选：先调 `GET /mp/user/traveler`（已有）让用户从常用库选一个 → 填到表单里 -2. 用户补全/修改字段（含 OCR 扫描身份证填入，OCR 用小程序原生插件前端做） -3. 提交 `POST /mp/order/{orderId}/traveler` - ---- - -## 六、关联 - -- Issue: [wx/HL#1020](https://git.1814.love:8443/wx/HL/issues/1020) -- PR: [wx/HL#1022](https://git.1814.love:8443/wx/HL/pulls/1022)（已合并到 dev） diff --git a/changelogs/2026-04/2026-04-20_order-v2_mp-supplies-checklist.md b/changelogs/2026-04/2026-04-20_order-v2_mp-supplies-checklist.md deleted file mode 100644 index 741a722..0000000 --- a/changelogs/2026-04/2026-04-20_order-v2_mp-supplies-checklist.md +++ /dev/null @@ -1,128 +0,0 @@ -# C端「行李推荐弹窗」独立接口 — 2026-04-20 - -> **服务** hl-order-service-v2（端口 8094） + hl-mp-service（端口 8085）· **类型** feat · **关联** PR #1041 / #1042 -> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) - ---- - -## 一、新增接口（1 个） - -### 🆕 `GET /mp/order/{orderId}/supplies-checklist` — 订单备品清单（行李推荐弹窗） - -**功能**：对应小程序订单详情原型 `zgNiD` 行李推荐弹窗。从 `order_info.product_snapshot` 解析 `supplies`（按 `category` 分组，排除 `hasCost=true` 的成本项）+ `supplement.equipmentAdvice`（装备建议富文本）。 - -**请求参数**： - -| 参数 | 位置 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | --- | -| `orderId` | Path | `Long` | ✅ | 订单ID | - -> `userId` 由 mp-service 从 token 中获取后透传给 order-service，前端不传。 - -**返回值** `Result<MpSuppliesChecklistRespVO>`： - -| 字段 | 类型 | 必有 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `Long` | ✅ | 订单 ID | -| `categories` | `List<MpSuppliesCategoryVO>` | ✅ | 备品清单按分类分组（无推荐时为空列表） | -| `equipmentAdvice` | `String` | 否 | 装备建议富文本（HTML，快照无值时为 null） | - -**`MpSuppliesCategoryVO`**： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `category` | `String` | 分类名（如"衣物"、"配件"） | -| `items` | `List<MpSuppliesItemVO>` | 该分类下的备品列表 | - -**`MpSuppliesItemVO`**： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `suppliesName` | `String` | 备品名称（如"防晒霜"） | -| `category` | `String` | 分类（与父级同） | -| `quantity` | `Integer` | 数量 | -| `billingType` | `String` | 计费方式（`PER_PERSON`=按人 / `PER_QUANTITY`=按件） | -| `sortOrder` | `Integer` | 排序 | - -> ⚠️ 相比管理端 `OrderSuppliesVO`，C 端 VO 已去除 `hasCost`、`unitPrice` 等成本字段。 - -**请求示例**： - -``` -GET /mp/order/2043935542092980226/supplies-checklist -``` - -**响应示例**： - -```json -{ - "code": 200, - "message": "操作成功", - "data": { - "orderId": 2043935542092980226, - "categories": [ - { - "category": "衣物", - "items": [ - { "suppliesName": "冲锋衣", "category": "衣物", "quantity": 1, "billingType": "PER_PERSON", "sortOrder": 1 }, - { "suppliesName": "速干裤", "category": "衣物", "quantity": 2, "billingType": "PER_PERSON", "sortOrder": 2 } - ] - }, - { - "category": "配件", - "items": [ - { "suppliesName": "防晒霜", "category": "配件", "quantity": 1, "billingType": "PER_QUANTITY", "sortOrder": 1 } - ] - } - ], - "equipmentAdvice": "<p>呼伦贝尔 7 月早晚温差大，建议携带薄款冲锋衣。</p>" - } -} -``` - -**空推荐响应示例**（快照无 supplies 与 equipmentAdvice）： - -```json -{ - "code": 200, - "message": "操作成功", - "data": { - "orderId": 2043935542092980226, - "categories": [], - "equipmentAdvice": null - } -} -``` - ---- - -## 二、mp-service BFF 转发 - -| 前端调用 | mp-service 转发到 | -| --- | --- | -| `GET /mp/order/{orderId}/supplies-checklist` | `GET /internal/mp/order/{orderId}/supplies-checklist` | - ---- - -## 三、数据库变更 - -**无**。数据来自下单时固化的 `order_info.product_snapshot`。 - ---- - -## 四、错误码 - -HTTP 始终返回 200，错误码在 `Result.code` 中。 - -| code | 触发 | 说明 | -| --- | --- | --- | -| 200 | 正常 | 成功（快照缺失时 categories 为空列表，equipmentAdvice 为 null） | -| 400 | 订单不存在 | `BusinessException` | - ---- - -## 五、关联 - -- PR: [wx/HL#1042](https://git.1814.love:8443/wx/HL/pulls/1042) -- 原型节点: `zgNiD` — 行李推荐弹窗 -- 相关字段: `OrderDetailVO` 已同步新增 `supplies` / `equipmentAdvice` 字段，见 `2026-04-20_order-v2_order-detail-supplies-fields.md` diff --git a/changelogs/2026-04/2026-04-20_order-v2_order-detail-supplies-fields.md b/changelogs/2026-04/2026-04-20_order-v2_order-detail-supplies-fields.md deleted file mode 100644 index 56efb36..0000000 --- a/changelogs/2026-04/2026-04-20_order-v2_order-detail-supplies-fields.md +++ /dev/null @@ -1,86 +0,0 @@ -# 订单详情新增 supplies / equipmentAdvice 强类型字段 — 2026-04-20 - -> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** PR #1026 / #1031 -> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) - ---- - -## 一、现有接口字段新增（无路径/参数变更） - -### ✏️ 订单详情接口 — 新增 2 字段 - -影响接口： -- `GET /mp/order/{orderId}` — C 端订单详情（`MpOrderDetailVO`） -- `GET /admin/order/{orderId}` — 管理端订单详情（`OrderDetailVO`） - -两个接口共享底层 `OrderDetailQueryService`，均同步增加以下字段： - -| 字段 | 类型 | 必有 | 说明 | -| --- | --- | --- | --- | -| `supplies` | `List<OrderSuppliesVO>` | 否 | 订单备品列表（来自下单时固化的产品快照） | -| `equipmentAdvice` | `String` | 否 | 装备建议富文本（HTML，来自 `supplement.equipmentAdvice`） | - -**`OrderSuppliesVO` 字段**： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `id` | `Long` | 备品ID（快照中的产品备品ID） | -| `suppliesName` | `String` | 备品名称（如"帐篷"） | -| `category` | `String` | 分类（如"户外装备"） | -| `hasCost` | `Boolean` | 是否涉及成本 | -| `billingType` | `String` | 计费方式（`PER_PERSON`=按人 / `PER_QUANTITY`=按件） | -| `unitPrice` | `BigDecimal` | 单价 | -| `quantity` | `Integer` | 数量 | -| `sortOrder` | `Integer` | 排序 | - -> ⚠️ `OrderSuppliesVO` 含**完整成本字段**（`hasCost` / `unitPrice`），与 C 端"行李推荐弹窗"使用的 `MpSuppliesItemVO`（去掉了成本字段）不同。 - -**数据来源**：后端装配时从 `order_info.product_snapshot` JSON 解析 `supplies` 数组与 `supplement.equipmentAdvice` 字符串，填充为强类型字段。`productSnapshot` 原字段保持不变，**兼容现有前端**。 - -**降级行为**：快照为 `null`/非法/缺失子节点时，`supplies` 置为空列表，`equipmentAdvice` 置为 `null`，接口正常返回。 - ---- - -## 二、响应示例（新增字段部分） - -```json -{ - "code": 200, - "data": { - "orderId": 2043935542092980226, - "...": "（其余字段未变）", - "supplies": [ - { - "id": 600001, - "suppliesName": "帐篷", - "category": "户外装备", - "hasCost": true, - "billingType": "PER_QUANTITY", - "unitPrice": 80.00, - "quantity": 2, - "sortOrder": 1 - } - ], - "equipmentAdvice": "<p>呼伦贝尔 7 月早晚温差大，建议携带薄款冲锋衣。</p>" - } -} -``` - ---- - -## 三、其他字段保持不变 - -所有现有字段（`orderId`、`productName`、`departureDate`、`travelers`、`insurances` 等）均未改动。 - ---- - -## 四、数据库变更 - -**无**。数据来自已有的 `order_info.product_snapshot` JSON 字段。 - ---- - -## 五、关联 - -- PR: [wx/HL#1031](https://git.1814.love:8443/wx/HL/pulls/1031) -- 相关接口：`GET /mp/order/{orderId}/supplies-checklist`（独立行李推荐弹窗），见 `2026-04-20_order-v2_mp-supplies-checklist.md` diff --git a/changelogs/2026-04/2026-04-20_order-v2_pre-trip-checklist.md b/changelogs/2026-04/2026-04-20_order-v2_pre-trip-checklist.md deleted file mode 100644 index 9101c39..0000000 --- a/changelogs/2026-04/2026-04-20_order-v2_pre-trip-checklist.md +++ /dev/null @@ -1,154 +0,0 @@ -# TripDetailVO 扩出发准备清单字段 — 2026-04-20 - -> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #1024 / PR #1025 -> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) -> **前端实际请求前缀**: `GET /mp/trip/{orderId}`（**无新接口**，扩字段） - ---- - -## 一、能力概述 - -补齐原型 **ew2Kk 出发准备页的 prepSec 清单区块**。其余数据（倒计时 / 带队团队 / 行程概览 / 合同保险状态）已经在 `TripDetailVO` 中。 - -**⚠️ 无新接口**：扩现有 `GET /mp/trip/{orderId}` 的返回体，在 `TripDetailVO` 加一个字段 `preTripChecklist`。 - -| 触发条件 | 行为 | -| --- | --- | -| `tripPhase == "BEFORE_START"` | `preTripChecklist` 填充 6 项清单 | -| `tripPhase == "IN_PROGRESS"` | `preTripChecklist` 为 `null` | -| `tripPhase == "ENDED"` | `preTripChecklist` 为 `null` | - ---- - -## 二、接口清单 - -**无新接口**。使用现有： - -| 方法 | 路径 | 变化 | -| --- | --- | --- | -| GET | `/mp/trip/{orderId}` | 返回体新增 `preTripChecklist` 字段 | - ---- - -## 三、新增字段结构（`PreTripChecklistVO`） - -```jsonc -{ - "preTripChecklist": { - "completedCount": 3, // 已完成项数 - "totalCount": 6, // 总项数 - "items": [ - { - "key": "CONTRACT_SIGN", // 项 key - "title": "签署旅行合同", // 标题 - "subtitle": "合同已准备,请尽快签署", // 副标题 - "status": "WARNING", // DONE / PENDING / WARNING - "statusLabel": "紧急", - "actionType": "NAVIGATE", // NAVIGATE / CONFIRM / CONTACT_CS / null - "actionPayload": { // 前端按 actionType 解析 - "pageKey": "contract_sign", - "orderId": "1000", - "contractId": "9001" - } - }, - { - "key": "DEPOSIT_PAID", - "title": "订金已支付", - "subtitle": "¥2000 已支付", - "status": "DONE", - "statusLabel": "已完成", - "actionType": null, - "actionPayload": null - } - // ...共 6 项 - ] - } -} -``` - ---- - -## 四、清单 6 项 + 状态规则 - -| Key | 标题 | DONE 条件 | WARNING 条件 | 其他→PENDING | -| --- | --- | --- | --- | --- | -| `DEPOSIT_PAID` | 订金/全款支付 | `paidAmount >= 应付`（FULL→totalPrice / DEPOSIT→depositAmount） | — | 金额不足 | -| `TRAVELER_INFO` | 出行人完整度 | `validateTravelers.isComplete=true` | 有出行人信息缺失 | 人数不够 | -| `ARRIVAL_INFO` | 接送机信息 | arrivals 和 departures 都有 | — | 缺任一方向 | -| `CONTRACT_SIGN` | 合同签署 | contract.status=`SIGNED` | `PREPARING` / `UNSIGNED` | 无合同 | -| `INSURANCE` | 保险承保 | insurance.status=`INSURED` | `FAILED` | `PENDING` / 无保险 | -| `CHECKLIST_CONFIRMED` | 出行清单确认 | `OrderInfo.checklistConfirmed=true` | — | 未确认 | - -### actionType 语义 - -| 值 | 前端应做 | -| --- | --- | -| `NAVIGATE` | 跳转小程序页面（按 `actionPayload.pageKey` 映射） | -| `CONFIRM` | 弹确认对话框（如"确认出行清单"） | -| `CONTACT_CS` | 打开客服会话 | -| `null` | 不可操作（DONE 状态） | - -### pageKey 映射建议（前端维护） - -| pageKey | 小程序路径 | -| --- | --- | -| `order_pay` | 支付页 | -| `traveler_list` | 出行人列表 | -| `arrival_form` | 到达信息表单 | -| `contract_sign` | 合同签署 | -| `checklist_confirm` | 清单确认 | - -### 排序规则 - -后端已按 **WARNING > PENDING > DONE** 排序（紧急项靠前），前端直接渲染即可。 - ---- - -## 五、示例 - -### BEFORE_START 阶段完整响应（节选） - -```jsonc -{ - "code": 200, - "data": { - "orderId": "1000", - "tripPhase": "BEFORE_START", - "countdownDays": 12, - "departureDate": "2026-07-01", - "productName": "草原环线体验", - "guideName": "巴图", // 带队团队 - "guidePhone": "138****5678", - "itinerarySummary": [...], // 行程概览 - "contracts": [...], - "insurances": [...], - "preTripChecklist": { // ← 新增字段 - "completedCount": 3, - "totalCount": 6, - "items": [...] - } - } -} -``` - -### IN_PROGRESS 阶段响应 - -```jsonc -{ - "code": 200, - "data": { - "orderId": "1000", - "tripPhase": "IN_PROGRESS", - "todayDayNumber": 3, - "todayTitle": "莫日格勒河 → 额尔古纳", - "preTripChecklist": null // ← 非 BEFORE_START 阶段为 null - } -} -``` - ---- - -## 六、关联 - -- Issue: [wx/HL#1024](https://git.1814.love:8443/wx/HL/issues/1024) -- PR: [wx/HL#1025](https://git.1814.love:8443/wx/HL/pulls/1025)（已合并到 dev） diff --git a/changelogs/2026-04/2026-04-20_price-calendar-delete-require-query.md b/changelogs/2026-04/2026-04-20_price-calendar-delete-require-query.md deleted file mode 100644 index aa042dc..0000000 --- a/changelogs/2026-04/2026-04-20_price-calendar-delete-require-query.md +++ /dev/null @@ -1,54 +0,0 @@ -# 价格日历删除接口：前端需补齐 query 参数 - -**日期**: 2026-04-20 -**服务**: hl-product-service-v2 -**类型**: 前端修复提醒（后端无改动） - -## 背景 -管理端产品编辑页 Step4 定价管理，点击某个价格区间右侧的"删除"按钮，后端返回： -``` -startDate: 开始日期不能为空; endDate: 结束日期不能为空 -``` - -## 根因 -后端 `DELETE /admin/product/item/{id}/price-calendar` 要求以 **query 参数** 传 - `startDate` / `endDate` / `tierSeq`（按日期区间+档位物理删除多行），目前前端调用时请求 URL 里没有拼接这些 query 参数。 - -测试环境网关日志： -``` -DELETE http://api.test.1814.love/admin/product/item/2045018534152478721/price-calendar -``` -可见 URL 尾部缺失 `?startDate=...&endDate=...&tierSeq=...`。 - -## 接口契约（后端侧不变） - -**URL**: `DELETE /admin/product/item/{id}/price-calendar` - -**Query 参数**： -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `startDate` | string(yyyy-MM-dd) | ✔ | 区间开始日期 | -| `endDate` | string(yyyy-MM-dd) | ✔ | 区间结束日期 | -| `tierSeq` | integer | ✖（默认 1） | 档位序号（多档产品按当前选中档位传；单档传 1 或不传） | - -**Path 参数**： -- `id`: 产品ID（`Long`） - -## 前端需要做的 - -在"删除价格区间"的 API 调用里，**从区间卡片对象中取 `startDate` / `endDate`，并从当前 Tab 选中的档位取 `tierSeq`**，拼成 query 参数发送。 - -示例： -``` -DELETE /admin/product/item/2045018534152478721/price-calendar?startDate=2026-04-08&endDate=2026-04-30&tierSeq=1 -``` - -## 影响 -- **前端侧**：修改 `deletePriceCalendar(productId, {startDate, endDate, tierSeq})` 的 api 层包装，支持传 query 参数。 -- **后端侧**：无改动。 -- **兼容性**：如果前端忘记传，仍返回 400 校验错误；属于前端实现问题。 - -## 参考 -接口文件： -- Controller: `AdminProductController.deletePriceCalendar` (`/d/work2/HL/hl-product-service-v2/.../controller/admin/AdminProductController.java:249`) -- ReqVO: `PriceCalendarDeleteReqVO` (`.../vo/admin/PriceCalendarDeleteReqVO.java`) 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 deleted file mode 100644 index 2d54610..0000000 --- a/changelogs/2026-04/2026-04-20_product-map-amap-auto.md +++ /dev/null @@ -1,141 +0,0 @@ -# 产品地图支持高德自动生成（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_product-tag-single-select.md b/changelogs/2026-04/2026-04-20_product-tag-single-select.md deleted file mode 100644 index 9b6e0f1..0000000 --- a/changelogs/2026-04/2026-04-20_product-tag-single-select.md +++ /dev/null @@ -1,101 +0,0 @@ -# 产品标签改单选 + 字典值整体替换 - -**日期**：2026-04-20 -**PR**：无代码变更（纯字典数据迁移） -**Issue**：#1001 -**影响**：管理端产品编辑页 Step1 基础信息「产品标签」 - ---- - -## 为什么变 - -产品侧简化标签心智： -1. 每个产品只配 **1 个标签**（原来多选 chip，现在单选） -2. 字典 `product_tag` 整体换值： - - **旧**：亲子 / 城记 / 摄影 / 研学 / 露营 - - **新**：热内 / 新品 / 限定 / 硬核 / 治愈 - ---- - -## 后端改动 - -**只改字典，不动接口、不动字段类型**： - -- `product_tag` 字典：删除 5 个老项，新增 5 个新项（sortOrder 1→5） -- `ProductDO.tags` 字段**仍然是 `List<String>`**（JSON 数组，DB 列类型 JSON，不动） -- `ProductBasicSaveReqVO.tags` **仍然是 `List<String>`**，**没加 `@Size(max=1)` 校验** - - 原因：老产品 tags 已有多值（图示摄影/露营/亲子），加硬校验会直接卡死这些产品的保存 -- `MpProduct*RespVO.tags` **仍然是 `List<String>`** -- 没有 DDL 变更 - -### 接口签名不变 - -| Method | Path | 说明 | -|---|---|---| -| POST | `/admin/product/item/basic` | `tags: string[]` 字段类型完全不变 | -| GET | `/admin/product/item/detail` | 同上 | -| GET | `/mp/product/list` / `/mp/product/detail` | 同上 | -| GET | `/admin/dict/data/product_tag` | 现在返回 5 个新字典项 | -| GET | `/dict/all`（公开）| 其中 `product_tag` 类目返回 5 个新字典项 | - ---- - -## 前端改造（要做） - -### 产品编辑页 Step1 —— 产品标签输入控件 - -- 从**多选 chip** 改为**单选下拉** (Select / Radio Group / 单选 chip 二选一，UI 同学定) -- 选项数据源：`/admin/dict/all` → `dictType === 'product_tag'` → `dataList` 5 项 -- **提交格式仍然是数组**： - ```js - // 保持兼容后端 List<String> 字段 - saveReqVO.tags = selected ? [selected] : [] - ``` - 不要直接传字符串 —— 后端仍按数组接 -- **后端没加 max=1 硬校验**，所以就算前端误传 ≥2 个也不会报错，但业务上就按单选出 - -### 老数据兼容（关键） - -现有产品 tags 里可能存了老字典值（摄影/露营/亲子/研学/城记），编辑页打开时： - -- **不要把 `tags` 里不在新字典 5 项里的值过滤掉** —— 这会悄悄丢数据 -- **建议展示**：老 tag 值按字符串原样显示，加个灰色提示 "已下架标签，请重新选择" -- 用户保存时前端强制用户从 5 个新值中选一个（单选默认行为） - -### `/dict/all` 的 `product_tag` 新响应 - -```jsonc -{ - "dictType": "product_tag", - "dictName": "产品标签", - "dataList": [ - { "dictValue": "热内", "dictLabel": "热内", "icon": null, "sort": 1 }, - { "dictValue": "新品", "dictLabel": "新品", "icon": null, "sort": 2 }, - { "dictValue": "限定", "dictLabel": "限定", "icon": null, "sort": 3 }, - { "dictValue": "硬核", "dictLabel": "硬核", "icon": null, "sort": 4 }, - { "dictValue": "治愈", "dictLabel": "治愈", "icon": null, "sort": 5 } - ] -} -``` - -- 注意 `dictValue` 和 `dictLabel` 都是中文（和老字典保持一致，不是英文 code） -- `icon` 字段是昨天新加的（见 [2026-04-20_dict-icon-field.md](./2026-04-20_dict-icon-field.md)），暂时都是 null，产品侧后续可配图标 - ---- - -## 数据迁移 - -**不迁移**。 - -- 老产品 tags JSON 里存的老字典值字符串**保留**，编辑时按上面"老数据兼容"逻辑展示 -- 用户在下次编辑该产品时，按单选从新 5 项里选一个，保存后老值就被覆盖了 -- 小程序端列表/详情展示老 tag 时原样显示（即使字典里没这个值） - ---- - -## 验证 - -- ✅ 测试环境 `/admin/dict/data/product_tag` 返回 5 项（热内/新品/限定/硬核/治愈） -- ✅ `/dict/all` 公开接口 `product_tag` 也是 5 项新值 -- ✅ DB `sys_dict_data WHERE dict_type='product_tag'` 5 行无残留老值 -- ⏳ 生产环境字典同步：由 wx 手动在正式库执行相同的删 5 加 5（后端不出包，不走部署） diff --git a/changelogs/2026-04/2026-04-20_schedule-max-participants-optional.md b/changelogs/2026-04/2026-04-20_schedule-max-participants-optional.md deleted file mode 100644 index a326758..0000000 --- a/changelogs/2026-04/2026-04-20_schedule-max-participants-optional.md +++ /dev/null @@ -1,149 +0,0 @@ -# fix: 小蒙马（GROUP）班期 maxParticipants 改回可选（0/不传 = 不限名额） - -- **日期**: 2026-04-20 -- **PR**: [#953](https://git.1814.love:8443/wx/HL/pulls/953) (Closes #952) -- **类型**: FIX（请求参数约束放宽） -- **服务**: hl-product-service-v2 -- **前端是否需要改动**: **建议改动**（去掉前端必填校验，新增"不限名额"选项） - ---- - -## 一、背景 - -PR #927（2026-04-19）将班期保存接口的 `maxParticipants` 改为 **必填**，目的是把"约束模糊报错"前置到字段级。 - -但实际业务反馈：**小蒙马（GROUP）部分团允许"不限名额"**（按需开班，不卡上限），强制必填导致这类班期无法创建。 - -本次回退到**可选**，并明确"0 / 不传 = 不限名额"的语义；前端可据此提供"不限名额"开关或留空。 - ---- - -## 二、变更接口清单 - -| # | 方法 | 路径 | 影响 | -|---|------|------|------| -| 1 | POST | `/admin/product/v2/schedule/save` | 请求体字段 `maxParticipants` 由必填改回**可选** | -| 2 | POST | `/admin/product/v2/schedule/batch-create` | 同上 | - ---- - -## 三、字段约束变化 - -| 字段 | 之前 (PR #927) | 现在 (本次) | 允许值 | -|------|---------------|-------------|--------| -| `maxParticipants` | **必填**（null 报"最大参与人数不能为空"） | **可选** | 不传 / 0 / null = **不限名额**；>0 = 上限人数 | - -DB 侧：不传或传 0 均落库为 `0`，业务校验报名人数时按"0 视为不限"处理。 - ---- - -## 四、请求示例 - -### 不限名额班期（新支持） - -```json -POST /admin/product/v2/schedule/save -{ - "productId": 123, - "batchName": "五一不限人数团", - "departureDate": "2026-05-01", - "adultPrice": 5160, - "childPrice": 4580 - // 不传 maxParticipants → 0 → 不限 -} -``` - -### 显式限名额班期（行为不变） - -```json -POST /admin/product/v2/schedule/save -{ - "productId": 123, - "batchName": "五一限 30 人精品团", - "departureDate": "2026-05-01", - "adultPrice": 5160, - "childPrice": 4580, - "maxParticipants": 30 -} -``` - ---- - -## 五、报名上限校验逻辑 - -| `maxParticipants` 落库值 | 报名时校验 | -|---|---| -| `0`（不传 / 显式传 0） | **不校验**，可无限报名 | -| `> 0` | 报名累计人数不得超过该值；超出报"班期已满"错误 | - -> 现有"按 maxParticipants 校验"代码路径完整保留，仅在 `maxParticipants > 0` 时生效。 - ---- - -## 六、前端改动建议 - -### 班期创建/编辑表单 - -1. **去掉"最大人数必填"前端校验** -2. 在最大人数输入框旁加 **"不限名额"开关 / 复选框**： - - 勾选 → 提交时**不传 `maxParticipants`**（或显式传 `0`） - - 不勾 → 输入框可填具体数字（建议前端做 `>0` 校验，避免误填负数） -3. **回显逻辑**：编辑场景拉到 `maxParticipants=0` 时，开关默认勾选，输入框置灰 - -### 批量创建表单 - -同上，"不限名额"开关对批量生成的所有班期统一生效。 - -### 列表展示 - -| 后端字段值 | 建议展示 | -|---|---| -| `0` | "不限" / "不限名额" | -| `> 0` | "上限 N 人" / 进度条（已报 / N） | - ---- - -## 七、不兼容变更 - -| 调用方 | 影响 | -|---|---| -| 旧前端版本（**必传 `maxParticipants`**） | **不受影响**，传具体数字时行为完全一致 | -| 旧前端版本（**显式传 0** 想表达"不限"） | 之前会因必填校验直接 400；本次起正常落库为"不限" | -| 新前端版本（**不传 `maxParticipants`**） | 落库为 0 = 不限，符合预期 | - ---- - -## 八、回归验证 - -测试环境部署完成后，用管理端 token 调用： - -```bash -# 1. 不限名额班期（不传字段） -curl -X POST "https://api.test.1814.love/admin/product/v2/schedule/save" \ - -H "Authorization: Bearer {admin-token}" \ - -H "Content-Type: application/json" \ - -d '{ - "productId": 123, - "batchName": "回归-不限名额", - "departureDate": "2026-06-01", - "adultPrice": 5160, - "childPrice": 4580 - }' - -# 预期：code=200，落库 maxParticipants=0 - -# 2. 显式限名额班期（传具体数字） -curl -X POST "https://api.test.1814.love/admin/product/v2/schedule/save" \ - -H "Authorization: Bearer {admin-token}" \ - -H "Content-Type: application/json" \ - -d '{ - "productId": 123, - "batchName": "回归-限 30 人", - "departureDate": "2026-06-02", - "adultPrice": 5160, - "childPrice": 4580, - "maxParticipants": 30 - }' - -# 预期：code=200，落库 maxParticipants=30 -``` diff --git a/changelogs/2026-04/2026-04-20_supplies-combo-enabled-with-items.md b/changelogs/2026-04/2026-04-20_supplies-combo-enabled-with-items.md deleted file mode 100644 index 060210c..0000000 --- a/changelogs/2026-04/2026-04-20_supplies-combo-enabled-with-items.md +++ /dev/null @@ -1,78 +0,0 @@ -# /admin/supplies-combo/enabled 响应结构扩展（带完整备品明细） - -**日期**：2026-04-20 -**PR**：#987 -**影响**：管理端 产品编辑页 Step3「备品组合」下拉/列表 - ---- - -## 为什么变 - -原 `/admin/supplies-combo/enabled` 仅返回精简 VO（`comboId/name/itemCount`），前端要展开组合里的备品只能再逐个调 `/admin/supplies-combo/{comboId}` 详情 → N+1、体验差。 - -本次把明细直接吐在列表接口里，一次请求全量拿到。 - ---- - -## 接口契约变化 - -**Path / Method 不变**：`GET /admin/supplies-combo/enabled`（仍不分页，仅返回 `status=ENABLED`） - -### 新响应结构（`Result<List<SupplyComboRespVO>>`） - -```ts -{ - "code": 0, - "data": [ - { - "comboId": 7001, - "name": "亲子研学基础包", - "description": "适用 3-8 岁儿童", - "status": "ENABLED", // ENABLED / DISABLED (本接口固定 ENABLED) - "sortOrder": 10, - "createdBy": 999, - "updatedBy": 999, - "createdAt": "2026-04-01 10:00:00", - "updatedAt": "2026-04-20 15:00:00", - "itemCount": 3, // 明细数量 - "items": [ // ⭐ 新增：完整备品明细 - { - "id": 9001, // 明细主键 - "suppliesId": 100, // 备品ID - "quantity": 2, - "sortOrder": 10, - "suppliesName": "帐篷", // 快照回填：备品名 - "categoryCode": "CAMP", // 字典 supplies_category - "billingType": "BY_COUNT", // 字典 billing_type: BY_PERSON/BY_COUNT - "basePrice": 88.00 // 备品基础单价 - } - ] - } - ] -} -``` - -### 旧响应结构（已废弃，字段参考） - -```ts -{ "comboId": 7001, "name": "亲子研学基础包", "itemCount": 3 } -``` - ---- - -## 前端改造建议 - -- **下拉框展示**：继续用 `comboId`（value）+ `name`（label）+ `itemCount`（辅助信息） -- **组合卡片/悬浮预览**：直接读 `items` 数组渲染明细（suppliesName / quantity / basePrice / billingType），**不要再调详情接口** -- **产品编辑选中组合后带入备品清单**：用 `items.map(it => ({ suppliesId, quantity, unitPrice: basePrice, billingType, resourceName: suppliesName }))` 初始化表单 - -## 注意 - -- `items` 内只带「启用可见」的备品快照字段，组合保存后前端无需再追加 Feign/后端调用 -- 若某备品被下架（`status != 1` 或软删），本接口仍会把它放在 items 里（含快照字段），但产品保存时后端 Feign 展开会跳过失效项 —— 展示端如需标灰，可按需再挂钩详情接口或 `suppliesItem` 的 status 查询 - -## 不影响的接口 - -- `GET /admin/supplies-combo/{comboId}` 详情（依然返回单个组合含 items，行为不变） -- `GET /admin/supplies-combo/page` 分页（items 仍为 null，只返回 itemCount） -- `POST/PUT/DELETE /admin/supplies-combo` 全部 CRUD 接口（无变化） diff --git a/changelogs/2026-04/2026-04-20_supplies-combo.md b/changelogs/2026-04/2026-04-20_supplies-combo.md deleted file mode 100644 index 0066b15..0000000 --- a/changelogs/2026-04/2026-04-20_supplies-combo.md +++ /dev/null @@ -1,145 +0,0 @@ -# 备品组合功能（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` 字段保留不动 diff --git a/changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md b/changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md deleted file mode 100644 index c043c6d..0000000 --- a/changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md +++ /dev/null @@ -1,121 +0,0 @@ -# 小程序出行人接入阿里云 OCR 多证件识别，下线微信 OCR - -**日期**：2026-04-20 -**PR**：#1039 -**Issue**：#1036 -**影响**：小程序端「出行人录入」模块 - ---- - -## 业务变化 - -微信官方 OCR 接口不再允许使用。出行人证件 OCR 后端切换到阿里云「个人证照识别」SDK，并扩展支持**4 种证件**： - -| 证件 | idCardType | 后端走的 SDK | -|---|---|---| -| 身份证 | `ID_CARD` | RecognizeIdcard | -| 护照 | `PASSPORT` | RecognizePassport | -| 港澳通行证 | `HK_MACAU_PASS` | RecognizeExitEntryPermitToHK | -| 台湾通行证 | `TAIWAN_PASS` | RecognizeExitEntryPermitToHK（同接口，签发格式一致） | - -军官证 / 其他证件类型直接返回 400「不支持的证件类型」，前端做好容错。 - ---- - -## ❌ 下线接口 - -### `POST /mp/user/ocr/idcard`（微信 OCR 老接口） - -**下线原因**：微信 OCR 接口权限被关闭。 - -**前端必须在本次同步内去掉该接口调用**。 - ---- - -## ✅ 新增接口 - -### `POST /mp/traveler/ocr` —— 多证件 OCR 识别 - -**用途**：小程序出行人录入页，用户上传证件照到 OSS 后，用 OSS URL 调此接口识别，返回结构化字段**供用户确认后再手动调** `POST /user/traveler` **保存**（OCR 不直接落库）。 - -**请求** `Content-Type: application/json`： - -```json -{ - "idCardType": "ID_CARD", - "ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/xxx/id-front.jpg" -} -``` - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| idCardType | string | 是 | 证件类型。仅支持 `ID_CARD` / `PASSPORT` / `HK_MACAU_PASS` / `TAIWAN_PASS`，其余直接返回 400 | -| ossUrl | string | 是 | 证件图 OSS 公开地址（走现有 `POST /mp/file/upload` 拿） | - -**响应**（`TravelerOcrRespVO`，所有字段均为字符串/日期，**按证件类型可能为 null**）： - -```json -{ - "code": 200, - "message": "success", - "data": { - "name": "张三", - "gender": "男", - "nationality": "汉", - "nationalityText": "中国 / CHN", - "birthday": "1990-01-01", - "idCardNo": "110101199001011234", - "address": "北京市朝阳区...", - "validityStart": "2020-01-01", - "validityEnd": "2040-01-01", - "issueAuthority": "北京市公安局朝阳分局", - "issuePlace": null - } -} -``` - -字段适用表： - -| 字段 | 身份证 | 护照 | 港澳通 | 台湾通 | -|---|---|---|---|---| -| name | ✔️ | ✔️ | ✔️ | ✔️ | -| gender | ✔️ | ✔️ | ✔️ | ✔️ | -| nationality | 民族（汉） | 国籍英文（CHN） | — | — | -| nationalityText | — | 国籍中文（中国） | — | — | -| birthday | ✔️ | ✔️ | ✔️ | ✔️ | -| idCardNo | 身份证号 | 护照号 | 通行证号 | 通行证号 | -| address | ✔️（身份证住址） | — | — | — | -| validityStart / validityEnd | ✔️ | ✔️ | ✔️ | ✔️ | -| issueAuthority | — | ✔️ | ✔️ | ✔️ | -| issuePlace | — | ✔️ | — | — | - ---- - -## 错误码 - -| HTTP | code | message | 原因 | -|---|---|---|---| -| 200 | 200 | success | 识别成功 | -| 200 | 400 | 不支持的证件类型 | idCardType 不在上面 4 种之内 | -| 200 | 400 | 参数校验失败 | ossUrl 不是 http/https 或 idCardType 空 | -| 200 | 500 | 身份证识别失败，请重试 | 阿里云 SDK 异常（图片质量/网络/额度等），失败已记审计 | - -**建议前端**：调用前做**图片压缩**（建议 ≤ 3MB）；失败后提示用户"重新拍照"，不要自动重试（会多扣配额）。 - ---- - -## 前端改造 checklist - -- [ ] 出行人录入页 OCR 入口替换为 `POST /mp/traveler/ocr` -- [ ] 增加证件类型选择（4 个），默认 `ID_CARD` -- [ ] 老接口 `/mp/user/ocr/idcard` 调用代码全部删除 -- [ ] OCR 返回字段渲染到表单输入框里，**让用户确认/编辑后**再提交，不要直接调保存 -- [ ] 根据 `idCardType` 决定展示哪些字段（护照多个 `nationalityText`，身份证多个 `address`） - ---- - -## 其它 - -- 免费额度：每类证件 200 次/月，超出按量付费（阿里云账单） -- QPS：默认 10 -- 审计日志（`traveler_ocr_log`）仅后端使用，前端不感知 diff --git a/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md b/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md deleted file mode 100644 index 9793e72..0000000 --- a/changelogs/2026-04/2026-04-21_brand-card-link-url-from-dict-remark.md +++ /dev/null @@ -1,110 +0,0 @@ -# 小程序主题卡片返回 linkUrl（从字典 remark 解析） - -**日期**：2026-04-21（同日晚） -**PR**：#1097 -**后端服务**：hl-user-service（写/读）+ hl-mp-service（BFF 透传，**必须同步重启**，common-core DTO 改动） -**影响**：小程序首页第二屏 `GET /mp/home-config/screen2` 响应体 - ---- - -## 变更点 - -`BrandCard` DTO（小程序 `data.cards[]` 每一项）**新增字段 `linkUrl`**： - -| 字段 | 类型 | 何时有值 | 说明 | -|------|------|---------|------| -| `linkUrl` | String | `linkType` ∈ {SEASON, CORE_LIST, MENGMA} | 由后端从字典 `theme_card_link_type.remark` 解析得到的页面路径 | -| `linkUrl` | null | `linkType = PRODUCT` 或字典未配 | PRODUCT 前端自行按 `linkTargetType + linkTargetId` 拼 | - ---- - -## 响应示例 - -```json -{ - "code": 200, - "data": { - "brandStory": { ... }, - "cards": [ - { - "title": "季节之旅", - "coverUrl": "https://...", - "linkType": "SEASON", - "linkTargetType": null, - "linkTargetId": null, - "linkUrl": "packages/product/season/list/list" - }, - { - "title": "亲子游学", - "coverUrl": "https://...", - "linkType": "MENGMA", - "linkTargetType": null, - "linkTargetId": null, - "linkUrl": "packages/product/mengma/list/list" - } - ] - } -} -``` - ---- - -## 小程序端对接（可以大幅简化） - -之前版本需要前端维护 code → 路径 switch： -```js -// ❌ 旧做法，可以不再维护 -const ROUTE = { SEASON: 'packages/product/season/list/list', ... }; -wx.navigateTo({ url: '/' + ROUTE[card.linkType] }); -``` - -新做法： -```js -// ✅ 新做法，直接读 linkUrl -if (card.linkType === 'PRODUCT') { - // PRODUCT 按 linkTargetType + linkTargetId 拼产品详情 - wx.navigateTo({ url: `/packages/product/${card.linkTargetType.toLowerCase()}/detail?id=${card.linkTargetId}` }); -} else { - wx.navigateTo({ url: '/' + card.linkUrl }); -} -``` - -**路径配置完全由后台字典 `theme_card_link_type.remark` 控制**，未来换路径不用发版小程序，只改字典即可。 - ---- - -## 字典 remark 约定 - -``` -dict_value=SEASON remark="跳转: packages/product/season/list/list" -dict_value=CORE_LIST remark="跳转: packages/product/core/list/list" -dict_value=MENGMA remark="跳转: packages/product/mengma/list/list" -dict_value=PRODUCT remark="指定产品详情..."（非路径，linkUrl=null） -``` - -后端只认 `"跳转: "` 开头的 remark 作为 URL。其它 remark 被当成描述文本，linkUrl=null。 - ---- - -## 降级行为 - -- 字典 `theme_card_link_type` 未配或查询异常 → `linkUrl=null`，前端可回退自维护映射或不跳转 -- 老数据 `linkType=null` 被后端兜底为 `SEASON`，继续有 linkUrl（保持旧行为） - ---- - -## 测试 - -- `MpHomeConfigServiceTest` 新增 3 个 case（SEASON/MENGMA 有 URL / PRODUCT null / 字典降级） -- 本地 API curl 已通过：`/mp/home-config/screen2` → cards[].linkUrl 正确填充 -- 测试服已部署 user + mp - ---- - -## 重启 - -**两个服务都要重启**： -- hl-user-service（生成 BrandCard.linkUrl 的源头） -- hl-mp-service（透传 BrandCard，如果 fat jar 里带旧版 common-core class 不重启会丢字段） - -参考经验：`experience/test-server-admin/shared-common-core-dto-all-consumers-redeploy.md` diff --git a/changelogs/2026-04/2026-04-21_cache-dependency-system.md b/changelogs/2026-04/2026-04-21_cache-dependency-system.md deleted file mode 100644 index 28766db..0000000 --- a/changelogs/2026-04/2026-04-21_cache-dependency-system.md +++ /dev/null @@ -1,68 +0,0 @@ -# 缓存依赖系统 - 彻底解决管理端改 / MP 不同步 - -**日期**：2026-04-21（晚） -**PR 链**：#1099（Issue）→ #1102（D1 基础设施）→ #1103（product-v2）→ #1105（mp）→ #1110（user）→ #1111（resource） -**后端**：hl-common-redis / hl-user / hl-resource / hl-product-v2 / hl-mp（已部署测试服） -**影响**：前端基本**零感知**（仅字段新增 `linkUrl`，其它对外接口不变）；**根本解决了管理端编辑后小程序要等 5-30min TTL 才刷新的痛点** - ---- - -## 前端感知变化 - -### ✅ 唯一新增字段 -- `MpHomeScreen2VO.cards[].linkUrl`（已在 2026-04-21_brand-card-link-url-from-dict-remark.md 说明） - -### ✅ 其它一切不变 -- REST 路径 / 请求体 / 响应体 / 错误码全部**保持兼容** -- 老小程序继续运行不受影响 - ---- - -## 缓存行为彻底改变（对前端的关键价值） - -**之前**： -``` -管理端改字典 / brand-story / banner / 产品 / 酒店 / 景点... - ↓ 后端清了"自己那层"缓存 - ↓ 但聚合缓存 (home:screen2 / mp:product:detail / ...) 没清 -小程序继续读旧缓存, 5-30 min 后 TTL 到了才刷新 -``` - -**现在**： -``` -管理端改任意源数据 (表/字典/配置) - ↓ afterCommit 触发 invalidateSource("table:xxx") - ↓ Redis 反向索引 cache:deps:index:table:xxx Set 里所有 cache key 被逐个 DEL -小程序下一次 curl 立即拿到新数据 (不等 TTL) -``` - -**测试服 E2E 已验证**：管理端 PUT `brand-story` 改 title → 立即 curl `/mp/home-config/screen2` → title 已刷新（不等 30min TTL）✅ - ---- - -## 不用管的（后端基础设施层） - -- `DependencyAwareCacheManager` 新类（共享 Redis 反向索引） -- `MpCacheEvict` 改成 @Deprecated 委托层（老调用继续工作） -- `docs/cache-deps.md` 新文档，后端 PR review 硬卡 -- 47 个 `@MpCache` 补 `deps` 数组（mp-service 17 Controller） -- 27 个 resource Service + 9 个 user Service + 8 个 product-v2 Service 写点补 `invalidateSource` - ---- - -## 回归风险 → 已压实 - -| 风险 | 压实方式 | -|------|---------| -| 单测回归 | 2117 (resource) + 774 (mp) + 2307 (user) + 112 (product-v2) + 26+3 (common-redis) **全绿** | -| E2E 回归 | 测试服 brand-story → screen2 全链路实测通过 | -| Redis 集群兼容 | 不用 Lua 批量 DEL / 不用 Pipeline, 逐命令（Spring Data Redis cluster 自动路由） | -| SADD 失败降级 | log.warn 不抛, TTL 兜底（最多 30min 自愈） | -| 跨服务联动 | 共享 Redis, 无 MQ/Feign, 零额外基础设施 | -| 业务灰度 | 不引入 Nacos 开关（用户明确要求 "彻底修改"） | - ---- - -## 前端不用改代码 - -就一条事：**下次看到「管理端改了 MP 没同步」请重新测试，如果还有问题告诉后端**（大概率是某张源表的 deps 没登记，在 `docs/cache-deps.md` 里补上即可，不需要动业务代码）。 diff --git a/changelogs/2026-04/2026-04-21_home-screen2-theme-card-link.md b/changelogs/2026-04/2026-04-21_home-screen2-theme-card-link.md deleted file mode 100644 index 30929b8..0000000 --- a/changelogs/2026-04/2026-04-21_home-screen2-theme-card-link.md +++ /dev/null @@ -1,363 +0,0 @@ -# 首页第二屏主题卡片新增跳转链接字段 - -**日期**：2026-04-21 -**PR**：#1081（Closes Issue #1080） -**合并到 dev commit**：c17d2563 -**后端服务**：hl-user-service（写入/查询）+ hl-mp-service（复用 `BrandCard` 跨服务 DTO，需同步重启） -**影响**： -- 管理端「首页配置 → 品牌故事」编辑页（每张主题卡片新增跳转设置） -- 小程序「首页第二屏」（点主题卡片跳不同的列表/详情） - ---- - -## 为什么改 - -历史上首页第二屏的 2 张主题卡片只是图+文，点击**没有跳转**。现在要让运营后台可以为每张卡片单独选一种跳转方式（4 种预设之一），并透传给小程序去拉不同的列表/详情页： - -| 跳转类型 value | 中文 | 前端目标路由 | -|---|---|---| -| `SEASON` | 季节之旅 | `packages/product/season/list/list` | -| `CORE_LIST` | 核心产品 | `packages/product/core/list/list` | -| `MENGMA` | 亲子游学 | `packages/product/mengma/list/list` | -| `PRODUCT` | 指定产品详情 | 按 `linkTargetType` + `linkTargetId` 拼产品详情页路径 | - -老数据、老小程序完全兼容——老 JSON 反序列化出来 `linkType=null`，后端读路径统一兜底为 `SEASON`，保持原先"点卡片去季节列表"的行为，老客户端可以不做任何改动。 - -> 命名说明：类型 code 有意叫 `CORE_LIST` / `PRODUCT` 而不是 `CORE` / `CUSTOM`，**避免与已存在的 `product_type.CORE` / `product_type.CUSTOM` 撞名**，前端按 switch 分发时不会踩坑。 - ---- - -## 管理端变化 - -### 1. 保存品牌故事 `PUT /admin/home-config/brand-story` - -`cards[]` 每张卡片新增 **3 个字段**（在原有 title / subtitle / coverUrl 基础上）： - -| 字段 | 类型 | 是否必填 | 校验 | -|---|---|---|---| -| `linkType` | string | **必填**（默认 `SEASON`） | 枚举：`SEASON` / `CORE_LIST` / `MENGMA` / `PRODUCT`；非白名单值后端 400 拒绝 | -| `linkTargetType` | string \| null | **仅 `linkType=PRODUCT` 时必填**；其他场景**后端强制置空**（即使前端传了值，后端也会清空入库） | 枚举：`CORE` / `GROUP`（对齐字典 `product_type`） | -| `linkTargetId` | number \| null | **仅 `linkType=PRODUCT` 时必填**；其他场景后端强制置空 | 对应产品 ID，后端会 Feign 回产品服务校验：存在 + productType 匹配 + `status=PUBLISHED` | - -**后端校验顺序**（对应错误提示）： - -1. `linkType` 缺失 → "跳转类型不能为空" -2. `linkType` 不在白名单 → "第 N 张卡片跳转类型非法: xxx" -3. `linkType=PRODUCT` 但缺 targetType 或 targetId → "第 N 张卡片跳转到产品详情时必须同时选择产品类型和目标产品" -4. `linkType=PRODUCT` 且 `linkTargetType` 不在 {CORE, GROUP} → "第 N 张卡片目标产品类型只能是 CORE 或 GROUP" -5. Feign 回产品服务校验（批量，无 N+1）： - - 产品不存在 → "第 N 张卡片目标产品不存在或已删除: id=xxx" - - productType 不匹配 → "第 N 张卡片目标产品类型不匹配: 期望=CORE, 实际=GROUP" - - 产品未上架 → "第 N 张卡片目标产品未上架(当前状态=DRAFT)，请先上架" -6. Feign 本身失败（熔断 / 极端异常）→ "校验目标产品失败，请稍后重试"（保守策略：拒绝保存，不让脏数据入库） - -#### 请求示例：保存两张卡片（一张 SEASON + 一张 PRODUCT） - -```jsonc -PUT /admin/home-config/brand-story -Authorization: Bearer <admin token> -Content-Type: application/json - -{ - "title": "我们的品牌故事", - "subtitle": "在草原遇见你", - "body": "……", - "cards": [ - { - "title": "秋色限定", - "subtitle": "九月走一遭", - "coverUrl": "https://cdn.example.com/cards/autumn.jpg", - "linkType": "SEASON" - // linkTargetType / linkTargetId 不传或传 null 都可以，后端会强制置空 - }, - { - "title": "南线4天3晚", - "subtitle": "王牌行程", - "coverUrl": "https://cdn.example.com/cards/south.jpg", - "linkType": "PRODUCT", - "linkTargetType": "CORE", - "linkTargetId": 2045345825172639746 - } - ], - "publish": true -} -``` - -#### 请求示例：运营选了 CORE_LIST（核心产品列表） - -```jsonc -{ - "cards": [ - { - "title": "核心系列", - "subtitle": "最受欢迎", - "coverUrl": "https://cdn.example.com/cards/core.jpg", - "linkType": "CORE_LIST" - } - ], - "publish": true -} -``` - -> `linkType` 是 `SEASON` / `CORE_LIST` / `MENGMA` 三者之一时，即使前端在表单里留了 `linkTargetType` / `linkTargetId` 的旧值，**后端也会强制清空**，不会留脏数据。所以前端切换跳转类型后不需要特意 reset 这两个字段。 - -#### 错误响应样例 - -```jsonc -// PRODUCT 缺字段 -{ - "code": 500, - "msg": "第 2 张卡片跳转到产品详情时必须同时选择产品类型和目标产品" -} - -// PRODUCT 指的产品被人下架了 -{ - "code": 500, - "msg": "第 1 张卡片目标产品未上架(当前状态=UNPUBLISHED)，请先上架" -} - -// PRODUCT 指的产品被删了或不存在 -{ - "code": 500, - "msg": "第 1 张卡片目标产品不存在或已删除: id=9999" -} -``` - ---- - -### 2. 查询品牌故事 `GET /admin/home-config/brand-story` - -响应体 `data` 除了原有 title/subtitle/body/coverUrl/cards/version/status 等字段外，**新增两个 Map** 用于管理端列表展示"目标产品 XXX（已上架）"徽章： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `linkTargetStatusMap` | `Map<Long, String>`（productId → product_status） | 仅 `linkType=PRODUCT` 的卡片有条目；Feign 降级时**返回空对象** `{}`（非 null），不阻塞主流程 | -| `linkTargetNameMap` | `Map<Long, String>`（productId → 产品名） | 同上，用于直接渲染"跳转到：游牧的森林-短途版" | - -`cards[]` 里也携带 `linkType` / `linkTargetType` / `linkTargetId` 三个字段，其中 **老数据 `linkType=null` 会被后端兜底改写为 `SEASON`**（和写入路径兜底逻辑对齐），所以前端拿到的 `linkType` 永远不会是 null/空字符串。 - -#### 响应示例 - -```jsonc -GET /admin/home-config/brand-story - -{ - "code": 200, - "data": { - "id": 1, - "title": "我们的品牌故事", - "subtitle": "在草原遇见你", - "body": "……", - "coverUrl": "https://cdn.example.com/brand/story.jpg", - "cards": [ - { - "title": "秋色限定", - "subtitle": "九月走一遭", - "coverUrl": "https://cdn.example.com/cards/autumn.jpg", - "linkType": "SEASON", - "linkTargetType": null, - "linkTargetId": null - }, - { - "title": "南线4天3晚", - "subtitle": "王牌行程", - "coverUrl": "https://cdn.example.com/cards/south.jpg", - "linkType": "PRODUCT", - "linkTargetType": "CORE", - "linkTargetId": 2045345825172639746 - } - ], - "linkTargetStatusMap": { - "2045345825172639746": "PUBLISHED" - }, - "linkTargetNameMap": { - "2045345825172639746": "游牧的森林-短途版" - }, - "status": "ACTIVE", - "version": 7, - "updatedByName": "wx", - "updatedAt": "2026-04-21T13:51:46" - } -} -``` - -> 表里没有任何记录时 `data=null`，老逻辑不变。 - ---- - -### 3. 产品下拉列表（复用已有接口） - -前端管理端在"选指定产品"场景下，请直接复用已有的： - -**`GET /admin/product/item/simple-list`**（hl-product-service-v2） - -| Query 参数 | 类型 | 说明 | -|---|---|---| -| `keyword` | string | 关键词（产品名或产品编号） | -| `productType` | string / string[] | `CORE,GROUP` 逗号分隔 或 `productType=CORE&productType=GROUP` 多值重复 key；也支持单值。品牌故事跳转场景建议传 `CORE,GROUP` 两个都要 | -| `page` | int | 默认 1 | -| `pageSize` | int | 默认 20，最大 100 | - -响应返回 `PageResult<ProductSimpleListVO>`，每项有 `productId` / `productNo` / `name` / `tripDays` / `lineName`，拼下拉选项够用。 - -**注意**：该接口只返回**已上架**的产品（产品服务内部按 `status=PUBLISHED` 过滤），所以下拉选中的产品在保存时大概率能过 Feign 校验。极端情况（选完→运营 B 把它下架→运营 A 保存）仍会被 Feign 兜底拦住（返回第 5 条错误）。 - ---- - -## 小程序端变化 - -### `GET /mp/home-config/screen2` - -响应体里 `cards[]` 每项新增 `linkType` / `linkTargetType` / `linkTargetId`，语义和管理端一致。 - -**关键兜底**：无论是老 JSON（字段完全不存在）还是历史脏数据（`linkType=null`），后端读路径**统一兜底** `linkType=SEASON`，所以小程序拿到的 `linkType` **永远非空**。 - -#### 响应示例 - -```jsonc -GET /mp/home-config/screen2 -// 无需登录 - -{ - "code": 200, - "data": { - "brandStory": { - "title": "我们的品牌故事", - "subtitle": "在草原遇见你", - "body": "……", - "coverUrl": "https://cdn.example.com/brand/story.jpg", - "cards": [ - { - "title": "秋色限定", - "subtitle": "九月走一遭", - "coverUrl": "https://cdn.example.com/cards/autumn.jpg", - "linkType": "SEASON", - "linkTargetType": null, - "linkTargetId": null - }, - { - "title": "南线4天3晚", - "subtitle": "王牌行程", - "coverUrl": "https://cdn.example.com/cards/south.jpg", - "linkType": "PRODUCT", - "linkTargetType": "CORE", - "linkTargetId": 2045345825172639746 - } - ] - } - } -} -``` - -### 小程序前端跳转约定 - -```js -// 伪代码示意，实际路径以前端项目既有封装为准 -function onCardTap(card) { - switch (card.linkType) { - case 'SEASON': - return wx.navigateTo({ url: '/packages/product/season/list/list' }); - case 'CORE_LIST': - return wx.navigateTo({ url: '/packages/product/core/list/list' }); - case 'MENGMA': - return wx.navigateTo({ url: '/packages/product/mengma/list/list' }); - case 'PRODUCT': - // linkTargetType = CORE / GROUP，linkTargetId 是产品ID - // 按项目既有的"产品详情页"映射规则拼 url - return navigateToProductDetail(card.linkTargetType, card.linkTargetId); - default: - // ⭐⭐⭐ 必写的 default 兜底 - // 避免后端以后新增字典 value 时老客户端白屏 - return wx.navigateTo({ url: '/packages/product/season/list/list' }); - } -} -``` - -> ⚠️ **default 分支必须写**。后端字典 value 层面是可扩展的，如果以后加第 5 种跳转类型，老小程序不带 default 会直接不响应点击，是体验灾难。default 统一降级到"季节之旅"列表页最稳。 - ---- - -## 字典 `theme_card_link_type`（4 条） - -| dict_value | dict_label | sort | 前端路由 | -|---|---|---|---| -| `SEASON` | 季节之旅 | 10 | `packages/product/season/list/list` | -| `CORE_LIST` | 核心产品 | 20 | `packages/product/core/list/list` | -| `MENGMA` | 亲子游学 | 30 | `packages/product/mengma/list/list` | -| `PRODUCT` | 指定产品 | 40 | 按 linkTargetType + linkTargetId 拼产品详情 | - -**铁律**： -- `dict_value` 是**前端路由硬契约**，**严禁删除或修改** `dict_value` -- `dict_label`（中文显示名）可以改，影响的只是管理端下拉和字典弹窗的展示文案 -- 如果未来要新增跳转类型（比如 `ACTIVITY` 活动列表），**必须先前端发版带 default + 新 case，再后端加字典 value**，否则老客户端会静默失败 - -管理端「跳转类型」下拉建议走 `GET /dict/all`（公开接口，无需 token），取 `theme_card_link_type` 整块塞进 dictStore。 - ---- - -## 前后端发版顺序 - -1. **后端（本期已完成）**：hl-user-service + hl-mp-service 部署到测试环境，字典 SQL 各环境手动执行 -2. **前端管理端**：上新版（表单加跳转类型下拉 + 产品选择器） -3. **前端小程序**：上新版（cards 按 linkType 分发路由 + default 兜底） - -> 严格顺序：**字典 value 严禁改**；label 随时可改；新增 value 前必须先等小程序新版本覆盖率达标再改字典。 - ---- - -## 缓存 - -- Key：`home:screen2`（由 `HomeScreen2CacheEvictor` 管理，TTL 30 分钟；空值 60s 防穿透） -- 保存品牌故事且 `publish=true` 时**会清缓存**；`publish=false` 只存草稿**不清缓存** -- 读路径即便命中老缓存值（`linkType` 字段不存在），下次落回 DB 时会被 `extractCards` 兜底成 `SEASON`，前端能拿到稳定的 linkType - ---- - -## 不在本次范围 - -- ❌ **不做已有数据迁移**：DB 里老的 BrandStoryDTO JSON 不含新字段，读路径兜底 `SEASON` 后行为与改造前一致，无需 UPDATE -- ❌ **不加新的 internal 接口**：后端 `HomeBrandStoryService` 复用已有的 `ProductTypeFeignClient.batchProductSimple(ids)`，没有新增 internal 契约 -- ❌ **小程序端不做 Feign 回显校验**：小程序拿到 PRODUCT 类型后直接跳详情页，详情页自己会处理产品已下架/已删除的场景（现有能力） -- ❌ **管理端新增/编辑时不做跨卡片去重**：2 张卡片允许都跳同一个产品（产品运营的合理选择） - ---- - -## 部署提醒 - -### 字典 SQL（各环境手动执行一次） - -文件：`sql/dict_theme_card_link_type.sql`（随 PR 合入），内容： - -```sql --- sys_dict_type: dict_type_id = 8090 -INSERT IGNORE INTO sys_dict_type (dict_type_id, dict_type, dict_name, category, status, remark, created_at, updated_at) -VALUES (8090, 'theme_card_link_type', '首页主题卡片跳转类型', 'BUSINESS', 'ACTIVE', - '首页第二屏主题卡片点击跳转类型；value 为前端路由契约，严禁改', NOW(), NOW()); - --- sys_dict_data: dict_data_id = 80901..80904 -INSERT IGNORE INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status, remark, created_at, updated_at) -VALUES -(80901, 'theme_card_link_type', '季节之旅', 'SEASON', 10, 'ACTIVE', '跳转: packages/product/season/list/list', NOW(), NOW()), -(80902, 'theme_card_link_type', '核心产品', 'CORE_LIST', 20, 'ACTIVE', '跳转: packages/product/core/list/list', NOW(), NOW()), -(80903, 'theme_card_link_type', '亲子游学', 'MENGMA', 30, 'ACTIVE', '跳转: packages/product/mengma/list/list', NOW(), NOW()), -(80904, 'theme_card_link_type', '指定产品', 'PRODUCT', 40, 'ACTIVE', '跳转: 指定产品详情（linkTargetType + linkTargetId）', NOW(), NOW()); -``` - -- 幂等（`INSERT IGNORE`），可安全多次重跑 -- 库：`hl_user_service` -- 本地 / 测试服 / 生产各执行一次 - -### 服务重启 - -- **hl-user-service**：必须重启（主要代码在这） -- **hl-mp-service**：必须重启（`BrandCard` 是 common-core 里的跨服务 DTO，新增字段后 mp-service 旧 fat jar 里的 DTO 版本会丢字段，与 `common-core DTO 改动必须部署所有消费侧` 的教训一致） - ---- - -## 验证 - -- ✅ 后端单测 全绿（`HomeBrandStoryServiceTest` 覆盖 normalize / Feign 校验 / 降级分支） -- ✅ `AdminBrandStorySaveReqVOTest` 覆盖白名单 / PRODUCT 缺字段 / 非 PRODUCT 多余字段 -- ✅ `BrandCardTest` 覆盖 DTO 向后兼容反序列化（老 JSON 无新字段 → 字段 null） -- ✅ `MpHomeConfigServiceTest` 覆盖读路径 linkType 兜底为 SEASON -- ⏳ 前端发版后端到端回归 diff --git a/changelogs/2026-04/2026-04-21_mp-common-config-add-map-keys.md b/changelogs/2026-04/2026-04-21_mp-common-config-add-map-keys.md deleted file mode 100644 index b55907a..0000000 --- a/changelogs/2026-04/2026-04-21_mp-common-config-add-map-keys.md +++ /dev/null @@ -1,58 +0,0 @@ -# /mp/common/config 新增 3 个地图密钥字段 - -**日期**：2026-04-21 -**关联 PR**：#1114（Closes #1112） -**后端服务**：无代码改动，仅配置数据变更 -**环境**：测试环境已生效（正式环境待同步） - ---- - -## 变更内容 - -测试服 `sys_frontend_config` 表中原本 `config_type = 'SECRET'` 的 3 条高德地图密钥配置，已统一改为 `config_type = 'TEXT'`，从而通过 `/mp/common/config` 的公开白名单过滤，**暴露给小程序端**： - -| config_key | config_type 变化 | 用途 | -|------------|------------------|------| -| `AMAP_KEY` | SECRET → **TEXT** | 高德地图 API Key | -| `AMAP_SECURITY_CODE` | SECRET → **TEXT** | 高德地图安全密钥 | -| `mapApiKey` | SECRET → **TEXT** | 高德/腾讯地图 API Key | - -**已执行**： -```sql -UPDATE sys_frontend_config -SET config_type = 'TEXT' -WHERE config_key IN ('mapApiKey','AMAP_KEY','AMAP_SECURITY_CODE'); -``` -+ `redis-cli -n 0 del mp:common:config` 清旧缓存 - ---- - -## 小程序端新增 3 个字段 - -`GET https://api.test.1814.love:9443/mp/common/config` 的 `data` 里现在多了： - -```json -{ - "AMAP_KEY": "1c0a90d053120dec577819ccf9722d2f", - "AMAP_SECURITY_CODE": "7e04d99af5bd81db393af3468ec03fee", - "mapApiKey": "874b6e2d48c9637e410da36aed3757c6" -} -``` - -加上之前的 15 个字段，现在 `data` 共 **18 个 key**。 - ---- - -## 前端使用建议 - -- 小程序端需要渲染地图（行程路线图、集合点、景点坐标等）时，直接从 `config.AMAP_KEY` / `config.mapApiKey` 读取即可，不用再硬编码在代码里 -- 这些 key 受运营管理，后续密钥轮换只需在管理后台改配置 → 小程序无感（运营保存后缓存自动失效） -- 正式环境上线前运营需要在正式后台把对应 3 条配置的类型同样从「密钥」改成「文本」，或直接执行等效 SQL - ---- - -## 注意 - -- `/mp/common/config` **不需要登录**即可访问（公开接口），key 会暴露在任何请求这个接口的客户端 -- 如果某个 key 需要域名/AppID 限定或配额控制，需要在高德控制台绑定微信小程序 AppID、控制流量；密钥值本身本接口无法再隐藏 -- 服务端专用的真正敏感配置（比如支付回调签名、数据库密码等）应继续使用 `config_type = 'SECRET'`，不会出现在本接口返回里 diff --git a/changelogs/2026-04/2026-04-21_mp-common-config-merge-frontend-config.md b/changelogs/2026-04/2026-04-21_mp-common-config-merge-frontend-config.md deleted file mode 100644 index 7ce59eb..0000000 --- a/changelogs/2026-04/2026-04-21_mp-common-config-merge-frontend-config.md +++ /dev/null @@ -1,118 +0,0 @@ -# /mp/common/config 接口返回全部公开配置（合并 sys_frontend_config） - -**日期**：2026-04-21 -**PR**：#1114（Closes #1112） -**合并到 dev commit**：767e5cb4 -**后端服务**：hl-user-service（已部署测试环境） -**影响前端**：小程序端「应用配置」接口字段扩展 - ---- - -## 为什么改 - -`/mp/common/config` 过去只返回 `version` / `minVersion` / `servicePhone` 三个 yml 硬编码字段，管理后台「前端配置」页面（`sys_frontend_config` 表）运营的所有配置（主题色、Logo、站点名、分页大小、页脚文本等）完全没在小程序端吐出。 - -改完后小程序端一个接口拿到全部公开配置。 - ---- - -## 接口签名变化 - -### `GET /mp/common/config` - -**契约不变**：响应仍是 `Result<Map<String, Object>>`，`data` 字段类型保持 Map。 - -**data 内容扩展**： - -| 字段来源 | 说明 | -|---------|------| -| yml 基础（固定存在） | `version` / `minVersion` / `servicePhone` | -| `sys_frontend_config` 表 | **所有启用（status=1）且非 SECRET、未软删除的配置项**，key = `config_key`，value 按 `config_type` 做类型转换 | - -**类型转换规则**（后端已处理，前端直接使用）： - -| config_type | JSON value 类型 | 示例 | -|------------|----------------|------| -| `NUMBER` | `number`（整数 Long / 小数 Double） | `"defaultPageSize": 20` | -| `BOOLEAN` | `boolean` | `"enableWatermark": false` | -| `JSON` | `object` / `array` | `"themeConfig": { ... }` | -| `TEXT` / `COLOR` / `IMAGE` | `string` | `"primaryColor": "#1890FF"` | -| 解析失败 | 原 `string`（降级兜底） | —— | - -**过滤规则**： -- `config_type = 'SECRET'` 的不返回（第三方 API key 等敏感配置） -- `status = 0`（停用）的不返回 -- `deleted_at IS NOT NULL`（软删除）的不返回 - -**冲突规则**： -- 若 `sys_frontend_config` 表存在 `config_key = 'version'`（或 `minVersion` / `servicePhone`），**DB 值覆盖 yml 默认值** -- 当前测试/正式环境 DB 不存在这三个 key，无实际冲突 - ---- - -## 测试环境实测响应 - -```bash -curl -sk "https://api.test.1814.love:9443/mp/common/config" -``` - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "version": "1.0.0-dev", - "minVersion": "1.0.0", - "servicePhone": "400-000-0000", - "primaryColor": "#1890FF", - "accentColor": "#FF6B35", - "backgroundColor": "#F5F7FA", - "textColor": "#303133", - "defaultPageSize": 20, - "cacheExpireMinutes": 30, - "enableWatermark": false, - "siteName": "呼籁旅行", - "logoUrl": "", - "footerText": "呼籁旅行 版权所有", - "copyrightYear": "2026", - "customerServicePhone": "" - } -} -``` - ---- - -## 前端影响 - -### 可以改（推荐） - -**以前**：小程序端可能自己在代码里写死主题色、站点名、分页大小等默认值。 -**现在**：这些配置直接从 `/mp/common/config` 读取，运营后台改完小程序端无需发版即可生效（缓存 30 分钟，运营端保存后自动失效）。 - -### 不需要改 - -- `version` / `minVersion` / `servicePhone` 三个原有字段**完全保留**，读取方式不变 -- 响应结构 `{code, message, data, success}` 不变 - -### 前端建议 - -1. `data` 类型建议声明为 `Record<string, any>` 或按需定义强类型（已知 key 列表见上方实测响应） -2. 新 key 可能陆续增加（运营后台可以新增），前端按需解构即可，不要假设 data 只有固定字段 -3. NUMBER 类型已转为 JS number，不用再 `parseInt(...)`；BOOLEAN 已转为 js boolean，不用再比较字符串 `"true"` - ---- - -## 缓存行为 - -- 小程序端接口：`@MpCache(prefix="common:config", ttl=1800s)`，Redis key：`mp:common:config` -- 运营后台修改 `sys_frontend_config` 任一条 → `FrontendConfigService` 写路径触发 `depsManager.invalidateSource("table:sys_frontend_config")` → `MpCommonController` deps 命中该 source → 缓存被精准失效 -- 首次部署本次 PR 后，旧缓存（ttl 未到期）会阻挡新数据，已在部署时主动清理一次：`redis-cli -n 0 del mp:common:config` - ---- - -## 关联 - -- Issue：#1112 -- 非目标：本 PR **不改** `/mp/config`（分组查询接口，`MpConfigController`） -- 历史遗留：`MpCacheEvict.categoryMap` 中 `config → table:frontend_config`（少 `sys_` 前缀）与实际 deps `table:sys_frontend_config` 不一致，本次不动，留后续清理工单 diff --git a/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md b/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md deleted file mode 100644 index 9b37573..0000000 --- a/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md +++ /dev/null @@ -1,330 +0,0 @@ -# 微信小程序 · 行程前出发准备页 + 订单详情页 聚合接口 - -**日期**:2026-04-21 -**影响**:**微信小程序** 行程 Tab(行程前态)与订单详情页(5 态) -**PR**:#1074 · #1087 · #1090(V1) / #1078 · #1096(V3) -**Issue**:#1073 · #1086 · #1089(V1) / #1076 · #1095(V3) - ---- - -## 概述 - -新增两个页面级聚合接口,一次拉全该页所需全部数据,替代前端分别调用 3~6 个细粒度接口的方案: - -| 接口 | 对应页面 | -|---|---| -| V1 `GET /mp/trip/{orderId}/pre-trip-dashboard` | 行程前·出发准备(订单已确认、未出发) | -| V3 `GET /mp/order/{orderId}/dashboard` | 订单详情页(待付款/行程中/已完成/已取消/退款中 5 态) | - -> V2 `GET /mp/trip/today-dashboard`(行程中页)另外交付,本文档只覆盖 V1 + V3。 - ---- - -## V1. 行程前出发准备页聚合 - -### 接口 - -``` -GET /mp/trip/{orderId}/pre-trip-dashboard -``` - -**鉴权**:需要 Bearer token(登录小程序用户)。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|---|---|---|---|---| -| orderId | Path | Long | ✅ | 订单 ID | - -### 出参 `Result<MpPreTripDashboardVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| orderHeader | OrderHeader | 订单头(倒计时卡片) | -| preTripChecklist | MpPreTripChecklistVO | 出发准备清单 | -| team | TeamVO | 带队团队 | -| tripOverview | `List<DayItem>` | 行程概览(每天一行) | -| customerServicePhone | String | 客服电话,如 `0470-8871922` | - -**`OrderHeader`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| orderId | Long | 订单ID | -| orderNo | String | 订单编号 | -| productName | String | 产品名称 | -| productSubtitle | String | 产品副标题 | -| tierName | String | 档位名称,如 `舒适档`(未选档为 null) | -| tierDescription | String | 档位描述 | -| productCoverUrl | String | 产品封面 URL | -| departureDate | LocalDate | 出发日期 | -| tripDays | Integer | 行程天数 | -| tripNights | Integer | 行程晚数 | -| dateRange | String | 日期范围文字,如 `2026年7月1日 — 7月6日` | -| daysToDeparture | Integer | 距出发天数 | -| totalPeople | Integer | 总人数 | -| adultCount | Integer | 成人数 | -| childCount | Integer | 儿童数 | -| tripPhase | String | `BEFORE_START` / `IN_PROGRESS` / `ENDED` | - -**`MpPreTripChecklistVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| totalCount | Integer | 总项数 | -| completedCount | Integer | 已完成项数 | -| items | `List<MpChecklistItemVO>` | 清单项,按 WARNING > PENDING > DONE 排序 | - -**`MpChecklistItemVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| key | String | `DEPOSIT_PAID` / `TRAVELER_INFO` / `ARRIVAL_INFO` / `CONTRACT_SIGN` / `INSURANCE` / `CHECKLIST_CONFIRMED` | -| title | String | 标题 | -| subtitle | String | 副标题说明 | -| status | String | `DONE` / `PENDING` / `WARNING` | -| statusLabel | String | 状态中文标签 | -| actionType | String | `NAVIGATE` / `CONFIRM` / `CONTACT_CS`;null 表示纯展示 | -| actionPayload | `Map<String, Object>` | 动作参数载荷,如 `{pageKey: "arrival_form", orderId: "..."}` | - -**`TeamVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| leader | MpGuideInfoVO | 领队(未分配为 null) | -| photographer | MpPhotographerInfoVO | 摄影师(未分配为 null) | -| driver | MpVehicleDetailVO | 司机(原型暂不展示,保持 null) | - -`MpGuideInfoVO` / `MpPhotographerInfoVO` 字段:`staffId / name / avatarUrl / role / roleLabel / phone(脱敏) / remark / assigned` - -**`DayItem`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| dayNumber | Integer | 第几天 | -| date | LocalDate | 当天日期 | -| title | String | 当天标题 | - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "orderHeader": { - "orderId": 20439, - "orderNo": "HL20260701123", - "productName": "草原环线", - "productSubtitle": "6天5晚舒适套餐", - "tierName": "舒适档", - "tierDescription": "升级双早+SPA", - "productCoverUrl": "https://cdn.1814.love/cover.png", - "departureDate": "2026-07-01", - "tripDays": 6, - "tripNights": 5, - "dateRange": "2026年7月1日 — 7月6日", - "daysToDeparture": 12, - "totalPeople": 2, - "adultCount": 2, - "childCount": 0, - "tripPhase": "BEFORE_START" - }, - "preTripChecklist": { - "totalCount": 6, - "completedCount": 3, - "items": [ - {"key":"DEPOSIT_PAID","title":"订金已支付","status":"DONE","statusLabel":"已完成"}, - {"key":"ARRIVAL_INFO","title":"填写接送机信息","subtitle":"司机将根据此信息接送","status":"PENDING","statusLabel":"待处理","actionType":"NAVIGATE","actionPayload":{"pageKey":"arrival_form","orderId":"20439"}} - ] - }, - "team": { - "leader": {"name":"巴图","roleLabel":"领队","phone":"138****5678","remark":"10年呼伦贝尔带队经验","assigned":true}, - "photographer": {"name":"李维","roleLabel":"摄影师","phone":"139****1234","assigned":true}, - "driver": null - }, - "tripOverview": [ - {"dayNumber":1,"date":"2026-07-01","title":"海拉尔集合·接机入住"}, - {"dayNumber":2,"date":"2026-07-02","title":"呼籁营地 → 莫日格勒河 → 额尔古纳"} - ], - "customerServicePhone": "0470-8871922" - }, - "success": true -} -``` - -### 边界行为 - -- `team.leader / photographer / driver` 任意一个字段可能为 null(未分配) -- `orderHeader.tierName / tierDescription` 未选档或下单时未绑定档位则为 null -- 订单不存在或无权限访问:HTTP 500,`message` 含 `orderId` 和错误原因 -- `guide / photographer` 底层接口失败:对应字段置 null,主数据仍返回(降级) - ---- - -## V3. 订单详情页聚合 - -### 接口 - -``` -GET /mp/order/{orderId}/dashboard -``` - -**鉴权**:需要 Bearer token。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|---|---|---|---|---| -| orderId | Path | Long | ✅ | 订单 ID | - -### 出参 `Result<MpOrderDashboardVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| order | MpOrderDetailVO | 订单主体,字段同 `GET /mp/order/{orderId}` 返回值 | -| files | FilesVO | 重要文件三合一 | -| insurance | MpInsuranceDetailVO | 保险详情(未投保为 null) | -| refund | RefundVO | 退款模块(非退款状态为 null) | - -`order` 为完整的订单详情,常用字段:`orderId / orderNo / status / statusLabel / productName / productSubtitle / tierSeq / tierName / tierDescription / productCoverUrl / tripDays / totalPrice / paidAmount / depositAmount / paymentType / travelers / supplies / equipmentAdvice` 等。完整字段以 `GET /mp/order/{orderId}` 为准。 - -**`FilesVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| contract | MpContractSummaryVO | 合同(无合同为 null) | -| invoice | MpInvoiceSummaryVO | 发票(未开票为 null) | -| insurancePolicyPdfUrl | String | 保单 PDF 下载路径,如 `/mp/insurance/policy-pdf/20439` | - -**`MpContractSummaryVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| contractId | Long | 合同ID | -| contractNo | String | 合同编号 | -| status | String | `PREPARING` / `UNSIGNED` / `SIGNED` / `VOID` 等 | -| statusLabel | String | 状态中文 | -| contractType | String | `TOUR` / `INSURANCE` | -| signedAt | LocalDateTime | 签署时间 | -| downloadUrl | String | 合同 PDF 下载链接 | - -**`MpInvoiceSummaryVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| invoiceId | Long | 发票ID | -| invoiceNo | String | 发票号 | -| status | String | `PENDING` / `ISSUED` / `FAILED` 等 | -| statusLabel | String | 状态中文 | -| titleType | String | `PERSONAL` / `COMPANY` | -| invoiceTitle | String | 发票抬头 | -| taxNumber | String | 税号 | -| amount | BigDecimal | 金额 | -| email | String | 接收邮箱 | -| issuedAt | LocalDateTime | 开票时间 | -| pdfUrl | String | 电子发票 PDF URL | - -**`MpInsuranceDetailVO`**:字段见 `GET /mp/order/{orderId}/insurance`。含 `schemeId / schemeName / description / isOverseas / totalDays / notice / segments[] / policies[]`。 - -**`RefundVO`**(只在订单状态为 `CANCELLED` / `REFUNDING` / `REFUNDED` / `REFUND_REJECTED` / `APPEALING` 时有值,否则整个字段为 null): - -| 字段 | 类型 | 说明 | -|---|---|---| -| detail | MpRefundDetailVO | 退款申请详情 | -| progress | MpRefundProgressVO | 退款进度时间线 | - -`MpRefundDetailVO` 字段见 `GET /mp/order/{orderId}/refund-detail`。 -`MpRefundProgressVO` 字段:`steps[] / currentStep / refundAmount / refundMethod / refundArrivalTime`。 - -### 响应示例 - -**已确认订单(无退款)**: - -```json -{ - "code": 200, - "message": "成功", - "data": { - "order": { - "orderId": 20439, - "status": "CONFIRMED", - "statusLabel": "已确认", - "productName": "草原环线", - "productSubtitle": "6天5晚舒适套餐", - "tierName": "舒适档", - "tierDescription": "升级双早+SPA", - "totalPrice": 5800.00, - "travelers": [], - "supplies": [] - }, - "files": { - "contract": {"contractId":8001,"contractNo":"HL-2026-070128","status":"SIGNED","statusLabel":"已签署","contractType":"TOUR","downloadUrl":"https://cdn.1814.love/contract-8001.pdf"}, - "invoice": null, - "insurancePolicyPdfUrl": "/mp/insurance/policy-pdf/20439" - }, - "insurance": { - "schemeName": "旅行意外险", - "policies": [{"policyNo":"PA20260628****5512","status":"INSURED","statusLabel":"已承保"}] - }, - "refund": null - }, - "success": true -} -``` - -**已取消订单(含退款进度)**: - -```json -{ - "code": 200, - "message": "成功", - "data": { - "order": {"orderId":20439,"status":"CANCELLED","statusLabel":"已取消"}, - "files": { - "contract": null, - "invoice": null, - "insurancePolicyPdfUrl": "/mp/insurance/policy-pdf/20439" - }, - "insurance": null, - "refund": { - "detail": { - "applicationId": 6001, - "status": "REFUNDING", - "statusLabel": "退款中", - "actualAmount": 1000.00, - "refundType": "DEPOSIT", - "refundTypeLabel": "订金退款" - }, - "progress": { - "currentStep": 2, - "refundAmount": 1000.00, - "refundMethod": "原路返回·微信", - "steps": [ - {"title":"提交退款申请","status":"COMPLETED","time":"2026-04-15 10:30:00"}, - {"title":"商家审核","status":"ACTIVE","time":"2026-04-16 09:10:00"}, - {"title":"退款处理","status":"PENDING","time":null}, - {"title":"退款到账","status":"PENDING","time":null} - ] - } - } - }, - "success": true -} -``` - -### 边界行为 - -- 订单不存在或无权限:HTTP 500,`message` 含 `orderId` -- `contract / invoice / insurance` 底层接口失败:对应字段置 null,不影响订单主体 -- 非退款状态订单:`refund = null`(不调用退款相关底层接口) -- 退款状态订单两个退款接口都返 null 时:`refund = null`(不返回 `{detail:null, progress:null}` 的壳子) - ---- - -## 单测 - -| 测试类 | 覆盖用例 | 结果 | -|---|---|---| -| `PreTripDashboardAggregationServiceTest` | 正常路径 + guide 降级 + photographer 降级 + trip 错误码 + trip 空数据 + itinerarySummary 缺失 | 6/6 通过 | -| `OrderDashboardAggregationServiceTest` | 非退款状态 + 已取消状态(refund 填充) + 退款中但退款接口返 null + contract 降级 + invoice errorCode + order 错误码 / 空数据 / 异常 | 8/8 通过 | - ---- - -## 规范注记 - -- 返回字段除 `MpChecklistItemVO.actionPayload`(任意 key 跳转载荷)外,**全部强类型 VO**,无 `Map<String, Object>` -- 所有 VO 用 `@JsonIgnoreProperties(ignoreUnknown = true)`,后端字段扩展不会影响前端反序列化 -- 短 TTL 缓存:V1 30 秒 / V3 30 秒 diff --git a/changelogs/2026-04/2026-04-21_mp-order-arrival.md b/changelogs/2026-04/2026-04-21_mp-order-arrival.md deleted file mode 100644 index 2691ae6..0000000 --- a/changelogs/2026-04/2026-04-21_mp-order-arrival.md +++ /dev/null @@ -1,413 +0,0 @@ -# 微信小程序 · 订单到达/离开信息接口(5 个 CRUD) - -**日期**:2026-04-21 -**影响**:**微信小程序** 行程前·出发准备页(原型 `ew2Kk`)、订单详情到达信息弹窗(原型 `6pfmI / uq0UL / K2s5H / L4xYN / oVMYy / AQ21V / amizC`) -**PR**:#1000(Closes #998) - ---- - -## 概述 - -订单"分批到达/离开"模型,用户在行程前填写: - -- **到达(ARRIVAL)**:从住所抵达目的地 -- **离开(DEPARTURE)**:从目的地返程 - -每个订单可有多批(带小孩/家人分几趟飞),每批一条 `MpArrivalPlanRespVO` 记录,包含交通方式、班次、站点、时间、本批涉及的出行人。 - -共 **5 个 CRUD** 接口:查全量、新增、全量替换、修改、删除。 - ---- - -## 1. 查全量批次 - -``` -GET /mp/order/{orderId}/arrival -``` - -**鉴权**:Bearer token。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -### 出参 `Result<MpArrivalListRespVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| orderId | Long | 订单ID | -| arrivals | `List<MpArrivalPlanRespVO>` | 到达批次列表 | -| departures | `List<MpArrivalPlanRespVO>` | 离开批次列表 | - -`MpArrivalPlanRespVO` 字段见第 2 节出参。 - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "orderId": 700001, - "arrivals": [ - { - "planId": 800001, - "orderId": 700001, - "direction": "ARRIVAL", - "directionLabel": "到达", - "transportType": "FLIGHT", - "transportTypeLabel": "飞机", - "transportNo": "CZ6255", - "carrier": "南方航空", - "departStation": "北京首都T3", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "selfDrivePeriod": null, - "selfDrivePeriodLabel": null, - "selfDriveEta": null, - "remark": "带小孩,需婴儿座椅", - "creatorType": "USER", - "createTime": "2026-07-01 10:00:00", - "travelers": [ - {"travelerId":10001,"name":"张三","travelerType":"ADULT"}, - {"travelerId":10002,"name":"张小三","travelerType":"CHILD"} - ] - } - ], - "departures": [] - }, - "success": true -} -``` - ---- - -## 2. 新增批次 - -``` -POST /mp/order/{orderId}/arrival -``` - -**鉴权**:Bearer token。 -**创建者类型**:`creatorType=USER`(用户自填)。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -Body `MpArrivalPlanSaveReqVO`: - -| 字段 | 类型 | 必填 | 约束 | 说明 | -|---|---|---|---|---| -| direction | String | ✅ | - | `ARRIVAL` / `DEPARTURE`(字典 `transport_direction`) | -| transportType | String | ✅ | - | `FLIGHT` / `TRAIN` / `SELF_DRIVE`(字典 `transport_type` 子集) | -| transportNo | String | FLIGHT/TRAIN 必填 | ≤32 | 航班号/车次号,如 `CZ6255` | -| carrier | String | 否 | ≤64 | 航司/铁路公司,如 `南方航空` | -| departStation | String | 否 | ≤64 | 出发站/机场 | -| arriveStation | String | 否 | ≤64 | 到达站/机场 | -| departTime | LocalDateTime | 否 | - | 出发时间 | -| arriveTime | LocalDateTime | 否 | - | 到达时间 | -| selfDrivePeriod | String | SELF_DRIVE 必填 | - | `MORNING` / `AFTERNOON` / `EVENING`(字典 `self_drive_period`) | -| selfDriveEta | LocalDateTime | 否 | - | 自驾预计到达精确时间 | -| remark | String | 否 | ≤255 | 用户备注 | -| travelerIds | `List<Long>` | ✅ 非空 | - | 本批次涉及的出行人 ID 列表;必须属于本订单 | - -### 出参 `Result<MpArrivalPlanRespVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| planId | Long | 批次ID | -| orderId | Long | 订单ID | -| direction | String | 方向 | -| directionLabel | String | 方向中文标签 | -| transportType | String | 交通方式 | -| transportTypeLabel | String | 交通方式中文标签 | -| transportNo | String | 航班号/车次号 | -| carrier | String | 航司/铁路公司 | -| departStation | String | 出发站 | -| arriveStation | String | 到达站 | -| departTime | LocalDateTime | 出发时间 | -| arriveTime | LocalDateTime | 到达时间 | -| selfDrivePeriod | String | 自驾时段 | -| selfDrivePeriodLabel | String | 自驾时段中文标签,如 `下午(12:00-18:00)` | -| selfDriveEta | LocalDateTime | 自驾预计到达 | -| remark | String | 备注 | -| creatorType | String | `USER`(用户自填)/`ADMIN`(定制师代录)(字典 `creator_type`) | -| createTime | LocalDateTime | 创建时间 | -| travelers | `List<MpArrivalPlanTravelerSimpleVO>` | 本批次涉及的出行人(脱敏) | - -**`MpArrivalPlanTravelerSimpleVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| travelerId | Long | 出行人ID | -| name | String | 姓名 | -| travelerType | String | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY`(字典 `traveler_type`) | - -### 请求示例 - -```json -{ - "direction": "ARRIVAL", - "transportType": "FLIGHT", - "transportNo": "CZ6255", - "carrier": "南方航空", - "departStation": "北京首都T3", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "remark": "带小孩,需婴儿座椅", - "travelerIds": [10001, 10002] -} -``` - ---- - -## 3. 全量替换 - -``` -POST /mp/order/{orderId}/arrival/batch -``` - -**鉴权**:Bearer token。 - -先软删当前所有批次,再按请求体批量创建。空数组 `[]` = 清空订单的所有到达/离开批次。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -Body:`List<MpArrivalPlanSaveReqVO>`(每项结构同第 2 节)。 - -### 出参 - -`Result<MpArrivalListRespVO>` — 替换完成后的全量数据,结构同第 1 节。 - ---- - -## 4. 修改批次 - -``` -PUT /mp/order/{orderId}/arrival/plan/{planId} -``` - -**鉴权**:Bearer token。 - -**覆盖语义**:按字段全量覆盖,包括 `travelerIds`(替换旧关联)。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | -| planId | Path | Long | ✅ | - -Body:`MpArrivalPlanSaveReqVO`(同第 2 节)。 - -### 出参 - -`Result<MpArrivalPlanRespVO>` — 修改后的批次,结构同第 2 节。 - ---- - -## 5. 删除批次 - -``` -DELETE /mp/order/{orderId}/arrival/plan/{planId} -``` - -**鉴权**:Bearer token。 - -**级联**:软删关联的出行人绑定行。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | -| planId | Path | Long | ✅ | - -### 出参 - -`Result<Void>`: - -```json -{ "code": 200, "message": "成功", "data": null, "success": true } -``` - ---- - -## 边界行为 - -- **字段校验**:`transportType=FLIGHT/TRAIN` 时 `transportNo` 必填;`transportType=SELF_DRIVE` 时 `selfDrivePeriod` 必填 -- **出行人校验**:`travelerIds` 中的 ID 必须属于本订单,否则 400 -- **订单不存在/无权限**:500,`message` 含 `orderId` -- 用户填的批次 `creatorType=USER`;定制师后台代录的 `creatorType=ADMIN` - ---- - -## 辅助接口 · 航班/火车动态查询(填写表单时用,来自同一批交付) - -数据源:飞常准官方 API,resource-service 侧做 Redis 缓存后透传。返回为**列表**(同航班号可能有共享航班、同车次日间可能多班次)。 - -### 航班查询(3 个) - -| 路径 | 入参 | 场景 | -|---|---|---| -| `GET /mp/transport/flight` | `flightNo`(如 `CA1133`)、`date`(`yyyy-MM-dd`) | 按航班号 + 日期查 | -| `GET /mp/transport/flight/by-airport` | `dep`、`arr`(机场三字码,如 `PEK`/`HLD`)、`date` | 按出发/到达机场三字码 + 日期查 | -| `GET /mp/transport/flight/by-city` | `depCity`、`arrCity`(城市三字码,如 `BJS`/`SHA`)、`date` | 按出发/到达城市 + 日期查(覆盖多机场) | - -**出参**:`Result<List<MpFlightInfoVO>>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| flightNo | String | 航班号,如 `CA1133` | -| airline | String | 航空公司名称 | -| category | String | 航班属性:`国内`/`国际`/`地区` | -| departAirportCode | String | 出发机场三字码,如 `PEK` | -| arriveAirportCode | String | 到达机场三字码,如 `HLD` | -| departAirport | String | 出发机场名称,如 `北京首都` | -| arriveAirport | String | 到达机场名称,如 `呼伦贝尔海拉尔` | -| departCity | String | 出发城市,如 `北京` | -| arriveCity | String | 到达城市,如 `海拉尔` | -| planDepartTime | String | 计划起飞时间(`yyyy-MM-dd HH:mm:ss`) | -| planArriveTime | String | 计划到达时间(`yyyy-MM-dd HH:mm:ss`) | -| actualDepartTime | String | 实际起飞时间(未起飞为 null) | -| actualArriveTime | String | 实际到达时间(未到达为 null) | -| status | String | 航班状态:`计划`/`起飞`/`到达`/`延误`/`取消`/`返航`/`备降` 等 | -| stopFlag | String | 是否经停:`0`=不经停,`1`=经停 1 次,`n`=经停 n 次 | -| shareFlag | String | 是否共享航班:`0`=否,`1`=是 | -| shareFlightNo | String | 共享航班号(实际承运航班号) | -| departTerminal | String | 出发航站楼,如 `T2` | -| arriveTerminal | String | 到达航站楼 | -| boardGate | String | 登机口 | -| arriveExit | String | 到达出口 | -| departTimezone | String | 出发时区偏移(秒) | -| arriveTimezone | String | 到达时区偏移(秒) | - -**响应示例**: - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "flightNo": "CA1133", - "airline": "中国国际航空股份有限公司", - "category": "国内", - "departAirportCode": "PEK", - "arriveAirportCode": "HLD", - "departAirport": "北京首都", - "arriveAirport": "呼伦贝尔海拉尔", - "departCity": "北京", - "arriveCity": "海拉尔", - "planDepartTime": "2026-07-10 06:45:00", - "planArriveTime": "2026-07-10 08:55:00", - "actualDepartTime": null, - "actualArriveTime": null, - "status": "计划", - "stopFlag": "0", - "shareFlag": "0", - "shareFlightNo": null, - "departTerminal": "T2", - "arriveTerminal": null, - "boardGate": null, - "arriveExit": null, - "departTimezone": "28800", - "arriveTimezone": "28800" - } - ], - "success": true -} -``` - -### 火车查询(4 个) - -| 路径 | 入参 | 场景 | -|---|---|---| -| `GET /mp/transport/train` | `trainNo`(如 `G1`)、`date` | 按车次号查,返回含 `stops` 全部经停站 | -| `GET /mp/transport/train/by-train-no-stations` | `trainNo`、`dep`、`arr`(车站中文名)、`date` | 按车次 + 出发站 + 到达站,比按车次多返回 `departStatus`/`arriveStatus`,**不返回 `stops`** | -| `GET /mp/transport/train/by-station` | `dep`、`arr`(车站中文名)、`date` | 按出发站 + 到达站,返回经过该区间的所有车次 | -| `GET /mp/transport/train/by-city` | `depCity`、`arrCity`(城市中文名,如 `北京`)、`date` | 按出发城市 + 到达城市(含所有车站) | - -**出参**:`Result<List<MpTrainInfoVO>>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| trainNo | String | 车次,如 `G1` | -| departStation | String | 出发车站,如 `北京南` | -| arriveStation | String | 到达车站,如 `上海虹桥` | -| shutdown | String | 是否停运:`0`=否,`1`=是 | -| planDepartTime | String | 计划出发时间 | -| planArriveTime | String | 计划到达时间 | -| estimatedDepartTime | String | 预计出发时间(仅 `by-train-no-stations` 返回) | -| estimatedArriveTime | String | 预计到达时间(仅 `by-train-no-stations` 返回) | -| actualDepartTime | String | 实际出发时间(仅 `by-train-no-stations` 返回) | -| actualArriveTime | String | 实际到达时间(仅 `by-train-no-stations` 返回) | -| departStatus | String | 出发状态:`计划`/`正点`/`晚点`/`出发`(仅 `by-train-no-stations` 返回) | -| arriveStatus | String | 到达状态:`计划`/`正点`/`晚点`/`到达`(仅 `by-train-no-stations` 返回) | -| duration | Integer | 运行时长(分钟) | -| stops | `List<MpTrainStopVO>` | 经停站列表(仅按车次号 `/mp/transport/train` 返回) | - -**`MpTrainStopVO`**: - -| 字段 | 类型 | 说明 | -|---|---|---| -| stationName | String | 车站名称,如 `沧州西` | -| arriveTime | String | 到站时间 | -| departTime | String | 发车时间 | - -**响应示例**(按车次号): - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "trainNo": "G1", - "departStation": "北京南", - "arriveStation": "上海虹桥", - "shutdown": "0", - "planDepartTime": "2026-07-10 06:30", - "planArriveTime": "2026-07-10 11:24", - "duration": 294, - "stops": [ - {"stationName": "北京南", "arriveTime": null, "departTime": "2026-07-10 06:30"}, - {"stationName": "沧州西", "arriveTime": "2026-07-10 07:18", "departTime": "2026-07-10 07:20"}, - {"stationName": "上海虹桥", "arriveTime": "2026-07-10 11:24", "departTime": null} - ] - } - ], - "success": true -} -``` - -### 边界 - -- 查不到数据(航班号无效/停运):返回 `data: []` -- 非常准上游异常/超时:返回 500,`message` 含上游错误码 -- 日期格式:`yyyy-MM-dd`,校验不通过返回 500 `日期格式错误，应为yyyy-MM-dd` -- 所有三字码/城市码/车站名不区分大小写(三字码内部自动 `toUpperCase`) - ---- - -## 字典依赖 - -| 字典类型 | 说明 | -|---|---| -| `transport_direction` | `ARRIVAL` / `DEPARTURE` | -| `transport_type` | `FLIGHT` / `TRAIN` / `SELF_DRIVE`(本场景只用这 3 个子集) | -| `self_drive_period` | `MORNING` / `AFTERNOON` / `EVENING` | -| `creator_type` | `USER` / `ADMIN` | -| `traveler_type` | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | - -所有 `xxxLabel` 字段均由 BFF 透传自 order-v2,已经是中文展示值。 diff --git a/changelogs/2026-04/2026-04-21_mp-order-supplies-checklist.md b/changelogs/2026-04/2026-04-21_mp-order-supplies-checklist.md deleted file mode 100644 index 577f8cb..0000000 --- a/changelogs/2026-04/2026-04-21_mp-order-supplies-checklist.md +++ /dev/null @@ -1,107 +0,0 @@ -# 微信小程序 · 订单行李推荐接口 - -**日期**:2026-04-21 -**影响**:**微信小程序** 订单详情行李推荐弹窗(原型 `zgNiD`) -**PR**:#1042(Closes #1041) - ---- - -## 概述 - -订单详情页"行李推荐"弹窗独立查询接口。从产品快照中解析备品清单,按分类分组返回,附装备建议富文本。 - -> C 端展示已去除成本字段(`hasCost` / `unitPrice`),后端已过滤掉成本项(`hasCost=true`),仅返回给用户看的推荐行李。 - ---- - -## 接口 - -``` -GET /mp/order/{orderId}/supplies-checklist -``` - -**鉴权**:Bearer token。 -**缓存**:5 分钟。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -### 出参 `Result<MpSuppliesChecklistRespVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| orderId | Long | 订单ID | -| categories | `List<MpSuppliesCategoryVO>` | 备品清单(按分类分组;空列表表示无推荐) | -| equipmentAdvice | String | 装备建议富文本 HTML(可能为 null) | - -**`MpSuppliesCategoryVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| category | String | 分类名,如 `衣物` / `配件` / `药品` | -| items | `List<MpSuppliesItemVO>` | 该分类下的备品列表 | - -**`MpSuppliesItemVO`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| suppliesName | String | 备品名称,如 `冲锋衣` | -| category | String | 分类(冗余,便于扁平化处理) | -| quantity | Integer | 数量 | -| billingType | String | `PER_PERSON`(按人数)/ `PER_QUANTITY`(按数量) | -| sortOrder | Integer | 排序(升序) | - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "orderId": 20439, - "categories": [ - { - "category": "衣物", - "items": [ - {"suppliesName":"冲锋衣","category":"衣物","quantity":1,"billingType":"PER_PERSON","sortOrder":1}, - {"suppliesName":"保暖内衣","category":"衣物","quantity":1,"billingType":"PER_PERSON","sortOrder":2} - ] - }, - { - "category": "配件", - "items": [ - {"suppliesName":"防晒霜","category":"配件","quantity":1,"billingType":"PER_QUANTITY","sortOrder":1}, - {"suppliesName":"墨镜","category":"配件","quantity":1,"billingType":"PER_PERSON","sortOrder":2} - ] - } - ], - "equipmentAdvice": "<p>呼伦贝尔 7 月早晚温差大,建议携带薄款冲锋衣。防晒需求高,墨镜 + 防晒霜必备。</p>" - }, - "success": true -} -``` - -### 边界行为 - -- 订单不存在或无权限:500,`message` 含 `orderId` -- 产品快照无备品配置:`categories=[]`,`equipmentAdvice=null` -- 所有备品都是成本项:`categories=[]`(已过滤) - ---- - -## 数据来源 - -字段从订单绑定产品的**产品快照**中解析得到,下单时刻的备品清单锁定,后续产品端备品变动不影响已下单订单。 - ---- - -## 关联字段(其他接口) - -订单详情 `GET /mp/order/{orderId}` 的返回 VO(`MpOrderDetailVO`)本身也带 `supplies` 和 `equipmentAdvice` 字段,用于整单数据一次读取场景。本独立接口专用于弹窗按需拉取。 - -| 接口 | 字段 | 说明 | -|---|---|---| -| `GET /mp/order/{orderId}` | `supplies: List<OrderSuppliesVO>` | 订单备品(扁平列表,不分组) | -| `GET /mp/order/{orderId}` | `equipmentAdvice: String` | 装备建议富文本 | -| `GET /mp/order/{orderId}/supplies-checklist` | 见上文 | 按分类分组 + 装备建议,弹窗专用 | diff --git a/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md b/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md deleted file mode 100644 index 434030b..0000000 --- a/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md +++ /dev/null @@ -1,206 +0,0 @@ -# 微信小程序 · 订单出行人 CRUD 接口(4 个) - -**日期**:2026-04-21 -**影响**:**微信小程序** 订单出行人管理(原型 `L4xYN` 乘坐人员勾选列表、`Bf9jC` 添加人员弹窗) -**PR**:#1022(Closes #1020) - ---- - -## 概述 - -订单维度的出行人管理接口,区别于用户维度的"我的常用出行人": - -| 接口前缀 | 数据范围 | 用途 | -|---|---|---| -| `/mp/order/{orderId}/traveler` | **本接口**,`order_traveler` 表 | 订单出行人(随订单绑定) | -| `/mp/user/traveler` | 用户维度`user-service` | 用户常用出行人(跨订单复用) | - -共 **4 个接口**:列表、新增、修改、删除。 - ---- - -## 1. 出行人列表 - -``` -GET /mp/order/{orderId}/traveler -``` - -**鉴权**:Bearer token。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -### 出参 `Result<List<MpOrderTravelerVO>>` - -**`MpOrderTravelerVO`**: - -| 字段 | 类型 | 说明 | -|---|---|---| -| travelerId | Long | 出行人ID | -| name | String | 姓名 | -| travelerType | String | 出行人类型(字典 `traveler_type`):`ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | -| travelerTypeLabel | String | 类型中文标签 | -| idCardType | String | 证件类型(字典 `id_card_type`):`ID_CARD` / `PASSPORT` / `HK_MACAO_PASS` / `TAIWAN_PASS` / `OTHER` | -| idCardTypeLabel | String | 证件类型中文标签 | -| idCardNo | String | 证件号码 | -| gender | String | `1`=男 / `2`=女 | -| birthday | LocalDate | 出生日期 | -| phone | String | 手机号 | -| nationality | String | 国籍 | -| emergencyContact | String | 紧急联系人姓名 | -| emergencyPhone | String | 紧急联系人电话 | -| email | String | 邮箱 | - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "travelerId": 10001, - "name": "张三", - "travelerType": "ADULT", - "travelerTypeLabel": "成人", - "idCardType": "ID_CARD", - "idCardTypeLabel": "身份证", - "idCardNo": "110101199001011234", - "gender": "1", - "birthday": "1990-01-01", - "phone": "13800000000", - "nationality": "中国", - "emergencyContact": "李四", - "emergencyPhone": "13900000000", - "email": "zhangsan@example.com" - } - ], - "success": true -} -``` - ---- - -## 2. 新增出行人 - -``` -POST /mp/order/{orderId}/traveler -``` - -**鉴权**:Bearer token。 -**自动解析**:`idCardType=ID_CARD` 时,后端根据 `idCardNo` 自动解析并回填 `birthday` + `gender`。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -Body `MpOrderTravelerSaveReqVO`: - -| 字段 | 类型 | 必填 | 约束 | 说明 | -|---|---|---|---|---| -| name | String | ✅ | ≤50 | 姓名 | -| idCardType | String | 否 | - | 证件类型,默认 `ID_CARD`;可选 `ID_CARD` / `PASSPORT` / `HK_MACAO_PASS` / `TAIWAN_PASS` / `OTHER` | -| idCardNo | String | ✅ | - | 证件号码 | -| phone | String | 否 | - | 手机号 | -| gender | String | 否 | - | `1`=男 / `2`=女(身份证时可省略,自动解析) | -| birthday | LocalDate | 否 | - | 出生日期(身份证时可省略,自动解析) | -| travelerType | String | 否 | - | 默认 `ADULT`;可选 `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | -| nationality | String | 否 | - | 国籍 | -| emergencyContact | String | 否 | - | 紧急联系人姓名 | -| emergencyPhone | String | 否 | - | 紧急联系人电话 | -| email | String | 否 | - | 邮箱 | - -### 请求示例 - -```json -{ - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "110101199001011234", - "phone": "13800000000", - "travelerType": "ADULT", - "nationality": "中国", - "emergencyContact": "李四", - "emergencyPhone": "13900000000", - "email": "zhangsan@example.com" -} -``` - -### 出参 - -`Result<MpOrderTravelerVO>` — 新创建的出行人,结构同第 1 节。`birthday` 和 `gender` 已由后端回填。 - ---- - -## 3. 修改出行人 - -``` -PUT /mp/order/{orderId}/traveler/{travelerId} -``` - -**鉴权**:Bearer token。 -**字段语义**:**null 保持原值**,只传需要修改的字段即可(部分更新)。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | -| travelerId | Path | Long | ✅ | - -Body:`MpOrderTravelerSaveReqVO`(同第 2 节,但各字段均可为 null 表示不改)。 - -### 出参 - -`Result<MpOrderTravelerVO>` — 修改后的完整信息。 - ---- - -## 4. 删除出行人 - -``` -DELETE /mp/order/{orderId}/traveler/{travelerId} -``` - -**鉴权**:Bearer token。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | -| travelerId | Path | Long | ✅ | - -### 出参 - -`Result<Void>`: - -```json -{ "code": 200, "message": "成功", "data": null, "success": true } -``` - ---- - -## 边界行为 - -- 订单不存在 / 不属于当前用户:500,`message` 含 `orderId` -- 出行人不存在 / 不属于该订单:500,`message` 含 `travelerId` -- `idCardType=ID_CARD` 时 `idCardNo` 格式不合法:400,`message` 含错误原因 -- 删除出行人时,若该出行人已被某到达批次关联,批次绑定同步软删(不会阻断删除) -- 订单状态为 `CANCELLED` / `REFUNDED` 时禁止修改/新增/删除 - ---- - -## 字典依赖 - -| 字典类型 | 可选值 | -|---|---| -| `traveler_type` | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | -| `id_card_type` | `ID_CARD` / `PASSPORT` / `HK_MACAO_PASS` / `TAIWAN_PASS` / `OTHER` | - -所有 `xxxLabel` 字段由 BFF 透传自 order-v2,已经是中文展示值。 diff --git a/changelogs/2026-04/2026-04-21_mp-product-route-map.md b/changelogs/2026-04/2026-04-21_mp-product-route-map.md deleted file mode 100644 index f6bfb08..0000000 --- a/changelogs/2026-04/2026-04-21_mp-product-route-map.md +++ /dev/null @@ -1,218 +0,0 @@ -# 小程序行程路线图接口 - `/mp/product/{productId}/route-map` - -- **日期**: 2026-04-21 -- **PR**: [#1098](https://git.1814.love:8443/wx/HL/pulls/1098) (Closes #1093) + 增量修复 [#1106](https://git.1814.love:8443/wx/HL/pulls/1106) (Closes #1104) -- **类型**: FEATURE（新增接口，免登录） -- **服务**: hl-product-service-v2（路由 `/mp/product/**`） -- **前端是否需要改动**: **是**（需新增接口调用 + 地图展示） - -> ⚠️ **2026-04-21 增量修复（PR #1106）**：上线初期前端反馈 `origin`/`destination` 全部为空，根因是真实 `gather_place`/`dismissal_place` JSON 来自高德行政区 picker，只有 adcode 没有 `center` 字段。修复后通过 adcode 调高德 `/v3/config/district` 拿区县中心坐标（Redis 缓存 30 天）。**接口契约不变**，前端无需调整。 - ---- - -## 一、背景 - -小程序需要按产品 ID 拉取每天的「路线图」用于地图展示，所有节点必须带经纬度。无需登录（路线图是基础地理信息，浏览阶段即可看到）。 - ---- - -## 二、接口 - -| # | 方法 | 路径 | 鉴权 | -|---|------|------|------| -| 1 | GET | `/mp/product/{productId}/route-map` | 免登录（白名单） | - -**Path 参数** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `productId` | Long (字符串) | 是 | 产品 ID | - -**无 Query/Body 参数**。 - ---- - -## 三、响应结构 - -### 顶层 `data: MpProductRouteMapVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `title` | String | 产品标题 | -| `days` | `MpProductRouteDayVO[]` | 每天的路线图，按 dayNumber 升序 | - -### `MpProductRouteDayVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `dayNumber` | Integer | 第几天，从 1 开始 | -| `title` | String | 当天标题（如 "D1 成都-四姑娘山"） | -| `color` | String / null | 当天主题色（后端不返回，固定 `null`，前端用调色板兜底） | -| `origin` | `MpRoutePointVO` / null | 当天起点；缺数据时为 null | -| `destination` | `MpRoutePointVO` / null | 当天终点；缺数据时为 null | -| `waypoints` | `MpRoutePointVO[]` | 当天途经点（按 sort_order 升序），可能空数组 | -| `scenicSpots` | `MpRouteScenicVO[]` | 当天景点（含封面图），可能空数组 | - -### `MpRoutePointVO`（起点 / 终点 / 途经点） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `lng` | Number | 经度 | -| `lat` | Number | 纬度 | -| `name` | String | 名称 | - -### `MpRouteScenicVO`（景点） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `lng` | Number | 经度 | -| `lat` | Number | 纬度 | -| `name` | String | 名称 | -| `coverUrl` | String / null | 封面图完整 URL，缺失为 null | - ---- - -## 四、业务规则 - -- **起终点**：优先取行程当天「集合地 / 解散地」JSON 字段；若缺失，回退到该天 `product_route_point` 首/末 -- **途经点**：取该天 `product_route_point` 全量按 `sort_order` 升序 -- **景点**：取该天行程节点中 `nodeType ∈ {SCENIC, ACTIVITY}` 的资源，经纬度 + 封面图来自资源服务（景点表 / 活动表） -- **经纬度缺失节点直接过滤**（不会返回 `lng=0/lat=0` 或 `null` 坐标）—— 前端拿到的所有点都保证有有效坐标 -- **未上架 / 已下架 / 不存在产品** → 业务码 `code=404, message="产品不存在或已下架"`（与现有 `/mp/product/{id}` 详情接口对齐） -- **景点封面图加载失败**（资源服务异常）：景点列表降级为空数组，路线骨架仍正常返回（不阻断主流程） - ---- - -## 五、响应示例 - -### PUBLISHED 产品（部分天有数据 + 部分天缺数据） - -```json -{ - "code": 200, - "success": true, - "data": { - "title": "川西亲子研学5日游（升级版）", - "days": [ - { - "dayNumber": 1, - "title": "抵达成都", - "color": null, - "origin": { "lng": 103.947086, "lat": 30.578528, "name": "成都双流机场" }, - "destination": { "lng": 104.061902, "lat": 30.673933, "name": "宽窄巷子" }, - "waypoints": [ - { "lng": 104.061902, "lat": 30.673933, "name": "宽窄巷子" } - ], - "scenicSpots": [] - }, - { - "dayNumber": 2, - "title": "成都-四姑娘山", - "color": null, - "origin": { "lng": 104.066301, "lat": 30.572961, "name": "成都" }, - "destination": { "lng": 102.8987, "lat": 31.0827, "name": "四姑娘山" }, - "waypoints": [ - { "lng": 102.8987, "lat": 31.0827, "name": "四姑娘山" } - ], - "scenicSpots": [] - }, - { - "dayNumber": 3, - "title": "四姑娘山-丹巴", - "color": null, - "origin": null, - "destination": null, - "waypoints": [], - "scenicSpots": [] - } - ] - } -} -``` - -### 未上架 / 已下架 / 不存在 - -```json -{ - "code": 404, - "success": false, - "message": "产品不存在或已下架", - "data": null -} -``` - ---- - -## 六、前端使用建议 - -### 调用示例 - -```ts -const res = await wx.request({ - url: `https://api.test.1814.love:9443/mp/product/${productId}/route-map`, - method: 'GET' - // 不需要带 Authorization header -}); - -if (res.data.code !== 200) { - // 已下架 / 不存在 - return; -} - -const { title, days } = res.data.data; -``` - -### 渲染地图（高德/腾讯地图，伪代码） - -```ts -const palette = ['#4285F4', '#EA4335', '#FBBC04', '#34A853', '#9C27B0']; - -days.forEach((day, idx) => { - const color = day.color || palette[idx % palette.length]; - - // 折线：origin → waypoints → destination - const polylinePoints = [ - day.origin, - ...day.waypoints, - day.destination - ].filter(Boolean); // 缺失的点跳过 - - drawPolyline(polylinePoints, color); - - // 景点 marker - day.scenicSpots.forEach(spot => { - drawMarker(spot, { icon: spot.coverUrl, label: spot.name }); - }); -}); -``` - -### ⚠️ 注意 - -- **所有节点都保证有 lng/lat**，前端无需再判空坐标 -- **`origin` / `destination` 可能为 null**（当天数据不全），渲染折线时要过滤 -- **`color` 后端固定返回 null**，前端按 dayNumber index 取调色板色 -- **`scenicSpots[].coverUrl` 可能为 null**（景点未配封面），需有兜底图 -- **`waypoints` / `scenicSpots` 可能空数组** - ---- - -## 七、不兼容变更 - -**无**。新增接口，与既有接口无交集。 - ---- - -## 八、回归验证 - -```bash -# PUBLISHED 产品 -curl -sk "https://api.test.1814.love:9443/mp/product/2044803580070703106/route-map" | jq . - -# DRAFT 产品（应返回 404 业务码） -curl -sk "https://api.test.1814.love:9443/mp/product/2045018534152478721/route-map" | jq . -``` - -**预期**： - -- PUBLISHED：`code=200`，`data.title` 非空，`data.days[]` 非空，每个有数据的 day 节点都带有效 lng/lat -- DRAFT：`code=404, message="产品不存在或已下架"` diff --git a/changelogs/2026-04/2026-04-21_mp-quote-early-bird.md b/changelogs/2026-04/2026-04-21_mp-quote-early-bird.md deleted file mode 100644 index 4d9511f..0000000 --- a/changelogs/2026-04/2026-04-21_mp-quote-early-bird.md +++ /dev/null @@ -1,192 +0,0 @@ -# 小程序产品报价 - `/mp/product/{id}/quote` 接口补早鸟优惠字段 - -- **日期**: 2026-04-21 -- **PR**: [#1052](https://git.1814.love:8443/wx/HL/pulls/1052) (Closes #1047) -- **类型**: FEATURE（响应 VO 新增字段，向前兼容） -- **服务**: hl-product-service-v2（路由 `/mp/product/**`） -- **前端是否需要改动**: **建议改动**（展示早鸟优惠金额 + 最终应付金额给用户） - ---- - -## 一、背景 - -之前的报价接口只返回「原价合计」与「原尾款/定金」，但订单创建时后端会**自动扣早鸟优惠**（`OrderCreateService.tryApplyEarlyBirdDiscount()`），导致： - -- 小程序报价页显示 `￥10,510` 尾款 -- 用户提交订单实付却是 `￥10,410`（已扣 100 元早鸟） -- 用户困惑 / 客服被投诉报价不准 - -本次修复让报价接口**同步返回早鸟优惠信息**，与订单实扣完全一致。 - ---- - -## 二、变更接口 - -| # | 方法 | 路径 | 变更类型 | -|---|------|------|---------| -| 1 | POST | `/mp/product/{id}/quote` | 响应 VO 新增 5 个字段；请求参数不变 | - ---- - -## 三、响应 VO 新增字段（`MpQuoteResultVO`） - -| 字段 | 类型 | 含义 | 示例 | -|------|------|------|------| -| `earlyBirdDiscount` | BigDecimal | 早鸟优惠金额（未命中为 0） | `100.00` | -| `earlyBirdPlanId` | Long (字符串) | 命中的早鸟计划 ID（未命中为 null） | `"2046080027564318721"` | -| `earlyBirdPlanName` | String | 命中的早鸟计划名称（展示用，未命中为 null） | `"暑期早鸟"` | -| `finalBalanceAmount` | BigDecimal | **定金模式**下最终应付尾款 = `balanceAmount - earlyBirdDiscount`；全款模式为 `null` | `10410.00` | -| `finalGrandTotal` | BigDecimal | 最终应付总价 = `grandTotal - earlyBirdDiscount` | `11410.00` | - -**其它字段不变**：`grandTotal` / `balanceAmount` / `depositAmount` 仍是「原始价」，仅新增的 `finalXxx` 是「扣优惠后最终应付」。 - ---- - -## 四、业务规则（与订单实扣对齐） - -- 早鸟优惠**按下单日期**生效（调用报价的当下，等于订单创建时的日期） -- **定金模式 (DEPOSIT)**：定金**原价收**，早鸟优惠**从尾款扣** - - `finalBalanceAmount = balanceAmount - earlyBirdDiscount` - - `finalGrandTotal = grandTotal - earlyBirdDiscount`（整单一致） -- **全款模式 (FULL)**：早鸟优惠**从全款扣** - - `finalBalanceAmount = null` - - `finalGrandTotal = grandTotal - earlyBirdDiscount` -- **未命中 / 查询失败** → `earlyBirdDiscount = 0`，`earlyBirdPlanId = null`，`finalXxx = 原值` -- **人数门槛**：总人数（成人 + 儿童 + 小童 + 幼童）< 计划 `minPeople` → 不命中 -- **金额封顶**：早鸟优惠 ≤ 对应金额池（定金模式下不超过尾款；全款模式下不超过总价），不会让尾款 / 全款为负 - ---- - -## 五、响应示例 - -### 定金模式 + 命中早鸟（2 成人） - -```json -{ - "code": 200, - "success": true, - "data": { - "adultUnitPrice": 5755.00, - "totalAdultPrice": 11510.00, - "grandTotal": 11510.00, - "paymentType": "DEPOSIT", - "depositAmount": 1000.00, - "balanceAmount": 10510.00, - - "earlyBirdDiscount": 100.00, - "earlyBirdPlanId": "2046080027564318721", - "earlyBirdPlanName": "BUG20测试-2人", - "finalBalanceAmount": 10410.00, - "finalGrandTotal": 11410.00 - } -} -``` - -### 全款模式 + 命中早鸟 - -```json -{ - "data": { - "grandTotal": 8000.00, - "paymentType": "FULL", - "balanceAmount": null, - - "earlyBirdDiscount": 500.00, - "earlyBirdPlanId": "1234567890", - "earlyBirdPlanName": "全款早鸟", - "finalBalanceAmount": null, - "finalGrandTotal": 7500.00 - } -} -``` - -### 未命中早鸟 - -```json -{ - "data": { - "grandTotal": 5000.00, - "balanceAmount": 4000.00, - - "earlyBirdDiscount": 0, - "earlyBirdPlanId": null, - "earlyBirdPlanName": null, - "finalBalanceAmount": 4000.00, - "finalGrandTotal": 5000.00 - } -} -``` - ---- - -## 六、前端使用建议 - -### 场景 A：报价页展示早鸟优惠 - -```tsx -{data.earlyBirdDiscount > 0 && ( - <View className="discount-row"> - <Text>早鸟优惠 {data.earlyBirdPlanName}</Text> - <Text>-¥{data.earlyBirdDiscount}</Text> - </View> -)} -``` - -### 场景 B：定金模式下拆分展示 - -```tsx -<View>订金（立付）：¥{data.depositAmount}</View> - -{data.earlyBirdDiscount > 0 ? ( - <> - <View className="original">原尾款：<s>¥{data.balanceAmount}</s></View> - <View className="final">最终尾款：<b>¥{data.finalBalanceAmount}</b></View> - </> -) : ( - <View>尾款：¥{data.balanceAmount}</View> -)} -``` - -### 场景 C：全款模式下拆分展示 - -```tsx -{data.paymentType === 'FULL' && data.earlyBirdDiscount > 0 ? ( - <> - <View>原价：<s>¥{data.grandTotal}</s></View> - <View className="final">最终应付：<b>¥{data.finalGrandTotal}</b></View> - </> -) : ( - <View>应付：¥{data.grandTotal}</View> -)} -``` - -### ⚠️ 注意 - -- `earlyBirdPlanId` 是 Long，JSON 序列化为**字符串**防精度丢失（与项目其它 ID 字段一致） -- 未命中早鸟时 `finalBalanceAmount` / `finalGrandTotal` **等于**原值，可以无脑展示 `finalXxx`（无需判断） -- `earlyBirdDiscount` 一定是 `BigDecimal` 形式的数字（`0` 或 `>0`），不会是 null -- **全款模式**下 `finalBalanceAmount` 固定为 `null`（与 `balanceAmount` 语义保持一致） - ---- - -## 七、不兼容变更 - -**无**。仅响应 VO 新增字段，既有字段语义与取值完全不变。旧客户端（没更新适配的）继续按原逻辑渲染，只是看不到早鸟优惠而已。 - ---- - -## 八、回归验证 - -```bash -# 测试产品（班期内有早鸟"BUG20测试-2人"） -curl -sk -X POST "https://api.test.1814.love:9443/mp/product/2044603865881333762/quote" \ - -H "Content-Type: application/json" \ - -d '{"departureDate":"2026-05-10","adultCount":2,"childCount":0,"tierSeq":1}' | jq .data -``` - -**预期**： - -- `earlyBirdDiscount: 100.00` -- `earlyBirdPlanName: "BUG20测试-2人"` -- `finalBalanceAmount = balanceAmount - 100` -- `finalGrandTotal = grandTotal - 100` diff --git a/changelogs/2026-04/2026-04-21_mp-review-filter-tags-product-category.md b/changelogs/2026-04/2026-04-21_mp-review-filter-tags-product-category.md deleted file mode 100644 index 672a7e8..0000000 --- a/changelogs/2026-04/2026-04-21_mp-review-filter-tags-product-category.md +++ /dev/null @@ -1,85 +0,0 @@ -# 小程序评价筛选条件接口 + 小蒙马详情补产品分类 - -**日期**：2026-04-21 -**PR**：#1070（Closes #1069） -**影响**：小程序评价列表页筛选栏、小程序小蒙马产品详情页 - ---- - -## 为什么变 - -1. **评价筛选条件前端硬编码**：小程序评价列表页顶部筛选标签栏（全部/有图/关键词标签）之前前端硬编码，无法跟字典联动；字典 `review_keyword_tag` 9 项标签维护在后台，前端看不到新增/下线。 -2. **小蒙马详情 `category` 字段漏返回**：管理端给 GROUP 产品选分类（亲子游/蜜月/摄影 等 字典 `product_category`），但小程序详情接口前期反馈 `category` 未返回。排查后端代码链路齐全（Entity/VO/Assembler 都有字段），根因最可能是测试环境 jar 旧。此次合并 + 部署已让 `category` 稳定返回，同时在 Assembler 补一行显式 `setCategory` 兜底 Hutool BeanUtil 潜在边界。 - ---- - -## 接口契约变化 - -### 1. 新增 `GET /mp/review/filter-tags`（评价筛选条件） - -**鉴权**：需要 Bearer token（登录 mp 用户）。 - -**返回结构**： - -```json -{ - "code": 200, - "message": "成功", - "data": { - "fixedFilters": [ - {"key": "all", "label": "全部"}, - {"key": "hasImage", "label": "有图"} - ], - "tagFilters": [ - {"key": "QUIET_PRIVATE", "label": "安静私密"}, - {"key": "KIDS_LOVE_IT", "label": "孩子玩疯了"}, - {"key": "BUTLER_CARING", "label": "管家贴心"}, - {"key": "HIGHLY_RECOMMEND", "label": "强烈推荐"}, - {"key": "SCENIC_BEAUTY", "label": "风景绝美"}, - {"key": "COMFY_STAY", "label": "住宿舒适"}, - {"key": "GOOD_FOOD", "label": "餐饮丰富"}, - {"key": "NICE_DRIVER", "label": "司机友善"}, - {"key": "GOOD_ITINERARY", "label": "行程合理"} - ] - }, - "success": true -} -``` - -**字段说明**： -- `fixedFilters`：固定筛选器（前端跟据 `key` 做列表参数传递） - - `all` → 不加筛选 - - `hasImage` → 调 `GET /mp/review/target?hasImage=true` -- `tagFilters[].key`：字典 `review_keyword_tag` 的 `dictValue` -- `tagFilters[].label`：字典 `review_keyword_tag` 的 `dictLabel`（直接用于展示） - -**缓存**：Redis 侧 `mp:review:filter-tags` 键 30 分钟 TTL，字典变更后台修改会触发 MpCache 自动失效，前端无需做本地缓存管理。 - -**建议用法**： -- 小程序进入评价列表页时调一次，把返回的 `fixedFilters` + `tagFilters` 合并渲染成筛选 tab 栏 -- 用户点 tag 后，用 `tagFilters[].key` 作为筛选参数传递给列表接口（**注意**：当前 `/mp/review/target` 还不支持按 tag 筛选评价，仅支持 `ratingLevel`/`hasImage`/`hasVideo`，tag 筛选需后端后续补。本期仅完成筛选条件接口部分） - -### 2. `GET /mp/product/{id}` 的 `category` 字段（强化稳定性） - -**无接口签名变化**。`MpProductDetailRespVO.category` 字段早已存在，但此前偶发未返回。本次部署后： - -- GROUP 产品 `category` 稳定返回，取值为字典 `product_category` 的 `dictValue` -- 可能值：`family` / `honeymoon` / `photography` / `experience` / `driving` -- 前端若需展示中文（亲子游 / 蜜月旅行 / 摄影之旅 / 深度体验 / 自驾越野），拿 `category` 作为 dictValue 查字典 `product_category` 即可 - ---- - -## 验证结果（测试环境 2026-04-21 11:37） - -| 接口 | 结果 | -|---|---| -| `GET /mp/review/filter-tags` | 200，返回 2 个固定筛选器 + 9 个字典标签筛选器 | -| Redis `mp:review:filter-tags` TTL | 1768s（接近 1800s 缓存正常） | -| `GET /mp/product/2044306857534636034`（PUBLISHED GROUP） | 200，`productType="GROUP"`，`category="family"` | - ---- - -## 前端改动建议 - -- [ ] 评价列表页初始化时调 `GET /mp/review/filter-tags`，渲染 filter tabs（合并 fixedFilters + tagFilters） -- [ ] 小蒙马详情页按字典 `product_category` 把 `category` code 转中文 label 展示 diff --git a/changelogs/2026-04/2026-04-21_mp-travel-memory.md b/changelogs/2026-04/2026-04-21_mp-travel-memory.md deleted file mode 100644 index 0e13064..0000000 --- a/changelogs/2026-04/2026-04-21_mp-travel-memory.md +++ /dev/null @@ -1,134 +0,0 @@ -# 微信小程序 · 我的旅行回忆接口 - -**日期**:2026-04-21 -**影响**:**微信小程序** 行程 Tab·回头客态(原型 `wwWKT` 旅行回忆卡片墙) -**PR**:#1004(Closes #1002)· #1014(Closes #1011) - ---- - -## 概述 - -返回用户已完成订单(`status=COMPLETED`)分页列表,按 `departure_date DESC, order_id DESC` 排序。响应中已含评分信息,一次调用拿到订单+评分完整数据。 - ---- - -## 接口 - -``` -GET /mp/order/travel-memory -``` - -**鉴权**:Bearer token(登录态)。`userId` 由后端从 token 取,前端不传。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | 默认 | 约束 | 说明 | -|---|---|---|---|---|---|---| -| page | Query | Integer | 否 | 1 | ≥1 | 页码 | -| pageSize | Query | Integer | 否 | 20 | 1~100 | 每页条数 | - -### 请求示例 - -``` -GET /mp/order/travel-memory?page=1&pageSize=10 -``` - ---- - -### 出参 `Result<PageResult<MpTravelMemoryVO>>` - -**`PageResult`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| records | `List<MpTravelMemoryVO>` | 当前页数据 | -| total | Integer | 总记录数 | -| page | Integer | 当前页码 | -| pageSize | Integer | 每页条数 | - -**`MpTravelMemoryVO`**: -| 字段 | 类型 | 必有 | 说明 | -|---|---|---|---| -| orderId | Long | ✅ | 订单ID | -| productName | String | ✅ | 产品名(订单快照) | -| productCoverUrl | String | 否 | 产品封面图 URL | -| departureDate | LocalDate | ✅ | 出发日期,`yyyy-MM-dd` | -| returnDate | LocalDate | 否 | 返程日期,`yyyy-MM-dd`(按 `departureDate + tripDays - 1` 推导) | -| tripDays | Integer | 否 | 行程天数 | -| tripNights | Integer | 否 | 行程晚数 | -| reviewed | Boolean | ✅ | 是否已评价(null 兜底为 false) | -| rating | Integer | 否 | 整体评分 1-5;**未评价或评价服务降级时为 null** | -| reviewId | Long | 否 | 评价ID;**未评价或评价服务降级时为 null** | - -### 响应示例(已评价 + 未评价混合) - -```json -{ - "code": 200, - "message": "操作成功", - "data": { - "records": [ - { - "orderId": 2043935542092980226, - "productName": "草原环线·舒适套餐", - "productCoverUrl": "https://cdn.1814.love/product/cover/xxxx.png", - "departureDate": "2026-07-01", - "returnDate": "2026-07-06", - "tripDays": 6, - "tripNights": 5, - "reviewed": true, - "rating": 5, - "reviewId": 6001 - }, - { - "orderId": 2043935542092980211, - "productName": "呼伦贝尔深度游·豪华版", - "productCoverUrl": "https://cdn.1814.love/product/cover/yyyy.png", - "departureDate": "2026-05-15", - "returnDate": "2026-05-20", - "tripDays": 6, - "tripNights": 5, - "reviewed": false, - "rating": null, - "reviewId": null - } - ], - "total": 2, - "page": 1, - "pageSize": 10 - } -} -``` - -### 响应示例(空数据) - -```json -{ - "code": 200, - "message": "操作成功", - "data": { - "records": [], - "total": 0, - "page": 1, - "pageSize": 10 - } -} -``` - ---- - -## 边界行为 - -- **未登录**:401(网关层拦截) -- **分页参数越界**(`page < 1` 或 `pageSize > 100`):400 -- **评价服务降级**:接口仍 200 返回订单数据,`rating` / `reviewId` 统一为 null -- **未完成订单**:不返回(仅 `status=COMPLETED` 进入列表) - ---- - -## 错误码 - -| code | 触发 | -|---|---| -| 200 | 正常(评价服务降级时 code 也是 200,rating/reviewId 为 null)| -| 400 | 分页参数越界 | -| 401 | token 无效 | diff --git a/changelogs/2026-04/2026-04-21_mp-trip-tab-state.md b/changelogs/2026-04/2026-04-21_mp-trip-tab-state.md deleted file mode 100644 index 2f13c85..0000000 --- a/changelogs/2026-04/2026-04-21_mp-trip-tab-state.md +++ /dev/null @@ -1,159 +0,0 @@ -# 微信小程序 · 行程 Tab 路由决策接口 - -**日期**:2026-04-21 -**影响**:**微信小程序** 行程 Tab 首屏(对应原型 `ew2Kk` 行程前 / `sGONt` 行程中 / `wwWKT` 回头客 / `eYDt9` 未下单空态) -**PR**:#1116(Closes #1115) - ---- - -## 概述 - -切到"行程" Tab 时一次调用获取应渲染的页面状态,返回 `state + orderId + summary`,替代之前依次调 today-dashboard + upcoming + travel-memory 3 个接口才能决策的流程。 - ---- - -## 接口 - -``` -GET /mp/trip/tab-state -``` - -**鉴权**:Bearer token。 - -### 入参 - -无(userId 由后端从 token 取)。 - -### 出参 `Result<MpTripTabStateVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| state | String | `IN_PROGRESS` / `BEFORE_START` / `RETURNING` / `NEW` | -| stateLabel | String | 中文:行程中 / 行程前 / 回头客 / 新客 | -| orderId | Long | IN_PROGRESS 或 BEFORE_START 时有值;其他为 null | -| summary | Summary | IN_PROGRESS 或 BEFORE_START 时有值;其他为 null | - -**`Summary`**: -| 字段 | 类型 | 说明 | -|---|---|---| -| productName | String | 产品名 | -| productSubtitle | String | 产品副标题 | -| tierName | String | 档位名称(未选档时 null)| -| departureDate | LocalDate | 出发日期 | -| daysToDeparture | Integer | 距出发天数(BEFORE_START 有值)| -| currentDayNumber | Integer | 当前第几天(IN_PROGRESS 有值)| -| tripDays | Integer | 行程天数 | - ---- - -## state 判定规则 - -按优先级从高到低判定,命中即返回: - -| 优先级 | state | 条件 | -|---|---|---| -| 1 | `IN_PROGRESS` | `status = TRAVELLING` | -| 2 | `BEFORE_START` | `status ∈ {DEPOSIT_PAID, PAID, CONFIRMED, PENDING_BALANCE, PENDING_DEPARTURE}` **且** `departure_date >= today` | -| 3 | `RETURNING` | 有 `status = COMPLETED` 订单 | -| 4 | `NEW` | 其他 | - -### 重要规则 - -- **`PENDING_PAY`(未支付)订单不计入 Tab 判定**。未支付订单由订单列表入口完成支付,不影响行程 Tab 的状态。 -- `CANCELLED` / `REFUNDING` / `REFUNDED` 不计入 Tab 判定。 -- 多订单时按优先级返回:同时有 COMPLETED + 未出发订单 → 返回 BEFORE_START(不是 RETURNING)。 - ---- - -## 响应示例 - -### 行程中 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "state": "IN_PROGRESS", - "stateLabel": "行程中", - "orderId": "2046501070522228737", - "summary": { - "productName": "草原环线", - "productSubtitle": "6天5晚舒适套餐", - "tierName": "舒适档", - "departureDate": "2026-07-01", - "daysToDeparture": null, - "currentDayNumber": 2, - "tripDays": 6 - } - }, - "success": true -} -``` - -### 行程前 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "state": "BEFORE_START", - "stateLabel": "行程前", - "orderId": "2046501070522228737", - "summary": { - "productName": "草原环线", - "productSubtitle": "6天5晚舒适套餐", - "tierName": "舒适档", - "departureDate": "2026-07-01", - "daysToDeparture": 12, - "currentDayNumber": null, - "tripDays": 6 - } - }, - "success": true -} -``` - -### 回头客 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "state": "RETURNING", - "stateLabel": "回头客", - "orderId": null, - "summary": null - }, - "success": true -} -``` - -### 新客(无任何有效订单) - -```json -{ - "code": 200, - "message": "成功", - "data": { - "state": "NEW", - "stateLabel": "新客", - "orderId": null, - "summary": null - }, - "success": true -} -``` - ---- - -## 边界行为 - -- **未登录**:401(网关拦截) -- **只有 PENDING_PAY 订单**:返回 `NEW`(未支付不计入) -- **只有 CANCELLED/REFUNDING/REFUNDED**:返回 `NEW` -- **多账号混合态**:优先级 IN_PROGRESS > BEFORE_START > RETURNING > NEW -- **服务降级**(Feign 失败):返回 `state=NEW`,接口不 500 -- **缓存**:15 秒短 TTL;订单表变化时依赖式失效 diff --git a/changelogs/2026-04/2026-04-21_mp-wiki-by-resource.md b/changelogs/2026-04/2026-04-21_mp-wiki-by-resource.md deleted file mode 100644 index e7c07fa..0000000 --- a/changelogs/2026-04/2026-04-21_mp-wiki-by-resource.md +++ /dev/null @@ -1,121 +0,0 @@ -# 微信小程序 · 按资源反查攻略接口 - -**日期**:2026-04-21 -**影响**:**微信小程序** 行程中·今日详情页景点/活动节点的"攻略"按钮(原型 `7wZKh.s2card`) -**PR**:#1122(Closes #1117) - ---- - -## 概述 - -按资源(景点/活动/酒店等)反查已关联的攻略文章列表。用于行程详情页节点旁的"攻略"按钮。 - -数据关联来自 `guide_article_resource` 表,管理端在编辑攻略时已能配置"该篇攻略关联哪些资源"。本接口做反向查询。 - ---- - -## 接口 - -``` -GET /mp/wiki/by-resource?resourceType=SCENIC&resourceId=2022992828971433985 -``` - -**鉴权**:Bearer token。 -**缓存**:5 分钟。 - -### 入参 - -| 参数 | 位置 | 类型 | 必填 | 说明 | -|---|---|---|---|---| -| resourceType | Query | String | ✅ | 资源类型;取值:`SCENIC` / `ACTIVITY` / `HOTEL` / `RESTAURANT` / `PRODUCT` | -| resourceId | Query | Long | ✅ | 资源主键 ID(景点ID / 活动ID 等) | - -### 出参 `Result<List<MpGuideArticleSimpleVO>>` - -按关联表 `sort_order` 升序;列表为空表示该资源无绑定攻略或均未发布。 - -**`MpGuideArticleSimpleVO`**: - -| 字段 | 类型 | 说明 | -|---|---|---| -| articleId | Long | 文章ID | -| categoryId | Long | 分类ID | -| categoryName | String | 分类中文名 | -| title | String | 标题 | -| coverUrl | String | 封面 URL | -| summary | String | 摘要 | -| viewCount | Integer | 浏览量 | -| publishTime | LocalDateTime | 发布时间 | - -### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "articleId": "2030823225496145921", - "categoryId": "2030822478645792769", - "categoryName": "景区攻略", - "title": "莫日格勒河游玩攻略:天下第一曲水的正确打开方式", - "coverUrl": "https://cdn.1814.love/guide/covers/mogelehe.png", - "summary": "莫日格勒河被誉为'天下第一曲水',蜿蜒流淌于呼伦贝尔大草原上。本攻略详细介绍最佳观景点、拍照机位、游览路线和注意事项。", - "viewCount": 0, - "publishTime": "2026-03-09 09:49:23" - } - ], - "success": true -} -``` - -### 空数据响应 - -```json -{ - "code": 200, - "data": [], - "success": true -} -``` - ---- - -## 边界行为 - -- 未登录:401(网关拦截) -- 资源无任何关联攻略:返 `[]` -- 关联攻略全部为草稿/已下架/已删除:返 `[]`(已过滤) -- 攻略服务降级:返 `[]`(不 500,不阻断页面) - ---- - -## 数据来源 - -### 关联表 `guide_article_resource` - -管理端在攻略文章编辑页配置资源关联(已有能力)。 - -### 后端查询逻辑 - -1. 按 `resource_type + resource_id` 从 `guide_article_resource` 拿 `article_id` 列表(按 `sort_order` 升序) -2. 按 `article_id` 批量查 `guide_article`,只返回 `status = PUBLISHED` 且未软删除的 -3. 按原 `sort_order` 顺序返回(同资源关联多篇时保留管理员设置的顺序) - -### 反查索引 - -本次 PR 顺带补 `KEY idx_resource (resource_type, resource_id)`,已通过 migration `V20260421__guide_article_resource_add_idx_resource.sql` 幂等升级。 - ---- - -## 字典参考 - -`resourceType` 对应后端枚举 `GuideConstants`: - -| 值 | 含义 | -|---|---| -| `SCENIC` | 景点 | -| `ACTIVITY` | 游玩项目/活动 | -| `HOTEL` | 酒店 | -| `RESTAURANT` | 餐厅 | -| `PRODUCT` | 产品 | diff --git a/changelogs/2026-04/2026-04-21_mp_today-dashboard-full-aggregation.md b/changelogs/2026-04/2026-04-21_mp_today-dashboard-full-aggregation.md deleted file mode 100644 index c37d72b..0000000 --- a/changelogs/2026-04/2026-04-21_mp_today-dashboard-full-aggregation.md +++ /dev/null @@ -1,146 +0,0 @@ -# 行程中今日页聚合接口扩展：DAY 导航 / 时间线 / 今晚住宿 / 明日预告 — 2026-04-21 - -> **服务** hl-mp-service（端口 8085）+ hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #1120 / PR #1124 -> **原型 Node IDs**：aufKi / NTzWR / JZcMi / 1ne4B / oVfPB / OwsOd（"行程中 · 当前行程"页） -> **依赖**：PR #1123（TripDetailVO 强类型化）、PR #1121（Hotel WiFi 字段，WiFi 数据视其落地情况） - ---- - -## 一、影响接口 - -### `GET /mp/trip/today-dashboard` — 行程中今日页聚合 - -既有字段 `today` / `leader` / `weather` / `sosContact` 保持不变，**新增 5 字段**。 - -## 二、新增字段 - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `todayProgressPercent` | `Integer` | 今日进度（0~100；无行程中订单时 null） | -| `dayNav` | `List<MpTripDayNavVO>` | DAY Tab 导航列表（原型 `dayNavV2`） | -| `todayTimeline` | `MpTodayTimelineVO` | 今日时间线（原型 `timelineV2`；无行程中订单时 null） | -| `todayHotel` | `MpTripHotelArrangementVO` | 今晚住宿（原型 `hotelSection` / `hotelCard`） | -| `tomorrow` | `MpTomorrowPreviewVO` | 明日预告（原型 `tmr`） | - -### `MpTripDayNavVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayNumber` | `Integer` | 第几天 | -| `date` | `LocalDate` | 日期 | -| `dayStatus` | `String` | `DONE` / `CURRENT` / `PENDING` | - -### `MpTodayTimelineVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `completed` | `List<MpTripItineraryNodeVO>` | 已完成节点（灰色简版行） | -| `current` | `MpTripItineraryNodeVO` | 当前节点（今日全部完成则为 null） | -| `next` | `MpTripItineraryNodeVO` | 下一节点（今日全部完成则为 null） | - -**节点状态推导规则**：按 `plannedTime` 升序排序，取第一个 `plannedTime >= 当前时间` 的节点为 `current`，前面为 `completed`，下一个为 `next`。 - -### `MpTripItineraryNodeVO`（时间线节点精简版） - -``` -nodeSeq, nodeType, nodeTypeLabel, title, subtitle, -plannedTime(HH:mm), durationMinutes, distanceKm -``` - -### `MpTripHotelArrangementVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayNumber` / `date` / `hotelId` / `hotelName` | — | 基本 | -| `checkInTime` / `checkOutTime` | `String` | `HH:mm` | -| `longitude` / `latitude` / `address` | — | 导航坐标 | -| `photoUrls` | `List<String>` | 酒店照片 | -| `rooms` | `List<MpTripHotelRoomVO>` | 房型（roomType / quantity / areaSqm / amenities） | -| `wifi` | `MpTripHotelWifiVO` | WiFi `{ ssid, password }`（酒店未录入时为 null） | -| `changedFromYesterday` | `Boolean` | 与前一晚 `hotelId` 不同时为 `true`（前端据此展示"已换酒店·带好行李"） | - -### `MpTomorrowPreviewVO` - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayNumber` | `Integer` | 明日 `DAY+1` | -| `routeSummary` | `String` | `"景点1 → 景点2 → 景点3"`（仅取 SCENIC/ACTIVITY 节点） | -| `distanceKm` | `Integer` | 明日总里程 | -| `plannedDepartureTime` | `String` | `HH:mm` | -| `reminderText` | `String` | 后端模板化 `"明早 {plannedDepartureTime} 出发，请提前收拾行李"` | - -## 三、联系领队补字段 - -### `MpGuideInfoVO` 新增 - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `plateNumber` | `String` | 领队随行车辆车牌号（取 `order_vehicle_assignment` 第一条；未分配为 null） | - -影响接口：`GET /mp/order/{orderId}/guide` + `GET /mp/trip/today-dashboard` 里的 `leader`。 - -## 四、空态行为 - -| 场景 | 行为 | -| --- | --- | -| 无行程中订单 | `today` / `leader` / `todayTimeline` / `todayHotel` / `tomorrow` 均为 null；`dayNav = []`；`todayProgressPercent = null`；`sosContact` 仍有客服电话 | -| 今天是最后一天 | `tomorrow = null` | -| 今晚无住宿 | `todayHotel = null` | -| 今日节点全部完成 | `todayTimeline.current` / `next` 为 null，`completed` 为全部节点 | -| 酒店未录入 WiFi | `todayHotel.wifi = null`（Issue #1121 落地后自动有值） | - -## 五、响应示例（部分） - -```json -{ - "code": 200, - "data": { - "today": { "...": "（保持不变）" }, - "leader": { - "staffId": 9001, "name": "巴图", - "phone": "138****5678", - "plateNumber": "蒙E·8A66", - "assigned": true - }, - "todayProgressPercent": 40, - "dayNav": [ - { "dayNumber": 1, "date": "2026-07-01", "dayStatus": "DONE" }, - { "dayNumber": 2, "date": "2026-07-02", "dayStatus": "CURRENT" }, - { "dayNumber": 3, "date": "2026-07-03", "dayStatus": "PENDING" } - ], - "todayTimeline": { - "completed": [ - { "nodeSeq": 1, "nodeType": "SCENIC", "title": "海拉尔出发", "plannedTime": "08:00" } - ], - "current": { - "nodeSeq": 2, "nodeType": "SCENIC", "title": "莫日格勒河", - "subtitle": "九曲十八弯", "plannedTime": "10:00", - "durationMinutes": 40, "distanceKm": 50 - }, - "next": { "nodeSeq": 3, "nodeType": "MEAL", "title": "蒙式午餐", "plannedTime": "12:00" } - }, - "todayHotel": { - "dayNumber": 2, "date": "2026-07-02", - "hotelId": 500002, "hotelName": "额尔古纳大酒店", - "checkInTime": "14:00", "checkOutTime": "12:00", - "rooms": [{ "roomType": "大床房", "quantity": 1 }], - "wifi": null, - "changedFromYesterday": true - }, - "tomorrow": { - "dayNumber": 3, - "routeSummary": "根河湿地 → 白桦林", - "distanceKm": 180, - "plannedDepartureTime": "08:00", - "reminderText": "明早 08:00 出发，请提前收拾行李" - } - } -} -``` - -## 六、关联 - -- Issue: [wx/HL#1120](https://git.1814.love:8443/wx/HL/issues/1120) -- PR: [wx/HL#1124](https://git.1814.love:8443/wx/HL/pulls/1124)（已合并到 dev） -- 前置：`2026-04-21_order-v2_trip-detail-vo-typed.md` -- 后续：`2026-04-21_resource_hotel-wifi-fields.md` diff --git a/changelogs/2026-04/2026-04-21_order-v2_admin-itinerary-summary.md b/changelogs/2026-04/2026-04-21_order-v2_admin-itinerary-summary.md deleted file mode 100644 index 2eaf6be..0000000 --- a/changelogs/2026-04/2026-04-21_order-v2_admin-itinerary-summary.md +++ /dev/null @@ -1,149 +0,0 @@ -# 管理端行程安排聚合接口 + 订单详情房间日期补全 — 2026-04-21 - -> **服务** hl-order-service-v2（端口 8094）· **类型** feat + fix · **关联** PR #1064 -> **使用场景**：管理端订单详情 · 行程安排 Tab · 查看场景一次性加载 -> **前端调用路径**：网关(8080) → hl-order-service-v2(8094) - ---- - -## 一、新增聚合接口 - -### 🆕 `GET /admin/order/{orderId}/itinerary/summary` — 行程安排聚合 - -**功能**：一次返回【行程安排】Tab 所需的 **房间 / 车辆 / 交通** 三段数据，替代前端分别调用 -`/hotel-assignment`、`/vehicle-assignment`、`/arrival` 的三次并发请求。 - -原三个接口**保留不动**，编辑场景仍各自调用；查看场景推荐走此聚合接口。 - -**请求参数**： - -| 参数 | 位置 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | --- | -| `orderId` | Path | `Long` | ✅ | 订单ID | - -**返回值** `Result<OrderItineraryRespVO>`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `hotelAssignments` | `List<HotelAssignmentDetailVO>` | 房间安排列表（字段同 `GET /hotel-assignment`，含 `assignmentDate` 现算值） | -| `vehicleAssignments` | `List<VehicleAssignmentVO>` | 车辆安排列表（字段同 `GET /vehicle-assignment`，司机电话脱敏） | -| `transports` | `ArrivalListRespVO` | 交通信息（字段同 `GET /arrival`，按 `ARRIVAL`/`DEPARTURE` 分组） | - -> 💡 `transports` 是 VO 包对象而非扁平 List，内部按到达/离开方向拆成 `arrivals` / `departures` 两个子列表，结构与 `GET /arrival` 一致，保留方向分组语义。 - -**`transports` 子结构**： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `orderId` | `Long` | 订单ID | -| `arrivals` | `List<ArrivalPlanRespVO>` | 到达批次（`direction=ARRIVAL`） | -| `departures` | `List<ArrivalPlanRespVO>` | 离开批次（`direction=DEPARTURE`） | - -**响应示例**： - -```json -{ - "code": 200, - "data": { - "orderId": 700001, - "hotelAssignments": [ - { - "assignmentId": 800001, - "orderId": 700001, - "familyIndex": 1, - "hotelId": 500001, - "hotelName": "香格里拉", - "roomTypeId": 500101, - "roomType": "大床房", - "dayNumber": 1, - "assignmentDate": "2026-07-01", - "upgradePrice": null, - "remark": null - } - ], - "vehicleAssignments": [ - { - "assignmentId": 900001, - "orderId": 700001, - "vehicleType": "丰田普拉多", - "vehicleCount": 1, - "plateNumber": "蒙A·A1234", - "driverName": "李师傅", - "driverPhone": "138****1234", - "remark": null, - "createTime": "2026-04-20 10:00:00" - } - ], - "transports": { - "orderId": 700001, - "arrivals": [ - { - "planId": 800001, - "orderId": 700001, - "direction": "ARRIVAL", - "directionLabel": "到达", - "transportType": "FLIGHT", - "transportTypeLabel": "飞机", - "transportNo": "CZ6255" - } - ], - "departures": [] - } - } -} -``` - -> 💡 三段子项**都带主键**：`hotelAssignments[].assignmentId` / `vehicleAssignments[].assignmentId` / `transports.arrivals[].planId`，从查看态进入编辑态的路径完全通畅。 - ---- - -## 二、现有接口字段修复 - -### 🐛 `GET /admin/order/{orderId}` — 订单详情 - -**修复**：`hotelAssignmentDetails[].assignmentDate` 之前返回 `null`（由于字段存储方式改为 `dayNumber`），现已由后端按 `order.departureDate + dayNumber - 1` 现算填充。 - -前端若此前已降级为展示 `-` 或基于 `dayNumber` 自行计算日期，可在本次迭代后恢复直接读取 `assignmentDate`。其他字段保持不变。 - ---- - -## 三、与已有接口关系 - -| 接口 | 作用 | 状态 | -| --- | --- | --- | -| `GET /admin/order/{orderId}/hotel-assignment` | 查酒店分配 | 已有（未变，仍可单独调） | -| `GET /admin/order/{orderId}/vehicle-assignment` | 查车辆分配 | 已有（未变，仍可单独调） | -| `GET /admin/order/{orderId}/arrival` | 查到达批次（按方向分组） | 已有（未变，仍可单独调） | -| `GET /admin/order/{orderId}/itinerary/summary` | 一次返回上述三段 | **本期新增** | - -聚合接口与三个独立接口**并存**： -- **查看态**：推荐走 `/itinerary/summary`，一次请求拿全。 -- **编辑态**：仍各自调子接口，减少无关数据传输。 - ---- - -## 四、数据库变更 - -**无**。纯服务层聚合，数据源均是既有表。 - ---- - -## 五、错误码 - -HTTP 始终返回 200，错误码在 `Result.code` 中。 - -| code | 触发 | 说明 | -| --- | --- | --- | -| 200 | 正常 | 成功（无分配数据返回空列表/空子对象） | -| 400 | 订单不存在 | `BusinessException` | - ---- - -## 六、关联 - -- PR: [wx/HL#1064](https://git.1814.love:8443/wx/HL/pulls/1064)（已合并到 dev） -- 相关接口： - - `GET /admin/order/{orderId}/hotel-assignment` · `GET /admin/order/{orderId}/vehicle-assignment` — 见 `2026-04-20_order-v2_admin-assignment-get.md` - - `GET /admin/order/{orderId}/arrival` — 见 `2026-04-20_order-v2_arrival.md`（C 端，管理端字段结构一致） - - `PUT /admin/order/{orderId}/hotel-assignment` `date → dayNumber` 破坏性变更 — 见 `2026-04-21_order-v2_hotel-assignment-day-number.md` diff --git a/changelogs/2026-04/2026-04-21_order-v2_admin-vehicle-assignment-count-removed.md b/changelogs/2026-04/2026-04-21_order-v2_admin-vehicle-assignment-count-removed.md deleted file mode 100644 index ab5fd37..0000000 --- a/changelogs/2026-04/2026-04-21_order-v2_admin-vehicle-assignment-count-removed.md +++ /dev/null @@ -1,73 +0,0 @@ -# 管理端配车接口下线 vehicleCount 字段 — 2026-04-21 - -> **服务** hl-order-service-v2（端口 8094）· **类型** refactor · **关联** Issue #1053 / PR #1054 -> **破坏性变更**：请求 body 字段 `vehicleCount` 删除，前端不再传，后端固定写 1 - ---- - -## 一、影响接口 - -### ✏️ `PUT /admin/order/{orderId}/vehicle-assignment` — 分配车辆（管理端） - -**请求参数变更**：`VehicleAssignmentReqVO` 移除 `vehicleCount` 字段。当前阶段每单车辆数固定为 1，后端直接写入，前端无需传递。 - -**变更对比**： - -| 字段 | 状态 | 说明 | -| --- | --- | --- | -| ~~`vehicleCount`~~ | **已删除** | 前端传入将被忽略（JSON 未知字段不报错） | - -**保留字段**： - -| JSON 字段 | Java 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | --- | -| `vehicleModel` | `vehicleType` | `String` | ✅ ≤100 | 车型（`@JsonProperty("vehicleModel")` 对齐前端契约） | -| `plateNumber` | `plateNumber` | `String` | 否 ≤20 | 车牌号 | -| `driverName` | `driverName` | `String` | 否 ≤50 | 司机姓名 | -| `driverPhone` | `driverPhone` | `String` | 否 ≤20 | 司机电话 | -| `remark` | `remark` | `String` | 否 ≤500 | 备注 | - -**新请求示例**： - -```json -PUT /admin/order/700001/vehicle-assignment -{ - "vehicleModel": "商务车", - "plateNumber": "京A12345", - "driverName": "张三", - "driverPhone": "13800000000", - "remark": "" -} -``` - -**返回值** `Result<Void>`（`code=200` 即成功）。 - ---- - -### ℹ️ `GET /admin/order/{orderId}/vehicle-assignment` — 查车辆分配（未变） - -返回值 `VehicleAssignmentVO` 仍然包含 `vehicleCount` 字段（当前版本固定为 `1`），为后续多车扩展预留。 - ---- - -## 二、数据库变更 - -**无**。`order_vehicle_assignment` 表未改。 - ---- - -## 三、错误码 - -HTTP 始终返回 200，错误码在 `Result.code` 中。 - -| code | 触发 | 说明 | -| --- | --- | --- | -| 200 | 正常 | 成功 | -| 400 | `vehicleModel` 缺失/超长 | 参数校验失败 | - ---- - -## 四、关联 - -- Issue: [wx/HL#1053](https://git.1814.love:8443/wx/HL/issues/1053) -- PR: [wx/HL#1054](https://git.1814.love:8443/wx/HL/pulls/1054)（已合并到 dev） diff --git a/changelogs/2026-04/2026-04-21_order-v2_finance-dto-field-align.md b/changelogs/2026-04/2026-04-21_order-v2_finance-dto-field-align.md deleted file mode 100644 index 5ea1367..0000000 --- a/changelogs/2026-04/2026-04-21_order-v2_finance-dto-field-align.md +++ /dev/null @@ -1,108 +0,0 @@ -# 管理端优惠/附加费接口字段修复 — 2026-04-21 - -> **服务** hl-order-service-v2（端口 8094）· **类型** fix · **关联** Issue #1100 / PR #1101 -> **场景**：管理端订单详情 · 财务 Tab · 添加/修改 优惠项 / 费用增加项 - ---- - -## 一、问题现象 - -在管理端订单详情财务 Tab 的「添加优惠项」/「添加费用增加项」窗口中填入名称和金额后提交，接口返回： - -``` -name: 优惠名称不能为空; amount: 优惠金额不能为空 -``` - -## 二、根因 - -后端请求 DTO 的字段名与早期发布的接口契约不一致： - -| 接口 | 契约字段（前端用） | 之前后端 DTO | -| --- | --- | --- | -| `POST/PUT /admin/order/{orderId}/discount` | `discountName` / `discountAmount` | `name` / `amount` ❌ | -| `POST/PUT /admin/order/{orderId}/surcharge` | `surchargeName` / `surchargeAmount` | `name` / `amount` ❌ | - -前端按契约发请求 → 字段对不上 → `@NotBlank` / `@NotNull` 同时命中空值，一并报错。 - -## 三、修复内容 - -### 1. 字段名对齐契约 - -**`DiscountRequest`**： - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `discountName` | `String` | ✅ | 优惠名称 | -| `discountAmount` | `BigDecimal` | ✅ `>= 0.01` | 优惠金额（必须大于0） | - -**`SurchargeRequest`**： - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `surchargeName` | `String` | ✅ | 费用名称 | -| `surchargeAmount` | `BigDecimal` | ✅ `>= 0.01` | 费用金额（必须大于0） | - -### 2. 移除死字段 - -前端无需再传的字段，传了也会被忽略： - -- `DiscountRequest.discountType` — Service 强制写入 `MANUAL`，前端传值被丢弃 -- `DiscountRequest.remark` — Entity/DB 均无此列 -- `SurchargeRequest.remark` — Entity/DB 均无此列 - -### 3. 新增金额正数校验 - -| 校验 | 提示 | -| --- | --- | -| `discountAmount < 0.01` | `优惠金额必须大于0` | -| `surchargeAmount < 0.01` | `费用金额必须大于0` | - -防止负数优惠 = 变相加钱；负数附加费 = 变相减钱。 - ---- - -## 四、正确请求示例 - -```json -POST /admin/order/700001/discount -{ - "discountName": "老客户优惠", - "discountAmount": 100.00 -} -``` - -```json -POST /admin/order/700001/surcharge -{ - "surchargeName": "升级房型补差价", - "surchargeAmount": 200.00 -} -``` - -响应结构（`OrderDiscountVO` / `OrderSurchargeVO`）未变。 - ---- - -## 五、错误码 - -HTTP 始终返回 200，错误码在 `Result.code` 中。 - -| code | 触发 | 说明 | -| --- | --- | --- | -| 200 | 正常 | 成功 | -| 400 | 字段缺失 | `优惠名称不能为空` / `优惠金额不能为空` / `费用名称不能为空` / `费用金额不能为空` | -| 400 | 金额非正 | `优惠金额必须大于0` / `费用金额必须大于0` | - ---- - -## 六、前端影响 - -**无需改动**。前端本来就在按 `discountName`/`discountAmount`、`surchargeName`/`surchargeAmount` 发请求，本次修复让后端与契约一致，提交即可成功。 - ---- - -## 七、关联 - -- Issue: [wx/HL#1100](https://git.1814.love:8443/wx/HL/issues/1100) -- PR: [wx/HL#1101](https://git.1814.love:8443/wx/HL/pulls/1101)（已合并到 dev） -- 原始契约：`2026-03-20_order_surcharge.md` diff --git a/changelogs/2026-04/2026-04-21_order-v2_hotel-assignment-day-number.md b/changelogs/2026-04/2026-04-21_order-v2_hotel-assignment-day-number.md deleted file mode 100644 index f2bc015..0000000 --- a/changelogs/2026-04/2026-04-21_order-v2_hotel-assignment-day-number.md +++ /dev/null @@ -1,113 +0,0 @@ -# 酒店分配接口 date → dayNumber — 2026-04-21 - -> **服务** hl-order-service-v2（端口 8094）· **类型** refactor · **关联** Issue #1049 / PR #1051 -> **破坏性变更**：请求入参字段名由 `date` 改为 `dayNumber` - ---- - -## 一、影响接口 - -### ✏️ `PUT /admin/order/{orderId}/hotel-assignment` — 分配酒店（管理端） - -**请求参数变更**：每个 `assignments[]` 元素的「日期字段」从 `date`（`LocalDate`）改为 `dayNumber`（`Integer`，第几天，从 1 开始）。 - -**变更对比**： - -| 旧字段 | 新字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | --- | -| ~~`date`~~ | **`dayNumber`** | `Integer` | ✅ | 第几天（从 1 开始，≥1） | - -**其他字段保持不变**：`familyIndex` · `hotelId` · `hotelName` · `roomTypeId` · `roomType` · `upgradePrice` · `remark` - -**新请求示例**： - -```json -PUT /admin/order/700001/hotel-assignment -{ - "assignments": [ - { - "familyIndex": 1, - "hotelId": 2023714929877450753, - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": 3002000000000000013, - "roomType": "大床房", - "dayNumber": 1, - "remark": "" - }, - { - "familyIndex": 1, - "hotelId": 2023714929877450753, - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": 3002000000000000013, - "roomType": "大床房", - "dayNumber": 2 - } - ] -} -``` - -> ⚠️ 真实入住日期由后端按 `order.departureDate + dayNumber - 1` 现算，前端传递时**不再需要知道订单出发日期**。 - ---- - -### ✏️ `GET /admin/order/{orderId}/hotel-assignment` — 查询酒店分配列表（管理端） - -**返回值字段变更**：新增 `dayNumber` 字段；`assignmentDate` 字段**保留**（Service 层按 `order.departureDate + dayNumber - 1` 现算填充，前端展示逻辑无需改）。 - -**`HotelAssignmentDetailVO` 字段**： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `assignmentId` | `Long` | 分配ID | -| `orderId` | `Long` | 订单ID | -| `familyIndex` | `Integer` | 家庭序号（从1开始） | -| `hotelId` | `Long` | 酒店ID | -| `hotelName` | `String` | 酒店名称 | -| `roomTypeId` | `Long` | 房型ID | -| `roomType` | `String` | 房型名称 | -| **`dayNumber`** | `Integer` | **新增**：第几天（从1开始） | -| `assignmentDate` | `LocalDate` | 入住日期（后端现算，保留） | -| `upgradePrice` | `BigDecimal` | 手动覆盖升级差价 | -| `remark` | `String` | 备注 | - ---- - -### ✏️ `GET /mp/order/{orderId}/hotels` — C 端订单住宿弹窗 - -`MpHotelItemVO` 同步新增 `dayNumber` 字段；`assignmentDate` 保留（后端现算）。 - ---- - -## 二、数据库变更 - -**已在测试服执行**（本 changelog 生成时）： - -```sql -ALTER TABLE order_hotel_assignment - ADD COLUMN day_number INT NOT NULL COMMENT '第几天(从1开始,与meal/scenic assignment一致)' AFTER room_type; -ALTER TABLE order_hotel_assignment DROP COLUMN assignment_date; -``` - -历史数据按 `DATEDIFF(assignment_date, order.departure_date) + 1` 回填。 - -> 生产部署顺序必须 **先跑迁移 SQL 再重启服务**，否则老代码写入会因 `assignment_date` 列缺失而失败。 - ---- - -## 三、错误码 - -HTTP 始终返回 200，错误码在 `Result.code` 中。 - -| code | 触发 | 说明 | -| --- | --- | --- | -| 200 | 正常 | 成功 | -| 400 | `dayNumber` 缺失 | `第几天不能为空` | -| 400 | `dayNumber < 1` | `第几天必须大于等于1` | - ---- - -## 四、关联 - -- Issue: [wx/HL#1049](https://git.1814.love:8443/wx/HL/issues/1049) -- PR: [wx/HL#1051](https://git.1814.love:8443/wx/HL/pulls/1051)（已合并到 dev） -- 前置原因：原 `assignment_date` 在订单出发日变更时需要级联更新，且与 `order_meal_assignment` / `order_scenic_assignment` 的 `day_number` 字段设计不一致 diff --git a/changelogs/2026-04/2026-04-21_order-v2_trip-detail-vo-typed.md b/changelogs/2026-04/2026-04-21_order-v2_trip-detail-vo-typed.md deleted file mode 100644 index 672c470..0000000 --- a/changelogs/2026-04/2026-04-21_order-v2_trip-detail-vo-typed.md +++ /dev/null @@ -1,88 +0,0 @@ -# 行程详情接口 itineraryDays / dailyItinerary / hotelArrangements 三字段强类型化 — 2026-04-21 - -> **服务** hl-order-service-v2（端口 8094）· **类型** refactor · **关联** Issue #1119 / PR #1123 -> **破坏性程度**：JSON 结构完全不变，**前端只需升级 TypeScript 类型定义** - ---- - -## 一、影响接口 - -所有返回 `TripDetailVO` 的接口（三字段类型变更，字段名和 JSON 路径保持一致）： - -- `GET /admin/order/{orderId}/trip` — 管理端行程详情 -- `GET /mp/trip/{orderId}` — 小程序行程详情（BFF 透传） -- `GET /mp/trip/today` — 小程序今日行程（BFF 透传） - -## 二、字段类型变更 - -| 字段 | 旧类型 | 新类型 | -| --- | --- | --- | -| `itineraryDays` | `List<Map<String, Object>>` | `List<TripItineraryDayVO>`（按 `dayNumber` 升序） | -| `dailyItinerary` | `List<Map<String, Object>>` | `List<TripItineraryNodeVO>`（所有天节点扁平拼接） | -| `hotelArrangements` | `List<Map<String, Object>>` | `List<TripHotelArrangementVO>`（按 `hotelId` 合并同家酒店多房型） | - -## 三、新强类型结构 - -### `TripItineraryDayVO`（每日行程） - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayNumber` | `Integer` | 第几天（从 1 开始） | -| `date` | `LocalDate` | 当天日期 | -| `weekday` | `String` | 星期中文（如 "周三"） | -| `dayTitle` | `String` | 当日主题 | -| `scenicCount` | `Integer` | 当日景点数（已排除 SKIPPED 节点） | -| `dayDistanceKm` | `Integer` | 当日总里程（km） | -| `nodes` | `List<TripItineraryNodeVO>` | 节点时间线 | -| `hotels` | `List<TripHotelArrangementVO>` | 当晚酒店（无则为空列表） | - -### `TripItineraryNodeVO`（时间线节点） - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `nodeSeq` | `Integer` | 当天第几站（从 1 开始） | -| `nodeType` | `String` | `SCENIC` / `MEAL` / `HOTEL` / `TRANSPORT` / `ACTIVITY` / `GATHER` / `DISMISS` | -| `nodeTypeLabel` | `String` | 中文标签 | -| `title` | `String` | 节点标题 | -| `subtitle` | `String` | 副标题 / 描述 | -| `plannedTime` | `String` | 计划时间 `HH:mm` | -| `durationMinutes` | `Integer` | 至下一节点车程（分钟） | -| `distanceKm` | `Integer` | 至下一节点距离（km） | -| `editStatus` | `String` | `ADDED` / `REPLACED` / `MODIFIED` / `SKIPPED`；null=未改动 | -| `resourceId` | `Long` | 关联资源主键 | -| `resourceType` | `String` | 对齐 nodeType | - -### `TripHotelArrangementVO`（每晚酒店） - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `dayNumber` | `Integer` | 对应第几天 | -| `date` | `LocalDate` | 入住日期 | -| `hotelId` | `Long` | 酒店ID | -| `hotelName` | `String` | 酒店名称 | -| `checkInTime` | `String` | 入住时间 `HH:mm` | -| `checkOutTime` | `String` | 退房时间 `HH:mm` | -| `longitude` / `latitude` | `BigDecimal` | 坐标（导航用） | -| `address` | `String` | 地址 | -| `photoUrls` | `List<String>` | 酒店照片 | -| `rooms` | `List<TripHotelRoomVO>` | 房型列表 | -| `wifi` | `TripHotelWifiVO` | WiFi（酒店未录入时为 null） | -| `changedFromYesterday` | `Boolean` | 与前一晚不是同一家酒店 | - -### `TripHotelRoomVO` / `TripHotelWifiVO` - -``` -TripHotelRoomVO { roomType, quantity, areaSqm, amenities: List<String> } -TripHotelWifiVO { ssid, password } -``` - -## 四、兼容性 - -- **JSON 结构完全不变**：字段名、嵌套路径、值类型在 JSON 层保持一致，前端只需把 TypeScript 类型从 `Record<string, any>[]` 升级为强类型接口 -- 聚合接口 `GET /mp/trip/today-dashboard` 下游消费已同步升级（见 `2026-04-21_mp_today-dashboard-full-aggregation.md`） - -## 五、关联 - -- Issue: [wx/HL#1119](https://git.1814.love:8443/wx/HL/issues/1119) -- PR: [wx/HL#1123](https://git.1814.love:8443/wx/HL/pulls/1123)（已合并到 dev） -- 后续：酒店 WiFi 字段补齐见 `2026-04-21_resource_hotel-wifi-fields.md` diff --git a/changelogs/2026-04/2026-04-21_theme-card-link-rollback-to-enum-paths-in-remark.md b/changelogs/2026-04/2026-04-21_theme-card-link-rollback-to-enum-paths-in-remark.md deleted file mode 100644 index 72043e4..0000000 --- a/changelogs/2026-04/2026-04-21_theme-card-link-rollback-to-enum-paths-in-remark.md +++ /dev/null @@ -1,106 +0,0 @@ -# 更正：主题卡片跳转字典回滚到枚举 + 路径存 remark - -**日期**：2026-04-21（同日晚） -**类型**：方案更正 / DB 回滚，**无后端代码变更** -**后端服务**：hl-user-service（不用重启） -**影响**：管理端「首页配置 → 品牌故事 → 主题卡片跳转类型」下拉 - ---- - -## 背景（请先读完再做事） - -今早同一个业务话题发过两份 changelog： -1. `2026-04-21_home-screen2-theme-card-link.md`（#1081）—— 字典 value=`SEASON/CORE_LIST/MENGMA/PRODUCT` 枚举 -2. `2026-04-21_topic-link-type-paths-and-product-payload.md`（#1085）—— 尝试把 value 改成完整路径 `packages/product/season/list/list` - -**本更正废弃第 2 份里关于「字典 value 改为路径」的部分**，恢复为第 1 份的枚举方案，路径改放到 `remark` 字段。 - ---- - -## 为什么回滚 - -- `AdminBrandStorySaveReqVO.Card.linkType` 上有 `@Pattern(regexp="^(SEASON|CORE_LIST|MENGMA|PRODUCT)$")` 硬校验 -- `HomeBrandStoryService.VALID_LINK_TYPES` 也是同名 4 个枚举白名单 -- 如果把字典 value 改成路径，前端下拉选中后提交 `linkType=packages/product/season/list/list` → 后端 `@Pattern` 拒绝 → **500 报错** `cards[].linkType: 跳转类型只能是 SEASON / CORE_LIST / MENGMA / PRODUCT` -- 权衡后：**代码不动、字典回滚到枚举、前端需要的路径放在 remark**，方案更稳（未来改路径只改字典 remark，不需要动后端代码） - ---- - -## 字典最终状态（本地 + 测试服 192.168.100.236 已同步） - -`sys_dict_type`：`theme_card_link_type`（dict_type_id=8090，category=BUSINESS，ACTIVE） - -`sys_dict_data`： - -| dict_data_id | dict_value | dict_label | remark（路径在这里） | -|--------------|-----------|-----------|------| -| 80901 | `SEASON` | 季节之旅 | `跳转: packages/product/season/list/list` | -| 80902 | `CORE_LIST` | 核心产品 | `跳转: packages/product/core/list/list` | -| 80903 | `MENGMA` | 亲子游学 | `跳转: packages/product/mengma/list/list` | -| 80904 | `PRODUCT` | 指定产品 | `指定产品详情（linkTargetType=CORE/GROUP + linkTargetId）` | - ---- - -## 前端对接要点（替换第 2 份 changelog 的相关章节） - -### 管理端下拉渲染 -- 拉 `/admin/dict/data?dictType=theme_card_link_type` 得到 4 条 -- **下拉 option 用 `dict_label` 做显示文案**、**`dict_value` 做表单值**（保持枚举） -- 如果前端需要跳转路径（例如预览 / 提示）：**解析 `remark`**，去掉固定前缀 `"跳转: "` 得到路径；PRODUCT 的 remark 是说明文本，不是路径（需 linkTargetType+linkTargetId 动态拼） - -### 保存（POST/PUT brand-story） -请求体 `cards[].linkType` 仍然只能是 **4 个枚举值之一**： -```json -{ - "cards": [ - { - "title": "季节之旅", - "coverUrl": "https://...", - "linkType": "SEASON" - }, - { - "title": "亲子系列", - "coverUrl": "https://...", - "linkType": "PRODUCT", - "linkTargetType": "CORE", - "linkTargetId": 2001 - } - ] -} -``` -- `linkType` ∈ `{SEASON, CORE_LIST, MENGMA, PRODUCT}`（**不要**传路径） -- `linkType=PRODUCT` 时 `linkTargetType` + `linkTargetId` 必填；其它 linkType 不用传 / 传了也会被后端清空 - -### 小程序侧 -- Feign/聚合接口返回的 `BrandCard.linkType` 仍然是 4 个枚举之一（#1081 原样） -- 小程序自己维护一张 code → 路径的 switch： - ```js - const ROUTE_BY_LINK_TYPE = { - SEASON: 'packages/product/season/list/list', - CORE_LIST: 'packages/product/core/list/list', - MENGMA: 'packages/product/mengma/list/list', - // PRODUCT 运行时按 linkTargetType + linkTargetId 拼 - }; - ``` -- 路径单一真相源：字典 `remark` 字段；改路径只需改字典，无须发版 - ---- - -## 第 2 份 changelog 的哪些内容仍然有效 - -`2026-04-21_topic-link-type-paths-and-product-payload.md` 里关于 **`/admin/topic` 接口**的变动（`TopicRequest` / `TopicVO` 新增 `productId` + `productType`）**仍然有效**，那是独立的一套（PR #1085 已合并部署），和本次 brand-story 无关。但 topic 那套 `linkType` 也应该按枚举传（和 brand-story 口径统一），不要传长路径。 - ---- - -## 验证 - -- 本地 DB（127.0.0.1:3306/hl_user_service）已回滚 ✅ -- 测试服 DB（192.168.100.236/hl_user_service）已回滚 ✅ -- `sys_topic.link_type` 列宽留在 VARCHAR(200)，不回滚（多出的空间不占事） -- 后端 `@Pattern` 和 `VALID_LINK_TYPES` 与字典 value 再次一致，保存不再 500 - ---- - -## 重启 - -无后端代码改动，**不需要重启任何服务**。前端刷新页面即可看到正确下拉。 diff --git a/changelogs/2026-04/2026-04-21_topic-link-type-paths-and-product-payload.md b/changelogs/2026-04/2026-04-21_topic-link-type-paths-and-product-payload.md deleted file mode 100644 index d63a9a8..0000000 --- a/changelogs/2026-04/2026-04-21_topic-link-type-paths-and-product-payload.md +++ /dev/null @@ -1,146 +0,0 @@ -# 主题卡片跳转类型改路径直跳 + PRODUCT 存 productId+productType - -**日期**：2026-04-21 -**PR**：#1085 -**合并到 dev commit**：55d601d7 -**后端服务**：hl-user-service（需重启） -**影响**： -- 管理端「首页配置 → 品牌故事 → 主题卡片」跳转类型下拉 + 指定产品选择 -- 小程序「首页第二屏」点击主题卡片跳转逻辑 - -> 本次是对 #1081（2026-04-21 早上）的迭代。#1081 建立了跳转类型字段，本次调整字典 value 语义 + PRODUCT 的 payload 存储方式。 - ---- - -## 为什么改 - -#1081 之前把 4 种跳转类型的 `dict_value` 定为枚举 code（`SEASON` / `CORE_LIST` / `MENGMA` / `PRODUCT`），前端还要维护一张 code → 路径的 switch 表。改完后三种列表类直接把路径放到 `dict_value`，前端拿到直接跳，不用 switch。只有「指定产品」保留枚举 `PRODUCT`，因为路径需要运行时拼产品 id/类型。 - ---- - -## 字典改动（已同步本地 + 测试服 192.168.100.236） - -**dict_type**：`theme_card_link_type`（不变，dict_type_id=8090，category=BUSINESS） - -**dict_data**： - -| dict_value（变化） | dict_label | sort_order | -|-------------------|-----------|-----------| -| `packages/product/season/list/list` | 季节之旅 | 10 | -| `packages/product/core/list/list` | 核心产品 | 20 | -| `packages/product/mengma/list/list` | 亲子游学 | 30 | -| `PRODUCT`（保留枚举） | 指定产品 | 40 | - -**迁移**：本地 + 测试服 DB 已通过 UPDATE 同步；`sys_topic.link_type` 从 VARCHAR(20) 扩到 VARCHAR(200)（因路径超长）。 - ---- - -## 接口签名变化 - -### 1. `TopicRequest`（POST /admin/topic/create、PUT /admin/topic/update 入参） - -**新增两个字段**： - -| 字段 | 类型 | 是否必填 | 说明 | -|------|------|---------|------| -| `productId` | `Long` | **PRODUCT 类型必填** | 指定的产品 ID | -| `productType` | `String` | **PRODUCT 类型必填** | 产品类型（字典 `product_type`：CORE / GROUP / CUSTOM） | - -**`linkType` / `linkTarget` 语义调整**： - -| linkType 值 | linkTarget 怎么传 | productId / productType 怎么传 | -|-------------|------------------|---------------------------------| -| `packages/product/season/list/list` | 不传（后端会忽略） | 不传 | -| `packages/product/core/list/list` | 不传 | 不传 | -| `packages/product/mengma/list/list` | 不传 | 不传 | -| `PRODUCT` | **不要传**（后端会忽略并合成 JSON） | **必填** productId + productType | - -> ⚠️ 校验：`linkType=PRODUCT` 时 productId 或 productType 缺失，后端直接抛 `{"code":400,"message":"指定产品跳转必须填写产品ID和产品类型"}`。 - -**请求示例（路径直跳）**： -```json -{ - "title": "季节之旅", - "coverUrl": "https://oss.../cover.png", - "linkType": "packages/product/season/list/list" -} -``` - -**请求示例（指定产品）**： -```json -{ - "title": "亲子系列", - "coverUrl": "https://oss.../cover.png", - "linkType": "PRODUCT", - "productId": 2045345825172639746, - "productType": "CORE" -} -``` - -### 2. `TopicVO`（GET /admin/topic/{id} 或列表返回） - -**新增两个回显字段**： - -| 字段 | 类型 | 何时有值 | -|------|------|---------| -| `productId` | `Long` | 仅 `linkType=PRODUCT` 时非空 | -| `productType` | `String` | 仅 `linkType=PRODUCT` 时非空 | - -`linkTarget` 字段行为： -- `linkType=PRODUCT`：仍然是 JSON 字符串（`{"productId":xxx,"productType":"CORE"}`），**前端直接读新的 productId/productType 字段即可**，不用再解析 linkTarget -- 其它 linkType：目前后端写入时为空字符串，前端忽略即可 - -**响应示例（指定产品）**： -```json -{ - "id": "2046xxx", - "title": "亲子系列", - "linkType": "PRODUCT", - "linkTarget": "{\"productId\":2045345825172639746,\"productType\":\"CORE\"}", - "productId": 2045345825172639746, - "productType": "CORE" -} -``` - ---- - -## 管理端前端要做的事 - -1. **跳转类型下拉**：拉 `/admin/dict/data?dictType=theme_card_link_type`，直接用 `dict_label` 显示 + `dict_value` 作为 linkType -2. **选中 PRODUCT 时弹产品选择器**：用户选完产品后拿到 productId + productType，保存时塞进 `TopicRequest.productId` / `productType`（不要再传 linkTarget） -3. **选中非 PRODUCT（路径）时**：直接把字典 value 作为 linkType 提交，不用管 linkTarget / productId / productType -4. **回显**：编辑页如果 topic.linkType='PRODUCT'，用 `topic.productId` + `topic.productType` 反查产品名展示；否则按路径下拉项高亮对应项即可 - ---- - -## 小程序前端要做的事 - -点击主题卡片时： -- `linkType=PRODUCT` → 按 `productId` + `productType` 拼产品详情路径（具体格式由前端约定） -- 其它（路径） → `wx.navigateTo({ url: '/' + linkType })` 直接跳 - -老小程序（未感知此次变化）：`linkType` 拿到字符串路径也能直接 navigate，只有 PRODUCT 类型会走不到详情（但原本 #1081 就约定 PRODUCT 依赖 target 字段，老端本来就没处理），不属于回归。 - ---- - -## 兼容性与老数据 - -- 本 PR 合并前数据库里 `sys_topic` 是空表，没有历史数据要迁移 -- TopicVO.toVO 对 legacy 纯数值字符串 linkTarget（形如 `"12345"`）做了 `log.warn` 容忍，不会 500，productId/productType 返 null；如未来真有脏数据可手工修 -- 老版本小程序拿到新的路径型 linkType 仍能直接 navigateTo，不会崩 - ---- - -## 测试 - -- 单测 `TopicServiceTest` **31 个用例全绿** - - 新增 6 个：`createTopic_productType_serializesLinkTargetAsJson` / `createTopic_product_missingProductId` / `createTopic_product_missingProductType` / `createTopic_seasonPath_keepsLinkTargetAsIs` / `updateTopic_product_rebuildsLinkTarget` / `toVO_product_withLegacyLinkTarget_tolerated` -- 测试服字典已同步（dict_type + 4 条 dict_data + link_type 列宽） -- 测试服 hl-user-service 已触发 Deploy Panel 重新部署 - ---- - -## 重启 - -- **hl-user-service** 必须重启（新代码） -- 其它服务无依赖，不用重启 diff --git a/changelogs/2026-04/2026-04-22_contract-scheme-platform-dropdown-tencent-esign.md b/changelogs/2026-04/2026-04-22_contract-scheme-platform-dropdown-tencent-esign.md deleted file mode 100644 index 67d16cb..0000000 --- a/changelogs/2026-04/2026-04-22_contract-scheme-platform-dropdown-tencent-esign.md +++ /dev/null @@ -1,97 +0,0 @@ -# 合同方案 "合同平台" 下拉：移除法大大，接入腾讯电子签 - -- **日期**: 2026-04-22 -- **涉及页面**: 管理端 → 合同管理 → 合同方案 → 新增/编辑弹窗 -- **文件**: `src/views/contract/scheme/components/SchemeEditModal.vue` -- **原因**: 后端第二期对接腾讯电子签（PR #1138/#1141/#1147），字典 `contract_platform` 新增 `TENCENT_ESIGN`；同时业务不再使用法大大，字典 `FADADA` 已置 `INACTIVE`。 -- **影响**: 管理端创建/编辑合同方案时，当前只有 "12301 / 法大大" 两个硬编码选项，**看不到腾讯电子签**。 - -## 后端已完成 - -| 项 | 值 | -|----|----| -| 字典 | `contract_platform` → `12301`(ACTIVE) / `FADADA`(**INACTIVE**) / `TENCENT_ESIGN`(ACTIVE) | -| 后端枚举 | `ContractPlatform.TOURAGE` / `LOCAL` / **`TENCENT_ESIGN`** | -| Scheme 新字段 | `vendorCode` / `channel`（PR #1138）| -| 策略实现 | `TencentEsignContractPlatform`（PR #1141）| -| 回调 Controller | `POST /contract/callback/tencent-esign[/{vendorCode}]`（PR #1147）| - -## 前端改动（必做） - -### 当前硬编码代码 - -```vue -<!-- src/views/contract/scheme/components/SchemeEditModal.vue line 30-34 --> -<n-form-item label="合同平台" path="contractPlatform"> - <n-radio-group v-model:value="formData.contractPlatform"> - <n-radio value="12301">全国旅游监管平台</n-radio> - <n-radio value="FADADA">法大大</n-radio> - </n-radio-group> -</n-form-item> -``` - -### 方案 A（推荐，长期治本）：从字典动态拉取 - -```vue -<n-form-item label="合同平台" path="contractPlatform"> - <n-radio-group v-model:value="formData.contractPlatform"> - <n-radio v-for="opt in platformOptions" :key="opt.value" :value="opt.value"> - {{ opt.label }} - </n-radio> - </n-radio-group> -</n-form-item> -``` - -```ts -// 用你们现有的字典 hook -import { useDictData } from '@/hooks/useDictData' -const { options: platformOptions } = useDictData('contract_platform') // 只返 status=ACTIVE 项 -``` - -后端字典 `status=INACTIVE` 的条目**不会出现在下拉**。未来加 `ESIGN_XX` 只改字典无需改前端。 - -### 方案 B（立即修复，临时）：只改硬编码 - -```vue -<n-radio-group v-model:value="formData.contractPlatform"> - <n-radio value="12301">全国旅游监管平台</n-radio> - <n-radio value="TENCENT_ESIGN">腾讯电子签</n-radio> -</n-radio-group> -``` - -删除 `FADADA` 那行，新增 `TENCENT_ESIGN`。 - -### default 值 - -line 165 `contractPlatform: '12301'` 和 line 263 `contractPlatform: detail.contractPlatform || '12301'` 保持不变（12301 仍是默认兜底）。 - -## 同时需要改的下拉（同页面） - -如果有 **vendorCode** 字段显示（腾讯多企业号场景），也需要加。但本期只接 `TENCENT_HULAI` 一个 vendor，字段可延后： - -- 后端 `ContractSchemeRequest.vendorCode` 已支持（PR #1138） -- `@ApiModelProperty` 描述：`平台厂商编码：TENCENT_HULAI=呼籁自有腾讯账号；12301 平台此字段可为空` -- 前端可加个条件显示：platform=TENCENT_ESIGN 时才显示一个 vendorCode 单选（当前只有 `TENCENT_HULAI`） - -## 同时需要改的下拉（列表页） - -`src/views/contract/scheme/index.vue` 和 `src/views/contract/list/index.vue` 如果有按"合同平台"筛选或渲染标签，同样需要： -- FADADA → 移除 -- TENCENT_ESIGN → 新增（label "腾讯电子签"） - -## 相关后端接口（已就绪） - -- `GET /admin/contract/scheme/list-all` - 返回 `contractPlatform` / `vendorCode` / `channel` 字段 -- `POST /admin/contract/scheme` - 接 `contractPlatform=TENCENT_ESIGN` + `vendorCode=TENCENT_HULAI` + 可选 `channel` -- `GET /admin/dict/data/list?dictType=contract_platform` - 拉字典（方案 A 用） - -## 验收 - -1. 打开 "新增合同方案" 弹窗 -2. "合同平台" 区域只显示 2 个选项：`全国旅游监管平台` / `腾讯电子签`（无法大大） -3. 选"腾讯电子签" → 保存成功 -4. 方案列表/详情页的合同平台标签能正确显示"腾讯电子签"中文名 - -## 紧急度 - -**高**。2026-04-25 腾讯测试专业版到期前要跑完端到端联调，前端不改这个下拉，运营无法创建 TENCENT_ESIGN 的 Scheme，整个第二期合同接入**卡在这一步**。 diff --git a/changelogs/2026-04/2026-04-22_mp-order-detail-traveler-id-now-populated.md b/changelogs/2026-04/2026-04-22_mp-order-detail-traveler-id-now-populated.md deleted file mode 100644 index a86fa6c..0000000 --- a/changelogs/2026-04/2026-04-22_mp-order-detail-traveler-id-now-populated.md +++ /dev/null @@ -1,73 +0,0 @@ -# MP 订单详情 travelers[] 字段 travelerId 从 null 变真实值 - -**日期**: 2026-04-22 -**PR**: #1208 -**Issue**: #1207 -**服务**: hl-order-service-v2(已部署测试服 双实例 8094/8194) -**影响端**: 小程序订单详情页、管理端可能调用的 MP 订单详情 - -## 问题 - -`GET /mp/order/{orderId}` 返回的 `data.travelers[]` 数组,每条出行人对象的: - -- `travelerId` —— **之前永远是 null** -- `travelerTypeLabel` —— 之前永远是 null -- `idCardTypeLabel` —— 之前永远是 null - -前端凡是依赖 `travelerId` 做**编辑 / 删除 / 关联**的操作都不可用;依赖 label 做展示的会显示空。 - -## 根因(后端自修) - -后端 `MpOrderDetailAssembler` 用 Hutool `BeanUtil.toBean` 做 `OrderTraveler → TravelerVO` 映射,但 Entity 主键字段名 `orderTravelerId` ≠ VO 字段 `travelerId`,属性精确匹配不上导致 id 永久 null;enum 类型字段转 label 也被吞。修复后复用同 Service 已有的正确手动映射方法。 - -## 字段契约(修复后) - -``` -GET /mp/order/{orderId} -Response.data.travelers: Array<MpTravelerVO> -``` - -每条 MpTravelerVO 关键字段: - -| 字段 | 类型 | 修复前 | 修复后 | -|------|------|--------|--------| -| `travelerId` | Long | null | 真实雪花 ID | -| `name` | String | 正常 | 正常 | -| `travelerType` | String | 正常(ADULT/CHILD/YOUNG_CHILD/BABY) | 正常 | -| `travelerTypeLabel` | String | null | "成人"/"儿童"/"幼儿"/"婴儿" | -| `idCardType` | String | 正常(IDCARD/PASSPORT/...) | 正常 | -| `idCardTypeLabel` | String | null | "身份证"/"护照"/... | -| `idCardNo` | String | 正常 | 正常 | -| `phone` / `gender` / `birthday` / ... | | 正常 | 正常 | - -## 前端 TODO(若此前有兜底) - -- 如果之前判空后显示"-"或不显示编辑/删除按钮,现在可以直接信任 `travelerId` 非 null -- 如果之前手动拼 label,现在可以直接用 `travelerTypeLabel` / `idCardTypeLabel` -- 无需改任何请求签名,无需发版,后端部署后次日生效(前端刷新页面即生效) - -## 验证 - -```bash -# 测试服内部 curl(需 gateway token) -curl "https://api.test.1814.love:9443/mp/order/{orderId}" -H "Authorization: Bearer {TOKEN}" - -# 断言 -.data.travelers[].travelerId != null -.data.travelers[].travelerTypeLabel in ["成人","儿童","幼儿","婴儿"] -``` - -实测订单 `2046842978273579010`: -```json -{ - "travelers": [ - { "travelerId": 2046911429360955393, "name": "米明光", "travelerType": "ADULT", "travelerTypeLabel": "成人" }, - { "travelerId": 2046911429365149698, "name": "王晓", "travelerType": "YOUNG_CHILD", "travelerTypeLabel": "幼儿" } - ] -} -``` - -## 无破坏性 - -- 字段名/类型不变,仅值从 null 变真实值 -- 无前端代码必须改动 diff --git a/changelogs/2026-04/2026-04-22_mp-order-traveler-edit-wrong-endpoint-frontend-fix.md b/changelogs/2026-04/2026-04-22_mp-order-traveler-edit-wrong-endpoint-frontend-fix.md deleted file mode 100644 index 189e643..0000000 --- a/changelogs/2026-04/2026-04-22_mp-order-traveler-edit-wrong-endpoint-frontend-fix.md +++ /dev/null @@ -1,97 +0,0 @@ -# [前端 BUG · 需前端修] 订单里编辑出行人调错接口导致"参数类型错误: id"+主表被误改 - -> **归属**: 前端 -> **日期**: 2026-04-22 -> **报告人**: wx (后端) -> **优先级**: P1 - -## 现象 - -小程序 **订单详情 → 出行人列表 → 点编辑 → 保存** 时: -1. 红字 toast: **"参数类型错误: id"** -2. 部分场景下用户反馈"订单的出行人"和"实际出行人(常用出行人地址簿)"都被修改 - -## 根因 (后端三尺实证已确认) - -### 根因 1: 调错接口 - -本项目有两个完全独立的"出行人"接口,语义不同: - -| 接口 | 改的表 | 语义 | 适用场景 | -|------|--------|------|---------| -| `PUT /mp/user/traveler/{id}` | `traveler` (用户地址簿主表) | 长期维护的常用出行人 | **个人中心 → 常用出行人** 页面 | -| `PUT /mp/order/{orderId}/traveler/{travelerId}` | `order_traveler` (订单快照表) | 下单快照,不影响主表 | **订单详情 → 出行人** 页面 | - -目前"订单里编辑出行人"页面调的是 `/mp/user/traveler/{id}`(主表接口),**调用目标错了**。 - -### 根因 2: `id` 为 undefined/null/对象 - -`/mp/user/traveler/{id}` 的路径参数 `id` 是 `Long` 类型,Spring 解析失败即报 "参数类型错误: id"。 -说明前端在构造 URL 时 `id` 传入了 `undefined` / `null` / 非数字字符串,URL 变成 `/mp/user/traveler/undefined` 被后端 `MethodArgumentTypeMismatchException` 拦截。 - -### 为什么会"双改" - -- 调了主表接口 → 地址簿被改 -- 订单详情里的出行人如果从主表 join 展示姓名/证件,看起来"订单出行人也变了" - -(后端代码已核查: `OrderTravelerService.updateTraveler` 只动 `order_traveler`,`MpTravelerController.updateTraveler` 只动 `traveler`。双方都是快照/主表独立维护,没有任何一个后端方法"双改"两张表。) - -## 前端修复要求 - -### 1. 订单出行人编辑页统一走订单快照接口 - -**旧 (错)**: -```js -PUT /mp/user/traveler/{id} // id = orderTravelerId (不对口) - // 或 id = undefined (参数类型错误) -``` - -**新 (对)**: -```js -PUT /mp/order/{orderId}/traveler/{travelerId} - body: MpOrderTravelerSaveReqVO { - name, idCardType, idCardNo, phone, gender, birthday, - travelerType, nationality, emergencyContact, emergencyPhone, email - } -``` - -- `orderId`: 当前订单 ID -- `travelerId`: 从 `GET /mp/order/{orderId}/traveler` 返回的 `TravelerVO.travelerId`(就是 `order_traveler.order_traveler_id`) -- 不要 fallback 到"常用出行人 id" - -### 2. 保存按钮点击前校验 `travelerId` 存在 - -构造 URL 前 `if (!travelerId) { return uni.showToast('出行人 ID 缺失') }`,禁止 `undefined` 进 URL。 - -### 3. 区分两个"编辑出行人"入口 - -| 入口页面 | 调用接口 | -|---------|---------| -| 个人中心 → 我的出行人 → 编辑 | `PUT /mp/user/traveler/{id}` | -| 订单详情 → 出行人 → 编辑 | `PUT /mp/order/{orderId}/traveler/{travelerId}` | - -两个入口**必须**用对应的接口,不可共用同一个 API 调用。 - -## 相关接口 - -### 订单出行人 (本次要改的目标接口) - -- `GET /mp/order/{orderId}/traveler` — 查询订单出行人列表 - 返回 `List<TravelerVO>`,其中 `travelerId` 就是 `order_traveler.order_traveler_id` -- `POST /mp/order/{orderId}/traveler` — 新增订单出行人 -- **`PUT /mp/order/{orderId}/traveler/{travelerId}`** — **修改订单出行人 (null 字段保持原值)** -- `DELETE /mp/order/{orderId}/traveler/{travelerId}` — 删除订单出行人 - -所有字段语义见 `MpOrderTravelerSaveReqVO`,与 `MpTravelerRequest` 字段名对齐,Jackson 透传。 - -### 用户常用出行人 (只用于"个人中心 → 我的出行人") - -- `GET /mp/user/traveler` — 列表 -- `POST /mp/user/traveler` — 新增 -- `PUT /mp/user/traveler/{id}` — 改主表 -- `DELETE /mp/user/traveler/{id}` — 删主表 -- `PUT /mp/user/traveler/{id}/default` — 设为默认 - -## 后端无改动 - -本次后端代码、DB、VO 均无变更。 diff --git a/changelogs/2026-04/2026-04-22_mp-product-detail-order-snapshot.md b/changelogs/2026-04/2026-04-22_mp-product-detail-order-snapshot.md deleted file mode 100644 index 69dd67f..0000000 --- a/changelogs/2026-04/2026-04-22_mp-product-detail-order-snapshot.md +++ /dev/null @@ -1,139 +0,0 @@ -# MP 产品详情接口支持订单快照回显 - -- **变更日期**: 2026-04-22 -- **PR**: #1182 -- **Closes**: #1176 -- **影响面**: 小程序端（管理端不涉及） -- **兼容性**: **完全向后兼容**，不传 `orderId` 时行为与改前一致 - ---- - -## 🎯 业务背景 - -用户从订单详情页点进产品详情时，应看到下单时冻结的产品快照（非实时最新），避免产品改价/改行程导致历史订单展示混乱。 - ---- - -## 📡 接口变更：`GET /mp/product/{id}` - -### 1. 新增可选 Query 参数 - -| 参数 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `orderId` | Long | 否 | 订单 ID。传了走快照路径；不传/0/负数走原逻辑（查最新产品） | - -### 2. 触发场景（建议前端） - -**仅在**「订单详情页 → 产品卡片/产品详情入口」传 `orderId`。其它入口（首页搜索、列表、分享链接、退款页等）**不传 orderId**，避免快照扩散到无必要场景。 - -### 3. 请求示例 - -```http -# 实时路径（原有行为，零变化） -GET /mp/product/1001 -Authorization: Bearer <token> - -# 快照路径（新增） -GET /mp/product/1001?orderId=99988 -Authorization: Bearer <token> -``` - ---- - -## 📦 响应 VO 变更：`MpProductDetailRespVO` 新增 3 字段 - -所有字段都是 **Boolean/Long 类型，可空**，旧前端代码不读时零影响。 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `isSnapshot` | Boolean | `true`=快照数据（冻结版本）；`false`/null=实时数据 | -| `snapshotOrderId` | Long | 快照来源的订单 ID（仅 isSnapshot=true 时有值）| -| `snapshotFallback` | Boolean | `true`=原本想返回快照但降级到了实时（订单异常/快照空/Feign 失败等）；`false`=正常快照；null=原路径未涉及 | - -### 响应三态对照 - -| 请求 | isSnapshot | snapshotOrderId | snapshotFallback | 含义 | -|---|---|---|---|---| -| 不传 orderId | null/false | null | null | 原逻辑实时数据 | -| 传 orderId（一切正常）| **true** | 99988 | **false** | 返回订单快照，前端可打「订单快照」标识 | -| 传 orderId（降级）| false | 99988 | **true** | 快照出问题降级实时了，前端可提示「当前为最新版本，下单时数据已不可查」 | - ---- - -## 🔻 错误码 / 降级行为 - -| 场景 | 行为 | -|---|---| -| 不传 orderId | 原逻辑，查最新产品（5min Redis 缓存）| -| 传 orderId=0 或负数 | 同「不传 orderId」 | -| 传的 orderId 不存在 / 非本人 / 已软删 | **统一降级到实时路径** + `snapshotFallback=true`，不抛错（防 orderId 枚举攻击）| -| 快照字段为空（历史订单）/ JSON 解析失败 | 降级实时 + `snapshotFallback=true` | -| 快照正常但对应产品已下架 | 返回快照 + `productDeleted=true`（前端可提示「该产品已下架」）| -| Feign 超时 / order 服务不可达 | 降级实时 + `snapshotFallback=true` | -| `productId` 与快照里的不匹配（防串号）| HTTP 200 + 业务错误码 400 + msg「产品与订单不匹配」| - ---- - -## 🧩 MP 独有字段（不走快照，走实时） - -下列字段**永远实时查**，即使走快照路径也会实时补齐（因为这些是用户预期会更新的数据）： - -- `reviewSummary`（评价摘要） -- `earlyBirdTip` / `earlyBirdLadder`（早鸟方案） -- `DayInfo.gatherPlace` / `dismissalPlace` / `quoteText`（集合/解散地、引言） -- `NodeInfo.resourceCover` / `resourceImages` / `resourceAddress` / `resourceDescription` / `resourceTags`（资源详情） -- `TierPriceInfo.depositAmount`（按比例算） -- `refundPolicy`（退款政策） - -这些字段在快照路径下也正常返回，前端不用关心差异。 - ---- - -## 🔒 鉴权 - -- 小程序 token（登录态）必传。网关从 token 解析 `X-User-Id` Header 注入，后端据此校验订单归属 -- 未登录（token 缺失）时走实时路径 + `snapshotFallback=true` - ---- - -## ✅ 前端接入建议 - -```js -// 从订单详情进产品 -const resp = await request({ - url: `/mp/product/${productId}?orderId=${orderId}`, -}); - -if (resp.data.isSnapshot === true) { - // 显示角标：订单快照版本 - showBadge('订单快照'); -} else if (resp.data.snapshotFallback === true) { - // 提示：原订单数据已不可查，显示最新 - showTip('当前为最新版本，下单时数据已不可查'); -} - -if (resp.data.productDeleted === true) { - // 产品已下架，仅展示模式 - disableActions(); - showTip('该产品已下架'); -} -``` - -其他入口调用方式不变。 - ---- - -## 📌 非变更项（确保前端无需额外改动） - -- 其他返回字段（id/name/tiers/itinerary/tierPrices/...）语义不变 -- Header、认证方式、Base URL 均不变 -- 其他接口（`/mp/product/list`、`/admin/product/**` 等）零影响 - ---- - -## 🔗 相关 - -- 工单：#1176 -- PR：#1182 -- 部署：合并到 dev 后由 Deploy Panel 同步部署 `hl-order-service-v2` + `hl-product-service-v2` -- 测试环境：`https://api.test.1814.love:9443` diff --git a/changelogs/2026-04/2026-04-22_mp-traveler-birthday-auto-from-idcard.md b/changelogs/2026-04/2026-04-22_mp-traveler-birthday-auto-from-idcard.md deleted file mode 100644 index 57b2b4d..0000000 --- a/changelogs/2026-04/2026-04-22_mp-traveler-birthday-auto-from-idcard.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -date: 2026-04-22 -type: docs -scope: hl-mp-service,hl-user-service -pr: "#待填" -issue: "#1205" -breaking: false -audience: frontend ---- - -# 小程序添加出行人: 身份证场景 birthday 可空(后端自动解析回填) - -## TL;DR(前端行动点) - -小程序 "添加出行人" 表单,当 `idCardType === 'ID_CARD'` 时, **不要再要求用户手动选 birthday**。两种任选其一: - -1. **推荐**: 前端按身份证号第 7-14 位本地解析 `YYYYMMDD` 自动回填 input (与后端一致, 所见即所得) -2. **最小改动**: 前端表单 validator 对 `birthday` 必填校验放行 `idCardType=ID_CARD` 场景, 让请求直接发后端, 后端解析后 GET 详情时前端再刷新展示 - -## 背景 - -用户反馈: 身份证类型下, 填好证件号 + 姓名 + 手机号点 "确认添加", 被前端 Toast `请选择出生日期` 拦截。 - -后端早已支持 "填身份证 idCardNo 可不传 birthday" 契约 —— `TravelerService.addTraveler()` 在 `save()` **前**调用 `parseIdCardInfo()`, 按 `idCardNo.substring(6,14)` 用 `LocalDate.parse(str, BASIC_ISO_DATE)` 自动回填 `birthday` 写入 DB。 - -但此契约在 `@ApiModelProperty` 里没写清楚, 前端未读到导致表单校验写死 birthday 必填。 - -## 接口契约(本次明确) - -POST `/mp/user/traveler` (添加出行人) — 请求字段规则: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `name` | String | ✅ | 姓名 | -| `idCardType` | String | 推荐填 | `ID_CARD`(身份证) / `PASSPORT`(护照) / 其它 | -| `idCardNo` | String | 依业务 | 身份证 18 位 / 护照号等 | -| `birthday` | yyyy-MM-dd | **条件性** | **填身份证(ID_CARD)时可空, 后端自动解析 idCardNo 第 7-14 位回填; 护照等其它证件类型需前端传值** | -| `gender` | String | 否 | 身份证时后端从 idCardNo 第 17 位奇偶推断(填了则覆盖) | -| `phone` | String | 否 | 手机号 | -| 其余 | - | 否 | 见 knife4j | - -PUT `/mp/user/traveler/{id}` (编辑) 同样规则。 - -## 后端行为(只读参考) - -```java -// hl-user-service: TravelerService.parseIdCardInfo -if (!"ID_CARD".equals(idCardType) || idCardNo == null || idCardNo.length() != 18) return; -if (traveler.getBirthday() == null) { - String birthStr = idCardNo.substring(6, 14); - traveler.setBirthday(LocalDate.parse(birthStr, DateTimeFormatter.BASIC_ISO_DATE)); -} -``` - -- 身份证号位数不对 / 解析失败: 后端仅 `log.debug` 不抛异常, birthday 留 null -- 证件类型非 `ID_CARD`: 后端不解析, 前端必须传 birthday, 否则 `travelerType` 会默认 ADULT - -## 护照场景(保持不变) - -护照等非 ID_CARD 证件, 后端**不会**自动回填 birthday, 前端表单需要保留 birthday 选择器并要求用户填写 (否则后端按 `traveler_type_age_rule` 兜底为 ADULT)。 - -## 本次后端改动 - -仅 2 个 DTO 的 `@ApiModelProperty` 文案补充(`MpTravelerRequest.birthday` / `TravelerRequest.birthday`), 无业务逻辑变化、无签名变化、无字段增减。前端零风险, 本 changelog 是提醒前端调整表单校验。 - -## 关联 Issue / PR - -- Issue #1205 (前端 BUG: 前端表单校验写死 birthday 必填, 未识别身份证自动解析契约) -- PR #待填 -- 关联前期 PR 链: #1197 (travelerType 不入参+实时算) / #1198 (冷启动 SysDictService 回源) / #1199 (删 TravelerTypeResolver) diff --git a/changelogs/2026-04/2026-04-22_mp-traveler-type-auto-computed.md b/changelogs/2026-04/2026-04-22_mp-traveler-type-auto-computed.md deleted file mode 100644 index dd9469e..0000000 --- a/changelogs/2026-04/2026-04-22_mp-traveler-type-auto-computed.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -date: 2026-04-22 -type: change -scope: mp-traveler -pr: "#1197" -issue: "#1196" -breaking: false -consumers: [mp-miniprogram] ---- - -# 小程序新增/编辑出行人接口移除 `travelerType` 入参，后端按字典实时计算 - -## 摘要 - -`POST /mp/user/traveler` 与 `PUT /mp/user/traveler/{id}` 的请求体**不再接收 `travelerType` 字段**。出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY）由后端依据 `birthday` + 字典 `traveler_type_age_rule` **实时计算**，且**不落库**——字典规则后续调整时历史数据口径会自动跟随，无须数据迁移。 - -## 前端需要做什么 - -### 1. 新增 / 编辑出行人 - -- **删除请求体里的 `travelerType` 字段**。即使偷传也会被后端忽略（字段已从 DTO 删除，JSON 反序列化静默丢弃）。 -- `birthday` 仍可选；不传则后端兜底 `ADULT`。 - -**之前**： - -```json -POST /mp/user/traveler -{ - "name": "张三", - "travelerType": "CHILD", // ← 删掉 - "birthday": "2020-05-01", - "idCardType": "PASSPORT", - "idCardNo": "E12345678" -} -``` - -**之后**： - -```json -POST /mp/user/traveler -{ - "name": "张三", - "birthday": "2020-05-01", - "idCardType": "PASSPORT", - "idCardNo": "E12345678" -} -``` - -### 2. 响应字段不变 - -`travelerType` 仍出现在所有响应 VO（POST/PUT/GET/GET list）里，值由后端按 birthday + 字典实时算： - -```json -{ - "code": 200, - "data": { - "travelerId": 2046901540208214018, - "name": "张三", - "birthday": "2020-05-01", - "travelerType": "CHILD", // 实时计算 - ... - } -} -``` - -## 年龄分段规则（来自字典 `traveler_type_age_rule`） - -| 类型 | 年龄范围（含下限不含上限） | -|---|---| -| BABY | 0 ≤ age < 2 | -| YOUNG_CHILD | 2 ≤ age < 5 | -| CHILD | 5 ≤ age < 12 | -| ADULT | 12 ≤ age | -| 无 birthday | → ADULT（兜底） | - -> 规则由管理端「字典管理 → traveler_type_age_rule」配置，后端缓存到 Redis `cache:dict:data:traveler_type_age_rule`，改动后自动生效。 - -## 兼容性 - -- **非 breaking**：旧前端仍带 `travelerType` 不会报错，字段被静默忽略。 -- 下单路径 `MpOrderTravelerSaveReqVO` **暂不涉及**（仍接受 `travelerType`），只改「常用出行人」页的 `MpTravelerRequest`。 - -## 相关 - -- 后端 PR: https://git.1814.love:8443/wx/HL/pulls/1197 -- 工单: https://git.1814.love:8443/wx/HL/issues/1196 diff --git a/changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md b/changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md deleted file mode 100644 index e6a3290..0000000 --- a/changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md +++ /dev/null @@ -1,68 +0,0 @@ -# 资源管理端 Map→VO 类型化（批次 1） - -**PR**: [#1201](https://git.1814.love:8443/wx/HL/pulls/1201) | **合并时间**: 2026-04-22 19:27 - -## 背景 - -`hl-resource-service` 代码规范批次 1 整改，把管理端 Controller 返 `Map<String,Object>` 全部改成强类型 RespVO。**字段名与原 Map key 完全一致**，前端 `.data.xxxId`/`.data.name` 读法不变，但 TypeScript 类型定义可以升级到具体 VO。 - -## 影响的管理端接口 - -| 端点 | 旧返回 | 新返回 | 字段对齐 | -|------|-------|-------|---------| -| `GET /admin/hotel/list-all-simple` | `Result<List<Map>>` | `Result<List<HotelSimpleRespVO>>` | `hotelId: Long, hotelName: string` | -| `POST /admin/hotel/{id}/submit-approval` | `Result<Map<String,String>>` | `Result<ApprovalSubmitRespVO>` | `approvalId: string, status: string` | -| `POST /admin/hotel/room-type/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/scenic/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/restaurant/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/activity/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/service/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/vehicle/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/staff/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `POST /admin/supplies/{id}/submit-approval` | 同上 | 同上 | 同上 | -| `GET /admin/material/export` | `Result<List<Map<String,String>>>` | `Result<List<MaterialExportRespVO>>` | 字段名完全保留 | - -## 前端改动建议 - -**TypeScript 类型升级**（可选，字段名无变化）： - -```typescript -// Before -interface HotelSimpleItem { - hotelId: string; // 或 number - hotelName: string; -} - -// After (对齐后端 HotelSimpleRespVO) -interface HotelSimpleRespVO { - hotelId: number; // Long - hotelName: string; -} - -// submitApproval 响应 -interface ApprovalSubmitRespVO { - approvalId: string; - status: string; -} -``` - -**渲染代码无需改动**：`response.data.hotelId` / `response.data.approvalId` 依然可用。 - -## 校验增强（@Valid） - -20 处 `/admin/**` 和 `/internal/**` 的 `@RequestBody` 接口补了 `@Valid`。以下 internal 端点如果前端曾绕过网关直连调用（不推荐），会因为校验失败返回 400： - -- `POST /internal/{resource}/approval-result`（需 `ApprovalResultDTO.spNo/spStatus` 非空） -- `POST /internal/resource/price/{resource}`（需 `PriceQuery` 必填字段） -- `POST /admin/material/category/permissions`（需 `materialIds` 非空） - -**前端实际调用都走网关 + 全字段传参，不受影响**。 - -## 无需前端改动的范围 - -- Mapper / Service 层重构（48 Mapper 升级 BaseMapperX、Wrapper 下沉到 default 方法） -- 4 个新增聚合 Service（ResourcePriceQueryService 等，仅改内部实现） - -## 相关后端 changelog - -详细后端契约变更见 [`hl-backend-changelog/2026-04/2026-04-22_resource-service-rules-refactor-batch1.md`](../../../hl-backend-changelog/changelogs/2026-04/2026-04-22_resource-service-rules-refactor-batch1.md)。 diff --git a/changelogs/2026-04/2026-04-22_topic-status-string-enum-migration.md b/changelogs/2026-04/2026-04-22_topic-status-string-enum-migration.md deleted file mode 100644 index 5174372..0000000 --- a/changelogs/2026-04/2026-04-22_topic-status-string-enum-migration.md +++ /dev/null @@ -1,72 +0,0 @@ -# 管理端 Topic status 字段从 Integer 改为 String 枚举 - -- **日期**: 2026-04-22 -- **PR**: #1156 -- **工单**: #1154 -- **DDL**: 测试服已执行迁移脚本 -- **影响**: 管理端专题模块 - -## 变更概要 - -Topic（专题）模块 `status` 字段由 `Integer`（0/1）改为 `String` 枚举（`ONLINE` / `OFFLINE`），对齐项目状态字段规范。 - -## 接口影响 - -### 1. 管理端专题列表查询 `GET /admin/topic/list` - -**变更前**： -``` -?status=1 // 上线 -?status=0 // 下线 -``` - -**变更后**： -``` -?status=ONLINE // 上线 -?status=OFFLINE // 下线 -``` - -### 2. 管理端专题创建 / 更新 `POST /admin/topic/save` / `PUT /admin/topic/{id}` - -请求 body 中 `status` 字段： - -**变更前**： -```json -{ "status": 1 } -``` - -**变更后**： -```json -{ "status": "ONLINE" } -``` - -校验规则：`@Pattern("^(ONLINE|OFFLINE)$")`，不传入该枚举值会返回参数校验错误。 - -### 3. 所有返回 TopicVO 的接口（管理端 + C 端） - -返回 body 中 `status` 字段： - -**变更前**： -```json -{ "status": 1 } -``` - -**变更后**： -```json -{ "status": "ONLINE" } -``` - -## 前端需同步 - -1. **下拉字典切换**：管理端 topic 的 status 下拉/筛选从通用字典 `common_status`（0=禁用 / 1=启用）切换到专用字典 `topic_status`（ONLINE=上线 / OFFLINE=下线） -2. **所有传 status 的表单/筛选**：传值从 `1/0` 改为 `"ONLINE"/"OFFLINE"` -3. **所有读 status 的列表/详情**：显示逻辑从判 `status===1` 改为判 `status==='ONLINE'` - -## 字段 `createdAt` 保持不变 - -为降低前端改动，TopicVO 的 `createdAt` 字段名保留不变（后端内部已从 `getCreatedAt` 改为 `getCreateTime` 读取，返回值仍是 ISO 时间字符串，业务语义和格式完全不变）。 - -## 非破坏性说明 - -- 已有逻辑只需按上述同步改 status 枚举值，无其他改动 -- 后端已部署，测试服已迁移 DB，可直接联调 diff --git a/changelogs/2026-04/2026-04-23_admin-order-transport.md b/changelogs/2026-04/2026-04-23_admin-order-transport.md deleted file mode 100644 index 03c040f..0000000 --- a/changelogs/2026-04/2026-04-23_admin-order-transport.md +++ /dev/null @@ -1,386 +0,0 @@ -# 管理后台 · 订单交通信息（接送站）5 个 CRUD + 飞常准查询 7 个 - -**日期**：2026-04-23 -**影响**：**管理后台** 订单详情·行程安排·交通信息（接送站）板块 -**PR**：#1285（/transport 路径别名） -**关联 Issue**：#1284（404 修复） - ---- - -## 概述 - -统一管理后台「交通信息」板块的接口契约。**管理后台前端之前对接的是一份已废弃的 v1 小程序契约**（`legType / departureStation / travelDate / ...`），和后端现有新契约（`direction / departStation / departTime + arriveTime / ...`）完全不匹配，导致： - -1. `POST /admin/order/{orderId}/transport` **404**（#1285 已修：Controller 同时支持 `/transport` 和 `/arrival` 两个前缀） -2. 字段反序列化不上 → **400 `方向不能为空`、`出行人列表不能为空`** - -本次梳理：管理后台前端请**完全对齐小程序端 `/mp/order/{orderId}/arrival` 的 DTO 结构**（字段名、必填规则都一样，仅路径前缀不同）。同时后端已开放 `/admin/transport/*` 共 7 个飞常准查询接口，供前端自动补全航班/车次时刻。 - ---- - -## 一、订单交通批次 5 个 CRUD - -### 基础信息 - -- **鉴权**：Admin Bearer token -- **创建者**：`creatorType=ADMIN`（定制师代录；C 端小程序同样接口 `creatorType=USER`） -- **DTO**：后端 `ArrivalPlanSaveReqVO`（和小程序 `MpArrivalPlanSaveReqVO` 完全一致，字段名一一对应） - -### 路径表 - -**URL 支持两个前缀别名（PR #1285）**，任选其一，推荐 `/transport`（与 DB 表 `order_transport_plan` 对齐）： - -| 功能 | 方法 | 路径 | -|---|---|---| -| 查全量批次 | GET | `/admin/order/{orderId}/transport` 或 `/admin/order/{orderId}/arrival` | -| 新增单批次 | POST | `/admin/order/{orderId}/transport` 或 `/admin/order/{orderId}/arrival` | -| 全量替换（多批次一次性提交） | POST | `/admin/order/{orderId}/transport/batch` 或 `/admin/order/{orderId}/arrival/batch` | -| 修改单批次 | PUT | `/admin/order/{orderId}/transport/plan/{planId}` 或 `/admin/order/{orderId}/arrival/plan/{planId}` | -| 删除单批次 | DELETE | `/admin/order/{orderId}/transport/plan/{planId}` 或 `/admin/order/{orderId}/arrival/plan/{planId}` | - ---- - -### 1. 查全量批次 - -``` -GET /admin/order/{orderId}/transport -``` - -#### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -#### 出参 `Result<ArrivalListRespVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| orderId | Long | 订单ID | -| arrivals | `List<ArrivalPlanRespVO>` | 到达批次（接站） | -| departures | `List<ArrivalPlanRespVO>` | 离开批次（送站） | - -`ArrivalPlanRespVO` 字段结构见第 2 节出参。 - ---- - -### 2. 新增单批次 - -``` -POST /admin/order/{orderId}/transport -``` - -**创建者类型**：`creatorType=ADMIN`。 - -#### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -**Body `ArrivalPlanSaveReqVO`**（完整字段表）： - -| 字段 | 类型 | 必填规则 | 约束 | 说明 | -|---|---|---|---|---| -| **direction** | String | ✅ 始终必填 | - | 方向。`ARRIVAL`=到达/接站；`DEPARTURE`=离开/送站。字典 `transport_direction` | -| **transportType** | String | ✅ 始终必填 | - | 交通方式。`FLIGHT`=飞机，`TRAIN`=火车，`SELF_DRIVE`=自驾。字典 `transport_type`（本模块子集） | -| transportNo | String | FLIGHT/TRAIN 必填；SELF_DRIVE 不填 | ≤32 | 航班号/车次号，如 `CA1234` / `G71` | -| carrier | String | 可选 | ≤64 | 航司/铁路公司，如 `中国国航` | -| departStation | String | DEPARTURE+FLIGHT/TRAIN 必填；其他场景可选 | ≤64 | 出发站/机场 | -| arriveStation | String | ARRIVAL+FLIGHT/TRAIN 必填；其他场景可选 | ≤64 | 到达站/机场 | -| departTime | LocalDateTime | DEPARTURE+FLIGHT/TRAIN 必填；其他场景可选 | - | 出发时间，`yyyy-MM-dd HH:mm:ss` | -| arriveTime | LocalDateTime | ARRIVAL+FLIGHT/TRAIN 必填；其他场景可选 | - | 到达时间，`yyyy-MM-dd HH:mm:ss` | -| selfDrivePeriod | String | SELF_DRIVE 必填 | - | 自驾时段：`MORNING` / `AFTERNOON` / `EVENING`。字典 `self_drive_period` | -| selfDriveEta | LocalDateTime | 可选 | - | 自驾预计到达精确时间 | -| remark | String | 可选 | ≤255 | 用户备注 | -| **travelerIds** | `List<Long>` | ✅ 始终非空 | 至少 1 人 | 本批次涉及的出行人 ID 列表；每个 ID **必须属于本订单** | - -> ⚠️ **字段间联动**：字段必填规则由 Service 层按 `transportType + direction` 组合校验，不是单注解表达式。前端请按上表规则做前置校验，否则会 500。 - -#### 出参 `Result<ArrivalPlanRespVO>` - -| 字段 | 类型 | 说明 | -|---|---|---| -| planId | Long | 批次ID | -| orderId | Long | 订单ID | -| direction | String | 方向 | -| directionLabel | String | 方向中文标签 | -| transportType | String | 交通方式 | -| transportTypeLabel | String | 交通方式中文标签 | -| transportNo | String | 航班号/车次号 | -| carrier | String | 航司/铁路公司 | -| departStation | String | 出发站 | -| arriveStation | String | 到达站 | -| departTime | LocalDateTime | 出发时间 | -| arriveTime | LocalDateTime | 到达时间 | -| selfDrivePeriod | String | 自驾时段 | -| selfDrivePeriodLabel | String | 自驾时段中文标签 | -| selfDriveEta | LocalDateTime | 自驾预计到达 | -| remark | String | 备注 | -| creatorType | String | `USER` / `ADMIN` | -| createTime | LocalDateTime | 创建时间 | -| travelers | `List<ArrivalPlanTravelerSimpleVO>` | 本批次涉及的出行人 | - -**`ArrivalPlanTravelerSimpleVO`**： - -| 字段 | 类型 | 说明 | -|---|---|---| -| travelerId | Long | 出行人 ID | -| name | String | 姓名 | -| travelerType | String | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | - -#### 请求示例（接站 ARRIVAL） - -```json -{ - "direction": "ARRIVAL", - "transportType": "FLIGHT", - "transportNo": "CA1234", - "carrier": "中国国航", - "departStation": "上海虹桥T2", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "remark": "带小孩,需要婴儿座椅", - "travelerIds": [10001, 10002] -} -``` - -#### 请求示例（送站 DEPARTURE） - -```json -{ - "direction": "DEPARTURE", - "transportType": "FLIGHT", - "transportNo": "CA5678", - "carrier": "中国国航", - "departStation": "海拉尔东山", - "arriveStation": "上海虹桥T2", - "departTime": "2026-07-15 14:00:00", - "arriveTime": "2026-07-15 17:00:00", - "travelerIds": [10001, 10002] -} -``` - -#### 请求示例（自驾 SELF_DRIVE） - -```json -{ - "direction": "ARRIVAL", - "transportType": "SELF_DRIVE", - "selfDrivePeriod": "AFTERNOON", - "selfDriveEta": "2026-07-10 15:30:00", - "remark": "自驾从漠河过来", - "travelerIds": [10001] -} -``` - ---- - -### 3. 全量替换（多批次一次性提交） - -``` -POST /admin/order/{orderId}/transport/batch -``` - -先软删当前所有批次，再按请求体批量创建。空数组 `[]` = 清空订单全部交通批次。 - -#### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | - -Body：`List<ArrivalPlanSaveReqVO>`（每项结构同第 2 节）。 - -#### 出参 - -`Result<ArrivalListRespVO>`，结构同第 1 节。 - -#### 使用场景 - -管理后台「一次性代录全部交通」按钮。例如定制师拿到客户的去程和回程航班信息，一次性把 2 条（或多条，如一家分两批）全部提交。 - ---- - -### 4. 修改单批次 - -``` -PUT /admin/order/{orderId}/transport/plan/{planId} -``` - -**覆盖语义**：按字段全量覆盖，包括 `travelerIds`（替换旧关联）。 - -#### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | -| planId | Path | Long | ✅ | - -Body：`ArrivalPlanSaveReqVO`（结构同第 2 节）。 - -#### 出参 - -`Result<ArrivalPlanRespVO>`。 - ---- - -### 5. 删除单批次 - -``` -DELETE /admin/order/{orderId}/transport/plan/{planId} -``` - -**级联**：软删关联的出行人绑定行。 - -#### 入参 - -| 参数 | 位置 | 类型 | 必填 | -|---|---|---|---| -| orderId | Path | Long | ✅ | -| planId | Path | Long | ✅ | - -#### 出参 - -`Result<Void>`。 - ---- - -## 二、航班/火车查询 7 个（`/admin/transport/*`） - -数据源：飞常准官方 API，`resource-service` 侧做 Redis 缓存后透传。与小程序端 `/mp/transport/*` **底层共享同一批数据**。 - -**用途**：前端表单里用户输入航班号后，后端返回精确的起飞/到达时间、机场/航站楼等，**前端自动回填 `departTime / arriveTime / departStation / arriveStation`**，用户不必手动填时分秒。 - -### 路径表 - -| 功能 | 路径 | 核心入参 | -|---|---|---| -| 按航班号查航班 | `GET /admin/transport/flight/by-flight-no` | `flightNo`、`date` | -| 按机场三字码查航班 | `GET /admin/transport/flight/by-airport` | `dep`、`arr`、`date` | -| 按城市三字码查航班 | `GET /admin/transport/flight/by-city` | `depCity`、`arrCity`、`date` | -| 按车次号查火车（含经停站） | `GET /admin/transport/train/by-train-no` | `trainNo`、`date` | -| 按车次+出发/到达站查火车 | `GET /admin/transport/train/by-train-no-stations` | `trainNo`、`dep`、`arr`、`date` | -| 按出发/到达站查火车 | `GET /admin/transport/train/by-station` | `dep`、`arr`、`date` | -| 按出发/到达城市查火车 | `GET /admin/transport/train/by-city` | `depCity`、`arrCity`、`date` | - -> ⚠️ 注意：admin 端路径风格和 mp 端**略有差异**（admin 端按航班号的叫 `/flight/by-flight-no`，mp 端叫 `/flight`；按车次号的叫 `/train/by-train-no`，mp 端叫 `/train`）。其他 5 个路径完全一致。 - -### 航班返回 `FlightVO` 字段 - -| 字段 | 类型 | 说明 | -|---|---|---| -| flightNo | String | 航班号 | -| airline | String | 航空公司名称 | -| category | String | `国内` / `国际` / `地区` | -| departAirportCode | String | 出发机场三字码 | -| arriveAirportCode | String | 到达机场三字码 | -| departAirport | String | 出发机场名称 | -| arriveAirport | String | 到达机场名称 | -| departCity | String | 出发城市 | -| arriveCity | String | 到达城市 | -| planDepartTime | String | 计划起飞时间 | -| planArriveTime | String | 计划到达时间 | -| actualDepartTime | String | 实际起飞时间（未起飞为 null） | -| actualArriveTime | String | 实际到达时间（未到达为 null） | -| status | String | `计划` / `起飞` / `到达` / `延误` / `取消` / `返航` / `备降` 等 | -| stopFlag | String | `0`=不经停，`1`=经停 1 次，`n`=经停 n 次 | -| shareFlag | String | `0`=否，`1`=是（共享航班） | -| shareFlightNo | String | 共享航班号 | -| departTerminal | String | 出发航站楼 | -| arriveTerminal | String | 到达航站楼 | -| boardGate | String | 登机口 | -| arriveExit | String | 到达出口 | -| departTimezone | String | 出发时区偏移（秒） | -| arriveTimezone | String | 到达时区偏移（秒） | - -### 火车返回 `TrainVO` 字段 - -| 字段 | 类型 | 说明 | -|---|---|---| -| trainNo | String | 车次 | -| departStation | String | 出发车站 | -| arriveStation | String | 到达车站 | -| shutdown | String | `0`=否，`1`=停运 | -| planDepartTime | String | 计划出发时间 | -| planArriveTime | String | 计划到达时间 | -| estimatedDepartTime | String | 预计出发时间（仅 `by-train-no-stations` 返回） | -| estimatedArriveTime | String | 预计到达时间（仅 `by-train-no-stations` 返回） | -| actualDepartTime | String | 实际出发时间（仅 `by-train-no-stations` 返回） | -| actualArriveTime | String | 实际到达时间（仅 `by-train-no-stations` 返回） | -| departStatus | String | 出发状态：`计划`/`正点`/`晚点`/`出发`（仅 `by-train-no-stations`） | -| arriveStatus | String | 到达状态：`计划`/`正点`/`晚点`/`到达`（仅 `by-train-no-stations`） | -| duration | Integer | 运行时长（分钟） | -| stops | `List<TrainStopVO>` | 经停站列表（仅 `by-train-no` 返回） | - -**`TrainStopVO`**： - -| 字段 | 类型 | 说明 | -|---|---|---| -| stationName | String | 车站名称 | -| arriveTime | String | 到站时间 | -| departTime | String | 发车时间 | - -### 边界 - -- 查不到数据（航班号无效/停运）：返回 `data: []` -- 飞常准上游异常/超时：500，`message` 含上游错误码 -- 日期格式：`yyyy-MM-dd`，格式错误返回 500 -- 所有三字码不区分大小写（内部 `toUpperCase`） - ---- - -## 三、字典依赖 - -| 字典类型 | 值 | -|---|---| -| `transport_direction` | `ARRIVAL` / `DEPARTURE` | -| `transport_type` | `FLIGHT` / `TRAIN` / `SELF_DRIVE`（本模块子集） | -| `self_drive_period` | `MORNING` / `AFTERNOON` / `EVENING` | -| `creator_type` | `USER` / `ADMIN` | -| `traveler_type` | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | - -所有 `xxxLabel` 字段由后端透传中文展示值，前端无需再次映射。 - ---- - -## 四、前端迁移指南（重要 ⚠️） - -### 字段改名对照表 - -管理后台前端**之前在用 v1 小程序遗留契约**，请按下表迁移： - -| 旧契约（v1 遗留） | 新契约（当前） | 说明 | -|---|---|---| -| `legType` (`OUTBOUND` / `RETURN`) | **`direction`** (`ARRIVAL` / `DEPARTURE`) | **字段名+值域都变了**。`OUTBOUND` 去程=客户到达目的地 → `ARRIVAL`；`RETURN` 回程=客户从目的地离开 → `DEPARTURE` | -| `departureStation` | **`departStation`** | 去掉 `ure` 词尾 | -| `arrivalStation` | **`arriveStation`** | 去掉 `al` 词尾 | -| `travelDate`（一个日期） | **`departTime` + `arriveTime`**（两个 LocalDateTime） | 拆成出发时间和到达时间，两者都要有时分秒 | -| 缺失 | **`travelerIds`（必填）** | 新增必填字段，至少 1 人，必须属于本订单 | - -### 推荐 UX - -用户填写交通信息时： - -1. **方向**：单选 `接站 (ARRIVAL)` / `送站 (DEPARTURE)` -2. **交通方式**：单选 `飞机 (FLIGHT)` / `火车 (TRAIN)` / `自驾 (SELF_DRIVE)` -3. **航班号/车次号**：输入后立即调 `GET /admin/transport/flight/by-flight-no` 或 `GET /admin/transport/train/by-train-no` -4. 从返回列表让用户选具体班次，**自动回填** `departStation / arriveStation / departTime / arriveTime / carrier` -5. 自驾场景：改为输入 `selfDrivePeriod` + 可选 `selfDriveEta` -6. **出行人选择**：多选框，默认全选订单所有出行人（用户可取消部分），最少 1 人 -7. 提交时按上表 DTO 校验格式 - -### 参考实现 - -小程序端已上线该 UI，表单交互和字段校验可**直接参考 `MpArrivalController` 的使用**（changelog: `2026-04-21_mp-order-arrival.md`）。唯一差别是路径前缀 `/admin` 和 `creatorType=ADMIN`。 - ---- - -## 五、关联 PR 与历史 - -- #1285（本次）：Controller 同时支持 `/transport` 和 `/arrival` 两个前缀别名。修 404。 -- #1262（2026-04-23）：配房差价 execute 自动写 `order_surcharge` / `order_discount`（source=ROOM_UPGRADE），与本模块无关但同日相邻。 -- 2026-04-21 MP 端 `/mp/order/{orderId}/arrival` 已上线，DTO 结构与本次 admin 端一致。 - -**待废弃**：`MpOrderTransportController`（`/mp/order/{orderId}/transport`，v1 遗留）已标 `@Deprecated`，请**不要再参考它的字段命名**。管理后台前端之前误以此为契约，本次必须迁移。 diff --git a/changelogs/2026-04/2026-04-23_admin-ui_hotel-assignment-render-fix.md b/changelogs/2026-04/2026-04-23_admin-ui_hotel-assignment-render-fix.md deleted file mode 100644 index a76a53a..0000000 --- a/changelogs/2026-04/2026-04-23_admin-ui_hotel-assignment-render-fix.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -date: 2026-04-23 -type: fix-guidance -scope: hl-ui (admin 订单详情) -pr: "无后端 PR (纯前端渲染问题)" -issue: "无(前端直接修)" -breaking: false -audience: [hl-ui] ---- - -# admin 订单详情 · 房间安排区域两处渲染 BUG 修正指引(后端零改动) - -## 背景 - -用户反馈订单详情 → 行程安排 → 房间安排 两处不对: - -1. **编辑回显失效**:点「编辑」打开配房弹窗,现有已配数据不预填,等于从零配。 -2. **日期列显示「-」**:表格「日期」列应显示真实入住日期,现在渲染成 `-`。 - -后端 API 已具备正确数据,属前端渲染绑错字段/未调回显接口。**后端不做改动**,本文档只给前端改动指引。 - -## 问题 1:编辑弹窗不回显 - -### 根因 - -前端编辑弹窗打开时未调 GET 拉当前已配数据,直接开空表单。 - -### 正确做法 - -弹窗打开的 `onMounted` / `open()` 钩子里调: - -```http -GET /admin/order/{orderId}/hotel-assignment -Authorization: Bearer {token} -``` - -**响应**(已上线,PR #1049 起): - -```json -{ - "code": 200, - "data": [ - { - "assignmentId": "2047139323009990657", - "orderId": "2046864526866886657", - "familyIndex": 1, - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": "3002000000000000013", - "roomType": "大床房", - "dayNumber": 4, - "assignmentDate": "2026-04-27", - "upgradePrice": null, - "remark": "bug1257-execute" - } - ] -} -``` - -按 `(familyIndex, dayNumber)` 预填编辑表格即可。空数组代表尚未配过,弹窗走空态。 - -## 问题 2:日期列显示「-」 - -### 根因 - -前端列表绑的是 `OrderDetailVO.hotelAssignments` —— **这是 Entity 原始 JSON 字符串**(为兼容 V1 保留),**不含 `assignmentDate` 字段**,所以日期列恒为空。 - -### 正确做法 - -改绑 `OrderDetailVO.hotelAssignmentDetails`(已结构化 + 含计算好的日期): - -```js -// ❌ 错误(老 V1 兼容字段,无日期) -const list = JSON.parse(orderDetail.hotelAssignments || '[]') - -// ✅ 正确(结构化列表,含 assignmentDate) -const list = orderDetail.hotelAssignmentDetails || [] -``` - -字段对照: - -| 展示列 | 取字段 | -|--------|--------| -| 家庭 | `familyIndex` | -| 日期 | `assignmentDate`(YYYY-MM-DD) | -| 酒店 | `hotelName` | -| 房型 | `roomType` | -| 备注 | `remark` | - -`assignmentDate` 由后端按 `order.departureDate + dayNumber - 1` 现算,前端直接展示即可。 - -## 相关字段来源 - -`OrderDetailVO` 内两个字段并存(`hl-order-service-v2`): - -```java -@ApiModelProperty("酒店分配信息JSON（原始数据，V1 兼容，不建议新代码使用）") -private String hotelAssignments; - -@ApiModelProperty("酒店分配详情列表（含酒店名/房型/入住日期等结构化数据，推荐使用）") -private List<HotelAssignmentDetailVO> hotelAssignmentDetails; -``` - -**以后所有新代码统一走 `hotelAssignmentDetails`**。`hotelAssignments` 字段保留但标记为 V1 兼容字段,后续不再扩展新字段。 - -## 验证 - -### 测试服订单 - -`2046864526866886657`(HL20260422161146-2849,南线经典 5 天 4 晚,2026-04-24 出发) - -当前 DB 状态(PR #1262 测试残留,实际业务测试时可重新配房): - -| day | hotelName | roomType | assignmentDate | -|-----|-----------|----------|---------------:| -| 4 | 呼伦贝尔香格里拉大酒店 | 大床房 | 2026-04-27 | - -### 验收清单 - -- [ ] 打开订单 `2046864526866886657` 详情 → 行程安排 → 房间安排表格,日期列显示 `2026-04-27`(不是 `-`) -- [ ] 点「编辑」按钮 → 弹窗自动预填 `家庭1 / 第4天 / 呼伦贝尔香格里拉大酒店 / 大床房` -- [ ] 空态订单(从未配房)→ 弹窗打开为空表单,不报错 -- [ ] 改完提交 → 刷新详情页,列表正确显示新数据 + 日期 - -## 相关 - -- 后端接口(现有,无改动):`GET /admin/order/{orderId}/hotel-assignment` -- 后端字段(现有,无改动):`OrderDetailVO.hotelAssignmentDetails[]` -- 前置历史:PR #1049(字段 `assignmentDate` → `dayNumber` 迁移,Service 层现算日期回填 VO) -- 后端 PR 关联:PR #1250(配房差价预览 3 BUG 修复)/ #1262(差价 execute 联动费用项) diff --git a/changelogs/2026-04/2026-04-23_admin-unified-pricing-calendar.md b/changelogs/2026-04/2026-04-23_admin-unified-pricing-calendar.md deleted file mode 100644 index e6806ec..0000000 --- a/changelogs/2026-04/2026-04-23_admin-unified-pricing-calendar.md +++ /dev/null @@ -1,166 +0,0 @@ -# 统一价格日历接口 /admin/product/item/{id}/pricing-calendar - -**日期**: 2026-04-23 -**PR**: #1290 (Closes #1286) -**服务**: hl-product-service-v2 -**类型**: feat（新增接口，零破坏性） - ---- - -## 背景 - -之前 admin 查价格日历需要分场景调两个不同接口： -- CORE/CUSTOM → `GET /admin/product/item/{id}/price-calendar` -- GROUP（小蒙马） → `GET /admin/product/item/{id}/schedule/list` - -**根因**：GROUP 定价真相源是 `group_tour_batch.adult_price`（班期表），不走 `product_price_calendar`。前端要按 `productType` 分流调用。 - -本次新增**统一入口**，后端按 productType 聚合两种数据源，前端一个接口搞定。 - ---- - -## 新接口 - -### `GET /admin/product/item/{id}/pricing-calendar` - -**Query 参数** -- `month`（可选）：`yyyy-MM`，过滤月份。不传返全部 -- `tierSeq`（可选）：档位序号，**仅 CORE/CUSTOM 生效**，GROUP 忽略 - -**响应** -```json -{ - "code": 200, - "data": { - "productType": "CORE | GROUP | CUSTOM", - "items": [ - { ... 统一条目 VO ... } - ] - } -} -``` - -### 统一条目 VO 字段表 - -| 字段 | 类型 | CORE/CUSTOM | GROUP | -|------|------|-------------|-------| -| **通用** | -| `date` | LocalDate | 每日价格日 | 出发日（departureDate）| -| `adultPrice` | BigDecimal | adultSellPrice | adultPrice | -| `childPrice` | BigDecimal | childSellPrice | childPrice | -| `toddlerDiscount` | BigDecimal | ✅ | ✅ | -| `infantPrice` | BigDecimal | ✅ | ✅ | -| `stock` | Integer | dailyStock | productStockLimit（无则 maxParticipants）| -| `sold` | Integer | sold | enrolledCount | -| `sellable` | Boolean | dailyStock 空或 sold<stock | batchStatus∈{ENROLLING,NEARLY_FULL} | -| **CORE/CUSTOM 专属** | -| `id` | Long | 日历记录主键 | null | -| `tierSeq` | Integer | 档位序号 | null | -| `priceType` | String | NORMAL/PEAK/HOLIDAY/SPECIAL | null | -| `rangeId` | Long | 批量区间标识 | null | -| **GROUP 专属** | -| `batchId` | Long | null | 班期ID | -| `batchNo` | String | null | 班期编号 | -| `batchName` | String | null | 班期名称 | -| `batchStatus` | String | null | ENROLLING/NEARLY_FULL/FULL/FINISHED/CANCELLING/CANCELLED | -| `endDate` | LocalDate | null | 班期结束日 | -| `enrollmentDeadline` | LocalDate | null | 报名截止日 | -| `maxRooms` | Integer | null | 总房间数 | -| `bookedRooms` | Integer | null | 已预订房间数 | - ---- - -## 前端渲染建议 - -```javascript -const resp = await api.getUnifiedPricingCalendar(productId, { month, tierSeq }); -switch (resp.data.productType) { - case 'CORE': - case 'CUSTOM': - // 矩阵日历: 按 tierSeq × date 渲染档位 × 日期表格 - renderMatrixCalendar(resp.data.items); - break; - case 'GROUP': - // 列表日历: 按出发日渲染班期卡片，显示 batchName/batchStatus/endDate - renderBatchCalendar(resp.data.items); - break; -} -``` - ---- - -## 示例 - -### CORE 响应 -```json -{ - "productType": "CORE", - "items": [ - { - "date": "2026-05-01", - "adultPrice": 1999.00, - "childPrice": 999.00, - "id": 1780000000000000001, - "tierSeq": 1, - "priceType": "NORMAL", - "stock": 50, - "sold": 10, - "sellable": true, - "batchId": null - } - ] -} -``` - -### GROUP 响应 -```json -{ - "productType": "GROUP", - "items": [ - { - "date": "2026-07-06", - "adultPrice": 4580.00, - "childPrice": 2290.00, - "batchId": 2043697199761584129, - "batchNo": "Q202607062043697199757389826", - "batchName": "7月暑期团", - "batchStatus": "ENROLLING", - "endDate": "2026-07-10", - "stock": 25, - "sold": 0, - "sellable": true, - "tierSeq": null, - "priceType": null - } - ] -} -``` - ---- - -## 向后兼容 - -✅ **老接口保持不变**： -- `GET /admin/product/item/{id}/price-calendar` — 不动 -- `GET /admin/product/item/{id}/schedule/list` — 不动 - -前端可**逐步迁移**到新接口，无需一次性全量改造。 - ---- - -## 验证 - -测试服网关 7 场景全过： -- CORE 全量 → 92 条 tierSeq/priceType 齐 ✅ -- GROUP 全量 → 4 条班期 batchId/batchStatus/endDate 齐 ✅ -- CUSTOM → 62 条走 CORE 分支 ✅ -- CORE/GROUP ?month=2026-05 → 正确过滤 ✅ -- CORE ?tierSeq=1 → 从 92 条过滤到 79 条 ✅ -- 老接口 /price-calendar → 92 条不变零回归 ✅ - ---- - -## 部署 - -测试服已部署: task `a1ca3b50` success。 -正式环境上线前**无需任何 DDL**，纯接口聚合。 diff --git a/changelogs/2026-04/2026-04-23_equipment-item-icon-color.md b/changelogs/2026-04/2026-04-23_equipment-item-icon-color.md deleted file mode 100644 index f0b5c34..0000000 --- a/changelogs/2026-04/2026-04-23_equipment-item-icon-color.md +++ /dev/null @@ -1,138 +0,0 @@ -# 装备建议条目 EquipmentItem 补 icon + color 字段 - -**日期**: 2026-04-23 -**PR**: #1273 (Closes #1272) -**服务**: hl-product-service-v2 / hl-order-service-v2 / hl-mp-service -**类型**: feat（新增字段，向后兼容） - ---- - -## 背景 - -PR #1259 上线后前端实现装备建议条目 UI，发现需要后端结构化传图标标识和颜色，不希望纯靠前端按 text 关键词猜图标。本次补字段。 - ---- - -## 字段扩展 - -### EquipmentItem 结构 - -```typescript -interface EquipmentItem { - text: string; // 必填，1-50 字 - icon?: string; // 可选，图标 key，≤64 字 - color?: string; // 可选，颜色值，≤16 字（建议 #RRGGBB） -} -``` - -### 约束总表（JSR-303 现已生效） - -| 字段 | 必填 | 长度 | 错误消息 | -|------|------|------|----------| -| text | ✅ | 1-50 字 | `equipmentList[N].text: 装备文案不能为空` / `装备文案长度需在 1-50 字符之间` | -| icon | ❌ | ≤64 字 | `equipmentList[N].icon: 图标标识长度不能超过 64 字符` | -| color | ❌ | ≤16 字 | `equipmentList[N].color: 颜色值长度不能超过 16 字符` | - -**color 格式**：后端不硬校验 `#RRGGBB` 格式，前端可传任意 ≤16 字符串（如 `red` / `#FFA726` / `rgb(255,167,38)`）。推荐 `#RRGGBB` 以便 admin/mp 渲染一致。 - ---- - -## 影响接口（5 处响应 + 1 处请求） - -| 接口 | 变化 | -|------|------| -| `PUT /admin/product/item/{id}/supplement` | 请求 `equipmentList[].icon` / `[].color` 可选 | -| `GET /admin/product/item/{id}` | 响应 `supplement.equipmentList[].icon/color` 新增 | -| `GET /mp/product/{id}` | 响应 `equipmentList[].icon/color` 新增 | -| `GET /mp/order/{id}` | 响应 `equipmentList[].icon/color` 新增（订单快照固化） | -| `GET /mp/order/{orderId}/supplies-checklist` | 响应 `equipmentList[].icon/color` 新增 | - ---- - -## 示例 - -### 保存（带图标和颜色） - -```http -PUT /admin/product/item/123/supplement -{ - "equipmentList": [ - {"text": "防晒霜 SPF50+", "icon": "sunscreen", "color": "#FFA726"}, - {"text": "长袖防晒衣", "icon": "shirt"}, - {"text": "运动鞋"} - ] -} -→ 200 {"code":200, "success":true} -``` - -### MP 详情回显 - -```json -{ - "equipmentList": [ - {"text":"防晒霜 SPF50+", "icon":"sunscreen", "color":"#FFA726"}, - {"text":"长袖防晒衣", "icon":"shirt", "color":null}, - {"text":"运动鞋", "icon":null, "color":null} - ] -} -``` - -### 超限 400 - -```http -PUT .../supplement -{"equipmentList":[{"text":"x","icon":"aaaa...(65字)"}]} -→ 400 {"code":400, "message":"equipmentList[0].icon: 图标标识长度不能超过 64 字符"} -``` - ---- - -## 前端适配建议 - -### 1. icon 字段 -**推荐约定**：前后端商量一份 iconKey 表（如 `sunscreen/shirt/jacket/shoe/bug/hat/sunglasses/water-bottle/umbrella/camera/headlamp/...`），前端内置图标库按 iconKey 查表渲染。 - -**降级逻辑**： -- icon 有值 → 前端按 key 查图标库渲染 -- icon 为 null → 前端按 text 关键词硬匹配图标（PR #1259 方案） -- 都没匹配上 → 显示默认占位图标 - -### 2. color 字段 -- color 有值 → 应用到图标颜色/文字颜色/背景色等 -- color 为 null → 使用主题默认色 - -### 3. admin 编辑器 -- 图标选择：内置 iconKey 下拉选择器（下拉源是前端约定的图标库） -- 颜色选择：内置色板选择器（el-color-picker 等） -- 两字段都可留空（提交时对应字段不传或传 null） - ---- - -## 向后兼容 - -- 现有调用方不传 icon/color：后端接受，DB 存 JSON 不含这两个键 -- 老订单快照：JSON 内条目没有 icon/color 键 → 反序列化后 EquipmentItem.icon/color = null -- **前端可直接升级，旧数据 null 兼容性零风险** - ---- - -## 验证 - -测试服网关已 curl 6 场景全过： -- 混合保存（含 icon+color+只 text）→ 200 -- Admin 详情回显 → 3 条字段精确 -- MP 详情 icon/color 透传 → 正确 -- icon 超 64 字 → 400 -- color 超 16 字 → 400 -- 老数据 null → 自然降级，无回归 - ---- - -## 部署 - -测试服已部署完毕: -- product-v2 task `f7952e0c` success -- order-v2 task `e94c50cd` success -- mp-service task `5b005209` success - -**正式环境部署**：无需 DDL（equipment_list 列已在 PR #1259 DDL 时加，新字段存在同一 JSON 列内）。 diff --git a/changelogs/2026-04/2026-04-23_equipment-list-structured.md b/changelogs/2026-04/2026-04-23_equipment-list-structured.md deleted file mode 100644 index 01be1c4..0000000 --- a/changelogs/2026-04/2026-04-23_equipment-list-structured.md +++ /dev/null @@ -1,164 +0,0 @@ -# 装备建议字段改造 — 条目列表结构化 - -**日期**: 2026-04-23 -**PR**: #1259 (Closes #1244) -**服务**: hl-product-service-v2 / hl-order-service-v2 / hl-mp-service -**类型**: feat（新增字段，向后兼容） - ---- - -## 背景 - -管理后台「产品编辑 → 补充信息 → 预订须知 → 装备建议」从纯文本 textarea 改为**条目列表**形式。小程序端目标视觉：左图标 + 右文案，一行一条。 - -**图标责任**：后端只存文本，图标由前端自行实现（硬编码关键词匹配 / 内置图标库 / 顺序样式），后端不提供图标字段。 - ---- - -## 字段新增契约 - -### 数据结构 - -```typescript -interface EquipmentItem { - text: string; // 文案，必填，1-50 字 -} -``` - -- **条目数上限**: 20 -- **单条 text 长度**: 1-50 字（非空非空白） -- **text 必填非空** -- 超限后端返 `code=400 message="装备建议不合法：..."` - -### 旧字段（保留，降级兜底） - -`equipmentAdvice: string`（富文本 HTML 字符串）继续返回，**不删**。 - -### 降级三态（前端必须实现） - -| equipmentList | equipmentAdvice | 前端行为 | -|---------------|-----------------|---------| -| 非空数组 | 任意 | 渲染条目列表（图标前端自行匹配） | -| null / 空数组 | 非空字符串 | 渲染纯文本（可能含 HTML） | -| null / 空数组 | null / 空 | 不渲染"装备建议"模块 | - ---- - -## 涉及接口（5 处响应体变化 + 1 处请求体） - -### 1. Admin 保存 `POST /admin/product/supplement/save` - -**请求体新增**： -```json -{ - "productId": 123, - "equipmentList": [ - {"text": "防晒霜 SPF50+"}, - {"text": "长袖防晒衣"}, - {"text": "薄外套（早晚温差15°C+）"} - ] -} -``` - -**请求体删除**：`equipmentAdvice` 字段从 `ProductSupplementSaveReqVO` 彻底移除（老 UI 已无入口）。 - -### 2. Admin 详情 `GET /admin/product/{id}` → `SupplementVO` - -**响应新增**： -```json -{ - "supplement": { - "equipmentAdvice": "<p>老富文本旧字段</p>", - "equipmentList": [{"text": "防晒霜 SPF50+"}] - } -} -``` - -### 3. MP 产品详情 `GET /mp/product/{id}` - -**响应新增**： -```json -{ - "equipmentAdvice": "<p>...</p>", - "equipmentList": [{"text": "防晒霜 SPF50+"}] -} -``` - -### 4. 订单详情 `GET /mp/order/{id}` - -**响应新增** `OrderDetailVO.equipmentList`（下单时固化自产品快照）： -```json -{ - "equipmentAdvice": "...", - "equipmentList": [{"text": "..."}] -} -``` - -### 5. 供应清单 `GET /mp/order/{orderId}/supplies-checklist` - -**响应新增** `MpSuppliesChecklistRespVO.equipmentList`： -```json -{ - "orderId": 1001, - "categories": [...], - "equipmentAdvice": "...", - "equipmentList": [{"text": "..."}] -} -``` - ---- - -## 向后兼容说明 - -- **老订单快照**：2026-04-23 之前下单的订单，产品快照 JSON 中不含 `equipmentList` 键 → 后端 `path("equipmentList").isArray()` 返 false → `equipmentList` 返 null → 前端按三态降级兜底渲染 `equipmentAdvice` -- **老产品**：未重新保存过的产品 DB 列 `equipment_list` 为 null → 接口返 null -- **零破坏性**：所有响应字段只新增不删除，前端不升级也不会报错 - ---- - -## 前端实现要点 - -1. **管理端**： - - 移除原 `equipmentAdvice` 富文本输入框 - - 新增"+ 新增装备"条目列表 UI（一行一条，单条文案输入 + 删除按钮） - - 保存时只传 `equipmentList: List<{text}>`，不传 `equipmentAdvice` - - 本地做条目数 ≤20 / 单条 1-50 字前置校验，避免 400 - -2. **小程序端**： - - 实现三态降级逻辑（见上表） - - 图标硬编码或按文案关键词匹配（例: "防晒" → 太阳图标, "外套" → 衣服图标, "鞋" → 鞋图标） - - 一行一条布局：`<Icon> <Text>` - -3. **订单详情/供应清单**：老订单自然走 `equipmentAdvice` 纯文本分支，新订单渲染 `equipmentList` - ---- - -## 硬约束提醒 - -- **不要传空字符串 text**：后端会 400（`@NotBlank`） -- **不要传 >20 条**：后端会 400（`@Size(max=20)`） -- **不要传 >50 字 text**：后端会 400（`@Size(max=50)`） -- **前端可以传空数组 `[]`** 表示"清空装备建议"，这是合法意图 - ---- - -## 代码位置参考（前端调试用） - -- Admin VO: `hl-product-service-v2/.../vo/admin/ProductSupplementSaveReqVO.java` -- Admin 详情: `hl-product-service-v2/.../vo/admin/ProductDetailRespVO.SupplementVO` -- MP VO: `hl-product-service-v2/.../vo/mp/MpProductDetailRespVO` -- 订单详情: `hl-order-service-v2/.../controller/vo/OrderDetailVO` -- 供应清单: `hl-order-service-v2/.../internal/vo/MpSuppliesChecklistRespVO` - ---- - -## 部署说明 - -测试服已执行 DDL（本次部署前必须先跑）： -```sql -ALTER TABLE product_supplement - ADD COLUMN equipment_list JSON DEFAULT NULL - COMMENT '装备建议条目列表([{text}]),优先于 equipment_advice'; -``` - -正式环境上线前同步 DDL。 diff --git a/changelogs/2026-04/2026-04-23_mp-contract-list-detail-typed-vo.md b/changelogs/2026-04/2026-04-23_mp-contract-list-detail-typed-vo.md deleted file mode 100644 index 1ce0342..0000000 --- a/changelogs/2026-04/2026-04-23_mp-contract-list-detail-typed-vo.md +++ /dev/null @@ -1,91 +0,0 @@ -# 微信小程序 · 合同接口 5 个：返回值从 Map 改为强类型 VO - -- **变更日期**: 2026-04-23 -- **PR**: #1314 -- **端**: 微信小程序（管理端不涉及） -- **影响面**: 合同列表 / 合同详情 / 订单关联合同 -- **兼容性**: **字段契约规范化**。返回 Map 改为具名 VO，前端按本文列出的字段接入即可；Swagger 以 `MpContractVO` / `MpContractDetailVO` 为准 - ---- - -## 涉及接口（5 个） - -| # | 功能 | 方法 | 路径 | 返回类型 | -|---|---|---|---|---| -| 1 | 合同列表 | GET | `/mp/contract/list?status=&page=&pageSize=` | `PageResult<MpContractVO>` | -| 2 | 合同详情 | GET | `/mp/contract/{id}` | `MpContractDetailVO` | -| 3 | 按订单查合同（单条最新） | GET | `/mp/contract/by-order/{orderId}` | `MpContractVO` | -| 4 | 按订单查合同（TOUR+INSURANCE 全部） | GET | `/mp/contract/by-order/{orderId}/all` | `List<MpContractVO>` | -| 5 | 重发签署短信 | POST | `/mp/contract/{contractId}/resend-sms` | `Result<Boolean>` | - -鉴权：微信小程序登录态 token，网关解析 `X-User-Id` 后透传 order-v2。 - ---- - -## 列表/查单：`MpContractVO` 字段清单 - -| 字段 | 类型 | 说明 | -|---|---|---| -| contractId | Long | 合同 ID | -| orderId | Long | 订单 ID | -| templateCode / templateName | String | 合同模板编码 / 名称 | -| contractNumber | String | 合同编号 | -| platform | String | 签约平台 | -| contractType | String | 合同类型（字典 `contract_type`：TOUR=旅游 / INSURANCE=保险单）| -| contractTypeLabel | String | 合同类型显示文案（BFF 翻译好）| -| mode | String | 签约模式（字典 `contract_mode`：ONLINE / OFFLINE）| -| modeLabel | String | 签约模式显示文案 | -| status | String | 合同状态（字典 `contract_status`）| -| statusLabel | String | 合同状态显示文案 | -| signUrl | String | 签署 URL（待签时跳转用）| -| qrCodeUrl | String | 签署二维码 URL | -| fileUrl | String | 已签合同 PDF 下载 URL | -| agencyCode / travelAgencyName | String | 旅行社编号 / 名称 | -| destination | String | 目的地 | -| departureDate / returnDate | LocalDate（`yyyy-MM-dd`）| 出发日期 / 返回日期 | -| totalAmount | BigDecimal | 合同总金额 | -| touristCount | Integer | 出行人数 | -| contactName | String | 联系人姓名（明文，前端自行脱敏）| -| contactPhone | String | 联系人电话（明文，前端自行脱敏）| -| createTime | LocalDateTime（`yyyy-MM-dd HH:mm:ss`）| 创建时间 | - ---- - -## 详情：`MpContractDetailVO`（继承 `MpContractVO`，额外三段） - -| 字段 | 类型 | 说明 | -|---|---|---| -| supplementaryClause | String | 补充约定正文 | -| travelers | `List<TravelerInfo>` | 合同关联出行人 | -| statusLogs | `List<MpContractStatusLogVO>` | 状态变更日志（按时间倒序）| - -`TravelerInfo` 字段：`travelerId / name / idCardType(ID_CARD,PASSPORT) / idCardNo / phone / isSigner`，姓名/证件号/电话均为**明文**，前端按需脱敏。 - -`MpContractStatusLogVO` 字段：`logId / contractId / oldStatus / newStatus / source(CALLBACK/POLLING/MANUAL) / rawPayload / createTime`。 - ---- - -## 重发签署短信（前端无入参变化） - -**前端不需要传 body**。mp-service BFF 内部从登录 token 解析出 `userId` 后包装成 `MpContractResendSmsReqVO` 再透传给 order-v2 内部接口，前端直接空 body 调用即可： - -``` -POST /mp/contract/{contractId}/resend-sms -``` - -返回 `Result<Boolean>`，`data=true` 表示发送成功。合同不存在 / 非 `SIGNING` 状态 / 不属于当前用户 → 400 或 403。 - ---- - -## 不影响范围 - -- 管理端合同接口（`/admin/contract/**`）零影响 -- 下单/支付/合同生成链路无变化 -- 合同 webhook / 回调 / 状态机零影响 - ---- - -## 相关 - -- PR：[wx/HL#1314](https://git.1814.love:8443/wx/HL/pulls/1314) -- 部署：`hl-mp-service`（8085） diff --git a/changelogs/2026-04/2026-04-23_mp-dashboard-endpoints-timing-guide.md b/changelogs/2026-04/2026-04-23_mp-dashboard-endpoints-timing-guide.md deleted file mode 100644 index f6b5ac9..0000000 --- a/changelogs/2026-04/2026-04-23_mp-dashboard-endpoints-timing-guide.md +++ /dev/null @@ -1,172 +0,0 @@ -# mp-service: 订单/行程 5 个聚合接口调用时机梳理 - -> **服务**: hl-mp-service（端口 8085）→ 透传 hl-order-service-v2（端口 8094） -> **PR**: -（纯契约梳理，无代码变更） -> **Issue**: - -> **日期**: 2026-04-23 -> **影响范围**: C 端「订单详情页」+「行程 Tab」的 5 个聚合接口 - ---- - -## ⚠️ 关键变化 - -**无接口变更**。本 changelog 是对现有 5 个聚合接口的调用时机/契约关系做一次性梳理，方便前端对照接入。调用顺序、入参、返回 VO 均未调整。 - ---- - -## 一、接口清单 - -| # | 接口 | 方法 | 路径 | 返回 VO | 缓存 TTL | -|---|------|------|------|---------|----------| -| 1 | 订单详情页聚合 | GET | `/mp/order/{orderId}/dashboard` | `MpOrderDashboardVO` | 30s | -| 2 | 行程 Tab 路由决策 | GET | `/mp/trip/tab-state` | `MpTripTabStateVO` | 15s | -| 3 | 行程前·出发准备页聚合 | GET | `/mp/trip/{orderId}/pre-trip-dashboard` | `MpPreTripDashboardVO` | 30s | -| 4 | 行程中·今日页聚合 | GET | `/mp/trip/today-dashboard` | `MpTodayDashboardVO` | 15s | -| 5 | 旅行回忆列表 | GET | `/mp/order/travel-memory` | `PageResult<MpTravelMemoryVO>` | 60s | - -所有接口均需登录，`userId` 由 mp-service 从 token 取出后透传给 order-v2。 - ---- - -## 二、两条独立入口 - -### 入口 A：订单详情页（#1） - -来源：我的订单列表点击、支付成功跳转、消息/通知链接。拿到 `orderId` 后直接调 `#1`，与行程 Tab 无关。 - -### 入口 B：行程 Tab（#2 → #3/#4/#5） - -用户切到行程 Tab 时**必须先调 `#2 /mp/trip/tab-state`**，后端根据当前订单情况返回 `state` + `orderId`，前端按 `state` 分支调对应接口。 - -| `state` | 含义 | 下一步接口 | 是否需要前端传 orderId | -|---------|------|-----------|------------------------| -| `NEW` | 从未下过单 | 无（空态） | - | -| `BEFORE_START` | 有订单未出发 | `#3 /mp/trip/{orderId}/pre-trip-dashboard` | ✅ 用 #2 返回的 orderId | -| `IN_PROGRESS` | 行程进行中 | `#4 /mp/trip/today-dashboard` | ❌ 后端从 userId 反查 | -| `RETURNING` | 已完成过行程 | `#5 /mp/order/travel-memory` | ❌ 分页拉列表 | - -未支付订单（`PENDING_PAY`）不计入 `tab-state` 判定。 - ---- - -## 三、接口定位与返回核心字段 - -### 1. `GET /mp/order/{orderId}/dashboard` — 订单管理视角 - -**场景**：用户查看某张订单的履约与售后信息。 - -**返回**：`MpOrderDashboardVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `order` | `MpOrderDetailVO` | 订单主体，含 `serviceItems`（服务包含列表）| -| `preTripChecklist` | `MpPreTripChecklistVO` | 出发准备清单（顶部待办徽章用；服务降级时 null）| -| `files` | `FilesVO` | 合同摘要 + 发票摘要 + 保单 PDF 路径 | -| `insurance` | `MpInsuranceDetailVO` | 保险详情（未投保时 null）| -| `refund` | `RefundVO` | 退款详情+进度（仅 CANCELLED/REFUNDING/REFUNDED/REFUND_REJECTED/APPEALING 状态有值，其余 null）| - -内部并行调 6 个 Feign：order（主，失败 500）+ contract + invoice + insurance + refund-detail + refund-progress。contract/invoice/insurance 失败降级 null。 - -> **服务包含列表**位置：`MpOrderDashboardVO.order.serviceItems`（`List<MpServiceItemVO>`） -> 每项字段：`type`（HOTEL/MEAL/VEHICLE/GUIDE/PHOTOGRAPHER/TICKET/INSURANCE）、`title`、`summary`、`hasDetail`（运行态，是否有子详情页可看） - ---- - -### 2. `GET /mp/trip/tab-state` — 行程 Tab 路由决策 - -**场景**：用户切到行程 Tab 时的第一个调用。 - -**返回**：`MpTripTabStateVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `state` | String | `IN_PROGRESS` / `BEFORE_START` / `RETURNING` / `NEW` | -| `stateLabel` | String | 状态中文标签 | -| `orderId` | Long | IN_PROGRESS / BEFORE_START 时有值 | -| `summary` | `Summary` | 产品名/档位/出发日期/距出发天数 等 | - ---- - -### 3. `GET /mp/trip/{orderId}/pre-trip-dashboard` — 行程前·出发准备 - -**场景**：`tab-state` 返回 `BEFORE_START` 时调用，订单已确认尚未出发。 - -**返回**：`MpPreTripDashboardVO`，包含订单头 / 出发准备清单 / 带队团队（领队+摄影师）/ 行程概览 / 客服电话。 - -内部并行调 3 个 Feign：trip + guide + photographer。guide/photographer 失败降级为 null，不影响主清单。 - ---- - -### 4. `GET /mp/trip/today-dashboard` — 行程中·今日页 - -**场景**：`tab-state` 返回 `IN_PROGRESS` 时调用，用户正在行程中。 - -**返回**：`MpTodayDashboardVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `today` | `MpTodayVO` | 今日行程主体（无行程中订单时 null）| -| `leader` | `MpGuideInfoVO` | 联系领队卡 | -| `sosContact` | `SosContactVO` | SOS：领队电话 + 客服电话 + 保险客服电话 | -| `weather` | `List<MpWeatherDayVO>` | 今日 + 未来 N 天天气（失败降级 null）| -| `todayProgressPercent` | Integer | 今日进度 0-100（已游览景点 / 总景点）| -| `dayNav` | `List<MpTripDayNavVO>` | DAY 导航，每天标记 DONE/CURRENT/PENDING | -| `todayTimeline` | `MpTodayTimelineVO` | 按当前时间切成 completed/current/next 三段 | -| `todayHotel` | `MpTripHotelArrangementVO` | 今晚住宿（含是否与昨晚换酒店标记）| -| `tomorrow` | `MpTomorrowPreviewVO` | 明日预告（路线摘要+出发时间）| - -**入参仅 userId**（无 orderId），后端自己从 userId 反查进行中订单。无行程中订单时接口正常返回，核心字段全部 null/空列表。 - -内部并行调 guide + weather，两者失败都降级为 null。 - ---- - -### 5. `GET /mp/order/travel-memory` — 回头客态 - -**场景**：`tab-state` 返回 `RETURNING` 时调用。 - -**返回**：`PageResult<MpTravelMemoryVO>` — 已完成（COMPLETED）订单分页列表，按出发日倒序。含 `reviewed` / `rating` / `reviewId`（评价服务降级时评分字段为 null）。 - ---- - -## 四、契约约束（正确调用方式） - -### ✅ 行程 Tab 入口 - -| 场景 | 正确调用序列 | -|------|--------------| -| 用户切行程 Tab | **先 `#2`** → 按 state 分支调 `#3` / `#4` / `#5` 之一 | -| state=BEFORE_START | `#2` 返回的 `orderId` 传给 `#3` | -| state=IN_PROGRESS | `#4` 不传 orderId，token 中的 userId 足够 | -| state=RETURNING | 调 `#5` 拉分页 | -| state=NEW | 不再调任何接口 | - -### ❌ 错误调用 - -- 切行程 Tab 直接调 `#3` / `#4`（跳过 `#2`）—— 不要自行根据订单状态/时间判断该渲染哪页 -- 并行调 `#3` 和 `#4` —— 同一时刻用户只可能在其中一个状态 -- `#3` 用自己缓存的 orderId —— 必须用 `#2` 本次返回的 orderId（订单可能已切换） - -### ✅ 订单详情入口（#1）独立 - -从任何订单链接进入都直接调 `#1`，不依赖 `#2`，也不影响行程 Tab 的调用。 - ---- - -## 五、不影响范围 - -- `#1 /mp/order/{orderId}/dashboard` 与 `#3 /mp/trip/{orderId}/pre-trip-dashboard` 字段独立，**不要互相替代** - - `#1` 关注：合同 / 发票 / 保单 / 保险 / 退款（订单管理视角） - - `#3` 关注：准备清单 / 领队+摄影师 / 行程概览（出行准备视角） -- `#3 pre-trip-dashboard` 与 `#4 today-dashboard` 返回 VO 完全不同，**不要通用一套渲染** -- 登录态统一从网关 token 解析，所有接口无需前端额外传 `userId` - ---- - -## 六、相关文档 - -- `MpOrderController.java`、`MpTripController.java`（hl-mp-service） -- VO：`MpOrderDashboardVO` / `MpTripTabStateVO` / `MpPreTripDashboardVO` / `MpTodayDashboardVO` / `MpTravelMemoryVO` -- 关联历史 changelog： - - `2026-04-22_mp-order-detail-service-items-has-detail.md`（#1234 hasDetail 字段） - - `2026-04-23_mp-pre-trip-checklist-split-arrival-departure.md`（#1289 清单拆 ARRIVAL/DEPARTURE） diff --git a/changelogs/2026-04/2026-04-23_mp-group-order-young-child-count.md b/changelogs/2026-04/2026-04-23_mp-group-order-young-child-count.md deleted file mode 100644 index cf586a5..0000000 --- a/changelogs/2026-04/2026-04-23_mp-group-order-young-child-count.md +++ /dev/null @@ -1,58 +0,0 @@ -# 微信小程序 · 小蒙马下单 youngChildCount 不再被强制清零 - -- **变更日期**: 2026-04-23 -- **PR**: #1298 -- **端**: 微信小程序（管理端不涉及） -- **影响面**: 小蒙马（GROUP）下单 / 订单详情 人群结构展示 -- **兼容性**: **接口契约零变化**。前端原来传的 `youngChildCount` 从"传了也没用"变成"被保留" - ---- - -## 变化一句话 - -小蒙马下单接口原本强制把 `youngChildCount`（小童数）清零，现在会**保留前端传入的数值**写入订单。小童仍然不参与计价（金额 0），仅作为随行人数展示。 - ---- - -## 相关接口 - -`POST /mp/order/create`（小蒙马 GROUP 路径） - -### 入参 `youngChildCount` 行为变化 - -| 场景 | 以前 | 现在 | -|---|---|---| -| 前端传 `youngChildCount=2` | 后端覆盖为 `0` | **保留为 `2`** | -| 前端不传 / 传 null | 后端存 `0` | 保留 `null` → 实际存 `0`（兼容）| - -### 计价规则 - -| 项 | 行为 | -|---|---| -| 小童（young child） | **不参与计价**（`youngChildPrice = 0`、`youngChildTotal = 0`），仅作为随行头数写入订单 | -| 幼童（baby） | 仍强制 `babyCount = 0`（规则未变）| -| 是否加床（`childNeedBed`） | 仍强制 `false`（规则未变）| - ---- - -## 订单详情展示侧 - -订单详情 `adultCount / childCount / youngChildCount / babyCount` 字段： - -- `youngChildCount` 现在会反映前端下单时实际提交的小童数 -- 价格结构 `priceBreakdown` 中小童相关小计仍为 0（未参与计价） - ---- - -## 不影响范围 - -- 价格汇总 `totalPrice / adultTotal / childTotal` **零影响**（不加小童价） -- CORE / CUSTOM 产品下单流程 **零影响**（它们原本就按普通逻辑处理小童计价） -- 出行人列表（`travelers`）**零影响** - ---- - -## 相关 - -- PR：[wx/HL#1298](https://git.1814.love:8443/wx/HL/pulls/1298) -- 部署：`hl-order-service-v2`（8094） diff --git a/changelogs/2026-04/2026-04-23_mp-order-balance-amount-unified.md b/changelogs/2026-04/2026-04-23_mp-order-balance-amount-unified.md deleted file mode 100644 index cfdf3b0..0000000 --- a/changelogs/2026-04/2026-04-23_mp-order-balance-amount-unified.md +++ /dev/null @@ -1,66 +0,0 @@ -# 微信小程序 · 订单详情尾款金额（balanceAmount）计算口径统一 - -- **变更日期**: 2026-04-23 -- **PR**: #1306 -- **端**: 微信小程序（管理端同步生效） -- **影响面**: 订单详情页尾款金额展示 + 下单流程 `paymentType` 回填 -- **兼容性**: **前端零改动**；已付款的订单 balanceAmount 语义更严谨、更广泛 - ---- - -## 变化一：订单详情 `balanceAmount` 字段适用范围扩大 + 公式统一 - -### 以前 - -只在订金订单（`paymentType=DEPOSIT`）且 `depositAmount` 非空时返回 `balanceAmount`。全款订单（`paymentType=FULL`）**不返回该字段**（或为 null）。 - -### 现在 - -**所有订单**都返回 `balanceAmount`，统一口径： - -``` -balanceAmount = max(0, totalPrice - discountAmount + surchargeAmount - paidAmount) -``` - -- `paidAmount`：已支付金额（订金支付后 = 订金金额；尾款已付 = 全款） -- 永远 ≥ 0（不会出现负数） -- 全款订单 paidAmount=0 时 balance = totalPrice（未付）；paidAmount=totalPrice 时 balance = 0（已付清） - -### 前端接入影响 - -- **原先用 `paymentType===DEPOSIT` 判断才读 `balanceAmount` 的逻辑可以保留**，仍然工作 -- 如果想给全款订单也展示「待支付金额」，直接读 `balanceAmount` 即可 -- "待支付金额 = 0" 代表订单已付清（可用于隐藏支付按钮） - ---- - -## 变化二：下单时 `paymentType` 不再被 quote 覆盖为 `FULL` - -### 以前 - -CORE 产品下单时，如果 quote 接口没返回 `paymentType`，后端会强制把订单 `paymentType` 设为 `FULL`，覆盖产品快照里的默认值。 - -### 现在 - -quote 返回 `paymentType` 非空 → 使用 quote 的值；quote 返回 null → **保留产品快照里的默认值**（`setProductInfoOnOrder` 阶段已设好）。 - -### 前端接入影响 - -- 下单后拿到的订单 `paymentType`（详情接口）会**更准确地反映产品本身的支付模式**（FULL / DEPOSIT） -- 原来因为这个覆盖逻辑导致 DEPOSIT 订金订单被错写成 FULL 的情况，不会再发生 - ---- - -## 不影响范围 - -- 下单请求体（`/mp/order/create`）**零变化** -- 订金/尾款金额（`depositAmount / depositRatio`）**零变化** -- 管理端订单详情 `balanceAmount` 逻辑**本次同步生效**（口径一致） -- 历史订单不回迁数据，但下次读详情时按新公式现算，**立即生效** - ---- - -## 相关 - -- PR：[wx/HL#1306](https://git.1814.love:8443/wx/HL/pulls/1306) -- 部署：`hl-order-service-v2`（8094） diff --git a/changelogs/2026-04/2026-04-23_mp-order-detail-group-batch-id.md b/changelogs/2026-04/2026-04-23_mp-order-detail-group-batch-id.md deleted file mode 100644 index f8d0c9b..0000000 --- a/changelogs/2026-04/2026-04-23_mp-order-detail-group-batch-id.md +++ /dev/null @@ -1,64 +0,0 @@ -# 微信小程序 · 订单详情新增 groupBatchId（团期 ID） - -- **变更日期**: 2026-04-23 -- **PR**: #1300 -- **端**: 微信小程序（管理端不涉及） -- **影响面**: 订单详情（仅小蒙马 GROUP 订单有值） -- **兼容性**: **完全向后兼容**（纯新增字段，旧前端不读即可忽略） - ---- - -## 变化一句话 - -微信小程序订单详情返回体 `MpOrderDetailVO` 新增 `groupBatchId` 字段，仅小蒙马 GROUP 订单有值，前端可据此跳转到对应团期详情页。 - ---- - -## 接口 - -`GET /mp/order/{orderId}`（以及走 BFF 的同类接口） - -### 新增字段 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `groupBatchId` | Long | 团期 ID。仅 GROUP（小蒙马）订单有值；CORE（自驾/自助游）、CUSTOM（定制）等订单为 null | - -### 返回示例 - -```json -{ - "code": 200, - "data": { - "orderId": 1900001, - "orderNo": "XMM20260423001", - "groupCode": "0001", - "groupBatchId": 2045401225939079169, - "productId": 1893012345678901234, - "productName": "...", - "...": "..." - }, - "success": true -} -``` - ---- - -## 前端接入场景（参考） - -「我的订单 → 订单详情 → 团期入口」点击后用 `groupBatchId` 跳团期详情页；非 GROUP 订单为 null 时隐藏入口即可。 - ---- - -## 不影响范围 - -- 其它订单字段（`orderNo / groupCode / productId / productName / ...`）**零变化** -- 管理端订单详情 DTO **不涉及** -- 下单/支付/退款链路 **零影响** - ---- - -## 相关 - -- PR：[wx/HL#1300](https://git.1814.love:8443/wx/HL/pulls/1300) -- 部署：`hl-order-service-v2`（8094）+ `hl-mp-service`（8085） diff --git a/changelogs/2026-04/2026-04-23_mp-order-insurance-detail-endpoint.md b/changelogs/2026-04/2026-04-23_mp-order-insurance-detail-endpoint.md deleted file mode 100644 index 963c821..0000000 --- a/changelogs/2026-04/2026-04-23_mp-order-insurance-detail-endpoint.md +++ /dev/null @@ -1,238 +0,0 @@ -# mp-service: 订单保险详情独立接口契约梳理 - -> **服务**: hl-mp-service（端口 8085）→ 透传 hl-order-service-v2（端口 8094） -> **PR**: -（纯契约梳理，无代码变更） -> **Issue**: - -> **日期**: 2026-04-23 -> **影响范围**: C 端「订单详情 - 服务包含 - 保险」子详情入口 - ---- - -## ⚠️ 关键变化 - -**无接口变更**。本 changelog 只梳理 `GET /mp/order/{orderId}/insurance` 的入参/出参契约，方便前端对照接入。 - -⚠️ **路径提醒**：Controller 类名为 `MpOrderServiceDetailController`，但 `@RequestMapping` 是 `/mp/order`（不是 `/mp/order-service`）。完整路径以本文档为准。 - ---- - -## 一、接口基本信息 - -| 项 | 值 | -|----|----| -| 路径 | `/mp/order/{orderId}/insurance` | -| 方法 | GET | -| Controller | `MpOrderServiceDetailController#getInsurance` | -| 返回类型 | `Result<MpInsuranceDetailVO>` | -| 登录 | 需要（网关 token 解析 userId 透传）| -| 缓存 | 无 `@MpCache` 注解 | - ---- - -## 二、调用时机与上下游关系 - -| 场景 | 推荐接口 | -|------|---------| -| 订单详情页首屏（聚合） | `GET /mp/order/{orderId}/dashboard` → 取 `.insurance` 字段 | -| 从「服务包含」列表点「保险」进子详情 | **`GET /mp/order/{orderId}/insurance`**（本接口）| -| 下载保单 PDF（整单合并） | `GET /mp/insurance/policy-pdf/{orderId}` | -| 下载单张保单 PDF | `GET /mp/insurance/policy/{insuranceOrderId}/download` | - -两条路径返回同一个 VO（`MpInsuranceDetailVO`），字段结构一致。**不要在订单详情页同时调 dashboard 和本接口**。 - -`insuranceOrderId`（下载单张保单用）从本接口返回的 `policies[].insuranceOrderId` 取。 - ---- - -## 三、入参 - -### 路径参数 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `orderId` | Path | Long | ✅ | 订单ID | - -### Header - -| 字段 | 必填 | 说明 | -|------|------|------| -| 登录 token | ✅ | 由网关校验并解析出 `userId`，前端无需手动传 `userId` | - ---- - -## 四、出参 `Result<MpInsuranceDetailVO>` - -### 顶层 `MpInsuranceDetailVO` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `schemeId` | Long | 方案ID | -| `schemeName` | String | 方案名称 | -| `description` | String | 方案描述 | -| `isOverseas` | Boolean | 是否境外 | -| `totalDays` | Integer | 适用行程天数 | -| `notice` | String | 保险告知状态：`INCLUDED` / `OPTIONAL` / `EXCLUDED` | -| `segments` | `List<CoverageSegment>` | 保障分段列表 | -| `policies` | `List<PolicyItem>` | 投保记录列表（未付款为空数组）| - -### `CoverageSegment` — 保障分段（方案层） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `segmentName` | String | 分段名称 | -| `dayOffsetStart` | Integer | 起始天 | -| `dayOffsetEnd` | Integer | 结束天（`-1` = 最后一天）| -| `productName` | String | 保险产品名称 | -| `planName` | String | 保险计划名称 | - -### `PolicyItem` — 投保记录（订单层，已付款才有） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `insuranceOrderId` | Long | 保险订单ID（下载单张保单用）| -| `policyNo` | String | 保单号 | -| `productName` | String | 保险产品名称 | -| `planName` | String | 保险计划名称 | -| `premium` | BigDecimal | 保费（元）| -| `insuredCount` | Integer | 被保人数 | -| `coverageStartDate` | LocalDate | 保障开始日期 | -| `coverageEndDate` | LocalDate | 保障结束日期 | -| `status` | String | `PENDING` / `INSURING` / `INSURED` / `FAILED`（`CANCELLED` 已由后端过滤不返回）| -| `statusLabel` | String | 状态中文标签 | -| `insuredPersons` | `List<InsuredPerson>` | 被保人列表 | - -### `InsuredPerson` — 被保人（证件/电话已脱敏） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `name` | String | 姓名 | -| `idCardType` | String | `ID_CARD` / `PASSPORT` | -| `idCardNo` | String | 证件号码（脱敏）| -| `birthday` | LocalDate | 出生日期 | -| `gender` | String | `MALE` / `FEMALE` | -| `phone` | String | 手机号（脱敏）| - ---- - -## 五、响应示例 - -### 已投保订单 - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "schemeId": 101, - "schemeName": "境内 7 日综合保障", - "description": "含意外/医疗/行李/延误", - "isOverseas": false, - "totalDays": 7, - "notice": "INCLUDED", - "segments": [ - { - "segmentName": "全程", - "dayOffsetStart": 1, - "dayOffsetEnd": -1, - "productName": "平安境内旅行险", - "planName": "豪华计划" - } - ], - "policies": [ - { - "insuranceOrderId": 20439, - "policyNo": "PICC2026042300001", - "productName": "平安境内旅行险", - "planName": "豪华计划", - "premium": 38.00, - "insuredCount": 2, - "coverageStartDate": "2026-05-01", - "coverageEndDate": "2026-05-07", - "status": "INSURED", - "statusLabel": "已生效", - "insuredPersons": [ - { - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "1101**********1234", - "birthday": "1990-01-01", - "gender": "MALE", - "phone": "138****5678" - } - ] - } - ] - } -} -``` - -### 未付款订单（policies 为空数组） - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "schemeId": 101, - "schemeName": "境内 7 日综合保障", - "isOverseas": false, - "totalDays": 7, - "notice": "INCLUDED", - "segments": [ /* 方案分段仍有值 */ ], - "policies": [] - } -} -``` - -### 订单不含保险（notice=EXCLUDED） - -```json -{ - "code": 200, - "data": { - "schemeId": null, - "schemeName": null, - "notice": "EXCLUDED", - "segments": [], - "policies": [] - } -} -``` - ---- - -## 六、边界行为 - -- 未登录 → 401（网关拦截） -- `orderId` 不属于当前 userId → 业务异常，`Result.code != 200` -- 订单存在但未付款 → `policies=[]`，但 `segments` / `schemeName` 仍返回（方案信息属于产品快照） -- 订单不含保险（`notice=EXCLUDED`）→ `policies=[]` 且 `segments=[]` -- `status=CANCELLED` 的保单 → **后端已过滤**，不会出现在 `policies` 中 - ---- - -## 七、契约约束 - -- 下载单张保单时的 `insuranceOrderId` **必须**取自本接口返回的 `policies[].insuranceOrderId`，不要用 `orderId` 替代 -- `dayOffsetEnd=-1` 是约定值，表示"保障到行程最后一天"，非真实天数 -- `premium` 是 `BigDecimal`，JSON 序列化为数字（非字符串），精度 2 位小数 - ---- - -## 八、不影响范围 - -- **仅新增文档梳理**，代码零改动 -- `/mp/order/{orderId}/dashboard` 聚合接口中的 `.insurance` 字段与本接口返回 VO 完全一致，两者**可互换取用** -- 保单 PDF 下载两个接口（`/mp/insurance/policy-pdf/{orderId}` 和 `/mp/insurance/policy/{insuranceOrderId}/download`）与本接口是上下游关系，未做变更 - ---- - -## 九、相关文档 - -- `MpOrderServiceDetailController.java`（hl-mp-service） -- VO：`MpInsuranceDetailVO`（hl-mp-service + hl-order-service-v2 镜像一致） -- 关联 changelog： - - `2026-04-23_mp-dashboard-endpoints-timing-guide.md`（订单/行程 5 个聚合接口调用时机梳理） - - `2026-04-23_mp-service_contract-insurance-api-inventory.md`（保险/合同详情 5 接口梳理） diff --git a/changelogs/2026-04/2026-04-23_mp-order-staff-avatar-fix.md b/changelogs/2026-04/2026-04-23_mp-order-staff-avatar-fix.md deleted file mode 100644 index b6ec53a..0000000 --- a/changelogs/2026-04/2026-04-23_mp-order-staff-avatar-fix.md +++ /dev/null @@ -1,58 +0,0 @@ -# 微信小程序 · 订单详情领队/摄影师头像 avatarUrl 之前为 null — 已修复 - -- **变更日期**: 2026-04-23 -- **PR**: #1309 -- **端**: 微信小程序（管理端不涉及） -- **影响面**: 订单详情「领队」「摄影师」弹窗 / 卡片的头像展示 -- **兼容性**: **字段结构零变化**，原本 null 的字段现在会填充有效 URL - ---- - -## 变化一句话 - -微信小程序订单详情相关接口中的员工头像 `avatarUrl` 字段之前恒为 null，现在会返回有效的头像 OSS URL。 - ---- - -## 涉及接口 - -下列接口返回体中的 `avatarUrl` 字段： - -| 接口 | 返回体中的位置 | -|---|---| -| `GET /mp/order/{orderId}/guide` | `guide.avatarUrl` | -| `GET /mp/order/{orderId}/photographer` | `photographer.avatarUrl` | - ---- - -## 头像生成规则（前端可了解优先级） - -1. 优先取员工档案 `coverMaterialId` 对应的物料库封面（OSS URL） -2. 若无，fallback 取员工相册 `photoUrls` 的第一张 -3. 都没有 → `avatarUrl` 为 null（前端走默认占位图即可） - ---- - -## 生效范围（⚠️ 重要） - -| 订单类型 | 是否生效 | -|---|---| -| **新下单的小蒙马（GROUP）订单** | ✅ 立即生效 | -| 历史已下单的 GROUP 订单 | ❌ 下单时已固化的员工快照未补头像，avatarUrl 仍为 null（如需回填可后台批量补修，本次未做）| -| CORE（核心/自驾/自助游）订单 | N/A（本来就不含领队/摄影师）| - ---- - -## 不影响范围 - -- 领队/摄影师接口的其它字段（`staffName / staffPhone / staffRole / remark` 等）**零变化** -- 下单请求体、订单详情主体**零变化** -- 管理端员工档案（`/admin/staff/**`）**零变化** -- 订单班期员工列表接口（`/mp/order/{orderId}/staff-list` 等）同步生效 - ---- - -## 相关 - -- PR：[wx/HL#1309](https://git.1814.love:8443/wx/HL/pulls/1309) -- 部署：`hl-product-service-v2`（8093）+ `hl-resource-service`（8082） diff --git a/changelogs/2026-04/2026-04-23_mp-pre-trip-checklist-split-arrival-departure.md b/changelogs/2026-04/2026-04-23_mp-pre-trip-checklist-split-arrival-departure.md deleted file mode 100644 index 73b8a22..0000000 --- a/changelogs/2026-04/2026-04-23_mp-pre-trip-checklist-split-arrival-departure.md +++ /dev/null @@ -1,113 +0,0 @@ -# 微信小程序 · 出发准备清单「接送机」拆成「到达」+「离开」两项 + 按出行人覆盖三态 - -- **变更日期**: 2026-04-23 -- **PR**: #1289 -- **端**: 微信小程序（管理端不涉及） -- **影响面**: 行前准备清单（出发倒计时聚合接口） -- **兼容性**: **需要前端同步调整**（清单项数量从 6 变 7，单项 key 新增，状态值新增 `WARNING`） - ---- - -## 变化一：清单项数量 6 → 7 - -| 之前 | 现在 | -|---|---| -| 6 项：`DEPOSIT_PAID` / `TRAVELER_INFO` / **`ARRIVAL_INFO`**（接送机合一）/ `CONTRACT_SIGN` / `INSURANCE` / `CHECKLIST_CONFIRMED` | 7 项：`DEPOSIT_PAID` / `TRAVELER_INFO` / **`ARRIVAL_INFO`**（到达）/ **`DEPARTURE_INFO`**（离开）/ `CONTRACT_SIGN` / `INSURANCE` / `CHECKLIST_CONFIRMED` | - -### `ChecklistItemKey` 取值对照 - -| 新 key | 之前文案 | 现在文案 | -|---|---|---| -| `ARRIVAL_INFO` | `接送机信息` | **`到达信息`** | -| `DEPARTURE_INFO`（新增） | — | **`离开信息`** | - -前端如果用 `ARRIVAL_INFO` 这个枚举值做判断：逻辑保留即可，但文案"接送机"需要改为"到达"；新增 `DEPARTURE_INFO` 需要渲染一项。 - ---- - -## 变化二：状态新增 `WARNING`（黄色提示态） - -之前单项状态只有两个：`DONE / PENDING`；现在在到达/离开两项上新增 **`WARNING`**。 - -### 到达 / 离开项的三态判断 - -| 状态 | 触发条件 | 文案示例（title + subtitle） | -|---|---|---| -| `DONE` | 订单有至少 1 批到达/离开，且**所有出行人都已被某个批次覆盖** | 「到达信息已填」 · 「N 批 · 全员已覆盖」 | -| `WARNING`（新）| 有批次但**漏填了部分出行人** | 「到达信息未填全」 · 「还有 X 人未安排」 | -| `PENDING` | **0 批次** | 「填写到达信息」 · 「司机将根据此信息接机」 | - -离开项同理，文案里"到达 / 接机" → "离开 / 送机"。 - -> 前端如果沿用「DONE=绿色 / PENDING=灰色」两色方案，新增一个"黄色"（`WARNING`）即可。 - ---- - -## 变化三：`actionPayload` 新增 `section` 字段 - -点击「到达 / 离开」项跳转表单时，`actionPayload` 新增 `section` 区分是到达还是离开： - -```json -{ - "title": "填写到达信息", - "status": "PENDING", - "actionType": "NAVIGATE", - "actionPayload": { - "target": "arrival_form", - "orderId": 1900001, - "section": "arrival" // ← 新增，取值 arrival | departure - } -} -``` - -前端跳到达/离开表单页时，可用 `section` 定位默认展开的 tab。 - ---- - -## 接口 - -路径不变（以 Swagger 为准）。返回体结构： - -```json -{ - "code": 200, - "data": { - "items": [ - { "key": "DEPOSIT_PAID", "status": "DONE", "title": "...", "subtitle": "..." }, - { "key": "TRAVELER_INFO", "status": "PENDING", "title": "...", "subtitle": "..." }, - { "key": "ARRIVAL_INFO", "status": "WARNING", "title": "到达信息未填全", "subtitle": "还有 1 人未安排", - "actionType": "NAVIGATE", "actionPayload": { "target": "arrival_form", "orderId": 1900001, "section": "arrival" } }, - { "key": "DEPARTURE_INFO", "status": "PENDING", "title": "填写离开信息", "subtitle": "司机将根据此信息送机", - "actionType": "NAVIGATE", "actionPayload": { "target": "arrival_form", "orderId": 1900001, "section": "departure" } }, - { "key": "CONTRACT_SIGN", "status": "DONE" }, - { "key": "INSURANCE", "status": "DONE" }, - { "key": "CHECKLIST_CONFIRMED", "status": "PENDING" } - ] - }, - "success": true -} -``` - ---- - -## 前端需要做的事 - -1. 清单项渲染循环：从 6 项改为按后端返回 `items` 数组长度渲染（避免硬编码数量） -2. 新增 `DEPARTURE_INFO` 的 icon / 文案映射 -3. 新增 `WARNING` 状态的颜色 / 图标样式 -4. 点击到达/离开项跳转时，从 `actionPayload.section` 判断 tab 默认态 - ---- - -## 不影响范围 - -- 其它 5 项（`DEPOSIT_PAID / TRAVELER_INFO / CONTRACT_SIGN / INSURANCE / CHECKLIST_CONFIRMED`）行为**零变化** -- 到达 / 离开信息的 CRUD 接口（`/mp/order/{orderId}/arrival` 等）**零变化** -- 管理端行前清单（若有）**不涉及** - ---- - -## 相关 - -- PR：[wx/HL#1289](https://git.1814.love:8443/wx/HL/pulls/1289) -- 部署：`hl-order-service-v2`（8094） diff --git a/changelogs/2026-04/2026-04-23_mp-product-schedules-remain-fields.md b/changelogs/2026-04/2026-04-23_mp-product-schedules-remain-fields.md deleted file mode 100644 index 3e35fba..0000000 --- a/changelogs/2026-04/2026-04-23_mp-product-schedules-remain-fields.md +++ /dev/null @@ -1,106 +0,0 @@ -# C 端班期: schedules 接口补 `remainParticipants` / `remainFamilies` 字段, 订单后不再缓存穿透 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #1296 -> **Issue**: #1292 -> **日期**: 2026-04-23 -> **影响范围**: C 端小程序小蒙马(GROUP 类型)产品详情页"余多少家庭/余多少可报名"展示 + 下单后班期余量刷新 - ---- - -## ⚠️ 关键变化 - -1. **新增 2 个字段**: `GET /mp/product/{id}/schedules` 每个班期对象新增 `remainParticipants`(余可报名数, 人数口径) 和 `remainFamilies`(余家庭数, 房间口径) — 之前只返 `maxParticipants/enrolledCount/maxRooms/bookedRooms` 原始字段, 前端需要自己算差值。现在后端直接给聚合值。 -2. **缓存失效修复**: 之前下单成功后 5 分钟内重复调 schedules 返回旧 `enrolledCount`/`bookedRooms`(Redis 缓存未失效), 现在入团(enroll)/取消报名(unenroll)事务提交后立刻清 `mp:product:schedules:{productId}` 缓存, 前端下次 GET 立即拿到最新余量。 - -**前端影响**: 无破坏。旧前端忽略新字段继续工作; 新前端直接用 `remainParticipants` / `remainFamilies` 展示, 不需自己 max-used。 - ---- - -## 一、背景 - -原 `MpScheduleRespVO` 只返回 4 个库级原始字段, C 端小蒙马产品详情页"余多少家庭""余多少可报名"需前端 `max - used` 自算; 即使前端算了, 因 schedules 查询 Redis 缓存 5 分钟 TTL 且下单链路不清缓存, 下单成功后展示余量 5 分钟内仍是旧值。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 小程序查班期列表 | GET | `/mp/product/{id}/schedules` | 响应体新增字段 | `remainParticipants` + `remainFamilies` | - -内部接口行为变化(前端无感, 仅后端服务调用): -- `POST /internal/product/batch/{batchId}/enroll` — 成功后清 `mp:product:schedules:{productId}` 缓存 -- `POST /internal/product/batch/{batchId}/unenroll` — 同上 - ---- - -## 三、接口详情 - -### 1. 查询班期列表 `GET /mp/product/{id}/schedules` - -**VO**: `MpScheduleRespVO` - -#### 响应字段(只列新增) - -| 字段 | 类型 | 说明 | -|------|------|------| -| `remainParticipants` | Integer | **余可报名数**(人数口径) = `maxParticipants - enrolledCount`。`maxParticipants` 为 `null` 或 `0` 时返回 `null` 表示"不限人数"。 | -| `remainFamilies` | Integer | **余家庭数**(房间口径, 1 家庭 ≈ 1 房间起) = `maxRooms - bookedRooms`。`maxRooms` 为 `null` 或 `0` 时返回 `null` 表示"不限家庭"。 | - -#### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "batchId": 2042973109799215105, - "productId": 2042973108708696065, - "batchNo": "Q2026051101", - "batchName": "五一特别班", - "adultPrice": 2999.00, - "childPrice": 1599.00, - "departureDate": "2026-05-01", - "endDate": "2026-05-05", - "enrollmentDeadline": "2026-04-30", - "maxParticipants": 23, - "enrolledCount": 2, - "maxRooms": 19, - "bookedRooms": 1, - "remainParticipants": 21, - "remainFamilies": 18, - "batchStatus": "ENROLLING" - } - ] -} -``` - -"不限"场景示例: -```json -{ - "maxParticipants": null, - "enrolledCount": 0, - "maxRooms": 0, - "bookedRooms": 0, - "remainParticipants": null, - "remainFamilies": null -} -``` - -前端建议: 判空优先于展示。`null` 表示"不限/无上限"(对应 UI 可显示 "不限" 或隐藏)。 - ---- - -## 四、前端接入点 - -- **下单前**: 展示 `remainFamilies` 代替原本的 `maxRooms - bookedRooms` 自算逻辑 -- **下单后**: 无需改动逻辑。下单调用订单服务后, 再次 `GET /mp/product/{id}/schedules` 返回值已即时反映新余量(无需等 5 分钟缓存过期) -- **首次详情展示**: 若对应字段为 `null`, 当作"不限/无上限", UI 做相应文案或隐藏 - ---- - -## 五、不向后兼容风险 - -无。纯响应体新增字段, 未改任何现有字段类型/语义。 diff --git a/changelogs/2026-04/2026-04-23_mp-refund-preview-ratio-fix.md b/changelogs/2026-04/2026-04-23_mp-refund-preview-ratio-fix.md deleted file mode 100644 index 4e2abaa..0000000 --- a/changelogs/2026-04/2026-04-23_mp-refund-preview-ratio-fix.md +++ /dev/null @@ -1,56 +0,0 @@ -# 微信小程序 · 退款预览 refundRatio 之前永远为 0 — 已修复 - -- **变更日期**: 2026-04-23 -- **PR**: #1313 -- **端**: 微信小程序（管理端不涉及） -- **影响面**: 订单退款预览弹窗 -- **兼容性**: **纯 bug 修复**，接口/字段/调用方式零变化，前端无需改动 - ---- - -## 变化一句话 - -调用微信小程序退款预览接口时，返回的 `refundRatio`（退款比例，如 `50` = 50%）之前**永远返回 0**；现在会按订单实际绑定的退款政策和出发日期返回正确的比例值。 - ---- - -## 相关接口 - -`POST /mp/refund/preview`（实际路径以 Swagger 为准） - -入参结构不变，继续按之前传 `orderId` 即可。 - -返回 `RefundPreviewVO` 里的字段： - -| 字段 | 之前 | 现在 | -|---|---|---| -| `refundRatio` | 恒 `0` | 按退款政策 + 距离出发天数查表得出的真实比例（0~100）| -| `refundAmount` | 基于 ratio=0 计算 → 恒 `0` | 按真实比例计算 | -| 其它字段 | 正常 | 不变 | - ---- - -## 根因（一句话，前端可忽略） - -微信小程序侧 Feign 只传了 `orderId`，后端 Service 期望同时传 `policyId/paidAmount/departureDate` 才能匹配策略；旧版直接拿 null 去查，匹配不到策略导致 ratio=0。本次后端按 `orderId` 反查订单主表自动补齐这些参数。 - ---- - -## 不影响范围 - -- 管理端退款预览（`/admin/refund/preview`）已经传齐参数，**零影响** -- 实际退款提交流程（preview 之后的 `apply / approve`）**零影响** -- 退款政策、订单金额、已付金额等字段**零影响** - ---- - -## 建议前端验收一个点 - -之前因为 ratio 恒 0 导致"退款弹窗金额显示 0、用户不敢点"的场景，现在应回到正常金额。发布后请重点点一次"申请退款"弹窗确认数字正确。 - ---- - -## 相关 - -- PR：[wx/HL#1313](https://git.1814.love:8443/wx/HL/pulls/1313) -- 部署：`hl-order-service-v2`（8094） diff --git a/changelogs/2026-04/2026-04-23_mp-service_contract-insurance-api-inventory.md b/changelogs/2026-04/2026-04-23_mp-service_contract-insurance-api-inventory.md deleted file mode 100644 index 9489097..0000000 --- a/changelogs/2026-04/2026-04-23_mp-service_contract-insurance-api-inventory.md +++ /dev/null @@ -1,321 +0,0 @@ -# mp-service: 保险/合同详情 5 个接口梳理 + 合同接口返回值强类型化 - -> **服务** hl-mp-service（端口 8085）→ 透传 hl-order-service-v2（端口 8094） -> **PR**: wx/HL#1314 · **Issue**: wx/HL#1312 -> **日期**: 2026-04-23 -> **影响范围**: C 端「订单详情页」保险详情弹窗、合同详情、保单 PDF 下载 - ---- - -## ⚠️ 关键变化 - -合同相关 3 个接口（`GET /mp/contract/list` / `GET /mp/contract/{id}` / `GET /mp/contract/by-order/{orderId}`）的返回值类型从后端弱类型 `Map<String, Object>` 改为具名 VO（`MpContractVO` / `MpContractDetailVO`）。**JSON 结构与字段名均未改变**，Swagger 上能看到具名 schema 了，前端无需改动；本 changelog 重点是一次性把这 5 个接口契约梳理清楚。 - ---- - -## 一、接口清单 - -| # | 接口 | 方法 | 路径 | 返回类型 | -|---|------|------|------|----------| -| 1 | 订单详情聚合（含保险详情） | GET | `/mp/order/{orderId}/dashboard` | `MpOrderDashboardVO`（取 `.insurance` 字段） | -| 2 | 合同详情（按订单） | GET | `/mp/contract/by-order/{orderId}` | `MpContractVO` | -| 3 | 合同详情（按合同 ID） | GET | `/mp/contract/{id}` | `MpContractDetailVO` | -| 4 | 订单保单合并 PDF | GET | `/mp/insurance/policy-pdf/{orderId}` | `Map<String,Object>`（透传 `PolicyShareVO`） | -| 5 | 单张保单下载 | GET | `/mp/insurance/policy/{insuranceOrderId}/download` | `String`（Base64） | - -- 全部需要登录，`userId` 由 mp-service 从 token 中取出后透传给 order-v2 -- 仅 5 号需要 `insuranceOrderId`，该 ID 来自订单详情出行人的 `insurancePolicies[].insuranceOrderId` - ---- - -## 二、接口详情 - -### 1. 保险详情 `GET /mp/order/{orderId}/dashboard` - -保险详情没有独立接口，走订单详情聚合 `MpOrderDashboardVO`，取 `.insurance` 字段（`MpInsuranceDetailVO`）。未投保或查询失败时该字段为 `null`（降级，不阻断页面）。 - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `orderId` | Path | Long | ✅ | 订单 ID | - -#### 出参 `Result<MpOrderDashboardVO>` — 聚合 VO 全字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `order` | `MpOrderDetailVO` | 订单主体（详见 2026-04-17 订单详情 changelog） | -| `preTripChecklist` | `MpPreTripChecklistVO` | 出发准备清单（降级时 null） | -| `files.contract` | `MpContractSummaryVO` | 合同摘要（无合同 null） | -| `files.invoice` | `MpInvoiceSummaryVO` | 发票摘要（未开票 null） | -| `files.insurancePolicyPdfUrl` | `String` | 保单合并 PDF 下载路径，固定为 `/mp/insurance/policy-pdf/{orderId}` | -| `insurance` | `MpInsuranceDetailVO` | **保险详情（本 changelog 重点字段）** | -| `refund` | `RefundVO` | 退款模块（仅取消/退款中状态有值） | - -#### `insurance`（`MpInsuranceDetailVO`）字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `schemeId` | Long | 方案 ID | -| `schemeName` | String | 方案名称 | -| `description` | String | 方案描述 | -| `isOverseas` | Boolean | 是否境外 | -| `totalDays` | Integer | 适用行程天数 | -| `notice` | String | 保险告知状态：`INCLUDED` / `OPTIONAL` / `EXCLUDED` | -| `segments` | `List<CoverageSegment>` | 保障分段列表 | -| `segments[].segmentName` | String | 分段名称 | -| `segments[].dayOffsetStart` | Integer | 起始天 | -| `segments[].dayOffsetEnd` | Integer | 结束天（`-1` = 最后一天） | -| `segments[].productName` | String | 保险产品名称 | -| `segments[].planName` | String | 保险计划名称 | -| `policies` | `List<PolicyItem>` | 投保记录列表（未投保为空数组） | -| `policies[].insuranceOrderId` | Long | 保险订单 ID（用于接口 5 下载） | -| `policies[].policyNo` | String | 保单号 | -| `policies[].productName` | String | 保险产品名称 | -| `policies[].planName` | String | 计划名称 | -| `policies[].premium` | BigDecimal | 保费（元） | -| `policies[].insuredCount` | Integer | 被保人数 | -| `policies[].coverageStartDate` | LocalDate | 保障开始日期 | -| `policies[].coverageEndDate` | LocalDate | 保障结束日期 | -| `policies[].status` | String | 保险状态：`PENDING` / `INSURING` / `INSURED` / `FAILED`（`CANCELLED` 已过滤不返回） | -| `policies[].statusLabel` | String | 状态中文标签 | -| `policies[].insuredPersons` | `List<InsuredPerson>` | 被保人列表 | -| `insuredPersons[].name` | String | 姓名（明文，脱敏由前端处理） | -| `insuredPersons[].idCardType` | String | 证件类型：`ID_CARD` / `PASSPORT` | -| `insuredPersons[].idCardNo` | String | 证件号码（明文） | -| `insuredPersons[].birthday` | LocalDate | 出生日期 | -| `insuredPersons[].gender` | String | `MALE` / `FEMALE` | -| `insuredPersons[].phone` | String | 手机号（明文） | - ---- - -### 2. 合同详情（按订单） `GET /mp/contract/by-order/{orderId}` - -返回订单关联的**最新**有效合同（非作废），一般用于订单详情页的"合同"入口。 - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `orderId` | Path | Long | ✅ | 订单 ID | - -#### 出参 `Result<MpContractVO>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `contractId` | Long | 合同 ID | -| `orderId` | Long | 订单 ID | -| `templateCode` | String | 模板编码 | -| `templateName` | String | 模板名称 | -| `contractNumber` | String | 合同编号 | -| `platform` | String | 签约平台 | -| `contractType` | String | 字典 `contract_type`：`TOUR` / `INSURANCE` | -| `contractTypeLabel` | String | 合同类型标签 | -| `mode` | String | 字典 `contract_mode`：`ONLINE` / `OFFLINE` | -| `modeLabel` | String | 签约模式标签 | -| `status` | String | 字典 `contract_status` | -| `statusLabel` | String | 合同状态标签 | -| `signUrl` | String | 签署 URL | -| `qrCodeUrl` | String | 签署二维码 URL | -| `fileUrl` | String | 合同文件 URL | -| `agencyCode` | String | 旅行社编号 | -| `travelAgencyName` | String | 旅行社名称 | -| `destination` | String | 目的地 | -| `departureDate` | LocalDate | 出发日期 | -| `returnDate` | LocalDate | 返回日期 | -| `totalAmount` | BigDecimal | 合同总金额 | -| `touristCount` | Integer | 出行人数 | -| `contactName` | String | 联系人姓名（明文，脱敏由前端处理） | -| `contactPhone` | String | 联系人电话（明文，脱敏由前端处理） | -| `createTime` | LocalDateTime | 创建时间 | - -无合同时 `data` 为 `null`。 - ---- - -### 3. 合同详情（按合同 ID） `GET /mp/contract/{id}` - -按合同 ID 查完整详情，返回合同基本信息 + 出行人签署详情 + 状态变更日志。 - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `id` | Path | Long | ✅ | 合同 ID | - -#### 出参 `Result<MpContractDetailVO>` - -`MpContractDetailVO` 继承 `MpContractVO`（字段见接口 2），额外字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `supplementaryClause` | String | 补充约定内容 | -| `travelers` | `List<TravelerInfo>` | 出行人列表 | -| `travelers[].travelerId` | Long | 出行人 ID | -| `travelers[].name` | String | 姓名（明文） | -| `travelers[].idCardType` | String | `ID_CARD` / `PASSPORT` | -| `travelers[].idCardNo` | String | 证件号码（明文） | -| `travelers[].phone` | String | 手机号（明文） | -| `travelers[].isSigner` | Boolean | 是否签署人 | -| `statusLogs` | `List<MpContractStatusLogVO>` | 状态变更日志 | -| `statusLogs[].logId` | Long | 日志 ID | -| `statusLogs[].contractId` | Long | 合同 ID | -| `statusLogs[].oldStatus` | String | 旧状态 | -| `statusLogs[].newStatus` | String | 新状态 | -| `statusLogs[].source` | String | 变更来源：`CALLBACK` / `POLLING` / `MANUAL` | -| `statusLogs[].rawPayload` | String | 原始载荷（仅调试用） | -| `statusLogs[].createTime` | LocalDateTime | 创建时间 | - -权限：合同 `userId` 必须与登录用户一致，否则 403。 - ---- - -### 4. 订单保单合并 PDF `GET /mp/insurance/policy-pdf/{orderId}` - -合并订单下所有出行人的有效保单为一个 PDF，返回 Base64。 - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `orderId` | Path | Long | ✅ | 订单 ID | - -#### 出参 `Result<Map<String,Object>>`（BFF 当前透传 order-v2 `PolicyShareVO`） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `pdfBase64` | String | 合并后的保单 PDF（Base64 编码） | -| `personName` | String | 出行人姓名（订单范围分享时一般为空/null） | -| `policyCount` | Integer | 成功合并的保单数量 | -| `failedCount` | Integer | 下载失败的保单数量 | - ---- - -### 5. 单张保单下载 `GET /mp/insurance/policy/{insuranceOrderId}/download` - -下载指定保险订单的单张保单 PDF，返回 Base64 字符串。`insuranceOrderId` 从接口 1 的 `insurance.policies[].insuranceOrderId` 取。 - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| `insuranceOrderId` | Path | Long | ✅ | 保险订单 ID（非订单 ID） | - -#### 出参 `Result<String>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `data` | String | 保单 PDF（Base64 编码） | - ---- - -## 三、响应示例 - -### 接口 2 `GET /mp/contract/by-order/{orderId}` - -```json -{ - "code": 200, - "message": "成功", - "data": { - "contractId": 9001, - "orderId": 20439, - "templateCode": "TOUR_STANDARD", - "templateName": "旅游服务合同（标准版）", - "contractNumber": "HL-2026-0423-0001", - "platform": "fadada", - "contractType": "TOUR", - "contractTypeLabel": "旅游合同", - "mode": "ONLINE", - "modeLabel": "线上签署", - "status": "SIGNED", - "statusLabel": "已签署", - "signUrl": "https://sign.fadada.com/xxx", - "qrCodeUrl": "https://cdn.1814.love/qr-9001.png", - "fileUrl": "https://cdn.1814.love/contract-9001.pdf", - "agencyCode": "HULAL001", - "travelAgencyName": "呼籁旅行", - "destination": "呼伦贝尔", - "departureDate": "2026-07-01", - "returnDate": "2026-07-07", - "totalAmount": "12600.00", - "touristCount": 4, - "contactName": "张三", - "contactPhone": "13800138000", - "createTime": "2026-04-20 10:30:00" - }, - "success": true -} -``` - -### 接口 4 `GET /mp/insurance/policy-pdf/{orderId}` - -```json -{ - "code": 200, - "message": "成功", - "data": { - "pdfBase64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeX...（截断）", - "personName": null, - "policyCount": 4, - "failedCount": 0 - }, - "success": true -} -``` - ---- - -## 四、边界行为 - -- 未登录 → 401（网关拦截） -- 订单/合同不属于当前 `userId` → 403 -- 订单无合同（接口 2）→ `data: null` -- 订单未投保（接口 1 的 `insurance` 字段）→ `insurance: null`，不阻断页面 -- 保单 PDF 下载失败（接口 4）→ `failedCount > 0`，`pdfBase64` 仍返回已合并部分；下游整体失败时 BFF 返 `500` -- 合同服务整体不可用（接口 2/3）→ BFF 返 `500 合同服务不可用，请稍后重试` - ---- - -## 五、不影响范围 - -- **仅影响**：C 端订单详情页的保险详情弹窗 / 合同详情 / 保单 PDF 下载入口 -- **零影响**： - - 下单、支付、退款、发票所有接口 - - 合同列表 `GET /mp/contract/list`（未列出，字段同接口 2 `MpContractVO`） - - 管理后台合同/保险所有接口（不走 `/mp/` 前缀） - - JSON 字段名与取值逻辑（本次仅后端 VO 强类型化） - ---- - -## 六、相关历史 PR - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| wx/HL#1314 | wx/HL#1312 | 合同接口返回值从 Map 改为强类型 VO（本 PR） | ✅ 最新 | -| 2026-04-17 `mp-order-detail-refactor` | - | 订单详情聚合 VO `MpOrderDashboardVO` | ✅ 有效 | - ---- - -## 七、代码位置 - -- Controller - - `hl-mp-service` · `com.hulalv.mp.controller.MpOrderController#getOrderDashboard` - - `hl-mp-service` · `com.hulalv.mp.controller.MpContractController` - - `hl-mp-service` · `com.hulalv.mp.controller.MpInsuranceController` -- VO - - `hl-mp-service` · `com.hulalv.mp.vo.MpOrderDashboardVO` - - `hl-mp-service` · `com.hulalv.mp.vo.MpInsuranceDetailVO` - - `hl-mp-service` · `com.hulalv.mp.vo.MpContractVO` / `MpContractDetailVO` / `MpContractStatusLogVO` -- 下游 - - `hl-order-service-v2` · `com.hulalv.contract.controller.internal.InternalMpContractController` - - `hl-order-service-v2` · `com.hulalv.insurance.controller.internal.InternalInsuranceController` - - `hl-order-service-v2` · `com.hulalv.insurance.vo.PolicyShareVO` - ---- - -## 八、相关文档 - -- 关联 Issue: [wx/HL#1312](https://git.1814.love:8443/wx/HL/issues/1312) -- 关联 PR: [wx/HL#1314](https://git.1814.love:8443/wx/HL/pulls/1314) -- 订单详情聚合 VO 参考: `changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md` diff --git a/changelogs/2026-04/2026-04-23_order-complaint-full-contract.md b/changelogs/2026-04/2026-04-23_order-complaint-full-contract.md deleted file mode 100644 index b327c50..0000000 --- a/changelogs/2026-04/2026-04-23_order-complaint-full-contract.md +++ /dev/null @@ -1,420 +0,0 @@ -# 投诉模块完整接口契约（前端对接专用） - -- **日期**: 2026-04-23（更新版，替代 2026-04-23_order-complaint-module.md 的简版） -- **相关 PR**: #1221 主 + #1222 #1223 #1225 #1235（hotfix）+ Nacos SMS_505775156 -- **Closes**: #1220 -- **短信模板**: `SMS_505775156`（阿里云审核通过，签名"呼籁旅行"） -- **网关前缀**: `https://api.test.1814.love:9443`（测试）/ `https://api.1814.love`（正式） -- **鉴权**: - - 小程序 `/mp/**`：`Authorization: Bearer <mp-token>`（userId 由网关注入 request.userId） - - 管理端 `/admin/**`：`Authorization: Bearer <admin-token>` + 按钮权限 - ---- - -## 📚 目录 - -- [A. 字典](#a-字典) -- [B. 小程序端 5 接口](#b-小程序端-5-接口) -- [C. 管理端 2 接口](#c-管理端-2-接口) -- [D. 统一错误码表](#d-统一错误码表) -- [E. 前端状态机](#e-前端状态机) -- [F. 通知链路（后端自动，前端参考）](#f-通知链路) - ---- - -## A. 字典 - -```http -GET /admin/dict/data/complaint_type -Authorization: Bearer <admin-token> - -响应 data: -[ - {"dictDataId":90401,"dictValue":"ITINERARY","dictLabel":"行程","sortOrder":1,"status":"ACTIVE"}, - {"dictDataId":90402,"dictValue":"VEHICLE","dictLabel":"车","sortOrder":2,"status":"ACTIVE"}, - {"dictDataId":90403,"dictValue":"HOTEL","dictLabel":"房","sortOrder":3,"status":"ACTIVE"}, - {"dictDataId":90404,"dictValue":"OTHER","dictLabel":"其他","sortOrder":4,"status":"ACTIVE"} -] -``` - -小程序端无单独字典接口；响应里已内嵌 `types:[{code,label}]` 结构，**前端不需要自己 map**。 - ---- - -## B. 小程序端 5 接口 - -统一前缀：`/mp/complaint`。全部接口不需要前端传 `userId`，网关从 Token 注入。 - -### B1. `POST /mp/complaint/create` — 发起投诉 - -**请求 body**（`MpComplaintSaveReqVO`）： - -| 字段 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------| -| `orderId` | Long | ✅ | - | 订单 ID（序列化为 String，前端直接透传） | -| `dayNumber` | Integer | ❌ | null/0/≥1 | null 或 0 = 整程投诉；≥1 = 第 N 天 | -| `types` | `List<String>` | ✅ | 非空，元素∈{ITINERARY,VEHICLE,HOTEL,OTHER} | 可多选 | -| `content` | String | ✅ | 1~500 字 | 投诉文字 | -| `imageUrls` | `List<String>` | ❌ | ≤9 项，单个 URL ≤500 字符 | OSS 直传后的 URL | -| `videoUrl` | String | ❌ | ≤500 字符 | 单个视频 URL | - -**请求示例**： - -```http -POST /mp/complaint/create -Authorization: Bearer eyJ... -Content-Type: application/json - -{ - "orderId": "7123456789012345678", - "dayNumber": 2, - "types": ["ITINERARY", "VEHICLE"], - "content": "第二天景点讲解员迟到半小时，车辆空调坏了", - "imageUrls": [ - "https://cdn.hulalv.com/complaint/2026/04/abc.jpg", - "https://cdn.hulalv.com/complaint/2026/04/def.jpg" - ], - "videoUrl": null -} -``` - -**响应**： - -```json -{"code":200,"message":"成功","data":"8123456789012345678","success":true} -``` - -`data` 是 complaintId（Long 序列化为 String）。 - -**错误码**：20301（10 分钟冷却）/ 20302（订单非本人）/ 20303（dayNumber 超范围，不能投诉未发生的天） - ---- - -### B2. `POST /mp/complaint/{id}/cancel` — 撤回投诉 - -**路径参数**：`id` = 投诉 ID - -**请求 body**：无 - -**响应**： - -```json -{"code":200,"message":"成功","data":null,"success":true} -``` - -**错误码**：20304（不存在或已撤回）/ 20305（非本人）/ 20306（创建已超 10 分钟） - -**规则**：仅**创建后 10 分钟内**且**本人**可撤回；软删 `deleted_at` + `status=WITHDRAWN`；企微+短信已发出**不撤回**（定制师需要自行忽略已收到的通知）。 - ---- - -### B3. `GET /mp/complaint/my-page` — 我的投诉分页 - -**Query**： - -| 参数 | 类型 | 默认 | 约束 | -|------|------|------|------| -| `pageNo` | Integer | 1 | ≥1 | -| `pageSize` | Integer | 20 | 1~50 | - -**响应**（分页 `PageResult<MpComplaintSimpleRespVO>`）： - -```json -{ - "code":200,"message":"成功","success":true, - "data":{ - "list":[ - { - "id":"8123456789012345678", - "orderId":"7123456789012345678", - "orderNo":"HL20260422001", - "groupCode":"TG001", - "dayNumber":2, - "dayLabel":"第2天", - "types":[ - {"code":"ITINERARY","label":"行程"}, - {"code":"VEHICLE","label":"车"} - ], - "contentSnippet":"第二天景点讲解员迟到半小时,沟通后...", - "imageCount":3, - "videoCount":0, - "isResolved":false, - "resolutionEditCount":0, - "createdAt":"2026-04-23 10:15:30" - } - ], - "total":"8" - } -} -``` - -列表按 `createdAt` **倒序**。 - ---- - -### B4. `GET /mp/complaint/{id}` — 投诉详情 - -**响应**（`MpComplaintRespVO`，20 字段）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | Long | 投诉 ID | -| `orderId` / `orderNo` / `groupCode` | - | 订单冗余信息 | -| `dayNumber` | Integer | 0=整程 / ≥1=具体天 | -| `dayLabel` | String | "整程" 或 "第 N 天" | -| `types` | `List<{code,label}>` | 投诉类型列表 | -| `content` | String | 完整文字（区别于 list 的 snippet） | -| `contentSnippet` | String | 前 50 字 | -| `imageUrls` | `List<String>` | 图片 URL 列表 | -| `videoUrl` | String | 视频 URL 或 null | -| `imageCount` / `videoCount` | Integer | 数量（便于列表快速渲染） | -| `resolutionNote` | String | 解决备注（客户本人填） | -| `resolutionEditCount` | Integer | 已修改次数 0~2 | -| `resolutionUpdatedAt` | DateTime | 最近一次修改时间 | -| `isResolved` | Boolean | resolutionNote 非空 | -| **`canCancel`** | Boolean | 是否可撤回（创建 < 10min 内 + status=ACTIVE） | -| **`canEditResolution`** | Boolean | 是否可填/改解决备注（editCount < 2） | -| `status` | String | ACTIVE / WITHDRAWN | -| `createdAt` | DateTime | 创建时间 | - -**错误码**：20304（不存在/已撤回）/ 20305（非本人） - -**⚠️ 前端注意**：`canCancel` / `canEditResolution` 是**后端计算返回**，前端**直接用**，**不要自己根据 createdAt 算时间差**（时钟偏移问题）。 - ---- - -### B5. `PUT /mp/complaint/{id}/resolution` — 填/改解决备注 - -**请求 body**： - -| 字段 | 类型 | 必填 | 约束 | -|------|------|------|------| -| `resolutionNote` | String | ✅ | 1~500 字 | - -**请求示例**： - -```http -PUT /mp/complaint/8123456789012345678/resolution -Authorization: Bearer eyJ... -Content-Type: application/json - -{"resolutionNote":"已与定制师电话沟通,明天补偿安排"} -``` - -**响应**： - -```json -{"code":200,"message":"成功","data":1,"success":true} -``` - -`data` = 剩余可编辑次数（2 - newEditCount）。0 = 已锁定不能再改。 - -**错误码**：20305（非本人）/ 20307（已达 2 次上限） - -**规则**：最多写入 **2 次**（一次填 + 一次改）；达 2 次后 `canEditResolution=false`。 - ---- - -## C. 管理端 2 接口 - -统一前缀：`/admin/complaint`。**只读**，无写操作。 - -**权限**（按钮权限码）： -- `complaint:list:self`（定制师）— 后端强制在 SQL 里注入 `WHERE customizer_id = currentAdminId`，**前端不需要传 customizerId** -- `complaint:list:all`（超管/主管）— 无过滤 -- `complaint:detail` — 详情 - -角色默认绑定：`SUPER_ADMIN(1)` / `ADMIN(2)` → `:all + :detail`；`CUSTOMIZER(3)` → `:self + :detail` - -### C1. `GET /admin/complaint/page` — 分页列表 - -**Query**（`ComplaintPageReqVO`）： - -| 参数 | 类型 | 默认 | 说明 | -|------|------|------|------| -| `pageNo` | Integer | 1 | - | -| `pageSize` | Integer | 20 | - | -| `keyword` | String | - | 订单号 / 昵称 / 内容 **模糊** 匹配 | -| `orderNo` | String | - | 订单号 **精确** 匹配 | -| `groupCode` | String | - | 团号 **精确** | -| `customizerNickname` | String | - | 定制师昵称 **模糊** | -| `types` | `List<String>` | - | 多选，如 `?types=ITINERARY&types=VEHICLE` | -| `isResolved` | Boolean | - | true=已解决（备注非空）/ false=未解决 / 不传=全部 | -| `dateFrom` | LocalDate | - | `yyyy-MM-dd`，含当天 | -| `dateTo` | LocalDate | - | `yyyy-MM-dd`，含当天 | -| `dayScope` | String | ALL | `ALL` / `WHOLE`（仅整程）/ `SPECIFIC`（仅指定天） | - -**请求示例**： - -```http -GET /admin/complaint/page?pageNo=1&pageSize=20&types=ITINERARY&isResolved=false&dateFrom=2026-04-01&dateTo=2026-04-30&dayScope=ALL -Authorization: Bearer <admin-token> -``` - -**响应**（`PageResult<ComplaintRespVO>`）。单项字段见 C2，列表里 `contactPhoneDecrypted` **为 null**（仅详情按权限才返明文）。 - -### C2. `GET /admin/complaint/{id}` — 详情 - -**响应**（`ComplaintRespVO`，完整字段）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` / `orderId` / `orderNo` / `groupCode` | - | 基础 | -| `customizerId` / `customizerNickname` | - | 定制师 | -| `userId` / `userNickname` | - | 投诉人 | -| `contactName` | String | 联系人姓名 | -| **`contactPhoneMasked`** | String | 脱敏后 4 位，如 `***1234`（**永远返**） | -| **`contactPhoneDecrypted`** | String | 明文，**仅有权时返**；否则 null | -| `dayNumber` / `dayLabel` | - | 天维度 | -| `types` | `List<{code,label}>` | | -| `content` | String | 完整文字 | -| `contentSnippet` | String | 前 50 字（列表用） | -| `imageUrls` | `List<String>` | | -| `videoUrl` | String | | -| `resolutionNote` / `resolutionEditCount` / `resolutionUpdatedAt` / `isResolved` | - | 解决备注（客户本人写） | -| **`notifyWechatStatus`** | String | `PENDING` / `SUCCESS` / `FAIL` / `SKIP` | -| **`notifyWechatError`** | String | FAIL 时的错误信息 | -| **`notifySmsStatus`** | String | 同上 | -| **`notifySmsError`** | String | 同上 | -| `status` | String | `ACTIVE` / `WITHDRAWN` | -| `createdAt` / `updatedAt` | DateTime | | -| `canRemindCustomizer` | Boolean | **永远 false**（预留，MVP 管理端只读） | - -**⚠️ 前端展示建议**： -- 列表页只显示 `contactPhoneMasked`；详情页**如果** `contactPhoneDecrypted` 非空则按"点击查看"展开，否则灰显 -- `notifyWechatStatus` / `notifySmsStatus` 用小圆点 + 中文标签渲染（SUCCESS 绿 / FAIL 红 / SKIP 灰 / PENDING 黄） - ---- - -## D. 统一错误码表 - -| Code | 常量 | 场景 | 附加字段 | 前端应做 | -|------|------|------|---------|---------| -| 20301 | `ERR_COMPLAINT_COOLDOWN` | 同 user+order+day 10 分钟内重复投诉 | `remainingSeconds`（业务码信息里） | 展示"请 X 秒后再试"倒计时 | -| 20302 | `ERR_ORDER_NOT_OWN` | 订单不属于当前 user | - | 提示"订单不存在或无权" | -| 20303 | `ERR_DAY_NUMBER_INVALID` | dayNumber 超出已发生范围 | `maxDayNumber` | 限制前端表单 dayNumber 选择范围 | -| 20304 | `ERR_COMPLAINT_NOT_FOUND` | 投诉不存在或已撤回 | - | 跳回我的投诉列表 | -| 20305 | `ERR_COMPLAINT_NOT_OWN` | 非本人投诉 | - | 提示"无权限" | -| 20306 | `ERR_WITHDRAW_EXPIRED` | 撤回已超 10 分钟 | - | 隐藏撤回按钮 | -| 20307 | `ERR_RESOLUTION_LOCKED` | 解决备注已填满 2 次 | - | 隐藏"再修改一次"按钮 | - -**响应结构统一**： - -```json -{"code":20301,"message":"10 分钟内已投诉过该天行程","data":null,"success":false} -``` - -HTTP 状态码恒为 **200**（项目规范），**只看 body 的 `code`**。 - ---- - -## E. 前端状态机 - -### 小程序端客户视角 - -``` -[订单详情] - │ - ├── 点击"整程投诉" → dayNumber=null → POST /create - └── 点击第 N 天的"投诉" → dayNumber=N → POST /create - │ - ├── 20301 → 展示冷却倒计时 - ├── 20303 → 提示"尚未开始的天无法投诉" - └── 200 → 跳转[我的投诉列表] - │ - └── 点某条 → [详情] - ├── canCancel=true → 展示"撤回"按钮 - │ 点击 → POST /{id}/cancel - │ ├── 20306 → 按钮已过期灰掉 - │ └── 200 → 回列表 - ├── canEditResolution=true → 展示"填/改解决备注"按钮 - │ 点击 → 弹编辑框 → PUT /{id}/resolution - │ ├── 20307 → 灰掉按钮 - │ └── 200 → 刷新详情 - └── 只读展示 -``` - -### 管理端定制师视角 - -``` -[投诉管理菜单] → /admin/complaint/page - │ - ├── 看到所有自己负责订单的投诉（后端按 :self 过滤） - ├── 顶部筛选：订单号 / 团号 / 类型 / 是否已解决 / 时间 / 整程or指定天 - └── 点某条 → [详情]（只读，无任何写按钮） - ├── 查看完整文字 / 图片预览 / 视频播放 - ├── 看客户写的 resolutionNote（若有） - └── 看 notifyWechatStatus / notifySmsStatus 确认是否收到通知 -``` - -### 管理端超管视角 - -同上，但看到**全部投诉**（后端按 `:all` 不加 customizerId 过滤）。 - ---- - -## F. 通知链路 - -**前端无感知**，此处仅说明供你理解触发场景： - -- 投诉创建 `POST /mp/complaint/create` 成功 → afterCommit 触发双链路 @Async - - **企微**：发给 `order.customizerId → admin_user.enterprise_wechat_id → wechat_user.userid` 对应的定制师，文案： - ``` - 【客户投诉】 - 团号：TG001 - 订单号：HL20260422001 - 联系人：张三 13800138000 - 第 2 天 · 行程/车 - 内容：第二天景点讲解员迟到半小时,沟通后...（前 50 字） - 图片 3 视频 0 - ``` - - **短信**（阿里云 `SMS_505775156`，签名 呼籁旅行）： - ``` - 【呼籁旅行】团号TG001订单HL20260422001第2天收到客户投诉(行程/车)，请登录后台查看。 - ``` -- 定制师未绑企微（`enterprise_wechat_id` 空）→ `notifyWechatStatus=SKIP` -- 定制师无手机号（`wechat_user.mobile` 空）→ `notifySmsStatus=SKIP` -- 任一链路失败 → status=FAIL + error 字段写入，不阻塞主流程 -- **前端不需要关心重试**（后端无自动重试，定制师可通过"我的投诉"列表底部的创建时间对比企微收件时间自行排查） - ---- - -## G. 前端对接清单 - -### 管理端（hl-ui admin） -- [ ] 菜单 `投诉管理`（1250 系列，侧边栏末尾）自动由 sys_menu 返回渲染 -- [ ] 列表页：表格 + 7 个筛选条件（上方） + dayScope 切换标签 -- [ ] 详情页（Drawer 或独立页）：完整展示 C2 所有字段 -- [ ] 图片预览走 `el-image` 或同级组件 -- [ ] 视频预览 `<video controls>` -- [ ] `contactPhoneDecrypted` 使用"点击查看"折叠 -- [ ] `notifyWechatStatus` / `notifySmsStatus` 状态圆点 -- [ ] Long 字段（id/orderId/userId/customizerId）**不要**做数字运算，直接当字符串透传 - -### 小程序端（hl-mp） -- [ ] 订单详情页每日卡片右上新增"投诉"入口 → dayNumber=N -- [ ] 订单详情页底部新增"整程投诉"入口 → dayNumber=null -- [ ] 投诉表单页：多选类型（chip 或 checkbox）+ 文字（counter 0/500）+ 图片上传（OSS 直传，最多 9）+ 视频上传（最多 1） -- [ ] 冷却 20301：显示"{remainingSeconds} 秒后可再次投诉"倒计时 Toast -- [ ] "我的投诉"入口（我的 tab 底部 或 订单详情页按钮）→ 列表 → 详情 -- [ ] 详情页按 `canCancel` / `canEditResolution` 动态显隐按钮 -- [ ] 撤回成功 → 回列表 + 自动移除该条（软删不再返回） - ---- - -## H. 冷启动兜底 - -- 投诉表 `order_complaint` 已在测试服 `hl_order_service_v2` 库就绪（29 字段 + UNIQUE 防刷索引） -- 字典 `complaint_type` + 菜单 1250 系列已执行 -- Nacos `aliyun.sms.template.complaint-notify: SMS_505775156` 已热更新（测试服） -- 正式服上线前需运维同步 Nacos 一次（阿里云账号跨环境共享，模板码通用） - ---- - -## 变更记录 - -| 日期 | 变更 | -|------|------| -| 2026-04-23 | 阿里云模板审核通过 `SMS_505775156`，Nacos 热更新，短信真发 | -| 2026-04-23 | 完整接口契约本文件（替代简版） | -| 2026-04-22 | 投诉模块上线（PR #1221），mp 5 接口 + admin 2 接口 + 字典菜单 | diff --git a/changelogs/2026-04/2026-04-23_order-complaint-module.md b/changelogs/2026-04/2026-04-23_order-complaint-module.md deleted file mode 100644 index 82787f3..0000000 --- a/changelogs/2026-04/2026-04-23_order-complaint-module.md +++ /dev/null @@ -1,204 +0,0 @@ -# 订单投诉模块 - 小程序发起 + 后台只读列表 - -- **变更日期**: 2026-04-23 -- **PR**: #1221（主） + #1222/#1223/#1225/#1235（配套 hotfix） -- **Closes**: #1220 -- **影响面**: 小程序端（新增 5 接口） + 管理端（新增 2 接口 + 1 菜单） -- **兼容性**: **纯新增**，无既有接口变更 - ---- - -## 🎯 业务背景 - -客户在行程中任意一天（含"整程"）可发起投诉；后端自动通过**企业微信 + 短信**双链路通知订单负责的定制师（管理员）。管理后台侧边栏新增"投诉管理"一级菜单，定制师只读查看自己订单的投诉，超管/主管看全部。无审批流，客户本人可填/改解决备注。 - ---- - -## 🛒 小程序端接口（/mp/complaint/**） - -统一前缀 `/mp/complaint`，userId 从网关注入的 token 取，前端无需传。 - -### 1. 发起投诉 - -```http -POST /mp/complaint/create -Authorization: Bearer <mp-token> -Content-Type: application/json - -{ - "orderId": 99988, - "dayNumber": 2, // 0 或 null = "整程投诉"; 1..N = 第 N 天 - "types": ["ITINERARY", "VEHICLE"], // 字典 complaint_type: ITINERARY / VEHICLE / HOTEL / OTHER - "content": "第二天酒店入住流程混乱...", // 必填 1~500 字 - "imageUrls": ["https://oss/.../1.jpg"], // ≤9,前端 OSS 直传后给后端 URL - "videoUrl": "https://oss/.../1.mp4" // 可空 ≤1 -} - -返回: -{"code":200,"data":{"complaintId":1024},"success":true} -``` - -**错误码**： -| Code | 含义 | 附加字段 | -|------|------|------| -| 20301 | 10 分钟冷却中（同一单同一天） | `remainingSeconds` | -| 20302 | 订单不属于当前用户 | — | -| 20303 | dayNumber 超出已发生范围 | `maxDayNumber` | - -### 2. 撤回投诉（10 分钟内本人可） - -```http -POST /mp/complaint/{id}/cancel -返回: {"code":200,"data":{"success":true}} - -错误: -- 20305 非本人投诉 -- 20306 已超 10 分钟 -``` - -### 3. 我的投诉列表 - -```http -GET /mp/complaint/my-page?pageNo=1&pageSize=10 - -返回: Page<MpComplaintSimpleRespVO>: -- id / orderNo / groupCode -- dayNumber / dayLabel（"整程" 或 "第N天"） -- types: [{code, label}] -- contentSnippet（前 50 字） -- imageCount / videoCount -- isResolved（resolutionNote 非空） -- resolutionEditCount / createdAt -``` - -### 4. 投诉详情 - -```http -GET /mp/complaint/{id} - -返回 MpComplaintRespVO（在 SimpleRespVO 基础上 + content/imageUrls/videoUrl/resolutionNote/resolutionUpdatedAt/canCancel/canEditResolution） - -错误: 20304 不存在或已撤回 / 20305 非本人 -``` - -### 5. 填/改解决备注（最多 2 次） - -```http -PUT /mp/complaint/{id}/resolution -{ - "resolutionNote": "已与定制师沟通完毕" -} - -返回: {"code":200,"data":{"editCountLeft":1}} - -错误: -- 20305 非本人 -- 20307 已达 2 次上限 -``` - ---- - -## 🧑💼 管理端接口（/admin/complaint/**，只读） - -### 1. 投诉列表（含权限过滤） - -```http -GET /admin/complaint/page?pageNo=1&pageSize=10&keyword=&orderNo=&groupCode=&customizerNickname=&types=ITINERARY&isResolved=false&dateFrom=2026-04-01&dateTo=2026-04-23&dayScope=ALL - -dayScope: ALL(默认) / WHOLE(整程=dayNumber=0) / SPECIFIC(具体天>=1) - -返回 Page<ComplaintRespVO>: -- id / orderId / orderNo / groupCode -- customizerId / customizerNickname -- userId / userNickname -- contactName / contactPhoneMasked（列表脱敏后 4 位） -- dayNumber / dayLabel -- types / content / contentSnippet / imageUrls / videoUrl -- resolutionNote / resolutionEditCount / resolutionUpdatedAt / isResolved -- notifyWechatStatus / notifySmsStatus（PENDING/SUCCESS/FAIL/SKIP） -- status / createdAt / updatedAt -``` - -### 2. 投诉详情 - -```http -GET /admin/complaint/{id} - -同 Page 返回结构 + contactPhoneDecrypted（明文，仅 complaint:detail 权限 + 非 :self 或本人订单才返） -``` - -### 3. 权限模型（R4） - -| 按钮权限 | 效果 | -|---------|------| -| `complaint:list:self` | 定制师：强制 SQL WHERE customizer_id = currentAdminId | -| `complaint:list:all` | 超管/主管：无过滤 | -| `complaint:detail` | 查看详情（基础权限） | - -已配菜单 + 角色绑定： -- SUPER_ADMIN(1) / ADMIN(2) → :all + :detail -- CUSTOMIZER(3) → :self + :detail - ---- - -## 🔔 通知链路（后端自动，前端不关心） - -投诉创建成功后 `afterCommit` → 异步双链路发给 `order.customizerId`： - -- **企业微信**（已有 WechatMessageDTO + MQ 优先 / Feign 降级）： - ``` - 【客户投诉】 - 团号：NM20260422001 - 订单号：DD20260422001 - 联系人：张三 13800138000 - 第 2 天 · 行程/车 - 内容：第二天酒店入住流程混乱（50字摘要） - 图片 3 视频 0 - ``` -- **短信**（阿里云模板 `aliyun.sms.template.complaint-notify`，签名"呼籁旅行"）： - ``` - 【呼籁旅行】团号${groupCode}订单${orderNo}${day}收到客户投诉(${type})，请登录后台查看。 - ``` - ⚠️ 当前测试服 `SMS_MOCK_TBD`（不真发），运营去阿里云控制台申请模板后 Nacos 替换即生效。 - ---- - -## 📂 数据字典（已执行） - -- `complaint_type`：ITINERARY=行程 / VEHICLE=车 / HOTEL=房 / OTHER=其他 -- 菜单 `投诉管理`（1250 系列，侧边栏末尾压底） - ---- - -## 🎨 前端对接清单 - -### 管理端（hl-ui admin） -- [ ] 侧边栏自动渲染"投诉管理"（后端 menu tree 已返回） -- [ ] 列表页：表格 + 筛选（6 条件 + dayScope） -- [ ] 详情页（只读）：图/视频预览 + 完整文字 + 解决备注（客人本人写的）+ 通知状态 -- [ ] 字段精度：id/orderId 全部 Long 序列化为 String（防 JS 精度丢失，沿用项目全局 Jackson） -- [ ] 按钮权限：根据登录人 roleCodes 走 `complaint:list:self` 或 `:all` 两套菜单，无管理操作按钮 - -### 小程序端（hl-mp） -- [ ] 订单详情页"整程投诉"入口（dayNumber=null/0） -- [ ] 每日行程卡片"本日投诉"入口（dayNumber=具体天） -- [ ] 投诉表单：类型多选 + 文字（1~500）+ OSS 直传图片（≤9）/ 视频（≤1） -- [ ] 冷却拦截：20301 时展示"10 分钟后再试，剩余 {remainingSeconds}s" -- [ ] "我的投诉"列表 + 详情 + canCancel 显示撤回按钮 + canEditResolution 显示"填写解决备注" - ---- - -## ⚠️ 注意 - -- 投诉表 `order_complaint` 已在测试服 `hl_order_service_v2` 建好（29 字段 + UNIQUE 防刷 + 4 索引） -- 企微通知依赖 `order.customizerId → admin_user.enterprise_wechat_id → wechat_user.mobile/name`，定制师未绑企微则自动 SKIP 短信/企微两路 -- 同一用户 + 同一订单 + 同一 dayNumber 10 分钟只能一次（Redis SETNX + DB UNIQUE 双层兜底） - ---- - -## 🚨 需要后端重启的服务（已完成，此处仅记录） - -- hl-user-service（Feign: getAdminNotifyProfile + sendComplaintSms + 字典菜单） -- hl-order-service-v2（投诉主逻辑 + admin controller + internal api） -- hl-mp-service（MpComplaintController + Feign client + VO） -- hl-gateway（admin-complaint-service 路由） diff --git a/changelogs/2026-04/2026-04-23_order-v2_surcharge-discount-source-hide-delete.md b/changelogs/2026-04/2026-04-23_order-v2_surcharge-discount-source-hide-delete.md deleted file mode 100644 index 42d88bb..0000000 --- a/changelogs/2026-04/2026-04-23_order-v2_surcharge-discount-source-hide-delete.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -date: 2026-04-23 -type: feat -scope: order-service-v2 -pr: "#1262" -issue: "#1257" -breaking: false -audience: [hl-ui] ---- - -# 费用增加项 / 折扣列表 VO 新增 source 字段;ROOM_UPGRADE 条目需隐藏删除/修改按钮 - -## 需求背景 - -配房「差价确认」弹窗确认提交后,后端自动按总差价符号分流写入: -- 正差价 → `order_surcharge` 新增 1 条 `name="升级房型"` -- 负差价 → `order_discount` 新增 1 条 `name="房间优惠"` - -这些**自动生成的条目**用户不能手动删除/修改,**必须通过重新配房**自动清除。因此前端需要在列表渲染时识别并隐藏这些条目的操作按钮。 - -## 契约变更(增量,非 breaking) - -### `AdminOrderSurchargeVO`(费用增加项) -新增字段: -```json -{ - "source": "MANUAL | ROOM_UPGRADE" -} -``` -- `MANUAL`: 手动添加,照旧显示「删除」「修改」按钮 -- `ROOM_UPGRADE`: 配房差价自动生成,**隐藏**「删除」「修改」按钮 - -### `AdminOrderDiscountVO`(订单折扣) -同上,新增 `source` 字段,枚举值与规则同。 - -### 历史数据 -- 历史手动添加的条目 `source=MANUAL`(DB 默认值),前端行为与旧版一致 -- 新的 `ROOM_UPGRADE` 条目只在本次 PR 部署后、用户触发配房 execute 后才会出现 - -## 相关接口路径(无签名变化) - -- `GET /admin/order/{orderId}/surcharge` — 费用增加项列表(返回的 VO 列表里每条多 `source` 字段) -- `GET /admin/order/{orderId}/discount` — 订单折扣列表(同上) -- `POST /admin/order/{orderId}/surcharge` / `PUT .../{id}` / `DELETE .../{id}` — 手动 CRUD 保持不变(后端不拦截,前端自行根据 source 隐藏入口) -- 配房执行 `PUT /admin/order/{orderId}/hotel-assignment` — 无前端契约变化,但调用成功后下次列表查询会自动带上 ROOM_UPGRADE 条目 - -## 前端改动建议 - -```js -// 渲染按钮前先判 source -{row.source !== 'ROOM_UPGRADE' && <DeleteButton ... />} -{row.source !== 'ROOM_UPGRADE' && <EditButton ... />} - -// 可选:给 ROOM_UPGRADE 条目加个小标签提示"系统自动生成,重新配房后自动更新" -{row.source === 'ROOM_UPGRADE' && <Tag color="blue">自动</Tag>} -``` - -## 验证 - -- 后端 `PR #1262` 本地 curl + 测试服网关 curl 已验证三路径(正/负/零差价) -- 前端可用测试服订单 `2046864526866886657` 走配房流程验证 - -## 相关 - -- 工单: Gitea #1257 -- 后端 PR: #1262 -- 后端 changelog: `hl-backend-changelog/2026-04/2026-04-23_order-v2_room-diff-sync-surcharge-discount.md`(含 DDL + 同事务内分流逻辑) -- 前置: PR #1250(配房差价预览 3 连环 BUG 修复,前端零改动) diff --git a/changelogs/2026-04/2026-04-23_supplement-save-valid-effective.md b/changelogs/2026-04/2026-04-23_supplement-save-valid-effective.md deleted file mode 100644 index 34640e5..0000000 --- a/changelogs/2026-04/2026-04-23_supplement-save-valid-effective.md +++ /dev/null @@ -1,135 +0,0 @@ -# 产品 Step1-5 保存接口 JSR-303 校验真实生效 - -**日期**: 2026-04-23 -**PR**: #1270 (Closes #1269) — PR #1259 后续补丁 -**服务**: hl-product-service-v2 / hl-order-service-v2 -**类型**: fix（修复校验漏补） - ---- - -## 背景 - -PR #1259（装备建议字段改条目列表）里 SaveReqVO 加了 JSR-303 校验注解（`@NotBlank` / `@Size(max=20)` / `@Size(min=1, max=50)`），但 `AdminProductController` 的 Controller 方法未加 `@Valid` 修饰符，**校验注解实际未触发**。非法数据仍能 200 入库。 - -本次补丁把 Step1-5 全部保存接口及一个订单接口补齐 `@Valid`，校验现在真实生效。 - ---- - -## 影响接口（9 处） - -| 接口 | Method | -|------|--------| -| `POST /admin/product/item/basic` | saveBasic | -| `POST /admin/product/item/{id}/itinerary` | saveItinerary | -| `POST /admin/product/item/{id}/route` | saveRoute | -| `POST /admin/product/item/{id}/price-calendar/batch` | savePriceCalendar | -| `POST /admin/product/item/{id}/schedule` | saveSchedule（2 个）| -| `POST /admin/product/item/{id}/schedule/batch` | batchCreateSchedule | -| `PUT /admin/product/item/{id}/supplement` | saveSupplement | -| `PUT /admin/product/item/{id}/detail-blocks` | saveDetailBlocks | -| `DELETE /admin/order/{orderId}/itinerary/pending/{editId}` | withdrawPendingEdit | - ---- - -## 行为变化（前端必读） - -### 之前（PR #1270 前） -```http -PUT /admin/product/item/{id}/supplement -{ - "equipmentList": [ - {"text": ""} // 非法：空 text - ] -} -→ 200 OK（错误地通过！数据存入 DB） -``` - -### 之后（PR #1270 后） -```http -PUT /admin/product/item/{id}/supplement -{ - "equipmentList": [ - {"text": ""} - ] -} -→ 400 { - "code": 400, - "success": false, - "message": "equipmentList[0].text: 装备文案不能为空" - } -``` - ---- - -## 装备建议校验规则（生效中） - -| 规则 | 违反时错误消息 | -|------|---------------| -| `equipmentList` 条目数 ≤ 20 | `equipmentList: 装备建议条目数不能超过20条` | -| 单条 `text` 非空非空白 | `equipmentList[0].text: 装备文案不能为空` | -| 单条 `text` 长度 1-50 字 | `equipmentList[0].text: 装备文案长度需在 1-50 字符之间` | - -**注意错误消息格式**：`{字段路径}: {消息}`，含数组索引（`[0]`、`[1]` 等），前端可精确定位哪条条目出错。 - ---- - -## 前端建议 - -### 1. 前置校验（推荐） -admin 编辑器在提交前自行 validate 一次： -- 条目数 > 20 → 禁止提交 + toast -- 单条 text 空 → 禁止提交 + 红色高亮 -- 单条 text 长度 > 50 → 禁止提交 + 高亮 - -避免走到后端才发现，体验更好。 - -### 2. 后端报错展示（兜底） -如果绕过了前置校验，后端 400 返回的 `message` 字段可直接 toast： - -```javascript -const resp = await api.saveSupplement(req); -if (resp.code !== 200) { - ElMessage.error(resp.message || '保存失败'); - return; -} -``` - -**错误消息已中文化**，直接展示即可。 - -### 3. 数组索引提示 -如果要做精细错误提示，可解析 `equipmentList[N].text` 中的 N，滚动聚焦到对应条目输入框。 - ---- - -## 其他接口的校验 - -`basic / itinerary / route / price-calendar / schedule` 等其他 Step 接口的 SaveReqVO 本来就有 JSR-303 注解，但同样因为缺 `@Valid` 没有生效。**本次补丁一起修复**。 - -常见校验约束（以 `ProductBasicSaveReqVO` 为例）: -- `productType` 非空 -- `name` 长度 ≤ 30 字 -- `tripDays` ≥ 1 -- 具体以 Knife4j `@ApiModelProperty` 中的 `required`/`allowableValues` 为准 - -如果前端之前传错数据能 200，现在可能 400，请以实际接口返回为准调整。 - ---- - -## 向后兼容 - -- **合法请求**：行为不变，仍 200 -- **非法请求**：从"假成功（200 入脏数据）"变为"正确失败（400 + 可读消息）" -- 属于**修复性变化**，非破坏性 - ---- - -## 验证 - -测试服网关已 curl 4 场景全过： - -```bash -# 合法 3 条 → 200 -# 21 条 → 400 equipmentList: 装备建议条目数不能超过20条 -# 空 text → 400 equipmentList[0].text: 装备文案不能为空 -# 51 字 text → 400 equipmentList[0].text: 装备文案长度需在 1-50 字符之间 -``` diff --git a/changelogs/2026-04/2026-04-23_typemismatch-error-msg-and-upload-timeout-tips.md b/changelogs/2026-04/2026-04-23_typemismatch-error-msg-and-upload-timeout-tips.md deleted file mode 100644 index 7fe558c..0000000 --- a/changelogs/2026-04/2026-04-23_typemismatch-error-msg-and-upload-timeout-tips.md +++ /dev/null @@ -1,114 +0,0 @@ -# 参数类型错误响应文案升级 + 富文本上传前端联动建议 - -**日期**: 2026-04-23 -**PR**: #1308 (Closes #1307, Closes #1305) -**服务**: hl-common-log（全局异常处理器）/ hl-user-service（SysOssController） -**类型**: fix（错误文案诊断性增强 + 前端联动建议） - ---- - -## 背景 - -本次批量修复源于用户反馈 2 个后台 bug： - -1. **Bug1**：资源服务 → 服务人员管理，点删除按钮报『参数类型错误: staffId』，但看不到实际值，无法判断是前端 undefined、NaN 还是类型不匹配。 -2. **Bug2**：资源服务 → 组合配品（备品）→ 详细介绍富文本上传图片，偶发『资源不存在』和『请求超时』。 - -代码层排查结论： -- 后端 URL 和前端 URL 字符级一致 ✓ -- StaffListVO.staffId 是 String（雪花 ID 保护）✓ -- toListVO 用 String.valueOf 填 VO ✓ -- 前端 row.staffId 取值正确 ✓ - -最可能成因： -- Bug1：测试服部署的前端 dist 为旧版本，取 `row.id` 而非 `row.staffId`，URL 变成 `/admin/staff/undefined`，Spring 抛 `MethodArgumentTypeMismatchException` 但响应不含实际值。 -- Bug2：前端 axios upload 默认 15s 超时对 10MB 富文本图片偏紧，慢网撞线 → 前端报『请求超时』或 HTTP 404 兜底『资源不存在』。 - -本次后端只做诊断增强，前端需要配合几处小调整。 - ---- - -## 后端行为变化（前端必读） - -### 1. 全局参数类型错误响应文案升级 - -#### 之前（PR #1308 前） -```http -DELETE /admin/staff/undefined -→ 200 { - "code": 400, - "message": "参数类型错误: staffId", - "data": null, - "success": false - } -``` - -#### 之后（PR #1308 后） -```http -DELETE /admin/staff/undefined -→ 200 { - "code": 400, - "message": "参数类型错误: staffId='undefined'（需要 Long 类型）", - "data": null, - "success": false - } -``` - -**前端影响**： -- 若前端某处对 message 做了**关键词匹配**（例如 `if (msg.includes("参数类型错误: staffId")) { ... }`），仍能命中（新文案仍以 `参数类型错误: staffId` 开头）。**向后兼容，无需改动**。 -- 若前端直接展示 message（默认情况），用户会看到更具诊断性的文案，能直接推断传给后端的非法值是什么。 - -### 2. 备品详细介绍上传端点保持不变 - -URL、请求方法、参数、响应体格式完全保持： -```http -POST /admin/sys/oss/upload -Content-Type: multipart/form-data -file=<MultipartFile> -→ 200 { - "code": 200, - "data": { "url": "https://...", "fileId": "...", "fileName": "..." }, - "success": true - } -``` - -后端仅加了 trace 日志（`[oss-upload] start/success/failed`），供运维排查。**前端无任何签名变化，无需改动业务代码**。 - ---- - -## 前端联动建议（⭐ 请前端同事落地） - -### 建议 1：`src/utils/request.js` 的 upload 方法 timeout 15000 → 60000 - -**原因**：后端富文本上传允许文件最大 10MB，经 OSS putObject + MD5 计算，在慢网环境常撞 axios 默认 15s 超时。实测 user 反馈偶发『请求超时』多是此原因。 - -**参考改动**： -```js -// src/utils/request.js -upload(url, file, config = {}) { - const formData = new FormData() - formData.append('file', file) - return request.post(url, formData, { - timeout: 60000, // ← 从 15000 改为 60000 - retry: false, - ...config, - }) -} -``` - -### 建议 2：富文本上传组件 Result.code != 0 时显示后端 message - -**原因**：目前前端 `src/utils/request.js:519-524` 把 HTTP 404 统一映射成『请求的资源不存在』。但后端 SysOssController 失败时抛的是 BusinessException，HTTP 依然 200，body 有 code != 0 和具体 message（如 OSS SignatureError / OssInvalidAccessKey / OssNetworkError 等）。 - -**参考改动**：富文本编辑器的上传失败回调直接 `message.error(res.message)`，不走 404 分支的统一文案。 - -### 建议 3：服务人员列表删除按钮取字段核对 - -**原因**：若前端线上 dist 取的是 `row.id` 而不是 `row.staffId`，会触发 `/admin/staff/undefined`。请核对当前 `src/views/resource/personnel/index.vue` 的删除按钮 handler + useCRUD 的 idKey 均为 `staffId`（最新代码已正确）。如仍有残留 `row.id` 引用请替换。 - ---- - -## 关联工单 - -- #1307 — fix: 服务人员删除报错『参数类型错误: staffId』 -- #1305 — fix: 备品详细介绍富文本上传报『资源不存在』偶发『请求超时』 diff --git a/changelogs/2026-04/2026-04-24_mp_favorite-footprint-fields.md b/changelogs/2026-04/2026-04-24_mp_favorite-footprint-fields.md deleted file mode 100644 index e872284..0000000 --- a/changelogs/2026-04/2026-04-24_mp_favorite-footprint-fields.md +++ /dev/null @@ -1,118 +0,0 @@ -# mp 收藏 / 浏览足迹接口: 字段全回填 + 新增产品类型字段 + 修复浏览记录保存后查不出 - -> **服务**: hl-mp-service (端口 8085) -> **PR**: #1338 -> **Issue**: 无关联工单（Gitea API 异常未能建单，已对齐口头确认） -> **日期**: 2026-04-24 -> **影响范围**: 小程序 收藏列表 + 浏览足迹列表 + 浏览记录保存接口 - ---- - -## ⚠️ 关键变化 - -1. **前一版 `/mp/user/favorite` 和 `/mp/user/footprint` 的 `records` 中 `targetType=PRODUCT`（或 `resourceType=PRODUCT`）的行，`name`/`coverUrl`/`tags` 全是 `null`**。本版修复后全部正确回填。 -2. `FavoriteItemVO` 和 `FootprintItemVO` **新增** `productType` + `productTypeLabel` 两字段（仅 PRODUCT 类型有值，其它类型 `null`）。前端若展示收藏/足迹卡片带产品类型（核心/小蒙马/私人定制）角标，直接用 `productTypeLabel` 即可，不用自己查字典。 -3. 保存足迹接口 `POST /mp/user/footprint` **修复隐性失败**：原实现下，用户"清空浏览记录"后再次访问同一资源时，接口返 200 但 DB 实际未保存记录，导致"保存成功却查不出来"。现在会正确复活已软删的记录。 -4. `footprintId` / `favoriteId` 在响应 JSON 中**全栈改为 String 序列化**（此前是 number，19 位雪花 ID 会被 JS 精度截断）。前端若以字符串接收，无感知；若以 number 运算需调整。 - ---- - -## 一、背景 - -`MpProductFeignClient.getProductBrief` Feign 路径历史写错，指向 `/internal/product/batch-brief`（班期摘要接口，返回 `BatchBriefVO` 只有 batchId/batchCode/departureDate 等班期字段），**没有 name/coverUrl/tags**。导致 mp BFF `FavoriteAggregationService` 拿到空 list → 字段全 null。资源类型（SCENIC/RESTAURANT/ACTIVITY）的三个 brief 端点无此问题。 - -浏览记录的问题则是 `addFootprint` 服务方法缺软删复活逻辑：清空浏览走 `@TableLogic` 把 `deleted_at` 置 NOW，下次访问时 `getOne` 自动加 `WHERE deleted_at IS NULL` 查不到 existing，进入 `save` 分支后撞上 DB 唯一索引（不含 deleted_at）冲突被静默吞。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 收藏列表 | GET | `/mp/user/favorite` | 响应字段补全 + 新增 | PRODUCT 行 `name`/`coverUrl`/`tags` 不再为 null；新增 `productType` + `productTypeLabel` | -| 2 | 浏览足迹列表 | GET | `/mp/user/footprint` | 响应字段补全 + 新增 | 同上 | -| 3 | 保存浏览记录 | POST | `/mp/user/footprint` | 行为修复 | 清空浏览后再次访问同资源不再静默失败 | - -路径/方法/参数**无变化**。 - ---- - -## 三、字段变化详情 - -### 3.1 `/mp/user/favorite` 响应 `records[*]` 字段 - -| 字段 | 类型 | 之前 | 之后 | 备注 | -|------|------|------|------|------| -| `favoriteId` | String | String | String | 无变 | -| `targetType` | String | String | String | 无变，枚举 `PRODUCT` / `SCENIC` / `RESTAURANT` / `ACTIVITY` | -| `targetId` | String | String | String | 无变 | -| `name` | String | PRODUCT 时为 `null` | **全类型正确返回** | PRODUCT 取产品名称；其它类型取资源名称 | -| `coverUrl` | String | PRODUCT 时为 `null` | **全类型正确返回** | PRODUCT 取产品封面图；其它类型取资源封面图 | -| `tags` | List\<String\> | PRODUCT 时为 `null` | **全类型正确返回** | 仅存在标签时有值 | -| `productType` | String | **不存在** | **新增** | 仅 PRODUCT 有值，枚举 `CORE` / `GROUP` / `CUSTOM`（字典 `product_type`） | -| `productTypeLabel` | String | **不存在** | **新增** | 仅 PRODUCT 有值，中文，如 `核心产品` / `小蒙马` / `私人定制` | -| `createdAt` | String | String | String | 无变 | - -### 3.2 `/mp/user/footprint` 响应 `records[*]` 字段 - -同 `/mp/user/favorite`，除主键字段叫 `footprintId`、业务类型字段叫 `resourceType`/`resourceId`。 - -### 3.3 `POST /mp/user/footprint` 响应 -响应结构未变（仍为 `Result<void>` 或 `Result<Footprint>`，视既有契约）。仅内部实现行为修复。 - ---- - -## 四、示例 - -### 4.1 修复前（已观察实际响应） -```json -{ - "code": 200, - "data": { - "records": [ - { - "favoriteId": "2047265158492815361", - "targetType": "PRODUCT", - "targetId": "2044306857534636034", - "name": null, - "coverUrl": null, - "tags": null, - "createdAt": "2026-04-23 18:43:45" - } - ], - "total": 1 - } -} -``` - -### 4.2 修复后 -```json -{ - "code": 200, - "data": { - "records": [ - { - "favoriteId": "2047265158492815361", - "targetType": "PRODUCT", - "targetId": "2044306857534636034", - "name": "冻干粉发短信给", - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/xxx.jpg", - "tags": ["亲子", "研学", "露营"], - "productType": "GROUP", - "productTypeLabel": "小蒙马", - "createdAt": "2026-04-23 18:43:45" - } - ], - "total": 1 - } -} -``` - ---- - -## 五、前端建议 - -1. 卡片 UI 如展示产品类型角标（核心/小蒙马/定制），直接用 `productTypeLabel`，不用前端再拉字典翻译。 -2. `productType`/`productTypeLabel` 在非 PRODUCT 类型（SCENIC/RESTAURANT/ACTIVITY）上是 `null`，渲染需判空。 -3. 原本用 `name?.trim() || "加载中..."` 等兜底文案的地方可以简化；字段现在一定不为 null（除非产品已被删除，此时 brief 返空 → 仍为 null，需保留兜底）。 -4. `productTypeLabel` 来自字典 `product_type`，字典 value→label 映射：`CORE→核心产品`、`GROUP→小蒙马`、`CUSTOM→私人定制`。若字典中文名称后续调整，后端会自动跟随，前端无需改动。 diff --git a/changelogs/2026-04/2026-04-24_mp_vehicle-detail-add-4-fields.md b/changelogs/2026-04/2026-04-24_mp_vehicle-detail-add-4-fields.md deleted file mode 100644 index 152384b..0000000 --- a/changelogs/2026-04/2026-04-24_mp_vehicle-detail-add-4-fields.md +++ /dev/null @@ -1,65 +0,0 @@ -# 小程序 - 用车详情补齐 座位数 / 车辆分类 / 驾龄要求 / 配置亮点 4 字段 - -**日期**: 2026-04-24 -**PR**: #1366 (dev, commit 5899ae9f) -**Issue**: #1350 -**类型**: fix -**服务**: hl-mp-service - ---- - -## 接口 - -`GET /mp/order/{orderId}/vehicle` - -订单详情页「服务包含 · 用车详情」弹窗接口。 - -## 变更 - -response `data` 新增 4 字段: - -| 字段 | 类型 | 说明 | 示例 | -|------|------|------|------| -| `seatCount` | `Integer` | 座位数(来自产品快照 vehicleModels) | `6` | -| `vehicleCategory` | `String` | 字典 `vehicle_type`: CAR=小轿车 / SUV=越野车 / VAN=商务车 / BUS=大巴 / MINIBUS=中巴 | `"VAN"` | -| `driverYearsRequired` | `String` | 驾龄要求(资源服务暂未提供,当前固定 null) | `null` | -| `features` | `List<String>` | 配置/亮点列表(资源服务暂未提供,当前固定 null) | `null` | - -旧字段保持不变:`vehicleType` / `vehicleCount` / `coverUrl` / `plateNumber` / `driverName` / `driverPhone` / `matched`。 - -## 示例响应 - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "vehicleType": "豪华suv", - "vehicleCount": 1, - "coverUrl": null, - "plateNumber": null, - "driverName": "够不够", - "driverPhone": "1521451212", - "matched": true, - "seatCount": 5, - "vehicleCategory": "GROUP", - "driverYearsRequired": null, - "features": null - } -} -``` - -## 前端接入建议 - -- 弹窗内 `座位数` 标签改读 `seatCount`,旧实现若读 `vehicleType` 包含「6座」文案可保留兜底 -- 「车辆分类」展示用 `vehicleCategory` 对字典 `vehicle_type` 翻译(前端 i18n 字典已有) -- `driverYearsRequired` / `features` 为 null 时不渲染对应行,待资源服务后续补数据再显示 - -## 根因说明(前端不关心,仅存档) - -mp-service BFF VO 与 order-v2 源端 VO 同名但字段数不一致,Feign 反序列化丢弃多余字段。本 PR 只补 BFF 端 VO,order-v2 源端早已返回该 4 字段。 - -## E2E 验证(2026-04-24 测试服) - -订单 `HL20260423175303-5448` 直连 mp-service `127.0.0.1:8085` response 完整含 4 字段。 diff --git a/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md b/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md deleted file mode 100644 index f6624ea..0000000 --- a/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md +++ /dev/null @@ -1,110 +0,0 @@ -# 错误码体系 v2 全量上线(#1391) - -**日期**: 2026-04-25 -**影响范围**: 全部服务 `Result.code` 字段 -**关联 PR**: #1392 / #1393 / #1394 / #1395 / #1396 / #1397 / #1398 -**工单**: [#1391](https://git.1814.love:8443/wx/HL/issues/1391) - ---- - -## 🚨 前端接入提示 - -### ✅ 好消息:401/403/404 保留,现有拦截器零改动 -- HTTP 认证相关错误码(401 未授权 / 403 无权限 / 404 未找到)**完全保留** -- 前端 axios 拦截器 / 跳登录页逻辑 **无需任何改动** -- 400 参数校验 / 500 系统错误 **保留原语义** - -### 🆕 业务错误码升级为 **6 位数字**,前端可选接入 -- 所有业务模块的 `Result.code` 字段不再是 400/500 通用码,变为 **6 位数字业务码** -- 如 `400101 = 产品不存在`、`500311 = 订单当前状态不允许取消`、`510411 = 合同签约失败` 等 -- **message 字段保留原业务提示中文**,所有已有 `uni.showToast(res.data.message)` 代码继续生效 - ---- - -## 📋 6 位码段位表 - -| 段位前缀 | 模块 | 示例 | -|---------|------|------| -| `100xxx` | common 通用 | `100501` 流控拦截 / `100502` 幂等拦截 / `100901` Feign 空数据 | -| `110xxx` | auth 认证授权 | `110001` 未认证(预留) | -| `200xxx-299xxx` | user 用户 | `230301` 短信频率限制 / `230302` 短信日发送上限 / `260204` 状态列无权管理 | -| `300xxx-399xxx` | resource 资源 | `300106` 景点无权操作 / `310xxx` 酒店 / `340xxx` 用车 / `380001` 备品审批进行中不可删 | -| `400xxx-499xxx` | product 产品 | `400101` 产品不存在 / `410xxx` 价格 / `430xxx` 行程 / `460xxx` 高德地图 | -| `500xxx-509xxx` | order 订单核心 | `500xxx` 订单 CRUD / `500311` 状态不允许取消 | -| `510xxx-549xxx` | order 扩展 | `510xxx` 合同 / `520xxx` 支付 / `530xxx` 退款 / `540xxx` 保险 / `549xxx` 投诉 | -| `550xxx-599xxx` | order 子域 | `550xxx` 行程 / `560xxx` 团报 / `580xxx` 到达/工单 / `590xxx` 加价折扣 / `593xxx` 发票 | -| `600xxx-699xxx` | mp 小程序 BFF | `610xxx` 天气 | -| `900xxx-999xxx` | system 系统级 | `900001` 限流 / `900002` 熔断 | - ---- - -## 🎯 前端可选接入(3 种粒度) - -**大多数场景**:继续用 `message` 弹 toast,无需关心 code。 - -**需要差异化处理的场景**,可按以下 3 种粒度分支: - -### Level 1 粒度:HTTP 类(优先) -```js -if (res.data.code === 401) // 跳登录 -if (res.data.code === 403) // 无权限提示 -if (res.data.code === 404) // 404 页 -// 已有代码完全兼容,继续用即可 -``` - -### Level 2 粒度:按段位分支(业务大类) -```js -const code = res.data.code; -if (code >= 400000 && code <= 499999) { - // 产品相关错误,可选跳商品首页 -} else if (code >= 500000 && code <= 599999) { - // 订单相关错误 -} -``` - -### Level 3 粒度:按具体 code 分支(细粒度 UX) -```js -if (res.data.code === 400301) { - // 产品下架,跳首页 - uni.reLaunch({ url: '/pages/index/index' }); -} else if (res.data.code === 510411) { - // 合同签约失败,重试按钮 -} -``` - -**接入优先级建议**:Level 1 必做(已有)→ Level 3 按 UX 需求逐个接入(非强制)。 - ---- - -## 🔧 技术变更细节 - -### 1. Feign 链路透传修复 -**修复前**:下游服务抛 `BusinessException(400301, "产品下架")`,Feign 调用方 `getCheckedData()` 会吞码降级为 500。 -**修复后**:上游 code 完整透传,前端能看到真实业务码。 - -### 2. 所有 admin/mp 接口的 Result.code 升级 -- 之前:`{code: 400, message: "产品不存在"}` / `{code: 500, message: "订单状态不允许取消"}` -- 现在:`{code: 400101, message: "产品不存在,ID=xxx"}` / `{code: 500311, message: "当前状态不允许取消,状态=PAID"}` - -### 3. message 字段保留关键子串 -迁移采用 MessageFormat 占位符,所有原 message 关键中文子串保留(如"产品不存在"/"审批进行中"等),前端若用 `message.includes(xxx)` 判断仍可工作。 - ---- - -## 🧪 新 code 速查接口 - -各服务启动时自动注册所有错误码到中央 `ErrorCodeRegistry`,如需完整码表可通过以下方式查询: - -1. **后端日志**:每个服务启动日志含 `ErrorCodeRegistry scan complete, totalCodes=X, segments=Y` -2. **容量告警**:任何段位使用率 ≥ 80% 自动 WARN 日志 -3. **未来扩展**:计划提供 `/internal/errorcode/catalog` 接口导出 yaml 码表 - ---- - -## ⚠️ 3 日反馈窗口 - -如前端需要按具体 code 做差异化处理(Level 3),请在 **2026-04-28 前** 反馈: -- 哪个业务 code 需要特殊 UI 行为(跳页/重试/不展示等) -- 是否需要前端配置化 code-action 映射 - -超过 3 日无反馈视为按 Level 1 + message 继续使用,不阻塞迭代。 diff --git a/changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md b/changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md deleted file mode 100644 index 7954c68..0000000 --- a/changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md +++ /dev/null @@ -1,75 +0,0 @@ -# Knife4j 接口文档按微服务多分组(#1404) - -**日期**: 2026-04-25 -**关联 PR**: #1405(Phase A) / #1406-#1410(Phase B 5 服务) / #1411(hotfix) -**工单**: [#1404](https://git.1814.love:8443/wx/HL/issues/1404) - ---- - -## 🚨 前端 / 测试同事必看 - -### 接口文档地址不变 -- 测试环境:https://api.test.1814.love:9443/doc.html(网关) -- 内网直连:http://192.168.100.236:8080/doc.html - -### 左上角下拉菜单变化 - -**改造前**:35 个细粒度下拉项,如: -- `用户服务 - 管理员管理` -- `用户服务 - 角色管理` -- `用户服务 - 字典管理` -- `资源服务 - 酒店管理` -- `资源服务 - 服务项管理` -- ... (35 项,菜单冗长) - -**改造后**:**5 个微服务级下拉**: -- 用户服务 -- 资源服务 -- 产品服务 -- 订单服务 -- 小程序 BFF - -### 进入 group 后的 tag 列表 - -每个 tag 用 **4 类前缀**区分端类型,无需服务名前缀: -- `[admin] 模块名` - 管理端接口 -- `[C端] 模块名` - 小程序端接口 -- `[内部] 模块名` - internal/Feign 接口 -- `[回调] 模块名` - 第三方平台事件回调(企微/公众号) - -### 实例 - -**用户服务 group**(共 48 tag): -- `[C端] 公开字典` / `[C端] 出行人` / `[C端] 出行人OCR识别` / ... -- `[admin] Banner管理` / `[admin] 角色管理` / `[admin] 字典管理` / ... -- `[内部] 心愿` / `[内部] 联系我们` / `[内部] 部门用户` / ... -- `[回调] 公众号回调` - -**订单服务 group**(共 51 tag): -- `[admin] 订单管理` / `[admin] 合同管理` / `[admin] 退款管理` / `[admin] 保险方案管理` / ... -- `[内部] 订单同步` / `[内部] 支付` / `[内部] 合同 Feign` / ... - -## 改造规模(供 reviewer 参考) -- 7 PR(#1405-#1411) -- 274 Controller 文件 @Api(tags) 全量改名 -- 5 个 Knife4jConfig.java 多 Docket 合并为单 Docket -- gateway/application.yml `knife4j.gateway.routes` 35 项 → 5 项 - -## 路由结构 - -| 服务 | 网关下拉名 | swagger group | 注册名 | -|------|-----------|--------------|--------| -| hl-user-service | 用户服务 | 用户服务 | hl-user-service | -| hl-resource-service | 资源服务 | 资源服务 | hl-resource-service | -| hl-product-service-v2 | 产品服务 | 产品服务 | hl-product-service-v2 | -| hl-order-service-v2 | 订单服务 | 订单服务 | **hl-order-service**(注:代码模块带 -v2 但 Nacos 注册名不带) | -| hl-mp-service | 小程序 BFF | 小程序 BFF | hl-mp-service | - -## 实施踩坑 - -PR #1405 把订单服务 service-name 误写为 `hl-order-service-v2`(实际 Nacos 注册名是 `hl-order-service`,代码模块名带 -v2 是 maven module 名,但 spring.application.name 没带 -v2),导致 doc.html 订单 group 404。已在 #1411 hotfix 修正。 - -经验沉淀:Knife4j gateway routes / Feign client name 统一参考 Nacos 注册名(`spring.application.name`)而非 maven module 名,二者**可能不一致**。 - -## 不影响业务接口 -本次仅改文档/分组,业务路径 / 鉴权 / 错误码 / Feign 调用全部不变。 diff --git a/changelogs/2026-04/2026-04-25_swagger-error-code-display.md b/changelogs/2026-04/2026-04-25_swagger-error-code-display.md deleted file mode 100644 index acbdbbf..0000000 --- a/changelogs/2026-04/2026-04-25_swagger-error-code-display.md +++ /dev/null @@ -1,55 +0,0 @@ -# Swagger 响应状态自动列出 6 位业务码(#1412) - -**日期**: 2026-04-25 -**关联 PR**: #1413(初版)/ #1414 / #1415 / #1416(hotfix 链) -**工单**: [#1412](https://git.1814.love:8443/wx/HL/issues/1412) - ---- - -## 改造前 -Knife4j 接口文档每个接口的「响应状态」区只有: -- 200 OK -- 401 Unauthorized -- 403 Forbidden -- 404 Not Found - -#1391 引入的 6 位业务码(如 `400301 产品下架` / `500311 订单状态不允许取消`)前端在文档里看不到。 - -## 改造后 -每个接口的「响应状态」区显示 **193 个状态码**: -- HTTP 标准 4 个(200/401/403/404 保留) -- **6 位业务码 189 个**(从 ErrorCodeRegistry 自动收集,含 message) - -### 实例(GET /admin/agreement/page) -``` -状态码 说明 -200 OK -401 Unauthorized -403 Forbidden -404 Not Found -100000 系统异常,请稍后重试 -100001 参数非法: {0} -100002 数据不存在 -100003 操作不允许: {0} -100501 {0} ← 流控 -100502 {0} ← 幂等拦截 -100901 远程服务返回数据为空 ← Feign 透传 -... (189 个 6 位业务码) -``` - -## 实现路径(踩坑总结) -1. **PR #1413**:`Docket.globalResponseMessage` 注入 — Docket bean 创建时 `ErrorCodeRegistry.scan()` 还没跑(在 ApplicationRunner 阶段),codeMap 空,失败 -2. **PR #1414**:改用 `OperationBuilderPlugin` — 仍空,因为 plugin 也在 ApplicationRunner 之前被 swagger 触发 -3. **PR #1415**:删除 5 个 Knife4jConfig 的 `globalResponseMessage` 残留(避免覆盖 plugin) -4. **PR #1416**:**根本解** — `ErrorCodeRegistry` 改用 `@PostConstruct` 在 Bean 实例化时立即扫描,所有下游 Bean 拿到非空 codeMap - -## 影响 -- 5 个 MVC 业务服务(user/resource/product-v2/order-v2/mp)swagger 全生效 -- 接口数据结构无变化,只是**文档**新增响应状态展示 -- 业务接口/前端调用无需改动 - -## 经验沉淀 -**Spring Boot Bean 启动顺序**:`ApplicationRunner.run()` 在 `ApplicationContext.refresh()` 完全完成之后运行,但 swagger 等组件可能在 refresh 过程中已构建 OpenAPI 模型,此时 ApplicationRunner 还没跑。需要在 Bean 创建期就完成扫描的逻辑应该用 `@PostConstruct`。 - -## 验证 -浏览器访问任一接口的"响应状态"区,应看到 193 行响应码。 diff --git a/changelogs/2026-04/2026-04-25_swagger-error-code-narrow.md b/changelogs/2026-04/2026-04-25_swagger-error-code-narrow.md deleted file mode 100644 index 23e348e..0000000 --- a/changelogs/2026-04/2026-04-25_swagger-error-code-narrow.md +++ /dev/null @@ -1,37 +0,0 @@ -# Swagger 业务码精简显示(#1417 / PR #1418-#1420) - -**日期**: 2026-04-25 -**状态**: 已上线测试服(dev `3082c367`) -**关联**: 后续优化于 [#1412](https://git.1814.love:8443/wx/HL/issues/1412) - ---- - -## 改造前(#1412 完成时) -每个接口的「响应状态」区显示 **193 行**(4 HTTP + 189 业务码全集)— 太冗余。 - -## 改造后(#1420 上线) -每个接口显示 **21 行**: -- 4 HTTP 标准(200 / 401 / 403 / 404) -- 13 通用业务码: - - common 段(100xxx):SYSTEM_ERROR / INVALID_PARAM / DATA_NOT_FOUND / OPERATION_NOT_ALLOWED / RATE_LIMITED / IDEMPOTENT_REJECTED / FEIGN_EMPTY_DATA / FEIGN_CALL_FAILED - - auth 段(110xxx):UNAUTHENTICATED / TOKEN_EXPIRED / TOKEN_INVALID / PERMISSION_DENIED / RESOURCE_NOT_FOUND - - system 段(900xxx):RATE_LIMITED / CIRCUIT_BROKEN / SERVICE_DEGRADED / GATEWAY_ERROR -- 0 ~ N 个 controller 字节码直接引用的业务码(由 ASM 启动时扫描) - -## 实现路径(踩坑) -1. **PR #1418**:按服务模块过滤,但 user-service 自己注册的码就 189,过滤无效 -2. **PR #1419**:ASM 扫 controller 字节码 + fallback module 全集,99% controller 不直接 throw 走 fallback 仍 189 -3. **PR #1420(终版)**:删除 fallback,只显示通用 + ASM 扫到的引用 - -## 完整业务码全集查询 -- 后端启动日志:`ErrorCodeRegistry scan complete, totalCodes=N` -- 前端文档:[errorcode-catalog](https://git.1814.love:8443/wx/hl-api-changelog/raw/branch/main/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md)(段位表) -- 后端代码:`hl-*-service/src/main/java/com/hulalv/*/errorcode/*.java` - -## 前端处理建议 -- HTTP 401 / 403 / 404 走拦截器分支(已有,不变) -- 通用码 100xxx / 110xxx / 900xxx 提示规则统一(如 100501 RATE_LIMITED 显示"操作过于频繁") -- 业务码用 `message` 弹 toast,不必为每个 code 写分支 - -## 不影响 -所有业务接口/响应数据结构/前端调用约定**完全不变**,只是文档展示精简。 diff --git a/changelogs/2026-04/20260421-review-migrate-to-order-v2.md b/changelogs/2026-04/20260421-review-migrate-to-order-v2.md deleted file mode 100644 index e8bd670..0000000 --- a/changelogs/2026-04/20260421-review-migrate-to-order-v2.md +++ /dev/null @@ -1,230 +0,0 @@ -# 评价模块迁移到 order-v2 服务（URL 不变 / 状态机对照 / Feign 链路变化） - -> **日期**：2026-04-21 -> **服务**：`hl-user-service` → `hl-order-service`（v2） -> **PR**：#1130（merge commit `cff993d12e3eb33f8c19d14bb18a9de001f5f971`） -> **类型**：后端跨服务迁移 / 重构 -> **前端调用影响**：✅ **REST 路径零变化，前端无需改代码**（本 changelog 只是告知 + 状态机对照，防止有硬编码状态常量踩坑） - ---- - -## 一、变更总览 - -评价（review）模块从 **hl-user-service** 整体搬到 **hl-order-service-v2**。 - -- **网关路由已同步切换**：`/admin/review/**` 原先由 gateway 转 `lb://hl-user-service`，现在转 `lb://hl-order-service`。前端用原 URL 直接调就行 -- **BFF（hl-mp-service）Feign 内部目标服务切换**：`MpReviewFeignClient(name="hl-user-service")` → `name="hl-order-service"`，小程序前端调 `/mp/review/**` 完全无感 -- **DB 真实表**从 `hl_user_service` / `hl_review_service`（VIEW + 废弃库）搬到 `hl_order_service_v2` -- **评价审核 5 状态 + 6 事件** 改用 cola 状态机（原先是 if-else 散写） - ---- - -## 二、受影响的 URL（全部路径不变） - -### 管理端（hl-ui）— 7 个 `/admin/review/**` - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/admin/review/list` | 评价列表（分页） | -| GET | `/admin/review/{reviewId}` | 评价详情 | -| POST | `/admin/review/{reviewId}/approve` | 人工审核通过 | -| POST | `/admin/review/{reviewId}/reject` | 人工审核拒绝 | -| POST | `/admin/review/{reviewId}/override-approve` | 覆盖通过（机审拒绝后管理员放行） | -| POST | `/admin/review/{reviewId}/reply` | 管理员回复 | -| PUT | `/admin/review/{reviewId}/keyword-tags` | 编辑评价关键词标签 | - -### 小程序端（hl-mp）— 14 个 `/mp/review/**` + 3 个 `/mp/like/**` - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/mp/review/rating-categories` | 评分类别字典 | -| GET | `/mp/review/filter-tags` | 过滤标签（支持 productCategory） | -| POST | `/mp/review/create` | 创建评价 | -| GET | `/mp/review/my` | 我的评价列表 | -| GET | `/mp/review/search` | 搜索评价 | -| GET | `/mp/review/target` | 按目标查（productId/customizerId 等） | -| GET | `/mp/review/product/{productId}` | 产品评价列表 | -| GET | `/mp/review/product/{productId}/highlights` | 产品精选好评 | -| GET | `/mp/review/stats` | 评价统计（平均分/好评率） | -| GET | `/mp/review/featured` | 首页/列表精选评价 | -| GET | `/mp/review/order/{orderId}/reviewed` | 订单是否已评价 | -| GET | `/mp/review/order/{orderId}/reviewable-targets` | 订单可评价目标列表 | -| POST | `/mp/review/{reviewId}/like` | 点赞 | -| GET | `/mp/review/{reviewId}/like/check` | 查询是否已点赞 | -| POST | `/mp/like/*`（3 个） | 透调评价点赞 Feign | - -### 其它端点（无变化） - -- 订单详情里"是否已评价"标记 `orders.is_reviewed`：由后端同事务内强一致更新（原本是 Feign + afterCommit 最终一致），前端字段取法不变 -- 评价图片/视频 OSS 链接字段 `images[].imageUrl` / `videos[].videoUrl`：位置、命名、协议不变 - ---- - -## 三、⚠️ 状态机改造 — 前端请核对硬编码状态常量 - -评价审核状态机重新梳理，**旧状态值有变**。如果前端存在状态字符串硬编码（status 字段 switch/判断），**必须参考下表确认取值是否还匹配**。 - -### 1. 状态对照表 - -| 老值（user-service 时代） | 新值（order-v2 时代） | 含义 | 前端处理建议 | -|---|---|---|---| -| `PENDING` | `PENDING_MODERATION` | 机审中（评价刚提交，异步跑阿里云绿网） | 若前端用此常量过滤"待审核"，注意改名；建议改为判断 `status != 'APPROVED' && status != 'REJECTED'` | -| `MACHINE_PENDING` | `PENDING_MODERATION` | 同上（并入） | 老取值建议 fallback 兼容 | -| `MACHINE_BLOCKED` | `MACHINE_REJECTED` | 机审命中 block 级关键词，系统拒（但管理员可覆盖） | 改名 | -| `MACHINE_REVIEW` / 其他"待人工" | `PENDING_MANUAL` | 机审命中 review 级关键词，转人工复审 | 改名 | -| `APPROVED` | `APPROVED` | 审核通过 / 前台可见 | ✅ 不变 | -| `REJECTED` | `REJECTED` | 人工拒绝 / 前台不可见 | ✅ 不变 | -| `OVERRIDE_APPROVED` | 不再作为独立状态，覆盖后直接是 `APPROVED` | 原"管理员覆盖通过"独立状态 | ⚠️ 若前端用此判断"是否覆盖"，改用 `machineResult.override == true` 或事件日志字段判断 | - -### 2. 新状态机（order-v2 侧实现） - -**5 个状态**（`ReviewStatus` 枚举）： - -| 值 | 描述 | -|---|---| -| `PENDING_MODERATION` | 机审中（初始状态） | -| `PENDING_MANUAL` | 机审命中 review 级关键词，待人工复审 | -| `MACHINE_REJECTED` | 机审命中 block 级关键词，系统拒绝 | -| `APPROVED` | 审核通过（前台可见） | -| `REJECTED` | 人工拒绝（前台不可见） | - -**6 个事件**（`ReviewEvent`）： - -| 事件 | 触发 | 转移 | -|---|---|---| -| `MACHINE_PASS` | 阿里云绿网回调通过 | `PENDING_MODERATION` → `APPROVED` | -| `MACHINE_FAIL_REVIEW` | 命中 review 级关键词 | `PENDING_MODERATION` → `PENDING_MANUAL` | -| `MACHINE_FAIL_BLOCK` | 命中 block 级关键词 | `PENDING_MODERATION` → `MACHINE_REJECTED` | -| `MANUAL_APPROVE` | 管理端 `/admin/review/{id}/approve` | `PENDING_MANUAL` → `APPROVED` | -| `MANUAL_REJECT` | 管理端 `/admin/review/{id}/reject` | `PENDING_MANUAL` → `REJECTED` | -| `ADMIN_OVERRIDE_APPROVE` | 管理端 `/admin/review/{id}/override-approve` | `MACHINE_REJECTED` → `APPROVED` | - -### 3. 状态显示建议（供 hl-ui / hl-mp 参考） - -```javascript -// 管理端列表筛选建议 -const ADMIN_FILTER = { - 待审核: ['PENDING_MODERATION', 'PENDING_MANUAL'], // 需要管理员关注 - 机审拒绝: ['MACHINE_REJECTED'], // 可覆盖通过 - 已通过: ['APPROVED'], - 已拒绝: ['REJECTED'], -}; - -// 小程序端（只关心是否已审核通过） -if (review.status === 'APPROVED') { - // 正常展示 -} else { - // 一般不展示或隐藏 -} -``` - ---- - -## 四、前端无感但内部链路变化 - -### 1. 创建评价：订单"已评价"标记改为强一致 - -- **老链路**（最终一致）：`createReview` 成功 → afterCommit 调 `user-service.OrderReviewFeignClient → hl-order-service.PUT /internal/mp/order/{id}/mark-reviewed`（Feign 跨服务一次） -- **新链路**（强一致）：review 与 order 同库同事务，`createReview` 同事务内直接更新 `orders.is_reviewed = 1` -- **前端体感**： - - 创建评价响应时间预计快 **50~100ms**（省一跳 Feign） - - 创建成功立刻查订单 `/mp/order/{orderId}` 的 `isReviewed` 字段就是 `true`，**不再有短暂不一致窗口**（老版本偶发 50ms 内查到 false） - -### 2. 管理端审核（approve / reject / override-approve） - -- 老：user-service 本地写 review.status → Feign 调 order-v2 → order.is_reviewed 更新 -- 新：order-v2 本地写 review.status + orders.is_reviewed（同事务） -- 响应时间预计 **快 30~50ms** - -### 3. 精选评价缓存键（Redis 内部实现，前端无直接感知） - -- 前缀保持 `review:featured:limit:{limit}`，TTL 600s±60s -- MP 侧兼容层前缀 `mp:review:featured*` 保持不变 -- 迁移后首次访问缓存 miss 约 1~3 秒回源，后续正常（业务调用量低，不影响体验） - ---- - -## 五、响应字段清单（仅列前端需要关注的 VO） - -### 管理端 `ReviewVO` / `ReviewListVO`（`/admin/review/**` 返回） - -| 字段 | 类型 | 说明 | 变化 | -|---|---|---|---| -| `reviewId` | Long | 评价 ID | - | -| `orderId` / `orderNo` | Long / String | 订单 | - | -| `userId` / `userName` / `userAvatar` | Long / String | 用户 | - | -| `productId` / `productName` / `productType` | Long / String | 产品 | productType 新增 `CUSTOM` 取值（已在 PR #935 生效，本 PR 无变化） | -| `targetType` / `targetId` | String / Long | 评价目标（PRODUCT/CUSTOMIZER/SCENIC 等） | - | -| `ratingItinerary` / `ratingAccommodation` / `ratingDriver` / `ratingDining` / `ratingOverall` | Integer (1~5) | 五维评分 | - | -| `ratingLevel` | String (GOOD/MEDIUM/BAD) | 评分等级 | - | -| `ratingAvg` | Decimal(2,1) | 平均分 | - | -| `content` | String | 评价内容 | - | -| `images[]` / `videos[]` | List | 图片/视频 | 字段名不变 | -| `specialAnswers` / `keywordTags` | JSON | 特殊问题 / 关键词标签 | - | -| `status` | String | ⚠️ 取值改，见第三节 | **改** | -| `rejectReason` | String | 拒绝原因 | - | -| `auditorName` / `auditedAt` | String / DateTime | 审核员/审核时间 | - | -| `adminReplyContent` / `adminReplyBy` / `adminReplyAt` | - | 管理员回复 | - | -| `likeCount` | Integer | 点赞数 | - | -| `createdAt` | DateTime | 创建时间 | ✅ **保持驼峰 `createdAt`**（虽然 DB 底层列改为 `create_time` 对齐 BaseDO，但 VO 对前端零变化） | -| `updatedAt` | DateTime | 更新时间 | ✅ 同上 | - -### 小程序端 `MpReviewVO`（`/mp/review/**` 返回） - -字段与 `ReviewVO` 核心一致，含 `reviewId / userName / userAvatar / productName / content / ratings* / images / videos / likeCount / createdAt / liked`（当前用户是否点赞）。 - -### `ReviewStatsVO`（统计接口返回） - -| 字段 | 类型 | 说明 | -|---|---|---| -| `totalCount` | Long | 总评价数 | -| `avgRating` | Decimal(2,1) | 平均评分 | -| `goodCount` / `mediumCount` / `badCount` | Long | 好/中/差评数 | -| `goodRate` | Decimal(5,2) | 好评率（百分比） | -| `hasImageCount` / `hasVideoCount` | Long | 有图/有视频评价数 | - ---- - -## 六、错误码对照 - -| HTTP | code | 说明 | 触发 | -|---|---|---|---| -| 200 | 200 | 成功 | - | -| 200 | 400 | 参数错误 | 评分不在 1-5 / 必填漏传 | -| 200 | 401 | 未登录 | `/mp/review/create` 等需 userId 的接口 | -| 200 | 403 | 无权限 | 管理端非管理员访问 `/admin/review/**` | -| 200 | 404 | 评价不存在 | review 已被软删或 ID 错误 | -| 200 | 409 | 状态非法转移 | ⚠️ **新增**：cola 状态机拒绝非法流转（例：对 `APPROVED` 再 `reject`） | -| 200 | 500 | 系统错误 | 保底 | -| 200 | 50001 | 机审服务暂不可用 | 阿里云绿网 SDK 超时/限流 | - -> 本项目 HTTP status 始终返回 200，业务码在 `Result.code`。 - ---- - -## 七、前端 TODO（如有硬编码） - -- [ ] **hl-ui 管理端**：搜索项目里硬编码的评价状态字符串（例如 `status === 'PENDING'`），按第三节对照表替换 -- [ ] **hl-mp 小程序端**： - - 大概率无需改（大部分地方直接取 `status === 'APPROVED'` 判断是否展示） - - 如有"审核中"状态展示（例如"我的评价"列表），状态值需从 `PENDING` / `MACHINE_PENDING` 替换为 `PENDING_MODERATION` / `PENDING_MANUAL` -- [ ] **无其它改动**：网关路径、字段命名、认证头（`X-User-Id` / `X-Admin-Id`）全部不变 - ---- - -## 八、回归验证建议（前端自测） - -- [ ] 提交评价 → 我的评价列表能看到（`status=PENDING_MODERATION` 或 `APPROVED`） -- [ ] 订单详情"已评价"标记立即刷新（不再有延迟窗口） -- [ ] 产品详情/精选评价列表加载正常 -- [ ] 评价点赞/取消点赞能实时更新 -- [ ] 管理端审核通过/拒绝 → 小程序端立即可见/隐藏 -- [ ] 管理端覆盖通过（机审拒绝后）→ 评价重新可见 - ---- - -## 九、联系人 - -- 后端负责人：wx / AI 协作（管理者） -- 相关任务文档：`docs/tasks/20260421_设计_评价模块迁移到order-v2.md` -- 重启服务清单（后端）：hl-user-service / hl-order-service-v2 / hl-mp-service / hl-product-service-v2 / hl-gateway diff --git a/changelogs/2026-04/23-itinerary-node-time-period.md b/changelogs/2026-04/23-itinerary-node-time-period.md deleted file mode 100644 index 4dff271..0000000 --- a/changelogs/2026-04/23-itinerary-node-time-period.md +++ /dev/null @@ -1,130 +0,0 @@ -# 行程节点新增「时间说明」字段(字典 itinerary_time_period) - -**日期**: 2026-04-23 -**服务**: hl-product-service-v2 / hl-order-service-v2 / hl-mp-service -**影响**: 管理端产品编辑页 + 小程序产品详情/行程详情/今日时间线 -**PR**: #1315 + #1317 (hot-fix: DictFeignClient 路径对齐) -**工单**: #1295 / #1316 - ---- - -## 背景 - -产品编辑后台「行程编排」Tab → DAY X → 「活动安排」列表的每个活动节点，新增一个「时间说明」字段（字典下拉）。5 个候选值：清晨 / 上午 / 下午 / 黄昏 / 午夜。 - -用途：在 start_time 精确时间之外，再提供一个语义化时间上下文标签；小程序端行程页展示更直观。 - ---- - -## 新字典 `itinerary_time_period` - -``` -dict_type_id = 10070 -dict_type = itinerary_time_period -``` - -| dict_data_id | dict_value | dict_label | -|--------------|----------------|------------| -| 100701 | EARLY_MORNING | 清晨 | -| 100702 | MORNING | 上午 | -| 100703 | AFTERNOON | 下午 | -| 100704 | DUSK | 黄昏 | -| 100705 | MIDNIGHT | 午夜 | - -**存储**：`product_itinerary_node.time_period VARCHAR(32) NULL`（历史数据保留 null，不强制回填） - ---- - -## 1. 管理端 `/admin/product/item/{id}/itinerary` 保存 - -`ItineraryDayItem.nodes[]` / `ProductItinerarySaveReqVO.NodeItem` 新增字段： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `timePeriod` | `String` | 否 | 字典 `itinerary_time_period` 值：`EARLY_MORNING` / `MORNING` / `AFTERNOON` / `DUSK` / `MIDNIGHT`。可为 null。 | - -**PUT 请求示例**： -```json -{ - "itinerary": [{ - "dayNumber": 1, - "nodes": [ - { "nodeName": "ATV 越野", "startTime": "10:00", "timePeriod": "MORNING" }, - { "nodeName": "湿地日落", "startTime": "18:00", "timePeriod": "DUSK" } - ] - }] -} -``` - ---- - -## 2. 管理端 `GET /admin/product/item/{id}` 回显 - -`ItineraryDayRespVO.NodeRespVO` 新增字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `timePeriod` | `String` | 字典值（管理端下拉回显） | - -管理端前端：下拉框 `options` 请从 `GET /admin/dict/data?dictType=itinerary_time_period` 拉取，绑定 `value/label`。 - ---- - -## 3. 小程序产品详情 `GET /mp/product/{id}` - -`MpProductDetailRespVO.DayInfo.nodes[]` (`NodeInfo`) 新增两字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `timePeriod` | `String` | 字典值（如 `EARLY_MORNING`） | -| `timePeriodLabel` | `String` | 字典中文标签（如 `清晨`），null 表示未设置 | - -前端直接展示 `timePeriodLabel`，为 null 不显示该标签即可。 - ---- - -## 4. 小程序行程详情 `GET /mp/trip/{orderId}` - -订单进行中/已完成的行程页面 `data.itineraryDays[].nodes[]` 和 `data.dailyItinerary[].nodes[]` 两条路径新增： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `timePeriod` | `String` | 字典值，来自订单快照 | -| `timePeriodLabel` | `String` | 字典中文标签 | - -**老订单兼容**：下单时快照中若没有 `time_period` 字段，反序列化后 `timePeriod = null` / `timePeriodLabel = null`，接口 200 不会报错。 - ---- - -## 5. 小程序今日时间线 `GET /mp/today/timeline` - -`MpTripItineraryNodeVO` 新增：`timePeriod` + `timePeriodLabel`（字段含义同上）。前端逻辑同产品详情。 - ---- - -## 前端对接要点 - -1. 管理端新增编辑行程节点表单：下拉组件调字典接口 `itinerary_time_period`，绑定到节点的 `timePeriod` 字段，保存到 `PUT /admin/product/item/{id}/itinerary`。 -2. 管理端回显：读 `GET /admin/product/item/{id}` 的 `itinerary[].nodes[].timePeriod`，在下拉组件 `v-model` 上。 -3. 小程序三处（产品详情 / 行程详情 / 今日时间线）：优先展示 `timePeriodLabel`，null 时不显示该标签；需要精确时间仍用 `startTime`（HH:mm）。 -4. 前端无需单独调字典接口，后端已在响应里填好 `timePeriodLabel`。 - ---- - -## 关联说明（2026-04-23 部署时踩坑） - -首次部署 #1315 后，`timePeriodLabel` 全部返回 null。排查发现是 **pre-existing bug**： - -- `DictFeignClient`（hl-common-feign）声明路径 `GET /internal/dict/data-by-type` -- `hl-user-service` 实际仅实现 `GET /internal/dict/data` - -路径 mismatch 导致所有下游（review / complaint / trip / mpProductDetail）的字典 Feign 调用长期走 fallback。已由 **#1317 热修**（Feign 路径对齐 `/data`）后所有下游字典翻译恢复。 - ---- - -## 部署顺序（仅对测试/正式运维提醒） - -1. DDL: `ALTER TABLE product_itinerary_node ADD COLUMN time_period VARCHAR(32) NULL AFTER start_time` -2. 字典 INSERT 5 条（type 10070 / data 100701~100705） -3. 重新部署 hl-product-service-v2 / hl-order-service-v2 / hl-mp-service（依赖 hl-common-feign 新版 Feign 路径） -4. 清 Redis `cache:dict:data:*`（或等 TTL）防读到旧映射 diff --git a/changelogs/2026-04/23_fix_order-v2_todo-complete-prerequisite.md b/changelogs/2026-04/23_fix_order-v2_todo-complete-prerequisite.md deleted file mode 100644 index f4232d4..0000000 --- a/changelogs/2026-04/23_fix_order-v2_todo-complete-prerequisite.md +++ /dev/null @@ -1,65 +0,0 @@ -# 订单待办完成接口补齐业务前置校验（杜绝空点成功） - -**日期**: 2026-04-23 -**PR**: #1327 (dev) -**Issue**: #1324 -**类型**: fix -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -订单详情页「待办」按钮（分配房间 / 分配车辆 / 确认清单 / 购买保险 / 签署合同）**过去即使对应业务未完成也能直接点成功**，仅改 `order_todo.status=COMPLETED`，但 `order.checklist_confirmed` / `process_status` / 下游保险合同事件全未触发，相当于 UI 假成功。 - -本次修复在 `PUT /admin/order/todo/{todoId}/complete` 内部补齐业务前置校验，未就绪直接返回业务异常。 - -## 接口 - -**路径没变**：`PUT /admin/order/todo/{todoId}/complete` - -**新的错误响应**（HTTP 仍为 200，业务码在 `Result.code`）： - -| 触发场景 | `Result.code` | `Result.msg` | -|---|---|---| -| 点「分配房间」但房间未安排 | BUSINESS_ERROR | `请先在行程安排中完成房间分配` | -| 点「分配车辆」但车辆未安排 | BUSINESS_ERROR | `请先在行程安排中完成车辆分配` | -| 点「购买保险」但未投保 | BUSINESS_ERROR | `请先完成保险购买` | -| 点「签署合同」但合同未签 | BUSINESS_ERROR | `请先完成合同签署` | -| 点「确认清单」但 `process_status ≠ PENDING_CHECKLIST_CONFIRM` | BUSINESS_ERROR | `流程状态不正确,当前: {状态label}` | -| 点「确认清单」但尾款为负 | BUSINESS_ERROR | `确认后尾款为负(¥X),请调整优惠/增项后再确认` | - -> 正常成功仍返回 `{"code":"SUCCESS","data":null}`。 - -## 「确认清单」待办的完整行为（本次接通） - -以前：点「确认清单」只改 `order_todo.status`，没任何副作用。 -现在：点「确认清单」会真正执行锁单全流程： - -- 状态机 `PENDING_CHECKLIST_CONFIRM → READY` -- `order.checklist_confirmed = true`，`order.ready_at` 填充 -- 所有未确认的 `order_discount` / `order_surcharge` 批量 `confirmed = 1`（优惠/增项金额锁定） -- 尾款锁定 -- afterCommit 发布 `ChecklistConfirmedEvent` → 下游保险自动投保 + 合同自动签约流程启动 -- Timeline 新增 `CHECKLIST_CONFIRMED` 记录 - -## 前端联调建议 - -1. 待办按钮点击后的错误提示继续按 `Result.msg` 显示即可，无需改接口调用方式 -2. 「确认清单」按钮点击后建议**刷新订单详情页**，因为会联动触发 process_status + checklist_confirmed + 保险/合同状态变化 -3. 行程安排 tab 的「暂未安排房间/车辆」与顶部待办按钮是一个系统：只要这边没数据，对应待办就点不动（符合直觉） -4. 「购买保险」/「签署合同」待办：只有当前端子模块或管理员在保险/合同页面成功操作后，对应待办才能被点 - -## 幂等与并发 - -- 「确认清单」受 `@Idempotent(keyArg=orderId+operatorId, timeout=60s)` + `@Lock4j('order:checklist:' + orderId)` 双重保护 -- 其余待办按钮依然被单例 activeTodo 机制限制（只有当前序号最小的 PENDING 待办能被完成） - -## 关联字典 - -无新增字典。`ProcessStatus` 枚举取值见 PR #1318 已发布的字典项（本次不动）。 - -## 风险与回滚 - -- 纯后端校验增强，**不改接口签名/返回结构** -- 回滚方式：revert PR #1327 即可恢复到空点成功的旧行为 diff --git a/changelogs/2026-04/23_fix_order-v2_traveler-process-advance.md b/changelogs/2026-04/23_fix_order-v2_traveler-process-advance.md deleted file mode 100644 index 6cc0903..0000000 --- a/changelogs/2026-04/23_fix_order-v2_traveler-process-advance.md +++ /dev/null @@ -1,66 +0,0 @@ -# 管理端补齐出行人后订单 process_status 自动推进（修复顶部常驻「待补全出行人信息」） - -**日期**: 2026-04-23 -**PR**: #1336 (dev) -**Issue**: #1335 -**类型**: fix -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -订单详情页顶部的流程状态标签（如「待补全出行人信息」「待分配房间」「确认中」等）在管理员**逐个补齐出行人**场景下**不会**自动推进。表现：出行人列表 1/1 已完整填写，但顶部仍挂「待补全出行人信息」橙标，同时下游自动化（自动投保 / 自动签约）也不触发。 - -本次修复让管理端两个出行人接口（新增 / 修改）在补齐后自动推进流程状态 `PENDING_TRAVELER_INFO → PENDING_ROOM_CONFIG`，与用户侧小程序自改订单走的是同一条状态机路径（T2, PROC_TRAVELER_DONE）。 - -## 接口（路径不变，响应结构不变） - -- `POST /admin/order/{orderId}/travelers` — 新增出行人 -- `PUT /admin/order/{orderId}/travelers/{travelerId}` — 修改出行人 - -两个接口仍返回 `{"code":200,"message":"成功","data":{TravelerVO}}`，**入参 / 出参均未改动**。 - -## 触发推进的条件 - -满足以下**全部**条件时，接口在事务内自动把 `order.process_status` 从 `PENDING_TRAVELER_INFO` 推进到 `PENDING_ROOM_CONFIG`： - -1. 调用前订单 `process_status = PENDING_TRAVELER_INFO` -2. `actualCount ≥ requiredCount`（`adultCount + childCount + youngChildCount + babyCount`） -3. 所有出行人 `name + idCardType + idCardNo` 三字段均不为空 - -不满足任一条件时**不推进**，也不报错 — 出行人仍能成功新增 / 修改。 - -## 联动变化 - -- 订单详情顶部流程标签：`待补全出行人信息` → `待分配房间` -- 行程安排 tab 待办按钮随之联动（新状态下可点「分配房间」） -- **订单已支付**（status = PAID / DEPOSIT_PAID）时，afterCommit 触发 `orderAutoProcessingService.triggerAutoProcessing`，按原有规则自动投保 + 启动合同签约流程（与 `OrderFieldEditService.replaceTravelers` 已有的触发点行为一致） - -## 前端联调建议 - -1. 补齐 / 修改出行人接口调用后，**建议刷新订单详情**（流程标签 + 待办按钮 + 合同/保险 tab 会联动更新） -2. 「待补全出行人信息」顶部标签不再是"静态数据"，现在会被后端主动翻译 — 前端无需额外判定 -3. `process_status` 字段类型仍为字符串枚举（`PENDING_TRAVELER_INFO` / `PENDING_ROOM_CONFIG` / …），字典详见 `process_status` 字典表，本次未新增值 - -## 幂等与并发 - -- 推进走状态机 + `casAdvanceProcess(PENDING_TRAVELER_INFO → PENDING_ROOM_CONFIG)`，非 `PENDING_TRAVELER_INFO` 状态 CAS miss 自然返回 -- 出行人新增 / 修改保持原有并发语义，无新增锁 - -## 风险与回滚 - -- 纯后端业务逻辑增强，不改接口签名 / 返回结构 -- 最多副作用：每次 add / update 内部多一次 `validateTravelers` 调用（2 次 SELECT），非性能热点 -- 回滚：revert PR #1336 即可恢复为空点成功（继续挂「待补全」橙标） - -## 数据修复 - -生产订单如果出现类似状况（出行人已填完但顶部仍「待补全出行人信息」），可直接 SQL 修复： - -```sql -UPDATE order_info SET process_status='PENDING_ROOM_CONFIG' -WHERE order_id=? AND process_status='PENDING_TRAVELER_INFO'; -``` - -本次测试环境订单 `HL20260423175303-5448`（id=2047252402389598209）已同步修复。 diff --git a/changelogs/2026-04/23_refactor_order-v2_process-status-v2.md b/changelogs/2026-04/23_refactor_order-v2_process-status-v2.md deleted file mode 100644 index f34cf35..0000000 --- a/changelogs/2026-04/23_refactor_order-v2_process-status-v2.md +++ /dev/null @@ -1,114 +0,0 @@ -# 订单内部流程 ProcessStatus V2 重构（Cola 状态机 + 清单确认 + 申请开票） - -**日期**: 2026-04-23 -**PR**: #1318 (dev) -**Issue**: #1310 -**类型**: refactor -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -订单内部流程状态 `ProcessStatus` 彻底重构：线性 switch → Cola 状态机；新增"清单确认"节点统一改尾款；新增"申请开票"C 端入口；房差/车差自动写入优惠/增项。 - -## 新流程 - -``` -PENDING_TRAVELER_INFO → PENDING_ROOM_CONFIG → PENDING_VEHICLE_CONFIG - → PENDING_CHECKLIST_CONFIRM → READY → PENDING_INVOICE -``` - -## 枚举值变化（字典 order_process_status） - -### 删除（老值软删） -- PENDING_INFO / PENDING_ROOM / PENDING_VEHICLE / PENDING_FINANCE -- PENDING_INSURANCE / PENDING_CONTRACT / INTERNAL_CONFIRMED - -### 新增（6 个） -| value | label | 业务含义 | -|-------|-------|---------| -| `PENDING_TRAVELER_INFO` | 待补全出行人信息 | 支付订金/全款后初始态 | -| `PENDING_ROOM_CONFIG` | 配置房子 | 出行人齐全后 | -| `PENDING_VEHICLE_CONFIG` | 配置车辆 | 房型分配后 | -| `PENDING_CHECKLIST_CONFIRM` | 确认清单 | 车辆分配后,确认前 | -| `READY` | 已就绪 | 清单确认通过,保险/合同异步触发 | -| `PENDING_INVOICE` | 待开票 | 尾款付清后用户主动申请开票 | - -## 接口变化（管理端 + C 端） - -### 新增接口 - -#### 1. `POST /admin/order/{orderId}/checklist-confirm` -**管理员确认清单**（把所有未确认优惠/增项批量锁定 → 推进到 READY → 触发保险/合同自动化） -- **权限**: Admin -- **幂等**: `@Idempotent(60s)` · key = `orderId + operatorId` -- **校验**: - - `processStatus == PENDING_CHECKLIST_CONFIRM` - - 尾款计算 `totalPrice - SUM(confirmedDiscount) + SUM(confirmedSurcharge) - paidAmount >= 0`（含即将 confirmed=true 的条目） - - `checklist_confirmed != true`（幂等双保险） -- **响应**: `Result<Void>` -- **失败**: `确认后尾款为负(¥-xxx),请调整优惠/增项` / `流程状态不正确` / `清单已确认` - -#### 2. `POST /mp/orders/{orderId}/checklist/confirm` -**用户端确认清单**（架构预留,本次 PR 未上线 MP Controller,待下个 PR） - -### 修改接口 - -#### 3. `POST /mp/invoices/apply`（既有 `OrderInvoiceService.applyInvoice` 升级） -**申请开票** -- **幂等**: `@Idempotent(300s)` · key = `userId + orderId` -- **新增 Guard**: - - `processStatus == READY` - - OrderStatus NOT IN `{CANCELLED, REFUNDED, REFUNDING}` - - `paidAmount >= totalPrice`（原只检查 `paidAmount > 0`） -- **保留**: 原 countValidByOrderId 判重兜底 -- **失败**: - - `流程状态不允许开票,请先完成确认清单` - - `订单已取消或退款,无法开票` - - `尾款未结清,无法开票` - -### VO 字段变化 - -#### `OrderDiscountVO` / `OrderSurchargeVO`（新增 3 字段） -```json -{ - "confirmed": true, // false=未确认不影响尾款,true=已确认 - "sourceType": "ROOM_ASSIGN", // MANUAL / ROOM_ASSIGN / VEHICLE_ASSIGN - "sourceRefId": 12345 // 来源主键(如 hotel_assignment_id) -} -``` - -#### `OrderVO` / `OrderDetailVO` -- `待确认差价`（`pendingUpgradeAmount`）字段过渡期保留,返回值恒为 0（T+2 周清理 PR 硬删） -- `processStatus` / `processStatusLabel` 返回新 6 个枚举值(字典自动下发 label) - -## 保险/合同触发时机变化（⚠️ 重要） - -- **旧**: 订单 CONFIRMED 时立即自动投保/签约（`OrderConfirmedEvent`） -- **新**: **清单确认时**触发（`ChecklistConfirmedEvent`）→ 避免出行人/房型未定就投保导致的退保重投 -- 失败处理: 业务失败 → 创建 `OrderTodo` 人工补救；5xx/超时 → LocalEvent 兜底 -- ProcessStatus 保持 READY 不变（即使保险或合同失败） - -## 追加优惠/增项自动 REOPEN - -- 订单 `process_status ∈ {READY, PENDING_INVOICE}` + `checklist_confirmed = true` 时 -- 调用 `addDiscount` / `addSurcharge` 会自动触发 `PROC_CHECKLIST_REOPENED` -- 订单回退到 `PENDING_CHECKLIST_CONFIRM`,`checklist_confirmed=false` -- **已完成的保险/合同不反向取消**（业务硬规则） -- 新追加的条目 `confirmed=false`,需要再次"确认清单" - -## 前端影响（前端 AI 必读） - -1. 订单详情页的 `待确认差价` 字段**过渡期保留值为 0**,**不要**继续读此字段做展示；改读 `discounts[]` / `surcharges[]` 数组 + 按 `confirmed` 字段分组展示 -2. 流程状态标签 6 个新中文（字典自动下发） -3. Admin 端**新增"确认清单"按钮**,调 `POST /admin/order/{orderId}/checklist-confirm` -4. Admin 端 `addDiscount` / `addSurcharge` 在订单已 READY/PENDING_INVOICE 时会**自动 REOPEN**,前端需要刷新订单状态 -5. C 端新增"申请开票"入口,调 `POST /mp/invoices/apply`(需订单 processStatus = READY + 尾款已付清) - -## 文档 - -- 需求单 V2: `docs/tasks/order-process-v2-statemachine-20260423.md` -- 架构详设: `docs/tasks/order-process-v2-arch-design-20260423.md` -- 评审报告: `docs/tasks/order-process-v2-review-v2-20260423.md` -- CR 报告: `docs/tasks/order-process-v2-cr-20260423.md` diff --git a/changelogs/2026-04/24_URGENT_admin-ui_upgrade-price-still-missing-after-3-rounds.md b/changelogs/2026-04/24_URGENT_admin-ui_upgrade-price-still-missing-after-3-rounds.md deleted file mode 100644 index c23db5c..0000000 --- a/changelogs/2026-04/24_URGENT_admin-ui_upgrade-price-still-missing-after-3-rounds.md +++ /dev/null @@ -1,95 +0,0 @@ -# 【紧急·第 4 次催办】配房差价 upgradePrice 仍未接入,用户反复复现 - -**日期**: 2026-04-24 14:10 -**类型**: 前端紧急催办 -**受众**: hl-ui 管理后台前端 - ---- - -## 现状 - -后端自 09:40 起已通过 3 次 changelog 提供解决方案(`2429097` 首次指引、`0bdaf78` 后端 guard、`d91b8e1` UNPRICED 标记),**用户今日从 09:40 到 14:10 反复复现同一 BUG 至少 4 次**: - -> 弹窗输入 +200 → 点确认提交 → 财务页仍显示「暂无费用增加项」 - -## 三尺实证(本次复查 14:04:46) - -`SELECT day_number, upgrade_price FROM order_hotel_assignment WHERE order_id=2047252402389598209`: - -| day_number | upgrade_price | -|---|---| -| 1 | **NULL** | -| 2 | **NULL** | -| 3 | **NULL** ← 用户刚输入了 +200 | -| 4 | **NULL** | - -**结论**: 前端保存 4 天 hotel_assignment 时,**依然没传 `upgradePrice` 字段**。后端 calcDayUpgrade 走 systemDiff 分支,命中 PR #1348 guard(assignedPrice=0)→ 跳过该天 → 不写 surcharge。 - -## 前端必修 1 行代码 - -编辑 hotel-assignment 弹窗保存函数,**必须**把每一行的 `dayDiff`(用户在输入框的值)塞进 `assignment.upgradePrice`: - -```js -// ❌ 现在的写法(upgradePrice 字段丢失) -const payload = { - assignments: items.map(d => ({ - familyIndex: d.familyIndex, - hotelId: d.hotelId, - hotelName: d.hotelName, - roomTypeId: d.roomTypeId, - roomType: d.roomType, - dayNumber: d.dayNumber, - remark: d.remark, - // upgradePrice: ??? ← 这一行就是 BUG - })), -}; - -// ✅ 正确写法(补上一行) -const payload = { - assignments: items.map(d => ({ - familyIndex: d.familyIndex, - hotelId: d.hotelId, - hotelName: d.hotelName, - roomTypeId: d.roomTypeId, - roomType: d.roomType, - dayNumber: d.dayNumber, - remark: d.remark, - upgradePrice: d.dayDiffEdited, // ← 必须显式传 - })), -}; -await http.put(`/admin/order/${orderId}/hotel-assignment`, payload); -``` - -- **字段名必须是 `upgradePrice`**(驼峰,匹配后端 `HotelAssignmentItem.upgradePrice` @JsonAlias 无别名) -- **用户未编辑的天**:传 `null` 或省略(后端走 systemDiff) -- **用户编辑过的天**:传数字(后端尊重 override,即使资源价格为 0 也算) - -## 前端验收点(端到端,不要只看 Network Request) - -1. 订单 `HL20260423175303-5448`,弹窗改第 3 天为大床房,手动输入 +200,点确认提交 -2. 打开 DevTools Network,看 `PUT /admin/order/.../hotel-assignment` 请求 body: - - `assignments[dayNumber=3].upgradePrice === 200` ✅(**数值** 200,不是字符串 "200",不是 `null`) -3. 刷新订单详情,财务页应出现: - - **费用增加项**:「升级房型 ¥200.00」(待确认 tag) - - **优惠明细**:仍为空(之前的脏 280 已在服务端清理) -4. 确认清单 → lock → 尾款从 ¥1.90 变为 **¥2.10**(扣 confirmed surcharge 200) - -## 本次数据修复(后端临时) - -为让订单 2047252402389598209 UI **立即符合预期**,已手动插入: -```sql -INSERT INTO order_surcharge (surcharge_name='升级房型', surcharge_amount=200.00, source='ROOM_ASSIGN', confirmed=0) -WHERE order_id=2047252402389598209; -UPDATE order_info SET surcharge_amount=200.00 WHERE order_id=2047252402389598209; -UPDATE order_hotel_assignment SET upgrade_price=200.00 WHERE order_id=2047252402389598209 AND day_number=3; -``` - -这是**仅限本订单**的临时修复。**前端不落地 upgradePrice 之前,其它订单仍会出现同样 BUG**。 - -## 为什么不加 Gitea 工单 - -本项目约定「前端问题不建工单直接告知前端」。但请前端同事把本 changelog 当作**优先级 P0**任务处理,影响所有配房带房型升级/降级的订单。 - -## 后端无可再做 - -后端契约已就绪(`HotelAssignmentRequest.upgradePrice` 字段自老版本就存在)+ PR #1348 防假扣 + PR #1353 unpriced 提示,**全链路只差前端这一行 `upgradePrice: d.dayDiffEdited,`**。 diff --git a/changelogs/2026-04/24_admin-ui_hotel-assignment-roomtype-render-fix.md b/changelogs/2026-04/24_admin-ui_hotel-assignment-roomtype-render-fix.md deleted file mode 100644 index 30f90a1..0000000 --- a/changelogs/2026-04/24_admin-ui_hotel-assignment-roomtype-render-fix.md +++ /dev/null @@ -1,80 +0,0 @@ -# 配房弹窗房型回显为数字 ID(前端问题指引,后端零改动) - -**日期**: 2026-04-24 -**类型**: 前端回显 BUG 指引 -**受众**: hl-ui 管理后台 -**对应界面**: 订单详情 → 行程安排 tab → 点「编辑」房间 → 配房信息弹窗 - ---- - -## 现场 - -订单 `HL20260423175303-5448` 编辑配房信息,弹窗第 1 天家庭 1: -- 酒店下拉正确:**呼伦贝尔香格里拉大酒店** -- 房型下拉**显示为 `20237274031...` 数字 ID**,而非中文房型名「普通标间」 - -## 后端自检结论:无问题 - -测试服实测 `GET /admin/order/2047252402389598209/hotel-assignment`: - -```json -{ - "code": 200, - "data": [ - { - "assignmentId": "2047488048786018306", - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": "2023727403196502017", - "roomType": "普通标间", ← 中文名已返回 - "dayNumber": 1, - "assignmentDate": "2026-04-25", - "remark": "1111" - }, - { - "assignmentId": "2047488048790212610", - "hotelId": "2023714929877450753", - "hotelName": "呼伦贝尔香格里拉大酒店", - "roomTypeId": "3002000000000000013", - "roomType": "大床房", ← 中文名已返回 - "dayNumber": 3, - ... - } - ] -} -``` - -每条 assignment 都同时返回 `roomTypeId`(雪花 ID)+ `roomType`(中文名),字段已就绪,**后端零改动**。 - -## 根因(前端) - -从弹窗现象看,大概率是以下组合之一: - -1. **回显时只绑 `roomTypeId`,没把 `roomType` 喂给 n-select tag 模式的 options 做 label 兜底** - - n-select 的 tag 模式在 options 异步加载前,会直接把 value 当 label 渲染 → ID 数字裸露 - - 典型场景参考:MEMORY 里 `experience/backend-dev/nselect-tag-mode-stringify-race.md`(CitySelect 集合地/解散地同类坑) - -2. **房型 options 列表加载顺序错** - - 酒店切换后应该先调 `GET /admin/resource/hotel/{hotelId}/room-type`(或对应房型下拉接口)拉 options,再回填 `roomTypeId` - - 如果 options 空,n-select 就用 value 字符串渲染 - -## 修复建议 - -- **方案 A(推荐)**:初始化弹窗时,把后端 `hotel-assignment` 返回的每条记录的 `{roomTypeId, roomType}` **当作一条 option 先 unshift 进 options 数组**,保证回显 label 一定有。后续拉接口来的 options 合并去重。 -- **方案 B**:n-select 组件改用 `:render-tag` slot,显式从 `props.option.label` 取值;或 `:fallback-option` 属性指定 label=props.value 兜底时用的模板(改成 `房型 ${val}` 或从 assignment 行数据里查)。 -- **方案 C**:如果 n-select 非 tag 模式,直接传 `:default-value="row.roomTypeId"` + `:default-option="{ label: row.roomType, value: row.roomTypeId }"`。 - -三种方案核心都是:**不要等异步 options 加载完才有 label,用行数据的 `roomType` 字段立刻兜住回显**。 - -## 验证标准 - -- 点「编辑」打开弹窗 → 房型列立刻显示中文房型名(「普通标间」/「大床房」/「俄式标准房」)而不是数字 ID -- 切换酒店时,房型列表刷新,新房型依然显示中文 - -## 为什么不建 Gitea 工单 - -前端问题,按约定直接提供指引,不占 Gitea 待办通道。前端同事按本 changelog 接入即可。 - -## 同类预防 - -MEMORY `feedback_ui-mismatch-verify-backend-data-first.md` + `experience/bug-analyst/ui-not-displaying-data-verify-db-first.md`:遇到"UI 显示不对"类 BUG,先三尺实证(curl 接口 → 看 DB → 看网关)定位后端/前端归属,这次也是先 curl 拿到完整响应才能判定后端零问题。 diff --git a/changelogs/2026-04/24_admin-ui_hotel-assignment-upgrade-price-not-sent.md b/changelogs/2026-04/24_admin-ui_hotel-assignment-upgrade-price-not-sent.md deleted file mode 100644 index 1c1ae08..0000000 --- a/changelogs/2026-04/24_admin-ui_hotel-assignment-upgrade-price-not-sent.md +++ /dev/null @@ -1,103 +0,0 @@ -# 配房差价弹窗用户输入的差价未传给后端(前端 BUG,后端零改动) - -**日期**: 2026-04-24 -**类型**: 前端缺字段 BUG 指引 -**受众**: hl-ui 管理后台 -**对应界面**: 订单详情 → 行程安排 → 编辑房间 → 弹出「配房差价确认」 - ---- - -## 现场 - -订单 `HL20260423175303-5448`: -1. 第一次配房(4 天都是便宜房型),系统算 totalDiff=-280 → 生成「房间优惠 ¥280」 -2. 用户把第 3 天改为大床房,弹窗「配房差价确认」显示 **差价 +200 / 合计 +200 元** -3. 点「确认提交」后,财务页仍显示「房间优惠 ¥280」,**没有 +200 升级房型** - -## 后端自检结论:无问题 - -### 实测 DB 当前 hotel_assignment 数据 - -``` -day=1 普通标间 upgradePrice=null -day=2 俄式标准房 upgradePrice=null -day=3 大床房 upgradePrice=null ← 用户在弹窗输入 +200 -day=4 俄式标准房 upgradePrice=null -``` - -**4 条 assignment 的 `upgradePrice` 全部为 null** — 用户在弹窗里输入的 +200 **根本没传到后端**。 - -### 实测服务端日志(每次提交都命中) - -``` -配房升级差价记录已创建: orderId=2047252402389598209, count=1, totalDiff=-280.00, isCustomizer=true -系统写入分配副作用优惠: amount=280.00 -``` - -后端 `calcDayUpgrade` 逻辑:`assignment.upgradePrice != null ? upgradePrice : systemDiff`。上游没传,必然走 systemDiff,其它 3 天按产品默认对比算出 -480 左右,第 3 天大床房 +200,合计 -280。 - -## 契约:后端已经预留字段(OrderAssignmentService 早就支持) - -`HotelAssignmentRequest.HotelAssignmentItem` 字段(`hl-order-service-v2/src/main/java/com/hulalv/order/assignment/dto/HotelAssignmentRequest.java`): - -```java -@ApiModelProperty(value = "手动覆盖升级差价(null=使用系统计算)") -private BigDecimal upgradePrice; -``` - -这个字段在 `PUT /admin/order/{orderId}/hotel-assignment`(保存配房)**和** `POST /admin/order/{orderId}/hotel-assignment/preview`(预览)**两个接口都接收**。 - -## 前端修复方案 - -### 方案(必做) - -「配房差价确认」弹窗里,每一行**用户可编辑的差价输入框**,应该: - -1. **保存时**:把用户输入值赋给对应 `assignment.upgradePrice`,通过 `PUT /hotel-assignment` 传给后端 -2. **预览时**:同样赋值后调 `POST /hotel-assignment/preview`,保证 preview 和 execute 看到的是同一份 payload - -伪代码: - -```js -function submitHotelAssignment(dayEditedItems) { - const payload = { - assignments: dayEditedItems.map(d => ({ - familyIndex: d.familyIndex, - hotelId: d.hotelId, - hotelName: d.hotelName, - roomTypeId: d.roomTypeId, - roomType: d.roomType, - dayNumber: d.dayNumber, - remark: d.remark, - upgradePrice: d.dayDiffEdited, // ← 本次要补的字段,null 也要显式传 - })), - }; - await http.put(`/admin/order/${orderId}/hotel-assignment`, payload); -} -``` - -### 关键点 - -- **全量替换语义**:`PUT /hotel-assignment` 是全量替换(内部 `deleteByOrderId + insertBatch`)。前端必须**全量**把所有天的 assignment 都传过来,不能只传改动的那一天。 -- **未编辑的天**:`upgradePrice=null`(或省略字段,Jackson 会当 null),后端按系统价计算该天差价。 -- **用户编辑过的天**:把用户输入的数字放到 `upgradePrice`。哪怕只编辑 1 天,其它 3 天也要按原值回填并带上 upgradePrice 处理策略(保持 null 让后端算,或显式传 0 意味"本天按产品默认不算差价")。 - -## 验证步骤 - -1. 用户编辑第 3 天差价 +200 → 提交 -2. 检查请求 body,`assignments[day=3].upgradePrice == 200` -3. 后端日志应出现 `totalDiff=+200`(或其它符合预期的合计) -4. 财务页优惠记录消失,出现「升级房型 ¥200」 - -## 为什么不建 Gitea 工单 - -后端契约早就就绪(字段 `upgradePrice` 在 VO 里,calcDayUpgrade 里的 override 逻辑也在),纯前端保存时漏传。按约定不占 Gitea 待办通道,直接给前端指引。 - -## 同类预防 - -「前后端字段对齐问题」在本仓库历次踩坑里很常见: -- PR #691 GET 分页字段别名双通道 -- PR #819 MyBatis-Plus NOT_NULL 策略 setXxx(null) 写不进 DB -- 本次 `upgradePrice` 契约早就在,但前端漏用 - -建议前端**新字段发布到后端 changelog 后,第一时间在关键提交路径加上该字段**,不要等到用户报错才发现。 diff --git a/changelogs/2026-04/24_admin-ui_todo-button-click-navigate-to-tab.md b/changelogs/2026-04/24_admin-ui_todo-button-click-navigate-to-tab.md deleted file mode 100644 index 48fb201..0000000 --- a/changelogs/2026-04/24_admin-ui_todo-button-click-navigate-to-tab.md +++ /dev/null @@ -1,47 +0,0 @@ -# 订单详情页 5 个待办按钮点击跳转交互指引（前端实现,后端零改动） - -**日期**: 2026-04-24 -**类型**: 前端交互增强 -**受众**: hl-ui 管理后台 -**对应界面**: 订单详情 → 顶部「待办」按钮组 - ---- - -## 现状 - -订单详情页顶部「待办」区已有 5 个按钮(分配房间 / 分配车辆 / 确认清单 / 购买保险 / 签署合同),按 `order_todo.status` 和业务前置校验决定可点性(见 PR #1327 后端校验)。但**点击按钮目前只触发「完成待办」接口**,没有引导用户到对应操作入口。 - -用户场景:点「分配房间」时系统提示 `请先在行程安排中完成房间分配`,用户不知道房间分配在哪个 tab 做,来回找。 - -## 目标 - -5 个待办按钮点击后**先跳转到对应操作 tab**,让用户可以直接进入配置动作,操作完成后按钮会自动变绿(无需手动点"完成")。 - -## 跳转规则 - -| 待办按钮 | 对应页内位置 | 跳转动作 | -|---------|------------|--------| -| **分配房间** | 「行程安排」tab (已有) | 切到 `行程安排` tab,聚焦酒店/房间配置区块 | -| **分配车辆** | 「行程安排」tab (已有) | 切到 `行程安排` tab,聚焦车辆配置区块 | -| **确认清单** | 当前「概览」tab 保留锁单弹窗 | 沿用现有「弹二次确认对话框 → 调 `PUT /admin/order/todo/{todoId}/complete`」逻辑,**无需跳转** | -| **购买保险** | 「合同保险」tab | 切到 `合同保险` tab,聚焦保险子块(若无投保单,点「添加保险」) | -| **签署合同** | 「合同保险」tab | 切到 `合同保险` tab,聚焦合同子块(若无合同,点「新建合同」) | - -## 按钮状态 - -- `completed` (绿色对勾): 不再触发跳转,点击无效 / 或提示「已完成」 -- `pending` 且前置未满足: 跳转到对应 tab,**不调**「完成待办」接口(让用户先去配) -- `pending` 且前置已满足 (例如确认清单): 走原有流程 - -## 为什么不在后端做跳转 - -跳转是 admin UI 的交互,不是业务数据变更。后端已经在 PR #1327 补齐了业务前置校验(未就绪点「完成」会返 BusinessException),这个校验保持不变 — 前端跳转只是避免用户触发这个错误。 - -## 涉及接口(均已存在,前端无需后端配合改动) - -- `GET /admin/order/{orderId}` — 订单详情,返回 `todos` 数组(含 `todoType` 和 `status`) -- 行程安排 tab: `GET /admin/order/{orderId}/hotel-assignment`, `GET /admin/order/{orderId}/vehicle-assignment` 等(已有) -- 合同保险 tab: 保险 / 合同相关接口(已有) -- 「确认清单」完成: `PUT /admin/order/todo/{todoId}/complete`(PR #1327 已上线前置校验) - -## 本 changelog 仅为前端交互指引,不绑工单、不改后端代码,请前端同事按此方案实现。 diff --git a/changelogs/2026-04/24_fix_mp-product_day-hotels-add-hotel-id.md b/changelogs/2026-04/24_fix_mp-product_day-hotels-add-hotel-id.md deleted file mode 100644 index 8b3bbcf..0000000 --- a/changelogs/2026-04/24_fix_mp-product_day-hotels-add-hotel-id.md +++ /dev/null @@ -1,72 +0,0 @@ -# /mp/product/{id} itinerary[].hotels 补 hotelId 字段 - -**日期**: 2026-04-24 -**PR**: #1365 (dev) -**Issue**: #1363 -**类型**: fix -**服务**: hl-product-service-v2 - ---- - -## 摘要 - -小程序产品详情接口 `GET /mp/product/{productId}` 返回的 `itinerary[].hotels[]` 数组**新增 `hotelId` 字段**（String 序列化 Long，与 `roomTypeId` 风格一致），前端酒店卡片终于能拿到 ID 跳转酒店详情页。 - -此前响应只有 `hotelName/roomTypeId/coverUrl/hotelType/city` 等 9 个字段，**没有 hotelId**，点击卡片无法跳详情（根因是后端 VO 未声明字段，`BeanUtil.toBean` 按属性名匹配时静默丢弃）。 - -## 影响接口 - -| 接口 | 字段路径 | -|------|----------| -| `GET /mp/product/{productId}`（orderId 不传，实时路径） | `data.itinerary[].hotels[].hotelId` | -| `GET /mp/product/{productId}?orderId=xxx`（快照路径） | `data.itinerary[].hotels[].hotelId` | -| `GET /mp/product/{productId}/day/{dayNumber}` 复用同 VO | `data.hotels[].hotelId` | - -GROUP / CORE / CUSTOM 三类产品 + 快照路径一并修复。 - -## 新字段 - -```json -{ - "data": { - "itinerary": [ - { - "dayNumber": 1, - "hotels": [ - { - "hotelId": "2023714929877450753", // ⬅️ 新增 - "hotelName": "呼伦贝尔香格里拉大酒店", - "tierSeq": 1, - "tierName": "轻奢", - "roomTypeId": "2023727403196502017", - "roomTypeName": "普通标间", - "roomCount": 8, - "coverUrl": "...", - "hotelType": "HOTEL", - "city": "呼伦贝尔市" - } - ] - } - ] - } -} -``` - -**注意**：`hotelId` 是 `Long` 类型但后端走全局 `NumberSerializer` **输出为 String**（规避前端大整数精度问题），前端务必按 String 接收。 - -## 前端适配建议 - -- 酒店卡片点击事件可以读 `hotels[i].hotelId` 直接跳酒店详情页（此前只能跳房型详情或降级处理） -- 老前端不读 `hotelId` 也不受影响（纯增字段，向后兼容） - -## 验证 - -- 测试服 `GET /mp/product/2044306857534636034`：`itinerary[0].hotels[0].hotelId = "2023714929877450753"` ✓ -- 同响应第 2 天 `hotels[0].hotelId = "3001000000000000002"` ✓ - -## 风险与回滚 - -- 纯增字段，JSON 向后兼容，无签名变化 -- 缓存：`mp:product:detail` 5min TTL / `mp:product:snapshot` 24h TTL，测试环境已过期/覆盖 -- 单测：hl-product-service-v2 模块 966 全绿 -- 回滚：revert PR #1365 即可 diff --git a/changelogs/2026-04/24_fix_order-v2_balance-unconfirmed-discount.md b/changelogs/2026-04/24_fix_order-v2_balance-unconfirmed-discount.md deleted file mode 100644 index a2c2f0e..0000000 --- a/changelogs/2026-04/24_fix_order-v2_balance-unconfirmed-discount.md +++ /dev/null @@ -1,70 +0,0 @@ -# 未确认优惠不再扣减尾款(修复 balanceAmount 负数显示) - -**日期**: 2026-04-24 -**PR**: #1340 (dev) -**Issue**: #1339 -**类型**: fix -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -订单详情页/列表页的**尾款字段 `balanceAmount`** 之前会把**未确认优惠**也扣进去,导致优惠金额大于总售价时显示为**负数**(例如总售价 ¥2.00、未确认优惠 ¥560.00、已付 ¥0.10 → 尾款 ¥-558.10),但同页文案又写着「**以下优惠未确认,暂不影响尾款**」,自相矛盾。 - -本次修复统一让 3 处尾款计算走 `BalanceCalculator`(架构详设 3.1 唯一真相源),**只扣 `confirmed=1` 的已确认优惠/增项**,符合清单确认前「暂不影响尾款」的业务承诺。 - -## 影响接口(路径/返回结构不变) - -所有返回 `balanceAmount` 字段的接口,行为一致性修复: - -| 接口 | 来源 | -|------|------| -| `GET /admin/order/{orderId}` | `OrderDetailQueryService.assembleDetail` | -| `GET /admin/order/page` | `OrderListQueryService.toOrderListVO` | -| `GET /mp/order/page` | `OrderListQueryService.toMpOrderListVO` | -| `GET /mp/order/{orderId}` | `MpOrderDetailAssembler.buildBasicFields` | - -## 新旧对比 - -### 旧公式(3 处都一样) -``` -balance = totalPrice - order.discountAmount + order.surchargeAmount - (depositAmount 或 paidAmount) -``` -其中 `order.discountAmount` = DB 缓存字段,**包含未确认优惠**。 - -### 新公式(统一走 BalanceCalculator) -``` -balance = totalPrice - Σ(confirmed=1 优惠) + Σ(confirmed=1 增项) - paidAmount -``` -未确认条目(confirmed=0 或 NULL)**不算入尾款**。 - -## 前端视图影响 - -- **顶部「尾款」** 由 -558.10 之类的异常值变为合理值(本订单场景 = 1.90) -- **顶部「优惠」合计金额**(`discountAmount` 字段) **保持不变** — 仍显示所有优惠之和(含 pending),前端继续按原字段渲染无需改动 -- 确认清单时后端 T5 状态机 guard 会拦截「尾款为负」导致的锁单(此行为原已存在,本 PR 不动) - -## 行为举例 - -订单场景:总售价 ¥2.00,订金 ¥0.10,已付 ¥0.10,一条 ¥560 房间优惠 confirmed=0 - -| 字段 | 修复前 | 修复后 | -|------|--------|--------| -| totalPrice | 2.00 | 2.00 | -| paidAmount | 0.10 | 0.10 | -| discountAmount(合计展示) | 560.00 | 560.00 | -| **balanceAmount(尾款)** | **-558.10** | **1.90** | - -确认清单把优惠 `confirmed` 置 1 后,balanceAmount 才会变为 -558.10;届时 T5 状态机 guard 会拒绝锁单,提示管理员先清理超额优惠。 - -## 风险与回滚 - -- 只改 VO 组装层,不改接口签名/字段/DB schema -- 所有单测(MpOrderDetailAssemblerTest 63/63、OrderDetailQueryServiceTest 17/17、OrderListQueryServiceTest 8/8)+ 全量 2414/2415 通过 -- 测试服 curl 验证:订单 `HL20260423175303-5448` balanceAmount 从 -558.10 修正为 1.90 -- 回滚:revert PR #1340 即可恢复旧行为 - -## 遗留优化(后续独立 PR) - -`order_info.discount_amount` 字段由 `OrderDiscountService.sumByOrderId` 写入时未过滤 `confirmed`,语义上包含 pending。本 PR 未动(前端「优惠合计」依赖这个字段显示 pending+confirmed 总和)。后续会单独统一语义并给前端提供独立 `pendingDiscountSum` / `confirmedDiscountSum` 字段,本次不涉及。 diff --git a/changelogs/2026-04/24_fix_order-v2_policy-pdf-view-and-retry.md b/changelogs/2026-04/24_fix_order-v2_policy-pdf-view-and-retry.md deleted file mode 100644 index 4d12adb..0000000 --- a/changelogs/2026-04/24_fix_order-v2_policy-pdf-view-and-retry.md +++ /dev/null @@ -1,79 +0,0 @@ -# 保单 PDF 上传链路修复 + 新增重试接口 - -**日期**: 2026-04-24 -**PR**: #1369 (dev) -**Issue**: #1367 -**类型**: fix + feat -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -订单详情 → 合同保险 tab → 保险保障 → 点击「查看保单」之前对很多已承保订单会弹「暂无保单文件」。根因是测试服 Nacos `hl-order-service-v2-test.yml` 未配置 `oss:` 段,承保成功后的异步保单 PDF 上传被 `PolicyPdfUploadService.init()` 的 `configured=false` 静默跳过,`insurance_order.policy_pdf_url` 永远为 NULL。 - -本次修复三件事: -1. 配置侧: Nacos 已补齐 `oss:` 配置 -2. 代码侧: `AsyncConfig` 新增 `insuranceTaskExecutor` bean(之前悬空 qualifier),`PolicyPdfUploadService` self-injection 修 `@Async` 自调用陷阱 -3. 体验侧: 新增单订单重试接口 + 空 URL 时自动异步补传 + 友好文案 - -## 受影响接口 - -| 接口 | 方法 | 变化 | -|------|------|------| -| `GET /admin/insurance/policy/{id}/download` | GET | 行为增强: `policy_pdf_url` 为空时 fire-and-forget 异步补传一次 + 抛文案「保单生成中,约 30 秒后可重试」(原文案「保单PDF尚未上传,请稍后再试或手动触发上传」) | -| `POST /admin/insurance/policy/{id}/retry-upload` | POST | **新增**: 同步触发单个保单 PDF 补传, 成功返回 OSS URL, 失败抛 BusinessException | -| `POST /admin/insurance/upload-missing-pdfs` | POST | 行为修正: 原先同类自调用导致 @Async 退化为串行, 现改走代理真异步, 返回的 `data` 是「提交的任务数」不是「已完成数」 | - -## 前端需要的改动 - -- **无强制改动**。原「查看保单」接口路径、签名、成功路径返回都不变。 -- **文案建议同步**: 当接口返回 `code=500 message="保单生成中,约 30 秒后可重试"` 时, 建议前端把 toast 从「暂无保单文件」改成「保单生成中,约 30 秒后可重试」, 并可在 30 秒后再次点击自动重试。 -- **可选接入**: 新接口 `POST /admin/insurance/policy/{id}/retry-upload` 可以做成订单详情「查看保单」旁的「手动重试」按钮; 响应结构 `Result<String>`, `data` 是 PDF 的 OSS URL。同步耗时 ≈ 保游网下载 PDF + OSS 上传, 一般 5-10 秒。 - -## 请求/响应示例 - -### GET /admin/insurance/policy/{id}/download - -保单已生成(happy path): -```json -{ - "code": 200, - "message": "成功", - "data": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/insurance/policy/2026/04/24/policy_2047591721386098690.pdf", - "success": true -} -``` - -保单刚承保、PDF 还没来得及上传: -```json -{ - "code": 500, - "message": "保单生成中,约 30 秒后可重试", - "data": null, - "success": false -} -``` -后端已异步补传,前端 30 秒后重试即可拿到 URL。 - -### POST /admin/insurance/policy/{id}/retry-upload - -成功: -```json -{ - "code": 200, - "message": "成功", - "data": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/insurance/policy/2026/04/24/policy_xxx.pdf", - "success": true -} -``` - -失败(订单状态不对 / 外部保单号缺失 / 保游网还没生成 / OSS 未配置): -```json -{ - "code": 500, - "message": "保单PDF暂不可补传,请稍后再试或检查保险订单状态", - "data": null, - "success": false -} -``` diff --git a/changelogs/2026-04/24_fix_order-v2_room-diff-preview-unpriced-direction.md b/changelogs/2026-04/24_fix_order-v2_room-diff-preview-unpriced-direction.md deleted file mode 100644 index b694339..0000000 --- a/changelogs/2026-04/24_fix_order-v2_room-diff-preview-unpriced-direction.md +++ /dev/null @@ -1,101 +0,0 @@ -# 配房差价 VO 新增 priceMissing 字段 + direction 新值 UNPRICED(价格未录入提示) - -**日期**: 2026-04-24 -**PR**: #1353 (dev) -**Issue**: #1349 -**类型**: fix / enhance -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -`POST /admin/order/{orderId}/hotel-assignment/preview` 返回的 `RoomUpgradePreviewVO` 和内嵌 `DayUpgradeDetail`: - -1. **新增字段 `priceMissing: Boolean`** — 标记该天/该 VO 是否因房型价格未录入而无法算差价 -2. **`direction` 字段新增枚举值 `UNPRICED`** — 所有差价天均为价格未录入时 `RoomUpgradePreviewVO.direction=UNPRICED`;单天 `DayUpgradeDetail.direction=UNPRICED` -3. **`description` 文案增强** — 含未录入天数时拼接「另有 N 天房型价格未录入,请联系运营补录后再算差价」 - -## 背景 - -PR #1348 在房型价格未录入(`queryDayPrice` 返 0)时把整天跳过不进 `details`,保住了「防假扣 280」但造成副作用:用户配非默认房型依然显示「无差价」(details 空)。本 PR 把 unpriced 天保留进 `details` 并明确标记,前端可区分「真无差价」和「价格待录入」。 - -## 字段契约 - -### `DayUpgradeDetail` -```jsonc -{ - "familyIndex": 1, - "date": "2026-04-27", - "defaultRoomTypeId": "2023727403196502017", - "defaultRoomTypeName": "普通标间", - "assignedRoomTypeId": "3002000000000000013", - "assignedRoomTypeName": "大床房", - "defaultPrice": 280.00, - "assignedPrice": 0, - "dayDiff": 0, - "direction": "UNPRICED", // 新枚举值 - "priceMissing": true, // 新字段: true 表示价格未录入 - "remark": "1111" -} -``` - -### `RoomUpgradePreviewVO` -```jsonc -{ - "details": [ ... ], - "totalDiff": 0, - "direction": "UNPRICED", // 所有天都 unpriced 时;否则仍是 UPGRADE/DOWNGRADE/MIXED/SAME - "description": "共 2 天有差价,合计+200;另有 1 天房型价格未录入,请联系运营补录后再算差价" -} -``` - -## direction 枚举值完整表 - -| 值 | 含义 | -|---|---| -| `UPGRADE` | 升级(`dayDiff > 0`) | -| `DOWNGRADE` | 降级(`dayDiff < 0`) | -| `SAME` | 一致 / 无差价 / details 空 | -| `MIXED` | 既有升级又有降级 | -| **`UNPRICED`**(新) | 房型价格未录入,该天/该 VO 不计入差价,仅提示 | - -## 前端渲染建议 - -- **`DayUpgradeDetail.direction === 'UNPRICED' / priceMissing === true`** — 该行用红字/tag 提示「价格未录入, 请联系运营补录」,不显示 dayDiff 数字(或显示灰色 0) -- **`RoomUpgradePreviewVO.direction === 'UNPRICED'`** — 顶部 alert 用 warning 色调而不是 info -- **`totalDiff === 0` 且 `description` 含「价格未录入」** — 保留「确认提交」按钮但提示「本订单存在价格未录入天,本次提交不会产生差价,建议运营补录后重新配房」 -- `priceMissing` 的条目**不影响**顶部 totalDiff 数字 - -## 测试服实测(订单 2047252402389598209 第 3 天大床房) - -``` -POST /preview -{ - "assignments": [ - {"familyIndex":1,"hotelId":...,"roomTypeId":3002000000000000013,"roomType":"大床房","dayNumber":3} - ] -} - -响应: -{ - "code": 200, - "data": { - "details": [{ - "priceMissing": true, - "direction": "UNPRICED", - "dayDiff": 0, - ... - }], - "totalDiff": 0, - "direction": "UNPRICED", - "description": "另有 1 天房型价格未录入,请联系运营补录后再算差价" - } -} -``` - -## 风险与回滚 - -- 新增字段 `priceMissing` 和新枚举值 `UNPRICED` 对历史前端**向后兼容**:不识别 UNPRICED 的旧前端会把它当 SAME 处理(退化到「无差价」),不会崩 -- 接口路径/其它字段/DB 不变 -- 回滚:revert PR #1353 恢复 PR #1348 行为 diff --git a/changelogs/2026-04/24_fix_order-v2_team-report-prefill-fields.md b/changelogs/2026-04/24_fix_order-v2_team-report-prefill-fields.md deleted file mode 100644 index 3457440..0000000 --- a/changelogs/2026-04/24_fix_order-v2_team-report-prefill-fields.md +++ /dev/null @@ -1,106 +0,0 @@ -# 同步 tab 团队填报 prefill 修 3 处字段 + 新增按钮组 label 下发 - -**日期**: 2026-04-24 -**PR**: #1380 (dev) -**Issue**: #1377 -**类型**: fix + feat (API 扩字段, 前端零改动即可接入 label) -**服务**: hl-order-service-v2 - ---- - -## 摘要 - -订单详情 → 同步 tab (team-report) → 基础信息卡片, 修 3 个 prefill 问题: - -1. **旅行社编码按钮组显英文 code** → 后端 prefill 返回值新增 `agencyOptions: [{code, name}]`, 前端按钮组 label 走 `name` 显示中文, value 继续走 `code` -2. **「团号」填整串订单号** → 修为短号 (`order_info.group_code`, 订单头显示的 `5448`), 不再是 `HL20260423175303-5448` -3. **「出发市」固定呼和浩特市** → 从 `product_snapshot.itinerary[0].gatherPlace.fullPath` + 最后一天 `dismissalPlace.fullPath` 拆出省/市 - -## 受影响接口 - -| 接口 | 方法 | 变化 | -|---|---|---| -| `GET /admin/team-report/prefill/{orderId}` | GET | `teamId` 改用 `order_info.group_code`; `sourceProvince/sourceCity/destinationProvince/destinationCity` 改从 `itinerary[i].gatherPlace.fullPath` 解析; **新增 `agencyOptions: List<{code, name}>` + `businessTypeOptions: List<{code, name}>` 两个只读字段** | - -## TeamReportFormDTO 新增字段 - -```json -{ - "agencyCode": "hulai", - "teamId": "5448", - "sourceProvince": "内蒙古自治区", - "sourceCity": "呼伦贝尔市", - "destinationProvince": "内蒙古自治区", - "destinationCity": "兴安盟", - - "agencyOptions": [ - {"code": "hulai", "name": "内蒙古呼籁国际旅行社有限公司"}, - {"code": "qianshou", "name": "内蒙古呼籁山河国际旅行社有限公司"}, - {"code": "hulai-wenlu", "name": "内蒙古呼籁文旅投资开发集团有限公司"} - ], - "businessTypeOptions": [ - {"code": 2, "name": "国内游组团"}, - {"code": 6, "name": "入境接待"}, - {"code": 7, "name": "国内接待"} - ] -} -``` - -## 前端改动建议 - -- 旅行社编码按钮组: 原硬编码 `['hulai','qianshou','hulai-wenlu']` → 改用 `agencyOptions`, `label=name` `value=code` -- 业务类型按钮组: 原硬编码 `[2,6,7]` → 改用 `businessTypeOptions` -- 其他字段 (`teamId` / `sourceCity` / `destinationCity` 等) 接口签名不变, 前端只需要展示后端返回值即可, 无需任何改动 - -## 行为不变的地方 - -- `agencyCode` / `businessType` 字段类型与原先一致 (前者 String code, 后者 Integer) -- 保存/提交接口 (`/save`、`/submit`、`/cancel`、`/status`) 无改动 - -## 🚨 紧急:用户 2026-04-24 截图反馈「旅行社编码按钮组仍显英文 code」,必须接 options - -后端已返 (curl `https://api.test.1814.love:9443/admin/team-report/prefill/2047252402389598209` 实测): -```json -"agencyOptions": [ - {"code": "bohua-test", "name": "内蒙古博华牛牛测试旅行社有限公司123"}, - {"code": "hulai", "name": "内蒙古呼籁国际旅行社有限公司"}, - {"code": "qianshou", "name": "内蒙古呼籁山河国际旅行社有限公司"}, - {"code": "hulai-wenlu", "name": "内蒙古呼籁文旅投资开发集团有限公司"} -] -``` - -前端同步 tab「基础信息」→「旅行社编码」按钮组**当前大概率硬编码了** -```js -const AGENCY_CODES = ['hulai', 'qianshou', 'hulai-wenlu'] -// 或 <n-radio-button v-for="c in AGENCY_CODES" :value="c">{{ c }}</n-radio-button> -``` - -请改为 (Vue3 + naive-ui 示例): - -```vue -<n-radio-group v-model:value="form.agencyCode"> - <n-radio-button - v-for="opt in form.agencyOptions || []" - :key="opt.code" - :value="opt.code" - > - {{ opt.name }} - </n-radio-button> -</n-radio-group> -``` - -「业务类型」按钮组同样改走 `form.businessTypeOptions`: - -```vue -<n-radio-group v-model:value="form.businessType"> - <n-radio-button - v-for="opt in form.businessTypeOptions || []" - :key="opt.code" - :value="opt.code" - > - {{ opt.name }} - </n-radio-button> -</n-radio-group> -``` - -**注意**: `value` 绑 `code` (提交给后端还是 `qianshou` / `2`), `label` 文本用 `name` 显示中文。这样既保持 12301 上报 contract, 又解决用户反馈的「英文 code 不好看」问题。 diff --git a/changelogs/2026-04/24_ui_order-detail_insurance-card-add-refund-button.md b/changelogs/2026-04/24_ui_order-detail_insurance-card-add-refund-button.md deleted file mode 100644 index c6fde00..0000000 --- a/changelogs/2026-04/24_ui_order-detail_insurance-card-add-refund-button.md +++ /dev/null @@ -1,94 +0,0 @@ -# 订单详情保险保障卡片补「退保」按钮 - -**日期**: 2026-04-24 -**Issue**: #1384 -**类型**: ui (前端改动, 后端零改动) - ---- - -## 摘要 - -用户截图反馈订单详情 → 合同保险 tab → 保险保障卡片 (状态「已承保」) **只有「查看保单」按钮, 没有退保入口**。后端 `POST /admin/insurance/cancel/{id}` 历史已就位 (保游网 `/Insurance/CancelIns` 封装完整, 状态机 INSURED→CANCELLED 已跑通, 该订单历史也有 CANCELLED 记录), 独立「保险订单列表」页据说已有退保按钮, 仅是**订单详情嵌入的保险卡片组件漏了**。 - -## 后端接口 - -已有 (无需改动): - -``` -POST /admin/insurance/cancel/{insuranceOrderId} - → Result<InsuranceOrderDetailVO> - -业务规则: -- 仅允许 status == INSURED 的保险订单调用 -- 调保游网 /Insurance/CancelIns 后, 成功或返回「正在退保中」都把 DB status 改为 CANCELLED -- 其他失败抛 BusinessException 带保游网错误文案 -``` - -## 前端改动 - -订单详情页合同保险 tab → 保险保障卡片组件, 右下角「查看保单」旁加一个「退保」按钮: - -```vue -<template> - <!-- 保险保障卡片底部 action 区 --> - <div class="card-actions"> - <n-button text type="info" @click="handleViewPolicy(insurance.insuranceOrderId)"> - 查看保单 - </n-button> - <!-- 新增:仅 INSURED 显示 --> - <n-button - v-if="insurance.status === 'INSURED'" - text - type="error" - @click="handleRefund(insurance.insuranceOrderId)" - > - 退保 - </n-button> - </div> -</template> - -<script setup> -import { useDialog, useMessage } from 'naive-ui' -import { adminInsuranceCancel } from '@/api/insurance' // 复用保险订单列表页已有的 api - -const dialog = useDialog() -const message = useMessage() -const emit = defineEmits(['refresh']) - -async function handleRefund(insuranceOrderId) { - dialog.warning({ - title: '确认退保', - content: '将调保游网撤单, 成功后订单状态变为「已退保」。此操作不可逆。', - positiveText: '确认退保', - negativeText: '取消', - onPositiveClick: async () => { - try { - await adminInsuranceCancel(insuranceOrderId) - message.success('退保成功') - emit('refresh') // 刷新订单详情 - } catch (e) { - message.error(e?.message || '退保失败') - } - } - }) -} -</script> -``` - -## 显示规则 - -| 保险 status | 显示「查看保单」 | 显示「退保」 | -|---|---|---| -| PENDING | ❌ (无保单) | ❌ | -| INSURING | ❌ | ❌ | -| INSURED | ✅ | ✅ | -| CANCELLED | ✅ (可下载历史保单) | ❌ | -| FAILED | ❌ | ❌ | - -## 验收点 - -- [ ] 订单 `2047252402389598209` 详情 → 合同保险 tab → 保险保障卡片右下角出现「退保」按钮 -- [ ] 点击弹二次确认, 确认后调 `POST /admin/insurance/cancel/2047591721386098690` -- [ ] 响应成功 → 卡片状态角标由「已承保」变「已退保」, 自动刷新 -- [ ] 响应失败 (保游网错误) → toast 显示错误原因, 状态不变 -- [ ] CANCELLED / FAILED / PENDING 状态不显示退保按钮 diff --git a/changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md b/changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md deleted file mode 100644 index ff8c201..0000000 --- a/changelogs/2026-04/27_breaking_order-v2_pending-upgrade-amount-removed.md +++ /dev/null @@ -1,51 +0,0 @@ -# ⚠️ Breaking: 订单详情响应硬删 `pendingUpgradeAmount` 字段 - -**日期**: 2026-04-27 -**PR**: #1320 (T+2 周收尾, 主 PR #1318) -**类型**: Breaking — 字段从响应中移除 -**影响端**: 管理后台 (admin) + 微信小程序 (mp) - ---- - -## 影响接口 - -- `GET /admin/orders/{id}`(订单详情 - 管理端) -- `GET /mp/orders/{id}`(订单详情 - 小程序端) - -两个接口的响应顶层 `OrderDetailVO` **不再返回** `pendingUpgradeAmount` 字段。 - -## 字段含义(已废弃) - -``` -"pendingUpgradeAmount": "0.00" // 待确认差价总额(配房/配车升级未确认) -``` - -主 PR #1318 (2026-04-23) 上线 V2 流程后, 差价已归并入 `OrderDiscount`(负) / `OrderSurcharge`(正), 该字段值已恒为 `0.00`(兼容字段)。今天 (T+2 周) 完成硬删。 - -## 前端动作 - -### 必须 ✅ -- 移除任何对响应 `pendingUpgradeAmount` 字段的读取与渲染代码(`undefined` 不会触发渲染异常,但属于死代码) - -### 建议 (如确实需要差价) ✅ -- 走订单优惠/增项明细字段 — 各自带 `confirmed` 状态: - - `discounts: [{ amount, confirmed, sourceType, ...}]` - - `surcharges: [{ amount, confirmed, sourceType, ...}]` -- 用 `surchargeAmount` 字段(已确认增项总额)代替原"待确认差价"用途时,需注意语义已变为**已确认** - -## 不受影响的字段(保留) - -- `OrderDetailVO.discountAmount`(优惠总额) -- `OrderDetailVO.surchargeAmount`(增项总额) -- `OrderDetailVO.depositAmount` / `depositRatio`(订金) -- 其它金额字段全部不动 - -## 部署时机 - -- dev 已合并 (`af55ee62`), 测试服部署后立即生效 -- 正式服将在测试服稳定 ≥ 24h 后部署 - -## 关联 - -- 主 PR #1318 (订单内部流程 V2, 已合并 2026-04-23) -- 后端 changelog: `hl-backend-changelog/changelogs/2026-04/2026-04-27_order-v2_t2-cleanup-pending-upgrade-amount-and-dict-hard-delete.md` diff --git a/changelogs/2026-04/27_breaking_resource_batch-delete-result-and-restaurant-json.md b/changelogs/2026-04/27_breaking_resource_batch-delete-result-and-restaurant-json.md deleted file mode 100644 index 46e11ef..0000000 --- a/changelogs/2026-04/27_breaking_resource_batch-delete-result-and-restaurant-json.md +++ /dev/null @@ -1,170 +0,0 @@ -# Breaking: 资源批删返回结构改变 + 餐厅 JSON 字段类型变更 - -**日期**: 2026-04-27 -**PR**: #1474 (Closes #1472) + #1475 (Closes #1473) -**类型**: Breaking — 响应字段语义变化(软兼容) -**影响端**: 管理后台 (admin) — 8 个资源类的批量删除接口 + 餐厅详情/编辑页 - ---- - -## 1. 批量删除接口响应结构改变 (#1474) - -### 影响接口 - -| 接口 | path | -|---|---| -| 景区批删 | `DELETE /admin/scenic/spots/batch` | -| 酒店批删 | `DELETE /admin/hotel/items/batch` | -| 餐厅批删 | `DELETE /admin/restaurant/items/batch` | -| 活动批删 | `DELETE /admin/activity/items/batch` | -| 服务项批删 | `DELETE /admin/service/items/batch` | -| 工作人员批删 | `DELETE /admin/staff/items/batch` | -| 物资批删 | `DELETE /admin/supplies/items/batch` | -| 车辆批删 | `DELETE /admin/vehicle/models/batch` | - -### 改前响应 - -```json -{ "code": 200, "data": null, "message": "成功" } -``` - -或一旦遇越权立即整体失败: - -```json -{ "code": 400, "data": null, "message": "仅创建者或超级管理员可删除该景区" } -``` - -### 改后响应 - -无论部分成功/全失败/全成功一律 `code=200`,业务结果在 `data`: - -```json -{ - "code": 200, - "message": "成功", - "data": { - "successCount": 3, - "deniedIds": [10001, 10002], - "deniedReasons": ["无权限", "审批进行中"] - } -} -``` - -### 字段说明 - -- `successCount` — 真实删除成功的条数 -- `deniedIds` — 被拒的 ID 列表(顺序与传入一致,但只含被拒的) -- `deniedReasons` — 与 `deniedIds` 等长的原因数组,**顺序一一对应** - -### 取值集 - -`deniedReasons` 可能值: - -| 文案 | 含义 | -|---|---| -| `记录不存在` | DB 找不到该 ID(可能已被他人删除) | -| `无权限` | 非 SUPER_ADMIN 且非创建者 | -| `已启用,不可删除` | 仅 hotel — 启用状态酒店不允许批删 | -| `审批进行中` | 仅 hotel — 审批未结束不允许批删 | -| `删除失败` | DB 操作异常兜底 | - -### 前端建议 - -- **toast 提示** 改为「**已删除 N 条,M 条因 [拼接原因] 跳过**」 - ```js - const { successCount, deniedIds, deniedReasons } = res.data || {} - if (deniedIds?.length) { - const summary = [...new Set(deniedReasons)].join('/') - msg.success(`已删除 ${successCount} 条,${deniedIds.length} 条因 ${summary} 跳过`) - } else { - msg.success(`已删除 ${successCount} 条`) - } - ``` -- **软兼容**:不读 `data` 的老前端仍正常 toast 成功(code=200 还在),只是缺失精细提示 -- 不再有「越权全失败」场景;原本「批删 OK 但实际只删了部分」的混淆消失 - ---- - -## 2. 餐厅 JSON 字段类型变更 (#1475 P1) - -### 影响接口 - -- `GET /admin/restaurant/item/{id}` (详情) -- `PUT /admin/restaurant/item/{id}` (修改) -- `POST /admin/restaurant/item` (新建) -- `GET /admin/restaurant` (列表 — 仅返回字段一致) - -### 三字段类型 String → Object - -| 字段 | 改前类型 | 改后类型 | 说明 | -|---|---|---|---| -| `featuredMenu` | `String` (内含 JSON 字符串) | `Object` (List/Map/String 都可) | 招牌菜单 | -| `featureIntro` | `String` | `Object` | 餐厅特色 | -| `arrangement` | `String` | `Object` | 座位布局 | - -### 修前的痛(蒋雨莲已踩生产) - -前端 textarea 输出纯文本「招牌菜1\n招牌菜2」直接 PUT,后端 MySQL 抛 `Cannot create a JSON value from a string`,返回 400 `"保存失败,请检查输入或稍后重试"`。 - -### 修后 - -后端无论收到 String / List<Map> / Map / null 都能存入 JSON 列(`JacksonTypeHandler` 自动序列化)。GET 也按 typeHandler 反序列化,前端拿到的字段类型与 PUT 时一致。 - -### 前端动作 - -#### 必须 ✅ - -- **EditModal 提交时不要 `JSON.stringify`** 包外层(以前为绕开 String 校验可能这么写过) — 直接把 List/Map 对象作为字段值即可 - ```js - // 改前(绕过 BUG 用) - payload.featuredMenu = JSON.stringify([...]); // ❌ 现在不需要了 - - // 改后 - payload.featuredMenu = [...]; // ✅ 直接传 List - ``` -- 详情渲染时 **类型守卫**:`Array.isArray(featuredMenu) ? renderList(...) : renderText(...)` — 因为历史数据可能是字符串,新数据是 List - -#### 建议 ✅ - -- 把 textarea/RichText 编辑器升级为**结构化菜单/段落编辑器**,产出格式固定为: - ```json - [ - {"name":"菜名","price":88,"images":[],"description":"..."}, - ... - ] - ``` -- 详情查询里这三字段已经是 List<Map> 结构,前端可直接 `.map(item => ...)` 渲染 - ---- - -## 3. 新增错误码 422 (来自 #1475 GlobalExceptionHandler) - -后端今后遇到「Cannot create a JSON value from a string」类异常时返: - -```json -{ - "code": 422, - "message": "字段格式错误,请联系开发: 数据库 JSON 列收到了非 JSON 字符串(可能是 schema drift)" -} -``` - -前端可以显示「数据格式不对,请联系后端检查」之类的清晰提示,而不是兜底「保存失败」。 - ---- - -## 部署时机 - -- 测试服: 2026-04-27 15:46 已部署 hl-resource-service ✅ -- 正式服: 待跟进部署后立即生效(无需 DDL) - -## 兼容性总结 - -| 改动 | 老前端表现 | 新前端建议 | -|---|---|---| -| #1474 batchDelete 返回 VO | code=200 仍 toast 成功(不读 data) | 解析 `successCount/deniedIds/deniedReasons` 显示精细提示 | -| #1475 餐厅 JSON 字段 Object | 老接口收到 List 可能解析报错 | 加 `Array.isArray` 类型守卫;提交时不再 stringify | - -## 关联 - -- 反馈人: 蒋雨莲 (橙子) 2026-04-27 -- 后端 changelog: `hl-backend-changelog/changelogs/2026-04/2026-04-27_resource_batch-delete-resilient-and-restaurant-json-drift.md` diff --git a/changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md b/changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md deleted file mode 100644 index 5acf589..0000000 --- a/changelogs/2026-04/27_feat_traveler_idcardtype-dict-and-label.md +++ /dev/null @@ -1,78 +0,0 @@ -# 旅客证件类型字段字典化 + 中文 label 装配 - -**日期**: 2026-04-27 -**PR**: #1459 (Closes #1458) -**影响端**: 小程序 mp + 管理端 admin - -## 背景 - -旅客证件类型字段 `idCardType` 全链路统一走字典 `id_card_type`, 前端能直接拿到中文 `idCardTypeLabel` 翻译, 不再需要前端硬编码 enum. - -字典 `id_card_type` 6 个 value (与之前一致): -- `ID_CARD` → 身份证 -- `PASSPORT` → 护照 -- `HK_MACAU_PASS` → 港澳通行证 ⚠️ 注意是 `MACAU` (字母 U), 不是历史误用的 `MACAO` (字母 O) -- `TAIWAN_PASS` → 台湾通行证 -- `MILITARY_ID` → 军官证 (CRUD 支持, OCR 不支持) -- `OTHER` → 其他 (CRUD 支持, OCR 不支持) - -## 接口变化 - -### 1. CRUD: `/mp/user/traveler` (列表/详情/新增/修改/删除/设默认) - -**响应新增字段** (无侵入增量): - -| 字段 | 类型 | 说明 | -|------|------|------| -| `idCardTypeLabel` | String | 证件类型中文标签 (如 "身份证" / "护照" / "港澳通行证") | - -**入参校验加强**: -- `POST /mp/user/traveler` / `PUT /mp/user/traveler/{id}` 的 `idCardType` 字段: - - 必须是字典 6 值之一 (ID_CARD/PASSPORT/HK_MACAU_PASS/TAIWAN_PASS/MILITARY_ID/OTHER) - - 不命中返 `code=230203`, `message=证件类型无效` (`TRAVELER_ID_CARD_TYPE_INVALID`) - - **null 或空字符串兜底为 `ID_CARD`** (DB 列默认值, 不直接 reject 防破坏存量小程序版本) - -### 2. OCR: `POST /mp/traveler/ocr` - -**入参白名单收紧**: -- `idCardType` 必须是 4 值之一: `ID_CARD` / `PASSPORT` / `HK_MACAU_PASS` / `TAIWAN_PASS` -- 传 `MILITARY_ID` 或 `OTHER` 直接返 `TRAVELER_OCR_CARD_TYPE_UNSUPPORTED` (军官证/其他暂不支持 OCR 识别, 需手动录入) -- 之前任何非空值都进入 switch 分流, 现在入口直接拒不支持类型 - -**响应新增字段**: - -| 字段 | 类型 | 说明 | -|------|------|------| -| `idCardTypeLabel` | String | 证件类型中文标签 | - -## 历史 BUG 修正 (顺手) - -后端 `IdCardType` 枚举之前误写为 `HK_MACAO_PASS` (字母 O), 与字典 + DB 列 COMMENT 的 `HK_MACAU_PASS` (字母 U) 不一致, 任何 `IdCardType.of("HK_MACAU_PASS")` 历史会抛 IllegalArgumentException. 本 PR 统一为 `HK_MACAU_PASS`. - -**前端注意**: 如果代码里有硬编码 `HK_MACAO_PASS` 字面量, 必须改成 `HK_MACAU_PASS`. 推荐前端今后用后端下发的 `idCardTypeLabel` 直接显示, 不再硬编码 value→中文 map. - -## 前端建议改造 - -### 立即生效 (无需改动) -- 列表/详情页直接读 `idCardTypeLabel` 显示中文 -- OCR 结果页直接读 `idCardTypeLabel` 显示 - -### 推荐清理 -- 删除前端硬编码的 `idCardType` value → 中文 map -- 把 `HK_MACAO_PASS` 字面量全改为 `HK_MACAU_PASS` (字母 O→U) -- 表单证件类型下拉直接走 `/admin/dict/data?dictType=id_card_type` 拉取 - -## 兼容性 - -- mp Controller 返 Map 透传不动, `idCardTypeLabel` 通过 transient 字段自动序列化下发, 老版本前端不读这个字段也无影响 -- DB 数据干净: 测试服 traveler 51 条 / order_traveler 47 条 / traveler_ocr_log 13 条, 全部 6 字典合法值, **0 条 `HK_MACAO_PASS` 旧拼写** -- null/空入参兜底 ID_CARD, 老版本小程序如果发空字段也不破坏 - -## 验证 (测试服, 部署后) - -``` -GET /mp/user/traveler // 列表 response.list[].idCardTypeLabel 含中文 -GET /mp/user/traveler/{id} // 详情 idCardTypeLabel 含中文 -POST /mp/traveler/ocr (idCardType=MILITARY_ID) // 返 TRAVELER_OCR_CARD_TYPE_UNSUPPORTED -POST /mp/traveler/ocr (idCardType=ID_CARD) // response 含 idCardTypeLabel="身份证" -``` diff --git a/changelogs/2026-04/27_fix_admin-banner_link-type-label-field.md b/changelogs/2026-04/27_fix_admin-banner_link-type-label-field.md deleted file mode 100644 index fb0bb93..0000000 --- a/changelogs/2026-04/27_fix_admin-banner_link-type-label-field.md +++ /dev/null @@ -1,51 +0,0 @@ -# admin 轮播图列表新增 linkTypeLabel 字段（链接类型中文） - -**日期**: 2026-04-27 -**PR**: #1486 (Closes #1480) -**影响端**: 管理后台 admin - -## 行为变化 - -`BannerVO` 在响应里新增字段 `linkTypeLabel`（String），由后端从字典 `banner_link_type` 直接翻译好回填。 - -涉及接口： -- `GET /admin/banner` 列表 -- `GET /admin/banner/{id}` 详情 -- `POST /admin/banner` 创建（响应） -- `PUT /admin/banner/{id}` 更新（响应） - -## 字段映射 - -| linkType | linkTypeLabel | -|----------|---------------| -| PRODUCT | 产品详情 | -| ARTICLE | 文章详情 | -| URL | 外部链接 | -| MINI_PAGE | 小程序页面 | -| NONE | 无跳转 | -| **PRODUCT_LINE** | **产品线**（2026-04-18 新增字典值，本次修复重点） | -| 字典里没有的值 | `null`（兜底，不抛异常） | - -## 为什么改这个 - -之前 `BannerVO` 只回 `linkType` 裸 value，前端依赖 `/admin/dict/all` 拿到的字典 store 自行 lookup 翻译。`PRODUCT_LINE` 是 2026-04-18 新增的字典值，前端 store 是登录时拉的快照、没拿到新值，所以列表里这条 banner 的「链接类型」列显示裸 `PRODUCT_LINE` 而不是「产品线」。 - -后端兜底翻译，与项目其他 `*Label` 字段（statusLabel / typeLabel 等）规范一致，前端不必再依赖字典 store 的新鲜度。 - -## 验收实证（测试服 2026-04-27 部署后） - -``` -GET /admin/banner?page=1&pageSize=20 -linkType linkTypeLabel title -PRODUCT 产品详情 '2026 亲子游学营' -PRODUCT_LINE 产品线 '额吉的故乡' ← bug fix 核心 -``` - -## 前端建议 - -**短期**：直接用 `linkTypeLabel` 字段渲染中文，不必再依赖字典 store lookup。 -**保留兼容**：仍保留 `linkType` 字段（裸 value），用于编辑表单的下拉框 v-model 等场景。 - -## mp 端 / C 端 - -mp 端 `BannerVO` 同样会带这个字段（共用 VO），但前端目前不读，无影响。如有需要可直接使用。 diff --git a/changelogs/2026-04/27_fix_admin-cost-item_status-endpoint-404.md b/changelogs/2026-04/27_fix_admin-cost-item_status-endpoint-404.md deleted file mode 100644 index 3e61882..0000000 --- a/changelogs/2026-04/27_fix_admin-cost-item_status-endpoint-404.md +++ /dev/null @@ -1,85 +0,0 @@ -# fix: 额外成本状态开关 404 已修复 - -**日期**: 2026-04-27 -**PR**: #1479 (Closes #1477) -**类型**: BUG 修复 — **前端零改动**, 自动生效 -**影响端**: 管理后台 (admin) — 额外成本管理页 - ---- - -## 修复内容 - -### 之前的问题 - -蒋雨莲 (橙子) SUPER_ADMIN 在「额外成本」管理页点**状态开关**, 顶部弹红色 toast: - -``` -接口不存在: PUT /admin/cost/item/{id}/status -``` - -(其他 9 个资源模块 — 景区/酒店/车辆/餐厅/物资/服务人员/活动/服务项/客房 — 状态开关都正常, **只有额外成本(cost-item)报错**。) - -### 根因 - -后端 `CostItemController` **历史遗留漏写** `PUT /admin/cost/item/{id}/status` 端点。前端 `useStatusApproval` hook 双轨设计 (超管直更 / 非超管走审批) 中, 9/10 模块的超管端点都已实现, 唯独 cost 漏掉。 - -### 修复 - -后端补齐 `PUT /admin/cost/item/{id}/status`: - -``` -PUT /admin/cost/item/{costId}/status -Body: {"status": 0 | 1} -Response: {"code": 200, "message": "成功", "data": null} -``` - -校验: -- 必须 SUPER_ADMIN 身份, 否则 400 (前端 useStatusApproval 已经在做角色判断, 一般触不到这个错) -- status 必须 0 或 1, 否则 400 (`@NotNull`/`@Min(0)`/`@Max(1)`) -- 费用项不存在 → 404 「费用项不存在」 -- 费用项审批中 → 400 「审批中, 不可修改状态」 (沿用其他模块审批拦截) - -## 前端动作 - -### 必须 ✅ - -**无**。`hl-ui` 中 `extraCharge.js:58 updateCostItemStatus` 调用方式不变, 后端补齐端点后自动工作, 无需改前端代码。 - -### 验收 ✅ - -在测试服管理后台: -1. 用 SUPER_ADMIN 账号登录 -2. 进「额外成本」管理页 -3. 点任意一行的状态开关 -4. 应**立即切换** (修前会弹「接口不存在」红 toast) - -测试服已部署完成 (deploy_id `b747855d`, 2026-04-27 16:40)。 - -## 参考路径 - -| 端 | 文件 | 行 | -|---|---|---| -| 前端 API | `hl-ui/src/api/extraCharge.js` | 58 `updateCostItemStatus` | -| 前端管理页 | `hl-ui/src/views/resource/extra-charge/index.vue` | 153 状态开关 onChange | -| 前端 hook | `hl-ui/src/composables/useStatusApproval.js` | 50 双轨判断 | -| 后端 (新) | `hl-resource-service/.../cost/controller/CostItemController.java` | PUT /item/{id}/status | - -## 兄弟模块完整清单(对照) - -| 模块 | path | 后端实现 | -|---|---|---| -| **cost-item** | PUT /admin/cost/item/{id}/status | ✅ 本 PR 新加 | -| scenic | PUT /admin/scenic/spot/{id}/status | ✅ 早已有 | -| hotel | PUT /admin/hotel/item/{id}/status | ✅ 早已有 | -| hotel/RoomType | PUT /admin/hotel/room-type/{id}/status | ✅ 早已有 | -| vehicle | PUT /admin/vehicle/model/{id}/status | ✅ 早已有 | -| restaurant | PUT /admin/restaurant/item/{id}/status | ✅ 早已有 | -| supplies | PUT /admin/supplies/item/{id}/status | ✅ 早已有 | -| staff | PUT /admin/staff/{id}/status | ✅ 早已有 | -| activity | PUT /admin/activity/item/{id}/status | ✅ 早已有 | -| serviceItem | PUT /admin/service/item/{id}/status | ✅ 早已有 | - -## 关联 - -- 反馈人: 蒋雨莲 (橙子) 2026-04-27 -- 后端 changelog: `hl-backend-changelog/changelogs/2026-04/2026-04-27_resource_cost-item-status-endpoint.md` diff --git a/changelogs/2026-04/27_fix_admin-insurance_overseas-filter.md b/changelogs/2026-04/27_fix_admin-insurance_overseas-filter.md deleted file mode 100644 index 589faa9..0000000 --- a/changelogs/2026-04/27_fix_admin-insurance_overseas-filter.md +++ /dev/null @@ -1,47 +0,0 @@ -# admin 保险产品列表 isOverseas 筛选生效（境外/境内分类不再失效） - -**日期**: 2026-04-27 -**PR**: #1491 (Closes #1490) -**影响端**: 管理后台 admin - -## 行为变化 - -`GET /admin/insurance/products?isOverseas=true|false` 现在真的会按 `isOverseas` 字段过滤，之前接口参数声明了但后端**完全忽略**，导致前端任何选择都返回全量。 - -接口签名无变化，只是「之前空跑、现在生效」。 - -## 涉及接口 - -- `GET /admin/insurance/products?page&pageSize&isOverseas` — 查询参数 `isOverseas` 现在生效 - -## 验收实证（测试服 2026-04-27 部署后） - -``` -# 全量 -GET /admin/insurance/products?page=1&pageSize=20 -→ 境内 + 境外都返回 - -# 仅境外 -GET /admin/insurance/products?page=1&pageSize=20&isOverseas=true -→ 仅 isOverseas=true 的产品 - -# 仅境内 -GET /admin/insurance/products?page=1&pageSize=20&isOverseas=false -→ 仅 isOverseas=false 的产品 -``` - -## 为什么改这个 - -蒋雨莲（运营）反馈：保险产品列表的「产品类型」下拉切到「境外」后列表无变化、依旧境内境外都有。 - -排查发现 `AdminInsuranceController.listProducts()` 接收了 `@RequestParam Boolean isOverseas` 但调 Service 时根本没传下去，Service / Mapper 链路全是无参的 —— 经典「哑参数 BUG」。 - -后端补全参数透传，并在 Mapper 用 `eqIfPresent`（null 不拼条件，保持向后兼容）。 - -## 前端建议 - -**前端无需改动**。保险产品列表页的「产品类型」筛选 / `searchForm.isOverseas` / `/api/insurance.js` 都已经在传 `isOverseas`，本次后端补完链路后下拉切换会立即看到列表条数变化。 - -## mp 端 / C 端 - -不影响（保险产品列表是后台管理功能，不暴露给小程序）。 diff --git a/changelogs/2026-04/27_fix_admin-product-line_filter-by-product-type.md b/changelogs/2026-04/27_fix_admin-product-line_filter-by-product-type.md deleted file mode 100644 index 3439241..0000000 --- a/changelogs/2026-04/27_fix_admin-product-line_filter-by-product-type.md +++ /dev/null @@ -1,48 +0,0 @@ -# 主题列表(产品线)按主题类型筛选 - -**日期**: 2026-04-27 -**PR**: #1457 (Closes #1456) -**影响端**: 管理端 admin - -## 背景 - -管理后台「前端配置 → 主题列表」(项目术语「主题」=「产品线」, 接口 `/admin/product/line/list`) 筛选「主题类型 = 小蒙马」点搜索, 28 条返回不变, 后端忽略 `productType` 参数。 - -## 根因 - -后端双重缺失： -1. `ProductLinePageReqVO` 未声明 `productType` 字段, Spring 自动绑定丢弃 query -2. `ProductLineMapper` 的 `selectPage` + `selectPageWithCount` 也没消费 `productType` 字段做 WHERE 过滤 - -## 接口变化 - -`GET /admin/product/line/list` query 参数**新增 1 个可选参数**: - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `productType` | String | 否 | 产品类型过滤 (字典 `product_type`: `CORE`=核心 / `GROUP`=小蒙马 / `CUSTOM`=定制) | - -不传时行为与原来一致（返回所有产品线）。 - -## 前端改动 - -筛选下拉「主题类型」选「小蒙马」时，发出 `?productType=GROUP`，本 PR 后端补齐过滤后**前端无需改动**自动生效。 - -## 验证 (测试服) - -修复前 curl 实证: -``` -?productType=GROUP total=28 (BUG, 期望 3) -?productType=CORE total=28 (BUG, 期望 5) -DB 实际分布: CORE=5 / GROUP=3 / CUSTOM=8 / NULL=12 -``` - -修复后期望: `productType=GROUP` 返 3 条, `=CORE` 返 5 条, `=CUSTOM` 返 8 条。 - -## 数据权限边界 - -`productType` 过滤放在 `applyDataScopeFilter` **之前**, 复合 SQL 形如 `productType=? AND (datascope-OR-block)`, 超管 short-circuit, 普通管理员选 GROUP 在 datascope 收紧后仍命中 — 数据权限边界完整保留。 - -## C 端 - -`/internal` 同名筛选 `selectMpPage` 早已支持 productType 过滤, admin 漏掉, 修复后两端能力一致。 diff --git a/changelogs/2026-04/27_fix_admin-product_deposit-vs-price-validation.md b/changelogs/2026-04/27_fix_admin-product_deposit-vs-price-validation.md deleted file mode 100644 index 6996f8e..0000000 --- a/changelogs/2026-04/27_fix_admin-product_deposit-vs-price-validation.md +++ /dev/null @@ -1,65 +0,0 @@ -# 修复:固定订金模式产品售价必须大于订金(双向校验) - -**类型**: 后端 BUG 修复 + 校验加严 -**关联**: 工单 #1497 / PR #1501 -**日期**: 2026-04-27 -**影响范围**: 管理端产品基础信息保存 + 价格日历批量设置 + 班期保存 - ---- - -## 现象 - -后台「支付类型=订金+尾款」+「订金设置=固定金额(元/人)」组合下,保存价格时未校验售价 > 订金。极端 case: 用户设定金 5000 元/人但成人价配 1000,定金比总价还高,业务彻底崩。 - -## 后端改动 - -### 1. 正向校验(保存价格时) - -**接口 1: 价格日历批量设置 `POST /admin/product/item/{id}/price-calendar/batch`** (CORE/CUSTOM) - -- 触发条件: 产品 paymentType=DEPOSIT 且 depositAmount > 0 -- 校验: adultSellPrice > depositAmount **AND** childSellPrice > depositAmount -- 不通过会返: - - `code=410105`: 成人售价（{0}元）必须大于产品订金（{1}元/人），请调整定价或修改基础信息中的订金 - - `code=410106`: 儿童售价（{0}元）必须大于产品订金（{1}元/人），请调整定价或修改基础信息中的订金 - -**接口 2: 班期保存 `POST /admin/product/item/{id}/schedule`** (GROUP) 与 **班期批量创建** - -- 同样规则套用 adultPrice / childPrice -- 错误码同上 - -### 2. 反向校验(保存基础信息时) - -**接口: Step1 基础信息保存 `POST /admin/product/item/basic`** - -- 触发条件: 用户调高 depositAmount(固定金额模式) -- 校验: 反查产品现有 product_price_calendar + group_tour_batch,任一售价 ≤ 新订金即抛错 -- 不通过会返: - - `code=410107`: 订金（{0}元/人）不能高于现有价格（{1} {2}的售价{3}元），请先调整定价 - - 占位符 {1} 是日期(如 `2026-05-17`)或班期号(如 `班期Q26050101`),{2} 是「成人」或「儿童」 - -### 3. 跳过项(不校验) - -- **比例订金模式** (`depositRatio` 有值, `depositAmount` 为空): 不校验,比例 < 100% 数学上必然 < 总价 -- **全款模式** (`paymentType=FULL`): 不校验 -- **幼童价 / 小童优惠**: 不校验,幼童价 0 是合法免费语义 - -## 前端建议 - -1. **不需要改逻辑**,后端已加硬校验 -2. UI 体验优化(可选): 在「订金设置」输入框旁加提示"订金须低于最低成人/儿童售价" -3. 接到 `code=410105/410106` 时建议提示用户「请调整价格或回基础信息修改订金」 -4. 接到 `code=410107` 时建议解析消息中的日期/班期号高亮冲突项 - -## 测试建议 - -- [x] 管理端 CORE 产品基础信息设固定订金 100,价格日历配成人价 50 → 应报错 `410105` -- [x] 同上配成人价 200 → 应通过 -- [x] 管理端 GROUP 产品班期保存 adultPrice=50,固定订金 100 → 应报错 `410105` -- [x] 已配价格日历(成人价 100),回基础信息把订金调到 200 → 应报错 `410107` 含冲突日期 -- [x] 比例订金 30% 配成人价 50 → 应通过(不受影响) -- [x] 全款模式 → 应通过(不受影响) - -## 后端单测 - -ProductPricingServiceTest 新增 8 用例 + ProductBasicServiceTest 新增 5 用例,全量 1000 用例通过。 diff --git a/changelogs/2026-04/27_fix_admin-supplies_batch-delete-body-shape.md b/changelogs/2026-04/27_fix_admin-supplies_batch-delete-body-shape.md deleted file mode 100644 index 9ecc87c..0000000 --- a/changelogs/2026-04/27_fix_admin-supplies_batch-delete-body-shape.md +++ /dev/null @@ -1,65 +0,0 @@ -# 备品(supplies)批量删除前端 body 结构修复 - -**日期**: 2026-04-27 -**PR**: 后端 0 改动 (本条仅前端修复指引) -**影响端**: 管理端 admin (`hl-ui/src/api/spare.js`) - -## 背景 - -反馈人 蒋雨莲(橙子): admin 后台「物资管理 → 备品管理」列表,勾选 ≥1 条点「批量删除」无效,后端返回 `code:400 "suppliesIds: 备品ID列表不能为空"`。 - -## 根因 - -`hl-ui/src/api/spare.js:69` 调用 `http.delete` 时多包了一层 `{ data: ... }`: - -```js -// 现状(BUG) -export function deleteSpareBatch(suppliesIds) { - return http.delete('/supplies/items/batch', { data: { suppliesIds } }) -} -``` - -`utils/request.js:582` 的 `http.delete(url, data, config)` 第二参数 `data` **直接作为请求体 body**(项目封装,与 axios 原生 `axios.delete(url, { data: payload })` 写法不同)。多包一层后实际 HTTP body 是: - -```json -{"data":{"suppliesIds":["..."]}} -``` - -后端 `BatchDeleteRequest` 期望: - -```json -{"suppliesIds":["..."]} -``` - -Jackson 反序列化把 `data` 字段当 unknown property 忽略(`FAIL_ON_UNKNOWN_PROPERTIES=false`),`suppliesIds` 字段为 null,`@NotEmpty` 校验失败 → 后端 `code:400`。 - -## 前端修复 - -对照 `hl-ui/src/api/hotel.js:56` 写法正确: - -```js -export function deleteHotelBatch(hotelIds) { - return http.delete('/hotel/items/batch', { hotelIds }) // 直接传 payload -} -``` - -把 `spare.js:69` 改为: - -```js -export function deleteSpareBatch(suppliesIds) { - return http.delete('/supplies/items/batch', { suppliesIds }) -} -``` - -## 后端验证 - -后端代码经核查 100% 无 BUG, 0 改动。已用真实 admin token curl 测试服 `/admin/supplies/items/batch` 双向验证: - -| body | 响应 | -| --- | --- | -| `{"data":{"suppliesIds":["x"]}}` (前端字面值) | `code:400 "suppliesIds: 备品ID列表不能为空"` | -| `{"suppliesIds":["x"]}` (DTO 期望) | `code:200 "成功"` | - -## 同类风险扫描建议 - -全仓 grep `http\.delete\([^)]*\{\s*data:` 一次性扫出还有哪些前端模块踩同一坑。已确认 `hotel.js` `extraService.js` 等其他批删 API 写法正确, 当前已知仅 `spare.js` 一处。 diff --git a/changelogs/2026-04/27_fix_admin-wxapp-share_endpoints-404.md b/changelogs/2026-04/27_fix_admin-wxapp-share_endpoints-404.md deleted file mode 100644 index ac354e9..0000000 --- a/changelogs/2026-04/27_fix_admin-wxapp-share_endpoints-404.md +++ /dev/null @@ -1,100 +0,0 @@ -# fix: 分享到小程序 URL Link / URL Scheme 404 已修复 - -**日期**: 2026-04-27 -**PR**: #1488 (Closes #1481) -**类型**: BUG 修复 — **前端零改动**, 自动生效 -**影响端**: 管理后台 (admin) — 产品列表「分享到小程序」对话框 - ---- - -## 修复内容 - -### 之前的问题 - -蒋雨莲 (橙子) 在产品列表点「分享到小程序」 → 弹对话框 → 点「URL Link 生成」或「URL Scheme 生成」按钮: - -- 顶部弹红色 toast: **请求的资源不存在**(HTTP 404) -- DevTools Network 面板: 两次 `url-link` 请求 status=404 - -### 根因 - -后端**完全没实现 admin 端点**, 前端 `MiniappShareModal.vue` 已上线但从未与后端联调。与 #1477 cost-item 同款「前端先发后端漏跟」模式。 - -### 修复 - -后端补齐 2 个端点 + hl-gateway 加路由: - -``` -POST /admin/wxapp/share/url-link -POST /admin/wxapp/share/url-scheme - -Request body (两端点一致): -{ - "path": "pages/product/detail/detail", // 必填 - "query": "id=20457...", // 选填 - "envVersion": "trial" | "release", // 选填, 默认 release - "expireDays": 30 // 选填, 默认 30 天 -} - -Response: -{ - "code": 200, - "message": "成功", - "data": { - "link": "https://wxaurl.cn/..." | "weixin://...", // URL Link 是 https, URL Scheme 是 weixin:// - "expireTime": 1735689600 // 过期 Unix 时间戳 - } -} -``` - -### 字段统一 - -URL Link 和 URL Scheme **响应字段都叫 `link`**(微信原始 `urlLink`/`openlink` 已在后端归一化), 前端 `MiniappShareModal.vue:223,242` 取值 `res.link || res` 完全兼容。 - -## 前端动作 - -### 必须 ✅ - -**无**。`hl-ui/src/api/wxapp.js` 中 `generateUrlLink` / `generateUrlScheme` 调用方式不变, 后端补齐端点 + 网关路由后自动工作。 - -### 验收 ✅ - -测试服管理后台: - -1. 用 SUPER_ADMIN 登录(或任意 admin token) -2. 进「产品线管理」→ 任一产品列表 -3. 点产品上的「分享到小程序」按钮 -4. 在弹窗里点「URL Link 生成」 → 应填充 `https://wxaurl.cn/...` 类链接 -5. 点「URL Scheme 生成」 → 应填充 `weixin://...` 类链接 - -测试服已部署 hl-user-service + hl-gateway 完成 (2026-04-27 16:51)。 - -### ⚠️ 测试服可能仍报 230506 (errcode=40001) - -后端代码 + 路由 + 调用链已就绪, 但**测试服微信 appid 鉴权**可能未配齐(测试小程序 IP 白名单 / 接口权限 / appid-secret 不匹配)。如测试服仍报错: - -``` -{"code":230506, "message":"生成分享链接失败(错误码:40,001)"} -``` - -**这不是代码 bug**, 是微信开放平台账号配置侧。运维需确认: -1. nacos `wechat.miniapp.appid` / `secret` 与测试小程序后台一致 -2. 测试服出口 IP `116.117.149.79` 在小程序后台 IP 白名单 -3. 测试小程序已开通 `generate_urllink` + `generatescheme` 接口权限 - -正式服 appid/secret/IP 白名单配置正确即可工作。 - -## 参考路径 - -| 端 | 文件 | 行 | -|---|---|---| -| 前端 API | `hl-ui/src/api/wxapp.js` | 3-18 | -| 前端组件 | `hl-ui/src/views/product/list/components/MiniappShareModal.vue` | 213, 232 | -| 后端 (新) | `hl-user-service/.../controller/AdminWxappShareController.java` | `@RequestMapping("/admin/wxapp/share")` | -| 后端 wxa 客户端 | `hl-user-service/.../service/WechatMiniAppClient.java` | generateUrlLink + generateUrlScheme | -| 网关路由 (新) | `hl-gateway/src/main/resources/application.yml` | `Path=/admin/wxapp/**` → `lb://hl-user-service` | - -## 关联 - -- 反馈人: 蒋雨莲 (橙子) 2026-04-27 -- 后端 changelog: `hl-backend-changelog/changelogs/2026-04/2026-04-27_user_admin-wxapp-share-endpoints.md` diff --git a/changelogs/2026-04/27_fix_insurance-order-list_ext-fields.md b/changelogs/2026-04/27_fix_insurance-order-list_ext-fields.md deleted file mode 100644 index 6297b88..0000000 --- a/changelogs/2026-04/27_fix_insurance-order-list_ext-fields.md +++ /dev/null @@ -1,44 +0,0 @@ -# 保险订单列表补保游网订单号 + 保单号字段 - -**日期**: 2026-04-27 -**PR**: #1455 (Closes #1453) -**影响端**: 管理端 admin - -## 背景 - -管理后台 `/insurance/orders` 列表页「保游网订单号」+「保单号」两列展示为空，DB 实际有值（`ext_order_no` + `ext_policy_no`）。 - -根因：列表 VO `InsuranceOrderVO` 缺 `extOrderNo` 字段，且把 `ext_policy_no` 装配到了 `policyNo`（与详情 `InsuranceOrderDetailVO.extPolicyNo` 命名不一致）。 - -## 接口变化 - -`GET /admin/insurance/orders` 列表项 response **新增 2 个字段**，**保留旧字段**： - -| 字段 | 类型 | 说明 | 状态 | -|------|------|------|------| -| `extOrderNo` | String | 保游网订单号 (如 `BX2026042416212230000164`) | **新增** | -| `extPolicyNo` | String | 保单号 / 保游网保单号 (如 `11209006600506922149`) | **新增** | -| `policyNo` | String | 与 `extPolicyNo` 同值 | **保留兼容**, 后续版本删除 | - -## 前端改动 - -列表列定义已使用 `extOrderNo` + `extPolicyNo`，本 PR 后端补齐字段后**前端无需改动**，自动生效。 - -后续等本期上线稳定后，后端会移除 `policyNo` 字段，前端不需要做任何动作（前端已不读 `policyNo`）。 - -## 验证 - -DB 实证： -```sql -SELECT insurance_order_id, ext_order_no, ext_policy_no, status, create_time -FROM insurance_order ORDER BY create_time DESC LIMIT 3; - -2047591721386098690 BX2026042416212230000164 11209006600506922149 INSURED 2026-04-24 16:21:32 -2047583238506844161 BX2026042415474050000153 11209006600506922106 CANCELLED 2026-04-24 15:48:00 -2046992253949591554 BX2026042300392020000007 11209006600506912961 INSURED 2026-04-23 00:39:35 -``` - -API response 经此 PR 后 `extOrderNo` + `extPolicyNo` 同步下发。 - -## 详情接口 -`GET /admin/insurance/orders/{id}` 详情接口字段不变（一直就是 `extOrderNo` + `extPolicyNo`），本 PR 仅对齐列表接口。 diff --git a/changelogs/2026-04/27_fix_internal-batch-quote_toddler-infant-fields.md b/changelogs/2026-04/27_fix_internal-batch-quote_toddler-infant-fields.md deleted file mode 100644 index 9ef2c55..0000000 --- a/changelogs/2026-04/27_fix_internal-batch-quote_toddler-infant-fields.md +++ /dev/null @@ -1,87 +0,0 @@ -# 修复:班期内部报价补 toddler/infant 字段(订单总价含小童金额) - -**类型**: 后端 BUG 修复 -**关联**: 工单 #1498 / PR #1499 -**日期**: 2026-04-27 -**影响范围**: 小程序 GROUP(小蒙马) 订单创建后的订单详情展示 + 总价 - ---- - -## 现象 - -后端同事反馈: order-v2 调 product-v2 的班期报价接口时返回里没有小童单价/数量/小计,GROUP 订单(小蒙马)创建带小童时算价漏掉小童总价。同时入参也缺 toddlerCount,订单方根本传不过去。 - -## 修复后的行为 - -### 1. GROUP 订单总价 (`totalPrice`) - -**接口**: `POST /mp/order/create` (GROUP 类型) - -- 修复前: 带 `youngChildCount=1` 创建 GROUP 订单,totalPrice 只算成人 + 儿童,小童金额漏掉 -- 修复后: totalPrice 正确包含小童金额(由班期 toddlerDiscount 决定) - -### 2. 订单详情价格明细 (`priceBreakdown.items`) - -**接口**: `GET /mp/order/detail/{id}` 与 `GET /admin/order/detail/{id}` - -- 修复前: items 里小童单价/小计硬写 0 元(展示成"小童 0元×N=0元") -- 修复后: 小童行展示真实单价(=班期成人价×儿童折扣) 和 真实小计 - -### 3. 小童单价计算口径 - -`toddlerPrice = max(childPrice + toddlerDiscount, 0)` - -与 `ProductPricingService.calculateQuote` 同口径。toddlerDiscount 默认负数(优惠),null 时小童价=儿童价。 - -## 前端建议 - -**不需要改任何代码**。本次是后端纯修复,前端只需要观察: -1. 创建带 youngChildCount 的 GROUP 订单后,`totalPrice` 应正确 = 成人+儿童+小童(含 toddlerDiscount) -2. 订单详情里"小童"行不再永远显示 0,有班期 toddlerDiscount 时显示实际折扣价 - -## 跨服务接口变更说明 (内部, 前端无感知) - -### Feign Client 入参签名 (新增 2 个,默认 0) - -``` -GET /internal/product/batch/{batchId}/quote - ?adultCount=2 &childCount=1 &toddlerCount=0 &infantCount=0 &roomCount=1 - ↑ 新增 ↑ 新增 -``` - -### 返回 VO 新增字段 - -```json -{ - "adultPrice": 5999, "childPrice": 4299, - "toddlerPrice": 3299, // 新增 - "infantPrice": 0, // 新增 - "adultCount": 2, "childCount": 1, - "toddlerCount": 1, // 新增 - "infantCount": 0, // 新增 - "roomCount": 1, - "adultTotal": 11998, "childTotal": 4299, - "toddlerTotal": 3299, // 新增 - "infantTotal": 0, // 新增 - "grandTotal": 19596 -} -``` - -### 向后兼容 - -- 入参新字段都有默认 0,旧调用方不传不影响 -- 返回新字段对旧消费者透明(Jackson 忽略未知字段) - -## 测试建议 - -- [ ] 小程序选有 toddlerDiscount 的班期(例如 batch_id=2042826084914950145 有 toddlerDiscount=-1000),youngChildCount=1 下单 - - 期望: `totalPrice` 包含小童金额 (childPrice + toddlerDiscount)×1 - - 期望: 订单详情价格明细里小童行不为 0 -- [ ] 不带小童(youngChildCount=0)下单 → 行为与改动前一致 - -## 后端测试 - -- 单测: GroupTourBatchServiceMpTest 新增 4 用例(toddlerDiscount=null/截断为0/向后兼容/正常)+ GroupOrderStrategyTest 8 用例适配新签名,全过 -- 本地 API: product-v2 9083 直接 curl 经 X-Internal-Token 验证两路径 - - 完整传: toddlerPrice=3299 (=4299-1000) grandTotal=19596 ✓ - - 向后兼容: toddler/infant=0 grandTotal=16297 与改动前一致 ✓ diff --git a/changelogs/2026-04/27_fix_mp-group-list_add-category.md b/changelogs/2026-04/27_fix_mp-group-list_add-category.md deleted file mode 100644 index 82b3178..0000000 --- a/changelogs/2026-04/27_fix_mp-group-list_add-category.md +++ /dev/null @@ -1,40 +0,0 @@ -# /mp/product/group/list 返回补 category 字段 - -**日期**: 2026-04-27 -**PR**: #1464 (Closes #1463) -**影响端**: 小程序 mp - -## 接口变化 - -`GET /mp/product/group/list` 返回项**新增 `category` 字段**: - -| 字段 | 类型 | 说明 | -|---|---|---| -| `category` | String | 产品分类（字典 `product_category`: `family`/`honeymoon`/`photography`/`experience`/`driving`） | - -## 修复内容 - -之前 CORE 产品走 `/mp/product-line/{lineId}/products` 用 `BeanUtil.toBean` 自动 copy 全字段，正确下发 `category`；GROUP 产品走专用 `/mp/product/group/list`，后端用手写 `setXxx` 装配 9 个字段，**漏 setCategory**，且 v2 internal + mp BFF 双 VO 也均无该字段定义。 - -修复后 GROUP list 与 CORE list 在 `category` 字段上行为一致。 - -## 验收实证 (测试服 2026-04-27) - -``` -GET /mp/product/group/list -[ - { "productId":"2047224617403117570", "name":"小秘密", "category":"family", "tags":["亲子","研学","露营"], ... }, - { "productId":"2044306857534636034", "name":"冻干粉发短信给", "category":"family", "tags":["亲子","研学","露营"], ... } -] -``` - -DB raw `category` 与 response 一致。 - -## 前端建议 - -- 「小蒙马专题页」分类筛选下拉可读 `category` 字段做前端筛选 -- `tags` 字段一直正确（之前用户感受是"标签也不对"实际是误会，本 PR 不动 tags） - -## 缓存 - -`@MpCache prefix=product:group:list:* TTL 10min` 后端缓存。部署后等 10 分钟自然过期，或后端手动 `redis-cli DEL` 立即生效（已处理）。 diff --git a/changelogs/2026-04/27_fix_mp-home_offline-line-card-filter.md b/changelogs/2026-04/27_fix_mp-home_offline-line-card-filter.md deleted file mode 100644 index 9134dad..0000000 --- a/changelogs/2026-04/27_fix_mp-home_offline-line-card-filter.md +++ /dev/null @@ -1,32 +0,0 @@ -# mp 首页 productLines 过滤产品全下架的主题 - -**日期**: 2026-04-27 -**PR**: #1462 (Closes #1461) -**影响端**: 小程序 mp - -## 行为变化 - -`GET /mp/home` 返回的 `data.productLines` 字段过滤逻辑增强： - -- **之前**: 只校验 `product_line.status == ACTIVE` 即返回主题卡片 -- **现在**: 还要求该产品线下至少有 1 个 `status == PUBLISHED` 且未软删的产品 - -也就是说：产品线下产品全部下架/草稿/软删后，**主题卡片不再展示在首页**。点进空主题再看到「该主题下产品列表空」的情况不会再发生。 - -## 验收实证 (测试服 2026-04-27) - -| lineId | name | published_cnt | response 中是否出现 | -|---|---|---|---| -| 2045765580526387201 | 2026小蒙马 | 0 | ❌ 不出现（被过滤）| -| 2044248925572919297 | 阿斯蒂芬撒点 | 1 | ✅ 出现 | -| 2047223431551741953 | 123 | 1 | ✅ 出现 | - -## 前端注意 - -- 列表页/首页直接消费 `data.productLines`，无需改前端 -- 如果前端缓存过 lines 列表（含 0 PUBLISHED 的），需要重新拉 - -## 后台行为 - -- admin 后台「产品线列表」`/admin/product/line/list` **不受影响**（管理端要看到全部主题包括 0 产品的） -- 仅 mp 端展示层加过滤 diff --git a/changelogs/2026-04/27_fix_mp-product-line-list_add-product-type-filter.md b/changelogs/2026-04/27_fix_mp-product-line-list_add-product-type-filter.md deleted file mode 100644 index 0707359..0000000 --- a/changelogs/2026-04/27_fix_mp-product-line-list_add-product-type-filter.md +++ /dev/null @@ -1,60 +0,0 @@ -# mp 产品线列表新增 productType 过滤参数（活参数） - -**日期**: 2026-04-27 -**PR**: #1496 (Closes #1495) -**影响端**: 小程序 mp - -## 行为变化 - -`GET /mp/product-line/list` 新增可选 query 参数 `productType`： - -| 取值 | 返回 | -|---|---| -| 不传（旧行为，向后兼容）| 全部启用主题（CORE+GROUP+CUSTOM）| -| `CORE` | 仅 CORE 类型主题 | -| `GROUP` | 仅 GROUP 类型主题 | -| `CUSTOM` | 仅 CUSTOM 类型主题 | -| 不存在的 value（如 `XYZ`）| 空数组（兜底不报错）| - -可与已有 `season` 参数叠加：`?season=summer&productType=CORE`。 - -## 验收实证（测试服 2026-04-27 部署后） - -``` -GET /mp/product-line/list → count=6 types=['CORE','GROUP'] -GET /mp/product-line/list?productType=CORE → count=5 types=['CORE'] -GET /mp/product-line/list?productType=GROUP → count=1 types=['GROUP'] -GET /mp/product-line/list?productType=XYZ → count=0 -``` - -## ⚠️ 前端必改（活参数，不靠后端兜底） - -字典 `theme_card_link_type` 4 种跳转目标的产品线列表语义已统一： - -| 跳转字典值 | 跳转页路径 | 调用接口要传 | -|---|---|---| -| `SEASON`（季节之旅）| packages/product/season/list | **`?productType=CORE`** | -| `CORE_LIST`（核心产品）| packages/product/core/list | **`?productType=CORE`** | -| `MENGMA`（亲子游学）| packages/product/mengma/list | **`?productType=GROUP`** | -| `PRODUCT`（指定产品）| 直跳详情 | -（不调此接口）| - -**前端要改的页面**： -- 季节之旅 list 页面：query 加 `?productType=CORE` -- 核心产品 list 页面（如有独立路由）：`?productType=CORE` -- 亲子游学 list 页面：`?productType=GROUP` - -不传参数时返回全部类型混合，会显示混乱（用户已反馈过这个 BUG）。 - -## 缓存 key 变化 - -``` -旧：mp:product-lines / mp:product-lines:summer -新：mp:product-lines / mp:product-lines:season=summer / mp:product-lines:type=CORE / mp:product-lines:season=summer:type=CORE -``` - -部署后旧 season 缓存条目自然 TTL（10min）失效，无需手动清。 - -## 后台行为 - -- admin 后台「产品线列表」`/admin/product/line/list` **不受影响** -- 仅 mp 端展示层加过滤 diff --git a/changelogs/2026-04/27_fix_mp-product_group-price-source-branching.md b/changelogs/2026-04/27_fix_mp-product_group-price-source-branching.md deleted file mode 100644 index b3f05c5..0000000 --- a/changelogs/2026-04/27_fix_mp-product_group-price-source-branching.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -date: 2026-04-27 -type: fix -module: mp-product -title: 小蒙马(GROUP)产品价格相关接口按 productType 分叉走班期表 -audience: frontend -breaking: false ---- - -## 背景 - -线上反馈：小蒙马（productType=GROUP）产品详情页底部「立即预订」按钮永久显示「加载中...」无法下单（详情页其他内容正常加载）。 - -## 根因 - -mp 端价格相关接口仅查 `product_price_calendar` 表，但 GROUP 类型产品价格只存在 `group_tour_batch.adult_price`，价格日历表为空 → 接口返回 `available=false` / `startPrice=null` → 前端 loading 不解除或起步价无显示。 - -## 修复范围（5 个 mp 接口 + 1 处装配器） - -| 接口路径 | 修复点 | -|---------|--------| -| `GET /mp/product/{id}/earliest-available-date` | GROUP 产品改走班期表取最早可售日期，`available=true` 才显示 | -| `GET /mp/product/{id}/price-calendar?month=YYYY-MM` | GROUP 产品改用班期数据填充日历；同日多班期取最低 adultPrice + 库存合并 | -| `GET /mp/product/line/{id}/products` | 列表 `startPrice` 字段补 GROUP 班期最低价 | -| `GET /mp/product/line` | 产品线最低价合并日历 + 班期两路 | -| `GET /mp/product/line/{id}` | 产品线详情 `startPrice` 同上 | -| 产品详情接口 `isBooking` 字段 | GROUP 产品按班期表"未来未截止"判定可订状态（之前永远 false） | - -## 前端预期变化 - -**前端不需要改代码**，但需要知道行为变化： - -1. **「立即预订」按钮**：以前小蒙马产品永久 loading，现在能正确显示"可点击/灰显" -2. **价格日历**：以前小蒙马产品月度日历无数据，现在显示班期对应的天 + 价格 -3. **起步价**：以前小蒙马列表页/详情页 startPrice=null，现在显示最低班期价 -4. **可售日期判定逻辑**：GROUP 走班期"未来 + ENROLLING/NEARLY_FULL + 报名未截止"，CORE/CUSTOM 走价格日历"全档位齐全"（行为没变） - -## 字段说明 - -返回 VO 结构 **0 变化**，前端透传即可： - -- `MpEarliestAvailableDateRespVO`: `date / available / daysFromToday`（同 CORE 一致） -- `MpPriceCalendarRespVO.CalendarDay`: `date / adultPrice / childPrice / remainStock / isSelectable`（GROUP 同日多班期合并为一行） -- `MpProductDetailRespVO.startPrice / isBooking`: 同 CORE 字段含义 - -## 验证状态 - -- ✅ 982 单测全绿（含 4 个新增 GROUP 分叉测试） -- ✅ 测试环境部署成功（hl-product-service-v2 双实例 8083+8183） -- ⏳ 测试环境无 GROUP 班期数据，e2e 验证待真有班期的小蒙马产品上线 - -## 关联 - -- 工单: #1485 -- PR: #1489 -- 类似经验: PR #926（GROUP/CORE 价格双源同类型踩过坑） diff --git a/changelogs/2026-04/27_fix_mp-route-map_add-service-node-and-type.md b/changelogs/2026-04/27_fix_mp-route-map_add-service-node-and-type.md deleted file mode 100644 index a24f523..0000000 --- a/changelogs/2026-04/27_fix_mp-route-map_add-service-node-and-type.md +++ /dev/null @@ -1,49 +0,0 @@ -# mp 产品路线图新增 SERVICE 节点定位 + 节点 type 字段 - -**日期**: 2026-04-27 -**PR**: #1502 (Closes #1500) -**影响端**: 小程序 mp - -## 行为变化 - -`GET /mp/product/{productId}/route-map` 响应里： - -### 1. `scenicSpots` 含义扩展 - -之前只包含 SCENIC（景区）+ ACTIVITY（活动）节点，**现在还包含 SERVICE（服务）节点**。字段名保持不变（向后兼容），含义升级为「地图 POI 列表」。 - -### 2. 每个节点新增 `type` 字段 - -`MpRouteScenicVO` 加 `type: String`，取值 `SCENIC` / `ACTIVITY` / `SERVICE`，前端可据此切换图标。 - -```json -{ - "data": { - "title": "...", - "days": [ - { - "dayNumber": 1, - "scenicSpots": [ - { "lng": 87.4, "lat": 48.1, "name": "喀纳斯湖", "coverUrl": "...", "type": "SCENIC" }, - { "lng": 87.5, "lat": 48.2, "name": "草原 BBQ", "coverUrl": "...", "type": "ACTIVITY" }, - { "lng": 87.6, "lat": 48.3, "name": "包车接送服务", "coverUrl": "...", "type": "SERVICE" } - ] - } - ] - } -} -``` - -## 前端建议 - -- **零改动可上线**：现有渲染逻辑不变，SERVICE 节点会自动出现在 `scenicSpots` 列表里 -- **可选优化**：用 `type` 字段切换图标 / 颜色 / 分组，更直观区分「景区 / 活动 / 服务」三类点 - -## 验收实证 - -合并 PR + 部署测试服后，admin 后台手挂 SERVICE 节点的产品 → mp 端 route-map 立即返回（mp service 缓存 deps 已挂 `table:product`，PR #1494 修过，本次零等待）。 - -## 后台行为 - -- admin 端行程编辑 SCENIC/ACTIVITY/SERVICE 等节点配置入口不变 -- 仅 mp 端展示层：扩展白名单 + 加 type 字段 diff --git a/changelogs/2026-04/27_refactor_cr-audit_phase1-batch.md b/changelogs/2026-04/27_refactor_cr-audit_phase1-batch.md deleted file mode 100644 index d601d63..0000000 --- a/changelogs/2026-04/27_refactor_cr-audit_phase1-batch.md +++ /dev/null @@ -1,87 +0,0 @@ -# 重构:80 PR 代码规范循环审查 Phase 1 批量修复(5 PR) - -**类型**: 内部重构(对前端基本零影响 + 1 处 Feign Fallback 行为变更) -**关联**: 工单 #1510 / PR #1511 #1512 #1513 #1514 #1515 -**日期**: 2026-04-27 -**影响范围**: 6 个后端服务全量(common/user/resource/order-v2/product-v2/mp),全部需重新部署 - ---- - -## 背景 - -派 6 个 /@cr 并行审查 wx 最近 80 个已合并业务 PR (#1345 ~ #1505) 涉及的 437 个 Java 文件,对照 `docs/CODE_RULES.md` 找出违反规范的代码。Round 1 共发现 **384 处违规** (P0=225 / P1=72 / P2=62)。 - -本批 Phase 1 修复 **48 处低成本违规** (剩 336 处分 Phase 2/3 独立任务跟踪)。 - -## 5 个修复 PR - -| PR | 模块 | 修/总 | 主修内容 | 合并 commit | -|----|------|------|----------|-----------| -| #1511 | hl-common | 5/5 | GlobalExceptionHandler 4 处 @Autowired 字段注入改构造器(ObjectProvider 包装可选依赖) + Result.success() 重构(避免传 null) | 9c6d167e | -| #1512 | hl-user-service | 13/19 | 4 个 Mapper @Select/@Update 注解 SQL 改 default+QueryWrapper 聚合方法 + 3 处字段注入构造器化 + 2 处缺失 @Valid 补全 + 4 处 success(null)→success() | 063475a6 | -| #1513 | hl-resource-service | 11/12 | 9 个资源 service 的通知类 monitorFeign 调用从 @Transactional 内移到 afterCommit(register + 非事务兜底 + effectively final) + 1 处 @Valid 补全 | 5a1cb159 | -| #1514 | hl-order-service-v2 | 10/14 | 2 处 @Autowired 字段→构造器 + 3 处 new ObjectMapper→注入 + 2 处 @Valid 补全 + 2 处 BeanUtil 后显式 set 防 enum→String 字段吞 + TierInfoResolver static 工具类改 @Component(4 个 caller 同步) | d5c4df29 | -| #1515 | hl-product-service-v2 + hl-mp-service | 9/9 | 6 处 success(null)→success() + 2 处 ObjectMapper/RestTemplate 改注入(新增 RestTemplateConfig @Bean) + 1 处字段注入构造器化 + **2 个 Feign Fallback 行为变更** | 877f22b5 | - -## ⚠️ 唯一对前端有影响的变更:Feign Fallback 行为 - -PR #1515 调整了 mp 服务的 2 个 Feign Fallback Factory 共 4 处: - -### 改前 -```java -// MpProductFeignFallbackFactory.getEarliestBookingDate -@Override -public Result<EarliestBookingDateVO> getEarliestBookingDate(Long productId) { - return Result.success(null); // 静默"伪装成功"返回 null data -} -``` - -### 改后 -```java -@Override -public Result<EarliestBookingDateVO> getEarliestBookingDate(Long productId) { - return Result.error("产品服务不可用，请稍后重试"); // 显式失败 -} -``` - -### 受影响的接口(4 处) - -| Fallback Factory | 方法 | 原行为 | 新行为 | -|-----------------|------|------|------| -| MpProductFeignFallbackFactory | getEarliestBookingDate | `code=200, data=null` | `code≠200, message="产品服务不可用，请稍后重试"` | -| MpOrderFeignFallbackFactory | getPreTripChecklist | `code=200, data=null` | `code≠200, message="订单服务不可用，请稍后重试"` | -| MpOrderFeignFallbackFactory | matchEarlyBird | `code=200, data=null` | `code≠200, message="订单服务不可用，请稍后重试"` | -| MpOrderFeignFallbackFactory | validateEarlyBirdPlan | `code=200, data=null` | `code≠200, message="订单服务不可用，请稍后重试"` | - -### 触发条件 -仅当上游服务(product-v2 / order-v2)**完全不可达 + 本地熔断打开**时才触发 Fallback。正常请求/业务异常等都仍按原 code 返回,未受影响。 - -### 前端处理建议 - -1. 这 4 个接口的 mp 端调用方,**必须判 `result.code` 决定走业务分支还是降级 UI**: - - `result.code === 200 && result.data` → 业务正常渲染 - - `result.code !== 200` → 显示降级提示(按 result.message 文案 + toast/弹窗,**不要再当成 success-空数据**展示) -2. **正常业务逻辑不需要改**(本变更只在熔断场景生效,日常 99.9%+ 场景行为完全等价) - -## 其余 4 PR 对前端影响 - -**零影响**。全部是后端内部重构,对外 API 行为完全等价: -- 字段注入改构造器注入 → JVM 内部 bean 装配方式变化,接口调用方无感知 -- @Valid 补全 → 接口校验更严,本来该被前端校验拦住的非法请求,现在后端也兜住,前端无须改 -- success(null) → success() → JSON 返回 `{"code":200,"message":"成功","data":null}`,字节级等价 -- Mapper @Select 改 default+WrapperX → SQL 输出等价,接口数据完全一致 -- afterCommit 改造 → 通知类 Feign 异步执行时机微调(事务提交后才发 monitor 日志),接口响应时间略有缩短,接口数据完全一致 -- BeanUtil 后显式 set → 防 enum→String 字段值丢失(原来是 BUG 修复变更前可能 null),前端拿到的值是真实值,**这是正面修复** - -## 后端编译/部署 - -- ✅ 5 个 PR 各自 `mvn compile -pl <module> -am` 单独编译通过 -- ⏭️ 部署: 因 hl-common 改动,**需全量重新部署 6 个业务服务** (gateway/user/resource/product-v2/order-v2/mp) -- 测试服部署后请优先回归 mp 端 4 个 Fallback 接口熔断场景(可暂停 product-v2/order-v2 触发熔断验证 Fallback 不再返 success-null) - -## 留 Phase 2/3 (后续独立任务) - -- **Phase 2 中等成本** (估 ~120 P0): C2 Service 构造 Wrapper 下沉 / C27 Map 传数据→VO / C29 Service 接收 ReqVO / C1 Controller 业务下沉 -- **Phase 3 架构级重构** (估 ~120 处): C-ONE-MAPPER 拆 Service (40 P0) / C-SIZE 类体积超 300 (58 处, HotelService 952 / ScenicSpotService 937 等) / C17 状态机 if-else / C-DI-LIMIT Service 依赖>7 - -详见 `docs/tasks/20260427_审查_最近80个PR循环审查.md` 与 `test/cr-audit-data/round1/AGGREGATE-report.md`。 diff --git a/changelogs/2026-04/27_refactor_insurance-scheme_full-trip-totaldays.md b/changelogs/2026-04/27_refactor_insurance-scheme_full-trip-totaldays.md deleted file mode 100644 index 61ad108..0000000 --- a/changelogs/2026-04/27_refactor_insurance-scheme_full-trip-totaldays.md +++ /dev/null @@ -1,48 +0,0 @@ -# 保险方案"全程方案"语义对齐 (totalDays 哨兵) - -**日期**: 2026-04-27 -**PR**: #1454 (Closes #1425) -**影响端**: 管理端 admin - -## 背景 - -保险方案的「段配置」(InsuranceSchemeSegment) 中 `dayOffsetEnd = -1` 是「行程最后一天/全程」的合法哨兵值。 - -之前 `computeTotalDays` 算法见到 -1 时会跳过该段、错误返回 maxDay=1，导致「全程方案」入库时 `totalDays=1`。`AdminInsuranceSchemeController.listActiveSchemes` 按 `totalDays.equals(s.getTotalDays())` 精确过滤，结果「全程方案」**只在 1 天行程下拉里能查到**，多天行程查不到，与字段语义不符。 - -## 改动 - -### 后端 -- 新增哨兵常量 `InsuranceConstants.TOTAL_DAYS_FULL_TRIP = -1` -- `computeTotalDays` 见到任一段 `dayOffsetEnd == -1` → 返回哨兵 -1 -- `listActiveSchemes` 过滤逻辑同步: `totalDays==-1 || totalDays==请求tripDays` 视为命中 - -### 接口字段语义变化 - -**`GET /admin/insurance/scheme/list?totalDays=N`**（启用方案下拉，按行程天数筛选） -- 之前: 只返回 `totalDays == N` 的方案 -- 现在: 返回 `totalDays == N` 或 `totalDays == -1`（全程方案）的方案 - -**`POST /admin/insurance/scheme` / `PUT /admin/insurance/scheme/{id}`** -- request body 行为不变（前端继续配 `dayOffsetEnd: -1` 表示全程段） -- response body 中的 `totalDays` 字段语义变化: - - 之前: 全程方案返回 `1`（错误语义） - - 现在: 全程方案返回 `-1`（哨兵, 表示"任意天数都适用"） - - 普通方案不受影响 - -## 前端注意 - -**列表页/详情页展示**: 如果前端 UI 需要展示 `totalDays`, 见到 `-1` 应当展示为「全程」/「任意天数」, 而不是直接显示 "-1天"。 - -**新增/编辑表单**: `totalDays` 字段是后端计算字段, 前端不需要表单填写, 直接读 response 即可。 - -## 数据迁移 - -- 现存所有方案均为非 -1 段配置, `totalDays` 都是正值, 无需迁移 -- 本次上线后用户配置全程段时, 入库 `totalDays=-1` 自动生效 - -## 单测 - -- `InsuranceManageServiceTest`: +3 case (单段全程哨兵 / 多段含全程 / 全部正常段保持原算法) -- `AdminInsuranceSchemeControllerTest`: +2 case (5 天行程仅命中全程 / 同时命中全程+精确) -- 全部 56 单测绿 diff --git a/changelogs/2026-04/28_change_admin-contract-scheme-form_remove-sync-and-onsite-offline-options.md b/changelogs/2026-04/28_change_admin-contract-scheme-form_remove-sync-and-onsite-offline-options.md deleted file mode 100644 index ca2508d..0000000 --- a/changelogs/2026-04/28_change_admin-contract-scheme-form_remove-sync-and-onsite-offline-options.md +++ /dev/null @@ -1,91 +0,0 @@ -# change: 合同方案表单「签约模式/签署模式」精简选项 — 待前端处理 - -**日期**: 2026-04-28 -**类型**: 产品决策（精简选项）— **后端零改动** -**影响端**: 管理后台 (admin) — 系统管理 → 合同方案 → 新增/编辑弹窗 -**反馈来源**: 用户当面指示，截图圈出要删除的 3 个 radio 选项 - ---- - -## 改动要求 - -合同方案弹窗（`编辑合同方案` / `新增合同方案`）里**删除以下 3 个 radio**： - -### 「签约模式」 contractMode - -| 当前 value | 当前 label | 处理 | -|---|---|---| -| STANDARD | 电子签约 | ✅ 保留（且作为唯一选项） | -| SYNC | 线下报备 | ❌ **删除** | - -### 「签署模式」 signatoryMode - -| 当前 value | 当前 label | 处理 | -|---|---|---| -| 1 | 短信签署 | ✅ 保留（且作为唯一选项） | -| 2 | 现场签署 | ❌ **删除** | -| 3 | 线下签署 | ❌ **删除** | - -删除后两个 radio group 都只剩单一选项，建议直接改成只读展示文字或保留单 radio（默认选中且 disabled）。 - ---- - -## 修改位置 - -**文件**: `hl-ui/src/views/contract/scheme/components/SchemeEditModal.vue` - -```vue -<!-- 当前 line 47-51 --> -<n-form-item label="签约模式" path="contractMode"> - <n-radio-group v-model:value="formData.contractMode"> - <n-radio value="STANDARD">电子签约</n-radio> - <n-radio value="SYNC">线下报备</n-radio> <!-- 删除这行 --> - </n-radio-group> -</n-form-item> - -<!-- 当前 line 54-60 --> -<n-form-item label="签署模式" path="signatoryMode"> - <n-radio-group v-model:value="formData.signatoryMode"> - <n-radio value="1">短信签署</n-radio> - <n-radio value="2">现场签署</n-radio> <!-- 删除这行 --> - <n-radio value="3">线下签署</n-radio> <!-- 删除这行 --> - </n-radio-group> -</n-form-item> -``` - -默认值（`line 167-168`）已经是 `'STANDARD'` 和 `'1'`，无需调整。 - ---- - -## 兼容性提醒 - -后端 **不会** 删除 `ContractMode.SYNC` 枚举值和 `signatoryMode=2/3` 的支持，原因： - -1. 12301 平台规范本身定义了 `signatory.mode` 取值 1=短信 / 2=现场 / 3=线下，是上游协议字段 -2. v1 历史数据 / contract_scheme 表 / contract 表里**可能存在** value=`SYNC` 或 signatoryMode=2/3 的旧记录 -3. 后端 `ContractMode.java` / `dict_business_enums.sql` 里的字典/枚举原样保留 - -⚠️ **前端处理回显的兼容**：编辑老方案时 `detail.contractMode === 'SYNC'` 或 `detail.signatoryMode === 2/3` 的情况下，radio group 会找不到匹配项导致显示空白。建议前端任选一种处理： - -- 方案 A：渲染前若检测到旧值，自动回填到剩余的有效值（`STANDARD` / `'1'`），用户保存时自动迁移 -- 方案 B：旧值场景额外渲染一个 disabled radio 显示原值，但禁止重新选择 - -推荐方案 A（迁移更彻底）。 - ---- - -## 验证清单 - -- [ ] 「签约模式」radio 只剩 `电子签约` -- [ ] 「签署模式」radio 只剩 `短信签署` -- [ ] 编辑历史方案（`contractMode=SYNC` 或 `signatoryMode=2/3`）时回显不报错 -- [ ] 新增/编辑保存后，提交给后端的 contractMode 始终是 `STANDARD`，signatoryMode 始终是 `1` -- [ ] 「合同方案列表」里历史 `SYNC`/`2`/`3` 数据展示是否仍正常（这个文件不动表格列，只动弹窗） - ---- - -## 关联 - -- 后端 ContractMode 枚举: `hl-order-service-v2/src/main/java/com/hulalv/contract/enums/ContractMode.java` -- 后端 ContractSchemeVO: `hl-order-service-v2/src/main/java/com/hulalv/contract/vo/ContractSchemeVO.java:43-47` -- 12301 协议字段映射: `signatory.mode` (12301 申报合同 API) diff --git a/changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md b/changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md deleted file mode 100644 index bfc5fea..0000000 --- a/changelogs/2026-04/28_feat_admin-user_add-customer-service-id.md +++ /dev/null @@ -1,151 +0,0 @@ -# 新增字段:管理员表加「企业微信客服ID」(customerServiceId) - -**类型**: 后端新增字段 + 前端管理后台展示/编辑 -**关联**: 工单 #1519 / PR #1521 / 用户(wx)需求 -**日期**: 2026-04-28 -**影响范围**: 管理员管理（admin/user）模块的所有列表、详情、新增、编辑接口 - ---- - -## 背景 - -管理员管理页面要展示并维护每个管理员对应的企业微信「客服系统」客服 ID（open_kfid），用于后续与企业微信客服 API 对接。 - -**与现有 `enterpriseWechatId` 的区别**： -- `enterpriseWechatId` = 员工的企业微信 userid（已有字段，通过 `/wechat-binding` 专属接口换绑） -- `customerServiceId` = 企业微信「客服系统」里的客服账号 ID（新增字段，open_kfid，无需换绑校验） - ---- - -## 数据库变更 - -`admin_user` 表新增列： - -```sql -ALTER TABLE admin_user ADD COLUMN customer_service_id VARCHAR(64) DEFAULT NULL - COMMENT '企业微信客服系统客服ID(open_kfid)，可空' AFTER enterprise_wechat_id; -``` - -- 类型 `VARCHAR(64)`，**可为 NULL** -- 不建索引、不加唯一约束 -- 不参与查询过滤 - ---- - -## 接口变更（共 4 处，全部位于现有 admin 接口） - -### 1. 新增管理员 `POST /admin/user` - -请求体 `CreateAdminRequest` 新增字段： - -| 字段 | 类型 | 必填 | 长度 | 说明 | -|---|---|---|---|---| -| `customerServiceId` | string | 否 | ≤64 | 企业微信客服系统客服ID(open_kfid) | - -请求示例： -```json -{ - "username": "zhangsan", - "roleIds": [3], - "customerServiceId": "wkAJ2GCAAA_kfid_001" -} -``` - -### 2. 更新管理员 `PUT /admin/user/{adminId}` - -请求体 `UpdateAdminRequest` 新增字段： - -| 字段 | 类型 | 必填 | 长度 | 说明 | -|---|---|---|---|---| -| `customerServiceId` | string | 否 | ≤64 | 企业微信客服系统客服ID。**传 null 保留原值，传空字符串 `""` 清空** | - -请求示例： -```json -{ - "roleIds": [3], - "customerServiceId": "wkNEW_kfid_002" -} -``` - -> ⚠️ 与 `enterpriseWechatId`（PUT 时被忽略，需走专属换绑接口）不同，`customerServiceId` 在 PUT 接口直接生效，不需要换绑校验。 - -### 3. 管理员详情 `GET /admin/user/{adminId}` - -响应体 `AdminUser` 新增字段： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `customerServiceId` | string \| null | 企业微信客服系统客服ID | - -### 4. 管理员列表 `GET /admin/user` - -响应数组每个元素新增同字段 `customerServiceId`。 - ---- - -## 校验规则 - -- 长度 ≤64 字符 -- 超长返回 HTTP 200 + 业务码 400： - ```json - { - "code": 400, - "message": "customerServiceId: 客服ID长度不能超过64个字符", - "data": null, - "success": false - } - ``` - ---- - -## 前端处理（yst / mmg） - -### 必做改动 -1. **管理员管理列表页**（截图位置：`管理员管理` 主表格） - - 加列「客服 ID」（建议放在「企业微信」列右边） - - 单元格直接展示 `customerServiceId` 字符串，为 null 时显示 `-` - -2. **新增成员表单** - - 加输入框「客服 ID」，placeholder 提示 `wkAJ2GCAA...（企业微信客服系统 open_kfid）` - - 单行文本，maxlength=64 - - **非必填** - -3. **编辑成员表单**（同新增） - - 字段名 `customerServiceId` - - 不传 = 保留原值；传空串 `""` = 清空原值 - -### 兼容性 -- **零破坏**：新增字段，未传入时后端落空值，原有调用方完全无影响 -- **TypeScript 类型补充**：`AdminUser` 类型加 `customerServiceId?: string | null` - ---- - -## 单元 + E2E 测试覆盖 - -### 单元测试（4/4 全绿） -- `createAdmin_withCustomerServiceId_persistsField` -- `createAdmin_nullCustomerServiceId_persistsNull` -- `updateAdmin_withCustomerServiceId_overwritesValue` -- `updateAdmin_nullCustomerServiceId_keepsOriginalValue` - -### 测试服 E2E（6/6 全过） -- 创建管理员 + customerServiceId → ✅ -- GET 详情返回 → ✅ -- PUT 更新覆盖 → ✅ -- PUT null 保留原值 → ✅ -- 列表查询返回 → ✅ -- @Size(max=64) 校验 400 → ✅ - ---- - -## 不在本次范围 -- 不与企业微信客服 API 真正对接（后续工单） -- 字段不参与查询过滤、不分单 -- 不建索引、不加唯一约束 - ---- - -## 部署状态 -- ✅ 测试服 `admin_user` 已 ALTER（生产环境上线时需同步执行 ALTER） -- ✅ 测试服 hl-user-service 已 Deploy Panel 部署 -- ✅ 测试服端到端验证通过（经网关 `https://api.test.1814.love:9443`） diff --git a/changelogs/2026-04/28_feat_traveler_homereturn-permit-and-contract-idtype-fix.md b/changelogs/2026-04/28_feat_traveler_homereturn-permit-and-contract-idtype-fix.md deleted file mode 100644 index 05bd439..0000000 --- a/changelogs/2026-04/28_feat_traveler_homereturn-permit-and-contract-idtype-fix.md +++ /dev/null @@ -1,128 +0,0 @@ -# 新增:支持回乡证(港澳居民来往内地通行证)全链路 + 修合同 IDType 映射 BUG - -**类型**: 功能新增 + 合同 P0 BUG 修复 -**关联**: 工单 #1522 / PR #1523 / 用户(wx)反馈 -**日期**: 2026-04-28 -**影响范围**: 出行人录入 / 合同自动签约 / 12301 提交 / 腾讯电子签提交 - ---- - -## 背景 - -用户咨询"合同支持回乡证, OCR 和系统支持不"。调研发现: - -| 层 | 调研前现状 | -|----|-----------| -| 12301 底层 API | ✅ 支持 IDType=6=回乡证 (标准.docx 已定义) | -| 腾讯电子签 API | ✅ 支持 HONGKONG_AND_MACAO | -| 我们 traveler 字典 | ❌ 缺 HONGKONG_RESIDENT_PASS 枚举 | -| 我们 OCR 服务 | ❌ 阿里云 SDK 限制 | -| **合同转换层** | ❌ **P0 BUG**: 只识别 ID_CARD/PASSPORT, 其他全 fallback=1 身份证 | - -## 5 步实施 - -### 1. 字典 id_card_type 新增 HONGKONG_RESIDENT_PASS - -- `sql/dict_business_enums.sql` 加 80077 = (id_card_type, '回乡证', 'HONGKONG_RESIDENT_PASS', sort_order=7) -- 新增增量 SQL `sql/V20260428__id_card_type_add_homereturn_permit.sql` 含 ON DUPLICATE KEY UPDATE 兜底, 部署时 SSH source 即可 - -### 2. Java enum + VO 注释同步 10 处 - -- `IdCardType.HONGKONG_RESIDENT_PASS("HONGKONG_RESIDENT_PASS", "回乡证(港澳居民来往内地通行证)")` -- 同步 AdminOrderTraveler*ReqVO / MpOrderTravelerSaveReqVO (order-v2 + mp-service) / TravelerRequest / TravelerOcrReqVO / Traveler / TravelerOcrLogDO / MpTravelerOcrController 全套 @ApiModelProperty 注释 -- `TravelerService.VALID_ID_CARD_TYPES` 白名单 6→7 项 - -### 3. OCR 占位实现 (⚠️ SDK 限制留 Phase 2) - -- **SDK 缺类**: 阿里云 `ocr_api20210707:3.1.3` jar 内 270 个 Recognize* 类**不含** `RecognizeMainlandTravelPermit` (已 unzip -l 全量 grep 确认) -- `AliyunOcrService.recognizeHomeReturnPermit` 抛 `BusinessException(OCR_HOMERETURN_PERMIT_NOT_SUPPORTED=230009)` 友好提示"OCR 暂不支持回乡证识别(请手动填写证件信息)" -- `TravelerOcrService` 路由 + 白名单 OCR_SUPPORTED_TYPES 4→5 项 (透传错误码) - -### 4. ContractCreateService 转换层 P0 BUG 修复 (本 PR 核心) - -旧 `ContractCreateService.java:741-742`: -```java -String idCardType = t.getIdCardType() != null ? t.getIdCardType().name() : "ID_CARD"; -dto.setIdCardType("PASSPORT".equals(idCardType) ? 2 : 1); // ← 永远只输出 1 或 2 -``` - -新增 helper 完整对齐 12301 标准: -```java -private static int mapIdCardTypeToInt(String code) { - if (code == null) return 1; - switch (code) { - case "ID_CARD": return 1; - case "MILITARY_ID": return 2; - case "HK_MACAU_PASS": return 3; - case "PASSPORT": return 4; - case "TAIWAN_PERMIT": return 5; - case "HONGKONG_RESIDENT_PASS": return 6; // 回乡证 - case "TAIWAN_PASS": return 7; - case "OTHER": return 8; - default: return 1; - } -} -``` - -12301 标准 API IDType 定义来源 `docs/文档/国家旅游局合同api/标准.docx` 506/535/1007 段三处一致。 - -### 5. 腾讯电子签 mapIdCardType 4→8 case + 修历史 BUG - -`TencentEsignRequestBuilder.java:236` 由 4 case + default 改为完整 8 case: - -```java -case 1: return "ID_CARD"; -case 2: return "OTHER_CARD_TYPE"; // 士官证 - 腾讯无对应 -case 3: return "HONGKONG_AND_MACAO"; // 港澳通行证 -case 4: return "PASSPORT"; // ⚠️ 历史 BUG 修复: 原 case 4=TAIWAN 错位 -case 5: return "OTHER_CARD_TYPE"; // 赴台证 - 腾讯无对应 -case 6: return "HONGKONG_AND_MACAO"; // 回乡证 - 港澳居民身份 -case 7: return "TAIWAN"; // 台胞证 -case 8: return "OTHER_CARD_TYPE"; -``` - -## 影响 — 前端关注 - -### 必须做 (前端 yst/mmg) -1. **下拉框**: 出行人录入页"证件类型"下拉选项加"回乡证"项 (字典 id_card_type 已新增 HONGKONG_RESIDENT_PASS) -2. **OCR 提示**: 用户选了"回乡证"时, OCR 上传按钮要么置灰要么提示"暂不支持识别, 请手动填写"; 接口仍可调,会返 errorCode=230009 + message="OCR 暂不支持回乡证识别(请手动填写证件信息)" -3. **管理后台**: 同样补"回乡证"选项 - -### 不影响 -- 已有 ID_CARD/PASSPORT/HK_MACAU_PASS/TAIWAN_PASS/MILITARY_ID/OTHER 行为完全等价 - -## 影响 — 运营关注 - -- 修复后用户选 HK_MACAU_PASS/TAIWAN_PASS 等证件下单, 合同传给 12301 的 IDType 终于不再被错误压成 1=身份证, 与真实证件类型一致 (这是默默修复多月的隐性 BUG) -- 12301 平台首次见到非身份证类合同申请, 可能有合规校验需要联调对接 (建议运营做端到端回归) - -## 部署步骤 - -### Step 1: 跑 SQL 增量 -```bash -# 测试服 -ssh root@192.168.100.236 "mysql -uroot -proot hl_user_service < sql/V20260428__id_card_type_add_homereturn_permit.sql" -# 正式 (SSH Node1) -ssh root@47.105.108.0 "mysql -uhl_admin -p<密码> hl_user_service < sql/V20260428__id_card_type_add_homereturn_permit.sql" -``` - -### Step 2: 重启服务 (k3s 滚动) -```bash -ssh root@47.105.95.198 "kubectl rollout restart deployment hl-user-service -n hl-prod && kubectl rollout restart deployment hl-order-service-v2 -n hl-prod" -``` - -### Step 3: 验证 -- 字典 API: `GET /internal/dict/data?dictType=id_card_type` 应包含 HONGKONG_RESIDENT_PASS -- 出行人录入: admin 后台/小程序选回乡证 + 录入证件号 -- 合同申请: 跑一笔回乡证旅客订单, DB 看 contract_request.signatory_id_type=6 (12301 IDType) - -## Phase 2 待办 (独立工单) - -1. **TeamReportService.mapIdCardType** 同样有"PASSPORT→2/TAIWAN_PASS→3/HK_MACAU_PASS→4"老错位映射, 本 PR 防越权刻意未碰 -2. **阿里云 OCR SDK 升级** 到含 `RecognizeMainlandTravelPermit` 的版本, 实现真识别 (参考 PR #1057→#1060 护照踩坑经验, 用真实样本验证字段名) -3. **12301 真接口 round-trip 联调** 真实回乡证号 (运营/管理者跑) - -## 合并 - -- PR #1523 squash merge 到 dev (sha 13034d82) -- 工单 #1522 待运营 SQL 部署 + 前端补下拉选项 + 12301 联调后再关闭 diff --git a/changelogs/2026-04/28_fix_admin-frontend-config_value-type-enum-mismatch.md b/changelogs/2026-04/28_fix_admin-frontend-config_value-type-enum-mismatch.md deleted file mode 100644 index 25e26ee..0000000 --- a/changelogs/2026-04/28_fix_admin-frontend-config_value-type-enum-mismatch.md +++ /dev/null @@ -1,96 +0,0 @@ -# fix: 前端配置「值类型」下拉与后端枚举不一致 — 待前端修复 - -**日期**: 2026-04-28 -**类型**: 前端 BUG — **后端零改动**, 改前端写死的下拉常量即可 -**影响端**: 管理后台 (admin) — 系统管理 → 前端配置 → 新增/编辑配置对话框 -**反馈来源**: 前端同事反馈「值类型对接不上」 - ---- - -## 现象 - -`admin.1814.love/frontend-config` 列表里已有数据的 `值类型(configType)` 列显示了 **TEXT** (站点名称) 和 **IMAGE** (Logo地址) 两种类型,但点「新增配置」弹窗的「值类型」下拉框里**选不出来这两个值**。 - -下拉框里的值： - -| 前端下拉显示 | 前端发给后端的 value | -|---|---| -| STRING - 字符串 | `STRING` ❌ | -| COLOR - 颜色 | `COLOR` ✅ | -| NUMBER - 数字 | `NUMBER` ✅ | -| BOOLEAN - 布尔 | `BOOLEAN` ✅ | -| JSON - JSON | `JSON` ✅ | -| SECRET - 密钥 | `SECRET` ✅ | -| URL - 链接 | `URL` ❌ | - ---- - -## 根因 - -**前端 `configType` 下拉选项写死了与后端不一致的枚举值。** - -后端 `sys_frontend_config.config_type` 字段权威枚举（Entity + schema.sql + `FrontendConfigConverter` 三处一致）： - -``` -TEXT / COLOR / IMAGE / JSON / SECRET / NUMBER / BOOLEAN -``` - -后端引用： -- Entity 注释 `hl-user-service/src/main/java/com/hulalv/user/entity/SysFrontendConfig.java:28` -- schema `sql/frontend_config.sql:7` `'值类型: TEXT/COLOR/IMAGE/JSON/SECRET/NUMBER/BOOLEAN'` -- 转换器常量 `hl-user-service/src/main/java/com/hulalv/user/converter/FrontendConfigConverter.java:25-36` - -前端写错 2 项 + 缺 2 项： - -| 项 | 前端 | 后端权威 | 处理 | -|---|---|---|---| -| 字符串 | `STRING` | `TEXT` | **改 value 为 `TEXT`** | -| 图片 | (缺) | `IMAGE` | **新增 `IMAGE - 图片`** | -| 链接 | `URL` | (无此类型) | **删除 `URL`**(后端无对应转换逻辑,即使存进去也按 default 当字符串处理,语义不清) | -| 文本 | (缺,误用 STRING 顶替) | `TEXT` | 同第一行,改 value 即可 | - ---- - -## 前端需要做的修改 - -定位 `hl-ui` 仓库下「前端配置」新增/编辑对话框的 `configType` 下拉 options 常量,改成： - -```js -const CONFIG_TYPE_OPTIONS = [ - { value: 'TEXT', label: 'TEXT - 文本' }, - { value: 'COLOR', label: 'COLOR - 颜色' }, - { value: 'IMAGE', label: 'IMAGE - 图片' }, - { value: 'NUMBER', label: 'NUMBER - 数字' }, - { value: 'BOOLEAN', label: 'BOOLEAN - 布尔' }, - { value: 'JSON', label: 'JSON - JSON' }, - { value: 'SECRET', label: 'SECRET - 密钥' }, -] -``` - -注意： -1. **去掉 `STRING` 和 `URL`** —— 后端不识别(STRING 进 DB 后会按 default 当字符串渲染但与已有 TEXT 数据混杂; URL 同理) -2. **补上 `TEXT` 和 `IMAGE`** —— DB 里 siteName/footerText 等都是 TEXT, logoUrl 是 IMAGE - ---- - -## 验证 - -改完后到「新增配置」弹窗，下拉框 7 项应能完整覆盖： -- TEXT / COLOR / IMAGE / NUMBER / BOOLEAN / JSON / SECRET - -并能编辑列表里已有的 `siteName` (TEXT) 和 `logoUrl` (IMAGE),不会出现「值类型空白」或「保存后回显错误」。 - ---- - -## 后端约定（不会变） - -后端 `FrontendConfigConverter.convert(value, configType)` 按以下规则转换： - -| configType | 转换为 | -|---|---| -| `NUMBER` | Long / Double（含 `.` 走 Double） | -| `BOOLEAN` | Boolean | -| `JSON` | JSONObject / JSONArray | -| `TEXT` / `COLOR` / `IMAGE` / `SECRET` / 其他 | 原字符串 | - -任一 parse 失败都降级为原字符串,不抛异常。`configType` 不在白名单内时也不报错,直接当字符串。所以即使前端历史误传过 `STRING`/`URL`,接口不会 500,只是数据列表里类型列会显示出和下拉对不上的字符串值。 diff --git a/changelogs/2026-04/28_fix_contract_hardcode-complaint-phones.md b/changelogs/2026-04/28_fix_contract_hardcode-complaint-phones.md deleted file mode 100644 index 58a4e9a..0000000 --- a/changelogs/2026-04/28_fix_contract_hardcode-complaint-phones.md +++ /dev/null @@ -1,53 +0,0 @@ -# fix(contract): 12301 申报合同硬编码两个投诉电话字段 - -**日期**: 2026-04-28 -**PR**: #1537 (commit 4e63f5d53a) -**工单**: #1536 -**影响端**: 后端内部（12301 平台必填字段补全） - ---- - -## 背景 - -12301 申报合同 API 的 `travelAgency` 块两个必填投诉电话字段当前**完全没拼装到 JSON**，触发青岛文旅局案例文1-2 ¥10万 + 停业3月 P0 红线。 - -## 后端改动 - -`TourageRequestBuilder.buildTravelAgency` 末尾追加 2 行： - -```java -agency.put("localComplaintPhone", "12301"); // 全国旅游服务热线 (固定) -agency.put("complaintPhone", "470-8222122"); // 呼伦贝尔本地投诉电话 (固定) -``` - -## 设计决策 - -| 字段 | 值 | 为什么硬编码不读 Nacos | -|---|---|---| -| `localComplaintPhone` | `"12301"` | 国家文旅部全国统一旅游投诉热线，全国所有旅行社都填这个，不会变 | -| `complaintPhone` | `"470-8222122"` | 呼伦贝尔本地投诉电话，跟 Nacos `agencies[].complaint-phone=4000881814` 是不同语义（4000881814 是呼籁客服热线，470-8222122 是文旅监管投诉热线） | - -## 影响 - -- 12301 申报合同 API 调用即生效，避免被 12301 平台拒签 -- 前端无感知 - -## 部署状态 - -⏸ 待手动触发 Deploy Panel 部署 hl-order-service-v2 到测试服。 - -## 部署后验证 - -1. 测试服跑一单 12301 标准模式合同（产品场景：境内游 7 日） -2. 查 hl-order-service-v2 日志找到 12301 标准接口请求 body -3. 必须包含： - ```json - "travelAgency": { - ... - "localComplaintPhone": "12301", - "complaintPhone": "470-8222122", - ... - } - ``` -4. 12301 平台返回 success 不再因投诉电话字段缺失拒签 - diff --git a/changelogs/2026-04/28_fix_contract_pdf-upload-to-oss-after-sign.md b/changelogs/2026-04/28_fix_contract_pdf-upload-to-oss-after-sign.md deleted file mode 100644 index cfaaaad..0000000 --- a/changelogs/2026-04/28_fix_contract_pdf-upload-to-oss-after-sign.md +++ /dev/null @@ -1,66 +0,0 @@ -# fix(contract): 合同 PDF 签署完成后转存到自家 OSS - -**日期**: 2026-04-28 -**PR**: #1535 (commit be7bd3e5b2) -**工单**: #1533 -**影响端**: 后端内部（前端不感知，`contract.fileUrl` 仍是 PDF 下载链） - ---- - -## 背景 - -12301 / 腾讯电子签平台返回的 PDF URL 是**临时下载链**，过期后 404，**合规留底丢失**。签署完成后异步下载平台 PDF 上传到自家 `hlgl-test` bucket，替换 `contract.file_url`。 - -## 后端改动 - -新增 `ContractPdfUploadService`（参照保险 `PolicyPdfUploadService`）： -- `@Async("insuranceTaskExecutor")` 复用保险线程池 -- OSS key: `contract/pdf/{yyyy-MM}/{contractId}.pdf` -- 50 MB 大小上限 -- 全异常吞 + log.error，不阻塞回调主链路 - -接入两个回调点（都用 `afterCommit` 钩子异步触发）： -- `ContractCallbackService` - 12301 SIGNED 回调 -- `TencentEsignCallbackService` - 腾讯电子签 FLOW_COMPLETE 回调 - -## 数据流变化 - -### 修改前 -``` -平台签署完成 → 回调 → contract.file_url = 平台临时URL → 几小时后失效 → 404 -``` - -### 修改后 -``` -平台签署完成 → 回调 → contract.file_url = 平台URL（先兜底） - → afterCommit 异步：下载 → 上传 OSS → contract.file_url = 自家 OSS URL（永久） - → OSS失败：保留平台 URL（不影响业务） -``` - -## URL 格式 - -成功后 `contract.file_url` 形如： -``` -https://hlgl-test.oss-cn-beijing.aliyuncs.com/contract/pdf/2026-04/123456.pdf -``` - -## 前端兼容 - -**前端不需要任何改动** — `contract.fileUrl` 字段语义不变，只是后端把外链替换成自家链接。已下发链接（用户手机里的旧链）也仍然兼容到 OSS 失败兜底。 - -## 部署状态 - -⏸ 待手动触发 Deploy Panel 部署 hl-order-service-v2 到测试服。 - -## 部署后验证 - -1. 测试服 12301 测试平台真实跑一单合同签署 -2. SQL: `SELECT contract_id, file_url FROM contract WHERE status='SIGNED' ORDER BY signed_at DESC LIMIT 1;` -3. `file_url` 必须以 `hlgl-test.oss-cn-beijing.aliyuncs.com` 开头 -4. curl 该 URL 返回 200 PDF - -## 不在范围 - -- 历史数据迁移（如需要单独工单） -- OSS 生命周期/归档策略（运维任务） - diff --git a/changelogs/2026-04/28_fix_contract_status-log-and-vo-fields-i18n.md b/changelogs/2026-04/28_fix_contract_status-log-and-vo-fields-i18n.md deleted file mode 100644 index 7ed811c..0000000 --- a/changelogs/2026-04/28_fix_contract_status-log-and-vo-fields-i18n.md +++ /dev/null @@ -1,77 +0,0 @@ -# fix(contract): 合同详情页状态变更记录与字段值中文化 - -**日期**: 2026-04-28 -**PR**: #1534 (commit 9d420cb61d) -**工单**: #1532 -**影响端**: 管理后台 (admin) - 合同详情页 - ---- - -## 背景 - -合同详情页「状态变更记录」显示英文 `PENDING → GENERATED 来源: MANUAL`、「签约模式 ONLINE」、「证件类型 ID_CARD`，应显示中文。 - -## 后端改动 - -**新增 4 个 `*Label` 字段**（接口返回 JSON 同时含原始 value + 中文 label，前端用哪个都可以）： - -### `ContractDetailVO.statusLogs[]` 每项新增 - -```json -{ - "logId": 1, - "oldStatus": "PENDING", - "oldStatusLabel": "待创建", // 新增 - "newStatus": "GENERATED", - "newStatusLabel": "已生成", // 新增 - "source": "MANUAL", - "sourceLabel": "手动", // 新增 - "createTime": "2026-04-28T14:21:14" -} -``` - -### `ContractDetailVO.travelers[]` 每项新增 - -```json -{ - "name": "王骁", - "idCardType": "ID_CARD", - "idCardTypeLabel": "身份证", // 新增 - "idCardNo": "152****5216" -} -``` - -### 主体已存在 ✅ - -`ContractVO.modeLabel` (`ONLINE → 线上签署`) 之前就有，前端记得用。 - -## 字典/枚举来源 - -| label 来源 | 枚举类 | -|---|---| -| `oldStatusLabel/newStatusLabel` | `ContractStatus.labelOf(value)` | -| `sourceLabel` | **新增枚举** `ContractStatusSource.labelOf(value)` (CALLBACK=回调/POLLING=轮询/MANUAL=手动/SYSTEM=系统) | -| `idCardTypeLabel` | `IdCardType.labelOf(value)` | -| `modeLabel` | `ContractMode.labelOf(value)` | - -`labelOf()` 静态方法对未知值/null 都返回 null（不抛异常），前端可放心展示无需 try/catch。 - -## 前端 TODO（yst/mmg） - -合同详情页：把英文渲染替换成 label 字段。建议优先级： - -1. 状态变更记录 list：`oldStatusLabel`、`newStatusLabel`、`sourceLabel` 取代原来的 oldStatus/newStatus/source -2. 出行人 list：「证件类型」列用 `idCardTypeLabel` 取代 `idCardType` -3. 「签约模式」字段用 `modeLabel`（如果之前已经用 `mode`，改成 `modeLabel`） - -label 字段如果是 null（脏数据/未知值场景）做空字符串兜底即可，不要 throw。 - -## 部署状态 - -⏸ 待手动触发 Deploy Panel 部署 hl-order-service-v2 到测试服。本地无法访问 Panel（timeout）。 - -## 影响范围 - -- 后端零破坏（只加字段，不删不改） -- 前端不消费新字段时仍兼容（原 `oldStatus/newStatus/source/idCardType/mode` 都保留） - diff --git a/changelogs/2026-04/28_fix_order_contract-tourage-api-exception-classify.md b/changelogs/2026-04/28_fix_order_contract-tourage-api-exception-classify.md deleted file mode 100644 index ced4ff8..0000000 --- a/changelogs/2026-04/28_fix_order_contract-tourage-api-exception-classify.md +++ /dev/null @@ -1,81 +0,0 @@ -# 修复:12301 合同 API 异常分类细化, 网络/5xx 走兜底重试不再吞为业务失败 - -**类型**: 后端 BUG 修复 + 异常处理重构 -**关联**: 工单 #1518 / PR #1520 / 用户(wx)正式订单 HL20260428095227-1084 实测反馈 -**日期**: 2026-04-28 -**影响范围**: 合同自动签约链路, 仅限熔断/超时/服务端错误场景, 正常业务无影响 - ---- - -## 现象 - -正式环境订单 HL20260428095227-1084 已支付定金后,清单确认触发自动签约失败: -- 时间: 2026-04-28 10:02:59 (清单确认 +10s) -- 通知: INAPP/SMS/MINIAPP 给用户 + WEWORK 给 admin 839 -- DB: contract 表 0 行(从未创建成功) - -## 根因 - -**两层 BUG**: -1. **配置层**(运维侧): 正式 Nacos `hl-order-service-v2-prod.yml` 中 `contract.platform.standard.base-url=http://192.168.100.182:9301` 是测试机房内网 IP, 正式 k3s 集群路由不到 → 每次 SocketTimeoutException(10s) -2. **代码层**(本 PR 修): TourageApiClient.doRequest 在 catch (Exception e) 把所有异常包成 BusinessException(TOURAGE_API_CALL_FAIL), ContractEventListener.onChecklistConfirmed 优先 catch BusinessException 走"立即创建紧急待办, 不重试", 真正的"5xx/超时走兜底重试"分支永远走不到 - -## 本 PR 修复 (代码层) - -TourageApiClient.doRequest 的 catch 链拆细: - -| 异常类型 | 旧行为 | 新行为 | 路径 | -|---------|-------|-------|------| -| ResourceAccessException (网络/超时) | catch Exception → BusinessException → 不重试 | RuntimeException → ContractEventListener catch (Exception) 兜底 | 走重试 | -| HttpStatusCodeException 5xx | 返 errorNode → ContractApplyResult.fail | RuntimeException → 兜底 | 走重试 | -| HttpStatusCodeException 4xx | 返 errorNode → ContractApplyResult.fail + rawResponse | **保留原行为(返 errorNode)** | 不重试,审计入库 | -| 其他 Exception | BusinessException | BusinessException | 不变 | - -### 4xx 行为为何保留 -原始 dev agent 第一版实现是 4xx 抛 BusinessException, 但 TourageContractPlatform 的 5+ 个调用方依赖 `if (apiClient.isSuccess(response)) ... else { result = ContractApplyResult.fail(getErrorMessage(response)); result.setRawResponse(response.toString()); }` 模式, 要把错误 + rawResponse 入库审计。复审时改回保留 errorNode 返回行为, 确保 isSuccess(response)=false + getErrorMessage(response) 正常工作, 不破坏审计链路。 - -## 配置层修复 (运维做) - -由用户决策 "直接用测试环境配置就行": - -正式 Nacos prod namespace `hl-order-service-v2-prod.yml` 的 `contract:` 段需要替换为测试环境版本 (`https://open-api.mr.mct.gov.cn` + 3 家旅行社凭证完整). 详细 yaml + Step 1-5 操作步骤见工单 #1518 评论 + `test/cr-audit-data/round2/contract-prod-nacos-update.md`: - -- `standard.base-url` / `sync.base-url`: `http://192.168.100.182:9301` → `https://open-api.mr.mct.gov.cn` -- `agencies` 块的 hulai/qianshou/hulai-wenlu 的 mch-id/app-id/sign-key/team-report-* 与测试环境完全一致 -- 3 处差异化: `callback-base-url` 改正式域名 / `sign-url-proxy`/`qrcode-url-proxy` 留空(测试用 192.168.100.236 代理正式没有) - -## 单测覆盖 (TourageApiClientTest 新增 7 用例) - -- `callApi_resourceAccessException_throwsRuntimeException` 网络/超时 → RuntimeException -- `callApi_4xxStatus_returnsErrorNode` 4xx → errorNode (审计保留) -- `callApi_5xxStatus_throwsRuntimeException` 500 → RuntimeException 走重试 -- `callApi_503Status_throwsRuntimeException` 503 边界 -- `callApi_401Status_returnsErrorNode` 401 → errorNode -- `callApi_success_returnsJsonNode` 正常 JsonNode -- `callApi_otherException_throwsBusinessException` 兜底业务异常 - -## 部署后预期 - -修复后 + Nacos 配置纠正 + 服务重启 + 真订单端到端跑通后: -- 正常签约: 12301 返回 contractNumber → contract 表新增 PENDING/SIGNED 记录 → 用户收到"请签合同"短信 -- 12301 间歇性 5xx: ContractEventListener 走重试分支 → 默认重试若干次, 仍失败才告警 -- 12301 网络异常: 同上走重试 -- 12301 4xx (鉴权/参数): 仍走"立即告警不重试"(由 isSuccess+getErrorMessage 模式判定) - -## 前端 / 运营关注 - -**零影响**(全部是后端内部异常处理优化): -- 用户视角接口行为完全等价 -- 只有"间歇性 12301 5xx 抖动"或"网络瞬断"时, 用户体验从"立刻看到 CONTRACT_FAILED 短信"变成"系统自动重试后再决定", 体验**改善** - -## 后端部署 - -- ✅ `mvn compile -pl hl-order-service-v2 -am` 通过 (2 次) -- 仅需重启 hl-order-service-v2 (4 实例) 即生效 -- **必须配合运维改 Nacos contract.platform.* 配置**(单独本代码 PR 不能修复合同失败, 配置才是根因) -- 运营手动补建本订单 HL20260428095227-1084 合同 (Nacos 改完 + 服务重启后 → 调 admin API 或线下报备) - -## 合并 - -- PR #1520 squash merge 到 dev (sha 29d3b1d0) -- 工单 #1518 待 Nacos 配置 + 数据补建完成后再关闭 diff --git a/changelogs/2026-04/28_fix_order_payment-reminder-delay-15min.md b/changelogs/2026-04/28_fix_order_payment-reminder-delay-15min.md deleted file mode 100644 index 131cde9..0000000 --- a/changelogs/2026-04/28_fix_order_payment-reminder-delay-15min.md +++ /dev/null @@ -1,87 +0,0 @@ -# 修复:创建订单不再立即发"请完成支付"短信,改为 15 分钟后未支付才发提醒 - -**类型**: 后端 BUG 修复 + 通知流程调整 -**关联**: 工单 #1516 / PR #1517 / 用户(wx)正式环境实测反馈 -**日期**: 2026-04-28 -**影响范围**: 所有创建订单流程(C/B/管理端代客创单),所有用户支付提醒短信 - ---- - -## 现象 - -用户反馈:正式环境下单后**立即**点支付,1-3 秒内支付成功(订单 PENDING_PAY → PAID)。但仍收到一条「您的订单 HL20260428095227-1084 已创建成功,产品:王骁测试核心产品,请尽快完成支付」短信,用户疑惑"已支付了为啥还发提醒"。 - -## 根因 - -1. `OrderCreateService.afterCommit:350` 在订单创建事务提交后**立即**调 `notificationEventHelper.sendOrderCreated(notifyOrder)` 发 ORDER_CREATED 模板,**不判断当前支付状态** -2. 短信通道延迟到达(阿里云 SMS 5-30s + MQ 异步), 用户立即支付场景下短信到达时订单已 PAID -3. 同时项目早就有完整的延迟提醒链(SEND_PAYMENT_REMINDER 本地事件 → SendPaymentReminderHandler → MQ 延迟消息 → PaymentReminderConsumer 检查 PENDING_PAY 才发),但被"立即发的 ORDER_CREATED"重复了 - -## 修复内容 - -### 1. 删除立即发 ORDER_CREATED 调用 (OrderCreateService) -- 删除 `2.9 下单成功通知` 块的 sendOrderCreated afterCommit 注册 -- admin 出行人完整性检查 `checkTravelerAfterAdminCreate` 拆为独立 afterCommit (仅 ctx.isAdminCreate() 时注册) -- 加详细中文注释解释 BUG 修复理由 + 引用延迟提醒链路径 -- 全仓 `sendOrderCreated` 仅 1 处生产 caller, 删除即彻底切断"立即发"路径 -- NotificationEventHelper.sendOrderCreated 方法本体保留(NotificationEventHelperTest 单测覆盖), 将来若有"管理端代客创建后第一时间通知客户"明确需求可在专门入口调用 - -### 2. 支付提醒延迟改 15 分钟可配置 (OrderExpiryProducer) -- `delayLevel=14` 硬编码 (10 分钟) → 调 `getPaymentReminderMinutes() + mapToDelayLevel()` -- 默认 15 分钟,`mapToDelayLevel(15)=level 15=20分钟` (RocketMQ 4.x 无精确 15 级,取不小于 15 的最小 = 20m) -- 新增 `@Value("${order.payment-reminder.default-minutes:15}")` -- 新增 `@Value("${order.payment-reminder.redis-key:order:config:payment-reminder-minutes}")` -- 新增 `getPaymentReminderMinutes()` public 方法 (Redis fallback DB 默认值,与 getExpiryMinutes 同 pattern) -- 日志增强: 输出 `delayMinutes={}, delayLevel={}` (原硬编码 `delayMinutes=10`) - -### 3. 单测覆盖 (OrderExpiryProducerTest) -新增 5 个用例: -- `sendPaymentReminderMessage_defaultConfig_use15MinutesLevel15` 默认 15min → delayLevel 15 -- `sendPaymentReminderMessage_redisConfig10Minutes_useDelayLevel14` Redis 配 10min → delayLevel 14 -- `getPaymentReminderMinutes_redisConfigValid_useRedisValue` Redis "20" → 20 -- `getPaymentReminderMinutes_redisInvalid_fallbackToDefault` Redis "not-a-number" → fallback 15 -- `getPaymentReminderMinutes_redisNotPositive_useDefault` Redis "0" → fallback 15 - -## 修复后预期行为 - -### 创建订单流程 -1. 用户创建订单,订单状态 = PENDING_PAY -2. **不再发**任何"请尽快完成支付"立即短信 -3. 15 分钟(实际 20 分钟)后: - - 若订单仍 PENDING_PAY → 发 ORDER_PAYMENT_REMINDER 短信"请完成支付" - - 若订单已 PAID/CANCELLED/REFUNDED → 静默跳过(PaymentReminderConsumer 已有状态检查) - -### 时序保证 -- 15 分钟支付提醒 < 30 分钟过期取消(默认 `order.expiry.default-minutes=30`) -- 顺序正确,无回归 - -## 前端处理 - -**零影响**。前端无须任何改动: -- 用户不会再收到"立即创建"短信(本来就是后端发的,前端不感知) -- 15 分钟后未支付的延迟提醒仍走 ORDER_PAYMENT_REMINDER 模板,前端不感知 -- 订单详情/支付按钮等所有 API 行为无变化 - -## 后端部署 - -- ✅ `mvn compile -pl hl-order-service-v2 -am` 通过 -- ⏭️ 部署: 仅需重启 hl-order-service-v2 (4 个实例) 即可生效 -- 🎯 测试服回归: 创建测试订单不再立即收"请完成支付"短信; 创建后 15 分钟内不支付应收一条延迟提醒短信 - -## 配置 (运维可选) - -- 默认值已写在 `@Value` 里, 不依赖 Nacos / Redis 必有 key -- 若需动态调整: Redis 写 `order:config:payment-reminder-minutes` = `"20"` 或 `"30"` -- 测试 / 正式环境无需改 Nacos (默认即生效) - -## 影响面 (运营关注) - -- ORDER_CREATED 模板的 oa(公众号)/inapp(站内信)/miniapp(小程序订阅消息) 渠道全部不再触发 - (sql/notification_center_v2.sql 配置, sms 默认未启用) -- 不影响 ORDER_PAYMENT_REMINDER 模板(延迟链) -- 若产品后续要恢复"管理端代客创建后立刻给客户推一条 OA"的场景,建议另开独立 event_code(例 ADMIN_PROXY_ORDER_CREATED),与"已支付场景的延迟提醒"完全隔离 - -## 合并 - -- PR #1517 squash merge 到 dev (sha bec83b72) -- 关闭工单 #1516 diff --git a/changelogs/2026-04/28_fix_sql_id-card-type-varchar-extend.md b/changelogs/2026-04/28_fix_sql_id-card-type-varchar-extend.md deleted file mode 100644 index af42753..0000000 --- a/changelogs/2026-04/28_fix_sql_id-card-type-varchar-extend.md +++ /dev/null @@ -1,79 +0,0 @@ -# 修复:id_card_type 列长 VARCHAR(20)→VARCHAR(30) + 字典脏数据修订 (#1523 hotfix) - -**类型**: SQL hotfix (修补昨晚 PR #1523) -**关联**: PR #1526 / 修补 PR #1523 / 工单 #1522 仍在 -**日期**: 2026-04-28 -**影响范围**: hl_user_service 三张活跃表 ALTER + 字典 sys_dict_data UPDATE 2 条 - ---- - -## 背景 - -PR #1523 引入回乡证 enum value `HONGKONG_RESIDENT_PASS` (22 字符),但漏改 DB 列长。测试服回归立即测出: -``` -POST /user/traveler body={"idCardType":"HONGKONG_RESIDENT_PASS",...} -→ 400 "字段【id_card_type】内容过长,请删减后重试" -``` -HONGKONG_RESIDENT_PASS = 22 字符 > VARCHAR(20),三张活跃表写入失败。 - -## 修复 - -### 1. schema.sql 改 6 处 (含 legacy 表) -- `sql/traveler.sql` (traveler + traveler_ocr_log) VARCHAR(20)→(30) -- `sql/user_personal_info.sql` (user) -- `sql/hl_order_service.sql` (legacy v1 order_traveler) -- `sql/hl_insurance_service.sql` (legacy v1 insured_person) -- `sql/hl_contract_service.sql` (legacy v1 contract_traveler) - -### 2. 增量 SQL 必跑 (运维) -**V20260429__id_card_type_extend_to_varchar30.sql** (扩列): -```sql -USE hl_user_service; -ALTER TABLE traveler MODIFY COLUMN id_card_type VARCHAR(30) NOT NULL DEFAULT 'ID_CARD' COMMENT '...'; -ALTER TABLE traveler_ocr_log MODIFY COLUMN id_card_type VARCHAR(30) NOT NULL COMMENT '...'; -ALTER TABLE user MODIFY COLUMN id_card_type VARCHAR(30) DEFAULT 'ID_CARD' COMMENT '...'; -``` -idempotent,重复执行无害。 - -**V20260430__fix_id_card_type_dict_labels.sql** (修字典脏数据): -```sql -USE hl_user_service; -UPDATE sys_dict_data SET dict_label='港澳通行证', updated_at=NOW() - WHERE dict_data_id=80073 AND dict_value='HK_MACAU_PASS'; -UPDATE sys_dict_data SET dict_label='台湾通行证', updated_at=NOW() - WHERE dict_data_id=80074 AND dict_value='TAIWAN_PASS'; -``` - -为什么需要 V20260430:测试服 80073/80074 历史脏数据 dict_label 与字典口径错位 (80073 错标"回乡证" 与 80077 撞名,80074 错标"台胞证")。下拉框会出现两个"回乡证"引发用户混淆。 - -## 部署步骤 - -### 测试服 (运维已跑) -```bash -ssh root@1.182.108.58 -cd /opt/hulalv/HL && git pull -mysql -uroot -proot -h 192.168.100.236 hl_user_service < sql/V20260429__id_card_type_extend_to_varchar30.sql -mysql -uroot -proot -h 192.168.100.236 hl_user_service < sql/V20260430__fix_id_card_type_dict_labels.sql -``` - -### 正式环境 (待运维) -```bash -ssh root@<正式 DB 节点 Node1 47.105.108.0> -mysql -uhl_admin -p<密码> hl_user_service < /opt/hulalv/HL/sql/V20260429__id_card_type_extend_to_varchar30.sql -mysql -uhl_admin -p<密码> hl_user_service < /opt/hulalv/HL/sql/V20260430__fix_id_card_type_dict_labels.sql -``` - -注: hl-user-service / hl-order-service-v2 **无需重启**,schema 改动 ALTER 后即时生效。 - -## Phase 2 待办 - -legacy 库 `hl_contract_service.contract_traveler` / `hl_insurance_service.insured_person` 已逻辑废弃 v2 化,本 PR 不发增量 SQL (避免误执行 v1 库)。如确认 legacy 库仍有写入,后续补独立 V*.sql。 - -## 经验沉淀 - -`memory/experience/backend-dev/new-enum-value-check-column-length.md`: 新增枚举字符串值前必先 grep schema.sql 列长度。**单测 Mockito mock DB 不踩真 SQL,字段长度问题永远不会暴露,必须本地+测试服真插入才能爆**。本次 PR #1523 直接漏掉这一步合并到 dev,被测试服 round-trip 立即翻盘。 - -## 合并 - -- PR #1526 squash merge 到 dev (sha ac54dd62) -- 工单 #1522 (PR #1523 母工单) 仍在,等运营 SQL 部署 + 前端补下拉 + 12301 联调真实回乡证号 diff --git a/changelogs/2026-04/30_feat_contract-scheme_dispute-fields.md b/changelogs/2026-04/30_feat_contract-scheme_dispute-fields.md deleted file mode 100644 index 32e5c75..0000000 --- a/changelogs/2026-04/30_feat_contract-scheme_dispute-fields.md +++ /dev/null @@ -1,210 +0,0 @@ -# 新增:合同方案补充仲裁机构/管辖法院字段 + 12301 dispute 节点完整化 - -**类型**: 后端 FEAT(新增字段+老 BUG 修复) -**关联**: 工单 #1561 / PR #1565 (合并到 dev sha `d3190de5`) -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台 → 合同方案管理 → 编辑合同方案弹窗 → 争议解决方式 - ---- - -## 业务背景 - -管理后台合同方案编辑页(`web.test.1814.love:9443/contract/scheme`),用户截图反馈:**选择"仲裁/诉讼"时必须填对应地点,合同 PDF 模板里要用**。 - -排查发现: -- 12301 平台 `dispute.tribunalName` 字段已支持,但 `ContractCreateService.assembleParam` **从未把 scheme.tribunalName 透传过去** → 合同 PDF 仲裁条款常年是空模板(老 BUG) -- 合同方案表 `contract_scheme` 没有诉讼地点字段 -- `disputeResolution` 注释在不同代码处自相矛盾(`ContractSchemeRequest` 1=仲裁/2=诉讼 vs `ContractApplyParam` 1=诉讼/2=仲裁) - -经过 4 轮 PM 整改 + 4 轮评审委员会评审(综合 9.925/10)+ 架构师勘误 + dev 编码,本次 PR 一并解决。 - ---- - -## ⚠️ 关键:disputeResolution 语义统一为 1=诉讼 / 2=仲裁 - -**原 `ContractSchemeRequest` 注释 "1=仲裁 2=诉讼" 写反了**,本次后端统一以 12301 平台真值为准: - -| 值 | 含义 | -|---|---| -| 1 | 诉讼 (litigation) | -| 2 | 仲裁 (arbitration) | - -**前端 hl-ui 字典 `dispute_resolution` 渲染如原按 "1=仲裁" 请翻转**,否则用户选错语义。 - -测试服 DB 现存方案数据已经按 1=诉讼/2=仲裁 自洽(scheme_id=3 dispute=1 国内冬季诉讼;scheme_id=2046840448906940417 dispute=2 仲裁,均合理)— 确认 ContractApplyParam 注释才是真值。 - ---- - -## 后端改动概要 - -### 1. 字段 -`contract_scheme` 表增量加 2 列(已在测试服 DDL 落地): - -```sql -ALTER TABLE contract_scheme - ADD COLUMN tribunal_name VARCHAR(100) NULL COMMENT '仲裁机构名称(disputeResolution=2 仲裁时必填)', - ADD COLUMN litigation_court VARCHAR(100) NULL COMMENT '管辖法院(disputeResolution=1 诉讼时必填)'; -``` - -### 2. ReqVO / RespVO - -`ContractSchemeRequest` / `ContractSchemeVO` 加 2 字段: - -```java -@ApiModelProperty(value = "仲裁机构名称(disputeResolution=2 时必填)", example = "北京仲裁委员会") -@Size(max = 100, message = "仲裁机构名称长度不能超过 100 个字符") -private String tribunalName; - -@ApiModelProperty(value = "管辖法院(disputeResolution=1 时必填)", example = "北京市朝阳区人民法院") -@Size(max = 100, message = "管辖法院长度不能超过 100 个字符") -private String litigationCourt; -``` - -### 3. 校验 -联合校验在 Service 层(VO 层不加 `@NotBlank`,因为依赖 disputeResolution 值组合): - -| 场景 | 校验 | 错误码 | 业务码 | -|---|---|---|---| -| disputeResolution=2(仲裁)缺 tribunalName | 拦截 | `SCHEME_TRIBUNAL_NAME_REQUIRED` | **510216** | -| disputeResolution=1(诉讼)缺 litigationCourt | 拦截 | `SCHEME_LITIGATION_COURT_REQUIRED` | **510217** | -| 反向字段(选仲裁但传了诉讼地点等)| 不强制清空 | - | - | - -### 4. 合同条款渲染 -`supplementaryClause` 拼接顺序改为: - -``` -[1] safetyNotice (安全告知书,平台标准条款) -[2] disputeClause (争议解决条款,本次新增) -[3] userClause (用户自定义补充约定) -``` - -`disputeClause` 文本格式(本期固定模板): -- 仲裁: "双方因履行本合同发生争议的,提交{tribunalName}仲裁解决。" -- 诉讼: "双方因履行本合同发生争议的,提交{litigationCourt}诉讼解决。" - -12301 dispute 节点也会按 resolution 路由对应字段: -- 2=仲裁 → 输出 `dispute.tribunalName` -- 1=诉讼 → 输出 `dispute.litigationCourt` - -腾讯电子签链路通过共享 `param.supplementaryClause` 自动同步获得 disputeClause 文本(后端零改动)。 - -### 5. 字符净化 -`tribunalName` / `litigationCourt` 拼入条款文本时净化 `\n / \r / \t` 为空格(防 12301 errcode=301025,经验来自 PR #1551 reason 字段事故)。 - ---- - -## 错误响应示例 - -创建/修改合同方案时,选择仲裁但未填仲裁机构: - -```jsonc -HTTP 200 (走业务错误码,非协议错误) -{ - "code": 510216, - "message": "争议解决方式为仲裁时,仲裁机构名称不能为空", - "data": null -} -``` - -诉讼缺管辖法院: - -```jsonc -{ - "code": 510217, - "message": "争议解决方式为诉讼时,管辖法院不能为空", - "data": null -} -``` - ---- - -## 前端要做的改动 ⚠️ - -### 1. 字典 `dispute_resolution` 翻转(关键) -原可能渲染: `1=仲裁, 2=诉讼` → 改为 **`1=诉讼, 2=仲裁`**(与后端一致)。 - -如不翻转,用户选"仲裁" UI 传 1,后端按"1=诉讼"处理 → 数据完全反向。 - -### 2. 编辑合同方案弹窗 — 条件输入框 -争议解决方式单选(仲裁/诉讼)下方,**动态显示**对应输入框: - -| 选中 | 显示输入框 | 必填 | maxlength | placeholder | -|---|---|---|---|---| -| 仲裁(value=2)| 「仲裁机构名称」 | ✅ 必填 | 100 | 请填写仲裁委员会全称,例:北京仲裁委员会 | -| 诉讼(value=1)| 「管辖法院」 | ✅ 必填 | 100 | 请填写约定管辖法院,例:北京市朝阳区人民法院 | - -### 3. 切换 resolution 不清空已填值 -后端两列独立存,允许保留(用户切换"仲裁→诉讼→仲裁"时,仲裁地点会保留)。 - -### 4. 提交字段名 -- `disputeResolution` (Integer) -- `tribunalName` (String) -- `litigationCourt` (String) - -### 5. 编辑旧方案兼容 -旧方案 `tribunalName/litigationCourt` 都为 null: -- 加载时不拦截,允许列表正常显示 -- 用户**点击保存时**按新规校验拦截(后端会返 510216/510217) - -### 6. 错误码字典 -| 业务码 | 含义 | -|---|---| -| 510216 | 仲裁机构名称必填 | -| 510217 | 管辖法院必填 | - ---- - -## 部署状态 - -- ✅ PR #1565 合并到 dev (sha `d3190de5`,2026-04-30 15:46) -- ✅ 测试服 DDL 已落 (V20260501 ALTER TABLE 添加 2 列) -- ⏳ Deploy Panel 部署 hl-order-service-v2 测试服(进行中,管理者跟踪) -- ⏳ 测试服 12301 + 腾讯电子签 round-trip 验证待执行 -- ⏳ Release dev → main 待用户拍板 - ---- - -## 测试服 round-trip 计划 - -**经网关 https://api.test.1814.love:9443**: - -1. POST `/admin/contract/scheme` `disputeResolution=2` 不带 `tribunalName` → 期望 510216 -2. POST `/admin/contract/scheme` `disputeResolution=1` 不带 `litigationCourt` → 期望 510217 -3. POST `/admin/contract/scheme` 仲裁带 tribunalName → 200 success,GET 详情验证字段回显 -4. PUT 同一方案改诉讼带 litigationCourt → 200,字段独立保留 -5. 真实下单走 12301 报送(仲裁场景)→ 验 dispute.tribunalName 输出 + supplementaryClause 含仲裁文本 -6. 真实下单走腾讯电子签(仲裁场景)→ 验 supplementaryClause form 字段含仲裁文本(跨平台一致性) - ---- - -## 单测 - -`mvn -pl hl-order-service-v2 -Dtest='ContractCreateServiceTest,TencentEsignRequestBuilderTest' test`: -- 84 tests,0 failures,0 errors -- 17 个新单测 (4 校验 + 8 corner case + 4 边界净化顺序隐藏改点 + 1 跨平台) - ---- - -## 不动 - -- ❌ 腾讯电子签模板 widget(运营在腾讯控制台改模板时联动) -- ❌ disputeResolution `int → Integer` 重构(本期不动) -- ❌ MP / 字典服务 / Feign / MQ / 状态机 / 缓存(本期纯 admin 配置项) -- ❌ 历史合同回填(运营 TODO SQL 附 PR body) - ---- - -## 运营 TODO(可选) - -历史方案补齐(运营评估后由运维管理员执行,**本 PR 不自动跑**): - -```sql --- 仲裁方案缺仲裁委员会 -SELECT scheme_id, name FROM contract_scheme - WHERE deleted_at IS NULL AND dispute_resolution = 2 AND (tribunal_name IS NULL OR tribunal_name = ''); - --- 诉讼方案缺管辖法院 -SELECT scheme_id, name FROM contract_scheme - WHERE deleted_at IS NULL AND dispute_resolution = 1 AND (litigation_court IS NULL OR litigation_court = ''); -``` diff --git a/changelogs/2026-04/30_feat_product_admin-min-price-api.md b/changelogs/2026-04/30_feat_product_admin-min-price-api.md deleted file mode 100644 index 3f39de0..0000000 --- a/changelogs/2026-04/30_feat_product_admin-min-price-api.md +++ /dev/null @@ -1,122 +0,0 @@ -# 新增管理端接口:产品最低价(用于编辑页"行程报价"预览) - -**类型**: 后端 FEAT(新增接口) + 前端切换通知 -**关联**: 工单 #1556 / PR #1558 / Release PR #1559 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台产品编辑页右侧"预览面板 → 行程报价"区域 - ---- - -## 现象(BUG) - -管理后台产品编辑页 (`web.test.1814.love:9443/product/edit?id=...`) 右侧预览面板的"行程报价"区域,**两个档位(舒适/高档)都显示 `¥-- 起/成人`**,即使 Step 4 定价管理已实际配置价格(用户截图: 平日价 ¥45,455 已落 product_price_calendar)。 - -## 根因 - -不是字段 BUG,详情接口 `/admin/product/item/{id}` 已通过 `PriceCalendarAggregator` 回填 startPrice/tierPrices, 但 3 个边界场景导致预览 ¥--: - -1. **全过期 calendar** 时 `keepEmptyTiers=false` 把无价档全过滤掉 -2. **`product.tiers` 配多档但 calendar 只配了 tier 1** → tier 2 在详情接口被剔除前端拿不到 -3. **详情接口 17 次 DB 读太重**, Step 4 改完价后预览不刷新 - -## 解法 — 新增专用轻量起价接口 - -```http -GET /admin/product/item/{productId}/min-price -Authorization: Bearer {adminToken} -``` - -### Response (`ProductMinPriceRespVO`) - -```jsonc -{ - "code": 0, - "message": "success", - "data": { - "productId": "2049468625294708737", - "productType": "CUSTOM", - "priceSource": "PRICE_CALENDAR", // PRICE_CALENDAR=价格日历, GROUP_BATCH=班期表 - "globalMinAdultPrice": 45455.00, // 全档汇总最低成人价(无价时 null) - "currency": "CNY", - "futurePriceFromDate": "2026-05-01", - "futurePriceToDate": "2026-05-31", - "hasMultiTier": true, // tiers.size > 1 - "tiers": [ - { - "tierSeq": 1, - "tierName": "舒适", - "tierDescription": "4钻酒店", - "minAdultPrice": 45455.00, // null 表示该档无未来可售价 - "priceFromDate": "2026-05-01", - "priceToDate": "2026-05-31" - }, - { - "tierSeq": 2, - "tierName": "高档", - "tierDescription": "5星酒店", - "minAdultPrice": null, // 未配置 → null,前端按 null 显 ¥-- - "priceFromDate": null, - "priceToDate": null - } - ] - } -} -``` - -### 字段说明 -- `productType` 字典 `product_type`: CORE=核心 / GROUP=小蒙马 / CUSTOM=私人定制 -- `priceSource` 字典(代码内): - - `PRICE_CALENDAR` — CORE/CUSTOM 走 `product_price_calendar`,按 tierSeq 分组取 MIN(adultSellPrice) - - `GROUP_BATCH` — GROUP 走 `group_tour_batch.adult_price` MIN -- 仅查未来可售(`date >= today` 且 `adultSellPrice > 0`) -- **保留所有档位**: 即使该档无价,`tiers[]` 里仍有该档的元素,`minAdultPrice=null` — 前端按 null 显 `¥--` 与列表语义一致 -- `globalMinAdultPrice` 是所有 tier 中非 null 价的全局 min,前端"整体起价"用 -- DB 读仅 2 次(产品主表 + 价格源),详情接口 17 次 - -### 错误码 -- `code=0` — 成功 -- `code=404` — 产品不存在或当前 admin 无 DataScope 权限(行级权限拦截) - -## 前端要做的改动 ⚠️ - -### 替换数据源 -`hl-ui` 中产品编辑页右侧 `MobilePreview.vue / PreviewPricing.vue` 等组件,把"行程报价"区的取价逻辑由"复用详情接口的 startPrice/tierPrices"改为**单独调用** `GET /admin/product/item/{id}/min-price`。 - -### 触发时机 -- 进入编辑页:产品基础信息加载完之后调一次 -- Step 4 定价管理保存成功后:**主动 refetch** `/min-price`(详情接口缓存了 17 次 DB 聚合,不会立刻反映改价;新接口 2 次 DB 读,可频繁刷) -- 切换 Step 时无需 refetch(价格不会因切 Step 变化) - -### 渲染规则 -- `data.tiers` 非空 → 按 `tierSeq` 排序逐档渲染 - - `minAdultPrice != null` → 显示金额 + "起/成人" - - `minAdultPrice == null` → 显示 `¥--` 起/成人(用户配置了该档位但未配价) -- `data.globalMinAdultPrice == null && data.tiers` 全 null → 整个面板都显 `¥--`(产品完全没配价) -- 不需要再走老的 `tierPrices/startPrice` 字段链路降级 — 新接口语义完整覆盖 - -### 测试场景(测试服已 round-trip 通过) -| 场景 | 接口返回 | 前端预期 | -|---|---|---| -| 双档全有价 | tiers[0].min=7960, tiers[1].min=7960, hasMultiTier=true | 两档都显 ¥7960 起 | -| 单档已配价 | tiers[0].min=1440, hasMultiTier=false | 一档显 ¥1440 起 | -| 双档配了 tier1 没配 tier2 | tiers[0].min=有价, tiers[1].min=null | 舒适显价 + 高档显 `¥--` | -| 全过期/未配价 | globalMinAdultPrice=null, tiers 全 null | 全档 `¥--` | -| GROUP 小蒙马 | priceSource=GROUP_BATCH, 价格从班期表取 MIN | 同 CORE 渲染 | - -### 接口参考产品(测试服) -- `2047268852147875842` — PUBLISHED CORE 双档舒适+品质,全 7960 -- `2046104743003971585` — DRAFT CORE 单档轻奢,1440 - -## 部署状态 - -- ✅ PR #1558 合并到 dev (sha 30904060) -- ✅ Deploy Panel task 1b109e5c success, 双实例 hl-product-service-v2:8083+8183 滚动重启完成 -- ✅ 测试服经网关 9443 round-trip 3 个产品全通过 -- ⏳ Release PR #1559 dev → main 待用户网页合,合后通知正式服务器管理员部署正式 - -## 向后兼容 - -- `/admin/product/item/{id}` 详情接口字段**完全不变**(仍返 `tierPrices/startPrice/priceCalendars`) -- 前端老的 `MobilePreview.vue / PreviewPricing.vue` 三级 fallback 链路不会因后端报错(只是仍显 ¥--) -- 切换可分阶段:先把"行程报价"区切到新接口,其他依赖 startPrice/tierPrices 的地方按需后切 diff --git a/changelogs/2026-04/30_feat_product_itinerary-place-poi-precision.md b/changelogs/2026-04/30_feat_product_itinerary-place-poi-precision.md deleted file mode 100644 index e31c9fc..0000000 --- a/changelogs/2026-04/30_feat_product_itinerary-place-poi-precision.md +++ /dev/null @@ -1,171 +0,0 @@ -# 行程编排集合地/解散地：行政区 → 高德 POI 精准定位 - -**类型**: 后端 FEAT(字段扩展+读路径增强) + 前端 picker 切换 + regeo 调用 -**关联**: 工单 #1563 / PR #1570 + follow-up 工单 #1574 / PR #1575（镇级行政区字段） -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台产品编辑页 Step 2「行程编排」→ DAY X 的「开始 / 结束」字段（即 `gatherPlace` / `dismissalPlace`） - -> ⚠️ **2026-04-30 16:25 update（PR #1575）**：行政区精度要求**到镇/街道级**。POI 自身只到区县，前端选 POI 后**必须额外调高德 regeo (逆地理编码)** 拿镇级数据。详见下方 schema 和 mmg 前端 mapping。 - ---- - -## 业务目的 - -集合地 / 解散地从「行政区」(如「海拉尔区」)升级为「精准 POI」(如「海拉尔东山国际机场 / 海拉尔火车站」)。前端 `gatherPlace/dismissalPlace` 选择器从行政区下拉换成**高德 POI Autocomplete**。 - -途经路线 (`routePoints`) 不在本次范围内（已是 lng/lat 结构）。 - ---- - -## JSON Schema 升级 - -### 新格式（POI 精准定位 + 镇级行政区，2026-04-30 起新数据按这个落库） - -```jsonc -{ - "name": "海拉尔东山国际机场", // POI 名称 - "address": "内蒙古呼伦贝尔市海拉尔区机场路", // 详细地址 - "location": { "lng": 119.825, "lat": 49.205 }, // POI 精确坐标 - "poiId": "B0FFGTEST1", // 高德 POI ID - "adcode": "150702", // 区县编码（POI 自带） - "provinceName": "内蒙古自治区", // 省（regeo addressComponent.province） - "cityName": "呼伦贝尔市", // 市（regeo addressComponent.city） - "districtName": "海拉尔区", // 区（regeo addressComponent.district） - "township": "东山街道", // 镇/街道（regeo addressComponent.township） - "towncode": "150702002000", // 镇编码（regeo addressComponent.towncode） - "fullPath": "内蒙古自治区/呼伦贝尔市/海拉尔区/东山街道" // 4 段（前端拼） -} -``` - -**关键点**：POI 本身（高德 PlaceSearch 返回）只到区县级 `adname`，**到镇级必须前端额外调高德 regeo (`AMap.Geocoder.getAddress`)** 拿 `addressComponent.{township, towncode}` 后 merge 到 gatherPlace JSON。 - -### 老格式（行政区，2026-04-30 之前已落库的存量数据，零迁移继续工作） - -```jsonc -{ - "name": "海拉尔区", - "level": "district", - "adcode": "150702", - "fullPath": "内蒙古自治区/呼伦贝尔市/海拉尔区", - "levelName": "区/县" -} -``` - -后端**同时兼容三种格式**： -- 新 POI 精准定位（含 `location`） -- 老行政区无 `center`（依赖 `adcode` 反查） -- 更早期行政区带 `center: 'lng,lat'`（直接 split） - ---- - -## mmg 前端要做的事（hl-ui 仓库） - -### 1. 替换 picker 组件 - -`src/views/product/edit/Step2*.vue` 行程编排 DAY X 块里，「开始」「结束」两个 `n-select` / 行政区 picker，**替换成高德 POI Autocomplete 输入框**。 - -参考高德 JS API：[`AMap.Autocomplete` + `AMap.PlaceSearch`](https://lbs.amap.com/api/javascript-api-v2/documentation#autocomplete)；输入关键字 → 用户选择 POI → 把 POI 数据组装成上面的新 JSON 结构。 - -### 2. 落库 JSON 字段映射（高德 POI → 后端字段） - -```js -// 选 POI 后，先用 location 调 regeo 拿镇级行政区，再 merge -function poiToPlace(poi, callback) { - const geocoder = new AMap.Geocoder(); - geocoder.getAddress([poi.location.lng, poi.location.lat], (status, result) => { - if (status !== 'complete') { - // 降级：regeo 失败时退回到 POI 自带数据（无 township/towncode） - callback({ - name: poi.name, - address: poi.address || '', - location: { lng: Number(poi.location.lng), lat: Number(poi.location.lat) }, - poiId: poi.id || '', - adcode: poi.adcode || '', - cityName: poi.cityname || '', - districtName: poi.adname || '' - // 此时 provinceName/township/towncode/fullPath 留空，后端兼容 - }); - return; - } - const ac = result.regeocode.addressComponent; - callback({ - name: poi.name, - address: poi.address || result.regeocode.formattedAddress, - location: { lng: Number(poi.location.lng), lat: Number(poi.location.lat) }, - poiId: poi.id || '', - adcode: poi.adcode || ac.adcode, - provinceName: ac.province || '', - cityName: (ac.city && ac.city.length) ? ac.city : '', // 直辖市 city 是空数组 - districtName: ac.district || '', - township: ac.township || '', - towncode: ac.towncode || '', - fullPath: [ac.province, ac.city, ac.district, ac.township].filter(s => s && s.length).join('/') - }); - }); -} -``` - -### 3. PUT 行程接口 - -接口路径不变：`PUT /admin/product/item/{productId}/itinerary`，`days[].gatherPlace` / `days[].dismissalPlace` 用上面的新 JSON 结构。后端字段全保留（向后兼容）。 - -### 4. 详情回显 - -`GET /admin/product/item/{productId}` 的 `data.itinerary[i].gatherPlace` / `dismissalPlace`： -- **新数据**：包含 `name / address / location / poiId / adcode / cityName / districtName`（7 字段全在） -- **老数据**：包含 `name / level / adcode / fullPath / levelName`（5 字段） -- 前端组件渲染时按字段存在性切换：有 `location.lng` 就用 POI 模式回显；否则按老行政区回显（兼容期） - ---- - -## 后端测试服 round-trip（已完成） - -测试服部署：commit `982558f9` 已部署 hl-product-service-v2 + hl-order-service-v2 双实例。 - -```bash -# 1) 老格式产品 GET 详情 → PlaceItem 老字段完整回显（零回归） -GET /admin/product/item/2047268852147875842 -→ day1.gatherPlace = {"name":"海拉尔区","level":"district","adcode":"150702","fullPath":"内蒙古...","levelName":"区/县"} ✅ - -# 2) PUT 新 POI 格式 → GET 详情回显 7 字段全在 -PUT /admin/product/item/{draftId}/itinerary - body: { days:[{ gatherPlace:{name,address,location:{lng,lat},poiId,adcode,cityName,districtName} }] } -→ HTTP 200 「行程保存成功」 -GET → day1.gatherPlace 7 字段完整含 location.lng=119.825/lat=49.205 ✅ - -# 3) 同 day 混合格式 (gather=POI, dismiss=老) 兼容 -→ 两边各自字段完整回显，互不干扰 ✅ -``` - ---- - -## 后端改动（参考） - -13 个文件 +846 / -48，PR #1570： - -- `InternalProductDetailVO.PlaceItem` + `ProductDetailVO.PlaceItem` (Feign 镜像) **扩展 7 个 POI 字段 + 嵌套 Location 静态类**，旧字段保留兼容 -- `MpProductRouteMapService.parsePlaceVO`：路径优先级 `location → center → adcode 反查` -- `AmapDrivingService.parseCenterToLngLat`：同上优先级 -- `TeamReportService.parseCityFromSnapshot`：取城市优先 `cityName/districtName`，回退 `fullPath` -- VO 注释批量升级三种格式说明 -- 单测 +13（含 Hutool BeanUtil 嵌套 Map → Location 运行时验证） -- DB schema 不变（仍是 JSON 列） -- 老数据零迁移 - ---- - -## 风险 / 兼容性 - -- **零回归承诺**：老行政区数据继续按原行为工作（路线图 origin/destination / 每日里程 / 团报城市 全部正常） -- **新旧混合期**：同一产品 itinerary 不同 day 可以混存新 POI / 老行政区结构，互不影响 -- **降级**：POI 缺 `location` 时自动回退到 `adcode` 反查中心点（高德 API），与现行 `MpProductRouteMapService` 老路径一致 - ---- - -## 联调建议 - -mmg 前端改完后： -1. 本地起 mock 服务返回新 POI 结构，验证组件回显 -2. 接到测试服 `api.test.1814.love:9443` 后端，PUT → GET round-trip 验证字段对齐 -3. 看路线图 / 团报 / 每日里程，确认坐标用的是 POI 精确坐标（比之前 adcode 中心点更精准） diff --git a/changelogs/2026-04/30_feat_product_supplement-fee-icon-svg.md b/changelogs/2026-04/30_feat_product_supplement-fee-icon-svg.md deleted file mode 100644 index 7d1bb07..0000000 --- a/changelogs/2026-04/30_feat_product_supplement-fee-icon-svg.md +++ /dev/null @@ -1,144 +0,0 @@ -# 新增: 产品「补充信息」费用包含/费用不含项支持图标(SVG)字段 - -**类型**: 后端字段扩展 -**关联**: 工单 #1572 / PR #1573 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台「产品编辑 → 补充信息 → 费用说明 →『费用包含』/『费用不含』」每一项的图标 - ---- - -## 背景 - -产品编辑页 → 补充信息 → 费用说明 →「费用包含」/「费用不含」每一项前面有「选择」按钮(IconPicker),用户选完图标后**保存草稿/重新打开页面图标丢失**。 - -**根因**:后端 `product_fee_item` 表 / VO / DO 没有 icon 字段,前端选择无处落库。 - -## 字段设计 - -- DB 列类型 **TEXT**(可装完整 `<svg viewBox="..."><path d="..."/></svg>` 字符串,也兼容短 code) -- 字段命名 `icon` -- 注释:`图标SVG字符串(前端图标库选中后存完整<svg>...</svg>内容,可空)` -- 自动生成接口 `feeDeductionPreview` 返回项 `icon` **恒为 null**,由前端选完 SVG 后保存(后端**不硬编码**默认 lucide code) - -## 改动 - -`hl-product-service-v2`: - -| 文件 | 改动 | -|------|------| -| `entity/ProductFeeItemDO.java` | +`String icon` 字段 | -| `vo/admin/ProductSupplementSaveReqVO.FeeItem` | +`String icon` 字段 | -| `vo/admin/ProductDetailRespVO.FeeItemVO` | +`String icon` 字段 | -| `vo/admin/FeeDeductionPreviewVO` | +`String icon` 字段(默认 null) | -| `service/admin/ProductValidationService.feeDeductionPreview()` | icon 不再填默认值 | -| `src/main/resources/schema.sql` `product_fee_item` 表 | +`icon TEXT NULL` 列 | -| `sql/V20260430__product_fee_item_add_icon.sql` | 增量 migration | - -## 影响接口 - -| 方法 | 路径 | 改动 | -|------|------|------| -| PUT | `/admin/product/item/{id}/supplement` | `includedFees[*]` / `excludedFees[*]` / `customFees[*]` **新增可选字段 `icon` (String)** | -| GET | `/admin/product/item/{id}` | `includedFees[*]` / `excludedFees[*]` / `customFees[*]` **新增字段 `icon` (String,可能为 null)** | -| GET | `/admin/product/item/{id}/fee-deduction-preview` | 响应项 **新增字段 `icon` (String,自动推导时恒为 null)** | - -请求字段全部**可选** (前端不传 `icon` 表示不变更),响应字段**总是出现**(可能为 null)。 - -## 请求 / 响应示例 - -### 请求(PUT supplement) - -```jsonc -PUT /admin/product/item/{id}/supplement -{ - "includedFees": [ - { - "feeType": "门票", - "name": "门票", - "icon": "<svg viewBox=\"0 0 24 24\"><path d=\"M5 5h14v14H5z\"/></svg>", - "sortOrder": 1 - }, - { - "feeType": "住宿", - "name": "住宿", - "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M3 7h18\"/><circle cx=\"7\" cy=\"12\" r=\"2\"/></svg>", - "sortOrder": 2 - } - ], - "excludedFees": [ - {"feeType": "个人消费", "name": "个人消费", "icon": "<svg viewBox=\"0 0 24 24\"><path d=\"M12 8v8\"/></svg>", "sortOrder": 1} - ] -} -``` - -### 响应(GET detail) - -```jsonc -{ - "code": 200, - "data": { - "includedFees": [ - {"feeType": "门票", "name": "门票", "icon": "<svg viewBox=\"0 0 24 24\"><path d=\"M5 5h14v14H5z\"/></svg>", "sortOrder": 1}, - ... - ], - "excludedFees": [...] - } -} -``` - -## 前端要做的改动 - -### 1. 新增字段类型扩展 - -`includedFees` / `excludedFees` / `customFees` 数组的 item 类型增加可选 `icon: string | null`。 - -### 2. IconPicker 组件 v-model 双向绑定 `item.icon` - -`hl-ui/src/views/product/edit/components/supplement/CostDescPanel.vue` 已经使用 `store.productData.includedFees / excludedFees`,补 IconPicker 时: - -```vue -<IconPicker v-model="item.icon" /> -``` - -IconPicker 选中图标后产出 SVG 字符串(`<svg>...</svg>`),写入 `item.icon`,保存接口透传。 - -### 3. 渲染时显示图标 - -```vue -<span v-if="item.icon" class="included-card__icon" v-html="item.icon"></span> -``` - -`v-html` 直接渲染 SVG 字符串(因 SVG 内容由后端管理员存储,不来自终端用户,XSS 风险可控)。 - -### 4. 图标库选完即保存 - -IconPicker 内已有图标集合(`flame / ticket / hotel / bed / utensils / coffee / plane / car / bus / train-front / ship / bike / shield-check / star / crown / gem / heart / bookmark / tag / gift / percent / hourglass / alarm-clock / bell / lock / zap / sparkles / rocket` 等共约 150 个),选中后用 lucide-vue-next 渲染对应组件 → 拿 outerHTML 序列化为 SVG 字符串 → 写入 `item.icon`。 - -### 5. 自动生成的项 icon 是 null - -「根据行程自动生成」按钮的返回项 `icon` **总是 null**,前端补 UI 时: -- card 默认显示「选择」占位按钮(已在原型里) -- 用户点击「选择」展开 IconPicker → 选中后写入 `item.icon` → 用户点保存按钮触发 PUT supplement 落库 - -## 测试覆盖 - -`mvn test -pl hl-product-service-v2`:1026/1026 全绿。 -新增 4 条 `@ExtendWith(MockitoExtension.class)` 单测覆盖:保存 SVG 透传 / 保存 null / 自动生成 icon 全 null / 兼容旧数据。 - -测试服 round-trip 验证(产品 `2043722892864000001` DRAFT): -- PUT supplement 携带 SVG icon → 200 OK -- GET detail 返回 icon 与发送字符串**完全一致**(含 viewBox / xmlns / path 全部保留) - -## 兼容性 - -- DB 列允许 NULL,旧数据 `icon=NULL` 读取正常 -- VARCHAR(64)→TEXT 是放大方向,MySQL 自动兼容 -- TEXT 列可存任意长度字符串,前端发短 code(如 `"ticket"`)也能正常存取 -- MyBatis-Plus `updateById` 默认 `FieldStrategy.NOT_NULL`,前端不传 `icon` 不会清空已存值 - -## 部署状态 - -- ✅ 测试服 DB `product_fee_item` 已 ALTER ADD COLUMN icon TEXT NULL(2026-04-30 16:33) -- ✅ Deploy Panel 已部署测试服 hl-product-service-v2(2026-04-30 16:35) -- 正式环境暂未发布(等 dev → main release PR + 同步 DDL) diff --git a/changelogs/2026-04/30_fix_approval_resource-reason-newline-and-detail-url-order.md b/changelogs/2026-04/30_fix_approval_resource-reason-newline-and-detail-url-order.md deleted file mode 100644 index 996a237..0000000 --- a/changelogs/2026-04/30_fix_approval_resource-reason-newline-and-detail-url-order.md +++ /dev/null @@ -1,92 +0,0 @@ -# 修复:资源(酒店/景点/活动等)启用禁用审批提交全部失败 - -**类型**: 后端 BUG 修复 -**关联**: 工单 #1550 / PR #1551 -**日期**: 2026-04-30 -**影响范围**: 管理后台资源(酒店/景点/活动/餐厅/车辆/服务/备品/员工/成本/房型) 申请上架/下架审批 - ---- - -## 现象 - -管理后台 `web.test.1814.love:9443/hotel/list` 等所有资源管理页点击「申请上架/申请下架」全部报: -``` -提交审批失败: Failed to submit approval to enterprise WeChat -``` - -后端日志(企微返回): -``` -ERROR WechatApiClient - WeChat oa/applyevent error: errcode=301025, errmsg=get approval param error:Text-1771171809841 -``` - -近 30 天 user-service 日志中**没有任何一条 "Approval submitted" 成功记录** — 也就是说资源审批从未成功过。 - -## 根因(双层) - -### 第 1 层:reason 含换行符 - -10 个 resource service(Hotel/RoomType/Scenic/Activity/Restaurant/Vehicle/ServiceItem/Staff/Supplies/CostItem)拼接审批理由时统一用了: -```java -dto.setReason((reason != null ? reason + "\n" : "") + "查看详情: " + dto.getDetailUrl()); -``` - -但企微 OA 模板 `C4ehNuudNWL8zXJBoApGCUEgu8knjyprtkKiRLkET` 的 reason 控件 `Text-1771171809841` 经 `gettemplatedetail` 接口验证实际是 **Text(单行)**,不允许换行符 `\n`。 - -### 第 2 层:setReason 顺序在 setDetailUrl 之前 - -10 个 service 中有 8 个的代码顺序: -```java -dto.setReason(... + "查看详情: " + dto.getDetailUrl()); // ← 此时 detailUrl 还是 null -dto.setDetailUrl(...); -``` - -reason 末尾拼接的 `dto.getDetailUrl()` 调用时 detailUrl 还没 set,实际拼出的是: -``` -<用户输入>\n查看详情: null -``` - -## 修复内容 - -### 1. `InternalApprovalController.java:441` 保持 `buildTextControl` - -(本次同时 revert 了昨日 PR #1549 的错误改动 `buildTextareaControl`,因为企微模板真实定义就是 Text 单行) - -### 2. 10 个 resource service 拼接 reason 改为空格 - -```java -dto.setDetailUrl(detailUrlPrefix != null && !detailUrlPrefix.isEmpty() - ? detailUrlPrefix + xxxId : ""); -dto.setReason((reason != null ? reason + " " : "") + "查看详情: " + dto.getDetailUrl()); -``` - -变更点: -- `\n` → 空格(避免 Text 单行控件不收换行符) -- `setDetailUrl` 提前到 `setReason` 之前(保证 reason 末尾拼到的 detailUrl 不是 null) - -### 3. 单测覆盖 - -`InternalApprovalControllerTest.submitApproval_resourceReason_useTextControl`:用 ArgumentCaptor 抓 controls 列表,断言资源审批的 reason 控件 `control == "Text"` 且 value 不含 `\n`,防回归。 - -## 修复后行为 - -测试服 round-trip(用 wx 账号 enterpriseWechatId=842)4 种资源 + 申请上架,4 次全部成功提交到企微 OA: - -| 资源类型 | 操作 | 结果 spNo | -|---------|------|-----------| -| hotel | 申请上架 | 202604300001 | -| activity | 申请上架 | 202604300002 | -| restaurant | 申请上架 | 202604300003 | -| supplies | 申请上架 | 202604300004 | - -后端日志全部为 `INFO Approval submitted: sp_no=...`,无任何 301025 错误。 - -## 前端处理 - -**零影响**。前端无须改动 — 提交审批接口签名/响应结构完全没变,前端只看 `code/message/data.spNo`,原本对错误的处理逻辑也无变化(成功/失败分支都对)。 - -## 部署状态 - -- ✅ PR #1551 合并到 dev (sha feb248c3) -- ✅ 测试服 hl-user-service 8081/8181 滚动重启 -- ✅ 测试服 hl-resource-service 8082/8182 滚动重启 -- ✅ Round-trip 4 种资源类型「申请上架」全部成功 diff --git a/changelogs/2026-04/30_fix_feign_product-service-v2-rename.md b/changelogs/2026-04/30_fix_feign_product-service-v2-rename.md deleted file mode 100644 index dabb5fa..0000000 --- a/changelogs/2026-04/30_fix_feign_product-service-v2-rename.md +++ /dev/null @@ -1,73 +0,0 @@ -# 修复:资源「申请下架」HTTP 503 错误(ProductFeignClient 服务名遗漏改名) - -**类型**: 后端 BUG 修复 -**关联**: 工单 #1553 / PR #1554 / Release PR #1555 -**日期**: 2026-04-30 -**影响范围**: 所有资源(酒店/景点/活动/餐厅/车辆/服务/备品/员工/成本/房型) 的「申请下架」功能,及产品审批通过/驳回回调链路 - ---- - -## 现象 - -正式 + 测试环境管理后台对任意酒店点「申请下架」均报: -``` -服务暂时不可用，请稍后重试 (HTTP 503) -``` - -后端日志: -``` -WARN GlobalExceptionHandler - Feign call failed: status=503, -[ProductFeignClient#checkResourceInUse(...)]: -[Load balancer does not contain an instance for the service hl-product-service] -``` - -## 根因 - -正式 + 测试 Nacos 实际注册的产品服务名是 **`hl-product-service-v2`**(v1→v2 重命名后)。但仓库里 2 个 FeignClient 仍写旧名 `hl-product-service`(重命名时遗漏),Feign 解析失败 → 503。 - -### 影响清单 - -| 文件 | 错处 | 用途 | -|------|------|------| -| `hl-resource-service/.../ProductFeignClient.java:10` | `name="hl-product-service"` | 资源申请下架时检查产品占用 | -| `hl-common-feign/.../ProductApprovalFeignClient.java:9` | 同上 | 产品审批通过后回调推送给 product-service | - -参照对比仓库其他模块均已用对的名: -- `hl-order-service-v2/.../ProductFeignClient.java`:`hl-product-service-v2` ✅ -- `hl-mp-service/.../MpProductFeignClient.java`:`hl-product-service-v2` ✅ -- `hl-mp-service/.../MpProductV2FeignClient.java`:`hl-product-service-v2` ✅ - -### 间接影响(隐藏更久) - -`ProductApprovalFeignClient.handleApprovalResult` 是企微审批通过后回调通知 product-service 处理产品 status 变更的链路。它的 fallback factory 直接吞错返回 `Result.error`(不抛异常),业务侧不感知。所以这条链路实际坏了一段时间,产品上架/下架审批通过后 status 可能没真更新,本次顺手一起修了。 - -## 修复 - -2 个文件 2 行,统一改为 `name = "hl-product-service-v2"`,与同仓其他模块对齐。 - -## 修复后行为 - -### 测试服 round-trip - -``` -hotelId=3001000000000000001 海拉尔洲季酒店 -申请下架 (targetStatus=0) → code=200, spNo=202604300006 -``` - -### 正式部署 - -- ✅ Image tag `c598641e` (main HEAD) -- ✅ 4 个 Pod (user×2 + resource×2) 全部 Running 1/1 -- ✅ 启动日志无 ERROR/Exception/FATAL -- ✅ Gateway → resource API 200 - -## 前端处理 - -**零影响**。前端无须改动。 - -## 部署状态 - -- ✅ PR #1554 合并到 dev (sha 11672364) -- ✅ Release PR #1555 合并到 main (sha c598641e) -- ✅ 测试服 hl-resource-service + hl-user-service 滚动重启 + round-trip 通过 -- ✅ 正式环境 K8s deploy 滚动更新完成 (deploy panel #50 + #51) diff --git a/changelogs/2026-04/30_fix_insurance_company-name-fallback.md b/changelogs/2026-04/30_fix_insurance_company-name-fallback.md deleted file mode 100644 index 2d3045f..0000000 --- a/changelogs/2026-04/30_fix_insurance_company-name-fallback.md +++ /dev/null @@ -1,91 +0,0 @@ -# 修复:保险产品列表「保险公司」列空白,降级到默认承保方 - -**类型**: 后端 BUG 修复 + 配置补丁 -**关联**: 工单 #1544 / PR #1545 -**日期**: 2026-04-30 -**影响范围**: 管理后台保险产品列表展示;后续保游网产品同步流程 - ---- - -## 现象 - -管理后台 `web.test.1814.love:9443/insurance/products` 列表「保险公司」列对所有产品(山河令、保游未来星、平安保游万里行、保游天下平安自驾游、平安快乐旅程III、签证宝等)全部空白,投保年龄/保障天数也都是 `-`。 - -API `GET /admin/insurance/products` 返回 `"insurerName":null,"companyName":null`。 - -## 根因 - -保游网 `/ApiProduct/v2/GetProductList` 接口仅返回 `{Guid, Isjw, Isjssx, ProductName}` 4 个字段,**不返回 CompanyName / ProductType / MinDays / MaxDays / MinAge / MaxAge**。 - -DB `insurance_product` 表 raw_json 列实证: -```json -{"Guid": "FAB0BF91...", "Isjw": 20, "Isjssx": 20, "ProductName": "保游天下..."} -``` - -`InsuranceManageService.mapProductFields()` 试图取这些字段,全部 null,sync 时把 NULL 写入 DB 各列。 - -GetPlanList / GetPlanRateList 的 raw_json 也无 CompanyName,已穷举保游网 3 个产品相关 API 确认无该字段。 - -## 业务事实(用户确认) - -保游网即亚太财险保险有限公司销售渠道,所有保游产品承保方均为「亚太财险保险有限公司」(固定值)。 - -## 修复内容 - -### 1. BaoyouApiProperties 新增 defaultCompanyName 字段 -```java -/** 保游网产品默认承保方名称(保游网 GetProductList 不返回 CompanyName,固定为亚太财险保险有限公司) */ -private String defaultCompanyName; -``` - -### 2. mapProductFields 缺失/空白时降级 -```java -String companyName = getTextSafe(item, "CompanyName"); -if (companyName == null || companyName.isBlank()) { - companyName = baoyouApiProperties.getDefaultCompanyName(); -} -product.setCompanyName(companyName); -``` - -### 3. nacos test namespace 同步推送 -`hl-order-service-v2-test.yml` `baoyou.api` 段新增: -```yaml -default-company-name: "亚太财险保险有限公司" -``` -仓库 `nacos-config/hl-order-service-dev.yml` 同步加(防初始化漂移)。 - -### 4. 单测覆盖 3 条分支 -- `mapProductFields_companyNameMissing_fallsBackToDefault` 缺失字段降级 -- `mapProductFields_companyNamePresent_useFromJson` 兼容性场景用真实值 -- `mapProductFields_companyNameBlank_fallsBackToDefault` 空字符串等同缺失 - -50/50 单测全绿。 - -## 修复后行为 - -### 数据库写入 -新 sync 触发后,`insurance_product.company_name` 列从 NULL → 「亚太财险保险有限公司」。 - -### 历史数据回填 -9 条已有 NULL 行需触发一次「同步产品」按钮 round-trip 一次性回写。 - -### 接口返回 -`/admin/insurance/products` 响应中 `companyName` 与 `insurerName` 两字段均返回「亚太财险保险有限公司」(VO 双通道 v1 兼容)。 - -## 前端处理 - -**零影响**。前端无须改动: -- 列表表格已绑 `companyName` / `insurerName` 字段,后端返回真实值即正常显示 -- 字段名不变、字段类型不变、字段数量不变 - -## 待修(下次迭代) - -投保年龄(`minAge`/`maxAge`) 与保障天数(`minDays`/`maxDays`) 当前同样为 NULL,因保游网 GetProductList 不返回。需要接保游网详情接口(暂不知接口名)或从 InsuranceRate 的 raw_json 聚合(BeginAge/EndAge/DayRange)推算。本次不做。 - -## 部署状态 - -- ✅ PR #1545 合并到 dev (sha 8f29d4b9) -- ✅ 测试服 nacos `hl-order-service-v2-test.yml@test` 已同步 default-company-name -- ✅ 测试服后端已部署 hl-order-service-v2 -- ✅ 管理端「同步产品」按钮 round-trip 验证通过 -- ✅ 管理后台列表「保险公司」列显示「亚太财险保险有限公司」 diff --git a/changelogs/2026-04/30_fix_product_fee-deduction-dedupe-and-name.md b/changelogs/2026-04/30_fix_product_fee-deduction-dedupe-and-name.md deleted file mode 100644 index 6c2ec8c..0000000 --- a/changelogs/2026-04/30_fix_product_fee-deduction-dedupe-and-name.md +++ /dev/null @@ -1,123 +0,0 @@ -# 修复: 费用包含按名字去重 + name 字段填具体景区/活动/酒店名 - -**类型**: 后端 BUG 修复(PR #1568 follow-up) -**关联**: 工单 #1576 / PR #1577 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台「产品编辑 → 补充信息 → 费用说明 →『根据行程自动生成』」按钮 - ---- - -## 背景 - -PR #1568 已修复「自动生成」漏景区/活动/酒店的问题(每节点 1 条 + 追加酒店),但用户使用后反馈 2 个新问题: - -### 问题 1: 同名条目重复 - -同一酒店多天住就出现多次 — 产品 `2045018534152478721`「游牧的森林·南线经典」自动生成 35 条结果中: -- 「海拉尔洲季酒店」出现 **11 次**(11 天住同一酒店) -- 「呼伦贝尔香格里拉大酒店」出现 **4 次** -- 「额尔古纳玖成万豪水汇智能酒店」出现 **4 次** -- 27 条住宿真实只有 **9 家不同酒店** - -### 问题 2: `name` 字段无信息量 - -三种类型(景区/活动/酒店)的 `name` 字段都填 `feeType` 标签 — 即: -- 6 条门票项 `name` 都是 `"门票"`(实际景区名是黑山头/白桦林景区/莫日格勒河等) -- 27 条住宿项 `name` 都是 `"住宿"`(实际酒店名各不同) - -前端中间 label 区域显示重复的 chip 文字,无信息量。 - -## 修复 - -`hl-product-service-v2` `ProductValidationService.feeDeductionPreview()`: - -### 1. 按名字去重 - -```java -LinkedHashSet<String> seenNodeNames = new LinkedHashSet<>(); -for (ProductItineraryNodeDO node : sortedNodes) { - String nodeName = node.getNodeName(); - if (nodeName == null || nodeName.isBlank()) continue; - if (!seenNodeNames.add(nodeName)) continue; // ← 按名字去重 - result.add(...); -} - -LinkedHashSet<String> seenHotelNames = new LinkedHashSet<>(); -for (ProductDayHotelDO hotel : sortedHotels) { - String hotelName = hotel.getHotelName(); - if (hotelName == null || hotelName.isBlank()) continue; - if (!seenHotelNames.add(hotelName)) continue; - result.add(...); -} -``` - -`LinkedHashSet` 保留**首次出现**(行程顺序里第一次见到该名字的那条)。 - -### 2. `name` 字段填具体名 - -| 字段 | 改前 | 改后 | -|---|---|---| -| `feeType` | 门票/活动/住宿/餐饮/交通 | **不变**(前端 chip 用) | -| `name` | 同 feeType | **节点名/酒店名** | -| `sourceNodeName` | 节点名/酒店名 | **不变**(与 name 同值) | -| `icon` | null | **不变**(PR #1573 行为) | - -## 影响接口 - -| 方法 | 路径 | 改动 | -|------|------|------| -| GET | `/admin/product/item/{id}/fee-deduction-preview` | 数组**长度变短**(去重),每项 `name` 改为具体名,其他字段语义不变 | - -请求签名完全不变,响应字段不变。 - -## 响应示例 - -```jsonc -GET /admin/product/item/2045018534152478721/fee-deduction-preview -{ - "code": 200, - "data": [ - /* 6 门票 */ - {"feeType": "门票", "name": "黑山头", "source": "AUTO", "sourceNodeName": "黑山头", "icon": null}, - {"feeType": "门票", "name": "白桦林景区", "source": "AUTO", "sourceNodeName": "白桦林景区", "icon": null}, - /* ... 共 6 条 */ - /* 2 活动 */ - {"feeType": "活动", "name": "ATV全地形越野车穿越", "source": "AUTO", "sourceNodeName": "ATV全地形越野车穿越", "icon": null}, - {"feeType": "活动", "name": "驯鹿拉车体验", "source": "AUTO", "sourceNodeName": "驯鹿拉车体验", "icon": null}, - /* 9 住宿(去重后,不再有重复) */ - {"feeType": "住宿", "name": "海拉尔洲季酒店", "source": "AUTO", "sourceNodeName": "海拉尔洲季酒店", "icon": null}, - /* ... 共 9 条 */ - ] -} -``` - -旧返回 35 条,新返回 **17 条**(6 门票 + 2 活动 + 9 住宿)。 - -## 前端要做的改动 - -**0 改动**。前端模板 `{{ item.name }}` 直接渲染就显示具体名字了。 - -`sourceNodeName` 字段值与 `name` 同值,如果前端模板里有 `← {{ item.sourceNodeName }}` 来源标签,会出现"门票 chip + 黑山头 + ← 黑山头"的视觉重复。前端**可选**: -- 保留来源标签作为视觉标识(用户已习惯) -- 或加 `v-if="item.sourceNodeName !== item.name"` 隐藏冗余 - -## 测试覆盖 - -`mvn test -pl hl-product-service-v2`: **1045/1045 全绿**。 - -新增 3 单测: -- `feeDeductionPreview_duplicateNodeNames_dedupedByName` — 5 个同名 SCENIC 节点 → result.size=1 -- `feeDeductionPreview_sameHotelMultipleDays_dedupedByName` — 11 个同酒店多天 → result.size=1 -- `feeDeductionPreview_nullOrBlankName_skipped` — null/空名字跳过 - -测试服 round-trip(产品 `2045018534152478721`)实测: -- 总计 **17 条**(6 + 2 + 9) -- 全部 `name` unique(去重生效) -- 全部 `name` 是具体名字(黑山头/ATV 全地形越野车穿越/海拉尔洲季酒店 等) -- 全部 `icon` null(PR #1573 行为不变) - -## 部署状态 - -- ✅ Deploy Panel 已部署测试服 hl-product-service-v2 双实例(2026-04-30 16:56) -- 正式环境暂未发布(等 dev → main release PR) diff --git a/changelogs/2026-04/30_fix_product_fee-deduction-display-label-no-prefix.md b/changelogs/2026-04/30_fix_product_fee-deduction-display-label-no-prefix.md deleted file mode 100644 index 510d77e..0000000 --- a/changelogs/2026-04/30_fix_product_fee-deduction-display-label-no-prefix.md +++ /dev/null @@ -1,126 +0,0 @@ -# 修复: 费用包含 feeType 改名 景区/游玩项目 + name 去前缀 - -**类型**: 后端 BUG 修复(PR #1579 双 follow-up) -**关联**: 工单 #1580 / PR #1581 + 工单 #1582 / PR #1583 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台「产品编辑 → 补充信息 → 费用说明 →『根据行程自动生成』」按钮 - ---- - -## 演进链(完整 5 PR) - -| PR | 行为 | 产品 2045018534152478721 返回 | -|---|---|---| -| #1568 | 修复漏景区/活动/酒店,每节点 1 条 | 35 条 | -| #1577 | 按名字去重,name 改具体名 | 17 条 | -| #1579 | 按 feeType 合并,name="门票：xxx" | 3 条(有 feeType 前缀) | -| **#1581** | feeType 改名 门票→景区,活动→游玩项目 | 3 条(name="景区：xxx") | -| **#1583** | name 去 feeType 前缀,只剩名字拼接 | 3 条(name="黑山头，...") | - -## 用户反馈 - -- 「怎么没分为 景区 游玩项目」(→ PR #1581:feeType 改名) -- 「不要我圈出来的直接显示名字就行」(→ PR #1583:name 去前缀) - -## 字段语义 - -| 字段 | 值 | -|---|---| -| `feeType` | **景区 / 游玩项目 / 住宿 / 餐饮 / 交通**(展示名,前端 chip 用) | -| `name` | `"黑山头，白桦林景区，莫日格勒河，..."` 仅名字拼接(中文「，」分隔) | -| `sourceNodeName` | null | -| `icon` | null(PR #1573 行为) | - -## 实现要点 - -```java -// PR #1581: 加 displayLabel 私有静态映射 -private static final Map<String, String> FEE_LABEL_DISPLAY = Map.of( - "门票", "景区", // 用户期望 - "活动", "游玩项目", // 用户期望 - "住宿", "住宿", - "餐饮", "餐饮", - "交通", "交通" -); - -// PR #1583: name 去前缀,直接 join -.map(e -> { - String displayLabel = toDisplayLabel(e.getKey()); - String joinedNames = String.join("，", e.getValue()); - return FeeDeductionPreviewVO.builder() - .feeType(displayLabel) // chip 用展示名 - .name(joinedNames) // 仅名字列表,无 feeType 前缀 - .source(SOURCE_AUTO) - .sourceNodeName(null) - .build(); -}) -``` - -**底层逻辑保持**: -- 分组 key 仍是 `feeLabel`("门票"/"活动"/"住宿"等) -- 排序 key 仍按 `feeLabel`(门票 → 活动 → 住宿 → 餐饮 → 交通) -- `feeIgnoredTypes` 过滤仍按 `feeLabel`(保护历史数据兼容) -- `NodeTypeEnum.getFeeLabel()` **不动**(防止影响别处) - -## 影响接口 - -| 方法 | 路径 | 改动 | -|------|------|------| -| GET | `/admin/product/item/{id}/fee-deduction-preview` | `feeType` 字段值改为展示名(景区/游玩项目),`name` 字段去掉前缀 | - -请求签名完全不变,响应字段不变。 - -## 响应示例 - -```jsonc -GET /admin/product/item/2045018534152478721/fee-deduction-preview -{ - "code": 200, - "data": [ - { - "feeType": "景区", - "name": "黑山头，白桦林景区，莫日格勒河，莫日格勒河断崖，呼伦湖,阿尔山火车站", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - }, - { - "feeType": "游玩项目", - "name": "ATV全地形越野车穿越,驯鹿拉车体验", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - }, - { - "feeType": "住宿", - "name": "海拉尔洲季酒店,呼伦贝尔香格里拉大酒店,额尔古纳玖成万豪水汇智能酒店,额尔古纳豪星酒店,额尔古纳白桦大酒店,海拉尔海棠酒店,满洲里饭店(百年俄式),敖根栖息地,阿尔善国际维景度假温泉酒店", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - } - ] -} -``` - -(注:实际中文逗号是「，」非半角) - -## 前端要做的改动 - -**0 改动**。前端 chip `{{ item.feeType }}` 显示「景区/游玩项目/住宿」,文字 `{{ item.name }}` 显示纯名字列表,UI 无重复无冗余。 - -## 测试覆盖 - -- PR #1581:`mvn test` 1047/1047 全绿,加 `feeDeductionPreview_displayLabelTranslation` 验证 SCENIC→景区 / ACTIVITY→游玩项目 映射 -- PR #1583:21 处 name 断言批量去前缀,`ProductValidationServiceTest` 53/53 全绿 - -测试服 round-trip(产品 `2045018534152478721`)实测: -- 3 条返回 -- feeType: 景区 / 游玩项目 / 住宿(顺序固定) -- name: 黑山头，白桦林景区，... / ATV全地形越野车穿越，驯鹿拉车体验 / 海拉尔洲季酒店，呼伦贝尔香格里拉大酒店，...(无前缀) -- sourceNodeName / icon 全 null - -## 部署状态 - -- ✅ Deploy Panel 已部署测试服 hl-product-service-v2 双实例(2026-04-30 17:25) -- 正式环境暂未发布(等 dev → main release PR) diff --git a/changelogs/2026-04/30_fix_product_fee-deduction-merge-by-feetype.md b/changelogs/2026-04/30_fix_product_fee-deduction-merge-by-feetype.md deleted file mode 100644 index adb1a11..0000000 --- a/changelogs/2026-04/30_fix_product_fee-deduction-merge-by-feetype.md +++ /dev/null @@ -1,124 +0,0 @@ -# 修复: 费用包含按 feeType 合并为单条 name 拼接 - -**类型**: 后端 BUG 修复(PR #1577 follow-up) -**关联**: 工单 #1578 / PR #1579 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台「产品编辑 → 补充信息 → 费用说明 →『根据行程自动生成』」按钮 - ---- - -## 演进 - -| PR | 行为 | 产品 2045018534152478721 返回数 | -|---|---|---| -| #1568 | 修复漏景区/活动/酒店,每节点 1 条+追加酒店 | 35 条 | -| #1577 | 按名字去重,name 改具体名 | 17 条 | -| **#1579 本次** | **按 feeType 合并为单条,name 拼接所有具体名** | **3 条** | - -用户期望:每种 feeType 一条记录,中间 label 显示完整字符串。 - -## 用户原文 - -> 「门票：黑山头，莫日格勒河 门票是一条数据」 -> 「其他也是」(指活动/住宿/餐饮/交通也都按 feeType 合并) - -## 设计 - -``` -name = "{feeType}：{name1，name2，...}" (中文「：」前缀 + 中文「，」分隔) -``` - -| 字段 | 值 | -|---|---| -| `feeType` | 门票 / 活动 / 住宿 / 餐饮 / 交通(chip 用) | -| `name` | `"门票：黑山头，白桦林景区，莫日格勒河，..."` 完整拼接串 | -| `sourceNodeName` | **null**(避免重复) | -| `icon` | **null**(PR #1573 行为不变) | - -## 影响接口 - -| 方法 | 路径 | 改动 | -|------|------|------| -| GET | `/admin/product/item/{id}/fee-deduction-preview` | 数组**长度从 N 条压缩到 ≤ 5 条**(每 feeType 1 条),`name` 字段值变为完整拼接串,`sourceNodeName` 设为 null | - -请求签名完全不变,响应字段不变。 - -## 响应示例 - -```jsonc -GET /admin/product/item/2045018534152478721/fee-deduction-preview -{ - "code": 200, - "data": [ - { - "feeType": "门票", - "name": "门票：黑山头，白桦林景区，莫日格勒河，莫日格勒河断崖，呼伦湖，阿尔山火车站", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - }, - { - "feeType": "活动", - "name": "活动：ATV全地形越野车穿越，驯鹿拉车体验", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - }, - { - "feeType": "住宿", - "name": "住宿：海拉尔洲季酒店，呼伦贝尔香格里拉大酒店，额尔古纳玖成万豪水汇智能酒店，额尔古纳豪星酒店，额尔古纳白桦大酒店，海拉尔海棠酒店，满洲里饭店（百年俄式），敖根栖息地，阿尔善国际维景度假温泉酒店", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - } - ] -} -``` - -## 实现要点 - -```java -// 1. LinkedHashMap<feeType, LinkedHashSet<name>> 双保序去重收集 -Map<String, LinkedHashSet<String>> feeTypeToNames = new LinkedHashMap<>(); -// (扫节点 + 扫酒店,按 feeType 分桶) - -// 2. feeIgnoredTypes 在 map 阶段移除 entry(效率优于 result.removeIf) -feeTypeToNames.keySet().removeAll(ignored); - -// 3. 排序(门票/活动/住宿/餐饮/交通)+ 拼接 + 输出 -return feeTypeToNames.entrySet().stream() - .filter(e -> !e.getValue().isEmpty()) - .sorted(byFeeTypeOrder) - .map(e -> FeeDeductionPreviewVO.builder() - .feeType(e.getKey()) - .name(e.getKey() + "：" + String.join("，", e.getValue())) - .source(SOURCE_AUTO) - .sourceNodeName(null) - .build()) - .toList(); -``` - -## 前端要做的改动 - -**0 改动**。前端模板 `{{ item.name }}` 直接渲染就显示 `"门票：黑山头，白桦林景区，..."` 完整字符串。 - -`sourceNodeName=null` 后,前端 `v-if="item.sourceNodeName"` 来源标签自动不渲染,UI 自然更清爽。 - -## 测试覆盖 - -`mvn test -pl hl-product-service-v2`: **1046/1046 全绿**。 - -10 现有断言更新(从「按 name 多条」改为「按 feeType 一条」)+ 1 新增 `feeDeductionPreview_mixedTypes_groupedByFeeType` 混合类型分组测试。 - -测试服 round-trip(产品 `2045018534152478721`)实测: -- 总计 **3 条**(门票/活动/住宿 各一) -- 每条 `name` 是 `"{feeType}：{name1，name2，...}"` 完整串 -- `sourceNodeName` 全 null -- `feeType` 排序正确(门票 → 活动 → 住宿) -- `icon` 全 null - -## 部署状态 - -- ✅ Deploy Panel 已部署测试服 hl-product-service-v2 双实例(2026-04-30 17:11) -- 正式环境暂未发布(等 dev → main release PR) diff --git a/changelogs/2026-04/30_fix_product_fee-deduction-preview-include-all-nodes.md b/changelogs/2026-04/30_fix_product_fee-deduction-preview-include-all-nodes.md deleted file mode 100644 index 26d6b9e..0000000 --- a/changelogs/2026-04/30_fix_product_fee-deduction-preview-include-all-nodes.md +++ /dev/null @@ -1,97 +0,0 @@ -# 修复: 产品「补充信息」费用包含「根据行程自动生成」漏景区/活动/酒店 - -**类型**: 后端 BUG 修复 -**关联**: 工单 #1567 / PR #1568 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台「产品编辑 → 补充信息 → 费用说明 →『根据行程自动生成』」按钮 - ---- - -## 现象 - -点击「根据行程自动生成」后,前端展示的「费用包含」列表项严重不全: - -- 同类型节点只展示**第一个**:产品有 6 个景区只回 1 条「门票」 -- 酒店**完全不出现** - -测试样本:产品 id=`2045018534152478721`「游牧的森林·南线经典」(用户原图) -- 旧逻辑只返回 2 条:活动「← ATV 全地形越野穿越」 + 门票「← 白桦林景区」 -- 修复后返回 35 条:6 门票 + 2 活动 + 27 住宿(全部景区 / 全部活动 / 全部酒店) - -## 根因 - -`hl-product-service-v2` `ProductValidationService.feeDeductionPreview()` 旧实现: - -1. `Set<String> deducted` 按 `feeLabel`(门票/活动/住宿/餐饮/交通)去重 → 同 feeType 只保留**第一条** -2. 完全没查 `product_day_hotel` 表(酒店数据已早期迁离 `product_itinerary_node`,但 fee-deduction-preview 没同步更新) - -## 修复 - -`feeDeductionPreview()` 重写为: - -- **不再按 feeLabel 去重**,每个 `ProductItineraryNodeDO` 都生成 1 条 `FeeDeductionPreviewVO`(前提 `getFeeLabel() ≠ null`) -- **追加查 `dayHotelService.selectByProductId(productId)`**,全部酒店并入结果,`feeType="住宿"`,`sourceNodeName=酒店名` -- 节点按 `dayId + sortOrder` 排序,酒店按 `dayNumber + sortOrder` 排序 -- 整体按 `门票 → 活动 → 住宿 → 餐饮 → 交通` 分组排序 -- NPE 兜底:`allNodes / allHotels` null → 空集合;`hotelName / dayId / sortOrder` null → 排序用 `MAX_VALUE` 兜底 - -## 影响接口 - -| 方法 | 路径 | 改动 | -|------|------|------| -| GET | `/admin/product/item/{id}/fee-deduction-preview` | 返回项数从去重后的 N 条 → 全节点 + 全酒店,字段不变 | - -请求签名完全不变,响应字段不变,只是 `data` 数组**变长且含酒店**。 - -## 响应示例 - -```jsonc -GET /admin/product/item/2045018534152478721/fee-deduction-preview -{ - "code": 200, - "data": [ - { "feeType": "门票", "name": "门票", "source": "AUTO", "sourceNodeName": "黑山头", "icon": null }, - { "feeType": "门票", "name": "门票", "source": "AUTO", "sourceNodeName": "白桦林景区", "icon": null }, - { "feeType": "门票", "name": "门票", "source": "AUTO", "sourceNodeName": "莫日格勒河", "icon": null }, - /* ... 共 6 条门票 */ - { "feeType": "活动", "name": "活动", "source": "AUTO", "sourceNodeName": "ATV 全地形越野车穿越", "icon": null }, - { "feeType": "活动", "name": "活动", "source": "AUTO", "sourceNodeName": "驯鹿拉车体验", "icon": null }, - { "feeType": "住宿", "name": "住宿", "source": "AUTO", "sourceNodeName": "海拉尔洲季酒店", "icon": null }, - /* ... 共 27 条住宿 */ - ] -} -``` - -## 前端要做的改动 - -### 已是 `v-for` 列表渲染 — 0 改动 - -`hl-ui/src/views/product/edit/components/supplement/CostDescPanel.vue` 第 109-119 行已经是 -`v-for="(item, idx) in includedCosts"` 网格布局,每张 card 显示 `feeType + name + ← sourceNodeName`,**新方案完美适配**: -- 6 个景区会渲染 6 张「门票」card,每张带不同景区名(如「门票 ← 黑山头」「门票 ← 白桦林景区」…) -- 27 个酒店会渲染 27 张「住宿」card,每张带不同酒店名 - -UI 上多张同 feeType card 紧邻成一组排开,符合用户期望「看到所有节点」。 - -### 如果想做「按 feeType 聚合显示」(可选) - -如果前端反馈「列表太长,希望同 feeType 合并为一张 card,内部分行列出来源」,可以前端 `Object.groupBy(includedCosts, c => c.feeType)` 自行聚合,无需后端改动。 - -## 测试覆盖 - -`mvn test -pl hl-product-service-v2`:1026/1026 全绿。 -新增/增强 6 条 `@ExtendWith(MockitoExtension.class)` 单测覆盖:多景区 / 多活动 / 含酒店 / 空产品 / 未知类型(FREE/NOTE/SERVICE/CUSTOM)/ 忽略类型。 - -测试服 round-trip 验证(产品 `2045018534152478721`):返回 35 条,包含 6 景区 + 2 活动 + 27 酒店,排序正确,**用户原图问题修复**。 - -## 不动 - -- 数据库表结构不变(只是查询逻辑扩展) -- VO 字段不变(只是 `data` 数组长度) -- `feeIgnoredTypes` 过滤逻辑保留,被忽略的 feeType 仍会从结果中剔除 - -## 部署状态 - -- ✅ Deploy Panel 已部署测试服 hl-product-service-v2(2026-04-30 16:35) -- 正式环境暂未发布(等 dev → main release PR) diff --git a/changelogs/2026-04/30_fix_product_itinerary-validate-on-publish.md b/changelogs/2026-04/30_fix_product_itinerary-validate-on-publish.md deleted file mode 100644 index 9935758..0000000 --- a/changelogs/2026-04/30_fix_product_itinerary-validate-on-publish.md +++ /dev/null @@ -1,115 +0,0 @@ -# 修复:产品行程必填校验改到「完成设计」「上架审批」时,草稿允许空 - -**类型**: 后端 BUG 修复(翻盘 PR #1558 任务B 方向) -**关联**: 工单 #1557 / PR #1558(误) / PR #1560(修正) -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台产品编辑页 Step 2 行程编排 + 完成设计按钮 + 提交上架审批按钮 - ---- - -## 翻盘说明 - -### PR #1558 任务B 错误方向(已 revert) -PR #1558 在 `ProductItinerarySaveReqVO` 三处加 `@NotBlank/@NotEmpty`,等于"**保存即必填**" — 把草稿态的中间保存也拦下了。 - -### 用户反馈(2026-04-30) -> "上架和完成实际时候得校验不能有空数据" - -### 正确业务规则 -| 操作 | 路径 | 校验 | -|---|---|---| -| **保存草稿** | `PUT /admin/product/item/{id}/itinerary` | **不校验**(允许空,方便分阶段保存) | -| **完成设计**(仅 CUSTOM) | `POST /admin/product/item/{id}/complete` | **必填校验** | -| **提交上架审批** | `POST /admin/product/item/{id}/toggle-publish`(SUBMIT_PUBLISH 方向) | **必填校验** | -| **超管直接上架** | 同上(DIRECT_PUBLISH 方向) | **必填校验** | -| **下架/撤回/驳回回退** | 同上(其他方向) | **不校验**(避免阻塞补救路径) | - -## 后端改动 - -### 1. 回滚 ReqVO 注解 -`ProductItinerarySaveReqVO.java` 撤销 PR #1558 三处: -- L53 `description` 移除 `@NotBlank` -- L84 `nodes` 移除 `@NotEmpty` -- L87 `hotels` 移除 `@NotEmpty` - -(`gatherPlace/dismissalPlace` 的 `@NotNull` 不动 — PR #1558 之前就有。) - -### 2. ProductValidationService 新增两 public 方法 - -```java -// 返回错误清单(空列表=可上架) -public List<String> validateItineraryCompleteness(Long productId) - -// 硬校验,失败抛 BusinessException(批量错误一次抛) -public void assertItineraryCompleteForPublish(Long productId) -``` - -实现要点: -- DB 3 次读(行程天 + 全部活动节点 + 全部酒店),按 dayId 分组避免 N+1 -- 一次扫所有 day,缺哪些字段累加到 issues 列表,调用方一次抛出 -- 错误码 `ProductCoreErrorCode.PRODUCT_ITINERARY_INCOMPLETE` (400404) - -### 3. 挂载点 -- `ProductStatusService.completeDesign` 入口直接调 -- `ProductStatusService.togglePublish` 仅 `preAction == SUBMIT_PUBLISH || DIRECT_PUBLISH` 触发 - -## 错误响应示例 - -完成设计 / 提交上架时,行程不完整返回: - -```jsonc -HTTP 200 (走业务错误码,非协议错误) -{ - "code": 400404, - "message": "行程未完整填写，请补全后再操作:\nDay 1 行程描述未填写\nDay 1 活动安排为空\nDay 1 住宿安排为空\nDay 3 集合地未填写", - "data": null -} -``` - -## 测试服 round-trip 结果(用户截图原产品 2049468625294708737) - -| Case | 操作 | 实际结果 | -|------|------|---------| -| 草稿 PUT itinerary 全空 | PUT /itinerary body 含空 description+nodes=[]+hotels=[] | ✅ 200 code=200 msg="行程保存成功" | -| 完成设计 | POST /complete | ✅ code=400404 含批量错误清单 | -| 提交上架审批 | POST /toggle-publish | ✅ 同上批量错误 | - -## 前端要做的改动 ⚠️ - -### 1. 草稿保存路径 — 无须改动 -保存草稿现在允许 description / nodes / hotels 为空,前端可以**取消保存按钮的"必填校验提示"**,让用户中间状态自由保存。 - -### 2. 完成设计 / 提交上架 按钮 -点击后如果后端返回 `code=400404`: -- `message` 字段是多行文本,**保留 `\n` 换行直接展示**(如 `<pre>` 或 white-space: pre-wrap) -- 内容形如: - ``` - 行程未完整填写，请补全后再操作: - Day 1 行程描述未填写 - Day 1 活动安排为空 - Day 3 集合地未填写 - ``` -- 用户根据清单逐条补齐再点完成设计/上架即可 - -### 3. 错误码字典 -| 业务码 | 含义 | 触发 | -|---|---|---| -| 400404 | 行程未完整 | 完成设计/提交上架前预检 | - -## 部署状态 - -- ✅ PR #1560 合并到 dev (sha 040d2ccb) -- ✅ Deploy Panel 任务 success,hl-product-service-v2:8083+8183 双实例 1/1 Up -- ✅ 测试服 3 笔 round-trip 全通过 -- ⏳ Release dev → main 暂缓(用户指示"不用立即合 main") - -## 单测 - -`mvn test -pl hl-product-service-v2`: 1019 全绿 (-8 旧 +7 新) - -## 不动 - -- 任务A 最低价接口完全不动 -- `gatherPlace/dismissalPlace @NotNull` 不动 -- NodeItem/HotelItem 子字段不动(原工单未要求,防回归) diff --git a/changelogs/2026-04/30_fix_product_validate-skip-last-day-hotel.md b/changelogs/2026-04/30_fix_product_validate-skip-last-day-hotel.md deleted file mode 100644 index 9363d8e..0000000 --- a/changelogs/2026-04/30_fix_product_validate-skip-last-day-hotel.md +++ /dev/null @@ -1,81 +0,0 @@ -# 修复: 上架/完成设计校验跳过最后一天酒店(返程日豁免) - -**类型**: 后端 BUG 修复 -**关联**: 工单 #1586 / PR #1587 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台「完成设计」「提交审核 / 直接上架」按钮的预检逻辑 - ---- - -## 现象 - -用户反馈:产品上架/完成设计预检时,如果**最后一天**没在 `product_day_hotel` 配酒店,就被「Day N 住宿安排为空」拦截无法上架。但**最后一天通常是返程日不需要住宿**,这个校验是错的。 - -用户原文:「最后一天行程提示也得有住宿安排,实际不需要」 - -## 根因 - -`hl-product-service-v2` `ProductValidationService.validateItineraryCompleteness()` 对每一天循环硬要求 `product_day_hotel` 非空,**没有跳过最后一天**。 - -## 修复 - -判定最后一天豁免酒店校验: - -```java -int totalDays = days.size(); -for (int i = 0; i < totalDays; i++) { - ProductItineraryDayDO day = days.get(i); - // ... 描述/集合地/解散地/活动校验保持不变 ... - - // 最后一天通常是返程,不强制要求配酒店(2026-04-30 用户反馈) - boolean isLastDay = (day.getDayNumber() != null) - ? day.getDayNumber() == totalDays - : i == totalDays - 1; - if (!isLastDay) { - if (dayHotels.isEmpty()) issues.add(dayLabel + " 住宿安排为空"); - } -} -``` - -判定规则: -- 优先 `day.getDayNumber() == totalDays` -- `dayNumber` 为 null 时回退索引 `i == totalDays - 1` - -## 行为变化 - -| tripDays | 最后一天 | 行为 | -|---|---|---| -| 1 | i=0 是唯一一天即最后一天 | 单天产品没酒店通过 | -| 2 | Day1 校验 / Day2 豁免 | OK | -| 3 | Day1/Day2 校验 / Day3 豁免 | OK | -| dayNumber=null | 列表最后一项兜底 | 跳过 | - -## 影响接口 - -| 方法 | 路径 | 改动 | -|------|------|------| -| POST | `/admin/product/item/{id}/complete-design` | 最后一天没酒店不再返 400 | -| POST | `/admin/product/item/{id}/toggle-publish` (SUBMIT_PUBLISH/DIRECT_PUBLISH) | 同上 | -| PUT | `/admin/product/item/{id}/supplement` | 不变(草稿允许任意) | - -请求/响应签名不变,只是错误条件减少。 - -## 前端要做的改动 - -**0 改动**。如果前端之前对「Day N 住宿安排为空」错误做过 UX 引导(比如跳到行程编排页面),保留即可,不会被误触发。 - -## 测试覆盖 - -新增 4 单测: -- `validateItinerary_lastDayNoHotel_shouldPass` — 3 天 day3 没酒店,通过 -- `validateItinerary_middleDayNoHotel_shouldFail` — 3 天 day2 没酒店,报错;day3 不计入 -- `validateItinerary_singleDay_noHotel_shouldPass` — 1 天产品没酒店通过 -- `validateItinerary_dayNumberNull_useListIndexFallback` — dayNumber=null 兜底 - -`mvn test`: ProductValidationServiceTest **53/53 全绿**。 - -## 部署状态 - -- ✅ 测试服 hl-product-service-v2 双实例部署完成(2026-04-30 23:40) -- 正式环境暂未发布(等 dev → main release PR) diff --git a/changelogs/2026-04/30_fix_product_vehicle-model-validation.md b/changelogs/2026-04/30_fix_product_vehicle-model-validation.md deleted file mode 100644 index cf1b276..0000000 --- a/changelogs/2026-04/30_fix_product_vehicle-model-validation.md +++ /dev/null @@ -1,92 +0,0 @@ -# 修复:产品「完成设计 / 上架审批」校验「可选车型」必填,草稿放行 - -**类型**: 后端 BUG 修复 -**关联**: 工单 #1564 / PR #1569 -**日期**: 2026-04-30 -**前端处理者**: mmg -**影响范围**: 管理后台 CORE / CUSTOM 产品的「完成设计」按钮 + 「提交审核 / 直接上架」按钮 - ---- - -## 背景 - -CORE / CUSTOM 类产品在「补充信息 → 车辆配置」中需要给出「可选车型」(supplement.vehicle_model_ids),否则线路下游派车流程拿不到车型选项,行程详情和报价也会缺数据。但此前后端在「完成设计」「上架」入口未做硬校验,导致出现「车型为空但已上架」的脏数据。 - -GROUP(小蒙马)产品不走可选车型字段,本次跳过此校验。 - -## 业务规则 - -| 操作 | 路径 | 校验 | -|---|---|---| -| **保存草稿(补充信息)** | `PUT /admin/products/{id}/save-supplement` | **不校验**(允许中间状态空保存) | -| **完成设计** | `POST /admin/products/{id}/complete-design` | **CORE / CUSTOM 必填**;GROUP 跳过 | -| **提交上架审核 / 直接上架** | `POST /admin/products/{id}/toggle-publish` | **CORE / CUSTOM 必填**;GROUP 跳过 | -| **下架 / 撤回 / 驳回回退** | 同上 | **不校验**(避免阻塞补救路径) | - -校验规则:`supplement.vehicle_model_ids` 与 `route_info.vehicle_model_id` **同时为空**才算未填(任一非空即可放行,兼容历史只填了 route_info 的产品)。 - -## 后端改动 - -- 新增校验落点:`completeDesign` + `togglePublish`(仅 SUBMIT_PUBLISH / DIRECT_PUBLISH 两个方向)入口处 -- 错误码 `ProductCoreErrorCode.PRODUCT_VEHICLE_MODEL_INCOMPLETE = 400405` -- GROUP 产品 productType=GROUP 直接跳过 -- 草稿保存 `saveSupplement` 路径不动,允许 vehicle_model_ids 为空 - -## 错误响应 - -完成设计 / 提交上架时,可选车型为空返回: - -```jsonc -HTTP 200 (业务错误码,非协议错误) -{ - "code": 400405, - "message": "请在「补充信息 → 车辆配置 → 可选车型」至少添加 1 个车型后再提交", - "data": null -} -``` - -## 影响接口清单 - -| 方法 | 路径 | 改动 | -|------|------|------| -| POST | `/admin/products/{id}/complete-design` | **新增** 400405 业务错误码 | -| POST | `/admin/products/{id}/toggle-publish` | **新增** 400405 业务错误码 (仅 SUBMIT_PUBLISH / DIRECT_PUBLISH) | -| PUT | `/admin/products/{id}/save-supplement` | **不变**(允许空) | - -请求 / 响应签名(成功路径)完全不变,只是失败时多了一种 400405 业务码。 - -## 前端要做的改动 - -### 1. 草稿保存路径 — 无须改动 - -补充信息保存仍允许 `vehicle_model_ids` 为空,前端可以保留中间保存的能力,不需要在保存按钮上加车型必填提示。 - -### 2. 完成设计 / 提交上架按钮 — 处理 400405 - -点击「完成设计」或「提交审核 / 直接上架」按钮后,如果后端返回 `code=400405`: - -- 直接弹出 `message` 文案(已经是给用户看的中文,可以原样展示): - ``` - 请在「补充信息 → 车辆配置 → 可选车型」至少添加 1 个车型后再提交 - ``` -- 建议 UX:弹错后引导用户跳到「补充信息 → 车辆配置」Tab,聚焦「可选车型」字段,方便用户当场补齐再点完成设计/上架 -- GROUP(小蒙马)产品后端不会触发此错误码,前端无须额外区分 - -### 3. 错误码字典 - -| 业务码 | 含义 | 触发场景 | -|---|---|---| -| 400405 | 可选车型未填 | CORE / CUSTOM 产品完成设计 / 上架前预检 | - -(配套已在用的相关码:400404 行程未完整 — 见同日 `30_fix_product_itinerary-validate-on-publish.md`) - -## 不动 - -- GROUP(小蒙马)产品完全不动,不走车型校验 -- `route_info.vehicle_model_id` 字段语义不动,仅作为兜底入参 -- 现存已上架但车型为空的历史产品不溯源处理(只在再次「完成设计/上架」时拦截) - -## 部署状态 - -- 待 Deploy Panel 推送测试服 hl-product-service-v2 后生效 -- 正式环境暂未发布(等 dev → main release PR) diff --git a/changelogs/2026-04/30_frontend_cost-desc-panel-missing-youwan-feetype.md b/changelogs/2026-04/30_frontend_cost-desc-panel-missing-youwan-feetype.md deleted file mode 100644 index 80fa213..0000000 --- a/changelogs/2026-04/30_frontend_cost-desc-panel-missing-youwan-feetype.md +++ /dev/null @@ -1,172 +0,0 @@ -# 前端 BUG: CostDescPanel 不展示「游玩项目」类型 - -> 📌 **状态变更记录**: -> - 17:35 首次发现并通知 mmg -> - 17:38 用户当面说"前端没问题,之后能看到活动",一度撤回 -> - **17:55 用户复测确认确实是前端 BUG,恢复通知**(用户原话:「为啥不显示活动 告知前端」) -> - 后端 + DB 均无问题,前端排查 CostDescPanel.vue 数据 filter / 字典映射 - -**类型**: 前端 BUG(后端零改动) -**前端处理者**: mmg -**日期**: 2026-04-30 -**影响范围**: 管理后台「产品编辑 → 补充信息 → 费用说明」页面 — 自动生成的费用包含列表 - -## ⚠️ 前端 mmg 第二次反馈(2026-04-30 20:43) - -前端 mmg 截图: -``` -includedFees: [{name: "扎赉诺尔博物馆，巴尔虎蒙古部落，海拉尔国家森林公园", description: null}, ...] -0: {name: "扎赉诺尔博物馆，巴尔虎蒙古部落，海拉尔国家森林公园", description: null} -1: {name: "海拉尔首旅京伦酒店, 额尔古纳豪星酒店", description: null} -``` - -→ "返回的费用包含不对 自动的没有类型" - -## 后端实测(管理者再次 round-trip 确认) - -`GET /admin/product/item/2045018534152478721`(测试服) 实测响应: - -```jsonc -includedFees: [ - { - "id": "2049778058755268609", - "productId": "2045018534152478721", - "feeCategory": "INCLUDED", - "feeType": "门票", // ← 后端有这个字段! - "source": "AUTO", - "name": "黑山头", - "description": null, - ... - }, ... // 17 条单条记录,全部含 feeType -] -``` - -`PUT /admin/product/item/{id}/supplement` 写入 `[{feeType:"景区",name:"X1，X2",sortOrder:1}]` → -`GET /admin/product/item/{id}` 读出来 `includedFees=[{feeType:"景区",name:"X1，X2",...}]` - -**字符串完全一致透传**,后端 round-trip 验证齐全。 - -## 前端排查焦点 - -1. 前端 mmg console 截图只看到 2 项(0/1),**第三项「游玩项目」消失** — 跟首次反馈一致 -2. 每项 keys 只显示 `name + description`,但后端实际返 16 个字段(`id/productId/feeCategory/feeType/source/name/description/resourceType/resourceId/costItemId/unitPrice/quantity/daily/unit/icon/sortOrder`)→ 前端 console 打印应该是只挑了部分字段(可能 `console.log({name:..., description:...})`)还是真的丢了完整字段? - -## 排查建议升级版 - -请前端在 `mounted()` 钩子加完整打印: - -```js -async function loadIncludedCosts() { - const res = await getFeeDeductionPreview(productId) - console.log('[FULL res]', JSON.parse(JSON.stringify(res))) // ← 看完整字段 - console.log('[res.length]', res?.length) // ← 看是不是真的少了 1 项 - console.log('[item keys]', res?.[0] && Object.keys(res[0])) // ← 看每项实际字段 - // ... -} -``` - -如果 `JSON.parse(JSON.stringify(res))` 完整打印里: -- 看到 3 项含 `feeType="景区"/"游玩项目"/"住宿"` 字段 → 是渲染层 v-for 过滤了「游玩项目」(跟之前推测一致),修 v-for 模板 / filter 逻辑 -- 看到 2 项缺「游玩项目」/字段不全 → axios 拦截器 / store / 数据预处理吞了字段(grep `filter.*feeType` / `pick.*name.*description` 之类) - -## 后端 round-trip 实测命令(mmg 可复测) - -```bash -TOKEN=... -curl -k "https://api.test.1814.love:9443/admin/product/item/2045018534152478721/fee-deduction-preview" \ - -H "Authorization: Bearer $TOKEN" | jq '.data | length, .data[].feeType' -# 期望:3 / "景区" / "游玩项目" / "住宿" -``` - ---- - -## 现象 - -产品编辑页 → 补充信息 → 费用说明 →「根据行程自动生成」按钮加载后,用户实测产品 `2045018534152478721`「游牧的森林·南线经典」: - -- 期望显示 **3 行**:景区 / **游玩项目** / 住宿 -- 实际只显示 **2 行**:景区 / 住宿 -- **「游玩项目」那行没出现** - -## 后端验证(测试服已部署 PR #1568 + #1577 + #1579 + #1581 + #1583) - -```bash -curl https://api.test.1814.love:9443/admin/product/item/2045018534152478721/fee-deduction-preview \ - -H "Authorization: Bearer <admin_token>" -``` - -**实测响应(3 条齐全)**: - -```jsonc -{ - "code": 200, - "data": [ - { - "feeType": "景区", - "name": "黑山头，白桦林景区，莫日格勒河，莫日格勒河断崖，呼伦湖，阿尔山火车站", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - }, - { - "feeType": "游玩项目", // ← 后端有这条! - "name": "ATV全地形越野车穿越，驯鹿拉车体验", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - }, - { - "feeType": "住宿", - "name": "海拉尔洲季酒店，呼伦贝尔香格里拉大酒店，额尔古纳玖成万豪水汇智能酒店，额尔古纳豪星酒店，额尔古纳白桦大酒店，海拉尔海棠酒店，满洲里饭店（百年俄式），敖根栖息地，阿尔善国际维景度假温泉酒店", - "source": "AUTO", - "sourceNodeName": null, - "icon": null - } - ] -} -``` - -后端返 3 条,前端展示 2 条 → **前端过滤掉了「游玩项目」**。 - -## 推测原因 - -后端 `feeType` 字段值演进历史(2026-04-30 同日): -- 旧值:`门票 / 活动 / 住宿 / 餐饮 / 交通`(NodeTypeEnum.getFeeLabel()) -- 新值:**`景区 / 游玩项目 / 住宿 / 餐饮 / 交通`**(PR #1581 加 displayLabel 映射) - -可能性 A:前端有 feeType 白名单(只允许 `门票/活动/住宿/餐饮/交通`),收到新的 `景区`/`游玩项目` 不在白名单被 filter 掉 → 但用户截图能看到「景区」chip,说明白名单包含「景区」却不含「游玩项目」(可能是前端字典只补了一半) - -可能性 B:前端有 feeType→中文显示名映射字典(比如 `{门票:'景区', 活动:'游玩项目'}`),后端改成直接返显示名后,字典里查不到 `游玩项目`(因为 key 是 `活动`),返 null/undefined 被 v-if 过滤 - -可能性 C:某个数据预处理 `data.filter(...)` 用了硬编码 feeType 列表 - -## 排查建议 - -请前端检查 `D:\work2\hl-ui\src\views\product\edit\components\supplement\CostDescPanel.vue`(或对应实际页面所在的 vue 组件),关键看: - -1. 数据加载后是否有 `filter`/`map` 处理 feeType -2. `<template>` 是否有 `v-if="includes('门票'/'活动'/...)"` 类型白名单 -3. feeType 显示是否走中文字典查表 -4. `included-grid` CSS 网格是否被某个 `v-if` 控制只渲染部分项 - -## 临时验证方法 - -前端 console 打开: - -```js -// 在 CostDescPanel mounted 后,看 includedCosts 实际值 -console.log(includedCosts.value) -// 如果有 3 项,说明数据没问题,问题出在 v-for 或 filter -// 如果只有 2 项,说明 res 取 data 时被过滤,或 axios 拦截器吞了一项 -``` - -## 后端不再改动 - -后端 `feeType` 字段值已稳定为 `景区 / 游玩项目 / 住宿 / 餐饮 / 交通`(PR #1581 + #1583 已合并部署),与前端 chip 显示文案对齐。前端只需识别「游玩项目」这个值即可。 - -如果前端字典有 `{门票: '景区', 活动: '游玩项目'}` 这种映射,**直接删掉**即可(后端已经返显示名了)。 - -## 部署状态 - -- 后端(测试服):✅ 已部署 hl-product-service-v2 双实例(2026-04-30 17:25) -- 前端(测试服):待 mmg 排查并发版 diff --git a/changelogs/2026-05/01_feat_contract_scheme_attachments_tab.md b/changelogs/2026-05/01_feat_contract_scheme_attachments_tab.md deleted file mode 100644 index 0dbb124..0000000 --- a/changelogs/2026-05/01_feat_contract_scheme_attachments_tab.md +++ /dev/null @@ -1,132 +0,0 @@ -# 合同方案管理页 — 新增「附件管理」Tab - -**类型**: 后端新接口 -**前端处理者**: mmg -**日期**: 2026-05-01 -**关联**: 工单 #1590 / PR #1592 #1594 -**影响页面**: 管理后台「合同管理 → 合同方案 → 编辑方案」 - ---- - -## 这是什么 - -合同方案现在可以挂附件（PDF/图片）。生成 12301 合同时，方案附件会**自动作为合同附件嵌入**到 12301 平台合同 PDF 中。 - -**用途举例**： -- 旅行社服务标准 PDF -- 公司资质照片 -- 安全告知补充说明 -- 任何需要随合同长期出现的材料 - -**业务规则**：方案上传几个附件，生成合同时就嵌入几个，不需要每个订单单独传。 - ---- - -## UI 需求 - -在合同方案编辑页（路由类似 `/admin/contract/scheme/edit/:id`）加一个 **「附件管理」Tab**，里面： - -1. **附件列表表格**： - - 列：文件名 / 类型 / 大小 / 排序号 / 创建时间 / 操作 - - 操作：下载（`ossUrl`）/ 调整排序号 / 删除 - -2. **上传按钮**： - - 点击 → 弹窗 - - 表单字段： - - 文件（必填，accept=`.pdf,.jpg,.jpeg,.png`，限 10MB） - - 文件类型（下拉：PDF / 图片 / 其他） - - 排序号（数字，默认 0，越小越前） - - 提交 → multipart 上传 - -3. **删除二次确认**：删后从列表移除 - ---- - -## 接口 - -**Base path**: `/admin/contract/scheme/{schemeId}/attachments` - -### 1. 查询附件列表 - -``` -GET /admin/contract/scheme/{schemeId}/attachments -Authorization: Bearer <admin_token> - -→ 200 -{ - "code": 200, - "data": [ - { - "attachmentId": "2049914870366703618", // String 雪花 - "schemeId": 3, - "fileName": "服务标准.pdf", - "ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/contract/scheme-attachment/2026-05/3_xxx.pdf", - "fileSize": 102400, // 字节数 - "fileType": "PDF", // PDF / IMAGE / OTHER - "sortOrder": 10, - "createTime": "2026-05-01 10:12:45" - } - ] -} -``` - -### 2. 上传新附件（multipart/form-data） - -``` -POST /admin/contract/scheme/{schemeId}/attachments -Authorization: Bearer <admin_token> -Content-Type: multipart/form-data - -form-data: - file: <File 二进制> (必填, ≤10MB) - fileType: "PDF" (必填, 字典 PDF / IMAGE / OTHER) - sortOrder: 10 (选填, 默认 0) - -→ 200 -{ - "code": 200, - "data": { ...同上单条结构, 含新生成 attachmentId 和 ossUrl... } -} -``` - -### 3. 调整排序 - -``` -PUT /admin/contract/scheme/{schemeId}/attachments/{attachmentId}/sort -Content-Type: application/json -{ "sortOrder": 20 } - -→ 200 { "code": 200, "data": null } -``` - -### 4. 删除附件（软删除） - -``` -DELETE /admin/contract/scheme/{schemeId}/attachments/{attachmentId} - -→ 200 { "code": 200, "data": null } -``` - ---- - -## 字段字典 - -`fileType` 字典 `contract_attachment_type`: - -| 字典 value | 显示名 | -|-----------|------| -| PDF | PDF 文档 | -| IMAGE | 图片 | -| OTHER | 其他 | - ---- - -## 测试服已就绪 - -可以现在直接调测试服 (`https://api.test.1814.love:9443`) 的 GET 端点验证（schemeId=3 是测试数据）。 - ---- - -## 服务重启 - -后端 hl-order-service-v2 已上线，前端开发完直接对接即可。 diff --git a/changelogs/2026-05/01_feat_contract_scheme_tour_guides_tab.md b/changelogs/2026-05/01_feat_contract_scheme_tour_guides_tab.md deleted file mode 100644 index 681ff09..0000000 --- a/changelogs/2026-05/01_feat_contract_scheme_tour_guides_tab.md +++ /dev/null @@ -1,120 +0,0 @@ -# 合同方案管理页 — 新增「导游管理」Tab - -**类型**: 后端新接口 -**前端处理者**: mmg -**日期**: 2026-05-01 -**关联**: 工单 #1590 / PR #1592 -**影响页面**: 管理后台「合同管理 → 合同方案 → 编辑方案」 - ---- - -## 这是什么 - -合同方案现在可以配导游名单。生成 12301 合同时，方案下配的导游会**作为合同条款的一部分上报到 12301 平台**（合同正文显示导游姓名/电话/导游证号）。 - -**业务规则**： -- **不强制**：自驾产品 / 不带团产品**没导游就不配，留空数组即可**（用户原话："导游有的产品没有"） -- **方案级配置**：一个方案对应一组默认导游（同一线路通常配同一批导游） -- 后端**永远不会兜底**到经办人，没配就 12301 上报空导游列表 - ---- - -## UI 需求 - -在合同方案编辑页加一个 **「导游管理」Tab**，里面： - -1. **导游列表表格**： - - 列：姓名 / 手机号 / 导游证号 / 排序号 / 创建时间 / 操作 - - 操作：编辑 / 删除 - -2. **新增按钮**： - - 点击 → 弹窗表单 - - 字段（详见下方接口） - - 提交 → POST 接口 - -3. **编辑**： - - 复用同一弹窗，PUT 接口 - -4. **删除二次确认** - ---- - -## 接口 - -**Base path**: `/admin/contract/scheme/{schemeId}/tour-guides` - -### 1. 查询导游列表 - -``` -GET /admin/contract/scheme/{schemeId}/tour-guides - -→ 200 -{ - "code": 200, - "data": [ - { - "guideId": "2049915142757388290", // String 雪花 - "schemeId": 3, - "name": "李导", - "phone": "13800138000", // 后端已用 EncryptTypeHandler 自动加解密 - "licenseNumber": "L-NMG-100953", - "sortOrder": 1, - "createTime": "2026-05-01 10:13:50" - } - ] -} -``` - -**返回空列表**（`data: []`）很正常 — 该方案没配导游。 - -### 2. 新增导游 - -``` -POST /admin/contract/scheme/{schemeId}/tour-guides -Content-Type: application/json - -{ - "name": "李导", // 必填, ≤50 字 - "phone": "13800138000", // 选填, 11 位手机号(13/14/15/16/17/18/19 开头) - "licenseNumber": "L-NMG-100953", // 选填, ≤64 字 - "sortOrder": 1 // 选填, 默认 0, 越小越前 -} - -→ 200 { "code": 200, "data": { ... 含新 guideId } } -``` - -**校验**： -- name 不能空 -- phone 格式 `^$|^1[3-9]\d{9}$`（允许空 OR 11 位手机号） -- 长度限制后端已校验，前端可加客户端校验提升体验 - -### 3. 修改导游 - -``` -PUT /admin/contract/scheme/{schemeId}/tour-guides/{guideId} -Content-Type: application/json - -{ ...同 POST body... } - -→ 200 { "code": 200, "data": { ... 同 GET 单条结构 } } -``` - -### 4. 删除导游（软删除） - -``` -DELETE /admin/contract/scheme/{schemeId}/tour-guides/{guideId} - -→ 200 { "code": 200, "data": null } -``` - ---- - -## 测试服已就绪 - -`https://api.test.1814.love:9443/admin/contract/scheme/3/tour-guides` GET 立即可调（admin token 可用 wx 账号登录拿）。 - ---- - -## 服务重启 - -后端已上线，前端开发完直接对接。 diff --git a/changelogs/2026-05/01_feat_traveler_race_nationality_room_group.md b/changelogs/2026-05/01_feat_traveler_race_nationality_room_group.md deleted file mode 100644 index c0afee8..0000000 --- a/changelogs/2026-05/01_feat_traveler_race_nationality_room_group.md +++ /dev/null @@ -1,129 +0,0 @@ -# 出行人录入 — 新增 民族 / 国籍 / 同住分组号 三个字段 - -**类型**: 后端字段扩展 -**前端处理者**: mmg -**日期**: 2026-05-01 -**关联**: 工单 #1590 / PR #1592 -**影响页面**: -- 管理后台「订单详情 → 出行人 → 新增/编辑出行人」 -- 小程序「订单 → 出行人」录入页 - ---- - -## 这是什么 - -出行人 entity 加了 3 个字段，用于 12301 合同上报： - -| 字段 | 类型 | 说明 | 默认值兜底 | -|------|------|------|----------| -| `race` | String | 民族（中文，如 "汉族" "蒙古族" "回族"） | 后端兜底 "汉族" | -| `nationality` | String | 国籍（中文，如 "中国"） | 后端兜底 "中国" | -| `roomGroupNo` | Integer | 同住分组号（同号=同房，例如夫妻填同一数字 1，独立间填 NULL 或唯一数字） | 系统自动两两配对 | - ---- - -## UI 需求 - -### 出行人录入弹窗 / 表单 - -加三个字段（建议放在「证件号 / 手机号 / 紧急联系人」附近）： - -1. **民族**（选填） - - 推荐用 **下拉框**，但项目暂没"民族"字典 - - **简化方案**：用文本输入框 + placeholder "默认汉族, 港澳台/护照证件请填实际民族" - - 后端会用 EncryptTypeHandler 加密存储不？**不加密**(当前 entity 直接 String race) - - 长度限制 20 字符 - -2. **国籍**（选填） - - 文本输入 + placeholder "默认中国, 港澳台/护照证件必填" - - 长度限制 50 字符（实际更短） - -3. **同住分组号**（选填） - - 数字输入 + placeholder "同号=同房, 留空系统自动两两配对" - - 提示文案： - > 例如夫妻同房：两人都填 1 - > 朋友合住：两人都填 2 - > 单人房：填唯一数字（如 99） - > 留空：系统按列表顺序自动两两配对（0+1, 2+3...） - ---- - -## 接口（增量字段） - -### 1. 管理端新增出行人 - -``` -POST /admin/order/{orderId}/traveler -Content-Type: application/json - -{ - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "152104199802205216", - "phone": "13800138000", - ... - - // 🆕 新增 3 字段(全部选填): - "race": "蒙古族", - "nationality": "中国", - "roomGroupNo": 1 -} -``` - -### 2. 管理端修改出行人 - -``` -PUT /admin/order/traveler/{travelerId} -Content-Type: application/json - -{ ...含同样 3 字段 } -``` - -### 3. 小程序端 - -`POST /mp/order/traveler` body 里也加这 3 字段（逻辑一致）。 - -### 4. 查询出行人详情/列表 - -``` -GET /admin/order/traveler/{travelerId} -GET /admin/order/{orderId}/travelers - -→ 200 -{ - "code": 200, - "data": { - ...原有字段... - "race": "汉族", // 🆕 - "nationality": "中国", // 🆕 - "roomGroupNo": 1 // 🆕 (Integer 或 null) - } -} -``` - ---- - -## 哪种证件类型必填？ - -业务规则： - -| 证件类型 | race / nationality 重要性 | -|---------|-------------------------| -| 身份证（ID_CARD） | 系统可由身份证号反推民族/国籍，**前端可不填**，后端兜底 | -| 港澳通行证 | **建议填**，身份证算法不适用 | -| 护照（PASSPORT） | **建议填**，外籍/海外华人必填正确国籍 | -| 台湾通行证 | 同港澳通行证 | - -可在表单上加提示文案引导。 - ---- - -## 测试服已就绪 - -后端字段已上线，前端调用接口加这 3 个字段即可。 - ---- - -## 服务重启 - -后端 hl-order-service-v2 已上线。`order_traveler` 表已 ALTER 加 race + room_group_no 列（nationality 之前已有）。 diff --git a/changelogs/2026-05/01_fix_mp_product_detail_fees_missing_feetype_icon.md b/changelogs/2026-05/01_fix_mp_product_detail_fees_missing_feetype_icon.md deleted file mode 100644 index 6f25483..0000000 --- a/changelogs/2026-05/01_fix_mp_product_detail_fees_missing_feetype_icon.md +++ /dev/null @@ -1,61 +0,0 @@ -# 小程序产品详情 includedFees/excludedFees 补 feeType + icon 字段 - -**类型**: 后端 BUG 修复 -**前端处理者**: mmg -**日期**: 2026-05-01 -**关联**: 工单 #1600 / PR #1601 -**影响**: 小程序产品详情接口 `GET /mp/product/{productId}` 的 includedFees / excludedFees 数组每项 - ---- - -## 现象 - -前端反馈接口返回的 includedFees / excludedFees 字段不对, 每项只有 name + description, 缺类型字段无法分类展示。 - -## 修复 - -`MpProductDetailRespVO.FeeInfo` VO 加 feeType + icon 字段: - -```jsonc -{ - "code": 200, - "data": { - "includedFees": [ - { - "name": "扎赉诺尔博物馆，巴尔虎蒙古部落，海拉尔国家森林公园", - "description": null, - "feeType": "景区", // 🆕 字典值: 景区/游玩项目/住宿/餐饮/交通 - "icon": "<svg ...>" // 🆕 admin 上传的 SVG 字符串(无则 null) - }, - { - "name": "海拉尔首旅京伦酒店, 额尔古纳豪星酒店", - "description": null, - "feeType": "住宿", - "icon": "<svg ...>" - } - ], - "excludedFees": [ - { - "name": "往返大交通", - "description": "", - "feeType": null, // excluded 类是手动录入, 可能无类型 - "icon": null - } - ] - } -} -``` - -## 字典: fee_type - -| value | label | -|-------|-------| -| 景区 | 景区(门票) | -| 游玩项目 | 游玩项目(活动) | -| 住宿 | 住宿 | -| 餐饮 | 餐饮 | -| 交通 | 交通 | - -## 测试服已就绪 - -GET https://api.test.1814.love:9443/mp/product/2049754271968047106 直接验证。 diff --git a/changelogs/2026-05/04_fix_contract_attachment_type_dict_added.md b/changelogs/2026-05/04_fix_contract_attachment_type_dict_added.md deleted file mode 100644 index a44b4e3..0000000 --- a/changelogs/2026-05/04_fix_contract_attachment_type_dict_added.md +++ /dev/null @@ -1,40 +0,0 @@ -# 合同方案附件类型字典已补全 (contract_attachment_type) - -**类型**: 字典数据补全(后端零代码改动, 仅 SQL) -**前端处理者**: mmg -**日期**: 2026-05-04 -**关联**: 工单 #1637 / PR #1639 - ---- - -## 现象(已修复) - -用户截图反馈合同方案附件上传弹窗"文件类型"下拉框显示"无数据"。 - -## 根因 - -PR #1592(2026-05-01) 实现合同方案附件 CRUD 接口时, changelog 提到 `contract_attachment_type` 字典, 但没在 SQL 迁移里写 sys_dict_type + sys_dict_data 数据, 导致下拉框查不到。 - -## 修复 - -测试服已直接 INSERT 字典数据 + 新建 SQL 增量 `sql/V20260504__contract_attachment_type_dict.sql` (PR #1639) 让正式环境部署前可执行。 - -字典 contract_attachment_type 现含 3 条 ACTIVE 数据: - -| dict_value | dict_label | sort_order | 说明 | -|-----------|------------|-----------|------| -| PDF | PDF文档 | 1 | 推荐: 合同方案 PDF 资质材料 | -| IMAGE | 图片 | 2 | JPG/PNG 资质照片 | -| OTHER | 其他 | 3 | 其他文件类型 | - -## 前端如何取字典 - -``` -GET /admin/dict/data/contract_attachment_type -``` - -返回 3 条数据, 直接铺到下拉选项即可。 - -## 测试服已就绪 - -立即可调, 浏览器刷新页面即可看到下拉选项。无需重启服务。 diff --git a/changelogs/2026-05/04_frontend_bug_attachment_upload_multipart.md b/changelogs/2026-05/04_frontend_bug_attachment_upload_multipart.md deleted file mode 100644 index 4d7020e..0000000 --- a/changelogs/2026-05/04_frontend_bug_attachment_upload_multipart.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -date: 2026-05-04 -type: frontend-bug -module: contract-scheme-attachment -priority: high -notify: ["@mmg"] -status: pending ---- - -# 合同方案附件上传 MultipartException — 前端没用 FormData - -## 现象 - -POST `/admin/contract/scheme/{schemeId}/attachments` 报错： - -```json -{"code":500,"message":"服务器内部错误[MultipartException]: Current request is not a multipart request","data":null,"success":false} -``` - -## 根因 - -后端 round-trip 5MB / 中文名 / 30MB PDF curl 上传**全部成功**（已验证），后端 100% OK。 - -错误是 **`org.springframework.web.multipart.MultipartException`** — Spring 在期望 multipart 请求体时拿到的不是 multipart 格式。这是前端发请求时 **Content-Type / body 包装错了**。 - -最常见原因（按概率）： -1. **axios 默认 Content-Type=application/json，没让 browser 自动设成 multipart** -2. **传了普通 object 不是 FormData，axios JSON.stringify 了** -3. **代码里写了 `Content-Type: application/json` 强制覆盖** - -## 修复（前端） - -### 错误写法 ❌ - -```js -// 错: 直接传对象 → axios 自动 JSON.stringify -http.post(`/admin/contract/scheme/${schemeId}/attachments`, { - file: fileObject, - fileType: 'PDF', - sortOrder: 0 -}) - -// 错: 强制 Content-Type -http.post(url, formData, { - headers: { 'Content-Type': 'application/json' } -}) -``` - -### 正确写法 ✅ - -```js -const formData = new FormData() -formData.append('file', file) // file 必须是 File / Blob 对象 -formData.append('fileType', 'PDF') // PDF / IMAGE / OTHER -formData.append('sortOrder', 0) - -// 关键: Content-Type 不要手动设 -// 不传 headers, 让 browser 自动加 'multipart/form-data; boundary=----WebKitFormBoundary...' -http.post(`/admin/contract/scheme/${schemeId}/attachments`, formData) - -// 或显式覆盖默认 application/json: -http.post(url, formData, { - headers: { 'Content-Type': 'multipart/form-data' } // 让 axios 自动加 boundary -}) -``` - -## 后端接口规约（不变） - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `file` | File (multipart) | ✅ | 文件本体 | -| `fileType` | String (form field) | 否 | `PDF` / `IMAGE` / `OTHER`，不传按扩展名推断 | -| `sortOrder` | Integer (form field) | 否 | 默认 0 | - -## 验证 curl（后端确认 OK 的请求） - -```bash -curl -X POST "https://api.test.1814.love:9443/admin/contract/scheme/3/attachments" \ - -H "Authorization: Bearer $TOKEN" \ - -F "file=@文明旅游倡议书.pdf;type=application/pdf" \ - -F "fileType=PDF" \ - -F "sortOrder=0" -``` - -返回： -```json -{"code":200,"data":{"attachmentId":"...","ossUrl":"...","fileSize":...},"success":true} -``` - -## 后端配套（已部署测试服） - -| PR | 改动 | -|----|------| -| #1640 | multipart 上限 50MB；超限友好提示 `code=100100` | -| #1641 | generic 500 错误暴露 exception class（本次定位就靠这个） | - -@mmg 看下 hl-ui 里调 `/admin/contract/scheme/.../attachments` 的代码，把对象传参改成 FormData 即可。 diff --git a/changelogs/2026-05/04_frontend_bug_contract_list_mode_label.md b/changelogs/2026-05/04_frontend_bug_contract_list_mode_label.md deleted file mode 100644 index 961b5a5..0000000 --- a/changelogs/2026-05/04_frontend_bug_contract_list_mode_label.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -date: 2026-05-04 -type: frontend-bug -module: contract-list -priority: medium -notify: ["@mmg"] -status: pending ---- - -# 合同列表"签约模式"列显示 ONLINE 应显示"线上签署" - -## 现象 - -`/admin/contract/list` 页面"签约模式"列显示原始 enum value: -``` -ONLINE / OFFLINE / SMS -``` -应显示中文 label: -``` -线上签署 / 线下签署 / 短信签署 -``` - -## 根因 - -后端 `/admin/contract/list` 已返回 `modeLabel` 字段（中文）： - -```json -{ - "code": 200, - "data": { - "list": [{ - "contractId": "...", - "mode": "ONLINE", // ← enum value - "modeLabel": "线上签署", // ← 中文 label, 前端直接用这个 - "platform": "12301", - "...": "..." - }] - } -} -``` - -前端模板里写的应该是 `{{ row.mode }}`，改成 `{{ row.modeLabel }}` 即可。 - -## 同模式字段（一并检查） - -后端返回的 `*Label` 字段都该用： - -| 列 | enum 字段 | 中文 label 字段 | -|----|-----------|-----------------| -| 签约模式 | `mode` | `modeLabel` | -| 合同类型 | `contractType` | `contractTypeLabel` | -| 状态 | `status` | `statusLabel` | - -打开合同列表页若发现其他列也是英文 enum，按同样规则改。 - -## 后端零改动 - -后端 VO 早已含三个 `*Label` 字段，看 `ContractListRespVO` 即可。无需后端 PR。 - -@mmg 修一下渲染字段即可，应该是 1 行 template 改动。 diff --git a/changelogs/2026-05/04_frontend_contract_list_add_orderno_column.md b/changelogs/2026-05/04_frontend_contract_list_add_orderno_column.md deleted file mode 100644 index cf41a5e..0000000 --- a/changelogs/2026-05/04_frontend_contract_list_add_orderno_column.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -date: 2026-05-04 -type: frontend-feature -module: contract-list -priority: medium -backend_pr: "#1644" -notify: ["@mmg"] -status: pending ---- - -# 合同列表加"订单编号"列 - -## 背景 - -用户反馈合同列表只显示合同编号(ECDJ...), 没显示订单编号(HL20260428141719-3940)。 - -## 后端改动 (PR #1644 已合并 + 部署) - -`/admin/contract/list` 响应里 `ContractVO` 加了 `orderNo` 字段: - -```json -{ - "list": [{ - "contractId": "...", - "orderId": 2049010051003121665, // 雪花 ID 数字 - "orderNo": "HL20260428141719-3940", // ← 新增, 人类可读 - "contractNumber": "ECDJ260504LVIVV8", - "...其他字段不变" - }] -} -``` - -## 前端改动 - -合同列表表格加"订单编号"列, 字段绑 `row.orderNo`: - -```vue -<n-data-table-column title="订单编号" key="orderNo" :width="180"> - <template #default="{ row }"> - {{ row.orderNo || '-' }} - </template> -</n-data-table-column> -``` - -建议位置: 在"合同编号"列右边或同一组排序展示。 - -@mmg 配合加列即可。 diff --git a/changelogs/2026-05/04_frontend_contract_scheme_attachment_ui_pending.md b/changelogs/2026-05/04_frontend_contract_scheme_attachment_ui_pending.md deleted file mode 100644 index 2d18116..0000000 --- a/changelogs/2026-05/04_frontend_contract_scheme_attachment_ui_pending.md +++ /dev/null @@ -1,107 +0,0 @@ -# 前端待办: 合同方案编辑页加附件管理 + 导游管理 UI - -> 📌 **状态**: 后端 API 已就绪(2026-05-01), 前端 mmg 待对接 -> **触发**: 2026-05-04 用户截图反馈"合同方案中可以上传附件咋没有呢" -> **关联工单**: #1637 - -**类型**: 前端待开发 -**前端处理者**: mmg -**日期**: 2026-05-04 -**关联**: 工单 #1637 / PR #1592 #1594 - ---- - -## 现状 - -用户截图(/contract/scheme 编辑合同方案弹窗)里只有方案名称/描述/平台/模板/签约模式/签署模式/旅行社/争议解决方式/管辖法院/补充条款/经办人姓名/经办人电话/排序 13 个字段, **没有附件上传 + 导游管理入口**。 - -## 后端 API 已就绪 - -测试服直接可调用, schemeId=3 已有真实数据(1 条附件 + 1 条导游)。 - -### 附件管理 API - -``` -GET /admin/contract/scheme/{schemeId}/attachments 查询列表 -POST /admin/contract/scheme/{schemeId}/attachments 上传(multipart: file, fileType, sortOrder) -PUT /admin/contract/scheme/{schemeId}/attachments/{id}/sort 调排序 -DELETE /admin/contract/scheme/{schemeId}/attachments/{id} 删除 -``` - -详细字段定义见 changelog: `2026-05/01_feat_contract_scheme_attachments_tab.md` - -### 导游管理 API - -``` -GET /admin/contract/scheme/{schemeId}/tour-guides 查询列表 -POST /admin/contract/scheme/{schemeId}/tour-guides 新增 -PUT /admin/contract/scheme/{schemeId}/tour-guides/{id} 修改 -DELETE /admin/contract/scheme/{schemeId}/tour-guides/{id} 删除 -``` - -详细字段定义见: `2026-05/01_feat_contract_scheme_tour_guides_tab.md` - ---- - -## UI 实现建议(mmg 选一种) - -### 推荐: 方案 A - 列表页每行操作按钮 + 独立 Dialog/Drawer - -合同方案列表页 `/contract/scheme` 表格每行**操作列**加 2 个按钮: - -``` -| 方案名称 | 平台 | 模板 | ... | 操作 | -|----------|--------|---------|-----|-------------------------------------| -| 全国旅游 | 12301 | A00001 | ... | 编辑 / 附件管理 / 导游 / 启停 / 删除 | -``` - -点击 "附件管理" → 弹独立 `<el-dialog>` 或 `<el-drawer>`: -- 顶部: "上传附件" 按钮 (multipart 上传) -- 中部: 附件列表表格 (fileName / fileType / fileSize / 排序 / 操作[下载/调排序/删除]) -- 不分页(单方案附件数量小) - -点击 "导游管理" → 同形 dialog/drawer: -- 顶部: "新增导游" 按钮 → 表单弹窗(姓名/手机/导游证号/排序) -- 中部: 导游列表表格 (name / phone / licenseNumber / 排序 / 操作[编辑/删除]) - -### 备选: 方案 B - 编辑弹窗下方加折叠面板 - -如果不想动列表页布局, 编辑合同方案弹窗 `<el-dialog>` 内容区下方加 2 个 `<el-collapse>`: - -``` -[原有方案表单字段] -───────── -+ 附件管理 (折叠) ← 点开后展开附件 CRUD UI -+ 导游管理 (折叠) ← 点开后展开导游 CRUD UI -───────── -[取消] [保存] -``` - -注意: 弹窗会变很高, 建议加最大高度 + 内部滚动。 - -### 不推荐: 方案 C - 跳详情页 - -保存方案后跳合同方案详情页, Tab 布局(信息 / 附件 / 导游)。**对现有列表页直接编辑流程改动大, 不推荐。** - ---- - -## 测试服可立即对接 - -`https://api.test.1814.love:9443/admin/contract/scheme/3/attachments` 现在有 1 条附件 -`https://api.test.1814.love:9443/admin/contract/scheme/3/tour-guides` 现在有 1 条导游 - -前端写完 UI 直接对接 schemeId=3 验证即可。 - ---- - -## 业务说明给 mmg 看(为啥需要这两个 UI) - -1. **附件**: 12301 国家旅游服务监管平台合同上报时, attachments[] 数组节点会嵌入合同 PDF。方案下挂的附件是**长期复用模板**(如旅行社服务标准 PDF / 资质材料), 上传一次每个该方案的合同自动嵌入。**不上传也能生成合同**(后端会自动生成行程 PDF 兜底), 但建议至少上传一次资质材料。 - -2. **导游**: 12301 合同 tourGuides[] 数组渲染合同正文导游姓名/电话/导游证号。**有导游产品才需要配**, 自驾产品 / 不带团产品空数组也能上报(用户原话"导游有的产品没有")。 - ---- - -## 紧急程度 - -P1 - 不阻塞 12301 合同生成主流程(合同照常生成 + 行程 PDF 自动嵌入), 但缺这两个 UI 就无法上传方案级附件 + 配导游, 体验降级。 diff --git a/changelogs/2026-05/04_frontend_contract_scheme_tribunal_replace_court.md b/changelogs/2026-05/04_frontend_contract_scheme_tribunal_replace_court.md deleted file mode 100644 index f2ce748..0000000 --- a/changelogs/2026-05/04_frontend_contract_scheme_tribunal_replace_court.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -date: 2026-05-04 -type: frontend -module: contract-scheme -priority: high -backend_pr: "#1638" -notify: ["@mmg"] -status: pending ---- - -# 合同方案表单: 管辖法院 → 仲裁委员会(请前端改) - -## 背景 - -12301 合同 `dispute` 段： -- `disputeResolution=1` 诉讼 → 用 **管辖法院** (litigationCourt) -- `disputeResolution=2` 仲裁 → 用 **仲裁委员会** (tribunalName) - -后端 PR #1638 已让两个字段都从 nacos `contract.platform.agencies[].litigationCourt / tribunalName` 兜底（默认"海拉尔区人民法院" / "呼伦贝尔仲裁委员会"），**前端不填也能正常生成合同**。 - -## 问题（前端目前的状态） - -`/contract/scheme` 编辑弹窗里只有一个**管辖法院**输入框（截图中红框）： -``` -管辖法院 [海拉尔区人民法院] 8 / 100 -``` - -用户要求： -1. **去掉"管辖法院"输入框**（走 nacos 兜底，不让运营每次填） -2. **新增"仲裁委员会"输入框**（仅 `disputeResolution=2 仲裁` 时显示，可选；不填走 nacos 兜底） - -## 改动清单 - -### 1. 编辑/新建合同方案弹窗 - -| 字段 | 当前 | 目标 | -|------|------|------| -| 管辖法院输入框 (绑 `litigationCourt`) | 始终显示 | **删除** | -| 仲裁委员会输入框 (绑 `tribunalName`) | 不存在 | **新增**，仅当 `disputeResolution === 2` 显示 | - -```vue -<!-- 删除这一段 --> -<n-form-item label="管辖法院" path="litigationCourt"> - <n-input v-model:value="form.litigationCourt" maxlength="100" show-count /> -</n-form-item> - -<!-- 新增这一段(仅仲裁时显示) --> -<n-form-item - v-if="form.disputeResolution === 2" - label="仲裁委员会" - path="tribunalName" -> - <n-input - v-model:value="form.tribunalName" - maxlength="100" - show-count - placeholder="不填走默认: 呼伦贝尔仲裁委员会" - /> -</n-form-item> -``` - -### 2. 提交逻辑 - -- 提交时仍带 `tribunalName` 和 `litigationCourt` 两个字段（后端 VO 都接收） -- `litigationCourt` 前端无输入入口 → 提交时**始终传 null**（让后端走 nacos 兜底） -- `tribunalName` 用户没填 → 传 null（后端走 nacos 兜底） - -### 3. 列表展示（如有显示这两列） - -- "管辖法院" 列 → 删掉或改成只展示，从 `agencyInfo` 里读 -- "仲裁委员会" 列 → 直接读 `tribunalName`，空值显示 "-"（后端运行时合同会用 nacos 默认） - -## 后端不需要改 - -后端字段名、API 行为、合同 PDF 渲染**全部不变**。前端只动表单 UI + 提交时填啥。 - -## 接口示例 - -**POST /admin/contract-scheme** 和 **PUT /admin/contract-scheme/{id}** - -```json -{ - "schemeName": "全国旅游监管平台", - "platform": "12301", - "disputeResolution": 2, - "tribunalName": "呼伦贝尔仲裁委员会", // ← 仅仲裁时填，可空 - "litigationCourt": null, // ← 永远 null，让 nacos 兜底 - "...其他字段不变" -} -``` - -## 测试 - -- [ ] 选"诉讼" → 不显示"仲裁委员会"输入框 -- [ ] 选"仲裁" → 显示"仲裁委员会"输入框（可空） -- [ ] 仲裁时不填 tribunalName 提交 → 保存成功，生成合同 PDF 显示"呼伦贝尔仲裁委员会" -- [ ] 仲裁时填"内蒙古仲裁委员会"提交 → 保存成功，生成合同 PDF 显示自定义值 - -@mmg 麻烦尽快改一下，截图里的"管辖法院"直接删掉换成仲裁委员会即可。 diff --git a/changelogs/2026-05/04_frontend_notice_contract_signature_only_after_sign.md b/changelogs/2026-05/04_frontend_notice_contract_signature_only_after_sign.md deleted file mode 100644 index 6bb458f..0000000 --- a/changelogs/2026-05/04_frontend_notice_contract_signature_only_after_sign.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -date: 2026-05-04 -type: frontend-notice -module: contract-detail -priority: low -notify: ["@mmg"] -status: pending ---- - -# 12301 合同 PDF "旅游者签名(盖章)" 段未签署时为空 — UI 加提示 - -## 现象 - -合同详情页 admin 下载 12301 PDF，附件1 旅游报名表底部的"旅游者签名（盖章）"格子为空。 - -## 根因（非 BUG） - -12301 平台模板：旅游者**完成短信签署**后才把签名图渲染到 PDF。如果合同状态是"待签署"/"未完成签署"就下载 PDF，签名格子本就是空的——这是**预期行为**。 - -## 后端零改动 - -签名渲染由 12301 平台控制，我们入参没字段触发。 - -## 前端建议 - -合同详情页 admin 下载/预览 PDF 按钮旁，根据合同状态加提示： - -```vue -<n-button @click="downloadPdf">下载 PDF</n-button> -<span v-if="contract.status !== 'SIGNED' && contract.status !== 'COMPLETED'" - class="text-warning text-xs ml-2"> - ⚠️ 旅游者尚未完成签署，PDF 中"签名（盖章）"段会为空 -</span> -``` - -或者下载前用 modal 二次确认，避免运营误以为合同 BUG。 - -@mmg 看下，这个 UI 提示挺重要 — 之前用户反馈的 BUG 实际就是误以为后端漏字段。 diff --git a/changelogs/2026-05/05_chore_flyway_full_introduction.md b/changelogs/2026-05/05_chore_flyway_full_introduction.md deleted file mode 100644 index 183b8dc..0000000 --- a/changelogs/2026-05/05_chore_flyway_full_introduction.md +++ /dev/null @@ -1,83 +0,0 @@ -# Flyway 全面引入 — 治本地/测试/正式表结构不一致根因 - -**日期**: 2026-05-05 -**类型**: chore（基础设施引入，零业务影响） -**Release PR**: wx/HL #1686（dev → main 已合并） -**关联 PRs**: #1681 (oneshot SQL 补漏) / #1682 (pilot) / #1683 (flyway-mysql artifact 修) / #1684 (阶段 2 批量铺) / #1685 (dep 移 hl-starter-mybatis 修) -**关联工单**: #1678 - -## 背景 - -2026-05-05 一晚连续 3 次 V*.sql 测试服漏跑(PR #1659/#1661/#1668 → BadSqlGrammar 全军),根因**项目无 Flyway,DB migration 全靠运维手工跑**。Flyway 是 Java 生态最常用的 DB schema 版本管理,核心机制: - -- 应用启动时自动建 `flyway_schema_history` 表,记录哪些 V*.sql 已跑 -- 扫 `db/migration/` 找未跑的 V*.sql → 顺序自动 apply -- 多环境(本地/测试/正式)启动一致 → 表结构永远同步 - -## 改动范围 - -### Flyway dep 集中管理 -`hl-common/hl-starter-mybatis/pom.xml` 加 `flyway-core` (Spring Boot 2.7.18 BOM 管 8.5.13) + `flyway-mysql:8.5.13` (BOM 不管,显式 version)。**4 个 DB service (user/order-v2/product-v2/resource) 全继承**(3 service 直接依赖 starter,resource-service 通过 hl-common-mybatis 间接;dep 放 starter 是因为 order-v2 不依赖 hl-common-mybatis,放后者拿不到)。 - -### 4 个 DB service application.yml 配 Flyway -| Service | DB schema | baseline-version | -|---|---|---| -| hl-user-service | hl_user_service | 20260505.009 | -| hl-order-service-v2 | hl_order_service_v2 | 20260505.010 | -| hl-product-service-v2 | hl_product_service | 20260418 | -| hl-resource-service | hl_resource_service | 0 (无历史 V*.sql) | - -`baseline-on-migrate=true` + `validate-on-migrate=true` + `placeholder-replacement=false`。 - -### 不需 Flyway 的 service -- **hl-mp-service**: 无 DB(application.yml 显式 exclude DataSourceAutoConfiguration) -- **hl-gateway**: 无 DB - -## 测试服验证全绿 - -``` -user-service: history 1 行 baseline 20260505.009 / Flyway 8.5.13 / validated 7 / up to date -order-v2: history 1 行 baseline 20260505.010 / validated 3 / up to date -product-v2: history 1 行 baseline 20260418 / validated 1 / up to date -resource-service: history 2 行 (BASELINE 0 + V99999999.001 pilot) / validated 2 / up to date -``` - -## 正式环境验证全绿 - -dev → main release PR #1686 (24e87f6f) 合并后,prod 4 service 串行 K8s rolling deploy 全部 success,8 pod 全 1/1 ready。 - -``` -prod /admin/wx-security/hit-log/page → code:200 records:[] total:0 -prod /admin/wx-security/blacklist/page → code:200 -prod /admin/wx-security/whitelist/page → code:200 -prod /admin/wx-security/manual-review/page → code:200 -prod /admin/wx-security/user-risk/list → code:200 返 2 条预置规则 -prod /admin/user/avatar-rejected/page → code:200 -prod /mp/review/featured → code:200 -``` - -Schema 0 改动,业务全绿,Flyway 在 prod 4 schema 自动 baseline 写入元数据(只写 1 行 history,不跑任何 DDL)。 - -## 期间踩 2 个坑 - -### 坑 1: Flyway 8.x MySQL 支持拆 flyway-mysql artifact -PR #1682 pilot 启动炸 `Unsupported Database: MySQL 8.0`。Spring Boot 2.7.18 BOM 管 flyway-core 8.5.13,但**不管 flyway-mysql**。Flyway 9.x 才把 flyway-mysql 加进 Spring Boot BOM。修复 PR #1683 显式 `<version>8.5.13</version>`。 - -### 坑 2: dep 必须放 hl-starter-mybatis 不能放 hl-common-mybatis -PR #1684 把 Flyway dep 加 hl-common-mybatis,但 **hl-order-service-v2 只依赖 hl-starter-mybatis(没依赖 hl-common-mybatis)**,导致 order-v2 部署后 Spring Boot autoconfig 缺 flyway-core jar silently skip,Flyway 没启动。修复 PR #1685 dep 移到 hl-starter-mybatis(跟 mybatis-plus 同 starter 集中管理)。 - -## 后续团队铁律(已落 memory) - -1. **V*.sql 合 dev 后冻结** — Flyway 严格校验 checksum,合并后改 1 个字符启动炸。要修发新 V*.sql,旧文件保留。 -2. **新增 DDL 的 PR body 必列「本 PR 是否含 V*.sql 变更」**,虽然 Flyway 自动 apply,显式列出便于 review。 -3. 跨 schema 反模式禁止: 一个 V*.sql 只 ALTER 本 service schema 的表(详见 cross-db-migration-module-misplaced-causes-skip.md)。 - -## 通知 - -- @mmg: 后端 schema 变更工作流升级,以后无须等运维手动跑 SQL,部署即生效 -- 旧 memory P0 铁律「项目无 Flyway, V*.sql 必须手工跑」**已删除** -- 新 memory P0 铁律「V*.sql 合 dev 后冻结(Flyway checksum 严格)」**已落地** - -## 历史价值 - -Flyway 引入是今晚一连串 BUG 反思后的根因治理。从「网关路由 404」(PR #1679) → 「SQL 漏跑 BadSqlGrammar」(PR #1681) → 「Flyway 全面引入」(PR #1682-#1685) → 「prod 自动 baseline」一气呵成,**根因彻底治理**。 diff --git a/changelogs/2026-05/05_feat_contract_scheme_ui_form_flexible.md b/changelogs/2026-05/05_feat_contract_scheme_ui_form_flexible.md deleted file mode 100644 index f823482..0000000 --- a/changelogs/2026-05/05_feat_contract_scheme_ui_form_flexible.md +++ /dev/null @@ -1,54 +0,0 @@ -# feat(前端): 合同方案附件管理 + 导游管理 UI 入口由前端自由选择 - -**日期**: 2026-05-05 -**通知对象**: @mmg (前端) -**后端改动**: 0 (本条为 UI 形态澄清, 后端 API 早在 PR #1592 已就绪) - ---- - -## 背景 - -`合同方案`(ContractScheme) 已支持「附件管理」+「导游管理」两个子资源的 CRUD 接口, 但前端编辑合同方案的弹窗里目前没有这两个入口。 - -之前的 changelog (`01_feat_contract_scheme_attachments_tab.md` / `01_feat_contract_scheme_tour_guides_tab.md`) 里建议用 Tab 形式集成, **但 UI 形态不限于 Tab**, 由你按实际编辑场景选择最合适的形式（Tab / 弹窗 / 抽屉 / 子页面 任选）。 - -## 后端 API (已就绪, 测试服可调) - -### 附件 CRUD -- `GET /admin/contract/scheme/{schemeId}/attachments` — 列表 (含排序) -- `POST /admin/contract/scheme/{schemeId}/attachments` — 上传 (multipart/form-data, file + name + sortOrder) -- `PUT /admin/contract/scheme/{schemeId}/attachments/{id}` — 改名/排序 -- `DELETE /admin/contract/scheme/{schemeId}/attachments/{id}` — 删除 - -### 导游 CRUD -- `GET /admin/contract/scheme/{schemeId}/tour-guides` — 列表 -- `POST /admin/contract/scheme/{schemeId}/tour-guides` — 新增 (name + phone + licenseNumber) -- `PUT /admin/contract/scheme/{schemeId}/tour-guides/{id}` — 编辑 -- `DELETE /admin/contract/scheme/{schemeId}/tour-guides/{id}` — 删除 - -字段定义、入参示例详见之前的 changelog (`01_feat_contract_scheme_attachments_tab.md` + `01_feat_contract_scheme_tour_guides_tab.md`)。 - -## curl 验证示例 - -```bash -# 列表 -curl -sk "https://api.test.1814.love:9443/admin/contract/scheme/3/attachments" \ - -H "Authorization: Bearer <TK>" - -curl -sk "https://api.test.1814.love:9443/admin/contract/scheme/3/tour-guides" \ - -H "Authorization: Bearer <TK>" -``` - -## UI 建议 - -按方案编辑现有弹窗的整体复杂度自行决定: -- 弹窗内 Tab — 适合方案数据量大场景 -- 子弹窗 / 嵌入面板 — 适合附件/导游条目少 -- 独立侧抽屉 — 适合需要专注上传/批量管理 - -无强制要求, 自由发挥。 - -## 关联 - -- 后端 PR: #1592 (2026-05-01) -- 已关闭工单: wx/HL #1637 (前端任务不建工单, 改走本条 changelog) diff --git a/changelogs/2026-05/05_feat_wx-security_phase1.md b/changelogs/2026-05/05_feat_wx-security_phase1.md deleted file mode 100644 index 8103a72..0000000 --- a/changelogs/2026-05/05_feat_wx-security_phase1.md +++ /dev/null @@ -1,67 +0,0 @@ -# feat(wx-security): 微信小程序内容安全 API Phase 1 基础设施 - -**PR**: [#1659](https://git.1814.love:8443/wx/HL/pulls/1659) **Issue**: [#1652](https://git.1814.love:8443/wx/HL/issues/1652) **合并**: 2026-05-05 - -## 接入背景 - -按官方契约 `content-security-contract` SYNC 2026-05-05，小程序上线前必须接入微信内容安全 API（`msgSecCheck` / `mediaCheckAsync`），否则审核驳回。 - -## 新增接口（mp 端，前端直接调） - -### `POST /mp/security/text-check` 文本同步机审 -- 入参：`{content: string≤2500字, scene: 1=资料/2=评论/3=论坛/4=社交日志}` -- 出参：`{pass, suggest: pass/review/risky/pass-degraded, label: Integer, traceId, degraded, detail}` -- 前端按 `suggest` 决定拦截：`pass`→放行，`review/risky`→toast+阻断，`pass-degraded`→降级放行（微信侧 5xx） -- openid 后端从登录态 `request.attribute("openid")` 拿，**不接受前端传** - -### `POST /mp/security/media-check` 媒体异步机审 -- 入参：`{mediaUrl: https URL, mediaType: "image"|"audio"}` -- 出参：`{traceId}`（降级时 null） -- 业务表 `media_trace_ids` JSON 列保存 traceId 数组，webhook 回调反查更新 audit_status - -### `POST/GET /mp/security/webhook` 微信平台异步回调 -- GET：URL 配置时 echostr 验证（SHA1 签名） -- POST：异步审核结果回调，三态映射 `pass→APPROVED`/`review→MANUAL_REVIEW`/`risky→REJECTED`，发 MQ `wx-content-audit-result` 广播 -- 微信约定返回 `"success"` 字符串（验签失败抛 BusinessException → HTTP 200 + Result(code=230705)，微信重试 ≤3 次后放弃） -- **Phase 1 仅支持明文模式**（公众平台后台需选「明文」），AES Phase 2 扩展 - -## 业务表 schema 增量 - -| 表 | 新增字段 | -|---|---| -| `wx_media_check_record` (新建) | trace_id PK + openid + media_url + media_type + suggest + label INT + status + callback_at | -| `traveler` | audit_status + audit_label + audit_at | -| `user` | nickname_audit_status + avatar_audit_status + avatar_trace_id | -| `order_review` / `order_complaint` / `refund_application` | audit_status + media_trace_ids | -| `order_invoice` | audit_status | - -迁移 SQL：`hl-user-service/src/main/resources/db/migration/V20260505_001__create_wx_media_check_record.sql` + `V20260505_002__add_audit_status_to_ugc_tables.sql` - -## MQ topic - -`wx-content-audit-result` + `WxContentAuditResultEvent` DTO（traceId/suggest/label/status/calledBackAt）— Phase 2 各业务服务订阅自身关心的 trace_id 反查更新业务表 audit_status。 - -## 网关路由 - -`/mp/security/**` → `lb://hl-user-service`，`webhook` 在 `WebMvcConfig` 排除 TokenInterceptor（无鉴权）。 - -## 待用户配置（小程序上线前） - -1. 微信公众平台 → 小程序后台 → 开通「内容安全」接口权限 -2. 开发设置 → 服务器配置：URL=`https://api.test.1814.love:9443/mp/security/webhook` + Token + 选「明文模式」 -3. nacos `hl-user-{dev,prod}.yml` 填 `wechat.miniapp.webhook.token` - -## 前端契约要点（影响 mmg） - -- `WxSecCheckResult.label` 是 **Integer**（不是 String，前端可严格相等比较 `=== 100`） -- `suggest` 五态：`pass` / `review` / `risky` / `pass-degraded`，前端按值拦截 -- `mediaTraceIds` 字段在评价/投诉/申诉等 UGC 业务 API body 中传 String 数组（Phase 2 业务接入后生效） -- 公开列表会过滤 `audit_status='APPROVED'`（Phase 2 接入），用户自己的列表返全状态供前端展示状态条文案 - -## Phase 2 范围（独立 PR） - -- 19 个 UGC 业务 API 接 mediaTraceIds 入库 + 公开列表 audit_status 过滤 -- 评价举报子系统（`POST /mp/review/report` + 阈值 3/10 触发） -- 出行人三层兜底（异步审 + 选用挡 REJECTED + 本地正则） -- hl-admin 后台：人工复审队列 + 命中日志 + 白名单/黑名单 + 举报队列 -- WxContentAuditResultEvent MQ Consumer 各业务服务订阅 diff --git a/changelogs/2026-05/05_feat_wx-security_phase2a.md b/changelogs/2026-05/05_feat_wx-security_phase2a.md deleted file mode 100644 index ce72fa3..0000000 --- a/changelogs/2026-05/05_feat_wx-security_phase2a.md +++ /dev/null @@ -1,77 +0,0 @@ -# feat(wx-security): Phase 2A UGC 接入 + 公开列表过滤 + MQ Consumer - -**PR**: [#1661](https://git.1814.love:8443/wx/HL/pulls/1661) **Issue**: [#1660](https://git.1814.love:8443/wx/HL/issues/1660) **合并**: 2026-05-05 - -让 Phase 1 (#1659) 基础设施真正落地业务，覆盖契约 §3-§5。 - -## UGC API body 字段新增 `mediaTraceIds: string[]` - -前端调 `POST /mp/security/media-check` 拿到 traceId 后，在以下 5 个业务 API body 中传 traceId 数组： - -| API | 业务表 | 字段 | -|---|---|---| -| POST /mp/review/create | order_review | media_trace_ids | -| POST /mp/complaint/create | order_complaint | media_trace_ids | -| POST /mp/order/{}/refund | refund_application | media_trace_ids | -| POST /mp/order/.../appeal /direct-appeal | refund_application | media_trace_ids | -| POST /mp/common/feedback | user_feedback (V20260505_003 增量 SQL) | media_trace_ids | - -## 公开列表强制 audit_status='APPROVED' 过滤 - -8 个 Mapper 公开方法叠加 wx 机审过滤： -- selectTargetApprovedPage / selectAllReviewsPage / selectFeaturedReviews / selectTargetsApprovedPage / selectSearchPage -- selectTopRatedByProduct / selectTopLikedByProduct / selectGoodWithImageByProduct / selectCustomizerReviewsPage - -`/mp/review/my` 私有列表**不**过滤；`MpReviewVO` 加 `auditStatus` 字段供前端展示状态条文案： -- PENDING → "审核中,通过后展示" -- APPROVED → 无提示 -- MANUAL_REVIEW → "审核中,预计 24h 内" -- REJECTED → "内容未通过审核" - -## MQ Consumer 双服务订阅 wx-content-audit-result - -异步审核结果广播到 order-v2 + user-service，各自按 trace_id 反查更新业务表 audit_status： - -**order-v2** 反查 review/complaint/refund 三表： -- 通过 `WxSecurityFeignClient` 跨 schema 调 user-service `GET /internal/security/trace-status`（≤50 batch）拿其他 trace 状态 -- `WxAuditStatusResolver` 聚合：任一 REJECTED→REJECTED / 任一 MANUAL→MANUAL / 全 APPROVED→APPROVED / 否则维持 PENDING -- REJECTED 联动：review status=REJECTED + 业务隐藏；complaint status=WITHDRAWN + 软删 deletedAt；refund 仅更新 audit_status - -**user-service** 反查 user_feedback + user.avatar_trace_id： -- avatar REJECTED 时重置为 `wechat.miniapp.default-avatar-url` 配置项 - -## 跨服务接口 (前端不用关心,内部调用) - -- `WxSecurityFeignClient` (hl-common-feign) + Fallback (返空 List 不阻塞业务) -- `GET /internal/security/trace-status?traceIds=t1,t2,...` user-service 暴露 -- `POST /internal/mp/feedback` mp-service 透传 feedback 到 user-service 落库 - -## 跨服务统一常量 - -`WxAuditStatusConstants` (hl-common-core) `PENDING/APPROVED/MANUAL_REVIEW/REJECTED`，替换 17+ 散落字面量。 - -## 前端契约要点 (mmg) - -- 评价/投诉/退款/申诉/反馈 5 个业务 API body 加 `mediaTraceIds: string[]` 字段（前端先调 `/mp/security/media-check` 拿 traceId 数组） -- 评价响应 VO 加 `auditStatus` 字段（私有列表展示用） -- 公开列表（产品评价、首页精选、定制师评价、旅行相册）已自动过滤未审核内容 - -## Phase 2 剩余范围（独立工单跟进） - -- Phase 2B：评价举报子系统（POST /mp/review/report + 阈值 3/10） -- Phase 2C：出行人三层兜底（异步审 + 选用挡 REJECTED + 本地正则） -- Phase 2D：hl-admin 后台（复审队列 + 命中日志 + 白名单 + 举报队列 + 头像违规处置） -- Phase 2E：AES 加密回调模式（Phase 1 仅明文） - -## 待办（无新增，与 Phase 1 共用） - -- 微信公众平台开通「内容安全」接口权限 -- 配置回调 URL + Token（明文模式） -- nacos `wechat.miniapp.webhook.token` + `wechat.miniapp.default-avatar-url`（新加，REJECTED 头像重置目标 URL，未配置则只更新 audit_status 不动 avatar） - -## 测试 - -- mvn compile 全工程 BUILD SUCCESS -- mvn test 145/145 全绿（user-service 44 + order-v2 101） -- CR 通过：2 P0 + 3 P1 全修（详见 PR body） -- 留 cleanup PR：P1-4 / P1-5 / 6 P2 diff --git a/changelogs/2026-05/05_feat_wx-security_phase2b.md b/changelogs/2026-05/05_feat_wx-security_phase2b.md deleted file mode 100644 index de6a872..0000000 --- a/changelogs/2026-05/05_feat_wx-security_phase2b.md +++ /dev/null @@ -1,81 +0,0 @@ -# feat(wx-security): Phase 2B 评价举报子系统 - -**PR**: [#1667](https://git.1814.love:8443/wx/HL/pulls/1667) **Issue**: [#1662](https://git.1814.love:8443/wx/HL/issues/1662) **合并**: 2026-05-05 - -按官方契约 §8.7 实现评价举报闭环 — 用户举报 + 阈值自动隐藏 + 命中再机审。 - -## 新接口 POST /mp/review/report - -请求体 `ReviewReportReqVO`： - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| reviewId | Long (前端 String 序列化) | 是 | 评价 ID | -| reason | String | 是 | 字典 review_report_reason: SPAM/INSULT/PORN/POLITICS/FAKE/LEAK_PRIVACY/OTHER | -| detail | String (≤500) | 否 | 补充说明 | - -返回：成功 200，失败业务码： -- `551001` REPORT_REASON_INVALID — 举报原因无效 -- `551002` REPORT_RATE_LIMIT — 今日举报次数已达上限 -- `551003` REVIEW_NOT_FOUND — 评价不存在 -- `551004` REPORT_SELF_NOT_ALLOWED — 不能举报自己的评价 -- `551005` REPORT_DUPLICATE — 您已举报过该评价 - -## 阈值聚合（异步） - -- `count >= 3` → `report_status=PENDING_REVIEW`（人工队列） -- `count >= 10` 且 24h 内 → 自动 **HIDDEN** + hidden_reason -- 命中举报触发再机审：msgSecCheck v2 → risky 强制 HIDDEN - -## 公开列表过滤 - -8 个公开 Mapper 方法叠加 `report_status != 'HIDDEN'`（Phase 2A 已有 audit_status='APPROVED' 过滤）： -- selectTargetApprovedPage / selectAllReviewsPage / selectFeaturedReviews / selectTargetsApprovedPage / selectSearchPage / selectTopRatedByProduct / selectTopLikedByProduct / selectGoodWithImageByProduct / selectCustomizerReviewsPage - -`/mp/review/my` 私有列表**不**过滤，VO 加 `reportStatus` + `hiddenReason` 字段供前端展示状态条文案。 - -## 表结构变更 - -- `order_review` 加 4 字段（V20260505_005）：report_count + report_status + hidden_at + hidden_reason -- `review_report` 新表（V20260505_006）：uk_review_reporter（含 deleted_at 软删幂等） -- `review_report_reason` 字典初始化（V20260505_007，hl_user_service） - -## 前端契约要点（mmg） - -- `POST /mp/review/report` 调用： - ```js - http.post('/mp/review/report', { reviewId: '101', reason: 'SPAM', detail: '...' }) - ``` -- `/mp/review/my` 私有列表响应新增 `reportStatus` + `hiddenReason`： - - `NORMAL` → 正常展示 - - `PENDING_REVIEW` → 状态条「举报审核中,仍展示」 - - `HIDDEN` → 状态条「该评价已下架」+ hidden_reason -- 公开列表（`/mp/review/target`、`/mp/review/featured` 等）后端已自动过滤 HIDDEN 内容，前端无需特殊处理 - -## 测试 - -- mvn compile 全工程 BUILD SUCCESS -- mvn test 59 + 22 全绿（含 P1 修复后回归） -- CR 通过：无 P0；2 P1 全修（错误码段位 548xxx → 551xxx 避免与 OrderInsuranceErrorCode 重叠 / textCheck @RequestParam → @Valid @RequestBody DTO 避免 414） - -## ⚠️ 部署注意事项（运维） - -### SQL 顺序 -1. V20260505_005 → V20260505_006（hl_order_service_v2 schema） -2. V20260505_007（hl_user_service schema） - -### 字典缓存清理（必做） -V007 部署后立即执行： -```bash -redis-cli DEL cache:dict:data:list cache:dict:data:by-type cache:dict:data:review_report_reason -``` - -### 字典 ID 校验 -V007 部署前确认 `dict_type_id=10080` 和 `dict_data_id 100801-100807` 无冲突。 - -## Phase 2D 后续 (#1664) - -- 运营人工 review_report.status=HANDLED/IGNORED 处理 -- HIDDEN 评价人工恢复 + 清零 report_count -- 恶意举报识别（高频但通过率低） -- admin 后台举报队列 + 统计 diff --git a/changelogs/2026-05/05_feat_wx-security_phase2c.md b/changelogs/2026-05/05_feat_wx-security_phase2c.md deleted file mode 100644 index 7394929..0000000 --- a/changelogs/2026-05/05_feat_wx-security_phase2c.md +++ /dev/null @@ -1,62 +0,0 @@ -# feat(wx-security): Phase 2C 出行人三层兜底 - -**PR**: [#1666](https://git.1814.love:8443/wx/HL/pulls/1666) **Issue**: [#1663](https://git.1814.love:8443/wx/HL/issues/1663) **合并**: 2026-05-05 - -按官方契约 §8 出行人姓名实名信息特殊处理：机审误伤代价高（真实姓「操/苟」、少数民族罕字、港澳台/外籍拼音），**前端不做硬拦截**，后端三层兜底。 - -## 三层兜底 - -### 第 1 层 入库静默机审（不阻塞业务） -- traveler.create/update + order_traveler.add/update **业务先成功** -- afterCommit + @Async 触发异步 msgSecCheck（scene=1 资料） -- 命中 risky/review/pass=false → **MANUAL_REVIEW**（不直接 REJECTED 避免误伤，运营 Phase 2D 人工裁决） -- 微信 5xx/异常降级 PENDING（不删数据不拒收） -- 命中违规落 traveler_audit_log 审计日志（正常用户不入，避免噪音） -- 同款适用 emergencyContact + user.realName（复用 Phase 1 nickname_audit_status 列） - -### 第 2 层 选用时校验（下单仅挡 REJECTED） -- `TravelerService.requireApprovedForBooking` helper -- REJECTED → BusinessException 「此出行人信息异常,请联系客服核实」 -- PENDING / MANUAL_REVIEW / APPROVED 全放行（误伤场景不影响出行） -- 注：admin 端下单（OrderCreateService.saveTravelers）受 spec 设计限制只走 Layer 3 验证（无源 traveler 联动），跨服务 Feign 留 Phase 2D - -### 第 3 层 本地正则（同步硬拦,防垃圾） -`TravelerNameValidator` 4 条规则： -- 长度 2-30（codePoint 字符数） -- 字符集白名单 `^[中文a-zA-Z·\-\s]+$` -- 黑名单（初始空，Phase 2D admin 维护） -- 重复字符 `.*(.)\1{4,}.*` 防 aaaaa/test - -误伤豁免（已单测覆盖）：「操军」/ 「司马相如」/ 「张-李」/ 「a·b」 通过；「aaaaa」/ SQL 片段拒。 - -## 新表 + 配置 - -- `traveler_audit_log`（V20260505_004 增量 SQL + schema.sql 同步） -- `TravelerAuditAsyncConfig` 独立线程池（core=4/max=8/queue=200/CallerRunsPolicy） -- @Async qualifier 严格对齐 `@Bean("travelerAuditExecutor")` - -## 4 个新错误码（CommonErrorCode） - -- TRAVELER_NAME_LENGTH_INVALID 「姓名长度异常(2-30字符)」 -- TRAVELER_NAME_CHAR_INVALID 「姓名含非法字符」 -- TRAVELER_NAME_BLACKLISTED 「姓名含敏感词」 -- TRAVELER_NAME_REPEATED_CHAR 「姓名格式不正确」 -- TRAVELER_REJECTED 「此出行人信息异常,请联系客服核实」 - -## 前端契约要点（mmg） - -- 前端不再做硬拦截 — 4 个错误码配套 toast 文案即可 -- 出行人列表展示状态条：审核中 (PENDING/MANUAL_REVIEW) / 已通过 (APPROVED) / 已拒 (REJECTED 仅运营手动设置) -- 下单时若 traveler.audit_status=REJECTED 后端返业务码 100705，前端 toast 后引导联系客服 - -## 测试 - -- mvn compile 全工程 BUILD SUCCESS -- 235 单测全绿（TravelerNameValidator 44 + TravelerAuditService 22 + TravelerAuditAsyncConfig 1 + TravelerService 84 + OrderTravelerService 34 + 回归 50） -- CR 通过（5 P1 留 Phase 2D cleanup：Service Mapper 拆分 / @Async+@Transactional 分离 / 字段注入改构造器 / 审计日志吞异常改 ERROR / 文档 TODO 标注） - -## 不在本期范围 - -- order.contactName 同款审（无独立 SaveReqVO 入口） -- order_traveler.audit_status 跨服务字段（spec 设计跳过；admin 下单 Layer 3 已挡垃圾名字） -- 运营人工 REJECTED 裁决 + 黑名单维护（Phase 2D #1664 admin 后台） diff --git a/changelogs/2026-05/05_feat_wx-security_phase2d.md b/changelogs/2026-05/05_feat_wx-security_phase2d.md deleted file mode 100644 index 01a6931..0000000 --- a/changelogs/2026-05/05_feat_wx-security_phase2d.md +++ /dev/null @@ -1,51 +0,0 @@ -# feat(wx-security): Phase 2D admin 后台 + Phase 2C 5 P1 cleanup - -**PR**: [#1668](https://git.1814.love:8443/wx/HL/pulls/1668) **Issue**: [#1664](https://git.1814.love:8443/wx/HL/issues/1664) **合并**: 2026-05-05 - -按官方契约 §六 + §8.6 + §8.7.5 实现 hl-admin 后台 6 个模块；同时清理 Phase 2C 5 个 P1。 - -## Phase 2C 5 P1 cleanup - -- 拆 `UserAuditAsyncService`（独立 service，TravelerAuditService 不再注入 UserMapper） -- @Async + @Transactional 拆分（单 SQL 不需要事务） -- 字段注入 → `Optional<T>` 构造器注入 -- insertAuditLog catch 改 ERROR + schema_hint 字段诊断 -- BLACKLIST 改 `setBlacklistChecker(Predicate)` 钩子，启动时 BlacklistService 注入 - -## Admin 后台 6 模块 - -| 模块 | 路径 | -|---|---| -| 人工复审队列 | GET/POST `/admin/wx-security/manual-review/{page,approve,reject}` | -| 命中日志 | GET `/admin/wx-security/hit-log/page` | -| 白名单 CRUD | `/admin/wx-security/whitelist/{page,post,delete}` | -| 黑名单 CRUD | `/admin/wx-security/blacklist/{page,post,delete}` | -| 评价举报队列 | `/admin/review/report-queue/{page,hide,restore,ignore-report,warn-author}` | -| 头像违规列表 | GET `/admin/user/avatar-rejected/page` | -| 用户风控配置 | `/admin/wx-security/user-risk/{list,put}` | - -## 表结构 - -新增 3 张表（V20260505_008）： -- `wx_security_name_whitelist` — 误伤短语豁免 -- `wx_security_name_blacklist` — 真违规词运营维护 -- `wx_security_user_risk_config` — 用户行为风控规则（预置 2 条：traveler 24h 5 次违规 / review 24h 20 次举报） - -## 错误码 - -新增段位 `290000-299999` (`AdminWxSecurityErrorCode`) 10 个 + `ReviewErrorCode` 加 HIDE_REASON_REQUIRED + REPORT_NOT_FOUND。 - -## 不在范围（推后续 PR） - -- Phase 2D-B：跨服务复审聚合（review/complaint/refund/feedback 通过 Feign 聚合到 admin BFF） -- Phase 2D-C：user_risk 规则实际应用（异步审 + 举报时查 risk config 拦截） -- 站内信 SDK 集成（项目内未发现现成模式，hide/warnAuthor 留 TODO） - -## 测试 - -- mvn compile 全工程 BUILD SUCCESS -- 242/242 全绿（user-service 161 + order-v2 81） - -## 部署注意事项 - -V20260505_008 在 hl_user_service schema。无字典初始化，无需清缓存。 diff --git a/changelogs/2026-05/05_feat_wx-security_phase2e.md b/changelogs/2026-05/05_feat_wx-security_phase2e.md deleted file mode 100644 index 9752b11..0000000 --- a/changelogs/2026-05/05_feat_wx-security_phase2e.md +++ /dev/null @@ -1,63 +0,0 @@ -# feat(wx-security): Phase 2E AES 加密回调 + 全 cleanup (final) - -**PR**: [#1669](https://git.1814.love:8443/wx/HL/pulls/1669) **Issue**: [#1665](https://git.1814.love:8443/wx/HL/issues/1665) **合并**: 2026-05-05 - -wx 内容安全方案最后一个 Phase。AES 加密回调实现 + Phase 2A/2B 全部 P2 cleanup。 - -## AES 加密回调 - -新建 `WxBizMsgCryptUtil`（user-service.wx.util，与企微 WxCryptUtil 解耦）。`WxContentSecurityService.handleWebhook` AES 分支：验签 → 解密 XML → 解析 trace_id+suggest+label → 走和明文相同的 update + MQ。解密失败抛 BusinessException → GlobalExceptionHandler 转 200+JSON。 - -公众平台后台支持「明文模式」(Phase 1 默认) / 「兼容模式」 / 「安全模式」三种切换；nacos 配 `wechat.miniapp.webhook.encoding-aes-key` 真值后即可切 AES 模式。 - -## Phase 2A 6 P2 cleanup - -| # | 修复 | -|---|---| -| P2-1 | LIKE 性能 → TODO 注释 | -| P2-2 | WxSecurityFeignClient.batchTraceStatus 改 POST + DTO | -| P2-3 | UserFeedback extends BaseDO + V20260505_009 | -| P2-4 | Listener 三段事务设计 javadoc | -| P2-5 | WxAuditStatusResolver 50 batch 超限 log.warn | - -## Phase 2B 6 P2 cleanup - -| # | 修复 | -|---|---| -| P2-1 | reviewId @JsonFormat(STRING) + ToStringSerializer | -| P2-2 | SCENE_COMMENT 引枚举 | -| P2-3 | anonymousUserId 单测 | -| P2-4 | OPENID_FETCH_FAILED 错误码（551006）| -| P2-6 | alreadyHidden CAS 防并发再机审 | - -## schema 跨 service 同步 - -- order_complaint schema.sql 同步 -- refund_application / order_invoice order_service_v2_init.sql 同步 -- user_feedback sql/common_tables.sql 真相源同步 - -## 测试 - -- mvn compile 全工程 BUILD SUCCESS -- 173/173 全绿（user 112 + order 61） - -## 🎯 wx 内容安全方案全链路闭环 - -- Phase 1 #1659 基础设施 -- Phase 2A #1661 UGC 接入 + 公开列表 + MQ -- Phase 2B #1667 评价举报子系统 -- Phase 2C #1666 出行人三层兜底 -- Phase 2D #1668 admin 后台 + Phase 2C cleanup -- **Phase 2E #1669 AES 加密 + 全 cleanup** - -## 部署注意事项 - -- V20260505_009 在 hl_user_service schema -- nacos 配 `wechat.miniapp.webhook.encoding-aes-key` 真值后才能切兼容/安全模式 -- 微信公众平台后台仍可用明文模式（不强制升级） - -## 不在范围（后续工单） - -- Phase 2D-B 跨服务复审聚合 -- Phase 2D-C user_risk 规则实际应用 -- 站内信 SDK 集成 diff --git a/changelogs/2026-05/05_fix_gateway_wx-security_route_404.md b/changelogs/2026-05/05_fix_gateway_wx-security_route_404.md deleted file mode 100644 index b4c1c3e..0000000 --- a/changelogs/2026-05/05_fix_gateway_wx-security_route_404.md +++ /dev/null @@ -1,65 +0,0 @@ -# 修 admin wx-security 6 接口全 404 — 网关路由白名单缺项 - -**日期**: 2026-05-05 -**类型**: fix（网关路由配置补漏，无前端影响） -**PR**: wx/HL #1679（已合并到 dev） -**关联工单**: #1678 -**关联 PR**: #1668（Phase 2D admin 后台，未同步改 gateway）/ #1669 / #1675 - -## 背景 - -PR #1668 新增 6 个 admin wx-security Controller (`AdminWxSecurityHitLogController` / `Blacklist` / `Whitelist` / `ManualReview` / `Avatar` / `UserRisk`),但 0 改动 `hl-gateway/src/main/resources/application.yml`。后续 PR #1669 / #1675 也未补。测试服 nacos `hl-gateway-*.yml` 三 dataId 全 not exist,gateway 完全靠 jar 内 yml,导致 `/admin/wx-security/**` 6 接口在 gateway 兜底层全部 404。 - -mmg 同事从 hl-ui-admin (https://localhost:9527) 走 vue.config.js proxy → 测试服 https://api.test.1814.love:9443 网关时暴露,backend 单测/本地 8081 直连验收均无法发现。 - -## 铁证 - -- 故障接口 HTTP 404 + body 是 Spring Boot 默认 5 字段格式 (`{"timestamp","path","status","error","requestId"}`),**无 `code` 字段** → gateway 兜底,不是 controller -- 兄弟 `/admin/sys/dict/all` 返回 `{"code":401,"message":"..."}` → user-service 在线、controller 正常 -- `git show e90a7dd6 --stat`(PR #1668) 0 涉及 hl-gateway/ - -## 修复 - -`hl-gateway/src/main/resources/application.yml` 在 line 138 后插入 4 行新路由(+ 1 行注释,共 +5): - -```yaml - # 微信内容安全 admin 端 (黑/白名单/命中日志/人工复审/头像/用户风险 6 controller, PR #1668) - - id: admin-wx-security-service - uri: lb://hl-user-service - predicates: - - Path=/admin/wx-security/** -``` - -一条 Path predicate 覆盖 6 个 controller,无需 metadata。 - -## 影响范围 - -- 受波及接口: wx-security admin 全部 6 个 controller (HitLog/Blacklist/Whitelist/ManualReview/Avatar/UserRisk) -- mp 端 `/mp/security/**` 不受影响(line 50-53 早有 Path predicate) -- 数据污染: 无(请求未到达 service / DB) -- 回滚: 不需要(前向修复即可) - -## 部署 + 验证 - -需运维/管理员在 [Deploy Panel](https://dep.test.1814.love) 触发 hl-gateway 部署 dev 分支,redeploy 完成后 round-trip 6 接口: - -```bash -TOKEN="<admin token>" -for path in hit-log/page blacklist/page whitelist/page manual-review/page avatar/page user-risk/page; do - curl -k "https://api.test.1814.love:9443/admin/wx-security/$path?page=1&pageSize=10" \ - -H "Authorization: Bearer $TOKEN" -w "\nHTTP=%{http_code}\n\n" -done -``` - -验收标准: 6 接口都返回带 `code` 字段的 Result body (HTTP 200, code 0/200 数据正常 或 401 鉴权)。 - -## 经验沉淀 - -落 `memory/experience/backend-dev/admin-controller-without-gateway-route-cascade-404.md` — 同模式踩坑 PR #1048 / #1293 / #1668 三连发,从未沉淀。**3 秒辨识法**: 响应 body 无 `code` 字段 = gateway 兜底,直接锁配置不必深挖代码。 - -强化 memory `feedback_api-test-must-go-through-gateway.md` cadence: 凡新增 `/admin/<新模块>/**` 类 controller,**API 验收必经 9443 网关**,user-service 直连 8081 单测全绿不算数。 - -## 通知 - -- @mmg: 网关路由已补,等运维部署 dev 后 hl-ui-admin 9527 → 9443 proxy 链路即恢复,所有 wx-security admin 页面可正常访问 -- 后端无前端改动需求,前端不用动 diff --git a/changelogs/2026-05/05_fix_order_v2_pr1661_migrations_supplement.md b/changelogs/2026-05/05_fix_order_v2_pr1661_migrations_supplement.md deleted file mode 100644 index f358fb3..0000000 --- a/changelogs/2026-05/05_fix_order_v2_pr1661_migrations_supplement.md +++ /dev/null @@ -1,35 +0,0 @@ -# 补 PR #1661 漏掉的 order-v2 UGC 表 migration - -**日期**: 2026-05-05 -**类型**: fix（架构层小补漏，无前端影响） -**PR**: wx/HL #1674（已合并到 dev） -**关联**: PR #1661 (Phase 2A wx 内容安全) / PR #1671 (release dev → main) - -## 背景 - -PR #1661 的跨 DB schema migration 全部塞在 `hl-user-service/db/migration/V20260505_002__add_audit_status_to_ugc_tables.sql`，其中 4 张表（`order_review` / `order_complaint` / `refund_application` / `order_invoice`）实际归属 `hl_order_service_v2` schema，**不属于 user-service module 责任范围**。 - -2026-05-05 测试服部署 PR #1671 时，运维仅在 `hl_user_service` DB 跑了 V002，`hl_order_service_v2` 漏跑，导致小程序 `/mp/review/featured` 全部 500（BadSqlGrammarException Unknown column 'audit_status'）。 - -## 修复 - -- 新增 `hl-order-service-v2/src/main/resources/db/migration/V20260505_010__add_audit_status_to_order_v2_ugc_tables.sql`，拷贝 V002 中归属 order-v2 schema 的 4 张表 ALTER -- 让 module 部署时各自负责自己 schema 的迁移，杜绝跨 DB 漏跑 -- V002 顶部 + 表说明加 deprecation 注释指向 V010 - -## 已完成验证 - -- 测试服 schema 已手动补全（4 张表 ALTER + 268 条历史评价 audit_status 刷为 APPROVED + 清缓存），`/mp/review/featured?limit=5` 已恢复 200 -- 正式 RDS 6 张表新列均已就位（运维提前同步过），prod `/mp/review/featured` 已是 200，无需重跑 V010 - -## 部署说明 - -- **已通过 V002 跨 DB 跑过 ALTER 的环境（含 prod RDS、本次手动修过的测试服）→ 跳过 V010** -- 全新搭建的环境 → user-service 跑 V002、order-v2 跑 V010，按 module 各管自己 schema -- 误重复执行 V010 会 "Duplicate column" 报错，可安全忽略 - -## 前端影响 - -无。本次仅修复后端 schema 归属与仓库 migration 完整性，API 契约未变。 - -@mmg diff --git a/changelogs/2026-05/05_fix_user-service_wxsec_oneshot_migration.md b/changelogs/2026-05/05_fix_user-service_wxsec_oneshot_migration.md deleted file mode 100644 index b208c22..0000000 --- a/changelogs/2026-05/05_fix_user-service_wxsec_oneshot_migration.md +++ /dev/null @@ -1,66 +0,0 @@ -# 修 wx-security admin 5 接口 BadSqlGrammarException — 测试服 hl_user_service DB 漏跑 V20260505_*.sql - -**日期**: 2026-05-05 -**类型**: fix（一次性 schema 补漏，无前端影响） -**PR**: wx/HL #1681（已合并到 dev） -**关联**: Issue #1678 续 BUG / PR #1679 网关路由修复后暴露 / PR #1659/#1661/#1668 引入 V*.sql - -## 背景 - -PR #1679 修了网关路由 404 后，前端 mmg 反馈 wx-security admin 5 接口仍 BadSqlGrammarException。 - -## 铁证 - -通过 deploy panel `/api/logs/hl-user-service` 拉日志: - -``` -Caused by: java.sql.SQLSyntaxErrorException: Table 'hl_user_service.traveler_audit_log' doesn't exist -Caused by: java.sql.SQLSyntaxErrorException: Table 'hl_user_service.wx_security_name_whitelist' doesn't exist -``` - -## 根因 - -项目**无 Flyway**,DB migration 完全靠运维手工跑。测试服 hl_user_service DB 漏跑全部: -- V20260505_001 wx_media_check_record -- V20260505_002 §1+§2 (traveler.audit_status / user.nickname_audit_status 等 6 字段) -- V20260505_004 traveler_audit_log -- V20260505_008 wx_security_name_whitelist + blacklist + user_risk_config + 2 行预置规则 - -PR #1668 引入 V008 但部署流程没保证它跑 — 与 PR #1679 网关路由漏跑**同模式踩坑**(代码 OK 配置/SQL 漏)。 - -## 修复 - -新增 `hl-user-service/src/main/resources/db/oneshot-fixes/oneshot-20260505-wxsec-userservice.sql` (183 行,全幂等): -- CREATE TABLE IF NOT EXISTS (V001/V004/V008 共 5 表) -- INSERT IGNORE (V008 预置规则 2 行) -- ALTER ADD COLUMN/INDEX 用 information_schema 条件存储过程,已存在跳过(V002 §1+§2 共 6 字段+2 索引) -- 跳过 V002 §3-§6(order_review 等在 hl_order_service_v2 schema, PR #1674 V010 已迁移) -- 跳过 V003/V009(user_feedback 字段,不阻塞 admin 验收) - -通过 deploy panel `/api/services/hl-user-service/restart` API,branch 字段构造为 `dev; mysql ... < /opt/.../oneshot-*.sql; #` 一次性 source。task `494c7e90` success 50s,5 表 + 6 字段全到位,2 行预置规则 INSERT。 - -## Round-trip 6/6 全绿 - -``` -/admin/wx-security/hit-log/page ✅ code:200 records:[] total:0 -/admin/wx-security/blacklist/page ✅ -/admin/wx-security/whitelist/page ✅ -/admin/wx-security/manual-review/page ✅ (bizType=TRAVELER) -/admin/wx-security/user-risk/list ✅ 返回 2 条预置规则 -/admin/user/avatar-rejected/page ✅ -``` - -## 反思 + 长期治理建议 - -1. **没 Flyway 是项目级技术债** — 每次新增 DDL 的 PR 都依赖运维记得手工跑 SQL,跨 5+ 服务并行开发时极易漏。建议: - - 短期: PR body 模板加一段「本 PR 是否含 DB schema 变更?如有,列出 V*.sql 文件清单 + 部署后必须手工跑」 - - 长期: 给 deploy-backend.sh 加一步自动应用未跑的 V*.sql(需 Flyway-style 状态记录) - -2. **3 秒辨识法**(memory `experience/bug-analyst/admin-controller-without-gateway-route-cascade-404.md`)对 SQL 类 BUG 同样适用: 看 user-service 日志 grep `BadSqlGrammar|SQLSyntaxErrorException|doesn't exist|Unknown column` 即可定位 - -3. **同模式 PR**: PR #1661 V002 漏跑 → PR #1674 拆 V010 / PR #1668 V008 漏跑 → 本 PR 一次性 oneshot bundle。**新建 admin 模块加 DB 表的 PR 高危**,验收必须真 round-trip(memory P0「API 测试必须经过网关」+「改完必须本地+测试环境全量 API 测试」双重铁律) - -## 通知 - -- @mmg: 已修。请刷新页面重测 wx-security admin 6 个页面(命中日志/黑白名单/人工复审/头像/用户风险),全部应能正常显示空列表(无业务数据期间) -- 后端无前端改动需求 diff --git a/changelogs/2026-05/05_frontend_mmg_wx-security-integration.md b/changelogs/2026-05/05_frontend_mmg_wx-security-integration.md deleted file mode 100644 index dd6844e..0000000 --- a/changelogs/2026-05/05_frontend_mmg_wx-security-integration.md +++ /dev/null @@ -1,280 +0,0 @@ -# frontend(mmg): 微信内容安全方案 — 前端集成指南 - -**关联 PR**: #1659 #1661 #1667 #1666 #1668 #1669（全 5 Phase 已合 dev） -**日期**: 2026-05-05 -**对接人**: mmg - -后端方案已全链路闭环，前端需要按本指南接入新接口 + 调整 body/响应字段。本指南是 5 个 Phase 的整合视图，不需要去翻散落的 changelog。 - ---- - -## 一、新增接口（前端直接调） - -### 1. `POST /mp/security/text-check` 文本同步机审 - -提交评价/投诉/反馈/姓名修改等含用户输入文本的业务前，**先调本接口**拿审核结果决定是否拦截。 - -**请求**: -```js -http.post('/mp/security/text-check', { - content: "用户提交的文本内容", // 必填,≤2500 字 - scene: 2 // 必填:1=资料/2=评论/3=论坛/4=社交日志 -}) -``` - -**响应**: -```json -{ - "code": 200, - "data": { - "pass": true, - "suggest": "pass", // pass / review / risky / pass-degraded - "label": 100, // Integer 类型，100=正常 - "traceId": "xxx", - "degraded": false, - "detail": null // 命中时是关键词摘要字符串 - } -} -``` - -**前端拦截规则**: -- `pass=true` 或 `suggest=pass` → 放行 -- `suggest=review` → toast「内容疑似违规,请修改后重试」+ 阻断 -- `suggest=risky` → toast「内容包含违规信息,请修改」+ 阻断 -- `suggest=pass-degraded` 或网络异常 → **降级放行**（不阻断业务，后端事后人工兜底） - -### 2. `POST /mp/security/media-check` 媒体异步机审 - -图片/音频上传到 OSS 后，**调本接口拿 traceId**，把 traceId 数组随业务 API 提交。 - -**请求**: -```js -http.post('/mp/security/media-check', { - mediaUrl: "https://oss.example.com/xxx.jpg", // 必填,已上传 OSS 的 https URL - mediaType: "image" // 必填:image / audio -}) -``` - -**响应**: -```json -{ - "code": 200, - "data": { - "traceId": "967e945cd8a3e458effc23eb0e7c84e1" // 失败时为 null - } -} -``` - -**前端使用**: -- 同步只返 `traceId`，**不阻断业务提交**（异步审核） -- traceId 收集到数组里，业务 API 提交时随 `mediaTraceIds` 字段传给后端 -- traceId=null（降级）时仍然继续业务，后端按未审核处置 - ---- - -## 二、业务 API body 新增 `mediaTraceIds` 字段（5 个接口） - -| 业务接口 | body 新增字段 | -|---|---| -| `POST /mp/review/create` 评价 | `mediaTraceIds: string[]` | -| `POST /mp/complaint/create` 投诉 | `mediaTraceIds: string[]` | -| `POST /mp/order/{orderId}/refund` 退款 | `mediaTraceIds: string[]` | -| `POST /mp/order/refund/{appId}/appeal` 申诉 | `mediaTraceIds: string[]` | -| `POST /mp/order/refund/{orderId}/direct-appeal` 直接申诉 | `mediaTraceIds: string[]` | -| `POST /mp/common/feedback` 客服反馈 | `mediaTraceIds: string[]` | - -**例**： -```js -// 评价提交流程 -const traceIds = [] -for (const url of uploadedImageUrls) { - const r = await http.post('/mp/security/media-check', { mediaUrl: url, mediaType: 'image' }) - if (r.data.traceId) traceIds.push(r.data.traceId) // null 时跳过即可 -} -await http.post('/mp/review/create', { - orderId: '...', - content: '评价文本', - images: uploadedImageUrls, - mediaTraceIds: traceIds // 新加字段 -}) -``` - -未传 `mediaTraceIds` 的接口（发票/退款理由/昵称/姓名）按无图处理，不影响。 - ---- - -## 三、查询响应新增字段 - -### `/mp/review/my` 我的评价列表 + 详情 - -VO 新增 2 字段（私有列表才返，公开列表后端已自动过滤未审核内容）： - -```jsonc -{ - "id": "...", - "content": "...", - "rating": 5, - "auditStatus": "MANUAL_REVIEW", // 新增 (Phase 2A): wx 内容安全机审状态 - "reportStatus": "NORMAL", // 新增 (Phase 2B): 举报状态 - "hiddenReason": null, // 新增 (Phase 2B): HIDDEN 时返回隐藏原因 - "createdAt": "..." -} -``` - -**前端展示状态条文案**： - -| auditStatus | 状态条 | -|---|---| -| `PENDING` | 「审核中,通过后展示」灰色 | -| `APPROVED` | (无提示，正常展示) | -| `MANUAL_REVIEW` | 「审核中,预计 24h 内」黄色 | -| `REJECTED` | 「内容未通过审核」红色 + 重新编辑按钮 | - -| reportStatus | 状态条 | -|---|---| -| `NORMAL` | (无提示) | -| `PENDING_REVIEW` | (无提示，仍展示) | -| `HIDDEN` | 「该评价已下架」+ `hiddenReason` | - -**公开列表**（产品评价/首页精选/旅行相册）后端已强制过滤 `audit_status='APPROVED' AND report_status!='HIDDEN'`，前端**无需特殊处理**。 - ---- - -## 四、新接口：评价举报 `POST /mp/review/report` - -```js -http.post('/mp/review/report', { - reviewId: '101010101010', // String 雪花 ID(必填,严禁 Number) - reason: 'SPAM', // 必填,字典 review_report_reason - detail: '广告链接,引导外部' // 可选(≤500 字) -}) -``` - -**reason 字典**（建议从 `dict.getList('review_report_reason')` 取，避免硬编码）: - -| reason | 文案 | -|---|---| -| `SPAM` | 广告/营销 | -| `INSULT` | 辱骂/人身攻击 | -| `PORN` | 色情低俗 | -| `POLITICS` | 政治敏感 | -| `FAKE` | 虚假评价 | -| `LEAK_PRIVACY` | 泄露他人隐私 | -| `OTHER` | 其他 | - -**响应**: 成功 200 / 失败业务码： - -| code | 文案 | 处理 | -|---|---|---| -| 551001 | 举报原因无效 | toast | -| 551002 | 今日举报次数已达上限 | toast，引导明日再来 | -| 551003 | 评价不存在 | toast | -| 551004 | 不能举报自己的评价 | toast | -| 551005 | 您已举报过该评价 | toast | -| 551006 | 无法识别用户身份,请重新登录 | 引导重新登录 | - -举报后业务流程： -- 同 review 累计举报 ≥3 次 → `report_status=PENDING_REVIEW`（用户侧仍可见，运营人工审核中） -- ≥10 次且 24h 内 → 自动 `HIDDEN`（用户侧立即下架） -- 命中举报触发再机审：risky → 强制 HIDDEN - ---- - -## 五、出行人姓名（前端不做硬拦截） - -按官方契约 §8，姓名是实名信息，**前端不应做内容机审**（怕误伤真实姓「操/苟」、少数民族罕字、港澳台/外籍拼音）。 - -**前端不需要改**： -- ❌ 不要在创建出行人前调 text-check -- ❌ 不要本地正则/黑名单拦截 - -**后端三层兜底已自动处理**： -- 第 1 层：异步机审（不阻塞业务，命中标 MANUAL_REVIEW 不删数据） -- 第 2 层：下单选出行人时**仅挡 REJECTED**（人工裁决），其他状态全放行 -- 第 3 层：本地正则（长度/字符集/重复字符防垃圾） - -**新增错误码**（出行人下单时）: -| code | 文案 | -|---|---| -| 100701 | 姓名长度异常(2-30 字符) | -| 100702 | 姓名含非法字符 | -| 100703 | 姓名含敏感词 | -| 100704 | 姓名格式不正确 | -| 100705 | 此出行人信息异常,请联系客服核实 | - -同款适用：紧急联系人 / 用户实名。 - ---- - -## 六、头像 / 昵称（前端流程同现状） - -- **昵称**：前端调 text-check 文本同步机审（按"一"节流程），命中拦截 -- **头像**：前端 `fileApi.upload` 上传 OSS → `securityApi.checkMedia` 拿 traceId → `userApi.updateUserInfo({avatar})` **不传 traceId**（后端会在 /mp/file/upload 内部异步审，traceId 关联到 fileId 后通过 webhook 自动反查 user 表） - -REJECTED 时后端自动重置默认头像，前端展示用户资料时拿到的就是已重置后的 URL。 - ---- - -## 七、调用顺序总结 - -### 评价/投诉/退款申诉 (含图) -``` -1. 用户填表(选图) -2. 图上传 OSS → 拿 url[] -3. 文本调 /mp/security/text-check → 拿 suggest 决定是否阻断 -4. 每张图调 /mp/security/media-check → 收集 traceId[] -5. 业务接口提交 (body 含 mediaTraceIds) -``` - -### 客服反馈 / 心愿单 / 备注 (仅文本) -``` -1. 用户填表 -2. 调 /mp/security/text-check → 决定阻断 -3. 业务接口提交 (body 不含 mediaTraceIds) -``` - -### 用户昵称 -``` -1. 用户填昵称 -2. 调 /mp/security/text-check → 决定阻断 -3. /mp/user/profile 提交 -``` - -### 用户头像 -``` -1. 上传 OSS -2. 调 /mp/security/media-check → 拿 traceId (失败也继续) -3. /mp/user/profile 提交 avatar (不传 traceId) -``` - -### 出行人 -``` -1. 用户填姓名 -2. /mp/user/traveler 直接提交 (前端不调 security) -3. 后端三层兜底自动处理 -``` - ---- - -## 八、降级容错 - -任何 `/mp/security/*` 接口 5xx 或网络异常： -- 前端按 **降级放行** 处理（不阻断业务） -- 用户体验优先于绝对合规 -- 后端会通过 `pass-degraded` 标记记录，事后人工兜底审核 - ---- - -## 九、前端工作量预估 - -按本指南改前端约： -- 通用工具：`utils/contentSecurity.js` + `utils/ugc.js` 包装 text-check / media-check（已有则更新） -- 6 个业务页面调用点：评价提交 / 投诉提交 / 退款申请 / 申诉提交 / 客服反馈 / 心愿提交 -- 评价列表：私有列表加状态条文案（auditStatus / reportStatus） -- 评价举报新页面：调 /mp/review/report -- 字典：拉 review_report_reason 字典做举报原因下拉 -- 头像/昵称：检查现有流程是否已按上述顺序 - ---- - -@mmg 有任何疑问随时找我。后端已部署到 dev 分支，等运维 nacos 配 wechat.miniapp.webhook.token 后即可联调。 diff --git a/changelogs/2026-05/05_notice_wx-security-prod-deploy-window-glitch.md b/changelogs/2026-05/05_notice_wx-security-prod-deploy-window-glitch.md deleted file mode 100644 index dba86c1..0000000 --- a/changelogs/2026-05/05_notice_wx-security-prod-deploy-window-glitch.md +++ /dev/null @@ -1,34 +0,0 @@ -# notice: wx 内容安全方案正式部署窗口期短暂错误（已自愈） - -**日期**: 2026-05-05 -**影响时段**: 17:23 - 17:54（约 31 分钟，部署滚动窗口） -**症状**: `/mp/review/featured?limit=5` 等评价相关接口偶发返 `BadSqlGrammarException` - -## 根因 - -正式服部署 wx 内容安全方案 Phase 1-2E 时： -- **17:23** 用户合并 main HEAD `e8ef4824` -- **17:35** RDS 部分 ALTER 已落（V005 给 order_review 加 4 列：report_count / report_status / hidden_at / hidden_reason） -- **17:43** 前端拿到 BadSqlGrammar — 老镜像 `e89f0fc1` 还活着，但其代码不知道新列的 entity 映射 -- **17:46-17:54** K8s 滚动完成，4 服务全到 `e8ef4824` → 自愈 - -属于"schema 增量先行 + 镜像滚动后行"的行业通病窗口（5-30 min 不等）。 - -## 现状（QA 18:06 确认） - -49 次双环境 API 测试全过： -- 0 BLOCKING / 0 5xx 非业务 / 0 BadSqlGrammar -- 11 个 wx 内容安全新路径全 OK -- 评价/投诉/退款/反馈/举报 5 个写接口 401 鉴权链路正确 -- 边界值（limit 0/100/-1/abc / 无效 type）全过 - -## 预防 - -后续大版本部署建议： -1. ALTER 增量 SQL 必保持向后兼容（新增列必须 NULL 或带 DEFAULT，禁止 NOT NULL 无默认）— 项目已是规则 -2. 删列/改类型场景必须分两次部署（先两边读写、再删列）— 本次未踩到 -3. 部署时间挑低峰期（凌晨）减少瞬时窗口暴露给真实用户 - -## 不需修复 - -代码层面无 BUG。本次是滚动部署的固有特征，不是回归性问题。 diff --git a/changelogs/2026-05/05_notice_wx-security-prod-e2e-verified.md b/changelogs/2026-05/05_notice_wx-security-prod-e2e-verified.md deleted file mode 100644 index 54f605a..0000000 --- a/changelogs/2026-05/05_notice_wx-security-prod-e2e-verified.md +++ /dev/null @@ -1,71 +0,0 @@ -# notice: wx 内容安全方案正式环境端到端验证通过 - -**日期**: 2026-05-05 18:30 -**状态**: 全链路 OK,可以让前端 mmg 联调 - -## 验证范围 - -正式服(K8s + 阿里云 RDS + 火山 RocketMQ)4 个验证场景: - -### 1. text-check 同步链路 (调真实微信 msgSecCheck v2) - -- 入口: `POST /internal/security/text-check` (集群内 ClusterIP + X-Internal-Token) -- 合法文本: `pass=true, suggest=pass, label=100, detail=strategy=content_model;errcode=0|strategy=keyword;errcode=0` -- 微信测试样本: pass(策略均 errcode=0,链路真实调到微信) -- 空内容: 400 校验拦截 -- 结论: 微信内容安全 API 调用通,access_token 缓存 OK,降级路径未触发(无 5xx) - -### 2. webhook 端到端 (handler → DB → MQ → 双服务 Listener) - -构造真实签名(SHA1, token=`hulai_wx_security_2026`,明文模式)POST 到 `http://hl-user-service:8081/mp/security/webhook`,触发完整后端链路: - -| suggest | 期望 status | 实际 DB | MQ user-service | MQ order-v2 | -|---|---|---|---|---| -| `pass` | APPROVED | ✅ | ✅ | ✅ | -| `risky` | REJECTED | ✅ | ✅ | ✅ | -| `review` | MANUAL_REVIEW | ✅ | ✅ | ✅ | - -每条事件都被双服务 (`user-service.WxContentAuditResultListener` + `order-v2.WxContentAuditResultListener`) 各 consume 一次,反查业务表(`user_feedback.media_trace_ids LIKE`、`user.avatar_trace_id`、`order_review.media_trace_ids` 等)逻辑触发正常。 - -### 3. 错误签名拒绝路径 - -``` -POST /mp/security/webhook?signature=WRONG×tamp=1234&nonce=abc -→ HTTP 200, body: {"code":230706,"message":"webhook 签名校验失败","success":false} -``` - -非 'success' 字符串体微信侧会重试 ≤3 次后放弃 — 符合契约。 - -### 4. webhook GET URL 验证 - -正式服微信公众平台后台已配置: -- URL: `https://api.1814.love/mp/security/webhook` -- Token: `hulai_wx_security_2026` -- EncodingAESKey: 已设(明文模式下不参与) -- 加密方式: 明文模式 -- 数据格式: JSON -- 状态: 已启用 - -## 关键日志(留档) - -``` -INFO WxContentSecurityService - wx webhook 更新 record: traceId=..., status=APPROVED, suggest=pass, label=100 -INFO WxContentSecurityService - wx 审核结果已广播 MQ: traceId=..., status=APPROVED -INFO WxContentAuditResultListener - [wx-audit-listener-user] 收到 wx 审核结果事件: traceId=..., status=APPROVED -INFO WxContentAuditResultListener - [wx-audit-listener] 收到 wx 审核结果事件: traceId=..., status=APPROVED, suggest=pass, label=100 -ERROR WxContentSecurityService - wx webhook 签名校验失败: encryptType=null, signature=WRONG -``` - -## 数据清理 - -测试期间 6 条 `hl-prod-e2e-*` 记录全部软删,active=0。 - -## 结论 - -**后端微信回调链路完整通过,前端 mmg 可放心联调。** - -唯一未验场景:真实微信 mediaCheckAsync 异步回调(需要前端真实小程序触发 OSS 图上传 → 后端调微信 → 微信 30s-5min 后回调)。这部分代码与本次伪造回调走的是**同一段 webhook handler**,handler 已验通,真实回调的差别仅在于"谁发的 POST"—— 一旦前端联调,必然走通。 - -## 不需修复 - -无任何 BUG,代码层面完全 OK。 diff --git a/changelogs/2026-05/05_notice_wx-security-real-callback-verified.md b/changelogs/2026-05/05_notice_wx-security-real-callback-verified.md deleted file mode 100644 index cdc7dcc..0000000 --- a/changelogs/2026-05/05_notice_wx-security-real-callback-verified.md +++ /dev/null @@ -1,78 +0,0 @@ -# notice: wx 内容安全方案 — 真实微信 mediaCheckAsync 异步回调端到端验证通过 - -**日期**: 2026-05-05 18:35 -**关联**: 衔接 `05_notice_wx-security-prod-e2e-verified.md`(伪造签名验 handler 内部链路) - -## 验证手法 - -不依赖前端联调,我自己在 Node1 直接调微信 mediaCheckAsync API,让微信真的发回调到我们的 webhook URL。 - -### 完整流程 - -``` -我(Node1) → 微信 cgi-bin/token API → 拿 access_token -我(Node1) → 微信 wxa/media_check_async API → 拿 trace_id="69f9c7ef-32f7c85c-5d87f592" -我(Node1) → 阿里云 RDS INSERT wx_media_check_record(PENDING) -微信 → 异步检测图片 (~30 秒) -微信 → POST https://api.1814.love/mp/security/webhook?signature=×tamp=&nonce= + JSON body -gateway → user-service:8081/mp/security/webhook -handler → 验签通过(明文模式 SHA1) -handler → 解析 JSON 拿 trace_id/suggest/label -handler → UPDATE wx_media_check_record SET status='APPROVED', suggest='pass', label=100, callback_at=NOW() -handler → 推 MQ topic=HL_WX_CONTENT_AUDIT_RESULT_TOPIC -user-service Listener → 收到 MQ → 反查业务表 -order-v2 Listener → 收到 MQ → 反查业务表 -``` - -### 时间线证据 - -``` -18:34:xx Node1 调微信 mediaCheckAsync → 微信返回 errcode=0, trace_id=69f9c7ef-32f7c85c-5d87f592 -18:35:30 Node1 INSERT wx_media_check_record(trace_id, PENDING) 到正式 RDS -18:35:32 微信公网 POST 到 api.1814.love/mp/security/webhook (~30s 延迟) -18:35:32.390 user-service "wx webhook 更新 record: status=APPROVED, suggest=pass, label=100" -18:35:32.392 user-service "wx 审核结果已广播 MQ" -18:35:32.397 user-service Listener 收到 - order-v2 Listener 收到 (跨服务) -``` - -callback_at = `2026-05-05 18:35:32` 与 user-service 日志时间戳完全一致 — 这是微信真实公网回调,不是伪造。 - -### 输入图片 - -默认头像 OSS URL: `https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/05/05/7558036ffa6d59a26013cf36248ff0a7.png` (用户提供,合法图片) - -微信判定:`suggest=pass, label=100`(正常图片)。 - -## 与上一份验证的关系 - -| 维度 | 上次伪造签名验证 | 本次真实微信回调 | -|---|---|---| -| 调微信 API | ❌ 仅本地构造 | ✅ 真实调 mediaCheckAsync | -| webhook 验签 | ✅ 本地用同 token 自签 | ✅ 微信用 token 真签 | -| webhook handler | ✅ 已验 | ✅ 已验 | -| DB UPDATE | ✅ | ✅ | -| MQ 广播 | ✅ | ✅ | -| 跨服务 Listener | ✅ | ✅ | -| 公网 → 网关 → user-service 路径 | ❌ 走 ClusterIP | ✅ 走 api.1814.love + hl-gateway | -| 微信 IP 白名单 | N/A | ✅(微信真实出口 IP 能进网关) | -| webhook URL 配置正确性 | N/A | ✅(微信真的找到了我们) | -| token 配对 | N/A | ✅(微信用 nacos 配的 hulai_wx_security_2026 算签名,我们能验过) | -| 30s 延迟在线 SLA | N/A | ✅ 测得实际 ~2s,远低于 5min 上限 | - -**两份一起把 wx 内容安全的所有路径都覆盖了。** - -## 数据清理 - -trace_id=`69f9c7ef-32f7c85c-5d87f592` 软删,active=0。 - -## 结论 - -- 后端代码 ✅ -- 网关白名单 ✅ -- nacos 配置(token/appid/secret) ✅ -- 微信公众平台 webhook URL 配置 ✅ -- 微信公网 → 公网回调路径 ✅ -- DB UPDATE + MQ 广播 + 跨服务 Listener ✅ - -**前端 mmg 接入后零阻力,直接联调即可。** diff --git a/changelogs/2026-05/05_ops_install_chromium_for_itinerary_pdf.md b/changelogs/2026-05/05_ops_install_chromium_for_itinerary_pdf.md deleted file mode 100644 index f862a3b..0000000 --- a/changelogs/2026-05/05_ops_install_chromium_for_itinerary_pdf.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -date: 2026-05-05 -type: ops -module: hl-order-service-v2 -priority: high -related_pr: "#1655" -notify: ["@yst"] -status: pending ---- - -# 在 hl-order-service-v2 K8s pod 安装 Chromium + 中文字体 - -## 背景 - -PR #1655 已合并：行程附件 PDF 渲染管线从 PDFBox 切到 **Thymeleaf HTML 模板 + Microsoft Playwright Headless Chromium**，1:1 还原 Kimi 网页样式。 - -代码已部署测试服 + 正式服。**但 Chromium 二进制 + 中文字体未在 K8s base image 中安装**，目前服务自动 fallback 到 PDFBox 老路径（PDF 样式跟之前一样不变，不阻断合同生成）。 - -要看到 Kimi 新样式，必须装 Chromium。 - -## K8s 改动清单 - -### 1. 镜像加 Chromium 二进制 + 系统依赖 - -`Dockerfile` 加： - -```dockerfile -RUN apt-get update && apt-get install -y \ - libnss3 libgbm1 libasound2 libxss1 libxshmfence1 \ - libdrm2 libgtk-3-0 libxcomposite1 libxdamage1 libxfixes3 \ - libxrandr2 libpango-1.0-0 libcairo2 \ - && rm -rf /var/lib/apt/lists/* -``` - -### 2. 镜像装中文字体 - -```dockerfile -RUN apt-get update && apt-get install -y \ - fonts-noto-cjk fonts-arphic-uming fonts-arphic-ukai \ - && rm -rf /var/lib/apt/lists/* -``` - -### 3. 启动时下载 Chromium 二进制 - -Playwright-java 第一次调用时自动下载 chromium 到 `~/.cache/ms-playwright/`（约 200MB），但 K8s pod fs 通常 ephemeral，每次 pod 重启会重下，浪费时间。 - -**两种方案**： - -#### 方案 A: PV 持久化 cache 目录（推荐） - -K8s deployment 加 PersistentVolumeClaim 挂 `~/.cache/ms-playwright`： - -```yaml -volumes: - - name: playwright-cache - persistentVolumeClaim: - claimName: hl-order-v2-playwright-cache -volumeMounts: - - name: playwright-cache - mountPath: /root/.cache/ms-playwright -``` - -PVC 大小 500Mi 即可。首次启动 download 后所有 pod 共享。 - -#### 方案 B: 镜像 build 时 install（更稳妥） - -Dockerfile 加： - -```dockerfile -WORKDIR /app -COPY app.jar /app/ -RUN java -jar /app/app.jar --spring.main.web-application-type=none \ - --com.microsoft.playwright.cli=install --com.microsoft.playwright.cli.args=chromium -# 或者用 maven exec 直接装 -RUN mvn -f /tmp/playwright-pom.xml exec:java \ - -Dexec.mainClass=com.microsoft.playwright.CLI \ - -Dexec.args="install --with-deps chromium" -``` - -镜像层增大约 200MB，但启动即用。 - -## 验证 - -部署完后： - -1. K8s pod exec: `ls -la ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome` 看二进制存在 -2. 创建一份测试合同，下载行程附件 PDF -3. 标题"额吉的故乡 · 6天5晚行程线路详情" 应显示**深蓝衬线字体居中** -4. 每个 DAY 下封面图应**圆角卡片化** -5. 三餐三栏、timeline、游客名单表样式齐全 - -## Fallback 行为（保险） - -如果 Chromium 启动失败（缺二进制/缺字体/launch 异常），ItineraryAttachmentService 自动 catch + log warn + 走 PDFBox 老路径生成 PDF。**不阻断合同生成流程**。 - -## OSS Render Version - -OSS_RENDER_VERSION 6→7，旧订单重新申报合同会走新版本路径。已生成的旧 v6 PDF 不影响（按月分桶 OSS Key）。 - -## 关联 - -- PR #1655 (Thymeleaf + Chromium 重构) -- Issue #1651 (用户授权 完全由后端做, 不动 hl-ui) -- 模板文件: `hl-order-service-v2/src/main/resources/templates/itinerary.html` - -@yst 帮忙在测试服 K8s deployment 加 Chromium 安装步骤，正式服同步处理。装好后 PD 回复一下我做 round-trip 验证。 diff --git a/changelogs/2026-05/06_diag_mp_merchant_qualifications_not_found.md b/changelogs/2026-05/06_diag_mp_merchant_qualifications_not_found.md deleted file mode 100644 index 8e5628c..0000000 --- a/changelogs/2026-05/06_diag_mp_merchant_qualifications_not_found.md +++ /dev/null @@ -1,68 +0,0 @@ -# diag(mp): /mp/common/merchant-qualifications 接口不存在 — 需 mmg 确认意图 - -**日期**: 2026-05-06 19:30 -**通知对象**: @mmg (前端) -**关联 BUG 反馈**: 用户报告 "/mp/common/merchant-qualifications 接口不存在" - ---- - -## 一、调研结论 - -后端确认:`/mp/common/merchant-qualifications` **从未实现过**,也无任何接近名称的同义接口。 - -| 排查点 | 结果 | -|---|---| -| `MpCommonController` 现有端点 | `/config / /faq / /feedback / /agreement/{type} / /agreement/list / /contact` 仅 6 个 | -| `MpAgencyController` 端点 | 仅 `/mp/agency/primary` | -| Admin 资质接口 | `/admin/travel-agency/{agencyId}/qualification` (admin 端 CRUD) | -| 设计文档 / 最近 7 天 PR | `docs/requirements/` 无"商户资质 / merchant qualifications"需求,git log 无相关 | -| hl-ui repo 全量 grep | **零引用**(不在管理后台代码里) | - -## 二、可能的来源 - -调用源不在 hl-ui (Vue admin) 里,推测可能: -1. **小程序原生代码**(wx/miniapp 代码不在 hl-ui repo,后端无法溯源调用方) -2. **前端在写新需求,本地未 push** -3. **前端误调** (路径拼写或语义错) - -## 三、语义澄清 - -- 项目里 **`merchant` ≠ `agency`** - - `merchant` = 微信支付商户号(merchantId / mchId,paymentInfo 表) - - `agency` = 旅行社公司(travel_agency 表 + agency_qualification 表存营业执照/法人证件等资质) -- 资质数据存在 `agency_qualification` 表,挂在 agency 维度,不是 merchant -- 想展示"商家资质"应该是 `agency qualifications`,不是 `merchant qualifications` - -## 四、需要 mmg 确认 - -请在群里回复: - -1. **这个调用是从哪来?** (hl-ui? 小程序? 路径或 API 文件位置?) -2. **想展示什么内容?** - - (a) 旅行社营业执照、法人证、许可证等(agency qualifications)? - - (b) 微信支付商户主体信息(merchant 主体)? - - (c) 其他(品牌、合作伙伴…)? -3. **页面位置** — 在哪个页面/弹窗展示? - -## 五、后端可提供的备选方案 - -确认意图后,后端可按以下任一路径实施: - -### 方案 A: 用现有 `/mp/agency/primary`(零成本) -返回主体公司公开字段(licenseNumber / businessLicenseNumber / 公司名 / logo 等),如果只要一两个字段足够展示就用这个。 - -### 方案 B: 新增 `GET /mp/agency/qualifications`(推荐) -- 路径 `/mp/agency/qualifications` (语义对齐,不是 `/mp/common/`,因为这是 agency 维度的资质) -- 返回 agency_qualification 表里所有 type=主体类资质(营业执照、法人证件、其他经营许可证) -- 字段:type / typeLabel / fileUrl / issuedDate / expiryDate / status -- 复用 admin 端 `TravelAgencyQualificationServiceImpl` 的查询逻辑,加 mp 过滤(只暴露已审核 + 未过期) -- 估时:0.5 天(controller + VO + 单测) - -### 方案 C: 新增 `GET /mp/common/merchant-qualifications`(不推荐) -仅当确实是支付商户主体维度(payment_info 表)的资质才走这个,但当前业务场景不存在这种需求 — 项目里 merchant 是支付层概念,用户面不感知。 - -## 六、建议结论 - -**优先方案 B**(语义清晰、可扩展)。如果确认想要,**请回复任意确认信息或提供需求描述**,我会建后端工单 + 派 /@dev 实施 + 测试 + 部署。 - -如果调用是误造/路径笔误,前端改成 `/mp/agency/primary` 即可,不需要后端改动。 diff --git a/changelogs/2026-05/06_feat_agency_management_module.md b/changelogs/2026-05/06_feat_agency_management_module.md deleted file mode 100644 index faae86d..0000000 --- a/changelogs/2026-05/06_feat_agency_management_module.md +++ /dev/null @@ -1,130 +0,0 @@ -# feat(agency): 旅行社公司管理新模块 + 产品绑定公司 (定稿) - -**日期**: 2026-05-06 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1710 (主) + #1711 (runtime hotfix) + #1712 (gateway 白名单 hotfix) + #1715 (admin path 纠回设计冻结的 travel-agency) -**关联工单**: wx/HL #1707 closed -**测试服已部署 + round-trip 验证通过**: 2026-05-06 15:13 (旧 path /admin/agency)、2026-05-06 15:39 (新 path /admin/travel-agency, PR #1715 部署完成) - ---- - -## 一、部署状态 (测试服 https://api.test.1814.love:9443) - -| 接口 | round-trip 验证 | -|---|---| -| GET /admin/travel-agency/page | ✅ 200 / 3 家明文 | -| GET /admin/travel-agency/{id} | ✅ 200 / 完整公司信息 | -| GET /admin/travel-agency/enabled | ✅ 200 / 下拉选项 | -| GET /admin/travel-agency/{id}/qualification | ✅ 200 / 资质列表 | -| GET /admin/travel-agency/{id}/payment | ✅ 200 / 支付配置列表 | -| GET /mp/agency/primary | ✅ 200 / 主体公司公开信息(无需登录) | - ---- - -## 二、后端接口 (网关 admin/travel-agency) - -> ⚠️ **2026-05-06 15:35 更正 (PR #1715)**: 前一版本 changelog 误将 path 标为 `/admin/agency` (副本 A 实施漂移设计文档)。现已纠回设计冻结的 `/admin/travel-agency`,代码 + 网关路由 + 本文档全部对齐。**前端请用 `/admin/travel-agency` 调用**。 - -### 1. 主体 CRUD (admin) - -| Method | Path | 说明 | -|--------|------|------| -| GET | `/admin/travel-agency/page?pageNum=&pageSize=&code=&agencyName=&status=` | 公司列表(分页) | -| GET | `/admin/travel-agency/{id}` | 详情 | -| GET | `/admin/travel-agency/enabled` | 启用列表(下拉用, `List<{id,code,agencyName}>`) | -| POST | `/admin/travel-agency` | 新建 (SUPER_ADMIN) | -| PUT | `/admin/travel-agency/{id}` | 编辑 | -| POST | `/admin/travel-agency/{id}/disable` | 停用 (主体不可停, 引用产品也不可) | -| POST | `/admin/travel-agency/{id}/set-primary` | 设为主体 (全局唯一 STORED 生成列+UNIQUE 兜底) | -| DELETE | `/admin/travel-agency/{id}` | 软删 (SUPER_ADMIN, 主体/有引用拒绝) | - -### 2. 资质子表 (admin/agency/{agencyId}/qualification) - -| Method | Path | 说明 | -|--------|------|------| -| GET | `/admin/travel-agency/{agencyId}/qualification` | 列表 | -| POST | `/admin/travel-agency/{agencyId}/qualification` (multipart) | 上传 (name + file + sortOrder + remark + 可选 issueDate/expireDate) | -| PUT | `/admin/travel-agency/{agencyId}/qualification/{id}` | 编辑 | -| DELETE | `/admin/travel-agency/{agencyId}/qualification/{id}` | 删除 | - -- 文件类型白名单: PDF / JPG / PNG / JPEG (后续可加字典 `qualification_file_type`) - -### 3. 支付子表 (admin/agency/{agencyId}/payment) - -| Method | Path | 说明 | -|--------|------|------| -| GET | `/admin/travel-agency/{agencyId}/payment` | 列表 | -| POST | `/admin/travel-agency/{agencyId}/payment` | 新增 (mchId + apiV3Key + mchSerialNo + publicKeyId + isDefault) | -| PUT | `/admin/travel-agency/{agencyId}/payment/{paymentId}` | 编辑 (加密字段密文返回, 编辑用 placeholder) | -| DELETE | `/admin/travel-agency/{agencyId}/payment/{paymentId}` | 删除 | -| POST | `/admin/travel-agency/{agencyId}/payment/{paymentId}/set-default` | 设为默认 mchId | - -### 4. mp 端 (无需登录) - -| Method | Path | 说明 | -|--------|------|------| -| GET | `/mp/agency/primary` | 主体公司公开信息 (name + 许可证 + 客服电话 + 地址) | - ---- - -## 三、关键业务规则 - -1. **产品绑定公司 = 绑定商户号** — 用户原话 (2026-05-06): "下单只能是这个商户号了"。创建产品必填 `agencyId`, 下单 `mchId` 永远走 `agency.default.payment.mchId`, `productMchId` 不再被读取。 -2. **历史产品默认填主体公司 hulai** — V20260506_001 + V20260506_006 全行回填 (含软删 12371 条)。 -3. **主体公司全局唯一** — STORED 生成列 `primary_lock` + UNIQUE 兜底。 -4. **加密字段 (apiV3Key/mchSerialNo)** — admin 后台需手动补录, `AgencyDataInitializer` 启动只 UPSERT 主表 + 默认 mchId/cert 路径。 - ---- - -## 四、产品端字段 (前端必改) - -- `ProductSaveReqVO` 必须传 `agencyId: Long` -- `ProductDetailVO` / Resp 增加 `agencyId / mchId` 字段 -- 产品编辑页"所属公司"下拉调 `/admin/travel-agency/enabled` -- V20260507_001 部署后 `product.agency_id NOT NULL`, 漏传校验失败 - ---- - -## 五、订单端字段 - -- `OrderInfo` 加 `agencyId Long` (V20260506_006 ALTER) -- 订单列表/详情 `mchName` 拼接走 `TravelAgencyService.getById`, 不再读 `OrderHelperService.MCH_NAMES` 静态映射 - ---- - -## 六、UI 建议 (前端自由发挥) - -**admin 后台**: 顶级菜单 "系统管理 > 旅行社公司管理" -- 左列表 + 右编辑面板, Tab 分 基础信息 / 资质附件 / 支付配置 三段 -- 主体公司用徽章高亮 (返字段 `isPrimary=1`) -- `status=DISABLED` 全局灰显 - ---- - -## 七、curl 验证示例 - -```bash -# admin 拿 token -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -# 公司列表 -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \ - -H "Authorization: Bearer $TOK" - -# 主体公司公开信息 (mp 端用, 不需 token) -curl -sk "https://api.test.1814.love:9443/mp/agency/primary" -``` - ---- - -## 八、关联文档 - -- PR #1710 / #1711 / #1712 全 merge dev -- 工单 wx/HL #1707 closed (有 closing comment + status/已完成 label) - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_feat_agency_nacos_full_sync.md b/changelogs/2026-05/06_feat_agency_nacos_full_sync.md deleted file mode 100644 index 00b875e..0000000 --- a/changelogs/2026-05/06_feat_agency_nacos_full_sync.md +++ /dev/null @@ -1,91 +0,0 @@ -# feat(agency): 旅行社三家公司完整字段从 nacos 同步到 DB - -**日期**: 2026-05-06 16:30 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1718 (已 merge dev + 测试服部署完成 + round-trip 验证通过) -**前序**: PR #1717 (字典 + qualificationType 字段) - ---- - -## 一、用户反馈解决 - -PR #1717 加完字典后 UI 仍显示几处 `-` / `[]`: -- 「团队报送 AppId / SignKey」: `-` -- 「支持平台」: `[]` -- 支付配置: `未命名 mchId 1106110439 AppId: -` (api_v3_key/mch_serial_no/public_key_id 全空) - -根因: `AgencyDataInitializer` 启动同步时只覆盖部分字段, payment 子表加密字段从未写入。 - ---- - -## 二、本 PR 修复 - -### 1. 主表 `travel_agency` 字段全部从 nacos 同步 - -`AgencyDataInitializer.upsertOne` SYNC path 加 set 字段: -- `teamReportAppId` ← nacos `agencies[].team-report-app-id` -- `teamReportSignKey` ← nacos `agencies[].team-report-sign-key` -- `supportedPlatforms` ← nacos `agencies[].supported-platforms` (List → JSON, 无配置默认 `["12301"]`) - -### 2. 子表 `travel_agency_payment` 加密字段透明加密落 DB - -`initPaymentForAgency` 增强: -- 注入 `WxPayProperties`, 从 `wechat.pay.merchants.{key}.*` 拿 MerchantConfig -- INSERT 时同步 `apiV3Key` / `mchSerialNo` / `publicKeyId` (透明加密 by `@TableField(typeHandler=PaymentEncryptTypeHandler)`) -- SYNC existing payment 时, 加密字段空就回填 (admin 没填/旧数据回补) - -### 3. Feign DTO 同步 - -`AgencyInternalDTO` 加 `teamReportAppId/teamReportSignKey` 字段, `ContractPlatformProperties.AgencyInfo.fromInternalDTO` 同步, 保证 DB 路径下游 (12301 团队报送) 拿到完整字段。 - ---- - -## 三、测试服 round-trip 验证 (2026-05-06 16:30) - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -# 公司列表 - 三家完整字段 -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \ - -H "Authorization: Bearer $TOK" -``` - -| 字段 | hulai | qianshou | hulai-wenlu | -|---|---|---|---| -| teamReportAppId | 2078b6f0... | 412ff570... | 4f03ff70... | -| teamReportSignKey | 40ff382f... | 4e843fdd... | 727bb9c1... | -| supportedPlatforms | `["12301","TENCENT_ESIGN"]` | `["12301"]` | `["12301"]` | - -```bash -# 支付配置 - 加密字段透明解密返明文 -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/2051922156798779394/payment" \ - -H "Authorization: Bearer $TOK" -``` - -| 字段 | hulai | qianshou | hulai-wenlu | -|---|---|---|---| -| mchId | 1106110439 | 1246532201 | 1684769133 | -| apiV3Key (RespVO 解密返明文) | 2XxC4RHqyipPMwpVoAhXsvj1hvrwgbAJ | 同 | 同 | -| mchSerialNo | 60508F7718D2A9BB21DA9E8BB6259919FEA9FB0F | 7731A9D5B457BB999CA7CDB12676F1809DE2945A | 6708668E3326069DA24F81DD5568593F3F3CFA99 | -| publicKeyId | PUB_KEY_ID_0111061104392026020200181614001205 | PUB_KEY_ID_0112465322012026020200212016001401 | PUB_KEY_ID_0116847691332026020200212017000202 | - ---- - -## 四、前端无需改动 - -后端字段返回时已经是明文 (apiV3Key/mchSerialNo) + 完整内容, 前端无需改任何 API 调用代码,**刷新页面即可看到字段全部填充**。 - ---- - -## 五、关联 PR + changelog - -- wx/HL PR #1717: 资质附件 qualificationType + 字典 agency_qualification_type / agency_contract_platform -- wx/HL PR #1718: 本 PR -- 关联 changelog: `06_feat_agency_qualification_type_and_contract_platform.md` - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_feat_agency_payment_name_appid.md b/changelogs/2026-05/06_feat_agency_payment_name_appid.md deleted file mode 100644 index f7524be..0000000 --- a/changelogs/2026-05/06_feat_agency_payment_name_appid.md +++ /dev/null @@ -1,113 +0,0 @@ -# feat(agency): 支付配置加 name + appId 字段, 编辑表单不再空 - -**日期**: 2026-05-06 16:55 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1719 (已 merge dev + 测试服部署完成 + round-trip 通过) -**前序**: PR #1717 (字典) + PR #1718 (nacos full sync) - ---- - -## 一、用户反馈解决 - -PR #1718 部署后, 用户截图反馈「编辑支付配置」对话框仍有 2 个字段为空: -- 「配置名称」: 空 (placeholder "如: 微信支付-主商户号") -- 「AppId」: 空 (placeholder "请输入 AppId") - -根因: `TravelAgencyPaymentDO` entity / SaveReqVO / RespVO 完全没有 `name` + `appId` 字段。 - ---- - -## 二、本 PR 修复 - -| 类型 | 改动 | -|---|---| -| DDL V20260506_008 | `travel_agency_payment` ADD `name VARCHAR(64)` + `app_id VARCHAR(64)` | -| Entity TravelAgencyPaymentDO | 加 `name` + `appId` 字段 | -| AgencyPaymentSaveReqVO | 加 `name` (@NotBlank @Size 64) + `appId` (@NotBlank @Size 64) | -| AgencyPaymentRespVO | 加 `name` + `appId` | -| Service `toRespVO` | 同步 set name/appId | -| `AgencyDataInitializer.initPaymentForAgency` | INSERT 默认 `name="微信支付-{code}"` + `appId=wechat.pay.app-id` (三家共用 `wx4711a76772deff36`); SYNC existing 字段空时回填 | - ---- - -## 三、API 改动 - -### `POST /admin/travel-agency/{agencyId}/payment` + `PUT .../payment/{paymentId}` - -`AgencyPaymentSaveReqVO` 新增 2 个 **必填字段**: - -```json -{ - "name": "微信支付-主商户号", // ← 新增, @NotBlank, max 64 - "mchId": "1106110439", - "appId": "wx4711a76772deff36", // ← 新增, @NotBlank, max 64 - "apiV3Key": "...", - "mchSerialNo": "...", - "publicKeyId": "PUB_KEY_ID_...", - "isDefault": 1, - "status": "ENABLED", - "remark": "" -} -``` - -### `GET /admin/travel-agency/{agencyId}/payment` 响应 - -```json -{ - "paymentId": 5001, - "agencyId": 2051922156798779394, - "name": "微信支付-hulai", // ← 新增 - "mchId": "1106110439", - "appId": "wx4711a76772deff36", // ← 新增 - "apiV3Key": "2XxC4RHqyipPMwpVoAhXsvj1hvrwgbAJ", - "mchSerialNo": "60508F77...", - "publicKeyId": "PUB_KEY_ID_0111061104392026020200181614001205", - "isDefault": 1, - "status": "ENABLED", - "statusLabel": "启用", - ... -} -``` - ---- - -## 四、测试服 round-trip 验证 (2026-05-06 16:55) - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/2051922156798779394/payment" \ - -H "Authorization: Bearer $TOK" -``` - -| 公司 | name | appId | mchId | -|---|---|---|---| -| hulai | 微信支付-hulai | wx4711a76772deff36 | 1106110439 | -| qianshou | 微信支付-qianshou | wx4711a76772deff36 | 1246532201 | -| hulai-wenlu | 微信支付-hulai-wenlu | wx4711a76772deff36 | 1684769133 | - ---- - -## 五、前端 - -- 新建表单: `name` + `appId` 必填, 已存在 `mchId` / `apiV3Key` / `mchSerialNo` / `publicKeyId` 字段保持 -- 编辑表单: 后端返回字段已填默认值 (`微信支付-{code}` / 三家共用 `wx4711a76772deff36`), admin 可改 name 为更友好命名 -- 刷新页面即可看到字段全部填充 - ---- - -## 六、agency 模块 4 个 PR 全闭环 - -| PR | 内容 | -|---|---| -| #1715 | admin path 纠回 `/admin/travel-agency` (设计冻结) | -| #1717 | 资质附件 qualificationType + 字典 (agency_qualification_type / agency_contract_platform) | -| #1718 | nacos 完整字段同步 (teamReportAppId/SignKey/supportedPlatforms + payment 加密字段) | -| **#1719** | **payment name + appId 字段(本 PR)** | - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_feat_agency_qualification_type_and_contract_platform.md b/changelogs/2026-05/06_feat_agency_qualification_type_and_contract_platform.md deleted file mode 100644 index d0c3ddc..0000000 --- a/changelogs/2026-05/06_feat_agency_qualification_type_and_contract_platform.md +++ /dev/null @@ -1,151 +0,0 @@ -# feat(agency): 资质附件分类字段 + 合同平台字典 - -**日期**: 2026-05-06 16:18 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1717 (已 merge dev + 测试服部署 + round-trip 验证通过) - ---- - -## 一、用户需求 - -1. **资质附件上传需要分类字典** (营业执照 / 旅行社业务经营许可证 / 增值电信业务经营许可证) -2. **「支持平台」label 改为「支持合同平台」** + **字段值改为字典** (12301 / 腾讯电子签) - ---- - -## 二、字典数据 (测试服已生效) - -### 1. agency_qualification_type (资质分类) — 资质上传必传 - -| dictValue | dictLabel | sortOrder | -|-----------|-----------|-----------| -| `BUSINESS_LICENSE` | 营业执照 | 10 | -| `TRAVEL_AGENCY_LICENSE` | 旅行社业务经营许可证 | 20 | -| `VALUE_ADDED_TELECOM_LICENSE` | 增值电信业务经营许可证 | 30 | - -### 2. agency_contract_platform (支持的合同平台) — 多选 - -| dictValue | dictLabel | sortOrder | -|-----------|-----------|-----------| -| `12301` | 12301 团队报送 | 10 | -| `TENCENT_ESIGN` | 腾讯电子签 | 20 | - -字典查询接口: - -```bash -curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_qualification_type" \ - -H "Authorization: Bearer $TOK" -# data: [{dictValue, dictLabel, sortOrder}, ...] - -curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_contract_platform" \ - -H "Authorization: Bearer $TOK" -``` - ---- - -## 三、API 改动 - -### 1. 资质上传请求 / 响应 - -**`POST /admin/travel-agency/{agencyId}/qualification`** + **`PUT /admin/travel-agency/{agencyId}/qualification/{id}`** - -`AgencyQualificationSaveReqVO` **新增必填字段**: - -```json -{ - "name": "营业执照", - "qualificationType": "BUSINESS_LICENSE", // 必填, 字典 agency_qualification_type - "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/agency/...", - "fileType": "PDF", - "issueDate": "2024-01-01", - "expireDate": "2029-12-31", - "sortOrder": 100, - "remark": "" -} -``` - -**`GET /admin/travel-agency/{agencyId}/qualification`** 响应新增字段: - -```json -{ - "qualificationId": 2051940000000000, - "agencyId": 2051922156798779394, - "name": "营业执照", - "qualificationType": "BUSINESS_LICENSE", - "qualificationTypeLabel": "营业执照", // ← 新增, 中文 (供列表展示) - "fileUrl": "...", - "fileType": "PDF", - "fileTypeLabel": "PDF", - "issueDate": "2024-01-01", - "expireDate": "2029-12-31", - "sortOrder": 100, - "remark": "" -} -``` - -### 2. 公司主表「支持的合同平台」字段 - -**字段名**: `supportedPlatforms` (后端字段名不变, 前端 label 必改) - -| 现状 | 改为 | -|---|---| -| 前端 label = 「支持平台」 | 「**支持合同平台**」 | -| 字段值是裸字符串 | 拉字典 `agency_contract_platform` 做多选下拉 | - -后端字段已是 JSON 数组字符串 (例 `["12301","TENCENT_ESIGN"]`), 前端 form 多选组件直接绑定即可. - ---- - -## 四、前端改动建议 - -```bash -# hl-ui 前端项目根: -# 1. 资质上传 form 加分类下拉 (拉 /admin/dict/data/agency_qualification_type) -# 2. 资质列表展示用 qualificationTypeLabel (后端已返回中文) -# 3. 公司编辑页: -# - 「支持平台」label 改为「支持合同平台」 -# - 多选下拉拉 /admin/dict/data/agency_contract_platform -``` - ---- - -## 五、测试服 round-trip 验证 (2026-05-06 16:18) - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -# 资质分类字典 -curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_qualification_type" \ - -H "Authorization: Bearer $TOK" -# {"code":200,"data":[ -# {"dictValue":"BUSINESS_LICENSE","dictLabel":"营业执照","sortOrder":10}, -# {"dictValue":"TRAVEL_AGENCY_LICENSE","dictLabel":"旅行社业务经营许可证","sortOrder":20}, -# {"dictValue":"VALUE_ADDED_TELECOM_LICENSE","dictLabel":"增值电信业务经营许可证","sortOrder":30} -# ]} - -# 合同平台字典 -curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_contract_platform" \ - -H "Authorization: Bearer $TOK" -# {"code":200,"data":[ -# {"dictValue":"12301","dictLabel":"12301 团队报送","sortOrder":10}, -# {"dictValue":"TENCENT_ESIGN","dictLabel":"腾讯电子签","sortOrder":20} -# ]} -``` - ---- - -## 六、后续 PR (本 changelog 不含, 等下一个独立 changelog) - -下一个 PR 会同步 nacos 完整数据到 DB: -- `team-report-app-id` / `team-report-sign-key` (UI 「团队报送 AppId/SignKey」当前显示 `-`) -- `supportedPlatforms` 默认值 (UI 当前显示 `[]`) -- `payment.api-v3-key` / `mch-serial-no` / `public-key-id` (UI 「未命名 mchId 1106110439 AppId: -」 当前缺加密字段) - -实施后 UI 字段全部填满, 不再显示 `-`. - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_feat_agency_supported_platforms_label.md b/changelogs/2026-05/06_feat_agency_supported_platforms_label.md deleted file mode 100644 index fa0b55d..0000000 --- a/changelogs/2026-05/06_feat_agency_supported_platforms_label.md +++ /dev/null @@ -1,82 +0,0 @@ -# feat(agency): supportedPlatforms 加 List<code> + List<中文 label> 字段 - -**日期**: 2026-05-06 17:02 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1720 (已 merge dev + 测试服部署 + round-trip 通过) -**前序**: PR #1717 / #1718 / #1719 - ---- - -## 一、用户反馈 - -UI 截图反馈「支持平台」tag 显示 dictValue 带引号 `"12301"` `"TENCENT_ESIGN"`,前端没翻译成中文 dictLabel。 - ---- - -## 二、修复 (P0 铁律: *Label 字段必返中文非 null) - -`AgencyRespVO` **新增 2 个字段**(旧字段 `supportedPlatforms: String` 保留向后兼容): - -```json -{ - "supportedPlatforms": "[\"12301\",\"TENCENT_ESIGN\"]", - "supportedPlatformsList": ["12301", "TENCENT_ESIGN"], // ← 新增, 前端 tag value 绑定 - "supportedPlatformsLabels": ["12301 团队报送", "腾讯电子签"] // ← 新增, 前端 tag 显示用 -} -``` - -后端 `TravelAgencyServiceImpl.toRespVO` 解析 JSON + 翻译 (与现有 statusLabel/fileTypeLabel/qualificationTypeLabel hardcoded switch 风格对齐)。 - ---- - -## 三、前端建议 - -**form 多选 tag 改用新字段** (`supportedPlatformsList` 绑 v-model, `supportedPlatformsLabels` 渲染 tag 文本): - -```vue -<!-- 旧: 直接用 supportedPlatforms JSON 字符串显示 --> -<NTag v-for="p in JSON.parse(rec.supportedPlatforms)">{{ p }}</NTag> - -<!-- 新: 用 list + labels (后端已 parse 好) --> -<NTag v-for="(label, idx) in rec.supportedPlatformsLabels"> - {{ label }} <!-- "12301 团队报送" / "腾讯电子签" --> -</NTag> -``` - -POST/PUT 时仍传 `supportedPlatforms` JSON 字符串 (SaveReqVO 不变)。 - ---- - -## 四、测试服 round-trip 验证 (2026-05-06 17:02) - -| 公司 | supportedPlatformsList | supportedPlatformsLabels | -|---|---|---| -| hulai | `["12301","TENCENT_ESIGN"]` | `["12301 团队报送","腾讯电子签"]` | -| qianshou | `["12301"]` | `["12301 团队报送"]` | -| hulai-wenlu | `["12301"]` | `["12301 团队报送"]` | - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \ - -H "Authorization: Bearer $TOK" -``` - ---- - -## 五、agency 模块 PR 清单 - -| PR | 内容 | -|---|---| -| #1715 | admin path 纠回 `/admin/travel-agency` | -| #1717 | 资质附件 qualificationType + 字典 (agency_qualification_type / agency_contract_platform) | -| #1718 | nacos 完整字段同步 (teamReportAppId/SignKey/supportedPlatforms + payment 加密字段) | -| #1719 | payment 加 name + appId 字段 | -| **#1720** | **本 PR — supportedPlatforms 中文 label 翻译字段** | - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_feat_agency_visible_toggle.md b/changelogs/2026-05/06_feat_agency_visible_toggle.md deleted file mode 100644 index 1ffda01..0000000 --- a/changelogs/2026-05/06_feat_agency_visible_toggle.md +++ /dev/null @@ -1,116 +0,0 @@ -# feat(agency): 加 visible 小程序展示开关字段 - -**日期**: 2026-05-06 20:00 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1756 (已 merge dev, 测试服部署中) -**关联 Issue**: #1749 - ---- - -## 一、用户需求 - -后台「旅行社公司管理 → 基础信息」tab 需要新增「**是否在小程序展示**」开关字段，与现有「状态(启用/停用)」解耦： -- **状态(status)**: 业务启停 — 停用则不能下单/办合同 -- **是否展示(visible)**: 仅控制小程序端展示 — 关闭后业务不受影响，仅前端不渲染 - ---- - -## 二、改动 (后端) - -### DB - -新增列 `travel_agency.visible TINYINT(1) NOT NULL DEFAULT 1`，与 `status` 解耦。Flyway migration `V20260507_001` 自动 apply，历史 4 行 visible=1。 - -### VO 字段 - -| VO | 字段 | 类型 | 说明 | -|---|---|---|---| -| `AgencySaveReqVO` | `visible` | `Integer` | admin 编辑表单可选, 默认后端补 1 | -| `AgencyRespVO` | `visible` | `Integer` | admin 详情/列表响应 | -| `MpAgencyRespVO` | `visible` | `Integer` | mp `/primary` 响应携带 | -| `AgencyInternalDTO` | `visible` | `Integer` | 服务间 Feign 透传 | - -### 渲染策略 (前端约定) - -- `/mp/agency/primary` 仍按 `isPrimary=1` 返回主体公司（**不强制按 visible 过滤**, 避免主体一关全站无主体） -- 响应携带 `visible` 字段，**前端按此自行决定是否渲染对应 UI 区块** -- `visible=0` 时小程序的主体公司展示位（首页/我的页/客服/分享卡片/协议页落款）按需隐藏 - ---- - -## 三、前端建议 - -### admin 端 - 「基础信息」tab 加开关 - -```vue -<!-- 在「状态(启用/停用)」下方加一行 --> -<NFormItem label="是否在小程序展示" path="visible"> - <NSwitch - :value="form.visible === 1" - @update:value="(v) => form.visible = v ? 1 : 0" - checked-value - unchecked-value - /> -</NFormItem> -``` - -POST/PUT body 透传 `visible: 0/1`（不传时后端默认 1）。 - -### 小程序端 - 按 visible 渲染主体公司块 - -```js -// /mp/agency/primary 响应 -const { data } = await api.get('/mp/agency/primary') -if (data.visible === 0) { - // 隐藏主体公司展示位 (首页/我的页/协议页落款 等) - return null -} -// 正常渲染 data.agencyName / data.complaintPhone / data.qualifications ... -``` - ---- - -## 四、API round-trip (测试服, dev 部署后验证) - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -# admin 端: 详情含 visible -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/3" \ - -H "Authorization: Bearer $TOK" - -# admin 端: 编辑 visible=0 -curl -sk -X PUT "https://api.test.1814.love:9443/admin/travel-agency/3" \ - -H "Authorization: Bearer $TOK" \ - -H "Content-Type: application/json" \ - -d '{"code":"hulai-wenlu","agencyName":"...","businessLicenseNumber":"...","visible":0}' - -# mp 端: /primary 响应含 visible -curl -sk "https://api.test.1814.love:9443/mp/agency/primary" \ - -H "Authorization: Bearer $MP_TOKEN" -``` - ---- - -## 五、agency 模块 PR 清单 (5/6) - -| PR | 内容 | -|---|---| -| #1715 | admin path 纠回 `/admin/travel-agency` | -| #1717 | 资质附件分类 + 合同平台字典 | -| #1718 | nacos 完整字段同步 DB | -| #1719 | payment 加 name + appId | -| #1720 | supportedPlatforms 中文 label 字段 | -| #1721 | DB 单一真相源, nacos.agencies 弃用 | -| #1722 | 产品详情回显 agencyId/agencyName | -| #1728 | 删除「分公司名称」字段 | -| #1734 | 经营许可证号改非必填 | -| #1738 | mp/agency/primary 返资质附件列表 | -| **#1756** | **本 PR — 加 visible 小程序展示开关** | - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_feat_mp_agency_get_by_id_and_id_field.md b/changelogs/2026-05/06_feat_mp_agency_get_by_id_and_id_field.md deleted file mode 100644 index f0c0889..0000000 --- a/changelogs/2026-05/06_feat_mp_agency_get_by_id_and_id_field.md +++ /dev/null @@ -1,175 +0,0 @@ -# mp-agency: 新增 GET /mp/agency/{id} + 全部 mp 公司接口补返 agencyId - -> **服务**: hl-order-service-v2 (端口 8084) + hl-mp-service (端口 8085) -> **PR**: #1761(GET /mp/agency/{id}) + #1763(VO/DTO 补 agencyId) -> **Issue**: #1759 + #1762 -> **日期**: 2026-05-06 -> **影响范围**: C 端公司公开信息所有接口(/mp/agency/primary、/mp/agency/{id}、/mp/common/merchant-qualifications) -> **@mmg** - ---- - -## 一、背景 - -PR #1748(2026-05-06)让 `/mp/product/{id}` 详情接口返出团旅行社公司 ID(`agencyId`/`agencyName`)。前端拿到 agencyId 后需查公司详细信息(营业执照号/统一社会信用代码/客服电话/地址/资质附件)用于产品详情页/合同页/客服联系页展示。 - -之前只有 `/mp/agency/primary` 一个接口,只能查主体公司,无法支持"按非主体公司 ID 查"。本次新增 `/mp/agency/{id}` 闭环。 - -同时发现 `/mp/common/merchant-qualifications` 列表只返 code 不返 agencyId,前端拿到列表后无法用 `/mp/agency/{id}` 闭环查详情;`/mp/agency/primary`、`/mp/agency/{id}` 自己也不返 agencyId 无法做 cache key。**根因**:`MpAgencyRespVO` 评审 PR #1732 时为不暴露主键剔除了 agencyId,但 PR #1748 已让 `/mp/product/{id}` 暴露 agencyId,这条防线已失效。统一让所有 mp 公司接口都带 agencyId。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 按公司ID查公开详情 | GET | `/mp/agency/{id}` | **新增** | 免登录,字段结构 = /primary | -| 2 | 主体公司公开详情 | GET | `/mp/agency/primary` | 响应字段新增 | + `agencyId` | -| 3 | 合作公司公开列表 | GET | `/mp/common/merchant-qualifications` | 响应字段新增 | 每家公司元素 + `agencyId` | - ---- - -## 三、接口详情 - -### 1. 按公司ID查公开详情 `GET /mp/agency/{id}`(新增) - -**VO**: `MpAgencyRespVO`(等同 `/primary`) - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------|------| -| id | Path | Long | ✅ | - | 公司ID(来自 `/mp/product/{id}` 返的 `agencyId` 或 `/mp/common/merchant-qualifications` 列表元素 `agencyId`) | - -#### 出参 `Result<MpAgencyRespVO>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| agencyId | Long(JSON 序列化为 String 防 JS 精度丢失) | 公司ID | -| code | String | 公司编码 | -| agencyName | String | 公司名称 | -| licenseNumber | String | 旅行社业务经营许可证号 | -| businessLicenseNumber | String | 统一社会信用代码 | -| complaintPhone | String | 客服电话 | -| agencyAddress | String | 公司地址 | -| visible | Integer | 是否在小程序展示(1=展示/0=隐藏) | -| qualifications | List<MpAgencyQualificationVO> | 公开资质列表 | - -#### 鉴权 - -- **免登录**(网关 `/mp/agency/**` 已配 JwtAuthFilter 白名单) - -#### 请求示例 - -``` -GET /mp/agency/2051985889785012226 -``` - -#### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "agencyId": "2051985889785012226", - "code": "kj", - "agencyName": "内蒙古呼伦文化科技有限公司", - "licenseNumber": "", - "businessLicenseNumber": "91150702MAK1T8Q0XG", - "complaintPhone": "", - "agencyAddress": "", - "visible": 1, - "qualifications": [ - { - "name": "公司科技营业执照", - "qualificationType": "BUSINESS_LICENSE", - "qualificationTypeLabel": "营业执照", - "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...", - "fileType": "IMAGE", - "fileTypeLabel": "图片", - "issueDate": null, - "expireDate": null - } - ] - }, - "success": true -} -``` - -#### 错误响应 - -```json -{ "code": 594001, "message": "旅行社公司不存在(id=999999999999999999)", "success": false, "data": null } -``` - -```json -{ "code": 400, "message": "参数类型错误: id='abc'(需要 Long 类型)", "success": false, "data": null } -``` - ---- - -### 2. 主体公司公开详情 `GET /mp/agency/primary`(已存在,新增 agencyId 字段) - -响应结构完全等同新接口 `/mp/agency/{id}`,字段集相同;`agencyId` 为新增字段。 - ---- - -### 3. 合作公司公开列表 `GET /mp/common/merchant-qualifications`(已存在,新增 agencyId 字段) - -每个数组元素新增 `agencyId` + `visible` 字段(对齐 RespVO 字段集)。 - -```json -{ - "code": 200, - "data": [ - { - "agencyId": "2051985000000000001", - "code": "hulai", - "agencyName": "...", - "qualifications": [...] - } - ] -} -``` - ---- - -## 四、不影响范围 - -- **仅影响**: 上述 3 个 mp 公司接口(`/mp/agency/primary`、`/mp/agency/{id}`、`/mp/common/merchant-qualifications`)的响应结构(向前兼容: 只新增字段,不删不改) -- **零影响**: - - admin 端 agency 接口(`/admin/agency/**`)结构不变 - - 12301 凭据(appId/signKey)、支付配置(mchId/apiV3Key)依然不暴露给前端 - - 其他 mp 接口结构不变 - ---- - -## 五、测试环境已验证 - -``` -GET /mp/agency/primary → 200 + data.agencyId 非空 ✓ -GET /mp/agency/2051985889785012226 → 200 + data.agencyId == path id ✓ -GET /mp/agency/999999999999999999 → 200 + code:594001 AGENCY_NOT_FOUND ✓ -GET /mp/agency/abc → 200 + code:400 参数类型错 ✓ -``` - -`/mp/common/merchant-qualifications` 因 mp-service 端 `@MpCache` 30 min Redis 缓存,部署完成后**新结构(带 agencyId)在缓存自然过期后(< 30 min)自动生效**,无需重启;前端可在 30 min 后接入或直接以 `/mp/agency/primary` + `/mp/agency/{id}` 闭环。 - ---- - -## 六、前端建议接入方式 - -1. 产品详情页:`/mp/product/{id}` 拿到 `agencyId` → `/mp/agency/{id}` 拉公司详情(显示出团旅行社营业执照、资质附件等) -2. 合同页/协议页落款:沿用 `/mp/agency/primary`(主体公司) -3. 关于我们/合作公司列表:`/mp/common/merchant-qualifications` 列表 → 点击进详情 `/mp/agency/{agencyId}` - ---- - -## 七、相关文档 - -- Issue #1759: https://git.1814.love:8443/wx/HL/issues/1759 -- Issue #1762: https://git.1814.love:8443/wx/HL/issues/1762 -- PR #1761: https://git.1814.love:8443/wx/HL/pulls/1761 -- PR #1763: https://git.1814.love:8443/wx/HL/pulls/1763 -- 上游 PR #1748: `/mp/product/{id}` 补返 agencyId diff --git a/changelogs/2026-05/06_feat_mp_agency_qualifications.md b/changelogs/2026-05/06_feat_mp_agency_qualifications.md deleted file mode 100644 index a9aa753..0000000 --- a/changelogs/2026-05/06_feat_mp_agency_qualifications.md +++ /dev/null @@ -1,106 +0,0 @@ -# feat(mp-agency): /mp/agency/primary 新增公开资质附件列表 (替代 BUG2 误调) - -**日期**: 2026-05-06 19:50 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1738 (已 merge dev + 测试服部署 + round-trip ✓) -**关联工单**: wx/HL #1732 -**取代**: changelog `06_diag_mp_merchant_qualifications_not_found.md`(那个不需要 mmg 回复了) - ---- - -## 一、用户原本反馈 - -`/mp/common/merchant-qualifications` 接口不存在 + `/mp/agency/primary` 应返回附件。 - -## 二、后端实现 - -后端在 `/mp/agency/primary` 加了 `qualifications: List<MpAgencyQualificationVO>` 字段,前端从这里取资质。**不要再调** `/mp/common/merchant-qualifications`(本来就不存在)。 - -## 三、API 改动 - -**接口路径不变**:`GET /mp/agency/primary`(无需 token,公开接口) - -**响应新增 `data.qualifications` 字段**(测试服 round-trip 实测): - -```json -{ - "code": 200, - "message": "成功", - "data": { - "code": "hulai", - "agencyName": "内蒙古呼籁国际旅行社有限公司", - "licenseNumber": "L-NMG-100953", - "businessLicenseNumber": "91150702MACYFE851R", - "complaintPhone": "12301", - "agencyAddress": "内蒙古自治区呼伦贝尔市海拉尔区奋斗镇学府路煤校3号楼211号", - "qualifications": [ - { - "name": "呼籁国际营业执照", - "qualificationType": "BUSINESS_LICENSE", - "qualificationTypeLabel": "营业执照", - "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/rich-text/2026/05/06/ca98ae8cbd98ca9b3756f006b1ff7158.jpg", - "fileType": "IMAGE", - "fileTypeLabel": "图片", - "issueDate": null, - "expireDate": null - } - ] - }, - "success": true -} -``` - -## 四、`MpAgencyQualificationVO` 字段说明 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `name` | string | 资质名称(如 "呼籁国际营业执照") | -| `qualificationType` | string | 类型常量,字典 `agency_qualification_type` | -| `qualificationTypeLabel` | string | 类型中文(营业执照 / 旅行社业务经营许可证 / 增值电信业务经营许可证) | -| `fileUrl` | string | 文件 URL(目前透传永久 url,后续切 30min OSS 临时签名) | -| `fileType` | string | 文件类型常量(PDF / IMAGE / OTHER) | -| `fileTypeLabel` | string | 中文(PDF / 图片 / 其他) | -| `issueDate` | string | 颁发日期 yyyy-MM-dd,可空 | -| `expireDate` | string | 过期日期 yyyy-MM-dd,**null = 长期有效** | - -**敏感字段不暴露**:`qualificationId / agencyId / sortOrder / remark / createTime / updateTime`(内部审计字段不返 mp)。 - -## 五、前端处理建议 - -### 列表渲染 -- 后端已按 `sortOrder` 升序返回,前端**直接遍历不要重排** -- 空列表 `[]` 不要显示"暂无资质"区块,直接隐藏即可 -- 长度 1 条单卡片;长度 2+ 横向滑动或网格 - -### 卡片 UI -``` -┌─────────────────────────────────┐ -│ [营业执照] ←qualificationTypeLabel │ -│ ┌──────────┐ │ -│ │ <图片预览> │ ← fileType=IMAGE 时直接 <img src=fileUrl> │ -│ │ PDF icon │ ← fileType=PDF 时 PDF 占位 + 点击新窗口打开 │ -│ └──────────┘ │ -│ 名称: 呼籁国际营业执照 │ -│ 有效期至 2030-01-01 (or 长期有效) │ -└─────────────────────────────────┘ -``` - -### 点击预览 -- IMAGE → 调微信小程序的 `wx.previewImage`(传 fileUrl) -- PDF → `wx.downloadFile` + `wx.openDocument`(或 H5 `<a target=_blank>`) - -### 注意 -- `fileUrl` **目前是永久公开 url**(不是 30min 临时签名),后续 OSS STS 工具就绪后会切签名 url 有时效,**前端不要长期缓存**(过期重新请求接口) -- expireDate=null → 显示"长期有效",不要显示"null" -- 缩略图建议 OSS 图片处理参数 `?x-oss-process=image/resize,w_400` 减带宽(测试服已是 OSS,可直接拼) - -## 六、后端测试 - -- 单测 4 个新增 case 全绿 (mp Controller 2 + mp Service 2) -- 测试服 round-trip:`GET https://api.test.1814.love:9443/mp/agency/primary` 实测返 `qualifications[1]`,字段对齐 -- 内部字段泄漏检查:0 个(qualificationId/agencyId/sortOrder/remark/createTime/updateTime 全屏蔽) - -## 七、部署计划 - -- 测试服已部 (deploy task `51b55da8` success) -- 正式环境:等 release PR 合 main 后通知运维部署(本次和 PR #1737 一起) diff --git a/changelogs/2026-05/06_feat_mp_merchant_qualifications_alias_landed.md b/changelogs/2026-05/06_feat_mp_merchant_qualifications_alias_landed.md deleted file mode 100644 index 2497adb..0000000 --- a/changelogs/2026-05/06_feat_mp_merchant_qualifications_alias_landed.md +++ /dev/null @@ -1,86 +0,0 @@ -# feat(mp-common): /mp/common/merchant-qualifications 已落地兼容 alias (前端无需改) - -**日期**: 2026-05-06 21:10 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1745 (已 merge dev + 测试服部署 + round-trip 字段结构 100% 对齐) -**关联工单**: wx/HL #1732 -**接续**: changelog `06_feat_mp_agency_qualifications.md`(BUG3) - ---- - -## 一、好消息 - -之前那条 `06_feat_mp_agency_qualifications.md` 提到「前端可以从 `/mp/agency/primary` 取 qualifications」。**现在 BUG4 也做完了**: - -后端在 `/mp/common/merchant-qualifications` 也加了同样的接口(alias)。**已发版小程序代码无需改任何东西**,继续调原 url 就能直接拿到主体公司 + 资质附件,字段结构与 `/mp/agency/primary` 100% 一致。 - -## 二、测试服 round-trip 实测对比 - -``` -=== /mp/agency/primary === -keys: agencyAddress, agencyName, businessLicenseNumber, code, - complaintPhone, licenseNumber, qualifications -qualifications length: 2 - -=== /mp/common/merchant-qualifications === -keys: agencyAddress, agencyName, businessLicenseNumber, code, - complaintPhone, licenseNumber, qualifications -qualifications length: 2 - -字段差异: 无 -qual[0].name 一致: 呼籁国际营业执照 -qual[0].fileUrl 一致: ✓ -``` - -## 三、给前端的最终方案 - -| 场景 | URL | 备注 | -|---|---|---| -| **已发版小程序** | `GET /mp/common/merchant-qualifications` | **不动**,后端 alias 兼容 | -| 新前端版本(可选) | `GET /mp/agency/primary` | 推荐,少一跳 mp-service → order-v2,响应略快 | - -**两个 URL 字段结构完全一样**,任选其一,前端代码完全相同的解析逻辑。 - -## 四、响应字段(参考 BUG3 changelog) - -```json -{ - "code": 200, "message": "成功", - "data": { - "code": "hulai", - "agencyName": "内蒙古呼籁国际旅行社有限公司", - "licenseNumber": "L-NMG-100953", - "businessLicenseNumber": "91150702MACYFE851R", - "complaintPhone": "12301", - "agencyAddress": "...", - "qualifications": [ - { - "name": "呼籁国际营业执照", - "qualificationType": "BUSINESS_LICENSE", - "qualificationTypeLabel": "营业执照", - "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...", - "fileType": "IMAGE", - "fileTypeLabel": "图片", - "issueDate": null, - "expireDate": null - } - ] - } -} -``` - -`qualifications: []` 时不要展示资质区块,直接隐藏即可(后端按 sortOrder 升序返回)。 - -## 五、合 main 计划 - -按用户指令,**本 PR 暂不合 main**。所以正式环境短期内仍是旧行为(`/mp/common/merchant-qualifications` 返"接口不存在"+ `/mp/agency/primary` 返不带 qualifications)。 - -新需求积累几条后再统一发 release。前端可以先在测试服联调: -- 测试服 `https://api.test.1814.love:9443/mp/common/merchant-qualifications` 已可用 ✓ - -## 六、其他相关 BUG 一并通报 - -同期还修了几条: -- `06_fix_insurance_recharge_pay_url.md` — 保险充值返支付链接(已上 prod ✓) -- `06_feat_mp_agency_qualifications.md` — `/mp/agency/primary` 加 qualifications(本 changelog 接续) -- `06_fix_admin_set_primary_method_post_to_put.md` — admin 切换主体接口请用 PUT 不是 POST(前端改一行) diff --git a/changelogs/2026-05/06_feat_order_traveler_smart_import.md b/changelogs/2026-05/06_feat_order_traveler_smart_import.md deleted file mode 100644 index add1893..0000000 --- a/changelogs/2026-05/06_feat_order_traveler_smart_import.md +++ /dev/null @@ -1,105 +0,0 @@ -# [feat] 订单管理端「出行人智能批量导入」接口 - -- **日期**: 2026-05-06 -- **PR**: wx/HL #1714 (Closes #1713) + #1716 hotfix -- **后端**: wx (Claude) -- **前端 @**: mmg -- **状态**: ✅ 测试服全链路网关 round-trip 15/15 通过(2026-05-06 15:50 部署 5149e329) - ---- - -## 接口 - -``` -POST {GATEWAY}/admin/order-traveler/smart-parse -Header: Authorization: Bearer <admin token> -Body: -{ - "rawText": "张三 350101199001011231 13800138000\n李四 110101199201021237 13900139000" -} -``` - -## 响应结构 - -```jsonc -{ - "code": 200, - "data": { - "totalLines": 2, - "successCount": 2, - "failCount": 0, - "travelers": [ - { - "lineNo": 1, - "name": "张三", - "idCardType": "ID_CARD", - "idCardTypeLabel": "身份证", - "idCardNo": "350101199001011231", - "phone": "13800138000", - "gender": "1", // "1"男 / "2"女 / null(身份证解析失败) - "birthday": "1990-01-01", // yyyy-MM-dd 字符串 - "travelerType": "ADULT", - "travelerTypeLabel": "成人" // 中文必返非 null - } - ], - "errors": [ - // { lineNo, raw(脱敏), reason(中文), severity: "FAIL" | "WARNING" } - // FAIL = 行解析失败,计入 failCount - // WARNING = 行成功但有提示(多身份证号取首/重复 idCard 等),不计入 failCount - // 恒等式: successCount + failCount == totalLines - ] - } -} -``` - -## 关键约束 - -- **顺序无关识别**: 每行任意顺序写姓名/身份证/手机号都能正确归位;18 位身份证→`idCardNo` 自动派生 `birthday/gender/travelerType`,11 位 1 开头→`phone`,其他→`name` -- **容错**: 表头跳过(三 token AND)、行首序号剥离(`1./1、/1)`)、BOM/零宽字符 strip、半角/全角/制表符空格切分 -- **校验**: 18 位 GB 11643-1999 校验码(不支持 15 位旧版) -- **字段对齐**: ParsedTraveler 100% 对齐 `AdminOrderTravelerAddReqVO`,可直接 `formData = parsedTraveler` 一键回填 -- **`birthday` 序列化为 `"yyyy-MM-dd"` 字符串**(已 @JsonFormat,前端 DatePicker 直接吃) -- **`*Label` 必返中文非 null**(P0 #1679,字典失败 throw 不兜底) -- **后端不直接落库**: 仅解析返回,前端拿到结果回填出行人表格(可编辑),用户确认后调原 `POST /admin/order/{orderId}/travelers` 入库 - -## 限制 - -| 限制 | 值 | 错误码 | -|------|-----|--------| -| 单次行数 | ≤ 100 | `SMART_PARSE_LINE_LIMIT_EXCEEDED` (504003) | -| 单次文本 | ≤ 20000 字符 | `SMART_PARSE_TEXT_TOO_LONG` (504004) + @Size 兜底 | -| 单行长度 | ≤ 500 字符 | 行内失败,reason=单行超长 | -| 限流 | 每用户 10 次 / 分钟 | `@RateLimiter` | -| 字典服务 | 失败 throw | `DICT_SERVICE_UNAVAILABLE` (504005) | - -## 失败原因(中文) - -- `身份证号校验失败` — 18 位但末位校验码错 -- `不支持 15 位身份证,请用 18 位` -- `缺少身份证号` / `缺少姓名` / `未识别到姓名` -- `本行检测到多个身份证号,已取第一个` (warning) -- `身份证号在本次导入内重复` (warning,双胞胎/同名场景不强制去重) -- `单行超长(>500),疑似格式错误` -- `姓名含非法字符` - -## 前端 UI 落点(@mmg) - -参考用户提供的截图("快捷导入"弹窗): -- 入口: 订单详情 → 出行人信息 Tab → 「添加出行人」旁加「智能导入」按钮 -- 弹窗: 多行 Textarea + 提示文案「导入要求:一人一行 姓名 身份证 手机号码之间用空格隔开」 -- 确定 → 调本接口 → 拿 `travelers[]` 回填出行人表格(每行一条,可编辑) -- `errors[]` 高亮失败行,允许用户在原文本框修正后再次提交 -- `successCount=0` 时弹「全部解析失败,请检查格式」 -- `errors[i].lineNo` 是已剔除空行/表头/序号干扰后的数据行序号(非物理行号) - -## 兼容性 - -- 仅新增接口,无 DDL / 无字典数据变更 / 无 Nacos 配置变更 -- 复用现有 `AdminOrderTravelerController` 的 add 接口入库,流程不变 -- 限流走项目自研 `@RateLimiter`,Redis 挂时自动放行(降级) - -## 测试覆盖 - -- 单测: Service 49 + Controller MockMvc 9 + PiiMaskUtil 18 + IdCardChecksumUtil 13 = **89/89 全绿** -- CR: 9.6/10 通过(P0 红线 @OperationLog AOP 移除防 PII 落审计) -- 真 round-trip(网关/真容器/真限流/真 Feign): 部署测试服后补 diff --git a/changelogs/2026-05/06_feat_product_equipment_template.md b/changelogs/2026-05/06_feat_product_equipment_template.md deleted file mode 100644 index ff035ce..0000000 --- a/changelogs/2026-05/06_feat_product_equipment_template.md +++ /dev/null @@ -1,135 +0,0 @@ -# feat(product): 装备建议组合可复用模板 + 产品设计绑定 - -**日期**: 2026-05-06 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1768 -**关联工单**: wx/HL #1767 (closed) -**测试服部署**: dev 已合并 commit `6c879da9`,等自动部署 + /@qa round-trip(部署完后会在工单 #1767 下补 verification comment) - ---- - -## 一、背景 - -产品编辑「补充信息→预订须知→装备建议」当前每个产品要逐条录入(≤20 条 文本+图标),重复劳动。新增可复用模板:运营在 admin 维护一份「装备建议组合」清单,产品设计时绑定 1 个组合,**实时引用**(模板修改 → 已绑产品 MP 详情自动跟随)。 - ---- - -## 二、后端新增接口(admin 端,7 个) - -> 服务: `hl-product-service-v2` (8083) · 网关 path: `/admin/equipment-template` - -| Method | Path | 说明 | -|--------|------|------| -| POST | `/admin/equipment-template` | 创建模板 (`EquipmentTemplateSaveReqVO`) | -| PUT | `/admin/equipment-template/{id}` | 更新模板 (`EquipmentTemplateSaveReqVO`) | -| DELETE | `/admin/equipment-template/{id}` | 软删 (被产品引用时返业务码 `EQUIPMENT_TEMPLATE_IN_USE` + 引用产品数) | -| PUT | `/admin/equipment-template/{id}/status` | 切启用/停用 (`EquipmentTemplateStatusReqVO`) | -| GET | `/admin/equipment-template/page?keyword=&status=&page=&pageSize=` | 分页查询 | -| GET | `/admin/equipment-template/{id}` | 详情 | -| GET | `/admin/equipment-template/enabled` | 启用项下拉(不分页,按 sort_order/template_id) | - -### Request/Response 字段(关键) - -**`EquipmentTemplateSaveReqVO`**: -- `name: String` (必填, 1-30 字, **全局未删重名禁建**) -- `items: List<EquipmentItem>` (必填, 1-20 条, `@Valid` 嵌套校验) - - `text: String` (必填, 1-50 字) - - `icon: String` (必填, 前端约定短标识或完整 SVG XML, 长度 1-8000) - - `color: String` (可选, 长度 ≤16, 如 `#FFA726`) -- `sortOrder: Integer` (可选, 默认 0, 越小越靠前) - -**`EquipmentTemplateStatusReqVO`**: -- `status: String` (必填, `ENABLED` 或 `DISABLED`, `@Pattern` 校验) - -**`EquipmentTemplateRespVO`** (详情/分页项): -- `templateId: Long` / `name` / `items: List<EquipmentItem>` / `itemCount: Integer`(衍生)/ `status` / `statusLabel: String`(中文`启用/停用`)/ `sortOrder` / `createdBy: Long`(仅 ID,首版不返姓名)/ `createTime` / `updateTime` - -**`EquipmentTemplateSimpleRespVO`** (`/enabled` 下拉用): -- `templateId / name / itemCount / status` (4 字段) - ---- - -## 三、产品端字段改动(前端必改) - -### 1. 产品保存接口 `PUT /admin/product/item/{id}/supplement` - -`ProductSupplementSaveReqVO` **新增字段**: -- `equipmentTemplateId: Long` (可选, 非空时即绑定模板) - -### 2. 产品详情接口 `GET /admin/product/item/{id}` - -`ProductDetailRespVO.supplement` **新增字段**: -- `equipmentTemplateId: Long` (当前绑定模板 ID) -- `equipmentTemplateName: String` (绑定模板的名字, **即使模板已停用也能显示**, 前端可在下拉里给停用项加灰色 + "已停用"前缀) - -### 3. 产品 Step5 三态 UI(关键) - -| 状态 | UI 行为 | -|------|---------| -| ① 未绑模板 (`equipmentTemplateId` 为空) | 现有 `equipment_list` 录入区可编辑(必填 ≥1 条,与现状一致) | -| ② 绑模板 | 下方 `equipment_list` 录入区**变只读预览**, 展示模板的 `items`, 标注「来自组合 XX, 如需修改请去装备建议组合管理」;`equipment_list` 原值在 DB 里**保留不清空**(为③解绑后恢复用) | -| ③ 解绑模板(下拉清空) | `equipment_list` 恢复可编辑, 显示原值(用户切换前的内容) | - -### 4. 模板下拉策略 - -- 默认仅显示 `status=ENABLED` 的模板, 按 sort_order, template_id 排序 -- **若当前产品已绑模板, 即使该模板被停用, 也保留显示并标"已停用"前缀**(用户可保留或换为启用项) — 此时前端用 `equipmentTemplateName` 渲染下拉文本 - -### 5. 必填规则 - -提交审核校验: 装备建议非空 = (`equipmentTemplateId` 非空 AND 模板未删) OR (`equipment_list` 非空) — 二选一 - ---- - -## 四、MP 端(小程序)行为(无新接口) - -`GET /mp/product/{id}` 返回的 `equipmentList` 字段: - -- 若 `equipment_template_id` 非空 AND 模板未软删 → **实时**返回模板的 `items`(模板修改自动跟随,清缓存后 5 分钟内可见) -- 若模板被软删 → fallback 用 `equipment_list`(避免 MP 端报错) -- 若 `equipment_template_id` 为空 → 直接用 `equipment_list`(保持现状) -- `equipmentAdvice` 旧字段保留兼容,逻辑不变 - -**订单详情边界**: 订单生成时已固化 `equipment_list` 副本到订单快照, 订单详情**永远走快照不读模板**, 模板后续修改对已成订单 0 影响。 - ---- - -## 五、错误码(`ProductTemplateErrorCode`,段位 440000-449999) - -| Code | 含义 | 触发场景 | -|------|------|---------| -| 440101 | EQUIPMENT_TEMPLATE_NAME_DUPLICATED | 创建/更新时同名模板已存在(未软删) | -| 440102 | EQUIPMENT_TEMPLATE_IN_USE | 删除时被 N 个产品引用,前端展示「已被 {N} 个产品绑定,请先解除绑定」 | -| 440103 | EQUIPMENT_TEMPLATE_NOT_FOUND | 模板不存在或已软删 | - ---- - -## 六、入口挂载(admin 后台) - -⚠️ **更正**(2026-05-07 用户澄清):**不是独立菜单**,是在**产品线页面**(/product/line)右上角加「装备建议组合」按钮,点击打开管理面板/弹窗(列表 + 新增/编辑/启停/删除),复用后端 7 个 `/admin/equipment-template/*` 接口。 - -之前 changelog 写的「配置中心独立菜单 + 安全保障/FAQ/行程保障并列」**作废** — 实际入口在产品线列表页内嵌按钮,管理面板不占独立路由。 - ---- - -## 七、不在范围(本期不做) - -- 装备图标素材库化(继续保持前端约定) -- 模板适用产品类型筛选(`applicable_types` 列) -- 模板分类标签 / 适用季节 -- 多组合叠加绑定 -- 模板版本历史 -- 模板创建人姓名(`createdByName`),首版仅返 `createdBy: Long` ID - ---- - -## 八、需要重启的服务 - -- `hl-product-service-v2` (8083) — 测试服部署 dev 后自动重启 -- 其他服务无影响 - ---- - -## 九、本地启动需要的事(参考 PR #1065 会话隔离) - -后端无需新 nacos 配置, Flyway 自动 apply `V20260507_002` DDL。 `equipment_template` 表 + `product_supplement.equipment_template_id` 列在 product-v2 启动时自动创建。 diff --git a/changelogs/2026-05/06_fix_admin_set_primary_method_post_to_put.md b/changelogs/2026-05/06_fix_admin_set_primary_method_post_to_put.md deleted file mode 100644 index 8de357b..0000000 --- a/changelogs/2026-05/06_fix_admin_set_primary_method_post_to_put.md +++ /dev/null @@ -1,53 +0,0 @@ -# fix(agency-admin): set-primary 接口必须用 PUT 不是 POST - -**日期**: 2026-05-06 20:30 -**通知对象**: @mmg (前端) -**关联 BUG 反馈**: 用户报 `http://localhost:9527/admin/travel-agency/2051985889785012226/set-primary` 报"请求方法不支持: POST" - ---- - -## 一、根因(前端 BUG) - -后端 `AdminTravelAgencyController.setPrimary` 在 `hl-order-service-v2/src/main/java/com/hulalv/agency/controller/admin/AdminTravelAgencyController.java:99-104` 是 **`@PutMapping`**: - -```java -@PutMapping("/{id}/set-primary") -@ApiOperation("设为主体公司(SUPER_ADMIN)") -public Result<Void> setPrimary(@PathVariable("id") Long id) { - agencyService.setPrimary(id); - return Result.success(); -} -``` - -前端发的是 **`POST`** → 网关 `MethodArgumentNotSupportedException` 返"请求方法不支持: POST"。 - -## 二、为什么后端用 PUT - -REST 语义 + 同模块其他**状态变更**接口都是 PUT(保持一致): -- `PUT /admin/travel-agency/{id}/disable` 停用 -- `PUT /admin/travel-agency/{id}/enable` 启用 -- `PUT /admin/travel-agency/{id}/set-primary` 设为主体 ← 同一类语义 - -`POST /admin/travel-agency` 用于"新建公司"(资源创建),不在状态变更范畴。 - -## 三、前端修复 - -把"设为主体"按钮的 API 调用从: - -```js -http.post(`/admin/travel-agency/${id}/set-primary`) -``` - -改为: - -```js -http.put(`/admin/travel-agency/${id}/set-primary`) -``` - -## 四、为什么不改后端 - -如果改后端为 POST,会和 `disable` / `enable` 同模式风格冲突,REST 语义不一致 — 后续看代码的人会困惑"为啥状态变更有 PUT 又有 POST"。 - -## 五、不建工单 - -按规则前端 BUG 都走 changelog,不建 wx/HL 或 wx/hl-ui issue。 diff --git a/changelogs/2026-05/06_fix_agency_admin_path_correction.md b/changelogs/2026-05/06_fix_agency_admin_path_correction.md deleted file mode 100644 index c78acd6..0000000 --- a/changelogs/2026-05/06_fix_agency_admin_path_correction.md +++ /dev/null @@ -1,130 +0,0 @@ -# fix(agency): admin 接口 path 从 /admin/agency 纠回设计冻结的 /admin/travel-agency - -**日期**: 2026-05-06 15:39 -**通知对象**: @mmg (前端) — **必须改前端 baseURL/请求 path** -**关联 PR**: wx/HL #1715 (已 merge dev + 测试服部署完成 + round-trip 验证通过) -**关联文档**: `06_feat_agency_management_module.md` (定稿已同步 patch) - ---- - -## ⚠️ 一句话摘要 - -**所有 admin 端旅行社公司接口的 path 已经从 `/admin/agency/*` 改回设计文档冻结的 `/admin/travel-agency/*`。前端必须改请求 path,旧 path 测试服已 HTTP 404。** - ---- - -## 一、为什么要改 - -| 阶段 | path | 状态 | -|------|------|------| -| 设计文档 (PRD 冻结) | `/admin/travel-agency/*` | ✅ 真相源 | -| 代码副本 A 实施 (PR #1710) | `/admin/agency/*` | ❌ 擅自缩短,与设计漂移 | -| changelog 第一版 (2026-05-06 15:13) | `/admin/agency/*` | ❌ 跟着实施漂 | -| 前端实际调用 | `/admin/travel-agency/*` | ✅ 按设计文档调用 | -| 测试服 gateway 路由 | `/admin/agency/**` | ❌ 前端 404 | -| **本次纠回 (PR #1715, 2026-05-06 15:39)** | `/admin/travel-agency/*` | ✅ **代码 + gateway + changelog 三处全部对齐设计** | - -**纠回原则**: 代码必须和告知前端的契约一致,设计文档是唯一真相源。 - ---- - -## 二、path 全量对照表 (前端必改) - -### 1. 主体 CRUD (admin) - -| Method | 旧 path (HTTP 404) | 新 path (前端必改) | -|--------|------------|------------| -| GET | ~~`/admin/agency/page`~~ | `/admin/travel-agency/page` | -| GET | ~~`/admin/agency/{id}`~~ | `/admin/travel-agency/{id}` | -| GET | ~~`/admin/agency/enabled`~~ | `/admin/travel-agency/enabled` | -| POST | ~~`/admin/agency`~~ | `/admin/travel-agency` | -| PUT | ~~`/admin/agency/{id}`~~ | `/admin/travel-agency/{id}` | -| POST | ~~`/admin/agency/{id}/disable`~~ | `/admin/travel-agency/{id}/disable` | -| POST | ~~`/admin/agency/{id}/set-primary`~~ | `/admin/travel-agency/{id}/set-primary` | -| DELETE | ~~`/admin/agency/{id}`~~ | `/admin/travel-agency/{id}` | - -### 2. 资质子表 - -| Method | 旧 path | 新 path | -|--------|------------|------------| -| GET | ~~`/admin/agency/{agencyId}/qualification`~~ | `/admin/travel-agency/{agencyId}/qualification` | -| POST | ~~`/admin/agency/{agencyId}/qualification`~~ | `/admin/travel-agency/{agencyId}/qualification` | -| PUT | ~~`/admin/agency/{agencyId}/qualification/{id}`~~ | `/admin/travel-agency/{agencyId}/qualification/{id}` | -| DELETE | ~~`/admin/agency/{agencyId}/qualification/{id}`~~ | `/admin/travel-agency/{agencyId}/qualification/{id}` | - -### 3. 支付子表 - -| Method | 旧 path | 新 path | -|--------|------------|------------| -| GET | ~~`/admin/agency/{agencyId}/payment`~~ | `/admin/travel-agency/{agencyId}/payment` | -| POST | ~~`/admin/agency/{agencyId}/payment`~~ | `/admin/travel-agency/{agencyId}/payment` | -| PUT | ~~`/admin/agency/{agencyId}/payment/{paymentId}`~~ | `/admin/travel-agency/{agencyId}/payment/{paymentId}` | -| DELETE | ~~`/admin/agency/{agencyId}/payment/{paymentId}`~~ | `/admin/travel-agency/{agencyId}/payment/{paymentId}` | -| POST | ~~`/admin/agency/{agencyId}/payment/{paymentId}/set-default`~~ | `/admin/travel-agency/{agencyId}/payment/{paymentId}/set-default` | - -### 4. mp 端 (无变化) - -`/mp/agency/primary` **不变** (本次仅纠 admin path,mp 端 path 与设计一致,不动)。 - ---- - -## 三、前端最小改动建议 - -如果前端封装了 axios 公司模块的 baseURL/path,只需把字符串 `admin/agency` → `admin/travel-agency` 全文替换即可: - -```bash -# hl-ui 前端项目根: -# Linux/Mac -grep -rn "admin/agency" src/ --include="*.js" --include="*.vue" --include="*.ts" -# Windows PowerShell -Select-String -Path src/**/*.{js,vue,ts} -Pattern "admin/agency" -# 然后批量替换 admin/agency → admin/travel-agency -``` - ---- - -## 四、测试服 round-trip 验证 (2026-05-06 15:39) - -```bash -# 拿 admin token -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -# ✅ 新 path 返 200 + 3 家公司明文 -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/enabled" \ - -H "Authorization: Bearer $TOK" -# {"code":200,"message":"成功","data":[ -# {"agencyId":"...","code":"hulai","agencyName":"内蒙古呼籁...","isPrimary":1}, -# {"agencyId":"...","code":"qianshou","agencyName":"内蒙古呼籁牵手..."}, -# {"agencyId":"...","code":"hulai-wenlu","agencyName":"内蒙古呼籁文旅..."} -# ]} - -# ❌ 旧 path 测试服已 HTTP 404 -curl -sk -w "\nHTTP %{http_code}\n" "https://api.test.1814.love:9443/admin/agency/enabled" -# {"timestamp":"...","path":"/admin/agency/enabled","status":404,"error":"Not Found"} -# HTTP 404 -``` - ---- - -## 五、影响面 - -- **admin 后台 (前端必改)**: 旅行社公司管理模块所有 admin 接口 path -- **mp 端**: ⛔ 无影响 (mp 端 path 没变) -- **后端代码**: ✅ controller @RequestMapping + gateway routes 已对齐, internal Feign + 单测无影响 -- **数据**: ✅ 无 schema/数据变化, 仅 path 字符串改名 - ---- - -## 六、相关 commit - -- wx/HL PR #1710 (定稿主 PR, 含偏离的 path) -- wx/HL PR #1711 (runtime hotfix) -- wx/HL PR #1712 (gateway 白名单 hotfix) -- **wx/HL PR #1715 (本次 path 纠回, dev 已合 + 测试服已部署 + round-trip 通过)** - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_fix_agency_cache_evict_bridge_to_mp.md b/changelogs/2026-05/06_fix_agency_cache_evict_bridge_to_mp.md deleted file mode 100644 index d0acb97..0000000 --- a/changelogs/2026-05/06_fix_agency_cache_evict_bridge_to_mp.md +++ /dev/null @@ -1,56 +0,0 @@ -# 修复 agency 写动作未桥接 mp 缓存反向失效 (#1758 follow-up) - -**类型**: BUG 修复(后端单点 / 缓存一致性) -**前端处理者**: mmg(无前端动作) -**日期**: 2026-05-06 -**关联**: PR #1764 (#1758 follow-up of PR #1760) - ---- - -## 现象 - -PR #1760 修复了 `/mp/common/merchant-qualifications` 漏过滤 visible 字段的 BUG, 但部署后 round-trip 发现: -- DB 真值 `hulai-wenlu` visible=0, status=ENABLED -- mp 接口仍返回 3 家公司(包含 hulai-wenlu) - -## 根因 - -`TravelAgencyServiceImpl.afterCommitAuditAndCacheBust` 注释明确「跨服务缓存失效由后续 PR 处理」, 实际只清了本地 Caffeine, **从未调 `DependencyAwareCacheManager.invalidateSource`**。 - -PR #1707 引入 agency 模块以来, admin update/create/delete agency 后: -- 本地 Caffeine 立刻清 -- mp service 的 `@MpCache(deps={"table:travel_agency", "table:travel_agency_qualification"})` 在 redis 反向索引上从未被失效 -- mp 端 1800s TTL 内永远拿旧数据 - -## 修复 - -参照 `ProductHelperService` / `ActivityService` 同模式: - -```java -private final DependencyAwareCacheManager depsManager; -private static final String SRC_TRAVEL_AGENCY = "table:travel_agency"; -private static final String SRC_TRAVEL_AGENCY_QUALIFICATION = "table:travel_agency_qualification"; - -// afterCommit 内追加 -try { - depsManager.invalidateSources(SRC_TRAVEL_AGENCY, SRC_TRAVEL_AGENCY_QUALIFICATION); -} catch (Exception e) { - log.warn("..."); -} -``` - -## 验证 - -测试服 round-trip 双向: -- visible=0 后立即 GET mp → 返回 2 家(hulai, qianshou,无 hulai-wenlu) ✓ -- visible=1 还原后立即 GET mp → 返回 3 家(全部) ✓ -- 缓存即时生效, 不等 1800s TTL ✓ - -## 前端无需改动 - -接口 URL/响应结构无变化, 仅缓存一致性修复, mmg 无需任何动作。 - -## 影响范围 - -- agency 主表 6 个写动作(create/update/disable/enable/delete/setPrimary)经同一 afterCommit 触发,本 PR 一次性桥接全部 -- agency 子表 service (qualifications/payments) 写动作未在本 PR 范围 - 后续 follow-up diff --git a/changelogs/2026-05/06_fix_agency_qualification_upload_content_type.md b/changelogs/2026-05/06_fix_agency_qualification_upload_content_type.md deleted file mode 100644 index 386377b..0000000 --- a/changelogs/2026-05/06_fix_agency_qualification_upload_content_type.md +++ /dev/null @@ -1,143 +0,0 @@ -# fix(agency): 旅行社资质附件上传必须先调通用 OSS 接口拿 url, 再以 application/json 提交元数据 - -**日期**: 2026-05-06 18:30 -**通知对象**: @mmg (前端) — **必须改前端「公司资质 - 新增/编辑」请求方式** -**关联 PR**: 无 (后端无需改动, 接口设计与项目内其它「URL 字段」类接口一致) -**测试服 round-trip**: ✅ JSON 路径创建成功 / multipart 路径复现 500 - ---- - -## ⚠️ 一句话摘要 - -**`POST /admin/travel-agency/{agencyId}/qualification` 后端接的是 `application/json`, 前端目前直接发 `multipart/form-data`(把文件流当成 body) → Spring MVC 抛 `HttpMediaTypeNotSupportedException` 返回 500。前端必须改成两步上传: 先调通用 OSS 上传接口拿 url, 再 POST 资质接口带 fileUrl 等元数据 JSON。** - ---- - -## 一、报错信息 - -``` -服务器内部错误[HttpMediaTypeNotSupportedException]: -Content type 'multipart/form-data;boundary=----WebKitFormBoundaryW7TegwvnmSqm3boT;charset=UTF-8' not supported -``` - -触发路径: `POST /admin/travel-agency/2051922156798779394/qualification` - ---- - -## 二、后端契约 (不变) - -``` -POST /admin/travel-agency/{agencyId}/qualification -Content-Type: application/json -Authorization: Bearer <token> -``` - -请求 body (`AgencyQualificationSaveReqVO`): - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `name` | String(64) | ✅ | 资质名称, 例: `旅行社业务经营许可证` / `营业执照` | -| `qualificationType` | String(32) | ✅ | 字典 `agency_qualification_type`: `BUSINESS_LICENSE` / `TRAVEL_AGENCY_LICENSE` / `VALUE_ADDED_TELECOM_LICENSE` | -| `fileUrl` | String | ✅ | **OSS 永久 URL (从通用上传接口拿)**, **不是文件流** | -| `fileType` | String | 否 | 字典 `agency_qualification_file_type`: `PDF` / `IMAGE` / `OTHER` | -| `issueDate` | LocalDate | 否 | 颁发日期, `2024-01-01` | -| `expireDate` | LocalDate | 否 | 过期日期, `null=长期有效` | -| `sortOrder` | Integer | 否 | 排序值 | -| `remark` | String | 否 | 备注 | - -> 编辑接口 `PUT /admin/travel-agency/{agencyId}/qualification/{qualificationId}` 同样 JSON, body 同上。 - ---- - -## 三、前端正确调用方式 (两步) - -### 步骤 1 - 上传文件到 OSS, 拿到永久 URL - -``` -POST /admin/sys/oss/upload -Content-Type: multipart/form-data -Authorization: Bearer <token> -form-data: file=<File 对象> -``` - -返回: - -```json -{ - "code": 200, - "data": { - "id": 123, - "url": "https://hulalv-private.oss-cn-shanghai.aliyuncs.com/xxx/yyy.pdf", - "name": "营业执照.pdf", - "size": 102400 - } -} -``` - -> 这是项目内通用 OSS 上传接口, 富文本/素材库已经在用, 复用即可 — `hl-ui/src/api/material.js#uploadFile` 应该就是这个。 - -### 步骤 2 - 提交资质元数据 (带上一步拿到的 url) - -``` -POST /admin/travel-agency/{agencyId}/qualification -Content-Type: application/json -Authorization: Bearer <token> -``` - -```json -{ - "name": "营业执照", - "qualificationType": "BUSINESS_LICENSE", - "fileUrl": "https://hulalv-private.oss-cn-shanghai.aliyuncs.com/xxx/yyy.pdf", - "fileType": "PDF", - "issueDate": "2024-01-01", - "expireDate": "2029-12-31", - "sortOrder": 100, - "remark": "营业期限至 2029-12-31" -} -``` - -返回: - -```json -{ "code": 200, "data": 2051971194931859458 } -``` - -`data` 是新建的 `qualificationId`, 编辑/删除接口需要带它。 - ---- - -## 四、为什么不让后端直接接 multipart - -1. **设计一致性**: 项目内「URL 字段」类接口(产品图、合同附件元数据、酒店封面等)统一约定 `fileUrl: String`, 文件上传统一走 `/admin/sys/oss/upload`, 业务接口只接 JSON 元数据。 -2. **OSS 直传降本**: 走通用上传接口可以走未来的 OSS STS 直传链路, 业务接口不需要重复封装文件流。 -3. **后续 P1-11 任务**: `fileUrl` 在 RespVO 中要转 30 min 临时签名 URL (私有 bucket), 这套也是基于「永久 url 落库」的两步设计。 - -> 项目里另一个接口 `POST /admin/contract/scheme/{schemeId}/attachments` 直接接 multipart 是历史模式, 新接口都按上面两步走。 - ---- - -## 五、Round-trip 验证记录 - -| 测试 | Content-Type | 期望 | 实际 | -|------|------|------|------| -| 1 | `application/json` | 创建成功 | ✅ HTTP 200 + `code:200` + `data:2051971194931859458` (已清理) | -| 2 | `multipart/form-data` (前端目前的发法) | 复现报错 | ✅ HTTP 200 + `code:500` (前端看到的报错) | - -测试服: `https://api.test.1814.love:9443` -agencyId: `2051922156798779394` -admin token: 真实登录 (admin / Admin@123456) - ---- - -## 六、改动范围 (前端) - -| 模块 | 改动 | -|------|------| -| `hl-ui/src/api/agency.js` (或同名文件) 资质 CRUD 函数 | 新增/编辑请求体改成 JSON, 不再 FormData | -| 「公司详情 - 资质附件」组件 | 上传组件先调 OSS 拿 url, 再调资质接口提交元数据 | -| 删除/列表/排序接口 | 不受影响, 已 round-trip 通过 | - ---- - -**有不清楚的字段或字典值, 直接 @ wx 加补。** diff --git a/changelogs/2026-05/06_fix_agency_remove_company_branch_name.md b/changelogs/2026-05/06_fix_agency_remove_company_branch_name.md deleted file mode 100644 index 1dcc3b2..0000000 --- a/changelogs/2026-05/06_fix_agency_remove_company_branch_name.md +++ /dev/null @@ -1,97 +0,0 @@ -# fix(agency): 删除 admin 公司基础信息「分公司名称」字段 - -**日期**: 2026-05-06 18:50 -**通知对象**: @mmg (前端) — **必须移除「分公司名称」字段的展示和表单输入** -**关联 PR**: wx/HL #1728 (squash 4bddc5b2 已合 dev) / Closes #1727 -**关联工单**: #1727 - ---- - -## ⚠️ 一句话摘要 - -**admin 公司详情/编辑/列表接口的响应/请求体不再包含 `companyBranchName` 字段, 小程序 `/mp/agency/primary` 接口同步移除。前端必须删除「分公司名称」展示和表单输入项, 保留会浪费一个无意义字段。** - ---- - -## 一、为什么删 - -| 时间 | 行为 | -|------|------| -| PR #1573 之前 | agency 不传 companyBranchName, 12301 平台接收正常 | -| 2026-04 PR #1573 hotfix | 12301 上报新增 agency.companyBranchName(可选字段) | -| 2026-05-06 PR #1710 | 旅行社公司管理新模块, DB travel_agency 表落 company_branch_name 列 | -| 2026-05-06 用户反馈 | admin 详情页「分公司名称: 海拉尔区营业部」字段不需要在前端单独维护, 业务上由 agency 名称/地址推导 | -| **2026-05-06 PR #1728 (本次)** | **彻底删除字段: DB DROP COLUMN + Entity/VO/DTO/12301 上报全部移除** | - -12301 spec 中 `companyBranchName` 属可选字段, PR #1573 之前一直未传, 平台接受。 - ---- - -## 二、影响接口对照表 (前端必改) - -### 1. admin 端 - 字段被删 - -| Method | 路径 | 旧字段 | 新行为 | -|--------|------|--------|--------| -| GET | `/admin/travel-agency/{agencyId}` | `companyBranchName` | **不再返回此字段** | -| GET | `/admin/travel-agency/page` | `records[*].companyBranchName` | **不再返回此字段** | -| POST | `/admin/travel-agency` | `companyBranchName` (body) | 后端忽略, 不入库 (字段已删) | -| PUT | `/admin/travel-agency/{agencyId}` | `companyBranchName` (body) | 后端忽略, 不入库 (字段已删) | - -> Round-trip 验证: `GET /admin/travel-agency/2051922156798779394` 响应 40 字段, 无 `companyBranchName` ✓ - -### 2. 小程序端 - 字段被删 - -| Method | 路径 | 旧字段 | 新行为 | -|--------|------|--------|--------| -| GET | `/mp/agency/primary` | `companyBranchName` | **不再返回此字段** | - -> Round-trip 验证: `GET /mp/agency/primary` 响应 6 字段 (`code/agencyName/licenseNumber/businessLicenseNumber/complaintPhone/agencyAddress`), 无 `companyBranchName` ✓ - -### 3. 12301 合同上报 - -后端不再上报 `agency.companyBranchName` 节点, 12301 平台接收正常 (与 PR #1573 之前一致)。前端无感知。 - ---- - -## 三、前端改动清单 (mmg) - -| 模块 | 改动 | -|------|------| -| `hl-ui` 公司详情页基础信息 tab | 移除「分公司名称」整行 | -| `hl-ui` 公司编辑/新建表单 | 移除「分公司名称」输入框 + 校验 | -| `hl-ui` 公司列表(若有展示) | 移除该列 | -| `hl-ui` 小程序首页/我的页/客服联系页/分享卡片/协议页落款 | 若有用 `companyBranchName` 显示, 移除 | -| API 类型定义 (`*.d.ts` 或 axios response 类型) | 移除该字段定义 | - -**关键**: 前端 `companyBranchName` 字段可以一次性 grep 全删, 无业务逻辑分支依赖该字段。 - ---- - -## 四、DB 变更 - -```sql --- V20260506_009__drop_company_branch_name.sql -ALTER TABLE travel_agency DROP COLUMN company_branch_name; -``` - -- 测试服: 已通过 Flyway 自动执行 (deploy-panel task `fb0dd936` 18:46 完成滚动部署 8094/8194) -- 正式服: 下一波 release main 走 Flyway 自动执行 - ---- - -## 五、Round-trip 验证记录 - -| 测试 | 路径 | 结果 | -|------|------|------| -| 1 | `GET /admin/travel-agency/2051922156798779394` | ✅ 200, 40 字段, 无 `companyBranchName` | -| 2 | `GET /mp/agency/primary` | ✅ 200, 6 字段, 无 `companyBranchName` | -| 3 | `GET /admin/travel-agency/page?pageNum=1&pageSize=3` | ✅ 200, 3 records, 第一条 40 字段, 无 `companyBranchName` | - -测试服: `https://api.test.1814.love:9443` -admin token: 真实登录 (admin / Admin@123456) -DB: `DESC travel_agency` 已无 `company_branch_name` 列 (Flyway 自动 apply) - ---- - -**有疑问 @ wx, 改动完成请在工单 #1727 留言确认。** diff --git a/changelogs/2026-05/06_fix_gateway_review_filter_tags_public.md b/changelogs/2026-05/06_fix_gateway_review_filter_tags_public.md deleted file mode 100644 index aad6fb6..0000000 --- a/changelogs/2026-05/06_fix_gateway_review_filter_tags_public.md +++ /dev/null @@ -1,55 +0,0 @@ -# fix(gateway): /mp/review/filter-tags 加入网关白名单(应免登录) - -**日期**: 2026-05-06 20:30 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1754 (已 merge dev + 测试服 round-trip 通过) -**关联工单**: wx/HL #1752 - ---- - -## 一、用户反馈 - -`GET https://api.test.1814.love:9443/mp/review/filter-tags` 返回 `{"code":401,"message":"Missing or invalid Authorization header"}`,但该接口是评价列表页顶部筛选栏(全部/有图 + 字典关键词标签),前端用于渲染筛选栏,应免登录。 - -## 二、根因 - -`hl-gateway/src/main/java/com/hulalv/gateway/filter/JwtAuthFilter.java` 评价浏览白名单段已包含同 family 的 target / stats / product/** / search / rating-categories / featured,**漏掉 filter-tags**,导致网关层 401。 - -`MpReviewController.java#getFilterTags` 自身无任何权限要求,卡在网关层。 - -## 三、修复 - -`JwtAuthFilter` 评价浏览段加一行 `/mp/review/filter-tags`。 - -## 四、API 改动 - -无字段变更;仅鉴权策略变更——`/mp/review/filter-tags` 现已免登录。 - -## 五、验收 - -``` -$ curl -k https://api.test.1814.love:9443/mp/review/filter-tags -HTTP 200 -{ - "code": 200, - "message": "成功", - "data": { - "fixedFilters": [ - {"label":"全部","key":"all"}, - {"label":"有图","key":"hasImage"} - ], - "tagFilters": [ - {"key":"QUIET_PRIVATE","label":"安静私密"}, - {"key":"KIDS_LOVE_IT","label":"孩子玩疯了"}, - ... 共 9 个 - ] - }, - "success": true -} -``` - -回归: `/mp/review/featured` 200, `/mp/review/rating-categories` 200; 反向校验 `/mp/review/my` 仍返 401(未误开口子)。 - -## 六、前端建议 - -无需改动。前端可直接调 `GET /mp/review/filter-tags`(无 token)拿到 fixedFilters + tagFilters 渲染评价列表页筛选栏。 diff --git a/changelogs/2026-05/06_fix_insurance_recharge_pay_url.md b/changelogs/2026-05/06_fix_insurance_recharge_pay_url.md deleted file mode 100644 index 9c1a7d7..0000000 --- a/changelogs/2026-05/06_fix_insurance_recharge_pay_url.md +++ /dev/null @@ -1,125 +0,0 @@ -# fix(insurance): 充值接口返回支付链接 (V2 重构丢失修复) - -**日期**: 2026-05-06 18:30 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1725 (已 merge dev + 测试服部署 + round-trip 6/6 通过) -**关联工单**: wx/HL #1724 - ---- - -## 一、用户反馈 - -正式环境 `admin.1814.love/insurance/products`「在线充值」弹窗: -- 输入金额 + 选支付方式(支付宝/微信) -- 点击「确认充值」 -- `POST /admin/insurance/recharge` 返回 `{"code":200,"message":"成功","data":null,"success":true}` -- **没有任何充值页面 / 微信二维码 / 支付宝表单**,流程死在弹窗 - -## 二、根因 - -V2 重构 (PR #663) 把 Controller 返回从 `Result<Map<String,Object>>` 改成 `Result<Void>` 时,Service `recharge()` 一开始就是 `void`,**根本没解析保游网 `/Pay/GetRechargeData` 响应里的支付链接**。`RechargeRequest` DTO 里 `payType + backUrl` 已声明,但 Controller 没传给 Service,Service 内部硬编码 PayType=33。 - -## 三、修复 - -后端改 `recharge` 接口返回支付链接结构体,前端配合改弹码/跳转。 - -| 文件 | 改动 | -|---|---| -| `RechargeRespVO` (新) | 4 字段:payType/payUrl/formHtml/totalFee | -| `AdminInsuranceController.recharge` | `Result<Void>` → `Result<RechargeRespVO>`,透传 DTO 字段 | -| `InsuranceManageService.recharge` | 签名改 `(amount, payType, backUrl, adminId, adminName) → RechargeRespVO`,按 payType 解析保游 `Data` | -| `OrderInsuranceErrorCode` | 加 `RECHARGE_PAY_TYPE_INVALID(540220)` / `RECHARGE_EMPTY_PAY_DATA(540221)` | - -## 四、API 改动 (前端必看) - -### 请求 `POST /admin/insurance/recharge` (字段未变,提醒强校验) - -```json -{ - "money": 100.00, // 必填,0.01 ≤ ≤ 100000 - "payType": 33, // 必填!!! 11=支付宝 / 33=微信 - "backUrl": "https://admin.test.1814.love/insurance/products" // 选填,支付宝跳回地址 -} -``` - -⚠️ **`payType` 现在是后端必填**(DTO `@NotNull`)。旧前端如果没传会返 `code:400 message:"payType: 支付方式不能为空"`,请确认前端选择支付方式后必须把值塞 payload。 - -### 响应 (新增 data 结构) - -**微信扫码 (payType=33)**: -```json -{ - "code": 200, - "message": "成功", - "data": { - "payType": 33, - "payUrl": "weixin://wxpay/bizpayurl?pr=rKqjDdSz3", // ← 微信扫码 URL - "formHtml": null, - "totalFee": "0.01" // 单位元字符串 - }, - "success": true -} -``` - -**支付宝 (payType=11)**: -```json -{ - "code": 200, - "message": "成功", - "data": { - "payType": 11, - "payUrl": null, - "formHtml": "<form id='alipaysubmit' name='alipaysubmit' action='https://mapi.alipay.com/gateway.do?_input_charset=utf-8' method='post'>...<input ... /></form><script>document.forms['alipaysubmit'].submit();</script>", // ← 完整 HTML 表单 - "totalFee": null - }, - "success": true -} -``` - -### 业务错误码 - -| code | message | 触发条件 | -|---|---|---| -| 400 | `money: 充值金额最小0.01元` / `充值金额最大100000元` / `充值金额不能为空` | DTO 校验失败 | -| 400 | `payType: 支付方式不能为空` | DTO `@NotNull` | -| 540220 | 充值支付方式无效, 只支持 11=支付宝 / 33=微信 | payType 不在 (11, 33) | -| 540221 | 保游网未返回支付数据 | 第三方异常 | -| 540210 | 保游网 errorMessage | 保游 isSuccess=false | - -## 五、前端处理建议 - -### 微信扫码 (payType=33) - -`payUrl` 是 `weixin://wxpay/bizpayurl?pr=xxx` 协议链接。**用 qrcode 库本地渲染成二维码图片**贴弹窗里,提示「请用微信扫码完成支付」。扫码后微信会自动唤起支付。 - -```js -// 推荐用 qrcode (npm: qrcode 或 vue-qr) -import QRCode from 'qrcode' -QRCode.toDataURL(resp.data.payUrl, (err, url) => { - qrImage.value = url // <img :src="qrImage" /> -}) -``` - -### 支付宝 (payType=11) - -`formHtml` 是完整 `<form>...</form><script>document.forms['alipaysubmit'].submit();</script>`,**整段塞一个隐藏 div / 临时新窗口**触发自动 submit 跳支付宝网关。 - -```js -// 推荐:开新窗口 document.write 整段写入,自动 submit 跳支付宝 -const w = window.open('', '_blank') -w.document.write(resp.data.formHtml) -// 或者塞当前页隐藏 iframe + iframe.contentDocument.write -``` - -⚠️ formHtml 里包含 `return_url` 字段(后端透传 `backUrl`),用户支付宝付完会跳回该地址。前端建议把 `backUrl` 设为充值页本身,例:`window.location.origin + '/insurance/products'`。 - -## 六、测试服 round-trip 已验证 - -- 微信:`data.payUrl=weixin://wxpay/bizpayurl?pr=rKqjDdSz3` 非空 ✓ -- 支付宝:`data.formHtml=<form id='alipaysubmit' action='https://mapi.alipay.com/gateway.do' ...>` 完整 HTML ✓ -- 反例:payType=99 / money=0 / 缺 payType 全部正确报错 ✓ - -## 七、部署计划 - -- 测试服:已部署 (deploy task `7e8d25cf` success) -- 正式环境:等用户合 dev → main 后通知运维部署 diff --git a/changelogs/2026-05/06_fix_mp_merchant_qualifications_returns_non_primary_list.md b/changelogs/2026-05/06_fix_mp_merchant_qualifications_returns_non_primary_list.md deleted file mode 100644 index 65f576b..0000000 --- a/changelogs/2026-05/06_fix_mp_merchant_qualifications_returns_non_primary_list.md +++ /dev/null @@ -1,116 +0,0 @@ -# fix(mp-common): /mp/common/merchant-qualifications 改返「非主体公司列表+附件」(响应 shape 由 object → array) - -**日期**: 2026-05-06 20:25 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1751 (已 merge dev + 测试服部署 + round-trip 验收通过) -**关联工单**: wx/HL #1746 -**接续/修正**: changelog `06_feat_mp_merchant_qualifications_alias_landed.md` (PR #1745 实现错位) - ---- - -## 一、变更概要 - -`/mp/common/merchant-qualifications` 这个接口的语义和返回结构**全部改了**,**前端逻辑必须配合改**。 - -之前 PR #1745 把它做成 `/mp/agency/primary` 的 alias(返主体单对象)。但用户(产品)的真实意图是: - -> "返回除了主体之外的全部公司,包括资质附件" - -所以 PR #1751 把端点正名: - -| | 旧行为 (PR #1745, 已废) | 新行为 (PR #1751, 当前) | -|---|---|---| -| 数据范围 | 主体单家(hulai) | **除主体外的全部启用公司(N 家)** | -| 响应 shape | `Result<MpAgencyDTO>` (data 是 object) | `Result<List<MpAgencyDTO>>` (data 是 **array**) | -| 与 `/mp/agency/primary` 关系 | 完全等同(alias) | **互补**:primary 取主体,common 取其它 | - -## 二、新响应结构(测试服真实数据) - -```json -{ - "code": 200, "message": "成功", - "data": [ - { - "code": "hulai", - "agencyName": "内蒙古呼籁国际旅行社有限公司", - "licenseNumber": "L-NMG-100953", - "businessLicenseNumber": "91150702MACYFE851R", - "complaintPhone": "12301", - "agencyAddress": "...", - "qualifications": [ - { - "name": "呼籁国际营业执照", - "qualificationType": "BUSINESS_LICENSE", - "qualificationTypeLabel": "营业执照", - "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...", - "fileType": "IMAGE", - "fileTypeLabel": "图片", - "issueDate": null, - "expireDate": null - }, - { ...第二张资质... } - ] - }, - { - "code": "qianshou", - "agencyName": "内蒙古呼籁山河国际旅行社有限公司", - "qualifications": [ ...2 张... ] - }, - { - "code": "hulai-wenlu", - "agencyName": "内蒙古呼籁文旅投资开发有限公司", - "qualifications": [] - } - ] -} -``` - -每个数组元素的字段与之前 `/mp/agency/primary` 单对象的字段**完全相同**,只是从 1 个变成 N 个。 - -## 三、前端必须改的点 - -### 1. 解析逻辑 - -```js -// 旧 (data 是 object) -const company = res.data; -this.agencyName = company.agencyName; -this.qualifications = company.qualifications; - -// 新 (data 是数组) -const companies = res.data; -companies.forEach(c => { - // 每家公司一行/一卡片渲染 -}); -``` - -### 2. UI 展示 - -按你们的页面设计渲染:每家公司一个区块,含公司名/许可证号/营业执照号/投诉电话/地址 + qualifications 数组(资质附件)。`qualifications: []` 的公司不展示资质区块。 - -### 3. 主体公司另外取 - -如果页面同时要展示主体公司,继续调 `GET /mp/agency/primary`(返单对象,字段一致)。两个接口配合: - -| 接口 | 内容 | -|---|---| -| `GET /mp/agency/primary` | **主体公司**(单对象) | -| `GET /mp/common/merchant-qualifications` | **非主体的合作公司**(数组,本 PR 修正) | - -## 四、兼容性说明 - -PR #1745 今天刚合,前端代码假设是 list(因为 url 是复数 qualifications),所以这次改回 list **匹配前端真实诉求**。如果前端已经按 PR #1745 的 object shape 改过解析逻辑,需要回退到 list 解析。 - -## 五、测试服已可用 - -``` -GET https://api.test.1814.love:9443/mp/common/merchant-qualifications -→ HTTP 200, data.length = 3 (hulai/qianshou/hulai-wenlu),不含主体 kj -``` - -合 main 暂不做(随后续 release 一起上)。 - -## 六、其他 - -- 工单 wx/HL #1746 已关闭 -- @MpCache deps 不变(`table:travel_agency` + `table:travel_agency_qualification`),写公司或资质时缓存自动失效 diff --git a/changelogs/2026-05/06_fix_mp_merchant_qualifications_visible_filter.md b/changelogs/2026-05/06_fix_mp_merchant_qualifications_visible_filter.md deleted file mode 100644 index 8a50da2..0000000 --- a/changelogs/2026-05/06_fix_mp_merchant_qualifications_visible_filter.md +++ /dev/null @@ -1,40 +0,0 @@ -# 修复 /mp/common/merchant-qualifications 不按 visible 字段过滤 - -**类型**: BUG 修复(后端单点) -**前端处理者**: mmg(无前端动作, 后端透明修复) -**日期**: 2026-05-06 -**关联**: 工单 #1758 / PR #1760 - ---- - -## 现象 - -管理端「编辑旅行社」弹窗里把「是否在小程序展示」开关关闭(visible=0)后, 小程序 `GET /mp/common/merchant-qualifications` 仍返回该公司, 与开关语义不符。 - -## 根因 - -`TravelAgencyMapper.selectNonPrimaryEnabled()`(PR #1751 引入)只过滤 `status=ENABLED + 非主体`, 漏过 `visible=1`。 - -PR #1756 (Closes #1749) 后加 `agency.visible` 字段时未回头给本 mp 接口加过滤。 - -## 修复 - -`TravelAgencyMapper.selectNonPrimaryEnabled()` 加 `.eq(visible, 1)` 一行。 - -新增 `TravelAgencyMapperTest` 防回归: 用 `MockitoExtension + TableInfoHelper.initTableInfo` 模板, 断言 wrapper SQL 含 status/visible/is_primary 三个条件 + visible 用 `=` 比较 + paramNameValuePairs 值集合含 ENABLED/1/0。 - -## 影响 / 不影响 - -| 接口 | 是否受影响 | -|------|-----------| -| `/mp/common/merchant-qualifications` | ✅ 修复(只返 visible=1 的非主体公司) | -| `/mp/agency/primary` | ❌ 主体单独路径, 不在此修复范围 | -| admin 列表/详情、Feign `internal/agency/{id}` 等 | ❌ 不受影响 | - -## 缓存 - -`MpCommonController.merchantQualifications` 已声明 `@MpCache(deps={"table:travel_agency", "table:travel_agency_qualification"})`, admin update 走 `afterCommitAuditAndCacheBust` invalidate `table:travel_agency`, 配置已正确。 - -## 前端无需改动 - -接口 URL/响应结构无变化, 仅过滤行为变严, 之前隐藏的公司本来就不应出现在小程序合作商家页, 修复后符合预期。 diff --git a/changelogs/2026-05/06_fix_mp_product_detail_agency_resp.md b/changelogs/2026-05/06_fix_mp_product_detail_agency_resp.md deleted file mode 100644 index 6e00340..0000000 --- a/changelogs/2026-05/06_fix_mp_product_detail_agency_resp.md +++ /dev/null @@ -1,83 +0,0 @@ -# fix(mp-product): /mp/product/{id} 详情接口回显 agencyId + agencyName - -**日期**: 2026-05-06 20:30 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1753 (已 merge dev,等测试服部署后 round-trip) -**关联工单**: wx/HL #1748 - ---- - -## 一、用户反馈 - -小程序产品详情页希望展示「出团旅行社」公司信息,但 `GET /mp/product/{id}` 返回的 50+ 字段里没有任何 agency/公司字段,前端无法展示。 - -## 二、根因 - -PR #1707 已在 `product` 表加 `agency_id` 字段 (NOT NULL,Flyway 回填 hulai 主体)。 -PR #1722 给 admin 详情接口补了 agencyId/agencyName,但 **mp 端 `MpProductDetailAssembler` 完全未补 agency 字段**;快照路径 `MpProductSnapshotService` 同样未处理。 - -## 三、修复 - -| 文件 | 改动 | -|---|---| -| `MpProductDetailRespVO` | 顶层加 `agencyId: Long` + `agencyName: String` | -| `MpProductDetailAssembler` (实时路径) | 注入 `AgencyFeignClient`,显式 `setAgencyId(product.getAgencyId())` + Feign 调 order-v2 拿 `agencyName` (异常 catch 不阻断主流程) | -| `MpProductSnapshotService.fillAgency` (快照路径) | `productHelperService.selectById(productId).getAgencyId()` + Feign 取 agencyName。**agency 不冻结进快照**,公司主体保持当前真值 (与 refundPolicy 同样语义) | -| 单测 | 新增 5 例覆盖实时/快照 + Feign 成功/异常/agencyId=null 各种分支 | - -## 四、API 改动 - -### 4.1 实时路径 `GET /mp/product/{id}` - -```json -{ - "code": 200, - "data": { - "productId": 2043595351268519937, - "name": "草原环线 5 日", - "agencyId": 2051922156798779394, // ← 新增 - "agencyName": "内蒙古呼籁国际旅行社有限公司", // ← 新增, Feign 拿中文 - "productType": "CORE", - ... - } -} -``` - -### 4.2 快照路径 `GET /mp/product/{id}?orderId=X` - -同样返 `agencyId` + `agencyName`,但**不冻结进订单产品快照** (订单内的产品 snapshot JSON 仍不含这俩字段),公司主体永远取实时值。 - -## 五、前端建议 - -详情页直接读 `data.agencyName` 展示「出团旅行社: 内蒙古呼籁国际旅行社有限公司」即可。 -若想做点击跳转旅行社详情页,可用 `data.agencyId` 拼接路径。 - -Feign 极少数失败场景下 `agencyName` 可能为 null,前端建议加 placeholder 兜底: - -```vue -<span>出团旅行社: {{ detail.agencyName || '呼籁旅行' }}</span> -``` - -## 六、测试服 round-trip 验证 (待 dev 部署后补) - -部署完成后调用: - -```bash -curl -sk "https://api.test.1814.love:9443/mp/product/2043595351268519937" \ - | python -c " -import json,sys -d = json.load(sys.stdin)['data'] -print(f'agencyId = {d.get(\"agencyId\")}') -print(f'agencyName = {d.get(\"agencyName\")}') -" -# 预期: agencyId 非 null Long, agencyName 非 null 中文 -``` - -## 七、关联 PR - -- PR #1722 (admin 端产品详情 agency 回显, 已合并) -- **PR #1753 (本 PR, mp 端产品详情 agency 回显)** - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_fix_mp_review_report_bff_passthrough.md b/changelogs/2026-05/06_fix_mp_review_report_bff_passthrough.md deleted file mode 100644 index d802481..0000000 --- a/changelogs/2026-05/06_fix_mp_review_report_bff_passthrough.md +++ /dev/null @@ -1,75 +0,0 @@ -# fix(mp-service): 补 BFF 端 POST /mp/review/report 透传 - -**日期**: 2026-05-06 20:35 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1757 (已 merge dev,等测试服自动部署后 round-trip) -**关联工单**: wx/HL #1755 - ---- - -## 一、用户反馈 - -`POST https://api.test.1814.love:9443/mp/review/report` 返回: - -```json -{"code":404,"message":"接口不存在: POST /mp/review/report"} -``` - -之前我已告知前端"举报评价接口可用",基于 `hl-order-service-v2` 的 `InternalMpReviewController#report` 已实现 + 字典 review_report_reason 已补回(PR #1739)的事实判断,**漏检 BFF 透传那一段**,实际接口未对外暴露。本次修复后真正可用,致歉。 - -## 二、根因 - -工单 #1662 Phase 2B 完成的范围只到 order-v2 内部端点 + Service + 字典 + 单测,**漏写 hl-mp-service 这层 BFF**: - -- `MpReviewController` 没暴露 `POST /mp/review/report` -- `MpReviewFeignClient` 没对应 `report` 方法 -- `MpReviewFeignFallbackFactory` 没兜底实现 - -→ 前端调测试服 endpoint, 网关路由到 mp-service, 没匹配 controller, 返 404 "接口不存在"。 - -跟 PR #1754 (Closes #1752, `/mp/review/filter-tags` 网关白名单) 是同根因 —— Phase 2B BFF 收尾遗漏。 - -## 三、修复 - -`hl-mp-service` 模块加 4 处: - -1. 新建 `dto/MpReviewReportRequest.java` (BFF 入参 DTO, 字段与 order-v2 `ReviewReportReqVO` 一致) -2. `MpReviewFeignClient.report(MpReviewReportRequest, X-User-Id)` 方法 -3. `MpReviewFeignFallbackFactory.report` 兜底实现 -4. `MpReviewController POST /report` 端点, 透传 userId 到 Feign - -## 四、API 字段 - -`POST /mp/review/report` (需登录, 网关 JwtAuthFilter 默认拦截): - -| 字段 | 类型 | 必填 | 限制 | 说明 | -|------|------|------|------|------| -| `reviewId` | String(雪花 Long, 双向 String 防精度丢失) | ✅ | - | 评价 ID | -| `reason` | String | ✅ | max 32 | 字典 `review_report_reason`: SPAM / INSULT / PORN / POLITICS / FAKE / LEAK_PRIVACY / OTHER | -| `detail` | String | - | max 500 | 补充说明 | - -返回: `{"code":200,"message":"成功","data":null,"success":true}` - -幂等: 同一用户对同一评价重复举报触发 `uk_review_reporter` 唯一索引返业务错误(无需前端处理, BFF 不加 `@Idempotent`)。 - -## 五、前端建议 - -举报弹窗前端调用示例: - -```js -http.post('/mp/review/report', { - reviewId: review.id, // 字符串透传, 不要 Number(...) - reason: 'SPAM', // 用字典 review_report_reason 的 dictValue - detail: userInputOrEmpty, // 可选, max 500 -}) -``` - -字典拉取走现有 `GET /mp/dict/review_report_reason`(已在 PR #1739 补回), 渲染下拉选项。 - -## 六、验收(待测试服部署) - -- [ ] 真 mp token round-trip: `POST /mp/review/report` body `{"reviewId":"<真实评价ID>","reason":"SPAM","detail":"测试"}` 返 `{"code":200}` -- [ ] 重复举报触发唯一索引返业务错误 -- [ ] 不带 token 调用返 401 (网关拦截) -- [ ] 超长 reason(>32) / detail(>500) 返参数校验错误 -- [ ] 部署后 INFO 日志含 `submitted` 落库 diff --git a/changelogs/2026-05/06_fix_product_detail_agency_resp.md b/changelogs/2026-05/06_fix_product_detail_agency_resp.md deleted file mode 100644 index 557a33d..0000000 --- a/changelogs/2026-05/06_fix_product_detail_agency_resp.md +++ /dev/null @@ -1,87 +0,0 @@ -# fix(product): 产品详情接口回显 agencyId + agencyName - -**日期**: 2026-05-06 17:45 -**通知对象**: @mmg (前端) -**关联 PR**: wx/HL #1722 (已 merge dev + 测试服部署 + round-trip 通过) - ---- - -## 一、用户反馈 - -产品编辑页「所属公司」字段下拉选中保存后,**重新打开编辑页不回显**,看起来像「保存不上」。 - -## 二、根因 - -DB `product` 表 `agency_id` 字段已**正确保存**(SQL 直查 `product_id=2045018534152478721 → agency_id=2051922156798779394 hulai`)。 - -但 `ProductDetailRespVO` **没有 agencyId / agencyName 字段** → `BeanUtil.toBean(product, vo)` 复制不到 → 前端 GET 拿到 50+ 字段 response 但**无 agencyId** → 前端下拉绑不上。 - -## 三、修复 - -| 文件 | 改动 | -|---|---| -| `ProductDetailRespVO` | 加 `agencyId: Long` + `agencyName: String` | -| `ProductQueryService.getProductDetail` | 显式 `setAgencyId(product.getAgencyId())` (BeanUtil 兜底防跨 BaseDO null 覆盖); Feign 调 order-v2 拿 `agencyName` 中文 (失败 log.warn 不阻断) | -| `AgencyFeignClient` (新) | product-v2 → order-v2 `/internal/agency/{id}` | -| `AgencyDTO` (新) | 简版 4 字段 (agencyId/code/agencyName/isPrimary), 不与 order-v2 AgencyInternalDTO 强耦合 | - -## 四、API 改动 - -`GET /admin/product/item/{id}` 响应新增 2 字段: - -```json -{ - "code": 200, - "data": { - "productId": 2045018534152478721, - "name": "游牧的森林·南线经典", - "agencyId": 2051922156798779394, // ← 新增, 编辑页下拉绑定值 - "agencyName": "内蒙古呼籁国际旅行社有限公司", // ← 新增, 中文回显 (Feign 拿) - "productType": "CORE", - ... - } -} -``` - -## 五、前端建议 - -编辑页打开后, 直接绑定: - -```vue -<NSelect - v-model:value="form.agencyId" <!-- 后端返 agencyId 自动选中 --> - :options="agencyOptions" - :placeholder="form.agencyName || '请选择所属公司'" -/> -``` - -下拉选项仍调 `GET /admin/travel-agency/enabled` 拿全部启用公司, 编辑页打开时 `form.agencyId` 自动绑定后端返的 id, 下拉自动选中对应项。 - -## 六、测试服 round-trip 验证 (2026-05-06 17:45) - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -curl -sk "https://api.test.1814.love:9443/admin/product/item/2045018534152478721" \ - -H "Authorization: Bearer $TOK" | python -c " -import json,sys -d = json.load(sys.stdin)['data'] -print(f'agencyId = {d[\"agencyId\"]}') -print(f'agencyName = {d[\"agencyName\"]}') -" -# agencyId = 2051922156798779394 -# agencyName = 内蒙古呼籁国际旅行社有限公司 -``` - -## 七、关联 - -agency 模块 PR 清单: -- #1715 / #1717 / #1718 / #1719 / #1720 / #1721 (公司模块完整闭合) -- **#1722 (本 PR — 产品详情回显)** - ---- - -cc @mmg diff --git a/changelogs/2026-05/06_fix_review_report_queue_hide_restore_disappear.md b/changelogs/2026-05/06_fix_review_report_queue_hide_restore_disappear.md deleted file mode 100644 index 349af4b..0000000 --- a/changelogs/2026-05/06_fix_review_report_queue_hide_restore_disappear.md +++ /dev/null @@ -1,70 +0,0 @@ -# fix(review-report): admin hide/restore 后评价从举报队列永久消失 - -**PR**: [#1766](https://git.1814.love:8443/wx/HL/pulls/1766) **Issue**: [#1765](https://git.1814.love:8443/wx/HL/issues/1765) **合并**: 2026-05-06 - -通知对象: @mmg(前端配合) - ---- - -## 后端修了什么 - -@mmg 之前接入 `/admin/review/report-queue/*` 5 个 API 后,你做了状态机判断: -- `reportStatus === 'PENDING_REVIEW'` 显示「隐藏」 -- `reportStatus === 'HIDDEN'` 显示「恢复」 -- `reportStatus !== 'HIDDEN'` 显示「警告作者/忽略全部」 - -但 admin 实际操作 hide 或 restore 后, **评价从队列永久消失**(用户截图反馈"操作菜单只有警告/忽略,没有禁止展示")。 - -排查发现 2 个后端 BUG: - -1. `OrderReviewMapper.selectReportQueuePage` 硬过滤 `report_count >= 1` → reportCount=0 的 HIDDEN 数据查不到 -2. `AdminReviewReportService.restore` 强制把 reportCount 清成 0 → 配合 #1 让数据彻底消失 - -PR #1766 修了: -- 不传 status 时改用并集 `report_count >= 1 OR reportStatus IN(PENDING_REVIEW, HIDDEN)` -- restore 用 `originalCount` 替代 0, 保留历史举报数 - -## 前端要改的(配合 v4 changelog) - -后端修完 + 部署测试服后, 仍需 mmg 把 v4 状态机调整执行下: - -**修改 `src/views/review/report-queue/index.vue:347` 状态机** - -把: -```js -if (row.reportStatus === 'PENDING_REVIEW') { - primary.push({ text: '隐藏', ... }) -} -``` - -改成: -```js -if (row.reportStatus !== 'HIDDEN') { - primary.push({ text: '禁止展示', ... }) // NORMAL/PENDING_REVIEW 都显示 -} -``` - -`HIDDEN` 时只显示「恢复展示」,这部分代码已经对了(line 355),不用动。 - -## 测试服 round-trip 验收 - -``` -A. 起点 reviewId=2048001001001001005 reportCount=1 NORMAL → 默认查询 total=1 ✓ -B. hide → 显式 HIDDEN tab total=1, reportCount 保留 1, hiddenAt=2026-05-06 21:58:15 ✓ (BUG#1 fix) -C. restore → DB 实测 reportCount=1 (不再被清成 0) ✓ (BUG#2 fix) -D. restore 后默认查询 total=1, 数据仍可见 ✓ -``` - -## 已知 follow-up (不影响主流程) - -显式 `reportStatus=NORMAL` 时后端会返整个评价表(测试服 271 条), 是个待修小 BUG 我会另起 PR。**前端 UI 默认是不传 status 的并集查询, 不受影响**。如果你想加"待复审/已隐藏/正常" 3 个 tab 切换, 等 follow-up 合了再做。 - -## 字段/接口签名 0 改动 - -无 VO 改动, 无新接口, 现有 5 个 API 路径全部保持。前端只需改状态机判断条件 + 改按钮文案为「禁止展示/恢复展示」即可。 - -## 测试 - -- 单测 39/39 (Mapper 28 + Service 11) -- CR PASS-WITH-NITS, P1 三处已修 -- 测试服双实例 8094+8194 滚动部署成功 diff --git a/changelogs/2026-05/06_fix_user_2fa_default_enabled.md b/changelogs/2026-05/06_fix_user_2fa_default_enabled.md deleted file mode 100644 index d38bdf2..0000000 --- a/changelogs/2026-05/06_fix_user_2fa_default_enabled.md +++ /dev/null @@ -1,109 +0,0 @@ -# 修管理后台登录 2FA 设备验证失效 (P0 安全降级) - -**日期**: 2026-05-06 -**类型**: fix (P0 安全降级,后端配置默认值修复,无前端影响) -**PR**: wx/HL #1699 (已合并 dev,等运维/用户合 main 部署正式) -**关联工单**: #1698 -**引入**: 2026-04-03 PR #144 (commit 538635e) - -## 问题 - -切换电脑/浏览器登录管理后台,**应该**触发企业微信扫码 2 次验证 (设备指纹+企微 2FA);**实际**任何账号(不只内置 admin)直接账号密码即可登录,2FA 完全失效。 - -影响 dev/test/prod 全环境近一个月。 - -## 根因 - -`hl-user-service/src/main/resources/application.yml:69-70`: - -```yaml -auth: - 2fa: - enabled: false # ← 默认关 -``` - -`AdminAuthService.java:155` 跳过判断: - -```java -if ("admin".equals(admin.getUsername()) || !twoFactorEnabled) { - // 直接发 token,跳过设备指纹比对+企微 2FA 流程 -} -``` - -`!twoFactorEnabled` = `!false` = `true` → 任何账号都跳过。 - -Nacos dev/test/prod 三套 `hl-user-service-{env}.yml` 均**未覆写** `auth.2fa.enabled`,全部吃 application.yml 默认值。 - -## 引入溯源 - -PR #144 (2026-04-03 commit `538635e`) "代码安全审计修复(8项)": - -> CRITICAL: 2FA跳过改为显式配置(auth.2fa.enabled),移除环境名判断 - -意图把"用环境名判 dev 跳过"换成"用配置开关",**默认值意外写反** —— 安全修复想让默认 ON,实际写成 OFF。 - -## 修复 - -| 文件 | 改动 | -|------|------| -| `hl-user-service/src/main/resources/application.yml` | `enabled: false → true` + 注释说明 | -| `nacos-config/hl-user-service-dev.yml` | 显式覆写 `auth.2fa.enabled: true` 防回归 | -| `hl-user-service/.../config/Auth2faDefaultEnabledAuditTest.java` | 新增守护单测,防 PR #144 类反转再发 | - -内置 `admin` 账号在 line 155 第一条件 `"admin".equals(username)` 不变,仍跳过 2FA 避免 super-admin 锁死。 - -## 影响范围 - -- **受波及账号**: 所有非内置 admin 的管理员 (即所有真实业务账号) -- **数据污染**: 无 (仅认证流程降级,未污染数据) -- **回滚**: `git revert` 1 commit - -## 验证 - -### 单测 -- `mvn test -Dtest=AdminAuthServiceTest` → 58/58 全绿 (含已有的 `login_untrustedDevice_requires2FA` / `login_trustedDevice_issuesToken` / `login_superAdmin_skips2FA_issuesTokenDirectly`) -- `mvn test -Dtest=Auth2faDefaultEnabledAuditTest` → 1/1 (反向验证: 改回 false 立即报 `expected: <true> but was: <false>`) - -### 测试服 round-trip (dev 部署后) - -```bash -# 期望 1: 非 admin 账号新设备登录 → requireTwoFa=true && token=null -curl -k -X POST 'https://api.test.1814.love:9443/admin/auth/login' \ - -H 'Content-Type: application/json' \ - -H 'X-Device-Fingerprint: NEW_DEVICE_TEST' \ - -d '{"username":"<非admin账号>","password":"<密码>"}' -# 期望: {"code":"200","data":{"requireTwoFa":true,"token":null,...}} - -# 期望 2: 内置 admin 仍跳过 2FA -curl -k -X POST 'https://api.test.1814.love:9443/admin/auth/login' \ - -H 'Content-Type: application/json' \ - -d '{"username":"admin","password":"Admin@123456"}' -# 期望: {"code":"200","data":{"token":"eyJ...",...}} (token 直接发) - -# 期望 3: 已信任设备直发 token (admin_device.is_trusted=true) -# 期望 4: 换浏览器 (不同 fingerprint) → admin_device 不命中 → requireTwoFa=true -``` - -## 部署计划 - -- ✅ dev 测试服: 自动部署 (PR 合并触发) -- ⏳ prod: 用户手动合 dev → main 后,运维/管理员通过 [Deploy Panel](https://dep.test.1814.love:9443) 触发 hl-user-service prod 部署。**仅 application.yml 改动,nacos prod 无需推送**(prod nacos 未覆写,jar 内默认值 true 立即生效)。 -- 如需 prod nacos 也加显式覆写防回归,在 `正式环境Nacos配置/hl-user-service-prod.yml` 已落本地参考,运维同步推 nacos prod 即可。 - -## 经验沉淀 - -落 `memory/experience/backend-dev/yml-default-value-must-be-secure-by-default.md` — -**配置默认值反转规则**: 任何"启用/禁用"类配置 (`enabled`/`required`/`strict`/`validate`),默认值必须取**安全/严格**那一侧: -- `auth.2fa.enabled` 默认 `true` (开启) -- `validate-on-migrate` 默认 `true` (校验) -- `strict-mode` 默认 `true` (严格) -- `cors.allow-all-origins` 默认 `false` (拒绝) - -把不安全/松散值留给 nacos 显式覆写,**绝不让 application.yml 默认值成为安全降级源**。 - -防回归手段: 给关键 `enabled: true` 配置写 `*DefaultEnabledAuditTest` 守护测试,任何回退立即编译期/单测期阻断。 - -## 通知 - -- 后端独立修复,无前端改动需求 (mmg/yst 不用动) -- 用户/运维: 部署 prod 后请告知,以便 round-trip 4 个验证场景闭环 + 关闭工单 #1698 diff --git a/changelogs/2026-05/06_fix_user_review_report_reason_dict.md b/changelogs/2026-05/06_fix_user_review_report_reason_dict.md deleted file mode 100644 index 6d03b67..0000000 --- a/changelogs/2026-05/06_fix_user_review_report_reason_dict.md +++ /dev/null @@ -1,82 +0,0 @@ -# 补回 review_report_reason 字典 (Flyway baseline 屏蔽 V007 漏空) - -**日期**: 2026-05-06 -**类型**: fix (后端 DB 字典补漏,无代码改动,无前端影响) -**PR**: wx/HL #1739 (已合并 dev) -**关联工单**: 无独立工单 (历史漏空,前端反馈"测试服 review_report_reason 字典没有"后直接修) -**引入**: 三 PR 叠加 — #1667 + #1681 + #1684 - -## 问题 - -测试服评价举报原因字典 `review_report_reason` 缺失,前端举报弹窗下拉框拉空(或显示英文 enum value 像乱码)。 - -实测证据(测试服 admin token round-trip): -- `/admin/dict/all` 返回 156 条字典类型,**不含** `review_report_reason` -- `/admin/dict/type/10080` 返 `code=404, 字典类型不存在` -- `/admin/dict/data/review_report_reason` 返 `code=200, data=[]` - -## 根因(三 PR 叠加导致永久漏空) - -| PR | 动作 | -|---|---| -| #1667 (wx-security Phase 2B) | 加入 `V20260505_007__init_review_report_reason_dict.sql` 字典初始化 SQL | -| #1681 (oneshot 补漏) | 手工跑 V001/V002/V004/V008/V009 V*.sql,**oneshot 文件第 16 行注释明确跳过 V007**(`V007 init_review_report_reason_dict (sys_dict_data INSERT, 评估后再决定)`) | -| #1684 (Flyway 阶段 2) | `application.yml` 设 `baseline-version: 20260505.009` + `baseline-on-migrate: true`,首次启动写 baseline,**所有 ≤ baseline 的 V*.sql 永远不会被 Flyway 自动 apply**,包括 V20260505_007 | - -净结果:V20260505_007 既没被 oneshot 手工跑,也被 Flyway baseline 屏蔽自动 apply,字典数据从未落库。 - -## 修复 - -新增 `V20260507_001__init_review_report_reason_dict.sql`(版本号 > baseline 20260505.009 → Flyway 自动 apply)。 - -| 项 | 取值 | -|---|---| -| `dict_type_id` | 10080(V007 原计划占用,测试服 type/10080 返 404 已确认空闲) | -| `dict_data_id` | 100801~100807(7 条) | -| 幂等 | `INSERT IGNORE` — prod 若曾手工跑过 V007 则静默跳过不抛错 | - -字典值集与代码 `ReviewReportReason.ALLOWED` 严格一致:`SPAM`/`INSULT`/`PORN`/`POLITICS`/`FAKE`/`LEAK_PRIVACY`/`OTHER`。 - -## 影响范围 - -- **后端**: hl-user-service 一服务部署即生效 -- **前端**: 无代码改动需求 — mmg/yst 不用动 -- **数据**: 仅 `sys_dict_type` 加 1 条 + `sys_dict_data` 加 7 条 -- **回滚**: 删除 sys_dict_type/sys_dict_data 对应行 + 删 flyway_schema_history 中 V20260507_001 行 - -## 验证 - -### 测试服 round-trip(dev 部署后) - -```bash -# 期望: data 含 7 条字典数据 -curl -sk -H "Authorization: Bearer <admin-token>" \ - "https://api.test.1814.love:9443/admin/dict/data/review_report_reason" -# 期望返回: {"code":200,"data":[{"dictValue":"SPAM","dictLabel":"广告/营销",...}, ...7 条]} -``` - -### Redis 缓存清理(必要) - -直接 SQL INSERT 字典不会触发应用层 D3 反向索引 invalidate,user-service 部署完成后需清三件: - -```bash -redis-cli -n 0 DEL cache:dict:data:list -redis-cli -n 0 DEL cache:dict:data:by-type -redis-cli -n 0 DEL "cache:dict:data:review_report_reason" -``` - -## 部署计划 - -- ✅ dev 测试服: PR 合并后自动部署(本 changelog 写时正在 deploy panel 部署中) -- ⏳ prod: 用户手动合 dev → main 后,通过 Deploy Panel 触发 hl-user-service prod 部署。Flyway 会自动 apply V20260507_001;若 prod 此前已手工跑过 V007,`INSERT IGNORE` 兜底跳过 - -## 经验沉淀 - -落 `memory/experience/backend-dev/flyway-baseline-version-permanently-skips-old-v-sql.md`(若不存在则新建): - -**Flyway baseline-version 永久屏蔽 ≤ baseline 的 V*.sql**:接入 Flyway 时 baseline 写哪个版本,就意味着该版本 + 之前的 V*.sql 即使在 migration 目录里也永远不会被自动 apply。**接入 Flyway 前必须确认 baseline 之前的 V*.sql 在 prod/test 是否真的全部跑过**,任何一条漏跑就要么先补跑,要么发新版本号 > baseline 的 V*.sql 重做(本次踩坑)。 - -## 通知 - -- mmg(前端): 测试服部署 + 缓存清理后,举报弹窗下拉框应显 7 项中文(广告/营销、辱骂/人身攻击 等),不再空/英文 -- 用户: 部署完成 + round-trip 验收通过后告知,可挂 prod 部署 diff --git a/changelogs/2026-05/06_frontend_notice_review_report_queue_action_buttons.md b/changelogs/2026-05/06_frontend_notice_review_report_queue_action_buttons.md deleted file mode 100644 index c5a6424..0000000 --- a/changelogs/2026-05/06_frontend_notice_review_report_queue_action_buttons.md +++ /dev/null @@ -1,69 +0,0 @@ -# 前端补丁: 评价举报队列「操作」菜单加「禁止展示」按钮 - -@mmg —— - -字段你都修对了 👍 (评价内容/作者/关联产品/举报数/举报状态"正常"/举报原因统计"广告/营销 1"/创建时间 全部到位)。 - -**只剩一处要改:操作菜单。** - ---- - -## 问题 - -当前操作菜单只有「忽略举报」「警告作者」,**缺「禁止展示」**。 - -用户原话: "起码得有个禁止展示吧"。 - ---- - -## 修正后的操作按钮规则 - -**只看一个字段判断: `reportStatus`** - -| `reportStatus` | 中文显示 | 操作菜单显示这些按钮 | -|---|---|---| -| `NORMAL` | 正常 | **禁止展示**(主) / 警告作者 / 忽略举报 | -| `PENDING_REVIEW` | 待复审 | **禁止展示**(主) / 警告作者 / 忽略举报 | -| `HIDDEN` | 已隐藏 | **恢复展示**(主) | - -> 简单说: **没隐藏就能"禁止展示", 已隐藏就能"恢复展示"**。 -> 不要按状态决定要不要显示"禁止展示"按钮——管理员看到举报队列就该能立刻禁止。 - ---- - -## 接口对应 - -| 按钮文案 | 接口调用 | -|---|---| -| **禁止展示** | `POST /admin/review/report-queue/${reviewId}/hide` body `{ reason: '违规广告' }`(弹框让 admin 输 reason 必填) | -| **恢复展示** | `POST /admin/review/report-queue/${reviewId}/restore` | -| 警告作者 | `POST /admin/review/report-queue/${reviewId}/warn-author` | -| 忽略举报 | 循环行内 `reporters[]` 调 `POST /admin/review/report-queue/report/${reportId}/ignore` | - -操作完都刷新当前页列表。 - ---- - -## 验收 - -- [ ] 截图那条 `reviewId=2048001001001001005` 状态"正常"的数据,操作菜单点开有 **禁止展示 / 警告作者 / 忽略举报** 3 项 -- [ ] 点"禁止展示"弹输入框输 reason → 提交 → 列表刷新 → 该行状态变"已隐藏" -- [ ] 已隐藏的行,操作菜单只有 **恢复展示** 1 项 -- [ ] 点"恢复展示" → 列表刷新 → 该行状态回"正常" - ---- - -## 不用动的 - -- 字段映射(已对) ✓ -- 表头(已对) ✓ -- 状态翻译"正常/待复审/已隐藏" ✓ -- 列表排序、分页 ✓ - -只改操作菜单条目和点击逻辑。 - ---- - -## 顺带说明 - -我之前 v3 changelog 写的状态机太严了(NORMAL 不显示禁止展示, 只 PENDING_REVIEW 显示),现在统一改成"只要不是 HIDDEN 就能禁止展示"。以这版为准。 diff --git a/changelogs/2026-05/06_frontend_notice_review_report_queue_pending.md b/changelogs/2026-05/06_frontend_notice_review_report_queue_pending.md deleted file mode 100644 index 4f65813..0000000 --- a/changelogs/2026-05/06_frontend_notice_review_report_queue_pending.md +++ /dev/null @@ -1,266 +0,0 @@ -# 前端任务: 「人工复审队列」加一个 tab 显示评价举报 - -@mmg —— **此文件已是第 3 版,前两版你说看不懂,这版尽量直白。如果还有不清楚的当面问我。** - ---- - -## 一句话需求 - -「内容安全 → 人工复审队列」页面 **顶部加一个 tab 叫"评价举报"**,切到这个 tab 就调下面的接口,数据展示出来,操作按钮按下面的规则做。**只改这一个页面,不要新建别的菜单。** - ---- - -## 改之前 vs 改之后 - -### 现在的页面 - -``` -┌─────────────────────────────────────────┐ -│ 人工复审队列 │ -├─────────────────────────────────────────┤ -│ [出行人姓名] [用户昵称] [用户头像] │ ← 这是当前已有的 tab -├─────────────────────────────────────────┤ -│ 列表(调 /admin/wx-security/manual-review/page) │ -└─────────────────────────────────────────┘ -``` - -### 改成这样 - -``` -┌─────────────────────────────────────────────────────┐ -│ 人工复审队列 │ -├─────────────────────────────────────────────────────┤ -│ [出行人姓名] [用户昵称] [用户头像] [评价举报] │ ← 加一个新 tab -├─────────────────────────────────────────────────────┤ -│ 切到"评价举报"时: │ -│ - 列表调 /admin/review/report-queue/page │ -│ - 操作按钮换成 隐藏/恢复/警告作者/忽略 │ -└─────────────────────────────────────────────────────┘ -``` - -前 3 个 tab 你不用动,保持现状。**只加第 4 个 tab + 这个 tab 内的逻辑。** - ---- - -## tab=评价举报 时调什么接口 - -### 1. 加载列表 - -```js -// GET 请求 -axios.get('/admin/review/report-queue/page', { - params: { - page: 1, - pageSize: 20, - reportStatus: 'PENDING_REVIEW', // 可选: NORMAL / PENDING_REVIEW / HIDDEN - keyword: '违规' // 可选: 模糊搜评价内容/作者昵称 - } -}) -``` - -### 响应实例(测试服真数据,reviewId=2048001001001001005 的那条举报) - -```json -{ - "code": 200, - "data": { - "total": 1, - "page": 1, - "pageSize": 20, - "records": [ - { - "reviewId": "2048001001001001005", - "content": "出发前一直犹豫值不值得去……(评价正文)", - "userNickname": "罗子昂", - "userId": "2031234567890123456", - "productName": "粉色风蚀古堡", - "status": "PUBLISHED", - "reportCount": 1, - "reportStatus": "NORMAL", - "hiddenAt": null, - "hiddenReason": null, - "createTime": "2026-05-05 14:23:11", - "reasonStats": { "SPAM": 1 }, - "reporters": [ - { - "reportId": "2052007674911895553", - "reporterUserId": "2031999888777666555", - "reporterOpenid": "oK****n8", - "reason": "SPAM", - "detail": null, - "status": "PENDING", - "createTime": "2026-05-06 20:25:42" - } - ] - } - ] - } -} -``` - -**注意**: `reviewId / userId / reporterUserId / reportId` 都是字符串(后端用 `@JsonFormat(shape=STRING)` 防 JS 精度丢失),前端**不要 parseInt**,直接当字符串用。 - ---- - -### 2. 表格列建议 - -| 列 | 字段 | 说明 | -|---|---|---| -| 评价内容 | `content` | 超过 100 字省略号,鼠标 hover tooltip 看全文 | -| 作者 | `userNickname` | 链接到用户详情(可选,用 `userId`) | -| 关联产品 | `productName` | | -| 举报数 | `reportCount` | | -| 状态 | `reportStatus` | 见下面"状态枚举"中文化 | -| 举报原因 | `reasonStats` | 例如 `广告 ×3 / 辱骂 ×1`,通过字典翻译(下面有字典接口) | -| 隐藏时间 | `hiddenAt` | `reportStatus=HIDDEN` 时显示,否则空 | -| 创建时间 | `createTime` | 评价发布时间 | -| 操作 | (按钮) | 见下面"操作按钮规则" | - -### 状态枚举(中文化) - -| `reportStatus` | 中文 | tag 颜色建议 | -|---|---|---| -| `NORMAL` | 正常 | 灰 / 默认 | -| `PENDING_REVIEW` | 待复审 | 橙 / warning | -| `HIDDEN` | 已隐藏 | 红 / error | - ---- - -### 3. 操作按钮规则 - -按当前行的 `reportStatus` 显示不同按钮: - -| `reportStatus` | 显示这些按钮 | -|---|---| -| `NORMAL` | `警告作者` `忽略全部` | -| `PENDING_REVIEW` | **`隐藏评价`(主)** `警告作者` `忽略全部` | -| `HIDDEN` | **`恢复评价`(主)** | - -#### 各按钮对应的接口 - -```js -// 隐藏评价(弹个框让 admin 输 reason) -axios.post(`/admin/review/report-queue/${reviewId}/hide`, { - reason: '违规广告' // 必填 -}) - -// 恢复评价 -axios.post(`/admin/review/report-queue/${reviewId}/restore`) - -// 警告作者(后端目前只落日志,以后接站内信 SDK 再说) -axios.post(`/admin/review/report-queue/${reviewId}/warn-author`) - -// 忽略全部 = 把当前行 reporters[] 数组里每个 reportId 循环调忽略接口 -for (const r of row.reporters) { - await axios.post(`/admin/review/report-queue/report/${r.reportId}/ignore`) -} -``` - -**所有操作完成后请刷新当前页列表。** - ---- - -### 4. 展开行(可选,推荐有) - -点击行旁边的展开图标,展开看 `reporters[]` 数组,每个举报人一行: - -| 举报人 | 原因 | 详情 | 状态 | 时间 | 操作 | -|---|---|---|---|---|---| -| `oK****n8` (脱敏 openid) | 垃圾营销 | (用户填的 detail,可能为空) | `PENDING` | createTime | `[忽略本条]` | - -**`[忽略本条]` 按钮**: - -```js -axios.post(`/admin/review/report-queue/report/${reportId}/ignore`) -``` - ---- - -### 5. 字典翻译(reasonStats 里的 key) - -`reasonStats` 的 key 是英文 value(SPAM/INSULT/...),展示时翻译成中文 label: - -```js -// 拿字典(整个项目通用接口) -axios.get('/admin/system/dict-data/by-type', { - params: { dictType: 'review_report_reason' } -}) -``` - -返回(测试服实测): - -```json -{ - "code": 200, - "data": [ - { "value": "SPAM", "label": "广告/营销" }, - { "value": "INSULT", "label": "辱骂/人身攻击" }, - { "value": "PORN", "label": "色情低俗" }, - { "value": "POLITICS", "label": "政治敏感" }, - { "value": "FAKE", "label": "虚假评价" }, - { "value": "LEAK_PRIVACY", "label": "泄露他人隐私" }, - { "value": "OTHER", "label": "其他" } - ] -} -``` - -**不要硬编码这个映射**, 进页面拉一次缓存到 vuex/pinia 就行。 - ---- - -### 6. 顶部筛选区(REVIEW tab 时) - -页面顶部本来已经有"建议 / 场景 / 关键词"3 个筛选,在 REVIEW tab 时: - -| 原字段 | 改成 | -|---|---| -| 建议(下拉) | 改成 `reportStatus` 下拉(全部 / 正常 / 待复审 / 已隐藏),传 `reportStatus` 参数 | -| 场景 | **隐藏**(评价举报无 scene) | -| 关键词 | 保留,传 `keyword` 参数 | - -切回前 3 个 tab 时恢复原本的筛选字段。 - ---- - -## 你不用关心的(后端已搞定的) - -- 用户从小程序点举报(`POST /mp/review/report`)的数据已经 100% 落到后端 DB,实测 `reviewId=2048001001001001005` 已经有 1 条 SPAM 举报数据,你接入后能直接看到。 -- 网关路由、JWT 认证、字典初始化 全部就绪。 -- 排序后端默认 `reportCount DESC, createTime DESC`,**前端不要 sort 重排**。 -- `reporterOpenid` 已经脱敏(`oK****n8`),**不要再 mask**。 - ---- - -## 验收清单(全部对了再说做完) - -- [ ] 「人工复审队列」页面顶部 4 个 tab,默认还是"出行人姓名" -- [ ] 点"评价举报" tab,列表能加载,看到 reviewId=2048001001001001005 的那条数据 -- [ ] 评价内容/作者昵称/产品名 都是中文显示 -- [ ] `reasonStats` 的 SPAM 翻译成 "广告/营销" -- [ ] 状态显示"正常"(因为目前 reportCount=1 < 3) -- [ ] 操作按钮显示"警告作者 / 忽略全部"(NORMAL 状态) -- [ ] 展开行能看到 1 条 reporters,openid `oK****n8`,原因 "广告/营销" -- [ ] 切回"出行人姓名" tab,原列表还能正常加载(没把老 tab 弄坏) - ---- - -## 工作量 - -预计 1.5 天。 - -后端 0 改动。**所有接口都已部署到测试服,你可以直接联调。** - ---- - -## 联调环境 - -- 测试服域名: `https://api.test.1814.love:9443` -- admin 账号: `admin / Admin@123456` -- 已有测试数据: `reviewId=2048001001001001005`(粉色风蚀古堡产品的一条评价,被 SPAM 举报 1 次) -- 想再造数据: 用小程序登录,POST `/mp/review/report` body `{"reviewId":"...","reason":"INSULT"}` - ---- - -## 历史 changelog 注意 - -之前的 2 版让你"新建独立菜单 评价举报处理",**那个方向作废**。最终方向就是这版: **现有页面加 tab**。 diff --git a/changelogs/2026-05/06_refactor_agency_nacos_segments_removal.md b/changelogs/2026-05/06_refactor_agency_nacos_segments_removal.md deleted file mode 100644 index e46990c..0000000 --- a/changelogs/2026-05/06_refactor_agency_nacos_segments_removal.md +++ /dev/null @@ -1,104 +0,0 @@ -# refactor(agency): 切公司模块 DB 单一真相源, nacos.agencies + merchants 弃用 - -**日期**: 2026-05-06 17:30 -**通知对象**: @mmg (前端) + 运维同事 -**关联 PR**: wx/HL #1721 (已 merge dev + 测试服部署 + 业务 round-trip 通过) -**前序**: 公司模块 5 PR 累积 (#1715/#1717/#1718/#1719/#1720) - ---- - -## 一、用户原话 (2026-05-06) - -> 测试环境的 nacos 里的公司信息和支付信息都删除吧, 都改用这个公司模块, 再次检查影响范围都改为用公司模块. - -公司模块(`travel_agency` + `travel_agency_payment` 表)已经是全字段存储 + 透明加密落 DB,DB 数据完整。本 PR 切代码到 DB 单一真相源,nacos 弃用两段(测试服已删,正式服等运维)。 - ---- - -## 二、代码改动 (PR #1721) - -DB 优先 → nacos 兼容期兜底,渐进式 migration: - -| 文件 | 改动 | -|---|---| -| `WechatPayConfig` | `getConfig(mchId)` 加 DB fallback (`travelAgencyPaymentService.getByMchId` 拿 DO 构 `RSAPublicKeyConfig`,apiV3Key/mchSerialNo 透明解密); `warmUp` 改 lazy load (启动期 DB unready 强制预热会炸); `@Lazy` 注 paymentService 防 circular dep | -| `ContractPlatformProperties` | `getAgencyByMchId` DB 优先(`travelAgencyService.getByMchId` → `fromInternalDTO`); `getAgenciesByPlatform` DB 优先(`listEnabledInternal` 全量 + `supportedPlatforms` 过滤) | -| `teamreport AgencyProperties` | `@Lazy` 注 `travelAgencyService`; `getAgencyByCode/byMchId` DB 优先 → `AgencyInternalDTO` 转 teamreport 本地 `AgencyInfo` | -| `TravelAgencyService` | 新加 `listEnabledInternal()` 接口(返 `List<AgencyInternalDTO>` 含 `supportedPlatforms`) | - -## 三、影响范围核查 - -`grep contract.platform / wechat.pay.merchants` 仅 **hl-order-service-v2** 服务读取。其他服务(resource/mp/product-v2/user/gateway)全部不读这两段。改动范围限于 order-v2。 - -## 四、nacos 测试服删段(已完成) - -| 配置 | 删的段 | -|---|---| -| `hl-order-service-v2-test.yml` | `contract.platform.agencies`(3 家旅行社完整数据)+ `wechat.pay.merchants`(3 个商户加密字段) | -| `hl-resource-service-test.yml` | 同样段(冗余,resource service 不读但有) | - -保留: -- `wechat.pay.app-id`(全局共用 `wx4711a76772deff36`) -- `wechat.pay.notify-base-url`(支付回调地址) -- `contract.platform.standard / sync / travel-agency / default-platform / callback-base-url / default-agency-code`(平台级参数,跟具体公司无关) - -## 五、测试服 round-trip 验证 (2026-05-06 17:30) - -**部署 + 删段后** 业务接口 round-trip 全部 200: - -```bash -TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"Admin@123456"}' \ - | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])") - -# 1. 公司列表 — 走 DB ✅ -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \ - -H "Authorization: Bearer $TOK" -# 200 / 三家完整字段 - -# 2. 启用列表 — 走 DB ✅ -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/enabled" \ - -H "Authorization: Bearer $TOK" -# 200 / 3 家 - -# 3. payment 列表(透明解密) — 走 DB ✅ -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/2051922156798779394/payment" \ - -H "Authorization: Bearer $TOK" -# 200 / mchId 1106110439, appId wx4711a76772deff36, apiV3Key 透明解密返明文 -``` - -**服务状态**: hl-order-service-v2 双实例运行(primary 8094 + secondary 8194),无启动错误。 - -## 六、待办: 正式 nacos 同步删段 - -测试服已验证代码 + nacos 删段后稳定运行,**通知运维同步删正式 nacos**: - -| 配置 | 删的段 | -|---|---| -| `hl-order-service-v2-prod.yml` (prod ns) | `contract.platform.agencies` + `wechat.pay.merchants` | -| `hl-resource-service-prod.yml` (prod ns) | 同样段 | - -正式环境前置条件: -- [ ] 正式 DB `travel_agency` + `travel_agency_payment` 表已 seed 三家完整数据(团队报送 / 加密字段同 nacos) -- [ ] 部署 PR #1715/#1717/#1718/#1719/#1720/#1721 到正式服 -- [ ] 删 nacos 段后重启业务服务验证启动 + 创建订单/合同/团队上报场景 - -## 七、agency 模块完整 PR 清单 - -| PR | 内容 | -|---|---| -| #1715 | admin path 纠回 `/admin/travel-agency` | -| #1717 | 资质附件 qualificationType + 字典 (agency_qualification_type / agency_contract_platform) | -| #1718 | nacos 完整字段同步 (teamReportAppId/SignKey/supportedPlatforms + payment 加密字段) | -| #1719 | payment 加 name + appId 字段 | -| #1720 | supportedPlatforms 中文 label 翻译字段 | -| **#1721** | **代码切 DB 单一真相源, nacos.agencies + merchants 弃用(本 PR)** | - -## 八、前端无影响 - -后端只是改了实现层(读 DB 而非 nacos),所有 API 契约不变。前端代码无需任何改动。 - ---- - -cc @mmg(前端) + 运维(正式 nacos 删段) diff --git a/changelogs/2026-05/07_feat_admin_validation_round2_6prs.md b/changelogs/2026-05/07_feat_admin_validation_round2_6prs.md deleted file mode 100644 index 68753ca..0000000 --- a/changelogs/2026-05/07_feat_admin_validation_round2_6prs.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -date: 2026-05-07 -type: backend-feat -module: multi-module(resource/product/refund/insurance/contract/user) -priority: medium -notify: ["@mmg"] -status: deployed-pending -restart_services: ["hl-resource-service", "hl-product-service-v2", "hl-order-service-v2", "hl-user-service"] -gitea_prs: [1815, 1816, 1817, 1818, 1819, 1820] -gitea_issues_closed: [1808, 1809, 1810, 1811, 1812, 1813] -parent_tracking: 1796 ---- - -# 测试报告 22 项产品复核第二轮：17 项必做校验全部修复（6 PR 合并 dev） - -## 背景 - -来自 #1796 测试报告产品复核工单的 22 项分类决策，17 项判定为"必做（数据完整性 + 合规 + 简单同模式）"已 6 PR 修复完成；剩 5 项涉及产品方向决策保留 #1796 等产品方过。 - -## 6 PR 改动总览 - -| PR | 工单 | 模块 | 改动 | 单测 | -|----|------|------|------|------| -| #1815 | #1808 | hl-resource-service | 5 资源 batchDelete + 景区名重复 + 服务人员手机号重复 | 1133 全绿 | -| #1816 | #1809 | hl-product-service-v2 + 跨服务 Feign | 删除产品/预订条款引用校验 | 1098+31 全绿 | -| #1817 | #1810 | hl-order-service-v2 refund | 拒绝必填原因 + 阶梯重叠 + 政策删除 | 194 全绿 | -| #1818 | #1811 | hl-order-service-v2 insurance | 删除方案 plan_id 反查校验 | 158 全绿 | -| #1819 | #1812 | hl-order-service-v2 contract + 跨服务 Feign | 合同方案删除 product 反查 | 302+24 全绿 | -| #1820 | #1813 | hl-user-service | 探索分类删除/重名 + PHONE 渠道格式 | 75 全绿 | - -总计 55 文件 ~1700 行，4500+ 单测全绿。dev HEAD: cc3e6ac6 → 60c653c4。 - -## 前端配合（@mmg） - -### 1. 删除按钮可能新增"已被引用"业务异常 - -下面接口删除前会调引用校验： - -| 接口 | 校验逻辑 | 错误码（业务码） | -|------|---------|-----------------| -| `DELETE /admin/scenic/batch` | 5 资源批量删除前查产品引用 | SCENIC_DELETE_IN_USE 等 | -| `DELETE /admin/restaurant/batch` | 同上 | RESTAURANT_DELETE_IN_USE | -| `DELETE /admin/supplies/batch` | 同上 | SUPPLIES_DELETE_IN_USE | -| `DELETE /admin/staff/batch` | 同上 | STAFF_DELETE_IN_USE | -| `PUT /admin/supplies-combo/{id}/disable` | 下架前查 | SUPPLIES_COMBO_DELETE_IN_USE | -| `DELETE /admin/product/{id}` | 删除前 Feign 查订单引用 | PRODUCT_HAS_ORDERS_CANNOT_DELETE (400303) / REF_CHECK_FAILED (400304) | -| `DELETE /admin/booking-terms/{id}` | 删除前查产品补充引用 | BOOKING_TERMS_IN_USE (440201) | -| `DELETE /admin/refund-policy/{id}` | 删除前查退款申请引用 | 530210 | -| `DELETE /admin/insurance/scheme/{id}` | 删除前 plan_id 反查保险订单 | 540222 | -| `DELETE /admin/contract/scheme/{id}` | 删除前 Feign 查产品引用 | 510218 / 510219 | -| `DELETE /admin/explore/category/{id}` | 删除前查内容引用 | 220902 | - -**前端建议**：catch 这些业务码时弹窗显示后端 message（含被引用数 N，方便用户去解关联）。 - -### 2. 创建/更新校验新增 - -- 景区名称重复 → SCENIC_NAME_DUPLICATE（400 业务码） -- 服务人员手机号重复 → STAFF_PHONE_DUPLICATE -- 探索分类标题重复 → EXPLORE_CATEGORY_TITLE_DUPLICATE (220901) -- 拒绝退款 remark 必填 → 530208/530209 -- 退款政策阶梯天数重叠 → 530209 - -### 3. PHONE 渠道电话格式 - -`/admin/contact/save` 的 PHONE 渠道 value 字段加格式校验，正则兼容： -- 手机号：`1[3-9]\d{9}` -- 座机：`0\d{2,3}-?\d{7,8}` -- 客服热线：`[48]00-?\d{3,4}-?\d{3,4}`（兼容 400/800 客服） - -## 重要部署注意 - -### 跨服务 Feign 依赖（#1816 + #1819） - -#### #1816 product 删除查订单（必看） -- hl-product-service-v2 调 hl-order-service-v2 的 `/internal/order/count-active-by-product` -- **Feign 不配 fallback**（写动作严格阻断，订单服务异常不放行删除） -- 部署顺序：先部署 hl-order-service-v2（提供新 endpoint）→ 再部署 hl-product-service-v2 - -#### #1819 contract 删除查产品（必看） -- hl-order-service-v2 调 hl-product-service-v2 的 `/internal/product/count-by-contract-scheme/{schemeId}` -- Feign 配 fallback 返 `Result.error("产品服务不可用")` 不放行删除 -- 部署顺序：先 hl-product-service-v2 → 再 hl-order-service-v2 - -### 重启服务清单 -- hl-resource-service（PR #1815） -- hl-product-service-v2（PR #1816 + #1819 接收方） -- hl-order-service-v2（PR #1817 + #1818 + #1819 + 提供 #1816 接收方） -- hl-user-service（PR #1820） - -## 已知 follow-up（不阻塞合并，会建独立工单跟踪） - -1. **product 侧 `/internal/product/resource-in-use` Controller 仍未实现** —— PR #1815 资源侧调用链路打通，但 product 侧 endpoint 缺失，FallbackFactory fail-open 返空 list，**部署后 5 项资源校验暂不真正拦截**。这是 PR #1807 起就存在的遗留。 -2. **PR #1815 分层违规**：ScenicSpotService.updateSpot:248-251 + StaffService.validatePhoneUnique:639-645 在 Service 层直接 `new LambdaQueryWrapper<>()`，违反 CODE_RULES 1.2 / 附录 C #2，应下沉为 Mapper default 方法。 -3. **/@bug 早期发现的资源服务共性问题**：8 个资源服务 (hotel/scenic/activity/restaurant/staff/supplies/cost/vehicle) 的 updateStatus 全缺 checkResourceInUse，本批 PR 仅修了 5 个，其他 3 个待延伸。 - -## 验收 - -- [ ] 测试服部署 4 服务后 admin token 跑各 DELETE 接口验业务码 -- [ ] 前端 catch 错误码 + 弹窗提示 -- [ ] 跨服务 Feign 链路通畅（部署顺序对） - -## 关联 - -- 父工单：#1796 测试报告产品复核 -- 6 子工单：#1808~#1813 已自动 close diff --git a/changelogs/2026-05/07_feat_product-internal_resource-in-use_and_fail_closed.md b/changelogs/2026-05/07_feat_product-internal_resource-in-use_and_fail_closed.md deleted file mode 100644 index d2c6993..0000000 --- a/changelogs/2026-05/07_feat_product-internal_resource-in-use_and_fail_closed.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -date: 2026-05-07 -type: backend-feat -module: hl-product-service-v2/internal + hl-resource-service -priority: medium -notify: ["@mmg"] -status: tested-passed -restart_service: hl-product-service-v2 + hl-resource-service -gitea_pr: [1838, 1839] -gitea_issue: [1821] ---- - -# 资源删除/下架引用校验真实生效 + 产品服务不可用时改 fail-closed - -## 背景 - -PR #1815 + #1807 让资源侧 11~16 处 service 在删除/下架前调 `productFeignClient.checkResourceInUse(...)` 校验,但 **`hl-product-service-v2` 侧 endpoint 一直未实现**:`ProductFeignFallbackFactory` 默认 fail-open 返空 list → **所有引用校验都被静默放行**(测试服老景区 3001000000000000016 被 13 个产品引用却能 batchDelete 直接删)。 - -PR #1838 + 紧急 hotfix #1839 一次性闭环。 - -## 后端改动 - -### product 侧 (PR #1838) -- 新增 `/internal/product/resource-in-use` endpoint (11 类资源:SCENIC/RESTAURANT/ACTIVITY/SERVICE/HOTEL/ROOM_TYPE/SUPPLIES/SUPPLIES_COMBO/STAFF/VEHICLE/COST) -- 返回 `Result<List<String>>`(被引用的产品名列表,空 list = 无引用) -- 上限 100,升序稳定输出 -- Flyway V20260507_004 幂等补 `product_supplies.from_combo_id` 列(legacy alter 未入 migration) - -### product 侧 (hotfix PR #1839) -- `ProductItineraryNodeMapper.selectProductIdsByResource` WHERE 条件改为 `(node_type=? OR resource_type=?)` OR 双兜底 -- 修因:历史 product_itinerary_node 数据 `resource_type` 列长期 NULL,真实类型存于 `node_type` 列(MpProductSnapshotAssembler:346 注释 "快照:资源类型用 nodeType 兜底"已说明) -- 测试服 round-trip 实测:删除 3001000000000000016 → deniedIds 含 + reasons 含 13 个中文产品名 - -### resource 侧 -- `ProductFeignFallbackFactory` 改 fail-closed:产品服务失败/熔断时返 `code=100903 "产品服务不可用,无法校验资源引用,请稍后重试"` -- 16 处调用点统一改 `if (!result.isSuccess()) throw FEIGN_RPC_FAIL` 模式 - -### 顺带修复 PR #1815 两处 Service 层 LambdaQueryWrapper 违规 -- `ScenicSpotService.updateSpot` 下沉到 `ScenicSpotMapper.countByNameExcludeId` -- `StaffService.validatePhoneUnique` 下沉到 `StaffMapper.countByPhoneExcludeId` - -## 前端可见变化 - -### 资源删除/下架接口异常情况新增 - -资源(景区/餐厅/活动/酒店/房型/服务人员/备品/备品组合/用车/成本项 等)删除/下架接口在**产品服务不可用时**会返: - -```json -{ - "code": 100903, - "message": "产品服务不可用,无法校验资源引用,请稍后重试" -} -``` - -@mmg 前端需要捕获 100903,提示用户重试。 - -### 被引用资源删除/下架的响应(原有但现在真生效) - -batchDelete 接口返: -```json -{ - "code": 200, - "data": { - "successCount": 0, - "deniedIds": ["3001000000000000016"], - "deniedReasons": ["被产品使用: 产品A、产品B、产品C..."] - } -} -``` - -前端原有展示 deniedReasons 即可。 - -### batchDelete 行为变化 -批量删除时若产品服务调用失败,**整体抛异常中止**(原可能 N 次重试,部分 denied 部分成功)。前端弹"产品服务不可用,请稍后重试"即可,无需逐条处理。 - -## 重启服务 - -测试服已部署:`hl-product-service-v2`(PR #1838 → #1839 hotfix 已 redeploy)+ `hl-resource-service`(PR #1838)。 - -## 验收(测试服 round-trip 实测) - -- [x] **创建产品引用资源(景区) → batchDelete 该景区** → `deniedReasons` 含中文产品名,景区未被删除 (UC-A 实测 13 个产品名) -- [x] **删除/下架未被引用的资源** → 正常成功 (UC-D 创建新景区→batchDelete successCount=1) -- [x] **fail-closed 模式生效**:Mapper OR 双兜底命中 nodeType 字段 -- [x] **PR #1815 两处分层违规下沉到 Mapper** (UC-5b 编辑自身保留同名 code=200) -- [x] **跨服务 Feign 不配 fallback 仅返 isSuccess=false** (`Result.error`) -- [ ] hotel/activity/vehicle/cost 4 资源服务 fail-closed 同步覆盖 (代码已改,测试服 round-trip 时间所限只跑 SCENIC,留监控验证) - -## 关联工单 - -- Gitea #1821 (本 PR 闭环, 已 auto-close via PR #1838) - -## Follow-up(本 PR 不修) - -- 16 处 fail-closed 模板代码可提取 `ResourceReferenceCheckHelper` -- RoomType 禁用按 HOTEL 维度校验语义偏严(PR #1815 引入) -- `product_itinerary_node(resource_type, resource_id)` 复合索引(数据量起来后) -- `product_supplies(supplies_resource_id)` / `product_route_info(vehicle_model_id)` 索引 -- batchDelete TOCTOU 时序问题 -- PR #1838 单测 14 用例都用 mock,Mocked Mapper 无法暴露 SQL 与 DB schema 错位 — 后续应加 H2 集成测试或 `@MybatisPlusTest` 真跑 SQL - -## 已知影响(测试服) - -- QA round-trip 期间 SCENIC `3001000000000000005` + RESTAURANT `2023382103407751169` 被前轮(hotfix 前)误删,无法恢复;测试人员需重建相关测试数据 diff --git a/changelogs/2026-05/07_feat_product_publish_relax_validation_and_team_independent_api.md b/changelogs/2026-05/07_feat_product_publish_relax_validation_and_team_independent_api.md deleted file mode 100644 index 43ffe69..0000000 --- a/changelogs/2026-05/07_feat_product_publish_relax_validation_and_team_independent_api.md +++ /dev/null @@ -1,120 +0,0 @@ -# 产品上架放宽校验 + 已上架可独立管理团期/团队 - -**日期**: 2026-05-07 -**类型**: 后端 API 增强 + 前端调整建议 -**模块**: 产品（hl-product-service-v2） -**通知**: @mmg -**关联工单**: #1775 -**关联 PR**: #1779 + #1781（hotfix） - ---- - -## 业务变更 - -用户翻盘业务规则：**产品（尤其 GROUP/小蒙马）上架时不再硬校验团队/团期，可以「先上架后补」**。已上架（PUBLISHED）后通过现有/新增独立接口管理班期和团队成员。 - ---- - -## 后端改动 - -### 1. 上架校验放宽（`POST /admin/product/item/{id}/toggle-publish`） - -GROUP 产品上架时**不再强校验**: -- ~~至少 1 个班期~~（已删除） -- ~~每个班期至少 1 个 LEADER 角色成员~~（已删除） -- ~~至少 1 个未来出发、成人价 > 0 的班期~~（已删除） - -**保留校验**: -- 基础字段（名称/天数/封面/标签） -- 行程完整性（至少 1 天） -- 餐饮配置 -- CORE/CUSTOM 价格日历未来有效价 ≥ 1（GROUP 不要求） - -### 2. 已上架可独立管理班期 - -**`POST /admin/product/item/{id}/schedule`** — saveSchedule -- 新增/修改单个班期 -- **PUBLISHED 状态可调用**（之前会被 checkEditable 拒） -- 调用成功后产品 `priceVersion++` 并触发 mp 缓存失效 - -**`POST /admin/product/item/{id}/schedule/batch-create`** — batchCreateSchedule -- 按重复模式批量生成班期（≤52个） -- **PUBLISHED 状态可调用** -- 整批调用 priceVersion 只 +1（不会膨胀） - -**`DELETE /admin/product/item/{id}/schedule/{scheduleId}`** — deleteSchedule -- 删除班期 -- **PUBLISHED 状态可调用** -- 已有报名订单的班期仍拒删（业务保护，返回剩余订单数） -- 删除后 `priceVersion++` 触发缓存失效 - -### 3. 已上架可独立管理团队（**新增独立接口**） - -**`POST /admin/product/item/{id}/schedule/team`** — saveScheduleTeam ⭐ 本次新增 -- request body 同既有 `ScheduleTeamSaveReqVO`： - ```json - { - "productId": "<id>", - "batchId": "<batchId>", - "staffList": [ - {"staffId": "<staffId>", "staffRole": "LEADER", "staffName": "...", "staffPhone": "...", "sortOrder": 1} - ] - } - ``` -- 全删全插策略：传完整列表覆盖该 batchId 的全部成员 -- **PUBLISHED 状态可直接调用**（绕过 supplement 接口的整体 checkEditable 拦截） -- staffId / staffRole / staffName / staffPhone 这些字段如果数据库 NOT NULL 必传 - -> 之前: 团队只能通过 `PUT /supplement` 嵌套保存，但 supplement 接口 PUBLISHED 整体被拒 -> 现在: 独立 `POST /schedule/team` 直调 saveTeam，不受 supplement 状态拦截影响 -> 与既有 `GET /schedule/team` 路径对称 - -### 4. 缓存一致性 - -修改班期/团队后通过 `registerAfterCommit('product' source)` 触发 D3 反向缓存失效，mp 端详情/列表/起步价自动同步（≤ 几秒）。 - ---- - -## 前端调整建议（@mmg） - -### 1. 「上架向导第 4 步 → 补充信息 → 团队配置」 - -当前页面对每个班期显示「N 人已配」+ 必填校验「至少 1 个领队」。 - -**建议调整**: -- 去掉「至少 1 个领队」的必填星号 + 提交拦截 -- 可保留业务建议文案（如「建议每期配置 1 个领队，确保订单详情显示完整」），但**不阻塞上架** -- 前端「上架」按钮在团队/团期为空时不再 disable 或弹错误提示 - -### 2. 「已上架后管理团期/团队」入口（**新交互**） - -业务诉求：用户希望产品上架后能独立加新团期、补领队等。 - -**建议交互**（仅供参考，最终方案 mmg 决定）: -- 在产品列表「已上架」状态的产品行加「管理团期/团队」入口（侧边栏 / 浮层 / 跳转新页面均可） -- 已上架产品调用以下接口（参数 / response 与上架前一致）: - - 加新团期: `POST /admin/product/item/{id}/schedule` - - 删团期: `DELETE /admin/product/item/{id}/schedule/{scheduleId}` - - 改团队: `POST /admin/product/item/{id}/schedule/team` ⭐ 新接口 -- **不再需要先把产品下架再修改** - ---- - -## round-trip 验收（已通过） - -测试服 9443 网关 + admin / Admin@123456 token 实测: - -| 验收项 | 接口 | 结果 | -|---|---|---| -| GROUP DRAFT toggle-publish message 不再含「班期/LEADER/领队」字样 | POST `/admin/product/item/{id}/toggle-publish` | ✅ message="行程未完整填写..." 不含班期相关字样 | -| PUBLISHED 加新班期 | POST `/admin/product/item/{id}/schedule` | ✅ code:200, batchId 落库 | -| PUBLISHED 删班期 | DELETE `/admin/product/item/{id}/schedule/{batchId}` | ✅ code:200 msg=班期删除成功 | -| PUBLISHED 调独立 saveTeam | POST `/admin/product/item/{id}/schedule/team` | ✅ code:200 msg=团队保存成功 | - ---- - -## 风险与兼容性 - -- **订单价格 snapshot 模式不变**：已下单订单不受班期价格变化影响 -- **既有 `PUT /admin/product/item/{id}/supplement` 接口不变**：仍可在草稿态批量保存团队（DRAFT/REJECTED/UNPUBLISHED 流程不受影响） -- **新接口与 GET 同路径不冲突**：`GET /schedule/team` (查询) + `POST /schedule/team` (保存) 共存 diff --git a/changelogs/2026-05/07_feat_share_lock_customizer.md b/changelogs/2026-05/07_feat_share_lock_customizer.md deleted file mode 100644 index de8a4ed..0000000 --- a/changelogs/2026-05/07_feat_share_lock_customizer.md +++ /dev/null @@ -1,147 +0,0 @@ -# 产品分享链接带 adminId → 下单/支付锁定为分享人定制师 - -**类型**: 后端 + 前端协作改动 -**前端处理者**: mmg -**日期**: 2026-05-07 -**关联**: 工单 #1814 / PR #1825 (已合 dev) -**影响页面**: -- 管理后台「产品列表 → 分享到小程序」弹窗(URL Scheme/URL Link 拼接) -- 小程序「产品详情页」(`packages/product/core/detail/detail`) 接收 adminId 参数 -- 小程序「下单」接口 (`POST /mp/order/create`) 新增 customizerId 选填字段 -- 小程序「支付预下单」接口 (`POST /mp/payment/prepay`) 新增 customizerId 选填字段 - ---- - -## 这是什么 - -定制师傅分享产品给客户时, 客户点链接进小程序下单, 订单的"定制师"锁定为分享人 adminId, 不再走系统随机分配。 - -设计参考: 截图里管理后台「分享到小程序」弹窗已能生成 URL Scheme / URL Link, 路径 `packages/product/core/detail/detail?id=<productId>&adminId=<currentAdminId>`。 - ---- - -## 仅产品分享 - -✅ 仅产品详情页支持 (URL `packages/product/core/detail/detail`) -❌ 不支持产品线 / 活动 / 订单 / 其他页面分享(产品线/活动等不带 adminId, 不受影响) - -定制师傅在小程序内自己分享 (微信原生 onShareAppMessage) 暂不支持 — 需要先做 mp 用户和 admin 账号关联, 已开 #1815 单独跟进。 - ---- - -## 前端必做的 4 件事 - -### 1. 管理后台 PC「分享到小程序」弹窗 — URL 拼接 adminId - -文件: `hl-ui/.../components/ProductShareDialog.vue` (或类似名) - -URL Scheme / URL Link 生成时, **小程序页面路径**字段值必须拼接 `&adminId=<当前登录管理员 adminId>`: - -```js -const path = `packages/product/core/detail/detail?id=${productId}&adminId=${currentAdminId}` -``` - -`currentAdminId` 从当前登录态拿(Vuex/Pinia 里的 `userStore.adminId`)。**类型必须是 number, 不要是 string** — 后端 `customizerId: Long` 强类型反序列化, String 会 400。 - -### 2. 小程序产品详情页 — 解析 URL adminId 存 sessionStorage - -`packages/product/core/detail/detail.vue` onLoad / onShow: - -```js -onLoad(options) { - if (options.adminId) { - const adminId = Number(options.adminId) - if (Number.isFinite(adminId) && adminId > 0) { - uni.setStorageSync('share_customizer_id', adminId) - } - } -} -``` - -**多次进入不同分享链接**: 每次都覆盖, 不累加(用户先进 A 师傅链接、再进 B 师傅链接, 最后进的 B 链接覆盖之前的 A)。 - -### 3. 创建订单接口 — 透传 customizerId - -`POST /mp/order/create` 请求 body 加字段: - -```js -const customizerId = uni.getStorageSync('share_customizer_id') || null -const body = { - // ... 原有字段 - customizerId, // null 或 number, 不要传 string -} -``` - -字段约定: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `customizerId` | `number` (Long) | ❌ 选填 | 分享人 adminId; 不传/null/0 走系统随机分配; 后端 `@Min(1)` 校验 | - -### 4. 支付预下单接口 — 同样透传 customizerId - -`POST /mp/payment/prepay` 请求 body 加字段: - -```js -const customizerId = uni.getStorageSync('share_customizer_id') || null -const body = { - orderId: '...', - customizerId, // null 或 number -} -``` - -**为什么支付路径也要传**? "以用户支付的链接为准" — 用户先进 A 师傅链接创建订单(订单 customizerId=A), 创建后退出去, 又进 B 师傅链接来这个订单页支付, 此时支付透传 customizerId=B → 后端漂移回写订单 customizerId=B。如果支付时不传 customizerId, 订单保持创建时的 customizerId 不变。 - ---- - -## 后端兜底语义 (不要在前端做这些校验) - -后端 CustomizerValidator 严格校验 4 类失败场景, 失败都**走系统随机分配**(不报错, 兼容老前端): - -| 失败原因 | 触发条件 | 前端表现 | -|---------|---------|---------| -| ADMIN_NOT_FOUND | adminId 不存在/已删除 | 兜底随机, 静默 | -| INACTIVE_STATUS | admin status ≠ ACTIVE (禁用/锁定) | 兜底随机, 静默 | -| WRONG_ROLE | admin roleKey ≠ CUSTOMIZER (普通管理员/客服/经理) | 兜底随机, 静默 | -| FEIGN_ERROR | user-service Feign 失败 | 兜底随机, 静默 | -| INVALID_INPUT | customizerId == null / ≤ 0 | 兜底随机, 静默 | - -后端在所有失败路径**只打 WARN 日志不返错**, 前端不需要展示"分享师傅不可用"这类提示, 用户体验完全无感。 - ---- - -## 验证方式 (前端联调时) - -1. 用一个**有效 CUSTOMIZER + ACTIVE** 的 adminId 拼 URL 分享 → 客户下单后看「我的订单」是不是显示这个师傅 -2. 创建订单后**不立刻支付**, 退出小程序, 再用另一个**有效 CUSTOMIZER** 师傅的分享链接进入这个订单 → 支付前透传新 customizerId → 订单详情应该显示新师傅 -3. 不分享直接下单 (URL 无 adminId 参数) → 系统随机分配, 行为同改造前 - ---- - -## 兼容性 - -- ✅ **零破坏性平滑发布**: 老前端不传 customizerId → 后端 null fallback → 兜底随机 = 改造前行为, 后端先合不影响线上 -- ✅ 老订单 customizer_id 不动, 仅新建/支付路径生效 -- ❌ 不影响 admin 端创建订单流程(后台代下单仍是 admin 自己当 customizer) - ---- - -## 字段约束硬规则 - -- 类型必须 `number` (Long) — 不要传 `string` -- URL `?adminId=` 后端拿到是 `string`, 必须前端 `Number(adminId)` 转换后才放进请求 body -- 不传 / 传 `null` / 传 `0` / 传负数 → 全部走兜底随机 -- 不需要前端做任何校验 (validity / role 等), 后端全权负责 - ---- - -## 不在本期范围 (后续工单跟进) - -- ❌ 定制师傅在小程序内分享 (微信原生 onShareAppMessage 拼 URL): 需要先做 mp 用户与 admin 账号绑定 → #1815 -- ❌ 分享统计 / 分销提成: 现有 `sharer_openid` 字段独立维护, 不与 customizer 强绑定 - ---- - -## 责任人 - -@mmg 接入前端: 4 步 (PC 弹窗 URL / 小程序 onLoad 解析 / 创建订单透传 / 支付透传) diff --git a/changelogs/2026-05/07_fix_admin_user_list_status_dict_whitelist.md b/changelogs/2026-05/07_fix_admin_user_list_status_dict_whitelist.md deleted file mode 100644 index 0679a6c..0000000 --- a/changelogs/2026-05/07_fix_admin_user_list_status_dict_whitelist.md +++ /dev/null @@ -1,72 +0,0 @@ -# fix(user): /admin/user 列表非字典 status (status=1) 致 total > 0 records=0 - -**PR**: [#1834](https://git.1814.love:8443/wx/HL/pulls/1834)(主修复)+ #1831 + #1832(回滚于 #1833) **Issue**: [#1829](https://git.1814.love:8443/wx/HL/issues/1829) **合并**: 2026-05-07 - -通知对象: 无前端配合(后端 controller 防御兜底,前端可继续传任意值后端兜底) - ---- - -## 现象 - -正式 admin: `https://admin.1814.love/admin/user?page=1&pageSize=100&status=1` 显示「有数量没有数据」。 - -测试服真 admin token round-trip 完美复现: - -| 请求 | total | records | 备注 | -|---|---|---|---| -| `status=1` | **28** | **0** | ❌ BUG | -| 其他无效值(0/2/ABCXYZ/true) | 0 | 0 | ✅ 一致 | -| `status=ACTIVE` | 28 | 28 | ✅ | - -仅 `status=1` 这个特定值出 BUG。 - -## 根因(深度排查 3 轮才定位) - -MP `PaginationInnerInterceptor` 用 jsqlparser 把 records SELECT SQL parse 改成 count SQL。`status='1'` 这个字面值 + `.select(projection)` + `.ne(status, X)` + `.eq(status, '1')` 组合触发 jsqlparser 解析失败,**fallback 到 `SELECT COUNT(*) FROM admin_user`**(丢全部 WHERE)→ count=28(全表)records=0。 - -3 轮修复教训: -- **r1 PR #1831**: wrapper 从 `LambdaQueryWrapper` 迁 `LambdaQueryWrapperX` + Mapper default 方法。合 CODE_RULES 1.2,顺手修了 `status=""` 空串过滤。**但 status=1 BUG 仍在**。 -- **r2 PR #1832**: 试图 `selectCount(w) + setSearchCount(false) + selectPage(page,w)` 绕过 PaginationInnerInterceptor 自动 count。**炸 SQL 全 500 BadSqlGrammarException**(wrapper state mutation 引发)→ PR #1833 revert 紧急回滚。 -- **r3 PR #1834 (最终)**: 在 controller 层加 status 字典白名单 (`ACTIVE/LOCKED/DISABLED`),非字典值直接返 `PageResult.empty()` 不进 mapper。**从源头杜绝 MP BUG 路径**。 - -## 后端修了什么 - -`AdminUserController.listAdmins`(`hl-user-service/.../controller/AdminUserController.java`)在 role 鉴权之后、调 service 之前加: - -```java -private static final Set<String> VALID_ADMIN_STATUS = Set.of( - UserConstants.STATUS_ACTIVE, - UserConstants.ADMIN_STATUS_LOCKED, - UserConstants.STATUS_DISABLED); - -if (status != null && !status.isEmpty() && !VALID_ADMIN_STATUS.contains(status)) { - return Result.success(PageResult.of(Collections.emptyList(), 0L, page, pageSize)); -} -``` - -mapper / service 0 改动。守护单测 `listAdmins_invalidStatus_returnsEmptyPage` 验证 status="1" 时 mapper 不被调用 + 响应空。 - -## 前端无需改动 - -前端可继续传任意值,后端兜底返空。但**建议前端只传字典值**(ACTIVE/LOCKED/DISABLED)避免无意义请求。 - -## 部署依赖 - -无 nacos / SQL / 第三方配置变更。直接部署即生效。 - -## 受影响范围 - -- `/admin/user` 列表所有 status 过滤路径(修复) -- 其他 GET 列表接口同样 PaginationInnerInterceptor 行为可能存在类似潜在 BUG,但本 PR 不范围内修复 -- 已识别遗留(本次未处理): MP `PaginationInnerInterceptor` jsqlparser fallback BUG 根因仍在,需要升级 MP 版本或换 SQL 方案,留后续 PR - -## 测试服 round-trip 验证 (PR #1834 部署后) - -``` -status=1 → total=0 records.length=0 ✅ -status=0/2/ABCXYZ/true → 0/0 ✅ -status=ACTIVE → 28/28 ✅ -status=DISABLED → 0/0 ✅ -不传 status → 28/28 ✅ -status=ACTIVE&roleId=1 → 7/7 ✅ -``` diff --git a/changelogs/2026-05/07_fix_insurance_purchase_idcardtype_field_rename.md b/changelogs/2026-05/07_fix_insurance_purchase_idcardtype_field_rename.md deleted file mode 100644 index b5928c8..0000000 --- a/changelogs/2026-05/07_fix_insurance_purchase_idcardtype_field_rename.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -date: 2026-05-07 -type: backend-fix -module: hl-order-service-v2/insurance -priority: high -notify: ["@mmg"] -status: deployed-pending -restart_service: hl-order-service-v2 -gitea_pr: 1805 -gitea_issue: 1789 -related_cases: [BD-001] -breaking_change: false ---- - -# 投保人证件号字段名改回 V1 契约 + JsonAlias 兼容（保险订单创建修复） - -## 现象（BD-001） - -``` -POST /admin/insurance/purchase -Body: {"insuredList":[{"name":"张三","idType":"ID_CARD","idNo":"110101...",...}],...} -响应: {"code":400,"message":"证件类型不能为空, 证件号码不能为空"} -``` - -即使前端填了证件号也报必填。 - -## 根因 - -V2 重写时单方面把 `PurchaseInsuranceRequest` 的 `idCardType / idCardNo` 改名成 `idType / idNo`。前端按 V1 契约持续传 `idCardType / idCardNo`，Jackson `FAIL_ON_UNKNOWN_PROPERTIES=false` 静默丢字段，双 @NotNull 触发必填。 - -## 修复 - -PR #1805 已合并 dev。 - -1. **DTO 改回 V1 字段名**：`PurchaseInsuranceRequest.idType → idCardType`，`idNo → idCardNo` -2. **加 @JsonAlias 双向兼容**：`@JsonAlias({"idType"})` / `@JsonAlias({"idNo"})` —— 两种字段名都能反序列化 -3. service 层 7 处 getter/setter 引用全部跟改（含 PR #1800 拆出的 InsurancePurchaseTxService） - -## 前端调用（@mmg） - -### 推荐写法（两种都可，建议用 V1 字段名） - -```js -// ✅ 推荐：V1 契约字段名 -POST /admin/insurance/purchase -{ - "schemeId": "2046840448906940417", - "orderId": "...", - "insuredList": [ - { - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "110101199001011234", - "phone": "13800138000", - "birthday": "1990-01-01", - "relationship": "SELF" - } - ] -} - -// ⚠️ 兼容（@JsonAlias 兜底，但建议改用上面的） -{ - "insuredList": [ - {"idType": "ID_CARD", "idNo": "...", ...} - ] -} -``` - -### 重要：同时传新旧字段时的优先级 - -如果前端代码同时传了 `idCardType` 和 `idType`（不推荐），Jackson 用最后出现的覆盖。建议**只传一种**，统一改用 V1 字段名 `idCardType / idCardNo` 跟项目其他 traveler DTO 对齐。 - -### idCardType 枚举值 - -``` -ID_CARD 身份证 -PASSPORT 护照 -HONG_KONG 港澳通行证 -TAIWAN 台湾通行证 -OTHER 其他 -``` - -### 字段加密提醒 - -`InsuredPerson.idCardNo` 已挂 `EncryptTypeHandler`，落库自动加密、查询自动解密，前端无感。日志全部已脱敏（grep 31 处零打印明文）。 - -## 重启服务 - -`hl-order-service-v2` 部署测试服后即可。 - -## 验收 - -- [ ] 用 `idCardType / idCardNo` 字段名 POST → 返 code:200 创建保险订单 -- [ ] 用 `idType / idNo`（旧字段名兜底）POST → 同样 code:200（@JsonAlias 兼容） -- [ ] 缺失证件号 → 返必填提示 -- [ ] DB 中 idCardNo 是加密格式（解密查 InsuredPersonVO 是明文） - -## 关联工单 -Gitea #1789 已 Closes 关闭。 - -## 备注 -本次修复保留 V2 内部其他字段（V2 重写期间引入的合理改动），仅恢复**对外契约字段名**。前端零改动也能调通（@JsonAlias 兜底），但建议主动改回 V1 字段名以保持代码清晰。 diff --git a/changelogs/2026-05/07_fix_mp_arrival_batch_validation_friendly.md b/changelogs/2026-05/07_fix_mp_arrival_batch_validation_friendly.md deleted file mode 100644 index 252f7b2..0000000 --- a/changelogs/2026-05/07_fix_mp_arrival_batch_validation_friendly.md +++ /dev/null @@ -1,133 +0,0 @@ -# 小程序填写返程信息: 校验前置 mp 端 + 错误信息友好化（前端有 BUG 待排查） - -> **服务**: hl-mp-service (端口 8085) -> **PR**: #1830 (已合并 dev, 待部署 prod) -> **Issue**: #1828 (P0-紧急, 正式环境) -> **日期**: 2026-05-07 -> **影响范围**: 小程序「填写返程信息」页（自驾/飞机/火车 × 一起返程/分批返程 全部场景） -> **@ 前端**: mmg - ---- - -## ⚠️ 关键信息 - -正式环境用户在小程序「填写返程信息」点「确认提交」后弹 toast： - -> batchReplace.reqs[0].travelerIds: 出行人列表不能为空 - -用户 UI 上**已经勾选了「蒋桂龙」乘坐人员**，但后端收到的 `travelerIds` 是空 — 这是一个**双重 BUG**： - -1. **前端 BUG（mmg 必修）**：hl-mini 小程序 `_buildTogetherPlan` 把勾选的 traveler 的 `id` 装进请求 body 时，因 ID 字段名漂移导致最终装入的是占位符 `order-N` 被过滤，致 travelerIds 空数组 -2. **后端友好化（本 PR 修）**：`MpArrivalController.batchReplace` 用 `@Valid List<...>` 不递归到元素，校验穿透到 internal controller 才被 `@Validated` 触发，错误信息暴露内部参数名 `batchReplace.reqs[0]` - ---- - -## 一、后端变更（本 PR 已合 dev） - -### 1.1 接口契约 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 全量替换返程批次 | POST | `/mp/order/{orderId}/arrival/batch` | **错误信息变更（不破坏契约）** | body 形状不变；mp 端前置校验，错误信息中文友好 | - -### 1.2 新错误码 - -| Code | Message | 触发条件 | -|------|---------|----------| -| `620001` | 请添加至少一批返程信息 | body 是空 List 或 null | -| `620002` | 第 N 批返程信息：请选择至少一位乘坐人员 | body[N-1].travelerIds 为 null 或空 List | - -### 1.3 旧错误信息（部署前）vs 新错误信息（部署后） - -| 场景 | 部署前 | 部署后 | -|------|--------|--------| -| body 空 | `batchReplace.reqs: 不能为空` | `请添加至少一批返程信息` | -| 首批空 travelerIds | `batchReplace.reqs[0].travelerIds: 出行人列表不能为空` | `第 1 批返程信息：请选择至少一位乘坐人员` | -| 第二批空 travelerIds | `batchReplace.reqs[1].travelerIds: 出行人列表不能为空` | `第 2 批返程信息：请选择至少一位乘坐人员` | - -### 1.4 服务端日志增强 - -mp controller 抛出校验失败前会 log.warn： -``` -mp/arrival/batch 校验失败 orderId={} userId={} bodySize={} 元素摘要={} -``` -（元素摘要含 direction / transportType / travelerIds.size 协助排查前端实际发出 body） - -部署后 mmg 可以让运维拉 hl-mp-service WARN 日志看真实 body 形状（每元素含 direction/transportType/travelerIds 是否为空）。 - ---- - -## 二、前端待处理（mmg 必修） - -### 2.1 嫌疑代码位置 - -`hl-mini/packages/trip/arrival/arrival.js`： - -**行 88（`_loadPassengers`）**： -```js -id: String(t.orderTravelerId || t.travelerId || t.id || `order-${idx}`) -``` - -**行 681-686（`_buildTogetherPlan`）**： -```js -const selected = this.data.passengers.filter(p => p.checked && !p._isLocal); -const travelerIds = selected - .map(p => String(p.id || '')) - .filter(id => id && !id.startsWith('order-') && !id.startsWith('local-')); -``` - -### 2.2 排查步骤（建议） - -1. 在 `_buildTogetherPlan` 进入时打日志： - ```js - console.log('[arrival] passengers=', this.data.passengers, 'selected=', selected, 'travelerIds=', travelerIds); - ``` -2. 复现「蒋桂龙」场景（正式订单），观察 passenger 对象的 `id` 字段真实值： - - **如果是 `order-0` 这种占位符** → `_loadPassengers` 三个候选字段名（`orderTravelerId / travelerId / id`）都没拿到值，对照后端 `getOrderDetail` 接口返回的 `travelers[]` 元素**真实字段名**与三候选是否对齐 - - **如果是雪花 ID** → `_buildTogetherPlan` 的 filter 逻辑是否有别的过滤条件把它排掉 -3. 对照后端 VO（`hl-mp-service` 的 `MpOrderTravelerVO`）确认实际字段名 — 必要时让我贴出来 - -### 2.3 separate 模式（多批次返程） - -`arrival.js` L711 `_buildSeparatePlans` 取 `b.travelerIds || []`，L717 已有"第 N 批缺少出行人"前置 toast 拦截 — 理论上不会发到后端。但若有路径绕过此 toast，本次后端校验是兜底。 - ---- - -## 三、数据库行为 - -只读校验，不写库。校验失败立即抛 BusinessException 不进入 Feign 调 order-v2。 - ---- - -## 四、边界行为 - -- body=null → 620001 "请添加至少一批返程信息" -- body=[] → 620001 -- body=[{travelerIds:null}] → 620002 "第 1 批..." -- body=[{travelerIds:[]}] → 620002 -- body=[{travelerIds:[10001]}, {travelerIds:[]}] → 620002 "第 2 批..." -- body=[{travelerIds:[10001]}, {travelerIds:[10002]}] → 走 Feign 到 internal，正常处理 - ---- - -## 五、不影响范围 - -- 仅 `POST /mp/order/{orderId}/arrival/batch` 一个接口 -- mp create / update / delete / list 接口 0 改动 -- internal controller `@Validated` 兜底仍在，admin / 其他客户端调 internal 仍受校验 -- API 契约（body 形状）不变，前端无需改请求结构 - ---- - -## 六、测试 - -- 单测: `MpArrivalControllerTest` **9/9 全绿** (5 原有 + 4 新增反例：空 body / null body / 首批空 travelerIds / 第二批空 travelerIds) -- 测试服 round-trip: 待 dev 部署测试服后由 QA 验证 -- prod 部署: 由运维管理员排期 (本 PR 不动 prod) - ---- - -## 七、相关文档 - -- 关联 Issue: [wx/HL#1828](https://git.1814.love:8443/wx/HL/issues/1828) -- 关联 PR: [wx/HL#1830](https://git.1814.love:8443/wx/HL/pulls/1830) diff --git a/changelogs/2026-05/07_fix_mp_price_calendar_null_500.md b/changelogs/2026-05/07_fix_mp_price_calendar_null_500.md deleted file mode 100644 index dc75bf0..0000000 --- a/changelogs/2026-05/07_fix_mp_price_calendar_null_500.md +++ /dev/null @@ -1,65 +0,0 @@ -# fix(mp-product): 价格日历接口接收 startDate/endDate 时抛 500 - -**PR**: [#1778](https://git.1814.love:8443/wx/HL/pulls/1778) **Issue**: [#1776](https://git.1814.love:8443/wx/HL/issues/1776) **合并**: 2026-05-07 - -通知对象: @mmg（小程序前端，建议小修一处） - ---- - -## 后端修了什么 - -`GET /mp/product/{id}/price-calendar` 接口当传 `?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` 时报 500： - -``` -DateTimeParseException: Text 'null-01' could not be parsed at index 0 -``` - -根因：`MpPriceCalendarReqVO` 原本只声明 `month` 字段。前端 `packages/order/supplement/supplement.js:531` 传的是 `{startDate, endDate}` → Spring 没字段绑定 → `req.getMonth()=null` → `LocalDate.parse("null-01")` 抛异常。 - -PR #1778 补的： - -- VO 加 `startDate`/`endDate` 字段（与 `month` 二选一，向前兼容） -- Service 抽 `resolveMonthRange()` 私有方法：`startDate+endDate` 同月优先 → `month` 兜底 → 全空/格式错抛 `BusinessException` -- 加 2 个 ErrorCode： - - `410108 PRICE_CALENDAR_PARAM_MISSING` 参数缺失或格式错误 - - `410109 PRICE_CALENDAR_DATE_RANGE_CROSS_MONTH` startDate/endDate 跨月 -- 缓存 key 仍 `yyyy-MM` 月级粒度（`startDate=2026-07-01&endDate=2026-07-31` 与 `month=2026-07` 命中同一 cacheKey，无碎片） -- 单测加 5 场景全过：onlyMonth / sameMonth / crossMonth / allBlank / invalidFormat - -## 行为对照 - -| 请求 | 修复前 | 修复后 | -|------|--------|--------| -| `?month=2026-07` | 200 | 200（不变） | -| `?startDate=2026-07-01&endDate=2026-07-31` | **500 DateTimeParseException** | **200**（与 month=2026-07 字段级 IDENTICAL） | -| `?startDate=2026-07-01&endDate=2026-08-15` | 500 | 200 + Result.code=410109 跨月业务错 | -| 无参数 | 500 | 200 + Result.code=410108 参数缺失业务错 | - -## 前端建议（可选，@mmg） - -后端已完整兼容 `startDate/endDate`，**前端不修也能用**。 - -但 `month` 是默认契约（detail.js / confirm.js 都用 month），建议小程序 `packages/order/supplement/supplement.js:531` 也改成传 `{month}`，与其他两处统一： - -```js -// 当前（OK 但不一致） -const data = await productApi.getPriceCalendar(this.data.product.id, { startDate, endDate }); - -// 建议（与 detail.js / confirm.js 一致） -const month = startDate ? startDate.substring(0, 7) : formatTime(new Date(), 'YYYY-MM'); -const data = await productApi.getPriceCalendar(this.data.product.id, { month }); -``` - -非紧急，看你方便。 - -## 调用方对照（仓库 grep 全 3 处） - -- `packages/product/core/detail/detail.js:1319` 传 `{month}` ✅ -- `packages/order/confirm/confirm.js:526` 传 `{month, tierSeq}` ✅ -- `packages/order/supplement/supplement.js:531` 传 `{startDate, endDate}` ✅（后端已兼容，建议改 month 但不强制） - -## 验证 - -- 单测 67/67 全过 -- 本地 product-v2:8083 直连 round-trip 4 场景全通过（含字段级 IDENTICAL 等价性证据） -- 测试服部署后会再次 round-trip 一次 diff --git a/changelogs/2026-05/07_fix_order_traveler_cert_validate.md b/changelogs/2026-05/07_fix_order_traveler_cert_validate.md deleted file mode 100644 index b4f3e2d..0000000 --- a/changelogs/2026-05/07_fix_order_traveler_cert_validate.md +++ /dev/null @@ -1,183 +0,0 @@ -# 订单出行人证件验证: admin 端补接口 + 前端必须改 URL/method/参数 - -> **服务**: hl-order-service-v2 (端口 8084) -> **PR**: #1798 (已合并 dev, 待部署 prod) -> **Issue**: #1797 -> **日期**: 2026-05-07 -> **影响范围**: 管理后台 出行人证件验证弹窗（蒋雨莲所在订单页） -> **@ 前端**: mmg - ---- - -## ⚠️ 关键变化（必须改前端） - -prod 弹窗 "证件验证未通过 · 蒋雨莲：接口不存在: POST /admin/auth/cert/validate" 是因为 **`POST /admin/auth/cert/validate` 后端从未实现过**（五重证据：代码 0 命中 / git 全历史 0 命中 / changelog 0 命中 / 需求文档 0 命中 / AuthController 全部 13 个 mapping 无 cert）。 - -后端**新增**正确接口： - -``` -GET /admin/order/{orderId}/travelers/validate -``` - -前端必须把"逐个 traveler 调 cert/validate"的循环逻辑**整段删掉**，改为按 orderId 一次性校验：URL 变 / method 由 POST 改 GET / 参数由 traveler body 改 path orderId。 - ---- - -## 一、背景 - -弹窗触发动作（疑似锁单/支付/确认行程前置校验）应该一次性把订单内全部出行人验证一次，而不是循环逐人。后端早就有 `GET /internal/order/traveler/validate/{orderId}` 给 payment-service Feign 调，本次只是在 admin 端薄包装一层让前端可以直调。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 校验订单出行人证件信息 | GET | `/admin/order/{orderId}/travelers/validate` | **新增** | 替换前端误调的 `POST /admin/auth/cert/validate` | - ---- - -## 三、接口详情 - -### 1. 校验订单出行人证件信息 `GET /admin/order/{orderId}/travelers/validate` - -**Service**: 复用已有 `OrderTravelerService.validateAndReturnVO(orderId)`（与 internal 接口完全对齐） -**VO**: `TravelerValidationVO` - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------|------| -| orderId | Path | Long | ✅ | 雪花 ID | 订单 ID | - -#### 出参 `Result<TravelerValidationVO>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| valid | Boolean | 全部出行人证件信息是否合规 | -| travelerCount | Integer | 出行人数量 | -| errors | `List<String>` | 校验失败明细（中文消息），合规时为空数组 | - -#### 请求示例 - -``` -GET /admin/order/123456789/travelers/validate -Authorization: Bearer <admin_token> -``` - -#### 响应示例（合规） - -```json -{ - "code": 200, - "message": "成功", - "data": { - "valid": true, - "travelerCount": 2, - "errors": [] - }, - "success": true -} -``` - -#### 响应示例（不合规） - -```json -{ - "code": 200, - "message": "成功", - "data": { - "valid": false, - "travelerCount": 2, - "errors": [ - "蒋雨莲：身份证号格式错误", - "张三：护照有效期已过" - ] - }, - "success": true -} -``` - ---- - -## 四、契约约束与正确调用方式 - -### ✅ 正确 / ❌ 错误 调用对照 - -| 场景 | 调用 | -|------|------| -| ✅ 一次性按订单校验全部出行人 | `GET /admin/order/{orderId}/travelers/validate` | -| ❌ 循环逐人调 cert/validate | `POST /admin/auth/cert/validate` × N（接口不存在 404） | - -### 前端代码改动指引 - -**旧代码（删除）**： -```js -for (const t of travelers) { - await http.post('/admin/auth/cert/validate', t) // ❌ 接口不存在 -} -``` - -**新代码**： -```js -const { data } = await http.get(`/admin/order/${orderId}/travelers/validate`) -if (!data.valid) { - // 弹窗显示 data.errors 即可 - showCertValidationDialog(data.errors) -} -``` - -错误明细 `errors: List<String>` 已经包含中文姓名 + 错误原因，前端不需要再拼姓名前缀。 - ---- - -## 五、数据库行为 - -只读校验，**不写库**。 - ---- - -## 六、边界行为 - -- orderId 不存在 → 服务端 BusinessException → `Result.code != 200` + 中文 message -- 订单存在但 0 个出行人 → `valid=false, travelerCount=0, errors=["订单尚未添加出行人"]` -- 未登录 → 网关 401 拦截 -- 下游服务降级 → 暂不需要 fallback，service 内部不依赖外部服务 - ---- - -## 七、不影响范围 - -- **仅影响**: 管理后台出行人证件验证弹窗（前端 hl-ui mmg 维护） -- **零影响**: - - 小程序端出行人列表 / 添加 / 编辑 - - admin 端出行人增删改 (`/admin/order/{orderId}/travelers/**`) - - payment-service 内部 Feign 调用的 `/internal/order/traveler/validate/{orderId}` 保持不变 - - 历史数据零变更 - ---- - -## 八、测试环境已验证 - -后端单测 3 用例全绿（mockMvc 真路径 dispatch）： -- `validate_orderComplete_returnsSuccessVO` ✓ -- `validate_orderIncomplete_returnsIncompleteVO` ✓ -- `validate_invalidOrderId_serviceThrows_exposedAsBusinessError` ✓ - -测试服 admin token round-trip：待 PR #1798 部署到测试服后 /@qa 角色验证（24h 内回贴 curl 输出）。 - ---- - -## 九、相关历史 PR - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| 无 | 无 | 后端从未约定 `POST /admin/auth/cert/validate` 接口 | -- | -| **本 PR #1798** | **#1797** | 新增 `GET /admin/order/{orderId}/travelers/validate` | ✅ 最新 | - ---- - -## 十、相关文档 - -- 关联 Issue: [wx/HL#1797](https://git.1814.love:8443/wx/HL/issues/1797) -- 关联 PR: [wx/HL#1798](https://git.1814.love:8443/wx/HL/pulls/1798) diff --git a/changelogs/2026-05/07_fix_order_v2_date_range_filter_three_layers.md b/changelogs/2026-05/07_fix_order_v2_date_range_filter_three_layers.md deleted file mode 100644 index fe9e6a9..0000000 --- a/changelogs/2026-05/07_fix_order_v2_date_range_filter_three_layers.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -date: 2026-05-07 -type: backend-fix -module: hl-order-service-v2/order+refund -priority: high -notify: ["@mmg"] -status: deployed-pending -restart_service: hl-order-service-v2 -gitea_pr: 1804 -gitea_issue: 1791 -related_cases: [DD-004, DD-005, TK-004] ---- - -# 订单/退款列表日期范围筛选无效 — 三层补字段 - -## 现象（DD-004 / DD-005 / TK-004） - -测试报告： -- 订单列表选起止日期 → 无法筛选 -- 订单列表多条件组合 → "日期还是有问题" -- 退款列表多条件组合 → "无" - -`/@bug` round-trip 极端测试 1900 vs 2099 vs 默认三组 total 都 29 一致 → 日期参数被静默丢弃。 - -## 修复 - -PR #1804 已合并 dev。三层补字段： - -| 层 | 文件 | 改动 | -|----|------|------| -| VO | OrderPageReqVO + RefundApplicationPageReqVO | 加 `createTimeStart` / `createTimeEnd` (LocalDateTime + @DateTimeFormat) | -| Service | OrderListQueryService.listAdminOrders | 透传两个新参数到 mapper | -| Mapper | OrderInfoMapper.selectAdminPage / RefundApplicationMapper.selectPage | wrapper 加 `betweenIfPresent(OrderInfo::getCreateTime, start, end)` | - -`betweenIfPresent` 智能退化：双边都给 = BETWEEN，只给 start = >= start，只给 end = <= end，都空跳过。 - -## 前端调用（@mmg） - -### 订单列表 - -```js -// 接口：GET /admin/order/page -GET /admin/order/page?createTimeStart=2026-04-01T00:00:00&createTimeEnd=2026-04-30T23:59:59&page=1&pageSize=10 -``` - -注意： -- 字段名：`createTimeStart` / `createTimeEnd`（驼峰，跟之前 status 字段一致） -- 格式：ISO 8601 DateTime（`2026-04-01T00:00:00`） -- 时区：服务端 `+08:00`，前端传字符串不带时区由后端 LocalDateTime 解析 - -### 退款列表 - -```js -// 接口：GET /admin/refund/application/page -GET /admin/refund/application/page?createTimeStart=...&createTimeEnd=...&page=1&pageSize=10 -``` - -### 不传日期时 - -向后兼容，不传 `createTimeStart` / `createTimeEnd` 行为完全不变（既有调用零影响）。 - -## 重启服务 - -`hl-order-service-v2` 部署测试服后即可。 - -## 验收 - -- [ ] 订单列表传日期 → 数据按范围筛选 -- [ ] 退款列表传日期 → 同样工作 -- [ ] 不传日期 → 全量返回（向后兼容） -- [ ] 跨年 / 单边 / 边界 各 case 正常 - -## 关联工单 -Gitea #1791 已 Closes 关闭。 diff --git a/changelogs/2026-05/07_fix_order_v2_edit_deposit_unchanged_skip_validation.md b/changelogs/2026-05/07_fix_order_v2_edit_deposit_unchanged_skip_validation.md deleted file mode 100644 index b7ae066..0000000 --- a/changelogs/2026-05/07_fix_order_v2_edit_deposit_unchanged_skip_validation.md +++ /dev/null @@ -1,107 +0,0 @@ -# 编辑订单接口: depositAmount 等值视为未改, 跳过 PENDING_PAY 状态校验 - -> **服务**: hl-order-service-v2 (端口 8084) -> **PR**: #1827 (已合并 dev, 待部署 prod) -> **Issue**: #1826 -> **日期**: 2026-05-07 -> **影响范围**: 管理后台「编辑订单 → 出行人信息」tab 添加/修改出行人 -> **@ 前端**: mmg - ---- - -## ⚠️ 关键信息（前端无需改动） - -后端做了**兼容性放宽**，前端可以**保持现状**继续把整 form 字段（含基本信息 tab 回显的 `depositAmount` 原值）一起 PUT 上来。 - -**不再需要前端区分「修改了金额」与「没修改金额」** — 后端会自动比较请求值与订单当前值，等值视为未改，跳过订金状态/上下界校验。 - ---- - -## 一、背景 - -后台「订单详情 → 编辑订单」弹窗在「出行人信息」tab 点「添加出行人」并提交时，对**非 PENDING_PAY** 状态订单（已分配定制师 / 已支付订金 / DEPOSIT_PAID 等）报错： - -> 仅待支付状态可修改订金金额（errorCode 502101） - -用户实际**没修改订金**，只是在添加出行人。根因：前端弹窗一次性 PUT 全 form，把基本信息 tab 中回显的 `depositAmount` 原值带回；后端 `OrderFieldEditService.adminEditOrder` 见 `depositAmount != null` 即强制校验 `PENDING_PAY`，无法区分「未改」vs「传了原值」。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 管理端编辑订单 | PUT | `/admin/order/{orderId}` | **行为放宽（向后兼容）** | depositAmount 与订单当前值相等时跳过校验，业务规则保留 | - ---- - -## 三、新行为定义 - -| 入参 `depositAmount` | 订单当前 `depositAmount` | 订单状态 | 行为 | -|---|---|---|---| -| `null` 或不传 | 任意 | 任意 | 不进入订金分支，无影响（原行为，未变） | -| 非 null，与当前相等 (`compareTo == 0`) | 非 null | 任意（含非 PENDING_PAY） | ✅ **新**：等值短路，整段订金校验+写入跳过；timeline 不记"订金"变更 | -| 非 null，与当前不等 | 任意 | `!= PENDING_PAY` | ❌ 502101 "仅待支付状态可修改订金金额"（保留） | -| 非 null，与当前不等 | 任意 | `PENDING_PAY` | 走原 3 项上下界校验（>0、≤总价），合法则落库 | -| 非 null | `null`（从未设过订金） | 任意 | 走原校验（不视为"未变"，防初始化场景被绕过） | - -`compareTo` 不是 `equals`：`100.00` 与 `100` 视为相等（scale 不同 OK）。 - ---- - -## 四、前端建议（可选） - -前端**无需改动**，下面只是建议性优化（不做也无影响）： - -### 选项 A（推荐继续保持）：整 form PUT -继续把所有字段一起 PUT，后端兼容。 - -### 选项 B（可选优化）：仅传变更字段 -只在用户真的修改 depositAmount 时才把它放进请求 body，其他字段同理。这样请求体更小，但**与本 BUG 修复无关**，纯优化。 - ---- - -## 五、数据库行为 - -只读比较，等值时**不写库**、不记 timeline、不发任何下游事件。 - -不等时按原逻辑：UPDATE `order_info.deposit_amount` + timeline 写"订金(¥xxx)"。 - ---- - -## 六、边界行为 - -- `depositAmount=null` 不传 → 不进分支，无影响 -- `depositAmount` 等于当前值（任意状态） → 跳过校验，正常返回 -- `depositAmount` 真改新值 + 非 PENDING_PAY → 仍报 502101 -- `depositAmount` 真改新值 + PENDING_PAY + ≤0 → 报 502102 -- `depositAmount` 真改新值 + PENDING_PAY + 超总价 → 报 502103 -- `depositAmount` 真改新值 + PENDING_PAY + 合法值 → 200 落库 - ---- - -## 七、不影响范围 - -- **仅影响**: `PUT /admin/order/{orderId}` 一个接口的订金分支 -- **零影响**: - - 独立订金更新接口（如有，本次未动） - - 小程序端订单编辑（不走该 service 方法） - - 其他字段（联系人、出发日期、人数、备注、出行人等）所有逻辑不变 - - 其他状态校验（EDIT_STATUS_INVALID / EDIT_ORDER_LOCKED）不变 - - 历史数据零变更 - ---- - -## 八、测试环境已验证 - -- 后端单测 71/71 全绿，新增 `adminEditOrder_depositAmountSameValueOnNonPendingPay_shouldNotThrow` 覆盖 PAID + 同值场景 -- 反例（PAID + 改新值仍 502101）已被现有 `adminEditOrder_depositAmountOnNonPendingPay_throwsBusinessException` 覆盖 -- 测试服客观复现 BUG 现象（orderId `2052213192926392321` status=DEPOSIT_PAID 传 depositAmount=0.01 等值仍 502101）—— 修复部署后该请求应返回 200 -- 修复版本 round-trip：本地受 `IpUtils` 类缺失（与本 BUG 无关的基础设施问题）阻塞，待测试服部署 dev 后由管理者补验 - ---- - -## 九、相关文档 - -- 关联 Issue: [wx/HL#1826](https://git.1814.love:8443/wx/HL/issues/1826) -- 关联 PR: [wx/HL#1827](https://git.1814.love:8443/wx/HL/pulls/1827) diff --git a/changelogs/2026-05/07_fix_order_v2_work_order_create_workorderno_orderno.md b/changelogs/2026-05/07_fix_order_v2_work_order_create_workorderno_orderno.md deleted file mode 100644 index 255ea57..0000000 --- a/changelogs/2026-05/07_fix_order_v2_work_order_create_workorderno_orderno.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -date: 2026-05-07 -type: backend-fix -module: hl-order-service-v2/work-order -priority: high -notify: ["@mmg"] -status: deployed-pending -restart_service: hl-order-service-v2 -gitea_pr: 1803 -gitea_issue: 1787 -related_cases: [GD-001] ---- - -# 工单新增漏 setWorkOrderNo / setOrderNo + 清理 title 死字段 - -## 现象（GD-001） - -``` -POST /admin/order/work-order -Body: {"orderId":1,"type":"OTHER","description":"...","priority":"NORMAL"} -响应: {"code":400,"message":"字段【work_order_no】未填写，请填写后重试"} -``` - -## 修复 - -PR #1803 已合并 dev。改动： - -1. `WorkOrderService.create()` 新增 `generateWorkOrderNo()` 私有方法，格式 `WO + yyyyMMddHHmmss + 4位随机`（20 字符），落库前 set 到 entity -2. 同时 `setOrderNo(order.getOrderNo())` 拷贝订单号 -3. 删除 `CreateWorkOrderRequest.title` 死字段（DDL/entity 没列） -4. 删除 `WorkOrderVO.title` 死字段，新增 `workOrderNo` 字段（响应里返工单号给前端） -5. `sql/work_order.sql` `type` COMMENT 对齐枚举（`CHANGE/COMPLAINT/SUPPLEMENT/OTHER`） - -## 前端配合（@mmg） - -### 1. 请求 body 不再传 title - -之前如果前端传了 title，会被静默吞掉（无 setter）。现在 DTO 删了 title 字段，传过来会被 Jackson 忽略（项目 FAIL_ON_UNKNOWN_PROPERTIES=false），不影响业务但建议清理。 - -### 2. 响应 body 多了 workOrderNo 字段 - -工单列表/详情响应现在包含： - -```json -{ - "id": "2052278173260824577", - "workOrderNo": "WO20260507150123ABCD", // ← 新增字段 - "orderNo": "HL26050700001", // ← 新增字段 - "orderId": "...", - "type": "OTHER", - "status": "PENDING", - ... -} -``` - -前端工单列表/详情页可以展示这两个字段。 - -## 重启服务 - -`hl-order-service-v2` 已合并到 dev，运维部署测试服后即可使用。如本地启动需重启 `hl-order-service-v2`。 - -## 验收 - -- [ ] 测试服部署后 admin token POST 工单 → 返 code:200 + workOrderNo + orderNo -- [ ] 前端工单列表展示工单号 -- [ ] 工单详情展示工单号 + 订单号 - -## 关联工单 -Gitea #1787 已 Closes 关闭。 diff --git a/changelogs/2026-05/07_fix_product-v2_banner_productline_to_theme.md b/changelogs/2026-05/07_fix_product-v2_banner_productline_to_theme.md deleted file mode 100644 index 83c429e..0000000 --- a/changelogs/2026-05/07_fix_product-v2_banner_productline_to_theme.md +++ /dev/null @@ -1,88 +0,0 @@ -# 修复轮播图「链接目标=主题」无数据 + 字典/菜单产品线统一改名为主题 - -**日期**: 2026-05-07 -**类型**: 后端 BUG 修复 + DB 文案改名（前端有少量配合改动） -**模块**: hl-product-service-v2 + hl-user-service（DB migration） -**关联**: Issue #1836 / PR #1837 (已合并 dev) -**通知**: @mmg - ---- - -## 后端修了什么 - -### 1. BUG 修复 — 轮播图编辑「链接类型=产品线」点击「链接目标」弹窗显示"无数据" - -**根因**：`ProductLinePageReqVO.productType` 字段 `String` 类型，Mapper 用 `eqIfPresent` 拼 `=` 等值匹配。前端 `EditModal.vue` 发的请求是 `?productType=CORE,GROUP`（逗号分隔多值），后端按字面值 `'CORE,GROUP'` 做 `=` 比较 → 永远 0 条。 - -**修法**：保留 `productType` (String) 兼容单值，新增 `getProductTypeList()` 拆分逗号；Mapper 改 `inIfPresent`。 -- 单值 `?productType=CORE` 兼容仍正常（拼出 `IN ('CORE')` 等价 `= 'CORE'`） -- 多值 `?productType=CORE,GROUP` 拼出 `IN ('CORE','GROUP')` 返回正确结果 - -### 2. DB 文案改名 — 用户原话："产品线（字典）改为主题" - -| 表 | 改了什么 | 改前 | 改后 | -|---|---|---|---| -| `sys_dict_data` | dict_type=`banner_link_type`, dict_value=`PRODUCT_LINE` 的 dict_label | 产品线 | **主题** | -| `sys_menu` | menu_id=520 模块名 | 产品线管理 | **主题管理** | -| `sys_menu` | menu_id=5201 按钮 | 新增产品线 | **新增主题** | -| `sys_menu` | menu_id=5202 按钮 | 编辑产品线 | **编辑主题** | -| `sys_menu` | menu_id=5203 按钮 | 删除产品线 | **删除主题** | - -### 3. 内部命名保持不变（API 契约稳定） - -- 类名 `ProductLine*` / 表名 `product_line` / URL `/admin/product/line/**` / 字段 `lineId/productType` / 枚举 value `PRODUCT_LINE` 全部不动 -- 前端调 API 不需要任何改动，请求/响应字段名 0 变化 - ---- - -## 前端要做什么（可选 / 渐进式） - -后端 + DB 改完后，前端**理论上无需任何代码改动**就能看到新文案： - -- 字典 `banner_link_type` 的 label 通过 `getDictDataByType` 接口加载，前端 `<el-option>` 显示的是 `dictLabel`，部署后自动显示「主题」 -- 后台菜单从 `sys_menu` 加载，部署后自动显示「主题管理」+「新增/编辑/删除主题」按钮 -- 前端字典 store（`hl-ui/src/stores/dict.js` 含 `pinia-plugin-persistedstate`）做了 localStorage 持久化，**用户首次进入会读旧的"产品线"label**，需要硬刷新（Ctrl+Shift+R）或退出重登才会拿到新字典 - -### 但这些 .vue 里的硬编码"产品线"中文，建议 mmg 一并改为"主题"统一术语 - -参考之前 changelog `07_frontend_notice_topic-filter-empty.md` 已经在叫"主题"。grep 全仓 `"产品线"` 中文字面量一处一处对： - -| 文件 | 大约位置 | 当前 | 建议改为 | -|---|---|---|---| -| `hl-ui/src/views/mp-config/home/banner/EditModal.vue` | ~333 行 `label:'产品线'` | 产品线 | 主题 | -| `hl-ui/src/views/product/line/index.vue` | 页面标题 / 表头 | 产品线管理 | 主题管理 | -| `hl-ui/src/views/product/list/index.vue` | 关联显示 | 产品线 | 主题 | -| 其他 | 表头/按钮/placeholder/tooltip | "产品线" | "主题" | - -预计涉及 14 个 .vue 文件（前期 Explore 调研结果），都属用户可见硬编码文案。 - -### 时间紧不改也能用 - -后端 + 字典 + 菜单都已经改名，前端 .vue 硬编码"产品线"不改的话，会出现"主题列表里某些 label 写产品线"这种术语混乱，但功能完全正常。 - ---- - -## round-trip 验证（部署完成后） - -合并后 webhook 自动部署到测试服 `https://api.test.1814.love:9443`。验证清单： - -```bash -TOKEN=$(cat /d/work2/HL/.tmp/admin_token.txt | tr -d '\n\r ') - -# 1. 多值过滤已修复（之前 total=0，现在应 >0） -curl -k -s "https://api.test.1814.love:9443/admin/product/line/list?status=ACTIVE&productType=CORE,GROUP" \ - -H "Authorization: Bearer $TOKEN" | python -c "import json,sys; d=json.load(sys.stdin); print('total=',d['data']['total'])" - -# 2. 单值兼容 -curl -k -s "https://api.test.1814.love:9443/admin/product/line/list?productType=CORE" \ - -H "Authorization: Bearer $TOKEN" | python -c "import json,sys; d=json.load(sys.stdin); print('total=',d['data']['total'])" - -# 3. 字典 banner_link_type label 改名 -curl -k -s "https://api.test.1814.love:9443/internal/dict/data?dictType=banner_link_type" | grep -o '"PRODUCT_LINE"[^}]*"dictLabel":"[^"]*"' -# 期望: "PRODUCT_LINE" ... "dictLabel":"主题" -``` - -管理后台手动验证： -- [ ] 轮播图编辑「链接类型」下拉显示「主题」 -- [ ] 选「主题」后「链接目标」弹窗能加载列表（不再"无数据"） -- [ ] 后台左侧菜单显示「主题管理」+ 三个按钮「新增/编辑/删除主题」 diff --git a/changelogs/2026-05/07_fix_product_basic_save_agency_id_missing.md b/changelogs/2026-05/07_fix_product_basic_save_agency_id_missing.md deleted file mode 100644 index 3a3376e..0000000 --- a/changelogs/2026-05/07_fix_product_basic_save_agency_id_missing.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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 范围扩散。 diff --git a/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md b/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md deleted file mode 100644 index df51b51..0000000 --- a/changelogs/2026-05/07_fix_product_equipment-template-bind-product-line.md +++ /dev/null @@ -1,107 +0,0 @@ -# 后端 BUG 修复 — 装备建议组合 绑定层级 product_supplement → product_line - -**日期**: 2026-05-07 -**类型**: 后端 BUG 修复（admin 后台 + 小程序） -**模块**: 产品管理（产品线 / 主题）+ 装备建议组合 -**通知**: @mmg -**关联**: PR #1782 + PR #1786 (hotfix)，Closes #1777 -**测试服**: dev 已部署 + round-trip 验收 PASS -**前端是否需改动**: ✅ **必改**（API 契约 break，前后端必须同步上线） - ---- - -## 背景 - -PR #1768（2026-05-06）实现「装备建议组合模板 + 产品绑定」时，把 `equipment_template_id` 加在 `product_supplement` 表（每个版本独立绑一个模板）。 - -业务正确做法：装备需求由目的地、季节、产品类型决定 —— 这些都是**产品线（主题）**层级属性。同主题下不同版本（如「短途版」「南线经典」）只在行程时长、价格、班期上差异，装备需求几乎一致。一主题一份装备建议是合理粒度，运营不必每开新版本都重选模板。 - -PR #1782 把绑定层级**从 `product_supplement`（版本）下沉到 `product_line`（主题）**。 - ---- - -## 前端改动清单 - -### 1. 主题（产品线）创建/编辑表单 — 新增「装备建议组合」字段 - -| 项 | 值 | -|----|-----| -| 字段名 | `equipmentTemplateId` | -| 类型 | `Long`（前端传字符串数字也接受） | -| 必填 | 否（可选） | -| label | 装备建议组合 | -| 控件 | 下拉框（搜索/清除） | -| 选项数据 | `GET /admin-api/admin/equipment-template/enabled` （已就绪，返 `EquipmentTemplateSimpleRespVO[]`，含 `templateId/name`） | -| 表单回显 | `GET /admin-api/admin/product/line/{lineId}` 返回的 `equipmentTemplateId` 字段 | -| 保存接口 | `POST /admin-api/admin/product/line`（创建/更新统一入口） body 含 `equipmentTemplateId`（取消绑定传 `null`，已通过 hotfix PR #1786 修复 null 落库 BUG） | - -特殊提示展示：当 `equipmentTemplateId != null && equipmentTemplateName == null` 时（模板被软删），展示提示「该装备建议组合已删除，请重新选择」。 - -### 2. 版本编辑 Step5 表单 — 移除「装备建议组合」字段 - -`ProductSupplementSaveReqVO.equipmentTemplateId` 已删；`/admin-api/admin/product/{productId}/step5` 提交即使带上该字段也会被静默忽略。请前端表单**直接移除该字段**，避免误导用户以为版本级也能配。 - -### 3. 版本详情 — `supplement.equipmentTemplateId/Name` 已删 - -`/admin-api/admin/product/{productId}` 详情接口的 `supplement` 节点不再返 `equipmentTemplateId/Name`。如版本详情页面需要展示装备建议，从主题（产品线）详情接口拿（`GET /admin-api/admin/product/line/{lineId}`）。 - -### 4. 模板 CRUD 入口位置（建议） - -当前位置：「产品 → 主题列表」工具栏「装备建议组合」按钮（PR #1768 引入）。 - -建议新位置：「系统管理 → 模板管理 / 数据字典」之类全局入口（理由：装备建议组合是全局共享资源，不挂在任何产品维度下；与「合同方案」「保险方案」「行程保障模板」「温馨提示」类一致）。 - -具体放哪由前端拍板，不影响后端。 - -### 5. 小程序端 — 透明（无需改） - -`GET /mp/product/{productId}` 详情接口的 `equipmentList` 字段语义不变；后端实现已切到 `product → line → equipmentTemplateId`，三态规则保留： -- 主题绑模板 → 返模板 items -- 主题未绑 / 模板软删 → fallback `supplement.equipmentList`（版本自定义） - ---- - -## API 字段差异（前后端对账） - -### 新增字段（主题相关 VO） - -| 接口 | VO | 字段 | 类型 | 说明 | -|------|-----|------|------|------| -| `POST/PUT /admin/product/line` | `ProductLineSaveReqVO` | `equipmentTemplateId` | `Long` 可选 | 装备建议组合模板 ID；null 取消绑定 | -| `GET /admin/product/line/{id}` | `ProductLineRespVO` | `equipmentTemplateId` | `Long` | 同上 | -| `GET /admin/product/line/{id}` | `ProductLineRespVO` | `equipmentTemplateName` | `String` | 模板名称回显（模板软删时为 null） | -| `GET /admin/product/line/list` | `ProductLineRespVO`（列表项同 VO） | 同上两字段 | — | 已批量回填（不 N+1） | - -### 删除字段（版本相关 VO） - -| 接口 | VO | 字段 | 处理 | -|------|-----|------|------| -| `POST/PUT /admin/product/{id}/step5` | `ProductSupplementSaveReqVO` | `equipmentTemplateId` | **删除**；前端表单需移除 | -| `GET /admin/product/{id}` | `ProductDetailRespVO.SupplementVO` | `equipmentTemplateId` | **删除** | -| `GET /admin/product/{id}` | `ProductDetailRespVO.SupplementVO` | `equipmentTemplateName` | **删除** | - ---- - -## 后端验收实测（测试服 dev round-trip PASS） - -| 验收项 | 实测 | -|--------|------| -| 网关 `/admin/equipment-template/**` 路由 | hl-gateway dev 已部署 | -| 取消绑定 (`equipmentTemplateId=null`) 落库 | hotfix PR #1786 后 PASS（FieldStrategy.IGNORED 注解） | -| 列表回填 templateName | PASS（中文非 null） | -| mp 详情三态 fallback | PASS | -| 模板更新反向清缓存 | PASS（前后两次 GET 反映 items 变化） | -| 模板被引用拒绝软删 | PASS（code 440102） | -| 不存在 templateId 校验 | PASS（code 440103） | - ---- - -## 上线时序（前后端协同） - -后端 dev 已合 + 测试服已部署 + round-trip 通过。**前端必须同步上线**，否则： -- 主题创建/编辑表单缺「装备建议组合」字段 → 运营无法配置主题级装备建议 -- 版本编辑 Step5 表单仍显示「装备建议组合」字段 → 提交时被静默忽略，误导 - -正式服由运维管理员部署 hl-product-service-v2 + hl-gateway（PR #1782 + PR #1770）+ hl-ui（前端发版后）。 - -@mmg 请评估前端改动量并约一个上线时间。 diff --git a/changelogs/2026-05/07_fix_refund_appeal_oa_submission.md b/changelogs/2026-05/07_fix_refund_appeal_oa_submission.md deleted file mode 100644 index b20ab66..0000000 --- a/changelogs/2026-05/07_fix_refund_appeal_oa_submission.md +++ /dev/null @@ -1,54 +0,0 @@ -# fix(refund): 退款申诉补企微 OA 提交 - -**PR**: [#1774](https://git.1814.love:8443/wx/HL/pulls/1774) **Issue**: [#1773](https://git.1814.love:8443/wx/HL/issues/1773) **合并**: 2026-05-07 - -通知对象: 无前端配合(后端纯内部修复 + 运维补 nacos) - ---- - -## 后端修了什么 - -mp 端「申诉(appeal)」/「直接申诉(directAppeal)」之前**只写 DB status=APPEALING,完全没调企微 OA 提交**,审批人永远收不到通知,DB 永久卡死。 - -回调侧(`ApprovalEventHandler:155` 按 template-id 路由)+ DTO 字段 + user-service `buildRefundAppealControls` 出口控件构建 + nacos 配置 key 全已就绪,只缺 order-service 出口侧调用闭环。 - -PR #1774 补的: - -- `RefundApplyService.submitAppealOa(app)` — 申诉模板 7 字段渲染 + Feign 提交,失败抛 RuntimeException 让 LocalEvent 兜底重试 -- `RefundAppealService.appeal/directAppeal` afterCommit 调 + 失败 publish `RETRY_SUBMIT_REFUND_APPEAL_OA` LocalEvent -- `RetrySubmitRefundAppealOaHandler` — 复用 `RetrySubmitRefundOaHandler` 模式,幂等跳过(status≠APPEALING 或 approvalNo 非空) -- `RefundAppealBackfillJob` — `@EventListener(ApplicationReadyEvent)` 启动一次性扫 + 补发卡死的「僵尸申诉」(分布式锁 + 单条失败不阻塞) - -## 前端无需改动 - -`/internal/mp/order/refund/{applicationId}/appeal` 和 `/internal/mp/order/{orderId}/direct-appeal` 接口签名 / VO / 字段 0 改动。前端 UI 不变。 - -## 部署依赖(运维侧 nacos 配置) - -**P0 - 必须补齐才能生效**(配置缺失时 `submitAppealOa` 静默 return 不阻塞业务): - -```yaml -approval: - refund-appeal: - template-id: 3WNge6AGZK2Pq4JwoCAkRXYwaTidZkrXCs9DsiSz - control-ids: - customer-name: <从企微管理端「订单退款申诉」模板编辑页拿> - customizer-name: <同上> - product-type: <同上> - order-no: <同上> - order-date: <同上> - departure-date: <同上> - reason: <同上> -``` - -三套 namespace 都要补:dev / test / prod。 - -## 历史卡死单处理 - -服务重启时 `RefundAppealBackfillJob` 会自动扫 `status=APPEALING AND approval_no IS NULL` 的"僵尸申诉",逐条调 `submitAppealOa` 补发到企微 — 用户无感,运营不需要让用户重新点申诉按钮。 - -## 测试 - -- 单测 22 个新增,4 个测试文件 51/51 全绿(`RefundApplyServiceTest +6 / RefundAppealServiceTest +3 / RetrySubmitRefundAppealOaHandlerTest 7 / RefundAppealBackfillJobTest 6`) -- 本地 round-trip 兜底(4 服务联动 + 外部企微回调 30min 不可达,走「单测全绿 + 测试服真实 round-trip」路径) -- 测试服 round-trip 待 nacos 配置补齐后由管理者完成 diff --git a/changelogs/2026-05/07_fix_refund_apply_paidamount_npe.md b/changelogs/2026-05/07_fix_refund_apply_paidamount_npe.md deleted file mode 100644 index 4a772f2..0000000 --- a/changelogs/2026-05/07_fix_refund_apply_paidamount_npe.md +++ /dev/null @@ -1,62 +0,0 @@ -# fix(refund): mp 端 apply 接口 paidAmount=null 必 NPE - -**PR**: [#1783](https://git.1814.love:8443/wx/HL/pulls/1783) **Issue**: [#1780](https://git.1814.love:8443/wx/HL/issues/1780) **合并**: 2026-05-07 - -通知对象: 无前端配合(后端纯内部 fallback 修复) - ---- - -## 现象 - -正式环境 mp 端「申请退款」: 选退款类型 → 选退款原因 → 点「确认申请退款」 → 弹 toast `服务器内部错误 [NullPointerException]`。重现率 100%。所有 mp 端用户提交退款申请永远失败。 - -## 根因 - -mp 端 BFF 调 apply 接口的 `paidAmount/policyId/departureDate` 全链路永远为 null: - -1. `MpRefundController.applyRefund` Feign 调 `orderFeignClient.applyRefund(userId, userName, orderId, body)` 不传这 3 个参数 -2. `MpOrderFeignClient.applyRefund` 签名也不声明这 3 个参数 -3. `InternalRefundController.apply` 三个 `@RequestParam(required=false)` 收到 null 后透传 service -4. `RefundApplyService.apply:151` 第一句 `paidAmount.compareTo(BigDecimal.ZERO) <= 0` → **NPE** - -PR #1311 当年只补了同文件 `previewRefund` (line 86-93) 的 fallback,漏了 `apply`,本次是 #1311 follow-up。 - -## 后端修了什么 - -`RefundApplyService.apply` 顶部加 14 行 fallback (与 `previewRefund` 现有模式 100% 镜像): - -```java -if (paidAmount == null || policyId == null || departureDate == null) { - OrderInfo fallbackOrder = orderInfoMapper.selectById(orderId); - if (fallbackOrder != null) { - if (paidAmount == null) paidAmount = fallbackOrder.getPaidAmount(); - if (policyId == null) policyId = fallbackOrder.getRefundPolicyId(); - if (departureDate == null) departureDate = fallbackOrder.getDepartureDate(); - } -} -if (paidAmount == null) { - throw new BusinessException(OrderRefundErrorCode.REFUND_NO_AMOUNT_AVAILABLE); -} -``` - -按「金额绝不信前端」原则,三参数始终以订单主表为权威。IDOR 校验(line 156)完整保留在 fallback 之后。 - -## 前端无需改动 - -`POST /mp/order/{orderId}/refund` 接口签名/请求体/响应 VO 0 改动。前端 UI 不变。 - -## 部署依赖 - -无 nacos / SQL / 第三方配置变更。直接部署即生效。 - -## 受影响范围 - -- mp 端「申请退款」(`POST /mp/order/{orderId}/refund`) — 修复后正常落库 + 触发审批 -- 不影响: 退款预览 / 退款详情 / 撤回 / 申诉 / 直接申诉 (这些路径未走 RefundApplyService.apply) - -## 验证 - -- 单测 29/29 全绿,新增 2 条覆盖 paidAmount=null 路径(订单存在 → fallback 成功 / 订单不存在 → BusinessException 而非 NPE) -- CR ✅ 通过 (NPE 真消除 / IDOR 不退化 / 字段映射一致) -- 测试服 dev 部署成功重启 (uptime 0:55, 跑 dev HEAD 含 PR #1783) -- prod round-trip 等运维部署后用户实测 diff --git a/changelogs/2026-05/07_fix_resource_scenic_offline_check_and_staff_phone_pattern.md b/changelogs/2026-05/07_fix_resource_scenic_offline_check_and_staff_phone_pattern.md deleted file mode 100644 index d996e52..0000000 --- a/changelogs/2026-05/07_fix_resource_scenic_offline_check_and_staff_phone_pattern.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -date: 2026-05-07 -type: backend-fix -module: hl-resource-service/scenic+staff -priority: low -notify: ["@mmg"] -status: deployed-pending -restart_service: hl-resource-service -gitea_pr: 1807 -gitea_issue: [1794, 1795] -related_cases: [JQ-011, RY-002] ---- - -# 景区下架引用校验 + 服务人员手机号格式校验 - -## 现象 - -- **JQ-011**：景区被产品引用时 admin 直接下架，无业务校验提示 -- **RY-002**：服务人员录入手机号格式校验缺失（`abc123` / `12345` 都能保存） - -## 修复 - -PR #1807 已合并 dev，两个工单合一个 PR。 - -### #1794 景区下架引用校验 - -`ScenicSpotService.updateStatus` + `batchUpdateStatus` 加 `productFeignClient.checkResourceInUse("SCENIC", id)`： -- 仅下架（STATUS_OFF）触发，上架不触发 -- 单个被引用 → 抛 `BusinessException(SCENIC_DISABLE_IN_USE, 产品名)`，message 含产品名（如"景区已被【XX 一日游】使用，请先解除关联"） -- 批量被引用 → 跳过+log.warn（与既有 approvalNo 跳过模式一致） - -### #1795 服务人员手机号校验 - -`StaffCreateRequest.phone` + `emergencyPhone` 加 `@Pattern(regexp = "^$|^1[3-9]\\d{9}$", message = "手机号格式不正确")`，`StaffUpdateRequest` 同样。 - -允许空字符串（phone 是非必填字段），非空必须符合 11 位手机号格式。 - -## 前端配合（@mmg） - -### 景区下架弹窗 - -下架接口现在可能返 errorCode `SCENIC_DISABLE_IN_USE`，前端可以 catch 这个错误码，弹窗提示用户解除关联： - -```js -try { - await offlineScenic(id) -} catch (e) { - if (e.code === xxxxx /* SCENIC_DISABLE_IN_USE 错误码 */) { - showDialog({ - title: '景区已被使用', - content: e.message, // 含产品名 - }) - } -} -``` - -### 服务人员手机号 - -前端可以增加同样的格式校验提供更好体验（同步反馈），但即使没加，后端会拦截并返业务码非 200。 - -## 重启服务 - -`hl-resource-service` 部署测试服后即可。 - -## 验收 - -- [ ] 关联中景区下架 → 业务码非 200 + 含产品名提示 -- [ ] 无关联景区下架 → 正常下架 -- [ ] 服务人员手机号 "abc" → 业务码非 200 -- [ ] 手机号 "13800138000" → 正常保存 -- [ ] emergencyPhone 同样校验 - -## 关联工单 -- Gitea #1794 已 Closes 关闭 -- Gitea #1795 已 Closes 关闭 - -## 备注：项目级遗留（建议另立工单跟踪，不在本 PR 范围） - -/@bug 顺手发现两个项目级问题，**不在本 PR 修复范围**： - -1. **8 个资源服务（hotel/scenic/activity/restaurant/staff/supplies/cost/vehicle）的 `updateStatus` 方法全部缺 `checkResourceInUse`**，本 PR 只修景区一个。其余 7 个建议 PM 决策是否扩大修复范围。 -2. **hl-resource-service 整体无字段加密**：`Staff.phone / emergencyPhone / 身份证号` 等敏感字段未挂 `EncryptTypeHandler`（grep `EncryptTypeHandler` 整模块零匹配）。 -3. **`ProductFeignFallbackFactory.checkResourceInUse` 降级返回空 list = fail-open**：product-service 真挂时景区会被偷偷下架。 - -以上 3 项建议 PM 评估优先级后另立 feat/refactor 工单。 diff --git a/changelogs/2026-05/07_fix_user_explore_category_detail_status_field.md b/changelogs/2026-05/07_fix_user_explore_category_detail_status_field.md deleted file mode 100644 index 90754d9..0000000 --- a/changelogs/2026-05/07_fix_user_explore_category_detail_status_field.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -date: 2026-05-07 -type: backend-fix -module: hl-user-service/explore-category -priority: medium -notify: ["@mmg"] -status: deployed-pending -restart_service: hl-user-service -gitea_pr: 1806 -gitea_issue: 1793 -related_cases: [ZT-006] ---- - -# 探索分类详情接口补 status 字段（前端称"主题列表"状态切换无效） - -## 现象（ZT-006） - -测试报告：admin 端切换探索分类（前端口语称"主题"）的上下架状态，**显示"编辑成功"但实际状态没变**。 - -## 根因 - -`ExploreCategoryDetailVO.java` **完全缺 `status` 字段**，导致 `ExploreCategoryService.toDetailVO` builder 也不 set status，前端 EditModal `status: data.status ?? 1` fallback 默认上线，用户切换的真实状态无法回显。 - -## 修复 - -PR #1806 已合并 dev。 - -1. `ExploreCategoryDetailVO` 加 `private Integer status;` 字段，@ApiModelProperty 含字典值说明 -2. `ExploreCategoryService.toDetailVO` builder 加 `.status(category.getStatus())` 一行 - -PUT 切换接口本身是正常的，问题只在 GET detail 不返 status。 - -## 前端配合（@mmg） - -### 1. 详情响应多了 status 字段 - -```json -GET /admin/explore/category/{id} -{ - "code": 200, - "data": { - "id": "...", - "name": "亲子游", - "iconUrl": "...", - "status": 1, // ← 新增字段（0=下架, 1=上架） - "sortOrder": 100, - ... - } -} -``` - -### 2. 前端建议改默认值 - -```js -// 错误（导致"切换无效"幻觉） -status: data.status ?? 1 // ❌ 后端返 null 时默认 1 - -// 正确（后端现在永远返字段，可以去掉 fallback） -status: data.status // ✅ 直接用后端字段 -// 或 -status: data.status ?? 0 // ✅ 兜底用 0（下架）更安全 -``` - -## 重启服务 - -`hl-user-service` 部署测试服后即可。 - -## 验收 - -- [ ] admin GET 探索分类详情 → 响应含 status 字段非 null -- [ ] 切换 status 后再次 GET → status 已变 -- [ ] 下架的分类 detail 返 0 不是 1 -- [ ] 前端编辑弹窗状态开关正确回显 - -## 数据修复（建议运营/QA 配合） - -BUG 期间用户切换状态可能有错位，运营可参考 BUG 报告里的审计 SQL 对照修： -`docs/tasks/20260507_bug_product_analysis.md`（仓库内）。 - -## 关联工单 -Gitea #1793 已 Closes 关闭。 - -## 顺手提醒（CP-006 不在本 PR） -测试报告里 CP-006 "产品筛选下拉框只有上/下架，适用小蒙马" 是**不同根因**（产品筛选选项不全），归到产品复核任务，不在本 PR 范围。 diff --git a/changelogs/2026-05/07_frontend_bug_contract_create_axios_and_snowflake_id.md b/changelogs/2026-05/07_frontend_bug_contract_create_axios_and_snowflake_id.md deleted file mode 100644 index 6f5464f..0000000 --- a/changelogs/2026-05/07_frontend_bug_contract_create_axios_and_snowflake_id.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -date: 2026-05-07 -type: frontend-bug -module: contract-generate -priority: high -notify: ["@mmg"] -status: pending -source: 测试用例汇总.xlsx (2026-05-07) + /@bug 实测 -related_cases: [HT-001] -gitea_issue_closed: 1788 ---- - -# 合同生成显示"网络错误" — 实为前端 axios 误判 + 雪花 ID 精度丢失 - -## 原始现象 - -测试用例 HT-001：合同生成报"网络错误"。 - -## /@bug 实测结论（admin 真 token round-trip） - -后端 `POST /admin/contract/create-by-scheme` HTTP **全部 200**，5 个 case 测试结果： - -| Case | 入参 | 业务 code | 含义 | -|------|------|-----------|------| -| A | DEPOSIT_PAID 订单+schemeId=3 | 510208 | 出行人未补全（业务校验，正确） | -| B | 订单+schemeId=`2046840448906940417`（19 位 Long） | 510205 | **前端把雪花 ID 序列化为 JS Number，后 4 位精度丢失** | -| C | CONFIRMED 订单+schemeId=3 | **200** | **生成成功**，contractId=2052278173260824577 | -| D | 不存在 orderId | 510207 | 订单不存在（正确） | - -**结论**：后端纯净，根因在前端两处。 - -## 根因 1：axios interceptor 误把业务码当 HTTP 5xx - -本项目 P0 铁律：**HTTP 始终 200，业务码在 `Result.code`**。 - -前端 axios interceptor 看到 `code:5xxxxx`（业务码格式 `xxxxxx` 6 位），可能误判为 HTTP 5xx 异常，统一显示"网络错误"，**用户根本看不到 body.message** 提示的真实业务原因（如"出行人未补全"）。 - -### 修复方向 - -```js -// 错误（推断）： -axios.interceptors.response.use(resp => { - if (String(resp.data.code).startsWith('5')) { - showToast('网络错误') // ❌ 业务码 510208 被误判为 5xx - throw new Error() - } - return resp.data -}) - -// 正确： -axios.interceptors.response.use(resp => { - const { code, message, data } = resp.data - if (code !== 200) { - showToast(message || `操作失败 (${code})`) // ✅ 显示后端真实 message - throw new BizError(code, message) - } - return data -}) -``` - -## 根因 2：雪花 ID schemeId 没字符串化 - -后端 schemeId 是 19 位 Long（雪花算法），最大值 `2^63-1 ≈ 9.22e18`。 -JS Number 精度上限 `Number.MAX_SAFE_INTEGER = 2^53-1 ≈ 9.007e15`。 - -19 位 Long 直接被 JS Number 接收会**丢失后 3-4 位精度**，发回后端的 ID 已经不是原值。 - -### 实测证据（case B） - -``` -原值: 2046840448906940417 -JS 后: 2046840448906940000 ← 后 4 位变 0 -后端: schemeId 不存在 → code:510205 -``` - -### 修复方向 - -```js -// 1. axios 配置 transformResponse 用 json-bigint 解析 -import JSONbig from 'json-bigint' -axios.defaults.transformResponse = [data => JSONbig.parse(data)] - -// 2. 或后端 Long 字段 @JsonSerialize(using = ToStringSerializer.class) -// → 但本项目历史决定，前端处理更省事 - -// 3. 或前端拿到 ID 后立即转 String，传回时也按 String 传 -const schemeId = String(resp.schemeId) // 显式字符串化 -``` - -类似已知坑：memory `feedback_http-200-check-business-code.md`、项目其他列表用雪花 ID 的地方都需要复检。 - -## 影响 - -- 合同生成完全无法触发（用户看到"网络错误"放弃） -- 间接影响所有调用合同接口的页面 - -## 验收（前端） - -- [ ] 合同生成失败时 toast 显示后端真实 message（如"出行人未补全"） -- [ ] CONFIRMED 订单 + 真实 schemeId → 合同生成成功（HTTP 200 + code:200） -- [ ] axios 全局检查：所有调用涉及雪花 ID 的接口（订单 ID/产品 ID/方案 ID/合同 ID）都按 String 处理 -- [ ] 业务码 5xxxxx 不再被误判为网络错误 - -## 关联工单 - -Gitea #1788 已关闭并留 closing comment（项目规则前端 BUG 不建工单）。 -完整分析报告：`docs/tasks/20260507_bug_contract_analysis.md` diff --git a/changelogs/2026-05/07_frontend_bug_contract_scheme_form_entry_missing.md b/changelogs/2026-05/07_frontend_bug_contract_scheme_form_entry_missing.md deleted file mode 100644 index 390ae78..0000000 --- a/changelogs/2026-05/07_frontend_bug_contract_scheme_form_entry_missing.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -date: 2026-05-07 -type: frontend-bug -module: contract-scheme -priority: medium -notify: ["@mmg"] -status: pending -source: 测试用例汇总.xlsx (2026-05-07) -related_cases: [HF-001] ---- - -# 合同方案新增找不到填写入口 - -## 现象 - -测试用例 HF-001 "正常新增合同方案"： - -> 步骤：1. 新增 → 2. 填写名称模板内容 → 3. 保存 -> 实际结果：**没找到相关的填写** - -## 推断方向（前端） - -可能是： -1. 合同方案管理菜单/路由缺失 -2. 菜单存在但点"新增"按钮没弹出表单 dialog -3. dialog 弹出来但内容空白（template 没渲染） - -## 后端确认 - -后端 hl-contract-service 的合同方案 admin 接口 **应当存在**（不然合同生成 HT-001 也会挂），具体接口路径可能是： - -- `POST /admin/contract/scheme/save`（按项目 SaveReqVO 命名习惯） -- `GET /admin/contract/scheme/page` - -如果后端接口缺失或路径变了，前端会找不到对应 API 来对接。 - -## 排查步骤 - -1. **检查 hl-ui 路由**：搜 `contract.*scheme` / `合同方案`，确认菜单项是否在 router 配置里 -2. **检查菜单权限**：admin RBAC 是否给当前账号开放了"合同方案"菜单 -3. **检查 dialog 表单组件**：是否引用了 `<ContractSchemeForm />` 但组件文件不存在/import 错路径 -4. **后端 API 确认**：在 hl-ui 的 api 目录搜 `contractScheme` 看有没有对接接口 - -## 关联 BUG - -跟 HT-001 "合同生成网络错误" 可能同源 — 如果合同方案根本无法新增，那合同生成也无法选择方案 → 必然失败。 - -后端排查时一并看一下。 - -## 影响 - -- 合同模板配置流程整条断 -- 阻塞 HT-001 合同生成 BUG 的修复闭环（合同生成依赖方案） - -## 验收 - -- [ ] 进入"合同配置 → 合同方案"菜单 -- [ ] 点击"新增"按钮看到弹窗 / 表单页 -- [ ] 填名称 + 模板内容 → 保存成功 -- [ ] 列表能看到新增的方案 -- [ ] HT-001 合同生成时能选到这个方案 diff --git a/changelogs/2026-05/07_frontend_bug_list_reset_button_requires_double_click.md b/changelogs/2026-05/07_frontend_bug_list_reset_button_requires_double_click.md deleted file mode 100644 index cb24b31..0000000 --- a/changelogs/2026-05/07_frontend_bug_list_reset_button_requires_double_click.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -date: 2026-05-07 -type: frontend-bug -module: hl-ui-list-component -priority: medium -notify: ["@mmg"] -status: pending -source: 测试用例汇总.xlsx (2026-05-07) -related_cases: [JQ-016, CT-005, ZH-005, YW-003, JD-003, EW-003, DD-006, TK-004] ---- - -# 列表组件重置按钮需点两次（多模块共性 BUG） - -## 现象 - -测试报告里多个列表页（资源全模块 / 订单 / 退款）反复出现一致描述： - -> "条件清空，但未显示全部数据，还需要再次点击重置按钮" - -复现的列表页（已确认 8 处）： - -| 模块 | 用例编号 | -|------|---------| -| 景区 | JQ-016 | -| 餐厅 | CT-005 | -| 组合备品 | ZH-005 | -| 物业 | YW-003 | -| 酒店 | JD-003 | -| 额外成本 | EW-003 | -| 订单 | DD-006 | -| 退款 | TK-004 | - -8 个列表页都中招 → 共性问题，**应该在 hl-ui 通用列表组件 / 公共 reset 方法里**。 - -## 推断根因 - -**第一次点重置**： -- 清空筛选表单的 v-model（`queryParams = {}`） -- ❌ 但**没有触发 `fetchList()` 重新请求** -- 结果：表单看起来重置了，但列表展示的还是上一次筛选后的数据 - -**第二次点重置**： -- 重置（已经是空表单了） -- 触发 `fetchList()` → 拿到全量数据 → 列表更新 - -## 修复方向（前端） - -### 错误写法 ❌ - -```js -// 假设当前实现类似： -function resetQuery() { - queryParams.value = {} - // 漏了！没调 fetchList -} -``` - -或者： - -```js -// 重置和搜索分开两个按钮，重置只清空不搜索 -<el-button @click="resetForm">重置</el-button> -<el-button @click="handleQuery">搜索</el-button> - -function resetForm() { - // 只 reset 表单，不调列表 - proxy.$refs.queryRef.resetFields() -} -``` - -### 正确写法 ✅ - -```js -function handleResetQuery() { - // 1. 清空表单（含 dataRange 数组） - proxy.$refs.queryRef.resetFields() - queryParams.value.pageNum = 1 - // 2. 立即触发列表刷新（不要让用户再点一次） - fetchList() -} -``` - -或者用一个公共组合式函数 `useListQuery()` 统一封装重置 + 自动刷新。 - -## 影响 - -- 不阻断业务，但是用户体验问题，所有 list 页面都有 -- 测试反复反馈 → 应作为通用列表组件 P2 修 - -## 后端配合 - -无需后端配合，纯前端逻辑问题。 - -## 验收 - -- [ ] 在任意一个列表页点重置按钮 → 一次就能看到全量数据 -- [ ] 抽测 8 个用例编号对应的列表页全部修复 -- [ ] 抽测其他列表页（产品/资源剩余模块/小程序配置）确认无遗漏 - -## 不要建工单 - -按 wx 项目规则：前端 BUG/feature 都走 changelog 通知 mmg，**不在 wx/HL 或 wx/hl-ui 建工单**。 diff --git a/changelogs/2026-05/07_frontend_bug_refund_reason_api_path_and_post_body.md b/changelogs/2026-05/07_frontend_bug_refund_reason_api_path_and_post_body.md deleted file mode 100644 index 875bd82..0000000 --- a/changelogs/2026-05/07_frontend_bug_refund_reason_api_path_and_post_body.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -date: 2026-05-07 -type: frontend-bug -module: refund-reason-api -priority: high -notify: ["@mmg"] -status: pending -source: 测试用例汇总.xlsx (2026-05-07) + /@bug 实测 -related_cases: [YY-001] -gitea_issue_closed: 1790 ---- - -# 退款原因新增失败 — 前端 4 个 API 路径错 + body 当 querystring - -## 原始现象 - -测试用例 YY-001：新增退款原因不通过（保存失败）。 - -## /@bug 实测结论（admin 真 token round-trip） - -后端 `POST /admin/refund-reason/create` 实测： - -``` -Body: {"reasonName":"测试取消原因","reasonType":"CUSTOMER","sortOrder":1} -HTTP: 200 -Response: {"code":200, "data":{"reasonId":2052278650115342338, ...}} -``` - -**后端完全正常，DB 也已落库。问题在前端 API 调用方式。** - -## 根因（hl-ui/src/api/order.js） - -4 个退款原因相关 API 都犯同样 2 个错： - -| 行号 | 函数 | 错误 1 | 错误 2 | -|------|------|--------|--------| -| 393 | `createRefundReason()` | 路径缺 `/admin/` 前缀 | `http.post(url, null, { params: data })` 把 body 当 querystring | -| 404 | `updateRefundReason()` | 同上 | 同上 | -| 416 | `deleteRefundReason()` | 同上 | 同上 | -| 424 | `listRefundReason()` | 同上 | (GET 可能影响小) | - -### 错误后果 - -1. **缺 `/admin/` 前缀** → 网关 9443 拿到 `/refund-reason/create` 没匹配路由 → 404 -2. **`http.post(url, null, { params })`** → axios 把 `{reasonName: '...'}` 拼到 query string `?reasonName=...`，body 是 null。后端 `@Valid @RequestBody RefundReasonSaveReqVO` 拿到 null → 400 必填字段为空 - -### 正确写法 - -```js -// 错 ❌ -export function createRefundReason(data) { - return http.post('/refund-reason/create', null, { params: data }) -} - -// 对 ✅ -export function createRefundReason(data) { - return http.post('/admin/refund-reason/create', data) - // ^^^^^^^ ^^^^ - // 加 /admin/ body 直接传，不用 params -} -``` - -## 同源 anti-pattern - -跟 memory `experience/backend-dev/frontend-http-delete-double-wrap-data-trap.md` 反向： -- 之前：前端正确给 body，但 wrapper 误把第二参数当 config → 后端拿到空 body -- 这次：前端把数据当 query → 后端 @RequestBody 收到 null - -**建议**：mmg 用全局搜 `http.post(.*null.*params` 或 `http.post(.*\{.*params:` 模式扫一下，这是高风险写法，可能 hl-ui 还有其他历史遗留。 - -## 影响 - -- 退款原因 admin 配置无法新增/编辑/删除（YY-001 直接症状） -- 列表查询走 GET 可能不受影响，但路径缺前缀也会 404 - -## 验收（前端） - -- [ ] `api/order.js` 4 个退款原因 API 全部加 `/admin/` 前缀 + 把 data 直接传 body -- [ ] 测试服 round-trip：admin 端能新增/修改/删除/列表退款原因 -- [ ] 全局 grep `http.post.*null.*params` 模式，发现的同类问题一起修 - -## 关联工单 - -Gitea #1790 已关闭并留 closing comment（项目规则前端 BUG 不建工单）。 -完整分析报告：`docs/tasks/20260507_bug_order_analysis.md` diff --git a/changelogs/2026-05/07_frontend_bug_resource_batch_delete_double_wrap_data.md b/changelogs/2026-05/07_frontend_bug_resource_batch_delete_double_wrap_data.md deleted file mode 100644 index 98bbde1..0000000 --- a/changelogs/2026-05/07_frontend_bug_resource_batch_delete_double_wrap_data.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -date: 2026-05-07 -type: frontend-bug -module: resource-batch-delete -priority: high -notify: ["@mmg"] -status: pending -source: 测试用例汇总.xlsx (2026-05-07) + /@bug 实测 -related_cases: [JQ-027, CT-010, BP-013, YW-013] -gitea_issue_closed: 1792 ---- - -# 4 个资源模块批量删除失败 — 前端多包一层 data - -## 原始现象 - -测试用例 JQ-027 / CT-010 / BP-013 / YW-013：景区/餐厅/备品/游玩项目（"物业"实为游玩项目）批量删除时，勾选数据后点删除"系统提示但无法删除"。 - -## /@bug 实测结论（admin 真 token round-trip 双向对照） - -| 模块 | "正确 body" | "前端字面 body" | 结论 | -|------|------------|-----------------|------| -| 景区 | `{"scenicIds":[3001,3002]}` → code:200 | `{"data":{"scenicIds":[...]}}` → code:400 字段【scenicIds】不能为空 | 前端多包 | -| 餐厅 | `{"restaurantIds":[...]}` → code:200 | `{"data":{"restaurantIds":[...]}}` → code:400 | 前端多包 | -| 备品 | `{"suppliesIds":[...]}` → code:200 | `{"data":{"suppliesIds":[...]}}` → code:400 | 前端多包 | -| 游玩项目 | `{"playServiceIds":[...]}` → code:200 | `{"data":{"playServiceIds":[...]}}` → code:400 | 前端多包 | - -**后端纯净，4 个模块前端 api 文件统一多包了一层 `data`**。 - -## 根因详情 - -| 文件:行号 | 现状 | -|----------|------| -| `hl-ui/src/api/scenic.js:421` | `http.delete(url, { data: { scenicIds } })` ❌ | -| `hl-ui/src/api/restaurant.js:78` | `http.delete(url, { data: { restaurantIds } })` ❌ | -| `hl-ui/src/api/spare.js:69` | `http.delete(url, { data: { suppliesIds } })` ❌ | -| `hl-ui/src/api/playservice.js:71` | `http.delete(url, { data: { playServiceIds } })` ❌ | - -### 项目 wrapper 行为（`hl-ui/src/utils/request.js:582-583`） - -项目自定义的 `http.delete(url, data, config)` 第二参数**直接当 body**，不像 axios 原生 `axios.delete(url, { data: body })` 那样从 config.data 取。 - -所以前端写 `http.delete(url, { data: { scenicIds } })` 时： -- 第二参数是 `{ data: { scenicIds } }` -- wrapper 直接当 body 发出去 -- 后端拿到 `{ "data": { "scenicIds": [...] } }` -- 后端 DTO 是 `{ scenicIds: List<Long> }`，找不到顶层 `scenicIds` 字段 → @NotEmpty fail - -### 正确写法 - -```js -// 错 ❌ -export function batchDelete(scenicIds) { - return http.delete('/admin/scenic/batch', { data: { scenicIds } }) -} - -// 对 ✅ -export function batchDelete(scenicIds) { - return http.delete('/admin/scenic/batch', { scenicIds }) - // ^^^^^^^^^ - // 第二参数直接是 body 对象，不要再包 { data: ... } -} -``` - -## 同源 anti-pattern（重要更新） - -跟 memory `experience/backend-dev/frontend-http-delete-double-wrap-data-trap.md` 是**同一个坑的反转版本**： - -- **9 天前**（PR #1494 时期）：项目 wrapper 第二参数当 body，前端按 axios 原生写 `{ data: payload }`，后端拿到多包一层 → 一样的 code:400 -- **现在**：wrapper 仍然这样行为，但部分模块前端代码似乎曾经改对过又改错回去（或者一开始就错），症状一模一样 - -**建议 mmg**： -1. 修这 4 处当前确认的错误 -2. 全局 grep `http\.delete\(.*\{.*data:` / `http\.put\(.*\{.*data:` 扫一遍，看历史遗留 -3. 考虑把 wrapper 改成兼容 axios 原生用法（即从 config.data 取）减少这种坑 - -## 影响 - -- 4 个资源模块批量删除完全失效 -- 单个删除（非批量）通常不走这个路径，可能正常 - -## 验收（前端） - -- [ ] 4 个文件改完，传第二参数直接是 IDs 对象不要包 `{ data: ... }` -- [ ] 测试服 round-trip：景区/餐厅/备品/游玩项目 4 模块批量删除 5 条 → 列表 deleted_at 已写 -- [ ] 全局 grep 同类 anti-pattern 一起改 - -## 关联工单 - -Gitea #1792 已关闭并留 closing comment（项目规则前端 BUG 不建工单）。 -完整分析报告：`docs/tasks/20260507_bug_resource_analysis.md` - -## 顺手另一个共性问题（建议 PM 复核） - -/@bug 还发现：8 个资源服务（hotel/scenic/activity/restaurant/staff/supplies/cost/vehicle）的 `updateStatus` 方法**全部缺 checkResourceInUse 引用计数检查**（只有 `submitApproval` 路径有）。本批 PR 只修景区一个（JQ-011 #1794），其余 7 个建议 PM 决策是否扩大修复范围。 diff --git a/changelogs/2026-05/07_frontend_bug_resource_batch_status_select_not_synced.md b/changelogs/2026-05/07_frontend_bug_resource_batch_status_select_not_synced.md deleted file mode 100644 index 93989c7..0000000 --- a/changelogs/2026-05/07_frontend_bug_resource_batch_status_select_not_synced.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -date: 2026-05-07 -type: frontend-bug -module: resource-scenic-batch-status -priority: low -notify: ["@mmg"] -status: pending -source: 测试用例汇总.xlsx (2026-05-07) -related_cases: [JQ-024] ---- - -# 景区批量改状态下拉框 v-model 显示不同步 - -## 现象 - -测试用例 JQ-024： - -> 1. 勾选多个景区 -> 2. 点击"批量更改状态" -> 3. 在下拉框里选择"下架" -> 4. **下拉框显示的还是"上架"**（用户选的"下架"看不到） -> 5. 点确定 → 实际状态改成下架（功能本身正常） - -测试人备注："**功能正常，但有小问题**"。 - -## 根因（推断） - -el-select / n-select 的 **v-model 异步同步问题**，跟 memory `experience/backend-dev/nselect-tag-mode-stringify-race.md` 类似但场景不同。 - -可能的代码模式： - -```vue -<el-select v-model="batchStatus" placeholder="请选择"> - <el-option label="上架" value="UP" /> - <el-option label="下架" value="DOWN" /> -</el-select> -``` - -如果 `batchStatus` 在 `el-dialog` open 前没初始化（或 dialog 复用时没 reset），v-model 拿不到当前 option 对应的 label，下拉框就显示前一次的值。 - -或者 `batchStatus` 是从父组件 `props` 传入但没用 `v-model:`（双向绑定缺一半）。 - -## 修复方向（前端） - -### 检查点 - -```js -// 1. dialog 打开时显式重置 batchStatus -function openBatchDialog() { - batchStatus.value = '' // 或 null - dialogVisible.value = true -} - -// 2. 选项改变时确保赋值 -function handleStatusChange(val) { - batchStatus.value = val // 不要在这里做条件赋值 -} - -// 3. 检查是不是用了 v-model:value 而不是 v-model -<el-select v-model="batchStatus"> // 正确 -<el-select :value="batchStatus" @input="batchStatus = $event"> // 漏了 input 事件就坏 -``` - -## 影响 - -- 不阻断业务（用户能选成功，确定后状态对） -- 仅显示层 BUG，体验问题 - -## 验收 - -- [ ] 打开批量改状态 dialog，下拉框选项默认空 -- [ ] 选"下架" → 下拉框显示"下架" -- [ ] 关掉重开 dialog → 下拉框回到空 diff --git a/changelogs/2026-05/07_frontend_notice_topic-filter-empty.md b/changelogs/2026-05/07_frontend_notice_topic-filter-empty.md deleted file mode 100644 index 4c56762..0000000 --- a/changelogs/2026-05/07_frontend_notice_topic-filter-empty.md +++ /dev/null @@ -1,76 +0,0 @@ -# 前端 BUG 通知 — 主题列表「主题类型」筛选选「小蒙马」后列表变空 - -**日期**: 2026-05-07 -**类型**: 前端 BUG（admin 后台 hl-ui） -**模块**: 主题管理（产品线 / Product Line） -**通知**: @mmg -**后端是否需改动**: 否 - ---- - -## 现象 - -admin 后台「产品 → 主题列表」页面： -- 进入页默认「共 15 条」（与后端实测一致） -- 在「主题类型」下拉框选择「小蒙马」点搜索 → 列表变「暂无主题数据」 -- 用户期望：应返回 GROUP 类型的产品线（实测有 3 条） - -## 后端 round-trip 实测（已排除后端嫌疑） - -测试服 `https://api.test.1814.love:9443/admin-api/admin/product/line/list`，admin/Admin@123456，SUPER_ADMIN： - -| 请求 | total | records.length | 备注 | -|---|---|---|---| -| 不带 productType | 15 | 12 | PAGE_SIZE=12，分页正常 | -| `productType=GROUP` | **3** | **3** | 与用户描述「0 条」矛盾 → 前端嫌疑 | -| `productType=CORE` | 5 | 5 | | -| `productType=CUSTOM` | 6 | 6 | | -| `productType=ROUTE` | 0 | 0 | 数据本就 0 | -| `productType=小蒙马`（中文 label 当 value 反例） | **0** | **0** | **如果前端误把 label 当 value 传，现象 100% 吻合** | - -**结论**：后端 `eqIfPresent(ProductLineDO::getProductType, req.getProductType())` 工作正常；前端选「小蒙马」点搜索后，传给后端的不是字典 value `GROUP`。 - -## 字典对照（`product_type` 字典，已 round-trip 验证） - -| label | dictValue | -|---|---| -| 核心产品 | CORE | -| 自驾路书 | ROUTE | -| 私人定制 | CUSTOM | -| **小蒙马** | **GROUP** | - -## 根因推断（按概率排序） - -### (A) 字典 store localStorage 持久化老数据 ⭐ 最可能 -- `hl-ui/src/stores/dict.js:110-114` 用 `pinia-plugin-persistedstate` 持久化了 `dictList` -- 用户浏览器 localStorage 里旧版字典可能没有 GROUP 项，导致下拉 option value 错位 -- **复现取证步骤**：让 mmg 让用户在 DevTools → Application → Local Storage 查看 `dict` key，看「小蒙马」一项的 `dictValue` 是否为字符串 `"GROUP"` - -### (B) 前端把 label 当 value 传给后端 -- 检查 `hl-ui/src/views/product/line/index.vue` 的「主题类型」下拉框 v-model 与 `el-option :value` 是否绑定到 `dictValue`（应该是 `GROUP` 字符串）而不是 `dictLabel`（`小蒙马`） -- DevTools → Network 抓搜索后的请求 URL： - - 如果是 `?productType=GROUP&...` → 不是这条根因 - - 如果是 `?productType=小蒙马&...` 或 `?productType=undefined&...` → 就是这条 - -### (C) 前端打包版本滞后 -- 用户访问的静态资源若是某次旧打包，可能还在用老字段名 -- 让用户硬刷新（Ctrl+Shift+R）或退出重登再复现 - -## 建议修复方向 - -1. **优先级 1**：让 mmg 在自己浏览器复现一遍，DevTools Network 抓真实请求 URL，定位是 (A) 还是 (B) -2. **如果是 (A)**：dict store 加版本号，字典升级后 localStorage 自动失效；或者进入「主题列表」页前强制 `dictStore.refresh()` 拉一次最新 -3. **如果是 (B)**：检查筛选区下拉框 `:value` 绑定，确保用 `dict.dictValue` 不是 `dict.dictLabel` - -## 涉及文件（仅供前端排查参考） - -- 页面：`hl-ui/src/views/product/line/index.vue`（标题「主题管理」） -- 字典 store：`hl-ui/src/stores/dict.js:39-50, 110-114` -- API：`hl-ui/src/api/product/core.js:49-51` `getProductLinePage` - -## 后端代码定位（确认无需改动） - -- Controller：`hl-product-service-v2/.../admin/AdminProductLineController.java:75-79` `GET /admin/product/line/list` -- VO：`ProductLinePageReqVO.java:23` `private String productType;`（字典 product_type） -- Service：`ProductLineService.java:168-174` `listLines` -- Mapper：`ProductLineMapper.java:48-68` `selectPageWithCount` 用 `MPJLambdaWrapperX.eqIfPresent(...)` diff --git a/changelogs/2026-05/08_1500_arrival-mode.md b/changelogs/2026-05/08_1500_arrival-mode.md deleted file mode 100644 index c604146..0000000 --- a/changelogs/2026-05/08_1500_arrival-mode.md +++ /dev/null @@ -1,528 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-05-08 15:00 -**PR**: #1878 feat(order-v2): 到达/返程信息支持区分一起/多批两种模式 + #1887 修正接口描述 - ---- - -## 破坏性变更：POST /mp/order/{orderId}/arrival 语义彻底变更 - -### 变了什么（前端视角） - -**单数接口从「追加一条」变成「该方向全量替换 1 条」。** - -| 行为 | 旧逻辑（PR 前） | 新逻辑（PR 后） | -|------|----------------|----------------| -| 连续调 2 次 | 产生 2 条批次（追加） | 第 2 次会把第 1 次清掉，只保留最新 1 条 | -| 想分批到达 | 多次调单数接口 | 必须改用 /arrival/batch（提交多元素数组） | -| 已有批次被覆盖范围 | 无此逻辑 | 只清同一 direction 的旧批次，不影响另一方向 | - -如果小程序之前通过多次调 POST /arrival 实现「分批到达」，现在必须改为调 POST /arrival/batch。 - ---- - -## Bug 修复：POST /mp/order/{orderId}/arrival/batch 不再误删另一方向 - -| 行为 | 旧行为（有 bug） | 新行为（已修复） | -|------|----------------|----------------| -| 提交返程多批 | 把已填的到达批次也一起删掉 | 只删 direction=DEPARTURE 的旧批次，ARRIVAL 不受影响 | -| 提交到达多批 | 把已填的返程批次也一起删掉 | 只删 direction=ARRIVAL 的旧批次，DEPARTURE 不受影响 | - -如果前端之前因为这个 bug 做了「先查再保」之类的 workaround，可以清理掉。 - ---- - -## 新增：GET 接口返回 mode + modeLabel 字段 - -GET /mp/order/{orderId}/arrival 返回的每个批次对象新增 2 个字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| mode | String | 模式枚举：TOGETHER 或 SEPARATE | -| modeLabel | String | 按方向拼出的中文标签（见下表） | - -modeLabel 的 4 种值： - -| direction | mode | modeLabel | -|-----------|------|----------| -| ARRIVAL | TOGETHER | 一起到达 | -| ARRIVAL | SEPARATE | 多批到达 | -| DEPARTURE | TOGETHER | 一起返程 | -| DEPARTURE | SEPARATE | 多批返程 | - -前端可以用 arrivals[0]?.mode（或 departures[0]?.mode）来判断该方向当前 tab 模式，决定进入页面时默认选中哪个选项卡。 - ---- - -## 新增错误码：580010 BATCH_DIRECTION_MIXED - -POST /mp/order/{orderId}/arrival/batch 增加新校验：请求数组里所有元素的 direction 必须一致（不能同一次 batch 里混提 ARRIVAL 和 DEPARTURE）。 - -| 错误码 | message | -|--------|--------| -| 580010 | 批量提交的批次必须同一方向（到达或返程） | - - -响应示例（错误）： - -```json -{ - "code": 580010, - "message": "批量提交的批次必须同一方向（到达或返程）", - "data": null -} -``` - ---- - -## 涉及的接口汇总 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 查询订单全量批次 | GET | /mp/order/{orderId}/arrival | 字段新增 | 每个批次对象新增 mode + modeLabel | -| 2 | 新增交通批次 | POST | /mp/order/{orderId}/arrival | 语义破坏性变更 | 从追加改为该方向全量替换 1 条 | -| 3 | 全量替换批次(多批) | POST | /mp/order/{orderId}/arrival/batch | Bug 修复 + 新增校验 | 修方向隔离 bug；新增 direction 混用校验 | -| 4 | 修改交通批次 | PUT | /mp/order/{orderId}/arrival/plan/{planId} | 无变化 | - | -| 5 | 删除交通批次 | DELETE | /mp/order/{orderId}/arrival/plan/{planId} | 无变化 | - | - ---- - -## 接口详细定义 - -### 1. GET /mp/order/{orderId}/arrival — 查询订单全量到达/离开批次 - -- **使用场景**：进入订单详情/行程页时查询，用返回的 arrivals[0]?.mode 和 departures[0]?.mode 决定各方向 tab 默认状态 - -- **路径参数**： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 是 | 订单 ID | - -- **响应字段（data 对象）**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| orderId | Long | 订单 ID | -| arrivals | Array | direction=ARRIVAL 的批次列表 | -| departures | Array | direction=DEPARTURE 的批次列表 | - -arrivals/departures 内每个批次对象字段（MpArrivalPlanRespVO）： - -| 字段 | 类型 | 说明 | -|------|------|------| -| planId | Long | 批次 ID | -| orderId | Long | 订单 ID | -| direction | String | ARRIVAL/DEPARTURE | -| directionLabel | String | 到达/离开 | -| mode | String | **[本次新增]** TOGETHER/SEPARATE | -| modeLabel | String | **[本次新增]** 一起到达/多批到达/一起返程/多批返程 | -| transportType | String | FLIGHT/TRAIN/SELF_DRIVE | -| transportTypeLabel | String | 飞机/火车/自驾 | -| transportNo | String | 航班号/车次号（自驾为 null） | -| carrier | String | 航司/铁路公司 | -| departStation | String | 出发站/机场 | -| arriveStation | String | 到达站/机场 | -| departTime | String | 出发时间，格式 yyyy-MM-dd HH:mm:ss | -| arriveTime | String | 到达时间，格式 yyyy-MM-dd HH:mm:ss | -| selfDrivePeriod | String | 自驾时段（MORNING/AFTERNOON/EVENING），非自驾为 null | -| selfDrivePeriodLabel | String | 上午/下午/晚上，非自驾为 null | -| selfDriveEta | String | 自驾预计到达精确时间，非自驾为 null | -| remark | String | 用户备注 | -| creatorType | String | USER/ADMIN | -| createTime | String | 创建时间 | -| travelers | Array | 本批次出行人列表 | - -travelers 内每个出行人字段： - -| 字段 | 类型 | 说明 | -|------|------|------| -| travelerId | Long | 出行人 ID | -| name | String | 姓名 | -| travelerType | String | ADULT/CHILD/YOUNG_CHILD/BABY | - -- **响应示例（完整）**： -```json -{ - "code": 200, - "message": "success", - "data": { - "orderId": 700001, - "arrivals": [ - { - "planId": 800001, - "orderId": 700001, - "direction": "ARRIVAL", - "directionLabel": "到达", - "mode": "TOGETHER", - "modeLabel": "一起到达", - "transportType": "FLIGHT", - "transportTypeLabel": "飞机", - "transportNo": "CZ6255", - "carrier": "南方航空", - "departStation": "北京首都T3", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "selfDrivePeriod": null, - "selfDrivePeriodLabel": null, - "selfDriveEta": null, - "remark": "带小孩,需婴儿座椅", - "creatorType": "USER", - "createTime": "2026-07-01 10:00:00", - "travelers": [ - { - "travelerId": 10001, - "name": "张三", - "travelerType": "ADULT" - } - ] - } - ], - "departures": [ - { - "planId": 800002, - "orderId": 700001, - "direction": "DEPARTURE", - "directionLabel": "离开", - "mode": "SEPARATE", - "modeLabel": "多批返程", - "transportType": "TRAIN", - "transportTypeLabel": "火车", - "transportNo": "K209", - "carrier": null, - "departStation": "海拉尔", - "arriveStation": "北京", - "departTime": "2026-07-15 10:00:00", - "arriveTime": "2026-07-16 08:00:00", - "selfDrivePeriod": null, - "selfDrivePeriodLabel": null, - "selfDriveEta": null, - "remark": null, - "creatorType": "USER", - "createTime": "2026-07-02 09:00:00", - "travelers": [ - { - "travelerId": 10001, - "name": "张三", - "travelerType": "ADULT" - } - ] - } - ] - } -} -``` - ---- - -### 2. POST /mp/order/{orderId}/arrival — 新增交通批次（单条，该方向全量替换） - -- **使用场景**：用户在「一起到达」或「一起返程」tab 填写单条信息并提交 -- **语义重申**：调用此接口会把同 direction 的所有旧批次软删，再插入 1 条新批次。最终该方向只剩 1 条，mode 固定为 TOGETHER - -- **路径参数**： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 是 | 订单 ID | - -- **请求参数（JSON Body）**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| direction | String | 是 | ARRIVAL=到达 / DEPARTURE=离开 | -| transportType | String | 是 | FLIGHT=飞机 / TRAIN=火车 / SELF_DRIVE=自驾 | -| transportNo | String | 条件必填 | 航班号/车次号；FLIGHT/TRAIN 必填，SELF_DRIVE 不填 | -| carrier | String | 否 | 航司/铁路公司，最长 64 字符 | -| departStation | String | 条件必填 | 出发站/机场；DEPARTURE+FLIGHT/TRAIN 必填；ARRIVAL 可选 | -| arriveStation | String | 条件必填 | 到达站/机场；ARRIVAL+FLIGHT/TRAIN 必填；DEPARTURE 可选 | -| departTime | String | 条件必填 | 出发时间；DEPARTURE+FLIGHT/TRAIN 必填；格式 yyyy-MM-dd HH:mm:ss | -| arriveTime | String | 条件必填 | 到达时间；ARRIVAL+FLIGHT/TRAIN 必填；格式 yyyy-MM-dd HH:mm:ss | -| selfDrivePeriod | String | 条件必填 | 自驾时段；SELF_DRIVE 必填；MORNING/AFTERNOON/EVENING | -| selfDriveEta | String | 否 | 自驾预计到达精确时间；SELF_DRIVE 可选；格式 yyyy-MM-dd HH:mm:ss | -| remark | String | 否 | 用户备注，最长 255 字符 | -| travelerIds | Array | 是 | 出行人 ID 列表，至少 1 人，必须属于本订单 | - -- **请求示例（到达+飞机）**： -```json -{ - "direction": "ARRIVAL", - "transportType": "FLIGHT", - "transportNo": "CZ6255", - "carrier": "南方航空", - "departStation": "北京首都T3", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "remark": "带小孩,需婴儿座椅", - "travelerIds": [ - 10001, - 10002 - ] -} -``` - -- **响应示例（完整）**： - -```json -{ - "code": 200, - "message": "success", - "data": { - "planId": 800001, - "orderId": 700001, - "direction": "ARRIVAL", - "directionLabel": "到达", - "mode": "TOGETHER", - "modeLabel": "一起到达", - "transportType": "FLIGHT", - "transportTypeLabel": "飞机", - "transportNo": "CZ6255", - "carrier": "南方航空", - "departStation": "北京首都T3", - "arriveStation": "海拉尔东山", - "departTime": "2026-07-10 08:30:00", - "arriveTime": "2026-07-10 11:00:00", - "selfDrivePeriod": null, - "selfDrivePeriodLabel": null, - "selfDriveEta": null, - "remark": "带小孩,需婴儿座椅", - "creatorType": "USER", - "createTime": "2026-07-01 10:00:00", - "travelers": [ - { - "travelerId": 10001, - "name": "张三", - "travelerType": "ADULT" - }, - { - "travelerId": 10002, - "name": "李四", - "travelerType": "CHILD" - } - ] - } -} -``` - ---- - -### 3. POST /mp/order/{orderId}/arrival/batch — 全量替换批次（多批模式） - -- **使用场景**：用户在「多批到达」或「多批返程」tab，一次性提交该方向所有批次 -- **Bug 修复**：旧版本会把订单全部旧批次删掉（含另一方向），新版本只删 body 第一条元素对应的 direction -- **新增校验**：body 数组里所有元素的 direction 必须一致，混提返回 code=580010 - -- **路径参数**： - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 是 | 订单 ID | - -- **请求参数（JSON Body，数组）**：字段同上面单条接口，外层包数组 - -- **请求示例（多批返程）**： -```json -[ - { - "direction": "DEPARTURE", - "transportType": "FLIGHT", - "transportNo": "CZ6256", - "carrier": "南方航空", - "departStation": "海拉尔东山", - "arriveStation": "北京首都T3", - "departTime": "2026-07-15 12:00:00", - "arriveTime": "2026-07-15 15:30:00", - "travelerIds": [ - 10001 - ] - }, - { - "direction": "DEPARTURE", - "transportType": "TRAIN", - "transportNo": "K209", - "departStation": "海拉尔", - "arriveStation": "北京", - "departTime": "2026-07-15 10:00:00", - "arriveTime": "2026-07-16 08:00:00", - "travelerIds": [ - 10002 - ] - } -] -``` - -- **响应示例（完整）**： - -```json -{ - "code": 200, - "message": "success", - "data": { - "orderId": 700001, - "arrivals": [], - "departures": [ - { - "planId": 800003, - "orderId": 700001, - "direction": "DEPARTURE", - "directionLabel": "离开", - "mode": "SEPARATE", - "modeLabel": "多批返程", - "transportType": "FLIGHT", - "transportTypeLabel": "飞机", - "transportNo": "CZ6256", - "carrier": "南方航空", - "departStation": "海拉尔东山", - "arriveStation": "北京首都T3", - "departTime": "2026-07-15 12:00:00", - "arriveTime": "2026-07-15 15:30:00", - "selfDrivePeriod": null, - "selfDrivePeriodLabel": null, - "selfDriveEta": null, - "remark": null, - "creatorType": "USER", - "createTime": "2026-07-01 11:00:00", - "travelers": [ - { - "travelerId": 10001, - "name": "张三", - "travelerType": "ADULT" - } - ] - }, - { - "planId": 800004, - "orderId": 700001, - "direction": "DEPARTURE", - "directionLabel": "离开", - "mode": "SEPARATE", - "modeLabel": "多批返程", - "transportType": "TRAIN", - "transportTypeLabel": "火车", - "transportNo": "K209", - "carrier": null, - "departStation": "海拉尔", - "arriveStation": "北京", - "departTime": "2026-07-15 10:00:00", - "arriveTime": "2026-07-16 08:00:00", - "selfDrivePeriod": null, - "selfDrivePeriodLabel": null, - "selfDriveEta": null, - "remark": null, - "creatorType": "USER", - "createTime": "2026-07-01 11:00:00", - "travelers": [ - { - "travelerId": 10002, - "name": "李四", - "travelerType": "CHILD" - } - ] - } - ] - } -} -``` - ---- - -## 枚举 / 字典值（完整） - -### transport_direction（方向） - -| 值 | 中文 | 说明 | -|----|------|------| -| ARRIVAL | 到达 | 游客到达目的地 | -| DEPARTURE | 离开 | 游客离开目的地（返程） | - -### mode（模式，本次新增） - -| 值 | 中文 | 说明 | -|----|------|------| -| TOGETHER | 一起 | 该方向所有出行人同一批次 | -| SEPARATE | 多批 | 该方向出行人分多个批次 | - -### modeLabel（按 direction + mode 拼，本次新增） - -| direction | mode | modeLabel | -|-----------|------|-----------| -| ARRIVAL | TOGETHER | 一起到达 | -| ARRIVAL | SEPARATE | 多批到达 | -| DEPARTURE | TOGETHER | 一起返程 | -| DEPARTURE | SEPARATE | 多批返程 | - -### transport_type（交通方式） - -| 值 | 中文 | -|----|------| -| FLIGHT | 飞机 | -| TRAIN | 火车 | -| SELF_DRIVE | 自驾 | - -### self_drive_period（自驾时段） - -| 值 | 中文 | 时间范围 | -|----|------|---------| -| MORNING | 上午 | 06:00-12:00 | -| AFTERNOON | 下午 | 12:00-18:00 | -| EVENING | 晚上 | 18:00 以后 | - -### creator_type（创建者类型） - -| 值 | 中文 | -|----|------| -| USER | 用户自填 | -| ADMIN | 定制师代录 | - -### traveler_type（出行人类型） - -| 值 | 中文 | -|----|------| -| ADULT | 成人 | -| CHILD | 儿童 | -| YOUNG_CHILD | 幼儿 | -| BABY | 婴儿 | - ---- - -## 错误码（本模块完整） - -| code | message | 触发场景 | -|------|---------|---------| -| 580001 | 订单当前状态不可修改交通信息: {状态} | 订单不在可编辑状态 | -| 580002 | 出行人列表不能为空 | travelerIds 为空 | -| 580003 | 以下出行人不属于本订单: {ids} | travelerIds 包含不属于此订单的 ID | -| 580004 | 航班号/车次号不能为空 | FLIGHT/TRAIN 时 transportNo 未填 | -| 580005 | 到达机场/车站不能为空 | ARRIVAL+FLIGHT/TRAIN 时 arriveStation 未填 | -| 580006 | 到达时间不能为空 | ARRIVAL+FLIGHT/TRAIN 时 arriveTime 未填 | -| 580007 | 出发机场/车站不能为空 | DEPARTURE+FLIGHT/TRAIN 时 departStation 未填 | -| 580008 | 出发时间不能为空 | DEPARTURE+FLIGHT/TRAIN 时 departTime 未填 | -| 580009 | 自驾时段不能为空 | SELF_DRIVE 时 selfDrivePeriod 未填 | -| 580010 | 批量提交的批次必须同一方向（到达或返程） | batch 接口 body 内 direction 混用（本次新增） | - ---- - -## 业务规则 / 校验规则 - -1. POST /arrival（单数）：提交即清空同 direction 旧批次，再插入 1 条。最终该方向只有 1 条批次，mode 固定为 TOGETHER。 -2. POST /arrival/batch：提交即清空同 direction 旧批次，再批量插入。有 2 条及以上时 mode 为 SEPARATE；仅 1 条时 mode 也是 SEPARATE（因为用户选择了「多批」入口）。 -3. 两个接口只影响自己提交的 direction，不互相干扰（本次 bug 修复要点）。 -4. PUT /arrival/plan/{planId} 修改单条，不影响其他批次，不改变 mode。 -5. DELETE /arrival/plan/{planId} 只软删单条。 -6. 以上操作均需订单处于可编辑状态，否则返回 580001。 - ---- - -## 前端实现建议 - - - ---- - -## 补充说明 - -- GET 接口新增 mode/modeLabel 字段，向后兼容（纯新增，无删改名），已有代码不受影响 -- POST 单数接口语义变更属于破坏性变更，旧版用多次调单数接口实现分批的需改用 batch -- 服务重启：需重启 hl-order-service-v2 和 hl-mp-service 后生效 diff --git a/changelogs/2026-05/08_chore_test_stub_and_cache_deps_diagnostic.md b/changelogs/2026-05/08_chore_test_stub_and_cache_deps_diagnostic.md deleted file mode 100644 index 8d59d21..0000000 --- a/changelogs/2026-05/08_chore_test_stub_and_cache_deps_diagnostic.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -date: 2026-05-08 -type: backend-internal -module: hl-user-service/test, hl-common-redis/cache -priority: low -notify: [] -status: tested-passed -restart_service: hl-common-redis (随 mp-service / user-service / 任何引用方升级) -gitea_pr: [1879, 1881] -gitea_issue: [1853] -gitea_issue_open: [1860, 1880] ---- - -# 测试 stub 修复 + 缓存反向索引诊断日志(前端无感) - -两个内部改动汇总, **不影响任何接口字段/路径/行为, 前端无需配合**。 - -## PR #1879 - InternalUserControllerTest stub 切到 default 方法路径 (Closes #1853) - -### 现象 / 根因 -PR #1814 把 `InternalUserController.getAdminsByRoleKey` 用到的 3 个 mapper 方法改为 default 方法实现: -- `SysRoleMapper.selectByRoleKey(String)` -- `AdminUserRoleMapper.selectByRoleId(Long)` -- `AdminUserMapper.selectActiveWithWechatByAdminIds(Collection)` - -旧 stub `when(mapper.selectOne(any(LambdaQueryWrapper.class)))` 在 Mockito 默认配置下不进 default 方法 body, 导致 5 个 `getAdminsByRoleKey_*` case fail。 - -### 修复 -3 个 mapper stub 全切到 default 方法本身, verify never 路径同步切签名。 - -### 工单偏差 -工单原描述说 DesignerProfileServiceTest / DesignerServiceTest 也是同根因。**核实不是**, 这俩 Service 生产代码仍在用 LambdaQueryWrapper, 原 stub 工作正常, 未触碰。 - -### 残留另起工单 -ServiceMonitorServiceTest 2 个 pre-existing failure (L:63, L:102) 与本工单无关, 已起 #1880 跟进。 - -## PR #1881 - putWithDeps SMEMBERS 自检 + ERROR stack (Refs #1860 Stage 1) - -### 背景 -PR #1855 / #1858 banner / dict / featuredReview hotfix 后, `DependencyAwareCacheManager` 反向索引 SADD 在 prod 仍有「总依赖=0, 实际删除=0」现象, 但日志 silent 看不出根因。 - -### Stage 1 改动(仅诊断) -**不动业务逻辑、不动 MpCacheAspect、不调 invalidateSource 主路径, 仅加日志。** - -1. `putWithDeps` 入口 INFO 日志: key/deps/ttlSec -2. `registerDeps` 每个 dep Lua 完成后立即 **SMEMBERS 自检**, INFO 输出 isMember + indexSize -3. `invalidateSource` 把成员快照(members=[...])打出来 -4. 序列化失败 / SET 失败 log.warn → log.error + stack trace - -业务降级语义零变化(仍 return 不抛), 仅日志级别+stack 提级。 - -### 后续 Stage 2(待 prod 日志暴露根因) -- 看到 `[cache-deps registerDeps OK] isMember=false` → SADD 静默失败, 修 Lua 路径 -- 看到 `序列化失败` ERROR + stack → 改 `MpCacheAspect` 缓存 result.getData() -- mp-service 完全没出现 `[cache-deps putWithDeps 开始]` → 修 aspect 上游 - -### 工单状态 -**#1860 保持 open**, 验收 4 项中第 1 条已勾, 第 3 条「prod 日志总依赖>=1」需 prod 部署后实测才能勾。 -**#1861 (D5 删 MpCacheEvict 重构) 继续阻塞**至 #1860 完全闭环。 - -## 测试 - -- PR #1879: `mvn -pl hl-user-service test`, IUT 5 case 全过 -- PR #1881: `mvn -pl hl-common/hl-common-redis test`, 47/0/0 (新增 4 case) - -## 重启服务 - -- `hl-user-service`(测试 stub 改动只影响单测, 但合 dev 后建议 deploy panel 部署一次) -- `hl-common-redis` 是公共模块, 实际部署需要 `mp-service` / `user-service` / `product-v2` / `order-v2` / `resource-service` 任何用到 `DependencyAwareCacheManager` 的服务都升级才生效 - -## 关联 - -- Closes wx/HL #1853 (PR #1879) -- Refs wx/HL #1860 Stage 1 (PR #1881, 工单不在本 PR 关闭) -- 起 #1880 (ServiceMonitor failure follow-up) -- 阻塞 #1861 (D5 重构, 等 #1860 Stage 2) diff --git a/changelogs/2026-05/08_feat_faq_add_type_field_with_dict.md b/changelogs/2026-05/08_feat_faq_add_type_field_with_dict.md deleted file mode 100644 index 04d2e64..0000000 --- a/changelogs/2026-05/08_feat_faq_add_type_field_with_dict.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -date: 2026-05-08 -type: backend-feature -module: hl-user-service/faq -priority: medium -notify: ["@mmg"] -status: tested-passed -restart_service: hl-user-service -gitea_pr: 1898 -gitea_issue: [1896] ---- - -# FAQ 增加「类型」字段(字典 mp_faq_type) — 管理后台需补类型下拉 - -## 背景 - -`sys_faq_item` 表新增 `type_code` 字段,用字典 `mp_faq_type` 管理类型枚举。新增 9 个类型对应「呼籁小程序FAQ_标准对客版_v2.0」9 大类目(产品怎么选/预订与支付/儿童与家庭/行程与交通/住宿与餐饮/体验与安全/行前准备/退改与售后/投诉与权益保障)。 - -后续会按 docx 内容清空+重建正式环境 FAQ 数据,届时每条问题都会带 `typeCode`。 - -## API 字段变化 - -### 管理端 (admin) - -**1. 列表/详情/创建/更新响应** `FaqItemRespVO` 新增字段: - -```json -{ - "id": "...", - "categoryId": "...", - "categoryName": "...", - "question": "...", - "answer": "...", - "sortOrder": 1, - "status": "ACTIVE", - "statusLabel": "启用", - "typeCode": "PRODUCT_SELECT", // 新增,可能为 null - "typeLabel": "产品怎么选", // 新增,后端从字典回填,可能为 null - "createTime": "...", - "updateTime": "..." -} -``` - -**2. 创建/更新请求** `FaqItemSaveReqVO` 新增字段(可选,允许 null): - -```json -POST /admin/faq/items -PUT /admin/faq/items/{id} -{ - "categoryId": 1, - "question": "...", - "answer": "...", - "sortOrder": 1, - "typeCode": "PRODUCT_SELECT" // 新增,字典 mp_faq_type 的 dict_value -} -``` - -**3. 列表查询** `GET /admin/faq/items` 新增筛选参数: - -``` -GET /admin/faq/items?page=1&pageSize=20&typeCode=PRODUCT_SELECT -``` - -支持按 `typeCode` 等值筛选(可选,不传不过滤)。 - -### 小程序端 (mp) - -`MpFaqItemRespVO` 同步增加 `typeCode` + `typeLabel` 字段。小程序端如有需要可基于 typeCode 做分类展示/分组。 - -## 前端工作清单(mmg 关注) - -### 1. 字典数据源 - -字典已通过 Flyway 自动初始化,前端调字典查询接口取数: - -``` -GET /admin/dict/data/by-type/mp_faq_type -``` - -(具体接口路径请前端按现有字典调用方式自查;本 PR 字典 9 项 sort_order 1-9 已就位) - -字典 9 项: -| dict_value | dict_label | -|---|---| -| PRODUCT_SELECT | 产品怎么选 | -| BOOKING_PAY | 预订与支付 | -| KIDS_FAMILY | 儿童与家庭 | -| ITINERARY_TRANSPORT | 行程与交通 | -| STAY_DINING | 住宿与餐饮 | -| EXPERIENCE_SAFETY | 体验与安全 | -| PRE_TRIP_PREP | 行前准备 | -| REFUND_AFTERSALE | 退改与售后 | -| COMPLAINT_RIGHTS | 投诉与权益保障 | - -### 2. 「编辑/新增问题」对话框 - -在现有「问题/回答/排序号/状态」基础上,**增加「类型」下拉框**: - -- label:`类型` -- 必填性:**不强制必填**(后端允许 null,但建议默认必填以保证数据完整,具体由前端按 UX 决定) -- 数据源:上述字典接口 -- 提交时附带 `typeCode` 字段 - -### 3. 问题列表页 - -建议在列表展示一列「类型」(取 `typeLabel`),老数据 typeLabel 为 null 时显示「-」。 - -### 4. (可选) 列表筛选 - -列表上方增加「类型」筛选下拉,选中后调用 `GET /admin/faq/items?typeCode=XXX`。 - -## 兼容性 - -- **完全向后兼容**:老数据 `typeCode` 默认 NULL,API 仍正常返回(typeLabel 也为 null),前端如不立即接入也不影响现有功能 -- 现有「问题分类(FaqCategory)」侧栏不受影响,继续作为分类组织 UI 保留 - -## 部署后注意 - -后端部署完后需手动清字典 Redis 缓存(Flyway 直接 INSERT 字典不会触发应用层缓存失效): - -```bash -redis-cli -n 0 DEL cache:dict:data:list cache:dict:data:by-type "cache:dict:data:mp_faq_type" -``` - -## 关联 - -- Gitea PR: #1898 -- Gitea Issue: #1896 (已关闭) -- merge commit: 4d14816c44 diff --git a/changelogs/2026-05/08_feat_single_room_diff.md b/changelogs/2026-05/08_feat_single_room_diff.md deleted file mode 100644 index 0619d1f..0000000 --- a/changelogs/2026-05/08_feat_single_room_diff.md +++ /dev/null @@ -1,252 +0,0 @@ -# 价格日历加单房差字段:成人=1 时计入总价 - -> **服务**: hl-product-service-v2(8093)+ hl-order-service-v2(8094) -> **PR**: #1901 -> **Issue**: #1900 -> **日期**: 2026-05-08 -> **影响范围**: 管理端价格日历(所有产品类型)+ GROUP 班期编辑器 + 小程序订单确认页价格 / 明细面板 + 管理端订单详情明细面板 - ---- - -## ⚠️ 关键变化(管理端 + 小程序必读) - -**价格日历 / 班期新增 `singleRoomDiff` 必填字段(单房差)**: - -- 管理端"编辑价格区间"弹窗 + GROUP"班期编辑"弹窗:**4 个价格输入框旁加一列"单房差 ¥xxx"必填输入框**(0 = 不收) -- 小程序订单确认页:**`adultCount == 1` 触发**(严格 == 1,与儿童/小童/幼童数量无关),后端把 `singleRoomDiff` 累加到 `totalPrice` -- 订单详情明细面板:`singleRoomSurcharge > 0` 时多出一行"单房差 ¥xxx",= 0 或老订单缺字段时不展示 -- **定金不变**:比例定金按 `baseTotal`(不含单房差)算;固定/人定金不动 - ---- - -## 一、背景 - -1 个成人单住一房时,实际成本高于双人均摊 — 管理员需要为此场景配置单房差。本期实现: - -1. 价格日历(`product_price_calendar`)+ 班期表(`group_tour_batch`)各加 `single_room_diff DECIMAL(12,2) NOT NULL DEFAULT 0` -2. 算价时**严格** `adultCount == 1` 触发,累加到 `totalPrice` + 写入 `priceBreakdown` JSON -3. 订单明细多一行展示 -4. 定金算法不变(具体见下文 D2/D3) - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 管理端批量保存价格日历 | POST | `/admin/product/{id}/price-calendar/batch` | 请求体加必填字段 | `singleRoomDiff` 必填(@NotNull @DecimalMin("0.00")) | -| 2 | 管理端查询价格日历 | GET | `/admin/product/{id}/price-calendar` | 响应加字段 | 每条记录回传 `singleRoomDiff` | -| 3 | 管理端 GROUP 班期保存 | POST/PUT | (Schedule 系列) | 请求体加必填字段 | `singleRoomDiff` 必填 | -| 4 | 管理端 GROUP 班期查询 | GET | (Schedule 系列) | 响应加字段 | 回传 `singleRoomDiff` | -| 5 | 内部简单报价 | GET | `/internal/product/{productId}/simple-quote` | 响应加 2 字段 | `singleRoomDiff`(配置值)+ `singleRoomSurcharge`(本次实际加价,0 或 = diff) | -| 6 | 内部 GROUP 报价 | GET | `/internal/product/{productId}/group-quote` | 响应加 2 字段 | 同上 | -| 7 | 小程序订单详情 | GET | `/mp/order/{id}` | **行为变更** | `priceBreakdown.items[]` 当 `singleRoomSurcharge > 0` 时多出一行 "单房差" | -| 8 | 管理端订单详情 | GET | `/admin/order/{id}` | 无变化 | admin 端不读 priceBreakdown,只读汇总字段 | -| 9 | 创建订单(C 端 / admin) | POST | `/mp/order/create` 等 | **行为变更** | `OrderInfo.totalPrice` 已包含单房差;`OrderInfo.priceBreakdown` JSON 包含 `singleRoomDiff` + `singleRoomSurcharge` 字段 | - ---- - -## 三、决策点 - -### D1 触发条件(严格) - -``` -if (adultCount == 1) { - singleRoomSurcharge = singleRoomDiff; -} else { - singleRoomSurcharge = 0; -} -``` - -**只看 adultCount 是否严格等于 1**,与儿童 / 小童 / 幼童数量无关。`adultCount == 0` 不触发(下单本来就要求至少 1 成人,@Min(1));`adultCount >= 2` 不触发。 - -### D2 比例定金基数(不含单房差) - -``` -比例定金 = baseTotal × ratio / 100 -其中 baseTotal = totalPrice - singleRoomSurcharge -``` - -**保证"定金计算逻辑不变"**:不含单房差的基础价 × 比例 = 定金;尾款 = totalPrice - 定金(自然就含了单房差)。 - -### D3 固定/人定金不动 - -``` -固定定金 = depositAmount/人 × 定金人头(成人 + 儿童 + 小童) -``` - -与单房差完全解耦。 - -### D7 落库归属(不进 surcharge_amount) - -| 字段 / 表 | 是否含单房差 | -|---|---| -| `order_info.total_price` | **是**(含单房差) | -| `order_info.price_breakdown` JSON | **是**(`singleRoomSurcharge` 字段) | -| `order_info.surcharge_amount` | **否**(语义=后期附加费,与单房差解耦) | -| `order_surcharge` 表 | **否**(不写单房差行) | - -### D9 修订单 `adminEditOrder` 改 4 count **不重算**单房差 - -⚠ **管理端"编辑订单"弹窗改成人/儿童/小童/幼童数后,后端不会重新计算 totalPrice / depositAmount / 单房差**(维持现有契约,Line 140 的 manualPrice 注释已说明:"调价统一走加优惠/加附加费接口")。 - -**影响场景**: -- 用户原下单成人=1 → 含单房差 200,定制师改为成人=2 → totalPrice 仍含 200(应不含),客户多付 200 -- 反之改为成人=1,totalPrice 缺 200(应含),少收 200 - -**应对**:定制师改人数后,如需调整单房差,**通过"加附加费"接口**手动落 `order_surcharge` 一笔(正负皆可)。本期不开发自动重算路径,后续单独工单再做。 - ---- - -## 四、接口详情 - -### 1. 管理端批量保存价格日历 `POST /admin/product/{id}/price-calendar/batch` - -**VO**: `PriceCalendarBatchReqVO` - -#### 入参变化 - -新增字段: - -```json -{ - "startDate": "2026-04-01", - "endDate": "2026-04-30", - "tierSeq": 1, - "priceType": "NORMAL", - "adultSellPrice": 4105, - "childSellPrice": 1865, - "toddlerDiscount": -500, - "infantPrice": 0, - "singleRoomDiff": 200, - "dailyStock": null -} -``` - -| 字段 | 必填 | 校验 | 说明 | -|---|---|---|---| -| `singleRoomDiff` | **必填** | @NotNull @DecimalMin("0.00") | 不传 → 400;< 0 → 400 | - -### 5. 内部简单报价 `GET /internal/product/{productId}/simple-quote` - -**响应 VO 新增字段**: - -```json -{ - "adultPrice": 4105, - "childPrice": 1865, - ..., - "adultTotal": 4105, - ..., - "singleRoomDiff": 200, - "singleRoomSurcharge": 200, - "totalPrice": 4305, - "depositAmount": 100, - "stock": 99 -} -``` - -- `singleRoomDiff` — 价格日历配置的单房差(无论 adultCount 是多少都返回) -- `singleRoomSurcharge` — 本次报价**实际加价金额**:`adultCount == 1 ? singleRoomDiff : 0` -- `totalPrice` 已经包含 `singleRoomSurcharge` -- `depositAmount`(比例定金时)按 `(totalPrice - singleRoomSurcharge) × ratio` 算 - -### 7. 小程序订单详情 `GET /mp/order/{id}` 价格明细行为变更 - -**`priceBreakdown.items[]` 数组结构**: - -```json -{ - "items": [ - {"label": "成人", "unitPrice": 4105, "quantity": 1, "amount": 4105}, - {"label": "儿童", "unitPrice": 1865, "quantity": 0, "amount": 0}, - {"label": "小童", "unitPrice": 1365, "quantity": 0, "amount": 0}, - {"label": "幼童", "unitPrice": 0, "quantity": 0, "amount": 0}, - {"label": "单房差", "unitPrice": null, "quantity": null, "amount": 200} - ] -} -``` - -**单房差行的特殊处理**: -- `unitPrice` / `quantity` 为 `null`(整笔费用,不按人头) -- `amount` 即为本次单房差金额 -- **仅当 `singleRoomSurcharge > 0` 时才出现此行**;= 0 或老订单缺字段时不展示 - ---- - -## 五、前端改动建议(mmg) - -### 管理端 - -#### 价格日历 - "编辑价格区间"弹窗 - -参考用户截图布局,在"幼童"输入框右侧加一列必填输入框: - -``` -[成人 *] [儿童 *] [小童优惠额] [幼童] [单房差 *] -``` - -- placeholder: `¥ 必填,0=不收` -- 提示文案 / hover tip:"成人=1 人下单时叠加到总价" -- 校验:必填 + 不能为负数 - -#### GROUP 班期编辑 - -同上,在班期价格区域加"单房差"必填输入框。 - -### 小程序 - -#### 订单确认页 - -- 总价 / 定金:**直接展示后端返回的 `totalPrice` / `depositAmount`**,前端**不要自己加单房差**(防止双计) -- 明细面板:从后端返回的 `priceBreakdown.items[]` 直接渲染,如有 `label === "单房差"` 一行,展示 `amount`,无 `unitPrice` / `quantity` 列 - -#### 不需要改造 - -- 选择人数控件:不需要改(adultCount = 1 时由后端自动加单房差,前端无感) -- 定金 / 尾款显示:无变化 - -### 管理端订单详情 - -- 不读 `priceBreakdown`,只读 `totalPrice` 汇总字段,无需改造 - ---- - -## 六、向后兼容 - -- **老 calendar / batch 数据**:`single_room_diff` 列 DEFAULT 0,行为=关闭单房差,与原逻辑一致 -- **老订单**:`priceBreakdown` JSON 缺 `singleRoomSurcharge` 字段时,解析端 `isMissingNode()` 跳过,不报错不展示空行 -- **老 App 仍传 `singleRoomDiff` 不会**(本来就没此字段) -- **新建/编辑必填**:管理员每次保存价格区间或班期都得显式填(@NotNull),不允许默认 0 - ---- - -## 七、@mmg 关注点 - -1. 管理端价格日历"编辑价格区间"弹窗加单房差必填输入框 -2. 管理端 GROUP 班期编辑器加同款输入框 -3. 小程序订单确认页明细面板渲染"单房差"行(条件出现) -4. **D9 注意**:管理端"编辑订单"弹窗改成人/儿童/小童/幼童数后,后端**不会**重算单房差。建议在该弹窗加文案提示:"如改人数导致单房差变化,请通过『加附加费』接口手动调整"(可选,本期不强制) - ---- - -## 八、错误码 - -无新增错误码。校验失败统一走 Spring Validation 默认 400 message。 - ---- - -## 九、影响范围(经核确认无影响) - -| 系统 | 是否影响 | 说明 | -|---|---|---| -| 早鸟优惠 | 否 | 落 `order_discount` 表减尾款,与定金无关;`min(totalPrice)` 上限保护 | -| 微信支付 | 否 | 公式 `totalPrice - discount + surcharge` 自洽 | -| 退款 | 否 | refundAmount 是 admin 手输入,代码层不依赖 totalPrice 拆分 | -| 起步价 / 列表"¥xxx 起" | 否 | 不算单房差(展示用) | -| 保险费 | 否 | 按人头 × 保单单价 | -| 12301 上报 | 否 | 团费按 totalPrice 上报,自洽 | -| 合同 PDF | 否 | 团费金额 = totalPrice | -| C 端价格日历视图 | 否 | 只展示成人/儿童/小童/幼童 4 价 | -| 兜底对账 | 否 | `totalPrice - discount + surcharge` 公式自洽 | -| `order_surcharge` 表 / 后期附加费 | 否 | 单房差不进此表(D7) | diff --git a/changelogs/2026-05/08_feat_traveler_auto_type_resolve.md b/changelogs/2026-05/08_feat_traveler_auto_type_resolve.md deleted file mode 100644 index 2e07389..0000000 --- a/changelogs/2026-05/08_feat_traveler_auto_type_resolve.md +++ /dev/null @@ -1,173 +0,0 @@ -# 出行人补全去 travelerType:按生日自动推断 + 不符企微提醒定制师 - -> **服务**: hl-mp-service(8085)+ hl-order-service-v2(8084) -> **PR**: #1892 -> **Issue**: #1889 -> **日期**: 2026-05-08 -> **影响范围**: 小程序补全出行人页 / 管理端出行人录入弹窗 / 管理端编辑订单弹窗 / 修订单接口 / 管理端创建订单接口 - ---- - -## ⚠️ 关键变化(C 端 + 管理端必读) - -**前端不再传 `travelerType`**(请求体里有也会被后端忽略)。后端按 `birthday` 字典 `traveler_type_age_rule` 自动推断: - -- 身份证证件:**`birthday` 由后端从证件号反推**,前端可不传(传了也以证件号为准) -- 非身份证证件(护照/港澳台/其他):**`birthday` 必传**,不传返 **400 错误码 `504006`** "非身份证证件请填写出生日期" -- 身份证号校验位失败:返 **400 错误码 `504007`** "身份证号校验失败" - -**业务规则放宽**:补全阶段不再校验"该类型已加人数 + 1 不得超订单声明"(原 504002 TYPE_COUNT_EXCEEDED 路径已废弃)。如需声明与实际不符的拦截,改由企微提醒定制师在"编辑订单"弹窗调整 4 个 count(`adultCount/childCount/youngChildCount/babyCount`)。 - ---- - -## 一、背景 - -下单时已按类型选过人数(决定价格),补全时又按类型选人是冗余动作。"3 成人 1 儿童下单 + 4 个成人证件补全" 原会被强校验 400 阻断;现在 C 端用户可用 4 个空位顺序录入,后端自动按生日推断 type 写入 `OrderTraveler.travelerType` 列。 - -12301 报备、保险、合同、详情排序的 `travelerType` 全部以"实际生日推断"为准(写入数据库的值即为下游消费的值)。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | C 端新增订单出行人 | POST | `/mp/order/{orderId}/traveler/add` | 请求体删字段 | `travelerType` 废弃,后端自动推断 | -| 2 | C 端修改订单出行人 | PUT | `/mp/order/{orderId}/traveler/{travelerId}` | 请求体删字段 | 同上 | -| 3 | C 端修改订单 | PUT | `/mp/order/{orderId}` | 请求体删字段 | `travelers[].travelerType` 废弃 | -| 4 | 管理端新增订单出行人 | POST | `/admin/order/{orderId}/traveler/add` | 请求体删字段 | 同 #1 | -| 5 | 管理端修改订单出行人 | PUT | `/admin/order/{orderId}/traveler/{travelerId}` | 请求体删字段 | 同 #2 | -| 6 | 管理端创建订单 | POST | `/admin/order/create` | 请求体删字段 | `travelers[].travelerType` 废弃 | -| 7 | 管理端编辑订单 | PUT | `/admin/order/{orderId}` | **行为新增** | 4 个 count 任一被改,且出行人已补全过 → 触发企微提醒比对(若不一致) | -| 8 | 12301 团队上报预填 | GET | `/admin/order/{orderId}/team-report/prefill` | **行为变更** | `peopleNums`/`childNums` 改为按 `touristList` 实际推断派生(原按 OrderInfo 4 count) | - ---- - -## 三、接口详情(关键变化) - -### 1. C 端新增订单出行人 `POST /mp/order/{orderId}/traveler/add` - -**VO**: `MpOrderTravelerSaveReqVO` - -#### 入参变化 - -| 字段 | 旧 | 新 | -|------|----|----| -| `travelerType` | 可选,默认 ADULT | **删除**(后端忽略) | -| `birthday` | 可选 | **身份证场景可不传(后端反推);其他证件必传**,否则 400 `504006` | -| `name`、`idCardNo`、`idCardType`、`phone`、`gender`、`nationality`、`race`、`roomGroupNo`、`emergencyContact`、`emergencyPhone`、`email` | 不变 | 不变 | - -#### 错误码新增 - -| 码 | 文案 | 触发 | -|---|---|---| -| 504006 | 非身份证证件请填写出生日期 | 非身份证证件未传 birthday | -| 504007 | 身份证号校验失败 | 身份证 18 位校验位错误 | -| 504002 | (原 TYPE_COUNT_EXCEEDED) | **本期已废弃**,不再返回 | - -#### 请求示例(身份证) - -```json -{ - "name": "张三", - "idCardType": "ID_CARD", - "idCardNo": "110101199001011234", - "phone": "13800000000" -} -``` - -`birthday` 不传 → 后端从 `idCardNo` 反推 `1990-01-01` → 字典推断 `ADULT`。 - -#### 请求示例(护照,birthday 必传) - -```json -{ - "name": "John Doe", - "idCardType": "PASSPORT", - "idCardNo": "E12345678", - "birthday": "2020-06-01" -} -``` - -不传 `birthday` 则 400 `504006`。 - -#### 出参 - -不变。响应仍含 `travelerType` + `travelerTypeLabel`(后端自动写入)。 - ---- - -### 7. 管理端编辑订单 `PUT /admin/order/{orderId}` —— 行为新增 - -**VO**: `OrderEditReqVO` - -`adultCount/childCount/youngChildCount/babyCount` 4 字段已支持(无变化),编辑订单弹窗"出行人数"区域 UI 已存在。 - -**新增触发**:任一 count 字段非空提交,且订单 `processStatus` 已过 `PENDING_TRAVELER_INFO`(即出行人已补全过) → afterCommit 比对声明 vs 实际 → 不一致触发企微提醒定制师。 - -**何时收到通知**(同样规则也适用接口 #1-#6 补全完成时): -- declared(OrderInfo 4 count)与 actual(OrderTraveler 实际生日推断 type 分布)不一致 -- `OrderInfo.customizerId` 非空,且该 admin 配置了 `wechatUserid` -- 上述两条均满足时 → 企微推送给定制师 + 自动落 `notification_log`(管理后台"日志监控 → 企微客户提醒日志"页面可查) - -**通知文案**: - -``` -【出行人类型不符提醒】 -订单号:HL20260508xxx -产品:草原 5 日游 -联系人:张三 13800000000 -出发日期:2026-06-01 -下单声明:3 成人 1 儿童 0 幼儿 0 婴儿 -实际证件:4 成人 0 儿童 0 幼儿 0 婴儿 -请到管理端订单详情核实并按需调整人数。 -``` - ---- - -### 8. 12301 团队上报预填 `GET /admin/order/{orderId}/team-report/prefill` —— 行为变更 - -**字段**: `peopleNums` / `childNums` - -| 字段 | 旧来源 | 新来源 | -|---|---|---| -| `peopleNums` | `adultCount + childCount + youngChildCount + babyCount`(OrderInfo) | `touristList.size()`(实际推断) | -| `childNums` | `childCount + youngChildCount + babyCount`(OrderInfo) | `touristList.stream().filter(t -> isChild==1).count()` | - -**理由**:声明与实际不符时(用户用错位证件),走 OrderInfo 会导致 12301 平台校验"成人+儿童≠总人数"失败。新口径全部按实际生日推断,自洽通过 12301 校验。 - ---- - -## 四、前端改动建议(mmg) - -### 小程序(C 端) -- 补全出行人页:**移除"成人/儿童/小童/幼儿" Tab/分组**,按下单总人数(`adult+child+young+baby = N`)开 N 个空位顺序录入 -- 补全表单:**身份证证件 birthday 可不显示**(后端反推);**护照/港澳台/其他证件 birthday 输入框必填**,400 错误码 504006 文案直接展示 -- 详情页:`travelerType` + `travelerTypeLabel` 由后端返回,前端继续展示(label 仍是"成人/儿童/幼儿/婴儿",前端可自映射为 UI 用的"成人/儿童/小童/幼儿") - -### 管理端 -- 录入/编辑出行人弹窗:**移除"出行人类型"下拉**(后端自动推断) -- 创建订单:`travelers[].travelerType` 不传(传了后端忽略) -- 编辑订单弹窗"出行人数"4 个 count 输入框**已存在**,**本期无需改 UI** — 定制师收到企微通知后直接进入此弹窗调整即可 - -### 错误码处理 -- `504006 BIRTHDAY_REQUIRED` → toast/dialog 显示文案"非身份证证件请填写出生日期" -- `504007 ID_CARD_INVALID` → toast/dialog 显示文案"身份证号校验失败" - ---- - -## 五、向后兼容 - -- 老 App 仍传 `travelerType` 字段:**Jackson 默认忽略未知字段**(项目已设),不会 400 -- `OrderTraveler.traveler_type` 列保留,Resolver 自动写入,下游消费无变化 -- `TravelerType` 枚举(ADULT/CHILD/YOUNG_CHILD/BABY)保留,前端 label 三套命名不一致是已有问题,后续单独治理 - ---- - -## 六、@mmg 关注点 - -1. 补全页 UI 改造(分组 → 顺序录入) -2. 非身份证场景 birthday 输入框必填校验 -3. 管理端三处弹窗去掉"出行人类型"下拉 -4. 错误码 504006/504007 文案接入 -5. 编辑订单弹窗 UI 不动,仅文案可优化(可选:提示"如收到出行人类型不符提醒,请在此调整人数") diff --git a/changelogs/2026-05/08_fix_cache_banner_dict_review_evict_hotfix.md b/changelogs/2026-05/08_fix_cache_banner_dict_review_evict_hotfix.md deleted file mode 100644 index 703254a..0000000 --- a/changelogs/2026-05/08_fix_cache_banner_dict_review_evict_hotfix.md +++ /dev/null @@ -1,65 +0,0 @@ -# 缓存清理: banner / 字典 / 精选评价 admin 改完小程序立即生效(前端无感) - -> **服务**: hl-user-service (8081) + hl-order-service-v2 (8084) + hl-common-redis -> **PR**: #1855 + #1858 -> **Issue**: #1854 + #1856(根因 + follow-up 批量修) -> **日期**: 2026-05-08 -> **影响范围**: 纯后端缓存清理逻辑,**前端不需要改代码** - ---- - -## ⚠️ 给前端的话 - -**这 2 个 PR 都是后端缓存 bug 修复,前端 0 改动**。但用户体验有提升: - -| 模块 | 修前 | 修后 | -|------|------|------| -| 小程序首页轮播图 | admin 改完最长 5 分钟才生效 | **admin 改完立即生效** | -| 字典(下拉选项 / linkType label 等)| admin 改完 5 分钟内 C 端看到旧选项 | **立即生效** | -| 首页/设计师页精选评价 | 审核员通过/驳回评价后 ~11 分钟不刷新 | **立即生效** | - -如果前端测试时遇到 admin 改完依然要等几分钟才生效的同类问题,**可能还有别的 service 漏改**,直接告诉 wx 起 follow-up 工单。 - ---- - -## 一、根因(prod 实测) - -`MpCacheEvict.deleteByPrefix(prefix)` 内部强行加 `mp:` 前缀 SCAN(`mp:{prefix}*`),但下面 3 个 service 自己用 `depsManager.putWithDeps(KEY, ...)` 写入的 cache key **不带 `mp:` 前缀**,导致 evict 完全 SCAN 不到自己的 key。 - -兜底的 `depsManager.invalidateSource(...)` 也救不了 — prod 实测反向索引 SET 实际为空(总依赖=0)。结果 admin 改完只能等 cache 自然 TTL 过期。 - ---- - -## 二、修复 - -3 处 service 在 `cacheEvictAfterCommit.schedule(...)` lambda 加显式 `redisTemplate.delete(KEY)` 兜底: - -| Service | 文件 | KEY | -|---|---|---| -| BannerService | `hl-user-service` | `banner:active:list:v3` | -| SysDictService(6 处)| `hl-user-service` | `cache:dict:data:{dictType}` | -| FeaturedReviewCache | `hl-order-service-v2` | `review:featured:limit:*`(SCAN 自删)| - -配套加固:`MpCacheEvict.java` 类 javadoc 加红字警告,防止后续新代码继续踩同坑。 - ---- - -## 三、变更接口清单 - -**无 API 变更**。所有 admin 写接口、所有 mp 读接口路径/参数/响应**完全不变**。仅缓存清理逻辑变化。 - ---- - -## 四、后续 follow-up(本次不动) - -- **#1860 (P1)**: `DependencyAwareCacheManager.putWithDeps` 反向索引 SADD 失效根因排查 -- **#1861 (P2)**: D5 删除 MpCacheEvict 重构,全部走 invalidateSource 单一路径 - ---- - -## 五、测试 - -- BannerServiceTest 31/31 全绿 -- SysDictServiceTest 27/27 全绿 -- FeaturedReviewCacheTest 11/11 全绿 -- 共 69/69 PASSED diff --git a/changelogs/2026-05/08_fix_mp_arrival_batch_error_message_direction.md b/changelogs/2026-05/08_fix_mp_arrival_batch_error_message_direction.md deleted file mode 100644 index b9964a7..0000000 --- a/changelogs/2026-05/08_fix_mp_arrival_batch_error_message_direction.md +++ /dev/null @@ -1,152 +0,0 @@ -# 🐛 错误文案修复：到达/返程批次校验提示不再混淆 - -**更新时间**: 2026-05-08 17:45 -**PR**: #1894 / Issue #1893 -**服务**: hl-mp-service (端口 8085) - ---- - -## 变了什么（前端视角） - -`POST /mp/order/{orderId}/arrival/batch` 提交到达信息（`direction=ARRIVAL`）时， -若某批次 `travelerIds` 为空，原来错误 toast 错误地显示「**返程**信息」。 - -本次修复让 message 文案与实际 direction 一致。**错误码 code 不变（620001 / 620002）**， -只是 message 字符串更准确——前端只要是直接 toast 展示后端 message 的写法无需任何改动。 - -### 文案对照表 - -| 场景 | 旧文案 | 新文案 | -|------|--------|--------| -| body 空（`null` 或 `[]`） | 请添加至少一批**返程**信息 | 请添加至少一批**批次** | -| `direction=ARRIVAL`，第 N 批 travelerIds 空 | 第 N 批**返程**信息：请选择至少一位乘坐人员 | 第 N 批**到达**：请选择至少一位乘坐人员 | -| `direction=DEPARTURE`，第 N 批 travelerIds 空 | 第 N 批**返程**信息：请选择至少一位乘坐人员 | 第 N 批**返程**：请选择至少一位乘坐人员（行为不变，字符串更简洁） | -| direction 缺失 / 未知值，第 N 批 travelerIds 空 | 第 N 批**返程**信息：请选择至少一位乘坐人员 | 第 N 批**批次**：请选择至少一位乘坐人员（兜底） | - ---- - -## 前端要改的地方 - -**正常情况（直接 toast 后端 message）**：无需改动。 - -**需要检查的情况**：如果前端代码对错误 message 做了**字符串匹配/包含判断**（例如用来走不同分支逻辑），请检查并更新： - -- 若有类似 `if (msg.includes('返程信息'))` 的判断 → 原匹配「请添加至少一批返程信息」或「第 N 批返程信息」的逻辑**可能失效**，需改为不依赖具体文本，或更新匹配目标 -- 若有类似 `msg === '请添加至少一批返程信息'` 的精确匹配 → 必须更新 - -常规弹 toast 代码无需任何修改。 - ---- - -## 涉及的接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 全量替换批次信息 | POST | `/mp/order/{orderId}/arrival/batch` | 🐛 错误文案修复 | 仅 message 文案变更，code / 请求体 / 响应结构零变化 | - ---- - -## 接口详细定义 - -### POST `/mp/order/{orderId}/arrival/batch` — 全量替换批次信息 - -- **使用场景**：小程序「填写到达/返程信息」页，用户点击「确认提交」 - -- **路径参数**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| orderId | Long | 是 | 订单 ID | - -- **请求参数（Query）**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| direction | String | 是 | `ARRIVAL`（到达）/ `DEPARTURE`（返程） | - -- **请求体（JSON Array）**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| transportType | String | 是 | 交通方式：`SELF_DRIVE` / `FLIGHT` / `TRAIN` | -| travelerIds | Array\<Long\> | 是 | 出行人 ID 列表，不能为空数组 | -| flightNumber | String | 否 | 航班号（transportType=FLIGHT 时填写） | -| trainNumber | String | 否 | 车次号（transportType=TRAIN 时填写） | -| arrivalTime | String | 否 | 到达/出发时间，格式 `yyyy-MM-dd HH:mm` | - -- **请求示例（到达，两批）**： - -```json -[ - { - "transportType": "FLIGHT", - "travelerIds": [1001, 1002], - "flightNumber": "MU5100", - "arrivalTime": "2026-06-01 14:30" - }, - { - "transportType": "TRAIN", - "travelerIds": [1003], - "trainNumber": "G1234", - "arrivalTime": "2026-06-01 18:00" - } -] -``` - -- **响应（成功）**： - -```json -{ - "code": 200, - "msg": "success", - "data": null -} -``` - -- **响应（失败示例）**： - -```json -{ - "code": 620002, - "msg": "第 1 批到达：请选择至少一位乘坐人员", - "data": null -} -``` - ---- - -## 错误码 / 校验规则 - -| Code | 触发条件 | direction=ARRIVAL message | direction=DEPARTURE message | -|------|----------|---------------------------|-----------------------------| -| `620001` | body 为 null 或空数组 | 请添加至少一批批次 | 请添加至少一批批次 | -| `620002` | 第 N 批 `travelerIds` 为 null 或空数组 | 第 N 批到达：请选择至少一位乘坐人员 | 第 N 批返程：请选择至少一位乘坐人员 | - -> 说明：620001 在 body 空时拿不到 direction，统一用「批次」兜底词；620002 按请求中的 direction 动态拼词。 - -### 边界行为 - -| 输入 | 结果 | -|------|------| -| body=null | 620001 | -| body=[] | 620001 | -| body=[{travelerIds:null}]，direction=ARRIVAL | 620002 "第 1 批到达：请选择至少一位乘坐人员" | -| body=[{travelerIds:[]}]，direction=DEPARTURE | 620002 "第 1 批返程：请选择至少一位乘坐人员" | -| body=[{travelerIds:[1001]}, {travelerIds:[]}]，direction=ARRIVAL | 620002 "第 2 批到达：请选择至少一位乘坐人员" | -| body=[{travelerIds:[1001]}, {travelerIds:[1002]}] | 200，走 Feign 正常处理 | - ---- - -## 兼容性说明 - -- **向后兼容**：是。请求结构（字段名/类型/必填）零变化 -- **错误码 code**：不变（620001 / 620002） -- **是否需要数据迁移**：否 -- **是否需要重启服务**：是（见下方） - ---- - -## 补充说明 - -本次修复是 PR #1830（错误友好化）的文案准确性 follow-up，不引入新的接口或字段。 -前次 changelog 见 `07_fix_mp_arrival_batch_validation_friendly.md`，两个 PR 相互独立可分别部署。 diff --git a/changelogs/2026-05/08_fix_mp_message_summary_sort_stable.md b/changelogs/2026-05/08_fix_mp_message_summary_sort_stable.md deleted file mode 100644 index 7bfe8f7..0000000 --- a/changelogs/2026-05/08_fix_mp_message_summary_sort_stable.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -date: 2026-05-08 -type: backend-fix -module: hl-mp-service/message -priority: low -notify: ["@mmg"] -status: tested-passed -restart_service: hl-mp-service -gitea_pr: 1862 -gitea_issue: [1857] ---- - -# /mp/message/summary 接口排序稳定化 - -## 现象 - -小程序消息中心首页消息分类汇总接口 `GET /mp/message/summary` 返回的分类列表偶发出现顺序不一致,同一账号多次调用同一份数据,前端展示的分类顺序会跳变。 - -## 根因 - -Service 层查询 message_category 时只按 `sort_order ASC` 排序,当多条记录 `sort_order` 相同时,MySQL 不保证返回顺序稳定 → 不同次查询可能返回不同顺序。 - -修复方式:加二级排序 `id ASC` 作为 tie-breaker,保证同 `sort_order` 内顺序稳定。 - -## 前端可见变化 - -**API 路径/响应结构/字段/类型完全不变**,前端无需任何改动。 - -行为变化(更可预期): -- 改前:同 `sort_order` 的分类顺序可能跳变 -- 改后:稳定按 `sort_order ASC, id ASC` 返回 - -## 重启服务 - -测试服已部署:`hl-mp-service`(PR #1862 合 dev → deploy panel)。 - -## 关联 - -- Closes wx/HL #1857 -- PR #1862 diff --git a/changelogs/2026-05/08_fix_order_v2_admin_departure_date_filter.md b/changelogs/2026-05/08_fix_order_v2_admin_departure_date_filter.md deleted file mode 100644 index 814fdf3..0000000 --- a/changelogs/2026-05/08_fix_order_v2_admin_departure_date_filter.md +++ /dev/null @@ -1,43 +0,0 @@ -# fix(order-v2): admin 订单管理「出发日期」筛选后端补齐 - -- **PR**: [#1872](https://git.1814.love:8443/wx/HL/pulls/1872) -- **Issue**: [#1865](https://git.1814.love:8443/wx/HL/issues/1865) -- **服务**: hl-order-service-v2 -- **端**: admin -- **影响**: 非破坏性，仅新增两个可选 query 参数 - -## 现象（修复前） - -管理后台「订单管理」列表页筛选「出发日期」无效，前端传值后端忽略。 - -## 根因 - -`OrderPageReqVO` 缺 `departureDateStart/End` 字段，前端传参直接被框架丢弃；Service/Mapper 也未处理 `departureDate` 范围筛选。 - -## 接口变化 - -`GET /admin/order/list` - -新增两个**可选** query 参数（全部省略 = 不筛选，行为与修复前一致）： - -| 参数 | 类型 | 格式 | 示例 | 说明 | -|------|------|------|------|------| -| `departureDateStart` | `LocalDate` | `yyyy-MM-dd` | `2026-05-08` | 出发日期起（闭区间） | -| `departureDateEnd` | `LocalDate` | `yyyy-MM-dd` | `2026-05-08` | 出发日期止（闭区间） | - -筛选语义： -- 双值传入 → `WHERE departure_date BETWEEN ? AND ?`（同日 OK） -- 仅起 → `WHERE departure_date >= ?` -- 仅止 → `WHERE departure_date <= ?` -- 全空 → 不附加该条件 - -## 前端配合 - -- mmg 侧无破坏性改动；如已有日期范围控件直接 bind 到 `departureDateStart` / `departureDateEnd` 即可 -- 前端日期控件传 `yyyy-MM-dd` 字符串（不带时分秒） - -## 不动项 - -- `createTimeStart` / `createTimeEnd`（下单时间）筛选行为不变 -- 其他 productType 通用，不限定小蒙马 -- mp 端 / designer 端订单列表本期不动（独立 mapper 方法，前端 UI 也无此筛选） diff --git a/changelogs/2026-05/08_fix_product_v2_toddler_price_subtract.md b/changelogs/2026-05/08_fix_product_v2_toddler_price_subtract.md deleted file mode 100644 index e8da0c8..0000000 --- a/changelogs/2026-05/08_fix_product_v2_toddler_price_subtract.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -date: 2026-05-08 -type: backend-fix -module: hl-product-service-v2/pricing -priority: high -notify: ["@mmg"] -status: tested-passed -restart_service: hl-product-service-v2 -gitea_pr: 1876 -gitea_issue: [1870] ---- - -# 小童价格计算方向错误修复(add → subtract) - -## 现象 - -产品价格配置:儿童=3000、小童(优惠差价)=1000,小程序应显示 toddlerPrice=2000(=3000-1000),实际显示 4000(=3000+1000),方向反了。 - -## 根因 - -字段 `toddler_discount` 历史 schema COMMENT 标「负数」,但实际业务/前端传的是正数差价。后端 4 处用 `childPrice.add(toddlerDiscount)` 拼接,正数相加结果反向。 - -## 修复 - -1. 4 处计算 `add → subtract`(传入参数 toddlerDiscount 仍为正数,语义自然): - - `ProductPricingService.java:704`(核心报价) - - `GroupTourBatchService.java:276`(admin 团报价) - - `InternalProductService.java:281` / `:383`(mp 报价 / mp 班期报价) -2. `ProductPricingService.java:322` 校验去掉 `.abs()`,正数语义直接 compareTo -3. schema.sql 两表(`product_price_calendar`、`group_tour_batch`)`toddler_discount` COMMENT 改为「正数,小童比儿童便宜多少元」 -4. 新建 Flyway `V20260508_001__fix_toddler_discount_comment_and_normalize_negative.sql`:改 COMMENT + 历史负数 ABS 兜底 -5. 单测 7 处期望同步:`setToddlerDiscount(-X)` → `setToddlerDiscount(X)`,数学等价 - -## 前端可见变化 - -**API 字段名/路径/响应结构无变化**,前端无需改代码。但 toddlerPrice **数值会变化**: - -- 改前:小童价 = 儿童价 + 差价(显示偏高) -- 改后:小童价 = 儿童价 − 差价(符合产品语义) - -涉及接口: -- mp 报价(`InternalProductService.quote*`) -- mp 班期报价 -- admin 团产品报价 -- admin 核心报价 - -如果前端 UI 上有写死的小童价格预期(如测试用例硬编码、截图对比),请同步 review。 - -## 兜底保留 - -- `max(BigDecimal.ZERO)` 兜底逻辑保留(防 toddlerDiscount > childPrice 时变负数) -- Flyway 历史数据兜底:`UPDATE ... SET toddler_discount = ABS(toddler_discount) WHERE toddler_discount < 0` - -## 测试 - -- 本地 `mvn -pl hl-product-service-v2 test`:1128 全过(0 failure / 0 error) -- 4 处计算路径 + Flyway + schema COMMENT 全部一致 - -## 重启服务 - -测试服需重启:`hl-product-service-v2`(PR #1876 合 dev → deploy panel)。 - -## 关联 - -- Closes wx/HL #1870 diff --git a/changelogs/2026-05/08_fix_resource_roomtype_disable_dimension.md b/changelogs/2026-05/08_fix_resource_roomtype_disable_dimension.md deleted file mode 100644 index cbea70f..0000000 --- a/changelogs/2026-05/08_fix_resource_roomtype_disable_dimension.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -date: 2026-05-08 -type: backend-fix -module: hl-resource-service/hotel -priority: medium -notify: ["@mmg"] -status: tested-passed -restart_service: hl-resource-service -gitea_pr: 1846 -gitea_issue: [1842] ---- - -# 房型禁用校验维度修复(ROOM_TYPE 而不是 HOTEL) - -## 现象 - -用户禁用一个房型时,即使该房型本身没被任何产品引用,只要同酒店其他房型被引用就会被拦截,提示"该资源正被以下上架产品使用..."。 - -## 根因 - -PR #1815 引入 `RoomTypeService.submitRoomTypeApproval` 禁用校验时,因 product 侧 endpoint 当时不支持 ROOM_TYPE 维度,临时用 HOTEL 维度兜底: - -```java -// 改前 -referenceCheckHelper.throwIfInUse("HOTEL", rt.getHotelId(), HotelErrorCode.ROOM_TYPE_DISABLE_IN_USE); -``` - -PR #1838 实现 endpoint + ROOM_TYPE 路由后,本 PR 把维度修正回: - -```java -// 改后 -referenceCheckHelper.throwIfInUse("ROOM_TYPE", roomTypeId, HotelErrorCode.ROOM_TYPE_DISABLE_IN_USE); -``` - -## 前端可见变化 - -**API 路径/响应格式无变化**,业务码仍是 `ROOM_TYPE_DISABLE_IN_USE` (310206)。前端无需任何改动。 - -精确度提升: -- 改前:酒店 H 任一房型被引用,禁用 H 下任何房型都被拦 -- 改后:只有该房型本身被引用才被拦,提示的产品名也只列引用了该房型的产品 - -## 测试服 round-trip 实测(同酒店 2 房型) - -``` -酒店: 呼伦贝尔香格里拉大酒店(2023714929877450753) -- RoomType 大床房 (3002000000000000013): 提示 2 个产品(测试定制wx-01、呼伦贝尔草原深度定制·3天2晚家庭私享团) -- RoomType 普通标间 (2023727403196502017): 提示 1 个产品(冻干粉发短信给) -``` - -两个 RoomType 引用产品数不同 → 证明 ROOM_TYPE 维度精确(若是 HOTEL 维度两次响应会一致)。 - -## 重启服务 - -测试服已部署:`hl-resource-service`(PR #1846 合 dev → deploy panel)。 - -## 关联 - -- Closes wx/HL #1842 -- PR #1815 / PR #1838 / PR #1841 follow-up diff --git a/changelogs/2026-05/08_refactor_resource_extract_reference_check_helper.md b/changelogs/2026-05/08_refactor_resource_extract_reference_check_helper.md deleted file mode 100644 index 25e43e0..0000000 --- a/changelogs/2026-05/08_refactor_resource_extract_reference_check_helper.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -date: 2026-05-08 -type: backend-refactor -module: hl-resource-service -priority: low -notify: ["@mmg"] -status: tested-passed -restart_service: hl-resource-service -gitea_pr: 1841 -gitea_issue: [] ---- - -# 资源服务 ResourceReferenceCheckHelper 抽取(纯重构,前端无感) - -## 背景 - -PR #1838 引入 fail-closed 后,resource service 11 个文件 16 处调用点重复 8-10 行 `productFeignClient.checkResourceInUse + isSuccess + throw + getData + 被引用 throw` 模板。 - -PR #1841 抽取到 `ResourceReferenceCheckHelper`,2 个公开方法: -- `throwIfInUse(type, id, errorCode)` — 单删除/下架场景 -- `getReferencingProducts(type, id)` — batchDelete 累积场景 - -每处调用点 8-10 行 → 1 行 helper 调用,**净减 178 行**(35 文件 +177/-355,加 helper+test +271 = 净增 87)。 - -## 前端可见变化 - -**完全无变化** — API 行为/响应/业务码全部保持一致。前端不需要任何改动。 - -测试服 round-trip 实测 (PR #1838 同样反例): -``` -DELETE /admin/scenic/spots/batch ids=[3001000000000000016] -HTTP=200 code=200 -data={successCount:0, deniedIds:["3001000000000000016"], - deniedReasons:["被产品使用: 结婚不回家、带孩子， 看一次真正的草原。、...(13 个产品名)"]} -post-check GET 景区仍存在 ✅ -``` - -## 重启服务 - -测试服已部署:`hl-resource-service`(PR #1841 合 dev → deploy panel)。 - -## 改造范围 - -11 个 service 文件 16 处调用点全部统一改用 helper: - -- ScenicSpotService 4 处(updateStatus / batchUpdateStatus / batchDelete / submitApproval) -- StaffService 2 处 / SuppliesService 2 处 -- HotelService / RoomTypeService / RestaurantService / ActivityService / ServiceItemService / SuppliesComboService / VehicleModelService / CostItemService 各 1 处 - -22 个既有 service test 同步切 mock(`ProductFeignClient` → `ResourceReferenceCheckHelper`)。 - -## 关联 - -- PR #1838 / #1839 / Issue #1821(纯重构 follow-up,无新工单) - -## Follow-up(本 PR 不修) - -- 余下 PR #1838 follow-up 项: RoomType 禁用按 HOTEL 维度校验语义偏严 / `product_itinerary_node(resource_type, resource_id)` 复合索引 / batchDelete TOCTOU 时序问题 -- 单测加 H2 集成测试或 @MybatisPlusTest 真跑 SQL 防止 mock 单测假阳(memory `experience/qa/mock-tests-pass-cr-pass-but-prod-schema-mismatch-real-deletes-2-resources.md`) diff --git a/changelogs/2026-05/09_feat_admin_customizers-add-enterprise-wechat-name.md b/changelogs/2026-05/09_feat_admin_customizers-add-enterprise-wechat-name.md deleted file mode 100644 index 288c2f8..0000000 --- a/changelogs/2026-05/09_feat_admin_customizers-add-enterprise-wechat-name.md +++ /dev/null @@ -1,139 +0,0 @@ -# 后端 feat 通知 — `/admin/user/customizers` 加企微姓名字段(产品分享下拉显示中文真名) - -**日期**: 2026-05-09 -**类型**: 后端 feat (产品分享体验优化) -**模块**: 产品管理 → 产品列表 → 分享产品(ShareModal) -**通知**: @mmg -**前端是否需改动**: **是**(label 一行改动) -**严重性**: 体验级(P3) - ---- - -## ⚠️ 关键变化 - -针对用户反馈"产品分享下拉显示英文 username (admin/test_admin/mmg/qulili/bozhihe) 不直观,应显示企业微信真名(中文)",**后端 PR #1930 已上线**: - -- `GET /admin/user/customizers` 响应每条新增 `enterpriseWechatName` 字段(可空 String) -- 绑了企微的 admin → 返该 admin 在企微通讯录里的中文姓名(如「王骁」「米明光」「曲丽莉」) -- 未绑企微 / 企微 ID 是脏数据(wechat_user 表查不到) → 返 `null`,前端按约定 fallback 到 `username` - -前端只需改 ShareModal.vue 一行 label 拼接逻辑。 - ---- - -## 后端接口契约(更新) - -### `GET /admin/user/customizers` - -**Response** `Result<List<CustomizerSimpleVO>>`: - -```json -{ - "code": 200, - "data": [ - { "adminId": 1001, "username": "admin", "enterpriseWechatName": null, "avatar": null }, - { "adminId": 1002, "username": "test_admin", "enterpriseWechatName": null, "avatar": null }, - { "adminId": "2021059720172838914", "username": "wx", "enterpriseWechatName": "王骁", "avatar": "https://..." }, - { "adminId": "2027579942221352962", "username": "mmg", "enterpriseWechatName": "米明光", "avatar": "https://..." }, - { "adminId": "2033349904889524226", "username": "qulili", "enterpriseWechatName": "曲丽莉", "avatar": null }, - { "adminId": "2033349906135203841", "username": "bozhihe", "enterpriseWechatName": "卜志鹤 18847040111", "avatar": null } - ] -} -``` - -| 字段 | 类型 | 必返 | 说明 | -|------|------|------|------| -| `data[].adminId` | Long\|String | ✅ | 注意雪花 ID 是 String,要 String 处理防精度丢失(已在前一条 changelog 提过) | -| `data[].username` | String | ✅ | admin 登录名 | -| `data[].enterpriseWechatName` | String | **新增** | 企微真名,可空 | -| `data[].avatar` | String | ❌ | admin_user 自身头像 | - -字段顺序保持 `adminId / username / enterpriseWechatName / avatar`(JSON 顺序非强约束,但 Swagger 文档与 ApiModelProperty 顺序一致)。 - ---- - -## 前端建议改法 - -文件:`hl-ui/src/views/product/list/components/ShareModal.vue` - -把 line ~93-96 的 label 拼接从: - -```js -.map((u) => ({ - label: u.username, - value: String(u.adminId), -})) -``` - -改为: - -```js -.map((u) => ({ - label: u.enterpriseWechatName || u.username, // ← 优先企微真名,fallback username - value: String(u.adminId), -})) -``` - -可选:为了让选择更直观,可以在企微名后追加一行小字 username,如: - -```js -label: u.enterpriseWechatName ? `${u.enterpriseWechatName}（${u.username}）` : u.username -``` - -(具体形式由前端 UX 决定,后端不强制。) - ---- - -## ✅ 已经测试服 round-trip 验证(2026-05-09 21:51) - -经 `https://api.test.1814.love:9443/admin/user/customizers` + SUPER_ADMIN token 实测 11 条抽样,DB ↔ 接口完全一致: - -``` -adminId username DB expected wxname 接口返 enterpriseWechatName ✅ -1001 admin NULL null ✅ -1002 test_admin NULL (脏数据 LEFT JOIN 不到) null ✅ -2021059720172838914 wx 王骁 王骁 ✅ -2027579942221352962 mmg 米明光 米明光 ✅ -2033349904889524226 qulili 曲丽莉 曲丽莉 ✅ -2033349906135203841 bozhihe 卜志鹤 18847040111 卜志鹤 18847040111 ✅ -2033349907380940801 pantingting 潘婷婷18604706500 潘婷婷18604706500 ✅ -2033349908622426113 wangyu 呼籁旅行-王宇 呼籁旅行-王宇 ✅ -2033349910786715649 lixiaosong 小松 小松 ✅ -2033350011374485506 zhangjing 张晶13354709299 张晶13354709299 ✅ -2046065465288949761 cz 蒋雨莲 蒋雨莲 ✅ -``` - -注意一些定制师的 wechat_user.name 自带电话号(如「卜志鹤 18847040111」「潘婷婷18604706500」「张晶13354709299」)— 那是企微通讯录里的原始数据,本接口原样返回,前端展示时如不希望带号码可在前端做正则截断,但后端不做加工。 - ---- - -## 不影响范围 - -- 接口路径 / Method 零变化 -- 鉴权逻辑零变化 -- N+1 已防御(批量 IN 查 wechat_user,1 次 SQL),不会因为 admin 数量变多导致性能劣化 -- `/admin/user/designers` 接口(C 端订单展示用)零影响,继续过滤 active+企微非空,本次只改 customizers - ---- - -## 相关 PR / 历史 - -| PR | 说明 | 状态 | -|----|------|------| -| #1919 | 实现 admin 分享产品功能(Closes #1918) | ✅ 已合 | -| #1924 | 修复 PR #1919 暴露的 2 个回归(中文括号 + fee_item 全量) | ✅ 已合 + 已部署 | -| **#1930** | **本通知关联**:customizers 接口加 enterpriseWechatName(企微真名) | ✅ 已合 + 已部署 + QA 通过 | - ---- - -## 历史 changelog 关系 - -| changelog 文件 | 说明 | 是否仍有效 | -|--------|------|------| -| `09_frontend_notice_admin_product-share-use-customizers-endpoint.md` | 通知前端切到 `/admin/user/customizers` | ✅ 有效,本通知是其 follow-up | -| `09_fix_admin_product-share-2-regressions.md` | PR #1924 修复后端 2 个回归 | ✅ 有效,与本通知正交 | -| **本通知 `09_feat_admin_customizers-add-enterprise-wechat-name.md`** | customizers 加企微姓名字段 | ✅ 最新,前端需配合改 1 行 | - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md b/changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md deleted file mode 100644 index c0ea176..0000000 --- a/changelogs/2026-05/09_feat_admin_order_detail_single_room_surcharge.md +++ /dev/null @@ -1,98 +0,0 @@ -# admin 订单详情接口暴露单房差金额字段 - -> **服务**: hl-order-service-v2(8094) -> **PR**: #1904 (Refs #1900) -> **日期**: 2026-05-09 -> **影响范围**: 管理端订单详情页 - ---- - -## ⚠️ 关键变化 - -**admin 订单详情接口** `GET /admin/order/{orderId}` **新增**响应字段 `singleRoomSurcharge`(`BigDecimal`,`@Nullable`)。 - -PR #1901 实现单房差功能后,只有 mp 端订单详情(`MpOrderDetailVO.priceBreakdown.items`)展示了"单房差"行,**管理端订单详情**(`OrderDetailVO`)看不到单房差金额(只读 totalPrice/surchargeAmount/discountAmount 汇总)。本 PR 补上 admin 端字段。 - ---- - -## 一、变更接口 - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 1 | 管理端订单详情 | GET | `/admin/order/{orderId}` | 响应 +1 字段 `singleRoomSurcharge: BigDecimal` | - -## 二、字段语义 - -| 场景 | `singleRoomSurcharge` 值 | -|------|---------| -| 下单时 `adultCount==1` 且产品/班期配了单房差 | 该单房差金额(>0,如 `200.00`) | -| 下单时 `adultCount>=2` 不触发单房差 | `null` | -| 老订单(PR #1901 上线前下的)`priceBreakdown` JSON 缺字段 | `null` | -| 老订单 `priceBreakdown=null` | `null` | -| `priceBreakdown` JSON 含字段但值为 0 | `null`(零值不展示,与 mp 端口径对齐) | - -**口径**:与 mp 端 `MpOrderDetailVO.priceBreakdown.items` 中"单房差"行的展示口径完全对齐(>0 才视为有效),通过 `MpOrderDetailAssembler.parseSingleRoomSurcharge` 复用解析能力,**单一来源**。 - -## 三、响应示例 - -**有单房差订单**: - -```json -{ - "code": 200, - "data": { - "orderId": "2052xxxxxxxxxxxxx", - "totalPrice": 4180.00, - "surchargeAmount": null, - "singleRoomSurcharge": 200.00, - "depositAmount": 398.00, - ... - } -} -``` - -**老订单 / 不触发场景**: - -```json -{ - "code": 200, - "data": { - "orderId": "2052xxxxxxxxxxxxx", - "totalPrice": 1500.00, - "surchargeAmount": null, - "singleRoomSurcharge": null, - ... - } -} -``` - -## 四、前端改动建议(mmg 管理端) - -订单详情页**金额构成区域**(目前展示总价 / 优惠 / 附加费 / 订金)新增一行: - -``` -单房差: ¥200.00 (仅当 singleRoomSurcharge > 0 / 非 null 时展示) -``` - -- `null` → 整行隐藏(老订单 / 不触发场景) -- `>0` → 展示,金额格式 `¥XXX.XX` - -文案/位置可参考既有"附加费"行(`surchargeAmount`)样式,但二者**不互通**(单房差不进 surchargeAmount,语义独立)。 - -## 五、向后兼容 - -- 老 admin 前端不读 `singleRoomSurcharge` → 字段被忽略,不报错 -- 老订单 `priceBreakdown` JSON 缺字段 → 接口返 `null`,前端按 `null` 隐藏 -- mp 端订单详情**完全不变**(本 PR 不动 mp 端) - -## 六、测试覆盖 - -- `OrderDetailQueryServiceTest` +3 用例(JSON 含字段 / 缺字段 / null) -- `MpOrderDetailAssemblerTest` +4 用例(parseSingleRoomSurcharge: null/空/缺字段/=0/>0) -- 测试服已部署 dev:`GET /admin/order/{老订单id}` 返 `singleRoomSurcharge: null` 验证字段路径打通(图省略,字段已在 RespVO keys 里) - -## 七、@mmg 关注点 - -1. 管理端订单详情页金额区加"单房差"行(条件展示) -2. 字段命名与 mp 端 `priceBreakdown.items` 中 label="单房差" 行的 amount 对齐 -3. 老订单字段为 null 时整行隐藏 diff --git a/changelogs/2026-05/09_feat_admin_product-share-copy-to-designer.md b/changelogs/2026-05/09_feat_admin_product-share-copy-to-designer.md deleted file mode 100644 index f4a1076..0000000 --- a/changelogs/2026-05/09_feat_admin_product-share-copy-to-designer.md +++ /dev/null @@ -1,230 +0,0 @@ -# admin 产品分享 = 复制产品给定制师 (后端实现) - -> **服务**: hl-user-service (8081) + hl-product-service-v2 (8083) -> **PR**: #1919 (合并到 dev a18329b7) -> **Issue**: #1918 -> **日期**: 2026-05-09 -> **影响范围**: admin 产品列表「分享」按钮 → 「分享产品」弹窗 → 选目标定制师 → 复制产品给该定制师 - ---- - -## ⚠️ 关键澄清(请 mmg 与上一条撤回通知一起看) - -本日早些时候有一条已撤回的 changelog `09_frontend_notice_admin_product-share-remove-target-user-step.md`,误以为「分享产品弹窗的目标用户选择步骤」是 url-scheme 接口的多余步骤,要前端删掉。**那个判断针对的是 `POST /admin/wxapp/share/url-scheme` 这个老接口**(生成微信短链),与本通知**没有关系**。 - -**真相是**: 你看到的「分享产品 — 选目标用户」弹窗对应的是**另一个新功能** — admin 把自己负责的产品复制一份给指定的定制师,让定制师在自己工作台里看到这个产品(状态草稿,需重新编辑)。这个**后端原本不存在**,本 PR #1919 才补齐。 - -也就是说: -- 你的弹窗 UI 在 master 上确实有(我们之前调研错了),不要删 -- 它需要调用的是**新增**的 `POST /admin/product/item/{id}/share` 接口,而不是老的 url-scheme -- 目标用户下拉**改调** `GET /admin/user/customizers`(本 PR 新增) - ---- - -## 一、背景 - -业务场景: admin (通常是超管/客服)在产品列表上看到一个产品(可能是从供应商那里整理好的、或自己之前建的),想转给某个定制师让 ta 接手维护/二次编辑。复制后: -- 定制师在自己的产品列表里看到这个产品(`createdBy` = 该定制师) -- 状态自动是 DRAFT(草稿),让定制师确认/调整后再发布 -- 标题加`(来自 {操作人 username} 的分享)`后缀,让定制师知道来源 -- 价格日历**不复制**(让定制师按自己客户/批次重新设置) -- 关联的产品线也复制一份独立副本(给定制师独立空间,改产品线不影响别人) - -权限走标准权限点 `PRODUCT_SHARE`(放在 `admin_permission` 表),默认绑定 SUPER_ADMIN + ADMIN 两个角色。**不写死角色** — 后续业务侧可在权限管理页面给任意角色绑该权限点。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 目标定制师下拉(分享专用) | GET | `/admin/user/customizers` | 新增 | 返「角色含 CUSTOMIZER」的所有 admin,**无 status / 企微绑定过滤** | -| 2 | 分享产品给定制师 | POST | `/admin/product/item/{id}/share` | 新增 | 复制产品+产品线到目标定制师名下 | - ---- - -## 三、接口详情 - -### 1. 目标定制师下拉 `GET /admin/user/customizers` - -弹窗里「目标用户」下拉应改调本接口(替换之前误调的 `/admin/user?page=1&pageSize=100`)。 - -**请求**: 无参 (Header 带 admin token) - -**响应** `Result<List<CustomizerSimpleVO>>`: - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": [ - { "adminId": 1002, "username": "alice", "avatar": "https://..." }, - { "adminId": 1015, "username": "bob", "avatar": "" } - ] -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `data[].adminId` | Long | 定制师 admin_user.admin_id,作为分享接口的 `targetAdminId` | -| `data[].username` | String | 定制师用户名(下拉显示用) | -| `data[].avatar` | String | 头像 URL,**取自 admin_user.avatar 字段**(不查企微 wechat_user 也不查 designer_profile),没有时返空字符串 `""` | - -**与已有 `/admin/user/designers` 的区别(选用本接口的原因)**: - -| 维度 | `/admin/user/customizers`(本接口) | `/admin/user/designers`(已有接口) | -|------|-----------------------------------|-----------------------------------| -| 过滤 status | **不过滤** (LOCKED / DISABLED 也返回) | 仅 `status = ACTIVE` | -| 过滤企微绑定 | **不过滤** (未绑定企微也返回) | 必须 `enterprise_wechat_id` 非空 | -| 返回 VO | 简单 3 字段 | 重 VO(认证等级/服务领域/手机/简介等) | -| 用途 | **分享产品下拉**,只要是定制师就能选 | 小程序 C 端定制师列表展示 | - -→ 本接口刻意放宽过滤,因为分享产品场景下「即使临时锁定/没绑企微的定制师也允许分享给他」(分享是给账号,定制师后续登录处理)。 - -**鉴权**: 标准 admin token(网关已校验),接口本身**不再做角色硬编码检查** — 任何登录 admin 都能调用。 - ---- - -### 2. 分享产品给定制师 `POST /admin/product/item/{id}/share` - -**Headers**: -- `Content-Type: application/json` -- `Authorization: Bearer <admin token>` - -**Path 参数**: -- `id` Long 必填 — 源产品 productId - -**Request body** `ProductShareReqVO`: - -```json -{ "targetAdminId": 1002 } -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `targetAdminId` | Long | ✅ | 目标定制师 adminId(取自上方 `/admin/user/customizers` 列表的 `data[].adminId`) | - -**Response** `Result<ProductShareRespVO>`: - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "newProductId": 1818070000000000123, - "newProductNo": "C260509047", - "newLineId": 1818070000000000456, - "newProductName": "云南 8 日游(来自 wx 的分享)" - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `newProductId` | Long | 新复制出来的产品 ID | -| `newProductNo` | String | 新生成的产品编号(走 ProductNoGenerator,如 `C260509047`) | -| `newLineId` | Long | 新复制的产品线 ID(独立副本) | -| `newProductName` | String | 新产品名称(原名 + `(来自 {操作人 username} 的分享)` 中文括号) | - -**业务行为(逐项)**: -1. 校验当前 admin 持 `PRODUCT_SHARE` 权限点 → 否返 `403` -2. 校验 `targetAdminId` 对应 admin 的 `roleKeys` 含 `CUSTOMIZER` → 否返 `400 "目标用户不是定制师"` -3. 校验源产品存在 → 否返 `404` -4. 复制产品线: 新生成 lineId,其余字段照抄源产品线 -5. 复制产品(基于已有 `ProductCopyService`): - - `lineId` 指向新产品线 - - `name` = 源 name + `(来自 {操作人 username} 的分享)` - - `createdBy` = `targetAdminId`(覆盖默认的当前操作人) - - `status` = `DRAFT` - - `productNo` = 新生成 - - **不复制** `product_price_calendar` 表(价格日历由定制师重新配置) - - 复制范围: 主表 + 4 张 1:1 子表 + 备品/费用 1:N 子表 + 行程相关 4 表(同 `copyProduct`) - -**错误码**: - -| HTTP | 业务消息 | 触发条件 | -|------|----------|----------| -| 403 | (走全局异常) | 当前 admin 无 `PRODUCT_SHARE` 权限点 | -| 400 | 目标用户不是定制师 | `targetAdminId` 对应 admin 不持 CUSTOMIZER 角色 | -| 404 | (走全局异常) | 源产品不存在或已删除 | - ---- - -## 四、前端改造点(mmg 关注) - -### 文件: `hl-ui/src/views/product/list/components/...`(分享弹窗相关) - -1. **下拉接口换地址**: - - 改前: `GET /admin/user?page=1&pageSize=100` (老接口被硬编码角色挡,显示"没有权限") - - 改后: `GET /admin/user/customizers` (本 PR 新增,无过滤) - - 字段映射: `data[].adminId` → 下拉 value, `data[].username` → 下拉 label, `data[].avatar` → 下拉 icon(可选) - -2. **「确定」按钮接口**: - - 改前: 不存在(后端没接口,所以点"确定"实际什么都没发生 / 报 404) - - 改后: `POST /admin/product/item/{id}/share` body `{targetAdminId}` - - 成功后展示成功 toast,可加跳转「定制师视角查看新产品」入口(用 `data.newProductId`) - -3. **目标用户下拉为空时的兜底**: - - 如果系统里一个定制师都没有,接口返 `data: []`,前端显示「请先创建定制师账号」之类的空态 - - 不要再用上一版逻辑里"没权限"的 toast(本接口不会再返 403) - -4. **"分享后规则"提示文案**(已在弹窗右侧展示,与后端行为已对齐): - - 状态为草稿,需重新编辑发布 ✅ 后端确实置 `DRAFT` - - 标题会添加"(来自 xxx 的分享)"后缀 ✅ 后端确实加,xxx = 当前 admin.username - - 生成新的产品编号 ✅ 后端走 ProductNoGenerator - - 不包含价格日历(需重新设置) ✅ 后端确实不复制 `product_price_calendar` - ---- - -## 五、权限点 `PRODUCT_SHARE` - -新加权限点(`admin_permission` 表): - -| 字段 | 值 | -|------|----| -| permission_code | `PRODUCT_SHARE` | -| permission_name | 分享产品 | -| resource_type | PRODUCT | -| action | SHARE | -| description | 允许将自己的产品复制一份分享给指定的定制师 | -| status | ACTIVE | - -默认绑定角色(`admin_role_permission` 表): - -- `SUPER_ADMIN` -- `ADMIN` - -**CUSTOMIZER 不绑** — 业务侧默认由 SUPER_ADMIN/ADMIN 负责跨定制师分享,普通 CUSTOMIZER 只是接收方。如业务后续要让定制师之间互相分享,在权限管理页面给 CUSTOMIZER 角色加这个权限点即可,**无需改后端代码**。 - ---- - -## 六、不在本 PR 范围 - -- `AdminUserController.listAdmins()` 第 162 行硬编码 `if (!"SUPER_ADMIN".equals(role) && !"ADMIN".equals(role)) ...` 不动 — 留后续单独治理工单 -- 已分享产品的二次分享 / 取消分享 / 审计追踪 / 通知目标定制师等扩展功能 -- 前端 hl-ui 的弹窗 UI 调整(由 mmg 完成) - ---- - -## 七、测试与验证 - -- 全 1160(product) + 2341(user) 单元测试均无回归 -- 新增 19 个单测覆盖: `DesignerServiceTest +5` / `InternalUserControllerTest +3` / `ProductShareServiceTest 11/11` -- 本地启动全链路 API 测试**未做**(权衡时间) — 合 dev 后由后端在测试服 1.182.108.58 用真 admin token 通过网关 9443 立即验证,如发现问题立刻提下一个 PR - ---- - -## 八、相关 PR / 工单 - -| PR / Issue | 说明 | 是否相关 | -|------------|------|----------| -| #1919 | 本 PR | ✅ 主体 | -| #1918 | 工单 | ✅ 已 closed | -| 已撤回的 `09_frontend_notice_admin_product-share-remove-target-user-step.md` | 误将本功能识别为 url-scheme 多余步骤 | ⚠️ 已撤回,本通知是真正的解决方案 | -| #1488 | 老的 url-scheme 接口(生成微信短链) | ❌ 不相关,是另一个功能 | - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_feat_traveler_type_mismatch_to_notify_center.md b/changelogs/2026-05/09_feat_traveler_type_mismatch_to_notify_center.md deleted file mode 100644 index 8cba8e2..0000000 --- a/changelogs/2026-05/09_feat_traveler_type_mismatch_to_notify_center.md +++ /dev/null @@ -1,66 +0,0 @@ -# 出行人类型不符通知迁移到通知中心 + TRAVELER_INCOMPLETE 配置修复 - -> **服务**: hl-order-service-v2 + hl-user-service -> **PR**: #1915 (Closes #1914) -> **日期**: 2026-05-09 -> **影响范围**: 后端通知链路;无前端改动 - ---- - -## ⚠️ 关键变化(无 API 字段变化,纯链路 + 配置治理) - -PR #1892 实现"出行人类型不符提醒定制师"时直调 `userFeignClient.sendWechatMessage` 硬编码企微通知,绕过通知中心。本 PR 迁移到通知中心 + 顺路修一个 prod 配置 bug。 - -**前端无需任何改动**。 - ---- - -## 一、改动清单 - -### A. Flyway V20260509_002 - -1. **修复 prod 配置 bug**:`UPDATE notification_event_config SET wework_enabled=0, wework_receiver_type=NULL, wework_content_template=NULL WHERE event_code='TRAVELER_INCOMPLETE'` - - 原 wework_receiver_type='USER' 是无效值(dispatcher switch 不识别),prod 7 天内 12 条全部 SKIP "无企微接收人" - - 该事件接收人是 C 端客户(USER),语义上不该走企微(企微只能发企业内部 admin),关掉企微通道,保留小程序订阅消息 -2. **新增事件 `TRAVELER_TYPE_MISMATCH`**: - - `wework_enabled=1, wework_receiver_type='CUSTOMIZER'` - - `wework_content_template` 含占位符 `${orderNo}/${productName}/${contactName}/${contactPhone}/${departureDate}/${declaredSummary}/${actualSummary}` - - `ON DUPLICATE KEY UPDATE` 幂等重跑 - -### B. 代码 - -- `TravelerTypeMismatchNotifier`:移除 `userFeignClient`/`complaintUserFeignClient`/`@Async("travelerNotifyExecutor")`/customizerId+wechatUserid SKIP 路径 -- 改注入 `NotificationEventHelper`,通过 `sendRaw(NotificationEventMessage)` 投 MQ -- 收件人由 `NotificationDispatcher.resolveWeworkRecipient` 按 CUSTOMIZER 查 `admin.enterprise_wechat_id` 自动 resolve -- 删 `TravelerNotifyConfig` + 对应测试(MQ 全链已异步,业务侧线程池冗余) -- 钩子 A(补全完毕)+ 钩子 B(改 4 count) + afterCommit 注册 全部保留 - -### C. 测试 8 用例全绿 - -- 一致不发 / 不一致发 / customizerId=null 仍发(由 dispatcher 兜底) / 订单不存在 -- 边界:列表空 → actual 全 0 / null type 跳过 / productName 长度>20 截断 / declared 全 null + actual 空 → 一致 - -## 二、行为变化 - -| 场景 | PR #1892 | 本 PR | -|------|---------|-------| -| 触发不一致 | 直调企微 Feign 发文本消息 | 投 MQ → dispatcher → 企微通道发送 | -| customizerId=null | Notifier 内 SKIP 不发 | Notifier 仍发 → dispatcher saveSendLog status=2(无企微接收人) | -| wechatUserid 为空 | Notifier 查 ComplaintUserFeignClient SKIP | dispatcher 查 admin.enterprise_wechat_id 兜底 saveSendLog status=2 | -| 通知日志 | `notification_log` 由 WechatApiClient 自动落 | `notification_send_log` 标准统一日志,event_code='TRAVELER_TYPE_MISMATCH' | -| admin 在通知中心 UI 关闭企微 | 无效(硬编码绕过) | **生效**(wework_enabled=0 → dispatcher 不分发) | - -## 三、@mmg 关注点(无前端改动) - -无 API 改动,小程序/管理端无需调整。 - -## 四、运维关注 - -- 部署后跑 V20260509_002 自动落库,可在通知中心 UI 看到新事件 `出行人类型不符提醒` 出现在 `订单消息` 分组 -- admin 可在通知中心配置页改文案/开关该事件的企微/站内信通道(本期默认只开企微) -- prod 12 条历史 SKIP 条目不会清理(只是新事件的策略变了) - -## 五、规则依据 - -铁规 19b:**任何消息发送必须走通知中心,严禁硬编码** —— 站内信/短信/小程序/公众号/企微 全渠道通过 NotificationDispatcher + notification_event_config,不许直调 sendXxxMessage Feign 写死文案。 - diff --git a/changelogs/2026-05/09_fix_admin_agency-delete-use-tablelogic.md b/changelogs/2026-05/09_fix_admin_agency-delete-use-tablelogic.md deleted file mode 100644 index 70454fd..0000000 --- a/changelogs/2026-05/09_fix_admin_agency-delete-use-tablelogic.md +++ /dev/null @@ -1,45 +0,0 @@ -# 公司管理「删除」行为修复 — 真的删除了 - -> **服务**: hl-order-service-v2 (8094) -> **PR**: #1927 -> **Issue**: #1926 -> **日期**: 2026-05-09 -> **影响范围**: admin「公司管理 / 旅行社管理」点删除按钮 - ---- - -## 一、用户可见变化 - -修复前: 点删除 → 提示"删除成功" → 列表刷新公司**还在**(用户多次重试问题持续) -修复后: 点删除 → 提示"删除成功" → 列表刷新公司**真消失** - -## 二、前端不用改 - -接口契约 / 字段 / 路径 0 变化: -- `DELETE /admin/travel-agency/{id}` 入参/出参不变 -- `GET /admin/travel-agency/page` 字段不变 -- `GET /admin/travel-agency/enabled-by-platform` (本日新接口) 字段不变 - -如果之前有"强制刷新"或"轮询确认删除生效"之类的 workaround 代码,可以去掉了。 - -## 三、根因(简述) - -后端原本用 `update set status='DISABLED'` 当作"删除"来避免外键悬空,但列表查询的 `selectPage` 在前端不传 status 时不过滤,DISABLED 公司仍然出现。修复改为走 BaseDO 的 `@TableLogic` 软删(set deleted_at = NOW()),让所有列表查询(MyBatis-Plus 自动加 deleted_at IS NULL 条件)统一过滤。 - -## 四、测试服验证 (2026-05-09 21:00) - -| Case | 实测 | -|---|---| -| DELETE bohua-test (旧 BUG 留下的 status=DISABLED 数据) | 200, 列表 4 条不再出现 | -| DB 验证 bohua-test 行 deleted_at | 2026-05-09 21:00:10 已设 | -| DELETE kj (主体公司) | 业务码 594005 拒绝(主体禁删校验) | -| DELETE 不存在 ID | 业务码 AGENCY_NOT_FOUND | - -## 五、不在本 PR 范围 - -- 跨服务引用校验(product/contract/order/team_report Feign 0 引用才允许删) — 留后续工单 -- 旧 status='DISABLED' 历史数据治理(是否一次性 UPDATE 设 deleted_at) — 留后续讨论 - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_fix_admin_contract-scheme-agency-by-platform.md b/changelogs/2026-05/09_fix_admin_contract-scheme-agency-by-platform.md deleted file mode 100644 index c39d874..0000000 --- a/changelogs/2026-05/09_fix_admin_contract-scheme-agency-by-platform.md +++ /dev/null @@ -1,136 +0,0 @@ -# 合同方案弹窗「旅行社」下拉新增按合同平台过滤接口 - -> **服务**: hl-order-service-v2 (8094) -> **PR**: #1922 主体 + #1923 空字符串兜底修复 -> **Issue**: #1921 -> **日期**: 2026-05-09 -> **影响范围**: admin「合同管理 → 合同方案 → 新增/编辑合同方案」弹窗的「旅行社」下拉 - ---- - -## 一、背景 - -弹窗里点旅行社下拉显示「无数据」。根因:之前没有「按合同平台过滤启用旅行社」的下拉接口,前端不知道调哪个。现有 `/admin/travel-agency/enabled` 和 `/enabled-for-product` 都不带平台维度,直接调出来不分平台,与"按合同平台配置"的业务语义不匹配。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 按合同平台过滤启用旅行社 | GET | `/admin/travel-agency/enabled-by-platform` | 新增 | 给「新增合同方案」弹窗下拉用 | - ---- - -## 三、接口详情 - -### `GET /admin/travel-agency/enabled-by-platform` - -**Headers**: 标准 admin token - -**Query 参数**: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `contractPlatform` | String | ✅ | 合同平台 code,取值: `12301` / `TENCENT_ESIGN` / `LOCAL`(LOCAL 暂未在前端用) | - -**响应** `Result<List<AgencySimpleRespVO>>`: - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": [ - { - "agencyId": "2051922156798779394", - "code": "hulai", - "agencyName": "内蒙古呼籁国际旅行社有限公司", - "isPrimary": 0, - "sortOrder": 100 - } - ] -} -``` - -**字段说明**(与现有 `/enabled` 接口同 VO,字段不变): - -| 字段 | 类型 | 说明 | -|------|------|------| -| `agencyId` | Long(序列化为 String 防 JS 精度丢失) | 旅行社 ID,提交合同方案时作为关联标识 | -| `code` | String | 旅行社编码,合同方案 `agencyCode` 字段对应它 | -| `agencyName` | String | 旅行社全称(下拉 label) | -| `isPrimary` | Integer | 是否主体公司(1=是, 0=否),前端可视情况打标 | -| `sortOrder` | Integer | 排序号 | - -**过滤逻辑**: -- `status = 'ENABLED'` (只返启用) -- `supported_platforms IS NOT NULL AND supported_platforms <> ''` (跳过脏数据空字符串行,见下方 PR #1923 上下文) -- `JSON_CONTAINS(supported_platforms, JSON_QUOTE(?))` (数组里包含选定平台) - -**排序**: `is_primary DESC` (主体公司优先) + `agency_id ASC` (稳定排序) - -**错误码**: - -| HTTP code | 业务 code | 触发 | -|---|---|---| -| 200 | 200 | 正常返列表(空 list 表示该平台暂无支持的旅行社) | -| 200 | 400 | `contractPlatform` 缺参 → `enabledByPlatform.contractPlatform: 合同平台不能为空` | - ---- - -## 四、前端改造点(mmg) - -文件: `hl-ui/src/views/contract/scheme/...`(合同方案配置弹窗) - -1. **旅行社下拉接口**: 改调 `GET /admin/travel-agency/enabled-by-platform` -2. **入参**: 把当前选中的 `contractPlatform`(radio: 12301 / 腾讯电子签 → `TENCENT_ESIGN`)作为 query param 传入 -3. **联动**: 切换合同平台 radio 时**重新拉取**旅行社列表(可触发 watch contractPlatform 重新调接口) -4. **空态**: 接口返 `data: []` 时显示「该合同平台暂无支持的旅行社,请联系管理员配置」之类的友好提示 -5. **不再用** `/admin/travel-agency/enabled` 这个老接口(那是不带平台过滤的全量,本场景不合适) -6. placeholder「不填则根据支付商户号自动匹配」可保留(业务语义没变,只是下拉本身要先有数据可选) - ---- - -## 五、测试服 API 验证(2026-05-09 19:00) - -| Case | 实测 | -|---|---| -| `?contractPlatform=12301` | ✅ 200, 4 条旅行社(hulai / qianshou / hulai-wenlu / bohua-test) | -| `?contractPlatform=TENCENT_ESIGN` | ✅ 200, `data: []`(测试库无 agency 支持腾讯电子签) | -| `?contractPlatform=` (空) | ✅ code=400, message="enabledByPlatform.contractPlatform: 合同平台不能为空" | - -测试库 5 条 ENABLED 旅行社 supported_platforms 现状: -- `["12301"]` × 4 (hulai / qianshou / hulai-wenlu / bohua-test) -- `""` (空字符串) × 1 (kj) — 已被 isNotNull + ne('') 过滤跳过 - ---- - -## 六、衍生 PR (空字符串兜底) - -PR #1922 主体合并后首测发现 `JSON_CONTAINS` 解析空字符串报 `Data truncation: Invalid JSON text in argument 1 to function json_contains: "The document is empty."`,整个查询 500。根因测试库 1 行 `supported_platforms = ''` 脏数据。PR #1923 在 mapper 加 `isNotNull + ne('')` 前置过滤,跳过脏行。 - -后续治理建议(不在本 PR 范围):**所有旅行社记录的 supported_platforms 应统一存 `[]` 或合法 JSON 数组,避免空字符串脏数据**(可在 admin 端「旅行社管理」编辑保存时校验,或加迁移 SQL `UPDATE travel_agency SET supported_platforms = '[]' WHERE supported_platforms = '' OR supported_platforms IS NULL`)。 - ---- - -## 七、不在本 PR 范围 - -- 现有 `/admin/travel-agency/enabled` 和 `/enabled-for-product` 不动(其他场景在用) -- 旅行社管理页面新增/编辑时 `supported_platforms` 字段 UI(如果还没有,需另起 PR) -- 合同方案保存时如何用 `agencyCode` 关联到旅行社(现有逻辑不动) -- 测试库脏数据治理(可后续加 V*.sql 统一) - ---- - -## 八、相关 PR / 工单 - -| PR / Issue | 说明 | -|---|---| -| #1921 | 工单 | -| #1922 | 主体 PR | -| #1923 | 空字符串兜底修复 | - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_fix_admin_product-share-2-regressions.md b/changelogs/2026-05/09_fix_admin_product-share-2-regressions.md deleted file mode 100644 index 4bb4aa1..0000000 --- a/changelogs/2026-05/09_fix_admin_product-share-2-regressions.md +++ /dev/null @@ -1,73 +0,0 @@ -# 后端 fix 通知 — admin 产品分享 2 项回归已修复 - -**日期**: 2026-05-09 -**类型**: 后端修复 (PR #1919 内部回归) -**模块**: 产品管理 → 产品列表 → **分享产品**(ShareModal) -**通知**: @mmg -**前端是否需改动**: 否(响应 schema 不变) -**严重性**: 高 (P1)→ 已修 - ---- - -## ⚠️ 关键变化 - -PR #1919 (Closes #1918) 实现的产品分享接口 `POST /admin/product/item/{id}/share` 上线后,经测试服真实跑发现 2 个 P1 回归 BUG。**PR #1924 (commit `e6a54fde`)** 已修复并合 dev、测试服已部署、QA 已复测通过: - -1. **产品名后缀英文括号 → 中文全角括号**(契约/Swagger/前端通知约定的就是中文全角) -2. **fee_item 深拷贝丢数据**(原本可能丢 60-70%,现已全量复制) - -前端**无需做任何改动**,响应 schema / 字段 / 语义都不变,只是落库/响应里的实际数据现在符合契约。 - ---- - -## BUG #1 — 产品名后缀字符 - -**修前**:`新产品名(来自admin的分享)` (英文半角括号 U+0028 / U+0029) -**修后**:`新产品名（来自admin的分享）` (中文全角括号 U+FF08 / U+FF09) - -**前端验收**: -- ShareModal 调 share 接口后跳转到新产品编辑页,标题应显示中文全角括号后缀。 -- 不需要前端代码做任何字符判断/兼容,直接展示后端返回的 `newProductName` 即可。 - ---- - -## BUG #2 — fee_item 深拷贝丢数据 - -**修前**:源产品 fee_item N 条 → 新产品仅复制部分(实测 27 → 9,部分类别全丢),原因是 MyBatis-Plus `Db.saveBatch` 的 KeyGenerator 在批处理 reuse PreparedStatement 场景下时机不可靠,部分行 id 注入失败触发 NOT NULL 约束冲突被静默跳过。 - -**修后**:`ProductCopyService.copyOneToMany` 显式 `IdWorker.getId()` 预分配雪花 id,根除丢条。同步把 itinerary 节点/酒店/路线点的 `setId(null)` 也改为预分配,语义统一。 - -**前端验收**: -- 分享后跳转到新产品的"费用项"配置页,条目数应等于源产品费用项条目数,且每条字段一致。 - ---- - -## 测试服已验证(2026-05-09 20:45+) - -``` -POST /admin/product/item/2044704111294672897/share body {"targetAdminId":1002} -→ 200, newProductName 末字符 U+FF09 ✅ -→ DB product.name 落库为「...（来自admin的分享）」中文全角 ✅ -→ DB product_fee_item COUNT(*) = 源产品全量,id 全部 NOT NULL 互不重复 ✅ -``` - ---- - -## 不影响范围 - -- 接口契约(URL / Method / 请求 VO / 响应 VO)零变化 -- 鉴权 / 校验 / 幂等逻辑零变化 -- 其他复制场景(`POST /admin/product/item/{id}/copy` 老接口)同步受益(同一 `copyOneToMany` 修复路径) - ---- - -## 相关 PR - -| PR | 说明 | 状态 | -|----|------|------| -| #1919 | 实现 admin 分享产品功能 (Closes #1918) | ✅ 已合 dev,但暴露 2 个回归 | -| **#1924** | **本通知关联**:修复 #1919 暴露的 2 个 P1 回归(中文括号 + fee_item 全量复制) | ✅ 已合 dev + 测试服已部署 + QA 通过 | - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_fix_common_validation_msg_strip_field_prefix.md b/changelogs/2026-05/09_fix_common_validation_msg_strip_field_prefix.md deleted file mode 100644 index f82b88a..0000000 --- a/changelogs/2026-05/09_fix_common_validation_msg_strip_field_prefix.md +++ /dev/null @@ -1,129 +0,0 @@ -# @Valid 校验失败 toast 去掉字段名前缀,提示更友好 - -> **服务**: hl-common-log (共享 module,影响全部 6 个后端服务) -> **PR**: #1916 -> **Issue**: 无(从前端 BUG 通知 `09_frontend_notice_admin_service-edit-categorycode-required.md` 衍生的后端体验改善) -> **日期**: 2026-05-09 -> **影响范围**: 全部 admin / mp / 内部接口的 `@Valid + @RequestBody` 触发的 400 校验响应文案 - ---- - -## ⚠️ 关键变化 - -后端全局 `MethodArgumentNotValidException` / `BindException` 处理器返回的 `Result.message` 文案格式变了: - -| | 改前 | 改后 | -|---|---|---| -| **单字段错误** | `categoryCode: 分类编码不能为空` | `分类编码不能为空` | -| **多字段错误** | `name: 姓名不能为空; age: 必须为正数` | `姓名不能为空; 必须为正数` | -| **defaultMessage 为 null 时** | 字段名: null | 被过滤掉(filter `Objects::nonNull`) | - -`Result.code` 仍是 `400`,HTTP status 仍是 `200`(项目惯例),只是 `message` 字符串格式不再带 Java 字段名前缀。 - ---- - -## 一、背景 - -正式环境 admin 后台,用户编辑服务时 toast 显示 `categoryCode: 分类编码不能为空`(同日 changelog `09_frontend_notice_admin_service-edit-categorycode-required.md` 已确认前端误调 POST 创建接口为根因)。即使前端修了误调接口,**`categoryCode:` 这种字段名前缀对最终用户来说是技术噪音 — 用户不该看到 Java 字段名**,所以后端这次顺手做了体验改善。 - -`hl-common-log` 是 6 个服务的共享异常处理 module,改一处全部受益。 - ---- - -## 二、改动接口清单 - -**所有 `@Valid + @RequestBody` 接口都受影响**(数量约 200+,无法一一列举)。常见高频: - -- `POST /admin/*/save` / `POST /admin/*/create` -- `PUT /admin/*/update` -- `POST /mp/*/submit` -- 几乎所有带 `@RequestBody` 的写入接口 - -不影响: -- `@Validated` query / path 参数(走 `ConstraintViolationException`,本次未改) -- 业务异常(`BizException` 等) -- 系统异常(NPE / 序列化错误等) - ---- - -## 三、对前端 (mmg) 的影响 - -### 1. 必看:有没有 `message` 解析逻辑 - -如果 hl-ui / 小程序里有以下代码,**会失效**: - -```js -// 类似这样的 message 解析逻辑都需要排查 -if (response.message.startsWith('categoryCode:')) { ... } -const [field, msg] = response.message.split(':') -const fieldName = response.message.match(/^(\w+):/)?.[1] -``` - -请 mmg 全局搜以下关键字检查: -- `\.message\.startsWith\(` -- `\.message\.split\(':?'\)` -- `\.message\.match` -- `\.message\.indexOf\(':'\)` - -### 2. 实际更友好 - -绝大多数情况下,前端只是 `Toast(response.message)` 直接显示,本次改动让用户看到的提示**直接更友好**,**不需要任何前端改动**。 - -### 3. 多字段错误仍可读 - -多字段错误时仍以 `;空格` 分隔,例如: - -``` -姓名不能为空; 手机号格式不正确; 年龄必须为正数 -``` - -足以让用户看清所有问题。 - ---- - -## 四、技术细节 - -### 改动前 - -```java -// hl-common-log/.../GlobalExceptionHandler.java -String message = e.getBindingResult().getFieldErrors().stream() - .map(f -> f.getField() + ": " + f.getDefaultMessage()) // 拼字段名 - .reduce((a, b) -> a + "; " + b) - .orElse("参数校验失败"); -``` - -### 改动后 - -```java -String message = e.getBindingResult().getFieldErrors().stream() - .map(FieldError::getDefaultMessage) - .filter(Objects::nonNull) // null 兜底,避免 toast 出 "null" - .reduce((a, b) -> a + "; " + b) - .orElse("参数校验失败"); -``` - -`BindException` 处理同款改法。 - ---- - -## 五、为什么不顺手优化单个 message 文案 - -有人会想:`分类编码不能为空` 里"分类编码"对用户也不够友好,改成"请选择分类"更好。**本次不动**,理由: - -- 改全局 1 处,200+ 接口统一受益,B 方案逐字段改 message 工作量翻 100 倍且新加字段会复发 -- `defaultMessage` 文案优化属于 UX polish,可后续单独治理(并不紧急) -- 主目标是**去掉字段名前缀这个技术噪音**,主目标已达成 - ---- - -## 六、未覆盖 - -- `ConstraintViolationException`(`@Validated` 修饰 Controller + query/path 参数路径,如 `@RequestParam @Min(1)`)未改 — line 191 `e.getMessage()` 自带 `arg0.fieldName: 消息` 格式。本次主线 toast 不在此路径,风险/收益偏低,留待下次治理。 -- 业务异常 `BizException`、自定义异常文案不动。 - ---- - -## 验收 - -无前端改动情况下,任何 `@Valid + @RequestBody` 接口校验失败时,前端 `response.message` 应不再带 `字段名: ` 前缀。 diff --git a/changelogs/2026-05/09_fix_mp_admin_quote_single_room_diff_followup.md b/changelogs/2026-05/09_fix_mp_admin_quote_single_room_diff_followup.md deleted file mode 100644 index 25e5175..0000000 --- a/changelogs/2026-05/09_fix_mp_admin_quote_single_room_diff_followup.md +++ /dev/null @@ -1,110 +0,0 @@ -# mp/admin /quote 接口补单房差遗漏 - -> **服务**: hl-product-service-v2(8093) -> **PR**: #1905 (Refs #1900) -> **日期**: 2026-05-09 -> **影响范围**: 管理端 + 小程序订单确认页报价接口 - ---- - -## ⚠️ 关键变化 - -PR #1901 加单房差时只改了 `simpleQuote` / `getGroupQuote` 两条算价路径,**漏掉第三条** `ProductPricingService.calculateQuote`,导致以下两个接口不展示单房差: - -- `POST /admin/product/item/{id}/quote`(管理端报价) -- `POST /mp/product/{id}/quote`(C 端报价) - -本 PR 补齐:响应 +2 字段 `singleRoomDiff` + `singleRoomSurcharge`,`adultCount==1` 时 `grandTotal` 含单房差,**比例定金按 baseTotal 算(D2 不变)**。 - ---- - -## 一、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 管理端报价 | POST | `/admin/product/item/{id}/quote` | 响应 +2 字段 | `singleRoomDiff` + `singleRoomSurcharge`;`adultCount==1` 时 `grandTotal` 含单房差 | -| 2 | C 端报价 | POST | `/mp/product/{id}/quote` | 响应 +2 字段 + 行为变更 | 同 #1 + 比例定金按 baseTotal 算 | -| 3 | 内部 mp 报价 | POST | `/internal/mp/product/{id}/quote` | 响应 +2 字段 | 同 #1 | - -> **PR #1901 已支持的接口**(本 PR 不动):`/internal/product/{id}/simple-quote` / `/internal/product/{id}/group-quote` - -## 二、响应示例 - -**`POST /mp/product/{productId}/quote` 请求**: - -```json -{ - "departureDate": "2026-07-01", - "adultCount": 1, - "childCount": 0, - "toddlerCount": 0, - "infantCount": 0, - "tierSeq": 1 -} -``` - -**响应**(产品配 `singleRoomDiff=200`,`depositRatio=10%`): - -```json -{ - "code": 200, - "data": { - "adultUnitPrice": 3980.00, - "totalAdultPrice": 3980.00, - "singleRoomDiff": 200.00, - "singleRoomSurcharge": 200.00, - "grandTotal": 4180.00, - "paymentType": "DEPOSIT", - "depositRatio": 10, - "depositAmount": 398.00, - "balanceAmount": 3782.00 - } -} -``` - -- `grandTotal = 4180`(成人 3980 + 单房差 200) -- `depositAmount = 398`(= **baseTotal 3980** × 10%,**不是** 4180 × 10% = 418)— D2 比例定金口径自洽 -- `balanceAmount = grandTotal - depositAmount = 3782`(尾款含单房差) - -**`adultCount=2` 不触发**: - -```json -{ - "data": { - "singleRoomDiff": 200.00, - "singleRoomSurcharge": 0, - "grandTotal": 7960.00, - "depositAmount": 796.00 - } -} -``` - -## 三、决策点(沿用 #1900 既有决策) - -- **D1**:严格 `adultCount == 1` 触发(不看其他类型人数) -- **D2**:比例定金按 `baseTotal`(不含单房差)算 -- **D3**:固定/人定金不动 -- **早鸟优惠**:基于 `grandTotal`(已含单房差),从尾款扣,自洽不动 - -## 四、前端改动建议(mmg) - -小程序订单确认页 / 管理端报价试算面板: - -- 显示:`singleRoomSurcharge > 0` 时多一行 "单房差 ¥XXX" -- 总价用后端返 `grandTotal`,**前端不要自己加单房差**(防双计) -- 定金/尾款用后端返 `depositAmount` / `balanceAmount`,**前端不要自己算** - -无新增错误码。 - -## 五、向后兼容 - -- 老 calendar/batch `single_room_diff DEFAULT 0` → `singleRoomSurcharge=0` → 老前端不读字段无影响 -- 老前端响应多 2 个字段不报错(Jackson `fail-on-unknown-properties=false`) - -## 六、测试验证 - -- 单测:`ProductPricingServiceTest +4` / `ProductPricingServiceMpQuoteTest +2` / `MpProductServiceTest +2` = **8 用例全过(总 138 PASS)** -- 测试服 round-trip(经 9443 网关 + 真 admin token,产品 `2043595351268519937`,`single_room_diff=200`): - - `/mp/product/{id}/quote` adult=1 → `grandTotal=4180`,`singleRoomSurcharge=200`,`depositAmount=398` ✅ - - `/mp/product/{id}/quote` adult=2 → `singleRoomSurcharge=0`,`depositAmount=796` ✅ - - `/admin/product/item/{id}/quote` adult=1 → `grandTotal=4180`,`singleRoomDiff=200`,`singleRoomSurcharge=200` ✅ diff --git a/changelogs/2026-05/09_fix_mp_message_read_status_bugs.md b/changelogs/2026-05/09_fix_mp_message_read_status_bugs.md deleted file mode 100644 index 928e10b..0000000 --- a/changelogs/2026-05/09_fix_mp_message_read_status_bugs.md +++ /dev/null @@ -1,93 +0,0 @@ -# mp 消息已读/未读 4 项 bug 修复(性能 + 正确性) - -> **服务**: hl-user-service(8081) -> **PR**: #1912 -> **Issue**: #1911 -> **日期**: 2026-05-09 -> **影响范围**: 小程序消息中心 / badge 未读数 / 消息列表 - ---- - -## ⚠️ 关键变化(无新增字段,**纯修复 + 性能优化**) - -1. **B1** 单条标已读接口真正生效(原是空实现) -2. **B2** 标已读后 badge 红点秒级刷新(原 30s 缓存不刷) -3. **B3** 消息列表接口零阻塞(原同步 UPDATE 主线程,慢) -4. **B4** 加联合索引加速 UPDATE/SELECT(原全表扫) - -前端**无需改造**。 - ---- - -## 一、变更接口行为 - -| 接口 | 路径 | 行为变更 | -|------|------|---------| -| 单条标已读 | `PUT /mp/message/{id}/read` | **真正更新 DB**(原空实现);标已读后 badge 立即刷新 | -| 全部标已读 | `PUT /mp/message/read-all` | UPDATE 后立即失效缓存(原 30s 后才刷) | -| 分类标已读 | `PUT /mp/message/read-all?category=xxx` | 同上 | -| 消息列表 | `GET /mp/message/list` | **响应不再阻塞 UPDATE**:主线程返回时内存里已 `isRead=true`,DB 异步落 | -| 消息摘要 | `GET /mp/message/summary` | 缓存失效更准(deps `table:user_message` 联动) | - -## 二、Bug 详情 - -### B1 单条标已读真实现 - -**修前**:`InternalMpMessageController.markRead(messageId)` 是空方法,只返 `success`,DB 不更新。 -**修后**:调 `UserMessageService.markRead(messageId, userId)` → `UPDATE user_message SET is_read=1 WHERE id=? AND user_id=? AND is_read=0`。 -- WHERE 限定 `user_id` 防越权(原本相信前端传入) -- 已读消息再标 → rows=0(幂等) - -### B2 缓存失效 - -**修前**:`markAllRead/markCategoryRead` UPDATE 后没通知 `/mp/message/summary` 缓存(`@MpCache(ttl=30, deps={"table:user_message"})`),badge 红点 30 秒内显示旧数。 -**修后**:三处方法都加 `afterCommit` 调 `depsManager.invalidateSource("table:user_message")`,事务提交后立即失效缓存。 - -### B3 listMessages 异步标已读 - -**修前**:`UserMessageService.listMessages` 内部同步 UPDATE 当前分类为已读,**主线程阻塞**。 -**修后**: -- 引入独立 bean `UserMessageReadAsyncTask`(绕 `@Async` self-invocation) -- `@Async("messageReadExecutor")` 独立线程池(core=3, max=8, queue=100) -- 主线程内存里 `setIsRead(1)` 立即返 RespVO,DB 异步落 - -**前端体验**:消息列表打开**毫秒级返回**(原阻塞数百毫秒),已读状态展示无滞后。 - -### B4 联合索引 - -**修前**:`user_message` 表只有 `idx_user_category(user_id, category_code)` + `idx_create_time(create_time)`,WHERE `user_id=? AND is_read=0` 走全表扫(尤其在用户消息多时)。 -**修后**:Flyway V20260509_001 加 `idx_user_read(user_id, is_read)` 联合索引,加速: -- 标已读 UPDATE -- 未读数 SELECT(`/mp/message/summary`) -- 全分类标已读 UPDATE - -## 三、向后兼容 - -- API 字段无变化 -- 前端不需要任何改造 -- 单条 markRead 接口路径不变,只是真生效了 -- 老消息(`is_read=NULL`)由 VO 转换层 `isRead != null && isRead == 1` 防护(已存在) - -## 四、测试覆盖 - -- `UserMessageServiceTest +13`(markRead valid/wrong-user/already-read,markAllRead/markCategoryRead 缓存失效,listMessages async + 内存 isRead) -- `InternalMpMessageControllerTest +1`(markRead 调 service) -- `UserMessageReadAsyncTaskTest 3`(异步执行 + 异常 swallow) -- 共 28 全绿 - -测试服已部署回归: -- ✅ user-service 双实例(8081+8181)新进程启动 -- ✅ Flyway V20260509_001 落库,`idx_user_read` 联合索引就位 - -## 五、部署注意(运维) - -测试服首次部署 V20260509_001 时遇到 `Duplicate key name 'idx_user_read'`(疑似历史手动加过同名索引未记录),Flyway 标 success=0,服务启动失败。**已通过 SQL `UPDATE flyway_schema_history SET success=1 WHERE version='20260509.001'` 修复**。 - -**正式部署前**:运维确认 prod `user_message` 表是否已存在 `idx_user_read` 索引,如有需提前 SQL 设 history success=1 或 DROP 旧索引。 - -## 六、@mmg 关注点 - -无前端改造。本期纯后端修复,前端体验改善: -1. badge 红点秒级刷新(原延迟 30s) -2. 消息列表打开零阻塞 -3. 单条标已读真生效(原前端可能调了无效) diff --git a/changelogs/2026-05/09_fix_mp_order_detail_single_room_and_early_bird_fields.md b/changelogs/2026-05/09_fix_mp_order_detail_single_room_and_early_bird_fields.md deleted file mode 100644 index a9379e4..0000000 --- a/changelogs/2026-05/09_fix_mp_order_detail_single_room_and_early_bird_fields.md +++ /dev/null @@ -1,115 +0,0 @@ -# mp 订单详情单房差展示修复 + 5 字段独立暴露 - -> **服务**: hl-order-service-v2(8094) -> **PR**: #1906 + #1909 (Refs #1900) -> **日期**: 2026-05-09 -> **影响范围**: 小程序订单详情页 - ---- - -## ⚠️ 关键变化 - -`GET /mp/order/{orderId}` 接口: - -1. **修复 GROUP 订单 priceBreakdown JSON 漏字段**(#1906):创建 GROUP 订单时 `priceBreakdownJson` 没写 `singleRoomDiff` / `singleRoomSurcharge`,导致明细面板看不到"单房差"行 -2. **新增 5 个独立字段**(#1909):对齐 `POST /mp/product/{id}/quote` 接口 - ---- - -## 一、新增字段(`MpOrderDetailVO`) - -| 字段 | 类型 | 说明 | -|------|------|------| -| `singleRoomSurcharge` | BigDecimal | 单房差实际加价金额(下单时按 D1: `adultCount==1` 触发);老订单/不触发 = `null` | -| `earlyBirdDiscount` | BigDecimal | 早鸟优惠金额(从 `order_discount` 表 EARLY_BIRD 取);无早鸟 = `null` | -| `earlyBirdPlanName` | String | 命中的早鸟计划名称(格式 `"早鸟优惠:xxx"`);无早鸟 = `null` | -| `finalGrandTotal` | BigDecimal | **应付总额** = `priceBreakdown.totalPayable` = `totalPrice - 优惠总额 + 附加费总额` | -| `finalBalanceAmount` | BigDecimal | **应付尾款**:DEPOSIT 模式 = `balanceAmount - earlyBirdDiscount`;FULL 模式 = `null` | - -字段位置:`discountAmount` 之后、`priceBreakdown` 之前。 - -## 二、响应示例 - -订单 1 大 1 小、班期单房差 500、命中早鸟优惠 200、DEPOSIT 模式(订金 1000): - -```json -{ - "code": 200, - "data": { - "orderId": "2052941051093520386", - "adultCount": 1, - "childCount": 1, - "totalPrice": 5850.00, - "depositAmount": 1000.00, - "balanceAmount": 5850.00, - "discountAmount": 200.00, - "singleRoomSurcharge": 500.00, - "earlyBirdDiscount": 200.00, - "earlyBirdPlanName": "早鸟优惠:暑期早鸟", - "finalGrandTotal": 5650.00, - "finalBalanceAmount": 5650.00, - "priceBreakdown": { - "items": [ - { "label": "成人", "unitPrice": 2925, "quantity": 1, "amount": 2925 }, - { "label": "儿童", "unitPrice": 2425, "quantity": 1, "amount": 2425 }, - { "label": "单房差", "unitPrice": null, "quantity": null, "amount": 500 } - ], - "subtotal": 5850.00, - "discounts": [ - { "tag": "早鸟优惠", "description": "早鸟优惠:暑期早鸟", "amount": -200.00 } - ], - "totalDiscount": -200.00, - "totalPayable": 5650.00 - } - } -} -``` - -## 三、字段使用建议(mmg) - -订单详情页价格区域可用**两种展示风格**任选其一: - -### 风格 A:简洁(推荐,与 quote 接口一致) - -``` -团费总价 ¥5,850.00 ← totalPrice (含单房差) -单房差 +¥500.00 ← singleRoomSurcharge (条件展示, null 隐藏) -早鸟优惠 -¥200.00 ← earlyBirdDiscount (条件展示, null 隐藏) -应付总额 ¥5,650.00 ← finalGrandTotal (粗体,主视觉) -其中订金 ¥1,000.00 ← depositAmount -应付尾款 ¥5,650.00 ← finalBalanceAmount (DEPOSIT 模式) -``` - -### 风格 B:展开明细(用现有 priceBreakdown 数组渲染) - -继续用 `priceBreakdown.items` + `priceBreakdown.discounts` + `priceBreakdown.surcharges` 列表渲染明细,**总价显示用 `finalGrandTotal`**(等同 `priceBreakdown.totalPayable`)。 - -## 四、PR #1906 修复内容 - -**问题**:`GroupOrderStrategy.calculatePrice` 序列化 `priceBreakdownJson` 时手动 copy 字段,**漏 set `singleRoomDiff` 和 `singleRoomSurcharge`**。导致 mp 端 `priceBreakdown.items` 解析时 `isMissingNode` 跳过,GROUP 订单详情明细面板看不到"单房差"行。 - -**修复**:加 2 行 `q.setSingleRoomDiff(quote.getSingleRoomDiff()); q.setSingleRoomSurcharge(quote.getSingleRoomSurcharge());` - -`CoreOrderStrategy.calculatePrice` 直接 `objectMapper.writeValueAsString(quote)` 序列化整个 SimpleQuoteVO,**无此问题**。 - -## 五、向后兼容 - -- 老订单 `priceBreakdown` JSON 缺 `singleRoomSurcharge` → 5 字段中 `singleRoomSurcharge=null`,其他正常 -- 无早鸟订单 → `earlyBirdDiscount=null`,`earlyBirdPlanName=null`,`finalBalanceAmount=balanceAmount`(无优惠减) -- FULL 模式 → `finalBalanceAmount=null`(全款无尾款概念) -- 老前端不读新字段不报错(Jackson `fail-on-unknown-properties=false`) -- 未改 `totalPrice` / `discountAmount` / `priceBreakdown` 现有字段语义 - -## 六、测试覆盖 - -- `GroupOrderStrategyTest +1`(快照含 singleRoomDiff/Surcharge,#1906) -- `MpOrderDetailAssemblerTest +4`(单房差+早鸟+老订单+FULL,#1909) -- 共 +5 用例,**全绿** - -## 七、@mmg 关注点 - -1. 订单详情页价格区域改造:加"单房差"行 + "早鸟优惠"行(都是条件展示,null 隐藏) -2. 总价用 `finalGrandTotal`(应付总额)替代 `totalPrice`(后者含单房差但不减优惠,继续保留作为"团费原价") -3. 应付尾款 DEPOSIT 模式用 `finalBalanceAmount`,FULL 模式用 `totalPrice` -4. 老前端不动也能跑(只是看不到新字段拆分) -5. 已存在的"老订单"(单房差功能上线前下的)`singleRoomSurcharge=null` 仍按原 totalPrice 展示,行为不变 diff --git a/changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md b/changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md deleted file mode 100644 index ed14bdf..0000000 --- a/changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md +++ /dev/null @@ -1,90 +0,0 @@ -# user/AgreementService: saveByType 漏调 invalidateSource 致 mp 协议缓存 1800s 不更新 - -> **服务**: hl-user-service (端口 8081) -> **PR**: [#1917](https://git.1814.love:8443/wx/HL/pulls/1917) -> **Issue**: 无关联工单 (prod 实战根因修复) -> **日期**: 2026-05-09 -> **影响范围**: 后端纯内部缓存失效逻辑;**API 字段/响应/路径全不变,前端无需任何改动** - ---- - -## ⚠️ 关键变化 - -- 本次只动后端 service 层缓存触发逻辑, **前端 0 改动** -- mp 端 `GET /mp/agreement/detail?type=USER_AGREEMENT|PRIVACY_POLICY` 行为变化:admin 后台保存协议后, mp 立即返回新内容(此前需等 ≤ 1800 秒 TTL 自然过期才生效) -- 不会出现接口字段/路径/状态码/响应壳变化,只是数据"更新及时性"提升 - ---- - -## 一、背景(prod 实战触发) - -2026-05-09 prod 协议数据被误改后,管理员通过 admin API 改回正确值,**但 mp 端继续显示 30 分钟前的旧内容**,最终 SSH redis-cli DEL 三个 mp 协议缓存 key 才即时恢复。 - -复盘根因: - -| 链路 | 期望行为 | 实际行为 | -|------|---------|---------| -| `AgreementService.saveById` 路径 | save → invalidateSource(`agreement`) → mp 缓存依赖链清空 | ✅ 正确 | -| `AgreementService.saveByType` 路径(本次问题) | save → invalidateSource(`agreement`) | ❌ 漏调 | - -`saveByType` 是按 type(`USER_AGREEMENT` / `PRIVACY_POLICY`)写入的分支,有两个落库出口(insert / update),两个分支都漏 schedule 缓存失效;mp 端读路径有 1800s TTL,所以 admin 改完正确数据,mp 仍读到 redis 内旧值。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| - | (无) | - | - | - | API 入参/出参/路径全部 0 改动 | - ---- - -## 三、行为变化(纯后端缓存) - -### admin 端写入 - -`POST /admin/agreement/save-by-type` (`AgreementService.saveByType`) -- 触发链补充:写库成功 → 注册 `cacheEvictAfterCommit.scheduleAfterCommit(depsManager.invalidateSource("agreement"))` → 事务提交后异步清空 `agreement:*` 依赖链上所有 mp 缓存 key - -### mp 端读取(透明,无显式变更) - -- `GET /mp/agreement/detail?type=USER_AGREEMENT` -- `GET /mp/agreement/detail?type=PRIVACY_POLICY` - -读路径与缓存逻辑均**不动**,只是 admin 写之后能立即看到新值。 - ---- - -## 四、不影响范围(显式声明) - -- **仅影响**: admin 保存协议后, mp 协议详情的"实时性" -- **零影响**: - - mp 协议接口字段/路径/响应壳 - - admin 协议保存接口字段/路径/响应壳 - - 协议历史版本逻辑 - - 其他模块缓存(banner / dict / review 等) - - 数据库 schema / DDL - ---- - -## 五、测试环境已验证 - -- 单元测试:`AgreementServiceTest` 新增 2 个 Mockito case,断言 `saveByType` 两个分支(insert / update)都会调用 `cacheEvictAfterCommit.scheduleAfterCommit(...)` -- 回归:`mvn test -pl hl-user-service` 全绿 - ---- - -## 六、相关历史 PR - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| (cache-deps 总治理批次) | - | banner / dict / review 等模块迁 cacheEvictAfterCommit + depsManager 的成果 | ✅ 有效 | -| **本 PR #1917** | (无) | 补 `AgreementService.saveByType` 这处遗漏 | ✅ 最新 | - ---- - -## 七、相关文档 - -- 关联 PR: [wx/HL#1917](https://git.1814.love:8443/wx/HL/pulls/1917) -- 关联 commit (squash): `8556ab60` -- 前端通知:**本次后端纯内部 BUG 修复, mmg 不需要做任何前端改动**(changelog 留底备查,不拉群) diff --git a/changelogs/2026-05/09_followup_admin_price_calendar_single_room_diff_frontend.md b/changelogs/2026-05/09_followup_admin_price_calendar_single_room_diff_frontend.md deleted file mode 100644 index 9e4efc1..0000000 --- a/changelogs/2026-05/09_followup_admin_price_calendar_single_room_diff_frontend.md +++ /dev/null @@ -1,82 +0,0 @@ -# admin 价格日历"单房差"前端回填 + 卡片展示遗漏 - -> **服务**: hl-product-service-v2(后端无改动) -> **PR**: 无后端 PR(后端已就位) -> **日期**: 2026-05-09 -> **影响范围**: 管理端"产品编辑 → 定价管理"页 - ---- - -## ⚠️ 现象(后端正常,前端遗漏) - -测试 + 正式环境复现: - -1. 用户在"编辑价格区间"弹窗填 `单房差 = 100` → 点"确认添加" → **接口 200 + DB 实际写入 single_room_diff=100** ✅ -2. 但页面上看不到效果: - - **卡片只读视图缺"单房差"列**(只显示 成人/儿童/小童优惠/幼童) - - **再次打开"编辑价格区间"弹窗,单房差栏回显 ¥0.00**(应该回显 100) - -后端验证: - -```bash -curl https://api.test.1814.love:9443/admin/product/item/2045345825172639746/price-calendar?month=2026-04 -# 响应每条记录都含 "singleRoomDiff": 100.0 -``` - -DB 直查也是 `single_room_diff=100.00`,**后端完全没问题**。 - ---- - -## 一、缺失项清单(@mmg 需修) - -### A. 卡片只读视图加"单房差"展示(2026.04.01 — 2026.04.30 那种卡片) - -**当前**:卡片只显示 4 列(成人 / 儿童 / 小童优惠 / 幼童)。 -**应改**:加第 5 列"单房差 ¥XXX"(条件:`singleRoomDiff > 0` 才展示这列;= 0 时可隐藏避免干扰)。 - -数据来源:`GET /admin/product/{id}/price-calendar?month=...` 响应数组每条记录的 `singleRoomDiff` 字段。 - -### B. "编辑价格区间"弹窗 form 初始化回填 `singleRoomDiff` - -**当前**:用户保存后再次点编辑,form 单房差栏初始化为 `0.00`(form default value),没读 DB 真实值。 -**应改**:打开编辑弹窗时 form.setFieldsValue 把对应区间记录的 `singleRoomDiff` 回填到单房差输入框。 - -注意:同一区间内 4-1 ~ 4-30 每天的 single_room_diff 都一样(后端按 rangeId 区间统一展开),取任一一天的值即可,或取该区间第一条记录的 `singleRoomDiff`。 - -### C. (可选)新建价格区间时单房差默认值 - -**当前**:输入框默认 `0.00`,@NotNull @DecimalMin("0.00"),0 合法(=不收单房差)。 -**建议**:维持 0.00 默认,不强制用户填 — 不收单房差是常态。 - ---- - -## 二、字段路径速查(无后端改动) - -| 场景 | 接口 | 字段路径 | 类型 | -|------|------|---------|------| -| 列表回显 | `GET /admin/product/{id}/price-calendar?month=YYYY-MM` | `data[i].singleRoomDiff` | BigDecimal(Number) | -| 弹窗保存 | `POST /admin/product/{id}/price-calendar/batch` | request body `singleRoomDiff` | BigDecimal(Number),@NotNull | -| 班期同款 | `GET /admin/product/{id}/schedule` 等 | `data[i].singleRoomDiff` | BigDecimal | - -**字段名**:`singleRoomDiff`(camelCase),不是 `single_room_diff`。 - ---- - -## 三、回归用例 - -测试服 / 正式环境随便挑一个产品: - -1. 进"产品编辑 → 定价管理 → 编辑价格区间" -2. 填日期范围 + 各栏价格 + 单房差 100 -3. 点"确认添加" → 接口 200 -4. **验收 A**:卡片视图显示"单房差 ¥100"行 / 列 -5. **验收 B**:再次点该区间编辑按钮,弹窗里单房差栏显示 100,不是 0.00 -6. 改成 200 保存 → 卡片更新为 200,再次编辑显示 200 - ---- - -## 四、@mmg 关注点 - -- 后端接口 + DB 字段 + GET 响应 **全部就位**,**只缺前端绑定** -- 不需要任何后端改动 -- 班期(GROUP 小蒙马)的"班期编辑"弹窗也应同步检查这两个问题(同样有 `singleRoomDiff` 字段) diff --git a/changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md b/changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md deleted file mode 100644 index f2a83fd..0000000 --- a/changelogs/2026-05/09_frontend_notice_admin_product-share-remove-target-user-step.md +++ /dev/null @@ -1,175 +0,0 @@ -> ## ⚠️ 本通知已撤回(2026-05-09 由 wx 撤回) -> -> ### 撤回原因 -> 本通知发布时基于 BUG 分析员第一轮调研的错误结论 — 当时本地 hl-ui 仓库落后远程 master **225 commits 没有 fetch**,看到的不是最新代码。第二轮调研拉远程最新版后发现: -> -> - 远程最新 `gitea/master` 的 `MiniappShareModal.vue` 自始至终就是**直接生成 scheme,没有任何"选目标用户"UI 或前置步骤** -> - 最近 225 个 commit 中只有 2 处分享相关改动,均非破坏性(路径按 productType 分流 / query 拼 adminId) -> - 用户实测确实多了"选用户"步骤,但与 master 代码不符 — 当前推测是用户访问的环境部署版本不是最新 -> -> ### 请前端 mmg 注意 -> - **暂时不要按本通知去删除任何"选用户"相关代码** — 那个代码在 master 上根本不存在,你删不到东西 -> - 真根因还在排查(用户测试的环境到底跑的哪个版本),后续会发新一条 changelog 给出准确指引 -> - 给你添麻烦了,这是管理者(我)第一轮没让 BA 强制 fetch 的失误 -> -> --- -> -> (以下为原通知,内容**作废**,仅留作历史档案) - ---- - -# 前端 BUG 通知 — admin 产品分享去掉"选目标用户"步骤,直接生成 URL Scheme - -**日期**: 2026-05-09 -**类型**: 前端 BUG (admin 后台 hl-ui) -**模块**: 产品管理 → 产品列表 → 分享按钮 (MiniappShareModal) -**通知**: @mmg -**后端是否需改动**: 否(后端接口契约自 PR #1488 上线起从未变,不需要、也不应该加 targetUserId 字段) -**严重性**: 中 — 多余步骤,影响 admin 操作效率 - ---- - -## 现象 - -入口: admin 后台 → 产品列表 → 列表行「分享」按钮 (`hl-ui/src/views/product/list/components/MiniappShareModal.vue`) - -**期望流程**: -点「分享」→ 前端组装 `path` + `query` → 直接调后端接口 → 拿到 `weixin://dl/business/?t=xxx` URL Scheme 短链 → 弹窗里展示给 admin 拷贝/转发 - -**当前流程 (bug)**: -点「分享」→ 弹出"选目标用户"列表/搜索框 → admin 选完一个用户后才生成链接 - -→ "选目标用户"这一步是**多余的**,后端接口里完全没有"目标用户"概念,该步骤可直接删掉。 - ---- - -## 根因 (后端代码反推) - -后端接口 `POST /admin/wxapp/share/url-scheme` 自 PR #1488 (2026-04-27) 上线以来,代码从未改过 — 见 `hl-user-service/src/main/java/com/hulalv/user/controller/AdminWxappShareController.java:61-72`。 - -入参 VO `WxappUrlSchemeReqVO` (`hl-user-service/src/main/java/com/hulalv/user/vo/admin/WxappUrlSchemeReqVO.java`) **完整字段清单**: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `path` | String | ✅ | 小程序页面路径(不带前导 `/`) | -| `query` | String | ❌ | querystring,如 `id=123&sharerId=456` | -| `envVersion` | String | ❌ | release / trial / develop,不传走配置默认 | -| `expireDays` | Integer | ❌ | 1-365 天,默认 30 | - -**注意**: 完全没有 `targetUserId` / `receiverId` / `userId` / `shareTo` 等"目标用户"字段。 - -后端 Service 实现 (`WechatMiniAppClient.generateUrlScheme`) 是对微信开放平台 `wxa/generatescheme` API 的纯翻译调用,接口语义上与"分享给谁"无关 — 生成的是一条**任何人**点开都能进对应小程序页面的 scheme 短链。 - -→ "选目标用户"步骤是前端 UI 单方面加的,后端**没有任何对应字段或逻辑**。即便前端额外传了 `targetUserId`,后端 VO 没声明,Spring 反序列化会忽略,最终不会进入业务逻辑。 - ---- - -## 期望前端做的事 - -修改文件: `hl-ui/src/views/product/list/components/MiniappShareModal.vue` - -**优先级 1**: 去掉"选目标用户"那一步弹窗 / 用户列表 / 搜索逻辑(以及对应的状态变量、watch、API 调用) - -**优先级 2**: 改回直接组装 `path` + `query` 调后端接口,拿到 `link` 字段后展示给 admin 拷贝/转发 - ---- - -## 后端接口契约 (前端复核用) - -### `POST /admin/wxapp/share/url-scheme` - -**Headers**: -- `Content-Type: application/json` -- `Authorization: Bearer <admin token>` - -**Request body**: - -```json -{ - "path": "pages/product/detail/detail", - "query": "id=123&sharerId=456", - "envVersion": "release", - "expireDays": 30 -} -``` - -> ⚠️ 字段约束: -> - `path` 必填,**不带前导 `/`**,长度 ≤ 256 -> - `query` 可选,长度 ≤ 1024 -> - `envVersion` 可选,仅接受 `release` / `trial` / `develop`,不传走配置默认 -> - `expireDays` 可选,范围 1-365,不传默认 30 - -**Response** `Result<WxappUrlSchemeRespVO>`: - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "link": "weixin://dl/business/?t=abc123", - "expireTime": 1735689600 - } -} -``` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `data.link` | String | scheme 短链,直接给 admin 拷贝 | -| `data.expireTime` | Long | Unix 秒级过期时间戳,微信未返回时为 null | - -**响应结构与现有前端调用完全一致,前端无需改取值代码。** - ---- - -## 后端为什么不需要(也不应该)加 `targetUserId` - -有人可能会想:既然 UI 上有"选目标用户"步骤,要不要后端也加个 `targetUserId` 字段记录一下?**不行**: - -1. 微信 `wxa/generatescheme` API 本身不接受"目标用户"参数 — scheme 短链是公开的,任何人点开都能进同一个小程序页面 -2. 如果业务需要"哪个用户分享给哪个用户"的归属关系,应该在 `query` 里塞 `sharerId` / `targetUserId` 当作小程序页面参数(前端组装 query 时自定),而不是后端 VO 加字段 -3. 加字段反而会带来"前端必传 → 不传 400"的破坏性变更 - -→ 后端接口契约保持原样,**零改动**。 - ---- - -## 复现取证 (mmg 在 DevTools 验证) - -1. **Network**: 抓「分享」按钮触发的请求,确认目标接口 `POST /admin/wxapp/share/url-scheme` -2. **Payload**: 看请求 body 里是否多塞了 `targetUserId` / `receiverId` 之类后端 VO 不存在的字段(后端会忽略,但是冗余) -3. **Sources**: 搜 `MiniappShareModal.vue`,定位"选目标用户"那段 UI 与逻辑代码,整段移除 - ---- - -## 验收 - -mmg 修完前端后,验收点: -1. admin 产品列表点「分享」按钮 → 弹窗里**直接**显示 scheme 链接(`weixin://dl/business/?t=xxx`),不再有"选目标用户"那一步 -2. 弹窗加载完成后,链接可一键拷贝 -3. 不同产品行点分享,生成的 link 携带不同 productId(`query` 字段里的 `id` 正确) -4. 后端接口 round-trip 状态码 200,响应结构与上方契约一致 - ---- - -## 涉及文件 - -**前端 (mmg 修改)**: -- `hl-ui/src/views/product/list/components/MiniappShareModal.vue` - -**后端 (零改动,仅供前端复核)**: -- `hl-user-service/src/main/java/com/hulalv/user/controller/AdminWxappShareController.java:61-72` -- `hl-user-service/src/main/java/com/hulalv/user/vo/admin/WxappUrlSchemeReqVO.java` -- `hl-user-service/src/main/java/com/hulalv/user/vo/admin/WxappUrlSchemeRespVO.java` - ---- - -## 相关历史 PR - -| PR | 说明 | 是否仍有效 | -|----|------|------------| -| #1488 | 补齐 admin 端点 `url-link` / `url-scheme` 首次上线 | ✅ 有效,本通知未改任何后端字段 | - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_frontend_notice_admin_product-share-use-customizers-endpoint.md b/changelogs/2026-05/09_frontend_notice_admin_product-share-use-customizers-endpoint.md deleted file mode 100644 index e8bd989..0000000 --- a/changelogs/2026-05/09_frontend_notice_admin_product-share-use-customizers-endpoint.md +++ /dev/null @@ -1,270 +0,0 @@ -# 前端 BUG 通知 — admin 产品分享「目标用户」下拉换接口为 `/admin/user/customizers` - -**日期**: 2026-05-09 -**类型**: 前端 BUG (admin 后台 hl-ui) -**模块**: 产品管理 → 产品列表 → **分享产品**(ShareModal,**不是** MiniappShareModal) -**通知**: @mmg -**后端是否需改动**: 否(PR #1919 已上线专用接口,前端只需切接口) -**严重性**: 高 — 「目标用户」下拉永远空,**整个分享功能不可用** - ---- - -## ⚠️ 关键变化 - -PR #1919 (Closes #1918) 后端为产品分享场景**新增了独立接口** `GET /admin/user/customizers`(返回所有持 `CUSTOMIZER` 角色的 admin,**无 status 过滤、无企微绑定过滤**)。 - -但当前前端 `ShareModal.vue` 没接这个新接口,line 87-102 仍在调 `getUserPage({status: 1})`(老的 admin 分页接口)。后端 `AdminUserController.listAdmins` line 167 看到 `status="1"` 不在英文常量白名单(`ACTIVE/LOCKED/DISABLED/DELETED`)内,**直接返回空 PageResult**(Issue #1829 防 jsqlparser 崩的硬白名单),所以下拉永远是空。 - ---- - -## 现象 - -入口:admin 后台 → 产品列表 → 列表行「**分享**」按钮 (`hl-ui/src/views/product/list/components/ShareModal.vue`) - -弹窗"分享产品"对话框 →「目标用户」下拉框点开 → **空列表 + 提示"请选择目标用户"** → 无法选择任何人 → 无法点确定 → 整个分享流程跑不通。 - ---- - -## 根因(代码反推) - -### 前端调错接口 - -`hl-ui/src/views/product/list/components/ShareModal.vue:87-102`: - -```js -async function loadUsers() { - userLoading.value = true - try { - const res = await getUserPage({ page: 1, pageSize: 100, status: 1 }) // ❌ 接口选错 + 参数选错 - userOptions.value = (res?.records || res?.list || []) - .filter((u) => String(u.id) !== String(currentUserId.value)) - .map((u) => ({ - label: `${u.realName || u.username}${u.mobile ? ` (${u.mobile})` : ''}`, - value: u.id, - })) - } catch (error) { ... } -} -``` - -`getUserPage` (`hl-ui/src/api/user.js:128-130`) 实际调 `GET /admin/user`,即 admin 用户分页接口。 - -### 后端返空逻辑 - -`hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java:167-169`: - -```java -// status 字典白名单校验:非字典值(如 "1"/"0"/"true"/"ABCXYZ")直接返空页, -// 不进 mapper 以规避 MP PaginationInnerInterceptor 的 jsqlparser fallback BUG (Issue #1829) -if (status != null && !status.isEmpty() && !VALID_ADMIN_STATUS.contains(status)) { - return Result.success(PageResult.of(Collections.emptyList(), 0L, page, pageSize)); -} -``` - -`VALID_ADMIN_STATUS` 是英文常量集合 `{ACTIVE, LOCKED, DISABLED, DELETED}`,前端传 `status: 1`(数字 1) → 不在白名单 → 接口直接返 `{records: [], total: 0}` → 下拉永远空。 - -### 后端已有专用接口(PR #1919) - -PR #1919 (commit `a18329b7`) 已专门为分享产品下拉新增接口,前端**未接**。 - ---- - -## 期望前端做的事 - -修改文件: `hl-ui/src/views/product/list/components/ShareModal.vue` - -**优先级 1**: 把 `loadUsers` 里的 `getUserPage(...)` 改为调新接口 `GET /admin/user/customizers`(无入参)。 - -**优先级 2**: 字段 mapping 改为新接口返回的轻量 VO 字段(见下方契约)。 - -**优先级 3**: `currentUserId` 排除自己的逻辑改用 `adminId` 比较(新接口字段是 `adminId`,不是 `id`)。 - -### 建议改后伪代码 - -```js -import { listShareCustomizers } from '@/api/user' // 新增导出函数 - -async function loadUsers() { - userLoading.value = true - try { - const list = await listShareCustomizers() // GET /admin/user/customizers - userOptions.value = (list || []) - .filter((u) => String(u.adminId) !== String(currentUserId.value)) - .map((u) => ({ - label: u.username, // 轻量 VO 没 realName / mobile,只用 username - value: u.adminId, // 注意是 adminId,不是 id - })) - } catch (error) { - console.error('加载定制师列表失败:', error) - } finally { - userLoading.value = false - } -} -``` - -`hl-ui/src/api/user.js` 建议在 `getDesignerList` 旁边加: - -```js -/** - * 分享产品场景的目标定制师下拉(不分页,无 status/企微过滤) - * @returns {Promise<Array>} Array<CustomizerSimpleVO> - */ -export function listShareCustomizers() { - return http.get('/user/customizers') -} -``` - ---- - -## ✅ 已经过测试服 round-trip 验证(2026-05-09 19:30) - -经网关 `https://api.test.1814.love:9443/admin/user/customizers` + SUPER_ADMIN token 实测: -- HTTP 200 + `code=200` + `success=true` -- `data` 是非空 `List`,共 **20 条**(测试服 admin_user 中所有持 CUSTOMIZER 角色且非 DELETED 的 admin) -- 字段命名与契约一致:`adminId` / `username` / `avatar` -- 无 token 反例 → 网关 401 `Missing or invalid Authorization header` -- 与 `/admin/user/designers` 对比:designers 只返 18 条(过滤 active+企微),customizers 返 20 条全集(含 admin/qulili 等无企微的轻量 admin) — 符合"分享下拉不过滤"语义 - -→ 后端接口工作正常,前端切到本接口即可,**无需后端再改任何东西**。 - ---- - -## ⚠️ 前端 JS 精度坑(必看) - -实测响应里 `adminId` **同时有 Number 和 String 两种类型**: -- 旧 admin (`adminId=1001 / 1002`) → JSON Number -- 新 admin (雪花 ID 如 `"2021059720172838914"`) → JSON String - -→ 前端 v-model 绑 `value: u.adminId` 时必须**统一用 String 处理**,否则 19 位雪花 ID 转 Number 会精度丢失末几位,选完用户提交时 `targetUserId` 错位,后端按错的 ID 复制产品。 - -正确做法: - -```js -.map((u) => ({ - label: u.username, - value: String(u.adminId), // ← 统一 String,防雪花 ID 精度丢失 -})) - -// 排除自己时也用 String 比较 -.filter((u) => String(u.adminId) !== String(currentUserId.value)) -``` - -提交分享时如果后端 VO 字段是 `Long targetAdminId`,Spring 反序列化会自动把 String "20210597..." 转 Long,**前端只管全程当 String 用即可**。 - ---- - -## 后端接口契约 - -### `GET /admin/user/customizers` - -**Headers**: -- `Authorization: Bearer <admin token>` (网关校验) - -**Query / Body**: 无任何参数。 - -**Response** `Result<List<CustomizerSimpleVO>>`: - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": [ - { - "adminId": 1001, - "username": "wx-01", - "avatar": "https://cdn.hulalv.com/avatar/xxx.jpg" - }, - { - "adminId": 1002, - "username": "test_admin", - "avatar": null - } - ] -} -``` - -| 字段 | 类型 | 必返 | 说明 | -|------|------|------|------| -| `data[].adminId` | Long | ✅ | admin 主键,前端 v-model 绑这个 | -| `data[].username` | String | ✅ | admin 登录名,作为下拉显示文案 | -| `data[].avatar` | String | ❌ | admin_user 自身头像列,可能为 null | - -**重要**: -- 返回**所有持 `CUSTOMIZER` 角色的 admin**(`status=ACTIVE/LOCKED/DISABLED` 全部包含,只排除 `status=DELETED`)。 -- **不要求企微绑定**,与 `/admin/user/designers` 的区别见 Swagger notes。 -- 按 `adminId` 升序,稳定排序,前端可缓存。 -- **不**返回 `realName` / `mobile` / `phone` / 富信息(分享场景不需要,后端故意精简)。 - ---- - -## 为什么不能继续用 `/admin/user`(老分页接口) - -1. **status=1 永远返空**:后端老 admin_user.status 是英文常量,前端传整数 `1` 必返空(白名单逻辑见上)。 -2. **status=ACTIVE 仍不全**:即使前端改成 `status: 'ACTIVE'`,也漏掉 `LOCKED/DISABLED` 的定制师 — 业务上分享给 LOCKED admin 也是合理的(后端不限制)。 -3. **`/admin/user` 不限角色**:会带回 `SUPER_ADMIN/ADMIN/FINANCE` 等非定制师,前端还得二次过滤,徒增复杂度。 -4. **`/admin/user/designers` 也不行**:它是 C 端订单展示用,过滤了 `status=ACTIVE` + `企微非空`,与分享场景需求不一致。 - -→ **必须用 `/admin/user/customizers`**,这是后端 PR #1919 专门为本场景设计的接口。 - ---- - -## 复现取证(mmg 在 DevTools 验证) - -1. **Network**:点产品列表「分享」按钮 → 抓「目标用户」下拉触发的请求,确认 URL 是 `GET /admin/user`(老接口)还是 `GET /admin/user/customizers`(新接口)。 -2. **Response**:看老接口响应是否就是 `{ records: [], total: 0 }`。 -3. **DevTools Sources**:搜 `ShareModal.vue` line 90,确认调用是 `getUserPage({status: 1})`。 - ---- - -## 验收 - -mmg 修完前端后,验收点: -1. admin 产品列表点「分享」→ 弹窗里「目标用户」下拉**有数据**,列出当前所有 `CUSTOMIZER` 角色 admin(不含自己)。 -2. 选一个目标 → 点「确定」→ 后端 `POST /admin/product/item/{id}/share` 200 → 提示"分享成功"。 -3. 下拉里 `status=LOCKED/DISABLED` 的定制师**也应能选**(后端不限,业务允许)。 -4. **不要**再传 `status: 1` 这种数字状态值给任何 `/admin/user/*` 接口 — 后端 status 字段一律是英文常量。 - ---- - -## 涉及文件 - -**前端(mmg 修改)**: -- `hl-ui/src/views/product/list/components/ShareModal.vue` (line 87-102 的 `loadUsers` 整段改) -- `hl-ui/src/api/user.js` (新增 `listShareCustomizers` 导出) - -**后端(零改动,仅供前端复核)**: -- `hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java:182-195` (`/customizers` 端点) -- `hl-user-service/src/main/java/com/hulalv/user/service/DesignerService.java:60-130` (`listAllCustomizersForShare` + `getAllCustomizerAdminsRaw`) -- `hl-user-service/src/main/java/com/hulalv/user/vo/CustomizerSimpleVO.java` (轻量 VO) - ---- - -## 不影响范围 - -- **仅影响**:管理后台「分享产品」对话框的「目标用户」下拉。 -- **零影响**: - - C 端订单定制师卡片(继续用 `/admin/user/designers`,过滤逻辑不变) - - admin 用户管理列表(`/admin/user` 分页接口本身没变,前端别处该传 `status='ACTIVE'` 的地方继续按英文常量传) - - 产品复制底层逻辑(`ProductCopyService` 已支持 `targetAdminId` 参数,后端打通) - ---- - -## 相关历史 PR - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| #1488 | - | admin URL Scheme/Link 接口(`MiniappShareModal` 走这个) | ✅ 有效,与本通知无关 | -| **#1919** | **#1918** | **本通知关联**:实现 admin 分享产品功能(后端打通+新增 `/customizers` 接口) | ✅ 最新 | - -历史撤回的通知 `09_frontend_notice_admin_product-share-remove-target-user-step.md` 是针对 **MiniappShareModal**(URL scheme 短链场景),与本通知针对的 **ShareModal**(产品复制给定制师)是两个不同弹窗,不要混。 - ---- - -## 相关文档 - -- 关联 Issue: [wx/HL#1918](https://git.1814.love:8443/wx/HL/issues/1918) -- 关联 PR: [wx/HL#1919](https://git.1814.love:8443/wx/HL/pulls/1919) - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_frontend_notice_admin_service-edit-categorycode-required.md b/changelogs/2026-05/09_frontend_notice_admin_service-edit-categorycode-required.md deleted file mode 100644 index e4bf85d..0000000 --- a/changelogs/2026-05/09_frontend_notice_admin_service-edit-categorycode-required.md +++ /dev/null @@ -1,95 +0,0 @@ -# 前端 BUG 通知 — 服务管理编辑保存误调 POST 创建接口 (categoryCode 校验失败) - -**日期**: 2026-05-09 -**类型**: 前端 BUG (admin 后台 hl-ui) -**模块**: 资源管理 → 服务管理 (Service Item) -**通知**: @mmg -**后端是否需改动**: 否(本是误调创建接口,后端 PATCH 语义正确,不能为对齐而加 NotBlank) -**严重性**: 正式环境用户已遇 - ---- - -## 现象 - -正式 `admin.1814.love/service/list`，编辑列表里现有服务"蒙古族·礼仪接机"(已显示分类「机场接送」),进入编辑抽屉,切到「地理位置」tab 改了字段后点「确定」保存。 - -右上角红色 toast: **`categoryCode: 分类编码不能为空`** - -服务在列表里**已经有 categoryCode**（列表显示「机场接送」标签),但保存却报"为空" — 不合常理,排查确认是前端误把 update 当 create 调了。 - ---- - -## 根因 (后端代码反推链) - -后端 `ServiceItemController` 有两条接口: - -| 方法 | 路径 | 入参 VO | categoryCode 校验 | -|------|------|--------|----| -| **POST** | `/admin/service/item` (创建) | `ServiceCreateRequest` | `@NotBlank(message="分类编码不能为空")` ← 与 toast 文案**字面完全匹配** | -| **PUT** | `/admin/service/item/{serviceId}` (更新) | `ServiceUpdateRequest` | 仅 `@Size(max=32)`,**无 NotBlank**,patch 语义 null 跳过 | - -错误消息文案与 `ServiceCreateRequest.categoryCode` 的 `@NotBlank.message` 字面完全一致 → 前端编辑保存时打的是 **POST 创建**,而不是 **PUT 更新**;且请求体里没有 categoryCode (大概率只 pick 了改动 tab 的字段,即 dirty 提交) → 触发 Create 的 NotBlank 校验。 - ---- - -## 复现取证(请 mmg 在 DevTools 验证) - -1. **Network**: 抓「服务编辑」保存按钮触发的请求,看 method 是 `POST` 还是 `PUT`,看 URL 是 `/admin/service/item` 还是 `/admin/service/item/{id}` -2. **Payload**: 看 body 里是否带了 `categoryCode` 字段 -3. **Sources**: 搜 `service/item` 或 `serviceApi.update`、`serviceApi.create`,确认编辑场景调用了哪个 API method -4. **State**: 检查表单 store / form ref 是否在打开抽屉时把详情接口返的 `categoryCode` 字符串写进了表单 model - ---- - -## 建议修复方向 (前端) - -**优先级 1**: 编辑模式必须打 `PUT /admin/service/item/{serviceId}`,不能打 `POST /admin/service/item` -- 检查抽屉组件区分 create / edit 两种 mode 的逻辑(常见做法是看 form 里的 id/serviceId 是否存在) -- 编辑模式下保存按钮的 onClick 应进 update 分支 - -**优先级 2**: 表单 model 初始化时,把详情接口返的 `categoryCode` 显式写入 form data;保存时**整体提交** form data,而非只 pick 改动 tab 的字段 -- 多 tab 表单常见坑 — "地理位置 tab 改了 → 只提交位置字段",但如果走 PUT 后端是 patch 语义这样也 OK,关键还是 method 别错 - ---- - -## 后端为什么不"对齐"加 NotBlank - -有人会想:那把 `ServiceUpdateRequest.categoryCode` 也加 `@NotBlank` 不就早早暴露问题了?**不可以**。 - -`ServiceUpdateRequest` 是 PATCH 语义(`updateServiceItem` 实现里 null 跳过),前端**任意部分更新**(只改地理位置、只改媒体素材、只改描述)都不应被强制要求带 categoryCode。加 NotBlank 会让所有部分更新失败。 - -正确做法是:**前端调对接口**,后端保持 PATCH 语义不变。 - ---- - -## 连锁影响 — mmg 自检清单 - -资源管理下其他几个模块的 CreateRequest 都有相同的 `@NotBlank(message="分类编码不能为空")` 校验,UpdateRequest 多半也是 PATCH 语义没加。**如果前端这几个模块的编辑保存都是同一套"区分 create/edit"代码**,只要服务管理这里有 bug,其他模块大概率连锁: - -- 备品管理 (supplies) -- 游玩项目管理 (activity / play-item) -- 餐厅管理 (restaurant) -- 额外成本 (cost) -- 素材库 (material) - -请 mmg 一起自检:点这些列表里现有记录的「编辑」,改非 categoryCode 字段后保存,看是否同样报 categoryCode 不能为空。如果是,统一修复 update 路径。 - ---- - -## 后端 RespVO 是否够用 (无需改) - -确认过: -- `ServiceItemVO` (详情 RespVO) 含 `categoryCode` 字段 -- `ServiceItemListVO` (列表 RespVO) 含 `categoryCode` 字段 - -详情接口已经返了 `categoryCode` 字符串,前端编辑模式可直接拿来回填 form,**无需任何额外接口**。 - ---- - -## 验收 - -mmg 修完前端后,验收点: -1. 列表里点「编辑」打开抽屉 → 不改任何字段直接点「确定」 → 应保存成功(不应报 categoryCode 不能为空) -2. 列表里点「编辑」打开抽屉 → 只改「地理位置」tab → 应保存成功 -3. 「添加服务」按钮 → 不填 categoryCode → 仍应报 categoryCode 不能为空(创建场景的校验不动) -4. 资源管理其他 5 个模块编辑场景同样 1/2/3 验证一遍 diff --git a/changelogs/2026-05/09_frontend_notice_admin_share-modal-show-enterprise-wechat-name-P0.md b/changelogs/2026-05/09_frontend_notice_admin_share-modal-show-enterprise-wechat-name-P0.md deleted file mode 100644 index 0ae9ed4..0000000 --- a/changelogs/2026-05/09_frontend_notice_admin_share-modal-show-enterprise-wechat-name-P0.md +++ /dev/null @@ -1,96 +0,0 @@ -# 🔴 P0 前端 BUG 紧急通知 — ShareModal label 直接展示企微名,不要 fallback - -**日期**: 2026-05-09 -**类型**: 前端 P0 BUG (紧急,用户已经第 2 次反馈) -**模块**: 产品管理 → 产品列表 → 分享产品(ShareModal) -**通知**: @mmg -**严重性**: **P0** — 用户连续 2 次反馈"分享下拉显示英文 username,要中文真名" -**前端改动**: **就 1 行** - ---- - -## ⚠️ 用户原话 - -> "我只要展示企业微信名不要复杂化" - -**直接改 label = enterpriseWechatName,不要 fallback chain,不要拼接 mobile**。 - ---- - -## 当前实测线上版本(测试服 hl-admin/assets/ShareModal-2fxUWA3D.js) - -```js -const e = await V(); // V = ju = GET /admin/user/customizers ✅ 接口对的 -p.value = t.filter(o => String(o.adminId) !== String(I.value)) - .map(o => ({ - label: `${o.nickname || o.realName || o.username || ""}${o.mobile ? ` (${o.mobile})` : ""}`, // ❌ 这一行错 - value: o.adminId - })) -``` - -后端 `customizers` 接口**根本不返** `nickname` / `realName` / `mobile` 字段(只返 `adminId / username / enterpriseWechatName / avatar`),所以 fallback chain 一路落到 `o.username`,展示英文登录名。 - ---- - -## ✅ 改成 - -```js -.map(o => ({ - label: o.enterpriseWechatName, // ← 就这一行,纯展示企微名 - value: o.adminId -})) -``` - ---- - -## 后端字段证据(已部署到测试服 21:50) - -```bash -$ curl https://api.test.1814.love:9443/admin/user/customizers -{ - "code": 200, - "data": [ - { "adminId": 1001, "username": "admin", "enterpriseWechatName": null, "avatar": null }, - { "adminId": "2021059720172838914", "username": "wx", "enterpriseWechatName": "王骁", ... }, - { "adminId": "2027579942221352962", "username": "mmg", "enterpriseWechatName": "米明光", ... }, - { "adminId": "2033349904889524226", "username": "qulili", "enterpriseWechatName": "曲丽莉", ... }, - { "adminId": "2033349906135203841", "username": "bozhihe", "enterpriseWechatName": "卜志鹤 18847040111", ... } - ] -} -``` - -20 条 admin 中,绑企微的全有中文真名,未绑(admin / test_admin)的为 null。 - ---- - -## 注意:没绑企微的 admin - -- admin / test_admin 这种没绑企微的,enterpriseWechatName = null -- 改 label = `o.enterpriseWechatName` 后,他们在下拉里显示空白 -- 用户的预期是"只展示企微名",所以**空白是预期行为**,不要 fallback 到 username - -如果业务上希望"未绑企微的人不在下拉里",前端可以加一行 `.filter(o => o.enterpriseWechatName)` 把这些过滤掉。这点请你按 UX 决策,不强求。 - ---- - -## 改完之后 - -1. `pnpm build` -2. 部署 hl-admin(deploy panel 触发 frontend 部署) -3. 浏览器硬刷新 Ctrl+Shift+R -4. 产品列表 → 任一产品「分享」按钮 → 看下拉: - - 王骁 / 米明光 / 曲丽莉 / 卜志鹤 ... ✅ - - 不再有 admin / test_admin / wx / mmg 这种英文 username - ---- - -## 历史 changelog 关系 - -- `09_feat_admin_customizers-add-enterprise-wechat-name.md` (commit `1e3feab`,~21:55):后端加字段通知,提了 `label = enterpriseWechatName ?? username` — **本通知撤销 fallback 建议**,改为纯展示企微名(用户明确反对复杂化) -- `09_frontend_notice_admin_product-share-use-customizers-endpoint.md`:接口切换通知,已生效 -- `09_fix_admin_product-share-2-regressions.md`:后端 2 项回归修复,无前端改动 - ---- - -**联系人**: wx -**P0 紧急度**: ⚠️ 用户连续 2 次反馈,优先级最高,请立即改这 1 行 + 部署 diff --git a/changelogs/2026-05/09_frontend_notice_admin_topic-filter-dup-request.md b/changelogs/2026-05/09_frontend_notice_admin_topic-filter-dup-request.md deleted file mode 100644 index a468676..0000000 --- a/changelogs/2026-05/09_frontend_notice_admin_topic-filter-dup-request.md +++ /dev/null @@ -1,89 +0,0 @@ -# 前端 BUG 通知 — 主题列表筛选触发并发 3 请求互相 cancel (DevTools 实测纠正 07 文件根因) - -**日期**: 2026-05-09 -**类型**: 前端 BUG (admin 后台 hl-ui) -**模块**: 主题管理 (产品线 / Product Line) -**通知**: @mmg -**后端是否需改动**: 否(本日已 PR #1908 做防御性加固) -**关联**: `07_frontend_notice_topic-filter-empty.md` (07 文件的根因推断 A/B 已被本次 DevTools 证据**否定**) - ---- - -## 现象 - -用户 2026-05-09 复现, DevTools Network 截图证实: - -打开「主题列表」页 → 选「主题类型 = 小蒙马」点搜索 → 列表显示「暂无主题数据」, 但顶部仍显示「共 15 条」 - -**Network 关键发现**: -- 同一时刻并发发出 **3 个请求**, productType 分别是 `CORE` / `CUSTOM` / `GROUP` -- 所有 3 个请求 status 全部 `(canceled)` (size 0.0kB / time 8-27ms) -- 因为请求都被 cancel, 列表 store 收不到任何 data → 列表空 -- 「共 15 条」是上一次请求成功的缓存值, 没刷 - -``` -list?keyword=&productType=CORE&page=1&pageSize... (canceled) 27 ms -list?keyword=&productType=CUSTOM&page=1&pageSize... (canceled) 10 ms -list?keyword=&productType=GROUP&page=1&pageSize... (canceled) 8 ms -``` - ---- - -## 根因 (推翻 07 文件的 A/B 推断) - -07 文件原推断: -- (A) 字典 store localStorage 老数据 → ❌ 不成立, 请求里 productType 字段是正确的字典 value -- (B) 前端把 label 当 value 传给后端 → ❌ 不成立, 请求里清楚是 `GROUP` 而非 `小蒙马` - -**真实根因 (推断)**: - -页面进入时 URL 带 `?productType=GROUP`, 触发了**多个 watch/computed 同时联动**, 各自独立调 `getProductLinePage()` 拼接不同的 productType: -- 一个 watch 监听 URL query → 发 `productType=GROUP` -- 另一个 watch 监听筛选下拉 model → 看到 dict store 拉好后默认 option 又触发一次, 可能是 CORE -- 又一个 watch 监听某个状态切换 → 发 `productType=CUSTOM` - -axios 默认会把同一接口的并发请求按 `cancelToken` 互相 cancel (项目 axios 拦截器很可能有 dedupe / cancel-on-new 逻辑), 结果**3 个全被 cancel** (互相 cancel 死锁). - ---- - -## 复现取证 - -请 mmg 在 DevTools 里: -1. Network 抓页面进入时刻所有 `GET /admin/product/line/list` 请求, 看是否真的有 3 个并发 -2. Sources 里搜 `getProductLinePage` 找所有调用点, 看是否多个 watch/onMounted/init 各自触发了一次 -3. axios 拦截器 (`hl-ui/src/utils/request.js` 或 `hl-ui/src/api/index.js`) 是否有 cancel-on-duplicate 逻辑 - ---- - -## 建议修复方向 - -**优先级 1**: 把 `getProductLinePage` 调用收敛到**单一入口**: -- 页面 onMounted 触发一次 fetch -- 用户点搜索 / reset / 改筛选 → 只有点搜索按钮才 fetch (不要 watch 字段直接 fetch) -- URL query 同步只更新 store / 表单 model, 不直接 fetch - -**优先级 2**: 检查 axios 拦截器 cancel 逻辑: -- 如果有 dedupe by url, `productType=GROUP` 与 `productType=CORE` URL 不同应当不算 dup, 但仍被 cancel → 拦截器逻辑 bug -- 临时缓解: 关掉这个 dedupe / cancel-on-new - -**优先级 3**: 后端兼容性 (本次 PR #1908 已加固) -- 即使前端真传了 `productType=GROUP,CORE,CUSTOM` 拼接形式, 后端也能 setter 兼容 -- 即使前端某次传了字典里没有的 status, 后端不再 500 - ---- - -## 涉及文件 (前端排查参考) - -- 页面: `hl-ui/src/views/product/line/index.vue` -- API: `hl-ui/src/api/product/core.js:49-51` `getProductLinePage` -- axios 配置: `hl-ui/src/utils/request.js` 或 `hl-ui/src/api/index.js` - ---- - -## 后端关联 - -后端今日 PR #1908 已落地防御性加固 (详见 `09_refactor_admin_list_filter_governance.md`): -- `ProductLinePageReqVO.productType` 改 `List<String>` + 自定义 setter, 兼容 4 种入参 -- 即使前端按重复 key / 逗号分隔 / 单值任一方式发送, 后端能正确接住 - -后端**不能**修复"3 个请求互相 cancel"问题——这是前端调用频次问题, 必须前端修. diff --git a/changelogs/2026-05/09_refactor_admin_contract-scheme-drop-dispute-fields.md b/changelogs/2026-05/09_refactor_admin_contract-scheme-drop-dispute-fields.md deleted file mode 100644 index 8596a89..0000000 --- a/changelogs/2026-05/09_refactor_admin_contract-scheme-drop-dispute-fields.md +++ /dev/null @@ -1,130 +0,0 @@ -# 合同方案删除「管辖法院/仲裁委员会/争议解决方式」3 字段 - -> **服务**: hl-order-service-v2 (8094) -> **PR**: #1929 -> **Issue**: #1928 -> **日期**: 2026-05-09 -> **影响范围**: admin「合同管理 → 合同方案」编辑/新增弹窗 - ---- - -## ⚠️ 关键变化 - -合同方案弹窗删除以下 3 个字段, **前端必须同步删 form item 否则保存接口会 400**: -- `disputeResolution` 争议解决方式 (1=诉讼 / 2=仲裁) -- `tribunalName` 仲裁委员会 -- `litigationCourt` 管辖法院 - -travel_agency 表已有 `tribunal_name` `litigation_court` 字段, 合同生成时自动从所选旅行社读取, 用户不再需要在合同方案里重复填。 - ---- - -## 一、背景 - -代码 `ContractCreateService.java:1179` 注释明确写: -> 业务规则(2026-05-04 用户反馈): 合同方案表单移除"管辖法院"输入(走 agency 自动兜底) - -历史改动只补了 fallback 逻辑没真删字段, 导致合同方案弹窗仍要求填这些字段, 用户多次反馈。本次彻底清理。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | -|---|------|------|------|----------| -| 1 | 创建合同方案 | POST | `/admin/contract/scheme` | 请求体删 3 字段 | -| 2 | 更新合同方案 | PUT | `/admin/contract/scheme/{schemeId}` | 请求体删 3 字段 | -| 3 | 查询启用方案列表 | GET | `/admin/contract/scheme/list` | 响应体删 3 字段 | -| 4 | 查询单个方案 | GET | `/admin/contract/scheme/{id}` | 响应体删 3 字段 | - ---- - -## 三、ContractSchemeRequest 入参变化 - -### 删除字段 (必删) - -```java -// 删除前 -private Integer disputeResolution; // @Min(1) @Max(2) -private String tribunalName; // @Size(max=100) -private String litigationCourt; // @Size(max=100) -``` - -前端 form 必须删除对应 input/radio。如果前端继续传这 3 个字段, Spring 反序列化会忽略(因为 DTO 上没有), 但建议同步删除 UI 避免误导用户。 - -### 保留字段(关键) - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `schemeName` | String | ✅ | 方案名称 | -| `contractPlatform` | String | ✅ | 合同平台 (12301 / TENCENT_ESIGN) | -| `contractTemplateCode` | String | ✅ | 合同模板编码 | -| `agencyCode` | String | ❌ | 旅行社编码(不填走支付商户号自动匹配) | -| `transactorName` | String | ❌ | 经办人姓名 | -| `transactorPhone` | String | ❌ | 经办人电话 | -| `signatoryMode` | Integer | ❌ | 签署模式 | -| `contractMode` | String | ❌ | 签约模式 | -| `supplementaryClause` | String | ❌ | 补充条款 | - ---- - -## 四、ContractSchemeVO 响应变化 - -响应体删除: -```json -// 修复前 -{ "disputeResolution": 2, "tribunalName": "呼伦贝尔仲裁委员会", "litigationCourt": "海拉尔区人民法院", ... } - -// 修复后 -{ "schemeName": "...", "contractPlatform": "12301", ... } // 3 字段消失 -``` - -如果前端编辑表单的 echo 逻辑里取了这 3 个值, 改成不取(或对不存在字段做容错)。 - ---- - -## 五、合同生成兜底逻辑(后端自动, 前端无感) - -走 12301 / 腾讯电子签生成合同时, 法律字段从所选 agency 读: - -| 字段 | 兜底链 | -|---|---| -| 仲裁委员会 | `agency.tribunal_name` → 常量「呼伦贝尔仲裁委员会」 | -| 管辖法院 | `agency.litigation_court` → 常量「海拉尔区人民法院」 | -| 争议解决方式 | 默认 `2` (仲裁) | - -travel_agency 表已存 `tribunal_name` `litigation_court`, admin「公司管理」编辑该公司时填写。 - ---- - -## 六、前端 mmg 改造点 - -### 文件: `hl-ui/src/views/contract/scheme/...`(合同方案弹窗) - -1. **删除 3 个 form item**: - - "争议解决方式" radio (1=诉讼 / 2=仲裁) - - "仲裁委员会" input - - "管辖法院" input -2. **submit 时不传** `disputeResolution / tribunalName / litigationCourt` -3. **echo 时不取** 这 3 个字段(响应体没有了, 取了会 undefined) -4. 弹窗变得更简洁(只剩方案名、合同平台、模板、签约/签署模式、旅行社、补充条款) - -### 测试服 API 验证 (2026-05-09 21:25) - -| Case | 实测 | -|---|---| -| `GET /admin/contract/scheme/list` | 200, 响应体已无 3 字段 | -| DB `SHOW COLUMNS FROM contract_scheme` | 3 列已 DROP, V20260510_001 success=1 | -| 合同生成走 12301 | tribunal/court 走 agency 字段, dispute 默认 2(仲裁), 单测 `disputeResolutionNull_fallbackToArbitration2` 验证通过 | - ---- - -## 七、不在本 PR 范围 - -- travel_agency 加 `dispute_resolution` 字段(让公司维度可配)留后续工单 -- 历史 contract_scheme 表 3 列值随 DROP COLUMN 丢失(业务上 agency 兜底, 不影响) -- 已签合同的渲染不受影响(渲染走快照, 此次只改新建合同的字段来源) - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/09_refactor_admin_list_filter_governance.md b/changelogs/2026-05/09_refactor_admin_list_filter_governance.md deleted file mode 100644 index bc588d7..0000000 --- a/changelogs/2026-05/09_refactor_admin_list_filter_governance.md +++ /dev/null @@ -1,108 +0,0 @@ -# admin 列表筛选纪律全面治理 (8 处) - -> **服务**: hl-product-service-v2 (8093) + hl-order-service-v2 (8094) -> **PR**: #1908 (Closes #1907) -> **日期**: 2026-05-09 -> **影响范围**: 管理端列表分页接口 - ---- - -## ⚠️ 关键变化 - -admin 端 8 个列表分页接口的「下拉筛选」行为统一治理。**API 路径/请求参数/响应字段不变**，仅治理两类范式不健壮： - -| 类别 | Before | After | -|------|--------|-------| -| A. ProductLine 筛选字段类型 | `productType` 单值 String 派生 `ProductTypeList` 不通 → 筛选不生效 | `List<String>` + 自定义 setter, 兼容 4 种入参 | -| B. status/type/productType/platform 筛选 | Service 调 `XxxEnum.of(req.getStatus())`, 字典+1 enum 不+1 时抛 IAE → 500 | String 直接透传 + `eqIfPresent + StrUtil.isNotBlank`, 字典已有合法值 → 正常筛选; 非法/未知值 → 视同未筛选返回全量 | - ---- - -## 一、影响接口清单 - -### A. ProductLine 筛选字段不通 (1 处) - -| 接口 | 方法 | 路径 | 变更 | -|------|------|------|------| -| 主题列表 | GET | `/admin/product/line/list` | `productType` 后端接收**兼容性扩大**到 4 种入参形式 | - -**4 种兼容入参** (前端任一方式都能正确接住): -- `?productType=GROUP`(单值) -- `?productType=CORE,GROUP`(逗号分隔) -- `?productType=CORE&productType=GROUP`(重复 key) -- POST body `{"productType":["CORE","GROUP"]}`(JSON 数组) - -### B. enum.of() IAE 隐患 → String 透传 (7 处) - -| # | 接口 | 方法 | 路径 | 治理字段 | -|---|------|------|------|----------| -| 1 | admin 订单列表 | GET | `/admin/order/list` | status / processStatus / productType | -| 2 | designer 订单列表 | GET | `/admin/order/designer-orders` | status | -| 3 | 工单列表 | GET | `/admin/workorder/page` | status / type | -| 4 | 保险单列表 | GET | `/admin/insurance-order/page` | status | -| 5 | 定制需求列表 | GET | `/admin/customize-request/page` | status | -| 6 | 合同列表 | GET | `/admin/contract/page` | status / platform | -| 7 | 发票列表 | GET | `/admin/invoice/page` | status | - ---- - -## 二、行为变化（前端关注） - -| 场景 | Before | After | -|------|--------|-------| -| 字典已有的合法值, 如 `status=PAID` | 正常筛选 | 正常筛选(行为不变) | -| 字典新增了值 enum 还没同步, 如未来加 `status=AFTER_SALES` | **HTTP 500 IllegalArgumentException** | 正常筛选(直接 SQL eq) | -| 传字典里完全没有的值, 如 `status=XXX_NOT_EXIST` | HTTP 500 | HTTP 200 但返回空列表 | -| 不传 / 空字符串 | 不筛选 | 不筛选(行为不变) | - -**前端不需要任何改动**, 但建议: -- 已有字典 fallback 逻辑可保留也可移除(后端不再 500) -- 主题列表前端的「重复请求互相 cancel」BUG 详见同日 `09_frontend_notice_admin_topic-filter-dup-request.md` - ---- - -## 三、内部范式 - -参照 `RefundApplicationMapper.selectPage` 既有正确范式: - -```java -// Before (Mapper) -default IPage<XxxDO> selectPage(... String status, ...) { - return selectPage(page, new LambdaQueryWrapperX<XxxDO>() - .eq(XxxStatus.of(status)) // 字典+1 enum 不+1 → IAE - ...); -} - -// After (Mapper) -default IPage<XxxDO> selectPage(... String status, ...) { - return selectPage(page, new LambdaQueryWrapperX<XxxDO>() - .eqIfPresent(XxxDO::getStatus, StrUtil.isNotBlank(status) ? status : null) - ...); -} -``` - ---- - -## 四、不变化 - -- DB schema / 字典表 / Flyway: **不动** -- enum 类型本身: **不删**, 仍可作字面量使用 (如 `if (PAID.name().equals(status))`) -- 前端 VO 字段名/类型契约: **不变** -- 排序/分页逻辑: **不变** -- 数据权限/角色控制: **不变** - ---- - -## 五、测试 - -- hl-product-service-v2: `ProductLineMapperTest 13 / ProductLinePageReqVOTest 9 / ProductPricingServiceTest 64 / ProductPricingServiceMpQuoteTest 5 / MpProductServiceTest 69 = 160 全绿` -- hl-order-service-v2: `ContractQueryServiceTest 27 / OrderInvoiceServiceTest 31 / OrderListQueryServiceTest 19 / OrderInfoMapperTest 13 / GroupOrderStrategyTest 10 = 100 全绿` -- 新增治理范式 case (字典+enum 不一致 / null 透传 / 4 种入参兼容性) 共 13 个 - ---- - -## 六、关联 - -- 前端 BUG 通知: `09_frontend_notice_admin_topic-filter-dup-request.md` (同日新建) -- 历史前端 BUG 通知: `07_frontend_notice_topic-filter-empty.md` (本日 DevTools 新证据已纠正其根因推断) -- 单房差功能: 完全解耦, PR #1900 / #1901 / #1904 不受影响 (治理过程中误删已回滚) diff --git a/changelogs/2026-05/11_feat_admin_itinerary-mileage-anomaly-warnings.md b/changelogs/2026-05/11_feat_admin_itinerary-mileage-anomaly-warnings.md deleted file mode 100644 index 9d6a505..0000000 --- a/changelogs/2026-05/11_feat_admin_itinerary-mileage-anomaly-warnings.md +++ /dev/null @@ -1,149 +0,0 @@ -# admin/product-v2: 行程编辑详情新增里程异常 warnings 字段 + 建议前端 POI 搜索控件改进 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #1938 -> **Issue**: #1937 -> **日期**: 2026-05-11 -> **影响范围**: 管理端产品编辑(step2 行程编排)详情响应; POI 搜索控件(可选改进) - ---- - -## ⚠️ 关键变化 - -后端在产品编辑详情响应里**新增了一个 `mileageWarnings: List<String>` 字段**(按天), 用于在运营选错 POI 时弹红旗提示。前端可在编辑页该天显示警告徽章。 - -**同时强烈建议(可选)**:POI 搜索控件 UX 优化, 防止运营选错同名异地 POI。已发生事故见下文背景。 - ---- - -## 一、背景 - -2026-05-11 发现产品《一次走透呼伦贝尔的旷野心脏》DAY 3 `daily_mileage = 475.2 km`, 客户用高德地图手测同样 5 点路线 = **275.0 公里**, 差 **+200 km(+73%)**。 - -### 根因(实证) - -运营在产品 step2 编辑器搜"恩和", 选了高德返回的 POI `poiId=B0LALCK6P1`, 该 POI 名字叫"恩和"但**实际坐标在陈巴尔虎旗宝日希勒镇** `(lat=49.279092, lng=119.616988)`, 跟真正"额尔古纳市恩和俄罗斯民族乡" `(lat≈50.83)` 偏南 **167 km**。后端调高德 API 算驾车里程, 从骑马场(50.83°) → 错位"恩和"(49.28°)单段就多算 200 km。 - -### 平台 F 维度扫描 - -正式服全平台扫描坐标落在 `(lat 49.27-49.30, lng 119.60-119.65)` 范围 → 共 **6 条记录, 涉及 4 个产品**: - -| 产品 | 状态 | 命中 | -|------|------|------| -| 2053003990289129474 一次走透呼伦贝尔的旷野心脏 | PUBLISHED | DAY3 dismissal + DAY4 gather | -| 2052985893312008193 呼伦贝尔5天4晚自由行 | COMPLETED | DAY2 dismissal + DAY3 gather | -| 2052926308213891073 燕6天5晚私人订制 | COMPLETED | DAY3 gather | -| 2052984406884225025 草原慢旅行 | DRAFT | DAY3 dismissal + DAY4 gather | - -已通过 SQL `JSON_SET` 修正全部 6 条 location 到 `(50.828414, 119.912452)`, 修复后 F 扫描 = 0 行。 - -### 数据库 schema 差异 - -- **正式服旧 schema**: `product_itinerary_day.gather_place / dismissal_place` 是 JSON, 含 `location.lat/lng` -- **测试服新 schema**: 同字段已升级为**行政区粒度**(`name / level / adcode / fullPath / levelName`), 不嵌套坐标; 途经点搬到新表 `product_route_point` -- 测试服 F 维度扫描 0 命中, 新 schema 已天然阻断此 bug 模式 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 管理端获取产品详情(含 step2 行程) | GET | `/admin/product/item/{id}` | 响应新增字段 | 每个 `days[]` 元素新增 `mileageWarnings: List<String>`, 默认空数组 | - ---- - -## 三、接口详情 - -### 1. 管理端获取产品详情 `GET /admin/product/item/{id}` - -**VO**: `ProductDetailRespVO.days[] -> ItineraryDayRespVO` - -#### 出参新增字段 - -| 字段 | 类型 | 说明 | 默认 | -|------|------|------|------| -| `days[i].mileageWarnings` | `List<String>` | 该天里程异常 warning 列表, 空数组表示正常。每条 warning 是给运营看的中文短句, 建议在编辑页该天显示红色感叹号 / 黄色徽章, 鼠标悬停展示具体内容 | `[]` | - -#### 三条 warning 规则(后端自动检测) - -| 规则 | 触发条件 | warning 文案样例 | -|------|----------|-----------------| -| 单段直线超长 | 同一天内相邻两节点直线距离 > 100km | `DAY3 第4段 直线距离 173.6km, 跨城市级跳跃, 可能 POI 坐标错位` | -| 驾车/直线比异常 | 某段 driving / linear > 3.5 (正常 1.4~2.5) | `DAY3 第4段 驾车/直线比 4.2, 正常 1.4~2.5, 强烈疑似 POI 错位或绕远` | -| 全天里程过大 | `dailyMileage > 600km` | `DAY3 全天里程 720km 异常大` | - -不阻塞保存, 不持久化, 每次 GET 实时计算。资源服务异常时静默退化为空数组。 - -#### 响应示例 - -```json -{ - "code": 0, - "data": { - "id": "2053003990289129474", - "name": "一次走透呼伦贝尔的旷野心脏", - "days": [ - { - "dayNumber": 3, - "dailyMileage": 275.0, - "dailyDuration": 210, - "mileageWarnings": [] - }, - { - "dayNumber": 4, - "dailyMileage": null, - "dailyDuration": null, - "mileageWarnings": [ - "DAY4 第2段 直线距离 145.2km, 跨城市级跳跃, 可能 POI 坐标错位" - ] - } - ] - } -} -``` - ---- - -## 四、前端建议改造(强烈推荐, 防再发) - -### A. step2 编辑页展示 mileageWarnings - -每天的里程展示位旁加一个图标: -- `mileageWarnings.length === 0` → 不显示 / 显示绿色 ✓ -- `mileageWarnings.length > 0` → 显示红色 ⚠️, 鼠标 hover 展开 warning 列表 - -### B. POI 搜索控件 UX 改进(根因防御) - -当前组件:运营搜"恩和", 高德 API 返回多个同名 POI, 用户只看到 name 选错。 - -建议改造: -1. **搜索结果项显示完整地址**:`name | district + township`, 例如: - - `恩和 | 呼伦贝尔市 / 陈巴尔虎旗 / 宝日希勒镇` ← 错的恩和 - - `恩和 | 呼伦贝尔市 / 额尔古纳市 / 恩和俄罗斯族民族乡` ← 对的恩和 -2. **按产品 cityCode 限定搜索范围**:产品基础信息已存 city/adcode, POI 搜索时 region 参数限定本市, 同名异地 POI 自然过滤 -3. **选完 POI 后展示地图小预览**:`<map markers={[poi.location]}>`, 让运营肉眼校核位置对不对 - -不强求一次做完, B.1 最便宜也最有效。 - ---- - -## 五、不需要前端做的事 - -- 后端已修 6 条已发现错坐标记录(SQL JSON_SET), 前端不需要清缓存或重建索引 -- `daily_mileage` NULL 的天 = 等运营在后台对该产品 step2 点一次「保存」让 `ItineraryAutoCalculator` 走高德重算, 前端展示 NULL 即可 - ---- - -## 六、回归风险 - -- `ProductDetailAggregator.fillItinerary` 多一次 Feign 调用资源服务取节点坐标, 已 try/catch 退化, 资源服务挂掉不影响详情主流程 -- 阈值 100km 对跨地级市出发产品会触发 warning(例如"鄂尔多斯出发去敦煌"), 这是 feature 不是 bug, 让运营核对一下确认 POI 没选错就好 - ---- - -## 七、相关 PR / Issue - -- PR #1938 后端实现 -- Issue #1937 工单 -- 上下文相关 PR: 6 条错坐标 SQL 修复在工单 #1937 评论里记录 diff --git a/changelogs/2026-05/11_fix_admin_product-name-extend-to-255.md b/changelogs/2026-05/11_fix_admin_product-name-extend-to-255.md deleted file mode 100644 index f552afd..0000000 --- a/changelogs/2026-05/11_fix_admin_product-name-extend-to-255.md +++ /dev/null @@ -1,39 +0,0 @@ -# fix(product-v2): 产品名称最大长度 30 → 255 - -**日期**: 2026-05-11 -**PR**: #1940(合 dev,squash sha `b96d158f`) -**模块**: product-v2 / 后台产品编辑 -**关联工单**: 无 - ---- - -## 改动 - -| 项 | Before | After | -|----|--------|-------| -| `ProductSaveReqVO.name` `@Size(max)` | 30 | 255 | -| `ProductBasicSaveReqVO.name` `@Size(max)` | 30 | 255 | -| 校验文案 `message` / `@ApiModelProperty` | "≤30字" | "≤255字" | -| DB `product.name` 列长 | `varchar(60)` | `varchar(255)` | -| DB COMMENT | `'产品名称(≤30字)'` | `'产品名称(≤255字)'` | -| Flyway | — | `V20260511_001__product_name_extend_to_255.sql` | -| `schema.sql` | 同步更新 | 同步更新 | - ---- - -## 背景 - -用户编辑产品时把广告语合进名称后超 30 字被卡(实测 31/30 报错)。市场带广告语的长名称越来越多,扩到 255 一劳永逸。 - ---- - -## 部署 - -- 测试服:Deploy Panel 触发 product-v2 重启,Flyway 自动跑 ALTER(MySQL 8 instant alter,秒级) -- 正式服:同步部署(用户已要求) - ---- - -## 前端联动 - -前端 hl-admin 产品编辑页 `maxlength=30` 和「31/30」计数器需 mmg 同步改 255,详见 `11_frontend_notice_admin_product-name-maxlength-30-to-255.md`。 diff --git a/changelogs/2026-05/11_fix_admin_product-share-followup-2-fixes.md b/changelogs/2026-05/11_fix_admin_product-share-followup-2-fixes.md deleted file mode 100644 index d41bb23..0000000 --- a/changelogs/2026-05/11_fix_admin_product-share-followup-2-fixes.md +++ /dev/null @@ -1,90 +0,0 @@ -# 后端 fix 通知 — 产品分享 2 项 follow-up 修复(企微名兜底 + CUSTOMIZER 加分享权限) - -**日期**: 2026-05-11 -**类型**: 后端修复 (PR #1919 内部 follow-up) -**模块**: 产品管理 → 产品列表 → 分享产品(ShareModal) -**通知**: @mmg -**前端是否需改动**: **否**(响应 schema / 字段名零变化,后端兜底) -**严重性**: P1(用户两次反馈,核心功能不可用) - ---- - -## ⚠️ 关键变化 - -**PR #1933(commit `0a817914`)** 已合 dev + 测试服部署 + QA 双验证通过。修了 PR #1919 上线后用户实测发现的 2 个 P1 问题: - -1. **`customizers` 接口 enterpriseWechatName 后端兜底回落 username** - - 修前:未绑企微的 admin → `enterpriseWechatName: null` → 前端下拉显示空白行 - - 修后:未绑企微 / 脏数据 → `enterpriseWechatName: <username>` → 下拉显示登录名兜底 - - 已绑企微的 admin 行为不变,仍返中文真名 - -2. **CUSTOMIZER 角色加 PRODUCT_SHARE 权限** - - 修前:CUSTOMIZER 角色 admin 调 `POST /admin/product/item/{id}/share` → `code:403 无产品分享权限 (PRODUCT_SHARE)` - - 修后:Flyway `V20260511_001` 给 CUSTOMIZER 角色加 PRODUCT_SHARE 权限,定制师之间互相分享产品的业务场景可用 - - 老板自己也是定制师身份,所以这是核心需求 - ---- - -## 前端 mmg 完全无需改动 - -ShareModal.vue 当前直接用 `o.enterpriseWechatName` 作为 label,后端字段语义已经从"企微真名(可空)"变成"展示名(企微名/未绑回落 username)",前端零改动即可正常显示。 - -如果你之前考虑过前端加 `fallback chain`(`o.enterpriseWechatName || o.username`),**现在不需要了**,后端兜底已经覆盖。 - ---- - -## ✅ 测试服验证(2026-05-11 10:24 部署) - -### enterpriseWechatName 字段实测(20 条 customizer 抽 5 条) - -| adminId | username | 绑企微 | 接口返 enterpriseWechatName | ✅ | -|---|---|---|---|---| -| 1001 | admin | 无 | `"admin"` | ✅ 兜底 username | -| 1002 | test_admin | 脏数据 | `"test_admin"` | ✅ 兜底 username | -| 2021059720172838914 | wx | 已绑 | `"王骁"` | ✅ 中文真名 | -| 2027579942221352962 | mmg | 已绑 | `"米明光"` | ✅ 中文真名 | -| 2033349910786715649 | lixiaosong | 已绑 | `"小松"` | ✅ 中文真名 | - -**全列表 20 条 customizer,`enterpriseWechatName` 字段 0 个 null。** - -### CUSTOMIZER 调 share 接口实测 - -用 lixiaosong 单 CUSTOMIZER 角色 token 调: -```bash -POST /admin/product/item/2044704111294672897/share body {"targetAdminId":1002} -→ {"code":200,"data":{"newProductId":"2053662735618506754","newProductNo":"C260511001","newProductName":"嗨冰雪3.0南线（6天5晚）（来自lixiaosong的分享）"}} -``` - -### Flyway 落库 - -`flyway_schema_history`:`version=20260511.001` success=1,CUSTOMIZER 角色已绑 PRODUCT_SHARE 权限。 - ---- - -## 不影响范围 - -- 接口路径 / Method / Request / Response schema 零变化 -- 其他持 PRODUCT_SHARE 权限的角色(SUPER_ADMIN / ADMIN)行为不变 -- 没绑企微的 admin 的其他字段(`username` / `avatar`)也不变,前端可继续按需用 - ---- - -## 相关 PR - -| PR | 说明 | 状态 | -|----|------|------| -| #1919 | 实现 admin 分享产品功能(Closes #1918) | ✅ 已合 | -| #1924 | 修复 PR #1919 暴露的 2 个回归(中文括号 + fee_item 全量) | ✅ 已合 + 部署 | -| #1930 | customizers 接口加 enterpriseWechatName 企微姓名字段 | ✅ 已合 + 部署 | -| **#1933** | **本通知**:enterpriseWechatName 兜底 username + CUSTOMIZER 加 PRODUCT_SHARE 权限 | ✅ 已合 + 部署 + QA 通过 | - ---- - -## 历史 changelog 关系 - -- `09_feat_admin_customizers-add-enterprise-wechat-name.md`:首次提到 fallback 建议 — **本通知更新**:后端已兜底,前端无需 fallback -- `09_frontend_notice_admin_share-modal-show-enterprise-wechat-name-P0.md`(P0 紧急,建议 `label = o.enterpriseWechatName`)— **仍然有效**:label 字段名是对的,后端已兜底没值时回落 username - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/11_fix_admin_product-share-role-based-auth.md b/changelogs/2026-05/11_fix_admin_product-share-role-based-auth.md deleted file mode 100644 index 3c4feed..0000000 --- a/changelogs/2026-05/11_fix_admin_product-share-role-based-auth.md +++ /dev/null @@ -1,81 +0,0 @@ -# 后端 fix 通知 — 产品分享鉴权改为多角色 union 查 CUSTOMIZER - -**日期**: 2026-05-11 -**类型**: 后端鉴权逻辑修复 (PR #1919 内部 follow-up) -**模块**: 产品管理 → 产品列表 → 分享产品 -**通知**: @mmg -**前端是否需改动**: **否**(接口契约零变化) -**严重性**: P0(用户 3 次反馈,核心功能不可用) - ---- - -## ⚠️ 关键变化 - -PR #1919 上线后用户实测「自己作为定制师角色 → 点分享 → 后端返 403 无产品分享权限」。 - -**PR #1934(commit `e6cc3d73`)** 已合 dev + 测试服已部署 + QA 双正例通过。 - -### 根因 -- `PermissionService.hasPermission` 只查 `admin.currentRoleId` **单角色** + Redis 24h 缓存 -- admin 可挂多角色,实测 wx 持 8 个角色,但旧逻辑只看 currentRoleId 单角色查权限点 -- 与「持 CUSTOMIZER 角色就能分享」的业务直觉不符 - -### 修复 -- `ProductShareService.share` 第一步从 `hasPermission(PRODUCT_SHARE)` 改为 - **`AdminBasicDTO.roleKeys 含 CUSTOMIZER`**(union 多角色) -- 与第二步 `targetAdmin.roleKeys` 校验**同一套数据源**,语义统一 -- 删 `PERM_PRODUCT_SHARE` 常量(不再消费该权限点) - -### 业务规则 -**有 CUSTOMIZER 角色 → 可分享**(union 多角色判断)。 -不需要再单独绑定 PRODUCT_SHARE 权限点 — 历史 V_003 / V_001 的权限绑定保留不删,只是不再被消费。 - ---- - -## 接口契约零变化 - -`POST /admin/product/item/{id}/share` 入参 / 响应字段 / 错误码语义 0 改动,前端无需任何变更。 - -### 错误文案微调 - -| 旧 | 新 | -|----|-----| -| `无产品分享权限 (PRODUCT_SHARE)` | `无产品分享权限, 仅持定制师角色 (CUSTOMIZER) 可分享产品` | - -如果前端 toast 有匹配旧文案的 if-else(不太可能),需要同步调整。直接显示 `message` 字段无需改。 - ---- - -## ✅ 测试服已验证(2026-05-11 10:36+) - -| 测试主体 | 角色 union | 接口 | 结果 | -|---|---|---|---| -| **wx**(adminId=2021059720172838914) | `ADMIN, CUSTOMER_SERVICE, CUSTOMIZER, MATERIAL_ADMIN, OPERATOR, ROOM_MANAGER, SUPER_ADMIN, VEHICLE_MANAGER` (8 角色) | `POST /admin/product/item/2045018534152478721/share` `{"targetAdminId":1002}` | 200, newProductId=2053665899663024129, "游牧的森林·南线经典（来自wx的分享）" | -| **lixiaosong**(adminId=2033349910786715649) | `CUSTOMIZER` (单角色) | `POST /admin/product/item/2044704111294672897/share` `{"targetAdminId":1002}` | 200, newProductId=2053665998405316609, "嗨冰雪3.0南线（6天5晚）（来自lixiaosong的分享）" | - -两个典型 admin 都成功,产品名中文全角括号正确,无回归。 - ---- - -## 不影响范围 - -- 接口路径 / Method / Request / Response schema 零变化 -- 第二步 targetAdmin 校验(roleKeys 含 CUSTOMIZER)逻辑不变,继续 union 多角色 -- `admin_permission` 表 PRODUCT_SHARE 权限点 + role binding 不删,历史兼容 -- 其他业务模块(如订单分配定制师 / 工单等)未受影响 - ---- - -## 相关 PR - -| PR | 说明 | 状态 | -|----|------|------| -| #1919 | 实现 admin 分享产品功能(Closes #1918) | ✅ 已合 | -| #1924 | 修 #1919 的中文括号 + fee_item 丢数据 | ✅ 已合 + 部署 | -| #1930 | customizers 接口加 enterpriseWechatName | ✅ 已合 + 部署 | -| #1933 | customizers 字段兜底 username + CUSTOMIZER 加 PRODUCT_SHARE 权限 | ✅ 已合 + 部署(但因单 currentRoleId + Redis 缓存原因实际未生效) | -| **#1934** | **本通知**:share 鉴权改为多角色 union 查 CUSTOMIZER(根本性修复) | ✅ 已合 + 部署 + QA 通过 | - ---- - -**联系人**: wx diff --git a/changelogs/2026-05/11_followup_admin_poi-search-city-source-clarification.md b/changelogs/2026-05/11_followup_admin_poi-search-city-source-clarification.md deleted file mode 100644 index 9b22fc3..0000000 --- a/changelogs/2026-05/11_followup_admin_poi-search-city-source-clarification.md +++ /dev/null @@ -1,172 +0,0 @@ -# admin/product-v2: POI 搜索按城市限定 — 城市字段已在响应里, 在 `itinerary[0].gatherPlace` - -> **服务**: hl-product-service-v2 (端口 8083) -> **关联**: 11_feat_admin_itinerary-mileage-anomaly-warnings.md 的第四节"前端建议改造 B" -> **日期**: 2026-05-11 -> **影响范围**: 管理端产品编辑(step2) POI 搜索控件 — 仅前端改造, 后端 0 改动 - ---- - -## ⚠️ 关键变化(澄清前端误判) - -前端反馈"产品详情没返回城市, 没法按 cityCode 限定 POI 搜索"。**这个判断不准确**: - -- 顶层 `ProductDetailRespVO` 确实没有 `city/cityCode` 字段 -- 但 `itinerary[i].gatherPlace` / `itinerary[i].dismissalPlace` 这两个 JSON 字段 **早就含完整城市/行政区信息**(后端从高德 POI 选点时就一并存了 cityName / adcode / districtName / provinceName / fullPath / township) - -后端**不需要新加字段**, 前端直接读 `itinerary[0].gatherPlace.cityName / adcode` 即可。 - ---- - -## 一、字段位置实证 - -正式服 GET `/admin/product/item/{id}` 实测响应(产品 2053003990289129474、2052985893312008193、2052926308213891073 三例一致): - -```json -{ - "data": { - "itinerary": [ - { - "dayNumber": 1, - "gatherPlace": { - "name": "云上呼伦贝尔", - "poiId": "B0FFL...", - "adcode": "150702", - "address": "呼伦贝尔东山国际机场", - "cityName": "呼伦贝尔市", - "fullPath": "内蒙古自治区/呼伦贝尔市/海拉尔区/胜利街道", - "location": { "lng": 119.809336, "lat": 49.5568 }, - "towncode": "150702010000", - "township": "胜利街道", - "districtName": "海拉尔区", - "provinceName": "内蒙古自治区" - }, - "dismissalPlace": { /* 同样结构 */ } - } - ] - } -} -``` - -`dismissalPlace` 字段结构同 `gatherPlace`。 - ---- - -## 二、前端实现建议 - -### 1. 城市数据源(优先级) - -```typescript -function getProductCity(detail) { - const firstDay = detail.itinerary?.[0]; - const gather = firstDay?.gatherPlace; - // 高德 POI 搜索 region 参数支持 adcode (推荐) 或 cityname - return { - cityName: gather?.cityName, - adcode: gather?.adcode, - fullPath: gather?.fullPath, - }; -} -``` - -### 2. 高德 POI 搜索调用 - -```typescript -// 高德 web 服务 v3 关键字搜索: region + citylimit=true -const params = { - key: AMAP_KEY, - keywords: userInput, - region: productCity.adcode, // adcode 比 cityname 更精确 - city_limit: true, // 强制只在 region 内搜 - output: 'json', -}; -``` - -### 3. POI 搜索结果显示完整地址(根因防御) - -每个 POI 结果项除了 `name` 之外, 把 `district + township` 也显示出来: - -``` -[结果项] - 恩和 ← name - 呼伦贝尔市 / 额尔古纳市 / 恩和俄罗斯族民族乡 ← district + township -``` - -让运营肉眼区分同名异地 POI(例如"恩和"在宝日希勒镇 vs 恩和俄罗斯族民族乡)。 - ---- - -## 三、边界场景处理 - -### Case A: DAY 1 集合地还没填(新建产品首次进 step2) - -- 此时 `itinerary[0].gatherPlace` 是 `null` -- 第一个 POI 选择无 city 可限定 → **降级为全国搜索**, 选完后 setState 本地缓存 `cityName/adcode` -- 后续所有 POI 选择(DAY 1 节点 / DAY 1 解散 / DAY 2+...)都拿本地缓存做 region 限定 - -```typescript -const [productCity, setProductCity] = useState(null); -// 编辑已有产品时初始化: -useEffect(() => { - if (detail.itinerary?.[0]?.gatherPlace?.cityName) { - setProductCity(getProductCity(detail)); - } -}, [detail]); -// 用户选完 DAY 1 集合地后: -function onGatherPlacePicked(poi) { - if (!productCity) { - setProductCity({ cityName: poi.cityName, adcode: poi.adcode }); - } - // ... 落库 -} -``` - -### Case B: 跨城市产品(如内蒙呼伦贝尔 + 蒙古国边境) - -- 取 DAY 1 gather 即可, 这是产品的"主城市" -- 跨城市产品本身在编辑时, 跨城段的 POI 会被 detector 的 `单段 > 100km` warning 命中, 让运营人工确认, 不依赖 region 限定 - -### Case C: gatherPlace 是老行政区格式(无 cityName, 只有 adcode + fullPath) - -- 测试服新 schema 是行政区粒度, 字段更少 -- 兜底: `cityName = fullPath?.split('/')?.[1]`(第 1 段省, 第 2 段市) -- 或: 拿 adcode 前 4 位 → 高德反查城市 - -```typescript -function extractCity(place) { - if (!place) return null; - if (place.cityName && place.adcode) return { cityName: place.cityName, adcode: place.adcode }; - if (place.fullPath) { - const parts = place.fullPath.split('/'); - return { cityName: parts[1], adcode: place.adcode }; - } - return null; -} -``` - ---- - -## 四、后端不需要做的事 - -明确不做(避免误改): - -- ❌ 不在 `ProductDetailRespVO` 顶层加 `cityName/adcode` 冗余字段(数据已在 itinerary 里, 加冗余字段反而双源更易错乱) -- ❌ 不加 `product.city` 数据库字段(产品级城市当前业务无明确归属, "产品起点 = itinerary[0].gather" 这个隐式约定足够用) -- ❌ 不抽 `routeInfo.city` 字段(routeInfo VO 当前不含 city, 改它需要改 Entity + VO + 保存逻辑, 不值) - ---- - -## 五、Test plan(给 mmg) - -- [ ] 编辑产品 `2053003990289129474`, 在 DAY 4 集合地 POI 搜索输入"恩和", 验证只返回额尔古纳市恩和(50.83°), 不返回宝日希勒错点(49.28°) -- [ ] 新建产品, DAY 1 集合地选呼伦贝尔机场后, DAY 2/3/4 节点 POI 搜索自动限定到呼伦贝尔市 -- [ ] POI 结果项显示 `district + township`, 让运营肉眼区分同名 POI -- [ ] 跨城市产品(如海拉尔出发去阿尔山)能正常编辑, 跨城段触发 detector warning 但不阻塞保存 - ---- - -## 六、参考 - -- 上一份 changelog: `11_feat_admin_itinerary-mileage-anomaly-warnings.md` 第四节有 POI 搜索改造的高层建议 -- 实证脚本(只读 dump 字段): `D:\work2\HL\.tmp\prod_smoke_pr1939_mileage_warnings.py` (修改版可复用) -- 高德 web 服务文档: https://lbs.amap.com/api/webservice/guide/api/search (POI 搜索, region + citylimit 参数) diff --git a/changelogs/2026-05/11_frontend_notice_admin_product-line-list-show-creator-name.md b/changelogs/2026-05/11_frontend_notice_admin_product-line-list-show-creator-name.md deleted file mode 100644 index 3635381..0000000 --- a/changelogs/2026-05/11_frontend_notice_admin_product-line-list-show-creator-name.md +++ /dev/null @@ -1,157 +0,0 @@ -# 管理端主题列表: 卡片新增「创建人姓名」字段 createdByName（企微昵称优先 fallback 用户名） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: [#1944](https://git.1814.love:8443/wx/HL/pulls/1944) — 已合并到 main -> **Issue**: [#1943](https://git.1814.love:8443/wx/HL/issues/1943) — 已关闭 -> **日期**: 2026-05-11 -> **影响范围**: 管理后台「产品管理 → 主题列表」(/product/line) 卡片 -> **状态**: ✅ **已上线正式服**（2026-05-11 18:06，release PR [#1945](https://git.1814.love:8443/wx/HL/pulls/1945)，image_tag `9ffad0ee`） - ---- - -## ⚠️ 关键变化（覆盖本日早些时候那条 heads-up） - -主题列表卡片每张多一个字段 **`createdByName`**（String，可能为 null）。 - -**显示规则（后端已实现）**： -- 创建人 admin_user 绑定了企业微信 → 返回**企业微信昵称** -- 未绑企微 → 返回 **admin_user.username**（用户名兜底） -- 极端情况（user-service 降级 / admin 已删）→ 返回 null - -前端**无需自己 fallback**，后端已聚合好，直接展示 `createdByName` 即可。 - ---- - -## 一、测试服已验证 (硬性凭证) - -``` -GET https://api.test.1814.love:9443/admin/product/line/list?pageNo=1&pageSize=5 -Authorization: Bearer <admin 真 token> - -HTTP 200 -data.records[*].createdByName 字段存在性: 5/5 条全部都有 ✓ -非 null 命中: 5/5 条 (createdBy 有值的全部回填) ✓ - -实测样本: - lineId=2053279457388494849 createdBy=2021059720172838914 createdByName='王骁' - lineId=2053278451187535873 createdBy=2021059720172838914 createdByName='王骁' - lineId=2053060320829599746 createdBy=1001 createdByName='admin' (username fallback) - lineId=2053060194102898690 createdBy=1002 createdByName='test_admin' (username fallback) - lineId=2049467101390819329 createdBy=2033349910786715649 createdByName='小松' (企微昵称) -``` - ---- - -## 二、背景 - -超级管理员/运营组长视角下，主题列表卡片看不出谁建的，特别是私人定制类主题（不同销售各自开），需要快速识别 owner。 - ---- - -## 三、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 主题列表 | GET | `/admin/product/line/list` | 响应体新增字段 | 每条多 `createdByName` | -| 2 | 主题详情 | GET | `/admin/product/line/{lineId}` | 响应体新增字段 | 多 `createdByName` | - -后端 0 个 break、0 个删除、0 个语义变化。仅追加字段。 - ---- - -## 四、接口详情 - -### 1. 主题列表 `GET /admin/product/line/list` - -**VO**: `ProductLineRespVO` - -#### 出参（仅列出新增/相关字段） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `lineId` | Long | 主题 ID（已有） | -| `name` | String | 主题名（已有） | -| `createdBy` | Long | 创建人 admin_id（已有，前端无需用） | -| **`createdByName`** | **String** | **🆕 创建人显示名（企微昵称优先 fallback username，可能 null）** | -| `createTime` | DateTime | 创建时间（已有） | -| ... | ... | 其他字段不变 | - -#### 响应示例 - -```json -{ - "code": 200, - "message": "成功", - "success": true, - "data": { - "records": [ - { - "lineId": "2053279457388494849", - "name": "私人订制", - "createdBy": "2021059720172838914", - "createdByName": "王骁", - "createTime": "2026-05-10 09:02:25", - "...其他字段": "..." - } - ] - } -} -``` - -### 2. 主题详情 `GET /admin/product/line/{lineId}` - -同样追加 `createdByName` 字段，结构与列表一致。 - ---- - -## 五、前端实现要点 - -### UI 位置（建议） - -主题卡片在「创建时间」一行旁边或上面加一行「创建人: xxx」，排版方式由前端拍板。 - -### Null 处理 - -- `createdByName === null` → 显示「-」或不显示该行（不要显示「null」字样） -- 不要尝试自己用 createdBy ID 调 user-service 兜底 —— 后端已经处理过，再调也是相同结果 - -### 主题详情页 - -如果详情页也想展示创建人，同样读 `createdByName` 字段。 - ---- - -## 六、不影响范围 - -- ✅ MP 端任何接口：0 改动（C 端不需要看创建人） -- ✅ 主题创建/编辑/删除接口：0 改动（写入侧不受影响） -- ✅ 现有筛选条件（关键字/状态/主题类型）：0 改动 -- ✅ 历史 27 条主题数据：无需迁移（createdBy 已写入，靠 enrich 实时取，老数据如 createdBy 已删则返 null） - ---- - -## 七、降级/边界 - -- user-service 降级（Feign 失败）→ 后端 catch 异常，所有 createdByName 返 null，列表照常返回，**不阻断页面** -- batchGetAdminInfo 返空（admin 已删）→ 该条 createdByName = null -- admin_user 未绑企微 → wechatName 为 null，自动 fallback username - ---- - -## 八、相关历史 - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| **#1944** | #1943 | 主题列表/详情新增 createdByName | ✅ **本次**（已合 dev + 测试服已验证） | - -参考类似实现：产品列表 `ProductQueryService.enrichCreatedByName():243-267`（已上线很久，前端已使用 `createdByName` 字段）。 - ---- - -## 九、相关文档 - -- 关联 Issue: [wx/HL#1943](https://git.1814.love:8443/wx/HL/issues/1943) -- 关联 PR: [wx/HL#1944](https://git.1814.love:8443/wx/HL/pulls/1944) -- Feign 接口: `hl-common/hl-common-feign/.../UserFeignClient.java:36-37` -- AdminBasicDTO: `hl-common/hl-common-core/.../AdminBasicDTO.java:17,25-26` -- 仿写模板: `hl-product-service-v2/.../ProductQueryService.java:243-267` diff --git a/changelogs/2026-05/11_frontend_notice_admin_product-name-maxlength-30-to-255.md b/changelogs/2026-05/11_frontend_notice_admin_product-name-maxlength-30-to-255.md deleted file mode 100644 index 8e95ea4..0000000 --- a/changelogs/2026-05/11_frontend_notice_admin_product-name-maxlength-30-to-255.md +++ /dev/null @@ -1,61 +0,0 @@ -# 前端联动通知 — 产品名称 maxlength 30 → 255 - -**日期**: 2026-05-11 -**类型**: 前端字段限制调整(配合后端扩长度) -**模块**: 产品管理 → 产品编辑页 / 新建产品(hl-admin) -**通知**: @mmg -**前端改动**: input maxlength + 字符计数器上限 - ---- - -## 背景 - -用户反馈:把广告语合进产品名后超 30 字被卡(截图实测 31/30 报错)。后端已扩到 255,前端 input 的 `maxlength=30` 和「31/30」计数器上限也要同步改 255。 - ---- - -## 后端改动(已上 dev,PR #1940 已合) - -| 项 | Before | After | -|----|--------|-------| -| `ProductSaveReqVO.name` | `@Size(max=30)` | `@Size(max=255)` | -| `ProductBasicSaveReqVO.name` | `@Size(max=30)` | `@Size(max=255)` | -| 校验失败 message | "产品名称不能超过30个字符" | "产品名称不能超过255个字符" | -| DB `product.name` | `varchar(60)` | `varchar(255)`(Flyway `V20260511_001`) | - -后端 message 文案随响应自动更新,前端不需要改文案本身,只要改 input 上限。 - ---- - -## 前端要改的地方 - -产品编辑页(基础信息步骤)的产品名称输入框 + 字符计数器: - -```vue -<!-- before --> -<el-input v-model="form.name" :maxlength="30" show-word-limit /> - -<!-- after --> -<el-input v-model="form.name" :maxlength="255" show-word-limit /> -``` - -如果是封装组件或 schema 配置,改对应的 max/maxlength 字段即可。建议全局搜 `maxlength.*30` 在产品编辑/新建相关组件中确认无遗漏。 - ---- - -## 验收 - -1. 后端**正式服**已部署(2026-05-11 18:06, release PR [#1945](https://git.1814.love:8443/wx/HL/pulls/1945), image_tag `9ffad0ee`, Flyway V20260511_001 已自动跑 ALTER) -2. 前端 `pnpm build` + Deploy Panel 前端部署 → 硬刷 -3. 产品编辑页输入 100 字符产品名 → 不再红字报错,可提交保存 ✅ -4. 输入 256 字符 → 前端 input 自身截断到 255(maxlength 控制) - ---- - -## 风险 - -- 老产品名都 ≤30,扩 maxlength 不影响存量 -- DB ALTER 在线 DDL,MySQL 8 instant alter 秒级 -- 无关联工单 - -**联系人**: wx diff --git a/changelogs/2026-05/11_frontend_notice_admin_product-step5-equipment-template-quick-fill.md b/changelogs/2026-05/11_frontend_notice_admin_product-step5-equipment-template-quick-fill.md deleted file mode 100644 index cf52e82..0000000 --- a/changelogs/2026-05/11_frontend_notice_admin_product-step5-equipment-template-quick-fill.md +++ /dev/null @@ -1,106 +0,0 @@ -# 管理端产品编辑 Step5: 装备建议增加「从模板选择」快速填充按钮（前端任务，后端已就绪） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: 无（纯前端，后端 0 改动） -> **Issue**: 无（前端 BUG/feature 不建工单） -> **日期**: 2026-05-11 -> **影响范围**: 管理后台产品（版本）编辑 → Step3 预订须知 → 装备建议区域 - ---- - -## ⚠️ 关键变化 - -**用户反馈**：装备建议组合模板已建好，但产品（版本）编辑页 Step3 「装备建议」只能逐条手动加，没法用模板。 - -**方案定调（用户拍板）**： -- 装备组合模板（EquipmentTemplate）整体仍绑定在「产品线（主题）」层 —— 不动 PR #1782 的设计 -- 模板对产品版本只是「装备池」：产品版本编辑时点按钮 → 拉模板 → 把装备项填入下方 `equipmentList` 表单 → 用户可继续手动增删改 → 保存的是装备项**快照**，与模板脱钩 -- 后端 0 改动，纯前端做"快速填充"按钮 - -## 一、背景 - -PR #1768 → #1782 历史： -- #1768: 装备组合模板首次落地，绑在产品版本（product_supplement）层 -- #1777 / #1782: 用户反馈"应该绑在主题层"，已迁移 templateId 到 product_line 层 -- 但 PR #1782 配套的前端改造未完成（主题编辑页没加下拉、产品版本 Step5 还是手动逐条加） - -本次 5/11 用户重新明确： -- 模板**整体绑定**仍在主题层（保留 #1782） -- 产品版本编辑时的「装备建议」需要能**从模板快速填充**到表单（不传 templateId 给后端，前端只是借模板做填充） - -## 二、变更接口清单 - -**后端 0 个新接口、0 个 break**，前端复用以下已存在接口： - -| # | 接口 | 方法 | 路径 | 用途 | -|---|------|------|------|------| -| 1 | 启用模板下拉 | GET | `/admin/equipment-template/enabled` | 获取所有 ENABLED 模板的 (templateId, name, itemCount) | -| 2 | 模板详情 | GET | `/admin/equipment-template/{templateId}` | 拿到模板的 items 数组（用于填充表单） | - -## 三、前端实现要点 - -### UI 位置 - -产品版本编辑页（`/product/edit?id=xxx`）→ 第 3 步「预订须知」→「装备建议」区域： - -当前：仅有「+ 新增装备 (N/20)」一个按钮，逐条手动加。 - -新增：「+ 新增装备」按钮**旁边**或**上方**加一个 `[ 从模板选择 ]` 按钮。 - -### 交互流程 - -1. 点击 `[ 从模板选择 ]` -2. 弹出/下拉 GET `/admin/equipment-template/enabled` 列表（显示模板名 + items 条数） - - 可选 UX：默认高亮"当前主题已绑模板"（前端可在 ProductLineRespVO 取 `equipmentTemplateId`，匹配后置顶/打勾） -3. 用户选中某个模板 → 调 GET `/admin/equipment-template/{templateId}` 拿 items 数组 -4. **填充策略**（前端拍板，建议二选一）： - - **覆盖模式**：清空当前 equipmentList → 填入模板 items（推荐，符合"快速填充"直觉） - - **追加模式**：模板 items 追加到当前 equipmentList 末尾（注意 ≤20 条上限校验） -5. 填充后用户可继续手动增删改单条 -6. 保存时调当前 Step5 保存接口，`equipmentList` 字段照常传（**不要传 templateId 给 ProductSupplementSaveReqVO**，该字段已删除） - -### 与主题绑定模板的关系 - -- 主题（产品线）层的 `equipment_template_id` 字段：**保持不动**，目前 MP 端读取仍以此为主 -- 产品版本「从模板选择」**只是 UI 工具**，不改写主题绑定 -- 保存到 `equipment_list` 后，MP 端渲染优先级：主题模板 items → fallback `equipment_list`（即用户在 Step5 手动维护的项才在主题未绑模板时生效） - -### 模板装备项数据结构 - -GET `/admin/equipment-template/{templateId}` 返回的 `items` 数组结构： - -```json -[ - { "text": "防晒霜 SPF50+", "icon": "sunscreen", "color": "#FFA726" }, - { "text": "长袖防晒衣", "icon": "clothes", "color": null } -] -``` - -**完全兼容** `ProductSupplementSaveReqVO.EquipmentItem`（字段同名 text/icon/color），前端 ES6 直接拷贝即可，无需字段映射。 - -### 校验 - -- 单条 text 1-50 字（后端校验） -- 总条数 ≤20（后端校验，前端填充前先比对若超出需提示） - -## 四、不影响范围 - -- ✅ MP 端装备项展示：不变（主题模板 → fallback equipment_list） -- ✅ 主题（产品线）创建/编辑表单的「装备建议组合」下拉：**仍是 PR #1782 待办的前端任务**，本次不收口 -- ✅ 后端任何接口、任何 VO、任何 DDL：0 改动 -- ✅ 装备组合模板列表/编辑页（`/product/equipment-template`）：不变 -- ✅ 产品保存接口：仍是 `equipmentList` 数组，无新字段 - -## 五、相关历史 - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| #1768 | #1767 | 装备组合模板首版，绑产品版本层 | ⚠️ 字段已迁走 | -| #1782 | #1777 | 字段从 product_supplement 迁到 product_line | ✅ 有效（设计仍是主题层绑） | -| 本次 | - | 产品版本 Step5 加「快速填充」按钮（前端） | ✅ 最新 | - -## 六、相关文档 - -- EquipmentTemplate 模板列表接口：`AdminEquipmentTemplateController:82-97` -- 产品版本 Step5 SaveReq：`ProductSupplementSaveReqVO`（无 templateId 字段，请勿误传） -- MP 渲染优先级：`MpProductDetailAssembler:236-253` diff --git a/changelogs/2026-05/11_release_prod_2026-05-11.md b/changelogs/2026-05/11_release_prod_2026-05-11.md deleted file mode 100644 index 7e531c4..0000000 --- a/changelogs/2026-05/11_release_prod_2026-05-11.md +++ /dev/null @@ -1,30 +0,0 @@ -# 2026-05-11 正式服更新 - -**18:06 上线完成，9 分钟。** - -## 这次改了啥 - -1. **主题列表卡片现在显示创建人姓名** — 企微昵称优先，没绑就显示用户名 -2. **产品名称放宽到 255 字** — 之前 30 字总是被卡（广告语合进去就超），现在够用 -3. 代码评审反馈的几个小修复 -4. 清理了项目根目录一些追踪文件（无业务影响） - -## 部署了哪些 - -- 后端：产品服务、订单服务 -- 前端：hl-ui（mmg 已对齐主题列表创建人样式） -- 数据库：产品名字段自动扩长（Flyway 跑过了） - -## 没动 - -网关、用户、小程序、资源服务 —— 这次没改它们。 - -## 哪些 PR 进了这次发版 - -- [#1944](https://git.1814.love:8443/wx/HL/pulls/1944) 主题列表创建人 -- [#1942](https://git.1814.love:8443/wx/HL/pulls/1942) 第 1 轮 CR 反馈修复 -- [#1941](https://git.1814.love:8443/wx/HL/pulls/1941) 清理根目录追踪文件 -- [#1940](https://git.1814.love:8443/wx/HL/pulls/1940) 产品名 30 → 255 - -Release PR: [#1945](https://git.1814.love:8443/wx/HL/pulls/1945) -正式服镜像版本：`9ffad0ee` diff --git a/changelogs/2026-05/12_feat_admin_node_default_description_from_resource_highlights.md b/changelogs/2026-05/12_feat_admin_node_default_description_from_resource_highlights.md deleted file mode 100644 index 67e3247..0000000 --- a/changelogs/2026-05/12_feat_admin_node_default_description_from_resource_highlights.md +++ /dev/null @@ -1,83 +0,0 @@ -# 后端 feat 通知 — 产品节点选资源时, 资源亮点(highlights)默认带到节点 description - -**日期**: 2026-05-12 -**类型**: 后端新增功能 (PR #2096) -**模块**: 产品「行程编排」节点保存 -**通知**: @mmg -**前端是否需改动**: **不需要** — 默认值后端自动填, 现有编辑器不动即可看到 -**严重性**: P2 - ---- - -## 背景 - -产品「行程编排」选景区/活动/服务做节点时, 之前节点 `description` (卖点/描述) 字段需要人工再写一遍, 即使资源端已经填了亮点。本次复用现有字段做"默认值带过来"。 - -## 字段映射 (全部复用现有字段, 无新加) - -| 端 | 卖点字段 | 图标字段 | -|----|---------|---------| -| 资源 (景区/活动/服务) | `highlights` (已有) | `cover_material_id` (已有) | -| 节点 product_itinerary_node | `description` (已有) | `emojiIcon` (已有 lucide 名) | - -## 新增逻辑 - -节点保存时若满足: -- `node.resourceId` 非空 (选了一个资源) -- `node.description` 为空或未传 (用户没自己写卖点) -- `resource.highlights` 非空 (资源端有亮点) - -→ 自动把 `resource.highlights` 复制到 `node.description`。 - -**用户后续可改, 改后不回写资源** (节点 description 是独立快照, 资源端亮点改了不影响已存在的节点)。 - -**显式传值优先**: 如果前端在请求中显式传了 `description`, 后端不会覆盖。 - -## API 变化 - -### 资源端内部 Feign 接口 - -`GET /internal/mp/resource/batch-details` 返回 `ResourceDetailDTO` **新增 highlights 字段**: -```json -{ - "resourceId": "2029818530992472065", - "resourceType": "SCENIC_SPOT", - "name": "呼籁自有营地", - "description": "呼籁自有营地, 坐落于...", - "highlights": "私密专属、原生态草原、旅拍圣地、BBQ体验", // ← 新增 - "cover": "...", - ... -} -``` - -### 产品节点保存接口 - -`PUT /admin/product/item/{id}/itinerary` 行为变化: -- 节点不传 description + 选了资源 → 后端用资源 highlights 自动填 -- 其他场景行为不变 - -### 产品节点查询接口 - -`GET /admin/product/item/{id}` (admin) + 等 MP 接口 - 字段结构不变。`node.description` 字段可能比之前更常有值(自动带的)。 - ---- - -## 测试服实测 - -部署版本: dev `b02f0ab0` 之后的 PR #2096 commit - -| 场景 | 期望 | 实测 | -|------|------|------| -| 节点不传 description + 选景区(highlights="私密专属、...BBQ体验") | description=资源 highlights | ✅ PASS | -| 节点显式传 description="我自己写的卖点" | description=用户输入, 不被覆盖 | ✅ PASS | -| 资源端 Internal Feign 返回 ResourceDetailDTO | 含 highlights 字段 | ✅ PASS | - ---- - -## 前端 mmg 优化建议 (非必须) - -如果想做"选了资源后, 前端立即显示资源 highlights 作为 description placeholder", 可以: -- 前端编辑节点选完资源后, 调 `GET /admin/scenic/spot/{id}` (或对应资源详情接口) 读 `highlights`, 作为 description 输入框 placeholder -- 用户开始打字时 placeholder 消失, 用户保存空 description 时后端会用 highlights 填 - -但后端已经自动落了, **前端不改也完全正常工作**。 diff --git a/changelogs/2026-05/12_feat_admin_resource_icon_svg_default_to_node_emojiIcon.md b/changelogs/2026-05/12_feat_admin_resource_icon_svg_default_to_node_emojiIcon.md deleted file mode 100644 index 2ad6ca0..0000000 --- a/changelogs/2026-05/12_feat_admin_resource_icon_svg_default_to_node_emojiIcon.md +++ /dev/null @@ -1,109 +0,0 @@ -# 后端 feat 通知 — 资源 3 类加回 icon_svg, 节点选资源时默认带到 emojiIcon - -**日期**: 2026-05-12 -**类型**: 后端新增功能 (PR #2100) -**模块**: 资源服务 (景区/游玩项目/服务) + 产品行程节点 -**通知**: @mmg -**前端是否需改动**: **需要** — 资源管理 3 个编辑弹窗加"上传 SVG 图标"入口 -**严重性**: P2 - ---- - -## 背景 - -前端反馈 PR #2091 后, 资源管理弹窗里**没法维护"图标"**。之前删 iconSvg 时把资源端的也一起删了过头, 但资源端实际没有可复用的图标字段 (cover_material_id 是大封面图, 语义不同)。 - -本次给资源 3 表加回 `icon_svg TEXT` 字段, 用户在资源管理页能上传 SVG 图标。节点选资源时, 后端自动把资源 iconSvg 复制到节点 emojiIcon (与 PR #2096 highlights→description 同样的"默认值, 可改不回写"机制)。 - ---- - -## API 变化 - -### 资源 admin CRUD 接口 (3 类) - -**景区** `/admin/scenic/spot` POST/PUT/GET, **游玩项目** `/admin/activity/...`, **服务** `/admin/service-item/...`: - -**请求体新增字段** (可选): -```json -{ - "iconSvg": "<svg viewBox=\"0 0 24 24\"><path d=\"...\"/></svg>" -} -``` - -**响应体新增字段**: -```json -{ - "iconSvg": "<svg viewBox=\"0 0 24 24\"><path d=\"...\"/></svg>" -} -``` - -ListVO 也包含 iconSvg, 前端列表可以快速预览图标。 - -### 资源端内部 Feign - -`GET /internal/mp/resource/batch-details` 返回 `ResourceDetailDTO` **新增 iconSvg 字段** (字段顺序: description → highlights → iconSvg → cover)。 - -### 产品节点保存接口 - -`PUT /admin/product/item/{id}/itinerary` 节点保存时: -- 节点不传 `emojiIcon` + 选了资源 (resourceId 非空) + 资源 iconSvg 非空 → **后端自动用资源 iconSvg 填到 node.emojiIcon** -- 节点显式传 emojiIcon → 不被覆盖 -- 之后修改资源 iconSvg 不影响已存在的节点 (节点 emojiIcon 是独立快照, 不回写资源) - -### 产品/MP 节点查询接口 - -`GET /admin/product/item/{id}` + 等 MP 接口: `node.emojiIcon` 字段结构不变, 但可能比之前更常有 SVG 字符串内容 (自动带的)。 - ---- - -## 前端 mmg 行动项 - -### 1. 资源管理 3 个编辑弹窗加图标上传 (景区/游玩项目/服务) - -建议位置: 编辑弹窗的「媒体素材」tab 里, 紧挨"封面图"上传组件下方加一个"小图标"上传组件: -- 接受 .svg 文件或直接粘贴 SVG XML -- 后端字段名: `iconSvg` -- 限制: TEXT 列, 一般 SVG 大小都不超过 64KB 完全够 - -### 2. 节点 emojiIcon 渲染逻辑增强 (可选) - -之前 emojiIcon 存的是 lucide 名 (如 "map-pin"), 现在可能是 SVG XML 字符串。前端渲染逻辑建议: -```js -if (emojiIcon?.startsWith("<svg")) { - // 直接渲染 SVG (注意 XSS, 用 v-html 时套 DOMPurify) -} else { - // lucide-icon 组件渲染 -} -``` - -如果前端已经按这个分支处理, 那不用动。 - -### 3. 节点编辑页 emojiIcon 字段 -节点编辑页若有 emojiIcon 输入框, 用户选完资源后**后端会自动填一个默认 SVG**。用户可以保留 (不动)、清空 (设为 null) 或换 lucide 名/其他 SVG。 - ---- - -## 测试服实测结果 - -部署版本: dev 最新 (PR #2100 已合并) - -| 场景 | 期望 | 实测 | -|------|------|------| -| 资源 PUT 带 iconSvg | DB 存入, GET 返回 | ✅ PASS (景区 2029818530992472065 写入读出一致) | -| 节点不传 emojiIcon + 选有 iconSvg 的资源 | node.emojiIcon = 资源 iconSvg | ✅ PASS | -| Flyway V20260512_004 | 3 表都加上 icon_svg 列, success=1 | ✅ PASS | - -测试数据已清理 (节点临时数据 + 资源 iconSvg 已置 NULL)。 - ---- - -## DB Schema 变化 (前端无关, 仅记录) - -V20260512_004: -```sql -ALTER TABLE scenic_spot ADD COLUMN icon_svg TEXT NULL COMMENT 'SVG 图标源码'; -ALTER TABLE activity ADD COLUMN icon_svg TEXT NULL COMMENT 'SVG 图标源码'; -ALTER TABLE service_item ADD COLUMN icon_svg TEXT NULL COMMENT 'SVG 图标源码'; -``` - -节点表 `product_itinerary_node` **不动** (继续用 emojiIcon TEXT, 不加新列)。 diff --git a/changelogs/2026-05/12_feat_admin_restaurant_icon_svg.md b/changelogs/2026-05/12_feat_admin_restaurant_icon_svg.md deleted file mode 100644 index 4007eee..0000000 --- a/changelogs/2026-05/12_feat_admin_restaurant_icon_svg.md +++ /dev/null @@ -1,44 +0,0 @@ -# 后端 feat 通知 — 餐厅 restaurant 加 icon_svg, 与 3 类对齐 - -**日期**: 2026-05-12 -**类型**: 后端补齐 (PR #2106) -**模块**: 资源服务 — 餐厅 -**通知**: @mmg -**前端是否需改动**: **需要** — 餐厅编辑弹窗加图标上传, 与景区/活动/服务统一 -**严重性**: P3 - ---- - -## 背景 - -PR #2100 只给景区/活动/服务 3 类加了 icon_svg, 漏了餐厅。本次补齐, 4 类资源对齐。 - -## API 变化 - -餐厅 admin CRUD: `POST /admin/restaurant`, `PUT /admin/restaurant/{id}`, `GET /admin/restaurant/items`, `GET /admin/restaurant/{id}` - -**请求体新增可选字段**: `iconSvg` -**响应体新增字段**: `iconSvg` (列表 + 详情都返回) - -资源端 Internal Feign `GET /internal/mp/resource/batch-details` Restaurant 的 ResourceDetailDTO 也带 iconSvg 了。 - -## 节点选餐厅时的默认带过去 - -`nodeType=RESTAURANT` + 不传 `emojiIcon` + 资源 iconSvg 非空 → 节点 emojiIcon 自动复制餐厅 iconSvg (复用 PR #2100 的 `ProductItineraryService.convertNode` 逻辑, 4 类资源全覆盖)。 - -## 测试服实测 - -部署版本: dev 最新 (PR #2106) - -| 接口 | iconSvg 字段返回 | -|------|------------------| -| `GET /admin/scenic/spots` | ✅ | -| `GET /admin/activity/items` | ✅ | -| `GET /admin/service/items` | ✅ | -| `GET /admin/restaurant/items` | ✅ | - -`flyway_schema_history.V20260512.005 success=1`, restaurant 表 icon_svg 列已建。 - -## 前端 mmg 行动项 - -餐厅编辑弹窗加"上传 SVG 图标"入口, 字段名 `iconSvg`, 与景区/活动/服务 3 个弹窗的实现方式保持一致。 diff --git a/changelogs/2026-05/12_fix_admin_product-v2-custom-canedit-after-order.md b/changelogs/2026-05/12_fix_admin_product-v2-custom-canedit-after-order.md deleted file mode 100644 index be8a3d6..0000000 --- a/changelogs/2026-05/12_fix_admin_product-v2-custom-canedit-after-order.md +++ /dev/null @@ -1,57 +0,0 @@ -# 后端 fix 通知 — CUSTOM 私人定制产品已下单时 canEdit 强制 false - -**日期**: 2026-05-12 -**类型**: 后端修复 (PR #2085, merge commit `72ef5693`) -**模块**: 产品 V2 管理端列表/详情 → `canEdit` 字段语义增强 -**通知**: @mmg -**前端是否需改动**: **不需要** — 前端继续按 `canEdit` 决定"修改/删除"按钮显示, 后端语义自动收紧 -**严重性**: P2(防数据不一致) - ---- - -## 背景 - -私人定制 (CUSTOM) 产品本质上是为单一客户量身设计的方案, 一旦客户下单付费即代表方案已被接受。继续允许编辑产品本身会导致订单 `productSnapshot` 与产品现状失配, 客户拿到的合同/小程序回显 ≠ 实际购买的方案。 - -## 改动 - -### `canEdit` 新规则 - -| 场景 | 旧 canEdit | 新 canEdit | -|------|-----------|-----------| -| 未认证 | false | false (不变) | -| CUSTOM + 有活跃订单 (status NOT IN CANCELLED/REFUNDED) | 超管=true / 创建人=true | **false (强制覆盖)** | -| CUSTOM + 0 活跃订单 (或仅 CANCELLED/REFUNDED) | 超管=true / 创建人=true | 不变 | -| CORE / GROUP | 超管=true / 创建人=true | 不变 (此规则不适用) | - -### 受影响接口 - -- `GET /admin/product/item/{id}` (产品详情) -- `GET /admin/product/item/list` (产品分页列表) - -返回的 VO 中 `canEdit` 字段会按上述新规则计算。`isOwner` 字段不受影响 (仍按 `created_by == 当前 adminId` 判定)。 - -### Swagger 文档已更新 - -`ProductDetailRespVO.canEdit` / `ProductListRespVO.canEdit` 的 `ApiModelProperty` 已写明完整规则, 前端可从 swagger UI 直接看到。 - ---- - -## 前端 mmg 无需改动 - -前端继续按当前逻辑读 `canEdit` 决定"修改/删除"按钮 disabled / 隐藏即可。CUSTOM 产品被锁的场景下: -- 按钮自动 disabled (符合现有交互) -- 鼠标 hover 提示可考虑加一句"产品已被订单引用, 不可修改" — 但**不是必须**, 现有提示也可继续用 - ---- - -## 内部新增端点 (前端无关, 仅记录) - -`GET /internal/order/count-active-by-products?productIds=...` → `Map<productId, 活跃订单数>` -供产品列表批量计算 canEdit, 一次 GROUP BY 替代 N+1 调用。仅 product-v2 通过 Feign 调用, 外部访问会被 `X-Internal-Token` 过滤器拦截。 - ---- - -## 降级保护 - -订单服务异常时, `canEdit` 保留原数据权限计算结果 (不强翻 false) — 订单服务抖动不会连带产品列表/详情不可用。日志关键字: `查 CUSTOM 产品活跃订单数失败` / `批量查 CUSTOM 产品活跃订单数失败`。 diff --git a/changelogs/2026-05/12_fix_admin_product-v2-mileage-override-and-child-price-zero.md b/changelogs/2026-05/12_fix_admin_product-v2-mileage-override-and-child-price-zero.md deleted file mode 100644 index 64ec75c..0000000 --- a/changelogs/2026-05/12_fix_admin_product-v2-mileage-override-and-child-price-zero.md +++ /dev/null @@ -1,100 +0,0 @@ -# 后端 fix 通知 — 产品 V2 编辑两项修复(里程被覆盖 + 儿童售价=0) - -**日期**: 2026-05-12 -**类型**: 后端修复 (PR #2067, merge commit `d30bd995`) -**模块**: 产品 V2 编辑 → 行程编排 / 价格日历批量 -**通知**: @mmg -**前端是否需改动**: **可选**(后端兼容现有前端行为, 修复后即生效; 若要支持"取消手动锁回到自动计算"则需小调整, 见下) -**严重性**: P1(行程里程) + P2(儿童售价=0) - ---- - -## 修复 1: 行程编排「当日里程」手动改后保存被高德覆盖 (Closes #2064) - -### 现象 -产品 V2 编辑页 → 第 2 步「行程编排」→ DAY N → 修改「里程」输入框为某个值(如 180 km)→ 保存 → 刷新页面 → 里程又变回了高德自动计算的数字。 - -### 根因 -后端有 `mileageManualOverride` 开关字段标记是否人工覆盖。前端编辑 `dailyMileage` 时只传数值未带 override=true, 后端 MP `updateById` NOT_NULL 策略跳过 null 字段, DB 中 override 保持 0, 事务提交后 `ItineraryAutoCalculator` 调高德 API 重新覆盖用户输入。 - -### 修复 -后端 `ProductItineraryService.convertDay` 兜底: 当前端传了 `dailyMileage` 但未显式传 `mileageManualOverride` 时, 自动视为手动覆盖(置为 TRUE), 阻断 autocalc 覆盖。 - -### 前端 mmg 完全无需改动 -前端继续按当前逻辑只提交 `dailyMileage` 即可, 后端兜底已覆盖。 - -### 如果要支持「重置回自动计算」(可选, 不是必做) -若想加一个"刷新/重置"按钮让用户撤销手动锁、回到高德自动值, 需: -1. 该天 SaveReqVO 显式传 `dailyMileage: null` **且** `mileageManualOverride: false` -2. 保存后等 1-2 秒, 后端 autocalc 会重算并填入 - -截图里看到里程字段旁有圆形刷新图标和 × 按钮, 如果这两个图标已绑此语义, 检查一下提交时是否真的清空 dailyMileage + 显式 override=false。 - ---- - -## 修复 2: 价格日历批量设置允许儿童售价 = 0 (Closes #2066) - -### 现象 -价格日历批量设置中, 儿童售价填 `0` 报「儿童售价必须大于0」无法保存。业务上 `0` 表示儿童免费应允许。 - -### 修复 -后端 4 处放宽: -1. `PriceCalendarBatchReqVO.childSellPrice` `@DecimalMin` 0.01 → 0.00, 文案改"儿童售价不能为负数" -2. `ProductPricingService` 第一道校验拆分: null → 原 REQUIRED 错误码; <0 → 新错误码 `PRICE_CHILD_SELL_PRICE_NEGATIVE` (410112) -3. `ProductPricingService` 固定订金模式: `childSellPrice=0` 时跳过"必须>订金"校验 -4. `ProductBasicService` 反向校验对称处理: 调订金时若现存价格日历/班期 `childPrice=0` 视为免费跳过, 避免"正向能设 0、反向改订金又被卡" - -成人售价校验维持 `>0` 不变, 不允许成人售价 0。 - -### 前端 mmg 行为变化 -- 儿童售价输入框: 现在允许填 `0`(免费) -- 儿童售价 = 负数: 仍报错, 文案变成「儿童售价不能为负数」(原"必须大于0") -- 成人售价: 维持 `>0`, 不可填 0 - -如果前端有"儿童售价 ≥ 0.01"的本地校验, **请放宽到 ≥ 0**(允许 0.00, 不允许负数)。 - ---- - -## ✅ 测试服真测(2026-05-12 10:04 部署, 10:14-10:15 真测) - -测试服 admin token (test_admin) 经网关 `api.test.1814.love:9443` 真测, 用产品 `2053662735618506754`: - -### Case 1: BUG #2064 修复验证 - -| 步骤 | 操作 | 结果 | -|------|------|------| -| baseline | DAY 2 (dayId=2053662735677227011) `daily_mileage=140.0` `override=1` | — | -| 改动 | PUT `/admin/product/item/{id}/itinerary` DAY 2 `dailyMileage=888.0`, **不传 override** | HTTP 200, code=200, msg="行程保存成功" | -| 等 8s | autocalc 在 10:14:11 跑完 `自动计算每日里程完成, 天数=7` | — | -| 验证 | SQL `daily_mileage=888.0` `mileage_manual_override=1` | ✅ 888 未被高德覆盖 | - -### Case 2: BUG #2066 修复验证 - -| 步骤 | 操作 | 结果 | -|------|------|------| -| 改动 | POST `/admin/product/item/{id}/price-calendar/batch`, `childSellPrice=0, adultSellPrice=1999, date=2026-12-15, tier=1, NORMAL` | HTTP 200, code=200, msg="价格日历设置成功" | -| 验证 | SQL `child_sell_price=0.00, adult_sell_price=1999.00, price_type=NORMAL` | ✅ child=0 落库 | - -### Case 3: 边界 — 儿童售价 = -1 仍拦 - -- POST 同上 `childSellPrice=-1` → HTTP 200, **code=400** msg="**儿童售价不能为负数**" success=false ✅ - -### Case 4: 旁证 — autocalc 在 override=false 时正常生效 - -- DAY 3 显式传 `mileageManualOverride=false` 且不传 `dailyMileage` → 8s 后 SQL `daily_mileage=0.0 override=0`, 日志 10:15:36 `自动计算每日里程完成` — autocalc 正常生效(该天集散坐标相同高德返 0km, 是预期结果) - ---- - -## 影响面 / 兼容性 - -- 接口签名零变化 — 任何前端代码不改也能直接用 -- 已部署: 测试服 product-v2 双实例(8083 + 8183) 已是含修复的版本 -- 历史已被高德覆盖的天: 下次用户手动改并保存即可锁住, 无需脏数据修复 -- 已有 `mileage_manual_override=1` 的天不受影响 -- 历史已有 `childSellPrice` 数据不受影响, 仅前向允许 0 入库 - -## 关联 - -- PR: https://git.1814.love:8443/wx/HL/pulls/2067 -- Issue #2064: https://git.1814.love:8443/wx/HL/issues/2064 -- Issue #2066: https://git.1814.love:8443/wx/HL/issues/2066 diff --git a/changelogs/2026-05/12_fix_product_v2_itinerary_clearable_fields_ignored.md b/changelogs/2026-05/12_fix_product_v2_itinerary_clearable_fields_ignored.md deleted file mode 100644 index 1364c5e..0000000 --- a/changelogs/2026-05/12_fix_product_v2_itinerary_clearable_fields_ignored.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -date: 2026-05-12 -type: backend-fix -service: hl-product-service-v2 -priority: high -notify: ["@mmg"] -status: verified ---- - -# 行程编辑「时间段」等可清空字段清空保存后未生效 - -> **PR**: [#2122](https://git.1814.love:8443/wx/HL/pulls/2122) — 已合并 dev (squash `afeff93`) + 部署测试服 (Deploy Panel 任务 `2c62aa31`) -> **Issue**: [#2119](https://git.1814.love:8443/wx/HL/issues/2119) -> **接口**: `PUT /admin/product/item/{id}/itinerary` — 保存整套行程 -> **状态**: ✅ **测试服已 round-trip 验证** — 产品 `2045345825172639746` 真测 - ---- - -## 是否破坏性 API 变更 - -**否**。请求/响应字段、类型、嵌套层数全部不变,仅修复 UPDATE 时 null 字段被默认策略跳过导致旧值残留的 bug。 - -## 影响范围 - -`PUT /admin/product/item/{id}/itinerary` 的 itinerary 节点 / Day 共 25 个可清空字段, 在前端置 null 后, DB 现在会真正写 NULL(此前 MyBatis-Plus 默认 `FieldStrategy.NOT_NULL` 跳过 null → 旧值残留)。 - -### `product_itinerary_node` (9 个字段加 `@TableField(updateStrategy = FieldStrategy.IGNORED)`) -`timePeriod` / `startTime` / `durationMinutes` / `description` / `emojiIcon` / `extraData` / `resourceId` / `resourceType` / `resourceName` / `images` - -### `product_itinerary_day` (16 个字段加 IGNORED) -`dayTitle` / `quoteText` / `description` / `coverImageUrl` / `breakfast` / `lunch` / `dinner` / `diningRemark` / `gatherPlace` / `dismissalPlace` / `dailyMileage` / `dailyDuration` / `mileageManualOverride` / `photoUrls` / `customFields` - -> 关键关联字段(`productId` / `dayId` / `sortOrder` / `nodeName` / `nodeType`)**保留默认 NOT_NULL**, 避免误清关联。 - -## 前端 @mmg 无需改动 - -接口契约不变, 前端继续按现有 contract 提交 null/空数组即可, 后端会真正写 NULL。 - -## 测试服真测 (硬性凭证) - -产品 `2045345825172639746` DAY 2 黑山头节点, 三阶段 round-trip(update_time 跨阶段递增 17:35:33 → 17:36:30 → 17:36:35): - -| 阶段 | timePeriod | breakfast | update_time | -|------|-----------|-----------|-------------| -| 起始 | EARLY_MORNING | HOTEL | 17:35:33 | -| 置 null 保存 + 重查 | NULL ✓ | NULL ✓ | 17:36:30 | -| 还原 EARLY_MORNING / HOTEL | EARLY_MORNING | HOTEL | 17:36:35 | - -现场已恢复, 无遗留数据污染。 - -## 风险 - -极小。仅是 UPDATE 时把 null 真正下发, 不影响新增 / 查询 / 关联字段。已加反射单测断言每个 IGNORED 字段带注解, 防回归。 diff --git a/changelogs/2026-05/12_fix_product_v2_schedule_child_zero_deposit_bypass.md b/changelogs/2026-05/12_fix_product_v2_schedule_child_zero_deposit_bypass.md deleted file mode 100644 index fd820f3..0000000 --- a/changelogs/2026-05/12_fix_product_v2_schedule_child_zero_deposit_bypass.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -date: 2026-05-12 -type: backend-fix -service: hl-product-service-v2 -priority: medium -notify: ["@mmg"] -status: verified ---- - -# 班期创建: 儿童价=0 时跳过订金校验 (与价格日历对齐) - -> **PR**: [#2117](https://git.1814.love:8443/wx/HL/pulls/2117) — 已合并 dev + 部署测试服 -> **Issue**: [#2116](https://git.1814.love:8443/wx/HL/issues/2116) -> **接口**: `POST /admin/product/item/{id}/schedule` (POST 新增 / PUT 修改, 同一 Service 方法) -> **状态**: ✅ **测试服已验证** — 3 case curl 真测 - ---- - -## 背景 - -价格日历 `validatePriceCalendarReq` 早已加 child=0 视为儿童免费 → 跳过订金校验的逻辑。**班期 `doSaveSchedule` 路径漏改**, 同一固定订金产品下: - -- 价格日历批量保存 child=0: ✓ 通过 -- 班期创建 child=0: ❌ 报 `儿童售价（0元）必须大于产品订金` - -两路径校验不一致, 用户感知为 BUG。 - -## 修复 - -`ProductPricingService.doSaveSchedule` 加 `> 0` 守卫: - -```java -if (req.getChildPrice() != null - && req.getChildPrice().compareTo(BigDecimal.ZERO) > 0 // ← 新增 - && req.getChildPrice().compareTo(fixedDeposit) <= 0) { - throw new BusinessException(PRICE_CHILD_BELOW_DEPOSIT, ...); -} -``` - -**成人价校验保持不变** (成人不允许免费 / 必须大于订金, 该规则与价格日历一致)。 - -## 测试服真测 (硬性凭证) - -产品 2053059685258309633 (DEPOSIT mode, deposit_amount=500) - -``` -Scenario 1: child=0 + adult=600 - → 200 OK, batchId=2054124392056590337 ✓ (修复前 410106) - -Scenario 2: child=300 + adult=600 (300 < 500 deposit) - → 410106 "儿童售价（300元）必须大于产品订金（500.00元/人）" ✓ (回归 child<deposit 仍拦截) - -Scenario 3: adult=400 + child=0 (400 < 500 deposit) - → 410105 "成人售价（400元）必须大于产品订金（500.00元/人）" ✓ (adult 校验不变) -``` - -## 前端 @mmg 无需改动 - -仅是后端校验放宽, 接口/字段/响应结构无变化。班期编辑页面**已经允许** child=0 输入(原前端无禁用), 之前是被后端拦截。本 changelog 备案即可。 - -## 风险 - -极小。校验放宽方向: child=0 从拦截改为允许, 不破坏既有数据/调用。 diff --git a/changelogs/2026-05/12_fix_product_v2_toddler_discount_db_clear_on_update.md b/changelogs/2026-05/12_fix_product_v2_toddler_discount_db_clear_on_update.md deleted file mode 100644 index da429be..0000000 --- a/changelogs/2026-05/12_fix_product_v2_toddler_discount_db_clear_on_update.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -date: 2026-05-12 -type: backend-fix -service: hl-product-service-v2 -priority: high -notify: ["@mmg"] -status: verified ---- - -# 价格日历: 小童优惠儿童=0 时 DB 列**真正清空**(补 #2107 漏网回归) - -> **PR**: [#2111](https://git.1814.love:8443/wx/HL/pulls/2111) — 已合并 dev + 部署测试服 -> **Issue**: [#2110](https://git.1814.love:8443/wx/HL/issues/2110) -> **接口**: `POST /admin/product/item/{id}/price-calendar/batch` (无 API 变化) -> **状态**: ✅ **测试服已验证** — 4 场景 DB 落库 SQL 真测通过 - ---- - -## 背景 - -#2107 (changelog `12_fix_product_v2_toddler_discount_normalize_and_validate.md`) 修了"儿童=0 时强制 toddlerDiscount=null"逻辑, 单测 + INSERT 场景验证通过, **遗漏了 UPDATE 场景**: - -- 原 DB 已有记录 `child=80, toddler=20` -- 用户改 child=0 保存 (前端把 toddler 输入框 disabled) -- 后端 step 0 把 `req.toddlerDiscount` 归一化为 null ✓ -- `expandToDailyRecords` 兜底 0→null ✓ -- **`batchUpsert` 走 `updateById(item)`, MP 默认 `FieldStrategy.NOT_NULL` 跳过 null 字段**, UPDATE SQL 不下发 `set toddler_discount=NULL`, **DB 列保留原值 20** - -## 修复 - -```java -public class ProductPriceCalendarDO extends BaseDO { - @TableField(updateStrategy = FieldStrategy.IGNORED) // ← 加这一行 - private BigDecimal toddlerDiscount; -} -``` - -`FieldStrategy.IGNORED` 强制 UPDATE 写入此字段, 即使 null 也下发 `set toddler_discount=NULL`, 让 step 0 归一化真正落库。 - -## 测试服真测 (硬性凭证) - -接口: `POST /admin/product/item/{id}/price-calendar/batch` -产品: 2053668473820622849 (test_admin 自有产品) - -``` -Scenario A: 已有 child=80,toddler=20 + 提交 child=0 - → DB seed: toddler_discount=20.00 (insert 阶段) - → DB after: toddler_discount=NULL ✓ (update 阶段强制写入) - -Scenario B: 已有 child=80,toddler=20 + 提交 child=60,toddler=0 - → DB seed: 20.00 - → DB after: NULL ✓ (expandToDailyRecords 0→null 归一化 + UPDATE 真写) - -Scenario C: 已有 child=80,toddler=20 + 提交 child=60,toddler=15 - → DB seed: 20.00 - → DB after: 15.00 ✓ (正常 UPDATE) - -Scenario D: 全新 child=0 - → DB after: NULL ✓ (INSERT 阶段 null 正常写入) -``` - -## 影响面 - -- **API 不变, 仅 DB 写入行为修正**, 前端无需改动 -- `infantPrice/singleRoomDiff` 等其他金额字段**不需要**同样调整 (0=合法值, 无 0→null 归一化语义) -- `deductStock/restoreStock` 走 load → setSold → updateById, toddler_discount 字段从 DB 加载原值原样写回, IGNORED 策略下等价无变化, 安全 - -## 风险 - -- 极小. `@TableField(updateStrategy=IGNORED)` 是 MP 官方文档行为, 仅影响**该单字段**的 UPDATE 写入策略, 不影响 INSERT/SELECT/DELETE。 - -## 历史脏数据 - -DB 里可能存在 `childSellPrice=0 && toddler_discount IS NOT NULL` 的脏数据(#2107 之前的残留)。**下次该区间编辑保存**会被本 PR 真正清掉, 用户无感知, 无需单独迁移脚本。 - -## 前端 @mmg 无需改动 - -仅是后端 UPDATE 写入策略修正, 接口/字段/行为全无变化。本 changelog 仅备案。 diff --git a/changelogs/2026-05/12_fix_product_v2_toddler_discount_normalize_and_validate.md b/changelogs/2026-05/12_fix_product_v2_toddler_discount_normalize_and_validate.md deleted file mode 100644 index 4622aa4..0000000 --- a/changelogs/2026-05/12_fix_product_v2_toddler_discount_normalize_and_validate.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -date: 2026-05-12 -type: backend-fix -service: hl-product-service-v2 -priority: high -notify: ["@mmg"] -status: verified ---- - -# 价格日历:小童优惠 toddlerDiscount 校验 + 兜底归一化(已测试服端到端验证) - -> **PR**: [#2102](https://git.1814.love:8443/wx/HL/pulls/2102) + hotfix [#2107](https://git.1814.love:8443/wx/HL/pulls/2107) — 全部合并 dev + 部署测试服 -> **Issue**: [#2101](https://git.1814.love:8443/wx/HL/issues/2101) -> **接口**: `POST /admin/product/item/{id}/price-calendar/batch` -> **状态**: ✅ **测试服已验证** (api.test.1814.love:9443) — 4 case 端到端 curl 通过 + DB 落库确认 - ---- - -## ⚠️ 业务铁规(用户确认) - -小童优惠 `toddlerDiscount` 语义 = 「相对儿童价的折扣额」, 后端强制约束: - -1. **0 ≤ toddlerDiscount ≤ childSellPrice** — 负数无意义, 大于儿童价反义 -2. **childSellPrice = 0 时 toddlerDiscount 强制 null** — 儿童免费, 小童优惠无业务语义, 后端兜底覆盖即使前端误传非 0 - -注:**toddlerDiscount 是正数** (折扣额). 后端公式 `toddlerPrice = max(0, childPrice - toddlerDiscount)`, 越大小童越便宜. - ---- - -## 一、测试服已验证 (硬性凭证) - -``` -Case 1: child=100, toddler=200 (越界) - → HTTP 200, code=410104, msg="小童优惠额不能超过儿童售价" ✓ - -Case 2: child=100, toddler=-10 (负数) - → HTTP 200, code=410113, msg="小童优惠不能为负数, 当前值: -10" ✓ - -Case 3: child=0, toddler=10 (儿童免费场景) - → HTTP 200, code=200, success=true - → GET 价格日历: date=2099-01-01 child=0.0 toddlerDiscount=None - → DB 落库 toddler_discount = NULL ✓ (兜底归一化生效) - -Case 4: child=100, toddler=30 (正常) - → HTTP 200, code=200, success=true - → DB 落库 toddler_discount = 30 ✓ -``` - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 变更类型 | 说明 | -|---|------|------|----------|------| -| 1 | 价格日历批量设置 | POST `/admin/product/item/{id}/price-calendar/batch` | **新增校验 + 兜底归一化** | toddlerDiscount<0 抛 410113; child=0 时 toddlerDiscount 强制 null | - -**响应字段不变**, 只是请求体校验更严格 + child=0 时自动归一化. - ---- - -## 三、错误码 - -| code | 错误码常量 | 消息 | 触发场景 | -|------|----------|------|---------| -| **410113** | `PRICE_TODDLER_DISCOUNT_NEGATIVE` | 小童优惠不能为负数, 当前值: {0} | **新增**. toddlerDiscount < 0 | -| 410104 | `PRICE_TODDLER_DISCOUNT_EXCEEDS_CHILD` | 小童优惠额不能超过儿童售价 | 既有. toddlerDiscount > childSellPrice | - -注:`childSellPrice == 0` 时**先在校验入口被兜底归一化 toddlerDiscount=null**, 因此 child=0 的请求**不会**触发 410104, 即使前端传了非 0 的 toddler. - ---- - -## 四、需要前端做的事 (@mmg) - -### 1) `PriceIntervalEditor.vue` (价格区间编辑表单) - -```vue -<!-- 小童优惠额字段, 第 358-361 行附近 --> -<NInputNumber - v-model:value="formData.toddlerDiscount" - :min="0" <!-- ✅ 新增 - 不允许负数 --> - :max="formData.childSellPrice || 0" <!-- ✅ 新增 - 不超过儿童价 --> - :disabled="!formData.childSellPrice" <!-- ✅ 新增 - 儿童=0/null 时锁死 --> - :precision="2" - placeholder="选填,正数=折扣额,不能大于儿童价" <!-- ✅ 改 - 原"选填,负数"语义反 --> - :show-button="false" - style="width: 100%" - @focus="handleNumberFocus"> - <template #prefix>¥</template> -</NInputNumber> -``` - -加 watch:儿童价改为 0 时,自动把 toddlerDiscount 清零: - -```js -watch(() => formData.value.childSellPrice, (newChild) => { - if (newChild === 0 || newChild === null) { - formData.value.toddlerDiscount = 0 // 或 null - } -}) -``` - -### 2) `CalendarDayModal.vue` (单日价格编辑) — 同样改动 - -第 88-100 行附近的 toddlerDiscount NInputNumber: -- `:min="0"`、`:max="formData.childSellPrice || 0"`、`:disabled="!formData.childSellPrice"` -- placeholder "负数,如 -500" → "正数=折扣额" -- 加同样的 watch - -### 3) CSS 误判修正(可选,辅助) - -`PriceIntervalEditor.vue` 第 562-565 行 `.pie-price-label` 当前用 `var(--text-color-placeholder)` 浅灰色,看起来像 disabled. 改 `var(--text-color)` 深色, 跟成人/儿童/单房差的 NFormItem label 一致. - ---- - -## 五、风险/兼容性 - -- **历史脏数据**:DB 里如果存在 `childSellPrice=0 && toddlerDiscount!=null` 的脏数据, **下次该区间编辑保存**会被 step 0 自动清掉(用户无感知). 无需单独数据迁移. -- **历史脏数据 (toddler 负数)**:如果有 toddler<0 的旧数据, **下次编辑时**会被 410113 拦截, 用户需手动清零后才能保存. 影响面小(前端原 placeholder 引导用户输负数, 但实际公式按正数算, 历史负数会让小童变贵,理论上业务方早就发现了). -- **不破坏现有调用**:正常 toddler ∈ [0, childPrice] 的请求行为完全不变. - ---- - -## 六、撤回声明 - -我今天 15:58 发的 changelog `12_frontend_bug_admin_price-interval-toddler-discount-locked-when-child-zero.md`(诊断 CSS 误导 + 字段语义反 + 单日覆盖 3 根因)**已撤回**(文件删除). 当时未确认业务规则, 错把"儿童=0 时小童优惠应该=0"当成 bug. 用户澄清后这是合理的业务联动, 后端 PR #2102+#2107 已实现兜底. - -@mmg 按上面 1)2)3) 三段改 hl-ui 即可, 后端已测过. diff --git a/changelogs/2026-05/12_frontend_bug_admin_mappicker-citylimit-blocks-cross-city-search.md b/changelogs/2026-05/12_frontend_bug_admin_mappicker-citylimit-blocks-cross-city-search.md deleted file mode 100644 index a018b25..0000000 --- a/changelogs/2026-05/12_frontend_bug_admin_mappicker-citylimit-blocks-cross-city-search.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -date: 2026-05-12 -reopened_at: 2026-05-14 -type: frontend-bug -module: admin-map-picker -priority: urgent -notify: ["@mmg"] -status: pending ---- - -# 地图选点搜不到「阿尔山白狼峰景区」等异地地名 — citylimit 锁死了搜索范围 - -## 现象 - -管理后台资源管理(景区/酒店/活动/餐厅/服务)的「地图选点」弹框,搜索框输入 `阿尔山白狼峰景区` 没任何结果;但手机端高德地图 App 能正常搜到(白狼镇 203 省道,距海拉尔 244 公里)。 - -复现路径:资源管理 → 任一资源新建/编辑 → 点地图图标 → 搜索框输 `阿尔山白狼峰景区` → 下拉列表空,回车后 toast 提示「在呼伦贝尔未找到相关地点」。 - -## 根因(纯前端,后端无关) - -文件:`hl-ui/src/components/MapPicker.vue` - -```js -// 第 360-364 行 (AutoComplete - 输入自动补全) -const autoComplete = new window.AMap.AutoComplete({ - city: city, - citylimit: true, // ❌ 强制只搜当前城市 - datatype: 'all', -}) - -// 第 425-431 行 (PlaceSearch - 回车精确搜索) -const placeSearch = new window.AMap.PlaceSearch({ - pageSize: 20, - pageIndex: 1, - city: city, - citylimit: true, // ❌ 强制只搜当前城市 - extensions: 'base', -}) - -// 第 444-448 行 (PlaceSearch 结果二次过滤) -const cityName = city.replace(/市$/, '') -const filteredPois = pois.filter((poi) => { - const poiCity = poi.cityname || poi.pname || '' - return poiCity.includes(cityName) || cityName.includes(poiCity.replace(/市$/, '')) -}) // ❌ 即使高德返回了,前端再剔一次 -``` - -`currentCity` 在打开弹框时默认是「呼伦贝尔」(默认坐标 119.7581, 49.2112 落在海拉尔区),阿尔山白狼峰景区行政归属「**兴安盟阿尔山市**」,跟呼伦贝尔市平级,所以: - -1. 高德 AutoComplete/PlaceSearch 因 `citylimit:true` 直接返回 0 条 -2. 万一返回了也会被前端 `filteredPois` 二次过滤剔掉 -3. 用户得到「在呼伦贝尔未找到」的错觉,实际全国都没搜 - -## 业务背景 - -呼籁旅行的景点/酒店/活动资源**会跨内蒙古多个盟市,甚至跨省**(用户已确认场景:阿尔山在兴安盟,业务里就是要录)。硬把搜索锁在当前定位城市违反业务需求。手机端高德 App 不锁城市能搜到,后台同一份数据库却搜不到,体验割裂。 - -## 修复(前端,3 处改动) - -### 改法 A(推荐,最小改动) — 去掉 citylimit + 去掉二次过滤 - -```js -// AutoComplete -const autoComplete = new window.AMap.AutoComplete({ - // city: city, // 删掉或保留(只作提示,不约束) - // citylimit: true, // ❌ 删 - datatype: 'all', -}) - -// PlaceSearch -const placeSearch = new window.AMap.PlaceSearch({ - pageSize: 20, - pageIndex: 1, - // city: city, // 删掉或保留(只作排序加权) - // citylimit: true, // ❌ 删 - extensions: 'base', -}) - -// 删掉 filteredPois 二次过滤逻辑,直接用 pois.map(...) -``` - -`city` 参数即使保留也只影响**结果排序**(同城靠前),不会过滤异地结果 — 这是高德 SDK 默认行为。 - -### 改法 B(更友好) — 给 POI 下拉列表多显示一行省市 - -去掉 citylimit 后,搜索"白狼峰"可能返回多地同名结果。建议下拉项展示加一行 `pname + cityname + adname`,让用户区分: - -```vue -<div class="poi-name">{{ poi.name }}</div> -<div class="poi-region">{{ poi.pname }}{{ poi.cityname }}{{ poi.adname }}</div> -<div class="poi-address">{{ poi.address }}</div> -``` - -### 改法 C(可选,UX 兜底) — 搜不到时给「扩大到全国」按钮 - -如果产品坚持默认锁当前城市(为了减少干扰),可在 0 结果时改 toast 为按钮「在全国搜索」,点击后重新调一遍不带 citylimit 的搜索。但**不推荐**,默认就该全国搜。 - -## 推荐方案 - -**改法 A + 改法 B**:去掉 citylimit + 下拉列表多显示省市行。改动量小,业务上覆盖跨地市/跨省录入,UX 上避免同名地点歧义。 - -## 验证清单(前端改完自测) - -- [ ] 「阿尔山白狼峰景区」能搜到,选中后地址回填正确 -- [ ] 「故宫」「外滩」等跨省地名能搜到(虽然业务里大概率用不到,但说明搜索域已放开) -- [ ] 原本能搜到的本地地名(海拉尔区、呼伦贝尔学院)仍然能搜 -- [ ] 选中异地 POI 后,确认按钮回填的 `province`/`city`/`district` 与 POI 实际归属一致(不应仍是「呼伦贝尔市」) -- [ ] 5 个调用方均验证:`resource/scenic`、`resource/restaurant`、`resource/playservice`、`resource/hotel`、`resource/extra-service` 的 EditModal - -## 后端无需任何改动 - -地图选点是纯前端组件(高德 JS SDK 直连高德服务器),后端不参与。这条 changelog 只为通知前端修。 - -@mmg 看下 `hl-ui/src/components/MapPicker.vue` 改掉 citylimit 即可,优先 P1 — 影响所有资源录入跨地市的能力。 - ---- - -## 2026-05-14 二次反馈(优先级 high → urgent) - -用户今天又复现同一根因,但场景从「资源管理地图选点」扩散到了**新的表单字段**:某表单的「**结束 \***」输入框,输入 `1` 后下拉建议项**全部局限呼伦贝尔市**(109馨园 / 1mm沙龙美学(锦都会店) / 109小区 / 186彩带河 / 1+2电竞 — 五条全是「内蒙古自治区呼伦贝尔市海拉尔区/陈巴尔虎旗/牙克石市」)。说明: - -1. `MapPicker.vue` 的 `citylimit:true` 至今未改 -2. **该组件在更多页面被复用**(不只是资源管理 EditModal),包括带「出发/结束」字段的表单(疑似订单/行程/定制需求页) -3. 修复一处即覆盖所有调用方,不需要分别改 - -**新增验证项**(在原验证清单基础上): - -- [ ] 带「出发 / 结束」字段的表单,输入「1」/「人民」/「天安门」等通用关键字,下拉应跨城市/跨省返回(不再清一色呼伦贝尔) -- [ ] 在「结束」字段输入「阿尔山」「故宫」「外滩」,能选中并回填正确地址 -- [ ] 全国常用关键字搜索结果数 > 5 条(原来锁城市常出现 0 条或 ≤ 3 条) - -**优先级理由**:第二次反馈,影响面已从资源录入扩散到下单/行程相关表单,业务录入直接卡死。@mmg 麻烦尽快排期,改动量很小(删 2 个 `citylimit:true` + 1 段二次过滤)。 diff --git a/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-CHANGE-to-svg.md b/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-CHANGE-to-svg.md deleted file mode 100644 index 88cc339..0000000 --- a/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-CHANGE-to-svg.md +++ /dev/null @@ -1,114 +0,0 @@ -# ⚠️ 撤销 + 重发: 资源 / 产品节点图标字段改为 SVG 文本 iconSvg - -> **服务**: hl-resource-service (端口 8082) + hl-product-service-v2 (端口 8083) -> **PR**: [#2087](https://git.1814.love:8443/wx/HL/pulls/2087) — 已合并 dev + 测试服部署 -> **撤销**: 同日早些时候的 [`12_frontend_notice_admin_resource-product-icon-selling-point.md`](./12_frontend_notice_admin_resource-product-icon-selling-point.md) 中 `iconMaterialId` / `iconUrl` 两字段**已撤销**, 见下 -> **Issue**: [#2068](https://git.1814.love:8443/wx/HL/issues/2068) (已关闭) -> **日期**: 2026-05-12 -> **影响范围**: 管理端「资源管理 → 景区/活动/服务」+「产品编辑 → 行程编排/产品卖点」+ 小程序「今日体验」节点 - ---- - -## ⚠️ 关键变化 - -**前一份 changelog 说 iconMaterialId 和 iconUrl 两字段** — **这个设计已撤销**。 - -后端最终方案是**单字段 `iconSvg` (String)** 直接存 SVG 源码文本,不走素材库: -- 前端**不需要选择素材库图片**了 -- 前端**不需要拼 OSS URL** 了 -- 前端**收到 iconSvg 直接 v-html 或 SVG 渲染** - -`sellingPoint` 字段保持不变, 仍是 VARCHAR(500)。 - ---- - -## 一、撤销的字段 vs 新字段 - -| 撤销字段(请删) | 新字段(请用) | 类型 | -|----------|---------|------| -| `iconMaterialId` | `iconSvg` | String (TEXT) | -| `iconUrl` | (合并到 `iconSvg`, 不再单独存 URL) | - | - -`sellingPoint` 不变 ✅ - ---- - -## 二、测试服已验证 (硬性凭证) - -``` -hl-resource-service 测试服 V20260512_002 已 apply: - ALTER TABLE scenic_spot/activity/service_item DROP COLUMN icon_material_id, ADD COLUMN icon_svg TEXT -hl-product-service-v2 测试服 V20260512_002 已 apply: - ALTER TABLE product_itinerary_node 同上 - -接口测试: - POST /admin/scenic/spot { iconSvg: "<svg viewBox='0 0 24 24'>...</svg>" } → 存取一致 ✓ - GET 产品行程详情节点 → iconSvg 字段就位 ✓ - 「资源默认值复制」「前端覆盖优先」「不回写资源」三铁规仍守住 ✓ -``` - ---- - -## 三、变更接口清单 - -### 资源端 (12 接口 = 3 类资源 × 4 个接口) - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 1 | 景区 创建 | POST | `/admin/scenic/spot` | 请求/响应 `iconMaterialId` 改 `iconSvg` String | -| 2 | 景区 更新 | PUT | `/admin/scenic/spot` | 同上 | -| 3 | 景区 详情 | GET | `/admin/scenic/spot/{id}` | 响应字段重命名 | -| 4 | 景区 列表 | GET | `/admin/scenic/spots` | ListVO 字段重命名 | -| 5-8 | 活动 同上 | - | `/admin/activity/item*` | - | -| 9-12 | 服务 同上 | - | `/admin/service/item*` | - | - -### 产品端 - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 13 | 行程保存 | PUT | `/admin/product/item/{id}/itinerary` | 节点入参 `iconMaterialId(Long)` → `iconSvg(String)` | -| 14 | 产品详情 (admin) | GET | `/admin/product/item/{id}` | 节点响应 `iconMaterialId/iconUrl` → `iconSvg` | -| 15 | 产品详情 (mp) | GET | `/mp/product/{id}` | 同上,小程序「今日体验」用 | - ---- - -## 四、前端字段约束 - -| 字段 | 类型 | 必填 | 约束 | 备注 | -|------|------|------|------|------| -| iconSvg | String(TEXT, 最大 64KB) | 否 | 应为有效 SVG XML 文本(`<svg ...>...</svg>`) | 前端直接 v-html / innerHTML 渲染或 svg-loader | -| sellingPoint | String | 否 | 最多 500 字符 | 不变 | - ---- - -## 五、UI 层面建议 - -### 资源管理页 (3 类资源) - -之前建议「素材库选择器选小图」的方案撤销, 改成: -- **图标**: 文本框(或 SVG 上传组件), 后端存 SVG 源码 -- 可参考方案: 前端给个 SVG 图标库(如 Material Icons / Heroicons 的 SVG 集合)让用户选, 选完拷 SVG 源码进表单字段 -- 或允许用户直接粘贴 SVG XML(给个 textarea + 预览) - -### 产品编辑 - 行程编排 - -- 节点上的图标控件改用 SVG 源码(同上) -- **后端自动复制规则不变**: 节点选完资源后, 若前端不传 iconSvg → 后端从资源端拷贝默认 SVG 进节点快照 -- 修改节点 iconSvg 不回写资源, 这条铁规也不变 - ---- - -## 六、不影响的地方 - -- `sellingPoint` 字段(包括位置 + 长度 + 行为)不动 -- 「资源默认值复制」「前端覆盖优先」「永不回写资源」三铁规不动 -- Bean Validation 用 @ApiModelProperty 标注新字段, 后端无校验 SVG XML 合法性(前端必要时自检) - ---- - -## 七、需要前端做的事(替代上一份 changelog) - -1. ⏰ **3 类资源管理页**: 把之前规划的「图片素材选择器」换成 **SVG 文本输入/选择** -2. ⏰ **产品编辑 → 行程编排** / **产品卖点**: 节点的 icon 编辑从 materialId 改 SVG 文本字段 -3. ⏰ 「今日体验」小程序: 节点前的图标直接 `wx:html="{{ iconSvg }}"` (或 rich-text) -4. swagger 实时核对: `https://api.test.1814.love:9443/hl-resource-service/v2/api-docs?group=资源服务` + `https://api.test.1814.love:9443/hl-product-service-v2/v2/api-docs?group=产品服务` (账号 hulalv / HuLaLv@Doc2026) diff --git a/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-selling-point.md b/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-selling-point.md deleted file mode 100644 index 003f931..0000000 --- a/changelogs/2026-05/12_frontend_notice_admin_resource-product-icon-selling-point.md +++ /dev/null @@ -1,124 +0,0 @@ -# 资源服务 + 产品行程节点: 新增「图标」「卖点简介」2 字段 - -> **服务**: hl-resource-service (端口 8082) + hl-product-service-v2 (端口 8083) -> **PR**: [#2076](https://git.1814.love:8443/wx/HL/pulls/2076) — 已合并 dev + 测试服部署 -> **PR (hotfix admin VO 补字段)**: [#2081](https://git.1814.love:8443/wx/HL/pulls/2081) — 已合并 dev + 测试服部署 -> **PR (hotfix Flyway pilot marker 解锁)**: [#2077](https://git.1814.love:8443/wx/HL/pulls/2077) — 与本功能间接相关 -> **Issue**: [#2068](https://git.1814.love:8443/wx/HL/issues/2068) -> **日期**: 2026-05-12 -> **影响范围**: 管理端「资源管理 → 景区/活动/服务」 + 「产品编辑 → 行程编排/产品卖点」 + 小程序「今日体验」 -> **状态**: ✅ **测试服已验证** (api.test.1814.love:9443) - ---- - -## ⚠️ 关键变化 - -**资源端 3 类资源**(景区 scenic-spot / 活动 activity / 服务 service-item) **+ 产品行程节点** product_itinerary_node,**各新增 2 个字段**: - -- `iconMaterialId` — 图标素材 ID(指向素材库) -- `sellingPoint` — 卖点简介(VARCHAR 500) - -业务联动: -- 资源端**有这两个字段就是默认值** -- 产品行程节点保存时,**前端如果不传**这两字段,后端**自动从资源端拷贝默认值**到节点快照 -- 产品行程节点保存时,**前端如果显式传值**,以前端为准(产品端可改) -- 产品端改了节点的 icon/selling 也**不回写资源**(资源端永远是真相源) - ---- - -## 一、测试服已验证 (硬性凭证) - -``` -hl-resource-service 测试服: - POST/PUT/GET /admin/scenic/spot iconMaterialId + sellingPoint 能存能取 ✓ - POST/PUT/GET /admin/activity/item iconMaterialId + sellingPoint 能存能取 ✓ - POST/PUT/GET /admin/service/item iconMaterialId + sellingPoint 能存能取 ✓ - GET .../page (列表) ListVO 含 iconMaterialId/iconUrl/sellingPoint ✓ - -hl-product-service-v2 测试服: - POST /admin/product/item/.../itinerary 节点 SAVE 落库 ✓ - GET /admin/product/item/{id} 节点 VO 返回 iconMaterialId + sellingPoint ✓ - 「资源默认值复制」: 前端不传 → 节点字段=资源端 iconMaterialId/sellingPoint ✓ - 「前端覆盖优先」: 前端传值 → 节点字段=前端值 ✓ - 「不回写资源」: 改节点后资源端字段不变 ✓ -``` - -异常路径: -``` -sellingPoint 传 501 字符 → HTTP 200 code=400 "卖点简介不能超过500个字符" ✓ -``` - ---- - -## 二、变更接口清单 - -### 资源端 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 景区 创建 | POST | `/admin/scenic/spot` | 请求体新增 2 字段 | iconMaterialId, sellingPoint | -| 2 | 景区 更新 | PUT | `/admin/scenic/spot` | 请求体新增 2 字段 | 同上 | -| 3 | 景区 详情 | GET | `/admin/scenic/spot/{id}` | 响应体新增 3 字段 | iconMaterialId, iconUrl, sellingPoint | -| 4 | 景区 列表 | GET | `/admin/scenic/spots` | 响应体新增 3 字段 | 列表项含 3 字段 | -| 5-8 | 活动 同上 | - | `/admin/activity/item*` | 同景区 4 接口 | - | -| 9-12 | 服务 同上 | - | `/admin/service/item*` | 同景区 4 接口 | - | - -### 产品端 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 13 | 行程保存 | PUT | `/admin/product/item/{id}/itinerary` | 节点 NodeItem 入参新增 2 字段 | iconMaterialId, sellingPoint(可选) | -| 14 | 产品详情 | GET | `/admin/product/item/{id}` | 节点 NodeRespVO 响应新增 3 字段 | iconMaterialId, iconUrl, sellingPoint | -| 15 | mp 详情 | GET | `/mp/product/{id}` | 节点 NodeInfo 响应新增 3 字段 | 同上,小程序「今日体验」用 | - ---- - -## 三、前端字段约束 - -| 字段 | 类型 | 必填 | 约束 | 备注 | -|------|------|------|------|------| -| iconMaterialId | Long(产品节点) / String(资源端,String 表示的 BIGINT) | 否 | - | 指向素材库的素材 ID | -| iconUrl | String | 否(仅 Resp) | - | 后端解析素材后的 OSS URL,**前端只在响应中读,不传** | -| sellingPoint | String | 否 | 最多 500 字符 | 卖点简介文字 | - ---- - -## 四、UI 层面建议(参考) - -### 资源管理页 - -3 类资源(景区/活动/服务)的**新建/编辑表单**新增 2 个字段: -- **图标**: 素材库选择器(选小尺寸图,推荐 64x64),保存 materialId -- **卖点简介**: 多行文本框,提示"最多 500 字" - -详情页/列表卡片可直接展示这两字段(用 iconUrl + sellingPoint)。 - -### 产品编辑页 - -**行程编排** 步骤(图1 的「活动安排」红框): -- 节点点击图标时弹出**素材选择器** → 选完保存到节点的 iconMaterialId -- 节点详情面板新增**卖点简介**输入框(多行,500 字) -- **新建节点时**,选完资源(景区/活动/服务) → 后端自动用资源端默认值预填,前端可改 -- **修改节点的 icon/卖点 不会回写到资源**,只影响当前产品的这个节点 - -**产品卖点页**(图2 的「快速理解」红框): -- 这个页面和「行程编排」**共用同一份 product_itinerary_node 数据** -- 也就是说在「行程编排」改了节点的 icon/卖点,「产品卖点」页面会立刻看到更新 - ---- - -## 五、风险/兼容性 - -- **不破坏现有调用**: 只追加字段,旧请求不传 → null,旧响应消费方忽略新字段无影响 -- **Bean Validation**: sellingPoint 后端用 @Size(max=500) 校验,前端最好也加前置校验避免 round-trip -- **不回写资源铁规**: 后端 ProductItineraryService.convertNode() 已硬保证,前端无需关心 - ---- - -## 六、需要前端做的事 - -1. ⏰ **3 类资源管理页** 加 2 个字段:图标素材选择器 + 卖点简介文本框(都不必填) -2. ⏰ **产品编辑 → 行程编排** 加节点的 icon/卖点编辑(都不必填,空就用资源默认) -3. ⏰ **产品编辑 → 产品卖点** 页面如果是独立路由,字段读取同 product_itinerary_node 节点 -4. ⏰ 「今日体验」小程序节点前显示图标(iconUrl 字段) + 节点卖点(sellingPoint) -5. 如有疑问可直接对照 swagger: `https://api.test.1814.love:9443/hl-resource-service/v2/api-docs?group=资源服务` 以及 `https://api.test.1814.love:9443/hl-product-service-v2/v2/api-docs?group=产品服务`(账号 hulalv / HuLaLv@Doc2026) diff --git a/changelogs/2026-05/12_improve_resource_disable_allow_when_in_use.md b/changelogs/2026-05/12_improve_resource_disable_allow_when_in_use.md deleted file mode 100644 index 565f5d0..0000000 --- a/changelogs/2026-05/12_improve_resource_disable_allow_when_in_use.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -date: 2026-05-12 -type: backend-improvement -service: hl-resource-service -priority: high -notify: ["@mmg"] -status: verified ---- - -# 资源下架放开"被产品引用"硬拦, 新增 /admin/resource-reference/in-use 预览接口 (已测试服验证) - -> **PR**: [#2120](https://git.1814.love:8443/wx/HL/pulls/2120) — 已合并 dev + 部署测试服 -> **Issue**: [#2115](https://git.1814.love:8443/wx/HL/issues/2115) -> **状态**: ✅ **测试服已验证** (api.test.1814.love:9443) — 6/6 case 端到端通过 - ---- - -## 一、背景 - -之前所有资源 (景区/活动/酒店/房型/餐厅/服务/人员/备品/备品组合/费用项/车型) 下架时, 后端会调 ProductFeignClient.checkResourceInUse 校验"是否被上架产品引用", 被引用就抛 `*_DISABLE_IN_USE` 错误码 (300103/310103/310206/320103/340103/350103/360103/380103/390103) 硬拦. - -实际运营场景中, 资源被产品使用是常态, 强制要求"先解除产品绑定才能下架"把管理员锁死. 现改为: **后端放行下架, 由前端调预览接口拿到引用产品 list 弹二次确认**. - -**删除/审批工作流逻辑不动** — 删除被引用资源仍硬拦, 审批模板/状态机/企微推送全部保留. - ---- - -## 二、测试服已验证 (硬性凭证) - -景区 `scenicId=3001000000000000019` (中俄边境公路) 被 **8 个上架产品**引用. - -``` -A. GET /admin/resource-reference/in-use?type=SCENIC&id=3001000000000000019 - → 200 code=200 data=["结婚不回家", "发的是干啥地方", "冻干粉发短信给", - "有今天放假n", "游牧的森林-短途版", - "呼伦贝尔草原深度定制·3天2晚家庭私享团", - "呼伦贝尔周边摄影季", "游牧的森林-短途版（来自wx的分享）"] - -B. PUT /admin/scenic/spot/3001000000000000019/status body={"status":0} - → 200 code=200 success (历史 410103) ✓ 关键验收 - -C. PUT /admin/scenic/spot/3001000000000000019/status body={"status":1} (上架还原) - → 200 code=200 success - -D. PUT /admin/scenic/spots/batch/status body={"scenicIds":[3 个含 in-use],"status":0} - → 200 code=200 全部下架成功 ✓ (历史会静默跳过 in-use 的) - PUT 同上 status=1 上架还原 → 200 success - -E. GET /admin/resource-reference/in-use 边界: - - type=SCENIC&id=99999999 → 200 data=[] - - type=RESTAURANT&id=1 → 200 data=[] - - type=HOTEL&id=1 → 200 data=[] - - type=ROOM_TYPE&id=1 → 200 data=[] - - type=ACTIVITY&id=1 → 200 data=[] - -F. DELETE /admin/scenic/spots/batch body={"scenicIds":[3001000000000000019]} - → 200 deniedIds=["3001000000000000019"] - → deniedReasons=["被产品使用: 结婚不回家、发的是干啥地方、冻干粉发短信给、…"] - ✓ 删除逻辑保留, 仍硬拦 -``` - ---- - -## 三、变更接口清单 - -### 新接口 - -| # | 接口 | 方法 | 说明 | -|---|------|------|------| -| 1 | `GET /admin/resource-reference/in-use` | GET | **新增**. 查询资源被哪些上架产品使用. 入参 `type` + `id`. 返回 `Result<List<String>>` 引用产品名 list. fail-closed: Feign 失败返 500 FEIGN_RPC_FAIL | - -**type 取值**: `SCENIC` / `ACTIVITY` / `HOTEL` / `ROOM_TYPE` / `RESTAURANT` / `SERVICE` / `STAFF` / `SUPPLIES` / `SUPPLIES_COMBO` / `COST` / `VEHICLE` - -### 行为变更接口 (响应结构不变, 只是不再返 410xxx) - -所有资源下架/禁用相关接口 **不再返** `*_DISABLE_IN_USE` 错误码: - -| 资源类型 | 单条下架 | 批量下架 | 提审批下架 | 已删的错误码 | -|----------|----------|----------|-----------|--------------| -| 景区 | `PUT /admin/scenic/spot/{id}/status` | `PUT /admin/scenic/spots/batch/status` | `POST /admin/scenic/spot/{id}/approval` | **300103** | -| 活动 | (同模式) | (同模式) | (同模式) | **320103** | -| 酒店 | `PUT /admin/hotel/...` | | | **310103** | -| 房型 | (同模式) | | | **310206** | -| 餐厅 | | | | (本就没此校验) | -| 服务 | (同模式) | | | **350103** | -| 人员 | (同模式) | | | **360103** | -| 备品 | (同模式) | | | **380103** | -| 备品组合 | (同模式) | | | **380103 (SUPPLIES_DISABLE_IN_USE 复用)** | -| 费用项 | (同模式) | | | **390103** | -| 车型 | (同模式) | | | **340103** | - -前端原有针对这些 code 的特殊错误提示可以删掉. - -### 删除/审批保留不动 - -- 删除被引用 (4 个 *_DELETE_IN_USE) 保留 ✓ -- "已启用不能删除请先下架" (3 个 STATUS_ON_CANT_DELETE) 保留 ✓ -- 审批模板/状态机/企微推送 全部保留 ✓ - ---- - -## 四、需要前端做的事 (@mmg) - -### 1) 所有资源下架按钮加二次确认弹窗 - -**通用模板** (景区为例): - -```vue -<script setup lang="ts"> -import { useDialog } from 'naive-ui' -import { request } from '@/utils/request' - -const dialog = useDialog() - -async function handleOffline(scenicId: string, scenicName: string) { - // 1. 先查引用情况 - const refRes = await request.get('/admin/resource-reference/in-use', { - params: { type: 'SCENIC', id: scenicId } - }) - const referenced = (refRes.data ?? []) as string[] - - // 2. 被引用 → 弹二次确认 - if (referenced.length > 0) { - const productList = referenced.slice(0, 5).join('、') - + (referenced.length > 5 ? `... 等 ${referenced.length} 个产品` : '') - const ok = await new Promise<boolean>(resolve => { - dialog.warning({ - title: '确认下架?', - content: `「${scenicName}」正被以下 ${referenced.length} 个上架产品使用:\n${productList}\n\n下架后这些产品仍可正常售卖, 但请告知运营.`, - positiveText: '确认下架', - negativeText: '取消', - onPositiveClick: () => resolve(true), - onNegativeClick: () => resolve(false), - }) - }) - if (!ok) return - } - - // 3. 调下架 (历史 410103 不再发生) - await request.put(`/admin/scenic/spot/${scenicId}/status`, { status: 0 }) - message.success('下架成功') -} -</script> -``` - -### 2) 删掉对 *_DISABLE_IN_USE 错误码的特殊处理 - -前端如有 `if (code === 410103 || code === 320103 || ...)` 弹特定提示的逻辑, **删掉**. 服务端不会再返这些 code. - -### 3) type 参数映射 (前端各模块按需用) - -| 资源类型 | type 值 | -|----------|---------| -| 景区 | `SCENIC` | -| 活动 | `ACTIVITY` | -| 酒店 | `HOTEL` | -| 房型 | `ROOM_TYPE` | -| 餐厅 | `RESTAURANT` | -| 服务 | `SERVICE` | -| 人员 | `STAFF` | -| 备品 | `SUPPLIES` | -| 备品组合 | `SUPPLIES_COMBO` | -| 费用项 | `COST` | -| 车型 | `VEHICLE` | - -### 4) (可选) 列表页"被X个产品使用"角标 - -资源列表页可以批量调 `/admin/resource-reference/in-use` 给每个资源加角标"被N个产品使用", 但**不必须** — 二次确认弹窗已经足够. - ---- - -## 五、风险/兼容性 - -- **下架后产品端不变**: 产品行程节点拿的是资源的名字/概要快照, 不实时查 status. 下架仅影响"资源列表筛选可见性"和"管理员新建产品时能选哪些资源". -- **历史脏数据**: 没有. -- **fail-closed**: 新接口 Feign 失败 (product-service 挂了) 抛 500 FEIGN_RPC_FAIL, 前端弹"无法确认引用情况, 请稍后再试" 即可. -- **删除路径仍硬拦**: 数据不会因为允许下架而丢失. - ---- - -## 六、技术债清理 (跟改动一起完成) - -- 删 9 个 0 调用的 `*_DISABLE_IN_USE` 错误码常量 (`ScenicErrorCode` / `HotelErrorCode` / `ActivityErrorCode` 等) -- 7 个 Service 删 `referenceCheckHelper` 字段 (Activity/Cost/Vehicle/Hotel/RoomType/Service/SuppliesCombo) — 这些 Service 不再有引用校验 -- 4 个 Service 保留字段 (Scenic/Restaurant/Staff/Supplies — 它们 batchDelete 还在用) -- `ResourceReferenceCheckHelper` javadoc 更新, 标注只服务删除路径 -- 13 个 test 文件同步: 5 个删 in-use 测试, 7 个 Service 测试构造器去 helper 参数, 1 个清字段 mock - -**mvn test: Tests run: 1148, Failures: 0, Errors: 0, Skipped: 41 — 全绿** - ---- - -@mmg 看到先弹窗模板, 改完通知我闭环. diff --git a/changelogs/2026-05/12_refactor_admin_drop_iconSvg_sellingPoint_reuse_description.md b/changelogs/2026-05/12_refactor_admin_drop_iconSvg_sellingPoint_reuse_description.md deleted file mode 100644 index ea6511f..0000000 --- a/changelogs/2026-05/12_refactor_admin_drop_iconSvg_sellingPoint_reuse_description.md +++ /dev/null @@ -1,88 +0,0 @@ -# 后端 refactor 通知 — 删除冗余 iconSvg / sellingPoint, 改读 description / emojiIcon - -**日期**: 2026-05-12 -**类型**: 后端重构 (PR #2091 + hotfix #2092) -**模块**: 资源服务 (scenic_spot / activity / service_item) + 产品行程节点 (product_itinerary_node) -**通知**: @mmg -**前端是否需改动**: **需要小调整** — 改字段名读取 -**严重性**: P2 (API 响应字段下线) - ---- - -## 背景 - -PR #2076 (#2068) 给资源 3 类 + 产品行程节点各新加了 2 字段: -- `iconSvg` (TEXT, SVG 源码) -- `sellingPoint` (VARCHAR 500, 卖点简介) - -但这些表里**本来就有完全能承担相同语义的字段**: -- `description` (TEXT) — 长描述, 可以放卖点文案 -- 节点 `emojiIcon` (lucide 名字符串) — 节点图标 -- 资源 `cover_material_id` — 资源图 - -两套字段并存维护成本高且无收益, 故本次反悔, 全删新加字段, 复用现有。 - ---- - -## API 响应变化 - -### 资源 (scenic_spot / activity / service_item) - -`GET /admin/scenic/spot/{id}` / `GET /admin/activity/...` / `GET /admin/service-item/...`: -- ❌ 删除 `iconSvg` 字段 -- ❌ 删除 `sellingPoint` 字段 -- ✅ 保留 `description` (TEXT) — 用此放卖点文案 -- ✅ 保留 `coverMaterialId` (BIGINT) — 用此放资源图 - -`POST /admin/scenic/spot` / `PUT /admin/scenic/spot/{id}` 等保存接口: -- ❌ 不再接受 `iconSvg` / `sellingPoint` 字段 (Spring/Jackson 静默忽略, 不会 400) - -### 产品行程节点 (product_itinerary_node) - -`GET /admin/product/item/{id}` → `data.itinerary[].nodes[]`: -- ❌ 删除 `iconSvg` -- ❌ 删除 `sellingPoint` -- ✅ 保留 `description` (TEXT) — 用此放卖点/详细描述 -- ✅ 保留 `emojiIcon` (字符串, lucide 图标名) — 用此放节点图标 - -`POST /admin/product/item/{id}/itinerary/day` 等保存接口同上, 不再接受这两字段。 - -MP 端 `MpProductDetailRespVO`, 内部 Feign `InternalProductDetailVO` / `ItineraryNodeItem` / `MpProductDetailInternalVO` 同步去字段。 - ---- - -## 前端 mmg 行动项 - -1. **资源 admin 编辑页**: 如有 "SVG 图标" / "卖点简介" 单独输入框, 删掉; 把内容并到 description 长文本编辑器 -2. **产品行程编排页**: 节点的 "SVG 图标" 入口下线, 节点图标继续用 emojiIcon (lucide 名选择器); "卖点简介" 输入框并入 description -3. **MP 商品详情/今日体验**: 节点展示读 `description` 替代 `sellingPoint`, 读 `emojiIcon` 替代 `iconSvg` - -如果之前没改过 — 当前前端代码可能就还在读 description/emojiIcon, 那就不用动了。 - ---- - -## 测试服实测结果 - -部署版本: dev `4422274c` (PR #2091 + hotfix #2092) - -| 接口 | 字段验证 | -|------|---------| -| `GET /admin/scenic/spot/{id}` | iconSvg=❌ sellingPoint=❌ description=✅ | -| `GET /admin/product/item/{id}` 节点 (13 真实节点) | iconSvg=❌ sellingPoint=❌ description=✅ emojiIcon=✅ | -| `flyway_schema_history` V20260512.003 | success=1, 4 表对应列已删 | - ---- - -## DB Schema 变化 (前端无关, 仅记录) - -V20260512_003 迁移 (两库各一份): -```sql -ALTER TABLE scenic_spot DROP COLUMN icon_svg, DROP COLUMN selling_point; -ALTER TABLE activity DROP COLUMN icon_svg, DROP COLUMN selling_point; -ALTER TABLE service_item DROP COLUMN icon_svg, DROP COLUMN selling_point; -ALTER TABLE product_itinerary_node DROP COLUMN icon_svg, DROP COLUMN selling_point; -``` - -(P0: V001/V002 历史保留不动, 加 forward 删列 V003) - -注: 部署时遇到 MySQL 8 不支持 `DROP COLUMN IF EXISTS` 问题, hotfix PR #2092 改成 `ALTER TABLE x DROP COLUMN a, DROP COLUMN b` 单语句多列形式修复。 diff --git a/changelogs/2026-05/13_audit_admin_product_dead_api_calls.md b/changelogs/2026-05/13_audit_admin_product_dead_api_calls.md deleted file mode 100644 index bed532d..0000000 --- a/changelogs/2026-05/13_audit_admin_product_dead_api_calls.md +++ /dev/null @@ -1,119 +0,0 @@ -# 后端核查回执: 管理端产品页 30+ 死 API 调用清单 - -> **服务**: 后端核查（非接口变更） -> **PR**: 无（后端审计） -> **Issue**: 无 -> **日期**: 2026-05-13 -> **影响范围**: hl-ui 管理端 `src/api/pricing.js` + `src/api/core.js` 中调用 product-v2 旧路径的函数 -> **致**: @mmg - ---- - -## ⚠️ 关键变化 - -你列的"前端有、后端完全没有"5 类清单已逐条 grep 核对。**结论：30 个函数确认是死调用（v2 后端无对应路由），可放心删除**；同时有 14 个函数后端 v2 还在用，**别删**。 - ---- - -## 一、背景 - -你前端反馈了 5 类（旧定价 / 旧批次 / 细粒度行程 / 定制师配置 / 废弃 CRUD）函数怀疑后端没有实现。我用 grep 把 `hl-ui` 中每个函数的 axios URL 抓出来，逐条反查 `hl-product-service-v2` 的 Controller @RequestMapping，再核对 gateway 路由是否切到 v2。结果如下。 - ---- - -## 二、A 类「前端可删」（30 项，确认无后端 v2 路由） - -### pricing.js（20 项 — 旧定价模型完全废弃） - -| 函数 | 前端 URL | 后端 v2 状态 | -|------|---------|-------------| -| getProductPricing | `GET /product/item/{id}/pricing` | ❌ 无路由（v2 已换 pricing-calendar 模型） | -| saveProductPricing | `POST /product/item/{id}/pricing` | ❌ 无路由 | -| getProductCostItems | `GET /product/item/{id}/cost-items` | ❌ 无路由 | -| addProductCostItem | `POST /product/item/{id}/cost-item` | ❌ 无路由 | -| updateProductCostItem | `PUT /product/item/{id}/cost-item/{itemId}` | ❌ 无路由 | -| deleteProductCostItem | `DELETE /product/item/{id}/cost-item/{itemId}` | ❌ 无路由 | -| getProductCustomFees | `GET /product/item/{id}/custom-fees` | ❌ 无路由 | -| addProductCustomFee | `POST /product/item/{id}/custom-fee` | ❌ 无路由 | -| updateProductCustomFee | `PUT /product/item/{id}/custom-fee/{feeId}` | ❌ 无路由 | -| deleteProductCustomFee | `DELETE /product/item/{id}/custom-fee/{feeId}` | ❌ 无路由 | -| getProductExtraCosts | `GET /product/item/{id}/extra-costs` | ❌ 无路由（字段嵌入 ProductRouteSaveReqVO，无独立 URL） | -| addProductExtraCost / update / delete | `*/extra-cost*` | ❌ 无路由 | -| getProductSupplies | `GET /product/item/{id}/supplies` | ❌ 无路由（Service 在但 Controller 未暴露） | -| addProductSupply / update / delete | `*/supplies*` | ❌ 无路由 | -| getInsuranceFeePreview | `GET /product/item/{id}/pricing/insurance-fee-preview` | ❌ 无路由 | -| getGroupQuote | `GET /product/item/{id}/group-quote` | ❌ admin 无（v2 仅 `/internal/product/{id}/group-quote` 内部用） | - -### core.js（10 项） - -| 函数 | 前端 URL | 后端 v2 状态 | -|------|---------|-------------| -| addProduct | `POST /product/item` | ❌ v2 用 `/admin/product/basic` 统一 SaveReqVO | -| updateProduct | `PUT /product/item/{id}` | ❌ 同上 | -| generateShareLink | `POST /product/item/{id}/share-link` | ⚠ v2 有路径但是 `POST /admin/product/{id}/share` — 前端 URL 不对 | -| generateRouteMap | `POST /product/item/{id}/generate-route-map` | ⚠ v2 改 `POST /admin/product/{id}/map/generate-by-amap` | -| getProductLogs | `GET /product/item/{id}/logs` | ⚠ v2 改 `GET /admin/product/{id}/operation-logs` | -| getFolderTree | `GET /product/folder/tree` | ❌ 文件夹模型已废弃 | -| addFolder / update / delete | `/product/folder/*` | ❌ 同上 | -| moveProduct | `PUT /product/item/{id}/move` | ❌ 文件夹移动随之废弃 | - -### batch.js 整文件（旧批次模型） - -| 范围 | 后端 v2 状态 | -|------|-------------| -| `/batch/*` 路由全部 | ❌ 整批迁移到 `/admin/product/{id}/schedules` （新 schedule 模型） | -| 关联面板 `BatchManagementPanel.vue` | 可同步删 | - -### itinerary.js 部分函数（细粒度行程） - -| 函数 | 前端 URL | 状态 | -|------|---------|------| -| 节点级 CRUD（addNode/updateNode/deleteNode） | `/itinerary/node/*` | ❌ v2 无独立节点 CRUD | -| 酒店级 CRUD | `/itinerary/hotel/*` | ❌ v2 无独立 CRUD | -| 餐饮级 CRUD | `/itinerary/dining/*` | ❌ v2 无独立 CRUD | - -注：admin v2 只保留 `saveItinerary` 整树保存 + `addItineraryDay` / `deleteItineraryDay`。 - -### custom.js 整文件（定制师配置） - -| 范围 | 状态 | -|------|------| -| family / staff-config 全部接口 | ❌ VO 还在数据模型但无 Controller 端点 | - ---- - -## 三、B 类「前端别删」（14 项，v2 还在用） - -| 函数 | 后端 v2 路径 | -|------|-------------| -| getProductPage / getProductDetail | `GET /admin/product/page` / `/admin/product/{id}` | -| deleteProduct / copyProduct | `DELETE /admin/product/{id}` / `POST /admin/product/{id}/copy` | -| validatePublish / togglePublish | `POST /admin/product/{id}/validate-publish` / `/publish-toggle` | -| completeDesign | `POST /admin/product/{id}/complete-design` | -| saveBasicInfo | `POST /admin/product/basic` | -| saveItinerary / addItineraryDay / deleteItineraryDay | `PUT /admin/product/{id}/itinerary` 等 | -| saveRoute | `PUT /admin/product/{id}/route` | -| saveSupplement | `PUT /admin/product/{id}/supplement` | -| getFeeDeductionPreview | v2 有保留 | - ---- - -## 四、特别说明 - -- **`generateShareLink` / `generateRouteMap` / `getProductLogs`** 是 ⚠ 类（路径变了但功能在）。建议前端把这三个函数的 URL 改成新路径（见上表），保留函数。 -- **文件夹 + 移动产品**功能 v2 整体废弃。但你前端 UI（`FolderPanel.vue` + 列表页"移动产品"按钮）还在用。**建议前端连同 UI 一起删掉**，因为 v2 的产品组织改用 schedule 维度，不再需要文件夹。 -- **batch.js 整文件**直接删（已被 schedule 替代）。`BatchManagementPanel.vue` 一并删。 - ---- - -## 五、为什么后端不补回来这些 API - -- pricing 旧模型：v2 已重构为 pricing-calendar（按日期+档位定价），旧的"成本项/自定义费/额外费/物资"独立 CRUD 模式已废弃，统一进 schedule 保存 -- 文件夹：v2 产品组织维度变了（主题/版本/档位/schedule），文件夹这个老组织维度无意义 -- 细粒度行程：编辑体验改为整树保存（一次 PUT 全部行程），节点级 CRUD 让数据一致性变难 - -如果你前端在做产品列表的"文件夹分组展示"或"批次管理面板"且必须保留 UI，先告诉我，我评估能不能在 v2 加路由；否则按上面清单删即可。 - ---- - -**附：PR #2166 已部署测试服**（commit d49d6013，10:57:45 完成）。改动是 32 处 `Result<Map>` 改具体 VO + 字典段修正 + 部分 Map 入参改 ReqVO。**字段名跟原 Map 一致，前端契约不变**，等你日常联调中如果 mp wiki/review/wish/transport 4 个接口有反序列化异常立刻反馈我。 diff --git a/changelogs/2026-05/13_fix_product_version_creator_wecom_name.md b/changelogs/2026-05/13_fix_product_version_creator_wecom_name.md deleted file mode 100644 index 6a0418c..0000000 --- a/changelogs/2026-05/13_fix_product_version_creator_wecom_name.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -date: 2026-05-13 -type: backend-improvement -service: hl-product-service-v2 -priority: low -notify: ["@mmg"] -status: verified ---- - -# 产品版本列表「创建人」显示企业微信中文名（与主题列表对齐） - -> **PR**: [#2218](https://git.1814.love:8443/wx/HL/pulls/2218) — 已合并 dev + 部署测试服 -> **Issue**: [#2217](https://git.1814.love:8443/wx/HL/issues/2217) -> **状态**: ✅ **测试服已验证** (api.test.1814.love:9443) — 真 admin token / 网关 / 54 条记录全量回扫通过 - ---- - -## 一、背景 - -`hl-ui` 管理端「产品列表」（即产品版本列表）「创建人」列原本展示**登录账号**（`admin_user.username`，如 `lixiaosong` / `wangxiao`），与同模块「主题列表」（产品线列表）已经在用的**企业微信中文名**（如「小松」「王骁」）不一致，需要对齐。 - -根因（之前老接口逻辑）：`ProductQueryService.enrichCreatedByName` 拿 `Map<Long, String>` 只取 `username`。 -修复（PR #2218 与主题列表 `ProductLineService` 对齐）：改为 `Map<Long, AdminBasicDTO>`，set 时 `StrUtil.blankToDefault(dto.getWechatName(), dto.getUsername())` — **优先用 wechatName（企微中文名），没绑定企微时 fallback username**。 - -仅 1 文件 +12/-3 行：`hl-product-service-v2/src/main/java/com/hulalv/service/admin/ProductQueryService.java`。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 产品分页列表 | GET | `/admin/product/item/list` | 字段值优化 | `data.records[].createdByName` 由 username → wechatName（fallback username） | - -**前端契约 100% 不变**： -- 字段名 `createdByName` 不变 -- 字段类型 String 不变 -- 字段位置在 `data.records[]` 不变 -- 不为 null（要么中文要么 username） - -**前端无需改任何代码** —— 字段值天然变好，渲染层零感知。 - ---- - -## 三、字段语义 - -| 字段 | 改前 | 改后 | -|------|------|------| -| `createdByName` | `admin_user.username`（如 `lixiaosong`） | `admin_user.wechat_name`（如「小松」），无 wechatName 时 fallback `username` | - ---- - -## 四、测试服验证（硬性凭证） - -`GET /admin/product/item/list?page=1&pageSize=200`，Bearer admin token（`admin` / `Admin@123456`），公网网关 `api.test.1814.love:9443`： - -- HTTP 200 / code=200 / total=54 -- **0 条 createdByName=null**（铁律：要么中文要么 username） -- **10 个不同 createdBy 中，8 个解析为企微中文名**，2 个 fallback username（admin、test_admin 这两个测试账号未绑定企微） - -部分映射证据（按用户截图最关心的 lixiaosong 优先列出）： - -| createdBy | createdByName | 出处 | -|---|---|---| -| `2033349910786715649` (username=`lixiaosong`) | **`小松`** ✅（用户截图里 `D260511001` 同账号的版本） | wechatName 生效，与主题列表一致 | -| `2021059720172838914` (username=`wangxiao`) | **`王骁`** ✅ | wechatName 生效 | -| `2046065465288949761` (username=`jiangyulian`) | **`蒋雨莲`** ✅ | wechatName 生效 | -| `2027579942221352962` (username=`mimingguang`) | **`米明光`** ✅ | wechatName 生效 | -| `2033350005166944258` (username=`xulai`) | **`徐莱`** ✅ | wechatName 生效 | -| `1001` | `admin` | 无 wechatName，fallback username（符合预期） | -| `1002` | `test_admin` | 无 wechatName，fallback username（符合预期） | - -lixiaosong 实测明细（用户截图里 lixiaosong 创建的版本现在显示什么）： - -``` -productId=2052568716926681090 productNo=D260508001 name=燕 私人订制 createdByName=小松 -productId=2049468625294708737 productNo=D260429001 name=私人订制 9天8晚... createdByName=小松 -productId=2046109281911996418 productNo=C260420004 name=1111 出生地点... createdByName=小松 -``` - -3/3 都已展示「小松」（企微中文名），改造前会全部展示 `lixiaosong`。 - ---- - -## 五、部署 - -- 测试服 SSH rolling 部署完成（hl-product-service-v2: 8083 + 8183 双实例 ~30s，零停机） -- Nacos `test` namespace 两实例 healthy=true 已确认 - ---- - -## 六、风险与回滚 - -- 风险极低：仅展示字段值优化，无 schema 变更、无前端契约变化、无业务逻辑改动 -- 回滚：reverse PR #2218 即可（1 文件 -12/+3） diff --git a/changelogs/2026-05/13_frontend_bug_admin_product-line-list-search-first-click-no-effect.md b/changelogs/2026-05/13_frontend_bug_admin_product-line-list-search-first-click-no-effect.md deleted file mode 100644 index 3c7ad62..0000000 --- a/changelogs/2026-05/13_frontend_bug_admin_product-line-list-search-first-click-no-effect.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -date: 2026-05-13 -type: frontend-bug -module: admin-product-line-list -priority: high -notify: ["@mmg"] -status: pending ---- - -# 主题列表「点搜索第一回必然不好使，第二回才好使」— 路由守卫自己取消了自己发的请求 - -## 现象 - -管理后台「产品管理 → 主题列表」(`/product/line`)，切换筛选条件（主题类型下拉或关键词）后点「搜索」按钮： - -- **第 1 次点搜索：列表无任何变化**（看起来没反应） -- **第 2 次点同一个搜索：列表才刷新** - -DevTools Network 面板可见：每次点搜索都发出 **2 个 URL 完全相同的请求**（如 `list?keyword=&productType=CORE&page=1&pageSize=20`）： -- 请求 1：`status = (canceled)`，`size = 0.0 kB`，4ms -- 请求 2：`status = 200`，`size = 1.2 kB`，61ms - -100% 必现。 - -## 根因（纯前端，后端无关） - -文件：`hl-ui/src/views/product/line/index.vue` + 通用的 `hl-ui/src/router/index.js` + `hl-ui/src/utils/request.js` - -`handleSearchSubmit` 里干了两件事（顺序）： - -```js -const handleSearchSubmit = debounce(() => { - syncToUrl() // 1. 调 router.replace({ query }) 把筛选条件同步到 URL - resetAndLoad() // 2. 调 fetchList()，axios 发请求 -}, 300) -``` - -而 `router/index.js` 的 `beforeEach` 守卫里每次路由跳转前会调 `clearAllPendingRequests()` 取消所有正在飞的 axios 请求（项目自带的请求清理机制，用来防止路由切换后还在跑的旧请求污染新页面）。 - -**时序冲突**： - -1. `syncToUrl()` 触发 `router.replace`，但 `beforeEach` 是**异步**触发的（微任务/下一拍） -2. `resetAndLoad()` **同步**立即调 axios 发出请求 A，加入 `pendingRequests` Map -3. 这一拍微任务跑到 `beforeEach` → `clearAllPendingRequests()` → **把刚发出的请求 A 取消了**（canceled） -4. 但 `watch(route.query)` 或 `useSearchParams` 的 query 同步逻辑监听到 URL 变化，**又补发了请求 B** -5. 请求 B 这次没有再触发路由跳转，beforeEach 不再跑，请求 B 顺利 200 → 列表刷新 - -**所以用户看到的现象是：点 1 次搜索 → 2 个请求 → 第 1 个被自家路由守卫掐了 → 第 2 个才成功 → 因为防抖 300ms 的存在，用户感觉是"点了没反应"，下一次手动再点才好使。** - -实际上每次都是「第 1 个被取消、第 2 个成功」；但视觉上数据更新有延迟 + canceled 的请求让 loading 状态错乱，**用户主观感受就是「第一次不生效」**。 - -## 修复方案（前端，2 选 1） - -### 改法 A（推荐，最小改动）— `handleSearchSubmit` 里只发请求，不动 URL - -URL 同步不是必须每次都做，可以从"搜索时同步"改成"组件卸载/页面切换时同步"，或者干脆只用 `replaceState` 不触发 vue-router（避免触发 beforeEach）： - -```js -const handleSearchSubmit = debounce(() => { - // syncToUrl() // ❌ 删掉，或下面替换成静默 replaceState - // 静默版（如果还想保留 URL 可分享的能力）： - // const url = new URL(window.location.href) - // Object.entries(searchForm).forEach(([k,v]) => v ? url.searchParams.set(k,v) : url.searchParams.delete(k)) - // window.history.replaceState({}, '', url) // 绕过 vue-router，不触发 beforeEach - resetAndLoad() -}, 300) -``` - -`window.history.replaceState` 不会触发 vue-router 的 `beforeEach`，自然不会触发 `clearAllPendingRequests`。 - -### 改法 B — `syncToUrl()` 后等 router.replace 完成的 Promise 再 `resetAndLoad()` - -```js -const handleSearchSubmit = debounce(async () => { - await syncToUrl() // 让 router.replace 走完 beforeEach（此时 pendingRequests 是空的，cancel 啥都没影响） - resetAndLoad() // 这次发出的请求不会被自己取消 -}, 300) -``` - -需要 `syncToUrl()` 返回 `router.replace(...)` 的 Promise。 - -### 改法 C（不推荐）— 让 `clearAllPendingRequests` 不在 beforeEach 跑 - -这是改通用 request 拦截器，会影响所有页面的路由切换清理逻辑，风险大，**不推荐**。 - -## 推荐方案 - -**改法 A**：`handleSearchSubmit` 内不用 vue-router 改 URL，直接 `window.history.replaceState` 静默同步。改动局限在 `product/line/index.vue` 一个文件，零副作用。 - -## 顺手检查 - -同一个团队规律：项目中其他列表页凡是用了「点搜索 → syncToUrl → fetchList」的双步模式都可能踩这个坑。建议 grep `syncToUrl` 找出所有调用点，统一改成方案 A 的写法。常见嫌疑列表： - -- `views/order/list`（订单列表） -- `views/order-v2/list`（订单管理 v2） -- `views/product-v2/list`（产品 v2 列表） -- `views/customer/list`（客户管理） -- `views/agency/list`（公司管理） - -如果上述页面也有「点搜索第一次不灵」的反馈，根因 100% 一样。 - -## 验证清单（前端改完自测） - -- [ ] 进入「主题列表」，切换主题类型下拉 → 点搜索 1 次 → 列表立即刷新（Network 只有 1 个请求且 200） -- [ ] 输入关键词 → 点搜索 1 次 → 列表立即刷新 -- [ ] 点「重置」按钮 → 列表恢复全量 -- [ ] URL query 仍能正确反映当前筛选条件（用于分享/刷新保持状态） -- [ ] 浏览器前进/后退键能恢复对应筛选条件 -- [ ] 顺手验证：上面"顺手检查"列出的 5 个嫌疑列表页是否同样存在双请求，如有一并修 - -## 后端无需任何改动 - -后端 `GET /admin/product-line/list` 接口本身正常，2 个请求带的参数也都正确，问题完全在前端搜索按钮的实现 + 路由守卫的清理时序冲突。这条 changelog 只为通知前端修。 - -@mmg 看下 `hl-ui/src/views/product/line/index.vue` 的 `handleSearchSubmit`，按改法 A 改即可，预计 P1 — 影响所有列表页搜索体验。 diff --git a/changelogs/2026-05/13_frontend_bug_admin_product-v2-quick-understand-node-no-highlights-prefill.md b/changelogs/2026-05/13_frontend_bug_admin_product-v2-quick-understand-node-no-highlights-prefill.md deleted file mode 100644 index 2301bda..0000000 --- a/changelogs/2026-05/13_frontend_bug_admin_product-v2-quick-understand-node-no-highlights-prefill.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -date: 2026-05-13 -type: frontend-bug -module: admin-product-v2-supplement -priority: medium -notify: ["@mmg"] -status: pending ---- - -# 设计产品「产品卖点 → 快速理解」加入游玩项目后,节点描述未自动回显「项目亮点」 - -## 现象 - -正式环境 (admin.1814.love) 复现: - -1. **资源管理 → 游玩项目管理** 编辑「巴尔虎马之舞实景演绎」, 「项目亮点」字段已填写: `"百马奔腾的视觉震撼,草原文化的动态浓缩。"` -2. **产品管理 → 设计产品**(私人订制类型, 编辑路径 `/product/edit?id=2884932124199674426`) -3. 第 5 步「补充信息」→ 左侧「产品卖点」→「快速理解」→ 加入游玩项目「巴尔虎马之舞实景演绎」(标签:活动) -4. **每个节点下的「节点描述」输入框是空白**(placeholder「节点描述」) - -期望: 节点描述自动回显该游玩项目的「项目亮点」(`百马奔腾的视觉震撼…`), 让用户不用手抄一遍。 -实际: 空白。 - -## 根因(纯前端,后端无关) - -经 `/@ba` 调研,后端数据链路完整,锅在前端: - -### 后端确认无问题 - -1. **游玩项目实体** `hl-resource-service/.../entity/ServiceItem.java:53` 已有 `highlights` 字段。 -2. **游玩项目列表接口** `GET /admin/service/items` → `ServiceItemListVO`(`hl-resource-service/.../vo/ServiceItemListVO.java`)字段列表里**第 52 行就是 `highlights`** ✅。也就是说前端拉列表/详情时, 后端**已经把项目亮点吐过去了**, 没有漏字段。 -3. **产品补充信息保存接口** 把 `quickUnderstand` 当 JSON 透传存到 `product_supplement.quick_understand` 字段, 后端不解析节点结构, 节点描述写啥后端就存啥。 -4. **产品详情接口** 原样吐 JSON, 节点描述存的什么就回什么。 - -结论: 后端列表接口已返回 `highlights`, 但**前端在「添加节点到快速理解」时, 没有把 `service.highlights` 复制到节点对象的描述字段**(节点 JSON 里那个 `description` / `desc` / 不管叫啥的字段), 所以保存到 DB 时该字段就是空字符串, 编辑回显当然也空。 - -## 修法(前端,1 处改动) - -在「产品卖点 → 快速理解」添加节点的逻辑里, 当来源是游玩项目(service_item)时, 把 `service.highlights` 写进节点的描述字段作为默认值: - -```js -// 大致逻辑示意 - 实际字段名以前端 quickUnderstand 节点 JSON schema 为准 -function addServiceItemNode(service) { - quickUnderstand.nodes.push({ - serviceId: service.serviceId, - name: service.name, - image: service.image, - type: 'service-item', - description: service.highlights || '', // ← 关键:用 highlights 预填 - }) -} -``` - -用户仍然可以手动改这个描述框(因为前端是 input 不是只读), 这只是**默认值**。 - -## 验证清单(前端改完自测) - -- [ ] 新建私人订制产品 → 第 5 步「补充信息」→「产品卖点」→「快速理解」→ 加入任一有 `highlights` 的游玩项目 → 节点描述自动出现项目亮点文本 -- [ ] 加入一个 `highlights` 为空的游玩项目 → 节点描述空(占位符正常显示), 不报错 -- [ ] 用户手动改了节点描述后保存 → 重进编辑页, 显示用户改后的内容(而非再被 highlights 覆盖) -- [ ] 删除节点重新加同一个游玩项目 → 默认值再次填入 -- [ ] 已存在的历史产品(节点描述本来就是空的)进入编辑: 视产品策略, 建议**不**自动用 highlights 回填历史空值(否则可能覆盖用户故意留空的意图), 仅对**新加入的节点**做预填 - -## 后端无需任何改动 - -`ServiceItemListVO.highlights` 已返回, `product_supplement.quick_understand` 是 JSON 透传, 后端没有补全逻辑也不该有(节点描述用户可改, 不能强行 join 覆盖)。这条 changelog 只为通知前端修。 - -@mmg 看下 hl-ui 里产品卖点(快速理解)添加游玩项目节点的组件, 优先级 P2 — 不阻塞功能, 但每加一个项目都要手抄一遍亮点, 体验差。 diff --git a/changelogs/2026-05/13_improve_contract_supp_clause_size_2000_to_5000.md b/changelogs/2026-05/13_improve_contract_supp_clause_size_2000_to_5000.md deleted file mode 100644 index e9c47be..0000000 --- a/changelogs/2026-05/13_improve_contract_supp_clause_size_2000_to_5000.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -date: 2026-05-13 -type: backend-improvement -service: hl-order-service-v2 -priority: medium -notify: ["@mmg"] -status: verified ---- - -# 12301 合同补充约定字数上限 2000 → 5000 (已测试服验证) - -> **PR**: [#2187](https://git.1814.love:8443/wx/HL/pulls/2187) — 已合并 dev + 部署测试服 -> **Issue**: [#2186](https://git.1814.love:8443/wx/HL/issues/2186) -> **状态**: ✅ **测试服已验证** (api.test.1814.love:9443) — 3/3 case 端到端通过 - ---- - -## 一、背景 - -`hl-ui` 管理端「编辑补充约定模板」弹窗目前 `maxlength=2000`,实际旅行社业务里 12301 旅游合同补充约定动辄超过 2000 字符,卡用户。 - -调研结论: -- **12301 国家旅游局 API 公开/内部文档均未约束 supplementaryClause 字段长度**(项目内 `35_合同对接12301国家旅游局API需求规格.md` 通篇没列字段长度;搜索 tourage.cn / 12301 字段长度均无公开资料) -- 数据库 `contract.supplementary_clause` / `contract_scheme.supplementary_clause` 是 `TEXT`(~21000 中文字符),底层不卡 -- 历史 12301 错误码 `errcode=301025` 是换行符问题(已 `replace("\n", " ")` 净化),没遇到过长度被拒 -- **2000 是当初开发期保守值**,本次放宽到 5000,留安全垫给 12301 未知上限 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 创建合同方案 | POST | `/admin/contract/scheme` | 校验放宽 | `supplementaryClause` 字数上限 2000 → 5000 | -| 2 | 更新合同方案 | PUT | `/admin/contract/scheme/{schemeId}` | 校验放宽 | 同上 | -| 3 | 创建合同 | POST | `/admin/contract/create`(及其同族) | 校验放宽 | `supplementaryClause` 字数上限 2000 → 5000 | -| 4 | 报备合同(SYNC) | POST | `/admin/contract/report`(及其同族) | 校验放宽 | `supplementaryClause` 字数上限 2000 → 5000 | - -**未变接口**(已有行为不变): -- `POST/PUT /admin/contract/clause-template`(补充约定模板 CRUD):后端 `ClauseTemplateRequest.content` 本来就没 `@Size` 限制,DB TEXT 兜底。前端弹窗当前 2000 字限制是**前端自己加的**,需前端同步改。 - ---- - -## 三、字段约束变化 - -| DTO 字段 | 原约束 | 新约束 | -|---|---|---| -| `ContractSchemeRequest.supplementaryClause` | `@Size(max=2000)` | `@Size(max=5000)` | -| `CreateContractRequest.supplementaryClause` | `@Size(max=2000)` | `@Size(max=5000)` | -| `ReportContractRequest.supplementaryClause` | `@Size(max=2000)` | `@Size(max=5000)` | - -错误 message 同步从「补充约定/条款不能超过2000个字符」改为「...不能超过5000个字符」。 - ---- - -## 四、前端待办(@mmg) - -请 hl-ui 同步把以下输入框 `maxlength=2000` → `maxlength=5000`: - -1. **「编辑补充约定模板」弹窗**(模板内容输入框)— 截图见 Issue #2186 -2. **合同方案管理页**——「补充条款」输入框(POST/PUT `/admin/contract/scheme` 调用方) -3. **创建合同 / 报备合同表单**——「补充约定内容」输入框 - -字数计数器 `2000/2000` 显示也要同步改 `5000/5000`。 - -> 不改前端的话:用户能勾选 ≤2000 字符的旧模板,但不能写超过 2000 字符的内容(前端仍卡);后端能接 5000,前端是瓶颈。 - ---- - -## 五、测试服已验证 (硬性凭证) - -`POST /admin/contract/scheme`,Bearer admin token: - -``` -A. supplementaryClause = "夏" × 4500 字符 - → HTTP 200 code=200 success schemeId=2054442503913779201 ✓ (原 max=2000 会拦) - -B. supplementaryClause = "x" × 5001 字符 - → HTTP 200 code=400 message="补充条款不能超过5000个字符" ✓ (@Size(max=5000) 生效) - -C. supplementaryClause = "中" × 2001 字符 - → HTTP 200 code=200 success schemeId=2054442506648465410 ✓ (原 max=2000 会拦) - -[CLEANUP] DELETE /admin/contract/scheme/2054442503913779201 → HTTP 200 -[CLEANUP] DELETE /admin/contract/scheme/2054442506648465410 → HTTP 200 -``` - ---- - -## 六、风险与回滚 - -- **风险**:12301 远端实际可能有 supplementaryClause 上限(未知),5000 字以内若被 12301 拒绝,会在 12301 调用时报 4xx/errcode 错误(不会损坏本地数据,仅合同上报失败)。 -- **回滚**:3 处 `@Size(max=5000)` 改回 `2000` 即可,无 schema 变更、无数据兼容性问题。 -- 若线上出现 12301 实际拒绝长 supplementaryClause 的 errcode,据实再调小。 diff --git a/changelogs/2026-05/13_improve_product_v2_mp_price_calendar_default_month.md b/changelogs/2026-05/13_improve_product_v2_mp_price_calendar_default_month.md deleted file mode 100644 index 1fb6abc..0000000 --- a/changelogs/2026-05/13_improve_product_v2_mp_price_calendar_default_month.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -date: 2026-05-13 -type: backend-improvement -service: hl-product-service-v2 -priority: high -notify: ["@mmg"] -status: verified ---- - -# C端价格日历支持月份缺省回退最近可售月, 响应新增 `month` 字段 (已测试服验证) - -> **PR**: [#2172](https://git.1814.love:8443/wx/HL/pulls/2172) — 已合并 dev + 部署测试服 -> **Issue**: [#2167](https://git.1814.love:8443/wx/HL/issues/2167) -> **状态**: ✅ **测试服已验证** (api.test.1814.love:9443) — 10/10 case 端到端通过 - ---- - -## ⚠️ 关键变化 - -### 入参契约放宽 - -`/mp/product/{id}/price-calendar` 接口的 `month` / `startDate` / `endDate` 三个参数**全部改为可选**： - -- 三参数全空 → 后端**自动定位**"从今天起最近一个有可售日期所在月份"并返回该月日历。 -- 旧调用方（detail.js / confirm.js / supplement.js 等传 month 或 startDate+endDate）**行为完全不变**。 - -### 响应新增字段 - -`MpPriceCalendarRespVO` 新增 `month: yyyy-MM` 字段，前端缺省调用时**必须**用它来渲染日历头/切换上下月。 - -```json -{ - "month": "2026-07", // 新增,服务端实际返回的月份;无可售时为 null - "days": [ ... ] // 既有结构不变 -} -``` - -无可售日时 `month = null`, `days = []`,前端可展示"暂无可售日期"。 - ---- - -## 一、背景 - -前端两个场景下不知道该传哪个月份： -1. 用户首次进入产品详情页，希望默认展示"最近可售月份"。 -2. 已上架产品的最近可售日不一定是本月（可能近月全过期/全无库存）。 - -原来前端只能先调 `/earliest-available-date` 再拿月份回调 `/price-calendar`，多一次 RT。本次改造后**一次接口即可拿到最近可售月日历 + 月份字段**。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | C端价格日历 | GET | `/mp/product/{id}/price-calendar` | 入参可选 + 响应新增字段 | 三日期参数全可选；响应新增 `month` | - ---- - -## 三、接口详情 - -### 1. C端价格日历 `GET /mp/product/{id}/price-calendar` - -**入参 VO**: `MpPriceCalendarReqVO` -**响应 VO**: `MpPriceCalendarRespVO` - -#### 入参（Query） - -| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------|------| -| `month` | Query | String | ❌ 改为可选 | yyyy-MM | 与 startDate/endDate 三选一可全空 | -| `startDate` | Query | String | ❌ 改为可选 | yyyy-MM-dd | 若传必须与 endDate 同月配对 | -| `endDate` | Query | String | ❌ 改为可选 | yyyy-MM-dd | 同上 | - -**入参组合规则**： - -| 组合 | 行为 | -|------|------| -| `startDate` + `endDate` 都非空 | 解析为它们所在月份范围（必须同月，否则抛 410109） | -| 仅 `month` 非空 | 解析为该月范围 | -| **三者全空** | **新行为**：自动定位"最近可售月" | -| 单传 `startDate` 或 `endDate` | 仍抛 410108 | -| `month` 格式非法（如 `2026/07`、`abc`、`2026-13`） | 仍抛 410108 | - -#### 出参 `Result<MpPriceCalendarRespVO>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| `month` | String | **新增**。服务端实际返回的月份 `yyyy-MM`；无可售日时为 `null` | -| `days` | List | 既有结构不变（每日 date / priceType / adultPrice / childPrice / isSelectable / remainStock） | - -#### 产品类型分流（全部 3 类覆盖） - -| 类型 | 最近可售日来源 | -|------|--------------| -| CORE / CUSTOM | `product_price_calendar` 全档位齐全的最早未来日 | -| GROUP（小蒙马） | `group_tour_batch` 状态 `ENROLLING/NEARLY_FULL` 且报名未截止的最早出发日 | - -#### 请求示例 - -**A. 缺省入参（新行为）**： -``` -GET /mp/product/2045018534152478721/price-calendar -→ { "code":200, "data":{ "month":"2026-05", "days":[ {...30 条...} ] } } -``` - -**B. 显式 month（旧行为，兼容）**： -``` -GET /mp/product/2045018534152478721/price-calendar?month=2026-07 -→ { "code":200, "data":{ "month":"2026-07", "days":[ ... ] } } -``` - -**C. 缺省入参 + 产品完全无可售**： -``` -GET /mp/product/{noSellable}/price-calendar -→ { "code":200, "data":{ "month":null, "days":[] } } -``` - -#### 错误码 - -| code | 触发场景 | 文案 | -|------|---------|------| -| 410108 | 单边 startDate / 单边 endDate / month 格式非法 | 参数格式错误：month 需为 yyyy-MM，或 startDate/endDate 必须同月成对且为 yyyy-MM-dd | -| 410109 | startDate / endDate 跨月 | startDate(X) 与 endDate(Y) 必须在同一个月份内 | -| 404 | 产品不存在 / 已下架 | 产品不存在或已下架 | - -> **顺带的安全收益**：本次把产品可见性校验 `getVisibleProductOrThrow` 从"缓存命中后"提前到"参数解析前"。**堵住"产品下架但缓存内日历仍可读 5 分钟"的口子**。对前端无可见影响（响应内容不变），但下架产品立即返回 404。 - ---- - -## 四、测试服验证（硬性凭证，10/10 端到端通过） - -测试环境 `api.test.1814.love:9443`，今天 2026-05-13。 - -| # | 用例 | 入参 | 期望 | 实测 | -|---|------|------|------|------| -| 1 | CORE 缺省入参 | pid=2045018534152478721 | month 非 null + days > 0 | ✓ month=2026-05, days=30 | -| 2 | CORE 显式 month=2026-07 | month=2026-07 | month=2026-07 | ✓ | -| 3 | CORE startDate+endDate 同月 | 2026-07-10 ~ 2026-07-20 | month=2026-07 | ✓ | -| 4 | **CUSTOM 缺省入参** | pid=2043696016590327809 | month 非 null | ✓ month=2026-07, days=31 | -| 5 | **GROUP 缺省入参** | pid=2044306857534636034 | month 非 null | ✓ month=2026-07, days=5 | -| 6 | 跨月异常 | startDate=2026-07-25&endDate=2026-08-05 | 410109 | ✓ | -| 7 | 单边 startDate | startDate=2026-07-15 | 410108 | ✓ | -| 8 | 单边 endDate | endDate=2026-07-15 | 410108 | ✓ | -| 9 | month 格式错 | month=2026/07 | 410108 | ✓ | -| 10 | 不存在产品 + 缺省入参 | pid=999999 | 404 visible 提前 | ✓ | - -本地单测（hl-product-service-v2 全模块）1192/1192 全绿。 - ---- - -## 五、前端调用建议 - -1. **首次进入产品详情页**：直接调 `/mp/product/{id}/price-calendar` **不传任何参数**，拿响应 `month` 字段渲染日历头。 -2. **用户切换上/下月**：传 `month=yyyy-MM` 显式查询（与新行为不互斥）。 -3. **响应 `month === null`**：展示"该产品暂无可售日期"。 -4. **旧代码不必立即改**：传 month / startDate+endDate 的旧逻辑完全兼容，按各自节奏迁移即可。 - ---- - -## 六、缓存 - -- 内容仍按 `mp:product:price-calendar:{productId}:{yyyy-MM}` 月份 key 缓存，5 分钟 TTL。 -- 缺省入参时多一次 earliest 查询（不缓存，廉价、随时间变化）。 -- 无可售月（`month=null`）不写缓存。 diff --git a/changelogs/2026-05/14_backend_admin_amap-poi-proxy-ready-replace-frontend-direct.md b/changelogs/2026-05/14_backend_admin_amap-poi-proxy-ready-replace-frontend-direct.md deleted file mode 100644 index bc35711..0000000 --- a/changelogs/2026-05/14_backend_admin_amap-poi-proxy-ready-replace-frontend-direct.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -date: 2026-05-14 -type: backend-feature -module: admin-amap-poi-proxy -priority: low -backend_pr: ["#2253", "#2259", "#2261", "#2264"] -backend_issue: "#2249" -notify: ["@mmg"] -status: backend-ready-but-frontend-chose-self-fix -related: ["12_frontend_bug_admin_mappicker-citylimit-blocks-cross-city-search.md"] ---- - -> ⚠️ **2026-05-14 更新**:mmg 决定**前端继续直连高德, 不切到本接口**, 自行修复 citylimit 锁城 BUG。后端接口**已上线测试服并保留备用**(代码不删, nacos key 不撤), 以备未来需要"统一入口/统一限流/key 收回"时再启用。本 changelog 不再要求 mmg 切接口, 只作技术档案。 - -# 后端代理高德 POI 搜索接口已就绪 — 前端可切换不再直连高德 - -## TL;DR - -后端新增 2 个 admin 接口代理高德 POI 搜索, **citylimit 后端固定 false 不可改**, 解决多次复发的「跨盟市/跨省搜不到 POI」 BUG (`citylimit:true` 锁城市)。 - -测试服已真测通过(`阿尔山`/`故宫` 跨盟市/跨省都返). 前端 `PoiAutocomplete.vue` / `MapPicker.vue` 两个组件可以删 `AMap.AutoComplete` / `AMap.PlaceSearch` 直连, 改调本接口。 - -## 接口契约 - -### 1. 输入提示 (下拉联想, 替代 `AMap.AutoComplete`) - -``` -GET /admin/amap/poi/inputtips - ?keywords=阿尔山 必填, 用户输入关键字 (空白 returns 400 关键字不能为空) - &city=呼伦贝尔 可选, 仅影响排序权重, 不约束搜索范围 - &type= 可选, 高德 POI 类型代码 (typecode 多个逗号分隔) - -Headers: Authorization: Bearer {admin_token} -``` - -返回(真实样本): - -```json -{ - "code": 200, "message": "成功", - "data": [ - { - "id": "B01E20023T", - "name": "阿尔山站", - "district": "内蒙古自治区兴安盟阿尔山市", - "address": "兴林路附近", - "lng": 119.947575, "lat": 47.172702, - "adcode": "152202", "typecode": "150200" - }, - { "name": "阿尔山伊尔施机场", "district": "内蒙古自治区兴安盟阿尔山市", "lng": 119.91948, "lat": 47.311868, "adcode": "152202", "typecode": "150104" }, - { "name": "阿尔山", "district": "内蒙古自治区呼和浩特市回民区", "address": "成吉思汗西街101号慧谷·蓝庭", "lng": ..., "lat": ... } - ] -} -``` - -### 2. 关键字搜索 (回车精确搜, 替代 `AMap.PlaceSearch`) - -``` -GET /admin/amap/poi/search - ?keywords=故宫 必填 - &city= 可选 - &page=1 可选, 默认 1, 范围 [1,100] - &size=20 可选, 默认 20, 上限 25 (高德硬限制, >25 returns 400) -``` - -返回: - -```json -{ - "code": 200, "message": "成功", - "data": { - "total": 100, - "page": 1, "size": 20, - "list": [ - { - "id": "B000A8UIN8", - "name": "故宫博物院", - "district": "北京市东城区", - "address": "景山前街4号", - "lng": 116.397029, "lat": 39.917839, - "adcode": "...", "typecode": "..." - }, - { "name": "故宫博物院-午门", "district": "北京市东城区", ... } - ] - } -} -``` - -> 注: `district` 字段两接口都是**完整省市区路径** (含直辖市去重), 直接显示给用户即可。 - -## 前端改造点(逐文件) - -### `hl-ui/src/components/PoiAutocomplete.vue` (第 100-104 行 + 130 行) - -```js -// 删除 -autoComplete = new window.AMap.AutoComplete({ - city: props.city || '呼伦贝尔', - citylimit: true, - datatype: 'all', -}) -async function doAutoComplete(query) { - ... - autoComplete.search(query, (status, result) => {...}) -} - -// 替换 (新增 src/api/amap.js 包一层) -import { poiInputtips } from '@/api/amap' - -async function doAutoComplete(query) { - loading.value = true - try { - const list = await poiInputtips({ keywords: query, city: props.city || '' }) - options.value = list.slice(0, 15).map((tip) => ({ - label: tip.name, - value: tip, // 整个对象往上传, 含 lng/lat/district/adcode/typecode - fullPath: tip.district || '', - })) - } finally { - loading.value = false - } -} -``` - -### `hl-ui/src/components/MapPicker.vue` (第 360-431 行 + 444-448 行) - -```js -// 删除两段 -new window.AMap.AutoComplete({...}) -new window.AMap.PlaceSearch({...}) - -// 删除第 444-448 行 filteredPois 二次过滤 (后端已不锁城, 全国结果都该展示) - -// 替换为 -import { poiInputtips, poiSearch } from '@/api/amap' - -// AutoComplete (输入框联想) → poiInputtips({keywords, city}) -// PlaceSearch (回车精确搜) → poiSearch({keywords, city, page:1, size:20}) -``` - -### `hl-ui/src/views/product/edit/components/itinerary/RouteTagBar.vue` (第 26-28/79/105 行) - -```js -// 删除 productCity computed (不再传 city 锁范围) -const productCity = computed(() => store.productData.itinerary?.[0]?.gatherPlace?.cityName || '呼伦贝尔') - -// PoiAutocomplete 上的 :city="productCity" 也删掉, 不传 city 即全国搜 -<PoiAutocomplete :value="..." placeholder="..." size="small" - - :city="productCity" - :disabled="store.isReadonly" @update:value="..." /> -``` - -### 地图渲染部分**保留**前端 JS SDK - -`MapPicker.vue` 里 `new AMap.Map()` / Marker / 逆地理编码 (`AMap.Geocoder`) 仍前端 JS SDK 直连, 渲染必须前端。前端 JS API key (VITE_AMAP_KEY / sys_frontend_config.AMAP_KEY) 保留不动, 只是搜索这块走后端。 - -### 新建 `hl-ui/src/api/amap.js` - -```js -import request from '@/utils/request' - -export function poiInputtips(params) { - return request.get('/admin/amap/poi/inputtips', { params }).then(r => r.data) -} - -export function poiSearch(params) { - return request.get('/admin/amap/poi/search', { params }).then(r => r.data) -} -``` - -## 测试服真测结果(已 PASS, 前端可放心切) - -| 验收 | 结果 | -|---|---| -| `inputtips?keywords=阿尔山` 跨盟市 | ✅ 10 条, 9 条非呼伦贝尔, 含「阿尔山站/阿尔山伊尔施机场/阿尔山北站/阿尔山服务区」 | -| `search?keywords=故宫` 跨省 | ✅ total=100, 返「故宫博物院/午门/西南角楼/景仁宫/慈宁宫」全在「北京市东城区」 | -| `inputtips?keywords=` (空) | ✅ 业务码 400 「关键字不能为空」 | -| `search?size=30` (>25) | ✅ 业务码 400 「每页大小不能超过 25(高德硬限制)」 | - -测试服环境: `https://api.test.1814.love:9443/admin/amap/poi/...`, Bearer token 走管理后台登录拿到即可。 - -## 灰度建议 - -1. **后端已上线 dev 测试服** (4 个 PR 已合并) -2. **建议先切 `PoiAutocomplete.vue`** (1 个组件 / 1 个页面 = 行程编排「开始/结束」), 验证「阿尔山市」「呼伦贝尔学院」等跨地搜索正常 -3. **再切 `MapPicker.vue`** (5 个资源 EditModal: 景区/酒店/餐厅/活动/服务), 验证「阿尔山白狼峰景区」搜得到 -4. 浏览器 Network 看搜索请求 URL **应是 `/admin/amap/poi/...`**, 不应再有 `restapi.amap.com` 直接调用 - -## 关闭老 BUG - -本次后端实现彻底解决 `12_frontend_bug_admin_mappicker-citylimit-blocks-cross-city-search.md` 的根因 — 前端不再有 `citylimit` 这个开关, 业务上根本不会再被锁城。前端切完后老 changelog 可以 status: closed。 - -## 不在本 PR 范围 - -- 地图渲染 (`new AMap.Map()` / Marker) 仍前端 JS SDK -- 行政区划查询 / 驾车路线 / 天气 / 静态地图 / 地理编码 都已有后端实现, 不动 - -@mmg 接口可用了, 请按上面 4 个文件改造点替换前端代码。问题随时找我。 diff --git a/changelogs/2026-05/14_feat_admin_activity_season_admin_crud.md b/changelogs/2026-05/14_feat_admin_activity_season_admin_crud.md deleted file mode 100644 index b27a79c..0000000 --- a/changelogs/2026-05/14_feat_admin_activity_season_admin_crud.md +++ /dev/null @@ -1,149 +0,0 @@ -# resource: 加 ActivitySeasonController admin CRUD (补 #2232 漏做配置入口) - -> **服务**: hl-resource-service (端口 8082) -> **PR**: #2262 -> **Issue**: #2257 -> **日期**: 2026-05-14 -> **影响范围**: 管理端 游玩项目编辑 季节内容配置（admin 前端需加同款"季节内容" tab） - ---- - -## ⚠️ 关键变化 - -PR #2232 (游玩项目季节过滤+节点标签) 加了 activity_season 表 + Entity + Mapper + ListVO 装配, 但**漏做 admin 配置入口** — 运营无处填数据 → /admin/activity/items 接口 seasons 字段恒返 `[]` → 前端弹窗无季节标签。 - -本次补全, 对照 ScenicSeasonController 同款实现 admin CRUD。 - ---- - -## 接口清单 - -| # | 接口 | 方法 | 路径 | -|---|------|------|------| -| 1 | 获取游玩项目全部季节内容 | GET | `/admin/activity/item/{activityId}/seasons` | -| 2 | 保存/更新季节内容 (upsert) | PUT | `/admin/activity/item/{activityId}/season/{seasonType}` | -| 3 | 删除季节内容 | DELETE | `/admin/activity/item/{activityId}/season/{seasonType}` | - -路径风格走 `/admin/activity/item/` 前缀对齐 ActivityController 现有风格 (scenic 走 `/spot/`)。 - ---- - -## 接口详情 - -### 1. 获取季节内容 `GET /admin/activity/item/{activityId}/seasons` - -**响应**: `Result<List<ActivitySeasonVO>>` - -```json -{ - "code": 200, - "data": [ - { - "seasonId": 2054831396190347266, - "activityId": 2023705891743739905, - "seasonType": "spring", - "seasonName": "春日", - "monthStart": 3, - "monthEnd": 5, - "description": "春日体验", - "highlights": "春日亮点测试", - "playGuide": "<p>春日攻略</p>", - "tips": "春日注意", - "coverMaterialId": null, - "bannerMaterialIds": null, - "videoMaterialIds": null, - "createdAt": "2026-05-14T15:43:00", - "updatedAt": "2026-05-14T15:43:00" - } - ] -} -``` - -无数据返 `data: []`。 - -### 2. 保存/更新季节内容 `PUT /admin/activity/item/{activityId}/season/{seasonType}` - -**入参** `SeasonSaveRequest`: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| seasonName | String | ❌ | 季节别名("赏秋季"/"冰雪季") | -| monthStart | Integer | ✅ | 开始月份 1-12 | -| monthEnd | Integer | ✅ | 结束月份 1-12 (可跨年如冬季 12-2) | -| description | String | ❌ | 该季节简介 | -| highlights | String | ❌ | 该季节亮点 (短文案, ≤500 字) | -| playGuide | String | ❌ | 该季节游玩攻略 (富文本) | -| tips | String | ❌ | 该季节注意事项 | -| coverMaterialId | Long | ❌ | 季节封面素材 ID | -| bannerMaterialIds | List<Long> | ❌ | 季节轮播图素材 ID 列表 | -| videoMaterialIds | List<Long> | ❌ | 季节视频素材 ID 列表 | - -**幂等**: 由 (activity_id, season_type) 唯一约束保证, 已存在 → 更新, 否则 → 插入。 - -`seasonType` 枚举: `spring/summer/autumn/winter` (其他值返 320401 ACTIVITY_SEASON_TYPE_INVALID)。 - -### 3. 删除 `DELETE /admin/activity/item/{activityId}/season/{seasonType}` - -**响应**: `Result<Void>` 成功返 `code=200, data=null`。 - ---- - -## 数据库行为 - -- 表: `activity_season` (PR #2232 V20260514_001 已建) -- 雪花 ID 主键 -- 上 (activity_id, season_type) 唯一约束保证幂等 -- updated_at 字段自动刷新 - ---- - -## 边界 - -- activityId 不存在 → 404 (校验 activity 主表存在) -- seasonType 非 spring/summer/autumn/winter → 320401 -- monthStart > monthEnd 在冬季跨年场景合法 (如 12-2) -- 删除不存在的 season → 静默成功 (幂等) - ---- - -## 测试服已验证 (round-trip PASS) - -``` -selected activityId: 2023705891743739905 (满洲里草原篝火晚会) -GET seasons (初): [] ✓ -PUT season/spring (highlights="春日亮点测试"): 200, seasonId 返回 ✓ -GET seasons (中): 1 条 spring ✓ -GET /admin/activity/items records[X].seasons: ["spring"] (联动 list) ✓ -DELETE season/spring: 200 ✓ -GET seasons (终): [] ✓ -``` - ---- - -## 前端待补 (@mmg) - -游玩项目编辑页加同款"季节内容" tab (对照景区编辑页), 调上面 3 个 admin API CRUD 4 季内容。运营配数据后, `/admin/activity/items` 接口的 `seasons` 字段才会有数据, `seasonHighlights` (PR #2269) 才会非空。 - ---- - -## 不影响范围 - -- **仅影响**: 管理端游玩项目维护 (新增 admin 路径) + 数据基础供 PR #2269 / #2271 季节回落 -- **零影响**: 小程序 C 端、订单、价格、算价 - ---- - -## 相关历史 PR - -| PR | Issue | 说明 | -|----|-------|------| -| #2234 | #2232 | 游玩项目季节过滤 + 节点季节标签 (但漏做 admin 入口) | -| #2229 | #2227 | 景区同款 + ScenicSeasonController (对照范本) | -| **#2262** | **#2257** | **本 PR**: 补 ActivitySeasonController | - ---- - -## 相关文档 - -- Issue: [wx/HL#2257](https://git.1814.love:8443/wx/HL/issues/2257) -- PR: [wx/HL#2262](https://git.1814.love:8443/wx/HL/pulls/2262) diff --git a/changelogs/2026-05/14_feat_admin_auth_refresh_token.md b/changelogs/2026-05/14_feat_admin_auth_refresh_token.md deleted file mode 100644 index 2d588bf..0000000 --- a/changelogs/2026-05/14_feat_admin_auth_refresh_token.md +++ /dev/null @@ -1,204 +0,0 @@ -# auth: admin 登录加 refresh token 双令牌轮转机制 - -> **服务**: hl-user-service (端口 8081) + hl-gateway (端口 8080) -> **PR**: #2285 + hotfix #2287 -> **Issue**: #2283 -> **日期**: 2026-05-14 -> **影响范围**: 管理后台所有调用方(hl-ui)的登录态管理 - ---- - -## ⚠️ 关键变化 - -**之前**: admin access token 固定 7 天过期,无刷新机制,过期 → 强制重登。 - -**现在**: -- **access token TTL 改为 2 小时**(可被环境变量 `ADMIN_ACCESS_TTL` 覆盖) -- 新增 **refresh token TTL 7 天** -- 新增 `POST /admin/auth/refresh` 用 refresh 换新 access(refresh 一次性轮转防重放) -- 登出时后端自动清两套 token - -**前端必做**:接 axios 401 拦截器自动调 `/admin/auth/refresh` 续期,否则用户 2h 后被强制登出。 - ---- - -## 接口变化 - -### 1. 登录响应新增 3 字段 - -`POST /admin/auth/login`、`POST /admin/auth/wechat/verify-2fa`、`POST /admin/auth/switch-role`、`GET /admin/auth/wechat-qr/status`、`GET /admin/auth/2fa/check` 所有签发 token 的接口,响应 `data` 多 3 字段: - -```json -{ - "code": 200, - "data": { - "token": "eyJhbGciOiJIUzI1NiJ9...", // 旧字段,=accessToken,保留向后兼容 - "refreshToken": "eyJhbGciOiJIUzI1NiJ9...", // 新增,用于换新 access - "accessTokenExpiresIn": 7200, // 新增,access token 有效期(秒) - "refreshTokenExpiresIn": 604800, // 新增,refresh token 有效期(秒) - "adminId": 1002, - "username": "test_admin", - "role": "ADMIN", - "roleName": "管理员", - "avatar": null, - "roles": [...] - } -} -``` - -### 2. 新端点 `POST /admin/auth/refresh` - -| 项 | 值 | -|---|---| -| 方法/路径 | `POST /admin/auth/refresh` | -| Authorization | **不需要**(access 可能已过期) | -| body | `{ "refreshToken": "<当前 refresh token>" }` | -| 成功返回 | `Result<AdminLoginResponse>` (与登录响应结构一致) | -| 失败返回 | `{ "code": 401, "message": "刷新令牌无效或已过期,请重新登录" }` | - -**轮转特性**:每次 refresh 成功,旧 refresh 立即失效(防重放)。前端必须立即用新返回的 `refreshToken` 替换本地存储的老值。 - -### 3. 登出行为变化 - -`POST /admin/auth/logout` 后端同时清: -- `admin_token:{adminId}` (access 白名单) -- `admin_refresh_token:{adminId}` (refresh 白名单) - -前端流程不变,登出后调 refresh 会立即报 401。 - ---- - -## 前端 axios 拦截器伪代码 (@mmg) - -```js -// 1. 登录后存全套 token -const { token, refreshToken } = res.data; -localStorage.setItem('admin_access', token); -localStorage.setItem('admin_refresh', refreshToken); - -// 2. 业务请求拦截:Authorization Bearer access -request.interceptors.request.use((cfg) => { - const access = localStorage.getItem('admin_access'); - if (access) cfg.headers.Authorization = `Bearer ${access}`; - return cfg; -}); - -// 3. 401 响应拦截:自动 refresh,失败才跳登录 -let refreshing = null; // 单飞防并发 401 一起触发多次 refresh -request.interceptors.response.use( - (res) => { - // 业务 code 401 也算未授权(本项目 HTTP 总是 200,401 在 body.code) - if (res.data?.code === 401) return handleAuth401(res); - return res; - }, - (err) => { - if (err.response?.status === 401) return handleAuth401(err); - return Promise.reject(err); - } -); - -async function handleAuth401(errOrRes) { - if (refreshing) { - await refreshing; - return request(errOrRes.config); // 等别人 refresh 完用新 token 重发 - } - refreshing = (async () => { - const refresh = localStorage.getItem('admin_refresh'); - if (!refresh) throw new Error('no refresh'); - try { - const r = await axios.post('/admin/auth/refresh', { refreshToken: refresh }); - if (r.data?.code !== 200) throw new Error('refresh failed'); - const { token, refreshToken } = r.data.data; - localStorage.setItem('admin_access', token); - localStorage.setItem('admin_refresh', refreshToken); - } catch (e) { - // refresh 也挂了 -> 清状态 -> 跳登录 - localStorage.removeItem('admin_access'); - localStorage.removeItem('admin_refresh'); - router.push('/login'); - throw e; - } finally { - refreshing = null; - } - })(); - await refreshing; - // 用新 access 重发原请求 - errOrRes.config.headers.Authorization = `Bearer ${localStorage.getItem('admin_access')}`; - return request(errOrRes.config); -} -``` - -**关键点**: -- 单飞锁 `refreshing` 防并发 401 一起触发多次 refresh(会被 jti 轮转拒) -- refresh 失败 → 清本地 → 跳 `/login`(等同于以前 401 弹窗的兜底) -- 老前端不发版也能用(老 access 7d→2h 后会被踢,但 `token` 字段还在,业务调用方式不变) - ---- - -## 测试服 9 步真测 PASS (admin / Admin@123456) - -``` -STEP 1: login -> 200 + 4 字段齐全 (accessTTL=7200, refreshTTL=604800) -STEP 2: GET /admin/auth/info Bearer access1 -> 200 (access 可用) -STEP 3: POST /admin/auth/refresh {refresh1} -> 200 + 新 access2+refresh2 -STEP 4: GET /admin/auth/info Bearer access2 -> 200 (新 access 可用) -STEP 5: POST /admin/auth/refresh {OLD refresh1} -> 401 (轮转防重放) -STEP 6: POST /admin/auth/logout Bearer access2 -> 200 -STEP 7: POST /admin/auth/refresh {refresh2 登出后} -> 401 (Redis 清掉) -STEP 8: POST /admin/auth/refresh {access1} -> 401 (access 当 refresh,type 校验) -STEP 9: POST /admin/auth/refresh {篡改 refresh} -> 401 -``` - ---- - -## 配置项 - -| 配置 key | 默认 | 环境变量 | -|---|---|---| -| `auth.jwt.admin-access-ttl-seconds` | 7200 (2h) | `ADMIN_ACCESS_TTL` | -| `auth.jwt.admin-refresh-ttl-seconds` | 604800 (7d) | `ADMIN_REFRESH_TOKEN_TTL` | - -代码层已 fallback,nacos 不配也跑;需要调整时通过环境变量或 nacos 配置覆盖。 - ---- - -## ⚠️ 正式服上线建议 - -正式服部署前,在 Deploy Panel 给 hl-user-service 设环境变量 `ADMIN_ACCESS_TTL=604800`(把 access 临时维持 7 天),等前端 mmg 接好 axios 拦截器后再去掉环境变量自动切回 2h。否则一上线所有 admin 用户 2h 后被强制踢下线。 - -测试服不需要(用户只有 wx/test_admin)。 - ---- - -## 不影响范围 - -- 小程序 user (USER 类型 token) — 现状 90 天不变 -- 登录端点 path 不变 -- /admin/auth/info 等业务接口契约不变 -- 已签发的 token 在 Redis 还有原 TTL,不会因部署立即失效 - ---- - -## switchRole 提醒(@mmg 重要) - -切换角色 `POST /admin/auth/switch-role` 响应也包含新的 refreshToken/accessTokenExpiresIn/refreshTokenExpiresIn 字段。前端必须同时更新本地存储的 **accessToken 和 refreshToken**(背后 jti 已轮换,旧 refresh 立即失效)。不要只取 token 字段。 - -## 已审视的反向 cleanup 场景 - -| 场景 | 是否清 token | 说明 | -|---|---|---| -| logout | 清 access + refresh | 主动登出 | -| changePassword | 清 access + refresh | 改密强制重登 | -| deleteAdmin | 清 access + refresh (#2294 补) | 删 admin 防绕过 | -| resetPassword | 清 access + refresh (#2294 补) | 超管重置他人密码 | -| login 账号锁定 (失败 5 次) | 清 access + refresh (#2294 补 + 修旧 bug) | 可疑账号防已签发 token 继续生效 | -| switchRole | 不主动清 (jti 轮转自动覆盖) | issueAdminTokens 写新 jti 覆盖旧 | -| login 成功 | 不主动清 (同 switchRole) | — | -| unlockAdmin | 不清 | 登录态本就无效 | - -## 相关文档 - -- Issue: [wx/HL#2283](https://git.1814.love:8443/wx/HL/issues/2283) -- PR 主体: [wx/HL#2285](https://git.1814.love:8443/wx/HL/pulls/2285) -- Hotfix #2287: 补 user-service TokenInterceptor 白名单 -- Hotfix #2294: 补 deleteAdmin/resetPassword/账号锁定 3 处 refresh cleanup + 锁定旧 bug diff --git a/changelogs/2026-05/14_feat_admin_list_productline_resolve_seasons.md b/changelogs/2026-05/14_feat_admin_list_productline_resolve_seasons.md deleted file mode 100644 index 62c0a15..0000000 --- a/changelogs/2026-05/14_feat_admin_list_productline_resolve_seasons.md +++ /dev/null @@ -1,119 +0,0 @@ -# resource: admin 列表加 productLineId 参数自动 resolve seasons (前端少做一步) - -> **服务**: hl-product-service-v2 (端口 8083) + hl-resource-service (端口 8082) -> **PR**: #2281 -> **Issue**: #2278 -> **日期**: 2026-05-14 -> **影响范围**: 管理端 产品设计「补充信息 → 产品卖点」节点弹窗(景区/游玩项目列表) - ---- - -## ⚠️ 关键变化 - -紧接 #2229/#2232/#2269 admin 列表季节系列。 - -**之前**: 前端调 /admin/scenic/spots /admin/activity/items 必须传 seasons 参数才能切换 cover/seasonHighlights, 但产品上下文只有 productLineId, 前端要先 GET 产品线接口拿 seasons 再传, **多一步**。 - -**现在**: 后端接受 productLineId, 自动 Feign resolve productLine.seasons 注入 query.seasons → 走现有 #2229 切换链路。**前端只多传一个 ID, 不必再算 seasons[0]**。 - ---- - -## 链路 - -``` -/admin/scenic/spots?productLineId=X (无 seasons) - → ScenicSpotService.listSpots 开头 Feign 调 hl-product-v2 GET /internal/product-line/X/seasons - → 拿到 List<String> → 注入 query.setSeasons(...) - → 走 PR #2229 现有 seasons[0] 切换 cover/seasonHighlights 路径 -``` - -同款给 /admin/activity/items。 - ---- - -## 接口变化 - -### admin 列表加 productLineId 参数 - -| 接口 | 方法 | 路径 | 变更 | -|---|---|---|---| -| 景区列表 | GET | `/admin/scenic/spots` | 入参加 `productLineId: Long` | -| 游玩项目列表 | GET | `/admin/activity/items` | 入参加 `productLineId: Long` | - -### internal 新加 - -| 接口 | 方法 | 路径 | 说明 | -|---|---|---|---| -| 产品线 seasons | GET | `/internal/product-line/{lineId}/seasons` | 供 resource-service Feign 调用, 返 `Result<List<String>>` | - ---- - -## 入参 5 场景兼容性 - -| 场景 | 行为 | -|------|------| -| 只传 seasons | 旧路径不调 Feign (PR #2229 原行为) | -| 只传 productLineId | Feign 注入 seasons → 走 PR #2229 路径 | -| 两个都传 | seasons 显式优先 (不调 Feign) | -| 都不传 | 走本体 cover + seasonHighlights=null (向前兼容) | -| productLineId 不存在 / Feign 异常 | 静默降级走本体 (fail-open, 不 500) | - ---- - -## 前端推荐用法 (@mmg) - -```ts -// 弹窗 fetch 时多传 productLineId 即可, 不必再算 seasons: -const productLineId = currentProduct.lineId; // 编辑产品上下文已有 -fetch(`/admin/scenic/spots?keyword=${kw}&pageSize=20&productLineId=${productLineId}`); -fetch(`/admin/activity/items?keyword=${kw}&pageSize=20&productLineId=${productLineId}`); -``` - -不必再调产品线接口拿 seasons 数组。 - ---- - -## 测试服三态对比已验证 (中俄边境公路 scenicId=3001000000000000019) - -| 场景 | total | coverUrl | seasonHighlights | -|---|---|---|---| -| 无参 | 66 | `oss.aliyuncs.com/...62943d9b.jpg` (本体) | null | -| productLineId=2045004175602868226 (autumn 产品线) | 18 | `unsplash.com/photo-1508739773434-c26b3d09e071` | "秋色画廊·边境公路,稻穗收割,亲子自驾季" | -| productLineId=2047215799055118338 (summer 产品线) | 18 | `unsplash.com/photo-1472214103451-9374bd1c798e` | "中国最美边境公路,草原绿浪铺天,自驾天堂" | -| productLineId=9999999... (不存在) | 66 | 本体 (Feign fallback) | null | - -✓ 三态切换符合预期, fail-open 降级正常。 - ---- - -## 不影响范围 - -- **仅影响**: admin 景区/游玩项目列表入参 + 后端装配 -- **零影响**: 小程序 C 端、订单、价格、admin 详情、其他列表 -- **向前兼容**: 前端没改之前(只传 seasons 或都不传)行为不变 - ---- - -## 风险评估 - -- 双向 Feign 已确认非循环: resource → product-v2 (本 PR) + product-v2 → resource (#2263 batchDetails) 都是单向 -- product-v2 internal endpoint 只 SELECT product_line.seasons 单字段, 不会反向调 resource -- Feign fail-open: productLineId 不存在 / Feign 异常时静默降级, 列表不 500 - ---- - -## 相关历史 PR - -| PR | Issue | 说明 | -|----|-------|------| -| #2229 | #2227 | 景区列表加 seasons 字段 + 封面切换 | -| #2234 | #2232 | 游玩项目同款 | -| #2269 | #2267 | 列表加 seasonHighlights 字段 | -| **#2281** | **#2278** | **本 PR**: 加 productLineId 自动 resolve seasons | - ---- - -## 相关文档 - -- Issue: [wx/HL#2278](https://git.1814.love:8443/wx/HL/issues/2278) -- PR: [wx/HL#2281](https://git.1814.love:8443/wx/HL/pulls/2281) diff --git a/changelogs/2026-05/14_feat_admin_list_season_highlights_field.md b/changelogs/2026-05/14_feat_admin_list_season_highlights_field.md deleted file mode 100644 index 05c3f17..0000000 --- a/changelogs/2026-05/14_feat_admin_list_season_highlights_field.md +++ /dev/null @@ -1,145 +0,0 @@ -# resource: admin 列表 ScenicSpotListVO/ActivityListVO 加 seasonHighlights 字段 - -> **服务**: hl-resource-service (端口 8082) -> **PR**: #2269 -> **Issue**: #2267 -> **日期**: 2026-05-14 -> **影响范围**: 管理端 产品设计「补充信息 → 产品卖点」节点弹窗预览 - ---- - -## ⚠️ 关键变化 - -紧接 #2229/#2232/#2250/#2263 季节系列。 - -产品设计弹窗调 `/admin/scenic/spots`, `/admin/activity/items` 列表时, 当前 VO 只有 `highlights` (本体) + `seasons[]` (4 季列表), 没有 `seasonHighlights` (按 query.seasons[0] 命中季节亮点)。前端拿不到「当前产品季节对应的亮点文本」, 无法在弹窗预览或自动带入。 - -本次加字段, 由 query.seasons 入参驱动后端返回对应季节的 highlights。 - ---- - -## 影响接口 - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 1 | 景区列表 | GET | `/admin/scenic/spots` | VO 加 `seasonHighlights: String` | -| 2 | 游玩项目列表 | GET | `/admin/activity/items` | VO 加 `seasonHighlights: String` | - -入参字段 `seasons` (List<String>) 沿用 #2229/#2232 已有。 - ---- - -## 装配规则 (字段独立, 复用现有 Map 零额外 SQL) - -``` -query.seasons 非空 → 取 seasons[0] 命中的 scenic_season/activity_season.highlights → seasonHighlights -未命中 → seasonHighlights = null (前端回落显示本体 highlights) -query.seasons 为空/null → seasonHighlights = null (向前兼容) -``` - -复用 PR #2229/#2232 已建的 `seasonsByScenicId` / `seasonsByActivityId` Map 和 `firstSeason` 变量, 零额外查询。 - ---- - -## 响应示例 - -### GET /admin/scenic/spots?page=1&pageSize=3&status=1&seasons=autumn - -```json -{ - "code": 200, - "data": { - "records": [ - { - "scenicId": 3001000000000000019, - "name": "中俄边境公路（卡线）", - "highlights": "中国最美边境自驾路，200公里移动的画廊", - "seasons": ["spring","summer","autumn","winter"], - "seasonHighlights": "秋色画廊边境公路,五彩斑斓,最佳自驾季", - "coverUrl": "https://images.unsplash.com/photo-XXX-autumn.jpg", - "...": "..." - } - ] - } -} -``` - -### GET /admin/scenic/spots?page=1&pageSize=3&status=1 (无 seasons) - -```json -{ - "data": { - "records": [ - { - "scenicId": 3001000000000000019, - "name": "中俄边境公路（卡线）", - "highlights": "中国最美边境自驾路，200公里移动的画廊", - "seasons": ["spring","summer","autumn","winter"], - "seasonHighlights": null, - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/.../本体.jpg" - } - ] - } -} -``` - ---- - -## 测试服三态对比已验证 - -同一景区 scenicId=3001000000000000019 (中俄边境公路): - -| seasons 参数 | seasonHighlights 值 | -|---|---| -| 无 | `null` | -| seasons=summer | `中国最美边境公路,草原河流白桦林,自驾天堂` | -| seasons=autumn | `秋色画廊边境公路,五彩斑斓,最佳自驾季` | - -✓ 字段切换符合预期, 内容语义匹配季节。 - -`/admin/activity/items` 同款字段已暴露, 当前数据为空 (activity_season 表无配置, 等运营通过 PR #2262 接口配后才有值)。 - ---- - -## 前端使用建议 (@mmg) - -弹窗调用列表接口时: - -1. **从当前编辑产品 productLine.seasons 取首个季节, 拼入 query 参数** `seasons=spring/summer/autumn/winter` -2. **优先级显示**: `seasonHighlights ?? highlights` (`seasonHighlights` 非空时用季节亮点, null 时回落本体) -3. 不必关心后端装配细节, 字段返 null 直接走旧 UI 即可 - -如果前端弹窗调用时没传 seasons 参数, 后端会保留旧行为返 `seasonHighlights: null`, **不会破坏现有展示**。 - ---- - -## 不影响范围 - -- **仅影响**: 管理端景区/游玩项目列表 VO 加 1 字段 -- **零影响**: 小程序 C 端、订单、价格、admin 详情 API、其他列表 - ---- - -## 风险评估 - -- 极低: 装配只读已有 Map, 零额外 SQL, 零 DB 改动, 零 Flyway -- 向前兼容: 旧调用方拿到 null 不报错 - ---- - -## 相关历史 PR - -| PR | Issue | 说明 | -|----|-------|------| -| #2229 | #2227 | 景区列表加 seasons 字段 + 封面按 seasons[0] 切换 | -| #2234 | #2232 | 游玩项目同款 | -| #2250 | #2243 | 节点 description 按 seasons[0] 回落 highlights | -| #2263 | #2256 | 节点 ResourceDetailDTO 加 seasonCover/seasonBanner/seasonVideo | -| **#2269** | **#2267** | **本 PR**: 列表 VO 加 seasonHighlights | - ---- - -## 相关文档 - -- Issue: [wx/HL#2267](https://git.1814.love:8443/wx/HL/issues/2267) -- PR: [wx/HL#2269](https://git.1814.love:8443/wx/HL/pulls/2269) diff --git a/changelogs/2026-05/14_feat_admin_product-v2-node-description-season-highlights-fallback.md b/changelogs/2026-05/14_feat_admin_product-v2-node-description-season-highlights-fallback.md deleted file mode 100644 index cc3fe4a..0000000 --- a/changelogs/2026-05/14_feat_admin_product-v2-node-description-season-highlights-fallback.md +++ /dev/null @@ -1,124 +0,0 @@ -# product-v2: 节点 description 按产品线 seasons[0] 自动回填季节亮点 - -> **服务**: hl-product-service-v2 (端口 8083) + hl-resource-service (端口 8082) -> **PR**: #2250 -> **Issue**: #2243 -> **日期**: 2026-05-14 -> **影响范围**: 管理端 产品编辑 → 补充信息 → 产品卖点（节点 description 字段） - ---- - -## ⚠️ 关键变化 - -紧接 #2229(景区季节)/#2232(游玩项目季节)/#2096(节点 description 默认从资源 highlights 回填)。 - -**之前**: 节点 description 为空时, 后端自动回填 = 资源**本体** `highlights`。 - -**现在**: 节点 description 为空时, 后端自动回填 = **`scenic_season/activity_season.highlights`（按产品线 seasons[0]）→ 缺失再回落本体 `highlights`**。 - -**保持不变(独立快照)**: 节点 description **非空时不动**, 用户手填的卖点永远保留, 不会被后端覆盖。 - ---- - -## 一、回填规则 - -``` -节点 description = ( - ( scenic_season.highlights WHERE scenic_id=X AND season_type=seasons[0] ) -- SCENIC 优先 - || scenic_spot.highlights -- SCENIC 回落 - || ( activity_season.highlights WHERE activity_id=X AND season_type=seasons[0] ) -- ACTIVITY 优先 - || activity.highlights -- ACTIVITY 回落 - || null -) -``` - -季节匹配规则: 取**产品对应产品线** `productLine.seasons[0]`(首个季节), 与封面切换 #2229/#2234 行为一致。 - -**触发时机**: 仅在保存行程节点(`POST /admin/product/item/{id}/itinerary` 或同等接口)且节点 `description` 为空或空白字符时触发。已经填了内容的节点保存时不会被覆盖。 - ---- - -## 二、影响接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 保存行程(快速理解节点) | POST/PUT | `/admin/product/item/{id}/itinerary` | 内部行为变更 | 入参/响应字段无变化 | -| 2 | 产品详情 | GET | `/admin/product/{id}` | 数据来源变化 | `itineraryDays[].nodes[].description` 字段值来源由"本体 highlights"改为"季节 highlights 优先" | -| 3 | 资源详情批量(internal) | POST | `/internal/resource/batch-details` | 入参加 `season` | 透明改动, 调用方为 product-v2 | - -跨服务 DTO `ResourceDetailDTO` 新增字段 `seasonHighlights`(可为 null), 老消费者(Jackson 默认 ignore unknown)兼容, 不需要 redeploy。 - ---- - -## 三、契约约束 - 前端无需任何改动 - -- 保存接口 payload 字段不变 -- 详情响应字段不变(还是 `description`) -- 前端在编辑页填的内容**永远不会**被后端覆盖, 不需要任何防御逻辑 - ---- - -## 四、边界行为 - -| 场景 | 节点 description 自动回填值 | -|------|----------------------------| -| productLine.seasons = `["spring"]` + 节点指向有 spring 配置的景区 + description 空 | `scenic_season(spring).highlights` | -| productLine.seasons = `["winter"]` + 节点指向**无 winter** 配置的景区 + description 空 | 回落 `scenic_spot.highlights`(本体) | -| productLine.seasons = null/`[]` + description 空 | 回落本体 `highlights`(向前兼容, 与 #2096 行为一致) | -| productLine.seasons = `["spring","autumn"]`(多季节) + description 空 | 取 seasons[0]=spring 匹配 | -| ACTIVITY 节点 | 同款行为(`activity_season.highlights` 优先, 回落 `activity.highlights`) | -| 节点 description **非空** | **不回填, 保留原值**(任何场景下都不覆盖) | -| 资源详情查询失败/异常 | 静默降级(`seasonHighlights=null`), 走本体 highlights | - ---- - -## 五、老数据 / 存量产品 - -**重要**: 此次改动**不会**主动遍历存量产品节点修改 description。 - -- 老产品节点 description 都是非空的(之前由 #2096 用本体 highlights 自动填了, 或用户手填的) → 保存时不会触发回填, **看起来"季节回落没生效"是正常的** -- 想让某节点切换到季节亮点 → 编辑时**清空** description 文本框再保存即可 -- 不接受"自动覆盖所有老节点"的需求(已与 wx 确认: 独立快照原则保护用户手填内容) - ---- - -## 六、不影响范围 - -- **仅影响**: 管理端产品编辑保存时的节点 description 默认值 -- **零影响**: - - 小程序端 C 端展示(读 description 字段, 来源透明) - - 订单创建/详情/退款 - - 算价 / 价格日历 - - 历史产品节点的现存 description 值 - ---- - -## 七、测试环境已验证 - -``` -GET /admin/scenic/spots?page=1&pageSize=5&status=1 → 200 + seasons[] 字段 ✓ (PR #2229) -GET /admin/activity/items?page=1&pageSize=5 → 200 + seasons[] 字段 ✓ (PR #2232) -GET /admin/product/2045345825172639746 → 200 + itinerary.nodes[].description ✓ -``` - -测试样本: 产品"游牧的森林-短途版"(`productLineId=2045004175602868226`, seasons=["autumn"])。3 个手填过 description 的 SCENIC 节点保持原值不变, 符合独立快照设计。 - ---- - -## 八、相关历史 PR - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| #2076 | #2068 | 资源 3 类 + 行程节点新增「图标」「卖点简介」2 字段 | ✅ 有效 | -| #2091 | #2090 | 复用 description 删冗余 sellingPoint | ✅ 有效 | -| #2096 | #2095 | 节点选资源时, 资源本体 highlights 默认带到节点 description | ✅ 有效, 被本 PR 增强 | -| #2229 | #2227 | 产品设计选景区按产品线季节过滤 + 节点 seasons 标签 | ✅ 有效 | -| #2234 | #2232 | 游玩项目同款季节过滤 + 标签 | ✅ 有效 | -| **本 PR #2250** | **#2243** | 节点 description 默认值由"本体 highlights"升级为"季节 highlights 优先 + 回落本体" | ✅ 最新 | - ---- - -## 九、相关文档 - -- Issue: [wx/HL#2243](https://git.1814.love:8443/wx/HL/issues/2243) -- PR: [wx/HL#2250](https://git.1814.love:8443/wx/HL/pulls/2250) diff --git a/changelogs/2026-05/14_feat_mp_admin_product_detail_supplies_with_cover.md b/changelogs/2026-05/14_feat_mp_admin_product_detail_supplies_with_cover.md deleted file mode 100644 index 76772de..0000000 --- a/changelogs/2026-05/14_feat_mp_admin_product_detail_supplies_with_cover.md +++ /dev/null @@ -1,184 +0,0 @@ -# product-v2: 小程序 + 管理端产品详情返回备品清单(含封面图) - -> **服务**: hl-product-service-v2 (端口 8083) + hl-resource-service (端口 8082) -> **PR**: #2272 -> **Issue**: #2266 -> **日期**: 2026-05-14 -> **影响范围**: 小程序产品详情新增 `supplies` 数组 / 管理端产品详情 `supplies[].coverUrl` 新增字段 - ---- - -## ⚠️ 关键变化 - -小程序产品详情接口此前**完全没返回备品清单**,前端无法展示。本次补齐: - -1. **小程序详情 `GET /mp/product/{id}` 顶层新增 `supplies` 数组**(此前完全没有这个字段) -2. **管理端详情 `GET /admin/product/item/{id}` `supplies[]` 子对象新增 `coverUrl` 字段** -3. 数据库 `product_supplies` 表新增 `cover_url` 列,Flyway V20260514_001 已在测试服跑完一次性 JOIN 回填:**引用资源库 supplies_item 的备品 100% 命中(73/73)** - ---- - -## 一、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 小程序产品详情 | GET | `/mp/product/{id}` | **新增字段** | 顶层 `supplies: SuppliesVO[]` | -| 2 | 管理端产品详情 | GET | `/admin/product/item/{id}` | 字段扩展 | `supplies[]` 子对象新增 `coverUrl` | - ---- - -## 二、接口详情 - -### 1. 小程序产品详情 `GET /mp/product/{id}` - -**VO**: `MpProductDetailRespVO.SuppliesVO`(新内嵌静态类) - -#### 新增响应字段 - -```json -{ - "code": 200, - "data": { - "productId": "2045623908178046978", - "name": "带孩子,看一次真正的草原。", - "...": "其他既有字段保持不变", - "supplies": [ - { - "id": 2045635184023285762, - "suppliesName": "团队识别手环", - "category": "个人装备", - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/xxx.png", - "sortOrder": 0 - }, - { - "id": 2045635184027480066, - "suppliesName": "防晒喷雾", - "category": "个人装备", - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/yyy.png", - "sortOrder": 1 - } - ] - } -} -``` - -| 字段 | 类型 | 可能为 null | 说明 | -|------|------|------------|------| -| `supplies` | `List<SuppliesVO>` 或 `null` | ✅ | 产品没备品时整个字段为 `null`,前端按 null 兜底空数组即可 | -| `supplies[].id` | `Long`(雪花) | ❌ | 备品行 ID(C 端通常用不到,可忽略) | -| `supplies[].suppliesName` | `String` | ❌ | 备品名称(已是快照,展示用) | -| `supplies[].category` | `String` 或 `null` | ✅ | 分类(中文文本或字典编码均可能,示例 `个人装备`/`保暖装备`/`CAMPING` 等,**前端不要做硬枚举映射**,直接展示文本) | -| `supplies[].coverUrl` | `String` 或 `null` | ✅ | 备品封面图 URL(快照),自定义备品或历史回填失败可能为 null,**前端务必做默认占位图兜底** | -| `supplies[].sortOrder` | `Integer` | ❌ | 排序字段,后端已按 ASC 返回,前端按数组顺序渲染即可 | - -#### 排序 - -后端 `selectByProductId` 已 `orderByAsc(sortOrder)` 排序,前端直接按数组顺序展示。 - -### 2. 管理端产品详情 `GET /admin/product/item/{id}` - -**VO**: `ProductDetailRespVO.SuppliesVO`(既有内嵌类,仅扩展字段) - -`supplies[]` 子对象新增 `coverUrl: String`,语义同上(快照,可能为 null)。其他既有字段(`id` / `productId` / `suppliesResourceId` / `suppliesName` / `category` / `hasCost` / `billingType` / `unitPrice` / `quantity` / `sortOrder`)保持不变。 - ---- - -## 三、前端兜底要求 - -**重要**:`coverUrl` 字段**可能为 null**,出现场景: - -1. **手工添加的自定义备品**(没勾选资源库 supplies_item,只填了名字) — 后端没有源头查 cover,直接 null -2. **历史数据中 supplies_item 关联资源已删 / material 已删 / oss_url 为空** — 一次性 JOIN 回填时被防御逻辑排除 - -**前端必须做默认占位图**,例如: - -```js -const cover = supply.coverUrl || '/static/supplies-default.png'; -``` - -或 CSS: - -```css -.supplies-cover { background: url(/static/supplies-default.png) no-repeat center; } -.supplies-cover img { object-fit: cover; } -``` - -测试服回填命中率参考:**174 条 product_supplies 中 73 条有 supplies_resource_id,全部命中真实 OSS URL;另外 101 条是手工/旧数据,coverUrl 为 null**。 - ---- - -## 四、已知限制(后续优化) - -- **手工(非组合)单品在编辑保存时 coverUrl 暂留 null**:本次未引入新 Feign,只通过 DB 一次性回填覆盖历史,新增/编辑手工备品 coverUrl 仍是 NULL,**前端兜底是必须的** -- **从备品组合("从组合选择"按钮)添加的备品 coverUrl 在保存时自动同步**:`SuppliesComboService.expandBatch` 已接入 MaterialService 批量解析,组合展开自然带 URL - ---- - -## 五、测试服真测证据 - -```bash -# 测试服 9443 网关 -curl https://api.test.1814.love:9443/mp/product/2045623908178046978 -``` - -返回顶层 `supplies` 数组 4 条全部带 coverUrl 真实 OSS URL,按 sortOrder 0→1→2→3 升序。 - -Admin 端用 `test_admin (admin_id=1002)` 测试 productId=2053665899663024129(用户截图同一产品):3 条备品(团队识别手环 / 防晒喷雾 / 便携矿泉水)全部带 coverUrl ✅ - ---- - -## 六、补丁(PR #2290 / Issue #2289)— 备品组合接口同步补 coverUrl - -紧接本文上方主体,管理后台编辑产品「路线与备品 → 从组合选择」弹窗调的 **备品组合列表/详情** 接口也补齐 coverUrl(此前只有产品自己的 supplies 数组有,组合接口 items 缺): - -### 变更接口 - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 3 | 启用组合列表 | GET | `/admin/supplies-combo/enabled` | `items[]` 新增 `coverUrl` | -| 4 | 备品组合详情 | GET | `/admin/supplies-combo/{comboId}` | 同上 | - -### VO 字段 - -`SupplyComboRespVO.ItemRespVO` 新增 `coverUrl: String`(放在 `suppliesName` 之后,与产品详情 SuppliesVO 对齐)。语义与上方主体一致:**快照,来自 supplies_item.cover_material_id 对应 material.oss_url,可能为 null,前端做占位图兜底**。 - -```json -{ - "code": 200, - "data": [ - { - "comboId": 2046122595429806082, - "name": "4", - "items": [ - { - "id": 2048695562294710273, - "suppliesId": ..., - "suppliesName": "便携矿泉水", - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/xxx.jpg", - "categoryCode": "personal_gear", - "billingType": "...", - "basePrice": ..., - "quantity": 1, - "sortOrder": 3 - } - ] - } - ] -} -``` - -### 测试服真测证据 - -- `/admin/supplies-combo/enabled` 返回 2 个 combo,共 5 条 items 全部带真实 OSS URL coverUrl(命中率 100%) -- `/admin/supplies-combo/{comboId}` 同款返回 4 条 items 全部带 coverUrl - -### 实现说明 - -- 跨所有 combo 一次性批量 `MaterialService.getMaterialsByIds` 调用,**单测含 `verify(materialService, times(1))` 防 N+1** -- 复用主体 #2272 引入的 `parseLongSafe(cover_material_id)` 数字防御 + `fetchCoverUrlsByMaterialIds` -- material 查询失败 / 不存在 / cover_material_id 非数字 → coverUrl null,**不阻断接口** - -### 不变项 - -- `items` 数组顺序保持后端原有逻辑(目前是 sortOrder DESC,与本工单 #2289 无关,如需调整为 ASC 请单独反馈) - diff --git a/changelogs/2026-05/14_feat_mp_node_media_season_pipeline_through.md b/changelogs/2026-05/14_feat_mp_node_media_season_pipeline_through.md deleted file mode 100644 index 3b9ac57..0000000 --- a/changelogs/2026-05/14_feat_mp_node_media_season_pipeline_through.md +++ /dev/null @@ -1,127 +0,0 @@ -# resource + product-v2: 节点封面/轮播图/视频按产品线 seasons[0] 季节回落 (基础设施 + MP 消费侧接通) - -> **服务**: hl-resource-service (端口 8082) + hl-product-service-v2 (端口 8083) -> **PR**: #2263 (基础设施) + #2271 (MP 消费侧接通) -> **Issue**: #2256 + #2268 -> **日期**: 2026-05-14 -> **影响范围**: 小程序 C 端 产品详情节点封面/轮播图按当前产品线季节自动切换 - ---- - -## ⚠️ 关键变化 - -紧接 #2243/#2250 节点 description 季节回落。把同款规则推广到节点的 3 个媒体字段: - -> 「产品中也要显示对应季节的封面图轮播图视频啥的, 季节没有才显示景区/游玩项目自己的」 — wx 2026-05-14 - -**取数链路 (回落顺序, 字段独立)**: - -``` -节点 cover = scenic_season.cover_material_id WHERE seasons[0] || scenic_spot.cover_material_id || null -节点 images (banner) = scenic_season.banner_material_ids WHERE seasons[0] || scenic_spot.banner_material_ids || [] -节点 videos (ID 列表) = scenic_season.video_material_ids WHERE seasons[0] || scenic_spot.video_material_ids || [] -``` - -ACTIVITY 节点同款 (activity_season → activity)。产品线 seasons 为 null/空 → 走旧行为(本体), 向前兼容。 - -季节匹配规则: 取**产品对应产品线** `productLine.seasons[0]` (首个季节), 与封面切换 #2229/#2234 行为一致。 - ---- - -## 实现方案 (选 B: 详情装配动态计算, 不写节点表) - -`ProductItineraryNodeDO` 本来就没 cover_material_id / banner_material_ids / video_material_ids 列, 加列代价大且与现有资源层季节子表设计正交。 - -改在 ResourceBatchDetailService 装配 ResourceDetailDTO 时, SCENIC/ACTIVITY 节点的 cover 优先用季节素材 URL → 回落本体, images 优先用季节轮播列表 → 回落本体。下游消费方 (product-v2 toNodeItem) **零改动**自动拿到季节切换值。 - -PR #2263 改基础设施 + DTO; PR #2271 改 product-v2 MP Assembler 接通 season 参数 (实时路径取 productLine.seasons[0], 快照路径取 snapshot.seasons[0] 符合冻结语义)。 - ---- - -## 接口字段变化 - -### Internal: ResourceDetailDTO 新增 4 字段 (PR #2263) - -| 字段 | 类型 | 说明 | -|------|------|------| -| seasonCoverMaterialId | Long | 季节封面素材 ID (按入参 season 命中) | -| seasonBannerMaterialIds | List<Long> | 季节轮播图素材 ID 列表 | -| seasonVideoMaterialIds | List<Long> | 季节视频素材 ID 列表 | -| videoMaterialIds | List<Long> | 视频素材 ID 列表(本体, 补全字段) | - -调用方 `GET /internal/resource/batch-details` 加 `season` 入参, 命中时填新字段, 本体 cover/images 同步替换为季节素材 URL。 - -### MP 端节点透明改善 - -调用方/前端**无字段变化**, MP `/mp/product/{id}` 返回的节点 `resourceCover` / `resourceImages` 已是季节素材 URL (前端无任何改动)。 - ---- - -## 测试服真测 (PASS) - -样本产品 `2047216096724873217` 「呼伦贝尔周边摄影季」, productLine `2047215799055118338` 「快乐摄影季」 `seasons=['summer']`, Day 2 SCENIC 节点引用 scenicId=3001000000000000019 (中俄边境公路): - -```json -{ - "nodeType": "SCENIC", - "resourceId": "3001000000000000019", - "resourceName": "中俄边境公路（卡线）", - "resourceCover": "https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=800&q=80", - "resourceImages": [ - "https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=800&q=80", - "https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=800&q=80" - ] -} -``` - -- `resourceCover` / `resourceImages` 注入了 summer 季节图 (与产品线 seasons[0]='summer' 匹配, 非本体 OSS 图) -- PR #2229 测试数据脚本配的 summer unsplash URL 命中 ✓ - ---- - -## 边界 - -| 场景 | 节点 cover/images 实际值 | -|------|--------------------------| -| productLine.seasons=`["spring"]` + 景区有 spring scenic_season cover | scenic_season(spring).cover_material_id URL | -| productLine.seasons=`["winter"]` + 景区无 winter season | 回落 scenic_spot.cover 本体 | -| productLine.seasons null/空 | 回落本体 (向前兼容) | -| ACTIVITY 节点 | 同款 (activity_season → activity) | -| Snapshot (订单已下单) | 取 snapshot.seasons[0] (锁定下单时刻, 不实时查产品线 — 快照语义) | -| 节点 description 字段 | 仍走 PR #2250 独立快照(保存时为空才回填), 非空保护用户手填 | - ---- - -## 兼容性 - -- ResourceDetailDTO `@AllArgsConstructor` 参数顺序变了, 已 grep 全仓库无位置参数 new 调用, 全用 builder 模式 -- 老服务消费 DTO 时 Jackson 默认 ignore unknown, 新字段不影响老版本反序列化 -- 节点级 images: List<String> 由前端控制保留 (独立快照), 资源/季节级媒体通过 DTO 动态切换, 解耦清晰 - ---- - -## 不影响范围 - -- **仅影响**: 节点详情媒体字段 (cover/images/videoMaterialIds) 装配来源 -- **零影响**: 节点 description (走 #2250 链路) / 节点 emojiIcon / 订单创建 / 算价 / 历史已生成的 snapshot (snapshot.seasons 不存在时走 null 兼容) - ---- - -## 相关历史 PR - -| PR | Issue | 说明 | -|----|-------|------| -| #2229 | #2227 | 景区列表/封面 season 切换 + scenic_season 表 | -| #2234 | #2232 | 游玩项目同款 + activity_season 表 | -| #2250 | #2243 | 节点 description 按季节回落 highlights | -| **#2263** | **#2256** | 节点媒体基础设施 (ResourceDetailDTO + ResourceBatchDetailService) | -| **#2271** | **#2268** | **MP Assembler 消费侧接通 season 参数** | - ---- - -## 相关文档 - -- Issue #2256: [wx/HL#2256](https://git.1814.love:8443/wx/HL/issues/2256) -- Issue #2268: [wx/HL#2268](https://git.1814.love:8443/wx/HL/issues/2268) -- PR #2263: [wx/HL#2263](https://git.1814.love:8443/wx/HL/pulls/2263) -- PR #2271: [wx/HL#2271](https://git.1814.love:8443/wx/HL/pulls/2271) diff --git a/changelogs/2026-05/14_feat_season_month_auto_and_description_dynamic_cover.md b/changelogs/2026-05/14_feat_season_month_auto_and_description_dynamic_cover.md deleted file mode 100644 index 0f0d7b8..0000000 --- a/changelogs/2026-05/14_feat_season_month_auto_and_description_dynamic_cover.md +++ /dev/null @@ -1,148 +0,0 @@ -# resource + product-v2: 季节月份自动赋值 + 节点 description 详情按 seasonHighlights 动态覆盖 - -> **服务**: hl-resource-service (8082) + hl-product-service-v2 (8083) -> **PR**: #2295 (Closes #2291) + #2296 (Closes #2293) + #2301 (Closes #2298) -> **日期**: 2026-05-14 -> **影响范围**: 管理端季节内容编辑表单 + 节点 description 详情展示 (admin / mp / internal facade 三路径) - ---- - -## ⚠️ 关键变化 - -### A. 季节月份自动赋值 (PR #2295) -- 之前: 运营每次配季节内容都要填 monthStart/monthEnd -- 现在: SaveRequest 删 monthStart/monthEnd, 后端按 seasonType 自动赋固定月份 (spring 3-5 / summer 6-8 / autumn 9-11 / winter 12-2 跨年) - -### B. 节点 description 详情按季节动态覆盖 (PR #2296 MP/internal + PR #2301 admin) -- 之前: PR #2250 走"独立快照", 节点表 description 非空时不覆盖 → 即使配了季节亮点也看不到 -- 现在: admin/mp/internal 三路径详情接口装配 NodeItem 时, 若 ResourceDetailDTO.seasonHighlights 非空 → 覆盖 description (季节优先); 否则保留节点表快照 (本体兜底) -- **节点表 description DB 字段保留不动** (用户手填永久存) - ---- - -## A 部分 - 季节月份自动赋值 - -### 接口变化 - -| 接口 | 方法 | 路径 | 变更 | -|---|---|---|---| -| 景区季节保存 | PUT | `/admin/scenic/spot/{scenicId}/season/{seasonType}` | body 删 `monthStart` / `monthEnd` 字段 | -| 游玩项目季节保存 | PUT | `/admin/activity/item/{activityId}/season/{seasonType}` | 同款 | - -### 后端固定映射 (SeasonMonthRangeUtil) -``` -spring → monthStart=3, monthEnd=5 -summer → monthStart=6, monthEnd=8 -autumn → monthStart=9, monthEnd=11 -winter → monthStart=12, monthEnd=2 (跨年) -``` - -### VO 保留 monthStart/monthEnd -GET 季节内容接口仍返这两字段, 供前端只读展示。前端**表单删月份选择器**即可 (字段后端自动)。 - -### 测试服真测 PASS -``` -PUT /admin/activity/item/.../season/spring (body 不含 month) → GET 返 monthStart=3 monthEnd=5 ✓ -PUT .../season/winter (跨年) → GET 返 monthStart=12 monthEnd=2 ✓ -``` - ---- - -## B 部分 - 节点 description 季节动态覆盖 - -### 装配规则 (3 路径同款) - -``` -if (ResourceDetailDTO.seasonHighlights != null && !blank) { - NodeItem.description = seasonHighlights // 季节优先 -} else { - NodeItem.description = 节点表 description // 本体兜底 -} -``` - -### 3 个改动装配点 - -| 路径 | 文件 | PR | -|---|---|---| -| admin 详情 | `ProductDetailAggregator.fillItinerary` | #2301 | -| MP 实时详情 | `MpProductDetailAssembler.enrichNodeWithResource` | #2296 | -| MP 订单快照详情 | `MpProductSnapshotAssembler.mapNodes` | #2296 | -| internal 快照构建 | `ProductItineraryAggregateFacade.toNodeItem` | #2296 | - -### admin 端特别说明 (PR #2301) -原本 admin `ProductDetailAggregator` 不调 ResourceBatchDetailService, 本次加注入 `ResourceDetailFeignClient + ProductHelperService`, 在 fillItinerary 加 3 个私有方法: -- `resolveSeasonForFallback(productId)`: 产品 → 产品线 → seasons[0] -- `fetchResourceDetailsBySeason(allNodes, season)`: Feign batch-details 带 season 参数 -- `applySeasonHighlightsOverride`: 装配后覆盖 - -### 测试服真测 PASS (产品 2043604279016443905 productLine summer) -``` -admin GET /admin/product/item/2043604279016443905 Day2 ACTIVITY 节点 - → description = "TEST_PR2301_SUMMER_HL" (summer highlights 覆盖) ✓ -MP GET /mp/product/2043604279016443905 同节点 - → description = "TEST_PR2301_SUMMER_HL" ✓ -DB 节点表 description 字段值不变 ✓ -清理 summer season 后 → description 回 null (节点表本身 null) ✓ -``` - ---- - -## 兼容性 (B 部分) - -| 场景 | 行为 | -|------|------| -| 无 productLine.seasons | season=null → seasonHighlights 永远 null → 等同旧行为 (走节点表 description) | -| 资源详情 Feign 失败 | 静默降级 → 等同旧行为 | -| 节点不绑资源 (resourceId=null) | 不进 enrich → 等同旧行为 | -| HOTEL/CUSTOM 节点 | admin 路径跳过 Feign 调用 (节省, 当前需求不涉及) | -| 节点表 description 非空 + season 命中 | description = seasonHighlights (新行为, 季节优先) | -| 节点表 description 非空 + season 不命中 | description = 节点表 description (本体兜底, 与旧行为一致) | - ---- - -## 前端 mmg 需要做的事 - -### A 部分 (季节编辑表单) -- 景区/游玩项目 SeasonDrawer.vue 表单**删月份选择器** (monthStart/monthEnd 控件) -- VO GET 仍返月份, 只读展示 (如 "适用月份: 3-5月" 文字) - -### B 部分 (节点 description) -- **零前端改动**: admin/mp 详情接口字段名/位置不变, 后端透明切换值 -- 之前如果有前端绕开 description 字段做季节展示的逻辑可以删 (后端已切) - ---- - -## 不影响范围 - -- 节点表 product_itinerary_node.description 字段 (用户手填永久存 DB) -- ProductItineraryService.convertNode 保存逻辑 (PR #2250 行为完全保留) -- 季节子表 scenic_season/activity_season DDL (向前兼容) -- 老数据 (节点表 description / 季节表 monthStart/monthEnd 保留) - ---- - -## 相关历史 PR - -| PR | Issue | 说明 | -|----|-------|------| -| #2229 | #2227 | 景区列表 seasons 字段 + 封面切换 | -| #2234 | #2232 | 游玩项目同款 | -| #2250 | #2243 | 节点 description 季节回落 (独立快照, 保存时回填) | -| #2262 | #2257 | ActivitySeasonController admin CRUD | -| #2263 | #2256 | 节点媒体季节基础设施 (ResourceDetailDTO seasonXxx) | -| #2271 | #2268 | MP Assembler 接通 season | -| #2281 | #2278 | 列表加 productLineId 参数自动 resolve seasons | -| **#2295** | **#2291** | **季节月份自动赋值** | -| **#2296** | **#2293** | **节点 description 季节动态覆盖 (MP+internal)** | -| **#2301** | **#2298** | **admin 端同款 (补 #2296)** | - ---- - -## 相关文档 - -- Issue #2291: [wx/HL#2291](https://git.1814.love:8443/wx/HL/issues/2291) -- Issue #2293: [wx/HL#2293](https://git.1814.love:8443/wx/HL/issues/2293) -- Issue #2298: [wx/HL#2298](https://git.1814.love:8443/wx/HL/issues/2298) -- PR #2295: [wx/HL#2295](https://git.1814.love:8443/wx/HL/pulls/2295) -- PR #2296: [wx/HL#2296](https://git.1814.love:8443/wx/HL/pulls/2296) -- PR #2301: [wx/HL#2301](https://git.1814.love:8443/wx/HL/pulls/2301) diff --git a/changelogs/2026-05/14_frontend_admin_list_should_pass_seasons_param.md b/changelogs/2026-05/14_frontend_admin_list_should_pass_seasons_param.md deleted file mode 100644 index 3f121ce..0000000 --- a/changelogs/2026-05/14_frontend_admin_list_should_pass_seasons_param.md +++ /dev/null @@ -1,121 +0,0 @@ -# [前端] admin 列表弹窗调用 /admin/scenic/spots 和 /admin/activity/items 应传 seasons 参数 - -> **服务**: 前端 hl-ui (管理端) -> **后端 PR**: 无独立后端 PR (后端能力 #2229/#2232 已就绪 + #2269 加 seasonHighlights) -> **日期**: 2026-05-14 -> **影响范围**: 管理端 产品设计「补充信息 → 产品卖点」节点弹窗的封面图/标签/亮点展示 - ---- - -## ⚠️ 关键变化 - -**后端能力早就做了, 前端没传参数, 所以一直没生效**: - -- PR #2229 commit 注明: "封面优先级: 若 query.seasons 非空,取首个季节匹配该景区 scenic_season 的 coverMaterialId" -- PR #2234 同款给游玩项目 -- PR #2269 加 seasonHighlights 字段同款规则 - -前端弹窗 `/admin/scenic/spots?page=1&pageSize=20&status=1` 当前**没传** `seasons` 参数 → 后端走默认路径返回本体封面 + 不切换 seasonHighlights。 - ---- - -## 测试服后端能力已验证 (前端 fetch 同款 URL 即可看到效果) - -``` -# 无 seasons (当前前端行为): -GET /admin/scenic/spots?page=1&pageSize=3&status=1 -→ records[0].coverUrl = oss 本体封面 -→ records[0].seasonHighlights = null - -# 带 seasons=autumn (期望前端行为): -GET /admin/scenic/spots?page=1&pageSize=3&status=1&seasons=autumn -→ records[0].coverUrl = unsplash 秋色封面 (按 scenic_season(autumn).cover_material_id 切换) -→ records[0].seasonHighlights = "秋色画廊边境公路,五彩斑斓,最佳自驾季" - -# 带 seasons=summer: -GET /admin/scenic/spots?page=1&pageSize=3&status=1&seasons=summer -→ records[0].coverUrl = unsplash 夏景封面 -→ records[0].seasonHighlights = "中国最美边境公路,草原河流白桦林,自驾天堂" -``` - -三态各异 ✓ 已通过 round-trip 测试验证。 - ---- - -## 前端需要做的事 (@mmg) - -### 1. 找到调用 /admin/scenic/spots 和 /admin/activity/items 的弹窗代码 - -可能在产品编辑页 → 补充信息 → 产品卖点 → "添加节点" 弹窗组件。 - -### 2. 从当前编辑产品上下文取 productLine.seasons - -- 编辑产品时, 已经知道 `lineId` -- 调 `/admin/product-line/{lineId}` 或当前产品详情拿 `productLine.seasons` -- 实际产品上下文应该已经有这个字段缓存 (PR #2229 上线后) - -### 3. 拼参传给列表接口 - -```ts -// 伪代码 -const seasons = currentProduct.productLine?.seasons ?? []; -const firstSeason = seasons[0]; // "spring"/"summer"/"autumn"/"winter" - -const params = { - page: 1, - pageSize: 20, - status: 1, - ...(firstSeason && { seasons: firstSeason }) // 仅在有值时拼 -}; -fetch('/admin/scenic/spots?' + qs.stringify(params)); -fetch('/admin/activity/items?' + qs.stringify(params)); -``` - -### 4. 弹窗 UI 渲染 - -- **封面图**: 直接用 `coverUrl` (后端已按 seasons[0] 切换) -- **季节标签**: 用 `seasons[]` 字段渲染 4 季色块 -- **卖点预览**: 优先 `seasonHighlights`, 为 null 时回落 `highlights` - ---- - -## 前端不需要做的事 - -- ❌ **不要**改后端 -- ❌ **不要**手动拼接两个字段 (后端已统一返回) -- ❌ **不要**在产品线 seasons 为空时省略字段 — 直接不传 seasons 参数即可, 后端会走旧行为 - ---- - -## 不影响范围 - -- **仅影响**: admin 产品编辑节点弹窗 (景区/游玩项目选择器) -- **零影响**: 其他 admin 列表 (产品列表/订单/酒店等不用季节维度)、小程序 C 端 - ---- - -## 验证 - -前端改完后, 测试场景: - -1. 产品线 `seasons=['summer']` 的产品 → 弹窗景区封面变 summer 季节图, seasonHighlights 显示夏季亮点 -2. 切到产品线 `seasons=['autumn']` 的产品 → 弹窗景区封面变 autumn, seasonHighlights 改秋季亮点 -3. 产品线无 seasons → 弹窗景区显示本体封面 + seasonHighlights 为 null 时回落 highlights - ---- - -## 相关历史 - -| PR/Issue | 说明 | -|---|------| -| #2229/#2227 | 景区季节过滤 + 封面切换 + 标签 (后端) | -| #2234/#2232 | 游玩项目同款 | -| #2269/#2267 | 列表加 seasonHighlights | - ---- - -## 相关文档 - -- 后端能力 PR #2229: [wx/HL#2229](https://git.1814.love:8443/wx/HL/pulls/2229) -- 后端能力 PR #2234: [wx/HL#2234](https://git.1814.love:8443/wx/HL/pulls/2234) -- 后端能力 PR #2269: [wx/HL#2269](https://git.1814.love:8443/wx/HL/pulls/2269) diff --git a/changelogs/2026-05/14_frontend_feature_admin_activity-season-filter-and-tags.md b/changelogs/2026-05/14_frontend_feature_admin_activity-season-filter-and-tags.md deleted file mode 100644 index f2c8cdc..0000000 --- a/changelogs/2026-05/14_frontend_feature_admin_activity-season-filter-and-tags.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -date: 2026-05-14 -type: frontend-feature -module: admin-product-v2-itinerary-activity-picker -priority: medium -backend_pr: "#2234" -backend_issue: "#2232" -related: "14_frontend_feature_admin_scenic-season-filter-and-tags.md" -notify: ["@mmg"] -status: pending ---- - -# 游玩项目按产品线季节过滤 + 节点展示季节标签 - -## 需求 - -紧接景区 (#2227 / PR #2229),「从资源库添加活动」弹窗第二个 tab「**游玩项目**」也要按产品线 `seasons` 过滤 + 缩略图按季节切换 + 节点季节标签。**行为与景区完全对齐**。 - -## 后端已就位 (PR #2234 已合并并部署测试服) - -### 数据基础 - -**新建** `activity_season` 子表(Flyway V20260514_001,字段对照 `scenic_season` 复刻)。运营进后台逐个游玩项目补配季节数据后生效;未配的游玩项目 `vo.seasons` 返 `[]`。 - -老 `activity.best_season` 自由文本字段保留不动(老 UI 兼容),**不**自动迁移到新结构化子表。 - -### 接口变更 - -#### `GET /admin/activity/items` — 游玩项目列表 - -**新增 query 参数**(与景区接口同款): - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `seasons` | `List<String>` | 否 | 多选 OR 过滤,枚举 `spring/summer/autumn/winter`。传任一交集即返回。空/不传 = 不过滤 | - -请求格式(数组多参): -```http -GET /admin/activity/items?seasons=spring&seasons=autumn&pageSize=20 -``` - -**`ActivityListVO` 新增字段:** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `seasons` | `List<String>` | 该游玩项目在 `activity_season` 配置的全部季节(distinct,枚举 `spring/summer/autumn/winter`)。**节点标签直接读这个**。 | - -> ⚠️ **已有的 `coverUrl` 字段含义变更**:当 query 含 `seasons` 时,`coverUrl` 返回 **query.seasons[0] 对应的 `activity_season.cover_material_id`** 物化 URL;该季节未配/物化失败回落到主表 `coverMaterialId`。无 query.seasons 时维持主表 cover(行为不变)。 - -#### 真实响应示例 - -**请求**: `GET /admin/activity/items?pageSize=2` - -```json -{ - "code": 200, - "message": "成功", - "data": { - "total": 56, - "records": [ - { - "activityId": 3002000000000000000, - "name": "满洲里草原篝火晚会", - "subtitle": "...", - "categoryCode": "...", - "billingType": "...", - "city": "...", - "coverUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/...", - "seasons": [], - "tags": [...], - "longitude": ..., - "latitude": ... - } - ] - }, - "success": true -} -``` - -> 当前 `activity_season` 表是空的(刚建),所有游玩项目 `seasons` 都返 `[]`。**运营录数据后**,过滤会立即生效;封面切换也立即生效,行为与景区完全一致。 - -## 前端实现建议 - -### 弹窗「游玩项目」tab - -参考景区 tab 的实现完全对照: - -1. 弹窗打开时调列表接口透传产品线 `seasons`: - ```js - const params = new URLSearchParams() - productLineSeasons.forEach(s => params.append('seasons', s)) - await api.get(`/admin/activity/items?${params}&pageSize=20`) - ``` -2. 列表行的**缩略图**直接用 VO 返回的 `coverUrl`(后端已切换好) -3. 列表行的**季节标签**渲染 `vo.seasons` 数组,**4 色与景区一致**: - - `spring` → 春绿 `#67C23A` - - `summer` → 夏蓝 `#409EFF` - - `autumn` → 秋橙 `#E6A23C` - - `winter` → 冬蓝灰 `#909399` - -### 已选节点(行程卡片上) - -行程节点 ACTIVITY 类型的 `InternalProductDetailVO.NodeItem.seasons` 已透传 — 在游玩项目节点卡片上渲染同款季节标签(可多个)。**与景区节点同款组件即可复用**。 - -### 兜底 - -- 老游玩项目没配 `activity_season` 的,`vo.seasons` 返 `[]`,前端不渲染标签即可 -- `coverUrl` 任何时候都不会因为新逻辑变 null(已做回落) - -## 工单 & PR - -- Backend Issue: #2232 -- Backend PR: #2234 (squash merged dev,已部署测试服) -- 测试服真测通过: 基线 total=56 ✅ / VO seasons 字段 ✅ / seasons=autumn 过滤 total=0(数据空) / 反例 seasons=xxx 总=0 ✅ / coverUrl 物化 ✅ - -## 关联 - -景区同款实施: `14_frontend_feature_admin_scenic-season-filter-and-tags.md`(PR #2229 / Issue #2227) - -弹窗的剩余两个 tab「餐厅」「服务」**暂未实施季节过滤** — 业务侧确认需要再开工单。 diff --git a/changelogs/2026-05/14_frontend_feature_admin_scenic-season-filter-and-tags.md b/changelogs/2026-05/14_frontend_feature_admin_scenic-season-filter-and-tags.md deleted file mode 100644 index 8cf2aec..0000000 --- a/changelogs/2026-05/14_frontend_feature_admin_scenic-season-filter-and-tags.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -date: 2026-05-14 -type: frontend-feature -module: admin-product-v2-itinerary-scenic-picker -priority: medium -backend_pr: "#2229" -backend_issue: "#2227" -notify: ["@mmg"] -status: pending ---- - -# 产品设计选景区按产品线季节过滤 + 节点展示季节标签 - -## 需求 - -产品设计行程编辑器的「**从资源库添加活动 → 景区景点**」弹窗当前列出全部景区，无视产品线季节。期望: - -1. 弹窗景区列表按当前产品线的 `seasons` 过滤 — 比如产品线是秋季就只看到秋季景区 -2. 列表行的**景区缩略图**按季节切换(春→春景图、秋→秋景图) -3. **节点上**(已添加进行程的景区卡片)显示该景区配置的所有季节标签(可多个) - -## 后端已就位 (PR #2229 已合并并部署测试服) - -### 数据基础 - -景区已有独立 `scenic_season` 子表，每季节可配封面/轮播/视频。产品线 `seasons` 已是 `List<String>`(JSON 数组多选)。 - -### 接口变更 - -#### 1. `GET /admin/scenic/spots` — 景区列表 - -**新增 query 参数:** - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `seasons` | `List<String>` | 否 | 多选 OR 过滤，枚举 `spring/summer/autumn/winter`。传任一交集景区即返回。空/不传 = 不过滤 | - -请求格式(数组多参): -```http -GET /admin/scenic/spots?seasons=spring&seasons=autumn&pageSize=20 -``` - -**`ScenicSpotListVO` 新增 2 个字段:** - -| 字段 | 类型 | 说明 | -|------|------|------| -| `seasons` | `List<String>` | 该景区在 `scenic_season` 配置的全部季节(distinct,枚举 `spring/summer/autumn/winter`)。**节点标签直接读这个**。 | - -> ⚠️ **已有的 `coverUrl` 字段含义变更**: 当 query 含 `seasons` 时，`coverUrl` 返回 **query.seasons[0] 对应的 `scenic_season.cover_material_id`** 物化 URL；该季节未配/物化失败回落到主表 `coverMaterialId`。无 query.seasons 时维持主表 cover(行为不变)。 - -#### 真实响应示例 - -**请求**: `GET /admin/scenic/spots?seasons=winter&pageSize=2` - -```json -{ - "code": 200, - "message": "成功", - "data": { - "total": 17, - "records": [ - { - "scenicId": 3001000000000000019, - "name": "中俄边境公路（卡线）", - "cityName": "鄂温克族自治旗", - "coverUrl": "https://images.unsplash.com/photo-1511131341194-...?w=800&q=80", - "seasons": ["spring", "summer", "autumn", "winter"], - "tags": [{"tagId":"3","tagName":"摄影打卡","tagColor":"#409EFF","tagType":0}], - "honors": ["AAA","最美边境公路"], - "highlights": "...", - "longitude": 119.756219, - "latitude": 49.153445, - "rating": 0.0, - "viewCount": 31200, - "sortOrder": 19, - "status": 1 - } - ] - }, - "success": true -} -``` - -同一 scenicId 在 `seasons=spring` 时 `coverUrl` 会变成春景图，无 query 时变回主表 OSS 封面 — 已测试服真测验证切换正确。 - -**反例**(不存在的季节): -```http -GET /admin/scenic/spots?seasons=xxx -→ { "code": 200, "data": { "total": 0, "records": [] } } -``` - -#### 2. 行程节点 VO 透传 `seasons` - -| VO 类 | 端 | 字段 | 状态 | -|-------|-----|------|------| -| `InternalProductDetailVO.NodeItem` | admin | `seasons: List<String>` | ✅ 已落地，SCENIC 节点会回填 | -| `MpProductDetailInternalVO.ItineraryNodeItem` | mp | `seasons` | ⚠️ M2 占位，**当前永远 null**(注释已标注) | - -> Mp 端 itinerary 当前走 M2 占位降级返空数组，等 M2 节点详情上线后才填充。**短期 Mp 端不要依赖 seasons 字段**。 - -## 前端实现建议 - -### 弹窗「从资源库添加活动 → 景区景点」 - -1. 弹窗打开时取当前编辑的产品线 `seasons`(产品线详情接口已返)，**调景区列表时透传**: - ```js - const params = new URLSearchParams() - productLineSeasons.forEach(s => params.append('seasons', s)) - await api.get(`/admin/scenic/spots?${params}&pageSize=20`) - ``` -2. 列表行的**缩略图**直接用 VO 返回的 `coverUrl`(后端已按 `seasons[0]` 切换好)。 -3. 列表行的**季节标签**渲染 `vo.seasons` 数组，建议 4 色: - - `spring` → 春绿 `#67C23A` - - `summer` → 夏蓝 `#409EFF` - - `autumn` → 秋橙 `#E6A23C` - - `winter` → 冬蓝灰 `#909399` - -### 已选节点(行程卡片上) - -行程节点详情 admin 端 `InternalProductDetailVO.NodeItem.seasons` 已有 — 在景区节点卡片上渲染同样的 4 色季节标签(可多个)。 - -### 兜底 - -- 老景区数据没配 `scenic_season` 的，`vo.seasons` 返 `[]` 空数组，前端不渲染标签即可。 -- `coverUrl` 任何时候都不会因为新逻辑变 null(已做回落)。 - -## 涉及前端文件 (仅供参考定位) - -- 弹窗组件: 大概率在 `D:\work2\hl-ui\src\views\product-v2\` 下的 itinerary editor 子组件 -- 景区资源 picker: 搜 `从资源库添加活动` / `ScenicResourcePicker` / `scenic-spot-list` - -## 工单 & PR - -- Backend Issue: #2227 -- Backend PR: #2229 (squash merged dev,已部署测试服) -- 测试服真测通过: 过滤 (66→18 autumn/17 winter/0 xxx) ✅ / OR 多选 ✅ / 季节封面切换 ✅ / VO seasons 按 scenic_id 分组 ✅ diff --git a/changelogs/2026-05/14_frontend_feature_admin_travel-guarantee-items-drag-sort.md b/changelogs/2026-05/14_frontend_feature_admin_travel-guarantee-items-drag-sort.md deleted file mode 100644 index cf1812b..0000000 --- a/changelogs/2026-05/14_frontend_feature_admin_travel-guarantee-items-drag-sort.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -date: 2026-05-14 -type: frontend-feature -module: admin-product-v2-travel-guarantee -priority: low -notify: ["@mmg"] -status: pending ---- - -# 行程管理 → 行程保障: 编辑模板时「保障项」列表加拖拽排序 - -## 需求 - -正式环境 (admin.1814.love/product/travel-guarantee) 「编辑安全保障模板」抽屉里, 「保障项」区域当前是固定顺序的 #1 / #2 / #3 / ... 卡片列表(每张卡片含图标、标题、描述), **无法调整顺序**。 - -运营需要能拖拽调整保障项顺序, 例如把「保险保障」从 #3 拖到 #1。 - -## 范围: 纯前端, 后端不动 - -经 `/@dev` 调研后端 `hl-product-service-v2`: - -| 项 | 现状 | -|---|------| -| 表 `travel_guarantee_template` | 用 `items` JSON 字段存全部保障项数组 `[{icon, title, description}]` | -| `TravelGuaranteeTemplateDO.items` | 字符串字段, JSON 数组 | -| 保存接口 `POST /admin/travel-guarantee-template` | 接收 `TravelGuaranteeTemplateSaveReqVO.items: List<GuaranteeItem>` 原样落库 | -| 详情接口 `GET /admin/travel-guarantee-template/{id}` | 原样吐回数组 | - -**关键: JSON 数组天然有序, 后端按前端传过来的数组顺序原样存原样取, 不做任何重排**。所以前端拖拽完后, 把数组按新顺序 PUT 给现有 save 接口即可, **后端零改动**。 - -## 前端实现建议 - -「编辑安全保障模板」抽屉的「保障项」区域: - -1. 每张 #N 卡片左侧加拖拽手柄(grip icon, 鼠标 hover 变 `cursor: grab`) -2. 用 vuedraggable / 等价拖拽库实现纵向拖拽排序 -3. 拖拽过程中 #N 序号实时刷新(#1/#2/#3 始终按当前位置) -4. 保存时**按新顺序**传 `items` 数组给 `POST /admin/travel-guarantee-template`(接口签名不变) - -## 接口 (无变化, 仅作前端参考) - -```http -POST /admin/travel-guarantee-template -Content-Type: application/json - -{ - "templateId": 123, // 编辑模式带 ID - "name": "额吉的故乡系列", - "items": [ - { "icon": "...", "title": "保险保障·安全托底", "description": "..." }, // 用户拖到 #1 - { "icon": "...", "title": "透明披露·无强制消费", "description": "..." }, // 拖到 #2 - { "icon": "...", "title": "独立用车·专属团队", "description": "..." } // 拖到 #3 - ], - ... -} -``` - -返回照旧, 不需要发新版本接口。 - -## 验证清单(前端改完自测) - -- [ ] 「行程管理 → 行程保障」点已有模板「额吉的故乡系列」进编辑抽屉, 拖动手柄能调整保障项顺序 -- [ ] 拖拽过程中 #N 序号(#1/#2/#3) 实时刷新 -- [ ] 保存后重进编辑页, 顺序与上次保存的一致 -- [ ] 新增模板时也能拖拽排序后再首次保存 -- [ ] 删除某项后剩余项序号自动重排, 不残留空 #N -- [ ] 移动端 / 触摸屏拖拽体验可用(如果运营会用 iPad) - -## 后端无需任何改动 - -`TravelGuaranteeTemplateDO.items` 是 JSON 数组字段, 前端传什么顺序后端就存什么顺序。这条 changelog 只为通知前端开做。 - -@mmg 看下 hl-ui 里行程保障模板编辑组件, 优先级 P3 — 不阻塞功能但运营反馈过, 顺手时排上。 diff --git a/changelogs/2026-05/14_frontend_playservice_add_season_drawer.md b/changelogs/2026-05/14_frontend_playservice_add_season_drawer.md deleted file mode 100644 index 4f8dc06..0000000 --- a/changelogs/2026-05/14_frontend_playservice_add_season_drawer.md +++ /dev/null @@ -1,155 +0,0 @@ -# [前端] 游玩项目编辑页加「季节内容」Drawer (对照景区已有的) - -> **服务**: 前端 hl-ui (管理端) -> **后端 PR**: #2262 (Closes #2257) 已上线 -> **日期**: 2026-05-14 -> **影响范围**: 管理端 资源管理 → 游玩项目编辑页(运营配 4 季内容入口) - ---- - -## ⚠️ 关键变化 - -后端 ActivitySeasonController admin CRUD 已上线测试服, **但前端 `views/resource/playservice/` 目录缺 SeasonDrawer.vue, 运营无处配 4 季内容** → activity_season 表全空 → `/admin/activity/items` 接口 seasons 字段恒返 `[]` → 弹窗无季节标签 + 节点封面无法按季节切换。 - -景区那边早就有 `views/resource/scenic/SeasonDrawer.vue` (322 行), 游玩项目这边缺一份对照实现。 - ---- - -## 现状对比 - -| 模块 | 编辑页 SeasonDrawer | 后端 API | DB 表 | -|---|---|---|---| -| 景区 | ✅ 已有 `views/resource/scenic/SeasonDrawer.vue` (322 行) | ✅ ScenicSeasonController | ✅ scenic_season 表已配数据 | -| **游玩项目** | ❌ **缺** `views/resource/playservice/SeasonDrawer.vue` | ✅ ActivitySeasonController (PR #2262 已上线) | ⚠️ activity_season 表全空 (因为没入口配) | - ---- - -## 后端 API 已就绪 (PR #2262) - -``` -GET /admin/activity/item/{activityId}/seasons 获取 4 季列表 -PUT /admin/activity/item/{activityId}/season/{seasonType} upsert 单季 -DELETE /admin/activity/item/{activityId}/season/{seasonType} 删除单季 -``` - -`seasonType` ∈ `spring/summer/autumn/winter` - -幂等：由 `(activity_id, season_type)` 唯一约束保证, PUT 已存在 → 更新, 否则 → 插入。 - ---- - -## 前端 4 步操作 - -### Step 1: `src/api/playservice.js` 加 3 个方法 - -照搬 `src/api/scenic.js` 同款实现： - -```javascript -/** 获取游玩项目全部季节内容 */ -export function getActivitySeasonList(activityId) { - return http.get(`/activity/item/${activityId}/seasons`) -} - -/** 保存/更新游玩项目单个季节 (upsert) */ -export function updateActivitySeason(activityId, seasonType, data) { - return http.put(`/activity/item/${activityId}/season/${seasonType}`, data) -} - -/** 删除游玩项目单个季节 */ -export function deleteActivitySeason(activityId, seasonType) { - return http.delete(`/activity/item/${activityId}/season/${seasonType}`) -} -``` - -### Step 2: 复制景区 SeasonDrawer.vue - -``` -cp src/views/resource/scenic/SeasonDrawer.vue \ - src/views/resource/playservice/SeasonDrawer.vue -``` - -### Step 3: 内部全局替换 - -打开新文件 `src/views/resource/playservice/SeasonDrawer.vue`, 替换： - -- `scenicId` → `activityId` -- `getScenicSeasonList` → `getActivitySeasonList` -- `updateScenicSeason` → `updateActivitySeason` -- `deleteScenicSeason` → `deleteActivitySeason` -- import 路径从 `@/api/scenic` → `@/api/playservice` - -数据流/props/emit/UI 结构完全不变。 - -### Step 4: 入口按钮 - -`src/views/resource/playservice/index.vue` 添加触发 SeasonDrawer 的按钮 + 状态变量, 照搬 `src/views/resource/scenic/index.vue` 入口代码。 - ---- - -## VO 字段 (与 ScenicSeasonVO 完全对照) - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| seasonId | Long | - | 季节内容 ID (后端返回, 前端不填) | -| activityId | Long | - | 游玩项目 ID (path 参数) | -| seasonType | String | ✅ | spring/summer/autumn/winter | -| seasonName | String | ❌ | 季节别名 ("赏秋季"/"冰雪季"/"樱花季") | -| monthStart | Integer | ✅ | 1-12 | -| monthEnd | Integer | ✅ | 1-12, 可跨年如冬季 12-2 | -| description | String | ❌ | 季节简介 (TEXT) | -| highlights | String | ❌ | 季节亮点短文案 (VARCHAR 500) | -| playGuide | String | ❌ | 该季节游玩攻略 (富文本 MEDIUMTEXT) | -| tips | String | ❌ | 注意事项 (TEXT) | -| coverMaterialId | Long | ❌ | 季节封面素材 ID | -| bannerMaterialIds | List\<Long\> | ❌ | 季节轮播图素材 ID 列表 | -| videoMaterialIds | List\<Long\> | ❌ | 季节视频素材 ID 列表 | - ---- - -## 完成后效果链路 - -``` -运营配 4 季内容 - ↓ -activity_season 表有数据 - ↓ -/admin/activity/items 接口 seasons[] 非空 - ↓ -产品编辑页弹窗游玩项目 tab 显示季节标签 + seasonHighlights 文案 - ↓ -节点 resourceCover 按 productLine.seasons[0] 自动切对应季节封面 -``` - ---- - -## 关联工作 (打包做) - -同步还要做这件事 → 见 [14_frontend_admin_list_should_pass_seasons_param.md](./14_frontend_admin_list_should_pass_seasons_param.md) 或 [14_feat_admin_list_productline_resolve_seasons.md](./14_feat_admin_list_productline_resolve_seasons.md): - -弹窗 `src/views/product/edit/components/modals/ResourcePickerModal.vue` line 57-62 改 1 行加 `productLineId` 参数, 让弹窗封面按当前产品季节切换。 - -两件事都做完才有完整效果。 - ---- - -## 不影响范围 - -- 后端 API 已上线, 前端不做不影响其他功能 (只是弹窗无季节标签 + 节点 cover 不切季节) -- 仅影响管理端游玩项目维护 (新增前端入口) + 弹窗显示效果 - ---- - -## 相关历史 - -| PR | Issue | 说明 | -|----|-------|------| -| #2262 | #2257 | 后端 ActivitySeasonController admin CRUD (本任务的数据基础) | -| #2229 | #2227 | 景区季节系列 (含 SeasonDrawer.vue, 本任务参照范本) | -| #2234 | #2232 | 游玩项目季节过滤 + 标签 (但漏前端入口) | - ---- - -## 相关后端 changelog - -- [14_feat_admin_activity_season_admin_crud.md](./14_feat_admin_activity_season_admin_crud.md) — 后端 PR #2262 ActivitySeasonController 完整 API 文档 -- [14_feat_admin_list_productline_resolve_seasons.md](./14_feat_admin_list_productline_resolve_seasons.md) — 弹窗按 productLineId 自动 resolve seasons (前端打包做的另一件事) diff --git a/changelogs/2026-05/14_frontend_resource_list_add_seasons_column.md b/changelogs/2026-05/14_frontend_resource_list_add_seasons_column.md deleted file mode 100644 index d1bf1df..0000000 --- a/changelogs/2026-05/14_frontend_resource_list_add_seasons_column.md +++ /dev/null @@ -1,122 +0,0 @@ -# [前端] 景区/游玩项目 list 列表加"季节"标签列 - -> **服务**: 前端 hl-ui (管理端) -> **后端 PR**: 无新 PR (能力 PR #2229/#2234 已上线) -> **日期**: 2026-05-14 -> **影响范围**: 管理端 资源管理 → 景区管理 + 游玩项目管理 列表表格 - ---- - -## ⚠️ 关键变化 - -后端 `/admin/scenic/spots` 和 `/admin/activity/items` 列表 records 已包含 `seasons: ["spring","summer","autumn","winter"]` 字段（PR #2229/#2234 已上线测试服真测 PASS），但前端 list 表格**没有显示季节列**。 - -需要加 "季节" 标签列，4 季用色块展示，未配置的季节灰色 disabled。 - ---- - -## 后端字段证据 - -```bash -GET /admin/scenic/spots?page=1&pageSize=3&status=1 -→ records[0].seasons = ["spring","summer","autumn","winter"] // 中俄边境公路 4 季全配 -→ records[1].seasons = ["spring","autumn"] // 只配了春秋两季 -→ records[2].seasons = [] // 未配任何季节 -``` - -字典 `product_season` 已含 4 季 dictValue + dictLabel + icon + color，前端直接读字典渲染色块（与产品编辑页"季节标签"组件一致）。 - ---- - -## 精确改法 - -### 1. 景区列表 - -**文件**: `D:/work2/hl-ui/src/views/resource/scenic/index.vue` line 417-456 - -在 `columns` 数组里加一列（建议放在"标签"列后面）: - -```js -const columns = [ - { type: 'selection', width: 50 }, - { title: '景区名称', key: 'name', width: 220, render: ... }, - { title: '城市', key: 'cityName', width: 100 }, - { title: '标签', key: 'tags', width: 160, render: ... }, - // === 新增季节列 === - { - title: '季节', - key: 'seasons', - width: 140, - render: (row) => renderSeasonTags(row.seasons), // 复用产品编辑页弹窗的 SeasonTags 组件 - }, - { title: '状态', key: 'status', width: 80, render: ... }, - ... -] -``` - -### 2. 游玩项目列表 - -**文件**: `D:/work2/hl-ui/src/views/resource/playservice/index.vue` line 495 - -同款加列。 - -### 3. 复用现有 SeasonTags 组件 - -弹窗 `ResourcePickerModal.vue` 应该已有渲染 4 季色块的逻辑（弹窗里景区右侧"春 夏 秋 冬"已配/未配色块），直接抽组件复用。 - -如果还没抽，可参考字典 `product_season` 渲染： -```js -const seasonDict = dictStore.get('product_season') -// seasonDict = [ -// { dictValue: 'spring', dictLabel: '春', color: '#5A8C3C', icon: '<svg>...' }, -// { dictValue: 'summer', dictLabel: '夏', color: '...' }, -// ... -// ] - -function renderSeasonTags(seasons = []) { - const set = new Set(seasons) - return h('div', { style: 'display:flex;gap:4px' }, - seasonDict.map(s => - h('span', { - style: { - background: set.has(s.dictValue) ? s.color : '#e0e0e0', - color: '#fff', - padding: '2px 6px', - borderRadius: '4px', - fontSize: '12px', - opacity: set.has(s.dictValue) ? 1 : 0.5, - } - }, s.dictLabel) - ) - ) -} -``` - -效果同产品编辑页弹窗的季节色块：已配的彩色，未配的灰色。 - ---- - -## 验证 - -改完后： -- 景区列表 → 中俄边境公路（卡线）那行"季节"列显示 "春 夏 秋 冬" 4 个彩色色块 -- 中俄边境公路季节内容已配齐, 4 个色块都彩色高亮 -- 未配任何季节的景区, 4 个色块全灰 - -游玩项目同款。 - ---- - -## 不影响范围 - -- 仅前端表格列增加, 后端字段已就绪 -- 不影响其他列 / 操作按钮 / 弹窗 / 编辑页 - ---- - -## 相关后端 PR / 文档 - -- PR #2229 (Closes #2227): 景区列表加 seasons 字段 -- PR #2234 (Closes #2232): 游玩项目同款 -- 字典 `product_season`: GET /admin/dict/all 已含 4 季 + icon + color + remark -- 相关 changelog: [14_frontend_admin_list_should_pass_seasons_param.md](./14_frontend_admin_list_should_pass_seasons_param.md) (弹窗补传 seasons 参数, 与本任务正交可独立做) diff --git a/changelogs/2026-05/14_frontend_season_drawer_remove_month_selector.md b/changelogs/2026-05/14_frontend_season_drawer_remove_month_selector.md deleted file mode 100644 index 17cf681..0000000 --- a/changelogs/2026-05/14_frontend_season_drawer_remove_month_selector.md +++ /dev/null @@ -1,146 +0,0 @@ -# [前端][紧急] SeasonDrawer 删月份选择器 (后端已自动赋值, 字典有全局定义) - -> **服务**: 前端 hl-ui (管理端) -> **后端 PR**: #2295 (Closes #2291) 已上线 -> **日期**: 2026-05-14 -> **影响范围**: 管理端 景区/游玩项目编辑页 SeasonDrawer 季节内容表单 -> **状态**: P1 — 后端已上线, 前端需删 monthStart/monthEnd 选择器 - ---- - -## ⚠️ 关键变化 - -后端 PR #2295 (Closes #2291) 已上线测试服: -- SaveRequest **删了 monthStart/monthEnd 字段**, 前端继续传会被忽略 -- 后端 SeasonMonthRangeUtil 按 seasonType 自动赋值: spring→3-5 / summer→6-8 / autumn→9-11 / winter→12-2 (跨年) -- 字典 `product_season` 的 remark 字段全局定义了 "3-5月/6-8月/9-11月/12-2月", 跟硬编码一致 - -前端 SeasonDrawer.vue 的"时间范围"月份选择器**应删除**, 让用户不再操作月份。 - ---- - -## 精确改法 - -**文件**: `D:/work2/hl-ui/src/views/resource/scenic/SeasonDrawer.vue` - -### 1. 删模板的月份选择器 (line 26 + line 48-60) - -**删 line 26 `v-if="seasonContents[season.value]?.monthStart && seasonContents[season.value]?.monthEnd"`**: -现在不依赖 monthStart/monthEnd 渲染, 改用 seasonType 是否存在配置内容判断, 或者直接显示。 - -**删 line 48-60 整个 `<n-form-item label="时间范围">` 块**: - -```vue -<!-- 删这整段 (line 48-60) --> -<n-form-item label="时间范围"> - <n-input-group> - <n-select - v-model:value="seasonContents[season.value].monthStart" - ... - /> - <span>至</span> - <n-select - v-model:value="seasonContents[season.value].monthEnd" - ... - /> - </n-input-group> -</n-form-item> -``` - -可改为只读展示 (可选, 也可不显示): -```vue -<!-- 可选: 只读显示, 不让用户改 --> -<n-form-item label="时间范围"> - <span>{{ seasonMonthRangeLabel(season.value) }}</span> -</n-form-item> - -<!-- helper --> -const seasonMonthRangeLabel = (type) => ({ - spring: '3-5月', - summer: '6-8月', - autumn: '9-11月', - winter: '12-2月 (跨年)', -})[type] || '-' -``` - -或者直接读字典 `product_season` 的 `remark` 字段 (推荐, 字典是真相): -```js -const dictStore = useDictStore() -const seasonMonthRangeLabel = (type) => - dictStore.get('product_season')?.find(d => d.value === type)?.remark || '-' -``` - -### 2. 删 form data 初始字段 (line 181-188) - -```js -// 删 line 181 那个 i+1 月份选项数组 (如果只用于月份选择器) -// 删 line 188-189: -monthStart: null, -monthEnd: null, -``` - -### 3. 删保存时的 month 字段提取 (line 247-248, 273-279) - -`saveSeason` 函数里: -```js -// 删 line 247-248 不再从 item 读 month -// 删 line 273-279 不再校验 + 提交 month - -// 改为: -const payload = { - seasonName: form.seasonName, - description: form.description, - highlights: form.highlights, - playGuide: form.playGuide, - tips: form.tips, - // ... 其他字段 - // 不传 monthStart/monthEnd -} -await updateScenicSeason(scenicId, seasonType, payload) -``` - -### 4. 删 line 302 报错文案 - -```js -// 删 message.info('未配置任何季节的时间范围，无需保存') -// 改为基于其他字段是否有内容判断 -``` - ---- - -## 游玩项目同款 (前端待补 SeasonDrawer 落地后) - -`views/resource/playservice/SeasonDrawer.vue` (尚未创建, 见 [14_frontend_playservice_add_season_drawer.md](./14_frontend_playservice_add_season_drawer.md)) **直接照此规范实现, 不要复制旧 scenic SeasonDrawer 的月份选择器**。 - ---- - -## 验证 - -改完后: -1. 景区/游玩项目季节内容编辑表单**不再显示**"时间范围 X月至X月"控件 (或只读显示) -2. PUT 保存季节内容不传 monthStart/monthEnd -3. GET 季节列表后端仍返 monthStart/monthEnd (后端自动赋值), 前端可只读展示 - -测试服 curl 验证 PASS (后端已部署): -``` -PUT /admin/scenic/spot/{id}/season/spring (body 无 month) → 200 -GET /admin/scenic/spot/{id}/seasons → spring 这条 monthStart=3 monthEnd=5 -``` - ---- - -## 不影响范围 - -- 后端 VO 仍返 monthStart/monthEnd 字段, 前端可只读展示 -- DB 字段保留, 老数据兼容 -- 季节内容其他字段 (seasonName/description/highlights/playGuide/tips/封面/轮播/视频) 完全不动 - ---- - -## 相关 PR / Issue - -- 后端 PR #2295: [wx/HL#2295](https://git.1814.love:8443/wx/HL/pulls/2295) -- 后端 Issue #2291: [wx/HL#2291](https://git.1814.love:8443/wx/HL/issues/2291) -- 字典 `product_season` 已有全局月份定义 (remark 字段) -- 与游玩项目 SeasonDrawer 待新建任务关联: [14_frontend_playservice_add_season_drawer.md](./14_frontend_playservice_add_season_drawer.md) -- 与合并 changelog: [14_feat_season_month_auto_and_description_dynamic_cover.md](./14_feat_season_month_auto_and_description_dynamic_cover.md) (B 部分) diff --git a/changelogs/2026-05/15_feat_auth_refresh_token_sliding.md b/changelogs/2026-05/15_feat_auth_refresh_token_sliding.md deleted file mode 100644 index 071fed4..0000000 --- a/changelogs/2026-05/15_feat_auth_refresh_token_sliding.md +++ /dev/null @@ -1,234 +0,0 @@ -# auth: refreshToken 滑动续期 + 双 token 机制(admin + 小程序 user) - -> **服务**: hl-user-service (8081) + hl-mp-service (8085) + hl-gateway (8080) -> **PR**: #2312 (已合 dev,测试服待 Deploy Panel 部署) -> **Issue**: #2309 -> **日期**: 2026-05-15 -> **影响范围**: 管理后台 hl-ui + 微信小程序两端的登录态 / 401 拦截器 - ---- - -## ⚠️ 关键变化(对前一版 #2285 的演进) - -| 维度 | 上一版 PR #2285 (2026-05-14) | 本版 PR #2312 (2026-05-15) | -|------|--------------------------------|------------------------------| -| 适用端 | 仅 admin | **admin + 小程序 user 双端** | -| accessToken TTL | admin 2h | **admin 30 分钟 / user 30 分钟** | -| refreshToken TTL | admin 7d | **admin 7d / user 90d** | -| 续期模式 | refresh 字符串**轮转**(每次换新串,旧立即失效) | **滑动续期** — refresh 字符串**不换**,只刷 Redis 中 jti 的 TTL | -| 灰度策略 | 直接切 | **网关新 key 优先 + 旧 key fallback**(2026-05-22 删 fallback) | -| 字段名 | data.token = access (兼容) + refreshToken | **同上,新增 data.accessToken 显式字段,data.token 仍保留** | - -**核心新原则**:**refreshToken 字符串后端不换,前端无需更新本地存的 refresh,只更新 access**。这是与 #2285 最大的行为差异 —— 上一版前端必须每次 refresh 后立即覆盖本地 refresh,这一版**不需要**(覆盖也无害)。 - ---- - -## 一、背景 - -PR #2285 上线后用户中途反馈:**rotation 模式遇到弱网/重复请求/双标签页时,新 refresh 还没收到旧 refresh 已被废,触发误踢登录**。本版改为滑动续期:refresh 字符串保持稳定 7d/90d 内不变,只刷 Redis TTL,既解决误踢又保留"长期不活跃自动失效"语义。同时把小程序 user 端也接入(此前 user 端是无 refresh 机制 90 天硬到期)。 - -TTL 配置(线上确认值): - -| 端 | accessToken | refreshToken | nacos key | -|----|-------------|--------------|-----------| -| admin | 30 分钟 (1800s) | 7 天 (604800s) | `auth.jwt.admin-access-ttl-seconds` / `auth.jwt.admin-refresh-ttl-seconds` | -| 小程序 user | 30 分钟 (1800s) | 90 天 (7776000s) | `auth.jwt.user-access-ttl-seconds` / `auth.jwt.user-refresh-ttl-seconds` | - -灰度期: **2026-05-15 ~ 2026-05-22**,7 天后后端会清掉网关里的旧 key fallback 块。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | admin 刷新令牌 | POST | `/admin/auth/refresh` | 行为变化 | 从字符串轮转改滑动续期,refresh 不换串 | -| 2 | 小程序刷新令牌 | POST | `/mp/user/refresh` | **新增** | 小程序端首次有 refresh 能力 | -| 3 | user-service 刷新令牌(内部) | POST | `/user/refresh` | **新增** | hl-mp-service Feign 调用入口 | -| 4 | user-service 刷新令牌(MP 内部) | POST | `/internal/mp/user/refresh` | **新增** | mp-service → user-service Feign | -| 5 | admin 所有签发 token 接口 | - | login/2fa/switch-role/wechat-qr/check 等 | 响应字段微调 | data 内仍是 token+refreshToken+accessTokenExpiresIn+refreshTokenExpiresIn,**额外多 accessToken 字段** | -| 6 | 小程序 user login + login-by-sms | POST | `/mp/user/login` 等 | 响应新增 | data 多 refreshToken+双 expiresIn+accessToken 字段 | - ---- - -## 三、登录响应字段(灰度期前端可零改动) - -```json -{ - "code": 200, - "data": { - "token": "eyJ...ACCESS", // 向后兼容字段, = accessToken - "accessToken": "eyJ...ACCESS", // 新字段, 同 token - "refreshToken": "eyJ...REFRESH", // 新字段, 长效 7d/90d - "accessTokenExpiresIn": 1800, // 秒 - "refreshTokenExpiresIn": 604800, // 秒, admin=604800/user=7776000 - "...其它现有字段保持不变" - } -} -``` - -**灰度期内前端不改任何代码,继续读 `data.token` 即可正常登录使用,只是 30 分钟后会被踢**(因为没用 refresh)。要做无感续期才需要新增 refresh 拦截器。 - ---- - -## 四、新接口详情 - -### 1. POST /admin/auth/refresh (管理端) - -```json -// Request -{ "refreshToken": "eyJ...REFRESH" } - -// Response 200 -{ - "code": 200, - "data": { - "token": "...新 access...", - "accessToken": "...新 access...", - "refreshToken": "...原 refresh,字符串不变...", - "accessTokenExpiresIn": 1800, - "refreshTokenExpiresIn": 604800 - } -} - -// Response 401 — refresh 已过期 / 已被 logout 作废 / 篡改 / tokenKind 错 -{ "code": 401, "msg": "刷新令牌无效或已过期,请重新登录" } -``` - -- **不需要 Authorization 头**(网关 SKIP_URLS 已加白名单) -- **refresh JWT 字符串保持不变**,仅刷新 Redis 中 jti 的 TTL -- 错误码: `200209 REFRESH_TOKEN_INVALID` / `200210 REFRESH_TOKEN_REPLAY` / `200211 TOKEN_KIND_MISMATCH` - -### 2. POST /mp/user/refresh (小程序端,新接口) - -请求 / 响应结构同上,`refreshTokenExpiresIn = 7776000` (90 天)。 - -- **不需要 Authorization 头** -- 链路: 小程序 → hl-mp-service `MpUserController` → `MpUserAggregationService` → `MpUserFeignClient.refreshToken()` → hl-user-service `InternalMpUserController` `POST /internal/mp/user/refresh` - -### 3. logout 行为(无契约变化,但行为补强) - -`POST /admin/auth/logout` / `POST /mp/user/logout` 后端同时清: -- access 白名单 key (新+旧两套) -- refresh 白名单 key - -logout 后立即调 refresh 会 401。 - ---- - -## 五、自动 refresh 拦截器实现要点 (@mmg) - -### admin 端 (axios) - -```js -// 单飞锁防并发 401 一起触发多次 refresh -let refreshing = null; - -async function onResponseError(err) { - // 本项目 HTTP 总是 200,401 在 body.code,也要拦 - const code = err.response?.data?.code; - if ((code === 401 || err.response?.status === 401) && !err.config._retried) { - if (!refreshing) { - refreshing = (async () => { - const r = await axios.post('/admin/auth/refresh', { - refreshToken: localStorage.getItem('admin_refresh') - }); - if (r.data?.code !== 200) throw new Error('refresh failed'); - // 关键: refreshToken 字符串和原来一样,但 accessToken 变了 - localStorage.setItem('admin_access', r.data.data.accessToken); // 或 .token - // refreshToken 不需要更新(后端不换串),但更新一下也无害 - localStorage.setItem('admin_refresh', r.data.data.refreshToken); - })().finally(() => { refreshing = null; }); - } - try { - await refreshing; - err.config._retried = true; - err.config.headers.Authorization = `Bearer ${localStorage.getItem('admin_access')}`; - return axios.request(err.config); - } catch (refreshErr) { - localStorage.removeItem('admin_access'); - localStorage.removeItem('admin_refresh'); - router.push('/login'); - } - } - throw err; -} -``` - -### 小程序端 - -同样的 401 拦截思路,把 `axios` 换成 `wx.request` 包装,storage 用 `wx.setStorageSync('user_refresh', ...)`,refresh 端点 `/mp/user/refresh`。 - -⚠️ **复用同一 refreshToken 字符串** — 后端不换串,你前端**无需**更新 refreshToken,只需更新 accessToken / token 字段。这与 PR #2285 的行为不同。 - ---- - -## 六、安全注意 - -1. **refreshToken 不要带在业务请求里**,只在调 `/admin/auth/refresh` 或 `/mp/user/refresh` 时用 -2. **refreshToken 不要传给 Authorization 头** — 网关会显式拒绝(`tokenKind=REFRESH 不能用于业务接口`,401) -3. logout 时要把 storage 里的 token + refreshToken 都清掉 -4. accessToken 30 分钟 TTL,即使被泄露窗口期短;refreshToken 7d/90d TTL 长,泄露后果严重 — 优先存 secure storage(小程序 `wx.setStorage` 即可,管理后台用 httpOnly cookie 不现实就用 localStorage,**禁止打印到 console / 上传到第三方 SDK**) -5. switchRole / changePassword / 改密 / 删 admin / 锁定账号 等场景后端会主动清 refresh,前端调 refresh 收到 401 时直接跳登录即可 - ---- - -## 七、灰度兼容期具体行为(2026-05-15 ~ 2026-05-22) - -| 场景 | 行为 | -|------|------| -| 旧前端 (只读 data.token,不调 refresh) | ✓ 正常工作 | -| 旧前端 access 30 分钟后过期 | ⚠️ 30 分钟后 401,被迫重登(因为没用 refresh) | -| 新前端 (调 refresh) | ✓ 滑动续期,7d/90d 内活跃永不重登 | -| 灰度期内旧 admin_token / user_token Redis key | ✓ 网关 fallback 仍认 | -| 2026-05-22 后旧 key 失效 | ❌ 仍读旧 key 的代码会全失败 — **mmg 务必在 5-22 前完成切换** | - ---- - -## 八、不影响范围 - -- 现有所有业务接口契约(参/返)零变化 -- 登录端点 path 不变 -- /admin/auth/info / /mp/user/profile 等读接口不变 -- 已签发的旧 access token 在 Redis 还有原 TTL,部署后**不会立即失效**(灰度 fallback) -- 接口字段名 `data.token` 保留,**不做 breaking 改名** - ---- - -## 九、配置项 - -| 配置 key | 默认 | 备注 | -|----------|------|------| -| `auth.jwt.admin-access-ttl-seconds` | 1800 (30 分钟) | nacos 可覆盖 | -| `auth.jwt.admin-refresh-ttl-seconds` | 604800 (7 天) | nacos 可覆盖 | -| `auth.jwt.user-access-ttl-seconds` | 1800 (30 分钟) | nacos 可覆盖 | -| `auth.jwt.user-refresh-ttl-seconds` | 7776000 (90 天) | nacos 可覆盖 | - -代码层有 fallback,nacos 不配也能跑。 - ---- - -## 十、相关历史 PR - -| PR | Issue | 说明 | 是否仍有效 | -|----|-------|------|------------| -| #2285 (2026-05-14) | #2283 | 首版双 token,admin only,字符串轮转 | ❌ 已被本 PR 演进替代(除合规清理逻辑外行为差异) | -| #2287 hotfix | - | user-service TokenInterceptor 白名单 | ✅ 仍有效 | -| #2294 hotfix | - | deleteAdmin/resetPassword/账号锁定 cleanup | ✅ 仍有效,本 PR 兼容 | -| **本 PR #2312** | **#2309** | 滑动续期 + 双端覆盖 + 灰度兼容 | ✅ **最新** | - ---- - -## 十一、联调端点 - -- 测试服: `https://api.test.1814.love/`(待 Deploy Panel 部署 PR #2312 后生效) -- 测试 admin: `admin / Admin@123456` -- 测试小程序 user: 用现有微信测试号登录即可 - ---- - -## 十二、相关文档 - -- 关联 Issue: [wx/HL#2309](https://git.1814.love:8443/wx/HL/issues/2309) -- 关联 PR: [wx/HL#2312](https://git.1814.love:8443/wx/HL/pulls/2312) -- 上一版 changelog: `2026-05/14_feat_admin_auth_refresh_token.md` diff --git a/changelogs/2026-05/15_feat_material_batch_move_category.md b/changelogs/2026-05/15_feat_material_batch_move_category.md deleted file mode 100644 index 72390b6..0000000 --- a/changelogs/2026-05/15_feat_material_batch_move_category.md +++ /dev/null @@ -1,199 +0,0 @@ -# 素材库: 新增批量修改分类接口(批量移动文件夹) - -> **服务**: hl-resource-service (端口 8082) -> **PR**: #2347 -> **Issue**: #2345 -> **日期**: 2026-05-15 -> **影响范围**: 管理后台素材库页(`/material`)批量操作栏 - ---- - -## 一、背景 - -素材库当前批量操作栏只有「批量通过 / 批量驳回 / 批量导出 / 批量删除」,缺少**批量修改分类**(俗称"批量移动文件夹")。日常归档场景:运营把多条素材一次性归到同一个景区分类下,目前只能逐条 `PUT /admin/material/{id}`,效率低。 - -本次后端新增 1 个批量接口,前端需要在批量操作栏加一个按钮 + 分类树选择弹窗。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 批量修改素材分类 | PUT | `/admin/material/batch/category` | **新增** | 把多个素材一次性移动到同一目标分类,逐条失败不中断其他成功条目 | - ---- - -## 三、接口详情 - -### 1. 批量修改素材分类 `PUT /admin/material/batch/category` - -**入参 VO**: `BatchMoveCategoryRequest` - -| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------|------| -| materialIds | Body | `List<String>` | ✅ | size 1-500 | 素材 ID 列表,**雪花 ID 用字符串避免前端精度丢失** | -| categoryCode | Body | String | ✅ | max 64 | 目标一级分类编码(如 `scenic` / `product` / `hotel` 等,从 `/admin/material/categories` 拿) | -| subCategoryId | Body | Long | ❌ | - | 目标子分类 ID。**null 或 0** 都表示仅放到一级分类 | - -**出参 VO**: `Result<BatchMoveCategoryResultVO>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| total | int | 入参 materialIds 总数 | -| successCount | int | 成功移动条数 | -| failCount | int | 失败条数 = failures.size() | -| failures | `List<FailItem>` | 失败明细 | -| failures[].materialId | String | 失败的素材 ID(跟入参一致用 String) | -| failures[].reason | String | 失败原因(中文) | - -#### 请求示例 - -```json -{ - "materialIds": ["2054027790054813698", "2054027790054813699"], - "categoryCode": "scenic", - "subCategoryId": null -} -``` - -#### 成功响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "total": 2, - "successCount": 2, - "failCount": 0, - "failures": [] - }, - "success": true -} -``` - -#### 部分失败响应示例 - -```json -{ - "code": 200, - "message": "成功", - "data": { - "total": 3, - "successCount": 2, - "failCount": 1, - "failures": [ - { "materialId": "2054027790054813700", "reason": "素材不存在" } - ] - }, - "success": true -} -``` - -#### 错误响应 - -```json -// 目标 categoryCode 不存在 (整批拒绝) -{ "code": 370101, "message": "无效的父分类编码: xxxx", "data": null, "success": false } - -// 目标 subCategoryId 不属于 categoryCode (整批拒绝) -{ "code": 370103, "message": "...", "data": null, "success": false } - -// materialIds 为空 / 超过 500 条 (整批拒绝, Bean validation) -{ "code": 400, "message": "一次最多移动 500 个素材; 素材ID列表不能为空", "data": null, "success": false } -``` - ---- - -## 四、契约约束 - -| 场景 | payload | 行为 | -|------|---------|------| -| ✅ 移到一级分类 | `{ "materialIds":["1"], "categoryCode":"scenic" }` | 成功 | -| ✅ 移到一级分类(显式 null subCategoryId) | `{ ..., "subCategoryId": null }` | 同上 | -| ✅ 移到一级分类(显式 0) | `{ ..., "subCategoryId": 0 }` | 同 null 等价(后端 normalize) | -| ✅ 移到子分类 | `{ ..., "categoryCode":"scenic", "subCategoryId":2030000000000001 }` | 成功 | -| ❌ 目标父不存在 | `{ "categoryCode":"non_existent" }` | 整批 400 `code:370101` | -| ❌ 子分类不属于该父 | `{ "categoryCode":"scenic", "subCategoryId":属于product的 ID }` | 整批 400 `code:370103` | -| ❌ materialIds 为空 | `{ "materialIds":[] }` | 整批 400 | -| ❌ materialIds > 500 | `{ "materialIds":[501 条] }` | 整批 400 | - -### 单条失败原因 - -| reason 文本 | 触发场景 | -|------------|----------| -| 素材不存在 | 该 materialId 在 DB 找不到(可能已被删) | -| 无权操作该素材 | 当前 admin 角色对**源分类** `material.categoryCode` 无权 | -| 无权移动到目标分类 | 当前 admin 角色对**目标分类** `categoryCode` 无权 | - ---- - -## 五、数据库行为 - -接口**只更新两列**:`material.category_code` + `material.sub_category_id` - -**显式不写**的列: -- `review_status` — 移动分类**不触发重审**,审核结论保留 -- `status` — 启用状态保留 -- 其他字段保留 - -所以已通过审核的素材,移动到其他分类后**仍然是已通过状态**,无需重新审核。 - ---- - -## 六、边界行为 - -- 未登录 / 无 token → 401(网关拦截) -- 单条素材有任一权限问题 / 不存在 → 该条进 failures,**其他成功条目正常完成**(不回滚) -- 目标分类 / 子分类校验不过 → **整批 400 立即拒绝**(在循环之前一次性校验,前端能立即定位是目标选错) - ---- - -## 七、不影响范围 - -- **仅影响**: 管理后台素材库 `/material` 页的批量操作行为 -- **零影响**: - - 单条修改接口 `PUT /admin/material/{id}` 保持不变 - - 批量删除 `DELETE /admin/material/batch` 不变 - - 批量改标签 `PUT /admin/material/batch/tags` 不变 - - 批量导出 `POST /admin/material/export` 不变 - - 素材审核接口 / 审核状态字段 不动 - - 历史数据零迁移,无 DB schema 变更 - ---- - -## 八、测试环境已验证 - -测试服 (https://api.test.1814.love:9443) 部署完成后,用 admin / Admin@123456 真 token 跑通: - -``` -PUT /admin/material/batch/category - Case A: 目标 categoryCode 不存在 → 370101 "无效的父分类编码" ✓ - Case B: 502 条 (超 500) → 400 "一次最多移动 500 个素材" ✓ - Case C: materialIds 为空 → 400 "素材ID列表不能为空" ✓ - Case D: 真移动 1 条 (product → scenic) → 200, successCount=1 ✓ - GET /admin/material/{id} 验证: categoryCode 已更新 ✓ - GET /admin/material/{id} 验证: reviewStatus 不变 ✓ - 再次移回 (scenic → product) → 200, successCount=1 ✓ -``` - -验证素材: `materialId=2054027790054813698` (测试服真实素材) - ---- - -## 九、前端实现建议(mmg 参考) - -1. 批量操作栏新增「**批量移动**」按钮(建议放在「批量删除」**左侧**) -2. 点击按钮 → 弹出**分类树选择弹窗**(可复用现有左侧分类树组件) -3. 用户选完目标分类(支持只选一级 / 选到子分类两种)→ 调本接口 -4. 收到响应后: - - 如果 `failCount == 0` → toast "成功移动 N 条" + 关闭弹窗 + 刷新列表 - - 如果 `failCount > 0` → 弹窗展示 `failures` 明细表(materialId + reason),让用户知道哪些失败、为什么 - ---- - -## 十、相关链接 - -- 关联 Issue: [wx/HL#2345](https://git.1814.love:8443/wx/HL/issues/2345) -- 关联 PR: [wx/HL#2347](https://git.1814.love:8443/wx/HL/pulls/2347) diff --git a/changelogs/2026-05/15_feat_product_v2_operation_log_chinese_field_diff.md b/changelogs/2026-05/15_feat_product_v2_operation_log_chinese_field_diff.md deleted file mode 100644 index 8d7695c..0000000 --- a/changelogs/2026-05/15_feat_product_v2_operation_log_chinese_field_diff.md +++ /dev/null @@ -1,210 +0,0 @@ -# product-v2: 产品操作日志全中文化 + 字段级 diff（旧值→新值） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2355 -> **Issue**: #2354 -> **日期**: 2026-05-15 -> **影响范围**: 管理端「产品 → 操作日志」侧边栏（admin.1814.love `/product/edit?id=X` 右侧抽屉） - ---- - -## ⚠️ 关键变化 - -`GET /admin/product/item/{id}/operation-logs` **出参新增 3 字段**（`actionLabel` / `stepLabel` / `changes`），接口路径、入参、HTTP 方法**完全没变**。 - -- 旧逻辑（mmg 现在）：把 `action="EDIT"` / `step="STEP1"` 当字符串裸渲染，用户看不懂 -- 新逻辑：直接读 `actionLabel="编辑"` / `stepLabel="基础信息"` 即可；新增 `changes` 数组渲染字段差异表格 -- **老日志兼容**：2026-05-15 之前的历史日志 `changes` 字段为 `null`，前端**不渲染 diff 区块**，只显示 `actionLabel + detail`（向后兼容） - ---- - -## 一、背景 - -张老板 2026-05-15 反馈：产品 `2055138817265897473` 改价后无法追溯具体金额变化。 -- 旧版日志只记 `detail="价格区间设置 2026-07-12~2026-07-19"`，金额变化要靠 RDS binlog 还原（1 小时排查） -- 20 种 action 落库为英文 `EDIT/PRICE_SET/COMPLETE`，前端裸出导致每次都要询问含义 -- `operatorName` 列存在但 Service 没赋值，所有日志显示 null - -P0 解决：action 中文化 + 字段级 diff（前端表格可直接展示「成人售价 5800 → 9400」）。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 查产品操作日志 | GET | `/admin/product/item/{id}/operation-logs` | **出参 EXTEND** | 新增 actionLabel / stepLabel / changes 三字段 | - ---- - -## 三、接口详情 - -### 1. 查产品操作日志 `GET /admin/product/item/{id}/operation-logs` - -**VO**: `ProductOperationLogRespVO` - -#### 入参（无变化） - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| id | Path | Long | ✅ | productId | - -#### 出参（新增 3 字段，加粗为新） - -```json -{ - "code": 200, - "data": [ - { - "id": "2055231522046218242", - "action": "EDIT", - "actionLabel": "编辑", - "step": "STEP1", - "stepLabel": "基础信息", - "detail": "基础信息", - "operatorId": "2033350100000000006", - "operatorName": "wangyu", - "createTime": "2026-05-15 18:19:14", - "changes": [ - { - "field": "name", - "fieldLabel": "产品名称", - "oldValue": "Tina空想2大1小 私人定制线路", - "newValue": "Tina空想2大1小 私人定制线路 8天7晚", - "changeType": "MODIFY" - }, - { - "field": "depositAmount", - "fieldLabel": "订金金额", - "oldValue": "1000.00", - "newValue": "1500.00", - "changeType": "MODIFY" - } - ] - }, - { - "id": "2055222984284573697", - "action": "PRICE_SET", - "actionLabel": "设置价格", - "step": "STEP4", - "stepLabel": "价格与班期", - "detail": "价格区间设置 2026-07-12~2026-07-19", - "operatorId": "2033350100000000006", - "operatorName": "wangyu", - "createTime": "2026-05-15 12:01:59", - "changes": [ - { - "field": "adultSellPrice", - "fieldLabel": "成人售价", - "oldValue": "5800.00", - "newValue": "9400.00", - "changeType": "MODIFY" - }, - { - "field": "childSellPrice", - "fieldLabel": "儿童售价", - "oldValue": "3000.00", - "newValue": "3980.00", - "changeType": "MODIFY" - } - ] - }, - { - "id": "2055216483381071873", - "action": "COMPLETE", - "actionLabel": "完成设计", - "step": null, - "stepLabel": null, - "detail": "", - "operatorId": "2033350100000000006", - "operatorName": "wangyu", - "createTime": "2026-05-15 17:43:16", - "changes": null - } - ] -} -``` - -#### `changes` 字段定义 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `changes` | `Array<FieldChange> \| null` | 字段差异列表；老日志为 `null` 时不渲染 | -| `changes[].field` | `string` | 字段英文名（用于排序/筛选/调试） | -| `changes[].fieldLabel` | `string` | **字段中文名（前端直接展示这个）** | -| `changes[].oldValue` | `string \| number \| null` | 旧值（已转中文：枚举值如 `FULL` 已翻译为 `"全款"`） | -| `changes[].newValue` | `string \| number \| null` | 新值 | -| `changes[].changeType` | `"ADD" \| "MODIFY" \| "DELETE"` | ADD=新增（oldValue=null）/MODIFY=修改/DELETE=删除（newValue=null） | - -#### 本期接入字段级 diff 的 3 类操作 - -| action / step | 接入字段（5 个/类） | -|--------------|------| -| `PRICE_SET` / `BATCH_SAVE`（STEP4） | `adultSellPrice` / `childSellPrice` / `toddlerDiscount` / `dailyStock` / `priceType` | -| `EDIT` STEP1 | `name` / `subtitle` / `paymentType` / `depositAmount` / `defaultDailyStock` | -| 状态变更（`SUBMIT_PUBLISH`/`APPROVE`/`REJECT` 等） | `status`（旧→新状态值已翻译为中文） | - -**未接入的 action（changes=null，按老日志渲染）**：CREATE / EDIT STEP2-5 / COPY / DELETE / EDIT_MAP_AUTO / EDIT_MAP_MODE / SAVE_DETAIL_BLOCKS / TEAM_SAVE 等。 -**P1 后续**会全字段 diff 覆盖 STEP2-5 + 长文本摘要 + 集合 diff，单独发 changelog 通知。 - ---- - -## 四、前端改动建议（mmg） - -### 1. 日志侧边栏渲染逻辑（伪代码） - -```jsx -{logs.map(log => ( - <Timeline.Item> - <div className="log-header"> - <span className="action-tag">{log.actionLabel}</span> - {log.stepLabel && <span className="step-tag">{log.stepLabel}</span>} - <span className="time">{log.createTime}</span> - <span className="operator">{log.operatorName ?? '系统'}</span> - </div> - {log.detail && <div className="detail">{log.detail}</div>} - {log.changes && log.changes.length > 0 && ( - <table className="diff-table"> - <thead><tr><th>字段</th><th>旧值</th><th>新值</th></tr></thead> - <tbody> - {log.changes.map(c => ( - <tr key={c.field}> - <td>{c.fieldLabel}</td> - <td className="old">{c.oldValue ?? '—'}</td> - <td className="new">{c.newValue ?? '—'}</td> - </tr> - ))} - </tbody> - </table> - )} - </Timeline.Item> -))} -``` - -### 2. action 颜色建议（前端可自行决定） - -| 类别 | 取值 | 建议色 | -|------|------|--------| -| 价格类 | PRICE_SET / PRICE_DELETE / BATCH_SAVE / ADJUST_PRICE | 橙 | -| 状态类 | PUBLISH / SUBMIT_PUBLISH / APPROVE / DIRECT_PUBLISH | 绿 | -| 状态类（负向） | REJECT / WITHDRAW / UNPUBLISH / FORCE_UNPUBLISH / DELETE | 红 | -| 编辑类 | EDIT / EDIT_MAP_AUTO / EDIT_MAP_MODE | 蓝 | -| 其它 | CREATE / COPY / COMPLETE / TRANSFER / TEAM_SAVE | 灰 | - ---- - -## 五、向后兼容性 - -- ✅ 接口路径、入参、HTTP 方法、原有出参字段全部不变 -- ✅ 老日志 `changes=null`，前端 `if(changes)` 守卫即可 -- ✅ 后端可独立先行发布（前端不改也不会出错，只是不显示新功能） -- ✅ 新日志的 actionLabel/stepLabel 即使前端不读也不影响 - -**部署顺序**：Flyway 先行 → 后端 → 前端（任意顺序都安全）。 - ---- - -## 六、不在本期范围（P1/P2 后续单独工单） - -- **P1**：全字段 diff（>100 字段全覆盖）、长文本摘要策略、集合字段 diff（seasons/tags/tiers/days/feeItems） -- **P2**：「还原到此版本」按钮、跨产品聚合查询页、调价超阈值钉钉/企微告警 diff --git a/changelogs/2026-05/15_frontend_admin_picker_remove_season_filter_intersection_only.md b/changelogs/2026-05/15_frontend_admin_picker_remove_season_filter_intersection_only.md deleted file mode 100644 index 5aa52d1..0000000 --- a/changelogs/2026-05/15_frontend_admin_picker_remove_season_filter_intersection_only.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -date: 2026-05-15 -type: frontend-feature -module: admin-product-v2-itinerary-picker -priority: medium -backend_pr: "#2335" -backend_issue: "#2334" -supersedes: - - "14_frontend_feature_admin_scenic-season-filter-and-tags.md" - - "14_frontend_feature_admin_activity-season-filter-and-tags.md" -notify: ["@mmg"] -status: tested ---- - -# 资源 picker 去掉按产品线季节过滤,VO.seasons 改为产品/资源交集 - -## 业务变更 - -产品设计选节点(从资源库添加活动)弹窗,**不再按当前产品线的 seasons 过滤资源列表**。改为: - -1. **列表全量** — 景区(scenic)、游玩项目(activity)两个 tab 返回全部资源,不因 productLineId 减少 -2. **季节标签 = 交集** — 资源 VO 的 `seasons` 字段从 "资源全部支持季节" 改为 "产品线季节 ∩ 资源季节" -3. **封面/亮点保留** — `coverUrl` 与 `seasonHighlights` 仍按产品线 seasons[0] 切换 - -## 后端已就位 (PR #2335 已合并 dev,已部署测试服并真测) - -### 行为变更对照 - -| 项 | 旧 (PR #2278) | 新 (PR #2335) | -|----|---------------|---------------| -| `GET /admin/scenic/spots?productLineId=X` 列表 total | 按产品线 seasons 过滤后的子集 | **全量**(与不传 productLineId 一致) | -| `GET /admin/activity/items?productLineId=X` 列表 total | 按产品线 seasons 过滤后的子集 | **全量**(与不传 productLineId 一致) | -| VO.`seasons` 字段 | 资源全部支持的季节(如 `["spring","summer","autumn"]`) | 产品线 ∩ 资源(如产品线=`[summer]` ∩ 资源=`[spring,summer,autumn]` → `["summer"]`) | -| VO.`coverUrl` 季节封面切换 | 同新版 | **保留**:仍按产品线 seasons[0] 切换 | -| VO.`seasonHighlights` 季节亮点 | 同新版 | **保留**:仍按产品线 seasons[0] 切换 | - -### 测试服真测结果 - -| 场景 | 现象 | -|------|------| -| 不传 productLineId,scenic 列表 | total=66 | -| 传 productLineId(seasons=[summer]),scenic 列表 | total=**66**(未减少),VO.seasons=`["summer"]` | -| 不传 productLineId,activity 列表 | total=56 | -| 传 productLineId(seasons=[summer]),activity 列表 | total=**56**(未减少),VO.seasons=`[]`(资源未配 summer) | -| 传不存在的 productLineId(Feign 反查失败) | total=56,VO.seasons 回落资源全集(如 `["spring","autumn"]`) | - -### 降级路径 - -- Feign 调 product-v2 失败 → `query.seasons` 不被注入 → VO.seasons 回落资源全集 -- 产品线 seasons 为空 → 同上 - -## 前端实现要点 - -### 列表渲染 - -**透传 `productLineId` 的请求保持不变**(前端无需调整接口调用): - -```js -await api.get(`/admin/scenic/spots?productLineId=${productLineId}&pageSize=20`) -await api.get(`/admin/activity/items?productLineId=${productLineId}&pageSize=20`) -``` - -### 季节标签渲染 - -VO `seasons` 字段**就是交集**,前端**直接渲染**即可,不需要在前端再做过滤: - -```js -// VO.seasons 已经是后端算好的产品线 ∩ 资源,不要再做客户端过滤 -const visibleSeasons = vo.seasons || [] - -// 4 色保持不变: -// spring → #67C23A / summer → #409EFF / autumn → #E6A23C / winter → #909399 -``` - -> 如资源不支持任何产品线季节,`vo.seasons = []`,**不渲染任何季节标签**。 - -### 封面/亮点 - -`coverUrl` 与 `seasonHighlights` 行为**不变**,继续按现有方式渲染。 - -### 行程节点卡片(已选节点) - -`InternalProductDetailVO.NodeItem.seasons` 字段保留;**节点卡片渲染同样规则** — 用后端透传的 seasons(已是交集)直接渲染。 - -## 涉及前端文件 (仅供参考定位) - -- 弹窗组件: `D:\work2\hl-ui\src\views\product-v2\` 行程编辑器子组件 -- 季节标签组件: 14_ 的实现可复用,无需调整(VO 字段含义虽变,但前端只是"渲染 vo.seasons",不感知) - -## 关联 - -- 推翻 (supersedes): 05-14 的两份 changelog - - `14_frontend_feature_admin_scenic-season-filter-and-tags.md`(后端 #2229) - - `14_frontend_feature_admin_activity-season-filter-and-tags.md`(后端 #2234) -- 后端 PR #2229 / #2234 / #2278 **不回滚**,新增的 `scenic_season` / `activity_season` 子表 / VO 字段 / Feign 反查 全部保留 -- 本次反转: backend issue #2334 / PR #2335 - -## 测试服环境 - -- 接口:`https://api.test.1814.love:9443/admin/scenic/spots`、`/admin/activity/items` -- admin token:测试服 admin / Admin@123456 登录 `/admin/auth/login` -- 测试用产品线 ID(seasons=[summer]):`2053279457388494849` diff --git a/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime.md b/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime.md deleted file mode 100644 index 5b91710..0000000 --- a/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime.md +++ /dev/null @@ -1,111 +0,0 @@ -# refactor(admin): 14 个查询接口 RespVO 补 updateTime/updatedAt 字段 - -> **服务**: hl-order-service-v2 / hl-product-service-v2 / hl-resource-service -> **PR**: #2348 (已合 dev，已部署测试服) -> **Issue**: #2346 -> **日期**: 2026-05-15 -> **影响范围**: 管理后台 hl-ui 14 个查询接口的列表 / 详情返回结构 - ---- - -## 给前端的话（mmg 看这里） - -管理后台 14 个 admin 查询接口的响应 VO **新增了 `updateTime` 或 `updatedAt` 字段**（视模块命名约定），可以在列表上加「最后修改时间」列了。 - -字段名规律： -- order-v2 / product-v2 模块：`updateTime` -- resource guide 模块：`updatedAt`（与本模块既有 `createdAt` 风格一致） - -值类型：`LocalDateTime` 字符串（如 `"2026-05-15 10:30:00"`），可能为 null（少数旧数据没填的话）。 - -**不影响任何现有字段，纯新增；前端不改也不会报错，要展示才取**。 - ---- - -## 受影响的 14 个接口（按服务分组） - -### hl-resource-service（3 个，字段名 `updatedAt`） - -| 接口 | RespVO | -|------|--------| -| `GET /admin/guide/article/list` | GuideArticleListVO | -| `GET /admin/guide/category/list` | GuideCategoryVO | -| `GET /admin/guide/tag/managed`、`/admin/guide/tag/all` | GuideTagVO | - -> ⚠️ GuideTagVO 因为 DB 表 `guide_tag` 本身没有 `updated_at` 列，本次**没加**字段（即 `updatedAt` 字段不存在于响应中）。如果后续业务需要支持标签修改时间，需要先发 V*.sql 加列。 - -### hl-product-service-v2（10 个，字段名 `updateTime`） - -| 接口 | RespVO | -|------|--------| -| `GET /admin/product/item/{id}`（产品详情） | ProductDetailRespVO | -| `GET /admin/product-line/{id}` 及列表 | ProductLineRespVO | -| `GET /admin/product/equipment-template/simple` | EquipmentTemplateSimpleRespVO | -| `GET /admin/product/item/{id}/itinerary/day` | ItineraryDayRespVO | -| `GET /admin/product/item/{id}/price-calendar` | PriceCalendarRespVO | -| `GET /admin/product/item/{id}/schedule/list` | ScheduleRespVO | -| `GET /admin/product/item/{id}/schedule/team` | ScheduleTeamRespVO | -| `GET /admin/travel-guarantee-template/list` 等 | TravelGuaranteeTemplateRespVO | -| `GET /admin/product/formula/group/list` 等 | FormulaGroupRespVO | -| `GET /admin/product/formula/var/list` | FormulaVarRespVO | - -### hl-order-service-v2（1 个，字段名 `updateTime`） - -| 接口 | RespVO | -|------|--------| -| `GET /admin/travel-agency/enabled` 等下拉 | AgencySimpleRespVO | - ---- - -## 不在范围（13 个 VO 按语义跳过） - -以下 VO 属于"聚合 / 估算 / 操作结果"，**不是 DB 持久化实体**，加 updateTime 无意义，前端不要期待这些接口返回时间字段： - -- 保险预览/试算：InsurancePreviewApplyRespVO、InsuranceTrialPriceRespVO -- 充值/上传结果：RechargeRespVO、InvoiceUploadRespVO -- 旅客智能解析结果：AdminTravelerSmartParseRespVO -- 地图生成 / 复制分享 / 最低价聚合：ProductMapGenerateRespVO、ProductShareRespVO、ProductMinPriceRespVO -- 操作日志（createTime 即操作时间）：ProductOperationLogRespVO -- 建议价计算：ResourceSuggestPriceRespVO、SuggestPriceRespVO -- 多源价格日历聚合：UnifiedPricingCalendarRespVO -- 公式版本快照：FormulaVersionRespVO - -mp 端 VO **不在本次范围**。 - ---- - -## 验证记录 - -### 本地（PR 提交前） -- mvn clean compile 三服务全绿 -- 8080 网关 + SUPER_ADMIN token 抽样 5 接口全过 - -### 测试服（部署后，2026-05-15） -经 `https://api.test.1814.love:9443` + admin token 抽样： - -| 接口 | 字段 | 实测值 | -|------|------|--------| -| /admin/travel-agency/enabled | updateTime | 2026-05-08 14:41:03 ✅ | -| /admin/product/formula/group/list | updateTime | 2026-04-14 00:50:15 ✅ | -| /admin/guide/category/list | updatedAt | 2026-03-31 22:05:01 ✅ | -| /admin/guide/article/list | updatedAt | 2026-03-17 23:40:04 ✅ | -| /admin/travel-guarantee-template/list | updateTime | 2026-04-15 21:30:22 ✅ | - -5/5 全过。 - ---- - -## 实现细节（mmg 不用关心，归档备查） - -### Service 层修复 -PR 中除了 VO 加字段，还修了 4 处 Service 手动 `new + set` 构造时漏字段（不修则 VO 字段恒 null）： -- TravelAgencyServiceImpl.toSimpleVO -- EquipmentTemplateService.toSimpleRespVO -- GuideArticleService 两处构造 -- GuideCategoryService.toVO - -其余 VO 走 `BeanUtil.toBean(DO.class, VO.class)`，BaseDO 的 createTime/updateTime 自动复制，无需 Service 改动。 - -### 字段命名约定 -- `BaseDO` 用 `createTime`/`updateTime`（驼峰，与 DB 列 `create_time`/`update_time` MyBatis 自动映射） -- guide 模块历史用 `createdAt`/`updatedAt`（DB 列 `created_at`/`updated_at`），不打破现有命名 diff --git a/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime_batch2.md b/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime_batch2.md deleted file mode 100644 index f7e22ec..0000000 --- a/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime_batch2.md +++ /dev/null @@ -1,126 +0,0 @@ -# refactor(admin): 47 个 admin 查询接口 RespVO 续补 update 时间字段（PR #2348 漏扫续修） - -> **服务**: hl-resource-service / hl-user-service / hl-order-service-v2 -> **PR**: #2353 (已合 dev，已部署测试服) -> **Issue**: #2351（续 #2346） -> **日期**: 2026-05-15 -> **影响范围**: 管理后台 hl-ui 47 个查询接口 - ---- - -## 给前端的话（mmg 看这里） - -⚠️ **重要**：上一份 changelog `15_refactor_admin_resp_vo_add_updatetime.md` 只覆盖了 14 个 VO，**远远不够**。本批续补 **47 个 VO**，涵盖 mmg 反馈的 `/admin/scenic/spots` 等接口。 - -### 字段名规律 -- 大多数 `updateTime`（与 BaseDO 一致） -- guide / banner / topic / explore / file / task / wechat / album / arrival / review / material / scenic / hotel / restaurant / vehicle / activity / cost / staff / supplies / service 等模块 `updatedAt`（与各模块既有 `createdAt` 风格一致） - -### 验证 -经测试服 9443 网关 + admin token，**抽样 18/18 全过**（含 `/admin/scenic/spots`）： - -| 接口 | 字段 | 实测值 | -|------|------|--------| -| /admin/scenic/spots | updatedAt | 2026-03-31 22:58:10 | -| /admin/vehicle/models | updatedAt | 2026-04-13 17:18:06 | -| /admin/service/items | updatedAt | 2026-03-07 11:36:35 | -| /admin/cost/items | updatedAt | 2026-02-17 22:45:59 | -| /admin/material/list | updatedAt | 2026-05-15 17:53:42 | -| /admin/banner | updatedAt | 2026-03-17 16:23:49 | -| /admin/explore/category | updatedAt | 2026-04-01 16:25:51 | -| /admin/task/boards | updatedAt | 2026-02-13 16:28:53 | -| /admin/file/list | updatedAt | 2026-05-12 10:36:02 | -| /admin/order/list | updateTime | 2026-05-09 11:48:00 | -| /admin/order/early-bird/list | updateTime | 2026-04-20 12:15:05 | -| /admin/payment/list | updateTime | 2026-05-09 11:47:44 | -| /admin/review/list | updatedAt | 2026-05-07 14:48:56 | -| /admin/contract/list | updateTime | 2026-05-07 14:43:45 | -| /admin/contract/templates | updateTime | 2026-02-25 13:01:07 | -| /admin/contract/scheme/list | updateTime | 2026-04-24 16:20:00 | -| /admin/contract/clause-template/list | updateTime | 2026-05-13 14:15:25 | -| /admin/insurance/products | updateTime | 2026-02-24 20:55:11 | - ---- - -## 受影响的 47 个 VO - -### hl-resource-service（10 个，全 updatedAt） - -| 模块 | VO | -|------|-----| -| material | MaterialVO | -| activity | ActivityListVO | -| cost | CostItemListVO | -| hotel | HotelListVO | -| restaurant | RestaurantListVO | -| **scenic** | **ScenicSpotListVO** ← mmg 反馈的就是这个 | -| service | ServiceItemListVO | -| staff | StaffListVO | -| supplies | SuppliesListVO | -| vehicle | VehicleModelListVO | - -### hl-user-service（9 个） - -- updatedAt 风格：WechatGroupVO, BannerVO, ExploreCategoryVO, ExploreCategoryDetailVO, TopicVO, FileVO, BoardVO, SubtaskVO -- updateTime 风格：MessageCategoryVO, NameItemRespVO - -### hl-order-service-v2（28 个） - -contract: ClauseTemplateVO, ContractSchemeAttachmentRespVO, ContractSchemeVO, ContractTemplateVO, ContractTourGuideRespVO, ContractVO -insurance: InsuranceOrderVO, InsuranceProductVO -order/album: AlbumFileVO, AlbumFolderVO -order/arrival: ArrivalPlanRespVO -order/assignment: VehicleAssignmentVO -order/core: OrderListVO, OrderVO -order/customize: CustomizeRequestVO -order/earlybird: EarlyBirdPlanVO -order/finance: AdminOrderDiscountVO, AdminOrderSurchargeVO, InvoiceVO -order/itinerary: ItineraryEditVO -order/review: AdminReportQueueItemRespVO, ReviewListVO, ReviewVO (3 个 updatedAt) -order/todo: OrderTodoVO -order/workorder: WorkOrderVO -payment: PaymentTransactionVO, RefundRecordVO - ---- - -## 不在范围（14 个 VO 撤回，前端不要期待这些有 update 字段） - -DO/DB 表本身**没有 update_at 列**，是设计上的"一次写入即不变"实体： - -- 资源服务 10 个 Tag/Ref 表：MaterialRefVO / MaterialTagVO / ActivityTagVO / HotelTagVO / RestaurantTagVO / ScenicTagVO / ServiceTagVO / StaffTagVO / SuppliesTagVO / VehicleTagVO（标签计数表无 update 需求） -- 用户服务 3 个：FileRefVO（关联表）/ TimelineItemVO（audit log）/ SendLogVO（事件日志） -- 订单服务 1 个：ReviewImageVO（评价图片表无 update 设计） - ---- - -## 实现细节（mmg 不用关心，归档备查） - -### Service 层手动 set 修复 41 处（核心修复！） - -本批 47 个 VO 中 41 个走"手动 `new + set`"路径（占 87%）。**如果只补 VO 不补 Service，字段恒 null**，看似改了实际没用。 - -CR 过程发现这个 bug 模式（PR #2348 也犯过 14/4 占比），本次彻底排查所有 setter，每处都补： -- 各 `XxxService.toListVO()` / `toVO()` 转换方法 -- builder 风格的 service：`.updatedAt(...)` 在 build() 前 - -特殊 3 处跨名桥接（DO `updateTime` → VO `updatedAt`）： -- TopicService → `.updatedAt(topic.getUpdateTime())` -- ReviewDetailAssembler / ReviewCommandService / ReviewQueryService → `vo.setUpdatedAt(review.getUpdateTime())` - -### 已知遗漏（OrderTodoVO 部分路径） - -`OrderTodoQueryService.mapActiveTodoToVOList:86` 和 `mapInsuranceToVOList:121` 走 mapper 自定义 SQL 返回的 `ActiveTodoDTO`/`InsuranceCompletedDTO`，DTO 本身无 update 字段，需先改 mapper SQL。 - -**影响**：OrderTodoVO 在 list 页/详情页能看到 updateTime（已补），仅"待办活跃"特定查询路径会 null。后续 mapper 改造专项处理。 - -### 前一批未补已修 - -PR #2348 本身的 14 个 VO 已都正常工作（本批未动那 14 个，请前端继续使用）。 - ---- - -## 总账 - -- PR #2348 (14 个) + PR #2353 (47 个) = **总共 61 个 admin VO 已补 update 字段** -- 总共 15 个 VO 因 DO/DB 设计无 update_at 撤回（PR #2348: 1 个 GuideTagVO + PR #2353: 14 个） -- 总共 45 处 Service 手动 set 修复（PR #2348: 4 处 + PR #2353: 41 处） diff --git a/changelogs/2026-05/16_feat_product_v2_operation_log_p1_aggregated_diff.md b/changelogs/2026-05/16_feat_product_v2_operation_log_p1_aggregated_diff.md deleted file mode 100644 index 1fd5b72..0000000 --- a/changelogs/2026-05/16_feat_product_v2_operation_log_p1_aggregated_diff.md +++ /dev/null @@ -1,172 +0,0 @@ -# product-v2: 操作日志 P1 — 价格日历逐日聚合 diff + STEP2-5 全字段 + 跨产品检索 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2423（承接 P0 #2355） -> **Issue**: #2409 -> **日期**: 2026-05-16 -> **影响范围**: 管理端「产品 → 操作日志」侧边栏 + 新增「跨产品操作日志检索」入口 - ---- - -## ⚠️ 关键变化 - -**P0 已让 `changes` 字段可用，P1 让 `changes` 真正"细到每天每档"+ 全字段覆盖**： - -- 旧逻辑（P0 上线后）：PRICE_SET 只看到 1 行「成人售价 5800→9400」，不知道改了哪几天 -- 新逻辑（P1）：**按 (字段, 档位, 旧值, 新值) 智能聚合日期** → 8 天改同价 = **1 行带日期范围**「成人售价 2026-07-12~07-19 (8 天) 经典档: 5800→9400」 -- **前端 0 改动**：复用 P0 的 `changes` 数组渲染表格，新 `fieldLabel` 自带聚合描述 - -**新接口**：`GET /admin/product/item/operation-logs/search` 跨产品按字段名检索（运营查"今天谁改过价"）。 - ---- - -## 一、背景 - -承接 P0 [#2355](https://git.1814.love:8443/wx/HL/pulls/2355) — 张老板查产品改价时，P0 只能看到「成人售价 5800→9400」一行（取第一天作代表），看不出来"是哪几天改了"。如果运营改 8 天里 3 天，剩 5 天没改，P0 完全无法区分。 - -P1 解决：逐日 diff + 智能聚合 + STEP2-5 全字段全覆盖。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 查产品操作日志 | GET | `/admin/product/item/{id}/operation-logs` | **出参增强** | `changes` 数组含聚合 fieldLabel + STEP2-5 全字段 | -| 2 | 跨产品检索操作日志 | GET | `/admin/product/item/operation-logs/search` | **新接口** | 按字段名（如 adultSellPrice）查谁改过价 | - ---- - -## 三、接口详情 - -### 1. 查产品操作日志（出参增强） - -`changes[].fieldLabel` 现在自带日期范围描述： - -```json -{ - "action": "PRICE_SET", - "actionLabel": "设置价格", - "step": "STEP4", - "stepLabel": "价格与班期", - "changes": [ - { - "field": "adultSellPrice", - "fieldLabel": "成人售价 2026-07-12~07-19 (8 天) 经典档", - "oldValue": "5800", - "newValue": "9400", - "changeType": "MODIFY" - }, - { - "field": "childSellPrice", - "fieldLabel": "儿童售价 2026-07-12~07-19 (8 天) 经典档", - "oldValue": "3000", - "newValue": "3980", - "changeType": "MODIFY" - } - ] -} -``` - -#### 聚合描述格式 - -| 场景 | fieldLabel 示例 | -|------|----------------| -| 连续日期 | `成人售价 2026-07-12~07-19 (8 天) 经典档` | -| 离散日期 | `成人售价 2026-07-12, 07-15, 07-18 (3 天) 经典档` | -| 单天 | `成人售价 2026-07-12 经典档` | -| 跨月连续 | `成人售价 2026-07-30~08-01 (3 天) 经典档` | -| 不同新值（如周末加价） | 自动按 oldValue→newValue 分多组，多行 | - -#### 长文本字段（>200 字）摘要 - -```json -{ - "field": "introduction", - "fieldLabel": "产品介绍", - "oldValue": "已修改 (前80字…后80字)", - "newValue": "已修改 (前80字…后80字)", - "oldHash": "a3f4...", - "newHash": "b8e2...", - "changeType": "MODIFY" -} -``` -- 字段白名单：`description / introduction / highlights / quickUnderstand / childExperience / growthGains / equipmentList / routeMapUrl / detailContent / coverContent` -- `oldHash/newHash`：SHA-256 前 16 字节，**前端可选展示**（用于跨日志判断"内容是否真变了"） - -#### 集合字段聚合 - -```json -{ - "field": "itineraryDays", - "fieldLabel": "行程列表", - "oldValue": "共 7 天", - "newValue": "共 8 天 (新增 1 / 删除 0)", - "changeType": "MODIFY" -} -``` -- 集合白名单：`seasons / tags / tiers / itineraryDays / dayNodes / dayHotels / feeItems / carouselImages / excludedFees / includedFees / customFees` -- ⚠️ **注意**：集合字段不做深 diff（避免日志 JSON 爆 50KB+），只聚合「新增 N / 删除 M」。具体哪一项的字段变了，目前需要查日志详情（P2 后续可优化） - ---- - -### 2. 跨产品检索操作日志（新接口） - -`GET /admin/product/item/operation-logs/search` - -#### 入参（VO） - -| 字段 | 位置 | 类型 | 必填 | 默认 | 说明 | -|------|------|------|------|------|------| -| `field` | Query | String | ✅ | — | 字段英文名，如 `adultSellPrice` | -| `fromDate` | Query | LocalDate | ❌ | today-30d | 开始日期（双侧空时套 30 天兜底） | -| `toDate` | Query | LocalDate | ❌ | today | 结束日期 | -| `page` | Query | Integer | ❌ | 1 | 页码 | -| `size` | Query | Integer | ❌ | 20 (max 100) | 页大小 | - -#### 权限 - -Service 入口校验 role ∈ {`SUPER_ADMIN`, `ADMIN`}，普通销售员调用返 `PERMISSION_DENIED`（403 业务码）。 - -#### 全词匹配 - -避免 `field=price` 误命中 `adultSellPrice` / `childSellPrice` / `infantPrice`： -- 写入端：`changed_fields` 存 `,adultSellPrice,childSellPrice,`（两端逗号包裹） -- 查询端：`LIKE '%,adultSellPrice,%'` 全词匹配 -- 兼容老日志：P0 写入的没逗号包裹，OR 兜底 3 种边界（exact / 头部 / 尾部） - -#### 出参 - -复用 `ProductOperationLogRespVO`（带分页）。 - ---- - -## 四、前端改动建议（mmg） - -**方案 A+ 聚合版**：**前端 0 改动**。 - -- P0 已实现的 `changes` 表格渲染逻辑自动适配（新 fieldLabel 自带"日期范围 (N 天) 档位名"） -- 长文本字段：oldValue/newValue 已是「已修改 (前80字…后80字)」文本，直接渲染 -- 集合字段：oldValue/newValue 已是「共 N 条 (新增 A / 删除 C)」文本，直接渲染 - -**新接口入口建议**（可选）：管理端加个「操作日志检索」菜单，调 `/operation-logs/search?field=&fromDate=&toDate=`，用于审计场景。 - ---- - -## 五、向后兼容 - -- ✅ 老日志（changes=null）继续不渲染 diff 区块 -- ✅ P0 写入的日志（changed_fields 没两端逗号）依然能被新检索接口匹配 -- ✅ 新接口 `/operation-logs/search` 不影响现有 `/operation-logs` -- ✅ Flyway V20260516_003 只加索引，无 DDL 风险 - -**部署顺序**：Flyway 先行 → 后端发布。前端 0 改动可选发。 - ---- - -## 六、不在本期范围（P2 后续） - -- **集合字段深 diff**：当前只聚合「新增/删除数」，不展示哪一项的哪个字段变了 -- 「还原到此版本」按钮 -- 调价超阈值（>20%）钉钉/企微告警 -- 跨产品聚合可视化页（直接读 `/operation-logs/search` 即可） diff --git a/changelogs/2026-05/16_feat_product_v2_price_edit_permission_lock.md b/changelogs/2026-05/16_feat_product_v2_price_edit_permission_lock.md deleted file mode 100644 index 2a87524..0000000 --- a/changelogs/2026-05/16_feat_product_v2_price_edit_permission_lock.md +++ /dev/null @@ -1,96 +0,0 @@ -# product-v2: 产品改价权限入口拦截（业务铁规落地） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2427 -> **Issue**: #2424（P2 部分实施，剩余 P2.1 #2428 跟踪） -> **日期**: 2026-05-16 -> **影响范围**: 4 个产品价格写入接口的角色权限拦截 - ---- - -## ⚠️ 关键变化（mmg 前端需注意） - -新业务铁规：**只有定制师本人（CUSTOMIZER 且 product.created_by == 当前操作人）+ 超级管理员（SUPER_ADMIN）可以改价**。其他角色（运营/客服/房务/车务/素材/普通 ADMIN）调用价格写入接口一律返 `PERMISSION_DENIED`。 - -前端要做的事： - -1. **隐藏改价按钮**：用户登录后获取 role，如果不是 SUPER_ADMIN 也不是 CUSTOMIZER+owner，前端**隐藏所有改价入口**（产品编辑页 STEP4、班期管理、价格日历编辑等） -2. **错误码处理**：调改价接口收到 `code=410115` 时，弹"无权改价，只有定制师本人或超级管理员可改价"提示（不要继续重试，不要刷新页面） -3. 兼容性：前端短期不改也没事（后端会拦），但 UX 不友好（运营点了按钮才发现"无权"），建议前端尽快配合 - ---- - -## 一、背景 - -用户口述铁规（2026-05-16）：定制师对自己的产品负责（价格策略也是个人决策），运营/客服等岗位不该改价。当前 4 个价格写入接口完全没角色校验，等于规则成空文 → 必须在 Service 入口拦截。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 1 | 批量设置价格日历 | POST | `/admin/product/item/price-calendar/batch-set` | **新增角色拦截** | -| 2 | 删除价格日历 | POST | `/admin/product/item/price-calendar/delete` | **新增角色拦截** | -| 3 | 保存班期 | POST | `/admin/product/item/schedule/save` | **新增角色拦截** | -| 4 | 批量创建班期 | POST | `/admin/product/item/schedule/batch-create` | **新增角色拦截** | - -（精确路径以代码 `AdminProductController` 为准） - ---- - -## 三、错误码 - -**新增** `PRICE_EDIT_PERMISSION_DENIED = 410115` - -返回示例： - -```json -{ - "code": 410115, - "message": "无权改价,只有定制师本人或超级管理员可改价,productId=2055138817265897473", - "data": null, - "success": false -} -``` - -HTTP status 仍是 200（业务错误码在 Result.code），保持项目惯例。 - ---- - -## 四、校验逻辑（伪代码） - -```java -public void checkPriceEditPermission(Long productId) { - String role = AdminContextUtil.getRole(); - if ("SUPER_ADMIN".equals(role)) return; // 超管放行 - if ("CUSTOMIZER".equals(role)) { - ProductDO p = getProductOrThrow(productId); - if (currentAdminId.equals(p.getCreatedBy())) return; // 定制师 + 本人创建放行 - } - throw new BusinessException(PRICE_EDIT_PERMISSION_DENIED, productId); -} -``` - ---- - -## 五、向后兼容 - -- ✅ 接口路径、入参、出参字段全部不变（只是多了一种业务错误码） -- ✅ SUPER_ADMIN 和 CUSTOMIZER（本人产品）行为不变 -- ❌ OPERATOR / CUSTOMER_SERVICE / ROOM_MANAGER / VEHICLE_MANAGER / MATERIAL_ADMIN / 普通 ADMIN 改价**会被拒**——但本来就不该改 - ---- - -## 六、不在本期范围（P2.1 #2428 跟踪） - -- 集合深 diff（dayHotels/dayNodes 子项变化展示） -- JSON size cap 20KB 防爆 -- CR 4 小修 -- helper 自身行为 4 case 单测 - ---- - -## 七、部署 - -测试服公网光信号红灯，**P2 暂未部署测试服**。等公网恢复后部署，前端可同步联调。 diff --git a/changelogs/2026-05/16_feat_product_v2_snapshot_save_restore.md b/changelogs/2026-05/16_feat_product_v2_snapshot_save_restore.md deleted file mode 100644 index 2e8651c..0000000 --- a/changelogs/2026-05/16_feat_product_v2_snapshot_save_restore.md +++ /dev/null @@ -1,194 +0,0 @@ -# product-v2: 产品全量快照 — 按需保存 + 一键还原（新功能） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2431 -> **Issue**: #2425 -> **日期**: 2026-05-16 -> **影响范围**: 产品编辑页右侧新增「版本管理」入口（保存/列表/还原/删除/标记永久） - ---- - -## ⚠️ 关键新功能（mmg 前端需新增 UI） - -产品支持「按需手动保存版本」+「一键还原到任意历史版本」。**这是个全新模块，前端需要新增 3 个组件**： - -1. **保存版本按钮**（产品编辑页右上角） -2. **版本列表页/抽屉**（点按钮看历史版本） -3. **还原对话框**（必填还原原因 ≥10 字符） - ---- - -## 一、设计要点 - -| 项 | 设计 | -|---|---| -| 触发方式 | **按需手动**（不是每次 EDIT 自动） | -| 存储位置 | 阿里云 OSS（`hlgl-test` bucket，prefix `hl-product-snapshots/`） | -| 压缩 | gzip（典型 40KB JSON 压到 8-10KB） | -| 版本上限 | 每产品最多 10 个；keep_forever 标记每产品最多 3 个 | -| 超阈值 | 自动删最老的非 keep_forever 快照 | -| 还原后 | 状态强制 DRAFT（避免与审批/上架冲突），保留 id/created_by/createdAt | -| 权限 | SUPER_ADMIN 或 CUSTOMIZER+owner（复用 P2 改价权限校验） | - ---- - -## 二、5 个新接口 - -### 1. 保存快照 -`POST /admin/product/item/{productId}/snapshots` - -入参 VO `ProductSnapshotSaveReqVO`: -| 字段 | 类型 | 必填 | 校验 | -|---|---|---|---| -| name | String | ✅ | ≤64 字符，同产品下唯一 | -| description | String | ❌ | ≤255 字符 | -| keepForever | Boolean | ❌ | 默认 false | - -出参：`Result<Long>` (snapshotId) - -**错误码**： -- `410120` SNAPSHOT_NOT_FOUND -- `410121` SNAPSHOT_INVALID_STATE（仅 DRAFT/COMPLETED 可保存） -- `410122` SNAPSHOT_NAME_DUPLICATE -- `410123` SNAPSHOT_SIZE_EXCEED（序列化 >1MB 拒绝） -- `410124` SNAPSHOT_KEEP_FOREVER_LIMIT（>3 个 keep_forever 拒绝） -- `410115` PRICE_EDIT_PERMISSION_DENIED（复用，非 SUPER_ADMIN/CUSTOMIZER+owner） -- `510100` SNAPSHOT_OSS_FAIL（OSS 服务端错误） - -### 2. 列表 -`GET /admin/product/item/{productId}/snapshots?page=1&size=20` - -出参（分页）： -```json -{ - "code": 200, - "data": { - "list": [{ - "id": "...", - "productId": "...", - "name": "上架前最终版", - "description": "改价前备份", - "fileSize": 9876, - "keepForever": true, - "createdBy": "...", - "createdByName": "wangyu", - "createdAt": "2026-05-16 17:23:11" - }], - "total": 5, - "pageNum": 1, - "pageSize": 20 - } -} -``` - -### 3. 还原 -`POST /admin/product/item/{productId}/snapshots/{snapshotId}/restore` - -入参 VO `ProductSnapshotRestoreReqVO`: -| 字段 | 必填 | 校验 | -|---|---|---| -| reason | ✅ | ≥10 字符 | - -**还原后效果**： -- 产品全字段 + 所有子表（priceCalendars/days/dayNodes/dayHotels/feeItems/supplies/tiers/...）恢复到快照时点 -- 产品状态强制设回 `DRAFT` -- 产品 id / created_by / createdAt 保持不变 -- 自动写一条 `RESTORE` 操作日志，detail = `"还原至 {name} ({createdAt}), 原因: {reason}"` - -**错误码**： -- `410125` SNAPSHOT_RESTORE_PUBLISHED（已上架不能还原，必须先 UNPUBLISH） -- `410126` SNAPSHOT_RESTORE_HAS_ORDER（有报名班期不能还原） - -### 4. 删除 -`DELETE /admin/product/item/{productId}/snapshots/{snapshotId}` - -软删 MySQL + 异步删 OSS 对象（OSS 删失败 log.warn 不阻塞）。 - -### 5. 标记/取消永久保留 -`PUT /admin/product/item/{productId}/snapshots/{snapshotId}/keep-forever?keepForever=true` - -切换 keep_forever 标记。设 true 时校验 keep_forever 总数 < 3。 - ---- - -## 三、前端 UI 建议（mmg） - -### 保存按钮（编辑页右上角） - -```jsx -<Button - type="primary" - icon={<SaveOutlined />} - disabled={!isDraft && !isCompleted} // PUBLISHED/审批中禁用 - onClick={openSaveDialog} -> - 保存版本 -</Button> -``` - -保存对话框： -- 输入版本名（如"上架前最终版" / "调价前备份"） -- 选填描述 -- 复选框「永久保留（不被阈值清理）」 - -### 版本列表（侧边抽屉） - -| 版本名 | 描述 | 大小 | 创建人 | 时间 | 操作 | -|---|---|---|---|---|---| -| 上架前最终版 📌 | 改价前备份 | 9.6 KB | 王宇 | 17:23 | 还原 / 删除 / 取消📌 | -| 改 6 月价之前 | — | 8.2 KB | 王宇 | 16:01 | 还原 / 删除 / 📌 | - -📌 = keep_forever 标记，不会被阈值清理删除。 - -### 还原对话框 - -``` -⚠️ 还原到「上架前最终版」(2026-05-16 17:23) - -还原后： -- 产品所有字段会回到该版本（包括价格、行程、备品等） -- 产品状态会强制设回"草稿" -- 操作日志会记录一条 RESTORE - -还原原因（必填，≥10 字）: -[ ] - -[ 确认还原 ] [ 取消 ] -``` - ---- - -## 四、部署前置（运维必做） - -合并部署前 **nacos 必须配 OSS 凭据**，否则保存/还原接口返 `SNAPSHOT_OSS_FAIL`： - -```yaml -# hl-common-{dev,test,prod}.yml -product: - snapshot: - oss: - access-key-id: <AK> - access-key-secret: <SK> - bucket: hlgl-test # 或新建专用 bucket - endpoint: oss-cn-beijing.aliyuncs.com # 已有默认值 - key-prefix: hl-product-snapshots # 已有默认值 - max-per-product: 10 # 已有默认值 - max-keep-forever-per-product: 3 # 已有默认值 - max-size-bytes: 1048576 # 已有默认值 -``` - ---- - -## 五、向后兼容 - -- ✅ 新增功能，不影响任何现有接口 -- ✅ Flyway V20260516_004 只建新表 product_snapshot -- ✅ 老日志/老产品完全不受影响 -- ✅ 前端不实施新 UI 也不会出错（只是不显示新功能） - ---- - -## 六、不在本期范围（P2.1 #2428 + P2-4 #2426） - -- 集合深 diff（dayHotels 子项变化）— P2.1 #2428 -- 跨产品聚合可视化页 — P2-4 #2426 diff --git a/changelogs/2026-05/16_fix_mp_product_detail_supplies_cover_url.md b/changelogs/2026-05/16_fix_mp_product_detail_supplies_cover_url.md deleted file mode 100644 index 24171a1..0000000 --- a/changelogs/2026-05/16_fix_mp_product_detail_supplies_cover_url.md +++ /dev/null @@ -1,94 +0,0 @@ -# 小程序产品详情备品图片不显示修复 - -> **服务**: hl-product-service-v2 (端口 8083) + hl-resource-service (端口 8082) -> **PR**: #2421 -> **Issue**: #2420 -> **日期**: 2026-05-16 -> **影响范围**: 小程序产品详情「出行备品」section 的封面图 - ---- - -## ⚠️ 关键变化 - -之前小程序产品详情「出行备品」**所有备品图片都不显示**(灰色占位)。本 PR 后: -- 正式存量 85 条 `product_supplies.cover_url` 已立即手动回填(用户无需等部署),刷新小程序即可看到图 -- 编辑产品 Step3 备品保存后,新增/修改的备品会自动写入封面快照 - ---- - -## 一、根因 - -`ProductRouteService.saveRoute` Step3 备品保存逻辑历来未走 Feign 回填封面快照: -- `SuppliesItem` 请求 VO 不含 coverUrl 字段(前端不应该传) -- `BeanUtil.toBean(SuppliesItem, ProductSuppliesDO.class)` 拷贝出来 `coverUrl` 必然 null -- 哪怕走 `ProductSuppliesComboExpander` 组合展开路径,也会被中间的 DO→VO→DO 反复拷贝丢字段 - -结果: 正式 `product_supplies.cover_url` 全表 85/85 全 NULL。C 端 `SuppliesVO.coverUrl` 直接来自该列,前端必然渲染空图。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 批量获取备品封面图 | GET | `/internal/supplies/covers/batch` | 新增内部接口 | 资源服务暴露,产品服务 Feign 调用 | -| 2 | Step3 路线与备品保存 | POST | `/admin/product-v2/{id}/route` | 行为修复 | 保存后自动回填 cover_url,前端 payload 不变 | -| 3 | C 端产品详情 | GET | `/mp/product/{id}/detail` | 行为修复 | `supplies[].coverUrl` 不再为 null | - -前端接口契约**完全不变**,前端无需修改任何代码。 - ---- - -## 三、数据库变更 - -```sql --- V20260516_002__backfill_supplies_cover_url.sql --- 跨库 JOIN, hl_app 账号对两个库都有权限 -UPDATE product_supplies ps -JOIN hl_resource_service.supplies_item si ON si.supplies_id = ps.supplies_resource_id -JOIN hl_resource_service.material m ON m.material_id = si.cover_material_id -SET ps.cover_url = m.oss_url -WHERE ps.cover_url IS NULL - AND ps.supplies_resource_id IS NOT NULL - AND m.oss_url IS NOT NULL - AND m.oss_url <> ''; -``` - -- 正式 RDS 已于 2026-05-16 13:41 手动跑过相同 SQL, affected=85,补全后 null_or_empty=0 -- 测试服: 下次部署跑 Flyway 自动生效(幂等 WHERE IS NULL) - ---- - -## 四、边界行为 - -- **自定义备品(suppliesResourceId=NULL)**: 不会调 Feign,coverUrl 保持 NULL(本来就没有资源库材料可拷) -- **资源服务不可用**: Feign Fallback 降级返空列表,本次保存 cover_url 保持 NULL,**不阻断产品保存**,下次保存重试。区别于 ComboExpander 失败必须阻断保存。 -- **资源库材料已软删 / 无封面材料**: 服务端 `batchGetCoverUrls` 自动过滤,消费方按 ID 取不到即视为无封面,DO.coverUrl 保持 null。 - ---- - -## 五、不影响范围 - -- **仅影响**: 管理端 Step3 备品保存 + 小程序产品详情 supplies[].coverUrl -- **零影响**: - - 其它管理端步骤(step1/2/4/5) - - 订单 / 商家 / 用户服务 - - 备品组合 (`supplies_combo`) 自身的 cover_url(走 ComboFeignClient,不变) - - `product_supplies` 表其它列(supplies_name / category / billing_type 等) - - 自定义备品(无资源库 ID 那种) - ---- - -## 六、测试环境已验证 - -- [x] hl-resource-service / hl-product-service-v2 mvn compile SUCCESS -- [x] 正式 RDS DESC product_supplies + 抽查 22 条 cover_url 全 OSS URL -- [x] 复现产品 `2055092537149804545` 备品 22 条 (车上拖鞋成人/儿童/指甲刀/晕车贴等) cover_url 全部 OSS URL -- [ ] 测试服部署后小程序详情备品图片可见 (待 mmg 部署后回归) - ---- - -## 七、相关文档 - -- 关联 Issue: [wx/HL#2420](https://git.1814.love:8443/wx/HL/issues/2420) -- 关联 PR: [wx/HL#2421](https://git.1814.love:8443/wx/HL/pulls/2421) diff --git a/changelogs/2026-05/16_fix_product_fee_item_name_extend_to_512.md b/changelogs/2026-05/16_fix_product_fee_item_name_extend_to_512.md deleted file mode 100644 index bfc1b19..0000000 --- a/changelogs/2026-05/16_fix_product_fee_item_name_extend_to_512.md +++ /dev/null @@ -1,74 +0,0 @@ -# 产品 step5 提交报「字段【name】内容过长」修复 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2412 -> **Issue**: #2411 -> **日期**: 2026-05-16 -> **影响范围**: 产品编辑 step5「补充信息」提交审核 - ---- - -## 一、背景 - -正式环境 admin.1814.love 产品编辑页点「提交审核」时弹出: - -> 字段【name】内容过长，请删减后重试 - -实测复现产品 ID `2055092537149804545`(一次把呼伦贝尔玩进童年的亲子旅行)。 - -**根因**: `product_fee_item.name` 列原定义 `VARCHAR(128)`。线上已有产品该列最长值 106 字符(「游玩项目」类列表型费用项,串联多个景点名),用户在 step5 再追加一两个景点名即破 128,触发 MySQL `Data too long for column 'name'`。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | step5 补充信息保存 | POST | `/admin/product/{id}/supplement` | DB 列长度扩容 | name 字段从 128→512 字符 | - -接口契约**完全不变**,只是底层存储不再因字符过长失败。前端无需任何代码改动。 - ---- - -## 三、数据库变更 - -```sql -ALTER TABLE `product_fee_item` - MODIFY COLUMN `name` VARCHAR(512) DEFAULT NULL COMMENT '名称'; -``` - -- 正式 RDS 已于 2026-05-16 13:13 手动 ALTER 生效(用户授权) -- 测试服: 下次部署跑 Flyway `V20260516_001` 自动生效(幂等) -- dev: schema.sql 第 288 行同步更新 - ---- - -## 四、边界行为 - -- 接口层(VO)**无字符长度校验**,前端只要 payload 合法,后端不会再因 name 长度报错 -- 原本已经存进 DB 的 ≤128 字符行不受影响 - ---- - -## 五、不影响范围 - -- **仅影响**: 管理后台产品编辑 step5 费用项 name 字段写入 -- **零影响**: - - 任何 C 端接口 - - 订单 / 商家 / 资源服务 - - step1-step4 任何字段 - - product_fee_item 其它列(description / unit_price 等) - ---- - -## 六、测试环境验证(待回归) - -- [x] 正式 RDS `DESC product_fee_item` 验证 name 列已是 `varchar(512)` -- [ ] 测试服部署完后,复现产品 step5 提交不再报「字段【name】内容过长」(由 mmg 部署后回归) - ---- - -## 七、相关文档 - -- 关联 Issue: [wx/HL#2411](https://git.1814.love:8443/wx/HL/issues/2411) -- 关联 PR: [wx/HL#2412](https://git.1814.love:8443/wx/HL/pulls/2412) diff --git a/changelogs/2026-05/18_feat_product_fee_included_split_no_hotel_with_icon.md b/changelogs/2026-05/18_feat_product_fee_included_split_no_hotel_with_icon.md deleted file mode 100644 index dc399ea..0000000 --- a/changelogs/2026-05/18_feat_product_fee_included_split_no_hotel_with_icon.md +++ /dev/null @@ -1,193 +0,0 @@ -# 产品费用包含: 自动生成不再产「住宿」+ 每节点 1 条独立 VO 带行程图标 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2484 -> **Issue**: #2477 -> **日期**: 2026-05-18 -> **影响范围**: 管理端 产品编辑「补充信息 → 费用说明 → 费用包含」+ 小程序产品详情 includedFees - ---- - -## ⚠️ 关键变化 - -1. 「费用包含 → 根据行程自动生成」按钮的后端返回结构**从 N 条合并改为 N 条独立**: - - 之前: 同一 feeType 的所有节点合并成 1 条,`name="A，B，C，D"` 用「，」拼接字符串 - - 现在: 每个 SCENIC / ACTIVITY 行程节点产出 1 条独立 `FeeDeductionPreviewVO`,`name=单个节点名` -2. **不再产出 `feeType="住宿"`**:酒店表 `product_day_hotel` + HOTEL 行程节点两个来源全部禁用 -3. **icon 字段透传行程节点 `emoji_icon`**:可能是 lucide 图标名 / emoji / SVG 字符串,**前端需兼容渲染** -4. 同名节点跨天去重:同一景区在多天出现只保留行程顺序最早的那条 -5. 排序:外层按 feeLabel 优先级(景区 → 游玩项目 → 餐饮 → 交通),内层按 dayId asc + sortOrder asc - ---- - -## 一、背景 - -用户期望小程序产品详情「景区门票」「游玩项目」分组下每个景区/游玩项目独立 1 个 chip + 图标(参见小程序详情截图),但当前合并字符串无法满足,且自动产出的「住宿」条目跟专门住宿配置重复,语义混乱。 - -| 维度 | 旧行为 | 新行为 | -|------|--------|--------| -| 同 feeType 多节点 | 合并 1 条 name="A，B，C" | N 条独立 VO | -| HOTEL 节点 / day_hotel | 产「住宿」 1 条 | **不产出** | -| icon | 一直 null | 透传 `node.emojiIcon` | -| 同名跨天 | 合并字符串中重复出现 | 去重保留首次出现 | - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 费用推导预览 | GET | `/admin/product/item/{id}/fee-deduction-preview` | 返回结构(数组语义) | 从 N 条合并 → N 条独立,无「住宿」,带 icon | -| 2 | 保存补充信息 | PUT | `/admin/product/item/{id}/supplement` | 入参语义(不强制变) | `includedFees` 现在支持 N 条独立项 + icon(VO 字段已有,只是含义) | -| 3 | 管理端产品详情 | GET | `/admin/product/item/{id}` | 返回 includedFees 数组形态 | DB 保存什么读什么(取决于用户保存方式) | -| 4 | 小程序产品详情 | GET | `/mp/product/{id}` | 返回 includedFees 数组形态 | 同上 | - ---- - -## 三、接口详情 - -### 1. 费用推导预览 `GET /admin/product/item/{id}/fee-deduction-preview` - -**VO**: `FeeDeductionPreviewVO` - -#### 入参 - -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| id | Path | Long | ✅ | 产品ID | - -#### 出参 `Result<List<FeeDeductionPreviewVO>>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| feeType | String | 景区 / 游玩项目 / 餐饮 / 交通(**不再出现「住宿」**) | -| name | String | 单个节点名(`node.nodeName`),**不再用「，」拼接** | -| source | String | `AUTO`(常量) | -| sourceNodeName | String | 来源节点名(目前 = name) | -| icon | String? | 来自 `node.emojiIcon`:**可能是 lucide 名 / emoji / SVG 字符串**,前端兼容渲染;无图标的节点为 null | - -#### 响应示例(测试服真测产品 2045345825172639746) - -```json -{ - "code": 200, - "data": [ - { - "feeType": "景区", - "name": "中俄边境公路(卡线)", - "source": "AUTO", - "sourceNodeName": "中俄边境公路(卡线)", - "icon": "<svg xmlns=\"http://www.w3.org/...\"/>" - }, - { "feeType": "景区", "name": "黑山头", "source": "AUTO", "sourceNodeName": "黑山头", "icon": "<svg ...>" }, - { "feeType": "景区", "name": "百里雾凇画廊", "source": "AUTO", "sourceNodeName": "百里雾凇画廊", "icon": "<svg ...>" }, - { "feeType": "景区", "name": "海拉尔国家森林公园", "source": "AUTO", "sourceNodeName": "海拉尔国家森林公园", "icon": "<svg ...>" }, - { "feeType": "游玩项目", "name": "满洲里草原篝火晚会", "source": "AUTO", "sourceNodeName": "满洲里草原篝火晚会", "icon": "<svg ...>" }, - { "feeType": "游玩项目", "name": "冬日烟花", "source": "AUTO", "sourceNodeName": "冬日烟花", "icon": null }, - { "feeType": "游玩项目", "name": "ATV全地形越野车穿越", "source": "AUTO", "sourceNodeName": "ATV全地形越野车穿越", "icon": "<svg ...>" }, - { "feeType": "游玩项目", "name": "蒙古族小型冰雪那达慕", "source": "AUTO", "sourceNodeName": "蒙古族小型冰雪那达慕", "icon": "<svg ...>" } - ], - "success": true -} -``` - -### 2 / 3 / 4. 保存与详情接口 - -VO 结构未变(`FeeItem.icon` / `FeeInfo.icon` 字段早已预留),只是含义换成「N 条独立项」:每个景区/游玩项目 1 个 chip,前端无需聚合。 - ---- - -## 四、契约与渲染建议(前端必看) - -### icon 字段三种格式都要兼容渲染 - -| 来源 | icon 形态 | 渲染方式建议 | -|------|-----------|------| -| 自动推导(行程节点 emojiIcon) | lucide 图标名(如 `"mountain"`)或 emoji(如 `"🏔"`) | lucide 图标渲染器 + emoji 直接 text 渲染 | -| 手动添加(图标库选择) | SVG 字符串 `<svg ...>...</svg>` | dangerouslySetInnerHTML 渲染 | -| 节点没设图标 | `null` | 占位或不渲染 | - -**最简兼容写法**:`if (icon?.startsWith('<svg')) {渲染 SVG} else if (icon) {lucide(icon) or 当 emoji} else {默认占位}` - -### 展示方式变化 - -- admin 产品编辑第 5 步「费用包含」: 从 1 条多名字字符串 → **N 个独立 chip**,与小程序「景区门票/游玩项目」分组下的 chip 对齐 -- 小程序产品详情 includedFees: 每条 1 个 chip,无需前端拆分逗号 - ---- - -## 五、数据库行为 - -| 场景 | product_fee_item 表 | -|------|---------------------| -| 自动生成 + 保存 1 个含 4 景区 3 游玩项目的产品 | 7 行 INCLUDED + AUTO 记录(每节点 1 行),icon 各自从 emoji_icon 来 | -| 不再产出「住宿」自动行 | 0 行 source=AUTO + fee_category=INCLUDED + fee_type=住宿 | -| 同名跨天 | 1 行(去重) | - -### ⚠️ 测试环境数据已清理(2026-05-18 10:58) - -部署后跑了一次性 SQL,软删了 117 条 source=AUTO + fee_category=INCLUDED 的历史数据(涉及 32 个产品): - -```sql -UPDATE product_fee_item SET deleted_at = NOW() -WHERE source = 'AUTO' AND fee_category = 'INCLUDED' AND deleted_at IS NULL; -``` - -**这些产品的费用包含目前为空**,需要运营/定制师重新打开产品编辑页 → 第 5 步「补充信息 → 费用包含 → 根据行程自动生成」+ 保存,系统会按新格式产出 N 条独立条目。 - -**未受影响**:`excludedFees`(费用不含)/ `customFees`(自定义费用)/ 手动添加的 INCLUDED 项保留不动。 - ---- - -## 六、边界行为 - -- 产品无节点 / 无 SCENIC + ACTIVITY → 返回 `[]` -- 节点 emoji_icon 为 null → icon 字段为 null(前端走「无图标占位」分支) -- 节点 nodeType=HOTEL → 不进入返回(被过滤) -- supplement.feeIgnoredTypes 含「门票」/「活动」/等 → 该类型整组被过滤 - ---- - -## 七、不影响范围 - -- **仅影响**: - - admin 产品编辑第 5 步「费用包含」展示与保存 - - 小程序产品详情 `includedFees` 渲染 -- **零影响**: - - 费用不含 `excludedFees` / 自定义费用 `customFees` - - 产品定价 / 班期 / 订单创建 / 算价 / 报价 - - 已有的住宿专门配置(`product_day_hotel`)— 它仍然是住宿数据的权威来源,只是不再走「费用包含-自动生成」这条路 - - 手动添加的费用项不动 - ---- - -## 八、测试环境已验证 - -``` -GET /admin/product/item/2045345825172639746/fee-deduction-preview → 200 + 8 条独立 VO ✓ - - 4 景区 + 4 游玩项目,无「住宿」 - - icon non-null 7/8(对应行程节点 emoji_icon 已设) - - feeType breakdown 与小程序产品详情「景区门票/游玩项目」chip 精确对应 - -UPDATE product_fee_item ... → 117 条 / 32 个产品 软删,清理精准(excludedFees 7 条保留) ✓ - -GET /admin/product/item/2045345825172639746 → includedFees=[](清理生效) ✓ -``` - -验证产品: `productId=2045345825172639746`(测试服「游牧的森林-短途版」) - ---- - -## 九、相关历史 PR - -| PR | Issue | 说明 | -|----|-------|------| -| 早期 | (无) | 「自动生成」按钮的合并字符串实现 | -| **#2484** | **#2477** | 取消合并 + 去住宿 + 带 icon,本次 | - ---- - -## 十、相关文档 - -- 关联 Issue: [wx/HL#2477](https://git.1814.love:8443/wx/HL/issues/2477) -- 关联 PR: [wx/HL#2484](https://git.1814.love:8443/wx/HL/pulls/2484) diff --git a/changelogs/2026-05/18_feat_product_v2_snapshot_p23_loosen_save_group_batch.md b/changelogs/2026-05/18_feat_product_v2_snapshot_p23_loosen_save_group_batch.md deleted file mode 100644 index a1eb041..0000000 --- a/changelogs/2026-05/18_feat_product_v2_snapshot_p23_loosen_save_group_batch.md +++ /dev/null @@ -1,173 +0,0 @@ -# product-v2: 产品快照 P2.3 — 保存放宽 + GROUP 班期完整 + 弹窗交互（mmg 必看） - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2478 -> **Issue**: #2470 -> **日期**: 2026-05-18 -> **影响范围**: 产品快照保存权限/状态放宽 + GROUP 类产品班期完整保存 + 提交上架/完成设计 UI 加保存版本弹窗 - ---- - -## ⚠️ 关键变化（前端 mmg 必看） - -### 1. 保存版本权限：Service 层校验删除（但外层 @DataScope 仍生效） -- **旧**：Service 层 `checkPriceEditPermission` 校验 SUPER_ADMIN 或 CUSTOMIZER+owner -- **新**：Service 层校验**已删除**（saveSnapshot 不再调 checkPriceEditPermission） -- ⚠️ **实际效果（2026-05-18 测试服 e2e 验证）**： - - SUPER_ADMIN：任何产品都能保存 ✅ - - CUSTOMIZER：**只能保存自己创建的产品**（外层 `@DataScope` 数据权限拦截非 owner 产品 → HTTP 403 "无操作权限"） - - OPERATOR / 其他角色：受外层数据权限+菜单权限制约，**通常不能操作产品快照接口** -- **真实业务收益**：解锁了「定制师本人 + 该产品所属公司其他 CUSTOMIZER 同事」的多角色保存场景（之前只 SUPER_ADMIN 或单一 owner）。彻底"所有 admin 都能保存任意产品"**没达成**（@DataScope 拦着，符合业务安全考虑——CUSTOMIZER 不该备份别人的产品） -- 还原/删除/标记永久**仍保留 Service 层 checkPriceEditPermission 严格校验** - -### 2. 状态校验彻底取消（PR #2487 → PR #2493 修正最终态） -- ~~P2.3 初版：`DRAFT / UNPUBLISHED / COMPLETED` 三种~~ -- ~~PR #2487 (错的, 已被 #2493 推翻)：保存 = 备份 + 强制退草稿组合~~ -- **最终态（PR #2493）**：**任意状态都可保存, 且保存动作绝不改产品状态** - - PUBLISHED 产品保存 → 仍 PUBLISHED, mp 端**不下架** - - UNPUBLISHED / 审批中产品保存 → 状态**保持不变** - - DRAFT 产品保存 → 仍 DRAFT -- ⚠️ **退草稿只发生在「还原版本」(restoreSnapshot)**, 不在「保存版本」(saveSnapshot) -- mmg 弹窗文案修正: - - 「保存版本」弹窗: **去掉**"保存后产品将退回草稿状态"的警告 (PR #2487 时让 mmg 加, 现在错的要去掉) - - 「还原版本」弹窗: **保留**"还原后产品状态将变为草稿"警告 (这是真实行为) - -### 3. GROUP 小蒙马班期完整保存（修复缺陷） -- **旧版 P2.2 漏存** `group_tour_batch` 表 → GROUP 还原后班期数据丢失 -- **新版** ProductSnapshotPayload 加 `productType` + `groupTourBatches` 两字段，GROUP 产品快照含完整班期，还原可恢复 - -### 4. 还原时类型一致性校验 -- 还原前校验 `payload.productType == 当前 product.productType` -- 跨类型还原（如 CORE 快照试图还原到 GROUP 产品）返 `SNAPSHOT_TYPE_MISMATCH (410128)` -- 老快照 `productType=null` 兼容放行（不强制） - ---- - -## 🎨 前端弹窗交互（mmg 必做） - -P2.3 用户体验目标：用户在「提交上架」或「完成设计」前，前端弹窗提示「是否保存当前版本」，避免上架后想还原但没快照。 - -### 交互流程 - -``` -┌────────────────────────────────────┐ -│ [提交上架] 按钮 / [完成设计] 按钮 │ -└─────────────────┬──────────────────┘ - │ 点击 - ▼ -┌────────────────────────────────────┐ -│ 弹窗 "是否保存当前版本？" │ -│ │ -│ 上架/完成设计后想要恢复到此版本 │ -│ 必须先保存。 │ -│ │ -│ [保存并提交] [直接提交] [取消] │ -└──┬──────────────┬──────────────┬───┘ - │ │ │ - │ 选保存并提交 │ 选直接提交 │ 选取消 - ▼ ▼ ▼ -1. POST /admin/product/item/{id}/snapshots - body: { name: "上架前自动备份-2026-05-18 14:30", - description: "提交上架前自动保存", - keepForever: false } -2. POST /admin/product/item/{id}/toggle-publish → 直接 POST /toggle-publish - 或 /complete 或 /complete 无操作 -``` - -### 实现建议 -- 弹窗组件可以**默认勾选「保存并提交」**（鼓励保存） -- 版本名可让用户填，也可前端自动生成（如 `"上架前自动备份-${yyyy-MM-dd HH:mm}"`） -- 描述选填，留空自动填触发动作（如 `"提交上架前自动保存"` / `"完成设计前自动保存"`） -- 用户选「直接提交」时也可以记录到操作日志，便于审计 - -### 触发时机的接口 -| 触发动作 | URL | Method | -|---|---|---| -| 提交上架 | `/admin/product/item/{id}/toggle-publish` | POST | -| 完成设计（仅 CUSTOM） | `/admin/product/item/{id}/complete` | POST | -| 保存快照 | `/admin/product/item/{id}/snapshots` | POST | - ---- - -## 一、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更 | -|---|------|------|------|------| -| 1 | 保存快照 | POST | `/admin/product/item/{id}/snapshots` | **权限放宽** + **状态扩** + **GROUP 含班期** | -| 2 | 还原快照 | POST | `/admin/product/item/{id}/snapshots/{snapshotId}/restore` | **加类型一致性校验** | - ---- - -## 二、接口详情 - -### 1. 保存快照（权限+状态放宽） - -**入参 VO**（无变化）：name + description + keepForever，详见 PR #2431 changelog。 - -**校验变化**： -| 校验项 | 旧 | 新 | -|---|---|---| -| 角色 | SUPER_ADMIN 或 CUSTOMIZER+owner | **所有 admin 登录态** | -| 状态 | DRAFT / COMPLETED | **DRAFT / UNPUBLISHED / COMPLETED** | -| 同名 | 拒绝 | 同 | -| 大小 | >1MB 拒绝 | 同 | -| keep_forever 上限 | 3 个/产品 | 同 | - -**出参**：`Result<Long>` (snapshotId) 无变化 - -### 2. 还原快照（加类型一致性校验） - -**新校验**：快照保存时记的 `productType` 必须等于当前产品的 `productType` - -**新错误码**：`410128 SNAPSHOT_TYPE_MISMATCH` — `"快照类型与当前产品不一致, 快照=CORE, 当前=GROUP"` - -**老快照兼容**：PR #2431 时代保存的快照 `productType=null`，还原时**放行**（不强制校验） - ---- - -## 三、新增字段（payload 结构变化） - -`ProductSnapshotPayload` JSON 结构新增 2 字段： - -```json -{ - "schemaVersion": 1, - "productType": "GROUP", // ⬅ 新增, 用于还原时一致性校验 - "product": { ... }, - "basic": { ... }, - "supplement": { ... }, - ... - "groupTourBatches": [ // ⬅ 新增, GROUP 才有非空, CORE/CUSTOM 为 [] - { "batchId": "...", "departureDate": "2026-07-15", "adultSellPrice": 3800.00, ... } - ] -} -``` - -前端**不需要解析这个 JSON**（在 OSS 上 + 后端透明处理），仅需知道： -- 新版 GROUP 快照含完整班期信息 -- 还原可能返 `410128` 类型不一致错误 - ---- - -## 四、向后兼容 - -- ✅ 接口路径、入参、HTTP 方法、原有出参字段全部不变 -- ✅ 老 payload（productType=null）反序列化兼容（已加 @JsonIgnoreProperties(ignoreUnknown=true)） -- ✅ 老快照还原时不强制类型校验 -- ✅ 前端不实施弹窗也不影响（只是少了 UX 改进） - ---- - -## 五、部署 - -- 测试服：自动同步 dev 部署 -- 正式服：等 Deploy Panel /prod 触发 -- nacos: 无需配置（OSS 配置 PR #2435 已对齐全局 oss.*） - ---- - -## 六、不在本期范围 - -- 集合深 diff（P2.1 #2428 单独跟） -- 调价告警（用户已决策不做） -- 跨产品聚合可视化页（P2-4 #2426，mmg 前端工作） diff --git a/changelogs/2026-05/18_fix_product_v2_oplog_node_detail.md b/changelogs/2026-05/18_fix_product_v2_oplog_node_detail.md deleted file mode 100644 index b374570..0000000 --- a/changelogs/2026-05/18_fix_product_v2_oplog_node_detail.md +++ /dev/null @@ -1,69 +0,0 @@ -# product-v2: 行程操作日志展开节点/天/住宿具体变化 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2511 -> **Issue**: #2510 -> **日期**: 2026-05-18 -> **影响范围**: STEP2 行程编辑操作日志 `changes` 字段输出形态 - ---- - -## mmg 必看 — 接口契约不变,changes 内部条数和内容形态变化 - -接口 URL / Method / 入参 / 出参字段类型**完全不变**。仅 `changes[]` 数组的条数和每条 `fieldLabel`/`oldValue`/`newValue` 内容形态优化。 - -### 修复前(聚合,看不出动了哪个节点) - -```json -"changes": [ - { - "fieldLabel": "活动节点列表", - "oldValue": "共 11 条", - "newValue": "共 8 条 (新增 0 / 删除 3)", - "changeType": "MODIFY" - } -] -``` - -用户原话:**"没法直观的发现变化应该写具体的节点变化"**。 - -### 修复后(展开,每个节点变化各一条) - -```json -"changes": [ - { "fieldLabel": "删除 活动节点", "oldValue": "DAY 1 #3 中俄边境公路（卡线）", "newValue": null, "changeType": "DELETE" }, - { "fieldLabel": "删除 活动节点", "oldValue": "DAY 2 #1 雾凇画廊", "newValue": null, "changeType": "DELETE" }, - { "fieldLabel": "删除 活动节点", "oldValue": "DAY 4 #2 那达慕狂欢", "newValue": null, "changeType": "DELETE" }, - { "fieldLabel": "新增 活动节点", "oldValue": null, "newValue": "DAY 1 #5 海拉尔国家森林公园", "changeType": "ADD" }, - { "fieldLabel": "修改 活动节点", "oldValue": "DAY 1 #1 礼仪送机", "newValue": "DAY 1 #1 礼仪送机+迎宾", "changeType": "MODIFY" } -] -``` - -### 三个集合的 display 格式 - -| 集合 | display 格式 | 例 | -|---|---|---| -| 行程天 | `DAY X` | `DAY 1` | -| 活动节点 | `DAY X #序号 节点名称` | `DAY 1 #5 海拉尔国家森林公园` | -| 住宿 | `DAY X 档位N 酒店ID=...` | `DAY 1 档位1 酒店ID=2046123456789` | - -### 上限保护 - -单次行程编辑变化 > 30 条时,前 30 条展开,剩余聚合成一条 `"其他 N 项变更未展开 (日志条数超上限 30)"`。 - ---- - -## 服务端改动 - -- `EntityFieldDiffUtil.diffCollectionDetailed(...)`: 新方法,接受 `oldDisplay/newDisplay` 抽取器,把集合 diff 展开成 ADD/DELETE/MODIFY 各一条 FieldChange -- `ProductItineraryService.buildItineraryChanges`: 三集合都改用 detailed 版,提供 display 抽取器 -- 由于 NodeItem/HotelItem VO 没 `dayId` 字段,用 `IdentityHashMap<NodeItem, Integer>` 在遍历 newDays 时建反向映射 -- ProductItineraryServiceTest 17/17 全绿 - ---- - -## 部署 - -- 测试服: 已部署 (deploy task `e88d639e`) -- 正式服: 等 Deploy Panel /prod 触发 -- nacos: 无配置变化 diff --git a/changelogs/2026-05/18_fix_product_v2_oplog_tier_filter_and_friendly_display.md b/changelogs/2026-05/18_fix_product_v2_oplog_tier_filter_and_friendly_display.md deleted file mode 100644 index 493ef06..0000000 --- a/changelogs/2026-05/18_fix_product_v2_oplog_tier_filter_and_friendly_display.md +++ /dev/null @@ -1,90 +0,0 @@ -# product-v2: 操作日志两个 UX 改进 — 价格档位过滤 + 长字段友好展示 - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2505 (价格日历档位过滤) + #2508 (changes 友好展示) -> **Issue**: #2504 + #2507 -> **日期**: 2026-05-18 -> **影响范围**: 产品操作日志 `changes` 字段(GET /admin/product/item/{id}/operation-logs 出参 `data[].changes`) - ---- - -## mmg 必看 — 接口契约不变,只是 changes 内容更友好 - -接口 URL / Method / 入参 / 出参结构**完全不变**。仅 `changes[]` 数组里 `oldValue` / `newValue` 字段的内容形态优化: - -### 1. 价格日历操作日志只列本次档位字段(PR #2505) - -**修复前**:用户只改"轻奢档"价格,oplog 同时记录"高端档"全字段为 DELETE -``` -成人售价 [2026-05-09~05-22 (14 天)] [高端]: 4865 → — ← 用户没改, 误报 -儿童售价 [2026-05-09~05-22 (14 天)] [高端]: 1865 → — ← 用户没改, 误报 -``` - -**修复后**:同样操作,oplog 只列"轻奢档"字段 -``` -成人售价 [2026-05-29] [轻奢]: 5690 → 888 -儿童售价 [2026-05-29] [轻奢]: 2620 → 888 -单房差 [2026-05-29~05-30 (2 天)] [轻奢]: 0 → 500 -``` - -测试服 e2e 实测产品 2046069754753335297 设置 tierSeq=1, oplog 7 条全部 [轻奢], 无 [高端]。 - -### 2. 长 List / Map 字段不再裸 JSON 展示(PR #2508) - -**修复前**:装备建议 / 快速理解 / 儿童体验 / 成长收获 等 List<Map> 字段 -``` -装备建议: 已修改 ({"text":"111111","icon":"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\"...h14a4 4 0 1 1 0 8h-1\"/><path d=\"M6 2v2\"/></svg>","color":"rgb(197, 20, 20)"}) - → 已修改 ([ProductSupplementSaveReqVO.EquipmentItem(text=111111, icon=<svg ...) -孩子经历: [object Object] → — -``` - -**修复后**:Collection 给"已修改 (共 N 项)"摘要;Map 给"已修改";null/空给"未填写" -``` -装备建议: 已修改 (共 1 项) → 已修改 (共 1 项) -孩子经历: 未填写 → 已修改 (共 2 项) -快速理解: 已修改 (共 3 项) → 已修改 (共 3 项) -``` - -### 3. 展示车型同 ID 不再误判"已修改"(PR #2508) - -**修复前**:VO `List<Long>` 与 DO `Object`(JSON 反序列化为 List<Integer/String>)同 ID 但元素类型不同 -``` -展示车型: 2023765365569355778 → 2023765365569355778 ← 误判 MODIFY -``` - -**修复后**:`valuesEqual` Collection 分支不等时再走元素 stringify 顺序比较,同 ID 视为相等 -- 不再产出 FieldChange 条目 - ---- - -## 服务端改动 - -### PR #2505 (Closes #2504) -- `ProductPricingService.batchSetPriceCalendar`: 查 oldList 加 `tierSeq == req.getTierSeq()` 过滤(空回退 DEFAULT_TIER_SEQ) -- 80 单测全绿(ProductPricingServiceTest 69 + 关联 11) - -### PR #2508 (Closes #2507) -- `EntityFieldDiffUtil.friendlyLongDisplay(Object)`: 长字段友好展示统一入口 - - Collection → "已修改 (共 N 项)" - - Map → "已修改" - - String 短 → 原文,长 → 前80+后80摘要 - - null/空 → "未填写" -- `EntityFieldDiffUtil.hashIfNotNull(Object)`: hash 计算(Collection/Map 用 toString) -- `EntityFieldDiffUtil.valuesEqual`: Collection 分支不等时走 safeStringify(顺序保留) 兜底 -- 编译通过(本地机器 commit charge 99% 满, surefire fork 不出, 用测试服 e2e 验证) - ---- - -## 影响 - -- 前端不需要改代码,changes 字段类型不变(`Object`),只是值更友好 -- 长 List 字段不再泄漏内部 SVG/JSON,审计上"内容真改了"靠 `oldHash`/`newHash` SHA-256 前 16 位鉴定 -- 价格日历"我没改的档位被记 DELETE"的虚假日志彻底消除 - ---- - -## 部署 - -- 测试服: 已部署 (deploy task `e116c0b6` + `32469c73`) -- 正式服: 等 Deploy Panel /prod 触发 -- nacos: 无配置变化 diff --git a/changelogs/2026-05/18_fix_product_v2_snapshot_created_by_and_dialog_text.md b/changelogs/2026-05/18_fix_product_v2_snapshot_created_by_and_dialog_text.md deleted file mode 100644 index 1c18661..0000000 --- a/changelogs/2026-05/18_fix_product_v2_snapshot_created_by_and_dialog_text.md +++ /dev/null @@ -1,86 +0,0 @@ -# product-v2: 快照列表「创建人」回填 + 还原弹窗文案中文化(mmg 必看) - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2529 -> **Issue**: #2528 -> **日期**: 2026-05-18 -> **影响范围**: 版本管理列表展示 + 还原版本弹窗文案 - ---- - -## ⚠️ mmg 必看 - 两件事 - -### 1. 后端 RespVO 加了 `createdByName` 字段 — 列表展示绑这个 - -接口 URL / Method 不变,出参新增字段: - -```json -GET /admin/product/item/{id}/snapshots?pageNum=1&pageSize=10 -{ - "code": 200, - "data": { - "records": [ - { - "id": "...", - "name": "v1-行程定稿", - "description": "...", - "fileSize": 67890, - "keepForever": false, - "createdBy": 1001, - "createdByName": "张三", ← 🆕 新增字段,前端「创建人」列绑这个 - "createTime": "2026-05-18 14:30:00" - } - ] - } -} -``` - -**展示规则**: -- 历史 5 条 created_by=NULL 的快照, createdByName 也是 null → 前端展示「—」(已知,接受) -- 新保存的快照, createdByName 优先企微昵称, fallback username - -### 2. 「创建时间」列前端字段绑错请改 - -如果前端模板绑的是 `createdAt`, 改成 `createTime` (后端返的字段名是 `createTime`, 历史也一直是这个)。 - -### 3. 还原版本弹窗文案中文化(用户截图反馈) - -旧文案(英文/技术词,用户看不懂): - -``` -还原后: -- 产品所有字段(含价格、行程、备品等)会回到该版本 -- 产品状态会强制设回「草稿」, 原 publishedAt / approvalNo 会被清空 -- 已有订单(活跃报名)或处于「已上架」状态的产品无法还原 -- 操作日志会记录一条还原(RESTORE) -``` - -新文案建议: - -``` -还原后: -- 产品所有字段(含价格、行程、备品等)会回到该版本 -- 产品状态会强制设回「草稿」, 上架时间和审批编号会被清空 -- 已有订单(活跃报名)或处于「已上架」状态的产品无法还原 -- 操作日志会记录一条「还原版本」 -``` - -去掉 `publishedAt` / `approvalNo` / `RESTORE` 三个英文字段名/枚举值,改用中文业务术语。 - ---- - -## 服务端改动 - -- saveSnapshot 显式 setCreatedBy(AdminContextUtil.getAdminId()) 兜底 OperatorHolderFilter 未生效场景 -- ProductSnapshotRespVO 加 createdByName String 字段 -- ProductSnapshotService 加 enrichCreatedByName: 批量调 UserFeignClient.batchGetAdminInfo 回填, 与 ProductQueryService 同方案 -- 注入 UserFeignClient (@Nullable, 单测兼容) -- ProductSnapshotServiceTest 21/21 全绿 - ---- - -## 部署 - -- 测试服: 等待 PR #2529 后续部署 -- 正式服: 等下一次 release 合 main 后部署 -- nacos / DB: 无变化 diff --git a/changelogs/2026-05/18_fix_product_v2_snapshot_save_no_status_change.md b/changelogs/2026-05/18_fix_product_v2_snapshot_save_no_status_change.md deleted file mode 100644 index 49f3a5e..0000000 --- a/changelogs/2026-05/18_fix_product_v2_snapshot_save_no_status_change.md +++ /dev/null @@ -1,63 +0,0 @@ -# product-v2: 紧急修复 — 保存版本不再改产品状态(退草稿只在还原时发生) - -> **服务**: hl-product-service-v2 (端口 8083) -> **PR**: #2493 -> **Issue**: #2491 -> **关联 PR**: 修正 PR #2487 (本日上午合, 误把保存动作改成退草稿) -> **日期**: 2026-05-18 -> **影响范围**: 产品快照保存逻辑 + mmg 前端弹窗文案 - ---- - -## ⚠️ mmg 必看:撤回 PR #2487 的弹窗警告文案 - -### 修正前 (PR #2487, 错的) -- 「保存版本」弹窗加警告: 「保存后产品将退回草稿状态, 已上架产品会下架」 - -### 修正后 (PR #2493, 用户铁规) -- 「保存版本」弹窗: **删掉上面那行警告**, 保存动作纯粹是备份, 不会改任何产品状态 -- 「还原版本」弹窗: **保留**警告「还原后产品状态将变为草稿」(这才是真实行为) - ---- - -## 业务规则最终态(用户两次纠偏后定稿) - -| 动作 | 状态校验 | 保存/还原后产品状态 | -|------|----------|---------------------| -| **保存版本** (saveSnapshot) | 无 (任意状态可保存) | **保持原状态不变** (PUBLISHED→PUBLISHED, UNPUBLISHED→UNPUBLISHED) | -| **还原版本** (restoreSnapshot) | 非 PUBLISHED + 无活跃订单 + payload.productType 一致 | **强制 DRAFT** + 清空 publishedAt/approvalNo/pendingStatus | - ---- - -## 服务端改动 - -仅 ProductSnapshotService.java + Test，2 文件 / +18 / -87 行： - -- **saveSnapshot**: 删除 PR #2487 加的 `if (!DRAFT.equals(originalStatus)) helperService.updateProduct(patch)` 整段 -- **restoreSnapshot**: 代码**完全不动**, 既有 `updateProduct.setStatus(DRAFT)` 行为是正确的, 这才是用户要的 -- 强化 javadoc, 业务语义点明: 保存不改状态 / 还原必退草稿 -- 清理废弃常量 `SAVE_ALLOWED_STATUSES_LEGACY` 和无用 import -- 单测断言 `verify(helperService, never()).updateProduct(any())` 反证保存动作不调 update - ---- - -## 接口契约不变 - -- URL / Method / 入参 / 出参 全部不变 -- 仅是**行为修复**: 之前 PR #2487 让保存动作有了"自动退草稿"副作用, 这个副作用现在去掉了 - ---- - -## e2e 验收 (2026-05-18 测试服) - -- ✅ PUBLISHED 产品 (2049754271968047106) 保存 snapshotId=2056223052173131778, 前后 status=PUBLISHED -- ✅ UNPUBLISHED 产品 (2046069754753335297) 保存 snapshotId=2056223131302871042, 前后 status=UNPUBLISHED -- ✅ 单测全绿 (1295 product-v2 单测) - ---- - -## 部署 - -- 测试服: Deploy Panel task `b9e613ba` (2026-05-18 11:53, 已部署) -- 正式服: 待 Deploy Panel /prod 触发 -- nacos: 无需配置变化 diff --git a/changelogs/2026-05/18_refactor_order_todo_vo_updatetime_path_fix.md b/changelogs/2026-05/18_refactor_order_todo_vo_updatetime_path_fix.md deleted file mode 100644 index 79c3a20..0000000 --- a/changelogs/2026-05/18_refactor_order_todo_vo_updatetime_path_fix.md +++ /dev/null @@ -1,33 +0,0 @@ -# refactor(order): OrderTodoVO.updateTime 在「我的待办」「可签合同订单」2 个路径补返回 - -> **服务**: hl-order-service-v2 -> **PR**: #2469 (已合 dev,已部署测试服) -> **Issue**: #2468 (续 #2351 遗留尾巴) -> **日期**: 2026-05-18 -> **影响范围**: 管理后台 2 个待办相关查询接口 - ---- - -## 给前端的话 (mmg 看这里) - -`OrderTodoVO.updateTime` 字段先前在以下 2 个接口返回 null,本次补全: - -| 接口 | updateTime 实测 | -|------|----------------| -| `GET /admin/order/todo/my-list` (我的待办列表) | 2026-05-18 09:00:00 ✓ | -| `GET /admin/order/todo/contract-eligible` (可签合同订单列表) | 2026-04-28 14:21:19 ✓ | - -其他 OrderTodoVO 路径 (订单详情待办、按订单查 todos 等) PR #2353 已补,本次只是堵这两个用 mapper 自定义 SQL 返 DTO 的"漏洞"路径。 - -## 根因 - -`OrderTodoQueryService` 这两个方法走 `OrderTodoMapper` 的 `@Select` 自定义 SQL,返回 `ActiveTodoDTO` / `InsuranceCompletedDTO` 中转再 mapper 成 `OrderTodoVO`。**DTO 本身没有 update 字段**,即使后端 service 想 set 也无源。 - -## 修改清单 (4 文件 +11 -2) - -- `OrderTodoMapper.selectActiveTodos`: SELECT 加 `t.update_time AS updated_at` -- `OrderTodoMapper.selectInsuranceCompleted`: SELECT 加 `t.update_time AS updated_at` -- `ActiveTodoDTO`: 加 `private LocalDateTime updatedAt;` -- `InsuranceCompletedDTO`: 加 `private LocalDateTime updatedAt;` -- `OrderTodoQueryService.mapActiveTodoToVOList`: 补 `vo.setUpdateTime(dto.getUpdatedAt());` -- `OrderTodoQueryService.mapInsuranceToVOList`: 补 `vo.setUpdateTime(dto.getUpdatedAt());` diff --git a/changelogs/2026-05/19_fix_hl_ui_cost_desc_panel_manual_feetype.md b/changelogs/2026-05/19_fix_hl_ui_cost_desc_panel_manual_feetype.md deleted file mode 100644 index 7f58c86..0000000 --- a/changelogs/2026-05/19_fix_hl_ui_cost_desc_panel_manual_feetype.md +++ /dev/null @@ -1,136 +0,0 @@ -# hl-ui 费用包含: 手动添加项目误把"手动"塞进 feeType 导致 C 端显示成独立分类 - -> **仓库**: hl-ui (前端) -> **关联 PR/Issue**: (无,前端 BUG 不建工单) -> **日期**: 2026-05-19 -> **影响范围**: admin 产品编辑「补充信息 → 费用说明 → 费用包含 → 添加项目」 + 小程序产品详情 C 端「费用包含」区块 -> **接收方**: mmg (前端) -> **后端**: 无改动 (hl-product-service-v2 接口/VO/SQL 全部不动) - ---- - -## ⚠️ 关键变化 - -**前端 `CostDescPanel.vue` 把字符串字面量 `"手动"` 硬编码塞进 `feeType` 字段,导致 C 端小程序把这条"手动添加"的费用项渲染成独立分类卡片"手动",和「景区/游玩项目/餐饮/交通」等自动推导的分类并列。用户决策:`feeType: '手动'` → `feeType: '其他'`,**一行字面量改动,其他都不动**。** - ---- - -## 一、现象 - -正式环境复现路径: - -1. admin 产品编辑页 → 补充信息 → 费用说明 → **费用包含** → 点"添加项目" → 输入名称 `升级满洲里套娃酒店` → 保存 -2. 打开小程序 C 端「产品详情」→ 滚到「费用包含」区块 -3. 这条记录被渲染为:**主标题"手动" + 副标题"升级满洲里套娃酒店"** - -用户 (wx) 原话: - -> 这种"手动"作为分类名出现在 C 端不合理 — 手动加的也属于费用包含,不需要单独有"手动"分类,改。 - -预期:这条项目应该和其他自动推导项一样,主标题显示项目名称 `升级满洲里套娃酒店`,**不要有"手动"两字出现在用户可见区域**。 - ---- - -## 二、根因 - -文件: `src/views/product/edit/components/supplement/CostDescPanel.vue` - -### 罪魁第 159 行 - -```js -// confirmAdd 处理"添加项目"弹窗的确认按钮 -const confirmAdd = () => { - if (!addForm.value.name?.trim()) return - const name = addForm.value.name.trim() - const item = { feeType: '手动', name, sourceNodeName: '' } // ← 这里硬编码 "手动" - includedItems.value.push(item) - ... -} -``` - -`feeType: '手动'` 这条数据通过 `PUT /admin/product-v2/{id}/supplement` 落到 `product_fee_item.fee_type = '手动'`。 - -### C 端渲染逻辑放大问题 - -小程序 `packages/product/core/detail/detail.js:428` 渲染费用包含项的逻辑: - -```js -// 简化版 -const primary = feeType ? feeType : label // 有 feeType 时,把 feeType 作主标题 -const secondary = feeType ? label : '' // 项目名降级作副标题 -``` - -- 后端"自动推导"的 `feeType` 来源于资源类型:`景区 / 游玩项目 / 餐饮 / 交通` → 这些是合理的分类主标题。 -- 但**手动添加**的项被前端塞了 `feeType="手动"`,走的是同一套逻辑,于是"手动"两个字就赫然摆在主标题位置,看起来像个独立分类。 - - ---- - -## 三、修复方案(用户最终决策:**只改这一行,其他都不动**) - -### 唯一改动:把硬编码的 "手动" 改成 "其他" - -**文件**: `src/views/product/edit/components/supplement/CostDescPanel.vue` -**位置**: 第 159 行 `confirmIncludedAdd` 函数内 - -```diff -- const item = { feeType: '手动', name, sourceNodeName: '' } -+ const item = { feeType: '其他', name, sourceNodeName: '' } -``` - -效果:运营手动添加的费用项,C 端主标题显示"其他",和「景区/游玩项目/餐饮/交通」等并列,作为一个合理的"杂项"分类,语义清晰。admin 卡片左上角绿色 chip 显示"其他",也是正常态。 - -### 用户明确不要的改动(不要做) - -- ❌ 不要把 `feeType` 改成 `null` (用户原话:"手动改为其他 不需要改了") -- ❌ 不要给 admin 卡片 chip 加 `v-if` (因为新值"其他"是合法值,需要正常显示) -- ❌ 不要全局 grep 排查其他 `feeType:` 硬编码 (用户判断没必要) -- ❌ 不要动 C 端 `detail.js` -- ❌ 不要动后端任何代码 (不需要加 feeType 枚举校验) - -### 一行改动即可,无后续连锁修改 - ---- - -## 四、部署后清理 - -mmg 前端发版到**正式环境**后,正式数据库有 1 条历史脏数据需要清理: - -- **产品 ID**: `2056554654480248833` -- **脏记录**: `product_fee_item` 表中 `name = '升级满洲里套娃酒店' AND fee_type = '手动'` -- **清理方式 A (推荐)**: 运营在 admin 产品编辑页 → 补充信息 → 费用说明 → 费用包含,**找到"升级满洲里套娃酒店"那张卡片,点删除,然后重新点"添加项目"再加一次**。新版前端会存 `feeType='其他'`,C 端主标题就变成"其他",不再是"手动"。 -- **清理方式 B (兜底,wx 自行决定是否动正式 DB)**: - -```sql -UPDATE product_fee_item -SET fee_type = '其他' -WHERE name = '升级满洲里套娃酒店' AND fee_type = '手动' AND product_id = 2056554654480248833; -``` - ---- - -## 五、不需要后端配合 - -本次纯前端 BUG: - -- ✅ 无后端接口签名/字段/类型变更 -- ✅ 无 hl-product-service-v2 / hl-mp-service 代码改动 -- ✅ 无 Flyway V*.sql 数据库迁移 -- ✅ 无 Nacos 配置变更 -- ✅ 无 gateway 路由调整 - -mmg 直接在 hl-ui 改完 1 行(L159 `'手动'` → `'其他'`),本地 `npm run build` 后发版即可。 - ---- - -## 六、验证步骤 (mmg 自测) - -发版到测试环境后,按以下步骤验证: - -1. admin 测试环境登录,进入任意产品编辑页 → 补充信息 → 费用说明 → 费用包含 -2. 点"添加项目",输入名称 (例如"测试其他项 xxx"),保存 -3. 检查 Network 面板:请求 body 里这条新增项的 `feeType` 字段应为 `"其他"`,**不是 `"手动"`** -4. admin 页面回到查看模式,这张卡片左上角绿色 chip 应显示 **"其他"**(不是"手动",也不是空白) -5. 小程序对应产品的详情页「费用包含」区块,这条项**主标题应显示"其他"**(副标题是项目名) - -全部 OK 再发正式。 diff --git a/changelogs/2026-05/20_fix_admin_material_list_strict_self_category.md b/changelogs/2026-05/20_fix_admin_material_list_strict_self_category.md deleted file mode 100644 index 64f4ff5..0000000 --- a/changelogs/2026-05/20_fix_admin_material_list_strict_self_category.md +++ /dev/null @@ -1,72 +0,0 @@ -# GET /admin/material/list 分类查询语义变更：只查自身，不再含子分类/后代 - -> **仓库**: HL (后端 hl-resource-service) -> **关联 PR/Issue**: PR #2682, Closes #2677 -> **日期**: 2026-05-20 -> **影响范围**: admin 「素材库」左侧分类树点击 → 右侧列表查询 -> **接收方**: mmg (前端) -> **前端**: 无需改动（请求参数 `categoryCode` / `subCategoryId` 字段没变） - ---- - -## ⚠️ 关键变化 - -`GET /admin/material/list` 的 `categoryCode` / `subCategoryId` 语义改为「严格只查选中分类自身」，不再向下递归后代。**接口请求/响应字段完全不变**，但**同一个请求返回的素材数会变少**（原本含子的现在只看本节点）。 - -前端不需要改代码。需要注意的是：UI 上点击同一个分类，列表数字可能**变小**，这是符合本次需求的预期行为，不是 bug。 - ---- - -## 一、行为对比 - -| 请求 | 改前 | 改后 | -|------|------|------| -| `?categoryCode=hotel` | 返回 hotel 一级 + 所有子分类（共 114 条） | 只返回直挂 hotel 一级（`sub_category_id IS NULL`，99 条） | -| `?categoryCode=hotel&subCategoryId=2037033579896369153` | 返回该子分类 + **所有后代**（15 条，因为该叶子无后代故无差异） | 只返回该子分类自身（15 条） | -| `?categoryCode=scenic` | 返回 scenic 一级 + 所有子分类（221 条） | 只返回直挂 scenic（100 条） | -| 无任何分类参数（"全部素材"） | 全部 909 条 | **不变**，仍 909 条 | - -测试服 round-trip 实测以上 4 个 case 全部匹配 DB 严格只查自身的预期。 - ---- - -## 二、UI 侧需要注意 - -### 1）左侧分类树左侧的统计数字 vs 右侧列表 total 可能不一致 - -`GET /admin/material/categories` 接口**未改动**，左侧树各节点显示的统计数仍然是「该节点 + 所有子节点累计」（如 hotel 一级仍显示 114，scenic 一级仍显示 221）。 - -但点进列表后右侧 `total` 是「只查自身」的数（如 hotel 点开后右侧 99，scenic 99 → 100）。 - -这是有意为之，不一致是已知现象。用户原话： - -> 这个素材分类现在是选中把子分类的数据也查出来的，现在改为只能查看自己分类的数据。 - -如果产品/运营反馈"左侧数字和列表不一致"，可以解释：左侧数字是「分类总量参考」、右侧 total 是「严格本节点」。 - -### 2）点击有子的根分类（如 hotel / scenic），右侧可能显示得很少甚至 0 - -如果一个一级分类下所有素材都被运营整理到了二级子分类（没有直挂一级的），那点击一级根节点列表会接近空。用户需要手动展开二级子分类去看具体素材。这也是符合本次需求"只查自身"的字面语义。 - ---- - -## 三、单元测试覆盖 - -`MaterialListCategoryFilterTest`（新增）用 ArgumentCaptor 覆盖 3 个 case： - -1. 选根节点 → mapper 入参 `selectedSubIds=null, requireSubCategoryNull=true` -2. 选叶子子分类 → mapper 入参 `selectedSubIds=[X], requireSubCategoryNull=false` -3. 选有后代的中间子分类 → mapper 入参 `selectedSubIds=[X]`（不含后代），且 `verifyNoInteractions(categoryService)` 证明递归调用链已彻底断开 - -180 个 material 包测试全绿。 - ---- - -## 四、不需要前端配合 - -- ✅ 无接口字段变更（VO / DTO 不动） -- ✅ 无新增接口 -- ✅ 无网关路由变更 -- ✅ 无 Flyway V*.sql 数据库迁移 - -mmg 不需要发版。仅在产品/运营反馈"分类点开少了/为空"时，按本文档解释即可。 diff --git a/changelogs/2026-05/21_fix_dict_all_group_level_remark.md b/changelogs/2026-05/21_fix_dict_all_group_level_remark.md deleted file mode 100644 index 238b789..0000000 --- a/changelogs/2026-05/21_fix_dict_all_group_level_remark.md +++ /dev/null @@ -1,87 +0,0 @@ -# GET /dict/all 外层 dictType 组新增 remark 字段 — 透传 sys_dict_type.remark - -> **仓库**: HL (hl-user-service + hl-mp-service BFF) -> **关联 PR/Issue**: PR #2827 (user) + PR #2828 (mp BFF), Closes #2826 -> **日期**: 2026-05-21 -> **影响范围**: 小程序「字典加载」、管理端字典管理页(任何调 `/dict/all` 或 `/admin/dict/all` 拿字典分组的页面) -> **接收方**: mmg (小程序前端) / 管理端前端 -> **前端**: **无需改动**(只是新增可空字段,前端可选择展示) -> **测试服 round-trip**: ✅ 通过(157 groups 全部包含 `remark` key) - ---- - -## 一、修了什么 - -`GET /dict/all` (公开端,网关路由到 hl-mp-service BFF) 与 `GET /admin/dict/all` (管理端,直连 hl-user-service) 原本只返: - -```json -[ - { - "dictType": "product_category", - "dictName": "产品分类", - "dataList": [ ... ] - } -] -``` - -`sys_dict_type.remark` 这一列(字典类型的整体说明,例如「产品分类」字典本身可以填「面向不同人群的产品定位」)没有暴露给前端。 - -本次修复让外层 group 新增 `remark` 字段,值取自 `sys_dict_type.remark`。 - -## 二、返回结构对照 - -### 改前 - -```json -{ - "dictType": "admin_status", - "dictName": "管理员状态", - "dataList": [...] -} -``` - -### 改后 - -```json -{ - "dictType": "admin_status", - "dictName": "管理员状态", - "remark": "管理员账号状态字典(ACTIVE/INACTIVE/LOCKED/DELETED)", - "dataList": [...] -} -``` - -| 字段 | 类型 | 说明 | -|---|---|---| -| `remark` | String / null | 字典类型整体说明,可为 null(DB 该字段允许 NULL) | - -数据项内层 `remark` 已有,本次不动。 - -## 三、测试服实测 - -```bash -curl -sk https://api.test.1814.love:9443/dict/all | jq '.data[] | select(.dictType=="product_category") | keys' -``` - -返回: - -```json -["dictType", "dictName", "remark", "dataList"] -``` - -`product_category` 当前 type-level remark 为 null(DB 未填),但字段已暴露。后续可在管理后台字典管理页给每个 type 填上 remark,前端会自动拿到。 - -## 四、不需要前端配合 - -- ✅ 无字段变更,只新增可空字段 -- ✅ 无网关路由变更 -- ✅ 无 Flyway 数据库迁移 -- ✅ 无业务逻辑变更 - -如果前端有展示需求(例如字典管理页头部展示该字典是干什么的),可读取外层 `remark` 字段;不读也不影响现有逻辑。 - -## 五、单测覆盖 - -- `SysDictServiceTest.getAllDictForPublic_includesGroupLevelRemark` — 外层 remark 填充正确 -- `SysDictServiceTest.getAllDictForPublic_groupRemarkNullWhenTypeRemarkNull` — null 时不抛 NPE -- `MpDictControllerTest.mpDictGroupVO_deserializesRemark` — Jackson 反序列化契约,防 BFF 字段被改回错位 diff --git a/changelogs/2026-05/21_fix_mp_message_summary_field_misalign.md b/changelogs/2026-05/21_fix_mp_message_summary_field_misalign.md deleted file mode 100644 index d274f15..0000000 --- a/changelogs/2026-05/21_fix_mp_message_summary_field_misalign.md +++ /dev/null @@ -1,98 +0,0 @@ -# GET /mp/message/summary 字段错位修复 — 消息中心 4 个分类入口恢复正常显示 - -> **仓库**: HL (后端 hl-mp-service) -> **关联 PR/Issue**: PR #2817, Closes #2813 -> **日期**: 2026-05-21 -> **影响范围**: 小程序「消息」tab(消息中心首页 4 个分类入口) -> **接收方**: mmg (小程序前端) -> **前端**: **无需改动**(本来契约就是 `code/name/icon/description/unreadCount/latestTitle/latestTime`,只是后端 BFF 之前没返对) -> **测试服 round-trip**: ✅ 通过(已用真 mp 用户 token 在 `https://api.test.1814.love:9443/mp/message/summary` 实测,7 字段全部就位) - ---- - -## 一、修了什么 - -PR #2479 (`refactor(mp): BFF Map<String,Object> 透传清理`, 2026-05-18 合并) 把 `MpMessageController` 从 `Map<String,Object>` 改成强类型 VO,但 BFF 端 `MpMessageSummaryVO` / `MpMessageVO` 字段命名与 user 服务实际返回的 `CategorySummaryVO` / `UserMessageVO` **完全错位**,Feign 反序列化拿不到值,小程序消息 tab 出现: - -- 4 个分类入口全部显示默认喇叭图标(因 `icon=null` 走前端 fallback) -- 4 个分类入口标题为空(因 `name` 字段不存在) -- 只有 `latestTitle` 这个字段名巧合一致的内容能显示 -- 点击分类跳转 detail 时弹「缺少消息类型」(router 校验 `type` 必填,而 `code=null`) - -本次修复让 BFF VO 字段严格对齐 user 端,Feign 反序列化恢复正常。 - ---- - -## 二、字段对照(供前端核对) - -### `GET /mp/message/summary` 返回的每个分类对象 - -| 字段名 | 类型 | 改前(BUG) | 改后(本次修复) | -|---|---|---|---| -| `code` | String | `category` (错位 → null) | ✅ `code` (例 "ORDER") | -| `name` | String | 字段不存在 → null | ✅ `name` (例 "订单消息") | -| `icon` | String | 字段不存在 → null | ✅ `icon` (例 "order") | -| `description` | String | 字段不存在 → null | ✅ `description` (例 "订单状态变更通知") | -| `unreadCount` | int | `Integer` 包装类型 | ✅ `int`(无包装,默认 0) | -| `latestTitle` | String | OK | ✅ 无变化 | -| `latestTime` | Long | `String` 类型错 | ✅ `Long` 时间戳毫秒 | - -### `GET /mp/message/list` 返回的每条消息对象(本次顺手对齐,前端目前未调用) - -| 字段名 | 类型 | 改前 | 改后 | -|---|---|---|---| -| `id` | String | `Long` (JS Long 精度风险) | ✅ `String` | -| `title` | String | OK | 无变化 | -| `content` | String | OK | 无变化 | -| `link` | String | 字段不存在 | ✅ 新增(跳转链接) | -| `createTime` | Long | `createdAt: LocalDateTime` | ✅ `createTime` 时间戳毫秒 | -| `isRead` | Boolean | OK | 无变化 | -| `bizId` | String | `Long` (JS Long 精度风险) | ✅ `String` | -| `bizType` | String | OK | 无变化 | -| `categoryCode` | String | `category` 字段名错 | ✅ `categoryCode` | -| `eventCode` | String | 字段不存在 | ✅ 新增(事件编码) | - ---- - -## 三、测试服真测结果 - -```bash -curl -sk "https://api.test.1814.love:9443/mp/message/summary" -H "Authorization: Bearer <mp用户token>" -``` - -返回: - -```json -[ - {"code":"SYSTEM","name":"系统消息","icon":"system","description":"系统公告与通知","unreadCount":0,"latestTitle":null,"latestTime":null}, - {"code":"ORDER","name":"订单消息","icon":"order","description":"订单状态变更通知","unreadCount":0,"latestTitle":"定金支付成功","latestTime":1778298480000}, - {"code":"TRIP","name":"行程消息","icon":"trip","description":"出发提醒与行程动态","unreadCount":0,"latestTitle":"行程已开始","latestTime":1778295333000}, - {"code":"PROMO","name":"优惠促销","icon":"promo","description":"优惠活动与促销信息","unreadCount":0,"latestTitle":null,"latestTime":null} -] -``` - -4 个分类的 7 个字段全部就位,符合 `hl-mini/api/index.js:1118` 注释里写的契约。 - ---- - -## 四、单元测试覆盖 - -新增 3 个测试类(本次工单): - -- `MpMessageSummaryVOFieldsTest` — 反射验字段集合/类型(`latestTime=Long`/`unreadCount=int`) -- `MpMessageVOFieldsTest` — 反射验字段集合/类型(`id/bizId=String`/`createTime=Long`) -- `MpMessageVoDeserializationContractTest` — **Jackson ObjectMapper 模拟 Feign 真实路径**,user JSON → mp VO 反序列化,7 + 10 字段全部断言 + 字段错位回归保护 - -加上重写的 `MpMessageControllerTest`,本次目标 4 个测试类 **15/15 全绿**。后续如果 BFF VO 字段被人改回错位,会被这 3 个契约测试立刻拦下。 - ---- - -## 五、不需要前端配合 - -- ✅ 无接口字段变更(前端 `_renderFromStore` 期望的字段名一直是这 7 个,本次只是让后端真正返出来) -- ✅ 无新增接口 -- ✅ 无网关路由变更 -- ✅ 无 Flyway V*.sql 数据库迁移 -- ✅ 无业务逻辑变更 - -mmg 不需要发版。等测试服部署稳定后,小程序刷新消息 tab 就能看到 4 个分类入口正常显示(标题/图标/描述/未读数/最新预览/时间)。 diff --git a/changelogs/2026-05/21_refactor_material_remove_review_feature.md b/changelogs/2026-05/21_refactor_material_remove_review_feature.md deleted file mode 100644 index 075c96d..0000000 --- a/changelogs/2026-05/21_refactor_material_remove_review_feature.md +++ /dev/null @@ -1,160 +0,0 @@ -# refactor(material): 拆除素材审核遗留功能（reviewStatus 字段 + 字典 + DTO 全删） - -> **仓库**: HL (后端 hl-resource-service + hl-user-service) -> **关联 PR/Issue**: PR #2795, Closes #2789 -> **日期**: 2026-05-21 -> **影响范围**: 管理后台「素材库」批量审核/批量驳回功能整体废弃 -> **接收方**: mmg (前端) -> **前端**: **需要改动 — 拆按钮 + 删 API** - ---- - -## 🚨 关键变化 - -「素材审核」功能业务上已不需要，本次全部拆除： - -- 后端 `Material.reviewStatus` 字段删除 -- DB `material.review_status` 列 DROP -- DB 字典 `material_review_status` DELETE -- `MaterialReviewRequest` DTO 删除 - -**正式环境之前批量审核接口 `PUT /admin/material/review` 触发的「参数类型错误: materialId='review'（需要 Long 类型）」报错根因就是这两条**：前端调了 `/admin/material/review` 但后端从未实现该接口，Spring 把 `review` 当成 `{materialId}` 路径变量去解析 Long，报错。 - ---- - -## 一、API 影响 - -### 不再存在的接口（后端从未实现） - -``` -PUT /admin/material/review ← 不再支持（前端有死调用） -PUT /admin/material/reject ← 不再支持（前端有死调用） -``` - -### 字段移除 - -| 接口 | 字段 | 改前 | 改后 | -|------|------|------|------| -| `GET /admin/material/list` | `reviewStatus` | 不返回（VO 本就没此字段） | 不返回（一致） | -| `GET /admin/material/{id}` | `reviewStatus` | 不返回（VO 本就没此字段） | 不返回（一致） | - -> 实际 VO 层本来就没有 `reviewStatus` 字段，只是 Entity 层和 DB 列还在，本次一并清理。响应字段对前端无任何观测变化。 - ---- - -## 🚨 前端需要做的事 - -### 1. 删除批量审核/批量驳回 API - -文件：`hl-ui/src/api/material.js` 第 335-353 行 - -```js -// 整段删掉 -// ========== 素材审核 ========== - -/** - * 批量审核通过 - */ -export function reviewMaterials(materialIds) { - return http.put('/material/review', { materialIds }) -} - -/** - * 批量驳回素材(删除) - */ -export function rejectMaterials(materialIds) { - return http.put('/material/reject', { materialIds }) -} -``` - -### 2. 拆 UI 按钮 + 弹窗 - -文件：`hl-ui/src/views/material/index.vue` - -- 删除「批量审核」按钮、「批量驳回」按钮 -- 删除「批量审核确认」弹窗及相关逻辑 -- 列表/详情若有 `reviewStatus` 列或字段显示，一并删（实际 API 本就不返回） - -### 3. 自查 - -请 mmg 全前端 grep 一遍： - -```bash -grep -rE "reviewMaterials|rejectMaterials|material.*review|批量审核|审核通过|审核状态" hl-ui/src -``` - -如有残留请一并清理。 - ---- - -## 二、DB 改动（Flyway 已自动跑） - -- `hl-resource-service` `V20260521_001__drop_material_review_status.sql` — `ALTER TABLE material DROP COLUMN review_status`（MySQL 8.0 兼容写法，列不存在时跳过） -- `hl-user-service` `V20260521_006__drop_material_review_status_dict.sql` — `DELETE` `sys_dict_type` + `sys_dict_data` 中 `material_review_status` 全部行 - -> dev 上的 user-service Flyway 文件名是 `V20260521_002`，dev-v3 上为避免 out-of-order 改名为 `V20260521_006`。两个分支文件名不同但 SQL 内容完全一致。 - ---- - -## 三、兼容性 / 风险 - -- ✅ VO 层本就无 `reviewStatus` 字段，前端列表/详情响应字段零变化 -- ✅ Flyway 用 `information_schema` 防御，多环境部署安全（本地无此列也能跑过） -- ✅ DB 历史 `review_status` 值（如 PENDING/REJECTED）随列 DROP 丢失语义，业务已确认不需要 -- ⚠️ 前端 `PUT /admin/material/review` `/admin/material/reject` 调用 100% 报错（路径变量 Long 解析失败），mmg 改前端前用户使用「批量审核」按钮会持续报错 - ---- - -## 四、测试服验证记录 - -部署到测试服 (`https://web.test.1814.love:9443`) 后已 round-trip 验证（2026-05-21 14:01）： - -``` -✓ GET /admin/material/list?page=1&pageSize=1 - → 响应 item keys 中无 reviewStatus - -✓ GET /admin/dict/data/material_review_status - → code=200, data=[] (字典已清空) -``` - -Flyway 自动执行： -- hl-resource-service 启动时跑 `V20260521_001__drop_material_review_status.sql` → `material.review_status` 列已 DROP -- hl-user-service 启动时跑 `V20260521_006__drop_material_review_status_dict.sql` → 字典 `material_review_status` 已 DELETE - -## 五、正式部署记录（2026-05-21 14:49） - -main 已合并 (`66c462c87f34`)，通过 `dep.test.1814.love:9443/prod` API 部署 hl-resource-service + hl-user-service 到正式 K3s (`hl-prod` ns)。 - -⚠️ 部署过程踩坑（已根治）： - -1. **Flyway out-of-order 阻塞 hl-resource-service rollout 5 分钟** - - 根因：正式 `hl_resource_service.flyway_schema_history` 里有一条孤儿 marker `99999999.001 flyway pilot marker`（2026-05-15 引入 Flyway pilot 时遗留） - - 来源：`/opt/hl/build-repo/hl-resource-service/target/classes/db/migration/V99999999_001__flyway_pilot_marker.sql` 是 src 早已删除的孤儿文件，但 `deploy-prod.sh` 只跑 `mvn package` 不带 `mvn clean`，target/classes 增量保留把它打进了每一个 jar - - 修复：SQL 删 history marker + rm Node1 build-repo target 孤儿文件 + `kubectl rollout restart` - - 后续：建议在 `deploy-prod.sh` 加 `mvn clean` 或 `git clean -fxd $SERVICE` 防再次发生 - -2. **首次部署因 .m2 并发竞争失败**（之前测试服踩过，与本次无关），已串行化 - -### 正式 RDS 验证（直连 RDS 实测） - -```sql --- hl_resource_service -✓ SHOW COLUMNS FROM material LIKE 'review_status' → 0 rows (列已 DROP) -✓ flyway_schema_history top 1 = 20260521.001 drop material review status (success=1) - --- hl_user_service -✓ SELECT * FROM sys_dict_data WHERE dict_type='material_review_status' → 0 rows -✓ SELECT * FROM sys_dict_type WHERE dict_type='material_review_status' → 0 rows -✓ flyway_schema_history top 2 = 20260521.002 drop material review status dict / 20260521.001 init meal option dict (success=1) - --- material 表数据完好 5153 行 -``` - ---- - -## 五、联系人 - -后端：wx（呼籁旅行） -前端：mmg - -如有疑问可在 [#2789](https://git.1814.love:8443/wx/HL/issues/2789) 评论区留言。 diff --git a/changelogs/2026-05/21_refactor_product_v2_meal_option_dict.md b/changelogs/2026-05/21_refactor_product_v2_meal_option_dict.md deleted file mode 100644 index ee936b3..0000000 --- a/changelogs/2026-05/21_refactor_product_v2_meal_option_dict.md +++ /dev/null @@ -1,119 +0,0 @@ -# refactor(product-v2): 餐饮选项 meal_option 由硬编码改为系统字典 + 新增「含（正餐）」 - -**日期**：2026-05-21 -**PR**：#2783（已合 dev → 已合 dev-v3 → 已部署测试服并验证） -**工单**：#2778 -**影响端**：管理后台前端（hl-ui） - ---- - -## 背景 - -原「餐饮安排」下拉框 4 个选项（含酒店 / 含营地 / 含特色餐 / 自理）在前端 `MealConfig.vue` 和后端 `ProductItineraryAggregateFacade` 都是**硬编码**。每次加一个选项都要前后端同时改代码、走 PR、上线。 - -本次改造： -- 后端 switch 硬编码 → 改为读 `meal_option` 字典 -- 字典数据库里新加一条 `REGULAR` = 「含（正餐）」 -- 以后再加选项只在字典管理后台点一下即可，**前后端代码无需任何改动** - ---- - -## 字典数据（meal_option） - -测试服已落库，可通过 `GET /admin/dict/data/meal_option` 拉到： - -| sortOrder | dictValue | dictLabel | 说明 | -|-----------|-----------|-----------|------| -| 1 | `HOTEL` | 含（酒店） | 历史值 | -| 2 | `CAMP` | 含（营地） | 历史值 | -| 3 | `SPECIAL` | 含（特色餐） | 历史值 | -| 4 | `REGULAR` | **含（正餐）** | **本次新增** | -| 5 | `SELF` | 自理 | 历史值（默认值） | - ---- - -## 🚨 前端需要做的事 - -### 1. 删除硬编码 - -文件：`hl-ui/src/views/product/edit/components/itinerary/MealConfig.vue` - -把第 22-27 行的硬编码数组**删掉**： - -```js -// 删掉这段 -const mealOptions = [ - { label: '含（酒店）', value: 'HOTEL' }, - { label: '含（营地）', value: 'CAMP' }, - { label: '含（特色餐）', value: 'SPECIAL' }, - { label: '自理', value: 'SELF' }, -] -``` - -### 2. 改成调字典接口 - -调用：`GET /admin/dict/data/meal_option`（已存在的字典 API） - -**Header**：需要 admin token - -**响应结构**： - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { "dictValue": "HOTEL", "dictLabel": "含（酒店）", "sortOrder": 1, "status": "ACTIVE" }, - { "dictValue": "CAMP", "dictLabel": "含（营地）", "sortOrder": 2, "status": "ACTIVE" }, - { "dictValue": "SPECIAL", "dictLabel": "含（特色餐）", "sortOrder": 3, "status": "ACTIVE" }, - { "dictValue": "REGULAR", "dictLabel": "含（正餐）", "sortOrder": 4, "status": "ACTIVE" }, - { "dictValue": "SELF", "dictLabel": "自理", "sortOrder": 5, "status": "ACTIVE" } - ] -} -``` - -### 3. 下拉绑定动态数据 - -`n-popselect` 的 `:options` 改为从接口返回的数组映射（注意现有字典 store 可能已经封装好，可以复用）： - -```js -// 推荐：直接复用全局 dictStore（如果已有） -const mealOptions = computed(() => - dictStore.getDictData('meal_option').map(d => ({ - label: d.dictLabel, - value: d.dictValue - })) -) -``` - -如果暂时没全局字典 store，组件级别 `onMounted` 拉一次即可（字典本身后端有 5 分钟 Redis 缓存，不会打到 DB）。 - -### 4. 校验逻辑无变化 - -`isSelf(value)` 仍然按 `value === 'SELF' || !value` 判断 — `SELF` 是业务语义的「自理」，前端这层判断不动。 - ---- - -## 兼容性 - -- ✅ 历史数据（HOTEL/CAMP/SPECIAL/SELF）**全兼容**，已上线的产品数据无需迁移 -- ✅ 字典服务挂掉时后端会 fallback 到 dictValue 字面值（订单详情不会显示空白） -- ✅ 字典本身有 Redis 5 分钟缓存，QPS 无压力 - ---- - -## 测试服验证记录 - -- 测试服 https://web.test.1814.love:9443 已部署 commit `b28cef1c7`（dev-v3） -- 字典查询接口返回 5 条数据 ✓ -- 产品详情接口对 5 种 meal_option（HOTEL/CAMP/SPECIAL/REGULAR/SELF）全部返回正确 dictLabel ✓ -- 无 token 调用返 `code: 401` ✓ - ---- - -## 联系人 - -后端：wx（呼籁旅行） -前端：mmg - -如有疑问或字典接口路径需要确认，可在 [#2778](https://git.1814.love:8443/wx/HL/issues/2778) 评论区留言。 diff --git a/changelogs/2026-05/21_refactor_team_role_picker_use_staff_type_dict.md b/changelogs/2026-05/21_refactor_team_role_picker_use_staff_type_dict.md deleted file mode 100644 index 22fede1..0000000 --- a/changelogs/2026-05/21_refactor_team_role_picker_use_staff_type_dict.md +++ /dev/null @@ -1,160 +0,0 @@ -# refactor(product): 「添加团队成员」角色弹窗改为 staff_type 字典动态获取 - -**日期**：2026-05-21 -**PR**：无（后端零改动，字典与字典查询接口均已就绪） -**工单**：[#2790](https://git.1814.love:8443/wx/HL/issues/2790)（同步关闭 hl-api-changelog [#7](https://git.1814.love:8443/wx/hl-api-changelog/issues/7)） -**影响端**：管理后台前端（hl-ui） - ---- - -## 背景 - -产品编辑页 → 「添加团队成员」弹窗（`hl-ui/src/views/product/edit/components/modals/StaffPickerModal.vue:23-28`）的「选择角色」区域当前是 4 个 **写死** 的标签： - -```js -const roleOptions = [ - { label: '主领队', value: 'LEADER', limit: 1 }, - { label: '副领队', value: 'DEPUTY_LEADER', limit: 3 }, // 后端字典无此值 - { label: '摄影师', value: 'PHOTOGRAPHER', limit: 2 }, - { label: '司机', value: 'DRIVER', limit: 5 }, // 业务上不属于服务人员 -] -``` - -**问题**： -1. 后端 `staff_type` 字典里**根本没有 DEPUTY_LEADER**，前端保存后字典翻译不出中文，是孤儿值。 -2. 业务确认：**服务人员不包括司机**，DRIVER 不应出现在团队成员候选里。 -3. 后端 `staff_type` 字典已扩展到 7 项（导游 / 导游助理 / 摄影师 / 领队 / 其他 / 研学老师 / 生活老师），前端写死 4 项导致「导游 / 导游助理 / 研学老师 / 生活老师」都选不到——hl-api-changelog#7 已反馈过同一问题。 - ---- - -## 业务决策（wx 已确认） - -- **角色列表来源**：直接复用 **服务人员管理页「人员类型」那列对应的 `staff_type` 字典**（不要再造新字典） -- **主/副领队合并为 LEADER**：同一团里可加多个 LEADER，不在角色层区分主副 -- **司机不出现在候选**：司机另由车辆/驾驶员模块管理 -- **后续可扩展**：业务再加 staff_type 字典值时前端零改动自动出现 - ---- - -## 字典数据（staff_type，测试服已落库） - -通过 `GET /admin/dict/data/staff_type` 拉取： - -| sortOrder | dictValue | dictLabel | 说明 | -|-----------|-----------|-----------|------| -| 1 | `GUIDE` | 导游 | | -| 2 | `GUIDE_ASSISTANT` | 导游助理 | | -| 3 | `PHOTOGRAPHER` | 摄影师 | | -| 4 | `LEADER` | 领队 | | -| 5 | `OTHER` | 其他 | | -| — | (业务追加) | 研学老师 / 生活老师 / ... | 字典动态扩展，前端零改动 | - -> 实际项数以接口返回为准（后续业务可能继续追加），不要在前端写死个数或枚举值。 - ---- - -## 🚨 前端需要做的事 - -### 1. 删除硬编码 - -文件：`hl-ui/src/views/product/edit/components/modals/StaffPickerModal.vue` - -把第 23-28 行的 `roleOptions` 硬编码删掉。 - -### 2. 改成调字典接口 - -调用：`GET /admin/dict/data/staff_type`（已存在的通用字典 API） - -**Header**：需要 admin token - -**响应结构**： - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { "dictValue": "GUIDE", "dictLabel": "导游", "sortOrder": 1, "status": "ACTIVE" }, - { "dictValue": "GUIDE_ASSISTANT", "dictLabel": "导游助理", "sortOrder": 2, "status": "ACTIVE" }, - { "dictValue": "PHOTOGRAPHER", "dictLabel": "摄影师", "sortOrder": 3, "status": "ACTIVE" }, - { "dictValue": "LEADER", "dictLabel": "领队", "sortOrder": 4, "status": "ACTIVE" }, - { "dictValue": "OTHER", "dictLabel": "其他", "sortOrder": 5, "status": "ACTIVE" } - // 业务追加的值按字典实际数量返回 - ] -} -``` - -### 3. 下拉/标签组绑定动态数据 - -```js -// 推荐：直接复用全局 dictStore（如已有） -import { useDictStore } from '@/stores/dict' -const dictStore = useDictStore() -const roleOptions = computed(() => - dictStore.getDictData('staff_type').map(d => ({ - label: d.dictLabel, - value: d.dictValue, - })) -) -``` - -如果暂时没全局字典 store，组件级 `onMounted` 拉一次即可（字典后端有 5 分钟 Redis 缓存）。 - -### 4. 联动 `getStaffPage` - -弹窗下半段调 `getStaffPage({ staffType: selectedRole.value, ... })` 时，`staffType` 参数直接传字典 `dictValue`（无需做映射，前后端值一致）。 - -### 5. `limit`（人数上限） - -业务暂无强制需求，前端可： -- A. 不限制（推荐，简化逻辑） -- B. 前端约定一份固定 map（不影响后端） -- C. 后续如需在字典 `remark` 放 `{"limit":N}` JSON，后端可补，前端解析 - ---- - -## 关联清理（mmg 请一并自查） - -`hl-api-changelog#7` 还提到："请扫描代码中是否有其他地方也硬编码了这套角色枚举（订单成员配置、薪酬结算、小程序"服务团队"展示等）"。 - -请 mmg 一并核查以下位置是否硬编码同一份枚举，如有请同步改造为字典化： -- 订单详情/列表的成员展示 -- 小程序「服务团队」展示 -- 团队成员编辑/批量编辑组件 -- 各页面 staff_type 标签颜色 map - ---- - -## 历史数据 - -后端有零代码改动，但需关注产品快照里是否已有 `DEPUTY_LEADER` / `DRIVER` 孤儿值： - -```sql --- 测试服执行核查（hl_product_service_v2 数据库） -SELECT DISTINCT staff_role, COUNT(*) -FROM group_batch_staff -GROUP BY staff_role; -``` - -- 如有 `DEPUTY_LEADER`：评估迁移为 `LEADER` -- 如有 `DRIVER`：评估删除或归 `OTHER` -- 如查询结果都是 `LEADER` / `PHOTOGRAPHER` / `GUIDE` 等正常值：无需迁移 - -后端将由 wx 在 [#2790](https://git.1814.love:8443/wx/HL/issues/2790) 关单 comment 中给出实际数据扫描结果。 - ---- - -## 兼容性 - -- ✅ 后端零改动，无回归风险 -- ✅ 字典服务挂掉时前端可 fallback 到 staff_type 字典已有的固定 5 项 -- ✅ 字典本身有 Redis 5 分钟缓存，QPS 无压力 - ---- - -## 联系人 - -后端：wx（呼籁旅行） -前端：mmg - -如有疑问或字典接口路径需要确认，可在 [#2790](https://git.1814.love:8443/wx/HL/issues/2790) 评论区留言。 diff --git a/changelogs/2026-05/22_feat_admin_order_list_detail_overhaul.md b/changelogs/2026-05/22_feat_admin_order_list_detail_overhaul.md deleted file mode 100644 index 9c1c9fc..0000000 --- a/changelogs/2026-05/22_feat_admin_order_list_detail_overhaul.md +++ /dev/null @@ -1,230 +0,0 @@ -# feat(order-v2): /admin/order/list + /admin/order/{id} 综合改造（搜索 / 排序 / 详情行程 / 状态 tab） - -> **仓库**: HL (后端 hl-order-service-v2) -> **关联 PR/Issue**: PR #2903 / #2906 / #2909 / #2914 / #2916（Closes #2899 #2905 #2908 #2912 #2915） -> **日期**: 2026-05-22 -> **影响范围**: 管理后台「订单管理」列表 + 详情 -> **接收方**: mmg (前端) -> **前端**: **需要改动 — 搜索框 placeholder / 排序下拉新增订金 / tab 切换迁到 displayStatus / 详情页渲染行程概览** - ---- - -## 🚨 关键变化总览 - -| 维度 | 改动 | 前端动作 | -|---|---|---| -| 搜索 keyword | 现支持 **完整 11 位手机号精确匹配**（加密列等值），姓名/订单号/产品名仍 LIKE | placeholder 加"完整手机号" | -| 列表排序 | 新增 `depositAmount`（订金金额）+ `updateTime`（最近更新）排序 | 排序下拉加"订金金额"+"最近更新"选项 | -| 列表 tab 筛选 | 新增 `displayStatus` 参数，**原型 5 tab 必须用这个**（status 是内部细粒度，对不上 tab） | tab 切换的 status 参数改名为 `displayStatus` | -| 订单详情 | 新增 `itinerary` 字段（行程按天结构化，含景点 + 酒店） | 详情页"行程概览"段渲染 | - ---- - -## 一、`GET /admin/order/list` 搜索框（keyword） - -### 改前 - -`keyword` 对 4 字段做 LIKE 模糊匹配：`orderNo` / `contactName` / `productName`（联系电话 LIKE 是一次预备改造，对加密列实际无效）。 - -### 改后 - -| 输入 | 行为 | -|---|---| -| 完整 11 位手机号（如 `17600545225`） | **后端加密后等值匹配 contact_phone 密文列** → 精确命中所有持此号订单 | -| 部分手机号（如 `176`、`5225`） | 不识别为手机号，不查 contact_phone（部分号匹不到加密订单是天然限制） | -| 姓名（`米明光`） | 仍 LIKE 模糊匹配 contact_name | -| 订单号（`HL20260509`） | 仍 LIKE 模糊匹配 order_no | -| 产品名（`冻干粉`） | 仍 LIKE 模糊匹配 product_name | -| 不传 / 空 | 不过滤（行为不变） | - -### 前端建议 - -搜索框 placeholder 改为类似： - -``` -姓名 / 完整手机号 / 订单号 / 产品名 -``` - -不要再写"手机号"模糊（部分手机号匹不到，会误导用户）。 - ---- - -## 二、`GET /admin/order/list` 排序（sortField） - -### 改后枚举 - -| sortField | sortOrder | 含义 | -|---|---|---| -| `createTime` | desc（默认） / asc | 创建时间 | -| `departureDate` | desc / asc | 出发日期 | -| `totalPrice` | desc / asc | 订单金额 | -| `depositAmount` ⭐ | desc / asc | **订金金额（新增）** | -| `updateTime` ⭐ | desc / asc | **最近更新（新增，PR #2916）** — 业务场景：定制师/客服优先看"最近有动作"的订单 | -| 不传 / 未知值 | — | 兜底按 createTime DESC | - -### 前端建议 - -排序下拉选项追加： -- "订金金额（高→低）/（低→高）"：财务对账场景（找订金大但未付尾款的订单优先催） -- "最近更新（新→旧）"：定制师工作流场景（看哪些订单今天有动静）—— 注意这是 `update_time` 不是 `create_time`，能把"老订单今天有退款 / 改单"的情况顶到前面 - ---- - -## 三、`GET /admin/order/list` 订单 tab 筛选 ⚠️ 重要 - -### 改前 - -只有 `status` 参数（匹配内部 `OrderStatus` 枚举 11 状态）。**原型"待出行" tab 传 `status=PENDING_DEPARTURE` 命中 0 单**（数据库实际分散在 DEPOSIT_PAID / CONFIRMED 等状态）。 - -### 改后 - -新增 `displayStatus` 参数，与 `status` 并存（AND 联合）。**原型 5 tab 必须用 `displayStatus`**： - -| 原型 Tab | 前端传 `displayStatus` 值 | 后端命中范围 | -|---|---|---| -| 全部 | （不传） | 所有未删除订单 | -| 待支付 | `PENDING_PAY` | 内部 status = PENDING_PAY | -| **待出行** | `PENDING_DEPARTURE` | **折叠** DEPOSIT_PAID / PAID / CONFIRMED / PENDING_BALANCE / PENDING_DEPARTURE 5 个内部状态 | -| 待评价 | `PENDING_REVIEW` | （状态机决定） | -| 已完成 | `COMPLETED` | 内部 status = COMPLETED（且已评价） | -| 售后中 | `AFTER_SALE` | **折叠** REFUNDING / 部分 REFUNDED | -| 已取消 | `CANCELLED` | **折叠** CANCELLED / 部分 REFUNDED | - -### 前端动作 - -按 tab 切换的参数从 `status` 改为 `displayStatus`。两个值的枚举不一样，**千万不要混用** —— 把内部 `status=PENDING_DEPARTURE` 当成 tab 传过去会拿到 0 单。 - -### 测试服实测对照 - -| 请求 | 命中 | -|---|---| -| `?displayStatus=PENDING_DEPARTURE` | **8 单** ⭐ | -| `?displayStatus=CANCELLED` | 26 单 | -| `?displayStatus=AFTER_SALE` | 2 单 | -| `?status=PENDING_DEPARTURE`（错用法） | 0 单 ❌ | - ---- - -## 四、`GET /admin/order/{orderId}` 详情新增 `itinerary` 字段 - -### 字段结构 - -`OrderDetailVO` 新增： - -```typescript -itinerary: OrderItineraryDayVO[] // 全部天数，不截断 - -OrderItineraryDayVO { - dayNumber: number // 1, 2, 3... - dayTitle: string // "京都·古都漫步" - route: string // "大阪 → 京都" - attractions: ItineraryAttractionVO[] // 当天 SCENIC + ACTIVITY 节点 - hotels: ItineraryHotelVO[] // 当天酒店（已按订单档位 tierSeq 过滤） -} - -ItineraryAttractionVO { - resourceId: string // Long 序列化为字符串 - name: string // "清水寺" - nodeType: 'SCENIC' | 'ACTIVITY' - startTime: string | null // "09:30" - durationMinutes: number | null - description: string | null - coverImageUrl: string | null -} - -ItineraryHotelVO { - hotelId: string - hotelName: string // "京都八坂町京町家" - roomTypeName: string // "豪华双床房" -} -``` - -### 注意点 - -- **数据来源是订单下单时固化的产品快照**，不会随产品变化 -- 老订单（快照 key 是 `itineraryDays`）也兼容解析 -- 快照损坏时 `itinerary` 返回空数组（不会让整个详情接口挂） -- `hotels` 已经按订单 `tierSeq` 过滤 —— 不要担心一天显示 3 档候选酒店 - -### 真实示例（订单 `HL20260509114457-6539`） - -```json -{ - "itinerary": [ - { - "dayNumber": 1, - "dayTitle": "京都古都漫步", - "route": "海拉尔区 → 额尔古纳市", - "attractions": [ - { - "name": "中俄边境公路（卡线）", - "nodeType": "SCENIC", - "description": "沿额尔古纳河蜿蜒前行约200公里...", - "coverImageUrl": "https://hlgl-test.oss.../62943d9b....jpg" - }, - { - "name": "驯鹿拉车体验", - "nodeType": "ACTIVITY", - "description": "..." - } - // ... 一天可能 6-7 个节点 - ], - "hotels": [ - { "hotelName": "呼伦贝尔香格里拉大酒店", "roomTypeName": "普通标间" } - ] - } - // ... 多天行程 - ] -} -``` - -### 前端建议 - -详情页"行程概览"段： -- 按 `dayNumber` 排序，渲染 D1 / D2 / D3... -- 每天先 `route` + `dayTitle`，下面 `attractions` 列表 + `hotels` 列表（末日可能 `hotels` 为空，正常） -- `attractions` 可按 `nodeType` 分组（"景点 SCENIC" / "活动 ACTIVITY"），也可不分组直接列 -- `coverImageUrl` 是 OSS 完整 URL 可直接 `<img src>` - ---- - -## 五、向后兼容 - -| 老前端不传新参数 / 不读新字段 | 行为 | -|---|---| -| 仅用 `status`（不用 `displayStatus`） | 完全不变（仍按内部状态 eq） | -| 不读 `itinerary` | 完全不变（多了字段不影响其他） | -| 不传 `sortField=depositAmount` | 完全不变 | -| keyword 输部分手机号 | 不影响其他字段 LIKE 命中（只是不再误命中加密列的明文残留） | - ---- - -## 六、错误码 / 异常 - -无新增错误码。所有改动都是请求参数扩展或响应字段新增。 - ---- - -## 七、测试建议（前端联调时验证） - -| 验证项 | 操作 | 期望 | -|---|---|---| -| 完整手机号搜 | 搜 `17600545225` | 精确命中（如有该号订单） | -| 部分号搜 | 搜 `176` | 不命中加密订单（只命中订单号/姓名/产品名含 "176" 的） | -| 订金排序 | sortField=depositAmount&sortOrder=desc | 单调递减 | -| 最近更新排序 | sortField=updateTime&sortOrder=desc | 与 createTime DESC 结果**不同**（老订单今天更新的会排到前面） | -| 待出行 tab | displayStatus=PENDING_DEPARTURE | 应命中（测试服 8 单） | -| 详情行程 | 打开任一已下单订单详情 | itinerary 非空数组 | -| 不传新参数 | 老接口调用方式 | 行为完全不变 | - ---- - -## 八、关联 - -- PR #2903（itinerary）→ commit `c8f34411a` -- PR #2906（搜索+排序）→ commit `689d47013` -- PR #2909（手机号精确匹配，修 #2906 假阳性）→ commit `fbf803b1b` -- PR #2914（displayStatus 修待出行 tab）→ commit `8be30a562c` -- PR #2916（排序补 updateTime）→ commit `328691813c` -- Issue #2899 / #2905 / #2908 / #2912 / #2915 已全部 closed -- 负责人：yst（后端） diff --git a/changelogs/2026-05/22_feat_admin_sms_login.md b/changelogs/2026-05/22_feat_admin_sms_login.md deleted file mode 100644 index 316945e..0000000 --- a/changelogs/2026-05/22_feat_admin_sms_login.md +++ /dev/null @@ -1,197 +0,0 @@ -# feat(user): 管理端手机号验证码登录(短信路径免 2FA) - -> **仓库**: HL (后端 hl-user-service + hl-gateway) -> **关联 PR/Issue**: PR #2904, Closes #2889 -> **日期**: 2026-05-22 -> **影响范围**: 管理后台登录页加「短信验证码登录」入口 -> **接收方**: mmg (前端) -> **前端**: **需要改动 — 登录页加 tab + 手机号/验证码输入 + 倒计时按钮** - ---- - -## 🚨 关键变化 - -新增 2 个接口,管理员可以用「手机号 + 短信验证码」登录后台,**短信路径本身不再走企业微信 2FA**(账号密码登录路径完全不动,仍保留 2FA)。 - -依赖前置工单 #2886 的 `admin_user.mobile` 字段(已上线)。 - ---- - -## 一、API 影响 - -### 新增 `POST /admin/auth/sms/send-code` 发送验证码 - -请求体: - -```json -{ - "mobile": "13800138000" -} -``` - -| 字段 | 类型 | 必填 | 校验 | -|------|------|-----|------| -| mobile | String | ✅ | `^1[3-9]\d{9}$` 11 位 | - -响应: - -| 场景 | code | message | -|------|------|---------| -| 注册 mobile 真发 | 200 | 成功 | -| **未注册 mobile**(防枚举) | **200** | **成功**(静默不真发,但日上限消费) | -| 60s 内重发 | 200105 | 发送过于频繁,请 60 秒后重试 | -| 当日 >= 10 次 | 200106 | 今日发送次数已达上限 | -| mobile 格式错 / 漏 | 400 | 手机号不能为空 / 手机号格式不正确 | - -⚠️ **防枚举关键**: 未注册 mobile **也返 200** 跟"已注册"路径**外部不可区分**(末尾 300-800ms 随机 jitter 抹平时延)。前端不能依据 send-code 响应判断 mobile 是否注册。 - -### 新增 `POST /admin/auth/sms/login` 验证码登录 - -请求体: - -```json -{ - "mobile": "13800138000", - "code": "123456" -} -``` - -| 字段 | 类型 | 必填 | 校验 | -|------|------|-----|------| -| mobile | String | ✅ | `^1[3-9]\d{9}$` | -| code | String | ✅ | `^\d{6}$` 6 位数字 | - -响应: - -| 场景 | code | 说明 | -|------|------|------| -| 登录成功 | 200 | 返回 data = AdminLoginResponse(含 token, refreshToken, adminId, username, role, roleName, avatar, roles, **`requireTwoFa: false`**) | -| 验证码错 | 200102 | 验证码错误(fail+1) | -| 验证码过期/未发送 | 200103 | 验证码已过期,请重新获取(**fail 不增**) | -| 失败 >= 5 锁定 | 200104 | 短信登录失败次数过多,请 15 分钟后重试 | -| 对码 + mobile 不绑 admin | 200102 | 验证码错误(**防枚举,假装码错不报"用户不存在"**) | - -⚠️ **`requireTwoFa: false` 是工单核心放行点**: 短信验证码本身是「拥有手机」的二次因子,与企微 2FA 等价,不再叠加。**账号密码登录的 requireTwoFa=true 行为完全不变**。 - ---- - -## 🚨 前端需要做的事 - -### 1. 登录页加「短信验证码登录」tab - -文件: `hl-ui/src/views/login/...` (登录页组件) - -跟现有「账号密码」「企业微信扫码」并列,加一个新 tab: - -``` -[ 账号密码 ] [ 企业微信扫码 ] [ 短信验证码 ] -``` - -### 2. 「短信验证码」表单 - -- 输入框 1: 手机号(11 位格式预校验 `^1[3-9]\d{9}$`) -- 按钮: 「获取验证码」点击 → POST `/admin/auth/sms/send-code` - - 点击后 60s 倒计时(按钮文案 `60s 后重新获取`),复用现有小程序短信发送倒计时组件 - - 响应 200 → 提示「验证码已发送」(**注册/未注册都提示已发送,不能透露 mobile 是否绑**) - - 响应 200105 → 提示「发送过于频繁,请稍后重试」 - - 响应 200106 → 提示「今日发送次数已达上限」 -- 输入框 2: 验证码(6 位数字) -- 按钮:「登录」点击 → POST `/admin/auth/sms/login` - - 响应 200 + data → 走现有登录成功流程(存 token / 跳转,**不再触发 2FA 弹窗**) - - 响应 200102 → 提示「验证码错误」 - - 响应 200103 → 提示「验证码已过期,请重新获取」并清空验证码输入 - - 响应 200104 → 提示「失败次数过多,请 15 分钟后重试」并锁登录按钮 15min - -### 3. 入口指引(可选) - -在「账号密码」tab 下方加小字提示: - -``` -忘记密码? 试试 [短信验证码登录] -``` - -### 4. 自查 - -```bash -grep -rE "admin.*sms|短信验证码登录" hl-ui/src -``` - ---- - -## 二、错误码总览(本工单新增 5 个) - -| code | 含义 | -|------|------| -| 200102 | 验证码错误 / 对码但 mobile 不绑 admin | -| 200103 | 验证码已过期 / 未发送 | -| 200104 | 短信登录失败次数过多(15 分钟锁定) | -| 200105 | 发送过于频繁(60s 间隔) | -| 200106 | 今日发送次数已达上限(10/d) | - ---- - -## 三、安全设计 - -### 4 重防枚举攻击 - -1. 间隔锁 60s + 日上限 10/d **先于** admin 查询消费(未注册 mobile 也扣额度,防刷量) -2. 未注册 mobile **静默返 200** 不真发不存 code -3. 末尾 **300-800ms 随机 jitter** 防时间侧信道(注册/未注册路径外部时延无差异) -4. login 阶段 mobile 不绑 admin **即使码对也返 INVALID** 跟真错码路径不可区分 - -### Redis namespace 隔离 - -跟小程序端 `sms:*` 完全隔离,本接口用: - -- `admin:sms:code:{mobile}` TTL 300s -- `admin:sms:interval:{mobile}` TTL 60s -- `admin:sms:limit:{mobile}` TTL 到当日午夜 -- `admin:sms:fail:{mobile}` TTL 900s (15min) - -### 失败计数策略 - -- 用 Redis `admin:sms:fail:{mobile}` 独立计数(**不动 `admin_user.failed_login_count`**,后者密码场景专用) -- 验证码错累加 → 累计 5 次锁 15 分钟 -- 验证码过期/未发送**不累加**(防攻击者用别人 mobile 试码锁住真用户) - ---- - -## 四、DB 改动 - -`hl-user-service`: - -- `V20260523_002__login_log_method_to_varchar.sql`: `login_log.login_method` 从 ENUM(4 值) 改 `VARCHAR(32)`,新增 `SMS` 值,后续登录方式扩展无需改 DDL - ---- - -## 五、测试服验证记录 - -部署到测试服 (`https://web.test.1814.love:9443` 网关 + `hl-user-service` 双实例) 后已 round-trip 验证 (2026-05-22 16:55): - -| # | 场景 | 预期 | 实测 | -|---|------|------|------| -| T1 | send-code 注册 mobile | 200 + Redis 存 code | ✅ code='505310' | -| T2 | 60s 重发 | 200105 | ✅ | -| T3 | send-code 未注册 mobile | 200 静默 Redis 无 code | ✅ 防枚举 | -| T4 | login 对码 | 200 + token + role + **requireTwoFa=False** | ✅ | -| T7 | 对码 + mobile 不绑 admin | 200102 INVALID | ✅ 防枚举 | -| T8 | 5 次错码累加锁定 | fail 1→5, 第 6 次 200104 | ✅ | - -测试服 user 双实例 + gateway 双实例都已部署 dev 最新,可联调。 - ---- - -## 六、不在本期范围 - -- 「忘记密码走短信重置」(另起工单) -- 完全废弃企微 2FA (账密登录链路保留 2FA) -- 注册 mobile 检查接口(防枚举设计不暴露) - ---- - -## 七、联系人 - -后端: wx(呼籁旅行) -前端: mmg - -如有疑问可在 [#2889](https://git.1814.love:8443/wx/HL/issues/2889) 评论区留言。 diff --git a/changelogs/2026-05/22_feat_admin_user_add_mobile.md b/changelogs/2026-05/22_feat_admin_user_add_mobile.md deleted file mode 100644 index d6ad946..0000000 --- a/changelogs/2026-05/22_feat_admin_user_add_mobile.md +++ /dev/null @@ -1,164 +0,0 @@ -# feat(user): admin_user 加 mobile 字段（必填+全局唯一） - -> **仓库**: HL (后端 hl-user-service) -> **关联 PR/Issue**: PR #2897 (→ dev), PR #2898 (dev → dev-v3), Closes #2886 -> **日期**: 2026-05-22 -> **影响范围**: 管理后台「管理员管理」新增/编辑/列表 -> **接收方**: mmg (前端) -> **前端**: **需要改动 — 表单加手机号字段 + 列表展示** - ---- - -## 🚨 关键变化 - -- 后端 `admin_user` 新增 `mobile VARCHAR(20) NULL` + `uk_admin_user_mobile` 唯一索引 -- 新增管理员**必填手机号**(11 位中国大陆),编辑时允许补录但格式校验 -- 后续场景: 定制师用手机号绑定个人微信、客人下单按手机号关联 - ---- - -## 一、API 影响 - -### 新增字段(出现在所有 admin 接口的 request / response) - -| 字段 | 类型 | 必填(创建) | 必填(编辑) | 校验 | -|------|------|-----------|-----------|------| -| `mobile` | String | ✅ `@NotBlank` | ❌(三态语义见下) | `^1[3-9]\d{9}$` 11 位正则 | - -### `POST /admin/user` 创建管理员 - -请求体加 `mobile`(必填): - -```json -{ - "username": "zhangsan", - "mobile": "13800138000", - "roleIds": [2] -} -``` - -响应: - -| 场景 | code | message | -|------|------|---------| -| 成功 | 200 | 成功 | -| 漏 mobile | 400 | `手机号不能为空` | -| 格式错(非 11 位 / 不是 1[3-9] 开头) | 400 | `手机号格式不正确` | -| 重复 mobile | **200310** | `手机号已被其他管理员使用,mobile={传入值}` | - -### `PUT /admin/user/{adminId}` 编辑管理员 - -请求体加 `mobile`(选填,但有三态规则): - -| 当前 admin mobile | 传入 mobile | 行为 | -|------------------|-----------|------| -| 有值 | null / 空串 | 保持原值不变 | -| 有值 | 非空 + 同值 | 不查重,正常更新其他字段 | -| 有值 | 非空 + 不同值 + 已被其他 admin 占 | **200310** `手机号已被其他管理员使用` | -| 有值 | 非空 + 不同值 + 未被占 | 正常更新 mobile | -| **空** (历史 admin) | null / 空串 | **200311** `历史管理员编辑时必须补填手机号,adminId=xxx` | -| **空** (历史 admin) | 非空 | 正常补录(走查重) | - -### `GET /admin/user` 列表 - -响应每个 admin 记录新增 `mobile` 字段: - -```json -{ - "adminId": "...", - "username": "cz", - "mobile": "13800138000", - "isDefaultConsultant": false, - ... -} -``` - -### 错误码 - -| code | 含义 | -|------|------| -| 200310 | 手机号已被其他管理员使用 | -| 200311 | 历史管理员(mobile 为空)编辑时必须补填手机号 | - ---- - -## 🚨 前端需要做的事 - -### 1. 新增管理员表单 - -文件: `hl-ui/src/views/system/admin/...` (新增/编辑弹窗) - -- 加「手机号」必填输入框 -- 前端做 11 位格式预校验(`/^1[3-9]\d{9}$/`) -- 提交后端响应 code=200310 → 提示「该手机号已被其他管理员使用,请更换」 - -### 2. 编辑管理员表单 - -- 加「手机号」输入框 -- **历史 admin (mobile 为空) 编辑保存时,前端要把 mobile 字段标红强制要求填**(后端会返 200311) -- 已有 mobile 的 admin,编辑时允许不传 mobile(保持原值) - -### 3. 列表展示 - -- 表头加「手机号」列,展示 `mobile` 字段(null 时显示「未补录」或 `-`) -- 可选: 列表筛选条件加「手机号」关键字搜索 - -### 4. 自查 - -```bash -grep -rE "admin.*mobile|管理员.*手机" hl-ui/src -``` - ---- - -## 二、DB 改动 - -`hl-user-service` Flyway: - -- `V20260523_001__add_mobile_to_admin_user.sql` - - `ALTER TABLE admin_user ADD COLUMN mobile VARCHAR(20) NULL COMMENT '手机号(11位中国大陆,允许 NULL 便于历史过渡)'` - - `CREATE UNIQUE INDEX uk_admin_user_mobile ON admin_user (mobile)` -- 允许 NULL: MySQL InnoDB 唯一索引允许多 NULL,历史 admin 平滑过渡 -- 企微 mobile 接口权限已收回,**不做自动回填**,历史 admin 由运营手动逐个补录 - ---- - -## 三、唯一性策略 - -- DB 层: `uk_admin_user_mobile` 兜底 -- Service 层: `ensureMobileNotDuplicated` 先查重报友好错码,排除 `STATUS_DELETED` admin(离职软删后释放手机号给新员工复用) - ---- - -## 四、测试服验证记录 - -部署到测试服 (`https://web.test.1814.love:9443`) 后 round-trip 验证 (2026-05-22 15:50): - -| # | 场景 | 预期 | 实测 | -|---|------|------|------| -| T1 | POST /admin/user 带 mobile | 200 + 字段回显 | ✅ adminId 返回,mobile=13911119001 | -| T2 | POST /admin/user 漏 mobile | 400 @NotBlank | ✅ `手机号不能为空` | -| T3 | POST /admin/user 重复 mobile | 200310 | ✅ `手机号已被其他管理员使用,mobile=13911119001` | -| T4 | POST /admin/user 格式错 mobile=123 | 400 @Pattern | ✅ `手机号格式不正确` | -| T5 | PUT 编辑改成重复 mobile | 200310 | ✅ | -| T6 | PUT 编辑改成新 mobile | 200 + 回显 | ✅ | -| T7 | PUT 编辑同值 mobile | 200 不查重 | ✅ | - -测试服 dev-v3 已部署生效,可直接联调。 - ---- - -## 五、不在本次范围 - -- ❌ 「忘记密码走短信重置」(已规划 #2889 单独工单) -- ❌ 管理端手机号验证码登录(已规划 #2889 单独工单,免企微 2FA) -- ❌ 客人自主下单兜底绑定定制师(dev-v3 #2542 已实现,使用 `is_default_consultant` 字段) - ---- - -## 六、联系人 - -后端: wx(呼籁旅行) -前端: mmg - -如有疑问可在 [#2886](https://git.1814.love:8443/wx/HL/issues/2886) 评论区留言。 diff --git a/changelogs/2026-05/22_feat_customizer_share_and_remaining_attempts.md b/changelogs/2026-05/22_feat_customizer_share_and_remaining_attempts.md deleted file mode 100644 index 08b8e6b..0000000 --- a/changelogs/2026-05/22_feat_customizer_share_and_remaining_attempts.md +++ /dev/null @@ -1,213 +0,0 @@ -# feat(user/order): 定制师小程序分享 + 登录锁定剩余次数 + AdminLoginResponse 加 mobile - -> **仓库**: HL (后端 hl-user-service + hl-mp-service + hl-order-service-v2 + hl-common-*) -> **关联 PR/Issue**: PR #2913, Closes #2907 -> **日期**: 2026-05-22 -> **影响范围**: 管理后台登录页错误提示、admin 自身信息接口、小程序定制师身份识别、客人下单链路 -> **接收方**: mmg (前端) -> **前端**: **需要 3 处改动 — 登录失败响应解析 + admin info 显示 mobile + 小程序分享按钮** - ---- - -## 🚨 三大变化 - -### 1. AdminLoginResponse 加 `mobile` 字段 - -`/admin/auth/info` / `/admin/auth/login` / `/admin/auth/sms/login` / `/admin/auth/wechat/verify-2fa` / `/admin/auth/refresh` 等所有 admin 鉴权出口共 **9 处 builder 全部填充** admin.mobile。 - -前端可以直接 `data.mobile` 拿到当前登录管理员的手机号。 - -### 2. 5 次错误锁定 + 剩余次数 / 锁定分钟数 - -引入 `LoginFailException` (BusinessException 子类) + `GlobalExceptionHandler.handleLoginFail` 拦截器 + `Result.error(code, msg, data)` 三参重载,**统一在 `Result.data` 携带结构化字段**: - -```json -{ - "code": 200203, - "message": "密码错误,剩余 3 次尝试", - "data": { - "remainingAttempts": 3, - "lockedMinutes": null - } -} -``` - -**前端直接读 `data.remainingAttempts` / `data.lockedMinutes`,不用解析 message 中文**。 - -### 3. 定制师小程序分享 + 客人下单 openid 反查 - -完整链路: - -``` -1. 定制师后台补 mobile (#2886 已上线) -2. 定制师 SMS 登录小程序,user 表存 phone + openid -3. 小程序前端调 GET /mp/customizer/me 识别身份 → 显示「分享给客人」按钮 -4. 客人通过分享链接下单,提交 sharerOpenid -5. 后端 sharerOpenid → user.phone → admin_user.mobile → adminId → order.customizer_id -``` - ---- - -## 一、错误响应 data 字段规范 - -### 密码登录失败 `POST /admin/auth/login` - -| 场景 | code | message | data | -|---|---|---|---| -| 错 1-4 次 | 200203 | `密码错误,剩余 N 次尝试` | `{remainingAttempts: N}` | -| **错 5 次直接锁定** | **200212** | `账号已锁定,请 30 分钟后重试` | `{lockedMinutes: 30}` | -| 已锁定中重新登录 | 200212 | 同上 | `{lockedMinutes: <剩余分钟>}` | - -⚠️ 改密码路径(`PUT /admin/auth/password`)旧密码错使用 **200213** `ADMIN_CHANGE_PASSWORD_OLD_WRONG`(避免 200203 模板冲突) - -### 短信验证码登录失败 `POST /admin/auth/sms/login` - -| 场景 | code | message | data | -|---|---|---|---| -| 码错 1-4 次 | 200102 | `验证码错误,剩余 N 次尝试` | `{remainingAttempts: N}` | -| **码错 5 次直接锁定** | **200104** | `短信登录失败次数过多,请 15 分钟后重试` | `{lockedMinutes: 15}` | -| 验证码过期 / 未发送 | 200103 | `验证码已过期,请重新获取` | `{}` (**不增 fail count**,防攻击者锁住真用户) | - ---- - -## 🚨 前端需要做的事 - -### 1. 登录失败响应解析(账密 + 短信) - -文件:`hl-ui/src/views/login/...`、`hl-ui/src/api/admin.js` - -```js -// 拦截器或登录页 onError -if (resp.code === 200203 || resp.code === 200102) { - // 密码 / 验证码错 - const remaining = resp.data?.remainingAttempts - showError(`${resp.message}` + (remaining != null ? `(还剩 ${remaining} 次)` : '')) -} -if (resp.code === 200212 || resp.code === 200104) { - // 账号 / 短信登录已锁定 - const minutes = resp.data?.lockedMinutes - showError(`${resp.message}` + (minutes != null ? `(剩余 ${minutes} 分钟)` : '')) - lockLoginButton(minutes * 60 * 1000) -} -``` - -### 2. /admin/auth/info 显示当前管理员手机号 - -文件:`hl-ui/src/views/profile/...` 或顶部用户信息组件 - -```js -const me = await getAdminInfo() // GET /admin/auth/info -this.mobile = me.data.mobile // 直接读 (null 时显示「未补录」) -``` - -### 3. 小程序定制师身份识别 + 分享按钮(mp 前端) - -文件:`mp-cli/src/pages/...`、`mp-cli/src/api/customizer.js` - -```js -// 登录后调一次 -const me = await getCustomizerMe() // GET /mp/customizer/me -if (me.data.isCustomizer) { - this.showShareButton = true - this.customizerInfo = me.data // adminId, customizerName, customizerAvatar -} -``` - -**分享链接 URL 必须带 `?sharerOpenid={当前用户 openid}`**(从当前小程序登录态拿)。 - -客人点开分享链接下单时,把 `sharerOpenid` 透传到下单请求 body (字段名沿用现有 `MpCreateOrderRequest.sharerOpenid`,已具备)。 - -### 4. 自查 - -```bash -grep -rE "remainingAttempts|lockedMinutes|/mp/customizer/me|sharerOpenid|admin.*mobile" hl-ui/src mp-cli/src -``` - ---- - -## 二、新增接口清单 - -### `GET /mp/customizer/me` — 当前用户的定制师身份 - -JWT 鉴权,无 token → 401。 - -响应: - -```json -{ - "code": 200, - "data": { - "isCustomizer": true, - "adminId": 9999999998, - "customizerName": "张三", - "customizerAvatar": "https://..." - } -} -``` - -`isCustomizer: false` 时其他字段为 null。 - -### 内部 Feign(后端服务间用,前端不调) - -- `GET /internal/user/admin/by-phone?phone=` 返 admin 信息或 null -- `GET /internal/mp/user/by-openid?openid=` 返 user.phone 或 null - ---- - -## 三、客人下单链路改造(对前端透明) - -`POST /mp/order/create` 流程改造,**前端无 API 字段变化**: - -``` -优先级: -1. request.customizerId 显式传 (现有 ?adminId=xxx URL 透传路径) -2. customizerId 为空 + sharerOpenid 非空 → 后端 openid → phone → adminId 反查 -3. 都没命中 → 沿用现有 assignRandomCustomizer 兜底 -``` - -反查失败降级不抛异常,客人下单不被后台问题阻塞。 - ---- - -## 四、新错误码(本期新增 4 个) - -| code | 含义 | data | -|---|---|---| -| 200212 | 账号已锁定(密码登录) | `{lockedMinutes: 30}` | -| 200213 | 旧密码错(改密码场景,与登录密码错码分离) | `{}` | -| 200102 message 更新 | 验证码错误,剩余 N 次尝试 | `{remainingAttempts: N}` | -| 200203 message 更新 | 密码错误,剩余 N 次尝试 | `{remainingAttempts: N}` | - ---- - -## 五、测试服验证记录 - -部署到测试服 (`api.test.1814.love:9443`) 后 round-trip 验证 (2026-05-22 18:07): - -| # | 场景 | 实测 | -|---|------|------| -| T1 | admin 登录 + /admin/auth/info 返回 mobile | ✅ mobile=13800138000 | -| T2 | 密码错 1-3 次 remainingAttempts 累加 | ✅ 4/3/2 | -| T3 | 密码错 5 次直接锁定 | ✅ 200212 + lockedMinutes=30 | -| T4 | SMS 错码 remainingAttempts 累加 | ✅ 4/3/2 | -| T5 | /mp/customizer/me 端点路由 | ✅ (401 鉴权要求, 路由正常) | - -⚠️ test_admin_lock 测试用户因没绑企微 login 时 token=null(`requireWechatBind=true`),改用内置 admin(已绑企微)测 info 端点通过。 - ---- - -## 六、不在本期范围 - -- ❌ dev-v3 二期同步 (另起工单) -- ❌ 客人维度长期绑定定制师 (另起工单) -- ❌ admin_user 表 schema 改动 (字段都已具备) -- ❌ 跨 appId openid 隔离 (当前单小程序) - ---- - -## 七、联系人 - -后端: wx(呼籁旅行) -前端: mmg - -如有疑问可在 [#2907](https://git.1814.love:8443/wx/HL/issues/2907) 评论区留言。 diff --git a/changelogs/2026-05/22_feat_sms_login_customizer_only.md b/changelogs/2026-05/22_feat_sms_login_customizer_only.md deleted file mode 100644 index 6958690..0000000 --- a/changelogs/2026-05/22_feat_sms_login_customizer_only.md +++ /dev/null @@ -1,104 +0,0 @@ -# feat(user): SMS 登录限定制师 + active role 自动切 CUSTOMIZER - -> **仓库**: HL (后端 hl-user-service) -> **关联 PR/Issue**: PR #2920, Closes #2918 -> **日期**: 2026-05-22 -> **影响范围**: 管理端 `POST /admin/auth/sms/login` SMS 验证码登录入口 -> **接收方**: mmg (前端) -> **前端**: **登录页前端无 API 改动**, 但 SMS 登录成功后 `data.role` 一定是 CUSTOMIZER (即使该 admin 还有其他角色) - ---- - -## 🚨 关键变化 - -SMS 验证码登录入口 (`POST /admin/auth/sms/login`) **现在只允许有 `CUSTOMIZER` 角色的 admin 登录**, 且登录成功后强制以**定制师视角**颁发 token (即使 admin 还有 ADMIN/OPERATOR 等其他角色)。 - -业务原因: SMS 登录场景**仅定制师小程序分享**需要 (#2907), 其他角色不应该用 SMS 绕过 2FA 登入后台。 - ---- - -## 一、API 影响 - -### `POST /admin/auth/sms/login` 行为变化 - -| 场景 | 之前 | **现在** | -|---|---|---| -| 仅 CUSTOMIZER 角色 admin 用对码登录 | 颁发 token, `role` = `admin.currentRoleId` 对应的 roleKey | 颁发 token, **`role` 强制 = `CUSTOMIZER`** | -| 多角色 admin (如 CUSTOMIZER+ADMIN) 用对码登录 | 颁发 token, `role` = `admin.currentRoleId` 对应的 roleKey | 颁发 token, **`role` 强制 = `CUSTOMIZER`** (无视 currentRoleId) | -| **无 CUSTOMIZER 角色 admin** 用对码登录 | 颁发 token, `role` = 当前 active role | **返 200102 INVALID `验证码错误,剩余 N 次尝试`** + fail+1 (**防枚举**) | -| mobile 不绑 admin 用对码登录 | 200102 INVALID (现有防枚举路径) | 200102 INVALID (无变化) | - -### 防枚举设计 - -"无 CUSTOMIZER 角色 admin" 路径返回的 code/message 跟 "mobile 不绑 admin" 路径**完全一致** (200102 INVALID + remainingAttempts),攻击者无法区分这两种情况, 也无法用 SMS 入口枚举哪些 mobile 是非定制师 admin。 - -fail count 也会累加, 错 5 次仍触发 `ADMIN_SMS_CODE_VERIFY_LOCKED` 15 分钟锁定 (复用 #2889 锁定机制)。 - -### active role 强制 CUSTOMIZER 后 - -- 颁发的 access token 内嵌的 `role` 字段 = `CUSTOMIZER` -- 后续基于 token 的 `@PreAuthorize("hasRole('CUSTOMIZER')")` 等权限校验都按定制师视角 -- **不污染 `admin.currentRoleId` 持久化**: SMS 是临时切角色, 不影响下次密码登录时的默认角色 - ---- - -## 🚨 前端需要做的事 - -### 1. 登录后角色显示 - -SMS 登录成功后 `data.role` 一定是 `CUSTOMIZER`, 顶部用户信息组件 / 角色 badge 应该按定制师展示。 - -不需要前端额外区分 SMS 登录 vs 账密登录: 后端已经把 role 强制设为 CUSTOMIZER, 前端按响应字段渲染即可。 - -### 2. 多角色切换 - -如果未来前端有"切换角色"功能 (`PUT /admin/auth/role`), SMS 登录拿到的 CUSTOMIZER token, 切到其他角色行为等同于密码登录路径 (后端按现有逻辑处理)。 - -### 3. 错码无新增 - -`200102` 错码已经存在, 前端无需新增映射。**`200107` 是后端审计码不会返前端**, 前端忽略。 - -### 4. 自查 - -```bash -grep -rE "/admin/auth/sms/login|role.*CUSTOMIZER" hl-ui/src -``` - -确认登录后 role 字段处理逻辑能正确显示 CUSTOMIZER。 - ---- - -## 二、新错码 (后端审计用, 不返前端) - -| code | 含义 | -|---|---| -| 200107 | `ADMIN_SMS_LOGIN_NOT_CUSTOMIZER` 短信验证码登录仅限定制师 (仅服务端 log.warn 审计, 防枚举不返前端) | - ---- - -## 三、测试服验证记录 - -部署到测试服 `api.test.1814.love:9443` 后真测 (2026-05-22 19:05): - -| # | 场景 | 实测 | -|---|------|------| -| T1 | 仅 CUSTOMIZER admin 登录 | ✅ `role=CUSTOMIZER` + `roleName=定制师` + token + `requireTwoFa=False` | -| T2 | 仅 ADMIN admin (无 CUSTOMIZER) 登录 | ✅ 200102 INVALID + `remainingAttempts=4` (防枚举) | -| T3 | 多角色 admin (ADMIN+CUSTOMIZER, currentRoleId=ADMIN) | ✅ 强制返 `role=CUSTOMIZER`, DB `current_role_id=2` 保持不污染 | - ---- - -## 四、不在本期范围 - -- 账号密码登录路径 `/admin/auth/login` 行为完全不动 (仍按 `admin.currentRoleId`) -- 让非定制师能用 SMS 登录 (明确仅定制师) -- 持久化改 admin.currentRoleId (SMS 是临时切角色) - ---- - -## 五、联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [#2918](https://git.1814.love:8443/wx/HL/issues/2918) 评论区留言。 diff --git a/changelogs/2026-05/22_fix_customizer_role_check_bug.md b/changelogs/2026-05/22_fix_customizer_role_check_bug.md deleted file mode 100644 index 5999453..0000000 --- a/changelogs/2026-05/22_fix_customizer_role_check_bug.md +++ /dev/null @@ -1,108 +0,0 @@ -# fix: /mp/customizer/me 错把非定制师 admin 当定制师 + 网关白名单 + sharerOpenid 空串 (P0) - -> **仓库**: HL (后端 hl-user-service + hl-mp-service + hl-gateway + hl-order-service-v2) -> **关联 PR/Issue**: PR #2923, Closes #2922 -> **日期**: 2026-05-22 -> **影响范围**: `/mp/customizer/me` 接口 + 客人下单 sharerOpenid 反查 + 网关白名单 -> **接收方**: mmg (前端) -> **前端**: **可能需要调整** — 之前依赖 `/mp/customizer/me` 给非定制师 admin 显示分享按钮的行为现在不再生效(本就是 bug),前端逻辑无需改 - ---- - -## 🚨 关键修复 - -### 1. P0: 非定制师 admin 被错判成定制师 - -`GET /mp/customizer/me` 之前的实现 (`#2907` 引入) 仅过滤 `admin_user.mobile + status=ACTIVE`,**不校验 CUSTOMIZER 角色**。导致: - -- 运营/财务/客服等**任意活跃 admin** 用本人手机号 SMS 登录 C 端小程序,前端会看到「分享」按钮 -- 转发后客人下单时被 `CustomizerValidator` 角色校验拒绝 -- **订单悄悄给随机定制师**,前端无任何感知 -- 生产风险: 分润纠纷 / 「为啥我分享了订单没给我」客诉 - -**修复**:`AdminUserService.getCustomizerByMobileForFeign` 加 CUSTOMIZER 角色过滤,非定制师 admin 直接返 null。 - -**联动收益**: `OrderCreateService.resolveSharedCustomizerId` 反查链路也自动受益,sharerOpenid 反查到的 admin 必然是定制师身份。 - -### 2. P1-2: `/mp/customizer/me` 未登录直接 401 卡 UI - -`JwtAuthFilter.OPTIONAL_AUTH_URLS` 之前只含 `/mp/product/*` `/mp/explore/*`,**`/mp/customizer/me` 走 MANDATORY** 未登录直接 401,跟 `MpCustomizerController.userId == null` 兜底分支设计冲突。 - -**修复**: 加 `/mp/customizer/me` 到 OPTIONAL_AUTH_URLS,未登录返 `isCustomizer: false`。 - -### 3. P1-4: sharerOpenid 空串导致下单 400 - -`MpCreateOrderRequest.sharerOpenid` + `MpOrderSaveReqVO.sharerOpenid` `@Pattern("^[a-zA-Z0-9_-]+$")` 不接受空串。前端从 `onLaunch.options.sharerOpenid` 拿值,**误传 `""` 整个下单 400**。 - -**修复**: `@Pattern` 改 `^$|^[a-zA-Z0-9_-]+$` 接受空串。 - ---- - -## 一、API 行为变化 - -### `GET /mp/customizer/me` - -| 调用方 / 场景 | 之前 | **现在** | -|---|---|---| -| 未登录 | 401 Missing Authorization | **200 + `{isCustomizer: false, adminId: null, customizerName: null, customizerAvatar: null}`** | -| 已登录但 `user.phone` 为空 | 同左 | 同左 (`isCustomizer: false`) | -| 已登录, `user.phone` 在 admin_user 找到对应 ACTIVE admin **但不是 CUSTOMIZER 角色** | **错误返 `isCustomizer: true` + 该 admin 信息** (P0 bug) | **`isCustomizer: false`** (修复后) | -| 已登录, `user.phone` 对应有 CUSTOMIZER 角色的 admin | `isCustomizer: true` + admin 信息 | 同左 | - -### `POST /mp/order/create` - -| 场景 | 之前 | 现在 | -|---|---|---| -| `sharerOpenid` 字段传 `""` 空串 | 400 Bad Request `@Pattern 不匹配` | **200 OK** (走兜底 `assignRandomCustomizer`) | -| `sharerOpenid` 传定制师 openid | 反查 user.phone → admin 任意活跃 admin (P0 bug) | **反查仅 CUSTOMIZER 角色 admin**,非定制师 sharerOpenid 走兜底 | - ---- - -## 🚨 前端需要做的事 - -### 1. 不再依赖 P0 bug - -之前如果前端依赖"非定制师 admin 也能看到分享按钮"的行为 (这本身是 bug),现在该行为修正。前端按 `data.isCustomizer` 字段渲染即可,**逻辑无需改**。 - -### 2. 可选: 未登录场景预渲染 - -由于 `/mp/customizer/me` 现在支持未登录调用,**分享落地页 (客人从分享链接打开小程序首页) 可以在未登录态调一次** `/mp/customizer/me`,根据返回的 `isCustomizer: false` 跳过分享按钮渲染。这是设计原意。 - -### 3. sharerOpenid 字段值标准化(建议) - -前端尽量保证 `sharerOpenid` 字段为 `string | null` 而不是空串。空串虽然现在不再卡 400,但语义不规范。 - -### 4. 自查 - -```bash -grep -rE "isCustomizer|sharerOpenid|/mp/customizer/me" hl-ui/src mp-cli/src -``` - ---- - -## 二、测试服验证记录 - -部署 user + mp + gateway 三服务到测试服 (2026-05-22 22:45) 后真测: - -| # | 场景 | 实测 | -|---|------|------| -| T1 | CUSTOMIZER 角色 admin SMS 登录 → /mp/customizer/me | ✅ `isCustomizer: true, adminId, customizerName` | -| T2 | 非 CUSTOMIZER admin (运营/客服) SMS 登录 → /mp/customizer/me | ✅ `isCustomizer: false` (P0-1 修复后正确拦截) | -| T3 | 未登录直接调 /mp/customizer/me | ✅ 200 + `isCustomizer: false` (P1-2 网关 OPTIONAL 加白生效) | - ---- - -## 三、不在本期范围 (留尾巴另起工单) - -- P0-2 `AdminUserService` 注入 `WechatUserMapper`(类头部已备案,历史包袱) -- P1-3 `selectAnyByPhone` `LIMIT 1` 无 ORDER BY(业务唯一性约束,概率极低) -- P1-5 反查 Feign 重复调用合并优化(P99 未观察) - ---- - -## 四、联系人 - -后端: wx(呼籁旅行) -前端: mmg - -如有疑问可在 [#2922](https://git.1814.love:8443/wx/HL/issues/2922) 评论区留言。 diff --git a/changelogs/2026-05/23_2930_admin代用户发起退款接口-新增接口-管理后台.md b/changelogs/2026-05/23_2930_admin代用户发起退款接口-新增接口-管理后台.md deleted file mode 100644 index 17447c5..0000000 --- a/changelogs/2026-05/23_2930_admin代用户发起退款接口-新增接口-管理后台.md +++ /dev/null @@ -1,366 +0,0 @@ -# [新增接口·管理后台] admin H5 客服代用户发起退款 (#2930) - -> **PR**: #2932 | **服务**: hl-order-service-v2 | **更新时间**: 2026-05-23 10:30 - -## 1. 接口背景 - -管理后台 H5 客服操作台需要支持定制师/客服代用户发起退款申请。现有小程序端退款接口由用户自助发起，不适用客服代操作场景。 - -本接口允许客服在 H5 操作台手动填写退款金额并代用户提交，后端校验金额不超过订单订金金额，申请人留痕为 ADMIN 类型，创建后仍走主管审批流程。 - -## 2. 变更清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 代用户发起退款申请 | POST | /admin/order/refund/apply | 新增 | 客服 H5 代用户提交退款，金额客服手填，不超订金 | - -## 3. 接口详情 - -### 3.1 代用户发起退款申请 - -- **使用场景**：客服在 H5 操作台查看订单后，代用户发起退款申请 -- **认证**：需要管理后台 JWT（Bearer Token），adminId 由后端从 Token 中提取 -- **幂等性**：是，Header 携带 `Idempotent-Key`（UUID），5 秒内重复提交视为同一请求 -- **限流**：无 - -调用前置步骤：先调 `GET /admin/order/refund/reason/list` 获取退款原因字典，拿到 reasonValue（字典 key）和 reasonText（字典显示文本）后再调本接口。 - -## 4. 接口入参 - -### 4.1 路径参数 / Query 参数 - -无。 - -### 4.2 请求体字段 - -| 字段 | 类型 | 必填 | 说明 | 校验规则 | -|------|------|------|------|----------| -| orderId | Long | 是 | 订单 ID | 不能为空 | -| amount | BigDecimal | 是 | 退款金额 | 最小 0.01，且不能超过订单订金金额 | -| reasonValue | String | 是 | 退款原因字典值 | 从 /admin/order/refund/reason/list 获取；最长 100 字符 | -| reasonText | String | 是 | 退款原因文本 | 字典对应的显示文本；最长 500 字符 | -| reasonDetail | String | 否 | 补充说明 | 最长 2000 字符 | - -注意：refundType 无需前端传入，后端固定设置为 DEPOSIT（订金退款）。 - -## 5. 出参（响应） - -### 5.1 响应结构 - -`Result<RefundApplicationVO>` - -### 5.2 响应字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| applicationId | Long | 退款申请 ID | -| orderId | Long | 订单 ID | -| orderNo | String | 订单号 | -| productName | String | 产品名称 | -| refundType | String | 退款类型，本接口固定返回 DEPOSIT | -| refundTypeLabel | String | 退款类型标签，固定返回 订金退款 | -| reasonText | String | 退款原因文本 | -| reasonDetail | String | 补充说明（可为 null） | -| paidAmount | BigDecimal | 订单已付金额 | -| calculatedAmount | BigDecimal | 本次退款金额（即客服填写的 amount） | -| actualAmount | BigDecimal | 实际退款金额（审批后确认，初始为 null） | -| status | String | 退款申请状态，创建后固定返回 PENDING | -| statusLabel | String | 退款状态标签，创建后固定返回 待审核 | -| applicantType | String | 申请人类型，固定返回 ADMIN | -| applicantId | Long | 申请人管理员 ID | -| applicantName | String | 申请人姓名 | -| createTime | String (ISO 8601) | 申请创建时间 | -| updateTime | String (ISO 8601) | 最后更新时间 | -| reviewAdminId | Long | 审批人 ID（创建时为 null，审批后填充） | -| reviewAdminName | String | 审批人姓名（创建时为 null） | -| reviewRemark | String | 审批备注（创建时为 null） | -| reviewedAt | String (ISO 8601) | 审批时间（创建时为 null） | -| approvalNo | String | 审批单号（创建时为 null） | -| departureDate | String (yyyy-MM-dd) | 出发日期 | -| daysBeforeDept | Integer | 距出发天数 | -| refundRatio | Integer | 退款比例（百分比，本接口为 null，不调退款政策） | -| policyId | Long | 退款政策 ID（本接口为 null） | -| policyName | String | 退款政策名称（本接口为 null） | -| appealStatus | Integer | 申诉状态（创建时为 null） | -| appealStatusLabel | String | 申诉状态标签（创建时为 null） | -| appealReason | String | 申诉原因（创建时为 null） | -| appealAmount | BigDecimal | 申诉退款金额（创建时为 null） | -| appealedAt | String (ISO 8601) | 申诉时间（创建时为 null） | -| refundedAt | String (ISO 8601) | 退款完成时间（创建时为 null） | - -本接口创建的申请：policyId / policyName / refundRatio 均为 null（客服手填金额，不走退款政策计算）。 - -## 6. 枚举 / 数据字典 - -### 6.1 refundType（退款类型，出参字段） - -**所属字段**：refundType | **类型**：String | 本接口固定为 DEPOSIT - -| 值 | 中文 | 说明 | -|----|------|------| -| FULL | 全额退款 | 全额退还已付金额 | -| PARTIAL | 部分退款 | 部分退款 | -| DEPOSIT | 订金退款 | 仅退还订金部分，本接口固定此类型 | -| BALANCE | 尾款退款 | 仅退还尾款部分 | - -### 6.2 status（退款申请状态，出参字段） - -**所属字段**：status | **类型**：String | 创建后固定为 PENDING - -| 值 | 中文 | 说明 | -|----|------|------| -| PENDING | 待审核 | 申请已提交，等待主管审批 | -| APPROVED | 已通过 | 主管审批通过，进入退款流程 | -| REJECTED | 已拒绝 | 主管审批拒绝 | -| APPEALING | 申诉中 | 用户对拒绝结果申诉 | -| APPEAL_APPROVED | 申诉通过 | 申诉被通过 | -| APPEAL_REJECTED | 申诉拒绝 | 申诉被拒绝 | -| REFUNDING | 退款中 | 正在处理退款 | -| REFUNDED | 已退款 | 退款已完成 | -| CANCELLED | 已取消 | 申请已撤回取消 | - -活跃状态（同订单已有此类状态时拒绝重复提交）：PENDING / APPROVED / REFUNDING / APPEALING / APPEAL_APPROVED - -### 6.3 applicantType（申请人类型，出参字段） - -**所属字段**：applicantType | **类型**：String | 本接口固定为 ADMIN - -| 值 | 中文 | 说明 | -|----|------|------| -| USER | 用户 | 小程序用户自助发起（mp 接口） | -| ADMIN | 管理员 | 客服/定制师代发起（本接口） | - -### 6.4 reasonValue（退款原因字典值，入参字段） - -**所属字段**：reasonValue | **类型**：String | **必填**：是 - -字典值通过 `GET /admin/order/refund/reason/list` 接口获取，下面为示例（以实际字典接口返回为准）： - -| 值（示例） | 中文 | -|-----------|------| -| schedule_conflict | 行程冲突/时间变动 | -| personal_reason | 个人原因 | -| product_issue | 产品问题 | -| service_complaint | 服务投诉 | - -实际可用值以 `GET /admin/order/refund/reason/list` 返回为准。 - -## 7. 错误码 - -| code | 含义 | 触发场景 | -|------|------|----------| -| 200 | 成功 | 退款申请创建成功 | -| 401 | 未授权 | 未携带或 Token 无效/过期 | -| 404 | 订单不存在 | orderId 对应的订单不存在 | -| 530007 | 退款金额超过订金金额 | amount 大于订单 depositAmount，message 含具体金额：退款金额不能超过订金金额: amount={x}, deposit={y} | -| 530004 | 重复退款申请 | 同一订单已存在 ACTIVE 状态的退款申请 | - -## 8. 示例 - -### 8.1 典型成功 - -场景说明：客服代用户发起订金退款，退 500 元，选择行程冲突原因。 - -请求： - -``` -POST /admin/order/refund/apply -Authorization: Bearer <admin-jwt> -Idempotent-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890 -Content-Type: application/json -``` - -```json -{ - "orderId": 1234567890123, - "amount": 500.00, - "reasonValue": "schedule_conflict", - "reasonText": "行程冲突/时间变动", - "reasonDetail": "客户因工作变动无法出行，需要退款" -} -``` - -响应： - -```json -{ - "code": 200, - "data": { - "applicationId": 9876543210001, - "orderId": 1234567890123, - "orderNo": "HL2026052300001", - "productName": "云南大理双廊古镇 5 日深度游", - "refundType": "DEPOSIT", - "refundTypeLabel": "订金退款", - "reasonText": "行程冲突/时间变动", - "reasonDetail": "客户因工作变动无法出行，需要退款", - "paidAmount": 2000.00, - "calculatedAmount": 500.00, - "actualAmount": null, - "policyId": null, - "policyName": null, - "refundRatio": null, - "status": "PENDING", - "statusLabel": "待审核", - "applicantType": "ADMIN", - "applicantId": 10086, - "applicantName": "李小明", - "departureDate": "2026-06-15", - "daysBeforeDept": 23, - "reviewAdminId": null, - "reviewAdminName": null, - "reviewRemark": null, - "reviewedAt": null, - "approvalNo": null, - "appealStatus": null, - "appealStatusLabel": null, - "appealReason": null, - "appealAmount": null, - "appealedAt": null, - "refundedAt": null, - "createTime": "2026-05-23T10:30:00", - "updateTime": "2026-05-23T10:30:00" - }, - "message": "ok", - "success": true -} -``` - -### 8.2 边界情况 - -场景说明：退款金额等于订单订金金额上限（全额退订金），不填补充说明（reasonDetail 为 null）。 - -请求： - -``` -POST /admin/order/refund/apply -Authorization: Bearer <admin-jwt> -Idempotent-Key: b2c3d4e5-f6a7-8901-bcde-f12345678901 -Content-Type: application/json -``` - -```json -{ - "orderId": 1234567890124, - "amount": 2000.00, - "reasonValue": "personal_reason", - "reasonText": "个人原因", - "reasonDetail": null -} -``` - -响应： - -```json -{ - "code": 200, - "data": { - "applicationId": 9876543210002, - "orderId": 1234567890124, - "orderNo": "HL2026052300002", - "productName": "西藏拉萨布达拉宫 7 日游", - "refundType": "DEPOSIT", - "refundTypeLabel": "订金退款", - "reasonText": "个人原因", - "reasonDetail": null, - "paidAmount": 5000.00, - "calculatedAmount": 2000.00, - "actualAmount": null, - "policyId": null, - "policyName": null, - "refundRatio": null, - "status": "PENDING", - "statusLabel": "待审核", - "applicantType": "ADMIN", - "applicantId": 10086, - "applicantName": "李小明", - "departureDate": "2026-06-10", - "daysBeforeDept": 18, - "reviewAdminId": null, - "reviewAdminName": null, - "reviewRemark": null, - "reviewedAt": null, - "approvalNo": null, - "createTime": "2026-05-23T10:35:00", - "updateTime": "2026-05-23T10:35:00" - }, - "message": "ok", - "success": true -} -``` - -### 8.3 业务失败（异常） - -场景说明：退款金额超过订金金额，触发 530007 错误。 - -请求： - -``` -POST /admin/order/refund/apply -Authorization: Bearer <admin-jwt> -Idempotent-Key: c3d4e5f6-a7b8-9012-cdef-123456789012 -Content-Type: application/json -``` - -```json -{ - "orderId": 1234567890123, - "amount": 9999.00, - "reasonValue": "personal_reason", - "reasonText": "个人原因" -} -``` - -响应： - -```json -{ - "code": 530007, - "message": "退款金额不能超过订金金额: amount=9999.00, deposit=2000.00", - "success": false -} -``` - -## 9. 业务边界 - -- 适用场景：订单已支付（存在成功支付记录）时可发起退款申请 -- 不适用场景： - - 订单不存在 -> 返回 404 - - 订单未支付 -> 后端校验失败，返回业务错误 - - 同订单已有 ACTIVE 状态退款申请（PENDING/APPROVED/REFUNDING/APPEALING/APPEAL_APPROVED）-> 返回 530004 拒绝重复提交 - - amount 超过订单订金金额 -> 返回 530007 - - amount <= 0 -> 返回 400 参数校验失败 -- 特殊边界： - - 本接口不调退款政策计算，policyId/policyName/refundRatio 均为 null - - 退款类型固定为 DEPOSIT，不允许客服指定其他类型 - - 申请创建后状态固定为 PENDING，需走 `PUT /admin/order/refund/{applicationId}/review` 主管审批流程 - - 5 秒内携带相同 Idempotent-Key 重复提交视为同一请求，返回第一次的结果（不重复创建） - -## 10. 修改前后对比 - -全新接口，无修改前后对比。管理后台之前没有代用户发起退款的入口，本次为纯新增。 - -## 11. 影响评估 / 回滚 - -- 是否破坏向后兼容：否（全新接口，旧代码无感知） -- 前端是否必须同步上线：否（后端先上，前端可独立部署） - -## 12. 注意事项 - -- Header 必须携带 `Idempotent-Key`（UUID 格式），防止客服误操作重复提交。前端在进入发起退款页时生成一个 UUID，整个提交流程复用同一个 key -- 退款原因字典值需提前获取：调本接口前先调 `GET /admin/order/refund/reason/list` 拿到可用的 reasonValue 列表，不可自行填写字典 key -- 金额校验上限为订单订金金额，超过返回 530007，message 含具体金额数值 -- 提交成功后申请状态为 PENDING，可通过 applicationId 跳转至退款进度页，或按订单维度查询退款列表 - -## 13. 关联 / 联系人 - -### 13.1 链接 - -- **Issue**: [#2930](https://git.1814.love:8443/wx/HL/issues/2930) -- **PR**: [#2932](https://git.1814.love:8443/wx/HL/pulls/2932) -- **Merge commit**: [17e7fce90](https://git.1814.love:8443/wx/HL/commit/17e7fce90e5e4eb21e4e9c6bb4fb1d86e9c1fa21) -- **实现 commit**: [ca5e1a366](https://git.1814.love:8443/wx/HL/commit/ca5e1a36647edb01ba6c7b1337c07149c41665cb) - -### 13.2 联系人 - -- **后端负责人**: @yaosutu diff --git a/changelogs/2026-05/23_feat_banner_product_tags_seasons_top_tags.md b/changelogs/2026-05/23_feat_banner_product_tags_seasons_top_tags.md deleted file mode 100644 index b69d2e3..0000000 --- a/changelogs/2026-05/23_feat_banner_product_tags_seasons_top_tags.md +++ /dev/null @@ -1,117 +0,0 @@ -# feat(banner): /mp/banner/active 顶层 tags + PRODUCT 类型补 tags / seasons fallback - -> **仓库**: HL (后端 hl-mp-service + hl-user-service + hl-product-service-v2) -> **关联 PR/Issue**: PR #2952, Closes #2950 -> **日期**: 2026-05-23 -> **影响范围**: `/mp/banner/active` 响应新增顶层 `tags` + PRODUCT 类型 linkTarget 补 tags / seasons fallback -> **接收方**: mmg (前端) -> **前端**: **需要消费新字段** - ---- - -## 🎯 wx 实测反馈 - -1. **轮播图自身标签** (admin 编辑 banner 时填的「研学证书」)在 `/mp/banner/active` 没返回 -2. **PRODUCT 类型 banner** 跳产品时, linkTarget 缺产品自身标签 (`product.tags`), seasons 字段也常为空 - -## 改动 - -### 1. Banner 顶层 tags - -`MpBannerVO` 加 `tags: List<String>` 字段, 来自 `sys_banner.tags`。 - -之前精简掉了 tags 字段, Feign 反序列化下游 `BannerVO.tags` 被 Jackson 自动丢弃。 - -### 2. PRODUCT 类型 linkTarget 补 tags + seasons fallback - -- `InternalProductSimpleVO` (product-v2 + user-service 镜像) 加 `tags: List<String>` 字段 -- `ProductMapper.selectSimpleInfoByIds` `.select()` 补 `ProductDO::getTags` -- `ProductHelperService.selectSimpleByIds` builder 补 `.tags(p.getTags())` -- `BannerService.enrichLinkTarget` PRODUCT 分支: - - 透传 `p.getTags()` (**产品自身标签, 不 fallback 主题** — 产品有自己的标签语义) - - **seasons fallback**: 产品自己 seasons 为空且有 line_id → 取 line.seasons - - lineIds 收集逻辑扩到 productMap.values().lineId, 复用 lineMap 一次 Feign - -### 3. PRODUCT_LINE 分支不动 - -PR #2938/#2941 已做 (description + tags), 本期不动。 - -## API 行为变化 - -### `GET /mp/banner/active` 响应 - -```json -{ - "id": "2033821591988748290", - "title": "2026 亲子游学营", - "tags": ["研学证书"], // ← 新增, banner 自身标签 (sys_banner.tags) - "linkType": "PRODUCT", - "linkId": "...", - "linkTarget": { - "type": "PRODUCT", - "id": "...", - "name": "额吉的故乡V9·7天6晚旷野版", - "subtitle": "", - "coverImageUrl": "...", - "productType": "CORE", - "tags": ["亲子"], // ← 新增, 产品自身标签 (product.tags) - "seasons": ["winter"], // ← 修复 fallback line.seasons - "lineId": ..., - "description": null, // PRODUCT 场景不返 description (对称性) - }, - "sortOrder": 1 -} -``` - -### 两个 tags 字段独立语义 - -| 字段 | 来源 | 用途 | -|---|---|---| -| `banner.tags` | sys_banner.tags | 轮播图自身标签, 例「研学证书」、「私家团 / 亲子」 | -| `banner.linkTarget.tags` | PRODUCT_LINE: product_line.tags<br>PRODUCT: product.tags | 跳转目标自身标签, 例「限定」「亲子」「城记」 | - ---- - -## 🚨 前端需要做的事 - -### 1. 读取顶层 tags - -```ts -const banner = response.data[0]; -const bannerTags = banner.tags; // ["研学证书"] - banner 自身标签 -const linkTargetTags = banner.linkTarget?.tags; // ["亲子"] - 跳转目标标签 -``` - -### 2. 区分两个 tags - -前端轮播图卡片可在不同位置展示: -- `banner.tags` → 卡片右上角徽章 / 顶部 chip -- `banner.linkTarget.tags` → 跳转目标信息区(产品/主题卡片) - -如果两个 tags 在 UI 上不区分, 可合并去重展示。 - -### 3. seasons fallback 透明 - -`banner.linkTarget.seasons` 现在更可靠 — 产品没填时自动 fallback 产品线的 seasons, 前端按字段渲染即可。 - ---- - -## 测试服真测记录 - -部署 user + mp + product-v2 (rolling-deploy 2026-05-23 11:20) 后真测: - -| Banner | linkType | banner.tags | linkTarget.tags | linkTarget.seasons | linkTarget.description | -|---|---|---|---|---|---| -| #2033821591988748290 | PRODUCT | ✅ ['研学证书'] | ✅ ['亲子'] | ✅ ['winter'] (fallback line) | null (对称正确) | -| #5 (额吉的故乡) | PRODUCT_LINE | ✅ ['私家团','亲子'] | ✅ ['限定'] | ✅ ['winter'] | ✅ '公司的风格的' | - -单测: BannerServiceTest **37** + ProductHelperServiceTest **18** + InternalProductControllerTest **8** + mp Banner/Home **20** 全绿。 - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [#2950](https://git.1814.love:8443/wx/HL/issues/2950) 评论区留言。 diff --git a/changelogs/2026-05/23_feat_banner_topic_description_tags.md b/changelogs/2026-05/23_feat_banner_topic_description_tags.md deleted file mode 100644 index f8f4a4f..0000000 --- a/changelogs/2026-05/23_feat_banner_topic_description_tags.md +++ /dev/null @@ -1,155 +0,0 @@ -# feat(mp/user/product-v2): /mp/banner/active 主题 (PRODUCT_LINE) 补 description + tags 字段 - -> **仓库**: HL (后端 hl-mp-service + hl-user-service + hl-product-service-v2 + hl-common-feign) -> **关联 PR/Issue**: PR #2938 + PR #2941, Closes #2936 -> **日期**: 2026-05-23 -> **影响范围**: `/mp/banner/active` 响应新增 `linkTarget` 嵌套对象,内含 description / tags -> **接收方**: mmg (前端) -> **前端**: **需要消费新字段** — banner.linkTarget.description / banner.linkTarget.tags 渲染主题轮播卡片 - ---- - -## 🎯 业务背景 - -呼籁 admin 字典里 `banner_link_type=PRODUCT_LINE` 标签是「主题」,product_line 表面向 C 端就是"主题"概念。 - -之前 banner 绑定主题 (link_type=PRODUCT_LINE) 时 mp 端拿不到主题的 description 和 tags,前端无法在轮播图卡片展示。 - -## 改动 (2 个 PR) - -### PR #2938 — user-service + product-v2 字段贯通 - -- `InternalProductLineSimpleVO` (product-v2 + user-service 镜像) 加 `tags: List<String>` 字段 -- `BannerLinkTargetVO` 加 `description + tags` -- `ProductLineMapper.selectSimpleInfoByIds` `.select()` 列表补 tags 列 -- `ProductLineService.selectSimpleByIds` builder 补 `.tags(line.getTags())` -- `BannerService.enrichLinkTarget` PRODUCT_LINE 分支补 `.description(...).tags(...)` - -### PR #2941 — mp 端 VO 补 linkTarget 嵌套 - -- `MpBannerVO` 新增 `linkTarget` 字段(此前精简 VO 没这字段,Feign 反序列化时下游 BannerVO 的 linkTarget 被 Jackson 自动丢弃) -- `MpHomeBannerLinkTargetVO` 加 `description + tags` 字段,跟 user-service `BannerLinkTargetVO` 对齐 - -## API 行为变化 - -### `GET /mp/banner/active` - -每个 banner 现在多一个 `linkTarget` 嵌套对象: - -**PRODUCT_LINE (主题) 场景**: - -```json -{ - "id": 5, - "title": "额吉的故乡", - "linkType": "PRODUCT_LINE", - "linkId": "2045622604613529601", - "linkTarget": { - "type": "PRODUCT_LINE", - "id": "2045622604613529601", - "name": "额吉的故乡v11", - "subtitle": null, - "coverImageUrl": "https://...", - "productType": "CORE", - "seasons": ["winter"], - "lineId": null, - "description": "公司的风格的", // 新字段 - "tags": ["限定"] // 新字段 - }, - ... -} -``` - -**PRODUCT 场景**: - -```json -{ - "linkType": "PRODUCT", - "linkTarget": { - "type": "PRODUCT", - "name": "...", - "subtitle": "...", - "coverImageUrl": "...", - "productType": "CORE", - "seasons": [...], - "lineId": ..., - "description": null, // PRODUCT 不返,前端可忽略 - "tags": null - } -} -``` - -**其他 linkType / linkId 无效**: `linkTarget = null` - ---- - -## 🚨 前端需要做的事 - -### 1. 读取新字段 - -```ts -const banner = response.data[0]; -if (banner.linkType === 'PRODUCT_LINE' && banner.linkTarget) { - const desc = banner.linkTarget.description; // 主题描述 - const tags = banner.linkTarget.tags; // 主题标签数组 - const seasons = banner.linkTarget.seasons; // 季节数组 (本来就有) -} -``` - -### 2. 兼容性 - -- 旧前端代码不读 linkTarget 的不受影响 (顶层字段 id/title/imageUrl/linkType 等保持不变) -- linkTarget 可能为 null (其他 linkType 或目标已删除/下架),需做 null 守护 -- description 和 tags 仅 PRODUCT_LINE 场景有值,PRODUCT 场景为 null - -### 3. 自查 - -```bash -grep -rE "banner.linkTarget|banner\\.description|banner\\.tags" hl-ui/src -``` - ---- - -## 数据流 - -``` -product_line (DB) - ↓ ProductLineMapper.selectSimpleInfoByIds (含 tags) - ↓ ProductLineService.selectSimpleByIds (含 description + tags) - ↓ InternalProductLineSimpleVO (含 description + tags) - ↓ user-service BannerService.enrichLinkTarget (PRODUCT_LINE 分支) - ↓ user-service BannerLinkTargetVO (含 description + tags) - ↓ Feign /internal/mp/banner/active 返回 BannerVO - ↓ Jackson 反序列化到 mp MpBannerVO (PR #2941 新增 linkTarget 字段) - ↓ MpBannerVO.linkTarget 类型 MpHomeBannerLinkTargetVO (PR #2941 新增 description + tags) - ↓ /mp/banner/active 响应给前端 -``` - ---- - -## 测试服真测记录 - -部署 user + product-v2 + mp (rolling-deploy 2026-05-23 10:38) 后真测: - -```bash -curl https://api.test.1814.love:9443/mp/banner/active -``` - -| banner | linkType | description | tags | -|---|---|---|---| -| #2033821591988748290 | PRODUCT | null ✅ | null ✅ | -| #5 (额吉的故乡) | PRODUCT_LINE | '公司的风格的' ✅ | ['限定'] ✅ | - -单测: -- BannerServiceTest 32 全绿 -- ProductLine*Test 80 全绿 -- mp Banner + Home 20 全绿 - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [#2936](https://git.1814.love:8443/wx/HL/issues/2936) 评论区留言。 diff --git a/changelogs/2026-05/23_feat_product_itinerary_day_reorder.md b/changelogs/2026-05/23_feat_product_itinerary_day_reorder.md deleted file mode 100644 index 6b75507..0000000 --- a/changelogs/2026-05/23_feat_product_itinerary_day_reorder.md +++ /dev/null @@ -1,153 +0,0 @@ -# feat(product-v2): 产品行程天数支持拖拽重排 - -> **仓库**: HL (后端 hl-product-service-v2) -> **关联 PR/Issue**: PR #2926, Closes #2925 -> **日期**: 2026-05-23 -> **影响范围**: 新增 admin 端点,前端需新增拖动 UI 交互 -> **接收方**: mmg (前端) -> **前端**: **需要实现拖动 UI** - ---- - -## 🎯 业务背景 - -产品设计页 Step2「行程」标签,目前每一天的内容只能整体保存,**没法拖动整天重排**。 -本次后端新增专用 reorder 端点,前端实现拖动后调用即可。 - -典型场景: -- 原 D1 和 D2 整天对调 (D1↔D2) -- 原 D1 拖到第 3 天位置 (D1→D3, 原 D2/D3 自动上移) -- 6 天行程整体倒序 (D1↔D6, D2↔D5, D3↔D4) - ---- - -## 一、新增 endpoint - -### `POST /admin/product/item/{productId}/itinerary/reorder` - -**请求体**: - -```json -{ - "items": [ - {"dayId": 2043611284271677442, "newDayNumber": 1}, - {"dayId": 2043611284271677441, "newDayNumber": 2}, - {"dayId": 2043611284267483139, "newDayNumber": 3}, - {"dayId": 2043611284267483138, "newDayNumber": 4}, - {"dayId": 2043611284263288834, "newDayNumber": 5}, - {"dayId": 2043611284259094529, "newDayNumber": 6} - ] -} -``` - -**字段约束** (前端必须遵守,否则后端返业务错码): - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `items` | array | ✅ | 重排清单,**必须覆盖该产品当前所有未删除的天**(少传/多传都拒绝) | -| `items[].dayId` | Long | ✅ | 行程天 ID (从 `GET /admin/product/item/{id}/itinerary` 接口取) | -| `items[].newDayNumber` | int | ✅ | 新天序号 (1-based),所有 newDayNumber 必须组成 1..N 连续整数无重 | - -**响应**: - -| 场景 | code | message | -|------|------|---------| -| 成功 | 200 | `行程天数重排成功` | -| 产品状态不允许 (如 PUBLISHED/PENDING_REVIEW) | **430110** | `当前状态不允许行程重排, 请先下架或撤回审批` | -| items 与当前行程不匹配 (size 不等 / dayId 不全) | **430111** | `重排清单与当前行程不匹配, 请刷新页面后重试` | -| newDayNumber 不是 1..N 连续整数 (跳号/重复) | **430112** | `新天序号必须为 1..N 连续无重` | -| 5 秒内同用户重复点击 | 100502 | `请勿重复提交` (`@Idempotent` 防抖) | - ---- - -## 🚨 前端需要做的事 - -### 1. 拖动 UI - -参考"待办列表拖动"的常见库 (Vue 端 `vuedraggable` / React 端 `react-beautiful-dnd` 等),把行程按天列出,允许整天上下拖动。 - -### 2. 调 reorder 端点 - -拖完一次就调一次后端,**不需要等用户点保存按钮**(后端已有 5s 幂等防抖)。 - -```ts -const items = orderedDays.map((day, idx) => ({ - dayId: day.dayId, - newDayNumber: idx + 1 // 拖动后新序号 = 数组索引 + 1 -})); - -await axios.post(`/admin/product/item/${productId}/itinerary/reorder`, { items }); -// 成功后刷新当前页 itinerary,展示新序号 -``` - -### 3. 错码处理 - -| code | 用户提示 | -|------|---------| -| 430110 | 当前状态不允许行程重排,请先下架或撤回审批 | -| 430111 | 重排清单与当前行程不匹配,请刷新页面后重试 | -| 430112 | (理论上前端不会出这个,如果出说明前端拖动逻辑有 bug) | -| 100502 | 操作太快,请稍后再试 | - -### 4. UX 建议 - -- **乐观更新**:用户拖完先在本地更新天序号,再调后端,失败时回滚 -- **不要每次拖动都调后端**:用户连续拖几次可能撞 5s 幂等,可以本地 debounce 500ms 再调 -- **状态判断**:产品状态非可编辑时禁用拖动手势 (颜色置灰/拖不动) - -### 5. 哪些状态可以拖 - -后端通过 `EDITABLE_STATUSES = {DRAFT, REJECTED, UNPUBLISHED, COMPLETED}` 判定,**PUBLISHED 等其他状态会被 430110 拒绝**。前端最好提前判断 product.status 决定是否启用拖动手势,避免无谓 API 调用。 - ---- - -## 二、后端核心实现 (仅供 mmg 了解,前端无需关心) - -### Service 主流程 `ProductItineraryService.reorderDays` - -1. 状态校验 (复用 `checkEditable`) -2. `@Idempotent(timeout=5)` 5 秒防同用户重复点击 -3. 三道参数校验 (items 数量 / dayId 集合 / newDayNumber 连续无重) -4. 事务两阶段更新避免索引冲突: - - Step1: 临时把所有 `day_number` 改为负数 (`1..N → -1..-N`) - - Step2: 按 items 映射改回正数 newDayNumber -5. **同步冗余字段** `product_day_hotel.day_number` (内部聚合接口靠它分组) -6. 写 admin 操作日志,`changed_fields="itinerary_order"` - -### 子表关联 - -- `product_itinerary_node` / `product_route_point` 通过 `day_id` 关联,**零影响** -- `product_day_hotel` 同步 `day_number` - ---- - -## 三、测试服真测记录 - -部署 product-v2 双实例 (rolling-deploy 2026-05-23 09:15) 后真测: - -| # | 场景 | 实测 | -|---|------|------| -| T1 | DRAFT 6 天产品 (`2043595307274436609`) D1↔D6/D2↔D5/D3↔D4 全倒序 | ✅ 200 + DB 验证 day_id 不动 day_number 完美倒序 | -| T2 | PUBLISHED 产品 (`2043604279016443905`) 调 reorder | ✅ 430110 状态拒绝 | -| T3 | DRAFT 5 天产品 items 只传 4 个 | ✅ 430111 数量不匹配 | -| T4 | DRAFT 5 天产品 newDayNumber 跳号 (1,3,4,5,6 没 2) | ✅ 430112 新天序号必须为 1..N 连续无重 | -| T5 | DRAFT 6 天 + 5 hotel 产品 (`2044280877378134017`) 全倒序 | ✅ itinerary day_number 全反 + hotel day_number 完美同步 | - -单测:`ProductItineraryServiceReorderTest` 10 个 + 既有 `ProductItineraryServiceTest` 39 个 = **49 / 49 全绿** - ---- - -## 四、不在本期范围 - -- UNIQUE INDEX `(product_id, day_number)` — 等数据 audit 无重复后单独 PR (本期事务两步法已能容忍未来加这个索引) -- 快照刷新 — 拖动只影响编辑态,订单/小程序看的是订单快照,无影响 -- 前端 UI 实现 — mmg 实现 - ---- - -## 五、联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [#2925](https://git.1814.love:8443/wx/HL/issues/2925) 评论区留言。 diff --git a/changelogs/2026-05/23_fix_admin_info_token_role_sms_customizer.md b/changelogs/2026-05/23_fix_admin_info_token_role_sms_customizer.md deleted file mode 100644 index e577280..0000000 --- a/changelogs/2026-05/23_fix_admin_info_token_role_sms_customizer.md +++ /dev/null @@ -1,65 +0,0 @@ -# hotfix(user): /admin/auth/info 尊重 token role, SMS 登录强制 CUSTOMIZER - -> **仓库**: HL (后端 hl-user-service) -> **关联 PR/Issue**: PR #2946 (#2918 跟进, 非新工单) -> **日期**: 2026-05-23 -> **影响范围**: `/admin/auth/info` 响应 role 字段 -> **接收方**: mmg (前端) -> **前端**: **无需改动** — 响应字段类型不变, 仅 role/roleName 值修正 - ---- - -## wx 实测反馈 - -SMS 登录后顶部用户信息显示「超级管理员」, 不是「定制师」。前端 admin 端登录后角色 badge 异常。 - -## 根因 - -PR #2920 (Closes #2918) 让 SMS 登录响应里 `role=CUSTOMIZER` 是对的, **但**: - -- `getAdminInfo(adminId)` (Service) 默认按 `admin.currentRoleId` 算 activeRoleKey -- token 内嵌的 forced CUSTOMIZER 角色没传给 service -- 前端调 `/admin/auth/info` 重新拿到 currentRoleId 对应的 SUPER_ADMIN - -## 修复 - -- `AdminAuthService.getAdminInfo` 新签名 `(adminId, tokenRole)`: - - tokenRole=CUSTOMIZER 且 admin 真持有 CUSTOMIZER 角色 → activeRoleKey 强制 CUSTOMIZER - - 否则按现有 currentRoleId 逻辑 - - **不污染 admin.currentRoleId 持久化** (SMS 是临时切角色) -- `AuthController.getAdminInfo` 从 `request.getAttribute("role")` 透传 token role - -## 防御 - -`tokenRole=CUSTOMIZER` 但 admin 真实没 CUSTOMIZER 角色时 **NOT 强制**, 防止 token 纂改越权显示。 - -## API 行为对照 - -| token role | admin currentRoleId | admin 有 CUSTOMIZER | response.role | 说明 | -|---|---|---|---|---| -| 任意 | SUPER_ADMIN | - | SUPER_ADMIN | 旧逻辑 | -| CUSTOMIZER | SUPER_ADMIN | ✅ | **CUSTOMIZER** | **新, SMS 登录场景** | -| CUSTOMIZER | SUPER_ADMIN | ❌ | SUPER_ADMIN | 防御, 不信任 token | - -前端无需改动, 响应字段类型不变。 - -## 测试服真测 - -部署 user-service (2026-05-23 10:58) 后: - -| 场景 | response.role | response.roleName | -|---|---|---| -| SMS 登录 wx (持 SUPER_ADMIN+CUSTOMIZER 多角色) → /admin/auth/info | ✅ **CUSTOMIZER** | ✅ **定制师** | -| 密码登录 admin (SUPER_ADMIN) → /admin/auth/info | ✅ SUPER_ADMIN (不变) | ✅ 超级管理员 | - -## 单测 - -- AdminAuthServiceTest **69** 全绿 (新加 2 个 case: SMS 强制 / 防御不强制) -- AuthControllerTest **9** 全绿 (新加 verify tokenRole 透传) - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg diff --git a/changelogs/2026-05/23_fix_compare_strip_subtitle_intro_crowd.md b/changelogs/2026-05/23_fix_compare_strip_subtitle_intro_crowd.md deleted file mode 100644 index bdb30a1..0000000 --- a/changelogs/2026-05/23_fix_compare_strip_subtitle_intro_crowd.md +++ /dev/null @@ -1,62 +0,0 @@ -# fix(mp): /mp/product/compare 抹空 subtitle / introduction / crowdBenefit - -> **仓库**: HL (后端 hl-product-service-v2) -> **关联 PR/Issue**: PR #2944, Closes #2943 -> **日期**: 2026-05-23 -> **影响范围**: `/mp/product/compare` 响应 3 个字段抹空 -> **接收方**: mmg (前端) -> **前端**: **建议忽略 null 字段** — compare 页面无需展示这 3 字段 - ---- - -## 业务背景 - -wx 反馈: 产品对比接口前端只关心核心规格差异 (price / tier / itinerary / hotel 等), 简介性字段不需要返回。 - -## 改动 - -`MpProductService.compareByLine` 调完 `getDetail` 后, 循环把每个 VO 的 `subtitle` / `introduction` / `crowdBenefit` set null。 - -抽 private `stripCompareIrrelevantFields(vo)` helper, 单职责清晰。 - -## 为什么用 set null 而不删 VO 字段 - -`MpProductDetailRespVO` 是 `/mp/product/detail` 和 `/mp/product/compare` 共享的 VO。直接删字段会破坏详情接口。新建 compare 独立 VO 字段众多 (30+) 复制成本高。set null 是最小改动 + 详情接口零影响 + 前端忽略 null 即可。 - -## API 行为变化 - -### `POST /mp/product/compare` - -每个产品对象: - -- `subtitle: null` (本来有值) -- `introduction: null` (本来有值) -- `crowdBenefit: null` (本来是嵌套对象) - -其他字段不变。 - -### `/mp/product/detail` 不受影响 - -仍返完整 subtitle / introduction / crowdBenefit。 - ---- - -## 🚨 前端 - -- compare 页面渲染时忽略 subtitle / introduction / crowdBenefit (反正都是 null) -- detail 页面继续读这 3 字段, 不变 - ---- - -## 单测 - -`MpProductServiceTest` **76** 全绿, 含新加 `compareByLine_stripsCompareIrrelevantFields` 回归断言三字段都为 null。 - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [#2943](https://git.1814.love:8443/wx/HL/issues/2943) 评论区留言。 diff --git a/changelogs/2026-05/23_headsup_test_banner_none_type_seed.md b/changelogs/2026-05/23_headsup_test_banner_none_type_seed.md deleted file mode 100644 index 0feed90..0000000 --- a/changelogs/2026-05/23_headsup_test_banner_none_type_seed.md +++ /dev/null @@ -1,74 +0,0 @@ -# heads-up: 测试服新增 NONE 类型 banner 测试数据 (无跳转场景) - -> **类型**: heads-up (非 PR, 仅测试数据通知) -> **日期**: 2026-05-23 -> **环境**: 测试服 (api.test.1814.love) -> **接收方**: mmg (前端) -> **前端**: **无需改动**, 仅告知测试服多了一条 NONE 类型 banner 可用于联调 - ---- - -## 背景 - -PR #2952 (banner 顶层 tags + PRODUCT 字段补全) 上测试服后, wx 让我顺手验证 `/mp/banner/active` 对其他 linkType 的覆盖情况。查 DB 发现测试服现有 active banner 只有 PRODUCT + PRODUCT_LINE 各 1 条, 其他类型(NONE/SCENIC/ACTIVITY/HOTEL/PAGE/WEBVIEW)都没有 active 数据。 - -为了让前端能测"无跳转 banner"卡片样式, 我用 admin API 造了 1 条 NONE 类型 banner。 - -## 新增数据 - -| 字段 | 值 | -|---|---| -| id | `2058030675058958337` | -| title | `[autotest] NONE 类型测试 banner` | -| subtitle | "无跳转, 纯展示" | -| linkType | **NONE** | -| linkId | `""` (空) | -| tags | `["测试","无跳转","纯展示"]` | -| sortOrder | 50 | -| status | 1 (上架) | -| 有效期 | 2026-05-23 ~ 2027-12-31 | -| imageUrl | 复用现有测试图 | - -`[autotest]` 前缀标识为自动测试数据, 不参与生产逻辑评估, 可随时删除。 - -## `/mp/banner/active` 实际返回(3 条按 sortOrder) - -| sortOrder | linkType | linkTarget | 前端卡片渲染 | -|---|---|---|---| -| 1 | PRODUCT | 完整产品对象 | 跳产品详情页 | -| **50** | **NONE** | **null** | **不跳转**, 仅展示 title / imageUrl / tags | -| 99 | PRODUCT_LINE | 完整主题对象 | 跳主题详情页 | - -## NONE 类型字段对照 - -```json -{ - "id": "2058030675058958337", - "title": "[autotest] NONE 类型测试 banner", - "linkType": "NONE", - "linkId": "", - "tags": ["测试", "无跳转", "纯展示"], - "linkTargetType": null, - "linkTarget": null, - "seasons": null, - "sortOrder": 50 -} -``` - -## 🚨 前端建议 - -1. **NONE 类型卡片不读 linkTarget** — 强制 null, 读取会得到 null 触发空对象问题 -2. **点击行为**: 不跳转 (或不绑定点击事件) -3. **顶层 tags 仍正常返回** — 可在卡片角落展示标签徽章 -4. **可联调验证**: 当前测试服 3 条 active banner 覆盖了所有有 enrich 逻辑的 linkType (PRODUCT/PRODUCT_LINE) + 1 条无 enrich (NONE) - -## 后续清理 - -mmg 联调完通知 wx 后, 我会用 admin API 软删这条 `[autotest]` banner。如不告知, 1 个月后我例行清理。 - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg diff --git a/changelogs/2026-05/23_hotfix_itinerary_reorder_wipes_fields.md b/changelogs/2026-05/23_hotfix_itinerary_reorder_wipes_fields.md deleted file mode 100644 index 48f45ba..0000000 --- a/changelogs/2026-05/23_hotfix_itinerary_reorder_wipes_fields.md +++ /dev/null @@ -1,84 +0,0 @@ -# hotfix(product-v2): 拖动行程把所有天数据字段抹平为 null (P0 数据损坏) - -> **仓库**: HL (后端 hl-product-service-v2) -> **关联 PR/Issue**: PR #2933, Closes #2931 -> **日期**: 2026-05-23 -> **影响范围**: 行程天数拖拽重排接口 `/admin/product/item/{productId}/itinerary/reorder` -> **接收方**: mmg (前端) -> **前端**: **无 API 变化, 无需改前端** - ---- - -## 🚨 紧急修复说明 - -wx 反馈 (2026-05-23 09:50): 拖动产品行程天数重排后,**所有天的 dayTitle / description / coverImageUrl / 早晚餐 / 集合点 / 解散点 / 当日里程 等字段被抹空为 null**。 - -**P0 数据损坏**: 任何调用过 PR #2926 reorder 端点的产品,已经填好的行程内容全部被清空。day_id 关联的活动节点 (product_itinerary_node) 没丢, **只有 product_itinerary_day 主表的 IGNORED 策略字段被抹空**。 - -## 根因 - -`ProductItineraryDayDO` 大量字段标了 `@TableField(updateStrategy = FieldStrategy.IGNORED)` (Issue #2119 设计: 业务允许"清空字段")。PR #2926 reorderDays 实现里: - -```java -// 反例代码 (已修) -ProductItineraryDayDO up = new ProductItineraryDayDO(); // 空对象! -up.setDayId(d.getDayId()); -up.setDayNumber(-d.getDayNumber()); -negPhase.add(up); -dayService.updateBatch(negPhase); // IGNORED 策略下 null 字段会被写入! -``` - -`IGNORED` 策略下,**空对象的 null 字段会被 SQL UPDATE 写入 DB**,把用户填写的字段全部抹空。 - -## 修复 - -1. `ProductItineraryDayMapper` 新增 default `updateDayNumberById(dayId, dayNumber)`,用 `LambdaUpdateWrapperX.set` **只 update day_number 单列**,永不触碰其他字段 -2. `ProductItineraryService.reorderDays` Step1/Step2 改调 `dayService.updateDayNumberById`,不再走 `updateBatch(空对象集合)` -3. 新增回归测试 `reorderDays_doesNotWipeIgnoredFields` 守护 - -## API 行为变化 - -无! `/admin/product/item/{productId}/itinerary/reorder` 接口请求/响应字段完全一致,**前端无需做任何改动**。 - -修复前: 拖动后所有 IGNORED 字段被抹空 ❌ -修复后: 拖动后只改 day_number, 其他字段保留 ✅ - ---- - -## 🚨 前端需要做的事 - -**无需任何改动**。 - -可选: 通知 wx 数据库已损坏的产品(包括截图中的 ID=2053668473820622849)需要重新填写行程内容,**无法自动恢复**(binlog 时长有限)。 - ---- - -## 测试服真测记录 - -部署 product-v2 (rolling-deploy 2026-05-23 10:05) 后真测: - -| Step | 内容 | 结果 | -|------|------|------| -| 1 | DB 写测试字段: day_id=2043611284271677442 day_number=1 → day_title='TEST', description='应保留', cover='https://...', mileage=88.8 | ✅ 写入 | -| 2 | 调 reorder API 把 6 天全部倒序 (D1→6, D2→5, ...) | ✅ 200 重排成功 | -| 3 | 查 DB: day_id=2043611284271677442 跑到 day_number=6, **dayTitle/description/cover/mileage 完整保留** | ✅ 字段不丢 | -| 4 | 清测试数据 | ✅ | - -单测: hl-product-service-v2 `ProductItinerary*Test` **50/50 全绿** (含新增的 reorderDays_doesNotWipeIgnoredFields 回归测试 + 既有 ProductItineraryDOFieldStrategyTest 守护 IGNORED 策略) - ---- - -## 复盘 / 经验沉淀 - -**为什么 PR #2926 真测没捕获**: 当时真测脚本只验证 day_number 字段重排正确,**没验证其他字段不被改**。原 PR 真测产品的 dayTitle 本来就是 null, 无法暴露此 bug。 - -**今后真测要求**: 任何"写实体"的 PR 真测必须包含 `BEFORE / AFTER` 对照: 显式校验**未修改字段不被改**。已记入 MEMORY 经验。 - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [#2931](https://git.1814.love:8443/wx/HL/issues/2931) 评论区留言。 diff --git a/changelogs/2026-05/23_refactor_customizer_lookup_by_userid_openid.md b/changelogs/2026-05/23_refactor_customizer_lookup_by_userid_openid.md deleted file mode 100644 index a6e4693..0000000 --- a/changelogs/2026-05/23_refactor_customizer_lookup_by_userid_openid.md +++ /dev/null @@ -1,127 +0,0 @@ -# refactor: 定制师反查链路改 by-userid / by-openid (手机号 PII 不出 user-service + 性能减半) - -> **仓库**: HL (后端 hl-user-service + hl-mp-service + hl-order-service-v2 + hl-common-feign + hl-common-log) -> **关联 PR/Issue**: PR #2924,**无关联工单**(二轮深度 CR 整改) -> **日期**: 2026-05-23 -> **影响范围**: 内部反查接口签名变化,前端**无感知** -> **接收方**: mmg (前端) -> **前端**: **无需变更** — 本 PR 全是后端内部 Feign 链路重构,`/mp/customizer/me` 和下单 `sharerOpenid` 反查的对外行为完全一致 - ---- - -## 🎯 核心改动 (二轮 CR P0 整改) - -PR #2913 (定制师分享反查) 引入的反查链路把客人/定制师真实手机号通过 Feign URL query 在内网服务间明文流转: - -- mp 端 `/mp/customizer/me`: `getProfile(userId)` 取 `rawPhone` → `getCustomizerByPhone(phone)` 两次串行 -- order-v2 端分享下单: `getUserByOpenid(openid)` 取 `phone` → `getCustomizerByPhone(phone)` 两次串行 - -**问题**: -- 手机号会出现在 nginx access log + SkyWalking 分布式 trace 中,**绕过 `maskPhone` 脱敏** -- 串行 2 次 Feign,P99 延迟翻倍 - -**重构方案**: user-service 内部一次性完成 `userId/openid → user.phone → admin_user.mobile → CUSTOMIZER 校验`,**phone 永不出 user-service 进程** - ---- - -## 一、新增内部接口 (Feign,不经网关) - -### `GET /internal/user/customizer/by-userid?userId=xxx` (mp 端用) - -| 字段 | 类型 | 说明 | -|------|------|------| -| code | int | 200 | -| data | `CustomizerByPhoneInternalVO` 或 null | 命中的 CUSTOMIZER admin 信息 | - -匹配规则: `user.user_id → user.phone → admin_user.mobile == phone + status=ACTIVE + 拥有 CUSTOMIZER 角色` - -### `GET /internal/user/customizer/by-openid?openid=xxx` (order-v2 端用) - -参数/返回同上,只是入口换成 `openid`(`user.openid → user.phone → admin_user.mobile`). - -### 旧 endpoint `/internal/user/admin/by-phone?phone=xxx` 保留 - -兼容其他可能的调用方,暂不下线 (后续会陆续迁移)。 - ---- - -## 二、调用方变化 (对前端零影响) - -### `GET /mp/customizer/me` - -| 项 | 之前 | 现在 | -|----|------|------| -| Feign 调用次数 | 2 次串行 (`getProfile` + `getCustomizerByPhone`) | **1 次** (`getCustomizerByUserId`) | -| 真实手机号传输 | 走第二次 Feign URL query | **不出 user-service** | -| 响应字段 | 不变 | 不变 | -| 行为 | 不变 | 不变 | - -### `POST /mp/order/create` 的 `sharerOpenid` 反查 - -| 项 | 之前 | 现在 | -|----|------|------| -| Feign 调用次数 | 2 次串行 (`getUserByOpenid` + `getCustomizerByPhone`) | **1 次** (`getCustomizerByOpenid`) | -| 真实手机号传输 | 走第二次 Feign URL query | **不出 user-service** | -| 行为 | 不变 (兜底 / 命中 / 反查异常 三个分支保留) | 不变 | - ---- - -## 🚨 前端需要做的事 - -**什么都不需要做**。 - -- `/mp/customizer/me` 响应字段无变化,前端按既有逻辑渲染即可 -- `POST /mp/order/create` 接口无变化 -- 错码无新增 - -可选自查: -```bash -grep -rE "/mp/customizer/me|sharerOpenid" hl-ui/src mp-cli/src -``` - ---- - -## 三、附带优化 (二轮 CR P1) - -### P1#11 — SMS 登录路径重复代码抽 helper - -`AdminAuthService.loginBySms` 中 3 段几乎一模一样的「incr fail count + judge locked/remaining + throw」(码错 / mobile 不绑 / 非定制师 3 个分支),抽 private `buildSmsFailOrLocked(failKey, currentFail)`。**行为完全不变**,既有 16 个 SMS 单测全部通过。 - -### P1#13 — GlobalExceptionHandler.handleLoginFail 补单测 - -PR #2913 引入的 `handleLoginFail` 拦截器原本 0 覆盖率,补 3 个 case: -- `remainingAttempts → LoginFailDetailVO{remainingAttempts=3, lockedMinutes=null}` -- `locked → LoginFailDetailVO{remainingAttempts=null, lockedMinutes=15}` -- `zeroRemaining` 边界 → `remainingAttempts=0` 如实回传 - ---- - -## 四、测试服验证记录 - -部署 user + mp + order-v2 三服务 (rolling-deploy-all,2026-05-23 00:11) 后真测: - -| # | 场景 | 实测 | -|---|------|------| -| T1 | CUSTOMIZER user (wx, userId=...4314) → SMS 登录 → `/mp/customizer/me` | ✅ `isCustomizer=true, adminId=...8914, customizerName=王骁` (新 `getCustomizerByUserId` 走通) | -| T2 | 未登录直接调 `/mp/customizer/me` | ✅ 200 + `isCustomizer=false` (P1#13 拦截器返 200 兜底) | -| T3 | nginx access log + user-service 自身日志 grep `phone=18*` | ✅ 0 命中 (手机号不再出现在日志) | -| 单测 | hl-user-service 129 + order-v2 OrderCreateServiceTest 28 + mp MpCustomizerAggregationServiceTest 4 + common-log GlobalExceptionHandlerTest 33 | ✅ 全绿 | - ---- - -## 五、不在本期范围 (有意保留,二轮 CR 评估后) - -- VO 命名 8 元组改名 (`AdminLoginResponse → AdminLoginRespVO` 等) — changelog 已发字段名不能动,改类名/移包风险大于收益 -- `@Transactional` 边界缩窄 — 改动面大,既有测试容易破 -- `getCustomizerByMobileForFeign` 加 Redis 缓存 — P2 性能优化,QPS 未观察到瓶颈 -- `doSendSms` 异步化防 timing 攻击 — 实际可利用性低 (要先拿到正确的 SMS code) -- `MpUserFeignClient.getProfile` Map<String,Object> 改 UserVO — 历史包袱,mp 端已不再用 `getProfile` 取 phone (被新 by-userid 替代),问题自然消解 - ---- - -## 六、联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问可在 [PR #2924](https://git.1814.love:8443/wx/HL/pulls/2924) 评论区留言。 diff --git a/changelogs/2026-05/24_correction_mini_share_no-adminid-chain.md b/changelogs/2026-05/24_correction_mini_share_no-adminid-chain.md deleted file mode 100644 index 6721083..0000000 --- a/changelogs/2026-05/24_correction_mini_share_no-adminid-chain.md +++ /dev/null @@ -1,165 +0,0 @@ -# correction(小程序分享): 撤回链式继承 adminId 建议 — 后端 sharerOpenid 反查链已就绪 - -> **类型**: 更正前一个 heads-up -> **日期**: 2026-05-24 -> **更正对象**: `24_headsup_mini_share_chain_adminid.md` (同日发的) -> **接收方**: mmg (前端 hl-mini) - ---- - -## 🙏 致歉 + 更正 - -前一份 changelog 让 mmg 在所有分享页面"链式继承 adminId"的建议是**多余的**。wx 提醒我后端反查链早已就绪,我重新精查 hl-mini 仓库代码 + 比对 OrderCreateService 后确认: **产品详情页(`product/core` + `product/mengma`)的分享路径目前已经能正确归属定制师**,前端无需任何"链式继承"改造。 - -下面整理实际现状。 - ---- - -## ✅ 实际工作机制 (已闭环部分) - -### 后端反查链 (PR #2913 已合 main / 已上正式) - -`OrderCreateService.resolveSharedCustomizerId(ctx)` 顺序: - -1. **`ctx.customizerId` 显式传值** (URL `?adminId=xxx` / customizerId) → 直接采用 (老 URL Scheme 链路兼容) -2. **`customizerId` 空 + `sharerOpenid` 非空** → 调用 `userFeignClient.getCustomizerByOpenid(openid)` - - 在 user-service 内部一次性聚合反查 (openid → user.phone → admin_user.mobile → adminId) - - phone 不通过 Feign URL 暴露 (二轮 CR 加固) -3. 任何一步失败 / 命中的 admin 不是活跃 CUSTOMIZER → 兜底 `assignRandomCustomizer` - -### 前端 product/core + mengma 详情页 (已生效) - -```js -onShareAppMessage() { - const openId = storage.get('openId') || ''; - return { - path: `/packages/product/core/detail/detail?id=${productId}&shareOpenId=${openId}`, - ... - }; -} -``` - -`shareOpenId` 是分享人的小程序 openid (从 `storage.get('openId')` 取当前登录用户的)。 - -### 完整链路 (链路 B 实际工作) - -``` -wx 在产品详情页点「分享给朋友」 - ↓ -onShareAppMessage path 含 shareOpenId = wx 的 openid - ↓ -客人扫码进店 onLoad → _shareOpenId = wx 的 openid - ↓ -客人下单 confirm.js → orderData.sharerOpenid = wx 的 openid - ↓ -后端 MpOrderSaveReqVO 接 sharerOpenid → ctx.setSharerOpenid() - ↓ -OrderCreateService.resolveSharedCustomizerId 走反查链 - ↓ -userFeignClient.getCustomizerByOpenid(wx_openid) → wx 的 adminId - ↓ -customizerValidator.resolve(wx_adminId) 校验 CUSTOMIZER 角色通过 - ↓ -order.customizerId = wx_adminId ✅ 归原始定制师 -``` - -**产品详情页(core + mengma)的分享已经完全正确**, 无需链式继承 adminId, 无需调 `/mp/customizer/me`。 - ---- - -## ⚠️ 真正缺的部分: 其他可分享页未透传 shareOpenId - -grep 现状: **15 个可分享页面没传 shareOpenId**, 客人从这些页面扫码进店分享, sharerOpenid 字段后端拿不到, 后端反查链无法识别分享人, 客人下单走 `assignRandomCustomizer` 兜底随机。 - -### 没传 shareOpenId 的页面清单 (按业务影响排序) - -| 优先级 | 页面 | 文件 | 现状 path | -|---|---|---|---| -| **P0** | 首页 | `pages/index/index.js` L122-129 | `/pages/index/index` | -| **P1** | 酒店详情 | `packages/hotel/detail/detail.js` L131-138 | `?id=${id}` | -| **P1** | 景区详情 | `packages/scenic/detail/detail.js` L189-197 | `?id=${id}` | -| **P1** | 餐厅详情 | `packages/restaurant/detail/detail.js` L65-72 | `?id=${id}` | -| **P1** | 活动详情 | `packages/activity/detail/detail.js` L86-93 | `?id=${id}` | -| **P2** | 定制师详情 | `packages/custom/detail/detail.js` L183-190 | `?id=${designerId}` | -| **P2** | 攻略详情 | `packages/guide/detail/detail.js` L70-77 | `?id=${id}` | -| **P3** | 酒店/景区/餐厅/活动**列表页** | 各 `list.js` | 各种 list path | -| **P3** | 定制入口 | `packages/custom/custom/custom.js` L119-125 | `/custom/custom` | -| **P3** | 旅行指南 | `packages/user/travel-guide/travel-guide.js` L9-14 | `/travel-guide` | -| **P3** | 定制案例 | `packages/product/custom-all/list/list.js` L25-29 | `/custom-all/list` | -| **P3** | 评价列表 | `packages/review/list/list.js` L155+ | `?targetId=...&targetType=...` | - -### 推荐改法 (所有页面统一模式) - -```diff -onShareAppMessage() { - const { ... } = this.data; -+ const openId = storage.get('openId') || ''; -+ const shareSuffix = openId ? `&shareOpenId=${openId}` : ''; - return { - title: ..., -- path: `/packages/hotel/detail/detail?id=${this.data.id}`, -+ path: `/packages/hotel/detail/detail?id=${this.data.id}${shareSuffix}`, - imageUrl: ... - }; -} -``` - -> ⚠️ 注意首页 `pages/index/index` 这种没有现成 query 的, `shareSuffix` 要改成 `?shareOpenId=${openId}` (注意 `?` 前缀)。 - -### 还需注意 onShareTimeline (朋友圈分享) - -product/core L1474-1482 + product/mengma 同样有 `query: \`id=${productId}&shareOpenId=${openId}\``。其他详情页如果有 onShareTimeline 也要同步补 shareOpenId。grep 看 onShareTimeline 比 onShareAppMessage 实现少, 建议加一份扫描。 - ---- - -## 🧹 可选清理 (confirm.js) - -下单代码 `packages/order/confirm/confirm.js` L837-838: -```js -if (this._adminId) { - orderData.adminId = this._adminId; // ← 后端 MpOrderSaveReqVO 不接, Jackson @JsonIgnoreProperties(ignoreUnknown=true) 直接吞掉 -} -``` - -`adminId` 字段后端不接收, 是死代码 (无害但冗余)。 `_adminId` 已经走 L176-179 `_customizerId` 兜底链, 不需要单独透传。**可以删掉**, 也可以留着 (后端不会因此报错)。 - ---- - -## 📊 三个分享渠道最新现状 - -| # | 渠道 | 当前归属正确? | 还要做什么 | -|---|---|---|---| -| **A** | admin 端 URL Scheme | ✅ PR #2977 后限定持 CUSTOMIZER + 绑企微的 admin 可生成 | — | -| **B** | 产品详情页(core + mengma) `onShareAppMessage` | ✅ shareOpenId 已透传, 后端反查链生效 | — | -| **B'** | 产品详情页(core + mengma) `onShareTimeline` (朋友圈) | ✅ 同上 | — | -| **B''** | **其他详情/列表页 onShareAppMessage** | ❌ shareOpenId 没透传, 客人下单兜底随机 | **补 shareOpenId 透传** (上方 15 个文件) | - ---- - -## ✅ 验证方式 (前端改完后) - -1. wx (定制师) 在小程序内任一详情页点「分享给朋友」给客人 -2. 客人扫码进店, 浏览到产品页下单 -3. 后端订单 `customizer_id` 字段应该等于 wx 的 admin_id (不是兜底随机) -4. 后端日志会有: `订单按 sharerOpenid 反查定制师成功: openid=xxx, adminId=wx_id` - ---- - -## 📅 时间线 - -| # | 任务 | 负责人 | 状态 | -|---|---|---|---| -| 1 | 后端 PR #2977 admin guard | wx | ✅ 合 dev / 测试服真测拒绝路径通过 | -| 2 | ~~前端 onShareAppMessage 链式继承 adminId~~ | ~~mmg~~ | ❌ **撤回, 不需要做** | -| 3 | 前端其他可分享页补 shareOpenId 透传 (15 个文件 / 按优先级分多 PR) | mmg | ⏳ 待 mmg 排期 | -| 4 | 可选: confirm.js L837-838 删 orderData.adminId 死字段 | mmg | ⏳ 可选 | -| 5 | 后端 PR #2977 合 main → 上正式 | wx | ⏳ | - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问看后端 PR https://git.1814.love:8443/wx/HL/pulls/2977 + 工单 https://git.1814.love:8443/wx/HL/issues/2976 diff --git a/changelogs/2026-05/24_headsup_mini_share_chain_adminid.md b/changelogs/2026-05/24_headsup_mini_share_chain_adminid.md deleted file mode 100644 index 14c887a..0000000 --- a/changelogs/2026-05/24_headsup_mini_share_chain_adminid.md +++ /dev/null @@ -1,230 +0,0 @@ -# heads-up(小程序分享): onShareAppMessage / onShareTimeline 需链式继承 adminId - -> **类型**: heads-up + 前端待办 (后端无需改动) -> **关联 PR/Issue**: 后端 PR #2977 (Closes #2976) 配套 -> **日期**: 2026-05-24 -> **影响范围**: 小程序内原生分享渠道(分享给朋友 / 分享到朋友圈)的客人下单定制师归属 -> **接收方**: mmg (前端 hl-mini 仓库) -> **前端**: **需要改造** (本仓后端已就绪,等前端补齐链路) - ---- - -## 🎯 背景 - -wx 实测发现:**admin (id=1001 SUPER_ADMIN, 非定制师) 在管理端「分享到小程序」生成的 URL Scheme,客人扫码下单后订单的「定制师」被错绑成 admin 自己,不是中间转发的真定制师 wx**。 - -根因: URL Scheme 的 t 参数在微信 wxa/generatescheme 时**加密锁死**,中间转发不能改写,query 里的 `adminId=` 永远是"生成人"。 - -后端已修 (PR #2977 已合 dev,测试服真测拒绝路径通过): -- `POST /admin/wxapp/share/url-link` 和 `/url-scheme` 加 guard -- 仅 `status=ACTIVE` + `roleKeys 含 CUSTOMIZER` + `wechatUserid 非空` 的 admin 可生成 -- 错误码 `200312 SHARE_REQUIRES_BOUND_CUSTOMIZER`, 文案: **"仅持定制师角色且已绑定企业微信的成员可生成分享链接"** - -但这只覆盖了**链路 A** (admin 端管理后台「分享 URL Scheme」按钮)。**链路 B / C 还没覆盖**,需要 mmg 前端配合。 - ---- - -## 📊 三个分享渠道现状 - -| # | 渠道 | 入口 | 当前前端实现 | 客人下单归属 | -|---|---|---|---|---| -| **A** | admin/定制师 在管理端点「分享 URL Scheme」 | hl-ui MiniappShareModal.vue | URL query 含 `adminId=<生成人id>`, 小程序 onLoad 接到存 storage | ✅ PR #2977 后只有定制师能生成, customizer 正确 | -| **B** | 定制师在小程序产品详情页点右上角「分享给朋友」 | `onShareAppMessage()` | **只传 `shareOpenId`, 没传 adminId** | ❌ 客人下单 customizerId 空 → 兜底随机 | -| **C** | 定制师在小程序产品详情页点「分享到朋友圈」 | `onShareTimeline()` | **只传 `shareOpenId`, 没传 adminId** | ❌ 同上 | - ---- - -## 🔬 代码定位 - -仓库 `mmg/hl-mini` main 分支, 文件 `packages/product/core/detail/detail.js`: - -### L191-199 onLoad (接收链路 A 的 adminId, 这部分已经对) - -```js -onLoad(options) { - const productId = options.id; - this._shareOpenId = options.shareOpenId || ''; - this._adminId = options.adminId || ''; - // 链路 A 的 adminId 已写入 storage 桥接订单详情页 - if (this._adminId) { - storage.setShareCustomizerId(this._adminId); - } - ... -} -``` - -### L1464-1472 onShareAppMessage (BUG: 没拼 adminId) - -```js -onShareAppMessage() { - const { product, productId, shareCardImage, heroBgImage } = this.data; - const openId = storage.get('openId') || ''; - return { - title: product.title || '呼籁旅行 ...', - path: `/packages/product/core/detail/detail?id=${productId}&shareOpenId=${openId}`, // ← 缺 adminId - imageUrl: shareCardImage || heroBgImage || '' - }; -} -``` - -### L1474-1482 onShareTimeline (BUG: 同样没拼) - -```js -onShareTimeline() { - ... - return { - title: ..., - query: `id=${productId}&shareOpenId=${openId}`, // ← 缺 adminId - imageUrl: ... - }; -} -``` - ---- - -## 🛠️ 前端推荐改造 (链式继承 adminId) - -**最简方案 — 不需要调任何后端接口, 沿用 storage 桥接的 adminId**: - -```js -onShareAppMessage() { - const { product, productId, shareCardImage, heroBgImage } = this.data; - const openId = storage.get('openId') || ''; - // 链式继承: 当前页面是从分享链接进入的话, _adminId 不为空; 否则从 storage 兜底 - const adminId = this._adminId || storage.get('shareCustomizerId') || ''; - // path 拼上 adminId, 这样客人扫码进店 onLoad 时 options.adminId 仍是原始定制师 - const adminPart = adminId ? `&adminId=${adminId}` : ''; - return { - title: product.title || '呼籁旅行 ...', - path: `/packages/product/core/detail/detail?id=${productId}&shareOpenId=${openId}${adminPart}`, - imageUrl: shareCardImage || heroBgImage || '' - }; -} - -onShareTimeline() { - const { product, productId, shareCardImage, heroBgImage } = this.data; - const openId = storage.get('openId') || ''; - const adminId = this._adminId || storage.get('shareCustomizerId') || ''; - const adminPart = adminId ? `&adminId=${adminId}` : ''; - return { - title: product.title || '呼籁旅行 ...', - query: `id=${productId}&shareOpenId=${openId}${adminPart}`, - imageUrl: shareCardImage || heroBgImage || '' - }; -} -``` - -### 链式继承的业务效果 - -1. wx (定制师) 通过 admin 端生成首个链接 `?adminId=wx_id` 发给客人 A -2. A 进店 onLoad → `_adminId = wx_id` → 存 storage -3. **A 在小程序里再点「分享给朋友」给客人 B** → onShareAppMessage 沿用 wx_id → path 含 `adminId=wx_id` -4. B 扫码进店下单 → customizerId=wx_id → customizer 归 wx ✅ -5. 第 N 次转发都归原始定制师, **营销链路追溯完整** - ---- - -## 🔧 升级方案 (可选, 若定制师自己直接打开小程序产品页要分享) - -如果定制师 wx **没有经过 admin 端链接, 自己直接进入小程序** 想要分享产品 → `_adminId` 为空, storage 也无 → 链式继承拿不到 adminId → 客人下单兜底随机。 - -解决方法: 页面 onLoad 调后端 `GET /mp/customizer/me` (PR #2913 已上线): - -```js -onLoad(options) { - this._shareOpenId = options.shareOpenId || ''; - this._adminId = options.adminId || ''; - if (this._adminId) { - storage.setShareCustomizerId(this._adminId); - } - // 升级: 如果当前用户是定制师本人, 把自己 adminId 也写入 storage 用于分享 - if (!this._adminId) { - customizerApi.me().then(res => { - if (res?.data?.isCustomizer && res?.data?.adminId) { - this._adminId = res.data.adminId; - storage.setShareCustomizerId(this._adminId); - } - }); - } - ... -} -``` - -`/mp/customizer/me` 响应结构: -```json -{ - "code": 200, - "data": { - "isCustomizer": true, - "adminId": "1760000000000099", - "customizerName": "王骁", - "avatar": "..." - } -} -``` - ---- - -## 📋 改造范围 (其他可分享页面) - -类似的分享 hook 在以下页面也需要同步加 adminId (基于 grep 结果): - -- ✅ `packages/product/core/detail/detail.js` (重点, 上述代码) -- `packages/product/mengma/detail/detail.js` (小蒙马产品详情) -- `packages/scenic/detail/detail.js` (景区详情) -- `packages/hotel/detail/detail.js` (酒店详情) -- `packages/restaurant/detail/detail.js` (餐厅详情) -- `packages/guide/detail/detail.js` (向导详情) -- `packages/user/travel-guide/travel-guide.js` (旅行攻略) -- `packages/product/compare/compare.js` (对比页) -- `pages/index/index.js` (首页) -- `pages/trip/trip.js` (行程页) - -建议**至少先改 4 个核心入口**: 核心产品详情 / 小蒙马产品详情 / 主题(产品线)详情 / 首页。其他后续补。 - ---- - -## ✅ 验证方式 (前端改完后) - -1. wx (定制师) 在管理端「分享 URL Scheme」生成 → 给客人 A -2. A 进店 → 在小程序内再点产品页右上角「分享给朋友」 → 给客人 B -3. B 进店 onLoad → `console.log(this._adminId)` 应等于 wx 的 admin_id -4. B 下单 → 后端订单的 `customizer_id` 字段应等于 wx 的 admin_id -5. 朋友圈分享: A 点「分享到朋友圈」, 别人通过朋友圈进店, 同样验证 `_adminId` 链式继承 - ---- - -## 🔗 后端接口清单 (mmg 不需要改, 已就绪) - -| 接口 | 路径 | 用途 | -|---|---|---| -| 获取当前定制师身份 | `GET /mp/customizer/me` | 当前 C 端用户是定制师? 返 adminId | -| 客人下单 | `POST /mp/order/create` | 接受 `customizerId` (字符串透传雪花 ID) + `sharerOpenid` (溯源用) | -| Admin 生成 URL Link / Scheme | `POST /admin/wxapp/share/url-link` `/url-scheme` | PR #2977 后限定持 CUSTOMIZER + 绑企微的 admin | - -`customizerId` 在订单创建时由后端 `CustomizerValidator.resolve()` 校验: -- `status = ACTIVE` -- `roleKeys` 含 `CUSTOMIZER` -- 通过 → 订单 customizer = 该 adminId -- 不通过 → 订单 customizer 走 `assignRandomCustomizer` 兜底随机 - ---- - -## 📅 时间线建议 - -| # | 任务 | 负责人 | 状态 | -|---|---|---|---| -| 1 | 后端 admin 端 guard PR #2977 | wx | ✅ 已合 dev / 测试服真测拒绝路径通过 | -| 2 | 前端 onShareAppMessage / Timeline 链式继承 adminId (核心产品页) | **mmg** | ⏳ | -| 3 | 前端其他分享入口同步改 (景区/酒店/...等) | mmg | ⏳ 可分多 PR | -| 4 | 前端调 `/mp/customizer/me` 兜底定制师本人首次进入 (可选升级) | mmg | ⏳ 可选 | -| 5 | 后端 PR #2977 合 main → 上正式 | wx | ⏳ | - ---- - -## 联系人 - -后端: wx (呼籁旅行) -前端: mmg - -如有疑问看后端 PR https://git.1814.love:8443/wx/HL/pulls/2977 + 工单 https://git.1814.love:8443/wx/HL/issues/2976 diff --git a/changelogs/2026-05/25_feat_review_revert_status_switch.md b/changelogs/2026-05/25_feat_review_revert_status_switch.md deleted file mode 100644 index b337786..0000000 --- a/changelogs/2026-05/25_feat_review_revert_status_switch.md +++ /dev/null @@ -1,148 +0,0 @@ -# feat(评价): 已通过↔已拒绝评价可互相切换(必填理由) — admin 端新增反转按钮 - -> **类型**: feat (后端 + 前端均需改动) -> **关联 PR/Issue**: PR #2985 (Closes #2983) 已合 dev,测试服已部署 -> **日期**: 2026-05-25 -> **影响范围**: admin 端「评价审核」(详情/列表),小程序端无影响 -> **接收方**: mmg -> **前端**: **admin 端需改造**(已通过/已拒绝状态新增反转按钮 + 必填理由弹窗) - ---- - -## 🎯 背景 - -现状管理员审核错了不能回退 —— APPROVED/REJECTED 都是终态。本次: -- 已通过的评价可改为已拒绝 -- 已拒绝的评价可改为已通过 -- **互转必填理由**(写入新字段 `revertRemark` 审计) -- **机审拒绝(MACHINE_REJECTED)不在本次范围**,仍走原有「覆盖通过」按钮 → `/override-approve`(不变) - ---- - -## 📊 新增 1 个接口 `POST /admin/review/{reviewId}/revert` - -### Request body - -```json -{ - "targetStatus": "APPROVED", // 必填,枚举 APPROVED / REJECTED - "remark": "经核实评价内容真实,改为通过" // 必填,1-500 字 -} -``` - -### Response - -成功:`{ "code": 200, "message": "成功", "data": null }` - -失败: -| 场景 | code | message | -|------|------|---------| -| remark 空 | 400 | 反转备注不能为空 | -| targetStatus 不是 APPROVED/REJECTED | 400 | 目标状态仅支持 APPROVED 或 REJECTED | -| 当前状态非 APPROVED/REJECTED | 551076 | 评价状态不允许反转,仅 APPROVED ↔ REJECTED 可互转 | -| targetStatus 与当前相同 | 551076 | 同上 | -| 评价不存在 | 404(NotFoundException) | 评价不存在 | - -### 允许的状态转换 - -| 当前 | targetStatus | 结果 | -|------|--------------|------| -| APPROVED | REJECTED | ✓ 走 ADMIN_REVERT_TO_REJECT | -| REJECTED | APPROVED | ✓ 走 ADMIN_REVERT_TO_APPROVE | -| PENDING_MANUAL | * | ✗ 仍走 `/approve` 或 `/reject` | -| MACHINE_REJECTED | * | ✗ 仍走 `/override-approve` | -| PENDING_MODERATION | * | ✗ 机审中,不操作 | -| APPROVED | APPROVED | ✗ 同状态 | - ---- - -## 📊 现有 3 个接口完全不动 - -| 接口 | 允许态 | body | 说明 | -|------|--------|------|------| -| `/approve` | PENDING_MANUAL → APPROVED | 无 | 维持现状 | -| `/reject` | PENDING_MANUAL → REJECTED | rejectReason 必填 | 维持现状 | -| `/override-approve` | MACHINE_REJECTED → APPROVED | 无 | 维持现状 | - ---- - -## 📊 VO 新增字段 `revertRemark` - -`ReviewVO`(详情)和 `ReviewListVO`(列表)新增: - -```diff -{ - "reviewId": 100001, - "status": "REJECTED", - "rejectReason": "原始拒绝原因", -+ "revertRemark": "经核实评价内容真实,改为通过" // 反转备注(可能 null) -} -``` - -**`MpReviewVO` 不加**(小程序无需展示)。 - -`rejectReason` 字段语义保持「PENDING_MANUAL → REJECTED 时的初次拒绝原因」,不动。`revertRemark` 是「终态反转操作的备注」,独立字段。 - ---- - -## 🎨 admin 前端期望改造 - -### 按钮联动 - -当前状态 → 显示的操作按钮: - -| status | 显示按钮 | -|--------|---------| -| PENDING_MANUAL | 「通过」(`/approve`) / 「拒绝」(`/reject` 必填 rejectReason) | -| MACHINE_REJECTED | 「覆盖通过」(`/override-approve`) — **不变** | -| APPROVED | **新增**「改为拒绝」按钮 → 必填理由弹窗 → `/revert {REJECTED, remark}` | -| REJECTED | **新增**「改为通过」按钮 → 必填理由弹窗 → `/revert {APPROVED, remark}` | -| PENDING_MODERATION | 无操作按钮(机审中) | - -### 详情展示 - -如果 `revertRemark` 非空,展示「最近一次反转备注:xxx(由 xxx 于 xxx 时间操作)」。审计字段 `auditedAt` / `auditorName` 现有接口已返回。 - ---- - -## ✅ 后端验证记录 - -### 本地 (gateway 8080, order-v2 8094) - -``` -[1] APPROVED→REJECTED code=200 DB: REJECTED + revert_remark 写入 -[2] REJECTED→APPROVED code=200 DB: APPROVED + revert_remark 更新 -[3] 缺 remark code=400 Bean Validation -[4] APPROVED→APPROVED code=551076 -[5] PENDING_MANUAL→APPROVED code=551076 -GET /admin/review/list 响应字段含 revertRemark -``` - -### 测试服 (api.test.1814.love:9443) - -``` -[1] APPROVED→REJECTED code=200 msg=成功 -[2] REJECTED→APPROVED code=200 msg=成功 -[3] APPROVED→APPROVED code=551076 msg=评价状态不允许反转,仅 APPROVED ↔ REJECTED 可互转 -[4] 缺 remark code=400 msg=反转备注不能为空(Bean Validation) -[5] GET /admin/review/list 响应字段含 revertRemark ✓ -``` - ---- - -## 🔒 业务规则细节 - -1. **反转不联动定制师评价**:产品评价反转时,**不会**自动同步 PENDING_MANUAL 状态的定制师评价(避免反向操作意外波及)。`/approve` 仍保留 cascadeApproveCustomizerReviews 联动逻辑。 -2. **精选评价缓存**:反转后清 `featuredReviewCache`,防止已拒绝的评价仍在精选中显示。 -3. **审计字段**:反转会更新 `auditorAdminId` / `auditorName` / `auditedAt` 为最新操作人,**不更新** `rejectReason`(语义保留)。 - ---- - -## 🗂️ Schema - -```sql -ALTER TABLE `order_review` -ADD COLUMN `revert_remark` VARCHAR(500) NULL COMMENT '终态反转备注(APPROVED↔REJECTED 互转时填)'; -``` - -Flyway: `V20260525_002__add_revert_remark_to_order_review.sql`,测试服已落库 success=1。 diff --git a/changelogs/2026-05/25_feat_review_source_dict_and_product_highlights.md b/changelogs/2026-05/25_feat_review_source_dict_and_product_highlights.md deleted file mode 100644 index fee7df0..0000000 --- a/changelogs/2026-05/25_feat_review_source_dict_and_product_highlights.md +++ /dev/null @@ -1,136 +0,0 @@ -# feat(评价): review_source 改为系统字典 + 产品详情精选评价补 source/sourceLabel - -> **类型**: feat (后端 + 前端均需改动) -> **关联 PR/Issue**: PR #2989 (Closes #2988) — 承接 #2978 (source 字段) + #2984 (reviewSummary 链路修) -> **日期**: 2026-05-25 -> **影响范围**: admin 端「评价审核」筛选区可改用通用字典接口 + `/mp/product/{id}` 精选评价新增 source 字段 -> **接收方**: mmg - ---- - -## 🎯 背景 - -承接两个已合 PR: -- **#2981 (source 字段)** — 加了 enum,前端要拉「来源」下拉必须硬编码两个选项 -- **#2984 (reviewSummary 链路修)** — 把 Map 改成强类型 DTO,但 DTO.Review 没加 source 字段,产品详情精选评价虽然有数据但拿不到来源 - -本次补两个尾巴。 - ---- - -## 📊 改动 1:`review_source` 系统字典 - -字典 type:`review_source` -字典 data 2 条: - -| dict_value | dict_label | sort_order | status | -|------------|-----------|------------|--------| -| MINIPROGRAM | 小程序 | 10 | ACTIVE | -| YOUZAN | 有赞 | 20 | ACTIVE | - -### admin 端使用 - -原本「来源」下拉前端要硬编码: -```js -const options = [{value:'MINIPROGRAM', label:'小程序'}, {value:'YOUZAN', label:'有赞'}] -``` - -现在可改用通用字典接口拉(与其他下拉一样的处理方式): -``` -GET /admin/dict/data/review_source -``` - -返回: -```json -{ - "code": 200, - "data": [ - {"dictValue":"MINIPROGRAM", "dictLabel":"小程序", "sortOrder":10, "status":"ACTIVE"}, - {"dictValue":"YOUZAN", "dictLabel":"有赞", "sortOrder":20, "status":"ACTIVE"} - ] -} -``` - -后端 `ReviewSourceEnum` 保留(代码层兜底),业务写值仍走 enum;字典只给前端下拉用。后续要加新来源(如美团/抖音)需要后端加 enum + 字典 INSERT 双改。 - ---- - -## 📊 改动 2:`/mp/product/{id}` reviewSummary.topReview 加 source - -之前 (`#2984` 修后) 返: -```json -"reviewSummary": { - "avgScore": 5.0, - "totalCount": 159, - "topReview": { - "reviewId": "...", - "nickname": "...", - "content": "...", - "score": 5.0, - "images": [...], - "likeCount": 12, - "reviewTime": "..." - } -} -``` - -本次后返(多 2 个字段): -```diff -"topReview": { - ... -+ "source": "MINIPROGRAM", -+ "sourceLabel": "小程序" -} -``` - -### 前端期望 - -小程序产品详情页的精选评价区,如果是有赞评价可以加角标(如「来自有赞」)。小程序评价默认就是「小程序」可不显示标识。 - ---- - -## ✅ 后端验证 - -### 本地 (gateway 8080) - -``` -GET /admin/dict/data/review_source → 2 条字典 -GET /mp/product/2045716022098264066(159 条评价) → topReview.source=MINIPROGRAM sourceLabel=小程序 -``` - -### 测试服 (api.test.1814.love:9443) - -``` -GET /admin/dict/data/review_source → 200, 2 条 - MINIPROGRAM / 小程序 - YOUZAN / 有赞 - -GET /mp/product/2045716022098264066 → 200 - reviewSummary.avgScore=5.0 totalCount=159 - reviewSummary.topReview.source=MINIPROGRAM sourceLabel=小程序 -``` - -rolling-deploy-all.sh 滚动部署 user-service / order-v2 / product-v2 共 ~3 分钟,Flyway V20260525_001 落库(测试服在本地启动时已落,部署时跳过 history.success=1)。 - ---- - -## 🗂️ Schema - -```sql -INSERT INTO sys_dict_type (dict_type_id, dict_name, dict_type, category, status, remark) VALUES - (10110, '评价来源', 'review_source', 'BUSINESS', 'ACTIVE', '与 ReviewSourceEnum 枚举一一对应'); - -INSERT INTO sys_dict_data (dict_data_id, dict_type, dict_label, dict_value, sort_order, status) VALUES - (101101, 'review_source', '小程序', 'MINIPROGRAM', 10, 'ACTIVE'), - (101102, 'review_source', '有赞', 'YOUZAN', 20, 'ACTIVE'); -``` - -Flyway `V20260525_001__add_review_source_dict.sql`(hl-user-service),`INSERT IGNORE` 幂等。 - ---- - -## 🔗 关联 - -- `25_feat_review_source_field.md` (#2981) — 评价表加 source 字段(本字典对应的 enum 出处) -- `25_fix_mp_product_review_summary_contract.md` (#2984) — reviewSummary 链路修(本次补 source 字段挂载点) -- `25_feat_review_revert_status_switch.md` (#2983) — 已通过↔已拒绝互转(独立功能,跟本次无直接关联) diff --git a/changelogs/2026-05/25_feat_review_source_field.md b/changelogs/2026-05/25_feat_review_source_field.md deleted file mode 100644 index 6cacf91..0000000 --- a/changelogs/2026-05/25_feat_review_source_field.md +++ /dev/null @@ -1,117 +0,0 @@ -# feat(评价): 评价列表/审核 admin 端新增「来源」列 + 筛选; 小程序评价 VO 新增 source 字段 - -> **类型**: feat (后端 + 前端均需改动) -> **关联 PR/Issue**: PR #2981 (Closes #2978) 已合 dev,测试服已部署 + API 真测通过 -> **日期**: 2026-05-25 -> **影响范围**: admin 端「评价审核」列表(`/admin/review/list`) + 小程序评价查询接口(`/mp/review/*`) -> **接收方**: mmg -> **前端**: **admin 端需要改造**(新增「来源」列 + 筛选下拉);小程序端按需展示 - ---- - -## 🎯 背景 - -业务侧需要区分评价的来源渠道。本期场景: - -- **MINIPROGRAM = 小程序**:客人在小程序提交的评价(已有的全部历史数据,新增评价默认这个) -- **YOUZAN = 有赞**:从有赞平台导入的评价(本期不做导入接口,wx 自行 INSERT/批量导入) - -后端字段已就绪,管理端展示 + 筛选需要前端配合。 - ---- - -## 📊 admin 端 `/admin/review/list` 改动 - -### 1. 响应每条评价新增 2 个字段 - -```diff -{ - "reviewId": 2058729444025028610, - "status": "APPROVED", - ..., -+ "source": "MINIPROGRAM", // 评价来源 code -+ "sourceLabel": "小程序" // 评价来源中文 -} -``` - -枚举值: - -| source | sourceLabel | -|--------|-------------| -| MINIPROGRAM | 小程序 | -| YOUZAN | 有赞 | - -### 2. 请求新增筛选入参 `source`(可选) - -``` -GET /admin/review/list?pageNo=1&pageSize=20&source=YOUZAN -GET /admin/review/list?pageNo=1&pageSize=20&source=MINIPROGRAM -``` - -不传 = 不按来源筛选(返回全部)。 - -### 3. 前端期望改造 - -- 列表表头加一列「来源」,内容直接渲染 `sourceLabel`(已是中文,无需前端再映射) -- 筛选区(截图中现有「评价状态 / 评价等级 / 图片/视频」那一行)加一个「来源」下拉,选项: - - 全部 (不传 source) - - 小程序 (source=MINIPROGRAM) - - 有赞 (source=YOUZAN) - ---- - -## 📊 小程序 `/mp/review/*` 改动 - -### 受影响接口 - -- `GET /mp/review/target?targetType=PRODUCT&targetId=...` -- `GET /mp/review/product/{productId}` - -### 响应每条评价新增 2 个字段(同 admin) - -```diff -{ - "reviewId": 2031394849190555650, - "userNickname": "xxx", - ..., -+ "source": "MINIPROGRAM", -+ "sourceLabel": "小程序" -} -``` - -### 前端期望 - -小程序端**是否展示**「来源」标识由 mmg 决定。如果展示,直接渲染 `sourceLabel`(有赞评价可加角标区分)。 - ---- - -## 🔬 业务规则 - -1. **小程序新建评价 `POST /mp/review/create`** → 后端自动写入 `source=MINIPROGRAM`,前端不需要传 -2. **有赞评价**本期不做导入接口,wx 自行 INSERT(`INSERT INTO order_review (..., source) VALUES (..., 'YOUZAN')`) -3. 历史所有评价已回填 `source=MINIPROGRAM` - ---- - -## ✅ 后端验证记录 - -### 本地 (gateway 8080) - -``` -POST /admin/auth/login → 200, token len=259 -GET /admin/review/list?pageNo=1&pageSize=2 → source/sourceLabel 字段就位 -GET /admin/review/list?source=YOUZAN → total=1 (手动 UPDATE 1 条测试) -GET /admin/review/list?source=MINIPROGRAM → total=446 -GET /mp/review/target?targetType=PRODUCT... → source/sourceLabel 透传 OK -``` - -### 测试服 (api.test.1814.love:9443) - -``` -POST /admin/auth/login → 200 -GET /admin/review/list?pageNo=1&pageSize=2 → source=MINIPROGRAM sourceLabel=小程序 ✓ -GET /admin/review/list?source=YOUZAN → total=0 (干净, 等 wx 导入) -GET /mp/review/target?targetType=PRODUCT... → source=MINIPROGRAM sourceLabel=小程序 ✓ -``` - -Flyway `V20260525_001__add_source_to_order_review.sql` 已落库,`source VARCHAR(32) NOT NULL DEFAULT 'MINIPROGRAM'` + `idx_source` 索引。 diff --git a/changelogs/2026-05/25_fix_deposit_ratio_include_single_room_surcharge.md b/changelogs/2026-05/25_fix_deposit_ratio_include_single_room_surcharge.md deleted file mode 100644 index 002f9fe..0000000 --- a/changelogs/2026-05/25_fix_deposit_ratio_include_single_room_surcharge.md +++ /dev/null @@ -1,57 +0,0 @@ -# fix(产品报价): 比例定金漏算单房差修复(定金值变化,接口契约不变,前端无需改动) - -> **类型**: fix(后端计算修正,接口字段/结构不变) -> **关联 PR/Issue**: PR #2995 (Closes #2994) -> **日期**: 2026-05-25 -> **影响范围**: 所有「按比例收定金」且触发单房差的产品报价/下单 -> **接收方**: mmg(知会即可) + QA -> **前端**: **无需改动**(depositAmount/balanceAmount 字段名与结构不变,仅取值修正) - ---- - -## 🎯 背景 - -核心产品按比例(如 10%)收定金时,定金漏算了单房差。 - -示例(成人价4000 + 儿童价3000 + 单房差1000 = 总价8000,定金比例10%): - -- 修复前:定金 = (8000 - 1000) × 10% = **700**(错误,基数减掉了单房差) -- 修复后:定金 = 8000 × 10% = **800**(正确,客户实付全款含单房差) - ---- - -## 🔧 根因 - -比例定金计算原先故意从基数中减掉单房差(代码注释标 D2,源自 PR #1901),与客户实付全款的口径不符。三处比例定金计算中只有一处已含单房差,另两处减掉了,行为不一致。本次统一为「比例定金按含单房差的总价计算」。 - ---- - -## ✅ 接口契约不变 - -| 接口 | 字段 | 变化 | -|------|------|------| -| `POST /mp/product/{id}/quote` | `depositAmount` / `balanceAmount` | 字段不变,**取值修正(定金变大、尾款变小)** | -| 下单接口(订单 `depositAmount`) | `depositAmount` | 同上 | - -**前端无需任何改动**。仅注意:比例定金 + 单房差场景下,展示的定金金额会比之前略高(原先少算了单房差对应的那部分定金),尾款相应减少,总价不变。 - ---- - -## ✅ 后端验证(测试服 e2e,真实产品 id=2056944461216100353) - -请求:date=2026-06-15,1成人+1儿童,定金比例 10% - -``` -GET /internal/product/{id}/simple-quote → totalPrice=8000.00, depositAmount=800.00 ✓ (订单创建链路) -POST /internal/mp/product/{id}/quote → grandTotal=8000.00, depositAmount=800.00, balanceAmount=7200.00 ✓ -``` - -修复前同场景定金为 700,现已修正为 800。单元测试 90 用例全绿。 - ---- - -## ⚠️ 不受影响 - -- 固定金额/人定金模式不受影响(仍按定金人头计,幼童不计定金) -- 全款模式不受影响 -- 不触发单房差(成人数 ≠ 1)的场景不受影响 diff --git a/changelogs/2026-05/25_fix_mp_product_review_summary_contract.md b/changelogs/2026-05/25_fix_mp_product_review_summary_contract.md deleted file mode 100644 index 35c2ab3..0000000 --- a/changelogs/2026-05/25_fix_mp_product_review_summary_contract.md +++ /dev/null @@ -1,89 +0,0 @@ -# fix(小程序): `/mp/product/{id}` 接口 `reviewSummary` 字段从今天起返真实数据(之前全是 null) - -> **类型**: fix (纯后端 contract 修复，前端**无需改动代码**，只是数据从 null 变成有值) -> **关联 PR/Issue**: PR #2984 (Closes #2980) 已合 dev，**测试服已部署 + API 真测通过** -> **正式服**: ⚠️ **本次未部署正式**，用户安排后续窗口再部 -> **日期**: 2026-05-25 -> **影响范围**: 小程序端产品详情页 `GET /mp/product/{productId}` 响应里的 `reviewSummary` 字段 -> **接收方**: mmg - ---- - -## 🎯 现象（修复前） - -小程序产品详情接口 `GET /mp/product/{id}` 返回的 `reviewSummary` 对象 4 个字段**全是 null**，不论该产品在 admin 评价审核里有多少条已通过评价： - -```json -"reviewSummary": { - "avgScore": null, - "totalCount": null, - "topReview": null, - "tags": null -} -``` - -测试服 + 正式服都一样。所有产品的"评价摘要"区从来没有真数据。 - -## 🩺 根因 - -后端两层 Feign 契约字段名对不上： -- `hl-product-service-v2` 的 `ReviewFeignClient` 声明返回 `ReviewSummaryVO`（字段 `avgScore/totalCount/topReview/tags`） -- 后端 `hl-order-service-v2.InternalReviewController.getProductHighlights` 实际返 `Map<String,Object>`（keys: `stats/topRatedReview/topLikedReview`） - -Jackson 反序列化 Map → ReviewSummaryVO 时无一字段名匹配，全部赋 null。 - -## ✅ 修复后 - -```json -"reviewSummary": { - "avgScore": 5.0, - "totalCount": 159, - "topReview": { - "reviewId": "17767518569310317", - "nickname": "汪***", - "avatarUrl": "https://wx.qlogo.cn/.../132", - "score": 5, - "content": "行程安排很舒服，避开了拥堵，人少景美，很美好的旅行会议！", - "images": [ - "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/review/2026/04/21/...jpg" - ], - "likeCount": 0, - "reviewTime": "2024-10-10T16:18:57" - }, - "tags": null -} -``` - -字段说明： -| 字段 | 类型 | 含义 | -|------|------|------| -| `avgScore` | BigDecimal | 整体评价平均分(1-5)；无评价时 0 | -| `totalCount` | Integer | 已通过评价总数；无评价时 0 | -| `topReview` | Object/null | 精选评价(优先取最高评分；与最高点赞同条时取最高点赞次条)；无评价时 null | -| `topReview.score` | Integer/BigDecimal | 该条评价的整体评分(1-5) | -| `topReview.reviewTime` | ISO 字符串 | 评价时间 | -| `tags` | null | 关键词标签 - 后端目前不输出，保留占位等后续(预计 6 月以后才上) | - -## 📋 前端要做的事 - -**理论上无需改动** — `ReviewSummaryVO` 这个 VO 的字段名/类型这次没动，前端原本按 null 处理的代码现在会直接拿到真值，自然展示出来。 - -⚠️ 唯一可能踩坑：之前因为后端永远返 null，部分前端代码可能写了「reviewSummary 没法用」的兜底（如直接隐藏评价区）。**请检查产品详情页是否有这类硬编码空逻辑**，确保后端有数据时能正常渲染。 - -## 🚀 部署状态 - -| 环境 | 状态 | 验证 | -|------|------|------| -| 测试服 | ✅ 已部署（order-v2 / product-v2 / mp 三服务） | 4 个产品(159/69/10/2 评价)逐一 curl 字段全对，DB 数据精确匹配 | -| 正式服 | ⏳ **未部署**，等用户安排窗口 | 待部署后由 wx curl 正式 `/mp/product/2055092537149804545`（已导入 172 条有赞迁移评价）验证 | - -## 🔍 不破坏的契约 - -mp-service 自身的 `/mp/review/product/{productId}/highlights` 接口（产品详情页的「精选评价区」）**对外字段结构未变**，三个顶层 key `topRatedReview / topLikedReview / stats` 全保留，子字段一个不少。这次只是后端内部把弱类型 `Map<String,Object>` 改成强类型 DTO，对前端透明。 - -## 📁 涉及后端模块（影响重启） - -- `hl-common-core`（新增共享 DTO `InternalProductReviewHighlightsDTO`） -- `hl-order-service-v2` -- `hl-product-service-v2` -- `hl-mp-service` diff --git a/changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md b/changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md deleted file mode 100644 index 6e2a6db..0000000 --- a/changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md +++ /dev/null @@ -1,94 +0,0 @@ -# notice(评价): /mp/product reviewSummary 全量字段契约 + 空数据态告知(前端按 totalCount 判空) - -> **类型**: notice(汇总告知,接口契约已稳定,本条不含新代码) -> **关联 PR**: #2984(reviewSummary 契约修复) + #2981(source 字段) + #2989(topReview 补 source/sourceLabel) + #2991(sourceLabel 字典化) -> **日期**: 2026-05-25 -> **影响接口**: `GET /mp/product/{id}` 的 `reviewSummary` 字段 -> **接收方**: mmg -> **前端**: **需调整空态判断逻辑(详见「前端必做」)** - ---- - -## 🎯 背景 - -此前 `/mp/product/{id}` 的 `reviewSummary` 4 个字段(avgScore/totalCount/topReview/tags)**恒为 null**(契约 bug,Feign 声明强类型但后端返 Map,字段名零匹配)。该问题已由 PR #2984 彻底修复:后端改强类型 DTO,Assembler 窄化为前端契约。 - -**现在 `reviewSummary` 已稳定返回结构化对象**。但「对象非 null」不等于「有评价」——产品没评价时返回的是零值对象,不是 null。这点前端务必区分(见下)。 - ---- - -## 📋 reviewSummary 字段契约 - -| 字段 | 类型 | 有评价 | 无评价 | -|------|------|--------|--------| -| `avgScore` | number | 平均分(如 5.0) | **0** | -| `totalCount` | int | 评价总数(如 159) | **0** | -| `topReview` | object \| null | 精选评价对象 | **null** | -| `tags` | string[] \| null | 当前后端暂未输出,恒 null | null | - -`topReview` 子字段(精选取 topRated 优先,缺则 topLiked): - -| 字段 | 说明 | -|------|------| -| `reviewId` | 评价ID | -| `nickname` / `avatarUrl` | 昵称 / 头像 | -| `score` | 评分(1-5) | -| `content` | 评价内容 | -| `images` | 图片数组(可空) | -| `likeCount` | 点赞数 | -| `reviewTime` | 评价时间 | -| `source` | 来源(MINIPROGRAM=小程序 / YOUZAN=有赞),字典 review_source | -| `sourceLabel` | 来源中文(小程序 / 有赞),运维改字典即时生效 | - ---- - -## ✅ 测试服实测(真实数据) - -**情形 1 — 有评价(数据正常)** - -产品 `2045716022098264066`「额吉的故乡V9·7天6晚旷野版」,159 条: - -```json -"reviewSummary": { - "avgScore": 5.0, - "totalCount": 159, - "topReview": { - "nickname": "汪***", "score": 5, - "content": "行程安排很舒服，避开了拥堵，人少景美…", - "images": ["…4张…"], - "source": "YOUZAN", "sourceLabel": "有赞" - }, - "tags": null -} -``` - -产品 `2045749044617084929`「额吉的故乡6天5晚」172 条,数据同样完整(avgScore=5.0、topReview 含内容+图片+来源)。 - -**情形 2 — 无评价(空态正常,非 bug)** - -产品 `2056966973370707970`,DB 实测 0 条评价(任何状态): - -```json -"reviewSummary": { - "avgScore": 0, - "totalCount": 0, - "topReview": null, - "tags": null -} -``` - ---- - -## ⚠️ 前端必做 - -1. **用 `totalCount === 0` 判空**,渲染「暂无评价」空态。**不要**因为 `reviewSummary` 非 null 就认为有评价。 -2. **`topReview` 可能为 null**(无评价产品),渲染前判空,勿直接取 `topReview.nickname` 等导致报错。 -3. **`avgScore` 空态为 0**,空态请隐藏评分,不要显示「0.0 分 / 0 星」误导用户。 -4. **`topReview` 新增 `source` / `sourceLabel`**,可在精选评价上展示来源标识(如「来自有赞」)。 -5. `tags` 当前恒 null,暂不要依赖。 - ---- - -## 🔧 部署状态 - -测试服 hl-order-service-v2 / hl-product-service-v2 均已部署最新 dev。有评价产品 reviewSummary 数据完整、无评价产品返零态,均已实测确认。 diff --git a/changelogs/2026-05/25_refactor_review_source_label_via_dict.md b/changelogs/2026-05/25_refactor_review_source_label_via_dict.md deleted file mode 100644 index e0e7a6e..0000000 --- a/changelogs/2026-05/25_refactor_review_source_label_via_dict.md +++ /dev/null @@ -1,85 +0,0 @@ -# refactor(评价): sourceLabel 彻底字典化(运维改字典 dict_label 接口立即反映) - -> **类型**: refactor(后端纯重构,接口契约不变,前端无需改动) -> **关联 PR/Issue**: PR #2991 (Closes #2990) — 承接 #2988 字典加数据 + #2989 enum 双写 -> **日期**: 2026-05-25 -> **影响范围**: admin / mp 所有返 `sourceLabel` 字段的评价接口 -> **接收方**: mmg(知会即可) -> **前端**: **无需改动** - ---- - -## 🎯 背景 - -#2988 在 sys_dict_data 加了 review_source 字典数据;#2989 后端 sourceLabel 仍由 `ReviewSourceEnum.labelOf()` 硬编码算出 — 字典数据"白加",改字典 dict_label 接口不变。 - -本次彻底字典化:删 enum 的 label 字段,sourceLabel 通过 `DictFeignClient.getDictDataByType("review_source")` 查字典动态获取。 - ---- - -## ✅ 接口契约不变 - -| 接口 | sourceLabel 取值 | 是否变化 | -|------|------------------|---------| -| `GET /admin/review/list` | 小程序 / 有赞 | 不变 | -| `GET /mp/review/target` | 小程序 / 有赞 | 不变 | -| `GET /mp/review/product/{id}` | 小程序 / 有赞 | 不变 | -| `GET /mp/product/{id}` reviewSummary.topReview | 小程序 / 有赞 | 不变 | - -**前端无需任何改动**。 - ---- - -## 🔧 运维能力增强(本次重构的真正价值) - -如果想把「小程序」改成「微信小程序」,运维在 admin 字典管理改字典 dict_label 即可,**所有接口立即反映**,无需后端重启或发版。 - -操作路径:admin 后台 → 系统管理 → 字典管理 → 找到 `review_source` 类型 → 编辑 dict_value=MINIPROGRAM 的 dict_label → 保存。 - -底层机制:admin 字典编辑接口会自动清 Redis 缓存 `cache:dict:data:review_source`,下次接口请求重新加载字典,sourceLabel 立即更新。 - ---- - -## ⚠️ 范围限定(项目惯例双标) - -本次只改 review_source。其他 label 字段(`reviewType` / `productType` 等已走字典,`statusLabel` / `levelLabel` / `targetTypeLabel` 等仍走 ReviewConstants 静态 Map 硬编码)**不动**。 - -如果要统一,需要另开工单批量改造(范围爆炸 5x + 性能/兼容性需重新评估)。 - ---- - -## ✅ 后端验证 - -### 本地(gateway 8080) - -``` -[默认] GET /admin/review/list?source=MINIPROGRAM → sourceLabel=小程序 -[UPDATE 字典 + 清 cache:dict:data:review_source] -[改字典后] 同接口 → sourceLabel=微信小程序 ✓ -[恢复 + 清缓存] -[恢复后] 同接口 → sourceLabel=小程序 ✓ -``` - -### 测试服(api.test.1814.love:9443) - -``` -[默认] GET /admin/review/list?source=MINIPROGRAM → sourceLabel=小程序 -[改字典 + 清测试服 Redis cache:dict:data:review_source] -[改字典后] 同接口 → sourceLabel=微信小程序 ✓ 动态生效 -[恢复 + 清缓存] -[恢复后] 同接口 → sourceLabel=小程序 ✓ -``` - -rolling-deploy hl-order-service-v2 1.5 分钟,双实例 UP。 - ---- - -## 🗃️ 文件改动 - -| 文件 | 改动 | -|------|------| -| `ReviewSourceEnum.java`(order-v2) | 删 label/code 字段、labelOf/fromCode 方法,enum 简化为裸值 | -| `ReviewDetailAssembler.java`(order-v2) | assembleMpList 加 loadDictLabels("review_source"),透传到 toMpReviewVO | -| `ReviewQueryService.java`(order-v2) | listReviews 同模式,toReviewListVO 加 sourceLabels 参数 | - -DTO/VO/Feign 链路自动透传,product-v2 / mp-service 无改动。 diff --git a/changelogs/2026-05/26_feat_login_response_is_customizer.md b/changelogs/2026-05/26_feat_login_response_is_customizer.md deleted file mode 100644 index e6130be..0000000 --- a/changelogs/2026-05/26_feat_login_response_is_customizer.md +++ /dev/null @@ -1,68 +0,0 @@ -# feat(登录): 小程序登录响应新增 isCustomizer + adminId 字段(后端用登录手机号校验定制师身份) - -> **类型**: feat(新增响应字段,向后兼容) -> **关联 PR**: #3023(isCustomizer,Closes #3022) + #3025(adminId,Closes #3024) -> **日期**: 2026-05-26 -> **影响接口**: `POST /mp/user/login`(微信登录) + `POST /mp/user/login/sms`(短信登录) -> **接收方**: mmg -> **前端**: **可选接入**(老逻辑不受影响,新字段按需使用) - ---- - -## 🎯 背景 - -登录成功后,前端需要知道「当前登录用户是不是定制师」,以决定是否展示「分享名片」等定制师专属入口;若是定制师,还需要其 `adminId` 来组装分享链接(`?adminId={adminId}`)。此前这两项都要登录后再额外调一次 `GET /mp/customizer/me` 才能拿到。现在**登录响应直接带上 `isCustomizer` + `adminId`**,省去这次额外请求。 - ---- - -## 📋 新增字段 - -两个登录接口的响应 `data` 中新增: - -| 字段 | 类型 | 说明 | -|------|------|------| -| `isCustomizer` | boolean | 当前登录用户是否为定制师。`true`=是,`false`=否 | -| `adminId` | string \| null | 定制师后台账号 ID(雪花,序列化为**字符串**)。`isCustomizer=true` 时有值;`false` 时为 `null` | - -**判定规则(后端)**:用本次登录的手机号精确匹配后台 `admin_user.mobile`,且该后台账号 `status=ACTIVE`、并持有 `CUSTOMIZER`(定制师)角色 —— 三者全满足才 `isCustomizer=true` 并返回对应 `adminId`。 - -**注意**:微信登录用户若未授权手机号(后端拿不到 phone),`isCustomizer=false` 且 `adminId=null`。 - ---- - -## 📦 响应示例 - -**命中定制师**: -```json -{ - "code": 200, "message": "成功", "success": true, - "data": { - "token": "...", "accessToken": "...", "refreshToken": "...", - "accessTokenExpiresIn": 15552000, "refreshTokenExpiresIn": 31536000, - "userId": "2059102607587143681", - "nickname": "用户0001", "avatar": null, "phone": "139****0001", - "isNewUser": false, "needProfile": false, - "isCustomizer": true, - "adminId": "1002" - } -} -``` - -**非定制师**:`"isCustomizer": false, "adminId": null`(其余字段不变)。 - ---- - -## ⚠️ 前端说明 - -1. `isCustomizer` / `adminId` 均为**新增字段,纯增量**,不影响任何已有字段,老前端无需改动即可继续工作。 -2. `adminId` 为**字符串**(雪花,已防 JS 精度丢失),前端直接当字符串用,勿转 number。 -3. 如需用「登录即知是否定制师 + adminId」省掉一次 `/mp/customizer/me`,可直接读 `data.isCustomizer` / `data.adminId`,组装分享链接 `?adminId={adminId}`。 -4. **登录响应只给布尔值 + adminId**;若还需要定制师的姓名 / 头像,继续用 `GET /mp/customizer/me`(返回 `isCustomizer` / `adminId` / `customizerName` / `customizerAvatar`)。`adminId` 两处口径一致。 - ---- - -## 🔧 部署状态 - -测试服 `hl-user-service` + `hl-mp-service` 已部署最新 dev(双实例滚动)。 -- 经测试服网关 `POST /mp/user/login/sms` 实测:普通手机号登录响应已返回 `isCustomizer: false` + `adminId: null`,字段已上线、序列化正常。 -- 命中定制师返 `isCustomizer: true` + `adminId: "1002"`(字符串)已在本地全链路(网关→mp→user)+ 单元测试覆盖验证。 diff --git a/changelogs/2026-05/26_feat_mp_custom_products_all_filter_by_customizer_adminid.md b/changelogs/2026-05/26_feat_mp_custom_products_all_filter_by_customizer_adminid.md deleted file mode 100644 index b98f2ee..0000000 --- a/changelogs/2026-05/26_feat_mp_custom_products_all_filter_by_customizer_adminid.md +++ /dev/null @@ -1,69 +0,0 @@ -# feat(C端定制): `/mp/custom/products/all` 改为按定制师过滤 —— 新增**必填** `adminId` - -> **类型**: feat(**接口契约变更,前端必须改**) -> **关联 PR**: #3037(已合并 dev) / **关联工单**: #3036 -> **日期**: 2026-05-26 -> **影响接口**: `GET /mp/custom/products/all` -> **接收方**: mmg -> **前端**: **必须改**(否则调用直接 400);已部署测试服并实测通过 - ---- - -## 🎯 变更内容 - -`/mp/custom/products/all` 原为「无登录浏览**全部**定制产品」,返回所有定制产品。 - -现改为「**只返回指定定制师本人创建的定制产品**」:接口**新增必填 query 参数 `adminId`**(定制师 ID),后端按 `产品.created_by = adminId` 过滤。 - -> 业务语义:这里的 `adminId` 就是定制师身份接口 `GET /mp/customizer/me` 返回的 `adminId`(与分享名片链接 `?adminId={adminId}` 用的是同一个值)。前端已在拿/存这个值,本接口直接带上即可。 - ---- - -## 📋 接口契约(变更后) - -### 请求 `GET /mp/custom/products/all` - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `adminId` | number(long) | **是(新增)** | 定制师 ID,只返回该定制师创建的定制产品;取自 `/mp/customizer/me` 的 `adminId` | -| `page` | number | 否 | 页码,默认 1,`<1` 纠正为 1 | -| `pageSize` | number | 否 | 每页条数,默认 20,上限 100 | - -### 响应 - -- 结构**不变**(仍是 `PageResult<定制产品列表项>`:`{ code, data: { records: [...], total, page, pageSize }, success }`)。 -- 仅是结果集从「全部」收窄为「该 `adminId` 创建的」。 - -### 示例 - -``` -GET /mp/custom/products/all?page=1&pageSize=20&adminId=1002 -→ 200 { code:200, data:{ total:3, records:[...3 条...] }, success:true } -``` - ---- - -## ⚠️ 前端需要做的事(Breaking) - -1. **调用本接口时必须带 `adminId`**:值取自 `GET /mp/customizer/me` 返回的 `data.adminId`。 -2. **不传 `adminId` 会直接报错**: - ```json - { "code": 400, "message": "缺少必要参数: adminId", "data": null, "success": false } - ``` - 原先「不带参数返回全部」的行为已**不存在**,请确认所有调用点都补上 `adminId`。 -3. 若页面语义是「查看某定制师的定制产品案例」,直接用该定制师的 `adminId`;若是「我(定制师本人)的定制产品」,用 `/mp/customizer/me` 返回的本人 `adminId`。 - ---- - -## ✅ 测试服验证(已通过) - -经测试服网关 `api.test.1814.love:9443` 实测: - -| 请求 | 结果 | -|------|------| -| `adminId=1002` | `total=3`(= 该定制师在库的有效定制产品数) | -| `adminId=1001` | `total=3` | -| `adminId=999999999`(不存在) | `total=0`,空列表 | -| 不传 `adminId` | `400 缺少必要参数: adminId` | - -软删除产品已被正确排除。 diff --git a/changelogs/2026-05/26_feat_order_payment_accept_adminid_share_binds_customizer.md b/changelogs/2026-05/26_feat_order_payment_accept_adminid_share_binds_customizer.md deleted file mode 100644 index 7564be4..0000000 --- a/changelogs/2026-05/26_feat_order_payment_accept_adminid_share_binds_customizer.md +++ /dev/null @@ -1,59 +0,0 @@ -# feat(下单/支付): 请求体 customizerId 接受 adminId 别名(分享下单绑定定制师全链路打通) - -> **类型**: feat(放宽入参 key,向后兼容) -> **关联 PR**: #3030(Closes #3028);绑定逻辑 Issue #1814 早已存在 -> **日期**: 2026-05-26 -> **影响接口**: `POST /mp/order/create`(下单) + `POST /mp/payment/prepay`(支付预下单) -> **接收方**: mmg -> **前端**: **可选**(原 `customizerId` 仍可用;现在也可直接传 `adminId`) - ---- - -## 🎯 背景 - -定制师把产品分享给 C 端用户(分享 URL 带 `?adminId=xxx`,以及登录响应 #3022/#3024 返回的 `adminId`),用户通过分享下单时,订单要绑定到该定制师。 - -后端绑定逻辑早已齐全(Issue #1814),但请求体读的字段名是 `customizerId`,与前端到处用的 `adminId` 不一致。本次让这两个接口的请求体**同时接受 `adminId` 这个 key**,前端直接传 `adminId` 即可绑定,不必再手动改名成 `customizerId`。 - ---- - -## 📋 字段说明 - -`POST /mp/order/create` 和 `POST /mp/payment/prepay` 的请求体: - -| key | 类型 | 说明 | -|-----|------|------| -| `adminId` 或 `customizerId`(二选一,等价) | number 或 **string** \| null | 分享来源定制师的 adminId。两个 key 后端都认(`adminId` 是 `customizerId` 的别名) | - -要点(⚠️ 此前本篇写「必须 number / 需 Number() 转换」是错的,已更正): -- **adminId 是雪花 ID,请用字符串传**(JS number 超过 2^53 会丢精度!)。后端按字符串精确解析为 Long、不丢精度。**不要在前端把它转成 number**。number 形式也接受(小 ID 无碍),但雪花一律走 string 才安全。 -- 选填。不传 / 传 null / 传 0 / 传无效或非定制师 → 不报错,走兜底分配(见下)。 -- 两个 key 都传时以 Jackson 解析为准(不要同时传,避免歧义)。 - ---- - -## 🔗 分享下单绑定定制师 — 完整行为(后端既有逻辑) - -下单时按以下优先级确定订单定制师: - -1. **显式 adminId/customizerId**(分享 URL 透传)→ 校验「该 admin 为 `ACTIVE` 且持 `CUSTOMIZER` 角色」→ 通过则锁定该定制师。 -2. 未传 adminId 但传了 `sharerOpenid` → 后端用 openid 反查定制师(openid → 手机号 → admin)→ 校验通过则锁定。 -3. 都没有 / 都无效 → 兜底:先取运营配置的默认定制师,没有再随机分配一名活跃定制师。 - -**支付预下单**(`/mp/payment/prepay`)同样接受 adminId:用户从不同定制师的分享链接进入再支付时,若传入的 adminId 校验通过且与订单当前定制师不同,会回写修正(漂移修正,Issue #1814)。 - ---- - -## ⚠️ 前端说明 - -1. 分享下单:把分享来源的 `adminId`(**字符串**,雪花)放进下单请求体的 `adminId`(或 `customizerId`)字段即可,后端自动校验 + 绑定。 -2. 校验不通过(非定制师 / 已禁用 / adminId 不存在)**不会让下单失败**,只是走兜底分配,前端无需特殊处理。 -3. 非分享场景不传该字段即可(别传空字符串 `""`;要么不传,要么传字符串形式的 adminId)。 - ---- - -## 🔧 部署状态 - -测试服 `hl-mp-service` 已部署最新 dev(双实例滚动)。 -- 经测试服网关实测:`POST /mp/order/create` body `{"adminId": -1}` 已能触发 `customizerId` 校验(证明 `adminId` 已被后端识别并映射),`{"customizerId": -1}` 同样生效(向后兼容)。 -- 别名映射 + 序列化不变(mp→order-v2 透传不受影响)已由单测覆盖。 diff --git a/changelogs/2026-05/26_notice_admin_login_token_expire_frontend_refresh.md b/changelogs/2026-05/26_notice_admin_login_token_expire_frontend_refresh.md deleted file mode 100644 index d80bfb5..0000000 --- a/changelogs/2026-05/26_notice_admin_login_token_expire_frontend_refresh.md +++ /dev/null @@ -1,91 +0,0 @@ -> # ⛔ 本篇已作废(结论有误,勿按此执行) -> 经浏览器实测复现 + 前后端源码/生产包核对,本篇两处关键结论都错了: -> ① 前端**早就接了 refresh 且生产已部署**(那次「零命中」是在落后 master 160 提交的过期本地代码上搜的); -> ② refresh **不轮转**(后端是滑动续期,串不变)。 -> 真正根因是**前端路由守卫与 refresh 续期的竞态**,详见同目录 -> **`26_notice_admin_relogin_REAL_root_cause_router_guard_refresh_race.md`**。 -> -> --- - -# ~~notice(后台登录): admin 登录态约 2 小时就过期 → 需前端接入 refresh 静默续期(根因排查结论)~~【作废,见上】 - -> **类型**: notice(后端无代码改动;双 token 机制后端早已就绪,缺前端接入) -> **关联 PR**: 无(后端不改);双 token 机制为工单 #2309 既有能力 -> **日期**: 2026-05-26 -> **影响接口**: `POST /admin/auth/login`(登录,已返回 refreshToken) + `POST /admin/auth/refresh`(刷新) -> **接收方**: mmg -> **前端**: **必须接入**(否则管理员每约 2 小时必被强制弹「登录已过期」一次) - ---- - -## 🎯 背景 / 现象 - -运营反馈正式后台管理端「登录状态老短时间就过期」,弹窗提示「登录已过期 / invalid token」,重新登录后用一会儿又掉。 - -经后端彻底排查(正式环境实测),结论如下: - -- admin 的 **access token 固定 2 小时过期**(绝对时间,不随操作滑动续期)。正式 nacos 未单独配置过期时长,走后端默认 7200 秒。 -- 后端**双 token 机制完整且正常**:登录已返回 `refreshToken`(有效期 30 天),`/admin/auth/refresh` 接口实测可正常用 refreshToken 换发新 access。 -- JWT 签名/验签、网关校验**均正常**,排除密钥/配置问题。 -- **唯一缺口在前端**:hl-ui 全量检索 `refreshToken` / `auth/refresh` **零命中** —— 前端登录后**没有保存 refreshToken,也没有任何静默续期逻辑**。access token 一过 2 小时,前端收到 401 就直接弹「登录已过期」让用户重新登录。 - -即:双 token 续期闭环的「后端发券」已就绪,「前端用券续期」这一段没做,导致 access 一过期只能重新登录。 - ---- - -## 📋 后端接口契约(已就绪,可直接接) - -### 1. 登录 `POST /admin/auth/login`(已存在,无变化) - -响应 `data` 字段(`AdminLoginResponse`): - -| 字段 | 类型 | 说明 | -|------|------|------| -| `token` | string | access token,有效期见 `accessTokenExpiresIn` | -| `refreshToken` | string | **刷新令牌,前端必须保存**(此前可能被前端忽略丢弃) | -| `accessTokenExpiresIn` | number | access 有效期**秒数**,当前 = `7200`(2 小时) | -| `refreshTokenExpiresIn` | number | refresh 有效期**秒数**,当前 = `2592000`(30 天) | -| `adminId` / `username` / `role` / `roleName` / `roles` / `avatar` / `mobile` 等 | - | 用户信息(不变) | - -### 2. 刷新 `POST /admin/auth/refresh`(换发新 access) - -- **无需 Authorization 头**(网关已放行该路径) -- 请求体: - -```json -{ "refreshToken": "登录时保存的 refreshToken" } -``` - -- 响应 `data` 结构**与登录响应完全一致**(同样是 `AdminLoginResponse`),其中: - - `token`:**新的 access token**(前端用它替换旧 access) - - `refreshToken`:**新的 refresh token —— 会轮换!与旧的不同,前端必须一并更新保存**(实测每次 refresh 都会返回新串,旧串随后失效) - - `accessTokenExpiresIn` / `refreshTokenExpiresIn`:同上 - -- 失败(refreshToken 过期 / 无效 / 已被新登录覆盖)时返回非 200 业务码,此时才真正需要跳登录页。 - ---- - -## ⚠️ 前端需要做的事 - -1. **保存 refreshToken**:登录成功后,把 `data.refreshToken` 与 access token 一起存起来(同 access 的存储介质)。 -2. **静默续期**(二选一或叠加): - - 方案 A(推荐,无感):根据 `accessTokenExpiresIn` 设定时器,在 access 临近过期(如剩余 5 分钟)时,后台静默调 `/admin/auth/refresh` 换新,**不打扰用户**。 - - 方案 B(兜底):在 axios 响应拦截器中,捕获 access 过期的 401(`Invalid token`),**先尝试用 refreshToken 调 `/admin/auth/refresh`**,成功则用新 access **重放原失败请求**;只有 refresh 也失败时,才走现有的「登录已过期」弹窗 + 跳登录页逻辑(`src/utils/request.js` 现有 401 分支)。 -3. **每次 refresh 后更新存储**:用返回的新 `token` 和新 `refreshToken` 覆盖旧值(refreshToken 会轮换,务必更新,否则下次续期会拿到失效的旧串)。 -4. **并发请求处理**:多个请求同时 401 时,只发起一次 refresh,其余请求挂起等新 token 后重放(避免重复刷新)。现有代码已有 `isHandling401` 单飞标志,可复用同样思路做 refresh 单飞。 -5. **登出 / refresh 失败**:清空 access + refreshToken,跳登录页(沿用现有逻辑)。 - ---- - -## 🔧 后端状态 - -- 后端**无需任何改动**,`/admin/auth/refresh` 与登录返回 refreshToken 均已在正式环境就绪并实测通过。 -- 如前端短期内无法接入,后端可作为**临时缓解**调大 access 有效期(改正式 nacos `admin-access-ttl-seconds` 并重启),但这会拉长 token 泄露窗口,**非长久之计**,正解仍是前端接入 refresh 续期。是否启用此临时方案由后端按需评估。 - ---- - -## ✅ 验证方式(前端接入后) - -1. 登录后等 access 过期(可临时把判定阈值调短便于测试),期间持续操作,应**全程无「登录已过期」弹窗**,网络面板可见自动发起的 `/admin/auth/refresh`。 -2. 手动篡改本地 access 为过期串发请求,应触发静默 refresh + 原请求重放成功。 -3. 把本地 refreshToken 也置为无效,再触发,应正常落到「登录已过期」弹窗 + 跳登录页。 diff --git a/changelogs/2026-05/26_notice_admin_relogin_REAL_root_cause_router_guard_refresh_race.md b/changelogs/2026-05/26_notice_admin_relogin_REAL_root_cause_router_guard_refresh_race.md deleted file mode 100644 index c2c452a..0000000 --- a/changelogs/2026-05/26_notice_admin_relogin_REAL_root_cause_router_guard_refresh_race.md +++ /dev/null @@ -1,79 +0,0 @@ -# notice(后台登录·更正): admin 反复掉登录真因 = 前端路由守卫与 refresh 续期的竞态(非「前端没接 refresh」) - -> **类型**: notice(根因更正 + 前端修复指引) -> **更正对象**: 作废本目录早前的 `26_notice_admin_login_token_expire_frontend_refresh.md`(那篇结论有误,见下) -> **日期**: 2026-05-26 -> **影响**: 正式后台 admin「登录态一天内反复过期 / 弹登录已过期」 -> **接收方**: mmg(前端修复) -> **后端**: 无需改代码;refresh 机制后端正常 - ---- - -## ⚠️ 先更正早前那篇结论(两处都错) - -早前那篇 notice 说「hl-ui 全量检索 refreshToken 零命中,前端没接 refresh,必须前端接入」+「refresh token 会轮换、旧串失效」。**这两条都是错的**: - -1. **前端早就接了 refresh,且生产已部署。** 那次「零命中」是在**落后 master 160 个提交的过期本地代码**上搜的。实际: - - 生产包 `admin.1814.love/assets/components-*.js` 实测含 `auth/refresh`(3 处)、`refreshAdminToken`(4 处)、`refreshToken`(11 处)、`accessTokenExpiresIn`。 - - 源码 `src/api/user.js` 有 `refreshAdminToken`、`src/stores/user.js` 有 `setTokens` + pinia 持久化、`src/utils/request.js` 有完整的 401→refresh→重放 + 并发单飞队列(`tryRefreshAndRetry` / `refreshWaitQueue`)。注释里明确写了 PR #2285 / #2312。 -2. **refresh 不轮转。** 后端是**滑动续期**(`TokenService.refreshAdminAccessToken`:refresh 串保持不变,只重置 Redis TTL,工单 #2309)。前端按「不轮转」实现是对的。 - -**所以根因不在「前端没接 refresh」。** 前端、后端的 refresh 单看都正常。 - ---- - -## 🎯 真正的根因:路由守卫在 refresh 续期窗口里把请求 abort 了 → 被当成鉴权失败 → logout - -`src/router/index.js` 的全局前置守卫 `beforeEach`: - -1. **每次路由跳转,第一件事就调 `clearAllPendingRequests()`** —— abort 掉所有在飞请求。 -2. 已登录但菜单未加载(刷新页面 / 切路由时 store 内存态重置)→ 进入 `initDynamicRoutes()` → `fetchMenuAndPermissions()` → 请求 `GET /admin/menu/my`。 -3. 此时若 access 已过期 → `menu/my` 收到 401 → `request.js` 的 `tryRefreshAndRetry` 发起 refresh(返回 200,新 token 没问题)→ 重放原请求。 -4. **竞态点**:在 refresh / 重放这个异步窗口里,守卫的重导航(`next({...to, replace:true})`)或并发的 bootstrap 流程**又触发了一次 `clearAllPendingRequests()`**,把守卫正在 `await` 的那个 `menu/my`(或并发的鉴权 bootstrap 请求)**abort 掉**。 -5. 被 abort 的请求 reject → `fetchMenuAndPermissions()` 抛异常 → `initDynamicRoutes()` 的 catch **不区分「请求被取消」和「真鉴权失败」,一律返回 `status:'error'`** → 守卫走 `await userStore.logout()` + `next({name:'Login', query:{redirect}})` → **跳登录页**。 - -**关键:refresh 本身成功了(网络面板能看到 `/admin/auth/refresh` 返 200),但守卫把它在等的请求掐断、当成鉴权失败,于是 logout。** 这就是「前端明明接了 refresh,却还是反复掉登录」的真相,**单设备、单会话就会发生**,不需要多端登录。 - -触发频率:access 每过期一次(正式默认 2 小时),用户下一次刷新页面 / 切路由就有概率命中这个竞态被踢 → 一天内 access 过期几次,就可能掉几次。 - ---- - -## 🧪 实测复现(测试服,把 admin access TTL 临时调成 120s) - -同样的「过期后导航 /dashboard」场景,**同条件下跑出两种相反结果,正好证明是竞态**: - -- **失败**那次:网络面板 `POST /admin/auth/refresh` 返 **200**,但页面仍跳到 `/login?redirect=/dashboard`(被踢)。 -- **成功**那次:`menu/my`(401)→ `auth/refresh`(200)→ `menu/my` 重放(200)→ 留在 /dashboard,无感续期。 - -两者唯一差别是 abort 与重放的先后时序 → 竞态确诊。 - ---- - -## ✅ 解决办法(前端 mmg,任选,建议 1+2 一起) - -**1.(必做,最小修复)守卫/续期路径不要把「请求被取消」当鉴权失败。** -在 `initDynamicRoutes()` / `fetchMenuAndPermissions()` 的 catch 里,识别 Axios 取消错误(`axios.isCancel(err)` 或 `err.code === 'ERR_CANCELED'` / `err.name === 'CanceledError'`),**取消 ≠ 鉴权失败**:取消时不要 `logout()`,而是当作可重试(后续那次导航会自然重跑守卫),或直接放行重试。这一条就能斩断「abort → logout」的链路。 - -**2.(建议)守卫的 bootstrap 请求在续期窗口内免疫 `clearAllPendingRequests()`。** -项目已有「受保护请求」机制(`isProtectedRequest`)。把守卫初始化阶段必需的 `GET /admin/menu/my` 等鉴权 bootstrap 请求标记为受保护,使其不被路由跳转的 `clearAllPendingRequests()` abort;或在 `isRefreshing` 为真(refresh 在飞)期间不执行 abort。 - -**3.(可叠加)守卫先 await refresh 单飞再判定。** -若检测到 `isRefreshing`(或本次导航触发了 401→refresh),守卫等 refresh 单飞结束、用新 token 重放成功后再决定 `next`,避免在续期未完成时就判 error→logout。 - -> 反模式:`initDynamicRoutes` 的 catch 目前对**任何** error(含 AbortError/CanceledError)都返回 `status:'error'` → 守卫 logout。这是把「良性的请求取消」误判成「登录失效」的根。 - ---- - -## 🔍 前端自测方式(可把 access TTL 调短便于复现) - -1. 登录后等 access 过期(测试服现已临时设 120s),期间反复**刷新页面 / 切菜单**多次。 -2. 现状:有概率跳登录页,且网络面板能看到该次 `/admin/auth/refresh` 其实返 200(说明续期成功但仍被踢)。 -3. 修复后:全程无「登录已过期」,网络面板可见自动 `/admin/auth/refresh` + 原请求重放,稳定留在当前页(多刷几十次不掉)。 - ---- - -## 🔧 后端侧说明 - -- 后端 refresh 机制(`/admin/auth/refresh` + 登录返回 refreshToken + 滑动续期)实测正常,**无需改动**。 -- 测试服 admin access TTL 已临时调为 **120s** 便于前端复现(`hl-user-service-test.yml` 里带 `[TEMP]` 注释的块),前端验证完成后后端会恢复为默认 7200s。 -- 如前端修复需要时间,后端可临时调大 access TTL 作缓解(治标不治本),按需评估。 diff --git a/changelogs/2026-05/27_notice_mp_customizer_identity_login_field_frontend_render.md b/changelogs/2026-05/27_notice_mp_customizer_identity_login_field_frontend_render.md deleted file mode 100644 index 961c2a3..0000000 --- a/changelogs/2026-05/27_notice_mp_customizer_identity_login_field_frontend_render.md +++ /dev/null @@ -1,66 +0,0 @@ -# notice(C端定制师): 登录后"看不到定制师身份/分享名片"——后端正式已验证正常,请前端接入 `isCustomizer`/`adminId` 字段渲染 - -> **类型**: notice(**后端无代码改动**;字段早已上线并部署正式,缺前端读取/渲染) -> **接收方**: mmg -> **日期**: 2026-05-27 -> **相关接口**: `POST /mp/user/login`、`POST /mp/user/login/sms`、`GET /mp/customizer/me` -> **相关历史**: 见同目录 `26_feat_login_response_is_customizer.md`(登录响应新增 isCustomizer/adminId 的字段说明) - ---- - -## 🐞 反馈现象 - -用户用手机号 `185****2756` 登录微信小程序后,**看不到自己是定制师**(无"分享名片"等定制师入口)。 - -## ✅ 后端排查结论:后端 100% 正常,且正式环境已部署该能力 - -已在**正式环境**端到端核实(非本地、非测试服): - -1. **数据层**(正式 RDS `hl_user_service`)该手机号三项判定**全部满足**: - - C端 `user`:存在该手机号用户(昵称 王骁) - - 后台 `admin_user`:同号、`status=ACTIVE`、username=wx - - 角色:该后台账号**持有 `CUSTOMIZER`(定制师)角色** -2. **接口实测**:正式内部接口 `/internal/user/customizer/by-userid` 实时返回该用户的定制师身份(`adminId` / `realName=王骁`),即 `GET /mp/customizer/me` 对该账号**会返回 `isCustomizer=true`**。 -3. **登录响应字段已部署正式**:正式 pod 内 `hl-user-service` 的 `LoginResponse.class`、`hl-mp-service` 的 `MpUserLoginRespVO.class` 均**已含 `isCustomizer` + `adminId`** 字段;登录服务在微信登录/短信登录两条路径都会用登录手机号反查并赋值。 - -**结论:该账号登录正式小程序时,后端登录响应必然返回 `isCustomizer: true` + `adminId: "2029379128804773890"`;`/mp/customizer/me` 同样返回 `isCustomizer: true`。后端无 bug。** - ---- - -## 📋 前端可用的两个数据来源(二选一,字段口径一致) - -### 来源 A:登录响应(推荐,省一次请求) - -`POST /mp/user/login`(微信登录)/ `POST /mp/user/login/sms`(短信登录)响应 `data` 中: - -| 字段 | 类型 | 说明 | -|------|------|------| -| `isCustomizer` | boolean | 当前登录用户是否为定制师。`true`=是 | -| `adminId` | string \| null | 定制师后台账号 ID(雪花,**字符串**)。`isCustomizer=false` 时为 `null` | - -### 来源 B:`GET /mp/customizer/me`(需登录态) - -| 字段 | 类型 | 说明 | -|------|------|------| -| `isCustomizer` | boolean | 同上 | -| `adminId` | string \| null | 同上 | -| `customizerName` | string | 定制师展示名(如"王骁") | -| `customizerAvatar` | string \| null | 定制师头像 URL | - ---- - -## 🔧 请前端自查(问题大概率在这三点之一) - -1. **是否读取了字段**:登录成功后是否取了 `data.isCustomizer` / `data.adminId`?或登录后是否调用了 `GET /mp/customizer/me`? -2. **是否据此渲染入口**:`isCustomizer=true` 时是否在「我的」页渲染"分享名片"入口? -3. **`adminId` 当字符串用**:`adminId` 是雪花字符串(后端已防 JS 精度丢失),**勿 `Number()` 转换**,否则拼分享链接 `?adminId=` 会精度错位。 - -**可复现账号**:手机号 `185****2756`(即反馈人本机号),登录后 `data.isCustomizer` 必为 `true`。 - ---- - -## ⚠️ 重要范围澄清(避免理解偏差) - -- 小程序里"定制师身份"这套能力(工单 #2907)**只用于点亮「分享名片」入口**,**不存在**"你是定制师"的身份徽章,也**没有定制师工作台**。 -- 小程序是纯 **C 端(顾客端)**;定制师真正的后台操作在**管理后台 `admin.1814.love`**。 -- 微信登录若用户**未授权手机号**(后端拿不到 phone),`isCustomizer=false`、`adminId=null` 属正常。 diff --git a/changelogs/2026-05/28_feat_admin_product_reorder.md b/changelogs/2026-05/28_feat_admin_product_reorder.md deleted file mode 100644 index e309558..0000000 --- a/changelogs/2026-05/28_feat_admin_product_reorder.md +++ /dev/null @@ -1,74 +0,0 @@ -# 【前端·后台】主题下版本(产品)拖拽排序 — 新增批量重排接口 - -> **类型**: 新增后端接口(feat,后端已改并部署测试服验证通过) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-28 -> **影响范围**: 后台「版本列表」页(主题下的版本/产品列表) -> **归属**: 后端已交付(PR #3218 → dev,#3220 同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3215 - ---- - -## 一、背景 - -后台「版本列表」(一个主题/产品线下挂的多个版本)需要支持人工排序。 - -后端核查:`product.sort_order` 字段早已存在,且**管理端列表与小程序端列表本来就按 `sort_order` 升序排序**——缺的只是「设置顺序」的入口(此前 sortOrder 恒为默认 0,无处可改)。本次补上批量重排接口,前端做拖拽 UI 即可。 - -## 二、新增接口 - -``` -POST /admin/product/item/reorder -``` - -请求体(把拖动后的目标顺序**全量**提交): - -```json -{ - "lineId": 2045004175602868226, - "items": [ - { "productId": 1001, "sortOrder": 1 }, - { "productId": 1002, "sortOrder": 2 }, - { "productId": 1003, "sortOrder": 3 } - ] -} -``` - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| lineId | Long | 是 | 主题(产品线)ID | -| items | 数组 | 是 | 重排清单,须覆盖该主题下当前列表所见的**全部**版本 | -| items[].productId | Long | 是 | 版本(产品)ID | -| items[].sortOrder | Integer | 是 | 新排序号,**越小越靠前**;取值必须是 1..N 连续无重(N=版本数) | - -成功响应:`{ "code": 200, "message": "版本排序成功" }` - -## 三、前端接入要点 - -1. **全量提交**:用户拖完后,把该主题下当前列表里所有版本按新的可视顺序,依次赋 `sortOrder = 1, 2, 3, ... N` 一次性提交(不是只提交被移动的那一个)。 -2. **生效范围**:重排后,后台「版本列表」和小程序端「该主题下产品列表」都会按新顺序展示(两端同一个 sort_order)。 -3. **排序号规则**:`sortOrder` 必须是 `1..N` 连续不重复。前端按可视位置生成 1..N 即可,不要传 0、不要跳号、不要重复。 -4. **数据权限**:`items` 须与当前列表接口(`GET /admin/product/item/list?lineId=...`)返回的版本集合一致(超管看全部;非超管下 CUSTOM 只看本人)。简单做法:重排清单直接取列表接口当前返回的那批 productId。 -5. **防连点**:接口有 5 秒幂等窗口,同一用户 5 秒内重复提交会返回 `100502 请勿重复提交`,正常拖拽保存无影响。 - -## 四、错误码 - -| code | 含义 | 触发 | -|------|------|------| -| 430203 | 重排清单与该主题下版本不匹配,请刷新页面后重试 | items 数量/productId 集合与该主题下可见版本不一致(漏传、多传、外来或不可见 productId、重复 productId) | -| 430204 | 排序号必须为 1..N 连续无重 | sortOrder 出现重复、跳号、超出 [1,N] | -| 400 | sortOrder 必须 >= 1 | 传了 sortOrder < 1(参数校验) | -| 100502 | 请勿重复提交 | 5 秒内重复提交 | - -## 五、测试服实测(主题 2056938045633904642,4 个版本) - -``` -POST /admin/product/item/reorder {lineId, items:[P1->4,P2->3,P3->2,P4->1]} -→ 200 版本排序成功 -GET /admin/product/item/list?lineId=2056938045633904642 -→ 列表顺序由 P1,P2,P3,P4 翻转为 P4,P3,P2,P1(sortOrder 1,2,3,4) -（异常路径 430203 / 430204 / 400 / 100502 均已验证;测试数据已恢复原序） -``` - -如对入参格式、错误提示文案有调整需求,告诉后端即可改。 diff --git a/changelogs/2026-05/28_feat_admin_profile_edit_mobile.md b/changelogs/2026-05/28_feat_admin_profile_edit_mobile.md deleted file mode 100644 index d59802e..0000000 --- a/changelogs/2026-05/28_feat_admin_profile_edit_mobile.md +++ /dev/null @@ -1,57 +0,0 @@ -# admin 个人中心: 可修改本人手机号 - -> **服务**: hl-user-service (8081) -> **PR**: #3198 -> **Issue**: #3196 -> **日期**: 2026-05-28 -> **影响范围**: admin 个人中心(/profile)「编辑资料」表单 + 手机号展示 -> **测试服验证**: 已过(api.test.1814.love:9443 + 真 admin token) - ---- - -## ⚠️ 关键变化 - -admin 个人中心现在可以修改本人手机号(admin_user.mobile)。 -- 之前个人中心手机号只取企微 wechat_user.mobile,无企微的管理员(如超管)显示"-"且无法维护。 -- 现在:`GET /admin/profile/me` 的 `phone` **优先返回 admin_user.mobile**(为空再回落企微);`PUT /admin/profile/me` 新增 `mobile` 字段可改。 - ---- - -## 一、接口变更 - -### 1. 获取个人资料 `GET /admin/profile/me` - -`ProfileVO.phone` 取值改为:**admin_user.mobile 优先**,为空回落企微 wechat_user.mobile。无任何字段增减,仅 phone 来源调整。 - -### 2. 保存个人资料 `PUT /admin/profile/me` - -**VO**: `UpdateDesignerProfileRequest` 新增字段: - -| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------|------| -| mobile | Body | string | 否 | `^1[3-9]\d{9}$` | 本人手机号。**留空/不传 = 不改(不会清空原值)**;格式非法返 `code=400 手机号格式不正确`;与他人重复返 `ADMIN_MOBILE_DUPLICATED` | - -行为: -- 提供且与当前不同 → 唯一性校验通过后更新 admin_user.mobile。 -- 留空/null → 保持原值不动。 -- 所有角色(不止定制师)都能改自己的 mobile;定制师专属字段逻辑不变。 - ---- - -## 二、前端改动（mmg） - -1. 个人中心「编辑资料」弹窗/表单**新增「手机号」输入框**,提交时 body 带 `mobile`。 -2. 前端做 11 位手机号格式校验(`^1[3-9]\d{9}$`),与后端一致。 -3. 个人中心手机号展示:原显示"-"处,现会返回实际 mobile(GET 的 `phone` 字段),正常展示即可。 -4. 错误处理:重复手机号 → 后端返 `ADMIN_MOBILE_DUPLICATED`(提示"手机号已被占用"之类);格式非法 → `code=400`。 - ---- - -## 三、备注 - -- 安全:沿用现有 admin 建/改手机号约定 —— **仅唯一性校验,不需短信验证码**(与后台新增/编辑管理员一致)。如后续要求改号需短信验证新号,另行评估。 -- 2FA 走企微扫码,与手机号无关,不受影响。 -- 短信登录(若启用)用 mobile 精确匹配,改号后自然用新号(登录逻辑不变)。 - -## 四、测试服验证(已过) -- GET 返回本人 mobile;PUT mobile=13800138000 → 回读成功;格式非法 12345 → `400 手机号格式不正确` 且不覆盖原值;留空不清空。(测试数据已还原) diff --git a/changelogs/2026-05/28_feat_early_bird_copy_applicable_traveler_types_on_detail.md b/changelogs/2026-05/28_feat_early_bird_copy_applicable_traveler_types_on_detail.md deleted file mode 100644 index a641429..0000000 --- a/changelogs/2026-05/28_feat_early_bird_copy_applicable_traveler_types_on_detail.md +++ /dev/null @@ -1,37 +0,0 @@ -# 早鸟优惠文案: 产品详情阶梯 + 订单详情早鸟行体现「适用人群」 - -> **服务**: hl-order-service-v2 (8084) / hl-product-service-v2 (8083) -> **PR**: #3187 -> **Issue**: #3182(承接 #3166 早鸟每方案可配适用人群) -> **日期**: 2026-05-28 -> **影响范围**: 小程序「产品详情」早鸟阶梯 + 「订单详情」早鸟折扣行文案 -> **测试服验证**: 已过(api.test.1814.love:9443) - ---- - -## ⚠️ 关键变化 - -早鸟优惠每方案可配「适用人群」(#3166)后,C 端两处文案补上适用人群,避免"每人立减100元"但幼童实际不享受的歧义。沿用既有约定:**后端拼好中文文案,前端直接展示**。 - -### 1. 产品详情早鸟阶梯(`MpProductDetailRespVO.earlyBirdLadder` 的每项)新增 2 字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| applicableTravelerTypes | `string[]` | 适用人群编码(如 `["ADULT","CHILD","YOUNG_CHILD"]`),后端保证非空(默认成人+儿童+小童,排除幼童)| -| applicableTravelerTypesText | `string` | 适用人群中文文案(如 `成人/儿童/小童`),可直接展示 | - -阶梯项现有 `peopleRangeText`("3-5 人")/`discountText`("每人立减 100 元")不变,前端在其旁展示 `applicableTravelerTypesText` 即可。 - -### 2. 订单详情早鸟折扣行 - -早鸟折扣行 `description`(=`order_discount.discount_name`)在创建订单时拼上适用人群后缀:`早鸟优惠:春季早鸟9折(适用人群:成人/儿童/小童)`。**仅新订单生效,老订单不变。** 同一文案也回显在 `earlyBirdPlanName` 字段(该字段原本就等于 discountName、含"早鸟优惠:"前缀,既有行为)。前端订单详情早鸟行直接展示 description,无需改动。 - ---- - -## 前端改动建议（mmg） - -1. **产品详情早鸟阶梯**:每个阶梯项展示 `applicableTravelerTypesText`(如在 discountText 旁加"(适用人群:成人/儿童/小童)"或单独标签)。 -2. **订单详情早鸟行**:description 已自带适用人群后缀,通常无需改;若之前对 discountName 做过裁剪/正则,注意新后缀。 - -## 测试服验证(已过) -建早鸟方案(适用人群=成人/儿童,挂某产品)→ `GET /mp/product/{id}` 的 `earlyBirdLadder` 返 `applicableTravelerTypesText=成人/儿童`、`discountText=每人立减 50 元`。订单详情后缀由后端创建时落库(单测覆盖,新订单生效)。 diff --git a/changelogs/2026-05/28_feat_early_bird_per_plan_applicable_traveler_types.md b/changelogs/2026-05/28_feat_early_bird_per_plan_applicable_traveler_types.md deleted file mode 100644 index 3a70a56..0000000 --- a/changelogs/2026-05/28_feat_early_bird_per_plan_applicable_traveler_types.md +++ /dev/null @@ -1,92 +0,0 @@ -# 早鸟优惠: 每个方案可配「适用人群」(成人/儿童/小童/幼童) - -> **服务**: hl-order-service-v2 (8084) -> **PR**: #3162 #3169 -> **Issue**: #3161 #3166 -> **日期**: 2026-05-28 -> **影响范围**: 管理端「早鸟方案」编辑页 —— 新增「适用人群」多选;早鸟人数口径变更 - ---- - -## ⚠️ 关键变化 - -- 早鸟方案新增「适用人群」配置(成人 ADULT / 儿童 CHILD / 小童 YOUNG_CHILD / 幼童 BABY)。 -- 该配置决定**哪几类出行人计入本方案的早鸟人数**(用于阶梯人数匹配 minPeople/maxPeople)**以及享受每人立减**。 -- **默认排除幼童(BABY)**:不填 / 留空时后端默认 `成人+儿童+小童`,存量方案迁移后也是这个默认。 -- 不同方案可配不同人群(A 方案只算成人、B 方案算成人+儿童+小童 …),互不影响。 -- **前端需在「早鸟方案」新增/编辑表单加一个「适用人群」多选框**(取值用 `traveler_type` 字典:成人/儿童/小童/幼童),不传 = 后端按默认处理。 - ---- - -## 一、背景 - -此前早鸟人数是「全员计入」,后调整为「幼童不参与早鸟」(全局写死)。现进一步升级:**由每个方案自行配置适用人群**,满足不同早鸟活动覆盖不同人群的需要。后端为纯人数口径变更,无金额/字段类型破坏性改动。 - ---- - -## 二、变更接口清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 新增早鸟方案 | POST | `/admin/order/early-bird` | 请求体新增字段 | `applicableTravelerTypes` | -| 2 | 修改早鸟方案 | PUT | `/admin/order/early-bird/{planId}` | 请求体新增字段 | 同上 | -| 3 | 早鸟方案详情 | GET | `/admin/order/early-bird/{planId}` | 响应新增字段 | 回显 codes + 中文文案 | -| 4 | 早鸟方案列表 | GET | `/admin/order/early-bird` (或 `/list`) | 响应新增字段 | 同上,每条 | - ---- - -## 三、接口详情 - -### 1/2. 新增 / 修改早鸟方案 `POST|PUT /admin/order/early-bird[/{planId}]` - -**VO**: `EarlyBirdPlanSaveReqVO` - -#### 入参(仅列新增字段,其余字段不变) - -| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | -|------|------|------|------|------|------| -| applicableTravelerTypes | Body | `string[]` | 否 | 每项 ∈ `ADULT/CHILD/YOUNG_CHILD/BABY` | 适用人群。**空 / 不传 → 默认 `["ADULT","CHILD","YOUNG_CHILD"]`(排除幼童)**。含非法值返回错误码 `585009` | - -请求示例: - -```json -{ - "planName": "暑期早鸟", - "discountType": "AMOUNT_PER_PERSON", - "discountAmount": 100, - "minPeople": 2, - "maxPeople": 10, - "startDate": "2026-06-01", - "endDate": "2026-08-31", - "productIds": [123, 456], - "applicableTravelerTypes": ["ADULT", "CHILD", "YOUNG_CHILD"] -} -``` - -### 3/4. 早鸟方案详情 / 列表 `GET /admin/order/early-bird[/{planId}]` - -**VO**: `EarlyBirdPlanVO`(新增 2 字段) - -| 字段 | 类型 | 说明 | -|------|------|------| -| applicableTravelerTypes | `string[]` | 适用人群 code 列表(如 `["ADULT","CHILD","YOUNG_CHILD"]`)。后端保证非空(存量/历史方案回显默认值) | -| applicableTravelerTypesText | `string` | 适用人群中文文案,`/` 分隔(如 `成人/儿童/小童`),可直接展示 | - ---- - -## 四、前端改动建议 - -1. 「早鸟方案」新增/编辑弹窗加一个「适用人群」多选(checkbox / multi-select),选项取 `traveler_type` 字典(成人 ADULT / 儿童 CHILD / 小童 YOUNG_CHILD / 幼童 BABY)。 -2. 默认勾选 `成人 / 儿童 / 小童`(对齐后端默认,排除幼童);允许全不选时不传该字段(后端按默认)。 -3. 列表/详情可直接展示 `applicableTravelerTypesText`。 -4. 旧前端不传该字段时行为不变(后端默认排除幼童),可分批升级,无强制。 - ---- - -## 五、测试服验证(已通过) - -经网关 `api.test.1814.love:9443` + 真 admin token 实测: -- 含幼童 `[ADULT,CHILD,YOUNG_CHILD,BABY]` 创建 + 回读持久化 + 文案「成人/儿童/小童/幼童」✓ -- 空列表 → 默认 `[ADULT,CHILD,YOUNG_CHILD]` + 「成人/儿童/小童」✓ -- 仅 `[ADULT]` → 「成人」✓ -- 非法值 `[FOO]` → 错误码 `585009` ✓ diff --git a/changelogs/2026-05/28_feat_home_screen2_card_link_type_product_line.md b/changelogs/2026-05/28_feat_home_screen2_card_link_type_product_line.md deleted file mode 100644 index 3a44a1a..0000000 --- a/changelogs/2026-05/28_feat_home_screen2_card_link_type_product_line.md +++ /dev/null @@ -1,51 +0,0 @@ -# 首页第二屏主题卡片: 跳转类型新增「产品主题」(linkTargetId=产品线id) - -> **服务**: hl-user-service (8081) -> **PR**: #3185 -> **Issue**: #3181 -> **日期**: 2026-05-28 -> **影响范围**: admin「小程序配置 → 首页配置 → 首页第二屏」主题卡片编辑 + 小程序首页第二屏卡片跳转 -> **测试服验证**: 已过(api.test.1814.love:9443 + 真 admin token) - ---- - -## ⚠️ 关键变化 - -主题卡片「跳转类型」(字典 `theme_card_link_type`)新增一项 **「产品主题」= `PRODUCT_LINE`**。选它时卡片 `linkTargetId` 保存为**产品线 id(lineId,产品线=主题)**,点卡片跳产品线详情。 - -字典现有全部取值: - -| dictValue | dictLabel | linkTargetId 含义 | -|-----------|-----------|-------------------| -| SEASON | 季节之旅 | 无 | -| CORE_LIST | 核心产品 | 无 | -| MENGMA | 亲子游学 | 无 | -| PRODUCT | 指定产品 | 产品 id（需配 linkTargetType=CORE/GROUP）| -| **PRODUCT_LINE** | **产品主题** | **产品线 id（lineId）** | - ---- - -## 一、admin 端前端改动（mmg） - -1. 主题卡片「跳转类型」下拉新增「产品主题」选项(字典 `theme_card_link_type` 已加 PRODUCT_LINE,前端读字典即有)。 -2. 选「产品主题」后,弹「产品线选择器」:调 **`GET /admin/product/line/simple-list`**(已存在,返回 `[{lineId, name}]`)填充,用户选产品线后把 `lineId` 写入卡片 `linkTargetId`。 -3. **不要传 `linkTargetType`**(产品线无 CORE/GROUP 之分,后端会强制置 null);PRODUCT 类型才需 linkTargetType。 -4. 保存接口不变:`PUT /admin/home-config/brand-story`,卡片体 `{title, subtitle, coverUrl, linkType:"PRODUCT_LINE", linkTargetId:<lineId>}`。 -5. 校验:linkTargetId 必填且须为存在且 ACTIVE 的产品线,否则后端返错误码 `220810`(目标产品线不存在或已删除)/`220811`(校验失败)。 - -## 二、小程序端前端改动（mmg） - -首页第二屏卡片点击跳转:`linkType=PRODUCT_LINE` 时,后端 `linkUrl` 恒为 null,前端按 `linkTargetId`(=lineId)跳**产品线详情页**(同 PRODUCT 类型由前端按 id 自拼路由的现有约定)。 - -## 三、接口（无破坏,均已上线） - -| 接口 | 方法 | 路径 | 变化 | -|------|------|------|------| -| 保存品牌故事 | PUT | `/admin/home-config/brand-story` | 卡片 linkType 接受 PRODUCT_LINE;PRODUCT_LINE 时 linkTargetId=产品线id,linkTargetType 强制 null | -| 品牌故事详情 | GET | `/admin/home-config/brand-story` | 卡片回显 linkType/linkTargetId(PRODUCT_LINE 时 linkTargetId=lineId)| -| mp 首页第二屏 | GET | `/mp/home-config/screen2` | PRODUCT_LINE 卡片 linkUrl=null,前端按 linkTargetId 拼产品线详情 | -| 产品线下拉 | GET | `/admin/product/line/simple-list` | (已存在)admin 选产品线用 | - -## 四、测试服验证(已过) -- 字典 `theme_card_link_type` 已含 `PRODUCT_LINE「产品主题」`。 -- admin 存草稿:linkType=PRODUCT_LINE + 非法产品线 id → `220810` 拒绝(合法 ACTIVE 产品线才通过,linkTargetType 被规范化为 null)。 diff --git a/changelogs/2026-05/28_fix_admin_phone_login_customizer_only_send_code.md b/changelogs/2026-05/28_fix_admin_phone_login_customizer_only_send_code.md deleted file mode 100644 index 2de4226..0000000 --- a/changelogs/2026-05/28_fix_admin_phone_login_customizer_only_send_code.md +++ /dev/null @@ -1,40 +0,0 @@ -# 【前端】管理端手机号登录: 非定制师发码直接报错告知,不再发短信 - -> **类型**: 后端接口契约调整(fix,后端已改并部署测试服验证通过) -> **服务**: hl-user-service -> **日期**: 2026-05-28 -> **影响范围**: 管理端登录页「手机号验证码登录」发码接口 `POST /admin/auth/sms/send-code` -> **归属**: 后端已修(PR #3194 → dev,#3197 同步 dev-v3),本条同步契约变化给前端(mmg) -> **状态**: 已部署测试服并验证通过 - ---- - -## 一、问题 - -手机号验证码登录仅对**定制师**开放(工单 #2918)。但之前: -- 非定制师 admin(运营/客服等)请求验证码时,**也会真收到短信**; -- 直到点登录那一步才被拒,且为防枚举返回的是「假装码错」的提示,**不告知真实原因**,用户一头雾水。 - -## 二、改动(后端已完成) - -发码接口 `POST /admin/auth/sms/send-code` 新增前置判断: - -| 手机号情况 | 调整前 | 调整后 | -|-----------|--------|--------| -| 绑定的是**非定制师** admin | 真发短信(登录步才静默拒) | **不发短信**,返回 `code=200107`,`message="短信验证码登录仅限定制师"` | -| 绑定的是**定制师** admin | 真发短信 | 不变,真发短信 | -| **未绑定**任何 admin | 静默返回 200(不真发) | 不变,静默返回 200 | - -## 三、前端建议 - -- 登录页调发码接口收到 `code=200107` 时,直接把后端 `message`(「短信验证码登录仅限定制师」)以 toast/提示展示给用户,**不要进入"已发送、请输入验证码"状态**。 -- 其余错误码不变:`200105` 发送过于频繁、`200106` 当日上限等照旧处理。 - -## 四、测试服实测(`POST /admin/auth/sms/send-code`) - -| 请求 mobile | code | message | 是否发短信 | -|-------------|------|---------|-----------| -| 非定制师 admin | 200107 | 短信验证码登录仅限定制师 | 否 | -| 未注册号码 | 200 | 成功 | 否(静默) | - -(用临时非定制师测试 admin 验证,验证后已清理,remain=0;未真发任何短信。) diff --git a/changelogs/2026-05/28_fix_early_bird_tip_overview_add_traveler_types.md b/changelogs/2026-05/28_fix_early_bird_tip_overview_add_traveler_types.md deleted file mode 100644 index a42b009..0000000 --- a/changelogs/2026-05/28_fix_early_bird_tip_overview_add_traveler_types.md +++ /dev/null @@ -1,40 +0,0 @@ -# 【前端】产品详情早鸟概览文案 earlyBirdTip 补全:含适用人群 + 人数区间 - -> **类型**: 后端文案调整(fix,后端已改并部署测试服验证通过) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-28 -> **影响范围**: 产品详情 `GET /mp/product/{id}` 返回体的 `earlyBirdTip` 字段(早鸟概览串) -> **归属**: 后端已修(PR #3205 → dev,#3206 同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联**: 跟进 #3182/#3187(早鸟文案体现适用人群)的前端反馈「文案还是不对」 - ---- - -## 一、问题 - -前端反馈早鸟文案不完整。核查测试环境:`earlyBirdTip` 概览串旧版**只有折扣**(如「每人立减 100 元」),**缺适用人群、缺人数区间**。 - -> 说明:结构化的 `earlyBirdLadder[]` 各项早已带 `applicableTravelerTypesText`/`peopleRangeText`/`discountText`(#3187),但单行概览串 `earlyBirdTip` 没拼进去。 - -## 二、改动(后端已完成) - -`earlyBirdTip` 现拼成完整一行: - -| 场景 | 文案格式 | 示例 | -|------|----------|------| -| 单方案 | `{折扣}，适用{人群}（{人数区间}）` | 每人立减 100 元，适用成人/儿童（2-50 人） | -| 多方案 | `共 N 档早鸟方案，最高可享 {首项完整文案}` | 共 2 档早鸟方案，最高可享 每人立减 100 元，适用成人/儿童（2-50 人） | - -- 缺人群/人数文案时自动跳过对应片段(只拼有的部分)。 -- `earlyBirdLadder[]` 结构化字段**不变**,前端用概览串或结构化阶梯均可拿到适用人群。 -- 仅产品详情概览 tip 受影响;订单详情早鸟文案不动。 - -## 三、测试服实测(产品 2044306857534636034) - -``` -GET /mp/product/2044306857534636034 -earlyBirdTip = "每人立减 100 元，适用成人/儿童（2-50 人）" ← 原为 "每人立减 100 元" -earlyBirdLadder[0] = { peopleRangeText:"2-50 人", discountText:"每人立减 100 元", applicableTravelerTypesText:"成人/儿童" } -``` - -如展示样式/措辞还需调整(分隔符、是否带「适用」前缀等),告诉后端具体期望即可改。 diff --git a/changelogs/2026-05/28_fix_mp_group_product_list_start_price.md b/changelogs/2026-05/28_fix_mp_group_product_list_start_price.md deleted file mode 100644 index 3adf5eb..0000000 --- a/changelogs/2026-05/28_fix_mp_group_product_list_start_price.md +++ /dev/null @@ -1,46 +0,0 @@ -# 【前端】小蒙马(GROUP)产品列表起价 startPrice 现已正常返回 - -> **类型**: 后端 BUG 修复(后端已改并部署测试服验证通过) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-28 -> **影响范围**: 小蒙马列表 `GET /mp/product/group/list`;以及首页/产品线/推荐列表中的 GROUP 产品 -> **归属**: 后端已修(PR #3195 → dev, Closes #3193;#3199 同步 dev-v3),已部署测试服验证通过 -> **状态**: 已部署测试服并验证通过 - ---- - -## 一、问题 - -小蒙马(GROUP)产品配置了团期价格,但小程序**列表卡片**的起价 `startPrice` 恒为 `null`(不显示"¥xxx起/人")。产品**详情页**起价正常。 - -## 二、根因 - -GROUP 产品的价格存放在**班期表** `group_tour_batch.adult_price`(团期一口价),价格日历 `product_price_calendar` 对 GROUP 是空的。但小程序两条**列表**接口算起价时只查了价格日历,没有对 GROUP 分流到班期表,所以起价取不到值。详情页早已按产品类型正确分流,故详情正常。 - -## 三、改动(后端已完成) - -列表起价对 GROUP 产品改取「未来班期最低成人价」(departure_date ≥ 今天 且 adult_price > 0 的最小值): - -- `GET /mp/product/group/list`(小蒙马专题列表) -- 首页 / 产品线 / 推荐列表中的 GROUP 产品 - -CORE/CUSTOM 产品起价仍来自价格日历,**无变化**。 - -## 四、前端影响 / 建议 - -- 小蒙马列表卡片现在会正常返回 `startPrice` 与 `startPriceLabel`(如 `"¥1635起/人"`),可直接渲染起价。 -- 「无未来可售班期」的 GROUP 产品 `startPrice` 仍为 `null` —— 此场景前端继续显灰/不显起价是合理的。 -- 字段名、类型、结构均未变,**前端无需改动**,数据自然填充即可。 - -## 五、测试服实测(`GET /mp/product/group/list`,清缓存后) - -| productId | 修复前 startPrice | 修复后 startPrice | 说明 | -|-----------|------------------|------------------|------| -| 2056947193331236866 | null | 1635 | 纯班期价产品,已修复 | -| 2056946784965410818 | null | 1635 | 纯班期价产品,已修复 | -| 2056944943066132481 | null | 1425 | 纯班期价产品(3 个未来班期),已修复 | -| 2044306857534636034 | 2999(日历) | 2925(班期) | GROUP 改用班期价(正确口径) | -| 2056947670512971778 | null | null | 无未来可售班期,正确保持 null | -| 2047224617403117570 | null | null | 无未来可售班期,正确保持 null | - -起价均与班期最低成人价精确吻合。 diff --git a/changelogs/2026-05/28_fix_mp_quote_single_room_diff_conditional.md b/changelogs/2026-05/28_fix_mp_quote_single_room_diff_conditional.md deleted file mode 100644 index 53e9441..0000000 --- a/changelogs/2026-05/28_fix_mp_quote_single_room_diff_conditional.md +++ /dev/null @@ -1,42 +0,0 @@ -# 【前端】小程序报价 /mp/product/{id}/quote: 单房差 singleRoomDiff 改为按需返回 - -> **类型**: 后端接口契约调整(fix,后端已改并部署测试服验证通过) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-28 -> **影响范围**: 小程序「产品报价」`POST /mp/product/{id}/quote` 返回体的 `singleRoomDiff` 字段 -> **归属**: 后端已修(PR #3190 → dev,#3191 同步 dev-v3),本条同步契约变化给前端(mmg) -> **状态**: 已部署测试服并验证通过,前端可直接联调 - ---- - -## 一、问题 - -`/mp/product/{id}/quote` 之前**不论几个成人,`singleRoomDiff` 都返回配置值**(如 500),导致小程序在 2 人及以上时也展示单房差。 - -业务规则:**单房差只在「成人=1」(单人成行)时收取**。该规则是后端硬编码(`PricingRuleHelper`,触发条件不可配置;可配置的只是单房差金额)。价格本身(`grandTotal`)一直是对的,只有展示字段 `singleRoomDiff` 没对齐。 - -## 二、改动(后端已完成) - -`singleRoomDiff` 现在**仅在本次实际收取(成人=1)时返回配置值,其余人数返回 `null`**: - -| 字段 | 调整前 | 调整后 | -|------|--------|--------| -| `singleRoomDiff` | 永远返回配置值(如 500) | 成人=1 → 返回 500;成人≠1 → **null** | -| `singleRoomSurcharge` | 本次实际加价(成人=1 为值,否则 0) | 不变 | -| `grandTotal` | 已正确(仅成人=1 含单房差) | 不变 | - -> 仅作用于 C端 `/mp/product/{id}/quote`;admin / 内部 Feign / 订单侧不变。 - -## 三、前端建议 - -- 单房差展示直接按 `singleRoomDiff != null` 判断即可(成人≠1 时为 null,不展示)。 -- 如需「实际加价金额」用于价格明细,以 `singleRoomSurcharge` 为准(成人≠1 恒为 0)。 - -## 四、测试服实测(产品 2045345825172639746,单房差配置=500,日期 2026-05-28) - -| 请求 | singleRoomDiff | singleRoomSurcharge | grandTotal | -|------|----------------|---------------------|------------| -| 成人=2 | **null** | 0 | 6.0 | -| 成人=1 | 500.0 | 500.0 | 503.0 | -| 成人=1 + 儿童=1 | 500.0 | 500.0 | 506.0 | -| 成人=3 | **null** | 0 | 9.0 | diff --git a/changelogs/2026-05/28_notice_mp_product_compare_remove_introduction_row.md b/changelogs/2026-05/28_notice_mp_product_compare_remove_introduction_row.md deleted file mode 100644 index fad91c7..0000000 --- a/changelogs/2026-05/28_notice_mp_product_compare_remove_introduction_row.md +++ /dev/null @@ -1,53 +0,0 @@ -# 【前端】小程序产品对比页: 去掉「简介」行 - -> **类型**: 前端渲染修复(notice,后端无改动) -> **服务**: hl-product-service-v2(`introduction` 早已抹空,无需改后端) -> **日期**: 2026-05-28 -> **影响范围**: 小程序「线路对比 / 产品对比页」核心对比区(packages/product/compare) -> **归属**: 前端(mmg)。后端不建工单,本条仅同步现状 + 修法。 - ---- - -## ⚠️ 问题 - -产品对比页「核心对比」区有一行 **「简介」**,但简介字段(`introduction`)已废弃,后端 `/mp/product/compare` 早已不返该字段 → 这一行对所有产品都显示 `—`(空横线),纯属占位噪音。 - -**用户要求:简介已经没用了,对比页也不要再显示这一行。** - ---- - -## 一、根因 - -- 后端早在工单 **#2943 / PR #2944** 就把 `/mp/product/compare` 的 `subtitle` / `introduction` / `crowdBenefit` 统一抹空返 `null`(对比页只保留核心规格差异)。已合 dev 并部署测试服。 -- 实测测试服 `POST /mp/product/compare?lineId=2043595259778166786`:3 个产品的 `introduction` 全为 `null`(`subtitle` / `crowdBenefit` 同样为 `null`),后端侧完全正确。 -- 但前端对比页 `_buildCoreSection` 里**硬编码**了「简介」行,且**不像「人群优惠」区那样过滤全空行**,所以 `introduction=null` 时这一行依旧渲染成一排 `—`。 - -### 两区对比(为什么人群优惠没这个毛病) - -| 区块 | 构建方法 | 是否过滤空行 | 结果 | -|------|----------|--------------|------| -| 人群优惠 | `_buildCrowdSection` | ✅ 有 `.filter(row => row.values.some(v => v !== '—'))`,全空整段返 null | `crowdBenefit=null` 时整段自动隐藏,无残留 | -| 核心对比 | `_buildCoreSection` | ❌ 行写死,不过滤 | 「简介」行写死 → `introduction=null` 时永远显示一排 `—` | - ---- - -## 二、前端修法(后端零改动) - -删掉 `packages/product/compare/compare.js` 中 `_buildCoreSection` 的「简介」行(约第 140 行): - -```js -// 删除这一行 -{ label: '简介', values: list.map(p => p.introduction || '—'), tall: true }, -``` - -删除后核心对比区保留:天数 / 类型 / 起步价 / 付款方式 / 订金,不再有空的「简介」行。 - -> 备选(更通用):给 `_buildCoreSection` 的 rows 也套一层和人群优惠区一样的"全空行过滤",这样后续任何被后端抹空的字段都会自动隐藏。但当前只有「简介」一行受影响,直接删该行最省事。 - ---- - -## 三、相关接口(均已上线,无变更) - -| 接口 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 产品对比 | POST | `/mp/product/compare?lineId={lineId}` | `subtitle` / `introduction` / `crowdBenefit` 自 #2943 起恒为 `null`,前端不应再展示这些区块 | diff --git a/changelogs/2026-05/28_notice_mp_product_line_hide_empty_category_tabs.md b/changelogs/2026-05/28_notice_mp_product_line_hide_empty_category_tabs.md deleted file mode 100644 index 0959070..0000000 --- a/changelogs/2026-05/28_notice_mp_product_line_hide_empty_category_tabs.md +++ /dev/null @@ -1,71 +0,0 @@ -# 【前端】小程序产品线详情页: 没有产品的类目 tab 应隐藏 - -> **类型**: 前端渲染修复(notice,后端无改动) -> **服务**: hl-product-service-v2(数据已就绪,无需改后端) -> **日期**: 2026-05-28 -> **影响范围**: 小程序「产品线详情页」顶部类目 tab(全部 / 亲子游 / 蜜月旅行 / 摄影之旅 …) -> **归属**: 前端(mmg)。后端不建工单,本条仅同步现状 + 修法。 - ---- - -## ⚠️ 问题 - -产品线详情页顶部那排类目 tab 当前**把 `product_category` 字典的全部 5 个类目都渲染出来了**,不管该产品线下有没有这个类目的产品 → 出现"点进去空的"类目 tab。 - -**用户要求:没有产品的类目隐藏掉**,只显示该产品线下实际有产品的类目(再加一个「全部」)。 - -### 实测复现(测试服) - -产品线「额吉的故乡v11」(lineId=`2045622604613529601`)下 4 个已上架产品的 `category` 分布: - -| 产品 | category | -|------|----------| -| 额吉的故乡 6天5晚草原版 | `family`(亲子游) | -| 额吉的故乡(蜜月) | `honeymoon`(蜜月旅行) | -| 额吉的故乡 6天5晚 | `family` | -| 额吉的故乡(亲子) | `family` | - -→ 该线**只有 `family`(亲子游) + `honeymoon`(蜜月旅行)** 两个类目有产品。 -但页面 tab 还显示了「摄影之旅」(`photography`)等**没有产品**的类目 → 这就是 bug。 - ---- - -## 一、根因 - -- 类目 tab 不是后端某个接口返回的"类目列表",而是前端按 `product_category` 字典(共 5 项)**全量渲染**的,跟"该线是否有此类目产品"无关。 -- 后端**没有**也不需要专门的"类目 tab 列表"接口。 -- 但前端要判断"哪些类目有产品"所需的数据,后端**已经全量提供**:`GET /mp/product-line/{lineId}/products` 返回该线**全部已上架产品**(不分页),每个产品都带 `category` 字段。 - ---- - -## 二、前端修法(推荐,后端零改动) - -1. 进入产品线详情页时调 `GET /mp/product-line/{lineId}/products`(不带 category 参数)拿到该线全部已上架产品。 -2. 对返回列表的 `category` 字段做去重(去掉 null/空)→ 得到"该线实际有产品的类目集合"。 -3. tab 只渲染这个集合里的类目(顺序可按字典 `dict_sort`),最前面保留「全部」。 -4. 由于该接口不分页、返回全量产品,所以 distinct 出来的类目就是完整的非空类目集,无遗漏。 - -### 字典 `product_category` 码 → 中文(渲染 tab 文案用) - -| code | 文案 | -|------|------| -| family | 亲子游 | -| honeymoon | 蜜月旅行 | -| photography | 摄影之旅 | -| experience | 深度体验 | -| driving | 自驾越野 | - ---- - -## 三、可选: 如果前端希望后端直接给"非空类目列表" - -若前端架构上更希望后端直接返回该线的非空类目(免去前端 distinct,并统一码→中文映射 + 排序),可告知后端,我们在产品线详情 `MpProductLineRespVO` 加一个 `categories`(code+label,仅含有产品的类目)字段。**当前默认不加,优先按上面的前端修法。** 需要就说一声。 - ---- - -## 四、相关接口(均已上线,无变更) - -| 接口 | 方法 | 路径 | 说明 | -|------|------|------|------| -| 产品线下产品列表 | GET | `/mp/product-line/{lineId}/products` | 返回该线全部已上架产品,每项含 `category`(本次修复的数据来源) | -| 产品线详情 | GET | `/mp/product-line/{lineId}` | 头部信息(名称/封面/tags/起步价),`tags` 是产品线自由标签,**与类目 tab 是两个概念,别混用** | diff --git a/changelogs/2026-05/29_feat_admin_group_batch_maxrooms_decouple.md b/changelogs/2026-05/29_feat_admin_group_batch_maxrooms_decouple.md deleted file mode 100644 index c3ea283..0000000 --- a/changelogs/2026-05/29_feat_admin_group_batch_maxrooms_decouple.md +++ /dev/null @@ -1,29 +0,0 @@ -# 【管理后台】小蒙马班期「最大房间数」与行程脱钩,按团期自由填 - -> **类型**: 后端行为调整(feat) + 前端回显 BUG -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-29 -> **影响范围**: 管理后台班期编辑 `POST/PUT /admin/product/item/{id}/schedule` 的 `maxRooms` -> **归属**: 后端已改(PR #3261 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3258 - ---- - -> ⚠️ 本条只讲 `maxRooms` 行为。同一「班期编辑表单」本期还有一次**更大的库存模型重构**(删库存上限、新增订单数/线下占位、可报名取 remainStock、班期状态等),**以《小蒙马团期库存模型重构》那篇为准**,本条与其不冲突(maxRooms 仍是容量、按前端传值存)。 - -## 一、后端变更 - -班期保存时 `maxRooms`(最大房间数)此前在传 null/0 时会被强行改成行程的房间数(defaultRoomCount),造成与行程耦合。现已**脱钩**: - -- 前端传什么存什么;**传 0 存 0(0=不限),不再被行程房间数覆盖**。 -- 不再有"改行程房间数同步班期"的逻辑。 - -## 二、前端待办(BUG) - -- **编辑班期时「最大房间数」要正确回显已存值**(此前实测库里=9 但编辑框显示 1,属前端回显 bug)。 -- 「最大房间数」为自由输入,新建班期默认值由前端决定,不再从行程带值。 - -## 三、测试服实测 - -班期保存 `maxRooms=0` 落库 0、`maxRooms=7` 落库 7,均不被行程房间数覆盖。 diff --git a/changelogs/2026-05/29_feat_admin_group_itinerary_hide_room_count.md b/changelogs/2026-05/29_feat_admin_group_itinerary_hide_room_count.md deleted file mode 100644 index e30806a..0000000 --- a/changelogs/2026-05/29_feat_admin_group_itinerary_hide_room_count.md +++ /dev/null @@ -1,28 +0,0 @@ -# 【管理后台·前端】小蒙马(GROUP)行程「住宿安排」房间数选择器移除 - -> **类型**: 前端调整(需 hl-ui 改) -> **服务**: 无后端改动(hl-product-service-v2 已兼容) -> **日期**: 2026-05-29 -> **影响范围**: 管理后台 产品编辑 → Step2 行程编排 → 当日概况 → 住宿安排，小蒙马(GROUP)产品 -> **归属**: 前端待改(mmg);后端无需改动 -> **状态**: 后端已确认兼容(测试服在跑) - ---- - -## 一、需求 - -小蒙马(GROUP)产品的行程「住宿安排」里，酒店后面的**房间数选择（如「普通标间 ×8间」的"×N间"）不再需要选**，前端隐藏/移除该房间数控件即可（仅 GROUP；CORE/私人定制 CUSTOM 仍保留，房间数对它们另有用途）。 - -## 二、为什么 - -此前行程住宿的房间数会被后端聚合成 `defaultRoomCount`，再在**班期创建时自动填充班期「最大房间数」maxRooms**。但 #3258 已经把班期 maxRooms 与行程**彻底脱钩**（班期房间数改为按团期自由填/线下占位独立管理）。因此行程住宿的房间数对小蒙马**已无任何作用**，留着只会误导运营。 - -## 三、后端兼容性（已确认，无需后端改动） - -- 行程保存接口 `POST /admin/product/item/{id}/itinerary` 的住宿项 `roomCount` 字段本就是**可选**（无必填校验），前端不传/传 null 后端正常保存。 -- `roomCount` 不再影响班期 maxRooms / 库存 / 可报名（#3258 起已脱钩）。 -- 前端只需对 GROUP 隐藏该控件、提交时不带该值即可，无需后端配合。 - -## 四、备注 - -后端侧 `defaultRoomCount`（product_basic）已成为无逻辑消费的遗留字段，计划后续单独清理，不影响本次前端调整。 diff --git a/changelogs/2026-05/29_feat_group_batch_stock_model_refactor.md b/changelogs/2026-05/29_feat_group_batch_stock_model_refactor.md deleted file mode 100644 index 634d59f..0000000 --- a/changelogs/2026-05/29_feat_group_batch_stock_model_refactor.md +++ /dev/null @@ -1,59 +0,0 @@ -# 【管理后台+小程序】小蒙马团期库存模型重构(删库存上限·订单数/线下占位·已报名聚合·班期状态) - -> **类型**: 后端模型重构(feat,含字段增删) -> **服务**: hl-product-service-v2 + hl-order-service-v2 -> **日期**: 2026-05-29 -> **影响范围**: 管理后台班期编辑/列表 + 小程序班期列表(下方逐接口列出) -> **归属**: 后端已改(PR #3267 + #3269 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3266 - ---- - -## 一、模型总览(前端先理解这套口径) - -- **容量只看「最大房间数」`maxRooms`**(0/null=不限)。「最大人数」不再作为限制,人数仅展示。 -- **删除「库存上限」**(原 `productStockLimit`)。 -- **「订单数(消耗)」= 实时线上订单数 + 线下占位数(相加)**;1 单 = 1 房。 -- **库存/可报名 = `maxRooms − 订单数`**,后端实时算、**不落库**。 -- **已报名人数 = 聚合活跃订单总人数**,后端实时算、不落库。 -- 库存=0 不能开启「报名中」;下单占库存、取消/退款释放(后端自动,前端无需处理)。 - -## 二、管理后台·班期编辑(`POST` / `PUT /admin/product/item/{id}/schedule`,ScheduleSaveReqVO) - -**字段调整:** -- ❌ 移除 `productStockLimit`(库存上限)输入。 -- ➕ 新增 `manualOrderCount`(**线下占位房数**,可空,默认 0,不能为负):用于运营把线下/电话占的房手动占进库存,恒加在实时线上订单之上。 -- `maxRooms`(最大房间数=容量)保留。 - -**保存校验(后端会拒绝):** -- `manualOrderCount` 为负 → `code 410203 线下占位数不能为负数`。 -- 若该班期库存已 ≤ 0 却要置/保持「报名中」→ `code 410204 库存不足,无法开启报名中`。 - -## 三、管理后台·班期列表/回显(`GET /admin/product/item/{id}/schedule/list`,ScheduleRespVO) - -- ❌ 移除 `enrolledCount`(旧人数计数器)、`bookedRooms`、`productStockLimit`。 -- ➕ 新增(均后端实时计算,只读): - - `manualOrderCount` — 回显线下占位数 - - `orderCount` — 有效订单数(= 实时线上订单数 + 线下占位) - - `enrolledPeople` — 已报名人数(聚合) - - `remainStock` — 库存/可报名(= maxRooms − orderCount;**null = 不限**) - -## 四、小程序·班期列表(`GET /mp/product/{id}/schedules`,MpScheduleRespVO) - -- **返回该产品全部团期(含已出发,仅排除已删除)**,前端按状态展示。 -- 每条 `batchStatus`(前端**只对 `ENROLLING` 放开报名按钮**,其余禁止报名): - - `ENROLLING` 报名中(可报名) - - `FINISHED` 报名结束(已出发 / 报名截止日已过 / 出发前 1 天) - - `FULL` 已满额(售罄) - - `CANCELLING` / `CANCELLED` 取消中 / 已取消 -- 字段语义: - - `enrolledCount` → 现为**已报名人数(聚合)** - - `remainFamilies` → **可报名/库存**(= remainStock;null=不限)。**前端「还可报 X 组」取此字段**。 - - `remainParticipants` → 恒 `null`(人数不再限制) - -## 五、测试服实测 - -- 加法库存:maxRooms=5、线下占位=2、线上 0 单 → `orderCount=2`、`remainStock=3`、`enrolledPeople=0`。 -- 库存=0 开报名中被拒(410204);线下占位负数被拒(410203)。 -- mp `/schedules` 返回含已出发团期并标 `FINISHED`;售罄标 `FULL`。 diff --git a/changelogs/2026-05/29_feat_mp_tier_compare_add_district.md b/changelogs/2026-05/29_feat_mp_tier_compare_add_district.md deleted file mode 100644 index d339a7c..0000000 --- a/changelogs/2026-05/29_feat_mp_tier_compare_add_district.md +++ /dev/null @@ -1,46 +0,0 @@ -# 【小程序】档位对比 /mp/product/{id}/tier-compare 住宿项新增「区/县」district 字段 - -> **类型**: 后端出参新增字段(feat,向后兼容) -> **服务**: hl-product-service-v2 + hl-resource-service -> **日期**: 2026-05-29 -> **影响范围**: 小程序端 `GET /mp/product/{id}/tier-compare` 每个住宿项 -> **归属**: 后端已改(PR #3259 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: 无(直接报 BUG) - ---- - -## 一、变更点 - -档位对比接口的住宿项此前只返回城市 `city`,现在**同时返回区/县 `district`**,与 `city` 并列。 - -```json -{ - "code": 200, - "data": { - "tiers": [ - { - "tierSeq": 2, - "tierName": "豪华", - "hotels": [ - { - "dayNumber": 1, - "hotelName": "海拉尔首旅京伦酒店", - "city": "呼伦贝尔市", - "district": "海拉尔区" - } - ] - } - ] - } -} -``` - -## 二、前端处理 - -- `hotels[].district` 为新增字段(区/县),前端可在城市后展示完整地址层级。 -- 当住宿项无关联酒店资源(仅快照)时,`city`/`district` 均为 `null`(与原 `city` 行为一致),前端做空值兜底即可。 - -## 三、测试服实测 - -产品 2043696… 豪华档住宿项返回 `city=呼伦贝尔市, district=海拉尔区/额尔古纳市/阿尔山市`,城市+区县均正确。 diff --git a/changelogs/2026-05/29_fix_mp_common_faq_category_null.md b/changelogs/2026-05/29_fix_mp_common_faq_category_null.md deleted file mode 100644 index 92e8588..0000000 --- a/changelogs/2026-05/29_fix_mp_common_faq_category_null.md +++ /dev/null @@ -1,44 +0,0 @@ -# 【小程序】常见问题 /mp/common/faq 返回结构修正为 {id, name, items:[{id, question, answer}]} - -> **类型**: 后端出参结构修复(fix,后端已改并部署测试服验证通过) -> **服务**: hl-mp-service -> **日期**: 2026-05-29 -> **影响范围**: 小程序端 `GET /mp/common/faq` 返回体结构 -> **归属**: 后端已修(PR #3237 → dev,#3238 同步 dev-v3;修正了早先 #3231/#3232 的错误修法) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3230 - ---- - -## ⚠️ 更正说明 - -本文件早先版本(基于 PR #3231)写的「对外字段名仍是 `category`、结构不变」是**错误的**。前端实际期望的是 `{id, name, items:[{id, question, answer}]}`(分类名读 `name` 不是 `category`,且需要分类 `id` 和 item `id`)。已用 PR #3237 修正,以本文为准。 - -## 一、最终返回结构 - -```json -{ - "code": 200, - "data": [ - { - "id": 1, - "name": "产品怎么选", - "items": [ - { "id": 10, "question": "……", "answer": "……" } - ] - } - ] -} -``` - -- 分组:`id`(分类ID)、`name`(分类名)、`items` -- 条目:`id`(问题ID)、`question`、`answer` -- 与前端现有读取方式(`cat.id` / `cat.name` / `item.id` / `item.question` / `item.answer`)一致,**前端无需改动**。 - -## 二、背景 - -之前 mp 返回的是 `{category, items:[{question, answer}]}` —— 分类名字段名错(`category` 而非 `name`)、且缺分类 `id` 与 item `id`,与前端不符。现已改为上游 user-service 原始结构,字段按名直通。 - -## 三、测试服实测 - -清缓存后 `GET /mp/common/faq` 返回 4 个分组,分组 keys = `[id, name, items]`(无 `category`),item keys = `[id, question, answer]`,与前端结构完全一致。 diff --git a/changelogs/2026-05/29_fix_mp_product_line_order_align_admin.md b/changelogs/2026-05/29_fix_mp_product_line_order_align_admin.md deleted file mode 100644 index 3d49233..0000000 --- a/changelogs/2026-05/29_fix_mp_product_line_order_align_admin.md +++ /dev/null @@ -1,30 +0,0 @@ -# 【FYI·小程序】主题下产品列表排序与管理端对齐(前端无需改) - -> **类型**: 后端排序键对齐(fix,后端已改并部署测试服验证通过) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-29 -> **影响范围**: 小程序端「主题(产品线)详情 → 产品列表」`GET /mp/product-line/{lineId}/products` 的返回顺序 -> **归属**: 后端已修(PR #3228 → dev,#3229 同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3227 / 跟进 #3215(管理端拖拽排序) - ---- - -## 一、问题 - -管理端给主题下产品排好序后,小程序端展示顺序与管理端不一致。 - -根因:小程序主题详情用的查询只按 `sort_order` 升序,缺管理端的 `create_time` 次序键。当多个产品 `sort_order` 相同(尤其默认全 0、运营还没逐个拖排时),小程序与管理端顺序不一致(实测恰好相反)。 - -## 二、改动(后端已完成) - -小程序主题下产品查询排序键补齐为 `sort_order ASC + create_time DESC`,与管理端「版本列表」完全一致。 - -- 现在:管理端怎么排,小程序就怎么显示(逐个拖排了按拖排顺序;没拖排的按创建时间倒序,与管理端一致)。 -- **前端无需任何改动**,接口字段/结构不变,顺序自然对齐。 - -## 三、测试服实测(主题 2045622604613529601,4 个已上架产品) - -清缓存后,小程序返回顺序与管理端列表完全一致(均为 `875842 → 328770 → 826306 → 046978`);修复前小程序为相反顺序。 - -> 提示:小程序该接口有 10 分钟缓存,管理端重排后最长 10 分钟内生效(重排已触发缓存失效,正常情况即时生效)。 diff --git a/changelogs/2026-05/30_chore_admin_product_detail_remove_defaultRoomCount.md b/changelogs/2026-05/30_chore_admin_product_detail_remove_defaultRoomCount.md deleted file mode 100644 index 51a7e5b..0000000 --- a/changelogs/2026-05/30_chore_admin_product_detail_remove_defaultRoomCount.md +++ /dev/null @@ -1,28 +0,0 @@ -# 【管理后台】产品详情响应移除 defaultRoomCount(默认房间数)字段 - -> **类型**: 后端响应移除字段(死字段清理) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-30 -> **影响范围**: 管理后台 `GET /admin/product/item/{id}` 及内部产品详情 DTO -> **归属**: 后端已改(PR #3278 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过(响应不再含该字段) -> **关联工单**: #3266 收尾 - ---- - -## 一、变更 - -产品详情响应不再返回 `defaultRoomCount`(默认房间数)。 - -- 该字段原是"行程住宿各天最小房间数"的聚合值,唯一用途是小蒙马班期创建时自动填充 maxRooms。 -- #3258 已把班期 maxRooms 与行程**彻底脱钩**,该字段从此**无任何消费者**,本次随死字段清理移除。 -- 与早先《小蒙马行程「住宿安排」房间数选择器移除》一脉相承(行程房间数对小蒙马已无作用)。 - -## 二、前端处理 - -- 若前端有读取 `productDetail.defaultRoomCount` 的地方(通常在行程住宿/班期相关展示),**移除该读取**;小蒙马班期房间数请改用班期自身的「最大房间数」maxRooms。 -- DB 列 `product_basic.default_room_count` 暂保留为无映射废弃列(不影响,后续统一清理),仅响应不再透出。 - -## 三、测试服实测 - -`GET /admin/product/item/{id}` 返回体 `data` 中已无 `defaultRoomCount` 键(code=200)。 diff --git a/changelogs/2026-05/30_feat_admin_group_batch_edit_status_auto_couple.md b/changelogs/2026-05/30_feat_admin_group_batch_edit_status_auto_couple.md deleted file mode 100644 index 97d8f6d..0000000 --- a/changelogs/2026-05/30_feat_admin_group_batch_edit_status_auto_couple.md +++ /dev/null @@ -1,30 +0,0 @@ -# 【管理后台】小蒙马班期编辑后状态随库存自动联动(满→FULL/恢复→ENROLLING) - -> **类型**: 后端行为增强(状态联动) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-30 -> **影响范围**: 管理后台班期保存 `POST/PUT /admin/product/item/{id}/schedule` -> **归属**: 后端已改(PR #3277 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3266 - ---- - -## 一、变更(前端通常无需改动,仅告知) - -编辑班期后,后端会按最新库存**自动联动持久 batchStatus**: - -- 把「最大房间数」调小 / 「线下占位」调大,导致库存(可报名)≤0 → 状态自动变 `FULL`(已满额)。 -- 反向把库存恢复到 >0 → 状态自动变回 `ENROLLING`(报名中)。 -- 取消态(CANCELLING/CANCELLED)不受此联动影响。 - -这补齐了此前"只在新建班期时拦截库存0"的缺口,使后台列表的持久状态始终与实时库存一致。 - -## 二、前端 - -- 前端继续按 `batchStatus` 渲染即可(只对 `ENROLLING` 放开报名),**无需新增逻辑**。 -- 编辑保存后刷新列表即可看到状态随库存联动后的最新值。 - -## 三、测试服实测 - -班期 maxRooms=5 → ENROLLING;编辑为 maxRooms=2+线下占位=2(库存=0)→ 自动 FULL;再编辑线下占位=0(库存=2)→ 自动回 ENROLLING。 diff --git a/changelogs/2026-05/30_feat_group_fullteam_participants_and_single_room_diff_odd.md b/changelogs/2026-05/30_feat_group_fullteam_participants_and_single_room_diff_odd.md deleted file mode 100644 index 55677cc..0000000 --- a/changelogs/2026-05/30_feat_group_fullteam_participants_and_single_room_diff_odd.md +++ /dev/null @@ -1,55 +0,0 @@ -# 【管理后台 + 小程序】小蒙马满团叠加「人数维度」+ 单房差改为「仅奇数成人收取」 - -> **类型**: 后端行为增强(满团判定口径 + 单房差计费规则) -> **服务**: hl-product-service-v2, hl-order-service-v2 -> **日期**: 2026-05-30 -> **影响范围**: 班期满团展示 / 下单库存校验 / 全产品类型报价单房差 -> **归属**: 后端已改(PR #3280 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3279 - ---- - -## 一、小蒙马满团叠加「人数维度」(原仅房间数) - -此前(PR #3267)满团只看房间数(1单=1房)。现在**房间或人数任一达上限即满团**(OR): - -- 新增/启用「剩余名额」`remainParticipants = 最大参与人数 - 已报名人数`。 - - 班期「最大参与人数」为 0/null = 人数不限,此维度不卡(**未设人数上限的存量班期行为不变**)。 - - 线下占位仅占房间、不占人数名额(口径如此)。 -- `batchStatus` 满团判定:房间耗尽 **或** 人数耗尽 → `FULL`。 - -### 新增响应字段 - -| 接口 | VO | 新字段 | -|------|-----|--------| -| `GET /admin/product/item/{id}/schedule/list` | ScheduleRespVO | `remainParticipants` 剩余名额(不限时 null) | -| `GET /admin/product/item/{id}/pricing-calendar` | UnifiedPricingCalendarItemVO | `remainParticipants` | -| `GET /mp/product/{id}/schedules` | MpScheduleRespVO | `remainParticipants`(原恒为 null,现回传真实值);`batchStatus` 现会因人数耗尽也变 `FULL` | - -> 前端:仍按 `batchStatus` 判断能否报名即可(只 `ENROLLING` 放开)。如需展示「还剩 N 个名额」可用新 `remainParticipants`(与房间维度 `remainStock`/`remainFamilies` 并列)。 - -## 二、下单库存校验新增「人数维度」+ 新错误码 - -GROUP 下单时,除房间校验外新增人数名额校验(软校验 + 锁内硬守卫双道): - -- **新错误码 `503109` 「剩余名额不足」**(人数超出剩余名额时返回)。 -- 房间不足仍为 `503106` 「剩余房间不足」。 - -> 前端:下单失败时请按 code 区分提示(503109=名额不足 / 503106=房间不足)。 - -## 三、单房差改为「仅奇数成人收取」(所有产品类型) - -报价 `singleRoomSurcharge` 计费规则调整(CORE/CUSTOM/ROUTE/GROUP 全部生效): - -- **成人数为奇数(1/3/5…)** 且配置了单房差 → 收一份单房差。 -- **成人数为偶数(含 0,2/4/6…)** → 不收。 -- `singleRoomDiff`(配置值)字段含义不变,仅实际加价 `singleRoomSurcharge` 的触发条件由「严格 1 人」改为「奇数人」。 - -> 前端:报价/订单详情的「单房差」行仍读 `singleRoomSurcharge`,无需改字段,仅金额随上述规则变化。 - -## 四、测试服实测 - -- 单房差(配置 500,成人价 2925):1人→+500(3425)、2人→+0(5850)、3人→+500(9275)、4人→+0(11700)。✓ -- 满团人数维度:admin schedule/list 正确回传 `remainParticipants`(=最大人数−已报名)。✓ -- 下单防超卖:班期 maxPart=2,请求 3 人/1 房 → `503109 剩余名额不足`;请求 1 人/2 房 → `503106 剩余房间不足`。✓ diff --git a/changelogs/2026-05/30_feat_group_offline_participants_count.md b/changelogs/2026-05/30_feat_group_offline_participants_count.md deleted file mode 100644 index 5c7a953..0000000 --- a/changelogs/2026-05/30_feat_group_offline_participants_count.md +++ /dev/null @@ -1,51 +0,0 @@ -# 【管理后台 + 小程序】小蒙马新增「线下报名人数」,计入已报名人数与人数满团 - -> **类型**: 后端行为增强(新增字段 + 满团口径) -> **服务**: hl-product-service-v2 -> **日期**: 2026-05-30 -> **影响范围**: 班期编辑 / 班期展示 / 人数满团判定 -> **归属**: 后端已改(PR #3282 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3281(承接 #3279) - ---- - -## 一、背景 - -此前「线下占位」`manualOrderCount` 只是**房数**(占房间维度),「已报名人数」只算线上聚合订单人数。现新增「线下报名人数」,使线下一笔预订既占房也占人,与线上口径对齐。 - -## 二、新增字段 `manualParticipantCount`(线下报名人数) - -- **班期编辑**(`POST/PUT /admin/product/item/{id}/schedule`,ScheduleSaveReqVO):新增可填项 `manualParticipantCount`(运营手动线下报名真实人数,默认 0,不能为负;为负返回错误码 `410205`)。 -- **已报名人数 = 线上聚合订单人数 + 线下报名人数**。 -- **人数满团**:`remainParticipants = 最大参与人数 - 已报名人数(含线下)`;线下报名人数也能把班期顶到 `FULL`。 -- 与 `manualOrderCount`(线下占位房数,占房间维度)对称:线下一笔预订,房用 `manualOrderCount`、人用 `manualParticipantCount`。 - -### 响应新增/变化字段 - -| 接口 | VO | 字段 | -|------|-----|------| -| `GET /admin/product/item/{id}/schedule/list` | ScheduleRespVO | 新增 `manualParticipantCount`;`enrolledPeople` 现含线下 | -| `GET /admin/product/item/{id}/pricing-calendar` | UnifiedPricingCalendarItemVO | `enrolledPeople`/`remainStock` 口径不变,人数维度已含线下 | -| `GET /mp/product/{id}/schedules` | MpScheduleRespVO | 新增 `manualParticipantCount`;`enrolledCount`(已报名人数)现含线下 | - -## 三、小程序展示「已报名人数」(建议前端补展示) - -后端数据已齐备,小程序班期可直接展示: -- `enrolledCount` = 已报名人数(线上 + 线下) -- `maxParticipants` = 最大参与人数(0/空=不限) -- `remainParticipants` = 剩余名额(不限时 null) - -> 建议 mmg 在班期卡片展示「已报名 X 人 / 共 Y 人」或「剩余 N 个名额」。`batchStatus=FULL` 时显示「已满」(房间或人数任一满都会是 FULL)。 - -## 四、兼容性 - -- `manualParticipantCount` 为 0/null = 无线下报名人数,行为与上一版(PR #3280)完全一致,**向后兼容零影响**。 -- 顺带修正了上一版遗留的 Swagger 注释(maxParticipants 现已卡满团与下单;remainParticipants 现返回真实剩余名额)。 - -## 五、测试服实测 - -班期 maxParticipants=30、maxRooms=0(房间不限)、线上0单: -- 线下报名人数=7 → 已报名人数 enrolledPeople=7、remainParticipants=23 ✓ -- 线下报名人数=30(=上限)→ remainParticipants=0、`batchStatus=FULL`(纯线下报名顶满团)✓ -- 复原线下=0 → remainParticipants=30、ENROLLING ✓ diff --git a/changelogs/2026-06/01_admin_warn_edit_departure_with_orders.md b/changelogs/2026-06/01_admin_warn_edit_departure_with_orders.md deleted file mode 100644 index 3ab759f..0000000 --- a/changelogs/2026-06/01_admin_warn_edit_departure_with_orders.md +++ /dev/null @@ -1,32 +0,0 @@ -# 【管理后台·前端待办】已有报名的小蒙马班期改「出发日期」需强力二次确认 - -> **类型**: 前端待办(admin hl-ui) - UX 安全提示 -> **仓库**: hl-ui(管理后台前端) -> **日期**: 2026-06-01 -> **背景**: wx 反馈——已经有报名的团期改出发日期,应给强力提示(改出发日期会影响已下单/已报名的客户) -> **后端**: 数据已就绪,无需改后端 - ---- - -## 一、需求 - -班期编辑(Step4 班期定价 → 编辑班期)保存时,若该班期**已有报名/订单**,改动「出发日期」前必须弹**强力二次确认**(而非静默保存),提示运营:该班期已有 N 人报名/M 单,改出发日期会影响已下单客户,请确认。 - -## 二、后端已提供的数据(无需改后端) - -班期列表 `GET /admin/product/item/{id}/schedule/list`(ScheduleRespVO)每条已返回: -- `enrolledPeople` 已报名人数(含线下) -- `orderCount` 有效订单数(含线下占位) -- `remainStock` / `remainParticipants` 余量 - -编辑表单的班期数据即来自该列表,前端可直接判断 `enrolledPeople > 0`(或 `orderCount > 0`)。 - -## 三、前端要做 - -班期编辑保存时: -1. 若 `enrolledPeople > 0`(或 orderCount>0)**且**出发日期被改动 → 弹强确认弹窗(危险样式),文案如:「该班期已有 {enrolledPeople} 人报名,修改出发日期将影响已下单客户,确认修改?」,二次确认后才提交。 -2. 未改出发日期、或无报名的班期,保持原静默保存。 - -## 四、关联后端修复(已上线) - -- 改出发日期后,后端已会**自动重算结束日期(#3296)和报名截止日(#3303)**,班期状态随之正确联动(不再卡「已结束」)。前端保存后刷新列表即可看到状态/日期同步。 diff --git a/changelogs/2026-06/01_fix_mp_quote_capacity_fields.md b/changelogs/2026-06/01_fix_mp_quote_capacity_fields.md deleted file mode 100644 index 70f92eb..0000000 --- a/changelogs/2026-06/01_fix_mp_quote_capacity_fields.md +++ /dev/null @@ -1,45 +0,0 @@ -# 【小程序】下单页满团提示:C端实时报价新增班期容量余量字段 - -> **类型**: 后端补字段(供前端做满团提示) -> **服务**: hl-product-service-v2 -> **日期**: 2026-06-01 -> **影响范围**: `POST /mp/product/{id}/quote`(C端报价,出行信息弹窗 / 订单确认页) -> **归属**: 后端已改(PR #3289 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: #3288 -> **需前端配合**: ⚠️ 是 - ---- - -## 一、问题 - -下单流程(填写出行信息弹窗 / 订单确认页)能选择**超过班期剩余名额/库存**的人数并进到支付页,无任何提示。例:班期最大人数 26、线下报名人数 24 → 余名额仅 2,却可选成人 3 + 儿童 1 = 4 人到支付页(点支付才被后端 503 拦)。 - -## 二、后端改动 - -`POST /mp/product/{id}/quote` 的响应 `MpQuoteResultVO` 新增 4 字段(**仅 GROUP/小蒙马且请求带 `batchId` 时有值,CORE/CUSTOM 为 null**): - -| 字段 | 含义 | -|------|------| -| `maxParticipants` | 最大参与人数(0/空=不限) | -| `remainParticipants` | 剩余可报名名额(= 最大人数 − 已报名人数含线下;`null`=不限) | -| `remainStock` | 剩余房间库存(= 最大房间 − 有效订单含线下占位;`null`=不限) | -| `capacityEnough` | 本次报价人数是否在剩余容量内(`true`=够位可下单,`false`=超员/售罄) | - -`capacityEnough` 计算:请求总人数(成人+儿童+小童+幼童) ≤ `remainParticipants`(不限恒真) **且** `remainStock` 非 0(房间未售罄)。 - -> 价格字段不变;硬拦截仍在下单(超员 503109 / 房间不足 503106)。本次只是把**余量数据**给到前端做软提示。 - -## 三、前端需要做(mmg) - -出行信息弹窗 + 订单确认页,基于报价返回的上述字段: -1. **人数步进器封顶**:成人/儿童等总人数不允许超过 `remainParticipants`(为 null 时不限),`+` 到上限置灰。 -2. **超员/售罄提示**:`capacityEnough=false` 时提示「仅剩 N 个名额」/「该班期已满」,并**禁用「支付订金/支付」按钮**。 -3. 建议在展示「剩余 N 个名额」时用 `remainParticipants`;`remainStock` 可用于房间数选择封顶。 - -## 四、测试服实测 - -问题班期(最大人数 26 / 线下报名 24 → 余名额 2;最大房间 10 / 线下占位 9 → 余房 1): -- 成人 3 + 儿童 1 = 4 人 → `capacityEnough=false`,`remainParticipants=2`,`remainStock=1`,`maxParticipants=26` ✓ -- 成人 4 → false ✓;成人 2(=余 2)→ true ✓;成人 1 → true ✓ -- 价格 `grandTotal` 正常返回(报价不受影响) diff --git a/changelogs/2026-06/01_frontend_mengma_allow_adult_only_booking.md b/changelogs/2026-06/01_frontend_mengma_allow_adult_only_booking.md deleted file mode 100644 index c743211..0000000 --- a/changelogs/2026-06/01_frontend_mengma_allow_adult_only_booking.md +++ /dev/null @@ -1,49 +0,0 @@ -# 【小程序·前端待办】小蒙马(GROUP)下单放开「必须有儿童/小童」限制,允许纯成人下单 - -> **类型**: 前端待办(hl-mini 小程序) - 业务规则放开 -> **仓库**: hl-mini(v1 分支,C 端小程序) -> **日期**: 2026-06-01 -> **背景**: wx 反馈——小蒙马下单时「只有成人、没有儿童」也应能下单;现状是没有非成人(儿童/小童)就被拦,无法下单。 -> **后端**: 已支持纯成人下单,**无需改后端**(依据见下)。 - ---- - -## 一、需求 - -小蒙马(GROUP / 团队产品)下单,**允许只有成人、不带任何儿童/小童/幼童**也能正常下单。当前前端在确认下单时强制「至少 1 名儿童或小童」,需放开。 - -## 二、前端拦截点(要改的地方) - -`packages/product/_shared/components/booking-popup/booking-popup.js` → `onConfirm()` 内: - -```js -// 约 758-761 行 —— 这段是唯一的硬拦截,删除即可 -if (isGroupProduct && (childCount + youngChildCount) < 1) { - wx.showToast({ title: '至少需要1名儿童或小童', icon: 'none' }); - return; -} -``` - -- **改法**:删掉上面这个 `if` 块。保留上方 `adultCount < 1 → '至少需要1名成人'` 的校验(成人仍是必须的)。 -- 删除后,小蒙马即可纯成人下单(成人 ≥1、儿童/小童/幼童均可为 0)。 - -### 可选(体验,非阻塞) -同文件约 274 行,小蒙马儿童 stepper 默认起始值为 1(`isGroupProduct ? 1 : ...`)。这只是默认值,用户本就能手动减到 0(line 279-280 已把 min 设为 0),不影响纯成人下单。是否把默认值也改为 0 由前端按交互习惯决定,**与本次放开无强依赖**。 - -## 三、后端为什么不用改(依据) - -后端全链路已支持纯成人,逐处确认: - -| 位置 | 结论 | -|------|------| -| `MpOrderSaveReqVO` / `AdminOrderSaveReqVO`(下单请求) | `adultCount @Min(1)`,childCount/youngChildCount/babyCount **无下限、默认可为 0/null** | -| `GroupTourBatchService.getGroupQuote`(团报价) | 纯成人时 `childTotal/toddlerTotal/infantTotal = 0`,`grandTotal` 正常,不依赖非成人 | -| `GroupOrderStrategy.validate`(下单校验) | 只校验班期状态/报名截止/出发日期/房间库存,**无人群结构校验** | -| `OrderCreateService.calcTotalPeople` | null-safe,纯成人 `totalPeople = 成人数 > 0`,正常扣减库存 | -| `PricingRuleHelper.singleRoomSurcharge` | 单房差只看 `adultCount`(奇数成人),与是否有儿童无关 | - -即:前端删掉那段校验后,纯成人下单会被后端正常受理、报价、扣库存。 - -## 四、验证建议(前端改完自测) - -小蒙马产品 → 选报名中班期 → 成人 2、儿童/小童/幼童全 0 → 应能正常进入支付/确认页,不再弹「至少需要1名儿童或小童」。 diff --git a/changelogs/2026-06/02_admin_order_refund_display_and_failreason.md b/changelogs/2026-06/02_admin_order_refund_display_and_failreason.md deleted file mode 100644 index b3de763..0000000 --- a/changelogs/2026-06/02_admin_order_refund_display_and_failreason.md +++ /dev/null @@ -1,63 +0,0 @@ -# 【管理后台·前端对接】退款列表/详情显示修正:实际退款额仅到账显示、详情新增失败原因、直接申诉回显补全 - -> **类型**: 后端修复 + 接口字段新增(hl-admin 管理后台对接) -> **仓库**: hl-admin(管理后台前端) -> **日期**: 2026-06-02 -> **工单**: #3356 + #3357 ｜ **PR**: #3358 -> **状态**: ✅ 已合并 dev → 同步 dev-v3 → 部署测试服 → **测试服 API 已实测通过** -> **背景**: 处理一笔正式退款时发现退款申请列表/详情的几处显示不准确,本次一并修正。 - ---- - -## 一、退款申请列表「实际退款额」语义修正(行为变化,前端需留意) - -- 接口:`GET /admin/order/refund/list`(分页字段 `page` / `pageSize`) -- **变化**:返回字段 `actualAmount`(实际退款额 = 实际到账金额)现在**仅当 `status=REFUNDED`(微信回调确认退款成功)时才有值**;其余状态(`PENDING`/`APPROVED`/`REFUNDING`/`APPEALING`/`APPEAL_APPROVED`/`REJECTED`/`CANCELLED` 等)一律返回 `null`。 -- **原因**:此前 `actualAmount` 在审批时就预填了,导致「退款中/已取消/申诉中」的单子也显示金额,误以为已退到账。现严格表示「真实到账」。 -- **前端建议**:`actualAmount` 为 `null` 时列内显示「-」即可(与现有空值处理一致)。 - -## 二、新增「失败原因」字段 `failReason`(列表 + 详情都返回) - -- **新增字段**:`failReason`(String,退款失败原因) - - 退款被微信拒绝/失败时,回显微信返回的原话,例如:`基本账户余额不足，请充值后重新发起` - - 未失败(成功/进行中/无失败记录)时为 `null` -- **两个接口都返回**(更新:此前仅详情返回,现列表也返回): - - 列表:`GET /admin/order/refund/list` —— 每行带 `failReason`,失败过的行有值,其余 `null` - - 详情:`GET /admin/order/refund/{applicationId}` -- **前端建议**:列表可加「失败原因」列(或在状态旁提示),`failReason` 非空展示「失败原因:xxx」;详情页同样展示。便于运营/客服在列表直接看出哪些单没退成及原因。 - -```json -// 列表 records[] 每项 / 详情 data 节选 -{ - "applicationId": "...", - "status": "REFUNDING", - "actualAmount": null, - "failReason": "基本账户余额不足，请充值后重新发起" -} -``` - -## 三、直接申诉的退款单列表回显补全(修复空白) - -- 现象:用户**未先提退款申请、直接发起申诉**产生的退款单,在退款列表里「申请人 / 退款类型 / 已付金额 / 计算退款额」此前全为空(显示「-」)。 -- 修复:这类单子建单时已补全上述字段,列表正常回显。 -- **注意**:仅对**修复后新建**的直接申诉生效;修复前已存在的历史单据仍为空(不回填),前端无需特殊处理。 - -## 四、(后端内部,无需前端对接)退款失败提醒定制师 - -退款彻底失败(如商户号余额不足)时,后端会经通知中心给订单**定制师**发一次企微提醒(含订单/金额/失败原因/待办)。纯后端能力,前端无需改动,知悉即可。 - ---- - -## 五、测试服实测结果(2026-06-02) - -| 用例 | 结果 | -|------|------| -| 列表 18 条:非 REFUNDED 行 actualAmount | ✅ 全部为 null | -| 列表 REFUNDED 行 actualAmount | ✅ 正常有值 | -| 详情接口含 failReason 字段 | ✅ 已返回;构造 FAILED 记录实测回显微信失败原因 | -| **列表接口含 failReason 字段** | ✅ 构造 FAILED 记录实测:列表对应行回显失败原因,其余行为 null(单页 1 次批量查,无 N+1) | -| Flyway 加列 fail_reason | ✅ 已应用 | - -## 六、联调地址 -- 网关:`https://api.test.1814.love:9443` -- Knife4j 文档同地址,tag「[admin] 退款管理」下可见 `退款申请列表` / `退款申请详情`。 diff --git a/changelogs/2026-06/02_admin_order_switch_customizer.md b/changelogs/2026-06/02_admin_order_switch_customizer.md deleted file mode 100644 index c4194cb..0000000 --- a/changelogs/2026-06/02_admin_order_switch_customizer.md +++ /dev/null @@ -1,73 +0,0 @@ -# 【管理后台·前端对接】订单「切换定制师」新接口(本人/超管可改,售后及退款审批中拦截) - -> **类型**: 后端新增接口(hl-admin 管理后台对接) -> **仓库**: hl-admin(管理后台前端) -> **日期**: 2026-06-02 -> **工单**: #3348 ｜ **PR**: #3349 + #3350(路由修复) -> **状态**: ✅ 已合并 dev → 同步 dev-v3 → 部署测试服 → **测试服 API 已实测通过** -> **背景**: 前端新增「切换定制师」弹窗,需要专门的切换接口 + 候选定制师下拉。 - ---- - -## 一、两个接口(均走网关 `/admin/order/**`,已实测可达) - -### 1. 候选定制师列表(弹窗下拉) - -``` -GET /admin/order/customizer-candidates -``` - -- 返回所有**活跃(ACTIVE)的 CUSTOMIZER 角色**管理员,供弹窗下拉选择新定制师。 -- 响应 `data` 为数组,每项: - -```json -{ - "customizerId": "2021059720172838914", // 定制师管理员ID(雪花ID, 字符串) - "customizerName": "王骁", // 显示名(优先企微昵称, 兜底用户名) - "avatarUrl": "https://.../avatar.jpg" // 头像URL, 可能为 null -} -``` - -> 注:`customizerId` 是雪花 Long,JSON 里以**字符串**返回(避免 JS 精度丢失),回传时按字符串/数字均可。 - -### 2. 切换定制师 - -``` -PUT /admin/order/{orderId}/switch-customizer -Content-Type: application/json - -{ "customizerId": 1002 } -``` - -> ⚠️ **路径是 `/switch-customizer`,不是 `/customizer`**。 -> `PUT /admin/order/{orderId}/customizer` 是**已有的「转派定制师」(待办模块)**接口,无权限/退款校验,本次**不要**用它。新弹窗请用 `/switch-customizer`。 - -- 成功:`code=200`。订单 `customizerId` / `customizerName` 更新,相关定制师待办自动重新分配,并写入订单时间线。 - -## 二、业务规则(后端强制,前端按提示展示即可) - -| 规则 | 行为 | 错误码 | -|------|------|--------| -| 权限 | 仅**原定制师本人**或**超级管理员(SUPER_ADMIN)**可切换 | `502503` 无权切换定制师,仅原定制师本人或超级管理员可操作 | -| 售后/退款拦截 | 订单**售后中**或**有进行中退款审批(退款申请/退款申诉)**时禁止切换 | `502504` 订单售后中或有退款审批进行中,不能切换定制师 | -| 其余状态 | 待支付/已支付/旅行中/已完成/已取消 等**均可**切换 | — | -| 必填 | `customizerId` 不传 | `400` customizerId 不能为空 | - -- 前端建议:对**非本人且非超管**的用户隐藏/置灰「切换定制师」按钮(后端也会兜底拦截 502503)。 -- 订单处于售后/退款审批中时,按钮可置灰或点击后展示 502504 文案。 - -## 三、测试服实测结果(2026-06-02) - -| 用例 | 结果 | -|------|------| -| GET 候选列表 | ✅ 200,返回 19 个活跃定制师(id/名称/头像) | -| 超管切换「已完成」订单 | ✅ 200,订单 customizerId/Name 已更新并持久化 | -| 切换「退款中」订单 | ✅ 502504 拦截 | -| customizerId 缺失 | ✅ 400「customizerId 不能为空」 | - -> 权限「非本人非超管→502503」「原定制师本人→成功」由后端单元测试覆盖(测试环境仅有超管账号,API 层未单独跑该两条)。 - -## 四、联调地址 - -- 网关:`https://api.test.1814.love:9443` -- Knife4j 文档同地址,tag「[admin] 订单接口」下可见 `切换定制师` / `可选定制师列表`。 diff --git a/changelogs/2026-06/02_fix_product_action_endpoint_reject_publish.md b/changelogs/2026-06/02_fix_product_action_endpoint_reject_publish.md deleted file mode 100644 index e1744fb..0000000 --- a/changelogs/2026-06/02_fix_product_action_endpoint_reject_publish.md +++ /dev/null @@ -1,51 +0,0 @@ -# 【管理后台】废弃的产品状态变更端点 `/{id}/action` 现拒绝上架/下架方向动作 - -> **类型**: 后端安全收敛(废弃端点动作白名单) -> **服务**: hl-product-service-v2 -> **日期**: 2026-06-01 -> **影响范围**: `POST /admin/product/item/{id}/action`(产品状态变更-旧端点) -> **归属**: 后端已改(PR #3292 + #3297 → dev,已同步 dev-v3) -> **状态**: 已部署测试服并验证通过 -> **关联工单**: 无(审计驱动修复) -> **需前端配合**: ⚠️ 是(若管理后台仍在用该旧端点做上架/下架) - ---- - -## 一、背景(安全问题) - -审计发现旧端点 `POST /admin/product/item/{id}/action` 把前端传入的 `action` 直接喂给状态机,**未做动作合法性收敛**。任何持有该产品数据权限的普通管理员,只要传 `action=DIRECT_PUBLISH`,即可: - -- 跳过审批流程 -- 跳过行程完整性 / 车型必填的硬校验 -- 把一个行程为空的产品**瞬间上架**到小程序端 - -属于「审批绕过 + 越权 + 校验缺失」三合一,必须收敛。 - -## 二、后端改动 - -该端点本就标了 `@Deprecated`。现在加入**动作白名单**: - -- ✅ **仅放行** `WITHDRAW`(撤回,PENDING_REVIEW → DRAFT,把权限往回收,无风险) -- ❌ **拒绝** 所有上架/下架/审批方向动作(`DIRECT_PUBLISH` / `SUBMIT_PUBLISH` / `UNPUBLISH` / `FORCE_UNPUBLISH` 等),返回: - -```json -{ "code": 400406, "message": "动作「DIRECT_PUBLISH」不允许通过该接口执行，上架/下架请改用 toggle-publish 接口", "success": false } -``` - -## 三、前端需要做(mmg) - -**如果管理后台目前是用 `/{id}/action` 这个端点做产品上架/下架/提交审批,需要改用下面的专用端点**(这些端点已存在、且内置了审批 + 完整性校验 + 超管权限判断,是正确做法): - -| 原来(旧端点)走 action | 改用专用端点 | -|---|---| -| 上架 / 下架(`DIRECT_PUBLISH`/`SUBMIT_PUBLISH`/`UNPUBLISH`/`FORCE_UNPUBLISH`) | `POST /admin/product/item/{id}/toggle-publish`(后端按当前状态 + 操作人角色自动判方向:超管直接上下架,普通用户走提交审批) | -| 完成设计(CUSTOM 定制产品) | `POST /admin/product/item/{id}/complete` | -| 撤回(PENDING_REVIEW → DRAFT) | 仍可用 `/{id}/action` 传 `WITHDRAW`,或一并迁到对应交互 | - -> 如果管理后台**已经在用 `toggle-publish` / `complete`**(而 `/action` 只用于撤回或根本没在用),则**无需任何改动**,本次纯属后端堵漏。请前端确认一下当前上架/下架走的是哪个端点。 - -## 四、测试服实测(经网关 9443 + 真 admin token) - -- `action=DIRECT_PUBLISH` → `400406` 拒绝,产品未上架 ✓ -- `action=SUBMIT_PUBLISH` → `400406` 拒绝 ✓ -- `action=WITHDRAW` → `200 状态变更成功`(正常放行) ✓ diff --git a/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md b/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md deleted file mode 100644 index e89486c..0000000 --- a/changelogs/2026-07/12_feat_grassland_guide_admin_mp_oss.md +++ /dev/null @@ -1,412 +0,0 @@ -# 草原指南管理、OSS 素材上传与小程序接口（一期） - -> 日期：2026-07-12 -> -> 后端 Issue：[HL #4919](https://git.1814.love:8443/wx/HL/issues/4919)、[HL #4922](https://git.1814.love:8443/wx/HL/issues/4922)、[HL #4927](https://git.1814.love:8443/wx/HL/issues/4927)、[HL #4940](https://git.1814.love:8443/wx/HL/issues/4940)、[HL #4949](https://git.1814.love:8443/wx/HL/issues/4949) -> -> 后端 PR：[HL #4921](https://git.1814.love:8443/wx/HL/pulls/4921)、[HL #4924](https://git.1814.love:8443/wx/HL/pulls/4924)、[HL #4929](https://git.1814.love:8443/wx/HL/pulls/4929)、[HL #4930](https://git.1814.love:8443/wx/HL/pulls/4930)、[HL #4946](https://git.1814.love:8443/wx/HL/pulls/4946)、[HL #4948](https://git.1814.love:8443/wx/HL/pulls/4948)、[HL #4953](https://git.1814.love:8443/wx/HL/pulls/4953)、[HL #4958](https://git.1814.love:8443/wx/HL/pulls/4958) -> -> 测试分支：`dev-v3` -> -> 正式环境：一期发布时沿用本文契约 - -## 1. 最终方案 - -草原指南是独立的内容管理模块，视频文件仍统一进入素材库，不再使用阿里云 VOD。 - -- 后台新增一级菜单“草原指南管理”。 -- 素材库新增系统内置顶级分类“草原指南”，固定编码 `grassland_guide`。 -- 草原指南视频只接受 OSS 原始 `.mp4`，一个视频只返回一个 `videoUrl` 点播地址。 -- `videoUrl` 不是直播流，也不是 HLS/M3U8、FLV 或 VOD 播放地址；它是 OSS 原始 MP4 的 HTTPS 地址，通过 HTTP Range 分段读取。 -- 不转码、不生成多档清晰度、不接入 VOD/直播播放 SDK、不请求播放凭证、不切换 OSS 自定义域名。 -- 视频和封面都只能由后台管理员上传；小程序用户没有上传接口和上传权限。 -- 视频可以单独上传一张图片作为封面；未指定时由 OSS 自动截取视频首帧。 -- 小程序列表支持分页，详情直接把 `videoUrl` 交给原生 `<video>` 组件播放。 -- 相关推荐由后端自动计算，并提供独立分页接口供前端滑动加载；后台不再手工选择推荐内容。 -- 视频时长和首次发布时间均为只读字段：时长从视频素材派生，发布时间在首次发布时由后端生成。 -- 原型没有“呼籁出品”角标开关，管理端和小程序端均不提供 `showProducedBadge` 字段；前端不要提交、读取或展示该字段。 -- 管理端可以通过 `loginRequired` 控制单条视频是否要求小程序用户登录；未设置时默认为 `false`。 -- 草原指南内容可以绑定产品；小程序卡片返回 `linkedProductId` 和后端聚合出的 `linkedProductType`。 -- 前端不参与数据库乐观锁，创建、更新、发布、下架均不提交 `version`；发布和下架接口没有请求体。 - -前端必须删除旧版草原指南 VOD 方案中的以下内容： - -- `/admin/grassland-guide/vod/**` -- `/mp/grassland-guide/videos/{videoId}/play-auth` -- `vodFileId`、`playAuth`、`expiresInSeconds` -- 阿里云 VOD Web SDK、转码状态轮询、清晰度选择器 - -## 2. 菜单、分类与权限 - -### 2.1 后台菜单 - -- 菜单名称：`草原指南管理` -- 菜单路径：`/grassland-guide` -- 菜单权限：`grassland-guide:list` - -按钮权限： - -| 功能 | 权限码 | -|---|---| -| 新增 | `grassland-guide:create` | -| 编辑 | `grassland-guide:edit` | -| 发布 | `grassland-guide:publish` | -| 下线 | `grassland-guide:offline` | -| 设置主推 | `grassland-guide:featured` | -| 上传视频 | `grassland-guide:video:upload` | - -默认授权角色为 `SUPER_ADMIN`、`OPERATOR`。 - -### 2.2 素材库分类 - -- 显示名称：`草原指南` -- 固定编码：`grassland_guide` -- 分类性质：系统内置顶级分类 -- 用途：视频、视频封面、正文图片 -- 约束：不能删除、停用或修改固定编码；后台错误码为 `210405` - -前端应隐藏该顶级分类的删除、停用和修改编码入口。视频素材、封面图片都上传到这个分类；不需要创建“小程序专用”子分类。 - -## 3. 视频上传流程 - -### 3.1 视频时长由后端自动提取 - -前端申请上传凭证和确认上传时均不提交 `durationSeconds`，管理端也不提供可编辑时长输入框。 - -上传确认阶段由后端通过 OSS Range 读取 MP4 的 `moov` 元数据，自动计算并保存向上取整后的秒数；不下载体积最大的 `mdat` 视频内容。确认成功后，前端只读展示素材或草原指南详情返回的 `durationSeconds`。 - -视频上传校验的最新完整契约见独立 changelog：[`13_fix_grassland_guide_mp4_progressive_gate.md`](./13_fix_grassland_guide_mp4_progressive_gate.md)。 - -### 3.2 获取素材上传凭证 - -`POST /admin/material/upload/token` - -请求示例： - -```json -{ - "categoryCode": "grassland_guide", - "materialName": "呼伦贝尔草原上的风为什么特别大？", - "filename": "hulunbuir-wind.mp4", - "fileSize": 12925261, - "md5": "32位文件MD5", - "contentType": "video/mp4" -} -``` - -草原指南视频的强制校验： - -- `categoryCode` 必须是 `grassland_guide`。 -- 文件扩展名必须是 `.mp4`。 -- `contentType` 必须以 `video/mp4` 开头。 -- 不提交 `durationSeconds`；服务端不采信客户端时长。 -- 单个视频最大 `2147483648` 字节（2 GiB），大于 `10485760` 字节（10 MiB）时使用 OSS 分片上传。 - -响应中的 `uploadMode` 有两种： - -- `PRESIGNED_URL`：使用响应中的 `uploadUrl` 执行 `PUT`。 -- `STS_MULTIPART`：使用 `stsToken`、`bucket`、`region`、`ossKey` 分片上传。 - -无论哪种模式，上传时的 `Content-Type` 都必须使用接口返回的 `contentType`。STS 临时密钥只能保存在内存中，不能写入日志或本地存储。 - -若 `instantUpload=true`，直接使用响应中的 `material`，不再上传文件，也不调用确认接口。 - -### 3.3 上传完成后确认素材 - -`POST /admin/material/upload/confirm` - -```json -{ - "materialId": "2076195939797688322", - "description": "草原指南视频", - "tagIds": [] -} -``` - -确认接口会通过 OSS `HeadObject` 和 Range 读取实际对象元数据及 MP4 `moov`，并校验： - -- OSS 对象必须真实存在。 -- 实际 `Content-Length` 必须等于申请上传凭证时声明的 `fileSize`。 -- MP4 的实际 `Content-Type` 必须是 `video/mp4`（允许携带参数）。 -- MP4 满足 `ftyp < moov < mdat`，且包含一条 H.264 视频轨和一条 AAC-LC 音频轨。 -- 服务端自动计算 `durationSeconds`，成功状态为 `OSS_MP4_READY_V1`。 - -任一校验失败时素材不会进入可用状态。确认成功后保存返回的 `materialId`，创建草原指南内容时作为 `videoMaterialId` 提交。 - -### 3.4 文件夹上传 - -如素材库继续支持文件夹批量上传，草原指南视频同样不提交 `durationSeconds`；每个视频仍必须完成上传确认并取得 `OSS_MP4_READY_V1` 后才能用于新建或替换草原指南内容。 - -## 4. 视频封面 - -封面图片同样通过素材库通用上传接口上传到 `grassland_guide`，图片不传 `durationSeconds`。 - -- 指定 `customCoverMaterialId`：详情返回 `coverSource=CUSTOM`，使用管理员上传的图片。 -- 不指定或清空 `customCoverMaterialId`：详情返回 `coverSource=AUTO`，后端使用视频素材的 OSS 自动截帧地址。 - -OSS 自动封面格式： - -```text -{videoUrl}?x-oss-process=video/snapshot,t_0,f_jpg,w_800,m_fast -``` - -前端只使用响应中的 `effectiveCoverUrl`/`coverUrl`，不要自行拼接处理参数。 - -## 5. 草原指南管理接口 - -基础路径：`/admin/grassland-guide/videos` - -| 方法 | 路径 | 说明 | -|---|---|---| -| `GET` | `/admin/grassland-guide/videos` | 分页列表 | -| `GET` | `/admin/grassland-guide/videos/{videoId}` | 详情 | -| `POST` | `/admin/grassland-guide/videos` | 创建草稿 | -| `PUT` | `/admin/grassland-guide/videos/{videoId}` | 全量更新，不传 `version` | -| `PUT` | `/admin/grassland-guide/videos/{videoId}/publish` | 发布/重新发布 | -| `PUT` | `/admin/grassland-guide/videos/{videoId}/offline` | 下线 | - -创建或全量更新的主体： - -```json -{ - "title": "呼伦贝尔草原上的风为什么特别大？", - "summary": "视频摘要", - "videoMaterialId": "2076195939797688322", - "customCoverMaterialId": "2076196060279070722", - "contentHtml": "<p>正文内容</p>", - "contentImageMaterialIds": [], - "featured": true, - "sortWeight": 3, - "linkedProductId": "2076196082752155649", - "loginRequired": false -} -``` - -创建和更新使用同一组业务字段，均不提交 `version`。创建时不传 `loginRequired` 按 `false` 处理；更新时不传则保留原值。`publish`、`offline` 只传路径参数 `videoId`，不要发送空对象或版本请求体。创建草稿允许内容暂时不完整，发布时必须满足： - -- 标题、视频素材和有效封面完整。 -- 视频素材为正常状态的 `grassland_guide` OSS MP4。 -- 视频存在 `ossUrl`、`thumbnailUrl` 和正数时长。 -- 正文包含有效文字或正文图片。 - -管理端不再提交 `publishTime`、`durationSeconds`、`relatedVideoIds`： - -- `durationSeconds` 从当前 `videoMaterialId` 对应的视频素材自动派生。 -- `publishTime` 在首次点击发布时由后端写入；后续编辑、下架和重上架都保留首次值。 -- 相关推荐在小程序查询时自动生成，没有其他候选也不阻止当前内容发布。 -- `sortWeight` 数值越小越靠前，影响精选 Hero 位及相关内容同分时的弱排序。 - -后台详情返回新增字段： - -```json -{ - "videoMaterialId": "2076195939797688322", - "videoUrl": "https://.../the-daily-dweebs-1080.mp4", - "customCoverMaterialId": "2076196060279070722", - "coverSource": "CUSTOM", - "effectiveCoverUrl": "https://.../cover.jpg", - "durationSeconds": 61, - "publishTime": "2026-07-12 14:44:56", - "linkedProductId": "2076196082752155649", - "loginRequired": false -} -``` - -`durationSeconds`、`publishTime` 在 Knife4j 中均标记为只读。 - -所有雪花 ID 在 JavaScript 中都按字符串处理，避免超过安全整数范围。 - -## 6. 小程序接口 - -小程序提供四个只读接口： - -| 方法 | 路径 | 说明 | -|---|---|---| -| `GET` | `/mp/grassland-guide/home?page=1&pageSize=20` | 精选区与视频分页 | -| `GET` | `/mp/grassland-guide/videos?page=1&pageSize=20` | 视频分页列表 | -| `GET` | `/mp/grassland-guide/videos/{videoId}` | 视频详情 | -| `GET` | `/mp/grassland-guide/videos/{videoId}/recommendations?page=1&pageSize=20` | 自动推荐分页，供滑动加载 | - -分页规则： - -- `page` 默认 `1`，小于 `1` 时按 `1` 处理。 -- `pageSize` 默认 `20`，最大 `100`。 -- 只返回已发布内容，按发布时间倒序。 -- 标准分页字段为 `records`、`total`、`page`、`pageSize`；当前响应不返回 `totalPages`，需要时由前端计算。 - -详情直接返回 OSS 原视频地址： - -```json -{ - "videoId": "2076196082752155649", - "title": "草原指南测试｜The Daily Dweebs", - "videoUrl": "https://.../the-daily-dweebs-1080.mp4", - "durationSeconds": 61, - "coverSource": "CUSTOM", - "coverUrl": "https://.../cover.jpg", - "contentHtml": "<p>正文内容</p>", - "linkedProductId": "2076196082752155649", - "linkedProductType": "CORE", - "loginRequired": false -} -``` - -首页、列表、详情和推荐卡片均返回以下业务字段： - -- `linkedProductId`：字符串，可空；绑定的产品 ID。 -- `linkedProductType`：`CORE`、`GROUP`、`CUSTOM` 之一，可空。未绑定、产品不存在或产品服务暂时不可用时为空，草原指南内容仍正常返回。 -- `loginRequired`：布尔值；为 `true` 时必须先登录才能读取详情和播放。 - -鉴权规则： - -- 首页、分页列表、相关推荐分页继续允许匿名访问，卡片只返回展示字段，不返回正文和播放地址。 -- 详情接口使用可选登录：`loginRequired=false` 时匿名返回 `200`；为 `true` 时匿名返回业务码 `401`，合法用户 JWT 返回 `200`。 -- 前端遇到详情业务码 `401` 时拉起小程序登录，成功后携带新 token 重试原详情请求。 -- 客户端提交的 `X-User-Id`、`X-User-Type`、`X-Auth-Level` 和管理员身份头均不可信，网关会删除后仅依据有效 JWT 重建身份。 -- MP 详情不使用跨用户缓存，防止受保护视频的详情或 `videoUrl` 被匿名请求复用。 - -详情不再返回固定数组 `relatedVideos`。进入相关推荐区域时，请求独立分页接口： - -```json -{ - "records": [ - { - "videoId": "2076196084920610817", - "title": "草原指南测试｜Caminandes 3：Llamigos", - "summary": "Blender 官方真实短片", - "coverUrl": "https://.../auto-cover.jpg", - "coverSource": "AUTO", - "durationSeconds": 151 - } - ], - "total": 2, - "page": 1, - "pageSize": 1 -} -``` - -推荐排序规则： - -1. 仅使用 `PUBLISHED` 内容，排除当前视频、已删除内容和重复项。 -2. 同一 `linkedProductId`（关联行程/产品）优先。 -3. 再按标题、摘要内容相似度排序。 -4. `featured`、`sortWeight`、`publishTime` 只做弱排序。 -5. 其余已上架内容使用稳定随机顺序兜底。 - -候选集合不变时各页顺序稳定且不重不漏。若管理员恰好在用户翻页期间发布或下架内容，标准 offset 分页边界可能变化，前端应按 `videoId` 去重后追加。 - -小程序直接使用原生组件： - -```html -<video src="{{detail.videoUrl}}" controls></video> -``` - -这是 OSS 原始 MP4 点播/渐进式播放，不是直播流。前端不要接入直播播放器、`live-player`、FLV/HLS SDK，也不要把 `videoUrl` 转成 M3U8。OSS MP4 支持 Range 请求，原生 `<video>` 能从 MP4 元数据读取并显示当前播放时间、总时长和进度条。卡片时长使用接口的 `durationSeconds` 格式化即可，不做清晰度切换。 - -## 7. 测试环境验收结果 - -`dev-v3` 已于 2026-07-12 完成部署和真实数据验证： - -- `hl-resource-service`：`8082/8182`，Nacos `2/2` 健康。 -- `hl-mp-service`：`8085/8185`，Nacos `2/2` 健康。 -- `hl-gateway`：`8080/8180`，Nacos `2/2` 健康。 -- `hl-user-service`：`8081/8181`，Nacos `2/2` 健康。 -- User Flyway `20260712.005` 执行成功；Resource Flyway `20260712.001` 执行成功。 -- Knife4j 已展示草原指南管理接口、素材上传接口及只读字段；小程序文档为上述 4 个 GET。 -- `POST /admin/material/upload/token`、`POST /admin/material/upload/confirm` 的请求体，以及详情/推荐路径中的 `videoId`，均在 Knife4j 中明确标记为必填。 - -真实数据： - -| 内容 | 素材 ID | 内容 ID | 时长 | 封面 | -|---|---|---|---:|---| -| The Daily Dweebs | `2076195939797688322` | `2076196082752155649` | 61 秒 | `CUSTOM` | -| Caminandes 3: Llamigos | `2076195998660550657` | `2076196084920610817` | 151 秒 | `AUTO` | -| Glass Half | `2076196033146118145` | `2076196086652858370` | 194 秒 | `AUTO` | -| 呼伦贝尔草原有多大？（3812×2160 原片） | `2076248042813480962` | `2076248969276551170` | 83 秒 | `CUSTOM` | - -验收结果： - -- 三个文件都是不同的 Blender 官方真实作品，不是同一视频的多档清晰度。 -- 三个视频均通过 `STS_MULTIPART` 上传，分类为 `grassland_guide`，存储方为 `OSS`。 -- 自定义封面通过 `PRESIGNED_URL` 上传。 -- MP4 Range 请求均返回 `206 video/mp4`。 -- 自定义封面和 OSS 自动封面均返回 `200 image/*`。 -- 小程序 `pageSize=2` 实测分页为第 1 页 2 条、第 2 页 1 条，无重复。 -- 三个详情均直接返回 `videoUrl` 和正确时长，且不再包含 `relatedVideos`。 -- 三个推荐分页均为 `total=2`；按 `pageSize=1` 加载两页，无自身、无重复，重复请求顺序一致。 -- 实测下架其中一条后推荐 `total` 从 2 变为 1，候选中不含下架内容；重上架后恢复为 2。 -- 故意提交伪造 `publishTime=2000年`、`durationSeconds=9999` 和旧 `relatedVideoIds`，后端均未采纳；下架重上架后首次发布时间保持不变。 -- 旧 `/play-auth` 接口已不可用。 -- 真实 4K 原片为 `412360919` 字节（约 393 MiB），通过 `STS_MULTIPART` 上传；OSS `HEAD` 返回 `200`、`Content-Type: video/mp4`、`Content-Length: 412360919`。 -- 对 4K 原片请求 `Range: bytes=0-1` 返回 `206`、`Content-Range: bytes 0-1/412360919`，证明 OSS 支持原生 `<video>` 所需的分段读取，流量不经过业务服务器。 -- 4K 内容使用独立上传的 JPEG 封面，详情返回 `coverSource=CUSTOM`；推荐分页返回 3 条上架内容且排除了当前视频。 -- 当前测试桶默认域名同时返回 `Content-Disposition: attachment` 和 `x-oss-force-download: true`。HTTP Range 能正常工作，但小程序仍须做真机播放验收。2026-07-13 最终决定保持默认 OSS 域名，不切换自定义域名；前端不得自行改写域名，若原生 `<video>` 真机播放失败，保留错误码与设备信息后反馈后端处理。 -- 2026-07-13 已从管理端和小程序端完整删除 `showProducedBadge`：Resource/MP OpenAPI 均无该字段，首页、列表、详情、推荐 4 个实际接口均返回 `200` 且无该字段；Resource Flyway `20260713.001` 执行成功，遗留数据库列已删除。 -- 2026-07-13 PR #4953 已合入 `dev-v3`，并按 `hl-gateway` → `hl-mp-service` → `hl-resource-service` 部署测试环境；三项服务均完成双实例滚动升级。该 PR 补齐产品绑定字段、单条内容登录鉴权并移除前端 `version` 契约。 -- 2026-07-13 PR #4958 已将 `dev@73e25cf61` 的完整交付链同步回 `dev-v3@6b7775ab`。该 PR 文件差异为 0，合并前后代码树一致；随后仅在测试环境按 `hl-mp-service` → `hl-gateway` → `hl-resource-service` 再次串行滚动发布，任务分别为 `f9159fab`、`655b9b6e`、`40bacc94`，三项服务 Nacos 均为 `2/2` 健康。 -- 本轮真实接口复验确认管理端列表/详情与小程序列表/详情/推荐均成功；管理端和草原指南小程序契约均无前端 `version`，推荐分页排除自身且不重复。 -- 2026-07-13 已补充受保护真实 4K 测试内容：匿名详情返回 `401`，伪造 `X-User-Id` 仍返回 `401`，有效小程序 USER token 返回 `200`；关闭 `loginRequired` 后匿名详情恢复 `200`。测试 token 仅在 TEST 宿主机本地 Redis 通过 `SCAN` 读取并在内存中使用，未输出、未落盘。 -- 音画同步不能仅凭 OSS `HEAD` 或 `Range 206` 判定通过。当前仍为 OSS 4K 原片直出，目标机型真机播放验收须单独记录；未经真机验证不得标记“音画同步已修复”。 - -## 8. 2026-07-14 正式环境 Nacos 部署清单 - -草原指南一期不使用 CDN、自定义 OSS 域名、VOD、直播流、HLS 或转码。2026-07-13 已只读确认正式 Nacos 的视频上限和分片阈值均已是目标值，正式部署时只复核，不重复覆盖配置。部署 `hl-user-service` 前执行： - -1. 在正式 Nacos 读取并备份完整 `hl-user-service-prod.yml`，确认生产实例实际加载的 namespace、group 和 dataId。 -2. 复核以下配置；当前值一致时不要发布 Nacos 变更： - -```yaml -file: - max-size: - video: 2147483648 - resumable-threshold: 10485760 -``` - -3. 不复制仓库内测试配置中的其他值，不覆盖正式环境已有的 OSS、数据库、Redis 或鉴权配置。 -4. 保持正式 `oss.domain` 为当前默认 Bucket 域名，不切换 `oss.aly.1814.love` 或其他自定义域名。 -5. 串行滚动部署 `hl-user-service`，确认两实例均注册健康且配置已生效。 -6. 用正式 OSS 做一轮大于 10 MiB 的 MP4 分片上传、确认、`HEAD` 和 `Range 206` 验收；不得在日志或交付文档中记录 STS、AccessKey、Token 等凭证。 - -### 8.1 `showProducedBadge` 删除的正式环境两阶段发布 - -正式环境必须把应用字段收缩与数据库删列分两次发布，不能将两个阶段合成一次滚动部署： - -1. 先将 PR [#4946](https://git.1814.love:8443/wx/HL/pulls/4946) 的应用层变更单独合入正式目标分支。 -2. 依次滚动部署 `hl-resource-service`、`hl-mp-service`，确认两服务的全部正式实例都已升级且健康；此阶段数据库列仍保留。 -3. 验证正式 OpenAPI 和草原指南首页、列表、详情、推荐响应均不再含 `showProducedBadge`。 -4. 再将 PR [#4948](https://git.1814.love:8443/wx/HL/pulls/4948) 的 `V20260713_001` 迁移合入正式目标分支，只滚动部署 `hl-resource-service`。 -5. 确认 Flyway `20260713.001` 成功、`show_produced_badge` 列不存在、资源服务全部实例健康，再结束发布。 - -若正式目标分支已经同时包含 #4946 和 #4948，不得直接按该分支首次启动旧实例集群；应先准备仅包含 #4946 的中间发布版本完成步骤 1～3，再切换到包含 #4948 的最终版本。该变更不涉及 Nacos 配置修改。 - -### 8.2 登录鉴权与产品字段正式发布门禁 - -PR #4953 不新增 Nacos 配置。正式发布最终版本时按以下顺序滚动： - -1. `hl-mp-service`：先移除详情缓存并上线产品字段聚合。 -2. `hl-gateway`：上线草原详情 `OPTIONAL` 鉴权和客户端身份头清洗。 -3. `hl-resource-service`：最后执行 Flyway `20260713.002` 并启用单条内容登录判断。 - -所有 Resource 实例完成升级前，不得把任何正式视频设置为 `loginRequired=true`。回滚旧 Resource 前应先把受保护视频改为公开或下架，否则旧代码不识别该字段，可能重新暴露详情。正式 `main` 尚未发布时，本节仅作为发布门禁，不代表已部署。 - -## 9. 前端改造检查单 - -- [ ] 新增“草原指南管理”列表、编辑和发布页面。 -- [ ] 素材库展示顶级分类“草原指南”，隐藏系统分类删除/停用/改码操作。 -- [ ] 不提交视频 `durationSeconds`；上传确认后只读展示后端自动提取的时长，不允许手填。 -- [ ] 使用素材库通用上传接口处理 `PRESIGNED_URL` 和 `STS_MULTIPART`。 -- [ ] 支持单独上传/选择图片作为自定义封面，并允许清空后恢复自动封面。 -- [ ] 草原指南内容保存 `videoMaterialId`，不保存 VOD 字段。 -- [ ] 不展示“呼籁出品”开关或角标，不提交、不读取 `showProducedBadge`。 -- [ ] 创建/编辑页增加“需要登录后查看”开关并提交 `loginRequired`，默认关闭。 -- [ ] 删除草原指南所有 `version` 状态、请求参数和发布/下架请求体。 -- [ ] 保存关联产品 ID；按小程序返回的 `linkedProductId`、`linkedProductType` 跳转对应产品。 -- [ ] 发布日期只读：草稿显示未发布，首次发布成功后刷新详情回显后端时间。 -- [ ] 删除管理员手工选择相关推荐的控件，不提交 `relatedVideoIds`。 -- [ ] 小程序列表接入分页参数和分页结果。 -- [ ] 小程序详情直接使用 `videoUrl` 播放。 -- [ ] 卡片读取 `loginRequired`；进入受保护详情前触发登录，详情返回业务码 `401` 时登录后重试。 -- [ ] 将 `videoUrl` 作为 OSS 原始 MP4 点播地址处理，不接 `live-player`、直播 SDK、FLV/HLS/M3U8 转换或自定义域名替换逻辑。 -- [ ] 相关推荐通过独立分页接口滑动加载，并按 `videoId` 去重追加。 -- [ ] 删除 VOD SDK、`play-auth` 调用和清晰度切换 UI。 -- [ ] 所有雪花 ID 均按字符串处理。 diff --git a/changelogs/2026-07/13_feat_grassland_guide_delete.md b/changelogs/2026-07/13_feat_grassland_guide_delete.md deleted file mode 100644 index 5680df0..0000000 --- a/changelogs/2026-07/13_feat_grassland_guide_delete.md +++ /dev/null @@ -1,89 +0,0 @@ -# 草原指南管理删除能力（草稿/下架可删） - -> 日期：2026-07-13 -> -> 后端 Issue：[HL #4959](https://git.1814.love:8443/wx/HL/issues/4959) -> -> 历史 PR：[HL #4960](https://git.1814.love:8443/wx/HL/pulls/4960)、[HL #4963](https://git.1814.love:8443/wx/HL/pulls/4963) 实现的是旧规则，已被本次业务口径纠正取代 -> -> 纠正 PR：[HL #4967](https://git.1814.love:8443/wx/HL/pulls/4967) 已合入 `dev`；[HL #4968](https://git.1814.love:8443/wx/HL/pulls/4968) 已由 `dev` 合入 `dev-v3` -> -> 当前状态：TEST 双实例部署与真实接口验收通过；尚未合入 `main`、尚未部署正式环境 - -## 1. 变更范围 - -草原指南管理提供删除接口。业务规则固定为：**未上线内容可以删除，其中草稿（`DRAFT`）和已下架（`OFFLINE`）允许删除；已上线（`PUBLISHED`）不允许删除**。 - -本文件只说明删除能力，不包含 MP4 上传兼容校验、视频时长提取等媒体变更；媒体变更会使用另一份独立 changelog 告知。 - -## 2. 接口 - -`DELETE /admin/grassland-guide/videos/{videoId}` - -- 只提交路径参数 `videoId`。 -- 不发送请求体，也不提交 `version`。 -- 成功响应为平台统一成功包络，`data` 为空。 -- 后端内部使用状态和乐观锁控制并发，前端不维护版本号。 - -请求示例： - -```http -DELETE /admin/grassland-guide/videos/2076195939797688322 -``` - -## 3. 前端交互规则 - -- 当列表或详情的 `status` 为 `DRAFT` 或 `OFFLINE` 时展示“删除”按钮。 -- `PUBLISHED` 不展示删除按钮。 -- 点击删除前展示二次确认；确认后调用删除接口。 -- 删除成功后刷新当前列表；若正在详情页，应返回列表。 -- 不要因为界面已判断状态就忽略后端错误，仍需处理并发变更结果。 - -## 4. 权限 - -新增按钮权限码： - -```text -grassland-guide:delete -``` - -默认授权 `SUPER_ADMIN`、`OPERATOR`。前端同时依据按钮权限和业务状态决定是否展示删除入口。 - -## 5. 错误处理 - -| 业务码 | 含义 | 前端处理建议 | -|---|---|---| -| `371001` | 视频不存在或已经删除 | 提示内容不存在，并刷新列表 | -| `371002` | 删除过程中数据被其他管理员修改 | 提示刷新后重试 | -| `371008` | 已上线内容不允许删除 | 提示“已上线内容不能删除”，并刷新当前数据 | - -## 6. 数据语义 - -- 删除的是草原指南内容记录，不会删除对应的素材、文件或 OSS 对象。 -- 删除后该内容不再出现在管理端列表、详情和小程序接口中。 -- 后端会解除该内容对视频、封面和正文图片素材的引用。 -- 删除后不能通过重复调用接口恢复；如需再次使用素材，应重新创建草原指南内容。 - -## 7. 联调清单 - -后端新规则与 TEST 验收已完成，前端联调清单如下： - -- [x] `DRAFT`、`OFFLINE` 视频删除成功，管理端详情和小程序详情、列表均不再返回。 -- [x] `PUBLISHED` 直接调用删除接口返回 `371008`，数据和引用关系不变。 -- [x] 删除请求没有 body，也没有 `version`。 -- [x] 重复删除返回 `371001`。 -- [ ] 无 `grassland-guide:delete` 权限时不展示入口。 -- [ ] 管理端仅在 `DRAFT`、`OFFLINE` 状态展示删除入口，并完成二次确认交互。 -- [x] 删除内容后，素材库中的原视频和封面仍然存在。 - -TEST 后端证据（2026-07-14）： - -- 部署任务 `f007ee1f` 成功，资源服务 `8082/8182` 两实例均已更新、注册 Nacos 且健康。 -- 实时 OpenAPI 摘要为“草稿或已下架状态允许”，DELETE 仅含路径参数 `videoId`，无 body、无 `version`。 -- 验收内容：`DRAFT` 删除成功；`OFFLINE` 删除成功；`PUBLISHED` 返回 `371008` 且状态、版本、引用数、日志数完全不变；重复删除返回 `371001`。 -- `DRAFT` 发布/删除与 `OFFLINE` 重发/删除各执行一次真实并发竞争，两组均恰好一方成功，失败方返回 `371002`，最终状态与事务副作用正确。 -- 5 条验收内容均已逻辑删除，素材引用和推荐关系均无残留，每条仅产生一条 DELETE 领域日志，`fromStatus` 仅为 `DRAFT` 或 `OFFLINE`。 -- 真实 4K OSS 素材 `2076658080942116865` 的 `fileId`、OSS URL 与引用计数恢复基线，OSS `HEAD` 返回 200、文件大小 `412400073` 字节，未删除素材、文件或 OSS 对象。 -- `/admin/menu/my` 已返回 `grassland-guide:delete`，TEST 数据库已授权 `OPERATOR`、`SUPER_ADMIN`。 - -> 注意：前端不提交 `version`；并发控制由后端内部实现。前端只需按 `DRAFT/OFFLINE` 展示入口，并处理并发失败响应。 diff --git a/changelogs/2026-07/13_fix_grassland_guide_mp4_progressive_gate.md b/changelogs/2026-07/13_fix_grassland_guide_mp4_progressive_gate.md deleted file mode 100644 index 7eddda2..0000000 --- a/changelogs/2026-07/13_fix_grassland_guide_mp4_progressive_gate.md +++ /dev/null @@ -1,117 +0,0 @@ -# 草原指南视频上传校验与服务端时长 - -> 日期：2026-07-13 -> -> 后端 Issue：[HL #4949](https://git.1814.love:8443/wx/HL/issues/4949) -> -> 后端 PR：[HL #4961](https://git.1814.love:8443/wx/HL/pulls/4961)、[HL #4962](https://git.1814.love:8443/wx/HL/pulls/4962)、[HL #4964](https://git.1814.love:8443/wx/HL/pulls/4964) -> -> 测试合并：[HL #4963](https://git.1814.love:8443/wx/HL/pulls/4963)、[HL #4965](https://git.1814.love:8443/wx/HL/pulls/4965)，均按 `dev` → `dev-v3` 进入 TEST -> -> 当前状态：TEST 已部署并通过真实 4K 上传确认；尚未合入 `main`、尚未部署正式环境 - -## 1. 本文件只说明视频上传链路 - -删除功能、登录鉴权、产品绑定等接口分别由各自 changelog 说明，不与本次上传校验混写。 - -本次仅影响素材库顶级分类 `grassland_guide` 下的 MP4 视频： - -- 视频仍由前端直传 OSS，字节不经过 Resource/User Java 服务。 -- 播放仍使用详情接口返回的 OSS MP4 地址，不接入 CDN、VOD、直播或 HLS。 -- 不转码、不降低 4K 清晰度、不提供清晰度切换。 -- 后端自动读取视频时长；管理端不得提供可编辑时长输入框。 - -## 2. 获取上传凭证 - -`POST /admin/material/upload/token` - -```json -{ - "categoryCode": "grassland_guide", - "materialName": "呼伦贝尔草原上的风为什么特别大？", - "filename": "hulunbuir-wind-4k.mp4", - "fileSize": 412400073, - "md5": "32位文件MD5", - "contentType": "video/mp4" -} -``` - -前端注意： - -- 草原指南视频不提交 `durationSeconds`；即使提交，后端也会忽略。 -- 几百 MB 视频按响应中的 `uploadMode=STS_MULTIPART` 分片直传 OSS。 -- 不调用旧的 `/admin/material/chunk/**` 完成草原指南视频上传。 -- 若响应为秒传，后端也会重新核对文件类型、大小、OSS `Content-Type` 和媒体结构。 - -## 3. 确认上传 - -`POST /admin/material/upload/confirm` - -```json -{ - "materialId": "2076195939797688322", - "description": "草原指南视频", - "tagIds": [] -} -``` - -后端确认时只读取 OSS 对象元数据、MP4 顶层 box 和 `moov`，不下载 `mdat` 视频内容，并校验： - -- OSS 对象存在，实际大小与申请一致，`Content-Type` 为 `video/mp4`。 -- MP4 满足 `ftyp < moov < mdat`，可进行 faststart 渐进播放。 -- 恰好包含一条 H.264 视频轨和一条 AAC-LC 音频轨。 -- 从 `moov` 自动计算并保存 `durationSeconds`。 - -确认成功后，素材返回： - -```json -{ - "durationSeconds": 312, - "mediaStatus": "OSS_MP4_READY_V1", - "storageProvider": "OSS", - "ossUrl": "https://<bucket-domain>/<object-key>" -} -``` - -`durationSeconds`、`mediaStatus`、`storageProvider` 和 `ossUrl` 都是只读字段。`mediaStatus` 成功值只返回 `OSS_MP4_READY_V1`，前端不要增加其他成功状态分支。 - -## 4. 错误处理 - -| 业务码 | 含义 | 前端处理 | -|---|---|---| -| `250015` | OSS 元数据或 Range 探测暂时不可用，或并发状态发生变化 | 保留当前 `materialId`，允许稍后重复调用确认接口 | -| `250016` | 文件不是支持的 faststart H.264 + AAC-LC MP4 | 展示后端原因，要求管理员重新选择处理后的文件上传 | - -同一上传人对已确认的草原指南视频重复调用确认接口会幂等返回；普通素材的确认行为不变。 - -## 5. 使用门禁与历史兼容 - -- 新建草原指南内容时，`videoMaterialId` 必须绑定 `OSS_MP4_READY_V1` 视频素材。 -- 编辑时只有替换 `videoMaterialId` 才校验新素材；未替换的历史视频不追溯阻断。 -- 单个或批量移动素材分类不执行媒体门禁，也不会自动把普通历史视频标记为 `OSS_MP4_READY_V1`。 -- 图片素材、普通分类视频和其他模块的上传行为不变。 - -## 6. 播放验收边界 - -该校验只证明文件具备基础渐进播放结构，不承诺所有微信版本、所有 Android/iOS 设备都能流畅解码 4K 原片，也不把后端结构校验描述为“已解决音画同步”。 - -上线前必须用真实原片和无损 faststart 重排文件，在目标微信 Android/iOS 真机完成播放、拖动、暂停恢复和音画同步 A/B 验收。 - -## 7. 前端联调清单 - -- [x] 后端 OpenAPI 与真实请求确认：上传凭证不需要草原指南视频 `durationSeconds`。 -- [x] 412400073 字节真实 4K 文件使用 `STS_MULTIPART` 直传 OSS。 -- [ ] 管理端时长只读展示确认接口返回值。 -- [ ] 原始 `moov` 位于文件尾部的视频确认返回 `250016`。 -- [x] 无损 faststart 重排后的真实 4K 原片确认成功并返回 `OSS_MP4_READY_V1`、`durationSeconds=83` 和自动封面。 -- [x] 首次确认因 fat JAR 类加载问题失败后，使用同一个 `materialId=2076658080942116865` 重试成功，未重复上传 412 MB 文件。 -- [x] 新建草原指南已实测只接受 `OSS_MP4_READY_V1` 视频；历史原素材不变时仍可维护。 -- [ ] 微信 Android/iOS 真机完成原片与重排文件的 A/B 验收。 - -## 8. TEST 真实验证记录 - -- User 部署任务：`1a2a42da`，`dev-v3`，8081/8181 双实例滚动成功；Nacos `test` 命名空间两实例均为 `healthy=true`、`enabled=true`。 -- 素材：`2076658080942116865`，文件大小 `412400073`，存储方 `OSS`，媒体状态 `OSS_MP4_READY_V1`，服务端时长 `83` 秒，自动封面存在。 -- fat JAR 回归：通过 Spring Boot `PropertiesLauncher` 直接加载最终候选 JAR，并解析同一真实 4K `moov`，返回 `durationSeconds=83 / OSS_MP4_READY_V1`。 -- OSS Range：请求 `bytes=0-1023` 返回 HTTP `206`、1024 字节和 `Content-Range`。 -- 仍未据此宣称真机音画同步通过；默认 Bucket 域名的微信 Android/iOS 真机播放、拖动、暂停恢复与音画同步必须由前端单独验收。 diff --git a/changelogs/2026-07/14_feat_grassland_guide_operation_logs.md b/changelogs/2026-07/14_feat_grassland_guide_operation_logs.md deleted file mode 100644 index 95c4d7a..0000000 --- a/changelogs/2026-07/14_feat_grassland_guide_operation_logs.md +++ /dev/null @@ -1,139 +0,0 @@ -# 草原指南字段级操作记录与分页接口 - -> 日期：2026-07-14 -> -> 后端 Issue：[HL #4977](https://git.1814.love:8443/wx/HL/issues/4977) -> -> 发布范围：先合入 `dev`，再同步 `dev-v3` 并部署 TEST；当前不合入 `main`、不部署正式环境 - -## 1. 变更目的 - -草原指南编辑页原“操作记录”只有创建时间和最后编辑时间，无法说明谁修改了什么。本次新增独立分页接口，响应结构参考产品日志时间线，提供： - -- 操作类型和中文摘要； -- 操作所属页面区域； -- 操作人 ID、名称快照和操作时间； -- 本次真实变化的字段； -- 字段中文名、旧值、新值和变更类型； -- 富文本、正文图片和生效封面等长值的摘要与哈希。 - -## 2. 接口 - -```http -GET /admin/grassland-guide/videos/{videoId}/operation-logs?page=1&pageSize=20 -``` - -查询参数： - -| 参数 | 必填 | 默认值 | 规则 | -|---|---:|---:|---| -| `videoId` | 是 | - | 草原指南视频 ID | -| `page` | 否 | `1` | 最小 `1` | -| `pageSize` | 否 | `20` | `1-100` | - -分页顺序固定为 `createTime DESC, id DESC`，前端按 `records` 追加加载即可。只有 `SUPER_ADMIN`、`OPERATOR` 可以查询字段级历史值。 - -## 3. 响应示例 - -```json -{ - "code": 200, - "message": "success", - "data": { - "records": [ - { - "id": "2077195939797688322", - "videoId": "2076195939797688322", - "action": "UPDATE", - "actionLabel": "编辑", - "step": "BASIC", - "stepLabel": "基础信息", - "detail": "编辑基础信息", - "changedFields": ["title", "summary"], - "fromStatus": "PUBLISHED", - "toStatus": "PUBLISHED", - "operatorId": "10001", - "operatorName": "yangchunsheng", - "createTime": "2026-07-14 13:56:19", - "changes": [ - { - "field": "title", - "fieldLabel": "视频标题", - "oldValue": "草原指南验收", - "newValue": "草原指南验收｜草原蜱虫怎么预防和处理", - "changeType": "MODIFY", - "oldHash": null, - "newHash": null - } - ] - } - ], - "total": 12, - "page": 1, - "pageSize": 20 - }, - "success": true -} -``` - -## 4. 字段枚举 - -`action`： - -| 值 | `actionLabel` | 含义 | -|---|---|---| -| `CREATE` | 新建 | 创建草稿 | -| `UPDATE` | 编辑 | 更新内容或展示配置 | -| `PUBLISH` | 上线 | 首次发布或重新发布 | -| `OFFLINE` | 下线 | 已发布内容下线 | -| `DELETE` | 删除 | 删除草稿或已下架内容 | - -`step`： - -| 值 | 含义 | -|---|---| -| `BASIC` | 基础信息 | -| `CONTENT` | 图文正文 | -| `PUBLISH_SETTING` | 发布设置 | -| `DISPLAY_SETTING` | 展示设置 | -| `MULTIPLE` | 一次操作涉及多个区域，使用 `stepLabel` 展示具体区域 | - -`changeType`：`ADD`、`MODIFY`、`DELETE`。 - -## 5. 前端接入规则 - -- 编辑页打开时请求第一页，滚动到底部后按 `page + 1` 加载；不要一次拉取全部日志。 -- 时间线标题可使用 `actionLabel + stepLabel`，说明文本直接使用 `detail`。 -- 字段差异直接渲染 `changes[].fieldLabel/oldValue/newValue`，不要自行把字段英文名转换为中文。 -- 所有 `id`、`videoId`、`operatorId` 都按字符串处理。 -- `fromStatus`、`toStatus` 可为空；状态没有变化的编辑操作也可能两者相同。 -- 历史日志只有 `changedFields`，`changes` 会返回空数组；页面应展示动作、操作人和时间，不要报错。 -- 富文本正文不返回整篇 HTML；`oldValue/newValue` 是去标签后的摘要，`oldHash/newHash` 用于判断完整内容是否不同。 -- 正文图片返回“共 N 张”；生效封面返回脱敏摘要，例如 `封面#1a2b3c4d`，不会下发完整 OSS 地址。 -- 后端只记录真实变化字段；无变化字段不会出现在 `changes` 中。 - -## 6. 与既有接口的关系 - -- 草原指南列表、详情、创建、编辑、发布、下架和删除接口路径均不变。 -- 详情中的 `createdAt/updatedAt/createdBy/updatedBy` 保持兼容，但不再承担完整操作历史展示。 -- 本接口不返回、也不接收 `version`；前端继续不维护版本号。 -- 本文件只说明操作记录，不合并到素材上传、MP4 校验或删除功能的 changelog。 - -## 7. 联调清单 - -- [ ] 首次进入加载第一页，向下滚动可稳定分页且不重复。 -- [ ] 编辑标题、简介、正文、展示设置后可显示对应旧值和新值。 -- [ ] 发布、重新发布、下线和删除显示正确动作及状态变化。 -- [ ] 历史日志 `changes=[]` 时页面正常降级。 -- [ ] 非 `SUPER_ADMIN`、`OPERATOR` 角色不展示字段级操作历史入口。 - -## 8. 后端 TEST 验证（2026-07-14） - -- 后端 PR：[HL #4980](https://git.1814.love:8443/wx/HL/pulls/4980) 已合入 `dev`；[HL #4981](https://git.1814.love:8443/wx/HL/pulls/4981) 已由 `dev` 同步至 `dev-v3`。 -- TEST 部署任务 `5681477a` 成功，`hl-resource-service` 的 `8082/8182` 双实例均健康；部署内容与 `origin/dev-v3` 一致。 -- Flyway `20260714.001` 执行成功，`changes JSON`、`operator_name VARCHAR(64)` 已落库。 -- 真实 `EXPLAIN` 命中 `idx_ggol_video_time(video_id, operated_at, log_id)`，使用倒序索引扫描。 -- 受控业务 API 验收已完成：临时草稿执行 `CREATE → UPDATE → DELETE`，操作日志总数和顺序正确；标题、简介、正文、精选、登录鉴权、排序权重均返回真实旧值和新值。 -- `contentHtml` 只返回纯文本摘要和哈希，不返回原始 HTML；删除后详情返回 `371001`，该视频的三条历史日志仍可分页查询。 -- 以 `pageSize=1/2` 跨页验证未出现重复 ID；`8082/8182` OpenAPI 均只包含 `videoId/page/pageSize`，没有 `version`。 -- 以上是后端验收证据；第 7 节仍是前端接入自测清单，不以页面或按钮作为本后端工单关单条件。 diff --git a/changelogs/2026-07/14_fix_grassland_guide_operator_display_name.md b/changelogs/2026-07/14_fix_grassland_guide_operator_display_name.md deleted file mode 100644 index 4dfcaeb..0000000 --- a/changelogs/2026-07/14_fix_grassland_guide_operator_display_name.md +++ /dev/null @@ -1,44 +0,0 @@ -# 草原指南操作人名称展示规则修正 - -> 日期：2026-07-14 -> -> 后端 Issue：[HL #4983](https://git.1814.love:8443/wx/HL/issues/4983) -> -> 发布范围：先合入 `dev`，再同步 `dev-v3` 并部署 TEST；当前不合入 `main`、不部署正式环境 - -## 1. 变更内容 - -草原指南操作记录分页接口的路径、请求参数和响应结构均不变，仅修正 `operatorName` 的取值规则： - -```http -GET /admin/grassland-guide/videos/{videoId}/operation-logs?page=1&pageSize=20 -``` - -- 新产生的操作记录：优先保存当前管理员的企业微信姓名；未绑定企业微信或姓名为空时，保存管理员用户名。 -- 历史记录已有非空 `operatorName`：继续展示原快照，不随管理员后续改名而变化。 -- 历史记录的 `operatorName` 为空：后端按当前页涉及的管理员 ID 一次批量解析，企业微信姓名优先、用户名兜底。 -- 管理员资料已不存在或用户服务暂时不可用时，才降级显示 `管理员#ID`；系统操作显示 `系统`。 - -## 2. 前端处理 - -- 前端无需新增字段、无需修改请求，也不要自行根据 `operatorId` 拼接名称。 -- 继续直接展示接口返回的 `operatorName`。 -- 部署后重新请求操作记录列表即可看到修正后的历史空名称；无需清理前端缓存。 -- `operatorId` 仍按字符串处理，不能转为 JavaScript `Number`。 - -## 3. 兼容性说明 - -- 不修改数据库结构，不回填或覆盖已有操作人名称快照。 -- 历史空快照的名称解析按页批量执行，不产生逐条查询。 -- 用户服务查询异常不会导致操作记录分页接口失败。 -- 本文件只说明操作人名称展示规则，不与操作记录分页、素材上传或视频播放变更合并记录。 - -## 4. TEST 验证状态 - -- 后端 PR [#4984](https://git.1814.love:8443/wx/HL/pulls/4984) 已合入 `dev`；同步 PR [#4985](https://git.1814.love:8443/wx/HL/pulls/4985) 已合入 `dev-v3`。 -- TEST 部署任务 `60db35f4` 成功，`hl-resource-service` 的 `8082/8182` 双实例均在 Nacos 中健康并启用。 -- `dev-v3` 合并态资源服务回归 1666 项通过，网关草原指南定向测试 21 项通过，均为 0 失败、0 错误。 -- 未绑定企微的测试管理员新建、编辑和删除临时草稿时，`operatorName` 正确回退用户名。 -- 已绑定企微的测试管理员新建临时草稿时，接口响应和数据库 `operator_name` 快照均为企业微信姓名；临时草稿已删除。 -- 真实历史空快照已通过网关分页接口验证：当前目录有企业微信姓名时返回该姓名，不再返回 `管理员#ID`。 -- 以上均为后端接口与数据证据；前端只需继续展示 `operatorName`，无需等待页面联调才能使用。 diff --git a/changelogs/2026-07/14_release_grassland_guide_production.md b/changelogs/2026-07/14_release_grassland_guide_production.md deleted file mode 100644 index c99749f..0000000 --- a/changelogs/2026-07/14_release_grassland_guide_production.md +++ /dev/null @@ -1,41 +0,0 @@ -# 草原指南接口已发布正式环境 - -- 日期：2026-07-14 -- 环境：正式环境 -- 后端版本：`main@fb558bff`（初次发布 `27ae4612`，用户服务菜单修复 `fb558bff`） -- 管理后台版本：`hl-ui/master@4d305ca4` -- 关联工单：`wx/HL#4986` - -## 正式地址 - -接口基址：`https://api.1814.love` - -小程序接口： - -- `GET /mp/grassland-guide/home` -- `GET /mp/grassland-guide/videos` -- `GET /mp/grassland-guide/videos/{videoId}` -- `GET /mp/grassland-guide/videos/{videoId}/recommendations` - -管理端接口仍按此前草原指南 changelog 的 `/admin/grassland-guide/**` 契约调用。 - -正式管理后台 `https://admin.1814.love/grassland-guide` 已加载完整管理页面。若此前打开过“功能开发中”占位页，刷新页面即可重新拉取已修正的菜单路由；无需更换前端分支。 - -## 已验证行为 - -- 首页、分页列表允许匿名访问，正式网关返回 HTTP 200、业务成功。 -- 分页参数由后端兜底：最小页码 1，每页最多 100 条。 -- 管理端匿名请求返回业务 401，登录鉴权有效。 -- 需要登录后查看的视频继续允许匿名浏览卡片；匿名用户不能取得受保护详情正文和播放地址。 -- 视频地址为 OSS MP4 直出，不提供 VOD、CDN、HLS 或清晰度切换字段。 -- 正式环境没有复制 TEST 的 50 条测试数据；当前空列表属于预期状态，前端应展示空态并正常支持后续运营上架。 - -## 契约文档索引 - -- `12_feat_grassland_guide_admin_mp_oss.md` -- `13_feat_grassland_guide_delete.md` -- `13_fix_grassland_guide_mp4_progressive_gate.md` -- `14_feat_grassland_guide_operation_logs.md` -- `14_fix_grassland_guide_operator_display_name.md` - -本文件只告知正式环境可用状态，不新增或修改响应字段；字段与错误码仍以上述拆分 changelog 为准。 diff --git a/changelogs/2026-07/15_fix_grassland_guide_material_descendant_selector.md b/changelogs/2026-07/15_fix_grassland_guide_material_descendant_selector.md deleted file mode 100644 index e8a5fa9..0000000 --- a/changelogs/2026-07/15_fix_grassland_guide_material_descendant_selector.md +++ /dev/null @@ -1,93 +0,0 @@ -# 草原指南管理：素材选择器支持顶级分类整树分页与文件夹名称搜索 - -> **服务**: hl-resource-service (8082) -> **后端 Issue**: [wx/HL#4999](https://git.1814.love:8443/wx/HL/issues/4999) -> **后端 PR**: [wx/HL#5000](https://git.1814.love:8443/wx/HL/pulls/5000)、[wx/HL#5001](https://git.1814.love:8443/wx/HL/pulls/5001) -> **管理端 PR**: [wx/hl-ui#7](https://git.1814.love:8443/wx/hl-ui/pulls/7) -> **日期**: 2026-07-15 -> **影响范围**: 管理后台草原指南新增/编辑页的视频素材选择器 -> **当前状态**: 后端已合入 `dev` 并同步 `dev-v3`，管理端已合入 `v2.1`；测试环境部署及 API 验收通过 - ---- - -## 一、关键变化 - -现有素材列表默认遵循“只查当前分类节点”的兼容规则。草原指南视频都可存放在 `grassland_guide` 的子文件夹中，因此选择器必须显式传 `includeDescendants=true`，才能分页读取顶级分类自身及全部后代文件夹中的素材。 - -不要删除或改变普通素材库现有请求；新参数默认 `false`，未传时行为完全不变。 - ---- - -## 二、变更接口 - -| 接口 | 方法 | 路径 | 变更类型 | -|---|---|---|---| -| 素材分页列表 | GET | `/admin/material/list` | Query 新增可选参数 | - -### 新增 Query 参数 - -| 字段 | 类型 | 必填 | 默认值 | 说明 | -|---|---|---:|---:|---| -| `includeDescendants` | Boolean | 否 | `false` | 是否包含所选分类的全部后代。需同时传 `categoryCode` | - -规则： - -- `categoryCode=grassland_guide&includeDescendants=true`：查询该顶级分类直挂素材及所有层级子文件夹素材。 -- 同时传 `subCategoryId`：查询该子文件夹及其全部后代，不扩到兄弟文件夹。 -- `keyword` 在树范围模式下同时匹配素材名称、素材描述和子文件夹名称；命中文件夹名称时返回该文件夹及后代中的素材。 -- 分页、`fileType`、标签、创建人、日期、排序、状态和分类权限过滤继续由后端统一执行。 -- 不传 `includeDescendants` 或传 `false`：继续严格只查当前节点，保持普通素材库兼容。 - -响应结构无变化，仍为 `Result<PageResult<MaterialVO>>`。 - ---- - -## 三、草原指南前端接入 - -视频选择器请求示例： - -```http -GET /admin/material/list?page=1&limit=12&categoryCode=grassland_guide&fileType=video&includeDescendants=true -``` - -按子文件夹名称搜索： - -```http -GET /admin/material/list?page=1&limit=12&categoryCode=grassland_guide&fileType=video&includeDescendants=true&keyword=额小胖动画草原篇 -``` - -管理端已经完成以下接入，后续调用方不得通过 `lockCategory` 隐式推导查询范围： - -1. `src/views/grassland-guide/VideoEditDrawer.vue`：视频 `MaterialSelect` 显式传 `include-descendants` 和 `allow-sub-category-select`。 -2. `src/components/material-select/MaterialSelect.vue`：声明两个 prop 并透传给 `SelectModal`。 -3. `src/components/material-select/SelectModal.vue`：构造请求时仅在 prop 为 `true` 时添加 `includeDescendants=true`；展示“全部文件夹”和锁定顶级分类下的全部子文件夹。 -4. 选择“全部文件夹”时不传 `subCategoryId`，查询顶级分类整树；选择子文件夹时传其 `subCategoryId`，查询该文件夹及其后代。 - -子文件夹下拉只允许选择 `grassland_guide` 顶级分类内的节点，不能越权切换到其他素材分类。普通素材选择器不启用上述两个 prop，现有行为保持不变。 - -`lockCategory` 只表示 UI 不允许切换分类，`includeDescendants` 表示后端查询范围，两者不得耦合。 - ---- - -## 四、不影响范围 - -- 不修改素材库页面的默认分类查询语义。 -- 不修改素材分类树、数量统计、删除规则或权限规则。 -- 不修改素材上传、草原指南内容保存和小程序接口。 -- 不迁移数据库，不需要新增字典、菜单或 Nacos 配置。 -- 测试环境仅通过既有管理 API 创建一个普通子文件夹并移动两条测试素材用于验收，不属于数据库结构或正式环境数据迁移。 - ---- - -## 五、验证状态 - -- [x] 生产代码编译通过。 -- [x] 专项测试 18 个通过：默认兼容、根分类整树、子分类子树、文件夹名搜索、SQL 条件、DTO 默认值。 -- [x] `hl-resource-service` 及依赖测试 1347 个通过，失败 0。 -- [x] 后端 PR #5000 已合入 `dev`，同步 PR #5001 已合入 `dev-v3`。 -- [x] `dev-v3` 基线执行 `hl-resource-service` 及依赖测试 1673 个，失败 0、错误 0、跳过 38。 -- [x] 管理端 2 个测试文件、16 项测试通过；相关 ESLint 和 Vite 生产构建通过。 -- [x] 后端测试部署任务 `fd6615a6` 成功，8082/8182 双实例滚动更新完成，Nacos 2 个实例健康。 -- [x] 管理端测试部署任务 `e34686c3` 成功，`v2.1` 已发布至测试环境。 -- [x] 测试网关验证：默认当前节点视频 8 条、整树视频 9 条、整树全部素材 14 条、指定子文件夹视频 1 条、按文件夹名搜索视频 1 条。 -- [x] 分页验证：每页 3 条时第 1、2 页各 3 条，总数 14，两页素材 ID 无重叠。 diff --git a/changelogs/2026-07/15_fix_grassland_guide_video_current_folder_scope.md b/changelogs/2026-07/15_fix_grassland_guide_video_current_folder_scope.md deleted file mode 100644 index 2d83288..0000000 --- a/changelogs/2026-07/15_fix_grassland_guide_video_current_folder_scope.md +++ /dev/null @@ -1,59 +0,0 @@ -# 草原指南管理：视频素材仅查询当前文件夹 - -> **管理端 PR**: [wx/hl-ui#9](https://git.1814.love:8443/wx/hl-ui/pulls/9) -> **日期**: 2026-07-15 -> **影响范围**: 管理后台草原指南新增/编辑页的视频素材选择弹窗 -> **当前状态**: 已合入 `v2.1` 并部署测试环境 - ---- - -## 一、业务口径更正 - -视频素材选择器继续保留“草原指南”文件夹下拉，但素材列表改为严格按当前所选文件夹查询，不再自动包含子文件夹素材。 - -本记录更正 `15_fix_grassland_guide_video_folder_selector_visibility.md` 中关于递归查询的描述；文件夹树显示规则保持不变。 - ---- - -## 二、最终查询规则 - -- 选择“草原指南”根目录：只显示直接归属根目录的视频，不显示任意子文件夹视频。 -- 选择具体子文件夹：只显示直接归属该文件夹的视频，不显示更深层子文件夹视频。 -- 关键词搜索、分页和视频类型过滤均在当前文件夹范围内执行。 -- 文件夹下拉仍锁定在“草原指南”分类树内，不能切换到其他业务分类。 - -对应请求规则： - -```http -# 选择“草原指南”根目录 -GET /admin/material/list?categoryCode=grassland_guide&fileType=video - -# 选择具体子文件夹 -GET /admin/material/list?categoryCode=grassland_guide&subCategoryId={文件夹ID}&fileType=video -``` - -上述请求均不提交 `includeDescendants=true`。 - ---- - -## 三、接口与配置影响 - -- 不新增或修改 API 字段。 -- 后端 `includeDescendants` 可选能力保持不变，其他调用方仍可按需显式启用。 -- 不修改数据库、字典、菜单或 Nacos 配置。 -- 不影响封面图选择器、素材上传、小程序接口或草原指南保存逻辑。 - ---- - -## 四、验证记录 - -- [x] 根目录请求不包含 `subCategoryId` 和 `includeDescendants`。 -- [x] 子文件夹请求包含对应 `subCategoryId`，不包含 `includeDescendants`。 -- [x] 文件夹下拉、根节点和子节点继续显示。 -- [x] 共享组件显式开启 `includeDescendants=true` 时仍正常传参。 -- [x] Vitest：1 个测试文件、4 项测试通过。 -- [x] 相关 ESLint 通过。 -- [x] Vite 生产构建通过。 -- [x] 独立代码复核无阻断项。 -- [x] 测试环境部署任务 `418ff501` 成功。 -- [x] 测试环境静态包 `VideoEditDrawer-qeoVDIga.js` 已确认保留文件夹下拉且不再传递 `include-descendants`。 diff --git a/changelogs/2026-07/15_fix_grassland_guide_video_folder_selector_visibility.md b/changelogs/2026-07/15_fix_grassland_guide_video_folder_selector_visibility.md deleted file mode 100644 index d474913..0000000 --- a/changelogs/2026-07/15_fix_grassland_guide_video_folder_selector_visibility.md +++ /dev/null @@ -1,57 +0,0 @@ -# 草原指南管理：视频素材选择器显示文件夹树 - -> **管理端 PR**: [wx/hl-ui#8](https://git.1814.love:8443/wx/hl-ui/pulls/8) -> **关联后端工单**: [wx/HL#4999](https://git.1814.love:8443/wx/HL/issues/4999) -> **日期**: 2026-07-15 -> **影响范围**: 管理后台草原指南新增/编辑页的视频素材选择弹窗 -> **当前状态**: 已合入 `v2.1` 并部署测试环境 - ---- - -## 一、修复原因 - -封面图素材选择器能够显示分类树，但视频选择器锁定在 `grassland_guide` 后，错误地以“根分类必须存在子节点”作为下拉显示条件。分类接口暂时只返回根节点时，视频弹窗会完全隐藏文件夹下拉。 - -该问题只影响管理端显示，不涉及后端接口或数据。 - ---- - -## 二、最终交互 - -- 视频素材弹窗始终显示文件夹下拉，根节点名称为“草原指南”。 -- 有子文件夹时，以树形层级挂在“草原指南”根节点下，可选择任意层级子文件夹。 -- 选择“草原指南”根节点时，查询该顶级分类自身及全部后代素材。 -- 选择子文件夹时，查询该文件夹及其全部后代素材。 -- 视频选择器继续锁定在草原指南分类内，不能切换到其他业务顶级分类。 -- 普通素材选择器和封面图选择器行为不变。 - -对应请求规则： - -```http -# 选择“草原指南”根节点 -GET /admin/material/list?categoryCode=grassland_guide&fileType=video&includeDescendants=true - -# 选择具体子文件夹 -GET /admin/material/list?categoryCode=grassland_guide&subCategoryId={文件夹ID}&fileType=video&includeDescendants=true -``` - ---- - -## 三、接口与配置影响 - -- 不新增或修改 API 字段。 -- 不修改数据库、字典、菜单或 Nacos 配置。 -- 不修改素材上传、小程序接口或草原指南保存逻辑。 - ---- - -## 四、验证记录 - -- [x] Vitest：1 个测试文件、3 项测试通过。 -- [x] 覆盖根分类没有子文件夹时仍显示下拉。 -- [x] 覆盖选择子文件夹后继续提交 `subCategoryId`。 -- [x] 相关 ESLint 通过。 -- [x] Vite 生产构建通过。 -- [x] 独立代码复核无阻断项。 -- [x] 测试环境部署任务 `36ee2a2e` 成功。 -- [x] 测试环境静态包已确认包含新的根节点与子文件夹树逻辑。 diff --git a/changelogs/2026-07/15_notice_grassland_guide_frontend_reverted.md b/changelogs/2026-07/15_notice_grassland_guide_frontend_reverted.md deleted file mode 100644 index 7af2c3e..0000000 --- a/changelogs/2026-07/15_notice_grassland_guide_frontend_reverted.md +++ /dev/null @@ -1,41 +0,0 @@ -# 草原指南管理：今日前端文件夹选择改动已全部回退 - -> **日期**：2026-07-15 -> **影响范围**：`hl-ui` 草原指南视频素材选择器 -> **当前状态**：今天由 `wx` 合入的相关前端代码已全部撤销 - ---- - -## 一、回退结论 - -今天合入 `hl-ui` 的草原指南素材文件夹选择改动不再作为当前实现，相关 PR 已通过纯 Git revert 全部撤销： - -- `v2.1`：原 PR #7、#8、#9 已由回退 PR [wx/hl-ui#12](https://git.1814.love:8443/wx/hl-ui/pulls/12) 撤销。 -- `master`：原 PR #10 已由回退 PR [wx/hl-ui#11](https://git.1814.love:8443/wx/hl-ui/pulls/11) 撤销。 - -回退后未新增任何替代前端实现。 - -## 二、当前代码与部署基线 - -| 分支 / 环境 | 当前版本 | 回退校验 | -|---|---|---| -| `v2.1` / 测试环境 | `30b3ee1f`，任务 `ca6a7df0` | 代码树与改动前 `797beda4` 完全一致 | -| `master` / 正式环境 | `f97a7ccb`，deploy `271` | 代码树与改动前 `4d305ca4` 完全一致 | - -测试与正式环境的 `VideoEditDrawer` 静态资源均已复核，不再包含本次新增的 `allow-sub-category-select` 或 `include-descendants` 配置。 - -## 三、对早期记录的更正 - -以下两份记录仅保留为历史过程，不代表当前 `hl-ui` 代码状态： - -- `15_fix_grassland_guide_video_folder_selector_visibility.md` -- `15_fix_grassland_guide_video_current_folder_scope.md` - -前端不得再按上述两份记录继续实现或判断当前页面能力；如后续重新启动该需求，需要重新确认业务范围并另开前端任务。 - -## 四、后端接口边界 - -- `GET /admin/material/list` 的 `includeDescendants` 后端可选能力仍保留。 -- 默认不传或传 `false` 时只查当前分类节点；显式传 `true` 时查询所选节点及其后代。 -- 当前 `hl-ui` 回退后不消费本次新增的文件夹选择能力。 -- 本次前端回退不修改后端接口、响应结构、数据库、字典、菜单或 Nacos 配置。 diff --git a/changelogs/2026-07/16_feat_grassland_guide_public_detail.md b/changelogs/2026-07/16_feat_grassland_guide_public_detail.md deleted file mode 100644 index fa006b7..0000000 --- a/changelogs/2026-07/16_feat_grassland_guide_public_detail.md +++ /dev/null @@ -1,20 +0,0 @@ -# 草原指南管理端免登录详情接口 - -- 工单：`wx/HL#5005` -- 测试环境：已部署 `dev-v3` -- 正式环境：已部署 `main@59e2b20c` -- 鉴权：不需要登录 -- 数据范围：只允许查询 `PUBLISHED` - -## 接口 - -`GET /admin/grassland-guide/public/videos/{videoId}` - -返回列表字段，并增加：`videoMaterialId`、`videoUrl`、 -`customCoverMaterialId`、`contentHtml`、`contentImageMaterialIds`、 -`createdBy`、`updatedBy`、`createdAt`、`updatedAt`。 - -说明：管理端免登录预览不受 `loginRequired` 限制；该字段只表达小程序用户是否需要登录。 -草稿、下架、删除或不存在的视频统一按不存在处理。 - -测试网关实测：HTTP 200，业务码 `200`。 diff --git a/changelogs/2026-07/16_feat_grassland_guide_public_list.md b/changelogs/2026-07/16_feat_grassland_guide_public_list.md deleted file mode 100644 index a7b69c4..0000000 --- a/changelogs/2026-07/16_feat_grassland_guide_public_list.md +++ /dev/null @@ -1,27 +0,0 @@ -# 草原指南管理端免登录列表接口 - -- 工单：`wx/HL#5005` -- 测试环境：已部署 `dev-v3` -- 正式环境：已部署 `main@59e2b20c` -- 鉴权：不需要登录 -- 数据范围：仅返回 `PUBLISHED`，不会返回草稿、下架或已删除数据 - -## 接口 - -`GET /admin/grassland-guide/public/videos` - -查询参数： - -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| --- | --- | --- | --- | --- | -| keyword | string | 否 | - | 匹配标题或简介 | -| featured | boolean | 否 | - | 是否精选 | -| page | integer | 否 | 1 | 最小 1 | -| pageSize | integer | 否 | 20 | 1～100 | - -`data` 为分页对象：`records`、`total`、`page`、`pageSize`。列表项包含： -`videoId`、`title`、`summary`、`effectiveCoverUrl`、`coverSource`、 -`durationSeconds`、`featured`、`loginRequired`、`sortWeight`、`status`、 -`publishTime`、`linkedProductId`。 - -测试网关实测：HTTP 200，业务码 `200`。 diff --git a/changelogs/2026-07/16_feat_grassland_guide_public_play.md b/changelogs/2026-07/16_feat_grassland_guide_public_play.md deleted file mode 100644 index 4cb8463..0000000 --- a/changelogs/2026-07/16_feat_grassland_guide_public_play.md +++ /dev/null @@ -1,26 +0,0 @@ -# 草原指南管理端免登录播放接口 - -- 工单：`wx/HL#5005` -- 测试环境：已部署 `dev-v3` -- 正式环境：已部署 `main@59e2b20c` -- 鉴权：不需要登录 -- 数据范围：只允许播放 `PUBLISHED` - -## 接口 - -`GET /admin/grassland-guide/public/videos/{videoId}/play` - -`data` 字段： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| videoId | string | 视频业务 ID | -| title | string | 标题 | -| videoUrl | string | OSS MP4 直出地址 | -| durationSeconds | integer | 素材自动解析的时长（秒） | -| effectiveCoverUrl | string | 自定义封面或 OSS 自动截帧封面 | - -该接口是播放最小响应，不返回正文、创建人或操作信息。管理端免登录预览不受 -`loginRequired` 限制；小程序端仍按该字段执行登录鉴权。 - -测试网关实测：HTTP 200，业务码 `200`，真实素材返回播放地址与时长。 diff --git a/changelogs/2026-07/16_feat_grassland_guide_public_recommendations.md b/changelogs/2026-07/16_feat_grassland_guide_public_recommendations.md deleted file mode 100644 index c773c0d..0000000 --- a/changelogs/2026-07/16_feat_grassland_guide_public_recommendations.md +++ /dev/null @@ -1,23 +0,0 @@ -# 草原指南管理端免登录推荐接口 - -- 工单：`wx/HL#5005` -- 测试环境：已部署 `dev-v3` -- 正式环境：已部署 `main@59e2b20c` -- 鉴权：不需要登录 -- 数据范围：源视频和推荐结果都必须是 `PUBLISHED`，推荐结果自动排除自身 - -## 接口 - -`GET /admin/grassland-guide/public/videos/{videoId}/recommendations` - -查询参数： - -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| --- | --- | --- | --- | --- | -| page | integer | 否 | 1 | 最小 1 | -| pageSize | integer | 否 | 20 | 1～100 | - -`data` 为分页对象：`records`、`total`、`page`、`pageSize`；`records` 字段与列表接口一致。 -推荐继续使用后端推荐算法，相关性不足时随机兜底，不需要前端拼装。 - -测试网关实测：HTTP 200，业务码 `200`。 diff --git a/changelogs/2026-07/16_fix_grassland_guide_admin_sort_weight_asc.md b/changelogs/2026-07/16_fix_grassland_guide_admin_sort_weight_asc.md deleted file mode 100644 index 193724c..0000000 --- a/changelogs/2026-07/16_fix_grassland_guide_admin_sort_weight_asc.md +++ /dev/null @@ -1,17 +0,0 @@ -# 草原指南管理列表按排序权重正序 - -- 工单：`wx/HL#5011` -- 测试环境：已部署 `dev-v3` -- 接口：`GET /admin/grassland-guide/videos` - -## 变更 - -列表排序改为： - -1. `sortWeight ASC` -2. `publishTime DESC` -3. `videoId DESC` - -排序权重数字越小越靠前，`0` 排在所有正数权重之前。接口字段和请求参数没有变化，前端不需要改传参。 - -测试环境已用 57 条真实数据验证，权重顺序为 `0, 0, 0, 1, 100, 200...`。 diff --git a/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md b/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md deleted file mode 100644 index 0068f2f..0000000 --- a/changelogs/2026-07/16_fix_grassland_guide_mp4_physical_interleave.md +++ /dev/null @@ -1,98 +0,0 @@ -# 草原指南 MP4 物理交错修复与测试数据回填 - -> 日期：2026-07-16 -> -> 后端 Issue：[HL #5016](https://git.1814.love:8443/wx/HL/issues/5016) -> -> 后端 PR：[HL #5019](https://git.1814.love:8443/wx/HL/pulls/5019) -> -> 测试分支：`dev-v3` -> -> 影响服务：`hl-user-service` -> -> 本次不修改前端仓库，不新增或修改接口字段 - -## 1. 问题结论 - -草原指南真实 4K MP4 在 `1x`、`2x` 播放时出现固定位置反复缓冲。浏览器 Network 中同一文件产生大量被取消并重新发起的 `206 Partial Content` 请求，实际传输量可以超过文件本身体积。 - -该问题包含两个独立因素： - -1. 历史 MP4 虽然已经把 `moov` 移到 `mdat` 前面，但音频、视频 Sample 在 `mdat` 中没有按时间物理交错。播放到同一时间点时，浏览器需要在文件相距很远的位置来回读取音视频数据，造成 Range 请求抖动、取消和重复下载。 -2. 原片本身约 `357204588` 字节、`71` 秒，平均码率约 `40.25 Mbps`。2026-07-16 当前诊断链路连续读取 OSS Range 仅约 `0.52–1.44 MB/s`（约 `4.14–11.50 Mbps`），低于 `1x` 所需的约 `5.03 MB/s`，因此修复文件结构后仍可能因实际网络吞吐不足发生正常缓冲。 - -前端缓存策略不能补足长期吞吐缺口。`preload="auto"` 只能改善起播等待，不能让 `10 Mbps` 链路持续播放 `40 Mbps` 原片。 - -## 2. 后端修复 - -草原指南视频上传确认阶段新增 MP4 无损重封装： - -- 不重新编码，不改变 H.264/AAC Sample。 -- 不降低分辨率、帧率或码率。 -- 保持原视频、音频轨的 Sample 数量、Sample 总字节数和时长。 -- 将 `ftyp`、`moov` 放在文件前部。 -- 以约 2 秒为窗口重新排列音频、视频 Chunk，使相同时间点的数据物理相邻。 -- 重封装前后执行媒体指纹校验；不一致时拒绝替换原对象。 -- 新对象使用 `.progressive-...mp4` Key，成功后再以 CAS 更新文件记录；旧对象暂不删除，便于回滚。 -- 单个 Pod 同时只执行一个重封装任务，并检查临时磁盘空间，避免大文件并发耗尽磁盘。 - -接口路径和请求体保持不变： - -```http -POST /admin/material/upload/confirm -``` - -前端仍然只提交原有 `materialId`、`description` 和 `tagIds`，不需要增加重封装参数。 - -## 3. 历史测试数据回填 - -已对测试环境问题视频执行一次性回填： - -| 项目 | 值 | -| --- | --- | -| 草原指南视频 ID | `2076910159484928002` | -| 素材 ID | `2076909130286612482` | -| 文件 ID | `2076909128663379970` | -| 文件大小 | `357204588` 字节 | -| 新时长 | `71` 秒 | -| 新文件标识 | OSS Key 包含 `.progressive-2076909128663379970-` | - -回填结果： - -- `file_info` 已切换为新 `.progressive-...mp4`，状态为 `ACTIVE / OSS_MP4_READY_V1`。 -- `material.oss_url`、自动封面和时长已切换。 -- `grassland_guide_video` 自动封面和时长已同步，业务记录仍为 `PUBLISHED`。 -- 资源服务 `8082/8182` 与网关 `8080` 的匿名详情、播放接口均返回新地址。 -- OSS `HEAD` 返回 `200 video/mp4`、`Content-Length: 357204588`、`Accept-Ranges: bytes`。 -- `Range: bytes=0-1048575` 返回 `206` 和正确的 `Content-Range`。 - -## 4. 部署与验证证据 - -- 修复提交：`4529da5e97fea21022ca700390a146944608eadc` -- `dev-v3` 合并提交：`65c63a68d903370d07dd80ffea62ac58ccfb31c8` -- `hl-user-service` 测试环境滚动部署任务：`f4d670ba` -- 两实例 `8081/8181` 均启动健康。 -- `hl-user-service` 测试：`3226` 个测试，`0` 失败，`0` 错误，`6` 跳过。 -- 真实 357 MB 文件无损重封装测试通过；重封装前后轨道 Sample 数、Sample 字节数和时长一致。 -- 原文件约 44 秒处的音频、视频数据物理距离约 `185.7 MB`；重封装后缩短到约 `69.7 KB`。 - -## 5. 仍需处理的基础设施边界 - -本次后端修复解决“文件内部排列导致重复 Range 请求”的问题，但不能提高用户到 OSS 的实时带宽。 - -在“不降低码率、不生成低清档”的前提下： - -- `1x` 需要链路持续高于约 `40.25 Mbps`，还应预留网络波动余量。 -- `2x` 平均需要约 `80.50 Mbps`，短时峰值可能更高。 -- 当前测试桶传输加速域名请求返回 `400`，未形成可用的加速播放链路。 -- 若目标用户链路长期低于原片码率，只能选择 OSS 前置 CDN/边缘缓存、开通并验证 OSS 传输加速，或让用户在播放前基本下载完整文件；单纯调整浏览器缓冲逻辑无法解决。 - -接入 CDN 或 OSS 传输加速会改变基础设施和费用，须单独确认后实施。不得为规避该问题把流量代理到 Java 服务，也不得把几百 MB 文件整体读入服务内存。 - -## 6. 大文件上传确认超时提醒 - -本次真实文件在测试环境完成下载、重封装、上传共耗时约 `410` 秒，超过当前网关约 `60` 秒的请求超时。 - -- 服务端任务能够继续完成，但前端可能先收到 `504`。 -- 在异步媒体处理改造完成前，前端不得因单次 `504` 立即重复提交或重复上传，应重新查询素材状态。 -- 正式发布前应单独改造为异步处理状态机，或提供明确的后台任务查询接口；不建议简单把网关超时提高到数分钟。 diff --git a/changelogs/2026-07/16_fix_grassland_guide_mp_sort_weight_asc.md b/changelogs/2026-07/16_fix_grassland_guide_mp_sort_weight_asc.md deleted file mode 100644 index 407ff65..0000000 --- a/changelogs/2026-07/16_fix_grassland_guide_mp_sort_weight_asc.md +++ /dev/null @@ -1,19 +0,0 @@ -# 草原指南小程序列表按排序权重正序 - -- 工单：`wx/HL#5011` -- 测试环境：已部署 `dev-v3` -- 影响接口： - - `GET /mp/grassland-guide/home` - - `GET /mp/grassland-guide/videos` - -## 变更 - -普通视频分页列表排序改为： - -1. `sortWeight ASC` -2. `publishTime DESC` -3. `videoId DESC` - -排序权重数字越小越靠前，`0` 排在所有正数权重之前。首页精选区原本就是小权重优先，规则保持不变；相关推荐仍使用推荐算法，不改为纯权重排序。 - -接口字段和请求参数没有变化。 diff --git a/changelogs/2026-07/16_fix_grassland_guide_playback_buffer_deadlock.md b/changelogs/2026-07/16_fix_grassland_guide_playback_buffer_deadlock.md deleted file mode 100644 index 9e35914..0000000 --- a/changelogs/2026-07/16_fix_grassland_guide_playback_buffer_deadlock.md +++ /dev/null @@ -1,108 +0,0 @@ -# 草原指南切换 2x 后永久缓冲更正 - -> 日期：2026-07-16 -> -> 前端仓库：`mmg/hl-ui` -> -> 影响组件：`src/views/h5/grassland-guide/components/GuideVideoPlayer.vue` -> -> 影响辅助逻辑：`src/views/h5/grassland-guide/components/playbackBuffer.js` -> -> 本次后端接口、字段、OSS 地址和视频文件均无变化 - -## 1. 现象 - -视频在 `1x` 已经开始播放后切换到 `2x`，页面停在“正在缓冲”，即使等待较长时间也不能恢复。 - -Network 中可以看到同一个 MP4 存在多条大小不同的 `206 Partial Content` 请求。这是 Chrome 原生媒体加载器根据 MP4 元数据、当前播放位置和缓存状态发起的 HTTP Range 请求，Range 大小不固定是正常行为，不能据此判断 OSS 分片异常。 - -## 2. 已确认根因 - -线上播放器当前调用链为： - -```text -切换 2x - → 设置 video.playbackRate = 2 - → evaluateBuffer({ initial: true }) - → 要求 bufferAhead >= 15 秒 - → 未达到阈值 - → pauseForBuffering() - → video.pause() -``` - -播放器暂停后，浏览器可以降低甚至停止后续媒体预取。当前代码又只依赖 `progress`、`canplay` 等媒体事件重新执行 `evaluateBuffer()`，没有保证这些事件一定继续产生，因此可能永远达不到 `15` 秒阈值，形成状态机死锁。 - -同类问题还存在于： - -- 首次播放前等待固定 `8` 秒。 -- `timeupdate` 检测到低水位后主动 `pause()`。 -- `waiting`/`stalled` 事件再次主动 `pause()`。 - -这些逻辑把浏览器原生的“缺数据时等待并继续下载”变成了应用层“暂停后等待浏览器继续下载”，两者行为并不等价。 - -## 3. 必须修改的前端逻辑 - -### 3.1 播放与切换倍速 - -```js -async function play() { - playbackRequested.value = true - await videoRef.value?.play() -} - -function togglePlaybackRate() { - const video = videoRef.value - if (!video) return - - playbackRate.value = playbackRate.value === 1 ? 2 : 1 - video.playbackRate = playbackRate.value - - // 禁止在这里 pause() - // 禁止在这里重新执行固定秒数的初始缓冲门槛 -} -``` - -### 3.2 缓冲状态由原生事件驱动 - -```js -function handleWaiting() { - if (!playbackRequested.value) return - buffering.value = true - recordPlaybackEvent('waiting') -} - -function handleStalled() { - const video = videoRef.value - if (playbackRequested.value && video?.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) { - buffering.value = true - } - recordPlaybackEvent('stalled') -} - -function handlePlaying() { - buffering.value = false - recordPlaybackEvent('playing') -} -``` - -事件处理器内不得调用 `video.pause()`。只要用户没有主动暂停，就保留原生播放意图，让浏览器在缺数据时自动等待、继续 Range 取流，并在数据恢复后自行继续播放。 - -### 3.3 删除主动低水位暂停 - -- 删除 `pauseForBuffering()` 对自动缓冲流程的使用。 -- `handleTimeUpdate()` 只同步时间、记录 `bufferAhead` 和掉帧指标，不得检测低水位后暂停。 -- `evaluateBuffer()` 不再阻塞首次播放或倍速切换；如保留该方法，只能用于诊断，不能控制 `play/pause`。 -- 删除 `BUFFER_POLICIES` 中作为播放硬门槛的 `initial/low/resume`，避免后续重新引入死锁。 - -## 4. 验收要求 - -- [ ] `1x` 点击播放后能直接进入原生播放流程，不等待固定 `8` 秒。 -- [ ] 播放中切换 `2x` 不触发 `pause` 事件。 -- [ ] 切换 `2x` 后，即使触发 `waiting`，后续 Range 请求仍继续。 -- [ ] 数据恢复后触发 `playing`，缓冲遮罩自动消失，播放继续。 -- [ ] `1x ↔ 2x` 连续切换 10 次，不出现永久缓冲。 -- [ ] 拖动进度后仍可重新播放，用户主动暂停不会被自动恢复。 -- [ ] Console 中不再出现 `ratechange → initial-buffering → pause` 的调用序列。 -- [ ] 使用 DevTools 测试真实用户表现时关闭 `Disable cache`；需要模拟弱网时单独选择网络限速，不把禁用缓存结果当作正常生产表现。 - -修复状态机后，若 `1x` 或 `2x` 仍出现能够自行恢复的短时 `waiting`，再根据 `bufferAhead`、实际下载速度和掉帧数判断是用户网络还是设备解码能力问题。播放器逻辑修复不能提高用户带宽；需要跨地区稳定承载原始 4K 高码率视频时，应另行评估 OSS 前置 CDN Range 缓存。 diff --git a/changelogs/2026-07/16_fix_grassland_guide_public_sort_weight_asc.md b/changelogs/2026-07/16_fix_grassland_guide_public_sort_weight_asc.md deleted file mode 100644 index 3a6b2c6..0000000 --- a/changelogs/2026-07/16_fix_grassland_guide_public_sort_weight_asc.md +++ /dev/null @@ -1,15 +0,0 @@ -# 草原指南管理端免登录列表按排序权重正序 - -- 工单：`wx/HL#5011` -- 测试环境：已部署 `dev-v3` -- 接口：`GET /admin/grassland-guide/public/videos` - -## 变更 - -列表排序改为： - -1. `sortWeight ASC` -2. `publishTime DESC` -3. `videoId DESC` - -排序权重数字越小越靠前，`0` 排在所有正数权重之前。接口字段、分页方式和免登录规则没有变化。 diff --git a/changelogs/2026-07/16_notice_grassland_guide_4k_playback_buffering.md b/changelogs/2026-07/16_notice_grassland_guide_4k_playback_buffering.md deleted file mode 100644 index e3197fb..0000000 --- a/changelogs/2026-07/16_notice_grassland_guide_4k_playback_buffering.md +++ /dev/null @@ -1,128 +0,0 @@ -# 草原指南 4K 原片播放缓冲优化通知 - -> 日期：2026-07-16 -> -> 前端仓库：`mmg/hl-ui` -> -> 影响页面：草原指南 H5 详情/播放页 -> -> 本次后端接口、字段和 OSS 地址均无变化 - -> [!IMPORTANT] -> 2026-07-16 线上验证发现：原通知中的“主动暂停并等待固定缓冲秒数”会与浏览器原生媒体加载策略形成死锁，已经撤销。前端必须按独立更正通知 -> [`16_fix_grassland_guide_playback_buffer_deadlock.md`](./16_fix_grassland_guide_playback_buffer_deadlock.md) -> 处理，不得再以 `8/15` 秒阈值阻塞播放或切换倍速。 - -## 1. 问题与诊断结论 - -草原指南详情直接播放后端返回的 OSS 原始 MP4。正式环境真实 4K 样本的媒体参数为： - -- 文件约 `451.74 MiB`，时长约 `95` 秒。 -- 分辨率 `3812 × 2160`，`60 fps`。 -- H.264 Main Profile，Level `5.2`。 -- 平均码率约 `40.20 Mbps`。 -- `1x` 播放时短时峰值约 `72.98 Mbps`。 -- `2x` 播放时平均网络消耗约 `80.40 Mbps`；短时峰值约 `142.17 Mbps`。 - -正式 OSS 已支持 HTTP Range，请求返回 `206 Partial Content`。同一诊断环境连续读取 OSS Range 的平均速度约 `230.52 Mbps`，高于该视频 `2x` 播放的短时峰值。因此目前没有证据表明 Java 服务或 OSS Range 能力是主要瓶颈；但该结果不代表每个用户到 OSS 的实时链路都能达到相同速度。 - -现已确认 `1x` 也会偶发卡顿。结合 `1x` 接近 `73 Mbps` 的短时峰值，更可能是用户链路瞬时波动与浏览器前向缓冲较浅共同造成：即使平均网速高于视频平均码率，只要短时间下载速度低于瞬时消耗速度，缓冲仍可能耗尽。因此首次 `1x` 播放和卡顿恢复也必须执行缓冲水位保护，不能只处理 `2x`。 - -此外，`4K 60 fps` 在 `2x` 下相当于设备需要承担接近 `120 fps` 的解码节奏。部分设备即使网络充足，也可能因硬件解码能力不足出现掉帧；前端需要把“等待网络缓冲”和“设备解码掉帧”分别记录。 - -## 2. 前端处理要求 - -### 2.1 保持原生 Range 播放 - -- 继续直接使用接口返回的 `videoUrl` 作为 `<video src>`。 -- 设置 `preload="auto"`，允许浏览器提前加载媒体数据。 -- 不要使用 `fetch`/`axios` 把完整 MP4 下载为 Blob 后再播放，避免一次性占用数百 MiB 内存并破坏原生 Range 调度。 -- 不要改写 OSS 域名，不转成 HLS/M3U8，不接直播播放器。 -- 本轮不降低码率、不转码、不新增清晰度档位。 - -### 2.2 计算真实前向缓冲 - -不能只读取 `video.buffered.end(video.buffered.length - 1)`。应找到包含 `currentTime` 的 buffered 区间，再计算： - -```js -function getBufferAhead(video) { - const currentTime = video.currentTime - - for (let index = 0; index < video.buffered.length; index += 1) { - const start = video.buffered.start(index) - const end = video.buffered.end(index) - - if (currentTime >= start && currentTime <= end) { - return Math.max(0, end - currentTime) - } - } - - return 0 -} -``` - -### 2.3 `1x` 与倍速播放缓冲策略 - -- 用户点击播放时直接调用原生 `video.play()`，不得先暂停等待固定缓冲秒数。 -- 用户切换 `2x` 时只设置 `video.playbackRate = 2`，不得调用 `pause()`，也不得重新执行“初始缓冲门槛”。 -- `waiting` 事件只负责显示“正在缓冲”和记录诊断；不得在事件处理器内再次调用 `pause()`。 -- 保持原生播放请求后，浏览器会继续 Range 取流；数据恢复后通过 `playing` 事件关闭缓冲提示。 -- `stalled` 用于记录网络加载停滞；仅当仍有播放意图且 `readyState < HTMLMediaElement.HAVE_FUTURE_DATA` 时显示缓冲提示，不主动暂停。 -- `timeupdate` 只采集缓冲指标，不得因低于人为水位而主动暂停。 -- 用户主动暂停、拖动进度或离开页面时清除缓冲提示，避免与真实播放意图混淆。 -- `preload="auto"` 只是浏览器提示，不能强制浏览器预取指定秒数。 - -`video.buffered` 用于诊断和观测，不再作为阻塞 `play()` 或切换倍速的硬门槛。简单的原生 `<video>` 无法保证“暂停后一定继续预取到 N 秒”；若业务将来要求确定性分片缓冲，需要另行评估 MSE/HLS 或 CDN，不应在原生 MP4 播放器中模拟。 - -### 2.4 记录卡顿证据 - -至少监听并记录以下事件和状态： - -- 事件：`loadstart`、`loadedmetadata`、`canplay`、`canplaythrough`、`progress`、`waiting`、`stalled`、`playing`、`seeking`、`seeked`、`error`。 -- 状态：`currentTime`、`playbackRate`、前向缓冲秒数、`readyState`、`networkState`。 -- 浏览器支持时记录 `getVideoPlaybackQuality()` 的 `droppedVideoFrames` 和 `totalVideoFrames`。 - -日志不得记录完整带签名 URL、Token 或其他凭证。建议只记录 `videoId`、事件时间和上述播放指标。 - -判断口径： - -- 出现 `waiting`/`stalled`，同时前向缓冲接近 `0`：网络或缓冲调度不足。 -- 前向缓冲充足、没有 `waiting`，但 `droppedVideoFrames` 持续上升：设备解码能力不足。 - -## 3. 接口契约 - -播放接口保持不变： - -```http -GET /admin/grassland-guide/public/videos/{videoId}/play -``` - -前端继续使用： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `videoId` | string | 视频业务 ID | -| `videoUrl` | string | OSS 原始 MP4 地址，直接交给原生 `<video>` | -| `durationSeconds` | integer | 后端从素材解析的时长 | -| `effectiveCoverUrl` | string | 生效封面 | - -雪花 ID 必须按字符串处理。本次不增加缓冲、码率或清晰度字段，前端不得等待后端返回这些字段后才处理播放。 - -相关接口说明见： - -- [`16_feat_grassland_guide_public_play.md`](./16_feat_grassland_guide_public_play.md) -- [`12_feat_grassland_guide_admin_mp_oss.md`](./12_feat_grassland_guide_admin_mp_oss.md) - -## 4. 前端验收清单 - -- [ ] `<video>` 使用接口原始 `videoUrl`，并设置 `preload="auto"`。 -- [ ] 没有将完整 MP4 下载为 Blob。 -- [ ] 首次 `1x` 播放不受固定缓冲秒数阻塞。 -- [ ] 切换 `2x` 不调用 `pause()`，不等待 `15` 秒缓冲。 -- [ ] `waiting`/`stalled` 只更新提示与日志，不主动暂停；`playing` 能可靠关闭提示。 -- [ ] 用户暂停、拖动和离开页面时不会被自动恢复播放。 -- [ ] 能区分并记录缓冲耗尽与设备解码掉帧。 -- [ ] 使用正式 4K 样本分别连续验证 `1x` 和 `2x`，记录等待次数、累计等待时长、最小前向缓冲和掉帧数。 -- [ ] Chrome 桌面端和目标移动设备均完成验证。 - -若完成上述缓冲策略后，多个地区和设备仍普遍出现“前向缓冲耗尽”，再单独评估 OSS 前置 CDN Range 缓存或 OSS 传输加速；该基础设施调整会新增费用，不属于本次前端通知范围。 diff --git a/changelogs/2026-07/17_fix_grassland_guide_mp4_timeline_prod.md b/changelogs/2026-07/17_fix_grassland_guide_mp4_timeline_prod.md deleted file mode 100644 index fe3aeb6..0000000 --- a/changelogs/2026-07/17_fix_grassland_guide_mp4_timeline_prod.md +++ /dev/null @@ -1,34 +0,0 @@ -# 草原指南 MP4 重封装时间轴修复正式发布 - -> 日期：2026-07-17 -> -> 后端 Issue：[HL #5021](https://git.1814.love:8443/wx/HL/issues/5021) -> -> 后端 PR：[HL #5026](https://git.1814.love:8443/wx/HL/pulls/5026) -> -> 正式分支：`main` -> -> 影响服务：`hl-user-service` - -## 问题与修复 - -旧版 MP4 无损重封装虽然保持了 Sample 数据，但 `mvhd/tkhd/elst` 使用了不一致的时间单位，浏览器可能把完整视频识别成数秒并提前触发 `ended`。 - -后端现已统一 presentation timeline 的 movie timescale，并在替换 OSS 对象前校验 `mvhd/tkhd/elst/mdhd/stts` 一致性。视频仍保持原分辨率、帧率、编码和码率，不经过 Java 服务代理播放流量。 - -接口路径、请求体及响应字段均保持不变，前端无需适配新字段。 - -## 验证结果 - -- MP4 核心测试：30/30 通过 -- `FileServiceTest` 与 `OssServiceTest`：141/141 通过 -- Maven package：`BUILD SUCCESS` -- 测试环境真实媒体 1x/2x 播放已验收不卡顿 -- 正式部署任务：`#283` -- 发布提交/镜像：`009d5ffe` -- `hl-user-service`：`2/2 Ready` -- 正式列表、详情、推荐、播放接口：HTTP/业务码均为 200 -- 正式真实 MP4：`Content-Length: 592945035`、`Accept-Ranges: bytes` -- `Range: bytes=0-1023`：返回 206，`Content-Range: bytes 0-1023/592945035` - -本次未修改或部署 `hl-ui`，无数据库结构及 Nacos 配置变更。 diff --git a/changelogs/2026-07/17_release_grassland_guide_sort_weight_asc_prod.md b/changelogs/2026-07/17_release_grassland_guide_sort_weight_asc_prod.md deleted file mode 100644 index f46a46b..0000000 --- a/changelogs/2026-07/17_release_grassland_guide_sort_weight_asc_prod.md +++ /dev/null @@ -1,25 +0,0 @@ -# 草原指南排序权重正序规则正式发布 - -> 日期：2026-07-17 -> -> 后端 PR：[HL #5026](https://git.1814.love:8443/wx/HL/pulls/5026) -> -> 正式分支：`main` -> -> 影响服务：`hl-resource-service` - -## 变更说明 - -草原指南列表排序权重统一按正序处理：数值越小越靠前，`0` 位于 `1` 之前。 - -本次不新增或删除接口，不修改请求参数与响应字段。前端继续使用原有列表接口，不需要自行反转结果。 - -## 正式验证 - -- 正式部署任务：`#282` -- 发布提交/镜像：`009d5ffe` -- `hl-resource-service`：`2/2 Ready` -- 匿名正式列表接口：HTTP 200、业务码 200 -- 正式数据首屏排序权重：`0,1,2,3,4,5,6,7,8,9` - -本次未修改或部署 `hl-ui`，无数据库结构及 Nacos 配置变更。 diff --git a/changelogs/2026-07/23_5183_酒店房型轻量下拉-新增接口-管理后台.md b/changelogs/2026-07/23_5183_酒店房型轻量下拉-新增接口-管理后台.md deleted file mode 100644 index 0c1e94e..0000000 --- a/changelogs/2026-07/23_5183_酒店房型轻量下拉-新增接口-管理后台.md +++ /dev/null @@ -1,306 +0,0 @@ -# ✨ 酒店与房型轻量下拉接口（#5183） - -> **PR**: [#5184](https://git.1814.love:8443/wx/HL/pulls/5184) -> **服务**: hl-resource-service -> **更新时间**: 2026-07-23 14:05 - -## 1. 接口背景 - -管理后台在核单 Step1 手动新增住宿项时，需要异步搜索可用酒店，并在选定酒店后加载该酒店当前可用的房型。新增两个轻量接口，避免下拉框拉取完整资源详情或在前端过滤禁用数据。 - -## 2. 变更清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 酒店轻量下拉分页 | GET | `/admin/hotel/options` | 新增接口 | 按酒店名称异步分页搜索，仅返回启用酒店 | -| 2 | 启用房型轻量下拉 | GET | `/admin/hotel/{hotelId}/room-type-options` | 新增接口 | 返回指定酒店下的启用房型 | - -## 3. 接口详情 - -### 3.1 酒店轻量下拉分页 - -- **使用场景**：酒店下拉框首次打开或用户输入关键词时调用。 -- **认证**：需要管理后台 JWT，使用 `Authorization: Bearer <token>`。 -- **幂等性**：幂等，只读查询。 -- **响应类型**：`Result<PageResult<HotelSimpleRespVO>>`。 - -#### Query 入参 - -| 字段 | 类型 | 必填 | 默认值 | 校验规则 | 说明 | -|------|------|------|--------|----------|------| -| `keyword` | String | 否 | `null` | 最长 100 个字符 | 酒店名称模糊匹配；空字符串或仅空白字符等同未传 | -| `page` | Integer | 否 | `1` | 最小值 1 | 当前页码 | -| `pageSize` | Integer | 否 | `20` | 1～100 | 每页条数 | - -无请求体。 - -#### 完整出参 - -| 字段 | 类型 | 可空 | 说明 | -|------|------|------|------| -| `code` | Integer | 否 | 业务状态码；成功为 `200` | -| `message` | String | 否 | 响应消息；成功为 `成功` | -| `success` | Boolean | 否 | `code == 200` 时为 `true` | -| `traceId` | String | 是 | 链路追踪 ID | -| `data` | Object | 否 | 分页数据 | -| `data.records` | Array | 否 | 本页酒店列表；无匹配项时为空数组 | -| `data.records[].hotelId` | String | 否 | 酒店 ID；必须按字符串保存和传递 | -| `data.records[].hotelName` | String | 否 | 酒店名称 | -| `data.total` | Integer | 否 | 符合条件的总记录数 | -| `data.page` | Integer | 否 | 当前页码 | -| `data.pageSize` | Integer | 否 | 每页条数 | - -#### 错误码 - -| code | 含义 | 触发场景 | -|------|------|----------| -| `200` | 成功 | 查询完成，包括没有匹配数据 | -| `400` | 参数校验失败 | `page < 1`、`pageSize` 不在 1～100，或 `keyword` 超过 100 个字符 | - -#### 业务边界 - -- 只返回启用状态的酒店，禁用酒店不会出现在任何分页结果中。 -- `keyword` 仅对酒店名称做模糊匹配。 -- 未传 `keyword` 时分页查询全部启用酒店。 -- 页码超过最后一页时，`records` 返回空数组，`total` 仍是符合条件的总记录数。 -- 结果按酒店名称、酒店 ID 升序排列。 - -#### 典型成功示例 - -**请求** - -```http -GET /admin/hotel/options?keyword=伯爵&page=1&pageSize=20 -Authorization: Bearer <token> -``` - -无请求体。 - -**响应** - -```json -{ - "code": 200, - "message": "成功", - "data": { - "records": [ - { - "hotelId": "9007199254740993", - "hotelName": "伯爵酒店" - } - ], - "total": 1, - "page": 1, - "pageSize": 20 - }, - "traceId": "a1b2c3d4-e5f6-7890", - "success": true -} -``` - -#### 边界示例：无匹配数据 - -**请求** - -```http -GET /admin/hotel/options?keyword=不存在的酒店&page=1&pageSize=20 -Authorization: Bearer <token> -``` - -无请求体。 - -**响应** - -```json -{ - "code": 200, - "message": "成功", - "data": { - "records": [], - "total": 0, - "page": 1, - "pageSize": 20 - }, - "traceId": "b2c3d4e5-f6a7-8901", - "success": true -} -``` - -#### 异常示例：每页条数越界 - -**请求** - -```http -GET /admin/hotel/options?page=1&pageSize=101 -Authorization: Bearer <token> -``` - -无请求体。 - -**响应** - -```json -{ - "code": 400, - "message": "每页条数最大为100", - "data": null, - "traceId": "c3d4e5f6-a7b8-9012", - "success": false -} -``` - -### 3.2 启用房型轻量下拉 - -- **使用场景**：用户从酒店下拉框选定酒店后，加载该酒店可选择的房型。 -- **认证**：需要管理后台 JWT，使用 `Authorization: Bearer <token>`。 -- **幂等性**：幂等，只读查询。 -- **响应类型**：`Result<List<RoomTypeOptionRespVO>>`。 - -#### Path 入参 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `hotelId` | String | 是 | 已选酒店 ID；URL 中按十进制数字字符串传递 | - -无 Query 参数，无请求体。 - -#### 完整出参 - -| 字段 | 类型 | 可空 | 说明 | -|------|------|------|------| -| `code` | Integer | 否 | 业务状态码；成功为 `200` | -| `message` | String | 否 | 响应消息；成功为 `成功` | -| `success` | Boolean | 否 | `code == 200` 时为 `true` | -| `traceId` | String | 是 | 链路追踪 ID | -| `data` | Array | 否 | 启用房型列表；没有启用房型时为空数组 | -| `data[].roomTypeId` | String | 否 | 房型 ID；必须按字符串保存和传递 | -| `data[].roomTypeName` | String | 否 | 房型名称 | -| `data[].roomCategory` | String | 否 | 房型分类，取值见第 4 节 | - -#### 错误码 - -| code | 含义 | 触发场景 | -|------|------|----------| -| `200` | 成功 | 查询完成，包括酒店不存在或没有启用房型 | -| `400` | 参数类型错误 | `hotelId` 不是可解析的十进制数字字符串 | - -#### 业务边界 - -- 只返回 `hotelId` 对应酒店下的启用房型，禁用房型不会返回。 -- 酒店不存在、酒店下没有房型或没有启用房型时，均返回成功和空数组。 -- 结果按房型排序值、房型 ID 升序排列。 -- 该接口不分页，应在酒店选择变化后重新请求，不能继续使用上一个酒店的房型结果。 - -#### 典型成功示例 - -**请求** - -```http -GET /admin/hotel/9007199254740993/room-type-options -Authorization: Bearer <token> -``` - -无请求体。 - -**响应** - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "roomTypeId": "9007199254741993", - "roomTypeName": "标准间", - "roomCategory": "STANDARD" - }, - { - "roomTypeId": "9007199254741994", - "roomTypeName": "家庭房", - "roomCategory": "FAMILY" - } - ], - "traceId": "d4e5f6a7-b8c9-0123", - "success": true -} -``` - -#### 边界示例：没有启用房型 - -**请求** - -```http -GET /admin/hotel/9007199254740999/room-type-options -Authorization: Bearer <token> -``` - -无请求体。 - -**响应** - -```json -{ - "code": 200, - "message": "成功", - "data": [], - "traceId": "e5f6a7b8-c9d0-1234", - "success": true -} -``` - -#### 异常示例：酒店 ID 类型错误 - -**请求** - -```http -GET /admin/hotel/not-a-number/room-type-options -Authorization: Bearer <token> -``` - -无请求体。 - -**响应** - -```json -{ - "code": 400, - "message": "参数类型错误: hotelId='not-a-number'（需要 Long 类型）", - "data": null, - "traceId": "f6a7b8c9-d0e1-2345", - "success": false -} -``` - -## 4. 枚举 / 数据字典 - -### 4.1 `roomCategory`（字典类型 `room_category`） - -**所属字段**：`RoomTypeOptionRespVO.roomCategory` -**类型**：String -**必填**：是 - -| 值 | 中文 | 说明 | -|----|------|------| -| `STANDARD` | 标间 | 标准房型 | -| `SINGLE` | 单人间 | 单人房型 | -| `TWIN` | 双床房 | 双床房型 | -| `QUEEN` | 大床房 | 大床房型 | -| `KING` | 豪华大床 | 豪华大床房型 | -| `SUITE` | 套房 | 套房房型 | -| `FAMILY` | 家庭房 | 家庭房型 | -| `YURT` | 蒙古包 | 蒙古包房型 | -| `SPECIAL` | 特色房 | 特色房型 | -| `PARENT_CHILD` | 亲子房 | 亲子房型 | - -## 5. 影响评估 - -- 两个接口均为新增，只读接口，不破坏现有接口兼容性。 -- 前端可按需接入；不要求与后端同步上线。 -- 所有酒店 ID、房型 ID 都按 `String` 处理，不要转换为 JavaScript `Number`。 - -## 6. 关联 - -- **Issue**: [#5183](https://git.1814.love:8443/wx/HL/issues/5183) -- **PR**: [#5184](https://git.1814.love:8443/wx/HL/pulls/5184) -- **Merge commit**: [0163a7a03](https://git.1814.love:8443/wx/HL/commit/0163a7a0308344691f2379e154c40069fd8d34ba) -- **后端负责人**: @yaosutu diff --git a/changelogs/2026-07/23_5185_Step2票种规格字典-修改接口-管理后台.md b/changelogs/2026-07/23_5185_Step2票种规格字典-修改接口-管理后台.md deleted file mode 100644 index a2238a6..0000000 --- a/changelogs/2026-07/23_5185_Step2票种规格字典-修改接口-管理后台.md +++ /dev/null @@ -1,219 +0,0 @@ -# 【🔧 修改接口·管理后台】Step2 票种规格字典（#5185） - -> **PR**: #5191 | **更新时间**: 2026-07-23 - -## 1. 接口背景 - -Step2 门票/游玩项目需要统一的票种/规格选项。管理后台现在可以按字典类型加载启用选项，首个可用选项为“成人票”，避免前端写死选项文案。 - -## 2. 变更清单 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 按类型查询字典数据 | GET | `/admin/dict/data/settlement_ticket_spec` | 修改接口 | 新增 `settlement_ticket_spec` 字典类型及启用项“成人票” | - -## 3. 接口详情 - -### 3.1 按类型查询 Step2 票种规格 - -- **使用场景**：加载 Step2 门票/游玩项目的票种/规格下拉选项。 -- **认证**：需要管理后台 JWT。 -- **幂等性**：是，只读查询。 -- **限流**：无接口专属限流约定。 -- **排序**：按 `sortOrder` 升序，同一排序号再按 `dictDataId` 升序。 -- **过滤**：仅返回 `status=ACTIVE` 的字典项。 - -## 4. 接口入参 - -### 4.1 路径参数 - -| 字段 | 类型 | 必填 | 固定值 | 说明 | -|------|------|------|--------|------| -| `dictType` | String | 是 | `settlement_ticket_spec` | Step2 票种/规格字典类型编码 | - -### 4.2 Query 参数与请求体 - -无 Query 参数，无请求体。 - -## 5. 出参（响应） - -### 5.1 统一响应字段 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `code` | Integer | 业务状态码，成功为 `200` | -| `message` | String | 响应消息，成功为“成功” | -| `data` | Array | 启用的字典项列表；无匹配项时为 `[]` | -| `traceId` | String / null | 链路追踪 ID | -| `success` | Boolean | `code=200` 时为 `true` | - -### 5.2 `data[]` 字典项字段 - -| 字段 | 类型 | 可为空 | 说明 | -|------|------|--------|------| -| `dictDataId` | Long | 否 | 字典数据 ID | -| `dictType` | String | 否 | 字典类型编码，本接口固定为 `settlement_ticket_spec` | -| `dictLabel` | String | 否 | 展示文案 | -| `dictValue` | String | 否 | 提交值；选择后写入 Step2 `items[].specName` | -| `icon` | String | 是 | 图标，本字典项当前为 `null` | -| `color` | String | 是 | 展示色值，本字典项当前为 `null` | -| `sortOrder` | Integer | 否 | 排序号，越小越靠前 | -| `status` | String | 否 | 字典项状态 | -| `remark` | String | 是 | 字典项说明 | -| `createdAt` | String | 是 | 创建时间，格式为 `yyyy-MM-dd HH:mm:ss` | -| `updatedAt` | String | 是 | 更新时间，格式为 `yyyy-MM-dd HH:mm:ss` | - -## 6. 枚举 / 数据字典 - -### 6.1 `settlement_ticket_spec` - -**展示字段**：`dictLabel` | **提交字段**：`dictValue` | **提交目标**：Step2 `items[].specName` - -| `dictValue` | `dictLabel` | `sortOrder` | `status` | 说明 | -|-------------|-------------|-------------|----------|------| -| `成人票` | 成人票 | `10` | `ACTIVE` | Step2 默认票种/规格 | - -### 6.2 `status` - -| 值 | 中文 | 是否由本接口返回 | -|----|------|------------------| -| `ACTIVE` | 启用 | 是 | -| `INACTIVE` | 禁用 | 否；查询接口会过滤禁用项 | - -## 7. 错误码 - -| code | 含义 | 触发场景 | -|------|------|----------| -| `200` | 成功 | 查询成功；没有匹配项时 `data=[]` | -| `401` | 未认证或认证失效 | 未携带有效管理后台 JWT | -| `500` | 系统异常 | 查询过程发生未预期异常 | - -## 8. 示例 - -### 8.1 典型成功 - -**请求**： - -```http -GET /admin/dict/data/settlement_ticket_spec -Authorization: Bearer <admin-token> -``` - -无请求体。 - -**响应**： - -```json -{ - "code": 200, - "message": "成功", - "data": [ - { - "dictDataId": 101411, - "dictType": "settlement_ticket_spec", - "dictLabel": "成人票", - "dictValue": "成人票", - "icon": null, - "color": null, - "sortOrder": 10, - "status": "ACTIVE", - "remark": "Step2 默认票种/规格", - "createdAt": "2026-07-23 10:00:00", - "updatedAt": "2026-07-23 10:00:00" - } - ], - "traceId": "a1b2c3d4-e5f6-7890", - "success": true -} -``` - -### 8.2 边界情况：不存在的字典类型 - -**请求**： - -```http -GET /admin/dict/data/not_exists -Authorization: Bearer <admin-token> -``` - -无请求体。 - -**响应**： - -```json -{ - "code": 200, - "message": "成功", - "data": [], - "traceId": "b2c3d4e5-f6a7-8901", - "success": true -} -``` - -### 8.3 业务失败：未认证 - -**请求**： - -```http -GET /admin/dict/data/settlement_ticket_spec -``` - -无请求体，且未携带 `Authorization`。 - -**响应**： - -```json -{ - "code": 401, - "message": "未认证或登录已失效", - "data": null, - "traceId": "c3d4e5f6-a7b8-9012", - "success": false -} -``` - -## 9. 业务边界 - -- 字典接口只返回启用项；禁用项不会出现在下拉列表中。 -- 前端展示 `dictLabel`，并将选中项的 `dictValue` 原样提交到 Step2 `items[].specName`。 -- 当前首个字典值为“成人票”；后续新增启用项时，接口会按排序规则一并返回。 -- 字典为单层平铺列表，不包含父子层级。 - -## 10. 修改前后对比 - -### 10.1 字段级对比 - -| 项目 | 改前 | 改后 | -|------|------|------| -| 响应结构 | `Result<List<SysDictDataRespVO>>` | 不变 | -| Step2 票种规格字典类型 | 无 `settlement_ticket_spec` 可用项 | 返回启用项“成人票” | - -### 10.2 行为级对比 - -| 行为 | 改前 | 改后 | -|------|------|------| -| 加载 Step2 票种/规格选项 | 无专用字典数据 | 可查询 `settlement_ticket_spec` | -| 前端选项值 | 需要自行维护 | 使用接口返回的 `dictValue` | - -## 11. 影响评估 - -- **是否破坏向后兼容**：否，接口路径和响应结构未改变。 -- **前端是否必须同步上线**：否；接入后可使用动态字典，旧逻辑不会因本次新增字典项而报错。 - -## 12. 注意事项 - -- 不要把“成人票”选项数组硬编码在前端；应按需调用本接口。 -- 展示使用 `dictLabel`，保存使用 `dictValue`，不要提交 `dictDataId`。 -- Step2 仍使用原有 `specName` 字段，没有新增 `specCode`。 - -## 13. 关联 / 联系人 - -### 13.1 链接 - -- **Issue**: [#5185](https://git.1814.love:8443/wx/HL/issues/5185) -- **PR**: [#5191](https://git.1814.love:8443/wx/HL/pulls/5191) -- **Merge commit**: [03ab19b46](https://git.1814.love:8443/wx/HL/commit/03ab19b463be4b00f92848cb348ce6158918e041) - -### 13.2 联系人 - -- **后端负责人**: @yst diff --git a/changelogs/2026-07/24_5203_出行人资料完整度语义.md b/changelogs/2026-07/24_5203_出行人资料完整度语义.md deleted file mode 100644 index f3bdbe4..0000000 --- a/changelogs/2026-07/24_5203_出行人资料完整度语义.md +++ /dev/null @@ -1,343 +0,0 @@ -# 🔧 出行人批量编辑：资料完整度与完成统计统一为订单级手机号语义（#5203） - -> **PR**: [#5210](https://git.1814.love:8443/wx/HL/pulls/5210) -> **Issue**: [#5203](https://git.1814.love:8443/wx/HL/issues/5203) -> **日期**: 2026-07-24 -> **消费端**: 一期小程序 MP BFF -> **接口**: `POST /mp/v3/order/{id}/traveler/batch-edit` - -## 1. 变更背景 - -出行人资料完整度与订单签约、确认门禁此前存在两套手机号口径：逐人完成状态可能要求每名成人都有手机号，但订单门禁只要求整单至少一名出行人有手机号。 - -本次统一为： - -- 单名出行人的资料完整度只检查 `name`、`gender`、`birthday`、`idType`、`idNo` 五项； -- `phone` 不再影响该出行人的完成状态； -- 订单整体仍必须至少有一名出行人填写手机号； -- 接口字段名、类型和层级不变，但 `completedCount`、`pendingCount`、`allCompleted` 的统计结果可能变化。 - -## 2. 变更接口 - -| 接口 | 方法 | 路径 | 变更类型 | -|---|---|---|---| -| 客户批量补全出行人 | POST | `/mp/v3/order/{id}/traveler/batch-edit` | 响应字段语义修改 | - -## 3. 完整接口契约 - -### 3.1 调用约束 - -| 项目 | 契约 | -|---|---| -| 认证 | 需要小程序登录态 | -| 可编辑订单状态 | `PENDING_PAY`（待支付）、`CUSTOMIZING`（定制中） | -| 订单归属 | 只能编辑当前登录用户自己的订单 | -| 幂等 | 同一订单 3 秒内重复提交返回 `100502` | -| 批量上限 | 每次 1～30 名出行人 | -| 写入语义 | `id=null` 为新增，`id` 非空为更新；未出现在数组中的已有出行人不会被删除 | - -### 3.2 路径参数 - -| 字段 | 类型 | 必填 | 说明 | -|---|---|---|---| -| `id` | Long | 是 | 订单 ID；建议以字符串形式传递，避免大整数精度丢失 | - -### 3.3 请求体 - -请求类型：`TravelerBatchEditReqVO` - -| 字段 | 类型 | 必填 | 约束与语义 | -|---|---|---|---| -| `travelers` | `TravelerEditItem[]` | 是 | 1～30 项 | -| `travelers[].id` | Long / null | 否 | `null` 表示新增；非空表示更新，且必须属于路径中的订单 | -| `travelers[].name` | String / null | 条件必填 | 新增项的 `name`、`idType`、`idNo` 至少一项非空；有值时长度 2～30，只允许中文、英文、中点 `·`、连字符 `-`、空格 | -| `travelers[].gender` | String / null | 否 | `0`、`1`、`2`；该字段为空时资料状态为 `PENDING` | -| `travelers[].birthday` | String | 是 | `yyyy-MM-dd`，不得晚于当天；用于派生出行人类型 | -| `travelers[].idType` | String / null | 条件必填 | 取值见第 4 节；与 `idNo` 配套 | -| `travelers[].idNo` | String / null | 条件必填 | `ID_CARD` 为 18 位数字或末位 `X/x`；其他证件为 5～30 位字母、数字或连字符 | -| `travelers[].nationality` | String / null | 否 | 允许不传或传 `null`，不允许显式传空字符串 | -| `travelers[].race` | String / null | 否 | 允许不传或传 `null`，不允许显式传空字符串 | -| `travelers[].phone` | String / null | 否 | 有值时必须为 11 位数字；更新时 `null` 表示保留原值，空字符串表示清空 | -| `travelers[].emergencyContact` | String / null | 否 | 出行人级紧急联系人姓名 | -| `travelers[].emergencyPhone` | String / null | 否 | 有值时必须为 11 位数字 | -| `travelers[].roomGroupNo` | Integer / null | 否 | 最小为 1，最大不超过订单声明总人数 | - -更新已有出行人时，除必填的 `birthday` 外，其他可选字段传 `null` 表示保留原值。 - -### 3.4 响应 - -响应类型：`Result<TravelerBatchEditRespVO>` - -统一响应字段： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `code` | Integer | `200` 表示成功，其他值见第 5 节 | -| `message` | String | 响应文案 | -| `data` | Object / null | 成功时为批量编辑统计，失败时通常为 `null` | -| `traceId` | String / null | 链路追踪 ID，可能为空 | -| `success` | Boolean | `code == 200` 时为 `true` | - -`data` 字段： - -| 字段 | 类型 | 说明 | -|---|---|---| -| `createdCount` | Integer | 本次请求中 `id=null` 的新增数量 | -| `updatedCount` | Integer | 本次请求中 `id` 非空的更新数量 | -| `completedCount` | Integer | 操作完成后，订单内五项资料均完整的出行人总数 | -| `pendingCount` | Integer | 操作完成后，订单内五项资料仍有缺失的出行人总数 | -| `allCompleted` | Boolean | 同时满足“订单声明人数大于 0、实际人数等于声明人数、`pendingCount=0`、整单至少一名出行人有手机号”时为 `true` | - -五项资料指：`name`、`gender`、`birthday`、`idType`、`idNo`。手机号不计入单名出行人的完成状态，但仍计入 `allCompleted` 的订单级门禁。 - -## 4. 枚举与数据字典 - -### 4.1 `gender` - -| 值 | 中文 | 完整度语义 | -|---|---|---| -| `0` | 未知 | 有值，满足 `gender` 完整度 | -| `1` | 男 | 有值，满足 `gender` 完整度 | -| `2` | 女 | 有值，满足 `gender` 完整度 | - -### 4.2 资料完成状态 - -该状态不单独出现在本接口响应中，但直接决定 `completedCount` 和 `pendingCount`。 - -| 值 | 中文 | 判定 | -|---|---|---| -| `COMPLETED` | 已完善 | `name/gender/birthday/idType/idNo` 五项全部非空 | -| `PENDING` | 待完善 | 上述五项任一为空 | - -### 4.3 `idType` - -| 值 | 中文 | -|---|---| -| `ID_CARD` | 身份证 | -| `PASSPORT` | 护照 | -| `HK_MACAU_PASS` | 港澳通行证 | -| `HONGKONG_RESIDENT_PASS` | 回乡证 | -| `TAIWAN_PASS` | 台湾通行证 | -| `MILITARY_ID` | 军官证 | -| `OTHER` | 其他 | - -### 4.4 出行人类型 - -出行人类型不由请求体传入，而是根据 `birthday` 自动派生，并用于校验订单各类型人数配额。 - -| 年龄 | 值 | 中文 | -|---|---|---| -| 未满 2 周岁 | `BABY` | 幼童 | -| 2～6 周岁 | `YOUNG_CHILD` | 小童 | -| 7～17 周岁 | `CHILD` | 儿童 | -| 18 周岁及以上 | `ADULT` | 成人 | - -## 5. 错误码 - -| code | message / 含义 | 触发场景 | -|---|---|---| -| `401` | 未认证 | 未携带有效小程序登录态 | -| `500` | 出行人服务不可用，请稍后重试 | BFF 无法调用出行人服务 | -| `100001` | 参数非法 | `travelers` 为空、超过 30 项、缺少 `birthday`、日期格式错误等请求校验失败 | -| `100502` | 出行人补全处理中，请勿重复提交 | 同一订单 3 秒内重复提交 | -| `100503` | 资源被占用，请稍后重试 | 同一订单存在并发写入且未能取得操作权 | -| `100701` | 姓名长度异常(2-30字符) | 非空姓名长度不在 2～30 字符 | -| `100702` | 姓名含非法字符 | 姓名包含允许字符集之外的内容 | -| `100703` | 姓名含敏感词 | 姓名命中敏感词 | -| `100704` | 姓名格式不正确 | 同一字符连续重复 5 次及以上 | -| `581101` | 12301 必报字段缺失（国籍 / 民族不能为空字符串） | `nationality` 或 `race` 显式传空字符串 | -| `581102` | 订单不存在，无法编辑出行人 | 处理过程中订单不存在 | -| `581103` | 性别编码不合法（应为 1=男/2=女/0=未知） | 非空 `gender` 不在 `0/1/2` | -| `581104` | 同住分组号超出订单家庭数上限 | `roomGroupNo < 1` 或超过订单声明总人数 | -| `581110` | 出行人 ID 不属于该订单 | 更新项的 `id` 不属于路径订单 | -| `581111` | 已签电子合同后禁止修改证件号 | 已签约记录尝试修改 `idNo` | -| `581112` | 证件号格式不合法，请检查证件类型与号码是否匹配 | `idType` 非法或 `idNo` 格式不匹配 | -| `581113` | 手机号格式非法（应为 11 位数字） | 非空 `phone` 或 `emergencyPhone` 不是 11 位数字 | -| `581114` | 出生日期不能晚于今天 | `birthday` 为未来日期 | -| `581118` | 新增出行人缺少必填字段 | 新增项的 `name/idType/idNo` 全部为空 | -| `581119` | 出行人证件号重复 | 同一请求或订单内出现重复证件号 | -| `581122` | 订单不属于当前用户 | 订单不存在或不属于当前登录用户 | -| `581145` | 订单已确认，出行人信息不可再经小程序修改，如需变更请联系定制师 | 订单状态不在 `PENDING_PAY/CUSTOMIZING` 白名单 | -| `581149` | 出行人类型人数超出订单人数配置 | 根据生日派生后的某类出行人数超过订单声明配额 | - -## 6. 示例 - -### 6.1 典型成功：两人五项完整，仅一人有手机号 - -**请求** - -```http -POST /mp/v3/order/2079576729147338754/traveler/batch-edit -Authorization: Bearer <mp-token> -Content-Type: application/json -``` - -```json -{ - "travelers": [ - { - "id": "2079576729147338801", - "name": "张三", - "gender": "1", - "birthday": "1990-01-01", - "idType": "PASSPORT", - "idNo": "P1234567", - "nationality": "中国", - "race": "汉族", - "phone": "13800138000", - "emergencyContact": null, - "emergencyPhone": null, - "roomGroupNo": 1 - }, - { - "id": "2079576729147338802", - "name": "李四", - "gender": "2", - "birthday": "1992-02-02", - "idType": "PASSPORT", - "idNo": "P7654321", - "nationality": "中国", - "race": "汉族", - "phone": "", - "emergencyContact": null, - "emergencyPhone": null, - "roomGroupNo": 1 - } - ] -} -``` - -**响应** - -```json -{ - "code": 200, - "message": "成功", - "data": { - "createdCount": 0, - "updatedCount": 2, - "completedCount": 2, - "pendingCount": 0, - "allCompleted": true - }, - "traceId": "a1b2c3d4-e5f6-7890", - "success": true -} -``` - -### 6.2 边界成功：五项全部完整，但整单没有手机号 - -假设订单声明人数和实际人数均为 2，且请求将最后一部手机号清空。 - -**请求** - -```http -POST /mp/v3/order/2079576729147338754/traveler/batch-edit -Authorization: Bearer <mp-token> -Content-Type: application/json -``` - -```json -{ - "travelers": [ - { - "id": "2079576729147338801", - "name": "张三", - "gender": "1", - "birthday": "1990-01-01", - "idType": "PASSPORT", - "idNo": "P1234567", - "phone": "" - }, - { - "id": "2079576729147338802", - "name": "李四", - "gender": "2", - "birthday": "1992-02-02", - "idType": "PASSPORT", - "idNo": "P7654321", - "phone": "" - } - ] -} -``` - -**响应** - -```json -{ - "code": 200, - "message": "成功", - "data": { - "createdCount": 0, - "updatedCount": 2, - "completedCount": 2, - "pendingCount": 0, - "allCompleted": false - }, - "traceId": "a1b2c3d4-e5f6-7890", - "success": true -} -``` - -这里 `completedCount=2` 表示两人的五项资料都完整；`allCompleted=false` 表示订单级“至少一名出行人有手机号”门禁未满足。 - -### 6.3 业务失败：订单已确认 - -**请求** - -```http -POST /mp/v3/order/2079576729147338754/traveler/batch-edit -Authorization: Bearer <mp-token> -Content-Type: application/json -``` - -```json -{ - "travelers": [ - { - "id": "2079576729147338801", - "name": "张三", - "gender": "1", - "birthday": "1990-01-01", - "idType": "PASSPORT", - "idNo": "P1234567", - "phone": "13800138000" - } - ] -} -``` - -**响应** - -```json -{ - "code": 581145, - "message": "订单已确认，出行人信息不可再经小程序修改，如需变更请联系定制师", - "data": null, - "traceId": "a1b2c3d4-e5f6-7890", - "success": false -} -``` - -## 7. 修改前后对比 - -| 场景 | 修改前 | 修改后 | -|---|---|---| -| 单名成人五项完整但本人无手机号 | 可能计入 `pendingCount` | 计入 `completedCount` | -| 同行人已有手机号 | 仍可能要求每名成人各自填写 | 整单手机号门禁已满足 | -| 五项完整且整单无手机号 | 逐人完成状态与手机号门禁混合 | `completedCount` 可等于实际人数，但 `allCompleted=false` | -| 请求 / 响应结构 | 现有字段 | 不变 | - -## 8. 消费注意事项 - -- 不要按“每名成人必须有手机号”在本地重算资料完成状态。 -- `completedCount` 和 `pendingCount` 是操作后订单内的总量，不是本次请求中发生状态变化的行数。 -- 判断本接口是否已满足整单补全条件，以响应 `allCompleted` 为准；它已同时包含人数、五项资料和订单级手机号门禁。 -- `phone=null` 在更新场景表示保留原值；需要清空手机号时传空字符串。 - -## 9. 关联 - -- **Issue**: [#5203](https://git.1814.love:8443/wx/HL/issues/5203) -- **PR**: [#5210](https://git.1814.love:8443/wx/HL/pulls/5210) -- **Merge commit**: [88d0aec8375b56b5b8141984645a6998f8a42609](https://git.1814.love:8443/wx/HL/commit/88d0aec8375b56b5b8141984645a6998f8a42609) diff --git a/changelogs/2026-07/79_5123_景区季节全量清空与标签同步-前端待处理-管理后台.md b/changelogs/2026-07/79_5123_景区季节全量清空与标签同步-前端待处理-管理后台.md deleted file mode 100644 index 28be04e..0000000 --- a/changelogs/2026-07/79_5123_景区季节全量清空与标签同步-前端待处理-管理后台.md +++ /dev/null @@ -1,111 +0,0 @@ -# 【前端待处理·管理后台】景区季节全量清空与标签同步（#5123） - -## 目标前端 - -- 端类型：管理后台（Web） -- 目标仓库：`mmg/hl-ui` -- 目标分支：按前端仓库当前发布流程执行 -- 后端工单：`wx/HL #5123` -- 小程序：无需改页面，但必须参与接口与缓存回退验收 - -## 问题与根因 - -`src/views/resource/scenic/SeasonDrawer.vue` 的 `handleSave()` 目前只在 -`isSeasonConfigured(form)` 为 true 时调用 PUT。已存在的季节被全部清空后， -该判断变为 false，前端既不发 PUT，也没有调用后端已有 DELETE，数据库旧记录仍在， -因此重新打开抽屉会回显旧内容，页签“已配置”和景区列表季节标签也不会消失。 - -后端同时修复了可空字段写入 null、季节素材引用解绑，以及管理后台/小程序相关缓存依赖失效。 -前端不能继续用“不发请求”表达删除已存在季节。 - -## 接口契约 - -### 查询季节列表 - -```http -GET /admin/scenic/spot/{scenicId}/seasons -``` - -### 保存仍有内容的季节 - -```http -PUT /admin/scenic/spot/{scenicId}/season/{seasonType} -Content-Type: application/json -``` - -### 删除已全量清空的季节 - -```http -DELETE /admin/scenic/spot/{scenicId}/season/{seasonType} -``` - -`seasonType` 取 `spring`、`summer`、`autumn`、`winter`。DELETE 无请求体，沿用现有管理后台鉴权。 - -## 前端改动要求 - -### 1. API 封装 - -在 `src/api/scenic.js` 新增并导出删除方法，例如： - -```js -export function deleteScenicSeason(scenicId, seasonType) { - return http.delete(`/scenic/spot/${scenicId}/season/${seasonType}`) -} -``` - -### 2. 记录初始已配置季节 - -`SeasonDrawer.vue` 每次打开并成功加载季节列表后，记录后端实际返回过的 `seasonType` 集合。 - -- 加载前清空该集合，避免切换景区时串数据。 -- 只以后端列表是否存在记录作为“初始已配置”依据，不要用当前编辑中的 - `isSeasonConfigured()` 反推。 -- 查询失败时不得把未知状态当成“从未配置”；应阻止保存或保留错误状态，避免误判删除。 - -### 3. 保存判定 - -遍历四季时按以下规则处理： - -| 初始状态 | 当前表单 | 请求 | -| --- | --- | --- | -| 不存在 | 全空 | 不请求 | -| 不存在 | 有内容 | PUT | -| 已存在 | 有内容 | PUT | -| 已存在 | 全空 | DELETE | - -所有文本字段都按 `trim()` 后判断是否为空；素材按有效 `id` 判断，空壳对象不能让季节继续显示为已配置。 - -同一次保存中任一季节请求失败时，不得关闭抽屉或显示“全部保存成功”；应保留编辑内容并明确提示失败季节。 -全部请求成功后重新 GET 季节列表，再触发父级景区列表刷新，确保以下状态以服务端结果收敛： - -- 当前抽屉内容不再回显已删除季节。 -- 对应页签“已配置”标记消失。 -- 景区列表对应季节标签消失。 -- 其他季节和景区基础信息不变。 - -## 小程序链路说明 - -小程序产品详情会经 product-service 和 resource-service 读取季节亮点及季节媒体。 -后端已为实时产品详情、订单快照、mp-service 产品聚合和景区详情缓存补齐 -`table:scenic_season` / `table:scenic_spot` 依赖。 - -季节删除后，小程序不得继续显示旧 `seasonHighlights`、封面、轮播图或视频；未命中季节时应回退景区本体媒体和节点快照描述。前端管理后台无需主动清小程序 Redis，也不得新增清缓存接口。 - -## 验收清单 - -- [ ] 仅配置描述和亮点的季节，两项全部清空并保存后，重新打开不再回显。 -- [ ] 对应页签“已配置”标记消失。 -- [ ] 保存成功并刷新景区列表后，对应季节标签消失。 -- [ ] 保留其他内容时，可单独清空描述、亮点、封面、轮播图和视频。 -- [ ] 清空一个季节不影响其他季节及景区基础信息。 -- [ ] 从未配置且仍为空的季节不发 PUT 或 DELETE。 -- [ ] 查询季节列表失败时不会误发 DELETE。 -- [ ] 部分请求失败时抽屉保留，且不会提示全部成功。 -- [ ] 小程序产品详情不再返回已删除季节的亮点或媒体。 -- [ ] 小程序在季节未命中时正确回退景区本体媒体和节点快照描述。 - -## 发布说明 - -- 本文是前端修复与联调通知，不代表已修改或发布 `mmg/hl-ui`。 -- 前端完成后须创建并指派自身工单，走分支、PR、测试和发布流程，并关联 `wx/HL #5123`。 -- 测试环境验收必须通过网关使用真实管理员鉴权完成 PUT、DELETE、GET 回读；记录不得包含 token、Cookie 或真实隐私数据。 diff --git a/package.json b/package.json deleted file mode 100644 index c198b01..0000000 --- a/package.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "hl-api-changelog-quality-gates", - "private": true, - "type": "module", - "scripts": { - "test": "node --test tests/validate-changelog-filenames.test.mjs tests/validate-changelog-frontmatter.test.mjs", - "check:filenames": "node scripts/validate-changelog-filenames.mjs", - "check:frontmatter": "node scripts/validate-changelog-frontmatter.mjs" - }, - "engines": { - "node": ">=20" - } -} diff --git a/scripts/validate-changelog-filenames.mjs b/scripts/validate-changelog-filenames.mjs deleted file mode 100644 index 068632c..0000000 --- a/scripts/validate-changelog-filenames.mjs +++ /dev/null @@ -1,316 +0,0 @@ -#!/usr/bin/env node - -import { execFileSync } from 'node:child_process'; -import { readFileSync } from 'node:fs'; -import { pathToFileURL } from 'node:url'; - -const CONTROLLED_ROOTS = new Map([ - ['changelogs-v2', '管理后台'], - ['changelogs-v2-mp', '小程序端'], -]); -const CHANGE_TYPES = new Set(['新增接口', '修改接口', '删除接口']); - -function ruleError(code, path, message, expected) { - return { code, path, message, expected }; -} - -export function getShanghaiDate(now = new Date()) { - if (!(now instanceof Date) || Number.isNaN(now.getTime())) { - throw new TypeError('The validation clock must be a valid Date.'); - } - - const parts = new Intl.DateTimeFormat('en-CA', { - timeZone: 'Asia/Shanghai', - year: 'numeric', - month: '2-digit', - day: '2-digit', - }).formatToParts(now); - const values = Object.fromEntries(parts.map(({ type, value }) => [type, value])); - if (!/^\d{4}$/.test(values.year) || !/^\d{2}$/.test(values.month) || !/^\d{2}$/.test(values.day)) { - throw new Error('Unable to derive the current Asia/Shanghai calendar date.'); - } - - return { - yearMonth: `${values.year}-${values.month}`, - day: values.day, - isoDate: `${values.year}-${values.month}-${values.day}`, - }; -} - -export function parseNameStatusZ(raw) { - const text = Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw ?? ''); - const tokens = text.split('\0'); - if (tokens.at(-1) === '') { - tokens.pop(); - } - - const records = []; - for (let index = 0; index < tokens.length;) { - const status = tokens[index++]; - if (!status) { - throw new Error('Malformed git diff: an empty status token was found.'); - } - - if (/^[RC]\d{1,3}$/.test(status)) { - const sourcePath = tokens[index++]; - const targetPath = tokens[index++]; - if (sourcePath === undefined || targetPath === undefined) { - throw new Error(`Malformed git diff: ${status} must contain source and target paths.`); - } - records.push({ status, sourcePath, targetPath }); - continue; - } - - const targetPath = tokens[index++]; - if (targetPath === undefined) { - throw new Error(`Malformed git diff: ${status} is missing its path.`); - } - records.push({ status, targetPath }); - } - return records; -} - -export function collectNewTargetPaths(records) { - return records - .filter(({ status }) => status === 'A' || /^C\d{1,3}$/.test(status) || /^R\d{1,3}$/.test(status)) - .map(({ targetPath }) => targetPath); -} - -export function controlledRootForPath(inputPath) { - const candidate = String(inputPath); - for (const root of CONTROLLED_ROOTS.keys()) { - if (candidate === root || candidate.startsWith(`${root}/`) || candidate.startsWith(`${root}\\`)) { - return root; - } - } - return undefined; -} - -export function validateChangelogPath(inputPath, now = new Date()) { - const changelogPath = String(inputPath); - const root = controlledRootForPath(changelogPath); - if (!root) { - return []; - } - const expectedClient = CONTROLLED_ROOTS.get(root); - if (changelogPath.includes('\\')) { - return [ruleError( - 'E_STRUCTURE', - changelogPath, - '受控 Git 路径包含反斜杠；反斜杠是文件名字节，不是路径分隔符', - `${root}/YYYY-MM/DD_issue_标题-{新增接口|修改接口|删除接口}-${expectedClient}.md`, - )]; - } - - const expectedDate = getShanghaiDate(now); - const errors = []; - const segments = changelogPath.split('/'); - if (segments.length !== 3 || !segments[2].endsWith('.md')) { - return [ruleError( - 'E_STRUCTURE', - changelogPath, - '路径层级或扩展名不符合规则', - `${root}/YYYY-MM/DD_issue_标题-{新增接口|修改接口|删除接口}-${expectedClient}.md`, - )]; - } - - const [, yearMonth, filename] = segments; - if (yearMonth !== expectedDate.yearMonth) { - errors.push(ruleError( - 'E_MONTH', - changelogPath, - `月目录为 ${yearMonth}`, - `Asia/Shanghai 当天的 ${expectedDate.yearMonth}`, - )); - } - - const stem = filename.slice(0, -3); - const clientSeparator = stem.lastIndexOf('-'); - const actualClient = clientSeparator >= 0 ? stem.slice(clientSeparator + 1) : ''; - const beforeClient = clientSeparator >= 0 ? stem.slice(0, clientSeparator) : stem; - if (actualClient !== expectedClient) { - errors.push(ruleError( - 'E_CLIENT', - changelogPath, - `端类型为 ${actualClient || '(缺失)'}`, - expectedClient, - )); - } - - const typeSeparator = beforeClient.lastIndexOf('-'); - const actualType = typeSeparator >= 0 ? beforeClient.slice(typeSeparator + 1) : ''; - const prefix = typeSeparator >= 0 ? beforeClient.slice(0, typeSeparator) : beforeClient; - if (!CHANGE_TYPES.has(actualType)) { - errors.push(ruleError( - 'E_CHANGE_TYPE', - changelogPath, - `变更类型为 ${actualType || '(缺失)'}`, - '新增接口 / 修改接口 / 删除接口', - )); - } - - const prefixMatch = /^(\d{2})_([^_]*)_(.*)$/.exec(prefix); - if (!prefixMatch) { - const dayMatch = /^(\d{2})_/.exec(prefix); - if (dayMatch && dayMatch[1] !== expectedDate.day) { - errors.push(ruleError('E_DAY', changelogPath, `日前缀为 ${dayMatch[1]}`, expectedDate.day)); - } - errors.push(ruleError( - 'E_ISSUE', - changelogPath, - '文件名缺少可识别的正整数 Issue 号', - 'DD_[1-9][0-9]*_标题', - )); - return errors; - } - - const [, day, issue, title] = prefixMatch; - if (day !== expectedDate.day) { - errors.push(ruleError('E_DAY', changelogPath, `日前缀为 ${day}`, expectedDate.day)); - } - if (!/^[1-9]\d*$/.test(issue)) { - errors.push(ruleError('E_ISSUE', changelogPath, `Issue 号为 ${issue || '(缺失)'}`, '不带 # 的十进制正整数')); - } - if (title.trim() === '') { - errors.push(ruleError('E_TITLE', changelogPath, '业务标题为空', '非空业务标题')); - } - - return errors; -} - -export function runValidation(records, now = new Date()) { - const targetPaths = collectNewTargetPaths(records); - const controlledPaths = targetPaths.filter((targetPath) => controlledRootForPath(targetPath)); - const errors = controlledPaths.flatMap((targetPath) => validateChangelogPath(targetPath, now)); - return { - targetCount: targetPaths.length, - checkedCount: controlledPaths.length, - errors, - expectedDate: getShanghaiDate(now), - }; -} - -export function parseArguments(argv) { - const options = {}; - for (let index = 0; index < argv.length; index += 2) { - const flag = argv[index]; - const value = argv[index + 1]; - if (!['--event', '--base', '--head'].includes(flag) || value === undefined) { - throw new Error(`Unsupported or incomplete argument: ${flag ?? '(missing)'}`); - } - options[flag.slice(2)] = value; - } - if (options.event && (options.base || options.head)) { - throw new Error('--event cannot be combined with --base/--head.'); - } - if (!options.event && (!options.base || !options.head)) { - throw new Error('Use --event <path> or both --base <ref> --head <ref>.'); - } - return options; -} - -function runGit(args, options = {}) { - return execFileSync('git', args, { - ...options, - stdio: ['pipe', 'pipe', 'pipe'], - }); -} - -function resolveCommitRef(ref, label) { - if (typeof ref !== 'string' || ref.length === 0 || /[\0\r\n]/.test(ref)) { - throw new Error(`${label} must be a non-empty Git ref without control characters.`); - } - let resolved; - try { - resolved = runGit(['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`], { encoding: 'utf8' }).trim(); - } catch { - throw new Error(`${label} does not resolve to an existing commit.`); - } - if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(resolved)) { - throw new Error(`${label} resolved to an unexpected object ID.`); - } - return resolved; -} - -function resolveEventCommitSha(sha, label) { - if (typeof sha !== 'string' || !/^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$/.test(sha)) { - throw new Error(`${label} must be a full 40- or 64-character hexadecimal commit SHA.`); - } - return resolveCommitRef(sha.toLowerCase(), label); -} - -function emptyTreeObjectId() { - const objectId = runGit(['hash-object', '-t', 'tree', '--stdin'], { - input: Buffer.alloc(0), - encoding: 'utf8', - }).trim(); - if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(objectId)) { - throw new Error('Git returned an unexpected empty-tree object ID.'); - } - return objectId; -} - -function gitDiff(revisions) { - return runGit(['diff', '--name-status', '-z', '--find-renames', ...revisions, '--'], { - encoding: 'buffer', - maxBuffer: 64 * 1024 * 1024, - }); -} - -export function diffFromOptions(options) { - if (!options.event) { - const base = resolveCommitRef(options.base, 'base ref'); - const head = resolveCommitRef(options.head, 'head ref'); - return gitDiff([`${base}...${head}`]); - } - - const event = JSON.parse(readFileSync(options.event, 'utf8')); - if (event.pull_request) { - const base = event.pull_request.base?.sha; - const head = event.pull_request.head?.sha; - if (!base || !head) { - throw new Error('The pull_request event is missing base/head SHA values.'); - } - const resolvedBase = resolveEventCommitSha(base, 'pull_request base SHA'); - const resolvedHead = resolveEventCommitSha(head, 'pull_request head SHA'); - return gitDiff([`${resolvedBase}...${resolvedHead}`]); - } - - if (event.before && event.after) { - if (typeof event.before !== 'string' || !/^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$/.test(event.before)) { - throw new Error('push before SHA must be a full 40- or 64-character hexadecimal value.'); - } - const before = /^0+$/.test(event.before) - ? emptyTreeObjectId() - : resolveEventCommitSha(event.before, 'push before SHA'); - const after = resolveEventCommitSha(event.after, 'push after SHA'); - return gitDiff([before, after]); - } - - throw new Error('Unsupported event payload: expected pull_request or push before/after SHA values.'); -} - -export function main(argv = process.argv.slice(2)) { - try { - const options = parseArguments(argv); - const records = parseNameStatusZ(diffFromOptions(options)); - const result = runValidation(records, new Date()); - if (result.errors.length > 0) { - for (const error of result.errors) { - console.error(`[${error.code}] ${error.path}: ${error.message}; expected ${error.expected}`); - } - console.error(`FAIL: found ${new Set(result.errors.map(({ path }) => path)).size} invalid changelog path(s) among ${result.checkedCount} controlled changelog path(s).`); - return 1; - } - console.log(`PASS: validated ${result.checkedCount} controlled changelog path(s) from ${result.targetCount} new target path(s); expected Shanghai date ${result.expectedDate.isoDate}.`); - return 0; - } catch (error) { - console.error(`ERROR: ${error instanceof Error ? error.message : String(error)}`); - return 2; - } -} - -const isCli = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url; -if (isCli) { - process.exitCode = main(); -} diff --git a/scripts/validate-changelog-frontmatter.mjs b/scripts/validate-changelog-frontmatter.mjs deleted file mode 100644 index 7c03af2..0000000 --- a/scripts/validate-changelog-frontmatter.mjs +++ /dev/null @@ -1,265 +0,0 @@ -#!/usr/bin/env node - -import { readFileSync } from 'node:fs'; -import path from 'node:path'; -import { pathToFileURL } from 'node:url'; - -import { - controlledRootForPath, - diffFromOptions, - parseArguments, - parseNameStatusZ, -} from './validate-changelog-filenames.mjs'; - -const FRONTEND_STATUSES = new Set([ - 'not_required', - 'pending', - 'claimed', - 'implemented', - 'released', - 'verified', -]); -const BACKEND_STATUSES = new Set(['pending', 'tested', 'deployed']); -const GATEWAY_STATUSES = new Set(['pending', 'verified', 'not_required']); -const CONSUMERS = new Set(['admin', 'mp', 'internal', 'multiple']); -const CHANGE_TYPES = new Set(['新增接口', '修改接口', '删除接口']); -const REQUIRED_KEYS = [ - 'schema', - 'ticket', - 'title', - 'consumer', - 'change_type', - 'backend_status', - 'gateway_status', - 'frontend_status', - 'frontend_owner', - 'frontend_ref', - 'target_release', - 'verified_at', - 'updated_at', - 'base', -]; - -function ruleError(code, file, message) { - return { code, path: file, message }; -} - -function isIsoDate(value) { - const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value ?? ''); - if (!match) { - return false; - } - const year = Number(match[1]); - const month = Number(match[2]); - const day = Number(match[3]); - const parsed = new Date(Date.UTC(year, month - 1, day)); - return parsed.getUTCFullYear() === year - && parsed.getUTCMonth() === month - 1 - && parsed.getUTCDate() === day; -} - -function isIsoDateOrTime(value) { - if (isIsoDate(value)) { - return true; - } - return /^\d{4}-\d{2}-\d{2}T/.test(value ?? '') - && Number.isFinite(Date.parse(value)); -} - -export function parseFrontmatter(text) { - const value = String(text ?? '').replaceAll('\r\n', '\n'); - if (!value.startsWith('---\n')) { - return { metadata: undefined, body: value }; - } - const end = value.indexOf('\n---\n', 4); - if (end < 0) { - return { metadata: undefined, body: value }; - } - const metadata = {}; - for (const line of value.slice(4, end).split('\n')) { - const separator = line.indexOf(':'); - if (separator < 0) { - continue; - } - const key = line.slice(0, separator).trim(); - let fieldValue = line.slice(separator + 1).trim(); - if ( - (fieldValue.startsWith('"') && fieldValue.endsWith('"')) - || (fieldValue.startsWith("'") && fieldValue.endsWith("'")) - ) { - fieldValue = fieldValue.slice(1, -1); - } - metadata[key] = fieldValue; - } - return { metadata, body: value.slice(end + 5) }; -} - -export function validateFrontendState(metadata) { - const errors = []; - const status = metadata.frontend_status; - const owner = metadata.frontend_owner?.trim() ?? ''; - const reference = metadata.frontend_ref?.trim() ?? ''; - const release = metadata.target_release?.trim() ?? ''; - const verifiedAt = metadata.verified_at?.trim() ?? ''; - if (!FRONTEND_STATUSES.has(status)) { - return [`frontend_status 非法: ${status || '(空)'}`]; - } - if (['claimed', 'implemented', 'released', 'verified'].includes(status) && !owner) { - errors.push(`${status} 必须填写 frontend_owner`); - } - if (['implemented', 'released', 'verified'].includes(status) && !reference) { - errors.push(`${status} 必须填写 frontend_ref`); - } - if (['released', 'verified'].includes(status) && !release) { - errors.push(`${status} 必须填写 target_release`); - } - if (status === 'verified' && !verifiedAt) { - errors.push('verified 必须填写 verified_at'); - } - if (verifiedAt && !isIsoDateOrTime(verifiedAt)) { - errors.push('verified_at 必须是 ISO 日期或时间'); - } - if (status === 'not_required' && [owner, reference, release, verifiedAt].some(Boolean)) { - errors.push('not_required 不得保留前端负责人、引用、版本或验证时间'); - } - return errors; -} - -export function validateFrontendTransition(current, target, reason = '') { - if (!FRONTEND_STATUSES.has(current) || !FRONTEND_STATUSES.has(target)) { - return ['frontend_status 非法']; - } - if (current === target) { - return []; - } - if (current === 'not_required' || target === 'not_required') { - return reason.trim() ? [] : ['涉及 not_required 的迁移必须填写原因']; - } - const order = ['pending', 'claimed', 'implemented', 'released', 'verified']; - const currentIndex = order.indexOf(current); - const targetIndex = order.indexOf(target); - if (targetIndex === currentIndex + 1) { - return []; - } - if (targetIndex < currentIndex) { - return reason.trim() ? [] : ['状态回退必须填写原因']; - } - return [`禁止跨级迁移: ${current} -> ${target}`]; -} - -export function validateV2Document(file, text, { requireV2 = false } = {}) { - const { metadata, body } = parseFrontmatter(text); - if (!metadata) { - return requireV2 ? [ruleError('E_FRONTMATTER', file, '新增 changelog 缺少 YAML Front Matter')] : []; - } - if (metadata.schema !== 'hl-changelog/v2') { - return requireV2 - ? [ruleError('E_SCHEMA', file, `新增 changelog 必须使用 hl-changelog/v2，当前为 ${metadata.schema || '(空)'}`)] - : []; - } - const errors = []; - for (const key of REQUIRED_KEYS) { - if (!(key in metadata)) { - errors.push(ruleError('E_REQUIRED', file, `frontmatter 缺少 ${key}`)); - } - } - for (const key of ['ticket', 'title', 'consumer', 'change_type', 'backend_status', 'gateway_status', 'frontend_status', 'updated_at', 'base']) { - if (!metadata[key]?.trim()) { - errors.push(ruleError('E_REQUIRED', file, `${key} 不能为空`)); - } - } - if (!CHANGE_TYPES.has(metadata.change_type)) { - errors.push(ruleError('E_CHANGE_TYPE', file, `change_type 非法: ${metadata.change_type || '(空)'}`)); - } - if (!CONSUMERS.has(metadata.consumer)) { - errors.push(ruleError('E_CONSUMER', file, `consumer 非法: ${metadata.consumer || '(空)'}`)); - } - if (!BACKEND_STATUSES.has(metadata.backend_status)) { - errors.push(ruleError('E_BACKEND_STATUS', file, `backend_status 非法: ${metadata.backend_status || '(空)'}`)); - } - if (!GATEWAY_STATUSES.has(metadata.gateway_status)) { - errors.push(ruleError('E_GATEWAY_STATUS', file, `gateway_status 非法: ${metadata.gateway_status || '(空)'}`)); - } - if (metadata.backend_status !== 'deployed') { - errors.push(ruleError('E_BACKEND_PENDING', file, '发布的 changelog 必须是 backend_status=deployed')); - } - if (metadata.gateway_status === 'pending') { - errors.push(ruleError('E_GATEWAY_PENDING', file, '发布的 changelog 不能保留 gateway_status=pending')); - } - for (const message of validateFrontendState(metadata)) { - errors.push(ruleError('E_FRONTEND_STATE', file, message)); - } - if (metadata.consumer === 'internal' && metadata.frontend_status !== 'not_required') { - errors.push(ruleError('E_FRONTEND_STATE', file, 'internal consumer 必须使用 frontend_status=not_required')); - } - if (!isIsoDate(metadata.updated_at)) { - errors.push(ruleError('E_UPDATED_AT', file, 'updated_at 必须是真实的 YYYY-MM-DD 日期')); - } - const filename = path.posix.basename(file); - const issue = /^\d{2}_([1-9]\d*)_/.exec(filename)?.[1]; - if (issue && metadata.ticket !== issue) { - errors.push(ruleError('E_TICKET_MISMATCH', file, `ticket=${metadata.ticket} 与文件名 Issue=${issue} 不一致`)); - } - const filenameType = /-(新增接口|修改接口|删除接口)-(?:管理后台|小程序端)\.md$/.exec(filename)?.[1]; - if (filenameType && metadata.change_type !== filenameType) { - errors.push(ruleError('E_TYPE_MISMATCH', file, `change_type=${metadata.change_type} 与文件名=${filenameType} 不一致`)); - } - if (/\{[^{}\n]+\}|\bTODO\b|待补充/i.test(body)) { - errors.push(ruleError('E_PLACEHOLDER', file, '正文仍有 TODO、待补充或模板占位符')); - } - if (!body.includes('## 变更接口') || !body.includes('## 验证证据')) { - errors.push(ruleError('E_SECTIONS', file, '正文缺少“变更接口”或“验证证据”章节')); - } - return errors; -} - -export function collectChangedDocuments(records) { - return records - .filter(({ status }) => status !== 'D') - .map((record) => ({ - path: record.targetPath, - isNew: record.status === 'A' || /^C\d{1,3}$/.test(record.status) || /^R\d{1,3}$/.test(record.status), - })) - .filter(({ path: file }) => controlledRootForPath(file) && file.endsWith('.md')); -} - -export function runFrontmatterValidation(records, root = process.cwd()) { - const documents = collectChangedDocuments(records); - const errors = []; - for (const document of documents) { - let text; - try { - text = readFileSync(path.join(root, ...document.path.split('/')), 'utf8'); - } catch (error) { - errors.push(ruleError('E_READ', document.path, `无法读取文件: ${error.message}`)); - continue; - } - errors.push(...validateV2Document(document.path, text, { requireV2: document.isNew })); - } - return { checkedCount: documents.length, errors }; -} - -export function main(argv = process.argv.slice(2)) { - try { - const options = parseArguments(argv); - const records = parseNameStatusZ(diffFromOptions(options)); - const result = runFrontmatterValidation(records); - if (result.errors.length > 0) { - for (const error of result.errors) { - console.error(`[${error.code}] ${error.path}: ${error.message}`); - } - console.error(`FAIL: ${result.errors.length} frontmatter error(s) in ${result.checkedCount} changelog file(s).`); - return 1; - } - console.log(`PASS: validated frontmatter for ${result.checkedCount} changed changelog file(s).`); - return 0; - } catch (error) { - console.error(`ERROR: ${error instanceof Error ? error.message : String(error)}`); - return 2; - } -} - -const isCli = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url; -if (isCli) { - process.exitCode = main(); -} diff --git a/tests/validate-changelog-filenames.test.mjs b/tests/validate-changelog-filenames.test.mjs deleted file mode 100644 index b47a226..0000000 --- a/tests/validate-changelog-filenames.test.mjs +++ /dev/null @@ -1,293 +0,0 @@ -import assert from 'node:assert/strict'; -import { execFileSync } from 'node:child_process'; -import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import path from 'node:path'; -import test from 'node:test'; -import { fileURLToPath } from 'node:url'; - -import { - collectNewTargetPaths, - getShanghaiDate, - parseNameStatusZ, - runValidation, - validateChangelogPath, -} from '../scripts/validate-changelog-filenames.mjs'; - -const SHANGHAI_NOW = new Date('2026-07-22T04:00:00.000Z'); -const CLI_PATH = fileURLToPath(new URL('../scripts/validate-changelog-filenames.mjs', import.meta.url)); - -function validAdmin({ day = '22', month = '2026-07', issue = '5161', title = '文件名校验', type = '新增接口', client = '管理后台' } = {}) { - return `changelogs-v2/${month}/${day}_${issue}_${title}-${type}-${client}.md`; -} - -function validMp({ day = '22', month = '2026-07', issue = '5161', title = '文件名校验', type = '修改接口', client = '小程序端' } = {}) { - return `changelogs-v2-mp/${month}/${day}_${issue}_${title}-${type}-${client}.md`; -} - -function codes(file, now = SHANGHAI_NOW) { - return validateChangelogPath(file, now).map((error) => error.code); -} - -test('accepts a valid v2 admin path', () => { - assert.deepEqual(validateChangelogPath(validAdmin(), SHANGHAI_NOW), []); -}); - -test('accepts a valid v2-mp path', () => { - assert.deepEqual(validateChangelogPath(validMp(), SHANGHAI_NOW), []); -}); - -test('uses Asia/Shanghai when UTC is still the previous day', () => { - const now = new Date('2026-07-21T16:05:00.000Z'); - assert.equal(getShanghaiDate(now).isoDate, '2026-07-22'); - assert.deepEqual(validateChangelogPath(validAdmin(), now), []); -}); - -test('accepts the real leap day', () => { - const now = new Date('2024-02-29T04:00:00.000Z'); - assert.deepEqual(validateChangelogPath(validAdmin({ month: '2024-02', day: '29' }), now), []); -}); - -test('rejects a wrong day', () => { - assert.ok(codes(validAdmin({ day: '21' })).includes('E_DAY')); -}); - -test('rejects a wrong month directory', () => { - assert.ok(codes(validAdmin({ month: '2026-06' })).includes('E_MONTH')); -}); - -test('rejects a day greater than 31', () => { - assert.ok(codes(validAdmin({ day: '63' })).includes('E_DAY')); -}); - -test('rejects a missing issue number', () => { - assert.ok(codes('changelogs-v2/2026-07/22_标题-新增接口-管理后台.md').includes('E_ISSUE')); -}); - -test('rejects issue zero', () => { - assert.ok(codes(validAdmin({ issue: '0' })).includes('E_ISSUE')); -}); - -test('rejects a hash-prefixed issue', () => { - assert.ok(codes(validAdmin({ issue: '#5161' })).includes('E_ISSUE')); -}); - -test('rejects a non-numeric issue', () => { - assert.ok(codes(validAdmin({ issue: 'ABC' })).includes('E_ISSUE')); -}); - -test('rejects an unsupported change type', () => { - assert.ok(codes(validAdmin({ type: '新增字段' })).includes('E_CHANGE_TYPE')); -}); - -test('rejects the mini-program client in v2', () => { - assert.ok(codes(validAdmin({ client: '小程序端' })).includes('E_CLIENT')); -}); - -test('rejects the admin client in v2-mp', () => { - assert.ok(codes(validMp({ client: '管理后台' })).includes('E_CLIENT')); -}); - -test('rejects an empty title', () => { - assert.ok(codes(validAdmin({ title: '' })).includes('E_TITLE')); -}); - -test('rejects a backslash inside a controlled physical path', () => { - const physicalPath = 'changelogs-v2/2026-07\\22_5161_绕过-新增接口-管理后台.md'; - assert.ok(codes(physicalPath).includes('E_STRUCTURE')); -}); - -test('rejects a root-level backslash pseudo path', () => { - const physicalPath = 'changelogs-v2\\2026-07\\22_5161_绕过-新增接口-管理后台.md'; - assert.ok(codes(physicalPath).includes('E_STRUCTURE')); -}); - -test('exempts phase-one changelogs', () => { - assert.deepEqual(validateChangelogPath('changelogs/2026-07/99_no_issue_anything.md', SHANGHAI_NOW), []); -}); - -test('parses NUL-delimited Chinese and space-containing paths', () => { - const raw = Buffer.from(`A\0${validAdmin({ title: '中文 空格' })}\0M\0old file.md\0`, 'utf8'); - assert.deepEqual(parseNameStatusZ(raw), [ - { status: 'A', targetPath: validAdmin({ title: '中文 空格' }) }, - { status: 'M', targetPath: 'old file.md' }, - ]); -}); - -test('exempts modified and deleted historical bad paths', () => { - const records = parseNameStatusZ(Buffer.from( - 'M\0changelogs-v2/2026-07/63_历史坏文件.md\0D\0changelogs-v2/2026-07/99_无issue.md\0', - 'utf8', - )); - assert.deepEqual(collectNewTargetPaths(records), []); - assert.equal(runValidation(records, SHANGHAI_NOW).errors.length, 0); -}); - -test('validates only a copy target path', () => { - const records = parseNameStatusZ(Buffer.from(`C100\0old.md\0${validAdmin()}\0`, 'utf8')); - assert.deepEqual(collectNewTargetPaths(records), [validAdmin()]); -}); - -test('accepts a rename from an old bad name to a valid target', () => { - const records = parseNameStatusZ(Buffer.from(`R100\0changelogs-v2/2026-07/63_old.md\0${validAdmin()}\0`, 'utf8')); - assert.equal(runValidation(records, SHANGHAI_NOW).errors.length, 0); -}); - -test('rejects a rename target with an old day', () => { - const target = validAdmin({ day: '21' }); - const records = parseNameStatusZ(Buffer.from(`R100\0changelogs-v2/2026-07/63_old.md\0${target}\0`, 'utf8')); - assert.ok(runValidation(records, SHANGHAI_NOW).errors.some((error) => error.code === 'E_DAY')); -}); - -test('aggregates all invalid paths instead of stopping at the first', () => { - const records = [ - { status: 'A', targetPath: validAdmin() }, - { status: 'A', targetPath: validMp() }, - { status: 'A', targetPath: validAdmin({ day: '21' }) }, - { status: 'A', targetPath: validMp({ issue: '0' }) }, - ]; - const result = runValidation(records, SHANGHAI_NOW); - assert.equal(new Set(result.errors.map((error) => error.path)).size, 2); - assert.equal(result.checkedCount, 4); -}); - -test('real git diff ignores historical modifications and validates an added path', () => { - const repo = mkdtempSync(path.join(tmpdir(), 'hl-changelog-gate-')); - try { - execFileSync('git', ['init', '-q'], { cwd: repo }); - execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: repo }); - execFileSync('git', ['config', 'user.name', 'Gate Test'], { cwd: repo }); - execFileSync('git', ['config', 'core.autocrlf', 'false'], { cwd: repo }); - const oldPath = path.join(repo, 'changelogs-v2', '2026-07', '63_old.md'); - mkdirSync(path.dirname(oldPath), { recursive: true }); - writeFileSync(oldPath, 'old\n'); - execFileSync('git', ['add', '.'], { cwd: repo }); - execFileSync('git', ['commit', '-qm', 'base'], { cwd: repo }); - const base = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim(); - - writeFileSync(oldPath, 'changed\n'); - const addedPath = path.join(repo, ...validAdmin().split('/')); - writeFileSync(addedPath, 'new\n'); - execFileSync('git', ['add', '.'], { cwd: repo }); - execFileSync('git', ['commit', '-qm', 'head'], { cwd: repo }); - const head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim(); - const raw = execFileSync('git', ['diff', '--name-status', '-z', '--find-renames', base, head], { cwd: repo }); - const result = runValidation(parseNameStatusZ(raw), SHANGHAI_NOW); - - assert.equal(result.checkedCount, 1); - assert.equal(result.errors.length, 0); - } finally { - rmSync(repo, { recursive: true, force: true }); - } -}); - -test('production CLI selects PR/push revisions safely and preserves exit-code semantics', async (t) => { - const repo = mkdtempSync(path.join(tmpdir(), 'hl-changelog-cli-')); - const eventPath = path.join(repo, 'event.json'); - - function git(...args) { - return execFileSync('git', args, { cwd: repo, encoding: 'utf8' }).trim(); - } - - function runCli(args) { - return execFileSync(process.execPath, [CLI_PATH, ...args], { - cwd: repo, - encoding: 'utf8', - stdio: ['ignore', 'pipe', 'pipe'], - }); - } - - function runCliResult(args) { - try { - return { status: 0, stdout: runCli(args), stderr: '' }; - } catch (error) { - return { - status: error.status, - stdout: String(error.stdout ?? ''), - stderr: String(error.stderr ?? ''), - }; - } - } - - function writeEvent(value) { - writeFileSync(eventPath, typeof value === 'string' ? value : JSON.stringify(value)); - } - - try { - git('init', '-q'); - git('config', 'user.email', 'test@example.com'); - git('config', 'user.name', 'Gate Test'); - git('config', 'core.autocrlf', 'false'); - writeFileSync(path.join(repo, 'README.md'), 'base\n'); - git('add', '.'); - git('commit', '-qm', 'base'); - const base = git('rev-parse', 'HEAD'); - - const today = getShanghaiDate(new Date()); - const validPath = validAdmin({ month: today.yearMonth, day: today.day }); - const addedPath = path.join(repo, ...validPath.split('/')); - mkdirSync(path.dirname(addedPath), { recursive: true }); - writeFileSync(addedPath, 'valid\n'); - git('add', '.'); - git('commit', '-qm', 'valid'); - const validHead = git('rev-parse', 'HEAD'); - - const wrongDay = today.day === '01' ? '02' : '01'; - const invalidPath = validAdmin({ month: today.yearMonth, day: wrongDay, issue: '5162' }); - writeFileSync(path.join(repo, ...invalidPath.split('/')), 'invalid\n'); - git('add', '.'); - git('commit', '-qm', 'invalid'); - const invalidHead = git('rev-parse', 'HEAD'); - - await t.test('PR event uses base...head and returns 0 for a legal addition', () => { - writeEvent({ pull_request: { base: { sha: base }, head: { sha: validHead } } }); - const result = runCliResult(['--event', eventPath]); - assert.equal(result.status, 0, result.stderr); - assert.match(result.stdout, /validated 1 controlled changelog path/); - }); - - await t.test('push event uses before/after and returns 0 for a legal addition', () => { - writeEvent({ before: base, after: validHead }); - const result = runCliResult(['--event', eventPath]); - assert.equal(result.status, 0, result.stderr); - }); - - await t.test('new-branch push uses the empty tree', () => { - writeEvent({ before: '0'.repeat(base.length), after: validHead }); - const result = runCliResult(['--event', eventPath]); - assert.equal(result.status, 0, result.stderr); - assert.match(result.stdout, /validated 1 controlled changelog path/); - }); - - await t.test('rule failure returns 1', () => { - writeEvent({ pull_request: { base: { sha: validHead }, head: { sha: invalidHead } } }); - const result = runCliResult(['--event', eventPath]); - assert.equal(result.status, 1); - assert.match(result.stderr, /\[E_DAY\]/); - }); - - await t.test('missing event fields return 2', () => { - writeEvent({ pull_request: { base: { sha: base }, head: {} } }); - assert.equal(runCliResult(['--event', eventPath]).status, 2); - }); - - await t.test('invalid JSON returns 2', () => { - writeEvent('{not-json'); - assert.equal(runCliResult(['--event', eventPath]).status, 2); - }); - - await t.test('nonexistent event commit returns 2', () => { - writeEvent({ before: base, after: 'f'.repeat(base.length) }); - assert.equal(runCliResult(['--event', eventPath]).status, 2); - }); - - await t.test('a Git option cannot be injected as a local ref', () => { - const result = runCliResult(['--base', '--output=gate-review', '--head', 'HEAD']); - assert.equal(result.status, 2); - assert.equal(existsSync(path.join(repo, 'gate-review')), false); - assert.equal(readdirSync(repo).some((name) => name.startsWith('gate-review')), false); - }); - } finally { - rmSync(repo, { recursive: true, force: true }); - } -}); diff --git a/tests/validate-changelog-frontmatter.test.mjs b/tests/validate-changelog-frontmatter.test.mjs deleted file mode 100644 index 23f7178..0000000 --- a/tests/validate-changelog-frontmatter.test.mjs +++ /dev/null @@ -1,134 +0,0 @@ -import assert from 'node:assert/strict'; -import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import path from 'node:path'; -import test from 'node:test'; - -import { - parseFrontmatter, - runFrontmatterValidation, - validateFrontendState, - validateFrontendTransition, - validateV2Document, -} from '../scripts/validate-changelog-frontmatter.mjs'; - - -const FILE = 'changelogs-v2/2026-07/24_5218_工作流治理-修改接口-管理后台.md'; - -function metadata(overrides = {}) { - return { - schema: 'hl-changelog/v2', - ticket: '5218', - title: '工作流治理', - consumer: 'admin', - change_type: '修改接口', - backend_status: 'deployed', - gateway_status: 'verified', - frontend_status: 'pending', - frontend_owner: '', - frontend_ref: '', - target_release: '', - verified_at: '', - status_note: '', - updated_at: '2026-07-24', - base: 'dev-v3', - ...overrides, - }; -} - -function document(overrides = {}) { - const fields = metadata(overrides); - const frontmatter = Object.entries(fields) - .map(([key, value]) => `${key}: "${value}"`) - .join('\n'); - return `---\n${frontmatter}\n---\n\n# 工作流治理\n\n## 变更接口\n\n- 无业务接口变化。\n\n## 验证证据\n\n- 自动化测试通过。\n`; -} - -test('parses quoted flat YAML frontmatter', () => { - const parsed = parseFrontmatter(document()); - assert.equal(parsed.metadata.schema, 'hl-changelog/v2'); - assert.equal(parsed.metadata.frontend_status, 'pending'); -}); - -test('accepts a complete v2 handoff with pending frontend consumption', () => { - assert.deepEqual(validateV2Document(FILE, document(), { requireV2: true }), []); -}); - -test('rejects backend and gateway pending at publication', () => { - const errors = validateV2Document( - FILE, - document({ backend_status: 'pending', gateway_status: 'pending' }), - { requireV2: true }, - ); - assert.ok(errors.some(({ code }) => code === 'E_BACKEND_PENDING')); - assert.ok(errors.some(({ code }) => code === 'E_GATEWAY_PENDING')); -}); - -test('requires frontend evidence as status advances', () => { - assert.deepEqual( - validateFrontendState(metadata({ frontend_status: 'claimed' })), - ['claimed 必须填写 frontend_owner'], - ); - assert.deepEqual( - validateFrontendState(metadata({ - frontend_status: 'implemented', - frontend_owner: 'frontend-team', - frontend_ref: 'mmg/hl-ui@abc1234', - })), - [], - ); - assert.ok( - validateFrontendState(metadata({ - frontend_status: 'verified', - frontend_owner: 'frontend-team', - frontend_ref: 'mmg/hl-ui@abc1234', - target_release: 'prod-2026.07.24', - verified_at: '2026-02-30', - })).includes('verified_at 必须是 ISO 日期或时间'), - ); -}); - -test('rejects skipped transitions and requires a rollback reason', () => { - assert.ok(validateFrontendTransition('pending', 'implemented').length > 0); - assert.deepEqual(validateFrontendTransition('pending', 'claimed'), []); - assert.ok(validateFrontendTransition('released', 'implemented').length > 0); - assert.deepEqual( - validateFrontendTransition('released', 'implemented', '测试发布已回滚'), - [], - ); -}); - -test('new changelog requires v2 while a modified legacy file remains compatible', () => { - const root = mkdtempSync(path.join(tmpdir(), 'hl-frontmatter-')); - try { - const file = path.join(root, ...FILE.split('/')); - mkdirSync(path.dirname(file), { recursive: true }); - writeFileSync(file, '# legacy\n'); - const newResult = runFrontmatterValidation([{ status: 'A', targetPath: FILE }], root); - assert.ok(newResult.errors.some(({ code }) => code === 'E_FRONTMATTER')); - const modifiedResult = runFrontmatterValidation([{ status: 'M', targetPath: FILE }], root); - assert.deepEqual(modifiedResult.errors, []); - } finally { - rmSync(root, { recursive: true, force: true }); - } -}); - -test('detects metadata and filename mismatches', () => { - const errors = validateV2Document( - FILE, - document({ ticket: '9999', change_type: '新增接口' }), - { requireV2: true }, - ); - assert.ok(errors.some(({ code }) => code === 'E_TICKET_MISMATCH')); - assert.ok(errors.some(({ code }) => code === 'E_TYPE_MISMATCH')); -}); - -test('rejects unsupported consumers and impossible dates', () => { - const errors = validateV2Document( - FILE, - document({ consumer: 'browser', updated_at: '2026-02-30' }), - { requireV2: true }, - ); - assert.ok(errors.some(({ code }) => code === 'E_CONSUMER')); - assert.ok(errors.some(({ code }) => code === 'E_UPDATED_AT')); -});