docs: 更新协议文档并清理过期的问题追踪文档

2026-03-27 14:05:14 +08:00
parent c592cc7854
commit 47e2aa3eb9
18 changed files with 1499 additions and 778 deletions
@@ -0,0 +1,90 @@
+# AppTheme 硬编码颜色且缺失 Dark Mode
+
+## 问题描述
+
+### 1. 颜色硬编码
+
+`AppTheme` 和各组件大量直接引用 `AppColors` 静态常量，而非 `Theme.of(context).colorScheme`：
+
+```dart
+// app_theme.dart
+appBarTheme: const AppBarTheme(
+  backgroundColor: AppColors.background,    // 硬编码
+  foregroundColor: AppColors.slate900,      // 硬编码
+),
+
+elevatedButtonTheme: ElevatedButtonThemeData(
+  style: ElevatedButton.styleFrom(
+    backgroundColor: AppColors.primary,     // 硬编码
+    foregroundColor: AppColors.primaryForeground,
+  ),
+),
+```
+
+这导致：
+- 主题切换时颜色不会改变
+- 组件无法响应系统深色模式
+- 违反 Flutter Material Design 规范
+
+### 2. 缺失 Dark Mode
+
+`AppTheme` 只有 `light` getter，没有 `dark`：
+
+```dart
+static ThemeData get light => ThemeData(...);
+```
+
+`LinksyApp` 硬编码使用 light：
+```dart
+theme: AppTheme.light,
+locale: const Locale('zh'),
+```
+
+## 正确做法
+
+### 颜色应使用 ThemeData
+
+```dart
+// 正确示例
+appBarTheme: AppBarTheme(
+  backgroundColor: Theme.of(context).colorScheme.surface,
+  foregroundColor: Theme.of(context).colorScheme.onSurface,
+),
+
+// ColorScheme 应由 ThemeData 生成
+colorScheme: ColorScheme.fromSeed(
+  seedColor: AppColors.primary,
+  brightness: Brightness.light,  // 或 Brightness.dark
+),
+```
+
+### 支持 Dark Mode
+
+```dart
+class AppTheme {
+  static ThemeData get light => ThemeData(
+    brightness: Brightness.light,
+    colorScheme: ColorScheme.fromSeed(
+      seedColor: AppColors.primary,
+      brightness: Brightness.light,
+    ),
+  );
+
+  static ThemeData get dark => ThemeData(
+    brightness: Brightness.dark,
+    colorScheme: ColorScheme.fromSeed(
+      seedColor: AppColors.primary,
+      brightness: Brightness.dark,
+    ),
+  );
+}
+```
+
+## 相关文件
+
+- `apps/lib/core/theme/app_theme.dart`
+- `apps/lib/core/theme/design_tokens.dart`
+
+## 修复优先级
+
+**低** - 当前只有 light 模式，不影响功能