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. 建议目录结构

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. 实施步骤

审计与基线：盘点页面模板、WordPress 插件实际启用业务功能、WooCommerce 支付/运输/税费流程、GTranslate 语言 URL；采集桌面/移动端截图与可复现交互；统计源站 CPU、数据库慢查询、错误日志与高频请求，不能把相关性当根因。
建模与导入：完成 PostgreSQL 结构和迁移；编写可重复执行的 WordPress/WooCommerce 导入脚本；维护旧 ID、资源 URL 与链接映射；校验数量、关联和资源完整性。
前台 1:1 还原：先还原公共组件与代表模板，再批量覆盖产品/文章/页面；逐项校验截图、响应式及交互。
后台业务实现：用 React + Ant Design 实现实际使用的 CMS/商品/订单/询盘/语言/SEO 功能；不做插件机制和 Elementor 克隆。
SEO、多语言、商城验收：重点语言试点，验证 hreflang/301/Canonical/Sitemap；测试注册、筛选、询盘、购物车、下单、支付与订单管理。
灰度上线：测试环境压测和安全测试；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 的故障根因尚未被证明，不能将新框架本身视为修复证据。

10 KiB Raw Permalink Blame History Unescape Escape