We need to create a new WordPress plugin for the PHSG site called:

**PHSG Reporting Review & Recommendations**

The goal is to give the client admin-facing reports and review tools around donations, membership dues, member rosters, and giving history.

This is a Bedrock/Roots WordPress project using Composer-managed plugins. The site includes WooCommerce, WooCommerce Memberships, WooCommerce Subscriptions, Event Tickets/Event Tickets Plus, ACF Pro, and existing FYD plugins including donation receipts and membership UX plugins. Before building anything, inspect the existing codebase for:

* WooCommerce order/payment structure
* WooCommerce Memberships usage
* WooCommerce Subscriptions usage
* Existing `donation-receipts` plugin behavior
* Existing `phsg-membership-account-ux` plugin behavior
* Any custom fields, order meta, user meta, membership plan IDs, donation product IDs, or dues-related products already in use

Do not make assumptions about donation or dues data if the existing plugins already define the source of truth.

Create the new plugin in the appropriate app plugin directory, likely:

`web/app/plugins/phsg-reporting-review-recommendations/`

Use a clean, maintainable plugin structure. Avoid editing vendor/core/plugin package files unless absolutely necessary. If the repo has an existing FYD plugin structure or namespace convention, follow that pattern.

## Plugin Requirements

Create an admin-only reporting interface titled:

**Reporting Review & Recommendations**

The admin UI should be accessible only to authorized admins. Use an appropriate capability such as `manage_woocommerce` or `manage_options`, depending on existing project conventions.

Add the reporting screen either under WooCommerce, Tools, or a PHSG/FYD admin menu if one already exists. Choose the location that best matches the existing project.

The report area should include the following sections/tabs:

1. **Lifetime Donations by Member / Donor**
2. **Annual & Cumulative Giving Reports**
3. **Monthly Membership Roster Cross-Check**
4. **Members Who Have Not Paid Dues**
5. **Review & Recommendations**

## 1. Lifetime Donations by Member / Donor

Build a report that shows lifetime donation totals grouped by donor.

The grouping logic should support both logged-in members and guest donors:

* Prefer `user_id` / WooCommerce customer ID when available.
* Fall back to normalized billing email when no user account exists.
* Include donor name, email, user/member link if available, first donation date, most recent donation date, donation count, and lifetime donation total.
* Include guest donors who do not have a WP user account.
* Avoid double-counting orders, refunds, or non-donation line items.
* Exclude failed, cancelled, pending, trashed, or refunded orders unless there is a clear existing business rule that says otherwise.
* Use completed/processing orders by default unless the existing donation receipt plugin defines a better rule.
* Subtract refunded amounts where applicable.

Add filters:

* Date range
* Donor/member search
* Member status if available
* Minimum lifetime giving amount
* Include/exclude guest donors
* Export CSV

## 2. Annual & Cumulative Giving Reports

Build a report that can show giving totals by year and cumulative totals.

The admin should be able to choose a year and see:

* Donor/member name
* Email
* Member status
* Annual giving total for selected year
* Lifetime giving total
* First donation date
* Most recent donation date
* Donation count for selected year
* Lifetime donation count

Also include summary cards:

* Total donations for selected year
* Number of unique donors
* Number of member donors
* Number of guest donors
* Average donation amount
* Top donor amount
* Cumulative lifetime giving total across all donors

Add filters:

* Year
* Date range override
* Member status
* Minimum annual giving amount
* Include/exclude guest donors
* Export CSV

## 3. Monthly Membership Roster Cross-Check

Build a monthly roster review tool that helps admins compare active members against paid dues / subscription/order activity.

The report should allow selecting a month and year.

For the selected month, show:

* Member name
* Email
* User ID
* Membership plan
* Membership status
* Membership start date
* Membership expiration/end date if applicable
* Related subscription status if applicable
* Most recent dues/payment order
* Payment date
* Payment amount
* Whether dues/payment appears current for the selected month
* Notes/reasoning column explaining why the row was flagged or considered current

The logic should inspect WooCommerce Memberships and WooCommerce Subscriptions first. If memberships are not subscription-backed, inspect WooCommerce orders/products that represent dues.

Important: determine the actual dues products, membership plans, and payment relationships from the existing codebase/data patterns. Do not hard-code IDs unless they are already defined in config/constants. If IDs are needed, add a small settings section or constants with clear comments.

Add statuses such as:

* Current
* Missing payment
* Expired membership
* Cancelled subscription
* On hold subscription
* No linked payment found
* Duplicate/ambiguous records
* Guest payment matched by email

