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

## 📋 目录

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

---

## 数据库基本信息

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

---

## 表关系图

### 核心业务流程图

```
门店信息 (lq_mdxx) ← 门店房间 (lq_md_room，预约可选)
    ↓
用户信息 (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`；员工作为团队成员时，上下班时间以此门店默认班次为准（人员表不存考勤分组列）。
- **门店房间表**: `lq_md_room`（门店下可预约/可排程房间，**一对多** 挂 `lq_mdxx`）。管理端在「门店信息」弹窗「房间信息」页签维护。建表脚本：`项目文档相关/sql/2026-05-09/lq_md_room_门店房间.sql`。
  - `F_Id`：主键（雪花字符串）
  - `F_StoreId`：门店 ID，关联 `lq_mdxx.F_Id`
  - `F_RoomName`：房间名称（必填）
  - `F_SortNo`：排序号（越小越靠前）
  - `F_Enabled`：是否启用（1 启用 / 0 停用）
  - `F_RoomType`：房间类型，与后端枚举 `LqStoreRoomTypeEnum` 一致（护理室=1、咨询室=2、其他=9）
  - `F_Capacity`：可容纳人数（可空，供预约参考）
  - `F_Remark`：备注
  - `F_CreateTime` / `F_LastModifyTime`：创建与最后修改时间
  - **接口**：`GET /api/Extend/LqMdRoom/GetByStoreId?storeId=` 列表；`POST /api/Extend/LqMdRoom/SaveByStore` 整单保存（请求体中未包含的已有房间行将删除）；`GET /api/Extend/LqMdRoom/Selector/RoomType` 类型下拉。后续预约在 `lq_yyjl` 等表上可增加 `F_RoomId` 关联本表 `F_Id`。
- **人员信息**: `BASE_USER` (系统用户表，包含门店ID等扩展字段)
- **员工档案扩展**: `lq_employee_profile` 与 `BASE_USER.F_Id` 一对一；入职日期仍用 `F_ENTRYDATE`，扩展用工/银行/教育/经历字段
- **扫码入职待审**: `lq_employee_profile_submission` 匿名填报快照，审核通过后才写主档（见 `项目文档相关/sql/2026-07-18/员工档案扩展与扫码入职申请表.sql`）
- **用户主档时点全量版本（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_hzf`（开单合作机构、结算机构名称）
- **关联字段**:
  - `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`
  - `lq_kd_kdjlb.hgjg` ↔ `lq_hzf.F_Id`（合作机构）
  - `lq_kd_kdjlb.fkyy` ↔ `lq_hzf.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` (科技部老师业绩关联品项明细)
- **沉睡回店统计索引（建议，见 `项目文档相关/sql/2026-07-23/优化沉睡回店统计索引.sql`）**:
  - `idx_xh_hyhk_effective_hksj_hy_md (F_IsEffective, hksj, hy, md)`：周期候选聚合 + 门店筛选
  - 已有 `idx_xh_hyhk_member_effective (hy, F_IsEffective, hksj)`、`idx_xh_hyhk_effective_date (F_IsEffective, hksj)` 可支撑 MAX 上一到店日

### 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` (退卡记录关联会员)
- **退款机构反查**: 退卡表不直接保存合作/结算机构；通过
  `lq_hytk_mx.F_BillingItemId → lq_kd_pxmx.F_Id → lq_kd_pxmx.glkdbh → lq_kd_kdjlb.F_Id`
  反查原开单的 `hgjg`（合作机构）与 `fkyy`（结算机构）。历史明细缺少 `F_BillingItemId` 时机构显示为空。

### 5.1 大项目部老师月度门店归属

- **归属表**: `lq_md_major_project_teacher_assignment`
- **人员来源**: `F_TeacherId`、`F_EducationTeacherId` 均关联 `BASE_USER.F_Id`，禁止使用已弃用的 `lq_ryzl`
- **门店来源**: `F_StoreId` 关联 `lq_mdxx.F_Id`
- **月份字段**: `F_Year`（yyyy）+ `F_Month`（MM）
- **归属粒度**: 同一门店、同一月份可配置多名老师；同一老师同月也可负责多个门店
- **唯一约束**: `(F_StoreId, F_Year, F_Month, F_TeacherId)`
- **用途**: 大项目老师工资、手机端“大项目老师明细”等按老师本人限制可见门店范围；无当月归属时必须返回空，不得退化为全门店
- **与门店组织归属的区别**: `lq_md_target.F_MajorProjectDepartment` 表示门店当月归属的大项目组织，不表示具体老师；老师人员归属以本表为准

