Neo-ZQYY/docs/audit/changes/2026-02-13__api-reference-overhaul.md

2026-02-13 API 参考文档全面重构

日期

2026-02-13 (Asia/Shanghai)

原始原因

用户 Prompt（跨多轮对话）：

P20260213-170000: "继续"（续接 Task 3 — API 文档全面重构） P20260213-171500: "继续"（完成文档生成、索引、清理、审计）

原始需求来自更早的 Prompt（上下文传递）：对所有 23+ API 文档进行全面重构，标准化 API 请求/参数存储，为每个 API 生成独立 .md 文档，重命名/迁移目录，废弃旧 test-json-doc 目录。

直接原因

旧 docs/test-json-doc/ 目录命名不规范，文档格式不统一，缺少标准化的 API 参数注册表。需要创建结构化的 docs/api-reference/ 目录体系。

修改文件清单

新增文件

• docs/api-reference/README.md — 索引文档
• docs/api-reference/api_registry.json — 25 个 API 的标准化定义
• docs/api-reference/_api_call_results.json — API 调用结果（字段提取）
• docs/api-reference/endpoints/*.md — 25 个端点文档
• docs/api-reference/samples/*.json — 24 个响应样本

修改文件

• .kiro/steering/structure.md — 添加 api-reference 目录描述，标记 test-json-doc 为废弃

临时文件（已创建并删除）

• scripts/gen_api_docs.py — 一次性 API 调用脚本 v1（已删除）
• scripts/gen_api_docs_v2.py — 一次性 API 调用脚本 v2（已删除）
• scripts/gen_api_md_docs.py — 一次性 Markdown 生成脚本（已删除）

变更性质判定

无逻辑改动。 全部为纯文档生成和目录结构描述调整，不涉及：

• 业务规则/计算口径
• 数据处理/ETL 逻辑
• API 行为（未修改 api/、tasks/、loaders/ 等运行时代码）
• 数据库 schema/表结构
• 鉴权/权限

Risk/Verify

• 风险：极低，纯文档变更
• 回归范围：无（不影响任何运行时代码）
• 验证步骤：
  1. 确认 docs/api-reference/endpoints/ 下有 25 个 .md 文件
  2. 确认 docs/api-reference/api_registry.json 包含 25 个 API 定义
  3. 确认 docs/api-reference/samples/ 下有 24 个 .json 文件（settlement_ticket_details 跳过）
  4. 确认 .kiro/steering/structure.md 中 api-reference 和 test-json-doc 描述正确