Mortezakoohjani e41ecfad4c Sync platform docs, infra, and module services with Accounting integration.

Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-25 22:35:23 +03:30

18 KiB

Raw Blame History

Progress

Completed work only. Future → roadmap.md. Next milestone → next-steps.md.

Phase 1 — Core Platform ✅

Infrastructure & structure

Full project structure with mandatory backend/ / frontend/ separation
Shared library backend/shared-lib
Architecture section: Frontend & Backend Separation

Core service

Config, database, cache, logging, base security
Models, APIs, Entitlement, Celery, Outbox
Tests and documentation

Frontend

Independent Next.js, API client, white-label theme baseline

Phase 2 — Identity & Access + SSO ✅

shared/auth/jwt.py, shared/auth/roles.py, Identity events in shared/events.py
Identity service + identity_access_db
Keycloak realm/clients/theme import
Core API protection (AUTH_REQUIRED, role deps)
Frontend SSO flow (/login, /auth/callback, /dashboard)
Compose services Identity + Frontend; Postgres init for identity DB

Core users + OTP request/verify + Payamak
Local JWT (HS256) for OTP users
Admin tenant CRUD + owner filtering
Frontend admin OTP/tenant UI (later aligned to central SSO)
test_otp_auth.py

Phase 4 — Tenant Onboarding & Workspace Activation ✅

Brief alias: sometimes called “Phase 3” externally — see phase-numbering decision.

Core tenant_memberships, tenant lifecycle, branding columns, domain primary/verification fields
users.current_tenant_id, FREE/STARTER plan seed, onboarding APIs
UserService / MembershipService / OnboardingService / TenantContextService
Frontend onboarding wizard, tenant dashboard, tenant switcher
test_onboarding.py + regression suite
JIT Core user from Keycloak JWT (UserService.resolve_current)
Automatic tenant subdomain SSL (Celery → SSH → provision_ssl.py)
Reverse proxy (Nginx) + base TLS + tenant SSL automation

Intentionally incomplete after Phase 4 (tracked in roadmap, not claimed done)

Payment gateway · real DNS/TXT custom-domain verify · legacy POST /admin/tenants auto membership/plan · first business module

Phase D — Documentation Architecture Consolidation ✅

Target docs/ tree (architecture, adr, development, reference, deployment, templates, phases, decisions)
Moved canonical docs with git history where possible
Deprecated stubs for old paths
ADR system initialized (ADR-001 … ADR-010)
Project principles, coding standards, testing/branching/release strategies
Module registry + provider registry + glossary
Deployment runbooks (production, SSL, monitoring, backup, restore, DR)
Roadmap / next-steps separation from progress
Phase area docs for Accounting, CRM, Restaurant, Marketplace, Automation, AI, Future
Cross-links updated in root and package READMEs

Phase 5.1–5.11 — Accounting Module ✅

Phases 5.1–5.6: Foundation through Sales Integration (see prior entry)
Phase 5.7: Purchase & Inventory accounting, InventoryValuationEngine
Phase 5.8: Fixed Assets, DepreciationEngine, asset lifecycle
Phase 5.9: HCM/Payroll, PayrollEngine, payroll accounting
Phase 5.10: Financial Reporting Engine, dashboards, export framework
Phase 5.11: Compliance, Audit Framework, Governance, SoD
Alembic migration 0002_phases_57_511
21 tests passing

Accounting Enterprise Frontend (in SuperApp) ✅ baseline

Design system tokens (light/dark) + DS components (components/ds)
TanStack Query providers, Sonner toasts, ColorMode
Typed accounting-api client (JWT + X-Tenant-ID, no mocks)
Accounting shell + routes: dashboard, COA, fiscal, currencies, cost centers, projects, ledger, setup, suppliers
Vouchers list/create/detail with validate/post/reverse/cancel + draft edit (ADR-010)
Foundation masters: edit/archive drawers, fiscal year/period actions, COA template import wizard
Setup checklist + completion scoreboard on dashboard
Treasury, customers, assets, payroll, reports, audit, settings pages (real APIs)
Catalog tile available → /accounting
Frontend docs under docs/frontend/

Remaining: Phase 5.12 AI UI blocked on AI provider; optional richer PDF export file delivery.

Accounting Frontend Integration (FE ↔ BE 5.1–5.11) ✅

Full route/menu scan vs /api/v1 routers; gap matrix executed
Domain rewires: payroll employees, compliance policies/risks, settlements, sales-accounting post, purchase GR + valuation, asset schedule, monitoring health
FE client: settlements, salesAccounting, purchaseInventory, compliance approvals/risks, ops PATCH
Ops documents: detail + edit; treasury receipt/payment cash/bank binding; voucher list pagination
BE list endpoints for settlements, risks, purchase posting-profiles (integration completeness)
Report: accounting-frontend-integration-report.md
Scoreboard honesty for partial/ops-backed modules; AI remains blocked

Phase 6.0 — CRM Service Foundation ✅

