浅念
129 lines
14 KiB
Markdown
129 lines
14 KiB
Markdown
# trade-pro 第 5 主题移植设计（V8_10 主线）— 修订版 R3
|
||
|
||
日期：2026-10-22 ｜ 状态：评审通过（R2 复审后小幅修订）｜ 目标版本：SiteForge Enterprise V8.10.0-dev.1
|
||
修订记录：R1 评审"需修订后通过"（13 项发现已吸收）→ R2 复审"小幅修订后通过"（补第 6 处前端入口、行号 187、显式/默认值判定机制）→ R3 终版 → **R3.1** 更正图标前提（cms 源 0 SVG，图标为新增设计）。
|
||
|
||
## 1. 背景与目标
|
||
|
||
把 cms 项目（D:\project\cms）Astro 主题的视觉设计移植为 SiteForge 第 5 套内置主题 `trade-pro`，首要服务 hesupipe.com 重建（英文外贸 B2B），长期服务后续外贸类客户站。附带解决：默认语言英文（现四套主题模板硬编码 `lang="zh-CN"` + 中文文案）。**图标更正（R3.1）**：cms 源码实测 0 个 SVG、图标亦为文本箭头，故"替换箭头为 SVG 图标集"属**新增设计项**（用户明确要求优化图标），不是 cms 移植内容，不与 dist 对照。
|
||
|
||
### 范围外
|
||
|
||
平台多语言切换（P6）、其他三套旧主题的改造、cms 主题 en/es 双语路由、主题市场上架流程、Figma 级自由编辑、前端主题入口全面 API 驱动化（本轮逐处追加，API 化列后续迭代）。
|
||
|
||
## 2. 已验证的平台事实（设计依据，R2 修正）
|
||
|
||
| # | 事实 | 证据 | 对设计的影响 |
|
||
|---|---|---|---|
|
||
| F1 | **主题白名单共三处硬编码** | `app/theme_pro.py:18` THEMES；`app/core.py:12` THEMES（`builder.py:18,224` 与 `main.py:19,267 /api/themes` 使用）；`app/theme_store.py:14` BUILTIN（`resolve()` 59-60 对非 BUILTIN 无 theme_versions 记录抛 ThemeError，`builder.py:189` 构建即调） | 平台适配必须三处同步，且统一为单一发现源 |
|
||
| F2 | **主题 ZIP 安装通道不可用于 trade-pro** | `theme_store.py:106-117,143-146`：安装包仅声明式文件，pro/site.html 只能从 4 个 BUILTIN layout_family 拷贝 | trade-pro 必须以内置目录形式随代码交付，不走 install() |
|
||
| F3 | **前端 6 处主题选择入口硬编码** | `app/templates/admin.html:13` 建站 select；**`app/templates/workspace.html:41` 工作台建站模态框下拉**（V8.10 主 UI）；`app/static/workspace.js:5,63` themeName 映射；`app/static/admin.js:5` cfg；`app/static/factory-v2.js:30` schemes；`app/templates/theme-gallery.html:4` 下拉 | 后端动态化不会自动传导，前端必须逐处追加 trade-pro |
|
||
| F4 | 组件宏库全主题共享 | `themes/_professional_components.html`（根目录）；由各主题 `pro.html:2` `{% from ... import card,cover ... with context %` 引用，经 `theme_pro.LOADER`/`builder.ENV`（均为 themes/ 根单目录单例）解析 | 需"每主题优先、回落共享"的宏覆盖机制（见 4.2.4）；部分调用点已是双目录（builder.py:291/376/393、main.py:517、factory_api.py:313），做法可对齐 |
|
||
| F5 | **主题包 blocks.css 无生效路径** | `builder.py:191` 恒定复制 `app/static/blocks.css` 到 dist | 平台适配需增加"主题目录优先"复制逻辑（见 4.2.3） |
|
||
| F6 | 页眉/页脚/导航由平台生成 | `site_design_v87.py:69 _nav()`；`builder.py:219` 注入 custom.css | 新主题适配平台 DOM；全站设计草稿功能须在新主题生效 |
|
||
| F7 | 兼容性检查：**13 种预设（缺失仅 warning）+ 14 个布局文件（缺失 valid=False，含 search.html）** | `blueprints.py:49-63` PAGE_TEMPLATES 13 种（无 search）；`theme_store.py:90-96` | 交付 14 个 pages/*.html（硬性）+ 13 种预设（尽力全） |
|
||
| F8 | 主题目录五文件硬性要求 | `theme_store.py:82`：manifest.json/theme.css/page-presets.json/pro.html/**pro.css** | 结构含 pro.css（承接组件样式） |
|
||
| F9 | **平台中文默认值与英文目标冲突** | `theme_pro.py:151-155` 默认导航全中文、`:22` TITLES、`:182` pretty_type 兜底'内容'；`site_design_v87.py:20` DEFAULTS `cta_text:'联系我们'` | 模板侧规避：主题内置英文 chrome 兜底，不消费平台中文默认（见 4.5） |
|
||
| F10 | **平台 custom.css 无条件覆盖按钮样式** | `builder.py:213-218` 生成 `.btn,.primary,.request,.button,.nav-btn{...}` 写入最后加载的 custom.css | 主题按钮用自有类名前缀 `sf-tp-`，避开平台选择器（见 4.5） |
|
||
| F11 | theme_color 映射仅 4 主题 | `theme_pro.py:170`，缺省回落 '#ffffff' | 映射表补 trade-pro（或从 manifest accent 读） |
|
||
| F12 | 设计素材源 | cms `src/styles/{tokens.css 250行, base.css 445行}` + 组件 scoped CSS + `dist/hesupipe` 成品像素基准 | 手工移植素材基础 |
|
||
| F13 | hesupipe 数据已在本机 V8_10 实例内 | 站点 `483295c29ea0`（193 条：16 page/129 post/48 product），经 `/staging/wxr` 导入清洗版 WXR（剔除 930 非内容条目、修复 19 个 `?p=` 链接），构建版本 `5552c7a9a9c1` | Phase 2/4 验收直接切该站主题；导入通道与清洗脚本已验证可复现 |
|
||
|
||
## 3. 方案选择
|
||
|
||
**A. 手工移植（选定）**：以 `dist/hesupipe` 成品为像素基准、`src/` 源码为素材，手写 Jinja 模板。9 种真实模板量可控，质量最高。
|
||
否决 B（脚本转换 dist 产物：哈希类名无法映射回内容变量）与 C（只换 CSS：结构受限，达不到设计还原）。
|
||
|
||
## 4. 架构设计
|
||
|
||
### 4.1 主题包结构（R2：补 pro.css，blocks.css 依赖 F5 适配）
|
||
|
||
```
|
||
themes/trade-pro/
|
||
├── manifest.json # id: trade-pro, version 1.0.0, style: international-b2b, 英文元数据, accent/theme_color
|
||
├── site.html / pro.html # lang="en"，全英文 UI 文案
|
||
├── _professional_components.html # 每主题覆盖宏库（4.2.4）
|
||
├── theme.css # base.css + tokens.css 移植，CSS 变量桥接设计令牌
|
||
├── blocks.css # 组件样式（依赖 4.2.3 平台适配后方可生效）
|
||
├── pro.css # 专业页组件样式（F8 硬性要求，可为承接层）
|
||
├── pages/*.html # 14 个布局文件（F7 硬性，含 search.html；9 独立 + 5 变体，见 4.3）
|
||
├── page-presets.json # 13 种模板预设（F7；warning 级但全部提供）
|
||
├── visual/ # 中性演示素材预览图（禁止 hesupipe 真实素材）
|
||
└── versions/ # 版本快照
|
||
```
|
||
|
||
### 4.2 平台适配层（R2：按 F1-F5、F9-F11 扩充为 7 项）
|
||
|
||
1. **主题发现统一（F1/F2）**：在 theme_store 新增单一发现函数（扫描 `themes/*/manifest.json` 得到 id+元数据）；`core.THEMES`、`theme_pro.THEMES`、`theme_store.BUILTIN` 三处改为引用该函数结果（保留原名称导出以兼容既有 import：builder.py:18/224、main.py:19/267、theme_pro.py:187、theme_store.py:59-60）。现有 4 主题目录不动，行为等价。
|
||
2. **前端入口逐处追加（F3，共 6 处）**：admin.html:13 select、workspace.html:41 建站模态框下拉、theme-gallery.html:4 下拉、workspace.js:5 themeName、admin.js:5 cfg、factory-v2.js:30 schemes 各追加 trade-pro 条目（英文名 + accent + 预览图引用）；`/api/themes`（main.py:267）确认返回发现函数结果。API 驱动化重构列后续迭代。
|
||
3. **主题资产复制（F5）**：builder.py:191 改为"主题目录存在 blocks.css 则复制主题版，否则复制平台版"（向后兼容）。
|
||
4. **宏覆盖机制（F4，R2 具体化）**：`theme_pro.py:20 LOADER` 与 `builder.py:22 ENV` 由单目录改为按主题构造 `ChoiceLoader([theme_dir, themes_root])`（与 builder.py:291 等现有双目录做法对齐）；列出全部构造点与使用点（theme_pro.py:190 render 等）逐一核对；Jinja 缓存按 env 实例管理，per-theme env 复用避免 5000 页级构建的重复编译开销；pro.html 顶部 `{% from '_professional_components.html' import ... %}` 即先命中主题目录版本。现有 4 主题目录无同名文件，回落共享库，行为不变（回归测试覆盖）。
|
||
5. **英文 chrome 兜底（F9）**：trade-pro 模板不消费平台中文默认——nav 未配置时模板内置 Home/Products/News/About/Contact 英文导航；不使用 TITLES/pretty_type 中文标签，模板自带英文 kind 标签；site_design 的 `cta_text` 仅在用户显式配置（非平台默认值）时渲染。**显式/默认值判定机制**：`ctx['nav']` 恒非空（theme_pro.py:151-155 已填中文默认）、`cta_text` 经 `site_design_v87.py:91` 与 DEFAULTS 合并后无法从源头区分，因此采用**值比对**——模板侧将"等于中文默认值（首页/联系我们等）"视为未配置并输出英文兜底（英文站场景下用户显式配置不会恰好等于中文默认值，判定可靠）。
|
||
6. **样式优先级（F10）**：主题按钮/交互元素全部使用 `sf-tp-` 前缀类名，避开平台 custom.css 的 `.btn/.primary/.request/.button/.nav-btn` 选择器；tokens.css 变量以 `--sf-tp-*` 命名并提供默认值，平台 accent 注入仅在站点显式设置时通过桥接变量生效。
|
||
7. **theme_color（F11）**：`theme_pro.py:170` 映射表补 trade-pro（取 manifest accent）。
|
||
|
||
所有平台改动配回归测试：现有 4 主题渲染关键断言不变。
|
||
|
||
### 4.3 页面模板映射（14 个布局文件）
|
||
|
||
| cms 页面 | SiteForge 模板 | 实现 |
|
||
|---|---|---|
|
||
| index | home | 独立（Hero+FeatureGrid+CardGrid+CTA） |
|
||
| about | about | 独立 |
|
||
| news/products 列表 | listing | 独立，按内容类型分支（Phase 0 确认可行性） |
|
||
| news 详情 | article | 独立 |
|
||
| product-category | category | 独立 |
|
||
| product 详情 | product | 独立（参数表/多图） |
|
||
| projects | case | 独立 |
|
||
| applications/support | standard | 独立 |
|
||
| contact | contact | 独立（LeadForm 样式） |
|
||
| 搜索 | search | 复用 listing 变体 |
|
||
| — | brand/service/faq/notfound | 复用 listing/standard 变体（后续精修） |
|
||
|
||
### 4.4 区块契约
|
||
|
||
沿用现有 block id 与属性 Schema（blueprints.BLOCKS：hero/richtext/features/stats/collection/image_text/gallery/faq/cta/attributes/**layout**/spacer + carousel/video/tabs/pricing/map/form_link 六组件），只重写渲染与样式 → 编辑器/预设/自动装配/整站模板开箱即用。映射：PageHero→hero、FeatureGrid→features、CardGrid→collection、CTA→cta、产品参数表→attributes。cms 组件属性超出契约时模板内智能适配，不扩平台契约。
|
||
|
||
### 4.5 语言、令牌、图标、素材
|
||
|
||
- `lang="en"`，主题内全部 UI 文案/面包屑/分页/日期英文；英文 chrome 兜底见 4.2.5
|
||
- tokens.css 变量 `--sf-tp-*` 桥接 SiteForge 设计令牌（V8.7 全站设计草稿可调），优先级规则见 4.2.6
|
||
- 图标：自设计内联 SVG 集合进主题宏库（替代箭头；**新增设计**，cms 源无 SVG，见 §1 更正）
|
||
- 素材规范：主题包仅含中性演示素材；hesupipe 真实图片留在站点数据侧
|
||
|
||
### 4.6 数据映射与导入通道
|
||
|
||
产品 specs/gallery → entry meta.fields（与现有 product 模板同构）；正文直接渲染；图片 URL 保持原站引用（镜像后续统一处理）。**导入通道（F13）**：本机 V8_10 实例站点 `483295c29ea0` 已含 hesupipe 全量 193 条（清洗版 WXR 经 `/api/factory/sites/{id}/staging/wxr` 暂存导入，清洗规则：仅保留 post/page/product、删除 19 个 `?p=` 形式 link）；Phase 2/4 直接切换该站主题验收，另以脚本化步骤记录保证可复现。
|
||
|
||
## 5. 实施阶段（R2：Phase 1 扩充，Phase 2 落到已有站点）
|
||
|
||
- **Phase 0 契约研究**：通读 industrial 主题全部文件 + theme_pro/builder/theme_store 渲染分工，产出契约清单；确认 listing 按内容类型分支的可行方案；给主线目录建 Git 仓库并提交基线（补丁管理，含 v8_workflows.py:67 修复）
|
||
- **Phase 1 平台适配**：4.2 全部 7 项 + 现有 4 主题回归测试（含双目录加载、资产复制、/api/themes）
|
||
- **Phase 2 骨架跑通**：trade-pro 空壳（manifest/site.html/pro.html/theme.css/pro.css 骨架 + home 布局）注册成功；**站点 483295c29ea0 切主题构建出首页**；前端 6 入口可见可选
|
||
- **Phase 3 完整模板**：其余 8 种独立布局 + 5 种变体（含 search）+ blocks.css 全量样式 + 图标宏库
|
||
- **Phase 4 预设与验收**：13 种 page-presets、编辑器区块验证、theme-gallery 预览、全量测试、实战与视觉验收
|
||
|
||
## 6. 测试与验收
|
||
|
||
- pytest：主题发现（三处白名单一致）、兼容性检查 valid=True（14 布局 + 13 预设）、9 种独立布局渲染快照、英文文案与 `lang="en"` 断言（含未配置 nav 时英文兜底）、4 主题回归（双目录回落、资产复制、按钮类名不冲突）
|
||
- 实战：站点 483295c29ea0 切 trade-pro 构建 ≥203 页零错误；**6 个前端入口均可见可选 trade-pro**；编辑器 hero/cta/features 可编辑可预览；全站设计草稿页眉/页脚配置生效（显式配置值渲染、平台中文默认不出现）
|
||
- 视觉验收两层：**必须一致**（设计令牌/字体/配色/组件视觉骨架/英文文案/图标体系）；**允许差异**（内容排列顺序、分页器样式细节）
|
||
|
||
## 7. 风险与缓解（R2 更新）
|
||
|
||
| 风险 | 缓解 |
|
||
|---|---|
|
||
| listing 模板无法按内容类型分支 | Phase 0 契约研究确认；兜底：kind 变量分支或 category 模板承担产品列表 |
|
||
| 宏覆盖机制的 per-theme env 影响构建性能 | env 按 themes 缓存复用；5000 页级构建跑性能回归（V8.9 有基线） |
|
||
| 平台生成页眉 DOM 与 cms 设计差异大 | 本轮样式层适配平台 DOM，结构模板化列后续迭代 |
|
||
| 前端逐处追加遗漏入口 | Phase 2 验收清单含 6 入口逐项检查；全仓 grep `automotive`（templates 命中 admin.html/theme-gallery.html/workspace.html 三文件 + static 下 workspace.js/admin.js/factory-v2.js）确认无第 7 处 |
|
||
| cms scoped CSS 分散难提取 | dist 编译 CSS 反查 + src 源码双重对照 |
|
||
|
||
## 8. 交付物
|
||
|
||
themes/trade-pro/ 完整主题包（14 布局 + 13 预设 + 五文件硬性项）、平台适配 diff（4.2 全部 7 项，含测试）、本文档、站点 483295c29ea0 切主题验收记录、Git 仓库与补丁清单。
|
||
|
||
## 9. 已知关联补丁（升级版本时需重放）
|
||
|
||
`app/v8_workflows.py:67` 类型列修复（`类型`/`分类` 兼容读取）——已在 V8_7、V8_10 各打一次。
|