455 lines
11 KiB
Markdown
455 lines
11 KiB
Markdown
---
|
||
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/`
|
||
- 前端当前使用的具体技术栈和构建工具
|
||
- 后端是否已有可复用入口、配置系统和测试结构
|
||
- 用户要的是“技能文件”、 “设计方案” 还是 “直接生成代码”
|
||
|
||
若信息不足，先补充上下文；若仓库已有实现，优先做兼容式演进，而不是重建。
|