backend/services/crm service scaffold (API / services / repositories / models)
Base aggregates: Lead, Contact, Organization, Opportunity, Pipeline, PipelineStage, SalesActivity, Quote
Publish-only event contracts (crm.lead.*, crm.opportunity.*, …)
CRM APIs only (/api/v1/leads|contacts|organizations|pipelines|opportunities|activities|quotes)
Platform provider contracts only (Automation, Customer360, Notification, Analytics, AI, Communication, Helpdesk)
Permissions crm.* trees; tenant isolation via X-Tenant-ID
Alembic 0001_initial + crm_db wiring (compose port 8003)
Architecture / dependency / repository / migration / API / permission / tenant / docs tests
Docs: crm-phase-6-0.md, module registry, phase area README

Phase 6.1 — Enterprise CRM Core Business Entities ✅

Expanded Lead / Contact / Organization (numbers, multi-contact, soft delete, audit actors)
Lookups: lead_sources, lead_statuses, contact_types, organization_types, organization_industries
Lead assignments, tag engine, reusable addresses, custom fields + values
Versioned notes, attachment file-storage references (no binary), CRM audit log
Services / repositories / validators / permissions / events for Phase 6.1
Alembic 0002_phase_61_entities
API coverage under /api/v1 for entities + lookups
Tests: model, repository, service, API, permission, migration, validation, audit, tenant, docs
Docs: crm-phase-6-1.md

Phase 6.2 — Enterprise Sales Process Engine ✅

Opportunity engine (number, title, revenue, probability, priority, close dates, soft delete, actors)
Unlimited pipelines + pipeline stages (start/won/lost/closed flags, required fields, exit validation)
Stage history, opportunity products (product_ref only), contact roles, competitors
Sales playbooks (versioned) + steps + assignments + completion tracking
Win/loss categories, reasons, immutable opportunity_win_loss snapshot
Rule-based forecasts (pipeline / weighted / committed; monthly/quarterly/annual)
Sales goals + targets with achievement %
Sales process definitions + sales_audit trail
Services / validators / events / permissions (crm.pipelines|playbooks|forecasts|goals|targets.*)
Alembic 0003_phase_62_sales_engine; version 0.6.2.0
API coverage for sales engine under /api/v1
Tests: pipeline, stage, playbook, forecast, win/loss, business rules, migration, permission, tenant, docs
Docs: crm-phase-6-2.md

Phase 6.3 — Enterprise Sales Collaboration Platform ✅

Expanded sales activities (types, priority, CRM entity links, participants, reminders)
Tasks + checklists + completion tracking
Meetings + attendees + finish/outcome
Call logs (opportunity-linked) + call outcomes
Email threads/messages metadata only (no delivery)
Immutable sales timeline + timeline event links
Threaded/versioned comments, mentions, bookmarks, favorites
Sales team roles/members/assignments + notification preferences
Collaboration audit; events crm.task|meeting|call|timeline|comment|mention.*
Permissions crm.tasks|meetings|calls|timeline|comments|mentions|team.*
Alembic 0004_phase_63_collaboration; version 0.6.3.0
Tests + docs: crm-phase-6-3.md

CRM Core Platform

Phases 6.0–6.3 complete (Foundation, Master Data, Sales Engine, Collaboration)

Phase 7.0 — Loyalty Service Foundation ✅

backend/services/loyalty service scaffold (API / services / repositories / models)
Foundation aggregates: LoyaltyProgram, MembershipTier, Member, PointAccount, Reward, Campaign, LoyaltyAuditLog, OutboxEvent
No mutable balance on PointAccount — direct balance mutation forbidden (extra=forbid)
Optimistic locking on Program / Member / PointAccount; campaign rule_version
Publish-only events via transactional outbox (loyalty.program|tier|member|point_account|reward|campaign.*)
Loyalty APIs only (/api/v1/programs|tiers|members|point-accounts|rewards|campaigns|audit)
Platform provider contracts only (Notification, Analytics, Customer360, AI, ModuleIntegration, CRM, Communication, FileStorage)
Permissions loyalty.* trees with manage/view inheritance; tenant isolation via X-Tenant-ID
Alembic 0001_initial + loyalty_db wiring (compose port 8004)
Soft-delete unique reclaim; IntegrityError → 409; null required-field → 422; production config guards
Enterprise validation & self-heal (incl. removal of incomplete 7.1 residue) — 52 tests passed
Docs: loyalty-phase-7-0.md, loyalty-phase-7-0-audit.md, ADR-011, module registry, phase area README

Phase 7.1 — Membership Engine ✅

Lifecycle state machine (activate / renew / freeze / resume / cancel / expire / transfer)
Member lifecycle fields + MembershipLifecycleEvent append-only history
Program soft-delete cascade policy: reject when blocking members exist
Permissions loyalty.members.{activate,renew,freeze,resume,cancel,expire,transfer,lifecycle.view}
Events loyalty.member.{activated,renewed,frozen,resumed,cancelled,expired,transferred}
Alembic 0002_phase_71_membership; version 0.7.1.0
Tests green (59) including test_phase71.py
Docs: loyalty-phase-7-1.md, phase-handover/phase-7-1.md, manifests, registry

Phase 8.0–8.10 — Enterprise Communication Platform ✅

