feat: 添加日历批量操作与客户端时区感知功能，优化前端 UI 交互体验
This commit is contained in:
zl-q
@@ -0,0 +1,285 @@
|
||||
# Calendar Timezone Unification Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Eliminate calendar time mismatches by enforcing one end-to-end timezone policy across App input, Agent runtime context, tool execution, and UTC database storage.
|
||||
|
||||
**Architecture:** Keep database schema unchanged (`start_at/end_at TIMESTAMPTZ + timezone`) and enforce strict runtime normalization. Device timezone is injected from `RunAgentInput.forwardedProps`, resolved into a single `effective_timezone`, then written explicitly into tool arguments and persisted as event timezone while timestamps are stored in UTC. Calendar read responses include deterministic event-timezone-rendered values so frontend rendering is stable and no implicit `toLocal()` conversion remains.
|
||||
|
||||
**Tech Stack:** FastAPI, Pydantic v2, AgentScope runtime/tooling, Flutter (Dart), PostgreSQL TIMESTAMPTZ, pytest, Flutter test.
|
||||
|
||||
---
|
||||
|
||||
## Chunk 1: Protocol and Backend Runtime Normalization
|
||||
|
||||
### Task 1: Freeze protocol and timezone precedence contract
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/protocols/agent/run-agent-input.md`
|
||||
- Create: `docs/protocols/calendar/timezone-policy.md`
|
||||
|
||||
- [ ] **Step 1: Write protocol delta checklist in docs first**
|
||||
|
||||
Document the exact policy:
|
||||
- `event_timezone > device_timezone > profile.timezone > UTC`
|
||||
- `event_timezone` must be present in final tool call
|
||||
- `start_at/end_at` must be timezone-aware
|
||||
- DB stores UTC timestamps and IANA timezone string
|
||||
|
||||
- [ ] **Step 2: Update RunAgentInput protocol with forwardedProps contract**
|
||||
|
||||
Add canonical payload example:
|
||||
|
||||
```json
|
||||
{
|
||||
"forwardedProps": {
|
||||
"client_time": {
|
||||
"device_timezone": "America/Los_Angeles",
|
||||
"client_now_iso": "2026-03-16T09:12:33-07:00",
|
||||
"client_epoch_ms": 1773658353000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Add calendar timezone policy protocol doc**
|
||||
|
||||
Include:
|
||||
- accepted datetime formats
|
||||
- explicit error codes
|
||||
- write/read response semantics
|
||||
- DST handling rule
|
||||
|
||||
- [ ] **Step 4: Verify docs consistency**
|
||||
|
||||
Run: `cd backend && uv run python -m pytest tests/unit/core/agentscope/test_system_prompt.py -q`
|
||||
Expected: PASS (no protocol-breaking prompt assumptions)
|
||||
|
||||
|
||||
### Task 2: Parse forwarded device time and compute effective timezone
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/src/core/agentscope/schemas/agui_input.py`
|
||||
- Modify: `backend/src/core/agentscope/runtime/runner.py`
|
||||
- Modify: `backend/src/core/agentscope/prompts/system_prompt.py`
|
||||
- Test: `backend/tests/unit/core/agentscope/test_system_prompt.py`
|
||||
|
||||
- [ ] **Step 1: Write failing tests for effective timezone resolution**
|
||||
|
||||
Add tests covering:
|
||||
- forwarded `device_timezone` present -> selected
|
||||
- missing forwarded timezone -> fallback profile timezone
|
||||
- invalid forwarded timezone -> fallback profile timezone
|
||||
|
||||
- [ ] **Step 2: Run tests to confirm RED**
|
||||
|
||||
Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_system_prompt.py -k timezone -v`
|
||||
Expected: FAIL on new assertions
|
||||
|
||||
- [ ] **Step 3: Implement minimal runtime context extraction**
|
||||
|
||||
Implement a typed helper in runner path to read:
|
||||
- `run_input.forwarded_props.client_time.device_timezone`
|
||||
- `client_now_iso`
|
||||
- `client_epoch_ms`
|
||||
|
||||
Compute `effective_timezone` using fixed precedence and pass it into `build_system_prompt(...)`.
|
||||
|
||||
- [ ] **Step 4: Inject effective_timezone into ENV section**
|
||||
|
||||
Update `build_system_prompt` env payload to include:
|
||||
- `timezone_profile`
|
||||
- `timezone_device`
|
||||
- `timezone_effective`
|
||||
|
||||
Update guidance sentence to resolve ambiguous time with `timezone_effective`.
|
||||
|
||||
- [ ] **Step 5: Run tests to confirm GREEN**
|
||||
|
||||
Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_system_prompt.py -v`
|
||||
Expected: PASS
|
||||
|
||||
|
||||
### Task 3: Remove timezone ambiguity and hidden fallbacks from calendar write
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/src/core/agentscope/tools/utils/calendar_domain.py`
|
||||
- Modify: `backend/src/core/agentscope/tools/custom/calendar.py`
|
||||
- Modify: `backend/src/v1/schedule_items/schemas.py`
|
||||
- Modify: `backend/src/v1/schedule_items/service.py`
|
||||
- Test: `backend/tests/unit/core/agentscope/test_calendar_tools.py`
|
||||
- Test: `backend/tests/unit/v1/schedule_items/test_schemas.py`
|
||||
- Test: `backend/tests/unit/v1/schedule_items/test_service.py`
|
||||
|
||||
- [ ] **Step 1: Write failing tests for forbidden naive datetime and required timezone**
|
||||
|
||||
Add tests for:
|
||||
- naive `start_at` rejected
|
||||
- missing `event_timezone` rejected in tool path
|
||||
- parse failure does not fallback to `now + 1h`
|
||||
|
||||
- [ ] **Step 2: Run tests to confirm RED**
|
||||
|
||||
Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_calendar_tools.py tests/unit/v1/schedule_items/test_schemas.py -v`
|
||||
Expected: FAIL on new constraints
|
||||
|
||||
- [ ] **Step 3: Implement strict parsing and normalization**
|
||||
|
||||
Implementation requirements:
|
||||
- `parse_iso_datetime` rejects naive input
|
||||
- remove default `Asia/Shanghai` in tool
|
||||
- remove fallback auto-generated start time
|
||||
- validate IANA timezone and normalize `start_at/end_at` to UTC before persistence
|
||||
|
||||
- [ ] **Step 4: Enforce service-level invariants**
|
||||
|
||||
Service invariant set:
|
||||
- timezone non-empty and valid IANA
|
||||
- `end_at is None or end_at >= start_at`
|
||||
|
||||
- [ ] **Step 5: Run backend tests**
|
||||
|
||||
Run: `cd backend && uv run pytest tests/unit/core/agentscope/test_calendar_tools.py tests/unit/v1/schedule_items/test_schemas.py tests/unit/v1/schedule_items/test_service.py tests/integration/test_schedule_items_routes.py -v`
|
||||
Expected: PASS
|
||||
|
||||
|
||||
### Task 4: Keep DB schema, add non-breaking constraint migration only
|
||||
|
||||
**Files:**
|
||||
- Create: `backend/alembic/versions/20260316_000x_schedule_items_time_constraints.py`
|
||||
- Test: `backend/tests/integration/test_schedule_items_routes.py`
|
||||
|
||||
- [ ] **Step 1: Write migration test expectation first**
|
||||
|
||||
Add/extend integration assertion for invalid `end_at < start_at` returning 422.
|
||||
|
||||
- [ ] **Step 2: Run integration test to confirm RED**
|
||||
|
||||
Run: `cd backend && uv run pytest tests/integration/test_schedule_items_routes.py -k end_at -v`
|
||||
Expected: FAIL
|
||||
|
||||
- [ ] **Step 3: Implement migration with CHECK only (no new columns)**
|
||||
|
||||
Migration includes:
|
||||
- `CHECK (end_at IS NULL OR end_at >= start_at)`
|
||||
|
||||
- [ ] **Step 4: Run migration + integration test**
|
||||
|
||||
Run: `cd backend && uv run alembic upgrade head && uv run pytest tests/integration/test_schedule_items_routes.py -v`
|
||||
Expected: PASS
|
||||
|
||||
---
|
||||
|
||||
## Chunk 2: Frontend Deterministic Display and Agent Input Wiring
|
||||
|
||||
### Task 5: Wire device timezone into RunAgentInput forwardedProps
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/chat/data/services/ag_ui_service.dart`
|
||||
- Modify: `apps/lib/features/chat/data/models/ag_ui_event.dart` (only if serialization helper is needed)
|
||||
- Test: `apps/test/features/chat/ag_ui_event_test.dart`
|
||||
|
||||
- [ ] **Step 1: Write failing test for forwarded client_time payload**
|
||||
|
||||
Assert outgoing run request contains:
|
||||
- `forwardedProps.client_time.device_timezone`
|
||||
- `client_now_iso`
|
||||
- `client_epoch_ms`
|
||||
|
||||
- [ ] **Step 2: Run test to confirm RED**
|
||||
|
||||
Run: `cd apps && flutter test test/features/chat/ag_ui_event_test.dart`
|
||||
Expected: FAIL
|
||||
|
||||
- [ ] **Step 3: Implement payload injection in one place**
|
||||
|
||||
Add a single helper to build client time context and attach it to run input requests.
|
||||
|
||||
- [ ] **Step 4: Run test to confirm GREEN**
|
||||
|
||||
Run: `cd apps && flutter test test/features/chat/ag_ui_event_test.dart`
|
||||
Expected: PASS
|
||||
|
||||
|
||||
### Task 6: Remove implicit local-time rendering and render by event timezone
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/calendar/data/models/schedule_item_model.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/messages/ui/widgets/calendar_message_card.dart`
|
||||
- Modify: `apps/lib/features/calendar/ui/widgets/create_event_sheet.dart`
|
||||
- Test: `apps/test/features/calendar/ui/calendar_time_utils_test.dart`
|
||||
- Test: `apps/test/features/calendar/ui/create_event_sheet_time_align_test.dart`
|
||||
|
||||
- [ ] **Step 1: Write failing tests for timezone-specific rendering**
|
||||
|
||||
Cover cases:
|
||||
- same UTC event shows different local clock time under different `event.timezone`
|
||||
- list/day/week/month are consistent for one event
|
||||
- create sheet sends explicit timezone in payload
|
||||
|
||||
- [ ] **Step 2: Run tests to confirm RED**
|
||||
|
||||
Run: `cd apps && flutter test test/features/calendar/ui/calendar_time_utils_test.dart test/features/calendar/ui/create_event_sheet_time_align_test.dart`
|
||||
Expected: FAIL
|
||||
|
||||
- [ ] **Step 3: Implement deterministic time conversion utility**
|
||||
|
||||
Implement one utility used by all calendar UI surfaces:
|
||||
- input: UTC datetime + IANA timezone
|
||||
- output: event-local datetime
|
||||
|
||||
Replace direct `.toLocal()` usage in calendar model/view with this utility.
|
||||
|
||||
- [ ] **Step 4: Enforce explicit timezone on create/update payload**
|
||||
|
||||
Create/update must always include `timezone` field from selected event timezone.
|
||||
|
||||
- [ ] **Step 5: Run Flutter tests**
|
||||
|
||||
Run: `cd apps && flutter test test/features/calendar/ui/calendar_time_utils_test.dart test/features/calendar/ui/create_event_sheet_time_align_test.dart`
|
||||
Expected: PASS
|
||||
|
||||
|
||||
### Task 7: End-to-end verification matrix and release checklist
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/plans/timezone-e2e-checklist.md`
|
||||
- Test: `backend/tests/integration/test_schedule_items_routes.py`
|
||||
- Test: `apps/test/features/calendar/ui/create_event_sheet_time_align_test.dart`
|
||||
|
||||
- [ ] **Step 1: Add reproducible matrix**
|
||||
|
||||
Matrix axes:
|
||||
- device timezone: `America/Los_Angeles`, `Asia/Shanghai`
|
||||
- profile timezone: `Asia/Shanghai`, `Europe/Paris`
|
||||
- explicit event timezone: `Asia/Tokyo`
|
||||
|
||||
- [ ] **Step 2: Run backend + frontend verification commands**
|
||||
|
||||
Run:
|
||||
- `cd backend && uv run pytest tests/unit/core/agentscope/test_system_prompt.py tests/unit/core/agentscope/test_calendar_tools.py tests/integration/test_schedule_items_routes.py -v`
|
||||
- `cd apps && flutter test test/features/chat/ag_ui_event_test.dart test/features/calendar/ui/calendar_time_utils_test.dart test/features/calendar/ui/create_event_sheet_time_align_test.dart`
|
||||
|
||||
Expected: all PASS
|
||||
|
||||
- [ ] **Step 3: Manual scenario check**
|
||||
|
||||
Manual script:
|
||||
1. device timezone set to Los Angeles
|
||||
2. profile timezone set to Shanghai
|
||||
3. ask agent create "明天上午9点开会"
|
||||
4. verify assistant text, tool card, DB UTC value, and calendar detail all align to chosen event timezone semantics
|
||||
|
||||
- [ ] **Step 4: Capture release notes**
|
||||
|
||||
Record:
|
||||
- removed hidden timezone defaults
|
||||
- deterministic precedence
|
||||
- no schema expansion
|
||||
|
||||
---
|
||||
|
||||
Plan complete and saved to `docs/superpowers/plans/2026-03-16-calendar-timezone-unification.md`. Ready to execute?
|
||||
Reference in New Issue
Block a user