仓库自包含化：Docker/CI/文档/规范入库，路由分组拆分

internal/api/webconsole.go

@@ -23,6 +23,15 @@ type createConsoleSessionRequest struct {
 }
 
 // create 创建控制台会话（内部清理残留连接并创建 OCI 控制台连接，约 30-90 秒）。
+//
+// @Summary  创建网页控制台会话
+// @Tags     网页控制台
+// @Param    id path int true "配置 ID"
+// @Param    instanceId path string true "实例 OCID"
+// @Param    body body object true "{type: serial|vnc}"
+// @Success  200 {object} map[string]any "sessionId 与 wsPath"
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/console-sessions [post]
 func (h *consoleHandler) create(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -42,6 +51,13 @@ func (h *consoleHandler) create(c *gin.Context) {
 }
 
 // remove 结束会话并删除云端控制台连接。
+//
+// @Summary  关闭网页控制台会话
+// @Tags     网页控制台
+// @Param    sessionId path string true "会话 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/console-sessions/{sessionId} [delete]
 func (h *consoleHandler) remove(c *gin.Context) {
 	h.svc.CloseSession(c.Param("sessionId"))
 	c.Status(http.StatusNoContent)
@@ -55,6 +71,13 @@ var wsUpgrader = websocket.Upgrader{
 }
 
 // ws 是控制台数据面：校验 token 后建立两跳 SSH 隧道，按会话类型分派数据泵。
+//
+// @Summary  控制台 WebSocket 数据面
+// @Tags     网页控制台
+// @Param    sessionId path string true "会话 ID"
+// @Param    token query string true "JWT(浏览器 WebSocket 无法带头,经 query 传递)"
+// @Success  101 "升级为 WebSocket"
+// @Router   /api/v1/console-sessions/{sessionId}/ws [get]
 func (h *consoleHandler) ws(c *gin.Context) {
 	if _, err := h.auth.ParseToken(c.Query("token")); err != nil {
 		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid or expired token"})