From 5f9cb06a1e4ab052cf2087456b8520a2475b9732 Mon Sep 17 00:00:00 2001 From: Developer <91611@user.local> Date: Fri, 5 Jun 2026 10:07:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E6=9B=B4=E6=96=B0=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E4=B8=BA=E5=BC=80=E5=8F=91=E8=80=85?= =?UTF-8?q?=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将 README.md 重命名为 AGENTS.md，提供项目开发指导 - 添加项目概述，说明污水毒品快检一体机控制软件功能 - 添加开发命令说明，包括获取依赖、运行、构建等常用命令 - 详细描述项目架构，包含 core、features、shared 三层结构 - 补充技术栈信息，明确状态管理、路由、数据持久化方案 - 添加核心数据模型说明，包含 Program 和 Step 实体定义 - 说明关键 Provider 和数据库表结构设计 - 补充国际化配置和代码规范要求 - 详细描述各功能模块，包括首页、程序管理、详情、设置模块 - 添加步骤参数说明表，明确各操作参数取值范围 - 更新当前实现状态，标注已完成和待完善功能 - 添加 UI 设计稿链接和页面截图参考 - 补充设计规范要求，包括配色、字体、适配等说明 --- README.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 160 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c9a82f9..6a2232a 100644 --- 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设计必须支持此尺寸 \ No newline at end of file