一个基于 Laravel 12 的家庭健康管理平台后端 API 服务

📖 项目介绍

家庭健康记录系统是一个功能完善的家庭健康管理平台后端服务，采用 Laravel 12 框架构建，专门为微信小程序提供 RESTful API 接口。系统支持多家庭成员管理、健康数据追踪、AI 智能分析、用药提醒等核心功能，帮助家庭更好地管理成员健康状况。

项目地址：

✨ 核心功能

• 👨‍👩‍👧‍👦 多成员管理 – 支持创建多个家庭，每个家庭可添加多位成员（老人、成人、儿童）
• 📊 健康指标监测 – 血压、血糖、心率、体温、体重等多项指标的录入与趋势分析
• 🤖 AI 智能分析 – 基于健康数据的智能分析、风险预测和个性化建议
• ⏰ 健康提醒 – 用药提醒、体检提醒、运动提醒、测量提醒等多维度提醒功能
• 🏥 完整医疗档案 – 体检报告、病史记录、用药记录、疫苗接种记录全生命周期管理
• 🏃 生活习惯追踪 – 睡眠质量、每日步数、饮水量、运动情况等生活方式记录
• 🚨 异常告警 – 健康指标超标自动告警，及时提醒用户关注异常情况
• 💬 微信登录 – 支持微信小程序一键登录（OpenID/UnionID），无需注册
• 🔐 权限控制 – RBAC 角色权限管理，保障家庭成员数据隐私安全
• 📱 移动端优化 – API 响应格式针对小程序优化，支持分页加载和离线缓存

🛠️ 技术栈

分类	技术	版本
后端框架	Laravel	12.x
编程语言	PHP	8.2+
API 认证	Laravel Sanctum	4.x
数据库	MySQL / SQLite	5.7+ / 3.x
队列系统	Database Queue	–
缓存系统	Database Cache	–
前端构建	Vite	5.x
CSS 框架	Tailwind CSS	3.x

📋 环境要求

• PHP >= 8.2
• Composer >= 2.0
• Node.js >= 18.x
• NPM >= 9.x
• MySQL 5.7+ 或 SQLite 3.x
• Git

🚀 快速开始

1️⃣ 克隆项目

git clone https://gitee.com/your-username/family-health.git
cd family-health

2️⃣ 安装依赖

# 安装 PHP 依赖
composer install

# 安装前端依赖
npm install

💡 提示: 如果下载速度慢，可以使用国内镜像源：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
npm config set registry https://registry.npmmirror.com

3️⃣ 配置环境变量

# 复制环境配置文件
cp .env.example .env

# 生成应用密钥
php artisan key:generate

编辑 .env 文件，修改以下配置：

# 应用配置
APP_NAME=家庭健康记录系统
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# 数据库配置（二选一）

# 方式一：MySQL（推荐生产环境）
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=family_health
DB_USERNAME=root
DB_PASSWORD=your_password

# 方式二：SQLite（适合开发测试）
DB_CONNECTION=sqlite
# DB_DATABASE=/absolute/path/to/database/database.sqlite

# 微信小程序配置（可选，不配置会使用模拟登录）
WECHAT_MINI_APP_ID=wx_your_app_id
WECHAT_MINI_APP_SECRET=your_app_secret

# 队列配置（建议使用 database）
QUEUE_CONNECTION=database

# 缓存配置
CACHE_STORE=database

4️⃣ 初始化数据库

方式一：使用 Laravel Migration（推荐）

# 执行数据库迁移
php artisan migrate

# 填充示例数据（包含 343+ 条测试数据）
php artisan db:seed

方式二：导入 SQL 文件

# 先创建数据库
mysql -u root -p -e "CREATE DATABASE family_health CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入表结构
mysql -u root -p family_health < database/family_health_database.sql

# 导入示例数据
mysql -u root -p family_health < database/family_health_sample_data.sql

5️⃣ 启动服务

开发模式（推荐）

一键启动所有服务（API + 队列 + 日志监控 + Vite）：

composer run dev

单独启动

# 启动 API 服务
php artisan serve

# 启动队列监听（后台运行）
php artisan queue:listen –tries=3 –timeout=0 &

# 启动 Vite 开发服务器（如需前端资源）
npm run dev

访问 http://localhost:8000 即可看到应用。

---

