refactor: Split serializers into Read/Write classes per resource

[Nickatak]

refactor: Split serializers into Read/Write classes per resource

Branch: refactor/serializers-read-write stacked on refactor/views-explicit (#740), which is stacked on docs/add-docstrings (#739), which is stacked on the modernization chain (#734-#738). Retarget chain when each parent lands.

This is the third pattern-establishment PR. With docstring conventions locked in by #739 and view shape locked in by #740, this PR locks in the serializer shape: each resource gets separate XxxReadSerializer and XxxWriteSerializer classes when both shapes are needed; read-only resources have only a Read class.

---

Summary

• Renames the existing read-only XxxSerializer classes to XxxReadSerializer.
• Splits OpportunitySerializer (the only resource with write endpoints) into OpportunityReadSerializer + OpportunityWriteSerializer.
• Wires OpportunityViewSet.get_serializer_class() to dispatch by action.
• Updates the FBVs in views.py to import the renamed classes.
• Documents the convention in docs/developer/backend.md (new Serializer shape section) and updates the serializer template in backend-docstring-style.md.

4 files changed, 160 insertions, 57 deletions. Two commits.

#	Subject
1	refactor: Split serializers into Read/Write classes per resource
2	docs: Document serializer shape convention

Why this shape

A single ModelSerializer per resource splits the input/output contract across two layers. The serializer says "here are the fields and their types"; the view says "but you can only call this with GET" (or "POST is gated to PMs"). A reader of serializers.py cannot tell which fields are writable, which are computed-on-read, or whether the class supports writes at all. That information lives in the view, the permissions, and the docstring — not in the serializer.

The pain is clearest where read and write semantics legitimately diverge. OpportunitySerializer.created_by is a stringified email on read but the view stamps the FK from request.user on write — the same field has different semantics for reads and writes. The single class either does both behaviors awkwardly (current state, with ReadOnlyField plus a view-layer perform_create override) or one of the behaviors is implicit (the writable subset of fields isn't documented anywhere except by elimination).

After this PR, each resource concentrates its shape contract back at the serializer. Read responses are described by the Read class; accepted writes are described by the Write class. Future changes to write-side behavior (validation, computed-on-write fields, accepted field set) land in the Write class only — read responses are not affected, and the change is atomic.

The convention

Resource state	Serializer classes
Read-only (no write endpoint exists)	XxxReadSerializer only
Read + write	XxxReadSerializer and XxxWriteSerializer

Auto-managed fields (id, created_at, updated_at) and request-stamped fields (Opportunity.created_by, set from request.user by the view) are absent from XxxWriteSerializer.Meta.fields rather than included with read_only=True. Absence is the contract: if the field doesn't appear in Meta.fields, the client cannot supply it on write.

OpportunityViewSet (the one ModelViewSet in the codebase) dispatches via:

def get_serializer_class(self):
    if self.action in ("list", "retrieve"):
        return OpportunityReadSerializer
    return OpportunityWriteSerializer

FBVs reference the right serializer directly — they only do one thing, so they only ever need one class.

What's not in this PR

Following the same pure-pattern rule as #739 and #740:

• The broken opportunities field on CustomUserReadSerializer (BUG-001) is left as-is. Flagged inline in the docstring; the bug-fix PR drops the field.
• The dead SkillMatrixSerializer (BUG-002) is left as-is. Not split into Read/Write because it has no consumers; the docstring is updated to note that it should conform to the new convention if/when it's wired up. The cleanup PR drops it.
• The OpportunityPermission PATCH gap (BUG-003) is unchanged here. PATCH is still 403'd; the permission-pattern PR resolves it.
• No empty XxxWriteSerializer stubs for read-only resources. The convention is "you have both classes when you have both behaviors," not "every resource pre-stubs both."

Test plan

Shape-only change; no behavior changes intended.

• ruff check ctj_api/ backend/ clean
• ruff format --check ctj_api/ backend/ clean
• mypy ctj_api/ backend/ clean (run with django-stubs)
• All 9 existing backend tests pass without modification

The integration tests don't import serializer classes by name (they exercise the API surface), so the renames are transparent to the test suite.

Follow-ups (not blocking)

The remaining pattern-PR axes:

• Test shape — the 21 tests live in one big APIBasicTests class; lock in per-resource organization.
• URL routing convention — camelCase /api/communityOfPractice/ is inconsistent with the snake_case Pythonic shape; needs a decision (and a frontend impact check).
• Permission class shape — OpportunityPermission branches both methods; UserDetailPermission only has_object_permission; lock in a convention.
• Error envelope — api_not_found defines a JSON error shape that nothing else follows; either lift it to a project-wide convention or document why the catch-all is special.

The bug-fix and cleanup PRs from #739 are still queued.

[RSkuma]

Decision approved, discussed at 5/7/26 meeting