social-app/docs/protocols/calendar/schedule-items.md

Schedule Items 协议

本文档定义 /api/v1/schedule-items 的日历日程管理协议。

Base URL: /api/v1/schedule-items

---

端点

方法	路径	说明
POST	``	创建日程
GET	``	按日期范围查询日程
GET	/{item_id}	获取指定日程详情
PATCH	/{item_id}	更新日程
DELETE	/{item_id}	删除日程
POST	/{item_id}/share	分享日程给其他用户
POST	/{item_id}/accept	接受日程订阅
POST	/{item_id}/reject	拒绝日程订阅

---

枚举类型

ScheduleItemStatus

值	说明
active	进行中
archived	已归档

兼容策略：历史数据中若存在 completed 或 canceled，服务端统一按 archived 语义处理；新写入仅允许 active 或 archived。

ScheduleItemSourceType

值	说明
manual	手动创建
imported	导入
agent_generated	Agent 生成

AttachmentType

值	说明
document	文档
reminder	提醒

---

数据结构

ScheduleItemMetadata

{
  "color": "#FF5733 | null",
  "location": "string | null",
  "notes": "string | null",
  "attachments": [
    {
      "name": "string",
      "type": "document | reminder",
      "visible_to": ["uuid"],
      "url": "string | null",
      "note": "string | null",
      "content": "string | null"
    }
  ],
  "reminder_minutes": "int (0-10080) | null",
  "version": 1
}

ScheduleItemCreateRequest

{
  "title": "string (1-255)",
  "description": "string | null (max 2000)",
  "start_at": "datetime (必须包含时区)",
  "end_at": "datetime | null (必须包含时区)",
  "timezone": "string (IANA 时区)",
  "metadata": "ScheduleItemMetadata | null"
}

ScheduleItemUpdateRequest

{
  "title": "string | null (1-255)",
  "description": "string | null (max 2000)",
  "start_at": "datetime | null (必须包含时区)",
  "end_at": "datetime | null (必须包含时区)",
  "timezone": "string | null (IANA 时区)",
  "metadata": "ScheduleItemMetadata | null",
  "status": "ScheduleItemStatus | null (active | archived)"
}

ScheduleItemResponse

{
  "id": "uuid",
  "owner_id": "uuid",
  "title": "string",
  "description": "string | null",
  "start_at": "datetime",
  "end_at": "datetime | null",
  "timezone": "string",
  "metadata": "ScheduleItemMetadata | null",
  "status": "ScheduleItemStatus",
  "source_type": "ScheduleItemSourceType",
  "created_at": "datetime",
  "updated_at": "datetime",
  "permission": "int (位掩码: 1=view, 2=invite, 4=edit)",
  "is_owner": "boolean"
}

ScheduleItemShareRequest

{
  "phone": "+8613812345678",
  "permission_view": "boolean (default: true)",
  "permission_edit": "boolean (default: false)",
  "permission_invite": "boolean (default: false)"
}

说明：permission_view、permission_edit、permission_invite 为布尔值，内部会转换为位掩码整数：

• permission_view = 1
• permission_invite = 2
• permission_edit = 4

ScheduleItemShareResponse

{
  "message": "string"
}

---

1) POST /

创建日程。

Request

ScheduleItemCreateRequest 对象。

Response

ScheduleItemResponse 对象，状态码 201。

---

2) GET /

按日期范围查询日程。

Query Parameters

• start_at: 开始时间（必须包含时区）
• end_at: 结束时间（必须包含时区）

Response

ScheduleItemResponse 对象数组。

---

3) GET /{item_id}

获取指定日程详情。

Path Parameters

• item_id: 日程 UUID

Response

ScheduleItemResponse 对象。

---

4) PATCH /{item_id}

更新日程（部分更新）。

Path Parameters

• item_id: 日程 UUID

Request

ScheduleItemUpdateRequest 对象。

Response

ScheduleItemResponse 对象。

---

5) DELETE /{item_id}

删除日程。

Path Parameters

• item_id: 日程 UUID

Response

204 No Content。

---

6) POST /{item_id}/share

分享日程给其他用户。

Path Parameters

• item_id: 日程 UUID

Request

ScheduleItemShareRequest 对象。

Response

ScheduleItemShareResponse 对象。

---

7) POST /{item_id}/accept

接受日程订阅邀请。

Path Parameters

• item_id: 日程 UUID

Response

字典对象。

---

8) POST /{item_id}/reject

拒绝日程订阅邀请。

Path Parameters

• item_id: 日程 UUID

Response

字典对象。