social-app/docs/plans/2026-03-11-calendar-dayview-improvement-impl.md

# 日视图改进实现计划

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 对日历日视图进行三项改进：固定顶部头部、添加「今天」按钮、双指缩放时间轴高度

**Architecture:** 使用 Stack + Positioned 布局固定头部，使用 GestureDetector 监听缩放手势动态调整时间轴高度

**Tech Stack:** Flutter, Dart

---

### Task 1: 修改 _hourHeight 为变量并添加缩放状态

**Files:**
- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart:27-38`

**Step 1: 添加状态变量**

在 `_CalendarDayWeekScreenState` 类中：
- 将 `static const double _hourHeight = 34;` 改为 `double _hourHeight = 34.0;`
- 添加缩放相关变量：
  ```dart
  double _baseHourHeight = 34.0;
  double _currentScale = 1.0;
  ```

**Step 2: Commit**

```bash
git add apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart
git commit -m "refactor: 将 _hourHeight 改为变量支持缩放"
```

---

### Task 2: 实现双指缩放时间轴高度功能

**Files:**
- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart`

**Step 1: 添加缩放手势监听**

在 `build` 方法的外层 `Scaffold` 包装 `GestureDetector`：
```dart
return Scaffold(
  backgroundColor: AppColors.todoBg,
  body: GestureDetector(
    onScaleStart: (details) {
      _baseHourHeight = _hourHeight;
    },
    onScaleUpdate: (details) {
      setState(() {
        _currentScale = details.scale.clamp(0.5, 2.0);
        _hourHeight = (_baseHourHeight * _currentScale).clamp(17.0, 68.0);
      });
    },
    child: SafeArea(...),
  ),
);
```

**Step 2: 运行测试验证**

运行 Flutter 测试确保没有破坏现有功能。

**Step 3: Commit**

```bash
git add apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart
git commit -m "feat: 添加双指缩放时间轴高度功能"
```

---

### Task 3: 实现固定顶部头部布局

**Files:**
- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart:78-113`

**Step 1: 重构 build 方法为 Stack 布局**

将 `Column` 改为 `Stack`，头部使用 `Positioned` 固定：
```dart
return Scaffold(
  backgroundColor: AppColors.todoBg,
  body: Stack(
    children: [
      // 可滚动内容
      Positioned.fill(
        top: 68, // 头部高度
        child: SingleChildScrollView(
          child: Padding(
            padding: const EdgeInsets.only(
              left: AppSpacing.lg,
              right: AppSpacing.lg,
              top: 2,
              bottom: 104,
            ),
            child: Column(
              children: [
                _buildWeekStrip(),
                const SizedBox(height: 8),
                KeyedSubtree(
                  key: _eventsKey,
                  child: _buildTimelineBoard(),
                ),
              ],
            ),
          ),
        ),
      ),
      // 固定头部
      Positioned(
        top: 0,
        left: 0,
        right: 0,
        child: _buildHeader(),
      ),
      // 底部 dock
      Positioned(
        bottom: 0,
        left: 0,
        right: 0,
        child: _buildBottomDock(),
      ),
    ],
  ),
);
```

**Step 2: 运行验证**

确保头部固定在顶部，内容可滚动。

**Step 3: Commit**

```bash
git add apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart
git commit -m "feat: 固定日视图头部在顶部"
```

---

### Task 4: 添加「今天」快捷按钮

**Files:**
- Modify: `apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart:115-183`

**Step 1: 修改 _buildHeader 添加「今天」按钮**

在 `_buildHeader` 方法中：
- 在 + 号按钮左侧添加「今天」按钮
- 使用 `isSameDay(_selectedDate, DateTime.now())` 判断是否显示
- 添加 `_goToToday()` 方法：
  ```dart
  void _goToToday() {
    final today = DateTime.now();
    setState(() {
      _selectedDate = today;
    });
    _calendarManager.setSelectedDate(today);
    _updateMonthDates();
    _scrollToSelectedDate(animate: true);
    _loadEvents();
  }
  ```

**Step 2: 修改 + 号按钮位置**

将 + 号按钮移到最右侧，今天按钮在 + 号左侧。

**Step 3: 运行验证**

- 查看非今天日期时是否显示「今天」按钮
- 点击后是否正确跳转到今天

**Step 4: Commit**

```bash
git add apps/lib/features/calendar/ui/screens/calendar_dayweek_screen.dart
git commit -m "feat: 添加今天快捷按钮"
```

---

### Task 5: 运行完整测试验证

**Step 1: 运行 Flutter 测试**

```bash
cd apps && flutter test
```

**Step 2: 手动验证**
- 日视图固定头部
- 「今天」按钮显示和跳转
- 双指缩放高度

**Step 3: Commit**

```bash
git add .
git commit -m "test: 验证日视图改进功能"
```

---

### Task 6: 更新文档并合并

**Step 1: 更新 runtime-route.md**

同步更新 `docs/runtime/runtime-route.md` 中的日历相关描述。

**Step 2: 提交并推送到远程**

```bash
git push origin dev
```

---

**Plan complete.**