# visaid

**Repository Path**: yzy5165156/visaid

## Basic Information

- **Project Name**: visaid
- **Description**: 视障人士辅助工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VisAid 视障人士居家辅助系统

VisAid 是一个面向视障用户和家属协同照护的移动端辅助系统。项目采用 React + Capacitor 构建 Android/Web 前端，FastAPI + MySQL 提供后端服务，结合视觉识别、语音播报、震动反馈、药品管理、安全求助和远程协助，形成视障端与家属端的功能闭环。

## 当前功能

### 视障用户端

底部导航保留 4 个入口：

- `首页`：功能选择入口，包含视觉识别、药品识别、寻物识别、发送紧急求助。
- `安全`：大按钮状态页，提供报平安、紧急求助、共享位置。
- `协助`：集中处理家属发来的当前任务，包括留言、语音指导、导航步骤、任务提醒、视频通话和实时画面共享。
- `我的`：用户中心，包含家属绑定、语音播报设置、震动设置、隐私说明、用户信息和退出登录。

识别页面支持系统返回键、顶部大触摸返回区和语音命令“返回首页”。安全、协助、我的页面进入时会进行语音播报，关键按钮配备震动反馈。

### 家属端

底部导航包含：

- `首页`：绑定用户概览和快捷入口。
- `健康`：查看绑定视障用户的药品管理、服药提醒、今日服药状态、服药依从性、24 小时活动模式和异常行为。
- `安全`：查看视障用户安全快照、位置、步数、外出护航状态，接收并处理紧急求助。
- `远程`：发送留言、语音指导、导航指令、任务提醒、视频通话请求，并查看视障端实时画面共享。
- `我的`：账号信息、绑定管理和设置。

### 药品识别与家属健康页闭环

药品识别流程如下：

1. 视障端拍照后调用 `/api/v1/vision/identify`。
2. 后端保存识别图片到 `uploads/`，并写入 `recognition_logs`。
3. 药品识别模式会额外生成一条药品记录，写入 `medicines`。
4. 自动生成的药品记录会在 `usage` 中保留完整识别结果，并标记为“药品识别记录，待家属确认有效期和用法”。
5. 家属端健康页的“药品管理”卡片会显示这些药品，标记“识别待确认”，并可直接为该药设置服药提醒。

这样视障端的药品识别结果可以被家属端接收、查看和后续管理。

## 技术栈

### 前端

- React 18
- React Router
- Ant Design Icons
- Vite
- Capacitor 8
- Capacitor Local Notifications
- Web Speech API / Android 原生语音插件
- Web Vibration API / Android 原生震动插件

### 后端

- Python 3
- FastAPI
- SQLAlchemy
- MySQL
- JWT 鉴权
- 智谱 GLM 视觉识别
- DeepSeek 语音引导润色，可通过环境变量开关控制

## 目录结构

```text
.
├── app/
│   ├── database.py              # MySQL 连接和数据库初始化
│   └── models.py                # 用户、药品、识别、安全、远程协助等模型
├── services/
│   ├── ai_engine.py             # DeepSeek 语音引导服务
│   └── vision_service.py        # 智谱视觉识别服务
├── src/
│   ├── components/              # 通用组件，如紧急求助长按按钮
│   ├── hooks/                   # 返回首页语音命令、页面播报等 Hook
│   ├── pages/
│   │   ├── Home.jsx             # 视障端首页
│   │   ├── Vision.jsx           # 视觉识别 / 药品识别
│   │   ├── Find.jsx             # 寻物识别
│   │   ├── SecurityMonitoring.jsx
│   │   ├── PatientRemoteAssistance.jsx
│   │   ├── HealthMonitoring.jsx
│   │   ├── RemoteAssistance.jsx
│   │   ├── Family.jsx
│   │   └── Profile.jsx
│   ├── services/
│   │   ├── api.js               # 在线 API 客户端
│   │   ├── offlineAPI.js        # 离线回退和同步队列封装
│   │   ├── medicineRecognition.js
│   │   ├── speech.js
│   │   └── haptics.js
│   ├── App.jsx
│   └── main.jsx
├── android/                     # Capacitor Android 工程
├── main.py                      # FastAPI 入口
├── requirements.txt
├── package.json
├── capacitor.config.json
└── vite.config.js
```

