配置字典与值集字段模型#

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

本页是数据字典（data-dictionary）与值集（value-set）两个资源树共 8 个资源族操作页复用的字段正本。字段来自当前后端 DTO、Mapper、实体与序列化配置；"可空未知"表示源码没有足以证明数据库值或成功响应一定非空的约束。时间字段均按 UTC epoch 秒传输，响应顶层 timestamp 例外为 epoch 毫秒，详见数据类型与时间。

8 个资源族：data-dictionary（数据字典项）、data-dictionary-type（字典类型）、data-dictionary-map（字典映射）、data-dictionary-table（字典表）、value-set（值集项）、value-set-type（值集类型）、value-set-map（值集映射）、value-set-table（值集表）。四对"项/类型 + map/table"结构同构：type 是 code→名称 的目录，item/mapper/table 挂在类型之下。

查询控制字段#

所有 list、page 和 listCache 都接收 JSON object。各 *ListRequestDTO 还声明了审计字段和时间范围过滤，但当前 Web 只发送资源筛选字段与排序；App 不应把未列出的动态查询能力当作稳定合同。

JSON 路径	JSON 类型	必填	可空	默认值/范围	语义与证据
sqlQueryCriteriaLike	boolean	否	是	true	false 时字符串按精确匹配；各 *ListRequestDTO 与 Mapper selectWhere
sqlQueryCriteria	object<string,string>	否	否	{}	Mapper 已观察值为字段级 eq；deleteTime=skip 可包含已逻辑删除行；不要发送任意 SQL
sqlQuerySorter.field	string	否	是	无	仅 Mapper 显式白名单字段生效；未知字段落入默认排序（见各族说明）
sqlQuerySorter.order	string	否	是	非 ascend 一律按降序分支	当前 Web 只发送 ascend 或省略；省略 order 时命中"非 ascend"降序分支
sqlQueryLimit	number	否	是	list 端点 null→100；listCache 端点 null→10000；两者均钳制 1..100000	es-center-server-core/src/main/java/com/es/center/server/core/query/QueryLimits.java:16-28；limit 由 Mapper 以参数拼接
current/pageSize	number	仅 page	未承诺	省略时 Java primitive 为 0	*PageRequestDTO.java:19-24（Java long）；本组 page Controller 未调用 normalizePageSize，服务端边界未闭合；当前 Web 发送 current≥1、pageSize=10
tenantId/tenantIds[]	string、array	否	是	无	服务端作用域字段：page 会被 Controller 强制覆盖为当前认证租户；listCache 中 tenantId 反而是合同的一部分（见下）；其余端点请求传入只会叠加过滤条件

字符串筛选默认是包含匹配；sqlQueryCriteriaLike=false 或对应 sqlQueryCriteria.<field>="eq" 才是精确匹配。范围结束值在 Mapper 中使用 <，因此是左闭右开。所有表都有一个显式的 delete_time is null 条件（sqlQueryCriteria.deleteTime="skip" 可解除），与实体 @TableLogic 逻辑删除一致。

数据字典（data-dictionary）#

查询筛选字段：dataDictionaryId、dataDictionaryTypeCode、dataDictionaryCode、value、name、createdUsername、lastModifiedUsername（string），sort、revision（number），审计时间范围与通用查询控制字段。证据：gt-common-configuration-dto/src/main/java/tech/gt/configuration/dto/DataDictionaryListRequestDTO.java:23-88。

data[] 或详情 data 的字典项对象字段为：dataDictionaryId、dataDictionaryTypeCode、dataDictionaryCode、value、name（string，可空未知），sort、revision（number，可空未知），createdTime、lastModifiedTime、deleteTime（number，UTC epoch 秒，可空未知），以及 createdUsername、lastModifiedUsername、tenantId（string，可空未知）。证据：DataDictionaryListResponseDTO.java:20-65、DataDictionaryGetByIdResponseDTO.java:20-66、gt-common-configuration-common/src/main/resources/mapper/postgresql/gt-common-configuration/DataDictionaryMapper.xml:4-18 selectColumns。

排序白名单：dataDictionaryId、dataDictionaryTypeCode、dataDictionaryCode、value、name、sort、createdUsername、createdTime、lastModifiedUsername、lastModifiedTime、deleteTime、revision、tenantId；未命中白名单时默认 order by t.sort_ asc（DataDictionaryMapper.xml selectListResponseDTO）。

写入字段#

JSON 路径	JSON 类型	保存必填	更新必填	可空	长度/语义
dataDictionaryId	string	否	是	保存可省略	≤32；Web 保存时生成 21 位 nanoid（去除 -_）；省略时服务端按 ASSIGN_UUID 生成
dataDictionaryTypeCode	string	是	是	否	1..128；重复检查键之一
dataDictionaryCode	string	是	是	否	1..128；重复检查键之一
value	string	否	否	是	≤1024
name	string	否	否	是	≤256
sort	number	否	否	是	Long；未发送时 updateById 写 NULL
revision	number	否	否	是	Long；普通字段，无乐观锁校验；当前 Web 更新不发送 → 被写 NULL

