metallkart-erp/CDC.md

МеталлКарт ERP — Document de continuité Session 27

Date: 22 mars 2026

---

1. RÈGLES INDISPENSABLES DE TRAVAIL

Architecture agentique

• claude.ai = ARCHITECTE + PROMPTEUR uniquement. NE JAMAIS piloter le VPS commande par commande.
• Si tenté de lancer des commandes complexes → STOP → écrire une spec → send_task.sh
• VPS Hostinger Ubuntu 24.04, IP 76.13.55.81, SSH: ssh root@76.13.55.81

Pattern d'envoi des specs (VALIDÉ, NE PAS IMPROVISER)

1. bash_tool: encoder la spec en base64
2. CLAUDE_TERMINAL (n8n workflow Y5kkG8IIFTxSSlDs):
   - Heredoc B64END pour écrire le b64 dans /tmp/sb.txt
   - node -e POST vers HOST_TERMINAL (172.17.0.1:9999) pour décoder et écrire /tmp/spec_XXX.md
3. CLAUDE_TERMINAL:
   - node -e POST vers HOST_TERMINAL: launch script qui lit /tmp/spec_XXX.md, encode b64, appelle send_task.sh
4. Vérifier les logs: via HOST_TERMINAL tail /opt/erp/logs/spec_XXX_*.log

Secrets:

• CLAUDE_TERMINAL: mk_terminal_2026
• HOST_TERMINAL: mk_host_2026

Règles absolues

• Ne jamais sleep >60s dans CLAUDE_TERMINAL (timeout)
• curl absent du container n8n → toujours node http.request()
• Ne jamais mettre du b64 en argument shell ni dans JS template literals
• /tmp dans CLAUDE_TERMINAL = container n8n, PAS le host VPS
• CLAUDE_TERMINAL a un timeout task runner n8n, POST HOST_TERMINAL pour commandes longues
• prisma migrate dev IMPOSSIBLE en non-interactif → db push
• EADDRINUSE port 3001 → fuser -k 3001/tcp
• Toujours utiliser db push (pas migrate dev) après modification schema

---

2. ÉTAT DU PROJET — Session 27

Stack

• Backend : Fastify + Prisma + PostgreSQL 16 + TypeScript, port 3001
• Frontend : Vite 8 + React 19 + Ant Design 6 + TypeScript, port 5173 (nginx 5180)
• Repo : /opt/erp/metallkart-erp/
• Services systemd : erp-backend.service, erp-frontend.service
• PG staging : 172.19.0.5, user metallkart, DB erp_staging

Modules backend complets

• auth (JWT, RBAC 15 rôles, seed 15 users)
• suppliers (CRUD, INN, pagination)
• products (CRUD, SKU, relations)
• orders (state machine XState 10 statuts, ref auto, transitions RBAC)
• revisions (workflow conditionnel, double approbation)
• photos (upload multipart, storage abstraction)
• passport (agrégation complète commande JSON)
• dashboard (summary, alertes, vue financière)
• payment-requests (XState, 4 catégories, budget checks)
• estimates (workflow 2 validateurs, versioning, import Excel)
• contract-tracking (XState relances, escalade)
• supplier-database (CRUD enrichi, tags, contacts)
• purchases (PR CRUD, génération auto smeta, consolidé)
• steel-references (52 profils, import bulk)
• tenders (6 statuts, offres, compare, award multi-fournisseur)
• purchase-orders (from-tender, TLT, QR, email, PDF)
• budget (double validation FIN+OPS, blocage PO)
• financial (suivi coûts, FinancialTracking, ExpenseCode, MonthlyBudget)
• cashflow (ДДС, RecurringPayment, BankStatement, forecast, export Excel)
• profitability (marge, hook cashflow→tracking, export)
• notifications (centralisées, NotificationHelper)
• tasks (centre de tâches unifié, escalade auto)
• audit (journal, stats, export CSV)
• admin (users CRUD, config système, health check)
• email (SMTP+IMAP, cron inbox poll)
• consultation (drafts KP, envoi email groupé)
• onec (import 1С OData, sync contractors/contracts/financial)
• smeta-revision (comparison engine, validate+apply, AdditionalCost)
• clients (CRUD, stats)
• document-files (upload, versioning, checksum)

