martial-web/README.md

# 武术赛事通 - 前端项目

基于 Vue 3 + Vite + Element Plus 构建

## 🌐 在线访问

- **生产环境**: https://martial.johnsion.club
- **后端 API**: https://martial-api.johnsion.club
- **API 文档**: https://martial-doc.johnsion.club

## 📦 技术栈

- **框架**: Vue 3.4 (Composition API)
- **构建工具**: Vite 5
- **UI 组件**: Element Plus
- **表单/表格**: Avue
- **HTTP 库**: Axios
- **路由**: Vue Router 4
- **状态管理**: Vuex 4
- **样式**: Sass/SCSS

## 📁 项目结构

```
martial-web/
├── src/
│   ├── main.js              # 应用入口
│   ├── App.vue              # 根组件
│   ├── router/              # 路由配置
│   ├── store/               # Vuex 状态管理
│   ├── views/               # 页面组件
│   ├── components/          # 通用组件
│   ├── api/                 # API 接口
│   └── utils/               # 工具函数
├── public/                  # 静态资源
├── .env.development         # 开发环境配置
├── .env.production          # 生产环境配置
├── vite.config.js           # Vite 配置
├── nginx.conf               # Nginx 配置（生产环境容器使用）
├── Dockerfile               # 完整构建 Dockerfile
├── Dockerfile.deploy        # 部署 Dockerfile
└── .drone.yml               # Drone CI/CD 配置
```

## 🚀 本地开发

### 环境要求

- Node.js >= 18
- npm >= 9

### 安装依赖

```bash
npm install
```

### 开发运行

```bash
npm run dev
```

访问 http://localhost:5173

### 生产构建

```bash
npm run build
```

构建产物在 `dist/` 目录

### 预览生产构建

```bash
npm run serve
```

## 🐳 Docker 部署

### 方法一：完整构建（开发/测试）

```bash
docker build -t martial/frontend:latest -f Dockerfile .
docker run -d -p 80:80 martial/frontend:latest
```

### 方法二：部署已构建产物（生产推荐）

```bash
# 先本地构建
npm run build

# 使用 Dockerfile.deploy 轻量化部署
docker build -t martial/frontend:latest -f Dockerfile.deploy .

# 运行容器
docker run -d \
  --name martial-frontend \
  --restart always \
  -p 5173:80 \
  --network martial_martial-network \
  -e TZ=Asia/Shanghai \
  martial/frontend:latest
```

## 🔄 CI/CD 自动部署

项目使用 Drone CI/CD 进行自动化部署。

### 部署流程

当推送到 `main` 分支时，自动触发：

1. **安装依赖** - `npm install`
2. **构建项目** - `npm run build`
3. **传输文件** - SCP 上传 dist、Dockerfile.deploy、nginx.conf 到服务器
4. **构建镜像** - 在服务器上执行 `docker build -f Dockerfile.deploy`
5. **部署容器** - 停止旧容器，启动新容器
6. **健康检查** - 验证服务可访问

### 查看构建状态

访问 https://martial-ci.johnsion.club

## ⚙️ 配置说明

### 环境变量

**开发环境** (`.env.development`)：
```env
VITE_APP_API=/api              # API 前缀（开发时走 Vite 代理）
```

**生产环境** (`.env.production`)：
```env
VITE_APP_API=                  # 留空（因为 BladeX 端点路径已完整）
```

### Nginx 配置

生产环境 nginx 配置（`nginx.conf`）：

```nginx
# 前端路由（Vue Router history 模式）
location / {
    try_files $uri $uri/ /index.html;
}

# API 代理到后端（通过宿主机网关地址）
location /blade-auth/ {
    proxy_pass http://172.21.0.1:8123/blade-auth/;
}

location /blade-system/ {
    proxy_pass http://172.21.0.1:8123/blade-system/;
}

location /api/ {
    proxy_pass http://172.21.0.1:8123/api/;
}
```

### Vite 配置

开发环境代理配置（`vite.config.js`）：

```js
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8123',
      changeOrigin: true
    }
  }
}
```

## 🔧 常见问题

### 问题1: "No endpoint POST /api/blade-auth/oauth/token"

**原因**: 错误配置 `VITE_APP_API` 为 `/api` 前缀，导致请求 `/api/blade-auth/oauth/token`

**解决**: 检查 `.env.production` 中 `VITE_APP_API=`（留空）

### 问题2: 容器启动报 "host not found in upstream martial-backend"

**原因**: nginx.conf 中使用 Docker 服务名 `martial-backend`，但容器无法解析

**解决**: 使用宿主机网关地址 `172.21.0.1:8123` 代替

### 问题3: 端口 80 占用

**原因**: 宿主机 Caddy 已占用 80 端口

**解决**: 前端容器使用其他端口（如 5173），由 Caddy 反向代理

## 📝 开发规范

### 代码风格

- 使用 ESLint + Prettier
- 遵循 Vue 3 组合式 API 最佳实践
- 组件命名使用PascalCase
- 文件命名使用kebab-case

### Git 提交规范

```
feat: 新功能
fix: 修复 Bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具配置
```

## 🏗️ 生产架构

### 部署拓扑

```
互联网
  ↓
Cloudflare CDN
  ↓
Caddy (80/443端口，自动 HTTPS)
  ↓
martial.johnsion.club → localhost:5173 (前端 Nginx 容器)
  ├── 静态文件 → 直接返回 Vue 应用
  └── /blade-auth, /blade-system, /api → 代理到后端 172.21.0.1:8123
```

### 网络架构

```
Docker Network: martial_martial-network (bridge)
├── martial-frontend (172.21.0.x) - 端口映射 5173:80
├── martial-mysql (172.21.0.x) - 端口映射 33066:3306
└── martial-redis (172.21.0.x) - 端口映射 63379:6379

宿主机:
├── Caddy (80/443) - 反向代理服务
├── Java 后端 (8123) - martial-master 应用
└── Drone CI/CD (8080) - 自动化部署
```

## 🔐 安全考虑

- 生产环境启用 HTTPS 证书（Caddy 自动签发）
- API 接口通过 Nginx 代理，隔离后端
- 敏感配置通过 Drone Secrets 管理
- 容器间网络隔离，仅暴露必要端口

## 📚 相关链接

- [后端仓库](https://git.waypeak.work/martial/martial-master)
- [BladeX 框架](https://bladex.cn)
- [Vue 3 文档](https://cn.vuejs.org/)
- [Element Plus](https://element-plus.org/)
- [Vite 文档](https://vitejs.dev/)

## 👥 贡献者

- **开发者**: JohnSion
- **AI 助手**: Claude Code