ad-claim-compliance

name

ad-claim-compliance

description

Kiểm tra tuân thủ Luật Quảng cáo về từ ngữ tuyệt đối trên content/website — phát hiện 'nhất', 'duy nhất', 'tốt nhất', 'số một', 'số 1', 'hàng đầu' và từ ngữ ý nghĩa tương tự (vị thế dẫn đầu/độc bản/tuyệt đối) theo TT 12/2026 + khoản 11 Điều 8 Luật Quảng cáo. 2-stage: Pass 1 detect→verdict+nguyên tắc reword (OPT 2, quét toàn portfolio, nhẹ); Pass 2 on-demand auto-generate câu thay thế giữ keyword + đúng char-limit (OPT 1). Verdict: VIOLATION/NEEDS_PROOF/PROOF_NOT_CITED/REVIEW/OK. Risk score = vị trí × page type × ngành YMYL. Evidence Registry per-client (tài liệu Điều 3.2 → claim OK; check citation Điều 3.4). 2 mode: standalone audit domain/portfolio + embedded gate trong qc-content/xay-dung-noi-dung/optimize-seo-page/refresh-content. Trigger: check tuân thủ quảng cáo, compliance từ ngữ, kiểm tra 'nhất'/'duy nhất'/'tốt nhất'/'số 1', superlative check, từ ngữ tuyệt đối, content vi phạm, audit ad claim. MCP: sf-enhanced, search-console, data-cache. Output Excel + terminal dashboard. Confirm cost trước crawl.

Ad Claim Compliance — Kiểm tra từ ngữ quảng cáo tuyệt đối

Mục tiêu duy nhất: Không để client bị xử phạt vì dùng từ ngữ tuyệt đối ("nhất", "duy nhất", "tốt nhất", "số một", "hàng đầu"...) trong content/website mà không có tài liệu hợp pháp chứng minh.

Triết lý: Detect trước, review sau, fix sau cùng. KHÔNG auto-reword mù toàn portfolio (đốt token + tạo bản nháp vô dụng cho claim mà writer chưa quyết giữ/bỏ). User phải XEM finding + verdict + nguyên tắc trước, rồi mới chọn claim nào cần auto-generate câu thay thế.

Cơ sở pháp lý (hiệu lực 05/07/2026):

• Khoản 11 Điều 8 Luật Quảng cáo: cấm dùng "nhất", "duy nhất", "tốt nhất", "số một" hoặc từ ngữ ý nghĩa tương tự mà không có tài liệu hợp pháp chứng minh.
• TT 12/2026/TT-BVHTTDL Điều 3: định nghĩa "từ ngữ tương tự" + 2 loại tài liệu chứng minh + quy định hiển thị citation.
• TÊN SKILL KHÔNG gắn số TT — Thông tư đổi số nhưng Điều 8 Luật QC là nền tảng bền. Khi luật cập nhật chỉ sửa references/lexicon.md + cơ sở pháp lý, không đổi skill.

⚖️ Giới hạn: Skill là heuristic compliance ở mức vận hành, KHÔNG phải tư vấn pháp lý. Vùng REVIEW (gray zone) + claim client ngân hàng/tài chính/y tế nên để legal client confirm trước khi sửa hàng loạt.

---

2 CHẾ ĐỘ

Mode	Input	Dùng khi
Standalone	1 domain HOẶC list domain (portfolio)	Audit trước deadline 5/7, onboard client mới, audit định kỳ
Embedded gate	1 bài/URL/raw content	Tự trigger trong content pipeline, chặn superlative TRƯỚC khi lên production

---

⚡ TỰ TRIGGER (Embedded gate)

Skill chạy như 1 gate compliance trong các pipeline content. KHÔNG cần user gọi tay:

qc-content            → sau khi chấm 12-dim, gate compliance TRƯỚC verdict PASS
xay-dung-noi-dung     → sau khi viết, TRƯỚC khi xuất DOCX/đăng
optimize-seo-page     → khi rewrite title/meta/H1 → check claim mới sinh ra
refresh-content       → khi update content cũ → check claim trong bản mới
research-quotation    → check claim trong sample content client gửi pitch
client-report-monthly → flag claim risk trong "Technical/Content" section nếu có

Hành vi gate: chỉ chạy Pass 1 (detect + verdict + nguyên tắc) trên content đang xử lý. Nếu có VIOLATION ở title/meta/H1 → BLOCK, báo finding, không cho pipeline xuất bản cho tới khi xử lý. Body VIOLATION → WARN, cho qua nhưng note vào output.

