RustyRPN/Documentation/cli.md

Command structure

rpnc
├── batch
│   ├── update       # 1. Recalculate all values of batch using data from transactions table
│   │                # 2. Update batch values
│   └── list         # list all batches in DB
│
├── card
│   ├── create       # add card to DB
│   │                #   - require customer
│   │                #   - require status
│   │                #   - require description
│   │                #   - require pin
│   ├── read         # fetch card details
│   ├── update       # modify card
│   ├── delete       # delete card
│   │                #   only allowed on cards not referenced by any transactions 
│   └── list         # list all cards
│                    #   allow filtering by customer, status
│
├── customer
│   ├── create       # add customer
│   │                #   - require customer number (ID) and name
│   ├── read         # fetch customer details
│   ├── update       # modify customer
│   ├── delete       # delete customer
│   │                #   only allowed on customers not referenced by any transactions 
│   └── list         # list all customers
│
├── daemon
│   ├── start        # start the web server daemon
│   ├── status       # check status of daemon
│   │                #   - running?
│   │                #   - port?
│   │                #   - db access?
│   │                #   - accessible from internet?
│   │                #   - fqdn?
│   └── stop         # stop daemon
│
├── db
│   ├── setup        # create database and schema
│   ├── reset        # drop and recreate database
│   ├── status       # check if connection to db is ok
│   ├── backup       # create a backup of database
│   └── restore      # recreate database from backup
│
├── file
│   ├── import       # read CSV into DB:
│   │                #   1. create any missing customers
│   │                #   2. create any missing cards
│   │                #   3. create transactions
│   │                #   4. create any missing batches
│   │                #   5. verify batch values match calculated value
│   ├── list         # list all files stored in DB
│   └── export       # export file to specified format
│
├── invoice
│   ├── create       # add invoice to DB:
│   │                #   - require batch OR date range
│   │                #   - require "all" or specific customer
│   ├── read         # fetch invoice details
│   ├── update       # modify invoice
│   │                #   - only allowed on invoices with "draft" status
│   ├── delete       # delete invoice
│   │                #   - only allowed on invoice with the highest ID number
│   │                #   - only allowed if invoice status is "draft"
│   ├── credit       # create a credit invoice
│   │                #   - required if errors is needed to be fixed on a sent invoice
│   ├── export       # write HTML files to disk
│   └── list         # list all invoices
│                    #   - allow filtering list by customer, date
│
└── transaction      # CRUD not needed via cli, transactions will only be added via "file import"
    ├── read         # fetch transaction details
    │                #   - CREATE not needed, they will only be created via "file import" function
    │                #   - UPDATE not needed, transactions are immutable
    │                #   - DELETE not needed, transactions are immutable
    └── list         # list transactions (with filtering)

Global flags:

--env=[dev,test] # production assumed --quiet # for scripts only caring about exit codes --help # display basic usage information --format=[raw,json,csv,columns] # columns assumed

Implementation Notes (added during CLI expansion)

The following clarifications were made while implementing the CLI stubs:

• Positional IDs: read, update, delete, and credit subcommands that operate on a single entity take a positional id argument (e.g., card read <id>, invoice credit <id>).
• Card create: Uses flags --customer, --status, --description, --pin.
• Card list: Optional filters --customer and --status.
• Customer create: Uses flags --id and --name.
• File export: Takes --format to specify the target export format.
• Invoice create: Uses flags --batch, --from, --to, --customer, and --all. The caller must supply either --batch or a --from/--to date range, and either --customer or --all.
• Invoice list: Optional filters --customer and --date.
• Transaction list: Optional filters --customer, --card, --batch, --from, --to.
• Global --env: Accepts dev or test; omitted means production.
• Global --format: Defaults to columns.