# 审计日志模块

## 概述

审计日志模块提供全面的系统操作审计功能，确保合规性和安全性。遵循 SOX 合规要求，支持操作追溯和完整性验证。

## 页面架构

### 主要页面

```
/audit                  - 审计概览（本页面）
/audit/logs             - 审计日志列表
/audit/logs/[id]        - 审计日志详情
/audit/search           - 高级搜索
/audit/statistics       - 统计分析
/audit/financial        - 财务审计
/audit/sensitive        - 敏感操作
/audit/integrity        - 完整性验证
```

## 审计概览页面 (`/audit`)

### 功能特性

1. **核心统计卡片**
   - 近 7 天操作总数 + 成功率
   - 财务操作数量
   - 敏感操作数量
   - 失败操作数量

2. **数据分析**
   - 模块分布（前 5 名）
   - 操作类型分布（前 6 名）
   - 每日趋势（最近 7 天）

3. **最近活动**
   - 最近 10 条审计日志
   - 实时状态显示
   - 快速跳转详情

4. **SOX 合规信息**
   - 加密存储提示
   - 完整性验证入口

### 设计风格

#### 1. 飞书风格设计系统

**颜色规范：**
```typescript
// 主色
primary: '#3370ff'        // 品牌蓝
primaryHover: '#1e5eff'   // 悬浮蓝

// 文字
textPrimary: '#1f2329'    // 主要文字
textSecondary: '#646a73'  // 次要文字
textTertiary: '#8f959e'   // 辅助文字

// 背景
bgPrimary: '#ffffff'      // 白色背景
bgSecondary: '#f7f8fa'    // 浅灰背景
bgHover: '#f7f8fa'        // 悬浮背景

// 边框
border: '#e5e6eb'         // 默认边框
borderHover: '#c9cdd4'    // 悬浮边框

// 状态色
success: '#00b42a'        // 成功（绿色）
error: '#f53f3f'          // 错误（红色）
warning: '#ff7d00'        // 警告（橙色）
info: '#3370ff'           // 信息（蓝色）
```

**渐变图标背景：**
- 蓝色：`linear-gradient(135deg, #3370ff 0%, #1e5eff 100%)`
- 绿色：`linear-gradient(135deg, #00b42a 0%, #009624 100%)`
- 橙色：`linear-gradient(135deg, #ff7d00 0%, #e66a00 100%)`
- 红色：`linear-gradient(135deg, #f53f3f 0%, #d63030 100%)`

#### 2. 布局规范

**标题栏：**
- 固定高度：`h-12` (48px)
- 背景：白色 + 底部边框
- 左侧：标题 + 描述
- 右侧：刷新按钮

**注意事项：**
- 边框必须在外层容器 `border-b`
- 高度容器在内层 `h-12`
- 这样确保所有标题栏视觉高度完全一致

**内容区域：**
- 背景色：`#f7f8fa`
- 内边距：`p-6`
- 间距：`space-y-6`

**卡片样式：**
```typescript
{
  backgroundColor: '#ffffff',
  border: '1px solid #e5e6eb',
  borderRadius: '8px',
  padding: '20px',
  // Hover 效果
  ':hover': {
    boxShadow: '0 4px 12px rgba(0, 0, 0, 0.08)',
    borderColor: '#c9cdd4',
  }
}
```

#### 3. 交互规范

**悬浮效果：**
- 卡片：阴影 + 边框颜色变化
- 按钮：背景色变化 + 文字颜色变化
- 装饰元素：缩放动画（`scale-125`）

**过渡动画：**
- 所有交互使用 `transition-all` 或 `transition-colors`
- 装饰元素使用 `transition-transform duration-500`
- 进度条使用 `transition-all duration-500`

**状态展示：**
- 加载中：旋转图标 + 提示文字
- 错误：错误图标 + 错误信息 + 重试按钮
- 空数据：图标 + 提示文字

### 数据流

