TorbatYar/docs/phase-handover/phase-9-0.md

# Phase Handover — 9.0 Sports Center Platform Foundation

> Mandatory starting point for Phase 9.1.

## Overview

Phase 9.0 delivered the independent **Sports Center Platform** microservice (`sports-center-service`, `sports_center_db`, port **8006**, version **0.9.0.0**). Foundation aggregates, connector interfaces, permissions, publish-only events, APIs, migration, and docs are in place. **No business workflows** (booking, attendance engine, billing, class lifecycle) were implemented.

## Completed Scope

- Independent service scaffold aligned with Loyalty/Communication patterns
- 20 foundation tables / aggregates
- Adapter-based connector framework (interfaces only)
- Platform provider contracts (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, Customer360)
- Tenant-aware CRUD APIs + connect/disconnect + locker assign/release
- Configuration shells for hours/policies/locale/custom fields
- Alembic `0001_initial`, compose + `.env.example` wiring
- ADR-014, phase doc, module registry, progress updates

## Created Modules

sports_centers · branches · sports · membership_types · memberships · coaches · sports_roles · sports_permissions · facilities · courts · rooms · locker_rooms · lockers · devices · device_providers · attendance_gateways · sports_configuration · sports_events · sports_settings · sports_audit

## Created Models

See `backend/services/sports_center/app/models/foundation.py` — SportsCenter, Branch, Sport, MembershipType, Membership, Coach, SportsRole, SportsPermission, Facility, Court, Room, LockerRoom, Locker, DeviceProvider, Device, AttendanceGateway, SportsConfiguration, SportsEvent, SportsSetting, SportsAuditLog.

## Repositories

Tenant-scoped repositories in `app/repositories/foundation.py` extending `TenantBaseRepository` (soft-delete aware).

## Services

Application services in `app/services/foundation.py` + `audit_service.py`. Write path: validate → uniqueness → persist → audit → commit → publish.

## Validators

`app/validators/foundation.py` — codes, email/phone, enums, date ranges, optimistic lock, forbid sport-specific hardcoding keys.

## Permissions

`sports_center.*` definitions in `app/permissions/definitions.py` (registry contracts; route-level enforcement deferred like Loyalty).

## Events

Publish-only contracts in `app/events/types.py` including:

- sports_center.member.created
- sports_center.membership.created
- sports_center.coach.created
- sports_center.facility.created
- sports_center.device.connected / disconnected
- sports_center.attendance.provider.changed
- sports_center.locker.assigned / released

In-memory publisher only (outbox bus later per ADR-006).

## Public APIs

All under `/api/v1/*` (see phase doc). Soft delete via `POST /{id}/delete`.

## Internal APIs

None beyond service-local health and foundation CRUD. No internal S2S endpoints yet.

## Database Changes

New database `sports_center_db` (sole owner). No changes to Core/CRM/Loyalty/Communication schemas.

## Migration History

| Revision | Description |
| --- | --- |
| `0001_initial` | Create all Phase 9.0 foundation tables |

## Indexes

Tenant + status / deleted indexes; unique `(tenant_id, code)` (and center-scoped codes where applicable); locker/membership number uniques.

## Constraints

Unique constraints always include `tenant_id`. No cross-DB FKs. Cross-aggregate links are UUID columns only.

## Configuration

SportsConfiguration + SportsSetting support working hours, membership/attendance/booking policies, waiting list, custom fields, timezone, language, currency.

## Connector Framework

`app/connectors/` — DeviceConnector + specialized Protocols + ConnectorRegistry. Capabilities: QR, RFID, Barcode, Fingerprint, Face Recognition, Turnstile, Door Controller, Payment Terminal, Attendance Device, Custom.

## Provider Interfaces

Platform providers in `app/providers/contracts.py` (Protocols only). Device providers stored as registry rows with `adapter_key`.

## Extension Points

- Register vendor adapters on ConnectorRegistry by `adapter_key`
- Add sports catalog entries without code changes
- Policy JSON documents for later engines
- Commands / Queries / Specifications / Policies packages prepared as shells

## Integration Points

REST + Events only. External refs: `external_customer_ref`, `external_crm_contact_ref`, `external_user_ref`, file/device refs.

### Accounting Integration

Contract only (`AccountingProvider`). No postings in 9.0.

### CRM Integration

Contract only; membership may store `external_crm_contact_ref`.

### Loyalty Integration

Contract only; Sports does not own points/ledger.

### Communication Integration

Contract only; no SMS/provider calls from Sports.

### AI Integration

Contract only (`AIProvider.suggest`).

### Storage Integration

Contract only; store file refs later.

### Notification Integration

Contract only; no delivery ownership.

## Known Limitations

- No booking / attendance / membership lifecycle engines
- No vendor device adapters implemented
- Permissions defined but not enforced on routes (JWT + X-Tenant-ID only)
- Events in-memory (no durable outbox yet)
- No frontend module UI

## Backward Compatibility

New service — no breaking changes to existing modules.

## Architectural Decisions

ADR-014 (this service). Relies on ADR-001, ADR-003, ADR-006.

## Future Dependencies

Phase 9.1+ engines will depend on this foundation, Core entitlement, and later Communication/Notification/Accounting integrations.

## Requirements for Phase 9.1

1. Read this handover + `docs/sports-center-phase-9-0.md` + ADR-014 first
2. Do not recreate foundation aggregates
3. Implement the next unfinished sports engine only (as scoped in next-steps/roadmap)
4. Keep sport-agnostic rules; keep connectors adapter-based
5. Do not own Accounting/CRM/Loyalty/Communication/Notification/Storage/Identity/AI

## Open Risks

- Device vendor diversity may require careful adapter versioning
- Membership vs Loyalty “member” terminology — keep refs explicit
- Unique constraints with nullable branch_id on settings may behave differently across DBs

## Performance Notes

Foundation CRUD only; indexes on tenant_id + common filters. No hot-path attendance writes yet.

## Security Notes

JWT via Keycloak; tenant isolation via `X-Tenant-ID` + row `tenant_id`. Soft deletes. Audit trail append-only. Never put vendor secrets in business tables without encryption strategy (later).

## Testing Summary

Pytest suites: architecture, API flow/events, permissions, migration, dependency, connectors, docs.

## Documentation Summary

- `docs/sports-center-phase-9-0.md`
- `docs/phase-handover/phase-9-0.md` (this file)
- `docs/architecture/adr/ADR-014.md`
- `docs/phases/SportsCenter/README.md`
- Updates: progress, module-registry, next-steps, ADR README, module-boundaries

## Next Phase Entry Point

Start Phase **9.1** from this document. Confirm scope in `docs/next-steps.md` before coding. Do not skip ahead to later sports phases.