feat: complete v1 local replay workflow

.planning/MILESTONE-AUDIT-v1.0.md

@@ -0,0 +1,32 @@
+# v1.0 Milestone Audit
+
+## Verdict
+
+v1.0 milestone intent is satisfied in this worktree.
+
+## Fresh Evidence
+
+- `cd backend && uv run pytest` → 19 passed
+- `cd frontend && pnpm exec vitest run` → 18 files / 61 tests passed
+- `cd frontend && pnpm exec tsc -b` → success
+- `cd frontend && pnpm build` → success
+- Live QA:
+  - `/replay` honors replay seed `defaultTimeframe` when workspace has no `activeTimeframe`
+  - `/import` supports upload import and manual row import, both returning the shared report UI
+  - `/api/backups/download` returns a real SQLite backup file
+  - `/import` exposes local safekeeping actions for CSV/report and SQLite backup/restore
+
+## Scope Covered
+
+- Trustworthy Excel import with row-level reporting, dedupe/conflict handling, and CSV detail export
+- Minimal manual import path reusing the same importer/report pipeline
+- Single-trade replay with markers, price lines, play/pause/step/speed, and per-trade replay progress restore
+- Same-timeframe multi-symbol compare and same-symbol multi-timeframe compare in replay
+- Lightweight replay analytics panel with equity curve and distributions
+- Durable local replay workspace and layout persistence
+- Local backup/export/restore entry points for safekeeping
+
+## Residual Non-Blocking Notes
+
+- Frontend build still emits the pre-existing DaisyUI `@property` warning and bundle-size warning, but build exits 0.
+- The root workspace `.planning` remains stale relative to this approved worktree; this worktree is the milestone source of truth.

.planning/PROJECT.md

