feat(system): 实现用户管理接口

需求 2.5.1 用户账号管理，全部要求管理员权限（require_admin 依赖）：

- 接口：列表/详情/新增/编辑/删除/重置密码/启停/角色下拉，
  角色下拉放 /users/meta/roles 以避开 /{user_id} 的路由匹配冲突
- 删除、禁用、改角色三处自我保护：不允许对当前登录账号执行，
  避免管理员误操作后立刻失去全部管理权限且无法自行恢复
- 重置密码与禁用均提升 token_version，使已签发令牌立即失效，
  不依赖 Redis 黑名单
- 密码按字节数校验（bcrypt 5.0 硬上限 72 字节，中文一字 3 字节）
- 用户列表按 id 倒序：create_time 为秒级精度，同秒数据分页结果不确定
- 修复 replace_roles 未同步关系集合的缺陷：改用 user.user_roles
  集合追加，此前 session.add(UserRole(...)) 会表现为保存成功但返回空角色
- update_user 的自我保护原先依赖返回 None 的占位函数，恒不生效，
  改为显式传入 operator_id

Co-Authored-By: Claude Code <noreply@anthropic.com>

backend/app/api/deps.py

@@ -6,8 +6,9 @@ from fastapi import Depends
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy.orm import Session
 
+from app.core.constants import ROLE_ADMIN
 from app.core.db import get_db
-from app.core.exceptions import AuthError
+from app.core.exceptions import AuthError, ForbiddenError
 from app.core.security import decode_token
 from app.models import User
 from app.repositories import user_repository
