# 企业微信 AI 机器人助理

Monorepo：`backend/` `admin/` `deploy/` `docs/`

## 本地启动

1. **复制环境变量**
   ```bash
   cp .env.example .env
   ```
   Windows PowerShell:
   ```powershell
   Copy-Item .env.example .env
   ```

2. **一键启动**
   ```bash
   docker compose up -d
   ```

3. **访问地址**
   - 管理后台（经 nginx）：http://localhost
   - 管理后台（直连）：http://localhost:3000
   - 后端 API（经 nginx）：http://localhost/api/health
   - 后端 API（直连）：http://localhost:8000/api/health
   - PostgreSQL：localhost:5432（仅本机连接）

## 端口说明

| 服务    | 端口  | 说明           |
|---------|-------|----------------|
| nginx   | 80    | 反代，/api→backend，其余→admin |
| admin   | 3000  | Next.js        |
| backend | 8000  | FastAPI        |
| db      | 5432  | PostgreSQL     |

## 阶段 2：登录与管理员

- 启动后 backend 会自动执行 `alembic upgrade head`（创建 users、audit_logs 表）。
- 创建管理员：在项目根目录执行 `python deploy/scripts/seed.py`（依赖见 `docs/stage2.md`）。
- 后台登录：打开 http://localhost → 登录页，token 存于 **localStorage**（key: `token`），详见 `admin/lib/api.ts` 与 `docs/stage2.md`。

## 阶段 1 验证

- `GET http://localhost/api/health` 或 `GET http://localhost:8000/api/health` 返回占位 JSON
- `GET http://localhost/api/ready` 或 `GET http://localhost:8000/api/ready` 返回占位 JSON
- 浏览器打开 http://localhost 或 http://localhost:3000，可访问 /login、/dashboard 占位页

## 云端最小回调壳部署

**重要**：企业微信回调域名必须备案且主体关联，必须先完成云端最小可用部署。

### 方式一：GitHub Actions 自动部署（推荐）

#### 快速开始（使用配置文件）

1. **使用配置文件自动设置**：
   ```powershell
   # 配置文件已创建：.github-config（包含你的 GitHub 信息）
   # 自动配置 Git 远程仓库
   .\scripts\setup-github-from-config.ps1
   
   # 推送代码到 GitHub
   .\scripts\push-to-github.ps1
   ```

#### 手动设置

1. **创建 GitHub 仓库并推送代码**：
   ```powershell
   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/bujie9527/wecom-ai-assistant.git
   git push -u origin main
   ```

2. **配置 GitHub Secrets**：
   - 进入 GitHub 仓库 → Settings → Secrets and variables → Actions
   - 添加以下 Secrets：
     - `PROD_HOST`: 生产服务器 IP
     - `PROD_USER`: SSH 用户名
     - `PROD_SSH_KEY`: SSH 私钥
     - `PROD_DOMAIN`: 生产域名
     - `PROD_APP_PATH`: 应用部署路径（可选，默认 `/opt/wecom-ai-assistant`）

3. **在生产服务器上准备**：
   ```bash
   # 安装 Docker
   sudo apt-get update && sudo apt-get install -y docker.io docker-compose-plugin
   
   # 克隆项目
   sudo mkdir -p /opt/wecom-ai-assistant
   cd /opt/wecom-ai-assistant
   git clone https://github.com/YOUR_USERNAME/wecom-ai-assistant.git .
   
   # 配置环境变量
   cp .env.prod.example .env.prod
   nano .env.prod  # 填写生产环境变量
   ```

4. **触发部署**：
   - 推送代码到 `main` 分支，GitHub Actions 会自动部署
   - 或手动触发：Actions → Deploy to Production → Run workflow

**详细文档**：参见 `docs/github-setup-guide.md`

### 方式二：手动部署

1. **准备环境**：
   - 备案域名（例如：`api.yourdomain.com`）
   - Linux 服务器（Ubuntu 20.04+ / CentOS 7+）
   - Docker + docker-compose

2. **配置环境变量**：
   ```bash
   cp .env.prod.example .env.prod
   # 编辑 .env.prod，填写必需变量（WECOM_TOKEN、WECOM_ENCODING_AES_KEY 等）
   ```

3. **部署最小回调壳**：
   ```bash
   # 使用生产配置（backend + nginx）
   docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d
   ```

4. **配置 HTTPS**（Let's Encrypt）：
   ```bash
   export DOMAIN=your-domain.com
   export SSL_EMAIL=your-email@example.com
   bash deploy/scripts/setup-ssl.sh
   ```

5. **配置企业微信回调**：
   - 回调 URL：`https://your-domain.com/api/wecom/callback`
   - Token：与 `.env.prod` 中的 `WECOM_TOKEN` 一致
   - EncodingAESKey：与 `.env.prod` 中的 `WECOM_ENCODING_AES_KEY` 一致

**详细文档**：参见 `docs/deploy.md` 和 `docs/deploy-cloud-minimal.md`