UR#45 换货资产快照与新旧资产独立搜索功能总结

本次交付范围

本次完成两张可独立发布的 Ticket：

Ticket 01：统一物流换货创建、直接换货创建和物流发货三个写入入口的资产解析与权威快照。
Ticket 02：将 GET /api/admin/exchanges 列表读取收口到独立 Query，提供新旧资产独立搜索、完整校验、权限、分页、错误转换、OpenAPI 和真实 PostgreSQL 验证。

未迁移换货详情、状态机、完成、取消、资料迁移、旧资产转新等旧用例；未回填历史快照；未实现 UR#86 资产前后代关系或 UR#98 店铺继承。

权威快照规则

IoT 卡可通过 ICCID、接入号或虚拟号定位，但新写入的 old_asset_identifier 和 new_asset_identifier 始终保存数据库中的完整 ICCID。
设备可通过虚拟号、IMEI 或 SN 定位，快照按“虚拟号 → IMEI → SN”选择首个非空稳定标识。
物流创建的旧资产、直接换货的新旧资产、物流发货的新资产共享同一规范化能力。
标识解析继续应用既有店铺数据范围、资产类型、状态和并发校验。不存在、类型不匹配或数据库故障使用统一错误体系，不返回底层错误。
历史换货单保持原快照，不做自动清洗或回填；列表搜索按资产类型和资产主键命中，因此仍可通过资产当前支持的任一标识找到历史记录。

列表搜索契约

GET /api/admin/exchanges 使用以下可选参数：

old_asset_keyword：最长 100 字符，只过滤旧资产一侧。
new_asset_keyword：最长 100 字符，只过滤新资产一侧。
两者同时提交时按 AND 组合，并继续与 status、flow_type、created_at_start、created_at_end 和分页条件按 AND 组合。
空值不增加对应过滤；无候选或无换货单命中时返回成功空分页。
卡候选对 ICCID、接入号和虚拟号做包含匹配；设备候选对虚拟号、IMEI 和 SN 做包含匹配；GORM 默认排除软删除资产和换货单。
旧通用 identifier 已从新 DTO 与 OpenAPI 契约移除。

列表采用 Handler → Query → GORM/DTO 通道。候选资产通过数据库子查询参与最终换货单条件，不逐条读取资产；total 和 items 复用同一过滤链，按 created_at DESC 排序。最终换货单查询继续应用既有店铺范围，候选解析不会扩大平台、超级管理员或代理的可见数据。

校验与错误边界

Handler 对完整请求 DTO 执行校验。显式 page=0、page_size=0、超上限分页、非法状态、非法流程类型、超长关键词和非法时间格式统一返回 HTTP 400：

{
  "code": 1001,
  "msg": "参数验证失败",
  "data": null,
  "timestamp": "RFC3339 时间"
}

候选或换货单查询失败返回脱敏 HTTP 500、code=2002、msg=数据库错误，不得将故障降级为空结果，也不向客户端暴露 SQL、候选数量或底层错误。

验证证据

真实 PostgreSQL 写用例测试覆盖卡 ICCID、接入号、虚拟号和设备虚拟号、IMEI、SN 输入，并验证物流创建、直接创建和物流发货的持久化快照。
设备无虚拟号时的 IMEI、SN 回退规则由规范化单元测试覆盖；历史非规范快照保持原值。
Query 集成测试覆盖六类标识、新旧独立、双关键词 AND、状态和时间组合、空结果、历史快照、软删除资产、店铺范围、分页排序与数据库故障。
代表性数据集在真实 PostgreSQL 中创建 120 条匹配换货单；连续执行 100 次第 2 页、每页 20 条查询，总数与排序保持一致，每次固定执行 2 条 SQL（计数 + 分页），并断言 P95 <200ms、P99 <500ms；测试同时执行 EXPLAIN 记录等价查询计划，证明没有逐行资产反查。
HTTP 测试验证完整 DTO 校验、独立关键词传递、统一分页外层和脱敏数据库错误。
OpenAPI 使用 go run ./cmd/gendocs 重新生成并核验新旧关键词、长度限制、AND 说明、权威快照响应语义以及旧 identifier 不再属于列表参数。

前端人工验收清单

将原单一资产输入框拆为“旧资产”和“新资产”两个输入框。
空值不提交；两个非空值同时提交并按 AND 展示结果。
表格分别展示旧资产类型/标识和新资产类型/标识，不混列。
前端不解析接入号、虚拟号或 ICCID，不在当前页本地过滤。
清空、分页、加载、空态和失败反馈沿用现有交互；失败时不得把旧结果伪装为新查询结果。

当前仓库没有可实施该页面的前端工程，因此前端部分以接口契约和本清单交付，等待同维护窗口的前端仓库实施与浏览器人工验收。

发布与回滚

发布时后端与前端在同一维护窗口切换：前端停止提交列表 identifier，改为提交 old_asset_keyword / new_asset_keyword。
本次无数据库迁移，不修改历史数据；后端回滚只需回退应用与 OpenAPI 产物。
若仅回滚前端，旧 identifier 不会产生筛选效果，因此不支持前后端跨版本长期混用；应整体回滚到上一版本。
发布后重点观察列表 HTTP 5xx、查询耗时和空结果比例；异常时按应用版本整体回滚，不执行数据修复。

5.3 KiB Raw Blame History Unescape Escape