# Story 2.5: Audit Service - Audit Logging

## Metadata
- **Story ID**: 2.5
- **Title**: Audit Service - Audit Logging
- **Epic**: 2 - Core Services (Authentication & Authorization)
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.1, 1.2, 1.5, 1.7

## Goal
Implement Audit Service as an independent microservice for audit logging. The service exposes a gRPC server, manages its own database connection with AuditLog entity, and registers with Consul service registry.

## Description
This story implements the Audit Service as a separate, independently deployable microservice. It includes audit log recording and querying via gRPC. The service has its own entry point, database connection with AuditLog entity schema, and service registration. Other services use AuditServiceClient to record audit events.

## Deliverables

### 1. Service Entry Point (`cmd/audit-service/main.go`)
- Independent service entry point
- Bootstrap with core kernel services
- Register with Consul service registry
- Start gRPC server on configured port (default: 8084)
- Graceful shutdown with service deregistration

### 2. gRPC Service Definition (`api/proto/audit.proto`)
- `RecordRequest` / `RecordResponse` - Record audit log entry
- `QueryRequest` / `QueryResponse` - Query audit logs with filters
- `AuditService` gRPC service definition

### 3. gRPC Server Implementation (`services/audit/internal/api/server.go`)
- gRPC server implementation
- Handler for Record and Query operations
- Integration with Audit Service business logic

### 4. Audit Service Implementation (`services/audit/internal/service/audit_service.go`)
- Record audit log entries
- Query audit logs with filters (actor, action, date range)
- Pagination support
- Immutable audit logs (no updates/deletes)

### 5. Audit Interface (`pkg/services/audit.go`)
- `AuditServiceClient` interface (defined in Epic 1, Story 1.7)
- `Record(ctx, action)` method
- `Query(ctx, filters)` method
- `AuditAction` struct with actor, action, target, metadata

### 6. Database Connection and Schema (`services/audit/ent/schema/audit_log.go`)
- Audit Service database connection (schema: `audit`)
- AuditLog entity schema:
  - ID, actor_id, action, target_id, metadata (JSONB), timestamp
  - Immutable (no update/delete operations)
- Migration support
- Per-service connection pool

### 7. Service Registration
- Register with Consul on startup
- Health check endpoint for Consul
- Service metadata (name: `audit-service`, port: 8084)
- Deregister on shutdown

## Acceptance Criteria
- [x] Audit Service is independently deployable
- [x] Service entry point exists at `cmd/audit-service/main.go`
- [x] Service registers with Consul on startup
- [x] gRPC server starts on configured port (8084)
- [x] Record RPC stores audit log entries
- [x] Query RPC retrieves audit logs with filters
- [x] Audit logs include complete context (actor, action, target, metadata)
- [x] Audit logs are immutable (no updates/deletes)
- [x] Service has its own database connection (audit schema)
- [x] AuditLog entity schema is defined and migrated
- [x] Other services can use AuditServiceClient to record events
- [x] Service can be discovered by other services via Consul
- [x] Health check endpoint works for Consul

## Related ADRs
- [ADR-0020: Audit Logging Storage](../../adr/0020-audit-logging-storage.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)

## Testing
```bash
# Test Audit Service
go test ./services/audit/...

# Test service startup
go run cmd/audit-service/main.go

# Test gRPC service
grpcurl -plaintext localhost:8084 list
grpcurl -plaintext -d '{"actor_id":"123","action":"user.login","target_id":"user-123"}' \
  localhost:8084 audit.AuditService/Record
```

## Files to Create/Modify
- `cmd/audit-service/main.go` - Service entry point
- `api/proto/audit.proto` - gRPC service definition
- `services/audit/internal/api/server.go` - gRPC server implementation
- `services/audit/internal/service/audit_service.go` - Audit service logic
- `services/audit/ent/schema/audit_log.go` - AuditLog entity schema
- `config/default.yaml` - Add audit service configuration