v0.10.5 首页 H2 产品线入口 ×6:ImageBoxWidget 重构为 Elementor 忠实 DOM + slim 白名单补齐 + H2 scoped CSS(post-18 对齐,桌面/移动/hover 实测一致)

2026-11-01 00:15:29 +08:00
commit 5b83e71ad9
128 changed files with 20008 additions and 0 deletions
@@ -0,0 +1,167 @@
+# DusunIoT WordPress 重构开发方案 V2
+
+> 状态：开发规划。基于 `dusuniot-website-stability-and-multilingual-brief.md` 和重构决策编写。
+> 核心原则：前台 1:1 还原，后台功能等价实现，底层用 Bun 单体替换 WordPress。
+
+## 1. 目标与边界
+
+- 将现有 WordPress + Elementor + WooCommerce + GTranslate 迁移到 **TanStack Start + Bun + PostgreSQL**。
+- **前台必须 1:1 还原**现有网站的视觉、响应式布局、内容、导航、产品筛选和实际交互；不要求复刻 WordPress/Elementor 的内部 DOM 或代码。以采集时的线上页面与截图为视觉基准。
+- **后台使用 React + Ant Design**，还原现有实际使用的业务功能，不要求与 WordPress 后台界面一致；不开发插件系统、Elementor 克隆或 WordPress 兼容运行环境。
+- **后台图标强制规范：只能使用 SVG 图标**（优先 Ant Design Icons SVG 或 Lucide React）。**禁止 Emoji、Unicode 特殊符号/特殊字体、Icon Font、字体图标、文字字符冒充图标**。菜单、按钮、提示、状态、空页面、表格操作、Dashboard 图标全部适用。图标要有可访问名称，装饰性图标 aria-hidden。
+- 单体项目同时提供 SSR、服务端 API / Server Functions、后台与定时任务；不引入 Go、PHP、微服务；PostgreSQL 为主数据库。
+- 保留 Cloudflare，按实际部署情况使用 Nginx/CDN 缓存；文件存储可用本地或 S3/R2。
+- 不以“更换技术栈”替代故障归因；现有 WordPress CPU 高负载、数据库权限撤销、筛选器和 GTranslate 回源等问题，仍需采集基线和证据。
+
+## 2. 技术栈
+
+| 领域 | 选型 |
+| --- | --- |
+| 前台 SSR / 路由 | TanStack Start + React + TypeScript |
+| 运行时和包管理 | Bun |
+| 业务 API | TanStack Start Server Functions / 服务端路由（对外接口） |
+| 数据库 | PostgreSQL |
+| SQL / 迁移 | Drizzle ORM + SQL 索引、事务 |
+| 后台 UI | React + Ant Design |
+| 前台样式 | 以原站 CSS 和视觉结果为基准，按需 Tailwind CSS |
+| 缓存 | Cloudflare + Nginx + 服务端缓存，按用户态区分 |
+| 图片与文档 | 本地对象目录或 S3/R2 |
+| 测试 | Playwright 截图对比 + E2E；Vitest 单元/集成测试 |
+| 图标 | SVG only（Ant Design Icons / Lucide） |
+
+生产环境要先验证 TanStack Start 与所选 Bun/Nitro 构建、SSR、Server Functions、流式响应及部署版本的兼容性，锁定经过测试的依赖版本。
+
+## 3. 功能还原范围
+
+### 前台：必须达到 1:1
+
+- 页面类型：首页、产品列表和详情、产品分类/筛选、文章/新闻、Landing Page、公司/联系页面、搜索和现有其他公开模板。
+- 还原 Header、Footer、导航及菜单、Banner、卡片、字体、颜色、边距、栅格、图片比例、动画、交互、移动端和平板布局。
+- 保留询盘表单的字段、验证、提交流程、通知；保留客户注册/登录、购物车、结账、订单查询及原站实际启用的支付/物流/税费规则。
+- 采集原站各页面样板和三类屏幕尺寸；通过 Playwright 截图差异及人工审核验收，不能仅以 DOM 或代码相同为标准。
+- 仅迁移实际使用的功能，不复制与业务无关的 WordPress 插件能力。
+
+### 后台：功能等价，界面重新设计
+
+使用 Ant Design 建立以下菜单（按审计结果增减）：
+
+| 模块 | 核心能力 |
+| --- | --- |
+| Dashboard | 业务概览、站点运行统计 |
+| Pages / Landing Pages | 内容、模板区块、发布/预览 |
+| Posts | 文章、分类、标签、状态 |
+| Products | 产品、分类、属性、规格、筛选配置、库存（如原站使用） |
+| Orders | 订单、状态、支付/发货/退款（按实际业务） |
+| Customers | 注册用户、资料、权限 |
+| Inquiries | 询盘记录、状态、通知 |
+| Media | 图片/附件上传、管理、引用 |
+| Languages | 语言版本、翻译、审核与发布 |
+| SEO | SEO Metadata、Sitemap、重定向 |
+| Settings | 导航、基本配置、邮件、支付（按实际启用） |
+
+**禁止在后台使用 Emoji、Icon Font、特殊字体或字符图标**；使用 SVG 图标组件库并统一尺寸、线宽和主题色。按钮图标也要兼容键盘和屏幕阅读器。
+
+页面编辑推荐“固定模板 + 可编辑内容区块”；不实现通用拖拽建站器。复杂模板只为现有业务页面制作 React 组件。
+
+## 4. 数据与后端模块
+
+建议按业务域组织：`auth`、`content`、`products`、`filters`、`orders`、`customers`、`inquiries`、`media`、`translations`、`seo`、`jobs`。
+
+核心表按实际数据进一步细化：
+
+- 内容：`contents`、`content_translations`、`content_revisions`、`categories`、`tags`、`menus`
+- 产品：`products`、`product_translations`、`product_attributes`、`product_attribute_values`、`product_categories`、`product_variants`（如存在）
+- 商城：`users`、`carts`、`orders`、`order_items`、`payments`（按现有功能）
+- 运营：`inquiries`、`media`、`redirects`、`jobs`、`audit_logs`、`legacy_id_mappings`
+
+关键约束：
+- 多语言为真实可发布的数据版本，每种语言有独立 URL、标题、正文、SEO 字段、CTA；缺翻译时不生成伪语言页面。
+- 筛选使用合理的关系型结构、索引、稳定分页和服务端参数校验；先用真实数据和 `EXPLAIN (ANALYZE, BUFFERS)` 验证，不默认加搜索引擎。
+- 订单创建、库存扣减、付款回调使用数据库事务、幂等键、唯一约束；第三方支付回调验证签名。
+- 认证使用安全的 HttpOnly、Secure Cookie 和服务端会话校验，后台所有接口执行权限检查；敏感操作审计。
+- 后台任务实现持久化队列、失败重试与可观测性；不能依赖 Web 请求触发后台任务。
+- Public SSR 响应可按 URL/语言缓存；登录、购物车、结账、账户、个性化内容禁止共享页面缓存；发布后精准失效。
+- 前端输入、富文本、文件上传要防 XSS/CSRF/恶意上传及滥用；密钥通过环境变量管理。
+
+## 5. 多语言与 SEO 迁移（硬性验收项）
+
+- 导出全部现有 WordPress 和 GTranslate 语言 URL，结合 Search Console/Analytics/询盘数据标记高价值页面；不直接下线小语种。
+- 尽量保持现有被索引 URL；确需变化时逐条建立 301 映射，校验跳转链；维护 `canonical`、`hreflang`、多语言 Sitemap、robots 与结构化数据。
+- 翻译支持草稿、人工审核、发布和原文更新提醒；语言的导航、CTA、表单字段等均可管理。
+- 先选重点语言及代表页面试点，再逐步扩展；商城多语言不默认全量复制。
+- 迁移前后比较：HTTP 状态码、标题/描述、页面正文、内部链接、结构化数据、索引覆盖、自然搜索流量、询盘转化。
+
+## 6. 建议目录结构
+
+```text
+src/
+    routes/
+        index.tsx
+        products/
+        blog/
+        account/
+        admin/
+    components/
+        website/
+        admin/
+        icons/
+    server/
+        auth/
+        content/
+        products/
+        filters/
+        orders/
+        inquiries/
+        translations/
+        seo/
+        jobs/
+    db/
+        schema/
+        migrations/
+    styles/
+scripts/
+    wordpress-import/
+    site-capture/
+tests/
+    visual/
+    e2e/
+    integration/
+public/
+```
+
+管理端图标组件集中维护于 `src/components/icons/`，通过 ESLint/代码审查阻止新增 Emoji、图标字体及字符冒充图标。
+
+## 7. 实施步骤
+
+1. **审计与基线**：盘点页面模板、WordPress 插件实际启用业务功能、WooCommerce 支付/运输/税费流程、GTranslate 语言 URL；采集桌面/移动端截图与可复现交互；统计源站 CPU、数据库慢查询、错误日志与高频请求，不能把相关性当根因。
+2. **建模与导入**：完成 PostgreSQL 结构和迁移；编写可重复执行的 WordPress/WooCommerce 导入脚本；维护旧 ID、资源 URL 与链接映射；校验数量、关联和资源完整性。
+3. **前台 1:1 还原**：先还原公共组件与代表模板，再批量覆盖产品/文章/页面；逐项校验截图、响应式及交互。
+4. **后台业务实现**：用 React + Ant Design 实现实际使用的 CMS/商品/订单/询盘/语言/SEO 功能；不做插件机制和 Elementor 克隆。
+5. **SEO、多语言、商城验收**：重点语言试点，验证 hreflang/301/Canonical/Sitemap；测试注册、筛选、询盘、购物车、下单、支付与订单管理。
+6. **灰度上线**：测试环境压测和安全测试；Cloudflare/Nginx 小比例导流；保留旧站只读备份与可回滚部署，处理迁移期间新增订单和内容的增量同步；切换后持续监控。
+
+## 8. 验收标准
+
+- 前台：原站页面模板与典型实际页面在约定视口下视觉、交互、内容基本一致；明显差异逐项修复，所有关键功能 E2E 通过。
+- 后台：原站实际启用的业务功能逐项通过检查；所有图标均为 SVG，**无 Emoji、Icon Font、特殊字体或字符图标**。
+- SEO：重要旧链接保持可用或正确 301；多语言 URL、canonical、hreflang、Sitemap、SEO 元数据正确；重点语言测试页面可以被正常抓取。
+- 交易：注册、询盘、购物车、结账、支付回调、订单状态端到端通过，订单数据与权限受保护。
+- 性能：以原站基线为比较对象，记录 p50/p95 TTFB、慢查询、CPU/内存、错误率、缓存命中率；达到试点确定的目标后才推广。
+- 运维：有备份恢复演练、日志、监控、迁移校验报告和回滚流程。
+
+## 9. 不做的事情
+
+- 不引入 Go、微服务、WordPress/PHP 运行环境或 WordPress 插件兼容层。
+- 不复刻 WordPress 后台外观或 Elementor 通用可视化编辑器。
+- 不凭推断删除原站重要功能、语言页面、已有 URL。
+- 不在未明确数据一致性与回滚方案前一次性全站切换。
+
+## 10. 开发执行优先级
+
+**P0**：原站模板/业务审计、完整页面采集、数据模型、迁移验证、关键页面 1:1 还原。
+
+**P1**：产品筛选、询盘、后台 CRUD、多语言 SEO、缓存与性能测试。
+
+**P2**：WooCommerce 实际启用业务的交易迁移、全面语言覆盖、灰度切换与长期监控。
+
+> 本文是目标架构与实施约束；现存 WordPress 的故障根因尚未被证明，不能将新框架本身视为修复证据。