yuezi-saas/docs/05-module-details.md

# 宫中有喜 — 模块详细设计

## 一、模块总览

| 编号 | 模块 | 核心实体 | 关键流程 |
|------|------|----------|----------|
| 5.1 | CRM | 线索、客户、合同 | 线索→跟进→签约→入住 |
| 5.2 | 房务 | 房间、预定、入住 | 预定→入住→在住→离店 |
| 5.3 | 护理 | 档案、计划、记录 | 建档→制定计划→执行→异常处理 |
| 5.4 | 月子餐 | 菜品、排餐、送餐 | 排餐→备餐→送餐→反馈 |
| 5.5 | 服务产康 | 项目、套餐、订单 | 预约→排班→服务→评价 |
| 5.6 | 月嫂 | 月嫂、订单、评价 | 选嫂→派嫂→服务→评价 |
| 5.7 | 进销存 | 物资、库存、采购 | 采购→入库→领用→盘点 |
| 5.8 | 财务 | 账户、收支、发票 | 收款→记账→对账→报表 |
| 5.9 | 人事薪资 | 员工、排班、工资 | 入职→排班→考勤→算薪 |
| 5.10 | 办公协同 | 审批、公告、交接 | 发起→审批→通知→归档 |
| 5.11 | 统计报表 | 报表、图表 | 采集→聚合→可视化→导出 |
| 5.12 | 知识库 | 文章、分类 | 创建→审核→发布→检索 |
| 5.13 | 系统设置 | 门店、用户、角色 | 配置→分配→生效 |

---

## 二、5.1 CRM 客户关系管理

### 2.1 业务流程

```
线索来源（微信/电话/转介/活动/小程序）
    ↓
[线索池] → 自动/手动分配 → [跟进中]
    ↓                          ↓
  无效关闭              多次跟进记录
                               ↓
                        [意向确认] → 签约
                               ↓
                        [合同] → 审批 → 生效
                               ↓
                        [客户] → 关联入住/服务
```

### 2.2 线索状态机

| 状态 | 值 | 可流转至 |
|------|-----|----------|
| 新线索 | new | following, invalid |
| 跟进中 | following | intended, invalid |
| 有意向 | intended | contracted, invalid |
| 已签约 | contracted | — |
| 无效 | invalid | new（可回收） |

### 2.3 核心业务规则

- 线索分配规则：轮询分配 / 按区域分配 / 手动指定
- 线索回收：超过 N 天未跟进自动回收至公海池
- 跟进提醒：距上次跟进 3/7 天自动提醒
- 签约流程：需主管审批 → 财务确认 → 合同生效
- 客户标签：VIP / 重点关注 / 转介绍来源 等自定义标签
- 问卷评分：入住中期 + 离店时各一次满意度问卷

### 2.4 关键 Service 方法

```php
// LeadService
assignLead(leadId, userId)        // 分配线索
recycleLead(leadId)               // 回收至公海
convertToCustomer(leadId, data)   // 线索转客户+建合同
batchImport(file)                 // Excel批量导入

// ContractService
createContract(data)              // 创建合同
approveContract(contractId, action) // 审批
calculateAmount(items)            // 计算合同金额
generatePdf(contractId)           // 生成PDF
```

---

## 三、5.2 房务管理

### 3.1 房态状态机

```
空闲(available) ←→ 已预定(reserved)
      ↓                    ↓
 已入住(occupied) ←── 办理入住
      ↓
 待清洁(cleaning) ← 办理离店
      ↓
 维修中(maintenance)
      ↓
 空闲(available)
```

### 3.2 核心业务规则

- 房间编号规则：楼层号 + 序号（如 301、302）
- 房型定价：基础日价 × 天数，支持季节浮动系数
- 预定冲突检测：同一房间日期区间不可重叠
- 入住办理：预定 → 验证身份 → 分配房间 → 入住登记
- 换房规则：在住期间可换房，自动调整账单
- 延住规则：检查目标日期房间是否可用 → 调整账单
- 房态看板：日历视图，支持按周/月切换，颜色区分状态

### 3.3 关键 Service 方法

