# BRAIN 表达式模板解码器 - Flask Web 应用程序

一个全面的 Flask Web 应用程序，用于解码字符串模板，具备语法检查、语法高亮显示，并与 WorldQuant BRAIN 平台无缝集成以获取真实操作员数据。

## 🚀 功能

### 核心功能
- **模板检测**：自动检测表达式中的 `<template_name/>` 模式
- **语法检查**：实时验证分号、注释和语法
- **语法高亮**：带行号和自动完成的颜色编码显示
- **模板解码**：生成表达式的两种模式
  - **完全迭代**：生成所有可能的模板变量组合
  - **随机迭代**：生成指定大小的随机样本
- **导出选项**：复制结果或下载为文本文件

### 模板类型
- **Op（操作符）** - 蓝色按钮，与 BRAIN 操作符集成
- **Data（数据字段）** - 绿色按钮，用于数据字段配置  
- **Normal（参数）** - 灰色按钮，用于一般参数

### BRAIN 集成
- **内置 API 集成**：直接连接到 WorldQuant BRAIN API，支持 CORS
- **186+ 操作符**：访问所有操作符类别（算术、排名、减少、时间序列等）
- **800+ 数据字段**：来自基础数据集，支持搜索和过滤
- **高级搜索**：按类别过滤操作符并按名称搜索
- **多选界面**：专业的操作符选择，带视觉反馈

## 🛠️ 设置与安装

### 先决条件
- Python 3.7 或更高版本
- pip（Python 包管理器）
- WorldQuant BRAIN 账户（用于 BRAIN 集成功能）

### 快速开始

1. **克隆或下载**此代码库到本地机器

2. **运行应用程序**（依赖项将自动安装！）:

   **在 Windows 上：**
   ```bash
   # 双击 run_app.bat 或在终端运行：
   run_app.bat
   ```

   **在 macOS/Linux 上：**
   ```bash
   # 首次使脚本可执行：
   chmod +x run_app.sh
   
   # 运行应用程序：
   ./run_app.sh
   ```

   **或直接用 Python 运行：**
   ```bash
   python app.py
   ```

3. **自动依赖安装**：
   - 应用程序将自动检查缺失的依赖项
   - 如果缺少任何软件包，将从 requirements.txt 安装
   - **对于中国用户**：依赖项将从清华大学镜像自动下载，以加快安装速度
   - 无需手动安装！

4. **打开应用程序**：
   - Flask 服务器在 `http://localhost:5000` 启动
   - 打开您的网络浏览器并导航到 `http://localhost:5000`
   - 一切都已集成 - 无需单独的代理服务器！

### 对于中国用户

该应用程序自动使用清华大学的 PyPI 镜像进行更快的下载。如果您希望手动安装依赖项：

**Windows：**
```bash
# 使用清华镜像的安装脚本
setup_tsinghua.bat
```

**macOS/Linux：**
```bash
# 使可执行并运行
chmod +x setup_tsinghua.sh
./setup_tsinghua.sh
```

**使用清华镜像的手动安装：**
```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
```

**配置其他镜像：**
您可以通过编辑 `mirror_config.txt` 更改镜像源。该文件包括几个流行的中国镜像：
- 清华大学 - 默认
- 阿里云
- 豆瓣
- 中国科学技术大学

### 手动安装

如果自动安装失败，您可以手动安装：

```bash
# 从 requirements.txt 安装依赖项
pip install -r requirements.txt

# 或单独安装软件包
pip install flask==2.3.3 flask-cors==4.0.0 requests==2.31.0 pandas==2.0.3

# 启动应用程序
python app.py
```

**注意**：该应用程序包括自动依赖检查，当您运行它时将尝试安装缺失的软件包。

## 🔗 BRAIN 集成

### 设置
1. **无需单独设置** - BRAIN API 集成已内置于 Flask 应用程序中
2. **连接到 BRAIN**：点击网页界面中的“连接到 BRAIN”按钮
3. **输入凭据**：使用您的 WorldQuant BRAIN 用户名和密码
4. **自动加载操作符**：系统会获取所有可用的操作符（186+）

### 使用 BRAIN 操作符
1. **配置模板**：将模板类型设置为 “Op” 
2. **选择来自 BRAIN**：在模板配置中点击“从 BRAIN 中选择”按钮
3. **搜索和过滤**：使用搜索框和类别过滤器查找操作符
4. **多选**：选择多个操作符并将其应用于您的模板
5. **生成组合**：解码模板以获取所有可能的操作符组合

## 📝 使用指南

### 1. 表达式编辑器
- 在主编辑器中输入或粘贴您的表达式
- 语法将自动检查并提供视觉反馈
- 模板将实时检测并高亮显示
- 输入 `<` 以获取模板建议的自动完成

### 2. 模板管理
- 检测到的模板出现在右侧面板中
- 点击模板类型按钮（Op/Data/Normal）进行配置
- 视觉指示器显示已配置 (✓) 与未配置 (•) 的模板
- 点击模板名称查看当前配置

### 3. 模板配置
- **普通模板**：手动输入以逗号分隔的值
- **操作符模板**：从 BRAIN 操作符中选择或手动输入
- **数据模板**：输入数据字段规格

### 4. 模板解码
生成表达式的两个选项：
- **full_iteration**：生成所有可能的组合
  - 使用笛卡尔积创建每一种可能的组合
  - 显示前 999 个结果，并为大数据集提供搜索功能
- **random_iteration**：生成随机样本
  - 指定随机表达式数量（默认为 10）
  - 首先生成所有组合，然后随机选择指定数量
  - 有助于测试或当您只需要部分可能性时
