@anhlp/alp-core 0.0.1-beta.6 → 0.0.1-beta.8
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.d.ts +5 -6
- package/dist/bridges.js +3 -4
- 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 +37 -45
- package/dist/packaged.js +42 -156
- 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 +6 -6
- package/dist/providers.d.ts +2 -5
- package/dist/providers.js +22 -6
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/template-path.d.ts +2 -2
- package/dist/template-path.js +0 -5
- package/dist/types.d.ts +2 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/validation.js +6 -6
- package/package.json +18 -2
- package/src/bridges.js +9 -10
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packaged.js +74 -191
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +7 -7
- package/src/providers.js +22 -8
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/template-path.js +1 -6
- package/src/types.d.ts +2 -0
- package/src/upgrade.js +54 -6
- package/src/validation.js +8 -7
- 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,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: databases
|
|
3
|
+
description: "Thiết kế schema, viết migration và backfill an toàn, và tối ưu truy vấn cho database quan hệ (PostgreSQL, MySQL, SQLite) và document store, dùng công cụ hiện có của dự án. Dùng khi thêm bảng hay collection, đổi constraint hay index, migrate dữ liệu, hoặc sửa truy vấn chậm. Không dùng cho logic API hay service (backend-development)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Cơ sở dữ liệu
|
|
7
|
+
|
|
8
|
+
## Khi nào dùng
|
|
9
|
+
|
|
10
|
+
- Thêm hoặc đổi bảng, cột, collection, constraint, hay index.
|
|
11
|
+
- Viết một migration schema, một backfill dữ liệu, hay một kế hoạch rollback.
|
|
12
|
+
- Chẩn đoán một truy vấn chậm, mẫu N+1, chờ lock, hay deadlock.
|
|
13
|
+
- Chọn biên transaction hoặc mức isolation cho một thao tác dữ liệu.
|
|
14
|
+
- Một cố vấn (advisor) hoặc reviewer chỉ đọc được hỏi để đánh giá một schema hay migration (chỉ
|
|
15
|
+
tư vấn).
|
|
16
|
+
|
|
17
|
+
## Không dùng cho
|
|
18
|
+
|
|
19
|
+
- Endpoint, logic service, auth, hay map lỗi: dùng backend-development.
|
|
20
|
+
- Cấp phát hạ tầng, backup, replication, hay hosting database: dùng devops.
|
|
21
|
+
- Một test fail hay một regression dữ liệu chưa rõ nguyên nhân: dùng bug-loop.
|
|
22
|
+
- Chọn engine database, ORM, hay công cụ migration mới: quyết định của owner.
|
|
23
|
+
|
|
24
|
+
## Điều kiện tiên quyết
|
|
25
|
+
|
|
26
|
+
- Đườ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.
|
|
27
|
+
- Engine và major version, lớp ORM hay query, và công cụ migration, đọc từ manifest,
|
|
28
|
+
config, và thư mục migration hiện có.
|
|
29
|
+
- Quy ước migration đang có: cách đặt tên, thứ tự, up/down hay chỉ-tiến, cách
|
|
30
|
+
migration chạy trong test và khi deploy.
|
|
31
|
+
- Một database local hoặc test để thao tác lên. Đừng bao giờ dùng database dùng chung hay
|
|
32
|
+
production.
|
|
33
|
+
|
|
34
|
+
## Quy trình
|
|
35
|
+
|
|
36
|
+
1. Nêu yêu cầu dữ liệu: thực thể, quan hệ, cardinality, field bắt buộc, tính duy nhất,
|
|
37
|
+
thời gian lưu, và các đường đọc và ghi chính.
|
|
38
|
+
2. Đọc schema hiện tại (migration, model, hay một dump của database test), không chỉ
|
|
39
|
+
các model ORM; chúng có thể lệch.
|
|
40
|
+
3. Thiết kế thay đổi. Đặt quy tắc toàn vẹn vào trong database ở nơi engine hỗ trợ:
|
|
41
|
+
NOT NULL, foreign key, unique, check constraint. Đọc
|
|
42
|
+
schema-and-migrations.md.
|
|
43
|
+
4. Lập kế hoạch triển khai cho bảng đang có dữ liệu sống: mở rộng, migrate dữ liệu,
|
|
44
|
+
chuyển code, thu hẹp. Mỗi bước phải an toàn khi cả bản ứng dụng cũ và mới
|
|
45
|
+
cùng chạy.
|
|
46
|
+
5. Đánh giá locking: câu lệnh có ghi lại cả bảng hay giữ một lock mạnh không? Dùng
|
|
47
|
+
dạng online của engine (ví dụ dựng index concurrent trong PostgreSQL) và một lock
|
|
48
|
+
timeout khi công cụ của dự án cho phép.
|
|
49
|
+
6. Viết migration bằng công cụ của dự án. Làm nó đảo được, hoặc ghi lại vì sao nó chỉ
|
|
50
|
+
tiến và cách khôi phục.
|
|
51
|
+
7. Viết backfill thành các bước riêng, chia lô, có thể tiếp tục, không nằm trong
|
|
52
|
+
migration schema khi bảng lớn.
|
|
53
|
+
8. Với việc tối ưu truy vấn, đo trước: ghi lại truy vấn, tham số của nó, và plan.
|
|
54
|
+
Đọc query-performance.md. Đổi một thứ, rồi đo lại trên dữ liệu tương đương.
|
|
55
|
+
9. Chạy migration lên, xuống (nếu được hỗ trợ), rồi lên lại trên một database test,
|
|
56
|
+
sau đó chạy test của dự án.
|
|
57
|
+
10. Handoff: các file migration, thứ tự triển khai, ước lượng lock và thời gian chạy, kế hoạch
|
|
58
|
+
backfill, đường rollback, plan trước và sau cho thay đổi truy vấn, quyết định còn mở.
|
|
59
|
+
|
|
60
|
+
Một agent chỉ đọc chạy bước 1-5 và 8 đối chiếu với đề xuất hoặc schema hiện tại, rồi
|
|
61
|
+
báo các rủi ro và một thiết kế được khuyến nghị thay vì tự sửa.
|
|
62
|
+
|
|
63
|
+
## Ràng buộc
|
|
64
|
+
|
|
65
|
+
- Theo engine, ORM, công cụ migration và cách đặt tên hiện có của dự án trước đã.
|
|
66
|
+
Prisma, Drizzle, SQLAlchemy/Alembic, Django migrations, golang-migrate, hay file SQL
|
|
67
|
+
thuần là ví dụ, không phải khuyến nghị.
|
|
68
|
+
- Không thêm dependency, extension, hay data store mới mà không có quyết định của
|
|
69
|
+
owner. Không tự cài.
|
|
70
|
+
- Đừng bao giờ chạy migration, backfill, hay ghi tạm lên database dùng chung, staging,
|
|
71
|
+
hay production; đó là một bước deploy của người sở hữu nó.
|
|
72
|
+
- Đừng bao giờ sửa một migration đã được áp dụng ngoài database local của bạn;
|
|
73
|
+
hãy thêm một migration mới.
|
|
74
|
+
- Thay đổi phá hủy (xóa hay đổi tên cột hoặc bảng, siết kiểu dữ liệu, xóa dữ liệu)
|
|
75
|
+
cần quyết định tường minh của owner và một kế hoạch rollback đã ghi lại.
|
|
76
|
+
- Đừng đọc credential hay dữ liệu cá nhân thật; dùng dữ liệu test và config ví dụ.
|
|
77
|
+
- Ở trong đường dẫn sở hữu. Skill này không cho quyền deploy hay release.
|
|
78
|
+
|
|
79
|
+
## Kiểm chứng
|
|
80
|
+
|
|
81
|
+
- Migration áp sạch lên một database rỗng và lên một database có dữ liệu đại diện.
|
|
82
|
+
- Migration xuống (nếu được hỗ trợ) phục hồi schema trước đó; lên lại áp được.
|
|
83
|
+
- Test của dự án pass với schema mới.
|
|
84
|
+
- Constraint từ chối đúng dữ liệu không hợp lệ mà nó phải từ chối (một test chứng minh).
|
|
85
|
+
- Với thay đổi về hiệu năng: plan và thời gian trước và sau trên dữ liệu tương đương,
|
|
86
|
+
kèm điều kiện đã ghi lại.
|
|
87
|
+
- Mỗi bước triển khai đều tương thích với bản ứng dụng đang chạy.
|
|
88
|
+
|
|
89
|
+
## Xử lý khi thất bại
|
|
90
|
+
|
|
91
|
+
- Migration fail trên dữ liệu hiện có: dừng, báo mẫu của các dòng vi phạm (không phải
|
|
92
|
+
nội dung của chúng), và đề xuất một bước dọn dẹp hoặc một constraint theo giai đoạn.
|
|
93
|
+
- Một lock hoặc một lần ghi lại dài là không tránh được: báo ước lượng và chuyển lên
|
|
94
|
+
quyết định về cửa sổ bảo trì.
|
|
95
|
+
- Không có database test: báo khoảng trống đó; đừng khai là migration đã chạy.
|
|
96
|
+
- Plan khác nhau giữa dữ liệu local và dữ liệu giống production: hãy nói ra; đừng khái quát
|
|
97
|
+
hóa.
|
|
98
|
+
- Một model ORM và schema thật không khớp: báo chỗ lệch trước khi đổi bên nào.
|
|
99
|
+
|
|
100
|
+
## Tài liệu tham khảo
|
|
101
|
+
|
|
102
|
+
- [references/schema-and-migrations.md](references/schema-and-migrations.md) — đọc khi thiết kế bảng, constraint, hay hình dạng document, hoặc khi lập kế hoạch migration expand/contract, backfill, tính đảo được, hay rủi ro lock (bước 3-7).
|
|
103
|
+
- [references/query-performance.md](references/query-performance.md) — đọc khi thêm index, đọc output EXPLAIN, sửa N+1, phân trang, hay chọn transaction và isolation (bước 8).
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Hiệu năng truy vấn
|
|
2
|
+
|
|
3
|
+
Đọc khi thêm index, đọc output EXPLAIN, sửa N+1, phân trang, hay
|
|
4
|
+
chọn transaction và isolation.
|
|
5
|
+
|
|
6
|
+
Hãy đo trước khi đổi bất cứ thứ gì. Ghi lại chính xác truy vấn kèm tham số của nó
|
|
7
|
+
(query log của ORM hoặc slow-query log của database trong môi trường test), số dòng
|
|
8
|
+
liên quan, và plan. Đo lại trên dữ liệu tương đương sau mỗi thay đổi.
|
|
9
|
+
|
|
10
|
+
## Đọc plan
|
|
11
|
+
|
|
12
|
+
- PostgreSQL: `EXPLAIN (ANALYZE, BUFFERS)`; MySQL: `EXPLAIN ANALYZE` (8.0.18+) hoặc
|
|
13
|
+
`EXPLAIN FORMAT=TREE`; SQLite: `EXPLAIN QUERY PLAN`. ANALYZE chạy thật truy vấn:
|
|
14
|
+
chỉ chạy nó trên database test, và bọc các lệnh ghi trong transaction rồi rollback.
|
|
15
|
+
- Hãy tìm: sequential scan hay full scan trên bảng lớn, số dòng ước lượng lệch xa số
|
|
16
|
+
dòng thực tế (statistics cũ), sort hay hash tràn ra đĩa, nested loop trên input
|
|
17
|
+
lớn, và filter chỉ áp sau khi đã lấy nhiều dòng.
|
|
18
|
+
- Plan phụ thuộc khối lượng dữ liệu và statistics. Một plan trên mười dòng nói lên rất
|
|
19
|
+
ít; hãy dùng khối lượng đại diện hoặc nói rằng kết quả chỉ là tạm thời.
|
|
20
|
+
|
|
21
|
+
## Index
|
|
22
|
+
|
|
23
|
+
- Index các cột dùng trong WHERE có tính chọn lọc, JOIN, và ORDER BY trên bảng lớn.
|
|
24
|
+
- Thứ tự cột trong composite index: cột so sánh bằng trước, rồi cột khoảng hay cột
|
|
25
|
+
sắp xếp. Một index trên (a, b) phục vụ filter theo a, hoặc a và b, không phải b một mình.
|
|
26
|
+
- Một covering index (bao cả các cột được chọn) có thể tránh phải tra lại bảng cho các
|
|
27
|
+
lượt đọc nóng.
|
|
28
|
+
- Index một phần hoặc có filter phù hợp với truy vấn trên một tập con nhỏ (`WHERE
|
|
29
|
+
deleted_at IS NULL`).
|
|
30
|
+
- Hàm áp lên một cột (`lower(email)`) vô hiệu hóa index thường; hãy dùng index trên
|
|
31
|
+
biểu thức hoặc lưu một cột đã chuẩn hóa.
|
|
32
|
+
- Ký tự đại diện ở đầu (`LIKE '%x'`) không dùng được index B-tree; full-text search là
|
|
33
|
+
quyết định của owner nếu cần.
|
|
34
|
+
- Mỗi index làm ghi chậm hơn và chiếm dung lượng. Chỉ xóa index không dùng hay trùng
|
|
35
|
+
lặp khi có bằng chứng là nó không được dùng.
|
|
36
|
+
- Document store: tạo index khớp với hình dạng truy vấn và thứ tự sắp xếp; kiểm tra
|
|
37
|
+
output explain xem có collection scan không.
|
|
38
|
+
|
|
39
|
+
## Truy vấn N+1
|
|
40
|
+
|
|
41
|
+
- Dấu hiệu: một truy vấn cho danh sách, rồi một truy vấn cho mỗi phần tử. Tìm nó trong
|
|
42
|
+
query log hoặc bằng cách đếm số truy vấn trong một test.
|
|
43
|
+
- Sửa bằng eager loading của ORM hoặc một truy vấn `WHERE id IN (...)` theo lô; trong
|
|
44
|
+
GraphQL hay các resolver tương tự, dùng một loader gom lô theo từng request.
|
|
45
|
+
- Thêm một test assert số truy vấn cho endpoint khi dự án có helper cho việc đó.
|
|
46
|
+
- Đừng lấy quá nhiều: chỉ load các cột và quan hệ mà người gọi dùng.
|
|
47
|
+
|
|
48
|
+
## Phân trang
|
|
49
|
+
|
|
50
|
+
- Phân trang keyset: `WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC,
|
|
51
|
+
id DESC LIMIT $n`, dựa trên một index trên cùng các cột đó. Chi phí mỗi trang là hằng.
|
|
52
|
+
- OFFSET quét rồi bỏ các dòng bị nhảy qua; chi phí tăng theo độ sâu. Chấp nhận được
|
|
53
|
+
với tập nhỏ.
|
|
54
|
+
- Luôn đưa một khóa phá thế bằng duy nhất vào thứ tự sắp xếp.
|
|
55
|
+
- `COUNT(*)` chính xác trên bảng lớn thì đắt; hãy dùng ước lượng hoặc bỏ nó khi sản
|
|
56
|
+
phẩm cho phép.
|
|
57
|
+
|
|
58
|
+
## Transaction
|
|
59
|
+
|
|
60
|
+
- Giữ transaction ngắn. Không gọi mạng, không chờ người dùng, không vòng lặp lớn bên trong.
|
|
61
|
+
- Nhóm các lệnh ghi phải cùng thành công hoặc cùng thất bại; không gì khác.
|
|
62
|
+
- Lock các dòng theo một thứ tự nhất quán xuyên các đường code để tránh deadlock;
|
|
63
|
+
retry khi gặp lỗi deadlock hay serialization với số lần có giới hạn.
|
|
64
|
+
- Chỉ dùng `SELECT ... FOR UPDATE` (hoặc `SKIP LOCKED` cho job queue) ở nơi bạn buộc
|
|
65
|
+
phải tuần tự hóa truy cập vào các dòng cụ thể.
|
|
66
|
+
- Transaction chạy lâu chặn vacuum (PostgreSQL) và giữ lock; hãy để mắt tới chúng
|
|
67
|
+
trong các batch job.
|
|
68
|
+
|
|
69
|
+
## Mức isolation
|
|
70
|
+
|
|
71
|
+
| Mức | Ngăn được | Cần để ý |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| Read committed (mặc định của PostgreSQL) | dirty read | non-repeatable read, lost update |
|
|
74
|
+
| Repeatable read (mặc định của MySQL InnoDB) | non-repeatable read | write skew; gap lock của MySQL |
|
|
75
|
+
| Serializable | mọi bất thường | lỗi serialization phải được retry |
|
|
76
|
+
|
|
77
|
+
- Với đọc-sửa-ghi, hãy ưu tiên một cập nhật nguyên tử (`SET n = n + 1`), một cập nhật
|
|
78
|
+
có điều kiện kèm kiểm tra version, hoặc một row lock, hơn là nâng isolation toàn cục.
|
|
79
|
+
- SQLite tuần tự hóa các bên ghi; transaction ghi dài chặn các bên ghi khác.
|
|
80
|
+
|
|
81
|
+
## Các kiểm tra khác
|
|
82
|
+
|
|
83
|
+
- Luôn dùng truy vấn tham số hóa; chúng còn cho phép tái dùng plan.
|
|
84
|
+
- Kích thước connection pool nên vừa với giới hạn của database; nhiều kết nối hơn có
|
|
85
|
+
thể chậm hơn.
|
|
86
|
+
- Tránh `SELECT *` trên bảng rộng ở các đường nóng.
|
|
87
|
+
- Chỉ cache khi có một quy tắc vô hiệu hóa đã nêu rõ và có sự đồng thuận của owner.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Schema và migration
|
|
2
|
+
|
|
3
|
+
Đọc khi thiết kế bảng, constraint, hay hình dạng document, hoặc khi lập kế hoạch
|
|
4
|
+
migration expand/contract, backfill, tính đảo được, hay rủi ro lock.
|
|
5
|
+
|
|
6
|
+
## Đánh đổi khi chuẩn hóa
|
|
7
|
+
|
|
8
|
+
- Bắt đầu ở dạng chuẩn hóa (khoảng dạng chuẩn thứ ba): mỗi dữ kiện lưu một lần, liên
|
|
9
|
+
kết bằng khóa. Nó giữ việc ghi đơn giản và ngăn các bất thường khi cập nhật.
|
|
10
|
+
- Chỉ phi chuẩn hóa cho một nhu cầu đọc đã đo được: một bộ đếm, một tổng hợp được
|
|
11
|
+
cache, một field sao chép để tránh một join nóng. Ghi lại ai giữ bản sao đồng bộ
|
|
12
|
+
(trigger, cùng transaction, hay một job) và cách phát hiện lệch.
|
|
13
|
+
- Dùng cột JSON cho các thuộc tính thật sự không có schema hoặc thưa, không phải để
|
|
14
|
+
khỏi phải thiết kế các cột được truy vấn, lọc, hay ràng buộc.
|
|
15
|
+
- Document store: hình dạng document theo mẫu truy cập. Nhúng dữ liệu được đọc cùng
|
|
16
|
+
nhau và có kích thước giới hạn; tham chiếu dữ liệu dùng chung, lớn, hay không giới
|
|
17
|
+
hạn (mảng lớn lên vô hạn gây hại). Lên kế hoạch một field version schema khi hình
|
|
18
|
+
dạng sẽ còn thay đổi.
|
|
19
|
+
|
|
20
|
+
## Khóa và kiểu dữ liệu
|
|
21
|
+
|
|
22
|
+
- Một primary key cho mỗi bảng; theo kiểu ID của dự án (bigint identity, UUID/ULID).
|
|
23
|
+
Khóa UUIDv4 ngẫu nhiên làm phân mảnh index B-tree trên bảng lớn; ID có thứ tự theo
|
|
24
|
+
thời gian tránh được điều đó ở nơi dự án cho phép.
|
|
25
|
+
- Dùng kiểu chính xác: decimal hay số nguyên theo đơn vị nhỏ nhất cho tiền, timestamp
|
|
26
|
+
có múi giờ (hoặc UTC theo quy ước), enum hay check constraint cho các tập đóng, text
|
|
27
|
+
kèm một check độ dài thay vì giới hạn varchar tùy ý.
|
|
28
|
+
- Lưu thời gian theo UTC; chuyển đổi ở biên.
|
|
29
|
+
|
|
30
|
+
## Constraint
|
|
31
|
+
|
|
32
|
+
- Mặc định NOT NULL; chỉ cho nullable khi sự vắng mặt có ý nghĩa.
|
|
33
|
+
- Foreign key cho các quan hệ, với một hành vi ON DELETE được chọn có chủ đích
|
|
34
|
+
(restrict, cascade, set null).
|
|
35
|
+
- Unique constraint cho tính duy nhất nghiệp vụ (email theo từng tenant), không chỉ
|
|
36
|
+
kiểm tra ở tầng app; kiểm tra ở tầng app sẽ bị đua.
|
|
37
|
+
- Check constraint cho các quy tắc giá trị mà engine có thể cưỡng chế.
|
|
38
|
+
- SQLite: foreign key cần bật theo từng kết nối; nhiều thao tác ALTER đòi phải dựng
|
|
39
|
+
lại bảng. MySQL: check constraint chỉ được cưỡng chế từ 8.0.16.
|
|
40
|
+
- Đặt tên constraint và index nhất quán để các migration sau có thể tham chiếu chúng.
|
|
41
|
+
|
|
42
|
+
## Mở rộng rồi thu hẹp
|
|
43
|
+
|
|
44
|
+
Đổi một schema đang sống theo từng bước, mỗi bước tương thích với cả bản app cũ và mới:
|
|
45
|
+
|
|
46
|
+
1. Mở rộng: thêm cột, bảng, hay index mới. Cho nullable hoặc có default an toàn.
|
|
47
|
+
2. Ghi cả hai: deploy code ghi cả hình dạng cũ và mới.
|
|
48
|
+
3. Backfill các dòng hiện có sang hình dạng mới.
|
|
49
|
+
4. Đọc cái mới: chuyển các lượt đọc; kiểm chứng.
|
|
50
|
+
5. Thu hẹp: ngừng ghi hình dạng cũ, rồi xóa nó trong một migration sau.
|
|
51
|
+
|
|
52
|
+
Đổi tên một cột tại chỗ làm vỡ bản đang chạy; hãy dùng thêm-sao chép-chuyển-xóa.
|
|
53
|
+
Thêm NOT NULL cho một cột đang có: thêm một check hoặc validate ở một bước riêng
|
|
54
|
+
sau khi backfill, rồi mới đặt NOT NULL.
|
|
55
|
+
|
|
56
|
+
## Backfill
|
|
57
|
+
|
|
58
|
+
- Tách khỏi migration schema với bảng lớn.
|
|
59
|
+
- Chia lô theo khoảng primary key hoặc keyset (ví dụ 1k-10k dòng mỗi lô), commit theo
|
|
60
|
+
từng lô, nghỉ giữa các lô nếu tải là vấn đề.
|
|
61
|
+
- Idempotent và tiếp tục được: chỉ chọn những dòng vẫn còn cần đổi.
|
|
62
|
+
- Log số lượng tiến độ, không log nội dung dòng.
|
|
63
|
+
- Kiểm chứng: số dòng còn cần đổi bằng không.
|
|
64
|
+
|
|
65
|
+
## Migration đảo được
|
|
66
|
+
|
|
67
|
+
- Cung cấp một bước down khi công cụ hỗ trợ và thay đổi có thể hoàn tác được.
|
|
68
|
+
- Thay đổi phá hủy dữ liệu thì không thể đảo thật sự; kế hoạch rollback là restore
|
|
69
|
+
hoặc một bản sao được giữ lại. Hãy nói thẳng điều đó.
|
|
70
|
+
- Giữ mỗi migration nhỏ và một mục đích; đừng trộn thay đổi schema với thay đổi dữ
|
|
71
|
+
liệu lớn.
|
|
72
|
+
- Đừng bao giờ sửa một migration đã được áp; hãy thêm một migration mới.
|
|
73
|
+
|
|
74
|
+
## Rủi ro locking
|
|
75
|
+
|
|
76
|
+
| Thao tác | Rủi ro | Dạng an toàn hơn |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| Tạo index (PostgreSQL) | chặn các lượt ghi | `CREATE INDEX CONCURRENTLY` ngoài transaction |
|
|
79
|
+
| Tạo index (MySQL InnoDB) | thường là online | xác nhận `ALGORITHM=INPLACE, LOCK=NONE` |
|
|
80
|
+
| Thêm cột với default biến động | ghi lại cả bảng | thêm nullable, backfill, rồi mới đặt default |
|
|
81
|
+
| Đổi kiểu cột | thường là ghi lại | cột mới, backfill, đổi chỗ |
|
|
82
|
+
| Thêm foreign key / check trên bảng lớn | full scan dưới lock | PostgreSQL: `NOT VALID`, rồi `VALIDATE` |
|
|
83
|
+
| Thêm NOT NULL | scan dưới lock | check constraint đã validate trước |
|
|
84
|
+
|
|
85
|
+
- Đặt một lock timeout (ví dụ `SET lock_timeout` trong PostgreSQL) để một migration
|
|
86
|
+
đang chờ sau một transaction dài fail nhanh thay vì chặn toàn bộ lưu lượng.
|
|
87
|
+
- Hành vi khác nhau theo engine và version; hãy xem tài liệu của version đang dùng.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
{
|
|
2
|
+
"label": "Design",
|
|
3
|
+
"description": "Quyết định UI và UX: layout, typography, token, trạng thái tương tác, và review theo các hướng dẫn về khả năng dùng và khả năng tiếp cận.",
|
|
4
|
+
"skills": ["ui-design"],
|
|
5
|
+
"assign": { "lead": ["ui-design"], "peer": ["ui-design"] }
|
|
6
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ui-design
|
|
3
|
+
description: "Ra quyết định và review thiết kế UI/UX: layout, typography, màu và token, trạng thái tương tác, hành vi responsive và tính nhất quán với design system. Dùng khi thiết kế hình thức của một màn hình hay component, định nghĩa token, hoặc review UI theo chuẩn khả dụng và accessibility. Không dùng để viết code component (frontend-development) hay viết nội dung."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Ra quyết định và review thiết kế UI
|
|
7
|
+
|
|
8
|
+
## Khi nào dùng
|
|
9
|
+
|
|
10
|
+
- Một màn hình, luồng hay component cần quyết định về layout, thứ bậc, khoảng cách hoặc kiểu chữ.
|
|
11
|
+
- Màu, khoảng cách, bán kính, đổ bóng hoặc kiểu chữ cần thành token, hoặc token cần biến thể sáng/tối.
|
|
12
|
+
- Một thiết kế cần đặc tả trạng thái tương tác: hover, focus, active, disabled, loading, rỗng, lỗi.
|
|
13
|
+
- UI đang có cần được review về khả dụng, accessibility và tính nhất quán với design system.
|
|
14
|
+
- Hành vi responsive theo chiều rộng, cách nhập liệu hoặc mức zoom chưa được quyết hoặc đang sai.
|
|
15
|
+
|
|
16
|
+
## Không dùng cho
|
|
17
|
+
|
|
18
|
+
- Viết hay refactor code component, hạ tầng styling hoặc quản lý state: frontend-development.
|
|
19
|
+
- Nội dung marketing hoặc đặt tên sản phẩm.
|
|
20
|
+
- Nhận diện thương hiệu, logo hoặc sản xuất hình minh họa.
|
|
21
|
+
- Tối ưu hiệu năng render: dùng quy trình profiling của dự án.
|
|
22
|
+
|
|
23
|
+
## Điều kiện tiên quyết
|
|
24
|
+
|
|
25
|
+
- Việc được giao (assignment) nêu rõ bề mặt (màn hình, component, luồng) và ai dùng nó trên thiết bị nào.
|
|
26
|
+
- Đọc ALP.md và design system đang có của dự án: file token, config theme, thư viện component,
|
|
27
|
+
style guide, ảnh chụp hoặc file thiết kế đã có trong repository.
|
|
28
|
+
- Biết cơ chế styling của stack (CSS variable, utility class, theme object, native style) qua
|
|
29
|
+
manifest và config, không phải qua tên thư mục.
|
|
30
|
+
|
|
31
|
+
## Quy trình
|
|
32
|
+
|
|
33
|
+
1. Kiểm kê những gì đã có. Tìm token, component và pattern hiện tại đã giải quyết được một phần
|
|
34
|
+
vấn đề. Ghi lại bạn đã tìm ở đâu trước khi nói là thiếu một thứ gì.
|
|
35
|
+
2. Nêu tác vụ người dùng mà bề mặt này phục vụ và một hành động chính duy nhất cho mỗi view. Thiết kế
|
|
36
|
+
thứ bậc quanh hành động đó; hạ bậc mọi thứ còn lại.
|
|
37
|
+
3. Quyết định layout và kiểu chữ từ thang đo đang có. Dùng thang khoảng cách và thang chữ của dự án;
|
|
38
|
+
chỉ thêm một bậc khi không bậc nào vừa, và nói rõ vì sao.
|
|
39
|
+
4. Quyết định màu qua token, không bao giờ dùng giá trị thô trong component. Map token semantic (surface,
|
|
40
|
+
text, border, accent, danger) sang palette nguyên thủy cho cả theme sáng và tối, và kiểm tra tương phản.
|
|
41
|
+
5. Đặc tả mọi trạng thái tương tác cho từng phần tử tương tác được, gồm cả focus bàn phím,
|
|
42
|
+
loading, rỗng và lỗi. Đặc tả chuyển động kèm một phương án giảm chuyển động.
|
|
43
|
+
6. Đặc tả hành vi responsive: cái gì reflow, co lại, ẩn đi hoặc đổi thứ tự ở mỗi breakpoint,
|
|
44
|
+
và layout hoạt động thế nào ở zoom 200% và trên thiết bị cảm ứng.
|
|
45
|
+
7. Viết quyết định thành một spec ngắn: token đã dùng hoặc thêm, layout theo từng breakpoint, bảng
|
|
46
|
+
trạng thái, ghi chú accessibility, và các câu hỏi còn mở. Giao phần cài đặt cho role triển khai.
|
|
47
|
+
8. Khi review, dùng checklist review, xếp các phát hiện theo mức nghiêm trọng và dẫn bằng chứng
|
|
48
|
+
(file và dòng, ảnh chụp, tỉ lệ tương phản đo được) cho từng cái.
|
|
49
|
+
|
|
50
|
+
## Ràng buộc
|
|
51
|
+
|
|
52
|
+
- Trước hết hãy tuân theo design system, stack và quy ước đang có của dự án. Chỉ đề xuất token,
|
|
53
|
+
component hay pattern mới khi cái đang có không đáp ứng được, và nêu rõ nó thay thế cái gì.
|
|
54
|
+
- Không thêm thư viện UI, bộ icon, dịch vụ font hoặc phụ thuộc công cụ thiết kế mà không có
|
|
55
|
+
quyết định của chủ sở hữu. Không tự động cài.
|
|
56
|
+
- Không tải dữ liệu thiết kế, font hay ảnh từ xa. Chỉ làm với những gì có trong repository và brief.
|
|
57
|
+
- Agent chỉ đọc (oracle, reviewer, architect) dừng ở spec hoặc các phát hiện; chúng không sửa file.
|
|
58
|
+
- Accessibility là yêu cầu, không phải bước làm đẹp: tương phản WCAG 2.2 AA, focus thấy được,
|
|
59
|
+
kích thước đích, và không có thông tin nào chỉ truyền tải bằng màu.
|
|
60
|
+
- Skill không cấp thẩm quyền: quyết định thiếu về sản phẩm hay thương hiệu chuyển lên main và người dùng.
|
|
61
|
+
|
|
62
|
+
## Kiểm chứng
|
|
63
|
+
|
|
64
|
+
- Mọi cặp màu trong spec đều có tỉ lệ tương phản được nêu và đạt ngưỡng của nó ở cả hai theme.
|
|
65
|
+
- Mọi phần tử tương tác được đều có đủ các trạng thái áp dụng được, gồm cả focus và disabled.
|
|
66
|
+
- Layout được mô tả tại các breakpoint của dự án và ở zoom 200% mà nội dung chữ không bị cuộn
|
|
67
|
+
ngang.
|
|
68
|
+
- Token mới theo đúng lược đồ đặt tên đang có và có giá trị cho cả hai theme.
|
|
69
|
+
- Mỗi phát hiện khi review đều có mức nghiêm trọng, vị trí, bằng chứng và một cách sửa cụ thể.
|
|
70
|
+
|
|
71
|
+
## Xử lý khi thất bại
|
|
72
|
+
|
|
73
|
+
- Chưa có design system: đề xuất một bộ token tối thiểu suy ra từ các giá trị đã dùng trong code,
|
|
74
|
+
và đánh dấu nó là một quyết định cho chủ sở hữu thay vì tự nghĩ ra cả một hệ thống.
|
|
75
|
+
- Đang dùng những pattern xung đột nhau: liệt kê kèm vị trí và khuyến nghị một cái; không
|
|
76
|
+
im lặng tự chọn.
|
|
77
|
+
- Màu thương hiệu không đạt tương phản: giữ giá trị thương hiệu cho phần trang trí và đề xuất một
|
|
78
|
+
biến thể đã điều chỉnh, đạt accessibility, cho chữ và control; chuyển lựa chọn lên trên.
|
|
79
|
+
- Chưa rõ thiết bị hay người dùng mục tiêu: nêu giả định đó trong spec và đánh dấu là còn mở.
|
|
80
|
+
|
|
81
|
+
## Tài liệu tham chiếu
|
|
82
|
+
|
|
83
|
+
- [references/design-tokens.md](references/design-tokens.md) — đọc khi định nghĩa, đặt tên hay tạo theme cho token, hoặc kiểm tra tương phản ở bước 4.
|
|
84
|
+
- [references/layout-and-typography.md](references/layout-and-typography.md) — đọc khi chọn grid, khoảng cách, thang chữ hay breakpoint ở bước 3 và 6.
|
|
85
|
+
- [references/interaction-states.md](references/interaction-states.md) — đọc khi đặc tả trạng thái hoặc chuyển động ở bước 5.
|
|
86
|
+
- [references/ui-review.md](references/ui-review.md) — đọc khi review UI đang có ở bước 8.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Design token
|
|
2
|
+
|
|
3
|
+
Đọc khi định nghĩa, đặt tên hay tạo theme cho token, hoặc khi kiểm tra tương phản màu.
|
|
4
|
+
|
|
5
|
+
## Các tầng
|
|
6
|
+
|
|
7
|
+
1. **Nguyên thủy** (palette và thang đo thô): `color-blue-600`, `space-4`, `radius-2`, `font-size-3`.
|
|
8
|
+
Đặt tên theo đúng bản chất của chúng. Không bao giờ dùng trực tiếp trong component.
|
|
9
|
+
2. **Semantic** (vai trò): `color-text-primary`, `color-surface-raised`, `color-border-subtle`,
|
|
10
|
+
`color-accent`, `color-danger`, `space-inset-md`. Đặt tên theo việc chúng làm. Các theme map
|
|
11
|
+
những token này sang các giá trị nguyên thủy khác nhau.
|
|
12
|
+
3. **Component** (không bắt buộc, chỉ khi một component lệch khỏi chuẩn): `button-primary-bg`,
|
|
13
|
+
`input-border-focus`. Trỏ vào token semantic. Thêm dè dặt; mỗi cái là một nhánh rẽ.
|
|
14
|
+
|
|
15
|
+
Component chỉ tiêu thụ token semantic hoặc token component. Đổi một theme đáng ra chỉ cần
|
|
16
|
+
sửa các map semantic, không phải sửa code component.
|
|
17
|
+
|
|
18
|
+
## Đặt tên
|
|
19
|
+
|
|
20
|
+
- Theo lược đồ đã có trong dự án. Nếu chưa có: `category-role-variant-state`, chữ thường,
|
|
21
|
+
nối bằng gạch ngang, ví dụ `color-text-secondary`, `color-accent-hover`.
|
|
22
|
+
- Tên mô tả vai trò, không mô tả giá trị: `color-danger`, không phải `color-red`; `space-stack-lg`,
|
|
23
|
+
không phải `space-24` ở tầng semantic.
|
|
24
|
+
- Giữ thang đo theo thứ tự và chịu được khoảng trống (`100`..`900`, hoặc `1`..`8`) để chèn thêm bậc.
|
|
25
|
+
- Một nguồn chân lý duy nhất. Nếu token tồn tại ở nhiều định dạng (CSS variable, theme object, hằng
|
|
26
|
+
số native), hãy sinh ra hoặc đồng bộ từ một file chứ không sửa tay từng cái.
|
|
27
|
+
|
|
28
|
+
## Sáng và tối
|
|
29
|
+
|
|
30
|
+
- Định nghĩa mọi màu semantic cho cả hai theme. Một token thiếu giá trị tối là một lỗi.
|
|
31
|
+
- Theme tối không phải theme sáng đảo ngược: dùng surface trung tính tối thay vì đen tuyệt đối,
|
|
32
|
+
nâng độ cao bằng surface sáng hơn thay vì bóng đậm hơn, và giảm độ bão hòa của những vùng
|
|
33
|
+
accent lớn.
|
|
34
|
+
- Tôn trọng tùy chọn của nền tảng (`prefers-color-scheme` hoặc tương đương native) và cho phép
|
|
35
|
+
ghi đè tường minh nếu sản phẩm đã có sẵn lựa chọn đó.
|
|
36
|
+
- Kiểm tra ảnh, hình minh họa, biểu đồ và vòng focus ở cả hai theme, không chỉ riêng chữ.
|
|
37
|
+
|
|
38
|
+
## Ngưỡng tương phản (WCAG 2.2)
|
|
39
|
+
|
|
40
|
+
| Cặp màu | Tối thiểu AA | AAA |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Chữ nội dung so với nền | 4.5:1 | 7:1 |
|
|
43
|
+
| Chữ lớn (24px+, hoặc 18.66px+ in đậm) | 3:1 | 4.5:1 |
|
|
44
|
+
| Đường biên component UI, icon mang nghĩa | 3:1 | - |
|
|
45
|
+
| Chỉ báo focus so với các màu kề nó | 3:1 | - |
|
|
46
|
+
| Control bị disabled, phần trang trí thuần túy | miễn | - |
|
|
47
|
+
|
|
48
|
+
- Tính tỉ lệ từ độ sáng tương đối của hai màu sRGB:
|
|
49
|
+
`(L1 + 0.05) / (L2 + 0.05)` với L1 là màu sáng hơn. Ghi lại con số, không ghi "trông ổn".
|
|
50
|
+
- Kiểm tra chữ trên mọi surface nó có thể xuất hiện (nền cơ sở, nền nổi, overlay, dòng được chọn, hover).
|
|
51
|
+
- Chữ placeholder vẫn là chữ: nó cần 4.5:1, hoặc nó không nên chứa hướng dẫn.
|
|
52
|
+
- Màu bán trong suốt: tính dựa trên nền thực tế sau khi ghép lớp.
|
|
53
|
+
- Không bao giờ truyền tải trạng thái chỉ bằng màu; luôn kèm chữ, icon, hình dạng hoặc vị trí.
|
|
54
|
+
|
|
55
|
+
## Các loại token khác
|
|
56
|
+
|
|
57
|
+
- Khoảng cách: một đơn vị cơ sở (thường là 4 hoặc 8) và một thang ngắn; xem layout-and-typography.md.
|
|
58
|
+
- Bán kính: 3-5 bậc cộng thêm `full`. Phần tử lồng trong dùng bán kính nhỏ hơn phần tử chứa nó.
|
|
59
|
+
- Độ cao: vài mức có tên, map đổ bóng và màu surface cùng với nhau.
|
|
60
|
+
- Chuyển động: token thời lượng (`fast`, `base`, `slow`) và token easing; xem interaction-states.md.
|
|
61
|
+
- Z-index: một tập có tên và có thứ tự (`dropdown`, `sticky`, `overlay`, `modal`, `toast`) thay cho
|
|
62
|
+
các con số đặt tùy hứng.
|
|
63
|
+
|
|
64
|
+
## Spec đầu ra cho một thay đổi token
|
|
65
|
+
|
|
66
|
+
Liệt kê từng token: tầng, tên, giá trị sáng, giá trị tối, tương phản với các surface đi kèm,
|
|
67
|
+
và nó thay thế những giá trị hard-code nào đang có (file và dòng).
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Trạng thái tương tác và chuyển động
|
|
2
|
+
|
|
3
|
+
Đọc khi đặc tả trạng thái cho các phần tử tương tác được hoặc cho view, hoặc khi định nghĩa chuyển động.
|
|
4
|
+
|
|
5
|
+
## Trạng thái của control
|
|
6
|
+
|
|
7
|
+
Đặc tả từng trạng thái áp dụng được cho mọi phần tử tương tác được. Đầu ra mong đợi là một
|
|
8
|
+
bảng trạng thái cho mỗi component.
|
|
9
|
+
|
|
10
|
+
| Trạng thái | Mục đích | Yêu cầu |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| Default | Hình thức khi nghỉ | Nhận ra được là tương tác được mà không cần hover |
|
|
13
|
+
| Hover | Gợi ý cho con trỏ | Thay đổi nhẹ; không bao giờ là tín hiệu duy nhất; không cần trên cảm ứng |
|
|
14
|
+
| Focus-visible | Vị trí bàn phím | Chỉ báo thấy được, 3:1 so với màu kề, không bị nội dung sticky che |
|
|
15
|
+
| Active / được nhấn | Phản hồi khi nhấn | Tức thì; khác biệt với hover |
|
|
16
|
+
| Selected / checked | Lựa chọn còn lưu lại | Không chỉ bằng màu; dùng dấu check, tô nền, độ dày hoặc chữ |
|
|
17
|
+
| Disabled | Hiện không dùng được | Giải thích vì sao nếu có thể; cân nhắc bật kèm thông báo |
|
|
18
|
+
| Chỉ đọc | Thấy được, không sửa được | Vẫn focus được và copy được |
|
|
19
|
+
| Loading / đang xử lý | Hành động đang diễn ra | Chặn submit hai lần; giữ kích thước ổn định; thông báo cho công nghệ trợ giúp |
|
|
20
|
+
| Invalid / lỗi | Dữ liệu nhập bị từ chối | Thông báo cạnh field, chữ kèm icon, chỉ ra cách sửa |
|
|
21
|
+
| Success | Hành động đã được xác nhận | Ngắn, không chặn, có thông báo |
|
|
22
|
+
|
|
23
|
+
Ghi chú:
|
|
24
|
+
|
|
25
|
+
- Không bao giờ bỏ viền focus mà không có thứ thay thế thấy được.
|
|
26
|
+
- Thứ tự focus theo thứ tự đọc; modal giữ focus bên trong và trả nó lại khi đóng.
|
|
27
|
+
- Nút disabled không focus được trên nhiều stack, nên người dùng không thể biết vì sao nó bị
|
|
28
|
+
disabled. Nên giải thích yêu cầu còn thiếu ngay cạnh control.
|
|
29
|
+
- Giữ vùng bấm ổn định qua các trạng thái; một spinner không được làm nút đổi kích thước.
|
|
30
|
+
|
|
31
|
+
## Trạng thái của view
|
|
32
|
+
|
|
33
|
+
Mọi view dựa trên dữ liệu đều cần thiết kế những trạng thái sau, không chỉ trạng thái có dữ liệu:
|
|
34
|
+
|
|
35
|
+
- **Loading lần đầu:** skeleton khớp layout cuối cho các chờ ngắn; spinner kèm nhãn cho những
|
|
36
|
+
hình dạng chưa biết. Tránh nháy loader với phản hồi rất nhanh (hoãn hiện nó một chút).
|
|
37
|
+
- **Rỗng (lần dùng đầu):** giải thích cái gì sẽ xuất hiện và mời hành động chính để tạo nó.
|
|
38
|
+
- **Rỗng (không có kết quả):** nói rõ filter hay truy vấn không ra gì; mời xóa nó đi.
|
|
39
|
+
- **Một phần:** một phần dữ liệu đã tải, một phần lỗi; hiện cái có và đánh dấu phần thiếu.
|
|
40
|
+
- **Lỗi:** nguyên nhân bằng lời thường, người dùng có thể làm gì (thử lại, kiểm tra kết nối, liên hệ),
|
|
41
|
+
và giữ lại dữ liệu người dùng đã nhập. Không hiện stack trace thô.
|
|
42
|
+
- **Offline / dữ liệu cũ:** cho biết dữ liệu cũ cỡ nào và khi nào sẽ làm mới, nếu sản phẩm hỗ trợ.
|
|
43
|
+
- **Bị từ chối quyền:** nói rõ là thiếu quyền truy cập và ai có thể cấp, mà không để lộ nội dung.
|
|
44
|
+
- **Tràn:** tên dài, nhiều mục, số lớn, ảnh bị thiếu.
|
|
45
|
+
|
|
46
|
+
## Thời điểm phản hồi
|
|
47
|
+
|
|
48
|
+
- Dưới ~100ms: cảm giác tức thì, không cần chỉ báo.
|
|
49
|
+
- ~100ms đến 1s: hiện một chỉ báo nhẹ trên chính control đó.
|
|
50
|
+
- Trên ~1s: hiện tiến trình hoặc trạng thái loading cho cả vùng.
|
|
51
|
+
- Trên ~10s: hiện tiến trình xác định nếu có thể và cho phép hủy hoặc chạy nền.
|
|
52
|
+
- Cập nhật lạc quan cần một đường thoát khi lỗi, thấy được và đảo lại được.
|
|
53
|
+
|
|
54
|
+
## Chuyển động
|
|
55
|
+
|
|
56
|
+
- Mục đích trước đã: chuyển động giải thích thay đổi không gian, tính liên tục hoặc phản hồi. Bỏ các
|
|
57
|
+
chuyển động trang trí không phục vụ điều nào trong số đó.
|
|
58
|
+
- Thời lượng: khoảng 100-200ms cho control nhỏ, 200-300ms cho panel và overlay, ít khi
|
|
59
|
+
trên 400ms. Lúc ra hơi nhanh hơn lúc vào.
|
|
60
|
+
- Easing: ease-out khi vào, ease-in khi ra, ease-in-out chuẩn khi di chuyển trên màn hình.
|
|
61
|
+
Dùng token chuyển động của dự án.
|
|
62
|
+
- Hoạt họa opacity và transform; tránh hoạt họa các thuộc tính layout gây reflow.
|
|
63
|
+
- **Giảm chuyển động:** khi người dùng yêu cầu giảm chuyển động (`prefers-reduced-motion` hoặc
|
|
64
|
+
thiết lập native), hãy thay chuyển động, parallax, zoom và hoạt họa tự chạy bằng một thay đổi
|
|
65
|
+
tức thì hoặc một crossfade ngắn. Nêu biến thể giảm đó trong spec cho từng hoạt họa.
|
|
66
|
+
- Không nội dung nào nháy quá ba lần mỗi giây.
|
|
67
|
+
- Nội dung tự chạy hoặc đang chuyển động kéo dài trên 5 giây cần có pause, stop hoặc hide.
|
|
68
|
+
|
|
69
|
+
## Thông báo
|
|
70
|
+
|
|
71
|
+
- Thay đổi trạng thái (đã lưu, loading xong, lỗi sau khi submit) được thông báo qua cơ chế live-region
|
|
72
|
+
hoặc cơ chế thông báo accessibility của stack, ở mức lịch sự trừ khi gấp.
|
|
73
|
+
- Sau khi submit form mà có lỗi, chuyển focus tới bản tóm tắt lỗi hoặc field không hợp lệ đầu tiên.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Layout và typography
|
|
2
|
+
|
|
3
|
+
Đọc khi chọn grid, khoảng cách, thang chữ, độ dài dòng hoặc breakpoint responsive.
|
|
4
|
+
|
|
5
|
+
## Thang khoảng cách
|
|
6
|
+
|
|
7
|
+
- Một đơn vị cơ sở, thường là 4px hoặc 8px. Ví dụ thang: 4, 8, 12, 16, 24, 32, 48, 64, 96.
|
|
8
|
+
- Dùng thang đang có. Giá trị lệch thang (13px, 22px) là một phát hiện (finding) khi review, trừ khi
|
|
9
|
+
nó đến từ một chỉnh sửa thị giác đã được ghi lại.
|
|
10
|
+
- Sự gần nhau thể hiện việc nhóm: khoảng cách trong một nhóm nhỏ hơn khoảng cách giữa các nhóm.
|
|
11
|
+
Tỉ lệ thường dùng là 1:2 (ví dụ 8 bên trong, 16 ở giữa; 16 bên trong, 32 giữa các mục lớn).
|
|
12
|
+
- Ưu tiên gap của layout trên container hơn margin trên phần tử con; nó tránh khoảng cách bị gộp hay nhân đôi.
|
|
13
|
+
|
|
14
|
+
## Grid
|
|
15
|
+
|
|
16
|
+
- Trang nội dung: một cột căn giữa có chiều rộng tối đa, hoặc grid 12 cột với gutter cố định
|
|
17
|
+
(16-32px) và lề ngoài co lại trên màn hình nhỏ (16px là mức tối thiểu thường dùng).
|
|
18
|
+
- Khung ứng dụng: thanh điều hướng rộng cố định, vùng chính linh động, pane chi tiết tùy chọn. Hãy quyết
|
|
19
|
+
pane nào co lại trước khi chiều rộng hẹp dần.
|
|
20
|
+
- Căn theo một số ít đường biên dọc. Mỗi đường biên thêm vào là thêm nhiễu thị giác.
|
|
21
|
+
- Dữ liệu dày (bảng, dashboard) có thể dùng thang chặt hơn, nhưng giữ nó nhất quán trong một view.
|
|
22
|
+
|
|
23
|
+
## Thang chữ
|
|
24
|
+
|
|
25
|
+
- Dùng thang theo module (tỉ lệ khoảng 1.2-1.25 cho ứng dụng, tới 1.333 cho dạng báo chí) hoặc
|
|
26
|
+
các bậc đã có của dự án. 5-7 cỡ là đủ cho phần lớn sản phẩm.
|
|
27
|
+
- Chữ nội dung: mặc định 16px trên web; không bao giờ dưới 14px cho chữ nội dung, 12px chỉ dành cho
|
|
28
|
+
nhãn phụ với tương phản đủ.
|
|
29
|
+
- Dùng `rem` (hoặc đơn vị co giãn được của nền tảng) để chữ đi theo thiết lập cỡ chữ của người dùng.
|
|
30
|
+
- Chiều cao dòng: khoảng 1.4-1.6 cho nội dung, 1.1-1.3 cho tiêu đề. Chữ lớn hơn cần ít hơn.
|
|
31
|
+
- Độ dày: hai hoặc ba mức (regular, medium hoặc semibold, bold). Thứ bậc đến từ cỡ,
|
|
32
|
+
độ dày và màu cùng nhau, không phải từ nhiều độ dày.
|
|
33
|
+
- Giới hạn một hoặc hai họ chữ, tốt nhất là họ dự án đã tải sẵn; thêm một font
|
|
34
|
+
là một quyết định về phụ thuộc, thuộc về chủ sở hữu.
|
|
35
|
+
- Dùng chữ số dạng bảng cho các cột số và bộ đếm thời gian.
|
|
36
|
+
|
|
37
|
+
## Độ dài dòng và tính dễ đọc
|
|
38
|
+
|
|
39
|
+
- Chiều dài dòng nội dung: khoảng 45-75 ký tự mỗi dòng; chặn container văn bản (ví dụ `max-width: 65ch`).
|
|
40
|
+
- Căn lề trái cho chữ nội dung ở ngôn ngữ viết trái sang phải; tránh chữ căn đều hai bên trên web.
|
|
41
|
+
- Khoảng cách giữa các đoạn xấp xỉ bằng chiều cao dòng.
|
|
42
|
+
- Tính trước việc chữ dài ra: bản dịch có thể dài hơn 30-40%; tránh nhãn có chiều rộng cố định.
|
|
43
|
+
- Hỗ trợ viết phải sang trái bằng các thuộc tính logic (start/end) ở nơi stack cho phép.
|
|
44
|
+
|
|
45
|
+
## Checklist thứ bậc cho mỗi view
|
|
46
|
+
|
|
47
|
+
- Một hành động chính rõ ràng; hành động phụ yếu hơn về thị giác; hành động phá hủy để tách riêng.
|
|
48
|
+
- Tiêu đề trang là chữ lớn nhất trong vùng nội dung.
|
|
49
|
+
- Các control liên quan đặt cạnh nhau; nhãn đặt cạnh input của nó (đặt trên với form trên màn hình hẹp).
|
|
50
|
+
- Đường quét mắt: tiêu đề và giá trị quan trọng đọc được khi nhìn nhanh mà không đọc phần nội dung.
|
|
51
|
+
|
|
52
|
+
## Hành vi responsive
|
|
53
|
+
|
|
54
|
+
- Dùng breakpoint của dự án. Nếu chưa có, hãy bắt đầu từ nội dung: thêm breakpoint ở nơi
|
|
55
|
+
layout bị vỡ, không phải ở các chiều rộng thiết bị. Các mốc tham chiếu thường gặp: ~640, ~768, ~1024, ~1280px.
|
|
56
|
+
- Thiết kế cho màn hình nhỏ trước; rồi nâng cấp cho màn hình rộng hơn.
|
|
57
|
+
- Với mỗi component hãy quyết: reflow, xếp dọc, co lại (vào menu hoặc phần mở ra), cắt bớt
|
|
58
|
+
(vẫn truy cập được giá trị đầy đủ), hoặc ẩn (chỉ khi không thiết yếu và có ở nơi khác).
|
|
59
|
+
- Ưu tiên quy tắc theo container cho những component dùng lại trong các pane rộng khác nhau, khi
|
|
60
|
+
stack hỗ trợ.
|
|
61
|
+
- Reflow: ở chiều rộng 320 CSS px (tương đương 1280px ở zoom 400%), nội dung không được cần
|
|
62
|
+
cuộn theo hai chiều, trừ bảng dữ liệu, bản đồ và những thứ tương tự.
|
|
63
|
+
- Cảm ứng: đích ít nhất 24x24 CSS px (WCAG 2.2 AA), khuyến nghị 44x44 cho hành động cảm ứng chính,
|
|
64
|
+
và có khoảng cách giữa các đích kề nhau.
|
|
65
|
+
- Không dựa vào hover cho thông tin thiết yếu trên thiết bị cảm ứng.
|
|
66
|
+
- Tôn trọng vùng an toàn và bàn phím trên màn hình ở mobile; giữ các hành động chính trong tầm với.
|
|
67
|
+
|
|
68
|
+
## Spec đầu ra
|
|
69
|
+
|
|
70
|
+
Với mỗi breakpoint: grid/số cột, những vùng nào hiện ra, thay đổi thứ tự, các cỡ chữ thay đổi,
|
|
71
|
+
và những component đổi hình thức. Ghi chú hành vi ở zoom 200% và ở chiều rộng hẹp nhất được hỗ trợ.
|