# Loggers

Custom logging framework with multi-writer fan-out and `Microsoft.Extensions.Logging` integration. This directory contains the **core** logger and writer abstractions — the defining layer for the logging system.

> For full architecture, configuration, all writers, and remote logging flow see `docs/LOGGING/README.md`.

## Architecture

```
IAcLoggerBase (: IAcLogWriterBase, ILogger)
  └─ AcLoggerBase (abstract, multi-writer fan-out, ILogger bridge)
       └─ [concrete loggers per consuming project]

IAcLogWriterBase
  └─ AcLogWriterBase (abstract, per-writer config from appsettings)
       ├─ AcTextLogWriterBase (abstract, text formatting)
       │    └─ AcConsoleLogWriter (colored console output)
       └─ [AcLogItemWriterBase<T> in AyCode.Entities — structured writers]
```

**Two-level filtering:** Logger has a global `LogLevel` gate; each writer has its own `LogLevel`. Both must pass for a log entry to be written. See `docs/LOGGING/README.md` → Design Overview.

## Key Files

### Logger Core
- **`IAcLoggerBase.cs`** — Unified interface combining `IAcLogWriterBase` + `ILogger`. Exposes `GetWriters` and `Writer<T>()`.
- **`AcLoggerBase.cs`** — Abstract logger implementing `ILogger`. Manages `List<IAcLogWriterBase>`. Reads config from `appsettings.json` (`AyCode:Logger:{AppType, LogLevel, LogWriters[]}`). Maps MS `LogLevel` to AC `LogLevel`. Fan-out dispatch to all writers. `[Conditional("DEBUG")]` variants for all methods.
- **`AcLoggerAdapter.cs`** — `AcLoggerProvider<TLogger>` implementing `ILoggerProvider` with `ConcurrentDictionary<string, TLogger>` per-category cache. Extension methods: `AddAcLogger<T>()`, `UseOnlyAcLogger<T>()`.

### Writers
- **`IAcLogWriterBase.cs`** — Writer contract: `Detail()`, `Debug()`, `Info()`, `Warning()`, `Suggest()`, `Error()`, plus `Write()` overloads and `Write(IAcLogItemClient)`.
- **`IAcLogWriterClientBase.cs`** — Marker interface for client-side writers (no additional members).
- **`AcLogWriterBase.cs`** — Abstract base. Own `LogLevel` loaded from appsettings by matching `AssemblyQualifiedName`. Named methods delegate to terminal `Write(AppType, LogLevel, text, caller, category, errorType, exMessage)`.
- **`AcTextLogWriterBase.cs`** — Abstract text formatter. Format: `[HH:mm:ss.fff] [AppType[0]] [Level] [Category->Method] [ThreadId] Text [Error]`. Subclasses implement `WriteText(string, LogLevel)`.
- **`AcConsoleLogWriter.cs`** — Colored console writer. Thread-safe via `static lock`. Colors: Gray=≤Trace, White=Debug–Info, Cyan=Suggest, Yellow=Warning, Red=≥Error.

### Supporting
- **`IAcLogItemClient.cs`** — Structured log item DTO interface for remote transmission (TimeStampUtc, AppType, LogLevel, ThreadId, CategoryName, CallerName, Text, Exception, ErrorType).
- **`LogLevel.cs`** — Byte enum: Detail(0), Trace(5), Debug(10), Info(15), Suggest(17), Warning(20), Error(25), Disabled(255). ⚠️ **Values synchronized with database `LogLevel` table — do NOT renumber.**