Aller au contenu

Logosw integration

Status: Placeholder — to be developed. Last reviewed: — Reference structural sibling: guidelines/i18n/translation-rules.md (rule + workflow style).

Scope (when this guideline lands)

Logosw export ingestion: file-based (no API), pushed via the apps/collection/ remote agent, parsed by apps/imports/ importers (CIVIL.txt → patients, ACTES_2.txt → procedures, plus others). Encoding quirks (UTF-8 / ISO-8859-1 mix), category mapping (17 stat categories, see docs/LOGOSW_CATEGORY_MAPPING.md), ImportRow audit trail, idempotency on re-import.

Out of scope (cross-refs)

  • AbstractImporter pattern (subclassing, ImportRow schema, bulk-mode rules) → guidelines/imports/abstract-importer.md (placeholder). This file owns the Logosw-specific quirks; that one owns the importer contract.
  • Remote agent upload pipeline (the apps/collection/ half — heartbeat, batching, retry) → no current guideline; likely needs guidelines/integrations/collection-agent.md once agent work re-starts (currently several agent-* items in backlog).
  • Shared connector contract → guidelines/integrations/overview.md (placeholder).
  • PII / patient data handling → guidelines/security/pii-and-logging.md (placeholder).

Sources to mine when writing this

  • apps/imports/importers/ — every importer is one source pattern. CIVIL.txt, ACTES_2.txt, plus others.
  • apps/collection/ — upload pipeline that feeds the importers (CollectionAgent, FileUpload model, heartbeat).
  • roadmap/ideas/logosw-export-questions.md — open questions about Logosw exports (encoding, missing fields).
  • docs/LOGOSW_CATEGORY_MAPPING.md — the 17-category mapping (reference, stays in docs/).
  • docs/IMPORTS_MODULE.md — existing module reference (French).
  • roadmap/done/imports-encoding-fixes.md — encoding-handling lessons learned.
  • roadmap/done/imports-bulk-performance.md — bulk-mode learnings.
  • The agent-related backlog items (agent-resilience, agent-retry-window, collection-partial-batch, etc.) — context on what's on the upload-side roadmap.

Starter hard rules to investigate

  1. Per-file encoding detection: don't assume UTF-8. Some Logosw files are ISO-8859-1 (devis.txt per existing notes); detect or pin per-file.
  2. Idempotent re-import: re-uploading the same file produces the same DB state. ImportRow tracking enables this — verify no importer bypasses it.
  3. ImportRow.status is always set — 'imported', 'skipped', 'failed'. Never silent.
  4. Category mapping consults docs/LOGOSW_CATEGORY_MAPPING.md — single source of truth for the 17 categories.
  5. Patient data never logged in clear (per guidelines/security/pii-and-logging.md).

Decision points to settle

  1. Encoding policy: force UTF-8 transcode at upload time vs detect-per-file at import time. Currently detect-per-file.
  2. Partial batch handling: what to do when a Logosw batch arrives missing some files (e.g. GL_REGL missed during Easter — see collection-partial-batch backlog).
  3. Re-import policy: a re-uploaded file with one row changed — does the importer re-process all rows or diff?
  4. Stale-data alerting: when a practice's Logosw upload hasn't arrived in N days, who gets alerted?

Known deviations to look for during writing

  • Importers that don't honour ImportRow (silent imports).
  • Hardcoded encoding (encoding='utf-8') without fallback.
  • Importers that emit logs containing patient names.
  • Category-code lookups that don't go through the canonical mapping.

If found, file as roadmap/backlog/integrations-logosw-drift-2026-MM.md.