refactor(todo): 移除 due_at 字段，改用 order 字段管理象限内顺序
This commit is contained in:
qzl
@@ -25,13 +25,13 @@ class TodoApi {
|
||||
Future<TodoResponse> createTodo({
|
||||
required String title,
|
||||
String? description,
|
||||
DateTime? dueAt,
|
||||
int priority = 1,
|
||||
int? order,
|
||||
List<String> scheduleItemIds = const [],
|
||||
}) async {
|
||||
final data = <String, dynamic>{'title': title, 'priority': priority};
|
||||
if (description != null) data['description'] = description;
|
||||
if (dueAt != null) data['due_at'] = dueAt.toIso8601String();
|
||||
if (order != null) data['order'] = order;
|
||||
if (scheduleItemIds.isNotEmpty) data['schedule_item_ids'] = scheduleItemIds;
|
||||
|
||||
final response = await _client.post(_prefix, data: data);
|
||||
@@ -42,16 +42,16 @@ class TodoApi {
|
||||
String id, {
|
||||
String? title,
|
||||
String? description,
|
||||
DateTime? dueAt,
|
||||
int? priority,
|
||||
int? order,
|
||||
String? status,
|
||||
List<String>? scheduleItemIds,
|
||||
}) async {
|
||||
final data = <String, dynamic>{};
|
||||
if (title != null) data['title'] = title;
|
||||
if (description != null) data['description'] = description;
|
||||
if (dueAt != null) data['due_at'] = dueAt.toIso8601String();
|
||||
if (priority != null) data['priority'] = priority;
|
||||
if (order != null) data['order'] = order;
|
||||
if (status != null) data['status'] = status;
|
||||
if (scheduleItemIds != null) data['schedule_item_ids'] = scheduleItemIds;
|
||||
|
||||
@@ -59,12 +59,19 @@ class TodoApi {
|
||||
return TodoResponse.fromJson(response.data);
|
||||
}
|
||||
|
||||
Future<void> updateTodoPriority(String id, int priority) async {
|
||||
try {
|
||||
await _client.patch('$_prefix/$id', data: {'priority': priority});
|
||||
} catch (_) {
|
||||
// Ignore response parsing errors, just need to know if request succeeded
|
||||
}
|
||||
Future<void> reorderTodos(List<TodoReorderItemPayload> items) async {
|
||||
final data = {
|
||||
'items': items
|
||||
.map(
|
||||
(item) => {
|
||||
'id': item.id,
|
||||
'priority': item.priority,
|
||||
'order': item.order,
|
||||
},
|
||||
)
|
||||
.toList(),
|
||||
};
|
||||
await _client.patch('$_prefix/reorder', data: data);
|
||||
}
|
||||
|
||||
Future<TodoResponse> completeTodo(String id) async {
|
||||
@@ -77,6 +84,18 @@ class TodoApi {
|
||||
}
|
||||
}
|
||||
|
||||
class TodoReorderItemPayload {
|
||||
final String id;
|
||||
final int priority;
|
||||
final int order;
|
||||
|
||||
const TodoReorderItemPayload({
|
||||
required this.id,
|
||||
required this.priority,
|
||||
required this.order,
|
||||
});
|
||||
}
|
||||
|
||||
class ScheduleItemBasic {
|
||||
final String id;
|
||||
final String title;
|
||||
@@ -107,7 +126,7 @@ class TodoResponse {
|
||||
final String ownerId;
|
||||
final String title;
|
||||
final String? description;
|
||||
final DateTime? dueAt;
|
||||
final int order;
|
||||
final int priority;
|
||||
final String status;
|
||||
final DateTime? completedAt;
|
||||
@@ -120,8 +139,8 @@ class TodoResponse {
|
||||
required this.ownerId,
|
||||
required this.title,
|
||||
this.description,
|
||||
this.dueAt,
|
||||
required this.priority,
|
||||
required this.order,
|
||||
required this.status,
|
||||
this.completedAt,
|
||||
required this.createdAt,
|
||||
@@ -136,10 +155,8 @@ class TodoResponse {
|
||||
ownerId: json['owner_id'] as String,
|
||||
title: json['title'] as String,
|
||||
description: json['description'] as String?,
|
||||
dueAt: json['due_at'] != null
|
||||
? DateTime.parse(json['due_at'] as String)
|
||||
: null,
|
||||
priority: json['priority'] as int,
|
||||
order: json['order'] as int,
|
||||
status: json['status'] as String,
|
||||
completedAt: json['completed_at'] != null
|
||||
? DateTime.parse(json['completed_at'] as String)
|
||||
@@ -157,8 +174,8 @@ class TodoResponse {
|
||||
String? ownerId,
|
||||
String? title,
|
||||
String? description,
|
||||
DateTime? dueAt,
|
||||
int? priority,
|
||||
int? order,
|
||||
String? status,
|
||||
DateTime? completedAt,
|
||||
DateTime? createdAt,
|
||||
@@ -170,8 +187,8 @@ class TodoResponse {
|
||||
ownerId: ownerId ?? this.ownerId,
|
||||
title: title ?? this.title,
|
||||
description: description ?? this.description,
|
||||
dueAt: dueAt ?? this.dueAt,
|
||||
priority: priority ?? this.priority,
|
||||
order: order ?? this.order,
|
||||
status: status ?? this.status,
|
||||
completedAt: completedAt ?? this.completedAt,
|
||||
createdAt: createdAt ?? this.createdAt,
|
||||
|
||||
@@ -288,12 +288,7 @@ class _TodoDetailScreenState extends State<TodoDetailScreen> {
|
||||
|
||||
String _buildSubtitle() {
|
||||
final parts = <String>[];
|
||||
if (_todo!.dueAt != null) {
|
||||
final due = _todo!.dueAt!;
|
||||
parts.add(
|
||||
'截止 ${due.month}月${due.day}日 ${due.hour.toString().padLeft(2, '0')}:${due.minute.toString().padLeft(2, '0')}',
|
||||
);
|
||||
}
|
||||
parts.add('象限内顺序 #${_todo!.order + 1}');
|
||||
if (_todo!.scheduleItems.isNotEmpty) {
|
||||
parts.add('已拆分为${_todo!.scheduleItems.length}个日历事件');
|
||||
} else {
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:drag_and_drop_lists/drag_and_drop_lists.dart';
|
||||
import 'package:go_router/go_router.dart';
|
||||
import 'package:lucide_icons/lucide_icons.dart';
|
||||
import '../../../../core/di/injection.dart';
|
||||
@@ -15,7 +16,6 @@ import '../../../../shared/widgets/toast/toast_type.dart';
|
||||
import '../../../calendar/ui/calendar_state_manager.dart';
|
||||
import '../../../calendar/ui/widgets/bottom_dock.dart';
|
||||
import '../../data/todo_api.dart';
|
||||
import '../widgets/todo_drag_item.dart';
|
||||
|
||||
class TodoQuadrantsScreen extends StatefulWidget {
|
||||
const TodoQuadrantsScreen({super.key});
|
||||
@@ -31,65 +31,56 @@ class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
|
||||
bool _isLoading = true;
|
||||
bool _isPullRefreshing = false;
|
||||
bool _loadingTodosRequest = false;
|
||||
bool _isReordering = false;
|
||||
String? _error;
|
||||
|
||||
String? _draggingTodoId;
|
||||
int? _dragTargetQuadrant;
|
||||
int? _dragInsertIndex;
|
||||
|
||||
bool get _isDragging => _draggingTodoId != null;
|
||||
|
||||
void _onDragStart(String todoId) {
|
||||
setState(() {
|
||||
_draggingTodoId = todoId;
|
||||
_dragTargetQuadrant = null;
|
||||
_dragInsertIndex = null;
|
||||
});
|
||||
}
|
||||
|
||||
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,
|
||||
Future<void> _onItemReorder(
|
||||
int oldItemIndex,
|
||||
int oldListIndex,
|
||||
int newItemIndex,
|
||||
int newListIndex,
|
||||
) async {
|
||||
if (_isReordering) {
|
||||
return;
|
||||
}
|
||||
|
||||
final sourceQuadrant = _quadrantByListIndex(oldListIndex);
|
||||
final targetQuadrant = _quadrantByListIndex(newListIndex);
|
||||
final sourceItems = _sortedQuadrantTodos(sourceQuadrant);
|
||||
if (oldItemIndex < 0 || oldItemIndex >= sourceItems.length) {
|
||||
return;
|
||||
}
|
||||
|
||||
final todoId = sourceItems[oldItemIndex].id;
|
||||
final previousTodos = List<TodoResponse>.from(_todos);
|
||||
try {
|
||||
final todo = _todos.firstWhere((t) => t.id == todoId);
|
||||
final sourceQuadrant = todo.priority;
|
||||
setState(() {
|
||||
_isReordering = true;
|
||||
});
|
||||
|
||||
if (sourceQuadrant == targetQuadrant) {
|
||||
_onDragEnd();
|
||||
final reordered = _reorderTodos(
|
||||
todoId: todoId,
|
||||
sourceQuadrant: sourceQuadrant,
|
||||
targetQuadrant: targetQuadrant,
|
||||
insertIndex: newItemIndex,
|
||||
);
|
||||
if (reordered == null) {
|
||||
return;
|
||||
}
|
||||
|
||||
setState(() {
|
||||
final index = _todos.indexWhere((t) => t.id == todoId);
|
||||
if (index != -1) {
|
||||
_todos[index] = _todos[index].copyWith(priority: targetQuadrant);
|
||||
}
|
||||
});
|
||||
setState(() => _todos = reordered.todos);
|
||||
|
||||
await _todoApi.updateTodoPriority(todoId, targetQuadrant);
|
||||
await _todoApi.reorderTodos(
|
||||
reordered.changedTodos
|
||||
.map(
|
||||
(updated) => TodoReorderItemPayload(
|
||||
id: updated.id,
|
||||
priority: updated.priority,
|
||||
order: updated.order,
|
||||
),
|
||||
)
|
||||
.toList(growable: false),
|
||||
);
|
||||
} catch (e) {
|
||||
if (!mounted) return;
|
||||
setState(() {
|
||||
@@ -97,12 +88,104 @@ class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
|
||||
});
|
||||
Toast.show(context, '移动失败', type: ToastType.error);
|
||||
} finally {
|
||||
if (mounted) _onDragEnd();
|
||||
if (mounted) {
|
||||
setState(() {
|
||||
_isReordering = false;
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void _onDragLeave() {
|
||||
// 清除高亮
|
||||
int _quadrantByListIndex(int listIndex) {
|
||||
switch (listIndex) {
|
||||
case 0:
|
||||
return 1;
|
||||
case 1:
|
||||
return 3;
|
||||
case 2:
|
||||
return 2;
|
||||
default:
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
_ReorderResult? _reorderTodos({
|
||||
required String todoId,
|
||||
required int sourceQuadrant,
|
||||
required int targetQuadrant,
|
||||
required int insertIndex,
|
||||
}) {
|
||||
final byId = {for (final todo in _todos) todo.id: todo};
|
||||
final moving = byId[todoId];
|
||||
if (moving == null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
final sourceList = _sortedQuadrantTodos(sourceQuadrant);
|
||||
final targetList = sourceQuadrant == targetQuadrant
|
||||
? sourceList
|
||||
: _sortedQuadrantTodos(targetQuadrant);
|
||||
|
||||
final sourceIndex = sourceList.indexWhere((todo) => todo.id == todoId);
|
||||
if (sourceIndex == -1) {
|
||||
return null;
|
||||
}
|
||||
|
||||
final mutableSource = List<TodoResponse>.from(sourceList);
|
||||
final extracted = mutableSource.removeAt(sourceIndex);
|
||||
|
||||
int targetIndex = insertIndex;
|
||||
if (sourceQuadrant == targetQuadrant && sourceIndex < targetIndex) {
|
||||
targetIndex -= 1;
|
||||
}
|
||||
|
||||
if (targetIndex < 0) {
|
||||
targetIndex = 0;
|
||||
}
|
||||
|
||||
final mutableTarget = sourceQuadrant == targetQuadrant
|
||||
? mutableSource
|
||||
: List<TodoResponse>.from(targetList);
|
||||
|
||||
if (targetIndex > mutableTarget.length) {
|
||||
targetIndex = mutableTarget.length;
|
||||
}
|
||||
|
||||
final moved = extracted.copyWith(priority: targetQuadrant);
|
||||
mutableTarget.insert(targetIndex, moved);
|
||||
|
||||
final updatedById = <String, TodoResponse>{};
|
||||
void reindex(List<TodoResponse> list, int priority) {
|
||||
for (var index = 0; index < list.length; index += 1) {
|
||||
final current = list[index];
|
||||
final updated = current.copyWith(priority: priority, order: index);
|
||||
list[index] = updated;
|
||||
if (current.priority != updated.priority ||
|
||||
current.order != updated.order) {
|
||||
updatedById[updated.id] = updated;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (sourceQuadrant == targetQuadrant) {
|
||||
reindex(mutableTarget, targetQuadrant);
|
||||
} else {
|
||||
reindex(mutableSource, sourceQuadrant);
|
||||
reindex(mutableTarget, targetQuadrant);
|
||||
}
|
||||
|
||||
if (updatedById.isEmpty) {
|
||||
return null;
|
||||
}
|
||||
|
||||
final updatedTodos = _todos
|
||||
.map((todo) => updatedById[todo.id] ?? todo)
|
||||
.toList(growable: false);
|
||||
|
||||
return _ReorderResult(
|
||||
todos: updatedTodos,
|
||||
changedTodos: updatedById.values.toList(growable: false),
|
||||
);
|
||||
}
|
||||
|
||||
@override
|
||||
@@ -160,14 +243,23 @@ class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
|
||||
await _loadTodos(showPageLoader: false);
|
||||
}
|
||||
|
||||
List<TodoResponse> get _importantUrgent =>
|
||||
_todos.where((t) => t.priority == 1).toList();
|
||||
List<TodoResponse> get _importantUrgent => _sortedQuadrantTodos(1);
|
||||
|
||||
List<TodoResponse> get _urgentNotImportant =>
|
||||
_todos.where((t) => t.priority == 3).toList();
|
||||
List<TodoResponse> get _urgentNotImportant => _sortedQuadrantTodos(3);
|
||||
|
||||
List<TodoResponse> get _importantNotUrgent =>
|
||||
_todos.where((t) => t.priority == 2).toList();
|
||||
List<TodoResponse> get _importantNotUrgent => _sortedQuadrantTodos(2);
|
||||
|
||||
List<TodoResponse> _sortedQuadrantTodos(int quadrantValue) {
|
||||
final list = _todos.where((t) => t.priority == quadrantValue).toList();
|
||||
list.sort((a, b) {
|
||||
final byOrder = a.order.compareTo(b.order);
|
||||
if (byOrder != 0) {
|
||||
return byOrder;
|
||||
}
|
||||
return a.createdAt.compareTo(b.createdAt);
|
||||
});
|
||||
return list;
|
||||
}
|
||||
|
||||
Future<void> _completeTodo(TodoResponse todo) async {
|
||||
try {
|
||||
@@ -287,59 +379,12 @@ class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
|
||||
return ErrorRetrySurface(message: '加载失败: $_error', onRetry: _loadTodos);
|
||||
}
|
||||
|
||||
Widget content = Column(
|
||||
mainAxisSize: MainAxisSize.min,
|
||||
children: [
|
||||
_buildQuadrant(
|
||||
title: '重要紧急',
|
||||
textColor: AppColors.g1Text,
|
||||
dividerColor: AppColors.g1Divider,
|
||||
borderColor: AppColors.g1Border,
|
||||
items: _importantUrgent,
|
||||
quadrantValue: 1,
|
||||
onComplete: _completeTodo,
|
||||
onTap: _navigateToDetail,
|
||||
),
|
||||
const SizedBox(height: 12),
|
||||
_buildQuadrant(
|
||||
title: '紧急不重要',
|
||||
textColor: AppColors.g2Text,
|
||||
dividerColor: AppColors.g2Divider,
|
||||
borderColor: AppColors.g2Border,
|
||||
items: _urgentNotImportant,
|
||||
quadrantValue: 3,
|
||||
onComplete: _completeTodo,
|
||||
onTap: _navigateToDetail,
|
||||
),
|
||||
const SizedBox(height: 12),
|
||||
_buildQuadrant(
|
||||
title: '重要不紧急',
|
||||
textColor: AppColors.g3Text,
|
||||
dividerColor: AppColors.g3Divider,
|
||||
borderColor: AppColors.g3Border,
|
||||
items: _importantNotUrgent,
|
||||
quadrantValue: 2,
|
||||
onComplete: _completeTodo,
|
||||
onTap: _navigateToDetail,
|
||||
),
|
||||
],
|
||||
);
|
||||
final content = _buildDragBoard();
|
||||
|
||||
if (withScroll) {
|
||||
return Stack(
|
||||
children: [
|
||||
RefreshIndicator.noSpinner(
|
||||
onRefresh: _onPullRefresh,
|
||||
child: SingleChildScrollView(
|
||||
padding: const EdgeInsets.only(
|
||||
left: 16,
|
||||
right: 16,
|
||||
top: 4,
|
||||
bottom: 96,
|
||||
),
|
||||
child: content,
|
||||
),
|
||||
),
|
||||
RefreshIndicator.noSpinner(onRefresh: _onPullRefresh, child: content),
|
||||
Align(
|
||||
alignment: Alignment.topCenter,
|
||||
child: AppPullRefreshFeedback(visible: _isPullRefreshing),
|
||||
@@ -348,141 +393,157 @@ class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
|
||||
);
|
||||
}
|
||||
|
||||
return Padding(
|
||||
padding: const EdgeInsets.fromLTRB(16, 4, 16, 16),
|
||||
child: content,
|
||||
);
|
||||
return content;
|
||||
}
|
||||
|
||||
Widget _buildQuadrant({
|
||||
required String title,
|
||||
required Color textColor,
|
||||
required Color dividerColor,
|
||||
required Color borderColor,
|
||||
required List<TodoResponse> items,
|
||||
required int quadrantValue,
|
||||
required Future<void> Function(TodoResponse) onComplete,
|
||||
required void Function(TodoResponse) onTap,
|
||||
}) {
|
||||
return Container(
|
||||
decoration: BoxDecoration(
|
||||
color: AppColors.todoCardBg,
|
||||
borderRadius: BorderRadius.circular(14),
|
||||
border: Border.all(color: borderColor, width: 1),
|
||||
Widget _buildDragBoard() {
|
||||
final quadrants = [
|
||||
_QuadrantMeta(
|
||||
value: 1,
|
||||
title: '重要紧急',
|
||||
textColor: AppColors.g1Text,
|
||||
dividerColor: AppColors.g1Divider,
|
||||
borderColor: AppColors.g1Border,
|
||||
items: _importantUrgent,
|
||||
),
|
||||
child: Column(
|
||||
mainAxisSize: MainAxisSize.min,
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: [
|
||||
_buildQuadrantHeader(title, textColor, items.length),
|
||||
Container(height: 1, color: dividerColor),
|
||||
const SizedBox(height: 8),
|
||||
Padding(
|
||||
padding: const EdgeInsets.fromLTRB(6, 0, 6, 8),
|
||||
child: DragTarget<String>(
|
||||
onWillAcceptWithDetails: (details) {
|
||||
_onDragEnterQuadrant(quadrantValue);
|
||||
return true;
|
||||
},
|
||||
onAcceptWithDetails: (details) {
|
||||
final parts = details.data.split(':');
|
||||
final todoId = parts[0];
|
||||
_onDrop(todoId, quadrantValue, 0);
|
||||
},
|
||||
onLeave: (_) {
|
||||
_onDragLeave();
|
||||
},
|
||||
builder: (context, candidateData, rejectedData) {
|
||||
final isDragOver = candidateData.isNotEmpty;
|
||||
return Container(
|
||||
decoration: BoxDecoration(
|
||||
color: isDragOver
|
||||
? AppColors.blue50.withValues(alpha: 0.3)
|
||||
: Colors.transparent,
|
||||
borderRadius: BorderRadius.circular(8),
|
||||
border: isDragOver
|
||||
? Border.all(color: AppColors.blue400, width: 2)
|
||||
: null,
|
||||
_QuadrantMeta(
|
||||
value: 3,
|
||||
title: '紧急不重要',
|
||||
textColor: AppColors.g2Text,
|
||||
dividerColor: AppColors.g2Divider,
|
||||
borderColor: AppColors.g2Border,
|
||||
items: _urgentNotImportant,
|
||||
),
|
||||
_QuadrantMeta(
|
||||
value: 2,
|
||||
title: '重要不紧急',
|
||||
textColor: AppColors.g3Text,
|
||||
dividerColor: AppColors.g3Divider,
|
||||
borderColor: AppColors.g3Border,
|
||||
items: _importantNotUrgent,
|
||||
),
|
||||
];
|
||||
|
||||
final lists = quadrants
|
||||
.map(
|
||||
(meta) => DragAndDropList(
|
||||
canDrag: false,
|
||||
header: _buildQuadrantHeader(meta),
|
||||
contentsWhenEmpty: _buildEmptyQuadrant(),
|
||||
lastTarget: const SizedBox(height: AppSpacing.lg),
|
||||
decoration: BoxDecoration(
|
||||
color: AppColors.todoCardBg,
|
||||
borderRadius: BorderRadius.circular(14),
|
||||
border: Border.all(color: meta.borderColor),
|
||||
),
|
||||
children: meta.items
|
||||
.map(
|
||||
(item) => DragAndDropItem(
|
||||
child: Padding(
|
||||
padding: const EdgeInsets.symmetric(
|
||||
horizontal: AppSpacing.sm,
|
||||
),
|
||||
child: _TodoItemWidget(
|
||||
item: item,
|
||||
onComplete: () => _completeTodo(item),
|
||||
onTap: () => _navigateToDetail(item),
|
||||
),
|
||||
),
|
||||
),
|
||||
child: items.isEmpty
|
||||
? SizedBox(
|
||||
height: 60,
|
||||
child: Center(
|
||||
child: Text(
|
||||
'暂无待办',
|
||||
style: TextStyle(
|
||||
fontFamily: 'Inter',
|
||||
fontSize: 13,
|
||||
color: AppColors.slate400,
|
||||
),
|
||||
),
|
||||
),
|
||||
)
|
||||
: _buildQuadrantItemList(
|
||||
items,
|
||||
quadrantValue,
|
||||
onComplete,
|
||||
onTap,
|
||||
),
|
||||
);
|
||||
},
|
||||
),
|
||||
)
|
||||
.toList(growable: false),
|
||||
),
|
||||
],
|
||||
)
|
||||
.toList(growable: false);
|
||||
|
||||
return SingleChildScrollView(
|
||||
padding: const EdgeInsets.fromLTRB(
|
||||
AppSpacing.lg,
|
||||
AppSpacing.xs,
|
||||
AppSpacing.lg,
|
||||
96,
|
||||
),
|
||||
child: DragAndDropLists(
|
||||
children: lists,
|
||||
onItemReorder: _onItemReorder,
|
||||
onListReorder: (oldListIndex, newListIndex) {},
|
||||
listDivider: const SizedBox(height: AppSpacing.md),
|
||||
itemDivider: Padding(
|
||||
padding: const EdgeInsets.symmetric(horizontal: AppSpacing.md),
|
||||
child: Container(height: 1, color: AppColors.slate100),
|
||||
),
|
||||
listPadding: EdgeInsets.zero,
|
||||
itemDecorationWhileDragging: BoxDecoration(
|
||||
color: AppColors.todoCardBg,
|
||||
borderRadius: BorderRadius.circular(AppRadius.md),
|
||||
border: Border.all(color: AppColors.borderSecondary),
|
||||
boxShadow: [
|
||||
BoxShadow(
|
||||
color: AppColors.slate200.withValues(alpha: 0.6),
|
||||
blurRadius: AppRadius.md,
|
||||
offset: const Offset(0, AppSpacing.xs),
|
||||
),
|
||||
],
|
||||
),
|
||||
itemGhost: const SizedBox(height: 42),
|
||||
itemDragOnLongPress: true,
|
||||
lastItemTargetHeight: AppSpacing.xl,
|
||||
disableScrolling: true,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
Widget _buildQuadrantHeader(String title, Color textColor, int itemCount) {
|
||||
return Padding(
|
||||
padding: const EdgeInsets.fromLTRB(10, 10, 10, 8),
|
||||
child: Row(
|
||||
mainAxisAlignment: MainAxisAlignment.spaceBetween,
|
||||
children: [
|
||||
Text(
|
||||
title,
|
||||
style: TextStyle(
|
||||
fontFamily: 'Inter',
|
||||
fontSize: 15,
|
||||
fontWeight: FontWeight.w700,
|
||||
color: textColor,
|
||||
),
|
||||
),
|
||||
Text(
|
||||
'${itemCount}项',
|
||||
style: TextStyle(
|
||||
fontFamily: 'Inter',
|
||||
fontSize: 12,
|
||||
fontWeight: FontWeight.w700,
|
||||
color: textColor,
|
||||
),
|
||||
),
|
||||
],
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
Widget _buildQuadrantItemList(
|
||||
List<TodoResponse> items,
|
||||
int quadrantValue,
|
||||
Future<void> Function(TodoResponse) onComplete,
|
||||
void Function(TodoResponse) onTap,
|
||||
) {
|
||||
Widget _buildQuadrantHeader(_QuadrantMeta meta) {
|
||||
return Column(
|
||||
mainAxisSize: MainAxisSize.min,
|
||||
children: items.map((item) {
|
||||
return TodoDragItem(
|
||||
todo: item,
|
||||
quadrant: quadrantValue,
|
||||
onDragStarted: () => _onDragStart(item.id),
|
||||
onDragEnd: _onDragEnd,
|
||||
child: _TodoItemWidget(
|
||||
item: item,
|
||||
onComplete: () => onComplete(item),
|
||||
onTap: () => onTap(item),
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: [
|
||||
Padding(
|
||||
padding: const EdgeInsets.fromLTRB(10, 10, 10, 8),
|
||||
child: Row(
|
||||
mainAxisAlignment: MainAxisAlignment.spaceBetween,
|
||||
crossAxisAlignment: CrossAxisAlignment.center,
|
||||
children: [
|
||||
Text(
|
||||
meta.title,
|
||||
style: TextStyle(
|
||||
fontFamily: 'Inter',
|
||||
fontSize: 15,
|
||||
fontWeight: FontWeight.w700,
|
||||
color: meta.textColor,
|
||||
),
|
||||
),
|
||||
Text(
|
||||
'${meta.items.length}项',
|
||||
style: TextStyle(
|
||||
fontFamily: 'Inter',
|
||||
fontSize: 12,
|
||||
fontWeight: FontWeight.w700,
|
||||
color: meta.textColor,
|
||||
),
|
||||
),
|
||||
],
|
||||
),
|
||||
);
|
||||
}).toList(),
|
||||
),
|
||||
Container(height: 1, color: meta.dividerColor),
|
||||
const SizedBox(height: AppSpacing.sm),
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
Widget _buildEmptyQuadrant() {
|
||||
return SizedBox(
|
||||
height: 60,
|
||||
child: Center(
|
||||
child: Text(
|
||||
'暂无待办',
|
||||
style: TextStyle(
|
||||
fontFamily: 'Inter',
|
||||
fontSize: 13,
|
||||
color: AppColors.slate400,
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
@@ -507,6 +568,31 @@ class _TodoQuadrantsScreenState extends State<TodoQuadrantsScreen> {
|
||||
}
|
||||
}
|
||||
|
||||
class _ReorderResult {
|
||||
final List<TodoResponse> todos;
|
||||
final List<TodoResponse> changedTodos;
|
||||
|
||||
const _ReorderResult({required this.todos, required this.changedTodos});
|
||||
}
|
||||
|
||||
class _QuadrantMeta {
|
||||
final int value;
|
||||
final String title;
|
||||
final Color textColor;
|
||||
final Color dividerColor;
|
||||
final Color borderColor;
|
||||
final List<TodoResponse> items;
|
||||
|
||||
const _QuadrantMeta({
|
||||
required this.value,
|
||||
required this.title,
|
||||
required this.textColor,
|
||||
required this.dividerColor,
|
||||
required this.borderColor,
|
||||
required this.items,
|
||||
});
|
||||
}
|
||||
|
||||
class _TodoItemWidget extends StatefulWidget {
|
||||
final TodoResponse item;
|
||||
final VoidCallback onComplete;
|
||||
|
||||
@@ -5,6 +5,7 @@ import 'package:social_app/features/todo/data/todo_api.dart';
|
||||
class TodoDragItem extends StatelessWidget {
|
||||
final TodoResponse todo;
|
||||
final int quadrant;
|
||||
final int sourceIndex;
|
||||
final VoidCallback onDragStarted;
|
||||
final VoidCallback onDragEnd;
|
||||
final Widget child;
|
||||
@@ -13,6 +14,7 @@ class TodoDragItem extends StatelessWidget {
|
||||
super.key,
|
||||
required this.todo,
|
||||
required this.quadrant,
|
||||
required this.sourceIndex,
|
||||
required this.onDragStarted,
|
||||
required this.onDragEnd,
|
||||
required this.child,
|
||||
@@ -21,7 +23,7 @@ class TodoDragItem extends StatelessWidget {
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
return LongPressDraggable<String>(
|
||||
data: '${todo.id}:$quadrant',
|
||||
data: '${todo.id}:$quadrant:$sourceIndex',
|
||||
delay: const Duration(milliseconds: 150),
|
||||
feedback: Material(
|
||||
elevation: 8,
|
||||
|
||||
@@ -25,6 +25,7 @@ dependencies:
|
||||
timezone: ^0.9.4
|
||||
image_picker: ^1.0.7
|
||||
package_info_plus: ^8.0.3
|
||||
drag_and_drop_lists: ^0.4.2
|
||||
|
||||
dev_dependencies:
|
||||
flutter_test:
|
||||
|
||||
@@ -27,6 +27,7 @@ void main() {
|
||||
() async {
|
||||
const todoId = 'todo-123';
|
||||
const targetPriority = 2;
|
||||
const targetOrder = 0;
|
||||
|
||||
when(
|
||||
() => mockClient.patch(any(), data: any(named: 'data')),
|
||||
@@ -38,6 +39,7 @@ void main() {
|
||||
'owner_id': 'user-1',
|
||||
'title': 'Test Todo',
|
||||
'priority': targetPriority,
|
||||
'order': targetOrder,
|
||||
'status': 'pending',
|
||||
'created_at': '2024-01-01T00:00:00Z',
|
||||
'updated_at': '2024-01-01T00:00:00Z',
|
||||
@@ -48,13 +50,15 @@ void main() {
|
||||
final result = await todoApi.updateTodo(
|
||||
todoId,
|
||||
priority: targetPriority,
|
||||
order: targetOrder,
|
||||
);
|
||||
|
||||
expect(result.priority, targetPriority);
|
||||
expect(result.order, targetOrder);
|
||||
verify(
|
||||
() => mockClient.patch(
|
||||
'/api/v1/todos/$todoId',
|
||||
data: {'priority': targetPriority},
|
||||
data: {'priority': targetPriority, 'order': targetOrder},
|
||||
),
|
||||
).called(1);
|
||||
},
|
||||
@@ -67,7 +71,10 @@ void main() {
|
||||
() => mockClient.patch(any(), data: any(named: 'data')),
|
||||
).thenThrow(Exception('Network error'));
|
||||
|
||||
expect(() => todoApi.updateTodo(todoId, priority: 2), throwsException);
|
||||
expect(
|
||||
() => todoApi.updateTodo(todoId, priority: 2, order: 0),
|
||||
throwsException,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -81,6 +88,7 @@ void main() {
|
||||
'owner_id': 'user-1',
|
||||
'title': 'Q1 Todo',
|
||||
'priority': 1,
|
||||
'order': 1,
|
||||
'status': 'pending',
|
||||
'created_at': '2024-01-01T00:00:00Z',
|
||||
'updated_at': '2024-01-01T00:00:00Z',
|
||||
@@ -88,8 +96,9 @@ void main() {
|
||||
),
|
||||
);
|
||||
|
||||
final result = await todoApi.updateTodo('todo-1', priority: 1);
|
||||
final result = await todoApi.updateTodo('todo-1', priority: 1, order: 1);
|
||||
expect(result.priority, 1);
|
||||
expect(result.order, 1);
|
||||
});
|
||||
|
||||
test('priority 2 = important not urgent (Q3)', () async {
|
||||
@@ -101,6 +110,7 @@ void main() {
|
||||
'owner_id': 'user-1',
|
||||
'title': 'Q3 Todo',
|
||||
'priority': 2,
|
||||
'order': 2,
|
||||
'status': 'pending',
|
||||
'created_at': '2024-01-01T00:00:00Z',
|
||||
'updated_at': '2024-01-01T00:00:00Z',
|
||||
@@ -108,8 +118,9 @@ void main() {
|
||||
),
|
||||
);
|
||||
|
||||
final result = await todoApi.updateTodo('todo-2', priority: 2);
|
||||
final result = await todoApi.updateTodo('todo-2', priority: 2, order: 2);
|
||||
expect(result.priority, 2);
|
||||
expect(result.order, 2);
|
||||
});
|
||||
|
||||
test('priority 3 = urgent not important (Q2)', () async {
|
||||
@@ -121,6 +132,7 @@ void main() {
|
||||
'owner_id': 'user-1',
|
||||
'title': 'Q2 Todo',
|
||||
'priority': 3,
|
||||
'order': 0,
|
||||
'status': 'pending',
|
||||
'created_at': '2024-01-01T00:00:00Z',
|
||||
'updated_at': '2024-01-01T00:00:00Z',
|
||||
@@ -128,8 +140,37 @@ void main() {
|
||||
),
|
||||
);
|
||||
|
||||
final result = await todoApi.updateTodo('todo-3', priority: 3);
|
||||
final result = await todoApi.updateTodo('todo-3', priority: 3, order: 0);
|
||||
expect(result.priority, 3);
|
||||
expect(result.order, 0);
|
||||
});
|
||||
});
|
||||
|
||||
group('TodoApi.reorderTodos', () {
|
||||
test('calls batch reorder endpoint once', () async {
|
||||
when(() => mockClient.patch(any(), data: any(named: 'data'))).thenAnswer(
|
||||
(_) async => Response(
|
||||
requestOptions: RequestOptions(path: '/api/v1/todos/reorder'),
|
||||
data: {},
|
||||
),
|
||||
);
|
||||
|
||||
await todoApi.reorderTodos(const [
|
||||
TodoReorderItemPayload(id: 'todo-1', priority: 1, order: 0),
|
||||
TodoReorderItemPayload(id: 'todo-2', priority: 1, order: 1),
|
||||
]);
|
||||
|
||||
verify(
|
||||
() => mockClient.patch(
|
||||
'/api/v1/todos/reorder',
|
||||
data: {
|
||||
'items': [
|
||||
{'id': 'todo-1', 'priority': 1, 'order': 0},
|
||||
{'id': 'todo-2', 'priority': 1, 'order': 1},
|
||||
],
|
||||
},
|
||||
),
|
||||
).called(1);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
@@ -0,0 +1,108 @@
|
||||
"""replace todo due_at with order field
|
||||
|
||||
Revision ID: 202603200001
|
||||
Revises: 20260319_0004
|
||||
Create Date: 2026-03-20 12:00:00
|
||||
"""
|
||||
|
||||
from typing import Sequence, Union
|
||||
|
||||
from alembic import op
|
||||
import sqlalchemy as sa
|
||||
|
||||
revision: str = "202603200001"
|
||||
down_revision: Union[str, Sequence[str], None] = "20260319_0004"
|
||||
branch_labels: Union[str, Sequence[str], None] = None
|
||||
depends_on: Union[str, Sequence[str], None] = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
bind = op.get_bind()
|
||||
inspector = sa.inspect(bind)
|
||||
columns = {column["name"] for column in inspector.get_columns("todos")}
|
||||
has_order = "order" in columns
|
||||
has_due_at = "due_at" in columns
|
||||
|
||||
if not has_order:
|
||||
op.add_column("todos", sa.Column("order", sa.Integer(), nullable=True))
|
||||
|
||||
if has_due_at:
|
||||
op.execute(
|
||||
"""
|
||||
WITH ranked AS (
|
||||
SELECT
|
||||
id,
|
||||
ROW_NUMBER() OVER (
|
||||
PARTITION BY owner_id, priority
|
||||
ORDER BY due_at NULLS LAST, created_at ASC, id ASC
|
||||
) - 1 AS seq
|
||||
FROM todos
|
||||
WHERE deleted_at IS NULL
|
||||
)
|
||||
UPDATE todos t
|
||||
SET "order" = ranked.seq
|
||||
FROM ranked
|
||||
WHERE t.id = ranked.id
|
||||
"""
|
||||
)
|
||||
else:
|
||||
op.execute(
|
||||
"""
|
||||
WITH ranked AS (
|
||||
SELECT
|
||||
id,
|
||||
ROW_NUMBER() OVER (
|
||||
PARTITION BY owner_id, priority
|
||||
ORDER BY created_at ASC, id ASC
|
||||
) - 1 AS seq
|
||||
FROM todos
|
||||
WHERE deleted_at IS NULL
|
||||
)
|
||||
UPDATE todos t
|
||||
SET "order" = ranked.seq
|
||||
FROM ranked
|
||||
WHERE t.id = ranked.id AND t."order" IS NULL
|
||||
"""
|
||||
)
|
||||
|
||||
op.execute('UPDATE todos SET "order" = 0 WHERE "order" IS NULL')
|
||||
op.alter_column("todos", "order", nullable=False, server_default=sa.text("0"))
|
||||
|
||||
op.execute("DROP INDEX IF EXISTS ix_todos_owner_status_due")
|
||||
op.execute("DROP INDEX IF EXISTS ix_todos_pending_due")
|
||||
|
||||
op.execute(
|
||||
'CREATE INDEX IF NOT EXISTS ix_todos_owner_status_order ON todos (owner_id, status, priority, "order")'
|
||||
)
|
||||
op.execute(
|
||||
"CREATE INDEX IF NOT EXISTS ix_todos_pending_order ON todos (owner_id, priority, \"order\") WHERE status = 'pending'"
|
||||
)
|
||||
|
||||
if has_due_at:
|
||||
op.drop_column("todos", "due_at")
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
bind = op.get_bind()
|
||||
inspector = sa.inspect(bind)
|
||||
columns = {column["name"] for column in inspector.get_columns("todos")}
|
||||
has_order = "order" in columns
|
||||
has_due_at = "due_at" in columns
|
||||
|
||||
if not has_due_at:
|
||||
op.add_column(
|
||||
"todos", sa.Column("due_at", sa.DateTime(timezone=True), nullable=True)
|
||||
)
|
||||
|
||||
op.execute("DROP INDEX IF EXISTS ix_todos_pending_order")
|
||||
op.execute("DROP INDEX IF EXISTS ix_todos_owner_status_order")
|
||||
|
||||
op.execute(
|
||||
"CREATE INDEX IF NOT EXISTS ix_todos_owner_status_due ON todos (owner_id, status, due_at)"
|
||||
)
|
||||
op.execute(
|
||||
"CREATE INDEX IF NOT EXISTS ix_todos_pending_due ON todos (owner_id, due_at) WHERE status = 'pending'"
|
||||
)
|
||||
|
||||
if has_order:
|
||||
op.drop_column("todos", "order")
|
||||
@@ -26,7 +26,7 @@ class TodoPriority(int, Enum):
|
||||
|
||||
class Todo(TimestampMixin, SoftDeleteMixin, Base):
|
||||
__tablename__: str = "todos"
|
||||
__table_args__ = {"extend_existing": True}
|
||||
__table_args__: dict[str, bool] = {"extend_existing": True}
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(
|
||||
UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
|
||||
@@ -43,9 +43,10 @@ class Todo(TimestampMixin, SoftDeleteMixin, Base):
|
||||
String(1000),
|
||||
nullable=True,
|
||||
)
|
||||
due_at: Mapped[datetime | None] = mapped_column(
|
||||
DateTime(timezone=True),
|
||||
nullable=True,
|
||||
order: Mapped[int] = mapped_column(
|
||||
Integer,
|
||||
nullable=False,
|
||||
default=0,
|
||||
)
|
||||
priority: Mapped[int] = mapped_column(
|
||||
Integer,
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
from .contracts import TodoOrder
|
||||
|
||||
__all__ = ["TodoOrder"]
|
||||
@@ -0,0 +1,7 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Annotated
|
||||
|
||||
from pydantic import Field
|
||||
|
||||
TodoOrder = Annotated[int, Field(ge=0)]
|
||||
@@ -26,8 +26,8 @@ class TodoRepository(Protocol):
|
||||
owner_id: UUID,
|
||||
title: str,
|
||||
description: str | None = None,
|
||||
due_at: datetime | None = None,
|
||||
priority: int = TodoPriority.IMPORTANT_URGENT,
|
||||
order: int = 0,
|
||||
created_by: UUID | None = None,
|
||||
) -> Todo:
|
||||
"""Create a new todo."""
|
||||
@@ -42,8 +42,8 @@ class TodoRepository(Protocol):
|
||||
todo: Todo,
|
||||
title: str | None = None,
|
||||
description: str | None = None,
|
||||
due_at: datetime | None = None,
|
||||
priority: int | None = None,
|
||||
order: int | None = None,
|
||||
status: TodoStatus | None = None,
|
||||
completed_at: datetime | None = None,
|
||||
) -> Todo:
|
||||
@@ -79,6 +79,8 @@ class SQLAlchemyTodoRepository(BaseRepository[Todo]):
|
||||
- No HTTP exceptions - returns None or raises SQLAlchemyError
|
||||
"""
|
||||
|
||||
_session: AsyncSession
|
||||
|
||||
def __init__(self, session: AsyncSession) -> None:
|
||||
super().__init__(session, Todo)
|
||||
self._session = session
|
||||
@@ -88,8 +90,8 @@ class SQLAlchemyTodoRepository(BaseRepository[Todo]):
|
||||
owner_id: UUID,
|
||||
title: str,
|
||||
description: str | None = None,
|
||||
due_at: datetime | None = None,
|
||||
priority: int = TodoPriority.IMPORTANT_URGENT,
|
||||
order: int = 0,
|
||||
created_by: UUID | None = None,
|
||||
) -> Todo:
|
||||
try:
|
||||
@@ -97,8 +99,8 @@ class SQLAlchemyTodoRepository(BaseRepository[Todo]):
|
||||
owner_id=owner_id,
|
||||
title=title,
|
||||
description=description,
|
||||
due_at=due_at,
|
||||
priority=priority,
|
||||
order=order,
|
||||
status=TodoStatus.PENDING,
|
||||
created_by=created_by,
|
||||
)
|
||||
@@ -128,8 +130,8 @@ class SQLAlchemyTodoRepository(BaseRepository[Todo]):
|
||||
todo: Todo,
|
||||
title: str | None = None,
|
||||
description: str | None = None,
|
||||
due_at: datetime | None = None,
|
||||
priority: int | None = None,
|
||||
order: int | None = None,
|
||||
status: TodoStatus | None = None,
|
||||
completed_at: datetime | None = None,
|
||||
) -> Todo:
|
||||
@@ -138,10 +140,10 @@ class SQLAlchemyTodoRepository(BaseRepository[Todo]):
|
||||
todo.title = title
|
||||
if description is not None:
|
||||
todo.description = description
|
||||
if due_at is not None:
|
||||
todo.due_at = due_at
|
||||
if priority is not None:
|
||||
todo.priority = priority
|
||||
if order is not None:
|
||||
todo.order = order
|
||||
if status is not None:
|
||||
todo.status = status
|
||||
if completed_at is not None:
|
||||
@@ -167,7 +169,7 @@ class SQLAlchemyTodoRepository(BaseRepository[Todo]):
|
||||
select(Todo)
|
||||
.where(Todo.owner_id == owner_id)
|
||||
.where(Todo.deleted_at.is_(None))
|
||||
.order_by(Todo.priority.asc(), Todo.due_at.asc().nullslast())
|
||||
.order_by(Todo.priority.asc(), Todo.order.asc(), Todo.created_at.asc())
|
||||
)
|
||||
|
||||
if status is not None:
|
||||
|
||||
@@ -6,7 +6,13 @@ from uuid import UUID
|
||||
from fastapi import APIRouter, Depends, Query, status
|
||||
|
||||
from v1.todo.dependencies import get_todo_service
|
||||
from v1.todo.schemas import TodoComplete, TodoCreate, TodoResponse, TodoUpdate
|
||||
from v1.todo.schemas import (
|
||||
TodoComplete,
|
||||
TodoCreate,
|
||||
TodoReorderRequest,
|
||||
TodoResponse,
|
||||
TodoUpdate,
|
||||
)
|
||||
from v1.todo.service import TodoService
|
||||
|
||||
|
||||
@@ -42,6 +48,17 @@ async def get_todo(
|
||||
return await service.get_by_id(todo_id)
|
||||
|
||||
|
||||
@router.patch(
|
||||
"/reorder",
|
||||
status_code=status.HTTP_204_NO_CONTENT,
|
||||
)
|
||||
async def reorder_todos(
|
||||
payload: TodoReorderRequest,
|
||||
service: Annotated[TodoService, Depends(get_todo_service)],
|
||||
) -> None:
|
||||
await service.reorder(payload)
|
||||
|
||||
|
||||
@router.patch("/{todo_id}", response_model=TodoResponse)
|
||||
async def update_todo(
|
||||
todo_id: UUID,
|
||||
|
||||
@@ -5,14 +5,16 @@ from uuid import UUID
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field
|
||||
|
||||
from schemas.todo import TodoOrder
|
||||
|
||||
|
||||
class TodoCreate(BaseModel):
|
||||
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
|
||||
|
||||
title: str = Field(..., min_length=1, max_length=255)
|
||||
description: str | None = Field(None, max_length=1000)
|
||||
due_at: datetime | None = None
|
||||
priority: int = Field(1, ge=1, le=4)
|
||||
order: TodoOrder | None = None
|
||||
schedule_item_ids: list[UUID] = Field(default_factory=list)
|
||||
|
||||
|
||||
@@ -21,8 +23,8 @@ class TodoUpdate(BaseModel):
|
||||
|
||||
title: str | None = Field(None, min_length=1, max_length=255)
|
||||
description: str | None = Field(None, max_length=1000)
|
||||
due_at: datetime | None = None
|
||||
priority: int | None = Field(None, ge=1, le=4)
|
||||
order: TodoOrder | None = None
|
||||
status: Literal["pending", "done", "canceled"] | None = None
|
||||
schedule_item_ids: list[UUID] | None = None
|
||||
|
||||
@@ -43,8 +45,8 @@ class TodoResponse(BaseModel):
|
||||
owner_id: UUID
|
||||
title: str
|
||||
description: str | None
|
||||
due_at: datetime | None
|
||||
priority: int
|
||||
order: TodoOrder
|
||||
status: str
|
||||
completed_at: datetime | None
|
||||
created_at: datetime
|
||||
@@ -52,6 +54,20 @@ class TodoResponse(BaseModel):
|
||||
schedule_items: list[ScheduleItemBasic] = Field(default_factory=list)
|
||||
|
||||
|
||||
class TodoReorderItem(BaseModel):
|
||||
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
|
||||
|
||||
id: UUID
|
||||
priority: int = Field(..., ge=1, le=4)
|
||||
order: TodoOrder
|
||||
|
||||
|
||||
class TodoReorderRequest(BaseModel):
|
||||
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
|
||||
|
||||
items: list[TodoReorderItem] = Field(..., min_length=1)
|
||||
|
||||
|
||||
class TodoComplete(BaseModel):
|
||||
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
|
||||
|
||||
|
||||
@@ -13,7 +13,13 @@ from core.logging import get_logger
|
||||
from models.todos import Todo, TodoStatus
|
||||
from v1.schedule_items.repository import SQLAlchemyScheduleItemRepository
|
||||
from v1.todo.repository import TodoRepository
|
||||
from v1.todo.schemas import ScheduleItemBasic, TodoCreate, TodoResponse, TodoUpdate
|
||||
from v1.todo.schemas import (
|
||||
ScheduleItemBasic,
|
||||
TodoCreate,
|
||||
TodoReorderRequest,
|
||||
TodoResponse,
|
||||
TodoUpdate,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
@@ -52,12 +58,20 @@ class TodoService(BaseService):
|
||||
user_id = self.require_user_id()
|
||||
|
||||
try:
|
||||
order_value = request.order
|
||||
if order_value is None:
|
||||
todos_in_priority = await self._repository.list_by_owner(
|
||||
owner_id=user_id,
|
||||
priority=request.priority,
|
||||
)
|
||||
order_value = len(todos_in_priority)
|
||||
|
||||
todo = await self._repository.create(
|
||||
owner_id=user_id,
|
||||
title=request.title,
|
||||
description=request.description,
|
||||
due_at=request.due_at,
|
||||
priority=request.priority,
|
||||
order=order_value,
|
||||
created_by=user_id,
|
||||
)
|
||||
|
||||
@@ -144,8 +158,8 @@ class TodoService(BaseService):
|
||||
todo,
|
||||
title=request.title,
|
||||
description=request.description,
|
||||
due_at=request.due_at,
|
||||
priority=request.priority,
|
||||
order=request.order,
|
||||
status=status_enum,
|
||||
completed_at=completed_at,
|
||||
)
|
||||
@@ -253,6 +267,53 @@ class TodoService(BaseService):
|
||||
},
|
||||
)
|
||||
|
||||
async def reorder(self, request: TodoReorderRequest) -> None:
|
||||
user_id = self.require_user_id()
|
||||
|
||||
seen_ids: set[UUID] = set()
|
||||
original_priorities: set[int] = set()
|
||||
target_priorities: set[int] = set()
|
||||
|
||||
try:
|
||||
for item in request.items:
|
||||
if item.id in seen_ids:
|
||||
raise HTTPException(status_code=400, detail="Duplicate todo id")
|
||||
seen_ids.add(item.id)
|
||||
|
||||
todo = await self._repository.get_by_id(item.id)
|
||||
if todo is None:
|
||||
raise HTTPException(status_code=404, detail="Todo not found")
|
||||
if todo.owner_id != user_id:
|
||||
raise HTTPException(
|
||||
status_code=403, detail="Not authorized to reorder this todo"
|
||||
)
|
||||
|
||||
original_priorities.add(todo.priority)
|
||||
target_priorities.add(item.priority)
|
||||
|
||||
await self._repository.update(
|
||||
todo,
|
||||
priority=item.priority,
|
||||
order=item.order,
|
||||
)
|
||||
|
||||
affected_priorities = original_priorities.union(target_priorities)
|
||||
for priority in affected_priorities:
|
||||
todos = await self._repository.list_by_owner(
|
||||
owner_id=user_id,
|
||||
status=TodoStatus.PENDING,
|
||||
priority=priority,
|
||||
)
|
||||
todos.sort(key=lambda current: (current.order, current.created_at))
|
||||
for index, todo in enumerate(todos):
|
||||
if todo.order != index:
|
||||
await self._repository.update(todo, order=index)
|
||||
|
||||
await self._session.commit()
|
||||
except SQLAlchemyError:
|
||||
await self._session.rollback()
|
||||
raise HTTPException(status_code=503, detail="Todo service unavailable")
|
||||
|
||||
async def list_todos(
|
||||
self,
|
||||
status: str | None = None,
|
||||
@@ -287,7 +348,7 @@ class TodoService(BaseService):
|
||||
)
|
||||
|
||||
schedule_item_ids = await self._repository.get_schedule_items(todo.id)
|
||||
schedule_items = []
|
||||
schedule_items: list[ScheduleItemBasic] = []
|
||||
for item_id in schedule_item_ids:
|
||||
item = await self._schedule_item_repository.get_by_id(item_id)
|
||||
if item:
|
||||
@@ -305,8 +366,8 @@ class TodoService(BaseService):
|
||||
owner_id=todo.owner_id,
|
||||
title=todo.title,
|
||||
description=todo.description,
|
||||
due_at=todo.due_at,
|
||||
priority=todo.priority,
|
||||
order=todo.order,
|
||||
status=status_value,
|
||||
completed_at=todo.completed_at,
|
||||
created_at=todo.created_at,
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
from pydantic import ValidationError
|
||||
|
||||
from v1.todo.schemas import TodoCreate, TodoReorderRequest, TodoResponse, TodoUpdate
|
||||
|
||||
|
||||
def test_todo_create_accepts_zero_based_order() -> None:
|
||||
request = TodoCreate.model_validate({"title": "Test", "priority": 1, "order": 0})
|
||||
|
||||
assert request.order == 0
|
||||
|
||||
|
||||
def test_todo_create_rejects_due_at_field() -> None:
|
||||
try:
|
||||
TodoCreate.model_validate(
|
||||
{
|
||||
"title": "Test",
|
||||
"priority": 1,
|
||||
"order": 0,
|
||||
"due_at": "2026-01-01T00:00:00Z",
|
||||
}
|
||||
)
|
||||
except ValidationError:
|
||||
return
|
||||
|
||||
raise AssertionError("TodoCreate should reject due_at")
|
||||
|
||||
|
||||
def test_todo_update_rejects_negative_order() -> None:
|
||||
try:
|
||||
TodoUpdate.model_validate({"order": -1})
|
||||
except ValidationError:
|
||||
return
|
||||
|
||||
raise AssertionError("TodoUpdate should reject negative order")
|
||||
|
||||
|
||||
def test_todo_response_contains_order_without_due_at() -> None:
|
||||
payload = {
|
||||
"id": "9d72aa0f-e2d5-4de3-9b2d-4609f53376c0",
|
||||
"owner_id": "2f5b38fb-cb6f-44ef-8824-e7978f644bc2",
|
||||
"title": "Test",
|
||||
"description": None,
|
||||
"priority": 1,
|
||||
"order": 0,
|
||||
"status": "pending",
|
||||
"completed_at": None,
|
||||
"created_at": "2026-03-20T00:00:00Z",
|
||||
"updated_at": "2026-03-20T00:00:00Z",
|
||||
"schedule_items": [],
|
||||
}
|
||||
|
||||
response = TodoResponse.model_validate(payload)
|
||||
dumped = response.model_dump()
|
||||
|
||||
assert dumped["order"] == 0
|
||||
assert "due_at" not in dumped
|
||||
|
||||
|
||||
def test_todo_reorder_request_requires_non_empty_items() -> None:
|
||||
try:
|
||||
TodoReorderRequest(items=[])
|
||||
except ValidationError:
|
||||
return
|
||||
|
||||
raise AssertionError("TodoReorderRequest should reject empty items")
|
||||
@@ -0,0 +1,274 @@
|
||||
# 前端导航解耦与统一缓存重构设计
|
||||
|
||||
## 1. 背景与问题定义
|
||||
|
||||
当前 `apps` 端在日历（日/月）与待办页面中存在以下系统性问题：
|
||||
|
||||
1. 页面切换语义错误：将业务 tab 切换实现为 `push/go` 混用，导致页面重建与路由栈膨胀。
|
||||
2. 数据刷新触发错误：页面通过路由监听触发 `load`，频繁重复请求后端。
|
||||
3. 状态职责耦合：导航状态、页面状态、数据状态边界不清，导致“切换逻辑改动会牵出数据 bug”。
|
||||
4. 回主页语义不一致：Dock 首页按钮被 `canPop -> pop` 策略污染，行为变成“返回上页”。
|
||||
5. 缓存能力分散：仅存在局部的个人信息缓存（`SettingsUserCache`），缺少统一可复用缓存模块。
|
||||
|
||||
目标是完成一次结构化重构，建立「解耦的导航切换 + 统一缓存 + 可控一致性」体系。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
1. Home/Calendar/Todo 切换不重建主页面（保持页面实例与滚动状态）。
|
||||
2. 日/月视图切换不触发整页重建和无必要网络请求。
|
||||
3. 建立统一缓存模块，合并个人信息缓存并覆盖 Calendar/Todo 数据读取。
|
||||
4. 启动体验采用「本地优先 + 后台静默刷新」策略，减少进入 App 的重复请求。
|
||||
5. 数据只在必要时刷新：手动下拉、写操作失效、生命周期关键点、缓存策略命中。
|
||||
6. 主页按钮语义固定为“回主页”，不再变成“返回上一页”。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
1. 本次不改后端协议与接口契约。
|
||||
2. 本次不引入复杂离线同步冲突解决（如多端 CRDT）。
|
||||
3. 本次不引入全量本地数据库迁移（先基于 SharedPreferences 持久化层）。
|
||||
|
||||
## 3. 复杂度与风险分级
|
||||
|
||||
- Complexity: `S3`
|
||||
- 跨 router、calendar、todo、settings、DI 的架构级调整。
|
||||
- Risk Tier: `L1`
|
||||
- 不触及鉴权协议和支付等高风险域，但涉及导航返回栈与数据一致性高回归区。
|
||||
|
||||
## 4. 架构总览
|
||||
|
||||
### 4.1 导航分层
|
||||
|
||||
采用两级导航：
|
||||
|
||||
1. 一级（主容器）：`StatefulShellRoute.indexedStack`
|
||||
- 分支：Home / Calendar / Todo
|
||||
- 作用：保活分支页面，避免 tab 切换重建。
|
||||
2. 二级（分支内部）
|
||||
- Calendar 分支：管理 month/day 主视图切换 + event detail/edit/share 子路由。
|
||||
- Todo 分支：管理 list/detail/edit 子路由。
|
||||
|
||||
### 4.2 状态与数据边界
|
||||
|
||||
1. 导航状态：Shell 当前分支 index、Calendar 内部视图类型。
|
||||
2. UI 状态：选中日期、滚动位置、拖拽态、loading/error。
|
||||
3. 数据状态：统一缓存模块管理（内存 + 持久化 + 网络回写）。
|
||||
|
||||
结论：页面只发“意图”，不直接承担缓存与路由策略。
|
||||
|
||||
## 5. 统一缓存模块设计
|
||||
|
||||
## 5.1 模块结构
|
||||
|
||||
新增 `apps/lib/core/cache/`：
|
||||
|
||||
1. `cache_key.dart`
|
||||
- 统一 key 命名规范。
|
||||
2. `cache_policy.dart`
|
||||
- TTL、软/硬过期、最小刷新间隔、刷新原因枚举。
|
||||
3. `cache_entry.dart`
|
||||
- 标准缓存实体（data/fetchedAt/expiresAt/version/dirty）。
|
||||
4. `cache_store.dart`
|
||||
- 抽象接口（get/set/remove/invalidateNamespace）。
|
||||
5. `memory_cache_store.dart`
|
||||
- 会话级热缓存。
|
||||
6. `persistent_cache_store.dart`
|
||||
- 本地冷缓存（SharedPreferences JSON）。
|
||||
7. `hybrid_cache_store.dart`
|
||||
- 两级缓存协调与 singleflight 去重。
|
||||
8. `cache_invalidator.dart`
|
||||
- 统一精准失效入口。
|
||||
|
||||
### 5.2 key 设计（首版）
|
||||
|
||||
1. 用户信息
|
||||
- `user:profile:me`
|
||||
2. 日历
|
||||
- `calendar:day:YYYY-MM-DD`
|
||||
- `calendar:month:YYYY-MM`
|
||||
3. 待办
|
||||
- `todo:list:pending`
|
||||
- `todo:list:priority:<n>`（按需）
|
||||
- `todo:detail:<id>`（按需）
|
||||
|
||||
### 5.3 策略设计（平衡型）
|
||||
|
||||
读取顺序：`memory -> persistent -> network`。
|
||||
|
||||
刷新策略：
|
||||
|
||||
1. 软过期（stale-while-revalidate）
|
||||
- 先展示缓存，后台静默刷新。
|
||||
2. 硬过期
|
||||
- 超过硬过期后必须请求网络或提示数据过旧。
|
||||
3. 最小刷新间隔
|
||||
- 避免频繁切换/回前台引发抖动请求。
|
||||
|
||||
建议默认值：
|
||||
|
||||
1. `user:profile`：软过期 30min，硬过期 24h。
|
||||
2. `calendar:day`：软过期 2min，硬过期 30min。
|
||||
3. `calendar:month`：软过期 5min，硬过期 60min。
|
||||
4. `todo:list:pending`：软过期 2min，硬过期 30min。
|
||||
|
||||
### 5.4 个人信息缓存合并方案
|
||||
|
||||
现有 `SettingsUserCache` 并入统一缓存模块：
|
||||
|
||||
1. 新建 `UserProfileRepository`（或在现有 settings service 中引入统一缓存）。
|
||||
2. `getProfile()` 通过 hybrid cache 获取 `user:profile:me`。
|
||||
3. 更新 profile 成功后立即写回缓存并同步持久化。
|
||||
4. 登出/会话失效时统一调用 `invalidateNamespace('user')`。
|
||||
|
||||
## 6. 一致性风险与解决方案
|
||||
|
||||
平衡型缓存会存在“短暂陈旧窗口”。本设计通过以下机制将体验风险降到可接受范围。
|
||||
|
||||
### 6.1 触发刷新矩阵
|
||||
|
||||
1. 手动下拉刷新：强制网络刷新。
|
||||
2. 写操作成功：精准失效受影响 key 并触发回填。
|
||||
3. App 回前台：若超过最小刷新间隔，触发静默刷新。
|
||||
4. 网络离线 -> 在线：触发静默刷新。
|
||||
5. 进入关键详情页：按策略进行 freshness check。
|
||||
|
||||
### 6.2 写后一致性
|
||||
|
||||
1. 乐观更新：本地先更新 UI 与缓存，避免“我刚改完却没变”。
|
||||
2. 失败回滚：API 失败时恢复旧值并 Toast 提示。
|
||||
3. 精准失效：不做全局清空，只失效关联 key，兼顾一致性与性能。
|
||||
|
||||
### 6.3 并发安全
|
||||
|
||||
1. singleflight：同 key 同时只允许一个网络请求。
|
||||
2. 版本保护：缓存写入比较 `updatedAt/version`，拒绝旧响应覆盖新状态。
|
||||
3. 失败兜底：请求失败不清空旧缓存，保持可读并允许重试。
|
||||
|
||||
### 6.4 可见性保障
|
||||
|
||||
1. 页面可显示“上次同步时间”（轻提示）。
|
||||
2. 硬过期数据需可见提醒（弱提示，不阻断基础浏览）。
|
||||
3. 提供稳定手动刷新入口。
|
||||
|
||||
## 7. 导航与页面职责重构
|
||||
|
||||
### 7.1 路由重构
|
||||
|
||||
1. `app_router` 引入 shell 分支，不再平铺所有主页面。
|
||||
2. Dock 切换改为 branch index 切换，不再 `push` 主页面。
|
||||
3. Calendar 内部 month/day 切换改为视图切换，不新增栈层。
|
||||
4. 事件详情/编辑等保留 `push`（细节页合理叠栈）。
|
||||
|
||||
### 7.2 回主页逻辑修正
|
||||
|
||||
1. Dock Home 统一执行“切到 Home 分支/`go('/home')`”。
|
||||
2. `returnToHomePreserveState` 仅用于非 Dock 的返回策略场景。
|
||||
3. 消除 `canPop -> pop` 对主页按钮语义的影响。
|
||||
|
||||
### 7.3 页面职责收敛
|
||||
|
||||
1. Calendar/Todo 页面移除路由监听触发 `load`。
|
||||
2. 页面只调用 repository：
|
||||
- `get(policy)`
|
||||
- `refresh(force: true)`
|
||||
- `mutate(...) + invalidate(...)`
|
||||
3. 页面不直接感知“缓存在哪一层”。
|
||||
|
||||
## 8. 分阶段实施计划（里程碑）
|
||||
|
||||
### M1 导航壳层与切换语义
|
||||
|
||||
1. 引入 shell + 分支保活。
|
||||
2. Dock 接口改造与主 tab 切换实现。
|
||||
3. Home 按钮语义修正。
|
||||
|
||||
### M2 统一缓存骨架
|
||||
|
||||
1. 新增 core cache 模块。
|
||||
2. 接入 user profile（替换 `SettingsUserCache`）。
|
||||
3. DI 注入 cache store 与 invalidator。
|
||||
|
||||
### M3 Calendar 接入
|
||||
|
||||
1. 引入 `CalendarRepository` 与 day/month key。
|
||||
2. 移除 route listener 自动刷新。
|
||||
3. 切换 month/day 时默认走缓存，不触发无必要请求。
|
||||
|
||||
### M4 Todo 接入
|
||||
|
||||
1. 引入 `TodoRepository` 与 list/detail key。
|
||||
2. 拖拽、完成、编辑后的精准失效。
|
||||
3. 下拉刷新走强制网络。
|
||||
|
||||
### M5 清理与验证
|
||||
|
||||
1. 清理旧缓存与重复加载逻辑。
|
||||
2. 补齐测试与性能观测。
|
||||
3. 评估参数并收敛默认策略。
|
||||
|
||||
## 9. 验收标准
|
||||
|
||||
### 9.1 体验验收
|
||||
|
||||
1. Home/Calendar/Todo 切换无明显重建卡顿。
|
||||
2. 日/月切换响应明显变快。
|
||||
3. 首次冷启动可先看到本地缓存内容。
|
||||
4. Dock Home 始终回主页。
|
||||
|
||||
### 9.2 网络验收
|
||||
|
||||
1. 切换页面时网络请求显著减少。
|
||||
2. 写操作后关联数据可及时更新。
|
||||
3. 手动刷新可强制拉取并回写缓存。
|
||||
|
||||
### 9.3 一致性验收
|
||||
|
||||
1. 不出现旧响应覆盖新数据。
|
||||
2. 离线后恢复在线可自动静默同步。
|
||||
3. 软过期/硬过期行为符合策略定义。
|
||||
|
||||
## 10. 测试与验证计划
|
||||
|
||||
### 10.1 单元测试
|
||||
|
||||
1. `hybrid_cache_store`：命中链路、singleflight、软硬过期判定。
|
||||
2. `cache_invalidator`：写操作触发的 key 精准失效。
|
||||
3. repository：读缓存、后台刷新、失败兜底、版本保护。
|
||||
|
||||
### 10.2 组件/页面测试（高回归）
|
||||
|
||||
1. Dock 切换不重建分支主页面。
|
||||
2. 日/月切换不重复触发全量加载。
|
||||
3. Home 按钮行为稳定。
|
||||
|
||||
### 10.3 集成回归
|
||||
|
||||
1. Calendar -> Todo -> Calendar 多轮切换请求计数。
|
||||
2. Todo 完成后列表更新与缓存一致性。
|
||||
3. profile 更新后设置页/其他依赖页可见一致。
|
||||
|
||||
## 11. 风险与回滚
|
||||
|
||||
### 11.1 主要风险
|
||||
|
||||
1. 导航壳层改造可能引发深链与返回栈回归。
|
||||
2. 缓存策略参数不当可能造成陈旧感。
|
||||
3. 早期失效 key 设计不完整可能出现局部不刷新。
|
||||
|
||||
### 11.2 控制策略
|
||||
|
||||
1. 按里程碑逐步落地，每个里程碑可单独回滚。
|
||||
2. 默认保留手动刷新兜底。
|
||||
3. 增加请求计数与缓存命中日志（开发态）。
|
||||
|
||||
### 11.3 回滚策略
|
||||
|
||||
1. 若 M1 不稳定，可先回退 shell 改造并保留缓存模块。
|
||||
2. 若缓存接入问题集中，可按域回退（user/calendar/todo 分域开关）。
|
||||
|
||||
## 12. 待确认参数（实施前锁定）
|
||||
|
||||
1. 软/硬过期默认值是否按本设计直接采用。
|
||||
2. 是否立即展示“上次同步时间”。
|
||||
3. 是否在首版启用“网络恢复自动静默刷新”。
|
||||
@@ -0,0 +1,438 @@
|
||||
# 前端导航解耦与统一缓存重构 Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** 完成 Home/Calendar/Todo 的解耦切换与统一缓存改造，实现本地优先显示、后台静默刷新、写后精准失效，并修复 Dock 回主页语义。
|
||||
|
||||
**Architecture:** 路由层采用 `StatefulShellRoute.indexedStack` 维持主分支保活；数据层新增 `core/cache` 统一缓存模块（memory + persistent + hybrid）；业务层通过 repository 接入缓存策略，页面仅负责发意图和渲染状态。写操作触发精准失效，读取遵循 soft/hard TTL + minimum refresh interval。
|
||||
|
||||
**Tech Stack:** Flutter, go_router, get_it, shared_preferences, flutter_test, mocktail
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 建立统一缓存核心模型与策略
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/lib/core/cache/cache_entry.dart`
|
||||
- Create: `apps/lib/core/cache/cache_key.dart`
|
||||
- Create: `apps/lib/core/cache/cache_policy.dart`
|
||||
- Test: `apps/test/core/cache/cache_policy_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
import 'package:flutter_test/flutter_test.dart';
|
||||
import 'package:social_app/core/cache/cache_policy.dart';
|
||||
|
||||
void main() {
|
||||
test('soft expired should allow stale read with background refresh', () {
|
||||
final now = DateTime(2026, 3, 20, 12);
|
||||
final policy = CachePolicy(
|
||||
softTtl: const Duration(minutes: 2),
|
||||
hardTtl: const Duration(minutes: 30),
|
||||
minRefreshInterval: const Duration(minutes: 1),
|
||||
);
|
||||
|
||||
final fetchedAt = now.subtract(const Duration(minutes: 3));
|
||||
final decision = policy.evaluate(now: now, fetchedAt: fetchedAt);
|
||||
expect(decision.canUseCached, true);
|
||||
expect(decision.shouldRefreshInBackground, true);
|
||||
expect(decision.mustBlockForNetwork, false);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/cache_policy_test.dart`
|
||||
Expected: FAIL with missing cache policy symbols.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
class CacheDecision {
|
||||
final bool canUseCached;
|
||||
final bool shouldRefreshInBackground;
|
||||
final bool mustBlockForNetwork;
|
||||
const CacheDecision({
|
||||
required this.canUseCached,
|
||||
required this.shouldRefreshInBackground,
|
||||
required this.mustBlockForNetwork,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/cache_policy_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/core/cache/cache_entry.dart apps/lib/core/cache/cache_key.dart apps/lib/core/cache/cache_policy.dart apps/test/core/cache/cache_policy_test.dart
|
||||
git commit -m "feat: add unified cache policy primitives"
|
||||
```
|
||||
|
||||
### Task 2: 实现 memory/persistent/hybrid cache store（含 singleflight）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/lib/core/cache/cache_store.dart`
|
||||
- Create: `apps/lib/core/cache/memory_cache_store.dart`
|
||||
- Create: `apps/lib/core/cache/persistent_cache_store.dart`
|
||||
- Create: `apps/lib/core/cache/hybrid_cache_store.dart`
|
||||
- Test: `apps/test/core/cache/hybrid_cache_store_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('same key concurrent load should execute loader once', () async {
|
||||
var calls = 0;
|
||||
final store = HybridCacheStore(...);
|
||||
Future<String> loader() async {
|
||||
calls += 1;
|
||||
return 'ok';
|
||||
}
|
||||
await Future.wait([
|
||||
store.getOrLoad<String>('k', loader: loader),
|
||||
store.getOrLoad<String>('k', loader: loader),
|
||||
]);
|
||||
expect(calls, 1);
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/hybrid_cache_store_test.dart`
|
||||
Expected: FAIL with missing HybridCacheStore.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
final Map<String, Future<dynamic>> _inflight = {};
|
||||
```
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/hybrid_cache_store_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/core/cache/cache_store.dart apps/lib/core/cache/memory_cache_store.dart apps/lib/core/cache/persistent_cache_store.dart apps/lib/core/cache/hybrid_cache_store.dart apps/test/core/cache/hybrid_cache_store_test.dart
|
||||
git commit -m "feat: implement hybrid cache store with singleflight"
|
||||
```
|
||||
|
||||
### Task 3: 接入 DI 与统一失效器
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/lib/core/cache/cache_invalidator.dart`
|
||||
- Modify: `apps/lib/core/di/injection.dart`
|
||||
- Test: `apps/test/core/cache/cache_invalidator_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('invalidate calendar day should also invalidate month key', () {
|
||||
final inv = CacheInvalidator(...);
|
||||
inv.invalidateCalendarDay(DateTime(2026, 3, 20));
|
||||
expect(inv.wasInvalidated('calendar:day:2026-03-20'), true);
|
||||
expect(inv.wasInvalidated('calendar:month:2026-03'), true);
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/cache_invalidator_test.dart`
|
||||
Expected: FAIL.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
class CacheInvalidator {
|
||||
void invalidateCalendarDay(DateTime date) { /* invalidate day + month */ }
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/cache_invalidator_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/core/cache/cache_invalidator.dart apps/lib/core/di/injection.dart apps/test/core/cache/cache_invalidator_test.dart
|
||||
git commit -m "refactor: wire unified cache and invalidator in di"
|
||||
```
|
||||
|
||||
### Task 4: 合并个人信息缓存（替换 SettingsUserCache）
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/settings/data/services/settings_user_cache.dart`
|
||||
- Create: `apps/lib/features/settings/data/services/user_profile_cache_repository.dart`
|
||||
- Modify: `apps/lib/features/settings/ui/screens/settings_screen.dart`
|
||||
- Test: `apps/test/features/settings/data/services/settings_user_cache_test.dart`
|
||||
- Create: `apps/test/features/settings/data/services/user_profile_cache_repository_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('repository should return persistent cache first then refresh in background', () async {
|
||||
// Arrange cached profile in persistent store
|
||||
// Assert immediate cached result + refresh called once
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/features/settings/data/services/user_profile_cache_repository_test.dart`
|
||||
Expected: FAIL.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
class UserProfileCacheRepository {
|
||||
Future<UserResponse> getProfile({bool forceRefresh = false}) async { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4: Run tests to verify they pass**
|
||||
|
||||
Run: `cd apps && flutter test test/features/settings/data/services/settings_user_cache_test.dart test/features/settings/data/services/user_profile_cache_repository_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/settings/data/services/settings_user_cache.dart apps/lib/features/settings/data/services/user_profile_cache_repository.dart apps/lib/features/settings/ui/screens/settings_screen.dart apps/test/features/settings/data/services/settings_user_cache_test.dart apps/test/features/settings/data/services/user_profile_cache_repository_test.dart
|
||||
git commit -m "refactor: merge profile cache into unified cache repository"
|
||||
```
|
||||
|
||||
### Task 5: 路由改造为 StatefulShellRoute + Dock 切换分支
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/core/router/app_router.dart`
|
||||
- Modify: `apps/lib/core/router/app_routes.dart`
|
||||
- Modify: `apps/lib/features/calendar/ui/widgets/bottom_dock.dart`
|
||||
- Modify: `apps/lib/features/home/ui/navigation/home_return_policy.dart`
|
||||
- Test: `apps/test/core/router/app_routes_test.dart`
|
||||
- Modify: `apps/test/features/home/ui/navigation/home_return_policy_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('dock home action should always resolve to goHome', () {
|
||||
final action = resolveHomeReturnAction(canPop: true, isAuthEntry: false);
|
||||
expect(action, HomeReturnAction.goHomeForDock);
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/features/home/ui/navigation/home_return_policy_test.dart`
|
||||
Expected: FAIL with old behavior.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
enum HomeReturnAction { pop, goHome, goHomeForDock }
|
||||
```
|
||||
|
||||
**Step 4: Run tests to verify they pass**
|
||||
|
||||
Run: `cd apps && flutter test test/core/router/app_routes_test.dart test/features/home/ui/navigation/home_return_policy_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/core/router/app_router.dart apps/lib/core/router/app_routes.dart apps/lib/features/calendar/ui/widgets/bottom_dock.dart apps/lib/features/home/ui/navigation/home_return_policy.dart apps/test/core/router/app_routes_test.dart apps/test/features/home/ui/navigation/home_return_policy_test.dart
|
||||
git commit -m "feat: switch main navigation to stateful shell tabs"
|
||||
```
|
||||
|
||||
### Task 6: Calendar repository 化并移除路由监听刷新
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/lib/features/calendar/data/services/calendar_repository.dart`
|
||||
- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart`
|
||||
- Modify: `apps/lib/features/calendar/ui/screens/calendar_month_screen.dart`
|
||||
- Modify: `apps/lib/features/calendar/ui/calendar_state_manager.dart`
|
||||
- Create: `apps/test/features/calendar/data/services/calendar_repository_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('getDayEvents returns cache immediately and refreshes in background', () async {
|
||||
// Arrange cache day key
|
||||
// Assert cached list emitted before network completion
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/features/calendar/data/services/calendar_repository_test.dart`
|
||||
Expected: FAIL.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
class CalendarRepository {
|
||||
Future<List<ScheduleItemModel>> getDayEvents(DateTime date, {bool forceRefresh = false}) async { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4: Run tests to verify they pass**
|
||||
|
||||
Run: `cd apps && flutter test test/features/calendar/data/services/calendar_repository_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/calendar/data/services/calendar_repository.dart apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart apps/lib/features/calendar/ui/screens/calendar_month_screen.dart apps/lib/features/calendar/ui/calendar_state_manager.dart apps/test/features/calendar/data/services/calendar_repository_test.dart
|
||||
git commit -m "refactor: decouple calendar screens from route-driven reload"
|
||||
```
|
||||
|
||||
### Task 7: Todo repository 化与写后精准失效
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/lib/features/todo/data/todo_repository.dart`
|
||||
- Modify: `apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart`
|
||||
- Modify: `apps/lib/features/todo/data/todo_api.dart`
|
||||
- Create: `apps/test/features/todo/todo_repository_test.dart`
|
||||
- Modify: `apps/test/features/todo/quadrant_drag_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('complete todo should optimistically update and invalidate pending list key', () async {
|
||||
// assert local list updated first, invalidator called
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/features/todo/todo_repository_test.dart`
|
||||
Expected: FAIL.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
class TodoRepository {
|
||||
Future<void> completeTodo(String id) async { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4: Run tests to verify they pass**
|
||||
|
||||
Run: `cd apps && flutter test test/features/todo/todo_repository_test.dart test/features/todo/quadrant_drag_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/todo/data/todo_repository.dart apps/lib/features/todo/ui/screens/todo_quadrants_screen.dart apps/lib/features/todo/data/todo_api.dart apps/test/features/todo/todo_repository_test.dart apps/test/features/todo/quadrant_drag_test.dart
|
||||
git commit -m "feat: add todo cache repository and precise invalidation"
|
||||
```
|
||||
|
||||
### Task 8: App 生命周期与网络恢复刷新策略
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/lib/core/cache/cache_refresh_coordinator.dart`
|
||||
- Modify: `apps/lib/main.dart`
|
||||
- Create: `apps/test/core/cache/cache_refresh_coordinator_test.dart`
|
||||
|
||||
**Step 1: Write the failing test**
|
||||
|
||||
```dart
|
||||
test('resume should trigger refresh only when min interval elapsed', () {
|
||||
// Arrange last refreshed timestamp
|
||||
// Assert callback invocation count
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/cache_refresh_coordinator_test.dart`
|
||||
Expected: FAIL.
|
||||
|
||||
**Step 3: Write minimal implementation**
|
||||
|
||||
```dart
|
||||
class CacheRefreshCoordinator with WidgetsBindingObserver { ... }
|
||||
```
|
||||
|
||||
**Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cd apps && flutter test test/core/cache/cache_refresh_coordinator_test.dart`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/core/cache/cache_refresh_coordinator.dart apps/lib/main.dart apps/test/core/cache/cache_refresh_coordinator_test.dart
|
||||
git commit -m "feat: add app lifecycle refresh coordinator"
|
||||
```
|
||||
|
||||
### Task 9: 全量验证与文档同步
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/protocols/*`（仅当路由/数据契约文档需更新时）
|
||||
- Modify: `docs/plans/2026-03-20-navigation-cache-decoupling-design.md`（回填最终参数）
|
||||
|
||||
**Step 1: Run focused tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd apps && flutter test test/core/cache test/features/settings/data/services/settings_user_cache_test.dart test/features/calendar test/features/todo test/features/home/ui/navigation/home_return_policy_test.dart test/core/router/app_routes_test.dart
|
||||
```
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
**Step 2: Run app-level verification**
|
||||
|
||||
Run: `cd apps && flutter test`
|
||||
Expected: PASS.
|
||||
|
||||
**Step 3: Static checks**
|
||||
|
||||
Run: `cd apps && flutter analyze`
|
||||
Expected: No errors.
|
||||
|
||||
**Step 4: Manual verification checklist**
|
||||
|
||||
1. 冷启动先显示缓存，随后静默更新。
|
||||
2. Home/Calendar/Todo 来回切换不重建主页面。
|
||||
3. 日/月切换不触发无必要请求。
|
||||
4. Dock Home 始终回主页。
|
||||
5. 写后数据可见一致，失败可回滚提示。
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/plans/2026-03-20-navigation-cache-decoupling-design.md docs/protocols
|
||||
git commit -m "docs: finalize navigation decoupling and unified cache rollout"
|
||||
```
|
||||
|
||||
## 实施顺序约束
|
||||
|
||||
1. 必须先完成 Task 1-3 再改业务页面（否则会出现重复实现）。
|
||||
2. Task 5（路由壳层）与 Task 6/7（业务接入）要分开提交，便于回滚。
|
||||
3. 每个 Task 的测试必须在本 Task 完成后立即执行，避免堆积回归。
|
||||
4. 不允许在未通过 focused tests 的情况下进入全量验证。
|
||||
|
||||
## 回滚策略
|
||||
|
||||
1. 若导航回归：回滚 Task 5 提交，保留缓存模块提交。
|
||||
2. 若缓存一致性异常：优先回滚 Task 6/7 的 repository 接入提交。
|
||||
3. 若生命周期刷新过于频繁：关闭 Task 8 coordinator 挂载，保留手动刷新兜底。
|
||||
|
||||
## Done 定义
|
||||
|
||||
1. 所有测试与 analyze 通过。
|
||||
2. 主页按钮行为稳定，无“返回上一页”误行为。
|
||||
3. 切换页面请求数明显下降，写后一致性符合设计预期。
|
||||
4. 统一缓存已接管用户信息、日历、待办三域。
|
||||
@@ -0,0 +1,43 @@
|
||||
# Todo Data Protocol
|
||||
|
||||
## Scope
|
||||
|
||||
Defines the backend/frontend data contract for `/api/v1/todos`.
|
||||
|
||||
## Field Definitions
|
||||
|
||||
- `id`: string (UUID)
|
||||
- `owner_id`: string (UUID)
|
||||
- `title`: string, `1..255`
|
||||
- `description`: string or `null`, max `1000`
|
||||
- `priority`: int, quadrant value in `[1, 4]`
|
||||
- `order`: int, zero-based ordering inside the same `priority` bucket, `>= 0`
|
||||
- `status`: enum string: `pending | done | canceled`
|
||||
- `completed_at`: datetime string or `null`
|
||||
- `created_at`: datetime string
|
||||
- `updated_at`: datetime string
|
||||
- `schedule_items`: array
|
||||
|
||||
## Request Contracts
|
||||
|
||||
### Create Todo (`POST /api/v1/todos`)
|
||||
|
||||
- required: `title`
|
||||
- optional: `description`, `priority`, `order`, `schedule_item_ids`
|
||||
- `order` omitted: backend assigns append position in the target quadrant.
|
||||
|
||||
### Update Todo (`PATCH /api/v1/todos/{todo_id}`)
|
||||
|
||||
- optional: `title`, `description`, `priority`, `order`, `status`, `schedule_item_ids`
|
||||
- `order` is interpreted inside the todo's final `priority` quadrant.
|
||||
|
||||
## Ordering Rules
|
||||
|
||||
- Todo list API returns items sorted by `priority ASC`, then `order ASC`.
|
||||
- Drag reorder in same quadrant updates `order` to a continuous sequence starting from `0`.
|
||||
- Drag move across quadrants updates both `priority` and `order`, and source/target quadrants should both stay contiguous from `0`.
|
||||
|
||||
## Compatibility Notes
|
||||
|
||||
- `due_at` is removed from todo protocol.
|
||||
- Clients must not send or depend on `due_at` for todo ordering.
|
||||
-391
@@ -1,391 +0,0 @@
|
||||
# Calendar Reminder Unified Interaction Implementation Plan
|
||||
|
||||
> **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:** 交付“系统通知主触达 + 前台统一提醒面板”的提醒链路，保证 iOS/Android 在前台、后台、终止态都可执行“稍后提醒”和“取消并归档（内部 archive）”。
|
||||
|
||||
**Architecture:** `LocalNotificationService` 仅做调度与平台桥接；`ReminderActionExecutor` 作为唯一动作执行器；新增 `ReminderPresentationCoordinator` + `ReminderActionSheet` 负责前台展示；新增持久化幂等与 cold-start 回放，避免动作丢失/重复执行。
|
||||
|
||||
**Tech Stack:** Flutter, flutter_local_notifications, SharedPreferences, Dart isolate callback, AndroidManifest receiver, iOS AppDelegate callback, Flutter tests.
|
||||
|
||||
---
|
||||
|
||||
## File Structure (Locked Before Tasks)
|
||||
|
||||
### Protocol (Must First)
|
||||
- Modify: `docs/protocols/calendar/reminder-alert-lifecycle.md`
|
||||
|
||||
### Reminder Core
|
||||
- Modify: `apps/lib/core/notifications/local_notification_service.dart`
|
||||
- Create: `apps/lib/core/notifications/reminder_notification_callbacks.dart`
|
||||
- Modify: `apps/lib/features/calendar/reminders/models/reminder_action.dart`
|
||||
- Modify: `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/reminder_action_dedupe_store.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/reminder_cold_start_queue.dart`
|
||||
|
||||
### Foreground UI
|
||||
- Create: `apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart`
|
||||
|
||||
### App & Platform Wiring
|
||||
- Modify: `apps/lib/main.dart`
|
||||
- Modify: `apps/android/app/src/main/AndroidManifest.xml`
|
||||
- Modify: `apps/ios/Runner/AppDelegate.swift`
|
||||
|
||||
### Tests
|
||||
- Modify: `apps/test/features/calendar/reminders/reminder_action_executor_test.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_action_sheet_test.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_permission_fallback_test.dart`
|
||||
- Create: `apps/test/platform/android_manifest_notification_action_test.dart`
|
||||
- Create: `apps/test/platform/ios_app_delegate_notification_callback_test.dart`
|
||||
|
||||
### Cleanup
|
||||
- Create: `docs/todo/calendar-reminder-migration-checklist.md`
|
||||
|
||||
---
|
||||
|
||||
### Task 0: 协议先行更新（必须）
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/protocols/calendar/reminder-alert-lifecycle.md`
|
||||
|
||||
- [ ] **Step 1: 更新动作语义文案**
|
||||
```text
|
||||
展示文案“取消”映射到内部动作 archive
|
||||
```
|
||||
- [ ] **Step 2: 增加幂等键协议**
|
||||
```text
|
||||
actionExecutionId = notificationId + actionId + fireTimeBucket
|
||||
```
|
||||
- [ ] **Step 3: 增加 cold-start queue 回放协议**
|
||||
```text
|
||||
顺序回放，单条失败不阻塞后续
|
||||
```
|
||||
- [ ] **Step 4: 运行协议自检**
|
||||
Run: `rg "archive|actionExecutionId|cold-start" docs/protocols/calendar/reminder-alert-lifecycle.md`
|
||||
Expected: 命中新增规则
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add docs/protocols/calendar/reminder-alert-lifecycle.md
|
||||
git commit -m "docs: align reminder protocol with archive and idempotency"
|
||||
```
|
||||
|
||||
### Task 1: 动作语义收敛（TDD）
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/test/features/calendar/reminders/reminder_action_executor_test.dart`
|
||||
- Modify: `apps/lib/features/calendar/reminders/models/reminder_action.dart`
|
||||
- Modify: `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（archive 入口）**
|
||||
```dart
|
||||
test('archive action cancels reminder and archives event', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 运行失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_executor_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 最小实现（增加 archive 枚举并接入 executor）**
|
||||
```dart
|
||||
enum ReminderAction { archive('archive'), snooze10m('snooze_10m'), ... }
|
||||
```
|
||||
- [ ] **Step 4: 运行通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_executor_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add apps/lib/features/calendar/reminders/models/reminder_action.dart apps/lib/features/calendar/reminders/reminder_action_executor.dart apps/test/features/calendar/reminders/reminder_action_executor_test.dart
|
||||
git commit -m "refactor: unify reminder action semantics to archive"
|
||||
```
|
||||
|
||||
### Task 2: 持久化幂等（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/reminder_action_dedupe_store.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（重启后仍去重）**
|
||||
```dart
|
||||
test('same actionExecutionId is rejected after restart', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 实现最小 store**
|
||||
```dart
|
||||
Future<bool> markIfNew(String actionExecutionId)
|
||||
```
|
||||
- [ ] **Step 4: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_dedupe_store_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add apps/lib/features/calendar/reminders/reminder_action_dedupe_store.dart apps/test/features/calendar/reminders/reminder_action_dedupe_store_test.dart
|
||||
git commit -m "feat: add persistent reminder action dedupe store"
|
||||
```
|
||||
|
||||
### Task 3: 冷启动回放队列（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/reminder_cold_start_queue.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（顺序回放）**
|
||||
```dart
|
||||
test('replays actions in receive order', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 写失败测试（单条失败不阻塞）**
|
||||
```dart
|
||||
test('continues replay after one action failure', () async {});
|
||||
```
|
||||
- [ ] **Step 3: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 4: 最小实现队列**
|
||||
```dart
|
||||
Future<void> replaySequentially(Future<void> Function(...) handler)
|
||||
```
|
||||
- [ ] **Step 5: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_cold_start_queue_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 6: Commit**
|
||||
```bash
|
||||
git add apps/lib/features/calendar/reminders/reminder_cold_start_queue.dart apps/test/features/calendar/reminders/reminder_cold_start_queue_test.dart
|
||||
git commit -m "feat: add reminder cold-start replay queue"
|
||||
```
|
||||
|
||||
### Task 4: 通知桥接映射（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart`
|
||||
- Modify: `apps/lib/core/notifications/local_notification_service.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（cancel 文案映射 archive）**
|
||||
```dart
|
||||
test('maps cancel action button to ReminderAction.archive', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_notification_bridge_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 接入 dedupe store + bridge**
|
||||
```dart
|
||||
if (!await dedupeStore.markIfNew(actionExecutionId)) return;
|
||||
```
|
||||
- [ ] **Step 4: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_notification_bridge_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add apps/lib/core/notifications/local_notification_service.dart apps/test/features/calendar/reminders/reminder_notification_bridge_test.dart
|
||||
git commit -m "feat: map reminder notification actions through unified bridge"
|
||||
```
|
||||
|
||||
### Task 5: 前台协调器（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（仅前台展示）**
|
||||
```dart
|
||||
test('shows reminder sheet only in app active state', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 写失败测试（去重窗口）**
|
||||
```dart
|
||||
test('suppresses duplicate presentation in dedupe window', () async {});
|
||||
```
|
||||
- [ ] **Step 3: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 4: 最小实现协调器**
|
||||
- [ ] **Step 5: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_presentation_coordinator_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 6: Commit**
|
||||
```bash
|
||||
git add apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart apps/test/features/calendar/reminders/reminder_presentation_coordinator_test.dart
|
||||
git commit -m "feat: add reminder foreground presentation coordinator"
|
||||
```
|
||||
|
||||
### Task 6: 前台提醒面板组件（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_action_sheet_test.dart`
|
||||
- Create: `apps/lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（稍后提醒按钮）**
|
||||
```dart
|
||||
testWidgets('tap snooze triggers snooze callback', (tester) async {});
|
||||
```
|
||||
- [ ] **Step 2: 写失败测试（归档按钮）**
|
||||
```dart
|
||||
testWidgets('tap archive triggers archive callback', (tester) async {});
|
||||
```
|
||||
- [ ] **Step 3: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_sheet_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 4: 最小实现 token 驱动 UI**
|
||||
- [ ] **Step 5: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_action_sheet_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 6: Commit**
|
||||
```bash
|
||||
git add apps/lib/features/calendar/reminders/ui/widgets/reminder_action_sheet.dart apps/test/features/calendar/reminders/reminder_action_sheet_test.dart
|
||||
git commit -m "feat: add reusable reminder action sheet"
|
||||
```
|
||||
|
||||
### Task 7: App 接线与后台入口（TDD）
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/main.dart`
|
||||
- Create/Modify: `apps/lib/core/notifications/reminder_notification_callbacks.dart`
|
||||
- Modify: `apps/lib/core/notifications/local_notification_service.dart`
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_notification_callbacks_test.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（后台入口是 top-level + pragma）**
|
||||
```dart
|
||||
test('background notification callback is top-level entry-point', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_notification_callbacks_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 接线 initialize 注册前台/后台回调**
|
||||
- [ ] **Step 4: 接线 foreground presenter 到 coordinator**
|
||||
- [ ] **Step 5: 接线 action handler 到 executor**
|
||||
- [ ] **Step 6: reminders 套件回归**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders`
|
||||
Expected: PASS
|
||||
- [ ] **Step 7: Commit**
|
||||
```bash
|
||||
git add apps/lib/main.dart apps/lib/core/notifications/reminder_notification_callbacks.dart apps/lib/core/notifications/local_notification_service.dart apps/test/features/calendar/reminders/reminder_notification_callbacks_test.dart
|
||||
git commit -m "feat: wire reminder callbacks for foreground and background"
|
||||
```
|
||||
|
||||
### Task 8: Android 平台配置可执行校验（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/platform/android_manifest_notification_action_test.dart`
|
||||
- Modify: `apps/android/app/src/main/AndroidManifest.xml`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（缺 ActionBroadcastReceiver）**
|
||||
```dart
|
||||
test('android manifest contains ActionBroadcastReceiver', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/platform/android_manifest_notification_action_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 增加 receiver 配置**
|
||||
- [ ] **Step 4: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/platform/android_manifest_notification_action_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add apps/android/app/src/main/AndroidManifest.xml apps/test/platform/android_manifest_notification_action_test.dart
|
||||
git commit -m "fix: register android action receiver for reminder notifications"
|
||||
```
|
||||
|
||||
### Task 9: iOS 平台配置可执行校验（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/platform/ios_app_delegate_notification_callback_test.dart`
|
||||
- Modify: `apps/ios/Runner/AppDelegate.swift`
|
||||
- Modify: `apps/lib/core/notifications/local_notification_service.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（registrant callback）**
|
||||
```dart
|
||||
test('ios app delegate registers flutter local notifications callback', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/platform/ios_app_delegate_notification_callback_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 实现 callback 注册 + category version bump (`calendar_reminder_v2`)**
|
||||
- [ ] **Step 4: 跑通过测试与 reminders 回归**
|
||||
Run (workdir=`apps`): `flutter test test/platform/ios_app_delegate_notification_callback_test.dart`
|
||||
Expected: PASS
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders`
|
||||
Expected: PASS
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add apps/ios/Runner/AppDelegate.swift apps/lib/core/notifications/local_notification_service.dart apps/test/platform/ios_app_delegate_notification_callback_test.dart
|
||||
git commit -m "fix: enable ios reminder action handling in background"
|
||||
```
|
||||
|
||||
### Task 10: Android 13+ 权限降级与埋点（TDD）
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/test/features/calendar/reminders/reminder_permission_fallback_test.dart`
|
||||
- Modify: `apps/lib/core/notifications/local_notification_service.dart`
|
||||
|
||||
- [ ] **Step 1: 写失败测试（未授权降级到应用内）**
|
||||
```dart
|
||||
test('fallbacks to in-app path when notifications permission denied', () async {});
|
||||
```
|
||||
- [ ] **Step 2: 跑失败测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_permission_fallback_test.dart`
|
||||
Expected: FAIL
|
||||
- [ ] **Step 3: 最小实现权限检查 + 降级埋点**
|
||||
- [ ] **Step 3: 最小实现权限检查 + 降级埋点**
|
||||
```text
|
||||
埋点字段至少包含：actionExecutionId、permissionState、appLifecycleState、platform
|
||||
```
|
||||
- [ ] **Step 4: 跑通过测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders/reminder_permission_fallback_test.dart`
|
||||
Expected: PASS
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add apps/lib/core/notifications/local_notification_service.dart apps/test/features/calendar/reminders/reminder_permission_fallback_test.dart
|
||||
git commit -m "feat: add reminder permission fallback path and telemetry"
|
||||
```
|
||||
|
||||
### Task 11: 旧代码清单与即时清理
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/todo/calendar-reminder-migration-checklist.md`
|
||||
- Modify/Delete: `apps/lib/**`, `apps/test/**`（以清单为准）
|
||||
|
||||
- [ ] **Step 1: 建立迁移清单（文件/符号/决策/责任人）**
|
||||
- [ ] **Step 2: 清理前扫描**
|
||||
Run: `rg "calendar_reminder_actions_v1|ReminderAction.cancel|_oldReminderEntry|_legacyReminderRoute" apps/lib apps/test`
|
||||
Expected: 输出待清理命中（仅代码引用，不含注释/文档示例）
|
||||
- [ ] **Step 3: 删除无用旧代码、无效测试、旧 fixture**
|
||||
- [ ] **Step 4: 清理后扫描**
|
||||
Run: `rg "calendar_reminder_actions_v1|ReminderAction.cancel|_oldReminderEntry|_legacyReminderRoute" apps/lib apps/test`
|
||||
Expected: no matches（注释/文档示例允许存在需在清单标注）
|
||||
- [ ] **Step 5: Commit**
|
||||
```bash
|
||||
git add docs/todo/calendar-reminder-migration-checklist.md apps/lib apps/test
|
||||
git commit -m "refactor: remove obsolete reminder paths after migration"
|
||||
```
|
||||
|
||||
### Task 12: 最终验证与交付
|
||||
|
||||
**Files:**
|
||||
- Verify only
|
||||
|
||||
- [ ] **Step 1: reminders 全量测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar/reminders`
|
||||
Expected: PASS
|
||||
- [ ] **Step 2: calendar 相关测试**
|
||||
Run (workdir=`apps`): `flutter test test/features/calendar`
|
||||
Expected: PASS
|
||||
- [ ] **Step 3: 手工矩阵 6/6 验证**
|
||||
```text
|
||||
Android: 前台/后台/杀进程
|
||||
iOS: 前台/后台锁屏/升级后
|
||||
```
|
||||
- [ ] **Step 4: 输出证据与指标**
|
||||
```text
|
||||
命令结果、回放日志、重试日志、重复执行率=0（按 actionExecutionId 统计）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Notes
|
||||
|
||||
- 任务顺序不可打乱：协议 -> 动作语义 -> 幂等 -> 回放 -> 桥接 -> UI -> 平台 -> 清理。
|
||||
- 每个任务只做最小改动并回归对应测试。
|
||||
- 视觉组件严格使用 `apps/lib/core/theme/design_tokens.dart`。
|
||||
- 若实现中与 spec 冲突，先改 spec/协议再继续写代码。
|
||||
@@ -1,524 +0,0 @@
|
||||
# 待办事项四象限拖拽实现计划
|
||||
|
||||
> **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
|
||||
- [ ] 编译无错误，测试通过
|
||||
@@ -1,215 +0,0 @@
|
||||
# 日历提醒统一交互设计（iOS/Android）
|
||||
|
||||
## 1. 背景与问题
|
||||
|
||||
当前日历提醒模块存在以下问题：
|
||||
|
||||
1. iOS 通知动作（"稍后提醒"/"取消"）在横幅场景下可见性不稳定，用户误判为无按钮。
|
||||
2. Android 与 iOS 的通知动作回调链路不一致，导致按钮点击在部分状态下无效。
|
||||
3. 前台提醒体验依赖系统默认样式，Android 观感较弱，不符合产品视觉语言。
|
||||
4. 提醒动作与弹窗交互代码存在历史分叉，维护成本高，且存在潜在无用旧代码残留。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
- 支持 App 关闭状态下的到点提醒（系统通知主触达）。
|
||||
- 统一提醒动作语义：
|
||||
- `稍后提醒` = 延后 10 分钟。
|
||||
- `取消` = 归档日历事件。
|
||||
- 前台状态提供一套跨平台复用的应用内提醒面板，提升视觉质量。
|
||||
- 无论动作来自系统通知还是应用内面板，都进入同一业务执行链路。
|
||||
- 在新链路稳定后，清除无用旧代码与重复入口。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 不改变提醒策略（仍按当前 reminderMinutes + 重复提醒策略）。
|
||||
- 不改动日历事件核心数据结构与后端协议。
|
||||
- 不在本次引入新的提醒类型（例如自定义延后时长、多级动作）。
|
||||
|
||||
## 3. 总体方案
|
||||
|
||||
采用“系统通知主触达 + 前台应用内面板增强”的混合方案：
|
||||
|
||||
1. **系统通知层（平台差异化）**
|
||||
- Android/iOS 继续使用 `flutter_local_notifications`。
|
||||
- 平台分别补齐通知动作接收能力，确保前台/后台/终止态都可触发动作。
|
||||
|
||||
2. **动作执行层（跨平台统一）**
|
||||
- 以 `ReminderActionExecutor` 作为唯一动作入口。
|
||||
- 内部动作 ID 固定为：`ReminderAction.snooze10m` 与 `ReminderAction.archive`。
|
||||
- UI 文案中的“取消”仅为展示文案，内部统一映射到 `archive`。
|
||||
|
||||
3. **前台呈现层（跨平台复用）**
|
||||
- 新增应用内 `ReminderActionSheet`（共享组件，遵循设计 token）。
|
||||
- 仅在应用前台触发，用于替代系统默认弹窗体验。
|
||||
|
||||
4. **展示策略（避免双提醒）**
|
||||
- 前台（App active）：默认只展示 `ReminderActionSheet`，不展示系统通知横幅。
|
||||
- 后台/终止态：只展示系统通知。
|
||||
|
||||
## 4. 关键设计决策
|
||||
|
||||
### 4.1 是否需要 iOS/Android 各写一套弹窗组件
|
||||
|
||||
不需要。应用内提醒组件采用一套 Flutter 共享实现。
|
||||
|
||||
需要分平台处理的是系统通知配置与回调桥接，不是应用内 UI 组件本身。
|
||||
|
||||
### 4.2 到点提醒是否继续使用“弹窗”
|
||||
|
||||
主流做法是系统通知，不是纯应用内弹窗。原因：
|
||||
|
||||
- App 关闭态仅系统通知可达。
|
||||
- 锁屏、通知中心具备天然可达性与系统一致性。
|
||||
- 可直接承载动作按钮（稍后提醒、取消并归档）。
|
||||
|
||||
前台场景再补应用内面板，兼顾体验与一致行为。
|
||||
|
||||
### 4.3 iOS 动作按钮显示问题
|
||||
|
||||
iOS 横幅通常不保证直接展示全部动作按钮，需展开通知查看动作。该行为属于系统 UI 规则。
|
||||
|
||||
此外 iOS 通知 category 存在缓存特性，category 变更后可能需要重装或升级 category id 才能稳定生效。
|
||||
|
||||
## 5. 模块与职责划分
|
||||
|
||||
### 5.1 保留并增强
|
||||
|
||||
- `apps/lib/core/notifications/local_notification_service.dart`
|
||||
- 仅负责通知调度与平台动作回调桥接。
|
||||
- 不负责前台 UI 展示。
|
||||
- 补齐后台动作回调接入。
|
||||
|
||||
- `apps/lib/features/calendar/reminders/reminder_action_executor.dart`
|
||||
- 作为唯一动作执行器。
|
||||
- 保持归档 outbox 重试机制。
|
||||
|
||||
### 5.2 新增
|
||||
|
||||
- `apps/lib/features/calendar/reminders/ui/reminder_presentation_coordinator.dart`
|
||||
- 感知 app 前后台状态。
|
||||
- 前台触发应用内提醒面板。
|
||||
- 作为前台展示唯一入口，禁止其他模块直接弹出提醒面板。
|
||||
|
||||
- `ReminderActionSheet`（共享组件）
|
||||
- 展示事件摘要 + 两个动作按钮。
|
||||
- 保证与系统通知动作语义一致。
|
||||
|
||||
### 5.3 平台接入补齐
|
||||
|
||||
- Android:
|
||||
- 在 `apps/android/app/src/main/AndroidManifest.xml` 增加 `ActionBroadcastReceiver`。
|
||||
- 配置并接入 `onDidReceiveBackgroundNotificationResponse`。
|
||||
- Android 13+ 先做 `POST_NOTIFICATIONS` 授权检查；未授权时降级应用内提示并记录埋点。
|
||||
- 后台回调函数必须为 top-level 且加 `@pragma('vm:entry-point')`。
|
||||
|
||||
- iOS:
|
||||
- 在 `apps/ios/Runner/AppDelegate.swift` 配置 plugin registrant callback（用于后台 action isolate）。
|
||||
- 后台回调函数必须为 top-level 且加 `@pragma('vm:entry-point')`。
|
||||
- `UNNotificationCategory` 在应用启动早期完成注册（早于提醒调度）。
|
||||
- 为 category id 增加版本化策略（`calendar_reminder_v{n}`），避免缓存导致动作更新不生效。
|
||||
|
||||
## 6. 动作流转（统一）
|
||||
|
||||
### 6.1 稍后提醒
|
||||
|
||||
触发源（系统通知按钮或应用内面板按钮）
|
||||
-> 统一映射为 `ReminderAction.snooze10m`
|
||||
-> `ReminderActionExecutor._snoozeEvent`
|
||||
-> 重新计算下一次时间并 `scheduleReminderAt`
|
||||
|
||||
### 6.2 取消（归档）
|
||||
|
||||
触发源（系统通知按钮或应用内面板按钮）
|
||||
-> 统一映射为 `ReminderAction.archive`
|
||||
-> 取消本地提醒
|
||||
-> 写 outbox 并调用归档接口
|
||||
-> 成功标记 done，失败进入 retry/backoff
|
||||
|
||||
### 6.3 动作回传契约（前台/后台/终止态统一）
|
||||
|
||||
- 每次动作生成幂等键：`actionExecutionId = notificationId + actionId + fireTimeBucket`。
|
||||
- 执行前先查重（本地持久化幂等表）；命中时直接 ACK，不重复执行业务副作用。
|
||||
- 终止态动作进入 cold-start queue 回放，按接收时间顺序处理。
|
||||
- 单条动作失败不阻塞后续动作；失败进入 retry/backoff 并可观测。
|
||||
|
||||
## 7. 旧代码收集与清理计划
|
||||
|
||||
### 7.1 旧代码清单建立
|
||||
|
||||
改造前先建立“提醒模块迁移清单”，按三类标记：
|
||||
|
||||
- `保留`：仍由新架构使用。
|
||||
- `替换`：保留接口，重写实现。
|
||||
- `删除`：无引用、重复职责、历史临时逻辑。
|
||||
|
||||
迁移清单字段必须包含：`文件路径`、`符号名`、`处理决策（保留/替换/删除）`、`责任人`。
|
||||
|
||||
### 7.2 清理时机
|
||||
|
||||
- 新链路在 Android+iOS 均验证通过后，立即执行删除。
|
||||
- 不做“先保留一版再说”的长期并存。
|
||||
|
||||
### 7.3 清理范围
|
||||
|
||||
- 无效弹窗触发入口。
|
||||
- 不再使用的提醒动作映射分支。
|
||||
- 重复回调注册与过时常量（旧 action id / 旧 category id）。
|
||||
- 不再有保护价值的旧测试与旧 fixture。
|
||||
|
||||
### 7.4 清理验收
|
||||
|
||||
- 以“旧标识 0 引用”为验收标准，至少覆盖：旧 action id、旧 category id、旧入口函数名。
|
||||
- 输出固定 grep 关键字清单并逐条验收。
|
||||
- 提醒链路测试通过。
|
||||
- 删除项对应测试通过，且无悬挂 fixture/snapshot 引用。
|
||||
- 手工回归覆盖前台/后台/终止态三种状态。
|
||||
|
||||
## 8. 测试与验证
|
||||
|
||||
### 8.1 自动化
|
||||
|
||||
- 新增/更新 reminders 相关单测：
|
||||
- 动作映射正确性（notification/app sheet -> executor）。
|
||||
- `archive` 的 outbox 行为与重试退避逻辑。
|
||||
- `snooze10m` 在边界时间的调度行为。
|
||||
- 同一 `actionExecutionId` 重复投递仅执行一次（幂等）。
|
||||
- 终止态 cold-start queue 回放不丢失且顺序一致。
|
||||
- 前台面板与系统通知并发触发时仅产生一次业务副作用。
|
||||
|
||||
### 8.2 手工验证矩阵
|
||||
|
||||
- Android:
|
||||
- 前台：面板按钮可用。
|
||||
- 后台：通知动作可用。
|
||||
- 杀进程：通知动作可用。
|
||||
|
||||
- iOS:
|
||||
- 前台：面板按钮可用。
|
||||
- 后台/锁屏：通知展开后动作可用。
|
||||
- 安装升级后 category 动作可用。
|
||||
|
||||
## 9. 风险与缓解
|
||||
|
||||
- **风险**：iOS category 缓存导致动作更新不生效。
|
||||
- **缓解**：category id 版本化 + 明确重装验证步骤。
|
||||
|
||||
- **风险**：后台动作 isolate 未正确注册导致点击丢失。
|
||||
- **缓解**：AppDelegate/Manifest 严格按插件要求配置，并做终止态回归。
|
||||
|
||||
- **风险**：前台面板与系统通知并发触发造成重复操作。
|
||||
- **缓解**：PresentationCoordinator 增加去重窗口与事件级幂等保护。
|
||||
|
||||
- **风险**：通知权限未授权导致后台提醒不可达。
|
||||
- **缓解**：启动期权限检查 + 降级提示 + 埋点追踪。
|
||||
|
||||
## 10. 完成定义（DoD）
|
||||
|
||||
- App 关闭状态下，系统通知可触达并可执行两个动作。
|
||||
- `取消` 在业务上严格等价于归档。
|
||||
- 前台统一提醒面板上线，Android 样式符合项目视觉语言。
|
||||
- 动作执行链路唯一，平台仅保留桥接差异。
|
||||
- 历史无用代码完成清理，且通过验证。
|
||||
- 手工矩阵 6/6 场景通过（Android 前台/后台/杀进程 + iOS 前台/后台锁屏/升级后）。
|
||||
- 动作日志可追踪，重复执行率=0（基于 `actionExecutionId` 统计）。
|
||||
@@ -1,113 +0,0 @@
|
||||
# 待办事项四象限拖拽交互设计
|
||||
|
||||
## 概述
|
||||
|
||||
四象限待办页面支持待办项在象限内排序以及跨象限拖拽移动，同时保持与后端的数据同步。
|
||||
|
||||
## 交互设计
|
||||
|
||||
### 拖拽状态
|
||||
|
||||
| 状态 | 视觉反馈 |
|
||||
|------|----------|
|
||||
| 按住（未拖拽） | 卡片 scale 1.0，轻微阴影 |
|
||||
| 拖拽开始 | 卡片 scale 1.03 + 阴影加深，原位置保留半透明占位框 |
|
||||
| 拖拽中 | 卡片跟随手指（transform），目标象限边框高亮发光 |
|
||||
| 释放-象限内排序 | 卡片平滑移动到新位置（200ms ease-out） |
|
||||
| 释放-跨象限移动 | 卡片以 spring 动画弹入目标位置 |
|
||||
| 操作完成 | 显示成功 Toast |
|
||||
|
||||
### 动画参数
|
||||
|
||||
- **micro-interaction**: 150-300ms
|
||||
- **easing**: ease-out 进入，ease-in 退出
|
||||
- **spring**: 用于跨象限移动，natural feel
|
||||
- **scale feedback**: 0.95-1.05 on press
|
||||
- **exit faster than enter**: 退出时长是进入的 60-70%
|
||||
|
||||
### 防误触
|
||||
|
||||
- 拖拽启动延迟：100-150ms 确认是长按而非点击
|
||||
- 仅在按住并移动超过阈值后启动拖拽
|
||||
|
||||
## 数据流
|
||||
|
||||
### 状态管理
|
||||
|
||||
```
|
||||
_QuadrantScreenState
|
||||
├── List<TodoResponse> _todos
|
||||
├── DragState _dragState (null / dragging)
|
||||
└── int? _dragTargetQuadrant (1, 2, 3)
|
||||
```
|
||||
|
||||
### API 交互
|
||||
|
||||
1. **象限内排序**：调用 `PUT /todos/{id}` 更新 `priority` 和 `sort_order`
|
||||
2. **跨象限移动**：调用 `PUT /todos/{id}` 更新 `priority`
|
||||
|
||||
### 乐观更新
|
||||
|
||||
- 用户释放后立即更新本地 UI
|
||||
- 后端请求失败时回滚 + 显示错误 Toast
|
||||
|
||||
## 组件结构
|
||||
|
||||
```
|
||||
TodoQuadrantsScreen
|
||||
├── _QuadrantDragContainer (LongPressDraggable + DragTarget)
|
||||
│ ├── _QuadrantCard (象限容器)
|
||||
│ └── _TodoDragItem (可拖拽待办项)
|
||||
└── _DragFeedbackWidget (拖拽中的视觉反馈)
|
||||
```
|
||||
|
||||
## 状态定义
|
||||
|
||||
| 状态 | 描述 |
|
||||
|------|------|
|
||||
| `idle` | 正常显示 |
|
||||
| `dragging` | 正在拖拽某项 |
|
||||
| `dragOverQuadrant` | 拖拽到某象限上方 |
|
||||
| `reordering` | 正在执行排序动画 |
|
||||
|
||||
## 优先级定义
|
||||
|
||||
| 象限 | Priority Value |
|
||||
|------|---------------|
|
||||
| 重要紧急 | 1 |
|
||||
| 紧急不重要 | 3 |
|
||||
| 重要不紧急 | 2 |
|
||||
|
||||
## 视觉规范
|
||||
|
||||
### 卡片样式
|
||||
|
||||
- **正常**: `color: AppColors.todoCardBg`, `borderRadius: 14px`
|
||||
- **拖拽中**: `opacity: 0.5` 在原位置显示占位
|
||||
- **跟随手指**: `scale: 1.03`, `shadow: elevated`
|
||||
|
||||
### 象限边框高亮
|
||||
|
||||
- **正常**: `border: 1px solid {quadrantBorderColor}`
|
||||
- **dragOver**: `border: 2px solid AppColors.blue400`, `boxShadow: 0 0 12px AppColors.blue200`
|
||||
|
||||
### 插入指示器
|
||||
|
||||
- 高度 2px，圆角 1px
|
||||
- 颜色：`AppColors.blue500`
|
||||
- 位置：两个待办项之间
|
||||
|
||||
## 错误处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|----------|
|
||||
| 后端请求失败 | 回滚本地状态，显示错误 Toast |
|
||||
| 网络断开 | 显示网络错误提示 |
|
||||
| 并发冲突 | 以最新数据为准，提示用户刷新 |
|
||||
|
||||
## 实现要点
|
||||
|
||||
1. 使用 Flutter `LongPressDraggable` + `DragTarget` 实现拖拽
|
||||
2. 使用 `AnimatedContainer` / `AnimatedPositioned` 实现平滑动画
|
||||
3. 乐观更新：先更新 UI，后请求后端
|
||||
4. 拖拽反馈使用 `Transform` 而非改变位置，避免 CLS
|
||||
Reference in New Issue
Block a user