完善 API 文档生成规范：统一路由注册和 OpenAPI 文档自动生成

主要改进：
1. 新增 docs/api-documentation-guide.md 详细文档指南
2. 在 AGENTS.md 中添加路由注册规范章节
3. 更新 README.md 文档目录结构

路由注册改进：
- 统一使用 Register() 函数注册路由并自动生成文档
- 所有接口必须指定 RouteSpec（Summary, Tags, Input, Output, Auth）
- 修复 docs.go 和 gendocs/main.go 使用 RegisterRoutesWithDoc 统一注册

DTO 规范更新：
- shop_dto.go 和 shop_account_dto.go 补充完整的 description 标签
- 所有枚举字段必须列出可能值和中文说明

文档生成优化：
- admin-openapi.yaml 自动生成更新
- 健康检查和任务管理接口加入文档
- H5 认证接口完整文档化

规范文档管理：
- 添加规范文档管理流程说明
- 详细文档放在 docs/ 目录
- AGENTS.md 只保留核心规则和引导链接

internal/model/shop_account_dto.go

@@ -2,36 +2,35 @@ package model
 
 // ShopAccountListRequest 代理商账号列表查询请求
 type ShopAccountListRequest struct {
-	Page     int    `json:"page" query:"page" validate:"omitempty,min=1"`                   // 页码
-	PageSize int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100"` // 每页数量
-	ShopID   *uint  `json:"shop_id" query:"shop_id" validate:"omitempty,min=1"`             // 店铺ID过滤
-	Username string `json:"username" query:"username" validate:"omitempty,max=50"`          // 用户名（模糊查询）
-	Phone    string `json:"phone" query:"phone" validate:"omitempty,len=11"`                // 手机号（精确查询）
-	Status   *int   `json:"status" query:"status" validate:"omitempty,oneof=0 1"`           // 状态
+	Page     int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+	PageSize int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
+	ShopID   *uint  `json:"shop_id" query:"shop_id" validate:"omitempty,min=1" minimum:"1" description:"店铺ID过滤"`
+	Username string `json:"username" query:"username" validate:"omitempty,max=50" maxLength:"50" description:"用户名（模糊查询）"`
+	Phone    string `json:"phone" query:"phone" validate:"omitempty,len=11" minLength:"11" maxLength:"11" description:"手机号（精确查询）"`
+	Status   *int   `json:"status" query:"status" validate:"omitempty,oneof=0 1" description:"状态 (0:禁用, 1:启用)"`
 }
 
 // CreateShopAccountRequest 创建代理商账号请求
 type CreateShopAccountRequest struct {
-	ShopID   uint   `json:"shop_id" validate:"required,min=1"`         // 店铺ID
-	Username string `json:"username" validate:"required,min=3,max=50"` // 用户名
-	Phone    string `json:"phone" validate:"required,len=11"`          // 手机号
-	Password string `json:"password" validate:"required,min=8,max=32"` // 密码
+	ShopID   uint   `json:"shop_id" validate:"required,min=1" required:"true" minimum:"1" description:"店铺ID"`
+	Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
+	Phone    string `json:"phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"手机号"`
+	Password string `json:"password" validate:"required,min=8,max=32" required:"true" minLength:"8" maxLength:"32" description:"密码"`
 }
 
-// UpdateShopAccountRequest 更新代理商账号请求
+// UpdateShopAccountRequest 更新代理商账号请求（不包含 phone 和 password，按照业务规则不允许修改）
 type UpdateShopAccountRequest struct {
-	Username string `json:"username" validate:"required,min=3,max=50"` // 用户名
-	// 注意：不包含 phone 和 password，按照业务规则不允许修改
+	Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
 }
 
 // UpdateShopAccountPasswordRequest 修改代理商账号密码请求（管理员重置）
 type UpdateShopAccountPasswordRequest struct {
-	NewPassword string `json:"new_password" validate:"required,min=8,max=32"` // 新密码
+	NewPassword string `json:"new_password" validate:"required,min=8,max=32" required:"true" minLength:"8" maxLength:"32" description:"新密码"`
 }
 
 // UpdateShopAccountStatusRequest 修改代理商账号状态请求
 type UpdateShopAccountStatusRequest struct {
-	Status int `json:"status" validate:"required,oneof=0 1"` // 状态（0=禁用 1=启用）
+	Status int `json:"status" validate:"required,oneof=0 1" required:"true" description:"状态 (0:禁用, 1:启用)"`
 }
 
 // ShopAccountResponse 代理商账号响应
@@ -46,3 +45,29 @@ type ShopAccountResponse struct {
 	CreatedAt string `json:"created_at" description:"创建时间"`
 	UpdatedAt string `json:"updated_at" description:"更新时间"`
 }
+
+// ShopAccountPageResult 代理账号分页响应
+type ShopAccountPageResult struct {
+	Items []ShopAccountResponse `json:"items" description:"代理账号列表"`
+	Total int64                 `json:"total" description:"总记录数"`
+	Page  int                   `json:"page" description:"当前页码"`
+	Size  int                   `json:"size" description:"每页数量"`
+}
+
+// UpdateShopAccountParams 更新代理账号聚合参数 (用于文档生成)
+type UpdateShopAccountParams struct {
+	IDReq
+	UpdateShopAccountRequest
+}
+
+// UpdateShopAccountPasswordParams 修改代理账号密码聚合参数 (用于文档生成)
+type UpdateShopAccountPasswordParams struct {
+	IDReq
+	UpdateShopAccountPasswordRequest
+}
+
+// UpdateShopAccountStatusParams 修改代理账号状态聚合参数 (用于文档生成)
+type UpdateShopAccountStatusParams struct {
+	IDReq
+	UpdateShopAccountStatusRequest
+}

internal/model/shop_dto.go

@@ -53,3 +53,18 @@ type ShopResponse struct {
 	CreatedAt    string `json:"created_at" description:"创建时间"`
 	UpdatedAt    string `json:"updated_at" description:"更新时间"`
 }
+
+// ShopPageResult 店铺分页响应
+// ShopPageResult 店铺分页响应
+type ShopPageResult struct {
+	Items []ShopResponse `json:"items" description:"店铺列表"`
+	Total int64          `json:"total" description:"总记录数"`
+	Page  int            `json:"page" description:"当前页码"`
+	Size  int            `json:"size" description:"每页数量"`
+}
+
+// UpdateShopParams 更新店铺聚合参数 (用于文档生成)
+type UpdateShopParams struct {
+	IDReq
+	UpdateShopRequest
+}