Kế hoạch chuyển đổi

Mục tiêu: www và nội dung của nó (trang, tin tức, thông báo, playbook) sống ở repo conan-web, soạn bằng Conan CMS. Phần còn lại của nền tảng ở lại conanplatform.

Trạng thái

Giai đoạn	Việc	Trạng thái
1	Dựng repo, khung các app, sửa theo rà soát	Xong
2	Các project Cloudflare, D1, tên miền, Access	Đang làm
3	Ngày cắt: www deploy từ repo này, gỡ khỏi conanplatform	Chưa
4	Chuyển dữ liệu tin tức, thông báo, playbook sang api-cms, đổi www sang đọc api-cms	Chưa

Đổi trạng thái thì sửa bảng này trong cùng PR với thay đổi đó.

Giai đoạn 1: dựng repo và khung (xong)

• Tách www.conan.school/ và packages/design-system/ sang repo conan-web.
• Dựng cms.conan.school/, api-cms.conan.school/, cms-docs.conan.school/, và gói hợp đồng packages/cms-contract/.
• ci.yml với các gác và job build cho từng app. CI chỉ kiểm, không deploy.
• Chép các luật áp dụng được từ conanplatform/CLAUDE.md sang CLAUDE.md của repo này.
• Sửa theo rà soát: khoá lạc quan If-Match, gác CSRF ở Pages Function và 415 ở api-cms, phân trang con trỏ cho danh sách quản trị, bản lịch sử dạng { action, entry }, hợp đồng dùng chung.

Giai đoạn 2: các project Cloudflare (đang làm)

Không có khoá Cloudflare nào trong GitHub. Mọi việc dưới đây làm ở dashboard Cloudflare, bằng tài khoản của chủ repo. Cấu hình build lấy đúng từ bảng ở Deploy và cấu hình.

• Cài ứng dụng GitHub của Cloudflare cho repo conan-web.
• Tạo D1 conan-cms, ghi database_id thật vào api-cms.conan.school/wrangler.toml và merge.
• Nối Worker api-cms-conan-school bằng Workers Builds. Lượt build đầu áp 0001_init.sql rồi deploy.
• Tạo Pages Git cms-conan-school và cms-docs-conan-school, production branch main.
• Đặt watch paths cho từng project, gồm cả các gói trong packages/ mà app dùng.
• Gắn tên miền cms.conan.school và cms-docs.conan.school cho hai Pages project.
• Cài Cloudflare Access cho cms.conan.school và điền hai biến của api-cms. Xem Cài Cloudflare Access.

Xong khi: đăng nhập được CMS, tạo và xuất bản được một bài thử, và api-cms.conan.school/public/<collection> trả bài đó.

Giai đoạn 3: ngày cắt www

Hiện www deploy từ conanplatform vào Pages ww3-conan-school (upload trực tiếp, không đổi sang Git được). Tên miền www.conan.school đi qua Worker cầu nối conan-www-stale-asset-bridge (www.conan.school/edge-hotfix/), Worker này chuyển mọi request tới DEPLOYMENT_ORIGIN, tức https://ww3-conan-school.pages.dev. Vì vậy project nào đang phục vụ production là do Worker cầu nối quyết định, không phải do tên miền.

Rủi ro chính: hai repo cùng có www. Còn conanplatform deploy www thì một sửa đổi merge bên đó vẫn "deploy xanh", chỉ là vào một project không còn ai xem, hoặc tệ hơn, nếu cầu nối vẫn trỏ về ww3, bản đó đè lên bản của repo này. Không có gì báo lỗi.

Làm theo đúng thứ tự, trong cùng một buổi:

