Weekly Schedule 模块重建说明

本文档用于让其他大模型在不了解现有实现细节的情况下，重新开发 weekly-schedule 模块。

1. 模块目标

构建一个“按周管理任务安排”的页面，支持：

• 管理多个周计划（新增、切换、重命名、复制、删除）
• 在“任务清单”和“时间网格（周一到周日 × 上午/下午/晚上）”之间拖拽分配任务
• 在时间格子内移动任务、删除任务、标记完成
• 在任务清单中新建/编辑/删除/分类查看/重置任务
• 本地持久化（刷新后恢复）
• 提供“如何做安排”的说明页

页面路由：

• 主页面：/weekly-schedule
• 指南页面：/weekly-schedule/guide

2. 核心数据模型

2.1 枚举

• DayOfWeek: monday ... sunday
• TimePeriod: morning | afternoon | evening
• TaskCategory: PLANNING | THINKING | WORK | MUSIC | EXERCISE | READING | COOKING | GAMING | DEVELOPING | LEARNING

2.2 Task

interface Task {
  id: string;
  name: string;
  category: TaskCategory;
  duration: number; // 分钟
  description?: string;
  completed?: boolean;
  isDragged?: boolean; // 是否已被安排到时间格子（在任务面板用于禁拖和状态提示）
  priority?: 'high' | 'medium' | 'low';
  score?: number;
}

2.3 TimeSlot / Schedule / Week

interface TimeSlot {
  day: DayOfWeek;
  period: TimePeriod;
  taskIds: string[]; // 仅保存任务 ID，任务实体在 Week.tasks
}

interface Schedule {
  id: string;
  weekStart: string; // ISO
  timeSlots: TimeSlot[];
  createdAt: string;
  updatedAt: string;
}

interface Week {
  id: string;
  name: string;
  schedule: Schedule;
  tasks: Task[];
  createdAt: string;
  updatedAt: string;
}

3. 状态与持久化协议

3.1 主状态容器

推荐一个 useWeeks hook（现有实现也是该方案）：

• weeks: Week[]
• currentWeekId: string | null
• currentWeek: Week | null
• isLoading: boolean
• 操作：addWeek / duplicateWeek / deleteWeek / updateWeek / updateWeekName / switchWeek

3.2 LocalStorage Key（必须兼容）

• weekly-schedule-weeks: 所有 week 数据
• weekly-schedule-current-week-id: 当前选中的 week id

3.3 初始化规则

1. 首次进入时读取 weekly-schedule-weeks
2. 若为空，创建默认 week（例如“第1周”）
3. 读取 weekly-schedule-current-week-id，若失效则回退到第一周
4. 初始化完成后再开启自动持久化

4. 页面结构与组件职责

4.1 页面入口

• page.tsx 只渲染 WeeklySchedule 容器组件

4.2 WeeklySchedule（核心编排层）

职责：

• 组合顶部周选择器、左侧时间网格、右侧任务面板、任务编辑弹窗
• 承载核心业务回调（拖拽、删除、编辑、清空、重置）
• 跳转指南页 /weekly-schedule/guide

4.3 WeekSelector

功能：

• 下拉选择当前周
• 添加新周（弹窗输入名称）
• 重命名周
• 复制周（默认名称“xxx(副本)”）
• 删除周（至少保留一个）

4.4 TimeGrid

布局：

• 7 列（周一到周日）× 3 行（上午/下午/晚上）
• 每个格子为 TimeSlot 组件
• 顶部提供“清空日程”按钮（仅清空格子中的任务关联）

4.5 TimeSlot

职责：

• 接收一个 timeSlot 与全量 tasks，通过 taskIds 映射出任务对象
• 支持放置任务（从任务面板 or 从其他时间格）
• 展示任务列表、完成状态、总时长
• 格子内任务过多时支持紧凑模式/折叠显示
• 支持“添加任务到当前格子”

4.6 TaskPanel

职责：

• 显示任务清单和统计（全部/待完成/已完成/按分类 tab）
• 支持拖拽来源（仅未安排任务可从面板拖拽）
• 支持新建任务、删除任务、编辑任务、切换完成、重置默认任务

4.7 TaskEditModal

字段：

• name 必填
• category 必填
• duration 必填（1~480）
• priority 必填（high/medium/low）
• description 可选

行为：

• 编辑模式：保留原 id/completed/isDragged
• 新建模式：生成新 id，默认 completed=false

5. 关键业务流程（重建时必须保证）

5.1 从任务面板拖拽到时间格

1. 检查目标格是否已包含该 task.id
2. 若没有，将 task.id 追加到目标 taskIds
3. 将任务池中该任务 isDragged 置为 true

5.2 时间格之间移动任务

1. 拖拽 payload 需带源位置 sourceDay/sourcePeriod
2. 从源格 taskIds 删除任务 id
3. 向目标格 taskIds 追加任务 id
4. 任务实体本身不变（通常 isDragged 保持 true）

5.3 从时间格删除任务

1. 从该格删除任务 id
2. 将任务池中该任务 isDragged=false

5.4 清空日程

1. 重建全部空 timeSlots
2. 将当前周 tasks 全部 isDragged=false
3. 不删除任务实体，不改任务总数

5.5 在时间格里“新建任务”

1. 通过弹窗创建任务
2. 新任务加入任务池（通常 isDragged=false）
3. 同时把该新任务 id 放入当前格 taskIds

5.6 重置任务清单

1. 优先从 /default-tasks.json 加载
2. 每个任务重新生成 id
3. 若失败回退硬编码默认任务

6. 默认数据要求

建议提供一批默认任务模板，涵盖主要分类，字段至少包括：

• name/category/duration/description/priority

当前实现是按分类生成多份副本（例如工作类较多），重建时可保留此策略或改为配置化。

7. 未启用但可预留能力

当前代码中有注释掉的能力，可作为后续版本：

• 导入/导出日程 JSON
• 导入/导出任务清单 JSON
• 评分仪表盘（周得分、分类得分、维度评价）

重建时可先不实现 UI，但建议预留数据结构扩展点。

8. UI 与交互约束

• 技术栈：React + Next.js + Ant Design + Tailwind（现状）
• 页面分栏：
  • 左 18 栅格：时间网格
  • 右 6 栅格：任务面板
• 任务状态视觉：
  • 已完成：弱化 + 删除线
  • 已安排：在任务面板显示“已安排”并禁拖
• 对关键操作给出即时反馈（message 成功/失败）

9. 重建验收清单（给大模型执行）

• 能创建、切换、重命名、复制、删除周计划
• 周计划删除时保证至少保留一个
• 任务可从任务面板拖入任意时间格
• 任务可在时间格之间移动
• 同一格不允许重复插入同一任务
• 删除格内任务后，任务面板恢复可拖拽
• 任务可新增、编辑、删除、勾选完成
• 清空日程不删除任务清单
• 刷新页面后，weeks 与当前 week 选择都能恢复
• 指南页可从主页面进入并返回

10. 推荐实现顺序

1. 定义 types 和 localStorage 协议
2. 实现 useWeeks（包含初始化和持久化）
3. 完成 WeeklySchedule 容器和分栏布局
4. 实现 WeekSelector
5. 实现 TaskPanel + TaskEditModal
6. 实现 TimeGrid + TimeSlot 拖拽逻辑
7. 完成“清空日程/重置任务/消息反馈/指南页跳转”
8. 最后补充导入导出与评分等增强功能