Opt-out: "skip compliance", "không cần check quảng cáo".

---

ENGINE — 4 LAYER

Layer 1 — DETECTION

Lexicon đầy đủ ở references/lexicon.md (3 nhóm theo Điều 3.1 + exception list + EN). Đọc file đó khi chạy.

Nguồn quét (Standalone, ưu tiên field hiển thị công khai):

• Title tag · Meta description · H1 · H2/H3 · Body · Schema (name, description) · Image alt · OG title/description

3 nhóm match (Điều 3.1):

• Nhóm A — Vị thế dẫn đầu: hàng đầu, dẫn đầu, đứng đầu, tiên phong, đầu ngành, top 1, đầu tiên · EN: leading, #1, no.1, market leader, pioneer
• Nhóm B — Tính độc bản: duy nhất, độc nhất, độc quyền, chỉ có tại, không nơi nào có, có một không hai · EN: only, the only, exclusive, one-of-a-kind
• Nhóm C — Tính tuyệt đối: nhất, số một, số 1, tốt nhất, hoàn hảo, tuyệt đối, vô địch, vượt trội, xuất sắc nhất, uy tín nhất · EN: best, finest, ultimate, perfect, unmatched, world-class

Pattern VN X nhất (chỗ khó nhất — false positive cao):

• Match mọi cụm \S+\s+nhất → candidate.
• BẮT BUỘC lọc qua exception list (references/lexicon.md): thống nhất, đồng nhất, nhất quán, nhất trí, thứ nhất, hợp nhất, nhất thời, nhất loạt, nhất là, nhất định, nhất thiết... → KHÔNG phải claim, loại bỏ.
• "duy nhất / độc nhất / đệ nhất / hạng nhất" → GIỮ (là claim).
• Khi không chắc 1 cụm X nhất có phải claim → đưa vào verdict REVIEW, không tự loại.

EN superlative: word list ở trên + pattern \b\w+est\b (cheapest, fastest, finest), lọc stopword (honest, interest, latest-as-recent...).

Mỗi finding lưu: url | location | matched_term | nhom | snippet (±8 từ ngữ cảnh) | page_type | industry.

Layer 2 — RISK SCORE

RiskScore = base(location) × mult(page_type) × mult(industry)

location	base		page_type	mult		industry	mult
Title tag	5		Money/PLP/Landing/Home	1.5		Banking/Finance/Insurance	1.5
Meta desc	4		Service/Product detail	1.3		Health/Pharma/Dental	1.5
H1	4		About/Profile	1.0		Khác	1.0
Schema name/desc	3		Blog informational	0.7
Body (đầu trang)	3
Body (sâu) / alt	2

Tier: HIGH ≥6 · MED 3–6 · LOW <3. Hard rule (override): superlative ở Title/Meta trên Money page ngành YMYL = auto HIGH bất kể điểm.

Layer 3 — VERDICT

Verdict	Điều kiện	Handling
VIOLATION	Claim KHÔNG có trong Evidence Registry + page type là quảng cáo (không phải blog trung lập)	→ OPT 1 hoặc OPT 2
NEEDS_PROOF	Claim có thể giữ NẾU client cấp tài liệu Điều 3.2 (đáng để xin proof — claim mạnh, trang quan trọng)	→ request doc; có doc → register → OK; không có → VIOLATION
PROOF_NOT_CITED	Claim CÓ proof trong Registry, nhưng page CHƯA hiển thị tên tài liệu + số/ký hiệu + thời gian (vi phạm hình thức Điều 3.4)	→ bổ sung dòng citation lên page, không cần đổi claim
REVIEW	Gray zone: blog informational, hoặc cụm X nhất không chắc là claim, hoặc ngữ cảnh mơ hồ	→ human phán, không auto
OK	Trong Registry còn hiệu lực + đã cite đúng Điều 3.4 · HOẶC false-positive đã loại · HOẶC ngữ cảnh thông tin trung lập rõ ràng	→ bỏ qua

Layer 4 — EVIDENCE REGISTRY (per-client)

Input optional: file registry per-client (template assets/evidence-registry-template.csv). Liệt kê các claim ĐÃ có tài liệu hợp pháp:

claim_text | claim_normalized | proof_type(survey/award) | proof_name | proof_number | issuer | valid_from | valid_to | source_url

Logic:

• Normalize claim text (lowercase, bỏ dấu câu) → match finding với registry.
• Match + còn hiệu lực (valid_to ≥ hôm nay) + page đã cite → OK.
• Match + còn hiệu lực + page CHƯA cite → PROOF_NOT_CITED.
• Match nhưng valid_to < hôm nay → VIOLATION (proof hết hạn, Điều 3.3) + cờ expired.
• Không có registry → mọi claim chạy verdict bình thường (không claim nào auto-OK).

Layer này tách "vi phạm thật" khỏi "claim hợp lệ có giấy tờ". Thiếu nó → skill spam false alarm cho client có chứng nhận thật.

---

🔑 2-STAGE FLOW — OPT 1 & OPT 2

Đây là logic cốt lõi. Hai option là action per-finding, KHÔNG phải mode toàn skill. Default chạy Pass 1 cho tất cả, OPT 1 chỉ chạy khi user chọn ở Pass 2.

PASS 1 — Detect + Verdict + Nguyên tắc (= OPT 2, luôn chạy, nhẹ)

Quét toàn bộ → mỗi finding ra: url · location · term · risk tier · verdict · NGUYÊN TẮC reword áp dụng.

NGUYÊN TẮC reword (không generate câu, chỉ chỉ hướng — references/reword-playbook.md):

• P1 — Quantify: thay claim tuyệt đối bằng số liệu provable ("giảm 30% thời gian" thay "nhanh nhất").
• P2 — Hedge: "một trong những...", "được nhiều khách hàng tin chọn".
• P3 — Factual scope: dữ kiện chứng minh được ("10 năm kinh nghiệm", "5.000+ khách hàng").
• P4 — Strip: bỏ superlative, giữ noun ("dịch vụ SEO" thay "dịch vụ SEO tốt nhất").
• P5 — Substantiate: giữ nguyên claim, đi xin tài liệu Điều 3.2 (chỉ khi NEEDS_PROOF + đáng đầu tư).

→ Output Pass 1 (dashboard + Excel) cho user review. DỪNG ở đây. Hỏi user chọn xử lý.

PASS 2 — Auto Reword (= OPT 1, on-demand, chỉ chạy khi chọn)

User chọn scope cần auto-generate: theo verdict (vd "tất cả VIOLATION"), theo client, theo URL list, hoặc từng finding. Với mỗi finding được chọn, generate 2–3 câu thay thế tuân thủ:

1. Giữ target keyword — bản thay thế phải SEO-tương đương, không giết keyword. (Đây là value của agency, không phải chỉ "an toàn pháp lý".)
2. Đúng char-limit slot: Title ≤60 ký tự · Meta 150–160 · H1 linh hoạt · giữ nguyên format slot.
3. Áp nguyên tắc P1–P4 theo references/reword-playbook.md, ưu tiên P1/P3 (provable) cho ngành YMYL.
4. Mỗi variant kèm note: nguyên tắc dùng + variant nào giữ keyword mạnh nhất + char count.

Output Pass 2: bảng finding → 2-3 variants → recommended append vào Excel (sheet Reword) + ghi đè được nếu user duyệt.

Routing handling theo verdict:

VIOLATION        → user chọn OPT 1 (auto reword) hoặc OPT 2 (giao writer tự sửa theo nguyên tắc)
NEEDS_PROOF      → action = request tài liệu Điều 3.2 từ client
                   → có tài liệu: thêm vào Registry → OK
                   → không có:    chuyển VIOLATION → OPT 1/OPT 2
PROOF_NOT_CITED  → action = bổ sung dòng citation (tên TL + số + thời gian) lên page; KHÔNG đổi claim
REVIEW           → human phán; nếu xác định là claim → VIOLATION → OPT 1/OPT 2
OK               → no action

---

CONFIRM DIALOG (Standalone, trước khi crawl)

KHÔNG auto-run crawl. Hiển thị estimate trước:

═══ AD CLAIM COMPLIANCE — CONFIRM ═══
Domain(s):      {list}
URL ước tính:   {N} (từ sitemap/GSC)
Crawl scope:    Title + Meta + H1 + H2/H3 + Body + Schema + Alt
Ngành:          {industry} (YMYL multiplier: {×})
Evidence Registry: {có / không có — nếu không, mọi claim chạy verdict đầy đủ}
Cost ước tính:  sf-enhanced crawl {N} URL (~{phút})

Chọn:
(A) Full crawl toàn site
(B) Sample — chỉ URL có GSC impressions (ưu tiên trang đang hiển thị SERP)
(C) Hủy

Mặc định gợi ý (B) cho portfolio lớn — sửa trang đang hiển thị SERP trước là ưu tiên thực tế.

---

OUTPUT

Phần 1 — Terminal dashboard (BẮT BUỘC, render đầu tiên — visualize:show_widget)

Cho CEO/Account nắm nhanh. ≥5 sections:

┌─ AD CLAIM COMPLIANCE ─────────────────────────────┐
│ Domain | Audit date | URLs scanned | Industry      │
├───────────────────────────────────────────────────┤
│ TỔNG: {N} findings  →  HIGH {n} · MED {n} · LOW {n}│
│ VERDICT: VIOLATION {n} · NEEDS_PROOF {n} ·         │
│          PROOF_NOT_CITED {n} · REVIEW {n} · OK {n} │
├───────────────────────────────────────────────────┤
│ Top URL rủi ro (HIGH, có GSC impressions)          │
│ Phân bố theo location (Title/Meta/H1/Body)         │
│ Phân bố theo nhóm từ (A/B/C)                       │
│ QC Score: {N}/100 [verdict]                        │
└───────────────────────────────────────────────────┘
═══ Excel saved: {path} ═══

Phần 2 — Excel (sheets)

Sheet	Nội dung
1. Dashboard	Tổng hợp số liệu, charts (verdict pie, location bar, risk histogram), QC badge
2. Findings	url · location · term · nhom · snippet · page_type · industry · risk_score · risk_tier · verdict · nguyên_tắc (OPT 2 luôn có)
3. Action List	Group theo client → verdict → URL. Cột: action (reword/request-doc/add-citation/review) · priority (P1–P5) · GSC impressions
4. Reword	(chỉ điền sau Pass 2) finding · variant_1/2/3 · principle · recommended · char_count · keyword_kept
5. Needs Proof	Claim đáng xin tài liệu Điều 3.2 → checklist gửi client
6. Evidence Registry	Mirror registry đã load + cờ expired/not-cited

Sort Findings + Action theo GSC impressions desc (trang hiển thị SERP nhiều = ưu tiên). Path: ~/compliance/{domain}-adclaim-{date}.xlsx

---

QC RUBRIC

BẮT BUỘC self-check trước khi output. PASS ≥80/100. FIX/FAIL → fix hoặc rebuild.

Dim	Hạng mục	Điểm	Check
D1	Detection coverage	15	Quét đủ Title/Meta/H1/H2-3/Body/Schema/Alt? Cả 3 nhóm + pattern X nhất + EN?
D2	False-positive control	15	Đã lọc exception list nhất? Không flag thống nhất/đồng nhất/thứ nhất...? Spot-check 5 finding X nhất đúng là claim?
D3	Risk score	10	Công thức location × page_type × industry áp đúng? Hard rule YMYL+Title/Meta = HIGH áp dụng?
D4	Verdict đúng	15	5 verdict gán đúng logic? NEEDS_PROOF vs VIOLATION phân biệt rõ? PROOF_NOT_CITED check Điều 3.4?
D5	Evidence Registry	10	Có registry: match + check hiệu lực (3.3) + check citation (3.4)? Không registry: không auto-OK claim nào?
D6	2-stage tách bạch	10	Pass 1 KHÔNG auto-generate reword? OPT 1 chỉ chạy khi user chọn? Routing per-verdict đúng?
D7	Reword chất lượng (nếu Pass 2)	10	Variant giữ keyword? Đúng char-limit? Áp P1-P4 đúng? YMYL ưu tiên provable?
D8	Confirm + Dashboard	10	Standalone: confirm dialog trước crawl, không auto-run? Render terminal dashboard NGAY ĐẦU, ≥5 sections?
D9	Output & Formatting	5	Excel đủ sheets? Sort theo GSC impressions? Save đúng path? Báo path? Font TNR? Gridlines ẩn? Border có? Text canh giữa?

Verdict: 90-100 EXCELLENT · 80-89 PASS · 65-79 FIX · <65 FAIL

Auto-FAIL:

• Pass 1 tự ý generate reword toàn bộ (vi phạm 2-stage)
• Flag thống nhất/đồng nhất/thứ nhất là claim (false-positive cơ bản)
• Auto-OK claim không có trong registry
• Standalone skip confirm dialog (auto crawl trái rule)
• Không render terminal dashboard

Inline trong output: dòng QC Score: {N}/100 [verdict]. Nếu FIX/FAIL → note lý do → tự fix → rerun QC → output.

---

CROSS-SKILL