## 环境变量

复制 `.env.example` 为 `.env`，并按本机环境填写：

```env
DATABASE_URL="mysql+pymysql://username:password@localhost:3306/visaid_db"
SECRET_KEY="replace-with-a-random-secret"

ZHIPU_API_KEY="your_zhipu_api_key"

DEEPSEEK_API_KEY="your_deepseek_api_key"
DEEPSEEK_API_URL="https://api.deepseek.com/chat/completions"
ENABLE_DEEPSEEK_VOICE_GUIDANCE="false"

# 可选：覆盖前端 API 地址
# VITE_API_BASE_URL="http://localhost:8000/api/v1"
# VITE_STATIC_BASE_URL="http://localhost:8000/static"
```

后端当前要求 `DATABASE_URL` 必须指向 MySQL，不再支持 SQLite。`SECRET_KEY` 必须配置，否则后端会拒绝启动。

## 本地开发

### 1. 安装后端依赖

```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

### 2. 启动后端

```bash
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

后端文档地址：

```text
http://127.0.0.1:8000/docs
```

### 3. 安装前端依赖

```bash
npm install
```

### 4. 启动前端

```bash
npm run dev
```

Vite 默认端口为 `3001`，开发环境会把 `/api` 代理到 `http://localhost:8000/api/v1`。

## Android 真机调试

前端生产包默认访问：

```text
http://localhost:8000/api/v1
```

Android 真机上的 `localhost` 指手机自身，因此调试电脑后端时需要 ADB 反向映射：

```powershell
D:\AndroidSdk\platform-tools\adb.exe devices
D:\AndroidSdk\platform-tools\adb.exe reverse tcp:8000 tcp:8000
D:\AndroidSdk\platform-tools\adb.exe reverse --list
```

正常应看到：

```text
tcp:8000 tcp:8000
```

构建并安装 APK：

```powershell
npm run build
.\node_modules\.bin\cap.cmd sync android
cd android
.\gradlew.bat assembleDebug
cd ..
D:\AndroidSdk\platform-tools\adb.exe install -r .\android\app\build\outputs\apk\debug\visaid-debug.apk
D:\AndroidSdk\platform-tools\adb.exe reverse tcp:8000 tcp:8000
```

## 主要接口

### 认证与绑定

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/v1/auth/register` | 注册 |
| POST | `/api/v1/auth/token` | 登录获取 Token |
| GET | `/api/v1/user/me` | 当前用户信息 |
| POST | `/api/v1/user/generate-bind-code` | 生成绑定码 |
| POST | `/api/v1/user/bind` | 家属提交绑定申请 |
| GET | `/api/v1/user/bindings` | 获取绑定关系 |
| GET | `/api/v1/user/bindings/pending` | 获取待审核绑定申请 |
| POST | `/api/v1/user/bindings/approve` | 审核绑定申请 |
| POST | `/api/v1/user/bindings/unbind` | 解除绑定 |
| GET / PUT | `/api/v1/user/settings` | 用户无障碍设置 |

### 识别与药品

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/v1/vision/identify` | 图片识别，保存识别历史 |
| GET | `/api/v1/vision/history` | 查询识别历史 |
| DELETE | `/api/v1/vision/history/{log_id}` | 删除识别历史及图片 |
| POST | `/api/v1/medicine` | 添加药品 |
| GET | `/api/v1/medicine/list` | 查询药品列表 |
| GET | `/api/v1/medicine/all` | 查询药品和过期状态 |
| GET | `/api/v1/medicine/inventory` | 查询药品库存/有效期状态 |
| POST | `/api/v1/medicine/reminder` | 添加服药提醒 |
| GET | `/api/v1/medicine/reminders` | 查询服药提醒 |
| DELETE | `/api/v1/medicine/reminder/{reminder_id}` | 删除服药提醒 |
| POST | `/api/v1/medicine/intake` | 记录服药状态 |
| GET | `/api/v1/medicine/intakes/today` | 今日服药状态 |
| GET | `/api/v1/medicine/intakes/weekly` | 本周服药统计 |

