chuanggao-website/技术资产参考文档.md

# 萨格官网技术资产参考文档

> 本文档用于指导创高家具官网（新项目）的开发，基于萨格官网现有技术架构整理。

---

## 一、技术栈总览

| 层级 | 技术选型 | 关键路径 |
|------|----------|----------|
| 前端 | Vue 3 + Vite + Element Plus + vue-i18n | 入口 `client/`，构建输出 `client/dist` |
| 后端 | Spring Boot 3 + MyBatis + MySQL + Druid | 统一接口前缀 `/api`（context-path） |
| 安全认证 | Sa-Token + Redis | 会话管理 |
| 文件存储 | MinIO / 本地磁盘 | 推荐生产用 MinIO 独立 bucket |
| 部署 | Nginx 反向代理 | `/`→前端静态文件，`/api`→后端服务 |

---

## 二、数据库规范

### 2.1 命名规范
- **表前缀**：`f_`
- **业务库名示例**：`wuhan_saga`（萨格）、`chuanggao_furniture`（创高家具）
- **全量 DDL**：`server/src/main/resources/schema.sql`
- **补丁脚本**：`database/` 目录

### 2.2 核心表分类

| 类型 | 表示例 | 说明 |
|------|--------|------|
| 公司信息 | `f_company` | 站点基础信息配置 |
| 轮播管理 | `f_carousel` | 首页轮播图 |
| 内容管理 | `f_news`、`f_news_cat` | 新闻及分类 |
| 产品体系 | `f_product_cat`、`f_product`、`f_spare_part` | 产品分类/整线/单体/备件 |
| 案例展示 | `f_case`、`f_case_cat` | 案例及分类 |
| 技术文章 | `f_technology` | 技术文档 |
| 媒体库 | `f_media_library` | 统一上传文件管理 |

---

## 三、多站点机制（Site Code）

### 3.1 设计目的
通过 `site_code` 实现同一套代码服务不同品牌站点，数据逻辑隔离。

### 3.2 配置位置

**后端（application.yml）**
```yaml
app:
  portal:
    site-code: saga          # 当前实例服务站点
    allowed-site-codes:      # 允许前台访问的站点白名单
      - saga
      - cg
```

**前端（.env.production）**
```
VITE_PORTAL_SITE_CODE=saga    # 与后端 site-code 对齐
```

### 3.3 数据隔离方式
- **共用表**（如新闻、分类）：带 `site_code` 字段，查询时自动过滤
- **独立表**（如公司信息、产品）：每站一条记录，天然隔离

### 3.4 接口规范
```
前台只读接口：/portal/news、/portal/case、/portal/case/category
管理端接口：/admin/**（需登录 Sa-Token）
```

---

## 四、附件存储规范

### 4.1 存储模式

| 模式 | 配置项 | 说明 |
|------|--------|------|
| 本地磁盘 | `upload.storage=local` | 写入 `upload.path` 指定目录 |
| MinIO | `upload.storage=minio` | 走 MinIO 对象存储 |

### 4.2 MinIO 配置（推荐生产用）
```yaml
upload:
  storage: minio
  
minio:
  endpoint: http://minio-server:9000
  access-key: ${MINIO_ACCESS_KEY}
  secret-key: ${MINIO_SECRET_KEY}
  bucket: saga-prod          # 创高项目建议换独立 bucket
```

### 4.3 路径规范
- 库中存储路径：`/uploads/分类/文件名`（如 `/uploads/news/2024/abc.jpg`）
- 前端访问方式：通过 `/api` + 该路径（Nginx 反代到后端或 MinIO）
- **注意**：不必把 MinIO 直出给浏览器，统一走 `/api` 保持灵活性

### 4.4 迁移脚本
- 本地 uploads 同步到 MinIO：`scripts/sync-uploads-to-minio.ps1`
- 部署文档：`server/deploy/MINIO_DEPLOY.md`
- 配置示例：`server/deploy/minio-spring-config.example.yml`

---

## 五、部署架构

### 5.1 Nginx 配置模板
```nginx
server {
    listen 80;
    server_name www.chuanggao.com;
    
    # 前端静态资源
    location / {
        root /var/www/chuanggao-website/client/dist;
        try_files $uri $uri/ /index.html;
    }
    
    # 后端 API
    location /api {
        proxy_pass http://localhost:8080/api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 5.2 部署目录结构（建议）
```
/opt/chuanggao-website/
├── client/dist/              # 前端构建产物
├── server.jar                # 后端可执行 jar
├── upload/                   # 本地存储模式用（如选 MinIO 可省略）
└── logs/                     # 应用日志
```

---

## 六、开发环境配置

### 6.1 前端代理（vite.config.ts）
```typescript
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true
    }
  }
}
```

### 6.2 后端跨域（开发时）
- 由 Vite 代理解决，后端无需额外 CORS 配置
- 生产环境同域部署，无跨域问题

---

## 七、创高家具站适配清单（A方案：独立库）

### 7.1 必须修改的文件

| 文件路径 | 修改内容 |
|----------|----------|
| `server/pom.xml` | `artifactId` 改为 `chuanggao-furniture`，`name` 改为"创高家具官网" |
| `server/src/main/resources/application.yml` | 库名 `chuanggao_furniture`、MinIO bucket `chuanggao-furniture-prod`、site-code `cg` |
| `server/src/main/resources/schema.sql` | 新公司信息、家具分类种子数据（沙发/床垫/全屋等） |
| `client/.env.production` | `VITE_PORTAL_SITE_CODE=cg` |
| `client/index.html` | 页面标题改为"创高家具" |
| `client/src/locales/zh-cn.ts` | 替换所有"萨格"专有文案 |
| `client/src/views/home/` | 首页模块重组（轮播、品类入口、品牌故事、门店/活动） |

### 7.2 建议删减的模块（工控专用）
- 技术文章模块（`f_technology`）
- 工控案例体系（`f_case` 中的工业场景）
- 复杂的备件体系（`f_spare_part` 简化）

### 7.3 建议新增的模块（家具专用）
- 门店/卖场分布（新表 `f_store`）
- 促销活动（新表 `f_promotion`）
- 品牌合作展示（新表 `f_partner`）
- 全屋定制方案（扩展产品体系）

### 7.4 品牌视觉调整
- 主色从"工业蓝"改为"暖色/木色"（家具城常见风格）
- Logo 替换为创高品牌标识
- 首页布局弱化技术感，强化"舒适、品质、生活场景"

---

## 八、关键文档/脚本索引

| 用途 | 路径 |
|------|------|
| MinIO 部署指南 | `server/deploy/MINIO_DEPLOY.md` |
| MinIO 配置示例 | `server/deploy/minio-spring-config.example.yml` |
| 本地同步到 MinIO | `scripts/sync-uploads-to-minio.ps1` |
| 数据库全量 DDL | `server/src/main/resources/schema.sql` |
| 数据库补丁 | `database/` |

---

## 九、决策确认（创高项目）

| 决策项 | 选择 |
|--------|------|
| 数据库方案 | **A方案：独立库**（新 schema，干净无历史数据） |
| 仓库策略 | Fork 后独立维护（改 artifact、项目名、文案） |
| 首页模块 | 轮播 + 品类入口 + 品牌故事 + 门店/活动 |
| MinIO | 独立 bucket `chuanggao-furniture-prod` |
| 双语支持 | 待定（先确认创高品牌定位） |

---

*文档创建时间：2026-05-08*
*基于项目：萨格官网（工控行业）*
*目标项目：创高官网（家具行业）*