### 6. 报销申请与流程配置关系

- **报销申请表**: `lq_reimbursement_application`
- **购买记录表**: `lq_purchase_records`
- **流程配置表**: `lq_reimbursement_workflow_config`
- **编号序列表**: `lq_reimbursement_application_sequence`
- **关联字段**: `lq_reimbursement_application.F_WorkflowConfigId` ↔ `lq_reimbursement_workflow_config.F_Id`（可选，用于返回流程名称 workflowName）
- **购买记录关联**: `lq_purchase_records.F_ApplicationId` ↔ `lq_reimbursement_application.F_Id`
- **收款人字段**: `lq_purchase_records.F_PayeeName`（`varchar(100)`，可空以兼容历史数据；新建或编辑购买记录时业务校验必填）
- **业务编号**: `lq_reimbursement_application.F_ApplicationNo`（`varchar(32)`，唯一索引；格式 `ZC-yyyy-M-序号`，如 `ZC-2026-7-001`）
- **月度序列**: `lq_reimbursement_application_sequence.F_Period`（主键，格式 `yyyy-M`）记录每个自然月的 `F_CurrentValue`；创建申请时在同一事务内原子递增，保证并发编号不重复

### 7. 考勤设置关系

- **考勤设置主表**: `lq_attendance_setting`
- **公休日期表**: `lq_attendance_holiday`
- **考勤分组表**: `lq_attendance_group`存**班次**（上下班时间、**上午下班/下午上班半天边界**（`F_AmWorkEndTime`、`F_PmWorkStartTime`）、启用、备注、解锁场景下的迟到/早退容忍等）；`F_DefaultRestGroupId` 指向本条班次绑定的**默认应休分组**（`lq_attendance_rest_group`）。~~`F_MonthlyRestDays` / `F_HalfDaySplitRestDays` / `F_RestUnlockCycle`~~ 已从本表删除，迁出至应休表（脚本：`项目文档相关/sql/2026-05-06/2026-05-06_考勤扩展_全量合并.sql`（节 B））。半天时段字段脚本：`项目文档相关/sql/2026-07-30/lq_attendance_group_半天时段字段.sql`。
- **应休分组表**: `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_LEAVEAPPLY.F_APPLYDEPTID` ↔ `BASE_ORGANIZE.F_Id`（申请部门组织 ID，取用户所属组织本级，与 `F_APPLYDEPT` 名称一致）。DDL：`项目文档相关/sql/2026-6-12/wform_leaveapply_增加申请部门ID_F_APPLYDEPTID.sql`
  - **销假流程表** `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_SupplementCountAsNormal`: 补卡是否按正常考勤计入全勤（1=是，0/null=否）；流程/后台补卡写入时默认 0；管理员可在打卡详情放行。当月任一未放行补卡日则整月非全勤
  - `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`（按需执行）；补卡计入全勤开关见 `项目文档相关/sql/2026-07-24/lq_attendance_record_补卡是否按正常考勤算.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**（后续可与薪酬日薪对接）。
- **数据来源**：打卡同步（备注含「系统按考勤打卡汇总生成」）与 Excel 导入（备注前缀 `[Excel导入]`，可选列 `F_DataSource=2`）互斥展示；算薪 `WorkingDays` 对导入行取 `F_WorkDays`（出勤天数），对同步行取打卡汇总。脚本：`项目文档相关/sql/2026-6-12/lq_attendance_summary_增加数据来源_F_DataSource.sql`。
- **主要字段**：`F_UserId`、`F_Year`、`F_Month`、`F_EmployeeStatus`（1 在职，2 离职，3 停薪留职）、`F_WorkDays`、`F_LeaveDays`、`F_RestDays`、`F_DataSource`、`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`。

#### 员工档案扩展 `lq_employee_profile`

- **用途**: 与 `BASE_USER` **一对一**扩展员工档案字段；姓名、手机、身份证、入职时间等主档字段仍在 `BASE_USER`（`F_ENTRYDATE` 为考勤/算薪/司龄唯一口径，本表**不重复**存储）。
- **关联**: `F_UserId` → `BASE_USER.F_Id`（唯一索引 `UK_lq_employee_profile_UserId`）。
- **主要字段**:
  - 用工档案：`F_MaritalStatus`、`F_PoliticalStatus`、`F_HouseholdType`、`F_CurrentAddress`、`F_EmployeeNo`（可空、非空唯一）、`F_EmployeeType`（全职/实习/其他）、`F_EmployeeStatus`（正式/试用/待离职，与 `F_IsOnJob` 分离）、`F_ProbationMonths`（3/6）、`F_RegularizationDate`、`F_RecruitmentType`
  - 银行：`F_BankName`、`F_BankCardCipher`（密文，禁止明文列）、`F_BankAccountName`（开户实名）
  - 身份证材料：`F_IdCardAddress`（完整地址，独立于 `BASE_USER.F_NATIVEPLACE`）、`F_IdCardFrontUrl`、`F_IdCardBackUrl`
  - 教育/经历：`F_GraduateSchool`、`F_EnrollmentDate`、`F_GraduationDate`、`F_Major`、`F_PreviousCompany`、`F_PreviousPosition`、`F_PreviousStartDate`、`F_PreviousEndDate`
  - 紧急联系人扩展：`F_EmergencyContactRelation`、`F_EmergencyContactAddress`（姓名/电话仍在 `BASE_USER.F_URGENTCONTACTS` / `F_URGENTTELEPHONE`）
  - 审计：`F_CreateTime`/`F_UpdateTime`/`F_CreateUser`/`F_UpdateUser`、`F_LastReviewUserId`/`F_LastReviewUserName`/`F_LastReviewTime`
- **派生字段（不落库）**: 年龄按身份证出生日期实时计算；司龄按 `BASE_USER.F_ENTRYDATE` 实时计算。
- **索引**: `UK_lq_employee_profile_UserId`、`UK_lq_employee_profile_EmployeeNo`（可空）。
- **建表脚本**: `项目文档相关/sql/2026-07-18/员工档案扩展与扫码入职申请表.sql`。
- **实体**: `NCC.Extend.Entitys.lq_employee_profile.LqEmployeeProfileEntity`。

#### 员工档案匿名提交 `lq_employee_profile_submission`

- **用途**: 通用二维码匿名填报的**待审核区**；审核通过后才事务写入 `BASE_USER` + `lq_employee_profile`；禁止匿名接口直接建号。
- **状态枚举**: 待审核(1)、已通过(2)、已驳回(3)、已作废(4)。
- **关联**: 审核通过后 `F_LinkedUserId` → `BASE_USER.F_Id`。
- **敏感字段**: `F_IdCardCipher` / `F_BankCardCipher` 存密文；`F_IdCardHash`（char(64)）用于身份证查重索引，**不对密文建唯一**；列表/接口默认脱敏。
- **主档快照列**: `F_RealName`、`F_MobilePhone`、`F_Gender`、`F_Birthday`、`F_Nation`、`F_NativePlace`、`F_Education`、`F_EntryDate`（申请入职日，通过后写 `BASE_USER.F_ENTRYDATE`）、组织/门店/岗位、`F_UrgentContacts`/`F_UrgentTelePhone`/`F_PostalAddress` 等；证件类型固定身份证，不重复存储。
- **档案扩展快照列**: 与 `lq_employee_profile` 同名字段（含 `F_BankAccountName`、`F_IdCardAddress`、`F_IdCardFrontUrl`、`F_IdCardBackUrl`）+ `F_FormSnapshotJson`（身份证、银行卡仅保存脱敏值的 JSON 备份）。
- **流程字段**: `F_SubmissionNo`（申请编号，唯一）、`F_Status`、`F_RejectReason`、`F_ReviewUserId`/`F_ReviewUserName`/`F_ReviewTime`、`F_SubmitSource`/`F_SubmitIp`/`F_SubmitTime`/`F_UserAgent`、`F_VoidUserId`/`F_VoidTime`。
- **索引**: `UK_lq_employee_profile_submission_No`；`IDX_lq_employee_profile_submission_Status_SubmitTime`；`IDX_lq_employee_profile_submission_IdCardHash`；`IDX_lq_employee_profile_submission_MobilePhone`。
- **建表脚本**: `项目文档相关/sql/2026-07-18/员工档案扩展与扫码入职申请表.sql`。
- **实体**: `NCC.Extend.Entitys.lq_employee_profile_submission.LqEmployeeProfileSubmissionEntity`。

#### 人事调动/离职填报 `lq_personnel_report`

- **用途**: 门店端提交调动/离职人事填报的**独立待办区**；不联动更新 `BASE_USER`、`lq_employee_profile`、流程、考勤、算薪等主业务表。
- **类型枚举**: 调动(1)、离职(2)。
- **处理状态**: 待处理(0)、已处理(1)；恢复待处理时清空处理人/处理时间。
- **快照字段**: 来源组织/门店、提交人、被填报员工姓名/手机、目标门店名称等均由服务端从当前用户或被填报人快照写入。
- **关联**: `F_ApplicantUserId` → `BASE_USER.F_Id`（只读校验，不写回）；`F_SourceMdid`/`F_TargetMdid` → `lq_mdxx.F_Id`（快照名称）。
- **流程字段**: `F_ReportNo`（填报编号，唯一）、`F_SubmitTime`、`F_HandleUserId`/`F_HandleUserName`/`F_HandleTime`/`F_HandleRemark`。
- **索引**: `UK_lq_personnel_report_No`；`IDX_lq_personnel_report_Handle_SubmitTime`；`IDX_lq_personnel_report_SourceOrg_SubmitTime`；`IDX_lq_personnel_report_Type_Handle`；`IDX_lq_personnel_report_ApplicantUserId`。
- **建表脚本**: `项目文档相关/sql/2026-07-18/人事调动离职填报表.sql`。
- **实体**: `NCC.Extend.Entitys.lq_personnel_report.LqPersonnelReportEntity`。
- **API**: `LqPersonnelReportService`，前缀 `/api/Extend/LqPersonnelReport`。

#### 员工到院转化登记 `lq_member_arrival_record`

- **用途与边界**: 员工确认会员已到院后的独立登记、见诊/成交结果维护及转化统计。模块只读 `lq_khxx`、`BASE_USER`、组织和门店；**不回写**会员主档、`FirstVisitTime`、预约、沟通、开单、耗卡、工资及人头自动统计表。
- **主键与编号**: `F_Id`（应用层 `YitIdHelper.NextId().ToString()`）；`F_RecordNo`（对外登记编号，唯一）；`F_RecordKey`（有效记录唯一键，格式 `门店ID_会员ID_yyyyMMdd`，作废时置空，使同门店+会员+自然日仅一条有效记录且作废后可重新登记）。
- **会员快照字段**: `F_MemberId`、`F_MemberName`、`F_MemberMobile`；`F_MemberId` 只读关联 `lq_khxx.F_Id`，提交时校验 `lq_khxx.gsmd = F_SourceMdid`。手机号在企业内部接口完整返回，但业务操作日志不得记录手机号。
- **来源快照字段**: `F_SourceOrganizeId`、`F_SourceOrganizeName`、`F_SourceMdid`、`F_SourceMdName`，均由服务端按登记人当前 `BASE_USER`、组织、`lq_mdxx` 快照生成，不接受前端指定门店。
- **到院与结果字段**: `F_ArrivalType`、`F_ArrivalTime`、`F_ConsultationStatus`、`F_ConsultationTime`、`F_DealStatus`、`F_DealTime`。到院类型枚举：售前(1)、售后(2)；见诊/成交状态枚举：待确认(0)、是(1)、否(2)。成交=是时见诊必须=是；见诊改为否时成交规范化为待确认；状态时间在状态变更时设置，恢复待确认时清空。
- **登记与修改字段**: `F_RecorderUserId`、`F_RecorderUserName`、`F_LastModifyUserId`、`F_LastModifyUserName`、`F_Remark`、`F_Version`、`F_CreateTime`、`F_UpdateTime`。`F_Version` 从 1 开始，用于更新结果和作废的乐观锁。
- **有效与作废字段**: `F_IsEffective`（1有效、0作废）、`F_VoidReason`、`F_VoidUserId`、`F_VoidUserName`、`F_VoidTime`。作废为软作废，同时将 `F_RecordKey` 置空、版本加一；作废记录不参与统计。
- **统计口径**: 所有筛选均按 `F_ArrivalTime`；只统计有效记录；所选范围内按 `F_MemberId` 去重，同一会员有多条记录时以最后一次到院记录决定售前/售后以及最终见诊/成交状态，因此售前人头+售后人头=总人头；`recordCount` 为筛选范围内未去重的有效登记数。
- **索引**: 主键 `PRIMARY(F_Id)`；唯一索引 `UK_lq_member_arrival_record_No(F_RecordNo)`、`UK_lq_member_arrival_record_RecordKey(F_RecordKey)`；查询索引 `IDX_lq_member_arrival_ArrivalTime_Effective(F_ArrivalTime,F_IsEffective)`、`IDX_lq_member_arrival_SourceOrg_ArrivalTime(F_SourceOrganizeId,F_ArrivalTime)`、`IDX_lq_member_arrival_SourceMd_ArrivalTime(F_SourceMdid,F_ArrivalTime)`、`IDX_lq_member_arrival_Member_ArrivalTime(F_MemberId,F_ArrivalTime)`、`IDX_lq_member_arrival_Recorder_ArrivalTime(F_RecorderUserId,F_ArrivalTime)`、`IDX_lq_member_arrival_Type_Status(F_ArrivalType,F_ConsultationStatus,F_DealStatus)`。
- **建表脚本**: `项目文档相关/sql/2026-07-20/员工到院转化记录表.sql`；菜单与权限脚本：`项目文档相关/sql/2026-07-20/员工到院转化菜单与权限.sql`。
- **实体**: `NCC.Extend.Entitys.lq_member_arrival_record.LqMemberArrivalRecordEntity`。
- **API**: `LqMemberArrivalService`，前缀 `/api/Extend/LqMemberArrival`；写操作及导出写入 `lq_business_operation_log`，模块编码为“员工到院信息”。

#### 会员自定义标签 `lq_member_tag` / `lq_member_tag_rel`

- **用途**: 全公司共用标签库；会员通过关联表打标，标签名 ≤5 字、支持 `F_Color`；单会员标签上限由 `sys_config.memberCustomTagMaxCount` 配置（默认 5）。
- **主要字段（`lq_member_tag`）**:
  - `F_Id`：主键（`YitIdHelper`）
  - `F_TagName`：标签名，全库唯一
  - `F_Color`：颜色 hex，默认 `#409EFF`
  - `F_CreateTime` / `F_CreatorUserId` / `F_LastModifyTime` / `F_LastModifyUserId`
