fix(spp_graduation): improve code quality, UX, tests, and documentation

[gonzalesedwin1123]

Summary

• Add state transition guards with multi-record safety on all workflow actions (action_submit, action_approve, action_reject, action_reset_draft)
• Add validation constraints: score range (0–1) on criteria responses, weight > 0 on criteria
• Restructure assessment form to 4-tab workflow entity pattern (Overview, Criteria Responses, Recommendation, History) with alert banners for submitted/rejected states
• Expose evidence_attachment_ids in criteria response views (inline list + popup form)
• Add kanban progressbar, graph/pivot views, pathway search view, and accessibility fixes
• Rename is_requires_assessment/is_requires_approval to is_assessment_required/is_approval_required
• Remove redundant record rules that duplicated ACL permissions
• Expand test coverage from ~20 to 40 tests (state guards, constraints, monitoring end date, security-scoped workflows)
• Add comprehensive UI testing guide (readme/USAGE.md) with 10 QA test sections
• Update readme/DESCRIPTION.md to reflect all changes and clarify score vs is_met design

Test plan

• All 40 unit tests pass (./scripts/test_single_module.sh spp_graduation)
• Linting passes (ruff, ruff-format, prettier)
• Code review by staff engineer agent — critical issues addressed
• UX review — workflow entity pattern, accessibility, search/filter improvements
• Module verification — installs cleanly, all data files load, no warnings
• Manual QA walkthrough using readme/USAGE.md test plan

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the spp_graduation module by improving code quality, user experience, testing, and documentation. It introduces robust workflow state management with validation, refines the assessment process with a new multi-tab UI and evidence handling, and expands data visualization options. The changes also include renaming key fields for clarity, streamlining security rules, and substantially increasing test coverage to ensure reliability and maintainability.

Highlights

• Workflow State Management: Added state transition guards with multi-record safety on all workflow actions (submit, approve, reject, reset draft) to ensure assessments follow a defined lifecycle.
• Validation Constraints: Implemented validation to enforce a score range of 0-1 on criteria responses and ensure criteria weights are greater than zero.
• User Interface Enhancements: Restructured the assessment form into a 4-tab workflow (Overview, Criteria Responses, Recommendation, History) with alert banners for submitted/rejected states, and exposed evidence attachment IDs in criteria response views.
• Data Visualization and Navigation: Introduced a kanban progress bar, graph and pivot views for assessments, and a pathway search view, alongside general accessibility improvements.
• Field Renaming and Clarity: Renamed is_requires_assessment and is_requires_approval fields to is_assessment_required and is_approval_required for improved clarity and consistency.
• Security Streamlining: Removed redundant record rules that duplicated existing Access Control List (ACL) permissions, simplifying the security configuration.
• Test Coverage Expansion: Significantly expanded test coverage from approximately 20 to 40 tests, including new tests for state guards, constraints, monitoring end dates, and security-scoped workflows.
• Documentation Updates: Added a comprehensive UI testing guide (readme/USAGE.md) with 10 QA test sections and updated the main module description (readme/DESCRIPTION.md) to reflect all changes and clarify the score vs. is_met design.

Changelog

• spp_graduation/manifest.py
  • Updated the Python external dependency name from dateutil to python-dateutil.
• spp_graduation/data/graduation_data.xml
  • Renamed boolean fields is_requires_assessment to is_assessment_required and is_requires_approval to is_approval_required in default pathway data.
• spp_graduation/models/graduation_assessment.py
  • Imported relativedelta, _, UserError, and ValidationError.
  • Added _check_company_auto = True to GraduationAssessment.
  • Added check_company=True to pathway_id field.
  • Removed assessment_date from _compute_name dependencies.
  • Implemented state transition guards and multi-record safety for action_submit, action_approve, action_reject, and action_reset_draft methods.
  • Added _check_score_range constraint to GraduationCriteriaResponse to ensure scores are between 0 and 1.
  • Updated evidence_attachment_ids field with a specific relation name.
• spp_graduation/models/graduation_criteria.py
  • Imported _, api, and ValidationError.
  • Added _check_weight_positive constraint to ensure criteria weight is greater than zero.
• spp_graduation/models/graduation_pathway.py
  • Added _check_company_auto = True.
  • Renamed is_requires_assessment to is_assessment_required and is_requires_approval to is_approval_required.
  • Removed default=0 from criteria_count field definition.
