diff --git a/docs/COPILOT_CODE_MAPPING.md b/docs/COPILOT_CODE_MAPPING.md new file mode 100644 index 0000000..9327c6c --- /dev/null +++ b/docs/COPILOT_CODE_MAPPING.md @@ -0,0 +1,498 @@ +# Copilot Chat Use Cases - Ánh xạ mã nguồn + +> Tài liệu ánh xạ chi tiết từng use case vào các phần mã nguồn cụ thể trong repo [ATC-O48/Claude-OpenAI-Code](https://github.com/ATC-O48/Claude-OpenAI-Code) và [ATC-O48/copilot-cli](https://github.com/ATC-O48/copilot-cli). + +--- + +## Mục lục + +- [Tổng quan ánh xạ](#tổng-quan-ánh-xạ) +- [Repo ATC-O48/Claude-OpenAI-Code](#repo-atc-o48claude-openai-code) + - [1. Giao tiếp hiệu quả](#1-giao-tiếp-hiệu-quả) + - [2. Gỡ lỗi mã](#2-gỡ-lỗi-mã) + - [3. Phân tích chức năng](#3-phân-tích-chức-năng) + - [4. Tái cấu trúc mã](#4-tái-cấu-trúc-mã) + - [5. Ghi chép mã nguồn](#5-ghi-chép-mã-nguồn) + - [6. Kiểm thử mã](#6-kiểm-thử-mã) + - [7. Phân tích an ninh](#7-phân-tích-an-ninh) +- [Repo ATC-O48/copilot-cli](#repo-atc-o48copilot-cli) +- [Sơ đồ ánh xạ tổng quan](#sơ-đồ-ánh-xạ-tổng-quan) +- [Tài liệu liên quan](#tài-liệu-liên-quan) + +--- + +## Tổng quan ánh xạ + +```mermaid +graph LR + subgraph "Use Cases (34)" + UC[34 Use Cases
7 nhóm kỹ năng] + end + subgraph "Claude-OpenAI-Code" + WS[workspaceStore.ts
519 dòng] + COMP[Components
15+ files] + CSS[index.css
1147 dòng] + DOCS[docs/
DESIGN_REVIEW.md] + CFG[Config files
eslint, package.json] + GH[.github/
workflows, templates] + end + subgraph "copilot-cli" + CL[changelog.md
1680 dòng] + RM[README.md] + GH2[.github/] + end + UC --> WS + UC --> COMP + UC --> CSS + UC --> DOCS + UC --> CFG + UC --> GH + UC --> CL + UC --> RM + UC --> GH2 +``` + +--- + +## Repo ATC-O48/Claude-OpenAI-Code + +### 1. Giao tiếp hiệu quả + +#### UC-01: Tạo mẫu (Generate Templates) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `README.md` | +| **Dòng** | 240-258 | +| **Chi tiết** | Contributing guidelines hiện tại cơ bản. Có thể tạo PR template, issue template chi tiết hơn, contributing guide đầy đủ cho dự án React/TypeScript IDE. | +| **Áp dụng thêm** | `.github/ISSUE_TEMPLATE/` — hiện chỉ có `ISSUE_TEMPLATE_GOOD_FIRST.md`, cần thêm bug report, feature request templates. | + +#### UC-04: Tạo sơ đồ (Create Diagrams) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `docs/DESIGN_REVIEW.md` | +| **Dòng** | 1-129 | +| **Chi tiết** | Kiến trúc hiện tại mô tả bằng text. Cần Mermaid diagrams cho: component tree, data flow (FileTree → workspaceStore → EditorTool), layout rendering (recursive PaneSplit/Pane). | + +#### UC-05: Tạo bảng (Create Tables) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `README.md` | +| **Dòng** | 136-147 | +| **Chi tiết** | Bảng tools hiện tại liệt kê 9 tools cơ bản. Có thể mở rộng bảng so sánh: tên tool, ToolType enum, có state riêng không, có kết nối store không, độ phức tạp UI. | + +--- + +### 2. Gỡ lỗi mã + +#### UC-06: Gỡ lỗi JSON không hợp lệ (Debug Invalid JSON) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 74-108 | +| **Chi tiết** | Sample files data hardcoded dưới dạng nested `FileNode` objects. Cần xác minh tất cả objects tuân thủ interface `FileNode` trong `src/types/workspace.ts` (id, name, type, children, content). | +| **Liên kết type** | `src/types/workspace.ts` dòng 1-22 — `FileNode` interface definition. | + +#### UC-07: Xử lý giới hạn tỷ lệ truy cập API (Handle API Rate Limits) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/tools/AgentTool.tsx` | +| **Dòng** | 17-26 | +| **Chi tiết** | Agent hiện tại trả về mock response (`setTimeout` + hardcoded reply). Khi kết nối API thật, cần thêm: exponential backoff, retry sau HTTP 429, hiển thị loading/error state cho người dùng. | + +#### UC-08: Chẩn đoán lỗi kiểm tra (Diagnose Test Failures) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 483-499 | +| **Chi tiết** | Hàm `duplicateFile` — kịch bản test failure: duplicate file ở root level (parentPath rỗng). Logic tìm parent node bằng `findFileNode(parentPath)` có thể trả về `null` khi path rỗng. | + +--- + +### 3. Phân tích chức năng + +#### UC-09: Khám phá phương án triển khai (Explore Feature Implementations) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/layout/PaneView.tsx` | +| **Dòng** | Toàn bộ file | +| **Chi tiết** | Triển khai drag-and-drop tab reordering. `@dnd-kit` đã có trong `package.json`. Có thể đề xuất 3 phương án: dnd-kit sortable, HTML5 native drag, custom pointer events. | +| **Dependencies** | `package.json` dòng 15 — `@dnd-kit/core`, `@dnd-kit/sortable` đã cài đặt. | + +#### UC-10: Phân tích phản hồi người dùng (Analyze User Feedback) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `docs/DESIGN_REVIEW.md` | +| **Dòng** | 1-129 | +| **Chi tiết** | File chứa nhiều "Recommendations" và "Areas for Improvement". Cần tổng hợp thành danh sách ưu tiên theo impact/effort matrix: persistent state, undo/redo, plugin system, accessibility, performance. | + +--- + +### 4. Tái cấu trúc mã + +#### UC-11: Cải thiện khả năng đọc hiểu mã (Improve Code Readability) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 153-252 | +| **Chi tiết** | Các hàm đệ quy `findPaneAndUpdate` (dòng 153-184), `splitInLayout` (dòng 233-252), `updateFileNodes` (dòng 185-215) thiếu comments, tên biến callback parameters không rõ ràng (`cb`, `node`). Cần thêm JSDoc, đặt tên mô tả hơn, tách logic phức tạp. | + +#### UC-12: Sửa lỗi lint (Fix Lint Errors) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `eslint.config.js` + `src/**/*.{ts,tsx}` | +| **Dòng** | — | +| **Chi tiết** | Chạy `npm run lint` để tìm tất cả lỗi và cảnh báo ESLint. Config sử dụng `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, `eslint-plugin-react-refresh`. | + +#### UC-13: Tái cấu trúc hiệu năng (Refactor for Performance) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/search/SearchBar.tsx` | +| **Dòng** | 6-15, 47-94 | +| **Chi tiết** | `flattenFiles()` (dòng 6-15) chạy recursive traversal mỗi lần component render. Search results (dòng 47-94) tính lại không cần thiết. Cần: `useMemo` cho flattenFiles, `debounce` cho search input, virtualization cho danh sách dài. | + +#### UC-14: Tái cấu trúc bền vững (Refactor for Sustainability) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/index.css` | +| **Dòng** | 1-1147 | +| **Chi tiết** | CSS monolith 1147 dòng chứa styles cho mọi component. Nên tách thành CSS modules hoặc Tailwind component classes. Giảm CSS không sử dụng, tối ưu specificity, nhóm theo component. | + +#### UC-15: Tái cấu trúc mẫu thiết kế (Refactor to Design Pattern) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/tools/ToolRenderer.tsx` | +| **Dòng** | 17-44 | +| **Chi tiết** | Switch-case hardcoded cho 9 tool types (`editor`, `preview`, `console`, `shell`, `secrets`, `file-history`, `multiplayer`, `settings`, `agent`). Mỗi khi thêm tool mới phải sửa file này. Nên dùng Registry Pattern hoặc Strategy Pattern. | + +#### UC-16: Tái cấu trúc lớp truy cập dữ liệu (Refactor Data Access Layers) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 254-519 | +| **Chi tiết** | Store 519 dòng chứa cả data access (`findFileNode`, `updateFileNodes`, `findPaneAndUpdate`) và business logic (`openFile`, `duplicateFile`, `createFile`). Cần tách thành: `fileSystemService.ts` cho data operations và `workspaceActions.ts` cho business logic. | + +#### UC-17: Tách logic nghiệp vụ khỏi UI (Decouple Business Logic from UI) + +**Ánh xạ 1:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/filetree/FileTree.tsx` | +| **Dòng** | 75-187 | +| **Chi tiết** | Logic tạo file (`handleNewFile` dòng ~85, `handleCreateFile` dòng ~95) trộn lẫn với JSX rendering. Nên tách thành custom hook `useFileTreeActions()`. Component chỉ render UI, hook xử lý logic. | + +**Ánh xạ 2:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/filetree/FileContextMenu.tsx` | +| **Dòng** | 36-54 | +| **Chi tiết** | `handleRename` (dòng ~36) dùng `window.prompt()` trực tiếp trong component. `handleDownload` (dòng ~44) chứa logic tạo Blob và download link trong component. Cần tách ra utility functions. | + +#### UC-18: Giải quyết vấn đề xuyên suốt (Address Cross-Cutting Concerns) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/layout/PaneOptionsMenu.tsx` | +| **Dòng** | 22-30 | +| **Chi tiết** | Click-outside detection logic lặp lại ở 3 component: `PaneOptionsMenu.tsx` (dòng 22-30), `FileContextMenu.tsx` (dòng 20-28), `SearchBar.tsx` (dòng 25-33). Mỗi nơi đều dùng `useEffect` + `addEventListener('mousedown')`. Cần tạo shared hook `useClickOutside()`. | +| **Files liên quan** | `src/components/filetree/FileContextMenu.tsx`, `src/components/search/SearchBar.tsx` | + +#### UC-19: Đơn giản hóa kế thừa (Simplify Inheritance Hierarchies) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/types/workspace.ts` | +| **Dòng** | 24-45 | +| **Chi tiết** | Union type `Pane \| PaneSplit` lặp lại ở nhiều nơi: `workspace.ts`, `workspaceStore.ts`, `WorkspaceLayout.tsx`. Cần tạo type alias `LayoutNode = Pane \| PaneSplit` và hàm type guard `isPane()` / `isPaneSplit()` dùng chung. | +| **Files liên quan** | `src/stores/workspaceStore.ts`, `src/components/layout/WorkspaceLayout.tsx` | + +#### UC-20: Khắc phục tắc nghẽn DB (Fix Database Bottlenecks) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | Toàn bộ file | +| **Chi tiết** | Store hiện dùng in-memory state (Zustand). Nếu migrate sang IndexedDB/localStorage cho persistent file storage, cần giải quyết: non-blocking reads/writes, Web Worker cho file tree lớn, optimistic updates, sync strategy. | + +#### UC-21: Dịch mã (Translate Code) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | Toàn bộ `src/` | +| **Dòng** | — | +| **Chi tiết** | Dự án React/TypeScript có thể dịch sang Vue 3 (Composition API), Svelte, hoặc Angular. Ví dụ cụ thể: `AgentTool.tsx` (58 dòng) — component chat interface đơn giản, phù hợp để demo dịch framework. | + +--- + +### 5. Ghi chép mã nguồn + +#### UC-22: Tạo vấn đề (Create Issues) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `.github/` | +| **Dòng** | — | +| **Chi tiết** | Tạo GitHub issues dựa trên "Areas for Improvement" trong `DESIGN_REVIEW.md`: (1) Persistent state, (2) Undo/redo, (3) Plugin system, (4) Accessibility, (5) Performance optimization. Cần thêm issue templates cho bug report và feature request. | + +#### UC-23: Ghi chép mã nguồn cũ (Document Legacy Code) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 254-519 | +| **Chi tiết** | Store có 519 dòng, 30+ actions, không có JSDoc documentation. Cần thêm: mô tả cho mỗi action, parameter types documentation, return value descriptions, usage examples. | + +#### UC-24: Giải thích mã nguồn cũ (Explain Legacy Code) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 233-252 | +| **Chi tiết** | Hàm `splitInLayout` — đệ quy traverse cây layout, tìm pane target, tạo PaneSplit mới thay thế. Logic phức tạp do nested recursion + immutable state updates. | + +#### UC-25: Giải thích thuật toán phức tạp (Explain Complex Algorithms) + +**Ánh xạ 1:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/layout/WorkspaceLayout.tsx` | +| **Dòng** | 17-52 | +| **Chi tiết** | Recursive `LayoutRenderer` component: traverse cây `PaneSplit`/`Pane`, render `ResizablePanelGroup` cho splits, `PaneView` cho leaf panes. Thuật toán DFS implicit trong React render tree. | + +**Ánh xạ 2:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 233-252 | +| **Chi tiết** | `splitInLayout` — đệ quy tìm pane bằng ID, thay thế bằng PaneSplit mới chứa pane gốc + pane mới. Xử lý cả trường hợp node là PaneSplit (đệ quy xuống children) và Pane (base case). | + +#### UC-26: Đồng bộ tài liệu (Sync Documentation) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `docs/DESIGN_REVIEW.md` vs `src/` | +| **Dòng** | — | +| **Chi tiết** | Design review document có thể outdated so với code hiện tại. Cần so sánh: component list trong doc vs thực tế, API descriptions vs implementation, recommendations đã thực hiện chưa. | + +#### UC-27: Viết bài blog/thảo luận (Write Blog Posts) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/layout/WorkspaceLayout.tsx`, `src/components/layout/PaneView.tsx` | +| **Dòng** | — | +| **Chi tiết** | Chủ đề blog: "Xây dựng recursive layout system cho browser-based IDE". Sử dụng code examples từ LayoutRenderer, PaneView, và react-resizable-panels integration. | + +--- + +### 6. Kiểm thử mã + +#### UC-28: Tạo bài kiểm tra đơn vị (Generate Unit Tests) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | Toàn bộ file | +| **Chi tiết** | Không có test nào trong repo. Cần unit tests cho tất cả store actions: `addWindow`, `removeWindow`, `addTab`, `removeTab`, `splitPane`, `openFile`, `createFile`, `renameFile`, `deleteFile`, `duplicateFile`, và các helper functions. Sử dụng Vitest. | + +#### UC-29: Tạo đối tượng giả (Create Mock Objects) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/stores/workspaceStore.ts` | +| **Dòng** | 254-519 | +| **Chi tiết** | Tạo mock factory cho Zustand store `useWorkspaceStore`. Mock data cần bao gồm: windows (với panes/tabs), files (nested FileNode tree), secrets (key-value pairs), resources (RAM/CPU/Storage). Dùng cho component testing. | + +#### UC-30: Tạo kiểm tra E2E (Create E2E Tests) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/App.tsx` | +| **Dòng** | 11-49 | +| **Chi tiết** | App.tsx là entry point chính. E2E test flow: (1) Mở app → verify layout renders, (2) Click file trong FileTree → verify EditorTool hiển thị nội dung, (3) Split pane → verify 2 panes hiện ra, (4) Search file (Ctrl+K) → verify kết quả. Sử dụng Playwright. | +| **CI liên quan** | `.github/workflows/datadog-synthetics.yml` — đã có Datadog E2E config. | + +#### UC-31: Cập nhật bài kiểm thử (Update Unit Tests) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | — (chưa có tests) | +| **Dòng** | — | +| **Chi tiết** | Sau khi refactor ToolRenderer.tsx sang Registry Pattern (UC-15), cần cập nhật/tạo tests để cover: đăng ký tool mới vào registry, render đúng component cho từng ToolType, fallback cho unknown tool type, type safety. | + +--- + +### 7. Phân tích an ninh + +#### UC-32: Bảo mật kho lưu trữ (Secure Repository) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `.github/` | +| **Dòng** | — | +| **Chi tiết** | Thiếu các file bảo mật chuẩn: (1) `.github/dependabot.yml` — auto-update dependencies, (2) `SECURITY.md` — vulnerability reporting policy, (3) `CODEOWNERS` — code review assignments. Hiện chỉ có `Funding.yml` và 1 issue template. | + +#### UC-33: Quản lý phụ thuộc (Manage Dependencies) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `package.json` | +| **Dòng** | 12-37 | +| **Chi tiết** | Dependencies cần kiểm tra: React 19, Zustand, Vite, Tailwind CSS v4, @dnd-kit, lucide-react, react-resizable-panels. DevDependencies: TypeScript, ESLint plugins. Cần Dependabot config cho automated vulnerability scanning. | + +#### UC-34: Tìm lỗ hổng bảo mật (Find Security Vulnerabilities) + +**Ánh xạ 1:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/tools/SecretsTool.tsx` | +| **Dòng** | 39 | +| **Chi tiết** | Secrets hiển thị hardcoded string `'sk-abc123...xyz'` thay vì giá trị thật. Trong production, cần proper masking logic, secure storage, và không log/display secrets trong DevTools. | + +**Ánh xạ 2:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/filetree/FileContextMenu.tsx` | +| **Dòng** | 44-54 | +| **Chi tiết** | `handleDownload` tạo Blob từ `file.content` và trigger download không có sanitization. Nếu file content chứa malicious scripts, có thể dẫn đến XSS khi mở file đã download. | + +**Ánh xạ 3:** + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `src/components/spotlight/SpotlightPage.tsx` | +| **Dòng** | 17-21 | +| **Chi tiết** | `copyLink` function sử dụng `navigator.clipboard.writeText()` không có error handling. Clipboard API có thể fail do permissions, browser support, hoặc iframe restrictions. Cần try-catch và fallback. | + +--- + +## Repo ATC-O48/copilot-cli + +### UC-02: Trích xuất thông tin (Extract Information) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `changelog.md` | +| **Dòng** | Toàn bộ file (~1680 dòng) | +| **Chi tiết** | Changelog đồ sộ chứa lịch sử 36+ phiên bản. Cần trích xuất và phân loại: bug fixes, tính năng mới, cải thiện hiệu năng, breaking changes theo từng phiên bản. | + +### UC-03: Tổng hợp nghiên cứu (Synthesize Research) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `changelog.md` + `README.md` | +| **Dòng** | — | +| **Chi tiết** | Tổng hợp tính năng qua 36+ phiên bản: từ CLI cơ bản đến agentic loop, MCP support, Fleet orchestration. Tạo timeline phát triển và đánh giá hướng đi sản phẩm. | + +### UC-01: Tạo mẫu (Generate Templates) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `README.md` | +| **Dòng** | 100-138 | +| **Chi tiết** | Usage patterns hiện tại. Có thể tạo templates cho: CLI command cheat sheet, configuration guide, troubleshooting guide, plugin development guide. | + +### UC-22: Tạo vấn đề (Create Issues) + +| Thuộc tính | Chi tiết | +|---|---| +| **File** | `.github/` | +| **Dòng** | — | +| **Chi tiết** | Issue templates cho copilot-cli repo. Cần templates cho: bug report (với CLI version, OS info), feature request, MCP integration request. | + +--- + +## Sơ đồ ánh xạ tổng quan + +```mermaid +graph TD + subgraph "Files được ánh xạ nhiều nhất" + A[workspaceStore.ts
12 use cases] --> |UC-06,08,11,16,
20,23,24,25,28,29| S1[Store Logic] + B[ToolRenderer.tsx
2 use cases] --> |UC-15,31| S2[Design Pattern] + C[FileTree.tsx
2 use cases] --> |UC-17| S3[UI/Logic Separation] + D[DESIGN_REVIEW.md
3 use cases] --> |UC-04,10,26| S4[Documentation] + E[index.css
1 use case] --> |UC-14| S5[CSS Architecture] + F[SearchBar.tsx
2 use cases] --> |UC-13,18| S6[Performance] + end +``` + +```mermaid +pie title Phân bố ánh xạ theo file + "workspaceStore.ts" : 12 + "FileTree.tsx + FileContextMenu.tsx" : 4 + "ToolRenderer.tsx" : 2 + "SearchBar.tsx" : 2 + "DESIGN_REVIEW.md" : 3 + "Các file khác" : 15 +``` + +### Bảng tổng hợp ánh xạ + +| Use Case | Repo | File(s) chính | Dòng | Mức độ | +|---|---|---|---|---| +| UC-01 Tạo mẫu | Cả 2 | `README.md`, `.github/` | 240-258 | Đơn giản | +| UC-02 Trích xuất thông tin | copilot-cli | `changelog.md` | Toàn bộ | Đơn giản | +| UC-03 Tổng hợp nghiên cứu | copilot-cli | `changelog.md`, `README.md` | — | Đơn giản | +| UC-04 Tạo sơ đồ | Claude-OpenAI-Code | `docs/DESIGN_REVIEW.md` | 1-129 | Đơn giản | +| UC-05 Tạo bảng | Claude-OpenAI-Code | `README.md` | 136-147 | Đơn giản | +| UC-06 Gỡ lỗi JSON | Claude-OpenAI-Code | `workspaceStore.ts` | 74-108 | Trung cấp | +| UC-07 Xử lý API rate limit | Claude-OpenAI-Code | `AgentTool.tsx` | 17-26 | Trung cấp | +| UC-08 Chẩn đoán lỗi test | Claude-OpenAI-Code | `workspaceStore.ts` | 483-499 | Trung cấp | +| UC-09 Khám phá phương án | Claude-OpenAI-Code | `PaneView.tsx` | Toàn bộ | Trung cấp | +| UC-10 Phân tích phản hồi | Claude-OpenAI-Code | `DESIGN_REVIEW.md` | 1-129 | Trung cấp | +| UC-11 Cải thiện đọc hiểu | Claude-OpenAI-Code | `workspaceStore.ts` | 153-252 | Đơn giản | +| UC-12 Sửa lỗi lint | Claude-OpenAI-Code | `eslint.config.js`, `src/` | — | Trung cấp | +| UC-13 Tái cấu trúc hiệu năng | Claude-OpenAI-Code | `SearchBar.tsx` | 6-15, 47-94 | Đơn giản | +| UC-14 Tái cấu trúc bền vững | Claude-OpenAI-Code | `index.css` | 1-1147 | Đơn giản | +| UC-15 Tái cấu trúc mẫu thiết kế | Claude-OpenAI-Code | `ToolRenderer.tsx` | 17-44 | Trung cấp | +| UC-16 Tái cấu trúc data access | Claude-OpenAI-Code | `workspaceStore.ts` | 254-519 | Trình độ cao | +| UC-17 Tách logic/UI | Claude-OpenAI-Code | `FileTree.tsx`, `FileContextMenu.tsx` | 75-187, 36-54 | Trình độ cao | +| UC-18 Vấn đề xuyên suốt | Claude-OpenAI-Code | `PaneOptionsMenu.tsx` | 22-30 | Trung cấp | +| UC-19 Đơn giản hóa kế thừa | Claude-OpenAI-Code | `workspace.ts` | 24-45 | Trung cấp | +| UC-20 Tắc nghẽn DB | Claude-OpenAI-Code | `workspaceStore.ts` | Toàn bộ | Trình độ cao | +| UC-21 Dịch mã | Claude-OpenAI-Code | Toàn bộ `src/` | — | Đơn giản | +| UC-22 Tạo vấn đề | Cả 2 | `.github/` | — | Đơn giản | +| UC-23 Ghi chép mã cũ | Claude-OpenAI-Code | `workspaceStore.ts` | 254-519 | Đơn giản | +| UC-24 Giải thích mã cũ | Claude-OpenAI-Code | `workspaceStore.ts` | 233-252 | Đơn giản | +| UC-25 Giải thích thuật toán | Claude-OpenAI-Code | `WorkspaceLayout.tsx`, `workspaceStore.ts` | 17-52, 233-252 | Trung cấp | +| UC-26 Đồng bộ tài liệu | Claude-OpenAI-Code | `DESIGN_REVIEW.md` vs `src/` | — | Trung cấp | +| UC-27 Viết blog | Claude-OpenAI-Code | `WorkspaceLayout.tsx`, `PaneView.tsx` | — | Đơn giản | +| UC-28 Tạo unit tests | Claude-OpenAI-Code | `workspaceStore.ts` | Toàn bộ | Trung cấp | +| UC-29 Tạo mock objects | Claude-OpenAI-Code | `workspaceStore.ts` | 254-519 | Trung cấp | +| UC-30 Tạo E2E tests | Claude-OpenAI-Code | `App.tsx` | 11-49 | Trình độ cao | +| UC-31 Cập nhật tests | Claude-OpenAI-Code | — | — | Trung cấp | +| UC-32 Bảo mật repo | Claude-OpenAI-Code | `.github/` | — | Đơn giản | +| UC-33 Quản lý phụ thuộc | Claude-OpenAI-Code | `package.json` | 12-37 | Đơn giản | +| UC-34 Tìm lỗ hổng | Claude-OpenAI-Code | `SecretsTool.tsx`, `FileContextMenu.tsx`, `SpotlightPage.tsx` | 39, 44-54, 17-21 | Trung cấp | + +--- + +## Tài liệu liên quan + +| File | Mô tả | +|------|--------| +| [COPILOT_USECASES.md](./COPILOT_USECASES.md) | Tổng hợp chi tiết 34 use cases | +| [COPILOT_PROMPT_TEMPLATES.md](./COPILOT_PROMPT_TEMPLATES.md) | 34 prompt templates cho từng use case | +| [DESIGN_REVIEW.md](./DESIGN_REVIEW.md) | Đánh giá thiết kế dự án Workspace IDE | + +--- + +*Tài liệu được tạo cho dự án Workspace IDE — ATC-O48/Claude-OpenAI-Code* diff --git a/docs/COPILOT_PROMPT_TEMPLATES.md b/docs/COPILOT_PROMPT_TEMPLATES.md new file mode 100644 index 0000000..242c1a0 --- /dev/null +++ b/docs/COPILOT_PROMPT_TEMPLATES.md @@ -0,0 +1,1967 @@ +# Copilot Chat - Prompt Templates + +> 34 prompt templates chi tiết cho từng use case, áp dụng vào mã nguồn thực tế trong repo [ATC-O48/Claude-OpenAI-Code](https://github.com/ATC-O48/Claude-OpenAI-Code) và [ATC-O48/copilot-cli](https://github.com/ATC-O48/copilot-cli). + +--- + +## Mục lục + +- [Hướng dẫn sử dụng](#hướng-dẫn-sử-dụng) +- [1. Giao tiếp hiệu quả](#1-giao-tiếp-hiệu-quả) + - [UC-01 Tạo mẫu](#uc-01-tạo-mẫu-generate-templates) + - [UC-02 Trích xuất thông tin](#uc-02-trích-xuất-thông-tin-extract-information) + - [UC-03 Tổng hợp nghiên cứu](#uc-03-tổng-hợp-nghiên-cứu-synthesize-research) + - [UC-04 Tạo sơ đồ](#uc-04-tạo-sơ-đồ-create-diagrams) + - [UC-05 Tạo bảng](#uc-05-tạo-bảng-create-tables) +- [2. Gỡ lỗi mã](#2-gỡ-lỗi-mã) + - [UC-06 Gỡ lỗi JSON](#uc-06-gỡ-lỗi-json-không-hợp-lệ-debug-invalid-json) + - [UC-07 Xử lý API rate limit](#uc-07-xử-lý-giới-hạn-tỷ-lệ-truy-cập-api-handle-api-rate-limits) + - [UC-08 Chẩn đoán lỗi test](#uc-08-chẩn-đoán-lỗi-kiểm-tra-diagnose-test-failures) +- [3. Phân tích chức năng](#3-phân-tích-chức-năng) + - [UC-09 Khám phá phương án](#uc-09-khám-phá-phương-án-triển-khai-explore-feature-implementations) + - [UC-10 Phân tích phản hồi](#uc-10-phân-tích-phản-hồi-người-dùng-analyze-user-feedback) +- [4. Tái cấu trúc mã](#4-tái-cấu-trúc-mã) + - [UC-11 Cải thiện đọc hiểu](#uc-11-cải-thiện-khả-năng-đọc-hiểu-mã-improve-code-readability) + - [UC-12 Sửa lỗi lint](#uc-12-sửa-lỗi-lint-fix-lint-errors) + - [UC-13 Tái cấu trúc hiệu năng](#uc-13-tái-cấu-trúc-hiệu-năng-refactor-for-performance) + - [UC-14 Tái cấu trúc bền vững](#uc-14-tái-cấu-trúc-bền-vững-refactor-for-sustainability) + - [UC-15 Tái cấu trúc mẫu thiết kế](#uc-15-tái-cấu-trúc-mẫu-thiết-kế-refactor-to-design-pattern) + - [UC-16 Tái cấu trúc data access](#uc-16-tái-cấu-trúc-lớp-truy-cập-dữ-liệu-refactor-data-access-layers) + - [UC-17 Tách logic/UI](#uc-17-tách-logic-nghiệp-vụ-khỏi-ui-decouple-business-logic-from-ui) + - [UC-18 Vấn đề xuyên suốt](#uc-18-giải-quyết-vấn-đề-xuyên-suốt-address-cross-cutting-concerns) + - [UC-19 Đơn giản hóa kế thừa](#uc-19-đơn-giản-hóa-kế-thừa-simplify-inheritance-hierarchies) + - [UC-20 Tắc nghẽn DB](#uc-20-khắc-phục-tắc-nghẽn-db-fix-database-bottlenecks) + - [UC-21 Dịch mã](#uc-21-dịch-mã-translate-code) +- [5. Ghi chép mã nguồn](#5-ghi-chép-mã-nguồn) + - [UC-22 Tạo vấn đề](#uc-22-tạo-vấn-đề-create-issues) + - [UC-23 Ghi chép mã cũ](#uc-23-ghi-chép-mã-nguồn-cũ-document-legacy-code) + - [UC-24 Giải thích mã cũ](#uc-24-giải-thích-mã-nguồn-cũ-explain-legacy-code) + - [UC-25 Giải thích thuật toán](#uc-25-giải-thích-thuật-toán-phức-tạp-explain-complex-algorithms) + - [UC-26 Đồng bộ tài liệu](#uc-26-đồng-bộ-tài-liệu-sync-documentation) + - [UC-27 Viết blog](#uc-27-viết-bài-blogthảo-luận-write-blog-posts) +- [6. Kiểm thử mã](#6-kiểm-thử-mã) + - [UC-28 Tạo unit tests](#uc-28-tạo-bài-kiểm-tra-đơn-vị-generate-unit-tests) + - [UC-29 Tạo mock objects](#uc-29-tạo-đối-tượng-giả-create-mock-objects) + - [UC-30 Tạo E2E tests](#uc-30-tạo-kiểm-tra-e2e-create-e2e-tests) + - [UC-31 Cập nhật tests](#uc-31-cập-nhật-bài-kiểm-thử-update-unit-tests) +- [7. Phân tích an ninh](#7-phân-tích-an-ninh) + - [UC-32 Bảo mật repo](#uc-32-bảo-mật-kho-lưu-trữ-secure-repository) + - [UC-33 Quản lý phụ thuộc](#uc-33-quản-lý-phụ-thuộc-manage-dependencies) + - [UC-34 Tìm lỗ hổng](#uc-34-tìm-lỗ-hổng-bảo-mật-find-security-vulnerabilities) +- [Sơ đồ tổng quan](#sơ-đồ-tổng-quan) +- [Tài liệu liên quan](#tài-liệu-liên-quan) + +--- + +## Hướng dẫn sử dụng + +Mỗi prompt template bao gồm: +- **Tên use case** (tiếng Việt + tiếng Anh) +- **Mức độ**: Đơn giản / Trung cấp / Trình độ cao +- **Prompt mẫu tiếng Việt**: Sử dụng trực tiếp trong Copilot Chat +- **Prompt mẫu tiếng Anh**: Phiên bản tiếng Anh tương đương +- **Ví dụ áp dụng**: Context cụ thể trong repo + +> **Mẹo**: Copy prompt mẫu, thay đổi tên file/dòng code nếu cần, paste vào Copilot Chat. Sử dụng `@workspace` để Copilot tham chiếu toàn bộ dự án. + +--- + +## 1. Giao tiếp hiệu quả + +### UC-01: Tạo mẫu (Generate Templates) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `README.md` (dòng 240-258), `.github/ISSUE_TEMPLATE/` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-01](./COPILOT_CODE_MAPPING.md#uc-01-tạo-mẫu-generate-templates) | + +**Prompt tiếng Việt:** + +``` +Tạo một mẫu PR template cho dự án React/TypeScript IDE này, bao gồm checklist cho: +thay đổi UI, thay đổi store, thêm tool mới, và cập nhật CSS. + +Yêu cầu: +- Phần mô tả thay đổi +- Checklist kiểm tra trước khi merge +- Section cho screenshots (nếu thay đổi UI) +- Ghi chú cho reviewer +``` + +**Prompt tiếng Anh:** + +``` +Create a PR template for this React/TypeScript IDE project with checklists for: +UI changes, store changes, new tool additions, and CSS updates. + +Include: +- Change description section +- Pre-merge checklist +- Screenshots section (for UI changes) +- Reviewer notes +``` + +**Ví dụ áp dụng:** + +Áp dụng vào `.github/PULL_REQUEST_TEMPLATE.md` — hiện repo chưa có PR template. Template nên phản ánh cấu trúc dự án: `src/components/`, `src/stores/`, `src/index.css`. + +--- + +### UC-02: Trích xuất thông tin (Extract Information) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `changelog.md` (repo copilot-cli) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-02](./COPILOT_CODE_MAPPING.md#uc-02-trích-xuất-thông-tin-extract-information) | + +**Prompt tiếng Việt:** + +``` +Trích xuất tất cả các tính năng mới được thêm vào từ phiên bản 1.0.30 đến 1.0.36 +trong changelog.md, phân loại theo: bug fix, tính năng mới, cải thiện hiệu năng. + +Output dưới dạng bảng markdown với cột: Phiên bản, Loại, Mô tả ngắn. +``` + +**Prompt tiếng Anh:** + +``` +Extract all new features added between versions 1.0.30 and 1.0.36 from changelog.md. +Categorize them as: bug fix, new feature, performance improvement. + +Output as a markdown table with columns: Version, Type, Short Description. +``` + +**Ví dụ áp dụng:** + +Áp dụng vào repo `ATC-O48/copilot-cli` — file `changelog.md` có ~1680 dòng covering 36+ phiên bản. Giúp team hiểu nhanh evolution của sản phẩm. + +--- + +### UC-03: Tổng hợp nghiên cứu (Synthesize Research) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `README.md`, `docs/DESIGN_REVIEW.md` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-03](./COPILOT_CODE_MAPPING.md#uc-03-tổng-hợp-nghiên-cứu-synthesize-research) | + +**Prompt tiếng Việt:** + +``` +Tổng hợp kiến trúc của Workspace IDE từ README.md và DESIGN_REVIEW.md thành một +bản tóm tắt kỹ thuật 500 từ, bao gồm: +- Điểm mạnh của kiến trúc hiện tại +- Điểm yếu cần cải thiện +- Đề xuất cải thiện theo thứ tự ưu tiên + +Sử dụng @workspace để tham chiếu cả 2 file. +``` + +**Prompt tiếng Anh:** + +``` +Synthesize the Workspace IDE architecture from README.md and DESIGN_REVIEW.md into +a 500-word technical summary including: +- Current architecture strengths +- Weaknesses to address +- Prioritized improvement recommendations + +Use @workspace to reference both files. +``` + +**Ví dụ áp dụng:** + +Kết hợp thông tin từ `README.md` (tech stack, features) với `docs/DESIGN_REVIEW.md` (detailed analysis, recommendations) để tạo executive summary cho stakeholders. + +--- + +### UC-04: Tạo sơ đồ (Create Diagrams) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `docs/DESIGN_REVIEW.md` (dòng 1-129) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-04](./COPILOT_CODE_MAPPING.md#uc-04-tạo-sơ-đồ-create-diagrams) | + +**Prompt tiếng Việt:** + +``` +Tạo sơ đồ Mermaid mô tả luồng dữ liệu từ khi người dùng click một file trong +FileTree cho đến khi nội dung hiển thị trong EditorTool, đi qua workspaceStore. + +Bao gồm các bước: +1. User click file trong FileTree.tsx +2. Gọi openFile() trong workspaceStore.ts +3. findFileNode() tìm file content +4. addTab() thêm tab mới vào pane +5. EditorTool.tsx render nội dung + +Sử dụng Mermaid sequence diagram. +``` + +**Prompt tiếng Anh:** + +``` +Create a Mermaid sequence diagram showing the data flow from when a user clicks +a file in FileTree to when content is displayed in EditorTool via workspaceStore. + +Include steps: +1. User clicks file in FileTree.tsx +2. openFile() called in workspaceStore.ts +3. findFileNode() locates file content +4. addTab() adds new tab to pane +5. EditorTool.tsx renders content + +Use Mermaid sequence diagram syntax. +``` + +**Ví dụ áp dụng:** + +Bổ sung vào `docs/DESIGN_REVIEW.md` hiện đang mô tả kiến trúc bằng text. Mermaid diagrams giúp visualize luồng dữ liệu phức tạp giữa components. + +--- + +### UC-05: Tạo bảng (Create Tables) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `src/components/tools/ToolRenderer.tsx` (dòng 17-44) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-05](./COPILOT_CODE_MAPPING.md#uc-05-tạo-bảng-create-tables) | + +**Prompt tiếng Việt:** + +``` +Tạo bảng so sánh tất cả 9 tools trong ToolRenderer.tsx, bao gồm các cột: +- Tên tool +- ToolType (enum value) +- Có state riêng không (local state vs store) +- Có kết nối workspaceStore không +- Số dòng code +- Độ phức tạp (Thấp/Trung bình/Cao) + +Dựa trên mã nguồn thực tế trong src/components/tools/. +``` + +**Prompt tiếng Anh:** + +``` +Create a comparison table for all 9 tools in ToolRenderer.tsx with columns: +- Tool name +- ToolType (enum value) +- Has own state (local state vs store) +- Connected to workspaceStore +- Lines of code +- Complexity (Low/Medium/High) + +Base the analysis on actual source code in src/components/tools/. +``` + +**Ví dụ áp dụng:** + +Bổ sung vào `README.md` dòng 136-147 — bảng tools hiện tại chỉ có tên và mô tả ngắn. Bảng chi tiết hơn giúp contributors hiểu nhanh cấu trúc tools. + +--- + +## 2. Gỡ lỗi mã + +### UC-06: Gỡ lỗi JSON không hợp lệ (Debug Invalid JSON) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `src/stores/workspaceStore.ts` (dòng 74-108) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-06](./COPILOT_CODE_MAPPING.md#uc-06-gỡ-lỗi-json-không-hợp-lệ-debug-invalid-json) | + +**Prompt tiếng Việt:** + +``` +Kiểm tra cấu trúc JSON trong sampleFiles (workspaceStore.ts dòng 74-108). +Xác minh tất cả FileNode objects có đầy đủ required fields theo interface FileNode +trong workspace.ts. + +Cụ thể kiểm tra: +- Mỗi FileNode có id, name, type đúng format +- Folders có children array (không phải undefined) +- Files có content string +- Không có circular references +- IDs là unique + +Liệt kê bất kỳ vi phạm nào tìm thấy. +``` + +**Prompt tiếng Anh:** + +``` +Validate the JSON structure in sampleFiles (workspaceStore.ts lines 74-108). +Verify all FileNode objects have required fields per the FileNode interface +in workspace.ts. + +Specifically check: +- Each FileNode has id, name, type in correct format +- Folders have children array (not undefined) +- Files have content string +- No circular references +- IDs are unique + +List any violations found. +``` + +**Ví dụ áp dụng:** + +`workspaceStore.ts` dòng 74-108 chứa hardcoded sample data. Khi thêm files mới vào sample data, dễ quên field hoặc sai type. Copilot có thể validate trước khi runtime. + +--- + +### UC-07: Xử lý giới hạn tỷ lệ truy cập API (Handle API Rate Limits) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `src/components/tools/AgentTool.tsx` (dòng 17-26) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-07](./COPILOT_CODE_MAPPING.md#uc-07-xử-lý-giới-hạn-tỷ-lệ-truy-cập-api-handle-api-rate-limits) | + +**Prompt tiếng Việt:** + +``` +AgentTool.tsx hiện tại trả về mock response (dòng 17-26). Viết logic xử lý +API call thật với: + +1. Exponential backoff: delay tăng gấp đôi sau mỗi retry (1s, 2s, 4s, 8s) +2. Retry tự động sau HTTP 429 status (max 3 retries) +3. Hiển thị trạng thái cho người dùng: loading, retrying (lần thứ n), error +4. Cancel request khi component unmount +5. Timeout sau 30 giây + +Giữ nguyên interface hiện tại (messages state, handleSend function). +Sử dụng AbortController cho cancellation. +``` + +**Prompt tiếng Anh:** + +``` +AgentTool.tsx currently returns mock responses (lines 17-26). Write real API +call logic with: + +1. Exponential backoff: delay doubles per retry (1s, 2s, 4s, 8s) +2. Auto-retry on HTTP 429 status (max 3 retries) +3. User-facing status: loading, retrying (attempt n), error +4. Cancel request on component unmount +5. 30-second timeout + +Keep existing interface (messages state, handleSend function). +Use AbortController for cancellation. +``` + +**Ví dụ áp dụng:** + +Khi kết nối AgentTool với API thật (OpenAI, Anthropic), rate limiting là vấn đề phổ biến. Template này giúp viết robust API client cho chat interface. + +--- + +### UC-08: Chẩn đoán lỗi kiểm tra (Diagnose Test Failures) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `src/stores/workspaceStore.ts` (dòng 483-499) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-08](./COPILOT_CODE_MAPPING.md#uc-08-chẩn-đoán-lỗi-kiểm-tra-diagnose-test-failures) | + +**Prompt tiếng Việt:** + +``` +Giả sử test cho hàm `duplicateFile` trong workspaceStore.ts thất bại khi +duplicate file ở root level (không có parentPath). Phân tích logic dòng 483-499 +và tìm nguyên nhân. + +Câu hỏi cần trả lời: +1. `parentPath` có giá trị gì khi file ở root? +2. `findFileNode(parentPath)` trả về gì khi path rỗng? +3. Điều kiện nào gây ra silent failure (không throw error)? +4. Đề xuất fix và test case bổ sung +``` + +**Prompt tiếng Anh:** + +``` +Assume the test for `duplicateFile` in workspaceStore.ts fails when duplicating +a file at root level (no parentPath). Analyze the logic at lines 483-499 +and find the root cause. + +Answer: +1. What is `parentPath` when the file is at root? +2. What does `findFileNode(parentPath)` return for an empty path? +3. What condition causes a silent failure (no thrown error)? +4. Suggest a fix and additional test cases +``` + +**Ví dụ áp dụng:** + +Hàm `duplicateFile` sử dụng `path.split('/').slice(0, -1).join('/')` để tìm parent. Khi file ở root, path có thể là `"filename"` → parentPath = `""` → `findFileNode("")` = `null` → silent fail. + +--- + +## 3. Phân tích chức năng + +### UC-09: Khám phá phương án triển khai (Explore Feature Implementations) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `src/components/layout/PaneView.tsx`, `package.json` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-09](./COPILOT_CODE_MAPPING.md#uc-09-khám-phá-phương-án-triển-khai-explore-feature-implementations) | + +**Prompt tiếng Việt:** + +``` +Đề xuất 3 phương án khác nhau để triển khai tính năng drag-and-drop tab reordering +trong PaneView.tsx, sử dụng @dnd-kit đã có trong package.json. + +Cho mỗi phương án, cung cấp: +- Mô tả kỹ thuật (2-3 câu) +- Ưu điểm +- Nhược điểm +- Độ phức tạp triển khai (giờ) +- Code skeleton minh họa + +So sánh: @dnd-kit/sortable vs HTML5 native drag vs custom pointer events. +Context: tabs hiện tại là danh sách ngang, mỗi tab có id và toolType. +``` + +**Prompt tiếng Anh:** + +``` +Propose 3 different approaches for implementing drag-and-drop tab reordering +in PaneView.tsx, using @dnd-kit already in package.json. + +For each approach, provide: +- Technical description (2-3 sentences) +- Pros +- Cons +- Implementation complexity (hours) +- Code skeleton + +Compare: @dnd-kit/sortable vs HTML5 native drag vs custom pointer events. +Context: tabs are a horizontal list, each with id and toolType. +``` + +**Ví dụ áp dụng:** + +`package.json` đã có `@dnd-kit/core` và `@dnd-kit/sortable`. PaneView hiện có tab bar nhưng chưa hỗ trợ reorder. Template giúp evaluate options trước khi implement. + +--- + +### UC-10: Phân tích phản hồi người dùng (Analyze User Feedback) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `docs/DESIGN_REVIEW.md` (dòng 1-129) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-10](./COPILOT_CODE_MAPPING.md#uc-10-phân-tích-phản-hồi-người-dùng-analyze-user-feedback) | + +**Prompt tiếng Việt:** + +``` +Dựa trên DESIGN_REVIEW.md, tổng hợp tất cả 'Recommendations' và tạo danh sách +ưu tiên theo impact/effort matrix. + +Format output: +| Recommendation | Impact (1-5) | Effort (1-5) | Priority Score | Sprint | +|---|---|---|---|---| + +- Impact: ảnh hưởng đến user experience +- Effort: thời gian dev cần (1=giờ, 5=tuần) +- Priority Score = Impact / Effort +- Sprint: gợi ý sprint nào nên thực hiện (Now/Next/Later) + +Sắp xếp theo Priority Score giảm dần. +``` + +**Prompt tiếng Anh:** + +``` +From DESIGN_REVIEW.md, compile all 'Recommendations' and create a prioritized +list using an impact/effort matrix. + +Output format: +| Recommendation | Impact (1-5) | Effort (1-5) | Priority Score | Sprint | +|---|---|---|---|---| + +- Impact: effect on user experience +- Effort: dev time needed (1=hours, 5=weeks) +- Priority Score = Impact / Effort +- Sprint: suggested sprint (Now/Next/Later) + +Sort by Priority Score descending. +``` + +**Ví dụ áp dụng:** + +`DESIGN_REVIEW.md` chứa nhiều recommendations: persistent state, undo/redo, plugin system, accessibility, performance. Template giúp biến qualitative feedback thành actionable backlog. + +--- + +## 4. Tái cấu trúc mã + +### UC-11: Cải thiện khả năng đọc hiểu mã (Improve Code Readability) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `src/stores/workspaceStore.ts` (dòng 153-252) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-11](./COPILOT_CODE_MAPPING.md#uc-11-cải-thiện-khả-năng-đọc-hiểu-mã-improve-code-readability) | + +**Prompt tiếng Việt:** + +``` +Cải thiện khả năng đọc hiểu của hàm `findPaneAndUpdate` và `splitInLayout` +trong workspaceStore.ts (dòng 153-252). Cụ thể: + +1. Thêm JSDoc cho mỗi hàm (mục đích, params, return, example) +2. Đổi tên biến rõ ràng hơn: + - `cb` → `updateCallback` hoặc `transformFn` + - `node` → `currentPane` hoặc `layoutNode` +3. Tách logic phức tạp thành helper functions có tên mô tả +4. Thêm early returns để giảm nesting +5. Giữ nguyên hành vi, chỉ cải thiện readability +``` + +**Prompt tiếng Anh:** + +``` +Improve readability of `findPaneAndUpdate` and `splitInLayout` functions +in workspaceStore.ts (lines 153-252). Specifically: + +1. Add JSDoc for each function (purpose, params, return, example) +2. Rename variables for clarity: + - `cb` → `updateCallback` or `transformFn` + - `node` → `currentPane` or `layoutNode` +3. Extract complex logic into descriptively named helper functions +4. Add early returns to reduce nesting +5. Preserve behavior, only improve readability +``` + +**Ví dụ áp dụng:** + +Ba hàm đệ quy trong workspaceStore.ts là core logic nhưng khó đọc. Tên biến generic (`cb`, `node`) không truyền đạt intent. JSDoc sẽ giúp contributors mới hiểu nhanh. + +--- + +### UC-12: Sửa lỗi lint (Fix Lint Errors) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `eslint.config.js`, `src/**/*.{ts,tsx}` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-12](./COPILOT_CODE_MAPPING.md#uc-12-sửa-lỗi-lint-fix-lint-errors) | + +**Prompt tiếng Việt:** + +``` +Chạy ESLint trên toàn bộ src/ với config trong eslint.config.js. +Liệt kê tất cả lỗi và cảnh báo, phân loại theo: + +1. Errors (phải sửa): + - Unused variables/imports + - Missing dependencies trong useEffect + - Type errors + +2. Warnings (nên sửa): + - Naming conventions + - Unused parameters + - Console.log statements + +Cho mỗi loại lỗi, đề xuất cách sửa cụ thể (auto-fix hoặc manual fix). +Chạy: `npm run lint` để lấy danh sách lỗi. +``` + +**Prompt tiếng Anh:** + +``` +Run ESLint on the entire src/ directory using the config in eslint.config.js. +List all errors and warnings, categorized as: + +1. Errors (must fix): + - Unused variables/imports + - Missing useEffect dependencies + - Type errors + +2. Warnings (should fix): + - Naming conventions + - Unused parameters + - Console.log statements + +For each error type, suggest a specific fix (auto-fix or manual). +Run: `npm run lint` to get the error list. +``` + +**Ví dụ áp dụng:** + +Config sử dụng `typescript-eslint`, `react-hooks`, `react-refresh` plugins. Chạy `npm run lint` sẽ reveal các vấn đề phổ biến trong React/TypeScript codebase. + +--- + +### UC-13: Tái cấu trúc hiệu năng (Refactor for Performance) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `src/components/search/SearchBar.tsx` (dòng 6-15, 47-94) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-13](./COPILOT_CODE_MAPPING.md#uc-13-tái-cấu-trúc-hiệu-năng-refactor-for-performance) | + +**Prompt tiếng Việt:** + +``` +Tối ưu SearchBar.tsx: flattenFiles() (dòng 6-15) được gọi mỗi lần render. +Đề xuất và implement cải thiện: + +1. Memoize flattenFiles() với useMemo, dependency là files array +2. Thêm debounce cho search input (300ms) dùng useCallback + setTimeout +3. Virtualize danh sách kết quả khi có nhiều files (react-window hoặc tương tự) +4. Tối ưu filter logic: dùng .includes() thay vì regex nếu không cần pattern matching + +Giữ nguyên UI hiện tại, chỉ cải thiện performance. +Ước lượng cải thiện re-render cho mỗi thay đổi. +``` + +**Prompt tiếng Anh:** + +``` +Optimize SearchBar.tsx: flattenFiles() (lines 6-15) runs on every render. +Suggest and implement improvements: + +1. Memoize flattenFiles() with useMemo, depending on files array +2. Add debounce for search input (300ms) using useCallback + setTimeout +3. Virtualize results list for large file counts (react-window or similar) +4. Optimize filter logic: use .includes() instead of regex if no pattern matching + +Keep current UI, only improve performance. +Estimate re-render improvement for each change. +``` + +**Ví dụ áp dụng:** + +`flattenFiles()` recursive traversal chạy O(n) trên mỗi keystroke. Với 1000+ files, mỗi ký tự gõ gây re-render chậm. Memoization + debounce giảm 90%+ unnecessary computation. + +--- + +### UC-14: Tái cấu trúc bền vững (Refactor for Sustainability) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `src/index.css` (1-1147 dòng) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-14](./COPILOT_CODE_MAPPING.md#uc-14-tái-cấu-trúc-bền-vững-refactor-for-sustainability) | + +**Prompt tiếng Việt:** + +``` +index.css có 1147 dòng. Đề xuất cách tách thành CSS modules hoặc Tailwind +components. Cụ thể: + +1. Phân tích file: nhóm styles theo component (layout, filetree, tools, search...) +2. Đề xuất cấu trúc tách file: + - src/styles/layout.css + - src/styles/filetree.css + - src/styles/tools.css + - ... +3. Xác định CSS không sử dụng (dead CSS) +4. Đề xuất cách giảm specificity conflicts +5. Migration plan: thứ tự tách, cách test không break UI + +Dự án dùng Tailwind CSS v4, nên tận dụng utility classes khi phù hợp. +``` + +**Prompt tiếng Anh:** + +``` +index.css has 1147 lines. Propose a strategy to split into CSS modules or +Tailwind components. Specifically: + +1. Analyze file: group styles by component (layout, filetree, tools, search...) +2. Propose file structure: + - src/styles/layout.css + - src/styles/filetree.css + - src/styles/tools.css + - ... +3. Identify unused CSS (dead CSS) +4. Propose how to reduce specificity conflicts +5. Migration plan: order of extraction, how to test without breaking UI + +Project uses Tailwind CSS v4, so leverage utility classes where appropriate. +``` + +**Ví dụ áp dụng:** + +`index.css` chứa styles cho mọi component trong 1 file. Khi team grow, merge conflicts trên file CSS sẽ tăng. Tách modules giúp parallel development. + +--- + +### UC-15: Tái cấu trúc mẫu thiết kế (Refactor to Design Pattern) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `src/components/tools/ToolRenderer.tsx` (dòng 17-44) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-15](./COPILOT_CODE_MAPPING.md#uc-15-tái-cấu-trúc-mẫu-thiết-kế-refactor-to-design-pattern) | + +**Prompt tiếng Việt:** + +``` +Refactor ToolRenderer.tsx từ switch-case (dòng 17-44) sang Registry Pattern. + +Yêu cầu: +1. Tạo toolRegistry: Map> +2. Hàm registerTool(type, component) để đăng ký tool mới +3. ToolRenderer chỉ cần: toolRegistry.get(type) || +4. Mỗi tool tự đăng ký vào registry (self-registration) +5. Type-safe: đảm bảo ToolType enum khớp với registry keys + +Lợi ích: thêm tool mới không cần sửa ToolRenderer, Open/Closed Principle. +Giữ nguyên 9 tools hiện tại: editor, preview, console, shell, secrets, +file-history, multiplayer, settings, agent. +``` + +**Prompt tiếng Anh:** + +``` +Refactor ToolRenderer.tsx from switch-case (lines 17-44) to Registry Pattern. + +Requirements: +1. Create toolRegistry: Map> +2. registerTool(type, component) function for new tool registration +3. ToolRenderer only needs: toolRegistry.get(type) || +4. Each tool self-registers into the registry +5. Type-safe: ensure ToolType enum matches registry keys + +Benefit: add new tools without modifying ToolRenderer, Open/Closed Principle. +Keep all 9 existing tools: editor, preview, console, shell, secrets, +file-history, multiplayer, settings, agent. +``` + +**Ví dụ áp dụng:** + +`ToolRenderer.tsx` hiện có switch-case cho 9 tools. Mỗi khi thêm tool mới, phải sửa file này — vi phạm Open/Closed Principle. Registry Pattern cho phép plugin-style tool registration. + +--- + +### UC-16: Tái cấu trúc lớp truy cập dữ liệu (Refactor Data Access Layers) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trình độ cao | +| **File liên quan** | `src/stores/workspaceStore.ts` (dòng 254-519) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-16](./COPILOT_CODE_MAPPING.md#uc-16-tái-cấu-trúc-lớp-truy-cập-dữ-liệu-refactor-data-access-layers) | + +**Prompt tiếng Việt:** + +``` +workspaceStore.ts chứa cả data access (findFileNode, updateFileNodes) và +business logic (openFile, duplicateFile). Tách thành: + +1. src/services/fileSystemService.ts: + - findFileNode(files, path): FileNode | null + - updateFileNodes(files, path, updater): FileNode[] + - createFileNode(name, type, content?): FileNode + - getFilePath(files, fileId): string + +2. src/services/workspaceActions.ts: + - openFile(state, path): StateUpdate + - createFile(state, parentPath, name): StateUpdate + - deleteFile(state, path): StateUpdate + - duplicateFile(state, path): StateUpdate + +3. workspaceStore.ts chỉ còn: state definition + action wiring + +Đảm bảo: +- Services là pure functions (dễ test) +- Store actions gọi services +- Types được export đúng cách +``` + +**Prompt tiếng Anh:** + +``` +workspaceStore.ts contains both data access (findFileNode, updateFileNodes) and +business logic (openFile, duplicateFile). Split into: + +1. src/services/fileSystemService.ts: + - findFileNode(files, path): FileNode | null + - updateFileNodes(files, path, updater): FileNode[] + - createFileNode(name, type, content?): FileNode + - getFilePath(files, fileId): string + +2. src/services/workspaceActions.ts: + - openFile(state, path): StateUpdate + - createFile(state, parentPath, name): StateUpdate + - deleteFile(state, path): StateUpdate + - duplicateFile(state, path): StateUpdate + +3. workspaceStore.ts retains: state definition + action wiring only + +Ensure: +- Services are pure functions (easy to test) +- Store actions call services +- Types are properly exported +``` + +**Ví dụ áp dụng:** + +Store hiện tại 519 dòng là monolith. Tách services giúp: unit test data access riêng, reuse logic giữa components, giảm cognitive load khi đọc store. + +--- + +### UC-17: Tách logic nghiệp vụ khỏi UI (Decouple Business Logic from UI) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trình độ cao | +| **File liên quan** | `src/components/filetree/FileTree.tsx` (dòng 75-187), `FileContextMenu.tsx` (dòng 36-54) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-17](./COPILOT_CODE_MAPPING.md#uc-17-tách-logic-nghiệp-vụ-khỏi-ui-decouple-business-logic-from-ui) | + +**Prompt tiếng Việt:** + +``` +FileTree.tsx (dòng 75-187) trộn lẫn UI và logic. Tách thành: + +1. Custom hook useFileTreeActions(): + - handleNewFile(parentPath: string): void + - handleCreateFile(name: string, type: 'file' | 'folder'): void + - handleContextMenu(e: MouseEvent, node: FileNode): void + - isCreating: boolean + - newFileName: string + - setNewFileName: (name: string) => void + +2. FileTree.tsx chỉ còn JSX rendering: + - Nhận actions từ hook + - Render tree nodes + - Delegate events cho hook + +3. Tương tự cho FileContextMenu.tsx: + - Tách handleRename (hiện dùng window.prompt()) vào hook + - Tách handleDownload (tạo Blob + download) vào utility + +Giữ nguyên UI hiện tại, chỉ di chuyển logic. +``` + +**Prompt tiếng Anh:** + +``` +FileTree.tsx (lines 75-187) mixes UI and logic. Decouple into: + +1. Custom hook useFileTreeActions(): + - handleNewFile(parentPath: string): void + - handleCreateFile(name: string, type: 'file' | 'folder'): void + - handleContextMenu(e: MouseEvent, node: FileNode): void + - isCreating: boolean + - newFileName: string + - setNewFileName: (name: string) => void + +2. FileTree.tsx becomes JSX-only: + - Receives actions from hook + - Renders tree nodes + - Delegates events to hook + +3. Same for FileContextMenu.tsx: + - Extract handleRename (currently uses window.prompt()) into hook + - Extract handleDownload (Blob creation + download) into utility + +Keep current UI, only move logic. +``` + +**Ví dụ áp dụng:** + +FileTree.tsx hiện là 188 dòng trộn state management, event handlers, và JSX. Custom hooks giúp: test logic riêng, reuse giữa mobile/desktop views, giảm component complexity. + +--- + +### UC-18: Giải quyết vấn đề xuyên suốt (Address Cross-Cutting Concerns) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `PaneOptionsMenu.tsx` (dòng 22-30), `FileContextMenu.tsx`, `SearchBar.tsx` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-18](./COPILOT_CODE_MAPPING.md#uc-18-giải-quyết-vấn-đề-xuyên-suốt-address-cross-cutting-concerns) | + +**Prompt tiếng Việt:** + +``` +Click-outside detection logic lặp lại ở PaneOptionsMenu.tsx (dòng 22-30), +FileContextMenu.tsx, và SearchBar.tsx. Tạo custom hook useClickOutside() +để tái sử dụng. + +Yêu cầu: +1. Hook signature: useClickOutside(ref: RefObject, onClickOutside: () => void) +2. Xử lý cả mousedown và touchstart events +3. Cleanup đúng cách khi unmount +4. Không trigger khi click vào element bên trong ref +5. Option để ignore specific elements (e.g., trigger button) + +Sau đó refactor cả 3 component để sử dụng hook mới. +Tạo file: src/hooks/useClickOutside.ts +``` + +**Prompt tiếng Anh:** + +``` +Click-outside detection logic is duplicated in PaneOptionsMenu.tsx (lines 22-30), +FileContextMenu.tsx, and SearchBar.tsx. Create a custom hook useClickOutside() +for reuse. + +Requirements: +1. Hook signature: useClickOutside(ref: RefObject, onClickOutside: () => void) +2. Handle both mousedown and touchstart events +3. Proper cleanup on unmount +4. Don't trigger when clicking inside the ref element +5. Option to ignore specific elements (e.g., trigger button) + +Then refactor all 3 components to use the new hook. +Create file: src/hooks/useClickOutside.ts +``` + +**Ví dụ áp dụng:** + +3 components có gần như cùng đoạn code: `useEffect` + `addEventListener('mousedown')` + check `ref.current.contains(e.target)`. Hook giúp DRY và consistent behavior. + +--- + +### UC-19: Đơn giản hóa kế thừa (Simplify Inheritance Hierarchies) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trung cấp | +| **File liên quan** | `src/types/workspace.ts` (dòng 24-45) | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-19](./COPILOT_CODE_MAPPING.md#uc-19-đơn-giản-hóa-kế-thừa-simplify-inheritance-hierarchies) | + +**Prompt tiếng Việt:** + +``` +Union type `Pane | PaneSplit` lặp lại ở workspace.ts, workspaceStore.ts, +WorkspaceLayout.tsx. Đơn giản hóa: + +1. Tạo type alias trong workspace.ts: + type LayoutNode = Pane | PaneSplit + +2. Tạo type guards: + function isPane(node: LayoutNode): node is Pane + function isPaneSplit(node: LayoutNode): node is PaneSplit + +3. Thay thế tất cả `Pane | PaneSplit` bằng `LayoutNode` + +4. Sử dụng type guards thay vì: + - 'children' in node + - (node as PaneSplit).children + - node.type === 'pane' + +5. Export từ workspace.ts, import ở các file khác + +Liệt kê tất cả vị trí cần thay đổi. +``` + +**Prompt tiếng Anh:** + +``` +The union type `Pane | PaneSplit` is repeated across workspace.ts, workspaceStore.ts, +and WorkspaceLayout.tsx. Simplify: + +1. Create type alias in workspace.ts: + type LayoutNode = Pane | PaneSplit + +2. Create type guards: + function isPane(node: LayoutNode): node is Pane + function isPaneSplit(node: LayoutNode): node is PaneSplit + +3. Replace all `Pane | PaneSplit` with `LayoutNode` + +4. Use type guards instead of: + - 'children' in node + - (node as PaneSplit).children + - node.type === 'pane' + +5. Export from workspace.ts, import in other files + +List all locations that need changes. +``` + +**Ví dụ áp dụng:** + +`Pane | PaneSplit` xuất hiện 10+ lần. Type guards giúp TypeScript narrowing tự động, giảm type assertions, và centralize type logic. + +--- + +### UC-20: Khắc phục tắc nghẽn DB (Fix Database Bottlenecks) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Trình độ cao | +| **File liên quan** | `src/stores/workspaceStore.ts` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-20](./COPILOT_CODE_MAPPING.md#uc-20-khắc-phục-tắc-nghẽn-db-fix-database-bottlenecks) | + +**Prompt tiếng Việt:** + +``` +workspaceStore.ts dùng in-memory state (Zustand). Nếu migrate sang +IndexedDB/localStorage cho persistent file storage, đề xuất: + +1. Storage strategy: + - IndexedDB cho file content (large data) + - localStorage cho workspace layout (small data) + - Zustand persist middleware cho auto-sync + +2. Tránh blocking UI thread: + - Web Worker cho IndexedDB read/write operations + - Async actions thay vì sync set() + - Optimistic updates: update UI trước, sync sau + +3. Migration plan: + - Phase 1: Zustand persist cho layout state + - Phase 2: IndexedDB cho file content + - Phase 3: Web Worker cho background operations + +4. Error handling: offline, storage full, concurrent access + +Cho code example cho Phase 1 (Zustand persist). +``` + +**Prompt tiếng Anh:** + +``` +workspaceStore.ts uses in-memory state (Zustand). For migrating to +IndexedDB/localStorage for persistent file storage, propose: + +1. Storage strategy: + - IndexedDB for file content (large data) + - localStorage for workspace layout (small data) + - Zustand persist middleware for auto-sync + +2. Avoid blocking UI thread: + - Web Worker for IndexedDB read/write operations + - Async actions instead of sync set() + - Optimistic updates: update UI first, sync later + +3. Migration plan: + - Phase 1: Zustand persist for layout state + - Phase 2: IndexedDB for file content + - Phase 3: Web Worker for background operations + +4. Error handling: offline, storage full, concurrent access + +Provide code example for Phase 1 (Zustand persist). +``` + +**Ví dụ áp dụng:** + +Hiện tại refresh browser = mất hết dữ liệu. Persistent storage là #1 recommendation trong DESIGN_REVIEW.md. Template hướng dẫn migrate không break UX. + +--- + +### UC-21: Dịch mã (Translate Code) + +| Thuộc tính | Chi tiết | +|---|---| +| **Mức độ** | Đơn giản | +| **File liên quan** | `src/components/tools/AgentTool.tsx` | +| **Xem ánh xạ** | [COPILOT_CODE_MAPPING.md → UC-21](./COPILOT_CODE_MAPPING.md#uc-21-dịch-mã-translate-code) | + +**Prompt tiếng Việt:** + +``` +Dịch component AgentTool.tsx từ React/TypeScript sang Vue 3 Composition API, +giữ nguyên chức năng chat interface. + +Yêu cầu: +1. Giữ nguyên: messages state, input handling, send logic, UI layout +2. Mapping React → Vue: + - useState → ref/reactive + - useRef → ref + template ref + - JSX → template syntax + - CSS classes giữ nguyên +3. Sử dụng