feat: add comprehensive CCWMCP guide and installation instructions

2026-03-01 15:03:57 +08:00 · 2026-02-28 23:40:51 +08:00
parent 096fc1c380
commit 0a49dc0675
13 changed files with 2298 additions and 103 deletions
--- a/docs/features/issue-hub.md
+++ b/docs/features/issue-hub.md
@@ -0,0 +1,172 @@
+# Issue Hub
+
+## One-Liner
+
+**The Issue Hub is a unified management interface for issues, execution queues, and discovery sessions with tabbed navigation and shared actions.**
+
+---
+
+## Pain Points Solved
+
+| Pain Point | Current State | Issue Hub Solution |
+|------------|---------------|-------------------|
+| **Scattered views** | Separate pages for issues/queue/discovery | Single unified page with tab navigation |
+| **Context switching** | Hard to move between related features | Tab-based navigation persists in URL |
+| **Duplicate actions** | Different actions per view | Context-aware action buttons per tab |
+| **No issue creation** | Can't create new issues from UI | New issue dialog with attachments |
+| **Missing sync** | No GitHub integration | GitHub sync button on Issues tab |
+
+---
+
+## Page Overview
+
+**Location**: `ccw/frontend/src/pages/IssueHubPage.tsx`
+
+**Purpose**: Unified page for managing issues, queue, and discovery with tab navigation and context-aware actions.
+
+**Access**: Navigation → Issues OR direct routes `/issues?tab=issues|queue|discovery`
+
+### Layout
+
+```
+--------------------------------------------------------------------------+
+|  Issue Hub Header (dynamic based on active tab)                             |
+|  [Refresh] [GitHub Sync] [Create Issue] [Fullscreen]                       |
+--------------------------------------------------------------------------+
+|  [Issues] [Queue] [Discovery]                                              |
+--------------------------------------------------------------------------+
+|  Tab Content (switches based on active tab)                                |
+|  +--------------------------------------------------------------------+    |
+|  |                                                                    |    |
+|  |  Issues Panel OR Queue Panel OR Discovery Panel                    |    |
+|  |                                                                    |    |
+|  |  Each panel has its own layout and controls                        |    |
+|  |                                                                    |    |
+|  +--------------------------------------------------------------------+    |
+--------------------------------------------------------------------------+
+```
+
+---
+
+## Core Features
+
+| Feature | Description |
+|---------|-------------|
+| **Tab Navigation** | Three tabs: Issues, Queue, Discovery. Tab state persists in URL (`?tab=issues`) |
+| **Dynamic Header** | Header title changes based on active tab |
+| **Context-Aware Actions** | Action buttons change based on current tab |
+| **GitHub Sync** | Pull issues from GitHub (Issues tab only) |
+| **Create Issue** | Modal dialog for creating new issues with attachments |
+| **Immersive Mode** | Fullscreen toggle to hide app chrome |
+| **Auto-Refresh** | Per-tab refresh buttons with loading states |
+
+### Tab-Specific Features
+
+| Tab | Features |
+|-----|----------|
+| **Issues** | Refresh, GitHub Sync, Create Issue buttons |
+| **Queue** | Refresh button only |
+| **Discovery** | Internal controls (no header actions) |
+
+---
+
+## Usage Guide
+
+### Basic Workflow
+
+1. **Navigate to Issue Hub**: Click "Issues" in the navigation
+2. **Switch Tabs**: Click tab buttons or modify URL (`?tab=queue`)
+3. **Issues Tab**: View issues, sync from GitHub, create new issues
+4. **Queue Tab**: View and manage execution queue
+5. **Discovery Tab**: Track discovery sessions
+
+### Key Interactions
+
+| Interaction | How to Use |
+|-------------|------------|
+| **Switch tabs** | Click tab buttons OR use URL parameter `?tab=issues|queue|discovery` |
+| **Refresh current tab** | Click the refresh button (actions update per tab) |
+| **Sync from GitHub** | Click the GitHub sync button on Issues tab |
+| **Create new issue** | Click "Create Issue" button, fill in the form |
+| **Toggle fullscreen** | Click the fullscreen button to enter/exit immersive mode |
+
+### New Issue Dialog
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| **Title** | Issue title (max 200 chars) | Yes |
+| **Description** | Detailed context (max 10000 chars) | No |
+| **Type** | Bug, Feature, Improvement, Other | No (default: Other) |
+| **Priority** | Low, Medium, High, Critical | No (default: Medium) |
+| **Attachments** | Images, Markdown, text, PDF files | No |
+
+**Attachment Support**:
+- Drag and drop files onto the upload area
+- Click to open file picker
+- Supported types: Images, Markdown (.md), text (.txt), JSON (.json), PDF (.pdf)
+- Remove attachments before creating issue
+
+---
+
+## Components Reference
+
+### Main Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `IssueHubPage` | `@/pages/IssueHubPage.tsx` | Main issue hub with tabs |
+| `IssueHubHeader` | `@/components/issue/hub/IssueHubHeader.tsx` | Dynamic header based on tab |
+| `IssueHubTabs` | `@/components/issue/hub/IssueHubTabs.tsx` | Tab switcher |
+| `IssuesPanel` | `@/components/issue/hub/IssuesPanel.tsx` | Issues list and management |
+| `QueuePanel` | `@/components/issue/hub/QueuePanel.tsx` | Queue management |
+| `DiscoveryPanel` | `@/components/issue/hub/DiscoveryPanel.tsx` | Discovery tracking |
+| `NewIssueDialog` | (internal to IssueHubPage) | Create issue modal |
+
+### State Management
+
+- **Local state**:
+  - `currentTab`: IssueTab ('issues' | 'queue' | 'discovery')
+  - `isNewIssueOpen`: boolean
+  - `isGithubSyncing`: boolean
+
+- **URL state**:
+  - Tab persists in URL search param: `?tab=issues`
+
+- **Custom hooks**:
+  - `useIssues` - Issues data and refresh
+  - `useIssueQueue` - Queue data and refresh
+  - `useIssueMutations` - Create issue mutation
+  - `pullIssuesFromGitHub` - GitHub sync API call
+  - `uploadAttachments` - Attachment upload for new issues
+
+---
+
+## Configuration
+
+### Tab Navigation
+
+Tabs are validated against allowed values:
+
+```typescript
+const VALID_TABS: IssueTab[] = ['issues', 'queue', 'discovery'];
+```
+
+Invalid tab values automatically redirect to 'issues'.
+
+### Issue Types
+
+| Type | Color | Description |
+|------|-------|-------------|
+| **Bug** | Red | Functional errors or problems |
+| **Feature** | Green | New feature requests |
+| **Improvement** | Blue | Enhancements to existing features |
+| **Other** | Gray | Other types |
+
+---
+
+## Related Links
+
+- [Issues Panel](/features/issue-hub) - Detailed issue management
+- [Queue](/features/queue) - Queue management details
+- [Discovery](/features/discovery) - Discovery session details
+- [Sessions](/features/sessions) - Workflow session management