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 中注明数据库变更

### 变更记录格式

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

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

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

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

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

---

## 📝 注意事项

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

---

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