web服务接口文档 #1374

A-nony-mous · 2025-08-27T22:31:07Z

A-nony-mous
Aug 27, 2025

zzz-od 功能接口设计文档

版本: v2.0
日期: 2025年8月27日
状态: 详细设计

1. 概述

本文档详细描述ZenlessZoneZero-OneDragon Web化改造中需要实现的具体功能接口，包括每个模块的功能职责、具体接口定义、数据结构和业务流程。

2. 基础设施接口

2.1 系统状态接口

健康检查和版本信息

GET /healthz - 系统健康状态检查
- 返回: {status: "ok", timestamp: "2025-08-27T10:00:00Z"}
- 用途: 监控系统可用性
GET /version - 获取版本信息
- 返回: {version: "v1.0.0", gitRevision: "abc123", buildTime: "2025-08-27T10:00:00Z"}
- 用途: 版本追踪和兼容性检查

3. 仪表盘(首页)功能模块

3.1 版本管理接口

GET /api/v1/home/version

功能: 获取启动器版本和代码版本信息
参数: 无
返回数据:

{
  "launcherVersion": "2.0.0",
  "codeVersion": "1.5.3",
  "lastUpdateTime": "2025-08-27T10:00:00Z"
}

3.2 背景图片管理接口

GET /api/v1/home/banner

功能: 获取当前主页背景配置
参数: 无
返回数据:

{
  "enabled": true,
  "currentImage": "background_001.jpg",
  "imageList": ["background_001.jpg", "background_002.jpg"],
  "lastUpdateTime": "2025-08-27T09:30:00Z"
}

POST /api/v1/home/banner:reload

功能: 触发背景图片刷新(从远程下载)
参数: 无
返回数据: {"success": true, "message": "背景刷新成功"}

3.3 公告管理接口

GET /api/v1/home/notices

功能: 获取公告卡片显示状态
参数: 无
返回数据:

{
  "enabled": true,
  "notices": [
    {
      "id": "notice_001",
      "title": "系统更新通知",
      "content": "系统将于今晚维护",
      "type": "info",
      "showTime": "2025-08-27T08:00:00Z"
    }
  ]
}

POST /api/v1/home/notices

功能: 设置公告卡片开关状态
参数: {"enabled": boolean}
返回数据: {"success": true}

3.4 更新检测接口

GET /api/v1/home/update/code

功能: 检测代码更新状态
参数: 无
返回数据:

{
  "hasUpdate": true,
  "currentVersion": "1.5.3",
  "latestVersion": "1.6.0",
  "updateUrl": "https://example.com/update",
  "changelog": "修复若干bug"
}

GET /api/v1/home/update/model

功能: 检测模型更新状态
参数: 无
返回数据:

{
  "hasUpdate": false,
  "modelsStatus": {
    "flashClassifier": {"current": "1.0.0", "latest": "1.0.0", "needUpdate": false},
    "hollowZeroEvent": {"current": "2.1.0", "latest": "2.2.0", "needUpdate": true}
  }
}

4. 账户管理功能模块

4.1 实例管理接口

GET /api/v1/accounts/instances

功能: 获取所有实例列表和当前激活实例
参数: 无
返回数据:

{
  "instances": [
    {
      "id": 0,
      "name": "主账号",
      "isActive": true,
      "activeInOD": true,
      "lastUsed": "2025-08-27T10:00:00Z"
    },
    {
      "id": 1,
      "name": "小号",
      "isActive": false,
      "activeInOD": false,
      "lastUsed": "2025-08-26T15:30:00Z"
    }
  ],
  "activeInstanceId": 0
}

POST /api/v1/accounts/instances/{id}:activate

功能: 切换激活指定实例
参数: URL中的id
返回数据: {"success": true, "activeInstanceId": 1}

POST /api/v1/accounts/instances

功能: 创建新实例
参数: {"name": "新实例名称", "activate": false}
返回数据: {"success": true, "instanceId": 2}

PUT /api/v1/accounts/instances/{id}

功能: 更新实例信息
参数: {"name": "更新后的名称", "activeInOD": true}
返回数据: {"success": true}

DELETE /api/v1/accounts/instances/{id}

功能: 删除实例(至少保留一个)
参数: URL中的id
返回数据: {"success": true} 或错误信息

4.2 游戏账号配置接口

GET /api/v1/accounts/game-account

功能: 获取游戏账号配置
参数: 无
返回数据:

{
  "platform": "qwe",
  "server": "abc",
  "gamePath": "C:\\Program Files\\ZenlessZoneZero\\Game.exe",
  "account": "user@example.com",
  "password": "encrypted_password",
  "preferredWindowTitle": "def",
  "autoLogin": true
}

