social-app/docs/plans/2026-03-11-calendar-reminder-metadata-design.md

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

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

目标

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

数据契约

metadata 结构

{
  "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 与详情页渲染测试
• 手动：创建提醒 -> 等待系统通知与震动 -> 更新/删除后确认调度变更