#

zhou zhou

昨天 51998ca88b0c4f4c6b124971dec7a262a9d32aab

#

 docs/flutter_ai_dev_guide.md

New file
@@ -0,0 +1,768 @@
# WMS Flutter AI 开发文档

## 1. 文档目标

本文档用于指导当前 WMS PDA 项目从 `uni-app` 迁移到 `Flutter`，并建立一套适合 AI 协作开发的工程体系。

核心目标：

- 从 0 开始搭建一套可长期演进的 Flutter 客户端工程
- 首期覆盖当前核心业务：登录、首页、设置、非订单组托、订单组托
- 中间件一次设计到位，兼容后期业务复杂化、多人协作、灰度发布、离线补偿、审计追踪
- 建立 AI 可稳定参与的开发流程，降低后续新增需求的沟通和返工成本

---

## 2. 当前项目背景

当前项目是一个基于 `uni-app + Vue2 + uView UI` 的 PDA 仓储客户端，核心链路如下：

1. 登录
2. 权限菜单首页
3. 设置页
4. 非订单组托
5. 订单组托
6. 多语言支持

现有系统特点：

- 登录态、服务端地址、业务开关依赖本地缓存
- 请求层已有统一拦截器
- 页面结构偏“业务页直连接口”
- `Main / NoMain` 存在重复页面
- 已经出现“业务配置驱动页面行为”的趋势

这意味着 Flutter 迁移不能只做页面翻译，而要顺手完成架构升级。

---

## 3. 迁移原则

### 3.1 业务原则

- 首期只迁移当前稳定核心业务，不同时重构后端
- 迁移期间保证旧版可回退
- 优先保证 PDA 扫码、录入、提交链路稳定

### 3.2 技术原则

- 先建基础设施，再开发业务页面
- 先统一数据模型，再开发交互逻辑
- 先定义中间件链路，再开发复杂流程
- 避免把 `uni-app` 的页面复制逻辑原样搬到 Flutter

### 3.3 AI 协作原则

- 所有需求必须先形成结构化任务卡
- 所有 AI 生成代码必须经过规则校验和人工验收
- 所有模块都必须有明确输入、输出、边界
- AI 只在稳定边界内增量开发，不直接跨层乱改

---

## 4. 目标技术栈

## 4.1 基础栈

- `Flutter 3.x`
- `Dart 3.x`
- 目标平台：`Android`
- 后续可扩展：`iOS`

## 4.2 推荐库

- 状态管理：`flutter_riverpod`
- 路由：`go_router`
- 网络请求：`dio`
- 数据模型：`freezed` + `json_serializable`
- 本地存储：`shared_preferences`
- 安全存储：`flutter_secure_storage`
- 国际化：`intl`
- 日志：`logger`
- 崩溃与监控：`sentry_flutter`
- 二维码/扫码：按 PDA 硬件方案接入，优先保留键盘输入兼容模式

## 4.3 不建议的做法

- 不建议首期直接上过重的微前端式拆分
- 不建议只靠单一全局 Provider 管整个应用
- 不建议所有业务逻辑都写在 Widget / Controller 中
- 不建议跳过中间件层直接把 Dio 当唯一基础设施

---

## 5. 总体架构

推荐采用分层架构：

```text
Presentation
  ├─ Pages
  ├─ Widgets
  ├─ ViewModels / Notifiers
Application
  ├─ UseCases
  ├─ DTO Mappers
  ├─ Workflow Coordinators
Domain
  ├─ Entities
  ├─ Value Objects
  ├─ Repository Contracts
Infrastructure
  ├─ API Clients
  ├─ Local Storage
  ├─ Device Services
  ├─ Repositories
Middleware
  ├─ Request Middleware
  ├─ Auth Middleware
  ├─ Route Middleware
  ├─ Action Middleware
  ├─ Sync Middleware
  ├─ Audit Middleware
```

说明：

