# AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

## 项目概述

污水毒品快检一体机控制软件（kuaishai2），用于控制设备运行程序、管理程序配置、监控运行状态。

**包名**: com.xiarui.kuaishai2

## 开发命令

```bash
# 获取依赖
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

### 页面截图链接

| 页面 | 功能描述 | 截图链接 |
|------|----------|----------|
| 首页 - 待机状态 | 状态栏 + 程序列表 + 开始运行按钮 + 瓷套棒确认 | [查看](https://lh3.googleusercontent.com/aida/ADBb0ujbe00elAXxTbD-KomnaatYJ40X-ubwTDSaI--jR_FRjPow3DJn7S61WpX9NxIMfgAyup6KXC_5qQWeZi0G9qQakQpvszL-OiaTU0C_yQ5FB-E1UMrystcYL0inmiky1Z2Ai-18NSYAdr0dJ6bbTp_dmJ4-JgmK0bjqdoUSnqlzo_Q1SwyNmbJb8WdNTKIUoXNudgLOCZURLWzONviyPgs9CqlxS1KUvopuxJymQF26kwxFO33lY6_vdLzD) |
| 首页 - 运行状态 | 实时监控：孔位、步骤、倒计时、进度条、暂停/停止控制 | [查看](https://lh3.googleusercontent.com/aida/ADBb0uj1bjMG6Fu-6-yvfL-Y51mJws-NBwlkX-GCbBBjLjb-4gNvMB_y8AESOu7X-UF_SHggCttMNpY6g88WgGOSJjw-1NOyTyigDBRInEwawYt8aXSGIGknLVw6zK_99aFnfturjzoYySuHBhKP2r34XWvfAO1g0e-as3hWBOaJW0gb2w8DSLmv3MpGLvsedJNq4SQFhl50LtNFM_zCMKjv-NtqyCE3y1vndNxnxCrJUy_BHvh4XHCahf18UnOU) |
| 程序管理 - 列表视图 | 程序表格：复选框、编号、名称、状态、批量操作、分页 | [查看](https://lh3.googleusercontent.com/aida/ADBb0ujE1ZBh5_Gn-yyy1bfU-U_xCeGHREsycgxyAlWBKzWbhFzvlusSWhCEY1u6RBRqVk5XZ49x8Ljpe4yXcS5e3q_jgGMGpcd1CN0RxX0nU6D75O056euNV7fY9cBNtTVGXibmM7Am1uj5uxV7TLbW8c_ix8WubRhn0gYFU6L87b80N6Zl-2T3lmBZsp98jwSsUXP3RqHk6CwMLoQ9LYcLRQTU5Dh5XD1e9aXus9I9pDgj-ZMUsFcZJA7XnJ0y) |
| 程序详情 - 步骤配置 | 左侧步骤列表 + 右侧参数表单（孔位、时间、速度等） | [查看](https://lh3.googleusercontent.com/aida/ADBb0ujEyurJOmwUkZx3ysQMSCk4pXU9_6Jh6bsEMhwlwyC88SQZ0hCFRHMhKADFecHdLXG3D-A5Hp3Avw25j1ivrP2CyTTdeXgd4QPCARNZetrezcL1iy0b7RYsVTTnXnzIFX846pRC_rxgbh8DdqMAiHPz8Q94JciAFCAokQfduFmDWw3Wzhj_P0KtlL8UmEIJNzGFi9ySTGo6eKmz6lfdfQ6VMowhYR5Qy8VGZi8qTLlXqFSU9f-dZepaJWs) |
| 系统设置 - 控制面板 | 软件升级、语言切换、密码修改、U盘导入 | [查看](https://lh3.googleusercontent.com/aida/ADBb0ugIEqBuSXmwYtQkPXXIJ7qBdL69VyQdTRzTyXjc5M6THuTBnbJlLyIDmvo7qfTz_RwjwZE_czzN6dyR_ydqk2Er5hNYduPLypOLqqR7I2sHaKDIvCeole91oJIVkAcnfJkWQJJPgaIhqfysMV4mrsHD0rhYJpngLorfE9WMl11tG9MPz9_E8XcmwaFqXqtYvxHeBsnvSNtIQfkX9S5QfnYtOiAsnUKioY3GpVvjK6bV4PYIfCMMHXv5koS8) |
| 运行完成 - 操作指引 | 成功提示 + 样本滴入说明 + 返回/重运行按钮 | [查看](https://lh3.googleusercontent.com/aida/ADBb0ujh5-3mBPpjWkSRHGOzNRQuusc4O7p_Kov2dbd3iiJmOHlElBb9-gPWC5bnfnRuDbhIbZDhxQhTfVkRpUhQU5nMGa5y7NpV4efvG6ZF0Bx4aVdm4HJ-o2Qca-alJuSfgsggJgbZ3QptA_cAXx-VfG79sHB1zUvRDHpPkLSu0lePhmjaR6m6-pwR42Pib7OLSNqS6V9208w7HoGCX1cPC6pH-hi8rZrMbMmbk2p-pTd2tJebNsow9aLb6bLJ) |

### 设计规范

- **主色调**: #2196F3（蓝色）
- **字体**: Inter
- **圆角**: 4px（工业控制风格）
- **配色模式**: Light + Tonal Spot
- **注意**: Stitch 生成的画布尺寸为 2560×2048，实际开发需适配 1024x600 横屏

---

## 其他说明

1. 需求文档：[已确认-污水毒品快检一体机_功能需求文档.md](docs/%E5%B7%B2%E7%A1%AE%E8%AE%A4-%E6%B1%A1%E6%B0%B4%E6%AF%92%E5%93%81%E5%BF%AB%E6%A3%80%E4%B8%80%E4%BD%93%E6%9C%BA_%E5%8A%9F%E8%83%BD%E9%9C%80%E6%B1%82%E6%96%87%E6%A1%A3.md)
2. 运行设备屏幕尺寸为1024x600(横屏),屏幕密度为200，UI设计必须支持此尺寸