配置与翻译域总览#

验证状态：已源码核验、未联调；适用基线：源码归纳 @ 2026-09-14。本页为领域页（原 68 个逐端点 CRUD 正本页 + 域内字段正本已收拢至此，验证状态随收拢继承；纯 CRUD 行为不复述）。

数据字典四族、值集四族与翻译词条的维护入口——data-service configuration 模块的枚举主数据域。四对「项/类型 + map/table」结构同构：type 是 code→名称 的目录，条目/映射/表挂在类型之下。端点全量事实（参数、请求/响应字段、错误码、权限点）不复述，一律见：

• 端点清单：清单层 · configuration（9 资源 88 端点，按资源分节）
• 业务语义：配置业务
• 在线调试：Swagger 视图 · 配置

Web 管理端对各族 page 做无限滚动加载（pageSize=10，翻页结束判据 extraData.current >= extraData.pages）；list 主要用于 XLSX 导出取数（Web 发送 sqlQueryLimit: 100000，服务端钳制同一上限）；写操作成功后列表页 reload 回第一页。新增主键 id：当前 Web 在客户端生成 21 位 nanoid（去除 -_）后提交；省略时服务端按 ASSIGN_UUID 生成。写/导入操作没有幂等键，超时后须先读取资源状态再决定是否重试。删除均为逻辑删除（写 delete_time）。资源表受 MyBatis 租户拦截器按当前认证租户约束，请求中的租户筛选字段不能代替空间切换（认证与空间）。

query-controls 通用查询控制字段#

各族 list/page/listCache 共用的查询控制约定（字段级形态见 Swagger；此处只留行为语义）：

• sqlQueryLimit：list 端点省略默认 100、listCache 端点省略默认 10000，均钳制 1..100000（QueryLimits.normalizeSqlQueryLimit）。
• 字符串筛选默认包含匹配；sqlQueryCriteriaLike=false 或 sqlQueryCriteria.<field>="eq" 才是精确匹配；范围结束值在 Mapper 中为左闭右开（<）。
• sqlQuerySorter.field 仅 Mapper 显式白名单字段生效，未命中的字段落入各族默认排序；order 非 ascend 一律走降序分支。
• 所有表都有显式 delete_time is null 条件（sqlQueryCriteria.deleteTime="skip" 可解除）。
• page 的 tenantId 会被 Controller 强制覆盖为当前认证租户；listCache 的 tenantId 反而是合同的一部分（见 data-dictionary 缓存读取）。
• page 的 current/pageSize 为 Java primitive（省略为 0），本组 Controller 未做边界归一化；当前 Web 发送 current≥1、pageSize=10。

data-dictionary 数据字典#

字典条目主档（重复检查键 typeCode+code）。CRUD 面：count/getById/list/page/save/updateById/removeById/removeByIds，基路径 /main-service/system-api/configuration/data-dictionary。独立子流程：异步导入、缓存读取。契约见清单层 · data-dictionary与配置业务 · data-dictionary。

data-dictionary-import-list 异步导入#

POST /main-service/system-api/configuration/data-dictionary/importList —— 把一批字典写入请求发布到 JMS 通道 data dictionary import list（租户随载荷传递，tenant-less 上下文发布）：

• HTTP status=200 && data=true 只表示 JMS 发布受理（事务后发布），不是导入成功：services 全仓没有 @JmsListener 消费该通道，JmsChannelContractTest 把它显式列为仓外消费边界——最终是否落库、以什么语义 upsert、逐行校验与失败回传、幂等与重试语义全部缺证，责任端为仓外消费方（关键缺口，本子流程不可当作完整导入合同）。
• Web 由 XLSX 可见列构造行，单元格以字符串读取后原样发送（sort 在 wire 上是字符串数字），服务端反序列化行为未联调证明；App 导入应优先发送数字类型。@Valid 标注在 List 参数上，框架是否对元素逐项级联校验未由本仓源码或测试证明；空数组也会被发布。
• Web 消费：XLSX 导入入口（configuration-data-dictionary:create 权限）；HTTP 返回后直接提示成功并 reload 列表——reload 看不到新数据不代表被拒绝，看到新数据也不代表全部行已按预期落库。

data-dictionary-list-cache 缓存读取#

POST /main-service/system-api/configuration/data-dictionary/listCache —— 读取「业务租户 + default 兜底」合并列表，供前端选择器整段加载：

