初始化

2026-07-15 16:13:27 +08:00
parent 6d6f559793
commit c4023c1623
276 changed files with 42622 additions and 0 deletions
--- a/_backup_20260613/open-api-doc.md
+++ b/_backup_20260613/open-api-doc.md
@@ -0,0 +1,449 @@
+# Mokee Gateway 对外开放 API 文档
+
+**网关地址**: `https://gw.server.zgitm.com`  
+**版本**: v1  
+**更新时间**: 2026-06-13  
+
+---
+
+## 1. 概述
+
+对外开放 API 用于外部业务系统接入 Mokee 网关平台，支持获取一次性 Token 并调用邮件发送等功能。
+
+> ⚠️ **编码要求**：所有请求和响应均使用 **UTF-8** 编码。`Content-Type` 必须指定 `charset=UTF-8`，否则中文会出现乱码或解析错误。
+
+### 认证流程
+
+```
+外部系统 ──POST /zgapi/v1/open/token──▶ 获取一次性 Token
+外部系统 ──POST /zgapi/v1/open/token/validate──▶ 校验 Token（不消费）
+外部系统 ──POST /zgapi/v1/open/token/consume──▶ 标记 Token 已消费
+外部系统 ──POST /zgapi/v1/open/email/send──▶ 发送邮件（消费 Token）
+外部系统 ──POST /zgapi/v1/open/file/upload──▶ 上传文件（消费 Token）
+外部系统 ──GET  /zgapi/v1/open/file/{id}/download──▶ 下载文件（消费 Token）
+```
+
+### Token 规则
+
+| 规则 | 说明 |
+|------|------|
+| 获取方式 | 传入 `systemCode` 即可获取，无需密钥 |
+| 有效期 | 获取后 **12 小时**内有效 |
+| 消费限制 | 每个 Token **只能使用一次**，调用任意接口即消费 |
+| 消费失败 | 接口调用失败（如邮件发送失败）**不消费** Token，可重试 |
+
+---
+
+## 2. 获取 Token
+
+传入系统编码，获取一次性 JWT Token。
+
+**请求**
+
+```
+POST /zgapi/v1/open/token
+Content-Type: application/json; charset=UTF-8
+```
+
+> **重要**：所有请求 Body 必须使用 **UTF-8** 编码。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| systemCode | string | 是 | 系统编码，需在网关平台已注册且启用 |
+
+**请求示例**
+
+```bash
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+  -H "Content-Type: application/json" \
+  -d '{"systemCode": "gateway"}'
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "token": "eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOi...",
+    "expiresIn": 43200,
+    "systemName": "网关管理平台",
+    "usageNote": "此 Token 只能消费一次，消费后立即失效"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | int | 200=成功 |
+| data.token | string | JWT Token，后续请求放入 Authorization 头 |
+| data.expiresIn | int | 有效时间（秒），43200 = 12小时 |
+| data.systemName | string | 系统名称 |
+| data.usageNote | string | 使用提示 |
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `systemCode` 参数 |
+| 401 | `systemCode` 无效或系统已停用 |
+
+---
+
+## 3. 校验 Token（不消费）
+
+检查 Token 是否有效（存在且未被消费）。**此接口不会消费 Token**，仅做状态查询。调用方可在实际操作前预先确认 Token 可用。
+
+**请求**
+
+```
+POST /zgapi/v1/open/token/validate
+Content-Type: application/json; charset=UTF-8
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| token | string | 是 | 需要校验的 JWT Token |
+
+**请求示例**
+
+```bash
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/validate" \
+  -H "Content-Type: application/json" \
+  -d '{"token": "eyJhbGciOiJIUzM4NCJ9..."}'
+```
+
+**成功响应（Token 有效，未被消费）**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "valid": true,
+    "systemCode": "gateway",
+    "msg": "Token 有效，未被消费"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.valid | bool | true = Token 有效可用 |
+| data.systemCode | string | Token 所属的系统编码 |
+| data.msg | string | 状态描述 |
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `token` 参数 |
+| 401 | Token 无效、已过期、已被消费、或类型错误 |
+
+> **关键：此接口不会消费 Token。** 校验通过后 Token 仍可用于后续操作。
+
+---
+
+## 4. 标记 Token 已消费
+
+外部系统在自己的业务逻辑中消费了 Token 后（如上传文件到自己的存储），调用此接口告知网关标记 Token 已消费，防止被重复使用。
+
+**请求**
+
+```
+POST /zgapi/v1/open/token/consume
+Content-Type: application/json; charset=UTF-8
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| token | string | 是 | 需要标记已消费的 JWT Token |
+| action | string | 是 | 消费动作描述，如 `发送邮件` / `上传文件` / `下载文件` |
+
+**请求示例**
+
+```bash
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/consume" \
+  -H "Content-Type: application/json" \
+  -d '{"token": "eyJhbGciOiJIUzM4NCJ9...", "action": "上传文件"}'
+```
+
+**成功响应**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "tokenConsumed": true,
+    "action": "上传文件",
+    "msg": "Token 已标记为已消费"
+  }
+}
+```
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `token` 或 `action` 参数 |
+| 401 | Token 无效、已过期、或已被消费 |
+
+---
+
+## 5. 发送邮件
+
+使用 Token 认证后发送邮件。**调用此接口将消费当前 Token。**
+
+**请求**
+
+```
+POST /zgapi/v1/open/email/send
+Content-Type: application/json; charset=UTF-8
+Authorization: Bearer <token>
+```
+
+> **重要**：请求 Body 必须使用 **UTF-8** 编码。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| to | string | 是 | 收件人邮箱地址 |
+| subject | string | 是 | 邮件主题 |
+| content | string | 是 | 邮件内容 |
+| contentType | string | 否 | `html`（默认）或 `text` |
+
+**请求示例**
+
+```bash
+# 先获取 Token
+TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+  -H "Content-Type: application/json" \
+  -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
+
+# 发送 HTML 邮件
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/email/send" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{
+    "to": "user@example.com",
+    "subject": "通知标题",
+    "content": "<h1>您好</h1><p>这是邮件内容</p>",
+    "contentType": "html"
+  }'
+```
+
+**成功响应**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "msg": "发送成功",
+    "tokenConsumed": true
+  }
+}
+```
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少必填参数 `to` / `subject` / `content` |
+| 401 | Token 无效、已过期或已消费 |
+| 500 | 邮件发送失败（Token 未消费，可重试） |
+
+---
+
+## 6. 上传文件
+
+使用 Token 认证后上传文件到文件对象存储。**调用此接口将消费当前 Token。**
+
+> 上传成功后返回文件 ID，可用于后续下载。
+
+**请求**
+
+```
+POST /zgapi/v1/open/file/upload
+Content-Type: multipart/form-data
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| file | file | 是 | 上传的文件 |
+| token | string | 是 | 开放 API Token（作为 form 字段传递） |
+| fileType | string | 否 | 文件类型: `avatar`/`icon`/`doc`/`other`（默认 `other`） |
+
+**请求示例**
+
+```bash
+# 先获取 Token
+TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+  -H "Content-Type: application/json" \
+  -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
+
+# 上传文件
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/file/upload" \
+  -F "file=@/path/to/avatar.png" \
+  -F "token=$TOKEN" \
+  -F "fileType=avatar"
+```
+
+**成功响应**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "fileId": "a1b2c3d4e5f6",
+    "fileName": "avatar.png",
+    "storageFileName": "a1b2c3d4e5f6.png",
+    "fileSize": 51200,
+    "tokenConsumed": true
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.fileId | string | 文件唯一 ID，用于下载 |
+| data.fileName | string | 原始文件名 |
+| data.storageFileName | string | 磁盘存储的实际文件名 |
+| data.fileSize | long | 文件大小（字节） |
+| data.tokenConsumed | bool | Token 已消费 |
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `file` 或 `token` 参数 |
+| 401 | Token 无效、已过期或已消费 |
+| 500 | 文件上传失败（Token 未消费，可重试） |
+
+---
+
+## 7. 下载文件
+
+使用 Token 认证后下载文件。**调用此接口将消费当前 Token。**
+Token 通过 URL query 参数传递。
+
+> **注意**: 每个下载链接的 Token 只能使用一次。如需多次下载，需每次获取新 Token。
+
+**请求**
+
+```
+GET /zgapi/v1/open/file/{id}/download?token=<token>
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| id | string | 是 | 文件 ID（路径参数） |
+| token | string | 是 | 开放 API Token（query 参数） |
+
+**请求示例**
+
+```bash
+# 先获取 Token
+TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+  -H "Content-Type: application/json" \
+  -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
+
+# 下载文件（保存到本地）
+curl -o downloaded.png \
+  "https://gw.server.zgitm.com/zgapi/v1/open/file/a1b2c3d4e5f6/download?token=$TOKEN"
+```
+
+**成功响应**: 直接返回文件二进制流，`Content-Type: application/octet-stream`，`Content-Disposition: attachment`。
+
+**错误响应**
+
+| HTTP 状态码 | code | 说明 |
+|:----------:|:----:|------|
+| 401 | 401 | Token 无效、已过期或已消费 |
+| 404 | 404 | 文件不存在或文件数据丢失 |
+
+---
+
+## 8. Java 调用示例
+
+使用 Hutool 或 OkHttp 均可，以下为 Hutool 示例：
+
+```java
+import cn.hutool.http.HttpRequest;
+import cn.hutool.http.HttpResponse;
+import cn.hutool.json.JSONObject;
+import cn.hutool.json.JSONUtil;
+
+public class OpenApiDemo {
+
+    private static final String BASE = "https://gw.server.zgitm.com";
+
+    public static void main(String[] args) {
+        // 1. 获取 Token
+        JSONObject tokenReq = JSONUtil.createObj().set("systemCode", "gateway");
+        String tokenResp = HttpRequest.post(BASE + "/zgapi/v1/open/token")
+                .header("Content-Type", "application/json; charset=UTF-8")
+                .body(tokenReq.toString())
+                .execute()
+                .body();
+
+        JSONObject tokenJson = JSONUtil.parseObj(tokenResp);
+        String token = tokenJson.getJSONObject("data").getStr("token");
+        System.out.println("Token: " + token.substring(0, 30) + "...");
+
+        // 2. 上传文件
+        JSONObject uploadResp = HttpRequest.post(BASE + "/zgapi/v1/open/file/upload")
+                .form("file", new java.io.File("./avatar.png"))
+                .form("token", token)
+                .form("fileType", "avatar")
+                .execute()
+                .body();
+        System.out.println("上传结果: " + uploadResp);
+
+        // 3. 发送邮件
+        JSONObject emailReq = JSONUtil.createObj()
+                .set("to", "user@example.com")
+                .set("subject", "测试邮件")
+                .set("content", "<h1>Hello</h1><p>这是一封测试邮件</p>")
+                .set("contentType", "html");
+
+        String emailResp = HttpRequest.post(BASE + "/zgapi/v1/open/email/send")
+                .header("Authorization", "Bearer " + token)
+                .body(emailReq.toString())
+                .execute()
+                .body();
+
+        System.out.println(emailResp);
+    }
+}
+```
+
+### Maven 依赖
+
+```xml
+<dependency>
+    <groupId>cn.hutool</groupId>
+    <artifactId>hutool-all</artifactId>
+    <version>5.8.28</version>
+</dependency>
+```
+
+---
+
+## 9. 附录
+
+### 可用系统编码
+
+请联系管理员获取已注册的系统编码，或登录网关管理平台查看。
+
+### 错误码汇总
+
+| HTTP 状态码 | code | 说明 |
+|:----------:|:----:|------|
+| 200 | 200 | 成功 |
+| 200 | 400 | 参数错误 |
+| 200 | 401 | 认证失败 |
+| 200 | 500 | 服务内部错误 |
+
+> **注意**：所有响应 HTTP 状态码均为 200，实际结果通过响应体中的 `code` 字段判断。
+
+### 联系支持
+
+如有问题请联系 Mokee Gateway 管理员。