social-app/docs/plans/2026-03-02-bugfix-design.md

# Bug Fix Design: TRIGGER-001 & TOKEN-001

**Date:** 2026-03-02
**Author:** AI Assistant
**Status:** Approved

## Overview

解决 `docs/bugs/backlog.md` 中的两个 bug：
1. TRIGGER-001: user_agents 自动创建
2. TOKEN-001: Flutter 硬编码颜色迁移

## TRIGGER-001: user_agents 自动创建

### Problem

新用户注册时，`user_agents` 表未自动创建默认 Agent 配置记录，导致首次使用 Agent Chat 功能失败。

### Solution

创建配置驱动的自动初始化机制：
- YAML 配置文件定义默认 agent 配置
- 数据库 catalog 表存储配置（持久化）
- Trigger 从 catalog 表读取并批量插入
- 应用启动时自动同步 YAML → catalog 表

### Architecture

```
user_agent_catalog.yaml
  ↓ (应用启动时)
initialize_user_agent_catalog()
  ↓ (upsert)
user_agent_catalog 表
  ↓ (Trigger 查询)
新用户注册 → create_profile_for_new_user()
  ├─→ 插入 profiles
  └─→ 批量插入 user_agents (3条)
```

### Data Model

#### 1. user_agent_catalog.yaml

```yaml
agents:
  - agent_type: INTENT_RECOGNITION
    llm_model_code: qwen3.5-flash
    status: active
    config:
      temperature: 0.7
    
  - agent_type: TASK_EXECUTION
    llm_model_code: deepseek-v3.2
    status: active
    config:
      temperature: 0.7
    
  - agent_type: RESULT_REPORTING
    llm_model_code: deepseek-v3.2
    status: active
    config:
      temperature: 0.7
```

#### 2. user_agent_catalog 表

```sql
CREATE TABLE user_agent_catalog (
    agent_type VARCHAR(20) PRIMARY KEY,
    llm_id UUID NOT NULL REFERENCES llms(id) ON DELETE RESTRICT,
    status VARCHAR(20) NOT NULL DEFAULT 'active',
    config JSONB NOT NULL DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT now(),
    updated_at TIMESTAMPTZ DEFAULT now(),
    CONSTRAINT chk_status CHECK (status IN ('active', 'paused', 'migrating'))
);
```

**字段说明：**
- `agent_type`: 主键，agent 类型（INTENT_RECOGNITION / TASK_EXECUTION / RESULT_REPORTING）
- `llm_id`: 外键，关联 llms 表
- `status`: 默认状态（active / paused / migrating）
- `config`: 默认配置（JSONB，包含 temperature 等）

#### 3. Trigger 函数

```sql
CREATE OR REPLACE FUNCTION create_profile_for_new_user()
RETURNS trigger AS $$
BEGIN
    -- 插入 profile（现有逻辑）
    INSERT INTO profiles (id, username, avatar_url, bio, settings, created_at, updated_at)
    VALUES (
        NEW.id,
        COALESCE(
            NEW.raw_user_meta_data ->> 'username',
            split_part(NEW.email, '@', 1),
            'user_' || substring(NEW.id::text, 1, 8)
        ),
        NULL, NULL, '{}'::jsonb, now(), now()
    )
    ON CONFLICT (id) DO NOTHING;

    -- 从 user_agent_catalog 批量插入 user_agents
    INSERT INTO user_agents (id, user_id, llm_id, agent_type, config, status, created_by, updated_by)
    SELECT 
        gen_random_uuid(),
        NEW.id,
        uac.llm_id,
        uac.agent_type,
        uac.config,
        uac.status,
        NEW.id,
        NEW.id
    FROM user_agent_catalog uac;
    
    RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER SET search_path = public;
```

### Implementation Components

#### 1. Python Model

```python
# backend/src/models/user_agent_catalog.py
class UserAgentCatalog(TimestampMixin, Base):
    __tablename__ = "user_agent_catalog"
    
    agent_type: Mapped[str] = mapped_column(String(20), primary_key=True)
    llm_id: Mapped[uuid.UUID] = mapped_column(UUID, ForeignKey("llms.id"), nullable=False)
    status: Mapped[str] = mapped_column(String(20), nullable=False)
    config: Mapped[dict] = mapped_column(JSONB, nullable=False, server_default="{}")
```

#### 2. 初始化函数

