weicw1996/hjc-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(app): 添加多模板关于我们页面及相关路由和404页面

Browse Source 
- 新增404页面，优化未找到页面体验，避免被搜索引擎索引
- 增加文件代理接口，隐藏真实文件服务器地址，支持文件请求代理
- 实现/article、/case、/product及/page动态路由兼容列表与详情展示
- 添加动态CMS页面兼容入口处理旧式路径，统一路由与SEO设置
- 新增模板1、模板7、模板2、模板3关于我们页面，实现多模板支持
- 模板增强支持CMS单页内容加载及SEO信息动态设置
- 配置环境变量及Git忽略文件规则辅助开发和构建环境管理
This commit is contained in:
赵忠林
2026-09-08 12:13:44 +08:00
commit 2b69686795
381 changed files with 59891 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
开发计划.md
+480
View File
@@ -0,0 +1,480 @@
# 通用企业官网程序开发计划
> 项目目标：基于 PC 端 + H5 响应式，开发一套可复用于多租户 SaaS 的企业官网**纯前端展示系统**，支持模板切换、租户隔离、独立域名绑定、订阅过期校验等能力。
> **项目定位**：本项目仅为官网前台展示，不含任何后端管理端代码。所有数据与业务能力均通过调用自研 SaaS 后端 API 实现。
> 当前阶段：方案规划（暂不写代码）
---
## 一、项目背景与现状分析
### 1.1 项目定位
本项目是一个**纯前端展示项目**：
- ✅ 本项目负责：官网页面渲染、模板展示、SEO/SSR、H5 响应式、域名路由
- ❌ 本项目不含：后端管理端、CMS 内容管理后台、租户/应用管理控制台
- 📡 数据来源：统一调用自研 SaaS 后端（Java 多租户系统）提供的 API 接口
管理端能力（模板选择、内容编辑、域名绑定、订阅管理等）由 SaaS 后端的管理后台负责，本项目只消费其 API。
### 1.2 现有资源
| 资源 | 路径 | 说明 |
| ------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| 模板预览 | `/Users/gxwebsoft/VUE/website/templates/cloud-website/template-01.png` ~ `template-04.png` | 4 套企业官网模板效果图（静态设计稿） |
| 参考项目 | `/Users/gxwebsoft/VUE/websopy-pc` | 基于 Nuxt 4 + Vue 3 + TypeScript 的项目，可参考其技术栈、代理模式、租户 header 传递机制 |
| SaaS 后端 | 自研 Java 多租户系统 | 提供租户、应用、CMS 站点数据、订阅管理等 API 接口 |
### 1.3 参考项目 `websopy-pc` 技术栈评估
| 维度 | 现状 | 是否适合参考 |
| ------ | -------------------------------- | ----------------------------- |
| 框架 | Nuxt 4.2 + Vue 3 + TS | ✅ 适合：Nuxt 原生 SSR，对 SEO/GEO 友好 |
| UI 库 | Ant Design Vue | ⚠️ 偏后台，官网前台不使用，模板内自定义样式 |
| 用途 | 管理控制台、开发者中心、租户后台 | ❌ 本项目不包含管理端，仅参考技术栈与代理思路 |
| 已有能力 | 多租户 header、CMS 站点 API、订阅 API、代理层 | ✅ 参考其接口调用方式和代理模式 |
| SEO 支持 | 已有 `usePageSeo` composable，可扩展 | ✅ 参考其 SEO 实现思路 |
**结论**：本项目采用与 `websopy-pc` 相同的 Nuxt 4 + Vue 3 + TS 技术栈，但作为**独立的纯前端展示项目**开发。参考 `websopy-pc` 的 Server API 代理模式、`runtimeConfig` 配置、租户 header 传递机制，但不复用其管理端代码。
### 1.3 核心需求拆解
1. **模板切换**：多套官网模板可配置切换，不同租户/应用使用不同模板。
2. **多租户接入**：通过租户 ID（TenantId）和应用 ID（AppId）从 SaaS 后端拉取站点配置、页面数据、菜单、内容等。
3. **SEO + GEO**：服务端渲染（SSR）、动态 TDK、结构化数据（JSON-LD）、语义化 HTML、站点地图（Sitemap）、robots 等。
4. **H5 支持**：响应式布局，一套代码同时适配 PC 和 H5。
5. **独立域名绑定**：
- 默认二级域名：`https://site-[租户ID].shoplnk.cn`
- 支持反向代理绑定顶级域名（如 `www.example.com`）。
6. **订阅过期校验**：通过应用订阅接口判断网站是否已过期，过期后引导续费。
---
## 二、技术栈选择
| 层级 | 技术 | 选型理由 |
| ----- | ------------------------------ | ------------------------------------------------ |
| 前端框架 | **Nuxt 4**（Vue 3 + TypeScript） | 原生 SSR/SSG，SEO/GEO 友好；同 `websopy-pc` 技术栈，团队学习成本低 |
| 样式方案 | **Tailwind CSS** | 与 `websopy-pc` 一致，响应式能力强，适合多模板隔离 |
| UI 组件 | 模板内自定义 + **Shadcn/Vue** 或轻量组件库 | 官网模板风格差异大，避免强绑定单一组件库 |
| 状态管理 | Pinia / Nuxt 内置 `useState` | 简单场景用 `useState`，复杂用 Pinia |
| 请求库 | `ofetch`（Nuxt 内置） | 与 `websopy-pc` 的 `server/api` 代理模式一致 |
| 后端代理 | Nuxt **Server / Nitro** | 隐藏真实 API 域名，统一处理租户 header、缓存、鉴权 |
| 部署 | Node.js + Nginx 反向代理 | 支持自定义域名、SSL、多租户路由分发 |
---
## 三、整体架构设计
```
┌──────────────────────────────────────────────────────────────────────┐
│ 用户访问层 │
│ 默认域名: https://site-[tenantId].shoplnk.cn │
│ 自定义域名: https://www.example.com → Nginx 反向代理 │
└──────────────────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Nginx 网关层 │
│ • 根据 Host 解析租户 / 应用 ID │
│ • 自定义域名 → 查询域名-租户映射表 → 转发到 Nuxt 服务 │
│ • SSL 证书管理（通配符或单域名） │
└──────────────────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Nuxt 官网前台服务（Nitro） │
│ • Middleware：根据 Host/Header 识别当前租户与应用 │
│ • Server API：代理 SaaS 后端接口（站点信息、页面、订阅、文件等） │
│ • SSR 渲染：动态生成页面 HTML + SEO Meta + JSON-LD │
│ • 模板引擎：根据模板 ID 加载对应模板组件与样式 │
└──────────────────────────────────┬─────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ 自研 SaaS 后端（Java） │
│ • 租户管理 / 应用管理 / 订阅管理 │
│ • CMS 站点数据：站点配置、页面、栏目、文章、产品、案例等 │
│ • 订阅接口：判断应用是否过期、续费引导 │
└──────────────────────────────────────────────────────────────────────┘
```
---
## 四、目录结构规划
本项目即为 `/Users/gxwebsoft/VUE/website`，纯前端展示项目，结构如下：
```
website/
├── app/
│ ├── components/ # 公共组件（SEO、Header、Footer、Loading、Renewal）
│ ├── composables/ # 组合式函数
│ │ ├── useSite.ts # 获取当前站点信息
│ │ ├── useTenant.ts # 租户/应用识别
│ │ ├── usePageSeo.ts # SEO Meta 设置
│ │ ├── useSubscription.ts # 订阅状态校验
│ │ └── useTemplate.ts # 模板加载与切换
│ ├── layouts/ # 布局（default、blank、renewal）
│ ├── pages/ # 页面路由
│ │ ├── index.vue # 首页
│ │ ├── [slug].vue # 动态 CMS 页面（关于我们、产品中心...）
│ │ ├── news/ # 新闻资讯列表/详情
│ │ ├── products/
│ │ ├── cases/
│ │ └── renewal.vue # 续费引导页
│ ├── templates/ # 模板集合（核心）
│ │ ├── template-01/ # 模板 1：科技感蓝
│ │ │ ├── index.vue # 模板首页
│ │ │ ├── components/ # 模板私有组件
│ │ │ ├── pages/ # 模板私有页面布局
│ │ │ ├── config.ts # 模板配置（名称、预览图、支持模块）
│ │ │ └── theme.css # 模板主题变量
│ │ ├── template-02/
│ │ ├── template-03/
│ │ └── template-04/
│ ├── api/ # 前端业务请求（可选，也可直接调 server/api）
│ ├── types/ # TS 类型定义
│ ├── utils/ # 工具函数
│ ├── plugins/ # 插件
│ ├── app.vue # 根入口
│ └── error.vue # 错误页
├── server/
│ ├── api/ # 服务端代理 API
│ │ ├── site/ # 站点信息
│ │ ├── page/ # 页面内容
│ │ ├── subscription/ # 订阅状态
│ │ ├── file/ # 文件代理
│ │ └── sitemap.xml.ts # 动态站点地图
│ ├── middleware/ # 服务端中间件
│ │ └── tenant.ts # 租户识别、域名解析、订阅校验
│ └── utils/ # 服务端工具函数
├── public/ # 静态资源
├── nuxt.config.ts # Nuxt 配置
├── tailwind.config.cjs # Tailwind 配置
├── package.json
├── .env.example # 环境变量示例
└── README.md
```
---
## 五、关键模块设计方案
### 5.1 模板切换机制
模板是核心竞争力，需要设计为“可插拔”结构：
1. **模板注册表**：每个模板在 `templates/[template-id]/config.ts` 中声明：
- `id`、`name`、`description`、`preview`（预览图路径）
- `supportedModules`：该模板支持的功能模块（首页、关于、产品、案例、新闻、联系、留言）
- `themeConfig`：主题色、字体、间距等变量
- `layouts`：模板提供的布局组件
2. **模板加载**：根据后端返回的 `templateId` 动态 `import()` 对应模板组件。
3. **模板隔离**：
- CSS 使用 `data-template-id` 命名空间或 CSS Modules 隔离，避免模板间样式冲突。
- 模板组件只负责渲染，数据由 `useSite()` 统一提供。
4. **预览与切换**：模板预览和切换能力由 SaaS 后端管理后台提供，本项目根据后端返回的 `templateId` 动态渲染即可。
### 5.2 多租户识别策略
Nuxt Server Middleware 中统一识别当前租户，优先级：
1. **自定义域名**：Host 不是 `*.shoplnk.cn` 时，查询 SaaS 后端“域名绑定表”获取 `tenantId` + `appId`。
2. **默认二级域名**：`site-[tenantId].shoplnk.cn` → 从 Host 解析 `tenantId`。
3. **环境变量默认**：用于本地开发或默认演示站点。
4. **Header 兜底**：`TenantId` / `AppId` Header（用于调试或特殊场景）。
识别结果写入 `event.context.tenant` 和 `event.context.app`，供 SSR 渲染和 Server API 使用。
### 5.3 SaaS 后端接口对接
本项目作为纯前端展示层，所有数据均通过调用 SaaS 后端 API 获取。参考 `websopy-pc` 的代理模式，在 Nuxt Server 层统一转发，隐藏真实后端地址：
| 能力 | 参考来源 | 本项目实现 |
| ---- | ---------------------------------------------------------- | ------------------------------------------ |
| 站点信息 | `websopy-pc/server/api/cms/cms-website/getSiteInfo.get.ts` | `server/api/site/info.get.ts` 代理 |
| 页面列表 | `websopy-pc/server/api/cms/cms-website/pageAll.get.ts` | `server/api/page/all.get.ts` 代理 |
| 订阅状态 | SaaS 后端订阅接口 | `server/api/subscription/status.get.ts` 代理 |
| 域名映射 | SaaS 后端域名绑定查询 | `server/api/domain/resolve.get.ts` 代理 |
| 文件代理 | `websopy-pc/server/api/_file/[...path].ts` | `server/api/file/[...path].ts` 代理 |
| 表单提交 | SaaS 后端留言/表单接口 | `server/api/form/submit.post.ts` 代理 |
统一在服务端转发 `TenantId` 和必要的鉴权信息，避免前端暴露真实后端地址和鉴权细节。
### 5.4 SEO + GEO 方案
1. **SSR 渲染**：Nuxt 默认 SSR，确保搜索引擎和 AI 爬虫能拿到完整 HTML。
2. **动态 TDK**：每页根据 CMS 数据设置 `title`、`description`、`keywords`。
3. **Open Graph / Twitter Card**：每页动态设置 `og:title`、`og:description`、`og:image`、`og:url`。
4. **Canonical URL**：避免重复内容，每个页面设置 canonical 链接。
5. **结构化数据（JSON-LD）**：
- `Organization` 企业信息
- `WebSite` 站点信息
- `WebPage` 页面信息
- `Product`、`Article`、`BreadcrumbList` 等
6. **Sitemap**：`server/api/sitemap.xml.ts` 根据站点页面动态生成。
7. **Robots**：根据环境配置 `robots` meta，开发/测试环境禁止抓取。
8. **语义化 HTML**：模板组件使用 `<header>`、`<nav>`、`<main>`、`<article>`、`<footer>` 等标签。
9. **URL 设计**：简洁语义化，如 `/about`、`/products`、`/news/[id]`。
### 5.5 H5 响应式
- 模板设计采用 **Mobile First** 原则。
- 使用 Tailwind 断点：`sm: md: lg: xl:`。
- 导航组件在 H5 下自动切换为汉堡菜单。
- 图片、视频使用响应式尺寸，避免移动端加载过大资源。
- 针对 H5 独立优化首屏加载性能（Lazy loading、资源预加载）。
### 5.6 独立域名绑定
#### 5.6.1 默认二级域名
- 格式：`https://site-[tenantId].shoplnk.cn`
- 在 Nginx 配置泛域名解析：`*.shoplnk.cn` → Nuxt 服务。
- Server Middleware 从 Host 中解析 `tenantId`。
#### 5.6.2 自定义顶级域名
- 用户在 SaaS 后台绑定域名 `www.example.com`。
- SaaS 后端记录“域名 → 租户 + 应用”映射。
- Nginx 监听 `www.example.com`（或默认 `server_name` 兜底），转发到 Nuxt 服务。
- Nuxt Server Middleware 通过域名查询后端映射表获取租户信息。
- SSL 证书：建议使用 Nginx 统一管理，可采用 Let's Encrypt 自动化证书，或 SaaS 后台提供证书上传。
### 5.7 订阅过期校验与续费引导
1. **订阅校验位置**：
- Nuxt Server Middleware：每次请求先校验当前应用的订阅状态。
- 前端挂载时：再次校验（防止 SSR 后状态变化）。
2. **过期状态处理**：
- 未过期：正常渲染。
- 已过期/未购买：渲染“续费引导页”（`pages/renewal.vue`），可保留展示站点基础信息，但隐藏关键功能和联系方式，或整站显示续费提示。
3. **续费接口**：调用 SaaS 后端订阅/续费接口，支付完成后刷新页面。
4. **缓存策略**：订阅状态可缓存短时间（如 60 秒），避免每次请求都调用后端，但要保证过期时及时切换。
---
## 六、开发阶段规划
建议按以下阶段推进，每个阶段产出可验证的里程碑。
### 第一阶段：基础框架搭建（约 1 周）
- [ ] 新建独立 Nuxt 4 项目（参考 `websopy-pc` 技术栈，但不含管理端代码）。
- [ ] 配置 TypeScript、Tailwind CSS、ESLint。
- [ ] 搭建基础目录结构（layouts、pages、composables、server）。
- [ ] 配置环境变量（`NUXT_PUBLIC_TENANT_ID`、`NUXT_PUBLIC_API_BASE`、`NUXT_PUBLIC_TEMPLATE_ID` 等）。
- [ ] 实现基础 Server Middleware：租户识别、域名解析、请求代理。
- [ ] 实现 `useSite()`、`useTenant()`、`usePageSeo()` 等核心 composables。
- [ ] 接入 SaaS 后端“站点信息”和“页面列表”接口。
**里程碑**：访问 `site-[tenantId].shoplnk.cn` 能显示基础首页，并从后端读取到站点标题和页面数据。
### 第二阶段：模板系统（约 1.5 周）
- [ ] 将现有 4 套模板设计稿转化为可运行的 Vue 组件（按 `templates/template-01/` 结构）。
- [ ] 设计模板配置规范（`config.ts`）和模板加载器（`useTemplate()`）。
- [ ] 实现模板样式隔离方案。
- [ ] 实现模板切换逻辑：根据后端 `templateId` 动态渲染对应模板。
- [ ] 提取公共组件：SiteHeader、SiteFooter、HeroSection、SectionTitle、ContactForm 等。
- [ ] 预留 CMS 模块接口：首页、关于我们、产品中心、案例展示、新闻资讯、联系我们。
**里程碑**：切换后端 `templateId`，页面能实时渲染不同模板风格。
### 第三阶段：页面路由与 CMS 渲染（约 1 周）
- [ ] 实现动态路由：`[slug].vue` 根据 CMS 页面配置渲染。
- [ ] 实现新闻、产品、案例列表页和详情页。
- [ ] 实现面包屑导航。
- [ ] 实现联系表单（提交到 SaaS 后端）。
- [ ] 对接 CMS 富文本内容渲染。
- [ ] 实现 404 页面和错误页。
**里程碑**：通过 CMS 配置的新页面能自动出现路由并正确渲染；新闻/产品/案例模块正常展示。
### 第四阶段：SEO / GEO 与性能优化（约 1 周）
- [ ] 全站动态 TDK、Open Graph、Canonical URL。
- [ ] 实现 JSON-LD 结构化数据注入。
- [ ] 实现动态 `sitemap.xml` 和 `robots.txt`。
- [ ] 配置图片懒加载、资源预加载、字体优化。
- [ ] 接入 Nuxt 性能分析，优化首屏加载时间。
- [ ] 验证 SSR 输出 HTML 是否完整可被爬虫抓取。
**里程碑**：搜索引擎能抓取完整页面；通过 Lighthouse SEO 评分基本项。
### 第五阶段：域名绑定与部署（约 1 周）
- [ ] Nginx 配置泛域名解析 `*.shoplnk.cn`。
- [ ] 实现自定义域名反向代理。
- [ ] 实现域名-租户映射查询（后端接口 + Nuxt Server Middleware）。
- [ ] SSL 证书方案确定并配置（通配符证书或单域名证书）。
- [ ] 编写部署脚本和 Dockerfile（可参考 `websopy-pc/Dockerfile`）。
- [ ] 配置 CI/CD 流程。
**里程碑**：`site-[tenantId].shoplnk.cn` 和自定义域名都能正常访问对应租户站点。
### 第六阶段：订阅过期与续费（约 0.5 周）
- [ ] 接入 SaaS 订阅查询接口。
- [ ] 在 Server Middleware 中校验订阅状态。
- [ ] 实现续费引导页（`renewal.vue`）。
- [ ] 实现过期后页面降级策略（展示基础信息 vs 完全屏蔽）。
- [ ] 对接续费支付流程。
**里程碑**：订阅过期后自动展示续费引导页；续费成功后恢复正常访问。
### 第七阶段：H5 适配与收尾（约 1 周）
- [ ] 所有模板完成 H5 响应式适配。
- [ ] 移动端导航、表单、图片、视频优化。
- [ ] 多端测试（iOS Safari、Android Chrome、微信内置浏览器）。
- [ ] 编写项目文档、模板开发规范、部署文档。
- [ ] 代码审查、性能测试、安全测试。
**里程碑**：PC 和 H5 都能正常访问；模板开发规范文档化。
---
## 七、环境变量规划（示例）
```bash
# SaaS 后端接口地址
NUXT_PUBLIC_SERVER_API_BASE=https://cms-api.websoft.top
NUXT_PUBLIC_MODULES_API_BASE=https://cms-api.websoft.top/api
# 默认租户/应用（本地开发或演示）
NUXT_PUBLIC_TENANT_ID=1
NUXT_PUBLIC_APP_ID=website
NUXT_PUBLIC_TEMPLATE_ID=template-01
# 域名配置
NUXT_PUBLIC_BASE_DOMAIN=shoplnk.cn
# 缓存与订阅校验
NUXT_SUBSCRIPTION_CACHE_TTL=60
```
---
## 八、风险与注意事项
| 风险点 | 说明 | 建议 |
| ----------------- | ------------------------ | ----------------------------- |
| 模板样式冲突 | 多模板共享全局 CSS 可能互相污染 | 使用 CSS 命名空间或 CSS Modules 隔离 |
| 自定义域名 HTTPS | 每个域名都需要证书，管理复杂 | 优先使用通配符证书或 SaaS 后台统一证书管理 |
| 租户数据安全 | 域名解析错误可能导致串站 | Server Middleware 严格校验域名-租户映射 |
| SEO 数据缺失 | 后端 CMS 未配置 TDK 时页面为空 | 提供默认值和必填校验 |
| 订阅校验性能 | 每次请求都校验会增加延迟 | 使用服务端缓存，过期时间 60 秒内 |
| H5 适配工作量大 | 4 套模板都要做响应式 | 前期约定模板栅格规范，公共组件优先做响应式 |
| 与 `websopy-pc` 耦合 | 本项目为纯展示，不引入管理端依赖 | 独立项目，仅参考接口协议和代理思路 |
| 接口依赖 | 本项目所有功能依赖 SaaS 后端 API 可用 | 做好接口异常降级处理（默认数据、缓存兜底） |
---
## 九、下一步建议
1. **确认技术方案**：本项目作为纯前端展示项目，采用 Nuxt 4 + Vue 3 + TS 技术栈，不含管理端代码，所有功能通过 SaaS 后端 API 实现——是否确认？
2. **确认 SaaS 接口协议**：
- 站点信息接口字段定义
- 域名绑定查询接口
- 订阅状态查询接口
- 新闻/产品/案例 CMS 数据接口
- 表单/留言提交接口
3. **确认模板规范**：模板数据由 SaaS 后端管理后台配置，本项目根据 `templateId` 渲染——是否确认？
4. **确认域名与证书方案**：`shoplnk.cn` 泛域名证书是否已准备？自定义域名证书如何管理？
5. **确认首期范围**：是否 4 套模板一次全部实现？还是先实现 1 套 MVP，后续扩展？
---
*文档生成时间：2026-07-05*
*版本：v1.1（明确纯前端展示项目定位）*
---
## 十、专项附录：标书购买功能（template-07 / 客户「汇吉采」）
> **性质**：这是叠加在基础官网框架之上的**客户专项需求**，不修改基础框架的定位与计划（一至九节保持不变）。
> **代码边界**：前端改动在本仓库（website-template）；后端改动在 **`cms-java-code` 仓库（即线上 cms-api）**，本仓库的 `server/api/*` 只做代理转发，不含交易逻辑。
### 10.1 后端选型结论（已评估确定）
**在 `cms-api`（= `cms-java-code`，即自研 SaaS 后端）内新增「标书」业务包，复用其已有的 `shop` 订单 + `payment` 微信扫码支付底座；不单独启用 `guilixu-java`。**
依据（已查代码确认）：
- 模板当前只连 cms-api（`modulesApiBase = https://cms-api.websoft.top/api`），前端零新增对接。
- cms-api 已内置：会员/用户体系（`ShopUser`、JWT）、`ShopOrder`、`PaymentController.createPaymentWithOrder`（建单+发起支付）、`WechatNativeStrategy`（返回 `codeUrl`）、`PaymentNotifyController`（异步回调）、多租户（`TenantId` 头）。
- `guilixu-java` 只是 cms-api 的裁剪分支（仅 payment+shop+common，无 cms），且独立部署、独立数据库，单独启用只增加跨库/跨服务成本、无收益。
> 详见 `outputs/汇吉采-标书购买-后端选型评估.md` 与 `outputs/汇吉采-标书购买功能方案评估.md`。
### 10.1.1 前端隔离策略（已决策：fork 独立网站端）
**决策依据（2026-08-26 与主人确认）**：
1. 标书购买是汇吉采**独家特色**，其他客户基本不会用 → 不应塞进通用模板污染内核。
2. 不排除汇吉采未来出现**更多深度定制**（不止标书） → 深度定制会持续侵蚀通用模板边界，fork 比在通用模板里写 `if (tenantId===10626)` 更干净。
3. 独立部署/运维：暂未知 → fork 不强制立即独立部署，可先 fork 代码、共用部署，待需求明确再切。
**结论**：前端**从本仓库 fork 出独立端（如 `website-huijicai`，基于 git branch 分出）**，汇吉采专属功能（标书购买 + 未来定制）只在独立端内开发，通用 website-template 保持纯净。
**fork 的正确姿势（规避维护噩梦）**：
- 用 **git branch / 独立仓库 + 共享子模块**，不要把通用内核复制粘贴成两份。
- 分层：通用内核（SEO、多租户中间件、部署脚本、基础组件）与汇吉采定制区（template-07 + 标书模块 + 未来定制）分离，定制区单独维护。
- 约定：通用安全/框架更新通过 **rebase / cherry-pick** 同步到独立端，防止长期漂移到"老版本分支"。
**后端不 fork（重要）**：cms-api 是多租户 monolith，fork 整个后端代价极高且不必要。`tender` 业务包直接在 cms-api 内新增，数据带 `tenantId=10626` 天然隔离，复用现有 shop/payment 底座。**即：前端物理隔离 + 后端租户逻辑隔离。**
### 10.2 前端任务清单（独立端 `website-huijicai`）
| 任务 | 做法 | 复用/新增 |
| ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------- |
| ① 激活 `buy` 入口 | 新增 `app/pages/buy.vue`，照搬 `renewal.vue` 加载 `components.BuyDocument`；无需改 `useTemplate` 核心 | 复用现有 routeMap `buy` 钩子 |
| ② `BuyDocument.vue` 改造 | 占位 stub → 购买流程壳（列表 + 详情 + 表单 + 支付二维码 + 结果页） | 改写现有文件 |
| ③ 标书列表/详情 | 仿 `ProductList/ProductDetail` 结构接 `tender` 接口（status=onsale 筛选、关键词、分类） | 复制改造 |
| ④ 联系表单 | 姓名/电话/邮箱/公司，**复用 `ContactForm` 手机号校验 + 滑块验证码** | 复用 |
| ⑤ 注册/登录页 | `register.vue` / `login.vue` + `useSupplier` 登录态 composable（Token 存 cookie）+ 购买入口权限门控 | 新增 |
| ⑥ 支付页 | 展示后端返回的 `code_url` 二维码 + **轮询订单状态** + 支付成功展示「下载标书」/「已发邮件」 | 新增 |
### 10.3 后端任务清单（cms-java-code 仓库，新增 `tender` 业务包）
- 实体：`Tender`（招标编号、发售起止、状态 onsale/ended、售价、关联文件）、`TenderOrder`（或复用 `ShopOrder` + 类型标识）、可选 `SupplierProfile`。
- 接口：
- `GET /api/tender/list`（按 status=onsale + 分类/关键词筛选）
- `GET /api/tender/detail`
- `POST /api/tender/order`（建单 + 微信扫码支付，复用 `createPaymentWithOrder`）
- `POST /api/tender/notify`（复用 `WxPayNotifyService` 异步回调置已支付）
- `GET /api/tender/order/status`（前端轮询）
- `GET /api/tender/order/download`（登录态 + 订单校验后下载标书 / 发邮件）
- 供应商账号：复用现有 `shop` 用户体系（加 `supplier` 角色/字段），下单接口要求 `loginUser != null`（已有约束天然实现"注册登录后才能买"）。
### 10.4 里程碑（建议）
1. **M1 后端底座就绪**：`tender` 实体 + 列表/详情/筛选接口 + 下单/支付/回调/交付全链路（复用 shop/payment）。
2. **M2 前端流程闭环**：`buy` 入口激活 + 列表/详情/表单/支付/结果页，能完整走通"注册→筛选项目→填信息→扫码付→下载"。
3. **M3 联调与权限校验**：下单时后端强制校验项目状态=onsale（防绕过）、支付回调稳定、邮件/下载双通道验证。
4. **M4 上线增强（P1）**：我的购买记录、后台标书上架审核、邮件模板润色。
### 10.5 仍需拍板（阻塞排期）
1. **生产拓扑**：汇吉采生产是否真的只连 cms-api？（从模板对接关系看是，需确认是否双后端）
2. **供应商建模**：复用 shop 会员表（加角色/字段）还是新建 `supplier` 表？（建议前者）
3. **标书建模**：新建 `Tender` 实体 vs 当特殊商品复用 `ShopGoods`？（建议新建 `Tender`，语义清晰）
4. **微信商户号**：cms-api 的微信支付配置（租户 10626）是否已配好商户号与公网 `notify_url`？
### 10.6 拍板结果（2026-08-26 已确认，含修正）
主人就 10.5 四项给出结论，并已 fork 出独立端 `/Users/gxwebsoft/VUE/website-huijicai`（master 分支、干净无改动、remote 指向 `website-huijicai.git`）。
1. **生产拓扑**：不排除双后端。→ **前端代理层预留可切换的 `tenderApiBase`：默认指向 cms-api（复用其 shop+payment 单库闭环），若确认交易走 guilixu-java 仅改 env 即可，前端代码不变**。最终生产拓扑需在开发启动前敲定（决定 baseURL 默认值）。
2. **供应商建模**：主人原提"复用 sys_user"，已**纠正为复用 `ShopUser`（前端会员表）**。`sys_user` 是后台管理员表（`common/system` 包），供应商复用它会混进后台权限，不安全。
- `ShopUser` 字段已极全：`type`(0个人/1企业/2其他)、`phone`、`email`、`realName`、`companyId`、`certification`(实名认证)、`tenantId` 等；加一个 `supplierStatus`(0非供应商/1待认证/2已认证) 标记字段即可，**无需新建表**。
- **⚠️ 缺口（影响 P0）**：cms-api 当前前端会员登录以**微信登录为主**（`WxLoginController.loginByMpWxPhone`），**未找到账号密码/短信验证码的会员注册登录接口**。若客户要求账号密码/短信注册（招投标场景常见），需**新建会员注册登录接口**（P0 增量），待确认客户登录方式。
3. **标书建模**：确认新建 **`Tender` 实体**（标书项目表）。订单直接复用 **`ShopOrder`**（其已有 `type` 订单类型字段，标书订单用 `type=3`；需把 `PaymentWithOrderRequest.OrderInfo.type` 的 `@Max(2)` 放开到 3）。
4. **微信商户号**：已就绪（租户 10626 商户号 + 公网 `notify_url`）。✅ 支付可推进。
> 前后端详细清单见 `outputs/汇吉采-标书购买-前端清单与后端接口清单.md`。