- **主要字段（`lq_member_tag_rel`）**:
  - `F_Id`：主键
  - `F_MemberId` ↔ `lq_khxx.F_Id`
  - `F_TagId` ↔ `lq_member_tag.F_Id`（唯一约束：会员+标签）
  - `F_Source`：1 管理后台 / 2 门店 PC / 3 员工小程序
  - `F_CreateTime` / `F_CreatorUserId`
- **删除规则**: 物理删除标签时级联删除全部 `lq_member_tag_rel`；取消会员标签仅删关联。
- **建表脚本**: `项目文档相关/sql/2026-07-30/创建会员自定义标签表_lq_member_tag.sql`
- **接口**: `LqMemberTagService`，前缀 `/api/Extend/LqMemberTag`

### 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` | 原分类①汇总·板块 | **已废弃**（阶段一产品不再维护；库列暂留，阶段二可 DROP） |
| `fl2` | 原分类②汇总·业态 | **已废弃**（同上；业态业务认 `qt2`，不认 fl2） |
| `fl3` | 分类③工资用 | **在用**：基础业绩 / 合作业绩；开单耗卡写入业绩类型，算薪依赖 |
| `fl4` | 原分类④统计品项用 | **已废弃**（同上） |
| `qt1` | 其它1·板块/卡类 | **在用**：储值卡判定固定认 `qt1 = 储值` |
| `qt2` | 其它2·业态大类 | **在用**：生美/医美/科美/合作等；开单耗卡 `F_ItemCategory` 来源 |

