QM-ServerV2 知识库

Appearance

快速上手（Quick Start） ​

源自仓库 README.md（2026-09-17 适配知识库）；最新精确状态见 知识库首页 与根级 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

各模块详细手册见 模块手册。

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.comLicense：Proprietary — 沐禾健康内部使用