# CMS 内容管理系统集成评估

## 已确认决策

本次评估基于以下 grilling 会话确定的架构决策：

| 决策项 | 结论 | 影响 |
|--------|------|------|
| 部署模式 | **混合渲染（SSR/ISR）** | CMS 草稿、实时预览、一键发布可直接落地，无需每次都触发全站构建 |
| CMS 路线 | **坚持自研轻量 Headless CMS** | 基于 `src/lib/cms/` + Prisma + Next.js API 继续建设，不引入 Strapi/Payload 等开源方案 |
| RBAC 范围 | **模型级 + 操作级权限** | 支持“角色 × 内容模型 × create/read/update/delete/publish”矩阵，不做到字段级 |
| 多语言 | **现在预留 locale 字段** | `ContentItem` 默认 `zh-CN`，数据模型一次成型，未来可扩展 |
| 内容迁移范围 | **按页面类型全量迁移** | 新闻、案例、团队、产品、方案、服务、法律页全部进入 CMS，不再保留“结构层常量 + 运营字段 CMS”的混合方案 |
| 媒体存储 | **本地 + OSS 双写** | `MediaAsset` 同时支持 `local`/`oss`/`s3`，开发/测试用本地，生产用 OSS |
| 工作流通知 | **仅站内消息** | 管理后台显示待审核 badge 与通知列表，不上邮件或企业 IM |

## 评估结论

基于当前项目实际（Next.js 14 App Router + Prisma/SQLite + 已搭建但尚未完全落地的 `src/lib/cms/` 层），标准官网 CMS 的核心功能模块（内容发布、媒体管理、模板驱动、版本控制、基础权限）**能够满足当前及可预见未来的大部分需求**。本次评估不再给出单一百分比匹配度，而是按模块给出 **满足 / 部分满足 / 不满足** 的定性判断，并在“必须补齐的缺口”中按优先级排序。

**最终建议**：继续基于已有 `src/lib/cms/` 层建设一个**字段可配置、RBAC 可扩展、支持多语言预留的轻量 Headless CMS**，配合 Next.js 混合渲染（ISR）实现内容实时发布与预览。无需采购重型商业 CMS，也无需引入开源 Headless CMS 替代当前实现。

## 项目现状速览

| 维度 | 当前状态 |
|------|---------|
| 技术栈 | Next.js 14、React 18、TypeScript、Tailwind CSS、Prisma + SQLite |
| 部署约束 | **混合渲染（SSR/ISR）已确认**、Nginx 反向代理、独立子域名 |
| 内容现状 | 营销页内容仍来自 `src/lib/constants/*.ts`；CMS 数据层已定义，页面侧未全面切换；计划按页面类型全量迁移 |
| CMS 基础设施 | 已存在 `ContentModel`、`ContentItem`、`ContentZone`、`MediaAsset`、`AuditLog` 等类型，以及 `/api/admin/*`、`/api/cms/*` 路由 |
| 核心约束 | 本地字体、品牌红 #C41E3A 克制使用、移动端优先、四层叙事结构 |

## 分项匹配度评估

### 1. 内容更新频率

**项目需求**：官网内容（产品、方案、服务、新闻、案例、团队、联系信息）更新频率中等，新闻/案例相对高频，产品/方案页面相对低频但可能伴随版本迭代调整。

**匹配度：高**

- 标准 CMS 的内容发布流程（草稿 → 审核 → 发布）对新闻、案例、团队动态等中等频度更新非常合适。
- 产品/方案页面的字段化建模（`productFields`、`solutionFields` 已定义）可支持非研发人员调整文案、标签、状态等。
- 部署模式已确认为 **混合渲染（SSR/ISR）**，CMS 发布后可通过 `revalidate` 实时生效，不再受静态导出“每次更新必须全量构建”的限制。

### 2. 内容管理权限分配

**项目需求**：需要区分超管、内容编辑、市场运营等角色，避免所有人都能修改核心产品数据或法律条款。

**匹配度：中**

- 当前 API 层已有 `/api/auth/*` 与 `/api/admin/*`，但尚未实现基于角色的权限中间件（RBAC）。
- 已确认 RBAC 粒度为 **模型级 + 操作级**：即“角色 × 内容模型 × create/read/update/delete/publish”。例如“内容编辑”可以创建和修改新闻，但不能发布新闻；不能修改产品或法律条款。
- 不实现字段级权限，避免初期过度复杂；若未来确有字段级需求，可作为二期扩展。

### 3. 多角色协作编辑

**项目需求**：市场、产品、法务可能共同参与内容产出，需要审稿、留痕、避免覆盖。

**匹配度：中-高**

