企业官网建设流程全解析

简介：致远OA V8.1数据字典是一份面向致远OA系统开发、实施及运维人员的技术参考文档，主要用于梳理数据库核心表结构、字段类型与约束信息，帮助理解系统底层数据设计，解决二次开发、数据迁移和报表取数中的结构盲区。文件以单个PDF形式打包，压缩后大小约2.2MB，内容完整展现了通讯录（ADDRESSBOOK）等业务表的字段定义，包括主键ID、人员MEMBER_ID、创建与修改日期，以及EXT_ATTR系列扩展字段，分别对应文本、数值、日期、枚举、选人、选部门和选岗位等类型，配置规则清晰易查。该资源已有2604人学习浏览，在OA实施与维护场景中具有较高的参考价值。通过这份数据字典，读者可以快速定位常用业务模块的数据存储逻辑，理解扩展字段的业务含义，从而提升定制开发效率、降低误操作风险，是从事致远OA相关工作的实用工具。

1. 致远OA V8.1 数据字典：一张通讯录表背后的十几个数据表

接到一个二次开发需求，让我把致远OA V8.1 的通讯录和考勤数据同步到第三方 HR 系统。对方直接丢来一串库表名，我对着数据库一张张翻注释，光确认表关系就折腾了一下午。后来拿到这份覆盖 V5 到 V8.1 的数据字典，才发现通讯录根本不是一张表的事——主表之外还挂着成员表、设置表、范围表、个人组表，考勤那边更夸张，排班、班次、打卡明细、日统计分成了七八张表。这篇笔记就按我实际拆表的顺序，把致远OA V8.1 数据字典里通讯录、代理、考勤、讨论这几个核心模块的表结构讲透，字段怎么读、关联怎么走、查询怎么写、坑在哪，一次说清。适合要做集成、写报表、排查数据不一致的开发和实施人员。

2. 通讯录表族：ADDRESSBOOK 四张主表与 70 个扩展字段

2.1 主表 ADDRESSBOOK：从 ID 到 MEMBER_ID 的流转

先看通讯录核心表 ADDRESSBOOK。这份字典里表注释写的是“V5 数据字典”，但表结构在 V8.1 里仍然沿用，字段类型和注释基本没动。主表字段不多，核心是 ID 和 MEMBER_ID 这两个字段的配合。

ID 是 BIGINT 类型的主键，强制必填，负责唯一标识一条通讯录记录。MEMBER_ID 是人员 ID，非必填，指向组织人员表里的成员。CREATE_DATE 和 UPDATE_DATE 是创建、修改时间，做增量同步时直接拿 UPDATE_DATE 当水位线就行，不用去翻操作日志。

这里有个细节值得注意：ADDRESSBOOK 主表本身并不存联系人的姓名、手机号这些业务字段，它更像一个“壳”，真正的联系人信息在 ADDRESSBOOK_MEMBER 表里。拆字典的时候别被表名带偏，ADDRESSBOOK 是通讯录实例表，ADDRESSBOOK_MEMBER 才是联系人明细表。对照关系可以理解为：一条通讯录记录在自己的容器里，每个容器装若干个联系人成员。

主表里最值得展开的是那组 EXT_ATTR 扩展字段，一共 70 个，分五段，不同段对应不同类型。这块内容多，单独放一节讲。

SELECT ID, MEMBER_ID, CREATE_DATE, UPDATE_DATE FROM ADDRESSBOOK WHERE UPDATE_DATE >= :lastSyncTime ORDER BY UPDATE_DATE;

这段 SQL 是同步任务的骨架。参数 lastSyncTime 是上次同步点位，每次跑完把最大 UPDATE_DATE 存回去。MEMBER_ID 非空时用它关联人员表拿姓名、部门；为空时说明这条通讯录记录没绑定人员，可能是手工建的纯外部联系人，处理逻辑要分开。实际项目里我用这个写法做增量抽取，一开始没注意 MEMBER_ID 可空，导致 JOIN 人员表时把空成员记录全丢了，后来加了个 IS NULL 分支才补齐。

2.2 EXT_ATTR_1 到 EXT_ATTR_70：四种类型分段的自定义字段

