loveuer/uzdb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Initial project setup - uzdb database client

Browse Source 
Initialize complete Wails (Go + React) database management tool

## Project Structure
- Frontend: React 18 + TypeScript + Vite
- Backend: Go 1.23 + Gin + GORM + SQLite + Zap
- Desktop: Wails v2

## Features Implemented

### UI/UX Design
- Complete design system with colors, typography, spacing
- Wireframes for all major screens
- User flows and interaction specifications
- Layout design with 3-panel architecture

### Frontend Components
- ConnectionPanel: Database connection sidebar with status indicators
- AppLayout: Resizable main layout framework
- MenuBar & ToolBar: Navigation and quick actions
- QueryEditor: SQL editor with syntax highlighting support
- DataGrid: Sortable, filterable, editable data table
- TableStructure: Table metadata viewer
- StatusBar: Connection info and query statistics
- StatusIndicator: Animated connection status component

### Backend Services
- Wails bindings: 15+ methods exposed to frontend
- Connection management: CRUD operations with connection pooling
- Query execution: SQL execution with result handling
- Table metadata: Schema introspection
- Encryption service: AES-256-GCM password encryption
- HTTP API: RESTful endpoints for debugging/integration

### Documentation
- Design system specification
- Feature requirements document
- Wireframes and user flows
- API testing guide
- Project README

## Technical Details
- Password encryption using AES-256-GCM
- Thread-safe connection manager with sync.RWMutex
- Unified error handling and logging
- Clean architecture with dependency injection
- SQLite for storing user data (connections, history)

🤖 Generated with Qoder
This commit is contained in:
loveuer
2026-03-29 06:49:23 -07:00
commit 5a83e86bc9
91 changed files with 16488 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
doc/README.md Normal file
View File

