feat: add course lookup, ratings, and moderated comments

[SebastianBoehler]

Summary

Add course lookup and community ratings to StudyOS Agent. Students can search the shared StudyPlanner catalog by title or course number, use their locally loaded ALMA registrations as search shortcuts, and submit a 1–5 star rating with an optional moderated comment.

This rates courses—not the StudyOS agent or aggregated services.

Product behavior

• Add a dedicated Course ratings screen outside Settings.
• Search the public StudyPlanner catalog and show course number, title, term, and ECTS where available.
• Show locally derived “My courses” shortcuts; the enrollment list itself stays on-device.
• Group ratings longitudinally by normalized course number across semesters.
• Show average and count separately, plus published comments only.
• Let an installation create/update/delete one rating per course and report published comments.
• Clearly label ratings as pseudonymous community feedback, not verified enrollment reviews.

Architecture

• Flutter calls the containerized ratings API.
• The ratings API proxies public, read-only StudyPlanner catalog search because the current catalog endpoint does not expose browser CORS headers.
• Catalog responses are typed, size-limited, rate-limited, and held in a bounded five-minute in-memory cache.
• Search returns a server-issued normalized course rating ID and registers that course before ratings are accepted.
• SQLite stores registered courses, pseudonymous installation credentials, ratings/comments, reports, and moderation audit records.
• ALMA credentials, cookies, profiles, timetables, and enrollment lists are never sent to the hosted ratings service.

Moderation and operations

• Star ratings count immediately; optional comments start pending.
• Moderators can publish, reject, or remove comments with audited reasons.
• User reports feed the moderation queue.
• No third-party semantic moderation or per-comment API billing is required initially.
• Production still needs HTTPS, reverse-proxy limits, a moderation owner, retention/privacy notices, and tested backups.

Acceptance criteria

• Users can look up catalog courses and select one to rate.
• Local registered-course titles can start a catalog lookup without uploading the enrollment list.
• Ratings are stored per registered normalized course identity, not against the StudyOS agent.
• Users can create/update/delete a 1–5 rating with an optional bounded comment.
• Public reads include count, average, and published comments only.
• Users can report comments; moderators can review and audit actions.
• API validation, ownership, isolation, pagination, rate limits, cache bounds, migration behavior, and moderation are tested.
• SQLite/Compose backup, privacy, retention, and deployment guidance is documented.
• Human reviewers approve the UI and deployment policy before merge/release.

Out of scope

• verified enrollment/completion badges
• replies, threads, reactions, or rich text
• automated third-party moderation
• routing university credentials through the ratings service

[SebastianBoehler]

This is already a strong issue spec. I checked current main and the issue/PR list: there is no exact duplicate, but two missing foundations and one naming collision should be resolved before implementation.

Dependencies and overlap

• Canonical service identity: the repository does not currently have an aggregated service catalog with stable IDs. feat: StudyOS data and action capability contract #54 is the closest architectural overlap, but it defines assistant capability contracts rather than a service directory. Please name the source of truth for service_id and its lifecycle (rename, removal, alias/migration) before storing ratings.
• Trusted identity and roles: the current Flutter profile is local app state, not authentication that a hosted API can trust. Ownership, one-rating-per-user, reporting abuse controls, and moderator authorization need an issuer/token/role contract or a separately scoped auth dependency. A client-supplied pseudonymous ID is not sufficient.
• Existing feedback feature: flutter_app/lib/src/feedback_client.dart already uses FeedbackClient for sending app feedback as GitHub issues. That is functionally distinct, but the new code should use explicit names such as ServiceReviewClient, ServiceReview, and /service-reviews to avoid ambiguous models/imports.

Decisions needed

1. Service catalog: what exact catalog/API provides valid service_id values? May reviews remain readable after a service is retired, and who can add/rename IDs?
2. Authentication: which identity provider issues API-verifiable credentials, and how is the moderator role assigned/revoked? If no trusted identity exists yet, should v1 be read-only until that dependency lands rather than ship resettable device identity?
3. Publication policy: I recommend publishing star ratings immediately while every non-empty comment starts pending; deterministic flags can prioritize the queue, not decide publication. Is that the intended baseline?
4. Rating vs comment lifecycle: should a rejected/removed comment leave its numeric rating in the aggregate? I recommend modeling these independently so moderation of text does not silently change the score; deleting the user's whole review removes both.
5. Reports: does one report merely queue a review, or temporarily hide content? Avoid automatic hiding from a single report; define deduplication per reporter and a bounded reason enum.
6. Operations: who is the moderator/data controller, what response target is realistic, and where will the container, persistent volume, backups, and restore drill run?

Suggested first-release boundary

Keep the first slice to authenticated users, one review per (service_id, author_id), immediately published stars, pre-moderated plain-text comments, report submission, and a minimal moderator queue. Exclude anonymous writes, automated/LLM moderation, search, sorting/ranking beyond newest-first pagination, moderator UI analytics, and multi-instance deployment.

Consider splitting delivery into reviewable prerequisites/slices:

1. service catalog + trusted identity/role contract
2. API schema/migrations, aggregate reads, ownership, and moderation audit
3. Flutter read/write/report states
4. moderator queue plus backup/restore and launch-policy documentation

Acceptance-criteria refinements

• service_id validation uses the named catalog source; unknown and retired IDs have specified behavior.
• The API derives author_id and moderator privileges from a verified credential, never from request-body identity or a resettable device ID.
• Rating and comment publication states are separate; the aggregate inclusion rule is explicit and tested for pending, rejected, removed, and user-deleted comments/reviews.
• average and count come from the same eligible rating set, define rounding/precision, and return a documented empty state when count is zero.
• Create/update semantics are atomic (unique database constraint plus upsert or conflict handling), including concurrent duplicate submissions.
• Comment bounds are specified in Unicode characters and request bytes; whitespace-only comments normalize to no comment.
• Public DTOs never expose author IDs, internal reasons, reports, moderator identities, deleted text, or unpublished text.
• Report submission is authenticated, deduplicated per reporter/review, rate-limited, and cannot reveal whether another user already reported.
• Moderation transitions define allowed source/target states and idempotency; every privileged action records actor, reason, timestamp, and target without logging comment text unnecessarily.
• Cursor pagination has a deterministic tie-breaker (for example created_at DESC, id DESC) and bounded page size.
• Deleting one's review hides it immediately from reads and aggregates; backup expiry and hard-deletion timing are documented.
• API contract tests cover forged identity/role claims, cross-user edit/delete, concurrent upserts, report spam, aggregate leakage, and moderation transition conflicts.

Once the service-ID source, trusted auth/role mechanism, publication policy, rating/comment coupling, and operational owner are answered, this is ready to turn into implementation slices. Until then, starting the API would bake the riskiest assumptions into its data model and authorization boundary.