Full Restruct API and Services

Signed-off-by: Asai Neko <sugar@sne.moe>
2026-01-29 00:45:58 +08:00
parent 89e7f1a41a
commit 79dfa8499c
27 changed files with 4011 additions and 21 deletions
--- a/api/auth/exchange.go
+++ b/api/auth/exchange.go
@@ -0,0 +1,87 @@
+package auth
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_auth"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+// Exchange handles the authorization code swap process.
+// @Summary      Exchange Auth Code
+// @Description  Exchanges client credentials and user session for a specific redirect authorization code.
+// @Tags         Authentication
+// @Accept       json
+// @Produce      json
+// @Param        payload  body      service_auth.ExchangeData  true  "Exchange Request Credentials"
+// @Success      200      {object}  service_auth.ExchangeResult
+// @Failure      400      {string}  string "Invalid Input"
+// @Failure      401      {string}  string "Unauthorized"
+// @Failure      500      {string}  string "Internal Server Error"
+// @Security     ApiKeyAuth
+// @Router       /auth/exchange [post]
+func (self *AuthHandler) Exchange(c *gin.Context) {
+	var exchangeData service_auth.ExchangeData
+
+	if err := c.ShouldBindJSON(&exchangeData); err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceExchange).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	userIdOrig, ok := c.Get("user_id")
+	if !ok {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceExchange).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorUnauthorized).
+			SetError(nil).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 401, errorCode)
+		return
+	}
+
+	userId, err := uuid.Parse(userIdOrig.(string))
+	if err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusServer).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceExchange).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorUuidParseFailed).
+			SetError(err).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 500, errorCode)
+		return
+	}
+
+	result := self.svc.Exchange(&service_auth.ExchangePayload{
+		Context: c,
+		UserId:  userId,
+		Data:    &exchangeData,
+	})
+
+	if result.Common.Exception.Original != exception.CommonSuccess {
+		utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+		return
+	}
+
+	utils.HttpResponse(c, 200, result.Common.Exception.String(), result.Data)
+}
--- a/api/auth/handler.go
+++ b/api/auth/handler.go
@@ -1,8 +1,23 @@
 package auth

 import (
+	"nixcn-cms/middleware"
+	"nixcn-cms/service/service_auth"
+
 	"github.com/gin-gonic/gin"
 )

