anhtnm1andClaude Opus 5
bbc09f628a
EPIC R01 (Team Duy) - safety net before the parallel refactor starts.
R01-T01 docs/architecture/ADR-001-layered-architecture.md
4-tier boundaries, allowed dependency directions, invariants I1-I6 and
the strangler-fig migration strategy.
R01-T02 tests/fakes/{fake_provider,fake_tool_executor}.py
Scripted, offline Provider and extra-tool executor doubles.
R01-T03 scripts/check_imports.py
AST-based Clean Architecture Guard (CASAN Check 3). Also covers relative
imports and function-local imports; ASCII-only output for cp932 consoles.
R01-T04 tests/characterization/test_run_cowork.py
13 snapshot tests pinning run_cowork's current observable contract before
EPIC R04 moves its orchestration into application/.
R01-T05 docs/architecture/dormant-code.md
Import-graph scan: 43 unimported modules verified down to 6 genuinely
dormant items (~1887 LOC); the rest run via subprocess/CLI entry points.
tests/conftest.py binds `cowork_local` to THIS checkout by absolute path -
previously sys.path discovery could import a sibling checkout and the suite
would silently test the wrong code.
Suite: 104 passed, 1.08s (2 pre-existing failures in test_config_security.py
remain - config.py still ships a hardcoded default password, EPIC R02/Team Nam).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
86 lines
5.9 KiB
Markdown
86 lines
5.9 KiB
Markdown
# Dormant / Dead Code Inventory (R01-T05)
|
|
|
|
* **Task**: R01-T05 — Phân loại và cô lập mã nguồn cũ
|
|
* **Owner**: 🔵 Team Duy
|
|
* **Ngày quét**: 2026-08-21
|
|
* **Phạm vi quét**: toàn bộ `*.py` production (loại trừ `tests/`, `assets/`, `docs/`, `.git/`)
|
|
|
|
---
|
|
|
|
## 1. Mục đích
|
|
|
|
Trước khi 3 team refactor song song, cần biết **file nào thật sự đang chạy**. Refactor
|
|
một module đã chết là lãng phí; xoá nhầm một module chỉ được gọi động là gây sự cố
|
|
runtime. Tài liệu này phân loại từng ứng viên, kèm **bằng chứng** và **hành động đề xuất**.
|
|
|
|
## 2. Phương pháp
|
|
|
|
Quét AST toàn repo, dựng đồ thị import, tìm module **không có module nào khác import**.
|
|
Kết quả thô: **43 module**. Sau đó xác minh thủ công từng ứng viên, vì phân tích tĩnh
|
|
không thấy 3 kiểu tham chiếu:
|
|
|
|
| Kiểu tham chiếu ẩn | Ví dụ thật trong repo |
|
|
| :--- | :--- |
|
|
| Chạy như subprocess | `state.py:285` gọi `python -m cowork_local.mcp_servers.ms365_server` |
|
|
| Entry point của gói | `__main__.py` (chạy bằng `python -m cowork_local`) |
|
|
| Script chạy tay | `tools/check_*.py`, `scripts/*.py` |
|
|
|
|
> ⚠️ **Kết luận quan trọng**: 43 module "không ai import" **KHÔNG** đồng nghĩa 43 module chết.
|
|
> Sau xác minh, chỉ còn **6 hạng mục (~1.887 dòng)** là dormant thật.
|
|
|
|
## 3. Phân loại kết quả
|
|
|
|
### 🟥 A. DORMANT THẬT — không có đường nào chạy tới (ứng viên xoá)
|
|
|
|
| Module | LOC | Bằng chứng | Rủi ro khi xoá | Hành động |
|
|
| :--- | ---: | :--- | :--- | :--- |
|
|
| `ui/accounts_tab.py` | 700 | Chỉ xuất hiện trong comment của `i18n.py:92`; không widget nào khởi tạo `AccountsTab` | Thấp — panel Monitoring → Accounts hiện không có đường vào | Cô lập, chờ xác nhận PO rồi xoá |
|
|
| `ui/flow_dialog.py` | 596 | Chỉ được nhắc trong docstring `ui/agent_manager_tab.py:4` và comment `i18n.py:2124` | Trung bình — Flow Manager có thể là tính năng tạm ẩn | **Hỏi PO trước**, chưa xoá |
|
|
| `security/` (cả package) | 296 | `prompt_validator`, `action_validator`, `attachment_validator`, `audit_logger`, `command_risk_classifier` — không file nào ngoài package tự import. Chức năng **trùng** `core/agent_security.py` + `core/security_rules.py` (đang chạy thật) | Trung bình — dễ nhầm đây là lớp bảo mật đang hoạt động | ⚠️ Ưu tiên cao: xoá hoặc hợp nhất trong **R09 (Team Nam)** |
|
|
| `core/codebase_memory_ui.py` | 123 | Không nơi nào import; `core/codebase_memory.py` (bản không-UI) mới là bản đang dùng | Thấp | Xoá |
|
|
| `core/graph_server.py` | 115 | Docstring nói phục vụ build không có QtWebEngine, nhưng **không có call site nào**; `ui/structure_graph_view.py` không gọi | Trung bình — có thể là fallback cho bản .exe chưa nối dây | Xác minh với bản đóng gói PyInstaller trước khi xoá |
|
|
| `ui/mcp_servers_dialog.py` | 57 | Không import; MCP settings hiện nằm trong `ui/settings_dialog.py` | Thấp | Xoá |
|
|
|
|
**Tổng: ~1.887 dòng (≈ 3,4% codebase).**
|
|
|
|
### 🟨 B. KHÔNG CHẾT — chạy qua đường ẩn (giữ nguyên)
|
|
|
|
| Module | Vì sao phân tích tĩnh báo nhầm |
|
|
| :--- | :--- |
|
|
| `__main__.py` | Entry point `python -m cowork_local` |
|
|
| `mcp_servers/ms365_server.py` | Chạy như tiến trình con — `state.py:285` |
|
|
| `core/routing/__init__.py` | Được import qua đường dẫn con (`from .routing.service import RoutingService`), heuristic theo tên lá không thấy |
|
|
| `tools/check_*.py` (34 file, 6.608 dòng) | Bộ smoke-test UI chạy tay: `python tools/check_nav.py`. Là **dev tooling**, không phải code chết |
|
|
| `scripts/bootstrap_gitea_repo.py`, `scripts/check_imports.py` | Script CLI chạy tay / chạy trong CI |
|
|
|
|
### 🟩 C. CODE SỐNG NHƯNG "ĐÓNG BĂNG" — đụng vào phải cẩn thận
|
|
|
|
| Module | LOC | Ghi chú cho người refactor |
|
|
| :--- | ---: | :--- |
|
|
| `core/chat_agent.py::run_cowork` | 580 | Đang có **characterization test** (`tests/characterization/test_run_cowork.py`, R01-T04). Mọi thay đổi hành vi phải làm cùng lúc với cập nhật snapshot |
|
|
| `providers/base.py` | 401 | Là contract chung của mọi provider; đổi chữ ký = vỡ cả 3 team. Đã có contract test (R03-T01) |
|
|
| `core/routing/*` | 2.263 | Đã có 79 test đang xanh. R03 **bọc** chứ không viết lại: `application/model_routing/` gọi xuống đây |
|
|
|
|
## 4. Quy tắc xử lý (bắt buộc)
|
|
|
|
1. **Không xoá trong cùng PR với refactor.** Xoá code chết là một commit riêng, để `git revert` được độc lập khi có sự cố.
|
|
2. **Cô lập trước, xoá sau.** Đánh dấu module bằng docstring cảnh báo, chạy 1 vòng release; không ai báo lỗi mới xoá.
|
|
3. **Hạng mục 🟥 A cần một người xác nhận** (PO hoặc chủ tính năng) trước khi xoá — trừ khi rõ ràng là bản trùng lặp (`codebase_memory_ui`, `mcp_servers_dialog`).
|
|
4. **Không refactor code trong nhóm 🟥 A.** Nếu một file trong danh sách này >400 dòng, nó **không** tính vào CASAN Check 2 — vì đường đi đúng là xoá, không phải tách nhỏ.
|
|
|
|
## 5. Việc cần bàn giao
|
|
|
|
| Hạng mục | Team nhận | EPIC |
|
|
| :--- | :--- | :--- |
|
|
| `security/` trùng lặp với `core/agent_security.py` | 🟣 Nam | R09 |
|
|
| `ui/accounts_tab.py`, `ui/flow_dialog.py`, `ui/mcp_servers_dialog.py` | 🟣 Nam (sở hữu `presentation/shell/`, `settings/`) | R08 |
|
|
| `core/graph_server.py`, `core/codebase_memory_ui.py` | 🟢 Hoa (sở hữu `presentation/graph/`) | R06 |
|
|
|
|
## 6. Cách chạy lại lần quét này
|
|
|
|
```bash
|
|
python scripts/check_imports.py # ranh giới kiến trúc (R01-T03)
|
|
# Bản quét đồ thị import dùng cho tài liệu này sẽ được đóng gói thành
|
|
# scripts/find_dormant.py trong R10-T02 (Testing & Governance tooling).
|
|
```
|