diff --git a/docs/refactor/GammaTeam_TaskSplit.html b/docs/refactor/GammaTeam_TaskSplit.html new file mode 100644 index 0000000..628b674 --- /dev/null +++ b/docs/refactor/GammaTeam_TaskSplit.html @@ -0,0 +1,612 @@ + + + + + +Phân Việc Refactor Team Gamma + + + + +
+ +
+

Team Gamma · Automation, Workflows & Governance

+

Một mục chung, rồi ba nhánh tính năng

+

+ Toàn bộ phần việc refactor 10 ngày của Team Gamma. Nhóm trưởng làm thêm một mục chung — + khung kiến trúc, hợp đồng dữ liệu, cổng kiểm duyệt — nằm ngoài ba nhánh; xong mục đó thì + ba người vào ba nhánh tính năng ngang nhau, không ai phải sửa chung file với ai. +

+

+ Ba tài liệu refactor gọi team này là “Team Nam” (theo tên lead). Cùng một team, cùng + phạm vi R02 · R08 · R09 · R07-T06. Tên nhánh giữ tiền tố nam/ đã thống nhất với + Team Duy và Team Hoa — đổi sang gamma/ sẽ lệch quy ước chung. +

+
+
Thời hạn21/08 → 31/08
+
Người3
+
Nhánh1 chung + 3 tính năng
+
Code phải bóc~6.500 dòng
+
Cổng phải quaCASAN Check 1
+
+
+ + +
+
+

Tóm tắt · thứ tự làm

+
    +
  • + CHUNG + Nhóm trưởng làm trước, nửa ngày + Dựng khung 5 thư mục (đang là 0 file) · interface + fake cho Config/Secrets · + chốt api_key và báo Team Duy · script CASAN Check 1 · đưa 3 check vào CI · + quyết số phận 24 checker UI. Merge xong mới chia nhánh. +
    • +
  • + N1 + Cấu hình · Bí mật · Vỏ ứng dụng — nhóm trưởng + R02 (6 task) · settings 4 widget · bootstrap + MainWindow · policy doc. + Giữ luôn app.py, config.py, theme.py, + i18n.py. ~2.700 dòng. +
    • +
  • + N2 + Giám sát — thành viên 1 + 7 tab Monitoring · CanonicalAuditLogger · MonitoringQueryService · + 2 vòng lặp import · ma trận Sandbox. ~2.650 dòng. +
    • +
  • + N3 + Co4E Studio — thành viên 2 + Co4EWorkflowService · tách co4e_tab.py + co4e_canvas.py + thành 5 phần. ~2.880 dòng, file to nhất team. +
    • +
+
+
+

Ba điều bắt buộc

+
    +
  1. Không chạm file dùng chung. Cần thêm chuỗi hay màu thì nhắn nhóm trưởng, đừng tự sửa.
    2. +
  2. Nộp factory, không tự lắp vào app.py. N1 lắp trong bootstrap.py ngày 28/08.
    3. +
  3. Bị chặn thì dùng fake, báo ngay trong ngày. Không ngồi đợi ai.
    4. +
+

Nghiệm thu

+

+ git diff --name-only giữa ba nhánh — giao của ba tập phải rỗng. + Còn giao nhau là quy ước 1 đang bị vi phạm. +

+
+
+ +
+

Mục chung — nhóm trưởng làm, xong mới chia nhánh

+

+ Sáu việc dưới đây không thuộc nhánh tính năng nào — chúng là thứ cả ba người cùng đụng + vào. Nhóm trưởng làm một lần trên nhánh nam/workflow-governance-base, merge + thẳng, rồi ba người mới tách nhánh riêng. Ước tính nửa ngày. +

