49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# 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 描述正确
|