Skip to content

feat(schedule): 实现日程聚合、PostgreSQL/SQLite 与日历读取闭环 #176

Description

@znnnnnnn-wil

背景

本 Issue 是人员二号(日程模块)的总跟踪 Issue。后续允许由多个 PR 分阶段交付,所有阶段性 PR 使用 Part of #176 关联;只有全部验收项完成后,最后一个 PR 才使用 Closes #176

相关设计:

目标

实现 Schedule 聚合在云端 PostgreSQL 和客户端 SQLite 的完整数据闭环,为 Agent 提供日程业务操作,为客户端提供云端确认快照落库、按日读取、日历展示及本地提醒数据读取能力。云端是业务写入的唯一权威,客户端只应用服务端确认后的最终快照。

核心协作接口

提供给 Agent(人员五号)

  • 创建日程:支持一次性、周期性、全天、时间和地点日程。
  • 查找日程:支持 Agent 查询、目标匹配、指代消解和多结果消歧。
  • 修改日程:修改 titlelocation_name 等日程字段;周期日程修改作用于整个系列。
  • 删除普通日程:云端软删除并返回最终快照。
  • 删除周期日程:按日程 IANA timezone 取得系统当前本地日期,并定位该日期当天或之后的第一个周期实例;支持仅删除该实例,或删除该实例及全部未来实例。调用方不能自行指定任意删除日期。

提供给客户端

  • 按日读取:用户选择日期后,从本地 SQLite 返回当天的一次性、全天和周期日程实例,并应用周期例外。
  • 应用 WebSocket 快照:把服务端成功写入 PostgreSQL 后返回的最终快照同步到 SQLite;统一覆盖创建、修改、普通删除、周期删除和周期例外。

后端工作范围

  • 定义 Schedule、周期例外、命令、查询、快照、结果及业务错误契约。
  • 按 v3.10 设计维护 PostgreSQL schedules 模型和 Alembic 迁移。
  • 实现 PostgreSQL schedule_occurrence_overrides 模型和迁移。
  • 实现账号隔离的 Schedule Repository 与周期例外 Repository。
  • 实现创建、查找、修改、普通删除和周期删除业务服务。
  • 实现 revision 乐观版本校验、软删除和最终持久化快照生成。
  • 实现一次性、周期性、全天、时间、地点及单一提醒字段约束。
  • 为人员一号的全量快照 HTTP 提供账号级日程与周期例外查询能力。
  • 补齐单元测试、Repository 集成测试、迁移测试及架构边界测试。

客户端工作范围

  • 建立 SQLite local_schedules 表及版本化迁移。
  • 建立 SQLite local_schedule_occurrence_overrides 表及版本化迁移。
  • 事务应用 WebSocket 云端确认快照。
  • 应用人员一号 HTTP 返回的账号全量恢复快照。
  • 根据 cloud_revision 忽略旧快照,维护软删除和账号隔离。
  • 展开 RRULE,并应用 cancel / replace 周期例外。
  • 提供按日、日期范围、列表和详情的本地读取能力。
  • 实现传统月历、日程列表和日程详情的只读展示,不提供 GUI 编辑表单。
  • 向人员三号提供本地日程、提醒配置和监听运行字段的读取接口;人员三号不直接写 SQL。
  • 在快照成功落库后通知提醒模块注册或重建监听。

数据与业务约束

  • 每条日程最多一个提醒,提醒配置作为 Schedule 字段保存,不建立独立 Reminder 表或 Reminder CRUD。
  • 周期日程只持久化 RRULE;正常实例按需展开,单次删除或替换写入 occurrence override。
  • next_trigger_atsnoozed_untilgeofence_armed 等仅属于客户端运行状态,不上传云端。
  • 客户端不得生成服务端不存在的新日程,也不得绕过云端自行确认创建、修改或删除。
  • 云端事务成功并返回最终快照后,客户端才能应用业务变更。

职责边界(不在本 Issue 范围)

  • 账号注册、JWT、HTTP 路由和数据库基础设施由人员一号负责。
  • Android 权限、时间/地点监听、提醒送达、完成和延期由人员三号负责。
  • WebSocket 连接、音频收发和消息传输由人员四号负责。
  • LLM 意图理解、追问、消歧和二次确认由人员五号负责。
  • 不实现 GUI 日程创建或编辑表单。

分阶段交付

  • 日程服务与客户端同步接口骨架(PR 167)。
  • PostgreSQL 模型、迁移与 Repository。
  • 日程 CRUD、周期范围和业务校验。
  • SQLite 表、迁移与云端快照应用。
  • RRULE 展开、按日查询和日历只读展示。
  • 与人员一号、三号、四号、五号的集成测试。

验收标准

  • Agent 能通过稳定业务接口创建、查找、修改和删除日程。
  • 普通删除与两种周期删除语义可被测试并正确返回最终快照。
  • PostgreSQL 写入成功后,WebSocket 快照能够事务应用到 SQLite。
  • 首次安装、换设备或本地数据丢失后可应用 HTTP 全量快照恢复。
  • 用户选择日期时能够从本地正确看到一次性、全天和周期实例。
  • 周期 cancel / replace 例外在云端与本地结果一致。
  • 人员三号能够通过接口获得提醒监听所需数据,且无需直接访问 SQLite。
  • 断网时已同步日程仍可被本地读取;离线不允许业务写入。
  • 所有后端 Ruff、pytest、架构检查和前端 lint、类型、格式检查通过。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions