用途：这是 Mix Space 项目的 API 设计约定，适用于编写控制器、API 端点或处理 HTTP 请求时保持风格统一。
主要能力与约定： 控制器装饰器使用 @ApiController 而非 @Controller，开发环境无前缀，生产环境自动添加 /api/v{version} 前缀。鉴权方面，需登录的端点用 @Auth()，可选鉴权用 @IsAuthenticated() 获取当前用户状态，用 @CurrentUser() 获取当前用户。
响应转换：全局 ResponseInterceptor 会包装每个控制器返回值。裸值 T 输出为 { data: T }；withMeta(data, meta) 输出为 { data, meta }；undefined 返回 204 No Content；@HTTPDecorators.RawResponse 不做处理，跳过封装与大小写转换。withMeta 通过内部 Symbol 识别，而非检测 data 键，返回顶层含 data 的对象字面量会被双重包装，CI 通过 scripts/check-controller-response-envelope.ts 强制检查。transformResponseCase 在传输边界把 data/meta 转为 snake_case，如 createdAt 转 created_at、categoryId 转 category_id，可用 @BypassCaseTransform(['items[].rawPayload']) 让字段子树跳过转换。
分页：分页信息放在 meta 中，不合并进 data，使用 MetaObjectBuilder 构建。CRUD 样板可用 BasePgCrudFactory。
参数校验：路径参数用 EntityIdSchema 处理雪花实体 ID，整数 ID 或实体 ID 用 IntIdOrEntityIdSchema，查询参数用 BasicPagerSchema，请求体用对应 CreateSchema。
HTTP 方法与状态码：GET 获取资源返回 200，POST 创建返回 201，PUT 全量更新返回 200，PATCH 部分更新返回 200，DELETE 删除返回 204。
错误处理：业务错误抛出 BusinessException 并传入 ErrorCodeEnum，HTTP 错误使用 BadRequestException、NotFoundException、UnauthorizedException 等。
幂等与缓存：创建操作可用 @HTTPDecorators.Idempotence() 添加幂等保护，支持自定义 key；缓存可用 @HttpCache.disable 禁用，或用 @HttpCache({ ttl, key }) 自定义。
限制：以上为项目内部约定，具体实现细节与版本要求暂未提供。