🧪 快速测试 API

获取访问令牌

curl -X POST http://localhost:8000/api/v1/auth/dev-login \
  -H "Content-Type: application/json" \
  -d '{"user_id": 1}'

响应示例：

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "1|xxxxxxxxxxxxx",
    "user": {...}
  }
}

获取仪表盘数据

curl -X GET http://localhost:8000/api/v1/dashboard \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxx"

查看健康指标列表

curl -X GET http://localhost:8000/api/v1/health-indicators \
  -H "Authorization: Bearer 1|xxxxxxxxxxxxx"

🗄️ 数据库说明

数据表概览

系统共包含 30+ 张数据表，按功能模块分类如下：

👤 用户与权限模块（5张表）

表名	说明	备注
users	用户表	含微信 OpenID/UnionID
roles	角色表	admin/doctor/family_member
permissions	权限表	细粒度权限定义
role_user	角色用户关联	多对多关系
permission_role	权限角色关联	多对多关系

👨‍👩‍👧‍👦 家庭与成员模块（3张表）

表名	说明	备注
families	家庭信息表	支持多家庭
family_members	家庭成员表	关联用户与健康档案
relationships	关系类型表	父子/夫妻/祖孙等16种关系

📊 健康核心数据模块（5张表）

表名	说明	备注
health_indicators	健康指标定义	血压/血糖/心率等26项指标
health_records	健康指标记录	实际测量数据
medical_examinations	体检记录	年度体检报告
medical_histories	病史记录	慢性病/急性病等
medications	用药记录	处方药/非处方药/保健品

📝 健康扩展功能模块（7张表）

表名	说明	备注
vaccination_records	疫苗接种记录	一类/二类疫苗
health_reminders	健康提醒	用药/体检/运动提醒
lifestyle_records	生活习惯记录	睡眠/步数/饮水/运动
health_diaries	健康日记	心情/症状/精力记录
health_alerts	健康告警	异常指标自动告警
health_record_shares	健康记录分享	分享给医生/家人
device_bindings	设备绑定	智能手环/血压计等

🤖 AI 功能模块（6张表）

表名	说明	备注
ai_health_analyses	AI 健康分析	智能分析报告
ai_health_predictions	AI 健康预测	疾病风险预测
ai_health_recommendations	AI 健康建议	个性化健康建议
ai_conversation_logs	AI 对话记录	健康咨询对话
ai_health_reports	AI 健康报告	综合健康报告
ai_data_validations	AI 数据验证	数据质量校验

⚙️ 系统基础表（7张表）

password_reset_tokens、sessions、cache、cache_locks、jobs、job_batches、failed_jobs、personal_access_tokens

示例数据说明

系统预置了丰富的示例数据，总计 343+ 条记录，涵盖：

• ✅ 12 个用户 – 包含完整的微信登录信息
• ✅ 8 个家庭 – 覆盖老中青三代不同家庭结构
• ✅ 27 个家庭成员 – 每个成员都有完整健康档案
• ✅ 120 条健康指标记录 – 血压(20)、血糖(20)、心率(10)、体重(10)、体温(10)等
• ✅ 15 条体检记录 – 主要家庭成员的年度体检数据
• ✅ 15 条病史记录 – 高血压、糖尿病等慢性病记录
• ✅ 20 条用药记录 – 降压药、降糖药、维生素等
• ✅ 50 条生活习惯记录 – 连续多天的睡眠、步数、饮水数据
• ✅ 30 条健康日记 – 日常健康状态主观感受
• ✅ 20 条健康告警 – 血压超标、血糖异常等告警
• ✅ 16 条 AI 数据 – 分析、预测、建议、报告、对话记录

详细数据统计请查看 数据优化总结

📡 API 接口文档

基本信息

• 基础路径: /api/v1
• 认证方式: Bearer Token (Laravel Sanctum)
• 请求头: Authorization: Bearer {token}
• 字符编码: UTF-8
• 响应格式: JSON

统一响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    // 业务数据
  }
}

错误响应

{
  "code": 40001,
  "message": "未授权访问",
  "data": null
}

分页响应

{
  "code": 0,
"message": "success",
"data": [
    // 数据列表
  ],
"meta": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 15,
    "total": 150,
    "has_more": true
  }
}

接口模块总览

🔐 认证模块 /api/v1/auth

