PRD: Thu thập lead & người đăng ký
| Module | Marketing (EXT-02) | PRD ID | PRD-CAP-001 |
| Status | Shipped | Owner | Marketing squad |
| Date | 2026-04-03 | Version | v1.0 |
| Packages | @nx/outreach · @nx/core | URD | CAP |
TL;DR
Cho phép trang marketing công khai thu thập các lead quan tâm - yêu cầu liên hệ/bán hàng/demo (inquiry) và người đăng ký bản tin (subscriber) - và cung cấp cho admin một bản đọc trực tiếp về tập người đăng ký. Việc subscribe là idempotent theo email, unsubscribe được tôn trọng qua token, và một endpoint thống kê cho admin báo cáo tổng số, mức tăng trưởng hàng tháng, cùng tỷ lệ active/deactivated. Kết quả: một danh sách đối tượng sạch, không trùng lặp, tôn trọng opt-out, sẵn sàng vận hành các chiến dịch dự kiến ở Giai đoạn 2.
1. Bối cảnh & Vấn đề
Nhà bán muốn xây dựng tập đối tượng từ trang công khai của mình - những người truy cập yêu cầu demo, liên hệ bán hàng, hoặc đăng ký nhận bản tin. Nếu không có bề mặt thu thập, các tín hiệu này bị mất hoặc rải rác qua các kênh tạm bợ: không có danh sách người đăng ký không trùng lặp, không có việc cưỡng chế unsubscribe, và admin không có cách nào đánh giá tập đối tượng đang tăng trưởng ra sao. Khoảng trống đó chặn mọi công việc chiến dịch gửi đi sau này, vốn phụ thuộc vào một tập người đăng ký sạch và tôn trọng opt-out.
Tính năng này thiết lập nền tảng thu thập trong @nx/outreach: ghi nhận inquiry và đăng ký bản tin, giữ danh sách người đăng ký idempotent và an toàn opt-out, và mở một bản đọc thống kê cho admin trên danh sách người đăng ký toàn cục.
2. Goals & Non-Goals
Goals
- Thu thập inquiry (liên hệ/bán hàng/demo) gửi từ trang công khai, kèm thông báo thời gian thực tới admin.
- Làm cho việc subscribe bản tin idempotent theo email - subscribe lại sẽ tái kích hoạt bản ghi đã unsubscribe trước đó thay vì tạo trùng.
- Tôn trọng unsubscribe dựa trên token trước mọi lần tái kích hoạt hoặc gửi.
- Mở thống kê người đăng ký cho admin: tổng số, mới-trong-tháng, đã kích hoạt, và đã hủy.
Non-Goals
- Chiến dịch, tự động hóa drip, và A/B testing - thuộc về Chiến dịch & Tự động hóa (
CMP, P2). - Hạ tầng gửi email/SMS - do nhà cung cấp bên ngoài đảm nhiệm.
- Logic giá khuyến mãi - thuộc về module Chiến dịch.
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Khử trùng lặp | Không có người đăng ký active trùng lặp trên mỗi email |
| Toàn vẹn opt-out | 100% token unsubscribe phân giải về một bản ghi đã hủy; không gửi tới người đăng ký đã hủy |
| Độ trễ thu thập | Inquiry gửi → thông báo admin gần thời gian thực |
| Khả năng quan sát đối tượng | Endpoint thống kê trả về total / monthlyNew / activated / deactivated cho danh sách toàn cục |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng |
|---|---|
| Khách truy cập | Gửi inquiry hoặc đăng ký bản tin từ trang công khai |
| Người đăng ký | Hủy đăng ký bất cứ lúc nào qua liên kết token một-chạm |
| Admin / Manager | Xem danh sách người đăng ký và thống kê của nó (tổng số, tăng trưởng, active/deactivated) |
Core scenarios: một khách truy cập gửi inquiry (admin được thông báo thời gian thực) hoặc đăng ký bản tin (idempotent theo email) → một người đăng ký sau đó nhấp liên kết unsubscribe (phân giải qua token, bị hủy) → một admin đọc thống kê người đăng ký trên danh sách toàn cục.
5. User Stories
- Là một khách truy cập, tôi muốn gửi inquiry liên hệ/bán hàng/demo từ trang công khai, để doanh nghiệp có thể theo dõi tiếp.
- Là một khách truy cập, tôi muốn đăng ký bản tin bằng email của mình, để nhận cập nhật - và đăng ký hai lần không bao giờ tạo bản trùng.
- Là một người đăng ký, tôi muốn hủy đăng ký qua liên kết token, để dừng nhận tin nhắn.
- Là một khách truy cập từng hủy đăng ký, tôi muốn việc đăng ký lại tái kích hoạt bản ghi của mình, để tham gia lại mà không có mục trùng.
- Là một admin, tôi muốn có thống kê người đăng ký (tổng số, mới-trong-tháng, đã kích hoạt, đã hủy), để đánh giá tăng trưởng đối tượng.
- Là một admin, tôi muốn có thông báo thời gian thực khi inquiry đến, để phản hồi nhanh.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Thu thập một inquiry (liên hệ/bán hàng/demo) gửi từ trang công khai | URD-CAP-001 |
| FR-2 | Subscribe bản tin idempotent theo email; email đang active trả về bản ghi hiện có, không tạo trùng | URD-CAP-002 |
| FR-3 | Đăng ký lại một email đã unsubscribe sẽ tái kích hoạt nó (subscribedAt đặt lại, unsubscribedAt xóa, status ACTIVATED) | URD-CAP-002 |
| FR-4 | Unsubscribe dựa trên token phân giải người đăng ký theo unsubscribeToken và hủy kích hoạt nó | URD-CAP-003 |
| FR-5 | Thống kê người đăng ký cho admin: total, monthlyNew, và tỷ lệ activated / deactivated, qua một aggregate duy nhất trên danh sách người đăng ký toàn cục | URD-CAP-004 |
| FR-6 | Một lần gửi inquiry mới phát ra một thông báo thời gian thực tới admin | URD-CAP-001 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Marketing. PRD này tham chiếu chúng thay vì lặp lại.
7. Non-Functional Requirements
| Lĩnh vực | Yêu cầu |
|---|---|
| Toàn vẹn dữ liệu | Subscribe idempotent theo email - một bản ghi active trên mỗi email; các dòng đã soft-delete bị loại khỏi thống kê |
| Toàn vẹn opt-out | Unsubscribe được tôn trọng trước mọi lần tái kích hoạt hoặc gửi; hủy kích hoạt chỉ qua token |
| Tenancy | Bảng thu thập là toàn cục (không scope theo merchant) theo ràng buộc module C-02; thống kê tổng hợp trên toàn bộ người đăng ký |
| Authz | Bản đọc cho admin (danh sách, thống kê) được gác theo permission; endpoint thu thập công khai chấp nhận strategy JWT/BASIC |
| Hiệu năng | Thống kê là một query aggregate COUNT(*) FILTER (...) duy nhất trên danh sách người đăng ký |
| i18n | locale của người đăng ký được thu để các lần gửi sau có thể bản địa hóa; nhãn hiển thị cho người dùng là song ngữ ({ en, vi }) |
8. UX & Flows
Màn hình chính: các form thu thập trên trang công khai (inquiry + bản tin) ở trang marketing, và màn hình danh sách người đăng ký ở back-office (overture-apps/bo) kèm UI kiểm tra form.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Inquiry | Một yêu cầu liên hệ/bán hàng/demo thu từ trang công khai (type, tên, email, doanh nghiệp, chủ đề) |
Subscriber | Một đăng ký bản tin - email, locale, topics, status (ACTIVATED/DEACTIVATED), subscribedAt, unsubscribedAt, unsubscribeToken |
Chỉ ở mức khái niệm - schema đầy đủ và bất biến nằm trong tài liệu lập trình viên outreach.
10. Dependencies & Assumptions
Phụ thuộc vào
@nx/outreach- package thu thập chứa controller, service, và repository cho inquiry và subscriber.@nx/core- schema subscriber/inquiry dùng chung và các repository cốt lõi.- Kênh thông báo thời gian thực - service WebSocket của outreach đẩy sự kiện inquiry-submitted tới admin.
Giả định
- Bảng thu thập là toàn cục (ràng buộc C-02); không có scope theo merchant trên subscriber/inquiry.
- Mỗi người đăng ký giữ một
unsubscribeTokenduy nhất cấp tại thời điểm thu thập cho unsubscribe một-chạm. - Nhà cung cấp bên ngoài (ngoài phạm vi) xử lý việc gửi email/SMS cuối cùng.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Người đăng ký trùng lặp khi gửi đúp nhanh | Subscribe idempotent theo email - trả về bản ghi active hiện có, không insert |
| Gửi tới một địa chỉ đã unsubscribe | Unsubscribe hủy kích hoạt bản ghi; ràng buộc C-01 yêu cầu opt-out phải được tôn trọng trước mọi lần gửi |
| Bảng toàn cục (không scope) xuyên các merchant | Chấp nhận theo ràng buộc C-02; thống kê là toàn cục có chủ đích |
| Chi phí thống kê khi danh sách lớn lên | Một query aggregate hôm nay; xem lại indexing/cache nếu danh sách lớn |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 (nền tảng) - marketing/CAP trong danh mục tính năng URD |
| Rollout | Tất cả các trang; không feature flag |
| Migration | Không (entity mới; bảng toàn cục) |
| Tiêu chí ra mắt | Subscribe idempotent đã kiểm chứng (không trùng); unsubscribe qua token hủy kích hoạt; thống kê trả về total/monthlyNew/activated/deactivated; gửi inquiry kích hoạt thông báo admin |
| Giám sát | Lượng subscribe/unsubscribe, tỷ lệ người đăng ký trùng (kỳ vọng 0), độ trễ query thống kê, độ tin cậy gửi thông báo inquiry |
13. FAQ
Điều gì xảy ra nếu cùng một email đăng ký hai lần? Không có gì bị trùng - một email đang active trả về bản ghi hiện có; một email từng unsubscribe sẽ được tái kích hoạt.
Unsubscribe hoạt động ra sao? Qua một liên kết token: unsubscribeToken phân giải về người đăng ký, sau đó người đó bị hủy kích hoạt. Opt-out luôn được tôn trọng trước mọi lần gửi.
Người đăng ký có được scope theo merchant không? Không - bảng thu thập là toàn cục theo ràng buộc C-02, nên thống kê tổng hợp trên toàn bộ người đăng ký.
Endpoint thống kê trả về gì? Một aggregate duy nhất: total, monthlyNew (đăng ký kể từ đầu tháng hiện tại), và tỷ lệ activated / deactivated, loại trừ các dòng đã soft-delete.
Tính năng này có gửi chiến dịch nào không? Không - việc gửi nằm ngoài phạm vi ở đây và thuộc về Chiến dịch & Tự động hóa (CMP, P2). Tính năng này chỉ thu thập và báo cáo đối tượng.
References
- URD: Marketing - Thu thập lead & người đăng ký
- PRD liên quan: Chiến dịch & Tự động hóa (kế hoạch)
- Module: Marketing - tổng quan + truy vết
- Developer: @nx/outreach