# 绿纤美业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` (门店基础信息)
- **门店主档时点版本（规划/R-003）**: `lq_store_profile_version` 按 `F_ValidFrom`/`F_ValidTo` 记录门店属性历史，用于考勤规则回看与算薪按日/按月取 `F_StoreType`、`F_StoreCategory`、`zxzt`、`dhhm` 等；与 `lq_mdxx` 当前行双写。建表脚本：`项目文档相关/sql/2026-4-3/R-003_门店主档版本快照表_lq_store_profile_version.sql`；说明见 `用户主档与薪酬考勤改造记录.md`（R-003）。
  - `longitude` (DECIMAL): 经度
  - `latitude` (DECIMAL): 纬度
  - `fence_polygons` (JSON): 电子围栏多边形坐标，格式 `[[{lng,lat},...]]`
  - `F_AttendanceCheckFence` (INT，可空): 正常打卡是否启用电子围栏校验（1-是，0-否；**可空**：空表示沿用历史默认「有围栏则校验」）
  - `F_AttendanceCheckWifi` (INT，可空): 正常打卡是否启用 Wi-Fi 校验（1-是，0-否）
  - `F_AttendanceWifiPairs` (VARCHAR): Wi-Fi 成对白名单，JSON 数组，如 `[{"ssid":"门店5G","bssid":"aa:bb:cc:dd:ee:ff"}]`
  - `F_AttendanceWifiVerifyPair` (INT，可空，默认 0): **是否校验 SSID 与 BSSID 为同一 AP**。`1`：端上能拿到 BSSID 时必须与某行 **SSID+BSSID 同时一致**；端上 **拿不到 BSSID** 时须 **在电子围栏内** 且 SSID 与某行一致（防同名热点）。`0`：不强制同 AP，只要当前 SSID 或 BSSID **命中任意一行中的字段** 即可（仍按行维护，但校验为「或」）
  - ~~`F_AttendanceWifiSsids` / `F_AttendanceWifiBssids~~`：已删除，统一使用` F_AttendanceWifiPairs`（脚本：`项目文档相关/sql/2026-4-3/门店考勤_围栏与WiFi打卡配置.sql`）
  - `F_BusinessHours` (TEXT): 营业时间设置
  - `F_TrafficTips` (TEXT): 交通提示
  - `F_AttendanceGroupId` (VARCHAR，可空): 门店默认考勤分组，对应 `lq_attendance_group.F_Id`；员工作为团队成员时，上下班时间以此门店默认班次为准（人员表不存考勤分组列）。
- **人员信息**: `BASE_USER` (系统用户表，包含门店ID等扩展字段)
- **用户主档时点全量版本（R-004）**: `lq_user_profile_version` 按 `F_ValidFrom`/`F_ValidTo` 记录脱敏后的完整主档 JSON（`F_FullSnapshotJson`，不含密码/密钥），与字段级审计 `lq_user_profile_audit` 双轨；算薪按统计月末时点优先用本表覆盖主档，再叠加门店切段 `lq_employee_store_assignment` 覆盖 `F_Mdid`。建表脚本：`项目文档相关/sql/2026-04-04/R-004_用户主档全量时点版本_lq_user_profile_version.sql`。
- **关联字段**: `BASE_USER.F_MDID` ↔ `lq_mdxx.F_Id`
- **员工门店归属快照（规划）**: `lq_employee_store_assignment` 按时间段记录 `F_EmployeeId` 与 `F_StoreId`，与当前 `F_Mdid` 双写；算薪/补录按业务日优先读快照（见改造记录与 R-002 脚本）。
- **月度业务事实人员（逻辑口径，无新表）**: 某自然月「有事实」的员工集合由后端 `LqMonthlyEmployeeFactHelper` 汇总（考勤汇总/切段、打卡明细、人头人次、金三角当月绑定、健康师/科技部业绩与退卡、各岗位工资归档月份等），`jkszh`/`kjblszh` 等通过 `BASE_USER.F_Id` 或 `F_ACCOUNT` 解析；算薪加载 `BASE_USER` 时对 **当月有事实** 的用户允许在 `F_ENABLEDMARK=0` 时仍参与计算（未软删）。仅 SQL 核对：`项目文档相关/sql/2026-04-05/查询_指定年月有业务事实的用户_BASE_USER.sql`。API：`GET /api/Extend/LqMonthlyEmployeeFact/employees`、`/employee-ids`。

