上报缺失翻译#

验证状态：已源码核验、未联调；适用基线：Web 7fe6dd10、services 89bd222c；核验日期：2026-09-12

用途与 App 场景#

匿名上报前端缺失的 i18n 词条（key→value 草稿），供运营侧在翻译管理中补充。本操作是匿名可达端点（permitAll），只落 default 租户的待处理队列，不直接产生正式词条。App 接入时不应把它当作翻译读取或写入通道。

Web 使用位置#

协议身份#

前置条件与权限#

无需登录态（permitAll 放行，SecurityConfig.java:526-527 应用于 yaml 清单）。服务端忽略请求中的 tenantId：注释明示「匿名缺失上报只允许落 default 租户，调用方传来的任何 tenant 参数一律忽略」，强制 DEFAULT_TENANT_ID="default"（TranslationPlusController.java:29-30,64）。language 经服务端 languageMap 配置映射后再入队（TranslationPlusController.java:61-63）。

输入#

输出、应答或事件#

副作用链：enqueueMissing 写入内存队列（TranslationScheduling.java:80，Semaphore 容量 10000），由 TranslationScheduling 定时任务批量入库（每轮最多 20 批、最长等待 6 秒，TranslationScheduling.java:39-43,134）。

完成判据#

status=200 && data===true 表示服务端已受理入队（队列满员 10000 时例外：词条被静默丢弃而 ACK 不变，见错误与边界）；词条何时落库、何时进入翻译视图均为异步，本操作不提供查询。Web 侧以该 ACK 为准删除本地快照（flush 脚本 :57-75），ACK 判定还要求 body 经 zod 校验为 {status:number, data:boolean}（translationPlusApi.ts:50-51）。

示例#

按已核验契约构造的示例，不是真实联调记录。

请求：POST /main-service/system-api/configuration/translation/saveMissing?language=zh-CN&namespace=translation&tenantId=default

1{
2  "Missing key": "Missing key"
3}

成功响应：

1{
2  "timestamp": 1789142400000,
3  "status": 200,
4  "error": null,
5  "localizedError": null,
6  "path": null,
7  "extraData": {},
8  "data": true
9}

超限失败（HTTP 400，键数 >500）：

1{
2  "timestamp": 1789142400000,
3  "status": 400,
4  "error": "At most 500 missing translations per request.",
5  "localizedError": null,
6  "path": "/main-service/system-api/configuration/translation/saveMissing",
7  "extraData": null,
8  "data": null
9}

错误与边界#

请求校验失败（@NotBlank）；键数超限见上方 400 示例。Web 侧 10 秒超时（translationPlusApi.ts:14 SAVE_MISSING_TIMEOUT_MS），失败静默保留本地快照、不升级为全局页面错误（translationPlusApi.ts:33 注释与 flush 脚本 to() 包裹）。匿名端点无鉴权限流的源码证据；滥用上限仅受队列容量 10000 约束，满员后 enqueue 静默丢弃新词条（remainingCapacity.tryAcquire() 失败即返回，TranslationScheduling.java:103），调用方仍收到 200 && data=true——该 ACK 在满员场景下不代表词条已入队。

调用关系与资源清理#

前端把待上报词条持久化在本地快照（missing-translation-report-store），30 秒周期 flush；只有收到受理 ACK 才删除对应快照。无服务端订阅资源。

已知缺口#

入队满员（10000）时的行为已由源码核验为静默丢弃（见错误与边界）；定时批量的落库时延在目标环境未联调核验。 仅完成双仓静态源码核验，未执行真实 HTTP 联调。

验证状态与依据#