字段字典与元数据

明·如归 · 宿舍管理白皮书 ｜ 第三篇 数据篇

一所学校今年要加一个"民族习惯"字段、明年要把"宿舍类型"从四类扩成六类、后年要把"健康备注"只对校医可见——每一次改动都不该找厂商改程序。如果改一个字段就得起工加价、这所学校的宿舍数据五年后就没人敢动了：旧字段不敢删（可能有历史数据）、新字段不敢加（加了导出模板全乱）、最后系统变成了一个谁也不敢碰的化石。数据篇第二章要谈的是：让一所学校的宿舍数据能长期可用的技术支点——不是"初始设计得多完美"、是"改起来有多容易"。

14.1 收掉自由填写权：字典治理

宿舍数据最常见的慢性病不是缺字段、是字段里填的东西五花八门。一个"民族"列、甲楼写全称"壮族"、乙楼写简称"壮"、丙楼打错字"戗族"——到统计的时候三类变三行、谁也不知道哪个才是对的。

治理办法不是培训填表的人（培训管不过一个学期）——是从源头收掉自由填写权：所有枚举类字段统一走数据字典。

14.1.1 字典项的标准结构

每一条字典项有五个标准列：

• 名称：给人看的中文名，比如"壮族"；
• 编码：给系统用的稳定标识、比如 Zhuang——名称可能改、编码一般不改；
• 排序号：前端下拉显示顺序（比如按人口数排、按笔画排）；
• 启用状态：字典项可以停用、不删除——历史数据里引用了停用项、值仍然能显示、只是新记录不能再选它；
• 父级编码（可选）：形成层级字典（例如"江苏省"下面挂 13 个地级市）。

这五个列一起决定了"一个字典项在系统里的完整身份"。少了任何一个都会出问题：没有编码，改名字会导致所有历史引用失效；没有启用状态，删除一个值会让旧数据报错；没有父级，地域字典会退化成扁平的一大堆。

14.1.2 哪些字段该归字典管

判据：只要一个字段的可能取值是有限、可枚举、稳定的——就该归字典管。

系统里已经归字典管的字段：

• 民族：56 个民族 + 待定；
• 政治面貌：中共党员、中共预备党员、共青团员、群众、其他民主党派；
• 学籍状态：在读、休学、退学、毕业、其他；
• 学历层次：本科、硕士、博士、进修生；
• 籍贯：省级 34 个 + 市级 300 多个（两级字典）；
• 宿舍类型：男生宿舍、女生宿舍、研究生公寓、教师公寓、其他；
• 床位类型：上铺、下铺、单人床、双人床；
• 报修类别：水电、家具、网络、门窗、其他；
• 调宿原因：宿舍矛盾、身体原因、专业调整、其他。

自由文本只留在"备注"类字段里。"备注"是唯一可以随便写的地方、其他都是选择、不是输入。

14.1.3 字典的治理节奏

• 新增字典项：管理员随时能加、加完立刻在下拉里可选；
• 修改字典项名称：随时能改、编码不变；历史数据仍然能找到；
• 停用字典项：软处理、旧数据保留、新数据不能再选；
• 删除字典项：几乎不允许——除非确认零历史引用；系统里有引用检查、有引用就拒绝删除。

这套节奏的目的：字典项不是一次定终身、是可以随业务演进逐步调整。学校扩了一个新专业、要加一个"专业类别"字典项——当天加、当天可选、不影响任何历史数据。

14.2 自定义字段的完整生命周期

学校想加一个"是否少数民族聚居区生源"字段。在系统里这件事从头到尾不写代码：

14.2.1 定义

管理员打开"字段管理"页面、填六样东西：

• 挂哪个对象：学生、房间、设备、消息——每个对象都有自己独立的字段池；
• 字段键（FieldKey）：内部标识、比如 EthnicMinorityArea——必须以字母开头、仅含字母数字下划线、长度不超过 50；
• 显示标签：是否少数民族聚居区生源；
• 字段类型：文本 / 数值 / 日期 / 下拉 / 布尔 / 长文本；
• 绑定字典：下拉类字段绑定字典编码（比如绑定"是 / 否"字典）；
• 校验规则：必填 / 最大长度 / 正则表达式。

六项定义完成、点保存、字段就存在了。

14.2.2 生效

保存之后：

• 表单页自动多一个输入框：学生新增/编辑页最下方多一列；
• 列表页的筛选区可选用它：可以按"是"筛选少数民族聚居区生源学生名单；
• 导出模板自动追加这一列：不需要重新设计模板；
• 接口返回结构自动带上这一列：所有下游系统（大屏、报表、企业微信集成）不用改代码就能收到新字段。

所有跟字段有关的事情都是跟随定义走的、没有一处需要开发手动加一行代码。

14.2.3 可见性

字段可以配"哪些角色可见"——"健康备注"只对校医角色和它的上级可见、辅导员看不到。自定义字段的角色可见性和内置字段的脱敏策略（第十三章）合在一起、构成了数据访问的字段级粒度控制。