### 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_DefaultRestGroupId` 指向本条班次绑定的**默认应休分组**（`lq_attendance_rest_group`）。~~`F_MonthlyRestDays` / `F_HalfDaySplitRestDays` / `F_RestUnlockCycle`~~ 已从本表删除，迁出至应休表（脚本：`项目文档相关/sql/2026-05-06/2026-05-06_考勤扩展_全量合并.sql`（节 B））。
- **应休分组表**: `lq_attendance_rest_group`（员工可选绑定 `BASE_USER.F_AttendanceRestGroupId` 覆盖默认；未绑定时休假额度使用门店默认班次对应考勤分组上的 `F_DefaultRestGroupId` 所指应休分组；与班次上下班时间解耦）
- **免考勤人员表**: `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` 计算；**上下班班次**以用户主门店 `F_MDID` 对应 `lq_mdxx.F_AttendanceGroupId` 为准）
- `**BASE_USER.F_LeaveDate`**（DATETIME，可空）：离职日期；主档「在职/离职」为离职时必填，在职时应为空。员工花名册无当月考勤汇总时：「入职≤查询月末」且（无离职日或「离职日≥查询月1日」）——当月离职仍出现在当月；查下一自然月时因不满足「离职≥下月1日」，上月已离职者不再出现；不依赖当前 `F_IsOnJob`。有汇总时以 `lq_attendance_summary.F_EmployeeStatus` 为准。建表/补列脚本：`项目文档相关/sql/2026-04-06/BASE_USER_增加离职日期_F_LeaveDate.sql`。
- **统一历史字段**（除历史表外，所有考勤配置表均已补齐）:
  - `F_DeleteMark`: 逻辑删除标记（0-正常，1-已删除）
  - `F_VersionNo`: 当前版本号
  - `F_LastModifyUserId`: 最后修改人ID
  - `F_LastModifyUserName`: 最后修改人姓名
  - `F_LastModifyTime`: 最后修改时间
- **关联字段**:
  - ~~`BASE_USER.F_AttendanceGroupId`~~：已从人员表删除；班次仅以门店 `lq_mdxx.F_AttendanceGroupId` 为准（迁移脚本：`项目文档相关/sql/2026-05-06/2026-05-06_考勤扩展_全量合并.sql` 末节 `DROP COLUMN`）
  - `BASE_USER.F_PunchAllowedStoreIds`（TEXT，可空）：可正常打卡的门店 ID 列表，JSON 数组字符串如 `["id1","id2"]`；空表示未单独配置，打卡白名单兜底为主门店 `F_MDID`。合并 DDL 见：`项目文档相关/sql/2026-05-06/2026-05-06_考勤扩展_全量合并.sql`
  - `BASE_USER.F_AttendanceRestGroupId` ↔ `lq_attendance_rest_group.F_Id`（可选：**应休福利**分组；空则使用门店默认班次对应 `lq_attendance_group.F_DefaultRestGroupId` 所指应休分组的月应休/半天拆分/解锁周期）
  - `lq_attendance_group.F_DefaultRestGroupId` ↔ `lq_attendance_rest_group.F_Id`（每条班次的默认应休口径；保存班次设置时由后端同步维护对应应休行）
  - `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-非直系亲属，不再从请假原因文本识别）
  - **销假流程表** `WFORM_LEAVE_CANCEL_APPLY`：字段含 `F_FLOWID`、`F_BILLNO`、`F_ATTENDANCERECORDID`（待销假的 `lq_attendance_record.F_Id`）、`F_CANCELREASON` 等；流程通过后由工作流钩子调用考勤销假。
  - **补卡流程表** `WFORM_ATTENDANCE_PUNCH_APPLY`：字段含 `F_PUNCHTARGETSJSON`（补卡目标 JSON：`date` / `punchIn` / `punchOut`）、`F_APPLYREASON` 等；流程通过后按考勤组标准上下班时间写入打卡。
  - **单据规则** `BASE_BILLRULE`：销假/补卡流程取号依赖编码 `WF_LeaveCancelApplyNo`、`WF_AttendancePunchApplyNo`；未配置时取号结果为「单据规则不存在」。初始化脚本：`项目文档相关/sql/2026-4-2/单据规则_BASE_BILLRULE_销假与补卡.sql`。

### 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_PunchInPhotoUploadRecordId` / `F_PunchOutPhotoUploadRecordId`: 上下班打卡照片在 `lq_upload_record` 中的记录 ID（与直传确认接口返回的 `uploadRecordId` 一致）；对外展示用访问地址由 `lq_upload_record.F_AccessUrl` 解析，**不在本表存 URL**
  - `F_IsPunchInFenceValid` / `F_IsPunchOutFenceValid`: 上下班围栏校验结果（1围栏内，0围栏外，null未校验）
  - `F_Status`: 打卡状态（1正常，2迟到，3休息，4请假，5病假，6缺卡，7旷工，8待考勤；8 表示考勤日晚于当前日期且尚无打卡，界面展示「暂无打卡」，不计入缺卡类异常统计）
  - `F_LateMinutes`: 迟到分钟数
  - `F_EarlyLeaveMinutes`: 早退分钟数
  - `F_IsManual`: 是否手动补录
  - `F_Remark`: 备注
  - `F_RuleSnapshotJson`: 规则快照JSON（保存打卡当日命中的**班次**考勤组、迟到早退规则等；其中月应休相关字段可与独立 `restGroup` 节点同时存在，汇总优先读快照内应休分组）
  - `F_AllRuleSnapshotJson`: 全量考勤规则快照JSON（保存打卡当时整套考勤设置，包括基础扣款倍率、公休、假期规则、缺卡/旷工/迟到早退规则、当前员工相关免考勤与额外假期配置等）
  - `F_SupplementRemark`: 补卡备注
  - `F_SupplementOperatorId` / `F_SupplementOperatorName` / `F_SupplementTime`: 补卡操作信息
  - `F_SupplementWorkflowId`: 关联补卡流程ID（可空）
  - `F_RelatedWorkflowsJson`: 关联流程 JSON（数组，记录与该日考勤相关的请假/补卡等流程，含类型、表单主键、单号、假种等，便于详情展示与追溯）
