v1.0: Backend modularization, frontend component optimization, Chinese docs

.planning/MILESTONES.md

@@ -0,0 +1,23 @@
+# Milestones
+
+## v1.0 QueryGPT 优化迭代 (Shipped: 2026-03-30)
+
+**Phases completed:** 3 phases, 13 plans, 33 tasks
+
+**Key accomplishments:**
+
+- Summary:
+- Objective:
+- One-liner:
+- One-liner:
+- One-liner:
+- What:
+- Critical Issues:
+- One-liner:
+- File:
+- Result:
+- Files Created:
+- One-liner:
+- Completed:
+
+---

.planning/PROJECT.md

@@ -0,0 +1,91 @@
+# QueryGPT 精进
+
+## What This Is
+
+QueryGPT 是一个开源 AI 数据库助手，用自然语言提问，自动生成只读 SQL 并执行，返回结果、分析和图表。支持语义层定义和 schema 关系图可视化。v1.0 优化迭代已完成：后端架构模块化、前端组件拆分与性能优化、中文文档。
+
+## Core Value
+
+自然语言查询数据库并获得完整的结果分析——这个核心流程必须流畅可靠。
+
+## Requirements
+
+### Validated
+
+- ✓ 自然语言转 SQL 并执行 — existing
+- ✓ 自动 Python 分析和图表生成 — existing
+- ✓ 语义层（业务术语定义） — existing
+- ✓ Schema 关系图可视化拖拽连接 — existing
+- ✓ 多模型支持（OpenAI、Anthropic、Ollama、自定义） — existing
+- ✓ 多数据库支持（SQLite、MySQL、PostgreSQL） — existing
+- ✓ SSE 实时流式响应 — existing
+- ✓ SQL/Python 自动修复重试 — existing
+- ✓ 配置导入导出 — existing
+- ✓ i18n 国际化支持（next-intl + 后端 i18n） — existing
+- ✓ Docker 部署支持 — existing
+- ✓ 桌面客户端（Electron） — existing
+- ✓ CI/CD（GitHub Actions 多层测试） — existing
+- ✓ gptme_engine.py 服务模块拆分（SQLExecutor、PythonSandbox、ResultProcessor、VisualizationEngine） — Phase 1
+- ✓ 全局异常处理标准化（具体异常类型 + structlog） — Phase 1
+- ✓ 加密 key 安全配置（非开发环境强制显式配置） — Phase 1
+- ✓ 前端大组件拆分（ChatArea 408→132行、SchemaSettings 618→357行） — Phase 2
+- ✓ 聊天消息分页和虚拟滚动（游标分页 + TanStack Virtual） — Phase 2
+- ✓ Schema 可视化性能优化（useMemo + useSchemaLayout hook） — Phase 2
+- ✓ 中文 README 文档（README.zh.md 388行，术语与 zh.json 一致） — Phase 3
+
+### Active
+
+（无 — v1 milestone 全部需求已完成）
+
+### Out of Scope
+
+- 多租户/用户认证 — 个人使用，不需要
+- 实时协作 — 单人使用场景
+- 写操作 SQL — 核心设计决策，只读更安全
+- 移动端适配 — 桌面场景足够
+- 批量查询执行 — 个人使用不需要
+
+## Context
+
+- v1.0 优化迭代完成：后端 990 行单体→5 模块，前端大组件拆分，消息分页+虚拟滚动，中文文档
+- 前后端分离架构：Next.js 15 + FastAPI，SSE 通信
+- 代码库映射已完成，见 `.planning/codebase/`
+- 已解决技术债：大文件拆分、泛异常处理→具体异常、消息分页
+- 剩余技术债：Python 沙箱加固、查询缓存、E2E 测试较薄
+
+## Constraints
+
+- **Tech Stack**: 保持现有技术栈（Next.js + FastAPI + SQLAlchemy），不做大规模技术迁移
+- **兼容性**: 重构不能破坏现有功能，需要保持 API 兼容
+- **个人项目**: 以实用为主，不需要过度工程化
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| 优先架构优化而非新功能 | 代码质量问题会持续拖慢后续开发 | ✓ Good — Phase 1 完成后代码结构清晰 |
+| 安全加固降优先级 | 个人使用，风险可控 | ✓ Good — 基础安全已在 Phase 1 处理 |
+| 保持现有技术栈 | 避免引入迁移风险，专注于打磨 | ✓ Good |
+| 直接模块提取而非依赖注入 | 简单直接，风险低 | ✓ Good — Phase 1 验证 |
+| TanStack Virtual 虚拟滚动 | 1000+ 消息场景需要，TanStack 生态一致 | ✓ Good — 60 FPS 验证 |
+| 中文 README 镜像英文结构 | 便于 diff 同步维护 | ✓ Good — 388 行对 386 行 |
+
+## 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-03-30 after v1.0 milestone*

