# 发型更换H5项目系统架构文档

## 1. 技术选型

### 1.1 前端技术栈
- **HTML5**：提供基础页面结构和语义化标签
- **CSS3**：实现响应式布局和动画效果
- **JavaScript (ES6+)**：实现前端交互逻辑
- **Axios**：处理HTTP请求，与后端API通信
- **FileReader API**：处理本地图片读取和预览
- **MediaDevices API**：支持移动端拍照功能
- **LocalStorage**：存储临时数据，如用户选择的发型ID

### 1.2 后端技术栈
- **Python 3.8+**：核心后端语言
- **Flask**：轻量级Web框架，用于构建API服务
- **Flask-CORS**：处理跨域请求
- **Requests**：调用远程HTTP接口进行发型更换处理
- **JSON**：数据交换格式
- **文件系统**：存储发型数据和配置信息

### 1.3 第三方服务
- **OSS**：存储发型图片，提供CDN加速
- **远程发型更换API**：处理实际的发型更换算法

## 2. 系统架构

### 2.1 架构概述
本项目采用前后端分离的架构模式，前端通过HTTP请求与后端API进行通信。后端作为中间层，负责管理发型数据和调用远程API处理发型更换请求。

```mermaid
sequenceDiagram
    participant Client as 前端H5
    participant Server as 后端服务
    participant OSS as OSS存储
    participant RemoteAPI as 远程发型更换API

    Client->>Server: GET /api/hairstyles
    Server->>Server: 读取发型配置文件
    Server-->>Client: 返回发型列表（包含OSS URL）
    
    Client->>Client: 用户选择图片和发型
    Client->>Server: POST /api/change-hair (图片数据, 发型ID)
    Server->>RemoteAPI: 调用远程API处理图片
    RemoteAPI-->>Server: 返回处理后的图片
    Server-->>Client: 返回发型更换结果
```

### 2.2 目录结构

```
hair_change_color/
├── backend/             # 后端Python服务
│   ├── app.py           # Flask应用主文件
│   ├── config.py        # 配置文件
│   ├── data/            # 数据目录
│   │   └── hairstyles.json  # 发型数据配置
│   └── requirements.txt # Python依赖
├── frontend/            # 前端H5
│   ├── index.html       # 首页
│   ├── css/             # CSS文件
│   │   └── style.css    # 主样式文件
│   ├── js/              # JavaScript文件
│   │   ├── main.js      # 主逻辑
│   │   └── api.js       # API调用封装
│   └── images/          # 前端静态图片
└── docs/                # 文档
    ├── PRD.md           # 产品需求文档
    └── ARCHITECTURE.md  # 系统架构文档
```

## 3. 核心模块设计

### 3.1 前端模块

#### 3.1.1 图片上传模块
- **功能**：支持用户上传本地图片或拍摄照片
- **实现**：
  - 使用`<input type="file">`实现本地图片选择
  - 使用`navigator.mediaDevices.getUserMedia()`实现摄像头拍摄
  - 使用`FileReader` API读取图片并生成预览

#### 3.1.2 发型选择模块
- **功能**：展示发型分类和列表，支持用户选择发型
- **实现**：
  - 从后端API获取发型列表
  - 按性别分类展示发型
  - 实现发型预览和选择逻辑

#### 3.1.3 结果展示模块
- **功能**：展示发型更换后的效果
- **实现**：
  - 接收后端返回的处理结果
  - 实现原图与效果图的对比展示
  - 提供保存和分享功能

### 3.2 后端模块

#### 3.2.1 发型管理模块
- **功能**：管理发型数据，提供发型列表API
- **实现**：
  - 从JSON配置文件读取发型数据
  - 启动时加载到内存
  - 提供GET /api/hairstyles接口返回发型列表