-func ApiHandler(r *gin.RouterGroup) {
+type AuthHandler struct {
+	svc service_auth.AuthService
+}
+
+func ApiHandler(r *gin.RouterGroup) {
+	authSvc := service_auth.NewAuthService()
+	authHandler := &AuthHandler{authSvc}
+
+	r.GET("/redirect", authHandler.Redirect)
+	r.POST("/magic", middleware.ApiVersionCheck(), authHandler.Magic)
+	r.POST("/token", middleware.ApiVersionCheck(), authHandler.Token)
+	r.POST("/refresh", middleware.ApiVersionCheck(), authHandler.Refresh)
+	r.POST("/exchange", middleware.ApiVersionCheck(), middleware.JWTAuth(), authHandler.Exchange)
 }
--- a/api/auth/magic.go
+++ b/api/auth/magic.go
@@ -0,0 +1,54 @@
+package auth
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_auth"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Magic handles the "Magic Link" authentication request.
+// @Summary      Request Magic Link
+// @Description  Verifies Turnstile token and sends an authentication link via email. Returns the URI directly if debug mode is enabled.
+// @Tags         Authentication
+// @Accept       json
+// @Produce      json
+// @Param        payload  body      service_auth.MagicData  true  "Magic Link Request Data"
+// @Success      200      {object}  service_auth.MagicResult
+// @Failure      400      {string}  string "Invalid Input"
+// @Failure      403      {string}  string "Turnstile Verification Failed"
+// @Failure      500      {string}  string "Internal Server Error"
+// @Router       /auth/magic [post]
+func (self *AuthHandler) Magic(c *gin.Context) {
+	var magicData service_auth.MagicData
+
+	if err := c.ShouldBindJSON(&magicData); err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceMagic).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	magicData.ClientIP = c.ClientIP()
+
+	result := self.svc.Magic(&service_auth.MagicPayload{
+		Context: c,
+		Data:    &magicData,
+	})
+
+	if result.Common.Exception.Original != exception.CommonSuccess {
+		utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+		return
+	}
+
+	utils.HttpResponse(c, 200, result.Common.Exception.String(), result.Data)
+}
--- a/api/auth/redirect.go
+++ b/api/auth/redirect.go
@@ -0,0 +1,59 @@
+package auth
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_auth"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Redirect handles the post-verification callback and redirects the user to the target application.
+// @Summary      Handle Auth Callback and Redirect
+// @Description  Verifies the temporary email code, ensures the user exists (or creates one), validates the client's redirect URI, and finally performs a 302 redirect with a new authorization code.
+// @Tags         Authentication
+// @Accept       x-www-form-urlencoded
+// @Produce      html
+// @Param        client_id     query     string  true  "Client Identifier"
+// @Param        redirect_uri  query     string  true  "Target Redirect URI"
+// @Param        code          query     string  true  "Temporary Verification Code"
+// @Param        state         query     string  false "Opaque state used to maintain state between the request and callback"
+// @Success      302           {string}  string  "Redirect to the provided RedirectUri with a new code"
+// @Failure      400           {string}  string  "Invalid Input / Client Not Found / URI Mismatch"
+// @Failure      403           {string}  string  "Invalid or Expired Verification Code"
+// @Failure      500           {string}  string  "Internal Server Error"
+// @Router       /auth/redirect [get]
+func (self *AuthHandler) Redirect(c *gin.Context) {
+	data := &service_auth.RedirectData{
+		ClientId:    c.Query("client_id"),
+		RedirectUri: c.Query("redirect_uri"),
+		State:       c.Query("state"),
+		Code:        c.Query("code"),
+	}
+
+	if data.ClientId == "" || data.RedirectUri == "" || data.Code == "" {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceRedirect).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(nil).
+			Throw(c).
+			String()
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	result := self.svc.Redirect(&service_auth.RedirectPayload{
+		Context: c,
+		Data:    data,
+	})
+
+	if result.Common.Exception.Original != exception.CommonSuccess {
+		utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+		return
+	}
+
+	c.Redirect(302, result.Data)
+}
--- a/api/auth/refresh.go
+++ b/api/auth/refresh.go
@@ -0,0 +1,52 @@
+package auth
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_auth"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Refresh handles the token rotation process.
+// @Summary      Refresh Access Token
+// @Description  Accepts a valid refresh token to issue a new access token and a rotated refresh token.
+// @Tags         Authentication
+// @Accept       json
+// @Produce      json
+// @Param        payload  body      service_auth.RefreshData  true  "Refresh Token Body"
+// @Success      200      {object}  service_auth.RefreshResult
+// @Failure      400      {string}  string "Invalid Input"
+// @Failure      401      {string}  string "Invalid Refresh Token"
+// @Failure      500      {string}  string "Internal Server Error"
+// @Router       /auth/refresh [post]
+func (self *AuthHandler) Refresh(c *gin.Context) {
+	var refreshData service_auth.RefreshData
+
+	if err := c.ShouldBindJSON(&refreshData); err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceRefresh).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	result := self.svc.Refresh(&service_auth.RefreshPayload{
+		Context: c,
+		Data:    &refreshData,
+	})
+
+	if result.Common.Exception.Original != exception.CommonSuccess {
+		utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+		return
+	}
+
+	utils.HttpResponse(c, 200, result.Common.Exception.String(), result.Data)
+}
--- a/api/auth/token.go
+++ b/api/auth/token.go
@@ -0,0 +1,52 @@
+package auth
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_auth"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Token exchanges an authorization code for access and refresh tokens.
+// @Summary      Exchange Code for Token
+// @Description  Verifies the provided authorization code and issues a pair of JWT tokens (Access and Refresh).
+// @Tags         Authentication
+// @Accept       json
+// @Produce      json
+// @Param        payload  body      service_auth.TokenData  true  "Token Request Body"
+// @Success      200      {object}  service_auth.TokenResult
+// @Failure      400      {string}  string "Invalid Input"
+// @Failure      403      {string}  string "Invalid or Expired Code"
+// @Failure      500      {string}  string "Internal Server Error"
+// @Router       /auth/token [post]
+func (self *AuthHandler) Token(c *gin.Context) {
+	var tokenData service_auth.TokenData
+
+	if err := c.ShouldBindJSON(&tokenData); err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceAuth).
+			SetEndpoint(exception.EndpointAuthServiceToken).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	result := self.svc.Token(&service_auth.TokenPayload{
+		Context: c,
+		Data:    &tokenData,
+	})
+
+	if result.Common.Exception.Original != exception.CommonSuccess {
+		utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+		return
+	}
+
+	utils.HttpResponse(c, 200, result.Common.Exception.String(), result.Data)
+}
--- a/api/event/checkin.go
+++ b/api/event/checkin.go
@@ -0,0 +1,113 @@
+package event
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_event"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+// Checkin generates a check-in code for a specific event.
+// @Summary      Generate Check-in Code
+// @Description  Creates a temporary check-in code for the authenticated user and event.
+// @Tags         Event
+// @Accept       json
+// @Produce      json
+// @Param        event_id  query     string  true  "Event UUID"
+// @Success      200       {object}  service_event.CheckinResult
+// @Router       /event/checkin [get]
+func (self *EventHandler) Checkin(c *gin.Context) {
+	userIdOrig, _ := c.Get("user_id")
+	userId, _ := uuid.Parse(userIdOrig.(string))
+
+	eventIdOrig := c.Query("event_id")
+	eventId, err := uuid.Parse(eventIdOrig)
+	if err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceEvent).
+			SetEndpoint(exception.EndpointEventServiceCheckin).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).String()
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	result := self.svc.Checkin(&service_event.CheckinPayload{
+		Context: c,
+		UserId:  userId,
+		Data:    &service_event.CheckinData{EventId: eventId},
+	})
+	utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String(), result.Data)
+}
+
+// CheckinSubmit validates a check-in code to complete attendance.
+// @Summary      Submit Check-in Code
+// @Description  Submits the generated code to mark the user as attended.
+// @Tags         Event
+// @Accept       json
+// @Produce      json
+// @Param        payload  body      service_event.CheckinSubmitData  true  "Checkin Code Data"
+// @Success      200      {object}  service_event.CheckinSubmitResult
+// @Router       /event/checkin/submit [post]
+func (self *EventHandler) CheckinSubmit(c *gin.Context) {
+	var data service_event.CheckinSubmitData
+	if err := c.ShouldBindJSON(&data); err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceEvent).
+			SetEndpoint(exception.EndpointEventServiceCheckinSubmit).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).String()
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	result := self.svc.CheckinSubmit(&service_event.CheckinSubmitPayload{
+		Context: c,
+		Data:    &data,
+	})
+	utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+}
+
+// CheckinQuery retrieves the check-in status of a user for an event.
+// @Summary      Query Check-in Status
+// @Description  Returns the timestamp of when the user checked in, or null if not yet checked in.
+// @Tags         Event
+// @Accept       json
+// @Produce      json
+// @Param        event_id  query     string  true  "Event UUID"
+// @Success      200       {object}  service_event.CheckinQueryResult
+// @Router       /event/checkin/query [get]
+func (self *EventHandler) CheckinQuery(c *gin.Context) {
+	userIdOrig, _ := c.Get("user_id")
+	userId, _ := uuid.Parse(userIdOrig.(string))
+
+	eventIdOrig := c.Query("event_id")
+	eventId, err := uuid.Parse(eventIdOrig)
+	if err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusUser).
+			SetService(exception.ServiceEvent).
+			SetEndpoint(exception.EndpointEventServiceCheckinQuery).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorInvalidInput).
+			SetError(err).
+			Throw(c).String()
+		utils.HttpResponse(c, 400, errorCode)
+		return
+	}
+
+	result := self.svc.CheckinQuery(&service_event.CheckinQueryPayload{
+		Context: c,
+		UserId:  userId,
+		Data:    &service_event.CheckinQueryData{EventId: eventId},
+	})
+	utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String(), result.Data)
+}
--- a/api/event/handler.go
+++ b/api/event/handler.go
@@ -2,10 +2,22 @@ package event

 import (
 	"nixcn-cms/middleware"
+	"nixcn-cms/service/service_event"

 	"github.com/gin-gonic/gin"
 )

