129 lines
2.9 KiB
Markdown
129 lines
2.9 KiB
Markdown
# 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` 说明。
|