致远OA V8.1数据字典解读：表结构、字段注释与业务模型还原

简介：致远OA V8.1 数据字典以单份PDF文档形式呈现，面向致远OA二次开发、数据库设计、系统运维与接口集成人员，帮助解决表结构不清、字段含义难追溯、数据建模与SQL编写缺少依据等问题。压缩包仅含1个PDF文件，大小约2.2MB，轻量便于随查随用；文档以数据表为线索，列出字段名称、数据类型、是否强制及中文注释，并覆盖主键、人员ID、创建与修改时间等基础字段。内容中可见ADDRESSBOOK、ADDRESSBOOK_MEMBER等通讯录相关表，扩展字段按文本、数字、日期、枚举、选人、选部门、选岗位等类型成组划分，能辅助读者理解企业组织与联系人数据的存储方式。已有2611人学习，适合在系统升级、迁移、报表开发、流程对接和排错时作为字段核对与结构梳理的参考，提升数据库设计与维护效率。

1. 数据字典到底是什么：一份让表结构自己开口说话的说明书

接手一套陌生的业务系统，最难受的时刻往往不是看不懂代码，而是打开数据库那一瞬：几十张表、上千个字段，名字全是 ADDRESSBOOK、EXT_ATTR_37、STATES 这类缩写，注释栏还空着。致远OA V8.1 数据字典要解决的就是这个场面——它把库里每张表、每个字段的名字、数据类型、是否必填、中文注释整理成一份能逐条查的清单。打个比方，它像搬家时给每个纸箱贴的标签，箱子还是那些箱子，但你能在三十秒内翻出那只装了螺丝刀的。标签写得越细，后来接手的人少走的弯路越多；标签写得含糊，一个字段就能让人耗掉半天。

2. 为什么需要一个数据字典：字段名背后到底藏着多少信息

2.1 一次猜字段的翻车

一个很常见的场面：某开发者接了个基于致远OA V8.1 的二次开发任务，要在通讯录导出里加一列「所属部门」。他打开数据库，看到 ADDRESSBOOK 表里整整齐齐排着 EXT_ATTR_51 到 EXT_ATTR_60 十个字段，注释写着「选部门类型数据字段」，类型是 VARCHAR(50)。直觉告诉他，这十个字段里应该有一个存着部门名称，于是他写了一句SELECT EXT_ATTR_51，跑出来却是一大片空白。

折腾了小半天，他才弄明白两件事：这些字段存的是部门 ID 而不是部门名称；绝大多数记录压根没往里填值，因为标准通讯录的部门关系走的是另一条路。这就是没有数据字典时最典型的翻车——字段名和注释都在，只是没人告诉他「这条路默认是空的」。

翻过来看，如果当时手里有一份数据字典，情况会完全不同。看到注释写「选部门类型数据字段」，他就知道这个字段装的是指向组织模型的 ID，不是给人看的文本；看到它不标强制，就知道可能是空的，得先查填充率再决定要不要用。同一个字段，有没有注释，工作量能差出十倍。

数据字典真正值钱的地方，不在于它列了多少字段，而在于它把「猜」这件事变成「查」。猜错字段类型会报错，猜错字段语义会得到一片空白——后者更麻烦，因为不报错。

2.2 字典的一行到底记了什么：字段、类型、强制、注释

一份数据字典的每一条记录，通常只有四个信息位：字段名、数据类型、是否强制、中文注释。看着朴素，但这四样合起来，恰好覆盖了一个字段「怎么用」的全部前提。

拿 ADDRESSBOOK 表的开头几个字段做例子：

「强制」这一列对应的是数据库层面的 NOT NULL：TRUE 表示这个字段不许为空，写入时必须给值，否则语句直接失败；FALSE 表示可以为空，但不能反过来理解成「业务上允许留空」——很多字段技术上可空，实际上会被程序逻辑强制填充。这个区别在排查问题时很关键：一条记录里某个字段是 NULL，可能是业务没走到，也可能是程序漏了赋值，得结合注释和表间关系判断。

注释这一列是整份字典里信息密度最高的部分。它往往用一句话交代了三件事：这个字段装什么、装的是 ID 还是文本、有没有隐含约定。比如 ADDRESSBOOK_SET 表里的 KEY_INFO_TYPE，注释是「关键信息类型，1-手机号+职务级别 2-手机号 3-职务级别」，这一行字直接把枚举值全列出来了，不用再去翻代码。再比如 EXTERNAL_SCOPE 注释「编外人员权限设置 1（按工作范围显示）2（全部隐藏）」，光看字段名你永远猜不到 2 是「全部隐藏」。

反过来说，注释也有边界。它告诉你字段存在、类型是什么、枚举大概有哪几种，但它不解释业务规则是怎么算出来的，也不保证注释和实际代码永远一致。字典是地图，地图会过期，走之前最好对一眼实际路况。

2.3 EXT_ATTR 的编号段：七十个扩展字段不是乱编的

ADDRESSBOOK 表最扎眼的地方是那七十个 EXT_ATTR 字段。第一次看到的人多半会头皮发麻：一个通讯录条目，为什么要留七十个扩展位？

答案藏在编号规律里。这七十个字段不是随便堆的，而是按十个一组按类型分段：

看懂这个规律，收益很直接：拿到任意一个 EXT_ATTR 字段，看编号就能反推它的类型，不用每次都去翻字典。第 37 号落在 31~40 区间，那它必然是个枚举位；第 55 号落在 51~60，那它装的是部门 ID，别指望它是部门名称。

这套设计背后的取舍也值得琢磨。为什么不新建一张扩展表，用「一条记录一行」的方式存自定义字段？因为那要额外 JOIN，查询成本上去了。为什么不干脆让用户随便加列？因为加列要改表结构，生产环境上风险太大。折中方案就是预留固定数量的字段位，需要什么类型就从对应区间里取一个还没被占用的编号。代价是扩展位有上限，七十个用完了就没了，而且字段语义完全靠外部配置说明，字典里只能给到「文本类型扩展字段 1」这种通用注释，具体这个位被谁占了、叫什么名字，字典本身答不出来。

这一点很值得记住：扩展字段的编号规律能让你少查很多次字典，但要知道某个扩展位在业务上到底代表什么，还得去翻对应模块的配置。字典负责告诉你「这里有个盒子」，不负责告诉你「盒子里装的是谁的钥匙」。

3. 表名后缀就是一张地图：读懂命名规律

3.1 一个功能四张表：主表、明细表、设置表、范围表

刚接触这类系统的库结构，最容易产生的错觉是「表太多了」。其实表多不代表模型复杂，很多时候是一个功能被拆成了几张职责不同的表。通讯录这一块就是典型：

看出来了吧，这里有三组「主表 + 从表」的关系。ADDRESSBOOK_SET 存的是设置本身，比如查看范围、关键信息显示什么、能不能导出打印；ADDRESSBOOK_SET_SCOPE 存的是这条设置对谁生效，靠 ADDRESSBOOK_SET_TYPE 区分是查看范围、关键信息还是导出打印权限，靠 USER_TYPE 标识是人员还是部门。换句话说，「谁能看到通讯录的哪些信息」这个问题的答案，不是某个字段里的一个值，而是两张表拼出来的一组记录。

这就是读这类库结构的第一个心法：遇到一个功能，先别急着找「主表在哪」，先看有没有同名前缀的一串表。后缀通常就是职责标签，_MEMBER 是从属实体，_SET 是配置，_SCOPE 是作用范围，_TEAM 是分组，_DETAIL 是明细。

一个简单的对照能说明这套约定的价值：如果只有 ADDRESSBOOK_SET 而没有 _SET_SCOPE，你会以为「查看范围」是一个全局设置；看到 _SCOPE 表，你才知道它是可以按人、按部门分别配的。少看一张表，理解就偏一层。

3.2 V3X_ 前缀与 STATES 字段：历史包袱怎么认