#### 3.2.2 图片处理模块
- **功能**：接收用户上传的图片，调用远程API处理
- **实现**：
  - 接收POST /api/change-hair请求
  - 解析图片数据和发型ID
  - 调用远程HTTP接口处理图片
  - 返回处理结果

#### 3.2.3 配置管理模块
- **功能**：管理应用配置，如远程API地址、OSS配置等
- **实现**：
  - 从config.py读取配置
  - 提供配置访问接口

## 4. 数据库设计

### 4.1 数据存储方案
本项目不使用传统数据库，而是采用文件系统存储数据：
- **发型数据**：存储在`backend/data/hairstyles.json`文件中
- **配置数据**：存储在`backend/config.py`文件中
- **临时文件**：使用内存存储，不持久化

### 4.2 发型数据结构

```json
{
  "hairstyles": [
    {
      "id": "hair_001",
      "name": "时尚短发",
      "gender": "male",
      "image_url": "https://oss.example.com/hairstyles/male/hair_001.jpg"
    },
    {
      "id": "hair_002",
      "name": "优雅长发",
      "gender": "female",
      "image_url": "https://oss.example.com/hairstyles/female/hair_002.jpg"
    }
  ]
}
```

## 5. API 接口设计

### 5.1 前端API调用

#### 5.1.1 获取发型列表
- **接口**：GET /api/hairstyles
- **参数**：无
- **返回**：
  ```json
  {
    "success": true,
    "data": {
      "male": [
        {
          "id": "hair_001",
          "name": "时尚短发",
          "image_url": "https://oss.example.com/hairstyles/male/hair_001.jpg"
        }
      ],
      "female": [
        {
          "id": "hair_002",
          "name": "优雅长发",
          "image_url": "https://oss.example.com/hairstyles/female/hair_002.jpg"
        }
      ]
    }
  }
  ```

#### 5.1.2 更换发型
- **接口**：POST /api/change-hair
- **参数**：
  - image: 图片文件（FormData）
  - hairstyle_id: 发型ID（字符串）
- **返回**：
  ```json
  {
    "success": true,
    "data": {
      "result_image": "data:image/jpeg;base64,..."
    }
  }
  ```

### 5.2 后端API实现

#### 5.2.1 Flask路由
- `/api/hairstyles`：处理获取发型列表请求
- `/api/change-hair`：处理发型更换请求
- `/`：提供前端静态文件（开发环境）

## 6. 部署与集成方案

### 6.1 开发环境
- **前端**：直接在浏览器中打开`frontend/index.html`
- **后端**：使用Flask开发服务器，运行`python backend/app.py`

### 6.2 生产环境
- **前端**：将前端文件部署到CDN或静态文件服务器
- **后端**：使用Gunicorn或uWSGI部署Flask应用
- **集成**：前端通过配置的API地址与后端通信

### 6.3 依赖管理
- **前端**：通过CDN引入Axios
- **后端**：使用pip管理依赖，依赖项记录在`requirements.txt`中

## 7. 性能与安全考虑

### 7.1 性能优化
- **图片处理**：前端压缩上传图片，减少传输时间
- **缓存策略**：缓存发型列表数据，减少API调用
- **响应式设计**：针对不同设备优化加载速度

### 7.2 安全考虑
- **CORS配置**：正确配置跨域资源共享，只允许指定域名访问
- **文件验证**：后端验证上传文件类型和大小，防止恶意文件
- **API限流**：对发型更换接口实施限流，防止滥用
- **数据加密**：传输敏感数据时使用HTTPS

## 8. 扩展性设计

### 8.1 功能扩展
- **支持更多发型分类**：通过修改配置文件即可添加新分类
- **增加滤镜效果**：在发型更换基础上添加滤镜功能
- **支持视频处理**：扩展为支持视频中的发型更换

### 8.2 技术扩展
- **支持WebSocket**：实现实时预览功能
- **添加用户系统**：支持保存用户历史记录和偏好设置
- **接入更多AI能力**：如人脸识别、风格推荐等