SiteForge Factory V5 — 四套商业视觉主题升级版

独立可部署源代码项目。V5 基于 V4 基于 V3，重点开发需求中的前四个模块：完整行业主题、可视化编辑、数据自动装配、旧站迁移审计。这是可测试的功能整合版，不等于已经通过生产级安全、真实 CMS 无损迁移和全设备视觉验收。

V5 本轮核心升级

四套主题新增商业版视觉体系、内置本地 SVG 示例视觉素材、内容与 Logo 优先展示、响应式细节、交互优化和独立商业交付检查报告，主题版本升级为 1.1.0 并保留旧版快照。后台 /theme-gallery 与正式静态网站共用主题样式资源。详细功能与验收限制请阅读 docs/COMMERCIAL_THEME_V5.md。

这是一套可以用于客户项目试点与二次精修的商业主题交付候选版，不是已经完成真实企业资料、表单和法律/SEO 验收的正式上线成品。

快速开始（Windows + Docker Desktop）

1. 安装 Docker Desktop，解压项目，在解压根目录打开 PowerShell。
2. 首次初始化（只执行一次，密码显示在终端并自行妥善保存）：

docker run --rm -v "${PWD}:/project" -w /project python:3.12-slim python scripts/init_config.py

3. 启动管理网站及后台任务 Worker：

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 采用离线解析。

自检

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 与手机视图逐项验收，再考虑生产上线。