-func ApiHandler(r *gin.RouterGroup) {
-	r.Use(middleware.ApiVersionCheck(), middleware.JWTAuth(), middleware.Permission(10))
+type EventHandler struct {
+	svc service_event.EventService
+}
+
+func ApiHandler(r *gin.RouterGroup) {
+	eventSvc := service_event.NewEventService()
+	eventHandler := &EventHandler{eventSvc}
+
+	r.Use(middleware.ApiVersionCheck(), middleware.JWTAuth(), middleware.Permission(10))
+	r.GET("/info", eventHandler.Info)
+	r.GET("/checkin", eventHandler.Checkin)
+	r.GET("/checkin/query", eventHandler.CheckinQuery)
+	r.POST("/checkin/submit", middleware.Permission(20), eventHandler.CheckinSubmit)
 }
--- a/api/event/info.go
+++ b/api/event/info.go
@@ -0,0 +1,55 @@
+package event
+
+import (
+	"nixcn-cms/internal/exception"
+	"nixcn-cms/service/service_event"
+	"nixcn-cms/utils"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+// Info retrieves basic information about a specific event.
+// @Summary      Get Event Information
+// @Description  Fetches the name, start time, and end time of an event using its UUID.
+// @Tags         Event
+// @Accept       json
+// @Produce      json
+// @Param        event_id  query     string  true  "Event UUID"
+// @Success      200       {object}  service_event.InfoResult
+// @Failure      400       {string}  string  "Invalid Input"
+// @Failure      404       {string}  string  "Event Not Found"
+// @Failure      500       {string}  string  "Internal Server Error"
+// @Router       /event/info [get]
+func (self *EventHandler) Info(c *gin.Context) {
+	eventIdOrig := c.Query("event_id")
+	eventId, err := uuid.Parse(eventIdOrig)
+	if err != nil {
+		errorCode := new(exception.Builder).
+			SetStatus(exception.StatusServer).
+			SetService(exception.ServiceEvent).
+			SetEndpoint(exception.EndpointEventServiceInfo).
+			SetType(exception.TypeCommon).
+			SetOriginal(exception.CommonErrorUuidParseFailed).
+			SetError(err).
+			Throw(c).
+			String()
+
+		utils.HttpResponse(c, 500, errorCode)
+		return
+	}
+
+	result := self.svc.Info(&service_event.InfoPayload{
+		Context: c,
+		Data: &service_event.InfoData{
+			EventId: eventId,
+		},
+	})
+
+	if result.Common.Exception.Original != exception.CommonSuccess {
+		utils.HttpResponse(c, result.Common.HttpCode, result.Common.Exception.String())
+		return
+	}
+
+	utils.HttpResponse(c, 200, result.Common.Exception.String(), result.Data)
+}
--- a/api/user/full.go
+++ b/api/user/full.go
@@ -8,6 +8,16 @@ import (
 	"github.com/gin-gonic/gin"
 )

+// Full retrieves the complete list of users directly from the database table.
+// @Summary      Get Full User Table
+// @Description  Fetches all user records without pagination. This is typically used for administrative overview or data export.
+// @Tags         User
+// @Accept       json
+// @Produce      json
+// @Success      200      {object}  service_user.UserTableResult
+// @Failure      500      {string}  string "Internal Server Error (Database Error)"
+// @Security     ApiKeyAuth
+// @Router       /user/full [get]
 func (self *UserHandler) Full(c *gin.Context) {
 	userTablePayload := &service_user.UserTablePayload{
 		Context: c,
--- a/api/user/info.go
+++ b/api/user/info.go
@@ -9,6 +9,18 @@ import (
 	"github.com/google/uuid"
 )

+// Info retrieves the profile information of the currently authenticated user.
+// @Summary      Get My User Information
+// @Description  Fetches the complete profile data for the user associated with the provided session/token.
+// @Tags         User
+// @Accept       json
+// @Produce      json
+// @Success      200      {object}  service_user.UserInfoResult
+// @Failure      403      {string}  string "Missing User ID / Unauthorized"
+// @Failure      404      {string}  string "User Not Found"
+// @Failure      500      {string}  string "Internal Server Error (UUID Parse Failed)"
+// @Security     ApiKeyAuth
+// @Router       /user/info [get]
 func (self *UserHandler) Info(c *gin.Context) {
 	userIdOrig, ok := c.Get("user_id")
 	if !ok {
--- a/api/user/list.go
+++ b/api/user/list.go
@@ -8,6 +8,18 @@ import (
 	"github.com/gin-gonic/gin"
 )

+// List retrieves a paginated list of users from the search engine.
+// @Summary      List Users
+// @Description  Fetches a list of users with support for pagination via limit and offset.
+// @Tags         User
+// @Accept       json
+// @Produce      json
+// @Param        limit   query     string  false  "Maximum number of users to return (default 0)"
+// @Param        offset  query     string  true   "Number of users to skip"
+// @Success      200     {object}  service_user.UserListResult
+// @Failure      400     {string}  string  "Invalid Input (Format Error)"
+// @Failure      500     {string}  string  "Internal Server Error (Search Engine or Missing Offset)"
+// @Router       /user/list [get]
 func (self *UserHandler) List(c *gin.Context) {
 	type ListQuery struct {
 		Limit  *string `form:"limit"`
--- a/api/user/update.go
+++ b/api/user/update.go
@@ -9,6 +9,20 @@ import (
 	"github.com/google/uuid"
 )

+// Update modifies the profile information for the currently authenticated user.
+// @Summary      Update User Information
+// @Description  Updates specific profile fields such as username, nickname, subtitle, avatar (URL), and bio (Base64).
+// @Description  Validation: Username (5-255 chars), Nickname (max 24 chars), Subtitle (max 32 chars).
+// @Tags         User
+// @Accept       json
+// @Produce      json
+// @Param        payload  body      service_user.UserInfoData  true  "Updated User Profile Data"
+// @Success      200      {object}  service_user.UserInfoResult
+// @Failure      400      {string}  string "Invalid Input (Validation Failed)"
+// @Failure      403      {string}  string "Missing User ID / Unauthorized"
+// @Failure      500      {string}  string "Internal Server Error (Database Error / UUID Parse Failed)"
+// @Security     ApiKeyAuth
+// @Router       /user/update [patch]
 func (self *UserHandler) Update(c *gin.Context) {
 	userIdOrig, ok := c.Get("user_id")
 	if !ok {