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