feat: Opportunities - reshape model + ship the listing surface

[Nickatak]

feat/opportunities: dissolve Project, reshape Opportunity, ship the listing surface

Off develop. #752 (feat/auth) and #753
(feat/navbar-trim-org-links) merged 2026-06-01; this PR is eight
commits directly on top of the current develop tip, no stacked-PR
coupling.

Summary

Two related shifts in one PR plus a small dev-tooling rider: the
backend reshape and the volunteer-facing /opportunities browse
surface wired to the result.

Backend — applied on top of the inherited Opportunity / Project /
Role layer:

• Project dissolves entirely. project_name moves onto
  Opportunity as free-text (deliberately weak as a filter key);
  meeting_times JSON moves onto Opportunity; the
  Opportunity.project FK, ProjectSerializer, ProjectViewSet,
  /api/projects/ URL, admin registration, and projects test suite
  are all removed. CommunityOfPractice / role-taxonomy is
  untouched here — that's the next PR.
• Opportunity.overview (Role Overview, now owned by Opportunity)
  is added; Role.overview / Role.responsibilities are backed
  out. Experience level stays on Opportunity as
  min_experience_required but per the filter spec is no longer a
  filter dimension (still displayed).
• Public-read is dropped across the board.
  OpportunityPermission no longer green-lights anonymous
  SAFE_METHODS; this closes the SAFE_METHODS PATCH gap (BUG-003)
  in the same change.
• Status enum: "on hold" → "on_hold"; default flips to
  "draft". OpportunityViewSet.get_queryset() filters the list
  action to status="open" so the volunteer-facing catalog only
  ever surfaces open roles; retrieve / update / destroy still
  operate against the full set (PM CMS reads off retrieve).
• OpportunityReadSerializer adds two derived display-only fields:
  role_title (from role.title) and skill_names: list[str]
  (alphabetically resolved from skills_required_matrix).
  CustomUserReadSerializer adds the parallel skill_names for the
  current user. Both save the listing card from N+1 lookups; the
  underlying FK UUIDs stay on the wire for matching consumers.
• CustomUser.meeting_availability JSON shape now documented:
  [{"day": "Wed", "start": "17:00", "end": "21:00"}, ...],
  parallel to Opportunity.meeting_times minus the team key.
• Migration 0002_dissolve_project_reshape_opportunity performs
  the reshape and backfills "on hold" rows via RunPython;
  migration accounts.0003 carries the new help_text on
  meeting_availability.
• Cleanup riders: Opportunity.min_experience_required drops
  null=True / default="" (closes DJ001 from Bump dependencies + replace lint stack #737's deferred
  items); dead SkillMatrixSerializer removed (BUG-002).

Frontend — the /opportunities browse surface, sign-in-gated,
zero hardcoded data:

• Two-column page: sticky left filter sidebar (Figma-shaped:
  Filters (N) count, Clear all, active-filter chips,
  collapsible <details> sections per filter), results column on
  the right with an N results count.