这是整个数据字典里最容易踩坑的地方。EXT_ATTR_1 到 EXT_ATTR_70 一共 70 个字段，不是随便排的，分成五个语义段：

为什么设计成这种分段？因为在 OA 的表单引擎里，管理员可以自定义表单字段，而这些自定义值最终落库时就落在固定编号的 EXT_ATTR 上。字段编号和类型固定，具体业务含义由单位自己的表单配置决定。比如某个单位在通讯录表单里加了一个“所属项目”文本框，对应值就可能存在 EXT_ATTR_1 里；另一个单位拿 EXT_ATTR_11 存“年度产值”，类型刚好是 DECIMAL(19,4)。

读字典的要点是：先确认单位实际启用了哪些自定义字段，再对应到具体的 EXT_ATTR 编号。单看数据字典只能拿到“第 31 到 40 个扩展字段是枚举类型”这层信息，拿不到“枚举值 1 代表什么”，后者得结合单位的表单配置或者去 OA 管理后台查。

EXT_ATTR_31 到 EXT_ATTR_40 这几个枚举字段尤其要注意。它们是 VARCHAR(50)，不是数字类型，但存的是枚举代码值。查询时如果拿数字直接等值匹配，数据库会做隐式转换，多数情况下能查出结果，但如果枚举值有前导零或者字母，隐式转换就直接翻车。我习惯在查询里显式写字符串匹配：

SELECT ID, MEMBER_ID FROM ADDRESSBOOK WHERE EXT_ATTR_31 = '01' OR EXT_ATTR_31 = 'A1';

参数说明：EXT_ATTR_31 是第一个枚举扩展字段，值来自单位自定义配置。这里用字符串写法是为了避免隐式转换。如果你确认枚举值都是纯数字，直接写 EXT_ATTR_31 = 1 也能跑，但一旦出现字母或前导零就废了。稳妥起见全部按字符串处理。

2.3 四张附属表怎么串：SET、SCOPE、TEAM、MEMBER

通讯录模块不止一张主表，完整字典里有 ADDRESSBOOK、ADDRESSBOOK_MEMBER、ADDRESSBOOK_SET、ADDRESSBOOK_SET_SCOPE、ADDRESSBOOK_TEAM、ADDRESSBOOK_TEAM_MEMBERS 六张表。我刚拿到字典时也是一头雾水，拆完之后关系其实很清楚。

ADDRESSBOOK 是主表，一个 ID 对应一条通讯录配置。ADDRESSBOOK_MEMBER 是成员表，通过自身 ID 关联 ADDRESSBOOK 的 MEMBER_ID，存联系人姓名、单位、电话、传真、邮箱这些具体字段。ADDRESSBOOK_SET 是设置表，存查看范围、关键信息、导出打印权限这些配置，其中 VIEW_SCOPE 字段控制谁能看到通讯录，KEY_INFO_TYPE 字段控制手机号和职务级别的显示方式。ADDRESSBOOK_SET_SCOPE 是设置的关联表，通过 ADDRESSBOOK_SET_ID 反查设置 ID，USER_ID 和 USER_TYPE 联动决定这条设置作用于哪个组织实体。

ADDRESSBOOK_TEAM 和个人组有关。NAME 是组名，TYPE 字段区分 0 系统组、1 个人组、2 私人通讯录，CREATOR_ID 标识建组人。ADDRESSBOOK_TEAM_MEMBERS 是组和成员的关联表，TEAM_ID 指向组，MEMBER_ID 指向成员。一张个人组表加一张关联表，典型的组-成员多对多设计。

给个完整的关联查询写法：

SELECT m.NAME, m.COMPANY_NAME, m.MOBILEPHONE, t.NAME AS TEAM_NAME FROM ADDRESSBOOK_TEAM t JOIN ADDRESSBOOK_TEAM_MEMBERS tm ON t.ID = tm.TEAM_ID JOIN ADDRESSBOOK_MEMBER m ON tm.MEMBER_ID = m.ID WHERE t.CREATOR_ID = :userId AND t.TYPE = 1;