+
    +
  1. + ~30 phút + Dựng khung thư mục + + domain/ application/ infrastructure/ + presentation/ platform/ tests/fakes/ — + hiện tại chưa tồn tại, 0 file. Mọi task của cả ba người đều ghi vào đây; để ba + người tự tạo là đụng nhau ở __init__.py ngay ngày đầu. + +
    2. +
  2. + ~45 phút + Viết interface + fake cho Config và Secrets + + SecretStore, ConfigRepository, kèm + FakeSecretStore và FakeConfigRepository. Chỉ chữ ký, chưa cần + thân hàm. Đây là thứ gỡ chốt cho cả hai người kia — 156 lời gọi + ctx.config.* trong 29 file đang chờ nó. + +
    3. +
  3. + ~20 phút + Chốt số phận api_key và báo Team Duy + + provider_conf() còn trả api_key bên trong, hay tách hẳn sang + SecretStore? Có 5 nơi đọc trực tiếp, 3 trong số đó nằm trong + providers/ của Team Duy. Quyết một mình rồi im lặng là làm vỡ code + team bạn. + +
    4. +
  4. + ~30 phút + Viết scripts/audit_security.py (CASAN Check 1) + + Gamma chủ trì check này ngày 30/08. Viết ngay hôm nay thì lead tự kiểm được trong suốt + quá trình chuyển API key, thay vì tới ngày cổng mới chạy lần đầu và phát hiện vấn đề. + +
    5. +
  5. + ~20 phút + Thêm 3 check CASAN vào CI + + CI hiện chỉ chạy pytest tests -q. Ba check (secret · ≤400 dòng · import + guard) không nằm trong CI, nên tới 30/08 mới biết ai vi phạm. Đưa vào CI thì mỗi PR tự + báo. + +
    6. +
  6. + ~30 phút + Quyết số phận 24 checker UI, rồi thông báo + + Chúng bám vào cowork_local.config (34 chỗ) và cowork_local.app + (16 chỗ) — sẽ chết ngay khi lead đụng config.py. Đây là lưới an toàn + duy nhất cho phần UI vừa làm xong. Xem mục quy ước bên dưới. + +
    7. +
+
+ +

Ba nhánh tính năng

+

+ Ba nhánh ngang nhau, mỗi nhánh khoảng 2.700 dòng phải bóc tách. Nhóm trưởng nhận nhánh N1 + vì đó là nhánh chạm tới file dùng chung nhiều nhất. Cột “sở hữu” là danh sách file + chỉ người đó được sửa. +

+ +
+ +
+
Nhánh N1 · Nhóm trưởng
+

Cấu hình, Bí mật & Vỏ ứng dụng

+

Nhánh chạm nhiều file dùng chung nhất — để nhóm trưởng giữ

+
nam/workflow-governance-config
+ +

Việc

+
    +
  • R02-T01…T06 AtomicJsonFile · ConfigRepository · Typed Settings Facade · SecretStore + Keyring · chuyển API key · schema versioning
    • +
  • R08-T07 tách settings_dialog.py → 4 section widget
    • +
  • R08-T10 bootstrap.py + tách MainWindow → shell · tray · lifecycle (cuối sprint, lắp factory của hai người kia)
    • +
  • R09-T01 tài liệu Security Policy Model
    • +
  • Chủ trì CASAN Check 1 · giữ CI · duyệt PR của hai người
    • +
+ +

Sở hữu độc quyền

+
    +
  • config.py
    • +
  • app.py → presentation/shell/
    • +
  • bootstrap.py
    • +
  • theme.py · i18n.py
    • +
  • infrastructure/config/ · secrets/ · persistence/
    • +
  • ui/settings_dialog.py → presentation/settings/
    • +
  • scripts/ · .gitea/workflows/
    • +
+ +

~2.700 dòng · 727 settings + 1.352 app + 616 config
+ mục chung ở trên

+
+ +
+
Nhánh N2 · Thành viên 1
+

Giám sát & Quan trắc

+

Hợp với người chịu được việc lặp, tách 7 tab có kỷ luật

+
nam/workflow-governance-monitoring
+ +

Việc

