# 07 — User guide: Teddy

> Hướng dẫn dùng nhanh trên site WordPress. Chi tiết tính năng: [06-features.md](06-features.md).

---

## Yêu cầu trước khi dùng

1. WordPress **6.9+** (AI Client), PHP **8.2+**.
2. Cài và cấu hình **WordPress AI Client** + ít nhất một **Connector** (OpenAI / Anthropic / …).
3. Kích hoạt plugin **Teddy**.
4. Tài khoản có quyền quản trị (`manage_options` cho Settings / Copilot đầy đủ).

Teddy **không** nhập API key trong Settings của chính nó — khóa nằm ở connector WP AI.

---

## Lần đầu (Getting Started)

1. Vào **Teddy → Getting Started**.
2. Xác nhận đã backup site.
3. Kiểm tra AI Client / connector sẵn sàng.
4. Bật các mục cần thiết (Copilot, widget khách, SEO…).
5. (Tuỳ chọn) Bật **Knowledge / RAG** rồi đợi / chạy rebuild index.
6. Làm bước gợi ý “viết 1 bài SEO” nếu muốn.
7. Có thể dismiss wizard khi xong — Settings vẫn ở **Teddy → Settings**.

---

## Dùng hàng ngày

### Admin — Copilot

1. **Teddy → Teddy Copilot**.
2. Hỏi bằng ngôn ngữ tự nhiên, ví dụ:
   - “Liệt kê sản phẩm sắp hết hàng”
   - “Tạo draft bài SEO về cà phê rang xay”
   - “Tìm bài viết chưa có alt text ảnh”
3. Với hành động nguy hiểm: xem preview → xác nhận (approval).
4. Nếu đã bật Agent Pipeline: mở “Why this answer” để xem tool / lý do.

### Content — SEO, Classification & Writer

1. Mở bài trong block editor → panel SEO (Teddy) để sinh / chỉnh meta, audit.
2. Panel **Content Classification** → **Suggest terms** → chọn **Apply to post** (chỉ term đã có trên site).
3. Hoặc nhờ Copilot / tool `seo.article.write` tạo draft.
4. **Teddy Writer**: generate / revise nội dung theo brief.

### Comments — Moderation & Suggest Reply

1. **Teddy → Settings → Comments**:
   - Bật **AI comment moderation** nếu muốn giữ bình luận khách và phân tích nền (tắt mặc định).
   - Bật **Suggest Reply** để thấy action trên Comments và Dashboard.
2. Trên **Comments**, bấm **Suggest Reply** → copy hoặc **Use in reply box** → gửi thủ công.
3. Khi moderation bật: bình luận khách mới vào hàng chờ; job nền có thể approve hoặc đánh spam. Lỗi AI → giữ hold.

**Lưu ý:** Nội dung bình luận được gửi tới connector AI đã cấu hình. Có thể chạy song song với WordPress AI Experiments (Comment Moderation) — nên chỉ bật một lớp auto-moderation nếu không muốn xung đột.

### Khách — Chat widget

1. Bật Support chatbot trong Settings (mặc định ON).
2. Widget nổi trên frontend, hoặc chèn shortcode `[teddy_chat]` / block Gutenberg.
3. Muốn trả lời theo nội dung shop/blog: bật **RAG**, rebuild index, đảm bảo embeddings hoạt động.

### Facebook Messenger

1. Checklist Meta App: [modules/channels/README.md](modules/channels/README.md).
2. **Teddy → Settings → Channels**: bật Messenger, dán Page access token + verify token (và App secret nếu có).
3. Callback URL: `https://YOUR-DOMAIN/wp-json/teddy/v1/channels/facebook/webhook`
4. Local Docker cần HTTPS tunnel (Meta không gọi `*.test`).
5. Nhắn thử vào Page (Development mode: chỉ tài khoản có role trên app).

### WooCommerce

1. WooCommerce active + flag Woo trong Settings ON.
2. Qua Copilot hỏi đơn hàng / tồn kho / list sản phẩm / cập nhật giá (có duyệt nếu nguy hiểm).

---

## Bật tính năng nâng cao

Trong **Teddy → Settings** (hoặc Getting Started):

| Muốn… | Bật flag |
|-------|----------|
| Trả lời khách theo kiến thức site + nguồn | `enable_rag` + reindex |
| Audit đầy đủ + Observability + Security UI | `use_agent_pipeline` |
| Publish Product nhiều bước / resume | `enable_workflows` |
| Plugin khác đăng ký tool | `enable_extension_sdk` |

Sau khi bật Agent Pipeline / Workflows, menu tương ứng xuất hiện dưới **Teddy**.

### Chọn provider và model

1. Vào **Teddy → Settings → Model**.
2. **Model provider**: chọn **Auto** (Teddy tự chọn connector đã cấu hình) hoặc một provider cụ thể. Chỉ connector đã cấu hình trong **Settings → Connectors** mới xuất hiện.
3. **Model**: chọn **Auto (provider default)** hoặc một model text-generation từ danh sách động. Khi provider là Auto, model hiển thị kèm tên provider (ví dụ `Google — Gemini 2.5 Flash`).
4. Model local/Ollama và Gemini Flash có nhãn gợi ý (local / free tier); chi phí thực tế vẫn phụ thuộc tài khoản connector và quota.
5. Nếu chưa có connector: bấm link **Settings → Connectors** ngay trên form.

---

## Kiểm tra sức khỏe

1. **Security** (khi Agent Pipeline on): chạy checklist, sửa finding Critical/High.
2. **Observability**: xem audit log và ước lượng token/cost.
3. **Knowledge status**: số embedding, phase cursor (Settings / REST).
4. Provider: đổi connector trong hệ WP AI, chọn preference provider/model trong Teddy Settings nếu cần.

---

## Gỡ cài / dữ liệu

- Mặc định **không** xóa bảng Teddy khi uninstall.
- Bật `delete_data_on_uninstall` trước khi gỡ nếu muốn dọn sạch.

---

## Khi gặp lỗi thường gặp

| Hiện tượng | Việc cần thử |
|------------|--------------|
| Chat trống / lỗi provider | Connector WP AI, model, quota |
| Enable RAG rồi trang trắng / “not allowed” | Cập nhật plugin; Getting Started vẫn được đăng ký ẩn — vào lại Settings |
| RAG không cite nguồn | Index đã chạy? Embedding available? `enable_rag` on? |
| Tool bị chặn | Capability user; approval token cho tool nguy hiểm |
| Playwright / E2E | Xem README + `docs/06-features.md` §9 |

---

## Tiếp theo

- Catalog đầy đủ: [06-features.md](06-features.md)
- Viết extension: [EXTENSION_GUIDE.md](EXTENSION_GUIDE.md)
- Index docs: [README.md](README.md)