2026-05-18 09:12:14 +08:00

11 KiB

Raw Permalink Blame History

name	description
python-fullstack-scaffold	为 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 连续运行

总体架构原则

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

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

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

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

后端推荐目录

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

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/

前端推荐目录

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

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 支持断线重连
配置写入支持备份
服务异常场景需易于接入守护或自动重启机制

输出要求

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

如果用户要“方案”

输出：

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

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

输出并执行：

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

生成代码时的验收清单

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

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

常用提示模板

模板 1：搭建完整框架

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

模板 2：只搭后端骨架

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

模板 3：只搭前端骨架

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

执行提醒

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

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

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

11 KiB Raw Permalink Blame History Unescape Escape