.planning/RETROSPECTIVE.md

@@ -0,0 +1,57 @@
+# Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+## Milestone: v1.0 — QueryGPT 优化迭代
+
+**Shipped:** 2026-03-30
+**Phases:** 3 | **Plans:** 13 | **Tasks:** 33
+
+### What Was Built
+- 后端 990 行单体拆分为 5 个服务模块（SQLExecutor、PythonSandbox、ResultProcessor、VisualizationEngine、GptmeEngine）
+- 前端 ChatArea 408→133 行、SchemaSettings 618→357 行组件拆分
+- 消息分页 API + TanStack Virtual 虚拟滚动（1000+ 消息 60 FPS）
+- Schema 可视化性能优化（useMemo 节点/边、useSchemaLayout hook）
+- 全局异常处理标准化 + 加密 key 安全配置
+- 完整中文 README 文档（388 行，术语与应用内 zh.json 一致）
+
+### What Worked
+- 3 阶段 COARSE 粒度划分合理，后端→前端→文档自然递进
+- Wave 并行执行显著提升效率（Phase 2 Wave 1 两个 agent 同时工作）
+- 详细的 PLAN.md 任务分解让 executor agent 一次性完成，极少返工
+- 验证阶段发现并修复了 5 个 bug，证明验证步骤有价值
+
+### What Was Inefficient
+- Phase 2 Wave 1 首次 worktree 失败（git config lock），需要重试
+- 部分 SUMMARY.md 的 one_liner 字段为空，影响自动提取
+- Phase 3（纯文档翻译）走完整 research→plan→verify 流程略显冗余
+
+### Patterns Established
+- TYPE_CHECKING guards 防循环导入（Phase 1 验证）
+- useMemo + useCallback 组合优化 React 渲染性能
+- 中文 README 镜像英文结构便于 diff 同步维护
+
+### Key Lessons
+1. 纯文档/翻译任务可以用 `--skip-research` 减少开销
+2. Git worktree 并行执行时需处理 config lock 竞争
+3. 组件拆分时同步做类型检查和 lint 验证能提前发现问题
+
+### Cost Observations
+- Model mix: 主要使用 Opus 4.6 (executor, verifier, planner)
+- Sessions: 1 session 完成全部 3 个阶段
+- Notable: Phase 3（1 plan 文档任务）全流程约 15 分钟
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Phases | Plans | Key Change |
+|-----------|--------|-------|------------|
+| v1.0 | 3 | 13 | 首次使用 GSD workflow，建立基线 |
+
+### Top Lessons (Verified Across Milestones)
+
+1. COARSE 粒度（3-5 phases）适合个人项目优化迭代
+2. 详细的 PLAN.md 任务分解 > 简短指令，减少 executor 返工

.planning/ROADMAP.md

