init: mipu-open 对外开放项目统一管理仓库

- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-04 12:16:08 +08:00
commit b450b512a2
38 changed files with 5473 additions and 0 deletions
--- a/docs/03-05_async-query.md
+++ b/docs/03-05_async-query.md
@@ -0,0 +1,187 @@
+<!-- mipuyun-api-doc: async-query -->
+# async/query - 异步查询
+
+# 异步查询（async/query）API 说明文档
+
+## 用户使用场景
+
+> 本接口目的是：
+> 当异步调用API返回code:202时，通过本接口查询异步请求的结果。
+
+## 使用时机
+
+> 当异步调用API返回 `code: 202` 时，表示请求已接收并正在后台处理。
+> 此时响应中会包含 `requestId`，使用本接口查询处理结果。
+
+## 性能指标
+
+> - 响应速度：毫秒级（直接从缓存读取）
+> - 请求频率QPS：无限制
+> - 数据保留时间：24小时
+
+## 请求说明
+
+| **请求地址** | https://${endpoint}/async/query/{requestId} |
+| --- | --- |
+| **请求方法** | GET |
+| **注意事项** | Header 必须带认证信息。 |
+
+## 请求参数
+
+### Header
+
+| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
+| --- | --- | --- | --- | --- |
+| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
+| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
+
+### 路径参数
+
+| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
+| --- | --- | --- | --- | --- |
+| requestId | String | 是 | abc123-def456 | 异步请求返回的 requestId |
+
+## 响应说明
+
+### 有结果（请求已处理完成）
+
+当异步请求已处理完成，**直接返回原始响应数据**（不包裹在统一响应结构中）。
+
+**判断方式**：响应体中直接包含业务数据字段（如 `itineraries`、`bookingId` 等），无 `code` 字段包裹。
+
+**示例 - 有结果（搜索）**：
+
+```json
+{
+  "itineraries": [
+    {
+      "itineraryId": "xxx",
+      "outbound": {
+        "segments": [...]
+      },
+      "price": {
+        "total": 1200.00
+      }
+    }
+  ],
+  "sessionId": "session-xxx"
+}
+```
+
+**示例 - 有结果（预订）**：
+
+```json
+{
+  "bookingId": "BK123456",
+  "status": "HOLD",
+  "expiryTime": "2025-01-20T12:00:00Z"
+}
+```
+
+### 无结果（请求未找到或已过期）
+
+当异步请求不存在或已过期时，返回 404 错误。
+
+**判断方式**：响应体中 `code: 404`
+
+**示例 - 无结果**：
+
+```json
+{
+  "code": 404,
+  "msg": "Not found"
+}
+```
+
+**可能原因**：
+1. `requestId` 不存在
+2. 请求已过期（超过 24 小时）
+3. 请求属于其他租户（clientCode 不匹配）
+
+### 请求仍在处理中
+
+当异步请求仍在处理中时，会返回处理中的状态。
+
+**示例 - 处理中**：
+
+```json
+{
+  "code": 202,
+  "msg": "Processing",
+  "requestId": "abc123-def456"
+}
+```
+
+## 完整示例
+
+### 请求示例
+
+```bash
+curl -X GET "https://api.example.com/async/query/abc123-def456" \
+  -H "client-key: your-client-key" \
+  -H "client-secret: your-client-secret"
+```
+
+### 响应示例（有结果）
+
+```json
+{
+  "itineraries": [
+    {
+      "itineraryId": "itinerary-001",
+      "outbound": {
+        "segments": [
+          {
+            "carrier": "CA",
+            "flightNumber": "CA123",
+            "origin": "PEK",
+            "destination": "SHA",
+            "departureTime": "2025-01-20T08:00:00",
+            "arrivalTime": "2025-01-20T10:00:00"
+          }
+        ]
+      },
+      "price": {
+        "currency": "CNY",
+        "total": 1200.00
+      }
+    }
+  ],
+  "sessionId": "session-xxx"
+}
+```
+
+### 响应示例（无结果）
+
+```json
+{
+  "code": 404,
+  "msg": "Not found"
+}
+```
+
+## 常见问题
+
+### Q: 如何获取 requestId？
+
+A: 当异步调用API返回 `code: 202` 时，响应中会包含 `requestId` 字段。
+
+```json
+{
+  "code": 202,
+  "msg": "Async request accepted",
+  "requestId": "abc123-def456"
+}
+```
+
+### Q: 结果会保留多久？
+
+A: 异步请求的结果会保留 24 小时，超时后自动删除。
+
+### Q: 可以查询其他租户的请求吗？
+
+A: 不可以。接口会根据认证信息中的 clientCode 进行租户隔离，只能查询本租户的请求。
+
+### Q: 建议的轮询策略是什么？
+
+A: 建议每隔 2-5 秒查询一次，最多查询 10 次。如果 10 次后仍未获取结果，可能是航司响应较慢，建议稍后重试。