Independent communication-service / communication_db (port 8005) — not owned by CRM/Loyalty/Restaurant
Provider framework + registry (mock, payamak; stubs for email/push/whatsapp/telegram/rubika/voice)
Communication router with priority, automatic failover, retry, circuit breaker
SMS platform: sender numbers, balance, rate limits, provider logs
Template engine: variables, locale, versioning, approval, preview, rendering
Dynamic contact sources (manual, CSV, CRM/Loyalty/Restaurant/Marketplace/Accounting/Website/External REST) — resolve only, no duplication
Queue engine: async queue, scheduling, priority, backoff retry, DLQ, batch
Delivery tracking: queued/sent/delivered/failed/expired/cancelled + timeline
OTP platform: generate/verify/expire, rate limit, brute-force lock, multi-channel path
Incoming provider webhooks with signature verification
Health /health, Capability /capabilities, providers status, monitoring stats
Permissions communication.*; events communication.*; audit on every send
Alembic 0001_initial; version 0.8.10.0
Tests: architecture, health/security, providers/SMS/failover/queue, templates/contacts/OTP/webhooks, validators
Docs: communication-phase-8.md, ADR-012, module/provider registry, progress

Phase AF — AI Development Framework ✅

Documentation-only. No business functionality. No modifications to existing services, schemas, or APIs.

Permanent area docs/ai-framework/
Master prompt, development loop, phase handover, quality gates
Templates: phase, service, module, entity, repository, service-layer, API, event, testing, documentation
Manifests: phase-manifest.yaml, service-manifest.yaml
Prompt rules + Cursor guidelines
Docs index / module registry / progress integration
ADR-013 Accepted
Architecture, documentation, cross-reference, link, template, and manifest validation

Phase SC-Reg — Sports Center Platform Registration ✅

Documentation-only registration. No business code, models, APIs, migrations, or repositories.

Phase roadmap 9.0–9.10 registered in phase-manifest.yaml
Service registered in service-manifest.yaml
Planned modules registered in module-registry.md
Sports terminology added to glossary.md
Roadmap doc: sports-center-roadmap.md
ADR-014 Accepted — Independent Sports Center Platform
Module boundaries + phase area README updated
Manifest / cross-reference / documentation / module validation passed

Phase 9.0 — Sports Center Platform Foundation ✅

backend/services/sports_center service scaffold (API / services / repositories / models)
Foundation aggregates: SportsCenter, Branch, Sport, MembershipType, Membership, Coach, SportsRole, SportsPermission, Facility, Court, Room, LockerRoom, Locker, DeviceProvider, Device, AttendanceGateway, SportsConfiguration, SportsEvent, SportsSetting, SportsAuditLog
Adapter-based connector framework (QR/RFID/Barcode/Fingerprint/Face/Turnstile/Door/Payment/Attendance) — interfaces only
Platform provider contracts only (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, Customer360)
Publish-only events (sports_center.member|membership|coach|facility|device|attendance|locker.*)
Sports APIs under /api/v1 + device connect/disconnect + locker assign/release
Permissions sports_center.* trees; tenant isolation via X-Tenant-ID
Alembic 0001_initial + sports_center_db wiring (compose port 8006)
Architecture / API / permissions / migration / dependency / connectors / docs tests
Docs: sports-center-phase-9-0.md, phase-handover/phase-9-0.md, ADR-014, module registry
No business workflow engines (booking/attendance lifecycle deferred)

Phase 9.1 — Sports Center Membership Catalog ✅

Catalog aggregates: SportCategory, AgeGroup, PricingModel, MembershipPackage, MembershipPlan, MembershipRule, RenewalPolicy, FreezingRule, ExpirationPolicy
MembershipType extended with catalog refs (package/plan/pricing/age/category/policies), transferability, sort order
Validators for age range, pricing/billing/rule kinds, money amounts, catalog ref integrity
Publish-only catalog events; permissions trees for catalog modules
APIs under /api/v1/sport-categories|age-groups|pricing-models|membership-packages|membership-plans|membership-rules|renewal-policies|freezing-rules|expiration-policies
/capabilities endpoint; version 0.9.1.0
Alembic 0002_phase_91_membership_catalog
Tests: catalog API, tenant isolation, age validation, architecture, docs
Docs: sports-center-phase-9-1.md, phase-handover/phase-9-1.md
No member enrollment / coach / attendance / booking engines

Phase 9.2 — Sports Center Member Management ✅

Members aggregate + family members, emergency contacts, medical information shells
Membership assignment (member_id) consuming Phase 9.1 catalog types
Status management: activate / suspend / cancel / freeze / unfreeze
Membership cards (QR/physical/digital), digital membership passes, waivers (sign), member documents (Storage refs)
Validators, permissions (sports_center.members.* trees), publish-only events
Alembic 0003_phase_92_member_management; version 0.9.2.0
Tests: members API, tenant isolation, transitions, architecture, migration, docs
Docs: sports-center-phase-9-2.md, phase-handover/phase-9-2.md
No coach / attendance / booking engines

18 KiB Raw Blame History Unescape Escape