- **索引说明**:
  - `uk_attendance_record_user_date`: 保证同一员工同一天只有一条有效记录
  - `idx_attendance_record_month_group`: 支持按月份、分组快速查询月度矩阵
- **库表升级**：补上传记录列见 `项目文档相关/sql/2026-04-13/lq_attendance_record_打卡照片上传记录ID.sql`；删除冗余照片 URL 列见同目录 `lq_attendance_record_移除打卡照片URL列.sql`（按需执行）。
- **关联字段**:
  - `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`（打卡时考勤分组快照）
  - `lq_attendance_record.F_PunchInPhotoUploadRecordId` / `F_PunchOutPhotoUploadRecordId` ↔ `lq_upload_record.F_Id`（打卡照片上传记录）

#### 考勤汇总表 `lq_attendance_summary`

- **用途**：按月存放员工出勤/请假/休息等汇总天数，供算薪、花名册「有汇总时以汇总员工状态为准」等使用。
- **与打卡关系**：可通过接口 `POST /api/Extend/LqAttendanceSummary/SyncFromAttendanceRecords/{year}/{month}` **从 `lq_attendance_record` 重算**（删除该月全部汇总行后重建）。人选与月度考勤矩阵、花名册「当月在职」一致（见 Skill `historical-on-job-inference` / 代码 `AttendanceMonthOnJobUserQuery`）；按自然日取该日最新一条打卡记录的状态：正常+迟到→`F_WorkDays`，请假+病假→`F_LeaveDays`，休息→`F_RestDays`；生成行 `F_EmployeeStatus=1`（在职）。未来月不允许从打卡生成。
- **当月考勤组展示**：管理端「考勤汇总列表」「月度考勤矩阵」中的考勤组文案按**该自然月**内有效打卡记录上的 `F_AttendanceGroupName` 快照聚合（月中换组时展示为「甲→乙」）；若当月无打卡快照则回退为**用户主门店**在 `lq_mdxx` 上当前默认考勤分组名称，便于与后续按考勤组规则扣款口径对齐。
- **汇总列表扩展列（实时自打卡）**：`GET /api/Extend/LqAttendanceSummary` 在分页结果上按人、按自然月从 `lq_attendance_record` 折叠为「每日一条」后计算：应休（`F_RuleSnapshotJson` 内 `restGroup.monthlyRestDays` 优先，其次 `attendanceGroup.monthlyRestDays` 快照字段，否则主档：`F_AttendanceRestGroupId` 应休表优先，再否则门店班次绑定的 `F_DefaultRestGroupId` 应休表）、到岗（状态正常+迟到）、工作天数=应休+到岗、带薪请假（请假状态且假种非事假/病假）、请假合计（请假+病假）、迟到早退天数（迟到或早退分钟大于 0）、旷工天数；扣款额为规则「固定金额」时自 `F_RuleSnapshotJson`/`F_AllRuleSnapshotJson` 汇总（迟到+早退合并一列金额）；请假扣款为日薪×`baseSetting` 倍率，**未传员工日薪时金额为 0**（后续可与薪酬日薪对接）。
- **主要字段**：`F_UserId`、`F_Year`、`F_Month`、`F_EmployeeStatus`（1 在职，2 离职，3 停薪留职）、`F_WorkDays`、`F_LeaveDays`、`F_RestDays`、`F_IsEffective`。

