# Operations Suite — Integrated Premium Edition

This document describes the operational expansion merged into the premium cPanel checkpoint.

## 1. Live farm operations dashboard

The web dashboard now links to `/dashboard/farm`. The database adds `farm_daily_reports`, veterinary records, vaccinations, tasks, equipment and maintenance history. The API exposes:

- `GET /api/operations/overview?projectId=...`
- `GET /api/operations/farm-units?projectId=...`
- `GET /api/operations/daily-reports?projectId=...`
- `POST /api/operations/daily-reports` — protected by `INTERNAL_API_SECRET` until full user authentication/RBAC is completed.

Daily reports validate the poultry closing balance and egg breakdown before insert.

## 2. Project management

`project_milestones` stores planned/actual dates, progress, responsibility and evidence. Public project APIs expose only projects in public statuses and never return the encrypted precise location.

## 3. License and document center

The existing ownership/license records remain the source of truth. `/dashboard/documents` and `/admin/licenses` expose the design shell for versioning, expiry, publication and review. `GET /api/documents/expiring` returns documents approaching expiry.

No license number, issuing authority or verification status is invented by the application.

## 4. Investor/user portal

The existing `/dashboard` remains the user/investor shell. Live investment, money collection and payment remain disabled. Operational and document features can be used without activating financial transactions.

## 5. Reports

`report_jobs` stores report generation requests. The API supports summary aggregation and a queue for `PDF`, `XLSX` and `CSV` output adapters. On shared hosting, heavy generation should be executed as bounded Cron work rather than a permanent worker.

Current repository code includes queue/storage architecture. Binary PDF/XLSX renderer execution still requires installed runtime dependencies on the target hosting environment and remains a deployment validation item.

## 6. cPanel Cron scheduler

The authenticated Cron endpoint now performs bounded work when PostgreSQL is connected:

- expired session cleanup;
- OTP cleanup;
- expiring-document scan;
- queued-report scan;
- farm-task reminder scan;
- health snapshot recording.

`CRON_SECRET` is independent from `INTERNAL_API_SECRET`.

## 7. Operational AI

`/dashboard/ai` and `/api/ai/*` implement an explainable rule engine. It compares two seven-day windows for:

- egg production change;
- feed-consumption change;
- mortality change.

Insights are stored with evidence and provider metadata. They are operational signals only and must not be presented as guaranteed return, personalized investment advice or veterinary diagnosis.

## 8. PWA/mobile web

The web app now includes:

- manifest with 192px and 512px install icons;
- production service-worker registration;
- navigation/offline shell caching;
- responsive mobile dock;
- reduced-motion support.

This provides an installable web experience while the future Flutter app remains a separate phase.

## 9. Security expansion

The premium checkpoint now includes:

- basic API rate limiting in the cPanel combined server;
- security headers;
- internal mutation guard using a hosting secret;
- 2FA method schema;
- security event schema;
- login-attempt history;
- device/session architecture;
- `/dashboard/security` and `/api/security/summary`.

Full user authentication and RBAC guards remain a dedicated next phase; therefore sensitive mutation endpoints are not left anonymously writable in the interim.

## 10. System health and backup tracking

`/admin/system` is the operations view. The database tracks health snapshots and backup executions, including verification and restore-test timestamps. `/api/system/health` reports application/database/Cron/backup state without revealing connection strings or secrets.

Actual hosting backup execution and restore testing must be performed on the real cPanel environment because the current coding workspace has no PostgreSQL CLI or Namecheap account access.