晰联 CELRYN · 通信数据，清晰可循

管理会话与 API Key 白名单

以下控制台接口仅接受登录 Cookie 会话，API Key 不能管理账户。浏览器通过同源 /api 前缀访问，写操作校验 Origin。白名单仅约束本租户 API Key 的数据查询，不影响管理会话，避免把账户锁在控制台之外。

在安全与异常每行填写一个 IPv4、IPv6 或 CIDR，最多 100 条；空数组表示不限来源。服务端只信任显式配置的代理，不采信任意 X-Forwarded-For。

方法 / 路径	请求或响应 data
`GET /console/security`	api_key_ip_allowlist: string[]；trusted_proxy_configured: boolean。
`PATCH /console/security`	请求 {api_key_ip_allowlist: string[]}；响应为服务端规范化后的相同配置。
`GET /console/alerts`	items: {id,type,message,count,created_at,last_seen_at}[]，仅当前租户。

同源浏览器会话 / 合成配置示例

fetch('/api/console/security', {
  method: 'PATCH', credentials: 'same-origin',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({api_key_ip_allowlist: ['203.0.113.10/32']})
})

异常包括 ip_denied、key_rejected、rate_limited、quota_exceeded，按租户、类型与 UTC 日期去重聚合。count 是发生次数，首次与最近发生时间分别保留。无异常返回空数组；站内记录不代表发送了邮件或外部通知。

报告与复核数据问题

从数据工具的“报告数据问题”进入工单，类别可预填。地址只携带类别，参考记录与详情通过请求体提交；不要提交密钥、密码、Webhook secret 或原始联系人资料。

方法 / 字段	说明
`POST /console/data-reports`	请求 {category,summary,detail,reference?}；返回 {item}。
`category`	number / operator / range / currency / exchange_rate / other。
`summary / detail / reference`	必填摘要最多 200 字符；必填详情最多 5000 字符；可选参考 ID 最多 500 字符。
`GET /console/data-reports`	{items}，仅当前租户工单；无工单为空数组。
`GET /console/data-reports/:id`	{item,updates:[{id,kind,detail,created_at}]}
`POST /console/data-reports/:id/updates`	body {detail} → {item}
`POST /console/data-reports/:id/reopen`	body {detail} → {item}
`item`	id、category、summary、detail、reference、status、review_note、created_at、updated_at；另含可空的 dataset_version、entity_id、request_id、resolution_kind、fix_version、verification。
`status`	open 待受理；reviewing 复核中；resolved 已解决；rejected 已驳回。

复核人员使用服务器本地 maintenance CLI 更新状态与 review_note，处理过程留有审计；不开放公开管理员复核接口。提交成功仅表示已留存问题，不能宣称数据已修复，也不承诺未约定的处理时限。

提交工单可携带数据版本、记录 ID 与请求 ID，查询号码不会加入地址或自动保留。未关闭工单可追加信息；已解决或驳回的工单可说明原因重新打开。关闭结果区分 fixed、explained、no_change；只有 fixed 才表示修复，必须同时列出已发布 fix_version 与 verification 复验依据。

质量报告的范围

数据质量概览调用 GET /console/data-quality，返回被检查版本 dataset_version、检查时间 checked_at、checks 与 limitations。每项检查包含 id、label、status、affected_count、description。

状态	含义
`pass`	已执行的规则检查通过，不等于真实世界准确率为 100%。
`warning`	存在需复核的差异；affected_count 为涉及记录数。
`not_checked`	缺少数据或检查条件，不能推断为无效或通过。

结果按目录内容、版本和参考数据缓存并持久化；页面刷新读取报告，目录变更或本地维护命令可触发重算。checked_at 与目录导入时间、来源发布时间是不同时间。

这是运营商网络声明与编号、地区、币种参考数据的规则交叉检查，部分参考源可能相同；未接入商业多源核验或运营商联网验证。不会证明单号携转、活跃性、可达性或当前运营商，也不核验外部实时报价。演示目录保持 demo 标识；详细限制以返回的 limitations 为准。

响应与错误

成功统一返回{code:0,data,meta}。格式错误返回 400，未登录或会话失效返回 401，跨站写请求拒绝返回 403，服务不可用时保留错误状态。错误体含 code、message、request_id；失败提交保留表单输入供修正或重试，不生成虚假成功记录。