+
    +
  • R08-T08 tách monitoring_tab.py → 7 tab độc lập
    • +
  • R09-T04 CanonicalAuditLogger
    • +
  • R09-T05 MonitoringQueryService read-only, phân trang
    • +
  • R09-T02 gỡ vòng lặp model_pricing ↔ usage_tracker
    • +
  • R09-T03 gỡ vòng lặp agent_security ↔ alert
    • +
  • R09-T06 ma trận Sandbox theo hệ điều hành
    • +
+ +

Sở hữu độc quyền

+
    +
  • ui/monitoring_tab.py → presentation/monitoring/
    • +
  • application/monitoring/
    • +
  • infrastructure/telemetry/ · sandbox/
    • +
  • core/audit_log.py
    • +
  • core/model_pricing.py · usage_tracker.py
    • +
  • core/agent_security*.py
    • +
+ +

~2.650 dòng · 1.545 monitoring + ~1.100 core

+
+ +
+
Nhánh N3 · Thành viên 2
+

Co4E Studio

+

Hợp với người nắm canvas và luồng chạy workflow

+
nam/workflow-governance-co4e
+ +

Việc

+
    +
  • R07-T06 Co4EWorkflowService thuần Python
    • +
  • R08-T09 tách co4e_tab.py + co4e_canvas.py → canvas · node property · run control · chat view · agent list
    • +
  • Gọi tool qua ToolPolicyGateway của Team Hoa — dùng fake, không chờ
    • +
+ +

Sở hữu độc quyền

+
    +
  • ui/co4e_tab.py → presentation/co4e/
    • +
  • ui/co4e_canvas.py
    • +
  • ui/co4e_config_panel.py
    • +
  • application/workflows/
    • +
  • domain/workflows/
    • +
  • core/co4e_run_manager.py
    • +
+ +

~2.880 dòng · file to nhất của cả team

+
+ +
+ +

Quy ước cho hai nhánh N2 và N3

+

+ Bảy điều dưới đây là luật của team, nhóm trưởng chốt và duyệt PR theo đó. Ba điều đầu là + bắt buộc — vi phạm thì PR bị trả về. +

+ +
+ +
+

1 · Không chạm file dùng chung

+

+ app.py, theme.py, i18n.py, config.py, + bootstrap.py thuộc nhánh N1. Cần thêm chuỗi hay token màu thì + nhắn, đừng sửa — lead thêm trong ngày. Đây là ba file duy nhất có thể gây conflict + thật, và luật này xoá hẳn khả năng đó. +

+
+ +
+

2 · Nộp factory, không tự lắp vào app

+

+ Mỗi nhánh expose một hàm dựng widget với chữ ký chốt từ ngày đầu, ví dụ + build_monitoring_tab(ctx, query_service) -> QWidget. Nhánh N1 gọi nó + trong bootstrap.py ngày 28/08. Không ai tự sửa chỗ khởi tạo trong + app.py. +

+
+ +
+

3 · Bị chặn thì dùng fake, không ngồi đợi

+

+ Chưa có ConfigRepository bản thật thì dùng FakeConfigRepository. + Chưa có ToolPolicyGateway của Team Hoa thì fake. Báo ngay trong ngày + nếu thiếu fake nào — đó là việc của nhóm trưởng, không phải lý do dừng tay. +

+
+ +
+

4 · PR nhỏ, mỗi ngày một lần

+

+ Một PR cho một sub-widget hoặc một service, không dồn 7 tab vào một PR cuối tuần. Nhóm + trưởng duyệt trong ngày. PR càng to thì rủi ro càng dồn về ngày 28/08. +

+
+ +
+

5 · Mỗi PR kèm test, và không làm đỏ 90 test cũ

+

+ Baseline hiện tại: 90 test xanh trong 4,3 giây. Chạy pytest tests -q + trước khi mở PR. Đây là lưới an toàn cho phần logic — giữ nó xanh suốt 10 ngày. +

+
+ +
+

6 · File mới ≤ 400 dòng, không import PySide6 vào lõi

