fengshao1227/yuezi-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
yuezi-saas/docs/03-api-specification.md
T
li 11c177a432 feat: 第一阶段基础框架搭建 
后端 (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设计/模块详设/小程序设计/部署方案
2026-03-13 19:52:09 +08:00

793 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 宫中有喜 — 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%"
}
}
}
```
Reference in New Issue View Git Blame Copy Permalink