xiaoxia-saas/README.md

小虾 SaaS - 快速开始指南

🚀 快速启动

1. 克隆仓库

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

2. 安装依赖

# 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. 配置环境变量

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

必须配置的项：

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

4. 初始化数据库

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

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

5. 启动服务

# 开发环境
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 使用示例

注册用户

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"
  }'

登录

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

返回：

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "abc123...",
  "token_type": "bearer",
  "user_id": "...",
  "expires_in": 1800
}

创建工作空间

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"
  }'

---

🧪 运行测试

# 运行所有单元测试
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/                 # 文档

---

🔧 开发工具

代码格式化

# 安装工具
pip install black isort

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

类型检查

pip install mypy
mypy packages/ apps/

---

🐳 Docker 部署

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

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

---

📚 更多文档

• Phase 4 完成总结
• 数据库迁移指南
• API 设计文档

---

🆘 常见问题

Q: 邮件发送失败？

A: 检查 SMTP 配置，Gmail 需要使用应用专用密码。

Q: 数据库连接失败？

A: 确认 PostgreSQL 正在运行，DATABASE_URL 配置正确。

Q: JWT token 无效？

A: 检查 JWT_SECRET_KEY 是否配置，access_token 是否过期。

---

支持联系: xiaoxia@example.com