# 迁移至 XControl CMS 的实施指南

本文梳理了从旧版静态页面体系迁移到全新 CMS 架构的步骤，并提供回滚方案以保障发布安全。

## 迁移准备

1. **梳理现有页面**：整理旧系统的路由、模板和数据源，并标注关键依赖（例如第三方 API、Webhook）。
2. **建立对照表**：在项目 wiki 中维护“旧页面 → 新模板”的映射，明确所需内容源与扩展。
3. **同步配置**：将上述映射写入 [`config/cms.json`](../../config/cms.json)，并针对每个模板准备默认内容样例。

## 实施步骤

1. **搭建预览环境**：
   - 创建 `feature/cms-migration` 分支；
   - 部署独立的 CMS 预览环境，指向 `cms.json` 中定义的内容源；
   - 确保团队成员可登录并在预览中校对页面。
2. **内容迁移**：
   - 使用 `scripts/content-migrator`（TODO）或手动脚本，将旧 Markdown/HTML 转换为 CMS 支持的内容块；
   - 对照对照表验证每个页面的链接、组件与扩展生效情况；
   - 在预览环境执行冒烟测试，覆盖核心业务流（注册、下单、反馈表单等）。
3. **灰度发布**：
   - 在 CDN/网关上新增 `cms-beta` 域名，对应新的渲染服务；
   - 内部用户和部分真实流量切换到新域，收集性能及错误日志；
   - 若未出现阻塞问题，逐步放大流量并更新主域名解析。

## 回滚方案

1. **保留旧环境**：迁移期间保留旧渲染服务与静态资源，避免同名覆盖；
2. **可控切换**：所有流量切换通过网关开关或流量调度平台完成，开关命名为 `enable_new_cms`；
3. **回滚流程**：
   - 若监控中断或错误率超出阈值，立即关闭 `enable_new_cms` 将流量打回旧系统；
   - 执行 `make revert-cms-release`（脚本需在部署仓库中实现）撤销最新配置发布；
   - 将问题归档在 incident 工单，收集 `cms.json` 与扩展日志，确认修复后重新灰度。

## 里程碑检查

- ✅ 完成 `cms.json` 配置与 Schema 校验；
- ✅ 预览环境可完整渲染所有页面；
- ✅ 灰度发布通过性能、监控、无障碍检查；
- ✅ 回滚演练至少一次，确保运维手册可执行。