Doc repo introduction 15436609161273575530

REPO_INTRODUCTION.md

@@ -0,0 +1,121 @@
+# 详细仓库介绍与使用说明
+
+本文档将深入介绍本仓库的内容、工作原理、硬件接口定义以及功能切换方法。
+
+## 1. 仓库内容概览
+
+本仓库是一个 AI 智能盲人眼镜系统的完整实现，包含：
+- **ESP32 固件** (`compile/`): 负责音视频采集、IMU 数据传输以及音频播放。
+- **Python 后端服务** (`app_main.py` 等): 负责核心 AI 逻辑处理，包括物体检测、盲道分割、语音识别与合成等。
+- **Web 监控界面** (`templates/`, `static/`): 提供实时视频流预览与调试功能。
+- **模型文件** (`model/`): 存放 YOLO、MediaPipe 等预训练模型。
+
+详细的文件结构说明请参考 `PROJECT_STRUCTURE.md`。
+
+## 2. 系统工作原理
+
+系统采用 **端云协同** (Edge-Cloud Collaboration) 架构：
+
+1.  **感知层 (ESP32)**:
+    -   **视频采集**: ESP32-CAM 通过 WebSocket (`/ws/camera`) 实时推送 JPEG 图像流。
+    -   **音频采集**: 通过 PDM 麦克风采集音频，经 WebSocket (`/ws_audio`) 上传至服务器。
+    -   **姿态感知**: 通过 SPI 接口读取 ICM42688 IMU 数据，经 UDP 发送至服务器。
+    -   **音频播放**: 接收服务器生成的音频流，通过 I2S 接口驱动扬声器播放。
+
+2.  **计算层 (Python Server)**:
+    -   **主控服务 (`app_main.py`)**: 基于 FastAPI 构建，负责 WebSocket 连接管理与任务分发。
+    -   **语音交互 (`asr_core.py`, `omni_client.py`)**: 使用阿里云 DashScope 进行语音识别 (ASR) 与大模型对话 (Qwen-Omni)。
+    -   **视觉导航 (`workflow_*.py`)**:
+        -   **盲道导航**: 使用 YOLO 分割模型识别盲道区域，结合光流算法进行稳像，计算行走方向。
+        -   **过马路辅助**: 识别斑马线与红绿灯，引导用户安全通过。
+        -   **物品查找**: 结合 YOLO-E 开放词汇检测与 MediaPipe 手部追踪，引导用户抓取物品。
+    -   **状态管理 (`navigation_master.py`)**: 维护系统全局状态机，根据用户语音指令切换不同模式。
+
+3.  **交互层**:
+    -   **语音反馈**: 系统通过 TTS (文本转语音) 或大模型直接生成语音，指导用户行动。
+    -   **Web 界面**: 开发者可通过浏览器实时查看摄像头画面、识别结果与系统状态。
+
+## 3. 硬件接口定义 (Pinout)
+
+本系统默认支持 **Seeed Studio XIAO ESP32S3** 开发板。引脚定义如下（基于 `compile/compile.ino` 和 `compile/camera_pins.h`）：
+
+### 3.1 摄像头接口 (DVP)
+| 信号 | GPIO (XIAO ESP32S3) | 描述 |
+| :--- | :--- | :--- |
+| PWDN | -1 | 断电控制 (未使用) |
+| RESET| -1 | 复位控制 (未使用) |
+| XCLK | 10 | 外部时钟 |
+| SIOD | 40 | SCCB 数据 (I2C SDA) |
+| SIOC | 39 | SCCB 时钟 (I2C SCL) |
+| Y9   | 48 | 数据位 9 |
+| Y8   | 11 | 数据位 8 |
+| Y7   | 12 | 数据位 7 |
+| Y6   | 14 | 数据位 6 |
+| Y5   | 16 | 数据位 5 |
+| Y4   | 18 | 数据位 4 |
+| Y3   | 17 | 数据位 3 |
+| Y2   | 15 | 数据位 2 |
+| VSYNC| 38 | 垂直同步 |
+| HREF | 47 | 水平参考 |
+| PCLK | 13 | 像素时钟 |
+
+### 3.2 麦克风接口 (PDM RX)
+| 信号 | GPIO | 描述 |
+| :--- | :--- | :--- |
+| CLK  | 42 | PDM 时钟 |
+| DAT  | 41 | PDM 数据 |
+
+### 3.3 扬声器接口 (I2S TX -> MAX98357A)
+| 信号 | GPIO | 描述 |
+| :--- | :--- | :--- |
+| BCLK | 7 | 位时钟 |
+| LRCK | 8 | 左右声道时钟 |
+| DIN  | 9 | 数据输入 |
+
+### 3.4 IMU 接口 (SPI -> ICM42688)
+| 信号 | GPIO | 描述 |
+| :--- | :--- | :--- |
+| SCK  | 1 (D0) | SPI 时钟 |
+| MOSI | 2 (D1) | 主出从入 |
+| MISO | 3 (D2) | 主入从出 |
+| CS   | 4 (D3) | 片选信号 |
+
+> **注意**: 如果使用其他 ESP32 开发板（如 AI-Thinker），请参考 `compile/camera_pins.h` 修改引脚定义。
+
+## 4. 功能切换方法
+
+系统主要通过 **语音指令** 进行功能切换。由于没有物理按键进行模式选择，用户需要直接说出特定关键词来触发相应功能。
+
+### 4.1 核心状态机 (`NavigationMaster`)
+系统通过 `navigation_master.py` 中的状态机管理当前模式。主要状态包括：
+- `IDLE`: 空闲状态（默认）
+- `CHAT`: 智能对话模式
+- `BLINDPATH_NAV`: 盲道导航模式
+- `CROSSING`: 过马路模式
+- `ITEM_SEARCH`: 物品查找模式
+- `TRAFFIC_LIGHT_DETECTION`: 红绿灯检测模式
+
+### 4.2 语音指令列表
+
+用户说话时无需唤醒词，直接说出以下指令即可切换功能：
+
+| 功能模式 | 触发指令 (关键词) | 描述 |
+| :--- | :--- | :--- |
+| **盲道导航** | "开始导航", "盲道导航" | 启动盲道识别与行走引导 |
+| | "停止导航", "结束导航" | 退出盲道导航，返回空闲状态 |
+| **过马路辅助** | "开始过马路", "帮我过马路" | 启动斑马线识别与过街引导 |
+| | "过马路结束", "结束过马路" | 退出过马路模式 |
+| **红绿灯检测** | "检测红绿灯", "看红绿灯" | 启动红绿灯识别与播报 |
+| | "停止检测", "停止红绿灯" | 停止红绿灯检测 |
+| **物品查找** | "帮我找一下 [物品名]" | 例如 "帮我找一下红牛"，启动物品搜索 |
+| | "找到了", "拿到了" | 确认物品已找到，退出查找模式 |
+| **智能对话** | "帮我看看这是什么" | 拍摄当前画面并进行 AI 识别描述 |
+| | (其他自然语言问题) | 进行常规 AI 对话 |
+
+### 4.3 自动状态流转
+除了语音指令外，部分功能会自动流转状态：
+- 在 **盲道导航** 中，如果检测到路口或斑马线，系统可能会自动提示或辅助切换。
+- 在 **过马路** 模式下，系统会自动经历 "寻找斑马线" -> "等待绿灯" -> "过马路" -> "寻找对面盲道" 的流程。
+
+---
+希望这份文档能帮助您更好地理解与使用本仓库！如有疑问，请查阅 `README.md` 或提 Issue 交流。

