emcp/.trae/skills/python-fullstack-scaffold/SKILL.md

---
name: "python-fullstack-scaffold"
description: "为 FastAPI + WebSocket + Web 前端系统生成前后端开发框架。用户需要搭建或重构 RK3568 电气量测控平台的 Python 全栈代码结构时调用。"
---

# Python Fullstack Scaffold

## 适用场景

当用户出现以下意图时，调用此技能：

- 要根据需求文档搭建 `FastAPI + WebSocket + Web前端` 的项目骨架
- 要为 `RK3568 / Ubuntu 20.04 / Python 3.8` 平台设计前后端分层结构
- 要从接口文档反推后端路由、数据模型、配置存储和前端页面模块
- 要统一实时数据、设备状态、报警事件、参数配置的代码组织方式
- 要为嵌入式 C 程序与 Python 服务之间的适配层预留稳定接口

如果用户只是修一个接口、改一个组件、补一个测试，不要调用此技能。

## 技能目标

基于“电气量测控平台系统需求分析与架构设计技术方案”，输出一套可直接落地的前后端开发框架，覆盖：

- 后端目录结构
- 前端目录结构
- 核心领域模型
- RESTful API 路由分层
- WebSocket 推送框架
- JSON/SQLite 数据存储组织
- 嵌入式适配层抽象
- 开发顺序、验收点与最小可运行骨架

## 固定技术约束

在生成方案或代码时，默认遵循以下约束，除非用户明确要求变更：

- 平台：`RK3568`，系统为 `Ubuntu 20.04`
- 后端：`Python 3.8`、`FastAPI`、`Uvicorn`
- 前端：Web 前端，优先采用当前项目已有技术栈；若项目未定型，则使用轻量、易部署的前端组织方式
- 通信：`HTTP RESTful API + WebSocket`
- 配置存储：`JSON`
- 报警存储：`SQLite`
- 实时数据：仅内存缓存，不落盘
- 实时刷新周期：`0.5 秒`
- 指令下发响应目标：`1 秒内`
- 系统需支持 `7 x 24` 连续运行

## 总体架构原则

始终按下面的职责边界组织代码：

1. 硬件层：`RK3568 + AI/AO + 开关量 + 网络/串口 + 显示屏`
2. 嵌入式 C 程序层：采集、控制执行、状态监测、报警生成
3. Python 服务层：接口、业务编排、缓存、存储、推送
4. Web 界面层：配置、状态、实时数据、报警、控制

禁止把以下职责混在一起：

- 路由层里直接写文件读写和数据库细节
- WebSocket 推送逻辑散落在多个业务模块中
- 前端页面组件里直接硬编码接口路径和协议细节
- C 程序适配逻辑与业务规则耦合

## 后端推荐目录

当用户要求搭建后端框架时，优先生成或对齐为如下结构：

```text
backend/
  app/
    main.py
    core/
      config.py
      logging.py
      security.py
      response.py
      exceptions.py
    api/
      deps.py
      router.py
      routes/
        realtime.py
        status.py
        config_device.py
        config_channel.py
        config_alarm.py
        config_system.py
        alarms.py
        control.py
    schemas/
      common.py
      realtime.py
      status.py
      device_config.py
      channel_config.py
      alarm_setting.py
      system_config.py
      alarm_event.py
      control.py
    services/
      realtime_service.py
      status_service.py
      config_service.py
      alarm_service.py
      control_service.py
      sync_service.py
    repositories/
      json_config_repo.py
      alarm_repo.py
    adapters/
      c_device_client.py
      mock_device_client.py
      protocol_models.py
    ws/
      manager.py
      realtime_publisher.py
      alarm_publisher.py
    db/
      sqlite.py
      models.py
    cache/
      memory_store.py
    tasks/
      polling.py
    utils/
      time_utils.py
      backup.py
  config/
    device.json
    channel.json
    setting.json
  data/
    alarm.db
  tests/
```

## 前端推荐目录

当用户要求搭建前端框架时，优先生成或对齐为如下结构：

