dicts、fields、subjects、composite-indexes、subject-schemas 各模块实体与 DTO 的字段含义与作用

实体与接口字段说明

本文档描述 dicts、fields、subjects、composite-indexes、subject-schemas 各模块中实体与 DTO 的字段含义与作用。

1. Dicts（字典）

字典为树形结构：一个文档表示一个节点。根节点（parentId 为空）表示「字典类型」（如 status、fieldType）；子节点表示该类型下的选项。Field 的 refType=dict 时，refId 指向字典根节点 _id，选项为该根及其子节点。

字段	类型	必填	说明
code	string	是	节点标识。根节点即字典类型（如 `status`、`fieldType`、`refType`），子节点即选项的 value。
name	string	是	显示名称。根为类型名（如「状态」），子节点为选项的 label（如「启用」「禁用」）。
description	string	否	描述说明。
sort	number	否	排序值，越小越靠前，默认 0。
parentId	ObjectId (ref: Dict)	否	父节点 `_id`，空或不存在表示根节点。

虚拟字段

虚拟字段	说明
parentIdValue	通过 `parentId` 关联的父 Dict 文档。

集合名：dicts

2. Fields（字段）

字段描述「主体（Subject）」下的列定义，包括类型、是否必填、索引与引用配置。fieldTypeId、refTypeId 为字典项 _id（来自字典 fieldType / refType）。

字段	类型	必填	说明
subjectId	ObjectId (ref: Subject)	是	所属主体（表）。
name	string	是	字段名称（界面展示）。
code	string	是	字段英文标识，对应动态表文档中的键名。
description	string	否	字段描述、占位提示等。
sort	number	否	表单内展示顺序，越小越靠前，默认 0。
fieldTypeId	ObjectId (ref: Dict)	是	字段类型，为字典 `fieldType` 下某一项的 `_id`（如 string、number、select、boolean、date 等）。
refTypeId	ObjectId (ref: Dict)	否	选项来源类型，为字典 `refType` 下项的 `_id`（dict 或 subject）。仅当 fieldType 为 select 时有效。
refId	ObjectId	否	选项来源 ID：字典根 `_id` 或 Subject `_id`。仅 fieldType=select 时有效。
refFieldId	ObjectId (ref: Field)	否	仅 refType=subject 时有效：用该 Subject 的哪个字段作为选项展示（如用分类的 name 显示）。
required	boolean	否	是否必填，默认 false。
index	0 / 1 / -1	否	单字段索引方向：0 无索引，1 升序，-1 降序（B-tree，用于排序/查询），默认 0。
unique	boolean	否	是否参与唯一约束（单字段或复合索引中的一环），默认 false。
text	boolean	否	是否参与该主体上的全文索引（`$text` 检索），默认 false。
parentId	ObjectId (ref: Field)	否	父级字段 `_id`；指定后当前字段为该父字段的嵌套字段，`subjectId` 继承自父字段。

虚拟字段

虚拟字段	说明
fieldType	通过 `fieldTypeId` 关联的 Dict（字段类型）。
refType	通过 `refTypeId` 关联的 Dict（引用类型）。
subject	通过 `subjectId` 关联的 Subject。
refSubject	通过 `refId` 关联的 Subject（refType=subject 时）。
refDict	通过 `refId` 关联的 Dict（refType=dict 时）。
refField	通过 `refFieldId` 关联的 Field（选项展示字段）。
parent	通过 `parentId` 关联的父 Field。

集合名：fields

3. Subjects（主体/表）

Subject 表示一张「逻辑表」的元数据，对应动态集合的命名与展示。实际列定义在 Fields 中，复合索引可在 Subject 上配置或存储在 composite_indexes 集合。

字段	类型	必填	说明
name	string	是	主体中文名称（界面显示）。
code	string	是	主体唯一英文标识（代码、集合名等引用），如 `device`、`category`。
sort	number	否	排序值，列表展示时使用。
description	string	否	描述信息。

集合名：默认由 Mongoose 生成（subjects）。
索引：name、code 各有唯一索引；(name, code) 复合唯一索引。

4. Composite-indexes（复合索引）

复合索引属于某一 Subject，由 2～10 个字段组成，可配置唯一、稀疏、后台构建、TTL 等。字段通过 Field._id（fieldId）引用。

4.1 CompositeIndex 实体

