# 控制台与组织管理

组织与项目额度、真实用量、账单资料、会话安全和管理员审批。

## 登录与组织 [#登录与组织]

使用已有账户[登录](/login)即可进入[控制台](/console)。开放平台暂未开放自助注册，需要接入可[联系商务](/contact)。管理员权限的初始化与委派规则见[平台管理与权限](/docs/admin)。

控制台中的项目、密钥、额度和用量归属当前组织。切换组织后，页面重新读取该组织的数据；服务端独立检查成员身份，不能通过修改 URL 或项目 ID 访问其他组织的资源。

组织角色和平台管理员角色分别管理：

| 操作                         | owner | developer | viewer |
| ---------------------------- | ----- | --------- | ------ |
| 查看所属组织与项目用量、额度 | 可以  | 可以      | 可以   |
| 修改组织信息、账单资料       | 可以  | 不可以    | 不可以 |
| 修改额度、提交额度申请       | 可以  | 不可以    | 不可以 |
| 修改项目名称与描述           | 可以  | 可以      | 不可以 |
| 查看并撤销本人其他会话       | 可以  | 可以      | 可以   |

## 组织与项目设置 [#组织与项目设置]

[组织设置](/console/organization)支持修改组织名称和账单联系邮箱。名称最多 80 字符，邮箱可留空。组织 ID 不可修改。

项目设置支持修改名称与描述，描述最多 1,000 字符。项目 ID 保持不变。当前区域显示“默认部署区域”，由实际部署决定，不支持在页面切换，也不代表已有跨区域冗余或数据驻留承诺。

组织账单联系邮箱用于组织资料。账单页面首次读取时可使用该邮箱作为初始值；账单资料单独保存后，其邮箱独立维护。当前没有账单邮件服务。

## 组织与项目额度 [#组织与项目额度]

[组织额度](/console/limits)显示本月实际字符用量、当前每分钟请求额度与申请历史。项目额度显示相应项目的统计；每次真实推理请求同时受到组织额度与项目额度约束。

- 每分钟请求额度按滚动 60 秒执行，已发起但上游失败的请求也占用该窗口。
- 月字符额度按 UTC 自然月统计成功请求的输入字符。正在处理的请求会预留额度，防止并发超用。
- 月用量记录只统计实际成功用量；处理中预留的部分不会显示为已成功消费。
- 修改额度不能超过服务端部署上限，也不能设为 0、负数或小数。
- 额度不足时，服务端返回 `429`。可等待窗口重置，或由组织所有者调整额度。

额度申请可以超过当前可配置上限。每个组织或项目范围同时只能有一条待审批申请；重复申请返回 `409`。提交后不会立即改变额度。

平台管理员在[额度审批](/admin/limits)批准或拒绝申请，并填写审核意见。批准会立即更新相应范围的额度。审批仍受部署上限约束，管理员不能通过网页绕过容量限制；需要扩容时，应先由部署维护人员调整配置。已处理申请不能再次审核。

部署上限由以下变量配置，所有值均为正整数：

| 变量                                   |    默认值 | 含义               |
| -------------------------------------- | --------: | ------------------ |
| `ELEJO_ORG_RPM_CAP`                    |        60 | 组织每分钟请求上限 |
| `ELEJO_ORG_MONTHLY_CHARACTERS_CAP`     | 1,000,000 | 组织每月字符上限   |
| `ELEJO_PROJECT_RPM_CAP`                |        30 | 项目每分钟请求上限 |
| `ELEJO_PROJECT_MONTHLY_CHARACTERS_CAP` |   500,000 | 项目每月字符上限   |

这些是部署配置上限，不是已购买套餐、余额或付费承诺。请求数安全上界为 1,000,000，每月字符数安全上界为 1,000,000,000,000。

## 用量统计 [#用量统计]

[用量统计](/console/usage)可查看最近 7、30、90 天，按组织或项目筛选。统计包含请求数、成功调用的输入字符数、成功率、失败请求数、每日趋势和产品分布。

数据来自服务端实际写入的用量记录。HTTP 2xx 状态计为成功，其余状态计为失败；失败请求的字符用量为 0。语音识别记录请求次数，但当前没有音频时长或音频字符计费，字符用量为 0。所选范围内没有记录时，页面显示真实的零值和空状态，成功率显示“—”。

图表按 UTC 日期汇总，空日期补零。可以展开“查看每日明细”读取表格。最近请求表最多显示 100 条记录，总数以汇总卡片为准。统计只覆盖已接入并通过平台记录的请求，不包含设备上未上报的离线 SDK 使用量。

## 账单资料与支付边界 [#账单资料与支付边界]

[账单页面](/console/billing)支持组织所有者保存法定名称、账单邮箱、地址和税务识别号。

账单数据通过服务端只读适配器接入。未配置时返回 `configured: false`、`available: false`、`balance: null` 和空账单；已配置但无法读取时为 `configured: true`、`available: false`。`available: true` 表示成功读取，`billingEnabled` 表示该组织是否开通计费，两者不能与“已配置”混淆。

