全渠道留言咨询与工单中心 API

APay 将「未登录访客售前/商务留言」与「注册用户售后工单」统一收敛在 tickets + ticket_messages 模型中：

  • 未登录访客无需先注册账号即可提交咨询（留下邮箱或微信等联系方式），并凭返回的 accessToken（或邮件通知中的深链 /?inquiry=TK-...&token=...）随时查看回复进度与继续追问；
  • 已注册会员在会员中心（/user/tickets）不仅能查看登录后提交的工单，还会自动归并此前使用相同邮箱提交的访客咨询；
  • 后台管理员在 /admin/tickets 统一处理所有咨询与工单，回复时自动触发站内通知（notifications）与邮件回执（ticket_reply 模板）。

公开与全渠道接口 (/api/inquiries)

1. 提交留言咨询 (POST /api/inquiries)

同时支持未登录访客与已登录用户调用，内置基于客户端 IP 的频控保护。

请求体 (Body)

{
  "category": "presales",
  "title": "企业算力网关定制咨询",
  "contactName": "Alex",
  "contactEmail": "alex@example.com",
  "contactInfo": "微信: alex_dev",
  "content": "你好，想咨询一下一人公司团队并发配额与私有部署合作方案。",
  "context": {
    "sourcePath": "/zh/gateways",
    "locale": "zh"
  }
}
字段类型必填说明
categorystring否presales（售前咨询）、cooperation（商务合作）、feedback（建议反馈）、technical（技术排障）、billing、account、listing、studio、extension、other
titlestring否咨询标题；未传时自动截取 content 前置摘要生成标题
contentstring是咨询或留言正文（2～2000 字）
contactNamestring否提问人称呼（已登录用户默认取昵称或邮箱前缀）
contactEmailstring条件必填联系邮箱（用于接收后台回复邮件通知；未登录时与 contactInfo 至少填一项）
contactInfostring条件必填微信号 / Telegram / 手机号等补充联系方式
contextobject否页面上下文快照（如 sourcePath、locale、故障报错信息等）

成功响应 (200)

{
  "code": 200,
  "message": "咨询提交成功",
  "data": {
    "id": 42,
    "ticketNo": "TK-20261025-8391",
    "accessToken": "f4a9c2...",
    "title": "企业算力网关定制咨询",
    "category": "presales",
    "status": "open",
    "autoDiagnosed": false,
    "botReply": null
  }
}

2. 查询咨询对话详情 (GET /api/inquiries/:ticketNo)

通过单号 TK-YYYYMMDD-XXXX 获取咨询状态与完整对话消息流 ticket_messages。鉴权支持以下任一方式：

  1. Query 参数携带创建时签发的 ?token=<accessToken>；
  2. 当前已登录会员的 userId 或绑定邮箱与该咨询单一致。

3. 继续追问回复 (POST /api/inquiries/:ticketNo/reply)

访客（凭 token）或登录会员向未关闭的咨询单追加回复，已解决（resolved / auto_resolved）的咨询单在收到用户追问后自动流转回 in_progress。

{
  "token": "f4a9c2...",
  "content": "补充一下，我们目前的日均调用量大约在 500 万 Tokens 左右。"
}

会员中心与管理后台接口

  • 会员中心 (/api/users/tickets)：
    • GET /api/users/tickets：分页返回当前登录用户的工单及同邮箱历史访客咨询；
    • POST /api/users/tickets：创建会员支持工单；
    • GET /api/users/tickets/:id 与 POST /api/users/tickets/:id/reply：查看详情并追加回复（回复同邮箱访客咨询时自动完成 userId 归属绑定）。
  • 管理后台 (/api/admin/tickets)：
    • GET /api/admin/tickets：支持按状态、分类、优先级及关键词（单号、标题、用户邮箱、访客称呼/邮箱/微信号）检索；
    • GET /api/admin/tickets/:id：返回咨询详情、联系方式、来源页面快照及关联账户资产/订单；
    • POST /api/admin/tickets/:id/reply：管理员回复后自动写入站内通知并异步发送 ticket_reply 邮件回执。