- `Presentation` 只负责展示、输入、页面状态
- `Application` 负责流程编排，不直接依赖页面
- `Domain` 负责业务规则抽象
- `Infrastructure` 负责接口、存储、设备、日志等实现
- `Middleware` 负责跨模块横切能力

---

## 6. 一步到位的中间件设计

中间件不是只指网络拦截器，而是整个客户端的“横切能力总线”。

### 6.1 必须首期落地的中间件

#### 6.1.1 Request Middleware

作用：

- 统一追加 baseUrl
- token 注入
- header 注入
- 请求超时控制
- 接口重试策略
- 幂等控制
- 请求日志输出

建议落地方式：

- 基于 `dio` 的 `Interceptors`

#### 6.1.2 Auth Middleware

作用：

- 登录态校验
- token 失效自动跳登录
- 刷新 token 预留
- 匿名路由白名单

建议落地方式：

- 请求拦截 + 路由守卫双层控制

#### 6.1.3 Route Middleware

作用：

- 页面访问鉴权
- 首页动态菜单权限过滤
- 环境检查
- 必填前置条件检查

示例：

- 未登录不可进入业务页
- 未配置服务端地址不可发起业务请求
- 未选择订单不可进入订单组托详情页

#### 6.1.4 Action Middleware

作用：

- 对关键业务动作统一增强
- 适合后期复杂流程接入审批、校验、补偿

需要覆盖的动作：

- 登录
- 扫码入库
- 查询物料
- 查询订单
- 提交组托
- 重置操作
- 设置保存

统一能力：

- 参数校验
- 埋点
- 日志
- 防抖
- 权限判定
- 规则校验
- 失败补偿入口

#### 6.1.5 Config Middleware

作用：

- 管理服务端配置
- 管理业务开关
- 管理页面字段显示配置
- 管理灰度开关
- 管理多租户差异配置

建议将当前以下数据统一纳入配置域：

- 服务地址
- 端口
- 项目标识
- 是否复核
- 是否多选
- 条码切分规则
- 字段显示配置
- 字段编辑配置

#### 6.1.6 Audit Middleware

作用：

- 记录关键动作日志
- 支持问题追踪
- 兼容后期审计要求

建议首期记录：

- 登录
- 菜单加载
- 关键查询
- 组托提交
- 设置修改

日志字段建议：

- `traceId`
- `userId`
- `deviceId`
- `action`
- `requestTime`
- `responseTime`
- `status`
- `errorCode`
- `errorMessage`

#### 6.1.7 Sync Middleware

作用：

- 为后期离线场景预留
- 为弱网重试、失败补偿、延迟提交预留

首期无需完整离线化，但架构必须预留：

- 本地任务队列
- 提交状态标记
- 重试机制
- 冲突处理策略

### 6.2 后期可扩展中间件

- Feature Flag Middleware
- Workflow Middleware
- Approval Middleware
- Rule Engine Middleware
- Notification Middleware
- Device Capability Middleware

---

## 7. 模块拆分方案

```text
lib/
  app/
    bootstrap/
    router/
    theme/
    l10n/
  core/
    constants/
    errors/
    middleware/
    network/
    storage/
    logging/
    utils/
    widgets/
  domain/
    auth/
    menu/
    settings/
    container_binding/
    order_binding/
  application/
    auth/
    menu/
    settings/
    container_binding/
    order_binding/
  infrastructure/
    auth/
    menu/
    settings/
    container_binding/
    order_binding/
    device/
  presentation/
    auth/
    home/
    settings/
    container_binding/
    order_binding/
```

模块边界要求：

- 每个业务域都必须有自己的 `domain / application / infrastructure / presentation`
- 跨域共享能力必须放 `core`
- 禁止页面直接调用 `dio`
- 禁止页面直接读写 `shared_preferences`

---

## 8. 当前业务到 Flutter 的映射

### 8.1 auth

功能：

