Sync Product co2api-revised-roadmap from project files

Product co2api-revised-roadmap.-.md

@@ -0,0 +1,172 @@
+<!-- codex-wiki-sync:7c33553b4615eb0220627f3b -->
+
+> Mirrored from `/mnt/DATA/Nextcloud/ADD ideas UG/Products/co2api/revised_roadmap.txt`.
+> Origin: `product:co2api`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+✅ UNIFIED ROADMAP — calco2la.to
+===============================
+
+1. ✅ CORE DATA MODELS
+----------------------
+- ✅ User model
+    - UUID primary key, password hashing
+    - is_confirmed, is_active_now, permission helpers
+- ✅ Role model
+    - Global roles with is_global
+- ✅ Organization model
+    - Recursive org trees supported
+- ✅ OrganizationMembership model
+    - Users ↔ Orgs with scoped roles
+- ✅ Permissions
+    - Scopes like user:create, org:update
+    - RolePermission & MembershipPermission
+- ✅ APIKey model
+    - Secure tokens, expiration, revocation
+    - Tracks usage_count and last_used_at
+- ✅ Airport model
+    - IATA, ICAO, city, geodata, valid_from/to
+- ✅ BillingInfo (org-level)
+- ✅ Factor model (stub; extendable)
+
+2. ✅ PERMISSIONS & ROLES
+-------------------------
+- Role templates (admin, org_admin, etc.)
+- Wildcard permission support
+- Scoped inheritance based on org hierarchy
+- Decorators + Jinja2 helpers
+
+3. ✅ AUTHENTICATION & ACCESS CONTROL
+-------------------------------------
+- Flask-Login session handling
+- Login, logout, registration
+- Email confirmation with token
+- Profile edit modal
+- ☐ Resend confirmation
+- ☐ Session expiration handling
+
+4. ✅ INTERNATIONALIZATION (i18n)
+---------------------------------
+- Flask-Babel + URL switching via /lang/<code>
+- _() support in templates
+- ☐ Admin-set default locale
+
+5. ✅ UI & TEMPLATES
+--------------------
+- Unified base template w/ header/footer
+- Login/register/profile/admin views styled
+- Icons for login/logout/user
+- ☐ Improve flash/toastr messages
+- ☐ Better JS UX (modals/forms)
+
+6. ✅ FLASK-ADMIN REMOVED
+--------------------------
+- Replaced with scoped custom admin UI
+
+7. ✅ EMAIL SERVICES
+--------------------
+- Register confirmation
+- Token-based reset
+- ☐ Resend unverified email
+- ☐ Admin address update
+- ☐ SMTP from env + admin config
+
+8. ✅ API KEY MANAGEMENT
+------------------------
+- secrets.token_urlsafe generation
+- Scoped access, limits
+- last_used and usage_count tracked
+- Create/revoke UI modals
+- ☐ Rotate on expiration
+- ☐ Global usage stats
+
+9. ✅ AIRPORT & FACTOR MANAGEMENT
+---------------------------------
+- Airport seed (~200)
+- Fuzzy matching helpers
+- Factor model scaffolded
+- ☐ Pagination/search
+- ☐ Versioned factor editing
+- ☐ Permissions for data_modeler
+
+10. ✅ ORGANIZATION & MEMBERSHIP
+-------------------------------
+- Recursive org creation
+- Scoped memberships
+- ☐ Invite by email
+- ☐ Handle orphaned orgs
+
+11. 🔥 API ENDPOINTS
+---------------------
+- ✅ /api/airports
+    - Filtering, pagination, sort
+    - API key auth & usage count
+    - OpenAPI spec
+- ✅ /api/flight
+    - Via support, segment calc (mock)
+    - Full segment unpacking + per-leg stats
+    - OpenAPI schema
+- ☐ /api/factors
+- ☐ Real emission logic (for /flight)
+- ☐ Rate limiting (APIKey)
+- ☐ API versioning (v1, test, latest)
+- ☐ Serve openapi.json
+- ☐ API response caching
+
+12. ✅ TESTING
+--------------
+- ✅ Unit tests (models, utils)
+- ☐ Integration: login, session
+- ☐ API auth + input tests
+- ☐ CLI test runner
+- ☐ Mock email/token flow
+
+13. ✅ OPTIONAL ENHANCEMENTS
+----------------------------
+- ☐ MFA support
+- ☐ Audit log: role/key changes
+- ☐ Admin impersonation
+- ☐ OIDC integration (future)
+- ☐ Profile pictures
+
+---
+
+🔥 CRITICAL PATH TO WORKING API
+===============================
+1. ✅ Roles & permission system
+2. ✅ Org + role hierarchy
+3. ✅ Finalize API key model & checks
+4. ✅ Normalize airport data
+5. ✅ Finalize factor access model
+6. ☐ Integrate real CO₂ calc logic
+7. ☐ Finalize flight endpoint (with segments)
+8. ☐ Docs: Swagger UI + openapi.json
+9. ☐ Version support + test endpoint
+10. ☐ Rate limiting by API key
+11. ☐ Deploy with monitoring
+
+---
+
+📌 IMMEDIATE TODOs
+==================
+- [Swagger 3.0] Fix Swagger / OpenAPI integration
+    * Flasgger fails loading YAML specs
+    * Validate OpenAPI 3.0.2 compatibility
+    * Enable correct UI rendering
+- Finalize YAML specs for all endpoints
+    * Fix `@swag_from` paths
+    * Define common schemas + responses
+- Real CO₂/fuel/distance calcs (mock → realistic)
+- Rate limit per API key
+- Test endpoint to remain mock-only
+
+---
+
+📊 FUTURE: ADMIN FEATURES
+=========================
+- Live usage dashboard (admin)
+- APIKeyUsage model (optional logging)
+- Alerts on usage limits
+- Client SDK generator
+- GraphQL/visual query interface