shanxia2.0/openspec/changes/operation-audit-enhancement/proposal.md

Why

客户要求系统中用户操作可追溯：记录请求人姓名、请求时间、接口地址、入参与出参。shanxia2.0 已通过 ApiRequestLogMiddleware 写入 sys_api_request_log，但请求人多为账号而非姓名、缺少全局管理页、业务语义弱、无法按业务单据精确查询。

What Changes

增强现有 API 请求日志

1. 中间件补齐 — JWT 解析 real_name → create_name；tenant_no 落库；异步写库行为保持
2. 业务语义字段 — business_title、business_type、business_id、oper_summary（写操作由 @oper_log 声明，只读走路径推断兜底）
3. ContextVar + 装饰器 — app/core/context.py 扩展；@oper_log 供路由/写接口标注模块、类型、业务主键与摘要

查询与管理

4. operlog API 增强 — 列表/详情优先读落库语义字段；支持按 business_id、business_title、business_type 筛选
5. 操作日志管理页 — web-admin 标准列表（P01），admin / super_admin 可查；详情展示入参/出参
6. CRM 嵌入 Tab 优化 — 客户/合同详情按 business_id 查日志，不再拉全量前端过滤

数据库

7. 表结构扩展 — sys_api_request_log、sys_api_request_log_his 增加语义列与 tenant_no、索引
8. 迁移脚本 — docs/sql/migrations/2026-06-29-operation-audit.sql；同步 docs/sql/shanxia2.0.sql

非本期（文档标注为后续）

• 定时归档至 sys_api_request_log_his
• 可配置高频只读 API 排除规则
• 全模块 @oper_log 覆盖（本期优先 CRM 写接口 + 样例）

Capabilities

New Capabilities

• operation-audit: API 全量请求审计与业务语义操作日志

Modified Capabilities

• （无独立基线 spec 变更；实现须符合 zkxw-engineering-standards 中 api/database/ui/permission conventions）

Impact

• 后端：api_request_log_middleware.py、context.py、新 oper_log 装饰器、oper_log.py CRUD、monitor.py、ORM、schemas
• 前端：新 views/system/operlog/（或 monitor/operlog/）、路由、菜单；CRM 详情 Tab 查询参数
• 配置：API_REQUEST_LOG_ENABLED 生产须为 true

Reference

• 现有中间件：backend/app/core/api_request_log_middleware.py
• 现有 operlog 适配：backend/app/crud/monitor/oper_log.py
• 设计文档：docs/superpowers/specs/2026-06-29-operation-audit-design.md
• RuoYi 对照：docs/sql/sx.sql → sys_oper_log