kuaishai2/AGENTS.md

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，实际开发需适配 1920×1080 横屏

---

其他说明

1. 需求文档：已确认-污水毒品快检一体机_功能需求文档.md
2. 运行设备屏幕尺寸为1920*1080(横屏),UI设计必须支持此尺寸