x-server-mobile/docs/DATABASE_SCHEMA.md

数据库结构文档

版本: 1.1.0 更新时间: 2026-03-01 状态: 线上稳定版本

---

📋 数据库概述

数据库名: xserver

---

表结构

1. users - 用户表

用户基本信息表，存储员工账户信息。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	用户ID
sn	varchar(36)	✓		SN编号（员工工号）
company_id	bigint unsigned	✓		公司ID
name	varchar(50)	✓		姓名
avatar	varchar(255)			头像URL
sex	tinyint			性别
email	varchar(100)			邮箱
phone	varchar(20)			手机号
password	varchar(255)			密码哈希
status	tinyint	✓	1	状态：1=在职，0=离职
user_type	tinyint	✓	1	用户类型
union_id	varchar(60)			飞书union_id
feishu_app_id	int unsigned			登录来源飞书应用ID
sign_img	varchar(255)			签名图片
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY company_id (company_id)
• KEY status (status)
• KEY union_id (union_id)
• KEY feishu_app_id (feishu_app_id)

---

2. companies - 公司表

公司信息表。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	公司ID
name	varchar(100)	✓		公司名称
abbr	varchar(50)	✓		公司简称
tenant_key	varchar(36)	✓		飞书tenant_key
sort	int	✓	0	排序
status	tinyint	✓	1	状态
feishu_enabled	tinyint(1)	✓	0	是否启用飞书
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY status (status)

---

3. company_feishu_apps - 公司飞书应用配置表

每个公司的飞书应用配置。

字段	类型	必填	默认值	说明
id	int unsigned	✓	AUTO_INCREMENT	配置ID
company_id	int	✓		公司ID
system_id	int	✓	1	系统ID：1=默认应用
name	varchar(90)	✓		应用名称
app_id	varchar(60)	✓		飞书App ID
app_secret	varchar(150)	✓		飞书App Secret
encrypt_key	varchar(60)			加密Key
verification_token	varchar(60)			验证Token
callback_url	varchar(255)			回调URL（PC端）
mobile_callback_url	varchar(255)			回调URL（移动端）
status	tinyint(1)	✓	1	状态
sort	int		0	排序
created_at	int	✓	0	创建时间
updated_at	int	✓	0	更新时间

索引:

• PRIMARY KEY (id)
• KEY company_id (company_id)
• KEY system_id (system_id)

---

4. user_feishu_apps - 用户飞书应用关联表

用户在不同飞书应用下的登录信息。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	关联ID
user_id	bigint unsigned	✓		用户ID
company_id	bigint unsigned	✓		公司ID
feishu_app_id	int unsigned	✓		飞书应用ID
feishu_user_id	varchar(60)			飞书user_id
feishu_open_id	varchar(60)			飞书open_id
tenant_key	varchar(60)			tenant_key
is_default	tinyint	✓	0	是否默认应用
last_login_at	timestamp			最后登录时间
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY user_id (user_id)
• KEY feishu_user_id (feishu_user_id)
• KEY feishu_open_id (feishu_open_id)

---

5. user_sn - 用户SN分配表

用户SN编号池。

字段	类型	必填	默认值	说明
user_sn	int unsigned	✓	0	SN编号
user_id	int unsigned	✓	0	分配给的用户ID（0=未分配）

索引:

• KEY user_sn (user_sn)
• KEY user_id (user_id)

---

6. approval_flow - 审批流程表

审批流程定义。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	流程ID
business_type	varchar(50)	✓		业务类型
name	varchar(100)	✓		流程名称
description	varchar(255)			描述
status	tinyint	✓	1	状态
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY business_type (business_type)
• KEY status (status)

---

7. approval_node - 审批节点表

审批流程节点定义。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	节点ID
flow_id	bigint unsigned	✓		流程ID
type	enum	✓		节点类型：approver=单人审批，and_approve=会签，or_approve=或签，notify=通知
name	varchar(100)	✓		节点名称
order	int	✓	0	节点顺序
approvers	json			审批人列表
conditions	json			条件配置
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY flow_id (flow_id)
• KEY order (order)

---

8. approval_order - 审批订单表

审批订单主表。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	订单ID
business_type	varchar(50)	✓		业务类型
business_id	bigint unsigned	✓		业务ID
title	varchar(200)	✓		标题
applicant_id	bigint unsigned	✓		申请人ID
status	enum	✓	draft	状态：draft=草稿，pending=审批中，approved=已通过，rejected=已拒绝，cancelled=已撤销
current_nodes	json			当前节点
flow_id	bigint unsigned	✓		流程ID
form_data	json			表单数据
attachments	json			附件
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY business_type (business_type)
• KEY applicant_id (applicant_id)
• KEY status (status)
• KEY created_at (created_at)

---

9. approval_record - 审批记录表

审批操作记录。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	记录ID
order_id	bigint unsigned	✓		订单ID
node_id	bigint unsigned	✓		节点ID
node_type	varchar(20)	✓		节点类型
approver_id	bigint unsigned	✓		审批人ID
action	enum	✓		操作：submit=提交，approve=通过，reject=拒绝，cancel=撤销
comment	varchar(500)			审批意见
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY order_id (order_id)
• KEY approver_id (approver_id)
• KEY created_at (created_at)

