xiaoxia-saas/README.md

# 灏忚櫨 SaaS - 鑷姩鍖栧壀杈?SaaS 骞冲彴

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0-009688.svg)](https://fastapi.tiangolo.com)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791.svg)](https://www.postgresql.org/)

涓€涓姛鑳藉畬鏁淬€佺敓浜у氨缁殑澶氱鎴?SaaS 骞冲彴锛屼笓涓鸿嚜鍔ㄥ寲瑙嗛鍓緫鏈嶅姟璁捐銆?
---

## 鉁?鐗规€?
### 馃攼 瀹屾暣鐨勮璇佺郴缁?- JWT 璁よ瘉锛坅ccess + refresh token锛?- 閭楠岃瘉鍜屽瘑鐮侀噸缃?- Session 绠＄悊
- bcrypt 瀵嗙爜鍔犲瘑

### 馃彚 澶氱鎴锋灦鏋?- 宸ヤ綔绌洪棿闅旂
- 鍥㈤槦鎴愬憳绠＄悊
- 鍩轰簬瑙掕壊鐨勬潈闄愭帶鍒讹紙Owner/Admin/Member/Viewer锛?- 閭€璇峰拰瀹℃壒娴佺▼

### 馃挸 璁㈤槄绠＄悊
- 3 绾ц闃呰鍒掞紙Free/Pro/Enterprise锛?- 閰嶉绠＄悊锛堥」鐩暟/瀛樺偍绌洪棿锛?- 鍗囩骇鍜屽彇娑堣闃?
### 鈿?楂樻€ц兘
- 鏁版嵁搴撹繛鎺ユ睜锛?-6x 鎬ц兘鎻愬崌锛?- 璇锋眰鏃ュ織鍜岀洃鎺?- 鎱㈡煡璇㈡娴?- 鍋ュ悍妫€鏌ワ紙Kubernetes 灏辩华锛?
### 馃摎 瀹屾暣鏂囨。
- API 鏂囨。锛圫wagger/ReDoc锛?- 閮ㄧ讲鎸囧崡
- 鎬ц兘浼樺寲鎸囧崡
- 11+ 绡囨妧鏈枃妗?
---

## 馃殌 蹇€熷紑濮?
### 鏂瑰紡 1: Docker锛堟帹鑽愶級

```bash
# 1. 鍏嬮殕浠撳簱
git clone https://github.com/your-org/xiaoxia-saas.git
cd xiaoxia-saas

# 2. 鍚姩鎵€鏈夋湇鍔?docker-compose up -d

# 3. 璁块棶 API 鏂囨。
open http://localhost:8000/docs
```

灏辫繖涔堢畝鍗曪紒馃帀

### 鏂瑰紡 2: 鏈湴寮€鍙?
```bash
# 1. 鍏嬮殕浠撳簱
git clone https://github.com/your-org/xiaoxia-saas.git
cd xiaoxia-saas

# 2. 鍒涘缓铏氭嫙鐜
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 瀹夎渚濊禆
pip install -r requirements.txt

# 4. 浣跨敤鍐呭瓨鏁版嵁搴擄紙鏃犻渶 PostgreSQL锛?echo "USE_IN_MEMORY_DB=true" > .env

# 5. 鍚姩寮€鍙戞湇鍔″櫒
uvicorn apps.api.main:app --reload

# 6. 璁块棶 API 鏂囨。
open http://localhost:8000/docs
```

---

## 馃摉 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": "myuser",
    "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"
  }'
```

### 鍒涘缓宸ヤ綔绌洪棿

```bash
curl -X POST http://localhost:8000/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "鎴戠殑鍥㈤槦",
    "subscription_plan": "free"
  }'
```

---

## 馃彈锔?鏋舵瀯

```
灏忚櫨 SaaS
鈹溾攢鈹€ packages/              # 鏍稿績涓氬姟閫昏緫
鈹?  鈹溾攢鈹€ domain/           # 棰嗗煙妯″瀷
鈹?  鈹溾攢鈹€ application/      # 鐢ㄤ緥
鈹?  鈹溾攢鈹€ ports/            # 鎺ュ彛瀹氫箟
鈹?  鈹斺攢鈹€ adapters/         # 閫傞厤鍣ㄥ疄鐜?鈹溾攢鈹€ apps/                 # 搴旂敤灞?鈹?  鈹斺攢鈹€ api/             # FastAPI 搴旂敤
鈹溾攢鈹€ migrations/           # 鏁版嵁搴撹縼绉?鈹溾攢鈹€ tests/               # 娴嬭瘯
鈹?  鈹溾攢鈹€ unit/           # 鍗曞厓娴嬭瘯锛?70 涓級
鈹?  鈹斺攢鈹€ integration/    # 闆嗘垚娴嬭瘯锛?2 涓級
鈹斺攢鈹€ docs/                # 鏂囨。
```

**璁捐妯″紡:**
- Clean Architecture
- 渚濊禆娉ㄥ叆
- Repository 妯″紡
- Domain-Driven Design

---

## 馃敡 閰嶇疆

### 鐜鍙橀噺

```env
# 鏁版嵁搴撳垏鎹?USE_IN_MEMORY_DB=true          # 寮€鍙戠幆澧冿紙鏃犻渶 PostgreSQL锛?USE_IN_MEMORY_DB=false         # 鐢熶骇鐜锛堜娇鐢?PostgreSQL锛?
# 鏁版嵁搴撹繛鎺?DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas

