352 lines
12 KiB
Plaintext
352 lines
12 KiB
Plaintext
syntax = "v1"
|
||
|
||
// =================================================================
|
||
// Type: 聊天室 (Chat Room)
|
||
// =================================================================
|
||
type (
|
||
// CreateRoomReq 創建聊天室請求
|
||
CreateRoomReq {
|
||
Authorization
|
||
Name string `json:"name" validate:"required,min=1,max=100"` // 聊天室名稱
|
||
Status string `json:"status,optional" validate:"omitempty,oneof=active archived"` // 狀態，預設為 active
|
||
}
|
||
|
||
// UpdateRoomReq 更新聊天室請求
|
||
UpdateRoomReq {
|
||
Authorization
|
||
RoomID string `path:"room_id" validate:"required"`
|
||
Name *string `json:"name,optional" validate:"omitempty,min=1,max=100"`
|
||
Status *string `json:"status,optional" validate:"omitempty,oneof=active archived"`
|
||
}
|
||
|
||
// RoomResp 聊天室回應
|
||
RoomResp {
|
||
RoomID string `json:"room_id"`
|
||
Name string `json:"name"`
|
||
Status string `json:"status"`
|
||
CreatedAt string `json:"created_at"`
|
||
UpdatedAt string `json:"updated_at"`
|
||
}
|
||
|
||
// ListRoomsReq 查詢聊天室列表請求
|
||
ListRoomsReq {
|
||
Authorization
|
||
Status string `json:"status,optional" validate:"omitempty,oneof=active archived"` // 狀態篩選
|
||
PageSize int `json:"page_size,optional" validate:"omitempty,min=1,max=100"` // 每頁大小，預設 20
|
||
LastID string `json:"last_id,optional"` // 用於 cursor-based pagination
|
||
}
|
||
|
||
// ListRoomsResp 聊天室列表回應
|
||
ListRoomsResp {
|
||
Rooms []RoomResp `json:"rooms"`
|
||
LastID string `json:"last_id,optional"` // 用於下一頁查詢
|
||
Total int64 `json:"total,optional"` // 總數（僅第一頁返回）
|
||
}
|
||
|
||
// AddMemberReq 添加成員請求
|
||
AddMemberReq {
|
||
Authorization
|
||
RoomID string `json:"room_id" validate:"required"`
|
||
UID string `json:"uid" validate:"required"` // 要添加的用戶 UID
|
||
}
|
||
|
||
// RemoveMemberReq 移除成員請求
|
||
RemoveMemberReq {
|
||
Authorization
|
||
RoomID string `path:"room_id" validate:"required"`
|
||
UID string `path:"uid" validate:"required"` // 要移除的用戶 UID
|
||
}
|
||
|
||
// UpdateMemberRoleReq 更新成員角色請求
|
||
UpdateMemberRoleReq {
|
||
Authorization
|
||
RoomID string `path:"room_id" validate:"required"`
|
||
UID string `path:"uid" validate:"required"`
|
||
Role string `json:"role" validate:"required,oneof=admin member"`
|
||
}
|
||
|
||
// MemberResp 成員回應
|
||
MemberResp {
|
||
RoomID string `json:"room_id"`
|
||
UID string `json:"uid"`
|
||
Role string `json:"role"`
|
||
JoinedAt string `json:"joined_at"`
|
||
UpdatedAt string `json:"updated_at"`
|
||
}
|
||
|
||
// ListMembersResp 成員列表回應
|
||
ListMembersResp {
|
||
Members []Member `json:"members"`
|
||
Total int64 `json:"total"`
|
||
}
|
||
|
||
// MemberResp 成員回應
|
||
Member {
|
||
UID string `json:"uid"`
|
||
Name string `json:"name"`
|
||
Avatar string `json:"avatar"`
|
||
}
|
||
|
||
// GetUserRoomsResp 用戶聊天室列表回應
|
||
GetUserRoomsResp {
|
||
Rooms []RoomResp `json:"rooms"`
|
||
Total int64 `json:"total"`
|
||
}
|
||
|
||
RoomReq {
|
||
Authorization
|
||
RoomID string `path:"room_id"`
|
||
}
|
||
)
|
||
|
||
// =================================================================
|
||
// Type: 訊息 (Message)
|
||
// =================================================================
|
||
type (
|
||
// SendMessageReq 發送訊息請求
|
||
SendMessageReq {
|
||
Authorization
|
||
RoomID string `path:"room_id" validate:"required"`
|
||
Content string `json:"content" validate:"required,min=1,max=5000"` // 訊息內容
|
||
}
|
||
|
||
// SendMessageResp 發送訊息回應
|
||
SendMessageResp {
|
||
RoomID string `json:"room_id"`
|
||
BucketDay string `json:"bucket_day"` // yyyyMMdd
|
||
TS int64 `json:"ts"` // timestamp
|
||
UID string `json:"uid"`
|
||
Content string `json:"content"`
|
||
}
|
||
|
||
// ListMessagesReq 查詢訊息列表請求
|
||
ListMessagesReq {
|
||
Authorization
|
||
RoomID string `path:"room_id" validate:"required"`
|
||
BucketDay string `json:"bucket_day,optional"` // yyyyMMdd，不提供則使用今天
|
||
PageSize int64 `json:"page_size,optional" validate:"omitempty,min=1,max=100"` // 每頁大小，預設 20
|
||
LastTS int64 `json:"last_ts,optional"` // 用於 cursor-based pagination
|
||
}
|
||
|
||
// ListMessagesResp 訊息列表回應
|
||
ListMessagesResp {
|
||
Messages []MessageResp `json:"messages"`
|
||
Total int64 `json:"total,optional"` // 總數（僅第一頁返回）
|
||
LastTS int64 `json:"last_ts,optional"` // 用於下一頁查詢
|
||
}
|
||
|
||
// MessageResp 訊息回應
|
||
MessageResp {
|
||
RoomID string `json:"room_id"`
|
||
BucketDay string `json:"bucket_day"` // yyyyMMdd
|
||
TS int64 `json:"ts"` // timestamp
|
||
UID string `json:"uid"`
|
||
Content string `json:"content"`
|
||
}
|
||
|
||
|
||
IsMemberResp {
|
||
IsMember bool `json:"is_member"`
|
||
}
|
||
)
|
||
|
||
// =================================================================
|
||
// Service: 聊天 API - 需要登入 (Chat Service)
|
||
// =================================================================
|
||
@server(
|
||
group: chat
|
||
prefix: /api/v1/chat
|
||
schemes: https
|
||
timeout: 30s
|
||
middleware: AuthMiddleware
|
||
)
|
||
service gateway {
|
||
// ==================== 聊天室管理 ====================
|
||
@doc(
|
||
summary: "創建聊天室"
|
||
description: "創建一個新的聊天室，創建者自動成為管理員"
|
||
)
|
||
/*
|
||
@respdoc-200 (RoomResp) // 建立成功
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-422 (ErrorResp) "創建太多聊天室了(目前仙梅設定上限)"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler createRoom
|
||
post /rooms (CreateRoomReq) returns (RoomResp)
|
||
|
||
@doc(
|
||
summary: "取得聊天室資訊"
|
||
description: "根據 room_id 取得聊天室的詳細資訊"
|
||
)
|
||
/*
|
||
@respdoc-200 (RoomResp) // 取得聊天室
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "不再房間內的人"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler getRoom
|
||
get /rooms/:room_id (RoomReq) returns (RoomResp)
|
||
|
||
@doc(
|
||
summary: "更新聊天室資訊"
|
||
description: "更新聊天室的名稱或狀態，需要管理員權限"
|
||
)
|
||
/*
|
||
@respdoc-200 (RoomResp) // 取得聊天室
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "不再房間內的人"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler updateRoom
|
||
put /rooms/:room_id (UpdateRoomReq) returns (RoomResp)
|
||
|
||
@doc(
|
||
summary: "刪除聊天室"
|
||
description: "刪除聊天室及其所有成員和訊息，需要管理員權限"
|
||
)
|
||
/*
|
||
@respdoc-200 (RespOK)
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler deleteRoom
|
||
delete /rooms/:room_id (RoomReq) returns (RespOK)
|
||
|
||
@doc(
|
||
summary: "查詢聊天室列表"
|
||
description: "查詢聊天室列表，支援狀態篩選和分頁(自己的，之後再支援管理員吃全部)"
|
||
)
|
||
/*
|
||
@respdoc-200 (ListRoomsResp) // 取得聊天室列表
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler listRooms
|
||
get /rooms (ListRoomsReq) returns (ListRoomsResp)
|
||
|
||
// ==================== 成員管理 ====================
|
||
@doc(
|
||
summary: "添加成員到聊天室"
|
||
description: "將用戶添加到聊天室，需要管理員權限"
|
||
)
|
||
/*
|
||
@respdoc-200 (MemberResp) // 取得聊天室列表
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler addMember
|
||
post /rooms/:room_id/members (AddMemberReq) returns (MemberResp)
|
||
|
||
@doc(
|
||
summary: "移除聊天室成員"
|
||
description: "將成員從聊天室中移除，需要管理員權限或本人操作"
|
||
)
|
||
/*
|
||
@respdoc-200 (RespOK)
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler removeMember
|
||
delete /rooms/:room_id/members/:uid (RemoveMemberReq) returns (RespOK)
|
||
|
||
@doc(
|
||
summary: "更新成員角色"
|
||
description: "更新成員在聊天室中的角色，需要管理員權限"
|
||
)
|
||
/*
|
||
@respdoc-200 (MemberResp)
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-404 (ErrorResp) "找不到聊天室"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler updateMemberRole
|
||
put /rooms/:room_id/members/:uid/role (UpdateMemberRoleReq) returns (MemberResp)
|
||
|
||
@doc(
|
||
summary: "查詢聊天室成員列表"
|
||
description: "查詢指定聊天室的所有成員"
|
||
)
|
||
/*
|
||
@respdoc-200 (ListMembersResp)
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler listMembers
|
||
get /rooms/:room_id/members (RoomReq) returns (ListMembersResp)
|
||
|
||
// ==================== 用戶相關 ====================
|
||
@doc(
|
||
summary: "查詢用戶所在的聊天室"
|
||
description: "查詢當前用戶或指定用戶所在的所有聊天室"
|
||
)
|
||
/*
|
||
@respdoc-200 (GetUserRoomsResp)
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler getUserRooms
|
||
get /users/rooms (Authorization) returns (GetUserRoomsResp)
|
||
|
||
@doc(
|
||
summary: "檢查用戶是否在聊天室中"
|
||
description: "檢查指定用戶是否在某個聊天室中"
|
||
)
|
||
/*
|
||
@respdoc-200 (IsMemberResp)
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler checkUserInRoom
|
||
get /rooms/:room_id/members/:uid (RemoveMemberReq) returns (IsMemberResp)
|
||
|
||
// ==================== 訊息相關 ====================
|
||
@doc(
|
||
summary: "發送訊息"
|
||
description: "在聊天室中發送訊息，需要是聊天室成員"
|
||
)
|
||
/*
|
||
@respdoc-200 (RespOK)
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler sendMessage
|
||
post /rooms/:room_id/messages (SendMessageReq) returns (RespOK)
|
||
|
||
@doc(
|
||
summary: "查詢訊息列表"
|
||
description: "查詢聊天室中的訊息列表，支援分頁和按日期篩選"
|
||
)
|
||
/*
|
||
@respdoc-200 (ListMessagesResp)
|
||
@respdoc-400 (ErrorResp) "請求參數格式錯誤"
|
||
@respdoc-401 (ErrorResp) "權限不夠"
|
||
@respdoc-403 (ErrorResp) "沒有登入"
|
||
@respdoc-500 (ErrorResp) // 伺服器內部錯誤
|
||
*/
|
||
@handler listMessages
|
||
get /rooms/:room_id/messages (ListMessagesReq) returns (ListMessagesResp)
|
||
}
|
||
|