# DCTS 系统架构 (System Architecture)

> 介绍 DCTS (Distributed Computing TLUSTY/SYNSPEC) 的整体设计架构、Master-Worker 拓扑结构、任务生命周期流转及容错机制。

---

## 1. 架构拓扑 (Topology)

DCTS 采用**中心化控制、分布式离散执行 (Master-Worker)** 的拓扑设计：

```mermaid
flowchart TB
    subgraph Master Node ["Master 服务端 (server)"]
        API["Axum HTTP REST API"]
        DB[(主数据库 dcts.db)]
        MQ[(任务队列 dcts_queue.db)]
        Scheduler["Grid Scheduler 网格调度器"]
        SeedsStorage["本地种子库 results/*.7"]
        
        API <--> DB
        API <--> MQ
        Scheduler --> MQ
        Scheduler --> DB
    end

    subgraph Compute Nodes ["分布式计算节点集群 (node)"]
        Worker1["Worker 节点 1 (Node Daemon)"]
        Worker2["Worker 节点 2 (Node Daemon)"]
        WorkerN["Worker 节点 N (Node Daemon)"]
    end

    Worker1 -- "1. 心跳/抢占任务 (Claim)" --> API
    Worker1 -- "2. 下载种子/基础数据" --> API
    Worker1 -- "3. 汇报结果/上传 .7 大气" --> API

    Worker2 -- "HTTP REST / Bearer Auth" --> API
    WorkerN -- "HTTP REST / Bearer Auth" --> API

    API --> SeedsStorage
```

---

## 2. 核心组件职责

### 2.1 Master 服务端 (`server` & Web `dashboard`)
- **工作流与可视看板调度**：解析 `config.yaml` 生成多维笛卡尔积参数网格点放入 SQLite 数据库；且自带前端服务透射特性（映射 `dashboard/dist`），开局即在后端服务的相同接口同服下发开机即饮用的富监看运维控制桌仪表网页。
- **任务调度与分配**：通过 `mq` 队列管理任务生命周期，响应 Worker 的 Claim 请求分配就绪任务。
- **状态维护与心跳监测**：后台离线检测线程定期标记超时未心跳的节点为 `offline`，并能将因为断线掉电死机僵挂在其身上的坏死大批网格运算占位点清表并原路全方位无漏损地安全刷进重置任务池中（Requeue）避免死锁失联漏计。
- **静态资源与种子分发**：提供原子数据、线列表与 `.7` 大气种子文件的 HTTP 下载和上传接口。

### 2.2 Worker 计算节点 (`node`)
- **环境自适应预热 (Bootstrap)**：启动时核对本地 `./runtime` 运行依赖，缺失时自动向 Master 拉取可执行文件与二进制数据。
- **任务抢占与执行 (Claim & Execute)**：根据并发配置轮询抢占任务，调用 `common` 启动子进程链（tlusty / synspec）。
- **种子检索与回传 (Seed Sync)**：计算成功后将收敛的大气结构文件（`.7`）与状态 JSON 汇报回服务端。

---

## 3. 任务生命周期 (Task Lifecycle)

网格计算点从创建到完成的状态流转如下图所示：

```mermaid
stateDiagram-v2
    [*] --> Pending : 工作流注册生成网格点
    Pending --> Running : Worker 成功 Claim 抢占
    
    state Running {
        [*] --> ExecutingChain
        ExecutingChain --> ColdStartChain : 默认冷启动 (lte->nc->nl)
        ColdStartChain --> Synspec : 物理收敛
        ColdStartChain --> SeedStepChain : 冷启动发散且有可邻近种子
        SeedStepChain --> Synspec : 热启动收敛
    }

    Running --> Completed : 计算成功 & 上传 .7 产物
    Running --> Pending : Worker 节点心跳超时/主动释放 (Requeue)
    Running --> Failed : 重试次数达到上限 / 彻底发散

    Completed --> [*]
    Failed --> [*]
```

---

## 4. 容错与高可用设计 (Fault Tolerance)

1. **分布式无状态 Worker & 上报阶梯退避**：Worker 节点不保存持久运行控制状态，异常宕机不会损坏主数据集。计算结果向 Master 上报时，具备多达 8 次指数阶梯容灾回退（最大间隔 60 秒，覆盖超 2 分钟断断连长窗），稳健保障长时间高密物理算单不受瞬时组网闪断或服务端短时上线切换干预。
2. **零文件扫描与连接并发缩流**：底层任务分批取配、排队清洗与邻接优化（Seed-Stepping）全链线依赖常驻内存的 SQlite 主从精算并调优收敛连接池配置（主库=8，队列=4 减免本地排他写冲突并发挂断）；去除了历史残存的高损及同步阻塞磁盘遍历 API，在确保零卡死响应的前提下提升查询搜索效力。
3. **任务超时与流控平稳保护 (Stale & Requeue)**：服务端后台定期向已超时死挂的 `Running` （默认 >1800 秒）作业予以强退回转为 `Pending`；此外当操作维护员发起暂停或终止工作流行为时，将仅平滑洗退待调 `Queued` 项，悉心保育在途已投的 Worker 数值演算完整出计算归表，防假命题竞合。
4. **多级退避与种子隔离**：若某点冷启动发散，自动隔离失败现场，依靠数据库记录寻找欧氏空间距离最匹配的热启动合拢 `.7` 气象序列；即便遇到底层强硬大步发散也不产生干扰并留存物理运行根系以便溯源。