- 类型定义中已有 `ContentStatus`（draft/review/published/archived）、`version`、`createdBy/updatedBy`、`AuditLog`，设计层面已考虑协作。
- `review` 状态定义为：**已提交待审核**，仅拥有 publish 权限的角色可审核通过或驳回。
- 工作流通知已确认采用 **站内消息** 作为最低可用方案：管理后台显示待审核 badge 与通知列表，暂不上邮件或企业 IM。
- “内容日历”、“任务分配”等高级协作能力不在本期范围内。

### 4. 内容版本控制

**项目需求**：产品文案、法律条款、首页 Hero 等关键内容需要可回溯、可回滚。

**匹配度：高**

- `ContentItem` 已包含 `version` 字段；`hasVersions` 在模型级别已配置；`AuditLog` 记录 before/after。
- 回滚后通过 ISR `revalidate` 即可生效，无需触发全量构建。

### 5. 第三方系统集成

**项目需求**：目前可见的第三方需求主要是联系表单、微信公众号/企业微信、SEO/结构化数据、以及未来 NovaVis 等产品的文档/控制台跳转。

**匹配度：中**

- 标准 CMS 的 Webhook、API、插件生态可满足常见集成（表单通知、SEO、社交媒体）。
- **风险点**：项目有“独立子域名 + Nginx 反向代理”的硬性部署架构，若 CMS 是 SaaS 或独立服务，需要处理跨域、认证同步、静态构建时拉取内容等问题。
- 当前 `MediaAsset` 已预留 `local | oss | s3` 存储类型，说明对 OSS/CDN 已有规划，标准 CMS 的媒体管理可与此对接。

### 6. 响应式内容适配

**项目需求**：Mobile First，所有页面必须适配桌面/平板/移动。

**匹配度：高**

- 响应式主要由前端组件（Tailwind + 设计令牌）承担，CMS 只需提供“内容”而非“布局”。
- 当前 `ContentZoneSettings` 中的 `columns`、`layout` 已足够支持前端做响应式渲染。
- 若 CMS 支持按设备投放不同内容（如移动端 Hero 文案更短），会带来额外复杂度；当前项目不需要这种高级能力。

### 7. 未来功能扩展预期

**项目需求**：独立产品区、案例 L3 信任层、品牌故事页、可能的博客/白皮书下载、多语言（潜在）。

**匹配度：中**

- 当前 `content-types.ts` 已覆盖 news/service/product/solution/hero-banner/stat-item/about/team/contact/legal，扩展性较好。
- **多语言**已决定现在预留 `locale` 字段：`ContentItem` 默认 `zh-CN`，未来新增语言时只需添加翻译记录，无需重构数据模型。
- **独立产品详情页**的“硬核”风格与套装产品的字段差异较大，需要单独设计 `standalone-product` 内容模型，支持技术参数、合规认证等字段分组。

## 标准 CMS 功能模块逐项评估

| 模块 | 是否满足 | 说明 |
|------|---------|------|
| 内容发布流程 | ✅ 满足 | draft/review/published/archived 状态已设计；混合渲染下通过 ISR 实时生效 |
| 媒体资源管理 | ⚠️ 部分满足 | 已定义 `MediaAsset` 与 `local/oss/s3` 预留；需独立开发上传、缩略图、WebP/AVIF 转换、OSS 对接，工作量约 1-2 人周 |
| 模板系统 | ✅ 满足 | 项目本身四层叙事 + HSI 架构即模板系统；CMS 只需驱动内容填充 |
| 权限管理 | ⚠️ 部分满足 | 简单角色已满足；模型级 + 操作级 RBAC 需要新增权限中间件与数据模型 |
| 版本控制 | ✅ 满足 | 已设计 version + audit log；回滚后 ISR revalidate 即可生效 |
| SEO/元数据 | ✅ 满足 | 页面类型字段可扩展 meta title/description/og image |
| 多语言 | ✅ 预留满足 | 现在为 `ContentItem` 增加 `locale` 字段，默认 `zh-CN`，未来直接扩展 |
| 表单/线索管理 | ⚠️ 部分满足 | 联系表单已有独立 API；本期不纳入 CMS 统一管理 |

## 预算、技术栈与维护成本

### 预算

| 方案 | 开发成本 | 持续成本 | 本次决策 |
|------|---------|---------|---------|
| **自研轻量 CMS**（当前路线） | 中等（约 3-4 人周完成核心缺口） | 无订阅费，仅需维护 | **选中** |
| 开源 Headless CMS（Strapi/Payload/Directus） | 较低（可节省 30%-50% 开发时间） | 服务器、数据库、升级、安全补丁 | 不引入 |
| SaaS CMS（Sanity/Contentful/DatoCMS） | 最低 | 按席位/流量收费，长期不可控 | 不引入 |

