docs(api): 补全 OpenAPI 注释与生成文档

为接口、模型与脚本补齐 Swagger/OpenAPI 注释，生成最新文档，并增加一键生成与查看入口。

apps/api/internal/httpapi/runtime_policy_handlers.go

@@ -9,6 +9,17 @@ import (
 	"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
 )
 
+// listRuntimePolicySets godoc
+// @Summary 列出运行策略集
+// @Description 管理端返回可分配给平台、模型或用户组的运行策略集。
+// @Tags runtime
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} RuntimePolicySetListResponse
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/policy-sets [get]
 func (s *Server) listRuntimePolicySets(w http.ResponseWriter, r *http.Request) {
 	items, err := s.store.ListRuntimePolicySets(r.Context())
 	if err != nil {
@@ -19,6 +30,17 @@ func (s *Server) listRuntimePolicySets(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// getRunnerPolicy godoc
+// @Summary 获取 Runner 策略
+// @Description 管理端获取当前生效的默认 Runner 调度策略。
+// @Tags runtime
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} store.RunnerPolicy
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/runner-policy [get]
 func (s *Server) getRunnerPolicy(w http.ResponseWriter, r *http.Request) {
 	item, err := s.store.GetActiveRunnerPolicy(r.Context())
 	if err != nil {
@@ -29,6 +51,20 @@ func (s *Server) getRunnerPolicy(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, item)
 }
 
+// updateRunnerPolicy godoc
+// @Summary 更新 Runner 策略
+// @Description 管理端写入默认 Runner 调度策略。
+// @Tags runtime
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param input body store.RunnerPolicyInput true "Runner 策略请求"
+// @Success 200 {object} store.RunnerPolicy
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/runner-policy [patch]
 func (s *Server) updateRunnerPolicy(w http.ResponseWriter, r *http.Request) {
 	var input store.RunnerPolicyInput
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -45,10 +81,26 @@ func (s *Server) updateRunnerPolicy(w http.ResponseWriter, r *http.Request) {
 }
 
 type updatePlatformDynamicPriorityRequest struct {
-	DynamicPriority *int `json:"dynamicPriority"`
-	Reset           bool `json:"reset"`
+	DynamicPriority *int `json:"dynamicPriority" example:"10"`
+	Reset           bool `json:"reset" example:"false"`
 }
 
+// updatePlatformDynamicPriority godoc
+// @Summary 更新平台动态优先级
+// @Description 管理端调整平台运行时动态优先级；reset 为 true 时清空动态值。
+// @Tags runtime
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param platformID path string true "平台 ID"
+// @Param input body updatePlatformDynamicPriorityRequest true "动态优先级请求"
+// @Success 200 {object} store.Platform
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/platforms/{platformID}/dynamic-priority [patch]
 func (s *Server) updatePlatformDynamicPriority(w http.ResponseWriter, r *http.Request) {
 	var input updatePlatformDynamicPriorityRequest
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -82,6 +134,21 @@ func (s *Server) updatePlatformDynamicPriority(w http.ResponseWriter, r *http.Re
 	writeJSON(w, http.StatusOK, item)
 }
 
+// createRuntimePolicySet godoc
+// @Summary 创建运行策略集
+// @Description 管理端创建运行策略集，policyKey 和 name 必填。
+// @Tags runtime
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param input body store.RuntimePolicySetInput true "运行策略集请求"
+// @Success 201 {object} store.RuntimePolicySet
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 409 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/policy-sets [post]
 func (s *Server) createRuntimePolicySet(w http.ResponseWriter, r *http.Request) {
 	var input store.RuntimePolicySetInput
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -105,6 +172,23 @@ func (s *Server) createRuntimePolicySet(w http.ResponseWriter, r *http.Request)
 	writeJSON(w, http.StatusCreated, item)
 }
 
+// updateRuntimePolicySet godoc
+// @Summary 更新运行策略集
+// @Description 管理端更新运行策略集及其限流、重试、超时等策略配置。
+// @Tags runtime
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param policySetID path string true "运行策略集 ID"
+// @Param input body store.RuntimePolicySetInput true "运行策略集请求"
+// @Success 200 {object} store.RuntimePolicySet
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 409 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/policy-sets/{policySetID} [patch]
 func (s *Server) updateRuntimePolicySet(w http.ResponseWriter, r *http.Request) {
 	var input store.RuntimePolicySetInput
 	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
@@ -132,6 +216,19 @@ func (s *Server) updateRuntimePolicySet(w http.ResponseWriter, r *http.Request)
 	writeJSON(w, http.StatusOK, item)
 }
 
+// deleteRuntimePolicySet godoc
+// @Summary 删除运行策略集
+// @Description 管理端删除非默认运行策略集；默认策略集受保护。
+// @Tags runtime
+// @Produce json
+// @Security BearerAuth
+// @Param policySetID path string true "运行策略集 ID"
+// @Success 204 "No Content"
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/policy-sets/{policySetID} [delete]
 func (s *Server) deleteRuntimePolicySet(w http.ResponseWriter, r *http.Request) {
 	if err := s.store.DeleteRuntimePolicySet(r.Context(), r.PathValue("policySetID")); err != nil {
 		if store.IsNotFound(err) {