# Company Celebration 项目指南

## 项目概述

年会庆典系统，包含投票、抽奖、大屏展示等功能。

## 技术栈

- **前端**: Vue 3 + TypeScript + Vite
- **后端**: Node.js + Express + Socket.IO
- **数据库**: MySQL + Redis
- **部署**: PM2

## 项目结构

```
packages/
├── client-mobile/   # 移动端（投票、扫码登录）
├── client-screen/   # 大屏端（展示、管理控制台）
├── server/          # 后端服务
└── shared/          # 共享类型和常量
```

---

## 运维部署流程

### 服务器信息

- **SSH 别名**: `vote`
- **项目目录**: `/root/company-celebration`
- **进程管理**: PM2 (`gala-server`)

### 标准部署流程

```bash
# 1. 本地提交并推送
git add <files>
git commit -m "commit message"
git push origin main

# 2. SSH 到服务器拉取代码
ssh vote "cd /root/company-celebration && git pull"

# 3. 构建项目
ssh vote "cd /root/company-celebration && pnpm build"

# 4. 重启服务
ssh vote "pm2 restart all && pm2 status"
```

### 常见问题处理

#### 服务器有本地修改冲突

```bash
ssh vote "cd /root/company-celebration && git stash && git pull"
```

#### 构建失败

1. 检查 TypeScript 类型错误
2. 本地修复后重新提交推送
3. 服务器重新拉取构建

#### 查看服务状态

```bash
ssh vote "pm2 status"
ssh vote "pm2 logs gala-server --lines 50"
```

### 环境变量配置

#### 服务端 `.env`

```bash
# 必需配置
NODE_ENV=production
DATABASE_URL=mysql://user:pass@localhost:3306/gala
REDIS_HOST=localhost
JWT_SECRET=your-secret-key
ADMIN_ACCESS_CODE=your-admin-code
MOBILE_CLIENT_URL=https://your-domain.com

# 微信公众号（扫码登录）
WECHAT_MP_APP_ID=your-mp-app-id
WECHAT_MP_APP_SECRET=your-mp-app-secret
WECHAT_MP_REDIRECT_ALLOWLIST=your-domain.com
```

#### 移动端 `packages/client-mobile/.env.production`

```bash
# 必须配置正确的生产环境地址，否则 API 调用会失败
VITE_SOCKET_URL=https://your-domain.com
VITE_API_URL=https://your-domain.com
```

> **注意**：如果 `VITE_API_URL` 为空，会使用默认的本地开发地址 `http://192.168.1.5:3000`，导致生产环境无法访问 API。

---

## 开发规范

### 类型定义

- 共享类型定义在 `packages/shared/src/types/`
- 修改类型后需确保所有引用处同步更新

### 提交规范

使用 Conventional Commits:
- `feat`: 新功能
- `fix`: 修复
- `chore`: 杂项
- `refactor`: 重构

---

## 关键变更记录

### 2026-02-03

- 公众号 OAuth 安全加固：`/api/mp/auth-url` 生成并缓存 state，`/api/mp/login` 强制校验 state。
- 增加回调域名白名单：新增 `WECHAT_MP_REDIRECT_ALLOWLIST`，仅允许白名单 host 的 `redirect_uri`。
- 移动端授权回调携带 state：微信回调时将 `state` 与 `code` 一起提交登录。
- 补充部署与生产环境变量示例：新增 `WECHAT_MP_APP_ID/SECRET/REDIRECT_ALLOWLIST` 说明。