BBS_ARTICLE 表里有一批名字很别扭的字段：V3X_BBS_BOARD_ID、V3X_BBS_ARTICLE_ID。第一次看到会以为这是跨库引用或者某种加密命名，其实不是。这类前缀是历史版本遗留的命名习惯，字段实际指向的就是同库的 BBS_BOARD 和 BBS_ARTICLE。老系统迭代时，表名改过、字段名没跟着改干净，前缀就这么留了下来。

对读字典的人来说，这类字段的处理原则很简单：看注释和类型，别被前缀唬住。V3X_BBS_BOARD_ID 是 BIGINT，注释写版块 ID，那就当普通外键用，前缀忽略即可。

同一张表里还有一类字段值得单独拎出来说：STATES。BBS_ARTICLE、BBS_ARTICLE_REPLY 都有它，注释是「0：正常、1：删除」。这是典型的软删除标记——记录不真删，只改标记，查询时统一带上STATES = 0。类似写法在这套库里很普遍，只是字段名不完全统一，有的叫 STATES，有的叫 CANCEL_FLAG，有的叫 AVAILABLE。

提示：看到 SMALLINT 类型、注释里带「0-否 1-是」这类描述的字段，先按布尔或状态标记处理，别当业务数值用。

软删除带来一个实际影响：统计数量时如果不加状态条件，结果会偏大。这不是字典能提醒你的，但字典给了你发现它的线索——只要看到 STATES 这个字段存在，就该问一句「默认值是几，查询要不要过滤」。

3.3 三种数据类型撑起整库：BIGINT、SMALLINT、DATETIME

把整份字典的类型分布扫一遍，会发现高频类型就那么几种：

BIGINT 做主键这件事，最容易被低估。用 INT 类型的变量去接 BIGINT 字段，在小数据量下不会报错，等 ID 长过 21 亿就开始溢出，排查起来相当玄学。同样，DECIMAL(19,4) 说明这个字段是给精确数值准备的，别用浮点类型去接，否则小数位会飘。

想把字典里的字段清单落到实际查询，可以直接从元数据里拉，不必手抄：

-- 从元数据表里取出一张表的字段清单，按建表顺序排 SELECT COLUMN_NAME, -- 字段名，如 EXT_ATTR_41 DATA_TYPE, -- 数据类型，如 varchar CHARACTER_MAXIMUM_LENGTH AS len, -- 长度，1024 / 50 这类 IS_NULLABLE, -- NO 表示必填，对应字典里的「强制 TRUE」 COLUMN_COMMENT -- 中文注释，信息量最大的一列 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = 'your_db' -- 换成实际库名 AND TABLE_NAME = 'ADDRESSBOOK' ORDER BY ORDINAL_POSITION; -- 保持建表时的字段顺序

这段查询里，IS_NULLABLE和字典的「强制」列是一一对应的，NO 即强制为 TRUE；COLUMN_COMMENT就是那份中文注释；ORDINAL_POSITION排序能把 EXT_ATTR 的编号顺序还原出来，方便确认 1~10 确实是文本段。实际使用时把库名和表名换掉即可，字段名不用改。

要注意一种情况：字典文档和实际库对不上。文档是某个时间点的快照，系统打过补丁之后可能多出字段或者注释被改过。两边冲突时以实际库为准，再把差异记下来——这种差异本身就是排查问题的线索。

4. 四个容易踩的误区：数据字典和你想的可能不一样

4.1 数据字典不是数据库：元数据与业务数据是两层楼

最常见的混淆，是把「数据字典」理解成「数据库里的一份数据」。两者确实都在库里，但层次完全不同。业务数据是通讯录里的联系人、考勤里的打卡记录；数据字典描述的是这些表本身长什么样——有哪些字段、什么类型、能不能为空。

打个比方，业务数据是仓库里的货，数据字典是货架上的标签和货位图。你把货全搬走，标签还在；你把标签撕了，货还在但没人找得到。

区分方法很简单：数据字典的查询对象是表结构，返回的是字段名、类型、注释；业务数据查询返回的是一行行记录。前者回答「这张表能装什么」，后者回答「这张表装了什么」。混为一谈的后果是，有人以为改字典就能改数据，或者以为字典里的字段一定都有值。

