qa-portal — CONTEXT.md

Internal Angular 20 app for the syncc QA team. Covers test case management (CRUD), manual execution logging, coverage dashboard, and QA user management. Only accessible to users with role QA, ADMIN, SUPER_ADMIN, or SUPER_ADMIN_LOCAL. For global conventions (branding, Angular patterns, Docker), see /CLAUDE.md.

1. Routes

Path	Component	Roles
`/login`	`LoginComponent`	Public
`/`	redirects to `/dashboard`	—
`/dashboard`	`DashboardComponent`	Any authenticated
`/test-cases`	`TestCaseListComponent`	Any authenticated
`/test-cases/new`	`TestCaseFormComponent`	Any authenticated
`/test-cases/:id`	`TestCaseDetailComponent`	Any authenticated
`/test-cases/:id/edit`	`TestCaseFormComponent`	Any authenticated
`/users`	`UsersComponent`	SUPER_ADMIN only
`**`	redirects to `/`	—

Guards: - authGuard — validates JWT; redirects to /login if absent or expired - superAdminGuard — restricts /users to SUPER_ADMIN / SUPER_ADMIN_LOCAL roles; redirects to /dashboard otherwise

2. Test Case Code Format

Codes are auto-generated on creation — never editable. Format: TC-{APP}-{NNN}.

App key	Code prefix	Label
`mobile-driver`	`TC-DR-`	App Conductor
`passengers-app`	`TC-PA-`	App Pasajero
`web-admin`	`TC-AD-`	Panel Admin
`syncc-landing`	`TC-LA-`	Landing Page
`analytics`	`TC-AN-`	Analytics
`qa-portal`	`TC-QA-`	QA Portal

Numbers are 3 digits (TC-DR-001), auto-extend to 4+ at 1000. Code generation is in apps/api-server/src/test-cases/test-cases.service.ts (the generateCode() private method).

The test case form and list filter use a cascading App → Module (feature) pattern, defined in src/app/constants/apps.ts as APPS: AppDef[]. Changing the app resets the module field.

4. Key Components

Component	Directory	Purpose
`LoginComponent`	`components/login/`	Auth form — matches analytics login style
`AppShellComponent`	`app-shell.component.ts`	Green navbar + `<router-outlet>`
`DashboardComponent`	`components/dashboard/`	Coverage stats by app/module
`TestCaseListComponent`	`components/test-case-list/`	Paginated table with filters
`TestCaseFormComponent`	`components/test-case-form/`	Create / edit (preconditions + steps FormArrays)
`TestCaseDetailComponent`	`components/test-case-detail/`	Detail view + manual execution logger
`UsersComponent`	`components/users/`	QA user creation and activation toggle

5. Services

Service	Path	Purpose
`AuthService`	`services/auth.service.ts`	Login, JWT in `localStorage` (`syncc_qa_token`), `currentUser()` signal
`TestCasesService`	`services/test-cases.service.ts`	CRUD + coverage + execution logging
`QaUsersService`	`services/qa-users.service.ts`	`GET /users/qa`, `PATCH /users/qa/:id/toggle`
`AuthInterceptor`	`interceptors/auth.interceptor.ts`	Attaches `Authorization: Bearer` header

6. Backend Endpoints Used

All requests go to environment.apiUrl (default http://localhost:3000).

Method	Path	Description
`POST`	`/auth/login`	Login — returns JWT
`GET`	`/test-cases`	List with filters: `?app=&feature=&priority=&status=&search=&page=&limit=`
`GET`	`/test-cases/coverage`	Coverage aggregates by app + feature
`GET`	`/test-cases/:id`	Single test case with execution history
`POST`	`/test-cases`	Create (roles: SUPER_ADMIN, ADMIN, QA)
`PATCH`	`/test-cases/:id`	Update
`DELETE`	`/test-cases/:id`	Hard delete (roles: SUPER_ADMIN, ADMIN only)
`POST`	`/test-cases/:id/executions`	Log a manual execution result
`GET`	`/users/qa`	List QA users (SUPER_ADMIN only)
`PATCH`	`/users/qa/:id/toggle`	Toggle QA user active/inactive (SUPER_ADMIN only)

7. Environment

Only apiUrl is needed — no city, OSRM, or analytics keys.

export const environment = {
  production: boolean,
  apiUrl: string,   // e.g. 'https://api.syncc.me' in prod
};

set-env.cjs writes this file at build time from API_URL env var. Fails the build if API_URL is not set.

8. Dev Workflow

cd apps/qa-portal
npm install
npm start              # Dev server at http://localhost:4201 (local env)
npm run build:prod     # Production build → dist/qa-portal/browser/

9. Key File Paths

What	Path
Routes	`src/app/app.routes.ts`
App/module constants	`src/app/constants/apps.ts`
Auth service	`src/app/services/auth.service.ts`
Test cases service	`src/app/services/test-cases.service.ts`
Shell (navbar)	`src/app/app-shell.component.ts`
Login	`src/app/components/login/`
Test case list	`src/app/components/test-case-list/`
Test case form	`src/app/components/test-case-form/`
Test case detail	`src/app/components/test-case-detail/`
Dashboard	`src/app/components/dashboard/`
QA users	`src/app/components/users/`
Tailwind config	`tailwind.config.js`
Set-env script	`set-env.cjs`

Last updated: 2026-07-07.