feat: follow llm.txt

2025-12-18 10:27:40 +08:00
parent 819fa7f218
commit 674c562831
25 changed files with 2775 additions and 106 deletions
--- a/backend/app/http/super/auth.go
+++ b/backend/app/http/super/auth.go
@@ -56,7 +56,7 @@ func (ctl *auth) login(ctx fiber.Ctx, form *dto.LoginForm) (*dto.LoginResponse,
 //	@Tags		Super
 //	@Accept		json
 //	@Produce	json
-//	@Success	200		{object}	dto.LoginResponse	"成功"
+//	@Success	200	{object}	dto.LoginResponse	"成功"
 //
 //	@Router		/super/v1/auth/token [get]
 func (ctl *auth) token(ctx fiber.Ctx) (*dto.LoginResponse, error) {
--- a/backend/app/http/super/routes.gen.go
+++ b/backend/app/http/super/routes.gen.go
@@ -18,7 +18,7 @@ import (
 // Routes implements the HttpRoute contract and provides route registration
 // for all controllers in the super module.
 //
-// @provider contracts.HttpRoute atom.GroupRoutes
+//	@provider	contracts.HttpRoute atom.GroupRoutes
 type Routes struct {
 	log         *log.Entry `inject:"false"`
 	middlewares *middlewares.Middlewares
--- a/backend/app/http/super/routes.manual.go
+++ b/backend/app/http/super/routes.manual.go
@@ -1,7 +1,7 @@
 package super

 func (r *Routes) Path() string {
-	return "/super"
+	return "/super/v1"
 }

 func (r *Routes) Middlewares() []any {
--- a/backend/app/http/super/tenant.go
+++ b/backend/app/http/super/tenant.go
@@ -20,7 +20,7 @@ type tenant struct{}
 //	@Tags		Super
 //	@Accept		json
 //	@Produce	json
-//	@Param		filter	query		dto.TenantFilter						true	"Filter"
+//	@Param		filter	query		dto.TenantFilter	true	"Filter"
 //	@Success	200		{object}	requests.Pager{items=dto.TenantItem}
 //
 //	@Router		/super/v1/tenants [get]
@@ -72,7 +72,7 @@ func (*tenant) updateStatus(ctx fiber.Ctx, tenantID int64, form *dto.TenantStatu
 //	@Tags		Super
 //	@Accept		json
 //	@Produce	json
-//	@Success	200		{array}	requests.KV
+//	@Success	200	{array}	requests.KV
 //
 //	@Router		/super/v1/tenants/statuses [get]
 //	@Bind		userID path
--- a/backend/app/http/super/user.go
+++ b/backend/app/http/super/user.go
@@ -20,7 +20,7 @@ type user struct{}
 //	@Tags		Super
 //	@Accept		json
 //	@Produce	json
-//	@Param		filter	query		dto.UserPageFilter					true	"Filter"
+//	@Param		filter	query		dto.UserPageFilter	true	"Filter"
 //	@Success	200		{object}	requests.Pager{items=dto.UserItem}
 //
 //	@Router		/super/v1/users [get]
@@ -36,7 +36,7 @@ func (*user) list(ctx fiber.Ctx, filter *dto.UserPageFilter) (*requests.Pager, e
 //	@Accept		json
 //	@Produce	json
 //	@Param		userID	path	int64						true	"UserID"
-//	@Param		form		body	dto.UserStatusUpdateForm	true	"Form"
+//	@Param		form	body	dto.UserStatusUpdateForm	true	"Form"
 //
 //	@Router		/super/v1/users/:userID/status [patch]
 //	@Bind		userID path
@@ -51,7 +51,7 @@ func (*user) updateStatus(ctx fiber.Ctx, userID int64, form *dto.UserStatusUpdat
 //	@Tags		Super
 //	@Accept		json
 //	@Produce	json
-//	@Success	200		{array}	requests.KV
+//	@Success	200	{array}	requests.KV
 //
 //	@Router		/super/v1/users/statuses [get]
 //	@Bind		userID path
@@ -68,7 +68,7 @@ func (*user) statusList(ctx fiber.Ctx) ([]requests.KV, error) {
 //	@Tags		Super
 //	@Accept		json
 //	@Produce	json
-//	@Success	200		{array}	dto.UserStatistics
+//	@Success	200	{array}	dto.UserStatistics
 //
 //	@Router		/super/v1/users/statistics [get]
 //	@Bind		userID path
--- a/backend/app/http/tenant/content.go
+++ b/backend/app/http/tenant/content.go
@@ -14,7 +14,7 @@ import (

 // content provides tenant-side read-only content endpoints.
 //
-// @provider
+//	@provider
 type content struct{}

 // list
@@ -23,11 +23,11 @@ type content struct{}
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string				true	"Tenant Code"
+//	@Param		tenantCode	path		string					true	"Tenant Code"
 //	@Param		filter		query		dto.ContentListFilter	true	"Filter"
 //	@Success	200			{object}	requests.Pager{items=dto.ContentItem}
 //
-//	@Router		/t/:tenant_code/v1/contents [get]
+//	@Router		/t/:tenantCode/v1/contents [get]
 //	@Bind		tenant local key(tenant)
 //	@Bind		user local key(user)
 //	@Bind		filter query
@@ -47,11 +47,11 @@ func (*content) list(ctx fiber.Ctx, tenant *models.Tenant, user *models.User, fi
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string	true	"Tenant Code"
+//	@Param		tenantCode	path		string	true	"Tenant Code"
 //	@Param		contentID	path		int64	true	"ContentID"
 //	@Success	200			{object}	dto.ContentDetail
 //
-//	@Router		/t/:tenant_code/v1/contents/:contentID [get]
+//	@Router		/t/:tenantCode/v1/contents/:contentID [get]
 //	@Bind		tenant local key(tenant)
 //	@Bind		user local key(user)
 //	@Bind		contentID path
@@ -79,11 +79,11 @@ func (*content) show(ctx fiber.Ctx, tenant *models.Tenant, user *models.User, co
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string	true	"Tenant Code"
+//	@Param		tenantCode	path		string	true	"Tenant Code"
 //	@Param		contentID	path		int64	true	"ContentID"
 //	@Success	200			{object}	dto.ContentAssetsResponse
 //
-//	@Router		/t/:tenant_code/v1/contents/:contentID/preview [get]
+//	@Router		/t/:tenantCode/v1/contents/:contentID/preview [get]
 //	@Bind		tenant local key(tenant)
 //	@Bind		user local key(user)
 //	@Bind		contentID path
@@ -106,7 +106,7 @@ func (*content) previewAssets(ctx fiber.Ctx, tenant *models.Tenant, user *models

 	previewSeconds := int32(detail.Content.PreviewSeconds)
 	if previewSeconds <= 0 {
-		previewSeconds = 60
+		previewSeconds = consts.DefaultContentPreviewSeconds
 	}
 	return &dto.ContentAssetsResponse{
 		Content:        detail.Content,
@@ -121,11 +121,11 @@ func (*content) previewAssets(ctx fiber.Ctx, tenant *models.Tenant, user *models
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string	true	"Tenant Code"
+//	@Param		tenantCode	path		string	true	"Tenant Code"
 //	@Param		contentID	path		int64	true	"ContentID"
 //	@Success	200			{object}	dto.ContentAssetsResponse
 //
-//	@Router		/t/:tenant_code/v1/contents/:contentID/assets [get]
+//	@Router		/t/:tenantCode/v1/contents/:contentID/assets [get]
 //	@Bind		tenant local key(tenant)
 //	@Bind		user local key(user)
 //	@Bind		contentID path
--- a/backend/app/http/tenant/content_admin.go
+++ b/backend/app/http/tenant/content_admin.go
@@ -15,7 +15,7 @@ import (

 // contentAdmin provides tenant-admin content management endpoints.
 //
-// @provider
+//	@provider
 type contentAdmin struct{}

 func requireTenantAdmin(tenantUser *models.TenantUser) error {
@@ -34,11 +34,11 @@ func requireTenantAdmin(tenantUser *models.TenantUser) error {
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string				true	"Tenant Code"
+//	@Param		tenantCode	path		string					true	"Tenant Code"
 //	@Param		form		body		dto.ContentCreateForm	true	"Form"
 //	@Success	200			{object}	models.Content
 //
-//	@Router		/t/:tenant_code/v1/admin/contents [post]
+//	@Router		/t/:tenantCode/v1/admin/contents [post]
 //	@Bind		tenant local key(tenant)
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		form body
@@ -61,12 +61,12 @@ func (*contentAdmin) create(ctx fiber.Ctx, tenant *models.Tenant, tenantUser *mo
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string				true	"Tenant Code"
-//	@Param		contentID	path		int64				true	"ContentID"
+//	@Param		tenantCode	path		string					true	"Tenant Code"
+//	@Param		contentID	path		int64					true	"ContentID"
 //	@Param		form		body		dto.ContentUpdateForm	true	"Form"
 //	@Success	200			{object}	models.Content
 //
-//	@Router		/t/:tenant_code/v1/admin/contents/:contentID [patch]
+//	@Router		/t/:tenantCode/v1/admin/contents/:contentID [patch]
 //	@Bind		tenant local key(tenant)
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		contentID path
@@ -91,12 +91,12 @@ func (*contentAdmin) update(ctx fiber.Ctx, tenant *models.Tenant, tenantUser *mo
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string					true	"Tenant Code"
-//	@Param		contentID	path		int64					true	"ContentID"
+//	@Param		tenantCode	path		string						true	"Tenant Code"
+//	@Param		contentID	path		int64						true	"ContentID"
 //	@Param		form		body		dto.ContentPriceUpsertForm	true	"Form"
 //	@Success	200			{object}	models.ContentPrice
 //
-//	@Router		/t/:tenant_code/v1/admin/contents/:contentID/price [put]
+//	@Router		/t/:tenantCode/v1/admin/contents/:contentID/price [put]
 //	@Bind		tenant local key(tenant)
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		contentID path
@@ -121,12 +121,12 @@ func (*contentAdmin) upsertPrice(ctx fiber.Ctx, tenant *models.Tenant, tenantUse
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string					true	"Tenant Code"
-//	@Param		contentID	path		int64					true	"ContentID"
+//	@Param		tenantCode	path		string						true	"Tenant Code"
+//	@Param		contentID	path		int64						true	"ContentID"
 //	@Param		form		body		dto.ContentAssetAttachForm	true	"Form"
 //	@Success	200			{object}	models.ContentAsset
 //
-//	@Router		/t/:tenant_code/v1/admin/contents/:contentID/assets [post]
+//	@Router		/t/:tenantCode/v1/admin/contents/:contentID/assets [post]
 //	@Bind		tenant local key(tenant)
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		contentID path
--- a/backend/app/http/tenant/dto/content.go
+++ b/backend/app/http/tenant/dto/content.go
@@ -5,6 +5,7 @@ import (
 	"quyun/v2/database/models"
 )

+// ContentListFilter defines list query filters for published contents within a tenant.
 type ContentListFilter struct {
 	// Pagination controls paging parameters (page/limit).
 	requests.Pagination `json:",inline" query:",inline"`
--- a/backend/app/http/tenant/dto/content_admin.go
+++ b/backend/app/http/tenant/dto/content_admin.go
@@ -6,6 +6,7 @@ import (
 	"quyun/v2/pkg/consts"
 )

+// ContentCreateForm defines payload for tenant-admin to create a new content draft.
 type ContentCreateForm struct {
 	// Title is the content title.
 	Title string `json:"title,omitempty"`
--- a/backend/app/http/tenant/dto/me.go
+++ b/backend/app/http/tenant/dto/me.go
@@ -4,7 +4,7 @@ import "quyun/v2/database/models"

 // MeResponse returns the resolved tenant context for the current request.
 type MeResponse struct {
-	// Tenant is the resolved tenant by `tenant_code`.
+	// Tenant is the resolved tenant by `tenantCode`.
 	Tenant *models.Tenant `json:"tenant,omitempty"`
 	// User is the authenticated user derived from JWT `user_id`.
 	User *models.User `json:"user,omitempty"`
--- a/backend/app/http/tenant/me.go
+++ b/backend/app/http/tenant/me.go
@@ -9,7 +9,7 @@ import (

 // me provides tenant context introspection endpoints (current tenant/user/tenant_user).
 //
-// @provider
+//	@provider
 type me struct{}

 // get
@@ -18,10 +18,10 @@ type me struct{}
 //	@Tags		Tenant
 //	@Accept		json
 //	@Produce	json
-//	@Param		tenant_code	path		string	true	"Tenant Code"
+//	@Param		tenantCode	path		string	true	"Tenant Code"
 //	@Success	200			{object}	dto.MeResponse
 //
-//	@Router		/t/:tenant_code/v1/me [get]
+//	@Router		/t/:tenantCode/v1/me [get]
 //	@Bind		tenant local key(tenant)
 //	@Bind		user local key(user)
 //	@Bind		tenantUser local key(tenant_user)
--- a/backend/app/http/tenant/routes.gen.go
+++ b/backend/app/http/tenant/routes.gen.go
@@ -19,7 +19,7 @@ import (
 // Routes implements the HttpRoute contract and provides route registration
 // for all controllers in the tenant module.
 //
-// @provider contracts.HttpRoute atom.GroupRoutes
+//	@provider	contracts.HttpRoute atom.GroupRoutes
 type Routes struct {
 	log         *log.Entry `inject:"false"`
 	middlewares *middlewares.Middlewares
@@ -45,60 +45,60 @@ func (r *Routes) Name() string {
 // Each route is registered with its corresponding controller action and parameter bindings.
 func (r *Routes) Register(router fiber.Router) {
 	// Register routes for controller: content
-	r.log.Debugf("Registering route: Get /t/:tenant_code/v1/contents -> content.list")
-	router.Get("/t/:tenant_code/v1/contents"[len(r.Path()):], DataFunc3(
+	r.log.Debugf("Registering route: Get /t/:tenantCode/v1/contents -> content.list")
+	router.Get("/t/:tenantCode/v1/contents"[len(r.Path()):], DataFunc3(
 		r.content.list,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.User]("user"),
 		Query[dto.ContentListFilter]("filter"),
 	))
-	r.log.Debugf("Registering route: Get /t/:tenant_code/v1/contents/:contentID -> content.show")
-	router.Get("/t/:tenant_code/v1/contents/:contentID"[len(r.Path()):], DataFunc3(
+	r.log.Debugf("Registering route: Get /t/:tenantCode/v1/contents/:contentID -> content.show")
+	router.Get("/t/:tenantCode/v1/contents/:contentID"[len(r.Path()):], DataFunc3(
 		r.content.show,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.User]("user"),
 		PathParam[int64]("contentID"),
 	))
-	r.log.Debugf("Registering route: Get /t/:tenant_code/v1/contents/:contentID/assets -> content.mainAssets")
-	router.Get("/t/:tenant_code/v1/contents/:contentID/assets"[len(r.Path()):], DataFunc3(
+	r.log.Debugf("Registering route: Get /t/:tenantCode/v1/contents/:contentID/assets -> content.mainAssets")
+	router.Get("/t/:tenantCode/v1/contents/:contentID/assets"[len(r.Path()):], DataFunc3(
 		r.content.mainAssets,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.User]("user"),
 		PathParam[int64]("contentID"),
 	))
-	r.log.Debugf("Registering route: Get /t/:tenant_code/v1/contents/:contentID/preview -> content.previewAssets")
-	router.Get("/t/:tenant_code/v1/contents/:contentID/preview"[len(r.Path()):], DataFunc3(
+	r.log.Debugf("Registering route: Get /t/:tenantCode/v1/contents/:contentID/preview -> content.previewAssets")
+	router.Get("/t/:tenantCode/v1/contents/:contentID/preview"[len(r.Path()):], DataFunc3(
 		r.content.previewAssets,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.User]("user"),
 		PathParam[int64]("contentID"),
 	))
 	// Register routes for controller: contentAdmin
-	r.log.Debugf("Registering route: Patch /t/:tenant_code/v1/admin/contents/:contentID -> contentAdmin.update")
-	router.Patch("/t/:tenant_code/v1/admin/contents/:contentID"[len(r.Path()):], DataFunc4(
+	r.log.Debugf("Registering route: Patch /t/:tenantCode/v1/admin/contents/:contentID -> contentAdmin.update")
+	router.Patch("/t/:tenantCode/v1/admin/contents/:contentID"[len(r.Path()):], DataFunc4(
 		r.contentAdmin.update,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.TenantUser]("tenant_user"),
 		PathParam[int64]("contentID"),
 		Body[dto.ContentUpdateForm]("form"),
 	))
-	r.log.Debugf("Registering route: Post /t/:tenant_code/v1/admin/contents -> contentAdmin.create")
-	router.Post("/t/:tenant_code/v1/admin/contents"[len(r.Path()):], DataFunc3(
+	r.log.Debugf("Registering route: Post /t/:tenantCode/v1/admin/contents -> contentAdmin.create")
+	router.Post("/t/:tenantCode/v1/admin/contents"[len(r.Path()):], DataFunc3(
 		r.contentAdmin.create,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.TenantUser]("tenant_user"),
 		Body[dto.ContentCreateForm]("form"),
 	))
-	r.log.Debugf("Registering route: Post /t/:tenant_code/v1/admin/contents/:contentID/assets -> contentAdmin.attachAsset")
-	router.Post("/t/:tenant_code/v1/admin/contents/:contentID/assets"[len(r.Path()):], DataFunc4(
+	r.log.Debugf("Registering route: Post /t/:tenantCode/v1/admin/contents/:contentID/assets -> contentAdmin.attachAsset")
+	router.Post("/t/:tenantCode/v1/admin/contents/:contentID/assets"[len(r.Path()):], DataFunc4(
 		r.contentAdmin.attachAsset,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.TenantUser]("tenant_user"),
 		PathParam[int64]("contentID"),
 		Body[dto.ContentAssetAttachForm]("form"),
 	))
-	r.log.Debugf("Registering route: Put /t/:tenant_code/v1/admin/contents/:contentID/price -> contentAdmin.upsertPrice")
-	router.Put("/t/:tenant_code/v1/admin/contents/:contentID/price"[len(r.Path()):], DataFunc4(
+	r.log.Debugf("Registering route: Put /t/:tenantCode/v1/admin/contents/:contentID/price -> contentAdmin.upsertPrice")
+	router.Put("/t/:tenantCode/v1/admin/contents/:contentID/price"[len(r.Path()):], DataFunc4(
 		r.contentAdmin.upsertPrice,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.TenantUser]("tenant_user"),
@@ -106,8 +106,8 @@ func (r *Routes) Register(router fiber.Router) {
 		Body[dto.ContentPriceUpsertForm]("form"),
 	))
 	// Register routes for controller: me
-	r.log.Debugf("Registering route: Get /t/:tenant_code/v1/me -> me.get")
-	router.Get("/t/:tenant_code/v1/me"[len(r.Path()):], DataFunc3(
+	r.log.Debugf("Registering route: Get /t/:tenantCode/v1/me -> me.get")
+	router.Get("/t/:tenantCode/v1/me"[len(r.Path()):], DataFunc3(
 		r.me.get,
 		Local[*models.Tenant]("tenant"),
 		Local[*models.User]("user"),
--- a/backend/app/http/tenant/routes.manual.go
+++ b/backend/app/http/tenant/routes.manual.go
@@ -1,12 +1,11 @@
 package tenant

 func (r *Routes) Path() string {
-	return "/t/:tenant_code/v1"
+	return "/t/:tenantCode/v1"
 }

 func (r *Routes) Middlewares() []any {
 	return []any{
-		r.middlewares.DebugMode,
 		r.middlewares.TenantResolve,
 		r.middlewares.TenantAuth,
 		r.middlewares.TenantRequireMember,
--- a/backend/app/middlewares/tenant.go
+++ b/backend/app/middlewares/tenant.go
@@ -1,7 +1,6 @@
 package middlewares

 import (
-	"go.ipao.vip/atom/container"
 	"quyun/v2/app/errorx"
 	"quyun/v2/app/services"
 	"quyun/v2/database/models"
@@ -12,9 +11,9 @@ import (
 )

 func (f *Middlewares) TenantResolve(c fiber.Ctx) error {
-	tenantCode := c.Params("tenant_code")
+	tenantCode := c.Params("tenantCode")
 	if tenantCode == "" {
-		return errorx.ErrMissingParameter.WithMsg("缺少 tenant_code")
+		return errorx.ErrMissingParameter.WithMsg("缺少 tenantCode")
 	}

 	tenantModel, err := services.Tenant.FindByCode(c, tenantCode)
@@ -39,18 +38,7 @@ func (f *Middlewares) TenantAuth(c fiber.Ctx) error {
 		return errorx.ErrTokenMissing
 	}

-	jwtProvider := f.jwt
-	if jwtProvider == nil {
-		if err := container.Container.Invoke(func(j *jwt.JWT) {
-			jwtProvider = j
-			f.jwt = j
-		}); err != nil {
-			f.log.WithError(err).Error("middlewares.tenant.auth.jwt_provider_missing")
-			return errorx.ErrInternalError.WithMsg("jwt provider missing")
-		}
-	}
-
-	claims, err := jwtProvider.Parse(authHeader)
+	claims, err := f.jwt.Parse(authHeader)
 	if err != nil {
 		f.log.WithError(err).Warn("middlewares.tenant.auth.invalid_token")
 		switch err {
--- a/backend/app/requests/label.go
+++ b/backend/app/requests/label.go
@@ -1,8 +1,11 @@
 package requests

+// KV is a generic key-value response item, commonly used for label/value enums.
 type KV struct {
-	Key   string `json:"key,omitempty"`
-	Value any    `json:"value,omitempty"`
+	// Key is a machine-readable value, usually an enum string.
+	Key string `json:"key,omitempty"`
+	// Value is the label payload, often a human-readable string.
+	Value any `json:"value,omitempty"`
 }

 func NewKV(k string, v any) KV {
--- a/backend/app/requests/pagination.go
+++ b/backend/app/requests/pagination.go
@@ -2,14 +2,21 @@ package requests

 import "github.com/samber/lo"

+// Pager is a common paginated API response envelope.
 type Pager struct {
+	// Pagination contains paging inputs (page/limit) echoed back in the response.
 	Pagination `      json:",inline"`
-	Total      int64 `json:"total"`
-	Items      any   `json:"items"`
+	// Total is the total number of items matching current filter (before paging).
+	Total int64 `json:"total"`
+	// Items is the paged result list; concrete type depends on endpoint.
+	Items any `json:"items"`
 }

+// Pagination defines common paging query parameters used by list endpoints.
 type Pagination struct {
-	Page  int64 `json:"page"  form:"page"  query:"page"`
+	// Page is 1-based page index; values <= 0 are normalized to 1.
+	Page int64 `json:"page"  form:"page"  query:"page"`
+	// Limit is page size; only values in {10,20,50,100} are accepted (otherwise defaults to 10).
 	Limit int64 `json:"limit" form:"limit" query:"limit"`
 }

--- a/backend/app/requests/sort.go
+++ b/backend/app/requests/sort.go
@@ -6,8 +6,11 @@ import (
 	"github.com/samber/lo"
 )

+// SortQueryFilter defines common query sorting parameters used by list endpoints.
 type SortQueryFilter struct {
-	Asc  *string `json:"asc" form:"asc"`
+	// Asc specifies comma-separated field names to sort ascending by.
+	Asc *string `json:"asc" form:"asc"`
+	// Desc specifies comma-separated field names to sort descending by.
 	Desc *string `json:"desc" form:"desc"`
 }

--- a/backend/app/services/content.go
+++ b/backend/app/services/content.go
@@ -26,9 +26,9 @@ type content struct{}
 // ContentDetailResult is the internal detail result used by controllers.
 type ContentDetailResult struct {
 	// Content is the content entity.
-	Content   *models.Content
+	Content *models.Content
 	// Price is the price settings (may be nil).
-	Price     *models.ContentPrice
+	Price *models.ContentPrice
 	// HasAccess indicates whether the user can access main assets.
 	HasAccess bool
 }
@@ -44,7 +44,7 @@ func (s *content) Create(ctx context.Context, tenantID, userID int64, form *dto.
 		visibility = consts.ContentVisibilityTenantOnly
 	}

-	previewSeconds := int32(60)
+	previewSeconds := consts.DefaultContentPreviewSeconds
 	if form.PreviewSeconds != nil && *form.PreviewSeconds > 0 {
 		previewSeconds = *form.PreviewSeconds
 	}
--- a/backend/database/migrations/20251217223000_media_contents.sql
+++ b/backend/database/migrations/20251217223000_media_contents.sql
@@ -15,6 +15,21 @@ CREATE TABLE IF NOT EXISTS media_assets(
    updated_at timestamptz NOT NULL DEFAULT NOW()
 );

+-- media_assets：媒体资源表（视频/音频/图片），用于承载实际文件对象及其处理状态
+COMMENT ON TABLE media_assets IS '媒体资源：存储对象的抽象（video/audio/image），关联租户与上传用户，记录处理状态与元数据';
+COMMENT ON COLUMN media_assets.id IS '主键ID：自增；仅用于内部关联';
+COMMENT ON COLUMN media_assets.tenant_id IS '租户ID：多租户隔离关键字段；所有查询/写入必须限定 tenant_id';
+COMMENT ON COLUMN media_assets.user_id IS '用户ID：资源上传者；用于审计与权限控制';
+COMMENT ON COLUMN media_assets.type IS '资源类型：video/audio/image；决定后续处理流程（转码/缩略图/封面等）';
+COMMENT ON COLUMN media_assets.status IS '处理状态：uploaded/processing/ready/failed/deleted；ready 才可被内容引用对外提供';
+COMMENT ON COLUMN media_assets.provider IS '存储提供方：例如 s3/minio/oss；便于多存储扩展';
+COMMENT ON COLUMN media_assets.bucket IS '存储桶：对象所在 bucket；与 provider 组合确定存储定位';
+COMMENT ON COLUMN media_assets.object_key IS '对象键：对象在 bucket 内的 key；不得暴露可长期复用的直链（通过签名URL/token下发）';
+COMMENT ON COLUMN media_assets.meta IS '元数据：JSON；包含 hash、duration、width、height、bitrate、codec 等；用于展示与计费/风控';
+COMMENT ON COLUMN media_assets.deleted_at IS '软删除时间：非空表示已删除；对外接口需过滤';
+COMMENT ON COLUMN media_assets.created_at IS '创建时间：默认 now()；用于审计与排序';
+COMMENT ON COLUMN media_assets.updated_at IS '更新时间：默认 now()；更新状态/元数据时写入';
+
 CREATE INDEX IF NOT EXISTS ix_media_assets_tenant_id ON media_assets(tenant_id);
 CREATE INDEX IF NOT EXISTS ix_media_assets_tenant_user_id ON media_assets(tenant_id, user_id);
 CREATE INDEX IF NOT EXISTS ix_media_assets_tenant_status ON media_assets(tenant_id, status);
@@ -35,6 +50,22 @@ CREATE TABLE IF NOT EXISTS contents(
    updated_at timestamptz NOT NULL DEFAULT NOW()
 );

+-- contents：内容表（可发布/可售卖/可试看）
+COMMENT ON TABLE contents IS '内容：可发布的媒体内容实体，承载标题描述、可见性、试看配置、发布状态等';
+COMMENT ON COLUMN contents.id IS '主键ID：自增；用于内容引用';
+COMMENT ON COLUMN contents.tenant_id IS '租户ID：多租户隔离关键字段；所有查询/写入必须限定 tenant_id';
+COMMENT ON COLUMN contents.user_id IS '用户ID：内容创建者/发布者；用于权限与审计（例如私有内容仅作者可见）';
+COMMENT ON COLUMN contents.title IS '标题：用于列表展示与搜索；建议限制长度（由业务校验）';
+COMMENT ON COLUMN contents.description IS '描述：用于详情页展示；可为空字符串';
+COMMENT ON COLUMN contents.status IS '状态：draft/reviewing/published/unpublished/blocked；published 才对外展示';
+COMMENT ON COLUMN contents.visibility IS '可见性：public/tenant_only/private；仅控制详情可见，正片资源仍需按价格/权益校验';
+COMMENT ON COLUMN contents.preview_seconds IS '试看秒数：默认 60；只对 preview 资源生效；必须为正整数';
+COMMENT ON COLUMN contents.preview_downloadable IS '试看是否允许下载：默认 false；当前策略固定为不允许下载（仅 streaming）';
+COMMENT ON COLUMN contents.published_at IS '发布时间：首次发布时写入；用于时间窗与排序';
+COMMENT ON COLUMN contents.deleted_at IS '软删除时间：非空表示已删除；对外接口需过滤';
+COMMENT ON COLUMN contents.created_at IS '创建时间：默认 now()；用于审计与排序';
+COMMENT ON COLUMN contents.updated_at IS '更新时间：默认 now()；编辑内容时写入';
+
 CREATE INDEX IF NOT EXISTS ix_contents_tenant_id ON contents(tenant_id);
 CREATE INDEX IF NOT EXISTS ix_contents_tenant_user_id ON contents(tenant_id, user_id);
 CREATE INDEX IF NOT EXISTS ix_contents_tenant_status ON contents(tenant_id, status);
@@ -53,6 +84,18 @@ CREATE TABLE IF NOT EXISTS content_assets(
    UNIQUE (tenant_id, content_id, asset_id)
 );

+-- content_assets：内容与媒体资源的关联（区分 main/cover/preview）
+COMMENT ON TABLE content_assets IS '内容-资源关联：将 media_assets 以角色（main/cover/preview）绑定到 contents，支持排序';
+COMMENT ON COLUMN content_assets.id IS '主键ID：自增';
+COMMENT ON COLUMN content_assets.tenant_id IS '租户ID：多租户隔离；必须与 content_id、asset_id 所属租户一致';
+COMMENT ON COLUMN content_assets.user_id IS '用户ID：操作人/绑定人；用于审计（通常为租户管理员或作者）';
+COMMENT ON COLUMN content_assets.content_id IS '内容ID：关联 contents.id；用于查询内容下资源列表';
+COMMENT ON COLUMN content_assets.asset_id IS '资源ID：关联 media_assets.id；用于查询资源归属内容';
+COMMENT ON COLUMN content_assets.role IS '资源角色：main/cover/preview；preview 必须为独立资源以满足禁下载与防绕过';
+COMMENT ON COLUMN content_assets.sort IS '排序：同一 role 下的展示顺序，数值越小越靠前';
+COMMENT ON COLUMN content_assets.created_at IS '创建时间：默认 now()；用于审计';
+COMMENT ON COLUMN content_assets.updated_at IS '更新时间：默认 now()；更新 sort/role 时写入';
+
 CREATE INDEX IF NOT EXISTS ix_content_assets_tenant_content ON content_assets(tenant_id, content_id);
 CREATE INDEX IF NOT EXISTS ix_content_assets_tenant_asset ON content_assets(tenant_id, asset_id);
 CREATE INDEX IF NOT EXISTS ix_content_assets_tenant_role ON content_assets(tenant_id, content_id, role);
@@ -73,6 +116,21 @@ CREATE TABLE IF NOT EXISTS content_prices(
    UNIQUE (tenant_id, content_id)
 );

+-- content_prices：内容定价与折扣（仅 CNY 分）
+COMMENT ON TABLE content_prices IS '内容定价：为内容设置价格与折扣（订单需记录成交快照，避免改价影响历史）';
+COMMENT ON COLUMN content_prices.id IS '主键ID：自增';
+COMMENT ON COLUMN content_prices.tenant_id IS '租户ID：多租户隔离；与内容归属一致';
+COMMENT ON COLUMN content_prices.user_id IS '用户ID：设置/更新价格的操作人（通常为 tenant_admin）；用于审计';
+COMMENT ON COLUMN content_prices.content_id IS '内容ID：唯一约束 (tenant_id, content_id)；一个内容在一个租户内仅一份定价';
+COMMENT ON COLUMN content_prices.currency IS '币种：当前固定 CNY；金额单位为分';
+COMMENT ON COLUMN content_prices.price_amount IS '基础价格：分；0 表示免费（可直接访问正片资源）';
+COMMENT ON COLUMN content_prices.discount_type IS '折扣类型：none/percent/amount；仅影响下单时成交价，需写入订单快照';
+COMMENT ON COLUMN content_prices.discount_value IS '折扣值：percent=0-100（按业务校验）；amount=分；none 时忽略';
+COMMENT ON COLUMN content_prices.discount_start_at IS '折扣开始时间：可为空；为空表示立即生效（由业务逻辑解释）';
+COMMENT ON COLUMN content_prices.discount_end_at IS '折扣结束时间：可为空；为空表示长期有效（由业务逻辑解释）';
+COMMENT ON COLUMN content_prices.created_at IS '创建时间：默认 now()；用于审计';
+COMMENT ON COLUMN content_prices.updated_at IS '更新时间：默认 now()；更新价格/折扣时写入';
+
 CREATE INDEX IF NOT EXISTS ix_content_prices_tenant_id ON content_prices(tenant_id);

 CREATE TABLE IF NOT EXISTS content_access(
@@ -88,6 +146,18 @@ CREATE TABLE IF NOT EXISTS content_access(
    UNIQUE (tenant_id, user_id, content_id)
 );

+-- content_access：购买权益/访问权限（退款后撤销）
+COMMENT ON TABLE content_access IS '内容权益：记录用户在租户内对内容的访问资格；退款后应立即 revoked';
+COMMENT ON COLUMN content_access.id IS '主键ID：自增';
+COMMENT ON COLUMN content_access.tenant_id IS '租户ID：多租户隔离；与内容、用户归属一致';
+COMMENT ON COLUMN content_access.user_id IS '用户ID：权益所属用户；用于访问校验';
+COMMENT ON COLUMN content_access.content_id IS '内容ID：权益对应内容；唯一约束 (tenant_id, user_id, content_id)';
+COMMENT ON COLUMN content_access.order_id IS '订单ID：产生该权益的订单；可为空（例如后台补发/迁移）';
+COMMENT ON COLUMN content_access.status IS '权益状态：active/revoked/expired；revoked 表示立即失效（例如退款/违规）';
+COMMENT ON COLUMN content_access.revoked_at IS '撤销时间：当 status=revoked 时写入；用于审计与追责';
+COMMENT ON COLUMN content_access.created_at IS '创建时间：默认 now()；用于审计';
+COMMENT ON COLUMN content_access.updated_at IS '更新时间：默认 now()；更新 status 时写入';
+
 CREATE INDEX IF NOT EXISTS ix_content_access_tenant_user ON content_access(tenant_id, user_id);
 CREATE INDEX IF NOT EXISTS ix_content_access_tenant_content ON content_access(tenant_id, content_id);

@@ -118,4 +188,3 @@ DROP INDEX IF EXISTS ix_media_assets_tenant_id;
 DROP TABLE IF EXISTS media_assets;

 -- +goose StatementEnd
-
--- a/backend/docs/docs.go
+++ b/backend/docs/docs.go
--- a/backend/docs/swagger.json
+++ b/backend/docs/swagger.json
--- a/backend/docs/swagger.yaml
+++ b/backend/docs/swagger.yaml
@@ -1,5 +1,79 @@
-basePath: /t/{tenant_code}/v1
+basePath: /t/{tenantCode}/v1
 definitions:
+  consts.ContentAssetRole:
+    enum:
+    - main
+    - cover
+    - preview
+    type: string
+    x-enum-varnames:
+    - ContentAssetRoleMain
+    - ContentAssetRoleCover
+    - ContentAssetRolePreview
+  consts.ContentStatus:
+    enum:
+    - draft
+    - reviewing
+    - published
+    - unpublished
+    - blocked
+    type: string
+    x-enum-varnames:
+    - ContentStatusDraft
+    - ContentStatusReviewing
+    - ContentStatusPublished
+    - ContentStatusUnpublished
+    - ContentStatusBlocked
+  consts.ContentVisibility:
+    enum:
+    - public
+    - tenant_only
+    - private
+    type: string
+    x-enum-varnames:
+    - ContentVisibilityPublic
+    - ContentVisibilityTenantOnly
+    - ContentVisibilityPrivate
+  consts.Currency:
+    enum:
+    - CNY
+    type: string
+    x-enum-varnames:
+    - CurrencyCNY
+  consts.DiscountType:
+    enum:
+    - none
+    - percent
+    - amount
+    type: string
+    x-enum-varnames:
+    - DiscountTypeNone
+    - DiscountTypePercent
+    - DiscountTypeAmount
+  consts.MediaAssetStatus:
+    enum:
+    - uploaded
+    - processing
+    - ready
+    - failed
+    - deleted
+    type: string
+    x-enum-varnames:
+    - MediaAssetStatusUploaded
+    - MediaAssetStatusProcessing
+    - MediaAssetStatusReady
+    - MediaAssetStatusFailed
+    - MediaAssetStatusDeleted
+  consts.MediaAssetType:
+    enum:
+    - video
+    - audio
+    - image
+    type: string
+    x-enum-varnames:
+    - MediaAssetTypeVideo
+    - MediaAssetTypeAudio
+    - MediaAssetTypeImage
  consts.Role:
    enum:
    - user
@@ -18,6 +92,14 @@ definitions:
    - TenantStatusPendingVerify
    - TenantStatusVerified
    - TenantStatusBanned
+  consts.TenantUserRole:
+    enum:
+    - member
+    - tenant_admin
+    type: string
+    x-enum-varnames:
+    - TenantUserRoleMember
+    - TenantUserRoleTenantAdmin
  consts.UserStatus:
    enum:
    - pending_verify
@@ -28,6 +110,129 @@ definitions:
    - UserStatusPendingVerify
    - UserStatusVerified
    - UserStatusBanned
+  dto.ContentAssetAttachForm:
+    properties:
+      asset_id:
+        description: AssetID is the media asset id to attach.
+        type: integer
+      role:
+        allOf:
+        - $ref: '#/definitions/consts.ContentAssetRole'
+        description: Role indicates how this asset is used (main/cover/preview).
+      sort:
+        description: Sort controls ordering under the same role.
+        type: integer
+    type: object
+  dto.ContentAssetsResponse:
+    properties:
+      assets:
+        description: Assets is the list of media assets for the requested role (preview/main).
+        items:
+          $ref: '#/definitions/models.MediaAsset'
+        type: array
+      content:
+        allOf:
+        - $ref: '#/definitions/models.Content'
+        description: Content is the content entity.
+      preview_seconds:
+        description: PreviewSeconds indicates the max preview duration (only meaningful
+          for preview response).
+        type: integer
+    type: object
+  dto.ContentCreateForm:
+    properties:
+      description:
+        description: Description is the content description.
+        type: string
+      preview_seconds:
+        description: PreviewSeconds controls preview duration (defaults to 60 when
+          omitted).
+        type: integer
+      title:
+        description: Title is the content title.
+        type: string
+      visibility:
+        allOf:
+        - $ref: '#/definitions/consts.ContentVisibility'
+        description: Visibility controls who can view the content detail (main assets
+          still require free/purchase).
+    type: object
+  dto.ContentDetail:
+    properties:
+      content:
+        allOf:
+        - $ref: '#/definitions/models.Content'
+        description: Content is the content entity.
+      has_access:
+        description: HasAccess indicates whether current user can access main assets
+          (free/owner/purchased).
+        type: boolean
+      price:
+        allOf:
+        - $ref: '#/definitions/models.ContentPrice'
+        description: Price is the current price settings for the content (may be nil
+          if not set).
+    type: object
+  dto.ContentItem:
+    properties:
+      content:
+        allOf:
+        - $ref: '#/definitions/models.Content'
+        description: Content is the content entity.
+      has_access:
+        description: HasAccess indicates whether current user can access main assets
+          (free/owner/purchased).
+        type: boolean
+      price:
+        allOf:
+        - $ref: '#/definitions/models.ContentPrice'
+        description: Price is the current price settings for the content (may be nil
+          if not set).
+    type: object
+  dto.ContentPriceUpsertForm:
+    properties:
+      currency:
+        allOf:
+        - $ref: '#/definitions/consts.Currency'
+        description: Currency is fixed to CNY for now.
+      discount_end_at:
+        description: DiscountEndAt disables discount after this time (optional).
+        type: string
+      discount_start_at:
+        description: DiscountStartAt enables discount from this time (optional).
+        type: string
+      discount_type:
+        allOf:
+        - $ref: '#/definitions/consts.DiscountType'
+        description: DiscountType defines the discount algorithm (none/percent/amount).
+      discount_value:
+        description: DiscountValue is interpreted based on DiscountType.
+        type: integer
+      price_amount:
+        description: PriceAmount is the base price in cents (CNY 分).
+        type: integer
+    type: object
+  dto.ContentUpdateForm:
+    properties:
+      description:
+        description: Description updates the description when provided.
+        type: string
+      preview_seconds:
+        description: PreviewSeconds updates preview duration when provided (must be
+          > 0).
+        type: integer
+      status:
+        allOf:
+        - $ref: '#/definitions/consts.ContentStatus'
+        description: Status updates the content status when provided (e.g. publish/unpublish).
+      title:
+        description: Title updates the title when provided.
+        type: string
+      visibility:
+        allOf:
+        - $ref: '#/definitions/consts.ContentVisibility'
+        description: Visibility updates the visibility when provided.
+    type: object
  dto.LoginForm:
    properties:
      password:
@@ -40,6 +245,22 @@ definitions:
      token:
        type: string
    type: object
+  dto.MeResponse:
+    properties:
+      tenant:
+        allOf:
+        - $ref: '#/definitions/models.Tenant'
+        description: Tenant is the resolved tenant by `tenantCode`.
+      tenant_user:
+        allOf:
+        - $ref: '#/definitions/models.TenantUser'
+        description: TenantUser is the membership record of the authenticated user
+          within the tenant.
+      user:
+        allOf:
+        - $ref: '#/definitions/models.User'
+        description: User is the authenticated user derived from JWT `user_id`.
+    type: object
  dto.TenantExpireUpdateForm:
    properties:
      duration:
@@ -162,6 +383,112 @@ definitions:
        description: Valid is true if Time is not NULL
        type: boolean
    type: object
+  models.Content:
+    properties:
+      created_at:
+        type: string
+      deleted_at:
+        $ref: '#/definitions/gorm.DeletedAt'
+      description:
+        type: string
+      id:
+        type: integer
+      preview_downloadable:
+        type: boolean
+      preview_seconds:
+        type: integer
+      published_at:
+        type: string
+      status:
+        $ref: '#/definitions/consts.ContentStatus'
+      tenant_id:
+        type: integer
+      title:
+        type: string
+      updated_at:
+        type: string
+      user_id:
+        type: integer
+      visibility:
+        $ref: '#/definitions/consts.ContentVisibility'
+    type: object
+  models.ContentAsset:
+    properties:
+      asset_id:
+        type: integer
+      content_id:
+        type: integer
+      created_at:
+        type: string
+      id:
+        type: integer
+      role:
+        $ref: '#/definitions/consts.ContentAssetRole'
+      sort:
+        type: integer
+      tenant_id:
+        type: integer
+      updated_at:
+        type: string
+      user_id:
+        type: integer
+    type: object
+  models.ContentPrice:
+    properties:
+      content_id:
+        type: integer
+      created_at:
+        type: string
+      currency:
+        $ref: '#/definitions/consts.Currency'
+      discount_end_at:
+        type: string
+      discount_start_at:
+        type: string
+      discount_type:
+        $ref: '#/definitions/consts.DiscountType'
+      discount_value:
+        type: integer
+      id:
+        type: integer
+      price_amount:
+        type: integer
+      tenant_id:
+        type: integer
+      updated_at:
+        type: string
+      user_id:
+        type: integer
+    type: object
+  models.MediaAsset:
+    properties:
+      bucket:
+        type: string
+      created_at:
+        type: string
+      deleted_at:
+        $ref: '#/definitions/gorm.DeletedAt'
+      id:
+        type: integer
+      meta:
+        items:
+          type: integer
+        type: array
+      object_key:
+        type: string
+      provider:
+        type: string
+      status:
+        $ref: '#/definitions/consts.MediaAssetStatus'
+      tenant_id:
+        type: integer
+      type:
+        $ref: '#/definitions/consts.MediaAssetType'
+      updated_at:
+        type: string
+      user_id:
+        type: integer
+    type: object
  models.Tenant:
    properties:
      code:
@@ -191,6 +518,27 @@ definitions:
      uuid:
        type: string
    type: object
+  models.TenantUser:
+    properties:
+      balance:
+        type: integer
+      created_at:
+        type: string
+      id:
+        type: integer
+      role:
+        items:
+          $ref: '#/definitions/consts.TenantUserRole'
+        type: array
+      status:
+        $ref: '#/definitions/consts.UserStatus'
+      tenant_id:
+        type: integer
+      updated_at:
+        type: string
+      user_id:
+        type: integer
+    type: object
  models.User:
    properties:
      created_at:
@@ -227,17 +575,25 @@ definitions:
  requests.KV:
    properties:
      key:
+        description: Key is a machine-readable value, usually an enum string.
        type: string
-      value: {}
+      value:
+        description: Value is the label payload, often a human-readable string.
    type: object
  requests.Pager:
    properties:
-      items: {}
+      items:
+        description: Items is the paged result list; concrete type depends on endpoint.
      limit:
+        description: Limit is page size; only values in {10,20,50,100} are accepted
+          (otherwise defaults to 10).
        type: integer
      page:
+        description: Page is 1-based page index; values <= 0 are normalized to 1.
        type: integer
      total:
+        description: Total is the total number of items matching current filter (before
+          paging).
        type: integer
    type: object
 externalDocs:
@@ -249,7 +605,7 @@ info:
    email: support@swagger.io
    name: UserName
    url: http://www.swagger.io/support
-  description: This is a sample server celler server.
+  description: Multi-tenant media platform backend API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
@@ -277,29 +633,56 @@ paths:
            $ref: '#/definitions/dto.LoginResponse'
      tags:
      - Super
+  /super/v1/auth/token:
+    get:
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 成功
+          schema:
+            $ref: '#/definitions/dto.LoginResponse'
+      tags:
+      - Super
  /super/v1/tenants:
    get:
      consumes:
      - application/json
      parameters:
-      - in: query
+      - description: Asc specifies comma-separated field names to sort ascending by.
+        in: query
        name: asc
        type: string
-      - in: query
+      - description: Desc specifies comma-separated field names to sort descending
+          by.
+        in: query
        name: desc
        type: string
-      - in: query
+      - description: Limit is page size; only values in {10,20,50,100} are accepted
+          (otherwise defaults to 10).
+        in: query
        name: limit
        type: integer
      - in: query
        name: name
        type: string
-      - in: query
+      - description: Page is 1-based page index; values <= 0 are normalized to 1.
+        in: query
        name: page
        type: integer
-      - in: query
+      - enum:
+        - pending_verify
+        - verified
+        - banned
+        in: query
        name: status
        type: string
+        x-enum-varnames:
+        - TenantStatusPendingVerify
+        - TenantStatusVerified
+        - TenantStatusBanned
      produces:
      - application/json
      responses:
@@ -382,21 +765,35 @@ paths:
      consumes:
      - application/json
      parameters:
-      - in: query
+      - description: Asc specifies comma-separated field names to sort ascending by.
+        in: query
        name: asc
        type: string
-      - in: query
+      - description: Desc specifies comma-separated field names to sort descending
+          by.
+        in: query
        name: desc
        type: string
-      - in: query
+      - description: Limit is page size; only values in {10,20,50,100} are accepted
+          (otherwise defaults to 10).
+        in: query
        name: limit
        type: integer
-      - in: query
+      - description: Page is 1-based page index; values <= 0 are normalized to 1.
+        in: query
        name: page
        type: integer
-      - in: query
+      - enum:
+        - pending_verify
+        - verified
+        - banned
+        in: query
        name: status
        type: string
+        x-enum-varnames:
+        - UserStatusPendingVerify
+        - UserStatusVerified
+        - UserStatusBanned
      - in: query
        name: tenantID
        type: integer
@@ -473,6 +870,264 @@ paths:
      summary: 用户状态列表
      tags:
      - Super
+  /t/{tenantCode}/v1/admin/contents:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: Form
+        in: body
+        name: form
+        required: true
+        schema:
+          $ref: '#/definitions/dto.ContentCreateForm'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.Content'
+      summary: 创建内容（草稿）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/admin/contents/{contentID}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: ContentID
+        format: int64
+        in: path
+        name: contentID
+        required: true
+        type: integer
+      - description: Form
+        in: body
+        name: form
+        required: true
+        schema:
+          $ref: '#/definitions/dto.ContentUpdateForm'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.Content'
+      summary: 更新内容（标题/描述/状态等）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/admin/contents/{contentID}/assets:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: ContentID
+        format: int64
+        in: path
+        name: contentID
+        required: true
+        type: integer
+      - description: Form
+        in: body
+        name: form
+        required: true
+        schema:
+          $ref: '#/definitions/dto.ContentAssetAttachForm'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.ContentAsset'
+      summary: 绑定媒体资源到内容（main/cover/preview）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/admin/contents/{contentID}/price:
+    put:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: ContentID
+        format: int64
+        in: path
+        name: contentID
+        required: true
+        type: integer
+      - description: Form
+        in: body
+        name: form
+        required: true
+        schema:
+          $ref: '#/definitions/dto.ContentPriceUpsertForm'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.ContentPrice'
+      summary: 设置内容价格与折扣
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/contents:
+    get:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: Keyword filters by title keyword (LIKE).
+        in: query
+        name: keyword
+        type: string
+      - description: Limit is page size; only values in {10,20,50,100} are accepted
+          (otherwise defaults to 10).
+        in: query
+        name: limit
+        type: integer
+      - description: Page is 1-based page index; values <= 0 are normalized to 1.
+        in: query
+        name: page
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            allOf:
+            - $ref: '#/definitions/requests.Pager'
+            - properties:
+                items:
+                  $ref: '#/definitions/dto.ContentItem'
+              type: object
+      summary: 内容列表（已发布）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/contents/{contentID}:
+    get:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: ContentID
+        format: int64
+        in: path
+        name: contentID
+        required: true
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/dto.ContentDetail'
+      summary: 内容详情（可见性+权益校验）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/contents/{contentID}/assets:
+    get:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: ContentID
+        format: int64
+        in: path
+        name: contentID
+        required: true
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/dto.ContentAssetsResponse'
+      summary: 获取正片资源（main role，需要已购或免费）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/contents/{contentID}/preview:
+    get:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: ContentID
+        format: int64
+        in: path
+        name: contentID
+        required: true
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/dto.ContentAssetsResponse'
+      summary: 获取试看资源（preview role）
+      tags:
+      - Tenant
+  /t/{tenantCode}/v1/me:
+    get:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/dto.MeResponse'
+      summary: 当前租户上下文信息
+      tags:
+      - Tenant
 securityDefinitions:
  BasicAuth:
    type: basic
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -39,6 +39,8 @@ require (
 	gorm.io/plugin/dbresolver v1.6.2
 )

+replace google.golang.org/genproto/googleapis/rpc => google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1
+
 require (
 	github.com/IBM/sarama v1.46.3 // indirect
 	github.com/KyleBanks/depth v1.2.1 // indirect
@@ -128,7 +130,6 @@ require (
 	golang.org/x/text v0.32.0 // indirect
 	golang.org/x/tools v0.40.0 // indirect
 	google.golang.org/appengine v1.6.8 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20251124214823-79d6a2a48846 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	gorm.io/hints v1.1.0 // indirect
 )
--- a/backend/main.go
+++ b/backend/main.go
@@ -11,7 +11,7 @@ import (

 // @title           ApiDoc
 // @version         1.0
-// @description     This is a sample server celler server.
+// @description     Multi-tenant media platform backend API.
 // @termsOfService  http://swagger.io/terms/
 // @contact.name   UserName
 // @contact.url    http://www.swagger.io/support
@@ -19,7 +19,7 @@ import (
 // @license.name  Apache 2.0
 // @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
 // @host      localhost:8080
-// @BasePath  /t/{tenant_code}/v1
+// @BasePath  /
 // @securityDefinitions.basic  BasicAuth
 // @externalDocs.description  OpenAPI
 // @externalDocs.url          https://swagger.io/resources/open-api/
--- a/backend/pkg/consts/consts.go
+++ b/backend/pkg/consts/consts.go
@@ -77,6 +77,12 @@ type ContentVisibility string
 // ENUM( main, cover, preview )
 type ContentAssetRole string

+const (
+	// DefaultContentPreviewSeconds is the default preview duration in seconds when content.preview_seconds is unset/invalid.
+	// 默认试看时长（秒）：当未配置或传入非法值时使用。
+	DefaultContentPreviewSeconds int32 = 60
+)
+
 // content_prices

 // swagger:enum DiscountType