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

## 软件设计说明书

---

### 第一章 引言

#### 1.1 编写目的

本文档是「可转债轮动分析系统 V1.0」的软件设计说明书，旨在详细描述系统的总体架构设计、模块划分、数据结构、接口设计、关键算法及安全与性能设计，作为软件著作权登记的技术文档依据，同时为系统的后续维护与功能迭代提供设计参考。

#### 1.2 项目背景

可转债作为一种兼具债券属性与股票属性的金融工具，近年来市场规模不断扩大。投资者在进行可转债投资决策时，需要对全市场可转债的实时行情进行监控，并通过历史数据回测验证轮动策略的有效性。传统的人工分析与手工数据整理方式效率低下、时效性差。本系统旨在构建一个集行情浏览、策略回测、数据入库与任务管理于一体的可转债分析平台，提升可转债量化研究的效率与准确性。

#### 1.3 术语定义

| 术语 | 说明 |
|------|------|
| 可转债 | 可转换公司债券，可在特定条件下转换为公司股票 |
| 溢价率 | 转股溢价率，衡量可转债价格相对其转股价值的溢价程度 |
| 转股价值 | 可转债按当前转股价转换后对应的股票市值 |
| 轮动策略 | 定期按特定指标排序、调仓的投资策略 |
| 全量入库 | 拉取全部可转债的历史K线数据并写入数据库 |
| 增量同步 | 仅同步自上次入库日期之后新增的数据 |
| 熔断 | 数据源连续失败达到阈值后，短时间内直接切换备用源的机制 |
| 限速器 | 令牌桶算法实现的请求速率控制组件 |

---

### 第二章 总体设计

#### 2.1 设计目标

1. 提供可转债实时行情浏览与多维度排序、筛选能力。
2. 提供多策略历史回测能力，输出收益、回撤、夏普比率等关键指标。
3. 提供可转债历史数据的高效入库能力，支持全量与增量两种同步方式。
4. 提供异步任务管理能力，实现入库任务进度的实时展示。
5. 保证系统在数据源异常、缓存服务不可用等情况下的可用性。

#### 2.2 系统架构

系统采用 B/S 架构，总体分为三层：

1. **表示层（View）**：基于 HTML、JavaScript、CSS 开发的单页应用，包含登录页与主页（实时行情、策略回测、数据管理三个标签页）。
2. **控制层（Controller）**：基于 Go 语言 net/http 开发的路由与控制器，负责接收 HTTP 请求、权限校验、参数解析与响应封装。
3. **模型层（Model）**：包含数据模型定义、存储接口抽象、数据源访问与业务服务四部分。

系统整体遵循 MVC 设计模式，控制层与模型层通过接口解耦，便于替换数据源与存储实现。

#### 2.3 技术选型

| 技术 | 用途 | 选型理由 |
|------|------|----------|
| Go 1.25 | 后端开发语言 | 高并发、静态编译、部署简单 |
| net/http | HTTP 服务框架 | 标准库，无额外依赖 |
| SQLite 3 | 数据持久化 | 单文件、零配置、适合个人分析场景 |
| modernc.org/sqlite | SQLite 驱动 | 纯 Go 实现，无 CGO 依赖 |
| Redis | 任务状态缓存 | 高性能内存存储，支持实时状态查询 |
| go-redis/v9 | Redis 客户端 | 官方维护的 Go Redis 客户端 |
| Chart.js | 前端图表 | 开源图表库，用于回测净值曲线展示 |
| Docker | 容器化部署 | 便于 Redis 等中间件的一键启动 |
| golang.org/x/crypto | 密码加密 | 提供 bcrypt 密码哈希算法 |

---

### 第三章 模块设计

系统按功能划分为六大模块，各模块职责如下。

#### 3.1 用户认证模块

负责用户注册、登录、登出与权限校验。

**功能组成**：
1. 注册：用户名 + 邮箱 + 验证码 + 密码。
2. 登录：支持用户名密码登录与邮箱验证码登录两种方式。
3. 权限校验：通过 token 识别登录用户，未登录访问受保护资源时自动跳转或返回未授权。
4. 管理员账号：系统初始化时自动创建管理员账号。

