# @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