docs(api): add comprehensive Godoc comments for all interfaces

- Add detailed Godoc for Loader, Capture, Parser, Engine interfaces
- Add detailed Godoc for Writer, UnixSocketWriter, MultiWriter, Builder
- Add detailed Godoc for Logger interface
- Enhance NewLogRecord documentation with pointer/omitempty behavior
- Enhance DefaultConfig documentation with default values

Implements code_style.comments.rules.godoc_exported from architecture.yml

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

api/types.go

@@ -99,52 +99,75 @@ type AppConfig struct {
 	Outputs []OutputConfig `json:"outputs"`
 }
 
-// Loader interface loads configuration from file/env/CLI
+// Loader defines the interface for loading application configuration.
+// Implementations must read configuration from a YAML file, merge with
+// environment variables (JA4SENTINEL_*), and validate the final result.
 type Loader interface {
 	Load() (AppConfig, error)
 }
 
-// Capture interface provides raw network packets
+// Capture defines the interface for capturing raw network packets.
+// Implementations must listen on a configured network interface, apply
+// BPF filters for specified ports, and emit RawPacket objects to a channel.
+// The Close method must be called to release resources (e.g., pcap handle).
 type Capture interface {
 	Run(cfg Config, out chan<- RawPacket) error
 	Close() error
 }
 
-// Parser converts RawPacket to TLSClientHello
+// Parser defines the interface for extracting TLS ClientHello messages
+// from raw network packets. Implementations must track TCP connection states,
+// reassemble fragmented handshakes, and return TLSClientHello objects with
+// IP/TCP metadata. Returns nil for non-TLS or non-ClientHello packets.
 type Parser interface {
 	Process(pkt RawPacket) (*TLSClientHello, error)
 	Close() error
 }
 
-// Engine generates JA4 fingerprints from TLS ClientHello
+// Engine defines the interface for generating TLS fingerprints.
+// Implementations must analyze TLS ClientHello payloads and produce
+// JA4 (required) and optionally JA3 fingerprint strings.
 type Engine interface {
 	FromClientHello(ch TLSClientHello) (*Fingerprints, error)
 }
 
-// Writer is the generic interface for writing results
+// Writer defines the generic interface for writing log records.
+// Implementations must serialize LogRecord objects and send them to
+// a destination (stdout, file, UNIX socket, etc.).
 type Writer interface {
 	Write(rec LogRecord) error
 }
 
-// UnixSocketWriter implements Writer sending logs to a UNIX socket
+// UnixSocketWriter extends Writer with a Close method for UNIX socket cleanup.
+// Implementations must connect to a UNIX socket at the specified path and
+// write JSON-encoded LogRecord objects. Reconnection logic should be
+// implemented for transient socket failures.
 type UnixSocketWriter interface {
 	Writer
 	Close() error
 }
 
-// MultiWriter combines multiple Writers
+// MultiWriter extends Writer to support multiple output destinations.
+// Implementations must write each LogRecord to all registered writers
+// and provide methods to add writers and close all connections.
 type MultiWriter interface {
 	Writer
 	Add(writer Writer)
 	CloseAll() error
 }
 
-// Builder constructs Writers from AppConfig
+// Builder defines the interface for constructing output writers from configuration.
+// Implementations must parse AppConfig.Outputs and create appropriate Writer
+// instances (StdoutWriter, FileWriter, UnixSocketWriter), combining them
+// into a MultiWriter if multiple outputs are configured.
 type Builder interface {
 	NewFromConfig(cfg AppConfig) (Writer, error)
 }
 
-// Logger interface for service logging
+// Logger defines the interface for structured service logging.
+// Implementations must emit JSON-formatted log entries to stdout/stderr
+// with support for multiple log levels (DEBUG, INFO, WARN, ERROR).
+// Each log entry includes timestamp, level, component, message, and optional details.
 type Logger interface {
 	Debug(component, message string, details map[string]string)
 	Info(component, message string, details map[string]string)
@@ -154,7 +177,10 @@ type Logger interface {
 
 // Helper functions for creating and converting records
 
-// NewLogRecord creates a LogRecord from TLSClientHello and Fingerprints
+// NewLogRecord creates a flattened LogRecord from TLSClientHello and Fingerprints.
+// Converts TCPMeta options to a comma-separated string and creates pointer values
+// for optional fields (MSS, WindowScale) to support proper JSON omitempty behavior.
+// If fingerprints is nil, the JA4/JA3 fields will be empty strings.
 func NewLogRecord(ch TLSClientHello, fp *Fingerprints) LogRecord {
 	opts := ""
 	if len(ch.TCPMeta.Options) > 0 {
@@ -224,7 +250,10 @@ const (
 	LogLevelError = "ERROR"
 )
 
-// DefaultConfig returns a configuration with sensible defaults
+// DefaultConfig returns an AppConfig with sensible default values.
+// Uses eth0 as the default interface, port 443 for monitoring,
+// no BPF filter, and a 30-second flow timeout. Returns an empty
+// outputs slice (caller must configure outputs explicitly).
 func DefaultConfig() AppConfig {
 	return AppConfig{
 		Core: Config{