Dùng dòng API tùy chỉnh trong mẫu báo cáo tài chính

Nova Industries cần một dòng trên báo cáo quản trị mà nhóm phân loại tài khoản không tạo ra được: một chỉ tiêu hoạt động đã điều chỉnh theo ngân sách, do ứng dụng tùy chỉnh (custom app) của công ty tính. Giá trị này phải hiện cạnh các dòng tài khoản chuẩn và các công thức phía sau phải dùng được nó.

Trong Mẫu báo cáo tài chính, dòng có Nguồn dữ liệu (Data Source) là Custom API sẽ gọi một hàm Python phía máy chủ đã được duyệt. Chỉ dùng khi dòng Dữ liệu tài khoản (Account Data) và Số tính toán (Calculated Amount) không đáp ứng được yêu cầu. Đây là tính năng nâng cao dành cho lập trình viên, không phải cách để báo cáo gọi một địa chỉ HTTP bên ngoài.

Trước khi bắt đầuCopy Anchor Link

• Dùng một site cài và triển khai được ứng dụng Frappe tùy chỉnh.
• Viết và kiểm thử một hàm Python ở cấp module trong ứng dụng đó.
• Kiểm tra hiệu năng, phân quyền, phạm vi truy cập dữ liệu và xử lý lỗi của hàm.
• Tạo hoặc xác định Mẫu báo cáo tài chính cần thêm dòng này.

Thêm dòng Custom APICopy Anchor Link

1. Mở Mẫu báo cáo tài chính.
2. Thêm một dòng vào bảng Các dòng báo cáo (Report Line Items) và mở màn hình sửa dòng.
3. Đặt Nguồn dữ liệu là Custom API.
4. Nhập đường dẫn Python dạng chấm, ví dụ my_app.financial_report_api.get_budget_variance.
5. Nếu các dòng công thức phía sau cần giá trị trả về, đặt Mã dòng (Line Reference).
6. Cấu hình Đảo dấu (Reverse Sign), Ẩn nếu bằng 0 (Hide If Zero), Dòng ẩn (Hidden Line), Đưa vào biểu đồ (Include in Charts) và Kiểu giá trị (Value Type) khi cần.
7. Lưu mẫu và chạy báo cáo tài chính tương ứng.

Quy ước của hàmCopy Anchor Link

ERPNext có thể truyền vào filters của báo cáo, danh sách periods đã tạo và row hiện tại. Hàm trả về một giá trị số cho mỗi kỳ, đúng thứ tự các kỳ.

from frappe.utils import flt

def get_budget_variance(filters=None, periods=None, row=None):
    filters = filters or {}
    periods = periods or []
    values = []

    for period in periods:
        variance = calculate_variance(
            company=filters.get("company"),
            from_date=period.from_date,
            to_date=period.to_date,
        )
        values.append(flt(variance))

    return values

Yêu cầu với giá trị trả vềCopy Anchor Link

Hành vi cần lưu ýCopy Anchor Link

• Đường dẫn phải có dạng app.module.method, và hàm phải nằm trong một ứng dụng đã cài.
• Không cần @frappe.whitelist() chỉ để báo cáo gọi được hàm.
• Dòng Custom API không hỗ trợ Server Script.
• ERPNext xử lý dòng Custom API trước kết quả tài khoản và công thức, nên hàm không được phụ thuộc vào các dòng phía sau trong mẫu.

Bảo mật và kiểm thử hàmCopy Anchor Link

• Kiểm tra giá trị bộ lọc đầu vào, dùng truy vấn có xét phân quyền khi cần, không trả về chi tiết nhạy cảm và giới hạn phạm vi truy vấn.
• Kiểm thử kỳ không có dữ liệu, nhiều kiểu chu kỳ, tách biệt giữa các công ty, ngoại tệ, khoảng ngày lớn và các tình huống lỗi.
• Đối chiếu kết quả với một cách tính độc lập trước khi đưa mẫu vào sử dụng.

Xử lý sự cốCopy Anchor Link

Đường dẫn API bị từ chốiCopy Anchor Link

Dùng đường dẫn module dạng chấm đầy đủ và kiểm tra hàm được định nghĩa ở cấp module trong một ứng dụng đã cài.

Dòng chỉ hiện số 0Copy Anchor Link

Xem Nhật ký lỗi (Error Log) để tìm lỗi Custom API, kiểm tra hàm có trả về mỗi kỳ một giá trị số không, và chạy thử hàm với đúng bộ lọc của báo cáo.

Dòng tính toán không dùng được kết quảCopy Anchor Link

Đặt cho dòng Custom API một Mã dòng duy nhất và dùng đúng mã đó trong công thức phía sau.

Câu hỏi thường gặpCopy Anchor Link

Chủ đề liên quanCopy Anchor Link

• Mẫu báo cáo tài chính
• Báo cáo kế toán
• Hệ thống tài khoản
• Frappe Framework