# 待办事项四象限拖拽实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 实现四象限待办页面的拖拽排序和跨象限移动功能

**Architecture:** 使用 Flutter `LongPressDraggable` + `DragTarget` 实现拖拽，`AnimatedContainer` 实现排序动画，乐观更新模式同步后端

**Tech Stack:** Flutter, go_router, provider/state management

---

## 文件结构

```
apps/lib/features/todo/
├── ui/screens/todo_quadrants_screen.dart  (修改: 添加拖拽状态管理)
├── ui/widgets/
│   └── todo_drag_item.dart  (创建: 可拖拽待办项组件)
└── data/todo_api.dart  (检查: 确认 API 支持更新 priority)
```

---

## 前置检查

- [ ] **Step 1: 检查 TodoApi 支持更新 priority**

文件: `apps/lib/features/todo/data/todo_api.dart`

```dart
// 确认有 updateTodo 方法支持更新 priority
Future<TodoResponse> updateTodo(String id, {int? priority, ...})
```

---

## Task 1: 添加拖拽状态管理

**文件:**
- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart:26-40`

- [ ] **Step 1: 添加拖拽相关状态和回调**

在 `_TodoQuadrantsScreenState` 中添加:

```dart
class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
  // ... existing states ...
  
  // 拖拽状态
  String? _draggingTodoId;
  int? _dragTargetQuadrant; // 1, 2, 3
  int? _dragInsertIndex;     // 插入位置索引
  
  // 辅助方法
  bool get _isDragging => _draggingTodoId != null;
  
  void _onDragStart(String todoId) {
    setState(() {
      _draggingTodoId = todoId;
    });
  }
  
  void _onDragEnd() {
    setState(() {
      _draggingTodoId = null;
      _dragTargetQuadrant = null;
      _dragInsertIndex = null;
    });
  }
  
  void _onDragEnterQuadrant(int quadrant) {
    setState(() {
      _dragTargetQuadrant = quadrant;
    });
  }
  
  void _onDragUpdateInsertIndex(int index) {
    setState(() {
      _dragInsertIndex = index;
    });
  }
  
  Future<void> _onDrop(String todoId, int targetQuadrant, int insertIndex) async {
    // 实现乐观更新 + 后端同步
  }
}
```

- [ ] **Step 2: 将 TodoDragItem 回调传入正确的 State 方法**

在 `_buildQuadrant` 构建 TodoDragItem 时传入：

```dart
TodoDragItem(
  todo: item,
  quadrant: quadrantValue,
  onDragStarted: () => _onDragStart(item.id),
  onDragEnd: _onDragEnd,
)
```

- [ ] **Step 3: 运行测试验证编译通过**

```bash
cd apps && flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
```

---

## Task 2: 创建 TodoDragItem 组件

**文件:**
- 创建: `apps/lib/features/todo/ui/widgets/todo_drag_item.dart`

- [ ] **Step 1: 创建 Stateful 拖拽组件**

```dart
class TodoDragItem extends StatefulWidget {
  final TodoResponse todo;
  final int quadrant; // 1, 2, 3
  final VoidCallback onDragStarted;
  final VoidCallback onDragEnd;
  
  const TodoDragItem({
    super.key,
    required this.todo,
    required this.quadrant,
    required this.onDragStarted,
    required this.onDragEnd,
  });
  
  @override
  State<TodoDragItem> createState() => _TodoDragItemState();
}

class _TodoDragItemState extends State<TodoDragItem> {
  @override
  Widget build(BuildContext context) {
    return LongPressDraggable<String>(
      data: '${widget.todo.id}:${widget.quadrant}',
      delay: const Duration(milliseconds: 150),
      feedback: Material(
        elevation: 8,
        borderRadius: BorderRadius.circular(8),
        child: Transform.scale(
          scale: 1.03,
          child: SizedBox(
            width: 280,
            child: _buildDragFeedback(),
          ),
        ),
      ),
      childWhenDragging: Opacity(
        opacity: 0.5,  // Spec: 占位框 opacity 0.5
        child: widget.child,
      ),
      onDragStarted: widget.onDragStarted,
      onDragEnd: (_) => widget.onDragEnd(),
      child: widget.child,
    );
  }
  
  Widget _buildDragFeedback() {
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
      decoration: BoxDecoration(
        color: AppColors.white,
        borderRadius: BorderRadius.circular(8),
        boxShadow: [
          BoxShadow(
            color: AppColors.slate400.withValues(alpha: 0.3),
            blurRadius: 12,
            offset: const Offset(0, 4),
          ),
        ],
      ),
      child: Text(
        widget.todo.title,
        style: const TextStyle(
          fontSize: 13,
          fontWeight: FontWeight.w600,
          color: AppColors.slate700,
        ),
      ),
    );
  }
}
```

- [ ] **Step 2: 验证编译**

```bash
flutter analyze lib/features/todo/ui/widgets/todo_drag_item.dart
```

---

## Task 3: 实现 DragTarget 象限接收

**文件:**
- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart` 的 `_buildQuadrant` 方法