方法	路径	说明	是否需要认证
POST	/wechat-login	微信小程序登录	❌
POST	/dev-login	开发环境快速登录	❌
GET	/me	获取当前用户信息	✅
PUT	/profile	更新用户资料	✅
POST	/logout	退出登录	✅

微信登录示例

请求：

POST /api/v1/auth/wechat-login
Content-Type: application/json

{
  “code”: “wx_login_code_from_miniprogram”,
  “nickname”: “张三”,
  “avatar”: “https://example.com/avatar.jpg”
}

响应：

{
  "code": 0,
"message": "登录成功",
"data": {
    "token": "1|xxxxxxxxxxxxx",
    "user": {
      "id": 1,
      "name": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "wechat_openid": "oXXXXXX"
    }
  }
}

💡 提示: 本地开发时如未配置 WECHAT_MINI_APP_ID，系统会使用 code 生成模拟 openid，方便调试。

📊 仪表盘 /api/v1/dashboard

方法	路径	说明
GET	/dashboard	获取家庭统计、最近记录、告警、待办提醒

返回数据包含：

• 家庭成员数量
• 今日健康记录数
• 活跃告警列表
• 待完成提醒
• 最近健康记录

👨‍👩‍👧‍👦 家庭与成员

家庭管理

方法	路径	说明
GET	/families	获取家庭列表
POST	/families	创建新家庭
GET	/families/{id}	获取家庭详情
PUT	/families/{id}	更新家庭信息
DELETE	/families/{id}	删除家庭

成员管理

方法	路径	说明
GET	/members	获取成员列表（支持 ?family_id=1 筛选）
POST	/members	添加家庭成员
GET	/members/{id}	获取成员详情
PUT	/members/{id}	更新成员信息
DELETE	/members/{id}	移除成员

📈 健康记录

健康指标

方法	路径	说明
GET	/health-indicators	获取指标列表
GET	/health-indicators/{id}	获取指标详情

查询参数：

• common_only=true – 仅返回常用指标
• category=blood – 按分类筛选
• quick_entry_only=true – 仅返回快捷录入指标

健康记录

方法	路径	说明
GET	/health-records	获取记录列表
POST	/health-records	录入新记录
GET	/health-records/{id}	获取记录详情
DELETE	/health-records/{id}	删除记录
GET	/health-records/trends	获取趋势图数据

查询参数：

• • family_member_id=1 – 按成员筛选
  • health_indicator_id=1 – 按指标筛选
  • start_date=2024-01-01 – 开始日期
  • end_date=2024-12-31 – 结束日期

趋势图参数：

• family_member_id=1 – 必填
• health_indicator_id=1 – 必填
• days=30 – 天数（默认30天）

🏥 医疗档案

资源	接口路径	说明
体检记录	/medical-examinations	CRUD 完整操作
病史记录	/medical-histories	CRUD，支持 ?status=active 筛选
用药记录	/medications	CRUD，默认 ?active_only=true
疫苗接种	/vaccination-records	CRUD 完整操作

⏰ 健康提醒与生活

健康提醒

方法	路径	说明
GET	/health-reminders	获取提醒列表
POST	/health-reminders	创建新提醒
POST	/health-reminders/{id}/complete	标记为已完成
DELETE	/health-reminders/{id}	删除提醒

生活习惯

方法	路径	说明
GET	/lifestyle-records	获取生活记录列表
POST	/lifestyle-records	录入生活记录（同日期自动更新）

健康日记

方法	路径	说明
GET	/health-diaries	获取日记列表
POST	/health-diaries	新建日记

🚨 告警与设备

健康告警

方法	路径	说明
GET	/health-alerts	获取活跃告警列表
POST	/health-alerts/{id}/resolve	解决告警
POST	/health-alerts/{id}/dismiss	忽略告警

设备绑定

方法	路径	说明
GET	/devices	获取已绑定设备列表
POST	/devices	绑定新设备
PUT	/devices/{id}	更新设备信息
DELETE	/devices/{id}	解绑设备

🤖 AI 功能

方法	路径	说明
GET	/ai/analyses	获取 AI 分析记录列表
GET	/ai/recommendations	获取 AI 健康建议
POST	/ai/recommendations/{id}/feedback	提交建议采纳反馈
GET	/ai/reports	获取 AI 健康报告列表
GET	/ai/reports/{id}	获取报告详情
POST	/ai/chat	AI 健康咨询对话
POST	/ai/predict	AI 健康风险预测