```text
frontend/
  src/
    main.ts
    App.vue
    router/
      index.ts
    api/
      http.ts
      realtime.ts
      status.ts
      config.ts
      alarm.ts
      control.ts
    websocket/
      realtime.ts
      alarm.ts
      reconnect.ts
    stores/
      realtime.ts
      status.ts
      alarm.ts
      config.ts
    views/
      RealtimeView.vue
      StatusView.vue
      DeviceConfigView.vue
      ChannelConfigView.vue
      AlarmSettingView.vue
      AlarmHistoryView.vue
      ControlView.vue
      SystemConfigView.vue
    components/
      status/
      realtime/
      alarm/
      config/
      control/
    types/
      api.ts
      realtime.ts
      status.ts
      config.ts
      alarm.ts
    utils/
      format.ts
      validators.ts
```

如果仓库已有前端目录，则优先复用现有技术栈、构建工具和状态管理方式，不要无意义重建。

## 领域模型拆分

构建代码框架时，必须先把需求拆成以下核心模型：

### 1. 实时数据模型

- `line_list`
- `switch`
- `ai_collect`

其中 `line_list` 需要体现：

- `line_no`
- 一次值 `pri_val`
- 二次值 `sec_val`

### 2. 设备状态模型

- `self_check`
- `net1`
- `net2`
- `uart1`
- `uart2`

### 3. 设备基础配置模型

- 操作密码
- 硬件版本信息
- 软件版本信息
- 网口配置
- 串口配置

### 4. 通道配置模型

- `ai_channel`
- `ao_channel`

### 5. 定值与 AI 报警设置模型

- 线路告警阈值
- 故障告警设置
- AI 通道报警设置

### 6. 系统配置模型

- 对时设置
- 亮度设置
- 屏保时间

### 7. 报警事件模型

- `alarm_type`
- `time`
- `no`
- `type`
- `content`
- `level`

### 8. 控制指令模型

- `ch`
- `action`

## API 设计规则

生成后端接口时，统一遵守以下规范：

- 所有 HTTP 接口统一响应结构：`code`、`msg`、`data`
- 路由层仅负责参数校验、调用服务、返回标准响应
- `GET /api/real-time-data` 作为实时数据备用查询接口
- `GET /api/device-status` 用于设备状态读取
- `POST /api/config/device` 持久化设备基础配置并下发设备
- `POST /api/config/channel` 持久化 AI/AO 通道配置并下发设备
- `POST /api/config/line_alarm_setting` 持久化线路定值与故障告警设置
- `POST /api/config/ai_alarm_setting` 持久化 AI 告警设置
- `POST /api/config/system` 处理对时、亮度、屏保配置，并实时下发
- `GET /api/alarm/list` 分页查询报警历史
- `POST /api/control/switch` 下发开关量控制指令

如果用户要求生成代码，优先先搭出路由、Schema、Service、Repository 的闭环，再补设备适配与前端页面。

## WebSocket 设计规则

必须把 WebSocket 当作一等公民设计，不要退化为轮询替代品。

### 实时数据通道

- 地址：`/ws/real-time`
- 推送周期：`0.5 秒`
- 推送内容：`real_time`
- 数据来源：内存缓存中的最新采样结果

### 报警通道

- 地址：`/ws/alarm`
- 触发方式：报警事件产生即推送
- 推送内容：单条报警事件或标准化事件消息

### WebSocket 实现要求

- 统一连接管理器
- 支持多客户端广播
- 支持断线清理
- 前端必须具备自动重连
- 推送数据结构必须和前端类型定义一致

## 存储设计规则

### JSON 配置

以下配置默认存放在 `config/`：

- `device.json`
- `channel.json`
- `setting.json`

要求：

- 保存前先做 Schema 校验
- 写入时支持原子替换
- 修改后自动备份旧版本
- 关键字段变更后调用设备下发接口

### SQLite 报警库

报警事件单独存放在 SQLite 中，至少包含：

- `id`
- `alarm_type`
- `time`
- `no`
- `type`
- `content`
- `level`