- [ ] **Step 1: 将象限容器改为 DragTarget**

```dart
Widget _buildQuadrant({
  required String title,
  required Color textColor,
  required Color dividerColor,
  required Color borderColor,
  required List<TodoResponse> items,
  required int quadrantValue, // 1, 2, 3
  required Future<void> Function(TodoResponse) onComplete,
  required void Function(TodoResponse) onTap,
}) {
  return DragTarget<String>(
    onWillAcceptWithDetails: (details) {
      // 解析拖拽数据
      final parts = details.data.split(':');
      final todoId = parts[0];
      // 标记目标象限
      _onDragEnterQuadrant(quadrantValue);
      return true;
    },
    onAcceptWithDetails: (details) {
      final parts = details.data.split(':');
      final todoId = parts[0];
      _onDrop(todoId, quadrantValue, 0); // TODO: 计算插入位置
    },
    onLeave: (_) {
      // 清除高亮
    },
    builder: (context, candidateData, rejectedData) {
      final isDragOver = candidateData.isNotEmpty;
      return AnimatedContainer(
        duration: const Duration(milliseconds: 200),
        decoration: BoxDecoration(
          border: Border.all(
            color: isDragOver ? AppColors.blue400 : borderColor,
            width: isDragOver ? 2 : 1,
          ),
          boxShadow: isDragOver ? [
            BoxShadow(
              color: AppColors.blue200.withValues(alpha: 0.4),
              blurRadius: 12,
            ),
          ] : null,
        ),
        child: _buildQuadrantContent(...),
      );
    },
  );
}
```

- [ ] **Step 2: 验证编译**

```bash
flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
```

---

## Task 4: 实现跨象限移动和象限内排序逻辑

**文件:**
- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`

- [ ] **Step 1: 实现 _onDrop 方法（支持跨象限移动和象限内排序）**

```dart
Future<void> _onDrop(String todoId, int targetQuadrant, int insertIndex) async {
  final todo = _todos.firstWhere((t) => t.id == todoId);
  final sourceQuadrant = todo.priority;
  
  // 乐观更新：先保存当前状态用于回滚
  final previousTodos = List<TodoResponse>.from(_todos);
  
  if (sourceQuadrant == targetQuadrant) {
    // 象限内排序：重新排列列表顺序
    setState(() {
      final currentIndex = _todos.indexWhere((t) => t.id == todoId);
      if (currentIndex != insertIndex) {
        final item = _todos.removeAt(currentIndex);
        _todos.insert(insertIndex, item);
        // 更新 sort_order (前端维护的排序索引)
        for (int i = 0; i < _todos.length; i++) {
          _todos[i] = _todos[i].copyWith(sortOrder: i);
        }
      }
      _onDragEnd();
    });
    
    // 后端同步 sort_order
    try {
      // 只更新 sort_order 字段
      await _todoApi.updateTodo(todoId, sortOrder: insertIndex);
    } catch (e) {
      _rollbackAndShowError(previousTodos, '排序失败');
    }
  } else {
    // 跨象限移动：更新 priority
    setState(() {
      final index = _todos.indexWhere((t) => t.id == todoId);
      if (index != -1) {
        _todos[index] = _todos[index].copyWith(priority: targetQuadrant);
      }
      _onDragEnd();
    });
    
    // 后端同步 priority
    try {
      await _todoApi.updateTodo(todoId, priority: targetQuadrant);
      if (mounted) {
        Toast.show(context, '已移动', type: ToastType.success);
      }
    } catch (e) {
      _rollbackAndShowError(previousTodos, '移动失败');
    }
  }
}

void _rollbackAndShowError(List<TodoResponse> previousTodos, String message) {
  setState(() {
    _todos = previousTodos;
  });
  if (mounted) {
    Toast.show(context, message, type: ToastType.error);
  }
}
```

- [ ] **Step 2: 检查 TodoApi.updateTodo 签名**

如果 `updateTodo` 不支持 `sortOrder` 参数，需要在 `TodoApi` 中添加：

```dart
// apps/lib/features/todo/data/todo_api.dart
Future<TodoResponse> updateTodo(
  String id, {
  int? priority,
  int? sortOrder, // 添加此参数
  String? title,
  String? description,
}) async {
  // 调用后端 API 更新
}
```

- [ ] **Step 3: 验证编译和功能**

```bash
flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
flutter analyze lib/features/todo/data/todo_api.dart
```

---

## Task 5: 添加插入指示器

**文件:**
- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`

- [ ] **Step 1: 添加插入位置状态和指示器 Widget**