ineedyou/full_stack_web/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Node
+node_modules/
+dist/
+.env.local
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Docker
+.dockerignore

ineedyou/full_stack_web/ARCHITECTURE.md

@@ -0,0 +1,106 @@
+# AI Glass Full Stack Web System 架构与文件功能说明
+
+本文件详细说明 `ineedyou/full_stack_web` 文件夹中各个文件与目录的具体功能与职责。
+
+## 目录结构概览
+
+```text
+ineedyou/full_stack_web/
+├── docker-compose.yml     # Docker 编排配置，一键启动整个系统的核心文件
+├── README.md              # 简要使用说明与启动指南
+├── ARCHITECTURE.md        # 本文件，详细的架构与文件功能说明
+├── backend/               # 后端目录 (Django + Django REST Framework)
+└── frontend/              # 前端目录 (React + Vite + Material UI)
+```
+
+---
+
+## 1. 后端 (Backend - Django)
+
+后端主要负责处理业务逻辑、数据库交互以及提供前端所需的 RESTful API。
+
+*   **`backend/Dockerfile`**
+    *   **功能**: 定义后端容器的构建过程。
+    *   **行为**: 基于 Python 3.9，安装 `requirements.txt` 中的依赖，并设置执行 `entrypoint.sh` 脚本作为启动入口。
+*   **`backend/requirements.txt`**
+    *   **功能**: 列出后端项目所需的所有 Python 第三方库（如 django, djangorestframework, psycopg2 等）。
+*   **`backend/manage.py`**
+    *   **功能**: Django 项目的标准命令行工具，用于执行数据库迁移、运行开发服务器、创建应用等。
+*   **`backend/entrypoint.sh`**
+    *   **功能**: 后端容器的启动脚本。
+    *   **行为**:
+        1. 轮询等待 PostgreSQL 数据库启动就绪。
+        2. 自动执行数据库迁移 (`makemigrations` 和 `migrate`)。
+        3. **自动创建默认的系统管理员 (`admin`) 和普通用户 (`user1`)，并重置他们的密码确保可登录，同时为他们生成 API Token。**
+        4. 启动 Django 服务。
+
+### 后端子模块 (Apps)
+
+#### `backend/config/` (主配置)
+*   **`settings.py`**: Django 核心配置文件，包含数据库连接信息 (读取 Docker 环境变量)、跨域设置 (CORS)、已安装的 App 列表等。
+*   **`urls.py`**: 主路由文件，将 API 请求分发到 `users` 和 `devices` 模块，并配置了 Swagger API 接口文档路由。
+*   **`wsgi.py` / `asgi.py`**: Web 服务器网关接口，用于生产环境部署。
+
+#### `backend/users/` (用户与认证)
+*   **`models.py`**: 继承了 Django 的默认 User 模型，用于区分管理员 (Admin) 和普通用户。
+*   **`views.py`**: 提供登录接口 (`CustomAuthToken`)，验证账号密码并返回 Token；提供用户信息获取接口 (`UserInfoView`)。
+*   **`urls.py`**: 定义认证相关的路由（如 `/api/auth/login/`）。
+
+#### `backend/devices/` (设备与日志管理)
+*   **`models.py`**:
+    *   `Device`: 定义 AI 眼镜设备的数据结构（设备ID、名称、所属用户、在线状态等）。
+    *   `DeviceLog`: 定义设备上传的日志结构（时间戳、日志级别、OCR文本等记录）。
+*   **`serializers.py`**: 数据序列化器，负责将 Django 模型对象与 JSON 数据相互转换，供 API 使用。
+*   **`views.py`**: 提供设备与日志的增删改查 API 接口。内置权限控制：管理员可查看所有数据，普通用户只能查看绑定到自己账号的设备与日志。
+*   **`urls.py`**: 定义设备管理的路由（如 `/api/devices/` 和 `/api/logs/`）。
+
+---
+
+## 2. 前端 (Frontend - React)
+
+前端主要负责与用户进行交互，展示数据并调用后端 API。
+
+*   **`frontend/Dockerfile`**
+    *   **功能**: 定义前端容器的多阶段构建过程。
+    *   **行为**: 第一阶段使用 Node.js 编译 React TypeScript 代码；第二阶段将编译好的静态文件放入 Nginx 服务器中进行部署。
+*   **`frontend/nginx.conf`**
+    *   **功能**: Nginx 配置文件，用于处理单页应用 (SPA) 的路由回退机制，确保在直接访问子路由时不会报 404 错误。
+*   **`frontend/package.json` / `package-lock.json`**
+    *   **功能**: Node.js 项目配置文件，定义了项目依赖（React, Material UI, Axios 等）以及打包脚本 (`npm run build`)。
+*   **`frontend/vite.config.ts`**
+    *   **功能**: Vite 构建工具的配置文件，提供极速的冷启动和热更新功能。
+*   **`frontend/tsconfig.json` / `tsconfig.node.json`**
+    *   **功能**: TypeScript 编译器的配置文件，确保代码的类型安全。
+
+### 前端源码 (`frontend/src/`)
+
+*   **`main.tsx`**
+    *   **功能**: React 应用的入口文件。
+    *   **行为**: 挂载根组件，并全局注入 Material UI 的暗色主题 (Dark Theme)。
+*   **`App.tsx`**
+    *   **功能**: 主组件，负责整个前端的路由配置 (React Router)。
+    *   **行为**: 定义了 `/login` 和 `/` (Dashboard) 路由，并通过 `PrivateRoute` 保护需要登录的页面。
+*   **`context/AuthContext.tsx`**
+    *   **功能**: 全局状态管理 (React Context)。
+    *   **行为**: 管理用户的登录状态、存储 Token、从后端拉取用户信息，并提供全局可用的 `login` 和 `logout` 函数。
+
+### 前端页面 (`frontend/src/pages/`)
+
+*   **`Login.tsx`**
+    *   **功能**: 用户登录页面。
+    *   **行为**: 渲染登录表单，收集用户名和密码，调用 `AuthContext` 的 `login` 方法向后端发起请求。如果失败会显示 "Invalid credentials"。
+*   **`Dashboard.tsx`**
+    *   **功能**: 主控制台页面。
+    *   **行为**: 登录成功后跳转至此。根据用户角色 (Admin 或 User) 展示不同的欢迎语。向后端请求 `/api/devices/` 和 `/api/logs/` 接口，并将获取到的设备列表和操作日志渲染到 Material UI 的数据表格中。
+
+---
+
+## 3. 部署与运行 (Docker Compose)
+
+*   **`docker-compose.yml`**
+    *   **功能**: 容器编排文件，负责将上述前后端及数据库串联起来。
+    *   **定义了三个服务**:
+        1.  **`db`**: 运行 PostgreSQL 15 数据库。将数据持久化挂载到 `postgres_data` volume 中，防止重启数据丢失。
+        2.  **`backend`**: 构建后端镜像并运行。暴露 `8000` 端口，连接到 `db` 服务，并注入连接数据库所需的账号密码环境变量。
+        3.  **`frontend`**: 构建前端 Nginx 镜像并运行。暴露 `3000` 端口供浏览器访问。
+    *   **依赖关系**: `frontend` 等待 `backend` 启动，`backend` 等待 `db` 就绪 (`healthcheck`)。实现了一条命令稳定启动。