4.2 ADDRESSBOOK 与 ADDRESSBOOK_MEMBER：内部通讯录和外部联系人

这两个名字太像了，看第一眼很容易当成一张表的主从拆分。实际上它们装的是两类不同对象：ADDRESSBOOK 关联的是系统内部人员，靠 MEMBER_ID 指向人员 ID；ADDRESSBOOK_MEMBER 存的是外部联系人档案，字段是姓名、单位名称、部门、级别、岗位、手机、传真、邮箱、地址这一套。

为什么容易混？因为两者都在「通讯录」这个功能里，都有人名和联系方式，界面上也常出现在同一个页面。

怎么区分？看有没有 MEMBER_ID。带 MEMBER_ID 的是内部人员视角的条目，走组织模型；带 COMPANY_NAME、POSTCODE、WEBSITE 这类字段的是外部联系人档案，是独立维护的一批人。做统计时把两者加在一起算「通讯录总人数」，结果一定是错的。

4.3 逻辑外键不是外键：字典里为什么看不到 FOREIGN KEY

翻遍整份字典，你会发现字段注释里到处是「人员 id」「部门 id」「模板 ID」，但几乎找不到物理外键约束的痕迹。这些关联是靠程序保证的，数据库层面没有强制。

为什么容易混？因为注释写得太像外键了。看到 MEMBER_ID 注释「人员 id」，本能反应是「那它一定约束到人员表」。

怎么区分？看有没有可能为空、有没有可能指向一条已经不存在的记录。逻辑外键允许悬空，人员离职后历史记录里的 MEMBER_ID 依然保留，但对应人员可能已经不在组织模型里。所以写关联查询时要用 LEFT JOIN，别默认一定能匹配上；做数据清理时也不能简单按「孤儿记录」就删。

4.4 STATES 的 0 和 1：别把删除标记当状态枚举

STATES 这个字段名带个复数 S，看着像状态集合，实际含义往往只有两个值：0 正常，1 删除。AGENT 表里类似语义的字段叫 CANCEL_FLAG，BBS_ARTICLE 里叫 STATES，ATTENDANCE_NO_REMIND_MEMBER 里叫 STATE 且注释是「0-正常 1-废弃」。

为什么容易混？因为同一个库里，STATE 和 STATES 两种写法都存在，而且有的表里 STATE 真的是多值状态码——ATTENDANCE_INFO 的 STATE 注释是「3-上班迟到 4-下班早退 5-正常上班 6-正常下班」，完全是另一套语义。

怎么区分？只看注释不够，得看取值范围。注释里出现「0-否 1-是」「0-正常 1-删除」这类两值描述的，按布尔处理；出现三个以上枚举值的，按状态码处理。查询过滤时，前者写STATES = 0，后者要按具体码值判断，两者混用会导致统计结果整段偏移。

5. 从通讯录到考勤：数据字典里的业务模型怎么还原

5.1 通讯录：可见性不是一个字段，是一组记录

把通讯录相关的六张表串起来，一个完整的模型就浮出来了。

ADDRESSBOOK 是条目表，一个内部人员的通讯录信息对应一条记录，靠 MEMBER_ID 挂到人员上，靠 TYPE 区分条目类别，七十个扩展字段兜住各单位的自定义需求。ADDRESSBOOK_MEMBER 是外部联系人档案，独立维护，靠 CREATOR_ID 记录谁建的、CATEGORY_ID 做归类。ADDRESSBOOK_TEAM 和 ADDRESSBOOK_TEAM_MEMBERS 管分组，TYPE 字段把组分成三类：0 系统组、1 个人组、2 私人通讯录。

真正体现设计意图的是 ADDRESSBOOK_SET 和 ADDRESSBOOK_SET_SCOPE 这一对。ADDRESSBOOK_SET 里放着 VIEW_SCOPE（查看范围）、KEY_INFO（关键信息）、KEY_INFO_TYPE（关键信息类型，1 手机号+职务级别、2 手机号、3 职务级别）、EXPORT_PRINT（导出打印）、DISPLAY_COLUMN（显示列头），还有 M3_SET、ZX_SET 这类给不同客户端单独配显示字段的开关。一条设置到底对谁生效，答案在 ADDRESSBOOK_SET_SCOPE 里：ADDRESSBOOK_SET_TYPE 标明这是查看范围、关键信息还是导出打印权限，USER_ID 和 USER_TYPE 标明作用对象是哪个组织模型实体。

