social-app/docs/bugs/backlog.md

Backlog - Known Issues & Improvements

Database Triggers

[TRIGGER-001] user_agents 自动创建

Status: ✅ Resolved
Priority: Medium
Created: 2026-02-27
Resolved: 2026-03-02

Description: 当新用户注册时，user_agents 表未自动创建默认 Agent 配置记录。

Current Behavior:

• auth.users → profiles 已有 trigger 自动创建
• user_agents 无自动创建机制

Expected Behavior: 新用户注册后，应有默认的 Agent 配置（如 INTENT_RECOGNITION、TASK_EXECUTION、RESULT_REPORTING 三种类型）。

Impact:

• 用户首次使用 Agent Chat 功能时可能失败
• 需要应用层手动初始化或前端引导配置

Solution:

1. 创建 user_agent_catalog.yaml 配置文件定义 3 种 agent 类型
2. 创建 user_agent_catalog 表存储配置（持久化）
3. 修改 user_agents 表唯一约束：user_id → (user_id, agent_type) 允许每个用户有多个 agents
4. 扩展 create_profile_for_new_user() trigger 从 catalog 批量插入 user_agents
5. 实现配置动态更新：修改 YAML → 重启应用 → 自动同步到数据库
6. 为已存在用户补充 user_agents 记录

Verification:

• ✅ 新用户注册自动创建 3 个 agents
• ✅ Catalog 表已填充（INTENT_RECOGNITION, TASK_EXECUTION, RESULT_REPORTING）
• ✅ 已为 1 个存在用户补充 3 个 agents
• ✅ Backend tests: 247 passed

Related Files:

• backend/src/core/config/static/database/user_agent_catalog.yaml
• backend/src/models/user_agent_catalog.py
• backend/alembic/versions/50ae013ce530_add_user_agent_catalog.py
• backend/src/core/config/initial/init_data.py

---

Flutter Design Tokens

[TOKEN-001] 大量硬编码颜色违反 AGENTS.md 规则

Status: ✅ Resolved (Partial)
Priority: Medium
Created: 2026-03-02
Resolved: 2026-03-02

Description: apps/AGENTS.md 规则要求禁止硬编码颜色，必须使用 design_tokens.dart 中的 AppColors。但实际代码中存在大量硬编码。

Current Behavior:

• apps/AGENTS.md 规定："NEVER hardcode colors, sizes, or spacing values"
• 代码中有 126 处硬编码 Color(0xFF...)（扫描发现比预期多 17 处）

Expected Behavior: 所有颜色应使用 AppColors 中定义的值。

Impact:

• 与项目规范不一致
• 后续 theme 统一修改困难
• 代码审查难以发现

Solution (渐进式迁移):

1. 扫描分析: 发现 126 个硬编码颜色，Top 3: FFF8FAFC (11), FFF8FAFF (9), FFE2E8F0 (5)
2. 扩展 AppColors: 添加 11 个语义化 token（surfaceSecondary, borderSecondary, success, warning 等）
3. 优先迁移: 8 个高频文件（settings, contacts, calendar_event_detail 等）
4. 批量替换: 37 个硬编码颜色已替换为 tokens
5. 测试验证: 140/140 Flutter tests 通过

Migration Results:

• ✅ 新增 token: 11 个（覆盖 57 次使用）
• ✅ 已迁移: 37 个硬编码颜色
• ⚠️ 剩余: 90 个（建议后续迭代继续迁移）

Recommendations:

1. 继续迁移剩余 90 个硬编码颜色
2. 优先处理 contacts_screen.dart, settings_screen.dart, features_screen.dart (46% of remaining)
3. 考虑添加 lint rule 防止新增硬编码颜色

Related Files:

• apps/lib/core/theme/design_tokens.dart
• apps/lib/features/*/ui/screens/*.dart (8 files migrated)
• apps/AGENTS.md