AI 对话示例

POST /api/v1/ai/chat
{
  "message": "我最近的血压偏高，应该注意什么？",
  "family_member_id": 1
}

📚 参考数据

方法	路径	说明
GET	/relationships	获取家庭成员关系类型列表

完整 API 文档请查看 API.md

---

🧪 测试

# 运行所有测试
php artisan test

# 运行单元测试
php artisan test –testsuite=Unit

# 运行功能测试
php artisan test –testsuite=Feature

# 运行指定测试文件
php artisan test tests/Feature/Api/AuthTest.php

📁 项目结构

Family/
├── app/                          # 应用核心代码
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── Api/V1/          # API v1 控制器（18个）
│   │   ├── Resources/Api/       # API 资源转换器（24个）
│   │   └── Traits/              # 复用 Trait
│   ├── Models/                  # Eloquent 模型（27个）
│   ├── Services/                # 业务逻辑服务层
│   │   ├── Ai/                  # AI 相关服务（4个）
│   │   ├── Auth/                # 认证服务
│   │   ├── Family/              # 家庭管理服务
│   │   └── Health/              # 健康管理服务（2个）
│   └── Providers/               # 服务提供者
│
├── bootstrap/                   # 框架引导文件
├── config/                      # 配置文件
│   ├── ai.php                   # AI 服务配置
│   ├── wechat.php               # 微信配置
│   ├── sanctum.php              # Sanctum 认证配置
│   └── ...                      # 其他 Laravel 配置
│
├── database/                    # 数据库相关文件
│   ├── migrations/              # 数据库迁移文件（37个）
│   ├── seeders/                 # 数据填充器（4个）
│   ├── scripts/                 # 数据库优化脚本（3个）
│   ├── factories/               # 模型工厂
│   ├── family_health_database.sql      # 完整数据库结构 SQL
│   └── family_health_sample_data.sql   # 示例数据 SQL
│
├── docs/                        # 项目文档
│   ├── API.md                   # API 详细文档
│   └── DATA_OPTIMIZATION_SUMMARY.md  # 数据优化总结
│
├── routes/                      # 路由定义
│   ├── api.php                  # API 路由（81行）
│   ├── web.php                  # Web 路由
│   └── console.php              # 命令行路由
│
├── resources/                   # 视图和资源文件
│   ├── css/                     # CSS 源文件
│   ├── js/                      # JavaScript 源文件
│   └── views/                   # Blade 模板
│
├── storage/                     # 存储目录
│   ├── app/                     # 应用存储
│   ├── framework/               # 框架存储
│   └── logs/                    # 日志文件
│
├── tests/                       # 测试文件
│   ├── Feature/Api/             # API 功能测试
│   └── Unit/Services/Ai/        # AI 服务单元测试
│
├── public/                      # Web 根目录
├── vendor/                      # Composer 依赖
├── artisan                      # Laravel 命令行工具
├── composer.json                # PHP 依赖配置
├── package.json                 # Node.js 依赖配置
└── vite.config.js               # Vite 构建配置

---

⚙️ 配置说明

关键环境变量

变量名	说明	默认值	示例
APP_NAME	应用名称	Laravel	家庭健康记录系统
APP_ENV	应用环境	local	local / production
APP_DEBUG	调试模式	true	true / false
DB_CONNECTION	数据库类型	sqlite	mysql / sqlite
WECHAT_MINI_APP_ID	微信小程序 AppID	–	wx1234567890
WECHAT_MINI_APP_SECRET	微信小程序 Secret	–	abcdef123456
QUEUE_CONNECTION	队列驱动	database	database / redis
CACHE_STORE	缓存驱动	database	database / redis

队列配置

对于 AI 分析、健康报告生成等长时任务，建议使用队列异步处理：

# 启动队列工作进程
php artisan queue:work --tries=3 --timeout=0

# 后台运行
nohup php artisan queue:work –tries=3 –timeout=0 > /dev/null 2>&1 &

# 查看队列状态
php artisan queue:monitor

💡 提示: 生产环境建议使用 Redis 作为队列驱动，性能更佳。

📱 微信小程序适配

核心优化点

