# 小虾 SaaS - 快速开始指南

## 🚀 快速启动

### 1. 克隆仓库

```bash
git clone https://gitea.your-server.com/xiaoxia/xiaoxia-saas.git
cd xiaoxia-saas
```

### 2. 安装依赖

```bash
# Python 依赖
pip install -r requirements.txt

# 或使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows
pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，填写实际配置
```

**必须配置的项：**
- `DATABASE_URL` - PostgreSQL 连接字符串
- `JWT_SECRET_KEY` - JWT 密钥（生产环境必须修改）
- `SMTP_*` - 邮件服务配置（用于发送验证邮件）

### 4. 初始化数据库

```bash
# 创建数据库
psql -U postgres -c "CREATE DATABASE xiaoxia_saas;"

# 执行迁移
psql $DATABASE_URL -f migrations/001_initial_schema.sql
```

### 5. 启动服务

```bash
# 开发环境
uvicorn apps.api.main:app --reload --host 0.0.0.0 --port 8000

# 生产环境
uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 6. 访问 API 文档

打开浏览器访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

---

## 📖 API 使用示例

### 注册用户

```bash
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123",
    "username": "myusername",
    "display_name": "My Name"
  }'
```

### 登录

```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123"
  }'
```

返回：
```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "abc123...",
  "token_type": "bearer",
  "user_id": "...",
  "expires_in": 1800
}
```

### 创建工作空间

```bash
curl -X POST http://localhost:8000/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "我的工作空间",
    "subscription_plan": "free"
  }'
```

---

## 🧪 运行测试

```bash
# 运行所有单元测试
pytest tests/unit -v

# 运行集成测试
pytest tests/integration -v

# 生成覆盖率报告
pytest --cov=packages --cov-report=html
```

---

## 📁 项目结构

```
xiaoxia-saas/
├── apps/
│   └── api/              # FastAPI 应用
│       ├── main.py       # 应用入口
│       └── app/
│           ├── api/routes/  # API 路由
│           ├── middleware/  # 中间件
│           └── dependencies.py  # 依赖注入
├── packages/
│   ├── domain/           # 领域模型
│   ├── application/      # 用例层
│   ├── ports/            # 接口定义
│   └── adapters/         # 适配器实现
├── migrations/           # 数据库迁移
├── tests/                # 测试
└── docs/                 # 文档
```

---

## 🔧 开发工具

### 代码格式化

```bash
# 安装工具
pip install black isort

# 格式化代码
black packages/ apps/ tests/
isort packages/ apps/ tests/
```

### 类型检查

```bash
pip install mypy
mypy packages/ apps/
```

---

## 🐳 Docker 部署

```bash
# 构建镜像
docker build -t xiaoxia-saas:latest .

# 运行容器
docker run -d \
  --name xiaoxia-saas \
  -p 8000:8000 \
  --env-file .env \
  xiaoxia-saas:latest
```

---

## 📚 更多文档

- [Phase 4 完成总结](docs/PHASE4-COMPLETE.md)
- [数据库迁移指南](migrations/README.md)
- [API 设计文档](docs/PHASE4-DESIGN.md)

---

## 🆘 常见问题

### Q: 邮件发送失败？
A: 检查 SMTP 配置，Gmail 需要使用应用专用密码。

### Q: 数据库连接失败？
A: 确认 PostgreSQL 正在运行，DATABASE_URL 配置正确。

### Q: JWT token 无效？
A: 检查 JWT_SECRET_KEY 是否配置，access_token 是否过期。

---

**支持联系:** xiaoxia@example.com