PUT /api/v1/accounts/game-account

功能: 更新游戏账号配置
参数: 完整的游戏账号配置对象
返回数据: {"success": true}

4.3 多账户选项接口

GET /api/v1/accounts/options

功能: 获取多账户全局选项
参数: 无
返回数据:

{
  "instanceRun": "sequential",
  "afterDone": "close_game",
  "switchDelay": 30,
  "maxConcurrent": 2
}

PUT /api/v1/accounts/options

功能: 更新多账户全局选项
参数: 多账户选项配置对象
返回数据: {"success": true}

5. 一条龙功能模块

5.1 一条龙运行控制

POST /api/v1/onedragon/run

功能: 启动一条龙任务
参数: {"instanceId": 0} (可选)
返回数据: {"runId": "uuid-string"}

POST /api/v1/onedragon/run/{runId}:cancel

功能: 取消正在运行的一条龙任务
参数: URL中的runId
返回数据: {"success": true}

GET /api/v1/onedragon/run/{runId}/status

功能: 查询一条龙任务状态
参数: URL中的runId
返回数据:

{
  "runId": "uuid-string",
  "status": "RUNNING",
  "progress": 45,
  "message": "正在执行体力计划 (3/7)",
  "startedAt": "2025-08-27T10:00:00Z",
  "updatedAt": "2025-08-27T10:15:00Z",
  "result": null,
  "error": null,
  "aggregate": {
    "totalTasks": 7,
    "completedTasks": 3,
    "failedTasks": 0,
    "currentTask": "体力计划执行"
  }
}

5.2 预备编组管理

GET /api/v1/onedragon/team

功能: 获取预设队伍配置
参数: 无
返回数据:

{
  "teams": [
    {
      "idx": 0,
      "name": "主力队",
      "members": ["安比", "妮可", "比利"],
      "autoBattle": "通用配置"
    },
    {
      "idx": 1,
      "name": "推图队",
      "members": ["丽娜", "安东", "本"],
      "autoBattle": "推图配置"
    }
  ]
}

PUT /api/v1/onedragon/team

功能: 更新预设队伍配置
参数: teams数组对象
返回数据: {"success": true}

5.3 体力计划管理

GET /api/v1/onedragon/charge-plan

功能: 获取体力计划配置
参数: 无
返回数据:

{
  "planList": [
    {
      "tabName": "asd",
      "categoryName": "ert",
      "missionTypeName": "qwe",
      "missionName": "zxc",
      "level": "asd",
      "autoBattleConfig": "通用配置",
      "runTimes": 3,
      "planTimes": 5,
      "cardNum": 0,
      "predefinedTeamIdx": 0,
      "notoriousHuntBuffNum": 0,
      "planId": "plan_001"
    }
  ],
  "loop": true,
  "skipPlan": false,
  "useCoupon": true,
  "restoreCharge": "体力药剂"
}

POST /api/v1/onedragon/charge-plan

功能: 新增体力计划
参数: 单个计划项对象
返回数据: {"success": true, "planId": "plan_002"}

PUT /api/v1/onedragon/charge-plan/{idx}

功能: 更新指定索引的体力计划
参数: 完整的计划项对象
返回数据: {"success": true}

DELETE /api/v1/onedragon/charge-plan/{idx}

功能: 删除指定索引的体力计划
参数: URL中的idx
返回数据: {"success": true}

POST /api/v1/onedragon/charge-plan:reorder

功能: 重新排序体力计划
参数: {"from": 0, "to": 2, "mode": "move"}
返回数据: {"success": true}

POST /api/v1/onedragon/charge-plan:clear-completed

功能: 清除已完成的计划项
参数: 无
返回数据: {"success": true, "removedCount": 3}

5.4 恶名狩猎配置

GET /api/v1/onedragon/notorious-hunt

功能: 获取恶名狩猎配置
参数: 无
返回数据:

{
  "planList": [
    {
      "tabName": "zxc",
      "categoryName": "asd",
      "missionTypeName": "asd",
      "missionName": "qwe",
      "level": "危险",
      "runTimes": 1,
      "planTimes": 3,
      "predefinedTeamIdx": 1
    }
  ]
}

PUT /api/v1/onedragon/notorious-hunt

功能: 更新恶名狩猎配置
参数: planList数组
返回数据: {"success": true}

5.5 咖啡计划配置(?)

GET /api/v1/onedragon/coffee-plan

功能: 获取咖啡计划配置
参数: 无
返回数据:

