n160 · /home/joehuang
版本：1.0
生成时间：2025-05-28
项目路径：~/masterplan/
Flutter 移动应用（Android/iOS）
一站式任务管理应用，支持任务创建/追踪/排期、联系人管理、多云同步（WebDAV/Dropbox/OneDrive/GoogleDrive/iCloud等）、AI助手等功能。
| 层级 | 技术方案 |
|---|---|
| 框架 | Flutter 3.x |
| 状态管理 | Provider + Riverpod（混用） |
| 服务定位 | GetIt |
| 本地数据库 | SQLite（sqflite） |
| 同步方案 | 多Provider抽象（Firebase/Supabase/MongoDB/PostgreSQL/Local等） |
| 国际化 | flutter_localizations |
| 依赖注入 | get_it |
| 其他 | uuid, shared_preferences, lpinyin |
┌─────────────────────────────────────────────────────────────┐
│ UI层 │
│ pages/ - 49个页面文件 │
│ home/ - 主页 │
│ tasks/ - 任务列表/详情/编辑 │
│ contacts/ - 联系人列表/详情/表单 │
│ settings/ - 设置页面 │
│ ai/ - AI聊天 │
│ focus/ - 聚焦任务 │
│ health/ - 数据健康 │
│ debug/ - 调试工具 │
│ widgets/ - 47个可复用组件 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 状态管理层 │
│ providers/ - 8个Provider │
│ task_provider.dart - 统一任务状态管理 │
│ focus_task_provider.dart - 聚焦任务（isFocused） │
│ priority_task_provider.dart - 优先任务（isPriority） │
│ scheduling_task_provider.dart - 排期任务 │
│ task_list_provider.dart - 任务列表管理 │
│ localization_provider.dart - 国际化 │
│ weekly_schedule_view_model.dart - 周视图 │
│ refresh_snapshot.dart - 刷新快照 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ services/ - ~100个服务文件 │
│ task_service.dart + mixins - 任务核心业务逻辑 │
│ database/ - SQLite数据库服务 │
│ repository/ - Repository模式实现 │
│ sync/ - 多Provider同步服务 │
│ storage/ - 存储适配器 │
│ streams/ - 流式服务 │
│ notification/ - 通知服务 │
│ export/ - 数据导出 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 数据层 │
│ models/ - 12个数据模型 │
│ task.dart - 任务模型（含层级/Recurrence） │
│ contact.dart - 联系人模型 │
│ sync_metadata.dart - 同步元数据 │
│ task_view.dart - 任务视图 │
│ sub_task_filter.dart - 子任务过滤 │
│ contact_interaction.dart - 联系交互 │
│ database/ - SQLite表结构与迁移 │
└─────────────────────────────────────────────────────────────┘
| 文件 | 职责 |
|---|---|
| task.dart | 核心任务模型，含层级结构、优先级、类型、状态、RecurrenceRule |
| contact.dart | 联系人模型，含多种联系方式、社交账号、评估字段 |
| sync_metadata.dart | 同步元数据 |
| task_view.dart | 任务视图模型 |
| sync_change.dart | 同步变更记录 |
| sub_task_filter.dart | 子任务过滤条件 |
| contact_relation.dart | 联系人关系 |
| contact_option.dart | 联系人选项 |
| task_instance.dart | 任务实例 |
| task_action.dart | 任务动作 |
| models.dart | 统一导出 |
class Task {
String id; // UUID
String title; // 标题
String? description; // 描述
TaskType type; // 任务类型（general/coreProject/continuous/belief/periodic/contact/longTerm/note/outline/diary/habit）
TaskPriority priority; // 优先级（high/medium/low）
TaskUrgency urgency; // 紧急度
TaskSource source; // 来源（goal/plan/contact/system/user/idea/sync）
TaskStatus status; // 状态（notStarted/inProgress/completed/cancelled/deferred/archived）
bool isStarred; // 星标
bool isFocused; // 聚焦
bool isPriority; // 优先
bool isDeleted; // 软删除标记
bool isExpanded; // UI展开状态
DateTime? dueDate; // 截止日期
DateTime? completedDate; // 完成日期
DateTime? startDate; // 开始日期
DateTime? reminderDate; // 提醒日期
String? parentId; // 父任务ID（层级关系）
int level; // 层级深度
int sortOrder; // 排序序号
List<Task> children; // 子任务列表
String? recurrenceRule; // 重复规则（JSON字符串）
RecurrenceRule? parsedRecurrenceRule; // 解析后的重复规则
List<String> tags; // 标签列表
List<String> participants; // 参与者
String? assignee; // 负责人
String? contactId; // 关联联系人ID
String? location; // 位置
int executionCount; // 执行次数
bool hasChildren; // 是否有子任务
DateTime createdAt; // 创建时间
DateTime updatedAt; // 更新时间
}
class Contact {
String id; // UUID
String name; // 姓名
String? gender; // 性别
String? category; // 分类
String? relationType; // 关系类型
String? company; // 公司
String? position; // 职位
String? industry; // 行业
String? city; // 城市
String? province; // 省份
String? country; // 国家
List<PhoneNumber> phoneNumbers; // 电话列表
List<EmailAddress> emailAddresses; // 邮箱列表
List<Address> addresses; // 地址列表
List<SocialMediaAccount> socialMediaAccounts; // 社交账号
List<String> interests; // 兴趣列表
DateTime? birthday; // 生日
DateTime? relationshipStartDate; // 关系开始日期
String? notes; // 备注
int influenceLevel; // 影响层级（1-10）
bool hasCooperationPotential; // 是否有合作潜力
int networkLevel; // 网络层级
int cooperationValue; // 合作价值
String? futureValue; // 未来价值
String? evaluation; // 评估
String? longTermPlan; // 长期计划
String? projectAreas; // 项目领域
double? valueAssessment; // 价值评估
bool isDeleted; // 软删除
DateTime? deletedAt; // 删除时间
DateTime createdAt; // 创建时间
DateTime updatedAt; // 更新时间
}
services/
├── database/ # 数据库层
│ ├── database_service.dart # 数据库服务接口
│ ├── sqlite_database_service.dart # SQLite实现
│ ├── platform_database_helper.dart # 平台辅助
│ ├── migration_manager.dart # 数据库迁移
│ └── sqlite_database.dart # SQLite核心
│
├── repository/ # Repository模式
│ ├── base_repository.dart # 基类
│ ├── task_repository.dart # 任务Repository接口
│ ├── task_repository_impl.dart # 实现
│ ├── task_repository_v2.dart # V2版本
│ ├── on_demand_task_repository.dart # 按需加载
│ ├── priority_task_repository.dart # 优先任务
│ ├── focus_task_repository.dart # 聚焦任务
│ ├── scheduling_task_repository.dart # 排期任务
│ ├── event_bus.dart # 事件总线
│ └── repository_manager.dart # 管理器
│
├── sync/ # 同步服务
│ ├── sync_service.dart # 同步服务接口
│ ├── sync_service_impl.dart # 实现
│ ├── sync_provider.dart # Provider接口
│ ├── sync_enums.dart # 枚举
│ ├── change_tracker.dart # 变更追踪
│ ├── sync_lock_manager.dart # 同步锁
│ ├── pending_changes_manager.dart # 待变更管理
│ ├── sync_retry_handler.dart # 重试处理
│ ├── sync_auditor.dart # 审计
│ ├── sync_metrics.dart # 指标
│ ├── sync_logger.dart # 日志
│ ├── sync_backup_service.dart # 备份
│ ├── sync_migration_service.dart # 迁移
│ ├── local_sync_service.dart # 本地同步
│ ├── sync_exceptions.dart # 异常
│ └── providers/ # 多Provider实现
│ ├── firebase_sync_provider.dart
│ ├── supabase_sync_provider.dart
│ ├── mongodb_sync_provider.dart
│ ├── postgres_sync_provider.dart
│ ├── local_sync_provider.dart
│ ├── dropbox_provider.dart
│ ├── google_drive_provider.dart
│ ├── google_drive_sync_provider.dart
│ ├── onedrive_provider.dart
│ ├── onedrive_sync_provider.dart
│ ├── webdav_provider.dart
│ ├── icloud_sync_provider.dart
│ └── baidu_drive_sync_provider.dart
│
├── storage/ # 存储适配器
│ ├── repository.dart # 存储Repository
│ ├── task_repository.dart # 任务存储
│ ├── contact_repository.dart # 联系人存储
│ └── database_repository_adapter.dart # DB适配器
│
├── streams/ # 流式服务
│ └── task_stream_service.dart # 任务流服务
│
├── task_service.dart # 任务服务核心（~6560行）
│ └── task_service/ # Mixin拆分
│ ├── task_service_query_mixin.dart
│ ├── task_service_hierarchy_mixin.dart
│ ├── task_service_state_mixin.dart
│ ├── task_service_batch_operations_mixin.dart
│ ├── task_service_crud_mixin.dart
│ ├── task_service_filter_mixin.dart
│ ├── task_service_priority_mixin.dart
│ └── task_service_focus_mixin.dart
│
├── notification/ # 通知服务
│ └── notification_service.dart
│
├── export/ # 数据导出
│ └── data_export_service.dart
│
├── service_locator.dart # GetIt服务定位器
├── settings_service.dart # 设置服务
├── localization_provider.dart # 国际化Provider
├── task_filter_service.dart # 任务过滤服务
├── contact_service.dart # 联系人服务
├── sub_task_service.dart # 子任务服务
├── expansion_state_service.dart # 展开状态服务
├── editing_state_service.dart # 编辑状态服务
├── webdav_service.dart # WebDAV服务
├── sync_service.dart # 同步服务
├── note_list_service.dart # 笔记列表服务
└── data_health_facade.dart # 数据健康门面
| 服务 | 职责 |
|---|---|
| TaskService | 任务核心业务逻辑，使用Mixin模式拆分为查询/层级/状态/批量CRUD/过滤/优先级/聚焦 |
| SQLiteDatabaseService | SQLite数据库操作，提供CRUD和事务支持 |
| RepositoryManager | 管理多个Repository实例，提供统一访问入口 |
| SyncService | 统一同步接口，封装多Provider同步逻辑 |
| SettingsService | 应用设置管理（SharedPreferences封装） |
| LocalizationProvider | 多语言支持（简/繁中文、英文等） |
| ContactService | 联系人CRUD和交互记录管理 |
| NotificationService | 任务提醒通知 |
| Provider | 职责 | 依赖 |
|---|---|---|
| TaskProvider | 统一任务状态管理，CRUD操作，派生查询（按日期/优先级/聚焦等） | OnDemandTaskRepository, GlobalEventBus |
| FocusTaskProvider | 聚焦任务（isFocused=true && isPriority=false） | TaskService |
| PriorityTaskProvider | 优先任务（isPriority=true） | TaskService |
| SchedulingTaskProvider | 排期任务（按日期查询） | SchedulingTaskRepository, EventBus |
| TaskListProvider | 任务列表管理 | TaskService |
| LocalizationProvider | 国际化语言/地区管理 | SharedPreferences |
| WeeklyScheduleViewModel | 周视图模式 | - |
| RefreshSnapshot | 刷新状态快照 | - |
┌─────────────────────────────┐
│ TaskService (核心) │
│ (mixin: Query/CRUD/Filter) │
└──────────────┬──────────────┘
│
┌─────────┼─────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌─────────────────┐
│Focus │ │Priority│ │Scheduling │
│Task │ │Task │ │Task │
│Provider│ │Provider│ │Provider │
└────────┘ └────────┘ └────────┬────────┘
│
▼
┌──────────────────┐
│Scheduling │
│TaskRepository │
└──────────────────┘
│
┌──────────┴──────────┐
▼ ▼
┌────────────┐ ┌────────────┐
│TaskService │ │ EventBus │
│(内存快照) │ │(事件总线) │
└────────────┘ └────────────┘
// 路由常量
static const String focus = '/focus';
static const String tasks = '/tasks';
static const String taskDetail = '/tasks/detail';
static const String contacts = '/contacts';
static const String contactDetail = '/contacts/detail';
static const String contactForm = '/contacts/form';
static const String settings = '/settings';
static const String health = '/health';
static const String firebaseTest = '/firebase-test';
static const String aiChat = '/ai-chat';
static const String llmSettings = '/settings/llm';
| 路由 | 页面 | 参数 |
|---|---|---|
| /focus | TaskFocusPriorityPage | - |
| /tasks | TaskListPage | - |
| /tasks/detail | TaskDetailPage | Task对象 |
| /contacts | ContactListPage | - |
| /contacts/detail | ContactDetailPage | Contact对象 |
| /contacts/form | ContactFormPage | Contact?(可选) |
| /settings | SettingsPage | - |
| /settings/llm | LlmSettingsPage | - |
| /health | HealthHomePage | - |
| /firebase-test | FirebaseTestPage | - |
| /ai-chat | AiChatPage | String(prefill) |
AppRouter.navigateToTaskDetail(BuildContext, Task);
AppRouter.navigateToContactDetail(BuildContext, String contactId);
AppRouter.navigateToContactForm(BuildContext, {Contact? contact});
main()
│
▼
[1] WidgetsFlutterBinding.ensureInitialized()
│
▼
[2] setupServiceLocator() // GetIt注册
│ ├── SharedPreferences
│ ├── SettingsService
│ ├── LocalizationProvider
│ ├── SQLiteDatabaseService
│ ├── TaskService
│ ├── RepositoryManager
│ └── SyncService
│
▼
[3] databaseService.initialize() // 数据库初始化
│
▼
[4] settingsService.initialize() // 设置加载
│
▼
[5] taskService.loadTasksProgressively() // 渐进式加载
│ ├── Phase1: 优先任务(50条)
│ ├── Phase2: 今日任务(聚焦+截止)
│ └── Phase3: 后台加载全部
│
▼
[6] MultiProvider注册 // 14个Provider
│
▼
[7] runApp(StartupApp + MyApp)
│
▼
[8] 首帧渲染后（postFrameCallback）
│ ├── autoSyncOnStart() // 自动同步
│ ├── startAutoSync() // 持续同步监听
│ └── _checkDateChangeAndCopyFocusTasks()
│
▼
[9] 延迟5秒：DataHealthFacade.cleanTempIds() // TEMP_ID清理
用户操作：点击新建任务
│
▼
TaskEditPage → 用户填写表单
│
▼
TaskProvider.createTask(Task)
│
├── _repository.create(task) // 保存到数据库
│
├── _eventBus.emit(taskCreated) // 发布事件
│
├── _reload() // 重新加载全部数据
│
└── notifyListeners() // 通知UI刷新
SyncService.sync()
│
├── SyncLockManager.acquireLock()
│
├── ChangeTracker.getChanges() // 获取变更
│
├── FOR each SyncProvider:
│ ├── FirebaseSyncProvider
│ ├── SupabaseSyncProvider
│ ├── MongoDBSyncProvider
│ ├── PostgreSQLSyncProvider
│ ├── LocalSyncProvider
│ ├── DropboxProvider
│ ├── GoogleDriveProvider
│ ├── OneDriveProvider
│ ├── WebDAVProvider
│ ├── iCloudSyncProvider
│ └── BaiduDriveSyncProvider
│
├── ConflictResolution.resolve() // 冲突处理
│
├── PendingChangesManager.flush() // 推送待变更
│
└── SyncLockManager.releaseLock()
TaskProvider.updateTaskHierarchy(taskId, newParentId, newLevel)
│
├── _repository.updateHierarchy() // 更新DB中的层级关系
│
├── _eventBus.emit(taskHierarchyChanged)
│
└── _reload() // 重新加载
┌────────────────────────────────────────────────────────────────┐
│ pages/ │
│ (TaskListPage, TaskDetailPage, ContactListPage, SettingsPage) │
└──────────────────────────────┬────────────────────────────────┘
│ context.watch/read
▼
┌────────────────────────────────────────────────────────────────┐
│ widgets/ │
│ (TaskCard, ContactTile, SyncStatusIndicator) │
└──────────────────────────────┬────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ providers/ │
│ TaskProvider/FocusTaskProvider/PriorityTaskProvider │
│ SchedulingTaskProvider/TaskListProvider │
│ LocalizationProvider │
└──────────────────────────────┬────────────────────────────────┘
│ 依赖注入
▼
┌────────────────────────────────────────────────────────────────┐
│ services/ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TaskService │ │
│ │ mixin: QueryMixin/HierarchyMixin/StateMixin/CRUDMixin │ │
│ │ FilterMixin/PriorityMixin/FocusMixin │ │
│ └─────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────┴────────┐ ┌──────────────┐ │
│ │SettingsService│ │ContactService │ │ SyncService │ │
│ └──────────────┘ └───────────────┘ └──────┬───────┘ │
│ │ │
│ ┌────────────────────────────────────────────┼───────────┐ │
│ │ RepositoryManager │ │ │
│ │ ┌─────────────────┐ ┌──────────────────┼───────┐ │ │
│ │ │ OnDemandTask │ │ SchedulingTask │ │ │ │
│ │ │ Repository │ │ Repository │ │ │ │
│ │ └────────┬────────┘ └────────┬─────────┘ │ │ │
│ └───────────┼────────────────────┼─────────────────┼───┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SQLiteDatabaseService │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ DatabaseService (接口) │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ models/ │
│ Task, Contact, SyncMetadata, TaskView, SubTaskFilter │
└────────────────────────────────────────────────────────────────┘
// 阶段1：必须串行
await SharedPreferences.getInstance()
// 阶段2：可并行（无依赖）
await Future.wait([
_initSettingsService(), // SettingsService
_initLocalizationProvider(),// LocalizationProvider
_initDatabaseService(), // SQLiteDatabaseService
])
// 阶段3：依赖服务（串行）
await _initDependentServices()
// - EditingStateService
// - TaskService
// - RepositoryManager
// - SyncService
目的：解耦数据访问，支持多种存储后端
TaskRepository (接口)
├── OnDemandTaskRepository (按需加载)
├── PriorityTaskRepository (优先任务)
├── FocusTaskRepository (聚焦任务)
├── SchedulingTaskRepository (排期任务)
└── TaskRepositoryImpl (SQLite实现)
好处：
- 测试时可用Mock Repository
- 可切换不同存储后端
- 统一数据访问接口
TaskService使用Mixin而非extends的原因：
class TaskService extends ChangeNotifier
with
TaskServiceQueryMixin, // 查询
TaskServiceHierarchyMixin, // 层级
TaskServiceStateMixin, // 状态
TaskServiceBatchOperationsMixin, // 批量
TaskServiceCRUDMixin, // CRUD
TaskServiceFilterMixin, // 过滤
TaskServicePriorityMixin, // 优先级
TaskServiceFocusMixin {} // 聚焦
多Provider抽象允许切换不同云服务：
SyncService (门面)
│
├── SyncProvider (接口)
│ ├── FirebaseSyncProvider
│ ├── SupabaseSyncProvider
│ ├── MongoDBSyncProvider
│ ├── PostgreSQLSyncProvider
│ ├── LocalSyncProvider
│ ├── DropboxProvider
│ ├── GoogleDriveProvider
│ ├── OneDriveProvider
│ ├── WebDAVProvider
│ ├── iCloudSyncProvider
│ └── BaiduDriveSyncProvider
│
├── ChangeTracker (变更追踪)
├── SyncLockManager (同步锁，防止并发)
└── ConflictResolution (冲突解决)
MasterPlan 是一个功能完善的任务管理应用，采用清晰的分层架构：
核心设计亮点：
1. TaskService的Mixin拆分模式
2. 多Provider同步抽象架构
3. Repository模式的灵活数据访问
4. 渐进式加载和内存hydrate的性能优化