* docs: maintenance mode — policy, triage bot, issue forms, status badge, docs for 2.3.0 From v2.3.0 the project takes no new features (CONTRIBUTING.md, in Vietnamese and English). Accepted: scheduled dependency updates; security fixes (High/Critical advisories, runtime vulnerabilities); major language/runtime/framework upgrades; bug fixes including UI/UX and accessibility; language fixes. - .github/workflows/triage.yml + scripts/triage.mjs (unit-tested): an issue or pull request whose title or label asks for a feature is labelled enhancement + out-of-scope, answered in both languages and closed (issues as "not planned"). The owner's items, bots, `maintenance-exception` and anything the owner does are left alone. It runs on pull_request_target but checks out only that one script from the default branch, never a pull request's code; workflow_dispatch is a dry run. - Issue forms: blank issues off, questions and ideas to Discussions, security to the private policy; a new language-problem form; the bug form no longer claims the site's report button fills it (those reports go to a private repository). The pull request template asks which of the five kinds of change it is. - README: a maintenance-mode badge and a Status section; the admin paragraph describes auto-publish. SECURITY.md: High/Critical fixes ship out of schedule; the age-check answer is local storage only. - Docs: decisions D21–D24, maintenance policy and cadence (17 §0, QODANA_TOKEN rotation), roadmap frozen, CI (Qodana, whole-tree licences, triage, merge rules), architecture tree, the Workers Builds deploy command, licence notes without the stale license-checker/GSAP lines. - CHANGELOG [2.3.0]; sonar.projectVersion 2.3.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: link #138 in the 2.3.0 changelog Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: album labels come from both language entries Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(ci): triage without a checkout, and linear title patterns SonarCloud and Qodana on #139: - githubactions:S7631 flags any checkout in a pull_request_target workflow, even of the default branch. The workflow now reads scripts/triage.mjs from the default branch through the API and imports it from a data: URL — nothing is checked out at all. - javascript:S8786: `\s+a?\s*` let two quantifiers compete for the same spaces. The title is trimmed once and the patterns are written so no two quantifiers overlap. - Qodana RegExpRedundantEscape: the bot check is `endsWith("[bot]")`, no regex. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
8.0 KiB
8.0 KiB
poli0981.dev — Documentation Suite
- Phiên bản suite: v2.0 · Ngày: 2026-10-24 (v1.0: 2026-07-17)
- Repo:
poli0981/poli0981-dev(public từ 10/2026) · nội dung:poli0981/content(submodulesrc/content) · Domain:poli0981.dev - Lịch sử thay đổi theo phiên bản:
CHANGELOG.mdở gốc repo. - Ngôn ngữ tài liệu: tiếng Việt (thuật ngữ kỹ thuật giữ tiếng Anh). Riêng
12_LEGAL/soạn song ngữ EN/VI vì là văn bản sẽ render trên site. - Tài liệu gốc:
poli0981.dev_proposal.md(bản đề xuất v0.1, đã được duyệt).
Danh sách file
| # | File | Nội dung |
|---|---|---|
| 00 | 00_INDEX.md | File này — mục lục + nhật ký quyết định |
| 01 | 01_PRD.md | Mục tiêu, phạm vi, yêu cầu, bảng truy vết requirement |
| 02 | 02_ARCHITECTURE.md | Stack, cấu trúc repo, rendering, i18n, wrangler, ADR |
| 03 | 03_DESIGN_SYSTEM.md | Token màu/chữ/spacing, motion, component inventory |
| 04 | 04_CONTENT_MODEL.md | Content Collections, schema, quy trình viết, EXIF |
| 05 | 05_SITEMAP_UX.md | Route map, wireframe từng trang, legal gate, mobile nav |
| 06 | 06_SECURITY.md | Headers/CSP, form, rate limit, secrets, supply chain |
| 07 | 07_CLOUDFLARE_SETUP.md | Hướng dẫn set Cloudflare từng bước |
| 08 | 08_CI_CD.md | Workflows, permissions, deploy, Dependabot, hooks |
| 09 | 09_ERROR_PAGES_OFFLINE.md | 404/403/429/5xx/offline + cách test |
| 10 | 10_BUG_REPORT_PIPELINE.md | Console capture → GitHub Issue + Discord |
| 11 | 11_WIDGETS_INTEGRATIONS.md | YouTube/Steam/GitHub widgets, cron worker, KV |
| 12 | 12_LEGAL/ | 5 văn bản song ngữ (xem dưới) |
| 13 | 13_SEO_RSS_OG.md | Meta, hreflang, sitemap, RSS, OG image, AI crawlers |
| 14 | 14_PERF_BUDGET.md | Ngân sách hiệu năng + kỷ luật islands |
| 15 | 15_ROADMAP.md | P0 spikes, phase P1–P4, launch checklist |
| 16 | 16_COST.md | Chi phí chốt + ngưỡng cần theo dõi |
| 17 | 17_MAINTENANCE.md | Lịch bảo trì, update playbook, backup |
12_LEGAL/: TERMS_OF_USE.md · PRIVACY_POLICY.md · DISCLAIMER.md · THIRD_PARTY_NOTICES.md · CONTENT_LICENSE.md — bản nháp gốc (07/2026). Văn bản đang hiệu lực là legal/*.md trong repo poli0981/content (render ở /legal/*); sửa ở đó, không sửa ở đây. Hai trang thêm sau (ai-usage, accessibility) chỉ có ở repo content, không có bản nháp tại đây.
Nhật ký quyết định (chốt 2026-07-17, cập nhật 2026-11-10)
| # | Quyết định | Chọn |
|---|---|---|
| D1 | Framework/hosting | Astro 7 + Svelte 5 islands, Cloudflare Workers + Static Assets |
| D2 | Quy trình viết | Markdown + Git (repo poli0981/content). Từ 10/2026 thêm admin tự viết ở admin.poli0981.dev (soạn/sửa → commit repo content; Xuất bản → workflow content-bump.yml mở PR bump submodule + auto-merge). Không Keystatic/CMS bên thứ ba |
| D3 | Q&A | FAQ tĩnh + liên hệ qua social/contact@ — không form, không D1 |
| D4 | Ngôn ngữ | VI (mặc định, không prefix) + EN (/en/) |
| D5 | Bình luận blog | Tắt (không Giscus) |
| D6 | Legal canonical | Trên site tại /legal/*; repo public mirror poli0981/legal = tuỳ chọn sau |
| D7 | Giấy phép | Code GPL-3.0 · Nội dung All Rights Reserved |
| D8 | Error pages | Tự phục vụ từ app (không mua zone Pro) |
| D9 | API ngoài | Không weather/map; widget YouTube + Steam + GitHub qua cron worker |
| D11 | Google Workspace (MX Google), một hộp thư + alias theo chủ đề (07 §11). Không Cloudflare Email Routing |
|
| D12 | Chống bot | Cổng Turnstile trước mọi trang, vé 48 giờ (06 §3b); bot đã xác thực đi thẳng nhờ Transform Rule x-verified-bot |
| D13 | Rate limit | WAF rule (edge) → Workers Rate Limiting: RL_SITE toàn site 100/10s → bindings theo nhóm /api (06 §2, 07 §6) thay bộ đếm KV |
| D14 | Analytics | Cloudflare Web Analytics, snippet thủ công chỉ ở bản build production (07 §12) |
| D15 | Admin | admin.poli0981.dev sau Cloudflare Access + Worker tự kiểm JWT (≤ 24 giờ, email phải có trong ADMIN_EMAILS — thiếu là từ chối); token GitHub chỉ ghi repo content; ảnh → Images binding → R2; mọi thao tác ghi audit log (06 §9) |
| D10 | Data services | KV (cache widget + ảnh widget mirror cho /ext-img, denylist một khoá, audit log admin) + R2 poli0981-media cho ảnh upload qua admin (từ 10/2026; AVIF/WebP sinh một lần lúc upload, phục vụ qua /media, cache 1 năm). Không D1. Ảnh build-time cũ vẫn ở src/assets/ |
| D16 | Palette & theme (10/2026) | Glacier Teal (xanh đêm + teal) thay palette ấm; theme mặc định theo hệ điều hành, nút 3 trạng thái hệ thống/sáng/tối (03 §2, §6) |
| D17 | Toolchain (10/2026) | Node 26 · TypeScript 7 (tsc kiểm kiểu) chạy song song TypeScript 6 (astro check, typescript-eslint, svelte2tsx cần JS API) · test bằng node:test (không thêm deps) · SonarCloud phân tích qua CI (08 §0) |
| D18 | Báo lỗi (10/2026) | Issue tạo ở repo private poli0981/site-reports (repo site đã public) — 10 §4 |
| D19 | Phát hành | Tag vX.Y.Z có ký GPG + GitHub Release + CHANGELOG.md; deploy vẫn là "merge main" (08 §8) |
| D20 | Trợ năng (11/2026, v2.2.0) | Mục tiêu WCAG 2.2 AA — kim chỉ nam, không tự nhận đã được kiểm định. Tuyên bố cho khách ở /legal/accessibility (song ngữ, repo content); ACCESSIBILITY.md ở root là bản của repo kèm ghi chú cho người sửa code (trang site thắng nếu lệch). Rào cản báo về accessibility@ hoặc nút "Báo lỗi". Cổng tự động: npm run test:a11y (axe-core + bàn phím + reflow + forced-colors, Playwright lái Chrome có sẵn) chạy trong check bắt buộc build (08 §0, checklist ở 03 §8) — ngoại lệ có chủ đích của D17 "không thêm deps cho test" |
| D21 | Chế độ bảo trì (11/2026, v2.3.0) | Không thêm tính năng mới. Chỉ nhận: deps định kỳ · vá bảo mật (High/Critical, lỗ hổng runtime) · nâng cấp lớn ngôn ngữ/runtime/framework · sửa lỗi (UI/UX, a11y) · sửa lỗi ngôn ngữ. Bot triage.yml gắn enhancement + out-of-scope và đóng đề xuất tính năng; ngoại lệ = nhãn maintenance-exception (CONTRIBUTING.md, 17 §0) |
| D22 | Nhãn nội dung & tuổi (11/2026) | contentWarning từ danh sách cố định 11 nhãn (src/lib/content-labels.ts) cho blog/truyện/album/từng ảnh + ageRating 13+/16+/18+. Banner; ảnh mờ bằng CSS (:has(), chạy khi tắt JS); hỏi tuổi bằng <dialog> gốc, không tự bật, câu trả lời chỉ ở localStorage ageGate (mốc tuổi, không ngày sinh) — Privacy §6 (04 §2) |
| D23 | Xuất bản tự động (11/2026) | Mỗi lần lưu/xoá trong admin tự dispatch content-bump.yml; build ghi __CONTENT_COMMIT__ ⇒ /api/health có version.content, admin phân biệt "đã merge" với "đã lên web". Điều kiện: Workers Builds deploy main (07 §9) |
| D24 | Chất lượng (11/2026) | Thêm Qodana (Ultimate, Qodana for JS, ngưỡng 0) cạnh SonarCloud. License: kiểm toàn bộ package-lock.json, ngoại lệ theo gói có lý do (scripts/license-policy.mjs) — license audit của Qodana cần Ultimate Plus nên không dùng (08 §0) |
Cách dùng suite
15_ROADMAP.mdcó trạng thái từng phase (P0–P3 đã xong, P4 launch đang chạy) và hướng đi tiếp.07_CLOUDFLARE_SETUP.mdlàm một lần khi mua domain, tick checklist cuối file.- Mỗi file có mục Trạng thái/Checklist riêng khi áp dụng — suite này là nguồn sự thật, cập nhật khi quyết định thay đổi.
- Lưu ý chung: phiên bản package ghi trong suite là bản đang dùng tại 2026-10-24 (
02§2);package.json+ lockfile mới là nguồn sự thật.