docs(api): 完善 WebAPI 文档与 OpenAPI / Swagger 配置

[ncw1992120]

Closes #406

背景

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

1. OpenAPI / Swagger：pom.xml 已依赖 springdoc-openapi（2.8.16），但没有任何全局 OpenAPI 配置 Bean——Swagger UI 缺标题/描述、没有 @SecurityScheme（Authorize 按钮不可用）。
2. 手写 docs/{zh,en}/api.md：只是一张 406 行路由表，缺少通用约定（响应信封、错误码、分页、认证模型）和高频端点的完整请求/响应说明。

改动

• OpenApiConfig.java（新增）：全局 @Configuration Bean。Info（标题/版本/描述）+ bearerAuth @SecurityScheme（HTTP bearer，覆盖 JWT 与 mc_ PAT）+ 顶层默认 SecurityRequirement。配置项全部 @Value 注入可外置覆盖。
• application.yml：springdoc 加 default-flat-param-object + 安全现状注释；新增 mateclaw.openapi.{title,version,server-url,description}（全走环境变量）。
• docs/{zh,en}/api.md：插入「通用约定」章节（R<T> 信封、ResultCode 状态码表、GlobalExceptionHandler 错误模型对照、IPage 分页、ID/类型约定、三态认证模型 + 滑动续期、X-Workspace-Id 机制）+ 「旗舰端点参考」章节（9 个高频端点完整字段表 + curl）。
• docs/{zh,en}/openapi.md（新增）：Swagger 使用指南（访问地址、Authorize、配置、安全提示）。

范围

刻意收窄——不改任何现有 Controller 注解。约 85% 的 Controller 已有 @Tag+@Operation，加全局安全方案后直接受益。@Parameter/@ApiResponse/@Schema 增强与 Swagger 门禁属后续。

验证

• mvn compile 通过（dev 基线），OpenApiConfig.class 已生成。
• diff 为纯新增：908 insertions, 0 deletions（未触碰 dev 的路由表或配置）。
• 中英文档 1:1 对齐（9 个旗舰端点）。
• 文档字段/码值/行号引用与源码 DTO 逐一核对。

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

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