Frontend complet

• Документооборот : 5 onglets (Оплаты, Сметы, Контракты, Поставщики, Заказчики)
• Заказы : liste + détail 5 onglets (Général, Ревизии, Фото, Паспорт, Ревизии смет)
• Закупки : 5 onglets (Потребности, Консультации, Заказы поставщикам, Бюджет, Планирование)
• Финансы : 2 onglets (Календарь ДДС, Рентабельность)
• Уведомления : 2 onglets (Уведомления, Задачи)
• Администрирование : 3 onglets (Пользователи, Журнал аудита, Настройки)
• Настройки : Category-Tag Configurator

---

3. NOUVEAU WORKFLOW ACHATS (référence)

Flux complet :

1. Smeta : créer → import Excel → versions/révisions → soumettre → valider (2 validateurs)
2. Lancement : commande LAUNCHED → PR auto-générées depuis specData
3. Consultations : matrice PR×Fournisseurs → envoi email → réponses → analyse AI
4. Tenders : compare matriciel → award ligne par ligne multi-fournisseur → PO DRAFT
5. Budget : vue consolidée → double validation Максим (FIN) + Никита (OPS)
6. PO : confirmation → email PDF+QR → expédition → réception QR scan

---

4. INFRASTRUCTURE

Composant	Détail
VPS	Hostinger Ubuntu 24.04, 76.13.55.81
PostgreSQL	16, staging 172.19.0.5
n8n	container n8n-n8n-1, SQLite
SMTP	purchase@metdesigntver.ru, beget.com:465
IMAP	purchase@metdesigntver.ru, beget.com:993
GitHub	cifemvostok-png/metallkart-erp (privé)
Пугина	PG 9.6, 85.91.121.250:5432
1С OData	scloud.ru (désactivé session 18)

---

5. HISTORIQUE DES SESSIONS

Sessions 1-7 (mars 2026)

Infrastructure, modules backend core (auth, suppliers, products, orders, payment-requests, estimates, contract-tracking, supplier-database, purchases, tenders, purchase-orders, financial, cashflow, profitability, notifications, tasks, audit, admin).

Session 8

Frontend scaffolding (Vite+React+AntDesign), Документооборот 4 tabs, Заказы pages.

Sessions 10-12

Phase 1.5 (filtres, ContractAttachment→APPENDIX, clients, archive PR), EstimatesTab enrichi, ДДС dashboard v2, bugfixes documents.

Sessions 13-16

Smeta import Excel (parser dynamique, 13 MaterialCategory), Document Files module, frontend finance+notifications+admin, Phase 1.5B/C (traductions, améliorations frontend).

Sessions 17-18

Email service SMTP+IMAP, consultation fournisseurs, QR codes PO, Planning Gantt, configurable scoring, 2-validator estimate workflow, bugfixes critiques.

Sessions 19-20

Consultation matrice PR×Fournisseurs, 1C OData import, tender cleanup+offer lines, compare modal matriciel, award lines multi-fournisseur, offer analyzer AI, tender responses multipart.

Sessions 21-22

Editable drawers, batch confirm, partial award, TLT intégration (auto-PO, exclude tenders), category-tag configurator, tender dispatch fix, visual validation tool, 18+ specs corrections/améliorations.

Sessions 23-24

TLT schema+auto-PO+frontend, data cleanup, SPEC_DETAIL_CATEGORIES, smeta revision engine (comparison+validate+apply+AdditionalCost), PR cascade cleanup, order delete/archive.

Sessions 25-26

SmetaLot prévisionnel (créé puis supprimé — lotissement déplacé au niveau PO), refonte lotissement backend/frontend, test infrastructure (E2E+Playwright), dropdown/expand fixes.

