# 管理员操作审计功能设计

## 1. 目标

统一使用 `tms_operation_audit_log` 记录所有敏感管理员操作，覆盖：

- 登录、登出
- 增删改
- 执行类操作：初始化、重置、升级、回滚、重启、密钥操作
- 非法操作：拒绝访问、权限不足、重放、签名失败等

设计原则：

- 只保留一张日志表
- 敏感操作日志写入失败时，业务直接失败
- 日志在落库前完成 `SM3` 摘要与 `SM2` 签名
- 人工审计字段不参与首签

## 2. 表结构

表名：`tms_operation_audit_log`

```sql
CREATE TABLE IF NOT EXISTS tms_operation_audit_log (
    id BIGINT PRIMARY KEY,
    log_id VARCHAR(64) NOT NULL COMMENT '日志唯一标识',
    operator_role_code VARCHAR(64) NOT NULL COMMENT '操作角色编码',
    operator_auth_level VARCHAR(32) NULL COMMENT '操作时认证等级',
    module_code VARCHAR(32) NOT NULL COMMENT '业务模块',
    action_type VARCHAR(32) NOT NULL COMMENT '操作动作',
    remote_ip VARCHAR(64) NULL COMMENT '来源IP',
    operation_result VARCHAR(16) NOT NULL COMMENT '操作结果: SUCCESS/FAILED/DENIED',
    summary VARCHAR(512) NOT NULL COMMENT '操作摘要',
    error_message VARCHAR(1024) NULL COMMENT '失败原因',
    audit_status VARCHAR(16) NOT NULL COMMENT '审计状态: PENDING/REVIEWED',
    audit_result VARCHAR(16) NULL COMMENT '审计结果: PASS/REJECT/NEED_VERIFY',
    audit_comment VARCHAR(1024) NULL COMMENT '审计意见',
    audited_by VARCHAR(64) NULL COMMENT '审计人',
    audited_at DATETIME(3) NULL COMMENT '审计时间',
    payload_hash VARCHAR(128) NOT NULL COMMENT 'SM3摘要',
    sign_value TEXT NOT NULL COMMENT 'SM2签名值',
    occurred_at DATETIME(3) NOT NULL COMMENT '操作发生时间',
    create_time DATETIME(3) NOT NULL COMMENT '落库时间',
    UNIQUE KEY uk_tms_operation_audit_log_log_id (log_id),
    KEY idx_tms_operation_audit_log_role_code (operator_role_code),
    KEY idx_tms_operation_audit_log_module_code (module_code),
    KEY idx_tms_operation_audit_log_action_type (action_type),
    KEY idx_tms_operation_audit_log_result (operation_result),
    KEY idx_tms_operation_audit_log_audit_status (audit_status),
    KEY idx_tms_operation_audit_log_occurred_at (occurred_at)
);
```

## 3. 枚举设计

### 3.1 `module_code`

- `AUTH`
- `INIT`
- `UPGRADE`
- `DEVICE`
- `NETWORK`
- `KEY`
- `SYSTEM`
- `SECURITY`

### 3.2 `action_type`

- `LOGIN`
- `LOGOUT`
- `CREATE`
- `UPDATE`
- `DELETE`
- `EXECUTE`
- `RESET`
- `ENABLE`
- `DISABLE`
- `BIND`
- `IMPORT`
- `EXPORT`
- `BACKUP`
- `RECOVER`
- `RESTART`
- `ACCESS`

### 3.3 `operation_result`

- `SUCCESS`
- `FAILED`
- `DENIED`

### 3.4 `audit_status`

- `PENDING`
- `REVIEWED`

### 3.5 `audit_result`

- `PASS`
- `REJECT`
- `NEED_VERIFY`

## 4. 摘要与签名

### 4.1 首签字段

入库前参与 `payload_hash` 和 `sign_value` 计算的字段：

- `log_id`
- `operator_role_code`
- `operator_auth_level`
- `module_code`
- `action_type`
- `remote_ip`
- `operation_result`
- `summary`
- `occurred_at`

### 4.2 不参与首签的字段

以下字段属于后续审计动作或补充信息，不参与首签：

- `audit_status`
- `audit_result`
- `audit_comment`
- `audited_by`
- `audited_at`
- `error_message`

### 4.3 规范化串

建议按固定字段顺序拼接：

```text
log_id=...
operator_role_code=...
operator_auth_level=...
module_code=...
action_type=...
remote_ip=...
operation_result=...
summary=...
occurred_at=...
```

规范要求：

- 字段顺序固定
- `null` 统一为空串
- 首尾空格统一裁剪
- 时间统一使用 UTC 与固定格式

### 4.4 签名流程

1. 构造 `canonical_payload`
2. 计算 `payload_hash = SM3(canonical_payload)`
3. 计算 `sign_value = SM2(privateKey, canonical_payload)`
4. 一次性写入数据库

## 5. Java 设计草案

核心对象：

