c7d71b77a7
Bộ 7 role chuyên biệt (triage → specialist → implementer → reviewer) cùng lớp dùng chung: guardrail, tri thức về repo, checklist, và contract đầu ra. Vì sao có: bug UI/UX được báo bằng lời kể triệu chứng, và người sửa hay bỏ qua ba thứ mà repo này rất dễ vi phạm — luật "không file nào ngoài theme/ được đặt tên một màu", trần LOC theo bánh cóc, và việc ui/ với presentation/ cùng tồn tại nên sửa nhầm file là "đã fix mà vẫn thấy lỗi". knowledge/qt_pitfalls.md chép lại 20 nguyên nhân gốc hay gặp của bug PySide6; examples/bad_fix.md có hai ca CÓ THẬT, gồm ca chính bản vá trong nhánh này từng mắc (compare_digest trên str ngoài ASCII) và lọt qua vòng review đầu. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# CASAN Quality Gate — cổng bắt buộc trước PR
|
|
|
|
Nguồn: `README.md`, `scripts/run_quality_gate.py`.
|
|
|
|
---
|
|
|
|
## 1. Năm cổng
|
|
|
|
| Cổng | Script | Kiểm tra |
|
|
|---|---|---|
|
|
| **C** — Clean Architecture | `scripts/check_imports.py` | `domain/` và `application/` không import `PySide6`, `PySide2`, `PyQt6`, `PyQt5`, `ui`, `app` |
|
|
| **A** — Atomic & Secrets | `scripts/audit_security.py` | Secret/plaintext trong file `.py` và file config |
|
|
| **S** — Single Responsibility | `scripts/check_loc.py --max-lines 400` | Mọi module production `<= 400 LOC` |
|
|
| **O** — Orphan Module | `scripts/check_orphan_modules.py` | Module không được import từ đâu |
|
|
| **A/N** — Tests | `pytest` | Toàn bộ suite |
|
|
|
|
## 2. Lệnh
|
|
|
|
```bash
|
|
# Đủ 5 cổng — chạy trước khi tạo PR
|
|
python scripts/run_quality_gate.py
|
|
|
|
# Chỉ guard tĩnh, bỏ test — vòng lặp sửa nhanh
|
|
python scripts/run_quality_gate.py --skip-tests
|
|
|
|
# Từng cổng
|
|
python scripts/check_imports.py
|
|
python scripts/audit_security.py
|
|
python scripts/check_loc.py --max-lines 400
|
|
pytest tests/e2e/test_smoke.py -v
|
|
```
|
|
|
|
## 3. Chạy test UI headless
|
|
|
|
```bash
|
|
QT_QPA_PLATFORM=offscreen pytest tests/ui -q # bash
|
|
$env:QT_QPA_PLATFORM="offscreen"; pytest tests/ui -q # PowerShell
|
|
```
|
|
|
|
64/108 module test dựng widget thật và 20 module import PySide6 ở module scope, nên môi
|
|
trường test **phải** có đủ runtime dependency. Chỉ có **một** `requirements.txt`, không có
|
|
cặp runtime/test riêng.
|
|
|
|
## 4. Bẫy khi sửa bug UI
|
|
|
|
- **Gate S rất dễ vỡ khi vá bug.** Nhiều file UI đã sát 400 dòng. Trước khi thêm code:
|
|
```bash
|
|
python scripts/check_loc.py --max-lines 400 | grep <tên file>
|
|
```
|
|
Sắp vượt → tách module **và nêu trong `fix_plan.md` trước khi làm** (`guardrail.md` G6).
|
|
|
|
- **Gate O bắt module mồ côi.** Tách file mới ra mà chưa import vào đâu là Gate O đỏ.
|
|
Tách và nối dây trong cùng một commit.
|
|
|
|
- **Gate C ít khi liên quan bug UI** — trừ khi bản vá "tiện tay" import widget vào
|
|
`application/`. Đó là dấu hiệu sửa sai tầng.
|
|
|
|
- **File `.py` mới phải được `git add` ngay.**
|
|
`tests/test_no_ignored_source.py::test_khong_file_py_nao_bi_bo_quen_chua_theo_doi` quét
|
|
`git ls-files --others --exclude-standard` và làm suite đỏ nếu có file `.py` chưa theo dõi
|
|
trong thư mục nguồn. File test mới cũng tính. Triệu chứng giống hệt regression, nhưng
|
|
không phải:
|
|
|
|
```
|
|
AssertionError: File mã nguồn chưa được git add — clone sạch sẽ thiếu:
|
|
tests/ui/test_<...>.py
|
|
```
|
|
|
|
- **`.venv` không được nằm trong repo.** `install.bat` dựng venv ở
|
|
`%LOCALAPPDATA%\CoworkLocal` chính vì gate đi bộ toàn cây thư mục — một `.venv` trong repo
|
|
biến mọi module vendored thành vi phạm Gate O.
|
|
|
|
## 5. Định nghĩa "xong"
|
|
|
|
Từ `docs/governance/definition-of-done.md`:
|
|
|
|
- code xong;
|
|
- test liên quan pass;
|
|
- tài liệu cập nhật nếu cần;
|
|
- PR đã được review;
|
|
- đã merge vào nhánh mặc định.
|
|
|
|
**Một PR = một thay đổi logic.** Không gộp nhiều bug UI không liên quan vào một PR.
|
|
|
|
Đóng góp từ FSG AI Core Team chỉ "xong" khi PR đã merge vào Cowork Local — "Core AI code
|
|
xong" hoặc "pre-review pass" **không** phải Done. Bằng chứng bắt buộc: core issue reference,
|
|
PR, evidence test, reviewer phía Cowork, merge commit.
|
|
|
|
---
|
|
|
|
## 6. Suite này vốn đã KHÔNG xanh
|
|
|
|
Tại `e5fa21e` (2026-09-07), chạy đầy đủ trên Windows + Python 3.14 cho ra:
|
|
|
|
```
|
|
11 failed, 884 passed, 2 skipped, 66 errors
|
|
```
|
|
|
|
Nghĩa là **"pytest đỏ" không nói lên điều gì** về bản vá của bạn. Bắt buộc phải so với
|
|
baseline, và so bằng **danh sách tên test**:
|
|
|
|
```bash
|
|
git stash push --include-untracked -m baseline
|
|
QT_QPA_PLATFORM=offscreen pytest -q > /tmp/base.txt 2>&1
|
|
git stash pop
|
|
QT_QPA_PLATFORM=offscreen pytest -q > /tmp/after.txt 2>&1
|
|
|
|
grep "^FAILED" /tmp/base.txt | sed 's/ - .*//' | sort > /tmp/f_base.txt
|
|
grep "^FAILED" /tmp/after.txt | sed 's/ - .*//' | sort > /tmp/f_after.txt
|
|
comm -13 /tmp/f_base.txt /tmp/f_after.txt # rỗng = không regression
|
|
```
|
|
|
|
Không so con số tổng: một test cũ hỏng cộng một test mới xanh cho ra cùng con số.
|
|
|
|
Nhóm đỏ lớn nhất hiện nay là `tests/characterization/test_co4e_runs_page.py` —
|
|
`RuntimeError: libshiboken: Internal C++ object (QGraphicsScene) already deleted`
|
|
(bẫy P13 trong `qt_pitfalls.md`). Chưa ai nhận sửa.
|
|
|
|
Gate A và Gate S cũng đỏ sẵn:
|
|
|
|
- A — 3 phát hiện trong `tests/test_project_context_{e2e,issue,knowledge}.py`;
|
|
- S — `core/chat_agent.py` 423 LOC, `mcp_servers/project_context/providers/knowledge.py` 408 LOC.
|
|
|
|
Đừng nhận nhầm bốn thứ trên là do bản vá của mình (`guardrail.md` G10).
|