cjyyzx/工单接口.md

我已经完整阅读了后端的 API 密钥系统代码。下面是完整的接口文档：

---

工单系统 — 外部 API 密钥调用接口文档

一、认证方式

所有请求通过 HTTP 请求头 X-Api-Key 传递 API 密钥进行认证。

X-Api-Key: gd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 密钥格式：gd_live_ + 40 位十六进制字符
• 密钥仅在创建时返回一次明文，之后无法再次获取
• 密钥支持过期时间和启用/禁用控制

二、权限模型

2.1 模块权限

每个 API 密钥创建时需指定 allowedModules，限制可访问的模块范围。合法模块如下：

模块键	路由前缀	说明
ticket	/api/tickets	工单管理
customer	/api/customers	客户管理
engineer	/api/engineers	工程师/运维管理
attachment	/api/attachments	附件上传
statusMonitor	/api/status	状态监控

请求路径不在上述模块范围内的，跳过模块权限检查。

2.2 角色映射

API 密钥通过认证后，系统会生成一个合成 ADMIN 用户（id: api-key:<keyId>, role: ADMIN）。因此 API 密钥只能访问 @Roles(...) 中包含 ADMIN 的接口。

2.3 禁止访问的路径

以下管理端路径明确禁止 API 密钥访问（即使密钥有效也返回 401）：

