diff --git a/docs/DATABASE_SCHEMA.md b/docs/DATABASE_SCHEMA.md new file mode 100644 index 0000000..7eefbd7 --- /dev/null +++ b/docs/DATABASE_SCHEMA.md @@ -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 (线上稳定版)