# 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-05-24

## 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/         # 预留开发目录
|-- docker-compose.yml
|-- .env.example
|-- .env.prod.example
|-- .gitmodules
`-- readme.md
```

## Submodules

### data

`data` 是数据基座服务，负责日频股票数据的采集、存储和查询。

主要能力：

- 定时从 Tushare 增量获取日频行情、估值、财务报表和财务指标。
- 将数据统一写入 DolphinDB 长表：`time/code/factor/value`。
- 通过 `/stock/daily/query` 查询基础因子和派生因子。
- 通过结构化 `Derivative` JSON 构造时序、截面、TA-Lib 和嵌套因子。
- 支持因子预处理，包括去极值、标准化和中性化。

服务端口：

| 环境 | 地址 |
| --- | --- |
| Docker 内部 | `http://seminar-data:8000` |
| 本机映射 | `http://127.0.0.1:8800` |
| 线上 | `https://data.realhuhu.com` |

常用接口：

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

详细说明见 `data/README.md`。

### analysis

`analysis` 是分析服务，位于 `data` 之上。它不直接维护行情数据，而是调用 `data` 查询 parquet 数据，再完成单因子测试和多因子策略回测。

主要能力：

- 单因子测试：分组收益、IC、Rank IC、显著性和分组回测指标。
- 多因子策略回测：选股、调仓、组合权重和净值曲线。
- 将分析结果保存为 `media/{file_id}.pkl`。
- 通过 WebSocket 返回运行状态和结果文件 id。

服务端口：

| 环境 | 地址 |
| --- | --- |
| Docker 内部 | `http://seminar-analysis:8000` |
| 本机映射 | `http://127.0.0.1:8801` |

常用接口：

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

详细说明见 `analysis/README.md`。

### card

`card` 是展示服务，负责把 `analysis` 生成的 pickle 结果转换为飞书交互卡片。

主要能力：

- 下载 `analysis/media/{file_id}.pkl`。
- 将单因子测试结果转换为 IC、收益、净值和回测统计卡片。
- 将多因子策略回测结果转换为收益风险指标、净值曲线、回撤和滚动指标卡片。
- 调用飞书消息回复接口发送模板卡片。

服务端口：

| 环境 | 地址 |
| --- | --- |
| Docker 内部 | `http://seminar-card:8000` |
| 本机映射 | `http://127.0.0.1:8802` |

常用接口：

- `GET /single-factor-analysis`
- `GET /factor-strategy-backtest`

详细说明见 `card/README.md`。

## 服务链路

```text
Tushare
  |
  v
data -> DolphinDB
  ^
  |
analysis
  |
  | media/*.pkl
  v
card -> Feishu
```

典型使用流程：

1. `data` 定时或手动更新 DolphinDB 中的日频因子数据。
2. 调用 `analysis` 的 WebSocket 接口提交因子或策略参数。
3. `analysis` 调用 `data` 获取数据，完成分析或回测，并生成 pickle 结果。
4. `card` 根据 `file_id` 下载 pickle，构造飞书卡片并回复消息。

## 环境配置

复制示例环境变量文件：

```bash
cp .env.example .env
cp .env.prod.example .env.prod
```

关键环境变量：

```env
TZ=Asia/Shanghai
PROD=true
NETWORK_NAME=seminar

DOLPHIN_HOST=dolphindb
DOLPHIN_PORT=8848
DOLPHIN_USERNAME=admin
DOLPHIN_PASSWORD=123456
DOLPHIN_DAILY_DB=...
DOLPHIN_DAILY_STOCK_TB=...

DATA_SERVICE_URL=http://seminar-data:8000
ANALYSIS_SERVICE_URL=http://seminar-analysis:8000

TUSHARE_TOKEN=...

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
```

`NETWORK_NAME` 需要指向 DolphinDB 所在的 Docker network。当前 `docker-compose.yml` 使用外部网络：

```yaml
networks:
  seminar:
    name: ${NETWORK_NAME}
    external: true
```

如果网络不存在，需要先创建：

```bash
docker network create seminar
```

## 启动服务

构建并启动全部服务：

```bash
docker compose up --build
```

只启动某个服务：

```bash
docker compose up --build seminar-data
docker compose up --build seminar-analysis
docker compose up --build seminar-card
```

端口映射：

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

## 克隆与初始化

克隆主仓库并递归拉取 submodules：

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

如果已经克隆但没有初始化 submodules：

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

查看 submodule 状态：

```bash
git submodule status --recursive
```

更新 submodules 到主仓库记录的提交：

```bash
git submodule update --recursive
```

根据 `.gitmodules` 中配置的远端分支更新：

```bash
git submodule update --remote
```

## Git 组织方式

主仓库是 compose 仓库，负责记录三个 submodule 的具体 commit 指针。每个 submodule 都是独立 Git 仓库，有自己的 `dev` 和 `master` 分支。

当前 submodule 配置：

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

开发约定：

1. 日常功能开发在对应 submodule 的 `dev` 分支进行。
2. 一个功能完成后，在 `dev` 上整理为一个清晰提交。
3. 确认无误后，将该提交合并到同一 submodule 的 `master` 分支。
4. 回到主仓库，更新并提交 submodule 指针。
5. 需要发布时，再推送 submodule 和主仓库。

## 开发流程

进入目标 submodule：

```bash
cd data
git switch dev
```

完成开发并提交：

```bash
git status
git add README.md
git commit -m "docs: update data README"
```

合并到 submodule 的 `master`：

```bash
git switch master
git merge --ff-only dev
```

如果无法 fast-forward，说明 `master` 和 `dev` 已分叉，需要先检查差异并决定合并方式：

```bash
git log --oneline --graph --decorate --all -20
git merge dev
```

回到主仓库提交 submodule 指针：

```bash
cd ..
git status
git add data
git commit -m "chore: update data submodule"
```

如果一次更新多个 submodule：

```bash
git add data analysis card
git commit -m "chore: update submodule pointers"
```

## 注意事项

- 在主仓库看到 `M data`、`M analysis` 或 `M card`，通常表示 submodule 指针变化或子仓库内部有未提交改动。
- 修改子模块内容时，要进入子模块目录提交；主仓库只记录子模块的 commit 指针。
- 不要在父仓库直接假设子模块已经发布。submodule 提交和父仓库指针提交是两件事。
- `analysis/media/*.pkl` 是运行产物，通常不应作为代码改动提交。
- `arena` 目前为空目录，未来如果放入正式代码，需要补充对应 README 和开发约定。