# JT

**Repository Path**: catcookie/jt

## Basic Information

- **Project Name**: JT
- **Description**: 实训最终考核项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 锦途金融分析平台

锦途是一个面向 A 股研究场景的多用户金融分析平台，包含 Flask API、Vue Web 界面和 Electron Windows 桌面端。系统整合股票行情、新闻公告、行业评分、关注列表、研究工作台、RAG 问答和管理员后台，并使用 Milvus 存储系统知识库向量。

## 用户须知

锦途面向 A 股研究和信息整理场景，提供数据浏览、关注管理、榜单、研究工作台和 AI 辅助分析。用户使用前应了解以下边界：

- 行情、新闻、公告、研报和舆情数据由外部数据源提供，可能存在延迟、缺失、错误或来源变化。
- 评分、榜单、关键词和 AI 生成内容是信息整理与研究辅助结果，不代表确定性预测，也不构成投资建议、买卖建议或收益承诺。
- 用户应结合正式披露文件和自身情况独立判断，并自行承担据此进行投资或交易的风险。
- 个人知识库仅在 Electron 客户端本地加密保存，但分析时命中的内容和近期对话可能发送到后端，并继续发送给配置的外部 LLM 服务。

### 主要功能

- 用户注册、JWT 登录、管理员申请和分级权限控制
- 股票列表、行情详情、关注管理和近期行情展示
- 新闻、公告、研报、行业评分、火箭股与潜力股榜单
- 预留支持碰撞动画的近期新闻高频关键词气泡（非必要功能，仍需继续开发与体验平衡，默认禁用）
- 聚合新闻、公告、研报和市场观点的研究工作台
- 个人知识优先、系统知识补充的 RAG 分析问答
- 管理员审核、账户管理、权限分配和运营数据统计
- 系统知识手工录入、文档导入、URL 提取和批量导入
- Electron 本地加密个人知识库与聊天历史

## 开发者须知

以下内容用于本地开发、测试和部署维护。生产环境部署前应替换所有示例密钥，并完成数据库、缓存、向量库、数据源和模型服务的连通性验证。

### 系统架构

```mermaid
flowchart LR
    UI[Vue 3 Web / Electron] -->|HTTP / JWT| API[Flask API]
    UI -->|Electron IPC| PKB[本地加密个人知识库]
    API --> MYSQL[(MySQL)]
    API --> REDIS[(Redis / 内存降级)]
    API --> MILVUS[(Milvus 系统知识库)]
    API --> LLM[OpenAI-compatible LLM]
    API --> SOURCES[行情 / 新闻 / 公告数据源]
```

系统知识库与个人知识库是两套独立存储：

| 数据 | 存储位置 | 说明 |
| --- | --- | --- |
| 业务数据 | MySQL | 用户、管理员、权限、股票、行情、关注、评分等 |
| 系统知识库 | Milvus | 默认集合 `system_knowledge_v1`，管理员统一维护 |
| 个人知识库 | Electron `userData/personal-knowledge/` | 按用户保存 AES-256-GCM 加密 JSON，不在服务端持久化；分析时会传输命中正文 |
| 缓存 | Redis | Redis 不可用时可降级到当前进程内存 |

更详细的存储位置和迁移说明见 [常见问题](docs/FAQ.md)。

### 技术栈

**后端**

- Python 3.11、Flask 3、SQLAlchemy 2、MySQL
- Redis（关键词快照、新闻及业务缓存）、APScheduler、JWT、bcrypt、Pydantic Settings
- Milvus / PyMilvus、Sentence Transformers、OpenAI SDK
- Requests、NumPy、scikit-learn、Loguru

**前端与桌面端**

- Vue 3、Vite 8、Vue Router、Pinia、Axios、ECharts、i18n-jsautotranslate
- Electron 39、electron-builder

### 目录结构

