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/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%"
}
}
}
```