Bug report tiếng Việt cho khách Nhật/US: template paste được, repro steps, expected vs actual

Trong dự án outsource, bug không chậm vì “dev lười” — thường chậm vì ticket kiểu:

“Trang thanh toán bị lỗi. Gấp giúp em.”

Không URL, không account, không bước, không expected. Dev JP/US phải hỏi lại 4–5 tin nhắn qua múi giờ → mất nửa ngày.

Bài này dành cho người viết báo cáo phía VN: QA, freelancer, BA, support — để ticket paste được và sửa được.

Bài viết này giúp bạn

• Nắm 5 mục bắt buộc mọi bug report
• Có template tiếng Việt (heading English) copy vào Jira/GitHub
• Biết viết repro và expected vs actual rõ
• Tránh lỗi giao tiếp với khách JP/US
• Dùng bug report generator lấy môi trường trình duyệt + format sẵn

---

Mục tiêu thật sự của bug report

Không phải “chứng minh có lỗi”. Mục tiêu là:

Người khác, trên máy khác, làm đúng các bước của bạn → thấy cùng lỗi.

Nếu họ không tái hiện được, ticket chưa xong — dù bạn đã thấy bug 10 lần.

---

Năm mục bắt buộc

1. Summary — một câu: hành động → hậu quả
2. Steps to reproduce — đánh số, bắt đầu từ trạng thái biết trước (logged out / clean cart)
3. Expected — đúng spec / đúng bản trước
4. Actual — xảy ra gì, kèm nguyên văn error
5. Environment — OS, browser hoặc app version, URL/build, locale, role user

Bổ sung mạnh (khi có):

• Screenshot / Loom ngắn
• Console (F12) + tab Network (status, request id)
• Tần suất: Always / 3 of 10 / Once
• Workaround tạm (nếu biết)

---

Template paste được (VI nội dung + EN heading)

Dùng heading English để ticket search/filter trên Jira của khách quốc tế; mô tả có thể Việt nếu PM Việt đọc trước.

## Summary
[Một câu: làm X thì xảy ra Y]

## Steps to reproduce
1. …
2. …
3. …

## Expected
- …

## Actual
- …
- Error message (verbatim): `…`

## Environment
- OS:
- Browser / App version:
- URL / Build:
- Account / Role:
- Locale / Language:
- Repro rate: Always | Sometimes (x/y) | Once

## Attachments
- Screenshot / video:
- Console / network log:

Ví dụ đã điền (web app)

## Summary
Checkout staging: bấm "Thanh toán" với giỏ 1 sản phẩm VND → API 500, không tạo order.

## Steps to reproduce
1. Mở https://staging.example.com (incognito)
2. Login `[email protected]` / role Buyer
3. Add product SKU-12, qty 1
4. Vào Cart → Checkout
5. Chọn phương thức "Card test"
6. Bấm "Thanh toán"

## Expected
- HTTP 200 từ `POST /api/orders`
- Redirect trang success
- Order xuất hiện trong My Orders

## Actual
- UI toast "Có lỗi xảy ra"
- `POST /api/orders` → 500
- Body: `{"code":"PAYMENT_GATEWAY_TIMEOUT","requestId":"req_7f3a"}`

## Environment
- OS: Windows 11
- Browser: Chrome 126.0.6478.127
- URL: https://staging.example.com
- Build: `[email protected]`
- Account: [email protected] (Buyer)
- Locale: vi-VN
- Repro rate: Always (5/5)

## Attachments
- screenshot-checkout-500.png
- network-har đính kèm (chỉ request orders, đã che Authorization)

Copy khung này thủ công, hoặc mở công cụ tạo bug report: tool tự lấy thông tin môi trường trình duyệt, bạn điền timing / reproducibility / steps / expected / actual, chọn Markdown hoặc plain text rồi paste vào ticket. Phù hợp cả báo cáo web và game (GPU, resolution…). Dữ liệu xử lý local — không gửi form lên server Kawa.

