# 房务原型对齐(二)— 配房改协议价同步 + 酒店富表单/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 <token>"
```

---

## 测试（测试服 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（预付款先不做）。