部署管理员设置 `BILLING_UPSTREAM_URL` 和 `BILLING_UPSTREAM_TOKEN`。平台向可信 HTTPS 端点发送 `POST { "workspaceId": "组织 UUID" }` 和 Bearer token。这个 POST 只读取账单，不创建交易。上游响应示例（数值仅用于协议说明）：

```json
{
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "billingEnabled": true,
  "balanceMinor": 1250,
  "currency": "USD",
  "invoices": [
    {
      "id": "invoice-example",
      "number": "INV-EXAMPLE",
      "status": "paid",
      "amountMinor": 500,
      "currency": "USD",
      "issuedAt": "2026-10-01T00:00:00.000Z"
    }
  ]
}
```

返回组织必须与查询组织一致，账单 ID 不能重复。上游用整数分传输金额，平台返回的 `balance` / `amount` 转为货币主单位（示例对应 12.50 美元余额、5.00 美元账单）。币种支持 USD、CNY、EUR；账单状态为 `paid`、`open`、`void`。

适配器仅服务端使用凭据，不把内部 URL 或 token 返回浏览器。查询超时 5 秒，拒绝重定向，响应上限 128 KiB，最多 100 条账单，按组织缓存 30 秒。无效或跨组织响应会显示不可用，不回退为虚假余额。

保存账单资料只会更新平台数据库，不会发起交易。充值、自动扣款、发票开具、回调签名验证、支付幂等与自动对账尚未实现。页面提供真实账单展示，支付按钮保持不可用。

## 账户安全 [#账户安全]

[安全页面](/console/security)展示当前账户的活跃登录会话，包括当前设备标记、创建与最近记录时间、到期时间，以及经过掩码处理的 IP。设备名称来自请求中的浏览器信息，不是硬件认证。

只能撤销本人其他会话。当前会话应通过退出登录结束；撤销其他用户会话会被拒绝。会话撤销不影响 API Key，需要停止密钥调用时，应到密钥管理页撤销相应 Key。重复撤销已不存在的会话返回 `404`，页面会显示服务端错误。

双重验证状态以账户实际配置为准，默认不会自动启用。控制台提供的验证器设置需要完成密码确认、保存恢复码和验证码验证后才算启用。恢复码属于敏感凭据，应保存在安全位置。是否已启用应以页面刷新后的账户状态为准。

生产环境仍需完成 HTTPS、告警、备份恢复、密钥轮换与访问控制验收。安全页面不代表已获得第三方合规认证；实际数据处理条款和部署区域须单独确认。

## 接口约定 [#接口约定]

以下接口使用当前登录会话。控制台通过 `x-workspace-id` 指定组织，服务端再次验证访问权限。请求为 JSON，同源写请求受来源校验保护；返回 `Cache-Control: no-store`。

| 方法         | 路径                                                    | 用途                               |
| ------------ | ------------------------------------------------------- | ---------------------------------- |
| `GET`        | `/api/platform/console/overview`                        | 额度、账单状态、接入地址与安全摘要 |
| `GET`        | `/api/platform/console/limits?projectId=...`            | 当前额度、部署上限、本月用量与申请 |
| `POST`       | `/api/platform/console/limits`                          | 更新组织或项目额度                 |
| `POST`       | `/api/platform/console/limits/request`                  | 提交额度申请                       |
| `GET / POST` | `/api/platform/console/organization`                    | 读取或更新组织资料                 |
| `GET`        | `/api/platform/console/projects/settings?projectId=...` | 项目资料与部署区域                 |
| `POST`       | `/api/platform/console/projects/update`                 | 更新项目名称和描述                 |
| `GET`        | `/api/platform/console/usage?days=30&projectId=...`     | 指定范围的真实用量                 |
| `GET`        | `/api/platform/console/billing`                         | 账单资料和支付接入状态             |
| `POST`       | `/api/platform/console/billing/profile`                 | 更新账单资料                       |
| `GET`        | `/api/platform/console/security`                        | 当前账户的会话与双重验证状态       |
| `POST`       | `/api/platform/console/security/revoke-session`         | 撤销本人其他会话                   |
| `GET`        | `/api/platform/console/admin/limit-requests`            | 管理员查看最近 200 条额度申请      |
| `POST`       | `/api/platform/console/admin/limit-requests/review`     | 管理员审核申请                     |

额度更新示例：

```json
{
  "scope": "project",
  "projectId": "your-project-id",
  "requestsPerMinute": 20,
  "monthlyCharacters": 200000
}
```

组织额度使用 `scope: "organization"` 且不传 `projectId`。额度申请在相同结构上添加 `reason`；审批请求使用 `{ "id": "request-id", "decision": "approved", "reason": "审核意见" }`，`decision` 也可为 `rejected`。

接口会拒绝越权、未知字段、错误项目、无效整数、超过长度的输入和重复审批。错误状态包括 `400`（输入错误）、`403`（权限或部署上限）、`404`（资源不存在或不可访问）、`409`（状态冲突）和 `429`（额度或频率限制）。页面显示错误后保留可操作的重试入口，不把失败提示为成功。
