feat: 正式 App 后端登录模块 v0.1.0

引入 JWT 认证、极光一键登录、短信 mock 登录与用户表，并补充技术实施文档与部署配置。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-23 17:37:18 +08:00
parent 3e37e4ac85
commit 1aafc28621
38 changed files with 1863 additions and 1 deletions
@@ -0,0 +1,39 @@
 # ===== 环境 =====
 # dev / prod。dev 模式下若 JG_PRIVATE_KEY_PATH 指向的文件不存在,jverify-login 接口会拒绝调用
 # (而不是 import 时炸进程),并提示用 mock 模式跑通其他链路。
 APP_ENV=dev
 APP_NAME=shaguabijia-app-server
 APP_DEBUG=true
 # ===== 数据库 =====
 # SQLite 本地文件路径。生产环境用 /opt/shaguabijia-app-server/data.db
 DATABASE_URL=sqlite:///./data/app.db
 # ===== JWT =====
 # 生产部署务必改成随机长字符串,可用:python -c "import secrets; print(secrets.token_urlsafe(64))"
 JWT_SECRET_KEY=change-me-in-prod-please-use-a-long-random-string
 JWT_ALGORITHM=HS256
 # access token 有效期(分钟),默认 2 小时
 JWT_ACCESS_TOKEN_EXPIRE_MINUTES=120
 # refresh token 有效期(天),默认 30 天
 JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
 # ===== 极光一键登录 =====
 # 控制台 → 应用设置 → 应用信息 拿到
 JG_APP_KEY=966b451a8d9cfe12d173ea9d
 JG_MASTER_SECRET=dae6d856c7556ac1b8f2deda
 # RSA 私钥路径(本地开发可指到项目里的 secrets/jverify_rsa_private.pem,生产用 /opt 下绝对路径)
 JG_PRIVATE_KEY_PATH=./secrets/jverify_rsa_private.pem
 JG_VERIFY_ENDPOINT=https://api.verification.jpush.cn/v1/web/loginTokenVerify
 JG_REQUEST_TIMEOUT_SEC=15
 # ===== 短信 (mock 模式) =====
 # mock = true 时,任意 6 位数字均通过,且 /sms/send 不真发短信(只 log)。
 # 后续接阿里云/腾讯云短信时,改成 false 并填供应商相关 key。
 SMS_MOCK=true
 SMS_CODE_TTL_SEC=300
 SMS_SEND_INTERVAL_SEC=60
 # ===== CORS =====
 # 逗号分隔,生产留空(只让 app 调,不开放 web)。本地开发可加 http://localhost:5173 之类
 CORS_ALLOW_ORIGINS=