{
  "chooseWay": "指定选择",
  "challengeWay": "自动战斗",
  "cardNum": 0,
  "autoBattle": "通用配置",
  "day": {
    "1": "咖啡选项A",
    "2": "咖啡选项B",
    "3": "咖啡选项A",
    "4": "咖啡选项C",
    "5": "咖啡选项B",
    "6": "咖啡选项A",
    "7": "咖啡选项C"
  },
  "predefinedTeamIdx": 0,
  "runChargePlanAfterwards": true
}

PUT /api/v1/onedragon/coffee-plan

功能: 更新咖啡计划配置
参数: 完整的咖啡配置对象
返回数据: {"success": true}

5.6 式舆防卫战配置

GET /api/v1/onedragon/shiyu-defense

功能: 获取式舆防卫战配置
参数: 无
返回数据:

{
  "criticalMaxNodeIdx": 25,
  "teams": [
    {
      "teamIdx": 0,
      "forCritical": true,
      "weaknessList": ["electric", "fire", "physical"]
    },
    {
      "teamIdx": 1,
      "forCritical": false,
      "weaknessList": ["ice", "ether"]
    }
  ]
}

PUT /api/v1/onedragon/shiyu-defense

功能: 更新式舆防卫战配置
参数: 完整的防卫战配置对象
返回数据: {"success": true}

6. 设置管理功能模块

6.1 游戏设置接口

GET /api/v1/settings/game

功能: 获取游戏相关设置
参数: 无
返回数据:

{
  "inputMethod": "keyboard",
  "resolution": "1920x1080",
  "fullscreen": true,
  "monitor": 0,
  "hdr": false,
  "launchArgs": "--windowed",
  "gameLanguage": "zh-cn"
}

PUT /api/v1/settings/game

功能: 更新游戏设置
参数: 游戏设置对象
返回数据: {"success": true}

6.2 键位配置接口

GET /api/v1/settings/keys

功能: 获取键鼠/手柄映射配置
参数: 无
返回数据:

{
  "keyboard": {
    "move_up": "W",
    "move_down": "S",
    "move_left": "A",
    "move_right": "D",
    "attack": "J",
    "dodge": "K",
    "interact": "F"
  },
  "gamepad": {
    "type": "xbox",
    "move": "left_stick",
    "attack": "X",
    "dodge": "B",
    "interact": "A"
  },
  "pressTime": {
    "short": 0.1,
    "medium": 0.3,
    "long": 0.8
  }
}

PUT /api/v1/settings/keys

功能: 更新键位配置
参数: 键位配置对象
返回数据: {"success": true}

6.3 模型配置接口

GET /api/v1/settings/model

功能: 获取当前模型选择和GPU设置
参数: 无
返回数据:

{
  "useGpu": true,
  "models": {
    "flashClassifier": "v1.0.0",
    "hollowZeroEvent": "v2.1.0",
    "lostVoidDet": "v1.5.0"
  },
  "gpuMemoryLimit": 4096
}

PUT /api/v1/settings/model

功能: 更新模型配置
参数: 模型配置对象
返回数据: {"success": true}

6.4 通知设置接口

GET /api/v1/settings/notify

功能: 获取通知推送配置
参数: 无
返回数据:

{
  "globalEnabled": true,
  "appNotifications": {
    "oneDragon": true,
    "autoBattle": true,
    "worldPatrol": false
  },
  "pushMethods": {
    "webhook": {
      "enabled": true,
      "url": "https://hooks.slack.com/xxx",
      "format": "slack"
    },
    "email": {
      "enabled": false,
      "smtp": "smtp.gmail.com",
      "port": 587,
      "username": "user@gmail.com"
    }
  }
}

PUT /api/v1/settings/notify

功能: 更新通知配置
参数: 通知配置对象
返回数据: {"success": true}

7. 资源管理功能模块

7.1 模型资源管理

GET /api/v1/resources/models

功能: 获取可用模型包列表
参数: 无
返回数据:

{
  "models": [
    {
      "name": "flashClassifier",
      "displayName": "闪避分类器",
      "currentVersion": "1.0.0",
      "latestVersion": "1.1.0",
      "needUpdate": true,
      "size": "50MB",
      "description": "用于自动闪避的AI模型"
    },
    {
      "name": "hollowZeroEvent",
      "displayName": "零号空洞事件识别",
      "currentVersion": "2.1.0",
      "latestVersion": "2.1.0",
      "needUpdate": false,
      "size": "120MB",
      "description": "零号空洞事件自动识别模型"
    }
  ],
  "useGpu": true,
  "gpuAvailable": true
}

