fengshao1227/yuezi-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 第一阶段基础框架搭建

Browse Source 
后端 (Laravel 10 + Sanctum):
- RBAC 四层权限系统 (users→roles→permissions→menus)
- 门店隔离中间件 (BelongsToStore Trait + StoreIsolation Middleware)
- 操作日志中间件 (自动记录写操作)
- 权限检查中间件 (CheckPermission)
- 16张数据库表迁移 (系统基础+RBAC+字典+配置)
- 11个 Eloquent Model
- Auth API (登录/登出/用户信息)
- 系统设置模块 CRUD (门店/部门/职务/用户/角色/菜单/权限/字典/日志)
- 45条 RESTful API 路由
- InitSeeder 初始数据 (超管/角色/76权限/31菜单)

前端 (Vue 3 + Element Plus + Vite):
- Axios 请求封装 + Token 注入
- Pinia 状态管理 (user + permission store)
- 动态路由 (服务端菜单→前端路由自动生成)
- 后台布局 (侧边栏+顶栏+主内容区)
- 登录页 + 仪表盘首页
- 系统设置 7 个 CRUD 页面

技术方案文档 (7卷):
- 技术总览/数据库设计/API规范/RBAC设计/模块详设/小程序设计/部署方案
This commit is contained in:
li
2026-03-13 19:52:09 +08:00
commit 11c177a432
144 changed files with 25209 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-technical-overview.md
+199
View File
@@ -0,0 +1,199 @@
# 宫中有喜 — 技术方案总览
## 一、项目概述
| 项 | 值 |
|---|---|
| 项目名称 | 宫中有喜月子会所综合管理系统 |
| 系统类型 | 多门店 SaaS 管理平台 + 客户端小程序 |
| 后端 | PHP 8.1+ / Laravel 10 |
| 数据库 | MySQL 8.0 |
| 前端（后台） | Vue 3 + Element Plus（SPA，自适应） |
| 前端（客户端） | 微信小程序（uni-app，可复用 Vue 组件） |
| API 风格 | RESTful JSON，统一前缀 `/api/v1/` |
| 部署 | Nginx + PHP-FPM / Docker Compose |
## 二、框架选型理由
### 后端：Laravel 10
- **Eloquent ORM**：模型关联、软删除、Scope 过滤（门店隔离天然支持）
- **中间件体系**：RBAC 权限、门店隔离、操作日志 一站式拦截
- **队列 & 事件**：短信、推送、异步报表 开箱即用
- **Sanctum**：后台 SPA token + 小程序 API token 双模认证
- **Migration & Seeder**：数据库版本控制，多人协作无冲突
- **生态成熟**：社区、文档、第三方包（Excel 导出、PDF、微信SDK）齐全
### 前端：Vue 3 + Element Plus
- 与 Laravel 前后分离配合成熟
- Element Plus 提供完整后台组件（表格、表单、日历、审批流）
- 响应式布局满足 Web + Mobile 自适应需求
### 客户端：uni-app
- 一套代码编译微信小程序 + H5
- Vue 3 语法，与后台前端技术栈统一，降低学习成本
- 丰富的插件市场（微信支付、地图、视频播放等）
## 三、系统架构图
```
┌─────────────────────────────────────────────────┐
│ 客户端 │
│ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ 微信小程序 │ │ 后台管理 SPA (Vue3) │ │
│ │ (uni-app) │ │ Element Plus │ │
│ └──────┬───────┘ └───────────┬──────────────┘ │
└─────────┼──────────────────────┼────────────────┘
│ HTTPS │ HTTPS
▼ ▼
┌─────────────────────────────────────────────────┐
│ Nginx 反向代理 / 负载均衡 │
│ 静态资源 + API 路由 + WebSocket │
└─────────────────────┬───────────────────────────┘
│
┌─────────────────────▼───────────────────────────┐
│ Laravel 10 API 层 │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │
│ │ 认证 │ │ RBAC │ │ 门店 │ │ 操作日志 │ │
│ │中间件 │ │中间件 │ │隔离 │ │中间件 │ │
│ └───┬────┘ └───┬────┘ └───┬────┘ └────┬─────┘ │
│ └──────────┴──────────┴────────────┘ │
│ ┌──────────────────────────────────────────┐ │
│ │ Controller 层 (13模块) │ │
│ │ CRM | 房务 | 护理 | 月子餐 | 产康 │ │
│ │ 月嫂 | 进销存 | 财务 | 人事 | 协同 │ │
│ │ 报表 | 知识库 | 系统设置 │ │
│ └──────────────────┬───────────────────────┘ │
│ ┌──────────────────▼───────────────────────┐ │
│ │ Service 层 (业务逻辑) │ │
│ └──────────────────┬───────────────────────┘ │
│ ┌──────────────────▼───────────────────────┐ │
│ │ Model 层 (Eloquent ORM) │ │
│ └──────────────────┬───────────────────────┘ │
└─────────────────────┼───────────────────────────┘
│
┌─────────────────────▼───────────────────────────┐
│ 数据层 │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ MySQL 8 │ │ Redis │ │ 文件存储 │ │
│ │ 主业务库 │ │ 缓存/队列│ │ (本地/OSS) │ │
│ └──────────┘ └──────────┘ └───────────────┘ │
└─────────────────────────────────────────────────┘
```
## 四、项目目录结构
```
saas/
├── backend/ # Laravel 后端
│ ├── app/
│ │ ├── Http/
│ │ │ ├── Controllers/
│ │ │ │ ├── Admin/ # 后台管理接口
│ │ │ │ │ ├── Crm/ # 5.1 CRM模块
│ │ │ │ │ ├── Room/ # 5.2 房务模块
│ │ │ │ │ ├── Care/ # 5.3 护理模块
│ │ │ │ │ ├── Meal/ # 5.4 月子餐模块
│ │ │ │ │ ├── Service/# 5.5 服务产康
│ │ │ │ │ ├── Nanny/ # 5.6 月嫂模块
│ │ │ │ │ ├── Stock/ # 5.7 进销存
│ │ │ │ │ ├── Finance/# 5.8 财务模块
│ │ │ │ │ ├── Hr/ # 5.9 人事薪资
│ │ │ │ │ ├── Office/ # 5.10 办公协同
│ │ │ │ │ ├── Report/ # 5.11 统计报表
│ │ │ │ │ ├── Kb/ # 5.12 知识库
│ │ │ │ │ └── System/ # 5.13 系统设置
│ │ │ │ └── Client/ # 微客宝客户端接口
│ │ │ ├── Middleware/
│ │ │ │ ├── StoreIsolation.php
│ │ │ │ ├── CheckPermission.php
│ │ │ │ └── OperationLog.php
│ │ │ └── Requests/ # 表单验证
│ │ ├── Models/ # Eloquent 模型
│ │ ├── Services/ # 业务逻辑层
│ │ ├── Enums/ # 枚举常量
│ │ ├── Events/ # 事件
│ │ ├── Listeners/ # 监听器
│ │ ├── Jobs/ # 队列任务
│ │ └── Traits/ # 公用 Trait
│ ├── database/
│ │ ├── migrations/ # 数据库迁移
│ │ └── seeders/ # 种子数据
│ ├── routes/
│ │ ├── api.php # 后台 API 路由
│ │ └── client.php # 客户端 API 路由
│ └── config/
│
├── frontend/ # Vue 3 后台前端
│ ├── src/
│ │ ├── views/ # 页面（按模块分目录）
│ │ ├── components/ # 公共组件
│ │ ├── api/ # 接口封装
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── router/ # 路由（动态菜单）
│ │ ├── utils/ # 工具函数
│ │ └── assets/ # 静态资源
│ └── vite.config.js
│
├── miniapp/ # uni-app 微信小程序
│ ├── pages/ # 页面
│ ├── components/ # 组件
│ ├── api/ # 接口
│ ├── stores/ # 状态
│ └── static/ # 静态资源
│
├── docs/ # 技术文档
│ ├── 01-technical-overview.md
│ ├── 02-database-design.md
│ ├── 03-api-specification.md
│ ├── 04-rbac-design.md
│ ├── 05-module-details.md
│ ├── 06-miniapp-design.md
│ └── 07-deployment.md
│
├── docker-compose.yml
└── README.md
```
## 五、开发阶段规划
### 第一阶段：基础框架（2周）
- Laravel 项目搭建 + 数据库迁移框架
- RBAC 权限系统（用户、角色、权限、菜单）
- 门店隔离中间件
- 操作日志中间件
- 审批流引擎基础
- Vue 3 后台框架 + 动态路由 + 登录认证
- 系统设置模块（门店、部门、角色、用户）
### 第二阶段：核心业务（4周）
- CRM 模块（线索、客户、签约、问卷）
- 房务模块（房态、预定、入离住）
- 护理模块（档案、计划、记录、异常、指标）
- 月子餐模块（排餐、送餐、评价）
### 第三阶段：增值 & 供应链（3周）
- 服务与产康模块
- 月嫂模块
- 进销存模块
### 第四阶段：财务 & 人事（2周）
- 财务模块
- 人事薪资模块
### 第五阶段：协同 & 报表（2周）
- 办公协同模块
- 统计报表模块
- 知识库模块
### 第六阶段：微客宝小程序（3周）
- uni-app 项目搭建
- 首页（商城、点餐、学堂、月嫂、活动）
- 共伴成长（护理记录、数据图表）
- 个人中心（账户、订单、服务、评价）
### 第七阶段：联调 & 部署（2周）
- 前后端联调
- 微信支付对接
- 性能优化
- Docker 部署
- 上线验收
docs/02-database-design.md
+1284
View File
File diff suppressed because it is too large Load Diff
docs/03-api-specification.md
+792
View File
@@ -0,0 +1,792 @@
# 宫中有喜 — API 接口规范
## 一、全局约定
### 1.1 基础信息
| 项 | 值 |
|---|---|
| Base URL | `https://{domain}/api/v1/` |
| 客户端 Base URL | `https://{domain}/api/v1/client/` |
| Content-Type | `application/json` |
| 认证方式 | Bearer Token（Sanctum） |
| 时区 | Asia/Shanghai |
| 编码 | UTF-8 |
### 1.2 认证
```
# 后台登录
POST /api/v1/auth/login
Body: { "username": "admin", "password": "xxx" }
Response: { "code": 0, "data": { "token": "xxx", "user": {...} } }
# 小程序登录
POST /api/v1/client/auth/wechat-login
Body: { "code": "wx_code", "encrypted_data": "...", "iv": "..." }
# 退出
POST /api/v1/auth/logout
Header: Authorization: Bearer {token}
# 刷新用户信息
GET /api/v1/auth/me
```
### 1.3 统一响应格式
```json
// 成功
{
"code": 0,
"message": "success",
"data": { ... }
}
// 分页
{
"code": 0,
"data": {
"list": [...],
"total": 100,
"page": 1,
"page_size": 20
}
}
// 失败
{
"code": 40001,
"message": "参数校验失败",
"errors": {
"phone": ["手机号格式不正确"]
}
}
```
### 1.4 错误码规范
| 范围 | 含义 |
|------|------|
| 0 | 成功 |
| 40001–40099 | 参数校验错误 |
| 40100–40199 | 认证错误（token 无效/过期） |
| 40300–40399 | 权限不足 |
| 40400–40499 | 资源不存在 |
| 42200–42299 | 业务逻辑冲突 |
| 50000–50099 | 服务器内部错误 |
### 1.5 分页与筛选
```
GET /api/v1/xxx?page=1&page_size=20&keyword=张&status=1&sort_by=created_at&sort_order=desc
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | int | 页码，默认 1 |
| page_size | int | 每页数量，默认 20，最大 100 |
| keyword | string | 模糊搜索 |
| sort_by | string | 排序字段 |
| sort_order | string | asc / desc |
| store_id | int | 门店过滤（超级管理员可用） |
| start_date / end_date | string | 日期范围 YYYY-MM-DD |
### 1.6 通用 Header
| Header | 说明 |
|--------|------|
| Authorization | `Bearer {token}` |
| X-Store-Id | 当前门店 ID（切换门店时） |
| Accept-Language | zh-CN |
---
## 二、后台管理 API（Admin）
### 2.1 系统设置模块 `/system/`
```
# 门店管理
GET /system/stores # 门店列表
POST /system/stores # 新建门店
GET /system/stores/{id} # 门店详情
PUT /system/stores/{id} # 编辑门店
DELETE /system/stores/{id} # 删除门店
# 部门管理
GET /system/departments # 部门树
POST /system/departments # 新建部门
PUT /system/departments/{id} # 编辑部门
DELETE /system/departments/{id} # 删除部门
# 职务管理
GET /system/positions # 职务列表
POST /system/positions # 新建职务
PUT /system/positions/{id} # 编辑
DELETE /system/positions/{id} # 删除
# 用户管理
GET /system/users # 用户列表（支持部门筛选）
POST /system/users # 新建用户
GET /system/users/{id} # 用户详情
PUT /system/users/{id} # 编辑用户
PUT /system/users/{id}/status # 启用/禁用
PUT /system/users/{id}/password # 重置密码
DELETE /system/users/{id} # 删除用户
# 角色管理
GET /system/roles # 角色列表
POST /system/roles # 新建角色
GET /system/roles/{id} # 角色详情（含权限树）
PUT /system/roles/{id} # 编辑角色
DELETE /system/roles/{id} # 删除角色
PUT /system/roles/{id}/permissions # 分配权限
# 菜单管理
GET /system/menus # 菜单树
POST /system/menus # 新建菜单
PUT /system/menus/{id} # 编辑菜单
DELETE /system/menus/{id} # 删除菜单
# 权限管理
GET /system/permissions # 权限列表
POST /system/permissions # 新建权限
# 操作日志
GET /system/operation-logs # 操作日志列表
# 数据字典
GET /system/dictionaries # 字典类型列表
POST /system/dictionaries # 新建字典类型
GET /system/dictionaries/{id}/items # 字典项列表
POST /system/dictionaries/{id}/items # 新建字典项
# 系统配置
GET /system/configs # 获取系统配置
PUT /system/configs # 更新系统配置
```
### 2.2 CRM 模块 `/crm/`
```
# 线索管理
GET /crm/leads # 线索列表
POST /crm/leads # 新建线索
GET /crm/leads/{id} # 线索详情
PUT /crm/leads/{id} # 编辑线索
POST /crm/leads/{id}/assign # 分配线索
POST /crm/leads/{id}/convert # 线索转客户
POST /crm/leads/import # 批量导入
GET /crm/leads/export # 导出 Excel
# 跟进记录
GET /crm/leads/{id}/follow-ups # 跟进记录列表
POST /crm/leads/{id}/follow-ups # 新建跟进记录
# 客户管理
GET /crm/customers # 客户列表
POST /crm/customers # 新建客户
GET /crm/customers/{id} # 客户详情（含跟进、合同）
PUT /crm/customers/{id} # 编辑客户
DELETE /crm/customers/{id} # 删除客户
# 合同/签约
GET /crm/contracts # 合同列表
POST /crm/contracts # 新建合同
GET /crm/contracts/{id} # 合同详情
PUT /crm/contracts/{id} # 编辑合同
POST /crm/contracts/{id}/approve # 审批合同
GET /crm/contracts/{id}/pdf # 导出合同 PDF
# 满意度问卷
GET /crm/surveys # 问卷模板列表
POST /crm/surveys # 新建问卷
GET /crm/surveys/{id}/results # 问卷结果
# CRM 仪表盘
GET /crm/dashboard # CRM 统计数据
```
### 2.3 房务模块 `/room/`
```
# 楼层/房型
GET /room/floors # 楼层列表
POST /room/floors # 新建楼层
GET /room/room-types # 房型列表
POST /room/room-types # 新建房型
# 房间管理
GET /room/rooms # 房间列表（含状态）
POST /room/rooms # 新建房间
PUT /room/rooms/{id} # 编辑房间
GET /room/rooms/board # 房态看板（日历视图数据）
# 预定管理
GET /room/reservations # 预定列表
POST /room/reservations # 新建预定
PUT /room/reservations/{id} # 编辑预定
POST /room/reservations/{id}/cancel # 取消预定
POST /room/reservations/{id}/checkin # 办理入住
# 入住管理
GET /room/check-ins # 在住列表
GET /room/check-ins/{id} # 入住详情
POST /room/check-ins/{id}/extend # 延住
POST /room/check-ins/{id}/change-room # 换房
POST /room/check-ins/{id}/checkout # 办理离店
# 房间日志
GET /room/rooms/{id}/logs # 房间操作日志
```
### 2.4 护理模块 `/care/`
```
# 护理档案
GET /care/profiles # 档案列表
POST /care/profiles # 新建档案
GET /care/profiles/{id} # 档案详情
PUT /care/profiles/{id} # 编辑档案
# 护理计划
GET /care/plans # 计划列表
POST /care/plans # 新建计划（含模板）
GET /care/plans/{id} # 计划详情
PUT /care/plans/{id} # 编辑计划
POST /care/plans/{id}/activate # 激活计划
# 护理记录
GET /care/records # 记录列表
POST /care/records # 新建记录
GET /care/records/{id} # 记录详情
# 异常登记
POST /care/alerts # 新建异常
GET /care/alerts # 异常列表
PUT /care/alerts/{id}/resolve # 处理异常
# 健康指标
GET /care/health-metrics # 指标记录列表
POST /care/health-metrics # 录入指标
GET /care/health-metrics/chart # 指标趋势图数据
# 护理模板
GET /care/templates # 护理模板列表
POST /care/templates # 新建模板
```
### 2.5 月子餐模块 `/meal/`
```
# 菜品管理
GET /meal/dishes # 菜品列表
POST /meal/dishes # 新建菜品
PUT /meal/dishes/{id} # 编辑菜品
DELETE /meal/dishes/{id} # 删除菜品
# 餐单模板
GET /meal/templates # 餐单模板列表
POST /meal/templates # 新建餐单模板
GET /meal/templates/{id} # 模板详情
# 每日排餐
GET /meal/daily-plans # 每日排餐列表
POST /meal/daily-plans # 新建/复制排餐
PUT /meal/daily-plans/{id} # 编辑排餐
POST /meal/daily-plans/batch-generate # 批量生成排餐
# 送餐记录
GET /meal/deliveries # 送餐记录列表
POST /meal/deliveries/{id}/confirm # 确认送达
POST /meal/deliveries/{id}/feedback # 餐品反馈
# 餐品评价
GET /meal/reviews # 评价列表
GET /meal/reviews/stats # 评价统计
```
### 2.6 服务与产康模块 `/service/`
```
# 服务项目
GET /service/items # 服务项目列表
POST /service/items # 新建项目
PUT /service/items/{id} # 编辑项目
# 服务套餐
GET /service/packages # 套餐列表
POST /service/packages # 新建套餐
PUT /service/packages/{id} # 编辑套餐
# 服务预约/订单
GET /service/orders # 订单列表
POST /service/orders # 新建预约
PUT /service/orders/{id} # 编辑
POST /service/orders/{id}/confirm # 确认
POST /service/orders/{id}/complete # 完成
POST /service/orders/{id}/cancel # 取消
# 技师排班
GET /service/therapist-schedules # 排班列表
POST /service/therapist-schedules # 新建排班
GET /service/therapist-schedules/board # 排班看板
```
### 2.7 月嫂模块 `/nanny/`
```
# 月嫂档案
GET /nanny/nannies # 月嫂列表
POST /nanny/nannies # 新建月嫂
GET /nanny/nannies/{id} # 月嫂详情
PUT /nanny/nannies/{id} # 编辑月嫂
PUT /nanny/nannies/{id}/status # 更新状态
# 月嫂订单
GET /nanny/orders # 订单列表
POST /nanny/orders # 新建订单
GET /nanny/orders/{id} # 订单详情
POST /nanny/orders/{id}/assign # 指派月嫂
POST /nanny/orders/{id}/complete # 完成
# 月嫂评价
GET /nanny/reviews # 评价列表
POST /nanny/reviews # 新建评价
GET /nanny/nannies/{id}/reviews # 某月嫂评价
# 月嫂排班
GET /nanny/schedules # 排班列表
POST /nanny/schedules # 新建排班
```
### 2.8 进销存模块 `/stock/`
```
# 仓库管理
GET /stock/warehouses # 仓库列表
POST /stock/warehouses # 新建仓库
# 物资管理
GET /stock/materials # 物资列表
POST /stock/materials # 新建物资
PUT /stock/materials/{id} # 编辑物资
GET /stock/materials/categories # 物资分类
# 库存查询
GET /stock/inventories # 库存列表
GET /stock/inventories/alerts # 库存预警
# 采购订单
GET /stock/purchase-orders # 采购单列表
POST /stock/purchase-orders # 新建采购单
GET /stock/purchase-orders/{id} # 详情
POST /stock/purchase-orders/{id}/approve # 审批
POST /stock/purchase-orders/{id}/receive # 入库
# 出入库
POST /stock/in-records # 入库记录
POST /stock/out-records # 出库记录
GET /stock/records # 出入库流水
# 供应商
GET /stock/suppliers # 供应商列表
POST /stock/suppliers # 新建供应商
PUT /stock/suppliers/{id} # 编辑
```
### 2.9 财务模块 `/finance/`
```
# 资金账户
GET /finance/accounts # 账户列表
POST /finance/accounts # 新建账户
PUT /finance/accounts/{id} # 编辑
# 收支记录
GET /finance/records # 收支流水
POST /finance/records # 新建收支
GET /finance/records/{id} # 详情
POST /finance/records/{id}/approve # 审核
# 客户账户
GET /finance/customer-accounts # 客户账户列表
GET /finance/customer-accounts/{id} # 客户账户详情
POST /finance/customer-accounts/{id}/recharge # 充值
POST /finance/customer-accounts/{id}/consume # 消费
GET /finance/customer-accounts/{id}/bills # 账单流水
# 储值卡/优惠券
GET /finance/voucher-cards # 储值卡列表
POST /finance/voucher-cards # 发行储值卡
# 发票管理
GET /finance/invoices # 发票列表
POST /finance/invoices # 开票申请
POST /finance/invoices/{id}/confirm # 确认开票
# 财务报表
GET /finance/reports/daily # 日报
GET /finance/reports/monthly # 月报
GET /finance/reports/category # 分类汇总
```
### 2.10 人事薪资模块 `/hr/`
```
# 员工档案
GET /hr/employees # 员工列表
POST /hr/employees # 新建员工
GET /hr/employees/{id} # 员工详情
PUT /hr/employees/{id} # 编辑
# 排班管理
GET /hr/schedules # 排班列表
POST /hr/schedules # 新建排班
POST /hr/schedules/batch # 批量排班
GET /hr/schedules/board # 排班日历
# 考勤
GET /hr/attendances # 考勤列表
POST /hr/attendances/clock # 打卡
GET /hr/attendances/monthly # 月度汇总
# 薪资
GET /hr/salaries # 工资单列表
POST /hr/salaries/calculate # 计算工资
POST /hr/salaries/{id}/confirm # 确认工资单
GET /hr/salaries/export # 导出工资单
# 请假/加班
GET /hr/leaves # 请假列表
POST /hr/leaves # 申请请假
POST /hr/leaves/{id}/approve # 审批
```
### 2.11 办公协同模块 `/office/`
```
# 公告
GET /office/announcements # 公告列表
POST /office/announcements # 发布公告
GET /office/announcements/{id} # 公告详情
# 审批流
GET /office/approvals # 审批列表（我的待办/已办）
POST /office/approvals # 发起审批
GET /office/approvals/{id} # 审批详情
POST /office/approvals/{id}/approve # 通过
POST /office/approvals/{id}/reject # 驳回
# 审批模板
GET /office/approval-templates # 模板列表
POST /office/approval-templates # 新建模板
# 交接班
GET /office/handovers # 交接班列表
POST /office/handovers # 新建交接
POST /office/handovers/{id}/confirm # 确认交接
# 消息/通知
GET /office/notifications # 通知列表
PUT /office/notifications/{id}/read # 标记已读
PUT /office/notifications/read-all # 全部已读
GET /office/notifications/unread-count # 未读数量
```
### 2.12 统计报表模块 `/report/`
```
# 经营概览
GET /report/overview # 经营总览仪表盘
# 营收报表
GET /report/revenue # 营收统计
GET /report/revenue/trend # 营收趋势
# 入住报表
GET /report/occupancy # 入住率统计
GET /report/occupancy/trend # 入住率趋势
# CRM 报表
GET /report/crm/conversion # 转化率统计
GET /report/crm/source # 来源分析
GET /report/crm/staff # 员工业绩
# 护理报表
GET /report/care/workload # 护理工作量
GET /report/care/quality # 护理质量
# 满意度报表
GET /report/satisfaction # 满意度统计
# 自定义报表
GET /report/custom # 自定义报表列表
POST /report/custom # 创建自定义报表
GET /report/custom/{id}/data # 获取报表数据
GET /report/custom/{id}/export # 导出报表
```
### 2.13 知识库模块 `/kb/`
```
# 分类
GET /kb/categories # 分类树
POST /kb/categories # 新建分类
PUT /kb/categories/{id} # 编辑分类
# 文章
GET /kb/articles # 文章列表
POST /kb/articles # 新建文章
GET /kb/articles/{id} # 文章详情
PUT /kb/articles/{id} # 编辑文章
DELETE /kb/articles/{id} # 删除文章
POST /kb/articles/{id}/publish # 发布
GET /kb/articles/search # 全文搜索
```
---
## 三、客户端 API（Client / 微客宝小程序）
### 3.1 认证
```
POST /client/auth/wechat-login # 微信登录
POST /client/auth/bindPhone # 绑定手机号
GET /client/auth/profile # 获取个人信息
PUT /client/auth/profile # 更新个人信息
```
### 3.2 首页
```
GET /client/home/banners # 轮播图
GET /client/home/notices # 公告
GET /client/home/services # 服务推荐
GET /client/home/activities # 活动列表
```
### 3.3 商城/服务
```
GET /client/services # 服务列表
GET /client/services/{id} # 服务详情
GET /client/packages # 套餐列表
GET /client/packages/{id} # 套餐详情
POST /client/orders # 下单
GET /client/orders # 我的订单
GET /client/orders/{id} # 订单详情
POST /client/orders/{id}/pay # 支付
POST /client/orders/{id}/cancel # 取消
```
### 3.4 月子餐
```
GET /client/meals/today # 今日餐单
GET /client/meals/week # 本周餐单
POST /client/meals/feedback # 餐品反馈
GET /client/meals/dishes # 可选菜品
POST /client/meals/custom-order # 自选点餐
```
### 3.5 共伴成长
```
GET /client/baby/care-records # 宝宝护理记录
GET /client/baby/health-chart # 健康数据图表
GET /client/baby/milestones # 成长里程碑
GET /client/mom/care-records # 妈妈护理记录
GET /client/mom/health-chart # 妈妈健康图表
```
### 3.6 月嫂
```
GET /client/nannies # 月嫂列表
GET /client/nannies/{id} # 月嫂详情
POST /client/nanny-orders # 预约月嫂
GET /client/nanny-orders # 我的月嫂订单
POST /client/nanny-reviews # 评价月嫂
```
### 3.7 学堂
```
GET /client/articles # 知识文章列表
GET /client/articles/{id} # 文章详情
GET /client/articles/categories # 分类
POST /client/articles/{id}/like # 点赞
POST /client/articles/{id}/collect # 收藏
```
### 3.8 社区
```
GET /client/community/posts # 帖子列表
POST /client/community/posts # 发帖
GET /client/community/posts/{id} # 帖子详情
POST /client/community/posts/{id}/comment # 评论
POST /client/community/posts/{id}/like # 点赞
```
### 3.9 个人中心
```
GET /client/my/account # 账户余额/储值卡
GET /client/my/coupons # 优惠券列表
GET /client/my/orders # 全部订单
GET /client/my/reviews # 我的评价
GET /client/my/collections # 我的收藏
GET /client/my/messages # 消息通知
```
### 3.10 支付
```
POST /client/pay/wechat # 微信支付下单
POST /client/pay/callback # 支付回调（后端内部）
GET /client/pay/status/{order_no} # 查询支付状态
```
---
## 四、文件上传
```
# 通用文件上传
POST /api/v1/upload/image # 上传图片（返回 URL）
POST /api/v1/upload/file # 上传文件（Excel/PDF）
POST /api/v1/upload/avatar # 上传头像（自动裁剪）
```
请求格式：`multipart/form-data`
| 参数 | 类型 | 说明 |
|------|------|------|
| file | File | 文件 |
| type | string | 业务类型（avatar/contract/care_record 等） |
---
## 五、WebSocket 事件（可选）
```
# 连接
ws://{domain}/ws?token={bearer_token}
# 事件
notification.new — 新通知推送
approval.pending — 待审批提醒
care.alert — 护理异常告警
room.status_change — 房态变更通知
```
---
## 六、接口安全
### 6.1 限流策略
| 接口类型 | 限制 |
|----------|------|
| 登录接口 | 5 次/分钟/IP |
| 普通接口 | 60 次/分钟/用户 |
| 上传接口 | 10 次/分钟/用户 |
| 导出接口 | 5 次/分钟/用户 |
| 支付回调 | 不限（白名单IP） |
### 6.2 数据权限
- 所有业务接口自动注入 `store_id` 过滤
- 超级管理员可通过 `X-Store-Id` Header 切换门店
- 敏感操作（删除、审批）记录操作日志
### 6.3 输入校验
- 所有写入接口使用 Laravel FormRequest 校验
- XSS 过滤：HTMLPurifier 处理富文本
- SQL 注入：Eloquent 参数绑定（禁止 raw SQL 拼接）
- 文件上传：类型白名单 + 大小限制（图片 5MB，文件 20MB）
---
## 七、典型接口示例
### 7.1 新建线索
```http
POST /api/v1/crm/leads
Authorization: Bearer xxx
Content-Type: application/json
{
"name": "张女士",
"phone": "13800138000",
"source": "wechat",
"expected_date": "2024-06-15",
"expected_room_type": 2,
"expected_days": 28,
"remark": "朋友推荐，预算10万左右"
}
```
Response:
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1001,
"name": "张女士",
"phone": "13800138000",
"source": "wechat",
"status": "new",
"assigned_to": null,
"created_at": "2024-03-15 10:30:00"
}
}
```
### 7.2 房态看板
```http
GET /api/v1/room/rooms/board?date=2024-03-15&range=week
Authorization: Bearer xxx
```
Response:
```json
{
"code": 0,
"data": {
"floors": [
{
"id": 1,
"name": "3楼",
"rooms": [
{
"id": 101,
"number": "301",
"type": "豪华套房",
"status": "occupied",
"customer": "李女士",
"check_in": "2024-03-10",
"check_out": "2024-04-07"
}
]
}
],
"summary": {
"total": 30,
"occupied": 22,
"available": 5,
"maintenance": 2,
"reserved": 1,
"occupancy_rate": "73.3%"
}
}
}
```
docs/04-rbac-design.md
+1392
View File
File diff suppressed because it is too large Load Diff
docs/05-module-details.md
+546
View File
@@ -0,0 +1,546 @@
# 宫中有喜 — 模块详细设计
## 一、模块总览
| 编号 | 模块 | 核心实体 | 关键流程 |
|------|------|----------|----------|
| 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 消息通知
| 渠道 | 场景 |
|------|------|
| 站内消息 | 审批、任务提醒、异常告警 |
| 微信模板消息 | 客户：入住通知、餐单推送、服务提醒 |
| 短信 | 重要通知备选渠道 |
docs/06-miniapp-design.md
+505
View File
@@ -0,0 +1,505 @@
# 宫中有喜 — 微客宝小程序设计
## 一、概述
| 项 | 值 |
|---|---|
| 产品名称 | 宫中有喜·微客宝 |
| 类型 | 微信小程序 |
| 框架 | uni-app (Vue 3) |
| 目标用户 | 在住/潜在客户（产妇及家属） |
| 核心功能 | 服务商城、月子餐、共伴成长、月嫂预约、学堂社区 |
## 二、页面架构
### 2.1 Tab 导航（底部 5 Tab）
```
┌──────────────────────────────────┐
│ 微客宝小程序 │
├────┬────┬────┬────┬────┤
│ 首页 │ 服务 │ 成长 │ 学堂 │ 我的 │
└────┴────┴────┴────┴────┘
```
### 2.2 完整页面树
```
pages/
├── index/ # Tab1: 首页
│ └── index.vue # 轮播 + 快捷入口 + 推荐 + 活动
│
├── service/ # Tab2: 服务
│ ├── index.vue # 服务分类列表
│ ├── detail.vue # 服务/套餐详情
│ ├── booking.vue # 预约下单
│ ├── nanny/
│ │ ├── list.vue # 月嫂列表
│ │ ├── detail.vue # 月嫂详情
│ │ └── order.vue # 月嫂预约
│ └── meal/
│ ├── today.vue # 今日餐单
│ ├── week.vue # 本周餐单
│ └── custom.vue # 自选点餐
│
├── growth/ # Tab3: 共伴成长
│ ├── index.vue # 成长首页（宝宝+妈妈）
│ ├── baby/
│ │ ├── records.vue # 宝宝护理记录
│ │ ├── chart.vue # 宝宝数据图表
│ │ └── milestone.vue # 成长里程碑
│ └── mom/
│ ├── records.vue # 妈妈护理记录
│ └── chart.vue # 妈妈健康图表
│
├── study/ # Tab4: 学堂
│ ├── index.vue # 文章列表
│ ├── detail.vue # 文章详情
│ └── community/
│ ├── index.vue # 社区帖子列表
│ ├── detail.vue # 帖子详情
│ └── post.vue # 发帖
│
├── mine/ # Tab5: 我的
│ ├── index.vue # 个人中心首页
│ ├── orders/
│ │ ├── list.vue # 我的订单
│ │ └── detail.vue # 订单详情
│ ├── account.vue # 账户余额/储值卡
│ ├── coupons.vue # 优惠券
│ ├── reviews.vue # 我的评价
│ ├── collections.vue # 我的收藏
│ ├── messages.vue # 消息通知
│ └── settings.vue # 设置
│
├── auth/ # 认证
│ ├── login.vue # 微信授权登录
│ └── bindPhone.vue # 绑定手机号
│
├── pay/ # 支付
│ ├── cashier.vue # 收银台
│ └── result.vue # 支付结果
│
└── common/ # 公共页面
├── webview.vue # 内嵌网页
└── preview.vue # 图片预览
```
---
## 三、核心页面设计
### 3.1 首页 (index)
```
┌────────────────────────────┐
│ [轮播图 Banner] │
├────────────────────────────┤
│ 📋公告栏（滚动） │
├────┬────┬────┬────┤
│ 商城 │ 点餐 │ 月嫂 │ 更多 │ ← 快捷入口
├────┴────┴────┴────┤
│ ⭐ 热门服务推荐 │
│ ┌─────┐ ┌─────┐ │
│ │ 项目1│ │ 项目2│ │
│ └─────┘ └─────┘ │
├────────────────────────────┤
│ 🎉 精彩活动 │
│ ┌──────────────────┐ │
│ │ 活动卡片 │ │
│ └──────────────────┘ │
├────────────────────────────┤
│ 📖 孕妈课堂（文章推荐） │
│ ┌──────────────────┐ │
│ │ 文章卡片 │ │
│ └──────────────────┘ │
└────────────────────────────┘
```
数据来源：
- 轮播图：`GET /client/home/banners`
- 公告：`GET /client/home/notices`
- 推荐服务：`GET /client/home/services`
- 活动：`GET /client/home/activities`
- 文章推荐：`GET /client/articles?recommend=1&limit=3`
### 3.2 共伴成长页
```
┌────────────────────────────┐
│ [宝宝头像] 小明 出生第15天 │
│ 体重: 3.5kg 身长: 50cm │
├────────────────────────────┤
│ Tab: [护理记录] [数据图表] [里程碑] │
├────────────────────────────┤
│ 今日护理记录 │
│ 09:00 喂奶 120ml ✓ │
│ 09:30 换尿布 ✓ │
│ 10:00 体温测量 36.8°C ✓ │
│ 11:00 洗澡 ✓ │
│ 12:00 喂奶 100ml ✓ │
│ ... │
├────────────────────────────┤
│ 切换至 [妈妈] 查看 │
└────────────────────────────┘
```
图表使用 uCharts 或 ECharts 小程序版，展示：
- 体重增长曲线
- 喂奶量趋势
- 睡眠时长统计
- 健康指标折线图
### 3.3 月子餐页
```
┌────────────────────────────┐
│ 📅 3月15日 周五 今日餐单 │
├────────────────────────────┤
│ 🌅 早餐 07:30 │
│ ┌────────────────────┐ │
│ │ [图] 红枣小米粥 │ │
│ │ [图] 蒸蛋 │ │
│ │ [图] 核桃酥 │ │
│ └────────────────────┘ │
│ [👍已送达] [💬反馈] │
├────────────────────────────┤
│ 🍵 早点心 10:00 │
│ ┌────────────────────┐ │
│ │ [图] 银耳莲子汤 │ │
│ └────────────────────┘ │
│ [⏳待送达] │
├────────────────────────────┤
│ 🌞 午餐 12:00 │
│ ┌────────────────────┐ │
│ │ [图] 黄花菜炖鸡 │ │
│ │ [图] 时令蔬菜 │ │
│ │ [图] 乌鸡汤 │ │
│ └────────────────────┘ │
│ [🔄申请换餐] │
├────────────────────────────┤
│ 🍵🌙🌙 午点/晚餐/晚点... │
├────────────────────────────┤
│ [查看本周餐单] [自选点餐] │
└────────────────────────────┘
```
---
## 四、组件设计
### 4.1 公共组件
```
components/
├── NavBar.vue # 自定义导航栏
├── TabBar.vue # 底部导航（自定义实现）
├── EmptyState.vue # 空状态占位
├── LoadMore.vue # 加载更多/到底了
├── PriceTag.vue # 价格显示（¥ 格式化）
├── StarRating.vue # 评分星级
├── CountDown.vue # 倒计时
├── ImageUploader.vue # 图片上传
├── DatePicker.vue # 日期选择
├── OrderCard.vue # 订单卡片
├── ServiceCard.vue # 服务项目卡片
├── ArticleCard.vue # 文章卡片
├── NannyCard.vue # 月嫂卡片
├── MealCard.vue # 菜品卡片
└── StatusTag.vue # 状态标签
```
### 4.2 业务组件
```
components/business/
├── PayButton.vue # 支付按钮（封装微信支付）
├── PhoneAuth.vue # 手机号授权组件
├── ShareCard.vue # 分享卡片生成
├── CouponSelector.vue # 优惠券选择
├── ServiceBooking.vue # 服务预约表单
└── ReviewForm.vue # 评价表单（星级+文字+图片）
```
---
## 五、状态管理 (Pinia)
```
stores/
├── user.js # 用户信息、Token、登录状态
├── cart.js # 购物车/预约车
├── order.js # 订单状态
└── app.js # 全局配置（门店信息、系统参数）
```
### 5.1 用户状态
```javascript
// stores/user.js
export const useUserStore = defineStore('user', {
state: () => ({
token: '',
userInfo: null, // 微信用户信息
customerInfo: null, // 客户业务信息
isLoggedIn: false,
storeId: null, // 所属门店
}),
actions: {
async wechatLogin(code) { ... },
async bindPhone(encryptedData, iv) { ... },
async fetchProfile() { ... },
logout() { ... },
}
})
```
---
## 六、API 封装
```
api/
├── request.js # 请求封装（baseURL, 拦截器, Token注入）
├── auth.js # 登录/注册
├── home.js # 首页数据
├── service.js # 服务/套餐
├── meal.js # 月子餐
├── nanny.js # 月嫂
├── growth.js # 共伴成长
├── order.js # 订单
├── pay.js # 支付
├── article.js # 文章/学堂
├── community.js # 社区
└── user.js # 个人中心
```
### 6.1 请求封装
```javascript
// api/request.js
const BASE_URL = 'https://xxx.com/api/v1/client'
const request = (options) => {
const userStore = useUserStore()
return new Promise((resolve, reject) => {
uni.request({
url: BASE_URL + options.url,
method: options.method || 'GET',
data: options.data,
header: {
'Authorization': `Bearer ${userStore.token}`,
'Content-Type': 'application/json'
},
success: (res) => {
if (res.data.code === 0) {
resolve(res.data.data)
} else if (res.data.code >= 40100 && res.data.code < 40200) {
// Token 过期，跳转登录
userStore.logout()
uni.navigateTo({ url: '/pages/auth/login' })
reject(res.data)
} else {
uni.showToast({ title: res.data.message, icon: 'none' })
reject(res.data)
}
},
fail: reject
})
})
}
export default request
```
---
## 七、微信能力集成
### 7.1 登录流程
```
用户打开小程序
↓
wx.login() 获取 code
↓
POST /client/auth/wechat-login { code }
↓
后端：code → openid/unionid → 查找/创建用户 → 返回 token
↓
若无手机号 → 弹出绑定手机号
↓
getPhoneNumber → 解密 → 绑定
↓
登录完成，进入首页
```
### 7.2 微信支付流程
```
用户点击支付
↓
POST /client/pay/wechat { order_id, ... }
↓
后端调用微信统一下单 → 返回支付参数
↓
前端 wx.requestPayment(payParams)
↓
支付成功/失败 → 跳转结果页
↓
后端接收微信回调 → 更新订单状态
```
### 7.3 分享
```javascript
// 页面分享配置
onShareAppMessage() {
return {
title: '宫中有喜·月子会所',
path: '/pages/index/index?inviter=' + userId,
imageUrl: '/static/share-cover.png'
}
}
onShareTimeline() {
return {
title: '宫中有喜·专业月子护理',
imageUrl: '/static/share-cover.png'
}
}
```
### 7.4 订阅消息
| 模板 | 触发场景 |
|------|----------|
| 订单状态通知 | 下单成功、支付成功、服务完成 |
| 服务预约提醒 | 预约确认、服务前1小时提醒 |
| 餐单推送 | 每日餐单发布 |
| 护理日报 | 每日护理小结 |
| 活动通知 | 新活动上线 |
### 7.5 其他微信能力
| 能力 | 用途 |
|------|------|
| 地图 | 门店定位、导航 |
| 客服 | 在线客服对话 |
| 图片选择/预览 | 评价上传图片 |
| 扫码 | 扫码签到、扫码支付 |
| 生物认证 | 敏感操作验证 |
---
## 八、UI 设计规范
### 8.1 色彩
| 色彩 | 色值 | 用途 |
|------|------|------|
| 主色 | #E8A87C | 温暖橘粉，品牌色 |
| 辅色 | #D4A574 | 暖棕，辅助强调 |
| 成功 | #67C23A | 完成/送达 |
| 警告 | #E6A23C | 提醒/待处理 |
| 危险 | #F56C6C | 异常/取消 |
| 文字主色 | #303133 | 正文 |
| 文字次色 | #909399 | 辅助说明 |
| 背景色 | #F5F5F5 | 页面背景 |
| 卡片色 | #FFFFFF | 内容卡片 |
### 8.2 字体
| 场景 | 大小 | 权重 |
|------|------|------|
| 大标题 | 36rpx | bold |
| 标题 | 32rpx | bold |
| 正文 | 28rpx | normal |
| 辅助文字 | 24rpx | normal |
| 价格 | 36rpx | bold |
### 8.3 间距
| 场景 | 值 |
|------|-----|
| 页面边距 | 32rpx |
| 卡片间距 | 24rpx |
| 卡片内边距 | 24rpx |
| 元素间距 | 16rpx |
| 紧凑间距 | 8rpx |
### 8.4 圆角
| 场景 | 值 |
|------|-----|
| 按钮 | 40rpx（胶囊） |
| 卡片 | 16rpx |
| 图片 | 12rpx |
| 标签 | 8rpx |
---
## 九、性能优化
| 策略 | 说明 |
|------|------|
| 分包加载 | 主包 < 2MB，子包按 Tab 分 |
| 图片懒加载 | 列表页图片按需加载 |
| 数据缓存 | 首页数据缓存 5 分钟 |
| 骨架屏 | 列表页加载时显示骨架 |
| 防抖节流 | 搜索输入防抖、按钮点击节流 |
| 虚拟列表 | 长列表使用 recycle-view |
### 9.1 分包配置
```json
{
"pages": [
"pages/index/index",
"pages/service/index",
"pages/growth/index",
"pages/study/index",
"pages/mine/index"
],
"subPackages": [
{
"root": "pages/service",
"pages": ["detail", "booking", "nanny/list", "nanny/detail", "nanny/order", "meal/today", "meal/week", "meal/custom"]
},
{
"root": "pages/growth",
"pages": ["baby/records", "baby/chart", "baby/milestone", "mom/records", "mom/chart"]
},
{
"root": "pages/study",
"pages": ["detail", "community/index", "community/detail", "community/post"]
},
{
"root": "pages/mine",
"pages": ["orders/list", "orders/detail", "account", "coupons", "reviews", "collections", "messages", "settings"]
},
{
"root": "pages/auth",
"pages": ["login", "bindPhone"]
},
{
"root": "pages/pay",
"pages": ["cashier", "result"]
}
]
}
```
---
## 十、安全设计
| 措施 | 说明 |
|------|------|
| Token 存储 | uni.setStorageSync 加密存储 |
| 接口签名 | 敏感接口请求签名（timestamp + nonce + sign） |
| HTTPS | 所有接口强制 HTTPS |
| 输入校验 | 前端校验 + 后端校验双重保障 |
| 敏感数据 | 手机号脱敏显示（138****8000） |
| 支付安全 | 服务端生成支付参数，前端不接触密钥 |
| 防重复提交 | 支付/下单按钮加 loading + 接口幂等 |
docs/07-deployment.md
+692
View File
@@ -0,0 +1,692 @@
# 宫中有喜 — 部署方案
## 一、部署架构
```
┌─────────────────────────────────────────┐
│ CDN (可选) │
│ 静态资源加速 │
└──────────────────┬──────────────────────┘
│
┌──────────────────▼──────────────────────┐
│ Nginx (反向代理) │
│ 80/443 → 静态资源 / API / WebSocket │
└────┬──────────────┬─────────────────────┘
│ │
▼ ▼
┌─────────┐ ┌──────────────┐
│ Vue SPA │ │ PHP-FPM │
│ (静态) │ │ Laravel App │
└─────────┘ └──────┬───────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
┌──────────┐ ┌────────┐ ┌─────────┐
│ MySQL 8 │ │ Redis │ │ Storage │
│ │ │ │ │ (文件) │
└──────────┘ └────────┘ └─────────┘
```
---
## 二、环境要求
| 组件 | 最低版本 | 推荐 |
|------|----------|------|
| OS | Ubuntu 20.04 / CentOS 8 | Ubuntu 22.04 |
| PHP | 8.1 | 8.2 |
| MySQL | 8.0 | 8.0 |
| Redis | 6.0 | 7.0 |
| Nginx | 1.18 | 1.24 |
| Node.js | 16 | 18 LTS |
| Composer | 2.x | 2.x |
| Docker | 20.10 | 24.x |
| Docker Compose | 2.x | 2.x |
### PHP 扩展
```
php-fpm php-mysql php-redis php-mbstring php-xml
php-curl php-gd php-zip php-bcmath php-intl
php-opcache php-fileinfo
```
---
## 三、Docker Compose 部署
### 3.1 docker-compose.yml
```yaml
version: '3.8'
services:
# Nginx 反向代理
nginx:
image: nginx:1.24-alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./docker/nginx/conf.d:/etc/nginx/conf.d
- ./docker/nginx/ssl:/etc/nginx/ssl
- ./frontend/dist:/var/www/frontend
- ./backend/public:/var/www/backend/public
- ./backend/storage/app/public:/var/www/backend/storage/app/public
depends_on:
- php
networks:
- app-network
restart: unless-stopped
# PHP-FPM
php:
build:
context: ./docker/php
dockerfile: Dockerfile
volumes:
- ./backend:/var/www/backend
depends_on:
- mysql
- redis
networks:
- app-network
restart: unless-stopped
# Laravel 队列 Worker
queue:
build:
context: ./docker/php
dockerfile: Dockerfile
command: php artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
volumes:
- ./backend:/var/www/backend
depends_on:
- mysql
- redis
networks:
- app-network
restart: unless-stopped
# Laravel 定时任务
scheduler:
build:
context: ./docker/php
dockerfile: Dockerfile
command: /bin/sh -c "while true; do php /var/www/backend/artisan schedule:run --verbose --no-interaction >> /dev/null 2>&1; sleep 60; done"
volumes:
- ./backend:/var/www/backend
depends_on:
- mysql
- redis
networks:
- app-network
restart: unless-stopped
# MySQL
mysql:
image: mysql:8.0
ports:
- "3306:3306"
environment:
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
MYSQL_DATABASE: ${DB_DATABASE}
MYSQL_USER: ${DB_USERNAME}
MYSQL_PASSWORD: ${DB_PASSWORD}
volumes:
- mysql-data:/var/lib/mysql
- ./docker/mysql/my.cnf:/etc/mysql/conf.d/my.cnf
- ./docker/mysql/init:/docker-entrypoint-initdb.d
networks:
- app-network
restart: unless-stopped
# Redis
redis:
image: redis:7-alpine
ports:
- "6379:6379"
command: redis-server --requirepass ${REDIS_PASSWORD}
volumes:
- redis-data:/data
networks:
- app-network
restart: unless-stopped
volumes:
mysql-data:
redis-data:
networks:
app-network:
driver: bridge
```
### 3.2 PHP Dockerfile
```dockerfile
# docker/php/Dockerfile
FROM php:8.2-fpm-alpine
# 安装扩展
RUN apk add --no-cache \
libpng-dev libjpeg-turbo-dev freetype-dev \
libzip-dev icu-dev oniguruma-dev \
&& docker-php-ext-configure gd --with-freetype --with-jpeg \
&& docker-php-ext-install \
pdo_mysql mbstring xml curl gd zip bcmath intl opcache pcntl \
&& pecl install redis \
&& docker-php-ext-enable redis
# Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
# PHP 配置
COPY php.ini /usr/local/etc/php/conf.d/custom.ini
WORKDIR /var/www/backend
# 权限
RUN chown -R www-data:www-data /var/www/backend
USER www-data
EXPOSE 9000
CMD ["php-fpm"]
```
### 3.3 PHP 配置
```ini
; docker/php/php.ini
upload_max_filesize = 20M
post_max_size = 25M
memory_limit = 256M
max_execution_time = 60
date.timezone = Asia/Shanghai
; OPcache
opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0
opcache.revalidate_freq=0
```
### 3.4 Nginx 配置
```nginx
# docker/nginx/conf.d/default.conf
# 后台管理 SPA
server {
listen 80;
server_name admin.example.com;
root /var/www/frontend;
index index.html;
# SPA 路由
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
# Gzip
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;
gzip_min_length 1024;
}
# API 服务
server {
listen 80;
server_name api.example.com;
root /var/www/backend/public;
index index.php;
# Laravel 路由
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# PHP-FPM
location ~ \.php$ {
fastcgi_pass php:9000;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
fastcgi_read_timeout 60;
}
# 文件上传大小
client_max_body_size 25m;
# 静态资源
location /storage {
alias /var/www/backend/storage/app/public;
expires 30d;
}
# 禁止访问隐藏文件
location ~ /\. {
deny all;
}
}
```
### 3.5 MySQL 配置
```ini
# docker/mysql/my.cnf
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
default-time-zone = '+08:00'
# InnoDB
innodb_buffer_pool_size = 512M
innodb_log_file_size = 128M
innodb_flush_log_at_trx_commit = 2
# 连接
max_connections = 200
wait_timeout = 600
# 慢查询
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2
# 二进制日志（用于备份恢复）
log-bin = mysql-bin
binlog_expire_logs_seconds = 604800
binlog_format = ROW
[client]
default-character-set = utf8mb4
```
---
## 四、环境变量 (.env)
```bash
# .env (生产环境示例)
APP_NAME="宫中有喜"
APP_ENV=production
APP_KEY=base64:xxxx
APP_DEBUG=false
APP_URL=https://api.example.com
# 数据库
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=gongzhongyouxi
DB_USERNAME=appuser
DB_PASSWORD=strong_password_here
DB_ROOT_PASSWORD=root_strong_password
# Redis
REDIS_HOST=redis
REDIS_PASSWORD=redis_password
REDIS_PORT=6379
# 缓存/队列/会话
CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
# 文件存储
FILESYSTEM_DISK=local
# 或 OSS:
# FILESYSTEM_DISK=oss
# OSS_ACCESS_KEY_ID=xxx
# OSS_ACCESS_KEY_SECRET=xxx
# OSS_BUCKET=xxx
# OSS_ENDPOINT=xxx
# 微信小程序
WECHAT_MINI_APP_ID=wxXXXXXXXXXXX
WECHAT_MINI_SECRET=xxxxxxxxxx
# 微信支付
WECHAT_PAY_MCH_ID=xxxxxxxxxx
WECHAT_PAY_KEY=xxxxxxxxxx
WECHAT_PAY_CERT_PATH=/path/to/cert
WECHAT_PAY_KEY_PATH=/path/to/key
WECHAT_PAY_NOTIFY_URL=https://api.example.com/api/v1/client/pay/callback
# 短信
SMS_DRIVER=aliyun
SMS_KEY=xxx
SMS_SECRET=xxx
SMS_SIGN=宫中有喜
# 日志
LOG_CHANNEL=daily
LOG_LEVEL=warning
```
---
## 五、部署流程
### 5.1 首次部署
```bash
# 1. 克隆代码
git clone <repo> /opt/saas
cd /opt/saas
# 2. 配置环境变量
cp .env.example .env
vim .env # 填入生产配置
# 3. 构建前端
cd frontend
npm install
npm run build
cd ..
# 4. 启动容器
docker compose up -d
# 5. 初始化 Laravel
docker compose exec php composer install --no-dev --optimize-autoloader
docker compose exec php php artisan key:generate
docker compose exec php php artisan migrate --force
docker compose exec php php artisan db:seed --class=InitSeeder
docker compose exec php php artisan storage:link
docker compose exec php php artisan config:cache
docker compose exec php php artisan route:cache
docker compose exec php php artisan view:cache
# 6. 验证
curl https://api.example.com/api/v1/health
```
### 5.2 更新部署
```bash
# 1. 拉取代码
cd /opt/saas
git pull origin main
# 2. 更新后端依赖
docker compose exec php composer install --no-dev --optimize-autoloader
# 3. 数据库迁移
docker compose exec php php artisan migrate --force
# 4. 清除缓存
docker compose exec php php artisan config:cache
docker compose exec php php artisan route:cache
docker compose exec php php artisan view:cache
docker compose exec php php artisan queue:restart
# 5. 更新前端（如有变更）
cd frontend
npm install
npm run build
cd ..
# 6. 重载 Nginx
docker compose exec nginx nginx -s reload
```
### 5.3 零停机部署（可选）
```bash
# 使用 Laravel 维护模式
docker compose exec php php artisan down --retry=60
# 执行部署步骤...
docker compose exec php php artisan up
```
---
## 六、备份策略
### 6.1 数据库备份
```bash
#!/bin/bash
# scripts/backup-db.sh
BACKUP_DIR="/opt/backups/mysql"
DATE=$(date +%Y%m%d_%H%M)
KEEP_DAYS=30
mkdir -p $BACKUP_DIR
# 备份
docker compose exec -T mysql mysqldump \
-u root -p"${DB_ROOT_PASSWORD}" \
--single-transaction \
--routines --triggers \
${DB_DATABASE} | gzip > "${BACKUP_DIR}/db_${DATE}.sql.gz"
# 清理旧备份
find $BACKUP_DIR -name "*.sql.gz" -mtime +$KEEP_DAYS -delete
echo "[$(date)] Backup completed: db_${DATE}.sql.gz"
```
### 6.2 文件备份
```bash
#!/bin/bash
# scripts/backup-files.sh
BACKUP_DIR="/opt/backups/files"
DATE=$(date +%Y%m%d)
mkdir -p $BACKUP_DIR
# 备份上传文件
tar -czf "${BACKUP_DIR}/storage_${DATE}.tar.gz" \
-C /opt/saas/backend storage/app/public
# 清理 30 天前
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
```
### 6.3 定时任务
```bash
# crontab -e
# 每天凌晨 3 点备份数据库
0 3 * * * /opt/saas/scripts/backup-db.sh >> /var/log/backup.log 2>&1
# 每周日凌晨 4 点备份文件
0 4 * * 0 /opt/saas/scripts/backup-files.sh >> /var/log/backup.log 2>&1
```
---
## 七、监控与日志
### 7.1 健康检查
```php
// routes/api.php
Route::get('/health', function () {
try {
DB::connection()->getPdo();
Redis::ping();
return response()->json([
'status' => 'healthy',
'timestamp' => now()->toISOString(),
'services' => [
'database' => 'ok',
'redis' => 'ok',
'storage' => is_writable(storage_path()) ? 'ok' : 'error',
]
]);
} catch (\Exception $e) {
return response()->json(['status' => 'unhealthy', 'error' => $e->getMessage()], 500);
}
});
```
### 7.2 日志管理
```php
// config/logging.php — 生产配置
'channels' => [
'daily' => [
'driver' => 'daily',
'path' => storage_path('logs/laravel.log'),
'level' => 'warning',
'days' => 14,
],
'business' => [
'driver' => 'daily',
'path' => storage_path('logs/business.log'),
'level' => 'info',
'days' => 30,
],
],
```
### 7.3 监控检查清单
| 监控项 | 方法 | 告警条件 |
|--------|------|----------|
| 服务存活 | /health 接口 | 连续 3 次失败 |
| CPU 使用率 | 系统监控 | > 80% 持续 5 分钟 |
| 内存使用率 | 系统监控 | > 85% |
| 磁盘使用率 | 系统监控 | > 80% |
| MySQL 连接数 | SHOW STATUS | > 150 |
| MySQL 慢查询 | 慢查询日志 | > 10 条/小时 |
| Redis 内存 | INFO memory | > 80% maxmemory |
| 队列积压 | queue:monitor | > 100 条待处理 |
| Laravel 日志 | 日志文件 | ERROR 级别 |
| 响应时间 | Nginx access_log | P95 > 2s |
| SSL 证书 | 定期检查 | 到期前 30 天 |
---
## 八、安全加固
### 8.1 服务器
```bash
# 防火墙 — 仅开放必要端口
ufw allow 22/tcp # SSH
ufw allow 80/tcp # HTTP
ufw allow 443/tcp # HTTPS
ufw enable
# SSH 加固
# /etc/ssh/sshd_config
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
```
### 8.2 Docker 安全
- 不使用 root 运行容器（PHP Dockerfile 已配置 www-data）
- MySQL/Redis 端口不暴露到公网（仅限 Docker 内部网络）
- 定期更新基础镜像
- 使用 `.dockerignore` 排除敏感文件
### 8.3 应用安全
| 措施 | 配置 |
|------|------|
| HTTPS 强制 | Nginx redirect 80→443 |
| CORS | 限定域名白名单 |
| CSRF | Sanctum SPA 模式自动处理 |
| Rate Limiting | Laravel throttle 中间件 |
| SQL 注入 | Eloquent 参数绑定 |
| XSS | HTMLPurifier + CSP Header |
| 文件上传 | 白名单 + 大小限制 + 病毒扫描 |
| 敏感数据 | .env 不入 Git，密钥加密存储 |
### 8.4 SSL 证书
```bash
# Let's Encrypt 免费证书
apt install certbot python3-certbot-nginx
certbot --nginx -d admin.example.com -d api.example.com
# 自动续期
certbot renew --dry-run
# crontab
0 0 1 */2 * certbot renew --quiet
```
---
## 九、性能优化
### 9.1 Laravel 优化
```bash
# 配置/路由/视图缓存
php artisan config:cache
php artisan route:cache
php artisan view:cache
# Composer 自动加载优化
composer install --optimize-autoloader --no-dev
```
### 9.2 MySQL 优化
- 索引覆盖常用查询（见 02-database-design.md 索引策略）
- 开启查询缓存（Redis 层面）
- 大表分页使用 cursor 分页
- 定期 ANALYZE TABLE
### 9.3 Redis 缓存策略
| 缓存键 | TTL | 场景 |
|--------|-----|------|
| user:{id} | 30min | 用户信息 |
| menu:{role_id} | 60min | 角色菜单 |
| room:board:{store_id}:{date} | 5min | 房态看板 |
| config:{key} | 60min | 系统配置 |
| dict:{type} | 24h | 数据字典 |
### 9.4 前端优化
- Vite 构建：代码分割 + Tree Shaking
- 路由懒加载：按模块动态 import
- 图片压缩：WebP 格式 + CDN
- Gzip：Nginx 开启 gzip 压缩
---
## 十、目录结构（Docker 相关）
```
saas/
├── docker/
│ ├── nginx/
│ │ ├── conf.d/
│ │ │ └── default.conf
│ │ └── ssl/ # SSL 证书
│ ├── php/
│ │ ├── Dockerfile
│ │ └── php.ini
│ └── mysql/
│ ├── my.cnf
│ └── init/ # 初始化 SQL
├── scripts/
│ ├── backup-db.sh
│ ├── backup-files.sh
│ └── deploy.sh
├── docker-compose.yml
├── .env
└── .env.example
```