浅念
8884e100f9
Overlay 190 upstream items (V8.22→8.31) preserving trade-pro theme, registry tests, and design docs. Re-applied full patch set on identical anchors (discovery/env_for/blocks.css/type-mapping/locale-override/ theme_color/frontend entries/test_theme_pro_v3 mods) plus compose pins. Verified: theme suites 35/35; dual-baseline full run 415 passed vs pristine 386+29 ours, FAILED-set diff EMPTY (same 10 Windows env fails). Live: container 8.31.1-dev.1 healthy, hesupipe 192 entries intact, trade-pro build 203 pages 0 errors. Co-Authored-By: Claude Code <noreply@anthropic.com>
92 lines
5.8 KiB
Markdown
92 lines
5.8 KiB
Markdown
# 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. 需要完全独立时，在属性栏点击“解除关联、保留当前内容”。
|
||
|
||
演示：[公共组件版本与同步的离线交互页](../examples/V8_25_公共组件_版本与同步演示.html)。该演示使用模拟数据，不连接 SiteForge 后台。
|
||
|
||
## 数据与接口
|
||
|
||
### 增量 Schema
|
||
|
||
沿用 `reusable_components`，新增：
|
||
|
||
`reusable_component_versions(component_id, version, block_json, snapshot_hash, created_at)`，主键 `(component_id, version)`。针对现存旧组件仅能为**当时当前版本**补快照，无法凭空还原过去没有保存的历史版本。
|
||
|
||
页面区块新增一个**可选、严格验证**的 `shared_ref`：
|
||
|
||
```json
|
||
{"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 | 无任何引用时允许删除 |
|
||
|
||
同步请求样例：
|
||
|
||
```json
|
||
{"plan_token":"64位预检SHA256","entry_ids":["页面ID1","页面ID2"]}
|
||
```
|
||
|
||
### 同步安全边界
|
||
|
||
- 源组件版本发生变化、预检结果不一致、被选页面出现本地修改或页面草稿乐观锁冲突 → 409 拒绝。
|
||
- 所选页面最多 100 个；事务内重新核对完整页面哈希与草稿修订号。
|
||
- `BEGIN IMMEDIATE` 的读/比较/写窗口和事务性快照日志；在 SQLite 下启用写锁，在 PostgreSQL 兼容层中使用事务顾问锁。
|
||
- 事务任一页面失败会整体回滚。只有新草稿变化，发布的 `entries.meta_json` 不变。
|
||
- 对于一个页面中的同一组件多个引用，同步所有满足条件的该组件实例；任何一个已在本地编辑都会拒绝整页，避免部分覆盖。
|
||
- 原页面的 URL、SEO、正文等未更改，组件源只在设计层按明确操作应用。
|
||
|
||
## 验收与运行
|
||
|
||
```bash
|
||
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`](../reports/V8_25_验收报告.html)。
|
||
|
||
## 尚未完成
|
||
|
||
- 当前同步是**选择性草稿更新**，不是一个“所有页面实时引用同一可变组件”的无版本动态系统。设计成这样是为了防止意外批量改动已发布站点。
|
||
- 全站页眉、页脚、导航仍由现有 `site_design_v87` 管理，尚未纳入本次公共组件源版本与跨页面同步模型。
|
||
- 没有完成多人实时协同编辑、视觉差异对比、正式 Art Design Pro 官方工程编译或真实 HTTPS 已登录 Chromium 后台验收。
|
||
- PostgreSQL/Redis 多 Worker、真实 S3/SFTP/Agent 发布、灾备恢复仍需独立生产化测试。
|