```php
// RoomService
checkAvailability(roomId, startDate, endDate)  // 检查可用性
getRoomBoard(date, range)                       // 房态看板数据

// ReservationService
createReservation(data)           // 新建预定
cancelReservation(id, reason)     // 取消预定
checkIn(reservationId, data)      // 办理入住

// CheckInService
changeRoom(checkInId, newRoomId)  // 换房
extend(checkInId, newEndDate)     // 延住
checkOut(checkInId)               // 离店
```

---

## 四、5.3 护理管理

### 4.1 护理流程

```
入住 → 建立护理档案（产妇+新生儿）
  ↓
评估体质/需求 → 制定个性化护理计划
  ↓
每日执行护理任务（按计划模板）
  ↓
记录护理项目 + 健康指标
  ↓
异常登记 → 处理 → 闭环
  ↓
离店总结 → 护理报告
```

### 4.2 护理档案内容

**产妇档案**：基本信息、分娩信息（日期/方式/胎次）、过敏史、饮食禁忌、体质评估

**新生儿档案**：出生信息、体重、身长、Apgar 评分、特殊情况

### 4.3 健康指标追踪

| 对象 | 指标 | 频率 |
|------|------|------|
| 产妇 | 体温、血压、恶露、伤口 | 日/2次 |
| 产妇 | 体重、情绪评估 | 周/1次 |
| 新生儿 | 体温、体重、身长 | 日/1次 |
| 新生儿 | 喂奶量、排便次数、黄疸 | 日/多次 |

### 4.4 核心业务规则

- 护理计划模板：按阶段（第1周、第2周...）预设任务
- 任务打卡：护理人员执行后打卡确认，支持拍照
- 异常三级：一般（记录即可）/ 注意（通知主管）/ 紧急（立即通知家属+医生）
- 交接班：上一班护理记录自动同步至下一班

### 4.5 关键 Service 方法

```php
// CareProfileService
createProfile(checkInId)               // 入住时自动建档
generateReport(profileId)             // 生成护理报告

// CarePlanService
createFromTemplate(profileId, templateId) // 从模板创建计划
activatePlan(planId)                  // 激活计划
getTasksForDate(profileId, date)      // 获取当日任务

// CareRecordService
createRecord(data)                    // 记录护理项目
recordHealthMetric(data)              // 录入健康指标
getMetricChart(profileId, metric, range) // 指标趋势

// CareAlertService
createAlert(data)                     // 创建异常
resolveAlert(alertId, resolution)     // 处理异常
```

---

## 五、5.4 月子餐管理

### 5.1 排餐流程

```
菜品库维护 → 餐单模板制定
  ↓
每日排餐（可从模板复制）
  ↓
按时段送餐（早/早点/午/午点/晚/晚点）
  ↓
送达确认 → 客户反馈
```

### 5.2 核心业务规则

- 六餐制：早餐、早点心、午餐、午点心、晚餐、晚点心
- 体质匹配：根据产妇体质推荐菜品，标记禁忌
- 过敏预警：菜品含过敏原时自动告警
- 换餐：入住客户可在规定时间前申请换餐
- 评价统计：菜品好评率影响后续推荐

### 5.3 关键 Service 方法

```php
// MealPlanService
generateDailyPlan(date, templateId)    // 生成日排餐
batchGenerate(startDate, endDate, templateId) // 批量生成
customizePlan(planId, customerId, items)  // 个性化调整

// MealDeliveryService
createDeliveryTasks(date)              // 生成送餐任务
confirmDelivery(deliveryId)            // 确认送达
recordFeedback(deliveryId, data)       // 记录反馈
```

---

## 六、5.5 服务与产康

### 6.1 业务流程

```
服务项目配置（产后瑜伽/盆底修复/催乳/满月汗蒸...）
  ↓
套餐组合（单项/套餐/卡次）
  ↓
客户预约 → 技师排班匹配
  ↓
服务执行 → 服务记录
  ↓
客户评价
```

### 6.2 核心业务规则

- 服务分类：产康项目 / 母婴护理 / 增值服务
- 计费模式：单次 / 套餐 / 次卡 / 月卡
- 排班冲突：同一技师同时段不可安排两个服务
- 服务时长：每个项目有标准时长，影响排班
- 次卡消费：每次服务自动扣减次数

---

## 七、5.6 月嫂管理

### 7.1 业务流程

```
月嫂入驻 → 建档（证书/经验/等级/日薪）
  ↓
客户选嫂（列表展示/筛选）
  ↓
下单 → 会所审核 → 确认指派
  ↓
月嫂上户 → 服务期间
  ↓
服务结束 → 客户评价 → 更新档案评分
```