**关键设计**：
- 密码使用 bcrypt 算法加盐哈希存储，不保存明文。
- 登录成功后生成随机 token，前端同时写入 localStorage 与 cookie，保证前后端鉴权一致。
- 验证码设置有效期与使用状态，验证后标记已使用。

#### 3.2 行情模块

负责可转债实时行情与历史K线数据的获取与展示。

**功能组成**：
1. 实时行情：获取全量可转债实时报价，过滤已退市转债。
2. 历史K线：获取指定转债的日K线数据。
3. 搜索与排序：支持按代码、名称、正股搜索，按多字段排序。

**关键设计**：
- 采用主备数据源机制，主数据源为东方财富接口，备用数据源为腾讯财经接口。
- 主数据源失败时自动切换备用数据源，保证数据可用性。

#### 3.3 策略回测模块

负责轮动策略的历史回测与结果展示。

**功能组成**：
1. 三种轮动策略：低价轮动、双低轮动、溢价率轮动。
2. 回测参数配置：起止日期、初始资金、持仓数量、调仓周期、价格区间等。
3. 基本面过滤：排除正股 ST、资产负债率过高或净利润为负的转债。
4. 结果展示：累计收益、年化收益、最大回撤、夏普比率、波动率、胜率等指标及净值曲线。

**关键设计**：
- 回测引擎以交易日为步长遍历历史数据，按调仓周期执行策略选股与调仓。
- 账户模型模拟现金与持仓，计算每日净值。
- 同时计算等权全转债基准，用于超额收益对比。

#### 3.4 数据入库模块

负责可转债历史数据的入库与同步。

**功能组成**：
1. 全量入库：拉取全部转债的历史K线。
2. 增量同步：仅同步已入库转债的新增数据。
3. 断点续跑：全量模式下跳过已入库转债，增量模式基于最后K线日期确定起点。

**关键设计**：
- 采用并发拉取 + 批量写入的架构，多 worker 并发获取数据，单 collector 串行批量写入数据库。
- SQLite 连接数限制为 1，避免写锁竞争。
- K线写入采用幂等 upsert 语义，重复写入自动跳过。

#### 3.5 异步任务模块

负责数据入库任务的异步执行与状态管理。

**功能组成**：
1. 任务创建：创建全量或增量入库任务。
2. 任务执行：异步并发执行入库任务。
3. 任务查询：查询任务列表与单个任务状态。
4. 任务取消：取消运行中的任务。
5. 实时进度：任务进度实时写入缓存，前端轮询展示。

**关键设计**：
- 任务管理器统一管理任务注册表与全局限速器，支持多任务并发。
- 任务状态同时写入 Redis（实时）与 SQLite（持久化），Redis 不可用时自动降级到 SQLite。
- 全局限速器采用令牌桶算法，控制数据源请求速率，避免高频请求被限流。

#### 3.6 数据源模块

负责外部行情数据的访问与容错。

**功能组成**：
1. 东财数据源：实时行情、历史K线、转债列表、基本面数据。
2. 腾讯数据源：历史K线备用源、实时报价。
3. 主备切换：主数据源失败时自动切换备用源。
4. 熔断机制：主源连续失败达到阈值后进入熔断窗口。

**关键设计**：
- 定义统一的数据源接口（MarketDataSource），屏蔽不同数据源的实现差异。
- 熔断窗口结束后自动放行一次探测请求，成功则解除熔断。

---

### 第四章 数据库设计

#### 4.1 数据库选型

系统采用 SQLite 3 作为持久化数据库。SQLite 为单文件嵌入式数据库，无需独立部署，适合个人分析场景；同时 SQL 语句遵循通用标准语法，便于后续迁移至 PostgreSQL 等数据库。

#### 4.2 核心数据表

**（1）可转债K线表（convertible_kline）**

存储每只可转债的日K线数据。

| 字段 | 类型 | 说明 |
|------|------|------|
| code | TEXT | 转债代码 |
| date | TEXT | 交易日期 |
| open | REAL | 开盘价 |
| close | REAL | 收盘价 |
| high | REAL | 最高价 |
| low | REAL | 最低价 |
| volume | INTEGER | 成交量 |
| amount | REAL | 成交额 |
| convert_price | REAL | 转股价 |
| convert_value | REAL | 转股价值 |
| premium_rate | REAL | 溢价率 |

