2026-04-15 21:01:12 +08:00

96 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# API Doc System Workflow
该工作流用于自动抓取 `system` API 文档页面,按 `platform=网页端(web)`、`project=全部(all)` 条件进行校验后,清洗输出模块与接口数据。
## 目录结构
- `config.mjs`: 抓取地址、筛选条件、输出目录、保留天数配置。
- `update.mjs`: 抓取、解析、清洗、落盘、历史清理的一体化脚本。
- `clear-pending.mjs`: 清空 `pending-updates.json` 的辅助脚本。
- `cleanup-marked.mjs`: 清理已标记删除的模块与接口,并重置待更新记录。
- `module/`: 按模块分文件夹存储,每个模块每天一份文件(`YYYYMMDD.json`)。[接口详细配置信息]
- `module-list/`: 每天一份模块总览文件(`YYYYMMDD.json`)。[接口快速一览]
- `interface-details/`: 全量接口明细归档文件(`YYYYMMDD.json`,按日更新)。[归档记录]
- `pending-updates.json`: 待更新文件(模块变化 + 接口变化 + 兼容 legacy 结构)。[待更新接口信息]
- `pending-history/`: 待更新历史快照(`YYYYMMDDHHmmss.json`,保留最近 5 个版本)。[历史快照]
## 运行
```bash
npm run apiconfig
```
如需清空待更新接口文件,可执行:
```bash
npm run apiconfig:clear-pending
```
如需清理“已标记删除”的模块与接口,可执行:
```bash
npm run apiconfig:clean-marked
```
执行前会先检查 `pending-updates.json`:
- 若存在未处理项,脚本会输出:
- `还有未更新接口等待处理!请处理待更新接口再执行此程序。`
- 并终止本次执行,不更新其他产物。
如需改抓取地址,可临时指定:
```bash
API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig
```
## 输出说明
- 模块文件包含当前模块全部接口信息(接口名、描述、Headers、Params、Response 等)。
- `module` 是最新接口信息的主数据源,每次执行 `npm run apiconfig` 都会更新当日模块文件。
- 每个模块快照新增 `changes.fromPreviousSnapshot` 字段,记录本模块相对上一快照的:
- 模块是否新增/重命名
- 接口新增/删除
- 接口 `params` 更新
- 接口 `response` 更新
- 每份模块快照新增 `versionWindow`,用于展示最近 5 个版本窗口(受保留天数控制)。
- 模块总览文件仅保留每个模块的精简接口清单:
- `method`
- `isUsed`
- `isPlaceholder`
- `module-list` 与 `interface-details` 均新增 `changes` 字段,统一汇总模块与接口变化统计:
- `moduleUpdates.added / deleted / updated / split / merged / replaced`
- `interfaceUpdates.added / deleted / paramsUpdated / responseUpdated`
- 接口明细文件包含当前项目所有接口信息,并带状态字段:
- `status.isUsed`: 是否使用(默认 `false`)
- `status.isPlaceholder`: 是否占位(默认 `false`)
- 状态会优先继承 `module` 目录最近快照中的状态,避免每次执行覆盖人工维护状态。
- `module-list`、`interface-details`、`pending-updates` 均包含 `versionWindow` 字段,用于展示最近 5 版本窗口信息。
- 脚本输出增加本地可读时间字段(如 `generatedAtLocal`),终端日志统一显示 `YYYY-MM-DD HH:mm:ss`。
- 页面中的 `platform/project` 是全局请求头配置项,脚本会校验 `web/all` 选项存在,并将其写入每份产物的 `filter` 字段。
- `pending-updates.json` 中:
- `summary`:变化统计汇总
- `moduleUpdates`:模块级变化(含拆分、合并)
- `interfaceUpdates`:接口级变化
- `legacy`:兼容旧结构(按模块聚合 methods)
## 待更新接口判定规则
- 与上一轮有效快照对比后,以下变化会写入 `pending-updates.json`:
- 模块更新:新增模块、删除模块、模块替换、旧模块拆分为多个新模块、多个旧模块合并为新模块
- 接口更新:新增接口、删除接口、`params` 变化、`response` 变化
- 同时会写入 `pending-history/`,用于保留最近 5 个待更新版本。
## 模块文件夹生命周期
- 新模块首次出现时自动创建模块文件夹并生成 `_module.lifecycle.json`。
- 当模块在最新文档中消失时,不删除模块文件夹,而是在该目录新增 `_deleted.YYYYMMDD.json` 删除标记,并将生命周期状态更新为 `deleted`。
- 若后续文档再次出现该模块,会自动恢复为 `active`,保留历史标记用于回退排查。
- 若确认无需保留回退数据,可执行 `npm run apiconfig:clean-marked` 物理删除已标记模块,并清理待删接口。
## 历史保留(最近 5 版本)
- `module/*/YYYYMMDD.json`、`module-list/YYYYMMDD.json`、`interface-details/YYYYMMDD.json` 自动保留最近 5 天快照。
- `pending-history/YYYYMMDDHHmmss.json` 自动保留最近 5 个版本快照。
- 如需调整保留数量,可修改 `config.mjs` 中 `retentionDays`。