skr/readme.plan.md

@fin.cx/skr Implementation Plan

Command to reread CLAUDE.md

cat /home/philkunz/.claude/CLAUDE.md

Project Overview

TypeScript module implementing SKR03 and SKR04 German accounting standards for double-entry bookkeeping with MongoDB persistence via @push.rocks/smartdata.

Implementation Tasks

Phase 1: Project Setup

• Initialize npm project with pnpm
• Create package.json with proper metadata (@fin.cx/skr)
• Install core dependencies
  • @push.rocks/smartdata
  • @git.zone/tstest (dev dependency)
• Create tsconfig.json based on @push.rocks/smarthash pattern
• Create npmextra.json for additional configuration
• Create .gitignore file
• Create directory structure
  • ts/ directory for source code
  • test/ directory for tests
  • .vscode/ for VS Code settings
• Create initial readme.md with project description

Phase 2: Core Infrastructure

• Create ts/index.ts with main exports
• Create ts/plugins.ts for dependency management
  • Import and export @push.rocks/smartdata
  • Import and export @push.rocks/smartunique for ID generation
  • Import and export @push.rocks/smarttime for date handling
• Set up database connection helper in ts/skr.database.ts
• Create type definitions in ts/skr.types.ts
  • Define AccountType enum
  • Define SKRType enum
  • Define TransactionStatus enum
  • Define report interfaces

Phase 3: Data Models

• Create ts/skr.classes.account.ts
  • Define Account class extending SmartDataDbDoc
  • Add accountNumber field with unique index
  • Add accountName with searchable decorator
  • Add accountClass (0-9)
  • Add accountType (asset/liability/equity/revenue/expense)
  • Add skrType (SKR03/SKR04)
  • Add balance field
  • Add validation methods
  • Add helper methods for balance updates
• Create ts/skr.classes.transaction.ts
  • Define Transaction class extending SmartDataDbDoc
  • Add transactionId with unique index
  • Add date field with index
  • Add debitAccount and creditAccount fields
  • Add amount field
  • Add description with searchable decorator
  • Add reference field
  • Add validation for double-entry rules
  • Add beforeSave hook for validation
• Create ts/skr.classes.journalentry.ts
  • Define JournalEntry class for multi-line entries
  • Support split transactions
  • Add validation for balanced entries

Phase 4: SKR Account Definitions

• Create ts/skr03.data.ts
  • Define account class 0 (Capital accounts)
  • Define account class 1 (Fixed assets)
  • Define account class 2 (Current assets)
  • Define account class 3 (Equity and liabilities)
  • Define account class 4 (Operating income)
  • Define account class 5 (Operating expenses - materials)
  • Define account class 6 (Operating expenses - personnel)
  • Define account class 7 (Operating expenses - other)
  • Define account class 8 (Financial accounts)
  • Define account class 9 (Closing accounts)
• Create ts/skr04.data.ts
  • Define account class 0 (Capital accounts)
  • Define account class 1 (Financial accounts)
  • Define account class 2 (Expenses)
  • Define account class 3 (Expenses continued)
  • Define account class 4 (Revenues)
  • Define account class 5 (Revenues continued)
  • Define account class 6 (Special accounts)
  • Define account class 7 (Cost accounting)
  • Define account class 8 (Free for use)
  • Define account class 9 (Closing accounts)

Phase 5: Business Logic

• Create ts/skr.classes.chartofaccounts.ts
  • Implement initializeSKR03() method
  • Implement initializeSKR04() method
  • Implement getAccountByNumber() method
  • Implement getAccountsByClass() method
  • Implement createCustomAccount() method
  • Implement validateAccountNumber() method
  • Implement importFromCSV() method
  • Implement exportToCSV() method
• Create ts/skr.classes.ledger.ts
  • Implement postTransaction() method
  • Implement postJournalEntry() method
  • Implement validateDoubleEntry() method
  • Implement updateAccountBalances() method
  • Implement reverseTransaction() method
  • Implement getAccountHistory() method
  • Implement closeAccountingPeriod() method

Phase 6: Reporting

• Create ts/skr.classes.reports.ts
  • Implement getTrialBalance() method
  • Implement getIncomeStatement() for SKR03
  • Implement getIncomeStatement() for SKR04
  • Implement getBalanceSheet() for SKR03
  • Implement getBalanceSheet() for SKR04
  • Implement getGeneralLedger() method
  • Implement getAccountStatement() method
  • Implement getCashFlowStatement() method
  • Add DATEV export format support

Phase 7: API Layer

• Create ts/skr.api.ts
  • Implement REST-style account methods
    • createAccount()
    • getAccount()
    • updateAccount()
    • deleteAccount()
    • listAccounts()
  • Implement transaction methods
    • postTransaction()
    • getTransaction()
    • listTransactions()
    • reverseTransaction()
  • Implement report methods
    • generateTrialBalance()
    • generateIncomeStatement()
    • generateBalanceSheet()
  • Implement search methods
    • searchAccounts()
    • searchTransactions()
  • Add pagination support
  • Add filtering support

Phase 8: Testing

• Create test/test.basic.ts
  • Test database connection
  • Test basic model creation
• Create test/test.skr03.ts
  • Test SKR03 account initialization
  • Test SKR03 specific account structure
  • Test process-oriented organization
  • Test SKR03 reporting
• Create test/test.skr04.ts
  • Test SKR04 account initialization
  • Test SKR04 specific account structure
  • Test financial statement organization
  • Test SKR04 reporting
• Create test/test.transactions.ts
  • Test simple transaction posting
  • Test complex journal entries
  • Test double-entry validation
  • Test balance updates
  • Test transaction reversal
• Create test/test.reports.ts
  • Test trial balance generation
  • Test income statement
  • Test balance sheet
  • Test report accuracy
• Create test/test.api.ts
  • Test API CRUD operations
  • Test API search functionality
  • Test API pagination
  • Test API error handling

Phase 9: Documentation

• Update readme.md with comprehensive documentation
  • Installation instructions
  • Quick start guide
  • API reference
  • SKR03 vs SKR04 explanation
  • Code examples
• Add inline JSDoc comments to all classes and methods
• Create example usage files
• Document CSV import/export format
• Document DATEV compatibility

Phase 10: Build and Quality

• Run pnpm build and fix any TypeScript errors
• Run pnpm test and ensure all tests pass
• Check for missing type definitions
• Optimize database indexes
• Add data validation and error handling
• Performance testing with large datasets
• Security review for data access

Phase 11: Advanced Features

• Add multi-currency support
• Add VAT/tax calculation helpers
• Add cost center accounting
• Add budget management
• Add audit trail functionality
• Add data migration tools
• Add backup/restore functionality

Phase 12: Finalization

• Final code review
• Update all documentation
• Create migration guide from other systems
• Prepare for npm publication
• Create changelog
• Tag version 1.0.0

Notes

• SKR03 uses process structure principle (operating procedures)
• SKR04 uses financial classification principle (financial statements)
• Account numbers are 4-digit (0000-9999)
• Must maintain double-entry bookkeeping rules
• Use @push.rocks/smartdata for all database operations
• Follow existing code patterns from @push.rocks modules
• Test with @git.zone/tstest using expect from tapbundle

Success Criteria

• All account classes (0-9) implemented for both SKR03 and SKR04
• Double-entry bookkeeping validation working
• Reports generating correctly
• All tests passing
• TypeScript compilation successful
• Documentation complete