ineedyou/full_stack_web/README.md

@@ -0,0 +1,75 @@
+# AI Glass Full Stack Web System
+
+This is a comprehensive full-stack system designed to manage the AI Glass devices, users, and logs. It uses:
+
+-   **Backend**: Django (Python) + Django REST Framework.
+-   **Frontend**: React (JavaScript/TypeScript) + Material UI.
+-   **Database**: PostgreSQL.
+-   **Deployment**: Docker Compose.
+
+## How to Run
+
+1.  **Navigate to the folder**:
+    ```bash
+    cd ineedyou/full_stack_web
+    ```
+
+2.  **Start the services**:
+    ```bash
+    docker-compose up -d --build
+    ```
+    This command will build the backend and frontend images, start the PostgreSQL database, and bring up the entire stack.
+
+3.  **Access the System**:
+    -   **Frontend (Dashboard)**: Open your browser and go to `http://localhost:3000`
+    -   **Backend API**: `http://localhost:8000/api/` (Browsable API)
+    -   **Admin Panel**: `http://localhost:8000/admin/`
+
+## Windows Troubleshooting
+
+If you encounter an error like:
+> `open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.`
+
+This means Docker Desktop is not running or not properly configured.
+
+1.  **Start Docker Desktop**: Ensure the Docker Desktop application is open and running in the background. The whale icon should be visible in your system tray.
+2.  **Wait for Engine Startup**: It may take a minute for the Docker engine to fully initialize.
+3.  **WSL2 Integration**: If using WSL2, go to Docker Desktop Settings -> Resources -> WSL Integration, and ensure your Linux distribution (e.g., Ubuntu) is checked.
+
+## Default Credentials
+
+### Superuser (Admin)
+-   **Username**: `admin`
+-   **Password**: `admin123`
+-   **Email**: `admin@example.com`
+
+### Regular User
+-   **Username**: `user1`
+-   **Password**: `user123`
+-   **Email**: `user1@example.com`
+
+## Features
+
+-   **User Authentication**: Login/Register/Logout using JWT tokens.
+-   **Role-Based Access**:
+    -   **Admin**: Can manage all users, view all device logs, and configure system settings.
+    -   **User**: Can view their own device status, logs, and update profile.
+-   **Device Management**: Register and monitor AI Glass devices.
+-   **Log Viewer**: Historical data of OCR scans, navigation events, and errors.
+
+## Development
+
+-   **Backend**: Located in `backend/`. Uses Django.
+-   **Frontend**: Located in `frontend/`. Uses React (create-react-app or Vite).
+-   **Database**: Data is persisted in a Docker volume `postgres_data`.
+
+## Stopping the System
+
+To stop the containers:
+```bash
+docker-compose down
+```
+To stop and remove volumes (reset database):
+```bash
+docker-compose down -v
+```

ineedyou/full_stack_web/backend/.gitattributes

@@ -0,0 +1,2 @@
+# Force bash scripts to always use LF line endings, even on Windows
+*.sh text eol=lf

ineedyou/full_stack_web/backend/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.9-slim
+
+ENV PYTHONDONTWRITEBYTECODE 1
+ENV PYTHONUNBUFFERED 1
+
+WORKDIR /app
+
+# Install netcat and dos2unix
+RUN apt-get update && apt-get install -y netcat-traditional dos2unix && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/
+RUN pip install --upgrade pip && \
+    pip install -r requirements.txt
+
+COPY . /app/
+
+# Convert line endings of entrypoint.sh to LF (Unix format) to fix Windows execution issues
+RUN dos2unix /app/entrypoint.sh && chmod +x /app/entrypoint.sh
+
+# Use entrypoint script to handle migrations and user creation
+ENTRYPOINT ["/app/entrypoint.sh"]

ineedyou/full_stack_web/backend/config/asgi.py

@@ -0,0 +1,16 @@
+"""
+ASGI config for config project.
+
+It exposes the ASGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/4.2/howto/deployment/asgi/
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
+
+application = get_asgi_application()