备份参考：`ExportFiles/lq_xmzl_backup_fl1234_20260729.csv`；DROP 脚本（勿擅自执行）：`项目文档相关/sql/2026-07-29/lq_xmzl_DROP_fl1_fl2_fl4_阶段二待执行.sql`。

### 金三角状态 (lq_jinsanjiao_user.status)

- `ACTIVE`: 活跃
- `INACTIVE`: 非活跃

### 预约状态 (lq_yyjl.F_Status)

- **存储**：字符串（中文），存量默认视为「已预约」。
- **取值**：`已预约`、`服务中`、`已转耗卡`、`已完成`、`已取消`（详见后端枚举 `LqYyjlStatusEnum` / `LqYyjlStatusTexts`）。

### 预约计划品项 (lq_yyjl_px)

- **用途**：预约主表 `lq_yyjl` 的计划品项子表；仅 `F_Px` 有值的行写入；`F_IsEffective=1` 有效，`0` 为软删历史。
- **主要字段**：`F_Id`、`F_YyjlId`、`F_Px`、`F_Pxmc`、`F_Pxjg`、`F_ProjectNumber`、`F_SourceType`、`F_BillingItemId`、`F_Jks`、`F_Jksxm`、`F_Remark`、`F_SortNo`、`F_IsEffective`、`F_CreateTime`、`F_LastModifyTime`。

