package jnpf.audit.sdk.annotation;
|
|
import jnpf.audit.AuditConsts;
|
|
import java.lang.annotation.ElementType;
|
import java.lang.annotation.Retention;
|
import java.lang.annotation.RetentionPolicy;
|
import java.lang.annotation.Target;
|
|
/**
|
* 层 2 审计注解：给非 CRUD 动作或需要精确动作名的场景一行声明语义。
|
*
|
* <p>与 lims 旧 {@code @BizLog} 的关系（M2 影子期）：**并存不互斥**，同方法双标注、各写各表，
|
* 靠 operationId 精确配对做 A/B；M3 达标后才删旧的。
|
*
|
* <p>已知限制沿袭：同类自调用绕开代理时注解不生效（与 @BizLog 同）。
|
*/
|
@Target(ElementType.METHOD)
|
@Retention(RetentionPolicy.RUNTIME)
|
public @interface AuditLog {
|
|
/** 事件类型，受控枚举（DATA_CHANGE / BIZ_ACTION / E_SIGNATURE），默认业务动作 */
|
String eventType() default AuditConsts.TYPE_BIZ_ACTION;
|
|
/** 动作码：基础三动作 CREATE/UPDATE/DELETE 或业务自定义大写蛇形 */
|
String action();
|
|
/**
|
* 方法抛异常时用这个动作码记一条**失败事件**；留空（默认）= 抛异常时不记录。
|
*
|
* <p>默认留空是为了**向后兼容**：M2 已有的层 2 埋点行为一字不变（只在成功后记录）。
|
* 想要"失败也留痕"的场景（电子签名、权限校验、密码修改等）显式声明即可，
|
* 例如 {@code action="SIGN", failureAction="SIGN_FAIL"}。
|
*
|
* <p>为什么拆成两个动作码而不是共用一个加标记：`audit_events` 上有
|
* {@code idx_audit_events_action_code} 索引，按动作码筛是最快路径；而"签名失败尝试"
|
* 在合规上是独立关注对象（连续失败可能是有人在试密码）。共用一个码就只能去 extra
|
* 的 text 列里捞。
|
*
|
* <p>⚠️ 失败事件求值时 {@code #result} 恒为 null（方法没有返回值）。凡引用了
|
* {@code #result} 的 SpEL 在失败路径上取不到值——切面对**每个字段单独兜底**
|
* （求值异常只丢该字段并 WARN，不会丢掉整条事件），但写表达式时优先用安全导航
|
* {@code #result?.id}，让意图显式。
|
*/
|
String failureAction() default "";
|
|
/** 失败事件的人读动作名，留空则回落 {@link #failureAction()} */
|
String failureLabel() default "";
|
|
/**
|
* 成功时是否记录事件。默认 true（M2 既有埋点行为一字不变）。
|
*
|
* <p>声明 {@code false} 的唯一正当场景是：<b>成功事实要由别处更完整地记录</b>。
|
* 当前只有电子签名——签名成功当场落库会产生「签名有记录、业务失败没记录」的孤儿行，
|
* 药厂合规上不接受（签名 + 业务是一个整体）。成功侧改由层 0 在<b>业务保存成功后</b>
|
* 据表单里的签名字段补写，失败侧（{@code SIGN_FAIL}）仍在此记录——
|
* 失败的签名尝试是独立的安全关注对象（连续失败可能是有人在试密码），
|
* 它不隶属于任何一次成功业务，没有"跟着业务一起不记"的道理。
|
*
|
* <p>⚠️ 声明 false 前必须先确认成功事实<b>确实</b>有另一条链路在记。
|
* 否则这就是在静默地删掉一个埋点。
|
*/
|
boolean recordSuccess() default true;
|
|
/**
|
* {@link #bizCodeExpr()} 求值为空时是否**跳过**记录。默认 true（保持 M2 原行为）。
|
*
|
* <p>声明 {@code false} 表示"没有业务单号也照记"——审计红线是**这次操作发生过不能缺**，
|
* bizCode 只是便于检索。层 0 早就是这个取舍（见 {@code AuditVisualLogListener} 类注释：
|
* 旧实现取不到单号就整条丢弃，新实现留空照记）。
|
*
|
* <p>典型场景：**电子签名**。签名往往先于业务对象存在（先签名拿 biz_sign、再创建请验单），
|
* 此时 dataId 天然为空。留着默认 true 会让签名事件被静默跳过、只在日志里留一行 WARN。
|
*/
|
boolean bizCodeRequired() default true;
|
|
/** 人读动作名，如"请验单 撤回" */
|
String label() default "";
|
|
/** 业务对象类型（对应 audit_events.biz_type） */
|
String bizType() default "";
|
|
/** 业务单号 SpEL，如 {@code "#qingyandan.jianyanLiushuihao"}；求值为空则跳过记录并告警 */
|
String bizCodeExpr();
|
|
/** 附加元数据 SpEL，求值结果须为 Map；写进 audit_events.extra */
|
String extraExpr() default "";
|
|
/**
|
* 操作原因 SpEL，写进 {@code audit_events.reason} 独立列。典型是用户在界面填的
|
* "说明 / 原因"（如签名的 note、退回的原因）。成功与失败**都求值**（它取自入参，失败时同样在）。
|
*
|
* <p>🔴 **本列的语义固定为"操作者陈述的业务原因"，不随成败切换含义**。失败的技术原因
|
* （异常 message）由切面写进 {@code extra.failureReason}，不占用本列——否则查询侧
|
* 拿到一个 reason 值时无法判断它是"用户填的"还是"系统报的"，这一列就没法解释了。
|
*/
|
String reasonExpr() default "";
|
|
/** 目标表名（对应 audit_events.target_table） */
|
String targetTable() default "";
|
|
/** 目标行主键 SpEL（对应 audit_events.target_id） */
|
String targetIdExpr() default "";
|
|
/**
|
* 批量目标主键 SpEL，结果可为 Collection、Iterable、数组或逗号分隔字符串。
|
*
|
* <p>配置后，切面对每个主键分别查询修改前后数据，并在每个 field_diffs 项中写入
|
* targetTable/targetId。事件顶层 target_id 仍由 targetIdExpr 决定，通常取第一条。
|
*/
|
String targetIdsExpr() default "";
|
|
/** 是否做字段级 diff；true 时 entityClass + targetIdExpr/targetIdsExpr 至少配置一项 */
|
boolean diff() default false;
|
|
/** diff=true 时用于反射定位 Mapper 的实体类 */
|
Class<?> entityClass() default Void.class;
|
|
}
|