字段	类型	必填	说明
subjectId	ObjectId (ref: Subject)	是	所属主体（Subject）。
name	string	否	索引名称，最大 128 字符；留空则由 MongoDB 自动生成。
fields	CompositeIndexField[]	是	索引字段列表，至少 2 个、最多 10 个元素。
description	string	否	索引描述，最大 256 字符。
unique	boolean	否	是否唯一索引（索引键不重复），默认 false。
sparse	boolean	否	是否稀疏索引（仅包含含该索引键的文档），默认 false。
background	boolean	否	是否后台创建索引，默认 true。
expireAfterSeconds	number	否	TTL：文档在指定秒数后自动删除，可选。

4.2 CompositeIndexField（复合索引中的一项）

字段	类型	必填	说明
fieldId	ObjectId (ref: Field)	是	参与索引的字段，对应 Field 的 `_id`。
indexDirection	1 / -1	否	排序方向：1 升序，-1 降序，默认 1。

集合名：由 Mongoose 默认（compositeindexes）。

5. Subject-schemas（主体表结构接口）

Subject-schemas 提供「整张表」的只读视图：主体信息 + 字段列表（含类型、引用等关联）+ 单字段索引汇总 + 复合索引（含字段名解析）。用于管理端展示表结构、表单生成、索引一览等。

5.1 SubjectSchemaDto（单张表完整结构）

字段	类型	说明
_id	ObjectId	主体 ID。
name	string	主体名称。
code	string	主体标识。
sort	number	排序值。
description	string	描述。
createdAt	Date	创建时间。
updatedAt	Date	更新时间。
fields	FieldSchemaItem[]	该主体下所有字段（含 fieldType、refType、ref、refField 等关联）。
singleFieldIndexes	SingleFieldIndexItem[]	由各 Field 的 index/unique/text 汇总得到的单字段索引列表。
compositeIndexes	CompositeIndexItem[]	来自 composite_indexes 集合的复合索引，且每条索引的字段已解析为 code/name。

5.2 FieldSchemaItem（表结构中的字段项）

在 Field 实体字段基础上，增加以下关联（由聚合查询填充）：

字段	类型	说明
fieldType	`{ _id, code, name }`	字段类型字典项。
refType	`{ _id, code, name }`	引用类型字典项（dict/subject）。
ref	`{ _id, code, name }`	选项来源：字典或 Subject。
refField	`{ _id, name, code }`	选项展示用字段（refType=subject 时）。

其余与 Field 实体一致（如 subjectId、name、code、fieldTypeId、refTypeId、refId、refFieldId、required、index、unique、text、parentId、sort、description 等）。

5.3 SingleFieldIndexItem（单字段索引项）

字段	类型	说明
fieldId	ObjectId	字段 ID。
fieldCode	string	字段英文标识。
fieldName	string	字段名称。
direction	1 / -1	索引方向（1 升序，-1 降序；全文索引视为 1）。
unique	boolean	是否唯一。
text	boolean	是否参与全文索引。

5.4 CompositeIndexFieldItem（复合索引中的字段项，含展示信息）

字段	类型	说明
fieldId	ObjectId	字段 ID。
fieldCode	string	字段英文标识（解析自 Field）。
fieldName	string	字段名称（解析自 Field）。
indexDirection	1 / -1	该字段在复合索引中的排序方向。

5.5 CompositeIndexItem（表结构中的复合索引项）

字段	类型	说明
_id	ObjectId	复合索引文档 ID。
name	string	索引名称。
fields	CompositeIndexFieldItem[]	参与索引的字段列表（含 code/name 解析）。
description	string	描述。
unique	boolean	是否唯一索引。
sparse	boolean	是否稀疏索引。
background	boolean	是否后台创建。
expireAfterSeconds	number	TTL 秒数（若有）。

关系小结

Subject：一张逻辑表；其 Fields 定义列与单字段索引（index/unique/text）。
CompositeIndex：属于某 Subject，由多个 Field（通过 fieldId）组成复合索引。
Dict：树形字典，根为类型（如 status、fieldType、refType），子为选项；Field 的 fieldTypeId/refTypeId 指向 Dict，refId 在 select 类型下指向 Dict 根或 Subject。
Subject-schemas：按 Subject 聚合 Field + Dict + CompositeIndex，输出整张表的字段与索引信息，供前端或下游使用。

实体与接口字段说明

On this page