#### 通用业务操作日志 `lq_business_operation_log`

- **用途**: 跨模块记录「谁、何时、对哪条业务、执行何种动作」，扩展信息放 `F_DetailJson`（JSON）。当前用于「取消流程补卡」等；后续订单、库存等可复用同一表与服务。
- **主要字段**: `F_ModuleCode`（如 `ATTENDANCE`）、`F_ActionCode`（如 `CANCEL_WORKFLOW_SUPPLEMENT`）、`F_BizType` / `F_BizId`、`F_Summary`、`F_DetailJson`、`F_OperatorUserId`、`F_OperatorUserName`、`F_OperateTime`。
- **建表脚本**: `项目文档相关/sql/2026-4-2/创建业务操作日志表_lq_business_operation_log.sql`。

#### 用户主档变更审计 `lq_user_profile_audit`（规划/R-001）

- **用途**: 记录 `BASE_USER` 字段级变更（何人、何时、何种动作、何字段、旧值→新值），用于算薪/考勤纠纷追溯；敏感字段按规范脱敏或不存明文。
- **主要字段**: `F_TargetUserId`（被改用户）、`F_OperatorUserId` / `F_OperatorUserName` / `F_OperateTime`、`F_Action`（如 `PROFILE_UPDATE`、`ADMIN_RESET_PASSWORD`）、`F_BatchId`（同次请求）、`F_FieldKey` / `F_FieldLabel`、`F_OldValue` / `F_NewValue`、`F_Source`、`F_ClientIp` / `F_UserAgent`（可选）、`F_Remark`（可选）。
- **设计文档**: `项目文档相关/docs/用户主档与薪酬考勤改造记录.md`（R-001 详细设计）。
- **建表脚本**: `项目文档相关/sql/2026-4-3/R-001_用户主档变更审计表_lq_user_profile_audit.sql`。
- **说明**: 可选方案为复用 `lq_business_operation_log`（`F_BizType=base_user`），见 R-001 脚本内注释。

#### 员工门店归属快照 `lq_employee_store_assignment`（规划/R-002）

- **用途**: 按日切段记录员工归属门店，支撑历史月工资与补录按「发生日」取门店，减少对当前 `BASE_USER.F_Mdid` 的依赖。
- **主要字段**: `F_EmployeeId`、`F_StoreId`、`F_StoreName`、`F_Year`、`F_Month`、`F_StatisticsMonth`、`F_StartDate`、`F_EndDate`、`F_IsEffective`（软删）、`F_Remark` 及创建/更新人、时间。
- **关联**: `F_EmployeeId` → `BASE_USER.F_Id`；`F_StoreId` → `lq_mdxx.F_Id`。
- **建表脚本**: `项目文档相关/sql/2026-4-3/R-002_员工门店归属快照表_lq_employee_store_assignment.sql`。
- **设计文档**: `项目文档相关/docs/员工门店归属快照表方案详细设计.md`、`用户主档与薪酬考勤改造记录.md`。

#### 门店主档时点版本 `lq_store_profile_version`（规划/R-003）

- **用途**: 门店资料变更形成**时点版本**，支撑考勤「当时打卡规则」回看与算薪按历史取 `F_StoreType`/`F_StoreCategory`/`zxzt`/`dhhm` 等。
- **主要字段**: `F_StoreId`、`F_VersionNo`、`F_ValidFrom`/`F_ValidTo`、操作人、`F_AttendanceSnapshotJson`、`F_StoreType`、`F_StoreCategory`、`F_Zxzt`、`F_Dhhm`、`F_Status`、`F_Dm`、`F_FullExtensionJson`（可选）。
- **关联**: `F_StoreId` → `lq_mdxx.F_Id`。
- **建表脚本**: `项目文档相关/sql/2026-4-3/R-003_门店主档版本快照表_lq_store_profile_version.sql`。
- **设计文档**: `项目文档相关/docs/用户主档与薪酬考勤改造记录.md`（R-003）。

