feat(api): Add human feedback API (#6) + async_utils module

Phase 6.6 人類回饋 API:
- PUT /api/v1/incidents/{id}/feedback endpoint
- effectiveness_score (1-5), human_feedback, learning_notes fields
- Sync to Redis (Working Memory) + PostgreSQL (Episodic Memory)
- For stats aggregation at /api/v1/stats/feedback/summary

async_utils module:
- fire_and_forget() for safe background tasks
- Prevents swallowed exceptions in asyncio.create_task()
- Addresses P2 #8 tech debt

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

apps/api/src/api/v1/incidents.py

@@ -342,6 +342,180 @@ async def generate_proposal(incident_id: str) -> ProposalGenerateResponse:
     )
 
 
+# =============================================================================
+# PUT /api/v1/incidents/{incident_id}/feedback - Phase 6.6 人類回饋 API
+# =============================================================================
+
+
+class FeedbackRequest(BaseModel):
+    """人類回饋請求"""
+
+    effectiveness_score: int | None = Field(
+        None,
+        ge=1,
+        le=5,
+        description="有效性評分 (1-5 分, 5 最有效)",
+    )
+    human_feedback: str | None = Field(
+        None,
+        max_length=1000,
+        description="文字回饋 (如 '這個建議很準' 或 '下次應該先檢查 X')",
+    )
+    learning_notes: str | None = Field(
+        None,
+        max_length=2000,
+        description="給未來 AI 的學習筆記",
+    )
+    should_remember: bool = Field(
+        default=True,
+        description="是否納入長期記憶 (Episodic Memory)",
+    )
+
+
+class FeedbackResponse(BaseModel):
+    """人類回饋回應"""
+
+    success: bool
+    message: str
+    incident_id: str
+    outcome: dict[str, Any] | None = None
+
+
+@router.put(
+    "/{incident_id}/feedback",
+    response_model=FeedbackResponse,
+    summary="提交人類回饋",
+    description="""
+    Phase 6.6: 人類回饋 API
+
+    用途:
+    - 收集人類對 AI 建議的有效性評分
+    - 記錄文字回饋與學習筆記
+    - 作為 AI 改進的訓練數據
+
+    工作流程:
+    1. 更新 Incident 的 outcome 欄位
+    2. 同步到 Redis (Working Memory) 和 PostgreSQL (Episodic Memory)
+    3. 供統計分析 API (/api/v1/stats/feedback/summary) 聚合查詢
+    """,
+)
+async def submit_feedback(
+    incident_id: str,
+    request: FeedbackRequest,
+) -> FeedbackResponse:
+    """
+    提交人類對 AI 建議的回饋
+
+    Args:
+        incident_id: 事件 ID
+        request: 回饋內容
+
+    Returns:
+        FeedbackResponse: 更新結果
+
+    Raises:
+        HTTPException: 404 事件不存在
+    """
+    from datetime import datetime
+
+    from sqlalchemy import select
+
+    from src.db.base import get_db_context
+    from src.db.models import IncidentRecord
+    from src.models.incident import IncidentOutcome
+
+    redis_client = get_redis()
+    redis_key = f"incident:{incident_id}"
+
+    # 1. 取得現有 Incident
+    try:
+        data = await redis_client.get(redis_key)
+        if not data:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Incident not found: {incident_id}",
+            )
+        incident = Incident.model_validate_json(data)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("feedback_redis_read_error", incident_id=incident_id)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to read incident: {str(e)}",
+        ) from e
+
+    # 2. 更新或建立 outcome
+    if incident.outcome is None:
+        incident.outcome = IncidentOutcome()
+
+    if request.effectiveness_score is not None:
+        incident.outcome.effectiveness_score = request.effectiveness_score
+    if request.human_feedback is not None:
+        incident.outcome.human_feedback = request.human_feedback
+    if request.learning_notes is not None:
+        incident.outcome.learning_notes = request.learning_notes
+    incident.outcome.should_remember = request.should_remember
+    incident.updated_at = datetime.now(UTC)
+
+    # 3. 寫入 Redis
+    try:
+        await redis_client.set(
+            redis_key,
+            incident.model_dump_json(),
+            ex=604800,  # 7 天 TTL
+        )
+        logger.info(
+            "feedback_redis_updated",
+            incident_id=incident_id,
+            effectiveness_score=request.effectiveness_score,
+        )
+    except Exception as e:
+        logger.exception("feedback_redis_write_error", incident_id=incident_id)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update Redis: {str(e)}",
+        ) from e
+
+    # 4. 同步到 PostgreSQL (Episodic Memory)
+    try:
+        async with get_db_context() as db:
+            stmt = select(IncidentRecord).where(
+                IncidentRecord.incident_id == incident_id
+            )
+            result = await db.execute(stmt)
+            record = result.scalar_one_or_none()
+
+            if record:
+                record.outcome = incident.outcome.model_dump(mode="json")
+                record.updated_at = datetime.now(UTC)
+                await db.commit()
+                logger.info(
+                    "feedback_db_updated",
+                    incident_id=incident_id,
+                )
+            else:
+                logger.warning(
+                    "feedback_db_record_not_found",
+                    incident_id=incident_id,
+                    message="將在下次 memory 同步時建立",
+                )
+    except Exception as e:
+        logger.warning(
+            "feedback_db_write_error",
+            incident_id=incident_id,
+            error=str(e),
+        )
+        # DB 寫入失敗不阻止回應 (Redis 已更新)
+
+    return FeedbackResponse(
+        success=True,
+        message="Feedback submitted successfully",
+        incident_id=incident_id,
+        outcome=incident.outcome.model_dump(mode="json"),
+    )
+
+
 # =============================================================================
 # DEBUG: 測試 Incident 狀態更新
 # =============================================================================

apps/api/src/core/async_utils.py

@@ -0,0 +1,54 @@
+"""
+Async Utilities
+===============
+Safe async patterns for production use.
+
+ADR-013: 此模組包含關鍵異步模式，修改前請先讀懂註解！
+"""
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any
+
+from src.core.logging import get_logger
+
+logger = get_logger("awoooi.async_utils")
+
+
+def fire_and_forget(coro: Coroutine[Any, Any, Any], name: str | None = None) -> asyncio.Task[Any]:
+    """
+    安全的 fire-and-forget 模式。
+
+    🔴 重要：不使用此函數的 asyncio.create_task() 會吞掉例外！
+
+    Args:
+        coro: 要執行的協程
+        name: 任務名稱 (用於日誌)
+
+    Returns:
+        已建立的任務 (可忽略)
+
+    Example:
+        # ✅ 正確用法
+        fire_and_forget(send_notification(user_id), name="notification")
+
+        # ❌ 錯誤用法 (例外會被吞掉)
+        asyncio.create_task(send_notification(user_id))
+    """
+    task = asyncio.create_task(coro, name=name)
+
+    def _handle_exception(t: asyncio.Task[Any]) -> None:
+        try:
+            exc = t.exception()
+            if exc is not None:
+                logger.error(
+                    "fire_and_forget_exception",
+                    task_name=name or "unnamed",
+                    error=str(exc),
+                    error_type=type(exc).__name__,
+                )
+        except asyncio.CancelledError:
+            logger.debug("fire_and_forget_cancelled", task_name=name or "unnamed")
+
+    task.add_done_callback(_handle_exception)
+    return task