证据：DataDictionarySaveRequestDTO.java:22-57、DataDictionaryUpdateRequestDTO.java:22-58；gt-common-configuration-common/src/main/java/tech/gt/configuration/entity/DataDictionary.java:20-486（@TableId ASSIGN_UUID、@TableLogic delete_time、created_*/last_modified_* 与 tenant_id 由 MetaObjectHandler 填充，es-center-server-main-service/src/main/java/com/es/center/server/config/MybatisPlusConfig.java:41-59）。

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

查询筛选字段：dataDictionaryTypeId、dataDictionaryTypeCode、name、createdUsername、lastModifiedUsername（string），revision（number）及通用查询控制字段。返回对象为 dataDictionaryTypeId、dataDictionaryTypeCode、name、审计用户名（string），createdTime、lastModifiedTime、deleteTime（UTC epoch 秒）与 revision（number）；可空性未由 DTO 单独保证。证据：DataDictionaryTypeListRequestDTO.java:23-79、DataDictionaryTypeListResponseDTO.java:20-56、DataDictionaryTypeMapper.xml。

排序白名单：dataDictionaryTypeId、dataDictionaryTypeCode、name、审计用户名与时间、deleteTime、revision、tenantId；默认 order by t.created_time desc。类型没有 sort 字段。

写入字段：dataDictionaryTypeId（≤32；保存可省略、更新必填）、dataDictionaryTypeCode（必填 1..128，重复检查键）、name（≤256）、revision（Long）。其余语义同数据字典写入字段。证据：DataDictionaryTypeSaveRequestDTO.java:22-45、DataDictionaryTypeUpdateRequestDTO.java:22-46。

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

在字典项之下按 key 挂映射：查询筛选字段另含 dataDictionaryMapId、key；返回对象为 dataDictionaryMapId、dataDictionaryTypeCode、dataDictionaryCode、key、value、name、sort 加审计与租户字段。排序白名单同字典项并含 key；默认 order by t.sort_ asc。证据：DataDictionaryMapListRequestDTO.java:23-91、DataDictionaryMapListResponseDTO.java:20-68、DataDictionaryMapMapper.xml。

写入字段：dataDictionaryMapId（≤32；保存可省略、更新必填）、dataDictionaryTypeCode（必填）、dataDictionaryCode（必填）、key（必填 1..128，重复检查键之一）、value（≤1024）、name（≤256）、sort、revision。证据：DataDictionaryMapSaveRequestDTO.java:22-62、DataDictionaryMapUpdateRequestDTO.java:22-63。

数据字典表（data-dictionary-table）#

按 row/key 组织的二维表：查询筛选字段另含 dataDictionaryTableId、row、key；返回对象为 dataDictionaryTableId、dataDictionaryTypeCode、dataDictionaryCode、row、key、value、name、sort 加审计与租户字段。排序白名单同字典项并含 row、key；默认 order by t.sort_ asc。证据：DataDictionaryTableListRequestDTO.java:23-94、DataDictionaryTableListResponseDTO.java:20-71、DataDictionaryTableMapper.xml。

写入字段：dataDictionaryTableId（≤32；保存可省略、更新必填）、dataDictionaryTypeCode（必填）、dataDictionaryCode（必填）、row（必填 1..128）、key（必填 1..128）、value（≤1024）、name（≤256）、sort、revision；重复检查键为 typeCode+code+row+key。证据：DataDictionaryTableSaveRequestDTO.java:22-67、DataDictionaryTableUpdateRequestDTO.java:22-68。

值集（value-set）#

查询筛选字段：valueSetId、valueSetTypeCode、value、createdUsername、lastModifiedUsername（string），sort、revision（number）及通用查询控制字段。返回对象为 valueSetId、valueSetTypeCode、value（string）、sort、revision（number）加审计与租户字段；值集项没有 name。排序白名单：valueSetId、valueSetTypeCode、value、sort、审计字段、revision、tenantId；默认 order by t.sort_ asc。证据：ValueSetListRequestDTO.java:23-82、ValueSetListResponseDTO.java:20-59、ValueSetMapper.xml。

写入字段：valueSetId（≤32；保存可省略、更新必填）、valueSetTypeCode（必填 1..128）、value（必填 1..1024，重复检查键之一）、sort、revision。证据：ValueSetSaveRequestDTO.java:22-49、ValueSetUpdateRequestDTO.java:22-50。

值集类型（value-set-type）#

查询筛选字段：valueSetTypeId、valueSetTypeCode、name、审计用户名（string），revision 及通用查询控制字段。返回对象为 valueSetTypeId、valueSetTypeCode、name、审计字段与 revision。排序白名单同字典类型；默认 order by t.created_time desc。证据：ValueSetTypeListRequestDTO.java:23-79、ValueSetTypeListResponseDTO.java:20-56、ValueSetTypeMapper.xml。