这一层是"权限的最小单元"从"能进哪个页面"细化到"能看哪一列"。传统系统只管到"能不能进学生管理页"、粒度太粗；本系统能管到"进来了能看到哪些字段"。

14.2.4 停用与删除

字段可以停用（IsEnabled = false）——停用后不再出现在新增表单中、但已有数据保留、导出仍含这一列。只有当它完全不需要出现在导出里时才删除——而删除只是停止展示、历史扩展值仍在库里。

"删掉字段"和"删掉数据"是两回事、系统把它们分开了。这是很多老系统做不好的一件事：他们一删字段就把数据一起删了、导致旧数据失去解释。

14.3 字段键的纪律：一道防注入的窄门

字段键（FieldKey）最终会变成前端的一个属性名、扩展值存储里的一个键名。系统对它有一条死规则：必须以字母开头、仅含字母/数字/下划线、长度不超过 50。

这条限制不是为了"规范好看"、是防住三种事故：

• 反例一：字段键叫 select——前端把它拼到查询里会破坏语法；
• 反例二：字段键叫 宿舍类型——不同编码环境下会变乱码；
• 反例三：字段键叫带分号和注释符的一串——查询注入的经典模板。

元数据配置系统的安全、往往就差这一条小规矩上。这条规矩看起来小、但它保证了"字段可以随便配、不会把系统配坏"。

14.4 导入模板的动态生成

字段定义好了、下一步是数据怎么进来。系统的导入模板不是写死的一张 Excel——它跟着字段定义动态生成：

• 打开"下载导入模板" → 系统查询当前所有"启用的字段定义" → 拼一个 Excel 表头 → 生成下载。
• 上传导入文件 → 系统按当前启用的字段定义逐列校验 → 校验通过的行进入待入库队列 → 失败的行返回错误报告。
• 停用某字段后再下载模板 → 这一列从模板消失；但校验规则仍在（兼容历史数据）。
• 新增字段后立即下载模板 → 新列已经在最右边、不用重新排模板。

一个系统能配出多少字段、决定它五年后还贴不贴得上这所学校的业务。这句话反过来同样成立：一个系统的字段改不动、它的业务适应能力就已经死了、只是死得慢。

14.5 元数据浏览器：给管理员看的一屏

字段字典和自定义字段配到一定数量之后、管理员需要一个"全局视图"。系统里有一个元数据浏览器：

• 按对象分组：学生 / 房间 / 设备 / 消息 各自的字段列表；
• 按状态过滤：只看启用 / 只看停用 / 只看必填；
• 按引用检查：一个字段有多少历史数据、能不能安全停用；
• 一键预览：这个字段在前端长什么样、导出时列头是什么。

元数据浏览器的价值是"配了这么多字段之后心里还有数"——没有这一屏、系统运行三年就会积累一堆没人敢动的僵尸字段。

14.6 三条关于字段的常见误解

误解一：字段越多越好。有些学校一上来配 50 个自定义字段、"以后可能用得上"。结果新学生入库要填 30 个必填项、老数据大部分字段是空的、导出模板一大半列没有数据。健康的字段数量是"每一个字段都有至少 60% 的历史数据被填过"——低于这个比例就该停用。

误解二：字典项可以随便删。字典项不是文件、删了就没了——它是数据的解释器。一个学生登记"民族 = 壮"、你把"壮"这个字典项删了、三年后没人知道这个"壮"到底是什么意思。永远用停用、不要用删除。

误解三：字段键和显示名可以一样。字段键是给系统看的、要稳定不变；显示名是给人看的、可以随意调整。两者混用的结果：想改一个字段的中文名就要动数据、不敢改、最后中文名带着一堆错别字永远在那。从一开始就严格分开。

14.7 一张表：字段治理能力清单

能力	当前状态	说明
字典项标准结构	已投产	名称 / 编码 / 排序 / 启用 / 父级
枚举字段全部归字典	已投产	民族、政治面貌、学籍状态等
自定义字段六项定义	已投产	对象 / 键 / 标签 / 类型 / 字典 / 校验
字段角色可见性	已投产	与内置字段脱敏共同生效
字段停用保留数据	已投产	新增不出现、导出仍含
导入模板动态生成	已投产	跟随启用字段自动追加列
字段键窄门校验	已投产	字母开头 + 字母数字下划线 + 50 位
元数据浏览器	已投产	分组、过滤、引用检查、预览
跨系统字段协商	未投产	与教务系统同步时需要字段映射

14.8 给学校的一件事

翻一翻你学校宿舍系统里"民族"、"政治面貌"、"籍贯"、"学历层次"四个字段、看看它们是不是从字典里选出来的、还是自由填写的。如果四个里面有两个以上是手打的——下学期之前全部归到字典管理。这一步做完、你至少不用再花每学期初那两周对"到底有几个人是壮族"这件事做人工裁决。

再翻一翻"字段管理"或"元数据配置"这一页、看看你们已经配了多少自定义字段、其中有多少是最近半年新增过的。如果最近半年一个都没新增、要么系统设计得太完美、要么没人敢改它——后者更常见。

字段字典管住了"数据长什么样"、下一章要管"数据对不对"：对账与质量运营。