#### 用户主档时点全量版本 `lq_user_profile_version`（R-004）

- **用途**: 用户主档变更形成**时点全量快照**（与 R-001 字段 diff 互补），便于按任意月末时点还原业务主档用于算薪/统计；JSON 内为脱敏 `UserEntity`（密码、密钥清空）。
- **主要字段**: `F_TargetUserId`、`F_VersionNo`、`F_ValidFrom`/`F_ValidTo`、`F_OperatorUserId`、`F_OperatorUserName`、`F_ChangeTrigger`、冗余 `F_Mdid`/`F_Gw`/`F_OrganizeId`、`F_FullSnapshotJson`。
- **关联**: `F_TargetUserId` → `BASE_USER.F_Id`。
- **建表脚本**: `项目文档相关/sql/2026-04-04/R-004_用户主档全量时点版本_lq_user_profile_version.sql`。

### 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` 或其他历史人员表
- **区间规则**: 婚假、丧假、年假、产假、迟到、缺卡、旷工规则统一按“最小值包含、最大值不包含”处理，最大值留空表示无上限
- **人员归属**: 员工**上下班班次**以主门店 `lq_mdxx.F_AttendanceGroupId` 为准；可打卡门店范围见 `BASE_USER.F_PunchAllowedStoreIds`（空则仅主门店）。免考勤人员使用 `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)

- 待补充具体枚举值

### 沟通记录 (lq_yaoyjl)

- **lxjl**：联系记录文字
- **lxjl_voice**：联系记录语音附件（与 `OssDirectUpload/ConfirmUpload` 返回的 `url` 一致，可为站点根相对路径；小程序播放时需拼 API 域名）。变更脚本：`项目文档相关/sql/2026-04-28/lq_yaoyjl_联系记录语音_lxjl_voice.sql`

---

## 开发注意事项

### 1. 查询优化

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

### 2. 数据一致性

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

### 3. 业务逻辑

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

### 4. 字段映射

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

### 5. 权限控制

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

---

## OSS 直传与图片审核

### `lq_upload_record`（上传记录 / 异步审核）

- **用途**：前端直传 OSS 后 `ConfirmUpload` 落库，Hangfire 队列执行 `ImageAuditJob` 做应用侧绿网审核。
- **兼容**：历史行 `F_AccessUrl` / `F_ThumbnailPublicUrl` 为空时，列表仍按 `F_ObjectKey` + `AliyunOSS:CustomDomain` 或 `LocalFileBaseUrl`+`/api/File/Image/...` 拼带域名 URL。
- **主要字段**：
  - `F_Id`：上传记录主键（可与业务表「仅绑图片记录 ID」方案关联）。
  - `F_ObjectKey`：OSS 完整对象键。
  - `F_FileType`：文件类型目录（如 `annexpic`、`attendancepic`）。
  - `F_AuditStatus`：0 待审 / 1 通过 / 2 违规 / 3 审核失败。
  - `F_AccessUrl`：图片**原图**对外完整 URL（须带域名）；`ConfirmUpload` 时写入 OSS 地址；违规落盘后改为 `{LocalFileBaseUrl}/api/Extend/OssDirectUpload/IllegalImage/{F_Id}`。
  - `F_ThumbnailPublicUrl`：缩略图对外完整 URL（须带域名），与 OSS 图片样式参数一致；违规落盘后可与 `F_AccessUrl` 相同。
  - `F_IllegalLocalPath`：审核不通过时，文件落在 `**NCC_App:SystemPath` + `IllegalImage/`** 下的**绝对物理路径**（不再使用独立 `IllegalImages` 配置节）。
  - `F_AuditRawResponse`：内容安全接口原始响应（TEXT，可截断）。

**库表升级**：`F_AuditRawResponse` 见 `项目文档相关/sql/2026-04-13/lq_upload_record_图片审核字段.sql`；`F_ThumbnailPublicUrl` 与字段长度见同目录 `lq_upload_record_缩略图URL与字段长度.sql`。

**配置说明**：`NCC_App:ImageModeration:Enabled=true` 且 `**SyncOnUpload=false`**（推荐）时，`FileService` 服务端上传 OSS 不再同步调绿网；直传场景由 `ConfirmUpload` 后 Hangfire 调用 `ImageAuditJob` 审核并写回 `F_AuditReason` / `F_AuditRawResponse`。若需恢复旧版「上传即审」，将 `**SyncOnUpload`** 设为 `true`。

---

## 视图说明

### 业绩统计视图

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

### 开单相关视图

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

---