---
url: /docs/guide/quickstart.md
---
# 快速上手（Quick Start）

> 源自仓库 `README.md`（2026-09-17 适配知识库）；最新精确状态见 [知识库首页](/index) 与根级 CLAUDE.md 变更记录。

**沐禾健康 V2 后端** — OAuth 双 token + admin MIS + RN Web
FastAPI + Python 3.12 + SQLModel + PostgreSQL 16 + Redis 7 + Celery

## 架构总览

```mermaid
graph TB
    C[客户端<br/>uniapp / 小程序 / RN Web 管理后台]
    C -->|HTTPS| GW[Nginx]
    GW --> APP[FastAPI · uvicorn<br/>24 业务模块 + admin MIS + 设备线]
    APP --> DDD

    subgraph DDD [DDD 4 层]
        I[interface 路由/Schema] --> A[application UseCase+Port]
        A --> D[domain 实体/状态机 零依赖]
        A -.端口.-> INF[infrastructure 适配器]
    end

    INF --> PG[(PostgreSQL 16)]
    INF --> RD[(Redis 7)]
    APP --> SMS[腾讯云 SMS / Mock]
    APP --> CEL[Celery Worker/Beat]

    subgraph CI [CNB cnb.cool]
        PIPE[Pipeline lint→test→制品]
        ART[Docker 制品<br/>qm-serverv2-api:latest]
        PIPE --> ART
        ART -.compose pull.-> APP
    end
```

## Quick Start（5 步）

### 1. 克隆与初始化

```bash
git clone <repo-url>
cd QM-ServerV2
cp .env.example .env
pip install uv && uv sync
```

### 2. 起本地基础设施（PG + Redis）

```bash
docker compose up -d   # qm-postgres (5432) + qm-redis (6379)
```

### 3. 跑迁移

```bash
# 生产：alembic 迁移链
uv run alembic upgrade head

# dev（快速）：临时 init_db()
V2_USE_PRISMA=1 uv run python -c "from src.app.oauth.infrastructure.persistence.db import init_db; import asyncio; asyncio.run(init_db())"
```

### 4. 启服务

```bash
# mock 模式（默认，无需 PG/Redis）
uv run python -m uvicorn main:app --port 3001

# 真库模式（PG + Redis）
V2_USE_PRISMA=1 V2_USE_REDIS=1 uv run python -m uvicorn main:app --port 3001

# Celery worker（异步任务）
uv run celery -A src.app.shared.celery_app worker --loglevel=info

# Celery beat（定时任务）
uv run celery -A src.app.shared.celery_app beat --loglevel=info
```

### 5. 验证

```bash
curl http://localhost:3001/health
# {"code":"0","msg":"ok","data":{"status":"healthy"}}
```

## 命令清单

```bash
# 测试
uv run pytest                                        # 全部测试（含覆盖率门禁 80%）
uv run pytest tests/unit/                            # 仅单测

# 工具链
uv run ruff check .                                  # lint
uv run mypy src                                      # 类型检查
uv run pre-commit run --all-files                    # 全套 git hooks

# 守卫（防 DDD 分层 + OATH-M-006 退化）
python3 scripts/check_layers.py                      # DDD 4 层守卫
python3 scripts/check_exception_handlers.py          # 顺序守卫

# admin-web 前端
cd admin-web && pnpm install && pnpm dev     # RN Web dev server

# 知识库
cd docs && pnpm install && pnpm docs:dev             # VitePress 本地预览
```

## 项目结构（顶层）

```
QM-ServerV2/
├── src/
│   ├── main.py                  # FastAPI 入口 + lifespan + ExceptionHandler
│   └── app/                     # 24 业务模块 + admin MIS + 设备线（各模块 CLAUDE.md = 模块手册）
├── tests/                       # 分层测试（unit / integration）
├── docs/                        # 本知识库（VitePress）
├── alembic/                     # 迁移链
├── scripts/                     # 守卫 / bump / 部署脚本
├── .cnb/                        # CNB Pipeline
└── docker-compose.yml           # 本地 PG + Redis
```

各模块详细手册见 [模块手册](/modules/)。

## CNB 平台（cnb.cool）

托管于 **cnb.cool/qingmu2026/qm-serverv2**，CI/CD 由 CNB Pipeline 驱动：

| 事件 | 触发 | 流程 |
|---|---|---|
| main push | 自动 | lint → test（pg/redis service）→ Docker 制品构建&推送 |
| git tag（v\*） | 自动 | release 版本制品构建&推送 |
| feat/\* push | 自动 | 仅 lint + test |

Docker 制品：`docker.cnb.cool/qingmu2026/qm-serverv2/qm-serverv2-api:latest`

**服务器部署一行命令**：

```bash
cd /srv/qm-serverv2 && docker compose pull && docker compose up -d && curl -s localhost:3001/health
```

## 贡献规范

* DDD 4 层范式（端口契约 + PickRepo + factory）
* 业务码优先（HTTP 200 + code 40101xxx/40201xxx/40301xxx/4040xxxx）
* `cz_` 函数前缀（项目命名约定）
* 测试 ≥ 80%（pyproject.toml 强制）
* Conventional Commits（feat / fix / refactor / chore / docs / test）

***

**著作人**：外星动物（常智）· WeChat iotchange · Email 14455975@qq.com
**License**：Proprietary — 沐禾健康内部使用