Thiết kế Flow & Guardrail — AI tạo đánh giá

Hạng mục	Nội dung
Trạng thái	🟡 Đang thảo luận
Liên quan	AI tạo đánh giá

1. Tổng quan Guardrail

Hệ thống có 5 lớp bảo vệ đảm bảo chất lượng và an toàn:

2. ① Rate Limit — Giới hạn tần suất

Thiết kế

Mục	Nội dung
Giới hạn	100 lượt generate/ngày/cửa hàng
Count gì	`generate-review` + `regenerate-review` (gọi Sonnet, tốn chi phí)
Enforce	DB count trên `mappy_review_generation_logs`
Reset	Hàng ngày (theo ngày server)

Logic

Implementation

php

private function checkRateLimit(int $shopId): void
{
    $todayCount = ReviewGenerationLog::where('shop_id', $shopId)
        ->whereIn('generation_type', ['initial', 'regenerate', 'tone_change'])
        ->whereDate('created_at', today())
        ->count();

    if ($todayCount >= config('services.review_generator.daily_limit', 100)) {
        throw new RateLimitExceededException();
    }
}

Tại sao 100/ngày?

Quy mô cửa hàng	Khảo sát/ngày	Generate/khảo sát	Tổng/ngày
Nhỏ (1 chi nhánh)	5-10	~2 lần (1 generate + 1 regenerate)	10-20
Lớn (5 chi nhánh)	20-50	~2 lần	40-100

100 là đủ cho cửa hàng lớn. Nếu cần điều chỉnh → REVIEW_DAILY_LIMIT trong .env.

3. ② Prompt Guardrail — Ràng buộc trong prompt

Các ràng buộc được nhúng trực tiếp trong system prompt để ngăn LLM tạo output không mong muốn:

Ràng buộc chất lượng

#	Ràng buộc	Trong prompt	Mục đích
1	Số ký tự 200-400	`文字数: 200〜400文字`	Tránh quá ngắn/dài
2	Cấu trúc cố định	`来店のきっかけ → 体験の詳細 → 感想・まとめ`	Đảm bảo logic
3	Keyword tự nhiên	`無理に全て入れる必要はない`	Tránh nhồi keyword
4	Đa dạng	`毎回異なる書き出し・構成・表現を使う`	Tránh trùng lặp giữa các review

Ràng buộc chống phát hiện AI

#	Ràng buộc	Trong prompt	Mục đích
5	Cấm liệt kê	`箇条書き形式を避ける`	AI hay tạo bullet point
6	Cấm từ nối máy móc	`「まず」「次に」「最後に」を避ける`	Dấu hiệu AI điển hình
7	Cấm khen quá mức	`過度な褒め言葉の連続を避ける`	Không tự nhiên
8	Cấm giọng quảng cáo	`「〜がおすすめです」を避ける`	Vi phạm Google policy
9	Thêm yếu tố con người	`小さな感想や個人的なエピソードを含める`	Tạo cảm giác thực

Ràng buộc tone

Tone	Ràng buộc trong prompt
丁寧	`敬語を使用。30〜50代の落ち着いた印象`
カジュアル	`友人に話すような口調。20〜30代の明るい印象`
ビジネス	`客観的で簡潔。ビジネスパーソンの印象`

4. ③ Quality Check — Kiểm tra chất lượng Hybrid

Tổng quan flow

Bước 1: Rule-based (tức thì, miễn phí)

#	Tiêu chí	Điểm tối đa	Logic	Fail sớm
1	Số ký tự (200-400)	20	`mb_strlen()`	Dưới 100 hoặc trên 600 → skip LLM
2	Phản ánh keyword (1-3 từ)	15	`str_contains()`	—
	Tổng bước 1	35		< 15 → skip LLM, retry ngay

Decision matrix:

Ký tự	Keyword found	Điểm rule	Hành động
280 (OK)	2/3	30	→ Tiếp tục LLM check
150 (NG)	1/3	5	→ Skip LLM, retry ngay
350 (OK)	0/3	20	→ Tiếp tục LLM check
50 (NG)	0/3	0	→ Skip LLM, retry ngay

Bước 2: LLM Check (Haiku 4.5)

#	Tiêu chí	Điểm tối đa	Kiểm tra
3	Tự nhiên (không AI-like)	30	Cấu trúc, từ nối, đa dạng
4	Biểu đạt không phù hợp	20	Quảng cáo, phóng đại, sai sự thật
5	Phản ánh đúng trọng tâm (mục đã chọn)	15	Review có tập trung vào mục sao cao nhất đã chỉ định
	Tổng bước 2	65

Tổng hợp điểm

	Tối đa	Đạt tối thiểu
Bước 1 (rule)	35	—
Bước 2 (LLM)	65	—
Tổng	100	>= 70

quality_breakdown JSON format

Đạt (có LLM check):

json

{
  "rule_based": {
    "char_count": { "score": 20, "detail": "280文字。範囲内。" },
    "keywords": { "score": 10, "detail": "2/3 keyword found" }
  },
  "llm": {
    "naturalness": { "score": 25, "detail": "概ね自然。" },
    "inappropriate": { "score": 20, "detail": "問題なし。" },
    "topic_reflection": { "score": 12, "detail": "指定項目（接客）が中心に反映されている。" },
    "feedback": ""
  },
  "total": 87,
  "passed": true
}

Fail (LLM skipped):

json

{
  "rule_based": {
    "char_count": { "score": 0, "detail": "52文字。範囲外。" },
    "keywords": { "score": 5, "detail": "1/3 keyword found" }
  },
  "llm": null,
  "total": 5,
  "passed": false
}

5. ④ Retry Strategy — Chiến lược thử lại

Flow

Chi tiết retry

