App 7 – CRM: liên hệ, pipeline, deal, đề xuất

Hướng: Xây mới bằng builder · Đợt: Đợt 1 · Phụ thuộc: —
Quy ước chung, nguồn dữ liệu nhân viên và cách chạy builder: 00-tong-quan.md

Mục đích: quản lý khách hàng và đối tác, theo dõi cơ hội bán hàng qua các giai đoạn pipeline, dự báo doanh thu và gửi đề xuất cho khách. Nguồn: Contacts, Sales Pipelines, Pipeline Deep Dive, Proposals.

Hướng: xây mới bằng builder. Độc lập; người phụ trách lấy từ hrm (tạm dùng người dùng Shell). Xây được ngay ở đợt 1.

Vai trò & quyền

Vai trò	Được làm
Quản lý bán hàng	Cấu hình pipeline và giai đoạn; xem mọi liên hệ, deal, đề xuất; giao lại deal; xem báo cáo
Nhân viên bán hàng	Tạo liên hệ; xem và sửa liên hệ, deal, đề xuất mình phụ trách
Nhân viên khác	Xem danh bạ khách hàng (chỉ đọc)

Dữ liệu

Thực thể	Trường	Ghi chú
Liên hệ	tên (cá nhân hoặc công ty), loại (Khách hàng, Client, Lead, Nhà cung cấp, Đối tác), email, điện thoại, website, địa chỉ, mã số thuế, ngân sách, loại ngân sách (Giờ, Tiền), người phụ trách (nhiều), tag, ghi chú, logo	Email không trùng
Người liên hệ	liên hệ (công ty), họ tên, chức vụ, email, điện thoại	Nhiều người cho một công ty
Pipeline	tên, mô tả, đang dùng
Giai đoạn	pipeline, tên, thứ tự, xác suất thắng (%), loại (Đang mở, Thắng, Thua)	Mẫu: Tiếp cận 10% → Đánh giá nhu cầu 25% → Đề xuất 50% → Đàm phán 75% → Thắng 100% / Thua 0%
Deal	tiêu đề, liên hệ, pipeline, giai đoạn, giá trị, tiền tệ, xác suất (mặc định theo giai đoạn), ngày dự kiến chốt, người phụ trách, ngày chốt thực tế, lý do thua
Hoạt động	liên hệ hoặc deal, loại (Gọi điện, Email, Họp, Ghi chú), nội dung, ngày, người ghi	Lịch sử giao tiếp
Đề xuất	tiêu đề, liên hệ, deal, nội dung (văn bản hoặc tệp PDF), giá trị, hiệu lực đến ngày, trạng thái (Nháp, Đã gửi, Chấp nhận, Từ chối, Hết hạn), là mẫu (đúng/sai)

Quy tắc nghiệp vụ

1. Deal phải nằm ở một giai đoạn thuộc chính pipeline của nó.
2. Chuyển deal sang giai đoạn Thắng hoặc Thua thì ghi ngày chốt thực tế; Thua bắt buộc lý do. Deal đã chốt không sửa giá trị.
3. Thắng deal với liên hệ loại Lead thì liên hệ tự chuyển thành Khách hàng.
4. Giá trị dự báo của deal = giá trị × xác suất; dự báo pipeline = tổng giá trị dự báo các deal đang mở.
5. Không xóa giai đoạn còn deal; không xóa liên hệ còn deal đang mở.
6. Đề xuất quá ngày hiệu lực mà vẫn Đã gửi thì tự chuyển Hết hạn; chỉ đề xuất Đã gửi mới được chuyển Chấp nhận hoặc Từ chối.
7. Đề xuất được chấp nhận có nút "Tạo dự án" (chuyển tên, khách hàng, giá trị sang App 6).
8. Nhân viên bán hàng chỉ thấy deal và đề xuất mình phụ trách.

Màn hình

Màn hình	Nội dung
Danh bạ	Bảng hoặc thẻ; lọc theo loại, tag, người phụ trách
Chi tiết liên hệ	Thông tin, người liên hệ, deal, đề xuất, dòng hoạt động
Pipeline	Bảng kanban theo giai đoạn, kéo thả deal; tổng giá trị mỗi cột
Đề xuất	Danh sách theo trạng thái; tạo từ mẫu
Báo cáo bán hàng	Tổng giá trị pipeline, dự báo, tỉ lệ thắng, giá trị trung bình deal thắng, số ngày chốt trung bình, tỉ lệ chuyển giai đoạn

Prompt cho builder – chia lượt

