# 可转债轮动分析系统 V1.0

## 操作说明书

---

### 一、引言

#### 1.1 编写目的

本说明书旨在介绍「可转债轮动分析系统 V1.0」的功能组成、运行环境和操作使用方法，帮助用户快速掌握系统的使用流程，同时也作为软件著作权登记的技术文档依据。

#### 1.2 读者对象

本说明书适用于可转债投资者、量化交易研究人员、金融数据工程师及系统运维人员。

#### 1.3 软件概述

可转债轮动分析系统是一款面向可转债市场的综合分析与数据管理平台。系统提供实时行情浏览、多策略历史回测、可转债历史数据入库与增量同步、异步任务管理等核心功能，帮助用户完成可转债的量化研究与投资决策。

系统采用 B/S 架构，后端基于 Go 语言开发，前端基于 HTML/JavaScript/CSS 开发，数据库采用 SQLite，任务状态缓存采用 Redis，支持 Docker 容器化部署。

#### 1.4 主要功能

1. 用户认证：支持用户名密码登录与邮箱验证码登录，提供注册功能与权限控制。
2. 实时行情：展示全量可转债实时行情，支持搜索、排序等操作。
3. 策略回测：支持低价轮动、双低轮动、溢价率轮动三种策略的历史回测。
4. 数据管理：展示数据库数据状态，提供全量更新与增量更新数据入库功能。
5. 异步任务：数据入库任务异步执行，实时显示任务进度，支持任务列表查询与取消。

---

### 二、运行环境

#### 2.1 硬件环境

| 配置项 | 最低要求 | 推荐配置 |
|--------|----------|----------|
| CPU | 双核 | 四核及以上 |
| 内存 | 2GB | 8GB |
| 硬盘 | 500MB 可用空间 | 2GB 及以上（视数据量） |
| 网络 | 可访问互联网 | 稳定宽带连接 |

#### 2.2 软件环境

| 类别 | 要求 |
|------|------|
| 操作系统 | Windows 10/11、Linux、macOS |
| 后端运行环境 | Go 1.25 及以上 |
| 数据库 | SQLite 3（内嵌，无需单独安装） |
| 缓存服务 | Redis（可选，未启动时自动降级） |
| 浏览器 | Chrome、Edge、Firefox 等现代浏览器 |
| 容器 | Docker（可选，用于启动 Redis） |

#### 2.3 部署方式

1. 直接运行：使用 `go run ./cmd/server` 启动后端服务，默认监听 8080 端口。
2. 环境变量配置：
   - `PORT`：服务端口，默认 8080
   - `STOCK_DB_PATH`：数据库文件路径
   - `REDIS_ADDR`：Redis 地址，默认 localhost:6379
   - `JOB_WORKERS`：任务并发数，默认 8
   - `JOB_BATCH_SIZE`：批量写入阈值，默认 20

---

### 三、用户认证

#### 3.1 登录

1. 打开浏览器访问系统首页，未登录时自动跳转至登录页面。
2. 系统默认采用「用户名 + 密码」登录方式。
3. 输入用户名和密码，点击「登录」按钮。
4. 登录成功后自动跳转至系统主页。

#### 3.2 邮箱验证码登录

1. 在登录页面切换至「邮箱验证码登录」方式。
2. 输入邮箱地址，点击「发送验证码」。
3. 验证码发送后，在系统中输入收到的验证码。
4. 点击「登录」完成验证。

#### 3.3 注册

1. 在登录页面点击「注册」进入注册流程。
2. 填写用户名、邮箱、验证码和密码。
3. 提交后完成账号注册。

#### 3.4 权限控制

系统对未登录用户自动跳转登录页，对受保护接口返回未授权状态，保障数据安全。

---

### 四、实时行情

#### 4.1 功能说明

实时行情页面展示全量可转债的实时报价数据，包括价格、涨跌幅、溢价率、转股价值、转股价、纯债价值、正股名称及正股涨跌幅等字段。

#### 4.2 操作步骤

1. 登录系统后，默认进入「实时行情」页面。
2. 点击「刷新数据」按钮加载最新行情。
3. 在搜索框中输入代码、名称或正股名称进行过滤。
4. 通过「按溢价率」「按价格」「按涨跌」等下拉框选择排序字段。
5. 选择「升序」或「降序」调整排序方向。
6. 点击表头对应列也可快速切换排序。

