CoreOTT Docs

API 参考

由 docs/source/endpoints.mjs 生成。缺示例请求的端点标红；CI 只告警不阻断。

当前有 1 个端点缺示例请求。

public

GET /api/health 缺少示例请求

健康检查：返回服务版本与 D1 迁移状态。

auth=公开 · tag=public

该端点缺少示例请求，已标红并在 CI 告警（不阻断构建）。

GET /api/plans

公开套餐目录投影（仅 is_public 且未下架），支持 ?locale=en|zh。

auth=公开 · tag=public

示例请求

GET /api/plans?locale=en&limit=10

示例响应

{
  "docs": [
    {
      "id": "019a1f4e-7b3c-7d2e-8f01-1234567890ab",
      "slug": "starter",
      "name": "Starter",
      "description": "For small teams, includes 5 licensed users.",
      "currency": "USD",
      "price_monthly_minor": 9900,
      "price_yearly_minor": 99000,
      "licensed_users_max": 100
    }
  ],
  "totalDocs": 1
}

auth

POST /api/auth/signup

客户自助注册；成功后发送验证邮件（staging 不暴露 token）。

auth=公开 · tag=auth

示例请求

POST /api/auth/signup
Content-Type: application/json

{"email":"ops@example.com","password":"Str0ngPassw0rd","company":"Example Media"}

示例响应

HTTP 201
{"user":{"id":"...","email":"ops@example.com","status":"pending"},"org":{"id":"...","name":"Example Media"}}
POST /api/auth/login

客户登录，返回会话 cookie（biz-token）与用户信息。

auth=公开 · tag=auth

示例请求

POST /api/auth/login
Content-Type: application/json

{"email":"ops@example.com","password":"Str0ngPassw0rd"}

示例响应

HTTP 200
{"user":{"id":"...","email":"ops@example.com","status":"active"},"token":"<jwt>"}
GET /api/me

当前用户与所属 org（控制台所有 own-org 判定的唯一入口）。

auth=客户会话 · tag=auth

示例请求

GET /api/me
Cookie: biz-token=<jwt>

示例响应

{"user":{"id":"...","email":"ops@example.com"},"org":{"id":"...","name":"Example Media"}}

console

GET /api/console/overview

控制台概览：实例/授权/发票/上报状态计数。

auth=客户会话 + own org · tag=console

示例请求

GET /api/console/overview
Cookie: biz-token=<jwt>

示例响应

{"instances":1,"licenses":1,"invoices":2,"reports":{"status":"ok"}}
GET /api/console/instances

本人 org 的实例列表（跨 org 一律 403/空）。

auth=客户会话 + own org · tag=console

示例请求

GET /api/console/instances
Cookie: biz-token=<jwt>

示例响应

{"docs":[{"id":"...","domain":"video.example.com","status":"active","version":"1.0.0"}]}
GET /api/console/instances/:id

实例详情：部署进度、版本/上报、授权状态、升级历史。

auth=客户会话 + own org · tag=console

示例请求

GET /api/console/instances/<instance-id>
Cookie: biz-token=<jwt>

示例响应

{"doc":{"id":"...","status":"active","license":{"status":"active","days_to_expiry":30}}}
POST /api/console/instances/:id/upgrade

一键升级触发：双闸门（凭据 + 授权 active）、幂等 job、失败回滚。

auth=客户会话 + own org · tag=console

示例请求

POST /api/console/instances/<instance-id>/upgrade
Content-Type: application/json

{"to_version":"1.2.0"}

示例响应

HTTP 202
{"job_id":"...","job":{"status":"running","stage":"migrate_d1"}}
POST /api/console/instances/:id/renew

续费下单：复用同档 renewal 单，awaiting_payment 唯一（重复 409）。

auth=客户会话 + own org · tag=console

示例请求

POST /api/console/instances/<instance-id>/renew
Cookie: biz-token=<jwt>

示例响应

HTTP 201
{"doc":{"id":"...","kind":"renewal","status":"awaiting_payment","amount_minor":99000}}
GET /api/console/tickets

工单列表 + 双向消息（附件只返回元数据/签名 URL）。

auth=客户会话 + own org · tag=console

示例请求

GET /api/console/tickets
Cookie: biz-token=<jwt>

示例响应

{"docs":[{"id":"...","subject":"Deploy help","status":"open","messages":[]}]}
POST /api/console/tickets

提交工单；进入 CRM 队列，SLA 按优先级计时。

auth=客户会话 + own org · tag=console

示例请求

POST /api/console/tickets
Content-Type: application/json

{"subject":"Deploy help","body":"TXT record not verified","category":"technical","priority":"high"}

示例响应

HTTP 201
{"doc":{"id":"...","status":"open","priority":"high","sla_due_at":"..."},"message":{...}}
GET /api/console/notifications

站内通知列表 + 未读数（org 级最小面）。

auth=客户会话 + own org · tag=console

示例请求

GET /api/console/notifications
Cookie: biz-token=<jwt>

示例响应

{"docs":[{"id":"...","kind":"ticket_reply","title":"New reply on ticket: Deploy help","read_at":null}],"unread_count":1}
POST /api/console/notifications/read

全部标为已读（org 级）。

auth=客户会话 + own org · tag=console

示例请求

POST /api/console/notifications/read
Cookie: biz-token=<jwt>

示例响应

{"updated":1}

crm

GET /api/crm/customers

CRM 客户列表（客户 = platform-orgs；sales 只看自己名下）。

auth=staff + crm.customers.read · tag=crm

示例请求

GET /api/crm/customers
Authorization: JWT <staff-jwt>

示例响应

{"docs":[{"id":"...","name":"Example Media","counts":{"instances":1,"licenses":1,"orders":2,"tickets":1}}]}
GET /api/crm/customers/:id

客户详情：org、实例、授权、订单、工单聚合。

auth=staff + crm.customers.read · tag=crm

示例请求

GET /api/crm/customers/<org-id>
Authorization: JWT <staff-jwt>

示例响应

{"doc":{"id":"...","name":"Example Media"},"instances":[...],"licenses":[...]}
GET /api/crm/tickets

CRM 工单队列 + SLA 高亮（超时且无更晚 staff 回复）。

auth=staff + crm.tickets.read · tag=crm

示例请求

GET /api/crm/tickets
Authorization: JWT <staff-jwt>

示例响应

{"docs":[{"id":"...","subject":"Deploy help","sla_breached":false}],"sla_breached_count":0}
POST /api/crm/tickets/:id/reply

员工回复工单；触发客户站内通知 + 邮件 outbox。

auth=staff + crm.tickets.reply · tag=crm

示例请求

POST /api/crm/tickets/<ticket-id>/reply
Authorization: JWT <staff-jwt>
Content-Type: application/json

{"body":"We are checking the TXT record."}

示例响应

{"doc":{"id":"...","author_type":"staff"},"ticket":{"status":"pending"}}