Lần	Temperature	Đặc điểm
1 (initial)	0.8	Generate bình thường
2 (retry 1)	0.9	Cao hơn → output khác biệt hơn
3 (retry 2)	0.9	Kèm feedback cụ thể từ lần trước

Thông tin truyền vào retry

【前回のスコア】52/100
【改善フィードバック】「まず」「次に」の接続詞が目立つ。箇条書き的な構成を避け...
※ 前回と異なる書き出し・構成で書いてください。

Thống kê dự kiến

Kết quả	Tỷ lệ
Đạt lần 1	~80%
Đạt sau retry 1	~15%
Đạt sau retry 2	~4%
Fail (3 lần hết)	~1%

6. ⑤ Error Fallback — Xử lý lỗi

Nguyên tắc

Khi AI fail, luôn fallback về nút Google Review. Không bao giờ block flow của khách hàng.

Decision matrix

Lỗi	HTTP	Frontend hiển thị	Có block flow?
Anthropic API timeout	503	Màn cảm ơn thường + nút Google Review	Không
Generate fail (3 retry hết)	500	"生成に失敗しました" + nút "もう一度試す" + nút Google Review	Không
Rate limit	429	"本日の生成上限に達しました" + nút Google Review	Không
Tone không hợp lệ	400	Không xảy ra (UI chỉ cho 3 option)	—
Khảo sát không tồn tại	404	Không xảy ra (dùng data vừa submit)	—
JSON parse fail (quality-check)	—	Tự động retry (điểm 0)	Không

Flow frontend

7. Đối sách Google Policy

Google phát hiện AI review bằng cách nào?

#	Phương pháp	Đối sách trong hệ thống
1	Phân tích mẫu văn bản — cùng cửa hàng lặp lại	temperature 0.8 + nội dung dựa trên mục đánh giá thực tế + "毎回異なる構成"
2	Phân tích thời gian đăng — nhiều bài liên tục	1 bài/flow, không batch
3	Phân tích IP/thiết bị — cùng IP nhiều bài	Khách tự đăng từ thiết bị/account mình
4	NLP phát hiện AI — văn phong quá hoàn hảo	Prompt cấm liệt kê, khen quá mức, thêm yếu tố con người
5	Mật độ keyword — SEO spam	"1〜3個", "無理に入れない"
6	Nội dung chung chung — không có trải nghiệm thực	Tạo từ dữ liệu khảo sát thực tế

Đối sách bắt buộc trên UI

Màn review (bắt buộc):

⚠ この文章はお客様のアンケート回答をもとにAIが作成した下書きです。
投稿される口コミはお客様ご自身の感想として公開されます。
実際のご体験に合っているかご確認のうえ、必要に応じて編集してからご投稿ください。

Sau khi nhấn đăng:

口コミの下書きが保存されました。
下記のリンクからGoogleマップを開いて、ご自身のアカウントで投稿してください。
[Googleマップで口コミを書く →]

Checklist tuân thủ

#	Đối sách	Đã thiết kế?
1	Khách tự đăng (không auto-post)	✅ Submit → redirect Google Maps
2	Khuyến khích chỉnh sửa	✅ Cảnh báo AI + textarea edit
3	Văn phong đa dạng	✅ temperature 0.8 + nội dung theo mục đánh giá + đổi tone
4	Keyword tự nhiên	✅ "1〜3個" + "無理に入れない"
5	1 bài/flow	✅ Không có batch generate
6	Phát hiện AI trong quality check	✅ naturalness score (30 điểm)
7	Ghi log toàn bộ	✅ `mappy_review_generation_logs`

8. Monitoring & Metrics

Metrics cần theo dõi

Metric	Query	Alert khi
Tỷ lệ đạt lần 1	`WHERE retry_count = 0 AND quality_score >= 70`	< 70%
Tỷ lệ fail hoàn toàn	`WHERE retry_count >= 3`	> 5%
Chi phí/ngày	`SUM(cost_yen) GROUP BY DATE`	> ¥1,000
Latency trung bình	Thời gian từ request → response	> 15s
Rate limit hits	Count 429 responses	> 10/ngày

Log table đã có sẵn

Tất cả metrics trên có thể query từ mappy_review_generation_logs:

quality_score, retry_count → tỷ lệ đạt/fail
cost_yen → chi phí
input_tokens, output_tokens → usage
created_at → latency (kết hợp với request log)

Thiết kế Flow & Guardrail — AI tạo đánh giá ​

1. Tổng quan Guardrail ​

2. ① Rate Limit — Giới hạn tần suất ​

Thiết kế ​

Logic ​

Implementation ​

Tại sao 100/ngày? ​

3. ② Prompt Guardrail — Ràng buộc trong prompt ​

Ràng buộc chất lượng ​

Ràng buộc chống phát hiện AI ​

Ràng buộc tone ​

4. ③ Quality Check — Kiểm tra chất lượng Hybrid ​

Tổng quan flow ​

Bước 1: Rule-based (tức thì, miễn phí) ​

Bước 2: LLM Check (Haiku 4.5) ​

Tổng hợp điểm ​

quality_breakdown JSON format ​

5. ④ Retry Strategy — Chiến lược thử lại ​

Flow ​

Chi tiết retry ​

Thông tin truyền vào retry ​

Thống kê dự kiến ​

6. ⑤ Error Fallback — Xử lý lỗi ​

Nguyên tắc ​

Decision matrix ​

Flow frontend ​

7. Đối sách Google Policy ​

Google phát hiện AI review bằng cách nào? ​

Đối sách bắt buộc trên UI ​

Checklist tuân thủ ​

8. Monitoring & Metrics ​

Metrics cần theo dõi ​

Log table đã có sẵn ​