这套拆法解决了一个现实问题：同一个通讯录，管理层能看手机号，普通员工只能看姓名和部门，导出权限还要单独控制。如果把这些规则塞进一个字段，配置组合会爆炸；拆成「设置 + 范围」两张表，每条规则一行记录，加一条规则就是插一行，逻辑清楚得多。

5.2 考勤：组、排班、班次、时间点，四层套下来

考勤这块表最多，但只要抓住分层，反而不乱。

最上层是 ATTENDANCE_TEAM，考勤组。它记录组名、创建人、考勤组管理人员、所属单位，还有 IS_NEW、START_DATE、END_DATE 三个字段——这说明考勤组是带版本的概念，改一次配置不是原地覆盖，而是结束旧版本、开一个新版本，历史打卡记录仍然挂在旧版本上，不会因为改规则而失真。

第二层是 ATTENDANCE_ARRANGE，排班。ARRANGE_TYPE 只有两个值：0 固定排班、1 周期排班。它把考勤组和具体的班次安排连起来。

第三层是 ATTENDANCE_CLASS，班次。CLASS_TYPE 说明一天要打几次卡：0 一天一次、1 一天两次、2 一天三次。这一层还放着规则参数——FLEX_TIME 弹性时间、LATE_SERIOUS 严重迟到、ABSENT_WORK 旷工、LEAVE_FIX_TIME 晚走多少时间、ATTEND_FIX_TIME 晚到多少时间。注意这些字段的类型都是 VARCHAR(50)，不是整数：它们存的是配置值或表达式，具体怎么解释要看程序，字典只能告诉你「这里有个阈值」。

第四层是 ATTENDANCE_FIX_TIME，班次的具体时间点：WORK_TIME 上班时间、END_TIME 下班时间、EARLY_WORK_TIME 最早签到时间、LAST_END_TIME 最晚签退时间，外加 ATTEND_REMIND、LEAVE_REMIND 两个提醒开关。固定排班的场景下，一个班次对应一条或几条这样的时间记录。

再往下就是数据层。ATTENDANCE_INFO 存当前打卡记录，字段非常具体：SIGN 存打卡地址或 IP，LONGITUDE、LATITUDE 存经纬度，CONTINENT 到 STREET 一整串存逆地址解析结果，TYPE 区分 1 签到、2 签退、3 外勤，STATE 用 3 上班迟到、4 下班早退、5 正常上班、6 正常下班四个码值标结果，MAC_ADDRESS 存 WIFI 地址，IMG_INFO、RECORD_INFO 用 JSON 存图片和语音附件信息。ATTENDANCE_HISTORY 是同构的历史表，额外冗余了 YEAR、MONTH、DAY 三个字段，方便按天归档查询。

统计层是 ATTENDANCE_DAY_STATISTICS，一天一条，把上午签到、上午签退、下午签到、下午签退四个状态，加上正常天数、异常天数、迟到次数、早退次数、外勤次数、缺卡总数、上班缺卡、下班缺卡全部预先算好。这张表的存在说明一件事：出勤统计不是实时算的，是每天跑一次落下来的。

还有两张容易漏掉的表。ATTENDANCE_SETTING 管地理围栏，存中心点经纬度、范围、过滤类型、过滤实体，RELATIVE_ID 还留着接第三方系统导入的围栏 ID；ATTENDANCE_REMIND 和 ATTENDANCE_NO_REMIND_MEMBER 管提醒，前者配置签到签退是否提醒、提前几分钟，后者是一份免打扰名单。

把这套结构串起来看，一个「早上打卡迟到」的判定链条就清楚了：考勤组决定规则版本，排班决定这天用哪个班次，班次决定应打卡次数和迟到阈值，时间点决定上班时间，打卡记录记下实际时间和位置，日统计把结果汇总成一次迟到。任何一环配置错了，最后的数字都会歪，而字典能帮你快速定位是哪一环。

