FinLedgerAI – Trợ lý tài chính CashyBear cá nhân hóa, dự đoán thông minh, ghi nhận minh bạch trên blockchain.

Tóm tắt dự án

FinLedgerAI là một hệ thống trợ lý tài chính tương tác CashyBear có cá tính (persona) vận hành bởi AI Agent. Người dùng chỉ nêu mục tiêu cuối, Agent tự động hoá chuỗi hành động: lập kế hoạch 7/14 ngày bắt đầu từ hôm nay, theo dõi – nhắc nhở đúng lúc, và đánh giá tiến độ.Các nhắc nhở và gợi ý được gửi qua SMS/Zalo với phong cách của từng persona — khi người dùng chi tiêu vượt kế hoạch, đến hạn tổng kết chu kỳ, hoặc khi xuất hiện cơ hội ưu đãi. Nhờ vậy, lời nhắc trở nên gần gũi, tự nhiên và cá nhân hóa, thay vì cứng nhắc hay gây khó chịu. Lớp AI Propensity chọn “đúng người, đúng thời điểm” cho thông điệp/ưu đãi, trong khi Blockchain Trust Layer (AdviceLog) ghi nhận dấu vết bất biến (hash đầu vào/đầu ra, phiên bản mô hình, persona, giai đoạn) để kiểm chứng. Toàn bộ hành trình hiển thị trên Dashboard và có Explorer UI để tra soát giao dịch on-chain.

Vấn đề & Cơ hội

• Người dùng khó duy trì kỷ luật chi tiêu và thiếu nhắc đúng lúc theo phong cách phù hợp.

• Doanh nghiệp sở hữu dữ liệu nhưng thiếu “cửa sổ thời điểm” và thiếu cơ chế giải trình cho AI.

• Cơ hội: persona-driven UX + calibrated timing + on-chain audit cho một trải nghiệm đáng tin cậy.

Giải pháp & Thành phần chính

1) Chatbot đa persona + AI Agent (Planner)

• Persona: Mentor (lịch sự, từng bước), Angry Mom (nghiêm khắc nhưng quan tâm), Banter/Gen Z (vui vẻ, chọc nhẹ).

• Kế hoạch 7/14 ngày “bắt đầu từ hôm nay” với các chỉ số: targetAmount, recommendedWeeklySave, weeklyCapSave, savedAmount, remainingAmount.

• To-do theo ngày: task/progress, API cập nhật/check, tổng hợp tiến độ lên dashboard.

• Nhắc nhở đa kênh (SMS/Zalo):

  • Khi người dùng chi tiêu vượt trần, đến hạn review chu kỳ 7/14 ngày, hoặc khi AI Propensity phát hiện cơ hội ưu đãi.

  • Nội dung tin nhắn được sinh theo giọng persona: Mentor gợi ý giải pháp, Angry Mom càu nhàu nhưng quan tâm, Banter người bạn thân dùng ngôn ngữ Gen Z vui nhộn.

  • Chính sách gửi: cooldown, frequency cap, quiet hours để tránh spam, đảm bảo tin nhắn mang tính đồng hành nhẹ nhàng thay vì gây áp lực.

2) AI Propensity (CustomerPotentialModel)

• Pipeline (scikit-learn): StandardScaler + One-Hot + Logistic Regression + Isotonic Calibration.

• Hiệu năng demo: AUC/AP ~0.82; Brier ~0.175; có bootstrap 95% CI, calibration plot; ablation (loại timing features) để kiểm chứng độ bền.

• Giải thích (Explainability): “facts” từ top-k w·x, tóm lược bằng Gemini; Frontend đọc qua /signals/offer.

• Kết nối kênh nhắc nhở (SMS/Zalo):

  • Khi dự đoán “Hot” (≥0.6) và timing gate (ví dụ: vừa có inflow lớn, dịp lễ) mở, hệ thống sinh offer message và gửi qua SMS/Zalo.

  • Tin nhắn ưu đãi cũng được gắn vào AdviceLog (qua hash) để đối chiếu minh bạch về lý do gửi.

  • Chính sách gửi: áp dụng cooldown, frequency_cap và quiet_hours để hạn chế spam, đảm bảo trải nghiệm nhẹ nhàng.

3) Blockchain Trust Layer (AdviceLog)

• Smart contract (Solidity, Hardhat local): event AdviceRecorded(inputHash, outputHash, modelVersion, persona, customerHash, sessionHash, stage, blockTime, nonce).

• Node/Express + Ethers v6:

  • Ghi: /advice/log, /advice/log-auto; hooks: /hook/chat/reply, /hook/plan/propose, /hook/plan/accept.

  • Đọc: /advice/logs (lọc theo customerId/sessionId/stage/date/txHash/block), chi tiết /advice/tx.

• Chuẩn hoá/hashing: canonical JSON → keccak256; customerHash/sessionHash ẩn PII; nonce chống đoán; xử lý BigInt JSON.

• Tự nạp ABI/address từ artifact; healthcheck, login demo.

• Tích hợp tự động: khi accept plan từ FastAPI → ghi log on-chain.

4) Explorer UI (React + TypeScript)

• Trang /explorer: thanh tìm kiếm hợp nhất (All/Customer ID/Tx/Block/Stage/Date), nút “My Logs”, bảng sự kiện (Block/Tx/Stage/Persona/Customer/Session/BlockTime/Nonce), liên kết trang Tx chi tiết.

• Verify panel: lọc theo khách + ngày, danh sách Tx, “Copy verification proof”.

5) Frontend Dashboard

• Hiển thị các chỉ số tiền mới; nhóm to-do theo ngày; cập nhật tiến độ; hiển thị ưu đãi/tín hiệu từ /signals/offer.

6) Vận hành & Ổn định (dev/local)

• Quy trình local: Hardhat node → deploy → Node server → React dev.

• Xử lý tình huống: EADDRINUSE, artifact/Ethers v6 (waitForDeployment), PowerShell quoting (node scripts), BigInt JSON.

7) API sử dụng

• Google Generative AI (Gemini API Key)

Luồng trải nghiệm end-to-end

Người dùng chọn persona → nhập mục tiêu (“tiết kiệm X trong Y tháng”) → /plan/propose sinh kế hoạch 7/14 ngày (bắt đầu từ hôm nay) → to-do ngày được theo dõi & cập nhật → khi chi tiêu lệch, nhận nhắc nhở đúng giọng persona → hết chu kỳ, dashboard tổng kết tiến độ → AI Propensity phát hiện “cửa sổ vàng” để gửi ưu đãi có lý do (facts) → khi /plan/accept, backend gọi hook ghi AdviceRecorded lên blockchain → Explorer UI cho phép tra soát & sao chép “verification proof”.