### 7.2 月嫂等级

| 等级 | 条件 | 日薪参考 |
|------|------|----------|
| 初级 | 持证 + <1年经验 | 300-500 |
| 中级 | 持证 + 1-3年 | 500-800 |
| 高级 | 持证 + 3-5年 + 好评率>90% | 800-1200 |
| 金牌 | 持证 + >5年 + 好评率>95% | 1200+ |

### 7.3 核心业务规则

- 月嫂状态：待岗 / 服务中 / 休息 / 离职
- 排班冲突：同一月嫂同时段只能服务一个客户
- 会所抽佣：订单金额 × 佣金比例
- 评价影响：综合评分影响等级和排序

---

## 八、5.7 进销存

### 8.1 业务流程

```
物资分类维护 → 供应商管理
  ↓
采购申请 → 审批 → 采购执行
  ↓
到货验收 → 入库
  ↓
领用申请 → 出库
  ↓
定期盘点 → 差异处理
  ↓
库存预警 → 自动触发采购
```

### 8.2 核心业务规则

- 库存预警：低于安全库存自动提醒
- 先进先出：按批次管理，临期品优先出库
- 采购审批：金额 > N 元需主管审批
- 出库关联：与护理/月子餐模块联动（如消耗护理用品）
- 盘点：支持全盘、抽盘，生成盘盈亏报表

---

## 九、5.8 财务管理

### 9.1 业务流程

```
收入类：签约收款 / 服务消费 / 充值 / 月嫂佣金
  ↓
支出类：采购付款 / 工资 / 运营费用
  ↓
记账 → 审核 → 入账
  ↓
日/月结算 → 报表
  ↓
发票管理
```

### 9.2 客户账户体系

```
客户账户
├── 现金余额（充值/退款）
├── 储值卡余额（卡种 × N）
├── 积分
└── 消费明细流水
```

### 9.3 核心业务规则

- 收支分类：预设分类树（一级→二级→三级）
- 审核流程：金额 > N 元需财务主管审核
- 客户充值：支持微信支付 / 线下转账
- 储值卡：预设面额、折扣率、有效期
- 退款：原路退回 / 退回余额，需审批
- 发票：电子发票 / 纸质发票，关联订单

---

## 十、5.9 人事薪资

### 10.1 业务流程

```
员工入职 → 建档 → 分配角色/部门
  ↓
排班管理（固定班/轮班）
  ↓
每日考勤（打卡/补卡/请假）
  ↓
月度汇总 → 工资计算
  ↓
工资确认 → 发放
```

### 10.2 工资计算公式

```
实发 = 基本工资 + 岗位工资 + 绩效
     + 加班费 + 补贴
     - 社保 - 公积金 - 个税
     - 缺勤扣款 - 其他扣款
```

### 10.3 核心业务规则

- 排班类型：早班/中班/晚班/夜班，支持跨天
- 考勤规则：迟到(≤30min) / 早退 / 旷工 / 加班
- 请假类型：年假/事假/病假/调休/产假/婚假
- 加班费：工作日1.5倍 / 周末2倍 / 节假日3倍
- 绩效：月度考核分数 × 绩效基数

---

## 十一、5.10 办公协同

### 11.1 审批引擎

```
审批模板定义（表单字段 + 流程节点）
  ↓
发起审批（填写表单）
  ↓
按流程流转（串行/并行/条件分支）
  ↓
审批人 通过/驳回
  ↓
结果通知 + 归档
```

### 11.2 审批流程类型

| 流程 | 触发 | 审批链 |
|------|------|--------|
| 请假申请 | 人事模块 | 主管→人事 |
| 采购申请 | 进销存模块 | 部门主管→财务 |
| 合同审批 | CRM模块 | 销售主管→总经理 |
| 退款申请 | 财务模块 | 客服→财务→总经理 |
| 换房申请 | 房务模块 | 客服→房务主管 |

### 11.3 核心功能

- 公告管理：发布、置顶、已读统计
- 交接班：上一班记录 → 下一班确认，确保信息连续
- 消息通知：站内消息 + 微信模板消息推送
- 待办汇总：首页展示所有待处理事项

---

## 十二、5.11 统计报表