Session 27 (22/03/2026)

27A — Infrastructure Consolidation

• CLAUDE.md : 4 nouvelles sections (tests obligatoires, validation frontend, skills, workflow achats)
• dev_task.sh : --allowedTools étendu avec 5 outils MCP Playwright
• Skills nettoyées : suppression tailwindcss, redis, mcp-server-guide (15 restantes)
• Test E2E workflow : 18/18 passés (auth→client→order→estimate→submit→approve→launch→PRs(9)→tender→dashboard)
• tests/test_workflow_e2e.sh créé

27B — Purchase Orders API Routes

• Nouveaux fichiers : src/modules/purchase-orders/po-pdf.service.ts
• Routes CRUD : POST/DELETE /purchase-orders (avec auto orderCode PO-YYYYMMDD-NNN, auto totalAmount)
• Routes workflow : confirm (QR), send-email (PDF+QR attachés), mark-shipped, receive, cancel
• Route génération : POST /purchase-orders/generate-from-tender/:tenderId (groupé par supplier)
• Route PDF : GET /purchase-orders/:id/pdf (pdfkit avec header, lignes, QR, signature)
• SMTP configuré : SMTP_FROM ajouté dans .env
• Dépendances : nodemailer, pdfkit, qrcode

27C — Budget Consolidé + Double Validation

• Nouveau modèle Prisma : BudgetValidation (@@unique orderId, enum PENDING/FIN_APPROVED/TECH_APPROVED/FULLY_APPROVED/REJECTED)
• Relations ajoutées : Order.budgetValidation, User.budgetFinValidations, User.budgetTechValidations
• Nouveaux fichiers : src/modules/budget/budget.service.ts, budget.routes.ts
• 6 routes /api/v1/budget : GET order/:orderId (vue consolidée), GET dashboard (KPIs), POST validate-financial, POST validate-technical, POST reject, POST reset
• BudgetService : calculs automatiques totalEstimated (smeta), totalAwarded (TenderLineAward), totalPO (PurchaseOrder non CANCELLED), variance, bySupplier, byCategory
• Guard PO confirm : vérifie FULLY_APPROVED avant DRAFT→CONFIRMED (sauf clientOrderId null)
• Rôles : DIRECTION_FIN pour financier, DIRECTION_OPS pour technique, ADMIN pour reset

27D — Frontend PO + Budget Tabs

• PurchaseOrdersTab : modal création (supplier, lignes éditables, auto-total, DatePicker), génération depuis tender AWARDED, suppression DRAFT, PDF download, actions contextuelles par status
• BudgetTab (280 lignes) : 4 KPI cards (estimé, PO, variance colorée, validé count), tableau commandes, drawer détail (bySupplier, byCategory, validation RBAC)
• Nouveaux fichiers : frontend/src/api/budget.ts, frontend/src/pages/purchases/BudgetTab.tsx
• Modifiés : PurchaseOrdersTab.tsx, PurchasesPage.tsx, App.tsx, types/purchases.ts, api/purchaseOrders.ts
• Route /purchases/budget ajoutée

27E — MEMORY.md Mémoire Étendue

• Créé /opt/erp/metallkart-erp/MEMORY.md : contexte complet projet (équipe, infra, credentials, bots TG, pipeline, règles métier smeta, n8n gotchas, skills, Пугина, historique sessions, DNS)
• CLAUDE.md : section "Mémoire étendue" ajoutée en référence
• Solution au problème de limite 30 mémoires claude.ai

Règles métier documentées (session 27)

• Smeta 3 onglets : Техданные (fabrication), Расчет (chiffrage/budget), СПЕЦИФИКАЦИЯ (plan achats)
• Пром-Лазер = placeholder historique → toujours ТЛТ pour Лазер et Труборез
• Services = chaque fournisseur différent
• Сетка : 2 modes (achat fini "комплект сетки" OU проволока + сварка сетки sous-traitée)
• Техданные exclut services de transformation (galvanisation, traitement thermique)

