social-app/docs/plans/2026-03-11-calendar-metadata-and-api-implementation.md

Calendar Metadata And API Implementation Plan

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

Goal: 统一后端 schedule-items 与 Agent 日历卡片的 metadata v1 约束，并让前端日历模块完成真实 API 接入与 metadata 全字段渲染。

Architecture: 后端以 v1.schedule_items.schemas 作为 metadata 单一真源，路由响应与 Agent 工具 payload 统一复用该结构。前端新增 Calendar API 数据层，使用 DTO 与领域模型映射驱动 UI；日历创建弹窗与详情页升级为可编辑/展示完整 metadata（location、notes、attachments、version）。

Tech Stack: FastAPI, Pydantic v2, SQLAlchemy, Flutter, Dio, GetIt, widget/unit tests

---

Task 1: 后端 metadata v1 校验（TDD）

Files:

• Modify: backend/tests/unit/v1/schedule_items/test_schemas.py
• Modify: backend/src/v1/schedule_items/schemas.py

Steps:

1. 增加失败测试：metadata.color 非 #RRGGBB 拒绝、metadata.version 非 1 拒绝、metadata/attachment 非法额外字段拒绝。
2. 运行 uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q，确认 RED。
3. 在 schema 中补齐约束：extra="forbid"、Field(pattern=...)、Literal[1]。
4. 再跑同一测试文件确认 GREEN。

Task 2: 后端响应完整 metadata（TDD）

Files:

• Modify: backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py
• Modify: backend/tests/unit/core/agent/test_list_calendar_events_tool.py
• Modify: backend/src/core/agent/infrastructure/crewai/tools/create_calendar_event_tool.py

Steps:

1. 增加失败测试：calendar_card.v1 与 calendar_event_list.v1 的 data 含完整 metadata，并兼容已有扁平字段。
2. 运行 uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py backend/tests/unit/core/agent/test_list_calendar_events_tool.py -q，确认 RED。
3. 调整 _event_payload 输出，补齐 metadata（color/location/notes/attachments/version）。
4. 再跑测试确认 GREEN。

Task 3: 前端日历真实 API 数据层（TDD）

Files:

• Add: apps/lib/features/calendar/data/calendar_api.dart
• Modify: apps/lib/features/calendar/data/models/schedule_item_model.dart
• Modify: apps/lib/features/calendar/data/services/mock_calendar_service.dart
• Modify: apps/lib/core/di/injection.dart
• Add: apps/test/features/calendar/data/calendar_api_test.dart

Steps:

1. 新增失败测试覆盖 GET/POST/PATCH/DELETE 与 metadata 映射（含 attachments/version）。
2. 运行 cd apps && flutter test test/features/calendar/data/calendar_api_test.dart，确认 RED。
3. 实现 API 与模型序列化/反序列化，CalendarService 在真实环境走 API，在 mock 环境走现有内存服务。
4. 再跑测试确认 GREEN。

Task 4: 前端完整 metadata 渲染与创建/查看增强（TDD）

Files:

• Modify: apps/lib/features/calendar/ui/widgets/create_event_sheet.dart
• Modify: apps/lib/features/calendar/ui/screens/calendar_event_detail_screen.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/chat/data/models/tool_result.dart
• Modify: apps/lib/features/chat/ui/widgets/ui_schema_renderer.dart
• Add: apps/test/features/calendar/ui/calendar_event_detail_screen_test.dart

Steps:

1. 增加失败测试：详情页显示 attachments/version；创建弹窗支持 attachments 输入并提交。
2. 运行对应 flutter test，确认 RED。
3. 改造 UI 与数据写回逻辑，保证 metadata 全字段渲染。
4. 再跑测试确认 GREEN。

Task 5: 文档与验证

Files:

• Modify: docs/runtime/runtime-route.md

Steps:

1. 更新 metadata v1 校验规则与返回示例。
2. 运行后端+前端相关测试集合，记录结果。
3. 执行 L2 门禁：refactor-cleaner、code-reviewer、security-reviewer 并修复问题。