[Docs] 完善 WebAPI 文档与 OpenAPI / Swagger 配置

[ncw1992120]

背景

项目已有两块 API 文档，但都不完整：

1. OpenAPI / Swagger：pom.xml 已依赖 springdoc-openapi-starter-webmvc-ui（2.8.16），application.yml 配了 /swagger-ui.html 与 /v3/api-docs，但没有任何全局 OpenAPI 配置 Bean——Swagger UI 缺标题/描述，没有 @SecurityScheme（Authorize 按钮不可用，用户无法从 UI 鉴权调试）。
2. 手写 docs/{zh,en}/api.md：只是一张 406 行的路由表（method + path + 一句话摘要），缺少通用约定（响应信封、错误码、分页结构、认证模型）和高频端点的完整请求/响应说明。第三方接入方拿不到字段级细节，只能反复翻源码。

现状

• 后端约 85% 的 Controller 已标注 @Tag + @Operation(summary)（多为中文），但零 @Parameter / @ApiResponse / @Schema / @SecurityRequirement。
• JwtAuthFilter 支持 JWT + mc_ PAT + SSE ?token= 三态，但 Swagger 完全不知道这些。
• GlobalExceptionHandler 的错误模型（含打破信封的 409 ConfirmRequiredException）、ResultCode 枚举、IPage 分页结构、Snowflake Long 序列化为字符串 等约定散落在源码里，文档未沉淀。

提议

分两块补齐，范围刻意收窄（不做全量 Controller 注解扫描）：

1. OpenAPI / Swagger 全局配置 + 安全方案

• 新增 OpenApiConfig @Configuration Bean：Info（标题/版本/描述）+ bearerAuth @SecurityScheme（HTTP bearer，覆盖 JWT 与 mc_ PAT）+ 顶层默认 SecurityRequirement。
• application.yml 加 mateclaw.openapi.{title,version,server-url,description} 外置项（全走环境变量）。
• 不改任何现有 Controller 注解——加安全方案后，85% 的 @Tag/@Operation 直接受益。

2. 手写 api.md 通用约定 + 旗舰端点

• 新增「通用约定」章节：R<T> 信封、ResultCode 状态码表、GlobalExceptionHandler 错误模型对照、IPage 分页结构、ID/类型约定、三态认证模型 + 滑动续期、X-Workspace-Id 双途径机制。
• 新增「旗舰端点参考」章节：login、chat/stream、Agent CRUD、会话、模型、审计、改密码、PAT、审批 共 9 个高频端点的完整字段表 + curl + 错误说明。
• 406 行路由表原样保留为完整索引。

3. 新增 openapi.md（Swagger 使用指南，中英双语）

访问地址、Authorize 用法、覆盖范围、配置项、安全提示（Swagger 当前公开可访问的现状）。

改动清单

文件	类型
mateclaw-server/.../config/OpenApiConfig.java	新增（98 行）
mateclaw-server/.../application.yml	修改（+14 行）
docs/zh/api.md	修改（+326 行）
docs/en/api.md	修改（+314 行）
docs/zh/openapi.md	新增（72 行）
docs/en/openapi.md	新增（72 行）

核对出的事实（已写进文档）

1. 响应信封字段是 msg 不是 message——唯一例外是 409 ConfirmRequiredException（字段是 message）。
2. Swagger UI 当前公开可访问（/swagger-ui* 走 SecurityConfig 的 .anyRequest().permitAll()），生产收口应改 SecurityConfig。
3. 修改密码端点用 @RequestParam（非 body），路径 {id} 仅信息性，实际从 JWT principal 解析。
4. PAT 明文只返回一次，mc_ 前缀，JwtAuthFilter 按前缀分发。
5. 业务码（1001/2001 等）不映射 HTTP 状态，会以 HTTP 500 返回。

不在范围（留作后续）

• 不逐个 Controller 补 @Parameter / @ApiResponse / @Schema（「关键端点注解」增强档）。
• 不改 SecurityConfig 给 Swagger 加门禁（仅文档提醒）。
• 不动 webchat.md（已很完整）。

验证

• mvn compile 通过，OpenApiConfig.class 已生成。
• 中英文文档结构完全对齐（9 个旗舰端点 1:1 对应）。
• 文档字段/码值/行号引用与源码 DTO 逐一核对。