NFR-ERR: Học từ lỗi
NFR · nguồn: sổ lỗi CI, sổ lỗi Cloudflare
Yêu cầu
Mọi lỗi của hệ, từ GitHub Actions lẫn Cloudflare (HTTP ở zone và runtime của Worker), phải:
- Được thu, không phụ thuộc người nhớ đi xem.
- Được gắn dấu vân tay: lỗi cùng nguyên nhân gốc mang cùng một mã (
F1..F7cho CI,C1..C13cho Cloudflare), để đếm theo nguyên nhân chứ không theo lượt. - Có chốt chặn: mỗi dấu vân tay có một gác, hook hoặc quyết định ghi lại khiến nó không lặp lại, hoặc ghi rõ vì sao chấp nhận.
User story
| Mã | Story | Tiêu chí chấp nhận |
|---|---|---|
| NFR-ERR-01 | Là chủ repo, tôi muốn mọi lượt CI đỏ được ghi vào sổ, để thấy lỗi nào lặp. | Given một lượt ci-checks có conclusion failure hoặc startup_failure When sổ được cập nhật Then có một dòng với run id, workflow, nhánh, lỗi rút gọn và dấu vân tay. |
| NFR-ERR-02 | Là chủ repo, tôi muốn lỗi Cloudflare của người đọc thật được ghi, không lẫn nhiễu nội bộ. | Given truy vấn lỗi HTTP trên zone When rà Then chỉ đếm requestSource = "eyeball" (bẫy C0: lượt trượt Cache API của Worker bị ghi thành 504). |
| NFR-ERR-03 | Là agent, tôi muốn lỗi đã có dấu vân tay bị chặn ngay lúc viết, để không đẩy lên CI rồi mới biết. | Given tôi vừa ghi một file có U+2014 When hook PostToolUse chạy Then bị chặn (F2). |
| NFR-ERR-04 | Là người vận hành, tôi muốn lỗi runtime của Worker có chỗ để đọc. | Given một Worker trong repo When CI chạy Then cấu hình wrangler phải khai [observability] (C12). |
| NFR-ERR-05 | Là chủ repo, tôi muốn việc thu sổ chạy tự động, để sổ không cũ đi. | Given có lượt đỏ mới When workflow sổ lỗi chạy Then dòng mới vào sổ, dấu vân tay đã biết được nhận ra, dấu vân tay mới được nêu ra. |
Hiện trạng: hai tầng
Tầng 2, sổ rà tay (đã có trên main). Hai trang, cùng khuôn: bảng 30 dòng, gom theo dấu vân tay, nguyên nhân gốc, chốt chặn.
| Sổ | Nguồn | Đáng nhớ |
|---|---|---|
| ci-error-ledger | Log job đỏ của GitHub Actions, 27.09 - 12.10.2026 | F1 vượt mốc qc-scan, F2 gõ thẳng U+2014, F3 gác Supabase bắt nhầm (đã gỡ), F4 PR đỏ vẫn merge, F5 site không có job build trong PR, F6 deploy hạ tầng, F7 startup_failure do thanh toán GitHub Actions |
| cf-error-ledger | GraphQL Analytics của Cloudflare, 06 - 12.10.2026 | C0 lọc eyeball, C1 slug JTBD có dấu gây 502, C12 Workers Logs trống vì không Worker nào khai [observability] |
Tầng 1, thu tự động: đã chạy từ 13.10.2026. scripts/error-ledger.mjs + .github/workflows/error-ledger.yml: mỗi dấu vân tay lỗi là một issue nhãn error-ledger, lỗi đã đóng mà quay lại thì tự mở lại với nhãn error-ledger-repeat. Chi tiết: error-ledger-auto.
Tests
| Mã | Cách kiểm | Trạng thái |
|---|---|---|
| NFR-ERR-01 | Rà tay theo khuôn ở ci-error-ledger.md | Tự động (error-ledger.yml, workflow_run + quét hằng ngày) |
| NFR-ERR-02 | Truy vấn mẫu ở mục "Cách rà lại" của cf-error-ledger.md | Thủ công |
| NFR-ERR-03 | scripts/hooks/post-edit-guards.mjs (PostToolUse, F2), scripts/hooks/stop-guards.mjs (Stop, qc-scan --check, F1); ở CI là npm run check:emdash và qc-scan | Có gác |
| NFR-ERR-04 | scripts/check-worker-observability.mjs trong job guards | Có gác |
| NFR-ERR-05 | node scripts/error-ledger.mjs --self-test trong job guards; bước Cloudflare đỏ khi nguồn trống | Có gác (bước Cloudflare chờ token có quyền Analytics Read) |
Khoảng trống
- F4 (PR đỏ vẫn merge) không chặn được từ repo: cần bật required status checks ở cài đặt nhánh.
- F7 là lỗi thanh toán GitHub, ngoài tầm repo.
- C2, C5, C6 chờ Workers Logs (C12 vừa bật) để có stack và
Referer.