yuezi-saas/docs/03-api-specification.md

宫中有喜 — 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 统一响应格式

// 成功
{
    "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 新建线索

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:

{
    "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 房态看板

GET /api/v1/room/rooms/board?date=2024-03-15&range=week
Authorization: Bearer xxx

Response:

{
    "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%"
        }
    }
}