• Three filters: Availability ON/OFF (matches against
  the user's meeting_availability), Project free-text substring,
  Skills OFF / Partial Match (≥30% overlap on skill_names). Pure
  predicate code in features/opportunities/lib/filters.ts.
• Card layout: role title + project name in the main title row
  (Role Title · Project), experience + chips below, prose
  sections, right rail with Meeting Times and Skills. No status
  badge, no posted date, no logo, no "create account" CTA —
  see Decisions baked in.
• Wired to the live API: opportunitiesApi.list() fetches the
  open opportunities, the auth context (useAuth()) provides the
  current user. State branches: auth loading, anonymous (sign-in
  prompt linking /login), fetch in flight, fetch error, zero
  results. No hardcoded sample data anywhere in the repo.

Dev tooling — make db-seed (new) runs a seed_dev
management command that idempotently creates one PM/admin user
(dev@example.com / password123!; isProjectManager + is_staff

• is_superuser set so the same account also drives Django admin)
  and three open opportunities. Dev-only; never imported by views or
  tests. Exempt from the no-hardcoded-data rule (test fixtures and
  dev-only seed scripts are carved out). See
  docs/developer/installation.md for credentials and
  docs/developer/quickstart-guide.md for the make-target entry.

Commits

Eight commits.

1. feat: Dissolve Project, reshape Opportunity for sign-in-only listings (19 files; +972 / −296; backend reshape + migration +
   initial frontend listing scaffold).
2. feat: Add filter bar to /opportunities (Availability, Project, Skills) (6 files; +343 / −6; client-side filter state, pure
   predicate code in lib/filters.ts).
3. feat: Restructure /opportunities filter UI to match Figma layout (4 files; +335 / −94; two-column grid with sticky
   sidebar, Filters (N) header + Clear all, active-filter chips,
   collapsible <details> sections, N results count).
4. refactor: Promote project name into the card title row, drop status badge (3 files; +23 / −81; project name moves to the
   main title row, status badge removed - the listing surface only
   ever shows open opportunities by design).
5. refactor: Drop posted-date from the card; reframe as project-role catalog (3 files; +13 / −21; this surface
   replaces HfLA's current GitHub-listed project-role catalog,
   so the "Posted: ..." framing is wrong - volunteers join an
   open role, they don't apply to a posting).
6. feat: Resolve display-only fields on Opportunity + User; filter list to open (8 files; +215 / −2; role_title +
   skill_names derived fields on both Read serializers,
   queryset filter on the list action, meeting_availability
   shape documented, tests).
7. feat: Wire /opportunities to live API; delete sample-data scaffolding (9 files; +283 / −260; opportunitiesApi client,
   User type updates, listing page becomes a real fetching
   component with loading / error / unauthenticated states,
   sample data files deleted).
8. feat: Add seed_dev management command + make db-seed for dev fixtures (6 files; +160 / −1; idempotent seed for one
   PM/admin user + three open opportunities so /opportunities
   renders on a fresh DB without hand-building the dependency
   graph through admin).

Decisions baked in

• The browse surface is a project-role catalog, not a job feed.
  The page replaces HfLA's current GitHub-listed project-role
  catalog - volunteers join an open project role; they don't apply
  to a recent posting. That framing drives: sign-in required
  (you're joining, not browsing), only open roles ever appear (no
  status badge needed), no posted-date metadata, no
  create-account CTA. Worth holding the line on: small UI choices
  ("Apply" buttons, "New this week" sort, etc.) follow from this
  framing and re-introduce job-board patterns we deliberately cut.
• No hardcoded data in committed code. Listing data comes off
  /api/opportunities/; the current user comes off the auth
  context. No sampleX.ts files; the only "data" in the repo are
  test fixtures (in tests/ paths) and the dev-only seed script
  (not imported by views or tests).
• Project dissolves into Opportunity, no FK. Everything
  belongs to the Opportunity — no Project data at all. Project
  identity is a string on Opportunity, a deliberately weak filter
  key. PeopleDepot will be the eventual source of truth for
  project metadata; no people_depot_project_id on Opportunity
  yet (out of scope, comes when PeopleDepot integration lands).
• Role keeps its model + FK. The role-taxonomy drop is the
  next PR (CommunityOfPractice / Role.community_of_practice /
  Skill.communities_of_practice /
  CustomUser.community_of_practice / frontend CoP picker).
  Leaving Role intact here keeps the PR scoped.
• Sign-in required, hard. SAFE_METHODS no longer grants
  anonymous access. Model docstrings + any "anonymous-visible"
  framing in the README will need a follow-up sweep — caught a
  few; flagged the rest as a follow-up.
• List action server-filters to status="open". Drafts,
  on-hold, filled, and closed opportunities never appear in the
  browse list — the listing surface is the volunteer-facing
  catalog. Retrieve / update / destroy still hit the full set
  so PMs can edit non-open records via the upcoming CMS.
• Display fields resolved at the serializer. role_title
  and skill_names are derived on the wire so the card can
  render with one request, not one + N. The underlying
  role: UUID / skills_required_matrix: UUID stay on the wire
  for matching-algorithm consumers.
• overview belongs to Opportunity, not Role. The Figma's
  Role Overview prose travels with the opportunity, not the role.
  Backing this off Role lets the role dataset stay generic.
• Skill partial-match threshold = 30%. Opportunities with no
  tagged skills always pass — we have no signal to score them and
  excluding them would hide listings just because their PM hasn't
  tagged skills yet.

Questions for review

1. project_name required on publish? Currently blank=True
   (draft-friendly). Figma always shows a project name; we may
   want it required once status flips to "open". Proposing:
   keep blank=True at the model layer, enforce on the publish
   transition in serializer-level validation — but happy to make
   it column-level required if you'd rather.
2. Catalog endpoints — auth-gated too? /api/opportunities/
   requires sign-in. The catalog endpoints (/api/roles/,
   /api/skills/, /api/communities-of-practice/) are still
   public (AllowAny). The "require sign-ins" direction here was
   about listings specifically; scope is undecided for catalog.
   Easy to flip if you want a flat policy.
3. body label. With Project dissolved, the Figma's "About
   the Project" prose now lives in Opportunity.body. The listing
   card labels that section "About the Project" — reads slightly
   oddly (it's opportunity-authored now). Keep, or rename to
   "About this opportunity"?

Test plan

• Backend: make local-test-backend → 45/45 pass (39 prior +
  6 new for role_title / skill_names / list-status filter /
  /api/auth/me skill_names).
• Backend lints: ruff check clean; mypy clean (36 source
  files); bandit -c pyproject.toml -r ctj_api/ accounts/ backend/ → 0 findings.
• Migrations: makemigrations --check reports no drift after
  both new migrations (ctj_api.0002 + accounts.0003).
• Frontend: npx vitest run → 37/37 pass (3 pre-existing
  skips); lint:types / lint:css / lint:dead (knip) /
  eslint clean.
• /opportunities returns 200; anonymous sees the sign-in
  prompt; authenticated user sees the filter sidebar + result
  list (or empty state).
• Anonymous GET /api/opportunities/ returns 403 with the
  not_authenticated envelope code.
• Browser walkthrough: sign in, see the listing populated;
  apply each filter and confirm results adjust; clear all;
  sign out and confirm the sign-in prompt returns; PM admin
  still CRUDs opportunities via Django admin end-to-end.

Follow-ups (out of scope for this PR)

• CoP / role-taxonomy deletion. CommunityOfPractice,
  PracticeAreas, /api/communities-of-practice/,
  Role.community_of_practice, Skill.communities_of_practice,
  CustomUser.community_of_practice, frontend copData.ts +
  qualifier CoP picker. Will be its own PR stacked on this one.
• Opportunity detail + PM CMS pages (/opportunities/<id>,
  /opportunities/new, /opportunities/<id>/edit). PM-only,
  reads off the retrieve action (which intentionally isn't
  filtered by status).
• Filter unit tests. Predicates in lib/filters.ts are pure
  and unit-testable; tests come with the broader opportunities
  test suite (queued behind detail + CMS).
• N+1 on skill_names. The current implementation issues one
  extra Skill.objects.filter per opportunity in the list
  response. Acceptable at current scale (open listings are
  small); revisit with a prefetch or denormalization when the
  catalog grows.
• Docstring / README "anonymous-visible" sweep. A small
  number of model + README hints still describe browse as
  public-readable; one more pass after the auth-gating posture
  settles.
• Status admin polish. The status dropdown in Django admin
  still shows the old labels in some places; tidy after the
  "on_hold" rename settles in.
• Seed script revisits next PR. The seed touches the CoP /
  Role taxonomy that's being removed in the follow-up PR; it
  rewrites alongside the deletion. Carried in this PR so the
  surface it tests is usable on a fresh DB today.