---
description: 若依框架操作日志注解 @ApiAccessLog 使用规范
globs: ["**/controller/**/*.java"]
alwaysApply: false
---
# 冲突优先级声明
Controller三层规范、Java编码规范优先级高于本文件。

# 操作日志 @ApiAccessLog 使用规范
## 一、注解基础说明
使用若依内置注解 `@ApiAccessLog`，自动记录操作人、操作时间、接口地址、请求参数、操作类型、耗时，满足信创等保审计日志要求。

## 二、注解必填属性规范
1. title：必填，模块业务中文名称，例："商品管理"；
2. operateType：操作类型枚举，可选值：
    - CREATE：新增
    - UPDATE：编辑修改
    - DELETE：删除
    - EXPORT：导出Excel
    - QUERY：查询（分页/详情）
3. saveRequestData：布尔值，默认true，记录请求参数；敏感接口（含身份证、手机号）设置为false，防止日志泄露隐私。

## 三、接口注解使用强制规则
1. 以下接口**必须添加@ApiAccessLog**：
    - POST /create 新增
    - PUT /update 编辑
    - DELETE /delete 删除
    - GET /export-excel 导出
2. 查询接口（分页、详情）按需添加，内部管理系统建议全部记录；APP端普通查询可省略日志注解；
3. 注解仅允许添加在Controller接口方法上，禁止在Service、Mapper层使用。

## 四、日志脱敏规范
1. 接口参数包含手机号、身份证、银行卡、家庭地址等敏感字段时：
    1. @ApiAccessLog(saveRequestData = false) 关闭参数记录；
    2. 或全局配置日志脱敏规则，自动隐藏敏感信息中间字符；
2. 生产环境日志持久化存储，保留至少6个月审计日志，符合信创等保三级要求。

## 五、禁止事项
❌ 新增/修改/删除/导出接口不添加操作日志注解；
❌ 在Service、Mapper、Convert等非Controller层使用日志注解；
❌ 敏感隐私接口完整记录明文身份证、手机号；
❌ 自定义日志打印替代框架统一@ApiAccessLog日志，分散审计日志。