- `OperationAuditLogEntity`
- `OperationAuditLogRepository`
- `OperationAuditService`
- `OperationAuditCommand`
- `OperationAuditSigner`

服务接口建议：

```java
public interface OperationAuditService {

    void record(OperationAuditCommand command);

    void review(String logId, AuditResult auditResult, String auditComment, String auditedBy);
}
```

`OperationAuditCommand` 建议字段：

- `operatorRoleCode`
- `operatorAuthLevel`
- `moduleCode`
- `actionType`
- `remoteIp`
- `operationResult`
- `summary`
- `errorMessage`

## 6. 日志记录流程

统一入口：`OperationAuditService.record(...)`

处理流程：

1. 业务侧提交 `OperationAuditCommand`
2. 服务补齐：
   - `log_id`
   - `occurred_at`
   - `audit_status = PENDING`
3. 生成 `payload_hash` 与 `sign_value`
4. 插入 `tms_operation_audit_log`
5. 若插入失败：
   - 对敏感操作直接抛异常，业务失败

## 7. 注解与 AOP 接入方案

### 7.1 注解定义

```java
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface AuditedOperation {

    String module();

    String action();

    String summary() default "";

    boolean sensitive() default true;
}
```

### 7.2 AOP 职责

切面负责：

- 读取注解元数据
- 从请求上下文提取：
  - 当前角色
  - 当前认证等级
  - 来源 IP
- 环绕执行目标方法
- 成功时记录 `SUCCESS`
- 捕获业务异常时记录 `FAILED`
- 捕获权限或安全拒绝时记录 `DENIED`
- 对 `sensitive = true` 的操作，日志写入失败时重新抛错

### 7.3 设计原则

- AOP 负责公共字段、结果判定和统一落库
- 业务方法负责提供准确的 `summary`
- 不在 AOP 中自动抓取完整请求参数，避免日志带入密码、令牌、密钥材料等敏感数据

## 8. 接口清单

### 8.1 首批需要接入审计的接口

#### 认证与角色管理

- `POST /api/v1/auth/password-login`
- `POST /api/v1/auth/ukey-login`
- `POST /api/v1/auth/logout`
- `POST /api/v1/auth/change-password`
- `POST /api/v1/auth/roles/{roleCode}/enable`
- `POST /api/v1/auth/roles/{roleCode}/reset-password`
- `POST /api/v1/auth/roles/{roleCode}/ukeys/bind`

#### 初始化与重置

- `POST /api/v1/init/tasks`
- `POST /api/v1/init/tasks/{taskId}/execute`
- `POST /api/v1/init/reset/tasks`
- `POST /api/v1/init/reset/tasks/{taskId}/execute`

#### 升级管理

- `POST /api/v1/upgrades`
- `POST /api/v1/upgrades/{taskId}/execute`
- `POST /api/v1/upgrades/{taskId}/rollback`

#### 设备与网络

- `POST /api/v1/device/restart`
- 网络配置写接口
- IP 白名单增删改接口

#### 密钥与密码卡

- LMK / IK / UKey / 密钥导入导出、备份恢复、销毁相关写接口

#### 安全事件

- 认证失败
- 权限不足
- 重放拦截
- 签名校验失败

### 8.2 日志分页查询接口

- `GET /api/v1/audit-logs`

查询条件：

- `operatorRoleCode`
- `moduleCode`
- `actionType`
- `operationResult`
- `auditStatus`
- `auditResult`
- `remoteIp`
- `dateFrom`
- `dateTo`
- `keyword`

默认排序：

- `occurred_at DESC`

### 8.3 日志详情接口

- `GET /api/v1/audit-logs/{logId}`

详情建议返回：

- 基础日志字段
- 审计字段
- `payload_hash`
- `sign_value`

### 8.4 日志审计接口

- `POST /api/v1/audit-logs/{logId}/review`

请求示例：

```json
{
  "auditResult": "PASS",
  "auditComment": "复核通过"
}
```

更新规则：

- 仅审计管理员可操作
- 仅允许 `PENDING -> REVIEWED`
- 更新字段：
  - `audit_status`
  - `audit_result`
  - `audit_comment`
  - `audited_by`
  - `audited_at`

## 9. 失败策略

敏感操作统一采用失败关闭：

- 审计日志写入失败，业务直接失败

敏感操作范围包括：

- 登录与登出
- 角色管理
- 口令变更
- UKey 管理
- 初始化与重置
- 升级与回滚
- 网络配置
- 白名单变更
- 密钥与密码卡操作
- 安全拦截事件

## 10. 推荐实现顺序

1. Flyway 建表，删除旧 `tms_auth_audit_log` / `tms_security_event`
2. 增加枚举、Entity、Repository
3. 增加 `OperationAuditSigner`（SM3 / SM2）
4. 增加 `OperationAuditService`
5. 增加 `@AuditedOperation` 与 AOP
6. 增加分页查询与详情接口
7. 增加审计接口
8. 在首批敏感接口上补齐注解与摘要