cms-SiteForge/docs/superpowers/specs/2026-10-22-trade-pro-theme-design.md

trade-pro 第 5 主题移植设计（V8_10 主线）— 修订版 R3

日期：2026-10-22 ｜ 状态：评审通过（R2 复审后小幅修订）｜ 目标版本：SiteForge Enterprise V8.10.0-dev.1 修订记录：R1 评审"需修订后通过"（13 项发现已吸收）→ R2 复审"小幅修订后通过"（补第 6 处前端入口、行号 187、显式/默认值判定机制）→ R3 为终版。

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 各打一次。