• 该 Plus 入口没有 @PreAuthorize 资源权限，任意已登录用户可读；查询在租户豁免作用域执行并以请求 tenantId 显式寻址缓存（空或 default → 仅读 default 公共空间；业务租户 → 业务租户在前、default 兜底，按 typeCode+code 去重）。它不是普通 list 的别名。
• 缓存语义：带 TTL 的缓存（字典项 10 分钟，本地+远程两级），配置写入不会主动失效该缓存（模块内无 @CacheInvalidate）——写后最长 10 分钟内可能读到未刷新的合并结果。
• 合并上限 20000、单租户默认 10000 为服务端常量，超限静默截断（未联调复核）。
• Web 消费：登录后根路由按当前租户预取（500ms 节流、重试 10 次）写入全局 store；各选择器挂载时以空 body 再取；切换空间/租户触发重新拉取。

data-dictionary-type 数据字典类型#

字典类型目录（code→名称，重复检查键 typeCode；无 sort 字段，默认按创建时间倒序）。CRUD 面同字典族，基路径 /main-service/system-api/configuration/data-dictionary-type。独立子流程：缓存读取。契约见清单层 · data-dictionary-type。

data-dictionary-type-list-cache 缓存读取#

POST /main-service/system-api/configuration/data-dictionary-type/listCache —— 与 data-dictionary 缓存读取同款「业务租户 + default 合并」合同（按 typeCode 去重、合并上限 20000、任意已登录用户可读、无主动失效）；差异：字典类型缓存 TTL 为 10 秒，写后不一致窗口更短。

data-dictionary-map 数据字典映射#

字典条目下按 key 挂映射（重复检查键 typeCode+code+key）。纯 CRUD 族，无独立子流程；契约见清单层 · data-dictionary-map。

data-dictionary-table 数据字典表#

按 row/key 组织的二维表（重复检查键 typeCode+code+row+key）。CRUD 族，另有 saveOrUpdate 端点；契约见清单层 · data-dictionary-table。

value-set 值集#

与数据字典同构的另一套枚举体系：条目主档（重复检查键 typeCode+value；条目无 name 字段）。CRUD 族，契约见清单层 · value-set。

value-set-type 值集类型#

值集类型目录（重复检查键 typeCode，默认按创建时间倒序）。CRUD 族，契约见清单层 · value-set-type。

value-set-map 值集映射#

值集条目下按 key 挂映射（重复检查键 typeCode+key）。CRUD 族，契约见清单层 · value-set-map。

value-set-table 值集表#

按 row/key 组织的二维表（重复检查键 typeCode+row+key）。CRUD 族，另有 saveBatch 端点；契约见清单层 · value-set-table。

translation 翻译#

i18n 词条主档（language+namespace+key 自然键）。CRUD 面：count/getById/list/page/save/updateById/removeById/removeByIds，基路径 /main-service/system-api/configuration/translation。独立子流程：批量导入、缺失上报。契约见清单层 · translation与配置业务 · translation。

translation-import-list 批量导入#

POST /main-service/system-api/configuration/translation/importList —— XLSX 批量导入词条，「受理即返回」。与 data-dictionary 异步导入不同，本操作消费链在仓内源码闭合：发布 translation import list 通道 → TranslationListener 消费 → 逐行按 language+namespace+key 自然键查重，命中复用既有 translationId 做 upsert、未命中新建 → saveOrUpdateBatch 落库 → 触发最终翻译视图刷新：

• status=200 只表示 JMS 发布受理；落库租户来自登录态（JMS 信封绑定当前认证租户，payload 的 tenantId 置 null，消费者以信封为可信租户来源）。
• 不提供逐行成功/失败回执；校验失败在消费端以日志记录后继续或整体失败的具体行为未联调核验。
• 入队词条的批量入库节奏见配置业务 · 运行时关联（TranslationScheduling 定时任务）。

translation-save-missing 缺失上报#

POST /main-service/system-api/configuration/translation/saveMissing —— 匿名上报前端缺失的 i18n 词条（key→value 草稿），供运营侧在翻译管理中补充：

• 匿名可达（permitAll 放行，无需登录态）；只落 default 租户的待处理队列——服务端忽略请求中的 tenantId，不是翻译读取或写入通道。
• 边界：单请求键数 ≤500（超出 HTTP 400）；词条入内存队列（容量 10000），满员时被静默丢弃而 ACK 不变（200 && data=true 不代表已入队）；落库由定时任务批量完成，何时进入翻译视图不可查询。
• Web 消费：本地快照 30 秒周期 flush（每请求 ≤500 键、每轮 ≤5 请求、10 秒超时失败静默保留快照），收到受理 ACK 才删除本地快照。