主键：code + date 联合主键。

**（2）转债基础信息表（convert_bond）**

存储转债的基本信息。

| 字段 | 类型 | 说明 |
|------|------|------|
| code | TEXT | 转债代码（主键） |
| name | TEXT | 转债名称 |
| stock_code | TEXT | 正股代码 |
| initial_convert_price | REAL | 初始转股价 |
| list_date | TEXT | 上市日期 |
| delist_date | TEXT | 退市日期 |

**（3）用户表（user）**

存储注册用户信息。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 用户ID（自增主键） |
| username | TEXT | 用户名 |
| email | TEXT | 邮箱 |
| password_hash | TEXT | 密码哈希 |
| created_at | TEXT | 创建时间 |
| updated_at | TEXT | 更新时间 |

**（4）验证码表（verify_code）**

存储邮箱验证码信息。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| email | TEXT | 邮箱 |
| code | TEXT | 验证码 |
| purpose | TEXT | 用途（注册/登录） |
| expires_at | INTEGER | 过期时间 |
| used | INTEGER | 是否已使用 |

**（5）任务表（ingest_task）**

存储数据入库任务的持久化记录。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT | 任务ID（主键） |
| type | TEXT | 任务类型（full/incremental） |
| status | TEXT | 任务状态 |
| total | INTEGER | 总数量 |
| done | INTEGER | 已完成数量 |
| success | INTEGER | 成功数量 |
| failed | INTEGER | 失败数量 |
| failed_codes | TEXT | 失败转债代码 |
| params | TEXT | 任务参数 |
| error | TEXT | 错误信息 |
| started_at | TEXT | 开始时间 |
| finished_at | TEXT | 完成时间 |

**（6）正股基本面表（stock_fundamental）**

存储正股的基本面数据，用于回测基本面过滤。

| 字段 | 类型 | 说明 |
|------|------|------|
| code | TEXT | 正股代码（主键） |
| name | TEXT | 名称 |
| roe | REAL | 净资产收益率 |
| debt_ratio | REAL | 资产负债率 |
| net_profit | REAL | 净利润 |
| status | INTEGER | 状态 |
| total_asset | REAL | 总资产 |
| total_debt | REAL | 总负债 |
| update_date | TEXT | 更新日期 |

---

### 第五章 接口设计

系统采用 RESTful 风格的 HTTP 接口，接口响应统一使用 JSON 格式，字段采用 camelCase 命名。除认证相关接口外，其余接口均需在请求头携带 Bearer token。

#### 5.1 认证接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /api/auth/send-code | POST | 发送邮箱验证码 |
| /api/auth/register | POST | 注册账号 |
| /api/auth/login | POST | 登录 |
| /api/auth/logout | POST | 登出 |
| /api/auth/me | GET | 获取当前用户信息 |

#### 5.2 行情接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /api/bonds | GET | 获取全量可转债实时行情 |
| /api/bonds/{code}/kline | GET | 获取指定转债日K线 |

#### 5.3 回测接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /api/backtest | POST | 执行策略回测 |

#### 5.4 数据接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /api/status | GET | 获取数据库数据状态 |
| /api/db/bonds | GET | 获取数据库中已有转债列表 |

#### 5.5 任务接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /api/tasks | POST | 创建入库任务 |
| /api/tasks | GET | 获取任务列表 |
| /api/tasks/{id} | GET | 获取单个任务状态 |
| /api/tasks/{id}/cancel | POST | 取消任务 |

---

### 第六章 关键算法设计

#### 6.1 轮动策略算法

轮动策略的核心逻辑为：在每个调仓周期，按指定指标对可转债进行排序，选取排名靠前的 N 只转债作为持仓，卖出不在持仓中的转债，买入新进入的转债。

低价轮动按价格升序选债；双低轮动按「价格 + 溢价率」综合指标升序选债；溢价率轮动按溢价率升序选债。调仓周期、持仓数量、价格区间等参数由用户配置。

#### 6.2 主备切换与熔断算法

数据源请求采用「主源优先，失败切换」策略：

1. 请求首先发往主数据源。
2. 主源失败时，记录失败计数，并立即切换到备用数据源。
3. 当主源连续失败次数达到阈值（3 次）时，开启熔断，后续请求直接使用备用源。
4. 熔断窗口（10 分钟）结束后，放行一次探测请求；探测成功则解除熔断恢复主源。

