# PLC Control

PLC Control 是一个面向 PLC / OPC UA 场景的本地控制与监控系统，提供设备建模、点位管理、控制单元自动控制、实时信号展示、日志追踪和文档查看能力。

## 核心功能

### 1. 数据源与点位管理

- 支持 OPC UA 数据源接入、重连和节点浏览
- 支持从节点批量创建点位
- 支持点位与设备、标签、信号角色的绑定
- 支持批量写点和实时值查看

### 2. 设备与控制单元建模

- 设备可按 `unit_id` 归属到控制单元
- 点位可按 `signal_role` 标记为 `start_cmd`、`stop_cmd`、`run`、`flt`、`rem` 等控制信号
- 控制单元通过时长参数描述启停节奏与累计运行逻辑

### 3. 自动控制引擎

- 后端为每个启用中的控制单元维护独立异步任务
- 支持 `Stopped -> Running -> DistributorRunning` 状态流转
- 支持通信锁定、故障锁定、人工确认
- 支持单个和批量启动/停止自动控制

### 4. 手动控制与联锁

- 设备手动启停前会检查 REM、FLT、信号质量和单元运行时状态
- 自动控制启用时会阻止冲突的手动命令
- `fault_locked`、`comm_locked`、`manual_ack_required` 都会阻止自动启动

### 5. 前端双视图

- `Ops` 视图:
  - 展示控制单元状态
  - 展示设备卡片和 REM/RUN/FLT 实时信号
  - 提供设备启停和批量自动控制入口
- `Config` 视图:
  - 展示数据源、设备、点位、事件、图表
  - 展示实时日志流

### 6. 实时通信

- WebSocket 推送点位实时值
- WebSocket 推送控制单元运行时变化
- SSE 推送日志增量
- 日志流默认跟随最新 `app.log*` 文件，支持轮转切换

## 系统设计

## 后端结构

- `src/main.rs`
  - 启动 Axum 服务
  - 注册 HTTP 路由、WebSocket 路由和静态页面
- `src/handler`
  - HTTP 接口层
- `src/service`
  - 数据查询与写入封装
- `src/control`
  - 自动控制引擎、运行时存储、手动控制校验、模拟反馈
- `src/connection.rs`
  - OPC UA 连接管理、订阅、轮询、批量写点
- `src/event.rs`
  - 控制事件、实时点位事件和事件持久化
- `src/websocket.rs`
  - WebSocket 房间与实时消息广播

## 控制引擎设计

控制引擎的几个关键点:

- 每个启用单元有一个独立任务
- 每轮循环都会重读单元配置和设备角色映射
- 设备/点位控制相关配置变更后，会主动唤醒对应单元任务
- `wait_phase` 使用 `sleep_until(deadline)`，保证阶段计时不会被中途轮询漂移

当前时长约束:

- `run_time_sec > 0`
- `stop_time_sec > 0`
- `acc_time_sec > 0`
- `bl_time_sec > 0`
- `acc_time_sec > run_time_sec`

## 前端 Web 设计

前端采用原生 ES Module 和分片 HTML 结构。

关键模块:

- `web/js/app.js`: 页面启动、视图切换、事件绑定
- `web/js/ops.js`: 运维视图渲染
- `web/js/logs.js`: WebSocket 与日志 SSE 处理
- `web/js/docs.js`: Markdown 文档抽屉
- `web/js/units.js` / `equipment.js` / `points.js`: 配置视图业务逻辑

文档查看入口:

- 可在前端页面中查看 `API.md`
- 可在前端页面中查看 `README.md`

两者都通过统一的文档抽屉组件展示。

## 实时日志设计

日志能力包含两部分:

- `GET /api/logs`
  - 拉取日志内容
- `GET /api/logs/stream`
  - SSE 增量推送

日志轮转行为:

- 如果未指定 `file`，后端总是跟随最新 `app.log*`
- 一旦轮转到新文件，SSE 流自动切换
- 前端会插入分隔提示，标识当前切换到了哪个日志文件

## 运行方式

## 主要依赖

- Rust
- Axum
- Tokio
- SQLx
- PostgreSQL
- async-opcua

## 关键环境变量

- `DATABASE_URL`
- `HOST`
- `PORT`
- `WRITE_API_KEY`
- `SIMULATE_PLC`

## 文档索引

- API 接口说明: `API.md`
- 控制引擎计划: `docs/superpowers/plans/2026-03-24-control-engine.md`
- 双视图前端计划: `docs/superpowers/plans/2026-03-25-dual-view-web.md`

## 当前实现特点

- 后端偏本地部署和现场控制使用
- 控制状态保存在内存中，重启后重置
- 前端和后端都围绕“实时控制 + 快速排障”设计