提示信息
# 同伴后端 — 新环境启动指南
> 适用场景：换电脑、新服务器、团队成员首次拉取项目
---
## 一、前置依赖
| 工具 | 版本要求 | 安装方式 |
|------|---------|---------|
| PHP | 8.4+ | `brew install php` |
| Composer | 2.x | `brew install composer` |
| PostgreSQL | 17/18 | `brew install postgresql@17` |
| Redis | 7+ | `brew install redis` |
| Node.js | 20+ | `brew install node`（admin 前端用）|
---
## 二、拉取代码
```bash
git clone git@gitee.com:ff369258/tongban_api.git
cd tongban_api
```
> 前提：本机 SSH 公钥已添加到 Gitee 账号。
> 公钥位置：`~/.ssh/id_ed25519.pub`，复制内容添加到 Gitee → 设置 → SSH 公钥。
---
## 三、后端 API 项目初始化
### 3.1 安装依赖
```bash
composer install
```
### 3.2 配置环境变量
```bash
cp .env.example .env
```
编辑 `.env`，填入以下关键配置：
```ini
# 数据库
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=tongban
DB_USERNAME=postgres
DB_PASSWORD=你的密码
# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
# JWT
JWT_SECRET=随机字符串（openssl rand -base64 32）
# OSS（阿里云）
OSS_ACCESS_KEY_ID=
OSS_ACCESS_KEY_SECRET=
OSS_BUCKET=
OSS_ENDPOINT=
# OpenIM
OPENIM_API_URL=
OPENIM_SECRET=
# 微信支付 / 支付宝 / Apple IAP（按需填写）
```
### 3.3 创建数据库
```bash
# 进入 PostgreSQL
psql -U postgres
# 创建数据库
CREATE DATABASE tongban;
\q
```
### 3.4 执行数据库 Schema
按顺序执行（**必须先跑 00_types.sql**）：
```bash
psql -U postgres -d tongban -f database/schema/00_types.sql
psql -U postgres -d tongban -f database/schema/01_users.sql
psql -U postgres -d tongban -f database/schema/02_user_devices.sql
psql -U postgres -d tongban -f database/schema/03_user_blocks.sql
psql -U postgres -d tongban -f database/schema/04_user_login_logs.sql
psql -U postgres -d tongban -f database/schema/05_user_risk_logs.sql
psql -U postgres -d tongban -f database/schema/06_user_forbidden.sql
psql -U postgres -d tongban -f database/schema/07_user_sign.sql
psql -U postgres -d tongban -f database/schema/08_user_module_cursors.sql
psql -U postgres -d tongban -f database/schema/09_user_verifications.sql
psql -U postgres -d tongban -f database/schema/10_user_cancellations.sql
psql -U postgres -d tongban -f database/schema/11_reports.sql
psql -U postgres -d tongban -f database/schema/12_signals.sql
psql -U postgres -d tongban -f database/schema/13_signal_receives.sql
psql -U postgres -d tongban -f database/schema/14_signal_replies.sql
psql -U postgres -d tongban -f database/schema/15_signal_low_quality_feedbacks.sql
psql -U postgres -d tongban -f database/schema/16_im_stranger_limit.sql
psql -U postgres -d tongban -f database/schema/17_im_daily_greet.sql
psql -U postgres -d tongban -f database/schema/18_im_day_stats.sql
psql -U postgres -d tongban -f database/schema/19_im_upload_logs.sql
psql -U postgres -d tongban -f database/schema/20_im_violation_logs.sql
psql -U postgres -d tongban -f database/schema/21_app_versions.sql
psql -U postgres -d tongban -f database/schema/22_orders.sql
psql -U postgres -d tongban -f database/schema/23_sms_logs.sql
psql -U postgres -d tongban -f database/schema/24_app_documents.sql
```
种子数据（可选）：
```bash
psql -U postgres -d tongban -f database/seed_documents.sql
```
### 3.5 启动开发服务器
```bash
php -S 0.0.0.0:8888 -t public
```
访问 `http://localhost:8888` 验证，访问 `http://localhost:8888/docs/api` 查看 API 文档。
---
## 四、Admin 后台前端初始化
```bash
cd admin
npm install
```
配置环境变量：
```bash
cp .env.example .env.local
```
编辑 `admin/.env.local`：
```ini
VITE_API_BASE=http://localhost:8888 # 后端地址
VITE_ADMIN_TOKEN=xxx # Admin Token（从后端 .env 的 ADMIN_TOKEN 复制）
```
启动开发服务器：
```bash
npm run dev # 访问 http://localhost:3000
```
---
## 五、日常开发：一键提交推送
项目根目录有 `push.sh`，直接运行即可提交并推送：
```bash
# 自动生成提交信息（列出变更文件）
./push.sh
# 自定义提交信息
./push.sh "feat: 添加新功能"
```
---
## 六、生成 API 文档
```bash
# 命令行生成
composer run-script gen-doc
# 或浏览器访问（动态刷新）
http://localhost:8888/docs/refresh
```
---
## 七、Git 仓库信息
| 项 | 值 |
|---|---|
| 仓库地址（SSH） | `git@gitee.com:ff369258/tongban_api.git` |
| 主分支 | `main` |
| 提交者 | 冯峰 / 827900566@qq.com |
---
## 八、常见问题
**Q: composer install 报错 PHP 版本不兼容**
A: 确保 PHP >= 8.4，运行 `php -v` 检查，Mac 上用 `brew link php` 切换版本。
**Q: psql 连不上数据库**
A: 先启动 PostgreSQL 服务：`brew services start postgresql@17`
**Q: Redis 连接失败**
A: 启动 Redis：`brew services start redis`
**Q: git push 要求密码**
A: 已切换为 SSH 协议，需确保 Gitee 账号已添加本机 SSH 公钥（见第二步）。