# 星线支持中心技术概览

支持中心由静态帮助文章、浏览器搜索、地区选择和回电申请组成。文章阅读不要求登录；回电申请另由独立接收服务校验并持久写入待处理队列。申请已接收不等于电话已拨出，也不承诺自动回电时间。

## 入口与内容模型

公开入口为 [星线支持](https://support.thestarline.cn/)。前端使用 HTML、CSS 和原生 ES modules，构建脚本从 `data.mjs` 与模板生成首页、搜索页、联系页、产品页、文章页和真正的 404 页面。

产品目录当前包含 Account、Cloud、Pay、Email 和 App。文章记录包括 `slug`、`product`、标题、摘要、关键词和分节正文；分节可以包含段落和步骤。新增文章需要同时核对 slug 唯一性、产品归属、链接和内容准确性。支持文章说明如何使用产品，不能作为其他产品能力已经验收的替代证据。

搜索在浏览器执行，将文本 NFKC 规范化、转为小写并按空白及常见中英文标点分词；可先按产品筛选。精确关键词、标题、关键词部分匹配、产品名、摘要和正文分别计分，所有查询词都需要获得正分才进入结果，再按总分排序。当前没有服务端全文搜索、语义向量检索或根据账号资料个性化排序。

## 地区选择与联系行为

地区数据覆盖 250 个国家或地区，中国选项继续提供 34 个省级选项。地区偏好使用 `starline-support-region-v1` 保存到本机。它用于联系流程展示，不能证明用户地理位置、产品授权地域或已取得特定国家经营许可。

更改地区后，申请表需要以当前选择重新校验。地区、联系语言和手机号是不同字段，不能仅根据国家码猜测用户希望使用的语言。当前回电语言只允许 `zh`、`en`。公开企业联系入口由站点提供，技术文档不复制联系人资料或二维码内容。

## 回电申请接口

前端向同源 `POST /api/callback-requests` 提交 JSON，不向第三方表单平台传输。服务端使用 Python 标准库实现接收和队列，不属于静态构建产物。

| 字段 | 类型与约束 |
| --- | --- |
| `requestId` | 标准 UUID；用作重试去重标识 |
| `phone` | 国际格式字符串，`+` 后为 7–15 位数字，首位不能为 0 |
| `region` | 白名单国家或地区 `code`；`CN` 必须含已知 `province`，其他地区不能带该字段 |
| `language` | `zh` 或 `en` |
| `consent` | 必须为布尔值 `true` |
| `website` | 必须为空字符串的诱捕字段 |

服务端拒绝缺失或额外字段、重复 JSON 键、非有限数值、无效地区及未经同意的提交。请求体最多 4096 字节，校验精确 Origin、内容类型、方法与读取时限。前端只有在 HTTP 成功、响应 `status` 为 `received` 且 `requestId` 与本次请求一致时，才显示成功。

## 持久化、幂等和失败

有效申请以 JSONL 写入私有队列，记录申请 ID、联系方式、地区、语言、UTC 创建时间、`pending` 状态和同意标志。目录及文件采用受限权限；日志刻意省略请求路径、请求头、申请内容和异常值。队列文件不进入静态站点，也不提供公开读取或管理接口。

写入过程使用线程锁及文件锁，先读取并验证既有队列，写入后同步文件与必要的目录状态，完成持久化才返回成功。同一 ID 与同一有效载荷重试返回 200；首次写入返回 201；相同 ID 携带不同内容返回 409。网络超时后应复用原 ID确认结果，不能通过不断生成 ID规避重试约束。

默认同一来源 15 分钟最多接受 5 份新申请，重复申请不重复计数；限流状态保存在进程内，重启会重置该窗口。超限返回 429 和 `Retry-After`，格式错误为 400，Origin 不符为 403，请求过大为 413，不支持的内容类型为 415。队列损坏或写入不可用时保留原文件并返回 503，不能先显示成功再丢弃申请。

## 扩展与验证边界

仅部署静态文件不会自动启用回电申请，必须同时连接接收服务与受保护的持久存储。当前服务只承担接收，不包含自动拨号、客服派单后台、公开查询进度或通话录音。增加后续处理时应保留申请 ID和状态更新审计，并按正式隐私规则处理联系方式。

资料依据 2026-10-23 源码整理。部署仍需验证同源接收路由、持久化、重试去重、限流、损坏队列和前端成功判断；后续人工联系需要单独确认。产品技术边界见 [Email](https://document.thestarline.cn/email/)、[Cloud](https://document.thestarline.cn/cloud/) 与 [Pay](https://document.thestarline.cn/pay/)，政策见 [隐私中心](https://document.thestarline.cn/privacy/)。

## 源码依据

主要文件为 `support/data.mjs`、`search.mjs`、`templates.mjs`、`build.mjs`、`app.mjs`、`regions.mjs`、`region-picker.mjs`、`callback-form.mjs` 和 `server/callback_server.py`。公开内容构建与申请接收服务须分别检查。