POST /api/v1/resources/models/{name}:download

功能: 下载指定模型
参数: {"version": "1.1.0", "useGpu": true}
返回数据: {"runId": "uuid-string", "message": "开始下载模型"}

7.2 环境依赖管理

GET /api/v1/resources/env

功能: 获取运行环境依赖状态
参数: 无
返回数据:

{
  "dependencies": [
    {
      "name": "git",
      "required": true,
      "installed": true,
      "version": "2.41.0",
      "status": "ok"
    },
    {
      "name": "python",
      "required": true,
      "installed": true,
      "version": "3.11.5",
      "status": "ok"
    },
    {
      "name": "uv",
      "required": false,
      "installed": false,
      "version": null,
      "status": "missing"
    }
  ]
}

POST /api/v1/resources/env/{name}:install

功能: 安装指定依赖
参数: URL中的name
返回数据: {"runId": "uuid-string", "message": "开始安装依赖"}

8. 战斗助手功能模块

8.1 自动战斗配置

GET /api/v1/battle/auto-battle/configs

功能: 获取自动战斗配置文件列表
参数: 无
返回数据:

{
  "configs": [
    {
      "name": "通用配置",
      "description": "适用于大部分战斗场景",
      "lastModified": "2025-08-27T09:00:00Z"
    },
    {
      "name": "推图配置",
      "description": "专门用于推图的配置",
      "lastModified": "2025-08-26T15:30:00Z"
    }
  ],
  "currentConfig": "通用配置"
}

GET /api/v1/battle/auto-battle/config

功能: 获取当前自动战斗配置
参数: 无
返回数据:

{
  "configName": "通用配置",
  "screenshotInterval": 0.1,
  "useGpu": true,
  "gamepadType": "xbox",
  "debugMode": false,
  "customSettings": {
    "attackInterval": 0.5,
    "dodgeThreshold": 0.8,
    "skillCooldown": 2.0
  }
}

PUT /api/v1/battle/auto-battle/config

功能: 更新自动战斗配置
参数: 完整配置对象
返回数据: {"success": true}

DELETE /api/v1/battle/auto-battle/configs/{name}

功能: 删除配置文件(除sample外)
参数: URL中的name
返回数据: {"success": true} 或错误信息

8.2 自动战斗控制

POST /api/v1/battle/auto-battle/debug

功能: 以调试模式运行一次
参数: {"configName": "通用配置"}
返回数据: {"runId": "uuid-string"}

POST /api/v1/battle/auto-battle/run

功能: 启动正常自动战斗
参数: {"configName": "通用配置", "duration": 300}
返回数据: {"runId": "uuid-string"}

8.3 躲避助手

GET /api/v1/battle/dodge/config

功能: 获取躲避助手配置
参数: 无
返回数据:

{
  "enabled": true,
  "sensitivity": 0.8,
  "reactionTime": 0.1,
  "dodgeKey": "space",
  "visualIndicator": true,
  "audioAlert": false
}

PUT /api/v1/battle/dodge/config

功能: 更新躲避助手配置
参数: 躲避配置对象
返回数据: {"success": true}

POST /api/v1/battle/dodge/run

功能: 启动躲避助手
参数: 无
返回数据: {"runId": "uuid-string"}

8.4 操作调试和模板生成

POST /api/v1/battle/operation-debug/run

功能: 启动操作调试
参数: {"debugType": "input_recording", "duration": 60}
返回数据: {"runId": "uuid-string"}

POST /api/v1/battle/template-generation/run

功能: 生成战斗模板
参数:

{
  "templateName": "新模板",
  "battleType": "boss",
  "difficulty": "hard",
  "recordDuration": 120
}

返回数据: {"runId": "uuid-string", "templatePath": "/templates/new_template.yaml"}

9. 零号空洞和迷失之地功能模块

9.1 零号空洞配置

GET /api/v1/hollow-zero/run-config

功能: 获取零号空洞运行配置
参数: 无
返回数据:

{
  "selectedChallenge": "挑战配置1",
  "targetLevel": "危险",
  "autoTeamSelection": true,
  "maxAttempts": 3,
  "restoreOnFail": true
}

PUT /api/v1/hollow-zero/run-config

功能: 更新运行配置
参数: 运行配置对象
返回数据: {"success": true}

GET /api/v1/hollow-zero/challenge/configs

功能: 获取挑战配置列表
参数: 无
返回数据:

{
  "configs": [
    {
      "name": "挑战配置1",
      "description": "平衡型配置",
      "difficulty": "normal",
      "lastModified": "2025-08-27T09:00:00Z"
    },
    {
      "name": "速刷配置",
      "description": "快速通关配置",
      "difficulty": "easy",
      "lastModified": "2025-08-26T14:20:00Z"
    }
  ]
}

POST /api/v1/hollow-zero/challenge/configs

功能: 创建新挑战配置
参数: {"name": "新配置", "baseConfig": "挑战配置1"}
返回数据: {"success": true, "configName": "新配置"}

9.2 迷失之地配置

GET /api/v1/lost-void/run-config

功能: 获取迷失之地运行配置
参数: 无
返回数据:

{
  "taskList": [
    {
      "name": "每日任务1",
      "enabled": true,
      "priority": 1
    },
    {
      "name": "每日任务2", 
      "enabled": false,
      "priority": 2
    }
  ],
  "autoSelectReward": true,
  "maxChallengeTime": 1800
}

PUT /api/v1/lost-void/run-config

功能: 更新运行配置
参数: 运行配置对象
返回数据: {"success": true}

9.3 运行控制

POST /api/v1/hollow-zero/run

功能: 启动零号空洞
参数: {"configName": "挑战配置1"}
返回数据: {"runId": "uuid-string"}

POST /api/v1/lost-void/run

功能: 启动迷失之地
参数: {"taskList": ["每日任务1", "每日任务2"]}
返回数据: {"runId": "uuid-string"}

10. 游戏助手功能模块

10.1 委托助手

GET /api/v1/assistant/commission/config

功能: 获取委托助手配置
参数: 无
返回数据:

{
  "dialogClickInterval": 0.5,
  "dialogOptions": "智能选择",
  "storyMode": "跳过",
  "autoDodge": true,
  "autoBattle": true,
  "maxCommissionTime": 600
}

PUT /api/v1/assistant/commission/config

功能: 更新委托助手配置
参数: 配置对象
返回数据: {"success": true}

POST /api/v1/assistant/commission/run

功能: 启动委托助手
参数: 无
返回数据: {"runId": "uuid-string"}

10.2 网络生存

GET /api/v1/assistant/life-online/run-config

功能: 获取网络生存运行配置
参数: 无
返回数据:

{
  "mode": "auto",
  "difficulty": "normal", 
  "targetScore": 10000,
  "maxDuration": 1200
}

POST /api/v1/assistant/life-online/run

功能: 启动网络生存
参数: 运行配置对象
返回数据: {"runId": "uuid-string"}

10.3 系统检测

GET /api/v1/assistant/mouse-sensitivity/check

功能: 获取鼠标灵敏度检查结果
参数: 无
返回数据:

{
  "lastCheckTime": "2025-08-27T09:00:00Z",
  "sensitivity": 0.5,
  "status": "optimal",
  "recommendations": []
}

POST /api/v1/assistant/mouse-sensitivity/run

功能: 启动鼠标灵敏度检查
参数: 无
返回数据: {"runId": "uuid-string"}

POST /api/v1/assistant/predefined-team/run

功能: 启动预设队伍检查
参数: 无
返回数据: {"runId": "uuid-string"}

11. 世界巡回(锄大地)功能模块(TBD)

11.1 路线管理

GET /api/v1/world-patrol/routes

功能: 获取路线列表
参数: area, entry, q, page, pageSize
返回数据:

