# 宫中有喜 — 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%"
        }
    }
}
```