- 登录
- 记住账号
- 语言切换
- 服务端地址配置

拆分：

- `AuthPage`
- `LoginUseCase`
- `AuthRepository`
- `ServerConfigRepository`

### 8.2 home

功能：

- 动态菜单
- 权限过滤
- 默认菜单兜底

拆分：

- `HomePage`
- `FetchMenuUseCase`
- `MenuRepository`
- `PermissionGuard`

### 8.3 settings

功能：

- 业务开关
- 条码截取规则
- 字段显示配置
- 字段编辑配置

拆分：

- `SettingsPage`
- `LoadSettingsUseCase`
- `SaveSettingsUseCase`
- `SettingsRepository`

### 8.4 container_binding

功能：

- 托盘扫码
- 物料扫码
- 物料详情编辑
- 组托提交

拆分：

- `ContainerBindingPage`
- `MaterialSelectPage`
- `ScanContainerCodeUseCase`
- `QueryMaterialUseCase`
- `SubmitContainerBindingUseCase`

### 8.5 order_binding

功能：

- 订单列表模式
- 全部明细模式
- 多选
- 复核
- 组托提交

重构原则：

- 不保留 `Main / NoMain` 双页面复制结构
- 统一为一个订单组托模块，通过模式参数控制

推荐模型：

- `OrderBindingEntryMode.withOrderList`
- `OrderBindingEntryMode.directDetailList`

---

## 9. AI 协作开发规范

### 9.1 AI 的职责

AI 适合负责：

- 页面骨架生成
- DTO / Entity / Mapper 生成
- UseCase 模板生成
- Riverpod Provider 模板生成
- 测试样板生成
- 文档同步更新

AI 不直接负责最终拍板：

- 业务规则真值
- 安全策略真值
- 发布决策
- 复杂异常流程验收

### 9.2 AI 任务卡模板

每次开发前必须先生成任务卡：

```md
## Task
- 模块：
- 页面：
- 目标：

## Input
- 接口：
- 字段：
- 配置项：

## Output
- 文件列表：
- 交互结果：
- 验收标准：

## Constraints
- 不允许改动：
- 依赖边界：
- 测试要求：
```

### 9.3 AI 开发流程

1. 先读模块文档
2. 再读任务卡
3. 再读接口契约
4. 再生成代码
5. 生成人工验收清单
6. 更新文档和测试

### 9.4 AI 代码验收门槛

- 能编译
- 有空安全
- 不跨层调用
- 不把业务逻辑堆到 Widget
- Provider 生命周期清晰
- DTO 与实体边界清晰
- 至少有基本测试或验收步骤

---

## 10. 开发阶段计划

### 阶段 0：基础准备

输出物：

- Flutter 工程初始化
- lint 规则
- 目录结构
- 路由骨架
- 主题和国际化骨架
- 中间件骨架

### 阶段 1：基础设施

输出物：

- Dio 网络层
- 请求中间件
- Auth 中间件
- 配置仓库
- 安全存储
- 日志系统

### 阶段 2：基础模块

输出物：

- 登录模块
- 首页模块
- 设置模块

### 阶段 3：核心业务

输出物：

- 非订单组托
- 订单组托统一模块
- 多选与复核

### 阶段 4：增强能力

输出物：

- 埋点
- 审计日志
- 音效和震动
- 失败重试
- 弱网提示

### 阶段 5：测试与上线

输出物：

- 回归测试清单
- PDA 设备测试清单
- 灰度发布方案
- 回滚方案

---

## 11. 中间件接口建议

### 11.1 RequestMiddleware

```dart
abstract class RequestMiddleware {
  Future<RequestContext> onRequest(RequestContext context);
  Future<ResponseContext> onResponse(ResponseContext context);
  Future<ErrorContext> onError(ErrorContext context);
}
```

### 11.2 ActionMiddleware

