AGENTS.md
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
项目概述
污水毒品快检一体机控制软件（kuaishai2），用于控制设备运行程序、管理程序配置、监控运行状态。
包名: com.xiarui.kuaishai2
开发命令
# 获取依赖
flutter pub get
# 运行应用 (调试模式)
flutter run
# 构建 APK
flutter build apk
# 构建发布版 APK
flutter build apk --release
# 代码分析
flutter analyze
# 运行测试
flutter test
# 清理构建缓存
flutter clean
代码架构
项目采用 feature-first 分层架构，结构如下：
lib/
├── core/ # 核心模块
│ ├── database/ # SQLite 数据库服务 (单例)
│ ├── router/ # GoRouter 路由配置
│ ├── theme/ # AppTheme 主题定义
│ └── localization/ # AppLocalizations 国际化
├── features/ # 功能模块
│ ├── home/ # 首页（设备控制面板）
│ ├── programs/ # 程序管理
│ ├── program_detail/ # 程序详情/步骤配置
│ ├── device/ # 设备运行控制
│ └── settings/ # 系统设置
└── shared/ # 共享组件
├── widgets/ # 通用组件 (CommonButton, CommonCard, StatusIndicator)
└── utils/ # 常量定义 (Constants)
技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| 状态管理 | flutter_riverpod | StateNotifier + Provider 模式 |
| 路由 | go_router | 声明式路由，支持路径参数 |
| 数据持久化 | sqflite | SQLite 本地数据库 |
| 国际化 | intl + flutter_localizations | 中/英双语 |
核心数据模型
Program (程序): id, code, name, createdAt, status(1启用/0停用)
Step (步骤): id, programId, stepNo, position, name, mixTime, magnetTime, volume, mixSpeed, blowSpeed, blowTime, needleSpeed
关键 Provider
programsProvider- 程序列表状态 (StateNotifier)runStateProvider- 设备运行状态 (RunStatus: idle/running/paused/completed/error)goRouterProvider- 路由配置
数据库
DatabaseService 为单例模式，表结构：
programs- 程序表steps- 步骤表 (外键关联 program_id)
国际化
AppLocalizations 支持中文(zh)和英文(en)，使用 AppLocalizations.of(context) 获取翻译。
代码规范
- Dart SDK 版本: ^3.11.5
- 使用
flutter_lints包的推荐 lint 规则 - 代码风格遵循 Flutter 官方最佳实践
功能模块
根据需求文档，应用包含以下核心模块：
1. 首页模块（设备控制面板）
- 状态栏：设备名称、实时时钟、系统状态、照明控制
- 程序列表：卡片展示、程序选择、查看详情
- 运行控制：启动/暂停/停止程序
- 运行状态监控：当前步骤、剩余时间、总进度
2. 程序管理模块
- 程序列表：编号、名称、创建时间、状态
- CRUD 操作：新增、编辑、删除、导入程序
3. 程序详情模块
- 步骤管理：步骤列表、排序、增删改
- 步骤参数：孔位、混合时间、吸磁时间、容积、速度等
4. 系统设置模块
- 软件升级、语言切换（中文/英文）、密码修改、U盘导入
步骤参数说明
| 参数 | 说明 | 取值范围 |
|---|---|---|
| 孔位 | 操作位置 | A1, A2, B1... |
| 混合时间 | 混合持续时间 | 正整数(秒) |
| 吸磁时间 | 磁珠吸附时间 | 正整数(秒) |
| 容积 | 液体体积 | 正整数(μL) |
| 混合/吹气速度 | 操作速度 | 低速/中速/高速 |
| 下针速度 | 针头下移速度 | 1-10档 |
当前实现状态
已完成基础架构搭建，实现了：
- 首页：状态栏、程序列表、运行控制面板、运行状态监控
- 程序管理：列表展示、新增/编辑/删除、状态切换
- 程序详情：步骤列表、步骤参数编辑
- 运行控制：启动/暂停/停止、进度监控（使用 MockRunner 模拟）
- 系统设置：基础页面框架
- 国际化：中/英文翻译配置
待完善：设备通信对接、实际硬件控制、U盘导入功能。
UI 设计稿
Stitch 项目链接: https://stitch.withgoogle.com/projects/16230138564963723693
页面截图链接
| 页面 | 功能描述 | 截图链接 |
|---|---|---|
| 首页 - 待机状态 | 状态栏 + 程序列表 + 开始运行按钮 + 瓷套棒确认 | 查看 |
| 首页 - 运行状态 | 实时监控：孔位、步骤、倒计时、进度条、暂停/停止控制 | 查看 |
| 程序管理 - 列表视图 | 程序表格：复选框、编号、名称、状态、批量操作、分页 | 查看 |
| 程序详情 - 步骤配置 | 左侧步骤列表 + 右侧参数表单（孔位、时间、速度等） | 查看 |
| 系统设置 - 控制面板 | 软件升级、语言切换、密码修改、U盘导入 | 查看 |
| 运行完成 - 操作指引 | 成功提示 + 样本滴入说明 + 返回/重运行按钮 | 查看 |
设计规范
- 主色调: #2196F3（蓝色）
- 字体: Inter
- 圆角: 4px（工业控制风格）
- 配色模式: Light + Tonal Spot
- 注意: Stitch 生成的画布尺寸为 2560×2048，实际开发需适配 1024x600 横屏
其他说明
- 需求文档：已确认-污水毒品快检一体机_功能需求文档.md
- 运行设备屏幕尺寸为1024x600(横屏),屏幕密度为200，UI设计必须支持此尺寸