{
  "routes": [
    {
      "id": "route_001",
      "name": "qwe",
      "area": "qwe",
      "entry": "qwe",
      "description": "qwe",
      "estimatedTime": 180,
      "difficulty": "easy",
      "lastModified": "2025-08-27T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "totalPages": 1
  }
}

POST /api/v1/world-patrol/routes

功能: 创建新路线
参数: 路线配置对象
返回数据: {"success": true, "routeId": "route_002"}

GET /api/v1/world-patrol/routes/{id}

功能: 获取指定路线详情
参数: URL中的id
返回数据: 完整的路线配置对象

PUT /api/v1/world-patrol/routes/{id}

功能: 更新路线配置
参数: 路线配置对象
返回数据: {"success": true}

DELETE /api/v1/world-patrol/routes/{id}

功能: 删除路线
参数: URL中的id
返回数据: {"success": true}

11.2 大地图管理

GET /api/v1/world-patrol/large-maps/{areaFullId}

功能: 获取大地图元数据
参数: URL中的areaFullId
返回数据:

{
  "areaId": "area_001",
  "icons": [
    {
      "id": "icon_001",
      "type": "treasure",
      "position": {"x": 100, "y": 200},
      "status": "collected"
    }
  ],
  "pathNetwork": {
    "nodes": [],
    "edges": []
  }
}

POST /api/v1/world-patrol/large-maps/{areaFullId}

功能: 保存大地图数据
参数: 大地图数据对象
返回数据: {"success": true}

11.3 运行控制

POST /api/v1/world-patrol/run

功能: 启动世界巡回
参数: {"routeId": "route_001"} (可选)
返回数据: {"runId": "uuid-string"}

POST /api/v1/world-patrol/run-record:reset

功能: 清空运行记录
参数: 无
返回数据: {"success": true, "resetCount": 150}

12. 开发工具功能模块

12.1 截图助手

GET /api/v1/devtools/screenshot-helper/config

功能: 获取截图助手配置
参数: 无
返回数据:

{
  "outputPath": "./screenshots",
  "format": "PNG",
  "quality": 95,
  "hotkey": "F12",
  "autoSave": true
}

POST /api/v1/devtools/screenshot-helper/run

功能: 启动截图助手
参数: 无
返回数据: {"runId": "uuid-string"}

12.2 大地图工具

POST /api/v1/devtools/large-map/overlap

功能: 大地图重叠计算
参数: 两张图片的二进制数据
返回数据:

{
  "success": true,
  "alignmentParams": {
    "offsetX": 120,
    "offsetY": -50,
    "confidence": 0.95
  }
}

POST /api/v1/devtools/large-map/merge

功能: 大地图合并
参数: 合并参数和图片数据
返回数据: {"success": true, "outputPath": "./merged_map.png"}

12.3 图标编辑器

GET /api/v1/devtools/icon-editor/{areaFullId}

功能: 获取区域图标清单
参数: URL中的areaFullId
返回数据:

{
  "icons": [
    {
      "id": "icon_001",
      "name": "宝箱",
      "tpCoords": {"x": 50, "y": 100},
      "lmCoords": {"x": 500, "y": 1000},
      "type": "treasure"
    }
  ]
}

PUT /api/v1/devtools/icon-editor/{areaFullId}

功能: 保存图标配置
参数: 图标清单对象
返回数据: {"success": true}

13. 通用任务管理接口

13.1 任务状态查询

GET /api/v1/runs/{runId}

功能: 获取任务状态(通用)
参数: URL中的runId
返回数据:

{
  "runId": "uuid-string",
  "type": "onedragon",
  "status": "RUNNING",
  "progress": 65,
  "message": "正在执行咖啡计划",
  "startedAt": "2025-08-27T10:00:00Z",
  "updatedAt": "2025-08-27T10:30:00Z",
  "result": null,
  "error": null
}

GET /api/v1/runs

功能: 获取所有任务状态列表
参数: status, type, limit
返回数据: 任务状态数组

13.2 任务控制

POST /api/v1/runs/{runId}:cancel

功能: 取消任务(通用)
参数: URL中的runId
返回数据: {"success": true, "message": "任务已取消"}

14. WebSocket事件推送

14.1 连接端点

WS /ws/v1/runs/{runId}

功能: 订阅指定任务的实时事件
事件类型:

started: 任务开始
progress: 进度更新
log: 日志消息
completed: 任务完成
failed: 任务失败
cancelled: 任务取消

WS /ws/v1/logs

功能: 订阅全局日志流
事件格式:

{
  "type": "log",
  "data": {
    "level": "INFO",
    "message": "开始执行体力计划",
    "timestamp": "2025-08-27T10:30:00Z",
    "module": "onedragon",
    "runId": "uuid-string"
  }
}

15. 错误处理规范

15.1 错误码定义

VALIDATION_ERROR: 请求参数验证失败
RUN_NOT_FOUND: 任务不存在
RUN_ALREADY_RUNNING: 任务已在运行
CONFIG_INVALID: 配置参数无效
FILE_NOT_FOUND: 文件不存在
PERMISSION_DENIED: 权限不足
INTERNAL_ERROR: 内部服务器错误

15.2 标准错误格式

{
  "error": {
    "code": "CONFIG_INVALID",
    "message": "队伍配置参数无效",
    "details": {
      "field": "members",
      "reason": "成员数量不能超过3个"
    }
  }
}

16. 接口实现优先级

P0 (核心功能，必须实现)

基础设施: healthz, version
一条龙: 运行控制, 队伍管理, 体力计划
账户管理: 实例切换, 游戏账号配置
任务管理: 状态查询, 取消控制
WebSocket: 任务事件推送

P1 (主要功能，优先实现)

设置管理: 游戏设置, 键位配置
资源管理: 模型下载, 环境检查
战斗助手: 自动战斗, 躲避助手
仪表盘: 版本检查, 背景管理

P2 (扩展功能，后期实现)

零号空洞/迷失之地
游戏助手功能
世界巡回
开发工具

这份文档详细描述了所有需要实现的接口功能，为开发团队提供了完整的实现指南。

3. 核心模块设计

3.1 任务执行架构

graph TB
    A[客户端请求] --> B[API网关]
    B --> C[任务管理服务]
    C --> D[任务注册表]
    D --> E{任务类型}
    E -->|一条龙| F[OneDragon任务]
    E -->|自动战斗| G[AutoBattle任务]
    E -->|世界巡回| H[WorldPatrol任务]
    
    F --> I[业务逻辑执行]
    G --> I
    H --> I
    
    I --> J[状态更新]
    J --> K[事件发布]
    K --> L[WebSocket推送]
    L --> M[客户端更新]
    
    C --> N[返回任务ID]
    N --> A

3.2 配置管理架构

graph LR
    A[客户端配置请求] --> B[配置管理服务]
    B --> C{操作类型}
    C -->|读取| D[配置读取器]
    C -->|写入| E[配置写入器]
    C -->|验证| F[配置验证器]
    
    D --> G[配置文件系统]
    E --> G
    F --> G
    
    G --> H[配置缓存]
    H --> I[配置同步器]
    I --> J[多实例同步]
    
    D --> K[返回配置数据]
    E --> L[返回操作结果]
    F --> M[返回验证结果]

3.3 实时通信架构

graph TB
    A[多个客户端] --> B[WebSocket网关]
    B --> C[连接管理器]
    C --> D[连接池]
    
    E[业务事件源] --> F[事件聚合器]
    F --> G[消息路由器]
    G --> H{消息类型}
    H -->|任务状态| I[任务订阅者]
    H -->|日志消息| J[日志订阅者]
    H -->|系统事件| K[系统订阅者]
    
    I --> L[推送到对应客户端]
    J --> L
    K --> L
    L --> B
    B --> A

4. 数据流设计

4.1 用户操作流程

4.1.1 任务启动流程

sequenceDiagram
    participant C as 客户端
    participant A as API网关
    participant T as 任务管理服务
    participant B as 业务逻辑
    participant W as WebSocket服务
    
    C->>A: POST /api/v1/onedragon/run
    A->>T: 创建任务请求
    T->>T: 生成任务ID
    T->>B: 异步启动任务
    T->>A: 返回任务ID
    A->>C: 返回 {runId}
    
    Note over B: 任务执行中
    B->>W: 发布状态事件
    W->>C: WebSocket推送状态更新
    
    B->>W: 发布日志事件
    W->>C: WebSocket推送日志消息
    
    B->>T: 任务完成
    T->>W: 发布完成事件
    W->>C: WebSocket推送完成通知

4.1.2 配置更新流程

sequenceDiagram
    participant C as 客户端
    participant A as API网关
    participant S as 配置管理服务
    participant F as 文件系统
    participant V as 配置验证器
    
    C->>A: PUT /api/v1/onedragon/team
    A->>S: 配置更新请求
    S->>V: 验证配置数据
    V->>S: 验证结果
    
    alt 验证成功
        S->>F: 写入配置文件
        F->>S: 写入成功
        S->>A: 返回成功
        A->>C: 200 OK
    else 验证失败
        S->>A: 返回验证错误
        A->>C: 400 Bad Request
    end

4.2 系统初始化流程

sequenceDiagram
    participant S as 系统启动
    participant A as API应用
    participant C as 上下文管理器
    participant D as 依赖管理器
    participant W as WebSocket管理器
    participant L as 日志服务
    
    S->>A: 应用启动
    A->>C: 初始化上下文
    C->>D: 加载依赖配置
    D->>C: 依赖就绪
    C->>A: 上下文就绪
    
    A->>W: 启动WebSocket服务
    W->>A: WebSocket就绪
    
    A->>L: 启动日志服务
    L->>A: 日志服务就绪
    
    A->>S: 系统就绪
    
    Note over S: 系统运行中
    
    S->>A: 系统关闭信号
    A->>W: 关闭WebSocket连接
    A->>L: 停止日志服务
    A->>C: 清理上下文
    C->>A: 清理完成
    A->>S: 系统关闭

5. 接口设计原则

5.1 RESTful API设计

资源组织

层次化URL: /api/v1/{module}/{resource}/{action}
HTTP方法语义: GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)
状态码规范: 2xx(成功)、4xx(客户端错误)、5xx(服务器错误)

