init: 项目初始提交 - NeoZQYY Monorepo 完整代码

apps/backend/README.md

@@ -0,0 +1,41 @@
+# apps/backend - FastAPI 后端
+
+为微信小程序提供 RESTful API，连接 zqyy_app 业务数据库，通过 FDW 只读访问 ETL 数据。
+
+## 内部结构
+
+`
+apps/backend/
+├── app/
+│   ├── main.py          # FastAPI 入口，启用 OpenAPI 文档
+│   ├── config.py        # 配置加载
+│   ├── database.py      # zqyy_app 数据库连接
+│   ├── routers/         # 路由模块
+│   ├── middleware/       # 中间件（鉴权、日志等）
+│   └── schemas/         # Pydantic 请求/响应模型
+├── tests/               # 后端测试
+├── pyproject.toml       # 依赖声明
+└── README.md
+`
+
+## 启动
+
+`ash
+cd apps/backend
+uvicorn app.main:app --reload
+`
+
+API 文档自动生成于 http://localhost:8000/docs
+
+## 依赖
+
+- fastapi>=0.100, uvicorn>=0.23
+- psycopg2-binary>=2.9.0
+- neozqyy-shared（workspace 引用）
+
+## Roadmap
+
+- [ ] 用户管理与微信登录
+- [ ] RBAC 权限中间件
+- [ ] 任务审批流 API
+- [ ] FDW 数据查询接口（助教业绩、财务日报等）

apps/backend/app/config.py

@@ -0,0 +1,36 @@
+"""
+后端配置加载
+
+优先级（低 → 高）：根 .env → 应用 .env.local → 环境变量
+敏感值（DSN、Token）禁止提交，仅放在 .env / .env.local 中。
+"""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# 根 .env（公共配置）
+_root_env = Path(__file__).resolve().parents[3] / ".env"
+load_dotenv(_root_env, override=False)
+
+# 应用级 .env.local（私有覆盖，优先级更高）
+_local_env = Path(__file__).resolve().parents[1] / ".env.local"
+load_dotenv(_local_env, override=True)
+
+
+def get(key: str, default: str | None = None) -> str | None:
+    """从环境变量读取配置值。"""
+    return os.getenv(key, default)
+
+
+# ---- 数据库连接参数 ----
+DB_HOST: str = get("DB_HOST", "localhost")
+DB_PORT: str = get("DB_PORT", "5432")
+DB_USER: str = get("DB_USER", "")
+DB_PASSWORD: str = get("DB_PASSWORD", "")
+APP_DB_NAME: str = get("APP_DB_NAME", "zqyy_app")
+
+# ---- 通用 ----
+TIMEZONE: str = get("TIMEZONE", "Asia/Shanghai")
+LOG_LEVEL: str = get("LOG_LEVEL", "INFO")

apps/backend/app/database.py

@@ -0,0 +1,26 @@
+"""
+zqyy_app 数据库连接
+
+使用 psycopg2 直连 PostgreSQL，不引入 ORM。
+连接参数从环境变量读取（经 config 模块加载）。
+"""
+
+import psycopg2
+from psycopg2.extensions import connection as PgConnection
+
+from app.config import APP_DB_NAME, DB_HOST, DB_PASSWORD, DB_PORT, DB_USER
+
+
+def get_connection() -> PgConnection:
+    """
+    获取 zqyy_app 数据库连接。
+
+    调用方负责关闭连接（推荐配合 contextmanager 或 try/finally 使用）。
+    """
+    return psycopg2.connect(
+        host=DB_HOST,
+        port=DB_PORT,
+        user=DB_USER,
+        password=DB_PASSWORD,
+        dbname=APP_DB_NAME,
+    )

apps/backend/app/main.py

@@ -0,0 +1,22 @@
+"""
+NeoZQYY 后端 API 入口
+
+基于 FastAPI 构建，为微信小程序提供 RESTful API。
+OpenAPI 文档自动生成于 /docs（Swagger UI）和 /redoc（ReDoc）。
+"""
+
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="NeoZQYY API",
+    description="台球门店运营助手 — 微信小程序后端 API",
+    version="0.1.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+
+@app.get("/health", tags=["系统"])
+async def health_check():
+    """健康检查端点，用于探活和监控。"""
+    return {"status": "ok"}

apps/backend/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "zqyy-backend"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "neozqyy-shared",
+]
+
+[tool.uv.sources]
+neozqyy-shared = { workspace = true }