diff --git a/docs/superpowers/specs/2026-04-16-vite-low-intrusion-mpa-design.md b/docs/superpowers/specs/2026-04-16-vite-low-intrusion-mpa-design.md deleted file mode 100644 index 28002d6..0000000 --- a/docs/superpowers/specs/2026-04-16-vite-low-intrusion-mpa-design.md +++ /dev/null @@ -1,521 +0,0 @@ -# Vite 低侵入接入设计（多页面静态站） - -**日期：** 2026-04-16 -**项目：** AgWeb 静态企业站 -**目标：** 在不重构现有站点架构的前提下，为当前多页面静态网站接入 Vite，提供稳定的开发、构建与可直接部署的生产产物。 - ---- - -## 1. 背景与目标 - -当前项目是一个传统多页面静态站：根目录下存在大量 `.html` 页面，公共资源位于 `assets/`，页面脚本以 jQuery 和全局脚本顺序加载为主，`header.html` / `footer.html` 通过运行时 `.load()` 拉取。项目目前没有任何包管理、构建流程或统一的生产输出目录。 - -本次接入的目标不是把站点现代化重写，而是先建立一层稳定的构建底座，使项目具备以下能力： - -- 使用统一命令进行本地开发 -- 使用统一命令输出生产构建产物 -- 产出一个可直接静态部署的 `dist/` 目录 -- 保留当前多页面结构、相对路径部署模型和大部分旧代码行为 -- 为后续首页性能优化和局部模块化收编提供基础设施 - ---- - -## 2. 非目标（明确不做） - -以下内容不属于本次设计范围： - -- 不把整站改造成 SPA / CSR 应用 -- 不引入 Vue、React 或其他 UI 框架 -- 不要求把所有 JS 改写为 ESM 模块 -- 不立即替换 jQuery 及其插件体系 -- 不立即把 `header.html` / `footer.html` 改成构建期注入 -- 不立即重构整站 CSS 架构 -- 不把“接入 Vite”与“首页性能彻底治理”绑定为同一阶段目标 - -这样划边界的原因很简单：当前项目的价值在于先低风险建立构建与部署流程，而不是一次性重做前端技术栈。 - ---- - -## 3. 项目现状理解 - -### 3.1 当前结构 - -项目当前是典型多页面静态站： - -- 根目录：大量面向访问的 `.html` 页面 -- `assets/`：CSS、JS、图片、字体等公共资源 -- `classiccase/`：案例子目录页面 -- `huace/`：独立子目录页面 -- `header.html` / `footer.html`：公共片段 - -### 3.2 已知技术特点 - -- HTML + Bootstrap 3.3.4 + jQuery -- 依赖脚本顺序与全局变量 -- 大量相对路径资源引用 -- 公共头尾通过运行时 `.load()` 获取 -- 没有现成 `package.json`、`vite.config`、锁文件或前端工程化配置 - -### 3.3 对本次设计的约束影响 - -这些现状意味着： - -1. Vite 必须按 **MPA（多页面应用）** 方式接入，而不是 SPA 模型。 -2. 第一阶段必须尽量保守，不应强行把旧脚本收编成模块。 -3. 目录层级和相对路径兼容性比“资源自动最优打包”更重要。 -4. `header.html` / `footer.html` 必须被视为运行时依赖的静态片段，而不是普通入口页面。 - ---- - -## 4. 方案选型 - -### 4.1 被考虑的方案 - -#### 方案 A：Vite 低侵入多页面接入（推荐） - -保留现有 HTML 页面与资源目录，把 Vite 用作多页面静态站的开发服务器与生产构建器。第一阶段以“构建稳定”和“可部署”优先，不强行收编旧脚本体系。 - -#### 方案 B：Vite + 同步结构整理 - -接入 Vite 的同时，顺便调整头尾复用方式、首页资源加载、重点页面 JS 入口组织。这能带来更大中期收益，但改动面明显增大，不符合本次“低侵入”目标。 - -#### 方案 C：继续保持纯静态站，只增加零散压缩工具 - -可以做局部压缩，但不能形成统一开发/构建/输出体系，后续演进空间小，不能满足本次目标。 - -### 4.2 推荐方案 - -选择 **方案 A：Vite 低侵入多页面接入**。 - -### 4.3 选择理由 - -- 最匹配当前站点形态 -- 最符合“原样可部署”的要求 -- 风险最低 -- 不会把“构建底座建设”和“站点重构”混成一件事 -- 能为后续按页面优化资源加载提供稳定基础 - ---- - -## 5. 目标产物与使用方式 - -接入完成后，项目应具备以下使用方式： - -### 5.1 开发命令 - -- `npm install` -- `npm run dev` - -### 5.2 构建命令 - -- `npm run build` -- `npm run preview` - -### 5.3 输出结果 - -构建后得到： - -- `dist/index.html` -- `dist/company.html` -- `dist/contact.html` -- `dist/product_*.html` -- `dist/solution_*.html` -- `dist/classiccase/*.html` -- `dist/huace/huace.html` -- `dist/assets/...` -- `dist/header.html` -- `dist/footer.html` - -### 5.4 部署要求 - -`dist/` 应能作为普通静态目录整体部署： - -- 可放在 Nginx 静态目录下 -- 可部署到对象存储/CDN 静态站 -- 不依赖服务端模板系统 -- 不依赖 SPA 路由重写 -- 仍按相对路径站点模型运行 - ---- - -## 6. 结构设计 - -### 6.1 新增文件 - -本次应新增最小工程化文件集： - -- `package.json` -- `vite.config.js` -- `.gitignore` -- 可选：开发说明文档补充 - -#### 各文件职责 - -**`package.json`** 仅承担工具入口职责： -- 安装 `vite` -- 提供 `dev` / `build` / `preview` 命令 - -**`vite.config.js`** 是核心配置文件，负责： -- 多页面入口配置 -- 输出目录配置 -- 相对路径部署兼容 -- 非入口静态文件保留策略 - -**`.gitignore`** 负责忽略： -- `node_modules/` -- `dist/` - -### 6.2 保留现有目录结构 - -以下目录和结构在第一阶段保留不动： - -- 根目录 HTML 页面 -- `assets/css` -- `assets/js` -- `assets/images` -- `assets/fonts` -- `header.html` -- `footer.html` -- `classiccase/` -- `huace/` - -设计上，Vite 接入应适配现有结构，而不是要求现有结构先重排后接入。 - ---- - -## 7. 多页面入口策略 - -### 7.1 入口页面的定义 - -入口页面必须满足： - -- 用户会直接访问 -- 页面是完整 HTML 文档 -- 有独立 URL 语义 - -### 7.2 第一阶段纳入入口的页面 - -#### 根目录页面 - -包括但不限于： -- `index.html` -- `company.html` -- `contact.html` -- `culture.html` -- `joinus.html` -- 各类 `product_*.html` -- 各类 `solution_*.html` -- 其他实际对外页面 - -#### 子目录页面 - -包括： -- `classiccase/*.html` -- `huace/huace.html` - -### 7.3 不作为入口的文件 - -以下文件不应纳入多页面入口集合： - -- `header.html` -- `footer.html` - -#### 原因 - -它们不是独立页面，而是运行时被 `.load()` 获取的片段。若错误地把它们当作入口页面处理，会混淆构建语义，也不利于后续逐步替换片段加载模式。 - ---- - -## 8. 静态资源与片段处理策略 - -### 8.1 `assets/` 的策略 - -第一阶段将 `assets/` 视为兼容层，而不是重构对象。 - -也就是说： -- 现有页面继续使用 `assets/...` 相对引用 -- 构建后仍保留 `dist/assets/...` 语义 -- 尽量不要求页面把资源改写为模块导入 - -#### 理由 - -如果第一阶段就要求所有图片、CSS、JS 都纳入现代模块导入体系，改动面会迅速扩大，和“低侵入接入”目标冲突。 - -### 8.2 `header.html` / `footer.html` 的策略 - -第一阶段保留现有运行时加载方式： - -```js -$("#header").load("header.html"); -$("#footer").load("footer.html"); -``` - -但设计上必须把这视为一个明确兼容要求： - -- 构建后片段文件必须仍然存在于 `dist/` 中 -- 片段路径关系不能因构建被破坏 -- 根目录页面和子目录页面都必须验证其加载行为 - -### 8.3 其他运行时静态依赖 - -若后续发现还有类似 `header/footer` 的运行时请求文件，也应归入“静态保留文件”，而不是强行纳入入口页面集合。 - ---- - -## 9. 路径与部署设计 - -### 9.1 核心约束 - -用户明确选择的是： - -- 构建后产物应原样可部署 -- `dist/` 应可作为静态站整体拷贝部署 -- 不应要求服务端特殊模板或路由逻辑 - -### 9.2 路径策略 - -因此路径设计必须围绕以下原则： - -- 采用适合相对路径部署的 Vite 配置 -- 构建后不能假设站点一定部署在域名根路径 -- 子目录页面构建后仍需能正确解析其资源路径与片段路径 - -### 9.3 兼容重点 - -这套设计中最需要重点看护的是： - -- 根目录页面资源路径 -- 子目录页面资源路径 -- 子目录页面对 `header/footer` 的请求路径 - -因为相对路径在不同目录层级上的含义不同，这部分是第一阶段成功与否的关键风险点。 - ---- - -## 10. 实施边界与脚本策略 - -### 10.1 为什么不立即收编旧脚本 - -当前脚本体系强依赖： - -- `