# Co-location MVP Web 界面使用说明

## 概述

本项目新增了基于 FastAPI + Web 前端的交互式界面，支持：

- 🌐 Web 查询 co-location 模式
- 📊 可视化展示挖掘结果 + LLM 解释
- 👍👎 用户点击反馈（喜欢 / 不喜欢）
- 🎯 在线训练 PreferenceEncoder
- 📈 实时绘制训练 Loss 曲线
- ⚙️ 支持修改训练参数

## 安装依赖

```bash
pip install -r requirements.txt
```

主要新增依赖：
- `fastapi>=0.104.0`
- `uvicorn[standard]>=0.24.0`
- `pydantic>=2.0.0`
- `python-multipart>=0.0.6`
- `aiofiles>=23.0.0`

## 启动 Web 服务

请在**项目根目录**（colocation_mvp/）下执行以下命令。

### 方式 1：使用 main.py（推荐）

```bash
python main.py --web
```

main.py 会自动将 `src` 加入 Python 路径，无需额外配置。

### 方式 2：直接使用 uvicorn

```bash
PYTHONPATH=src uvicorn web.app:app --host 0.0.0.0 --port 8000 --reload
```

### 自定义端口和主机

```bash
python main.py --web --host 127.0.0.1 --port 8080
```

## 访问界面

启动服务后，在浏览器中访问：

```
http://localhost:8000
```

## API 接口

### 1. 查询接口

**POST** `/api/query`

请求体：
```json
{
  "query": "找出所有3阶模式，参与率大于0.6"
}
```

响应：
```json
{
  "params": {
    "min_participation": 0.6,
    "max_pattern_size": 3,
    "priority": "size"
  },
  "patterns": [...],
  "rules": [...],
  "explanation": "...",
  "pattern_count": 10,
  "rule_count": 5,
  "re_ranked": true,
  "similarity_scores": {...}
}
```

### 2. 反馈接口

**POST** `/api/feedback`

请求体：
```json
{
  "pattern_id": 0,
  "pattern": ["Park", "Museum"],
  "feedback": "positive"
}
```

响应：
```json
{
  "status": "ok",
  "message": "Feedback saved: positive",
  "positive_count": 5,
  "negative_count": 2
}
```

### 3. 训练接口

**POST** `/api/train`

请求体：
```json
{
  "epochs": 10,
  "learning_rate": 0.001,
  "batch_size": 32,
  "margin": 0.3
}
```

响应：
```json
{
  "status": "ok",
  "message": "Training completed successfully",
  "loss_history": [0.8, 0.6, 0.4, ...],
  "epochs": 10
}
```

### 4. 训练历史接口

**GET** `/api/train/history`

响应：
```json
{
  "trainings": [
    {
      "time": "2024-01-01 12:00:00",
      "feedback_count": 10,
      "epochs": 10,
      "loss_history": [...]
    }
  ]
}
```

## 使用流程

### 完整闭环流程

1. **查询模式**
   - 在查询框输入自然语言查询
   - 点击"搜索"按钮
   - 查看挖掘结果

2. **提供反馈**
   - 在模式列表中点击 👍（喜欢）或 👎（不喜欢）
   - 反馈会自动保存到项目根目录下的 `memory/user_memory.json`

3. **训练模型**
   - 调整训练参数（轮数、学习率等）
   - 点击"开始训练"按钮
   - 查看 Loss 曲线变化

4. **重新查询**
   - 训练后的模型会自动用于下次查询的排序优化
   - 结果会根据您的偏好重新排序

## 目录结构

Web 界面相关代码与资源统一放在 **`src/web/`** 下，便于整体维护：

```
colocation_mvp/
├── src/
│   └── web/                    # Web 模块（后端 + 前端 + 静态资源）
│       ├── __init__.py
│       ├── app.py              # FastAPI 主入口
│       ├── router.py           # API 路由
│       ├── schemas.py          # Pydantic 数据模型
│       ├── services.py        # 业务逻辑封装
│       ├── frontend/           # 前端页面
│       │   └── index.html      # 主页面
│       └── static/             # 静态资源
│           ├── css/
│           │   └── style.css   # 样式文件
│           └── js/
│               └── main.js     # 前端逻辑
│
├── main.py                     # 主入口（python main.py --web）
├── config/                     # 配置文件
├── memory/                     # 反馈与用户向量（运行后自动创建）
├── models/                     # 训练模型（运行后自动创建）
└── logs/                       # 日志（运行后自动创建）
```

## 功能特性

### 1. 查询区
- 自然语言输入框
- 支持回车键快速查询
- 实时状态提示

### 2. 结果展示区
- **参数显示**：显示提取的挖掘参数
- **模式列表**：表格展示所有发现的模式
  - 模式内容
  - 参与率
  - 置信度
  - 相似度（如果启用 Stage3）
  - 反馈按钮
- **关联规则**：显示从模式生成的关联规则
- **LLM 解释**：显示对结果的自然语言解释

### 3. 训练控制区
- **参数配置**：
  - 训练轮数 (Epochs)
  - 学习率 (Learning Rate)
  - 批次大小 (Batch Size)
  - 边距 (Margin)
- **训练按钮**：启动模型训练
- **历史加载**：加载之前的训练记录
- **Loss 曲线**：使用 Chart.js 实时显示训练损失

## 注意事项

1. **运行目录**：请在项目根目录 `colocation_mvp/` 下执行 `python main.py --web`，配置与数据路径均相对于根目录。
2. **Stage3 配置**：确保 `config/config.yaml` 中 `stage3.enabled` 为 `true`。
3. **反馈数据**：需要至少有一些正反馈和负反馈才能进行训练。
4. **模型文件**：训练后的模型保存在根目录 `models/preference_encoder.pth`。
5. **训练历史**：训练历史保存在根目录 `logs/training_history.json`。

## 故障排除

### 问题：无法启动 Web 服务

**解决方案**：
- 检查是否安装了所有依赖：`pip install -r requirements.txt`
- 检查端口是否被占用：`lsof -i :8000`

### 问题：训练失败

**解决方案**：
- 确保有足够的反馈数据（至少需要正反馈和负反馈）
- 检查 Stage3 是否启用：`config/config.yaml` 中 `stage3.enabled: true`
- 检查是否启用了对比学习：`stage3.use_contrastive: true`

### 问题：前端无法加载

**解决方案**：
- 检查 `src/web/frontend/` 和 `src/web/static/` 目录是否存在
- 检查浏览器控制台是否有错误信息
- 确保 FastAPI 正确挂载了静态文件目录（/static）

## 开发说明

### 修改前端样式

编辑 `src/web/static/css/style.css`。

### 修改前端逻辑

编辑 `src/web/static/js/main.js`（前端入口为 `src/web/frontend/index.html`）。

### 添加新的 API 接口

1. 在 `src/web/schemas.py` 中添加请求/响应模型
2. 在 `src/web/services.py` 中添加业务逻辑
3. 在 `src/web/router.py` 中添加路由

## 论文应用

这个 Web 系统支持论文中描述以下创新点：

- ✅ **Human-in-the-loop**：用户参与反馈循环
- ✅ **Interactive Mining**：交互式模式挖掘
- ✅ **Preference Learning**：基于反馈的偏好学习
- ✅ **Online Learning**：在线增量学习
- ✅ **Visual Analytics**：可视化分析

## 后续扩展方向

- 多用户支持（user_id 管理）
- 权限管理（JWT 认证）
- 自动训练（达到阈值自动触发）
- 实时更新（WebSocket）
- 高级可视化（D3.js）