feat(system): 完成后端系统管理（审计/角色/操作日志/日志查询）

- 操作日志审计机制：audit 上下文（成功与失败都记、独立提交、操作人标量
  固化、commit 后查询前置约定），用户/角色全部写操作接入；request_data
  按键名的结构化脱敏 + UTF-8 字节边界截断
- 角色管理：CRUD 与启停；admin 禁删禁停、有绑定禁删（FOR UPDATE 锁行）、
  编码创建后不可改、停用角色不可再分配
- 日志查询：操作/登录两端点，列表与详情两段式（详情含已脱敏请求参数）；
  时间参数统一转本地 naive（修混用时区 500 与偏移丢弃）
- 用户管理：补齐 reset_password 操作人、编辑空串归一 NULL、并发唯一键兜底 400
- 测试 301 例全绿（单元 223 / 集成 78）

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

backend/README.md

@@ -1,11 +1,12 @@
 # 后端
 
-> AI摘要：衍水集团营销人员工资管理系统的后端服务。FastAPI + SQLAlchemy（同步）+ MySQL + Redis，Python 3.12 由 uv 锁定。六层结构 `api / services / repositories / models / schemas / core`。当前实现登录鉴权与健康检查，业务模块待需求澄清后开发。
+> AI摘要：衍水集团营销人员工资管理系统的后端服务。FastAPI + SQLAlchemy（同步）+ MySQL + Redis，Python 3.12 由 uv 锁定。六层结构 `api / services / repositories / models / schemas / core`。当前实现登录鉴权与系统管理（用户/角色/操作日志/日志查询），业务模块待需求澄清后开发。
 
 ## 职责
 
 - 提供 REST 接口（统一前缀 `/api`）
 - 登录鉴权：图形验证码、JWT、登录限流、登出黑名单、登录日志
+- 系统管理（需求 2.5.1）：用户管理、角色管理、操作日志（自动审计）、操作与登录日志查询
 - 后续承担：基础数据、业务数据、绩效核算、报表统计、T+ 数据同步
 
 ## 技术栈与版本
@@ -53,6 +54,24 @@ app/
 | POST | `/api/v1/auth/logout` | 是 | 令牌入黑名单，立即失效 |
 | GET | `/api/v1/auth/me` | 是 | 当前用户与角色 |
 
+### 系统管理接口（需求 2.5.1，全部要求管理员权限）
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET / POST | `/api/v1/system/users` | 用户列表（分页/筛选）/ 新增用户 |
+| GET / PUT / DELETE | `/api/v1/system/users/{id}` | 用户详情 / 编辑（含角色分配）/ 删除（物理删除） |
+| PUT | `/api/v1/system/users/{id}/password` | 重置密码（提升令牌版本，旧令牌立即失效） |
+| PUT | `/api/v1/system/users/{id}/status` | 启用 / 禁用（禁用同样提升令牌版本） |
+| GET | `/api/v1/system/users/meta/roles` | 角色下拉选项（仅启用角色） |
+| GET / POST | `/api/v1/system/roles` | 角色列表（含停用与绑定用户数）/ 新增角色 |
+| PUT / DELETE | `/api/v1/system/roles/{id}` | 编辑（不含编码）/ 删除（内置与有绑定的角色受保护） |
+| PUT | `/api/v1/system/roles/{id}/status` | 启用 / 禁用（内置 admin 禁停） |
+| GET | `/api/v1/system/operation-logs` | 操作日志查询（操作人/模块/操作/结果/时间范围；**不含 request_data** 大字段） |
+| GET | `/api/v1/system/operation-logs/{id}` | 操作日志详情（含已脱敏的请求参数，展开行懒加载） |
+| GET | `/api/v1/system/login-logs` | 登录日志查询（用户名/IP/结果/时间范围） |
+
+全部写操作自动写入操作日志（成功与失败都记，机制见下）。
+
 统一响应 `{code, message, data}`，分页为 `list/total/pageNum/pageSize`。
 状态码：400 参数错误 / 401 未登录 / 403 无权限 / 404 不存在 / 500 服务端异常。
 
@@ -118,6 +137,22 @@ Redis 黑名单只负责「用户主动登出」。
 bcrypt 5.0 起对超过 72 字节的密码**直接抛 ValueError**（此前是静默截断）。
 中文一个字符占 3 字节，24 个汉字即到顶——`max_length=20` 这类字符数校验拦不住。
 
+### 操作日志：审计上下文 + 独立提交
+
+写操作统一经 `services/audit_service.py` 的 `audit()` 上下文管理器留痕（用法见 `api/v1/system/users.py`）：
+
+- 调用形态为 DTO：`audit(session, operator=..., record=AuditRecord(module, action, summary, request_data), meta=...)`；落库条目为 `OperationLogEntry`
+- 正常退出记成功；抛异常**先 `session.rollback()` 再**记失败（success=0 + 中文错误原因），随后原异常继续传播
+- 日志**独立 commit**，整体兜底不外抛 —— 方向是「审计可丢，业务不可断」；反向理解：业务失败回滚不会带走失败记录，而那正是审计最需要的
+- **操作人标量在进入上下文时固化**：失败路径先 rollback 会使 ORM 对象过期，之后再读 id/username 会触发额外查询（账号并发被删时 ObjectDeletedError 还会被兜底吞掉）
+- 请求元信息（ip / user-agent / method / path）经路由层的 `RequestMetaDep` 传入 service
+- **commit 之后的任何查询/ORM 读取都要前置**（提到 commit 前或用已固化的局部变量）：业务已提交却因后置查询抛错会被记成「失败」，产生与事实相反的审计
+- 文本列按 `models/operation_log.py` 的长度常量截断；`request_data` 先经**结构化脱敏**（递归按键名整值抹除 password/token 等，不依赖文本模式匹配）再经 `core.logging.scrub` 文本兜底，最后按 **UTF-8 字节边界**截断（encode 带 `errors="replace"` 兜底孤立代理字符）—— 超长/编码异常都会在 MySQL 或 encode 处抛出，被兜底吞掉后表现为「日志莫名消失」
+- **日志列表与详情两段式**：`operation-logs` 列表排除 `request_data`（TEXT 大字段，随列表返回会让翻页负担随表增长），展开详情走 `GET /operation-logs/{id}` 懒加载
+- 模块/操作词表在 `core/constants.py`（`MODULE_*` / `ACTION_*`），前端 `utils/constants.ts` 与其对齐
+
+**角色管理保护规则**（后端是唯一防线，前端按钮禁用只是体验）：admin 角色禁删禁停；有用户绑定的角色禁删（`user_roles` 外键是 CASCADE；删除前走 `SELECT ... FOR UPDATE` 锁行，堵住并发绑定窗口）；`role_code` 创建后不可改；**停用角色不可再分配**（`_resolve_roles` 校验 status，停用只影响新分配、不影响既有授权）。
+
 ## 常见问题
 
 **起服务报 `APP_SECRET_KEY` 相关错误** —— `backend/.env` 未填或不足 32 字符。这是刻意的 fail-fast：空密钥签发 JWT 是安全问题，必须启动即失败。