From 63d8889bee5aa9c59b03b106634bbc7dbbbec36e Mon Sep 17 00:00:00 2001
From: Stev_Wang <304865932@qq.com>
Date: Mon, 2 Nov 2026 17:22:32 +0800
Subject: [PATCH] =?UTF-8?q?build(api):=20=E6=8F=90=E4=BA=A4=20OpenAPI=20?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6=E5=BF=AB=E7=85=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

固化 A0 基线契约（OpenAPI 3.1，含 ErrorCode/ErrorResponse 与 x-error-codes），供 openapi:diff 做破坏性变更检测。
---
 openapi/lingxi.openapi.json | 288 ++++++++++++++++++++++++++++++++++++
 1 file changed, 288 insertions(+)
 create mode 100644 openapi/lingxi.openapi.json

diff --git a/openapi/lingxi.openapi.json b/openapi/lingxi.openapi.json
new file mode 100644
index 0000000..7623e29
--- /dev/null
+++ b/openapi/lingxi.openapi.json
@@ -0,0 +1,288 @@
+{
+  "openapi": "3.1.0",
+  "paths": {
+    "/health": {
+      "get": {
+        "description": "真实检查 PostgreSQL 与 Redis；任一不可用返回 503 与统一错误体。",
+        "operationId": "HealthController_check",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "全部依赖健康",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HealthResponseDto"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "依赖不可用（错误码 50002），details 内附各依赖检查结果"
+          }
+        },
+        "summary": "健康检查",
+        "tags": [
+          "platform"
+        ]
+      }
+    }
+  },
+  "info": {
+    "title": "灵犀 API",
+    "description": "信息流广告素材生产平台后端 API。\n\n统一约定：\n- 前缀 /api/v1（健康检查 /health 除外）\n- 错误体 { code, message, details, trace_id }\n- 列表响应 { items, next_cursor }",
+    "version": "0.1.0",
+    "contact": {}
+  },
+  "tags": [],
+  "servers": [
+    {
+      "url": "/api/v1",
+      "description": "API v1"
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "bearer": {
+        "scheme": "bearer",
+        "bearerFormat": "JWT",
+        "type": "http"
+      }
+    },
+    "schemas": {
+      "ComponentHealthDto": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down"
+            ],
+            "example": "up"
+          },
+          "latencyMs": {
+            "type": "number",
+            "description": "检查耗时（毫秒）",
+            "example": 3
+          },
+          "error": {
+            "type": "string",
+            "description": "失败原因（仅 down 时返回）"
+          }
+        },
+        "required": [
+          "status",
+          "latencyMs"
+        ]
+      },
+      "HealthChecksDto": {
+        "type": "object",
+        "properties": {
+          "database": {
+            "$ref": "#/components/schemas/ComponentHealthDto"
+          },
+          "redis": {
+            "$ref": "#/components/schemas/ComponentHealthDto"
+          }
+        },
+        "required": [
+          "database",
+          "redis"
+        ]
+      },
+      "HealthResponseDto": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "degraded"
+            ],
+            "example": "ok"
+          },
+          "env": {
+            "type": "string",
+            "example": "development"
+          },
+          "version": {
+            "type": "string",
+            "example": "0.1.0"
+          },
+          "uptimeSeconds": {
+            "type": "number",
+            "description": "进程运行秒数",
+            "example": 128
+          },
+          "checks": {
+            "$ref": "#/components/schemas/HealthChecksDto"
+          },
+          "timestamp": {
+            "type": "string",
+            "example": "2026-11-02T08:00:00.000Z"
+          }
+        },
+        "required": [
+          "status",
+          "env",
+          "version",
+          "uptimeSeconds",
+          "checks",
+          "timestamp"
+        ]
+      },
+      "ErrorResponseDto": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "number",
+            "description": "错误码（见 ErrorCode 常量）",
+            "example": 42202
+          },
+          "message": {
+            "type": "string",
+            "description": "可直接展示给用户的提示",
+            "example": "内容触发合规拦截"
+          },
+          "details": {
+            "type": "object",
+            "description": "补充信息（字段错误、命中规则等），结构由错误码决定",
+            "example": {
+              "issues": [
+                {
+                  "path": "name",
+                  "message": "Required"
+                }
+              ]
+            }
+          },
+          "trace_id": {
+            "type": "string",
+            "description": "请求追踪 ID，与日志同源",
+            "example": "01JABCDEF0123456789ABCDEFG"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "trace_id"
+        ]
+      },
+      "ErrorCode": {
+        "type": "integer",
+        "description": "业务错误码（只允许使用 @lingxi/shared 中登记的错误码）",
+        "enum": [
+          40001,
+          40101,
+          40102,
+          40103,
+          40301,
+          40302,
+          40303,
+          40304,
+          40401,
+          40901,
+          40902,
+          40903,
+          42201,
+          42202,
+          42203,
+          42901,
+          42902,
+          50001,
+          50002,
+          50003
+        ]
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": [
+          "code",
+          "message",
+          "trace_id"
+        ],
+        "properties": {
+          "code": {
+            "$ref": "#/components/schemas/ErrorCode"
+          },
+          "message": {
+            "type": "string"
+          },
+          "details": {
+            "description": "补充信息，结构由错误码决定"
+          },
+          "trace_id": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "x-error-codes": [
+    {
+      "code": 40001
+    },
+    {
+      "code": 40101
+    },
+    {
+      "code": 40102
+    },
+    {
+      "code": 40103
+    },
+    {
+      "code": 40301
+    },
+    {
+      "code": 40302
+    },
+    {
+      "code": 40303
+    },
+    {
+      "code": 40304
+    },
+    {
+      "code": 40401
+    },
+    {
+      "code": 40901
+    },
+    {
+      "code": 40902
+    },
+    {
+      "code": 40903
+    },
+    {
+      "code": 42201
+    },
+    {
+      "code": 42202
+    },
+    {
+      "code": 42203
+    },
+    {
+      "code": 42901
+    },
+    {
+      "code": 42902
+    },
+    {
+      "code": 50001
+    },
+    {
+      "code": 50002
+    },
+    {
+      "code": 50003
+    }
+  ],
+  "x-api-config": {
+    "env": "development",
+    "featureVideo": false
+  }
+}