这段 SQL 查某个人建的所有个人组及其成员。TYPE = 1 过滤出个人组，避开系统组和私人通讯录。逻辑说明：先拿 TEAM 表定位组，再用 TEAM_MEMBERS 桥表把组和成员关联起来，最后去 MEMBER 表取联系人字段。参数 :userId 是当前登录人的 ID，做数据权限控制时直接拼这个条件。实际业务里，个人组常被用来做审批流里的常用联系人分组，查这个表能还原用户的分组习惯。

3. 代理与考勤：AGENT 和 ATTENDANCE 表族怎么读

3.1 AGENT 代理表：双人双单位的字段设计

代理设置是 OA 里一个高频次要功能，但字典里字段读起来有点绕。AGENT 表核心是“谁代理谁、什么时候代理、代理什么”。AGENT_ID 是代理人 ID，AGENT_TO_ID 是被代理人 ID，两个字段都是 BIGINT，没有前缀区分，第一次看时很容易搞反。CREATE_DATE 是代理信息创建时间，START_DATE 和 END_DATE 是代理期限起止，CANCEL_DATE 是取消时间。

关键在几个状态字段。CANCEL_FLAG 是取消标记，0 未取消，1 已取消。AGENT_TYPE 是代理类型，1 代理设置，2 离职交接。AGENT_OPERATION 是操作类型，0 被代理人自己，1 集团管理员，2 单位管理员。MATTER_TYPE 是事项条件设置类型，0 按处理人设置，1 按发起人设置。这里有个细节：字典注释里写“默认值为 1”，不是 0。

还有 AGENT_OPTION 字段存代理选项，VARCHAR(50) 类型，但没有展开具体取值。HAS_AWAKE 字段注释直接写了“未使用”，说明这个字段是历史遗留。

实际查询代理关系时，最常见的需求是“某个人当前生效的代理”。注意这里有个坑：代理记录不是一条就完，同一个被代理人可能被多个人分批代理，也可能代理结束后又来一条新的。判断生效状态的正确姿势是查 CANCEL_FLAG = 0 AND START_DATE <= 当前时间 AND END_DATE >= 当前时间，不能只看有没有记录：

SELECT a.AGENT_ID, a.AGENT_TO_ID, a.START_DATE, a.END_DATE, u.NAME AS AGENT_NAME FROM AGENT a LEFT JOIN ORG_USER u ON a.AGENT_ID = u.ID WHERE a.AGENT_TO_ID = :targetUserId AND a.CANCEL_FLAG = 0 AND a.START_DATE <= NOW() AND a.END_DATE >= NOW();

参数 :targetUserId 是需要查询的被代理人 ID。这段 SQL 的核心是把取消的和未生效的全滤掉，只留当前生效的代理关系。逻辑说明：先按被代理人过滤，再查取消标记和时间窗口。如果 OA 版本里 START_DATE 存的是空值，说明代理设置没限制开始时间，这时时间条件要改成写成可空判断；我在项目里遇到过一次，某条代理记录 START_DATE 是 NULL，导致这条代理永远查不出来，后来把时间条件拆成 IS NULL OR 判断才恢复。

AGENT_DETAIL 表是代理明细，AGENT_ID 关联主表，APP 存应用编号，ENTITY_ID 存实体 ID。用于控制代理人在哪些应用模块生效。AGENT_SCOPE 表存发起人范围，IDENTITY_TYPE 和 ENTITY_ID 配合，指定代理设置只对哪些组织范围内的发起人生效。比如集团管理员设代理时，可以选择只对某个子公司的人生效，范围就落在这张表里。

3.2 ATTENDANCE 考勤表族：从 HISTORY 到 DAY_STATISTICS

考勤模块是致远OA 表最多的模块之一，整个字典里排到 ATTENDANCE_TEAM，得有十几张。按用途分组：

考勤组与排班：ATTENDANCE_TEAM 是考勤组，ATTENDANCE_ARRANGE 是排班，ATTENDANCE_CLASS 是班次，ATTENDANCE_DAY 是某天对应哪个班次。考勤组是顶层容器，排班挂在考勤组下面，班次挂在排班下面，DAY 表再排具体星期几上什么班。

