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