From 2627e691ce937e5f6d3187f1d9301bca97e50f9e Mon Sep 17 00:00:00 2001 From: Nam Pham Dinh Thanh Date: Fri, 21 Aug 2026 22:24:03 +0900 Subject: [PATCH] =?UTF-8?q?docs(refactor):=20c=E1=BA=A3=20ba=20=C4=91?= =?UTF-8?q?=E1=BA=A9y=20chung=20gamma/refactor;=20=C4=91=E1=BA=B7t=20t?= =?UTF-8?q?=C3=AAn=20Nam,=20Hi=E1=BB=87p,=20L=C3=A2m?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Đổi mô hình: không còn nhánh riêng mỗi người, cả ba cùng đẩy vào gamma/refactor. Ba "nhánh" thành ba "làn" — vẫn chia việc như cũ, nhưng ranh giới file bây giờ là thứ DUY NHẤT giữ ba người không giẫm chân, vì không còn nhánh riêng làm vùng đệm. Thêm quy ước số 4 cho nhánh chung, xếp vào nhóm bắt buộc: pull --rebase trước mỗi lần đẩy; commit nhỏ, đẩy trong ngày; không bao giờ đẩy thứ làm pytest tests -q đỏ, vì nhánh hỏng là hai người kia đứng hình. Phần nghiệm thu đổi theo: trước đây so file giữa ba nhánh, giờ không còn ba nhánh để so. Thay bằng git log --name-only --pretty=%an trên gamma/refactor — không file nào được xuất hiện dưới hai tên khác nhau. Hai quyết định đã chốt, ghi vào GammaTeam_decisions.md: 1. api_key: đường A — ConfigRepository ghép key từ SecretStore vào dict, 5 nơi đọc không đổi dòng nào, không cần báo Duy và Hoa. 2. 24 checker UI: đường A — ai dời file thì sửa checker ngay trong commit đó, kèm ràng buộc phải nói rõ sửa gì và chạy check_probes_bite.py sau. Không đưa vào CI sprint này vì chúng dựng MainWindow thật. Baseline trong tài liệu cập nhật 90 -> 102 test. Co-Authored-By: Claude Opus 5 (1M context) --- docs/refactor/GammaTeam_TaskSplit.html | 151 ++++++++++++++----------- docs/refactor/GammaTeam_decisions.md | 36 +++++- 2 files changed, 113 insertions(+), 74 deletions(-) diff --git a/docs/refactor/GammaTeam_TaskSplit.html b/docs/refactor/GammaTeam_TaskSplit.html index 513eb87..0c5b484 100644 --- a/docs/refactor/GammaTeam_TaskSplit.html +++ b/docs/refactor/GammaTeam_TaskSplit.html @@ -216,21 +216,21 @@

Team Gamma · Automation, Workflows & Governance

-

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

+

Một nhánh chung, ba làn không đụng nhau

- 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 — + Toàn bộ phần việc refactor 10 ngày của Team Gamma — Nam, Hiệp, Lâm. Cả ba đẩy chung vào gamma/refactor. Nam 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. + phạm vi R02 · R08 · R09 · R07-T06. Nhánh của team dùng tiền tố gamma/; ba tài liệu refactor viết + nam/workflow-governance-* theo tên lead — cùng một thứ.

