feat: 增强日历功能并集成 AgentScope 代理服务

2026-03-11 15:28:29 +08:00
parent e55e445906
commit e20e7d2a02
85 changed files with 5175 additions and 885 deletions
@@ -0,0 +1,78 @@
+# 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` 并修复问题。
@@ -281,10 +281,21 @@
  {
    "id": "uuid",
    "title": "string",
+    "description": "string?",
    "start_at": "string",
    "end_at": "string?",
    "timezone": "string",
-    "status": "active"
+    "metadata": {
+      "color": "#FF6B6B",
+      "location": "会议室A",
+      "notes": "记得带身份证",
+      "attachments": [],
+      "version": 1
+    },
+    "status": "active",
+    "source_type": "manual",
+    "created_at": "string",
+    "updated_at": "string"
  }
 ]
 ```
@@ -403,43 +414,6 @@

 ---

-### POST /inbox/messages/{id}/accept
-
-接受邀请（需要认证）。
-
-接受日历邀请时，会为当前用户创建订阅关系。
-
-**Request:**
-```json
-{
-  "permission_view": "boolean (default: true)",
-  "permission_edit": "boolean (default: false)",
-  "permission_invite": "boolean (default: false)"
-}
-```
-
-**Response:** 204 No Content
-
-**Errors:**
- 401: 未认证
- 404: 消息不存在
- 400: 消息不是待处理状态或不是日历类型邀请
-
---
-
-### POST /inbox/messages/{id}/dismiss
-
-忽略邀请（需要认证）。
-
-**Response:** 204 No Content
-
-**Errors:**
- 401: 未认证
- 404: 消息不存在
- 400: 消息不是待处理状态
-
---
-
 ## Users

 ### GET /users/me