• /api/api-keys/** — API 密钥管理
• /api/api-permissions/** — API 模块权限管理

---

三、接口列表

基础路径：/api
所有请求需携带 X-Api-Key 请求头
返回格式：JSON

---

3.1 工单模块 (ticket)

需要 allowedModules 包含 "ticket"。

3.1.1 创建工单

POST /api/tickets

请求体：

字段	类型	必填	说明
platform	string	✅	平台类型：taiji / xm / original
accountInfo	string	✅	账号信息
modelUsed	string	✅	使用的模型
description	string	✅	问题描述
requestExample	string	✅	请求示例
contactInfo	string	❌	联系方式
framework	string	❌	使用框架
networkEnv	string	❌	网络环境：local / cloud
attachmentUrls	string[]	❌	附件 URL 列表
requestedLevel	string	❌	请求工程师等级：L1 / L2 / L3

3.1.2 为指定客户创建工单

POST /api/tickets/for-customer/:customerId

路径参数： customerId — 客户 ID

请求体： 同 3.1.1

3.1.3 查询工单列表

GET /api/tickets?page=1&pageSize=20&status=PENDING

查询参数：

参数	类型	必填	默认值	说明
page	number	❌	1	页码
pageSize	number	❌	20	每页条数
status	string	❌	—	筛选状态：PENDING / ACCEPTED / IN_PROGRESS / PENDING_CLOSE / CLOSED

3.1.4 查询单个工单

GET /api/tickets/:id

3.1.5 更新工单状态

PUT /api/tickets/:id/status

请求体：

字段	类型	必填	说明
status	string	✅	目标状态

3.1.6 自行接单

PUT /api/tickets/:id/self-assign

3.1.7 分配工程师

PUT /api/tickets/:id/assign

请求体：

字段	类型	必填	说明
engineerId	string	✅	工程师 ID

3.1.8 客户关闭工单

PUT /api/tickets/:id/customer-close

3.1.9 申请关闭工单

PUT /api/tickets/:id/close-request

3.1.10 审批关闭工单

PUT /api/tickets/:id/close-approve

3.1.11 拒绝关闭工单

PUT /api/tickets/:id/close-reject

3.1.12 催单

POST /api/tickets/:id/urge

请求体：

字段	类型	必填	说明
note	string	❌	催单备注

3.1.13 获取工单留言列表

GET /api/tickets/:id/messages

3.1.14 添加工单留言

POST /api/tickets/:id/messages

请求体：

字段	类型	必填	说明
content	string	✅	留言内容
attachmentUrls	string[]	❌	附件 URL 列表

3.1.15 删除工单留言

DELETE /api/tickets/messages/:messageId

⚠️ 不可访问的接口

接口	原因
GET /api/tickets/daily-usage/me	仅限 CUSTOMER 角色，API 密钥为 ADMIN 角色，无权限

---

3.2 客户模块 (customer)

需要 allowedModules 包含 "customer"。

3.2.1 查询客户列表

GET /api/customers

3.2.2 查询单个客户

GET /api/customers/:id

⚠️ 不可访问的接口

以下接口仅限 OPERATOR 角色，API 密钥（ADMIN）无权访问：

接口	方法
POST /api/customers	创建客户
PATCH /api/customers/:id/tier	更新客户等级
PATCH /api/customers/:id/bind-engineer	绑定工程师

---

3.3 工程师/运维模块 (engineer)

需要 allowedModules 包含 "engineer"。

3.3.1 查询工程师列表

GET /api/engineers

3.3.2 创建工程师

POST /api/engineers

请求体：

字段	类型	必填	说明
username	string	✅	用户名
email	string	✅	邮箱
password	string	✅	密码
level	string	✅	等级：L1 / L2 / L3
isAdmin	boolean	❌	是否管理员

3.3.3 创建运维人员

POST /api/engineers/operators

请求体：

字段	类型	必填	说明
username	string	✅	用户名
email	string	✅	邮箱
password	string	✅	密码

3.3.4 管理端 — 查询工程师列表

GET /api/engineers/admin/engineers

3.3.5 管理端 — 更新工程师信息

PATCH /api/engineers/admin/engineers/:id

请求体（均可选）：

字段	类型	说明
username	string	用户名
email	string	邮箱
level	string	等级：L1 / L2 / L3
isAvailable	boolean	是否可用

3.3.6 管理端 — 重置工程师密码

PATCH /api/engineers/admin/engineers/:id/password

请求体：

字段	类型	必填	说明
newPassword	string	✅	新密码

3.3.7 管理端 — 删除工程师

DELETE /api/engineers/admin/engineers/:id

3.3.8 管理端 — 查询运维人员列表

GET /api/engineers/admin/operators

3.3.9 管理端 — 更新运维人员信息

PATCH /api/engineers/admin/operators/:id

请求体（均可选）：

字段	类型	说明
username	string	用户名
email	string	邮箱

3.3.10 管理端 — 重置运维人员密码

PATCH /api/engineers/admin/operators/:id/password

请求体：

字段	类型	必填	说明
newPassword	string	✅	新密码

3.3.11 管理端 — 删除运维人员

DELETE /api/engineers/admin/operators/:id

⚠️ 注意 — me 接口的局限性

以下接口虽然角色上允许 ADMIN 访问，但 API 密钥的合成用户 ID 为 api-key:<keyId>，不对应真实工程师账号，调用会在服务层失败：

接口	说明
PATCH /api/engineers/me/availability	更新可用状态
PATCH /api/engineers/me/email	更新邮箱
PATCH /api/engineers/me/password	修改密码

---

3.4 附件模块 (attachment)

需要 allowedModules 包含 "attachment"。

3.4.1 获取上传 SAS Token

POST /api/attachments/sas-token

请求体：

字段	类型	必填	说明
fileName	string	✅	文件名（会被安全化处理）

返回： 包含 Azure Blob Storage 上传所需的 SAS Token。

---

3.5 状态监控模块 (statusMonitor)

需要 allowedModules 包含 "statusMonitor"。

3.5.1 获取外部服务状态

GET /api/status/external

3.5.2 获取运维仪表盘

GET /api/status/dashboard

3.5.3 获取公开仪表盘

GET /api/status/public-dashboard

注：此接口本身无需认证即可访问。使用 API 密钥访问时会消耗模块权限检查。

---

四、白名单路径（无需模块检查）

以下路径不受 API 模块权限限制，但部分仍需 JWT 认证（API 密钥不可替代）：

路径	说明
/api/auth/*	认证相关
/api/health	健康检查
/api/public/bing-background	必应壁纸
/api/api-permissions/*	权限管理（禁止API密钥访问）
/api/api-keys*	密钥管理（禁止API密钥访问）

---

五、错误码说明

HTTP 状态码	说明
401 Unauthorized	密钥无效、已禁用、已过期，或尝试访问禁止路径
403 Forbidden	密钥的 allowedModules 不包含请求的模块 / 角色不足
400 Bad Request	请求参数校验失败
404 Not Found	资源不存在

---

六、示例调用

# 查询工单列表
curl -H "X-Api-Key: gd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://your-domain/api/tickets?page=1&pageSize=10"

# 创建工单
curl -X POST \
     -H "X-Api-Key: gd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{
       "platform": "taiji",
       "accountInfo": "test-account",
       "modelUsed": "gpt-4",
       "description": "API调用异常",
       "requestExample": "curl https://api.example.com/v1/chat"
     }' \
     "https://your-domain/api/tickets"

---

七、认证流程总结

请求 → [全局 ApiKeyGuard] 读取 X-Api-Key → 验证密钥 → 设置 req.apiClient
     → [全局 ApiModulePermissionGuard] 解析路径模块 → 检查 allowedModules
     → [控制器 JwtAuthGuard] 检测 apiClient → 合成 ADMIN 用户 → 跳过 JWT 校验
     → [控制器 RolesGuard] 检查 ADMIN 是否在 @Roles() 的允许列表中
     → 执行业务逻辑

关键源码参考：

• 密钥验证：api-key.service.ts（validateKey 方法）
• 密钥 Guard：api-key.guard.ts
• 模块权限 Guard：api-module-permission.guard.ts
• JWT Guard 中的 API Key 处理：jwt-auth.guard.ts