```dart
// 在 State 中添加
int? _dragInsertIndex; // 拖拽插入位置

// 添加插入指示器 Widget
Widget _buildInsertIndicator() {
  return Container(
    height: 2,
    margin: const EdgeInsets.symmetric(vertical: 4),
    decoration: BoxDecoration(
      color: AppColors.blue500,
      borderRadius: BorderRadius.circular(1),
      boxShadow: [
        BoxShadow(
          color: AppColors.blue400.withValues(alpha: 0.3),
          blurRadius: 4,
        ),
      ],
    ),
  );
}
```

- [ ] **Step 2: 在象限内容列表中渲染插入指示器**

在 `_buildQuadrant` 的 items 列表中，根据 `_dragInsertIndex` 插入指示器：

```dart
// items 列表构建
final widgets = <Widget>[];
for (int i = 0; i < items.length; i++) {
  if (_dragInsertIndex == i && _dragTargetQuadrant == quadrantValue) {
    widgets.add(_buildInsertIndicator());
  }
  widgets.add(TodoDragItem(
    todo: items[i],
    quadrant: quadrantValue,
    onDragStarted: () => _onDragStart(items[i].id),
    onDragEnd: _onDragEnd,
  ));
}
```

- [ ] **Step 3: 验证编译**

```bash
flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
```

---

## Task 6: 添加 Spring 动画和退出/进入动画比例

**文件:**
- 修改: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`

- [ ] **Step 1: 使用真正的 Spring 动画替代 elasticOut**

Flutter 的 `SpringSimulation` 需要使用 `AnimationController`。对于跨象限移动的 feedback，可以使用 `Curves.bounceOut` 或自定义 spring：

```dart
// 使用 SpringSimulation 的替代方案 - CurvedAnimation + bounceOut
// 跨象限移动动画 (进入时间短，退出时间长，符合 spec)
 AnimatedContainer(
   duration: Duration(
     milliseconds: _isDragging ? 200 : 150, // 进入 150ms < 退出 200ms
   ),
   curve: Curves.easeOutCubic,
   // ...
 )
```

对于真正的 spring 物理效果，可以在 `pubspec.yaml` 添加 `flutter_animate` 包：

```yaml
dependencies:
  flutter_animate: ^4.5.0
```

然后使用：
```dart
import 'package:flutter_animate/flutter_animate.dart';

child.animate().spring(
  type: SpringType.bouncy,
  duration: 300.ms,
)
```

- [ ] **Step 2: 验证编译**

```bash
flutter analyze lib/features/todo/ui/screens/todo_quadrants_screen.dart
```

---

## Task 7: 集成测试

**文件:**
- 创建: `apps/test/features/todo/quadrant_drag_test.dart`

- [ ] **Step 1: 编写核心功能测试**

```dart
testWidgets('跨象限拖拽 - 成功后显示 Toast', (tester) async {
  // mock TodoApi
  when(() => todoApi.updateTodo(any(), priority: any(named: 'priority')))
    .thenAnswer((_) async => mockTodo);
  
  await pumpWidgetWithScaffolding(tester, todoApi: todoApi);
  
  // 执行拖拽
  final todoItem = find.text('测试待办');
  await tester.drag(todoItem, const Offset(0, 200)); // 拖到下一象限
  await tester.pumpAndSettle();
  
  expect(find.text('已移动'), findsOneWidget);
});

testWidgets('跨象限拖拽 - 失败后回滚并显示错误', (tester) async {
  when(() => todoApi.updateTodo(any(), priority: any(named: 'priority')))
    .thenThrow(Exception('网络错误'));
  
  await pumpWidgetWithScaffolding(tester, todoApi: todoApi);
  
  final todoItem = find.text('测试待办');
  await tester.drag(todoItem, const Offset(0, 200));
  await tester.pumpAndSettle();
  
  expect(find.text('移动失败'), findsOneWidget);
  // 验证 UI 回滚到原始状态
});

testWidgets('象限内排序 - 位置正确交换', (tester) async {
  // 验证排序逻辑
});
```

- [ ] **Step 2: 运行测试**

```bash
cd apps && flutter test test/features/todo/quadrant_drag_test.dart
```

---

## 验收标准

- [ ] 长按待办项 150ms 后启动拖拽
- [ ] 拖拽时卡片 scale 1.03 + 阴影，原位置显示 opacity 0.5 占位
- [ ] 拖到目标象限时，象限边框高亮发光 (2px blue400)
- [ ] 目标位置显示 2px 蓝色插入指示器
- [ ] 释放后卡片以平滑动画到达新位置
- [ ] 跨象限移动后本地 UI 立即更新
- [ ] 后端同步失败时回滚本地状态并显示错误 Toast
- [ ] 编译无错误，测试通过