@@ -0,0 +1,77 @@
+# Retraq
+
+## What This Is
+
+Retraq 是一个面向我自己本地使用的加密货币交易复盘工具，用来把历史交易记录和对应行情对齐后做快速回看。当前仓库已经有前后端 MVP，但接下来的项目方向会收敛到一条更明确的主线：以 Excel / 手动导入为主，把单笔交易复盘体验做到顺手、可靠、可重复。
+
+## Core Value
+
+导入一笔历史交易后，能够快速把它和对应 K 线、买卖点、时间区间对齐，并顺畅完成一次高质量复盘。
+
+## Requirements
+
+### Validated
+
+- ✓ 可以从 Excel 文件导入历史交易到本地 SQLite 数据库 — existing
+- ✓ 可以从前端查看交易列表，并进入复盘视图查看图表与仓位信息 — existing
+- ✓ 可以按时间周期请求并展示 K 线数据，当前支持 5m / 15m / 1h / 4h / 1d — existing
+- ✓ 可以生成基础统计信息与分析页面，展示胜率、盈亏等复盘辅助信息 — existing
+
+### Active
+
+- [ ] 导入后的每笔交易都能更可靠地和对应 K 线、买卖点、时间范围对齐，减少“图表和交易对不上”的摩擦
+- [ ] 单笔交易复盘流程优先，用户应能在导入后快速定位、打开并回看任意一笔交易
+- [ ] 多周期对比保留在 v1 范围内，但服务于单笔交易复盘主线，而不是独立成为复杂分析工作台
+- [ ] 统计分析继续保留为辅助能力，但优先级低于复盘体验本身
+
+### Out of Scope
+
+- 多用户、认证、权限系统 — 当前产品定位是个人本地工具，不为公开用户或团队协作设计
+- 公开部署与互联网暴露 — 当前仓库和 README 都默认本地运行，且后端未按公网服务做安全收口
+- 直接接入 OKX 账户历史作为 v1 主数据入口 — v1 明确以 Excel / 手动导入为主，自动同步放到后续阶段再评估
+- 学习模块的大规模内容化建设 — 当前 README 提到学习模块，但现阶段不应压过核心复盘主线
+
+## Context
+
+- 当前仓库已经是 brownfield 项目：前端有 `Replay` / `Analysis` / `Learn` 三个页面，后端已有交易导入、K 线拉取和统计接口
+- 真实痛点已经明确：当前复盘时“图表和交易对不上”，导致回看过程断裂，影响复盘效率
+- v1 的完成标准也已明确：导入交易后，能够顺畅复盘每笔交易，而不是先追求自动同步、内容体系或团队能力
+- 现有代码库已经暴露出几类 brownfield 风险：本地 SQLite + `create_all` 缺少迁移层、K 线依赖外部交易所、图表与分析页面较重、规划文档此前缺失
+
+## Constraints
+
+- **Tech stack**: 继续沿用当前 React + TypeScript + Vite 前端，以及 FastAPI + SQLAlchemy + SQLite 后端 — 这是现有代码和运行脚本已经建立的基础
+- **Data entry**: v1 以 Excel / 手动导入为主 — 这是当前用户目标和现有仓库能力的交集
+- **Runtime model**: 本地运行优先，不按公网服务设计 — README 已明确不建议直接暴露到公网
+- **Market data dependency**: K 线数据依赖外部交易所接口（当前实现通过 CCXT / OKX 等） — 这决定了市场数据可用性与历史覆盖范围受外部服务约束
+- **Product scope**: 复盘体验优先于自动同步、教育内容和多用户能力 — 这是当前项目的核心取舍
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| 产品定位为个人本地工具 | 用户明确说明主要给自己本地用，且当前仓库也围绕本地运行组织 | — Pending |
+| v1 以 Excel / 手动导入为主 | 当前已存在导入能力，且用户不希望先把复杂度投入到账户级同步 | — Pending |
+| v1 优先把复盘体验做到最好 | 用户最痛的点是交易与图表对不上，完成标准是“导入后能顺畅复盘每笔交易” | — Pending |
+| 统计分析保留为辅助，而非主线 | 当前仓库已有分析页，但用户优先级更明确地落在 replay 体验上 | — Pending |
+| 学习模块不作为当前主路线图核心 | 当前 README 虽包含该能力，但它不直接服务当前最重要的复盘痛点 | — Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd-transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-04-11 after initialization*

.planning/REQUIREMENTS.md