```text
JT/
├── JTB/                     # Flask 后端
│   ├── models/              # SQLAlchemy 模型
│   ├── routes/              # HTTP API Blueprint
│   ├── services/            # RAG、Milvus、行情和业务服务
│   ├── tasks/               # 定时任务与知识导入脚本
│   ├── tests/               # unittest 测试
│   ├── utils/               # JWT、Embedding、缓存与响应工具
│   ├── .env.example         # 后端配置示例
│   └── app.py               # 后端入口
├── JTF/                     # Vue / Electron 客户端
│   ├── electron/            # Electron 主进程、IPC 与本地加密存储
│   ├── src/                 # Vue 应用源码
│   ├── .env.production.example
│   └── package.json
├── docs/
│   ├── API.md               # HTTP 接口文档
│   ├── FAD.md               # 当前功能架构设计
│   ├── FRONTEND.md          # 前端结构、页面索引与开发约定
│   └── FAQ.md               # 常见问题、存储与迁移说明
└── JTBPlan.md               # 早期设计文档，部分内容已过期
```

### 环境要求

- Python 3.11 或兼容版本
- Node.js 22.12+ 与 npm（Vite 8 最低支持 Node 20.19，Electron 工具链要求更高版本）
- MySQL 8.x（需要预先创建数据库）
- Milvus 2.5+，默认监听 `localhost:19530`
- Redis 5+（可选）
- 可用的 OpenAI-compatible LLM 服务（AI 功能需要）

### 快速开始

### 1. 准备后端配置

在 MySQL 中创建数据库，例如：

```sql
CREATE DATABASE jtb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

复制环境变量模板：

```powershell
Set-Location JTB
Copy-Item .env.example .env
```

至少检查以下配置：

```dotenv
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DB=jtb

MILVUS_URL=localhost
MILVUS_PORT=19530
MILVUS_DATABASE=default
MILVUS_COLLECTION=system_knowledge_v1
MILVUS_AUTO_START=true
MILVUS_COMPOSE_FILE=docker/milvus-standalone.yml
MILVUS_AUTO_START_TIMEOUT_SECONDS=180

FLASK_SECRET_KEY=replace-with-a-random-secret
JWT_SECRET_KEY=replace-with-a-different-random-secret

INITIAL_SUPERADMIN_USERNAME=admin
INITIAL_SUPERADMIN_PASSWORD=replace-with-a-strong-password
INITIAL_SUPERADMIN_EMAIL=admin@example.com

PASSWORD_RESET_URL=http://localhost:5173/reset-password
SMTP_HOST=smtp.163.com
SMTP_PORT=465
SMTP_USERNAME=your_account@163.com
SMTP_PASSWORD=your_smtp_authorization_code
SMTP_FROM_EMAIL=your_account@163.com
```

`INITIAL_SUPERADMIN_USERNAME` 必须使用未被普通用户占用的新用户名。若数据库中已有同名普通用户且尚无超级管理员，当前初始化逻辑会直接将该用户提升为超级管理员，并保留其原密码，不会用环境变量中的密码覆盖。

如未部署 Redis，请设置：

```dotenv
REDIS_ENABLED=false
```

完整变量说明见 [后端配置](#后端配置)。不要提交真实 `.env`、API Key 或数据库密码。

### 2. 启动后端

```powershell
Set-Location JTB
python -m venv .venv
& .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python app.py
```

后端默认地址为 `http://127.0.0.1:5000`。首次启动会：

- 创建缺失的 MySQL 表并执行当前内置结构兼容处理
- 初始化权限和首个超级管理员
- 创建或校验 Milvus 集合及 COSINE 向量索引
- Milvus 不可用且启用了 `MILVUS_AUTO_START` 时，通过内置 Docker Compose 尝试启动 Milvus standalone
- 启动后台定时任务
- 为既有用户表补充 `keyword_limit` 等当前内置兼容字段

首次创建超级管理员后，修改 `INITIAL_SUPERADMIN_PASSWORD` 不会自动重置已有密码。

### 3. 导入默认系统知识（可选）

```powershell
Set-Location JTB
python tasks/import_system_kb.py
```

该脚本会将内置金融基础知识写入当前配置的 Milvus 集合。旧 SQLite-Vec 数据不会自动迁移。

