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)
|
|||
|
|
}
|
|||
|
|
|