# API Doc System Workflow 该工作流用于抓取 `system` API 文档页面,按 `platform=网页端(web)`、`project=全部(all)` 条件进行校验后,清洗输出模块与接口数据。 ## 目录结构 - `core/`: 核心实现目录(`config.mjs`、`update.mjs`、`clear-pending.mjs`)。 - `scripts/`: 脚本入口目录(`update.mjs`、`clear-pending.mjs`、`apidata.mjs`)。 - `system/`: 系统模式配置目录(如 `workflow-mode.json`)。 - `config.mjs`: 兼容转发入口(实际定义位于 `core/config.mjs`)。 - `scripts/agent/`: 从 `api-doc-agent` 迁移的 Agent 脚本(`run.mjs`、`api-list-update`、`interface-availability`)。 - `data/`: 数据目录,按功能分类存放产物。 - `data/module//module.json`: 模块接口明细(覆盖更新)。 - `data/module-list/module-list.json`: 模块总览(覆盖更新)。 - `data/interface-details/interface-details.json`: 全量接口明细(覆盖更新)。 - `data/pending-updates.json`: 待更新文件(模块变化 + 接口变化)。 ## 运行 ```bash npm run apiconfig ``` 如需清空待更新接口文件,可执行: ```bash npm run apiconfig:clear-pending ``` 执行前会先检查 `pending-updates.json`: - 若文件内容不是 `{}`(存在未处理项),脚本会输出: - `请先处理待更新接口再更新接口信息!` - 并终止本次执行,不更新其他产物。 ## Apidata 抓取脚本 新增 `apidata` 请求脚本,用于按配置发起接口请求并写入响应结果(支持提取登录 token)。 运行命令: ```bash npm run apiconfig:apidata ``` 配置文件:`workflows/api-doc-system/apidata/config.json` - `config.json` 仅存放待请求接口配置(不存放爬虫地址、版本等信息)。 - `requests`: 请求列表 - `method`: 接口 method(会拼接到 `?method=xxx`) - `body`: 请求 JSON(可省略,默认 `{}`) - `needAuth`: 是否携带登录 token(可省略;除 `user.login` 外默认 `true`) - 脚本内部固定请求地址:`http://192.168.11.56:6060/system?v=1.0`。 - 脚本默认携带请求头:`platform: web`、`project: all`。 示例配置(登录获取 token): ```json { "requests": [ { "method": "user.login", "body": { "username": "yjm", "password": "111111" } }, { "method": "order.list", "body": {} }, { "method": "order.manualOutboundOrder", "body": {} }, { "method": "order.badgeCount", "body": {} } ] } ``` 说明: - 脚本会按 `requests` 顺序串行执行。 - 当某次响应中包含 `data.token`(如 `user.login`)时,后续 `needAuth=true` 的接口会自动携带 `Authorization: Bearer `。 数据文件:`workflows/api-doc-system/apidata/data.json` - 每次执行会先清空该文件,再写入本次抓取结果。 - 输出结构为数组项:`{ 接口, message, data }`。 - 同步更新:`workflows/api-doc-agent/config/响应.md`(写入本次结果)。 如需改抓取地址,可临时指定: ```bash API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig ``` Agent 脚本入口: ```bash npm run apiagent -- --script list ``` ## 输出说明(去历史回档) - 模块文件包含当前模块全部接口信息(接口名、描述、Headers、Params、Response 等)。 - `module` 是最新接口信息的主数据源,每次执行 `npm run apiconfig` 都会覆盖更新 `module.json`。 - 每个模块快照新增 `changes.fromPreviousSnapshot` 字段,记录本模块相对上一快照的: - 模块是否新增/重命名 - 接口新增/删除 - 接口 `params` 更新 - 接口 `response` 更新 - 模块总览文件仅保留每个模块的精简接口清单: - `method` - `module-list/module-list.json` 每次执行覆盖更新,避免每日堆积快照文件。 - `module-list` 与 `interface-details` 均新增 `changes` 字段,统一汇总模块与接口变化统计: - `moduleUpdates.added / deleted / updated` - `interfaceUpdates.added / deleted / paramsUpdated / responseUpdated` - 接口明细文件包含当前项目所有接口信息,并带状态字段: - `status.isUsed`: 是否使用(默认 `false`) - `status.isPlaceholder`: 是否占位(默认 `false`) - 状态会优先继承 `module` 目录最近快照中的状态,避免每次执行覆盖人工维护状态。 - 脚本输出增加本地可读时间字段(如 `generatedAtLocal`),终端日志统一显示 `YYYY-MM-DD HH:mm:ss`。 - 页面中的 `platform/project` 是全局请求头配置项,脚本会校验 `web/all` 选项存在,并将其写入每份产物的 `filter` 字段。 - `pending-updates.json` 中: - 无任何变化时文件会被重置为 `{}`。 - 有变化时写入模块/接口变更清单,复杂迁移统一折叠为“新增 + 删除”。 - `summary`:包含 `moduleAdded`、`moduleDeleted`、`interfaceAdded`、`interfaceDeleted`、`interfaceParamsUpdated`、`interfaceResponseUpdated`、`totalChangedItems` - `interfaceUpdates`:包含 `added`、`deleted`、`paramsUpdated`、`responseUpdated` ## 待更新接口判定规则 - 与上一轮有效快照对比后,以下变化会写入 `pending-updates.json`: - 模块更新:新增模块、删除模块(拆分/合并/替换统一按增删处理) - 接口更新:新增接口、删除接口、`params` 变化、`response` 变化 ## 模块文件夹生命周期 - 新模块首次出现时自动创建模块文件夹并生成 `_module.lifecycle.json`。 - 运行 `npm run apiconfig` 时会先完成与上一轮数据的差异对比并写入 `pending-updates.json`。 - 对比完成后,当前文档中不存在的旧模块文件夹会被直接物理删除(不再保留 `_deleted.YYYYMMDD.json` 软删除标记)。 - 目录内仅保留本轮解析到的最新模块数据,避免历史目录残留影响结构一致性。 ## 结构优化说明 - 入口脚本统一放在 `scripts/`。 - 数据统一放在 `data/`,减少根目录散落文件。 - 采用覆盖写入模式,避免重复历史文件导致目录混乱与资源浪费。