feat(ci): 搭建 A0 工程骨架与契约基线 #2
@@ -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
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in new issue
Block a user