---

10. business_trip - 出差申请表

出差申请主表。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	申请ID
user_id	bigint unsigned	✓		用户ID
reason	varchar(500)	✓		出差事由
start_date	date	✓		开始日期
end_date	date			结束日期
destination	varchar(200)	✓		目的地
estimated_cost	decimal(10,2)		0.00	预估费用
status	enum	✓	draft	状态
approval_order_id	bigint unsigned			关联的审批订单ID
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY user_id (user_id)
• KEY status (status)
• KEY approval_order_id (approval_order_id)

---

11. business_trip_itinerary - 出差行程表

出差申请行程明细。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	行程ID
business_trip_id	bigint unsigned	✓		出差申请ID
start_time	datetime	✓		开始时间
end_time	datetime			结束时间
departure	varchar(100)			出发地
destination	varchar(100)	✓		目的地
transport	varchar(50)			交通工具
trip_type	varchar(20)		oneway	行程类型：oneway=单程，roundtrip=往返
remark	varchar(255)			备注
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间
updated_at	timestamp	✓	CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY business_trip_id (business_trip_id)
• KEY start_time (start_time)

---

12. feishu_login_session - 飞书扫码登录会话表

飞书扫码登录临时会话。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	会话ID
company_id	bigint unsigned	✓		公司ID
tenant_key	varchar(64)	✓		tenant_key
feishu_app_id	int unsigned			飞书应用ID
status	varchar(20)	✓	pending	状态：pending=待扫码，scanning=已扫码，success=成功，expired=过期
user_id	bigint unsigned			用户ID
expires_at	datetime	✓		过期时间
created_at	timestamp		CURRENT_TIMESTAMP	创建时间
updated_at	timestamp		CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• KEY company_id (company_id)
• KEY expires_at (expires_at)

---

13. feishu_message - 飞书审批消息映射表

用于存储飞书消息与审批订单、节点、用户的映射关系，支持消息卡片更新。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	记录ID
order_id	bigint unsigned	✓		审批订单ID
node_id	bigint unsigned	✓		审批节点ID
user_id	bigint unsigned	✓		审批人ID
message_id	varchar(64)	✓		飞书消息ID
msg_token	varchar(128)			消息Token（用于更新卡片）
status	varchar(20)	✓	active	状态：active=有效，updated=已更新，deleted=已删除
created_at	timestamp		CURRENT_TIMESTAMP	创建时间
updated_at	timestamp		CURRENT_TIMESTAMP	更新时间

索引:

• PRIMARY KEY (id)
• UNIQUE KEY idx_order_node_user (order_id, node_id, user_id)
• KEY idx_message_id (message_id)
• KEY idx_user_id (user_id)

---

14. feishu_message_log - 飞书消息日志表

飞书消息发送和更新的操作日志，用于调试和审计。

字段	类型	必填	默认值	说明
id	bigint unsigned	✓	AUTO_INCREMENT	记录ID
action	varchar(20)	✓		操作类型：send=发送，update=更新，update_card=更新卡片
order_id	bigint unsigned	✓		审批订单ID
node_id	bigint unsigned			审批节点ID
user_id	bigint unsigned			用户ID
message_id	varchar(64)			飞书消息ID
status	varchar(10)	✓		状态：success=成功，failed=失败
request_data	text			请求数据（JSON）
response_data	text			响应数据（JSON）
error_message	text			错误信息
created_at	timestamp	✓	CURRENT_TIMESTAMP	创建时间

索引:

• PRIMARY KEY (id)
• KEY idx_order_id (order_id)
• KEY idx_action (action)
• KEY idx_status (status)
• KEY idx_created_at (created_at)

---

📊 表关系图

users (1) ----< (N) user_feishu_apps
  |                        |
  |                        +----> company_feishu_apps
  |
  +----> companies (1) ----< (N) company_feishu_apps
         |
         +----> user_sn (N)

users (1) ----< (N) business_trip
  |                            |
  |                            +----> business_trip_itinerary (N)
  |
  +----> approval_order (1) ----< (N) approval_record
                                |
                                +----> approval_flow (1) ----< (N) approval_node

---

🔒 数据库变更规范

变更流程

1. 在 feature/mzl-dev 分支进行开发
2. 创建迁移脚本（migration）
3. 更新本文档
4. 提交时在 commit message 中注明数据库变更

变更记录格式

## [变更日期] - [变更内容]

### 新增表
- 表名：用途说明

### 修改表
- 表名：字段变更说明

### 删除表
- 表名（需谨慎）

### 索引变更
- 表名：索引变更说明

---

📝 注意事项

1. 密码字段：users.password 使用 PHP password_hash() 加密，格式为 $2y$...
2. 默认密码：新用户默认密码为 SN 编号
3. 软删除：用户表使用 status 字段标记状态（1=在职，0=离职）
4. 时间字段：统一使用 timestamp 类型，自动更新
5. JSON字段：用于存储复杂数据结构

---

维护人: 开发团队 最后更新: 2026-03-01 版本: 1.1.0 (线上稳定版)