响应格式标准化

成功响应: 直接返回数据或操作结果
错误响应: { error: { code, message, details? } }
分页响应: { data: [], pagination: { page, pageSize, total } }

5.2 WebSocket事件设计

事件格式标准

{
    "type": "事件类型",
    "data": "事件数据",
    "timestamp": "时间戳",
    "runId": "任务ID（可选）"
}

事件类型分类

任务事件: started、progress、completed、failed、cancelled
日志事件: log、error、warning、info
系统事件: connected、disconnected、heartbeat

6. 错误处理和异常管理

6.1 错误分类体系

业务错误 (Business Errors)

配置错误: 配置参数无效、配置文件损坏
任务错误: 任务执行失败、资源不足
权限错误: 实例未激活、功能未授权

系统错误 (System Errors)

网络错误: 连接超时、请求失败
资源错误: 文件不存在、磁盘空间不足
运行时错误: 内存不足、异常崩溃

6.2 异常处理流程

graph TD
    A[异常发生] --> B{异常类型}
    B -->|业务异常| C[业务异常处理器]
    B -->|系统异常| D[系统异常处理器]
    B -->|未知异常| E[通用异常处理器]
    
    C --> F[记录业务日志]
    D --> G[记录系统日志]
    E --> H[记录错误日志]
    
    F --> I[生成错误响应]
    G --> I
    H --> I
    
    I --> J[返回统一错误格式]
    J --> K[客户端错误处理]