+

+ Hai điều kiện của CASAN Check 2 và 3. Tự kiểm trước khi mở PR — CI sẽ báo, nhưng biết + sớm thì đỡ phải tách lại lần hai. +

+
+ +
+

7 · Checker UI thuộc phạm vi ai, người đó cập nhật

+

+ 24 checker sẽ vỡ khi file bị dời. Ai dời file thì sửa checker tương ứng ngay trong PR đó + — tốn thêm khoảng 15% thời gian, đổi lại giữ được lưới an toàn cho phần UI vừa làm xong. + Nhóm trưởng quyết định phương án này và chịu trách nhiệm nếu đổi ý. +

+
+ +
+ +

Lịch từng ngày

+

Ba hàng chạy độc lập. Hàng tô nền là lúc cả ba phải gặp nhau.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NgàyN1 · Cấu hình & VỏN2 · Giám sátN3 · Co4E
21/08
T6		Mục chung · dựng khung · interface + fake · chốt api_key · CASAN scriptMerge trước khi hai người kia bắt đầuChốt schema log 9 trườngGiữ nguyên định dạng cũ để 24 chỗ gọi không phải sửaChốt chữ ký Co4EWorkflowServiceNộp cho lead để lắp bootstrap sau
22–23/08
T7–CN		AtomicJsonFile · ConfigRepository · Typed Settings FacadeCanonicalAuditLogger · gỡ vòng lặp pricing ↔ usageCo4EWorkflowService — CRUD & validate, test không cần Qt
23/08
17:00		Checkpoint 1   100% DTO và fake xong · pytest xanh · không ai bị chặn
24/08
T2		Tách settings: provider + connector widget3 tab đầu: overview · sandbox · security eventsnode_property_panel · agent_list_panel
25/08
T3		Tách settings: routing + general widget4 tab còn lại: MCP · action logs · agent status · security settingsco4e_canvas_widget — thao tác node
26/08
T4		Chuyển API key sang SecretStoreBáo Team Duy trước khi đụng providers/Lắp shell MonitoringTab · query service bản thậtRun control · chat view
27/08
T5		Schema versioning · recovery policyMa trận Sandbox · gỡ vòng lặp agent_securityLắp container Co4ETab · thay fake bằng service thật
28/08
T6		bootstrap.py + tách MainWindowNhận factory của N2 và N3 để lắpNộp factory · dọn file >400 dòng · cập nhật checkerNộp factory · dọn file >400 dòng · cập nhật checker
28/08
17:00		Checkpoint 2   Tách xong 100% god file · 0 circular import
29/08
T7		Tài liệu Security Policy · integration test SettingsIntegration test MonitoringIntegration test luồng Co4E đầu-cuối
30/08
CN 17:00		CASAN Gate   Nhóm trưởng chủ trì Check 1 — quét toàn bộ config/JSON, phải ra 0 secret plaintext. N2 và N3 sửa ngay phần của mình nếu script bắt được.
31/08
T2 15:00		Bàn giao   Fix tồn đọng · cập nhật tài liệu kiến trúc · merge PR cuối · smoke test 5 luồng chính
+
+ +

Nghiệm thu: làm sao biết đã thật sự song song

+

Không phải “đã họp xong” mà là chạy được. Ba câu hỏi, trả lời bằng lệnh.

+ +
+ + + + + + + + + + + + + + + + + + + + + +
Câu hỏiCách trả lờiKhi nào
N2 có chạy được khi chưa có config bản thật?Dựng một tab Monitoring, chạy test của nó, không import cowork_local.config dòng nào — chỉ dùng FakeConfigRepository21/08
N3 có chạy được khi Team Hoa chưa xong gateway?Test Co4EWorkflowService xanh với FakeToolPolicyGateway23/08
Ba nhánh có đụng file nhau không?git diff --name-only giữa ba nhánh — giao của ba tập phải rỗngmỗi ngày
+
+ + + +
+ + +