```dart
abstract class ActionMiddleware<TInput, TOutput> {
  Future<TInput> before(TInput input);
  Future<TOutput> after(TOutput output);
  Future<void> onError(Object error, StackTrace stackTrace);
}
```

### 11.3 RouteGuard

```dart
abstract class RouteGuard {
  Future<bool> canActivate(RouteContext context);
}
```

### 11.4 SyncTask

```dart
class SyncTask {
  final String id;
  final String type;
  final Map<String, dynamic> payload;
  final int retryCount;
  final String status;
}
```

说明：

- 中间件接口必须轻量、稳定、少业务语义
- 业务特有规则写在 UseCase 或 Rule 层，不直接写死到中间件

---

## 12. 数据与配置策略

### 12.1 存储分层

- `SecureStorage`：token、敏感标识
- `SharedPreferences`：业务设置、UI 偏好、服务器配置
- `LocalDb`：后期离线任务、审计日志、缓存明细

### 12.2 配置模型统一

必须合并现有项目中分裂的配置概念：

- 服务端配置：`serverConfig`
- 业务配置：`businessConfig`
- 功能开关：`featureFlags`
- 设备配置：`deviceConfig`

禁止继续出现：

- 多套命名接近但含义重叠的缓存 key

---

## 13. 测试策略

### 13.1 单元测试

覆盖范围：

- UseCase
- Repository
- Mapper
- 中间件

### 13.2 组件测试

覆盖范围：

- 登录表单
- 设置项渲染
- 明细卡片
- 底部操作栏

### 13.3 集成测试

覆盖范围：

- 登录到首页
- 托盘扫码到组托提交
- 订单明细到组托提交
- 多选流程
- 配置切换后行为变化

### 13.4 真机测试

必须验证：

- PDA 扫码枪输入
- 软键盘兼容
- 弱网超时
- 连续扫码
- 多语言切换
- 屏幕适配

---

## 14. 发布与运维建议

### 14.1 环境划分

- `dev`
- `test`
- `staging`
- `prod`

### 14.2 发布要求

- 支持环境切换
- 支持灰度用户
- 支持日志追踪
- 支持快速回滚

### 14.3 监控建议

- 接口错误率
- 登录失败率
- 组托提交失败率
- 页面崩溃率
- 设备型号分布

---

## 15. 风险与规避

### 风险 1：直接照搬旧页面，导致 Flutter 项目继续重复

规避：

- 先做统一模块设计，再开始开发

### 风险 2：中间件只做网络拦截，后期复杂业务接不住

规避：

- 首期同时落地 Request、Auth、Route、Action、Config、Audit、Sync 七类中间件

### 风险 3：AI 一次生成过多代码，质量不可控

规避：

- 小任务卡开发
- 模块内闭环验收
- 分层校验

### 风险 4：配置项越来越多，最终失控

规避：

- 从第一天开始建立统一配置模型和版本化迁移策略

---

## 16. 第一版落地清单

首批必须完成：

- Flutter 工程初始化
- 路由与主题
- 国际化骨架
- Dio + 请求中间件
- 登录态管理
- 配置中心
- 日志与 traceId
- 登录页
- 首页
- 设置页

第二批完成：

- 非订单组托
- 订单组托统一模块
- 多选
- 复核
- 提交组托

第三批完成：

- 审计日志
- 同步任务队列
- 灰度开关
- 崩溃监控

---

## 17. 结论

这次迁移的正确方向不是“把现有 uni-app 页面改写成 Flutter”，而是：

- 用 Flutter 重建客户端基础设施
- 用中间件把复杂业务的横切能力提前设计好
- 用模块化分层承接长期演进
- 用 AI 协作流程提升开发速度，但不牺牲工程边界

只要首期把架构、中间件、配置中心、日志链路打稳，后续新增出入库、盘点、上架、下架、AGV、审批流、多仓、多租户，都可以在现有基础上继续扩展，而不需要再次推倒重来。