浅念
3c57c167f2
导入 SiteForge Factory V5 基线源码： - FastAPI + SQLite + Docker Compose（Web + Worker）架构 - 四套商业主题 × 14 页面模板（1.1.0，含历史版本快照） - 四种建站模式骨架 + 迁移审计 + 发布门禁 - 52 项 pytest 测试 - 补全计划主文档 docs/superpowers/plans/ Co-Authored-By: Claude Code <noreply@anthropic.com>
124 lines
9.0 KiB
Markdown
124 lines
9.0 KiB
Markdown
# SiteForge Factory V5 — 四套商业视觉主题升级版
|
||
|
||
> **独立可部署源代码项目**。V5 基于 V4 基于 V3，重点开发需求中的前四个模块：完整行业主题、可视化编辑、数据自动装配、旧站迁移审计。**这是可测试的功能整合版，不等于已经通过生产级安全、真实 CMS 无损迁移和全设备视觉验收。**
|
||
|
||
## V5 本轮核心升级
|
||
|
||
四套主题新增商业版视觉体系、内置本地 SVG 示例视觉素材、内容与 Logo 优先展示、响应式细节、交互优化和**独立商业交付检查报告**，主题版本升级为 `1.1.0` 并保留旧版快照。后台 `/theme-gallery` 与正式静态网站共用主题样式资源。详细功能与验收限制请阅读 [docs/COMMERCIAL_THEME_V5.md](docs/COMMERCIAL_THEME_V5.md)。
|
||
|
||
> 这是一套可以用于客户项目试点与二次精修的商业主题交付候选版，**不是已经完成真实企业资料、表单和法律/SEO 验收的正式上线成品**。
|
||
|
||
## 快速开始（Windows + Docker Desktop）
|
||
|
||
1. 安装 Docker Desktop，解压项目，在解压根目录打开 PowerShell。
|
||
2. 首次初始化（只执行一次，密码显示在终端并自行妥善保存）：
|
||
|
||
```powershell
|
||
docker run --rm -v "${PWD}:/project" -w /project python:3.12-slim python scripts/init_config.py
|
||
```
|
||
|
||
3. 启动管理网站及后台任务 Worker：
|
||
|
||
```powershell
|
||
docker compose up -d --build
|
||
docker compose ps
|
||
```
|
||
|
||
4. 浏览器打开 `http://localhost:8787/`，使用初始化后的 `admin` 密码登录。
|
||
|
||
进入 **`/factory-studio`** 查看网站工厂、主题装配、迁移审计。编辑器地址从网站管理工作台进入。主题预览 **`/theme-gallery`**。
|
||
|
||
V5 的 Compose 项目名为 `siteforge-v5`，默认使用单独的 Docker 数据卷，以免意外覆盖 V3。**如果你已经有 V4 数据，先做备份并设计独立迁移步骤，不要通过更改数据卷名直接强行复用。**
|
||
|
||
## 能实际做的四条工作流程
|
||
|
||
### A. 无旧站：从零新建网站
|
||
|
||
1. 登录，进入 `/factory-studio`，创建网站并选择 Automotive / Industrial / Corporate / Minimal 主题。
|
||
2. 在网站结构里初始化页面；填写公司介绍、Logo、邮箱、产品、新闻、案例及联系信息。
|
||
3. 在编辑器中选择全页自由排版模式，添加 Hero、图文、动态内容、**响应式多列容器**等组件；列内继续添加组件，支持跨列移动和复用组件。
|
||
4. 选择主题版本，预览，构建并下载静态站 ZIP，或进入现有审批发布流程。
|
||
|
||
### B. 数据生产：Excel、CSV、JSON 自动装配
|
||
|
||
1. 打开 `/factory-studio` 的“内容与自动装配”，上传 XLSX / CSV / JSON。
|
||
2. 系统建议车型、品牌、分类、动力形式、图库、技术参数、SEO 字段的映射；可以手动调整。
|
||
3. 先“预览数据和错误”，确认 URL 冲突、空标题与未映射字段，再执行导入。
|
||
4. 预览“品牌关系”并将缺失的品牌页面创建为空资料页，不伪造企业文案。
|
||
5. 切换主题重新构建，保留已经导入的 URL / SEO / 品牌和参数数据。
|
||
|
||
### C. 旧站迁移：WordPress 与其他来源
|
||
|
||
- WordPress WXR/XML：文章和页面、基础 SEO、公开自定义字段；V4/V5 继续提取特色图片、WXR 媒体 URL、品牌/产品分类、部分 WooCommerce 简单商品属性，以及 Elementor 已知标题/正文/图片组件。**未知 Elementor 组件、ACF 复杂字段、变体/订单及短代码均保留原始数据并产生复核提示。**
|
||
- 其他来源：现有 CSV/JSON/XLSX 导入，以及安全受限的公开 HTML 采集。没有对任意 PHP/MySQL/CMS 数据库格式进行通用自动转换。
|
||
- 旧站基线：上传原网站的 URL/SEO CSV、JSON、sitemap XML 或 WXR 文件。CSV 列可包含 `url,seo_title,description,canonical,robots,h1,status`。
|
||
- 系统对 **实际生成的 HTML** 检查缺失 URL、title/description/canonical/robots/H1 差异及静态资源、内部链接。阻断项必须修复，警告必须经具有审核权限的人员填写理由才能通过发布门禁。
|
||
|
||
### D. 主题开发与维护
|
||
|
||
四套内置主题各有 14 种独立模板、响应式 CSS、菜单、产品参数、产品多图切换/大图预览、搜索筛选、页脚，以及可配置的联系表单入口。主题 ZIP 支持受限声明式 CSS/区块预设的版本安装和兼容性检查。**不允许安装执行任意 Jinja/JS/Python 的 ZIP**，避免任意代码执行。
|
||
|
||
联系表单只有在后台设置正式的 HTTPS 外部表单接收地址时才会呈现。SiteForge 默认不会提供虚假的“发送成功”；表单服务的收件、隐私、防垃圾邮件和运维需要自行配置。
|
||
|
||
## 技术实现概要
|
||
|
||
- FastAPI / SQLite / Docker Compose Web + Worker；这是 V3 继承的运行架构，**尚未更换 PostgreSQL/Redis**。
|
||
- 专业主题引擎：四套主题的 `pro.html`、`pro.css` 和各 14 种页面模板。
|
||
- 编辑器：允许 `layout`（1-4 列、最多两层）及列内嵌套安全组件；支持整页替换、全主题预览、PC/平板/手机切换、图片上传、内联文本、按设备隐藏/间距、组件库保存复用。
|
||
- 内容装配：`app/assembly.py`、`app/table_loader.py`、`app/relations.py`。
|
||
- WordPress 特殊数据：`app/wordpress_compat.py`，不执行 Elementor/PHP 代码。
|
||
- 迁移清单/构建差异/人工复核：`app/migration_audit.py`，API `/api/audit/...`。
|
||
- 多站点权限、内容历史、基础审批、静态生成、ZIP / 本地发布延续 V3。
|
||
|
||
## 关键 API
|
||
|
||
| API | 功能 |
|
||
|---|---|
|
||
| `GET /api/factory/themes/{id}/compatibility` | 检查主题资源及 14 种页面结构 |
|
||
| `POST /api/factory/sites/{site}/mapping/parse-file` | Excel、CSV、JSON 字段解析，不直接写入数据库 |
|
||
| `POST /api/factory/sites/{site}/mapping/run` | 字段映射预览/写入 |
|
||
| `GET /api/factory/sites/{site}/relationships` | 产品与品牌分类关系检查 |
|
||
| `POST /api/factory/sites/{site}/relationships/assemble` | 创建缺失的空品牌页 |
|
||
| `GET/POST /api/sites/{site}/components` | 可复用组件库 |
|
||
| `PUT /api/sites/{site}/pages/{page}/blueprint` | 保存区块和整页设计模式 `layout_mode` |
|
||
| `PUT /api/sites/{site}/contact-settings` | 联系邮箱和外部 HTTPS 表单配置 |
|
||
| `POST /api/audit/sites/{site}/import-baseline` | 导入旧站 URL + SEO 清单 |
|
||
| `GET /api/audit/sites/{site}/builds/{build}/report` | 实际构建文件差异报告 |
|
||
| `GET /api/audit/sites/{site}/builds/{build}/report.csv` | 下载差异 CSV |
|
||
| `POST /api/audit/sites/{site}/builds/{build}/review-warning` | 有理由地审核单条警告 |
|
||
|
||
全部管理 API 均需要登录；写入 API 需要 CSRF 校验、站点角色权限。为避免不受控的远程页面运行风险，迁移清单和 WXR 采用离线解析。
|
||
|
||
## 自检
|
||
|
||
```bash
|
||
pip install -r requirements-dev.txt
|
||
python -m pytest -q
|
||
python -m compileall -q app
|
||
node --check app/static/editor.js
|
||
node --check app/static/factory-v2.js
|
||
node --check app/static/pro.js
|
||
```
|
||
|
||
Windows 也可以在安装开发依赖后运行 `powershell -ExecutionPolicy Bypass -File scripts/check.ps1`。2026-10-22 使用 Python 3.12 完成回归，当前 **54 项自动化测试全部通过**；四套演示主题的浏览器 E2E 与 Docker 容器仍应在目标部署环境重新验收，不能用源码测试通过代替上线验收。
|
||
|
||
运行依赖使用已经回归验证的精确版本。升级 FastAPI、Starlette、Pydantic 或 HTTPX 时应作为独立变更处理，并重新运行完整测试，避免 Docker 重建时悄然跨越框架兼容边界。
|
||
|
||
## V5 运行安全配置
|
||
|
||
- `SITEFORGE_ALLOWED_HOSTS` 是逗号分隔的后台访问域名白名单；本地 Compose 默认只允许 localhost。公网部署文件会自动加入 `SITEFORGE_DOMAIN`。
|
||
- 管理员密码与团队密码都使用 scrypt 派生后比较；仍建议通过 Docker Secret 或 `SITEFORGE_ADMIN_PASSWORD_FILE` 提供管理员密码。
|
||
- Worker 对临时失败的构建默认最多尝试 3 次，并采用短延迟退避；可通过 `SITEFORGE_JOB_MAX_ATTEMPTS` 调整。
|
||
- 安全响应头允许主题中心进行同源 iframe 预览，但禁止第三方网站嵌入管理后台。
|
||
|
||
## 明确未实现的部分
|
||
|
||
1. 任意外部 CMS 的自动无损迁移；完整 ACF Repeaters、Elementor 全部 widget、WooCommerce 变体/订单/支付、任意 SQL 备份的自动解释。
|
||
2. 任意上传完整可执行代码主题；上传仅限安全声明式主题，独立复杂主题需要开发者审核并放入代码仓库。
|
||
3. 真正任意元素绝对定位、所有断点分别绘制的 Figma 级编辑器；V4 提供可控的列布局与嵌套组件。
|
||
4. 内置表单邮件/CRM 收件服务；需配置受控外部 HTTPS 服务。
|
||
5. Art Design Pro **官方完整工程替换**；当前默认还是 SiteForge Web 管理后台。
|
||
6. PostgreSQL/Redis、多云/CDN 一键发布、正式渗透测试、高可用、监控、真实 Google Search Console 性能保障。
|
||
|
||
**建议首次试点：** 使用一个完整 WordPress 导出（WXR + 媒体备份）以及一份实际车型 Excel，分别做旧站迁移和新站创建，对所有链接、内容、SEO 与手机视图逐项验收，再考虑生产上线。
|