Skip to content

Docs/api improvements#99

Merged
raphael-frank merged 17 commits into
mainfrom
docs/api-improvements
Jul 2, 2026
Merged

Docs/api improvements#99
raphael-frank merged 17 commits into
mainfrom
docs/api-improvements

Conversation

@raphael-frank

@raphael-frank raphael-frank commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator

I extended and migrated our services to the API changes we discussed. These changes have been made:

  • Add role claim to token (list of all the role enums, client assumes most powerful)
  • Change Sport primary key to uuid (except path variables and post parameters)
  • All foreign keys returned should be as an object of id and name
  • Add attendees list from details also to event summary
  • Add rating field to feedback (include in summary)
  • Add report storage and endpoints
  • GET members/dashboard ()

Only review these changes, do NOT merge them, since I need to do some manual steps afterwards.

Summary by CodeRabbit

  • New Features

    • Added a personalized member dashboard with role-based views.
    • Introduced async report generation with saved member/team reports that can be viewed or deleted later.
    • Updated letter generation requests to use structured JSON inputs.
  • Bug Fixes

    • Switched sport links from names to IDs for more reliable sport management.
    • Added feedback ratings with validation.
    • Improved linked data display across events, finances, and dashboards.

raphael-frank and others added 9 commits June 27, 2026 11:22
Resolve TransactionEntity conflict by keeping the nullable creator_id
(this branch's ON DELETE SET NULL change in V3) over main's not-null
column.

Adapt main's finance implementation (#97) to this branch's regenerated
Reference-based finance contract: Transaction.member/creator and
Balance.member are now Reference{id,name} instead of String. Resolve
member display names via the member schema (firstName/lastName added to
the read-only finance MemberEntity), mirroring the feedback/event
services. Creator references are null-safe to match the nullable
creator_id. Finance tests updated to assert against the Reference shape.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@raphael-frank raphael-frank self-assigned this Jun 30, 2026
@raphael-frank raphael-frank added infra Issue regarding the infrastructure or CICD pipeline server Issue regarding a server service labels Jun 30, 2026
coderabbitai[bot]

This comment was marked as spam.

@raphael-frank

Copy link
Copy Markdown
Collaborator Author

I also refined the letter service endpoints.

@AET-DevOps26 AET-DevOps26 deleted a comment from coderabbitai Bot Jun 30, 2026

@f-s-h f-s-h left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@AET-DevOps26 AET-DevOps26 deleted a comment from coderabbitai Bot Jun 30, 2026
coderabbitai[bot]

This comment was marked as spam.

@AET-DevOps26 AET-DevOps26 deleted a comment from coderabbitai Bot Jun 30, 2026
@FadyGergesRezk

Copy link
Copy Markdown
Collaborator

There are minor misalignments, but I will handle them from the client side.

@coderabbitai

coderabbitai Bot commented Jun 30, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This PR migrates organization sports from name-based to UUID-based identity across all services (event, feedback, finance, organization, member), introducing a shared Reference schema for linked entities. It adds a role-discriminated member dashboard, an async persisted GenAI report system with PostgreSQL provisioning, Keycloak-based membership role synchronization, feedback ratings, cascade/set-null FK migrations, per-service hello route prefixing, and corresponding web client and test updates.

Changes

Sport UUID migration, Reference schema, dashboard, async reports, role sync

Layer / File(s) Summary
OpenAPI spec and generated API/TS types
api/openapi.yaml, web-client/src/api.ts, api/scripts/gen-*.sh
Sport path param renamed to sport_id; adds Reference, Dashboard, Report, MailRequest/PdfRequest schemas; feedback gets rating; async report endpoints replace sync one.
Database migrations
services/*/db/migration/*.sql
Adds UUID PK to organization.sports, backfills sport_id FKs, converts several FKs to ON DELETE CASCADE/SET NULL, adds bounded rating column.
Organization service sport UUID refactor
services/spring-organization/.../{entity,repository,service,controller}/*, tests
Entities/repositories/services move from sport_name to sportId UUID; directors mapped to Reference; controller endpoints take UUID sportId.
Keycloak role sync
services/spring-organization/.../service/{KeycloakRoleService,MemberRoleSyncService}.java, infra/keycloak/*, infra/helm/**/realm-config.json, values
New services reconcile Keycloak client roles post-commit based on trainer/director/trainee membership; realm configs add org-role-sync service account and member_roles claim mapper.
Event service sport UUID + Reference responses
services/spring-event/.../{entity,repository,service,converter}/*, tests
SportEventEntity PK moves to sportId; new shadow entities resolve member/sport/team names into Reference objects for event/attendee responses.
Feedback & finance Reference/rating propagation
services/spring-feedback/**, services/spring-finance/**, tests
Feedback gains validated rating; feedback/transaction/balance responses use Reference; finance director/team lookups move from sport name to sport id.
Async reports system
services/py-genai-helper/*, infra/postgres/*, infra/docker-compose*.yml, infra/helm/**
Provisions reports Postgres schema/user; adds db.py/reports.py persistence and background generation; Flask endpoints for generate/list/get/delete reports with auth checks.
Member dashboard feature
services/spring-member/.../{entity,repository,service,controller}/*, tests
New shadow entities/repositories aggregate cross-schema data; DashboardService builds role-specific dashboards; MemberController exposes GET /members/dashboard via MembersApi.
Hello route prefixing
services/spring-*/.../HelloController.java, tests
Each service's hello endpoint moves under a service-specific path prefix.
Web client auth/query updates
web-client/src/features/**, web-client/src/types.ts, web-client/src/__tests__/*
AuthUser.roles populated from member_roles claim; sport query hooks switch from name to id keys.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant app.py
  participant reports.py
  participant db.py
  participant PostgreSQL

  Client->>app.py: POST /reports/member/{id}
  app.py->>app.py: authorize (self or admin)
  app.py->>reports.py: trigger_member_report(member_id, token)
  reports.py-->>app.py: daemon thread started
  app.py-->>Client: 202 Accepted
  reports.py->>reports.py: generate_member_report_text()
  reports.py->>db.py: insert_member_report(member_id, text)
  db.py->>PostgreSQL: INSERT INTO reports.member_reports
  Client->>app.py: GET /reports/{report_id}
  app.py->>db.py: get_report(report_id)
  db.py->>PostgreSQL: SELECT member_reports / team_reports
  db.py-->>app.py: dict with kind
  app.py-->>Client: 200 Report
Loading
sequenceDiagram
  participant OrgService
  participant MemberRoleSyncService
  participant KeycloakRoleService
  participant KeycloakAdminAPI

  OrgService->>MemberRoleSyncService: scheduleSync(memberIds)
  MemberRoleSyncService->>MemberRoleSyncService: afterCommit or immediate
  MemberRoleSyncService->>MemberRoleSyncService: check trainer/director/trainee repos
  MemberRoleSyncService->>KeycloakRoleService: reconcile(memberId, desiredRoles)
  KeycloakRoleService->>KeycloakAdminAPI: POST /token (client_credentials)
  KeycloakAdminAPI-->>KeycloakRoleService: access_token
  KeycloakRoleService->>KeycloakAdminAPI: GET role-mappings for user
  KeycloakRoleService->>KeycloakAdminAPI: POST add roles / DELETE remove roles
Loading

Possibly related PRs

  • AET-DevOps26/team-devoops#97: The finance-service Reference-based transaction/balance mapping and director-managed lookups in this PR build directly on the transaction/balance CRUD logic introduced in that PR.

Suggested labels: enhancement

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 11.59% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check ❓ Inconclusive The title is too generic to clearly describe the API and schema changes in this PR. Rename it to mention the main change, e.g. "Migrate API to UUID sports IDs and add dashboard/report endpoints".
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/api-improvements

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
services/spring-member/src/main/java/tum/devoops/memberservice/controller/MemberController.java (1)

51-58: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Return the actual member resource URI in Location.

After the route migration, POST /members creates a resource retrievable at /members/{id}, but the response currently advertises /{id}.

🐛 Proposed fix
-            return ResponseEntity.created(URI.create("/" + member.getId())).body(member);
+            return ResponseEntity.created(URI.create("/members/" + member.getId())).body(member);
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@services/spring-member/src/main/java/tum/devoops/memberservice/controller/MemberController.java`
around lines 51 - 58, The MemberController.createMember response is setting an
incorrect Location header for newly created members. Update the URI built in
createMember so it points to the actual member resource path under /members/{id}
instead of just /{id}, keeping the rest of the ResponseEntity.created flow
unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In
`@services/spring-member/src/main/java/tum/devoops/memberservice/controller/MemberController.java`:
- Around line 51-58: The MemberController.createMember response is setting an
incorrect Location header for newly created members. Update the URI built in
createMember so it points to the actual member resource path under /members/{id}
instead of just /{id}, keeping the rest of the ResponseEntity.created flow
unchanged.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 10adb7af-32ba-450a-aa37-d69e2087e9c6

📥 Commits

Reviewing files that changed from the base of the PR and between f7a94cf and 3bafff7.

📒 Files selected for processing (3)
  • services/spring-member/src/main/java/tum/devoops/memberservice/config/SecurityConfig.java
  • services/spring-member/src/main/java/tum/devoops/memberservice/controller/MemberController.java
  • services/spring-member/src/test/java/tum/devoops/memberservice/controller/MemberControllerTest.java

f-s-h and others added 2 commits July 1, 2026 15:23
MemberService referenced these classes but they were never committed, breaking CI compilation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@raphael-frank raphael-frank merged commit 70055b1 into main Jul 2, 2026
18 checks passed
@raphael-frank raphael-frank deleted the docs/api-improvements branch July 2, 2026 11:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

infra Issue regarding the infrastructure or CICD pipeline server Issue regarding a server service

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants