# 日志系统模块（Logging System）

> **负责人**: FFOA 开发团队  
> **模块标识**: `logging`  
> **状态**: ✅ 已完成（v1.2.0）  
> **最后更新**: 2025-12-25

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2025-12-18 |
| [架构设计](./03-architecture.md) | ✅ | 2025-12-12 |
| [API 接口文档](./07-api.md) | ✅ | 2025-12-12 |
| [开发路线图](./10-roadmap.md) | ✅ | 2025-12-25 |
| [使用指南](./11-user-guide.md) | ✅ | 2026-05-11 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

---

## 📌 概述

日志系统是 FFOA 平台的技术基础设施模块，负责记录应用运行时的各类日志信息，支撑开发调试、运维监控和问题排查。

### 核心功能

| 功能 | 状态 | 说明 |
|------|------|------|
| HTTP 请求/响应日志 | ✅ | 自动记录所有 API 调用 |
| 错误日志和堆栈追踪 | ✅ | 含详细错误响应 |
| RequestID 追踪 | ✅ | 单请求链路追踪 |
| 敏感数据脱敏 | ✅ | password、token 等自动脱敏 |
| 日志轮转和清理 | ✅ | 按日期自动轮转 |
| 分布式追踪 | ✅ | traceId/spanId 跨服务追踪 |
| 日志采样 | ✅ | 大流量时按比例采样 |
| 告警机制 | ✅ | 慢请求/高错误率告警 |
| Temporal 工作流日志 | ✅ | Activity/Workflow 日志 |
| 数据库存储 | ✅ | PostgreSQL 持久化 |
| 日志管理 API | ✅ | 查询、统计、配置接口 |

### 业务价值

- **开发调试**: 详细的请求/响应日志，快速定位问题
- **运维监控**: 实时监控系统运行状态，及时发现异常
- **问题排查**: 全链路追踪，快速还原问题现场
- **合规审计**: 日志持久化存储，满足审计要求

---

## 🏗️ 技术信息

### 代码位置

- **后端**: `backend/src/core/observability/logging/`
  - config/ - Winston 日志配置
  - services/ - 日志服务
  - interceptors/ - HTTP 日志拦截器
  - logs.controller.ts - 日志管理 API
- **数据库**: `SystemLog`, `LogConfig`, `LogAlert`, `LogCleanupRecord` 表

### API 端点

- **Base URL**: `/api/v1/logs`
- **权限前缀**: `logs:`
- **主要接口**: 
  - 查询日志: GET `/api/v1/logs/query`
  - 统计分析: GET `/api/v1/logs/stats`
  - 配置管理: GET/PUT `/api/v1/logs/config`
  - 追踪查询: GET `/api/v1/logs/trace/:traceId`
- **总计**: 11个接口

### 技术栈

- **日志框架**: Winston
- **存储**: PostgreSQL + 文件系统
- **追踪**: 分布式追踪（traceId/spanId）
- **告警**: 慢请求/高错误率监控
- **采样**: 动态采样策略

### 日志文件结构

```
backend/logs/
├── application-YYYY-MM-DD.log    # 所有日志
├── error-YYYY-MM-DD.log          # 仅错误
└── http/
    └── http-YYYY-MM-DD.log       # HTTP 请求/响应
```

### 保留策略

| 日志类型 | 保留时间 | 单文件大小 |
|----------|----------|------------|
| application | 30 天 | 20MB |
| error | 30 天 | 20MB |
| http | 14 天 | 50MB |

---

## 🔗 相关模块

### 核心依赖

- **PostgreSQL** - 日志持久化存储
- **Winston** - 日志框架

### 被依赖模块

- 所有后端模块都依赖日志系统进行日志记录

### 业务关联

- [审计系统](../audit-system/README.md) - 业务合规审计（保留期更长）

---

## 📊 与审计系统的关系

| 维度 | 日志系统 | 审计系统 |
|------|----------|----------|
| 定位 | 技术运维 | 业务合规 |
| 保留期 | 14-30 天 | 3-7 年 |
| 可修改 | 可清理 | 不可删除 |
| 合规 | 无特殊要求 | SOX 合规 |

---

## 🚀 快速开始

### 开发环境

```bash
cd backend
NODE_ENV=development LOG_LEVEL=debug npm run start:dev
```

### 查看日志