### 技术栈兼容性

- **当前技术栈与混合渲染高度兼容**：Next.js 14 App Router 的 `fetch(revalidate)` + `/api/cms/revalidate` 已存在，CMS 内容发布后可直接刷新缓存。
- **Prisma + SQLite 已存在**，可直接作为 CMS 数据库；未来若流量/并发上升，可平滑迁移到 PostgreSQL，无需改动数据模型。
- `/api/cms/draft/*` 路由已存在，草稿预览能力可在混合渲染架构下直接复用。

### 维护成本

- 自研 CMS：核心功能可控，维护边界清晰；本期聚焦 RBAC、媒体管理、工作流、内容迁移四项，避免无限扩展。
- 标准 CMS：虽然管理后台成熟，但引入后会带来升级、插件兼容性、安全问题等持续投入；本次决定不引入。

## 最终建议

**当前项目不需要采购重型商业 CMS，也无需引入开源 Headless CMS 替代现有实现。** 最佳路径是：

> 基于已有的 `src/lib/cms/` + Prisma + Next.js API 路线，配合 **混合渲染（SSR/ISR）**，建设一个**字段可配置、RBAC 模型+操作级、多语言预留、支持本地+OSS 双写的 Headless CMS**。按页面类型全量迁移内容，不再保留“代码常量 + CMS 字段”的混合方案。

### 必须补齐的缺口（按优先级排序）

#### P0：数据模型扩展（阻塞其他所有任务）

1. **为 `ContentItem` 增加 `locale` 字段**
   - 默认 `zh-CN`，为 `ContentItem` 增加唯一索引 `(slug, modelCode, locale)`（若 slug 存在）。
2. **新增 RBAC 数据模型**
   - `Role`（角色：super_admin、content_admin、content_editor、reviewer、readonly）
   - `Permission`（角色 × 内容模型 × 操作：create/read/update/delete/publish）
   - 在 `/api/admin/*` 路由增加权限中间件。
3. **明确 `review` 状态语义**
   - `review` = 已提交待审核；只有具备对应模型 `publish` 权限的角色可审核或驳回。

#### P1：核心能力补齐

4. **媒体管理模块**
   - 完成 `/api/admin/media` 上传接口；
   - 本地存储落盘到 `public/uploads/`（开发/测试），生产写入 OSS/S3；
   - 生成缩略图、WebP/AVIF 派生格式；
   - `MediaAsset` 记录原图与派生格式 URL。
5. **工作流引擎（最简版）**
   - 状态机：draft → review → published / archived，支持驳回回 draft；
   - 站内消息通知：审核人收到待审核 badge，提交人收到审核结果通知；
   - `AuditLog` 记录状态流转与 before/after。

#### P2：内容迁移与页面切换

6. **按页面类型全量迁移**
   - 依次为：legal → news → team → cases → services → solutions → products → standalone-products → homepage zones；
   - 每个页面类型迁移时同步废弃 `src/lib/constants/*.ts` 中对应数据，改为从 CMS API 获取；
   - 营销页面使用 ISR，后台发布/回滚后调用 `/api/cms/revalidate`。
7. **管理后台界面**
   - 模型管理、内容编辑、媒体库、角色权限、工作流审核、通知中心。

### 风险与依赖

| 风险 | 等级 | 缓解措施 |
|------|------|---------|
| 全量迁移工作量大，可能挤压其他 7 月任务 | 高 | 按 P0 → P1 → P2 分阶段交付，优先完成模型扩展与 RBAC，内容迁移可逐页面进行 |
| 混合渲染对 Nginx 反向代理配置有新要求 | 中 | 更新 `nginx-static-production.conf`，确保 SSR/ISR 路径正确代理到 Next.js 服务 |
| SQLite 在高并发写入场景下可能成为瓶颈 | 中 | 当前后台管理并发低，可接受；若未来并发上升，平滑迁移至 PostgreSQL |
| 媒体文件 OSS 对接需要生产账号与 CDN 刷新策略 | 中 | 开发/测试阶段用本地存储，生产部署前完成 OSS 账号与 CDN 刷新脚本 |

### 建议创建的 ADR

- **ADR-0007：从纯静态导出迁移到混合渲染（SSR/ISR）以支撑 CMS**：记录放弃 `output: 'export'` 的原因、对 CMS 价值的提升、对 Nginx 配置的影响。见 [docs/adr/0007-hybrid-rendering-for-cms.md](../adr/0007-hybrid-rendering-for-cms.md)。