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