---

Viết repro steps: mẹo cho outsource VN

Bắt đầu từ “cửa sạch”

Dev không ngồi sẵn trên account của bạn. Ghi:

• URL chính xác (staging vs prod — đừng trộn)
• Cần login không? User nào? Role nào?
• Dữ liệu seed đặc biệt? (giỏ đã có sẵn, feature flag)

Đánh số hành động quan sát được

Yếu: “Thỉnh thoảng thanh toán xong bị đứng.”
Mạnh: “Sau bước 6, spinner > 30s rồi toast lỗi; không có order mới.”

Expected vs Actual phải cặp nhau

Expected	Actual
Form lưu và hiện toast xanh	Form reset, không toast
List 20 items/page	List trống, console TypeError: …

Tránh Actual kiểu “sai” mà không nói sai thế nào.

Ảnh + console

UI lệch layout: một ảnh đủ mạnh. Crash/logic: ảnh không thay được status code và stack. Với khách JP, họ thường hỏi requestId / traceId — để sẵn trong Actual.

---

Case study 1: Freelancer VN ↔ PM Nhật

Trước: Slack tiếng Việt ngắn, không env → PM dịch lại → eng JP hỏi thêm → 1 ngày trôi.

Sau: Template trên + HAR đã che token. Eng tái hiện trong 10 phút, fix cùng ngày.

Bài học: Đầu tư 8 phút viết ticket = tiết kiệm 1 vòng timezone.

Case study 2: “Only on mobile”

Yếu: “Mobile bị lỗi.”
Đủ: iPhone 13, iOS 17.5, Safari; không lỗi Chrome Android cùng account; xảy ra khi xoay ngang sau bước 3.

Môi trường cụ thể biến bug “không tái hiện” thành bug “chỉ Safari iOS”.

---

Checklist trước khi bấm Send

• Summary một câu có hành động + hậu quả
• Steps ≥ 3 bước, đánh số
• Có Expected và Actual tách biệt
• Error nguyên văn (không diễn giải mất mã)
• Env đủ để dựng lại (OS/browser/build/URL/role)
• Staging/prod ghi đúng
• Đã che mật khẩu, token, dữ liệu khách hàng trong ảnh/log
• Repro rate ghi rõ

---

Lỗi giao tiếp hay gặp với khách JP/US

Thói quen	Vì sao hại	Thay bằng
Chỉ nói “gấp”	Không giúp ưu tiên kỹ thuật	Severity: blocker checkout / cosmetic
Trộn nhiều bug một ticket	Khó assign, khó close	1 bug = 1 ticket
Sửa ticket bằng chat dài	Mất ngữ cảnh	Edit mô tả gốc + comment “Updated steps”
Gửi production secrets	Rủi ro bảo mật	Account test + redaction
Chỉ voice note	Không search được	Template text + link Loom

Severity gợi ý (dùng label khách hay dùng):

• Blocker — không thanh toán / không login
• Major — feature chính sai, có workaround xấu
• Minor — UI lệch, copy sai
• Trivial — typo

---

Khi nào dùng tool Kawa

• Cần lấy nhanh OS/browser/resolution từ máy đang reproduce
• Muốn output Markdown / text / JSON dán Jira hoặc Discord
• Báo cáo game/web có thêm GPU, timing (startup/play…), reproducibility

Quy trình gợi ý: reproduce trên Chrome → mở bug-report → tick mục env → điền steps/expected/actual → copy Markdown → dán GitHub Issue.

---

Mẫu siêu ngắn (khi khách chỉ cho form 1 ô)

[Summary] ...
[Steps] 1) ... 2) ... 3) ...
[Expected] ...
[Actual] ... | error: `...`
[Env] OS=...; Browser=...; URL=...; Build=...; Role=...; Rate=Always

Bookmark lý do: template paste + ví dụ checkout 500 — gửi được ticket “dev JP/US không phải hỏi lại” ngay trong sprint outsource.