docs(readme): 更新项目文档为开发者指南

- 将 README.md 重命名为 AGENTS.md，提供项目开发指导 - 添加项目概述，说明污水毒品快检一体机控制软件功能 - 添加开发命令说明，包括获取依赖、运行、构建等常用命令 - 详细描述项目架构，包含 core、features、shared 三层结构 - 补充技术栈信息，明确状态管理、路由、数据持久化方案 - 添加核心数据模型说明，包含 Program 和 Step 实体定义 - 说明关键 Provider 和数据库表结构设计 - 补充国际化配置和代码规范要求 - 详细描述各功能模块，包括首页、程序管理、详情、设置模块 - 添加步骤参数说明表，明确各操作参数取值范围 - 更新当前实现状态，标注已完成和待完善功能 - 添加 UI 设计稿链接和页面截图参考 - 补充设计规范要求，包括配色、字体、适配等说明
2026-06-05 10:07:36 +08:00
parent 8c2e26ec87
commit 5f9cb06a1e
1 changed files with 160 additions and 11 deletions
--- a/README.md
+++ b/README.md
@@ -1,17 +1,166 @@
-# kuaishai2
+# AGENTS.md

-A new Flutter project.
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

-## Getting Started
+## 项目概述

-This project is a starting point for a Flutter application.
+污水毒品快检一体机控制软件（kuaishai2），用于控制设备运行程序、管理程序配置、监控运行状态。

-A few resources to get you started if this is your first Flutter project:
+**包名**: com.xiarui.kuaishai2

- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
+## 开发命令

-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+```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设计必须支持此尺寸