5.3 代理与离职交接：一张 AGENT 表扛了两种业务

AGENT 表的名字很朴素，注释是「代理设置应用表」，但它承担的业务比名字多。

表里的核心是两个人：AGENT_ID 代理人、AGENT_TO_ID 被代理人。围绕这两个 ID，START_DATE 和 END_DATE 划定代理期限，CANCEL_DATE 和 CANCEL_FLAG 记录取消状态，AGENT_REMIND、AGENT_TO_REMIND 控制双方是否收到提醒。

真正有意思的是两个区分字段。AGENT_TYPE 用 1 表示代理设置、2 表示离职交接——也就是说，日常代办和人员离职后的工作移交，在这套模型里是同一张表的两类记录。AGENT_OPERATION 用 0 表示被代理人自己操作、1 表示集团管理员、2 表示单位管理员，说明这个设置可以由本人发起，也可以由管理员代为发起。MATTER_TYPE 用 0 表示按处理人设置、1 表示按发起人设置，默认值是 1，这决定了代理规则是按「谁来处理」还是按「谁发起的」生效。

代理的适用范围拆在另外两张表里。AGENT_DETAIL 存代理 ID 加应用（APP）和实体 ID，说明代理可以精确到某个应用模块下的某类对象。AGENT_SCOPE 存发起人范围，ENTITY_TYPE 是实体类型名（比如 ACCOUNT、DEPARTMENT），ENTITY_ID 是对应实体的 ID——这解释了为什么代理可以配成「只有某几个部门发起的事项才转给我」。

把三张表连起来读，一条代理规则的完整形态就出来了：谁代理谁、什么时间段、哪些应用的对象、哪些发起人范围、要不要提醒。这套拆法比把所有条件塞进一行要灵活得多，代价是查询时必须连表，少连一张就会漏掉范围限制。

6. 什么时候该翻数据字典，什么时候它帮不上忙

数据字典是好东西，但它不是万能的。判断标准其实很简单：你要回答的问题，是「结构问题」还是「逻辑问题」。结构问题它答得又快又准，逻辑问题它只能给你线索。

最该翻字典的三个时机：第一次接触一套陌生库结构时，先扫一遍表名和字段注释，对整个系统建立轮廓；接手别人写的报表或接口时，核对字段类型和可空性，避免用 INT 接 BIGINT 这类低级错；做数据迁移或对接时，逐字段对照长度和精度，尤其是 VARCHAR(50) 和 VARCHAR(1024) 的差别，短了会截断、长了浪费。

最不该指望字典的三个场景：想知道某个业务规则的具体算法，字典里只有字段名，没有公式；想搞清楚数据从哪来到哪去，字典描述静态结构，不描述调用链；想优化一条慢查询，索引和执行计划不在字典的覆盖范围内。这三种情况，字典最多帮你定位到「问题可能在这张表」，剩下的得靠自己读代码、看配置、跑执行计划。

我踩过最典型的一次坑，是拿着数据字典去解释一个统计报表的数字对不上。当时判断依据是 ATTENDANCE_DAY_STATISTICS 里的 LATE_NUM 字段，注释写得清清楚楚「迟到次数」，我就默认它是按打卡记录实时汇总的。结果发现这张表是每天定时任务跑出来的，跑完之后如果有人补卡或者修改了打卡记录，统计值不会自动回算，必须重跑任务。字典里没有任何一个字提到这件事——它只说了字段是什么，没说字段怎么来的。那次之后我养成了一个习惯：凡是看到 _STATISTICS、_COUNT、_SUM 这类后缀的字段或表，先问一句「这是实时算的还是落库的」，再决定信不信它。从那以后我每次碰一张不熟悉的表，都强制先拉一遍字段注释和同前缀的兄弟表，再动手写第一行 SQL。

希望这份梳理帮到你，下次面对一屏陌生表名时，至少知道先看哪一列。

本文还有配套的精品资源，点击获取