- **系统参数**（`BASE_SYSCONFIG`，`Category`=`SysConfig`）：
  - `consumeEditableDays`：小程序端耗卡可修改/作废/重开单天数，默认 **3**。
  - `consumeAllowCrossMonthEdit`：小程序端是否允许跨月修改/作废/重开单，**1=允许 / 0=不允许**，默认 **0**；关闭时耗卡月份与当前月不同即禁止（即使仍在可修改天数内）。
  - `adminConsumeVoidEditableDays`：管理后台作废耗卡允许天数，默认 **0**（0=不限制）；按钮权限 `btn_cancel`。
  - `adminConsumeDeleteEditableDays`：管理后台删除耗卡允许天数，默认 **0**；按钮权限 `btn_remove`。
  - 已废弃合并项 `adminConsumeCancelEditableDays`（读取天数时兼容）。

### 预约计划品项-计划健康师 (lq_yyjl_px_jks)

- **用途**：挂在 `lq_yyjl_px` 下的计划层多健康师（不参与业绩）；转耗卡时由前端带入 `lqXhJksyjList` 雏形。
- **约束**：同一 `F_YyjlPxId` 下 `F_Jks` 不可重复；跨品项允许同人。
- **主要字段**：`F_Id`、`F_YyjlId`、`F_YyjlPxId`、`F_Jks`、`F_Jksxm`、`F_SortNo`、`F_IsEffective`、`F_CreateTime`、`F_LastModifyTime`。
- **冗余**：`lq_yyjl_px.F_Jks` / `F_Jksxm` 存该行计划健康师首位（与 `jksList` 首项一致时可由服务端写入）。