# JWT 閰嶇疆
JWT_SECRET_KEY=your-secret-key-at-least-32-chars

# 閭欢閰嶇疆
SMTP_HOST=smtp.gmail.com
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
```

瀹屾暣閰嶇疆鍙傝€?`.env.example`

---

## 馃И 娴嬭瘯

```bash
# 杩愯鎵€鏈夋祴璇?pytest tests/ -v

# 杩愯鍗曞厓娴嬭瘯
pytest tests/unit -v

# 鐢熸垚瑕嗙洊鐜囨姤鍛?pytest --cov=packages --cov-report=html

# 鏌ョ湅瑕嗙洊鐜?open htmlcov/index.html
```

**娴嬭瘯缁熻:**
- 鍗曞厓娴嬭瘯: 170 涓?鉁?- 娴嬭瘯瑕嗙洊鐜? 85%+
- 闆嗘垚娴嬭瘯: 12 涓?
---

## 馃摎 鏂囨。

- [API 浣跨敤鎸囧崡](docs/API-GUIDE.md)
- [Docker 閮ㄧ讲鎸囧崡](docs/DOCKER-DEPLOYMENT.md)
- [鏁版嵁搴撳垏鎹㈡寚鍗梋(docs/DATABASE-SWITCH.md)
- [鎬ц兘鐩戞帶鎸囧崡](docs/PERFORMANCE-MONITORING.md)
- [鐜閰嶇疆鎸囧崡](docs/ENVIRONMENT-CONFIG.md)
- [鍋ュ悍妫€鏌ユ寚鍗梋(docs/HEALTH-CHECKS.md)
- [鍒嗛〉浣跨敤鎸囧崡](docs/PAGINATION.md)
- [鐢熶骇閮ㄧ讲妫€鏌ユ竻鍗昡(docs/PRODUCTION-CHECKLIST.md)
- [璐＄尞鎸囧崡](CONTRIBUTING.md)

---

## 馃殺 閮ㄧ讲

### Kubernetes

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: xiaoxia-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: xiaoxia-saas:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
```

### Docker Compose

```yaml
version: '3.8'
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://...
      - REDIS_URL=redis://...
```

鏌ョ湅 [瀹屾暣閮ㄧ讲鎸囧崡](docs/DOCKER-DEPLOYMENT.md)

---

## 馃幆 鎶€鏈爤

**鍚庣:**
- Python 3.12
- FastAPI 0.115.0
- Pydantic 2.9
- PostgreSQL 16
- Redis 7

**娴嬭瘯:**
- pytest
- pytest-asyncio
- pytest-cov

**閮ㄧ讲:**
- Docker
- Docker Compose
- Kubernetes锛堝彲閫夛級

---

## 馃搳 鎬ц兘

| 鎸囨爣 | 鏁板€?|
|------|------|
| API 骞冲潎鍝嶅簲鏃堕棿 | < 50ms |
| 鏁版嵁搴撴煡璇㈡椂闂?| < 10ms |
| 骞跺彂鏀寔 | 1000+ RPS |
| 杩炴帴姹犳€ц兘鎻愬崌 | 5-6x |
| 娴嬭瘯瑕嗙洊鐜?| 85%+ |

---

## 馃 璐＄尞

娆㈣繋璐＄尞锛佽鏌ョ湅 [璐＄尞鎸囧崡](CONTRIBUTING.md)

1. Fork 椤圭洰
2. 鍒涘缓鍒嗘敮 (`git checkout -b feature/AmazingFeature`)
3. 鎻愪氦鏇存敼 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 鎺ㄩ€佸埌鍒嗘敮 (`git push origin feature/AmazingFeature`)
5. 鍒涘缓 Pull Request

---

## 馃搫 璁稿彲璇?
鏈」鐩噰鐢?MIT 璁稿彲璇?- 鏌ョ湅 [LICENSE](LICENSE) 鏂囦欢浜嗚В璇︽儏

---

## 馃摓 鑱旂郴鏂瑰紡

- **鏂囨。:** https://docs.xiaoxia-saas.com
- **闂鍙嶉:** GitHub Issues
- **閭:** support@xiaoxia-saas.com

---

## 馃帀 鑷磋阿

鎰熻阿鎵€鏈夎础鐚€呭拰浣跨敤鑰咃紒

**寮€鍙戝洟闃?** 灏忚櫨 馃

---

**猸?濡傛灉杩欎釜椤圭洰瀵逛綘鏈夊府鍔╋紝璇风粰涓€涓?Star锛?*


<!-- CI Test -->

<!-- CI Test: 2026-06-18 16:11:49 -->

<!-- CI Final Test: 2026-06-18 16:15:58 -->

<!-- CI Container Test: 2026-06-18 16:22:22 -->

<!-- CI Fresh Start: 2026-06-18 16:28:15 -->