État technique post-session 27

• ~200+ routes API, 1000+ tests (18 e2e + 6 Playwright), tous verts
• Modules complets : Orders, Clients, Documents, Estimates, PurchaseRequirements, Tenders, TenderOffers, PurchaseOrders, Budget, ДДС, Profitability, Notifications, Audit
• Frontend : 6+ onglets page Achats (Сметы, Консультации, Заказы поставщикам, Бюджет)
• Mémoire : claude.ai 20/30 + MEMORY.md sur VPS

Session 29 — Sync PRs on Smeta Revision (24/03/2026)

29A — Backend syncPRsOnRevision

• Hook dans POST /revision/:revId/apply (estimates.routes.ts L470+)
• SmetaRevisionService.syncPRsOnRevision(revisionId) dans smeta-revision.service.ts
• Pour chaque decision APPLY: flag le PR via impactedPRIds ou description matching → revisionAlert=true + revisionNote
• Pour chaque decision ADDITIONAL_COST (position ORDERED):
  • Si delta > 0: crée nouveau PR DRAFT (quantity = delta × order.quantity, estimatedPrice = unitPrice)
  • Si delta < 0: flag SURPLUS sur PR existant (note avec fournisseur + PO number)
• Notification ACHETEUR via NotificationHelper.notifyRole si flagged > 0
• Champs Prisma ajoutés: revisionAlert, revisionNote, revisionAckBy, revisionAckAt sur PurchaseRequirement
• Routes: POST /purchase-requirements/:id/ack-revision, POST /purchase-requirements/ack-revision-bulk

29B — Frontend tag ПОМЕНЯТЬ + ack-revision

• Types purchases.ts: revisionAlert, revisionNote, revisionAckBy, revisionAckAt
• API purchases.ts: ackRevision(id), ackRevisionBulk(orderId)
• PurchaseRequirementsTab.tsx: tag ⚠ ПОМЕНЯТЬ + Tooltip revisionNote + bouton Обработано + row highlight #f9f0ff + bulk ack button

29C — Corrections

• Fix version collision: MAX(version)+1 au lieu de currentSmeta.version+1 (estimates.routes.ts L357)
• PR DRAFT pour delta ORDERED dans syncPRsOnRevision (action ADDITIONAL_COST)
• Historique révisions: déjà implémenté en 24J (bouton Просмотр diff)

29D — UX Notifications + Tasks

• Modal notification: clic sur message → Modal avec texte complet (whiteSpace: pre-wrap)
• Filtre rôle dans les tâches: Select "Фильтр по роли" + cartes cliquables

29E — Fix quantité delta PR

• quantity = deltaQtyPerUnit × order.quantity (quantité totale)
• estimatedPrice = unitPrice (prix unitaire inchangé)
• budgetAmount = deltaQtyTotal × unitPrice
• Arrondi toFixed(4) pour quantités, toFixed(2) pour prix
• Nettoyage 4 PR orphelins

29F — Alerte surplus (diminution quantité)

• Quand delta < 0 sur position ORDERED: flag PR existant avec revisionAlert + note SURPLUS
• Note inclut: fournisseur, n° PO, surplus total, coût
• Résolu via lineAwards → purchaseOrder → supplier

---

6. BUGS CONNUS NON RÉSOLUS

Session 30 — Revision Impact Report + Budget Fix (24/03/2026)

30A — Backend Revision Impact API

• Nouveau fichier: src/modules/purchases/revision-impact.service.ts — RevisionImpactService
• Route: GET /orders/:id/revision-impact (RBAC: ADMIN, DIRECTION_FIN, DIRECTION_OPS, ACHETEUR, ADM_PRODUCTION)
• Agrège PRs impactés par révisions: types SURPLUS/RACHAT/MODIFIED, totals, ack status
• Données via sourceType='SMETA_REVISION' + revisionAlert=true

30B — Frontend Onglet "Изменения Закупок"