### 沟通记录 (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`。

#### 品项分类配置 `lq_item_category_config`

- **用途**: 品项分类「内部编码 → 可变显示名/颜色」映射；内部编码与 `lq_xmzl.qt2` 及 11 张明细表 `F_ItemCategory` 保持一致（中文，零迁移），仅通过本表改显示名。
- **主要字段**:
  - `F_Id`：主键
  - `F_Code`：内部编码（如「医美」，唯一、不可变）
  - `F_DisplayName`：显示名称（初始等于 `F_Code`）
  - `F_Color`：颜色 hex（列表图标/图表）
  - `F_Sort`：排序
  - `F_Enabled`：是否启用（1 启用 / 0 停用）
  - `F_CreatorTime` / `F_CreatorUserId` / `F_LastModifyTime` / `F_LastModifyUserId` / `F_DeleteMark`：审计字段（`F_DeleteMark` 为 `null` 表示未删除）
- **种子数据**: 生美、医美、科美、合作、其他、产品（各 6 条，`F_DisplayName` 初始等于 `F_Code`）
- **建表脚本**: `项目文档相关/sql/2026-07-06/创建品项分类配置表_lq_item_category_config.sql`

#### 短信模板 `lq_sms_template`

- **用途**: 阿里云短信模板管理，按业务场景编码（如 `Birthday` / `Login` / `Register` / `VerifyCode`）绑定模板 CODE 与签名，可继续扩展新场景。
- **主要字段**:
  - `F_Id`：主键（`YitIdHelper`）
  - `F_Name`：模板名称
  - `F_TemplateCode`：阿里云模板 CODE（如 `SMS_503595047`）
  - `F_SignName`：签名（默认「绿纤聚财」）
  - `F_TemplateType`：类型（1 验证码 / 2 推广短信 / 3 通知短信）
  - `F_SceneCode`：业务场景编码（未删除记录内建议唯一，由服务校验）
  - `F_ParamTemplate`：参数 JSON 模板（占位符如 `{name}` / `{code}`）
  - `F_Enabled`：1 启用 / 0 停用
  - `F_Sort` / `F_Remark`：排序、备注
  - `F_CreatorTime` / `F_CreatorUserId` / `F_LastModifyTime` / `F_LastModifyUserId` / `F_DeleteMark`：审计（`F_DeleteMark` 为 `null` 表示未删除）