Navigation Menu

Repository navigation

web服务接口文档 #1374

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

web服务 接口文档 #1374

Uh oh!

A-nony-mous Aug 27, 2025

zzz-od 功能接口设计文档

1. 概述

2. 基础设施接口

2.1 系统状态接口

健康检查和版本信息

3. 仪表盘(首页)功能模块

3.1 版本管理接口

GET /api/v1/home/version

3.2 背景图片管理接口

GET /api/v1/home/banner

POST /api/v1/home/banner:reload

3.3 公告管理接口

GET /api/v1/home/notices

POST /api/v1/home/notices

3.4 更新检测接口

GET /api/v1/home/update/code

GET /api/v1/home/update/model

4. 账户管理功能模块

4.1 实例管理接口

GET /api/v1/accounts/instances

POST /api/v1/accounts/instances/{id}:activate

POST /api/v1/accounts/instances

PUT /api/v1/accounts/instances/{id}

DELETE /api/v1/accounts/instances/{id}

4.2 游戏账号配置接口

GET /api/v1/accounts/game-account

PUT /api/v1/accounts/game-account

4.3 多账户选项接口

GET /api/v1/accounts/options

PUT /api/v1/accounts/options

5. 一条龙功能模块

5.1 一条龙运行控制

POST /api/v1/onedragon/run

POST /api/v1/onedragon/run/{runId}:cancel

GET /api/v1/onedragon/run/{runId}/status

5.2 预备编组管理

GET /api/v1/onedragon/team

PUT /api/v1/onedragon/team

5.3 体力计划管理

GET /api/v1/onedragon/charge-plan

POST /api/v1/onedragon/charge-plan

PUT /api/v1/onedragon/charge-plan/{idx}

DELETE /api/v1/onedragon/charge-plan/{idx}

POST /api/v1/onedragon/charge-plan:reorder

POST /api/v1/onedragon/charge-plan:clear-completed

5.4 恶名狩猎配置

GET /api/v1/onedragon/notorious-hunt

PUT /api/v1/onedragon/notorious-hunt

5.5 咖啡计划配置(?)

GET /api/v1/onedragon/coffee-plan

PUT /api/v1/onedragon/coffee-plan

5.6 式舆防卫战配置

GET /api/v1/onedragon/shiyu-defense

PUT /api/v1/onedragon/shiyu-defense

6. 设置管理功能模块

6.1 游戏设置接口

GET /api/v1/settings/game

PUT /api/v1/settings/game

6.2 键位配置接口

GET /api/v1/settings/keys

PUT /api/v1/settings/keys

6.3 模型配置接口

GET /api/v1/settings/model

PUT /api/v1/settings/model

6.4 通知设置接口

GET /api/v1/settings/notify

PUT /api/v1/settings/notify

7. 资源管理功能模块

7.1 模型资源管理

GET /api/v1/resources/models

POST /api/v1/resources/models/{name}:download

7.2 环境依赖管理

GET /api/v1/resources/env

POST /api/v1/resources/env/{name}:install

8. 战斗助手功能模块

8.1 自动战斗配置

GET /api/v1/battle/auto-battle/configs

web服务接口文档 #1374

A-nony-mous
Aug 27, 2025