• Nouveau fichier: frontend/src/api/revisionImpact.ts
• Nouveau fichier: frontend/src/pages/orders/tabs/RevisionImpactTab.tsx (~200 lignes)
• 6ème onglet dans OrderDetailPage avec Badge pending count
• 3 cartes stats (SURPLUS rouge, RACHAT vert, MODIFIED jaune)
• Tableau 9 colonnes + ack individuel/bulk + row coloring + Tooltip revisionNote
• Visible uniquement pour commandes post-AWAITING_ESTIMATE

30C — Fix Budget Computation

• budget.service.ts: computeTotals() et getDashboard() — totalEstimated multiplié par order.quantity
• schema.prisma: variancePercent élargi Decimal(5,2) → Decimal(10,2)
• Résultat: order 50 totalEstimated=2 512 171₽ (×170), variancePercent=57.15% (plus d'overflow)

30D — Cancel Pending Revision + Visible History

• Backend: route DELETE /estimates/revisions/:revId — annule REV_PENDING (transaction: delete decisions, costs, revision, new smeta)
• Frontend: bouton "Отменить ревизию" avec Popconfirm dans SmetaRevisionTab
• Historique: Collapse remplacé par Card — toujours visible
• API: cancelRevision() ajoutée dans smetaRevisions.ts

État technique post-session 30

• ~205+ routes API, 1000+ tests (18 e2e + 6 Playwright), tous verts

• Nouveaux fichiers: revision-impact.service.ts, revisionImpact.ts, RevisionImpactTab.tsx

• Onglet OrderDetailPage: 6 tabs (Информация, Ревизии, Фото, Ревизия сметы, Паспорт заказа, Изменения Закупок)

• Validation toasts parfois apparaissent sur Закупки (à investiguer)

• Puppeteer screenshot multi-page auth loss (contournement: screenshot-api.js)

• 1С sync désactivé (routes 503) — données nettoyées session 18

Session 31 — PurchaseLots, Factures, Conditions paiement (24/03/2026)

TLT-C1a — Backend PurchaseLots + Factures + Conditions paiement

• POInvoice, POPaymentSchedule, POInstallment models
• createLotsForPO helper, 15+ routes, confirm guards, PaymentRequest auto-creation PAY-

TLT-C1b-1 — Frontend Drawer PO enrichi

• 3 sections: Лоты, Счёт-фактура, Условия оплаты
• 11 API functions, 6 types, RBAC actions

Session 32 — PO Workflow SENT, Onglet Счета, Steel Conversion, Cashflow PO, Доп затраты auto (25/03/2026)

32A — PO Workflow SENT + Lots Overflow Fix

• PurchaseOrderStatus +SENT, PurchaseLot.quantity Decimal(15,2), sendPOEmail→SENT transition

TLT-C1b-2 — Onglet Счета (ex-Оплаты)

• Code couleur lignes par statut, date paiement vert/rouge, bouton Файл facture, drawer enrichi

32B — Offer Analyzer Refonte + Steel References

• 51 profils acier seed, SteelConversionService т↔м, offer analyzer refonte raw+deterministic post-processing

32C — Cashflow Prévisionnel PO

• Forecast PO installments, KPI poCommitments, 5ème carte KPI frontend

32D — Calcul auto Сумма ДЗ

• Bannière orange temps réel ADDITIONAL_COST dans SmetaRevisionTab

Session 34 (07-08/04/2026)

Dev local PC validé. 22 items livrés (18 fixes + 4 features). Fixes: PDF blob, cashflow, P0 quantités PR, tender async, PR doublons, close() libère PR, updateSuppliers, Zod Predoplata/Postoplata, ADMIN bypass, tags alignés, Gantt barres, montants transhi, PR résiduelle award partiel, lots min 1, doublon priorité. Features: lien tender dans statut PR, Podtverdit vse groupe, filtre commande Tendery, arkhivirovat zakrytye. Pipeline WIN_TERMINAL testé.

Session 35 (08-09/04/2026)

15 specs livrées, workflow paiement refondu. Fixes (8): git push 403 PAT, CashflowTab off-by-one, award global supprimé→compare, revertToSent COMPARING→SENT, 4 fixes UI drawer PO, navigation tab PO depuis Счета, PR ORDERED après award, fournisseurs tender filtrés par dispatches, TLT renommé ООО "ТЛТ". Features (5): recherche textuelle tenders serveur-side, archivage PO (CANCELLED auto + RECEIVED manuel + bulk), installments liés aux paiements (purchaseOrderId, paymentRequestId, cascade markPaid), refonte workflow paiement PENDING→APPROVED→PAID avec toggle Инициировать/Отозвать, bouton "Заказ ТЛТ" sur LASER_FLAT/LASER_TUBE/PIPE_CUT. Améliorations: dates installments éditables (DatePicker inline, dueDate propagé sur PaymentRequest), purge données ERP local.

Session 36 (09-10/04/2026) — complète

SPEC-36A: Comparaison révision smeta descend dans specData (compareSpecItems, SPEC_DETAIL_CATEGORIES +LASER_TUBE/+TUBE_BENDING, endpoint recalculate). Fix lots TLT/laser: requirementId nullable, splitLots corrigé, items enrichis requirementIds. SPEC-36B: Ближайшие платежи avec vraies données (POInstallment+PaymentRequest), 7 colonnes, tags statut. Fix fournisseur: Decimal→string coercé Number(). SPEC-36C: Revert PO CONFIRMED→DRAFT (unconfirm), rejette PR, bloque si paidAt. SPEC-36D: PaymentRemindersService cron J-3/J-1/J-0/overdue, notifyRole ACHETEUR+DIRECTION_FIN, idempotent, POST /check-reminders ADMIN. SPEC-36E: Refonte lotissement PO par ligne (PurchaseLotLine model, validation 100%, deliveryDays TenderOffer). SPEC-36E-FIX: Backfill items JSON→PurchaseOrderLine (12 POs migrés), fix createFromTender/createTlt. SPEC-36F: LotSplitModal plein écran (matrice ligne×lot, InputNumber/DatePicker, auto-calcul deliveryDate, validation Tag 100%). SPEC-36G: Fix révision smeta compare v2 pas v1 (suppression filtre statut currentSmeta). SPEC-36H: Fix navigation cashflow (liens Заказ/description/ЗП, highlight blink-red 10s), filtres statut Radio.Group, tri Просроченные↑, colonne Просрочка (N дн. rouge). Fix lot split: deliveryDate sauvegardée dans payload, auto-remplissage depuis supplier.deliveryDelayDays. Backfill PurchaseOrderLine.material: 48 lignes fixées (28 via requirementId, 20 TLT→LASER_FLAT).

Session 37 (10/04/2026)

Fix budget byCategory: remplacé PR.budgetAmount (null) par PurchaseOrderLine groupées par material (quantity×finalPrice). SPEC-37A: Refonte Настройки multi-onglets (Профиль/Уведомления/Категории). Modèle UserNotificationPreference (7 catégories: PAYMENT_DUE, PR_APPROVE, PR_CONFIRM, TENDER_OFFER, SMETA_REVISION, PO_DELIVERY, LOT_ORDER_DUE). Defaults par rôle (ROLE_DEFAULT_CATEGORIES). Routes GET/PUT /notification-preferences (upsert transactionnel). NotificationHelper: shouldNotifyInApp() filtre par catégorie avant création. PaymentRemindersService: category PAYMENT_DUE ajouté. Frontend: ProfileTab (GET /auth/me), NotificationsTab (Switch inApp actif, Email/Telegram disabled futur), SettingsPage 3 onglets.

---

7. PROCHAINES ÉTAPES

• [P1] Cashflow prévisionnel (installments + PO confirmés + factures clients)
• [P1] Refonte Планирование/Gantt
• [P2] Erreurs TS backend (.test.ts)
• invoices (facturation client)
• reports (rapports financiers)
• Intégration Пугина (vues SQL lecture seule)