# compose

**Repository Path**: quant-seminar/compose

## Basic Information

- **Project Name**: compose
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Seminar

Seminar 是由多个独立服务组成的量化研究项目。主仓库负责组织环境变量、Docker Compose
和 Git submodules；业务代码分别位于 `data`、`analysis`、`card` 和 `arena` 下的前后端
子仓库。

## 项目结构

```text
Seminar
|-- data/          # 数据基座服务，Git submodule
|-- analysis/      # 分析和回测服务，Git submodule
|-- card/          # 飞书卡片渲染服务，Git submodule
|-- arena/
|   |-- backend/   # Arena FastAPI 服务，Git submodule
|   `-- frontend/  # Arena React 前端，Git submodule
|-- docker-compose.yml
|-- .env.example
|-- .env.prod.example
`-- .gitmodules
```

## 服务说明

### data

`data` 是数据基座服务，负责定时采集、存储和查询日频股票数据。它通过结构化
`Derivative` JSON 支持基础因子、衍生因子和预处理组合查询。衍生因子的计算顺序由依赖图
自动确定，不依赖 JSON 对象 key 的遍历顺序。

常用接口：

- `GET /stock/daily/metadata`
- `POST /stock/daily/query`
- `POST /stock/daily/update`

线上服务：`https://data.realhuhu.com`

### analysis

`analysis` 调用 `data` 获取数据，完成单因子分析和多因子策略回测，并将分析结果保存为
pickle 报告。任务通过 WebSocket 返回运行状态和报告 id。

常用接口：

- `WS /factor/single-factor-analysis`
- `WS /backtest/multi-factor-strategy`
- `GET /media/{file_id}`

### card

`card` 将 `analysis` 生成的 pickle 报告转换为飞书交互卡片。它是飞书展示适配服务；
Arena 后端有独立的报告序列化层，会把 pkl 转为前端可消费的 JSON 和 metrics。

### arena

`arena` 是面向用户的量化投研平台，不限定于单一研究方向。

- `arena/backend`：认证、任务编排、报告归属、版本管理、成果库、公开广场、研究助手和 API。
- `arena/frontend`：研究入口轮播、工作台、成果库、广场、公开用户主页、帮助中心和主题切换。
- 当前开放 `single factor analysis` 和 `multi factor strategy`；后续研究方向按研究类型插件平行扩展。

Arena 前后端暂未加入根目录 `docker-compose.yml`，本地启动方式见各自 README。

## 服务链路

```text
Tushare
  |
  v
data -> DolphinDB
  ^
  |
analysis -> media/*.pkl
  |                 |
  v                 v
card -> Feishu   arena/backend -> arena/frontend
                     ^
                     |
                 DeepSeek / OpenAI-compatible API
```

## Docker 服务

复制示例环境变量并启动已有基础服务：

```bash
cp .env.example .env
cp .env.prod.example .env.prod
docker compose up --build
```

| 服务 | 容器端口 | 本机端口 |
| --- | --- | --- |
| `seminar-data` | `8000` | `8800` |
| `seminar-analysis` | `8000` | `8801` |
| `seminar-card` | `8000` | `8802` |

## Submodules

克隆主仓库并拉取全部 submodules：

```bash
git clone --recursive https://gitee.com/quant-seminar/compose.git Seminar
```

已有仓库初始化或同步 submodules：

```bash
git submodule update --init --recursive
git submodule status --recursive
```

| 路径 | 远端 | 跟踪分支 |
| --- | --- | --- |
| `data` | `https://gitee.com/quant-seminar/data` | `master` |
| `analysis` | `https://gitee.com/quant-seminar/analysis` | `master` |
| `card` | `https://gitee.com/quant-seminar/card` | `master` |
| `arena/backend` | `https://gitee.com/quant-seminar/arena-backend.git` | `master` |
| `arena/frontend` | `https://gitee.com/quant-seminar/arena-frontend.git` | `master` |

`arena/backend` 与 `arena/frontend` 位于 `arena/` 下，但各自仍是独立 submodule。
如果只修改前端或后端，应先在对应子仓库提交，再回到主仓库提交 submodule 指针。

## Git 开发约定

每个 submodule 都是独立 Git 仓库，包含 `dev` 和 `master` 分支。日常功能开发在对应
submodule 的 `dev` 分支进行；功能稳定后整理提交并合并到该 submodule 的 `master`；
最后回到主仓库提交 submodule 指针。

```bash
cd arena/frontend
git switch dev
git add <files>
git commit -m "feat: ..."

git switch master
git merge --ff-only dev

cd ../..
git add arena/frontend
git commit -m "chore: update arena frontend submodule"
```

主仓库中的 `M data`、`M analysis` 或 `M card` 可能来自子仓库内部未提交改动。提交指针
前应进入对应 submodule 检查状态，不要在主仓库中误带其它模块的改动。