docs: 添加数据库结构文档（线上稳定版 v1.0.0）

记录主分支的完整数据库结构，包含12个表：用户管理： - users - 用户基本信息 - companies - 公司信息 - company_feishu_apps - 飞书应用配置 - user_feishu_apps - 用户飞书应用关联 - user_sn - 用户SN分配池 - feishu_login_session - 飞书扫码登录会话审批流程： - approval_flow - 审批流程定义 - approval_node - 审批节点定义 - approval_order - 审批订单 - approval_record - 审批记录业务数据： - business_trip - 出差申请 - business_trip_itinerary - 出差行程变更规范： - 数据库变更需落成文档 - 使用 migration 脚本管理 - commit message 需注明数据库变更 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 16:26:01 +08:00
parent 6594c90619
commit 92ffaf2ef0
1 changed files with 372 additions and 0 deletions
@@ -0,0 +1,372 @@
+# 数据库结构文档
+
+**版本**: 1.0.0
+**更新时间**: 2026-02-28
+**状态**: 线上稳定版本
+
+---
+
+## 📋 数据库概述
+
+**数据库名**: `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`)
+
+---
+
+## 📊 表关系图
+
+```
+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-02-28
+**版本**: 1.0.0 (线上稳定版)