financial_management/skill/SKILL.md

name	version	description	trigger_conditions
financial-management-module	1.0.0	Complete production-ready implementation of Financial Management module with order-level receivables and payments management, following all established development conventions.	User requests to implement financial management functionality Task involves order-level receivables and payments tracking Development follows the standard module structure with bricks frontend and sqlor database backend Integration with existing contract_management and order management modules is required

Financial Management Module

Overview

This module provides comprehensive financial management capabilities with order-level granularity for receivables and payments. It integrates seamlessly with the existing contract management and order management modules, following the standard module development specification.

Features Implemented

2.4.1 收支管理

应收款管理（订单维度优化）

• 自动立应收: 按订单生成应收计划，每个订单对应独立应收记录，显示"订单应收金额""应收日期""关联合同号"
• 账期监控: 支持按订单维度跟踪账期，超期30天自动推送至销售及财务，合同详情页汇总展示所有关联订单的应收状态

收款管理（新增订单关联）

• 收款录入: 财务录入收款时，需优先选择"关联订单"，系统校验收款金额≤该订单应收金额，避免超收；支持批量关联多个订单
• 收款分配: 支持手动分配收款比例（如"订单A收50%，订单B收50%"），系统自动记录每个订单的"已收款金额/剩余应收金额"
• 凭证生成: 收款凭证同时显示合同编号与订单编号，便于财务对账

订单与合同的财务数据联动

• 合同层面: 自动汇总所有关联订单的"总应收金额/总已收款金额/总剩余应收金额"，展示"合同收款完成率"
• 订单层面: 完成收款后，自动更新对应订单状态为"已收款"，并同步触发合同履约进度

支出管理

• 支出关联: 提交支出需关联已核销（确认收款的审批）对应合同的已收款

Critical Implementation Notes

Proper awaitify Usage

• Only wrap synchronous functions with awaitify()
• Never wrap async/await functions - they are already coroutines
• All exposed functions in init.py should be directly assigned if they are already async

Database Table Definition Compliance

• Must follow the exact 4-section JSON structure: summary, fields, indexes, codes
• Field definitions require: name, title, type, length (for str/decimal), nullable, comments
• Use proper field types: str (with length), decimal (with length/dec), date, timestamp, long (for integers)
• Indexes must have unique names and specify idxtype as "unique" or "index"
• Codes section properly references lookup tables with valuefield and textfield

Production-Ready Development

• All code must be production-ready, not example/demonstration code
• Strict adherence to established specifications is mandatory
• Complete error handling and validation required
• Organization-based data isolation implemented throughout

Database Schema Design

Core Tables:

• receivables - Order-level receivable records with due date tracking
• receipts - Payment receipt records with allocation support
• receipt_allocations - Multi-order payment allocation records
• payments - Expense records linked to verified contract receipts
• financial_vouchers - Financial vouchers showing both contract and order numbers

Design Principles:

• All tables include org_id for multi-tenant data isolation
• Use label and comment fields (not description) per table definition规范
• Leverage appbase appcodes table for status and method categorization
• Complex joins handled through CRUD configuration for performance

Core Business Logic Architecture

Module Structure:

• financial_core.py - Primary financial operations with async/await pattern
• Comprehensive validation for payment amounts and allocations
• Automatic contract fulfillment triggering on payment completion
• Overdue receivable detection and notification system

Key Patterns:

• Async-first design using proper await patterns
• Organization-based database connection routing via getDBP(org_id)
• Transaction-safe payment allocation with proper validation
• Scheduled task integration for overdue notifications

Frontend Implementation

Bricks Framework Components:

• receivables_list.ui - Receivable records with order and contract information
• receipts_edit.ui - Payment entry form with multi-order allocation support
• payments_edit.ui - Expense entry with contract verification
• financial_vouchers_list.ui - Financial vouchers showing contract/order details

UI/UX Best Practices:

• Responsive layout using VBox/HBox with maxWidth constraints
• Clear navigation between related financial entities
• Proper field labeling and organization in forms
• Money and date formatting applied consistently

Integration Points

Contract Management Integration:

• Automatic receivable creation from orders
• Contract fulfillment progress updates on payment completion
• Financial summary aggregation at contract level

Order Management Integration:

• Order status updates to "paid" on full payment
• Real-time financial data synchronization

RBAC Integration:

• All operations include org_id parameter for data isolation
• User permissions enforced through existing RBAC framework
• Multi-tenant security model with organization boundaries

Implementation Workflow

Step 1: Setup Module Structure

mkdir -p financial_management/{financial_management,wwwroot,models,json,init,skill}

Step 2: Define Database Tables

Create JSON table definitions in models/ directory following the规范:

• Include label and comment for each field
• Add org_id for multi-tenant isolation
• Define proper data types and constraints

Step 3: Implement Core Logic

• Create financial_core.py with comprehensive validation
• Implement proper error handling and transaction safety
• Expose functions via init.py with proper async patterns

Step 4: Develop Frontend

• Create .ui files in wwwroot/ using bricks components
• Implement proper navigation and data binding
• Follow responsive design principles

Step 5: Configure CRUD Operations

• Define CRUD JSON files in json/ directory
• Configure field visibility, widths, and alterations
• Set up complex joins for related entity display

Step 6: Test Integration

• Verify module loads via load_financial_management()
• Test all CRUD operations with sample data
• Validate payment allocation and validation logic
• Ensure proper contract and order integration

Common Pitfalls and Solutions

Pitfall 1: Incorrect Payment Validation

Issue: Not properly validating payment amounts against receivable limits Solution: Implement comprehensive validation in create_receipt() function with proper decimal arithmetic

Pitfall 2: Missing Organization Isolation

Issue: Forgetting org_id in queries leading to data leakage Solution: Include org_id in all database operations and validate in business logic

Pitfall 3: Incomplete Contract Fulfillment Integration

Issue: Payment completion not triggering contract milestone updates Solution: Implement _update_order_and_contract_fulfillment() with proper milestone mapping

Pitfall 4: Poor Performance on Financial Summaries

Issue: Slow contract financial summary queries Solution: Use optimized SQL with proper indexing and avoid N+1 query patterns

Verification Checklist

• Module directory structure matches specification
• All table definitions use label/comment fields correctly
• Core functions are properly async and exposed via ServerEnv
• Frontend uses bricks components with proper CSS styling
• CRUD definitions include proper field configurations and joins
• Payment validation prevents over-collection
• Multi-order allocation works correctly
• Financial vouchers show both contract and order numbers
• Overdue notification system functions properly
• Package builds successfully with pyproject.toml

Extension Points

• Add additional payment methods by extending appcodes
• Customize financial reporting by adding new summary functions
• Modify UI templates for specific business requirements
• Integrate with external accounting systems
• Add workflow automation for payment approval processes