# 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 onRequest(RequestContext context); Future onResponse(ResponseContext context); Future onError(ErrorContext context); } ``` ### 11.2 ActionMiddleware ```dart abstract class ActionMiddleware { Future before(TInput input); Future after(TOutput output); Future onError(Object error, StackTrace stackTrace); } ``` ### 11.3 RouteGuard ```dart abstract class RouteGuard { Future canActivate(RouteContext context); } ``` ### 11.4 SyncTask ```dart class SyncTask { final String id; final String type; final Map 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、审批流、多仓、多租户，都可以在现有基础上继续扩展，而不需要再次推倒重来。