# TradingAgents-CN v1.0.0-preview 发布说明

> 状态：预览版（Preview）
> 发布分支：v1.0.0-preview
> 重点：多应用架构预览（FastAPI + Vite + 现有 Streamlit 并存过渡）、统一配置与日志、文档与脚本体系升级

## 🎯 概览
v1.0.0-preview 标志着项目从“单一 Streamlit 应用 + tradingagents 库”演进为“后端 API + 现代前端 + 现有 Streamlit 共存”的多应用架构：
- 新增 FastAPI 后端（app/）：分层清晰（routers/services/middleware/core），统一配置与日志，提供分析/筛选/报告等 API
- 新增 Vite + TypeScript 前端（frontend/）：作为新一代 Web UI 的探索实现；与现有 Streamlit 并存过渡
- 完善统一配置（pydantic-settings）与结构化日志；新增运维与验证脚本

## 🚀 主要变化

### 1) 多应用架构（新增）
- app/（FastAPI）：
  - core：统一配置、数据库（MongoDB/motor）、Redis 客户端、日志设置
  - routers：analysis/config/auth/reports/screening/... 模块化路由
  - services：analysis、screening、favorites、queue、redis-progress 等服务化实现
  - middleware：请求日志、限流、跨域、统一异常与响应格式
  - worker：后台任务与队列处理（如进度、缓存、批处理）
- frontend/（Vite + TS）：
  - 与后端 API 对接的现代前端雏形；保留调试页与测试用 HTML
  - 现阶段与 Streamlit 前端并存，逐步替换为统一体验

### 2) 统一配置与可观测性
- 使用 pydantic-settings 实现“单一事实源”式配置管理（支持 dotenv + 环境变量）
- 增强 logging.toml（本地与 Docker）并统一日志入口（utils/logging_manager）
- 新增脚本与文档：检查系统状态、统一日志迁移、安装/启动助手等

### 3) 核心库增强
- tradingagents/ 下 dataflows、tools/analysis/indicators、graph/trading_graph 等模块增强
- 统一数据工具与缓存策略，保持对上层应用（Web/API）的向后兼容

### 4) 文档与脚本
- docs/ 体系扩展：开发流程、分支保护、紧急预案、架构设计、数据目录迁移等
- 新增/完善启动与验证脚本：start_backend.py、start_frontend.py、install_pdf_tools.py 等

## ⚠️ 注意事项（预览版）
- 与现有 Streamlit Web 并存过渡期：
  - 端口与依赖可能存在冲突，请按 BACKEND_STARTUP.md/README 指引运行
  - 新前端为预研阶段，功能覆盖逐步补齐
- 依赖管理：建议以 pyproject.toml 为主；requirements.txt 用于容器构建
- 仓库卫生：已加强 .gitignore；建议后续清理历史中已追踪的大体积二进制/归档文件（见“升级建议”）

## 🔧 升级与启动

### 本地开发（推荐 Python 3.10+）
1. 升级 pip：`python -m pip install --upgrade pip`
2. 安装依赖：`pip install -e .`
3. 启动 Streamlit Web：`python start_web.py`
4. 启动 FastAPI 后端：`python start_backend.py`
5. 启动新前端（如需）：
   - `cd frontend && npm install`
   - `npm run dev`

### Docker 部署（参考 docker-compose.yml）
- 一键启动：`docker-compose up -d --build`
- 仅启数据库：`docker-compose up -d mongodb redis mongo-express redis-commander`

## 🧪 验证
- 核心路径启动脚本通过本地验证：
  - Streamlit：端口 8501
  - FastAPI：默认端口 8000（可在 .env/环境变量调整）
  - 前端（Vite）：默认端口 5173（可在前端配置调整）
- 提供系统状态检查与日志检查脚本（scripts/validation、scripts/maintenance）

## 📚 相关文档
- docs/DEVELOPMENT_WORKFLOW.md
- docs/GITHUB_BRANCH_PROTECTION.md
- docs/EMERGENCY_PROCEDURES.md
- docs/releases/CHANGELOG.md（已补充 v1.0.0-preview 概览）
- docs/releases/v0.1.16-design-document.md（设计细节）

## ✅ 兼容性与影响面
- 对 tradingagents 库 API 基本无破坏性变更；
- Web 层（Streamlit）保持现有行为；新前端逐步补齐页面与交互；
- 部署脚本与文档更加标准化，便于后续 CI/CD 与生产化。

## 🗺️ 后续路线（建议）
- 明确新前端的替换计划与共用鉴权/配置/日志方案
- 按服务域拆分 app/services 超长模块，形成子包并完善单元测试
- 清理仓库中历史已追踪的大文件（安装包、归档、临时数据），降低仓库体积