• spp_graduation/readme/DESCRIPTION.md
  • Updated the module description to reflect new capabilities, models, configuration steps, UI locations, security groups, and extension points.
  • Clarified the distinction between score and is_met fields.
• spp_graduation/readme/USAGE.md
  • Added a new comprehensive UI testing guide with 10 detailed QA test sections.
• spp_graduation/security/graduation_rules.xml
  • Removed redundant record rules for spp.graduation.pathway and spp.graduation.criteria models, as ACL permissions are now sufficient.
• spp_graduation/tests/test_assessment.py
  • Added imports for date, relativedelta, UserError, and ValidationError.
  • Updated setUpClass to include post_graduation_monitoring_months in pathway creation.
  • Added extensive tests for state transition guards, multi-record workflow actions, score range constraints, and monitoring end date computation.
  • Refactored existing tests for clarity and expanded coverage.
• spp_graduation/tests/test_graduation_security.py
  • Removed the explicit name field from assessment creation in tests, relying on computed names.
  • Added tests to verify user and manager permissions for submitting, approving, and rejecting assessments.
• spp_graduation/tests/test_pathway.py
  • Added import for ValidationError.
  • Added tests for _check_weight_positive constraint on criteria.
  • Added tests to verify default values for renamed boolean fields in GraduationPathway.
• spp_graduation/views/graduation_assessment_views.xml
  • Introduced a new form view for GraduationCriteriaResponse for popup editing.
  • Enhanced the assessment list view with state-based decorations and optional column visibility.
  • Updated the kanban view to include a progress bar and improved card layout with badges and icons.
  • Refactored the assessment form view into a 4-tab structure (Overview, Criteria Responses, Recommendation, History) and added alert banners for submitted/rejected states.
  • Integrated many2many_binary widget for evidence_attachment_ids in criteria responses.
  • Added graph and pivot views for assessment data analysis.
  • Updated view_mode for assessment actions to include new graph and pivot views.
• spp_graduation/views/graduation_pathway_views.xml
  • Added a new search view for graduation pathways with filters for positive/negative exit and archived status.
  • Updated the pathway list view to show criteria_count and made code, is_assessment_required, is_approval_required, post_graduation_monitoring_months optional.
  • Improved the pathway form view layout, renamed fields, and updated the criteria list to include description as an optional hidden field.

Activity

• No specific activity (comments, reviews, progress updates) was provided in the context for this pull request.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.43%. Comparing base (4854031) to head (26e39d5).

Additional details and impacted files

@@            Coverage Diff             @@
##             19.0      #96      +/-   ##
==========================================
+ Coverage   70.39%   70.43%   +0.03%     
==========================================
  Files         674      674              
  Lines       37005    37031      +26     
==========================================
+ Hits        26051    26083      +32     
+ Misses      10954    10948       -6     

Flag	Coverage Δ
spp_base_common	90.26% <ø> (ø)
spp_case_graduation	97.77% <ø> (ø)
spp_graduation	99.24% <100.00%> (+5.79%)	⬆️
spp_programs	45.51% <ø> (ø)
spp_security	66.66% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
spp_graduation/__manifest__.py	0.00% <ø> (ø)
spp_graduation/models/graduation_assessment.py	100.00% <100.00%> (+8.95%)	⬆️
spp_graduation/models/graduation_criteria.py	100.00% <100.00%> (ø)
spp_graduation/models/graduation_pathway.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Code Review

This pull request significantly enhances the graduation management module by refactoring boolean fields to is_assessment_required and is_approval_required across models, data, and views, and correcting a dependency name. The assessment workflow now includes robust state transition checks with UserError and supports multi-record operations, alongside new validation constraints for scores (0-1) and positive weights. Multi-company support was integrated into GraduationAssessment and GraduationPathway models, leading to simplified security rules. UI/UX improvements include a redesigned assessment form with alert banners and tabbed organization, new Kanban, Graph, and Pivot views for data visualization, and enhanced list view decorations. A dedicated form view for criteria responses was added to manage evidence attachments. Finally, a comprehensive UI testing guide (USAGE.md) was introduced, and extensive unit tests were added or updated to cover the new features, workflow logic, and security rules.