- 每个模板必须至少具有一个配置值
- 结果将显示，并提供复制和下载选项

## 💡 示例表达式

```
positive_sentiment = rank(<backfill_op/>(<positive_sentiment/>,<days/>));
negative_sentiment = rank(<backfill_op/>(<negative_sentiment/>, <days/>));
sentiment_difference = <compare_op/>(positive_sentiment, negative_sentiment);
<time_series_operator/>(sentiment_difference, <days/>)
```

### 示例配置
- `<days/>` → `7, 14, 30`
- `<compare_op/>` → `ts_max, ts_min`（从 BRAIN 中选择）
- `<time_series_operator/>` → `ts_delta, ts_mean`（从 BRAIN 中选择）

### 生成输出
解码器将生成所有组合：
```
ts_delta(ts_max(7), 7)
ts_delta(ts_max(14), 14)
ts_delta(ts_max(30), 30)
ts_delta(ts_min(7), 7)
ts_delta(ts_min(14), 14)
ts_delta(ts_min(30), 30)
ts_mean(ts_max(7), 7)
...等等
```

## 🎯 语法规则

- 使用 `/* */` 进行多行注释
- 语句以 `;` 结束（最后一行除外）
- 不允许使用类、对象、指针或函数
- 最后一行是 BRAIN 模拟器的 Alpha 表达式

## 🏗️ 技术架构

### Flask 应用程序结构
```
BRAINProject/
├── app.py                 # 拥有自动依赖安装的 Flask 应用程序
├── templates/
│   └── index.html        # 主要网页界面模板
├── static/
│   ├── styles.css        # 应用程序样式
│   ├── script.js         # 核心应用程序逻辑
│   ├── decoder.js        # 模板解码算法
│   └── brain.js          # BRAIN API 集成模块
├── requirements.txt      # Python 依赖项
├── mirror_config.txt     # PyPI 镜像配置
├── run_app.bat           # Windows 启动脚本
├── run_app.sh            # Unix/macOS 启动脚本
├── setup_tsinghua.bat    # 使用清华镜像的 Windows 设置（适用于中国）
├── setup_tsinghua.sh     # 使用清华镜像的 Unix 设置（适用于中国）
├── brain_function_tester.ipynb  # 用于测试的 Jupyter 笔记本
└── README.md             # 本文件
```

### 关键组件
- **Flask 后端**：处理 BRAIN API 身份验证和数据获取
- **模板引擎**：Jinja2 模板用于动态内容
- **静态资源**：高效提供 CSS 和 JavaScript
- **CORS 处理**：内置跨域请求支持
- **会话管理**：安全的会话处理以进行 BRAIN 身份验证

### API 端点
- `GET /` - 主要应用程序页面
- `POST /api/authenticate` - BRAIN 身份验证
- `GET /api/operators` - 获取 BRAIN 操作符，支持分页
- `GET /api/datafields` - 获取 BRAIN 数据字段
- `GET /api/status` - 检查身份验证状态
- `POST /api/logout` - 从 BRAIN 登出

## 🔧 高级特性

### 操作符获取
- **强大的分页**：自动处理 BRAIN API 分页
- **类别支持**：获取所有类别的操作符
- **错误处理**：多种应急策略以确保可靠的数据加载
- **调试**：内置端点用于 API 响应分析

### 模板处理
- **实时检测**：在输入时检测模板
- **视觉反馈**：颜色编码的语法高亮
- **状态指示器**：清晰的视觉提示模板配置状态
- **验证**：确保在解码前所有模板都已配置

### 用户体验
- **专业 UI**：干净、现代的界面设计
- **响应式设计**：适用于桌面和平板设备
- **键盘快捷键**：高效的模板自动完成
- **导出选项**：复制单个结果或下载所有结果

## 🐛 故障排除

### 常见问题

1. **Flask 服务器无法启动**：
   - 检查 Python 版本（需要 3.7+）
   - 安装缺失的依赖项：`pip install -r requirements.txt`

2. **BRAIN 连接失败**：
   - 验证您的 BRAIN 凭据
   - 检查网络连接
   - 确保没有防火墙阻止外发 HTTPS 请求

3. **模板未检测到**：
   - 检查模板语法：`<template_name/>`
   - 使用按钮手动刷新模板

4. **没有加载操作符**：
   - 验证 BRAIN 身份验证是否成功
   - 检查浏览器控制台是否有错误信息
   - 尝试登出并重新认证

### 调试模式
在调试模式下运行应用程序以获取详细错误信息：
```bash
python app.py
# 应用程序默认启用调试模式
```

## 📈 性能

- **高效加载**：操作符在身份验证时加载一次
- **分页处理**：自动获取所有数据，无论 API 分页如何
- **会话管理**：持久会话提升用户体验
- **优化前端**：最小的 JavaScript 依赖加快加载速度

## 🔐 安全

- **会话安全**：Flask 安全会话，支持可配置的密钥
- **凭据处理**：凭据不被存储，仅用于 API 身份验证
- **CORS 保护**：正确配置的跨域请求处理
- **输入验证**：模板语法验证和语法检查

## 🚧 未来增强功能

- **模板库**：保存和共享模板配置
- **高级过滤**：更复杂的操作符和数据字段过滤
- **批量操作**：同时处理多个表达式
- **API 集成**：连接其他金融数据提供商
- **导出格式**：支持 JSON、CSV 和其他输出格式

---

**注意**：该 Flask 应用程序取代了之前的 HTML+代理架构，提供了更强大和集成的 BRAIN 模板解码解决方案。