• qc-content: thêm gate compliance — finding VIOLATION ở title/meta/H1 chặn verdict PASS của qc-content.
• xay-dung-noi-dung / optimize-seo-page: check title/meta/H1 mới sinh trước khi xuất.
• data-cache: cache crawl result theo domain (TTL 48h) tránh re-crawl khi chạy lại trong ngày.
• client-report-monthly: đưa compliance status vào section content nếu client thuộc nhóm rủi ro.

EXCEL FORMATTING STANDARD

BẮT BUỘC áp cho MỌI sheet trong output Excel. Không có ngoại lệ.

4 quy tắc cứng

#	Quy tắc	Chi tiết
F1	Font Times New Roman	Toàn bộ cell (kể cả header) dùng name='Times New Roman'. Không dùng Calibri, Arial hay font mặc định.
F2	Text canh giữa ô	Alignment(horizontal='center', vertical='center', wrap_text=True) cho tất cả cell. Ngoại lệ duy nhất: cell chứa URL dài → horizontal='left'.
F3	Tạo bảng có border	Mọi vùng data dùng Border với Side(style='thin') cho 4 cạnh. Header row dùng Side(style='medium') bottom để phân tách.
F4	Ẩn Gridlines	Mỗi sheet: ws.sheet_view.showGridLines = False. Áp TRƯỚC KHI save.

Code snippet chuẩn (import 1 lần, dùng lại cho mọi skill)

from openpyxl.styles import Font, PatternFill, Alignment, Border, Side

TNR = 'Times New Roman'

def fmt_cell(ws, row, col, val,
             bg=None, bold=False, sz=10,
             fg='00000000', align_h='center'):
    """Cell chuẩn: TNR + canh giữa + border."""
    c = ws.cell(row=row, column=col, value=val)
    c.font = Font(name=TNR, bold=bold, size=sz, color=fg)
    c.alignment = Alignment(
        horizontal=align_h,    # 'left' chỉ khi URL hoặc long text
        vertical='center',
        wrap_text=True
    )
    if bg:
        c.fill = PatternFill('solid', fgColor=bg)
    # Border luôn có
    thin  = Side(style='thin',   color='FFD1D5DB')
    medium = Side(style='medium', color='FF9CA3AF')
    c.border = Border(left=thin, right=thin, top=thin, bottom=thin)
    return c

def fmt_header(ws, row, col, val, bg='FF1E293B', sz=10):
    """Header: TNR bold white + medium bottom border."""
    c = fmt_cell(ws, row, col, val, bg=bg, bold=True, sz=sz, fg='FFFFFFFF')
    thin   = Side(style='thin',   color='FFD1D5DB')
    medium = Side(style='medium', color='FF9CA3AF')
    c.border = Border(left=thin, right=thin, top=thin, bottom=medium)
    return c

def hide_gridlines(ws):
    """Ẩn gridlines — gọi mỗi sheet trước khi save."""
    ws.sheet_view.showGridLines = False

Checklist apply (trước wb.save)

for sheet in wb.worksheets:
    hide_gridlines(sheet)   # F4: ẩn gridlines toàn bộ
# F1+F2+F3 đã apply trong fmt_cell / fmt_header

---

REFERENCES

• references/lexicon.md — lexicon đầy đủ 3 nhóm + exception list nhất + EN superlative + stopword. ĐỌC khi chạy Layer 1.
• references/reword-playbook.md — nguyên tắc P1–P5 + before/after patterns theo ngành. ĐỌC khi chạy Pass 2 (OPT 1) hoặc khi cần nêu nguyên tắc chi tiết ở Pass 1.
• assets/evidence-registry-template.csv — template registry giao client điền.

MCP & COST

sf-enhanced (crawl, primary — requires local Screaming Frog + MCP server) · search-console (GSC impressions) · data-cache (optional, tránh re-crawl). Community fallback: nếu không có sf-enhanced, skill dùng search-console (GSC impressions), vẫn không có search-console thì dùng web_fetch để crawl Title/Meta/H1 trực tiếp (chậm hơn, giới hạn ~50 URLs).

MỞ RỘNG (skeleton, chưa implement)

• Module 2 — Comparative claims: so sánh trực tiếp đối thủ (khoản 10 Điều 8 Luật QC cấm). Detect "hơn [tên đối thủ]", "tốt hơn X".
• Module 3 — Industry claims: y tế/TPCN ("chữa khỏi", "điều trị", "100% an toàn"), tài chính ("cam kết lợi nhuận", "lãi suất cao nhất"). Lexicon ngành riêng.