Add filters:

* Month/year
* Membership plan
* Membership status
* Payment status
* Show only flagged records
* Export CSV

## 4. Members Who Have Not Paid Dues

Build a focused report identifying members who appear to owe dues.

For each flagged member, show:

* Member name
* Email
* User ID
* Membership plan
* Membership status
* Last known payment date
* Last known payment amount
* Related order/subscription if available
* Number of days since last payment
* Reason flagged
* Suggested admin action

Examples of suggested actions:

* Confirm membership status manually
* Check subscription status
* Contact member about overdue dues
* Match guest payment to member account
* Review duplicate user/donor record
* Verify comped/lifetime membership status

This report should not modify accounts or memberships automatically. It should be review-only.

Add filters:

* Month/year or “as of” date
* Membership plan
* Membership status
* Days overdue threshold
* Show only active members
* Export CSV

## 5. Review & Recommendations

Create a summary/recommendations panel that highlights possible data cleanup or admin follow-up items.

Examples:

* Members with no recent dues payment
* Donations from guest emails that appear to match existing member emails
* Duplicate donor/member records by email
* Active memberships with cancelled/on-hold subscriptions
* Members with expired memberships but recent payments
* Donors with missing billing email/name
* Orders that look like donations but did not generate receipt metadata, if detectable
* Members with multiple active memberships, if that appears unintended

Each recommendation should include:

* Severity: info/warning/high
* Short issue title
* Explanation
* Affected count
* Link to the relevant filtered report
* Suggested next action

## Technical Requirements

Use WordPress and WooCommerce APIs where practical.

Use direct SQL only where it significantly improves performance, and keep queries safe with `$wpdb->prepare()`.

The plugin must:

* Be admin-only.
* Use nonces for CSV exports or report actions.
* Escape output properly.
* Sanitize all request/filter inputs.
* Use pagination for large reports.
* Avoid loading all orders/users into memory on large datasets.
* Avoid modifying orders, users, subscriptions, memberships, or donations automatically.
* Include clear inline comments around the data matching logic.
* Add reusable service classes for report queries/calculations.
* Add CSV export support for each report.
* Keep the UI simple and readable, using WordPress admin table styles where possible.

Suggested structure:

* `phsg-reporting-review-recommendations.php`
* `src/Plugin.php`
* `src/Admin/AdminPage.php`
* `src/Reports/LifetimeDonationsReport.php`
* `src/Reports/AnnualGivingReport.php`
* `src/Reports/MembershipRosterCrossCheckReport.php`
* `src/Reports/UnpaidDuesReport.php`
* `src/Reports/RecommendationsReport.php`
* `src/Services/DonationDataService.php`
* `src/Services/MembershipDataService.php`
* `src/Services/ReportCsvExporter.php`
* `src/Support/Formatting.php`

Use Composer/autoloading if the current repo/plugin structure supports it. Otherwise use safe manual includes.

## Admin UI

Use a tabbed admin screen.

Each tab should include:

* A short description of what the report does
* Filter controls
* Summary cards where helpful
* A paginated table
* CSV export button
* Clear empty states
* Clear notices if required plugins/classes are not available

If WooCommerce, Memberships, or Subscriptions are not active, show an admin notice explaining which dependency is missing instead of triggering fatal errors.

## Acceptance Criteria

The work is complete when:

1. The plugin activates without fatal errors.
2. The admin menu item appears for authorized admins.
3. Each report tab loads.
4. Filters work.
5. Tables paginate correctly.
6. CSV export works for each report.
7. Donation totals do not include non-donation purchases.
8. Refunds/cancelled/failed orders are not counted incorrectly.
9. Guest donors are included where appropriate.
10. Membership roster cross-check identifies active members with missing or questionable dues payments.
11. Unpaid dues report provides clear reasons and suggested actions.
12. Recommendations tab summarizes likely cleanup/follow-up items.
13. All output is escaped and all inputs are sanitized.
14. The implementation follows existing project conventions.

## Important Implementation Note

Before writing the final data queries, inspect the live codebase for the existing donation receipts and membership plugins. Identify how donations, receipts, dues, memberships, subscriptions, and member status are represented. Then implement the reporting logic around the actual source of truth rather than guessing from generic WooCommerce behavior.

Do not automatically email members, alter membership status, create orders, or make payment changes. This plugin is strictly for reporting, review, CSV exports, and admin recommendations.