本文档用于指导当前 WMS PDA 项目从 uni-app 迁移到 Flutter，并建立一套适合 AI 协作开发的工程体系。
核心目标：
当前项目是一个基于 uni-app + Vue2 + uView UI 的 PDA 仓储客户端，核心链路如下：
现有系统特点：
Main / NoMain 存在重复页面这意味着 Flutter 迁移不能只做页面翻译，而要顺手完成架构升级。
uni-app 的页面复制逻辑原样搬到 FlutterFlutter 3.xDart 3.xAndroidiOSflutter_riverpodgo_routerdiofreezed + json_serializableshared_preferencesflutter_secure_storageintlloggersentry_flutter推荐采用分层架构：
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 负责跨模块横切能力中间件不是只指网络拦截器，而是整个客户端的“横切能力总线”。
作用：
建议落地方式：
dio 的 Interceptors作用：
建议落地方式：
作用：
示例：
作用：
需要覆盖的动作：
统一能力：
作用：
建议将当前以下数据统一纳入配置域：
作用：
建议首期记录：
日志字段建议：
traceIduserIddeviceIdactionrequestTimeresponseTimestatuserrorCodeerrorMessage作用：
首期无需完整离线化，但架构必须预留：
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 / presentationcoredioshared_preferences功能：
拆分：
AuthPageLoginUseCaseAuthRepositoryServerConfigRepository功能：
拆分：
HomePageFetchMenuUseCaseMenuRepositoryPermissionGuard功能：
拆分：
SettingsPageLoadSettingsUseCaseSaveSettingsUseCaseSettingsRepository功能：
拆分：
ContainerBindingPageMaterialSelectPageScanContainerCodeUseCaseQueryMaterialUseCaseSubmitContainerBindingUseCase功能：
重构原则：
Main / NoMain 双页面复制结构推荐模型：
OrderBindingEntryMode.withOrderListOrderBindingEntryMode.directDetailListAI 适合负责：
AI 不直接负责最终拍板：
每次开发前必须先生成任务卡：
## Task
- 模块：
- 页面：
- 目标：
## Input
- 接口：
- 字段：
- 配置项：
## Output
- 文件列表：
- 交互结果：
- 验收标准：
## Constraints
- 不允许改动：
- 依赖边界：
- 测试要求：
输出物：
输出物：
输出物：
输出物：
输出物：
输出物：
abstract class RequestMiddleware {
Future<RequestContext> onRequest(RequestContext context);
Future<ResponseContext> onResponse(ResponseContext context);
Future<ErrorContext> onError(ErrorContext context);
}
abstract class ActionMiddleware<TInput, TOutput> {
Future<TInput> before(TInput input);
Future<TOutput> after(TOutput output);
Future<void> onError(Object error, StackTrace stackTrace);
}
abstract class RouteGuard {
Future<bool> canActivate(RouteContext context);
}
class SyncTask {
final String id;
final String type;
final Map<String, dynamic> payload;
final int retryCount;
final String status;
}
说明：
SecureStorage：token、敏感标识SharedPreferences：业务设置、UI 偏好、服务器配置LocalDb：后期离线任务、审计日志、缓存明细必须合并现有项目中分裂的配置概念：
serverConfigbusinessConfigfeatureFlagsdeviceConfig禁止继续出现：
覆盖范围：
覆盖范围：
覆盖范围：
必须验证：
devteststagingprod规避：
规避：
规避：
规避：
首批必须完成：
第二批完成：
第三批完成：
这次迁移的正确方向不是“把现有 uni-app 页面改写成 Flutter”，而是：
只要首期把架构、中间件、配置中心、日志链路打稳，后续新增出入库、盘点、上架、下架、AGV、审批流、多仓、多租户，都可以在现有基础上继续扩展，而不需要再次推倒重来。