qzl
79 lines
4.0 KiB
Markdown
79 lines
4.0 KiB
Markdown
# 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` 并修复问题。
|