# Story 0.3: Structured Logging System

## Metadata
- **Story ID**: 0.3
- **Title**: Structured Logging System
- **Epic**: 0 - Project Setup & Foundation
- **Status**: Completed
- **Priority**: High
- **Estimated Time**: 4-6 hours
- **Dependencies**: 0.1, 0.2

## Goal
Implement a production-ready logging system with structured JSON output, request correlation, and configurable log levels that can be used by all modules.

## Description
This story implements a complete logging system using Zap that provides structured logging, request correlation via request IDs, and context-aware logging. The system must support both development (human-readable) and production (JSON) formats.

## Deliverables

### 1. Logger Interface (`pkg/logger/logger.go`)
Define `Logger` interface with:

- `Debug(msg string, fields ...Field)` - Debug level logging
- `Info(msg string, fields ...Field)` - Info level logging
- `Warn(msg string, fields ...Field)` - Warning level logging
- `Error(msg string, fields ...Field)` - Error level logging
- `With(fields ...Field) Logger` - Create child logger with fields
- `WithContext(ctx context.Context) Logger` - Create logger with context fields
- `Field` type for structured fields
- Package-level convenience functions

### 2. Zap Implementation (`internal/logger/zap_logger.go`)
Implement `Logger` interface using Zap:

- Structured JSON logging for production mode
- Human-readable console logging for development mode
- Configurable log levels (debug, info, warn, error)
- Request-scoped fields support
- Context-aware logging (extract request ID, user ID from context)
- Field mapping to Zap fields
- Error stack trace support

### 3. Request ID Middleware (`internal/logger/middleware.go`)
Gin middleware for request correlation:

- Generate unique request ID per HTTP request
- Add request ID to request context
- Add request ID to all logs within request context
- Return request ID in response headers (`X-Request-ID`)
- Support for existing request IDs in headers

### 4. Global Logger Export (`pkg/logger/global.go`)
- Export default logger instance
- Package-level convenience functions
- Thread-safe logger access

### 5. DI Integration
- Provider function for Logger
- Register in DI container
- Make configurable via FX

## Implementation Steps

1. **Install Dependencies**
   ```bash
   go get go.uber.org/zap@v1.26.0
   ```

2. **Create Logger Interface**
   - Define `Logger` interface in `pkg/logger/logger.go`
   - Define `Field` type for structured fields
   - Add package documentation

3. **Implement Zap Logger**
   - Create `internal/logger/zap_logger.go`
   - Implement all interface methods
   - Support both JSON and console encoders
   - Handle log levels and field mapping

4. **Create Request ID Middleware**
   - Create `internal/logger/middleware.go`
   - Implement Gin middleware
   - Generate and propagate request IDs
   - Add to response headers

5. **Add Global Logger**
   - Create `pkg/logger/global.go`
   - Export default logger
   - Add convenience functions

6. **Integrate with DI**
   - Create provider function
   - Register in DI container
   - Test injection

## Acceptance Criteria
- [x] `Logger` interface is defined and documented
- [x] Zap implementation supports JSON and console formats
- [x] Log levels are configurable and respected
- [x] Request IDs are generated and included in all logs
- [x] Request ID middleware works with Gin
- [x] Context-aware logging extracts request ID and user ID
- [x] Logger can be injected via DI container
- [x] All modules can use logger through interface
- [x] Request correlation works across service boundaries
- [x] Structured fields work correctly

## Related ADRs
- [ADR-0005: Logging Framework](../../adr/0005-logging-framework.md)
- [ADR-0012: Logger Interface Design](../../adr/0012-logger-interface-design.md)

## Implementation Notes
- Use Zap's production and development presets
- Request IDs should be UUIDs or similar unique identifiers
- Context should be propagated through all service calls
- Log levels should be configurable via configuration system
- Consider adding log sampling for high-volume production
- Support for log rotation and file output (future enhancement)

## Testing
```bash
# Test logger interface
go test ./pkg/logger/...

# Test Zap implementation
go test ./internal/logger/...

# Test request ID middleware
go test ./internal/logger/... -run TestRequestIDMiddleware
```

## Files to Create/Modify
- `pkg/logger/logger.go` - Logger interface
- `pkg/logger/global.go` - Global logger export
- `internal/logger/zap_logger.go` - Zap implementation
- `internal/logger/middleware.go` - Request ID middleware
- `internal/di/providers.go` - Add logger provider
- `config/default.yaml` - Add logging configuration