# 可空映射与配置拆分验收（v0.18.0-preview）

基于 v0.17.0-preview 补齐通用生成能力，未添加业务模型、权限、金额默认值或领域校验。运行时和依赖不变，旧单文件配置与已有映射函数保留。

## 本轮完成

- 显式嵌套 mapping 支持 `S → T`、`*S → *T`、`S → *T`、显式 nil 策略下的 `*S → T`，也适用于 elements 下的 slice/等长数组。默认保留可空对象；非空目标必须明确选 zero/error。
- 同类型 `*T → T` 可显式选择 nil zero/error，省去重复解引用 converter。自定义 converter 继续独立控制行为，禁止同时配置 nil 策略。
- `pointerResult: true` 额外生成 `<Name>Ptr(S) (*T,error)`，原值函数不变。转换失败返回 nil 与原错误链；辅助函数名统一查重。
- 主配置以 mappingFiles 列出项目内子文件。子文件只含 mappings，统一解析跨文件引用、严格类型和字段覆盖；不做递归导入或隐式覆盖。
- 配置均为项目文件，生成不会改写。check、dry-run、workspace generate/check 共享加载过程；对子文件变化重新核对，保留边界与大小限制。

## 回归证据

[回归记录](nullableMappingRegression.json)：全仓库 44 个有测试的包通过 `-race`，包含实际生成消费者；go vet、go build、diff 检查通过。

`TestNullableMappingConsumer` 生成独立项目，配置跨文件向前引用与项目自定义转换函数，验证：

- nil、缺失、非 nil 零值对象、nil/非 nil 空 slice、nil 元素，以及 slice/array 内的嵌套转换。
- zero/error 空值策略、值到指针、可选指针返回；未显式映射的同类型指针仍共享引用。
- 子转换失败时父结果归零，指针辅助返回 nil，errors.Is 保留原因，错误含子字段与数组索引；内部原因和映射路径不进入公开 HTTP 提示。
- 32 个并发调用；通过实际生成 Handler 和 Logic 测试 JSON 请求与响应；生成模块执行 race 测试和根目录 build。
- 主配置与子文件、业务 Logic 在重新生成后逐字保留；check/preview 只读。子文件修改触发漂移，workspace generate 后 workspace check 通过。
- 未声明 nil 行为、错误类型/策略、辅助函数重名、未知映射、跨文件循环和字段遗漏均在写入前拒绝。

`TestMappingFileConfiguration/Rejection/Bounds` 覆盖文件加载顺序、来源诊断、配置变化摘要、重复文件/定义/JSON key、路径越界、符号链接、嵌套导入拒绝，以及单文件/总大小/文件数/合并映射数限制。

[原始最小复现](nullableMappingRepro.json)：在隔离副本中，用源码构建的真实 CLI 成功生成原来报 `nested mapping Child has incompatible types` 的项目；生成检查、模块编译测试和 build 通过。原项目文件快照一致，临时目录已清理。

[实际进程回归](nullableMappingLocal.json)：原有根目录启动、nethttp/native 信号退出、监听端口释放、上传下载、原始回调、错误响应与生成文件保护通过。

## 使用与边界

使用及迁移见 [生成能力指南](../GENERATION.md)。子文件仅拆分配置，不生成需要人工补齐的赋值代码；普通映射仍为编译器检查的 Go 代码，无运行时反射或 JSON 往返。

zero 表示目标 Go 零值，并跳过子映射；领域必填、金额精度、时间/编号格式和快照深拷贝仍由项目负责。普通指针输入已合并的 missing/null 不能在映射阶段恢复。nil error 是普通转换错误，特定业务错误码用自定义 converter 表达。

本版已完成固定标签的远程发布验收。框架验收不代表完整业务项目已迁移，本轮没有修改 eTax 业务代码。

## 远程发布验收

`v0.18.0-preview` 标签固定在 `4563a6354fac19f22cd8d407fd76d98b8cc9c406`，main 与标签已推送。空模块缓存从远程安装 CLI，所有实际生成消费者固定同版框架且没有本地 replace；校验和为 `h1:VV1T2i+TG5SmXfAO8ii3y0QunNXbKA8x8YR319CWsHg=`。

[远程报告](nullableMappingRemote.json)：53 项检查通过，耗时 51.27 秒。8 组生成消费者通过 race，包括可空映射、配置拆分、显式 nil 策略、指针辅助、错误链、检查/预览只读、workspace 再生成及旧能力回归。配置拆分验收的 generate、check、dry-run 和 workspace 操作均使用远程安装的 CLI。临时目录与服务进程已清理。

复验命令：

```sh
python3 scripts/verifyManagedRelease.py --version v0.18.0-preview --report /tmp/goOmniRemote.json
```

验收报告以独立提交补充，发布标签保持不变。