# 前端开发 API 接口文档:Provider 模板与 Node Configuration 本文档为 Coordinate 管理系统的前端接口规范,包含 **服务商模板管理(Provider)** 与 **节点任务配置管理(Node Configuration: booker / sentinel / standalone)** 的所有接口定义、字段说明及 JSON 示例。 --- ## 0. 通用约定 - **Base URL**: `/api` (例如 `http://127.0.0.1:8888/api`) - **请求头**: 除公共登录接口外,所有请求均须携带 Bearer Token: ```http Authorization: Bearer Content-Type: application/json ``` - **统一响应格式**: ```json { "code": 0, "message": "success", "data": {} } ``` - `code === 0` 表示请求成功; - `code !== 0` 表示业务异常,此时 `message` 包含人类可读的错误提示信息。 ### 业务错误码 | code | HTTP 状态 | 说明 | | :--- | :--- | :--- | | `0` | 200 | 成功 | | `40000` | 400 | 参数校验失败 / 掩码占位符拦截 / 删除最后一条未确认 | | `40101` | 401 | 未登录或 Token 无效/已过期 | | `40301` | 403 | 权限不足 (非管理员) | | `40400` | 404 | 目标资源不存在 | | `40900` | 409 | Provider 名称已被占用 | | `40902` | 409 | 标识符冲突 (同节点下 `node_id + identifier` 已存在) | | `42200` | 422 | 请求 Body 结构或数据类型非法 | --- ## 1. Provider 服务商模板接口 ### 1.1 获取服务商目录列表 - **接口路径**: `GET /api/providers` - **Query 参数**: - `enabled_only` (*boolean*, 可选, 默认 `false`): 设为 `true` 时仅返回已启用的服务商(适用于向导新建下拉框)。 **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "success", "data": [ { "id": 1, "name": "vfs", "enabled": 1, "plugin_config": { "lib_path": "plugins", "plugin_name": "vfs_plugin", "plugin_bin": "vfs_plugin.py", "plugin_proto": "IVSPlg" }, "role_templates": { "booker": { "proxy_cd": 300, "session_max_life": 1800, "booker.account_cd": 10800, "booker.target_instances": 1 }, "sentinel": { "sentinel.signal_ttl": 30, "sentinel.query_wait.mode": "Random" } }, "version": 1, "updated_by": "admin", "created_at": "2026-08-23T20:00:00", "updated_at": "2026-08-23T20:00:00" } ] } ``` --- ### 1.2 获取服务商详情 - **接口路径**: `GET /api/providers/{name}` - **Path 参数**: - `name` (*string*, 必填): 服务商唯一标识/名称(如 `vfs`, `tls`, `bls`)。 **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "success", "data": { "id": 1, "name": "vfs", "enabled": 1, "plugin_config": { "lib_path": "plugins", "plugin_name": "vfs_plugin", "plugin_bin": "vfs_plugin.py", "plugin_proto": "IVSPlg" }, "role_templates": { "booker": { "proxy_cd": 300, "session_max_life": 1800, "booker.account_cd": 10800 }, "sentinel": { "sentinel.signal_ttl": 30 } }, "version": 1, "updated_by": "admin", "created_at": "2026-08-23T20:00:00", "updated_at": "2026-08-23T20:00:00" } } ``` --- ### 1.3 新建服务商模板 - **接口路径**: `POST /api/providers` - **Body 参数**: - `name` (*string*, 必填): 服务商唯一标识/名称(如 `vfs`, `tls`, `bls` 等)。 - `enabled` (*boolean*, 可选, 默认 `true`): 是否启用。 - `plugin_config` (*object*, 可选): 默认插件加载配置。 - `role_templates` (*object*, 可选): 角色配置模板(键仅允许 `sentinel` / `booker` / `standalone`,值为点路径平铺字典)。 **请求示例**: ```json { "name": "tls", "enabled": true, "plugin_config": { "lib_path": "plugins", "plugin_name": "tls_plugin", "plugin_bin": "tls_plugin.py", "plugin_proto": "IVSPlg" }, "role_templates": { "standalone": { "login_interval": 1800, "session_max_life": 3600 } } } ``` **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "Provider created successfully", "data": { "id": 2, "name": "tls", "enabled": 1, "plugin_config": { ... }, "role_templates": { ... }, "version": 1, "updated_by": "admin", "created_at": "2026-08-23T20:05:00", "updated_at": "2026-08-23T20:05:00" } } ``` --- ### 1.4 编辑服务商模板 - **接口路径**: `PUT /api/providers/{name}` - **Body 参数**(支持稀疏更新,Body 中不传 `name`): - `enabled` (*boolean*, 可选): 启用状态。 - `plugin_config` (*object*, 可选): 插件配置对象。 - `role_templates` (*object*, 可选): 角色配置模板(覆盖更新)。 **请求示例**: ```json { "enabled": true, "plugin_config": { "lib_path": "plugins", "plugin_name": "tls_plugin_v2", "plugin_bin": "tls_plugin.py", "plugin_proto": "IVSPlg" } } ``` **响应示例 (`code: 0`)**: 返回更新后的 Provider 完整对象。 --- ### 1.5 删除服务商模板 - **接口路径**: `DELETE /api/providers/{name}` **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "Provider deleted successfully", "data": true } ``` --- ## 2. Node Configuration 节点任务配置接口 > **`entry_type` 说明**: 所有端点中的 `{entry_type}` 统一取值为: > - `booker` (Booker 占位/出票角色) > - `sentinel` (Sentinel 监控/扫位角色) > - `standalone` (Standalone 独立一体化抢签任务) --- ### 2.1 分页查询配置列表 - **接口路径**: `GET /api/node-configurations/{entry_type}` - **Query 参数**: - `page` (*integer*, 可选, 默认 `1`): 页码。 - `pageSize` (*integer*, 可选, 默认 `20`): 每页条数(最大 100)。 - `identifier` (*string*, 可选): 任务标识模糊搜索(如 `vfs`)。 - `node_id` (*string*, 可选): 节点唯一标识精确搜索(如 `node01`)。 - `order_id` (*string*, 可选, 仅 `standalone` 有效): 关联订单 ID 精确搜索。 **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "success", "data": { "total": 1, "page": 1, "page_size": 20, "items": [ { "id": 101, "node_id": "node01", "identifier": "vfs.ie.nl", "enable": 0, "debug": 0, "need_account": 1, "need_proxy": 1, "proxy_pool": ["proxy-cheap"], "proxy_cd": 300, "session_max_life": 1800, "active_time_start": "00:00", "active_time_end": "23:59", "website": "https://visa.vfsglobal.com/irl/en/nld/login", "booker": { "account_source": "built-in", "account_pool_id": "ie.nl.booker", "account_cd": 10800, "target_instances": 1 }, "plugin_config": { "lib_path": "plugins", "plugin_name": "vfs_plugin", "plugin_bin": "vfs_plugin.py", "plugin_proto": "IVSPlg" }, "appointment_types": [ { "weight": 10, "routing_key": "slot.dub.nl.tourist", "city": "Dublin", "visa_type": "Tourist", "country": "Netherlands" } ], "free_config": { "mission_code": "nld", "country_code": "irl" }, "version": 1, "updated_by": "admin", "created_at": "2026-08-23T20:10:00", "updated_at": "2026-08-23T20:10:00" } ] } } ``` --- ### 2.2 获取配置详情 - **接口路径**: `GET /api/node-configurations/{entry_type}/{entry_id}` - **Path 参数**: - `entry_type` (*string*, 必填): `booker` | `sentinel` | `standalone` - `entry_id` (*integer*, 必填): 配置条目主键 ID **响应示例 (`code: 0`)**: 返回该配置条目的全字段对象。 --- ### 2.3 新建配置条目 - **接口路径**: `POST /api/node-configurations/{entry_type}` - **重要规则**: **新建条目一律以停用状态落库 (`enable = 0`)**;同一节点下 `(node_id, identifier)` 冲突时返回 `40902`。 #### A. Booker 角色请求 Body 示例: ```json { "node_id": "node01", "identifier": "vfs.ie.nl", "website": "https://visa.vfsglobal.com/irl/en/nld/login", "need_account": 1, "need_proxy": 1, "proxy_pool": ["proxy-cheap"], "proxy_cd": 300, "session_max_life": 1800, "active_time_start": "00:00", "active_time_end": "23:59", "booker": { "account_source": "built-in", "account_pool_id": "ie.nl.booker", "target_instances": 1, "account_cd": 10800, "booking_cooldown": 300, "max_bookings_per_account": 8 }, "plugin_config": { "lib_path": "plugins", "plugin_name": "vfs_plugin", "plugin_bin": "vfs_plugin.py", "plugin_proto": "IVSPlg" }, "appointment_types": [ { "weight": 10, "routing_key": "slot.dub.nl.tourist", "city": "Dublin", "visa_type": "Tourist", "country": "Netherlands" } ], "free_config": { "mission_code": "nld", "country_code": "irl" } } ``` #### B. Sentinel 角色请求 Body 示例: ```json { "node_id": "node01", "identifier": "vfs.ie.nl", "website": "https://visa.vfsglobal.com/irl/en/nld/login", "sentinel": { "account_source": "built-in", "account_pool_id": "ie.nl.sentinel", "target_instances": 1, "signal_ttl": 30, "query_wait": { "mode": "Random", "fixed_wait": 10, "random_min": 60, "random_max": 300 } }, "plugin_config": { ... }, "appointment_types": [ ... ], "free_config": { ... } } ``` #### C. Standalone 角色请求 Body 示例: ```json { "node_id": "node01", "order_id": "ORD-20260823-001", "identifier": "tls.shanghai.fr", "account": { "username": "user@example.com", "password": "Password123" }, "proxy_pool": ["proxy-cheap"], "query_wait": { "mode": "Random", "fixed_wait": 10, "random_min": 55, "random_max": 65 }, "login_interval": 1800, "session_max_life": 3600, "user_preferences": { "support_pta": false, "expected_start_date": "2026-09-01", "expected_end_date": "2026-09-20" }, "plugin_config": { ... }, "appointment_types": [ ... ], "free_config": { ... } } ``` **响应示例 (`code: 0`)**: 返回新生成的配置对象(初始 `enable: 0`, `version: 1`)。 --- ### 2.4 稀疏更新配置 (Sparse Update) - **接口路径**: `PUT /api/node-configurations/{entry_type}/{entry_id}` - **说明**: - `set`:支持顶级字段(如 `proxy_cd`)与多层 JSON 点路径更新(如 `booker.account_cd`、`sentinel.query_wait.random_min`)。 - `clear`:显式将字段清空重置为默认空值(如 `website` 重置为空串、`account` 重置为空对象)。 - 成功更新后自动写入修订历史链,`version` 版本号自增 +1。 **请求示例**: ```json { "set": { "proxy_cd": 600, "booker.account_cd": 9000, "booker.target_instances": 2 }, "clear": [ "website" ] } ``` **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "Node configuration updated successfully", "data": { "id": 101, "node_id": "node01", "identifier": "vfs.ie.nl", "proxy_cd": 600, "website": "", "booker": { "account_source": "built-in", "account_pool_id": "ie.nl.booker", "account_cd": 9000, "target_instances": 2 }, "version": 2, "updated_by": "admin", "created_at": "2026-08-23T20:10:00", "updated_at": "2026-08-23T20:15:00" } } ``` --- ### 2.5 启用 / 停用配置 (Enable / Disable) - **接口路径**: `PUT /api/node-configurations/{entry_type}/{entry_id}/enable` - **Body 参数**: - `enable` (*boolean*, 必填): `true` 为启用 (`1`),`false` 为停用 (`0`)。 **请求示例**: ```json { "enable": true } ``` **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "Node configuration status toggled", "data": { "id": 101, "enable": 1, "version": 3, "updated_by": "admin", ... } } ``` --- ### 2.6 删除配置条目 - **接口路径**: `DELETE /api/node-configurations/{entry_type}/{entry_id}` - **Query 参数**: - `confirm_purge` (*boolean*, 可选, 默认 `false`): **删除保护守卫**。当当前角色的配置在数据库中**仅剩最后 1 条**时,若不传 `confirm_purge=true` 会拦截并返回 `40000`(提示需二次确认);有多条数据时可直接删除。 **请求示例**: ```http DELETE /api/node-configurations/booker/101?confirm_purge=true ``` **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "Node configuration deleted successfully", "data": true } ``` --- ### 2.7 查询配置修订历史记录 (Revisions) - **接口路径**: `GET /api/node-configurations/{entry_type}/{entry_id}/revisions` - **说明**: 每次新建、修改、启停或回滚都会自动保留完整快照。按时间倒序排列。 **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "success", "data": [ { "id": 15, "entry_type": "booker", "entry_id": 101, "version": 3, "action": "enable", "snapshot": { ... }, "updated_by": "admin", "created_at": "2026-08-23T20:20:00" }, { "id": 14, "entry_type": "booker", "entry_id": 101, "version": 2, "action": "update", "snapshot": { ... }, "updated_by": "admin", "created_at": "2026-08-23T20:15:00" }, { "id": 13, "entry_type": "booker", "entry_id": 101, "version": 1, "action": "create", "snapshot": { ... }, "updated_by": "admin", "created_at": "2026-08-23T20:10:00" } ] } ``` --- ### 2.8 回滚配置至指定历史版本 (Rollback) - **接口路径**: `POST /api/node-configurations/{entry_type}/{entry_id}/rollback` - **Body 参数**: - `revision_id` (*integer*, 必填): 目标历史快照的 ID(来自 2.7 节)。 **请求示例**: ```json { "revision_id": 13 } ``` **响应示例 (`code: 0`)**: ```json { "code": 0, "message": "Node configuration rolled back successfully", "data": { "id": 101, "enable": 0, "version": 4, "updated_by": "admin", ... } } ```