# 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`。