Windows 默认会在 Docker daemon 未运行时尝试启动 Docker Desktop。自动启动要求已安装 Docker Desktop，路径可通过 `DOCKER_DESKTOP_PATH` 调整。Milvus、MinIO 和 etcd 的持久化数据保存在 `JTB/docker/volumes/`，关闭自动启动可设置 `MILVUS_AUTO_START=false`。

### 4. 启动 Web 前端

```powershell
Set-Location JTF
npm ci
npm run dev
```

开发地址为 `http://localhost:5173`，Vite 会将 `/api` 代理到 `http://localhost:5000`。

### 5. 启动 Electron 桌面端

```powershell
Set-Location JTF
npm run electron:dev
```

个人知识库和聊天历史仅在 Electron 模式可用。浏览器模式没有 Electron IPC，不能读写本地个人知识。

前端目录、路由与页面文件对应关系见 [前端开发指导](docs/FRONTEND.md)。

### 后端配置

配置来源为 `JTB/.env`，字段定义见 `JTB/config.py`。

| 分类 | 环境变量 |
| --- | --- |
| MySQL | `DATABASE_URL`，或 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DB` |
| Redis | `REDIS_URL`、`REDIS_ENABLED` |
| 功能开关 | `KEYWORDS_ENABLED`（关键词功能默认 `false`） |
| LLM | `LLM_PROVIDER`、`LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL`、`LLM_EMBEDDING_MODEL` |
| 本地向量模型 | `LOCAL_EMBEDDING_MODEL`、`LOCAL_EMBEDDING_DIM` |
| Milvus | `MILVUS_ENABLED`、`MILVUS_URL`、`MILVUS_PORT`、`MILVUS_DATABASE`、`MILVUS_COLLECTION`、`MILVUS_TOKEN`、`MILVUS_TIMEOUT_SECONDS` |
| Flask / JWT | `FLASK_DEBUG`、`FLASK_SECRET_KEY`、`JWT_SECRET_KEY`、`JWT_ACCESS_TOKEN_MINUTES`、`JWT_REFRESH_TOKEN_DAYS` |
| 密码重置邮件 | `PASSWORD_RESET_URL`、`PASSWORD_RESET_TOKEN_MINUTES`、`PASSWORD_RESET_REQUEST_COOLDOWN_SECONDS`、`SMTP_HOST`、`SMTP_PORT`、`SMTP_USERNAME`、`SMTP_PASSWORD`、`SMTP_FROM_EMAIL`、`SMTP_USE_SSL`、`SMTP_USE_STARTTLS`、`SMTP_TIMEOUT_SECONDS` |
| 初始管理员 | `INITIAL_SUPERADMIN_USERNAME`、`INITIAL_SUPERADMIN_PASSWORD`、`INITIAL_SUPERADMIN_EMAIL` |
| 数据源 | `NEWS_SOURCES`、`STOCK_LIST_SOURCES`、`ANNOUNCEMENT_SOURCES`、`REPORT_SOURCES`；`STOCK_PRICE_SOURCES` 当前仅为保留字段，行情服务尚未读取 |

生产前端可通过 `VITE_API_BASE_URL` 指定包含 `/api` 的 API Base URL，例如 `https://api.example.com/api`；Electron 还支持进程环境变量 `JT_API_BASE_URL`。`VITE_API_BASE_URL` 优先于 Electron 注入值。

关键词功能的前端构建开关是 `VITE_KEYWORDS_ENABLED`，默认 `false`。该变量为 `true` 时才显示导航、路由和个人中心关键词偏好；它必须与后端 `KEYWORDS_ENABLED=true` 配套使用。

### 身份与权限

普通用户使用用户工作区，管理员使用独立后台。超级管理员隐式拥有所有权限。

普通用户注册和登录前必须阅读并确认 [用户须知](docs/USER_NOTICE.md)。本项目仅用于交流学习，不提供专业金融分析或投资建议；用户应独立核验信息并审查其自行上传至个人知识库的内容。

