task: "Refactor backend: tách rõ API routes, dọn dead code trong agent module"
test_command: "cd backend && pytest"
---

# Task: Loop vô hạn dọn dẹp backend CuCu

Mục tiêu:
- **Loop vô hạn** cho đến khi backend gọn gàng, tối giản, dễ scale, chuẩn senior nhất có thể.
- Dọn dẹp backend FastAPI + agent cho gọn, dễ đọc, dễ scale.
- Giảm nợ kỹ thuật, chuẩn hóa kiến trúc và cấu trúc module.
- Đảm bảo test backend chạy xanh, hạn chế regression.
- Code phải đạt chuẩn senior: clean, maintainable, scalable.

## Success Criteria

### 1. Kiến trúc & cấu trúc mã nguồn <!-- group: 1 -->

- [ ] API backend được tổ chức rõ ràng:
  - `backend/api/memos` và `backend/api/chatbot` tách bạch trách nhiệm.
  - Không còn logic business nặng nằm lẫn trong route handler.
- [ ] Module agent (`backend/agent/*`) được dọn:
  - Graph, tools, controller, helper tách vai trò rõ.
  - Không còn import dead code / module không dùng.
- [ ] Các singleton/service quan trọng (Mongo client, ConversationManager, LLM factory, cache) có một nơi khởi tạo rõ ràng, tránh duplicate logic.
- [ ] Đường dẫn, tên file, tên hàm tuân thủ convention nhất quán (snake_case cho Python, rõ domain).

### 2. Độ tin cậy & test backend <!-- group: 2 -->

- [ ] Tất cả test trong `backend/tests` pass ổn định với:
  - `cd backend && pytest` chạy không lỗi.
  - Không thêm test flaky mới (nếu có test flaky cũ, ghi chú rõ trong progress/guardrails).
- [ ] Route `/api/agent/chat` và các route chính của `memos` được cover test:
  - Response code đúng.
  - Trả về schema hợp lệ, không raise exception không kiểm soát.
- [ ] Các xử lý lỗi quan trọng (validation input, timeout LLM, lỗi DB) đều:
  - Bị log lại rõ ràng.
  - Trả về HTTP status chuẩn (4xx/5xx) với message dễ debug.

### 3. Hiệu năng & khả năng mở rộng nhẹ nhàng <!-- group: 3 -->

- [ ] Các đoạn code có nguy cơ N+1 hoặc vòng lặp lớn đã được rà soát:
  - Tránh query DB trong loop nếu không cần.
  - Dùng batch/aggregation khi hợp lý.
- [ ] Những chỗ cache phù hợp (ví dụ embedding, metadata ít đổi) tận dụng được `common/cache.py` hoặc service tương tự.
- [ ] Các config quan trọng (model name, timeout, limit, feature flag) đọc từ cấu hình trung tâm (`config.py` / env), không hard-code rải rác.

### 4. Developer Experience & guardrails <!-- group: 4 -->

- [ ] Có hướng dẫn ngắn gọn trong `backend/readme.md` hoặc README chính:
  - Cách chạy server backend.
  - Cách chạy test: `cd backend && pytest`.
  - Các env quan trọng cần set khi dev/test.
- [ ] `.ralph/guardrails.md` được cập nhật nếu backend/agent hay dính lỗi lặp lại:
  - Ví dụ: truy cập DB khi chưa init Mongo, quên await async, quên commit transaction, v.v.
- [ ] Mọi file backend được sửa trong task này đều:
  - Được format/lint theo rule chuẩn (ví dụ: ruff/black hoặc tool tương đương nếu đã cấu hình trong repo).

## Context / Gợi ý cho Agent

- Luôn đọc các skill sau trước khi thay đổi nhiều:
  - `.cursor/skills/cucu-python-backend/SKILL.md`
  - `.cursor/skills/cucu-api-design/SKILL.md`
  - `.cursor/skills/cucu-testing/SKILL.md`
  - `.cursor/rules/backend-python.md` (nếu tồn tại).
- Không thay đổi triết lý sản phẩm:
  - Backend phục vụ app note đơn giản, tập trung vào ổn định và dễ mở rộng, không over-engineer.
- Ưu tiên:
  - Làm thay đổi nhỏ, an toàn, kèm test, commit thường xuyên.
  - Khi đụng code phức tạp, thêm comment ngắn gọn giải thích ý đồ thay vì refactor “all-in-one” nếu không cần.


