168 lines
10 KiB
Markdown
168 lines
10 KiB
Markdown
# 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 的故障根因尚未被证明，不能将新框架本身视为修复证据。
|