✅ 响应格式统一 – 采用 code/message/data 标准格式，便于小程序端统一处理
✅ 分页优化 – 返回 has_more 字段，支持下拉加载更多，减少内存占用
✅ 性能优化 – Dashboard 数据 5 分钟缓存，减少数据库查询次数
✅ 数据传输优化 – 精简冗余字段，降低网络传输量，提升加载速度
✅ 图片上传支持 – 支持头像、体检报告等图片上传至服务器
✅ 离线缓存友好 – 数据结构设计支持小程序本地缓存策略

典型应用场景

场景	功能描述	涉及接口
🏠 首页仪表盘	快速查看家庭成员健康概览、告警、待办	GET /dashboard
📊 健康记录	血压、血糖等指标录入与趋势图表展示	GET/POST /health-records
💊 用药提醒	定时推送用药提醒，标记完成状态	GET/POST /health-reminders
🏥 体检报告	查看历史体检结果，对比分析	GET /medical-examinations
🤖 AI 助手	智能健康分析与个性化建议	POST /ai/chat
👨‍👩‍👧 成员管理	添加/编辑家庭成员信息	GET/POST /members

小程序端调用示例

// 获取访问令牌
wx.request({
url: 'https://your-domain.com/api/v1/auth/wechat-login',
method: 'POST',
data: {
    code: res.code,  // wx.login 获取的 code
    nickname: userInfo.nickName,
    avatar: userInfo.avatarUrl
  },
success: (res) => {
    if (res.data.code === 0) {
      // 保存 token
      wx.setStorageSync('token', res.data.data.token)
    }
  }
})

// 获取仪表盘数据
const token = wx.getStorageSync(‘token’)
wx.request({
url: ‘https://your-domain.com/api/v1/dashboard’,
header: {
    ‘Authorization’: ‘Bearer ‘ + token
  },
success: (res) => {
    if (res.data.code === 0) {
      console.log(‘仪表盘数据:’, res.data.data)
    }
  }
})

🔐 安全与权限

RBAC 权限系统

系统实现了完整的基于角色的访问控制（Role-Based Access Control）：

预设角色

角色	标识	说明
管理员	admin	系统管理员，拥有所有权限
医生	doctor	可查看和管理患者健康数据
家庭成员	family_member	普通用户，管理自己及家人的健康数据

权限隔离

• ✅ 家庭成员只能查看自己所在家庭的成员数据
• ✅ 敏感健康数据需要相应权限才能访问
• ✅ 健康记录分享功能支持临时授权给医生或其他家庭成员

API 认证机制

• 使用 Laravel Sanctum 进行令牌认证
• 支持个人访问令牌（Personal Access Tokens）
• 令牌可设置过期时间和权限范围（abilities）
• 每次请求需在 Header 中携带 Authorization: Bearer {token}

创建令牌示例

$token = $user->createToken('my-app-token', ['health-records:view'])->plainTextToken;

⚡ 性能优化

已实施的优化措施

✅ 数据库索引优化 – 为常用查询字段添加复合索引，提升查询效率
✅ Eager Loading – 避免 N+1 查询问题，减少数据库查询次数
✅ 缓存策略 – Dashboard 数据 5 分钟缓存，健康指标列表缓存
✅ 队列异步处理 – AI 分析、报告生成长时任务使用队列异步执行
✅ 软删除机制 – 使用 Laravel 软删除，避免物理删除导致的数据丢失
✅ SQL 优化 – 遵循 Laravel 最佳实践，优化查询语句

性能建议

🚀 Redis 缓存 – 对高频访问数据使用 Redis 缓存，进一步提升响应速度
🚀 数据归档 – 定期归档历史数据（如一年前的健康记录），保持主表轻量化
🚀 CDN 加速 – 静态资源（头像、体检报告图片）使用 CDN 分发
🚀 API 限流 – 实施 API 请求频率限制，防止恶意请求
🚀 监控告警 – 启用 Laravel Telescope 或 Sentry 进行性能监控和错误追踪

数据库优化脚本

项目提供了数据库优化脚本：

# 统计各表数据量
php database/scripts/count_rows.php

# 导出示例 SQL（用于测试）
php database/scripts/export_sample_sql.php

# 优化 SQL 查询
php database/scripts/optimize_sql.php

看完不过瘾，那就自己发一篇吧！