# Inbox Messages 协议

本文档定义 `/api/v1/inbox/messages` 的收件箱消息协议。

Base URL: `/api/v1/inbox/messages`

---

## 端点

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `` | 获取消息列表 |
| PATCH | `/{message_id}/read` | 标记消息为已读 |

---

## 枚举类型

### InboxMessageType

| 值 | 说明 |
|---|---|
| `friend_request` | 好友申请 |
| `calendar` | 日历消息 |
| `system` | 系统消息 |
| `group` | 群组消息 |

### InboxMessageStatus

| 值 | 说明 |
|---|---|
| `pending` | 待处理 |
| `accepted` | 已接受 |
| `rejected` | 已拒绝 |
| `dismissed` | 已忽略 |

---

## 消息内容类型

### CalendarInviteContent

```json
{
  "type": "invite",
  "permission": "int (1=view, 4=edit, 8=invite)",
  "action": "pending"
}
```

### CalendarUpdateContent

```json
{
  "type": "update",
  "title": "string",
  "action": "updated"
}
```

### CalendarDeleteContent

```json
{
  "type": "delete",
  "title": "string",
  "action": "deleted"
}
```

### FriendshipContent

```json
{
  "type": "request",
  "message": "string | null"
}
```

---

## 数据结构

### InboxMessageResponse

```json
{
  "id": "uuid",
  "recipient_id": "uuid",
  "sender_id": "uuid | null",
  "message_type": "InboxMessageType",
  "schedule_item_id": "uuid | null",
  "friendship_id": "uuid | null",
  "group_id": "uuid | null",
  "content": "CalendarInviteContent | CalendarUpdateContent | CalendarDeleteContent | FriendshipContent | null",
  "is_read": "boolean",
  "status": "InboxMessageStatus",
  "created_at": "datetime"
}
```

---

## 1) GET `/`

获取消息列表。

### Query Parameters

- `is_read`: boolean | null（可选，筛选已读/未读状态）

### Response

`InboxMessageResponse` 对象数组。

---

## 2) PATCH `/{message_id}/read`

标记指定消息为已读。

### Path Parameters

- `message_id`: 消息 UUID

### Response

`InboxMessageResponse` 对象。