account-kit 0.1.0__tar.gz

account_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kqstone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

account_kit-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+graft tests
+global-exclude __pycache__ *.py[cod]

account_kit-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: account-kit
+Version: 0.1.0
+Summary: Shared async account service for FastAPI apps
+Author: kqstone
+License-Expression: MIT
+Keywords: fastapi,authentication,account,jwt,totp,2fa,sqlalchemy,asyncpg,postgresql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: pydantic[email]>=2.0
+Requires-Dist: python-jose[cryptography]>=3.3
+Requires-Dist: bcrypt>=4.0
+Requires-Dist: python-multipart
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyotp>=2.9
+Requires-Dist: cryptography
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# account-kit
+
+dedd-online 与 dental-case-pro 共用的异步账号包。PostgreSQL + SQLAlchemy + asyncpg，表在 `auth` schema，用户主键是 UUID。
+
+账号能力：注册、登录、邮件验证码、审批、单设备会话、自定义角色、后台权限（`is_admin`，不是角色）、等级目录、两步验证。限额、限流、积分留在宿主。
+
+```python
+from account_kit import init_db, mount_account, seed_defaults
+from account_kit.config import AccountKitConfig
+
+await init_db(engine)
+await seed_defaults(session)
+mount_account(app, get_db, AccountKitConfig(jwt_secret="..."))
+```
+
+## 安装
+
+Python 包从 [PyPI](https://pypi.org/project/account-kit/) 安装：
+
+```bash
+pip install account-kit
+```
+
+界面包发在 GitHub Packages（不是 npmjs.com）。安装前在项目根写 `.npmrc`：
+
+```
+@kqstone:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
+```
+
+`NPM_TOKEN` 需要带 `read:packages` 的 classic PAT（或等价权限）。CI 里可以用 `GITHUB_TOKEN`，但要先在包的 **Manage Actions access** 里给消费仓库（如 `kqstone/dedd-online`、`kqstone/dental-case-pro`）Read 权限。从 private 仓库首次发布的包默认为 private；可在包设置里改成 public，但无论可见性如何，安装都仍需要 token。
+
+```bash
+npm install @kqstone/account-ui-vue    # Vue 3
+npm install @kqstone/account-ui-react  # React 18 / 19
+```
+
+不单独发布 client 包，请求客户端打进这两个界面包：
+
+- `@kqstone/account-ui-vue`：`LoginForm`、`RegisterForm`、`ResetPasswordForm`、`TierBadge`、`createAccountClient`
+- `@kqstone/account-ui-react`：同上
+
+界面包发布的是构建后的 `dist/`（ESM + `.d.ts`），样式在组件首次渲染时注入，不需要单独引入 CSS。
+
+## 本地开发
+
+宿主仓库用 `file:` 路径引用界面包时，先在 account-kit 里构建一次（`npm ci` 会通过 `prepare` 自动构建）：
+
+```bash
+cd packages/account-ui-vue && npm ci     # 或 packages/account-ui-react
+```
+
+改了界面包源码后，重新 `npm run build`，再在宿主里重新安装依赖。
+
+## 发布
+
+版本号写在 `pyproject.toml` 和两个 `packages/*/package.json` 里，三处保持一致。推送 `v<版本号>` tag（如 `v0.1.0`）后，GitHub Action 先校验 tag 与三处版本一致、跑测试和构建，然后：
+
+- Python 包发布到 [PyPI](https://pypi.org/project/account-kit/)（Trusted Publishing，不用 token）
+- 两个界面包发布到 [GitHub Packages](https://github.com/kqstone?tab=packages)（`GITHUB_TOKEN`，`packages: write`）
+
+日后若改发 npmjs.com：把 `publishConfig.registry` 改回默认、workflow 改为 `registry.npmjs.org` + `NPM_TOKEN`（或 npm trusted publishing），并更新本节安装说明。
+
+## 许可证
+
+MIT

account_kit-0.1.0/README.md

@@ -0,0 +1,66 @@
+# account-kit
+
+dedd-online 与 dental-case-pro 共用的异步账号包。PostgreSQL + SQLAlchemy + asyncpg，表在 `auth` schema，用户主键是 UUID。
+
+账号能力：注册、登录、邮件验证码、审批、单设备会话、自定义角色、后台权限（`is_admin`，不是角色）、等级目录、两步验证。限额、限流、积分留在宿主。
+
+```python
+from account_kit import init_db, mount_account, seed_defaults
+from account_kit.config import AccountKitConfig
+
+await init_db(engine)
+await seed_defaults(session)
+mount_account(app, get_db, AccountKitConfig(jwt_secret="..."))
+```
+
+## 安装
+
+Python 包从 [PyPI](https://pypi.org/project/account-kit/) 安装：
+
+```bash
+pip install account-kit
+```
+
+界面包发在 GitHub Packages（不是 npmjs.com）。安装前在项目根写 `.npmrc`：
+
+```
+@kqstone:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
+```
+
+`NPM_TOKEN` 需要带 `read:packages` 的 classic PAT（或等价权限）。CI 里可以用 `GITHUB_TOKEN`，但要先在包的 **Manage Actions access** 里给消费仓库（如 `kqstone/dedd-online`、`kqstone/dental-case-pro`）Read 权限。从 private 仓库首次发布的包默认为 private；可在包设置里改成 public，但无论可见性如何，安装都仍需要 token。
+
+```bash
+npm install @kqstone/account-ui-vue    # Vue 3
+npm install @kqstone/account-ui-react  # React 18 / 19
+```
+
+不单独发布 client 包，请求客户端打进这两个界面包：
+
+- `@kqstone/account-ui-vue`：`LoginForm`、`RegisterForm`、`ResetPasswordForm`、`TierBadge`、`createAccountClient`
+- `@kqstone/account-ui-react`：同上
+
+界面包发布的是构建后的 `dist/`（ESM + `.d.ts`），样式在组件首次渲染时注入，不需要单独引入 CSS。
+
+## 本地开发
+
+宿主仓库用 `file:` 路径引用界面包时，先在 account-kit 里构建一次（`npm ci` 会通过 `prepare` 自动构建）：
+
+```bash
+cd packages/account-ui-vue && npm ci     # 或 packages/account-ui-react
+```
+
+改了界面包源码后，重新 `npm run build`，再在宿主里重新安装依赖。
+
+## 发布
+
+版本号写在 `pyproject.toml` 和两个 `packages/*/package.json` 里，三处保持一致。推送 `v<版本号>` tag（如 `v0.1.0`）后，GitHub Action 先校验 tag 与三处版本一致、跑测试和构建，然后：
+
+- Python 包发布到 [PyPI](https://pypi.org/project/account-kit/)（Trusted Publishing，不用 token）
+- 两个界面包发布到 [GitHub Packages](https://github.com/kqstone?tab=packages)（`GITHUB_TOKEN`，`packages: write`）
+
+日后若改发 npmjs.com：把 `publishConfig.registry` 改回默认、workflow 改为 `registry.npmjs.org` + `NPM_TOKEN`（或 npm trusted publishing），并更新本节安装说明。
+
+## 许可证
+
+MIT

account_kit-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "account-kit"
+version = "0.1.0"
+description = "Shared async account service for FastAPI apps"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "kqstone" }]
+keywords = ["fastapi", "authentication", "account", "jwt", "totp", "2fa", "sqlalchemy", "asyncpg", "postgresql"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Natural Language :: Chinese (Simplified)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "sqlalchemy[asyncio]>=2.0",
+    "asyncpg>=0.29",
+    "pydantic[email]>=2.0",
+    "python-jose[cryptography]>=3.3",
+    "bcrypt>=4.0",
+    "python-multipart",
+    "jinja2>=3.1",
+    "pyotp>=2.9",
+    "cryptography",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "httpx>=0.27"]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+account_kit = ["templates/emails/*.html"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

account_kit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

account_kit-0.1.0/src/account_kit/__init__.py

@@ -0,0 +1,9 @@
+"""Shared account kit: one async user model for every app."""
+
+from account_kit.router import mount_account
+from account_kit.schema_setup import init_db
+from account_kit.seed import seed_defaults
+
+__version__ = "0.1.0"
+
+__all__ = ["init_db", "mount_account", "seed_defaults", "__version__"]

account_kit-0.1.0/src/account_kit/admin_router.py

@@ -0,0 +1,181 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from account_kit.admin_schemas import AdminUserPatch, RoleBody, RoleChangeCreate, RoleChangeReview, RolePatch, TierBody, TierPatch
+from account_kit.catalog import apply_admin_user_patch, create_role, create_tier, delete_role, delete_tier, patch_role, patch_tier
+from account_kit.config import get_config
+from account_kit.deps import get_current_user, get_db, require_admin
+from account_kit.models import Role, RoleChangeRequest, User, UserTier
+from account_kit.service import assert_role_code, get_user_by_id, to_response
+
+admin_router = APIRouter(tags=["account-admin"])
+public_extra = APIRouter(tags=["auth"])
+
+
+def _role_dict(row: Role) -> dict:
+    return {
+        "code": row.code,
+        "name": row.name,
+        "sort_order": row.sort_order,
+        "description": row.description,
+        "is_default": row.is_default,
+        "allow_register": row.allow_register,
+    }
+
+
+def _tier_dict(row: UserTier) -> dict:
+    return {
+        "code": row.code,
+        "name": row.name,
+        "sort_order": row.sort_order,
+        "badge_color": row.badge_color,
+        "description": row.description,
+        "is_default": row.is_default,
+    }
+
+
+@public_extra.get("/roles")
+async def public_roles(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Role).where(Role.allow_register.is_(True)).order_by(Role.sort_order, Role.code))
+    return [_role_dict(row) for row in result.scalars().all()]
+
+
+@public_extra.get("/tiers")
+async def public_tiers(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(UserTier).order_by(UserTier.sort_order, UserTier.code))
+    return [_tier_dict(row) for row in result.scalars().all()]
+
+
+@public_extra.post("/role-change-requests")
+async def request_role_change(
+    body: RoleChangeCreate,
+    current_user=Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    if not get_config().role_change_enabled:
+        raise HTTPException(status_code=404, detail="Not found")
+    code = assert_role_code(body.requested_role)
+    role = await db.get(Role, code)
+    if role is None:
+        raise HTTPException(status_code=400, detail="角色不存在")
+    if code == current_user.role:
+        raise HTTPException(status_code=400, detail="已经是该角色")
+    existing = await db.execute(
+        select(RoleChangeRequest).where(
+            RoleChangeRequest.user_id == current_user.id,
+            RoleChangeRequest.status == "pending",
+        )
+    )
+    if existing.scalars().first():
+        raise HTTPException(status_code=409, detail="已有待审核的角色申请")
+    row = RoleChangeRequest(user_id=current_user.id, from_role=current_user.role, to_role=code, status="pending")
+    db.add(row)
+    await db.commit()
+    await db.refresh(row)
+    return {"id": row.id, "from_role": row.from_role, "to_role": row.to_role, "status": row.status}
+
+
+@admin_router.get("/roles")
+async def list_roles(_admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Role).order_by(Role.sort_order, Role.code))
+    return [_role_dict(row) for row in result.scalars().all()]
+
+
+@admin_router.post("/roles", status_code=201)
+async def add_role(body: RoleBody, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _role_dict(await create_role(db, body))
+
+
+@admin_router.patch("/roles/{code}")
+async def edit_role(code: str, body: RolePatch, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _role_dict(await patch_role(db, code, body))
+
+
+@admin_router.delete("/roles/{code}", status_code=204)
+async def remove_role(code: str, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    await delete_role(db, code)
+
+
+@admin_router.get("/tiers")
+async def list_tiers(_admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(UserTier).order_by(UserTier.sort_order, UserTier.code))
+    return [_tier_dict(row) for row in result.scalars().all()]
+
+
+@admin_router.post("/tiers", status_code=201)
+async def add_tier(body: TierBody, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _tier_dict(await create_tier(db, body))
+
+
+@admin_router.patch("/tiers/{code}")
+async def edit_tier(code: str, body: TierPatch, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    return _tier_dict(await patch_tier(db, code, body))
+
+
+@admin_router.delete("/tiers/{code}", status_code=204)
+async def remove_tier(code: str, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    await delete_tier(db, code)
+
+
+@admin_router.get("/users")
+async def list_users(_admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(User).order_by(User.created_at.desc()))
+    return [await to_response(db, user) for user in result.scalars().all()]
+
+
+@admin_router.patch("/users/{user_id}")
+async def patch_user(
+    user_id: str,
+    body: AdminUserPatch,
+    _admin=Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    user = await get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    user = await apply_admin_user_patch(db, user, body)
+    return await to_response(db, user)
+
+
+@admin_router.delete("/users/{user_id}", status_code=204)
+async def delete_user(user_id: str, _admin=Depends(require_admin), db: AsyncSession = Depends(get_db)):
+    config = get_config()
+    user = await get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    if config.on_deleted is not None:
+        await config.on_deleted(db, user)
+    await db.delete(user)
+    await db.commit()
+
+
+@admin_router.post("/role-change-requests/{request_id}/review")
+async def review_role_change(
+    request_id: str,
+    body: RoleChangeReview,
+    admin=Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    if body.status not in ("approved", "rejected"):
+        raise HTTPException(status_code=400, detail="状态无效")
+    try:
+        request_uuid = uuid.UUID(request_id)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="申请不存在")
+    row = await db.get(RoleChangeRequest, request_uuid)
+    if row is None or row.status != "pending":
+        raise HTTPException(status_code=404, detail="申请不存在")
+    row.status = body.status
+    from datetime import datetime, timezone
+
+    row.reviewed_at = datetime.now(timezone.utc)
+    row.reviewed_by = admin.id
+    if body.status == "approved":
+        user = await get_user_by_id(db, row.user_id)
+        if user is not None:
+            user.role = row.to_role
+    await db.commit()
+    return {"id": row.id, "status": row.status}

account_kit-0.1.0/src/account_kit/admin_schemas.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import uuid
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from account_kit.schemas import ApprovalStatus
+
+
+class RoleBody(BaseModel):
+    code: str = Field(min_length=1, max_length=50)
+    name: str = Field(min_length=1, max_length=50)
+    sort_order: int = 0
+    description: Optional[str] = None
+    is_default: bool = False
+    allow_register: bool = False
+
+
+class RolePatch(BaseModel):
+    name: Optional[str] = Field(default=None, min_length=1, max_length=50)
+    sort_order: Optional[int] = None
+    description: Optional[str] = None
+    is_default: Optional[bool] = None
+    allow_register: Optional[bool] = None
+
+
+class TierBody(BaseModel):
+    code: str = Field(min_length=1, max_length=20)
+    name: str = Field(min_length=1, max_length=50)
+    sort_order: int = 0
+    badge_color: Optional[str] = None
+    description: Optional[str] = None
+    is_default: bool = False
+
+
+class TierPatch(BaseModel):
+    name: Optional[str] = Field(default=None, min_length=1, max_length=50)
+    sort_order: Optional[int] = None
+    badge_color: Optional[str] = None
+    description: Optional[str] = None
+    is_default: Optional[bool] = None
+
+
+class AdminUserPatch(BaseModel):
+    role: Optional[str] = None
+    is_admin: Optional[bool] = None
+    is_active: Optional[bool] = None
+    approval_status: Optional[ApprovalStatus] = None
+    tier_code: Optional[str] = None
+
+
+class RoleChangeCreate(BaseModel):
+    requested_role: str = Field(min_length=1, max_length=50)
+
+
+class RoleChangeReview(BaseModel):
+    status: ApprovalStatus

account_kit-0.1.0/src/account_kit/catalog.py

@@ -0,0 +1,167 @@
+"""Role and tier catalog. Limits stay in the host; this only stores names."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from fastapi import HTTPException
+from sqlalchemy import func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from account_kit.models import Role, User, UserTier, UserTierAssignment
+from account_kit.service import assert_role_code
+
+
+async def _clear_default_role(db: AsyncSession) -> None:
+    await db.execute(update(Role).values(is_default=False))
+
+
+async def _clear_default_tier(db: AsyncSession) -> None:
+    await db.execute(update(UserTier).values(is_default=False))
+
+
+async def create_role(db: AsyncSession, body) -> Role:
+    code = assert_role_code(body.code)
+    if await db.get(Role, code):
+        raise HTTPException(status_code=409, detail="角色已存在")
+    if body.is_default:
+        await _clear_default_role(db)
+    row = Role(
+        code=code,
+        name=body.name.strip(),
+        sort_order=body.sort_order,
+        description=body.description,
+        is_default=body.is_default,
+        allow_register=body.allow_register,
+    )
+    db.add(row)
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def patch_role(db: AsyncSession, code: str, body) -> Role:
+    row = await db.get(Role, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="角色不存在")
+    if body.name is not None:
+        row.name = body.name.strip()
+    if body.sort_order is not None:
+        row.sort_order = body.sort_order
+    if body.description is not None:
+        row.description = body.description
+    if body.allow_register is not None:
+        row.allow_register = body.allow_register
+    if body.is_default is True:
+        await _clear_default_role(db)
+        row.is_default = True
+    elif body.is_default is False and row.is_default:
+        raise HTTPException(status_code=400, detail="请先把另一个角色设为默认")
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def delete_role(db: AsyncSession, code: str) -> None:
+    row = await db.get(Role, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="角色不存在")
+    if row.is_default:
+        raise HTTPException(status_code=400, detail="不能删除默认角色")
+    used = await db.scalar(select(func.count()).select_from(User).where(User.role == code))
+    if used:
+        raise HTTPException(status_code=409, detail="仍有用户使用该角色")
+    await db.delete(row)
+    await db.commit()
+
+
+async def create_tier(db: AsyncSession, body) -> UserTier:
+    code = (body.code or "").strip()
+    if not code:
+        raise HTTPException(status_code=400, detail="等级代码无效")
+    if await db.get(UserTier, code):
+        raise HTTPException(status_code=409, detail="等级已存在")
+    if body.is_default:
+        await _clear_default_tier(db)
+    row = UserTier(
+        code=code,
+        name=body.name.strip(),
+        sort_order=body.sort_order,
+        badge_color=body.badge_color,
+        description=body.description,
+        is_default=body.is_default,
+    )
+    db.add(row)
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def patch_tier(db: AsyncSession, code: str, body) -> UserTier:
+    row = await db.get(UserTier, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="等级不存在")
+    if body.name is not None:
+        row.name = body.name.strip()
+    if body.sort_order is not None:
+        row.sort_order = body.sort_order
+    if body.badge_color is not None:
+        row.badge_color = body.badge_color
+    if body.description is not None:
+        row.description = body.description
+    if body.is_default is True:
+        await _clear_default_tier(db)
+        row.is_default = True
+    elif body.is_default is False and row.is_default:
+        raise HTTPException(status_code=400, detail="请先把另一个等级设为默认")
+    await db.commit()
+    await db.refresh(row)
+    return row
+
+
+async def delete_tier(db: AsyncSession, code: str) -> None:
+    row = await db.get(UserTier, code)
+    if row is None:
+        raise HTTPException(status_code=404, detail="等级不存在")
+    if row.is_default:
+        raise HTTPException(status_code=400, detail="不能删除默认等级")
+    used = await db.scalar(
+        select(func.count()).select_from(UserTierAssignment).where(UserTierAssignment.tier_code == code)
+    )
+    if used:
+        raise HTTPException(status_code=409, detail="仍有用户属于该等级")
+    await db.delete(row)
+    await db.commit()
+
+
+async def set_user_tier(db: AsyncSession, user: User, tier_code: str) -> None:
+    tier = await db.get(UserTier, tier_code)
+    if tier is None:
+        raise HTTPException(status_code=400, detail="等级不存在")
+    row = await db.get(UserTierAssignment, user.id)
+    if row is None:
+        db.add(UserTierAssignment(user_id=user.id, tier_code=tier.code))
+    else:
+        row.tier_code = tier.code
+        row.updated_at = datetime.now(timezone.utc)
+
+
+async def apply_admin_user_patch(db, user: User, body) -> User:
+    if body.role is not None:
+        code = assert_role_code(body.role)
+        if await db.get(Role, code) is None:
+            raise HTTPException(status_code=400, detail="角色不存在")
+        user.role = code
+    if body.is_admin is not None:
+        user.is_admin = body.is_admin
+    if body.is_active is not None:
+        user.is_active = body.is_active
+    if body.approval_status is not None:
+        user.approval_status = body.approval_status
+        if body.approval_status == "approved" and user.approved_at is None:
+            user.approved_at = datetime.now(timezone.utc)
+    if body.tier_code is not None:
+        await set_user_tier(db, user, body.tier_code)
+    await db.commit()
+    await db.refresh(user)
+    return user