@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bridges.js +2 -2
- package/dist/library-edit.d.ts +51 -2
- package/dist/library-edit.js +160 -8
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/models.d.ts +35 -0
- package/dist/models.js +17 -1
- package/dist/packaged.d.ts +45 -12
- package/dist/packaged.js +46 -5
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +3 -3
- package/dist/providers.d.ts +2 -4
- package/dist/providers.js +20 -4
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/user-settings.d.ts +2 -0
- package/dist/user-settings.js +40 -1
- package/dist/validation.d.ts +1 -0
- package/dist/validation.js +16 -10
- package/package.json +18 -2
- package/src/bridges.js +3 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packaged.js +77 -8
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +4 -4
- package/src/providers.js +20 -5
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/upgrade.js +54 -6
- package/src/user-settings.d.ts +2 -0
- package/src/user-settings.js +51 -1
- package/src/validation.d.ts +1 -0
- package/src/validation.js +21 -12
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -145
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +2 -2
- package/templates/skills/curate/SKILL.md +6 -5
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: web-testing
|
|
3
|
+
description: "Viết và chạy test web bằng công cụ của dự án: e2e (kiểu Playwright), unit và component (kiểu Vitest hay Jest), kiểm thị giác và accessibility, test hiệu năng và tải (kiểu k6), và các kiểm tra bảo mật cơ bản, chỉ trên môi trường test. Dùng khi thêm, sửa, hay chạy các bộ test web. Không dùng cho thiết kế test (test-strategy) hay chẩn đoán lỗi (bug-loop)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Test web
|
|
7
|
+
|
|
8
|
+
## Khi nào dùng
|
|
9
|
+
|
|
10
|
+
- Thêm hoặc cập nhật test e2e, unit, component, thị giác, hay accessibility cho một app
|
|
11
|
+
web.
|
|
12
|
+
- Làm cho một bộ test web chập chờn hay chậm trở nên tin cậy ở tầng công cụ (selector, chờ,
|
|
13
|
+
cách ly, fixture, trace).
|
|
14
|
+
- Chạy một mốc hiệu năng cơ sở hoặc test tải trên một môi trường test.
|
|
15
|
+
- Chạy các kiểm tra bảo mật cơ bản đã được phép (audit phụ thuộc, kiểm header, test luồng
|
|
16
|
+
auth) trên một môi trường test.
|
|
17
|
+
- Một reviewer chỉ đọc được nhờ đánh giá code test (chỉ tư vấn).
|
|
18
|
+
|
|
19
|
+
## Không dùng cho
|
|
20
|
+
|
|
21
|
+
- Quyết định test cái gì, ở tầng nào, và vì sao: dùng test-strategy.
|
|
22
|
+
- Một test fail hay hồi quy mà chưa rõ nguyên nhân: dùng bug-loop.
|
|
23
|
+
- Audit bảo mật hay review mối đe dọa của code: dùng security-review.
|
|
24
|
+
- Dựng chính tính năng đang được test: dùng frontend-development hay backend-development.
|
|
25
|
+
- Chọn framework test, runner, hay dịch vụ mới: quyết định của chủ sở hữu.
|
|
26
|
+
|
|
27
|
+
## Điều kiện tiên quyết
|
|
28
|
+
|
|
29
|
+
- Đường dẫn sở hữu và tiêu chí nghiệm thu trong brief; ALP.md và chỉ dẫn của dự án.
|
|
30
|
+
- Công cụ test và các lệnh đang có, đọc từ phần scripts của `package.json` (hoặc
|
|
31
|
+
tương đương), file config của runner, và config CI. Không suy ra từ tên thư mục.
|
|
32
|
+
- Các test đang có gần chỗ thay đổi. Chúng định ra cách đặt tên, fixture, helper, và cách
|
|
33
|
+
app được khởi động để test.
|
|
34
|
+
- Một môi trường test: dev server cục bộ, bản build preview, hoặc một bản
|
|
35
|
+
deploy test riêng. Không bao giờ là production trừ khi chủ sở hữu cho phép tường minh.
|
|
36
|
+
- Tài khoản và dữ liệu test lấy từ fixture hay script seed của dự án; không bao giờ dùng thông tin
|
|
37
|
+
đăng nhập của người dùng thật.
|
|
38
|
+
|
|
39
|
+
## Quy trình
|
|
40
|
+
|
|
41
|
+
1. Lấy các ca cần bao phủ từ brief hoặc từ đầu ra của test-strategy. Nếu chưa có,
|
|
42
|
+
hãy liệt kê các hành vi người dùng thấy được và chuyển việc chọn lên trên khi nó quan trọng.
|
|
43
|
+
2. Chọn tầng rẻ nhất chứng minh được từng ca: unit cho logic, component cho
|
|
44
|
+
render và tương tác, e2e cho một ít luồng liên trang then chốt. Đọc
|
|
45
|
+
unit-and-component.md hoặc e2e.md.
|
|
46
|
+
3. Dùng lại fixture, page object, factory, và helper đang có trước khi viết cái
|
|
47
|
+
mới.
|
|
48
|
+
4. Viết mỗi test sao cho nó độc lập: dữ liệu riêng, không phụ thuộc thứ tự, không dùng chung
|
|
49
|
+
state thay đổi được, dọn dẹp hoặc có state mới cho mỗi test.
|
|
50
|
+
5. Truy vấn phần tử theo vai trò, nhãn, hay chữ thấy được; chờ theo điều kiện, không bao giờ
|
|
51
|
+
chờ theo thời gian ngủ cố định.
|
|
52
|
+
6. Chỉ thêm kiểm thị giác hay accessibility ở nơi dự án đã chạy chúng hoặc
|
|
53
|
+
brief yêu cầu; giữ snapshot nhỏ và tất định.
|
|
54
|
+
7. Với việc hiệu năng hay tải, hãy đọc performance-testing.md; lập mốc cơ sở
|
|
55
|
+
trước khi so sánh, và xin phép tường minh cho bất kỳ đích dùng chung nào.
|
|
56
|
+
8. Với kiểm tra bảo mật, hãy đọc security-testing.md; chỉ chạy những kiểm tra an toàn trên
|
|
57
|
+
môi trường bạn được phép test.
|
|
58
|
+
9. Chạy các test mới và bộ test xung quanh bằng lệnh của dự án. Chạy một
|
|
59
|
+
test e2e mới vài lần ở máy cục bộ để lộ ra sự chập chờn.
|
|
60
|
+
10. Handoff: test đã thêm hay đổi, lệnh kèm kết quả, các lần chạy kiểm chập chờn, chỗ chứa
|
|
61
|
+
artifact (trace, báo cáo), các khoảng trống, và những gì cần chủ sở hữu quyết định.
|
|
62
|
+
|
|
63
|
+
## Ràng buộc
|
|
64
|
+
|
|
65
|
+
- Trước hết hãy theo stack test và quy ước đang có của dự án. Playwright,
|
|
66
|
+
Cypress, Vitest, Jest, Testing Library, axe, k6, hay Lighthouse chỉ là ví dụ, không phải
|
|
67
|
+
khuyến nghị.
|
|
68
|
+
- Không thêm framework test, browser, plugin, hay dịch vụ mà không có quyết định của
|
|
69
|
+
chủ sở hữu. Không tự động cài; nếu thiếu một binary browser hay một công cụ, hãy báo lại.
|
|
70
|
+
- Không bao giờ test tải, quét, hay thăm dò production hay hệ thống của bên thứ ba mà không có
|
|
71
|
+
văn bản cho phép tường minh của chủ sở hữu.
|
|
72
|
+
- Không bao giờ dùng thông tin đăng nhập thật hay dữ liệu cá nhân; dùng tài khoản test và dữ liệu tổng hợp.
|
|
73
|
+
- Không làm yếu các assertion, không thêm retry, không skip test để bộ test pass; một test
|
|
74
|
+
chập chờn hay fail thì chuyển sang bug-loop.
|
|
75
|
+
- Không cập nhật snapshot hay mốc cơ sở mà chưa kiểm rằng output mới đúng là
|
|
76
|
+
hành vi mong muốn.
|
|
77
|
+
- Ở trong đường dẫn sở hữu. Sửa cấu hình CI là ngoài phạm vi trừ khi được giao.
|
|
78
|
+
|
|
79
|
+
## Kiểm chứng
|
|
80
|
+
|
|
81
|
+
- Test mới phải fail khi không có hành vi nó bao phủ (hoặc khi hành vi đó bị vỡ) và pass
|
|
82
|
+
khi có.
|
|
83
|
+
- Test e2e mới pass qua nhiều lần chạy lặp lại (ví dụ ba tới năm lần) mà không cần retry.
|
|
84
|
+
- Bộ test xung quanh vẫn pass với lệnh của dự án.
|
|
85
|
+
- Không có thời gian ngủ cố định, không phụ thuộc thứ tự, không có secret thật trong test mới.
|
|
86
|
+
- Kết quả hiệu năng kèm mốc cơ sở, điều kiện đo, và môi trường đích.
|
|
87
|
+
|
|
88
|
+
## Xử lý khi thất bại
|
|
89
|
+
|
|
90
|
+
- Thiếu công cụ hay browser, hoặc app không khởi động được ở đây: báo đúng lệnh
|
|
91
|
+
và lỗi đó; không khẳng định là test đã chạy.
|
|
92
|
+
- Một test chập chờn: ghi lại trace hay log, rồi chuyển sang bug-loop để tìm nguyên nhân.
|
|
93
|
+
- Một test lộ ra bug của sản phẩm: báo nó kèm cách tái hiện; không sửa
|
|
94
|
+
test cho khớp với hành vi sai.
|
|
95
|
+
- Chưa rõ việc cho phép với một đích tải hay bảo mật: dừng lại và chuyển lên trên.
|
|
96
|
+
|
|
97
|
+
## Tài liệu tham chiếu
|
|
98
|
+
|
|
99
|
+
- [references/e2e.md](references/e2e.md) — đọc khi viết hay làm ổn định test end-to-end trên browser (bước 2-5).
|
|
100
|
+
- [references/unit-and-component.md](references/unit-and-component.md) — đọc khi viết test unit hay component, mock, hay snapshot (bước 2-6).
|
|
101
|
+
- [references/performance-testing.md](references/performance-testing.md) — đọc khi chạy mốc hiệu năng cơ sở, ngân sách, hay test tải (bước 7).
|
|
102
|
+
- [references/security-testing.md](references/security-testing.md) — đọc khi chạy audit phụ thuộc, kiểm header, hay test luồng auth (bước 8).
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Test end-to-end
|
|
2
|
+
|
|
3
|
+
Đọc khi viết hay làm ổn định test end-to-end trên browser.
|
|
4
|
+
|
|
5
|
+
Ví dụ dùng API kiểu Playwright; Cypress và các công cụ dựa trên WebDriver đều có
|
|
6
|
+
cái tương đương. Hãy dùng runner, config, và helper của dự án.
|
|
7
|
+
|
|
8
|
+
## Phạm vi
|
|
9
|
+
|
|
10
|
+
- Giữ số test e2e ít và tập trung vào các hành trình người dùng then chốt: đăng nhập, luồng
|
|
11
|
+
tạo/đọc/cập nhật chính, thanh toán hay gửi biểu mẫu, các ranh giới phân quyền.
|
|
12
|
+
- Đẩy các ca biên và biến thể validate xuống tầng test component hoặc unit.
|
|
13
|
+
- Một test chứng minh một hành trình; tránh những script khổng lồ test mọi thứ theo thứ tự.
|
|
14
|
+
|
|
15
|
+
## Selector
|
|
16
|
+
|
|
17
|
+
Ưu tiên những selector mà người dùng cũng nhận ra, theo thứ tự sau:
|
|
18
|
+
|
|
19
|
+
1. Vai trò kèm tên truy cập được: `getByRole('button', { name: 'Save' })`.
|
|
20
|
+
2. Nhãn: `getByLabel('Email')`.
|
|
21
|
+
3. Chữ thấy được hoặc placeholder cho nội dung không tương tác.
|
|
22
|
+
4. Một test ID riêng (`data-testid`) khi không có chỗ nắm nào truy cập được, theo
|
|
23
|
+
quy ước của dự án.
|
|
24
|
+
|
|
25
|
+
Tránh class CSS, cấu trúc DOM, nth-child, và XPath; chúng vỡ khi markup
|
|
26
|
+
đổi. Thiếu tên truy cập được thường là một bug accessibility thật; hãy báo lại.
|
|
27
|
+
|
|
28
|
+
## Chờ theo điều kiện, không ngủ
|
|
29
|
+
|
|
30
|
+
- Không bao giờ dùng thời gian ngủ cố định (`waitForTimeout`, `sleep`) để đồng bộ.
|
|
31
|
+
- Dùng các hành động tự chờ và những assertion ưu tiên web, tự thử lại tới khi một điều kiện
|
|
32
|
+
thành đúng (`expect(locator).toBeVisible()`, `toHaveText`, `toHaveURL`).
|
|
33
|
+
- Chờ đúng phản hồi mạng hay trạng thái UI mà bước kế tiếp phụ thuộc vào.
|
|
34
|
+
- Giữ timeout ở mức mặc định của dự án; nâng timeout lên để test pass là che đi một
|
|
35
|
+
đường đi chậm hoặc đã vỡ.
|
|
36
|
+
|
|
37
|
+
## Cách ly
|
|
38
|
+
|
|
39
|
+
- Mỗi test tự tạo hoặc tự seed dữ liệu của nó (gọi API, helper seed, hoặc fixture)
|
|
40
|
+
và không dựa vào test khác hay thứ tự chạy.
|
|
41
|
+
- Dùng một context browser mới cho mỗi test; dùng lại trạng thái lưu trữ đã đăng nhập từ một
|
|
42
|
+
bước setup thay vì đăng nhập qua UI mỗi lần, nếu dự án làm vậy.
|
|
43
|
+
- Dùng tên độc nhất (thêm hậu tố là ID của lần chạy) để tránh xung đột khi chạy song song.
|
|
44
|
+
- Dọn dữ liệu đã tạo khi môi trường là dùng chung, hoặc dùng một môi trường
|
|
45
|
+
dùng một lần rồi bỏ.
|
|
46
|
+
- Không dùng chung state thay đổi được ở cấp module giữa các test.
|
|
47
|
+
|
|
48
|
+
## Phụ thuộc bên ngoài
|
|
49
|
+
|
|
50
|
+
- Thay thế các dịch vụ bên thứ ba (thanh toán, email, bản đồ, analytics) ở tầng mạng
|
|
51
|
+
hoặc trỏ chúng tới các chế độ sandbox mà dự án đã dùng.
|
|
52
|
+
- Không bao giờ gửi email, SMS, hay thanh toán thật từ test.
|
|
53
|
+
- Kiểm soát thời gian và tính ngẫu nhiên ở nơi app cho phép (mock đồng hồ, dữ liệu có seed).
|
|
54
|
+
|
|
55
|
+
## Assertion
|
|
56
|
+
|
|
57
|
+
- Khẳng định các kết quả người dùng thấy được: chữ, URL, trạng thái bật, một dòng xuất hiện.
|
|
58
|
+
- Khẳng định là không có toast lỗi hay lỗi console, khi dự án cũng làm vậy.
|
|
59
|
+
- Tránh khẳng định layout chính xác tới từng pixel trong test chức năng; đó là việc của test thị giác.
|
|
60
|
+
|
|
61
|
+
## Kiểm thị giác và accessibility
|
|
62
|
+
|
|
63
|
+
- Snapshot thị giác: khung nhìn, font, và dữ liệu ổn định; che các vùng động (ngày,
|
|
64
|
+
ảnh đại diện); tắt hoạt họa. Hãy xem lại mọi khác biệt snapshot trước khi chấp nhận nó.
|
|
65
|
+
- Snapshot khác nhau giữa các OS và bản build browser; hãy sinh mốc cơ sở trong cùng
|
|
66
|
+
môi trường mà CI dùng.
|
|
67
|
+
- Quét accessibility (kiểu axe) trên các trang và trạng thái chính, gồm cả dialog đang mở.
|
|
68
|
+
Coi chúng là mức sàn, không phải bằng chứng đã đạt accessibility.
|
|
69
|
+
|
|
70
|
+
## Gỡ lỗi và trace
|
|
71
|
+
|
|
72
|
+
- Bật trace, ảnh chụp, hay video khi fail hoặc ở lần retry đầu, theo config của dự án.
|
|
73
|
+
- Đọc trace trước khi sửa test: xác định bước nào, trạng thái DOM, và các
|
|
74
|
+
lệnh gọi mạng tại thời điểm fail.
|
|
75
|
+
- Tái hiện sự chập chờn bằng cách chạy lặp lại (`--repeat-each` hoặc tương đương) và với
|
|
76
|
+
nhiều worker song song; ghi lại tỉ lệ fail.
|
|
77
|
+
- Retry trong CI có thể tồn tại như một chính sách; một test cần tới chúng thì vẫn là chập chờn và phải
|
|
78
|
+
chuyển sang bug-loop.
|
|
79
|
+
|
|
80
|
+
## Chạy test
|
|
81
|
+
|
|
82
|
+
- Chạy trên một server cục bộ hay bản build preview, khởi động theo đúng cách dự án làm
|
|
83
|
+
(config web-server của runner hoặc một script).
|
|
84
|
+
- Chạy headless trong CI, và chạy có giao diện hoặc kèm inspector ở cục bộ khi gỡ lỗi.
|
|
85
|
+
- Chạy đúng những browser mà dự án nhắm tới; không thêm browser mà không có quyết định.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Test hiệu năng và test tải
|
|
2
|
+
|
|
3
|
+
Đọc khi chạy mốc hiệu năng cơ sở, ngân sách, hay test tải.
|
|
4
|
+
|
|
5
|
+
Ví dụ dùng script kiểu k6 cho phần tải và audit kiểu Lighthouse cho hiệu năng
|
|
6
|
+
trang; Artillery, Gatling, Locust, hay WebPageTest là tương đương. Hãy dùng
|
|
7
|
+
những công cụ dự án đã có.
|
|
8
|
+
|
|
9
|
+
## Xin phép trước đã
|
|
10
|
+
|
|
11
|
+
- Không bao giờ test tải hay gây áp lực lên production, một môi trường staging dùng chung, hay bất kỳ
|
|
12
|
+
API bên thứ ba nào mà không có phép tường minh của chủ sở hữu, nêu rõ đích,
|
|
13
|
+
khung thời gian, và mức tải tối đa.
|
|
14
|
+
- Dồn tải lên dịch vụ bên thứ ba (thanh toán, email, bản đồ) có thể vi phạm điều khoản của họ
|
|
15
|
+
và tốn tiền; hãy stub chúng hoặc dùng sandbox của họ với các giới hạn của nó.
|
|
16
|
+
- Một test tải có thể trông như một cuộc tấn công với nhà cung cấp hosting; chủ sở hữu là người lo
|
|
17
|
+
việc thông báo nếu cần.
|
|
18
|
+
- Đích mặc định: một bản build cục bộ hoặc một môi trường test riêng mà bạn kiểm soát.
|
|
19
|
+
- Dừng ngay nếu lỗi vọt lên trên một môi trường dùng chung hoặc có người dùng khác bị
|
|
20
|
+
ảnh hưởng, và báo lại.
|
|
21
|
+
|
|
22
|
+
## Xác định câu hỏi
|
|
23
|
+
|
|
24
|
+
- Nêu rõ bạn đang đo cái gì và vì sao: kiểm hồi quy, ước lượng năng lực,
|
|
25
|
+
độ trễ dưới mức tải dự kiến, hay chạy dài để tìm rò rỉ.
|
|
26
|
+
- Chọn loại test: smoke (tải rất nhỏ, kiểm chính script), load (lưu lượng dự kiến),
|
|
27
|
+
stress (vượt mức dự kiến, tìm điểm vỡ), spike (bùng lên đột ngột), soak
|
|
28
|
+
(tải đều trong thời gian dài).
|
|
29
|
+
- Dùng tình huống thực tế: đúng tỉ lệ pha trộn endpoint và hành trình người dùng mà lưu lượng thật
|
|
30
|
+
có, thời gian nghĩ giữa các bước, payload và lượng dữ liệu thực tế.
|
|
31
|
+
|
|
32
|
+
## Mốc cơ sở
|
|
33
|
+
|
|
34
|
+
- Đo một mốc cơ sở trên bản main hay bản release hiện tại, trong cùng môi trường,
|
|
35
|
+
trước khi test một thay đổi.
|
|
36
|
+
- Giữ điều kiện giống nhau giữa các lần chạy: cỡ môi trường, lượng dữ liệu, chế độ
|
|
37
|
+
build, cấu hình mạng, cache nóng hay nguội, thời lượng test.
|
|
38
|
+
- Chạy nhiều hơn một lần; báo cả độ phân tán, không chỉ một lần chạy tốt nhất.
|
|
39
|
+
- Ghi lại điều kiện cùng với mỗi kết quả để có thể tái hiện.
|
|
40
|
+
|
|
41
|
+
## Chỉ số
|
|
42
|
+
|
|
43
|
+
- Server và API: các phân vị độ trễ (p50, p95, p99) thay vì giá trị trung bình,
|
|
44
|
+
thông lượng, tỉ lệ lỗi, và độ bão hòa (CPU, bộ nhớ, kết nối, độ sâu hàng đợi) nếu
|
|
45
|
+
quan sát được.
|
|
46
|
+
- Hiệu năng trang: Core Web Vitals (LCP, INP, CLS), thời gian tới byte đầu tiên, tổng
|
|
47
|
+
kích thước truyền, và các task dài, dưới một cấu hình thiết bị và mạng đã nêu rõ.
|
|
48
|
+
- Tách giới hạn của công cụ phía client khỏi giới hạn của server; một máy phát tải đang 100% CPU
|
|
49
|
+
cho ra những con số vô nghĩa.
|
|
50
|
+
|
|
51
|
+
## Ngân sách và ngưỡng
|
|
52
|
+
|
|
53
|
+
- Dùng ngân sách mà dự án đã định ra (kích thước bundle, LCP, độ trễ p95, tỉ lệ lỗi).
|
|
54
|
+
- Nếu chưa có, hãy báo các giá trị đo được và đề xuất ngân sách cho chủ sở hữu; đừng
|
|
55
|
+
tự nghĩ ra ngưỡng pass/fail rồi trình bày chúng như yêu cầu.
|
|
56
|
+
- Mã hóa các ngưỡng đã thống nhất vào cơ chế threshold của công cụ, để một lần chạy fail
|
|
57
|
+
một cách khách quan.
|
|
58
|
+
|
|
59
|
+
## Script
|
|
60
|
+
|
|
61
|
+
- Giữ script trong thư mục test của dự án, theo quy ước của dự án.
|
|
62
|
+
- Tham số hóa URL đích, số người dùng, và thời lượng qua biến môi trường;
|
|
63
|
+
mặc định trỏ tới đích cục bộ hay đích test, không bao giờ production.
|
|
64
|
+
- Dùng tài khoản test và dữ liệu tổng hợp; không bao giờ dùng thông tin đăng nhập thật. Tạo và dọn
|
|
65
|
+
dữ liệu test mà lần chạy đó cần.
|
|
66
|
+
- Kiểm cả phản hồi (status, một field quan trọng), không chỉ kiểm là request đã trả về;
|
|
67
|
+
lỗi nhanh trông giống như độ trễ tốt.
|
|
68
|
+
- Tăng tải dần dần; có một chặng smoke ngắn trước khi vào tải đầy.
|
|
69
|
+
|
|
70
|
+
## Đọc hiểu kết quả
|
|
71
|
+
|
|
72
|
+
- So với mốc cơ sở trong cùng điều kiện; coi những chênh lệch nằm trong
|
|
73
|
+
độ phân tán giữa các lần chạy là nhiễu.
|
|
74
|
+
- Tìm chỗ độ trễ bắt đầu bật lên khi tải tăng; đó là giới hạn năng lực.
|
|
75
|
+
- Đối chiếu với chỉ số và log của server ở nơi có, để xác định điểm nghẽn,
|
|
76
|
+
rồi giao việc chẩn đoán cho bug-loop hoặc cho skill phụ trách (databases,
|
|
77
|
+
backend-development, frontend-development).
|
|
78
|
+
|
|
79
|
+
## Báo cáo
|
|
80
|
+
|
|
81
|
+
- Môi trường đích và tham chiếu tới việc cho phép, công cụ và phiên b��n, tình huống, cấu hình
|
|
82
|
+
tải, thời lượng, lượng dữ liệu.
|
|
83
|
+
- Kết quả mốc cơ sở và kết quả mới kèm các phân vị, tỉ lệ lỗi, và độ phân tán.
|
|
84
|
+
- Các quan sát về điểm nghẽn, có ghi rõ là bằng chứng hay là suy luận.
|
|
85
|
+
- Những gì chưa chạy và vì sao.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Test bảo mật cơ bản
|
|
2
|
+
|
|
3
|
+
Đọc khi chạy audit phụ thuộc, kiểm header, hay test luồng auth.
|
|
4
|
+
|
|
5
|
+
Phần này nói về các kiểm tra an toàn, thường lệ, trong môi trường test. Review bảo mật của code hay
|
|
6
|
+
thiết kế thuộc về security-review. Viết mã khai thác, kiểm thử xâm nhập, và
|
|
7
|
+
quét những hệ thống bạn không sở hữu đều nằm ngoài phạm vi.
|
|
8
|
+
|
|
9
|
+
## Việc cho phép và an toàn
|
|
10
|
+
|
|
11
|
+
- Chỉ test những môi trường chủ sở hữu đã cho phép: cục bộ, CI, hoặc một bản
|
|
12
|
+
deploy test riêng. Không bao giờ test production hay hệ thống bên thứ ba mà không có văn bản
|
|
13
|
+
cho phép tường minh, nêu rõ đích và các kiểm tra được phép.
|
|
14
|
+
- Chỉ dùng tài khoản test và dữ liệu tổng hợp. Không đọc, in ra, hay lưu secret,
|
|
15
|
+
token, hay dữ liệu cá nhân thật.
|
|
16
|
+
- Dùng các kiểm tra không phá hoại. Không chạy scanner hung hãn, fuzzer, hay
|
|
17
|
+
công cụ dò vét cạn, trừ khi chủ sở hữu đã cho phép dùng chúng trên đích đó.
|
|
18
|
+
- Nếu một kiểm tra phát hiện một lỗ hổng thật, hãy dừng việc thăm dò nó, ghi lại các bước
|
|
19
|
+
tái hiện tối thiểu, và báo lên trên một cách riêng tư; không dán chi tiết khai thác
|
|
20
|
+
hay secret vào log dùng chung.
|
|
21
|
+
|
|
22
|
+
## Audit phụ thuộc
|
|
23
|
+
|
|
24
|
+
- Chạy công cụ audit có sẵn của trình quản lý package (ví dụ `npm audit`, `pnpm audit`,
|
|
25
|
+
`pip-audit`, `govulncheck`) hoặc scanner mà dự án đã dùng. Không
|
|
26
|
+
cài scanner mới mà không có quyết định.
|
|
27
|
+
- Báo lại: package, phiên bản đã cài, cảnh báo bảo mật, mức nghiêm trọng, đường chạy code có lỗ hổng
|
|
28
|
+
có với tới được hay không nếu biết, và phiên bản đã sửa.
|
|
29
|
+
- Không chạy các lệnh tự động sửa để nâng cấp phụ thuộc; nâng cấp là một
|
|
30
|
+
thay đổi riêng, phải được chủ sở hữu chấp thuận và có test riêng của nó.
|
|
31
|
+
- Ghi riêng các phụ thuộc chỉ dùng khi dev, tách khỏi phụ thuộc lúc chạy.
|
|
32
|
+
|
|
33
|
+
## Kiểm header HTTP
|
|
34
|
+
|
|
35
|
+
Gửi request tới các trang chính và các phản hồi API từ môi trường test rồi kiểm:
|
|
36
|
+
|
|
37
|
+
- `Strict-Transport-Security` trên các phản hồi HTTPS.
|
|
38
|
+
- `Content-Security-Policy` có mặt và không có `unsafe-inline` rộng hay nguồn script
|
|
39
|
+
dạng ký tự đại diện, theo chính sách của dự án.
|
|
40
|
+
- `X-Content-Type-Options: nosniff`.
|
|
41
|
+
- Kiểm soát việc nhúng khung: CSP `frame-ancestors` hoặc `X-Frame-Options`.
|
|
42
|
+
- `Referrer-Policy` đã được đặt.
|
|
43
|
+
- Cookie cho session: `Secure`, `HttpOnly`, và một `SameSite` phù hợp.
|
|
44
|
+
- CORS: không có origin dạng ký tự đại diện đi kèm thông tin đăng nhập; các origin được phép khớp với danh sách
|
|
45
|
+
đã định.
|
|
46
|
+
- Không có header tiết lộ phiên bản hay stack trace trong các phản hồi lỗi.
|
|
47
|
+
|
|
48
|
+
Hãy viết những cái này thành test tự động (test e2e hay test API) khi dự án muốn giữ chúng lại.
|
|
49
|
+
|
|
50
|
+
## Test luồng xác thực
|
|
51
|
+
|
|
52
|
+
- Truy cập chưa đăng nhập vào trang và API được bảo vệ thì bị từ chối hoặc bị chuyển hướng.
|
|
53
|
+
- Người dùng A không đọc hay sửa được tài nguyên của người dùng B bằng cách đổi một ID (IDOR).
|
|
54
|
+
- Một người dùng không có vai trò thì không tới được trang admin hay gọi được API admin trực tiếp, chứ không
|
|
55
|
+
phải chỉ chặn bằng cách ẩn nút.
|
|
56
|
+
- Logout làm session mất hiệu lực; cookie hay token session cũ thôi hoạt động.
|
|
57
|
+
- Token đã hết hạn hoặc bị can thiệp thì bị từ chối.
|
|
58
|
+
- Token đặt lại mật khẩu chỉ dùng được một lần và có hết hạn.
|
|
59
|
+
- Endpoint đăng nhập và đặt lại mật khẩu có giới hạn tần suất với các lần thử lặp lại (hãy test bằng một số nhỏ
|
|
60
|
+
request, không phải một lượt dò vét cạn).
|
|
61
|
+
- Thông báo lỗi không tiết lộ việc một tài khoản có tồn tại hay không, theo chính sách của dự án.
|
|
62
|
+
- Request làm đổi state phải có bảo vệ CSRF khi việc xác thực dựa vào cookie.
|
|
63
|
+
|
|
64
|
+
## Kiểm việc xử lý dữ liệu nhập
|
|
65
|
+
|
|
66
|
+
- Dữ liệu người dùng nhập được phản chiếu lại thì phải được escape trong trang đã render (hãy gửi một dấu hiệu vô hại,
|
|
67
|
+
ví dụ một chuỗi có dấu ngoặc nhọn và dấu nháy, rồi kiểm xem nó render ra như chữ).
|
|
68
|
+
- Tải file lên thì từ chối các loại không được phép và file quá lớn.
|
|
69
|
+
- Tham số chuyển hướng chỉ nhận những đích được phép.
|
|
70
|
+
- API từ chối những field ngoài dự kiến có thể đặt được các thuộc tính đặc quyền.
|
|
71
|
+
|
|
72
|
+
## Báo cáo
|
|
73
|
+
|
|
74
|
+
- Môi trường đã test và việc cho phép tương ứng.
|
|
75
|
+
- Từng kiểm tra: pass, fail, hay chưa chạy kèm lý do.
|
|
76
|
+
- Các phát hiện kèm mức nghiêm trọng, endpoint hay trang bị ảnh hưởng, cách tái hiện tối thiểu, và một
|
|
77
|
+
chủ sở hữu được gợi ý (backend-development, frontend-development, hay security-review).
|
|
78
|
+
- Các cảnh báo bảo mật của phụ thuộc kèm đường nâng cấp, nhưng không tự áp dụng chúng.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Test unit và component
|
|
2
|
+
|
|
3
|
+
Đọc khi viết test unit hay component, mock, hay snapshot cho code web.
|
|
4
|
+
|
|
5
|
+
Ví dụ dùng Vitest hoặc Jest với truy vấn kiểu Testing Library; Vue Test Utils,
|
|
6
|
+
Svelte Testing Library, và Angular TestBed có cái tương đương. Hãy dùng runner,
|
|
7
|
+
môi trường (jsdom, happy-dom, hay chế độ browser thật), và file setup của dự án.
|
|
8
|
+
|
|
9
|
+
## Test unit
|
|
10
|
+
|
|
11
|
+
- Nhắm vào logic thuần: định dạng, parse, validate, reducer, máy trạng thái,
|
|
12
|
+
selector, hàm tiện ích.
|
|
13
|
+
- Ca dạng bảng cho các biến thể dữ liệu nhập; gồm cả giá trị biên, giá trị rỗng, và
|
|
14
|
+
dữ liệu nhập không hợp lệ.
|
|
15
|
+
- Không cần DOM hay mạng; nếu một test unit cần nhiều mock, có thể code cần một
|
|
16
|
+
đường tách, hoặc test đó thuộc về một tầng khác.
|
|
17
|
+
- Kiểm soát thời gian và tính ngẫu nhiên bằng fake timer của runner hoặc đồng hồ được tiêm vào;
|
|
18
|
+
khôi phục chúng sau mỗi test.
|
|
19
|
+
|
|
20
|
+
## Test component
|
|
21
|
+
|
|
22
|
+
- Render component với props thực tế và các provider nó cần (router,
|
|
23
|
+
theme, query client, i18n) qua một helper test dùng chung nếu dự án có.
|
|
24
|
+
- Tương tác như một người dùng: gõ chữ, bấm, và hành động bàn phím kiểu user-event
|
|
25
|
+
chứ không phát ra các event tổng hợp ở tầng thấp.
|
|
26
|
+
- Truy vấn theo vai trò, nhãn, và chữ; chỉ dùng test ID khi không có gì truy cập được.
|
|
27
|
+
- Khẳng định những gì người dùng thấy hoặc những gì component phát ra, không khẳng định state nội bộ,
|
|
28
|
+
phương thức của instance, hay hook riêng tư.
|
|
29
|
+
- Bao phủ từng trạng thái thấy được: loading, rỗng, lỗi, thành công, disabled, và lỗi
|
|
30
|
+
validate.
|
|
31
|
+
- Dùng truy vấn bất đồng bộ (`findBy...`, `waitFor`) cho các cập nhật bất đồng bộ; không bao giờ dùng
|
|
32
|
+
khoảng chờ cố định.
|
|
33
|
+
|
|
34
|
+
## Mock
|
|
35
|
+
|
|
36
|
+
- Mock ở các biên: mạng (mock ở mức request, như handler kiểu MSW
|
|
37
|
+
hoặc công cụ của dự án), timer, các API browser mà môi trường test không có.
|
|
38
|
+
- Ưu tiên một mock thực tế của tầng HTTP hơn là mock từng module mà component
|
|
39
|
+
import.
|
|
40
|
+
- Không mock chính unit đang được test hay mock bản thân framework.
|
|
41
|
+
- Reset mock và handler giữa các test; những request không được xử lý và ngoài dự kiến thì nên làm
|
|
42
|
+
test fail.
|
|
43
|
+
- Giữ dữ liệu mock sát với hình dạng API thật, tốt nhất là lấy từ type hay fixture dùng chung.
|
|
44
|
+
|
|
45
|
+
## Snapshot
|
|
46
|
+
|
|
47
|
+
- Tránh snapshot DOM lớn; chúng vỡ khi markup đổi dù chẳng liên quan, và rồi bị
|
|
48
|
+
chấp nhận mà không ai review.
|
|
49
|
+
- Dùng snapshot inline nhỏ cho những output serialize ổn định (một chuỗi đã định dạng, một
|
|
50
|
+
config được sinh ra).
|
|
51
|
+
- Hãy review mọi thay đổi snapshot như một thay đổi hành vi trước khi cập nhật nó.
|
|
52
|
+
|
|
53
|
+
## Cách ly và vệ sinh
|
|
54
|
+
|
|
55
|
+
- Mỗi test tự dựng state của nó; không phụ thuộc thứ tự.
|
|
56
|
+
- Dọn các component đã render, timer, và thay đổi toàn cục (runner thường tự
|
|
57
|
+
dọn; hãy kiểm lại với các setup tự tạo).
|
|
58
|
+
- Không dùng mạng thật, không ghi file ngoài thư mục tạm, không có secret thật.
|
|
59
|
+
- Giữ test nhanh; bộ test chậm sẽ bị bỏ qua. Đánh dấu test chậm theo cách dự án làm.
|
|
60
|
+
|
|
61
|
+
## Độ bao phủ
|
|
62
|
+
|
|
63
|
+
- Dùng báo cáo coverage để tìm những nhánh chưa được test trong code đã đổi, không dùng nó như một
|
|
64
|
+
chỉ tiêu phải đạt. Không thêm test không có assertion để nâng con số.
|
|
65
|
+
|
|
66
|
+
## Lưu ý về môi trường
|
|
67
|
+
|
|
68
|
+
- jsdom và những môi trường tương tự không có layout, không có CSS thật, và thiếu một số API
|
|
69
|
+
(IntersectionObserver, ResizeObserver, matchMedia); hãy stub chúng trong setup hoặc test
|
|
70
|
+
những hành vi phụ thuộc layout trên browser thật (e2e hoặc chế độ browser).
|
|
71
|
+
- Server component hay loader của framework có thể cần chính tiện ích test của
|
|
72
|
+
framework hoặc cần một test e2e; hãy xem tài liệu framework cho phiên bản đã cài.
|
|
73
|
+
|
|
74
|
+
## Accessibility trong test component
|
|
75
|
+
|
|
76
|
+
- Truy vấn theo vai trò vốn đã phát hiện được việc thiếu tên và thiếu vai trò.
|
|
77
|
+
- Nếu dự án dùng một matcher kiểu axe, hãy chạy nó trên các trạng thái đã render với dialog
|
|
78
|
+
và menu đang mở.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"main": ["goal-griller", "xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits", "compact", "curate"],
|
|
3
|
-
"lead": ["xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits"],
|
|
4
|
-
"peer": ["xia", "bug-loop", "smart-commits"],
|
|
2
|
+
"main": ["goal-griller", "xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits", "compact", "curate", "skill-authoring", "architecture-docs", "feature-architecture", "test-strategy", "safe-refactor", "security-review", "release-readiness"],
|
|
3
|
+
"lead": ["xia", "sequence-execution-plan", "prompt-leverage", "bug-loop", "smart-commits", "architecture-docs", "feature-architecture", "test-strategy", "safe-refactor", "security-review", "release-readiness"],
|
|
4
|
+
"peer": ["xia", "bug-loop", "smart-commits", "feature-architecture", "test-strategy", "safe-refactor"],
|
|
5
5
|
"oracle": [],
|
|
6
|
-
"reviewer": [],
|
|
6
|
+
"reviewer": ["security-review", "release-readiness"],
|
|
7
7
|
"supervisor": []
|
|
8
8
|
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: architecture-docs
|
|
3
|
+
description: "Tạo và bảo trì tài liệu kiến trúc dựa trên bằng chứng trong repository: tổng quan, ranh giới, phụ thuộc giữa các module, luồng dữ liệu, API contract, quyết định, ADR, sơ đồ Mermaid và quy ước. Dùng khi tài liệu còn thiếu, đã lỗi thời, hoặc khi một thay đổi làm đổi ranh giới hay contract. Không dùng để thiết kế feature mới (dùng feature-architecture) hay nghiên cứu khả năng tái dùng (dùng xia)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Ghi lại kiến trúc mà code chứng minh được
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
- Project chưa có tổng quan kiến trúc, hoặc bản đang có mâu thuẫn với code.
|
|
10
|
+
- Một thay đổi thêm, bỏ hoặc di chuyển ranh giới module, public API, schema hay luồng dữ liệu.
|
|
11
|
+
- Một quyết định về công nghệ hoặc cấu trúc đã được xác nhận và cần một ADR.
|
|
12
|
+
- Người bảo trì tài liệu hoặc reviewer được yêu cầu kiểm tra tài liệu kiến trúc xem có lệch.
|
|
13
|
+
|
|
14
|
+
## Không dùng cho
|
|
15
|
+
- Thiết kế cách xây một feature mới: dùng feature-architecture.
|
|
16
|
+
- So sánh thư viện hay tìm code tái dùng được: dùng xia.
|
|
17
|
+
- Hướng dẫn người dùng, README và changelog không liên quan tới cấu trúc.
|
|
18
|
+
- Đoán ý định của code mà không ai giải thích được: hãy ghi lại một câu hỏi mở.
|
|
19
|
+
|
|
20
|
+
## Điều kiện tiên quyết
|
|
21
|
+
- Đọc ALP.md và mọi index tài liệu, cây `docs/` hoặc hướng dẫn đóng góp đang có.
|
|
22
|
+
- Biết rõ các đường dẫn sở hữu (owned paths): người ghi chỉ sửa các file tài liệu được giao;
|
|
23
|
+
role chỉ đọc thì báo cáo.
|
|
24
|
+
- Xác định thay đổi hoặc câu hỏi đã kích hoạt công việc này; giới hạn phạm vi tài liệu theo đó.
|
|
25
|
+
|
|
26
|
+
## Quy trình
|
|
27
|
+
1. **Tìm bố cục.** Theo bố cục tài liệu project đang dùng. Nếu chưa có, hãy đề xuất
|
|
28
|
+
`docs/architecture/overview.md`, `boundaries.md`, `conventions.md` và
|
|
29
|
+
`decisions/NNNN-title.md`, và xác nhận trước khi tạo cấu trúc cấp cao mới.
|
|
30
|
+
2. **Thu bằng chứng.** Đọc manifest, entry point, config build và deploy, file khai báo
|
|
31
|
+
route, schema, đồ thị import và test của khu vực trong phạm vi. Ghi mỗi dữ kiện kèm
|
|
32
|
+
đường dẫn file chứng minh nó.
|
|
33
|
+
3. **Tổng quan.** Mục đích, các đơn vị runtime (process, package, service), chúng khởi động
|
|
34
|
+
và nói chuyện với nhau ra sao, và các hệ thống bên ngoài. Một trang ngắn.
|
|
35
|
+
4. **Ranh giới và phụ thuộc.** Trách nhiệm của từng module, nó được import gì, ai import nó,
|
|
36
|
+
và bề mặt public mà người khác dựa vào. Ghi lại các vòng lặp và chỗ rò rỉ phát hiện được.
|
|
37
|
+
5. **Luồng dữ liệu và contract.** Truy vết đường đi chính của request hoặc job từ đầu tới cuối.
|
|
38
|
+
Với mỗi API, event hay schema, dẫn file định nghĩa và quy tắc đánh version của nó.
|
|
39
|
+
6. **Quyết định.** Ghi lại các lựa chọn công nghệ và cấu trúc đã được xác nhận, kèm bằng chứng
|
|
40
|
+
hoặc người đã xác nhận. Chỉ viết ADR khi đạt tiêu chí trong tài liệu tham chiếu về ADR;
|
|
41
|
+
nếu không thì một dòng trong phần tổng quan là đủ.
|
|
42
|
+
7. **Sơ đồ.** Chỉ thêm sơ đồ Mermaid ở chỗ chữ khó theo dõi hơn. Giữ sơ đồ nhỏ và suy ra từ
|
|
43
|
+
code: mỗi node ứng với một đường dẫn thật.
|
|
44
|
+
8. **Quy ước.** Ghi lại các mẫu đặt tên, phân lớp, xử lý lỗi, logging và test mà code đã theo
|
|
45
|
+
một cách nhất quán, mỗi mẫu kèm một đường dẫn ví dụ.
|
|
46
|
+
9. **Điều chưa biết.** Đánh dấu mọi thứ chưa chứng minh được là "Unverified" và liệt kê các câu
|
|
47
|
+
hỏi mở kèm người có thể trả lời. Chuyển quyết định lên trên; đừng tự bịa ra.
|
|
48
|
+
10. **Kiểm tra.** Xác minh link, đường dẫn và ví dụ (xem Kiểm chứng), rồi handoff kèm danh sách
|
|
49
|
+
bằng chứng.
|
|
50
|
+
|
|
51
|
+
## Ràng buộc
|
|
52
|
+
- Chỉ mô tả những gì code, config, test hoặc quyết định đã xác nhận chứng minh được. Không
|
|
53
|
+
trình bày kiến trúc mong muốn như thể nó đang là hiện trạng.
|
|
54
|
+
- Dẫn bằng chứng bằng đường dẫn file tương đối, kèm tên symbol hoặc khoảng dòng khi hữu ích.
|
|
55
|
+
- Giữ tài liệu đồng bộ: một thay đổi làm đổi ranh giới hay contract phải cập nhật tài liệu của
|
|
56
|
+
nó trong cùng thay đổi đó. Thay đổi nội bộ nhỏ không cần ADR và thường không cần sửa tài
|
|
57
|
+
liệu.
|
|
58
|
+
- Đừng refactor code cho khớp tài liệu; hãy báo cáo chỗ lệch.
|
|
59
|
+
- Các role chỉ đọc (architect, reviewer) trả về phát hiện và bản văn đề xuất, không sửa file.
|
|
60
|
+
|
|
61
|
+
## Kiểm chứng
|
|
62
|
+
- Mọi link tương đối và đường dẫn được dẫn đều phân giải được; chạy bộ kiểm tra link của
|
|
63
|
+
project nếu có, nếu không thì kiểm từng đường dẫn có tồn tại.
|
|
64
|
+
- Ví dụ code và câu lệnh trong tài liệu chạy hoặc biên dịch được trên cây hiện tại, hoặc được
|
|
65
|
+
đánh dấu là minh hoạ.
|
|
66
|
+
- Mỗi node và mũi nối trong sơ đồ khớp với một import, lời gọi, route hay mục config.
|
|
67
|
+
- Không có phát biểu nào thiếu bằng chứng hoặc thiếu dấu "Unverified".
|
|
68
|
+
|
|
69
|
+
## Xử lý khi thất bại
|
|
70
|
+
- Bằng chứng xung đột (code nói một đằng, config hoặc tài liệu nói một nẻo): ghi lại cái đang
|
|
71
|
+
chạy, nêu xung đột thành câu hỏi mở, và báo cáo.
|
|
72
|
+
- Khu vực quá lớn so với việc được giao: ghi lại ranh giới và entry point, liệt kê các module
|
|
73
|
+
chưa phủ, rồi trả về; đừng mở rộng phạm vi.
|
|
74
|
+
- Cần một quyết định nhưng chưa được xác nhận: soạn ADR ở trạng thái `Proposed` và chuyển cho
|
|
75
|
+
main.
|
|
76
|
+
- Bố cục tài liệu hiện tại không rõ hoặc đang tranh cãi: hỏi trước khi cấu trúc lại.
|
|
77
|
+
|
|
78
|
+
## Tài liệu tham chiếu
|
|
79
|
+
- [references/evidence-rules.md](references/evidence-rules.md) — đọc khi thu dữ kiện và dẫn nguồn (bước 2-5, 9).
|
|
80
|
+
- [references/adr.md](references/adr.md) — đọc khi quyết định một thay đổi có cần ADR hay không, và khi viết ADR (bước 6).
|
|
81
|
+
- [references/diagrams.md](references/diagrams.md) — đọc khi thêm hoặc cập nhật sơ đồ Mermaid (bước 7).
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Bản ghi quyết định kiến trúc (ADR)
|
|
2
|
+
|
|
3
|
+
Khung ADR dưới đây giữ tiêu đề tiếng ANH có chủ ý (t-d11c mục 3, người dùng quyết định
|
|
4
|
+
2026-11-06): đó là hình dạng một artifact mà tooling khác đọc, không phải prose hướng dẫn cách
|
|
5
|
+
làm việc. Phần nội dung dưới mỗi tiêu đề viết bằng ngôn ngữ của project.
|
|
6
|
+
|
|
7
|
+
Đọc khi phán xét một thay đổi có đáng viết ADR, khi viết ADR, hoặc khi đổi status của một ADR.
|
|
8
|
+
|
|
9
|
+
## Khi nào nên viết ADR
|
|
10
|
+
Viết khi có ít nhất một điều sau đúng:
|
|
11
|
+
- Lựa chọn đó đắt khi phải đảo ngược: nơi lưu dữ liệu, protocol, kiểu public API, runtime,
|
|
12
|
+
framework, mô hình triển khai.
|
|
13
|
+
- Nó làm đổi một ranh giới module hoặc hướng phụ thuộc được cho phép.
|
|
14
|
+
- Nó ảnh hưởng tới tính tương thích với bên tiêu thụ, dữ liệu đã lưu hoặc các nền tảng được hỗ
|
|
15
|
+
trợ.
|
|
16
|
+
- Đã có các phương án khác hợp lý được cân nhắc nghiêm túc rồi loại bỏ.
|
|
17
|
+
- Nếu không ghi lại thì cả team sẽ tranh lại chuyện đó.
|
|
18
|
+
|
|
19
|
+
Bỏ qua ADR với: refactor trong một module, cập nhật patch của dependency, chuyện đặt tên,
|
|
20
|
+
helper cục bộ, bản sửa lỗi đưa hành vi về đúng contract đã ghi, và các lựa chọn đã bị một ADR
|
|
21
|
+
hiện có quy định hoàn toàn. Một câu trong tài liệu liên quan là đủ.
|
|
22
|
+
|
|
23
|
+
## File và cách đánh số
|
|
24
|
+
- Theo vị trí và cách đánh số ADR project đang dùng. Mặc định:
|
|
25
|
+
`docs/architecture/decisions/NNNN-short-title.md`, bốn chữ số, lấy số trống kế tiếp.
|
|
26
|
+
- Không bao giờ đánh số lại hay xoá một ADR; hãy thay thế nó bằng ADR mới (supersede).
|
|
27
|
+
|
|
28
|
+
## Mẫu
|
|
29
|
+
```markdown
|
|
30
|
+
# NNNN. Short decision title
|
|
31
|
+
|
|
32
|
+
- Status: Proposed | Accepted | Superseded by NNNN | Deprecated
|
|
33
|
+
- Date: YYYY-MM-DD
|
|
34
|
+
- Deciders: who confirmed it (role or name as the project records it)
|
|
35
|
+
|
|
36
|
+
## Context
|
|
37
|
+
The forces and constraints, with evidence paths. What problem forces a choice now.
|
|
38
|
+
|
|
39
|
+
## Decision
|
|
40
|
+
The choice, stated as one or two sentences in active voice.
|
|
41
|
+
|
|
42
|
+
## Alternatives
|
|
43
|
+
- Option: why it was not chosen.
|
|
44
|
+
|
|
45
|
+
## Consequences
|
|
46
|
+
What gets easier, what gets harder, follow-up work, and what to watch.
|
|
47
|
+
|
|
48
|
+
## Evidence
|
|
49
|
+
Files, tests, benchmarks or discussions that support the context and decision.
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Vòng đời của status
|
|
53
|
+
| Status | Ý nghĩa | Ai chuyển |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| Proposed | Đã soạn, chưa được xác nhận | Bất kỳ người ghi; chuyển cho main để ra quyết định |
|
|
56
|
+
| Accepted | Đã được người sở hữu quyết định xác nhận | Main, sau khi người dùng hoặc người sở hữu có thẩm quyền xác nhận |
|
|
57
|
+
| Superseded by NNNN | Đã bị thay; giữ nguyên nội dung, link sang ADR mới | Người viết ADR mới |
|
|
58
|
+
| Deprecated | Không còn áp dụng, không có gì thay thế | Main, kèm lý do trong một ghi chú có ngày |
|
|
59
|
+
|
|
60
|
+
- Một agent không bao giờ tự đánh đề xuất của mình là Accepted khi chưa có xác nhận đó.
|
|
61
|
+
- Sửa một ADR đã Accepted chỉ được giới hạn ở lỗi chính tả và link; quyết định thay đổi là một
|
|
62
|
+
ADR mới.
|