打卡记录：ATTENDANCE_HISTORY 和 ATTENDANCE_INFO，两张结构很像，细节不同。HISTORY 的 SIGN 字段是 VARCHAR(500)，INFO 的 SIGN 是 VARCHAR(2000)。两张表都存打卡人员、部门、时间、定位信息、地址详情、图片数量、语音数量。INFO 表额外有 MAC_ADDRESS、DEVICE_INFO、PUNCH_TYPE、STATE 这些字段，STATE 字段直接标了考勤结果（3 上班迟到、4 下班早退、5 正常上班、6 正常下班）。

统计表：ATTENDANCE_DAY_STATISTICS 是核心统计出口，按人按天一条记录，AM_START_TIME 上午签到时间、AM_END_TIME 上午签退时间、PM_START_TIME 下午签到时间、PM_END_TIME 下午签退时间，还有对应的四个状态字段 AM_START_STATE、AM_END_STATE、PM_START_STATE、PM_END_STATE。NORMAL_DAY 出勤天数、AB_NORMAL_DAY 异常天数、LATE_NUM 迟到次数、LEAVE_EARLY_NUM 早退次数、OUTSIDE_NUM 外勤次数、MISSINGCLOCK_COUNT 缺卡总数。

这是一张宽表，设计目的就是让报表直接查它，不用再去逐条打卡记录里数。实际做考勤统计导出时，优先用这张表，别去 HISTORY 表做聚合，效率差距明显。

ATTENDANCE_SETTING 表是打卡范围设置，存围栏信息，LONGITUDE、LATITUDE、ATTEND_RANGE 三个字段配合定义了一个地理围栏，AVAILABLE 控制是否启用。这个围栏和考勤组的管理是分开的，考勤组管理员后台画围栏，考勤规则判断时再加载。做定位打卡功能时，判断逻辑是先找到人员所属考勤组，再查考勤组的 ATTENDANCE_SETTING 围栏，最后算距离；注意不同考勤组可能复用同一个围栏配置，别按组 ID 直接绑定。

3.3 表之间的关联字段

考勤表族里关联字段的命名不算统一，拆表时得靠注释辅助。ATTENDANCE_ARRANGE 有 ATTENDANCE_TEAM_ID 关联考勤组；ATTENDANCE_CLASS 有 ATTENDANCE_ARRANGE_ID 关联排班；ATTENDANCE_DAY 同时有 ATTENDANCE_ARRANGE_ID 和 ATTENDANCE_CLASS_ID，锁定某一天具体哪个班次。

打卡明细 HISTORY 和 INFO 表里有 TEAM_ID 和 RULE_ID，直接关联考勤组和规则，省了一层 JOIN——这也解释了为什么表结构看着冗余。日统计表 ATTENDANCE_DAY_STATISTICS 里 ACCOUNT_ID、DEPT_ID、TEAM_ID、RULE_ID、MEMBER_ID 五件套齐全，一个人员一条记录全带齐。这里有个容易搞混的点：TEAM_ID 是考勤组 ID，不是团队 ID，名字容易让人联想到业务团队。

还有一张 ATTENDANCE_FIX_TIME 表存班级的上下班时间段，WORK_TIME 上班时间、END_TIME 下班时间、EARLY_WORK_TIME 最早签到时间、LAST_END_TIME 最晚签退时间，ATTEND_REMIND 和 LEAVE_REMIND 是上班下班提醒开关。考勤提醒功能的数据源就是这张表，跟 ATTENDANCE_REMIND 表配合使用，前者存时间点，后者存提醒策略。

4. 数据字典实战：不碰库也能把查询 SQL 写对

拿到数据字典最直接的价值就是：连通数据库之前，SQL 就能先写对。字段名、类型、含义、关联关系全在字典里，照着一个字段一个字段拼就行。

4.1 从注释反推查询 SQL：以考勤日统计为例

考勤日统计报表是我做过的 OA 集成里最常见的需求。管理人员要一张表：某天哪些人迟到、哪些人缺卡。字典里 ATTENDANCE_DAY_STATISTICS 的字段注释直接给出了答案。

