cms-SiteForge/docs/V8_25_SHARED_DESIGN_SYSTEM.md

SiteForge Enterprise V8.25 — 公共组件与选择性同步

版本： 8.25.0-dev.1
状态： 开发集成版；在 V8.24 完整源码基础上增量开发。
生产约束： 未经 PostgreSQL/Redis、正式浏览器登录和远程部署验收，不得标记为生产可上线。

目标和本轮交付

将原先的“复制一次、以后完全独立”的组件库升级为两个明确选项：

• 复制插入： 区块是当前页面的独立副本，未来不会随源组件更新。
• 关联插入： 页面保存一个合法的 shared_ref，用于之后预检、挑选页面、生成新草稿。不会在页面构建时远程引用组件，也不会在源组件修改时自动更改任何已发布页面。

新增源组件不可变版本快照、历史版本查询与恢复为新版、引用页面列表、本地修改检测、过期预检保护、跨站点隔离、事务式选择性同步、解除关联按钮。保留原四套主题、移动端抽屉导航与可选 Tabs、两层安全布局、URL/SEO、历史版本及独立静态发布。

管理入口与操作

1. 选择网站和页面 → 打开原来的 /editor/{site_id}/{entry_id}。
2. 选中一个区块（也可以是双层多列布局中的列内组件） → “保存当前组件到组件库”。
3. 左侧“添加内容” → “从我的组件库添加”，根据需要选择“复制”或“关联插入”。
4. 顶部“更多 → 管理公共组件”，或左侧高级设置中的同名按钮。
5. 选中公共组件 → 查看历史版本、查看引用/同步；可使用当前选中区块的内容创建新版本，也可以将一个历史快照“恢复为新版本”。历史版本不被覆盖。
6. 检查引用页。存在本地修改、发布冲突或已是最新版的页面不可直接勾选。
7. 选择允许同步的页面 → 确认 → 这些页面生成新的设计草稿；逐页预览、保存与发布。网站仍然需要重新构建、执行正式审批部署。
8. 需要完全独立时，在属性栏点击“解除关联、保留当前内容”。

演示：公共组件版本与同步的离线交互页。该演示使用模拟数据，不连接 SiteForge 后台。

数据与接口

增量 Schema

沿用 reusable_components，新增：

reusable_component_versions(component_id, version, block_json, snapshot_hash, created_at)，主键 (component_id, version)。针对现存旧组件仅能为当时当前版本补快照，无法凭空还原过去没有保存的历史版本。

页面区块新增一个可选、严格验证的 shared_ref：

{"id":"source_component_id","version":2,"hash":"sha256_64_hex"}

引用元数据随安全区块数据一同保存，不产生运行时动态远程引用。指纹排除拷贝后重新生成的块 ID 和来源引用，比较实际区块内容。不能通过本功能执行任意 HTML/JS。

API（所有接口要求登录/CSRF 和相应站点权限）

方法	路径	权限	功能
GET	/api/sites/{site}/components	Viewer	本站组件与当前快照 SHA
POST	/api/sites/{site}/components	Editor	新建组件，初始版本 v1
PUT	/api/sites/{site}/components/{id}	Editor	按 expected_version 乐观锁创建下一版本
GET	/api/sites/{site}/components/{id}/versions	Viewer	查询不可变版本列表
GET	/api/sites/{site}/components/{id}/versions/{version}	Viewer	读取已校验 SHA 的历史快照
GET	/api/sites/{site}/components/{id}/usage	Viewer	预检被引用页面、版本、冲突、plan_token
POST	/api/sites/{site}/components/{id}/sync	Editor	按 plan_token 和页面 ID 列表同步到草稿
DELETE	/api/sites/{site}/components/{id}	Editor	无任何引用时允许删除

同步请求样例：

{"plan_token":"64位预检SHA256","entry_ids":["页面ID1","页面ID2"]}

同步安全边界

• 源组件版本发生变化、预检结果不一致、被选页面出现本地修改或页面草稿乐观锁冲突 → 409 拒绝。
• 所选页面最多 100 个；事务内重新核对完整页面哈希与草稿修订号。
• BEGIN IMMEDIATE 的读/比较/写窗口和事务性快照日志；在 SQLite 下启用写锁，在 PostgreSQL 兼容层中使用事务顾问锁。
• 事务任一页面失败会整体回滚。只有新草稿变化，发布的 entries.meta_json 不变。
• 对于一个页面中的同一组件多个引用，同步所有满足条件的该组件实例；任何一个已在本地编辑都会拒绝整页，避免部分覆盖。
• 原页面的 URL、SEO、正文等未更改，组件源只在设计层按明确操作应用。

验收与运行

python -m pytest -q tests/test_v825_shared_components.py
node --check app/static/editor.js
node --test tests_js/*.test.cjs
python scripts/http_end_to_end.py
python scripts/verify_release.py
python scripts/regression_v825.py --timeout 55 --group-size 2

本轮已完成：23 批共 370 项 Python 回归；13 项 Node JavaScript 回归；HTTP + Worker E2E；隔离 Chromium HTML 演示的 PC 和 390px 手机布局。参见 V8_25_验收报告.html。

尚未完成

• 当前同步是选择性草稿更新，不是一个“所有页面实时引用同一可变组件”的无版本动态系统。设计成这样是为了防止意外批量改动已发布站点。
• 全站页眉、页脚、导航仍由现有 site_design_v87 管理，尚未纳入本次公共组件源版本与跨页面同步模型。
• 没有完成多人实时协同编辑、视觉差异对比、正式 Art Design Pro 官方工程编译或真实 HTTPS 已登录 Chromium 后台验收。
• PostgreSQL/Redis 多 Worker、真实 S3/SFTP/Agent 发布、灾备恢复仍需独立生产化测试。