```typescript
// 1. 页面加载
useEffect(() => {
  if (!isReady) return;
  loadData();
}, [isReady]);

// 2. 并行请求数据
const loadData = async () => {
  const [statsData, logsData] = await Promise.all([
    getStatistics({ startDate, endDate }),  // 统计数据
    getAuditLogs({ limit: 10 })             // 最近日志
  ]);
};

// 3. 数据处理
- 计算成功率
- 格式化相对时间
- 计算百分比
```

### API 依赖

#### 1. `getStatistics(params)`

获取审计统计数据。

**请求参数：**
```typescript
{
  startDate: string;  // ISO 格式
  endDate: string;    // ISO 格式
}
```

**响应数据：**
```typescript
{
  summary: {
    total: number;      // 总操作数
    success: number;    // 成功数
    failed: number;     // 失败数
    financial: number;  // 财务操作数
    sensitive: number;  // 敏感操作数
  },
  byModule: Array<{ module: string; count: number }>,
  byAction: Array<{ action: string; count: number }>,
  byDay: Array<{ date: string; count: number }>
}
```

#### 2. `getAuditLogs(params)`

获取审计日志列表。

**请求参数：**
```typescript
{
  limit?: number;        // 默认 20
  sortBy?: string;       // 默认 'when'
  sortOrder?: 'asc' | 'desc';  // 默认 'desc'
}
```

**响应数据：**
```typescript
{
  items: AuditLogItem[];
  total: number;
  page: number;
  limit: number;
}
```

### 国际化

使用 `useTranslation` hook 获取翻译：

```typescript
const { t, locale } = useTranslation();

// 中文
t.audit?.overview?.title        // '审计概览'
t.audit?.financial?.title       // '财务操作'
t.audit?.sensitive?.title       // '敏感操作'

// 英文（locale === 'en'）
t.audit?.overview?.title        // 'Audit Overview'
```

### 权限控制

审计概览页面权限要求：`audit:read`

```typescript
// 在 layout.tsx 中配置
{
  id: 'overview',
  path: '/audit',
  requirePermission: 'audit:read',
}
```

### 响应式设计

```typescript
// 统计卡片
grid-cols-1 md:grid-cols-2 lg:grid-cols-4

// 数据分析
grid-cols-1 lg:grid-cols-3
```

### 性能优化

1. **并行请求**
   ```typescript
   await Promise.all([getStatistics(), getAuditLogs()]);
   ```

2. **条件渲染**
   - 使用 `isReady` 避免重复请求
   - 空数据提示减少 DOM 渲染

3. **事件优化**
   - 使用 inline style 而非 class 切换（避免 class 计算）
   - 悬浮效果使用 `onMouseEnter/Leave`

### 错误处理

```typescript
try {
  // API 调用
} catch (err) {
  if (err instanceof ApiClientError) {
    setError(err.message);
  } else {
    setError('加载审计数据失败');
  }
}
```

### 测试要点

1. **数据加载**
   - 验证并行请求
   - 验证加载状态
   - 验证错误处理

2. **交互功能**
   - 点击卡片跳转
   - 刷新按钮
   - 日志详情跳转

3. **样式效果**
   - Hover 悬浮效果
   - 装饰动画
   - 响应式布局

4. **国际化**
   - 中英文切换
   - 日期格式
   - 相对时间

## 开发规范

### 1. 文件命名
- 页面文件：`page.tsx`
- 布局文件：`layout.tsx`
- 组件文件：`PascalCase.tsx`

### 2. 样式规范
- 使用 Tailwind CSS utility classes
- 飞书颜色系统使用 inline style
- 避免自定义 CSS 类

### 3. TypeScript
- 所有 props 必须定义类型
- API 响应使用接口定义
- 避免使用 `any`

### 4. 注释规范
```typescript
/**
 * 组件/函数描述
 * 功能说明
 */
```

## 相关文档

- [审计系统架构](../../../../../docs/modules/audit-system/README.md)
- [审计系统 API](../../../../../docs/modules/audit-system/07-api.md)
- [前端架构规范](../../../../../docs/standards/02-architecture/frontend-architecture.md)
- [导航架构规范](../../../../../docs/standards/02-architecture/app-navigation-architecture.md)