@@ -0,0 +1,36 @@
 __pycache__/
 *.py[cod]
 *$py.class
 .venv/
 venv/
 env/
 *.egg-info/
 build/
 dist/
 .eggs/
 .pytest_cache/
 .ruff_cache/
 .mypy_cache/
 .env
 .env.*
 !.env.example
 *.db
 *.db-journal
 *.db-shm
 *.db-wal
 data/
 secrets/*
 !secrets/.gitkeep
 *.pem
 *.key
 .DS_Store
 .idea/
 .vscode/
 *.swp
@@ -1,3 +1,216 @@
 # shaguabijia-app-server
-傻瓜比价正式 app后端 
+傻瓜比价正式 App 后端 — FastAPI + SQLAlchemy + JWT。
 > 占坑期已有的试验后台 `shaguabijia-server` 是无状态 mock,本项目是正式版,
 > 引入账号体系、JWT 登录态、Alembic 迁移、SQLite 起步可平滑切 PostgreSQL。
 详细技术说明见 [docs/后端技术实现.md](docs/后端技术实现.md)(登录链路、极光 RSA、部署 checklist)。
 ---
 ## 技术栈
 | 维度 | 选型 | 说明 |
 |---|---|---|
 | 语言 | Python 3.11+ | |
 | Web | FastAPI 0.115+ | |
 | ASGI | uvicorn[standard] | |
 | ORM | SQLAlchemy 2.0 | Mapped/DeclarativeBase 新风格 |
 | 迁移 | Alembic | render_as_batch 兼容 SQLite |
 | DB | SQLite | 后续切 PostgreSQL 只改 `DATABASE_URL` |
 | Auth | JWT (PyJWT) | access(2h) + refresh(30d) |
 | 极光一键登录 | httpx + cryptography | RSA 解密,逻辑参考试验后台 |
 | 配置 | pydantic-settings | `.env` 加载 |
 | 测试 | pytest + TestClient | |
 ---
 ## 目录结构
 ```
 shaguabijia-app-server/
 ├── app/
 │   ├── main.py                FastAPI 入口 + /health + CORS
 │   ├── core/
 │   │   ├── config.py          Settings (pydantic-settings)
 │   │   ├── logging.py         统一日志配置
 │   │   ├── security.py        JWT 签发 / 校验 / token 对
 │   │   ├── jiguang.py         极光 REST 调用 + RSA 解密
 │   │   └── sms.py             短信验证码 (mock 实现)
 │   ├── db/
 │   │   ├── base.py            DeclarativeBase
 │   │   └── session.py         engine + SessionLocal + get_db
 │   ├── models/
 │   │   └── user.py            User 表
 │   ├── schemas/
 │   │   └── auth.py            登录/Token 相关 Pydantic
 │   ├── crud/
 │   │   └── user.py            upsert_user_for_login 等
 │   └── api/
 │       ├── deps.py            get_current_user (Bearer 校验)
 │       └── v1/
 │           └── auth.py        /api/v1/auth/* 路由
 │
 ├── alembic/                   迁移脚本
 │   ├── env.py
 │   ├── script.py.mako
 │   └── versions/              (空,第一次跑 alembic revision 生成)
 ├── alembic.ini
 │
 ├── deploy/
 │   ├── shaguabijia-app-server.service   systemd unit
 │   └── nginx/
 │       └── app-api.shaguabijia.com.conf
 │
 ├── secrets/                   不入 git。放 jverify_rsa_private.pem
 ├── data/                      不入 git。SQLite 文件默认在这里
 ├── tests/                     冒烟 + auth 流程
 │
 ├── pyproject.toml
 ├── .env.example
 └── README.md
 ```
 ---
 ## API 接口
 | 方法 | 路径 | 说明 | 鉴权 |
 |---|---|---|---|
 | GET  | `/health` | 健康检查 | 无 |
 | POST | `/api/v1/auth/jverify-login` | 极光一键登录(`loginToken` → 注册即登录 → 签发 token 对) | 无 |
 | POST | `/api/v1/auth/sms/send` | 发短信验证码(mock 阶段任意 6 位通过) | 无 |
 | POST | `/api/v1/auth/sms/login` | 手机号+验证码登录 | 无 |
 | POST | `/api/v1/auth/refresh` | 用 `refresh_token` 换新的 token 对 | 无 |
 | GET  | `/api/v1/auth/me` | 获取当前登录用户 | `Bearer access_token` |
 | POST | `/api/v1/auth/logout` | 登出(占位,客户端清 token) | `Bearer access_token` |
 登录类接口的响应统一格式:
 ```json
 {
  "access_token": "eyJxxx...",
  "refresh_token": "eyJxxx...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_expires_in": 2592000,
  "user": {
    "id": 1,
    "phone": "13800138000",
    "nickname": null,
    "avatar_url": null,
    "register_channel": "jverify",
    "status": "active",
    "created_at": "2026-05-23T04:30:00Z",
    "last_login_at": "2026-05-23T04:30:00Z"
  }
 }
 ```
 文档启动后看 `http://localhost:8770/docs` (Swagger UI)。
 ---
 ## 本地开发
 ### 1. 装依赖
 ```bash
 cd shaguabijia-app-server
 python3.11 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 ```
 ### 2. 准备配置
 ```bash
 cp .env.example .env
 # 编辑 .env,生产部署务必改 JWT_SECRET_KEY
 ```
 如果要测极光一键登录,把 RSA 私钥放到 `./secrets/jverify_rsa_private.pem`。
 没放也不影响其他接口(`sms`/`/health` 等),只是 `jverify-login` 会 502。
 ### 3. 建表(首次)
 ```bash
 # 生成首版 migration(已有 User model,会自动生成 create_table)
 alembic revision --autogenerate -m "init user table"
 # 应用 migration
 alembic upgrade head
 ```
 后续改 model 后:
 ```bash
 alembic revision --autogenerate -m "add nickname index"
 alembic upgrade head
 ```
 ### 4. 跑起来
 ```bash
 uvicorn app.main:app --reload --port 8770
 ```
 冒烟:
 ```bash
 curl http://localhost:8770/health
 # {"status":"ok"}
 # mock 走通登录闭环
 curl -X POST http://localhost:8770/api/v1/auth/sms/send -H 'Content-Type: application/json' -d '{"phone":"13800138000"}'
 curl -X POST http://localhost:8770/api/v1/auth/sms/login -H 'Content-Type: application/json' -d '{"phone":"13800138000","code":"123456"}'
 # 拿到 access_token 后:
 curl http://localhost:8770/api/v1/auth/me -H "Authorization: Bearer <access_token>"
 ```
 ### 5. 测试
 ```bash
 pytest -q
 ```
 ---
 ## 部署(生产)
 参考 `deploy/`,部署到 `app-api.shaguabijia.com`:
 ```bash
 # 一次性
 ssh server "apt-get install -y python3.11-venv python3-pip"
 # 后续更新
 rsync -avz --exclude='__pycache__' --exclude='.venv' --exclude='data' --exclude='secrets/jverify_rsa_private.pem' \
    ./ server:/opt/shaguabijia-app-server/
 # 私钥单独同步(只首次 / 私钥更换时)
 scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/
 ssh server "
    cd /opt/shaguabijia-app-server &&
    .venv/bin/pip install --quiet -e . &&
    .venv/bin/alembic upgrade head &&
    systemctl restart shaguabijia-app-server
 "
 ```
 详见 `deploy/shaguabijia-app-server.service` 和 `deploy/nginx/app-api.shaguabijia.com.conf`。
 ---
 ## 与试验后台的差异(为什么不直接复用 shaguabijia-server)
 | 维度 | 试验后台 (shaguabijia-server) | 本项目 (shaguabijia-app-server) |
 |---|---|---|
 | 数据库 | stdlib sqlite3,无 ORM | SQLAlchemy 2.0 + Alembic |
 | 业务 | mock parse(无账号体系) | 完整账号体系 + JWT |
 | 登录态 | 无,客户端发 phone 当 ID | JWT access+refresh |
 | 配置 | 硬编码 | pydantic-settings + `.env` |
 | 短信登录 | 无 | 有(mock 实现,留扩展点) |
 | 域名 | api.shaguabijia.com (试验) | app-api.shaguabijia.com (正式) |
 极光一键登录的具体实现(REST 调用、RSA padding 试错顺序)直接参考自试验后台,
 逻辑等价。
@@ -0,0 +1,40 @@
 [alembic]
 script_location = alembic
 prepend_sys_path = .
 sqlalchemy.url =
 [post_write_hooks]
 [loggers]
 keys = root,sqlalchemy,alembic
 [handlers]
 keys = console
 [formatters]
 keys = generic
 [logger_root]
 level = WARN
 handlers = console
 qualname =
 [logger_sqlalchemy]
 level = WARN
 handlers =
 qualname = sqlalchemy.engine
 [logger_alembic]
 level = INFO
 handlers =
 qualname = alembic
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
 level = NOTSET
 formatter = generic
 [formatter_generic]
 format = %(levelname)-5.5s [%(name)s] %(message)s
 datefmt = %H:%M:%S
@@ -0,0 +1,66 @@
 """Alembic 环境。
 跟标准模板的差别:
  - 从 app.core.config.settings 读 DATABASE_URL,不再走 alembic.ini 的 sqlalchemy.url
  - import app.db.base 让 Base.metadata 包含所有 model 表(model 文件首次导入时注册到 metadata)
 """
 from __future__ import annotations
 from logging.config import fileConfig
 from alembic import context
 from sqlalchemy import engine_from_config, pool
 from app.core.config import settings
 from app.db.base import Base  # noqa: F401  (触发 model 注册)
 config = context.config
 if config.config_file_name is not None:
    fileConfig(config.config_file_name)
 # 让 alembic 用我们的 DATABASE_URL,不是 alembic.ini 里的(空)
 config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
 target_metadata = Base.metadata
 def run_migrations_offline() -> None:
    """生成 SQL 但不连库。一般用于 review。"""
    context.configure(
        url=settings.DATABASE_URL,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
        render_as_batch=settings.DATABASE_URL.startswith("sqlite"),
    )
    with context.begin_transaction():
        context.run_migrations()
 def run_migrations_online() -> None:
    """常规模式:连库执行 migration。
    render_as_batch=True 让 SQLite 也能做 ALTER COLUMN(SQLite 原生不支持,
    Alembic 用"重建表"的方式模拟)。
    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )
    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            render_as_batch=settings.DATABASE_URL.startswith("sqlite"),
        )
        with context.begin_transaction():
            context.run_migrations()
 if context.is_offline_mode():
    run_migrations_offline()
 else:
    run_migrations_online()
@@ -0,0 +1,26 @@
 """${message}
 Revision ID: ${up_revision}
 Revises: ${down_revision | comma,n}
 Create Date: ${create_date}
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 ${imports if imports else ""}
 # revision identifiers, used by Alembic.
 revision: str = ${repr(up_revision)}
 down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
 branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
 depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
 def upgrade() -> None:
    ${upgrades if upgrades else "pass"}
 def downgrade() -> None:
    ${downgrades if downgrades else "pass"}
@@ -0,0 +1,46 @@
 """init user table
 Revision ID: 9c559acc164a
 Revises: 
 Create Date: 2026-05-23 13:56:26.790399
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 # revision identifiers, used by Alembic.
 revision: str = '9c559acc164a'
 down_revision: Union[str, Sequence[str], None] = None
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('user',
    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
    sa.Column('phone', sa.String(length=20), nullable=False),
    sa.Column('register_channel', sa.String(length=20), nullable=False),
    sa.Column('nickname', sa.String(length=64), nullable=True),
    sa.Column('avatar_url', sa.String(length=512), nullable=True),
    sa.Column('status', sa.String(length=20), nullable=False),
    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
    sa.Column('last_login_at', sa.DateTime(timezone=True), nullable=False),
    sa.PrimaryKeyConstraint('id')
    )
    with op.batch_alter_table('user', schema=None) as batch_op:
        batch_op.create_index(batch_op.f('ix_user_phone'), ['phone'], unique=True)
    # ### end Alembic commands ###
 def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    with op.batch_alter_table('user', schema=None) as batch_op:
        batch_op.drop_index(batch_op.f('ix_user_phone'))
    op.drop_table('user')
    # ### end Alembic commands ###
@@ -0,0 +1,58 @@
 """API 层共享依赖:DB session、当前登录用户。"""
 from __future__ import annotations
 import logging
 from typing import Annotated
 from fastapi import Depends, HTTPException, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy.orm import Session
 from app.core.security import TokenError, decode_token
 from app.db.session import get_db
 from app.models.user import User
 logger = logging.getLogger("shagua.deps")
 # auto_error=True → 没传 Authorization header 时直接 403。但我们想 401,
 # 所以手动 auto_error=False + raise HTTPException
 _bearer = HTTPBearer(auto_error=False, scheme_name="Bearer")
 def get_current_user(
    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)],
    db: Annotated[Session, Depends(get_db)],
 ) -> User:
    """从 Authorization: Bearer <access_token> 解出当前 user。
    失败时统一 401,WWW-Authenticate 头让客户端知道要重新登录。
    """
    if credentials is None or credentials.scheme.lower() != "bearer":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="missing bearer token",
            headers={"WWW-Authenticate": "Bearer"},
        )
    try:
        payload = decode_token(credentials.credentials, expected_type="access")
    except TokenError as e:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail=str(e),
            headers={"WWW-Authenticate": "Bearer"},
        ) from e
    user_id = int(payload["sub"])
    user = db.get(User, user_id)
    if user is None or user.status != "active":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="user not found or disabled",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return user
 CurrentUser = Annotated[User, Depends(get_current_user)]
 DbSession = Annotated[Session, Depends(get_db)]
@@ -0,0 +1,130 @@
 """认证相关 endpoint。
 路由前缀 `/api/v1/auth`,包含:
  POST /jverify-login         极光一键登录(loginToken → 手机号 → 注册即登录 → 签 JWT)
  POST /sms/send              发短信验证码(mock 阶段任意 6 位通过)
  POST /sms/login             手机号 + 验证码登录
  POST /refresh               用 refresh_token 换新的 token 对
  GET  /me                    当前登录用户(Bearer access_token)
  POST /logout                客户端登出(目前服务端无状态,仅返回 ok。后续加 jti 黑名单)
 """
 from __future__ import annotations
 import logging
 from fastapi import APIRouter, HTTPException, status
 from app.api.deps import CurrentUser, DbSession
 from app.core.jiguang import JiguangError, mask_phone, verify_and_get_phone
 from app.core.security import TokenError, decode_token, issue_token_pair
 from app.core.sms import SmsError, send_code, verify_code
 from app.crud import user as crud_user
 from app.schemas.auth import (
    JverifyLoginRequest,
    LogoutResponse,
    RefreshRequest,
    SmsLoginRequest,
    SmsSendRequest,
    SmsSendResponse,
    TokenPair,
    TokenWithUser,
    UserOut,
 )
 logger = logging.getLogger("shagua.auth")
 router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 def _login_response(db, user) -> TokenWithUser:
    """登录类接口共用的响应组装。"""
    tokens = issue_token_pair(user.id)
    return TokenWithUser(
        **tokens,
        user=UserOut.model_validate(user),
    )
 # ===================== 极光一键登录 =====================
@router.post("/jverify-login", response_model=TokenWithUser, summary="极光一键登录")
 def jverify_login(req: JverifyLoginRequest, db: DbSession) -> TokenWithUser:
    logger.info(
        "jverify_login operator=%s token_len=%d",
        req.operator or "-",
        len(req.login_token),
    )
    try:
        phone = verify_and_get_phone(req.login_token)
    except JiguangError as e:
        logger.error("[JG] verify+decrypt failed: %s", e, exc_info=True)
        raise HTTPException(status_code=502, detail=f"jiguang verify failed: {e}") from e
    user = crud_user.upsert_user_for_login(db, phone=phone, register_channel="jverify")
    if user.status != "active":
        raise HTTPException(status_code=403, detail="account disabled")
    logger.info("jverify_login ok user_id=%d phone=%s", user.id, mask_phone(phone))
    return _login_response(db, user)
 # ===================== 短信登录 =====================
@router.post("/sms/send", response_model=SmsSendResponse, summary="发送短信验证码 (mock)")
 def sms_send(req: SmsSendRequest) -> SmsSendResponse:
    try:
        cooldown = send_code(req.phone)
    except SmsError as e:
        raise HTTPException(status_code=429, detail=str(e)) from e
    from app.core.config import settings  # 局部 import 避免循环
    return SmsSendResponse(sent=True, mock=settings.SMS_MOCK, cooldown_sec=cooldown)
@router.post("/sms/login", response_model=TokenWithUser, summary="手机号+验证码登录")
 def sms_login(req: SmsLoginRequest, db: DbSession) -> TokenWithUser:
    if not verify_code(req.phone, req.code):
        raise HTTPException(status_code=400, detail="invalid sms code")
    user = crud_user.upsert_user_for_login(db, phone=req.phone, register_channel="sms")
    if user.status != "active":
        raise HTTPException(status_code=403, detail="account disabled")
    logger.info("sms_login ok user_id=%d phone=%s", user.id, mask_phone(req.phone))
    return _login_response(db, user)
 # ===================== Refresh =====================
@router.post("/refresh", response_model=TokenPair, summary="用 refresh_token 换新 token 对")
 def refresh(req: RefreshRequest, db: DbSession) -> TokenPair:
    try:
        payload = decode_token(req.refresh_token, expected_type="refresh")
    except TokenError as e:
        raise HTTPException(status_code=401, detail=str(e)) from e
    user_id = int(payload["sub"])
    user = crud_user.get_user_by_id(db, user_id)
    if user is None or user.status != "active":
        raise HTTPException(status_code=401, detail="user not found or disabled")
    return TokenPair(**issue_token_pair(user.id))
 # ===================== 当前用户 =====================
@router.get("/me", response_model=UserOut, summary="获取当前登录用户")
 def me(user: CurrentUser) -> UserOut:
    return UserOut.model_validate(user)
 # ===================== Logout =====================
@router.post("/logout", response_model=LogoutResponse, summary="登出(占位,客户端清 token)")
 def logout(user: CurrentUser) -> LogoutResponse:
    # 当前服务端无状态,真正的 token 失效靠客户端删 token。
    # TODO: 加 jti 黑名单表后,这里把 access_token 的 jti 写黑名单
    logger.info("logout user_id=%d", user.id)
    return LogoutResponse(ok=True)
@@ -0,0 +1,68 @@
 """全局配置。
 用 pydantic-settings 从环境变量 + .env 文件加载。所有可调参数集中在这里,
 业务代码通过 `from app.core.config import settings` 引用,不再读 os.environ。
 """
 from __future__ import annotations
 from functools import lru_cache
 from typing import Literal
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
        extra="ignore",
    )
    # ===== 环境 =====
    APP_ENV: Literal["dev", "prod"] = "dev"
    APP_NAME: str = "shaguabijia-app-server"
    APP_DEBUG: bool = True
    # ===== 数据库 =====
    DATABASE_URL: str = "sqlite:///./data/app.db"
    # ===== JWT =====
    JWT_SECRET_KEY: str = "change-me"
    JWT_ALGORITHM: str = "HS256"
    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 120
    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
    # ===== 极光 =====
    JG_APP_KEY: str = ""
    JG_MASTER_SECRET: str = ""
    JG_PRIVATE_KEY_PATH: str = "./secrets/jverify_rsa_private.pem"
    JG_VERIFY_ENDPOINT: str = "https://api.verification.jpush.cn/v1/web/loginTokenVerify"
    JG_REQUEST_TIMEOUT_SEC: int = 15
    # ===== 短信 =====
    SMS_MOCK: bool = True
    SMS_CODE_TTL_SEC: int = 300
    SMS_SEND_INTERVAL_SEC: int = 60
    # ===== CORS =====
    CORS_ALLOW_ORIGINS: str = ""
    @property
    def cors_origins_list(self) -> list[str]:
        if not self.CORS_ALLOW_ORIGINS.strip():
            return []
        return [o.strip() for o in self.CORS_ALLOW_ORIGINS.split(",") if o.strip()]
    @property
    def is_prod(self) -> bool:
        return self.APP_ENV == "prod"
@lru_cache(maxsize=1)
 def get_settings() -> Settings:
    return Settings()
 settings = get_settings()
@@ -0,0 +1,163 @@
 """极光一键登录服务端核验 + RSA 解密手机号。
 链路:
  Android SDK loginAuth → loginToken
  → 本服务 POST 极光 /v1/web/loginTokenVerify (Basic Auth = AppKey:MasterSecret)
  → 极光返回 RSA 公钥加密的手机号 (base64)
  → 用配套 RSA 私钥解密
  → 返回明文手机号
 参考实现:试验后台 shaguabijia-server/app/api/auth.py。
 """
 from __future__ import annotations
 import base64
 import logging
 from pathlib import Path
 import httpx
 from cryptography.hazmat.primitives import hashes, serialization
 from cryptography.hazmat.primitives.asymmetric import padding
 from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
 from app.core.config import settings
 logger = logging.getLogger("shagua.jg")
 class JiguangError(Exception):
    """极光接口 / 解密失败的统一异常,api 层 catch 后翻成 4xx/5xx。"""
 _private_key_cache: RSAPrivateKey | None = None
 def _load_private_key() -> RSAPrivateKey:
    """懒加载 RSA 私钥并缓存。首次调用时如果文件不存在抛 JiguangError,
    让单个请求失败 + 日志,而不是 import 时炸进程。"""
    global _private_key_cache
    if _private_key_cache is not None:
        return _private_key_cache
    path = Path(settings.JG_PRIVATE_KEY_PATH)
    if not path.is_file():
        raise JiguangError(
            f"RSA private key not found at {path}. "
            f"Set JG_PRIVATE_KEY_PATH or place the .pem file there."
        )
    key = serialization.load_pem_private_key(path.read_bytes(), password=None)
    if not isinstance(key, RSAPrivateKey):
        raise JiguangError("loaded key is not an RSA private key")
    _private_key_cache = key
    return key
 def _verify_login_token(login_token: str) -> str:
    """调极光 REST,返回 RSA 加密后的 base64 手机号字符串。"""
    if not settings.JG_APP_KEY or not settings.JG_MASTER_SECRET:
        raise JiguangError("JG_APP_KEY / JG_MASTER_SECRET not configured")
    auth_b64 = base64.b64encode(
        f"{settings.JG_APP_KEY}:{settings.JG_MASTER_SECRET}".encode()
    ).decode()
    try:
        resp = httpx.post(
            settings.JG_VERIFY_ENDPOINT,
            json={"loginToken": login_token, "exID": ""},
            headers={
                "Content-Type": "application/json",
                "Authorization": f"Basic {auth_b64}",
            },
            timeout=settings.JG_REQUEST_TIMEOUT_SEC,
        )
    except httpx.HTTPError as e:
        logger.exception("[JG] http error calling %s", settings.JG_VERIFY_ENDPOINT)
        raise JiguangError(f"jg http error: {e}") from e
    if resp.status_code != 200:
        body = resp.text[:500]
        logger.error("[JG] HTTP %s body=%s", resp.status_code, body)
        raise JiguangError(f"jg http {resp.status_code}")
    data = resp.json()
    code = data.get("code")
    if code != 8000:
        logger.error("[JG] verify failed code=%s content=%s", code, data.get("content"))
        raise JiguangError(f"jg verify failed code={code}")
    encrypted = data.get("phone") or ""
    if not encrypted:
        logger.error("[JG] response missing phone field: %s", data)
        raise JiguangError("jg response missing phone")
    return encrypted
 def _decrypt_phone(encrypted_b64: str) -> str:
    """RSA 解密 base64 密文。
    极光文档没明说 padding。实测 PKCS1v15 在 OAEP 密文上会"假成功"返回垃圾
    (UnicodeDecodeError 0x8e),因此按 OAEP-SHA1 → OAEP-SHA256 → PKCS1v15 顺序
    尝试,谁能解出 11 位纯数字手机号就用谁。
    base64 padding 兼容:JG 各运营商可能返回不带 `=` 的 base64,先按 4 字节对齐补齐。
    """
    private_key = _load_private_key()
    padded_b64 = encrypted_b64 + "=" * (-len(encrypted_b64) % 4)
    ciphertext = base64.b64decode(padded_b64)
    paddings = [
        ("OAEP-SHA1", padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA1()),
            algorithm=hashes.SHA1(),
            label=None,
        )),
        ("OAEP-SHA256", padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA256()),
            algorithm=hashes.SHA256(),
            label=None,
        )),
        ("PKCS1v15", padding.PKCS1v15()),
    ]
    last_err: Exception | None = None
    for name, pad in paddings:
        try:
            pt = private_key.decrypt(ciphertext, pad)
        except Exception as e:
            last_err = e
            logger.debug("[JG] decrypt padding=%s failed: %s", name, e)
            continue
        try:
            phone = pt.decode("utf-8")
        except UnicodeDecodeError:
            # PKCS1v15 在错误密文上会"假成功"返回垃圾;跳到下一种 padding
            logger.debug(
                "[JG] decrypt padding=%s yielded non-UTF8 bytes head=%s",
                name, pt[:4].hex(),
            )
            continue
        if phone.isdigit() and len(phone) == 11:
            logger.info("[JG] decrypted with padding=%s", name)
            return phone
        if phone.isascii() and phone.isprintable():
            logger.warning(
                "[JG] decrypted with padding=%s, non-standard format: %r", name, phone,
            )
            return phone
        logger.debug("[JG] decrypt padding=%s yielded non-phone string: %r", name, phone[:20])
    raise JiguangError(f"all RSA paddings failed; last error: {last_err}")
 def verify_and_get_phone(login_token: str) -> str:
    """对外暴露的唯一函数:loginToken → 明文手机号。失败抛 JiguangError。"""
    encrypted = _verify_login_token(login_token)
    return _decrypt_phone(encrypted)
 def mask_phone(phone: str) -> str:
    """日志用,不打明文。"""
    if len(phone) < 5:
        return "***"
    return phone[:3] + "****" + phone[-2:]
@@ -0,0 +1,20 @@
 """统一日志配置。
 业务代码用 `logger = logging.getLogger("shagua.xxx")` 即可,本模块在 main.py 启动时调一次。
 """
 from __future__ import annotations
 import logging
 import sys
 def setup_logging(debug: bool = False) -> None:
    level = logging.DEBUG if debug else logging.INFO
    logging.basicConfig(
        level=level,
        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
        stream=sys.stdout,
    )
    # 第三方库降噪
    logging.getLogger("httpx").setLevel(logging.WARNING)
    logging.getLogger("httpcore").setLevel(logging.WARNING)
@@ -0,0 +1,86 @@
 """JWT 签发与校验。
 设计:
  - access_token : 短期(默认 2 小时),每个业务请求 Bearer 携带
  - refresh_token: 长期(默认 30 天),过期时 POST /refresh 换新的 access
 两者结构一致(都是 JWT),靠 payload 里的 `typ` 字段区分,防止用 refresh 当 access 用。
 为什么不用 OAuth2 + session 表?
  - 占坑 + 早期阶段,JWT 自包含、零状态,够用
  - 后续需要"主动作废"(改密码/账号被盗)时再加 jti 黑名单表
 """
 from __future__ import annotations
 from datetime import datetime, timedelta, timezone
 from typing import Any, Literal
 import jwt
 from app.core.config import settings
 TokenType = Literal["access", "refresh"]
 class TokenError(Exception):
    """token 解析/校验失败时统一抛这个,api 层捕获后返回 401。"""
 def _now() -> datetime:
    return datetime.now(timezone.utc)
 def create_token(*, user_id: int, token_type: TokenType) -> tuple[str, datetime]:
    """签发 token,返回 (token_string, expires_at_utc)。"""
    now = _now()
    if token_type == "access":
        expire = now + timedelta(minutes=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES)
    else:
        expire = now + timedelta(days=settings.JWT_REFRESH_TOKEN_EXPIRE_DAYS)
    payload: dict[str, Any] = {
        "sub": str(user_id),
        "typ": token_type,
        "iat": int(now.timestamp()),
        "exp": int(expire.timestamp()),
    }
    token = jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
    return token, expire
 def decode_token(token: str, *, expected_type: TokenType | None = None) -> dict[str, Any]:
    """解析并校验 token。
    - 签名错/过期 → TokenError
    - expected_type 不匹配 → TokenError (防 refresh 当 access 用)
    """
    try:
        payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
    except jwt.ExpiredSignatureError as e:
        raise TokenError("token expired") from e
    except jwt.InvalidTokenError as e:
        raise TokenError(f"invalid token: {e}") from e
    if expected_type is not None and payload.get("typ") != expected_type:
        raise TokenError(f"wrong token type: want={expected_type} got={payload.get('typ')}")
    if "sub" not in payload:
        raise TokenError("token missing sub")
    return payload
 def issue_token_pair(user_id: int) -> dict[str, Any]:
    """登录/刷新成功后调,一次性发回 access + refresh。
    返回字段对齐 OAuth2 习惯,前端易接:
      access_token / refresh_token / token_type / expires_in
    """
    access, access_exp = create_token(user_id=user_id, token_type="access")
    refresh, refresh_exp = create_token(user_id=user_id, token_type="refresh")
    return {
        "access_token": access,
        "refresh_token": refresh,
        "token_type": "Bearer",
        "expires_in": int((access_exp - _now()).total_seconds()),
        "refresh_expires_in": int((refresh_exp - _now()).total_seconds()),
    }
@@ -0,0 +1,68 @@
 """短信验证码服务。
 当前实现:**mock 模式**。
  - send_code(): 不真发短信,仅 log。记录 phone → 发送时间(防 60s 内重复发)
  - verify_code(): 任意 6 位数字均通过(配合前台 demo 行为)
 后续接真供应商(阿里云 / 腾讯云)时:
  - send_code() 改为调供应商 API,把生成的 6 位码存到 cache(redis / sqlite)
  - verify_code() 比对 cache 里的码,且验过即作废
 进程内存方案占坑期够用;切真实供应商时一并切 redis。
 """
 from __future__ import annotations
 import logging
 import time
 from threading import Lock
 from app.core.config import settings
 logger = logging.getLogger("shagua.sms")
 # 进程内最近发送时间表:{phone: epoch_seconds},用于 60s 内拒发
 _last_sent: dict[str, float] = {}
 _lock = Lock()
 class SmsError(Exception):
    """业务异常:发送过频 / 验证码不对。api 层 catch 后翻成 4xx。"""
 def send_code(phone: str) -> int:
    """发送(或 mock 发送)验证码。
    Returns: 距下一次可发的秒数(=0 表示刚刚已发,需等 SMS_SEND_INTERVAL_SEC 秒)
    Raises: SmsError 如果上次发送在 SMS_SEND_INTERVAL_SEC 内
    """
    now = time.time()
    with _lock:
        last = _last_sent.get(phone, 0.0)
        elapsed = now - last
        if elapsed < settings.SMS_SEND_INTERVAL_SEC:
            remain = int(settings.SMS_SEND_INTERVAL_SEC - elapsed)
            raise SmsError(f"send too frequent, retry in {remain}s")
        _last_sent[phone] = now
    if settings.SMS_MOCK:
        logger.info("[SMS-MOCK] send to %s****, code=any-6-digits", phone[:3])
    else:
        # TODO: 接真实短信供应商
        logger.warning("[SMS] real provider not implemented yet, phone=%s****", phone[:3])
        raise SmsError("sms provider not configured")
    return settings.SMS_SEND_INTERVAL_SEC
 def verify_code(phone: str, code: str) -> bool:
    """校验验证码。mock 模式下任意 6 位数字均通过。"""
    if settings.SMS_MOCK:
        if len(code) == 6 and code.isdigit():
            logger.info("[SMS-MOCK] verify ok for %s****", phone[:3])
            return True
        logger.info("[SMS-MOCK] verify fail (need 6 digits) for %s****", phone[:3])
        return False
    # TODO: 比对供应商发出的真实验证码
    logger.warning("[SMS] real provider not implemented yet, phone=%s****", phone[:3])
    return False
@@ -0,0 +1,48 @@
 """user 表的 CRUD 工具函数。
 业务策略 = "注册即登录":phone 不存在则 insert,存在则更新 last_login_at。
 """
 from __future__ import annotations
 from datetime import datetime, timezone
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 from app.models.user import User
 def get_user_by_id(db: Session, user_id: int) -> User | None:
    return db.get(User, user_id)
 def get_user_by_phone(db: Session, phone: str) -> User | None:
    stmt = select(User).where(User.phone == phone)
    return db.execute(stmt).scalar_one_or_none()
 def upsert_user_for_login(
    db: Session,
    *,
    phone: str,
    register_channel: str,
 ) -> User:
    """登录入口统一调:有则更新 last_login_at,无则新建。
    返回 commit 后的 user。调用方拿到 user.id 直接签 JWT。
    """
    user = get_user_by_phone(db, phone)
    now = datetime.now(timezone.utc)
    if user is None:
        user = User(
            phone=phone,
            register_channel=register_channel,
            last_login_at=now,
        )
        db.add(user)
    else:
        user.last_login_at = now
        # 被禁用的账号被尝试登录时,不自动启用,直接抛(在调用方处理)
    db.commit()
    db.refresh(user)
    return user
@@ -0,0 +1,17 @@
 """SQLAlchemy 2.0 Declarative Base。
 所有 ORM model 继承 `Base`。Alembic 通过 `Base.metadata` 拿到完整表结构生成 migration。
 """
 from __future__ import annotations
 from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
 class Base(DeclarativeBase):
    """所有 model 的公共基类。"""
 # 在 Alembic env.py 里 import Base 才能扫描到所有 model,
 # 这里也 import 一次确保 metadata 包含全部表。
 # (新增 model 时记得加到 app.models.__init__ 里)
 from app import models  # noqa: E402,F401
@@ -0,0 +1,56 @@
 """SQLAlchemy engine + Session 工厂。
 FastAPI 路由通过 `Depends(get_db)` 拿到一个 request-scope 的 Session,
 请求结束自动 close。
 """
 from __future__ import annotations
 import os
 from collections.abc import Iterator
 from sqlalchemy import create_engine
 from sqlalchemy.orm import Session, sessionmaker
 from app.core.config import settings
 def _ensure_sqlite_dir(url: str) -> None:
    """SQLite 文件路径如果在子目录,首启时自动 mkdir,避免 sqlalchemy 报 unable to open。"""
    prefix = "sqlite:///"
    if not url.startswith(prefix):
        return
    path = url[len(prefix):]
    dirname = os.path.dirname(path)
    if dirname:
        os.makedirs(dirname, exist_ok=True)
 _ensure_sqlite_dir(settings.DATABASE_URL)
 # SQLite 跨线程访问要 check_same_thread=False;PG/MySQL 不需要这个参数
 _connect_args: dict = {}
 if settings.DATABASE_URL.startswith("sqlite"):
    _connect_args["check_same_thread"] = False
 engine = create_engine(
    settings.DATABASE_URL,
    connect_args=_connect_args,
    # echo 在 dev 下打 SQL,生产关掉
    echo=settings.APP_DEBUG and not settings.is_prod,
    future=True,
    pool_pre_ping=True,
 )
 SessionLocal = sessionmaker(bind=engine, autocommit=False, autoflush=False, expire_on_commit=False)
 def get_db() -> Iterator[Session]:
    """FastAPI 依赖。请求开始建 session,请求结束自动 close。
    出异常时 SQLAlchemy 默认会标记 transaction 为 invalid,close 时自动 rollback。
    """
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()
@@ -0,0 +1,59 @@
 """FastAPI 入口。
 通过 `uvicorn app.main:app --reload` 启动。
 """
 from __future__ import annotations
 import logging
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from app.api.v1.auth import router as auth_router
 from app.core.config import settings
 from app.core.logging import setup_logging
 setup_logging(debug=settings.APP_DEBUG)
 logger = logging.getLogger("shagua.main")
@asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
    # 提示而非强制建表:生产用 alembic upgrade head,本地 dev 也建议先跑一次 migration。
    # 这里只 log,不自动 create_all,避免生产环境意外建出过时 schema。
    logger.info(
        "started env=%s debug=%s db=%s",
        settings.APP_ENV,
        settings.APP_DEBUG,
        settings.DATABASE_URL.split("://", 1)[0],
    )
    yield
    logger.info("shutting down")
 app = FastAPI(
    title=settings.APP_NAME,
    version="0.1.0",
    docs_url="/docs" if not settings.is_prod else None,
    redoc_url="/redoc" if not settings.is_prod else None,
    lifespan=lifespan,
 )
 if settings.cors_origins_list:
    app.add_middleware(
        CORSMiddleware,
        allow_origins=settings.cors_origins_list,
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
@app.get("/health", tags=["meta"])
 def health() -> dict[str, str]:
    return {"status": "ok"}
 app.include_router(auth_router)
@@ -0,0 +1,2 @@
 """所有 ORM model 必须在这里 import 一次,Alembic / metadata 才能扫到。"""
 from app.models.user import User  # noqa: F401
@@ -0,0 +1,47 @@
 """用户表。
 登录方式有两种,但都映射到同一行 user:
  - 极光一键登录 → phone 唯一索引
  - 短信验证码登录(mock 阶段)  → 也是 phone 唯一索引
 注册即登录:phone 不存在则 insert,存在则更新 last_login_at。
 后续如果加微信/Apple 登录,新增 oauth_account 表,这张表不动。
 """
 from __future__ import annotations
 from datetime import datetime, timezone
 from sqlalchemy import DateTime, Integer, String, func
 from sqlalchemy.orm import Mapped, mapped_column
 from app.db.base import Base
 def _utcnow() -> datetime:
    return datetime.now(timezone.utc)
 class User(Base):
    __tablename__ = "user"
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    phone: Mapped[str] = mapped_column(String(20), unique=True, index=True, nullable=False)
    # 注册渠道:jverify / sms。后续加 wechat / apple 时扩
    register_channel: Mapped[str] = mapped_column(String(20), nullable=False, default="jverify")
    nickname: Mapped[str | None] = mapped_column(String(64), nullable=True)
    avatar_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
    # 账号状态:active / disabled / deleted
    status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), nullable=False
    )
    last_login_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=_utcnow, nullable=False
    )
    def __repr__(self) -> str:  # pragma: no cover
        return f"<User id={self.id} phone={self.phone}>"
@@ -0,0 +1,77 @@
 """Auth 相关请求 / 响应 schemas。
 跟客户端约定:
  - 字段统一用 snake_case
  - 时间字段统一 ISO 8601 (UTC)
  - 登录类接口成功时统一返回 TokenWithUser
 """
 from __future__ import annotations
 from datetime import datetime
 from pydantic import BaseModel, ConfigDict, Field
 # ===== 用户对外信息 =====
 class UserOut(BaseModel):
    model_config = ConfigDict(from_attributes=True)  # 允许直接 UserOut.model_validate(orm_user)
    id: int
    phone: str
    nickname: str | None = None
    avatar_url: str | None = None
    register_channel: str
    status: str
    created_at: datetime
    last_login_at: datetime
 # ===== Token 通用结构 =====
 class TokenPair(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "Bearer"
    expires_in: int = Field(..., description="access_token 剩余秒数")
    refresh_expires_in: int = Field(..., description="refresh_token 剩余秒数")
 class TokenWithUser(TokenPair):
    user: UserOut
 # ===== 极光一键登录 =====
 class JverifyLoginRequest(BaseModel):
    login_token: str = Field(..., description="客户端 loginAuth 拿到的 loginToken", min_length=1)
    operator: str = Field("", description="CM/CU/CT,用于日志,可选")
 # ===== 短信验证码 =====
 class SmsSendRequest(BaseModel):
    phone: str = Field(..., min_length=11, max_length=11, pattern=r"^1\d{10}$")
 class SmsSendResponse(BaseModel):
    sent: bool
    mock: bool = Field(..., description="是否 mock 发送(true 时验证码不会真发,任意 6 位通过)")
    cooldown_sec: int = Field(..., description="多少秒后才能再发一次")
 class SmsLoginRequest(BaseModel):
    phone: str = Field(..., min_length=11, max_length=11, pattern=r"^1\d{10}$")
    code: str = Field(..., min_length=4, max_length=8)
 # ===== Refresh =====
 class RefreshRequest(BaseModel):
    refresh_token: str = Field(..., min_length=1)
 # ===== Logout =====
 class LogoutResponse(BaseModel):
    ok: bool = True
@@ -0,0 +1,33 @@
 # 80 → 301 → 443
 server {
    listen 80;
    listen [::]:80;
    server_name app-api.shaguabijia.com;
    return 301 https://$host$request_uri;
 }
 # 443 SSL 反代到本地 uvicorn (127.0.0.1:8770)
 server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name app-api.shaguabijia.com;
    ssl_certificate     /etc/nginx/ssl/app-api.shaguabijia.com.pem;
    ssl_certificate_key /etc/nginx/ssl/app-api.shaguabijia.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_session_cache   shared:SSL:10m;
    client_max_body_size 4m;
    location / {
        proxy_pass http://127.0.0.1:8770;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 30s;
    }
 }
@@ -0,0 +1,22 @@
 [Unit]
 Description=Shaguabijia App Backend (FastAPI / uvicorn)
 After=network.target
 [Service]
 Type=simple
 User=root
 WorkingDirectory=/opt/shaguabijia-app-server
 Environment="PATH=/opt/shaguabijia-app-server/.venv/bin:/usr/bin:/bin"
 EnvironmentFile=/opt/shaguabijia-app-server/.env
 ExecStart=/opt/shaguabijia-app-server/.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8770 --workers 1 --log-level info
 Restart=on-failure
 RestartSec=3
 NoNewPrivileges=true
 PrivateTmp=true
 ProtectSystem=strict
 ReadWritePaths=/opt/shaguabijia-app-server
 ProtectHome=true
 [Install]
 WantedBy=multi-user.target
@@ -0,0 +1,250 @@
 # 傻瓜比价 App Server — 后端技术实现
 > 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
 > 仓库:`shaguabijia-app-server`
 > 当前版本:v0.1.0(登录模块)
 > 最后更新:2026-05-23
 ---
 ## 1. 本次实施范围
 本阶段目标是搭正式 App 后端的**账号与登录**能力,供 Android 正式版(`shaguabijia-app-android`)对接。
 已实现:
 | 能力 | 状态 | 说明 |
 |---|---|---|
 | 极光一键登录 | ✅ 已联调 | `loginToken` → 极光 REST 验真 → RSA 解密手机号 → 注册/登录 |
 | 短信验证码登录 | ✅ mock 可用 | 开发阶段任意 6 位通过,便于无短信供应商时联调 |
 | JWT 双 token | ✅ | access(2h) + refresh(30d) |
 | 用户表 + ORM | ✅ | SQLAlchemy 2.0 + Alembic |
 | `/me` 鉴权 | ✅ | Bearer access_token |
 | 单元测试 | ✅ | health + sms 登录闭环 + refresh + 限流 |
 未做(后续迭代):
 - 真实短信供应商(阿里云/腾讯云)
 - logout 服务端 token 黑名单(jti)
 - 昵称/头像修改、注销账号
 - PostgreSQL 生产切库(当前 SQLite 起步)
 ---
 ## 2. 与试验后台的关系
 | 维度 | 试验后台 `shaguabijia-server` | 正式后台 `shaguabijia-app-server` |
 |---|---|---|
 | 域名 | `api.shaguabijia.com` | `app-api.shaguabijia.com` |
 | 数据库 | stdlib sqlite3,手写 SQL | SQLAlchemy 2.0 + Alembic |
 | 账号体系 | 仅占坑(phone 当 ID) | User 表 + JWT |
 | 极光验 token | ✅ 有 | ✅ 移植并增强 |
 | 短信登录 | ❌ | ✅ mock |
 | 配置 | 硬编码 | pydantic-settings + `.env` |
 **极光一键登录的核心逻辑**(REST 调用、RSA padding 试错顺序)直接参考试验后台 `app/api/auth.py`,
 等价实现在 `app/core/jiguang.py`。
 试验后台 RSA 私钥部署在服务器 `/opt/shaguabijia-server/secrets/jverify_rsa_private.pem`(不入 git)。
 正式后台因原私钥不可用,在极光控制台**重新生成 1024-bit RSA 密钥对**并上传公钥。
 ---
 ## 3. 技术栈
 | 维度 | 选型 | 说明 |
 |---|---|---|
 | 语言 | Python 3.11+ | 本地开发用 3.13 |
 | Web | FastAPI 0.115+ | OpenAPI 自动生成 |
 | ASGI | uvicorn[standard] | 生产 `--host 127.0.0.1 --port 8770` |
 | ORM | SQLAlchemy 2.0 | Mapped 新风格 |
 | 迁移 | Alembic | `render_as_batch` 兼容 SQLite |
 | DB | SQLite | 生产可改 `DATABASE_URL` 切 PostgreSQL |
 | Auth | PyJWT | HS256,access + refresh |
 | 极光 | httpx + cryptography | REST 验 token + RSA 解密 |
 | 配置 | pydantic-settings | `.env` 加载 |
 | 测试 | pytest + httpx TestClient | 临时文件 SQLite |
 ---
 ## 4. 登录链路
 ### 4.1 极光一键登录(主路径)
 ```
 Android SDK loginAuth
    → 客户端拿到 loginToken
    → POST /api/v1/auth/jverify-login  { login_token, operator }
    → 后端 POST 极光 loginTokenVerify (Basic Auth = AppKey:MasterSecret)
    → 极光返回 RSA 加密的手机号(base64)
    → 后端用私钥解密(PKCS1v15,实测电信 CT 走此 padding)
    → upsert User(phone 唯一) → 签 JWT → 返回 TokenWithUser
 ```
 **关键配置**(与 Android 端必须一致):
 | 项 | 值 |
 |---|---|
 | 包名 | `com.jishisongfu.shaguabijia` |
 | 极光 AppKey | `966b451a8d9cfe12d173ea9d` |
 | RSA 公钥 | 极光控制台「加密公钥」(1024-bit,≤220 字符) |
 | RSA 私钥 | `secrets/jverify_rsa_private.pem`(不入 git) |
 **RSA 密钥说明**:
 - 密钥对由我方生成(`openssl genrsa 1024`),公钥上传极光控制台
 - 极光控制台限制公钥长度 ≤220 字符,因此用 **1024-bit** 而非 2048-bit
 - 私钥路径由 `JG_PRIVATE_KEY_PATH` 指定,懒加载;文件不存在时 `jverify-login` 返回 502
 ### 4.2 短信登录(mock 路径)
 ```
 POST /api/v1/auth/sms/send   { phone }     → 60s 冷却,不真发短信
 POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过(SMS_MOCK=true)
    → upsert User → 签 JWT → 返回 TokenWithUser
 ```
 ### 4.3 Token 刷新
 ```
 POST /api/v1/auth/refresh  { refresh_token }
    → 校验 refresh token → 签新 access+refresh 对
 ```
 Android 端通过 OkHttp `Authenticator` 在 401 时自动调用。
 ---
 ## 5. 数据模型
 ### User 表
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | id | INTEGER PK | 自增 |
 | phone | VARCHAR UNIQUE | 手机号,登录主键 |
 | register_channel | VARCHAR | `jverify` / `sms` |
 | nickname | VARCHAR NULL | 预留 |
 | avatar_url | VARCHAR NULL | 预留 |
 | status | VARCHAR | `active` / `disabled` |
 | created_at | DATETIME | 注册时间 |
 | last_login_at | DATETIME | 最近登录 |
 `upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册。
 ---
 ## 6. API 一览
 | 方法 | 路径 | 鉴权 | 说明 |
 |---|---|---|---|
 | GET | `/health` | 无 | 健康检查 |
 | POST | `/api/v1/auth/jverify-login` | 无 | 极光一键登录 |
 | POST | `/api/v1/auth/sms/send` | 无 | 发短信(mock) |
 | POST | `/api/v1/auth/sms/login` | 无 | 短信登录 |
 | POST | `/api/v1/auth/refresh` | 无 | 刷新 token |
 | GET | `/api/v1/auth/me` | Bearer | 当前用户 |
 | POST | `/api/v1/auth/logout` | Bearer | 登出占位 |
 Swagger UI: `http://localhost:8770/docs`
 ---
 ## 7. 目录结构
 ```
 app/
 ├── main.py                 # FastAPI 入口,lifespan,CORS
 ├── core/
 │   ├── config.py           # pydantic-settings
 │   ├── security.py         # JWT 签发/校验
 │   ├── jiguang.py          # 极光 REST + RSA 解密
 │   └── sms.py              # 短信 mock(内存验证码)
 ├── db/
 │   ├── base.py
 │   └── session.py          # engine + get_db
 ├── models/user.py
 ├── schemas/auth.py
 ├── crud/user.py
 └── api/
    ├── deps.py             # get_current_user
    └── v1/auth.py          # 登录路由
 alembic/                    # 数据库迁移
 deploy/                     # systemd + nginx
 secrets/                    # RSA 私钥(不入 git)
 tests/                      # pytest
 ```
 ---
 ## 8. 本地联调(真机 + LAN)
 后端监听所有网卡,供同一 WiFi 下的测试机访问:
 ```bash
 source .venv/bin/activate
 uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload
 ```
 Android debug 包 `BASE_URL` 指向开发机 LAN IP(配置在 `local.properties`,不入 git):
 ```
 debug.api.host=192.168.x.x
 debug.api.port=8770
 ```
 真机浏览器访问 `http://192.168.x.x:8770/health` 应返回 `{"status":"ok"}`。
 ---
 ## 9. 部署要点
 ```bash
 # 代码同步(排除 secrets 和 data)
 rsync -avz --exclude='.venv' --exclude='data' --exclude='secrets/*.pem' \
    ./ server:/opt/shaguabijia-app-server/
 # 私钥单独 scp(仅首次或轮换时)
 scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/
 # 迁移 + 重启
 ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
 ```
 生产 checklist:
 - [ ] `JWT_SECRET_KEY` 换成随机长字符串
 - [ ] `APP_ENV=prod`, `APP_DEBUG=false`
 - [ ] RSA 私钥权限 `chmod 600`
 - [ ] nginx SSL 证书有效
 - [ ] `alembic upgrade head` 已执行
 ---
 ## 10. 已知问题与后续
 | 项 | 说明 |
 |---|---|
 | logout 无服务端失效 | 目前靠客户端清 token;后续可加 jti 黑名单表 |
 | SMS 为 mock | 上线前需接真实短信供应商并设 `SMS_MOCK=false` |
 | SQLite 并发 | 生产流量上来后切 PostgreSQL,只改 `DATABASE_URL` |
 | 极光 RSA 1024-bit | 极光控制台限制所致;仅加密 11 位手机号,可接受 |
 ---
 ## 11. 联调验证记录(2026-05-23)
 本地 LAN 联调已通过:
 ```
 # 短信登录
 POST /api/v1/auth/sms/login → 200, user_id=2, phone=177****82
 # 极光一键登录
 POST /api/v1/auth/jverify-login → 200, operator=CT, token_len=448
 [JG] decrypted with padding=PKCS1v15
 jverify_login ok user_id=3, phone=153****91
 ```
 Android 端包名、签名、极光 AppKey 与控制台一致,SDK init 8000,loginAuth 6000。
@@ -0,0 +1,54 @@
 [project]
 name = "shaguabijia-app-server"
 version = "0.1.0"
 description = "Shaguabijia 正式 App 后端 (FastAPI + SQLAlchemy + JWT)"
 requires-python = ">=3.11"
 dependencies = [
    # Web 框架 & ASGI
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.32.0",
    # 数据校验
    "pydantic>=2.9.0",
    "pydantic-settings>=2.5.0",
    "email-validator>=2.2.0",
    # ORM & 迁移
    "sqlalchemy>=2.0.35",
    "alembic>=1.13.3",
    # JWT 签名 / 校验
    "pyjwt[crypto]>=2.9.0",
    # 极光一键登录:RSA 解密极光返回的加密手机号
    "cryptography>=42.0.0",
    # HTTP 客户端 (调极光 REST)
    "httpx>=0.27.0",
    # multipart form (FastAPI 表单上传依赖)
    "python-multipart>=0.0.9",
 ]
 [project.optional-dependencies]
 dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.24.0",
    "httpx>=0.27.0",
    "ruff>=0.6.0",
 ]
 [tool.setuptools.packages.find]
 include = ["app*"]
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
 [tool.ruff]
 line-length = 100
 target-version = "py311"
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "UP"]
 ignore = ["E501"]
@@ -0,0 +1,48 @@
 """测试用 fixtures。
 测试 DB 用临时文件 SQLite。
  - 不用 in-memory:in-memory 默认 per-connection,跨连接看不到表。
  - 用临时文件保证 SessionLocal 每次新连都看到同一份 schema。
 顺序:set env(必须在 import app.* 之前) → import app → 建表 → TestClient
 """
 from __future__ import annotations
 import os
 import tempfile
 from collections.abc import Iterator
 # 临时 db 文件路径,进程退出后清理
 _tmp_db = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
 _tmp_db.close()
 os.environ["DATABASE_URL"] = f"sqlite:///{_tmp_db.name}"
 os.environ.setdefault("JWT_SECRET_KEY", "test-secret-please-ignore-this-is-only-for-pytest-not-real")
 os.environ.setdefault("JG_APP_KEY", "test-key")
 os.environ.setdefault("JG_MASTER_SECRET", "test-secret")
 os.environ.setdefault("SMS_MOCK", "true")
 os.environ.setdefault("APP_ENV", "dev")
 os.environ.setdefault("APP_DEBUG", "false")  # 测试不打 SQL 日志
 import pytest
 from fastapi.testclient import TestClient
 from app.db.base import Base
 from app.db.session import engine
 from app.main import app
@pytest.fixture(scope="session", autouse=True)
 def _setup_db() -> Iterator[None]:
    Base.metadata.create_all(engine)
    yield
    Base.metadata.drop_all(engine)
    try:
        os.unlink(_tmp_db.name)
    except OSError:
        pass
@pytest.fixture()
 def client() -> TestClient:
    return TestClient(app)
@@ -0,0 +1,70 @@
 """auth 流程测试(不依赖真实极光,只测 sms mock 路径 + JWT 闭环)。"""
 from __future__ import annotations
 def test_sms_login_and_me_flow(client) -> None:
    """sms_send → sms_login → 用 access_token 调 /me 拿到自己。"""
    phone = "13800138000"
    # 1. 发短信(mock,任意 6 位均通过)
    r = client.post("/api/v1/auth/sms/send", json={"phone": phone})
    assert r.status_code == 200, r.text
    body = r.json()
    assert body["sent"] is True
    assert body["mock"] is True
    # 2. 登录
    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
    assert r.status_code == 200, r.text
    data = r.json()
    assert "access_token" in data
    assert "refresh_token" in data
    assert data["user"]["phone"] == phone
    assert data["user"]["register_channel"] == "sms"
    access = data["access_token"]
    refresh = data["refresh_token"]
    # 3. /me
    r = client.get("/api/v1/auth/me", headers={"Authorization": f"Bearer {access}"})
    assert r.status_code == 200, r.text
    assert r.json()["phone"] == phone
    # 4. /me 不带 token → 401
    r = client.get("/api/v1/auth/me")
    assert r.status_code == 401
    # 5. 用 refresh 换新 token
    r = client.post("/api/v1/auth/refresh", json={"refresh_token": refresh})
    assert r.status_code == 200, r.text
    assert "access_token" in r.json()
    # 6. 用 access 当 refresh 拒绝(防 token 类型混用)
    r = client.post("/api/v1/auth/refresh", json={"refresh_token": access})
    assert r.status_code == 401
    # 7. logout
    r = client.post("/api/v1/auth/logout", headers={"Authorization": f"Bearer {access}"})
    assert r.status_code == 200
    assert r.json()["ok"] is True
 def test_sms_send_too_frequent(client) -> None:
    phone = "13900139000"
    r1 = client.post("/api/v1/auth/sms/send", json={"phone": phone})
    assert r1.status_code == 200
    r2 = client.post("/api/v1/auth/sms/send", json={"phone": phone})
    assert r2.status_code == 429
 def test_sms_login_bad_code(client) -> None:
    """mock 模式下,5 位通过 schema 长度校验,但业务层只接受 6 位 → 400。"""
    phone = "13700137000"
    client.post("/api/v1/auth/sms/send", json={"phone": phone})
    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "12345"})
    assert r.status_code == 400
    assert "invalid sms code" in r.json()["detail"]
 def test_phone_format_validation(client) -> None:
    r = client.post("/api/v1/auth/sms/send", json={"phone": "1234567"})
    assert r.status_code == 422
@@ -0,0 +1,20 @@
 """最小冒烟:服务能起、/health 通。"""
 from __future__ import annotations
 def test_health_ok(client) -> None:
    resp = client.get("/health")
    assert resp.status_code == 200
    assert resp.json() == {"status": "ok"}
 def test_openapi_loads(client) -> None:
    resp = client.get("/openapi.json")
    assert resp.status_code == 200
    paths = resp.json()["paths"]
    # auth endpoints 都注册了
    assert "/api/v1/auth/jverify-login" in paths
    assert "/api/v1/auth/sms/send" in paths
    assert "/api/v1/auth/sms/login" in paths
    assert "/api/v1/auth/refresh" in paths
    assert "/api/v1/auth/me" in paths
		`@@ -0,0 +1,2 @@`
							`"""所有 ORM model 必须在这里 import 一次,Alembic / metadata 才能扫到。"""`
							`from app.models.user import User # noqa: F401`