### 12.1 预设报表

| 报表 | 维度 | 指标 |
|------|------|------|
| 经营概览 | 门店/日期 | 营收、入住率、客户数、满意度 |
| 营收分析 | 门店/月/类别 | 签约额、实收额、退款额、应收 |
| 入住统计 | 门店/月/房型 | 入住率、平均入住天数、房型分布 |
| CRM转化 | 来源/月/员工 | 线索数、转化率、签约率 |
| 护理质量 | 门店/月 | 异常率、满意度、任务完成率 |
| 餐品评价 | 菜品/月 | 好评率、投诉率 |
| 库存报表 | 仓库/月 | 采购额、消耗额、盘亏率 |
| 人力成本 | 部门/月 | 人工成本、人效比 |

### 12.2 核心功能

- 数据钻取：点击指标可下钻到明细
- 对比分析：同环比、多门店对比
- 导出功能：Excel / PDF
- 自定义报表：拖拽选择维度和指标
- 数据权限：按门店/部门过滤

---

## 十三、5.12 知识库

### 13.1 功能设计

- 分类管理：树形分类（如：产妇护理/新生儿护理/营养学/政策法规）
- 文章管理：富文本编辑器，支持图片/视频/附件
- 发布流程：草稿→审核→发布
- 全文检索：标题+内容全文搜索
- 权限控制：内部文章（员工可见）/ 公开文章（小程序可见）
- 阅读统计：浏览量、点赞量、收藏量
- 版本管理：文章修改历史

---

## 十四、5.13 系统设置

### 14.1 功能清单

| 功能 | 说明 |
|------|------|
| 门店管理 | 新建/编辑/启停门店 |
| 组织架构 | 区域 → 门店 → 部门 → 职务 |
| 用户管理 | 员工账号创建、角色分配 |
| 角色管理 | 角色定义、权限分配 |
| 菜单管理 | 动态菜单配置 |
| 字典管理 | 通用数据字典（下拉选项等） |
| 系统参数 | 全局配置项（如回收天数、审批金额阈值） |
| 操作日志 | 全局操作审计 |

### 14.2 多门店体系

```
总部（超级管理员）
├── 区域A
│   ├── 门店1（独立数据）
│   └── 门店2（独立数据）
└── 区域B
    └── 门店3（独立数据）
```

- 总部可查看所有门店数据
- 门店只能看到本店数据
- 部分配置（如字典、模板）可总部统一下发

---

## 十五、跨模块联动

| 触发 | 联动模块 | 动作 |
|------|----------|------|
| CRM签约 | 房务 | 自动创建预定 |
| 房务入住 | 护理 | 自动建立护理档案 |
| 房务入住 | 月子餐 | 自动生成排餐任务 |
| 护理异常(紧急) | 办公协同 | 推送通知 |
| 服务消费 | 财务 | 自动生成收支记录 |
| 月嫂订单 | 财务 | 佣金记录 |
| 采购入库 | 财务 | 付款记录 |
| 请假审批通过 | 人事 | 更新考勤 |
| 各模块 | 统计报表 | 数据采集 |

### 联动实现方式

使用 Laravel Event/Listener 解耦：

```php
// 事件定义
ContractSigned::class        → CreateReservationListener
CheckedIn::class             → CreateCareProfileListener
                             → GenerateMealPlanListener
CareAlertCreated::class      → NotifyStaffListener
ServiceCompleted::class      → CreateFinanceRecordListener
PurchaseReceived::class      → CreateFinanceRecordListener
LeaveApproved::class         → UpdateAttendanceListener
```

---

## 十六、通用功能

### 16.1 导入导出

- 导入：Excel 上传 → 校验 → 预览 → 确认导入
- 导出：异步队列生成 → 下载链接（大数据量）
- 模板下载：每个可导入功能提供 Excel 模板

### 16.2 操作日志

```php
// 自动记录
[时间] [用户] [模块] [操作] [对象] [变更内容]
// 示例
2024-03-15 10:30 张护士 护理模块 新建 护理记录#1001 { ... }
```

### 16.3 消息通知

| 渠道 | 场景 |
|------|------|
| 站内消息 | 审批、任务提醒、异常告警 |
| 微信模板消息 | 客户：入住通知、餐单推送、服务提醒 |
| 短信 | 重要通知备选渠道 |