@@ -0,0 +1,30 @@
+# Roadmap: QueryGPT 精进
+
+## Milestones
+
+- ✅ **v1.0 QueryGPT 优化迭代** — Phases 1-3 (shipped 2026-03-30)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 QueryGPT 优化迭代 (Phases 1-3) — SHIPPED 2026-03-30</summary>
+
+- [x] Phase 1: Backend Service Decomposition (7/7 plans) — gptme_engine.py 990行单体→5模块
+- [x] Phase 2: Frontend Component Optimization (5/5 plans) — 组件拆分 + 分页 + 虚拟滚动
+- [x] Phase 3: Chinese Documentation (1/1 plan) — README.zh.md 完整中文文档
+
+Full details: [milestones/v1.0-ROADMAP.md](milestones/v1.0-ROADMAP.md)
+
+</details>
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Backend Service Decomposition | v1.0 | 7/7 | ✓ Complete | 2026-03-29 |
+| 2. Frontend Component Optimization | v1.0 | 5/5 | ✓ Complete | 2026-03-30 |
+| 3. Chinese Documentation | v1.0 | 1/1 | ✓ Complete | 2026-03-30 |
+
+---
+
+*Next milestone: TBD — run `/gsd:new-milestone` to start*

.planning/STATE.md

@@ -0,0 +1,143 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+current_phase: 03
+current_plan: Not started
+status: v1.0 milestone complete
+last_updated: "2026-03-30T02:39:49.673Z"
+progress:
+  total_phases: 3
+  completed_phases: 3
+  total_plans: 13
+  completed_plans: 13
+  percent: 92
+---
+
+# State: QueryGPT 精进
+
+**Milestone:** QueryGPT 优化迭代
+**Initialized:** 2026-03-29
+**Granularity:** COARSE (3-5 phases)
+
+## Project Reference
+
+**Core Value:** 自然语言查询数据库并获得完整的结果分析——这个核心流程必须流畅可靠。
+
+**Current Focus:** Phase 03 — chinese-documentation
+
+**Key Constraints:**
+
+- Maintain existing technology stack (Next.js + FastAPI + SQLAlchemy)
+- Preserve API compatibility — refactoring is internal, contracts unchanged
+- Optimize code quality and maintainability, not new features (v2 scope)
+
+## Current Position
+
+Phase: 03 (chinese-documentation) — EXECUTING
+Plan: 1 of 1
+**Milestone Phase:** Roadmap
+**Current Phase:** 03
+**Current Plan:** Not started
+**Current Status:** Ready to plan
+
+**Progress:**
+
+[█████████░] 92%
+[========                                        ] 0% (0/3 phases started)
+
+```
+
+## Performance Metrics
+
+| Metric | Target | Current | Status |
+|--------|--------|---------|--------|
+| Requirement Coverage | 100% | 100% | ✓ |
+| Phase Count (COARSE) | 3-5 | 3 | ✓ |
+| Success Criteria per Phase | 2-5 | 4-5 | ✓ |
+| Phase 01 P01 | 8m | 2 tasks | 1 files |
+| Phase 01 P04 | 900 | 3 tasks | 3 files |
+| Phase 01 P05 | 5 minutes | 1 tasks | 2 files |
+| Phase 01 P06b | 45m | 3 tasks | 6 files |
+| Phase 01 P06 | 25 | 2 tasks | 3 files |
+| Phase 02 P01 | 266 | 5 tasks | 7 files |
+| Phase 02 P04 | 10 | 4 tasks | 4 files |
+| Phase 03 P01 | 15 | 2 tasks | 2 files |
+
+## Accumulated Context
+
+### Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| 3-phase structure (COARSE) | Requirements naturally group: backend → frontend → docs. No artificial compression needed. | Phases 1-3 identified |
+| BACK-06 and FRONT-07 paired with refactoring | Bug fixes during refactoring are part of refactoring work, not separate phases | Reduces phase count, maintains coherence |
+| Phase 2 depends on Phase 1 | Message pagination API requires backend service layer stability | Sequential execution unavoidable |
+| Phase 3 (docs) independent | Chinese documentation can run in parallel with phases 1-2 | No critical path impact |
+
+### Risks & Mitigations
+
+| Risk | Mitigation | Owner |
+|------|-----------|-------|
+| Circular imports during backend decomposition (Pitfall 1) | Use TYPE_CHECKING guards, enforce single-direction dependencies, use pycycle CI check | Phase 1 planning |
+| Cache invalidation completeness (Pitfall 2) | Will enumerate all cache invalidation paths during Phase 3 (deferred to v2) | Phase 3 of v2 |
+| API contract breakage | Write compatibility tests for SSE event format before refactoring | Phase 1 planning |
+| Chinese documentation sync drift (Pitfall 6) | Establish single-source-of-truth, version both docs | Phase 3 planning |
+
+### Research Flags
+
+From SUMMARY.md, phases with special research needs:
+
+1. **Phase 1:** gptme_engine.py dependency mapping before decomposition
+2. **Phase 3 (v2):** Cache invalidation path enumeration (all mutation points)
+3. **Phase 2:** TanStack Virtual + infinite pagination integration patterns
+
+### Decisions Made
+
+- [Phase 01-02]: Extracted PythonSandbox module with security analysis and timeout protection (PythonSecurityAnalyzer integration)
+- [Phase 01-02]: Extracted ResultProcessor module with graceful partial artifact extraction (collects errors without failing)
+- [Phase 01-02]: Used specific exception types per D-04: ValueError for security, RuntimeError for execution errors
+- [Phase 01-02]: TYPE_CHECKING guards prevent circular imports while maintaining type safety
+- [Phase 01-02]: Both modules use structlog for detailed diagnostic logging per D-03 pattern
+- [Phase 01]: Error handling standardized: specific exception types per D-04, safe responses per D-05, structured logging per D-03
+- [Phase 01]: Phase 01 Complete: All tests passing (75/75), API compatibility verified (BACK-02), service integration validated (BACK-06). Ready for Phase 2.
+- [Phase 02-01]: ChatArea decomposed into 7 focused sub-components, reducing 408 → ~100 lines per component
+- [Phase 02-02]: SchemaSettings decomposed into 4 focused sub-components, reducing 618 → ~100 lines, total 42% code reduction
+- [Phase 02-03]: Message pagination API + infinite query with TanStack Virtual for 1000+ messages at 60 FPS
+- [Phase 02-04]: Schema memoization (useMemo for nodes/edges, useSchemaLayout for layout saves with debouncing)
+- [Phase 02]: Phase 02 Complete: 7 requirements satisfied (FRONT-01 through FRONT-07), 5 bugs fixed, type checking/linting pass. Ready for Phase 3.
+
+### TODOs
+
+- [ ] User approves roadmap structure
+- [ ] Plan Phase 1: Backend service decomposition
+- [ ] Plan Phase 2: Frontend component optimization
+- [ ] Plan Phase 3: Chinese documentation
+
+### Blockers
+
+None currently.
+
+## Session Continuity
+
+**Last Update:** 2026-03-30 (Phase 02 completion)
+**Last Action:** Completed Phase 02 Plan 05: Final verification and testing
+
+**Phase 02 Complete Summary:**
+
+- Plan 02-01: ChatArea decomposed into 7 focused sub-components (1 commit)
+- Plan 02-02: SchemaSettings decomposed into 4 focused sub-components (4 commits)
+- Plan 02-03: Message pagination API + TanStack Virtual virtualization (5 commits)
+- Plan 02-04: Schema memoization and performance optimization (4 commits)
+- Plan 02-05: Type checking, linting, build verification, bug documentation (4 commits)
+- **Total:** 5 plans, 18 commits, 13 files created, 5 files modified
+- **Requirements:** All 7 FRONT requirements satisfied (FRONT-01 through FRONT-07)
+- **Quality:** TypeScript 0 errors, ESLint 0 critical errors, development build successful
+- **Bugs Fixed:** 5 bugs found and fixed during refactoring (all documented)
+- **Ready for:** Phase 03 (Chinese Documentation) — no dependency, can run in parallel
+
+**Next Phase:**
+
+- Phase 03: Chinese documentation (README.zh.md, DOC-01 requirement)
+- Expected duration: 1 plan, 1-2 hours
+- No dependency on Phase 2 code (documentation only)