@@ -0,0 +1,95 @@
+# Requirements: Retraq
+
+**Defined:** 2026-04-11
+**Core Value:** 导入一笔历史交易后，能够快速把它和对应 K 线、买卖点、时间区间对齐，并顺畅完成一次高质量复盘。
+
+## v1 Requirements
+
+### Import
+
+- [ ] **IMPT-01**: User can import historical trades from an Excel file into the local system
+- [ ] **IMPT-02**: User can see row-level import errors when a trade record cannot be imported
+- [ ] **IMPT-03**: User can import trades without creating duplicate records for the same source rows
+- [ ] **IMPT-04**: User can have imported trade timestamps normalized into a consistent internal time standard
+- [ ] **IMPT-05**: User can review an import report that summarizes successful rows, failed rows, and duplicate handling
+
+### Replay
+
+- [ ] **REPL-01**: User can open any single trade from the trade list directly into replay view
+- [ ] **REPL-02**: User can have replay automatically aligned to the correct symbol, time window, and default timeframe for the selected trade
+- [ ] **REPL-03**: User can see entry and exit markers, plus relevant price lines, on the replay chart for the selected trade
+- [ ] **REPL-04**: User can control replay with play, pause, step, and speed adjustment actions
+
+### Compare
+
+- [ ] **COMP-01**: User can compare the selected trade across multiple timeframes for the same symbol
+- [ ] **COMP-02**: User can keep compared charts synchronized by visible time range and crosshair position
+- [ ] **COMP-03**: User can change the timeframe of the comparison chart without leaving the replay flow
+
+### Analytics
+
+- [ ] **ANLY-01**: User can view core replay-supporting metrics including win rate, PnL, profit-loss ratio, and equity curve
+- [ ] **ANLY-02**: User can view distributions by time period and by trading symbol to support review
+- [ ] **ANLY-03**: User can view drawdown-related statistics for imported trades
+
+### Local State
+
+- [ ] **STAT-01**: User can return to the last-used replay layout and filters in a later session
+- [ ] **STAT-02**: User can resume replay from the previously saved progress of a selected trade
+- [ ] **STAT-03**: User can export or back up local review data for safekeeping
+
+## v2 Requirements
+
+### Compare Expansion
+
+- **COMP-04**: User can compare multiple different symbols on screen at the same time
+
+### Advanced Analysis
+
+- **ANLY-04**: User can view advanced attribution and behavior analysis beyond core replay metrics
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Multi-user accounts and permissions | Product is explicitly scoped as a personal local tool |
+| Cloud sync and remote backup service | v1 should stay local-first and avoid premature sync complexity |
+| Direct OKX account sync as primary v1 input | v1 input is intentionally Excel/manual import first |
+| Public SaaS deployment hardening | Current product is not being planned as a public service |
+| Live trading, paper trading, or order routing | Replay and review are the goal, not execution |
+| Education hub expansion | Learning content is not part of the current core replay milestone |
+| Generic BI/dashboard builder | Replay flow matters more than broad analytics surface area |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| IMPT-01 | Phase 1: Import Reliability & Schema Evolution | Pending |
+| IMPT-02 | Phase 1: Import Reliability & Schema Evolution | Pending |
+| IMPT-03 | Phase 1: Import Reliability & Schema Evolution | Pending |
+| IMPT-04 | Phase 1: Import Reliability & Schema Evolution | Pending |
+| IMPT-05 | Phase 1: Import Reliability & Schema Evolution | Pending |
+| REPL-01 | Phase 2: Single-Trade Replay Core | Pending |
+| REPL-02 | Phase 2: Single-Trade Replay Core | Pending |
+| REPL-03 | Phase 2: Single-Trade Replay Core | Pending |
+| REPL-04 | Phase 2: Single-Trade Replay Core | Pending |
+| STAT-02 | Phase 2: Single-Trade Replay Core | Pending |
+| COMP-01 | Phase 3: Multi-Timeframe Compare & Lightweight Analytics | Pending |
+| COMP-02 | Phase 3: Multi-Timeframe Compare & Lightweight Analytics | Pending |
+| COMP-03 | Phase 3: Multi-Timeframe Compare & Lightweight Analytics | Pending |
+| ANLY-01 | Phase 3: Multi-Timeframe Compare & Lightweight Analytics | Pending |
+| ANLY-02 | Phase 3: Multi-Timeframe Compare & Lightweight Analytics | Pending |
+| ANLY-03 | Phase 3: Multi-Timeframe Compare & Lightweight Analytics | Pending |
+| STAT-01 | Phase 4: Local UX Polish & Performance Hardening | Pending |
+| STAT-03 | Phase 4: Local UX Polish & Performance Hardening | Pending |
+
+**Coverage:**
+- v1 requirements: 18 total
+- Mapped to phases: 18
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-04-11*
+*Last updated: 2026-04-11 after initial definition*

.planning/ROADMAP.md

