Anisonary 是以 Astro + strict TypeScript 建立的動畫歌曲目錄，按季度與日本編輯播出日瀏覽作品、OP 與 ED。網站輸出為純靜態資產，正式交付使用 Cloudflare Workers Static Assets；它不是 Cloudflare Pages，也沒有 application Worker backend。下方同時保留 English technical notes。
This repository contains the completed static product: season directory, anime detail pages, traceable OP／ED credits and links, per-song source ledgers, source-attributed media, local-only cross-season search, privacy-bounded offline reading, a GitHub correction flow, and deployment through Cloudflare Workers Static Assets. The default catalogue covers twenty-eight reviewed snapshots across 2019–2026, with 1,917 unique titles and 4,229 known OP／ED records. The 2019 summer snapshot currently contains 38 TV titles and four web series; that quarter is still being expanded, and 2025 fall is not yet included. Fictional Mock Data remains test-only.
目前 source 版本：v1.31.1。歌曲頁顯示與藝人欄不同的已審閱演唱 credits，包括個別演唱者、角色與合成歌聲；與藝人欄完全相同的名稱不重複列出，純音樂及未核對 credits 保持原有資料。2019 夏季仍為 42 套作品、103 筆歌曲，正在補充；2025 秋季尚未收錄。歌曲、來源、核對日期與公開 API 內容保持不變。
導覽延續固定五個入口與年代、年份、季度目錄；搜尋可按動畫、歌曲、創作者、年份、季度及 OP／ED 篩選，每頁顯示 12 套作品。搜尋完全在瀏覽器內進行，YouTube 只於明確操作後連線。網站與同源靜態 JSON API 共用已審閱資料，無 application backend 或 database binding。依賴安全 gate 繼續鎖定 fast-uri 3.1.6 並稽核開發依賴。
Production build 會從最終 HTML 自動產生 hash-based Content Security Policy。政策不使用 unsafe-inline 或 unsafe-eval，禁止 inline event／style attributes，只開放同源資產、已核對的海報來源及使用者啟動後的 YouTube privacy-enhanced iframe。任何未批准的 media origin 會令 build fail closed。
| 可用性 / Availability | 成熟度 / Maturity | 證據 / Evidence |
|---|---|---|
| 公開靜態目錄 / Public static catalogue | Source 版本為 v1.31.1；正式發布狀態以對應 Release 驗收摘要為準 |
入口網站 / Live · 版本與驗收 / Releases · 資料來源 / Sources · 安全政策 / Security · 授權 / Licence · 版權 / Copyright |
| Layer | Technology and responsibility |
|---|---|
| Application | Astro 7 static output、semantic HTML、repository-owned CSS 與少量 browser JavaScript |
| Language／tooling | TypeScript 6（Astro strictest）、Node.js 22、npm lockfile |
| Delivery | Cloudflare Workers Static Assets、Wrangler 4、optional Workers Builds Git integration |
| Build safeguards | Generated hash-based CSP、bounded Service Worker、same-origin static JSON API、sitemap |
| Testing | Astro check、Vitest 4、Playwright 1.62、Wrangler deployment dry-run |
| Runtime services | 無 application Worker、database、object storage、analytics、authentication、payment 或 AI model |
完整用途、版本來源與官方技術參考見 docs/TECHNOLOGY_REFERENCES.md；公開資料流與信任邊界見 docs/ARCHITECTURE.md。
npm install
npm run devQuality checks:
npm run lint
npm test
npm run build
npm run cf:check
npx playwright install chromium
npm run test:e2e
npm run checkPublic API production check（production deployment required）：
PUBLIC_API_BASE_URL=https://anisonary.k-y.cc/api/v1 npm run api:check- With no
PUBLIC_API_BASE_URL, the site builds from the repository's reviewedCuratedProviderrecords and publishes the same public fields as static JSON assets. - When
PUBLIC_API_BASE_URLis set,ApiProviderrequests that public read-only contract through a fail-closed nested contract, URL, identity and timeout gate. MockProviderremains available only for isolated unit and component tests; its fixtures are not production assets.- Copy
.env.exampleto.envfor local configuration. Never commit secrets.
Season coverage uses a repository-owned source registry: Annict is the Japanese seasonal inventory baseline, while Bangumi provides a Chinese-entry cross-check. The twenty-eight published snapshots additionally cross-check Traditional Chinese calendar inventories, AniList identifiers and media, AnimeThemes records, public theme-song indexes, official sites, and Taiwan／Hong Kong licensing pages. These are editorial inputs only; production builds use the reviewed static snapshot and never require external APIs at runtime. See docs/DATA_SOURCES.md for the inventory rules and docs/DATA_PROVENANCE.md for the per-song ledger and media boundary.
/catalog/groups published years by decade;/catalog/<year>/lists only that year's published quarters. The main menu stays at five links as coverage grows;- year and quarter navigation is generated from the reviewed registry; cross-season works keep one detail page and every published season membership;
/search/embeds a bounded, text-only JSON index in static HTML and renders up to 12 anime results per page;- combine anime, song, or creator scope with year, quarter, and OP／ED filters; song links open the corresponding theme and its credits;
- the index is limited to 10,000 unique works, 20,000 seasonal references, and 8 MiB of serialized UTF-8 data. Larger catalogues require a reviewed indexing change; these are safety ceilings, not promised device capacity;
- native year／quarter links remain usable without JavaScript;
- filtering runs locally without query parameters, analytics, cookies, or a search API;
- the text-only result list does not load remote poster media;
- YouTube connects only after the user activates a clearly labelled consent button;
- Japanese and Traditional Chinese remain the primary visible languages, with English／Romaji support where available.
- production build 產生具內容版本的
/sw.js，只預先保存公開、同源、無 query string 的靜態內容； - navigation 維持 network-first，連線失敗時才讀取同一路徑快取或
/offline/； - 不建立 runtime cache entry，因此搜尋字詞、私人 response 與瀏覽路徑不會因操作而被寫入 Cache Storage；
/api/、404、第三方 poster 及 YouTube 媒體不在 precache 內；舊 Mock raster assets 已從 repository 移除；/manifest.webmanifest提供繁體中文 app metadata 與英文名稱支援。
PUBLIC_API_BASE_URL=
PUBLIC_SITE_URL=https://anisonary.k-y.cc
PUBLIC_DEFAULT_SEASON=2026-summer
PUBLIC_TIMEZONE=Asia/Tokyo
ANISONARY_REQUIRE_API_DATA=false
The default production build needs no API environment variable. PUBLIC_API_BASE_URL=https://anisonary.k-y.cc/api/v1 with ANISONARY_REQUIRE_API_DATA=true is reserved for the explicit live contract gate, where any unavailable or inconsistent endpoint must fail closed.
GET /api/v1/seasons.jsonreturns the reviewed season summaries;GET /api/v1/seasons/:seasonId.jsonreturns one reviewed season and its anime cards;GET /api/v1/anime/:slug.jsonreturns one reviewed anime, OP／ED records, public links and sources;- unknown season IDs and slugs return
404; - API assets use revalidation,
noindex, no permissive CORS, and stay outside the sitemap and offline precache.
The primary delivery path is Cloudflare Workers Static Assets. main is the production branch; non-production branches use version uploads for preview validation. GitHub Actions remains an independent quality gate and does not deploy.
Build: npm run build
Output: dist
Node: 22
Domain: anisonary.k-y.cc
Local preview and explicit deployment commands:
npm run cf:dev
npm run cf:check
npm run cf:preview
npm run cf:deploySee docs/DEPLOYMENT_CLOUDFLARE.md before changing build ownership or production settings.
Production domain: https://anisonary.k-y.cc. Non-production Cloudflare hostnames are marked noindex and are not recorded in public documentation; the retired Pages project is no longer part of the delivery path.
本 repository 的專案自有軟件部分依 Apache License 2.0 提供； curated catalogue records、來源 ledger、目錄編排、品牌及第三方內容不在該授權 範圍內。自行部署前先閱讀
LICENSING.md，並移除或替換你沒有 權利使用的目錄資料與媒體。
wrangler.jsonc目前指向本專案的正式 Worker 名稱與 custom domain。Fork 或 clone 後，不要直接執行npm run cf:deploy；先換成你自己的公開 Worker 名稱與 hostname，或移除routes只使用自己的workers.devhostname。
最短流程：
- 準備 Node.js 22、npm、Cloudflare account；custom domain 只在你擁有並已加入 Cloudflare 的 zone 上設定。
- 執行
npm ci，複製.env.example為不受 Git 追蹤的.env，把PUBLIC_SITE_URL換成自己的最終公開 URL；正常靜態 build 保持PUBLIC_API_BASE_URL空白。 - 在
wrangler.jsonc設定唯一 Workername。只用workers.dev時移除專案原有routes；使用 custom domain 時把 route 換成自己擁有的 hostname。同時更新public/robots.txt內的 sitemap hostname。 - 先執行
npm run lint、npm test、npm run build、npm run cf:check；需要完整 browser gate 時再安裝 Chromium 並執行npm run test:e2e。 - 以
npx wrangler login登入，私下確認npx wrangler whoami的 account 正確，再執行npm run cf:deploy。不要把登入輸出、API token 或 account metadata 貼到 issue、commit 或公開 log。 - 部署後核對首頁、搜尋、季度頁、動畫詳情、未知
404、security headers 與/api/v1/seasons.json；最後以自己的 URL 執行 live API contract gate。
完整的 workers.dev、custom domain、Workers Builds、驗收、rollback 與私隱檢查步驟見 docs/SELF_HOSTING.md。專案維護者的 production release 流程另見 docs/DEPLOYMENT_CLOUDFLARE.md。Apache-2.0 只授權軟件部分，不授予 curated catalogue 或第三方動畫資料、商標、圖片及影片的重用權；來源條款閘門見 docs/SOURCE_TERMS.md。
由 kyeunga25 擁有或有權授權的應用程式原始碼、元件、樣式、通用 provider／
schema、建置／驗證腳本、測試邏輯及通用技術文件，依
Apache-2.0 提供。
Curated catalogue records、來源 ledger、目錄選取／編排、審閱註記及其在測試、 文件、建置產物、static API 或頁面中的複本，沒有由 Apache-2.0 或開放資料 授權覆蓋。動畫、歌曲、錄音、海報／圖片、影片、credits、商標、外部內容及 Anisonary 品牌亦不在授權內。
Repository-owned application code, components, styles, generic provider and schema code, build and validation scripts, test logic, and generic technical documentation are licensed under Apache-2.0. Curated catalogue records, source ledgers, editorial selection and arrangement, embedded copies, third-party anime or music material, and Anisonary branding are excluded.
完整路徑與重用規則見 LICENSING.md、
COPYRIGHT.md、NOTICE 及
THIRD_PARTY_NOTICES.md。
- Public product scope and release status:
docs/PROJECT_PLAN.md - Static architecture and trust boundaries:
docs/ARCHITECTURE.md - Privacy-safe Cloudflare self-deployment:
docs/SELF_HOSTING.md - Technology, AI and reference disclosure:
docs/TECHNOLOGY_REFERENCES.md - Song and media provenance contract:
docs/DATA_PROVENANCE.md - Version history:
CHANGELOG.md - v1.26.0 2019 fall catalogue QA:
docs/QA_V1_26_2019_FALL.md - v1.25.0 2020 winter catalogue QA:
docs/QA_V1_25_2020_WINTER.md - v1.24.0 2020 spring catalogue QA:
docs/QA_V1_24_2020_SPRING.md - v1.23.0 2020 summer catalogue QA:
docs/QA_V1_23_2020_SUMMER.md - v1.22.0 2020 fall catalogue QA:
docs/QA_V1_22_2020_FALL.md - v1.21.0 2021 winter catalogue QA:
docs/QA_V1_21_2021_WINTER.md - v1.20.0 2021 spring catalogue QA:
docs/QA_V1_20_2021_SPRING.md - v1.19.0 2021 summer catalogue QA:
docs/QA_V1_19_2021_SUMMER.md - v1.18.0 2021 fall catalogue QA:
docs/QA_V1_18_2021_FALL.md - v1.2.0 theme-source and public-score-removal QA:
docs/QA_V1_2_PROVENANCE.md - v1.1.0 2026 winter／2025 summer catalogue QA:
docs/QA_V1_1_SEASON_EXPANSION.md - v1.0.0 static API and stable release QA:
docs/QA_V1_STATIC_API.md - Phase 2 catalogue scope and source ledger:
docs/PHASE2_CATALOG.md - v0.4.0 complete 2026 spring／summer catalogue QA:
docs/QA_2026_SPRING_SUMMER_CATALOG.md - v0.2.0 search and media privacy QA:
docs/QA_PHASE2_SEARCH_PRIVACY.md - v0.3.0 offline static catalogue QA:
docs/QA_PHASE2_OFFLINE_STATIC.md - Content Security Policy build 與 browser QA:
docs/QA_CONTENT_SECURITY_POLICY.md - Stable Japanese and Chinese seasonal source registry:
docs/DATA_SOURCES.md - Visual system and accepted concepts:
docs/DESIGN_SYSTEM.md - M0–M6 QA evidence:
docs/QA_PHASE1_M0_M6.md - M7 quality QA evidence:
docs/QA_PHASE1_M7.md - Phase 1 completion gate and historical measurement boundary:
docs/QA_PHASE1_COMPLETION.md - GitHub and Cloudflare delivery requirements:
docs/DEPLOYMENT_CLOUDFLARE.md - Public static API contract:
docs/API_HANDOFF.md - Public static API v1 production check:
docs/API_PRODUCTION_CHECK.md
The public repository must not contain crawlers, database dumps, unpublished data, secrets, private source adapters, private source-selection rules, or internal confidence rules.
- Deployment／部署： Cloudflare Workers Static Assets、Wrangler 與 optional Workers Builds。Repository 的
dist是唯一部署輸出；GitHub Actions 只作獨立品質檢查。 - Core stack／核心技術： Astro static output、TypeScript、Node.js、Vitest 及 Playwright。Browser 功能使用標準 HTML／CSS／JavaScript、Service Worker 與 Content Security Policy。
- AI model／AI 模型： 無（None）。Production、build、搜尋、static API、目錄資料及圖片流程都不呼叫或綁定 AI 模型，也不需要 AI API key；AI 生成的目錄記錄與圖片不作公開資料來源。
- Catalogue references／目錄參考： 動畫官網、製作／發行／播出單位等第一方資料是最終核對基準；Annict、Bangumi、AniList、AnimeThemes、UZUREA、公開繁中季度表及台灣／香港正式授權頁只作 inventory、identity、media 或交叉核對。完整角色、限制與更新規則見
DATA_SOURCES.md及DATA_PROVENANCE.md。這些來源不會在 production runtime 被即時查詢。 - Source terms／來源條款： 只使用文件化 API 或一般公開頁面，不保存 raw API dump、不收集 user data、不建立 mirror／backup／tracker，也不下載或重新託管第三方媒體；逐來源限制及停止條件見
SOURCE_TERMS.md。 - Disclosure boundary／披露邊界： 公開文件只列可重現的技術與公開來源，不記錄 prompts、對話、個人資料、真實 account／resource identifiers、keys、database 結構、private adapters 或內部評分規則。更完整的依賴與參考索引見
TECHNOLOGY_REFERENCES.md。