Thời hạn21/08 → 31/08
-
Người3
-
Nhánh1 chung + 3 tính năng
+
NgườiNam · Hiệp · Lâm
+
Nhánhgamma/refactor
Code phải bóc~6.500 dòng
Cổng phải quaCASAN Check 1
@@ -243,27 +243,27 @@
  • CHUNG - Nhóm trưởng làm trước, nửa ngày + Nam 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 + N1 — Nam · Cấu hình, Bí mật, Vỏ ứng dụ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 + N2 — Hiệp · Giám sát 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 + N3 — Lâm · Co4E Studio Co4EWorkflowService · tách co4e_tab.py + co4e_canvas.py thành 5 phần. ~2.880 dòng, file to nhất team.
    • @@ -278,18 +278,18 @@

    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. + Trên gamma/refactor: không file nào được sửa bởi hai người khác nhau. + Có là quy ước số 1 đang bị vi phạm.

    -

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

    +

    Mục chung — Nam làm, xong hai người kia mới bắt đầu

    - 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. + Sáu việc dưới đây không thuộc làn nào — chúng là thứ cả ba người cùng đụng + vào. Nam làm một lần và đẩy lên gamma/refactor, rồi hai người kia + mới bắt đầu. Ước tính nửa ngày.

    1. @@ -351,20 +351,21 @@
    -

    Ba nhánh tính năng

    +

    Ba làn

    - 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. + Ba làn ngang nhau, mỗi làn khoảng 2.700 dòng phải bóc tách, cùng đẩy vào một + nhánh gamma/refactor. Nam nhận làn N1 vì đó là làn 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 — trên nhánh chung, đây là thứ duy nhất giữ cho ba người không giẫm chân.

    -
    Nhánh N1 · Nhóm trưởng
    +
    Làn N1 · Nam

    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
    +

    Nam giữ — làn chạm nhiều file dùng chung nhất

    +
    gamma/refactor

    Việc

      @@ -390,10 +391,10 @@
    -
    Nhánh N2 · Thành viên 1
    +
    Làn N2 · Hiệp

    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
    +

    Hiệp — 7 tab, việc lặp cần kỷ luật

    +
    gamma/refactor

    Việc

      @@ -419,10 +420,10 @@
    -
    Nhánh N3 · Thành viên 2
    +
    Làn N3 · Lâm

    Co4E Studio

    -

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

    -
    nam/workflow-governance-co4e
    +

    Lâm — canvas và luồng chạy workflow

    +
    gamma/refactor

    Việc

      @@ -446,10 +447,10 @@
    -

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

    +

    Tám quy ước

    - 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ề. + Tám điều dưới đây là luật của team, Nam chốt. Bốn điều đầu là bắt buộc — trên một + nhánh chung, vi phạm không chỉ hại mình mà chặn cả hai người kia.

    @@ -458,8 +459,8 @@

    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 + bootstrap.py thuộc nhánh N1 của Nam. Cần thêm chuỗi hay token màu thì + nhắn, đừng sửa — Nam 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 đó.

    @@ -468,8 +469,7 @@

    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 + build_monitoring_tab(ctx, query_service) -> QWidget. Nam gọi nó trong bootstrap.py ngày 28/08. Không ai tự sửa chỗ khởi tạo trong app.py.

    @@ -478,13 +478,26 @@

    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 + Chưa có ToolPolicyGateway của Team Hoa thì đã có fake sẵn. 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 · Nhánh chung: kéo trước khi đẩy, đừng để nhánh đỏ

    +

    + Cả ba đẩy vào gamma/refactor, nên không còn nhánh riêng làm vùng + đệm. Ba việc bắt buộc: git pull --rebase trước mỗi lần đẩy; + commit nhỏ và đẩy trong ngày, đừng ôm 500 dòng ba hôm; và + không bao giờ đẩy thứ làm pytest tests -q đỏ — nhánh hỏng + là hai người kia đứng hình. Lỡ đẩy nhầm thì sửa ngay hoặc + git revert, đừng để qua đêm. +

    +
    +
    -

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

    +

    5 · Commit 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. @@ -492,27 +505,28 @@

    -

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

    +

    6 · Mỗi commit 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. + Baseline hiện tại: 102 test xanh trong 3,4 giây. Chạy pytest tests -q + trước mỗi lần đẩy. Đâ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

    +

    7 · 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 + Hai điều kiện của CASAN Check 2 và 3. Tự kiểm trước khi đẩy — 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

    +

    8 · 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 ý. + 24 checker sẽ vỡ khi file bị dời. Ai dời file thì sửa checker tương ứng ngay trong + commit đó — 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. + Đã chốt 21/08: đường A. Nam chịu trách nhiệm nếu đổi ý.

    @@ -529,7 +543,7 @@
    -
    N1 · Cấu hình, Bí mật & Vỏnhóm trưởng
    +
    N1 · Cấu hình, Bí mật & VỏNam · nhóm trưởng

    Input — cần có

    @@ -538,14 +552,14 @@
  • mã cũui/settings_dialog.py 727 dòng
  • mã cũapp.py 1.352 dòng
  • tự chốtQuyết định api_key — trước 26/08
    • -
  • từ N2Chữ ký build_monitoring_tab() — trước 28/08
    • -
  • từ N3Chữ ký build_co4e_tab() — trước 28/08
    • +
  • từ HiệpChữ ký build_monitoring_tab() — trước 28/08
    • +
  • từ LâmChữ ký build_co4e_tab() — trước 28/08