@@ -0,0 +1,91 @@
+# Roadmap: Retraq
+
+## Overview
+
+Retraq is a local-first crypto trade replay tool. v1 focuses on one tight workflow: import historical trades, align each trade to the right market window, compare a few supporting timeframes, and keep the local review state stable enough for repeated use.
+
+## Phases
+
+- [x] **Phase 1: Import Reliability & Schema Evolution** - Make Excel/manual import trustworthy and keep local trade data stable.
+- [x] **Phase 2: Single-Trade Replay Core** - Open any trade fast and land on the correct replay window.
+- [x] **Phase 3: Multi-Timeframe Compare & Lightweight Analytics** - Add supporting comparison and metrics without turning into a dashboard.
+- [x] **Phase 4: Local UX Polish & Performance Hardening** - Keep the app responsive and remember local review state.
+
+## Phase Details
+
+### Phase 1: Import Reliability & Schema Evolution
+**Goal**: Users can reliably import historical trades and trust the stored data.
+**Depends on**: Nothing (first phase)
+**Requirements**: IMPT-01, IMPT-02, IMPT-03, IMPT-04, IMPT-05
+**Success Criteria** (what must be TRUE):
+  1. User can import trades from an Excel file into the local system.
+  2. User can see row-level errors for records that fail to import.
+  3. User can re-import source rows without creating duplicate trades.
+  4. User can review an import report that summarizes successes, failures, duplicates, and normalized timestamps.
+**Plans**: 5 plans
+Plans:
+- [x] 01-01-PLAN.md — Backend test/migration foundation and locked import contracts
+- [x] 01-02-PLAN.md — Frontend test foundation and locked import report types
+- [x] 01-03-PLAN.md — Structured backend importer, dedupe/conflict logic, and report API
+- [x] 01-04-PLAN.md — Import entry/report UI for Phase 1 only
+- [x] 01-05-PLAN.md — Runtime wiring, route integration, and end-to-end verification
+**UI hint**: yes
+
+### Phase 2: Single-Trade Replay Core
+**Goal**: Users can open a single trade and replay it in the correct context.
+**Depends on**: Phase 1
+**Requirements**: REPL-01, REPL-02, REPL-03, REPL-04, STAT-02
+**Success Criteria** (what must be TRUE):
+  1. User can open any trade from the list directly into replay.
+  2. Replay opens on the correct symbol, time window, and default timeframe for the selected trade.
+  3. User can see entry/exit markers and relevant price lines on the chart.
+  4. User can control play, pause, step, and speed, and resume the selected trade from saved progress.
+**Plans**: 4 plans
+- [x] 02-01-PLAN.md — Replay session contract and local progress primitives
+- [x] 02-02-PLAN.md — Replay bootstrap and TradeList handoff
+- [x] 02-03-PLAN.md — Replay transport and controls
+- [x] 02-04-PLAN.md — Replay flow integration and smoke coverage
+**UI hint**: yes
+
+### Phase 3: Multi-Timeframe Compare & Lightweight Analytics
+**Goal**: Users can compare a trade across timeframes and read basic review metrics.
+**Depends on**: Phase 2
+**Requirements**: COMP-01, COMP-02, COMP-03, ANLY-01, ANLY-02, ANLY-03
+**Success Criteria** (what must be TRUE):
+  1. User can compare the selected trade across multiple timeframes for the same symbol.
+  2. User can change the comparison timeframe without leaving replay.
+  3. Compared charts stay synchronized by visible time range and crosshair position.
+  4. User can view win rate, PnL, profit-loss ratio, equity curve, time/symbol distributions, and drawdown stats.
+**Plans**: 4 plans
+Plans:
+- [x] 03-01-PLAN.md — Compare mode contract, pane resolver, and mode-aware annotation rules
+- [x] 03-02-PLAN.md — Same-symbol multi-timeframe compare path and cross-timeframe sync
+- [x] 03-03-PLAN.md — Same-timeframe multi-symbol compare stabilization under explicit mode switching
+- [x] 03-04-PLAN.md — Lightweight replay analytics panel and final Phase 3 smoke coverage
+**UI hint**: yes
+
+### Phase 4: Local UX Polish & Performance Hardening
+**Goal**: Users can keep their local replay workspace lightweight, persistent, and pleasant to use.
+**Depends on**: Phase 3
+**Requirements**: STAT-01, STAT-03
+**Success Criteria** (what must be TRUE):
+  1. User can return later and find the last-used replay layout and filters restored.
+  2. User can export or back up local review data for safekeeping.
+**Plans**: 3 plans
+Plans:
+- [x] 04-01-PLAN.md — Replay workspace/filter persistence bootstrap
+- [x] 04-02-PLAN.md — Replay chart/layout + analytics panel persistence
+- [x] 04-03-PLAN.md — Local backup/export/restore entry point on `/import`
+**UI hint**: yes
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Import Reliability & Schema Evolution | 5/5 | Approved in worktree | 2026-04-11 |
+| 2. Single-Trade Replay Core | 4/4 | Completed in worktree | 2026-04-11 |
+| 3. Multi-Timeframe Compare & Lightweight Analytics | 4/4 | Completed in worktree | 2026-04-11 |
+| 4. Local UX Polish & Performance Hardening | 3/3 | Completed in worktree | 2026-04-11 |

