简介《致远OA V8.1 数据字典》是一份面向致远OA开发、实施、运维及二次开发人员的数据库结构速查文档覆盖表结构、字段类型、约束条件与注释说明主要用于解决表字段含义不清、SQL编写缺少依据、系统升级排查困难等问题。压缩包共1个PDF文件约2.2MB便于本地检索和随查随用。文档以ADDRESSBOOK、ADDRESSBOOK_MEMBER等表为例逐项列出字段名称、数据类型、是否强制及中文注释涵盖主键、人员ID、创建与更新时间以及文本、数字、日期、枚举、选人、选部门、选岗位等扩展字段并补充用户名称、单位、部门、岗位、联系方式等联系人信息字段方便核对数据完整性。已有2611人学习适合在二次开发、接口对接、数据查询和系统维护升级时对照使用帮助读者快速定位字段含义、理解表间关系、排查数据异常并评估结构变更影响。1. 数据字典为什么比源码更快说清一套 OA 的整体结构接手一套跑了多年的 OA最快的上手方式不是读源码而是把 V8.1 数据字典摊开看字段类型和长度。代码会误导你它会重构、会分层封装、会把 SQL 拼在字符串里表结构不会。它是十来年业务沉淀留下来的痕迹能随便改表的人不多所以每一列的长度、每一个状态位的取值背后都有一次具体的业务演进。这份字典里最直观的一处是 ADDRESSBOOK 表主键、人员 ID、两个时间戳之后接上了 70 个 EXT_ATTR 扩展字段。这个数字本身就说明了架构选择——业务变化的速度远快于建表的速度。读数据字典要回答三类问题这条数据从哪来字段类型、长度、是否强制、谁能看见范围表、历史怎么保留状态位与归档表。带着「为什么这么设计」去看字段类型比背字段名有用得多。2. 70 个 EXT_ATTR宽表为什么代替了 EAV2.1 七段式列族类型在段位里不在元数据里把 ADDRESSBOOK 的扩展字段按顺序拆开会看到一条非常整齐的分段EXT_ATTR_1 到 10 是 VARCHAR(1024) 文本11 到 20 是 DECIMAL(19,4) 数字21 到 30 是 DATETIME 日期31 到 40 是 VARCHAR(50) 枚举41 到 50、51 到 60、61 到 70 同样是 VARCHAR(50)但语义分别是选人、选部门、选岗位。这不是随便排的而是「列族」思路把同一类型的扩展位集中放在连续段位里应用层只要知道序号落在哪一段就完全确定该怎么解析、怎么校验、怎么渲染表单。段位类型数量典型用途容易踩的点1-10VARCHAR(1024)10备注、拼接串、JSON 摘要长度够但没约束脏数据多11-20DECIMAL(19,4)10金额、工时、评分精度够但业务单位靠约定21-30DATETIME10时间点、到期日无时区跨区部署要统一31-40VARCHAR(50)10枚举 code存 code 不存 label别直接展示41-50VARCHAR(50)10人员实体 ID多选会截断只能放一个 ID51-60VARCHAR(50)10部门实体 ID同上且部门会合并撤销61-70VARCHAR(50)10岗位实体 ID同上为什么不走 EAV一张 attr_name / attr_value 竖表因为 EAV 每读一条业务记录都要 join 一次扩展表再 pivot 成行一个列表页十几个扩展字段就是十几次 join 或者一次大 unionSQL 优化器很难优化出执行计划。宽表把这些成本全部转移到了写入和存储上而扩展字段的读频率远高于写频率。DECIMAL(19,4) 的选择也有讲究19 位总长、4 位小数整数部分能放 15 位足够覆盖金额和工时两类场景又不需要在应用层做浮点转定点。2.2 语义在其他位置数据库只存字节元数据在配置里这份字典读起来最别扭的地方是字段名全是 EXT_ATTR_N业务含义一个都没写。因为扩展字段的「显示名、是否必填、下拉选项、默认值、在表单第几行」这些信息不在数据库里而在扩展字段定义和表单配置里。数据库只保证「存得下、类型对」语义完全由上层解释。这就导致一个很现实的问题光看字典查不出某个扩展字段装的是什么只能靠段位猜大类再靠数据分布反推。-- 反查某个扩展位到底有没有在用非空行数 取值样例 SELECT COUNT(*) AS total, COUNT(EXT_ATTR_11) AS not_null_cnt, -- 数字段位统计非空 MIN(EXT_ATTR_11) AS min_val, MAX(EXT_ATTR_11) AS max_val FROM ADDRESSBOOK WHERE TYPE 1; -- 按通讯录类型缩小范围 -- 引用型段位41-50 选人要看 ID 的分布判断是不是多选拼接 SELECT EXT_ATTR_41, COUNT(*) AS cnt FROM ADDRESSBOOK WHERE EXT_ATTR_41 IS NOT NULL AND EXT_ATTR_41 GROUP BY EXT_ATTR_41 ORDER BY cnt DESC LIMIT 20;第一段 SQL 判断「这个位有没有人用、值域大概在哪」第二段判断「这个位存的是单个 ID 还是拼接串」。如果结果里出现逗号分隔的长串基本可以确认是多人多选硬塞进 VARCHAR(50)长度一超就被截断——这是这类设计最常见的坑后面第 5 章会单独说。枚举段位还有个约定存的是 code 不是显示名所以直接 SELECT 出来给人看会得到一串数字字母必须过一遍枚举字典。2.3 按段位分派的读写代码扩展字段的读写难点不在 SQL而在类型转换集中在一处还是散落各处。常见的实现思路是把段位表做成一个常量映射所有读写都走同一个入口禁止业务代码里直接row[EXT_ATTR_11]。# 段位 - (解析类型, 附加参数) 的唯一事实来源 EXT_SEGMENTS [ (1, 10, text, None), # VARCHAR(1024) (11, 20, decimal, (19, 4)), # DECIMAL(19,4) (21, 30, datetime, None), # DATETIME (31, 40, enum, 50), # 枚举 code (41, 50, member, 50), # 人员实体 ID (51, 60, dept, 50), # 部门实体 ID (61, 70, post, 50), # 岗位实体 ID ] def attr_kind(index: int): 根据 EXT_ATTR_N 的 N 反推语义类型越界直接报错而不是静默兜底 for low, high, kind, extra in EXT_SEGMENTS: if low index high: return kind, extra raise ValueError(fEXT_ATTR_{index} 不在预留段位内) def read_attr(row: dict, index: int): 统一读入口NULL 统一返回 None空串也归一成 None避免下游两套判断 kind, extra attr_kind(index) raw row.get(fEXT_ATTR_{index}) if raw is None or raw : return None if kind decimal: return round(float(raw), extra[1]) # 定点转浮点只在这一层发生 if kind datetime: return raw # 交给上层格式化别在这里拼字符串 return raw # text / enum / 引用型都原样返回 ID 或 code这段代码的关键不是转换本身而是「越界报错」。段位之外的 N 一定是脏数据或者历史遗留静默兜底会让问题延后到报表层才暴露。另外空串归一成 None 很重要数据库里 NULL 和空串混用是常态如果不在入口统一每个查询条件都要写IS NOT NULL AND 两遍。2.4 加列的代价宽表不是没有成本的70 个扩展位加上业务字段ADDRESSBOOK 的列数已经接近三位数。很多人以为宽表的主要代价是存储其实不是——VARCHAR 是变长类型NULL 只占 NULL 位图里的一个 bit数据区不分配空间真正的代价有三个。第一是 DDL早期版本给大表加列会锁表重建即使后来的版本支持 instant add column也有「新列必须加在最后」之类的限制所以扩展位只能一次性预留够事后追加会破坏段位约定。第二是行溢出一旦有多个 VARCHAR(1024) 真的写满行长度超过页的一半就会触发溢出页随机读会多一次 IO。第三是可维护性任何一次全表SELECT *都会把 70 个空列捞回来网络和反序列化开销白白浪费。常见的做法是查询层强制列白名单禁止SELECT *。3. 多态引用与范围表为什么这套表结构里几乎没有外键3.1 一个 ENTITY_ID 三张表用多态引用的三种写法组织模型里的人员、部门、单位、岗位、职务级别分散在多张表里任何一个业务对象要引用「某个组织实体」都没法在数据库层建外键。这套字典里给出了三种风格不统一的解法正好能看出演进的痕迹。表类型字段类型字段形态取值含义ADDRESSBOOK_SET_SCOPEUSER_TYPEVARCHAR(50)组织模型实体类型字符串形式AGENT_SCOPEENTITY_TYPEVARCHAR(50)ACCOUNT、DEPARTMENT 等字符串ATTENDANCE_AUTH_ENTITYENTITY_TYPESMALLINT3 人员、1 部门、0 单位同一件事三种表达字符串型更可读、加新类型不用改表但拼错一个字符就变成孤儿数据数字型更省空间、能建联合索引但语义要靠文档。这些表全部没有外键约束级联删除、引用完整性都靠应用层。这是刻意的取舍OA 的组织架构调整非常频繁部门合并、人员调岗、单位拆分如果挂了外键一次组织调整会被数据库的约束检查卡住甚至出现「删不掉旧部门因为历史单据还引用着」的死局。代价是脏数据不可避免。所以字典里出现了几组专门的记录表AI_ORG_CHANGE_RECORD 记 OLD_ID / OLD_VALUE / NEW_ID / NEW_VALUEORG_TYPE 区分部门、岗位、职务级别AI_ORG_MEMBER_CHANGE 记 MEMBER_ID 加上旧单位、新单位、旧部门、新部门、旧岗位、新岗位、旧职务级别、新职务级别。这两张表本质上是组织调整的变更记录调整完成后如果报表数据对不上可以顺着这两张表倒推是哪一次调整、哪个字段从什么变成了什么。3.2 范围表模式SET 管规则SCOPE 管对象通讯录的可见性设计是这套字典里最值得学的一块。ADDRESSBOOK_SET 存的是「设置本身」VIEW_SCOPE 表示查看范围策略、KEY_INFO 和 KEY_INFO_TYPE 表示关键信息展示1 手机号加职务级别、2 只要手机号、3 只要职务级别、EXPORT_PRINT 控制导出打印、DISPLAY_COLUMN 是 VARCHAR(1024) 的显示列清单、EXTERNAL_SCOPE 控制编外人员1 按工作范围显示、2 全部隐藏、M3_SET 和 ZX_SET 分别是移动端和另一个客户端的独立显示设置、DEPARTMENT_INFO_ORDER 控制部门与人员谁排前面。一张表把「谁能看什么、看到哪些列、能不能导出」全部收进去。ADDRESSBOOK_SET_SCOPE 才是范围明细ADDRESSBOOK_SET_ID 指回设置ADDRESSBOOK_SET_TYPE 用 1/2/3 区分这条明细属于查看范围、关键信息还是导出打印权限USER_ID 加 USER_TYPE 指向具体的组织实体。也就是说同一张 scope 表被三类设置复用靠一个类型字段分流。-- 判断「我」能不能看到某人的通讯录条目 -- 第一步找到本单位的通讯录设置 WITH cfg AS ( SELECT ID FROM ADDRESSBOOK_SET WHERE ACCOUNT_ID :accountId ), -- 第二步只取查看范围那一类明细TYPE 漏了就会把导出权限当成可见范围 scope AS ( SELECT s.USER_ID, s.USER_TYPE FROM ADDRESSBOOK_SET_SCOPE s JOIN cfg ON cfg.ID s.ADDRESSBOOK_SET_ID WHERE s.ADDRESSBOOK_SET_TYPE 1 ) SELECT 1 FROM scope WHERE (USER_TYPE MEMBER AND USER_ID :myMemberId) OR (USER_TYPE DEPARTMENT AND USER_ID IN (:myDeptIds)) OR (USER_TYPE ACCOUNT AND USER_ID :accountId) LIMIT 1;这段 SQL 的写法直接决定了索引怎么建ADDRESSBOOK_SET_SCOPE 上的联合索引前缀应该是 (ADDRESSBOOK_SET_ID, ADDRESSBOOK_SET_TYPE, USER_TYPE)把范围收窄放在最前面。如果只建了 (USER_ID)那么每次判定都要全表扫出所有单位的所有范围行数据量一上来就是慢查询。3.3 代理关系双向字段、软取消和事项条件代理设置是另一个把「状态」设计得很满的例子。AGENT 表里 AGENT_ID 是代理人、AGENT_TO_ID 是被代理人两个方向都要能查所以索引得建两条AGENT_TYPE 区分 1 代理设置和 2 离职交接两者共用一张表但业务含义完全不同MATTER_TYPE 区分按处理人设置还是按发起人设置START_DATE 和 END_DATE 划出代理窗口CANCEL_DATE 加 CANCEL_FLAG 做软取消——不物理删除因为代理期间产生的单据还要能追溯是谁代谁处理的。AGENT_DETAIL 用 APP 字段按应用维度拆分一个代理可以只对某几个模块生效AGENT_SCOPE 则存发起人范围用 ENTITY_TYPE 加 ENTITY_ID 再走一次多态引用。-- 某人当前生效的代理关系时间窗口 未取消 排除离职交接 SELECT ID, AGENT_ID, AGENT_TO_ID, AGENT_TYPE, START_DATE, END_DATE FROM AGENT WHERE CANCEL_FLAG 0 AND START_DATE :now AND (END_DATE IS NULL OR END_DATE :now) AND (AGENT_ID :memberId OR AGENT_TO_ID :memberId) -- 双向查询 ORDER BY START_DATE DESC;注意 END_DATE 的判空很多实现把「长期有效」存成 NULL也有存成 9999-12-31 的两种写法在同一套系统里并存是常有的事查询必须兼容。另外 AI_DEAL_CONDITION 表把「自动处理条件」做成了可配置TEMPLATE_ID 定位流程模板SENDER_ID 和 USER_ID 分别是发起人和处理人DEAL_TYPE 枚举 0 回退、1 指定回退、2 撤销、3 终止、4 不同意、5 处理时长SIGNLE_VIEW_PERIOD 存处理时长阈值。把操作类型和时长指标塞进同一张条件表好处是一条规则能同时表达「谁在什么操作下、超过多久」就触发坏处是 DEAL_TYPE 5 时其他字段的语义就变了读代码的人很容易误解。4. 考勤模块的三层数据流水、日统计、归档各管一段4.1 排班链TEAM 到 ARRANGE 到 CLASS 到 FIX_TIME考勤的配置是一棵树从根往下读ATTENDANCE_TEAM 是考勤组带 IS_NEW、START_DATE、END_DATE 三个字段做版本化——考勤规则按生效日期切换历史统计必须按当时的规则算所以旧版本不删只把 IS_NEW 置 0。ATTENDANCE_ARRANGE 是排班0 固定排班、1 周期排班ATTENDANCE_CLASS 是班次CLASS_TYPE 表示一天 1 次、2 次还是 3 次FLEX_TIME 是弹性时间LATE_SERIOUS 是严重迟到阈值ABSENT_WORK 是旷工判定LEAVE_FIX_TIME 和 ATTEND_FIX_TIME 是允许晚走和晚到的宽限再往下 ATTENDANCE_FIX_TIME 存每一段的具体时间点WORK_TIME、END_TIME、EARLY_WORK_TIME最早可签到、LAST_END_TIME最晚可签退以及 ATTEND_REMIND 和 LEAVE_REMIND 两个提醒开关。ATTENDANCE_DAY 是这条链的落地某天对应哪个排班、哪个班次、是不是工作日。有一处细节值得停下来看LATE_SERIOUS、ABSENT_WORK、FLEX_TIME 这些明明都是「分钟数」的字段类型是 VARCHAR(50)。存成字符串之后凡是涉及比较和排序的地方都得先转数字跨库查询时还可能因为隐式转换把索引废掉。稳妥的做法是在应用层统一转换成分钟整数再比较别指望数据库替你做。4.2 ATTENDANCE_INFO 与 ATTENDANCE_HISTORY结构与用途的差异这两张表字段高度重合OWNER_ID、DEPT_ID、SIGN_TIME、SIGN、LONGITUDE、LATITUDE、COUNTRY、PROVINCE、CITY、TOWN、STREET、NEAR_ADDRESS、ADDRESS_CODE、ADDRESS_TYPE、YEAR/MONTH/DAY、IMG_INFO、RECORD_INFO。差异才是信息所在。差异点ATTENDANCE_INFOATTENDANCE_HISTORYSIGN 长度VARCHAR(2000)VARCHAR(500)STATE有3 上班迟到 / 4 下班早退 / 5 正常上班 / 6 正常下班无MODIFY_NUM有记录签到修改次数无DEVICE_INFO / MAC_ADDRESS有设备 ID 与 WIFI Mac无IS_WORK_DAY有无年月日冗余列有有用途活数据可改可申诉带防代打卡指纹已归档只读报表SIGN 字段在两张表长度不一致直接说明 INFO 表后期扩过列原来只存地址或 IP后来把定位描述一起拼进去2000 才够。STATE 的枚举从 3 开始而不是从 0 或 1 开始是另一个信号——1 和 2 曾经代表过别的含义语义变更之后就地废弃没人敢复用。这种「编号断档」在老系统里到处都是看到枚举缺号正确的反应是去代码里找历史映射而不是自己补上 0 和 1。至于为什么留两份结构相近的表ATTENDANCE_INFO 是写入热点每秒都在插还要支持修改和申诉索引要围绕 OWNER_ID 和 PUNCH_DATE 建ATTENDANCE_HISTORY 是只读归档数据量大但查询模式单一可以按月分区、可以压缩、可以放冷存储。拆开之后归档动作不会跟在线写入抢锁。IMG_INFO 和 RECORD_INFO 用 VARCHAR 存 JSON 而不是拆子表理由也类似图片和语音是补充证据按图片维度反查的需求几乎没有拆表只会增加一次 join。4.3 ATTENDANCE_DAY_STATISTICS把计算前移到写入时这张表是典型的预聚合宽表一人一天一行AM_START_TIME、AM_END_TIME、PM_START_TIME、PM_END_TIME 四个时间点加上四个对应的状态位再加上 NORMAL_DAY正常出勤天数、AB_NORMAL_DAY异常天数、NONWORKDAYS_DAY非工作日打卡天数、LATE_NUM、LEAVE_EARLY_NUM、OUTSIDE_NUM、MISSINGCLOCK_COUNT、WORKING_MISSINGCLOCK、KNOCKOFF_MISSINGCLOCK、WORKING_MISSINGCLOCK、PUNCH_CLASS应打卡次数 1 或 2。一行的列数看着吓人但它把「算」的成本从读时挪到了写时。-- 月度报表从日统计直接 SUM不去碰流水表 SELECT MEMBER_ID, SUM(NORMAL_DAY) AS 正常出勤, SUM(AB_NORMAL_DAY) AS 异常天数, SUM(LATE_NUM) AS 迟到次数, SUM(LEAVE_EARLY_NUM) AS 早退次数, SUM(OUTSIDE_NUM) AS 外勤次数, SUM(MISSINGCLOCK_COUNT) AS 缺卡总数 FROM ATTENDANCE_DAY_STATISTICS WHERE ACCOUNT_ID :accountId AND PUNCH_DATE :monthStart AND PUNCH_DATE :nextMonthStart GROUP BY MEMBER_ID;这条 SQL 之所以能跑得快全靠 PUNCH_DATE 上的索引和「一人一天一行」的粒度。如果换成从 ATTENDANCE_INFO 现场算就要按人按天分组、判断工作日、比对排班时间、判定迟到早退一次月度查询可能扫几十万行流水。预聚合的代价是补卡、申诉、规则变更之后必须重算那一天的统计行重算漏了就会出现「流水改了但报表没变」的数据不一致。PUNCH_CLASS 字段就是重算时的依据之一——它告诉你这一天应该打卡几次缺卡数才能算对。4.4 地理与附件为什么经纬度不按规范存按数据库设计规范经纬度应该用 DECIMAL比如 DECIMAL(10,6)这套字典里 LONGITUDE 和 LATITUDE 都是 VARCHAR(50)。原因不难推签到定位的数据来自第三方地图接口接口返回的就是字符串直接落库最省事也不用处理空串、空格、负号、精度不一致这些情况。代价在处理侧——要算「是否在围栏内」就得先 CAST 成 DECIMAL 或者交给应用层算而 CAST 一旦碰上空串就是报错而不是 NULL。所以正确做法是入库前统一格式化成固定小数位字符串查询时用正则先过滤再转换绝不能假设这一列一定是合法数字。ATTENDANCE_SETTING 里的 LONGITUDE、LATITUDE、ATTEND_REMIND、AVAILABLE 是围栏配置RELATIVE_ID 用来存第三方系统导入的围栏 ID这条设计说明围栏数据可能来自外部进一步解释了为什么地理字段全程按字符串处理。5. 排查与避坑读这份数据字典时最容易翻车的五个地方5.1 扩展字段只看到一个人或者干脆是空现象明明在表单上选了三个审批人查 EXT_ATTR_41 只看到第一个人的 ID后面的人不见了。原因41 到 50 段位定的是 VARCHAR(50)一个 BIGINT 主键转成字符串大概 10 到 20 位三个人拼起来必然超长写入时被数据库截断或者被应用层截断。解决先按主键查是否只有一个 ID确认是截断然后判断这个业务到底需要单选还是多选多选就必须另建关联表或者把这段改成 VARCHAR(1024)不能靠扩长度硬撑。排查脚本就一句SELECT LENGTH(EXT_ATTR_41), EXT_ATTR_41 FROM ADDRESSBOOK WHERE LENGTH(EXT_ATTR_41) 20;。5.2 通讯录里某人看不到但设置明明是「全部可见」现象用户反馈通讯录搜不到某个同事管理员进设置页看查看范围是全单位。原因ADDRESSBOOK_SET_SCOPE 里 ADDRESSBOOK_SET_TYPE 有 1、2、3 三种含义分别对应查看范围、关键信息、导出与打印。查询可见性时漏了这个条件就会把「导出权限」的明细误当成可见范围或者反过来把本该可见的实体过滤掉。解决所有涉及这张表的查询都必须显式带上ADDRESSBOOK_SET_TYPE 1并且用 ADDRESSBOOK_SET_ID 关联到本单位ACCOUNT_ID的设置别用全局设置去覆盖单位设置。5.3 签到距离算出来是负数报表里出现一堆异常现象围栏判断时抛出数字转换异常或者距离算出来明显不对。原因LONGITUDE、LATITUDE 是 VARCHAR里面可能有空串、前后空格、超过合理范围的脏值甚至有人在多地点打卡时把两个坐标拼在一列里。直接 CAST 就会报错或者得到错值。解决转换前先用正则白名单过滤^-?\d{1,3}(\.\d)?$过滤后再判范围经度 -180 到 180纬度 -90 到 90不合法的一律当未定位处理而不是当 0 处理——当 0 会让所有异常点落在赤道附近报表看着像有人在南美打卡。5.4 报表人数比通讯录少或者翻倍现象人员总数统计出来跟通讯录对不上。原因状态位没过滤干净。这套字典里的状态至少有四种形态——BBS 系列表里的 STATE 是 0 正常 1 删除AGENT 里的 CANCEL_FLAG 是 0 未取消 1 已取消ATTENDANCE_TEAM 的 IS_NEW 是 0 不是最新 1 是最新ATTENDANCE_NO_REMIND_MEMBER 的 STATE 是 0 正常 1 废弃。这些字段名不一样、取值含义也不统一任一漏掉都会串数据。解决给每张表建一份「必带条件」清单写查询前先对照更彻底的做法是在数据访问层把这几类表包一层视图把状态条件固化进去。5.5 跨单位查询串数据或者同一个 ID 出现两条记录现象多单位部署下A 单位的报表里出现了 B 单位的人。原因人员 ID 在不同单位下可能重复所有业务表都冗余了 ACCOUNT_ID 或 ORG_ACCOUNT_ID 做隔离键但查询时忘了带。ATTENDANCE_HISTORY、ATTENDANCE_DAY_STATISTICS、BBS_ARTICLE、AI_ORG_CHANGE_RECORD 都带这个字段它不是冗余而是必须的过滤条件。解决联合索引一律以 ACCOUNT_ID 打头比如 (ACCOUNT_ID, PUNCH_DATE, MEMBER_ID)既能保证隔离又能让范围查询走上索引并且约定所有查询构造器默认注入当前单位。6. 设计取舍宽表、冗余统计和无外键值不值6.1 宽表的实际代价比想象的小但不是没有边界很多人看到 70 个 EXT_ATTR 第一反应是「这么设计不规范」。先算一笔账VARCHAR 和 DATETIME 在 InnoDB 里是变长存储NULL 值只占 NULL 位图里的一个 bit数据区不分配DECIMAL(19,4) 是定长 9 字节左右。70 个扩展位全空时每行真正多出来的只有一个 NULL 位图加上变长列的偏移数组几字节到几十字节量级。所以在「扩展字段大面积空置、少数人用满」的分布下宽表的存储代价不算高换来的是免 join、强类型、ORM 直接映射三件事。真正的边界在列数上限和 DDL 成本列数逼近三位数之后任何一次表结构变更都是高风险动作所以扩展位只能一次预留够这也是为什么它一上来就是 70 个而不是 10 个。6.2 预聚合与无外键两个方向的取舍ATTENDANCE_DAY_STATISTICS 把迟到次数、缺卡数这类指标在写入时就固化是拿「一致性维护成本」换「读性能」。这个交换在考勤场景里划算因为读远多于写而且写入路径是单点的签到服务重算可以由同一个服务触发。但如果换到工单、合同这种数据随时被修改的场景预聚合会变成负担改一次数据要重算一串统计。无外键的取舍同理OA 的组织架构调整频率高到无法承受外键约束所以接受脏数据风险转而用 AI_ORG_CHANGE_RECORD、AI_ORG_MEMBER_CHANGE 这类变更记录表加上定时巡检来做一致性兜底。这套设计能成立前提是「组织调整是低频但影响面大的操作」可以接受用批处理补偿而不是要求数据库实时保证。6.3 我自己的三条自检习惯拿到一份新版数据字典我一般先做三件事。第一grep 所有状态类字段STATE、FLAG、IS_NEW、CANCEL_FLAG把取值含义列成表因为这类字段的编号断档和老语义是数据错乱的源头。第二grep 所有带 ACCOUNT_ID、ORG_ACCOUNT_ID 的表确认隔离键没有遗漏多单位部署下的串数据问题一旦上线很难回溯。第三把 EXT_ATTR 的段位表抄一份放进项目文档任何读写扩展字段的代码都必须引用这个唯一来源禁止硬编码下标。这三件事花了不到一小时但省下来的排查时间远不止于此。有一次做考勤报表我图省事直接从流水表现算月度迟到次数结果对不上人力的口径——因为漏了「非工作日打卡不计迟到」这一条而这条规则只体现在日统计表的 IS_WORK_DAY 判定里。从那以后我每次碰这类有预聚合表的模块都强制先把「流水、日统计、归档」三层的字段差异拉出来对比一遍再动查询。这份 V8.1 数据字典把通讯录、代理、自动处理、组织调整、考勤、讨论区的表结构和字段含义都摊开了正好可以拿它做一次逐表梳理把上面这些坑在自己系统里对照检查一遍。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/31 11:31:50 · 阅读 1.2k OA数据字典设计解析：EXT_ATTR宽表、多态引用与考勤预聚合
简介《致远OA V8.1 数据字典》是一份面向致远OA开发、实施、运维及二次开发人员的数据库结构速查文档覆盖表结构、字段类型、约束条件与注释说明主要用于解决表字段含义不清、SQL编写缺少依据、系统升级排查困难等问题。压缩包共1个PDF文件约2.2MB便于本地检索和随查随用。文档以ADDRESSBOOK、ADDRESSBOOK_MEMBER等表为例逐项列出字段名称、数据类型、是否强制及中文注释涵盖主键、人员ID、创建与更新时间以及文本、数字、日期、枚举、选人、选部门、选岗位等扩展字段并补充用户名称、单位、部门、岗位、联系方式等联系人信息字段方便核对数据完整性。已有2611人学习适合在二次开发、接口对接、数据查询和系统维护升级时对照使用帮助读者快速定位字段含义、理解表间关系、排查数据异常并评估结构变更影响。1. 数据字典为什么比源码更快说清一套 OA 的整体结构接手一套跑了多年的 OA最快的上手方式不是读源码而是把 V8.1 数据字典摊开看字段类型和长度。代码会误导你它会重构、会分层封装、会把 SQL 拼在字符串里表结构不会。它是十来年业务沉淀留下来的痕迹能随便改表的人不多所以每一列的长度、每一个状态位的取值背后都有一次具体的业务演进。这份字典里最直观的一处是 ADDRESSBOOK 表主键、人员 ID、两个时间戳之后接上了 70 个 EXT_ATTR 扩展字段。这个数字本身就说明了架构选择——业务变化的速度远快于建表的速度。读数据字典要回答三类问题这条数据从哪来字段类型、长度、是否强制、谁能看见范围表、历史怎么保留状态位与归档表。带着「为什么这么设计」去看字段类型比背字段名有用得多。2. 70 个 EXT_ATTR宽表为什么代替了 EAV2.1 七段式列族类型在段位里不在元数据里把 ADDRESSBOOK 的扩展字段按顺序拆开会看到一条非常整齐的分段EXT_ATTR_1 到 10 是 VARCHAR(1024) 文本11 到 20 是 DECIMAL(19,4) 数字21 到 30 是 DATETIME 日期31 到 40 是 VARCHAR(50) 枚举41 到 50、51 到 60、61 到 70 同样是 VARCHAR(50)但语义分别是选人、选部门、选岗位。这不是随便排的而是「列族」思路把同一类型的扩展位集中放在连续段位里应用层只要知道序号落在哪一段就完全确定该怎么解析、怎么校验、怎么渲染表单。段位类型数量典型用途容易踩的点1-10VARCHAR(1024)10备注、拼接串、JSON 摘要长度够但没约束脏数据多11-20DECIMAL(19,4)10金额、工时、评分精度够但业务单位靠约定21-30DATETIME10时间点、到期日无时区跨区部署要统一31-40VARCHAR(50)10枚举 code存 code 不存 label别直接展示41-50VARCHAR(50)10人员实体 ID多选会截断只能放一个 ID51-60VARCHAR(50)10部门实体 ID同上且部门会合并撤销61-70VARCHAR(50)10岗位实体 ID同上为什么不走 EAV一张 attr_name / attr_value 竖表因为 EAV 每读一条业务记录都要 join 一次扩展表再 pivot 成行一个列表页十几个扩展字段就是十几次 join 或者一次大 unionSQL 优化器很难优化出执行计划。宽表把这些成本全部转移到了写入和存储上而扩展字段的读频率远高于写频率。DECIMAL(19,4) 的选择也有讲究19 位总长、4 位小数整数部分能放 15 位足够覆盖金额和工时两类场景又不需要在应用层做浮点转定点。2.2 语义在其他位置数据库只存字节元数据在配置里这份字典读起来最别扭的地方是字段名全是 EXT_ATTR_N业务含义一个都没写。因为扩展字段的「显示名、是否必填、下拉选项、默认值、在表单第几行」这些信息不在数据库里而在扩展字段定义和表单配置里。数据库只保证「存得下、类型对」语义完全由上层解释。这就导致一个很现实的问题光看字典查不出某个扩展字段装的是什么只能靠段位猜大类再靠数据分布反推。-- 反查某个扩展位到底有没有在用非空行数 取值样例 SELECT COUNT(*) AS total, COUNT(EXT_ATTR_11) AS not_null_cnt, -- 数字段位统计非空 MIN(EXT_ATTR_11) AS min_val, MAX(EXT_ATTR_11) AS max_val FROM ADDRESSBOOK WHERE TYPE 1; -- 按通讯录类型缩小范围 -- 引用型段位41-50 选人要看 ID 的分布判断是不是多选拼接 SELECT EXT_ATTR_41, COUNT(*) AS cnt FROM ADDRESSBOOK WHERE EXT_ATTR_41 IS NOT NULL AND EXT_ATTR_41 GROUP BY EXT_ATTR_41 ORDER BY cnt DESC LIMIT 20;第一段 SQL 判断「这个位有没有人用、值域大概在哪」第二段判断「这个位存的是单个 ID 还是拼接串」。如果结果里出现逗号分隔的长串基本可以确认是多人多选硬塞进 VARCHAR(50)长度一超就被截断——这是这类设计最常见的坑后面第 5 章会单独说。枚举段位还有个约定存的是 code 不是显示名所以直接 SELECT 出来给人看会得到一串数字字母必须过一遍枚举字典。2.3 按段位分派的读写代码扩展字段的读写难点不在 SQL而在类型转换集中在一处还是散落各处。常见的实现思路是把段位表做成一个常量映射所有读写都走同一个入口禁止业务代码里直接row[EXT_ATTR_11]。# 段位 - (解析类型, 附加参数) 的唯一事实来源 EXT_SEGMENTS [ (1, 10, text, None), # VARCHAR(1024) (11, 20, decimal, (19, 4)), # DECIMAL(19,4) (21, 30, datetime, None), # DATETIME (31, 40, enum, 50), # 枚举 code (41, 50, member, 50), # 人员实体 ID (51, 60, dept, 50), # 部门实体 ID (61, 70, post, 50), # 岗位实体 ID ] def attr_kind(index: int): 根据 EXT_ATTR_N 的 N 反推语义类型越界直接报错而不是静默兜底 for low, high, kind, extra in EXT_SEGMENTS: if low index high: return kind, extra raise ValueError(fEXT_ATTR_{index} 不在预留段位内) def read_attr(row: dict, index: int): 统一读入口NULL 统一返回 None空串也归一成 None避免下游两套判断 kind, extra attr_kind(index) raw row.get(fEXT_ATTR_{index}) if raw is None or raw : return None if kind decimal: return round(float(raw), extra[1]) # 定点转浮点只在这一层发生 if kind datetime: return raw # 交给上层格式化别在这里拼字符串 return raw # text / enum / 引用型都原样返回 ID 或 code这段代码的关键不是转换本身而是「越界报错」。段位之外的 N 一定是脏数据或者历史遗留静默兜底会让问题延后到报表层才暴露。另外空串归一成 None 很重要数据库里 NULL 和空串混用是常态如果不在入口统一每个查询条件都要写IS NOT NULL AND 两遍。2.4 加列的代价宽表不是没有成本的70 个扩展位加上业务字段ADDRESSBOOK 的列数已经接近三位数。很多人以为宽表的主要代价是存储其实不是——VARCHAR 是变长类型NULL 只占 NULL 位图里的一个 bit数据区不分配空间真正的代价有三个。第一是 DDL早期版本给大表加列会锁表重建即使后来的版本支持 instant add column也有「新列必须加在最后」之类的限制所以扩展位只能一次性预留够事后追加会破坏段位约定。第二是行溢出一旦有多个 VARCHAR(1024) 真的写满行长度超过页的一半就会触发溢出页随机读会多一次 IO。第三是可维护性任何一次全表SELECT *都会把 70 个空列捞回来网络和反序列化开销白白浪费。常见的做法是查询层强制列白名单禁止SELECT *。3. 多态引用与范围表为什么这套表结构里几乎没有外键3.1 一个 ENTITY_ID 三张表用多态引用的三种写法组织模型里的人员、部门、单位、岗位、职务级别分散在多张表里任何一个业务对象要引用「某个组织实体」都没法在数据库层建外键。这套字典里给出了三种风格不统一的解法正好能看出演进的痕迹。表类型字段类型字段形态取值含义ADDRESSBOOK_SET_SCOPEUSER_TYPEVARCHAR(50)组织模型实体类型字符串形式AGENT_SCOPEENTITY_TYPEVARCHAR(50)ACCOUNT、DEPARTMENT 等字符串ATTENDANCE_AUTH_ENTITYENTITY_TYPESMALLINT3 人员、1 部门、0 单位同一件事三种表达字符串型更可读、加新类型不用改表但拼错一个字符就变成孤儿数据数字型更省空间、能建联合索引但语义要靠文档。这些表全部没有外键约束级联删除、引用完整性都靠应用层。这是刻意的取舍OA 的组织架构调整非常频繁部门合并、人员调岗、单位拆分如果挂了外键一次组织调整会被数据库的约束检查卡住甚至出现「删不掉旧部门因为历史单据还引用着」的死局。代价是脏数据不可避免。所以字典里出现了几组专门的记录表AI_ORG_CHANGE_RECORD 记 OLD_ID / OLD_VALUE / NEW_ID / NEW_VALUEORG_TYPE 区分部门、岗位、职务级别AI_ORG_MEMBER_CHANGE 记 MEMBER_ID 加上旧单位、新单位、旧部门、新部门、旧岗位、新岗位、旧职务级别、新职务级别。这两张表本质上是组织调整的变更记录调整完成后如果报表数据对不上可以顺着这两张表倒推是哪一次调整、哪个字段从什么变成了什么。3.2 范围表模式SET 管规则SCOPE 管对象通讯录的可见性设计是这套字典里最值得学的一块。ADDRESSBOOK_SET 存的是「设置本身」VIEW_SCOPE 表示查看范围策略、KEY_INFO 和 KEY_INFO_TYPE 表示关键信息展示1 手机号加职务级别、2 只要手机号、3 只要职务级别、EXPORT_PRINT 控制导出打印、DISPLAY_COLUMN 是 VARCHAR(1024) 的显示列清单、EXTERNAL_SCOPE 控制编外人员1 按工作范围显示、2 全部隐藏、M3_SET 和 ZX_SET 分别是移动端和另一个客户端的独立显示设置、DEPARTMENT_INFO_ORDER 控制部门与人员谁排前面。一张表把「谁能看什么、看到哪些列、能不能导出」全部收进去。ADDRESSBOOK_SET_SCOPE 才是范围明细ADDRESSBOOK_SET_ID 指回设置ADDRESSBOOK_SET_TYPE 用 1/2/3 区分这条明细属于查看范围、关键信息还是导出打印权限USER_ID 加 USER_TYPE 指向具体的组织实体。也就是说同一张 scope 表被三类设置复用靠一个类型字段分流。-- 判断「我」能不能看到某人的通讯录条目 -- 第一步找到本单位的通讯录设置 WITH cfg AS ( SELECT ID FROM ADDRESSBOOK_SET WHERE ACCOUNT_ID :accountId ), -- 第二步只取查看范围那一类明细TYPE 漏了就会把导出权限当成可见范围 scope AS ( SELECT s.USER_ID, s.USER_TYPE FROM ADDRESSBOOK_SET_SCOPE s JOIN cfg ON cfg.ID s.ADDRESSBOOK_SET_ID WHERE s.ADDRESSBOOK_SET_TYPE 1 ) SELECT 1 FROM scope WHERE (USER_TYPE MEMBER AND USER_ID :myMemberId) OR (USER_TYPE DEPARTMENT AND USER_ID IN (:myDeptIds)) OR (USER_TYPE ACCOUNT AND USER_ID :accountId) LIMIT 1;这段 SQL 的写法直接决定了索引怎么建ADDRESSBOOK_SET_SCOPE 上的联合索引前缀应该是 (ADDRESSBOOK_SET_ID, ADDRESSBOOK_SET_TYPE, USER_TYPE)把范围收窄放在最前面。如果只建了 (USER_ID)那么每次判定都要全表扫出所有单位的所有范围行数据量一上来就是慢查询。3.3 代理关系双向字段、软取消和事项条件代理设置是另一个把「状态」设计得很满的例子。AGENT 表里 AGENT_ID 是代理人、AGENT_TO_ID 是被代理人两个方向都要能查所以索引得建两条AGENT_TYPE 区分 1 代理设置和 2 离职交接两者共用一张表但业务含义完全不同MATTER_TYPE 区分按处理人设置还是按发起人设置START_DATE 和 END_DATE 划出代理窗口CANCEL_DATE 加 CANCEL_FLAG 做软取消——不物理删除因为代理期间产生的单据还要能追溯是谁代谁处理的。AGENT_DETAIL 用 APP 字段按应用维度拆分一个代理可以只对某几个模块生效AGENT_SCOPE 则存发起人范围用 ENTITY_TYPE 加 ENTITY_ID 再走一次多态引用。-- 某人当前生效的代理关系时间窗口 未取消 排除离职交接 SELECT ID, AGENT_ID, AGENT_TO_ID, AGENT_TYPE, START_DATE, END_DATE FROM AGENT WHERE CANCEL_FLAG 0 AND START_DATE :now AND (END_DATE IS NULL OR END_DATE :now) AND (AGENT_ID :memberId OR AGENT_TO_ID :memberId) -- 双向查询 ORDER BY START_DATE DESC;注意 END_DATE 的判空很多实现把「长期有效」存成 NULL也有存成 9999-12-31 的两种写法在同一套系统里并存是常有的事查询必须兼容。另外 AI_DEAL_CONDITION 表把「自动处理条件」做成了可配置TEMPLATE_ID 定位流程模板SENDER_ID 和 USER_ID 分别是发起人和处理人DEAL_TYPE 枚举 0 回退、1 指定回退、2 撤销、3 终止、4 不同意、5 处理时长SIGNLE_VIEW_PERIOD 存处理时长阈值。把操作类型和时长指标塞进同一张条件表好处是一条规则能同时表达「谁在什么操作下、超过多久」就触发坏处是 DEAL_TYPE 5 时其他字段的语义就变了读代码的人很容易误解。4. 考勤模块的三层数据流水、日统计、归档各管一段4.1 排班链TEAM 到 ARRANGE 到 CLASS 到 FIX_TIME考勤的配置是一棵树从根往下读ATTENDANCE_TEAM 是考勤组带 IS_NEW、START_DATE、END_DATE 三个字段做版本化——考勤规则按生效日期切换历史统计必须按当时的规则算所以旧版本不删只把 IS_NEW 置 0。ATTENDANCE_ARRANGE 是排班0 固定排班、1 周期排班ATTENDANCE_CLASS 是班次CLASS_TYPE 表示一天 1 次、2 次还是 3 次FLEX_TIME 是弹性时间LATE_SERIOUS 是严重迟到阈值ABSENT_WORK 是旷工判定LEAVE_FIX_TIME 和 ATTEND_FIX_TIME 是允许晚走和晚到的宽限再往下 ATTENDANCE_FIX_TIME 存每一段的具体时间点WORK_TIME、END_TIME、EARLY_WORK_TIME最早可签到、LAST_END_TIME最晚可签退以及 ATTEND_REMIND 和 LEAVE_REMIND 两个提醒开关。ATTENDANCE_DAY 是这条链的落地某天对应哪个排班、哪个班次、是不是工作日。有一处细节值得停下来看LATE_SERIOUS、ABSENT_WORK、FLEX_TIME 这些明明都是「分钟数」的字段类型是 VARCHAR(50)。存成字符串之后凡是涉及比较和排序的地方都得先转数字跨库查询时还可能因为隐式转换把索引废掉。稳妥的做法是在应用层统一转换成分钟整数再比较别指望数据库替你做。4.2 ATTENDANCE_INFO 与 ATTENDANCE_HISTORY结构与用途的差异这两张表字段高度重合OWNER_ID、DEPT_ID、SIGN_TIME、SIGN、LONGITUDE、LATITUDE、COUNTRY、PROVINCE、CITY、TOWN、STREET、NEAR_ADDRESS、ADDRESS_CODE、ADDRESS_TYPE、YEAR/MONTH/DAY、IMG_INFO、RECORD_INFO。差异才是信息所在。差异点ATTENDANCE_INFOATTENDANCE_HISTORYSIGN 长度VARCHAR(2000)VARCHAR(500)STATE有3 上班迟到 / 4 下班早退 / 5 正常上班 / 6 正常下班无MODIFY_NUM有记录签到修改次数无DEVICE_INFO / MAC_ADDRESS有设备 ID 与 WIFI Mac无IS_WORK_DAY有无年月日冗余列有有用途活数据可改可申诉带防代打卡指纹已归档只读报表SIGN 字段在两张表长度不一致直接说明 INFO 表后期扩过列原来只存地址或 IP后来把定位描述一起拼进去2000 才够。STATE 的枚举从 3 开始而不是从 0 或 1 开始是另一个信号——1 和 2 曾经代表过别的含义语义变更之后就地废弃没人敢复用。这种「编号断档」在老系统里到处都是看到枚举缺号正确的反应是去代码里找历史映射而不是自己补上 0 和 1。至于为什么留两份结构相近的表ATTENDANCE_INFO 是写入热点每秒都在插还要支持修改和申诉索引要围绕 OWNER_ID 和 PUNCH_DATE 建ATTENDANCE_HISTORY 是只读归档数据量大但查询模式单一可以按月分区、可以压缩、可以放冷存储。拆开之后归档动作不会跟在线写入抢锁。IMG_INFO 和 RECORD_INFO 用 VARCHAR 存 JSON 而不是拆子表理由也类似图片和语音是补充证据按图片维度反查的需求几乎没有拆表只会增加一次 join。4.3 ATTENDANCE_DAY_STATISTICS把计算前移到写入时这张表是典型的预聚合宽表一人一天一行AM_START_TIME、AM_END_TIME、PM_START_TIME、PM_END_TIME 四个时间点加上四个对应的状态位再加上 NORMAL_DAY正常出勤天数、AB_NORMAL_DAY异常天数、NONWORKDAYS_DAY非工作日打卡天数、LATE_NUM、LEAVE_EARLY_NUM、OUTSIDE_NUM、MISSINGCLOCK_COUNT、WORKING_MISSINGCLOCK、KNOCKOFF_MISSINGCLOCK、WORKING_MISSINGCLOCK、PUNCH_CLASS应打卡次数 1 或 2。一行的列数看着吓人但它把「算」的成本从读时挪到了写时。-- 月度报表从日统计直接 SUM不去碰流水表 SELECT MEMBER_ID, SUM(NORMAL_DAY) AS 正常出勤, SUM(AB_NORMAL_DAY) AS 异常天数, SUM(LATE_NUM) AS 迟到次数, SUM(LEAVE_EARLY_NUM) AS 早退次数, SUM(OUTSIDE_NUM) AS 外勤次数, SUM(MISSINGCLOCK_COUNT) AS 缺卡总数 FROM ATTENDANCE_DAY_STATISTICS WHERE ACCOUNT_ID :accountId AND PUNCH_DATE :monthStart AND PUNCH_DATE :nextMonthStart GROUP BY MEMBER_ID;这条 SQL 之所以能跑得快全靠 PUNCH_DATE 上的索引和「一人一天一行」的粒度。如果换成从 ATTENDANCE_INFO 现场算就要按人按天分组、判断工作日、比对排班时间、判定迟到早退一次月度查询可能扫几十万行流水。预聚合的代价是补卡、申诉、规则变更之后必须重算那一天的统计行重算漏了就会出现「流水改了但报表没变」的数据不一致。PUNCH_CLASS 字段就是重算时的依据之一——它告诉你这一天应该打卡几次缺卡数才能算对。4.4 地理与附件为什么经纬度不按规范存按数据库设计规范经纬度应该用 DECIMAL比如 DECIMAL(10,6)这套字典里 LONGITUDE 和 LATITUDE 都是 VARCHAR(50)。原因不难推签到定位的数据来自第三方地图接口接口返回的就是字符串直接落库最省事也不用处理空串、空格、负号、精度不一致这些情况。代价在处理侧——要算「是否在围栏内」就得先 CAST 成 DECIMAL 或者交给应用层算而 CAST 一旦碰上空串就是报错而不是 NULL。所以正确做法是入库前统一格式化成固定小数位字符串查询时用正则先过滤再转换绝不能假设这一列一定是合法数字。ATTENDANCE_SETTING 里的 LONGITUDE、LATITUDE、ATTEND_REMIND、AVAILABLE 是围栏配置RELATIVE_ID 用来存第三方系统导入的围栏 ID这条设计说明围栏数据可能来自外部进一步解释了为什么地理字段全程按字符串处理。5. 排查与避坑读这份数据字典时最容易翻车的五个地方5.1 扩展字段只看到一个人或者干脆是空现象明明在表单上选了三个审批人查 EXT_ATTR_41 只看到第一个人的 ID后面的人不见了。原因41 到 50 段位定的是 VARCHAR(50)一个 BIGINT 主键转成字符串大概 10 到 20 位三个人拼起来必然超长写入时被数据库截断或者被应用层截断。解决先按主键查是否只有一个 ID确认是截断然后判断这个业务到底需要单选还是多选多选就必须另建关联表或者把这段改成 VARCHAR(1024)不能靠扩长度硬撑。排查脚本就一句SELECT LENGTH(EXT_ATTR_41), EXT_ATTR_41 FROM ADDRESSBOOK WHERE LENGTH(EXT_ATTR_41) 20;。5.2 通讯录里某人看不到但设置明明是「全部可见」现象用户反馈通讯录搜不到某个同事管理员进设置页看查看范围是全单位。原因ADDRESSBOOK_SET_SCOPE 里 ADDRESSBOOK_SET_TYPE 有 1、2、3 三种含义分别对应查看范围、关键信息、导出与打印。查询可见性时漏了这个条件就会把「导出权限」的明细误当成可见范围或者反过来把本该可见的实体过滤掉。解决所有涉及这张表的查询都必须显式带上ADDRESSBOOK_SET_TYPE 1并且用 ADDRESSBOOK_SET_ID 关联到本单位ACCOUNT_ID的设置别用全局设置去覆盖单位设置。5.3 签到距离算出来是负数报表里出现一堆异常现象围栏判断时抛出数字转换异常或者距离算出来明显不对。原因LONGITUDE、LATITUDE 是 VARCHAR里面可能有空串、前后空格、超过合理范围的脏值甚至有人在多地点打卡时把两个坐标拼在一列里。直接 CAST 就会报错或者得到错值。解决转换前先用正则白名单过滤^-?\d{1,3}(\.\d)?$过滤后再判范围经度 -180 到 180纬度 -90 到 90不合法的一律当未定位处理而不是当 0 处理——当 0 会让所有异常点落在赤道附近报表看着像有人在南美打卡。5.4 报表人数比通讯录少或者翻倍现象人员总数统计出来跟通讯录对不上。原因状态位没过滤干净。这套字典里的状态至少有四种形态——BBS 系列表里的 STATE 是 0 正常 1 删除AGENT 里的 CANCEL_FLAG 是 0 未取消 1 已取消ATTENDANCE_TEAM 的 IS_NEW 是 0 不是最新 1 是最新ATTENDANCE_NO_REMIND_MEMBER 的 STATE 是 0 正常 1 废弃。这些字段名不一样、取值含义也不统一任一漏掉都会串数据。解决给每张表建一份「必带条件」清单写查询前先对照更彻底的做法是在数据访问层把这几类表包一层视图把状态条件固化进去。5.5 跨单位查询串数据或者同一个 ID 出现两条记录现象多单位部署下A 单位的报表里出现了 B 单位的人。原因人员 ID 在不同单位下可能重复所有业务表都冗余了 ACCOUNT_ID 或 ORG_ACCOUNT_ID 做隔离键但查询时忘了带。ATTENDANCE_HISTORY、ATTENDANCE_DAY_STATISTICS、BBS_ARTICLE、AI_ORG_CHANGE_RECORD 都带这个字段它不是冗余而是必须的过滤条件。解决联合索引一律以 ACCOUNT_ID 打头比如 (ACCOUNT_ID, PUNCH_DATE, MEMBER_ID)既能保证隔离又能让范围查询走上索引并且约定所有查询构造器默认注入当前单位。6. 设计取舍宽表、冗余统计和无外键值不值6.1 宽表的实际代价比想象的小但不是没有边界很多人看到 70 个 EXT_ATTR 第一反应是「这么设计不规范」。先算一笔账VARCHAR 和 DATETIME 在 InnoDB 里是变长存储NULL 值只占 NULL 位图里的一个 bit数据区不分配DECIMAL(19,4) 是定长 9 字节左右。70 个扩展位全空时每行真正多出来的只有一个 NULL 位图加上变长列的偏移数组几字节到几十字节量级。所以在「扩展字段大面积空置、少数人用满」的分布下宽表的存储代价不算高换来的是免 join、强类型、ORM 直接映射三件事。真正的边界在列数上限和 DDL 成本列数逼近三位数之后任何一次表结构变更都是高风险动作所以扩展位只能一次预留够这也是为什么它一上来就是 70 个而不是 10 个。6.2 预聚合与无外键两个方向的取舍ATTENDANCE_DAY_STATISTICS 把迟到次数、缺卡数这类指标在写入时就固化是拿「一致性维护成本」换「读性能」。这个交换在考勤场景里划算因为读远多于写而且写入路径是单点的签到服务重算可以由同一个服务触发。但如果换到工单、合同这种数据随时被修改的场景预聚合会变成负担改一次数据要重算一串统计。无外键的取舍同理OA 的组织架构调整频率高到无法承受外键约束所以接受脏数据风险转而用 AI_ORG_CHANGE_RECORD、AI_ORG_MEMBER_CHANGE 这类变更记录表加上定时巡检来做一致性兜底。这套设计能成立前提是「组织调整是低频但影响面大的操作」可以接受用批处理补偿而不是要求数据库实时保证。6.3 我自己的三条自检习惯拿到一份新版数据字典我一般先做三件事。第一grep 所有状态类字段STATE、FLAG、IS_NEW、CANCEL_FLAG把取值含义列成表因为这类字段的编号断档和老语义是数据错乱的源头。第二grep 所有带 ACCOUNT_ID、ORG_ACCOUNT_ID 的表确认隔离键没有遗漏多单位部署下的串数据问题一旦上线很难回溯。第三把 EXT_ATTR 的段位表抄一份放进项目文档任何读写扩展字段的代码都必须引用这个唯一来源禁止硬编码下标。这三件事花了不到一小时但省下来的排查时间远不止于此。有一次做考勤报表我图省事直接从流水表现算月度迟到次数结果对不上人力的口径——因为漏了「非工作日打卡不计迟到」这一条而这条规则只体现在日统计表的 IS_WORK_DAY 判定里。从那以后我每次碰这类有预聚合表的模块都强制先把「流水、日统计、归档」三层的字段差异拉出来对比一遍再动查询。这份 V8.1 数据字典把通讯录、代理、自动处理、组织调整、考勤、讨论区的表结构和字段含义都摊开了正好可以拿它做一次逐表梳理把上面这些坑在自己系统里对照检查一遍。希望帮到你。本文还有配套的精品资源点击获取