2026-04-17 21:04:52 +08:00

152 lines
6.1 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)` 条件进行校验后,清洗输出模块与接口数据。
## 目录结构
- `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`: 待更新文件(模块变化 + 接口变化)。
## 运行
```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 <token>`。
数据文件:`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/`,减少根目录散落文件。
- 采用覆盖写入模式,避免重复历史文件导致目录混乱与资源浪费。