| 权限 ID | 用途 |
| --- | --- |
| `1001` | 审核管理员注册 |
| `1002` | 管理用户和账户状态 |
| `1003` | 管理系统知识库 |
| `1004` | 分配管理员权限 |
| `1005` | 查看运营数据 |

Access Token 默认有效 15 分钟，Refresh Token 默认有效 14 天。完整认证和接口约定见 [API 文档](docs/API.md)。

### 定时任务

| 任务 | 默认频率 |
| --- | --- |
| 新闻抓取 | 每小时；关键词开关启用后附带提取 |
| 临时关键词升级 | 每 6 小时；仅关键词开关启用时注册 |
| 关注股票行情采集 | 每 10 分钟 |
| 公告和研报监测 | 每 30 分钟 |
| 榜单与行业评分 | 每天 18:00（服务进程本地时间） |

股票日线历史不再由后台任务对全量股票回补。用户进入股票详情页时，系统只检查当前股票是否缺少最近完成交易日的数据，缺失时才按需补齐该股票的日线历史。

首页不提供任务手动触发区域，服务端也不暴露手动任务执行接口。直接调用 `JTB/tasks` 中的任务函数仅用于开发者本地测试，不属于产品功能；生产任务由调度器统一执行。

关键词功能当前作为非必要能力默认禁用，保留全部页面、接口、缓存和提取实现供后续继续开发与体验平衡。关闭状态下不展示前端入口、不开放接口、不执行新闻后的关键词提取，也不注册关键词升级任务。需要联调时必须同时设置后端 `KEYWORDS_ENABLED=true` 和前端构建变量 `VITE_KEYWORDS_ENABLED=true`。

启用后，关键词刷新基于当前新闻标题快照生成统计。相同标题集合会复用 Redis 指纹缓存，不重复调用模型，也不会重复累加 `occurrence_count`；新快照采用覆盖式词频，并过滤“投资”“市场”等低指导价值宽泛词。Redis 不可用时该机制降级到当前进程内存。

### 测试与构建

后端测试：

```powershell
Set-Location JTB
python -m unittest discover -s tests -p "test_*.py" -v
```

前端生产构建：

```powershell
Set-Location JTF
npm ci
npm run build
```

Electron Windows 安装包：

```powershell
Set-Location JTF
npm run electron:pack
```

测试套件使用内存数据库和 Milvus Stub；发布前仍应在目标 MySQL、Milvus 和 LLM 环境执行集成验证。

### 文档

- [HTTP API 接口文档](docs/API.md)
- [功能架构设计（FAD）](docs/FAD.md)
- [前端开发指导](docs/FRONTEND.md)
- [常见问题、知识库存储与版本迁移](docs/FAQ.md)
- [早期设计计划](JTBPlan.md)（仅供历史参考，部分内容已经过期）

## 服务商须知

锦途依赖外部模型、邮件、行情、新闻、公告和研报服务。服务商或部署方需要确认以下事项：

- 为 LLM、SMTP、MySQL、Redis、Milvus 和各类数据源配置独立凭据，并限制访问范围；真实密钥不得提交到仓库。
- 确认数据源的抓取、存储、展示和再分发授权，尤其是新闻、公告、研报及市场观点内容。
- LLM 服务可能接收用户提交的问题、近期对话和命中的个人知识正文；接入前应评估服务商的数据留存、训练使用、跨境传输和合规政策。
- 服务商负责生产环境的密钥轮换、访问控制、备份、日志脱敏、限流和故障监控；本项目不保证外部服务持续可用或数据绝对准确。

### 安全提示

- 不要提交 `.env`、API Key、JWT Secret、数据库密码或个人知识库文件。
- 生产环境必须替换示例 Secret，并为 MySQL、Milvus 和 Redis 配置访问控制。
- 个人知识库备份必须同时考虑加密数据和 Electron `secure-store.json`；仅复制知识 JSON 无法在新系统上解密。
- 个人知识不会在服务端数据库中持久化，但分析时命中的个人知识正文和近期对话会传给 Flask 后端，并可能继续发送给配置的外部 LLM。
- 金融分析结果仅供研究参考，不构成投资建议，也不构成任何收益承诺。