From 1a7ce36aea87408b493627d7c79710d8f82aafc7 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 20 Jun 2026 09:55:41 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E6=88=BF=E5=8A=A1?= =?UTF-8?q?=E5=8E=9F=E5=9E=8B=E5=AF=B9=E9=BD=90(=E4=BA=8C)=20=E9=85=8D?= =?UTF-8?q?=E6=88=BF=E6=94=B9=E5=8D=8F=E8=AE=AE=E4=BB=B7#4072=20+=20?= =?UTF-8?q?=E9=85=92=E5=BA=97=E5=AF=8C=E8=A1=A8=E5=8D=95/OCR#4073=20+=20?= =?UTF-8?q?=E6=9C=88=E5=BA=A6=E5=AF=B9=E8=B4=A6#4074?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-配房改协议价+酒店富表单OCR+月度对账-管理后台.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 changelogs-v2/2026-06/20_4072_4073_4074_房务原型对齐二-配房改协议价+酒店富表单OCR+月度对账-管理后台.md diff --git a/changelogs-v2/2026-06/20_4072_4073_4074_房务原型对齐二-配房改协议价+酒店富表单OCR+月度对账-管理后台.md b/changelogs-v2/2026-06/20_4072_4073_4074_房务原型对齐二-配房改协议价+酒店富表单OCR+月度对账-管理后台.md new file mode 100644 index 0000000..08197b6 --- /dev/null +++ b/changelogs-v2/2026-06/20_4072_4073_4074_房务原型对齐二-配房改协议价+酒店富表单OCR+月度对账-管理后台.md @@ -0,0 +1,74 @@ +# 房务原型对齐(二)— 配房改协议价同步 + 酒店富表单/OCR + 月度对账 — 管理后台 + +> 变更类型：✨ 新功能（月度对账/OCR）+ 字段新增（协议价/酒店富字段） +> 端类型：管理后台（房务管家 · 配房/对账 / 资源管理 · 酒店） +> 日期：2026-06-20 +> 服务：hl-order-service-v3 + hl-resource-service +> PR：https://git.1814.love:8443/wx/HL/pulls/4098 （Closes #4072）、https://git.1814.love:8443/wx/HL/pulls/4099 （Closes #4073）、https://git.1814.love:8443/wx/HL/pulls/4100 （Closes #4074） + +--- + +## ⚠️ 关键说明（给前端，3 处） + +### 1. 配房编辑可改协议价（#4072） + +房务配房编辑 **`PUT /v3/admin/order/assignments/{id}`** 新增可选入参 **`protoPrice`（协议价）**。房务改协议价后，后端 afterCommit 自动同步写回 resource 价格日历（协议价单源真相）。 + +- 前端配房编辑表单可加「协议价」输入项（与 sellPrice 售价并列，均可选传）。 +- **定制师改结算价不在此**——那个在「确认订单」环节，另行处理。 + +### 2. 酒店档案富表单字段 + 营业执照 OCR（#4073） + +资源管理 · 酒店新增/编辑（`/admin/hotel/item`）出入参新增一批字段，配合原型 4-5 步引导表单： + +| 分组 | 字段 | 类型 | +|---|---|---| +| 营业执照资质 | licenseUnitName 单位名称 / socialCreditCode 信用代码 / legalPerson 法人 / registeredCapital 注册资本(字符串含单位) / registeredAddress 注册地址 / establishDate 成立日期 / businessTermEnd 营业期限到期日 / businessTermLongValid 长期有效 / businessScope 经营范围 / qualificationRemindDays 资质到期提前提醒天数(默认30) / qualificationRemindChannels 提醒渠道(逗号串) / licenseMaterialId 营业执照图片 | 扁平列 | +| 接待政策 | receptionPolicies | **JSON 数组** | +| 设施富子字段 | facilityDetails | **JSON 数组**（现有 facilities 逗号串保留） | + +JSON 结构示例： + +```json +"receptionPolicies": [ + {"policyType":"pet","value":"need_confirm","deposit":200.00,"remark":"仅限小型犬"}, + {"policyType":"extra_bed","value":"allowed","fee":100.00} +], +"facilityDetails": [ + {"facilityType":"breakfast","openTime":"07:00","closeTime":"10:00","fee":68.00,"breakfastType":"自助餐"}, + {"facilityType":"parking","parkingSpaces":50,"free":false,"fee":15.00} +] +``` + +**营业执照 OCR**：**`POST /admin/hotel/ocr/business-license`**（multipart 上传营业执照图片 → 识别返回单位名称/信用代码/法人/注册资本/注册地址/成立日期/营业期限/经营范围，供前端回填）。 + +> ⚠️ OCR 依赖测试服 Nacos 配 `aliyun.ocr.enabled=true` + AK/SK 才真生效（与车务/出行人 OCR 同源），未配返「服务未就绪」310416；字段录入不受影响。 + +### 3. 房务月度对账 + Excel 导出（#4074） + +新增 **`GET /v3/admin/house/reconciliation/monthly?month=YYYY-MM`**（现结酒店账单按 酒店×月 聚合 + 概览）+ **`GET .../monthly/export?month=YYYY-MM`**（Excel 下载）。 + +| 字段 | 说明 | +|---|---| +| overview | 概览：hotelCount/orderCount/roomNights/totalAmount 现结合计/paidAmount 已付/unpaidAmount 待付 | +| hotels[] | 每酒店：hotelId/hotelName/orderCount 订单数/roomNights 间夜/totalAmount 应付/avgPrice 均价/paidAmount 已付/unpaidAmount 待付 | + +- 仅统计**现结**（settlement paymentMethod=CASH_PAID）；待付/已付按订单 settlement_status 判。 +- 预付余额核销因「预付款先不做」暂缓。空月返空列表 + 全 0 概览。 + +```bash +curl -k "https://api.test.1814.love:9443/v3/admin/house/reconciliation/monthly?month=2026-05" -H "Authorization: Bearer " +``` + +--- + +## 测试（测试服 9443 实测） + +- **#4072**：配房编辑端点已部署（dummy id 返 808120），protoPrice 入参被接受;协议价写回 resource 内部链路单测覆盖（HouseAssignmentServiceTest 37 绿）。 +- **#4073**：酒店详情 9 个新字段全返出（Flyway V20260620_001 已应用，qualificationRemindDays 默认 30）；OCR 端点已部署（multipart 契约）。 +- **#4074**：GET monthly 返 200 + 正确空月聚合（totalAmount 字符串序列化）；Excel 导出返真 .xlsx（PK 魔数 3898 字节）；month 格式错返 808170。 + +## 备注 + +- 网关无需改（`/v3/admin/**`、`/admin/hotel/**` 路由已覆盖）。 +- via 房务管家 v2.0 原型对齐 batch（预付款先不做）。