- **种子数据**: 生日提醒 `SMS_503595047`、用于登录 `SMS_489770174`、用于注册 `SMS_489645186`、验证码短信 `SMS_321375912`
- **建表脚本**: `项目文档相关/sql/2026-07-23/创建短信模板与发送日志表_lq_sms.sql`

#### 短信发送日志 `lq_sms_send_log`

- **用途**: 记录短信发送结果（成功/失败/防重跳过）；手机号默认存明文 + 哈希，接口返回时按系统隐私开关决定是否脱敏。
- **主要字段**:
  - `F_Id`：主键
  - `F_SceneCode` / `F_TemplateId` / `F_TemplateCode` / `F_SignName`：场景与模板
  - `F_MobileMasked`：手机号（默认明文；历史版本可能为脱敏值）
  - `F_MobileHash`：手机号哈希（防重比对）
  - `F_MemberId` / `F_MemberName`：会员（生日等业务）
  - `F_TemplateParam`：实际参数 JSON
  - `F_SendContent`：发送内容摘要（签名 + 模板名称/CODE + 参数，便于日志查看）
  - `F_Status`：0 失败 / 1 成功 / 2 跳过
  - `F_ProviderResult`：厂商返回说明
  - `F_BizDate`：业务日期（生日防重按日）
  - `F_IsTest`：是否测试发送
  - `F_CreatorTime` / `F_CreatorUserId`：发送时间与操作人
- **配置**: `BASE_SYSCONFIG` 中 `F_CATEGORY=SmsConfig`（`smskeyid` / `smskeysecret` / `smssignname` / `smscompany` / `smsendpoint` / `smspreventduplicate`）；可回退读取历史 `SysConfig` 同名键。**AccessKey 未在 SmsConfig 单独配置时，发送自动复用 `appsettings` → `NCC_App:AliyunOSS`（与 OSS 同源）**
- **隐私开关**: `BASE_SYSCONFIG` 中 `F_CATEGORY=SysConfig`、`F_KEY=privacymobilemask`（对应前端字段 `privacyMobileMask`）：`0` 默认明文展示，`1` 开启后发送日志/短信相关接口脱敏返回
- **建表脚本**: 同上 `创建短信模板与发送日志表_lq_sms.sql`

---

### 培训签到

#### 动态令牌 `lq_training_checkin_token`

- **用途**: 教室投屏页动态二维码令牌；短生命周期，到期自动轮换。
- **主要字段**:
  - `F_Id`：主键（`YitIdHelper`）
  - `token_hash`：令牌 SHA256 哈希（校验用）
  - `plain_token`：令牌明文（仅供投屏展示，短生命周期）
  - `expire_time`：过期时间
  - `create_time`：创建时间
- **配置**: `BASE_SYSCONFIG` / `SysConfig` 键 `trainingCheckinQrRotateMinutes`（默认 3 分钟，范围 1–60）
- **建表脚本**: `项目文档相关/sql/2026-07-30-培训签到表.sql`

#### 签到记录 `lq_training_checkin_record`

- **用途**: 匿名培训签到/签退记录；管理端列表查询与导出。
- **主要字段**:
  - `F_Id`：主键
  - `real_name`：姓名
  - `mobile_phone`：手机号
  - `checkin_type`：1 签到 / 2 签退
  - `checkin_time`：打卡时间
  - `submit_ip`：提交 IP
  - `token_id`：关联 `lq_training_checkin_token.F_Id`（可选审计）
  - `create_time`：创建时间

---

## 视图说明

### 业绩统计视图

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

### 开单相关视图

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

---