DCTS/docs/api.md

# DCTS (Distributed Computing TLUSTY/SYNSPEC) API 文档

本文档由源代码自动提取并整理，详细说明了 **DCTS 分布式恒星大气网格计算系统** 服务端 (`dcts_server`) 提供的所有 RESTful API 接口规范、数据结构定义、鉴权机制、错误码及 `curl` 调用示例。

---

## 目录 (Table of Contents)

1. [通用说明与鉴权机制](#1-通用说明与鉴权机制)
2. [数据结构与类型定义 (Rust & TypeScript Schema)](#2-数据结构与类型定义-rust--typescript-schema)
3. [计算节点管理 API (Node Management)](#3-计算节点管理-api-node-management)
4. [任务调度与结果上报 API (Task Processing)](#4-任务调度与结果上报-api-task-processing)
5. [种子文件管理 API (Seed Management)](#5-种子文件管理-api-seed-management)
6. [静态资源与数据下载 API (Data Assets)](#6-静态资源与数据下载-api-data-assets)
7. [系统状态监控 API (System Status)](#7-系统状态监控-api-system-status)
8. [工作流管理 API (Workflow CRUD & Execution)](#8-工作流管理-api-workflow-crud--execution)
9. [错误处理与状态码汇总](#9-错误处理与状态码汇总)

---

## 1. 通用说明与鉴权机制

### 1.1 服务端信息
- **默认服务地址**: `http://127.0.0.1:8090` (端口可通过 `--port` / `DCTS_PORT` 环境变量配置)
- **传输协议**: HTTP / HTTPS
- **默认请求/响应格式**: `application/json` (部分文件下载接口为 `application/octet-stream`，任务上报为 `multipart/form-data`)

### 1.2 鉴权机制与权限控制矩阵 (`auth_middleware` & RBAC)

服务端基于角色访问控制 (RBAC) 划分三种请求鉴权级别：

1. **Admin 角色**：具有系统管理权限（工作流 CRUD/起停、节点凭据审批/吊销/重发、系统恢复）。在 Request Header 中需携带：
   ```http
   Authorization: Bearer <DCTS_ADMIN_TOKEN>
   # 或
   x-api-key: <DCTS_ADMIN_TOKEN>
   ```
2. **Node 角色**：仅限 Worker 节点运行态调用（心跳/抢占任务/汇报/下载数据）。携带管理员审批颁发的专属节点 Token：
   ```http
   Authorization: Bearer <NODE_SPECIFIC_TOKEN>
   ```
3. **Public 角色**：无需鉴权直接访问（如 `/login` 管理登录、`/node/register` 提交申请、`/node/check_status` 轮询审批、`/healthz` 健康检查）。

> [!TIP]
> **防侧信道保护**：底层调用 Constant-Time 等时比较机制 (`Sha256` 摘要匹配)，彻底规避侧信道攻击（Side-Channel Attack）。

### 1.3 限流机制与错误模型 (Rate Limiting & Unified Error)

- **API 限流 (Rate Limiting)**：服务端对敏感接口（如 `/login`、`/node/register`）应用了基于 Governor / 漏桶算法的请求限流器。超出速率上限时返回 `429 Too Many Requests`。
- **统一错误格式 (AppError)**：所有 RESTful API 的错误响应均格式化为标准 JSON：
  ```json
  {
    "success": false,
    "message": "错误原因详细说明",
    "data": null
  }
  ```

---

## 2. 数据结构与类型定义 (Rust & TypeScript Schema)

### 2.1 6维网格点参数 (`GridPointParams`)
定义恒星大气模型的 6 维大气参数：温度 $T_{\text{eff}}$、重力加速度 $\log g$、以及元素丰度 $\log(N_{\text{He}}/N_{\text{H}})$, $\log(N_{\text{C}}/N_{\text{H}})$, $\log(N_{\text{N}}/N_{\text{H}})$, $\log(N_{\text{O}}/N_{\text{H}})$。

- **Rust 定义** ([models.rs](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/common/src/models.rs#L6-L14)):
  ```rust
  #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
  pub struct GridPointParams {
      pub teff: f64,   // 有效温度 (K), e.g. 35000.0
      pub logg: f64,   // 表面重力加速度对数 (cgs), e.g. 5.5
      pub loghe: f64,  // 氦丰度对数, e.g. -1.0
      pub logc: f64,   // 碳丰度对数, e.g. -2.0
      pub logn: f64,   // 氮丰度对数, e.g. -2.0
      pub logo: f64,   // 氧丰度对数, e.g. -2.0
  }
  ```

- **TypeScript 类型声明**:
  ```typescript
  export interface GridPointParams {
    teff: number;
    logg: number;
    loghe: number;
    logc: number;
    logn: number;
    logo: number;
  }
  ```

---

### 2.2 任务规格 (`TaskSpec`)
服务端派发给 Worker 节点的单个计算任务定义。

- **Rust 定义** ([models.rs](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/common/src/models.rs#L98-L106)):
  ```rust
  #[derive(Debug, Clone, Serialize, Deserialize)]
  pub struct TaskSpec {
      pub task_id: Uuid,
      pub point_name: String,
      pub params: GridPointParams,
      pub task_type: TaskType,            // ColdRun | SeedStep
      pub seed_point_name: Option<String>,// 步进种子点名称（如适用）
      pub timeout_sec: u64,
  }

  #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
  #[serde(rename_all = "snake_case")]
  pub enum TaskType {
      ColdRun,
      SeedStep,
  }
  ```

- **TypeScript 类型声明**:
  ```typescript
  export type TaskType = 'cold_run' | 'seed_step';

  export interface TaskSpec {
    task_id: string;
    point_name: string;
    params: GridPointParams;
    task_type: TaskType;
    seed_point_name?: string | null;
    timeout_sec: number;
  }
  ```

---

### 2.3 任务上报报告 (`TaskReport`)
Worker 节点向服务端上报的任务计算结果。

- **Rust 定义** ([models.rs](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/common/src/models.rs#L126-L140)):
  ```rust
  #[derive(Debug, Clone, Serialize, Deserialize)]
  pub struct TaskReport {
      pub task_id: Uuid,
      pub point_name: String,
      #[serde(default)]
      pub params: Option<GridPointParams>,
      pub node_id: String,
      pub status: TaskStatus, // Pending | Running | Completed | Failed | Timeout
      pub converged: bool,
      pub max_relc: Option<f64>,
      pub atmosphere_has_nan: bool,
      pub elapsed_sec: f64,
      pub error_message: Option<String>,
      pub summary_json: String,
  }

  #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
  #[serde(rename_all = "snake_case")]
  pub enum TaskStatus {
      Pending,
      Running,
      Completed,
      Failed,
      Timeout,
  }
  ```

- **TypeScript 类型声明**:
  ```typescript
  export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'timeout';

  export interface TaskReport {
    task_id: string;
    point_name: string;
    params?: GridPointParams;
    node_id: string;
    status: TaskStatus;
    converged: boolean;
    max_relc?: number | null;
    atmosphere_has_nan: boolean;
    elapsed_sec: number;
    error_message?: string | null;
    summary_json: string;
  }
  ```

---

### 2.4 节点信息与请求模型 (`NodeRegisterRequest` / `NodeHeartbeatRequest`)

- **Rust 定义** ([models.rs](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/common/src/models.rs#L142-L170)):
  ```rust
  pub struct NodeRegisterRequest {
      pub node_id: String,
      pub host_name: String,
      pub max_slots: i32,
  }

  pub struct NodeHeartbeatRequest {
      pub node_id: String,
      pub active_slots: i32,
      pub cpu_usage: f32,
      pub memory_usage: f32,
  }

  pub struct NodeInfo {
      pub node_id: String,
      pub host_name: String,
      pub max_slots: i32,
      pub active_slots: i32,
      pub status: String,
      pub cpu_usage: f32,
      pub memory_usage: f32,
      pub last_heartbeat: DateTime<Utc>,
  }
  ```

- **TypeScript 类型声明**:
  ```typescript
  export interface NodeRegisterRequest {
    node_id: string;
    host_name: string;
    max_slots: number;
  }

  export interface NodeHeartbeatRequest {
    node_id: string;
    active_slots: number;
    cpu_usage: number;
    memory_usage: number;
  }

  export interface NodeInfo {
    node_id: string;
    host_name: string;
    max_slots: number;
    active_slots: number;
    status: 'online' | 'offline';
    cpu_usage: number;
    memory_usage: number;
    last_heartbeat: string;
  }
  ```

---

### 2.5 工作流响应模型与请求体 (`CreateWorkflowRequest` / `ApiResponse<T>`)

- **Rust 定义** ([workflow.rs](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L12-L24)):
  ```rust
  pub struct CreateWorkflowRequest {
      pub name: String,
      pub description: Option<String>,
      pub config_yaml: String,
  }

  pub struct ApiResponse<T> {
      pub success: bool,
      pub message: String,
      pub data: Option<T>,
  }
  ```

- **TypeScript 类型声明**:
  ```typescript
  export interface CreateWorkflowRequest {
    name: string;
    description?: string | null;
    config_yaml: string;
  }

  export interface ApiResponse<T = unknown> {
    success: boolean;
    message: string;
    data?: T | null;
  }

  export interface WorkflowSummary {
    name: string;
    description?: string | null;
    status: 'idle' | 'running' | 'paused' | 'completed';
    created_at: string;
    updated_at: string;
  }

  export interface WorkflowItem {
    name: string;
    description?: string | null;
    config_yaml: string;
    status: 'idle' | 'running' | 'paused' | 'completed';
    created_at: string;
    updated_at: string;
  }
  ```

---

## 3. 计算节点管理 API (Node Management)

处理 Worker 节点的注册登录与定期心跳保活。

### 3.1 注册计算节点 (`POST /api/node/register`)

- **处理函数**: [`register_node`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/node.rs#L6-L14)
- **函数签名**:
  ```rust
  pub async fn register_node(
      State(state): State<AppState>,
      Json(req): Json<NodeRegisterRequest>,
  ) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **请求 Header**: `Content-Type: application/json`
- **请求 Body**:
  ```json
  {
    "node_id": "node-worker-01",
    "host_name": "hpc-node-01.local",
    "max_slots": 8
  }
  ```
- **响应 Schema**:
  - `200 OK` (成功):
    ```json
    {
      "status": "ok",
      "message": "节点注册成功"
    }
    ```
  - `200 OK` (数据库异常):
    ```json
    {
      "status": "error",
      "message": "数据库错误详情"
    }
    ```
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/node/register \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer secret_token" \
    -d '{
      "node_id": "node-worker-01",
      "host_name": "hpc-node-01.local",
      "max_slots": 8
    }'
  ```

---

### 3.2 节点心跳保活 (`POST /api/node/heartbeat`)

- **处理函数**: [`heartbeat_node`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/node.rs#L17-L25)
- **函数签名**:
  ```rust
  pub async fn heartbeat_node(
      State(state): State<AppState>,
      Json(req): Json<NodeHeartbeatRequest>,
  ) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **请求 Header**: `Content-Type: application/json`
- **请求 Body**:
  ```json
  {
    "node_id": "node-worker-01",
    "active_slots": 2,
    "cpu_usage": 45.2,
    "memory_usage": 30.8
  }
  ```
- **响应 Schema**:
  - `200 OK` (成功):
    ```json
    {
      "status": "ok"
    }
    ```
  - `200 OK` (失败):
    ```json
    {
      "status": "error",
      "message": "节点未找到或心跳更新失败"
    }
    ```
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/node/heartbeat \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer secret_token" \
    -d '{
      "node_id": "node-worker-01",
      "active_slots": 2,
      "cpu_usage": 45.2,
      "memory_usage": 30.8
    }'
  ```

---

### 3.3 节点凭据与审批管理 API (Admin 角色)

#### 1. 列出全部节点及凭据状态 (`GET /api/admin/nodes`)
- **权限**: Admin 角色
- **响应 (`200 OK`)**:
  ```json
  {
    "success": true,
    "message": "成功获取节点列表",
    "data": [
      {
        "node_id": "node-worker-01",
        "has_token": true,
        "is_revoked": false,
        "issued_at": "2026-07-28T12:00:00Z"
      }
    ]
  }
  ```

#### 2. 同意节点接入申请 (`POST /api/admin/nodes/:node_id/approve`)
- **权限**: Admin 角色
- **说明**: 批准处于待审批状态的 Node，并生成该节点的专属 Token。

#### 3. 拒绝节点接入申请 (`POST /api/admin/nodes/:node_id/reject`)
- **权限**: Admin 角色
- **说明**: 拒绝处于待审批状态的 Node 接入。

#### 4. 吊销节点专属 Token (`POST /api/admin/nodes/:node_id/revoke`)
- **权限**: Admin 角色
- **说明**: 立即吊销节点专属 Token，被吊销的 Token 无法再通过 Node 鉴权，需重新申请。

#### 5. 重新颁发节点专属 Token (`POST /api/admin/nodes/:node_id/reissue`)
- **权限**: Admin 角色
- **说明**: 作废旧 Token 并重新生成新 Token 文本返回。

---

## 4. 任务调度与结果上报 API (Task Processing)

支持 Worker 节点抢占式领用任务与计算结果（含种子 `.7` 文件）上传。

### 4.1 领用计算任务 (`POST /api/task/claim`)

- **处理函数**: [`claim_task`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/task.rs#L15-L25)
- **函数签名**:
  ```rust
  pub async fn claim_task(State(state): State<AppState>) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **请求 Body**: 无
- **响应 Schema**:
  - `200 OK` (有可计算任务):
    ```json
    {
      "status": "ok",
      "task": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "point_name": "t35000_g5.5_he-1_c-2_n-2_o-2",
        "params": {
          "teff": 35000.0,
          "logg": 5.5,
          "loghe": -1.0,
          "logc": -2.0,
          "logn": -2.0,
          "logo": -2.0
        },
        "task_type": "cold_run",
        "seed_point_name": null,
        "timeout_sec": 7200
      }
    }
    ```
  - `200 OK` (当前队列为空):
    ```json
    {
      "status": "empty",
      "task": null
    }
    ```
  - `500 Internal Server Error`:
    ```json
    {
      "status": "error",
      "message": "领用任务失败: <error_details>"
    }
    ```
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/task/claim \
    -H "Authorization: Bearer secret_token"
  ```

---

### 4.2 上报任务结果与种子文件 (`POST /api/task/report`)

- **处理函数**: [`report_task`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/task.rs#L27-L102)
- **函数签名**:
  ```rust
  pub async fn report_task(
      State(state): State<AppState>,
      mut multipart: Multipart,
  ) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **请求格式**: `multipart/form-data`
  - Part `report`: JSON 字符串 (映射为 `TaskReport`)
  - Part `seed_file` *(可选)*: 二进制数据 (收敛网格点的 `.7` 大气结构种子文件)
- **响应 Schema**:
  - `200 OK` (成功):
    ```json
    {
      "status": "ok",
      "message": "上报成功"
    }
    ```
  - `400 Bad Request` (缺少 `report` 字段):
    ```json
    {
      "status": "error",
      "message": "请求中缺少 report 字段"
    }
    ```
  - `400 Bad Request` (参数格式错误):
    ```json
    {
      "status": "error",
      "message": "无法解析 params 或 summary_json"
    }
    ```
- **说明**: 当 `converged == true` 且 `atmosphere_has_nan == false` 且包含 `seed_file` 时，服务端会将种子保存至 `results_dir/<point_name>/<point_name>.7` 并记入 `seeds` 表。若冷启动任务失败，服务端会自动唤醒 `GridScheduler` 触发针对该网格点的步进回退算法 (Seed-step Fallback)。
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/task/report \
    -H "Authorization: Bearer secret_token" \
    -F 'report={
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "point_name": "t35000_g5.5_he-1_c-2_n-2_o-2",
      "node_id": "node-worker-01",
      "status": "completed",
      "converged": true,
      "max_relc": 0.00008,
      "atmosphere_has_nan": false,
      "elapsed_sec": 142.5,
      "error_message": null,
      "summary_json": "{\"name\":\"t35000_g5.5_he-1_c-2_n-2_o-2\",\"params\":{\"teff\":35000.0,\"logg\":5.5,\"loghe\":-1.0,\"logc\":-2.0,\"logn\":-2.0,\"logo\":-2.0},\"stages\":[],\"converged\":true,\"elapsed_sec\":142.5,\"atmosphere_has_nan\":false}"
    };type=application/json' \
    -F 'seed_file=@/path/to/t35000_g5.5_he-1_c-2_n-2_o-2.7'
  ```

---

## 5. 种子文件管理 API (Seed Management)

提供在网格计算过程中相近网格点间传递与下载 TLUSTY `fort.7` 大气结构二进制种子文件的功能。

### 5.1 下载网格点种子文件 (`GET /api/seed/:name`)

- **处理函数**: [`download_seed`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/seed.rs#L12-L58)
- **函数签名**:
  ```rust
  pub async fn download_seed(
      State(state): State<AppState>,
      AxumPath(name): AxumPath<String>,
  ) -> Response
  ```
- **鉴权**: 是 (若配置 Token)
- **路径参数**:
  - `name`: 网格点名称 (例如: `t35000_g5.5_he-1_c-2_n-2_o-2`)
- **安全检查**: 防止路径穿越攻击，校验参数中不可包含 `..`、`/` 或 `\`。
- **响应 Header**:
  - `Content-Type: application/octet-stream`
  - `Content-Disposition: attachment; filename="<name>.7"`
- **状态码与响应体**:
  - `200 OK`: 返回文件二进制流
  - `400 Bad Request`: `"非法的种子名称参数"`
  - `404 Not Found`: `"请求的种子文件不存在"`
  - `500 Internal Server Error`: `"无法打开种子文件"`
- **curl 示例**:
  ```bash
  curl -X GET http://localhost:8090/api/seed/t35000_g5.5_he-1_c-2_n-2_o-2 \
    -H "Authorization: Bearer secret_token" \
    --output t35000_g5.5_he-1_c-2_n-2_o-2.7
  ```

---

## 6. 静态资源与数据下载 API (Data Assets)

供 Worker 节点下载执行 TLUSTY / SYNSPEC 所需的原子数据文件和线表。

### 6.1 下载任意数据资源文件 (`GET /api/data/file/*filename`)

- **处理函数**: [`download_single_data_file`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/data.rs#L11-L24)
- **函数签名**:
  ```rust
  pub async fn download_single_data_file(
      AxumPath(filename): AxumPath<String>
  ) -> axum::response::Response
  ```
- **鉴权**: 是 (若配置 Token)
- **路径参数**:
  - `filename`: 文件相对名称 (例如: `he2.dat`)
- **响应 Header**:
  - `Content-Type: application/octet-stream`
  - `Content-Disposition: attachment; filename="<filename>"`
- **状态码与响应体**:
  - `200 OK`: 返回数据文件二进制流
  - `400 Bad Request`: `"无效的数据文件名"`
  - `404 Not Found`: `"资源数据文件不存在"`
  - `500 Internal Server Error`: `"无法读取资源数据文件"`
- **curl 示例**:
  ```bash
  curl -X GET http://localhost:8090/api/data/file/he2.dat \
    -H "Authorization: Bearer secret_token" \
    --output he2.dat
  ```

---

### 6.2 下载主光谱线表文件 (`GET /api/data/linelist`)

- **处理函数**: [`download_linelist`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/data.rs#L26-L28)
- **函数签名**:
  ```rust
  pub async fn download_linelist() -> axum::response::Response
  ```
- **鉴权**: 是 (若配置 Token)
- **响应**: 默认定位并流式返回 `assets/gfVIS99.dat` 文件。
- **状态码**: `200 OK` (或 `404 Not Found` / `500 Internal Server Error`)
- **curl 示例**:
  ```bash
  curl -X GET http://localhost:8090/api/data/linelist \
    -H "Authorization: Bearer secret_token" \
    --output gfVIS99.dat
  ```

---

## 7. 系统状态监控 API (System Status)

实时监控分布式计算集群节点活跃度与计算槽位利用率。

### 7.1 获取集群整体状态 (`GET /api/status`)

- **处理函数**: [`get_status`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/status.rs#L5-L17)
- **函数签名**:
  ```rust
  pub async fn get_status(State(state): State<AppState>) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **响应 Schema (`200 OK`)**:
  ```json
  {
    "status": "online",
    "nodes_online": 2,
    "total_active_slots": 4,
    "total_max_slots": 16,
    "nodes": [
      {
        "node_id": "node-worker-01",
        "host_name": "hpc-node-01.local",
        "max_slots": 8,
        "active_slots": 2,
        "status": "online",
        "cpu_usage": 45.2,
        "memory_usage": 30.8,
        "last_heartbeat": "2026-07-27T16:55:00.000Z"
      }
    ],
    "grid_stats": {
      "total": 512,
      "pending": 210,
      "running": 32,
      "converged": 260,
      "failed": 10
    }
  }
  ```
  > `grid_stats` 为**全部工作流的合计**（跨工作流全局聚合）。多工作流并发运行时，此处展示所有
  > 工作流 grid_points 的汇总进度；如需查看单个工作流的进度，可读取该工作流各自的 grid_points 统计
  > （`Database::get_grid_summary_stats(Some(workflow_name))`）。
- **curl 示例**:
  ```bash
  curl -X GET http://localhost:8090/api/status \
    -H "Authorization: Bearer secret_token"
  ```

---

### 7.2 轻量级健康检查端点 (`GET /healthz`)

- **鉴权**: 否 (Public 免鉴权，专用于 Docker / K8s / Caddy 探针)
- **响应 (`200 OK`)**:
  ```json
  {
    "status": "ok"
  }
  ```
- **curl 示例**:
  ```bash
  curl -i http://localhost:8090/healthz
  ```

---

## 8. 工作流管理 API (Workflow CRUD & Execution)

管理恒星大气网格计算工作流 YAML 配置的增删改查、启动与暂停控制。

### 8.1 获取工作流列表 (`GET /api/workflows`)

- **处理函数**: [`list_workflows`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L26-L31)
- **函数签名**:
  ```rust
  pub async fn list_workflows(State(state): State<AppState>) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **说明**: 返回工作流轻量级元数据列表（包含 `name`、`description`、`status`、`created_at`、`updated_at`）。如需获取具体工作流的 YAML 配置详情，请调用 `GET /api/workflows/:name`。
- **响应 Schema (`200 OK`)**:
  ```json
  {
    "success": true,
    "message": "成功获取工作流列表",
    "data": [
      {
        "name": "sdB_cno",
        "description": "sdB CNO 6D Stellar Atmosphere Grid",
        "status": "idle",
        "created_at": "2026-07-27T08:00:00Z",
        "updated_at": "2026-07-27T08:00:00Z"
      }
    ]
  }
  ```
- **curl 示例**:
  ```bash
  curl -X GET http://localhost:8090/api/workflows \
    -H "Authorization: Bearer secret_token"
  ```

---

### 8.2 创建或保存工作流 (`POST /api/workflows` / `PUT /api/workflows/:name`)

- **处理函数**: [`save_workflow`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L44-L81)
- **函数签名**:
  ```rust
  pub async fn save_workflow(
      State(state): State<AppState>,
      Json(req): Json<CreateWorkflowRequest>,
  ) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **请求 Body**:
  ```json
  {
    "name": "sdB_cno_custom",
    "description": "自定义 6维 网格计算工作流",
    "config_yaml": "grid:\n  teff: [35000, 36000]\n  logg: [5.5, 6.0]\n  loghe: [-1.0]\n  logc: [-2.0]\n  logn: [-2.0]\n  logo: [-2.0]\nchain:\n  - label: LTE_START\n    lte: T\n    niter: 30\n"
  }
  ```
- **响应 Schema**:
  - `200 OK` (成功保存):
    ```json
    {
      "success": true,
      "message": "工作流 'sdB_cno_custom' 保存成功",
      "data": null
    }
    ```
  - `400 Bad Request` (YAML 格式不合法):
    ```json
    {
      "success": false,
      "message": "无效的 YAML 配置: invalid syntax at line 2...",
      "data": null
    }
    ```
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/workflows \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer secret_token" \
    -d '{
      "name": "sdB_cno_custom",
      "description": "自定义 6维 网格计算工作流",
      "config_yaml": "grid:\n  teff: [35000, 36000]\n  logg: [5.5, 6.0]\n  loghe: [-1.0]\n  logc: [-2.0]\n  logn: [-2.0]\n  logo: [-2.0]\nchain:\n  - label: LTE_START\n    lte: T\n    niter: 30\n"
    }'
  ```

---

### 8.3 获取特定工作流详情 (`GET /api/workflows/:name`)

- **处理函数**: [`get_workflow`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L33-L42)
- **函数签名**:
  ```rust
  pub async fn get_workflow(
      State(state): State<AppState>,
      AxumPath(name): AxumPath<String>,
  ) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **路径参数**: `name` (工作流唯一名称，如 `sdB_cno`)
- **响应 Schema**:
  - `200 OK` (成功):
    ```json
    {
      "success": true,
      "message": "成功获取工作流详情",
      "data": {
        "id": 1,
        "name": "sdB_cno",
        "description": "sdB CNO 6D Stellar Atmosphere Grid",
        "config_yaml": "...",
        "status": "idle",
        "created_at": "2026-07-27T08:00:00Z",
        "updated_at": "2026-07-27T08:00:00Z"
      }
    }
    ```
  - `404 Not Found` (不存在):
    ```json
    {
      "success": false,
      "message": "工作流 'unknown_wf' 未找到",
      "data": null
    }
    ```
- **curl 示例**:
  ```bash
  curl -X GET http://localhost:8090/api/workflows/sdB_cno \
    -H "Authorization: Bearer secret_token"
  ```

---

### 8.4 删除工作流 (`DELETE /api/workflows/:name`)

- **处理函数**: [`delete_workflow`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L83-L105)
- **函数签名**:
  ```rust
  pub async fn delete_workflow(
      State(state): State<AppState>,
      AxumPath(name): AxumPath<String>,
  ) -> impl IntoResponse
  ```
- **鉴权**: 是 (若配置 Token)
- **响应 Schema (`200 OK`)**:
  ```json
  {
    "success": true,
    "message": "工作流 'sdB_cno_custom' 已删除",
    "data": null
  }
  ```
- **curl 示例**:
  ```bash
  curl -X DELETE http://localhost:8090/api/workflows/sdB_cno_custom \
    -H "Authorization: Bearer secret_token"
  ```

---

### 8.5 启动工作流 (`POST /api/workflows/:name/start`)

- **处理函数**: [`start_workflow`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L107-L183)
- **函数签名**:
  ```rust
  pub async fn start_workflow(
      State(state): State<AppState>,
      AxumPath(name): AxumPath<String>,
  ) -> impl IntoResponse
  ```
- **说明**: 校验工作流，解析 YAML 中定义的所有 6 维网格坐标点，通过 `GridScheduler::initialize_grid` 展开网格点并计算保序难度 Wave，写入 SQLite 任务队列并开启节点调度。
- **响应 Schema**:
  - `200 OK` (成功启动):
    ```json
    {
      "success": true,
      "message": "工作流 'sdB_cno' 已成功启动并安排计算任务",
      "data": null
    }
    ```
  - `400 Bad Request` (重复启动):
    ```json
    {
      "success": false,
      "message": "工作流 'sdB_cno' 已处于运行状态，无需重复启动",
      "data": null
    }
    ```
  - `404 Not Found`:
    ```json
    {
      "success": false,
      "message": "工作流 'sdB_cno' 未找到",
      "data": null
    }
    ```
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/workflows/sdB_cno/start \
    -H "Authorization: Bearer secret_token"
  ```

---

### 8.6 暂停工作流 (`POST /api/workflows/:name/stop`)

- **处理函数**: [`stop_workflow`](file:///home/fmq/program/tlusty/tl208-s54/dcts/crates/server/src/api/workflow.rs#L185-L207)
- **函数签名**:
  ```rust
  pub async fn stop_workflow(
      State(state): State<AppState>,
      AxumPath(name): AxumPath<String>,
  ) -> impl IntoResponse
  ```
- **响应 Schema (`200 OK`)**:
  ```json
  {
    "success": true,
    "message": "工作流 'sdB_cno' 已暂停",
    "data": null
  }
  ```
- **curl 示例**:
  ```bash
  curl -X POST http://localhost:8090/api/workflows/sdB_cno/stop \
    -H "Authorization: Bearer secret_token"
  ```

---

## 9. 错误处理与状态码汇总

| HTTP 状态码 | 触发场景说明 | 响应格式 | 核心原因与解决建议 |
| :--- | :--- | :--- | :--- |
| **`200 OK`** | 请求正常处理 | JSON / Binary Stream | 操作成功执行。 |
| **`400 Bad Request`** | 参数校验失败、缺失关键字段或 YAML 格式错误 | `application/json` / Plain Text | 检查请求 JSON 结构，验证 YAML 配置语法是否正确。 |
| **`401 Unauthorized`** | 鉴权失败或缺失 Authorization Header | `application/json` | 确认环境变量配置，并在 Request Header 中包含正确的 Token。 |
| **`404 Not Found`** | 资源、种子文件或工作流不存在 | `application/json` | 校验请求 URL 中的资源文件名或工作流 `name` 是否拼写无误。 |
| **`429 Too Many Requests`** | API 请求超出速率限制（限流生效） | `application/json` | 降低请求频率或配置漏桶/令牌桶容量参数。 |
| **`500 Internal Server Error`** | 服务端数据库错误、I/O 打开失败或队列异常 | `application/json` | 检查服务端日志以进一步厘清 SQLite 锁冲突、磁盘空间或资源路径问题。 |

---
*文档生成于 2026-07-27 | DCTS Server 0.1.0*