dennis/Radix-Skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import: 10 Radix skills across 3 categories

Browse Source 
Kategoriserer danske regnskabs-/ERP-skills, ERP-data-afstemnings-
skill og to devops-workflows (gitea-issue-agent, kanban-workflows)
som Radix-medlemmers AI-agenter kan dele.

Struktur:
  skills/<kategori>/<skill-navn>/SKILL.md
  skills/<kategori>/<skill-navn>/{references,templates,scripts}/

Indekseret af index.json (genereret af scripts/rebuild_index.py).
Kør `python3 scripts/rebuild_index.py --check` i CI for at fange
synkroniseringsfejl.
This commit is contained in:
Dennis Juhler Aagaard
2026-06-15 14:41:04 +02:00
commit 236053cd7f
30 changed files with 4460 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+25
View File
@@ -0,0 +1,25 @@
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.egg-info/
.venv/
venv/
.pytest_cache/
# macOS
.DS_Store
# Editor / IDE
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store
# Logs and temp
*.log
*.tmp
README.md
+67
View File
@@ -0,0 +1,67 @@
# Radix-Skills
Delt AI-skill-bibliotek for Radix. Bruges af alle medarbejderes AI-agenter
(Hermes, Codex m.fl.) til dansk regnskab/ERP, data-afstemning og devops-workflows.
> **Hvad er en "skill"?** En self-contained YAML-frontmatter + markdown-fil
> (`SKILL.md`) der beskriver et domæne-specifikt workflow, som en AI-agent kan
> loade på forespørgsel. Tænk på det som en delt playbook for en bestemt
> type opgave.
## Struktur
```text
Radix-Skills/
├── README.md # denne fil
├── index.json # maskinlæseligt index over alle skills
└── skills/
├── accounting/ # dansk regnskab, bogføring, ERP
│ ├── radix-accounting/ # top-level bogholderi-skill (sprog, formater, aktivering)
│ ├── coop-bankimport/
│ ├── dansk-csv-import/
│ ├── e-conomic-integration/
│ ├── kontoplan-mapping/
│ ├── momsafregning/
│ └── resultatopgoerelse/
├── data-science/
│ └── erp-data-reconciliation/ # afstemning mellem ERP-systemer
└── devops/
├── gitea-issue-agent/ # agent-drevet Gitea issue/PR-workflow
└── kanban-workflows/
```
Hver skill ligger i sin egen mappe og har mindst `SKILL.md`. Større skills
kan have undermapper:
- `references/` — uddybende dokumentation der kun loades ved behov
- `templates/` — skabeloner (f.eks. issue-kommentarer, rapporter)
- `scripts/` — hjælpescripts der følger med skillen
## Hvordan en agent bruger repo'et
1. Læs `index.json` for at finde relevante skills ud fra tags/description.
2. Gå ind i den relevante `skills/<kategori>/<navn>/` mappe.
3. Læs `SKILL.md` (med YAML-frontmatter) for at aktivere skillen.
4. Følg de nummererede steps i skillen.
5. Hvis skillen henviser til en reference, load den først når det er relevant
(ikke alle på én gang).
## Bidrag
Nye skills skal:
1. Lægges under `skills/<kategori>/<skill-navn>/` med en `SKILL.md`.
2. Følge SKILL.md-formatet (YAML-frontmatter med `name`, `description`,
`version`, `author`, `license` + markdown body).
3. Have en kort `description` der kan bruges til trigger-matching.
4. Have en `version` der følger semver.
5. Blive registreret i `index.json` (kør `python3 scripts/rebuild_index.py`).
Åbn en Gitea-PR med ændringerne — `gitea-issue-agent`-skillen kan guide dig.
## Vedligeholdelse
- `index.json` genereres automatisk af `scripts/rebuild_index.py` ud fra
frontmatter i alle `SKILL.md` filer.
- Store ændringer (ny kategori, formatændring) kræver opdatering af denne
`README.md`.
index.json
+215
View File
@@ -0,0 +1,215 @@
{
"repository": "Radix-Skills",
"version": 1,
"description": "Delt AI-skill-bibliotek for Radix — bruges af alle medarbejderes AI-agenter (Hermes, Codex m.fl.) til dansk regnskab/ERP/data/devops.",
"categories": [
"accounting",
"data-science",
"devops"
],
"skill_count": 10,
"skills": [
{
"category": "accounting",
"name": "coop-bankimport",
"path": "accounting/coop-bankimport/SKILL.md",
"description": "Reconcilier Coop Danmark-bankbetalinger mod Uniconta- eller e-conomic-fakturaer (og kreditnotaer, bonus, modregninger) — aktiveres ved \"Coop afstemning\", \"Coop bankbetaling\", \"Coop opgørelse\", \"forenel Coop betaling med faktura\", \"Coop kreditnota\".",
"version": "0.2.0",
"author": "radix-accountant",
"tags": [
"accounting",
"dansk-regnskab",
"coop-danmark",
"uniconta",
"e-conomic",
"reconciliation",
"bankafstemning"
],
"files": [
"accounting/coop-bankimport/SKILL.md"
]
},
{
"category": "accounting",
"name": "dansk-csv-import",
"path": "accounting/dansk-csv-import/SKILL.md",
"description": "Importér danske bank-CSV-eksporter (Nordea, Danske Bank, Jyske Bank, Sydbank) og e-conomic-bankimport-format — aktiveres ved \"importér CSV\", \"bankudtog\", \"kontoudtog\", \"Nordea eksport\", \"Danske Bank CSV\", \"Jyske Bank eksport\", \"e-conomic bankimport\".",
"version": "0.2.0",
"author": "radix-accountant",
"tags": [
"accounting",
"dansk-regnskab",
"csv-import",
"bank",
"nordea",
"danske-bank",
"jyske-bank",
"e-conomic"
],
"files": [
"accounting/dansk-csv-import/SKILL.md"
]
},
{
"category": "accounting",
"name": "e-conomic-integration",
"path": "accounting/e-conomic-integration/SKILL.md",
"description": "Integration med e-conomic cloud-bogføring — aktiveres ved \"bogfør i e-conomic\", \"hent fakturaer fra e-conomic\", \"kassekladde\", \"sync mod e-conomic\", \"opret kunde i e-conomic\", \"kontoudtog e-conomic\", \"REST API\", \"AppSecretToken\". Dækker auth, kontoplan, kassekladder, bogførte fakturaer, kreditorer, kunder og banktransaktioner.",
"version": "0.1.0",
"author": "radix-accountant",
"tags": [
"accounting",
"e-conomic",
"dansk-regnskab",
"api",
"cloud-bogfoering",
"integration"
],
"files": [
"accounting/e-conomic-integration/SKILL.md"
]
},
{
"category": "accounting",
"name": "kontoplan-mapping",
"path": "accounting/kontoplan-mapping/SKILL.md",
"description": "Kortlæg transaktioner, fakturaer og bilag til dansk standardkontoplan (SUM, DG, SL) eller bogføringssystem-specifik kontoplan (e-conomic 4-cifret, Uniconta) — aktiveres ved \"hvilken konto?\", \"kontoplan\", \"kontorådgivning\", \"bogføring af [transaktionstype]\", \"hvor skal jeg bogføre dette\".",
"version": "0.2.0",
"author": "radix-accountant",
"tags": [
"accounting",
"dansk-regnskab",
"kontoplan",
"SUM",
"DG",
"SL",
"uniconta",
"e-conomic"
],
"files": [
"accounting/kontoplan-mapping/SKILL.md"
]
},
{
"category": "accounting",
"name": "momsafregning",
"path": "accounting/momsafregning/SKILL.md",
"description": "Beregn dansk momsangivelse (moms, momsfradrag, momsrefusion) til SKAT — aktiveres ved forespørgsler om \"moms\", \"momsangivelse\", \"momsrefusion\", \"kvartalsmoms\", \"halvårsmoms\", \"momsregnskab\", \"25% moms\", \"momsfri\".",
"version": "0.1.0",
"author": "radix-accountant",
"tags": [
"accounting",
"dansk-regnskab",
"moms",
"skat",
"momsangivelse"
],
"files": [
"accounting/momsafregning/SKILL.md"
]
},
{
"category": "accounting",
"name": "radix-accounting",
"path": "accounting/radix-accounting/SKILL.md",
"description": "Dansk bogføring, regnskab og ERP-assistance til Radix-portalen — aktiveres ved forespørgsler om resultatopgørelse, momsafregning, kontoplan, CSV-import, bankafstemning, Uniconta-integration, e-conomic-integration eller Coop Danmark-reconciliation. Svar altid på dansk, brug dansk talformatering (1.234.567,89) og dd-MM-yyyy datoformat.",
"version": "0.2.0",
"author": "radix-accountant",
"tags": [
"accounting",
"dansk-regnskab",
"moms",
"radix-erp",
"uniconta",
"e-conomic",
"coop"
],
"files": [
"accounting/radix-accounting/SKILL.md"
]
},
{
"category": "accounting",
"name": "resultatopgoerelse",
"path": "accounting/resultatopgoerelse/SKILL.md",
"description": "Byg en dansk resultatopgørelse (P&L) ud fra Radix ERP-data — aktiveres ved forespørgsler om \"resultatopgørelse\", \"P&L\", \"årsregnskab\", \"indtjening pr. måned/kvartal/år\".",
"version": "0.1.0",
"author": "radix-accountant",
"tags": [
"accounting",
"dansk-regnskab",
"resultatopgoerelse",
"radix-erp"
],
"files": [
"accounting/resultatopgoerelse/SKILL.md"
]
},
{
"category": "data-science",
"name": "erp-data-reconciliation",
"path": "data-science/erp-data-reconciliation/SKILL.md",
"description": "Analyze and reconcile financial/accounting data between two ERP systems (e.g. SAP/Coop and Uniconta) using Excel exports. Covers file inspection, column mapping, Danish-format normalization, match-engine design, and iterative build workflow.",
"version": "",
"author": "",
"tags": [],
"files": [
"data-science/erp-data-reconciliation/SKILL.md",
"data-science/erp-data-reconciliation/references/auditor-pack-and-dedup.md",
"data-science/erp-data-reconciliation/references/bank-implementation.md",
"data-science/erp-data-reconciliation/references/bank-reconciliation.md",
"data-science/erp-data-reconciliation/references/coop-invoice-payment-allocation.md",
"data-science/erp-data-reconciliation/references/coop-payment-advice.md",
"data-science/erp-data-reconciliation/references/coop-uniconta-analysis.md",
"data-science/erp-data-reconciliation/references/coop-uniconta-import-ui-and-payment-advice.md",
"data-science/erp-data-reconciliation/references/coop-uniconta-match-engine.md",
"data-science/erp-data-reconciliation/references/django-accounting-ui-formatting.md",
"data-science/erp-data-reconciliation/references/idempotent-source-file-imports.md",
"data-science/erp-data-reconciliation/references/reconciliation-webapp-architecture.md",
"data-science/erp-data-reconciliation/references/three-way-django-analysis-engine.md",
"data-science/erp-data-reconciliation/scripts/excel-analyzer.py"
]
},
{
"category": "devops",
"name": "gitea-issue-agent",
"path": "devops/gitea-issue-agent/SKILL.md",
"description": "Build a Hermes-managed autonomous issue handler for a self-hosted Gitea instance — scan issues, analyze text + screenshot attachments, post a proposal for human approval, implement, test, push a branch, and open a Gitea PR. Use when the user wants Hermes to act on Gitea issues end-to-end with a human-in-the-loop approval gate, especially with image/visual context in the issue text.",
"version": "0.1.0",
"author": "Hermes Agent",
"tags": [
"gitea",
"issues",
"automation",
"hermes-plugin",
"pr-workflow",
"agent-loop",
"approval-gate"
],
"files": [
"devops/gitea-issue-agent/SKILL.md",
"devops/gitea-issue-agent/references/identity-and-safety.md",
"devops/gitea-issue-agent/scripts/verify-plugin-and-gitea.sh",
"devops/gitea-issue-agent/templates/proposal-comment.md"
]
},
{
"category": "devops",
"name": "kanban-workflows",
"path": "devops/kanban-workflows/SKILL.md",
"description": "Use when operating Hermes Kanban workflows: decomposing work as an orchestrator, executing as a worker, managing lanes, status, blockers, and reconciliation.",
"version": "1.0.0",
"author": "Hermes Agent",
"tags": [
"kanban",
"orchestration",
"workers",
"task-management",
"hermes"
],
"files": [
"devops/kanban-workflows/SKILL.md"
]
}
]
}
scripts/rebuild_index.py
+124
View File
@@ -0,0 +1,124 @@
#!/usr/bin/env python3
"""
Rebuild index.json from SKILL.md frontmatter in this repository.
Usage:
python3 scripts/rebuild_index.py
python3 scripts/rebuild_index.py --check # exit 1 if index.json is out of date
The index is the canonical machine-readable manifest of all skills in this
repository. Regenerate it whenever a SKILL.md is added, removed, or has its
frontmatter changed. Commit index.json together with the SKILL.md change.
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
SKILLS_ROOT = REPO_ROOT / "skills"
INDEX_PATH = REPO_ROOT / "index.json"
FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*):\s*(.+?)(?=\n[A-Za-z_]|\Z)", re.MULTILINE | re.DOTALL)
def _grab(frontmatter: str, key: str) -> str:
m = re.search(rf"^{key}:\s*(.+?)(?=\n[A-Za-z_]|\Z)", frontmatter, re.MULTILINE | re.DOTALL)
if not m:
return ""
val = m.group(1).strip()
# strip YAML block indicators and quotes
val = val.strip(">").strip("|").strip()
if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
val = val[1:-1]
return val.strip()
def _grab_tags(frontmatter: str) -> list[str]:
m = re.search(r"tags:\s*\[(.*?)\]", frontmatter, re.DOTALL)
if not m:
return []
return [t.strip().strip('"').strip("'") for t in m.group(1).split(",") if t.strip()]
def build_index() -> dict:
skills: list[dict] = []
for skill_md in sorted(SKILLS_ROOT.rglob("SKILL.md")):
rel = skill_md.relative_to(SKILLS_ROOT)
parts = rel.parts
category = parts[0] if len(parts) > 1 else "root"
name = parts[-2] if len(parts) > 1 else "root"
text = skill_md.read_text(encoding="utf-8")
fm_match = FRONTMATTER_RE.match(text)
frontmatter = fm_match.group(1) if fm_match else ""
desc = _grab(frontmatter, "description").replace("\n", " ").strip()
version = _grab(frontmatter, "version")
author = _grab(frontmatter, "author")
tags = _grab_tags(frontmatter)
all_files = sorted(
str(p.relative_to(SKILLS_ROOT))
for p in skill_md.parent.rglob("*")
if p.is_file()
)
skills.append(
{
"category": category,
"name": name,
"path": str(rel),
"description": desc,
"version": version,
"author": author,
"tags": tags,
"files": all_files,
}
)
return {
"repository": "Radix-Skills",
"version": 1,
"description": (
"Delt AI-skill-bibliotek for Radix — bruges af alle medarbejderes "
"AI-agenter (Hermes, Codex m.fl.) til dansk regnskab/ERP/data/devops."
),
"categories": sorted({s["category"] for s in skills}),
"skill_count": len(skills),
"skills": skills,
}
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--check", action="store_true", help="Exit 1 if index.json is stale")
args = parser.parse_args()
new_index = build_index()
new_json = json.dumps(new_index, ensure_ascii=False, indent=2) + "\n"
if args.check:
if not INDEX_PATH.exists():
print("index.json does not exist", file=sys.stderr)
return 1
current = INDEX_PATH.read_text(encoding="utf-8")
if current != new_json:
print("index.json is out of date — run scripts/rebuild_index.py", file=sys.stderr)
return 1
return 0
INDEX_PATH.write_text(new_json, encoding="utf-8")
print(
f"Wrote {INDEX_PATH.relative_to(REPO_ROOT)} with {new_index['skill_count']} skills "
f"across {len(new_index['categories'])} categories: {', '.join(new_index['categories'])}"
)
return 0
if __name__ == "__main__":
sys.exit(main())
skills/accounting/coop-bankimport/SKILL.md
+198
View File
@@ -0,0 +1,198 @@
---
name: coop-bankimport
description: >
Reconcilier Coop Danmark-bankbetalinger mod Uniconta- eller e-conomic-fakturaer (og kreditnotaer,
bonus, modregninger) — aktiveres ved "Coop afstemning", "Coop bankbetaling", "Coop opgørelse",
"forenel Coop betaling med faktura", "Coop kreditnota".
version: 0.2.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, dansk-regnskab, coop-danmark, uniconta, e-conomic, reconciliation, bankafstemning]
related: [dansk-csv-import, kontoplan-mapping, resultatopgoerelse, e-conomic-integration]
---
# Coop Danmark-bankimport & afstemning (Uniconta eller e-conomic)
Specifikt workflow til **Coop Danmark ↔ [Uniconta|e-conomic]-afstemning**. Hver bankbetaling fra Coop følges af en specifikation (opgørelse) der viser præcis hvilke fakturaer, kreditnotaer, bonusser og modregninger beløbet dækker. Målet er at matche **bankbetalinger (Coop) → opgørelseslinjer → bogføringssystem-bilag** og producere bogføringsklare posteringer.
## Hvilket bogføringssystem?
| System | Fordel ved Coop-afstemning | Ulempe |
|---|---|---|
| **Uniconta** | Lokal data, ingen API-rate-limit, kender hele kontohistorik | Manuel CSV-eksport nødvendig |
| **e-conomic** | Cloud-baseret, kan bogføre direkte via API, kunde 1 (Coop) findes typisk allerede | Rate-limit, kræver AppSecretToken |
**Spørg brugeren** hvilket system de bruger — svaret bestemmer hvordan data hentes og hvordan bogføringsforslaget præsenteres.
## Aktiveres ved
- "Forenel denne Coop-bankbetaling med Uniconta"
- "Importer Coop-opgørelse for uge 22"
- "Hvorfor matcher Coop-bankbetalingen ikke Uniconta-saldoen?"
- "Generer bogføringsforslag for denne Coop-indbetaling"
## Forventede input
Brugeren leverer typisk:
1. **Coop bankbetalings-CSV** (Sydbank, Jyske Bank eller Danske Bank — særskilt format for Coop)
2. **Coop-specifikation** (PDF eller Excel) — viser linjer for hver faktura
3. **Bogføringssystem-data** (ét af):
- **Uniconta-eksport** (fakturaer, kreditnotaer, åbne poster) — typisk Excel
- **e-conomic API-kald** (se `e-conomic-integration` skill): `/invoices/booked?filter=balance$gt:0&filter=customer.name$like:Coop`
## Coops bankbetalingsformat (typisk)
```
Bogføringsdato;Posteringstekst;Beløb;Saldo
15-06-2026;"Coop Danmark A/S Bankbetaling 12345678";-23.456,78;100.000,00
```
- **Negativ beløb** = du har modtaget penge fra Coop (kredit på din konto)
- **Reference** = Coops bankaftale-id (8 cifre typisk)
- **Dato** = afregningsdato
## Coops specifikation (Excel/PDF, eksempel)
| Fakturanr | Fakturadato | Beløb | Moms | Total | Type |
|---|---|---|---|---|---|
| 2026-1234 | 01-06-2026 | 1.000,00 | 250,00 | 1.250,00 | Faktura |
| 2026-1235 | 02-06-2026 | 2.500,00 | 625,00 | 3.125,00 | Faktura |
| KN-2026-100 | 03-06-2026 | -500,00 | -125,00 | -625,00 | Kreditnota |
| Bonus-2026-06 | 30-06-2026 | -1.000,00 | 0,00 | -1.000,00 | Bonus |
| Modregning-2026-06 | 30-06-2026 | -250,00 | 0,00 | -250,00 | Modregning |
| **Total** | | **1.750,00** | **750,00** | **2.500,00** | |
Bankbetalingen på 2.500,00 kr. dækker altså: 2 fakturaer − 1 kreditnota − bonus − modregning.
## Workflow
### Fase 1: Importér bankbetaling
1. **Modtag Coop-CSV** (typisk Sydbank-format)
2. **Filtrér Coop-poster** (tekst matcher `Coop Danmark`)
3. **Vis hver bankbetaling** med reference, dato, beløb
### Fase 2: Importér opgørelse (specifikation)
1. **Modtag specifikationsfil** (PDF eller Excel)
2. **Parse linjer**: fakturaer, kreditnotaer, bonus, modregninger
3. **Beregn totaler** og verificer at de matcher bankbetalingen
4. **Hvis differens**: marker som "afventer manuel kontrol"
### Fase 3: Match mod bogføringssystem
**Variant A: Uniconta**
1. **Hent Uniconta-fakturaer** (via API eller eksport) for samme periode
2. **For hver faktura i opgørelsen**: søg i Uniconta efter match på:
- **Primær match**: fakturanr + beløb (høj confidence)
- **Sekundær match**: beløb + dato ±7 dage (medium confidence)
- **Ingen match**: marker som "mangler i Uniconta"
**Variant B: e-conomic**
1. **Hent bogførte fakturaer** via API:
```
GET /invoices/booked?filter=balance$gt:0&filter=customer.name$like:Coop
```
2. **Filtrér på kunde** (Coop Danmark A/S) — de fleste Coops kunder findes som kunde 1, men tjek
3. **For hver faktura i opgørelsen**: søg i e-conomic-respons efter match på:
- **Primær match**: `bookedInvoiceNumber` + `grossAmount` (høj confidence)
- **Sekundær match**: `grossAmount` + `date` ±7 dage (medium confidence)
- **Ingen match**: marker som "mangler i e-conomic"
**Vis match-status** for hver linje (uanset variant):
- ✅ Matchet (faktura fundet)
- ⚠️ Forskelligt beløb (faktura fundet, men beløb afviger)
- ❌ Manglende (faktura ikke fundet)
### Fase 4: Generer bogføringsforslag
For hver matchet bankbetaling:
```
BOGFØRINGSFORSLAG — Coop bankbetaling [reference]
═══════════════════════════════════════════════════
Dato: [dd-MM-yyyy]
Bankbeløb: 2.500,00 kr. (positivt = indbetaling)
───────────────────────────────────────────────────
DEBET (kontonr / navn) BELØB
───────────────────────────────────────────────────
[56200] Bank, Sydbank 2.500,00
KREDIT (kontonr / navn) BELØB
───────────────────────────────────────────────────
[10120] Tilgodehavender, salg 1.250,00 (faktura 2026-1234)
[10120] Tilgodehavender, salg 3.125,00 (faktura 2026-1235)
[10120] Tilgodehavender, salg −625,00 (kreditnota KN-2026-100)
[52100] Bonus og rabatter 1.000,00 (bonus)
[58000] Modregning 250,00 (modregning)
Total debet: 2.500,00
Total kredit: 2.500,00
═══════════════════════════════════════════════════
Diff: 0,00 ✅ Balanceret
═══════════════════════════════════════════════════
```
### Fase 5: Bruger-godkendelse
⚠️ **Vis altid bogføringsforslaget og vent på eksplicit godkendelse** før der postes til Radix/Uniconta/e-conomic.
**Hvis brugeren vil bogføre direkte i e-conomic** (se `e-conomic-integration` skill):
1. Vis bogføringsforslaget med konkrete kontonumre
2. Generer `entries` JSON-objekt klar til `/journals/:id/vouchers/:n/entries` POST
3. Generer et UUID v4 Idempotency-Key
4. Vent på "ja, bogfør" — udfør derefter API-kald
5. Verificer at svaret er 201 Created og at `entries` indeholder bogførings-ID
## Almindelige problemer
- ❌ **Bankbeløb matcher ikke opgørelse-total**: typisk fordi opgørelsen kun viser netto (efter Coops egne fradrag som emballage-pant, kampagnerabat, mv.)
- ❌ **Faktura findes ikke i Uniconta**: kan skyldes at fakturaen er bogført i forkert regnskabsår, eller at Uniconta-eksporten er ufuldstændig
- ❌ **Kreditnota findes, men med forkert fortegn**: dobbelt-negativ bliver positivt — håndtér dette eksplicit
- ❌ **Coop-bonus mangler konto**: virksomheder der ikke har en dedikeret bonuskonto bruger typisk 52100 (Bonus/rabatter) — bekræft med brugeren
- ❌ **Modregning uden specifikation**: spørg brugeren — kan være emballage-pant, reklamation, eller andet
- ✅ ALTID verificer at bankbeløb = sum(opgørelseslinjer) ±0,01 kr. (afrundingstolerance)
- ✅ ALTID vis match-status per linje (matchet / afvigende / manglende)
- ✅ ALTID vent på brugerens "ja, bogfør" før API-kald
## Kontering (typisk dansk kontoplan)
| Kontotype | Kontonr (SUM/DG) | Bruges til |
|---|---|---|
| Bank | 56200 | Bank, Sydbank/Jyske/Danske (pengebevægelsen) |
| Tilgodehavender | 10120 | Åbne fakturaer der betales af Coop |
| Bonus/rabatter | 52100 | Coops bonus, årsbonus, kampagnerabat |
| Modregning | 58000 | Emballage-pant, reklamation, Cops egne fradrag |
| Kreditnotaer | 10120 (negativ) | Coops kreditnotaer (vareretur mv.) |
Tallene er eksempler — bekræft altid med virksomhedens egen kontoplan.
## Eksempel-aktivering
**Bruger:** "Jeg har lige fået en Coop-betaling på 12.345,67 kr. d. 15-06-2026. Her er opgørelsen — kan du finde ud af hvad der dækker hvad?"
**Svar (forkortet):**
> ✅ Bankbetaling genkendt: 12.345,67 kr. d. 15-06-2026
>
| Opgørelseslinje | Beløb | Uniconta-match | Status |
> |---|---|---|---|
> | Faktura 2026-1234 | 1.250,00 | UN-5678 | ✅ Matchet |
> | Faktura 2026-1235 | 3.125,00 | UN-5679 | ✅ Matchet |
> | Faktura 2026-1240 | 5.000,00 | UN-5680 | ✅ Matchet |
> | Kreditnota KN-2026-100 | -625,00 | UN-5681 | ✅ Matchet |
> | Bonus Q2 2026 | -1.404,33 | (bogføres direkte) | ⚠️ Ingen reference |
> | **Total** | **7.345,67** | | |
> | **Diff vs bank** | **5.000,00** | | ⚠️ Mangler 5.000,00 kr. |
>
> **Bogføringsforslag:**
> ```
> DEBET 56200 Bank 12.345,67
> KREDIT 10120 Tilgodehavender 1.250,00
> KREDIT 10120 Tilgodehavender 3.125,00
> KREDIT 10120 Tilgodehavender 5.000,00
> KREDIT 10120 Tilgodehavender -625,00
> KREDIT 52100 Bonus -1.404,33
> ```
>
> ⚠️ **Bemærk:** Diff på 5.000,00 kr. — enten mangler en faktura i opgørelsen, eller opgørelsen er ufuldstændig. Vil du:
> 1. Indberette bogføringsforslag som det er (med diff markeret)
> 2. Springe bankbetalingen over indtil videre
> 3. Kontakte Coop for komplet specifikation
skills/accounting/dansk-csv-import/SKILL.md
+178
View File
@@ -0,0 +1,178 @@
---
name: dansk-csv-import
description: >
Importér danske bank-CSV-eksporter (Nordea, Danske Bank, Jyske Bank, Sydbank) og
e-conomic-bankimport-format — aktiveres ved "importér CSV", "bankudtog", "kontoudtog",
"Nordea eksport", "Danske Bank CSV", "Jyske Bank eksport", "e-conomic bankimport".
version: 0.2.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, dansk-regnskab, csv-import, bank, nordea, danske-bank, jyske-bank, e-conomic]
related: [kontoplan-mapping, coop-bankimport, momsafregning, e-conomic-integration]
---
# Dansk CSV-import (bankudtog)
Håndterer import af **danske bank-CSV-eksporter** til Radix ERP med korrekt detektering af:
- Bank (Nordea, Danske Bank, Jyske Bank, Sydbank, Nykredit, Arbejdernes Landsbank)
- Datoformat (dansk `dd-MM-yyyy` eller ISO `yyyy-MM-dd`)
- Decimalformatering (komma som decimal — dansk standard)
- Feltsemikolon (dansk CSV-standard, ikke komma)
- Tegnsæt (Latin1, UTF-8 med/uden BOM)
## Aktiveres ved
- "Importér denne Nordea-CSV til Radix"
- "Jyske Bank har sendt kontoudtog — hjælp med at indlæse det"
- "Parse denne bankeksport"
- "Vis alle transaktioner fra marts 2026 i denne CSV"
## Genkendte bankformater
### Nordea (Erhverv)
```
Bogføringsdato;Tekst;Beløb;Saldo;Valuta;Reference
01-06-2026;"Nets *12345";-123,45;12.345,67;DKK;
```
- Separator: `;`
- Encoding: Latin1
- Beløb: dansk format (`-123,45`)
- Dato: `dd-MM-yyyy`
### Danske Bank
```
Dato;Tekst;Beløb;Saldo
01-06-2026;"MobilePay - Anders Hansen";-250,00;5.000,00
```
- Separator: `;`
- Encoding: UTF-8 med BOM
- Beløb: dansk format
- Dato: `dd-MM-yyyy`
### Jyske Bank
```
Dato;Beskrivelse;Beløb;Saldo
01-06-2026;"POS DSB 1234 København";-89,00;3.456,78
```
- Separator: `;`
- Encoding: Latin1
- Dato: `dd-MM-yyyy`
- Negative beløb: kan være `-89,00` eller `(89,00)` — begge understøttes
### Sydbank
```
Bogføringsdato;Posteringstekst;Beløb;Saldo
01-06-2026;"Coop Danmark A/S Bankbetaling";-12.345,67;45.678,90
```
- Separator: `;`
- Encoding: Latin1
- Dato: `dd-MM-yyyy`
### e-onomic bankimport-format
```
Dato;Tekst;Beløb;Saldo;Modkonto;Valuta;Bankkonto
01-06-2026;"Nets *12345";-123,45;12.345,67;5820;DKK;5508 8765432
```
- Separator: `;`
- Encoding: UTF-8 med BOM
- **Modkonto** (e-conomics kontonr, fx 5820 for bank) — bruges direkte ved bogføring
- **Bankkonto** i dansk 14-cifret format (reg.nr. + kontonr) — verificer mod kundens egen bankaftale
- Dato: `dd-MM-yyyy` (men konverter til ISO `yyyy-MM-dd` før API-kald til e-conomic)
## Workflow
1. **Modtag CSV-fil** (enten via sti eller indhold direkte i chat)
2. **Detektér bank-format** ud fra header (kolonnenavne) — spørg brugeren hvis usikker
3. **Detektér encoding** (tjek for BOM, prøv Latin1, UTF-8)
4. **Parse CSV** med korrekt separator (`;` for dansk)
5. **Normaliser data**:
- Datoer → `dd-MM-yyyy` (ensret formattering)
- Beløb → Python float (erstat `,` med `.`, fjern tusindtalsseparator)
- Negativ beløb → negativ tal (fjern evt. parentesnotation)
- Tekst → trim, fjern dobbelte mellemrum
6. **Vis preview** med de første 5-10 transaktioner (bed brugeren bekræfte format)
7. **Vis statistik**:
- Antal transaktioner
- Periode (første/sidste dato)
- Total ind, total ud, slutbalance
- Kontroller at slutbalance matcher det brugeren forventede
8. **Identificér dubletter** (samme dato + beløb + tekst)
9. **Kortlæg konti** (se kontoplan-mapping skill) — eller lad brugeren vælge
10. **Generer klar-til-import JSON** til Radix ERP API
## Eksempel-aktivering
**Bruger:** *indsætter en filsti eller indhold:*
```
Bogføringsdato;Tekst;Beløb;Saldo;Valuta
01-06-2026;"Nets *12345 MobilePay";-123,45;12.345,67;DKK
02-06-2026;"Coop Danmark";-5.678,90;6.666,77;DKK
...
```
**Svar:**
> ✅ Genkendt format: **Nordea Erhverv** (Latin1, semikolon-separeret)
>
> | Dato | Tekst | Beløb | Saldo |
> |---|---|---|---|
> | 01-06-2026 | Nets *12345 MobilePay | −123,45 | 12.345,67 |
> | 02-06-2026 | Coop Danmark | −5.678,90 | 6.666,77 |
> | ... |
>
> **Statistik:**
> - Periode: 01-06-2026 til 30-06-2026
> - Transaktioner: 47
> - Total ind: 8.901,23 kr.
> - Total ud: 23.456,78 kr.
> - Slutbalance: 6.666,77 kr.
>
> ⚠️ **1 mulig dublet** fundet (samme dato, beløb og tekst på række 12 og 23). Skal jeg springe dubletten over ved import?
## Almindelige CSV-fælder
- ❌ Latin1-filer åbnet som UTF-8 → `æ` i stedet for `æ`
- ❌ Datoer med `.` (amerikansk) i stedet for `-` (dansk)
- ❌ Beløb med `.` som tusindtalsseparator ignoreret
- ❌ Negative beløb som `(123,45)` (parentes) ikke håndteret
- ❌ Header-række fejlfortolket som data
- ❌ Linjeskift i `Tekst`-felt (fx "Coop\nDanmark") brækker parser
- ✅ ALTID detektér encoding først (BOM, Latin1, UTF-8)
- ✅ ALTID vis preview før import
- ✅ ALTID vis statistik og balancesum til kontrol
## Radix ERP API-endpoint (for import)
## Bogføringssystem-integration (efter import)
Efter import kan transaktioner bogføres direkte i e-conomic (se `e-conomic-integration` skill):
```
POST /journals/{journalId}/vouchers/{voucherNumber}/entries
Headers:
X-AppSecretToken: ${ECONOMIC_APP_SECRET_TOKEN}
X-AgreementGrantToken: ${ECONOMIC_AGREEMENT_GRANT_TOKEN}
Idempotency-Key: <UUID v4>
```
Eksempel-payload genereret fra importeret CSV:
```json
{
"accountingYear": {"year": 2026},
"entries": [
{
"date": "2026-06-01",
"text": "Nets *12345 MobilePay",
"amount": -123.45,
"amountInBaseCurrency": -123.45,
"currency": "DKK",
"account": {"accountNumber": 1690},
"contraAccount": {"accountNumber": 5820},
"vatAccount": {"vatCode": "I25"}
}
]
}
```
⚠️ **Bekræft ALTID med brugeren før bulk-import** — vis diff (antal transaktioner, totaler) og kræv eksplicit "ja, importer" før API-kald.
skills/accounting/e-conomic-integration/SKILL.md
+290
View File
@@ -0,0 +1,290 @@
---
name: e-conomic-integration
description: >
Integration med e-conomic cloud-bogføring — aktiveres ved "bogfør i e-conomic", "hent fakturaer
fra e-conomic", "kassekladde", "sync mod e-conomic", "opret kunde i e-conomic", "kontoudtog
e-conomic", "REST API", "AppSecretToken". Dækker auth, kontoplan, kassekladder, bogførte
fakturaer, kreditorer, kunder og banktransaktioner.
version: 0.1.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, e-conomic, dansk-regnskab, api, cloud-bogfoering, integration]
related: [resultatopgoerelse, momsafregning, kontoplan-mapping, coop-bankimport, dansk-csv-import]
---
# e-conomic-integration
Integration med **e-conomic** cloud-bogføringssystem via den officielle REST API. Bruges til at hente fakturaer, kunder, kreditorer, bogføre bilag, synce banktransaktioner og afstemme konti — alt på dansk.
## Aktiveres ved
- "Bogfør denne faktura i e-conomic"
- "Hent åbne fakturaer fra e-conomic"
- "Synk banktransaktioner til e-conomic"
- "Opret kunde X i e-conomic"
- "Hvad er saldi på konto 1010 i e-conomic?"
- "Generer kassekladdeline for denne betaling"
- "Vis alle kreditorer med udestående i e-conomic"
## API basics
### Base-URL
```
https://restapi.e-conomic.com
```
### Auth (kræver to tokens)
| Header | Værdi | Hvad det er |
|---|---|---|
| `X-AppSecretToken` | `${ECONOMIC_APP_SECRET_TOKEN}` | App-identifikation (din app's hemmelige token) |
| `X-AgreementGrantToken` | `${ECONOMIC_AGREEMENT_GRANT_TOKEN}` | Aftale-specifik adgang (bruger-godkendt) |
| `Content-Type` | `application/json` | Altid JSON |
| `Idempotency-Key` | `<unik UUID>` | Forhindrer dobbeltbogføring ved netværksfejl (POST/PUT) |
⚠️ **Tokens skal ALDRIG hardcodes** — brug miljøvariabler eller en secret manager.
### Demo-mode (sandbox)
Til test/udvikling, tilføj `?demo=true` til URL — alle writes deaktiveres (kun GET).
## Vigtigste endpoints
| Formål | Endpoint | HTTP |
|---|---|---|
| List konti (kontoplan) | `/accounts?pagesize=N` | GET |
| Hent én konto | `/accounts/:accountNumber` | GET |
| List bogføringsår | `/accounting-years` | GET |
| List perioder (måneder) i et år | `/accounting-years/:year/periods` | GET |
| Hent kontosaldo for en periode | `/accounts/:accountNumber/accounting-years/:year/periods/:period/totals` | GET |
| List kassekladder | `/journals` | GET |
| Hent kassekladdeline | `/journals/:id/vouchers?voucherNumber=:n` | GET |
| Opret kassekladdeline (bilag) | `/journals/:id/vouchers/:n/entries` | POST |
| Bogfør voucher | `/journals/:id/vouchers/:n/book` | POST |
| List bogførte fakturaer | `/invoices/booked` | GET |
| Opret bogført faktura | `/invoices/booked` | POST |
| Hent kunde | `/customers/:customerNumber` | GET |
| Opret kunde | `/customers` | POST |
| List kreditorer | `/suppliers` | GET |
| Opret kreditor | `/suppliers` | POST |
| List moms-konti | `/vat-accounts` | GET |
| Hent valutakurser | `/currencies` | GET |
⚠️ **Rate limit**: e-conomic har et fair-use loft. Hold dig under 10 requests/sekund.
## e-conomics standardkontoplan (4-cifret)
| Kontointerval | Type | Bruges til |
|---|---|---|
| 1000-1099 | Heading/profitAndLoss | Indtægter, overskrifter |
| 1100-1199 | ProfitAndLoss | Omsætning undergrupper (varekategorier) |
| 1200-1299 | ProfitAndLoss | Diverse indtægter |
| 1300-1399 | ProfitAndLoss | Produktionsomkostninger (COGS) |
| 1500-1599 | ProfitAndLoss | Lokaleomkostninger |
| 1600-1699 | ProfitAndLoss | Salgsomkostninger |
| 1700-1799 | ProfitAndLoss | Administrationsomkostninger |
| 1800-1899 | ProfitAndLoss | Personaleomkostninger (løn) |
| 2000-2099 | ProfitAndLoss | Andre driftsomkostninger |
| 2100-2199 | ProfitAndLoss | Afskrivninger |
| 2200-2299 | ProfitAndLoss | Finansielle indtægter |
| 2300-2399 | ProfitAndLoss | Finansielle udgifter |
| **5500-5899** | **Balance** | **Bank, kasse, tilgodehavender** |
| 5800-5899 | Balance | Bankkonti (typisk 5820 = drift) |
| 6000-6899 | Balance | Leverandørgæld, moms, A-skat |
| 6500-6599 | Balance | Moms (6500 = indgående, 6600 = udgående) |
| 6900-6999 | Balance | Diverse statuskonti |
⚠️ **Dette er e-conomics STANDARD kontoplan** — ikke alle kunder har den. Hent altid kundens egen kontoplan via `/accounts` endpoint.
## Momskoder (VAT-accounts)
| Kode | Type | Sats | Bruges til |
|---|---|---|---|
| `U25` | Udgående | 25% | Salg af varer/ydelser i DK (momspligtig) |
| `I25` | Indgående | 25% | Køb af varer/ydelser i DK (momsfradrag) |
| `U0` | Udgående | 0% | Eksport, EU-salg med VIES, moms-fritagne ydelser |
| `I0` | Indgående | 0% | Køb uden moms (import under bagatelgrænse) |
| `UEU25` | Udgående | 25% | EU-varesalg (vareleverance til andet EU-land) |
| `UV25` | Udgående | 25% | Byggeydelser i andre EU-lande (omvendt betalingspligt) |
⚠️ Korrekt momskode er afgørende for momsangivelsen — forkert kode kan give skattesmæk.
## Kassekladder (Journals)
| Journal-ID | Navn (typisk) | Bruges til |
|---|---|---|
| 1 | Daglig / Kassekladde | Almindelige bilag (køb, salg, bank) |
| 2 | Indbetalinger | Kundeindbetalinger (kontra-konto typisk 5820 bank) |
| 3 | Lønninger | Lønbogføring (entryType `financeVoucher`) |
| 4 | Moms | Momsafregning |
| 5 | Afskrivninger | Anlægsaktiver |
Journal-ID'er varierer fra kunde til kunde — hent altid `/journals` først.
## Workflow: Bogfør et bilag (kassekladdeline)
### Eksempel: bogfør kontantkøb af kontorartikler for 1.250,00 kr. inkl. moms (15-06-2026)
**Trin 1: Hent kunde-/kassekladde-info**
```
GET /journals
→ Find journal-ID for "Daglig" (typisk 1)
GET /journals/1/vouchers?voucherNumber=42
→ Find næste ledige bilagsnummer
```
**Trin 2: Opret kassekladdeline (visuelt, FØR API-kald)**
```json
{
"accountingYear": {
"year": 2026
},
"entries": [
{
"customerInvoiceNumber": "",
"date": "2026-06-15",
"voucherNumber": 42,
"text": "Kontorartikler — Kontorbutikken A/S",
"amount": -1250.00,
"amountInBaseCurrency": -1250.00,
"currency": "DKK",
"account": {
"accountNumber": 1690
},
"contraAccount": {
"accountNumber": 5820
},
"vatAccount": {
"vatCode": "I25"
}
}
]
}
```
**Trin 3: Vis brugeren og bekræft**
```
⚠️ Klar til at bogføre:
Kassekladde: Daglig (#1)
Bilagsnr: 42
Dato: 15-06-2026
Tekst: Kontorartikler — Kontorbutikken A/S
Debet: 1690 Kontorartikler 1.250,00 kr.
Kredit: 5820 Bank, drift −1.250,00 kr.
Momskode: I25 (25% indgående)
Total: 1.250,00 kr. (inkl. 250,00 kr. moms)
Vil du bogføre? (ja/nej)
```
**Trin 4: POST med Idempotency-Key**
```
POST /journals/1/vouchers/42/entries
Headers:
X-AppSecretToken: ${ECONOMIC_APP_SECRET_TOKEN}
X-AgreementGrantToken: ${ECONOMIC_AGREEMENT_GRANT_TOKEN}
Content-Type: application/json
Idempotency-Key: <UUID v4>
Body: [ovenstående entries-array]
```
⚠️ **Bogfør IKKE før brugeren har bekræftet.**
## Workflow: Synk banktransaktioner
1. **Hent konti** for bank (`/accounts?filter=accountType$eq:balance&pagesize=100`) — find bank-konto (typisk 5820)
2. **Hent kontosaldo** for indeværende periode:
```
GET /accounts/5820/accounting-years/2026/periods/6/totals
```
3. **Sammenlign** med bankens faktiske saldo (fra CSV-import eller bank-API)
4. **Vis diff** og identificer manglende/ukorrekte transaktioner
5. **Foreslå kassekladdeline** for hver manglende transaktion
## Workflow: Hent åbne fakturaer (kunder)
```
GET /invoices/booked?filter=balance$gt:0&pagesize=50
```
Returnerer alle bogførte fakturaer med ubetalt saldo > 0.
For hver faktura:
- `bookedInvoiceNumber` — fakturanr
- `customer.name` — kundenavn
- `netAmount` / `grossAmount` — beløb ekskl./inkl. moms
- `balance` — udestående
- `dueDate` — forfaldsdato (udledes af `termsNetDays` + `date`)
- `currency` — DKK/EUR/USD
Bruges typisk til:
- Inkasso-rapporter (forfaldne >30 dage)
- Aldersopdelt fordringsliste (0-30, 31-60, 61-90, 90+)
- Likviditetsforecast
## Workflow: Opret kunde
```json
POST /customers
{
"name": "Coop Danmark A/S",
"customerGroup": { "customerGroupNumber": 1 },
"paymentTerms": { "paymentTermsNumber": 1 },
"vatZone": { "vatZoneNumber": 1 },
"currency": "DKK",
"address": "Roskildevej 65",
"zip": "2620",
"city": "Albertslund",
"country": "Denmark"
}
```
⚠️ **Tjek altid for duplikat** (søg eksisterende kunder først):
```
GET /customers?filter=name$like:Coop$Danmark
```
## Almindelige fejl
- ❌ **Glemmer Idempotency-Key** ved POST → netværksfejl kan give dobbeltbogføring
- ❌ **Forkert momskode** (U25 vs UEU25) → SKAT fanger det i krydstjek
- ❌ **Brug danske datoer i API** — e-conomic bruger ISO `yyyy-MM-dd` i JSON, IKKE dansk `dd-MM-yyyy`
- ❌ **Beløb uden fortegn-konvention** — negativ = debet, positiv = kredit (modsat dansk regnskabstradition)
- ❌ **PageSize > 1000** uden pagination
- ❌ **POST uden først at have hentet den aktuelle voucher** → 409 Conflict
- ✅ ALTID brug Idempotency-Key ved alle writes
- ✅ ALTID konverter dansk dd-MM-yyyy → ISO yyyy-MM-dd FØR API-kald
- ✅ ALTID verificer kontoplanen (`/accounts`) før bogføring — kunden kan have egne konti
- ✅ ALTID tjek eksisterende kunder/leverandører før oprettelse (dublet-forebyggelse)
- ✅ ALTID vis bogføringsforslag til brugeren FØR API-kald
## Demo-mode anbefaling
Brug ALTID `?demo=true` under udvikling:
- Læs-data virker (GET)
- Skrive-data deaktiveret (POST/PUT returnerer 405)
- Forhindrer utilsigtet bogføring i produktion
- Kan derfor frit browse konti, fakturaer, kunder uden risiko
## Eksempel på aktivering
**Bruger:** "Bogfør et køb af kontorartikler for 1.250 kr. inkl. moms i e-conomic"
**Svar (forkortet):**
> ✅ Forbinder e-conomic...
>
> Klar til bogføring:
>
> | Felt | Værdi |
> |---|---|
> | Kassekladde | Daglig (#1) |
> | Bilagsnr | 42 |
> | Dato | 15-06-2026 |
> | Tekst | Kontorartikler — Kontorbutikken A/S |
> | Debet (1690 Kontorartikler) | 1.250,00 kr. |
> | Kredit (5820 Bank) | −1.250,00 kr. |
> | Momskode | I25 (indgående 25%) |
>
> ⚠️ Bekræft før jeg bogfører. Svaret "ja, bogfør" udløser API-kald med Idempotency-Key.
skills/accounting/kontoplan-mapping/SKILL.md
+183
View File
@@ -0,0 +1,183 @@
---
name: kontoplan-mapping
description: >
Kortlæg transaktioner, fakturaer og bilag til dansk standardkontoplan (SUM, DG, SL) eller
bogføringssystem-specifik kontoplan (e-conomic 4-cifret, Uniconta) — aktiveres ved
"hvilken konto?", "kontoplan", "kontorådgivning", "bogføring af [transaktionstype]",
"hvor skal jeg bogføre dette".
version: 0.2.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, dansk-regnskab, kontoplan, SUM, DG, SL, uniconta, e-conomic]
related: [resultatopgoerelse, momsafregning, dansk-csv-import, e-conomic-integration]
---
# Kontoplan-mapping
Mapper transaktioner og bilag til **korrekt konto i dansk standardkontoplan** (SUM, DG, SL). Bruges som hjælpe-skill af andre skills (resultatopgoerelse, momsafregning, dansk-csv-import, coop-bankimport).
## Aktiveres ved
- "Hvilken konto skal jeg bogføre et kontorlejemål på?"
- "Hvor hører MobilePay-gebyr hjemme i kontoplanen?"
- "Lav en kontoplan for min [virksomhedstype]"
- "Tjek om denne transaktion er konteret korrekt"
## Dansk standardkontoplan — overblik
### Driftskonti (resultatopgørelse)
| Hovedgruppe | Kontointerval | Bruges til |
|---|---|---|
| Omsætning | 1000-1999 | Salg, service, licens, abonnement, eksport |
| Produktionsomkostninger | 2000-2999 | Råvarer, direkte løn, underleverandører, fragt |
| Salgsomkostninger | 3000-3999 | Marketing, salgsfremmende, rejser, repræsentation |
| Administrationsomkostninger | 4000-4999 | Kontor, IT, telefon, kontorartikler, abonnementer |
| Lokaleomkostninger | 5000-5999 | Husleje, varme, el, vand, renovation, rengøring |
| Personaleomkostninger | 6000-6999 | Løn, pension, ATP, feriepenge, AER, sociale bidrag |
| Afskrivninger | 7000-7999 | Lineære afskrivninger, scrap, salg af aktiver |
| Finansielle poster | 8000-8999 | Renter, gebyrer, kursregulering, realiserede tab/gevinst |
| Ekstraordinære poster | 9000-9999 | Ekstraordinære indtægter/udgifter (sjældent) |
### Statuskonti (balance)
| Hovedgruppe | Kontointerval | Bruges til |
|---|---|---|
| Aktiver | 10000-19999 | Tilgodehavender, varelager, anlægsaktiver, bank, kasse |
| Passiver | 20000-29999 | Leverandørgæld, moms, A-skat, skyldig løn, feriepengeforpligtelse |
| Egenkapital | 30000-39999 | Ansvarlig kapital, overført resultat, årets resultat |
## e-conomic standardkontoplan (4-cifret, mest udbredt)
e-conomic leveres med en standard dansk kontoplan. **De fleste danske SMV'er bruger denne uden ændringer.**
### Driftskonti (resultatopgørelse)
| Kontointerval | Bruges til |
|---|---|
| 1000-1099 | Indtægter (heading + omsætning) |
| 1100-1299 | Diverse omsætning og indtægter |
| 1300-1499 | Produktionsomkostninger / varekøb / direkte løn |
| 1500-1599 | Lokaleomkostninger (husleje, el, varme) |
| 1600-1699 | Salgs- og rejseomkostninger (marketing, transport) |
| 1700-1799 | Administrationsomkostninger (kontor, IT, telefon) |
| 1800-1899 | Personaleomkostninger (løn, pension, AER) |
| 1900-2099 | Andre driftsomkostninger, afskrivninger |
| 2100-2299 | Finansielle poster (renter, gebyrer) |
| 2300-2999 | Ekstraordinære poster |
### Statuskonti (balance)
| Kontointerval | Bruges til |
|---|---|
| 5500-5899 | Aktiver — bank, kasse, tilgodehavender (5820 = typisk driftsbank) |
| 6000-6899 | Passiver — leverandørgæld, moms, A-skat, skyldig løn |
| 6500-6599 | Moms (udgående/indgående/afregning) |
| 6900-6999 | Egenkapital, diverse status |
### e-conomic standardkonti — udvalgte
| Kontonr | Navn | Bruges til |
|---|---|---|
| 1010 | Salg af varer/ydelser m/moms | Standard DK-salg (25% moms) |
| 1080 | Salg af varer/ydelser u/moms | Eksport, EU-salg (0% moms) |
| 1300 | Varekøb | Råvarer til videresalg |
| 1500 | Husleje | Kontorlejemål |
| 1510 | El | Elforbrug |
| 1520 | Varme | Opvarmning |
| 1530 | Vand | Vandforbrug |
| 1610 | Rejseudgifter | Transport, hotel, fly |
| 1690 | Kontorartikler | Småanskaffelser, kontorartikler |
| 1700 | Telefon & internet | Mobil, fastnet, internet |
| 1730 | Software / IT-licenser | SaaS-abonnementer, licenser |
| 1800 | Bruttoløn | Lønudbetaling |
| 1810 | Pension | Pensionsbidrag |
| 1820 | ATP | ATP-bidrag |
| 1900 | AER | AER-bidrag |
| 1910 | Feriepenge | Feriepengeforpligtelse |
| 2200 | Bankgebyrer | Gebyrer, renter |
| 2210 | Renteudgifter | Renter på lån |
| 5500 | Kasse | Kontant beholdning |
| 5508 | Bank, drift | Primær driftskonto (typisk) |
| 5820 | Bank, kassekladde | Standard bank-modkonto |
| 6500 | Udgående moms | 25% moms på salg |
| 6510 | Indgående moms | 25% moms på køb |
| 6520 | Momsafregning | Saldo (kredit = skyldig, debet = tilgodehavende) |
⚠️ **Tjek altid kundens egen kontoplan** via `GET /accounts` (e-conomic) eller Uniconta-eksport — der kan være afvigelser.
## Almindelige transaktioner — hurtig-mapping (alle systemer)
| Transaktion | SUM/DG | e-conomic | Type |
|---|---|---|---|
| Salg af vare (DK) | 1010 | 1010 | Driftsindtægt |
| Salg af ydelse (DK) | 1020 | 1010 | Driftsindtægt |
| Eksport (0% moms) | 1030 | 1080 | Driftsindtægt |
| Varekøb (DK) | 2010 | 1300 | Driftsomkostning |
| Kontorartikler | 4010 | 1690 | Driftsomkostning |
| Software-abonnement | 4030 | 1730 | Driftsomkostning |
| Hosting / cloud | 4030 | 1730 | Driftsomkostning |
| Husleje | 5010 | 1500 | Driftsomkostning |
| El, vand, varme | 5020-5040 | 1510-1530 | Driftsomkostning |
| Internet, telefon | 5050 | 1700 | Driftsomkostning |
| MobilePay-gebyr | 8010 | 2200 | Driftsomkostning (finansiel) |
| Stripe-gebyr | 8010 | 2200 | Driftsomkostning (finansiel) |
| Bankgebyr | 8020 | 2200 | Driftsomkostning (finansiel) |
| Renteindtægt | 8030 | 2210 (neg.) | Driftsindtægt (finansiel) |
| Renteudgift | 8040 | 2210 | Driftsomkostning (finansiel) |
| Løn til ansat | 6010 | 1800 | Personaleomkostning |
| A-skat (trukket fra løn) | 2090 | 6810 | Forpligtelse |
| Pension (arbejdsgivers andel) | 6020 | 1810 | Personaleomkostning |
| Feriepenge (reserveret) | 6015 | 1910 | Personaleomkostning |
| Moms, udgående | 2060 | 6500 | Forpligtelse |
| Moms, indgående | 2070 | 6510 | Tilgodehavende (modregnes) |
| Moms, afregning | 2080 | 6520 | Forpligtelse/Tilgodehavende |
| Bank (drift) | 5810 | 5508 / 5820 | Aktiv |
⚠️ **Tallene er eksempler iht. SUM-standarden** (Standard for virksomheders økonomistyring). Mange SMV'er bruger deres egen tilpassede kontoplan — **bekræft altid med virksomhedens egen kontoplan** inden bogføring.
## Workflow
1. **Modtag transaktionstype** (eller specifik transaktion)
2. **Find relevant kontointerval** (se tabellerne ovenfor)
3. **Anvend kontekst-regler**:
- Virksomhedstype (enkeltmands, ApS, A/S, forening) → kan have egne konti
- Branche (detail, engros, service, IT, produktion) → brancherelaterede konti
- Skatteforhold (momsregistrering, CVR, SElvangivelse) → særlige konti
4. **Vis anbefaling med begrundelse**:
- Kontonr, kontonavn, kontogruppe
- Hvorfor denne konto og ikke en alternativ
5. **Alternativer**: vis 1-2 alternative konti hvis der er rimelig tvivl
6. **Bekræft med bruger** — kontoplan-valg er en menneskelig beslutning, ikke en agent-beslutning
## Eksempel-aktivering
**Bruger:** "Hvor skal jeg bogføre et Stripe-gebyr på 234,56 kr.?"
**Svar:**
> **Anbefalet konto:** 8010 — Gebyrer, betalingsformidlere
>
> **Begrundelse:** Stripe-gebyrer er **finansielle omkostninger** (betalingsformidling), ikke driftsomkostninger. De hører under hovedgruppe 8 (Finansielle poster) og bogføres typisk sammen med bankgebyrer og renter.
>
> **Bogføring:**
> ```
> DEBET 8010 Gebyrer, betalingsformidlere 234,56
> KREDIT 5810 Bank, driftskonto 234,56
> ```
>
> **Alternativer:**
> - 8030 (Renteudgifter) — hvis virksomheden samler alle gebyrer dér (mindre korrekt)
> - 4025 (Salgsomkostninger, eksterne) — hvis virksomheden klassificerer alle salgsrelaterede omkostninger under salg
>
> ⚠️ *Dette er ikke bogføringsrådgivning. Kontakt din revisor for endelig kontoplan.*
## Særlige regler
- ❌ ALDRIG foreslå en konto uden begrundelse
- ❌ ALDRIG antag at kontoplanen følger SUM-standarden — bekræft med brugeren
- ❌ ALDRIG modificér kontoplanen uden advarsel og dobbeltgodkendelse
- ✅ ALTID vis kontogruppe (drift/balance) og sektion (omsætning/omkostning/aktiv/passiv)
- ✅ ALTID vis alternativer når der er rimelig tvivl
- ✅ ALTID medtag "Dette er ikke bogføringsrådgivning" disclaimer
skills/accounting/momsafregning/SKILL.md
+161
View File
@@ -0,0 +1,161 @@
---
name: momsafregning
description: >
Beregn dansk momsangivelse (moms, momsfradrag, momsrefusion) til SKAT — aktiveres ved
forespørgsler om "moms", "momsangivelse", "momsrefusion", "kvartalsmoms", "halvårsmoms",
"momsregnskab", "25% moms", "momsfri".
version: 0.1.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, dansk-regnskab, moms, skat, momsangivelse]
related: [resultatopgoerelse, kontoplan-mapping, dansk-csv-import]
---
# Dansk Momsafregning
Forbereder **momsangivelse** klar til indberetning via SKAT's TastSelv Erhverv (eller skat.dk). Håndterer både **kvartalsmoms** (små/mellemstore virksomheder) og **halvårsmoms** (helårsmomsansøgere, mikrovirksomheder under 5 mio. kr. i omsætning).
## Aktiveres ved
- "Beregn moms for Q2 2026"
- "Forbered momsangivelse for maj 2026"
- "Hvad er min momsrefusion for hele 2025?"
- "Hvornår skal jeg indberette moms næste gang?"
## Danske momssatser (gældende)
| Sats | Bruges til |
|---|---|
| **25%** | Standard (langt de fleste varer og ydelser i Danmark) |
| **0%** | Eksport ud af EU, visse avis/abonnementer, kunstnerisk virksomhed under 300.000 kr. |
| Fritaget | Sygehusbehandling, undervisning, finansielle ydelser, forsikring |
⚠️ **Bemærk**: EU-lande har forskellige satser, men denne skill håndterer **kun dansk moms**. For EU-handel brug særskilt sub-skill (ikke del af denne version).
## Kontogruppering (dansk standardkontoplan + e-conomic)
| Konto (SUM) | Konto (e-conomic) | Navn | Beløb i momsangivelsen |
|---|---|---|---|
| 1100-1199 | 1010 | Salg af varer/ydelser (DK, 25%) | Rubrik A: Varesalg (momspligtig) |
| 1200-1299 | 1010 | Salg af ydelser (DK, 25%) | Rubrik A: Ydelsessalg (momspligtig) |
| 1500-1599 | 1080 | Eksport (0% moms) | Rubrik A: EU-salg/eksport |
| 1600-1699 | 1300 | Råvarer/varekøb (DK, 25%) | Rubrik B: Varekøb (momsfradrag) |
| 1700-1799 | 1690 / 1730 | Driftsomkostninger (DK, 25%) | Rubrik B: Driftsomkostninger (momsfradrag) |
| 1800-1899 | 1800 | Import (køb fra udland) | Rubrik B: Import |
| 1900-1999 | — | Køb af ydelser uden moms | (ingen moms at fradrage) |
| 2060 | 6500 | Udgående moms | (salgsmoms) |
| 2070 | 6510 | Indgående moms | (momsfradrag) |
| 2080 | 6520 | Momsafregning | (saldo) |
⚠️ **Tjek altid kundens egen kontoplan** — de faktiske kontonumre kan variere. Ovenstående er standard-reference for både SUM (dansk standardkontoplan) og e-conomic (4-cifret).
## Struktur (momsangivelse, kvartal)
```
MOMSANGIVELSE — [Kvartal] [År]
═══════════════════════════════════════════════════
Periode: [dd-MM-yyyy] til [dd-MM-yyyy]
CVR: [hentes fra Radix]
═══════════════════════════════════════════════════
RUBRIK A — UDGÅENDE MOMS (moms af salg)
───────────────────────────────────────────────────
A1 Varesalg, momspligtig (25%) 1.234.567,89
A2 Ydelsessalg, momspligtig (25%) 89.012,34
A3 Varesalg, EU/eksport (0%) 0,00
A4 Ydelsessalg, EU (0%) 0,00
...
Udgående moms i alt (25% af A1+A2) 330.895,06
───────────────────────────────────────────────────
RUBRIK B — INDGÅENDE MOMS (moms på køb, kan fradrages)
───────────────────────────────────────────────────
B1 Varekøb, momsfradrag (25%) 450.123,45
B2 Driftsomkostninger, momsfradrag (25%) 67.890,12
B3 Import, betalt toldmoms 0,00
...
Indgående moms i alt (25% af B1+B2) 129.503,39
───────────────────────────────────────────────────
RUBRIK C — SALGSMOMS (MOMS DER SKAL INDBETALES)
═══════════════════════════════════════════════════
Udgående moms 330.895,06
Indgående moms −129.503,39
───────────────────────────────────────────────────
SALGSMOMS 201.391,67
═══════════════════════════════════════════════════
Hvis positiv: SKAT skylder dig penge
Hvis negativ: Du skylder SKAT penge
───────────────────────────────────────────────────
INDBETALINGSFRIST
───────────────────────────────────────────────────
Kvartalsmoms: 1. i 3. måned efter kvartalets udløb
Eksempel: Q1 (jan-mar) → frist 1. juni
═══════════════════════════════════════════════════
```
## Workflow
1. **Spørg om periode** (måned, kvartal, halvår)
2. **Bekræft virksomhedstype**: lille/mellemstor (kvartal) eller helårsmomsansøger (halvår)
3. **Hent salg og køb** fra Radix ERP for perioden
4. **Adskil konti** efter momssats (25%, 0%, fritaget)
5. **Beregn udgående moms** (moms af eget salg) og **indgående moms** (moms af køb)
6. **Beregn salgsmoms** = udgående moms − indgående moms
7. **Vis beløb at indberette** (positiv = SKAT skylder dig, negativ = du skylder SKAT)
8. **Angiv indberetningsfrist** iht. SKAT's regler
9. **Tilbyd at generere SKAT XML/CSV** (hvis brugeren vil indberette direkte)
## Reverse charge (vigtig!)
For køb af ydelser fra udlandet (fx en tysk konsulent):
- **Køber** skal selv beregne og indberette momsen (reverse charge)
- Konti der er reverse charge: typisk 1900-1999 (køb af ydelser uden moms i købsprisen)
- I momsangivelsen: medtag i **Rubrik A** (både salg OG køb) og **Rubrik B** som fradrag — nettoeffekten er nul, men SKAT kræver begge beløb indberettet
## Almindelige fejl
- ❌ Medtag IKKE lønudgifter i momsbasis (løn er momsfri i DK)
- ❌ Medtag IKKE renter i momsbasis (finansielle ydelser er fritaget)
- ❌ Glem IKKE reverse charge-beløb — SKAT krydstjekker
- ❌ Brug IKKE EUR-sats for DK-virksomheder — 25% er dansk standardsats
- ✅ ALTID angiv CVR-nummer i rapporten
- ✅ ALTID vis "Dette er ikke skatterådgivning — kontakt din revisor/SKAT" på momsangivelser
## SKAT-frister (2026)
| Type | Periode | Frist |
|---|---|---|
| Kvartalsmoms | Q1 (jan-mar) | 1. juni |
| Kvartalsmoms | Q2 (apr-jun) | 1. september |
| Kvartalsmoms | Q3 (jul-sep) | 1. december |
| Kvartalsmoms | Q4 (okt-dec) | 1. marts (næste år) |
| Halvårsmoms | H1 (jan-jun) | 1. september |
| Halvårsmoms | H2 (jul-dec) | 1. marts (næste år) |
| Moms, mikrovirksomhed (<5 mio. kr.) | Helår (jan-dec) | 1. marts (næste år, men kun hvis ansøgt om helårsmoms) |
⚠️ Frister kan ændre sig — tjek altid skat.dk for aktuelle frister.
## Eksempel på aktivering
**Bruger:** "Forbered momsangivelse for Q2 2026"
**Svar (forkortet):**
> Momsangivelse for perioden 01-04-2026 til 30-06-2026:
>
> | Rubrik | Beløb | Moms |
> |---|---|---|
> | A1 Varesalg | 234.567,89 | 58.641,97 |
> | A2 Ydelsessalg | 12.345,67 | 3.086,42 |
> | B1 Varekøb | 89.012,34 | 22.253,09 |
> | B2 Driftsomk. | 23.456,78 | 5.864,20 |
> | **Salgsmoms** | | **33.611,10** |
>
> **Frist:** 01-09-2026 (1. september 2026)
>
> *Dette er ikke skatterådgivning. Kontakt din revisor eller SKAT for endelig indberetning.*
skills/accounting/radix-accounting/SKILL.md
+104
View File
@@ -0,0 +1,104 @@
---
name: radix-accountant
description: >
Dansk bogføring, regnskab og ERP-assistance til Radix-portalen — aktiveres ved forespørgsler om
resultatopgørelse, momsafregning, kontoplan, CSV-import, bankafstemning, Uniconta-integration,
e-conomic-integration eller Coop Danmark-reconciliation. Svar altid på dansk, brug dansk
talformatering (1.234.567,89) og dd-MM-yyyy datoformat.
version: 0.2.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, dansk-regnskab, moms, radix-erp, uniconta, e-conomic, coop]
related: [resultatopgoerelse, momsafregning, kontoplan-mapping, dansk-csv-import, coop-bankimport, e-conomic-integration]
---
# radix-accountant
Dansk bogførings- og regnskabsassistent skræddersyet til **Radix ERP** (CRM/ERP kørt på portal.radixadm.dk) med integration mod **Uniconta** (lokalt), **e-conomic** (cloud-bogføring) og **Coop Danmark**-afstemningsflow.
## Aktiveres ved
Når brugeren skriver på dansk om:
- **Resultatopgørelse, P&L, årsregnskab, balance, indtægter/udgifter** → `resultatopgoerelse`
- **Moms, momsangivelse, momsfradrag, momsrefusion, kvartals-/halvårsmoms, 25% / 0%** → `momsafregning`
- **CSV-import, bank-eksport, kontoudtog, Nordea/Danske Bank/Jyske/Sydbank-format** → `dansk-csv-import`
- **Coop Danmark, bankbetaling, opgørelse, afstemning mod fakturaer** → `coop-bankimport`
- **Kontoplan, kontonummer, dansk standardkontoplan, finanskonto, postering** → `kontoplan-mapping`
- **e-conomic, bogfør i e-conomic, hent fakturaer fra e-conomic, kassekladde, sync mod e-conomic** → `e-conomic-integration`
## Faste konventioner (BINDENDE for alle sub-skills)
| Parameter | Værdi |
|---|---|
| Sprog | Dansk (alle svar, prompts, fejlmeddelelser) |
| Talformatering | `1.234.567,89` — punktum som tusindtalsseparator, komma som decimal |
| Negativ beløb | `−1.234,56` med unicode minus-tegn (Unicode minus U+2212), ALDRIG `-` |
| Datoformat | `dd-MM-yyyy` (fx `15-06-2026`) |
| Klokkeslæt | `HH:mm` 24-timers (fx `14:35`) |
| Valuta | `kr.` eller `DKK` — aldrig `$` medmindre brugeren eksplicit beder om anden valuta |
| Moms | `25%` (standard), `0%` (fritagne ydelser), `ekskl. moms` / `inkl. moms` |
| Kontoplan reference | **e-conomic**: 4-cifret DK-standard (1000-9999). **Uniconta**: egen struktur. **SUM/DG/SL**: generisk dansk standard |
| Decimaler i rapporter | 2 decimaler for beløb, 1 decimal for procenter, 0 decimaler for heltal |
| Afrundingsregel | Banker's rounding (half-even) for at matche dansk bogføringspraksis |
| Bank reference | BIC + 10-cifret kontonr (dansk format) eller bank-reference fra CSV |
## Reference-miljø
- **Radix ERP**: kører på `https://portal.radixadm.dk` (DEBUG=True bevidst, dansk datoformat bevidst)
- **Test-login**: `testadmin@example.dk` / `test1234` (KUN til test/udvikling — ALDRIG persistér i rapporter)
- **Uniconta**: lokalt bogføringssystem, fakturaer og kreditorer hentes derfra
- **e-conomic**: cloud-bogføring (https://www.e-conomic.dk), REST API på `https://restapi.e-conomic.com`, OAuth-baseret adgang via AppSecretToken + AgreementGrantToken
- **Coop Danmark**: bankbetalinger + specifikationer (opgørelser) per indbetaling
## Bogføringssystem — hvornår bruges hvad
| System | Bruges til | Fordel | Ulempe |
|---|---|---|---|
| **Uniconta** | Dansk lokalt bogføringssystem, mange SMV'er | Lokal kontrol, dyb funktionalitet | Kræver installation |
| **e-conomic** | Cloud-bogføring, Danmarks mest udbredte | Altid tilgængeligt, stærk API, gratis for små | Begrænset fleksibilitet i kontoplan |
| **Radix ERP (egen)** | Intern ERP, CRM-delen | Integreret med Radix-data | Bogføring er ikke primær funktion |
**Standardantagelse**: Hvis brugeren ikke specificerer, brug **e-conomic** (mest udbredt i danske SMV'er og har den bedste API). Spørg hvis det er uklart.
## Workflow
1. **Identificér brugerens hensigt** ud fra nøgleord (se listen ovenfor)
2. **Aktivér den relevante sub-skill** ved at indlæse dennes `SKILL.md` først
3. **Anvend de faste konventioner** i alle output (sprog, tal, dato, valuta)
4. **Bekræft data med brugeren** før du skriver noget tilbage til Radix/Uniconta/e-conomic (aldrig stille skriv)
5. **Generer rapporten** med tydelig header, periode, totaler og fodnoter
6. **Vis altid kildereference** (transaktions-id, fakturanummer, bankreference) i rapporter
## Vigtige regler
- ❌ ALDRIG bogfør uden brugerens eksplicitte godkendelse — vis diff først
- ❌ ALDRIG antag valuta — bekræft `DKK`/`EUR`/`USD` hvis ikke tydeligt
- ❌ ALDRIG brug amerikansk/UK-formatering (`,` som tusindtalsseparator) — det er den forkerte vej rundt for dansk
- ❌ ALDRIG modificér kontoplanen uden advarsel — ændringer kræver dobbeltgodkendelse
- ❌ ALDRIG hardcode API-tokens i eksempler — brug altid `${ECONOMIC_APP_SECRET_TOKEN}` placeholder-syntaks
- ❌ ALDRIG bogfør bilag i e-conomic uden først at vise `entries` JSON til brugeren
- ✅ ALTID vis "Dette er ikke bogføringsrådgivning — kontakt din revisor" på alle moms- og årsregnskabsrapporter
- ✅ ALTID angiv kilde (bankfil, Uniconta-id, e-conomic-bogføringsnr, faktura-nr) for hvert tal
- ✅ ALTID spørg før du sletter — brug aldrig `DELETE` uden bekræftelse
- ✅ ALTID brug Idempotency-Key ved POST/PUT til e-conomic API (forhindrer dobbeltbogføring ved netværksfejl)
## Sub-skills
| Skill | Formål |
|---|---|
| [resultatopgoerelse](resultatopgoerelse/SKILL.md) | Byg dansk P&L/resultatopgørelse med korrekt kontogruppering |
| [momsafregning](momsafregning/SKILL.md) | Beregn momsangivelse (kvartal/halvår), klar til SKAT-indberetning |
| [kontoplan-mapping](kontoplan-mapping/SKILL.md) | Map transaktioner til dansk standardkontoplan (SUM/DG/SL/e-conomic) |
| [dansk-csv-import](dansk-csv-import/SKILL.md) | Importér danske bank-CSV'er (Nordea, Danske Bank, Jyske, Sydbank) |
| [coop-bankimport](coop-bankimport/SKILL.md) | Reconcilier Coop Danmark bankbetalinger mod Uniconta- eller e-conomic-fakturaer |
| [e-conomic-integration](e-conomic-integration/SKILL.md) | Integration med e-conomic cloud-bogføring (auth, konti, kassekladde, fakturaer) |
## Reference-dokumenter
- `REFERENCES/dansk_kontoplan.md` — Oversigt over SUM/DG/SL-konti (kort)
- `REFERENCES/momssatser.md` — Aktuelle danske momssatser og fritagelser
- `REFERENCES/coop_format.md` — Forventet format på Coop opgørelser (PDF/Excel)
- `REFERENCES/economic_api.md` — e-conomic REST API endpoints og auth-flow
skills/accounting/resultatopgoerelse/SKILL.md
+148
View File
@@ -0,0 +1,148 @@
---
name: resultatopgoerelse
description: >
Byg en dansk resultatopgørelse (P&L) ud fra Radix ERP-data — aktiveres ved forespørgsler om
"resultatopgørelse", "P&L", "årsregnskab", "indtjening pr. måned/kvartal/år".
version: 0.1.0
author: radix-accountant
license: MIT
metadata:
hermes:
tags: [accounting, dansk-regnskab, resultatopgoerelse, radix-erp]
related: [kontoplan-mapping, momsafregning]
---
# Resultatopgørelse (Dansk P&L)
Genererer en **dansk resultatopgørelse** med korrekt kontogruppering iht. dansk standardkontoplan, dansk talformatering (`1.234.567,89`) og dansk terminologi (Bruttofortjeneste, Driftsresultat, Årets resultat).
## Aktiveres ved
- "Vis resultatopgørelsen for Q1 2026"
- "Hvad er bruttofortjenesten for maj?"
- "Generer P&L for hele 2025"
- "Sammenlign omsætning mellem januar og februar 2026"
## Struktur (standard dansk resultatopgørelse)
```
RESULTATOPGØRELSE — [Periode]
═══════════════════════════════════════════════════
NETTOOMSÆTNING
Salg af varer/ydelser (konto 1000-1099) 1.234.567,89
Andre driftsindtægter (konto 1100-1199) 5.678,90
───────────────────────────────────────────────────
Nettoomsætning i alt 1.240.246,79
VAREFORBRUG / COGS
Varekøb (konto 1300-1399) −450.123,45
Direkte løn (konto 1400-1499) −89.012,34
Fragt/emballage (konto 1500-1599) −12.345,67
───────────────────────────────────────────────────
Vareforbrug i alt −551.481,46
═══════════════════════════════════════════════════
BRUTTOFORTJENESTE 688.765,33
Bruttomargin 55,5%
EKSTERNE OMKOSTNINGER
Salgsomkostninger (konto 1600-1699) −23.456,78
Lokaleomkostninger (konto 1700-1799) −45.678,90
Administrationsomkostninger (1800-1899) −34.567,89
───────────────────────────────────────────────────
Eksterne omkostninger i alt −103.703,57
═══════════════════════════════════════════════════
DRIFTSRESULTAT FØR AFSKRIVNINGER (EBITDA) 585.061,76
EBITDA-margin 47,2%
AFSKRIVNINGER
Afskrivninger (konto 2000-2099) −50.000,00
───────────────────────────────────────────────────
Afskrivninger i alt −50.000,00
═══════════════════════════════════════════════════
DRIFTSRESULTAT (EBIT) 535.061,76
Driftsmargin 43,2%
FINANSIELLE POSTER
Renteindtægter (konto 2100-2199) 1.234,56
Renteudgifter (konto 2200-2299) −5.678,90
Kursreguleringer (konto 2300-2399) 789,01
───────────────────────────────────────────────────
Finansielle poster i alt −3.655,33
═══════════════════════════════════════════════════
RESULTAT FØR SKAT 531.406,43
Skat (konto 2500-2599) −117.149,42
───────────────────────────────────────────────────
═══════════════════════════════════════════════════
ÅRETS RESULTAT 414.257,01
Nettoavance 33,4%
═══════════════════════════════════════════════════
```
## Workflow
1. **Spørg om periode** (måned, kvartal, år, eller brugerdefineret datointerval)
2. **Hent data fra Radix ERP** via API eller Uniconta-eksport — spørg brugeren hvilken kilde der foretrækkes
3. **Gruppér konti** efter dansk standardkontoplan-struktur (se kontoplan-mapping skill)
4. **Beregn totaler** for hver sektion (Nettoomsætning, Vareforbrug, Eksterne omkostninger, osv.)
5. **Beregn marginer**:
- Bruttomargin = Bruttofortjeneste / Nettoomsætning × 100
- EBITDA-margin = EBITDA / Nettoomsætning × 100
- Driftsmargin = EBIT / Nettoomsætning × 100
- Nettoavance = Årets resultat / Nettoomsætning × 100
6. **Formater tal** iht. faste konventioner (punktum tusindtalsseparator, komma decimal)
7. **Vis rapport** med tydelig periode, totaler og marginer
8. **Tilbyd sammenligning** med tilsvarende periode året før (hvis data findes)
## Sammenlignings-rapport (bonus)
Når brugeren beder om en sammenligning:
```
SAMMENLIGNING — [Periode A] vs [Periode B]
═══════════════════════════════════════════════════
Periode A Periode B Ændring
────────────────────────────────────────────────────────────
Nettoomsætning 1.234.567,89 1.100.000,00 +12,2%
Bruttofortjeneste 688.765,33 590.000,00 +16,7%
Bruttomargin 55,5% 53,6% +1,9 pp
Driftsresultat (EBIT) 535.061,76 420.000,00 +27,4%
Driftsmargin 43,2% 38,2% +5,0 pp
Årets resultat 414.257,01 310.000,00 +33,6%
═══════════════════════════════════════════════════
```
`pp` = procentpoint (almindelig dansk regnskabsterm).
## Almindelige fejl at undgå
- ❌ Vis "−" som `-` (bindestreg) — brug Unicode minus `−` (U+2212) for korrekt typografi
- ❌ Bland ikke `1.234,56` (dansk) med `1,234.56` (US) — brug ALTID dansk
- ❌ Medtag ikke moms i omsætningstallet — nettoomsætning er ekskl. moms
- ❌ Vis ikke "EBIT" som "Driftsresultat" og "EBITDA" som "Driftsresultat før afskrivninger" som om de er det samme — de er forskellige
- ✅ ALTID vis "Dette er ikke bogføringsrådgivning" i årsregnskaber
## Eksempel på aktivering
**Bruger:** "Vis mig resultatopgørelsen for 2025"
**Svar (forkortet):**
> Henter transaktioner for perioden 01-01-2025 til 31-12-2025 fra Radix ERP...
>
> ```
> RESULTATOPGØRELSE — 01-01-2025 til 31-12-2025
> ═══════════════════════════════════════════════
> Nettoomsætning i alt 12.345.678,90
> ...
> ÅRETS RESULTAT 4.142.570,10
> Nettoavance 33,6%
> ═══════════════════════════════════════════════
> ```
>
> *Dette er ikke bogføringsrådgivning. Kontakt din revisor for årsregnskab.*
skills/data-science/erp-data-reconciliation/SKILL.md
+314
View File
@@ -0,0 +1,314 @@
---
name: erp-data-reconciliation
description: |
Analyze and reconcile financial/accounting data between two ERP systems
(e.g. SAP/Coop and Uniconta) using Excel exports. Covers file inspection,
column mapping, Danish-format normalization, match-engine design, and
iterative build workflow.
trigger: |
User asks to reconcile, match, compare, or afstemme data between two
accounting/ERP systems, typically via Excel files. Also relevant when
importing/exporting financial ledgers, kontoudtog, vendor/customer
statements, or bonus calculations across systems.
---
# ERP Data Reconciliation Skill
## Overview
Reconciling data between two ERP/accounting systems is a multi-phase task.
The typical deliverable is a webapp or script that can:
1. Import Excel files from both systems
2. Normalize dates, amounts, and text
3. Match postings between systems
4. Show unmatched, partial matches, and differences
5. Support manual approval/rejection
6. Generate reports
## Phase 1: File Analysis (CRITICAL — do not skip)
Before writing any import code, run a structured analysis of the Excel files.
### Steps
1. List all files in both source directories
2. For each file, identify:
- Sheet names
- Actual header row location (may NOT be row 1!)
- Column names and data types
- Date columns and their formats
- Amount columns and their formats
- Text columns
- Reference/invoice/document columns
- Null percentages
- Duplicate rows
- Data range (min/max dates)
### Key Pitfalls
- **Header row is NOT always row 1.** Uniconta exports often have account
info in rows 1-2, blank row 3, headers in row 4.
- **Amounts mixed formats.** Danish Excel files often have amounts as both
Excel floats AND as Danish text strings like `-2.543.803,93`.
Always normalize using a robust parser:
```python
def parse_danish_number(val):
if pd.isna(val): return float('nan')
if isinstance(val, (int, float)): return float(val)
s = str(val).strip()
if not s: return float('nan')
if '.' in s and ',' in s:
s = s.replace('.', '').replace(',', '.')
elif ',' in s: s = s.replace(',', '.')
return float(s)
```
- **Invoice/reference numbers may NOT match between systems.** This is the
#1 cause of failed reconciliation. Always check overlap BEFORE assuming
IDs can be used as join keys. Use amount overlap as a quick viability check.
### Analysis Script Template
Use or adapt `scripts/analyze_excel.py` from the Coop-Uniconta project:
- Reads all sheets in all files
- Prints column stats, null counts, sample values
- Detects Danish number formats
- Identifies empty/duplicate rows
## Phase 2: Determine Match Strategy
After analysis, document the match strategy BEFORE coding the engine.
### Decision Tree
1. **Do invoice/reference numbers overlap?**
- If yes → use `Faktura + abs(Amount) + Date` as PRIMARY signal (two-phase).
First phase: Reference==Faktura + abs(Amount) within tolerance (±5 DKK) + Date±21d.
Second phase: abs(Amount) + Date±21d for remaining rows.
- If no → use `Amount + Date + Text similarity`
2. **Are dates exact or within tolerance?**
- Same day → exact
- ±1-3 days → high confidence partial
- ±7 days → medium confidence
- ±21 days → general match tolerance
- >21 days → fuzzy/manual only
3. **Is text available on both sides?**
- Both have text → Levenshtein/rapidfuzz similarity score
- Only one side has text → amount+date only
4. **Do signs differ?**
- Same sign → same direction transaction
- Opposite sign → same transaction viewed from creditor vs debtor side.
Match on `abs(amount)` but label "MODSAT" in output.
*Example: Coop RE (payment) is negative; Uniconta Faktura is positive.*
### Tolerance Matching (V6 innovation)
Instead of exact amount match (±0.01), use a tolerance (±5 DKK):
- Catches rounding differences between systems
- Catches partial payments (one system may record 440.000, the other 430.732)
- Uses bucket-based indexing for fast lookup:
```python
AMT_TOL = 5.0
bucket = round(abs_amount / AMT_TOL) * AMT_TOL
# Search adjacent buckets: [bucket-AMT_TOL, bucket, bucket+AMT_TOL]
```
### Coop Fakturaliste + Uniconta Betalingsfordeling as the Simple Forward Workflow
When the user wants the process to be as simple as possible, prefer a forward-looking workflow based on:
1. `Payment_advice`
2. latest Uniconta Coop debtor/payment allocation export
3. the complete Coop invoice list
Model the invoice list and payment allocation as separate import sources. Use invoice number as the primary join between Coop invoices and Uniconta allocation lines, and calculate paid/open/partial status from payment/settlement lines rather than only from original invoice postings. Treat the payment allocation as an explanation layer between a bank deposit and many invoice/credit lines.
See `references/coop-invoice-payment-allocation.md` for the concrete Django model/import/status pattern, UI shape, and tests.
### Coop Payment Advice / Settlement Files as a Fourth Source
When the user provides Coop betalingsadviseringer/opgørelser for individual bank
payments, treat them as a separate reconciliation source, not just attachments.
They are often the missing bridge:
`Bank deposit → Coop payment advice total → advice invoice/credit lines → Coop ledger / Uniconta invoices`
For Coop-Uniconta style systems, the import UI should expose the full operational set, not just "Coop" and "Uniconta":
1. Uniconta Coop Debitor / payment allocation
2. Uniconta/ERP invoice list: all Coop invoices/credit notes for the year
3. Coop account statement / kontoudtog
4. Bank statement containing all Coop postings
5. Coop Payment_advice documents, uploadable continuously as they are collected
Recommended source/model names:
- `coop_settlement` or `coop_payment_advice`
- `PaymentAdvice` / `PaymentAdviceDocument` / `SettlementFile`: file name, unique id/bilag number, file type
(PDF/XLSX), document date, payment date, total amount, period, parse status, matched bank transaction, raw
text/raw JSON.
- `PaymentAdviceLine` / `SettlementLine`: invoice number, invoice date, company
code, amount, currency, line type (invoice/credit/bonus/modregning/unknown),
links to bank/Coop/Uniconta transactions, match status, explanation.
If the user does not yet have all payment advice documents, still allow upload now. Store raw PDF text or Excel row JSON with best-effort date/amount/reference/classification so later parsers can be tightened without re-requesting files.
Parser patterns observed:
- XLSX files may have header row 3 with columns `Fakturanummer`, `Fakturadato`,
`Firmakode`, `Beløb`, `Valuta` and supplier metadata in rows 1-2.
- Text PDFs often extract as repeated triples:
invoice number line, `dd.mm.yyyy firmakode` line, amount/`DKK` line.
- Some PDFs split sign into a separate `-` column/line; treat `123,45`, `-`,
`DKK` as `-123,45`.
- Some PDFs are bank statement screenshots, not payment advice. Classify and do
not parse them as settlement lines.
- Some files include manual middle calculations or special layouts. Keep raw text
and mark parse confidence/status instead of silently forcing a schema.
Matching/reporting logic:
1. Match payment-advice total to bank deposit using ±5 DKK tolerance.
2. Then match advice lines to Uniconta by invoice number first, then amount/date.
3. Match advice lines to Coop ledger by reference/doc number; in the Coop-Uniconta
project this was a very strong signal.
4. Treat payment-advice matches as an evidence/explanation layer, not as automatic
ledger settlement. An invoice can remain open in Uniconta while Payment_advice
proves Coop included it in a settlement, credit, bonus, modregning, or manual
middle calculation.
5. Report per bank deposit/open item: bank date/amount, matched advice file,
difference, line count, Uniconta hit count, Coop hit count, credit/bonus/
modregning total, advice documents/vouchers/classifications, and status OK /
partial / needs review.
6. Keep 2026 or out-of-period advice files in the database, but exclude or label
them separately when current bank/Uniconta data only covers 2024-2025.
### Invoice Status: Net-based + Deduplication
**Critical pitfall:** The same payment may exist in BOTH systems (Coop RE and Uniconta Betaling). If you sum both, you get double the actual paid amount.
**Solution:** Calculate net payments per invoice:
```python
# Net Coop payments (NOT abs-sum!)
coop_net = sum(c['amount'] for c in coop
if c['reference'] == fnr and c['doc_type'] in ('RE','ZP'))
coop_paid = abs(coop_net) if coop_net < 0 else 0
# Net Uniconta payments
uni_net = sum(u['amount'] for u in uni
if u['faktura'] == fnr and u['konteringstype'] == 'Betaling')
uni_paid = abs(uni_net) if uni_net < 0 else 0
# Deduplicate: if both exist, use only one
if coop_paid > 0 and uni_paid > 0:
if abs(coop_paid - uni_paid) <= AMT_TOL:
betalt = coop_paid # Same payment recorded twice
else:
betalt = max(coop_paid, uni_paid) # Partial, take largest
```
**Also handle:** Positive Coop RE amounts are credit memos (modregninger) that should be SUBTRACTED from the net, not added with abs().
### Match Scoring Formula (default)
```
Score = 0
# Amount match (40%)
if abs(a-b) < AMT_TOL: Score += 40
# Date match (35%)
days = abs(d1 - d2).days
if days == 0: Score += 35
elif days <= 3: Score += 25
elif days <= 7: Score += 15
elif days <= 14: Score += 5
# Text match (25%)
if both_have_text:
similarity = fuzzy_ratio(text1, text2) # 0-100
if similarity > 80: Score += 25
elif similarity > 50: Score += 12
# Reference bonus (extra)
if reference_match: Score += 40
# Thresholds
if Score >= 85: exact_match, auto_approvable
if Score >= 60: partial_match, requires_manual
if Score >= 40: fuzzy_match, requires_manual
```
| Table | Key Fields |
|-------|-----------|
| `ImportBatch` | source (coop/uniconta), filename, imported_at, raw_row_count |
| `Posting` | batch_id, source, fiscal_year, posting_date, amount, original_text, normalized_text, reference, document_number, original_data (JSON) |
| `Match` | posting_a_id, posting_b_id, score, match_type (exact/partial/fuzzy/manual), status (proposed/approved/rejected), matched_by (auto/user), matched_at |
| `AuditLog` | user, action, match_id, old_status, new_status, comment, timestamp |
## Phase 4: Build Iteratively
Follow this order strictly:
1. Analysis scripts and documentation → `ANALYSE.md`
2. Import parser with preview → validate before commit
3. Normalization layer (dates, amounts, text)
4. Match engine (exact → partial → fuzzy)
5. Simple web UI (dashboard → import → matching table)
6. Manual approve/reject + audit log
7. Reports and exports
8. Bonus calculation (if needed)
9. Tests + README + Docker
### Revisor/Auditor Package Pattern
When the user asks for output that can be sent to an accountant/revisor, produce a deterministic evidence package rather than relying on dashboard screenshots. First verify and remove duplicate import runs after a DB backup; then export a Markdown summary plus an Excel workbook with source files, month totals, open invoice/credit residuals, unexplained bank items, ignored bank items, payment advice rows, and raw normalized postings. Use explicit status language such as `AFSTEMT_MED_ÅBNE_POSTER` when the bank layer reconciles but invoice/credit-note residuals remain.
See `references/auditor-pack-and-dedup.md` for the duplicate-import cleanup sequence, auditor workbook sheet shape, status semantics, and verification checklist.
### Idempotent SourceFile Imports
For accounting import UIs, especially Coop `Payment_advice` bulk uploads, make uploads idempotent. Add a SHA256 `content_hash` on the source-file model, compute it before creating a new row, skip identical reuploads, and update/reparse an existing same-named source file when the content changed. Wrap child-row replacement in a database transaction and test both duplicate-skip and update-replace paths so repeated user uploads do not inflate reconciliation totals.
See `references/idempotent-source-file-imports.md` for the Django model/view/parser pattern, UI counters, bulk upload setting, and regression checklist.
## Danish-specific Conventions
- Dates: use ISO format internally (`YYYY-MM-DD`), but display in Danish
(`dd-MM-yyyy`) per user preference. Parse ambiguous Danish text dates with day-first semantics (`dayfirst=True`).
- Amounts: always normalize to float/Decimal; display with 2 decimals, Danish comma.
- Fiscal year: calendar year (1/1 – 31/12) unless specified otherwise.
- For Coop workflows, model invoice year/month separately from payment year/month: Coop can have ~3 months of credit, so December invoices may be paid in March of the following fiscal year. Reports must not treat that as an error by default.
- Text: normalize by lowercasing, stripping extra spaces, removing punctuation before fuzzy comparison.
- Regulation/bonus/fee/fine classification should be explicit and reviewable. Start with keyword classification (`bonus`, `rabat`, `gebyr`, `bøde`, `regulering`, `korrektion`, `modregning`) but keep raw data and manual review because wording/layout varies.
## Django Accounting UI Display Formatting
When the reconciliation deliverable is a Django webapp, treat amount display as part of the reconciliation contract rather than a cosmetic detail. Use one shared template filter/localization utility for money columns in dashboards, match tables, invoice/payment status pages, and reports.
For Danish accounting UIs, monetary amounts should normally render with `.` thousands separators, `,` decimal separators, exactly two decimals, and a leading minus sign for negative values (for example `1.234.567,89`, `-1.234.567,89`, `0,00`). Prefer `Decimal`-based formatting over Python floats. Replace monetary `|floatformat:2` usage, but do not reformat percentages, match scores, counts, or raw imported/audit JSON unless explicitly requested.
Minimum verification for UI formatting changes:
- Add a unit/template test for the formatting helper.
- Add at least one rendered-page regression test proving formatted money appears and raw `1234567.89`-style output is absent.
- Confirm templates using the filter load its tag module, and restart the web container if needed.
See `references/django-accounting-ui-formatting.md` for the concrete Django template-filter implementation, search targets, Docker test commands, and pitfalls.
## References
- See `references/coop-uniconta-analysis.md` for the concrete discovery
patterns from the Coop ↔ Uniconta project (header row locations,
column mappings, SAP document type codes, etc.).
- See `references/coop-uniconta-match-engine.md` for the 5-phase match engine
implementation, tolerance matching, net-based invoice status, and score formulas.
- See `references/bank-reconciliation.md` for three-source reconciliation extending
Coop ↔ Uniconta with bank CSV — month-level validation, bonus reconciliation,
and many-to-one (bank payment = sum of Coop invoices) matching strategy.
- See `references/coop-payment-advice.md` for using Coop betalingsadviseringer
(PDF/XLSX settlement files) as the bridge between bank deposits and invoice
lines, including parser patterns, coverage metrics, and reporting shape.
- See `references/three-way-django-analysis-engine.md` for Django implementation
structure: separate analysis module, batch import command, three-way report
outputs, interpretation pitfalls, and minimum tests.
- See `references/coop-invoice-payment-allocation.md` for the simplified forward
workflow using Coop invoice lists + Uniconta payment allocation + Payment_advice,
including separate models, invoice paid/open status logic, employee-expense
exceptions, UI badges, and minimum tests.
- See `references/coop-uniconta-import-ui-and-payment-advice.md` for the five-source
import UI pattern, flexible PDF/Excel Payment_advice raw import, monthly dashboard
fields, 3-month Coop credit handling, and regression tests.
- See `references/auditor-pack-and-dedup.md` for revisor-ready exports, duplicate
import cleanup after DB backup, status semantics such as `AFSTEMT_MED_ÅBNE_POSTER`,
and Excel/Markdown verification.
- See `references/idempotent-source-file-imports.md` for SHA256-based idempotent
accounting source-file uploads, update-vs-skip semantics, Django transaction
boundaries, bulk upload limits, and regression tests.
- See `references/django-accounting-ui-formatting.md` for Django money-formatting
implementation details, template search targets, regression tests, and pitfalls.
skills/data-science/erp-data-reconciliation/references/auditor-pack-and-dedup.md
+66
View File
@@ -0,0 +1,66 @@
# Auditor-ready reconciliation packs and duplicate-import cleanup
Use this when a reconciliation webapp must produce material that can be sent to an accountant/revisor, not just a green dashboard.
## Revisor-grade status language
Do not collapse every successful bank reconciliation into “fully reconciled”. Use explicit statuses:
- `AFSTEMT`: all required sources loaded, relevant bank movements explained, and no open invoice/credit-note residuals.
- `AFSTEMT_MED_ÅBNE_POSTER`: bank layer is explained, but invoice/credit-note residuals remain and must be reviewed by accounting/revisor.
- `BANK_DIFFERENCER`: required sources loaded, but relevant bank postings are unexplained.
- `MANGLER_DATA`: one or more required sources are missing.
This prevents the dangerous interpretation “0 unexplained bank postings = no accounting work remains”.
## Duplicate import cleanup pattern
Historical accounting imports are often rerun. Before trusting totals, check for duplicate `SourceFile` rows by source/file name/parsed count and repeated downstream row counts.
Safe cleanup sequence:
1. Create a database backup first.
2. Identify duplicate import runs, keeping the canonical/original `SourceFile` rows.
3. Delete duplicate `SourceFile` rows through the ORM so related imported rows cascade consistently.
4. Record an audit log entry with reason and deleted source file IDs.
5. Recompute counts and reports after cleanup.
Do not modify original source files. The goal is to remove duplicate imported rows, not change evidence.
## Auditor pack contents
Generate a deterministic export package with at least:
- Markdown executive summary in Danish.
- Excel workbook with sheets:
- `Resume`: data completeness, bank coverage, open balances, status.
- `Kildefiler`: imported files, parsed/error counts, timestamps.
- `Måneder`: month-level totals across Coop, bank, invoice list, and payment allocation.
- `Åbne poster`: invoice/credit-note residuals with invoice number, date, customer/account, total, paid, residual, vouchers, explanation.
- `Uforklaret bank`: relevant bank movements that could not be explained.
- `Ignoreret bank`: bank movements outside the debtor reconciliation scope, with reason.
- `Payment advice`: uploaded settlement/advice records.
- `Rå posteringer`: normalized postings for traceability.
Use Danish number formatting in human-facing Markdown and UI (`1.234.567,89`). Excel cells may stay numeric where useful, but headings and sheet names should be accountant-readable.
## Implementation notes
- Keep the analysis/export layer read-only; it should not mutate match status.
- Convert timezone-aware datetimes to ISO strings before writing with pandas/openpyxl; Excel rejects timezone-aware datetimes.
- Include both gross open amount and net open balance. Accountants often need both:
- gross open review amount = sum of absolute residuals;
- positive residuals = potential receivables;
- negative residuals = open credits/modregninger;
- net residual = positive + negative.
- Add tests that read the generated workbook back and assert key sheets/rows exist.
- If visual browser automation is unavailable, verify dashboard output with Django’s test client/HTTP response text and keep a separate browser/UI check when the environment supports it.
## Minimum verification
- Framework check passes.
- Full reconciliation/core tests pass.
- Auditor export command runs idempotently.
- Workbook exists and contains all expected sheets.
- Summary status and open totals match the recomputed analysis function.
- Dashboard shows bank coverage and open-poster status consistently with the exported package.
skills/data-science/erp-data-reconciliation/references/bank-implementation.md
+73
View File
@@ -0,0 +1,73 @@
# Bank Reconciliation — Django Implementation Guide
Practical implementation notes for extending a two-source Coop↔Uniconta reconciliation webapp with bank CSV support.
## Model extensions
Add these fields to `Transaction` (one migration):
```python
account_number = models.CharField(max_length=50, blank=True, db_index=True)
bank_text = models.TextField(blank=True)
valuta_date = models.DateField(null=True, blank=True)
```
Also extend `SourceFile.source` choices and `Transaction.source`/`match_type` choices to include `("bank", "Bank")` and `("bank_total", "Bank-samlet")`.
## Bank CSV parser
Key implementation in `apps/import_/parsers.py`:
- **Encodings**: Try `latin-1` first, then `utf-8`. Most Danish bank exports use latin-1.
- **Delimiter**: `;` (semicolon)
- **Header mapping**: Fuzzy-match by lowercasing, stripping null bytes and quotes:
- `dato` → date column
- `valør`/`valuta` → value date column
- `tekst`/`beskrivelse` → text column
- `bel` (prefix) → amount column
- `saldo` → balance column
- `reference`/`bilagsrefer` → reference column
- **Date parse**: `DD.MM.YYYY` → split by dots → `datetime(int(parts[2]), int(parts[1]), int(parts[0])).date()`
- **Amount parse**:
1. Strip `\xa0` (nbsp), `\u202f` (narrow nbsp), `" DKK"`
2. If `.` and `,` both present → remove dots, replace comma with dot
3. If only comma → replace with dot
4. Convert to `Decimal`
- **Bulk create**: Use `Transaction.objects.bulk_create(txns_to_create)` for performance
- **Account extraction**: Regex `r"(\d{8,})"` on text field to find kundenummer/kontonummer
## Bank ↔ Coop match (many-to-one)
Group bank payments by `(account_number, year, month)` and match against the sum of unmatched Coop transactions in the same bucket.
```python
bank_txns = Transaction.objects.filter(source="bank", year=year).values(
"account_number", "year", "month"
).annotate(total=Sum("amount"), count=Count("id"))
for bt in bank_txns:
coop_sum = Transaction.objects.filter(
source="coop", year=bt["year"], month=bt["month"],
match_status="unmatched", account_number=bt["account_number"],
).aggregate(s=Sum("amount"))["s"]
if coop_sum is not None and abs(bt["total"] - coop_sum) <= TOLERANCE:
# Create MatchGroup linking bank bucket to Coop bucket
...
```
**Note**: Bank amounts are positive (indbetalinger), Coop RE/Bankoverførsel amounts are negative. Compare absolute values. Set `match_type="bank_total"`.
## Views/templates changes
- **Dashboard**: Add `bank_count`, `bank_sum` cards; add `bank_count` / `bank_sum` columns to monthly overview table
- **Upload form**: Add `<option value="bank">Bank (Kontobevaegelser .csv)</option>`
- **Reconciliation list**: Add `bank` to source filter; render bank badge with `.badge-warning`
- **Run match page**: Document match phases: Reference → ZV↔Faktura → RE/Betaling → General → Many-to-one → Bank-total
## Discovered pitfalls
1. **Migrations not detected**: If `makemigrations` reports "No changes detected", check whether a prior manual migration already captured the changes. Run `migrate --check` first.
2. **Docker file path mismatch**: When testing via `docker compose exec`, container filesystem may differ from host. Use the web UI upload form for file import testing.
3. **Bank text homogeneity**: All transactions from the same counterparty often have identical text (e.g. `"Coop 0010014808 -SE MEDD."`). Text similarity is useless for matching. Rely on `account_number` + date+amount grouping.
4. **Bank negatives are rare but critical**: Negative bank amounts (~1-2%) represent bonus/modregning/retur. Do NOT match these against positive Coop invoices. Flag separately for bonus reconciliation.
5. **Bank total may differ slightly from Coop sum**: Normal difference is ±0.1% (fees, rounding). Use tolerance matching (e.g. ±5 DKK) for bank-total matches.
skills/data-science/erp-data-reconciliation/references/bank-reconciliation.md
+222
View File
@@ -0,0 +1,222 @@
# Bank Reconciliation — Three-Source Analysis (2026-05-26)
Reference for matching bank transactions against Coop SAP exports and Uniconta
ledgers. This extends the two-source reconciliation with a third (bank) dimension
that serves as the "ground truth" for actual cash flow.
---
## Bank file format (Danske Bank CSV export)
| Kolonne | Type | Brug |
|---------|------|------|
| Dato | DD.MM.YYYY | Primær dato |
| Valør | DD.MM.YYYY | Sekundær dato |
| Tekst | string | **Identifikation** |
| (tom) | — | Padding |
| Beløb | +/- flot/DK | Primær beløb |
| Saldo | flot/DK | Sekundær — løbende saldo |
| Egen bilagsreference | string | Audit/trace |
**CSV separator**: `;` (semikolon)
**Encoding**: `latin-1` (CP1252)
**Decimal**: Danish comma, Danish point-as-thousand-separator
**Negative**: explicit minus in front
Typisk tekstmønster for Coop-indbetalinger:
- `"Coop 0010014808 -SE MEDD."`
- Samme kundenummer for ALLE transaktioner
- Stort set alle transaktioner har identisk tekst
---
## Bank transaktionskategorier
### Standard indbetalinger (~98%)
- Beløb fra ~30.000 kr til ~800.000 kr
- Sum 2024: +9.225.626 kr (129 stk)
- Sum 2025: +10.031.368 kr (118 stk)
- Udgør den "faktiske" Coop-omsætning der rammer banken
### Negative poster — bonus/modregning/retur (~1-2%)
| Dato | Beløb | Tekst | Type |
|------|-------|-------|------|
| 13.06.2024 | -18.750,00 | COOP DANMARK AS | Bonus-tilbagebetaling |
| 25.11.2024 | -31,25 | Coop 365 | Lokal retur/modregning |
| 22.04.2025 | -128,00 | DK 57014 Coop Kvickly Slagelse | Butiksretur |
| 13.05.2025 | -40,00 | DK 50960 Coop Kvickly Slagelse | Butiksretur |
**Total negative: -18.949,25 kr**
---
## THREE-SOURCE MATCHING CONCEPT
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Coop Excel │ │ Uniconta Excel │ │ Bank CSV │
│ (fakturaer) │ │ (bogføring) │ │ (indbetalinger)│
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────┐
│ MATCH LAYER 1: Post-for-post (Coop ↔ Uniconta) │
│ Reference+abs(amount)+date → 68% match rate │
├──────────────────────────────────────────────────────────────────┤
│ MATCH LAYER 2: Month-level (All 3 sources) │
│ Sum(Coop) ≈ Sum(Uniconta) ≈ Sum(Bank) per month │
├──────────────────────────────────────────────────────────────────┤
│ MATCH LAYER 3: Bonus reconciliation (separate) │
│ Sum(KG + Kreditnota) per period ≈ Bank negative per release │
│ (tolerate time lag — bank credit arrives later than postings) │
└──────────────────────────────────────────────────────────────────┘
```
---
## Bank-to-Coop / Bank-to-Uniconta matching
### Month-level validation (PRIMARY)
Compare month totals across all three sources. If Coop and Uniconta diverge,
the bank settles the dispute.
| Måned | Bank (kr) | Coop (kr) | Uniconta (kr) | Status |
|-------|-----------|-----------|---------------|--------|
| 2024-04 | 2.139.610 | TBD | TBD | To verify |
| 2024-05 | 1.632.814 | TBD | TBD | To verify |
| 2024-09 | 1.053.598 | TBD | TBD | To verify |
**Interpretation rule:**
- Bank ≈ Coop: period is captured correctly in Coop
- Bank ≈ Uniconta: period is correct in Uniconta
- Bank >> Coop: missing Coop postings (likely late/omitted)
- Bank >> Uniconta: missing Uniconta postings
- Bank << both: bonus/modregning not yet reflected in accounting
### Many-to-one: Bank single payment = sum of Coop invoices
Each bank posting (e.g. 641.168,06 kr) is a **consolidated transfer** that
aggregates many individual Coop invoices. Algorithm:
1. Take bank amount B on date D
2. Find Coop transactions in [D-30 days, D+3 days] that sum to B ± tolerance
3. This is a "subset-sum" / knapsack search:
```python
def find_combo(target, candidates, tol=5.0):
# Greedy for small candidate sets
# DP for larger sets
candidates = sorted([c for c in candidates
if abs(c.amount) <= target + tol])
# ... subset sum with tolerance
```
4. If exact match: mark all matched Coop invoices as "grouped under bank payment"
5. If near-match (±500 kr): flag for manual review — likely partial payment or fees
---
## Bonus / Rebate reconciliation
### The mismatch:why Bank negatives don't match individual KG/Kreditnota
Coop KG-posteringer: 486 stk, total -1.101.849,97 kr
Bank negative total: -18.949,25 kr (4 stk)
Uniconta Kreditnota total: -4.593.829,17 kr
Uniconta Rabat: 1 stk, -178.194,55 kr
**Observation:** Bank -18.750 kr does NOT match ANY individual Coop KG posting
(nor any Uniconta Kreditnota). The nearest Uniconta Kreditnota is -18.961 (2025-03-21).
**Interpretation:** Bank negatives are **consolidated credit notes or bonus
payments** that aggregate MANY smaller individual credit postings across a period
(quarter or year). They arrive in the bank later than the individual postings.
### Suggested bonus reconciliation strategy
1. **Period-based grouping** (not transaction-based):
- Group Coop KG by quarter/year
- Group Uniconta Kreditnota by linked Faktura-number
- Group Uniconta Rabat by year
2. **Compare aggregated totals per period** with bank negatives per period:
```
Coop KG per period = sum(KG amounts where Posting Date in period)
Uniconta credit per period = sum(Kreditnota + Rabat amounts in period)
Bank negative per period = sum(bank negative amounts with Value Date in period)
```
3. **Differences indicate:
- Timing: bank credit arrives 1-3 months after postings
- Pooling: quarterly/yearly bonus vs monthly individual credits
- Source mismatch: some credits originate from Uniconta only, some from Coop only
4. **Manual review** for amounts > 50.000 kr discrepancies per period
### Special: Uniconta "Rabat" -178.194,55 "Coop bonus 2023"
- Single large posting on 2024-01-16
- No matching bank negative from 2023 or early 2024 found
- Likely an **accrual/adjustment** recognized in 2024 for 2023 bonus, but the
actual cash flow may have been handled differently (e.g. applied as discount
on future invoices rather than direct bank transfer)
- **Flag:** accrual-type postings should NOT be matched against bank — they
are non-cash adjustments. Separate them into "bonus accrued" vs "bonus paid".
---
## Key insight: Three sources triangulate
| Question | How to answer with 3 sources |
|----------|-------------------------------|
| "Is this invoice paid?" | Uniconta Faktura + Coop RE + Bank amount all agree |
| "Did bonus arrive in cash?" | Bank negative confirms, Coop KG shows breakdown |
| "Is Uniconta missing a posting?" | Bank has it but Uniconta doesn't → missing entry |
| "Is Coop missing a posting?" | Bank has it but Coop doesn't → missing entry |
| "Is this payment split?" | Bank single amount = sum of multiple Coop invoices |
| "Is there a bonus adjustment?" | Coop KG present, Uniconta Kreditnota present, but bank negative missing → accrual |
---
## Practical notes for the webapp
### Bank import
- Import as a third source alongside Coop and Uniconta
- Store as `Transaction(source="bank", ...)` with minimal fields:
- date, amount, text, original_value_date, original_balance
- Apply the same year filter (2024-2025) to exclude stray transactions
### Bank-specific views
1. **Month-level dashboard**: Three-bar chart per month (Coop, Uniconta, Bank)
2. **Divergence report**: Months where |Coop - Bank| > tolerance
3. **Bonus reconciliation**: Separate tab for aggregated KG/Kreditnota/Rabat vs bank negatives
4. **Many-to-one explorer**: Click a bank transaction to see suggested Coop invoice combinations that sum to the bank amount
### Data model extension for bank
```python
class BankTransaction(models.Model):
date = models.DateField()
value_date = models.DateField(null=True)
amount = models.DecimalField(max_digits=18, decimal_places=2)
text = models.TextField()
balance = models.DecimalField(max_digits=18, decimal_places=2)
source_file = models.ForeignKey(SourceFile, ...)
```
Or reuse existing `Transaction` model with `source="bank"`.
---
## Performance / verification script
Use `docker exec` with the container's Python + pandas to parse bank CSVs
and cross-check against already-loaded Coop/Uniconta data.
```python
# Quick verification of month-level totals
import pandas as pd
def parse_bank_csv(path):
df = pd.read_csv(path, sep=';', encoding='latin-1',
header=0, names=['Dato','Valør','Tekst','_','Beløb','Saldo','Ref'])
df['Dato'] = pd.to_datetime(df['Dato'], format='%d.%m.%Y', errors='coerce')
df['Beløb'] = df['Beløb'].str.replace('.', '').str.replace(',', '.').astype(float)
return df
# Summarize by month and compare with Coop/month, Uniconta/month
# Run this as a Django management command or script inside the container
```
skills/data-science/erp-data-reconciliation/references/coop-invoice-payment-allocation.md
+109
View File
@@ -0,0 +1,109 @@
# Coop fakturaliste + Uniconta betalingsfordeling workflow
Session-derived pattern from the Coop-Uniconta project: simplify reconciliation by using three forward-looking sources instead of many historical exports.
## Target workflow
Use these files as the primary operational import set:
1. Coop invoice list (`Coop Fakturaer YYYY.xlsx`) — all invoices/credits issued to Coop.
2. Uniconta payment allocation / debtor ledger (`Coop Debitor YYYY.xlsx`) — invoice and settlement/payment lines.
3. Coop `Payment_advice` — later bridge source for explicit settlement detail.
This supports the user question: “Mangler Coop at betale nogle fakturaer?”
## Models / concepts
Recommended separate models, not generic postings only:
### `CoopInvoice`
- source file, fiscal year/accounting year
- date
- account number/name
- customer reference (`Deres ref`)
- order number
- invoice number
- requisition
- total, net, VAT amounts
- payment terms / sent dates if present
- raw row JSON + sheet/row reference
### `PaymentAllocationLine`
- source file, fiscal/accounting year
- date
- account
- invoice number
- voucher/document number
- posting number
- text
- debit, credit, VAT
- physical voucher/origin/account type/debtor-creditor/name
- `is_payment_line` boolean
- raw row JSON + sheet/row reference
## Payment-line detection
In Uniconta debtor/payment allocation files, not every line is a payment. They may contain both original invoice postings and later settlement lines.
Observed signals for payment/settlement lines:
- `Bilag != Faktura`
- text contains `Coop 0010014808`
- text contains `Omp. Coop`
Do not infer paid status from invoice existence alone; calculate it from settlement/payment lines linked by invoice number.
## Invoice payment status algorithm
For each `CoopInvoice.invoice_number`:
1. Find `PaymentAllocationLine` rows with same invoice number.
2. Sum payment/settlement effect from rows marked `is_payment_line`.
3. Compare against `CoopInvoice.total_amount`.
4. Emit status:
- `paid`: residual within tolerance
- `partial`: some payment but residual remains
- `open`: no settlement/payment lines found
5. Keep explanatory fields: payment vouchers, dates, amount paid, residual, source rows.
Use Danish accounting display, but ISO dates and Decimal internally.
## Bank reconciliation with allocation groups
Use the payment allocation as an explanation layer between bank deposits and invoices:
`Bank payment → allocation group/voucher → multiple invoice lines → Coop invoices`
This is especially useful when one bank deposit equals many invoices/credits. Build groups by voucher/payment text/date and compare the group total to the bank payment.
## Employee expense exception
Negative bank postings whose text indicates purchases at Coop/Kvickly may be employee expenses, not Coop customer payments. Treat them as ignored/out-of-scope only when the user confirms the business meaning. In the Coop-Uniconta project, two negative bank lines with Coop/Kvickly text were confirmed as employee outlays and excluded from relevant bank coverage.
Implementation pattern:
- keep ignored bank payments visible in reports
- do not count them as unmatched customer-payment differences
- report both total bank count and relevant bank coverage percentage
## UI/reporting shape
Add a dedicated invoice-payment view or dashboard section:
- paid invoices
- open/different invoices
- total invoices
- open residual amount
- status badges: `BETALT`, `ÅBEN`, `DIFFERENCE`, `FAKTURAER`
- filters for year, customer/account, amount, residual, status
- export of open/difference invoices to Excel/CSV
## Minimum tests
Add tests for:
1. A Coop invoice is marked paid via matching Uniconta payment allocation lines.
2. Partial/open invoices calculate residual correctly.
3. Confirmed Coop/Kvickly employee expense bank lines are ignored but still reported.
4. Relevant bank coverage is 100% when all customer-payment bank lines are explained and only confirmed out-of-scope lines remain.
## Pitfalls
- Do not hardcode confidential file paths or sample data into committed code.
- Keep raw Excel/source folders gitignored.
- Do not collapse invoice list, payment allocation, and payment advice into one generic parser; their semantics differ.
- Payment advice parser can be added later, but wire the import type early so UI/workflow is ready.
skills/data-science/erp-data-reconciliation/references/coop-payment-advice.md
+125
View File
@@ -0,0 +1,125 @@
# Coop betalingsadviseringer / payment advice as reconciliation bridge
Use this when Coop provides per-payment settlement/advice documents (PDF/XLSX)
for bank deposits. These documents can turn previously unexplained bank deposits
into explainable groups of invoice, credit, bonus, and modregning lines.
## Durable workflow
1. Inventory files by extension and classify each file:
- `payment_advice` — Coop betalingsadvisering/payment advice with invoice lines.
- `bank_statement` — bank print/screenshot containing a Coop deposit message.
- `unknown` — manual calculation, unsupported layout, or needs OCR/manual review.
2. Extract payment advice rows:
- invoice/fakturanummer
- invoice date/fakturadato
- company code/firmakode
- amount/beløb
- currency/valuta
- raw row/text and parse confidence
3. Compute advice totals from parsed rows; do not rely solely on a trailing total
because some PDFs have manually added middle calculations or split sign columns.
4. Match advice total to bank transaction with ±5 DKK tolerance.
5. Match advice lines to Coop ledger by reference/doc number and to Uniconta by
invoice number. Fall back to amount/date only for remaining lines.
6. Produce a bank-deposit-level report for accounting review.
## PDF/XLSX parser patterns
XLSX pattern:
- Supplier metadata may be rows 1-2.
- Header row often contains: `Fakturanummer`, `Fakturadato`, `Firmakode`, `Beløb`,
`Valuta`.
- Dates can already be Excel datetimes.
Text PDF pattern A:
```text
Payment Advice
Fakturanummer
Fakturadato
Firmakode Beløb
Valuta
5119751312
17.11.2023 2245
-1556,98 DKK
...
```
Text PDF pattern B with split sign:
```text
5126294822
24.10.2024 1000
2.119,86
-
DKK
```
Treat the amount as negative when a standalone `-` follows the amount.
Bank-statement PDFs:
- May include `Kontobevægelser`, `Coop Danmark A/S -SE MEDD.`, and a bank amount.
- Do not parse these as settlement invoice lines; classify separately and optionally
link to the bank transaction/message.
## Reporting shape
Per bank deposit show:
- bank date
- bank amount
- matched payment advice file(s)
- total according to advice
- difference
- number of advice lines
- number of lines found in Coop ledger
- number of invoice numbers found in Uniconta
- credit/negative line total
- status: `OK`, `partial`, `needs_review`, `out_of_period`
## Interpretation pitfalls
- Advice files may include invoice dates from prior years but payment dates in the
current year. Derive both invoice year and payment/bank year.
- A low overlap with existing “likely Coop owes” flags does not mean the advice
files are useless; it means the analysis must model settlement files as their
own source rather than using them as loose attachments.
- 2026 advice files should be imported but labelled out-of-period when bank or
Uniconta data for 2026 is incomplete.
- Keep original PDFs/XLSX confidential and out of git; only commit parser code,
schemas, docs, and non-sensitive aggregate findings.
## Coop-Uniconta session observations
A mixed folder of 125 files contained 116 PDFs and 9 XLSX files. A first pass found
122 payment advice files, 2 bank-statement PDFs, and 1 unknown/special PDF. Parsed
advice lines were strong as a bridge: most lines matched Coop references/doc
numbers, many matched Uniconta invoice numbers, and many previously unexplained
bank deposits could be explained by matching advice totals to bank amounts within
±5 DKK.
Later production import of the same class of files used PyMuPDF (`fitz`) for PDFs
and pandas/openpyxl-style Excel parsing, creating one source-file record per
Payment_advice file and line-level records with raw JSON/text. A folder with 125
files (116 PDF, 9 Excel) produced 2,727 Payment_advice lines without mutating
original files. For a 2025 auditor pack, 1,253 lines were relevant and 78 of 296
open invoice/credit-note residuals had a Payment_advice trail.
Important interpretation: a Payment_advice line must not automatically close or
"pay" an invoice in the ledger analysis. Treat it as an evidence/explanation layer
for open items: the invoice can remain open in Uniconta while the advice proves
Coop included it in a settlement, modregning, credit, bonus, or manual middle
calculation. Reports should therefore add fields such as advice line count, advice
amount, document list, voucher/bilag list, classifications, and a human-readable
explanation rather than changing ledger status silently.
Implementation pattern that worked:
- Add `PyMuPDF>=1.24` to backend dependencies before relying on PDF import in Docker.
- Extend the batch importer to include `Entydigt*.pdf`, `Entydigt*.xlsx`, `*.xlsm`,
and `*.xls` from the payment-advice folder.
- Parse file names like `Entydigt id_4765_Bilag_7283.xlsx` into unique/document id
and voucher/bilag metadata when present.
- Classify lines as payment, credit, adjustment/manual total, or unknown, while
preserving raw row/text for manual review.
- Add regression tests that cover the case "open invoice has Payment_advice trail
but no Uniconta payment line"; expected output is explanatory evidence, not an
auto-paid status.
- Regenerate Markdown + Excel auditor packs after import and include Payment_advice
coverage counts in the summary.
skills/data-science/erp-data-reconciliation/references/coop-uniconta-analysis.md
+235
View File
@@ -0,0 +1,235 @@
# Coop ↔ Uniconta Reconciliation Reference (Aktualiseret 2025-05-26)
Konkrete felter, mappings og pitfalls fra det aktuelle Coop-Uniconta projekt.
---
## Coop (SAP export) — Kontoudtog.xlsx
| Kolonne | Navn | Type | Match-brug |
|---------|------|------|------------|
| Entry Date | Entry Date | datetime | Sekundær |
| Document Type | Document Type | **string** | **Filter + match-type** |
| Document Date | Document Date | datetime | Sekundær |
| **Posting Date** | Posting Date | **datetime** | **Primær dato** |
| **Reference** | Reference | **string (75% non-null)** | **Primær match-nøgle** |
| Net Due Date | Net Due Date | datetime | Forfaldsdato |
| **Amount** | Amount in Local Currency | **float** | **Primær beløb** |
| Document Currency | Local Currency | string ('DKK') | Filter |
| **Document Number** | Document Number | int | **Audit/trace** |
| Text | Text | string (20% non-null) | Sekundær match |
| Payment Reference | Payment Reference | string (12% non-null) | OCR/trace |
| User Name | User Name | string | Audit |
### Coop Document Types (2024-2025)
| Type | Andel | Beskrivelse | Uniconta-modpart |
|------|-------|-------------|----------------|
| RE | ~50% | Regning/betaling | Betaling/Faktura |
| ZV | ~15% | Udbetalingsforslag/faktura | Betaling |
| RG | ~6% | Kontoafstemning | Kreditnota |
| KG | ~5% | Kontoafstemning gruppe (bonus/rabat) | Kreditnota |
| ZC | ~3% | Kreditering | Kreditnota |
| ZP | ~0.4% | Betaling | Betaling |
| XX | ~0% (filtreret fra) | Manuelt bogført/migrering | — |
**VIGTIGT:** ZV-poster er positive fakturaer udstedt til kunder. De har typisk **ingen Reference/Faktura-nummer** og matches via `abs(beløb) + dato` mod Uniconta Betalinger.
---
## Uniconta — Coop danmark.xlsx
### Fil-struktur
- Række 1: Konto-info (Checked, Konto, Kontonavn, Adresse, Bynavn)
- Række 2-3: Tomme
- Række 4: Kolonne-headers: Dato, Faktura, Forfaldsdato, Bilag, Tekst, Beløb, Resterende, Forfalden, Konteringstype, Sum
- Række 5+: Data
| Kolonne | Navn | Type | Match-brug |
|---------|------|------|------------|
| **Dato** | Dato | **datetime** | **Primær dato** |
| **Faktura** | Faktura | **mixed int/str, 0=ingen** | **Primær match-nøgle** |
| Forfaldsdato | Forfaldsdato | datetime | Sekundær |
| Bilag | Bilag | mixed int/str | Audit |
| **Tekst** | Tekst | **string** | **Tekst-match** |
| **Beløb** | Beløb | **float/tekst** | **Primær beløb** |
| Resterende | Resterende | float | Filter |
| Forfalden | Forfalden | float | Filter |
| **Konteringstype** | Konteringstype | **string** | **Filter + match-bonus** |
| Sum | Sum | float | IGNORE — løbende saldo |
### Uniconta Konteringstyper
| Type | Beskrivelse | Match-modpart (Coop) |
|------|-------------|---------------------|
| Faktura | Faktura udstedt | RE (betaling) eller ZV |
| Betaling | Betaling modtaget | RE, ZP, ZV |
| Kreditnota | Kreditnota | RG, ZC, KG |
| Primo | Primo-saldo | XX (filtreres fra) |
| Afslutning | Årsafslutning | — |
| Overførsel | Overførselsbilag | — |
| Manuel | Manuel posting | — |
| Rabat | Rabat | KG |
---
## Match-nøgle-observationer
### Fakturanumre overlapper IDENTISK
- Coop `Reference` og Uniconta `Faktura` bruger **identiske 4-5 cifrede tal**.
- Eksempler: 46344, 44907, 48456, 49495, 51519
- **2.970 unikke RE-references findes som Faktura-numre i Uniconta.**
- Dette er den stærkeste match-signal — langt stærkere end beløb+dato alene.
### Modsat fortegn er NORMALT
| Coop type | Coop fortegn | Uniconta type | Uniconta fortegn | Match |
|-----------|-------------|---------------|-----------------|-------|
| RE (betaling) | Negativ (-) | Faktura | Positiv (+) | abs(beløb) |
| ZV (faktura) | Positiv (+) | Betaling | Negativ (-) | abs(beløb) |
| RG (kreditnota) | Positiv (+) | Kreditnota | Negativ (-) | abs(beløb) |
| KG (rabat) | Positiv (+) | Kreditnota | Negativ (-) | abs(beløb) |
**Implikation:** Match-motoren SKAL sammenligne `abs(beløb)`, ikke rå beløb.
### Dato-tolerance
- Faktura-reference matches: ±21 dage fungerer fint
- Generelle beløb+dato matches: ±21 dage fanger de fleste
- ZV↔Betaling matches: ±30 dage anbefales (betalingsforslag vs. faktura)
---
## Normalisering
### Beløb (dansk format)
Nogle Uniconta-celler indeholder tekststrenge som `-2.543.803,93`:
```python
def parse_danish_number(val):
if pd.isna(val) or val is None: return None
if isinstance(val, (int, float)): return float(val)
s = str(val).strip().replace('\xa0','').replace('\u202f','').replace(' DKK','')
if s.lower() in ('nan',''): return None
if s.endswith('.0'): s = s[:-2]
if '.' in s and ',' in s:
s = s.replace('.','').replace(',','.')
elif ',' in s:
s = s.replace(',','.')
try: return float(s)
except: return None
```
### Tekst
```python
def normalize_text(t):
if not t or pd.isna(t): return ''
return re.sub(r'\s+',' ',str(t).lower().strip()).strip()
```
---
## Konto-specifikt mønster
### "Coop 0010014808"
- Uniconta indeholder mange poster med teksten "Coop 0010014808"
- Beløb varierer fra -1.155.458,24 til -65.000
- Nogle har fakturanummer, andre har ikke
- Dette ligner en **samlet konto-kontering** for Coop-omsætning, ikke enkeltfakturaer
- Disse poster er svære at matche automatisk og bør behandles særskilt
### Bonus/rabat-poster
- Coop KG: "CCM Purchasing Rebate Credit"
- Uniconta Rabat: sjælden, men findes
- Disse bør matches separat via beløb + dato + bonus-tekst
---
## Specifikke problemer opdaget (V6.1)
1. **Faktura 46344** — Uniconta Faktura +441.720, Coop RE -441.720, men også Uniconta Betaling -430.732,50. Delvis kreditnota.
2. **Faktura 51519** — Uniconta Faktura +244.926, Coop RE -244.926, Uniconta Betaling -244.926. Dobbeltregistrering (Coop+Uni betaling).
3. **Faktura 48323** — Ingen Coop-betaling, men Uniconta Betaling -240.000 findes. Faktura er BETALT via Uniconta-betaling.
4. **Faktura 47140/47347 (DELVIST BETALT)** — Coop har både negativ og positiv RE med samme reference. Netto-sum giver korrekt status.
5. **Dobbelt-registrering** — Samme betaling findes som både Coop RE og Uniconta Betaling. Ved summing af begge får man 2x betalt. Løsning: brug netto-sum og dedupliker.
6. **MR8M-modregninger** — Positive Coop RE med "MR8M Credit memo" tekst er modregninger. De skal trækkes fra i netto-beregning, ikke lægges til med `abs()`.
---
## Afstemningsstrategi der virkede (V6.1 anbefalet)
**Fase 1: Reference-match (RE↔Faktura, RG↔Kreditnota)**
- Krav: Coop.Reference == Uniconta.Faktura
- Krav: abs(Coop.Amount) ≈ abs(Uniconta.Amount) ±5 kr (tolerance)
- Krav: Dato ±21 dage
- Bonus: Korrekt konteringstype
- Score ~250
- Resultat 2024-2025: ~2.421 matches
**Fase 2: ZV↔Faktura**
- Coop ZV (positive fakturaer) matcher Uniconta Faktura
- abs(beløb) ±5 kr + dato ±21 dage
- Bonus: Document Number == Faktura
- Resultat 2024-2025: ~173 matches
**Fase 3: RE↔Betaling uden reference**
- Coop RE uden fakturanummer matcher Uniconta Betaling
- abs(beløb) ±5 kr + dato ±21 dage
- Bonus: tekst-lighed
- Resultat 2024-2025: ~192 matches
**Fase 4: Generel abs(beløb)+dato**
- abs(beløb) ±5 kr + dato ±21 dage
- Konteringstype-bonus, tekst-lighed, reference-bonus
- Score ≥ 40
- Resultat 2024-2025: ~1.939 matches
**Fase 5: Mange-til-én**
- Sum af 2-3 Uniconta-poster == Coop-postering ±5 kr
- Dato ±14 dage, max 25 kandidater
- Resultat 2024-2025: ~276 matches
**Total matches 2024-2025: 5.001 ud af 7.328 Coop / 6.717 Uniconta (~68%)**
**Uafstemt: ~2.327 Coop (31,8%) + ~2.211 Uniconta (32,9%)**
---
## Faktura-status: Netto-baseret + deduplikering
### Dobbelt-registrering
Samme betaling findes som både Coop RE og Uniconta Betaling.
```python
# Beregn NETTO Coop betalinger (ikke abs-sum!)
coop_net = sum(c['amount'] for c in coop
if c['reference'] == fnr and c['doc_type'] in ('RE','ZP'))
coop_paid = abs(coop_net) if coop_net < 0 else 0
# Beregn NETTO Uniconta betalinger
uni_net = sum(u['amount'] for u in uni
if u['faktura'] == fnr and u['konteringstype'] == 'Betaling')
uni_paid = abs(uni_net) if uni_net < 0 else 0
# Dedupliker
if coop_paid > 0 and uni_paid > 0:
if abs(coop_paid - uni_paid) <= AMT_TOL:
betalt = coop_paid # Samme betaling
else:
betalt = max(coop_paid, uni_paid)
elif coop_paid > 0: betalt = coop_paid
elif uni_paid > 0: betalt = uni_paid
else: betalt = 0
```
**Resultat:** 2.968 BETALT, 2 DELVIST, 186 UBETALT
---
## Bevar original rådata
Exportér ALTID:
- Original række-nummer (Excel-rækkeindeks)
- Filnavn og ark-navn
- Rå JSON med alle kolonner
Så brugeren kan spore enhver match tilbage til kildefilen.
skills/data-science/erp-data-reconciliation/references/coop-uniconta-import-ui-and-payment-advice.md
+89
View File
@@ -0,0 +1,89 @@
# Coop-Uniconta import UI + Payment_advice lessons
Use this reference when building or fixing a Coop/Uniconta reconciliation webapp import flow.
## Required import sources
The user expects five uploadable source types, not a generic two-source UI:
1. **Uniconta Coop Debitor / betalingsfordeling**
- Shows how Coop payments are allocated across invoices/credits.
- Primary bridge from payment to invoice lines.
2. **Uniconta/ERP fakturaliste — all Coop invoices for the year**
- Complete invoice/credit-note list for the relevant year.
- Primary source for "has Coop paid all invoices?".
3. **Coop kontoudtog**
- Account statement from Coop's system.
4. **Bankkontoudtog — all Coop postings**
- Bank statement filtered to Coop-related transactions.
5. **Coop Payment_advice documents**
- PDF and Excel files, uploaded continuously as they are collected.
- Needed to identify and explain regulations, fees, bonuses, fines, credits, and offsets.
If a UI only shows "Coop" and "Uniconta", treat that as a workflow bug even if the backend has more enum choices.
## Fiscal year and monthly reporting
- Fiscal year is calendar year: 1/1–31/12.
- Store/report month for every data source.
- Keep invoice month/year separate from payment month/year.
- Coop can have around 3 months of credit: December 2025 invoices may be paid in March 2026. Cross-year payment timing is expected and should be visible, not automatically flagged as an error.
## Payment_advice ingestion pattern
Implement Payment_advice as a real source early, even before final matching logic is known.
Recommended flexible model fields:
- source file
- accounting year (nullable when no date can be inferred)
- document date
- payment date
- document/bilag number
- voucher number
- invoice number
- amount
- classification: `unknown`, `payment`, `bonus`, `fee`, `fine`, `adjustment`, `credit`
- raw text
- raw JSON / raw row data
- raw sheet name / row index
## Parser approach
For Excel:
- Read all sheets.
- Store raw row JSON.
- Best-effort infer date from date-like columns (`Dato`, `Date`, `Betaling`, `Forfald`).
- Best-effort infer amount from amount-like columns (`Beløb`, `Amount`, `Total`, `Netto`, `Moms`); if multiple amounts appear, pick the largest absolute amount as a temporary headline amount.
- Extract invoice/voucher/document IDs from matching column names.
For PDF:
- Store file even if text extraction is poor.
- Try `pypdf` / `PyPDF2` text extraction if available.
- Infer date and amount from filename + extracted text.
- Mark whether text was extracted.
Do not reject Payment_advice uploads just because final parser rules are not complete. The key is preserving raw documents/data so later parser improvements can be applied.
## UI copy / workflow guidance
On the import page, list the five source types in the same order as the user's workflow. Explain that data is split into accounting years by date, and that Payment_advice can be uploaded gradually.
For monthly dashboard rows, include at least:
- Coop postings count/sum
- Uniconta postings count/sum
- Bank postings count/sum
- Invoice list count/sum
- Payment allocation count, debit, credit
- Payment_advice count/sum
- Payment_advice classifications per month
## Minimum regression tests
Add tests that verify:
1. The upload page renders all five source labels and accepts PDF for Payment_advice.
2. Payment_advice Excel import preserves raw row data and derives accounting year/month.
3. Payment_advice classification detects at least a bonus/regulation example.
4. Existing invoice/payment allocation tests still pass after adding the new source.
skills/data-science/erp-data-reconciliation/references/coop-uniconta-match-engine.md
+236
View File
@@ -0,0 +1,236 @@
# Coop ↔ Uniconta Match Engine Reference (Aktualiseret 2025-05-26)
Konkrete match-engine-mønstre fra iteration V1 → V6.1.
---
## Match-filosofi: Faser i prioriteret rækkefølge
Fakturanummer-match (Reference ↔ Faktura) er det STÆRKESTE signal.
Beløb+dato er sekundært. Sekvens:
### V6.1 (anbefalet)
**Fase 1: Reference + abs(beløb) + dato**
- Coop `Reference` == Uniconta `Faktura` (identiske 4-5 cifrede tal)
- `abs(Coop.Amount) == abs(Uniconta.Amount)` ±5 kr (tolerance for afrunding)
- Dato ±21 dage
- Konteringstype-bonus (RE↔Faktura, RG↔Kreditnota, KG↔Kreditnota)
- Score ~250
- Resultat 2024-2025: ~2.421 matches
**Fase 2: ZV↔Faktura (Coop positive fakturaer)**
- Coop `Document Type == ZV` (positive fakturaer udstedt til kunder)
- Match mod Uniconta `Konteringstype == Faktura`
- `abs(beløb)` ±5 kr + dato ±21 dage
- Bonus: `Document Number == Faktura` nummer
- Resultat 2024-2025: ~173 matches
**Fase 3: RE↔Betaling uden reference**
- Coop `Document Type == RE` (betalinger) uden fakturanummer
- Match mod Uniconta `Konteringstype == Betaling`
- `abs(beløb)` ±5 kr + dato ±21 dage
- Bonus: tekst-lighed ("coop", "0010014808")
- Resultat 2024-2025: ~192 matches
**Fase 4: Generel abs(beløb) + dato (fallback)**
- `abs(beløb)` matcher ±5 kr
- Dato ±21 dage
- Konteringstype-bonus, tekst-lighed, reference-bonus
- Score ≥ 40
- Resultat 2024-2025: ~1.939 matches
**Fase 5: Mange-til-én**
- Sum af 2-3 Uniconta-poster == Coop-postering ±5 kr
- Dato ±14 dage, max 25 kandidater
- Resultat 2024-2025: ~276 matches
**Total matches 2024-2025: 5.001 ud af 7.328 Coop / 6.717 Uniconta (~68%)**
---
## Tolerance matching (V6 innovation)
I stedet for eksakt beløbs-match med ±0,01 kr, brug ±5 kr tolerance:
```python
AMT_TOL = 5.0 # DKK tolerance
# Index-building: bucket per tolerance interval
def build_index(transactions, max_days=21):
idx = defaultdict(lambda: defaultdict(list))
for t in transactions:
for delta in range(-max_days, max_days + 1):
d = t['date'] + timedelta(days=delta)
bucket = round(t['abs_amount'] / AMT_TOL) * AMT_TOL
idx[d][bucket].append(t)
return idx
# Lookup: søg naboliggende buckets
bucket = round(c['abs_amount'] / AMT_TOL) * AMT_TOL
for b in [bucket - AMT_TOL, bucket, bucket + AMT_TOL]:
candidates.extend(idx.get(c['date'], {}).get(b, []))
```
**Fordel:** Fanger afrundingsforskelle og delvise betalinger som
ellers ville være uafstemte.
**Bivirkning:** Kan skabe flere kandidater → brug score-threshold
og konteringstype-filter til at vælge den bedste.
---
## Fortegn: MODSAT er normalt og korrekt
| Coop type | Fortegn | Uniconta type | Fortegn | Match-mode |
|-----------|---------|---------------|---------|------------|
| RE (betaling) | Negativ | Faktura | Positiv | abs(beløb) |
| ZV (faktura) | Positiv | Betaling | Negativ | abs(beløb) |
| RG (kreditnota) | Positiv | Kreditnota | Negativ | abs(beløb) |
| KG (rabat) | Positiv | Kreditnota | Negativ | abs(beløb) |
```python
# Match via abs(), men marker med fortegn-kolonne
amt_match = abs(coop_amount - uniconta_amount) <= AMT_TOL
fortegn = "SAMME" if (coop_amount > 0) == (uniconta_amount > 0) else "MODSAT"
```
---
## Filtrering før match
**Afgræns til regnskabsår** i stedet for at filtrere på Doc_Type:
- 2024+2025 fjerner 8.861 Coop og 5.684 Uniconta poster
- Primært primo/XX/saldo-poster fra 2023 og 2026
- Langt mere effektiv end Doc_Type-filtrering
| Filter | Kilde | Hvad | Konsekvens |
|--------|-------|------|------------|
| År 2024-2025 | Begge | Regnskabsår-afgrænsning | 56% færre poster |
| `Primo` | Uniconta | Startsaldo | Fjernes ved års-filter |
| `Afslutning` | Uniconta | Årsafslutning | Fjernes ved års-filter |
---
## Mange-til-én: Praktisk approach
Én Coop-postering kan svare til SUM af flere Uniconta-poster.
- **AVOID:** `itertools.combinations` over 7.328 × 6.717 rækker = O(n²) timeout
- **USE:** Index Uniconta per `(dato, abs_beløb)` og søg kombinationer indenfor ±14 dage
- **LIMIT:** Maks 3 Uniconta-poster per Coop-postering, max 25 kandidater
- **TOLERANCE:** ±5 kr (ikke ±0,01 kr)
- Resultat: ~276 matches i 2024-2025 — større effekt end V5.1
---
## Faktura-status: Netto-baseret + deduplikering
### Problemet: Dobbelt-registrering
Samme betaling kan findes som både:
- **Coop RE** (betaling) med fakturanummer i Reference
- **Uniconta Betaling** med fakturanummer i Faktura-kolonnen
Hvis man summerer begge får man **dobbelt så meget betalt** som faktisk.
### Løsning: Netto-sum per faktura
```python
# 1. Beregn NETTO Coop betalinger per faktura
# (positive RE trækker fra — det er modregninger)
coop_net = sum(c['amount'] for c in coop
if c['reference'] == fnr
and c['doc_type'] in ('RE', 'ZP'))
coop_paid = abs(coop_net) if coop_net < 0 else 0
# 2. Beregn NETTO Uniconta betalinger per faktora
uni_net = sum(u['amount'] for u in uni
if u['faktura'] == fnr
and u['konteringstype'] == 'Betaling')
uni_paid = abs(uni_net) if uni_net < 0 else 0
# 3. Dedupliker: hvis begge findes, brug kun én
if coop_paid > 0 and uni_paid > 0:
if abs(coop_paid - uni_paid) <= AMT_TOL:
betalt = coop_paid # Samme betaling, tag én
else:
betalt = max(coop_paid, uni_paid) # Delvise, tag største
```
### MR8M-modregninger
Nogle fakturaer har både negativ og positiv RE med samme reference:
- Faktura 47140: RE -8.984 + RE +8.984 (MR8M modregning) = netto 0
- Med `abs()` ville dette tælle som 17.968 betalt (FORKERT)
- Med netto-sum: `abs(-8.984 + 8.984) = 0` (KORREKT)
---
## Score-formel (V6.1 konkret)
```
# Fase 1 (Reference-match)
Score = 250 - dato_diff * 4 - abs_amount_diff * 2
# Fase 2 (ZV↔Faktura)
Score = 150 - dato_diff * 3 - abs_amount_diff * 2
if doc_number == faktura: +50
if tekst_identisk: +25
if tekst_delvis: +12
Threshold: ≥ 60
# Fase 3 (RE↔Betaling)
Score = 120 - dato_diff * 3 - abs_amount_diff * 2
if reference == faktura: +40
if "coop" in tekst: +15
Threshold: ≥ 60
# Fase 4 (Generel)
Score = 100 - dato_diff * 3 - abs_amount_diff * 0.5
if konteringstype_match: +25
if tekst_identisk: +25
if tekst_delvis: +12
if reference_match: +40
Threshold: ≥ 40
# Fase 5 (Mange-til-én)
Score = 150 (fast, kræver manuel godkendelse)
```
---
## Rapport-struktur (Excel-ark)
Rækkefølgen er vigtig — brugeren vil se opsummering først:
0. `0_Opsummering` — nøgletal, antal matches, totalbeløb, difference, faktura-status
1. `1_Faktura_Status` — alle Uniconta fakturaer med BETALT/DELVIST/UBETALT
2. `2_Matches` — alle matchede par med type, score, fortegn, beløbs-diff, dato-diff
3. `3_Alle_Coop` — alle rå Coop-rækker med match-status kolonne
4. `4_Alle_Uniconta` — alle rå Uniconta-rækker med match-status kolonne
5. `5_Kun_Coop` — uafstemte Coop-poster
6. `6_Kun_Uniconta` — uafstemte Uniconta-poster
7. `7_Maaneds_Oversigt` — månedlig opsummering pr. år
**Nøgle:** Ark 3 og 4 bevarer overblik — brugeren vil se ALLE poster.
Ark 5+6 viser kun dem der stadig mangler.
---
## Bevar original rådata
Exportér ALTID:
- Original række-nummer (Excel-rækkeindeks)
- Filnavn og ark-navn
- Rå JSON med alle kolonner
Så brugeren kan spore enhver match tilbage til kildefilen.
---
## Performance-tips
- V6.1 kører på ~10 sekunder for 7.328 Coop + 6.717 Uniconta poster
- Brug `defaultdict(lambda: defaultdict(list))` til dato→beløb→post indeks
- Uniconta parsing: `pd.read_excel(file, header=3)` for at læse fra række 4
- Python 3.9 med pandas 2.3.3 — set `PYTHONPATH` hvis user-site-packages
skills/data-science/erp-data-reconciliation/references/django-accounting-ui-formatting.md
+122
View File
@@ -0,0 +1,122 @@
# Django Accounting UI Formatting
Former skill: `django-accounting-ui-formatting`.
Use this when changing how money, balances, invoices, payments, totals, or differences are displayed in a Django accounting/reconciliation webapp.
## Core rule
Accounting amounts must be formatted deliberately and consistently. Do not rely on ad-hoc `floatformat:2` everywhere if the app has locale-specific expectations.
For Danish Radix accounting/reconciliation UIs, render amounts with:
- thousands separator: `.`
- decimal separator: `,`
- exactly 2 decimals
- minus sign before the formatted number
Example:
```text
1234567.89 -> 1.234.567,89
-1234567.89 -> -1.234.567,89
0 -> 0,00
```
## Recommended Django implementation
Create a shared template filter in a common app, e.g.:
```text
backend/apps/common/templatetags/amount_format.py
```
Example filter:
```python
from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
from django import template
register = template.Library()
@register.filter
def amount_dk(value):
if value is None or value == "":
return "0,00"
try:
amount = Decimal(str(value)).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
except (InvalidOperation, ValueError, TypeError):
return value
sign = "-" if amount < 0 else ""
amount = abs(amount)
formatted = f"{amount:,.2f}"
return sign + formatted.replace(",", "X").replace(".", ",").replace("X", ".")
```
Ensure `templatetags/__init__.py` exists.
In templates:
```django
{% load amount_format %}
{{ amount|amount_dk }} kr
```
## What to update
Search all relevant templates for amount displays, especially:
- `floatformat:2`
- table columns named Beløb, Sum, Difference, Rest, Betalt
- dashboard cards
- report tables
- invoice/payment status pages
- transaction detail pages
Replace monetary `floatformat:2` with the shared amount filter. Leave percentages, scores, counts, and raw JSON/raw imported data alone unless the user explicitly asks otherwise.
## Tests
Follow TDD for behavior changes:
1. Add a failing unit/template test for the filter:
```python
template = Template("{% load amount_format %}{{ value|amount_dk }}")
assert template.render(Context({"value": Decimal("1234567.89")})) == "1.234.567,89"
```
2. Add at least one rendered-page regression test for the main UI path, asserting:
- formatted amount is present, e.g. `1.234.567,89`
- raw unformatted amount is absent, e.g. `1234567.89`
3. Run the relevant app tests and system check in the project runtime, usually Docker Compose for Radix internal apps:
```bash
docker compose exec -T web python manage.py test apps.core --settings=config.settings.test -v 2
docker compose exec -T web python manage.py check
```
## Verification
Before finalizing:
- Confirm there are no remaining monetary `|floatformat:2` usages in the changed templates.
- Confirm templates that use `amount_dk` include `{% load amount_format %}`.
- Restart the web container if the running app needs to load a new template tag module:
```bash
docker compose restart web
```
## Pitfalls
- Do not alter raw JSON/raw import displays; those are audit data and should preserve original values.
- Do not apply money formatting to percentages or match scores.
- Avoid Python float math for money formatting; use `Decimal` to avoid binary rounding surprises.
- If the app already has a localization/formatting utility, extend that instead of adding a second competing filter.
skills/data-science/erp-data-reconciliation/references/idempotent-source-file-imports.md
+122
View File
@@ -0,0 +1,122 @@
# Idempotent SourceFile imports for accounting/reconciliation apps
Use this when users can upload the same ERP/accounting source files repeatedly, especially bulk settlement files such as Coop `Payment_advice` PDFs/XLSX.
## Problem
Financial import apps often store one `SourceFile` plus many parsed rows/documents. If a user uploads the same file again, the app must not create:
- duplicate `SourceFile` records
- duplicate parsed settlement/payment/invoice lines
- duplicated totals in reconciliation reports
If the same named file has changed, treat it as an update of that source, not as a new independent source file.
## Durable pattern
Add a content hash to the source-file model:
```python
class SourceFile(models.Model):
source = models.CharField(max_length=64)
file_name = models.CharField(max_length=255)
file = models.FileField(upload_to="imports/")
content_hash = models.CharField(max_length=64, blank=True, db_index=True)
```
Compute SHA256 from the uploaded bytes before creating a new `SourceFile`. Always rewind the file afterwards:
```python
import hashlib
def uploaded_file_sha256(uploaded_file):
h = hashlib.sha256()
for chunk in uploaded_file.chunks():
h.update(chunk)
uploaded_file.seek(0)
return h.hexdigest()
```
Decision table:
| Existing row? | Same file name? | Same hash? | Action |
|---|---:|---:|---|
| no | n/a | n/a | create new `SourceFile`, parse rows |
| yes | yes | yes | skip import; report as unchanged/skipped |
| yes | yes | no | update existing `SourceFile`, delete old parsed child rows, reparse |
| yes | no | yes | usually skip as duplicate content; optionally report duplicate content under different name |
| yes | no | no | create new source file |
For source types that represent operational settlement documents, prefer matching on `(source, file_name)` for update semantics, plus `content_hash` for duplicate detection.
## Transaction boundary
Wrap the parser/import in a transaction so child rows are not partially replaced:
```python
from django.db import transaction
@transaction.atomic
def import_payment_advice(source_file):
PaymentAdviceDocument.objects.filter(source_file=source_file).delete()
# parse and recreate child rows/documents
```
If the upload flow creates a new file and parsing fails, delete only that newly-created `SourceFile`. Do not delete/revert an existing source record unless you have an explicit rollback strategy.
## UI behaviour
Return counters that distinguish:
- imported files
- updated files
- skipped unchanged files
- failed files
Use user-facing messages like:
- `1 uændret fil sprunget over`
- `1 fil opdateret`
- `23 filer importeret`
This matters for accounting users: they need confidence that re-uploading a folder does not inflate totals.
## Bulk upload settings
Django defaults may reject large batches with `TooManyFilesSent`. For workflows where users upload many small settlement documents, make the limit explicit in settings/env, for example:
```python
DATA_UPLOAD_MAX_NUMBER_FILES = int(os.getenv("DATA_UPLOAD_MAX_NUMBER_FILES", "2000"))
```
Add the setting to `.env.example` and document that it controls maximum files per HTTP upload.
## Tests to add
Minimum regression tests:
1. Upload same file twice with identical bytes:
- `SourceFile.objects.count()` unchanged after second upload
- child document/line count unchanged
- response contains skipped/unchanged message
2. Upload same file name with changed bytes:
- same `SourceFile` primary key reused
- `content_hash` changes
- old child rows are deleted/replaced, not appended
- response contains updated message
3. Bulk upload many files if the UI supports multi-file import:
- no `TooManyFilesSent`
- all valid new files imported
- repeated files skipped
4. Parser failure path:
- failed new file does not leave orphan `SourceFile`
- failed update does not silently erase previous valid data
## Documentation checklist
Update README/import docs with:
- duplicate uploads are skipped by content hash
- same file name with changed content updates the existing source
- updates replace parsed rows for that source file
- original source files are not edited in place; imported copies live under media/storage
- bulk upload file-count limit and env var
skills/data-science/erp-data-reconciliation/references/reconciliation-webapp-architecture.md
+167
View File
@@ -0,0 +1,167 @@
# Reconciliation Webapp Architecture (Django)
Reference architecture for building a webapp on top of a reconciliation engine.
Based on Coop-Uniconta project (Radix), May 2026.
## Stack
- **Backend**: Django 4.2 + Django REST Framework
- **Database**: MariaDB 11.4
- **Cache/Queue**: Redis + Celery (for background matching)
- **Frontend**: Django Templates + vanilla JS (no React needed for internal tools)
- **Deployment**: Docker Compose (web, db, redis)
- **Auth**: Django built-in + admin, later MS Entra/OIDC
## Project Structure
```
backend/
config/
settings/base.py # Shared config
settings/local.py # Dev overrides (DEBUG=True, admin enabled)
urls.py # URL routing
wsgi.py / asgi.py # Entry points
celery.py # Celery app
apps/
core/ # Models: Transaction, MatchResult, InvoiceStatus, AuditLog, BonusRule
models.py
admin.py
matching.py # 5-phase match engine
import_/ # Excel parsers
parsers.py # Coop + Uniconta import with preview
reconciliation/ # Views: dashboard, import, matching, reports
views.py
templates/
templates/
base.html # Dark-themed layout (sidebar nav + main content)
static/
css/app.css # Dark theme: --bg-primary: #0f172a, --accent: #3b82f6
manage.py
entrypoint.sh # wait-for-db + migrate + runserver
Dockerfile # python:3.12-slim
requirements.txt
```
## Data Model
```
AccountingYear (year, start_date, end_date)
SourceFile (source, file_name, file_path, row_count, parsed_count, error_count, accounting_year)
Transaction (source_file, source, year, month, date, amount, abs_amount,
doc_type, reference, faktura, text, text_normalized,
konteringstype, bilag, doc_number,
match_status, match_type, match_score, match_group,
original_data JSON)
MatchResult (group_id, match_type, score, status,
transaction_a, transaction_b, additional_b_ids JSON,
amount_diff, date_diff_days, explanation, comment,
approved_by, approved_at)
InvoiceStatus (faktura_number, accounting_year, invoice_total, paid_total, remaining,
status, invoice_date, first_invoice_text,
coop_payment_count, uniconta_payment_count, invoice_count)
AuditLog (action, user, match_result, details JSON)
BonusRule (name, year, period_start, period_end, conditions JSON, percentage, min_amount)
BonusCalculation (rule, transaction, calculated_amount, status)
```
## Key Design Decisions
1. **Store original_data as JSON** — Always preserve raw Excel row data for traceability.
2. **Separate `amount` and `abs_amount`** — `amount` keeps original sign for net calculations; `abs_amount` for matching.
3. **MatchResult captures both sides** — Primary match (transaction_a → transaction_b) + optional additional_b_ids for many-to-one.
4. **InvoiceStatus is computed, not stored per-transaction** — Recalculated after each matching run.
5. **AuditLog for every manual action** — Match approval, rejection, bonus adjustment.
## Match Engine Integration
The match engine runs as a Celery task triggered from the web UI:
```python
# apps/core/matching.py
AMT_TOL = Decimal("5.00")
DATE_TOL_REF = 21
DATE_TOL_GEN = 21
def run_matching(accounting_year=None):
# Phase 1: Reference match (RE↔Faktura, RG↔Kreditnota)
# Phase 2: ZV↔Faktura
# Phase 3: RE↔Betaling without reference
# Phase 4: General abs(amount)+date
# Phase 5: Many-to-one (sum of 2-3 Uni = 1 Coop)
# Bulk create MatchResult, bulk update Transaction statuses
```
## UI Pages
| Page | Purpose |
|------|---------|
| Dashboard | Year selector, stat cards, invoice status summary, monthly overview |
| Import | Upload Excel, show preview, map columns if auto-detection fails |
| Reconciliation List | Filterable table of all transactions, paginated (50/page) |
| Transaction Detail | Raw data, normalized data, potential matches, match history |
| Faktura Status | All invoices with BETALT/DELVIST/UBETALT, filterable |
| Reports | By type, by month, match summary, export to Excel |
| Run Match | Trigger background matching for selected year |
## Dark Theme CSS Variables
```css
:root {
--bg-primary: #0f172a;
--bg-secondary: #1e293b;
--bg-tertiary: #334155;
--text-primary: #f8fafc;
--text-secondary: #94a3b8;
--accent: #3b82f6;
--success: #22c55e;
--warning: #f59e0b;
--danger: #ef4444;
--border: #334155;
--radius: 8px;
}
```
Inspired by Radix-ERP visual style: sidebar navigation, card-based stats,
data tables with badges, filter bars above tables.
## Docker Compose
```yaml
services:
web:
build: ./backend
command: ["web-dev"]
ports: ["8000:8000"]
depends_on:
db: {condition: service_healthy}
env_file: [.env]
db:
image: mariadb:11.4
environment:
MARIADB_DATABASE: ${DB_NAME}
MARIADB_USER: ${DB_USER}
MARIADB_PASSWORD: ${DB_PASSWORD}
MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
redis:
image: redis:7-alpine
```
## Deployment Notes
- `python manage.py migrate` runs on container startup via entrypoint.sh
- `python manage.py createsuperuser` for first admin login
- Uploads stored in MEDIA_ROOT (mounted volume in production)
- Static files collected via `collectstatic` for production (nginx)
## Next Steps for a New Reconciliation Project
1. Copy project structure from template
2. Adapt parsers for the specific Excel formats
3. Run analysis script to determine match strategy
4. Configure AMT_TOL and DATE_TOL based on data quality
5. Build import UI with column mapping fallback
6. Implement match engine phases iteratively
7. Add manual match/approve/reject with audit log
8. Add reports and bonus calculation framework
skills/data-science/erp-data-reconciliation/references/three-way-django-analysis-engine.md
+146
View File
@@ -0,0 +1,146 @@
# Three-Way Django Analysis Engine — Coop ↔ Uniconta ↔ Bank
Session-specific implementation notes for building a maintainable three-source reconciliation layer in a Django-based internal finance app.
## When to use this pattern
Use when the task has three sources with different semantic roles:
- ERP/accounting ledger, e.g. Uniconta = invoiced/booked postings
- Counterparty/customer statement, e.g. Coop kontoudtog = settlement/detail source
- Bank CSV = actual cash movement / reality check
Do **not** treat the result as a legal claim automatically. The engine should produce review flags and explainable evidence.
## Recommended architecture
Keep the analysis engine separate from import parsing and HTTP views:
```text
apps/core/parsers.py # source-specific import/normalization
apps/core/three_way.py # pure-ish analysis functions
apps/core/management/commands/*.py # import/analyze CLI commands
apps/reconciliation/views.py # dashboard/report presentation only
apps/reconciliation/templates/... # HTML tables/cards
```
Good public functions in the analysis module:
```python
analyze_three_way_year(year)
build_monthly_summary(year)
build_invoice_statuses(year)
find_unexplained_bank_payments(year)
build_bonus_adjustment_summary(year)
```
Views should call these functions and render results; avoid embedding reconciliation logic in templates or views.
## Batch import command
For folder-based source projects, add a deterministic command that imports all configured source directories:
```bash
python manage.py import_all_sources --base-dir /app/source_data
```
Expected source layout:
```text
Fra Coop/
Fra Uniconta/
Fra bank/
```
The command should:
1. Walk each known directory.
2. Infer source from directory, not filename alone.
3. Preserve original file, sheet and row identifiers.
4. Store row-level import errors.
5. Print counts per file and total imported/error counts.
6. Be safe to rerun or clearly document duplicate behavior.
## Three-way reporting outputs
A useful first report page should show:
- possible amounts the counterparty may owe (`Mulige beløb Coop skylder`)
- unexplained bank postings (`Uforklarede bankposter`)
- invoice statuses analyzed
- months with material differences
- month-level totals across all three sources
- bonus/credit/offset summary by period
For each proposed issue, include evidence:
- amount difference
- relevant date range
- invoice/reference, if present
- source counts
- which fields matched and which did not
- score/status and whether manual review is required
## Interpretation pitfall
Large totals such as “possible amount owed” are **analysis flags**, not final claims.
Reasons:
- One bank payment can cover many Coop/Uniconta postings.
- One Coop settlement can cover many invoices.
- Dates may differ between invoice date, statement date, settlement date and bank date.
- Bonus/credit notes may be non-cash accruals or period-based offsets.
- Open-post lists are status snapshots and should be treated separately from ledger/history.
The UI and README should label these as review candidates until group matching and manual approval confirm them.
## Matching strategy after basic import
Start with conservative layers:
1. Invoice/reference + absolute amount + date tolerance.
2. Remaining amount + date tolerance.
3. Month-level totals across all three sources.
4. Many-to-one and one-to-many group matching.
5. Bonus/credit period reconciliation.
6. Manual approval/rejection with audit log.
For bank matching, prioritize group matching:
```text
bank payment = sum of many Coop settlement lines = sum of many Uniconta invoices
```
Use the bank as cash-flow validation, not necessarily as a row-level join target.
## Tests to include
Minimum tests for this class of feature:
- invoice is paid when Uniconta, Coop and bank agree
- invoice is flagged when Coop/bank evidence indicates a residual amount
- bank payment without Coop/Uniconta support is flagged as unexplained
- monthly summary calculates Bank-Coop and Bank-Uniconta differences correctly
For Django, add a lightweight test settings module if the normal dev database requires services/permissions:
```text
config/settings/test.py # SQLite, fast local tests
```
Then run:
```bash
DJANGO_SETTINGS_MODULE=config.settings.test python manage.py test
```
## Documentation to update
When this pattern is implemented, update:
- README.md: installation, Docker, import flow, analysis commands, limitations
- ANALYSE.md or ANALYSE_TREVEJS.md: source findings and interpretation
- HANDOFF.md: current status and next recommended steps
- TODO.md/ROADMAP.md: group matching, manual review, bonus expansion
skills/data-science/erp-data-reconciliation/scripts/excel-analyzer.py
+211
View File
@@ -0,0 +1,211 @@
"""
Generic Excel file analyzer for ERP reconciliation projects.
Usage:
python analyze_excel.py <directory> [--output analysis.json]
This script:
1. Scans a directory for .xlsx files
2. Identifies sheets, headers, data ranges
3. Detects Danish number formats
4. Prints null counts and sample values
5. Saves structured JSON for downstream processing
To customize for a project, adjust:
- EXPECTED_COLS: columns that must exist for a row to be considered a header
- AMOUNT_COL_PATTERNS: regex patterns for amount columns
- DATE_COL_PATTERNS: regex patterns for date columns
"""
import pandas as pd
import openpyxl
import os
import json
import re
from collections import OrderedDict
# --- CUSTOMIZE PER PROJECT ---
EXPECTED_COLS = {'Dato', 'Faktura', 'Bilag', 'Tekst', 'Beløb'}
AMOUNT_COL_PATTERNS = [
r'(?i)bel[oø]b',
r'(?i)amount',
r'(?i)sum',
r'(?i)rest',
r'(?i)forfalden',
]
DATE_COL_PATTERNS = [
r'(?i)dato',
r'(?i)date',
r'(?i)posting',
r'(?i)entry',
]
REFERENCE_COL_PATTERNS = [
r'(?i)reference',
r'(?i)faktura',
r'(?i)bilag',
r'(?i)document number',
r'(?i)invoice',
]
# --- END CUSTOMIZE ---
def classify_column(col_name):
"""Guess the semantic type of a column from its name."""
cn = str(col_name)
for p in AMOUNT_COL_PATTERNS:
if re.search(p, cn):
return 'amount'
for p in DATE_COL_PATTERNS:
if re.search(p, cn):
return 'date'
for p in REFERENCE_COL_PATTERNS:
if re.search(p, cn):
return 'reference'
return 'other'
def find_header_row(filepath, sheet=0, required_cols=None):
"""Find the first row that looks like a header."""
if required_cols is None:
required_cols = EXPECTED_COLS
wb = openpyxl.load_workbook(filepath, data_only=True)
ws = wb[wb.sheetnames[sheet]]
for i, row in enumerate(ws.iter_rows(values_only=True), start=0):
vals = set(str(v) for v in row if v is not None)
if required_cols.issubset(vals):
return i
return None
def parse_danish_number(val):
"""Normalize Danish text numbers like '-2.543.803,93' to float."""
if pd.isna(val):
return float('nan')
if isinstance(val, (int, float)):
return float(val)
s = str(val).strip()
if not s:
return float('nan')
# Danish format: thousands sep = '.', decimal = ','
if '.' in s and ',' in s:
s = s.replace('.', '').replace(',', '.')
elif ',' in s:
s = s.replace(',', '.')
try:
return float(s)
except ValueError:
return float('nan')
def analyze_file(filepath):
info = {
"filepath": filepath,
"filename": os.path.basename(filepath),
"size_kb": round(os.path.getsize(filepath) / 1024, 1),
"sheets": OrderedDict(),
}
xl = pd.ExcelFile(filepath)
for sheet in xl.sheet_names:
info["sheets"][sheet] = analyze_sheet(filepath, sheet)
return info
def analyze_sheet(filepath, sheet):
# Try default header=0 first; if columns look wrong, try header detection
df = pd.read_excel(filepath, sheet_name=sheet, engine='openpyxl')
header_row = None
# Simple heuristic: if ALL columns are unnamed, try detecting header
unnamed = [c for c in df.columns if 'Unnamed' in str(c)]
if len(unnamed) > len(df.columns) * 0.5:
hr = find_header_row(filepath, sheet)
if hr is not None:
df = pd.read_excel(filepath, sheet_name=sheet, engine='openpyxl', header=hr)
header_row = hr
cols = OrderedDict()
for col in df.columns:
col_type = classify_column(str(col))
is_date = pd.api.types.is_datetime64_any_dtype(df[col])
is_num = pd.api.types.is_numeric_dtype(df[col])
null_count = int(df[col].isna().sum())
unique_count = int(df[col].nunique())
samples = []
for v in df[col].dropna().head(5):
if len(samples) >= 3:
break
try:
if is_date:
samples.append(str(pd.Timestamp(v).date()))
else:
samples.append(str(v)[:60])
except Exception:
samples.append(str(v)[:60])
# Detect danish number format
danish_flag = False
if is_num:
for v in df[col].dropna().head(10):
if isinstance(v, str) and (',' in v or ('.' in v and ',' in v.replace('.', ''))):
danish_flag = True
break
cols[str(col)] = {
"semantic_type": col_type,
"pandas_dtype": str(df[col].dtype),
"null_count": null_count,
"null_pct": round(null_count / len(df) * 100, 1),
"unique_count": unique_count,
"is_date": bool(is_date),
"is_numeric": bool(is_num),
"danish_number_format": danish_flag,
"sample_values": samples,
}
empty_rows = int((df.isna().all(axis=1)).sum())
dupes = int(df.duplicated().sum())
# Try to find date range
date_range = None
for col, meta in cols.items():
if meta["is_date"]:
non_null = df[col].dropna()
if len(non_null) > 0:
date_range = {
"min": str(non_null.min().date()),
"max": str(non_null.max().date()),
"column": col,
}
break
return {
"rows": len(df),
"columns": len(df.columns),
"detected_header_row": header_row,
"empty_rows": empty_rows,
"duplicate_rows": dupes,
"date_range": date_range,
"columns": cols,
}
def main():
import argparse
parser = argparse.ArgumentParser(description="Analyze Excel files for data reconciliation")
parser.add_argument("directory", help="Directory containing .xlsx files")
parser.add_argument("--output", default="excel_analysis.json", help="Output JSON file")
args = parser.parse_args()
results = OrderedDict()
for f in sorted(os.listdir(args.directory)):
if f.endswith('.xlsx') and not f.startswith('~'):
fp = os.path.join(args.directory, f)
key = os.path.splitext(f)[0]
results[key] = analyze_file(fp)
print(f"Analyzed: {f}")
with open(args.output, 'w', encoding='utf-8') as fh:
json.dump(results, fh, indent=2, ensure_ascii=False)
print(f"\nSaved: {args.output}")
if __name__ == "__main__":
main()
skills/devops/gitea-issue-agent/SKILL.md
+248
View File
@@ -0,0 +1,248 @@
---
name: gitea-issue-agent
description: Build a Hermes-managed autonomous issue handler for a self-hosted Gitea instance — scan issues, analyze text + screenshot attachments, post a proposal for human approval, implement, test, push a branch, and open a Gitea PR. Use when the user wants Hermes to act on Gitea issues end-to-end with a human-in-the-loop approval gate, especially with image/visual context in the issue text.
version: 0.1.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [gitea, issues, automation, hermes-plugin, pr-workflow, agent-loop, approval-gate]
related_skills: [gitea-tea-macos-setup, software-engineering-workflows]
---
# Gitea Issue Agent
End-to-end workflow for an autonomous Gitea issue handler that lives inside
Hermes. Combines:
- A **Hermes plugin** exposing Gitea REST API tools (status, scan, get, fetch
images, comment, create PR).
- A **skill** that orchestrates the human-in-the-loop loop: propose → wait
for approval → implement → test → push → open PR.
- An optional **cron job** that triggers the loop on a schedule.
## When to use
- User wants Hermes to monitor issues across one or more Gitea repos and
propose fixes autonomously.
- Issue text often includes screenshots or design mock-ups (image support
is a first-class requirement).
- A human (the user) must approve each fix before code is written.
- Push and PR creation should target a working branch the user can review
and merge manually.
Do **not** use for: GitHub (use the `gitea`-equivalent catalog MCP for that),
issues that are just questions/discussions (no code work expected), or
workflows where the user wants fully autonomous implementation with no
human gate.
## Architecture
```
┌────────────────────────────────────────┐
│ ~/.hermes/plugins/gitea-issue-agent/ │
Cron tick → │ ├ plugin.yaml │
│ ├ __init__.py (registers 7 tools) │
│ └ README.md │
└─────────────┬──────────────────────────┘
│ exposes
▼
gitea_agent_status gitea_issue_agent_scan
gitea_list_repositories gitea_get_issue
gitea_fetch_issue_images gitea_comment_issue
gitea_create_pull_request
│ consumed by
▼
┌────────────────────────────────────────┐
│ Hermes skill gitea-issue-agent-loop │
│ (orchestrates: scan → propose → wait │
│ → implement → test → push → PR) │
└─────────────┬──────────────────────────┘
│ triggers
▼
┌────────────────────────────────────────┐
│ Cron job (optional) "every 30m" │
│ "Scan Gitea issues, propose solutions │
│ for new ones, implement approved." │
└────────────────────────────────────────┘
```
The plugin does **not** implement the loop — it only exposes the API
surface. The loop lives in the skill and the cron prompt. This separation
keeps the plugin small and lets the loop evolve without code changes to
the plugin.
## Required environment variables
Add to `~/.hermes/.env` and restart the gateway:
```bash
GITEA_BASE_URL=https://git.example.dk
GITEA_TOKEN=*** service-bruger PAT, scope: read+write issues/PRs/attachments>
GITEA_APPROVER_LOGIN=<the user's Gitea login, e.g. "dennis">
GITEA_DEFAULT_BASE_BRANCH=main
# Optional: comma-separated allowlist. If empty, /user/repos is scanned.
GITEA_REPOS=owner/repo1,owner/repo2
GITEA_AGENT_REPO_LIMIT=200
GITEA_AGENT_ISSUE_LIMIT_PER_REPO=50
```
Two Gitea identities, kept separate:
- `GITEA_TOKEN` → service-bruger account (e.g. `hermes-issues`). Posts
comments and PRs as a bot.
- `tea` CLI → the **user's personal** token, e.g. `dennis`. Used for
local git push of branches the user owns.
Mixing them causes comments to look like they came from the human
personally. See `references/identity-and-safety.md`.
## Tool set (the plugin registers these)
| Tool | Purpose |
| --- | --- |
| `gitea_agent_status` | Verify config + API connectivity; reports `authenticated_user`. |
| `gitea_list_repositories` | List repos visible to the token (or `GITEA_REPOS` allowlist). |
| `gitea_issue_agent_scan` | Scan open issues, classify each as `new` / `awaiting_approval` / `approved` / `pr_ready`. Returns short summary + image count. |
| `gitea_get_issue` | Fetch one issue + comments + image links + classification status. |
| `gitea_fetch_issue_images` | Download all screenshots/attachments from the issue + comments to a local cache, so `vision_analyze` can inspect them. |
| `gitea_comment_issue` | Post a comment; optional `marker` arg (`proposal` or `pr_ready`) prepends an HTML marker the scanner uses to track state. |
| `gitea_create_pull_request` | Open a PR from an already-pushed branch. The branch must be created and pushed by the agent via `git`/`terminal` first. |
Every tool returns JSON of the shape `{"success": true, ...}` or
`{"success": false, "error": "..."}`. JSON is the only contract; the
agent's loop should branch on `success` and surface `error` verbatim.
## The workflow (the loop the skill/cron implements)
1. **Scan**: `gitea_issue_agent_scan` to find `status == "new"` issues.
2. **For each new issue**:
1. `gitea_get_issue` for full text + comments.
2. `gitea_fetch_issue_images` to download any screenshots to
`~/.hermes/cache/gitea-issue-agent/<owner>/<repo>/<index>/`.
3. `vision_analyze` on each image (loaded into context) so the
proposal is grounded in what the screenshot actually shows.
4. Draft a proposal (in Danish if the user is Danish-speaking) covering:
- summary of the bug/feature
- root-cause hypothesis
- proposed change (files, tests, branch name)
- explicit approval request
5. `gitea_comment_issue` with `marker="proposal"`. The plugin
prepends the `<!-- hermes:gitea-issue-agent v1 status=proposal -->`
marker so the next scan classifies this issue as `awaiting_approval`.
3. **Stop and wait for approval.** Do not implement. The skill exits
cleanly; the cron re-scans later and the human will have either:
- Posted an approval comment (matched by `APPROVAL_RE` against
`GITEA_APPROVER_LOGIN`), or
- Applied one of the approval labels (`hermes-approved`,
`approved-by-dennis`, `dennis-approved`).
4. **On the next scan**, issues that satisfy the approval rule are
classified as `approved`. The skill then:
1. `cd` into the local clone of the repo (clone it first via
`git clone` if not present — `tea clone` will fail on non-standard
SSH ports, see `gitea-tea-macos-setup`).
2. Create a branch `hermes/issue-<n>-<slug>`.
3. Implement, run tests, commit, push (with token in URL or via
`~/.netrc`).
4. `gitea_create_pull_request` with `head=hermes/issue-<n>-<slug>`,
`base=main`, `body` linking to the issue, `draft=true`.
5. `gitea_comment_issue` with `marker="pr_ready"` and the PR URL.
5. **Stop.** The user reviews the PR in Gitea and merges by hand.
The two state markers (`proposal`, `pr_ready`) are the only state
machine. They survive Gitea restarts, plugin reloads, and Hermes
restarts, because they live in the issue's comment history.
## Approval semantics (default)
- A comment from `GITEA_APPROVER_LOGIN` matching
`(?is)(@?hermes|agent|bot).{0,80}(godkend|approved|ok|go)` counts as
approval. Danish is first-class because the user is Danish-speaking.
- Any of these labels applied by a maintainer also counts:
`hermes-approved`, `approved-by-dennis`, `dennis-approved`.
- Approval is only counted if it is **after** the latest `proposal`
comment. Re-approving an old proposal does nothing.
- If `GITEA_APPROVER_LOGIN` is not set, free-form approval comments are
ignored — only labels count. This is the safe default until the user
has decided which login should be allowed to approve.
For a longer rationale, see `references/identity-and-safety.md`.
## Install checklist (do these in order)
1. Decide on a service-bruger name (e.g. `hermes-issues`) and create a
Gitea PAT for it with `repository` (read+write) + `issue` (write) scope.
2. Tell the user the env vars they need to set in `~/.hermes/.env` (see
above). The agent **cannot** edit `.env` itself — Hermes blocks it
at the tool layer. See `references/identity-and-safety.md` for why.
3. Drop the plugin files into `~/.hermes/plugins/gitea-issue-agent/`
(`plugin.yaml` + `__init__.py` + `README.md`).
4. Tell the user to add `- gitea-issue-agent` under `plugins.enabled`
in `~/.hermes/config.yaml`. The agent **cannot** edit `config.yaml`
either — same reason.
5. Restart the gateway: `hermes gateway restart`.
6. Verify with `hermes chat -q "Kald gitea_agent_status" -t gitea_issue_agent`
— `api_ok: true`, `authenticated_user: hermes-issues` (or whatever the
service-bruger is named).
7. Verify the local CLI path: `tea login add --name <user> --url ...`,
`tea whoami`, then `git clone` any visible repo (don't rely on
`tea clone` — see `gitea-tea-macos-setup` for the SSH-port-2224 trap).
8. Only then create the cron job, and only after the user has
approved running it unattended.
## Verification
Use the bundled script `scripts/verify-plugin-and-gitea.sh` to confirm
the plugin is loaded, the API is reachable, and at least one repo is
visible. It should print `OK` lines and exit 0.
## Pitfalls (learned)
- **Hermes blocks the agent from writing to `~/.hermes/config.yaml` and
`~/.hermes/.env`.** The right move when blocked is to give the user
the exact one-line edit and stop. Do not try `execute_code`, `patch`,
or `write_file` a different way — the guard fires on all of them.
See `references/identity-and-safety.md`.
- **`tea clone` fails opaquely when SSH is on a non-standard port
(e.g. 2224).** Use `git clone` with the HTTPS `clone_url` from the
Gitea API. Strip the token from `origin` immediately.
- **Stale `osxkeychain` credentials can sabotage `git push` even when
the token is correct.** Switch to `~/.netrc` with `chmod 600`. See
the troubleshooting reference in `gitea-tea-macos-setup`.
- **Service-bruger identity matters.** The plugin's `authenticated_user`
field should NOT be your personal login. If it is, create a separate
service-bruger or you'll get bot comments attributed to you.
- **Free-form approval comments must be gated by a known login** (or
by maintainer-applied labels) — otherwise a co-worker saying "looks
good!" could trigger an autonomous push.
- **First run: verify, don't cron.** Always run a manual scan + a
manually-approved test issue before scheduling cron. A cron job
firing off PRs in the user's name is the failure mode to avoid.
- **Image analysis is mandatory for screenshot issues.** The plugin
extracts image URLs and downloads them locally; the skill MUST call
`vision_analyze` on each before writing the proposal, otherwise the
proposal will be blind to what the screenshot shows.
- **Plugin state is in issue comments, not in plugin memory.** The
proposal/PR markers make the workflow restart-safe.
## Related skills
- `gitea-tea-macos-setup` — the local `tea` + `git` + `osxkeychain`
setup that the agent relies on. Includes the SSH-port-2224 trap and
the `getlogin(2)` gotcha.
- `software-engineering-workflows` — the plan / spike / TDD / debugging
patterns the implement-and-test phase of the loop should follow.
- `software-development/simplify-code` — useful to invoke on the
agent's own code changes before opening the PR.
## Files in this skill
- `scripts/verify-plugin-and-gitea.sh` — one-shot verification of the
full setup (plugin loaded + API reachable + repos visible + clone
works). Run it after every change to the env or plugin.
- `references/identity-and-safety.md` — service-bruger vs personal
identity split, Hermes safety-guard reality, approval-gate design
rationale.
- `templates/proposal-comment.md` — starter template for the
`gitea_comment_issue` body when posting a proposal. Copy, fill in
the issue-specific bits, send.
skills/devops/gitea-issue-agent/references/identity-and-safety.md
+101
View File
@@ -0,0 +1,101 @@
# Identity and safety in the Gitea issue agent
## Two identities, one Gitea server
The setup has two Gitea users that should remain separate:
| Identity | Token stored in | Used for | What it posts |
| --- | --- | --- | --- |
| **Service-bruger** (e.g. `hermes-issues`) | `GITEA_TOKEN` in `~/.hermes/.env` | All plugin tool calls: scan, comment, create PR | Comments and PRs attributed to the bot |
| **Personal user** (e.g. `dennis`) | `tea` login + `~/.netrc` | Local `git push` of branches the agent created | Commits and merges attributed to you |
The plugin's `gitea_agent_status` reports `authenticated_user`. If it
reports your personal login, the bot will post comments as you — fix
the `GITEA_TOKEN` before scheduling any cron job.
## Why the Hermes safety-guards exist (and why the agent can't bypass them)
Hermes has three layers of "agent cannot edit" protection, all by
design:
1. **`~/.hermes/config.yaml`** — gates plugin load, model selection,
toolsets, gateway config. An agent that could rewrite this could
give itself new tools, change providers, or open outbound network
channels. The `patch` tool explicitly refuses:
`Refusing to write to Hermes config file: ... Agent cannot modify
security-sensitive configuration.`
2. **`~/.hermes/.env`** — contains API keys, tokens, passwords. The
`write_file`, `patch`, and `execute_code` tools all refuse to
modify it.
3. **`execute_code` with file writes** — when a script is going to
write files under `~/.hermes/`, the safety guard blocks it
unconditionally: `BLOCKED: execute_code script timed out without
user response.`
**The right move when blocked:** give the user the exact one-line
edit (or `cat > file <<EOF ... EOF` block) and stop. Do not try
alternative tools, do not retry, do not work around it. The user
must run the edit themselves.
This is not a bug. It is the threat model.
## Approval-gate design rationale
The agent should never implement, push, or open a PR for an issue
that hasn't been approved. This protects against three classes of
mistake:
1. **Misread issue** — the user wanted "fix the X button", the agent
rewrote `X()` in 14 files. Approval forces a human to look at the
proposal first.
2. **Out-of-scope issue** — the user wanted to push back, not fix.
Approval makes "no" cheap (just don't reply).
3. **Bad agent day** — the LLM hallucinated, the issue got a wrong
proposal, the agent is in a weird state. Approval makes the loop
recoverable without reverting commits.
The two state markers (`proposal`, `pr_ready`) survive Hermes
restarts, plugin reloads, and Gitea restarts, because they live in
the issue's comment history. The agent never has to remember
anything to resume — it can re-scan and pick up where it left off.
## Approval matching — why it requires a known login by default
The default approval regex is permissive enough to handle Danish
("godkend", "godkender") and English ("approve", "approved", "ok",
"go") in either order with the agent mention. But without a
known-login check, **any user** with write access to the repo could
say "looks good, agent" in a comment and trigger a push. That's a
prompt-injection vector — a malicious screenshot, or a co-worker
joking, could authorize code execution.
Two safe modes:
- **Label-only mode** (the default until `GITEA_APPROVER_LOGIN` is
set): a maintainer applies one of three labels. Labels can only
be applied by users with write access, so the trust surface is
the maintainer set, not "anyone who can comment".
- **Login-gated mode** (once `GITEA_APPROVER_LOGIN` is set): a
comment from that specific user, matching the regex, AND
after the latest proposal comment. This is the strict mode.
If the user wants both, both work — labels OR login-comment. If they
want neither (auto-implement everything), they should set both
`GITEA_APPROVER_LOGIN` and approve a *meta-issue* saying "always
implement" — but that's not the default and not recommended.
## The first run is always manual
Before scheduling a cron, the user must:
1. Run a manual `gitea_issue_agent_scan` and confirm issues show up.
2. Pick a real issue and walk it through: scan → fetch images →
analyze → propose → wait → approve → implement → test → push →
PR.
3. Confirm the PR body links to the issue, the commit message is
reasonable, and `git log` shows the expected author/email.
4. **Then** schedule a cron. The cron prompt itself should be
minimal — "scan, propose for new issues, implement approved" —
with a clear hand-off to the skill for the details.
skills/devops/gitea-issue-agent/scripts/verify-plugin-and-gitea.sh
+85
View File
@@ -0,0 +1,85 @@
#!/usr/bin/env bash
# Verify the Gitea issue agent is wired up end to end.
#
# Exits 0 on success. Prints OK / FAIL lines for each step.
# Run after every env or plugin change.
#
# Does NOT need a real token in the script — reads from ~/.hermes/.env.
set -uo pipefail
ok() { echo " OK $*"; }
bad() { echo " FAIL $*"; exit 1; }
echo "=== 1. Plugin files present ==="
PLUGIN_DIR="$HOME/.hermes/plugins/gitea-issue-agent"
for f in plugin.yaml __init__.py README.md; do
[ -f "$PLUGIN_DIR/$f" ] && ok "$f" || bad "$PLUGIN_DIR/$f missing"
done
echo
echo "=== 2. Plugin listed in config.yaml ==="
grep -q "gitea-issue-agent" "$HOME/.hermes/config.yaml" \
&& ok "config.yaml references gitea-issue-agent" \
|| bad "gitea-issue-agent not in plugins.enabled — add it under plugins.enabled in ~/.hermes/config.yaml"
echo
echo "=== 3. Plugin imports without error ==="
python3 - <<'PY' && ok "import gitea-issue-agent OK" || bad "import failed"
import importlib.util, sys
spec = importlib.util.spec_from_file_location(
"gitea_issue_agent",
f"{__import__('os').path.expanduser('~')}/.hermes/plugins/gitea-issue-agent/__init__.py",
)
mod = importlib.util.module_from_spec(spec)
sys.modules["gitea_issue_agent"] = mod
spec.loader.exec_module(mod)
assert len(mod.SCHEMAS) >= 5, f"expected at least 5 tools, got {len(mod.SCHEMAS)}"
PY
echo
echo "=== 4. Env vars present ==="
set +e
. "$HOME/.hermes/.env" 2>/dev/null
set -e
[ -n "${GITEA_BASE_URL:-}" ] && ok "GITEA_BASE_URL=$GITEA_BASE_URL" || bad "GITEA_BASE_URL missing in ~/.hermes/.env"
[ -n "${GITEA_TOKEN:-}" ] && ok "GITEA_TOKEN set (${#GITEA_TOKEN} chars)" || bad "GITEA_TOKEN missing in ~/.hermes/.env"
echo
echo "=== 5. API connectivity ==="
HTTP=$(curl -4 -s -o /dev/null -m 10 -w "%{http_code}" \
-H "Authorization: token $GITEA_TOKEN" \
"$GITEA_BASE_URL/api/v1/user")
if [ "$HTTP" = "200" ]; then
USER=$(curl -4 -s -m 10 -H "Authorization: token $GITEA_TOKEN" \
"$GITEA_BASE_URL/api/v1/user" | python3 -c "import sys,json; print(json.load(sys.stdin).get('login','?'))")
ok "API reachable, authenticated as: $USER"
else
bad "API $GITEA_BASE_URL/api/v1/user returned HTTP $HTTP"
fi
echo
echo "=== 6. At least one repo visible ==="
N=$(curl -4 -s -m 10 -H "Authorization: token $GITEA_TOKEN" \
"$GITEA_BASE_URL/api/v1/user/repos?limit=100" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))")
[ "$N" -gt 0 ] && ok "$N repos visible to token" || bad "no repos visible — token scope may be too narrow"
echo
echo "=== 7. local tea login (optional but recommended) ==="
if command -v tea >/dev/null 2>&1; then
TUSER=$(tea whoami 2>/dev/null | grep -E "^[a-zA-Z0-9_-]+$" | head -1)
[ -n "$TUSER" ] && ok "tea whoami -> $TUSER" || echo " INFO tea installed but no login yet"
else
echo " INFO tea not on PATH — see gitea-tea-macos-setup"
fi
echo
echo "=== 8. ~/.netrc (optional but recommended) ==="
if [ -f "$HOME/.netrc" ] && grep -q "git.radixadm.dk\|$GITEA_BASE_URL" "$HOME/.netrc"; then
ok "~/.netrc has an entry for $GITEA_BASE_URL"
else
echo " INFO ~/.netrc missing — git push will use osxkeychain (may be stale)"
fi
echo
echo "All checks passed. The agent is ready to use."
skills/devops/gitea-issue-agent/templates/proposal-comment.md
+40
View File
@@ -0,0 +1,40 @@
<!-- hermes:gitea-issue-agent v1 status=proposal -->
## Analyse
<kort resumé af hvad issuet beder om — i dansk hvis brugeren er dansk>
## Screenshots / visuelle referencer
<bullet-liste over hvad hver screenshot viser og hvad vi har udledt af den>
## Rod-hypotese
<1-3 bullets der peger på den underliggende årsag, ikke symptomet>
## Foreslået ændring
- **Repo:** `<owner>/<repo>`
- **Branch:** `hermes/issue-<index>-<kort-slug>`
- **Filer der forventes ændret:**
- `<sti/til/fil.py>` — <hvad og hvorfor>
- `<sti/til/test_x.py>` — ny test der dækker regressionen
- **Risiko:** lav / medium / høj — <begrundelse>
## Test-plan
- `docker compose exec web python manage.py test <app>` skal køre grønt
- Manuel verify: <trin brugeren kan tjekke i UI>
- Hvis relevant: <evt. playwright/screenshot-verifikation>
## Spørgsmål til Dennis
- <evt. valg brugeren skal tage før implementering — f.eks. "skal eksisterende data migreres, eller kun nye records?">
## Godkend
Hvis du vil have mig til at implementere det her, så svar med:
> @hermes godkend
(eller sæt label `hermes-approved` på issuet)
skills/devops/kanban-workflows/SKILL.md
+56
View File
@@ -0,0 +1,56 @@
---
name: kanban-workflows
description: "Use when operating Hermes Kanban workflows: decomposing work as an orchestrator, executing as a worker, managing lanes, status, blockers, and reconciliation."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [kanban, orchestration, workers, task-management, hermes]
related_skills: [autonomous-coding-agents]
---
# Kanban Workflows Umbrella
## Overview
Kanban work has two sides: orchestrators decompose and route work without doing it themselves; workers execute a scoped card, keep status current, and return verifiable evidence. Use this umbrella for both roles.
## When to Use
- Acting as a Hermes Kanban orchestrator.
- Acting as a Hermes Kanban worker.
- Deciding whether to split, assign, block, or reconcile cards.
- Handling worker pitfalls, examples, and edge cases.
## Role Playbooks
### Orchestrator
Decompose outcomes into cards small enough for one worker, include acceptance criteria, and avoid the temptation to implement the work directly. Route work, unblock workers, and reconcile results.
### Worker
Own exactly the assigned card. Update status when starting, blocked, or done. Run the requested checks and return concise evidence: files changed, commands run, output, and remaining risks.
### Lanes and external agents
If a worker uses an external coding agent lane, keep Kanban as the source of truth and verify the lane's output before closing the card.
## Common Pitfalls
1. Orchestrators doing implementation work themselves.
2. Workers broadening scope beyond the card.
3. Closing cards from self-reports without independent verification.
4. Losing blocker state instead of surfacing it promptly.
## Package Notes
Archived source skills retain the deeper role-specific text: `kanban-orchestrator` and `kanban-worker`.
## Verification Checklist
- [ ] Card scope and acceptance criteria are explicit.
- [ ] Exactly one owner is responsible for each action.
- [ ] Status reflects reality: pending, in progress, blocked, done.
- [ ] Completion includes verifiable evidence.