### 安全与健康

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/v1/safety/snapshot` | 获取安全快照 |
| POST | `/api/v1/safety/snapshot` | 更新位置、报平安、护航状态 |
| POST | `/api/v1/emergency/alert` | 发送紧急求助 |
| GET | `/api/v1/emergency/alerts` | 查询紧急求助 |
| PATCH | `/api/v1/emergency/alerts/{alert_id}` | 标记求助已处理 |
| POST | `/api/v1/health/device-sync` | 同步设备健康数据 |
| GET | `/api/v1/health/device-summary` | 健康数据汇总 |
| GET | `/api/v1/analysis/behavior` | 行为和识别活动分析 |

### 远程协助

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/v1/remote/voice-message` | 家属发送留言 |
| GET | `/api/v1/remote/voice-messages` | 视障端拉取留言 |
| PATCH | `/api/v1/remote/voice-messages/{message_id}/read` | 留言已读 |
| POST | `/api/v1/remote/voice-guidance` | 家属发送语音指导 |
| GET | `/api/v1/remote/voice-guidances` | 视障端拉取语音指导 |
| PATCH | `/api/v1/remote/voice-guidances/{guidance_id}/read` | 指导已读 |
| POST | `/api/v1/remote/navigation` | 创建导航指令 |
| GET | `/api/v1/remote/navigation/instructions` | 拉取导航指令 |
| PATCH | `/api/v1/remote/navigation/instructions/{instruction_id}/next` | 完成下一步导航 |
| PATCH | `/api/v1/remote/navigation/instructions/{instruction_id}/cancel` | 取消导航 |
| POST | `/api/v1/remote/tasks` | 创建远程任务 |
| GET | `/api/v1/remote/tasks` | 拉取远程任务 |
| PATCH | `/api/v1/remote/tasks/{task_id}/complete` | 标记任务完成 |
| POST | `/api/v1/remote/video-call` | 发起视频通话请求 |
| GET | `/api/v1/remote/video-call/requests` | 拉取通话请求 |
| PATCH | `/api/v1/remote/video-call/{call_id}/accept` | 接受通话 |
| PATCH | `/api/v1/remote/video-call/{call_id}/reject` | 拒绝通话 |
| POST | `/api/v1/remote/camera/start` | 开启实时画面共享 |
| POST | `/api/v1/remote/camera/upload` | 上传实时画面帧 |
| GET | `/api/v1/remote/camera/stream` | 家属端查看实时画面 |
| POST | `/api/v1/remote/camera/stop` | 停止实时画面共享 |

## 离线与同步

前端通过 `offlineAPI.js` 和 `localStorage.js` 提供基础离线回退能力。药品、提醒、健康、远程部分操作会优先请求后端；网络不可用时部分数据会保存在本地，并进入同步队列，网络恢复后由 `syncEngine.js` 自动同步。

## 注意事项

- 智谱视觉识别需要有效的 `ZHIPU_API_KEY`。
- DeepSeek 语音润色默认可关闭，关闭后会直接播报基础识别结果，识别等待时间更短。
- Android 真机调试后端时必须保持 `adb reverse tcp:8000 tcp:8000`。
- 药品识别生成的药品记录属于“待确认记录”，家属可在健康页查看识别内容并为药品设置提醒；真实有效期和用法的编辑表单仍需后续补充。
- 识别图片会保存到后端 `uploads/`，删除识别记录时会同步删除对应图片。

## 常用命令

```powershell
# 前端构建
npm run build

# 同步到 Android
.\node_modules\.bin\cap.cmd sync android

# Android debug 包
cd android
.\gradlew.bat assembleDebug
cd ..

# 安装到手机
D:\AndroidSdk\platform-tools\adb.exe install -r .\android\app\build\outputs\apk\debug\visaid-debug.apk

# 连接手机 App 到电脑后端
D:\AndroidSdk\platform-tools\adb.exe reverse tcp:8000 tcp:8000
```

## 作者与致谢

- 后端负责人：余子怡
- 前端负责人：陈海玲

感谢 DeepSeek 和智谱 AI 提供的大模型能力，也感谢参与测试和反馈的用户。