```python
# backend/src/core/config/initial/init_data.py

class UserAgentCatalogSeed(BaseModel):
    agent_type: str
    llm_model_code: str
    status: str
    config: dict[str, Any]

def load_user_agent_catalog(catalog_path: Path | None = None) -> dict[str, Any]:
    path = catalog_path or _default_user_agent_catalog_path()
    with path.open("r", encoding="utf-8") as file:
        loaded = yaml.safe_load(file) or {}
    # ... validation logic
    return parsed.model_dump()

async def initialize_user_agent_catalog() -> None:
    catalog = load_user_agent_catalog()
    
    async with AsyncSessionLocal() as session:
        async with session.begin():
            for agent in catalog["agents"]:
                # 查找 llm_id
                llm = await session.execute(
                    select(Llm).where(Llm.model_code == agent["llm_model_code"])
                )
                llm_id = llm.scalar_one().id
                
                # Upsert
                existing = await session.execute(
                    select(UserAgentCatalog).where(
                        UserAgentCatalog.agent_type == agent["agent_type"]
                    )
                )
                catalog_entry = existing.scalar_one_or_none()
                
                if catalog_entry:
                    catalog_entry.llm_id = llm_id
                    catalog_entry.status = agent["status"]
                    catalog_entry.config = agent["config"]
                else:
                    session.add(UserAgentCatalog(
                        agent_type=agent["agent_type"],
                        llm_id=llm_id,
                        status=agent["status"],
                        config=agent["config"]
                    ))
    
    logger.info("Initialized user agent catalog")

async def initialize_data() -> bool:
    await initialize_llm_catalog()
    await initialize_user_agent_catalog()  # 新增
    return True
```

### Migration Strategy

#### 1. Alembic 迁移

```python
# backend/alembic/versions/20260302_add_user_agent_catalog.py

def upgrade() -> None:
    # 创建表
    op.create_table(
        "user_agent_catalog",
        sa.Column("agent_type", sa.String(20), nullable=False),
        sa.Column("llm_id", sa.UUID(), nullable=False),
        sa.Column("status", sa.String(20), nullable=False),
        sa.Column("config", postgresql.JSONB(), nullable=False, server_default="{}"),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
        sa.PrimaryKeyConstraint("agent_type"),
        sa.ForeignKeyConstraint(["llm_id"], ["llms.id"], ondelete="RESTRICT"),
    )
    
    op.execute(
        "ALTER TABLE user_agent_catalog "
        "ADD CONSTRAINT chk_status CHECK (status IN ('active', 'paused', 'migrating'))"
    )
    
    # 替换 trigger 函数
    op.execute("""
        CREATE OR REPLACE FUNCTION public.create_profile_for_new_user()
        -- ... 新的 trigger 代码
    """)
    
    # 为已存在用户补充 user_agents
    op.execute("""
        INSERT INTO user_agents (id, user_id, llm_id, agent_type, config, status, created_by, updated_by)
        SELECT 
            gen_random_uuid(),
            p.id,
            uac.llm_id,
            uac.agent_type,
            uac.config,
            uac.status,
            p.id,
            p.id
        FROM profiles p
        CROSS JOIN user_agent_catalog uac
        WHERE NOT EXISTS (
            SELECT 1 FROM user_agents ua WHERE ua.user_id = p.id
        );
    """)
    
    _enable_rls("user_agent_catalog")

def downgrade() -> None:
    # 恢复旧 trigger
    op.execute("""
        CREATE OR REPLACE FUNCTION public.create_profile_for_new_user()
        -- ... 旧的 trigger 代码（只有 profile）
    """)
    
    _drop_rls("user_agent_catalog")
    op.drop_table("user_agent_catalog")
```

### Configuration Update Flow

**用户修改配置的步骤：**

1. 编辑 `backend/src/core/config/static/database/user_agent_catalog.yaml`
2. 重启应用（或调用 `uv run python -m core.runtime.cli bootstrap`）
3. `initialize_user_agent_catalog()` 自动执行
4. user_agent_catalog 表更新（upsert）
5. 新用户注册时使用新配置

**示例：**
```yaml
# 修改 temperature
agents:
  - agent_type: INTENT_RECOGNITION
    llm_model_code: qwen3.5-flash
    status: active
    config:
      temperature: 0.5  # 从 0.7 改为 0.5
```

重启应用后，新注册的用户 INTENT_RECOGNITION agent 会使用 temperature=0.5。

### Testing Strategy

1. **单元测试：** `load_user_agent_catalog()` 函数
2. **集成测试：** `initialize_user_agent_catalog()` upsert 逻辑
3. **E2E 测试：** 新用户注册后自动创建 3 个 user_agents 记录
4. **回归测试：** 已存在用户不受影响

### File Changes

```
backend/src/core/config/static/database/user_agent_catalog.yaml (填充)
backend/src/models/user_agent_catalog.py (新建)
backend/src/core/config/initial/init_data.py (扩展)
backend/alembic/versions/20260302_add_user_agent_catalog.py (新建)
backend/tests/unit/core/test_agent_init_data.py (扩展)
```

---

