# 发型更换H5项目启动和部署文档

## 1. 项目结构

```
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  # 系统架构文档
    └── DEPLOYMENT.md    # 部署文档
```

## 2. 开发环境搭建

### 2.1 后端环境

#### 2.1.1 依赖安装
1. 确保已安装 Python 3.8+
2. 进入后端目录
   ```bash
   cd backend
   ```
3. 安装依赖
   ```bash
   pip install -r requirements.txt
   ```

#### 2.1.2 配置修改
1. 编辑 `config.py` 文件，修改以下配置：
   - `REMOTE_API_URL`：远程发型更换API地址
   - `API_TIMEOUT`：API请求超时时间

2. 编辑 `data/hairstyles.json` 文件，添加或修改发型数据：
   - 确保每个发型对象包含 `id`、`name`、`gender` 和 `image_url` 字段
   - `gender` 字段值为 `male` 或 `female`
   - `image_url` 为发型图片的OSS地址

#### 2.1.3 启动服务
```bash
python app.py
```
服务将在 `http://127.0.0.1:5000` 启动

### 2.2 前端环境

#### 2.2.1 开发模式
在开发环境中，前端文件通过后端Flask服务提供，无需单独配置。

1. 启动后端服务后，访问 `http://127.0.0.1:5000` 即可看到前端页面
2. 前端代码修改后，刷新浏览器即可看到变化

## 3. 生产环境部署

### 3.1 后端部署

#### 3.1.1 使用 Gunicorn 部署
1. 安装 Gunicorn
   ```bash
   pip install gunicorn
   ```

2. 启动服务
   ```bash
   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   ```
   - `-w 4`：使用4个worker进程
   - `-b 0.0.0.0:5000`：绑定到所有网络接口的5000端口

#### 3.1.2 使用 Nginx 作为反向代理
1. 安装 Nginx
2. 配置 Nginx 反向代理
   ```nginx
   server {
       listen 80;
       server_name example.com;

       location / {
           proxy_pass http://localhost:5000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }
   ```

### 3.2 前端部署

#### 3.2.1 静态文件部署
在生产环境中，建议将前端文件部署到 CDN 或静态文件服务器，以提高加载速度。

1. 复制前端文件到静态文件服务器
2. 修改前端 `js/main.js` 中的 API 地址，指向后端服务地址

#### 3.2.2 配置示例
修改前端 API 调用地址：
```javascript
// 修改 API 调用地址
async function getHairstyles() {
    try {
        const response = await axios.get('https://api.example.com/api/hairstyles');
        return response.data;
    } catch (error) {
        console.error('获取发型列表失败:', error);
        throw error;
    }
}

async function changeHair(imageFile, hairstyleId) {
    try {
        const formData = new FormData();
        formData.append('image', imageFile);
        formData.append('hairstyle_id', hairstyleId);
        
        const response = await axios.post('https://api.example.com/api/change-hair', formData, {
            headers: {
                'Content-Type': 'multipart/form-data'
            }
        });
        return response.data;
    } catch (error) {
        console.error('更换发型失败:', error);
        throw error;
    }
}
```

## 4. 系统配置

### 4.1 后端配置

#### 4.1.1 主要配置项
编辑 `backend/config.py` 文件：

| 配置项 | 描述 | 默认值 |
|-------|------|-------|
| APP_NAME | 应用名称 | "Hair Change Color" |
| REMOTE_API_URL | 远程发型更换API地址 | "https://api.example.com/change-hair" |
| API_TIMEOUT | API请求超时时间（秒） | 30 |
| MAX_CONTENT_LENGTH | 文件上传大小限制 | 16MB |
| ALLOWED_EXTENSIONS | 允许的文件类型 | {'png', 'jpg', 'jpeg', 'gif'} |
| DEBUG | 调试模式 | True |

#### 4.1.2 发型数据配置
编辑 `backend/data/hairstyles.json` 文件，添加或修改发型数据：

```json
{
  "hairstyles": [
    {
      "id": "hair_001",
      "name": "时尚短发",
      "gender": "male",
      "image_url": "https://oss.example.com/hairstyles/male/hair_001.jpg"
    },
    // 更多发型...
  ]
}
```

