Owner dashboard: lead pipeline + client management #9

New issue

Open

opened 2026-05-09 18:23:46 +00:00 by forgejo_admin · 1 comment

forgejo_admin commented

2026-05-09 18:23:46 +00:00

Contributor

Type

Feature

Lineage

Standalone — implements the -admin surface per convention-client-project-structure.

Repo

ldraney/pal-enterprises

User Story

As the platform owner (Lucas)
I want an admin panel to view leads, promote them to clients, and manage client accounts
So that I can onboard and support clients without touching the database directly

Context

Per convention-client-project-structure, every project gets an -admin surface. For pal-enterprises, this is the owner-only panel where Lucas manages the leads pipeline and client accounts. The /admin route already exists in the scaffold (admin_controller.rb, admin/index.html.erb) but needs full CRUD for leads and client management. This is the dogfooding instance — pal-enterprises-admin is where Lucas manages his own business, the same way Marcus uses westside-admin.

File Targets

Files to modify:

app/controllers/admin_controller.rb — CRUD actions for leads and clients
app/views/admin/ — list, show, edit views for leads and clients
config/routes.rb — admin resource routes
app/services/keycloak_client.rb — Keycloak admin API integration for user creation on lead promotion

Files NOT to touch:

app/controllers/dashboard_controller.rb — separate from admin

Acceptance Criteria

/admin shows leads pipeline (new submissions, pending review)
Owner can view lead details (business name, name, logo, email)
Owner can promote a lead to client (triggers Keycloak user creation)
Owner can view all active clients with status
Only owner role can access /admin — clients get 403
Per-client links to their -docs and -admin surfaces visible

Test Expectations

Integration test: owner can access /admin
Integration test: client role is denied /admin access
Unit test: lead promotion creates Keycloak user
Run command: bin/rails test

Constraints

Owner-only access enforced by role check, not just route hiding
Keycloak user creation on promote should use the admin API
Keycloak admin API credentials sourced from environment variables (KEYCLOAK_ADMIN_URL, KEYCLOAK_ADMIN_USER, KEYCLOAK_ADMIN_PASSWORD) — see k8s/dev.yaml secrets
Follow existing Rails patterns (Hotwire/Turbo, plain CSS per ~/ror-css-guide)
Depends on #10 (Remove Tailwind) completing first — all new views use plain CSS design tokens, not Tailwind

Checklist

PR opened
Tests pass
No unrelated changes

convention-client-project-structure — the convention requiring this surface
project-pal-enterprises

### Type Feature ### Lineage Standalone — implements the `-admin` surface per `convention-client-project-structure`. ### Repo `ldraney/pal-enterprises` ### User Story As the platform owner (Lucas) I want an admin panel to view leads, promote them to clients, and manage client accounts So that I can onboard and support clients without touching the database directly ### Context Per `convention-client-project-structure`, every project gets an `-admin` surface. For pal-enterprises, this is the owner-only panel where Lucas manages the leads pipeline and client accounts. The `/admin` route already exists in the scaffold (`admin_controller.rb`, `admin/index.html.erb`) but needs full CRUD for leads and client management. This is the dogfooding instance — pal-enterprises-admin is where Lucas manages his own business, the same way Marcus uses westside-admin. ### File Targets Files to modify: - `app/controllers/admin_controller.rb` — CRUD actions for leads and clients - `app/views/admin/` — list, show, edit views for leads and clients - `config/routes.rb` — admin resource routes - `app/services/keycloak_client.rb` — Keycloak admin API integration for user creation on lead promotion Files NOT to touch: - `app/controllers/dashboard_controller.rb` — separate from admin ### Acceptance Criteria - [ ] `/admin` shows leads pipeline (new submissions, pending review) - [ ] Owner can view lead details (business name, name, logo, email) - [ ] Owner can promote a lead to client (triggers Keycloak user creation) - [ ] Owner can view all active clients with status - [ ] Only `owner` role can access `/admin` — clients get 403 - [ ] Per-client links to their `-docs` and `-admin` surfaces visible ### Test Expectations - [ ] Integration test: owner can access /admin - [ ] Integration test: client role is denied /admin access - [ ] Unit test: lead promotion creates Keycloak user - Run command: `bin/rails test` ### Constraints - Owner-only access enforced by role check, not just route hiding - Keycloak user creation on promote should use the admin API - Keycloak admin API credentials sourced from environment variables (KEYCLOAK_ADMIN_URL, KEYCLOAK_ADMIN_USER, KEYCLOAK_ADMIN_PASSWORD) — see k8s/dev.yaml secrets - Follow existing Rails patterns (Hotwire/Turbo, plain CSS per ~/ror-css-guide) - Depends on #10 (Remove Tailwind) completing first — all new views use plain CSS design tokens, not Tailwind ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `convention-client-project-structure` — the convention requiring this surface - `project-pal-enterprises`

forgejo_admin commented

2026-05-09 18:58:26 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-1187-2026-05-09

Ticket has good structure but multiple scope gaps prevent agent execution.

Blocking issues:

File targets claim admin_controller.rb and app/views/admin/ "already exist" -- they do not. Should say "create."
Lead model lacks business_name, logo, status fields referenced in AC. Migration needed.
No Client model exists. Architectural decision (Lead status enum vs. separate Client table) is unscoped.
Keycloak admin API integration (for lead promotion) does not exist in the codebase. Significant new infrastructure required.
No role-checking infrastructure (require_owner) exists. Session stores roles but nothing consumes them.
"Per-client links to -docs and -admin surfaces" -- no specification of how the system knows client surface URLs.

Traceability gaps:

No project-pal-enterprises project page in pal-e-docs
No arch-rails-app architecture note in pal-e-docs
convention-client-project-structure referenced in lineage does not exist in pal-e-docs

Decomposition needed: 6 AC across 4 distinct concerns (model expansion, role auth, views, Keycloak API). Exceeds 5-minute rule. Route to skill-decompose-ticket.

## Scope Review: NEEDS_REFINEMENT Review note: `review-1187-2026-05-09` Ticket has good structure but multiple scope gaps prevent agent execution. **Blocking issues:** - File targets claim admin_controller.rb and app/views/admin/ "already exist" -- they do not. Should say "create." - Lead model lacks business_name, logo, status fields referenced in AC. Migration needed. - No Client model exists. Architectural decision (Lead status enum vs. separate Client table) is unscoped. - Keycloak admin API integration (for lead promotion) does not exist in the codebase. Significant new infrastructure required. - No role-checking infrastructure (require_owner) exists. Session stores roles but nothing consumes them. - "Per-client links to -docs and -admin surfaces" -- no specification of how the system knows client surface URLs. **Traceability gaps:** - No `project-pal-enterprises` project page in pal-e-docs - No `arch-rails-app` architecture note in pal-e-docs - `convention-client-project-structure` referenced in lineage does not exist in pal-e-docs **Decomposition needed:** 6 AC across 4 distinct concerns (model expansion, role auth, views, Keycloak API). Exceeds 5-minute rule. Route to `skill-decompose-ticket`.