1. So www ở hai repo. www.conan.school/ ở đây phải gồm mọi thay đổi đã merge vào main của conanplatform từ ngày tách. Build ở đây xanh với bản mới nhất (npm run typecheck && npm run build).
2. Tạo Pages Git mới cho www ở dashboard Cloudflare, theo dòng www của bảng Deploy và cấu hình. Kiểm biến môi trường và compatibility flags của project mới khớp với ww3-conan-school (www cần nodejs_compat). www.conan.school/wrangler.toml vẫn ghi name = "ww3-conan-school": đổi theo tên project mới trong cùng PR.
3. Kiểm bản preview ở <project mới>.pages.dev: trang chủ, /courses, /books, một trang cộng đồng, /en. Mấy trang có dữ liệu từ api.conan.school phải có nội dung thật, không phải "đang được cập nhật".
4. Trỏ Worker cầu nối sang project mới. Đổi DEPLOYMENT_ORIGIN trong www.conan.school/edge-hotfix/src/index.ts thành https://<project mới>.pages.dev rồi deploy Worker cầu nối.
5. Merge PR gỡ www khỏi conanplatform trong cùng khung giờ: dac2205/conanplatform#454 (đang để nháp). PR này gỡ www.conan.school/, deploy-www.yml, deploy-edge-bridge.yml và job www khỏi CI bên đó. Gộp sớm hơn là www mất đường deploy; gộp muộn hơn là còn một đường deploy thứ hai.
6. Kiểm production. Mở www.conan.school, xem nguồn trang: tên file asset (/assets/...) phải trùng với bản ở <project mới>.pages.dev. Worker cầu nối giữ HTML trong cache tới 60 giây, nên chờ một phút rồi mới so. Kiểm lại vài trang như ở bước 3.

Chưa chốt: đường deploy của Worker cầu nối

Hiện Worker cầu nối deploy bằng deploy-edge-bridge.yml của conanplatform, và PR #454 gỡ workflow đó. Ở repo này nó chưa có dòng nào trong bảng triển khai. Phải chốt trước ngày cắt: nối www.conan.school/edge-hotfix vào Workers Builds (thêm dòng vào bảng ở CLAUDE.md và ở Deploy và cấu hình), hoặc dùng lượt deploy cuối của workflow bên conanplatform cho bước 4 rồi mới merge #454. Không deploy nó từ máy.

Quay lui: đổi DEPLOYMENT_ORIGIN về https://ww3-conan-school.pages.dev và deploy lại Worker cầu nối. Project ww3-conan-school vẫn giữ bản deploy cuối cùng, nên quay lui không cần build lại gì. Giữ project đó ít nhất vài tuần sau ngày cắt.

Xong khi: www deploy từ conan-web, Worker cầu nối trỏ project mới, và conanplatform không còn thư mục www.conan.school/ hay workflow nào chạm tới www.

Giai đoạn 4: chuyển dữ liệu sang api-cms

Làm lần lượt từng bộ sưu tập, không làm cả ba một lúc: tin tức, rồi thông báo, rồi playbook. Trang (pages) là loại mới, không có dữ liệu cũ để chuyển.

Với mỗi bộ sưu tập:

1. Đếm số bài ở api.conan.school (cả hai họ bảng legacy_* và không tiền tố, nếu có).
2. Viết script xuất dữ liệu cũ thành file trong repo, rồi chuyển thành migration 000N_*.sql cho conan-cms. Nội dung đi vào repo trước, D1 sau, do lệnh deploy của Workers Builds áp. Không chèn từ máy.
3. Giữ nguyên slug. Đổi slug là mọi đường dẫn đã chia sẻ và đã vào Google thành trang lỗi.
4. Sau khi migration áp xong, đếm lại ở api-cms. Hai con số phải bằng nhau.
5. Đổi loader của www (danh sách và trang chi tiết) sang api-cms.conan.school/public/....
6. Mở www, so từng trang mẫu với bản cũ. Kiểm sitemap vẫn khai đủ URL.
7. Báo người soạn từ nay soạn bộ sưu tập này ở CMS. Khoá việc soạn bộ đó ở admin cũ.

Bẫy cần nhớ: một loader catch lỗi rồi trả danh sách rỗng sẽ hiện "đang được cập nhật" khi api-cms hỏng. Trang trông khoẻ mạnh mà không có bài nào. Loader mới phải để lỗi hiện ra là lỗi.

Xong khi: www không còn đọc tin tức, thông báo, playbook từ api.conan.school.

Ngoài phạm vi

Khoá học, sách, cộng đồng, sự kiện, JTBD vẫn ở api.conan.school. www tiếp tục đọc chúng qua HTTP. Hai repo chỉ nối với nhau bằng API, không import mã của nhau, không đọc D1 của nhau.