SELECT m.NAME, d.PUNCH_DATE, d.AM_START_TIME, d.AM_START_STATE, d.PM_END_TIME, d.PM_END_STATE, d.LATE_NUM, d.MISSINGCLOCK_COUNT FROM ATTENDANCE_DAY_STATISTICS d LEFT JOIN ORG_MEMBER m ON d.MEMBER_ID = m.ID WHERE d.PUNCH_DATE = :targetDate AND d.AB_NORMAL_DAY > 0 ORDER BY d.LATE_NUM DESC;

逻辑说明：先过滤指定考勤日，再筛异常天数大于 0 的记录，就是当天有问题的所有人。AM_START_STATE 等于 3 表示上班迟到，PM_END_STATE 等于 4 表示下班早退。注意状态字段的值是字典注释里写明的：3 上班迟到、4 下班早退、5 正常上班、6 正常下班。实际做报表时候我会再加一个 CASE WHEN 把状态码翻译成可读文案，避免业务人员看到数字一头雾水。

这里有个细节：PUNCH_DATE 和字段名又有一个 DATE 结尾，但它是 DATETIME 类型，存的是考勤日零点。直接用等于号匹配日期时，如果库里存的是 2025-06-01 00:00:00，用 = '2025-06-01' 匹配没问题；但如果某些考勤记录存成了 2025-06-01 08:30:00，等于号就查不到。稳妥写法是 BETWEEN '2025-06-01 00:00:00' AND '2025-06-01 23:59:59'，这个坑我在写月度统计时踩过，查出来缺了五六条记录。

4.2 用字段口径做核对：HISTORY 与 INFO 的差别处理

字典里有两张打卡明细表 ATTENDANCE_HISTORY 和 ATTENDANCE_INFO，字段大部分重叠，但几个关键差异决定了对账逻辑怎么走。最典型的是 SIGN 字段长度：HISTORY 是 VARCHAR(500)，INFO 是 VARCHAR(2000)。SIGN 字段注释是“打卡(地址/ip)”，实际存储时可能是一长串拼接的定位信息，包含经纬度坐标、地图地址文本。从 HISTORY 往外部系统同步时，如果目标字段长度只有 500，长地址会被截断，导致地图上点位偏移。

比对两张表时还要注意，INFO 表多了 MODIFY_NUM 签到修改次数、DEVICE_INFO 设备信息、STATE 打卡状态、MAC_ADDRESS Wi-Fi 地址。这说明 INFO 表是“修正后”的明细，HISTORY 是“原始”记录。对账时以 INFO 表为准，只用 HISTORY 做痕迹追溯。数据不一致时，优先怀疑设备端打卡后修改过，或系统有补卡流程。

4.3 字典字段快速转查询清单

数据字典拆到后期，我会把高频字段整理成一张速查表，贴在项目文档里。这里给一张我常用的精简版：

这张表不是字典的替代品，是在字典基础上按业务提炼的瘦身版。实际开发时先看这张表定位到目标表和字段，再回到详细字典里确认类型与约束。

5. 避坑与排查：通讯录、代理、考勤字段的五个典型坑

5.1 扩展字段“同名不同型”

现象：在 OA 后台维护的表单数据，同步到第三方系统时部分字段值丢了。

原因：EXT_ATTR_1 到 EXT_ATTR_70 虽然都叫“扩展字段”，但类型跨度极大。EXT_ATTR_1 是 VARCHAR(1024) 能存长文本，EXT_ATTR_31 是 VARCHAR(50) 存枚举代码，EXT_ATTR_11 是 DECIMAL(19,4) 存数值。如果同步逻辑把整个 EXT_ATTR 段当成文本统一处理，数字和日期字段会被强转或截断。

解决：写同步前，先把单位启用的自定义字段编号梳理出来，按编号分组处理。文本段直接映射，数字段用 CAST 转数值，枚举段先映射代码值再显示，日期段统一格式化成目标系统要求的字符串。做的时候花半小时列一个字段映射表，后面能省大量返工。

5.2 打卡地址字段长度不一致

现象：从 ATTENDANCE_HISTORY 同步打卡地址到外部系统，地址后半截丢失，地图上显示的点发生偏移。