.planning/STATE.md

@@ -0,0 +1,87 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+status: completed
+stopped_at: Milestone v1.0 completed in worktree
+last_updated: "2026-04-11T11:40:00.000Z"
+last_activity: 2026-04-11 — v1.0 milestone completed after closeout gap fixes and fresh verification
+progress:
+  total_phases: 4
+  completed_phases: 4
+  total_plans: 16
+  completed_plans: 16
+  percent: 100
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-04-11)
+
+**Core value:** 导入一笔历史交易后，能够快速把它和对应 K 线、买卖点、时间区间对齐，并顺畅完成一次高质量复盘。
+**Current focus:** Milestone complete
+
+## Current Position
+
+Phase: complete
+Plan: closeout finished
+Status: v1.0 milestone complete in worktree
+Last activity: 2026-04-11 — fresh backend/frontend verification and Oracle closeout review passed
+
+Progress: [██████████] 100%
+
+## Performance Metrics
+
+**Velocity:**
+
+- Total plans completed: 16
+- Average duration: -
+- Total execution time: -
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| 1. Import Reliability & Schema Evolution | 5 | 5 | - |
+| 2. Single-Trade Replay Core | 4 | 4 | - |
+| 3. Multi-Timeframe Compare & Lightweight Analytics | 4 | 4 | - |
+| 4. Local UX Polish & Performance Hardening | 3 | 3 | - |
+
+**Recent Trend:**
+
+- Last 5 plans: 03-04, 04-01, 04-02, 04-03, closeout-gaps
+- Trend: Advancing
+
+## Accumulated Context
+
+### Decisions
+
+Recent decisions affecting current work:
+
+- [Phase 1]: Excel/manual import is the trusted v1 data entry path.
+- [Phase 1]: Structured import reports, CSV detail export, and backup-first migration wiring are now live in the worktree.
+- [Phase 2]: Single-trade replay was advanced from the existing replay shell rather than rebuilt from scratch.
+- [Phase 2]: Replay entry precedence is `route > local restore > latest trade > empty`, with browser-local replay progress persistence.
+- [Phase 2]: Playback uses a single shared cursor with `play / pause / step / reset / 1x-2x-4x` controls.
+- [Phase 3]: Replay compare now supports both same-timeframe multi-symbol and same-symbol multi-timeframe modes on a single secondary pane.
+- [Phase 3]: Replay analytics stays lightweight and collapsible inside the replay shell rather than reusing the full analysis dashboard UI.
+- [Phase 3]: Multi-timeframe compare and analytics stay supportive, not dominant.
+- [Phase 4]: Local state and polish stay in scope; sync/collaboration remain out of scope.
+- [Closeout]: Replay seed `defaultTimeframe` is now honored after workspace precedence.
+- [Closeout]: Manual row import now reuses the same importer/report pipeline as upload import.
+
+### Pending Todos
+
+- None
+
+### Blockers/Concerns
+
+- Root workspace `.planning` remains stale relative to the approved worktree and should not be used as the milestone source of truth.
+
+## Session Continuity
+
+Last session: 2026-04-11T11:40:00.000Z
+Stopped at: Milestone complete
+Resume file: .planning/MILESTONE-AUDIT-v1.0.md