Dán từng lượt theo thứ tự, mỗi lượt là một tin nhắn. Duyệt kế hoạch trước khi builder chạy; chỉ sang lượt sau khi lượt trước đã kiểm tra xong trong bản xem trước.

Lượt 1 – Lõi: liên hệ, pipeline, deal

Tôi cần app CRM có phân quyền, lưu trong database.
Mọi dữ liệu tách theo tổ chức của người đăng nhập.
Nhân viên lấy từ sự kiện của app hrm (hrm:stream:employees) vào bảng chỉ đọc,
khớp người đăng nhập qua mã user Shell; khi hrm chưa phát đủ sự kiện thì tạm dùng
sự kiện người dùng của Shell (shell:stream:users).
Có dữ liệu mẫu cho bảng nhân viên (khoảng 10 người) để thử trong bản xem trước.
Dữ liệu: liên hệ (tên cá nhân hoặc công ty, loại Khách hàng/Client/Lead/Nhà cung
cấp/Đối tác, email không trùng, điện thoại, website, địa chỉ, mã số thuế, người phụ
trách, tag, ghi chú), người liên hệ của công ty (họ tên, chức vụ, email, điện thoại),
pipeline (tên, đang dùng), giai đoạn (pipeline, tên, thứ tự, xác suất thắng %, loại
Đang mở/Thắng/Thua; mẫu Tiếp cận 10%, Đánh giá nhu cầu 25%, Đề xuất 50%, Đàm phán
75%, Thắng 100%, Thua 0%), deal (tiêu đề, liên hệ, giai đoạn, giá trị, tiền tệ, xác
suất mặc định theo giai đoạn, ngày dự kiến chốt, người phụ trách, ngày chốt thực tế,
lý do thua).
Phân quyền: quản lý bán hàng xem tất cả và cấu hình pipeline; nhân viên bán hàng chỉ
xem và sửa deal mình phụ trách; nhân viên khác chỉ xem danh bạ.
Quy tắc (kiểm tra ở API): deal phải ở giai đoạn thuộc pipeline của nó; sang Thắng
hoặc Thua thì ghi ngày chốt, Thua bắt buộc lý do; deal đã chốt không sửa giá trị;
thắng deal với lead thì lead thành khách hàng; không xóa giai đoạn còn deal, không
xóa liên hệ còn deal đang mở.
Màn hình: danh bạ dạng bảng có lọc theo loại, tag, người phụ trách; chi tiết liên
hệ có danh sách deal; pipeline dạng kanban kéo thả, tổng giá trị mỗi cột.

Lượt 2 – Hoạt động và đề xuất

Thêm hoạt động (gọi điện, email, họp, ghi chú) gắn với liên hệ hoặc deal, hiện
thành dòng thời gian trong chi tiết liên hệ. Thêm đề xuất (tiêu đề, liên hệ, deal,
nội dung, giá trị, hiệu lực đến, trạng thái Nháp/Đã gửi/Chấp nhận/Từ chối/Hết hạn,
là mẫu). Chỉ đề xuất Đã gửi mới được Chấp nhận hoặc Từ chối; đề xuất đã gửi quá
hiệu lực thì tự chuyển Hết hạn; tạo đề xuất mới từ mẫu.

Lượt 3 – Báo cáo bán hàng

Thêm báo cáo bán hàng: tổng giá trị pipeline, dự báo = tổng giá trị × xác suất của
deal đang mở, tỉ lệ thắng, giá trị trung bình deal thắng, số ngày chốt trung bình,
tỉ lệ chuyển giai đoạn. Tính ở API; nhân viên bán hàng chỉ thấy số của mình.

Lượt 4 – Phát sự kiện cho app khác

Phát sự kiện qua Redis Streams khi liên hệ được tạo, sửa, đổi loại hoặc ngừng dùng
(mã, tên, loại, email, mã số thuế, người phụ trách), để app dự án, chi phí và hóa
đơn đồng bộ danh sách khách hàng.

Kiểm tra trước khi Publish

Đăng nhập lần lượt bằng từng vai trò trong bản xem trước:

• [ ] Nhân viên bán hàng chỉ thấy deal của mình (thử gọi thẳng API).
• [ ] Chuyển deal sang Thua không có lý do thì bị từ chối; deal đã chốt không sửa giá trị.
• [ ] Thắng deal với lead thì liên hệ đổi thành Khách hàng.
• [ ] Tổng giá trị mỗi cột kanban khớp với tổng deal trong cột.
• [ ] Checklist chung trong 00-tong-quan.md (mục Checklist chung trước khi Publish).