原因：HISTORY 表的 SIGN 字段是 VARCHAR(500)，INFO 表的 SIGN 是 VARCHAR(2000)。有些长地址或复杂拼接的定位串超过了 500 字就被截断。

解决：优先从 ATTENDANCE_INFO 读取打卡地址，长度余量充足。如果只能读 HISTORY，同步前用 LEFT(SIGN, 500) 截断并记录告警日志。类似的情况还可能出现在 RECEIVE_ID 这种 TEXT 类型的字段上，建议先测一条最大长度记录再定目标表字段。

5.3 代理取消标记与代理类型混用

现象：查某人的代理关系时，发现已取消的代理也在结果里，还带出了离职交接的记录。

原因：判断生效状态只看了 AGENT_TYPE，没看 CANCEL_FLAG。AGENT_TYPE = 2 是离职交接，Type = 1 是普通代理，两者共用 AGENT 表。离职交接的记录如果没有单独清理流程，CANCEL_FLAG 长时间保持 0，就会伪装成有效代理。

解决：查询条件里强制加 CANCEL_FLAG = 0，并且按场景过滤 AGENT_TYPE。查普通代理就 WHERE AGENT_TYPE = 1，查交接记录再单独处理。

5.4 事项条件设置的默认值

现象：读取 AGENT 表的 MATTER_TYPE 字段，按字典误解“0 按处理人设置”处理，结果导出的数据全是按发起人。

原因：字典注释在 MATTER_TYPE 后面明确标注了“默认值为 1”，即新建记录默认按发起人设置。很多解析逻辑把默认值当 0 处理，导致语义反转。

解决：先看注释里的默认值标注。写 SQL 时显式写 MATTER_TYPE = 0 或 1，不要依赖默认值。数据清洗阶段把 NULL 统一回填为 1，避免下游逻辑误判。

5.5 考勤状态码与天数字段的关系

现象：考勤日报显示异常天数，但明细里没有状态码对应的记录。

原因：ATTENDANCE_DAY_STATISTICS 的 NORMAL_DAY 和 AB_NORMAL_DAY 是聚合结果，汇总时可能把缺卡、外勤、迟到分别计数。AB_NORMAL_DAY > 0 的记录，在明细 STATE 字段里可能只有“缺卡”没有“迟到”，两者维度不一致。

解决：报表逻辑先看聚合字段判断有没有异常，再看明细字段定位异常类型。别拿聚合结果去反推具体某次打卡状态，也别拿明细状态去重新合计聚合值。两者对不上时，优先以日统计表为准排查口径差异，确认是否包含补卡审批流。

6. 数据字典的进阶用法：把静态文档变成选型与排错工具

数据字典最容易被低估的用途，是拿它做功能边界判断。有一次客户问能不能在移动端做“考勤地点围栏外禁止打卡”，我没急着回需求，而是先翻了 ATTENDANCE_SETTING 表和 ATTENDANCE_INFO 表字段。ATTENDANCE_SETTING 表有 LONGITUDE、LATITUDE、ATTEND_RANGE 和 AVAILABLE 字段，说明原生是支持围栏配置的。在 REAL 场景里，这个能力对应的就是打卡时校验经纬度和半径。但如果要“禁止”，还要看打卡写入流程里是否校验了 AVAILABLE 和距离，这就不是看字段能确定的，得看代码逻辑。

还有一次排查通讯录看不到人，按数据字典把 ADDRESSBOOK_SET 的 VIEW_SCOPE、KEY_INFO_TYPE 和 ADDRESSBOOK_SET_SCOPE 的 USER_ID 串起来一查，发现是管理员的查看范围配置成“仅本人”，导致下属单位人员全部不可见。修复只需改 SET 表里 VIEW_SCOPE 的枚举值为单位范围。那次排查我没动一行代码，只写了三条 SELECT 就定位了根因，字典的价值就体现在这种时刻。

从那以后我每次做 OA 集成，都会强制走一遍这个流程：先按字典把表关系画成简图，再对照关键字段写一条最小可用的验证 SQL，跑通后再扩展业务逻辑。如果字段语义拿不准，宁可先查库确认，也不猜。希望帮到你。

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