// 定义文章相关的结构体（与数据表字段映射）
type (
	// 文章基础结构（对应数据表字段）
	Article {
		Id       int64  `json:"id"`
		Title    string `json:"title"`
		Content  string `json:"content"`
		Cover    string `json:"cover"`
		CreateAt string `json:"create_at"` // 前端通常用字符串承载时间，可根据需求改为 time.Time
		UpdateAt string `json:"update_at"`
		IsDelete int    `json:"is_delete"` // tinyint 映射为 int，1=已删除，0=未删除
		Topic    string `json:"topic"`
		Excerpt  string `json:"excerpt"`
	}
	// 1. 创建文章：请求体
	CreateArticleReq {
		Title   string `json:"title"` // 文章标题
		Content string `json:"content"` // 文章内容
		Cover   string `json:"cover"` // 封面图
		Topic   string `json:"topic"` // 话题
	}
	// 创建文章：响应
	CreateArticleResp {
		Id      int64 `json:"id"` // 新增文章的 ID
		Success bool  `json:"success"` // 操作是否成功
	}
	// 2. 文章列表：请求（带分页/筛选）
	ListArticleReq {
		Page  int    `json:"page,optional"` // 页码（可选，默认第一页）
		Size  int    `json:"size,optional"` // 每页条数（可选，默认 10 条）
		Topic string `json:"topic,optional"` // 按话题筛选（可选）
	}
	// 文章列表：响应
	ListArticleResp {
		Total int64     `json:"total"` // 总条数
		List  []Article `json:"list"` // 文章列表
	}
	// 3. 文章详情：请求（通过 ID 查询）
	DetailArticleReq {
		Id int64 `path:"id"` // 从路径参数取 ID，如 /api/articles/:id
	}
	// 文章详情：响应
	DetailArticleResp {
		Article Article `json:"article"` // 文章详情
		Success bool    `json:"success"` // 操作是否成功
	}
	// 4. 更新文章：请求（部分字段可选更新）
	UpdateArticleReq {
		Id      int64  `path:"id"` // 要更新的文章 ID
		Title   string `json:"title,optional"`
		Content string `json:"content,optional"`
		Cover   string `json:"cover,optional"`
		Topic   string `json:"topic,optional"`
		Excerpt string `json:"excerpt,optional"`
	}
	// 更新文章：响应
	UpdateArticleResp {
		Success bool `json:"success"`
	}
	// 5. 删除文章（软删除：修改 is_delete 为 1）：请求
	DeleteArticleReq {
		Id int64 `path:"id"` // 要删除的文章 ID
	}
	// 删除文章：响应
	DeleteArticleResp {
		Success bool `json:"success"`
	}
)

// 文章服务的 API 分组与路由前缀
@server (
	group:  article
	prefix: /api/articles
)
service article-api {
	// 1. 创建文章（POST）
	@handler CreateArticleHandler
	post / (CreateArticleReq) returns (CreateArticleResp)

	// 2. 查询文章列表（GET）
	@handler ListArticleHandler
	get / (ListArticleReq) returns (ListArticleResp)

	// 3. 查询文章详情（GET）
	@handler DetailArticleHandler
	get /:id (DetailArticleReq) returns (DetailArticleResp)

	// 4. 更新文章（PUT）
	@handler UpdateArticleHandler
	put /:id (UpdateArticleReq) returns (UpdateArticleResp)

	// 5. 删除文章（软删除，DELETE）
	@handler DeleteArticleHandler
	delete /:id (DeleteArticleReq) returns (DeleteArticleResp)
}