要求：

- 写入逻辑集中在 Repository
- 查询支持分页
- 前端历史页调用分页接口，不直接访问数据库

### 内存缓存

以下数据只保存在内存中：

- 实时量测数据
- 实时设备状态
- 最近待推送报警缓冲

## 嵌入式适配层规则

当用户要落地与 C 程序交互的代码框架时，必须建立设备适配层，不要让业务层直接依赖具体协议细节。

至少抽象以下能力：

- 读取实时数据
- 读取设备状态
- 读取报警事件
- 下发基础配置
- 下发通道配置
- 下发系统设置
- 下发开关控制

推荐做法：

- 定义统一客户端接口，例如 `DeviceClient`
- 提供 `MockDeviceClient` 供联调和前端开发使用
- 提供 `CDeviceClient` 作为真实嵌入式对接实现
- 通过配置切换 mock / real 模式

## 安全与可靠性规则

必须纳入以下要求：

- 密码不得明文长期存储，至少做哈希处理
- 配置接口增加基本权限校验能力
- WebSocket 支持断线重连
- 配置写入支持备份
- 服务异常场景需易于接入守护或自动重启机制

## 推荐开发顺序

当用户要求“开始搭框架”时，按以下顺序推进：

1. 先梳理接口、数据模型、目录结构
2. 再生成后端基础工程：配置、日志、异常、统一响应
3. 再生成 Schema、Repository、Service、Router
4. 再搭建内存缓存、轮询任务、WebSocket 管理器
5. 再补 SQLite 与 JSON 持久化
6. 再抽象设备适配层和 mock 数据源
7. 最后生成前端 API 封装、状态管理、页面骨架与 WebSocket 客户端

## 输出要求

调用本技能后，输出内容应尽量包含以下几项：

### 如果用户要“方案”

输出：

- 建议目录结构
- 模块职责划分
- 核心数据模型清单
- API / WebSocket 对应关系
- 开发阶段拆分

### 如果用户要“直接写代码”

输出并执行：

- 先识别现有仓库中 `backend/`、`frontend/` 的当前结构
- 尽量增量修改，不要推倒重来
- 先落最小可运行骨架，再补细节
- 优先保证接口契约、模块边界、可测试性

## 生成代码时的验收清单

生成或修改后，至少检查：

- 后端是否存在统一应用入口
- 路由、服务、仓储、适配层是否职责分离
- 是否覆盖需求文档中的全部 API
- 是否存在 `/ws/real-time` 与 `/ws/alarm`
- 实时数据是否只走内存缓存
- 报警历史是否落 SQLite
- 配置是否落 JSON
- 前端是否拆出页面、API、WebSocket、类型定义
- 是否保留 mock 联调能力

## 常用提示模板

### 模板 1：搭建完整框架

```text
请基于当前仓库和需求文档，搭建 RK3568 电气量测控平台的前后端代码框架。
后端使用 FastAPI，前端沿用仓库现有技术栈。
要求包含目录结构、统一响应、配置读写、SQLite 告警存储、WebSocket 实时推送、设备适配层与 mock 数据源。
```

### 模板 2：只搭后端骨架

```text
请按 python-fullstack-scaffold 技能，为该项目生成后端骨架。
要求覆盖 realtime、status、config、alarm、control 五类能力，并预留嵌入式 C 程序适配层。
```

### 模板 3：只搭前端骨架

```text
请按 python-fullstack-scaffold 技能，为该项目生成前端页面骨架和 API/WebSocket 接入层。
要求覆盖实时数据、设备状态、基础配置、通道配置、报警历史和控制页面。
```

## 执行提醒

在实际执行前，先确认以下信息：

- 当前仓库是否已经存在 `backend/` 和 `frontend/`
- 前端当前使用的具体技术栈和构建工具
- 后端是否已有可复用入口、配置系统和测试结构
- 用户要的是“技能文件”、 “设计方案” 还是 “直接生成代码”

若信息不足，先补充上下文；若仓库已有实现，优先做兼容式演进，而不是重建。