## TOKEN-001: Flutter 硬编码颜色迁移

### Problem

109 处硬编码 `Color(0xFF...)` 违反 `apps/AGENTS.md` 规则："NEVER hardcode colors, sizes, or spacing values"。

分散在 11 个页面文件：
- register_screen.dart, register_verification_screen.dart
- settings_screen.dart, account_screen.dart
- contacts_screen.dart, calendar_event_detail_screen.dart
- add_contact_screen.dart, features_screen.dart
- memory_screen.dart, home_screen.dart
- todo_detail_screen.dart

### Solution

**渐进式迁移：**
1. 扫描所有硬编码颜色，统计频率
2. 将高频颜色添加到 `design_tokens.dart` 的 `AppColors`
3. 逐页面替换硬编码为 `AppColors.xxx`
4. 保留合理的动态颜色场景

### Migration Steps

#### Phase 1: 扫描和统计

```bash
# 扫描所有硬编码颜色
grep -r "Color(0x" apps/lib --include="*.dart" | \
  sed 's/.*Color(0x\([0-9A-Fa-f]*\)).*/\1/' | \
  sort | uniq -c | sort -rn
```

**预期输出：**
```
  45 2196F3  # 蓝色（链接/主色）
  23 D32F2F  # 红色（错误）
  18 4CAF50  # 绿色（成功）
  ...
```

#### Phase 2: 扩展 AppColors

```dart
// apps/lib/core/theme/design_tokens.dart

class AppColors {
  // 现有颜色...
  
  // 从硬编码迁移的颜色
  static const Color linkBlue = Color(0xFF2196F3);
  static const Color errorRed = Color(0xFFD32F2F);
  static const Color successGreen = Color(0xFF4CAF50);
  // ... 根据扫描结果添加
}
```

#### Phase 3: 逐页面迁移

```dart
// Before
Container(
  color: Color(0xFF2196F3),
  child: Text('Link'),
)

// After
Container(
  color: AppColors.linkBlue,
  child: Text('Link'),
)
```

**迁移顺序（按频率）：**
1. register_screen.dart (最高频)
2. register_verification_screen.dart
3. settings_screen.dart
4. ... (其他页面)

#### Phase 4: 测试和验证

1. **视觉测试：** 逐页面检查 UI 是否正常
2. **Widget 测试：** 更新测试使用 AppColors
3. **设计审查：** 确认颜色一致性

### Allowed Exceptions

以下场景可以保留硬编码（需在 AGENTS.md 中明确）：
- 动态计算的渐变色
- 图片处理相关的颜色
- 第三方库要求的颜色格式

### Testing Strategy

1. **Widget 测试：** 确保组件仍然正常渲染
2. **视觉回归测试：** 对比迁移前后的截图
3. **代码审查：** 确保没有遗漏的硬编码

### File Changes

```
apps/lib/core/theme/design_tokens.dart (扩展)
apps/lib/features/*/ui/screens/*.dart (迁移)
apps/AGENTS.md (明确允许的场景)
```

---

## Implementation Order

1. **TRIGGER-001** (优先级更高，影响功能)
   - 创建 catalog YAML
   - 创建 model 和迁移
   - 扩展初始化逻辑
   - 修改 trigger
   - 测试

2. **TOKEN-001** (次要，不影响功能)
   - 扫描硬编码
   - 扩展 AppColors
   - 逐页面迁移
   - 测试

## Success Criteria

### TRIGGER-001
- [ ] 新用户注册后自动创建 3 个 user_agents 记录
- [ ] 已存在用户不受影响
- [ ] 配置可通过 YAML + 重启更新
- [ ] 所有测试通过

### TOKEN-001
- [ ] 硬编码颜色数量从 109 减少到 < 10
- [ ] UI 视觉无回归
- [ ] 所有测试通过

## Risks and Mitigations

### TRIGGER-001
- **风险：** llms 表中缺少对应的 model_code
  - **缓解：** 初始化前检查 llms 表是否存在，提供清晰的错误信息
- **风险：** Trigger 性能影响
  - **缓解：** catalog 表只有 3 行，查询性能可忽略

### TOKEN-001
- **风险：** 迁移后颜色不一致
  - **缓解：** 视觉回归测试 + 设计审查
- **风险：** 遗漏某些硬编码
  - **缓解：** 自动化扫描 + 代码审查

## Related Documents

- `docs/bugs/backlog.md` - Bug 列表
- `backend/AGENTS.md` - Backend 开发规则
- `apps/AGENTS.md` - Flutter 开发规则
- `backend/src/core/config/initial/init_data.py` - 现有初始化逻辑
- `backend/alembic/versions/20260227_0006_invite_codes_and_profile_referral.py` - Trigger 修改参考