52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
## 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`
|