mcp-fashion-server

⚠️ 所有现有工作成果均已删除 — 此存储库已在 fix/rewrite-windows-toast 分支上完全重建 v5 Trader 项目。初始化步骤请参阅 docs/GIT_RESET.md。

v5 Trader — FastAPI + Tauri 重写版

这是一款面向韩国股票超短线 v5 策略的本地专用桌面应用。核心策略／风险引擎仍使用 Python，但 UI 已改为 Tauri + React（桌面端），后端则拆分为 FastAPI。不支持自动交易，所有订单都必须经过用户明确批准。

• 操作系统：Windows 10/11（推荐）
• 后端：Python 3.11、FastAPI、uvicorn
• 前端：React + Vite + Tauri 2（需要 Rust toolchain）
• 架构：Ports & Adapters（复用 core/ports/adapters）
• 打包：通过 npm run tauri build 生成 exe/msi（图标以 Base64 保存，并在构建时还原）

---

文件夹结构

v5_rewrite/
├─ api/                # FastAPI 진입점 및 Pydantic 스키마
├─ app_desktop/        # Tauri + React 프론트엔드 (Vite 기반)
│  ├─ src/             # React 컴포넌트 및 페이지
│  └─ src-tauri/       # Tauri 설정, Rust 엔트리
├─ core/, ports/, adapters/, config/, tests/  # 기존 전략/어댑터 계층
├─ scripts/            # dev/bundle 유틸(아이콘 복원 등)
└─ .vscode/            # VS Code 설정/태스크/런치 구성

---

必备要求

• Python 3.11
• Node.js 18 或更高版本 + npm
• Rust stable toolchain（用于构建 Tauri）
• 若要在 Windows 环境中使用通知，需要安装 pywin32、winotify 并启用 Windows 通知中心

---

快速开始

# 1) 가상환경 + 백엔드 의존성
py -3.11 -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

# 2) 프론트엔드 의존성
cd app_desktop
npm install
cd ..

# 3) 개발 모드 실행 (FastAPI + Tauri 동시)
# PowerShell: 백엔드 uvicorn + Tauri dev 프로세스를 병렬로 기동
powershell -ExecutionPolicy Bypass -File scripts\dev.ps1

# 혹은 VS Code: Ctrl+Shift+B → dev:desktop(all)
# 혹은 F5 → “Dev: Desktop (API + Tauri)” 복합 디버그 실행

启动后，FastAPI 将在 http://127.0.0.1:5173 上运行，Tauri 开发窗口（或 WebView）也会自动打开。

---

主要功能

后端（FastAPI）

• GET /api/health – 健康检查
• GET /api/settings – 提供 watch/trade/chart/risk 默认值
• GET /api/holdings – 持仓 + 损益% + exit 信号摘要（名称缓存使用 hts_kor_isnm + SQLite）
• GET /api/reco?top=N – v5 策略 Top N 推荐（代码／名称／分数／原因）
• GET /api/candles – 行情蜡烛图数据（选择 mock/KIS）
• GET /api/name – 查询股票名称（使用缓存）
• POST /api/order – 仅将设置了批准标记的订单委托给经纪商适配器

前端（Tauri + React）

• 交易标签页：股票搜索、买入／卖出切换、数量／金额切换、限价 ±tick、快捷 % 按钮、批准勾选框、结果提示
• 图表标签页：蜡烛图 + 成交量、SMA20/60、RSI14 切换、周期选择（基于设置）
• 推荐标签页：Top N 卡片（名称／代码／分数／迷你火花线图）+“前往交易”按钮
• 持仓／通知标签页：选择表格行 → 滑动详情面板（蜡烛图、建议卖出、卖出表单）。再次确认禁止自动交易的政策
• 通知：使用 Tauri Notification 插件通过桌面通知提示风险信号／订单结果（也可同时使用 Windows Toast）

---

测试

pytest -q

所有核心逻辑（core/strategy_v5、risk、adapters、wiring）的覆盖情况均与迁移到 FastAPI 之前相同。

---

订单与 KIS 集成须知

1. 复制 config/kis.keys.toml.example 并创建 config/kis.keys.toml（禁止提交到 Git）
2. 将 [market]、[broker] 部分设为 "kis" 后，FastAPI 会加载 KIS 适配器
3. 即使只填写 appkey/appsecret，运行时也会自动获取 OAuth 令牌（缓存 Bearer ...、expires_at）
4. 只有在 approve=true 时，POST /api/order 才会将订单发送给经纪商；实盘模式下还会再次检查当日亏损限制、数量和批准状态
5. 所有结果都会记录到 SQLite 的 trades/logs 表中，重复通知每天最多发送一次

---

构建与发布

桌面程序包（Tauri）

# 아이콘(Base64) → ico 복원 후 빌드
powershell -ExecutionPolicy Bypass -File scripts\restore_icon.ps1
npm run tauri build        # (또는 루트에서 build_exe.ps1 실행)

• 生成文件：app_desktop/src-tauri/target/release/ 中的 .exe / .msi
• build_exe.ps1 会检查 .venv → 安装后端依赖 → 还原图标 → npm run tauri build

GitHub Actions（可选）

.github/workflows/release.yml 工作流会在推送 v*.*.* 标签时自动构建 EXE 并上传到发布页面。

---

开发辅助工具

• scripts/dev.ps1：同时启动 FastAPI 服务和 Tauri dev 进程
• .vscode/tasks.json：一键创建 venv、安装依赖、构建／测试前端
• .vscode/launch.json：组合运行 FastAPI 调试器和 Tauri dev
• run.bat：在 Windows 上调用 PowerShell 脚本并准备 dev 环境

---

Windows 通知

• 后端保留原有的 NotifierWindows 适配器（按 winotify → PowerShell BurntToast → win10toast(threaded=False) 的顺序）。
• Tauri 前端通过 tauri-plugin-notification 发送通知；如果没有权限，会在首次运行时请求。
• 设置 V5_DISABLE_WIN10TOAST=1 环境变量后，后端将停用 win10toast。

---

故障排除

问题	解决方法
FastAPI 无法启动	使用 pip install -r requirements.txt 安装后端依赖，并在 VS Code 设置中确认 .venv 的 Python 路径。
前端构建失败	确认 Node 版本为 18 或更高，然后在 app_desktop 中重新运行 npm install。如果没有 Rust toolchain，则需要安装 rustup-init。
未显示通知	确认 Windows 通知中心已开启／专注模式已关闭。远程桌面环境可能会受到限制。
KIS 401/500 错误	检查密钥文件路径／权限，并查看 FastAPI 日志。令牌会自动重新签发，失败时会输出警告。

---

版本与变更记录

• CHANGELOG.md
• VERSION

如需贡献／咨询，请提交 PR 或问题。v5 Trader 的目标是在遵守“禁止自动交易 + 用户批准式辅助”原则的同时，升级桌面使用体验。