# 日历提醒字段与详情页对齐设计

**Date:** 2026-03-11
**Status:** 已确认

## 目标

- 修复日历事件详情页字段映射错误，去掉 raw metadata 直出
- 新增可持久化的提醒字段（方案1）：`metadata.reminder_minutes`
- 打通前后端和 AgentScope 工具调用链
- 用前端本地通知实现系统提醒与震动

## 数据契约

### metadata 结构

```json
{
  "color": "#4F46E5",
  "location": "会议室A",
  "notes": "带电脑",
  "attachments": [],
  "reminder_minutes": 15,
  "version": 1
}
```

### 字段规则

- `reminder_minutes`: `int | null`
- 取值范围：`0..10080`（0 表示准时提醒，10080 表示最多提前 7 天）
- 兼容历史数据：缺失或 null 视为无提醒

## 前端设计

1. 模型层（`ScheduleMetadata`）新增 `reminderMinutes`
2. 详情页：提醒时间改为结构化渲染
   - null: `无`
   - 0: `准时提醒`
   - n: `开始前 n 分钟`
3. 创建/编辑弹层新增提醒选项，默认值为 `15`
4. 删除 metadata raw 原样渲染区块

## 本地通知设计

- 采用 Flutter 本地通知，调度时间：`startAt - reminderMinutes`
- 创建/编辑成功：重建该事件通知
- 删除成功：取消该事件通知
- App 启动后：扫描未来事件并重建通知（补偿机制）

## 后端与 AgentScope 设计

1. `ScheduleItemMetadata` 增加 `reminder_minutes`
2. service 继续走 `metadata -> extra_metadata`，不加新 DB 列
3. AgentScope `calendar.write` 增加 `reminder_minutes` 参数
4. CrewAI calendar tool 将 `reminderMinutes` 映射为 `metadata.reminder_minutes`
5. calendar tool 回包增加 `reminderMinutes` 字段

## 验证策略

- 后端：schemas/service/agentscope 单元测试
- 前端：calendar_api 与详情页渲染测试
- 手动：创建提醒 -> 等待系统通知与震动 -> 更新/删除后确认调度变更