Output — phải giao

    -
  • có rồiSecretStore · ConfigRepository + fake → cho N2 và N3
    • +
  • có rồiSecretStore · ConfigRepository + fake → cho Hiệp và Lâm
  • có rồiscripts/audit_security.py → cho CI
  • infrastructure/persistence/json/atomic_json_file.py
  • infrastructure/config/ — cài đặt thật + settings facade
    • @@ -559,7 +573,7 @@
-
N2 · Giám sátthành viên 1
+
N2 · Giám sátHiệp

Input — cần có

@@ -567,14 +581,14 @@
  • mã cũui/monitoring_tab.py 1.545 dòng
  • mã cũcore/usage_tracker.py 524 · sandbox_manager.py 335
  • mã cũcore/model_pricing.py 284 · agent_security.py 272 · audit_log.py 115
    • -
  • từ N1FakeConfigRepository — dùng được ngay
    • +
  • từ NamFakeConfigRepository — dùng được ngay
  • tự chốtGiữ nguyên 9 trường log, báo Duy và Hoa

    • Output — phải giao

      -
    • build_monitoring_tab() → cho N1, trước 28/08
      • +
    • build_monitoring_tab() → cho Nam, trước 28/08
    • FakeAuditLogger · FakeMonitoringQueryService → cho cả team
    • presentation/monitoring/ — 7 tab + shell
    • application/monitoring/monitoring_query_service.py
      • @@ -587,7 +601,7 @@
    -
    N3 · Co4E Studiothành viên 2
    +
    N3 · Co4E StudioLâm

    Input — cần có

    @@ -596,14 +610,14 @@
  • mã cũui/co4e_canvas.py 791 · co4e_config_panel.py
  • mã cũcore/co4e_run_manager.py 331
  • có sẵncore/co4e.py — dataclass Workflow/Node/Edge đã có
    • -
  • từ N1FakeConfigRepository
    • +
  • từ NamFakeConfigRepository
  • từ Team HoaDTO ToolPolicyGateway — rủi ro liên team cao nhất, lấy trong hôm nay

    • Output — phải giao

      -
    • build_co4e_tab() → cho N1, trước 28/08
      • +
    • build_co4e_tab() → cho Nam, trước 28/08
    • FakeCo4EWorkflowService → cho cả team
    • domain/workflows/ — DTO chốt ngày đầu
    • application/workflows/co4e_workflow_service.py
      • @@ -615,14 +629,14 @@
    -

    Output bắt buộc với cả ba, mỗi PR

    +

    Output bắt buộc với cả ba, mỗi lần đẩy

    - + @@ -637,9 +651,9 @@ - - - + + + @@ -685,7 +699,7 @@ - + @@ -701,7 +715,7 @@ - + @@ -721,18 +735,19 @@ - + - + - - + + diff --git a/docs/refactor/GammaTeam_decisions.md b/docs/refactor/GammaTeam_decisions.md index 99fbf27..bd9e695 100644 --- a/docs/refactor/GammaTeam_decisions.md +++ b/docs/refactor/GammaTeam_decisions.md @@ -1,9 +1,15 @@ -# Hai quyết định chờ nhóm trưởng chốt — Team Gamma +# Quyết định của Team Gamma -Hai việc này không code được cho tới khi có người quyết. Cả hai đều ảnh hưởng -ra ngoài phạm vi một người, nên để đây thay vì chôn trong comment. +Team: **Nam** (nhóm trưởng, nhánh N1) · **Hiệp** (N2) · **Lâm** (N3). -Trạng thái: **chưa chốt**. Hạn: trước khi N1 bắt đầu R02-T05 (26/08). +Ghi ở đây thay vì chôn trong comment, vì cả ba đều ảnh hưởng ra ngoài phạm vi +một người. + +| # | Việc | Trạng thái | +|---|---|---| +| 1 | `provider_conf()` còn trả `api_key` | **Chốt 21/08 — đường A** | +| 2 | Số phận 24 checker UI | **Chốt 21/08 — đường A** | +| 3 | DTO `ToolPolicyGateway` viết hộ Team Hoa | Đã làm, chờ Hoa xác nhận | --- @@ -53,7 +59,13 @@ họ không lên kế hoạch. Nếu chọn B thì **phải báo Team Duy và Team Hoa trong hôm nay**, không phải lúc đã sửa xong. -> Nhóm trưởng chốt: ☐ A ☐ B — ngày ____ +> **Nam chốt 21/08: đường A.** +> +> Việc kèm theo: `ConfigRepository` bản thật phải đọc key từ `SecretStore` rồi +> ghép vào dict do `provider_conf()` trả về. Năm nơi đọc không đổi một dòng, +> nên **không cần báo Duy và Hoa**. +> +> Nợ kỹ thuật đã ghi: đường B (bỏ `api_key` khỏi dict) để sau sprint này. --- @@ -104,7 +116,19 @@ không có gì thay thế cho phần giao diện. `tools/check_probes_bite.py` đã có sẵn cơ chế chứng minh checker còn cắn được; chạy nó sau mỗi đợt sửa là bắt được ngay chuyện đó. -> Nhóm trưởng chốt: ☐ A ☐ B ☐ C — ngày ____ +> **Chốt 21/08: đường A** — ai dời file thì cập nhật checker tương ứng ngay +> trong PR đó. +> +> Kèm hai ràng buộc, vì rủi ro của đường A là người sửa vội nới lỏng phép kiểm: +> +> 1. PR nào *sửa* checker phải nói rõ trong mô tả **sửa gì và vì sao**. +> 2. Sửa xong chạy `python tools/check_probes_bite.py` — nó cắm lỗi cố ý vào +> code rồi kiểm checker có bắt được không. Chính công cụ này đã từng bắt +> được một checker bị sửa thành *không thể đỏ*. +> +> Không đưa 24 checker vào CI trong sprint này: chúng dựng `MainWindow` thật, +> mỗi lần chạy tốn hàng chục giây và thỉnh thoảng sập lúc Qt dọn dẹp. Chạy tay +> theo phạm vi mình đụng là đủ. ---
    Điều kiệnNgưỡngTự kiểm bằng
    File mới sau khi tách≤ 400 dòngwc -l
    domain/ và application/ import PySide60grep -r PySide6
    Test hiện có96 xanhpytest tests -q
    Test hiện có102 xanhpytest tests -q
    Credential lộ0python scripts/audit_security.py
    Checker UI trong phạm vi mình dờiđã cập nhậtpython tools/check_<tên>.py
    NgàyN1 · Cấu hình & VỏN2 · Giám sátN3 · Co4EN1 · NamN2 · HiệpN3 · Lâm
    28/08
    T6    		bootstrap.py + tách MainWindowNhận factory của N2 và N3 để lắpbootstrap.py + tách MainWindowNhận factory của Hiệp và Lâm để lắp Nộp factory · dọn file >400 dòng · cập nhật checker Nộp factory · dọn file >400 dòng · cập nhật checker
    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.CASAN Gate   Nam chủ trì Check 1 — quét toàn bộ config/JSON, phải ra 0 secret plaintext. Hiệp và Lâm sửa ngay phần của mình nếu script bắt được.
    31/08
    T2 15:00
    N2 có chạy được khi chưa có config bản thật?Hiệp 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 FakeConfigRepository 21/08
    N3 có chạy được khi Team Hoa chưa xong gateway?Lâm có chạy được khi Team Hoa chưa xong gateway? Test Co4EWorkflowService xanh với FakeToolPolicyGateway 23/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ỗngBa người có đụng file nhau không?git log --name-only --pretty=%an trên gamma/refactor — + không file nào được xuất hiện dưới hai tên khác nhau mỗi ngày