mirror of
https://git.hiabuto.net/C3MA/CCMA.git
synced 2026-07-01 19:26:53 +02:00
Marcel Peterkau
84 lines
2.9 KiB
Markdown
84 lines
2.9 KiB
Markdown
# CCMA - Chaotic Creature Member Administration
|
|
|
|
File-based member administration for Chaos Computer Club Mannheim e.V.
|
|
|
|
The member store remains readable without this application. Every member has a
|
|
directory containing `member.json`, `contributions.json`, an append-only
|
|
`events.jsonl`, and a `files/` directory.
|
|
|
|
## Development
|
|
|
|
Requires Python 3.11+ with Tk support.
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
.venv/bin/pip install -r requirements.txt
|
|
.venv/bin/ccma
|
|
```
|
|
|
|
For development tools and tests, install the `dev` extra as well:
|
|
|
|
```bash
|
|
.venv/bin/pip install -e '.[dev]'
|
|
```
|
|
|
|
Alternatively, without installation:
|
|
|
|
```bash
|
|
PYTHONPATH=src python -m ccma
|
|
```
|
|
|
|
On first start, select or create the central member-store directory. The
|
|
`VERSION` file is the single source for application and package versions.
|
|
|
|
## Store layout
|
|
|
|
```text
|
|
member-store/
|
|
├── repository.json
|
|
├── housekeeper.json
|
|
├── rules/
|
|
└── members/
|
|
└── <uuid>/
|
|
├── member.json
|
|
├── contributions.json
|
|
├── events.jsonl
|
|
└── files/
|
|
```
|
|
|
|
## Housekeeper rules
|
|
|
|
The housekeeper runs every rule for every member. Built-in Python rules live in
|
|
`ccma/rules/scripts/`. A member store can add rules in its `rules/` directory.
|
|
If a store rule has the same filename as a built-in rule, the store version
|
|
replaces the built-in version.
|
|
|
|
Store rules are trusted executable Python code. Only place reviewed rules from
|
|
trusted sources in this directory. Rules return structured `RuleAction` objects;
|
|
CCMA performs all file writes, duplicate checks, audit events, and atomic updates.
|
|
|
|
`housekeeper.json` is written only after a complete run. Each refreshed task gets
|
|
the pending run ID. A failed run therefore cannot advance the stored counter or
|
|
silently resolve existing tasks.
|
|
|
|
## Claims and payments
|
|
|
|
Claims are stored in the member's `contributions.json`. A claim consists of
|
|
signed line items; fees increase and credits reduce its total. Payments remain
|
|
separate records and allocations connect one payment to one or more claims.
|
|
This supports partial payments, shared annual payments, unallocated credit, and
|
|
optional GnuCash transaction IDs without duplicating a bank transaction.
|
|
|
|
Claim status and outstanding balance are derived from line items and payment
|
|
allocations. Reminders are separate processes and only change the amount when
|
|
they explicitly add a fee line item. Every change is also appended to the
|
|
member's `events.jsonl` audit trail.
|
|
|
|
Overdue claims are evaluated by the reminder rule. It creates housekeeper tasks
|
|
for the next configured reminder level. Reminder drafts do not change a claim;
|
|
only confirming actual dispatch starts the new payment deadline and adds an
|
|
optional fee line item. A claim-level dunning hold suppresses automatic and
|
|
manual reminder preparation until it is removed or expires.
|
|
|
|
Do not place a real member store inside the source repository.
|