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`