写入字段：valueSetTypeId（≤32；保存可省略、更新必填）、valueSetTypeCode（必填 1..128，重复检查键）、name（≤256）、revision。证据：ValueSetTypeSaveRequestDTO.java:22-45、ValueSetTypeUpdateRequestDTO.java:22-46。

值集映射（value-set-map）#

查询筛选字段另含 valueSetMapId、key；返回对象为 valueSetMapId、valueSetTypeCode、key、value、sort 加审计与租户字段；没有 name。排序白名单含 key、value；默认 order by t.sort_ asc。证据：ValueSetMapListRequestDTO.java:23-85、ValueSetMapListResponseDTO.java:20-62、ValueSetMapMapper.xml。

写入字段：valueSetMapId（≤32）、valueSetTypeCode（必填）、key（必填 1..128）、value（必填 1..1024）、sort、revision；重复检查键为 typeCode+key。证据：ValueSetMapSaveRequestDTO.java:22-54、ValueSetMapUpdateRequestDTO.java:22-55。

值集表（value-set-table）#

查询筛选字段另含 valueSetTableId、row、key；返回对象为 valueSetTableId、valueSetTypeCode、row、key、value、sort 加审计与租户字段；没有 name。排序白名单含 row、key；默认 order by t.sort_ asc。证据：ValueSetTableListRequestDTO.java:23-88、ValueSetTableListResponseDTO.java:20-65、ValueSetTableMapper.xml。

写入字段：valueSetTableId（≤32）、valueSetTypeCode（必填）、row（必填 1..128）、key（必填 1..128）、value（必填 1..1024）、sort、revision；重复检查键为 typeCode+row+key。证据：ValueSetTableSaveRequestDTO.java:22-59、ValueSetTableUpdateRequestDTO.java:22-60。

listCache 的租户合并语义#

data-dictionary/listCache 与 data-dictionary-type/listCache（Plus Controller）的既定合同：请求 tenantId 为空或 default 时仅读 default 公共空间；为业务租户时分别读取业务租户与 default 两份结果，业务在前、default 兜底，按稳定领域键（字典项为 typeCode+code，类型为 typeCode）去重，合并上限 20000。单租户读取默认上限 10000（钳制 1..100000）。读取在租户豁免作用域执行并以 DTO 显式租户寻址缓存条目：字典项缓存 TTL 10 分钟（DataDictionaryService.java:80-86），字典类型缓存 TTL 10 秒（DataDictionaryTypeService.java:78-84）；配置写入不主动失效这些缓存。证据：DataDictionaryPlusController.java:54-97、DataDictionaryTypePlusController.java:54-96、es-center-server-main-service/src/main/java/com/es/center/server/configuration/function/DictionaryDefaultFallbackSupport.java:22-44。

证据基线#

前端：HEAD 7fe6dd1052aba67b37ed7cf3420ece767585b698。后端：HEAD 89bd222cd1430477ea989c77f5d5a0c6b5f5d13f。核验日期：2026-09-12。所读 Controller、DTO、Service、Mapper 与实体均与各自 HEAD 一致；inventory 冻结基线（Web aa138d8、services a3e783d2）之后两仓各有新增提交，本票证据按当前 HEAD 读取（指纹审计见 handoffs/15.json）。

结论	状态	仓库/基线	路径、符号及定位	内容指纹（脏文件）
通用查询控制与排序语义	已源码核验	services 89bd222c	es-center-server-core/src/main/java/com/es/center/server/core/query/QueryLimits.java:16-28；8 个 *Mapper.xml 的 selectWhere/selectListResponseDTO	与 HEAD 一致
分页字段与租户覆盖	已源码核验	services 89bd222c	*PageRequestDTO.java:19-24；各 Controller page 方法的 setTenantId(TenantIdSupplierExecutor.execute())	与 HEAD 一致
字段、校验与实体填充	已源码核验	services 89bd222c	8 组 *SaveRequestDTO/*UpdateRequestDTO；entity/*.java 的 @TableId/@TableLogic/FieldFill；MybatisPlusConfig.java:41-59,72-88	与 HEAD 一致
时间与 BigDecimal 序列化	已源码核验	services 89bd222c	es-center-server-main-service/src/main/java/com/es/center/server/config/JsonFormatConfig.java:20-113	与 HEAD 一致
listCache 合并语义	已源码核验	services 89bd222c	DataDictionaryPlusController.java:54-97、DataDictionaryTypePlusController.java:54-96、DictionaryDefaultFallbackSupport.java:22-44	与 HEAD 一致
清单归属	已重新比对	inventory	.scratch/institutional-app-api-docs/inventory/operations.json	SHA-256 b5cce137b4fc602840fdbe74c99d90667b3e581815bddc709e263ffcc64e00f9（工作树仅既有格式化漂移，本票未修改）
真实部署联调	未执行	—	未发送请求、未连接数据库/缓存/JMS	—