WEB/workflows/api-doc-system
2026-05-04 00:34:56 +08:00
..
2026-05-04 00:34:56 +08:00
2026-04-21 18:35:09 +08:00
2026-05-04 00:34:56 +08:00
2026-04-18 20:52:27 +08:00
2026-04-16 20:59:44 +08:00
2026-04-16 20:59:44 +08:00
2026-04-16 20:59:44 +08:00
2026-04-17 21:04:52 +08:00
2026-04-17 21:04:52 +08:00

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/<folder>/module.json: 模块接口明细(覆盖更新)。
    • data/module-list/module-list.json: 模块总览(覆盖更新)。
    • data/interface-details/interface-details.json: 全量接口明细(覆盖更新)。
    • data/pending-updates.json: 待更新文件(模块变化 + 接口变化)。

运行

npm run apiconfig

如需清空待更新接口文件,可执行:

npm run apiconfig:clear-pending

执行前会先检查 pending-updates.json:

  • 若文件内容不是 {}(存在未处理项),脚本会输出:
    • 请先处理待更新接口再更新接口信息!
  • 并终止本次执行,不更新其他产物。

Apidata 抓取脚本

新增 apidata 请求脚本,用于按配置发起接口请求并写入响应结果(支持提取登录 token)。

运行命令:

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):

{
  "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 <token>。

数据文件:workflows/api-doc-system/apidata/data.json

  • 每次执行会先清空该文件,再写入本次抓取结果。
  • 输出结构为数组项:{ 接口, message, data }。
  • 同步更新:workflows/api-doc-agent/config/响应.md(写入本次结果)。

如需改抓取地址,可临时指定:

API_DOC_URL=http://192.168.11.56:6060/api/docs/system npm run apiconfig

Agent 脚本入口:

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/,减少根目录散落文件。
  • 采用覆盖写入模式,避免重复历史文件导致目录混乱与资源浪费。