# FIT 新建 TA 条件写入：代码与测试交付

> 2026-09-18 后续更新：用户已授权更新本机服务，原8082及配套模拟接口现已加载并验证。交付的本机包附加类已修正为Java17，当前SHA256见release/manifest.json；普通平台包未安装。7封邮件的前置预订数据仍未装入。详见[本机更新证据](../../../.project-docs/50-evidence/topics/2026-09-18-local-service-update.md)。

以下为首次代码交付记录，运行状态以页首后续更新为准。2026-09-18。消费端代码已接入现有 `postReservation` / `getReservation`，无需平台新增封装；本轮未更新运行服务或操作平台沙箱。**写入映射依据官方API结构与数据字典组合推导，TA特殊类型是否落入沙箱页面的输入框尚待用户确认，不能把模拟回显当作页面验收。**

## 当前行为

| 情况 | 请求和完成判断 |
| --- | --- |
| GROUP NEW | 不发送TA，继续保留Block Name等原字段 |
| FIT NEW有Tour Code | 创建请求发送确认的Tour Code；逐笔回查唯一TA类型且值一致，才授予TA核验通过 |
| FIT NEW无Tour Code | 省略TA字段；不会因缺Tour而阻止新建，不生成TA核验项 |
| UPDATE | 不修改原预订TA；同类型新增房型仍沿用此前不传TA的范围 |
| GROUP→FIT | 实际按FIT NEW创建，使用最终Tour Code规则 |

缺失、空字符串、null、空白Tour均作为无值处理；非空值不自动改写或截断，超过Reservation说明中的50字符限制提前拒绝。Source Code=TA与TA Record Locator无关，保留原值。酒店附件上传仍取消。

## 请求结构与依据

Edge `POST /api/v1/reservations` 的原生正文内：

```json
{
  "reservations": {
    "reservation": [{
      "externalReferences": [{
        "id": "确认的Tour Code",
        "idContext": "TA_RECORD_LOCATOR"
      }]
    }]
  }
}
```

这里只展示本次增加的字段，其余创建必填内容仍由原转换器构造。无Tour时省略整个externalReferences；不传空数组或空值。不是把 `taRecordLocatorList` 查询参数塞进创建请求，也不改写成Custom Reference。

Oracle [RSV schema](https://github.com/oracle/hospitality-api-docs/blob/dd631fbd5d0fce74a7dbdf96b43f07ce587211f2/rest-api-specs/property/v1/rsv.json)提供创建和详情的externalReferences/id/idContext结构；[官方数据字典第718页](https://docs.oracle.com/en/industries/hospitality/opera-reporting-analytics/ddrna/SA_Definitions.pdf#page=718)把Travel Agent Locator对应为EXTERNAL_REFERENCE_TYPE=TA_RECORD_LOCATOR。两者组合是本次实现依据，官方公开材料仍没有直接的TA专用REST写入样例。平台公开0.11.0目录本轮再次确认两个操作存在。

## 实现与验证

新增窄范围TA转换器，实际创建与调用预览共用映射；回查按idContext查找唯一项，不假定第一项，不用其他类型同值替代。缺失、错误、重复类型阻止完整成功；确认值/酒店读回和调用摘要均能显示TA，其他外部参考号仍不进入调用展示。

修正此前隐藏的Tour必填条件及备注来源不能为空条件：仅允许无Tour的FIT NEW，酒店、任务/卡片/确认版本、来源邮件、正文摘要和调用锁仍严格一致；无Tour不能由此绕过UPDATE/附件归属。冻结创建计划使用null安全比较，新版本检查点拒绝旧计划静默续办。GROUP与既有FIT ID定位不改。

- 完整后端2714项：2697通过、17条件跳过、0失败/错误。
- 页面相关42项及类型检查通过；模拟器70项通过。
- 独立47参数场景（45成功、2预期零写拒绝）和3类取消故障符合预期；20笔创建携带TA专用类型，GROUP/UPDATE请求不携带。
- 无Tour的FIT真实Worker/H2/本地HTTP创建链成功；TA不一致时失败且不重复创建；官方固定版本schema切片校验通过。

全部为合成数据，无XML/EML上传。详细证据见[记录](../../../.project-docs/50-evidence/topics/2026-09-18-fit-new-conditional-ta.md)。

## 当前运行与用户下一步

当前原本机服务已经完成更新，不需要重复替换程序或重启。7封邮件中的修改/取消/转换需要先准备对应旧预订，再由用户上传及确认；本次只完成服务更新，没有导入这些预订。原本机模拟连接保留；使用平台沙箱的普通配置并未由本轮切换。

原交付包说明：更新包位于 `.planning/fit-new-ta-20260918/release/`：平台沙箱配置使用 `th-hotel-server-0.0.1-SNAPSHOT.jar`，原本机模拟装配使用 `th-hotel-local-simulation.jar`。`manifest.json`记录SHA256与尚未完成的页面核验。首次交付时仅生成文件；后续本机更新已完成，见页首。

历史安装参考：沿[原环境更新步骤](ohip-no-ta-local-test-20260918.md#用户接下来操作)使用这个新目录的包；继续使用原本机模拟酒店时，也需由用户更新匹配的模拟服务。不要用旧无TA包验收本次规则，不续办旧版本冻结任务。

服务更新后，以一笔有Tour的FIT新建、一笔无Tour的FIT新建和一笔GROUP新建核对。对有Tour的FIT，需同时查看Stay Details的TA输入框与同笔getReservation结果；若接口返回成功而输入框没有值，本映射不能算完成验收。无需为验证代码额外上传XML。