accounts/docs/cms/migration-guide.md

迁移至 XControl CMS 的实施指南

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

迁移准备

1. 梳理现有页面：整理旧系统的路由、模板和数据源，并标注关键依赖（例如第三方 API、Webhook）。
2. 建立对照表：在项目 wiki 中维护“旧页面 → 新模板”的映射，明确所需内容源与扩展。
3. 同步配置：将上述映射写入 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 校验；
• ✅ 预览环境可完整渲染所有页面；
• ✅ 灰度发布通过性能、监控、无障碍检查；
• ✅ 回滚演练至少一次，确保运维手册可执行。