# 绿纤美业ERP系统 - 数据库说明

## 📋 目录
- [数据库基本信息](#数据库基本信息)
- [表关系图](#表关系图)
- [核心业务表关系](#核心业务表关系)
- [已弃用表变更记录](#已弃用表变更记录)
- [重要业务规则](#重要业务规则)
- [数据字典](#数据字典)
- [开发注意事项](#开发注意事项)

---

## 数据库基本信息

- **数据库类型**: MySQL
- **数据库名称**: lqerp
- **字符集**: utf8
- **表总数**: 约100+张表
- **命名规范**: 业务前缀 `lq_` + 功能名称

---

## 表关系图

### 核心业务流程图
```
门店信息 (lq_mdxx)
    ↓
用户信息 (BASE_USER) ← 人员资料 (lq_ryzl) [已弃用]
    ↓
金三角设定 (lq_ycsd_jsj) ← 金三角用户绑定 (lq_jinsanjiao_user)
    ↓
开单记录 (lq_kd_kdjlb) ← 预约记录 (lq_yyjl)
    ↓
├── 开单品项明细 (lq_kd_pxmx) ← 项目资料 (lq_xmzl)
├── 开单健康师业绩 (lq_kd_jksyj)
├── 开单科技部老师业绩 (lq_kd_kjbsyj)
└── 业绩明细 (lq_yjmxb)

耗卡业务
    ↓
耗卡记录 (lq_xh_hyhk)
    ↓
├── 耗卡品项明细 (lq_xh_pxmx)
├── 耗卡健康师业绩 (lq_xh_jksyj)
└── 耗卡科技部老师业绩 (lq_xh_kjbsyj)
```

---

## 核心业务表关系

### 1. 门店与人员关系
- **门店信息表**: `lq_mdxx` (门店基础信息)
  - `longitude` (DECIMAL): 经度
  - `latitude` (DECIMAL): 纬度
  - `fence_polygons` (JSON): 电子围栏多边形坐标，格式 `[[{lng,lat},...]]`
  - `F_BusinessHours` (TEXT): 营业时间设置
  - `F_TrafficTips` (TEXT): 交通提示
- **人员信息**: `BASE_USER` (系统用户表，包含门店ID等扩展字段)
- **关联字段**: `BASE_USER.F_MDID` ↔ `lq_mdxx.F_Id`

### 2. 金三角管理关系
- **金三角设定**: `lq_ycsd_jsj` (金三角基础信息)
- **金三角用户绑定**: `lq_jinsanjiao_user` (金三角与用户绑定关系)
- **用户信息**: `BASE_USER` (系统用户表)
- **关联字段**: 
  - `lq_ycsd_jsj.F_Id` ↔ `lq_jinsanjiao_user.jsj_id`
  - `lq_jinsanjiao_user.user_id` ↔ `BASE_USER.F_Id`

### 3. 开单业务关系
- **开单记录**: `lq_kd_kdjlb` (核心业务表)
- **开单品项明细**: `lq_kd_pxmx` (品项明细)
- **开单健康师业绩**: `lq_kd_jksyj` (健康师业绩)
- **开单科技部老师业绩**: `lq_kd_kjbsyj` (科技部老师业绩)
- **项目资料**: `lq_xmzl` (项目基础信息)
- **关联字段**:
  - `lq_kd_kdjlb.F_Id` ↔ `lq_kd_pxmx.glkdbh`
  - `lq_kd_kdjlb.F_Id` ↔ `lq_kd_jksyj.glkdbh`
  - `lq_kd_kdjlb.F_Id` ↔ `lq_kd_kjbsyj.glkdbh`
  - `lq_kd_pxmx.px` ↔ `lq_xmzl.F_Id`
  - `lq_kd_jksyj.F_kdpxid` ↔ `lq_kd_pxmx.F_Id`
  - `lq_kd_kjbsyj.F_kdpxid` ↔ `lq_kd_pxmx.F_Id`

### 4. 耗卡业务关系
- **耗卡记录**: `lq_xh_hyhk` (耗卡记录表)
- **耗卡品项明细**: `lq_xh_pxmx` (耗卡品项明细)
- **耗卡健康师业绩**: `lq_xh_jksyj` (耗卡健康师业绩)
- **耗卡科技部老师业绩**: `lq_xh_kjbsyj` (耗卡科技部老师业绩)
- **关联字段**:
  - `lq_xh_hyhk.F_Id` ↔ `lq_xh_pxmx.glkdbh` (耗卡记录关联品项明细)
  - `lq_xh_hyhk.F_Id` ↔ `lq_xh_jksyj.glkdbh` (耗卡记录关联健康师业绩)
  - `lq_xh_hyhk.F_Id` ↔ `lq_xh_kjbsyj.glkdbh` (耗卡记录关联科技部老师业绩)
  - `lq_xh_jksyj.F_kdpxid` ↔ `lq_xh_pxmx.F_Id` (健康师业绩关联品项明细)
  - `lq_xh_kjbsyj.F_hkpxid` ↔ `lq_xh_pxmx.F_Id` (科技部老师业绩关联品项明细)

### 5. 退卡业务关系
- **退卡记录**: `lq_hytk_hytk` (退卡记录表)
- **退卡品项明细**: `lq_hytk_mx` (退卡品项明细)
- **退卡健康师业绩**: `lq_hytk_jksyj` (退卡健康师业绩)
- **退卡科技部老师业绩**: `lq_hytk_kjbsyj` (退卡科技部老师业绩)
- **关联字段**:
  - `lq_hytk_hytk.F_Id` ↔ `lq_hytk_mx.F_RefundInfoId` (退卡记录关联品项明细)
  - `lq_hytk_hytk.F_Id` ↔ `lq_hytk_jksyj.gltkbh` (退卡记录关联健康师业绩)
  - `lq_hytk_hytk.F_Id` ↔ `lq_hytk_kjbsyj.gltkbh` (退卡记录关联科技部老师业绩)
  - `lq_hytk_mx.F_BillingItemId` ↔ `lq_kd_pxmx.F_Id` (退卡明细关联开单品项明细)
  - `lq_hytk_mx.F_MemberId` ↔ `lq_khxx.F_Id` (退卡明细关联会员，通过会员ID)
  - `lq_hytk_hytk.hy` ↔ `lq_khxx.F_Id` (退卡记录关联会员)

### 6. 报销申请与流程配置关系
- **报销申请表**: `lq_reimbursement_application`
- **流程配置表**: `lq_reimbursement_workflow_config`
- **关联字段**: `lq_reimbursement_application.F_WorkflowConfigId` ↔ `lq_reimbursement_workflow_config.F_Id`（可选，用于返回流程名称 workflowName）

### 7. 考勤设置关系
- **考勤设置主表**: `lq_attendance_setting`
- **公休日期表**: `lq_attendance_holiday`
- **考勤分组表**: `lq_attendance_group`
  - 关键字段：`F_MonthlyRestDays`（月应休天数）、`F_HalfDaySplitRestDays`（可拆分半天休假天数，整数，表示允许拆成半天的整天额度）
- **免考勤人员表**: `lq_attendance_exempt_user`
- **额外假期表**: `lq_attendance_extra_leave`
- **婚假规则表**: `lq_attendance_marriage_leave_rule`
- **丧假规则表**: `lq_attendance_funeral_leave_rule`
- **年假规则表**: `lq_attendance_annual_leave_rule`
- **产假规则表**: `lq_attendance_maternity_leave_rule`
- **迟到 / 早退规则表**: `lq_attendance_late_rule`
- **缺卡规则表**: `lq_attendance_missing_card_rule`
- **旷工规则表**: `lq_attendance_absenteeism_rule`
- **配置历史表**: `lq_attendance_config_history`
- **人员信息来源**: `BASE_USER`（司龄按 `BASE_USER.F_ENTRYDATE` 计算，考勤分组绑定字段为 `BASE_USER.F_AttendanceGroupId`）
- **统一历史字段**（除历史表外，所有考勤配置表均已补齐）:
  - `F_DeleteMark`: 逻辑删除标记（0-正常，1-已删除）
  - `F_VersionNo`: 当前版本号
  - `F_LastModifyUserId`: 最后修改人ID
  - `F_LastModifyUserName`: 最后修改人姓名
  - `F_LastModifyTime`: 最后修改时间
- **关联字段**:
  - `BASE_USER.F_AttendanceGroupId` ↔ `lq_attendance_group.F_Id`（员工当前考勤分组，直接绑定在用户表，不单独建成员表）
  - `lq_attendance_group.F_MonthlyRestDays` / `lq_attendance_group.F_HalfDaySplitRestDays`（共同约束“休假”流程：前者控制月总休假天数，后者控制当月最多可拆成半天的休假额度）
  - `lq_attendance_exempt_user.F_UserId` ↔ `BASE_USER.F_Id`（免考勤人员）
  - `lq_attendance_extra_leave.F_UserId` ↔ `BASE_USER.F_Id`（员工额外假期额度配置）
  - `lq_attendance_config_history.F_BizId` ↔ 各考勤配置表 `F_Id`（按 `F_ModuleType` 区分模块）
  - `WFORM_LEAVEAPPLY.F_FUNERALRELATIONTYPE`（丧假关系类型：1-直系亲属，2-非直系亲属，不再从请假原因文本识别）

### 8. 考勤打卡记录表说明
- **表名**: `lq_attendance_record`
- **用途**: 存储员工每日真实打卡结果，供“打卡记录”页面按月生成矩阵视图，并同时固化“命中的规则快照”和“打卡当时整套考勤规则快照”。
- **核心字段**:
  - `F_UserId`: 员工ID
  - `F_EmployeeName`: 员工姓名快照
  - `F_StoreId` / `F_StoreName`: 门店快照
  - `F_AttendanceGroupId` / `F_AttendanceGroupName`: 考勤分组快照
  - `F_AttendanceDate`: 打卡日期
  - `F_PunchInTime` / `F_PunchOutTime`: 上下班打卡时间
  - `F_PunchInType` / `F_PunchOutType`: 上下班打卡类型（1正常上班，2外勤）
  - `F_PunchInLongitude` / `F_PunchInLatitude` / `F_PunchInAddress`: 上班打卡定位与地址
  - `F_PunchOutLongitude` / `F_PunchOutLatitude` / `F_PunchOutAddress`: 下班打卡定位与地址
  - `F_PunchInPhotoUrl` / `F_PunchOutPhotoUrl`: 上下班打卡照片
  - `F_IsPunchInFenceValid` / `F_IsPunchOutFenceValid`: 上下班围栏校验结果（1围栏内，0围栏外，null未校验）
  - `F_Status`: 打卡状态（1正常，2迟到，3休息，4请假，5病假，6缺卡，7旷工）
  - `F_LateMinutes`: 迟到分钟数
  - `F_EarlyLeaveMinutes`: 早退分钟数
  - `F_IsManual`: 是否手动补录
  - `F_Remark`: 备注
  - `F_RuleSnapshotJson`: 规则快照JSON（保存打卡当日命中的考勤组、迟到早退规则等配置，便于事后追溯）
  - `F_AllRuleSnapshotJson`: 全量考勤规则快照JSON（保存打卡当时整套考勤设置，包括基础扣款倍率、公休、假期规则、缺卡/旷工/迟到早退规则、当前员工相关免考勤与额外假期配置等）
  - `F_SupplementRemark`: 补卡备注
  - `F_SupplementOperatorId` / `F_SupplementOperatorName` / `F_SupplementTime`: 补卡操作信息
  - `F_SupplementWorkflowId`: 关联补卡流程ID（可空）
- **索引说明**:
  - `uk_attendance_record_user_date`: 保证同一员工同一天只有一条有效记录
  - `idx_attendance_record_month_group`: 支持按月份、分组快速查询月度矩阵
- **关联字段**:
  - `lq_attendance_record.F_UserId` ↔ `BASE_USER.F_Id`（打卡员工）
  - `lq_attendance_record.F_StoreId` ↔ `lq_mdxx.F_Id`（打卡时门店快照）
  - `lq_attendance_record.F_AttendanceGroupId` ↔ `lq_attendance_group.F_Id`（打卡时考勤分组快照）

### 9. 业绩统计关系
- **业绩明细**: `lq_yjmxb` (业绩统计表)
- **关联字段**:
  - `lq_yjmxb.jks` ↔ `BASE_USER.F_REALNAME` (健康师姓名)
  - `lq_yjmxb.mdbh` ↔ `lq_mdxx.mdbm` (门店编号)
  - `lq_yjmxb.xmbh` ↔ `lq_xmzl.xmbh` (项目编号)

---

## 已弃用表变更记录

### ⚠️ 重要变更

#### 1. 人员资料表弃用 (2024年)
- **弃用表**: `lq_ryzl` (人员资料表)
- **替代方案**: 使用系统用户表 `BASE_USER`
- **迁移字段**:
  - `lq_ryzl.dm` → `BASE_USER.F_MDID` (门店ID)
  - `lq_ryzl.zw` → `BASE_USER.F_ZW` (职位)
  - `lq_ryzl.gwfl1` → `BASE_USER.F_GWFL` (岗位分类)
  - `lq_ryzl.xm` → `BASE_USER.F_REALNAME` (姓名)
  - `lq_ryzl.sjh` → `BASE_USER.F_MobilePhone` (手机号)
- **业务影响**: 所有人员相关查询必须使用 `BASE_USER` 表

#### 2. 门店归属表弃用 (2024年)
- **弃用表**: `lq_mdxx_mdgs` (门店归属表)
- **替代方案**: 归属信息整合到 `lq_mdxx` 表
- **迁移字段**:
  - `syb` (事业部)
  - `jyb` (教育部)
  - `kjb` (科技部)
  - `dxmb` (大项目部)
  - `gsqssj` (归属起始时间)
  - `gszzsj` (归属终止时间)
  - `status` (状态)
- **业务影响**: 门店归属信息现在直接在 `lq_mdxx` 表中管理

#### 3. 门店目标设定表弃用 (2024年)
- **弃用表**: `lq_ycsd_mdmbsd` (门店目标设定表)
- **替代方案**: 目标信息整合到 `lq_mdxx` 表
- **迁移字段**:
  - `xsyj` (目标-门店生命线)
  - `xhyj` (目标-消耗业绩)
  - `xms` (目标-项目数)
  - `rt1` (目标-人头1)
  - `rt2` (目标-人头2)
  - `rc` (目标-人次)

---

## 重要业务规则

### 1. 删除标记规则
- **base_organize 表**: `DeleteMark` 为 `null` 表示未删除，为 `0` 或其他值表示已删除
- **其他表**: 通常使用 `deletemark` 字段，`0` 表示未删除，`1` 表示已删除

### 2. ID生成规则
- **主键字段**: 统一使用 `F_Id` (varchar类型)

### 3. 金额字段规则
- **存储类型**: 所有金额字段使用 `varchar` 类型存储
- **计算注意**: 查询时需要转换为 `decimal` 类型进行计算
- **精度要求**: 金额计算保留2位小数

### 4. 时间字段规则
- **存储类型**: 统一使用 `datetime` 类型
- **时区处理**: 注意时区转换问题
- **查询格式**: 使用 `yyyy-MM-dd HH:mm:ss` 格式

### 5. 考勤配置规则
- **司龄来源**: 考勤相关司龄一律使用 `BASE_USER.F_ENTRYDATE` 计算，不再依赖 `lq_ryzl` 或其他历史人员表
- **区间规则**: 婚假、丧假、年假、产假、迟到、缺卡、旷工规则统一按“最小值包含、最大值不包含”处理，最大值留空表示无上限
- **人员归属**: 同一员工只能归属一个考勤分组，直接维护在 `BASE_USER.F_AttendanceGroupId`；免考勤人员使用 `lq_attendance_exempt_user` 独立维护
- **额外假期**: 员工奖励假、旅游假等额外休假额度单独存储在 `lq_attendance_extra_leave`，按“员工 + 年份 + 假期名称”维度配置，可配置多条

---

## 数据字典

### 门店状态 (lq_mdxx.zxzt)
- 待补充具体枚举值

### 岗位分类 (BASE_USER.F_GWFL, F_GW)
- 待补充具体枚举值

### 项目分类 (lq_xmzl.fl1, fl2, fl3, fl4)
- 待补充具体枚举值

### 金三角状态 (lq_jinsanjiao_user.status)
- `ACTIVE`: 活跃
- `INACTIVE`: 非活跃

### 预约状态 (lq_yyjl.F_Status)
- 待补充具体枚举值

---

## 开发注意事项

### 1. 查询优化
- 所有列表查询必须支持分页
- 关键字段建立索引
- 避免 N+1 查询，使用 JOIN 优化

### 2. 数据一致性
- 统计接口与列表接口使用相同的过滤条件
- 所有数据查询必须添加园区权限过滤
- DTO字段名称、大小写必须完全一致

### 3. 业务逻辑
- 开单记录表是核心业务表，所有业务操作都围绕开单进行
- 人员信息已迁移到系统用户表，查询时使用 `BASE_USER`
- 门店归属信息现在直接在 `lq_mdxx` 表中管理

### 4. 字段映射
- 数据库字段使用拼音首字母命名
- 实体类字段使用驼峰命名
- 查询时注意字段名映射关系

### 5. 权限控制
- 所有数据查询必须添加园区权限过滤
- 使用 `base_organize.DeleteMark` 过滤已删除数据
- 接口必须校验 JWT Token

---

## 视图说明

### 业绩统计视图
- `v_jsj_monthly_performance`: 金三角月度业绩统计
- `v_jsj_monthly_summary`: 金三角月度业绩汇总
- `v_personal_monthly_performance`: 个人业绩月度统计

### 开单相关视图
- `v_order_detail_simple`: 开单详细记录视图

---