You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
33 lines
3.0 KiB
33 lines
3.0 KiB
2 days ago
|
# 05 · 示例值真值化写回（42 占位 + 退化 → e2e 实测）
|
||
|
|
|
||
|
|
**Type:** task
|
||
|
|
**Status:** resolved
|
||
|
|
**Blocked by:** 02, 04
|
||
|
|
|
||
|
|
## Answer
|
||
|
|
|
||
|
|
**117 文件响应示例全部真值化，全仓「非真实返回」清零**（2026-09-11）。写回 92 文件（87 占位 ∪ 5 退化升级端点）+ 请求示例残留标记处置 23 行 = 全仓收口。
|
||
|
|
|
||
|
|
**做法**：
|
||
|
|
- 真值源 = 5 份 specimens 合并（core/heavy/incr/graph r3 + doc-truth，doc-truth 后写优先），87 唯一端点覆盖 117 文件对账钥匙，**缺 0**（无需补库，仅 quick-create 相似分支需补采）
|
||
|
|
- 每文件删全部「## 响应示例」节（双节形态：错误码前后各一的占位+真值并存 43 文件 / 双占位 13 文件）→ 错误码节后（无则 data 结构节后）插入唯一真值节，标记统一 `// 示例数据（E2E 实测真值），字段结构以上表为准`
|
||
|
|
- **(b) 退化 7 端点全修复**（doc-truth 均有非空真值）：assign 失败行（UNKNOWN/明细不属于该交接单）、图谱 nodes×3+edges×2、quickAdd 失败行（手机号占用）、import/failures×2 失败行、quick-create 补采 `needConfirm=true + similarHits` 6 字段（`harvest_qc_t05.py`，七必填集 + 夹具 e2c-t05qc 已清扫）；batchEdit 行级失败不可达 → 成功信封真值 + 「失败行形态参照 快速添加联系人」注记
|
||
|
|
- 特例：3 个二进制端点（导入模板×2/联系人导出）文字说明（xlsx 流不走 JSON 信封）；assignable 6047 行截 3 条+实测注记；分页 content 截 1 条+`实测 total=N` 注记
|
||
|
|
- 请求示例侧 23 行标记：16 行「E2E 实测值注入」载荷 → `// 请求参数（E2E 实测载荷）`；7 行编造载荷 → `// 请求参数示例`
|
||
|
|
|
||
|
|
**验收（writeback_t05.py / fix2_t05.py 内置 V1–V9）**：「非真实返回」=0 ✅；117/117 唯一响应示例节+真值标记 ✅；错误码节 78 不回退 ✅；对账钥匙 117/117 完好 ✅；BOM=0 ✅；7 退化端点抽查全非空 ✅；二进制/total 注记就位 ✅。
|
||
|
|
|
||
|
|
**产物**：`writeback_t05.py` + `fix2_t05.py` + `harvest_qc_t05.py` + 日志 3 份；`D:\code\crm-api-docs` 工作树变更（不提交，等用户审查）。
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
用票 02 的 `specimens-doc-truth.json` 把 117 端点文档示例全部替换为真实 E2E 实测返回：42 个「非真实返回」占位 + 全部退化示例 → 逐字段真值 JSON，直至「非真实返回」标记全仓清零、每个示例都能让前端直接对照出参结构。
|
||
|
|
|
||
|
|
**纪律**：
|
||
|
|
- 与票 04 的结构写回合并执行顺序（04 先结构、05 后示例，或同一脚本一次写回）——避免同文件双写冲突
|
||
|
|
- 写回工具沿用 a4-doc-fields 的定点补丁模式（只替换响应示例块，不动请求参数/meta/tags/目录）
|
||
|
|
- 信封统一 `code/success/message/data`；写端点 data:null 形态照实保留
|
||
|
|
- 完成后跑 verify 对账：117/117 文件结构完整 + 全仓 grep「非真实返回」= 0
|
||
|
|
|
||
|
|
**产物**：写回脚本 + 对账脚本输出 + `D:\code\crm-api-docs` 工作树变更（不提交，留用户审查——沿用双仓不提交纪律）。
|