OpenAPI 与 Swagger 生成规则

Controller 使用 SpringDoc/OpenAPI 注解描述标签、操作、参数、响应和安全要求。接口变更要同步 DTO/VO、错误码、鉴权说明和示例，不以手工复制的 JSON 作为唯一契约。

生成文档前确认网关前缀、服务上下文、Bearer 认证和文件/SSE 的媒体类型。删除或废弃接口保留兼容窗口，并在 API 兼容性记录中注明替代路径。