weicw1996/hjc-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0fbf122a57a2f0c634b80931631d1c84c3e1cb2a
hjc-web/开发计划.md
T
gxwebsoft 2b69686795 feat(app): 添加多模板关于我们页面及相关路由和404页面 
- 新增404页面，优化未找到页面体验，避免被搜索引擎索引
- 增加文件代理接口，隐藏真实文件服务器地址，支持文件请求代理
- 实现/article、/case、/product及/page动态路由兼容列表与详情展示
- 添加动态CMS页面兼容入口处理旧式路径，统一路由与SEO设置
- 新增模板1、模板7、模板2、模板3关于我们页面，实现多模板支持
- 模板增强支持CMS单页内容加载及SEO信息动态设置
- 配置环境变量及Git忽略文件规则辅助开发和构建环境管理
2026-09-08 12:13:44 +08:00

481 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 通用企业官网程序开发计划
> 项目目标：基于 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`。
Reference in New Issue View Git Blame Copy Permalink