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

```json
{
  "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

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

### ScheduleItemUpdateRequest

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

字典对象。