```bash
# 实时查看 HTTP 日志
tail -f logs/http/http-$(date +%Y-%m-%d).log

# 查看错误日志
cat logs/error-$(date +%Y-%m-%d).log

# 通过 RequestID 追踪
grep "1763256789-abc123" logs/http/*.log
```

### 日志格式

```
📥 [RequestID] POST /api/v1/users | User: admin(user-001) | IP: 192.168.1.100
✅ [RequestID] POST /api/v1/users | 201 | 234ms | User: admin(user-001)
```

---

## ⚙️ 配置说明

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `NODE_ENV` | `development` | 环境 |
| `LOG_LEVEL` | `info` | 日志级别：error/warn/info/debug |
| `LOG_REGION` | `LOCAL` | 区域标识：CN/US/UAE |
| `LOG_SERVICE` | `APP` | 服务标识 |

### 日志级别

| 级别 | 请求信息 | Body/Query | 响应数据 | 错误堆栈 |
|------|---------|-----------|---------|---------|
| `error` | ❌ | ❌ | ❌ | ✅ |
| `info` | ✅ | ❌ | ❌ | ❌ |
| `debug` | ✅ | ✅ | ✅ | ✅ |

---

## 🛠️ 常用命令

```bash
# 查找慢请求（>2秒）
grep "ms" logs/http/http-$(date +%Y-%m-%d).log | \
  awk -F'|' '$3 ~ /[0-9]+ms/ {split($3, a, "ms"); if(a[1] > 2000) print}'

# 统计错误数量
grep -c "❌" logs/http/http-$(date +%Y-%m-%d).log

# 统计用户请求
grep "User:" logs/http/*.log | awk '{print $8}' | sort | uniq -c | sort -rn

# Top 10 API
grep "📥" logs/http/http-$(date +%Y-%m-%d).log | \
  awk '{print $5}' | sort | uniq -c | sort -rn | head -10
```

---

## 🧪 测试

### 服务清单

| 服务 | 文件 | 职责 |
|------|------|------|
| LoggerService | logger.service.ts | 框架核心日志服务 |
| AppLogger | app-logger.service.ts | 业务日志服务（推荐使用） |
| LogWriterService | log-writer.service.ts | 异步写入数据库 |
| LogManagementService | log-management.service.ts | 日志查询、配置、统计 |
| LogCleanupService | log-cleanup.service.ts | 定时清理过期日志 |
| TraceContextService | trace-context.service.ts | 分布式追踪上下文 |
| SamplingService | sampling.service.ts | 日志采样策略 |
| AlertService | alert.service.ts | 告警监控 |
| StructuredLoggerService | structured-logger.service.ts | JSON 结构化日志 |
| TemporalLoggerService | temporal-logger.service.ts | Temporal 工作流日志 |
| LoggingInterceptor | logging.interceptor.ts | HTTP 日志拦截器 |
| LogsController | logs.controller.ts | 日志管理 API |

---

## 📚 详细文档

- [产品需求文档](./01-prd.md) - 完整功能需求、业务场景
- [架构设计](./03-architecture.md) - 技术架构、数据库设计
- [API 接口文档](./07-api.md) - 日志管理 API 详细定义
- [开发路线图](./10-roadmap.md) - 开发进度、里程碑

---

## 🎯 开发状态

### 已完成（v1.2.0）

- ✅ 基础 HTTP 日志记录
- ✅ 文件输出和轮转
- ✅ 敏感数据脱敏
- ✅ 分布式追踪
- ✅ JSON 结构化输出
- ✅ 告警机制
- ✅ 日志采样
- ✅ 写入容错
- ✅ 多区域支持
- ✅ Temporal 日志
- ✅ 审批引擎集成
- ✅ 日志存储策略优化
- ✅ 日志管理 API

### 待规划（后续版本）

- [ ] OpenTelemetry SDK 集成（对接 Jaeger/Tempo）
- [ ] 日志可视化仪表板
- [ ] 实时日志流（WebSocket）
- [ ] 日志归档到云存储（S3/OSS）
- [ ] 机器学习异常检测

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team
- **最后更新**: 2025-12-25

---

**创建时间**: 2025-11-16  
**更新时间**: 2025-12-25  
**状态**: ✅ 已完成（v1.2.0）  
**版本**: v1.2.0