@@ -0,0 +1,186 @@
# uzdb Project Documentation
## 📚 Documentation Index
This directory contains all design and specification documents for the uzdb project.
### Core Documents
| Document | Description | Status |
|----------|-------------|--------|
| [Features](./features.md) | Complete feature specification with priorities | ✅ Complete |
| [Design System](./design-system.md) | Visual design language, colors, typography, components | ✅ Complete |
| [Wireframes](./wireframes.md) | UI mockups and layout specifications | ✅ Complete |
| [User Flows](./user-flows.md) | User interaction flows and edge cases | ✅ Complete |
---
## 🎯 Project Overview
**uzdb** is a lightweight database management tool inspired by DBeaver and Navicat, built with Wails (Go + React).
### Key Characteristics
- **Lightweight**: Fast startup, minimal resource usage
- **Simple**: Focus on essential features done well
- **Modern**: Clean UI following current design trends
- **Cross-platform**: Windows, macOS, Linux support via Wails
### Tech Stack
- **Frontend**: React + TypeScript + Vite
- **Backend**: Go 1.23+
- **Desktop Framework**: Wails v2
- **Styling**: CSS Variables + modern CSS
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────┐
│ Frontend (React) │
│ ┌──────────┬──────────┬──────────────┐ │
│ │ Sidebar │ Editor │ Data Grid │ │
│ │ │ │ │ │
│ └──────────┴──────────┴──────────────┘ │
│ Wails Runtime │
├─────────────────────────────────────────┤
│ Backend (Go) │
│ ┌──────────┬──────────┬──────────────┐ │
│ │ MySQL │PostgreSQL│ SQLite │ │
│ │ Driver │ Driver │ Driver │ │
│ └──────────┴──────────┴──────────────┘ │
└─────────────────────────────────────────┘
```
---
## 📁 File Structure
```
uzdb/
├── frontend/ # React application
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── App.tsx # Main app component
│ │ └── main.tsx # Entry point
│ └── package.json
├── doc/ # This directory - design docs
│ ├── features.md
│ ├── design-system.md
│ ├── wireframes.md
│ ├── user-flows.md
│ └── README.md # This file
├── internal/ # Go backend code
├── main.go # Go entry point
└── wails.json # Wails configuration
```
---
## 🎨 Quick Reference
### Color Palette
- **Primary**: `#3b82f6` (Blue)
- **Success**: `#10b981` (Green)
- **Warning**: `#f59e0b` (Amber)
- **Error**: `#ef4444` (Red)
### Keyboard Shortcuts
| Action | Shortcut |
|--------|----------|
| Run query | `Ctrl/Cmd + Enter` |
| New connection | `Ctrl/Cmd + N` |
| Save | `Ctrl/Cmd + S` |
| Find | `Ctrl/Cmd + F` |
| Close tab | `Ctrl/Cmd + W` |
### Supported Databases
- ✅ MySQL 5.7+
- ✅ PostgreSQL 12+
- ✅ SQLite 3.x
---
## 👥 Team Roles
### UI/UX Designer
- Responsible for visual design and user experience
- Maintains design system consistency
- Creates wireframes and prototypes
**See:** [.qoder/agents/uiux-designer.md](../.qoder/agents/uiux-designer.md)
### Frontend Developer
- Implements React components
- Integrates with Wails runtime
- Ensures responsive design
### Backend Developer
- Implements database drivers
- Handles Go business logic
- Manages connections and queries
---
## 📋 Development Workflow
### 1. Design Phase
1. Review feature requirements
2. Create/update wireframes
3. Define component specs
4. Get team approval
### 2. Implementation Phase
1. Create React components
2. Implement Go handlers
3. Write tests
4. Integration testing
### 3. Review Phase
1. Design review against specs
2. Code review
3. QA testing
4. Bug fixes
---
## 🔗 Related Resources
### Design Tools
- [Figma](https://figma.com/) - UI design and prototyping
- [Lucide Icons](https://lucide.dev/) - Icon library
- [Inter Font](https://rsms.me/inter/) - Primary typeface
### Development
- [Wails Documentation](https://wails.io/docs/)
- [React Docs](https://react.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
### Inspiration
- [DBeaver](https://dbeaver.io/) - Feature reference
- [Navicat](https://www.navicat.com/) - UX reference
- [TablePlus](https://tableplus.com/) - Modern design reference
---
## 📝 Contributing
When adding new features:
1. **Update documentation** in this directory
2. **Follow design system** for consistency
3. **Consider accessibility** requirements
4. **Test with real data** before merging
---
## 📞 Contact
For questions about design or features:
- Open an issue on GitHub
- Tag @uiux-designer for design questions
- Tag @maintainer for feature discussions
---
*Last updated: 2026-03-29*

217
doc/design-system.md Normal file
View File

@@ -0,0 +1,217 @@
# uzdb Design System
## Overview
uzdb is a lightweight database management tool inspired by DBeaver and Navicat, built with Wails (Go + React). This document defines the visual design language and component system.
---
## Color Palette
### Primary Colors
| Token | Value | Usage |
|-------|-------|-------|
| `--primary` | `#3b82f6` | Main actions, active states, links |
| `--primary-hover` | `#2563eb` | Hover states |
| `--primary-active` | `#1d4ed8` | Active/pressed states |
### Semantic Colors
| Token | Value | Usage |
|-------|-------|-------|
| `--success` | `#10b981` | Successful operations, connected status |
| `--warning` | `#f59e0b` | Warnings, pending states |
| `--error` | `#ef4444` | Errors, disconnected status, destructive actions |
| `--info` | `#06b6d4` | Informational messages |
### Neutral Colors
| Token | Value | Usage |
|-------|-------|-------|
| `--bg-primary` | `#ffffff` | Main background |
| `--bg-secondary` | `#f8fafc` | Secondary backgrounds, sidebars |
| `--bg-tertiary` | `#f1f5f9` | Cards, panels |
| `--border` | `#e2e8f0` | Borders, dividers |
| `--text-primary` | `#0f172a` | Primary text |
| `--text-secondary` | `#64748b` | Secondary text, labels |
| `--text-muted` | `#94a3b8` | Placeholder text, hints |
### Database Type Colors
| Token | Value | Usage |
|-------|-------|-------|
| `--db-mysql` | `#00758f` | MySQL connections |
| `--db-postgresql` | `#336791` | PostgreSQL connections |
| `--db-sqlite` |#003b57` | SQLite connections |
| `--db-mariadb` | `#003541` | MariaDB connections |
---
## Typography
### Font Family
```css
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
```
### Font Sizes
| Token | Size | Line Height | Usage |
|-------|------|-------------|-------|
| `--text-xs` | 12px | 16px | Captions, hints |
| `--text-sm` | 14px | 20px | Body text, labels |
| `--text-base` | 16px | 24px | Default text |
| `--text-lg` | 18px | 28px | Section titles |
| `--text-xl` | 20px | 28px | Panel titles |
| `--text-2xl` | 24px | 32px | Modal titles |
---
## Spacing
### Base Scale (4px grid)
| Token | Value |
|-------|-------|
| `--space-1` | 4px |
| `--space-2` | 8px |
| `--space-3` | 12px |
| `--space-4` | 16px |
| `--space-5` | 20px |
| `--space-6` | 24px |
| `--space-8` | 32px |
| `--space-10` | 40px |
| `--space-12` | 48px |
---
## Layout
### Application Shell
```
┌─────────────────────────────────────────────────────────────┐
│ Menu Bar (File, Edit, View, Tools, Help) │
├─────────────────────────────────────────────────────────────┤
│ Toolbar (Quick actions, search) │
├──────────┬──────────────────────────────────────────────────┤
│ │ │
│ Sidebar │ Main Content Area │
│ (200px) │ (Query editor, │
│ │ data grid, │
│ - Conn │ schema viewer) │
│ - DBs │ │
│ - Tables│ │
│ │ │
├──────────┴──────────────────────────────────────────────────┤
│ Status Bar (Connection info, query time, row count) │
└─────────────────────────────────────────────────────────────┘
```
### Breakpoints
- **Sidebar collapsible**: < 768px width
- **Responsive panels**: Stack vertically on small screens
---
## Components
### Button Styles
```css
.btn-primary {
background: var(--primary);
color: white;
padding: var(--space-2) var(--space-4);
border-radius: 6px;
font-size: var(--text-sm);
}
.btn-secondary {
background: transparent;
border: 1px solid var(--border);
color: var(--text-primary);
padding: var(--space-2) var(--space-4);
border-radius: 6px;
}
```
### Input Fields
```css
.input {
border: 1px solid var(--border);
border-radius: 6px;
padding: var(--space-2) var(--space-3);
font-size: var(--text-sm);
}
.input:focus {
outline: 2px solid var(--primary);
border-color: transparent;
}
```
### Data Grid
- Row height: 36px
- Header height: 40px
- Cell padding: 8px 12px
- Border: 1px solid var(--border)
- Alternating row colors for readability
### Tabs
- Active tab: Primary color underline (2px)
- Inactive tab: Transparent background
- Tab height: 36px
---
## Icons
Use [Lucide Icons](https://lucide.dev/) or [Heroicons](https://heroicons.com/)
Common icons:
- `database` - Connection/database
- `table` - Table view
- `search` - Search/query
- `play` - Execute query
- `download` - Export data
- `upload` - Import data
- `settings` - Settings/preferences
- `plus` - Add new
- `trash-2` - Delete
---
## Interactions
### Hover States
- Buttons: Darken background by 10%
- Links: Underline + primary color
- Table rows: Background `--bg-tertiary`
### Focus States
- All interactive elements: 2px primary outline
- Visible focus ring for keyboard navigation
### Loading States
- Spinner for async operations
- Skeleton screens for data loading
- Disabled state during execution
### Transitions
- Duration: 150ms
- Easing: `ease-in-out`
- Properties: color, background-color, transform
---
## Accessibility
### Requirements
- Minimum contrast ratio: 4.5:1 (AA standard)
- Focus indicators on all interactive elements
- Keyboard navigation support
- Screen reader friendly labels
- Resizable text up to 200%
### Keyboard Shortcuts
| Action | Shortcut |
|--------|----------|
| Execute query | Ctrl/Cmd + Enter |
| New connection | Ctrl/Cmd + N |
| Save | Ctrl/Cmd + S |
| Find | Ctrl/Cmd + F |
| Close tab | Ctrl/Cmd + W |

377
doc/features.md Normal file
View File

@@ -0,0 +1,377 @@
# uzdb Feature Specification
## Overview
uzdb is a lightweight database management tool built with Wails (Go + React). It provides essential database operations without the complexity of enterprise tools like DBeaver or Navicat.
---
## Target Users
1. **Developers** - Need quick database access for debugging and development
2. **Small Teams** - Want a simple, fast tool for daily database tasks
3. **Students/Learners** - Need an easy-to-use SQL client for learning
---
## Supported Databases (MVP)
### Phase 1 (Initial Release)
- ✅ MySQL 5.7+ / 8.0+
- ✅ PostgreSQL 12+
- ✅ SQLite 3.x
### Phase 2 (Future)
- ⏳ MariaDB 10.3+
- ⏳ Microsoft SQL Server
- ⏳ MongoDB (basic support)
---
## Core Features
### 1. Connection Management
#### 1.1 Create Connection
**Priority:** P0
**Description:** Users can create new database connections
**Requirements:**
- Support MySQL, PostgreSQL, SQLite
- Store connection details securely
- Test connection before saving
- Support SSH tunneling (Phase 2)
**UI Components:**
- Connection dialog with form fields
- Database type selector
- Test connection button
- Advanced options accordion
#### 1.2 Connection List
**Priority:** P0
**Description:** View and manage saved connections
**Requirements:**
- Display all saved connections
- Show connection status (connected/disconnected)
- Quick connect double-click
- Right-click context menu
**UI Components:**
- Sidebar connection tree
- Status indicators
- Context menu
#### 1.3 Edit/Delete Connection
**Priority:** P0
**Description:** Modify or remove existing connections
**Requirements:**
- Edit connection properties
- Duplicate connection
- Delete with confirmation
- Cannot delete active connection
---
### 2. Schema Explorer
#### 2.1 Database Navigation
**Priority:** P0
**Description:** Browse database structure in sidebar
**Requirements:**
- Expand/collapse databases
- Show schemas (PostgreSQL)
- List tables, views, procedures
- Icon differentiation by object type
**UI Components:**
- Tree view component
- Lazy loading for large schemas
- Search/filter capability (Phase 2)
#### 2.2 Table Metadata
**Priority:** P0
**Description:** View table structure and information
**Requirements:**
- Column list with types and constraints
- Indexes display
- Foreign keys relationships
- Triggers list
**UI Components:**
- Right sidebar panel
- Tabbed interface for different metadata types
---
### 3. Query Editor
#### 3.1 SQL Editor
**Priority:** P0
**Description:** Write and execute SQL queries
**Requirements:**
- Syntax highlighting (SQL keywords, strings, comments)
- Line numbers
- Basic autocomplete (table/column names)
- Multiple tabs support
- Query history (Phase 2)
**UI Components:**
- Monaco Editor or CodeMirror
- Tab bar for multiple queries
- Toolbar with run/save buttons
#### 3.2 Query Execution
**Priority:** P0
**Description:** Execute SQL and view results
**Requirements:**
- Execute selected text or full query
- Show execution time
- Display row count
- Cancel long-running queries
- Error message display with line number
**Keyboard Shortcuts:**
- `Ctrl+Enter`: Execute query
- `Ctrl+R`: Refresh results
#### 3.3 Query Snippets
**Priority:** P2
**Description:** Save and reuse common queries
**Requirements:**
- Save query as snippet
- Organize snippets by category
- Insert snippet into editor
- Share snippets (Phase 3)
---
### 4. Data Grid
#### 4.1 Results Display
**Priority:** P0
**Description:** Show query results in tabular format
**Requirements:**
- Virtual scrolling for large datasets
- Column resizing
- Sort by clicking headers
- Fixed header row
- Alternating row colors
**Performance:**
- Render 1000+ rows smoothly
- Load data in chunks (100 rows at a time)
#### 4.2 Data Editing
**Priority:** P1
**Description:** Edit cell values inline
**Requirements:**
- Double-click to edit
- Validate data types
- Show NULL indicator
- Commit on blur or Enter
- Escape to cancel
**Cell Editors:**
- Text input for strings
- Number input for integers/decimals
- Date picker for dates
- Checkbox for booleans
- Dropdown for enums
#### 4.3 Pagination & Navigation
**Priority:** P0
**Description:** Navigate through result sets
**Requirements:**
- Page size selector (25, 50, 100, 500)
- Jump to page input
- First/Previous/Next/Last buttons
- Total row count display
- Limit/offset in query
---
### 5. Data Export/Import
#### 5.1 Export Data
**Priority:** P0
**Description:** Export table/query results to file
**Requirements:**
- Formats: CSV, JSON, SQL INSERT
- Select destination path
- Configure export options
- Show progress for large exports
**Export Options (CSV):**
- Delimiter selection (comma, semicolon, tab)
- Include/exclude headers
- Quote character
- Encoding (UTF-8 default)
**Export Options (JSON):**
- Pretty print vs compact
- Array of objects vs arrays
#### 5.2 Import Data
**Priority:** P1
**Description:** Import data from files
**Requirements:**
- Import CSV/JSON to table
- Map columns
- Preview before import
- Handle errors gracefully
- Transaction support (rollback on error)
---
### 6. Additional Features
#### 6.1 Find in Results
**Priority:** P1
**Description:** Search within query results
**Requirements:**
- Case-sensitive toggle
- Match whole word
- Highlight matches
- Navigate between matches
#### 6.2 Query History
**Priority:** P2
**Description:** Track executed queries
**Requirements:**
- Store last 100 queries per connection
- Search history
- Re-execute from history
- Pin important queries
#### 6.3 Bookmarks
**Priority:** P2
**Description:** Save frequently used queries
**Requirements:**
- Bookmark query with name
- Organize in folders
- Quick access from sidebar
---
## Non-Functional Requirements
### Performance
- App startup: < 2 seconds
- Connection open: < 1 second (local)
- Query results render: < 100ms for 100 rows
- Memory usage: < 200MB idle
### Security
- Passwords stored encrypted (keyring/keystore)
- No plain-text credentials in config files
- SSL/TLS support for connections
- Sanitize SQL inputs to prevent injection in logs
### Accessibility
- WCAG 2.1 AA compliance
- Keyboard navigation throughout
- Screen reader support
- High contrast mode (Phase 2)
### Internationalization
- English (initial)
- Chinese (Simplified) (Phase 2)
- Spanish (Phase 3)
---
## Technical Architecture
### Frontend (React + TypeScript)
```
src/
├── components/
│ ├── Sidebar/
│ │ ├── ConnectionTree.tsx
│ │ └── SchemaExplorer.tsx
│ ├── Editor/
│ │ ├── QueryEditor.tsx
│ │ └── SQLEditor.tsx
│ ├── Grid/
│ │ ├── DataGrid.tsx
│ │ └── CellEditor.tsx
│ ├── Dialogs/
│ │ ├── ConnectionDialog.tsx
│ │ └── ExportDialog.tsx
│ └── common/
│ ├── Button.tsx
│ ├── Input.tsx
│ └── Modal.tsx
├── hooks/
│ ├── useQuery.ts
│ └── useConnection.ts
├── stores/
│ ├── connectionStore.ts
│ └── queryStore.ts
└── utils/
├── formatters.ts
└── validators.ts
```
### Backend (Go)
```
internal/
├── database/
│ ├── mysql.go
│ ├── postgres.go
│ ├── sqlite.go
│ └── connection.go
├── models/
│ ├── connection.go
│ ├── query.go
│ └── table.go
└── handlers/
├── connection_handler.go
├── query_handler.go
└── export_handler.go
```
---
## Out of Scope (for MVP)
❌ Visual query builder
❌ ER diagrams
❌ Database comparison/sync
❌ User management
❌ Backup/restore
❌ Query profiling/optimization
❌ Multi-tab result sets
❌ Stored procedure debugger
❌ Real-time collaboration
---
## Success Metrics
1. **Usability**: New user can connect and run query in < 2 minutes
2. **Performance**: Query results load in < 500ms for typical queries
3. **Stability**: < 1 crash per 100 hours of usage
4. **Adoption**: 100+ GitHub stars in first month
---
## Future Roadmap
### Phase 2 (v0.2)
- MariaDB support
- SSH tunneling
- Query history
- Data import
- Dark theme
### Phase 3 (v0.3)
- SQL Server support
- Visual query builder (basic)
- Snippet sharing
- Plugin system
### Phase 4 (v1.0)
- MongoDB support
- ER diagram viewer
- Team features (shared connections)
- Auto-update

691
doc/layout-design.md Normal file
View File

@@ -0,0 +1,691 @@
# uzdb 布局设计文档
## Overview
本文档详细描述 uzdb 数据库管理工具的整体布局设计，包括左侧连接面板、右侧功能区域的界面设计和交互规范。
---
## 整体布局架构
### 经典两栏布局
```
┌─────────────────────────────────────────────────────────────────────┐
│ ☰ File Edit View Query Tools Help │ ← 菜单栏
├─────────────────────────────────────────────────────────────────────┤
│ [▶ Run] [💾 Save] [📤 Export] [🔍 Find] [🗄️ MySQL @ localhost ▼] │ ← 工具栏
├──────────────────┬──────────────────────────────────────────────────┤
│ │ ┌─ 📑 query_1.sql ─────────────────────────┐ │
│ 🗄️ Connections │ │ │ │
│ ├─ ⚫ MySQL │ │ SELECT * FROM users │ │
│ │ ├─ 🔵 public │ │ WHERE active = true; │ │
│ │ │ ├─ 📋 users │ │ │
│ │ │ ├─ 📋 products │ │ │
│ │ │ └─ 📋 orders │ │ │
│ │ └─ 📊 information_schema │ │ │
│ ├─ ⚫ PostgreSQL│ └───────────────────────────────────────────┘ │
│ │ └─ 🔵 public │ ┌─ Results ────────────────────────────────┐ │
│ └─ ⚫ SQLite │ │ id │ name │ email │ active │ │
│ │ ├────┼───────┼─────────────────┼──────────┤ │
│ [+ New Conn] │ │ 1 │ Alice │ alice@mail.com │ ✓ │ │
│ │ │ 2 │ Bob │ bob@mail.com │ ✓ │ │
│ │ │ 3 │ Carol │ carol@mail.com │ ✗ │ │
│ │ └───────────────────────────────────────────┘ │
│ │ [◀] [1] [2] [3] [▶] Per page: [25▼] 127 rows │
├──────────────────┴──────────────────────────────────────────────────┤
│ ✓ Connected to MySQL@localhost:3306 │ UTF-8 │ LF │ ins │ ← 状态栏
└─────────────────────────────────────────────────────────────────────┘
```
### 布局尺寸规范
| 区域 | 默认宽度/高度 | 可调节范围 | 说明 |
|------|--------------|-----------|------|
| 左侧面板 | 240px | 180px - 400px | 可拖拽调节，支持折叠 |
| 菜单栏 | 32px (高) | 固定 | 标准菜单高度 |
| 工具栏 | 40px (高) | 固定 | 包含快捷操作 |
| 状态栏 | 28px (高) | 固定 | 显示连接和信息状态 |
| Tab 标签栏 | 36px (高) | 固定 | 每个标签页高度 |
---
## 左侧连接面板设计
### 1. 面板结构
```
┌─────────────────────────────┐
│ 🗄️ Connections [⚙️] │ ← 面板标题 + 设置按钮
├─────────────────────────────┤
│ 🔵 Active Connection │ ← 当前活跃连接（高亮）
│ ├─ 🗄️ database_name │
│ │ ├─ 📊 schema_name │
│ │ │ ├─ 📋 table1 │
│ │ │ ├─ 📋 table2 │
│ │ │ └─ 📋 table3 │
│ │ └─ 📊 another_schema │
│ ├─ 📋 views (5) │
│ ├─ ⚡ functions (12) │
│ └─ 📝 procedures (3) │
├─────────────────────────────┤
│ ⚫ saved_connection_1 │ ← 已保存但未连接
│ ⚫ saved_connection_2 │
│ ⚪ saved_connection_3 │ ← 连接错误
├─────────────────────────────┤
│ [+ New Connection] │ ← 新建连接按钮
└─────────────────────────────┘
```
### 2. 连接状态指示器
#### 状态类型与视觉表现
| 状态 | 图标 | 颜色 | 说明 | 交互 |
|------|------|------|------|------|
| **已连接** | `🔵` / `●` | `#10b981` (绿色) | 连接成功且可用 | 可展开查看结构 |
| **使用中** | `🟢` / `◉` | `#3b82f6` (蓝色) | 当前正在使用的连接 | 高亮显示，带光晕效果 |
| **未连接** | `⚫` / `○` | `#94a3b8` (灰色) | 已保存但未建立连接 | 双击或点击展开连接 |
| **连接中** | `⟳` / `⌛` | `#f59e0b` (橙色) | 正在建立连接 | 旋转动画，不可交互 |
| **错误** | `⚪` / `✕` | `#ef4444` (红色) | 连接失败 | 悬停显示错误信息 |
#### CSS 实现示例
```css
/* 状态指示器基础样式 */
.connection-status {
width: 8px;
height: 8px;
border-radius: 50%;
display: inline-block;
margin-right: 8px;
transition: all 0.15s ease-in-out;
}
/* 各状态样式 */
.status-connected {
background-color: var(--success);
box-shadow: 0 0 4px var(--success);
}
.status-active {
background-color: var(--primary);
box-shadow: 0 0 8px var(--primary);
animation: pulse 2s infinite;
}
.status-disconnected {
background-color: var(--text-muted);
border: 1px solid var(--border);
}
.status-connecting {
border: 2px solid var(--warning);
border-top-color: transparent;
animation: spin 1s linear infinite;
}
.status-error {
background-color: var(--error);
cursor: help;
}
/* 动画定义 */
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.6; }
}
@keyframes spin {
to { transform: rotate(360deg); }
}
```
### 3. 数据库类型图标
| 数据库类型 | 图标 | 颜色 | 使用场景 |
|-----------|------|------|----------|
| MySQL | `🗄️` / `🐬` | `#00758f` | MySQL 连接 |
| PostgreSQL | `🐘` / `🗄️` | `#336791` | PostgreSQL 连接 |
| SQLite | `◪` / `🗄️` | `#003b57` | SQLite 连接 |
| MariaDB | `🗄️` | `#003541` | MariaDB 连接 |
### 4. 交互方式
#### 单击交互
- **单击连接名**: 选中连接，如果未连接则尝试连接
- **单击展开箭头**: 展开/折叠数据库结构树
- **单击状态图标**: 显示连接详情 tooltip
#### 双击交互
- **双击连接**: 快速连接/断开连接
- **双击数据库/表**: 在新标签页打开数据浏览或结构查看
#### 右键菜单
```
┌─────────────────────────────┐
│ 🗄️ MySQL @ localhost │
├─────────────────────────────┤
│ ▶ Connect │
│ ▶ Disconnect │
│ ├───────────────────────── │
│ ▶ Edit Connection... │
│ ▶ Duplicate Connection │
│ ▶ Refresh Schema │
│ ├───────────────────────── │
│ ▶ Test Connection │
│ ▶ Copy Connection String │
│ ├───────────────────────── │
│ ▶ Delete Connection │
└─────────────────────────────┘
```
#### 键盘导航
| 快捷键 | 功能 |
|--------|------|
| `↑` / `↓` | 上下移动选择 |
| `→` | 展开节点 / 连接数据库 |
| `←` | 折叠节点 |
| `Enter` | 确认操作 / 连接 |
| `Space` | 切换展开/折叠 |
| `F2` | 重命名连接 |
| `Delete` | 删除连接（需确认） |
| `Ctrl+R` | 刷新 Schema |
| `Context Menu` | 显示右键菜单 |
### 5. 新建连接按钮区域
```
┌─────────────────────────────┐
│ │
│ ┌───────────────────────┐ │
│ │ + New Connection │ │ ← 主按钮
│ └───────────────────────┘ │
│ │
│ Recent: │
│ • MySQL @ localhost │
│ • PG @ prod-db │
│ │
└─────────────────────────────┘
```
---
## 右侧功能区域设计
### 1. SQL 编辑器模块
```
┌─ 📑 unsaved_query.sql ───────────────────────────────────────────┐
│ [×] │
├──────────────────────────────────────────────────────────────────┤
│ 1 │ -- Get active users with their orders │
│ 2 │ SELECT │
│ 3 │ u.id, │
│ 4 │ u.name, │
│ 5 │ u.email, │
│ 6 │ COUNT(o.id) as order_count │
│ 7 │ FROM users u │
│ 8 │ LEFT JOIN orders o ON u.id = o.user_id │
│ 9 │ WHERE u.active = true │
│ 10 │ AND u.created_at >= '2024-01-01' │
│ 11 │ GROUP BY u.id, u.name, u.email │
│ 12 │ HAVING COUNT(o.id) > 0 │
│ 13 │ ORDER BY order_count DESC │
│ 14 │ LIMIT 100; │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│ ▶ Run (Ctrl+Enter) │ ▶ Explain │ ✨ Format │ 📜 History │
│ 💾 Save │ 📤 Export Results │ 🔍 Find in Query │
└──────────────────────────────────────────────────────────────────┘
```
#### SQL 编辑器特性
| 功能 | 描述 | 实现建议 |
|------|------|----------|
| **语法高亮** | SQL 关键字、字符串、注释、函数等 | Monaco Editor / CodeMirror |
| **智能提示** | 表名、列名、函数自动补全 | 基于当前连接 schema |
| **代码格式化** | 美化 SQL 格式 | sql-formatter 库 |
| **多标签支持** | 同时编辑多个查询 | Tab 组件管理 |
| **查询历史** | 记录执行过的 SQL | 本地存储 + 搜索 |
| **代码片段** | 常用 SQL 模板快速插入 | 预定义 snippets |
#### 执行结果展示区
```
┌─ Results ────────────────────────────────────────────────────────┐
│ Query executed successfully in 0.045s (127 rows affected) │
├──────────────────────────────────────────────────────────────────┤
│ [Filters ▼] [Sort ▼] [Group By ▼] [🔄 Refresh] [📤 Export] │
├──────────────────────────────────────────────────────────────────┤
│ id │ name │ email │ created_at │ active │ ... │
├─────┼─────────┼─────────────────┼─────────────┼────────┼───────┤
│ 1 │ Alice │ alice@mail.com │ 2024-01-15 │ ✓ │ ... │
│ 2 │ Bob │ bob@mail.com │ 2024-01-16 │ ✓ │ ... │
│ 3 │ Charlie │ carol@mail.com │ 2024-01-17 │ ✗ │ ... │
│ 4 │ Diana │ diana@mail.com │ 2024-01-18 │ ✓ │ ... │
│ 5 │ Eve │ eve@mail.com │ 2024-01-19 │ ✓ │ ... │
└──────────────────────────────────────────────────────────────────┘
│ Showing 1-25 of 127 rows [◀◀] [◀] [1] [2] [3] [...] [▶] [▶▶] │
│ Per page: [25 ▼] [📋 Copy Row] │
└──────────────────────────────────────────────────────────────────┘
```
### 2. 数据浏览模块
```
┌─ 📋 public.users ────────────────────────────────────────────────┐
│ [×] │
├──────────────────────────────────────────────────────────────────┤
│ Table: users │ Database: public │ Connection: MySQL@local │
├──────────────────────────────────────────────────────────────────┤
│ [Data] [Structure] [Indexes] [Foreign Keys] [Triggers] │
├──────────────────────────────────────────────────────────────────┤
│ [✏️ Add Row] [🗑️ Delete] [🔍 Filter] [🔄 Refresh] [📤 Export]│
├──────────────────────────────────────────────────────────────────┤
│ ☐ │ id │ name │ email │ created_at │ active │ ✎ │
├────┼─────┼─────────┼─────────────────┼─────────────┼────────┼───┤
│ ☐ │ 1 │ Alice │ alice@mail.com │ 2024-01-15 │ ✓ │ ✎ │
│ ☐ │ 2 │ Bob │ bob@mail.com │ 2024-01-16 │ ✓ │ ✎ │
│ ☐ │ 3 │ Charlie │ carol@mail.com │ 2024-01-17 │ ✗ │ ✎ │
│ ☐ │ 4 │ Diana │ diana@mail.com │ 2024-01-18 │ ✓ │ ✎ │
└──────────────────────────────────────────────────────────────────┘
│ Selected: 0 rows Total: 1,247 rows │
│ [◀◀] [◀] [1] [2] [3] [...] [▶] [▶▶] Per page: [50 ▼] │
└──────────────────────────────────────────────────────────────────┘
```
#### 数据编辑功能
| 操作 | 交互方式 | 说明 |
|------|----------|------|
| **单元格编辑** | 双击单元格 | 根据数据类型弹出相应编辑器 |
| **行选择** | 点击复选框 | 支持多选批量操作 |
| **添加行** | 点击"Add Row" | 在表格末尾添加新行 |
| **删除行** | 选择后点删除 | 需要确认对话框 |
| **撤销/重做** | Ctrl+Z / Ctrl+Y | 支持多级撤销 |
#### 单元格编辑器类型
| 数据类型 | 编辑器 | 说明 |
|----------|--------|------|
| VARCHAR/TEXT | 文本输入框 | 支持多行编辑 |
| INT/BIGINT | 数字输入框 | 整数验证 |
| DECIMAL/FLOAT | 数字输入框 | 小数精度控制 |
| DATE | 日期选择器 | 日历控件 |
| DATETIME/TIMESTAMP | 日期时间选择器 | 包含时间 |
| BOOLEAN | 复选框 | 勾选/取消 |
| ENUM | 下拉选择框 | 预定义选项 |
| JSON | JSON 编辑器 | 语法高亮 |
| BLOB | 文件上传/预览 | 二进制数据处理 |
### 3. 表结构查看模块
```
┌─ 📋 Table Structure: users ──────────────────────────────────────┐
│ [×] │
├──────────────────────────────────────────────────────────────────┤
│ [Data] [Structure] [Indexes] [Foreign Keys] [Triggers] │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ Columns (5) ─────────────────────────────────────────────┐ │
│ │ Name │ Type │ Null │ Key │ Default │ Extra │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ id │ INT │ ❌ │ PK │ │ auto_inc│ │
│ │ name │ VARCHAR(100) │ ❌ │ │ │ │ │
│ │ email │ VARCHAR(255) │ ❌ │ UK │ │ │ │
│ │ created_at │ TIMESTAMP │ ✓ │ │ NOW() │ │ │
│ │ active │ BOOLEAN │ ❌ │ │ TRUE │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Indexes (2) ──────────────────────────────────────────────┐ │
│ │ Name │ Type │ Columns │ Unique │ Method │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ PRIMARY │ BTREE │ id │ ✓ │ BTREE │ │
│ │ idx_email │ BTREE │ email │ ✓ │ BTREE │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Foreign Keys (1) ─────────────────────────────────────────┐ │
│ │ Name │ Column │ References │ On Update │ On Delete││
│ ├────────────────────────────────────────────────────────────┤ │
│ │ fk_user_role │ role_id │ roles(id) │ CASCADE │ SET NULL ││
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Table Info ───────────────────────────────────────────────┐ │
│ │ Engine: InnoDB │ Collation: utf8mb4_unicode_ci │ │
│ │ Rows: 1,247 │ Size: 256 KB │ │
│ │ Auto Increment: 1248 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
```
### 4. 其他功能模块
#### 4.1 查询历史
```
┌─ 📜 Query History ───────────────────────────────────────────────┐
│ [×] │
├──────────────────────────────────────────────────────────────────┤
│ 🔍 Search history... [🗑️ Clear All] │
├──────────────────────────────────────────────────────────────────┤
│ Today │
│ ├─ SELECT * FROM users WHERE active = true... (10:45 AM) │
│ ├─ UPDATE products SET price = price * 1.1... (10:32 AM) │
│ └─ DELETE FROM temp_data WHERE created_at < ... (09:15 AM) │
│ │
│ Yesterday │
│ ├─ CREATE INDEX idx_email ON users(email)... (03:22 PM) │
│ └─ SELECT COUNT(*) FROM orders... (02:10 PM) │
│ │
│ Last 7 Days │
│ └─ ... │
└──────────────────────────────────────────────────────────────────┘
```
#### 4.2 导出向导
```
┌─ Export Data ────────────────────────────────────────────────────┐
│ [×] │
├──────────────────────────────────────────────────────────────────┤
│ │
│ Source: [✓ users (entire table) ▼] │
│ │
│ Format: [CSV Comma-separated (,) ▼] │
│ │
│ ┌─ Options ─────────────────────────────────────────────────┐ │
│ │ ☑ Include column headers │ │
│ │ ☐ Quote all fields │ │
│ │ Delimiter: [, ▼] Quote: [" ▼] Escape: [\ ▼] │ │
│ │ Encoding: [UTF-8 ] │ │
│ │ Line endings: [Unix (LF) ▼] │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Output: (○) Copy to clipboard │
│ (●) Save to file │
│ [ /home/user/exports/users.csv ] [Browse] │
│ │
│ Preview (first 5 rows): │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ id,name,email,created_at,active │ │
│ │ 1,Alice,alice@mail.com,2024-01-15,true │ │
│ │ 2,Bob,bob@mail.com,2024-01-16,true │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ [Cancel] [Export] │
│ │
└──────────────────────────────────────────────────────────────────┘
```
---
## 状态栏设计规范
### 状态栏布局
```
┌─────────────────────────────────────────────────────────────────┐
│ [状态] [连接信息] │ [编码] │ [换行] │ [模式] │
└─────────────────────────────────────────────────────────────────┘
```
### 状态指示
| 区域 | 内容 | 示例 |
|------|------|------|
| **连接状态** | 当前连接状态和详情 | `✓ Connected to MySQL@localhost:3306` |
| **查询信息** | 执行时间和影响行数 | `✓ 127 rows in 0.045s` |
| **错误信息** | 错误描述 | `✕ Error: Connection timeout` |
| **编码格式** | 文件/连接编码 | `UTF-8` |
| **换行符** | 行结束符类型 | `LF` / `CRLF` |
| **编辑模式** | 编辑器模式 | `ins` (插入) / `ovr` (覆盖) |
### 状态栏颜色
| 状态 | 背景色 | 文字色 | 图标 |
|------|--------|--------|------|
| 正常 | `#f8fafc` | `#64748b` | - |
| 成功 | `#d1fae5` | `#065f46` | `✓` |
| 警告 | `#fef3c7` | `#92400e` | `⚠` |
| 错误 | `#fee2e2` | `#991b1b` | `✕` |
| 信息 | `#dbeafe` | `#1e40af` | `ℹ` |
---
## 响应式设计
### 断点定义
| 断点 | 宽度范围 | 布局调整 |
|------|----------|----------|
| **Small** | < 768px | 侧边栏隐藏为抽屉，单栏布局 |
| **Medium** | 768px - 1024px | 侧边栏可折叠，双栏布局 |
| **Large** | > 1024px | 完整双栏布局，所有功能可见 |
### 小屏幕适配
```
┌─────────────────────────────────────┐
│ ☰ uzdb [⚙️] │ ← 汉堡菜单
├─────────────────────────────────────┤
│ [▶] [💾] [📤] [🔍] [▼] │ ← 简化 toolbar
├─────────────────────────────────────┤
│ │
│ [全屏编辑器/数据网格] │
│ │
│ │
├─────────────────────────────────────┤
│ ✓ Connected │ UTF-8 │ ins │
└─────────────────────────────────────┘
```
---
## 主题与配色
### 浅色主题（默认）
参考 `/root/codes/project/self/uzdb/doc/design-system.md` 中的颜色定义：
| 元素 | 颜色值 | 用途 |
|------|--------|------|
| 主背景 | `#ffffff` | 主内容区域 |
| 次级背景 | `#f8fafc` | 侧边栏、面板 |
| 第三背景 | `#f1f5f9` | 卡片、分组 |
| 边框 | `#e2e8f0` | 分隔线、边框 |
| 主文字 | `#0f172a` | 标题、正文 |
| 次级文字 | `#64748b` | 标签、说明 |
| 强调色 | `#3b82f6` | 链接、按钮、激活状态 |
### 深色主题（未来扩展）
预留深色主题支持，使用 CSS 变量实现主题切换。
---
## 交互细节规范
### 1. 悬停效果
| 元素 | 悬停效果 | 过渡时间 |
|------|----------|----------|
| 按钮 | 背景变深 10% | 150ms |
| 链接 | 下划线 + 强调色 | 150ms |
| 表格行 | 背景色 `#f1f5f9` | 100ms |
| 树节点 | 背景色 `#f1f5f9` | 100ms |
### 2. 焦点状态
所有可交互元素必须具有可见的焦点环：
```css
:focus-visible {
outline: 2px solid var(--primary);
outline-offset: 2px;
}
```
### 3. 加载状态
| 场景 | 加载指示 | 说明 |
|------|----------|------|
| 连接建立 | 旋转 Spinner | 状态变为"连接中" |
| 查询执行 | 进度条 + Spinner | 显示执行进度 |
| 数据加载 | Skeleton 骨架屏 | 渐进式加载 |
| 大数据导出 | 进度百分比 | 可取消操作 |
### 4. 空状态
```
┌─────────────────────────────────────┐
│ │
│ 🗄️ │
│ │
│ No Database Connections │
│ │
│ Get started by connecting to your │
│ first database │
│ │
│ [+ New Connection] │
│ │
│ Supported: MySQL, PostgreSQL, │
│ SQLite, MariaDB │
│ │
└─────────────────────────────────────┘
```
### 5. 错误提示
- **Inline 错误**: 表单字段下方红色文字
- **Toast 通知**: 右上角弹出提示，3 秒自动消失
- **模态对话框**: 严重错误需要用户确认
---
## 无障碍设计 (Accessibility)
### WCAG 2.1 AA 合规
- ✅ 对比度至少 4.5:1
- ✅ 键盘导航支持
- ✅ 屏幕阅读器标签
- ✅ 焦点指示器可见
- ✅ 可调整字体大小（最高 200%）
### 键盘快捷键总览
| 快捷键 | 功能 | 作用域 |
|--------|------|--------|
| `Ctrl+Enter` | 执行查询 | SQL 编辑器 |
| `Ctrl+S` | 保存 | 全局 |
| `Ctrl+N` | 新建连接 | 全局 |
| `Ctrl+F` | 查找 | 编辑器/数据网格 |
| `Ctrl+Z` | 撤销 | 编辑器 |
| `Ctrl+Y` | 重做 | 编辑器 |
| `Ctrl+W` | 关闭标签 | 标签页 |
| `F2` | 重命名 | 树节点 |
| `F5` | 刷新 | 全局 |
| `Delete` | 删除 | 选中项 |
| `Esc` | 取消/关闭 | 模态框 |
---
## 性能优化建议
### 1. 虚拟滚动
对于大数据集（>100 行），使用虚拟滚动技术：
- 只渲染可见区域的数据
- 滚动时动态加载数据块
- 保持滚动条总长度正确
### 2. 懒加载
- 树形结构按需加载子节点
- 图片/图标延迟加载
- 非关键组件异步加载
### 3. 缓存策略
- 查询结果短期缓存（5 分钟）
- Schema 信息中期缓存（30 分钟）
- 连接信息长期缓存（直到断开）
---
## 开发实现建议
### 推荐组件库
| 组件类型 | 推荐库 | 说明 |
|----------|--------|------|
| UI 组件 | Radix UI / Headless UI | 无样式组件，灵活定制 |
| 数据网格 | TanStack Table / AG Grid | 高性能表格 |
| 代码编辑 | Monaco Editor / CodeMirror | SQL 语法支持 |
| 图表 | Recharts / Chart.js | 数据统计展示 |
| 图标 | Lucide Icons / Heroicons | 一致风格 |
### Wails 集成要点
1. **前后端通信**: 使用 Wails Events 实现实时通知
2. **状态管理**: Zustand / Jotai 轻量级方案
3. **路由**: 单页应用，基于状态的视图切换
4. **样式**: TailwindCSS + CSS Variables 主题系统
---
## 附录：组件层级结构
```
App
├── MenuBar
├── ToolBar
├── MainContent
│ ├── Sidebar
│ │ ├── ConnectionPanel
│ │ │ ├── ConnectionHeader
│ │ │ ├── ConnectionList
│ │ │ │ └── ConnectionItem
│ │ │ │ ├── StatusIndicator
│ │ │ │ ├── ConnectionName
│ │ │ │ └── ContextMenu
│ │ │ └── NewConnectionButton
│ │ └── SchemaExplorer
│ │ └── SchemaTree
│ └── Workspace
│ ├── TabBar
│ └── TabContent
│ ├── SQLEditor
│ │ ├── EditorToolbar
│ │ ├── CodeEditor
│ │ └── ResultsPanel
│ ├── DataTable
│ │ ├── TableToolbar
│ │ ├── DataGrid
│ │ └── Pagination
│ └── TableStructure
│ ├── StructureTabs
│ └── StructureContent
└── StatusBar
```
---
## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2026-03-29 | Design Team | 初始版本，完整布局设计 |
---
## 参考文档
- [Design System](./design-system.md) - 视觉设计规范
- [Wireframes](./wireframes.md) - 原始线框图
- [Features](./features.md) - 功能规格说明
- [User Flows](./user-flows.md) - 用户流程

396
doc/user-flows.md Normal file
View File

@@ -0,0 +1,396 @@
# uzdb User Flows
## 1. First-Time User Experience
```
┌─────────────────┐
│ Launch App │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Empty State: │
│ "No Connections"│
└────────┬────────┘
│
│ Click "New Connection"
▼
┌─────────────────┐
│ Connection │
│ Wizard │
│ 1. Select Type │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 2. Configure │
│ Connection │
│ (Host, Port, │
│ Credentials) │
└────────┬────────┘
│
│ Click "Test Connection"
▼
┌─────────────────┐
│ Test Result │
│ ✓ Success │
│ ✕ Error + Help │
└────────┬────────┘
│
│ Save & Connect
▼
┌─────────────────┐
│ Main Interface │
│ with Schema │
│ Explorer │
└─────────────────┘
```
---
## 2. Query Execution Flow
```
┌─────────────────┐
│ Open Query Tab │
│ (Ctrl+T) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Write/Edit SQL │
│ - Syntax │
│ highlighting │
│ - Autocomplete │
│ - Snippets │
└────────┬────────┘
│
│ Ctrl+Enter or Click Run
▼
┌─────────────────┐
│ Execute Query │
│ Show loading │
│ indicator │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Display Results │
│ - Data grid │
│ - Row count │
│ - Execution time│
│ - Status │
└────────┬────────┘
│
├──────────────┬──────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Export Data │ │ Edit Cell │ │ Save Query │
│ (CSV, JSON) │ │ (Inline) │ │ (.sql file) │
└─────────────┘ └─────────────┘ └─────────────┘
```
---
## 3. Table Browsing Flow
```
┌─────────────────┐
│ Expand Database │
│ in Sidebar │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Expand Schema │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Click Table │
└────────┬────────┘
│
├─────────────────┬────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Preview Top │ │ View │ │ Open Table │
│ 100 Rows │ │ Structure │ │ Details │
│ (Double-click)│ │ (Right panel)│ │ Panel │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────────┐
│ Columns, Indexes│
│ Foreign Keys, │
│ Triggers │
└─────────────────┘
```
---
## 4. Connection Management Flow
### Add New Connection
```
┌─────────────────┐
│ Click "+" │
│ or File > New │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Select DB Type │
│ ○ MySQL │
│ ○ PostgreSQL │
│ ○ SQLite │
│ ○ MariaDB │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Fill Form │
│ - Name │
│ - Host/Port │
│ - Auth │
│ - Advanced opts │
└────────┬────────┘
│
│ Test Connection
▼
┌─────────────────┐
│ Connection Test │
│ Result │
└────────┬────────┘
│
│ Success → Save
▼
┌─────────────────┐
│ Added to │
│ Connection List │
└─────────────────┘
```
### Edit/Delete Connection
```
┌─────────────────┐
│ Right-click │
│ Connection │
└────────┬────────┘
│
├─────────────┬──────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Edit │ │ Duplicate │ │ Delete │
│ Connection │ │ Connection │ │ Connection │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
▼
┌─────────────────┐
│ Confirm Delete │
│ "Are you sure?" │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Connection │
│ Removed │
└─────────────────┘
```
---
## 5. Data Export Flow
```
┌─────────────────┐
│ Select Data │
│ (table/query │
│ results) │
└────────┬────────┘
│
│ Click Export button
▼
┌─────────────────┐
│ Export Dialog │
│ - Format: │
│ CSV/JSON/SQL │
│ - Options │
│ - Destination │
└────────┬────────┘
│
│ Configure options
▼
┌─────────────────┐
│ Review Settings │
│ - Preview │
│ - Row count │
│ - File size est.│
└────────┬────────┘
│
│ Click Export
▼
┌─────────────────┐
│ Export Progress │
│ [████████░░] 80%│
└────────┬────────┘
│
▼
┌─────────────────┐
│ Export Complete │
│ ✓ 1,234 rows │
│ exported to │
│ /path/file.csv│
│ │
│ [Open File] │
└─────────────────┘
```
---
## 6. Error Handling Flow
### Connection Error
```
┌─────────────────┐
│ Attempt Connect │
└────────┬────────┘
│
│ Fails
▼
┌─────────────────┐
│ Error Dialog │
│ ┌─────────────┐ │
│ │ ⚠ Connection│ │
│ │ Failed │ │
│ │ │ │
│ │ ECONNREFUSED│ │
│ │ localhost: │ │
│ │ 3306 │ │
│ └─────────────┘ │
│ │
│ Common causes: │
│ • Server not │
│ running │
│ • Wrong port │
│ • Firewall │
│ │
│ [Retry] [Help] │
└─────────────────┘
```
### Query Error
```
┌─────────────────┐
│ Execute Query │
└────────┬────────┘
│
│ Syntax Error
▼
┌─────────────────┐
│ Results Panel │
│ Shows error: │
│ ┌─────────────┐ │
│ │ ❌ Error │ │
│ │ Line 3: │ │
│ │ Unknown col │ │
│ │ 'emai' │ │
│ │ │ │
│ │ SELECT id, │ │
│ │ emai │ │
│ │ ^^^^ │ │
│ └─────────────┘ │
└─────────────────┘
```
---
## 7. Keyboard Navigation Flow
```
Global Shortcuts:
- Ctrl+N: New connection
- Ctrl+T: New query tab
- Ctrl+S: Save
- Ctrl+W: Close tab
- Ctrl+Enter: Run query
- Ctrl+F: Find in editor
- Ctrl+,: Settings
Within Data Grid:
- Arrow keys: Navigate cells
- Enter: Edit cell
- Esc: Cancel edit
- Ctrl+C: Copy selection
- Ctrl+F: Filter column
Within Query Editor:
- Ctrl+Space: Autocomplete
- Tab: Insert snippet
- Ctrl+/: Toggle comment
- Ctrl+D: Duplicate line
```
---
## 8. Settings/Preferences Flow
```
┌─────────────────┐
│ Tools > Settings│
│ or Ctrl+, │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Settings Modal │
│ ┌─────────────┐ │
│ │ General │ │ ← Selected
│ │ Editor │ │
│ │ Data Grid │ │
│ │ Keybindings │ │
│ │ Themes │ │
│ └─────────────┘ │
│ │
│ ┌─────────────┐ │
│ │ Font size │ │
│ │ [14 ▼] │ │
│ │ │ │
│ │ Theme │ │
│ │ [Light ▼] │ │
│ │ │ │
│ │ Auto-save │ │
│ │ [✓] │ │
│ └─────────────┘ │
│ │
│ [Reset] [OK] │
└─────────────────┘
```
---
## Edge Cases Handled
1. **Lost Connection During Query**
- Show error message
- Offer to reconnect
- Preserve query text
2. **Large Result Sets (>10k rows)**
- Warn user before loading all
- Offer to limit results
- Provide streaming option
3. **Unsaved Changes on Close**
- Prompt to save
- Auto-save to temp file
- Restore on relaunch
4. **Multiple Tabs with Same Connection**
- Share connection instance
- Independent transactions
- Clear tab indicators
5. **Long-running Queries**
- Show progress if available
- Provide cancel button
- Timeout configuration

228
doc/wireframes.md Normal file
View File

@@ -0,0 +1,228 @@
# uzdb UI Wireframes
## Main Application Window
### 1. Connection Manager (Startup Screen)
```
┌─────────────────────────────────────────────────────────────┐
│ uzdb - Connect │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ + New Connection │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 🗄️ Local MySQL │ │
│ │ localhost:3306 • mysql │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 🐘 Production PostgreSQL │ │
│ │ prod-db.example.com:5432 • postgres │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ ◪ Local SQLite │ │
│ │ ~/data/app.db │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ [New Connection] [Edit] [Delete] [Connect] │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 2. Main Application Layout
```
┌────────────────────────────────────────────────────────────────────┐
│ File Edit View Query Tools Help │
├────────────────────────────────────────────────────────────────────┤
│ [▶ Run] [💾 Save] [📤 Export] [🔍 Find] [Connection: ▼] │
├─────────────┬──────────────────────────────────────────────────────┤
│ │ ┌─ Query Editor ──────────────────────────────┐ │
│ 🗄️ Database │ │ │ │
│ ├─ 🗄️ MySQL │ │ SELECT * FROM users │ │
│ │ ├─ 📊 public │ WHERE active = 1; │ │
│ │ │ ├─ 📋 users │ │ │
│ │ │ ├─ 📋 products │ │ │
│ │ │ └─ 📋 orders │ │ │
│ │ └─ 📊 information_schema │ │ │
│ ├─ 🐘 PostgreSQL│ └─────────────────────────────────────────┘ │
│ │ └─ 📊 public │ 127 rows │ 0.045s │
│ └─ ◪ SQLite ├──────────────────────────────────────────────────┤
│ │ Results │
│ Connections │ ┌─────────────────────────────────────────────┐ │
│ (drag to add) │ │ id │ name │ email │ active │ │
│ │ ├────┼──────────┼────────────────┼───────────┤ │
│ │ │ 1 │ Alice │ alice@mail.com │ ✓ │ │
│ │ │ 2 │ Bob │ bob@mail.com │ ✓ │ │
│ │ │ 3 │ Charlie │ charlie@mail.c │ ✗ │ │
│ │ └─────────────────────────────────────────────┘ │
│ │ │
│ │ [<] [1] [2] [3] [...] [10] [>] Per page: [25▼] │
├─────────────┴───────────────────────────────────────────────────┤
│ ✓ Connected to MySQL@localhost:3306 │ UTF-8 │ LF │ ins │
└──────────────────────────────────────────────────────────────────┘
```
### 3. Query Editor Tab
```
┌─ Untitled.sql ───────────────────────────────────────────────────┐
│ 1 │ SELECT u.id, u.name, COUNT(o.id) as order_count │
│ 2 │ FROM users u │
│ 3 │ LEFT JOIN orders o ON u.id = o.user_id │
│ 4 │ WHERE u.created_at > '2024-01-01' │
│ 5 │ GROUP BY u.id, u.name │
│ 6 │ HAVING COUNT(o.id) > 5 │
│ 7 │ ORDER BY order_count DESC │
│ 8 │ LIMIT 100; │
└──────────────────────────────────────────────────────────────────┘
▶ Run (Ctrl+Enter) │ Explain │ Format │ History │ Snippets
```
### 4. Table Data View
```
┌─ public.users ───────────────────────────────────────────────────┐
│ [Filters] [Sort] [Group By] [Refresh] [Export] [Import] │
├──────────────────────────────────────────────────────────────────┤
│ ☑ │ id │ name │ email │ created_at │ [actions] │
├───┼─────┼─────────┼─────────────────┼─────────────┼───────────┤
│ ✓ │ 1 │ Alice │ alice@mail.com │ 2024-01-15 │ ✏️ 🗑️ │
│ ✓ │ 2 │ Bob │ bob@mail.com │ 2024-01-16 │ ✏️ 🗑️ │
│ ✓ │ 3 │ Charlie │ charlie@mail.co │ 2024-01-17 │ ✏️ 🗑️ │
│ ✓ │ 4 │ Diana │ diana@mail.com │ 2024-01-18 │ ✏️ 🗑️ │
└──────────────────────────────────────────────────────────────────┘
│ Showing 1-25 of 1,247 rows [First] [Prev] [1] [2] [Next] [Last]│
└───────────────────────────────────────────────────────────────────┘
```
### 5. Table Details Panel (Right Sidebar)
```
┌─ Table Info ─────────────────────────────────┐
│ 📋 users │
├──────────────────────────────────────────────┤
│ Columns (5) │
│ ┌──────────────────────────────────────────┐ │
│ │ name │ type │ null │ key │ │
│ ├──────────────────────────────────────────┤ │
│ │ id │ int │ ❌ │ PK │ │
│ │ name │ varchar │ ❌ │ │ │
│ │ email │ varchar │ ❌ │ UK │ │
│ │ created_at │ timestamp │ ✓ │ │ │
│ │ active │ boolean │ ❌ │ │ │
│ └──────────────────────────────────────────┘ │
│ │
│ Indexes (2) │
│ ├─ PRIMARY (id) │
│ └─ idx_email (email) │
│ │
│ Foreign Keys (0) │
│ │
│ Triggers (1) │
│ └─ update_timestamp │
└──────────────────────────────────────────────┘
```
### 6. New Connection Dialog
```
┌─────────────────────────────────────────────────────────────┐
│ New Connection [✕] │
├─────────────────────────────────────────────────────────────┤
│ │
│ Database Type: [MySQL ▼] │
│ │
│ ┌─ Connection ──────────────────────────────────────────┐ │
│ │ Name: [Local Development ] │ │
│ │ Host: [localhost ] │ │
│ │ Port: [3306 ] │ │
│ │ Username: [root ] │ │
│ │ Password: [••••••••••••••••• ] 👁 │ │
│ │ Database: [ ] │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Advanced ────────────────────────────────────────────┐ │
│ │ SSL: [▼] │ │
│ │ Timeout: [30] seconds │ │
│ │ Max connections: [10] │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ [Test Connection] [Cancel] [Save & Connect] │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 7. Export Data Dialog
```
┌─────────────────────────────────────────────────────────────┐
│ Export Data [✕] │
├─────────────────────────────────────────────────────────────┤
│ │
│ Source: [✓ users (entire table) ▼] │
│ │
│ Format: [CSV Comma-separated (.) ▼] │
│ │
│ ┌─ Options ────────────────────────────────────────────┐ │
│ │ ☑ Include column headers │ │
│ │ ☐ Quote all fields │ │
│ │ Encoding: [UTF-8 ] │ │
│ │ Line endings: [Unix (LF) ▼] │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ Output: (○) Copy to clipboard │
│ (●) Save to file │
│ [ /home/user/exports/users.csv ] [...] │
│ │
│ [Cancel] [Export] │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 8. Empty State - No Connections
```
┌─────────────────────────────────────────────────────────────┐
│ │
│ │
│ 🗄️ │
│ │
│ No Database Connections │
│ │
│ Get started by connecting to your first database │
│ │
│ │
│ [+ New Connection] │
│ │
│ Supported: MySQL, PostgreSQL, SQLite, MariaDB │
│ │
└─────────────────────────────────────────────────────────────┘
```
## Responsive Considerations
### Small Screens (< 768px)
- Sidebar becomes collapsible drawer
- Tabs stack vertically
- Toolbar items move to overflow menu
- Data grid shows horizontal scroll
### Medium Screens (768px - 1024px)
- Sidebar can be collapsed
- Single query editor tab visible
- Reduced panel padding
---
## Component States
### Button States
- **Default**: Primary color background
- **Hover**: Darken 10%
- **Active**: Darken 20%, slight inset shadow
- **Disabled**: 50% opacity, not clickable
- **Loading**: Spinner replaces icon/text
### Input States
- **Default**: Light border
- **Focus**: Primary color ring
- **Error**: Red border + error message
- **Disabled**: Gray background, not editable
- **Read-only**: Subtle background, copyable
### Connection Status
- **Connected**: Green dot + "Connected"
- **Connecting**: Spinning loader
- **Disconnected**: Gray dot + "Disconnected"
- **Error**: Red dot + error tooltip