5f9cb06a1e
- 将 README.md 重命名为 AGENTS.md，提供项目开发指导 - 添加项目概述，说明污水毒品快检一体机控制软件功能 - 添加开发命令说明，包括获取依赖、运行、构建等常用命令 - 详细描述项目架构，包含 core、features、shared 三层结构 - 补充技术栈信息，明确状态管理、路由、数据持久化方案 - 添加核心数据模型说明，包含 Program 和 Step 实体定义 - 说明关键 Provider 和数据库表结构设计 - 补充国际化配置和代码规范要求 - 详细描述各功能模块，包括首页、程序管理、详情、设置模块 - 添加步骤参数说明表，明确各操作参数取值范围 - 更新当前实现状态，标注已完成和待完善功能 - 添加 UI 设计稿链接和页面截图参考 - 补充设计规范要求，包括配色、字体、适配等说明
166 lines
7.3 KiB
Markdown
166 lines
7.3 KiB
Markdown
# 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，实际开发需适配 1920×1080 横屏
|
||
|
||
---
|
||
|
||
## 其他说明
|
||
|
||
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设计必须支持此尺寸 |