---

### 五、策略回测

#### 5.1 功能说明

策略回测页面支持对可转债轮动策略进行历史回测，评估策略收益、回撤、夏普比率等指标，并与等权基准进行对比。

#### 5.2 策略类型

1. 低价轮动：按价格从低到高选取标的。
2. 双低轮动：按价格与溢价率综合选取标的。
3. 溢价率轮动：按溢价率从低到高选取标的。

#### 5.3 操作步骤

1. 点击顶部「策略回测」标签页。
2. 在「策略参数」区域选择策略类型，设置起始日期、结束日期、初始资金、持仓数量、调仓周期、价格区间等参数。
3. 在「转债选择」区域勾选参与回测的转债，或点击「全选」选择全部。
4. 点击「开始回测」按钮执行回测。
5. 回测完成后，自动展示回测结果，包括累计收益、年化收益、最大回撤、夏普比率、波动率、胜率等指标，以及净值曲线对比图。

#### 5.4 基本面过滤

勾选「基本面过滤」选项后，系统自动排除正股为 ST、资产负债率过高或净利润为负的转债。

---

### 六、数据管理

#### 6.1 数据状态

1. 点击顶部「数据管理」标签页。
2. 点击「刷新状态」按钮。
3. 页面展示数据库路径、转债数量、K线总数、数据区间等信息。

#### 6.2 全量更新

1. 在「数据更新任务」区域点击「全量更新」按钮。
2. 系统创建全量数据入库任务，拉取所有转债的历史K线数据。
3. 已入库的转债自动跳过，避免重复拉取。

#### 6.3 增量更新

1. 在「数据更新任务」区域点击「增量更新」按钮。
2. 系统创建增量同步任务，仅同步已入库转债自上次入库日期之后的新增数据。
3. 可通过「起始日期」输入框指定增量同步的起点日期。

#### 6.4 任务列表

1. 在「任务列表」区域点击「刷新任务」查看所有任务记录。
2. 任务列表展示任务ID、类型、状态、进度、成功数、失败数、开始时间、完成时间等信息。
3. 运行中的任务会显示进度条和实时进度百分比。
4. 点击「取消」按钮可取消运行中的任务。

#### 6.5 异步任务机制

数据入库任务采用异步执行方式，任务状态实时写入 Redis 缓存，同时持久化到 SQLite 数据库。前端通过定时轮询获取任务实时状态，实现任务进度的实时展示。

---

### 七、数据入库命令行工具

#### 7.1 功能说明

系统提供独立的数据入库命令行工具，支持全量入库与增量同步。

#### 7.2 全量入库

执行命令：`go run ./cmd/ingest -all -db stock.db`

#### 7.3 增量同步

执行命令：`go run ./cmd/ingest -incr -db stock.db`

---

### 八、系统架构

#### 8.1 总体架构

系统采用 MVC 三层架构：

1. Model 层：数据模型与存储接口，包括可转债、K线、用户、任务等数据模型。
2. Controller 层：HTTP 接口处理，包括行情、回测、认证、任务等控制器。
3. View 层：前端页面，包括登录页、主页等。

#### 8.2 数据源架构

系统采用主备数据源机制：

1. 主数据源：东方财富接口，提供实时行情与历史K线。
2. 备用数据源：腾讯财经接口，主数据源失败时自动切换。
3. 熔断机制：主数据源连续失败达到阈值后，进入熔断窗口直接使用备用数据源。

#### 8.3 异步任务架构

1. 任务管理器（Manager）：管理任务注册表和全局限速器，支持多任务并发。
2. 任务执行器（Runner）：单任务并发拉取与批量写入。
3. 限速器：令牌桶模式，控制 API 请求速率，避免高频请求被限流。
4. 缓存层：Redis 存储任务实时状态，SQLite 存储持久化记录。

---

### 九、常见问题

1. 无法访问系统：请检查服务是否启动、端口是否被占用。
2. 实时行情加载失败：可能是数据源网络异常，稍后重试。
3. Redis 连接失败：系统会自动降级，任务功能仍可使用，仅失去实时状态缓存。
4. 数据入库任务失败：可能是部分老转债在数据源无数据，属于正常现象。