#### 6.3 全局限速算法

系统采用令牌桶算法实现全局限速。令牌桶以固定速率（默认 400 毫秒一个令牌）生成令牌，初始突发额度为 4。每个数据请求在发出前必须获取一个令牌，未获取到令牌的请求等待。该算法保证数据请求速率稳定，避免因高频请求触发数据源的限流封禁。

#### 6.4 增量同步起点算法

增量同步时，系统一次性查询所有已入库转债的最后K线日期（GROUP BY 聚合查询），形成「转债代码 → 最后日期」映射。对每只转债，其增量同步起点为该最后日期的次日；若指定了起始日期参数，则以两者中较晚者为起点。该设计避免了逐只查询导致的性能损耗。

---

### 第七章 安全设计

#### 7.1 身份认证

系统采用 token 机制进行身份认证。登录成功后服务端生成随机 token，客户端在后续请求中携带 token，服务端校验 token 有效性。未登录用户访问受保护资源时，页面请求自动跳转登录页，接口请求返回 401 未授权。

#### 7.2 密码安全

用户密码采用 bcrypt 算法加盐哈希后存储，数据库中不保存明文密码。bcrypt 算法具有自适应的计算成本，能有效抵御暴力破解。

#### 7.3 数据安全

1. 敏感数据（如密码哈希）仅存储在本地数据库中，不对外暴露。
2. 接口响应仅返回必要字段，不泄露数据库连接信息等敏感数据。
3. 前端对用户输入进行基础校验，后端对请求参数进行统一校验。

#### 7.4 权限控制

系统通过中间件统一实现权限控制，所有受保护接口均经过权限校验中间件，确保只有登录用户才能访问业务数据。

---

### 第八章 性能与容错设计

#### 8.1 性能设计

1. **并发拉取**：数据入库任务采用多 worker 并发拉取数据，默认 8 个并发。
2. **批量写入**：拉取结果汇聚后按批次（默认 20 只）批量写入数据库，减少事务开销。
3. **单写者模型**：SQLite 连接数限制为 1，仅 collector 单 goroutine 写入，避免写锁竞争。
4. **聚合查询**：增量同步使用一次性聚合查询获取全部最后日期，避免逐只查询。

#### 8.2 容错设计

1. **数据源容错**：主备数据源切换 + 熔断机制，保证数据源异常时的可用性。
2. **缓存降级**：Redis 不可用时自动降级到内存空实现，任务系统仍可运行，仅失去实时状态缓存能力。
3. **写入重试**：数据库写入失败时自动重试（最多 3 次），应对文件系统短暂占用。
4. **请求退避**：数据源请求失败时按 3 秒、6 秒递增退避重试。
5. **优雅退出**：服务关闭时自动取消运行中的任务，避免数据不一致。

---

### 第九章 部署设计

#### 9.1 部署架构

系统后端编译为单个可执行文件，前端静态资源随程序提供。数据库为 SQLite 单文件。Redis 作为可选中间件通过 Docker 部署。

#### 9.2 部署步骤

1. 编译后端程序：`go build ./cmd/server`。
2. 配置环境变量（端口、数据库路径、Redis 地址等）。
3. 启动后端服务。
4. 如需 Redis，执行 `docker compose up -d` 启动 Redis 容器。
5. 浏览器访问系统地址完成使用。

#### 9.3 环境变量配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| PORT | 8080 | 服务端口 |
| STOCK_DB_PATH | 可执行目录下 stock.db | 数据库路径 |
| REDIS_ADDR | localhost:6379 | Redis 地址 |
| REDIS_PASSWORD | 空 | Redis 密码 |
| JOB_WORKERS | 8 | 任务并发数 |
| JOB_BATCH_SIZE | 20 | 批量写入阈值 |

---

### 第十章 总结

「可转债轮动分析系统 V1.0」采用 MVC 架构，通过模块化设计实现了用户认证、实时行情、策略回测、数据入库与异步任务管理五大核心功能。系统在数据源容错、缓存降级、并发性能、权限安全等方面进行了专门设计，具备良好的可用性、健壮性与可扩展性，能够满足可转债量化研究与投资决策的实际需求。