feat(logging): add logging to auth feature

2026-04-01 14:28:30 +08:00
parent 2b12d1ef79
commit 63d225c567
5 changed files with 138 additions and 15 deletions
@@ -111,3 +111,91 @@ This file governs `apps/**` (Flutter). Keep rules strict, short, and reusable.
 - Prioritize tests for model parsing, service logic, and high-regression interaction flows.
 - Simple static UI changes may skip tests.
 - Auth/Home/Cache changes must include targeted regression tests.
+
+## Logging Conventions (Must)
+
+### Logger Setup
+
+```dart
+import 'core/logging/logger.dart';
+
+class SomeBloc extends Cubit<SomeState> {
+  final Logger _logger = getLogger('features.<feature>.<component>');
+}
+```
+
+### Log Level Policy
+
+| Level | When to Use | Noise Level |
+|-------|-------------|-------------|
+| **error** | All exceptions and failures - MUST log every error site | Required, never skip |
+| **warning** | Degraded behavior, retry, fallback, malformed data | Minimal, only when action taken |
+| **info** | Key business events (login, logout, send message) | Minimal, only milestone events |
+| **debug** | Detailed flow tracing (only in debug builds) | High, avoid in release |
+
+### Error Logging Requirements
+
+**Every try-catch that handles an exception MUST log it:**
+```dart
+try {
+  await _repository.someOperation();
+} catch (e, stackTrace) {
+  _logger.error(
+    message: 'Operation failed: $operationName',
+    error: e,
+    stackTrace: stackTrace,
+    extra: {'context': 'relevant_data'},
+  );
+  // handle error
+}
+```
+
+### Info Logging Requirements
+
+**Only log these milestone events:**
+- User login/logout
+- Message sent/received
+- Data sync completed
+- Important state transitions
+
+```dart
+_logger.info(
+  message: 'User logged in',
+  extra: {'user_id': user.id},
+);
+```
+
+### Warning Logging Requirements
+
+**Only log when taking corrective action:**
+- Retrying after failure
+- Using fallback data
+- Skipping malformed data
+- Deprecation warnings
+
+```dart
+_logger.warning(
+  message: 'Cache miss, loading from remote',
+  extra: {'key': cacheKey},
+);
+```
+
+### Module Naming Convention
+
+| Feature | Module Path |
+|---------|------------|
+| auth | `features.auth` |
+| calendar | `features.calendar` |
+| chat | `features.chat` |
+| contacts | `features.contacts` |
+| home | `features.home` |
+| messages | `features.messages` |
+| settings | `features.settings` |
+| todo | `features.todo` |
+
+### Prohibited Practices
+
+- **Never** log sensitive data: passwords, tokens, PII, message content
+- **Never** log at debug level in production (release mode)
+- **Never** skip error logging even if you "handle" the error
+- **Never** log for every iteration in loops - only on failures