### 4.2 前端配置

#### 4.2.1 响应式设计
前端页面采用响应式设计，自动适配不同屏幕尺寸：
- 移动端：< 768px
- 平板：768px - 1024px
- PC端：> 1024px

#### 4.2.2 浏览器兼容性
支持的浏览器：
- Chrome (最新版)
- Firefox (最新版)
- Safari (最新版)
- Edge (最新版)
- 移动端浏览器

## 5. 常见问题与解决方案

### 5.1 后端服务启动失败
- **问题**：`ModuleNotFoundError: No module named 'Flask'`
  **解决方案**：运行 `pip install -r requirements.txt` 安装依赖

- **问题**：`FileNotFoundError: [Errno 2] No such file or directory: 'data/hairstyles.json'`
  **解决方案**：确保 `data` 目录存在且包含 `hairstyles.json` 文件

### 5.2 前端页面无法访问
- **问题**：后端服务未启动
  **解决方案**：运行 `python app.py` 启动后端服务

- **问题**：API 调用失败
  **解决方案**：检查浏览器控制台的网络请求，确认 API 地址是否正确

### 5.3 发型更换功能不工作
- **问题**：远程 API 调用失败
  **解决方案**：检查 `config.py` 中的 `REMOTE_API_URL` 配置是否正确

- **问题**：上传图片失败
  **解决方案**：检查图片大小是否超过限制（默认16MB），以及文件类型是否被允许

## 6. 性能优化建议

### 6.1 前端优化
- **图片压缩**：上传前压缩图片，减少传输时间
- **缓存策略**：缓存发型列表数据，减少 API 调用
- **懒加载**：实现发型图片懒加载，提高页面加载速度

### 6.2 后端优化
- **使用生产服务器**：在生产环境中使用 Gunicorn 或 uWSGI 替代开发服务器
- **启用 Gzip 压缩**：减少响应数据大小
- **增加 worker 数量**：根据服务器配置增加 Gunicorn worker 数量

## 7. 安全建议

### 7.1 前端安全
- **使用 HTTPS**：在生产环境中使用 HTTPS 协议
- **验证文件类型**：前端验证上传文件类型，防止恶意文件

### 7.2 后端安全
- **配置 CORS**：正确配置跨域资源共享，只允许指定域名访问
- **限制文件大小**：设置合理的文件上传大小限制
- **API 限流**：对发型更换接口实施限流，防止滥用
- **验证请求参数**：验证所有请求参数，防止注入攻击

## 8. 监控与维护

### 8.1 日志管理
- **Flask 日志**：后端服务日志默认输出到控制台
- **访问日志**：使用 Nginx 等反向代理时，配置访问日志记录

### 8.2 健康检查
- **API 健康检查**：定期检查 `/api/hairstyles` 接口是否正常响应
- **服务状态监控**：监控后端服务运行状态，确保服务稳定

## 9. 部署流程总结

1. **准备环境**：
   - 安装 Python 3.8+
   - 安装依赖：`pip install -r backend/requirements.txt`

2. **配置项目**：
   - 修改 `backend/config.py` 中的远程 API 地址
   - 编辑 `backend/data/hairstyles.json` 添加发型数据

3. **启动服务**：
   - 开发环境：`python backend/app.py`
   - 生产环境：使用 Gunicorn 或 uWSGI 启动

4. **访问应用**：
   - 开发环境：`http://127.0.0.1:5000`
   - 生产环境：配置域名后访问

5. **维护更新**：
   - 更新发型数据：修改 `hairstyles.json` 文件
   - 更新代码：部署新代码后重启服务

## 10. 故障排除

### 10.1 服务无法启动
- 检查端口是否被占用
- 检查依赖是否安装完整
- 检查配置文件是否正确

### 10.2 API 调用失败
- 检查网络连接
- 检查远程 API 服务是否可用
- 检查 API 地址配置是否正确

### 10.3 前端页面异常
- 清除浏览器缓存
- 检查浏览器控制台错误信息
- 验证 API 响应数据格式