@@ -71,3 +72,20 @@ def _is_digits(value: object) -> bool:
     令牌内容不可信，直接 int() 会因非法输入抛 ValueError 而不是 401。
     """
     return isinstance(value, str) and value.isdigit()
+
+
+def require_admin(current_user: Annotated[User, Depends(get_current_user)]) -> User:
+    """要求当前用户具备管理员角色。
+
+    需求 2.5.1 只定义了「系统管理员（全部权限）」与「普通用户（业务操作）」两个
+    角色，故权限判定用**角色粗粒度**即可，不必引入权限码表 —— `permissions`
+    与 `role_permissions` 表已建好，等业务方给出权限清单后再启用。
+
+    :raises ForbiddenError: 已登录但不具备管理员角色（403）
+    """
+    if ROLE_ADMIN not in user_repository.get_role_codes(current_user):
+        raise ForbiddenError("需要管理员权限")
+    return current_user
+
+
+AdminUser = Annotated[User, Depends(require_admin)]

backend/app/api/router.py

@@ -8,6 +8,7 @@ from fastapi import APIRouter
 
 from app.api import health
 from app.api.v1 import auth
+from app.api.v1.system import users as system_users
 
 api_router = APIRouter()
 
@@ -17,4 +18,10 @@ api_router.include_router(health.router)
 # 业务接口：/api/v1/*
 v1_router = APIRouter(prefix="/v1")
 v1_router.include_router(auth.router)
+
+# 系统管理（需求 2.5.1）：/api/v1/system/*
+system_router = APIRouter(prefix="/system")
+system_router.include_router(system_users.router)
+v1_router.include_router(system_router)
+
 api_router.include_router(v1_router)

backend/app/api/v1/system/__init__.py

@@ -0,0 +1,7 @@
+"""系统管理路由（需求 2.5.1）。
+
+含用户管理、角色查询、操作日志查询三部分，全部要求管理员权限。
+
+与 `api/v1/auth.py` 的分工：`auth` 是登录链路（未认证即可访问的验证码与登录，
+以及任何登录用户都能访问的 `/me` 与登出）；本包是**管理功能**。
+"""

backend/app/api/v1/system/users.py

@@ -0,0 +1,131 @@
+"""用户管理接口（需求 2.5.1：用户账号管理）。
+
+全部要求管理员权限 —— 按需求「系统管理员（全部权限）、普通用户（业务操作）」，
+用户管理属管理员专属。
+
+删除、禁用、改角色三处都有**自我保护**：不允许对当前登录账号执行，
+否则管理员误操作会立刻失去全部管理权限且无法自行恢复。
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Path, Query
+
+from app.api.deps import AdminUser, DbSession
+from app.core.response import ApiResponse, PageResult, ok
+from app.schemas.user import (
+    PasswordResetIn,
+    RoleOut,
+    UserCreateIn,
+    UserOut,
+    UserQuery,
+    UserStatusIn,
+    UserUpdateIn,
+)
+from app.services import user_service
+
+router = APIRouter(prefix="/users", tags=["系统管理 · 用户"])
+
+
+@router.get("", response_model=ApiResponse[PageResult[UserOut]], summary="用户列表")
+def list_users(
+    session: DbSession,
+    _: AdminUser,
+    query: Annotated[UserQuery, Query()],
+) -> ApiResponse[PageResult[UserOut]]:
+    """分页查询用户，支持按用户名/姓名模糊、状态与角色筛选。"""
+    return ok(user_service.list_users(session, query))
+
+
+@router.get("/{user_id}", response_model=ApiResponse[UserOut], summary="用户详情")
+def get_user(
+    session: DbSession,
+    _: AdminUser,
+    user_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[UserOut]:
+    """查询用户详情。"""
+    return ok(user_service.get_user(session, user_id))
+
+
+@router.post("", response_model=ApiResponse[UserOut], summary="新增用户")
+def create_user(
+    session: DbSession,
+    _: AdminUser,
+    payload: UserCreateIn,
+) -> ApiResponse[UserOut]:
+    """新增用户。用户名须唯一，至少指定一个角色。"""
+    return ok(user_service.create_user(session, payload), message="用户已创建")
+
+
+@router.put("/{user_id}", response_model=ApiResponse[UserOut], summary="编辑用户")
+def update_user(
+    session: DbSession,
+    current_user: AdminUser,
+    user_id: Annotated[int, Path(ge=1)],
+    payload: UserUpdateIn,
+) -> ApiResponse[UserOut]:
+    """编辑用户的基本信息与角色。
+
+    **不含用户名与密码**：用户名是审计追溯的锚点；密码走专门的重置接口。
+    """
+    return ok(
+        user_service.update_user(session, user_id, payload, operator_id=current_user.id),
+        message="已保存",
+    )
+
+
+@router.delete("/{user_id}", response_model=ApiResponse[None], summary="删除用户")
+def delete_user(
+    session: DbSession,
+    current_user: AdminUser,
+    user_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[None]:
+    """删除用户。
+
+    物理删除。历史操作日志通过 `user_id` 置空 + 冗余用户名保留可追溯性。
+    业务上更推荐用「禁用」代替删除 —— 禁用保留完整审计线索。
+    """
+    user_service.delete_user(session, user_id, operator_id=current_user.id)
+    return ok(message="用户已删除")
+
+
+@router.put("/{user_id}/password", response_model=ApiResponse[None], summary="重置密码")
+def reset_password(
+    session: DbSession,
+    _: AdminUser,
+    user_id: Annotated[int, Path(ge=1)],
+    payload: PasswordResetIn,
+) -> ApiResponse[None]:
+    """重置用户密码。
+
+    会同时提升该用户的令牌版本，使其**已签发的令牌立即失效** ——
+    否则改密后旧令牌在有效期内仍可用。
+    """
+    user_service.reset_password(session, user_id, payload.new_password)
+    return ok(message="密码已重置，该用户需重新登录")
+
+
+@router.put("/{user_id}/status", response_model=ApiResponse[UserOut], summary="启用/禁用用户")
+def set_status(
+    session: DbSession,
+    current_user: AdminUser,
+    user_id: Annotated[int, Path(ge=1)],
+    payload: UserStatusIn,
+) -> ApiResponse[UserOut]:
+    """启用或禁用用户。
+
+    禁用会提升令牌版本使已签发令牌立即失效，否则被禁用者仍可凭旧令牌
+    继续访问直到过期（最长 2 小时）。
+    """
+    result = user_service.set_status(session, user_id, payload.status, operator_id=current_user.id)
+    return ok(result, message="已启用" if payload.status == 1 else "已禁用")
+
+
+@router.get("/meta/roles", response_model=ApiResponse[list[RoleOut]], summary="角色下拉选项")
+def list_roles(session: DbSession, _: AdminUser) -> ApiResponse[list[RoleOut]]:
+    """取全部启用角色，供用户表单的角色选择使用。
+
+    路径放在 `/users/meta/roles` 而非 `/roles`，是为了避免与
+    `/{user_id}` 的路由匹配冲突（`roles` 会被当成 user_id 解析而报 422）。
+    """
+    return ok(user_service.list_roles(session))