chore(ci,docs): GitHub Actions, ADRs, README overhaul, §21 Hardening Release
- .github/workflows/ci.yml: two jobs — frontend (tsc --noEmit, lint, build, Playwright) and backend (Postgres 16 + odoo:19 --test-enable --test-tags encoach_api) — catches regressions before merge. - docs/adr/: start an Architecture Decision Record trail with 0001 canonical directory layout, 0002 JWT refresh flow, 0003 paginated response envelope, 0004 RAG metadata + chunking. - docs/PROJECT_SUMMARY.md §21 Hardening Release: full recap of the AI quality loop, compliance, Paymob, i18n, and CI work shipped in this drop, plus new DB tables, REST routes, frontend routes, verification results, and operator-facing configuration. - README.md refreshed for the v4 split-repo doctrine and the new feature surface. - new_project/DEPRECATED.md: formal retirement notice pointing at backend/ as the canonical tree. Made-with: Cursor
This commit is contained in:
Yamen Ahmad
@@ -1319,3 +1319,133 @@ Network tab showed `/api/reports/filters 200`, `/api/reports/record?size=100 200
|
||||
- **Both `encoach_exam_template` and `encoach_scoring` declare `encoach.student.attempt`.** The Reports controller only reads fields that exist on both definitions (`listening/reading/writing/speaking/overall_band`, `cefr_level`, `status`, `started_at`, and whichever of `completed_at` / `finished_at` is present — `_attempt_completed_at()` probes both). No field access assumes a specific addon version.
|
||||
- **In-progress attempts are excluded from the aggregates.** If you ever notice a student you expect to see missing from Student Performance or Stats Corporate, check their attempt status — `in_progress` attempts are deliberately skipped. They DO still appear in the Record page (which shows everything) unless you also pass `status` or `period` filters.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## §21 — Hardening Release (Phase 2/3 completion)
|
||||
|
||||
This section records the final wave of work that closed out all remaining items in the Phase 2 (performance & reliability) and Phase 3 (core AI features, accessibility, onboarding) roadmaps. After this release the platform is considered deployment-ready.
|
||||
|
||||
### 21.1 What shipped
|
||||
|
||||
The release is organised by capability, not file path.
|
||||
|
||||
#### Human-in-the-loop AI quality loop (P3.3 → P3.5)
|
||||
|
||||
| Stage | Where | What it does |
|
||||
|---|---|---|
|
||||
| 1. Quality gate | `encoach_exam_template.services.quality_checker` + `ielts_validator` | Runs after every AI exam submit; if scores fall below thresholds the exam is parked in `pending_review` instead of `published`. |
|
||||
| 2. Review queue | `encoach_exam_template/controllers/review_workflow.py` + `frontend/src/pages/admin/ExamReview{Queue,Detail}.tsx` | Admin-only pages list pending exams, surface aggregate + per-question quality reports, and let a reviewer approve (`→ published`) or reject (`→ draft`) with audit notes. Writes to new `reviewed_by_id`, `reviewed_at`, `review_notes` fields. |
|
||||
| 3. Prompt library | `encoach_ai.models.ai_prompt` + `controllers/prompt_controller.py` + `frontend/src/pages/admin/AIPromptEditor.tsx` | `encoach.ai.prompt` with a unique `(key, version)` key, one active row per key. Authors can add a new version, activate it (auto-deactivates prior), and dry-run render with sample variables. Renderer uses `str.format_map` against a safe dict. |
|
||||
| 4. Student feedback | `encoach_ai.models.ai_feedback` + `controllers/feedback_controller.py` + `frontend/src/components/AIFeedbackButtons.tsx` + `frontend/src/pages/admin/AIFeedbackTriage.tsx` | Thumbs up/down on any AI artefact (`question`, `coach`, `explanation`, `translation`, `narrative`, `other`). Unique `(user, subject_type, subject_id)` constraint gives upsert semantics; thumbs-down requires a comment. Admin triage page lists/filters/resolves feedback (`open → acknowledged|fixed|dismissed`). |
|
||||
|
||||
Together these four stages mean every AI output can be gated, reviewed, iterated, and measured — closing the loop from prompt → generation → delivery → feedback → next prompt revision.
|
||||
|
||||
#### Compliance (P3.2)
|
||||
|
||||
New `encoach_api/controllers/gdpr.py` + `models/gdpr_erasure.py`:
|
||||
|
||||
- `GET /api/gdpr/export` — JSON dump of the calling user's profile, entity memberships, exam attempts, answers, AI feedback, AI calls, tickets, coaching sessions.
|
||||
- `POST /api/gdpr/delete` — requires `{"confirm": true}`; anonymises the partner PII, deletes personal feedback + coaching transcripts, strips free-text PII from retained exam answers, nulls `user_id` on AI logs, deactivates the `res.users` row, and writes a tombstone to `encoach.gdpr.erasure.request` for audit. Admin accounts are blocked from self-erasure.
|
||||
- `frontend/src/pages/PrivacyCenter.tsx` — routed at `/student/privacy`, `/teacher/privacy`, `/admin/privacy`; download-my-data button produces a timestamped JSON file; erase flow is gated behind a `type "DELETE" to confirm` alert dialog.
|
||||
|
||||
#### Paymob real checkout (P2.6)
|
||||
|
||||
New `encoach_lms_api/controllers/paymob.py` + `models/paymob_order.py`:
|
||||
|
||||
- `POST /api/payments/paymob/checkout` runs the three-step Paymob Accept flow (auth → order → payment key) and returns the hosted iframe URL. Our `encoach.paymob.order` row is created *before* the external call so partial failures don't lose orders.
|
||||
- `POST /api/payments/paymob/webhook` verifies the HMAC-SHA512 signature over Paymob's canonical field sequence (`amount_cents|created_at|currency|…|success`). Mismatches return 401; duplicates are idempotent; unknown orders return 200 to stop Paymob retrying.
|
||||
- Credentials read at request time from `ir.config_parameter` (`encoach.paymob.api_key`, `hmac_secret`, `integration_id`, `iframe_id`) so operators can rotate without restarting Odoo.
|
||||
- `GET /api/paymob-orders` now reads real rows instead of returning `[]`.
|
||||
|
||||
#### Internationalisation (P3.1)
|
||||
|
||||
- `frontend/src/i18n/` bootstraps `i18next` + `i18next-browser-languagedetector` with nested feature-scoped namespaces.
|
||||
- Initial locales: `en` (source of truth, typed with `Translations` interface) and `ar` (full translation of the same keys).
|
||||
- RTL handling: when the active language is in `RTL_LANGS`, `document.documentElement.dir` is flipped to `rtl` so Tailwind utilities and Radix primitives adapt.
|
||||
- `frontend/src/components/LanguageToggle.tsx` added next to the theme toggle in both `AdminLmsLayout` and `RoleLayout` headers.
|
||||
- Loaded via `main.tsx` side-effect import so every route picks it up.
|
||||
|
||||
#### CI scaffolding (P3.8)
|
||||
|
||||
- `.github/workflows/ci.yml` with two jobs:
|
||||
- **frontend**: `tsc --noEmit` → `eslint` → `vite build` → Playwright smoke tests against the Vite preview server; uploads a Playwright HTML report on failure.
|
||||
- **backend**: spins up Postgres 16 as a service and runs the Odoo 19 container with `--test-enable --test-tags encoach_api` against a throwaway `encoach_ci` database.
|
||||
- `backend/custom_addons/encoach_api/tests/test_health.py` — first `HttpCase`: asserts `/api/health` returns 200 and `/api/health/ready` returns 200 or 503 (never 5xx).
|
||||
- `frontend/playwright.config.ts` + `frontend/e2e/login.spec.ts` — the login page renders the sign-in form; `/` redirects unauthenticated traffic to `/login`.
|
||||
- New npm scripts: `test:e2e`, `test:e2e:install`.
|
||||
|
||||
### 21.2 New DB tables (summary)
|
||||
|
||||
| Table | Purpose | Added in |
|
||||
|---|---|---|
|
||||
| `encoach.ai.prompt` | Versioned prompt templates (`key`, `version`, `is_active`, `content`). | P3.4 |
|
||||
| `encoach.ai.feedback` | Student thumbs up/down on AI output, with triage status. | P3.5 |
|
||||
| `encoach.gdpr.erasure.request` | Tombstone row per right-to-erasure request. | P3.2 |
|
||||
| `encoach.paymob.order` | Full lifecycle of every Paymob checkout, including the verified HMAC. | P2.6 |
|
||||
|
||||
All have per-group `ir.model.access.csv` entries: admin read/write, authenticated-user read for metadata, create-only on feedback.
|
||||
|
||||
### 21.3 New REST endpoints
|
||||
|
||||
Everything requires a valid JWT unless noted; write routes additionally check `base.group_system` where relevant.
|
||||
|
||||
```
|
||||
GET /api/ai/prompts list keys (latest per key)
|
||||
GET /api/ai/prompts/:key/versions full history for a key
|
||||
GET /api/ai/prompts/:id one version (full content)
|
||||
POST /api/ai/prompts create new version (admin)
|
||||
POST /api/ai/prompts/:id/activate flip active pointer (admin)
|
||||
POST /api/ai/prompts/:id/render dry-run render with sample vars
|
||||
|
||||
POST /api/ai/feedback upsert (user)
|
||||
GET /api/ai/feedback/summary up/down counts + my rating
|
||||
GET /api/ai/feedback admin triage list
|
||||
POST /api/ai/feedback/:id/resolve admin triage resolve
|
||||
|
||||
GET /api/gdpr/export full data-subject export (self)
|
||||
POST /api/gdpr/delete right-to-erasure (self, confirm=true)
|
||||
|
||||
POST /api/payments/paymob/checkout start a checkout
|
||||
POST /api/payments/paymob/webhook HMAC-verified callback (public)
|
||||
GET /api/payments/paymob/orders list my orders
|
||||
GET /api/paymob-orders admin + self order list (rewired)
|
||||
```
|
||||
|
||||
### 21.4 Frontend surface (new routes)
|
||||
|
||||
```
|
||||
/admin/exam/review-queue → ExamReviewQueue.tsx
|
||||
/admin/exam/review/:examId → ExamReviewDetail.tsx
|
||||
/admin/ai/prompts → AIPromptEditor.tsx
|
||||
/admin/ai/feedback → AIFeedbackTriage.tsx
|
||||
/student|teacher|admin/privacy → PrivacyCenter.tsx
|
||||
```
|
||||
|
||||
Plus the `AIFeedbackButtons` primitive (drop-in `<ThumbsUp/>/<ThumbsDown/>` that handles the upsert, dialog, and comment prompt) and `LanguageToggle` in both main layouts.
|
||||
|
||||
### 21.5 Verification
|
||||
|
||||
- `python3 -m compileall -q backend/custom_addons/encoach_ai backend/custom_addons/encoach_api backend/custom_addons/encoach_lms_api` — clean.
|
||||
- `npx tsc --noEmit -p tsconfig.app.json` — clean.
|
||||
- `npm run build` — succeeds; bundle analyser shows the same split profile as the §20 release (initial JS ≈ 250 KB gzipped on the login path); new features are lazy-loaded chunks.
|
||||
- New modules do not depend on optional addons: all cross-model reads use `if model in request.env` guards so missing addons degrade gracefully instead of 500-ing.
|
||||
|
||||
### 21.6 Configuration operators need to set
|
||||
|
||||
Before the Paymob flow will actually charge anything, set in **Settings → Technical → System Parameters**:
|
||||
|
||||
```
|
||||
encoach.paymob.api_key = <merchant API key>
|
||||
encoach.paymob.hmac_secret = <from Paymob dashboard>
|
||||
encoach.paymob.integration_id = <default integration (card)>
|
||||
encoach.paymob.iframe_id = <hosted iframe id>
|
||||
```
|
||||
|
||||
Until those are set, `POST /api/payments/paymob/checkout` returns 503 with a descriptive message instead of silently crashing.
|
||||
|
||||
### 21.7 Deferred (known)
|
||||
|
||||
- `P1.2` — blanket-sudo audit + entity-isolation `ir.rule`s. Needs a coordinated frontend + data migration pass; deferred to a follow-up release. Current security model relies on JWT identity + controller-level `has_group` checks.
|
||||
- Broader i18n coverage. Only the keys listed in `src/i18n/locales/en.ts` are translated today — extending to every page is a rolling job that can happen in small PRs now that the plumbing is in place.
|
||||
- Playwright coverage is intentionally minimal (login + redirect); it exists as a safety net, not as full end-to-end coverage.
|
||||
|
||||
Reference in New Issue
Block a user