Mining Manager Laravel Package

Getting Started

Read the release notes as a scoping document, not just a changelog. v2.0.4 confirms what the earlier metadata only hinted at: this is not a general-purpose Laravel package, it is a SeAT plugin (SeAT is the Laravel-based EVE Online corporation management application). That single fact changes the install path, the licensing picture, and the integration surface.

Minimal steps

1. Confirm the host, not just the package. You are installing into a SeAT instance, so the real compatibility question is which SeAT major version this plugin targets, not which Laravel version. Check composer.json for the eveseat/* constraints and the service provider namespace. Installing into a plain Laravel app is not the intended path and most of the plugin's assumptions (SeAT users, corporations, permissions, ESI, scheduler) will be absent.
2. Pin v2.0.4 explicitly. The release is described as backwards compatible with nine additive migrations, which is a good sign — but the release notes are dense enough that you want a known tag, not dev-main. Re-verify the tag against git log and git tag -l; the previously noted future-dated release is a metadata oddity worth confirming rather than ignoring.
3. Back up the database and the settings. SeAT has a settings backup facility; use it before migrating. "Additive migrations" means the schema change is safe, not that the behaviour change is safe — and there are five behaviour changes in this release.
4. Migrate, then walk the upgrade checklist before users touch anything:
   • Re-tick the Extraction at Risk and Extraction Lost webhook flags under Settings → Webhooks. The 2.0.4 bug means any webhook saved in an affected version may have those two alerts silently switched off.
   • Decide, with whoever owns finance, whether the belt/ice/gas tax increase is acceptable before the next billing run.
   • Confirm whether Allow Data Export was ever switched off. If it was, exports now actually stop.
5. Grant the new permission. Find Moons requires Director, Moon Manager, or the new mining-manager.moon_finder permission. Members retain the Extraction Simulator; the finder is gated.

First use case

The realistic first use case is invoice and wallet reconciliation hygiene, not moons or charts. The headline of 2.0.4 is that a wallet transfer without a pasted tax code — previously an unresolvable row — can now be assigned to an invoice by hand, cascades to the next unpaid invoice, and holds any surplus as an account balance. If you currently reconcile corporation wallet transfers against invoices by hand, that is the workflow to exercise first: run a manual assignment through Wallet Verification, undo it, then re-run and watch the cascade and balance behaviour before letting the scheduled matcher do it unattended.

Implementation Patterns

Treat the plugin as a SeAT citizen, not a generic dependency. Do not wrap it behind a port as you would a third-party API client. SeAT plugins are designed to extend the host through its own extension points — service providers, migrations, permissions, settings, scheduled commands, webhooks, and ESI scopes. The idiomatic integration is to configure and operate those, not to abstract them away. Your custom code should sit alongside the plugin as SeAT modules, not between it and the host.

Operate through the artisan commands, not the UI, for anything repeatable. The release notes confirm real console surface: import-character-mining (now with --dry-run that walks the same path as the import and prints what it would write without writing), and calculate-taxes --recalculate. Two patterns follow:

• Run --dry-run in staging before every real import, especially after this update — the summation fix changes what gets written for belt/ice/gas.
• Never run --recalculate as a habit. It now refuses to touch invoices that have a payment code, money against them, or a paid/partial status. That is the correct behaviour, but it means recalculation is no longer a safe "just refresh everything" button; it is a correction tool for invoices that have not gone out.

Model the payment state machine explicitly in your own reporting. The plugin now has, in effect, four states a payment can be in: matched by tax code, manually assigned, cascaded remainder, or held as balance. It also records a payment row on Mark as Paid, bulk Mark as Paid, and the status dropdown. If you build dashboards or finance exports on top of the plugin's tables, read the payment rows rather than inferring from invoice status — the whole point of this release is that the invoice is "a record, not a calculation."

Use the scheduled job and webhook surfaces as your integration boundary. The Outstanding Mining Tax digest is per-webhook opt-in and corp-scoped; if you want it in your own alerting, wire to that rather than polling the database. Same for the wallet watcher: refunds are matched by scanning the corporation wallet (across every division) for MM-REFUND in the transfer reason. If your corporation has wallet activity that the plugin should see, make sure the ESI scopes and divisions are configured before relying on automatic matching.

Respect the keyword contracts. MM-UPFRONT (default, configurable under Settings → Features) authorises pre-invoicing payment. MM-REFUND closes a refund. These are string contracts between a human making an in-game transfer and the plugin's matcher. If your corporation uses a different convention, either configure the keyword or document the default prominently for directors, because a typo means the transfer sits in the queue.

Extension points to use, in order of preference:

• Settings (General, Features, Webhooks) — cascade, surplus-to-balance, upfront payments, data export, digest opt-in.
• Permissions — mining-manager.moon_finder and the Director/Moon Manager roles for the finder; do not widen these casually, the release notes are explicit that listing every valuable moon in a region is director-grade intel.
• SeAT's settings backup — record your configuration so a rebuild is reproducible.
• The artisan commands and their flags.
• The published migrations, as read-only documentation of the domain model.

Only if none of those suffice should you consider a fork — and if you do, keep a PATCHES.md.

Testing. Stand up a disposable SeAT instance with a copy of production data, not a bare Laravel app. Exercise the five behaviour changes from the release notes as acceptance criteria: webhook flags, belt/ice/gas totals, Janice split prices, partly-paid reminders, and export blocking. Only then promote.

Gotchas and Tips

The five upgrade behaviour changes are the whole risk of this release. None are schema-breaking, all are operationally visible, and three of them affect money:

• Webhook flags reset silently. The Extraction at Risk and Extraction Lost toggles could display as off regardless of their stored value, and saving the webhook committed the off state. Anything already switched off stays off. Re-tick them and verify by triggering a test alert.
• Belt, ice and gas bills rise. SeAT adds a row each time a fetch finds a character's mining day has grown; the import was treating each row as the whole day, and now sums them. Bills from this update forward are higher; nothing in the existing ledger is recounted. Tell finance before the next run, or the first invoice after upgrade will look like an error.
• Janice split prices were zero and are now real. The plugin was reading a field Janice's pricer never sends. Values and tax change from the first refresh after updating. Invoices already issued keep their billed amounts — which is correct, but means you will see a discontinuity between old and new invoices that needs explaining.
• Partly paid invoices are now reminded. Including ones that went partial before the update. The first reminder run may contact members who have not heard from the plugin in a long time. Warn whoever handles member comms, or suppress the run once and review.
• Allow Data Export now enforces. It never worked. If it was switched off, every mining, tax, analytics, theft and report download stops for everyone, directors and admins included. The settings backup is unaffected. Audit this toggle before upgrading, especially if your workflow includes scheduled exports.

Payments and refunds are not fully automatic by design. EVE has no API for sending ISK, so a refund is a director making an in-game transfer with MM-REFUND in the reason, plus the plugin watching every corporation wallet division. If a refund will never match (wrong reason, wrong division, manual cash-out), Mark as sent is the escape hatch. Document that, or refunds will sit open forever.

Invoice immutability is now real. Once an invoice has a payment code, money against it, or a paid/partial status, calculate-taxes --recalculate will not touch it. If you have a workflow that assumed recalculation fixed everything, it now silently skips those rows. Check the output rather than assuming success.

Late-arriving mining is marked, not charged. A row that arrives after the bill keeps its quantity and value but carries a zero rate and a note explaining why. Where observer data catches up on an already-billed row, only the delta is added and the billed value and tax stay fixed. This is the right design for auditability, but it means "why is this row zero-rated?" is a legitimate question your support docs should answer.

Excluded ore is a deliberate gap. Event ore, quest ore and all six Mutanite types from Homefront Operations (Tyranite, Nephrite, Dense Moissanite, Amethystic Crystallite, Hiemal Tricarboxyl Condensate, Volatile Ice, Veldspar Isotope, Mutanite) are not imported, taxed, valued or charted. If your corporation mines them, they will not appear. Rows already in the ledger stay. This is a policy decision by the maintainer, not a bug — check issue #3 for the rationale before filing.

Prior versions silently failed batch operations. Sync, Auto-Match, Verify and Dismiss all threw on the first line because toastr was never loaded — and a batch where every row failed still reported green. If you are upgrading from an earlier version, any "successful" batch run you remember from before 2.0.4 should be treated as unverified. Re-run reconciliation after upgrading and check the actual rows, not the toast.

A partial payment could previously be credited twice, and a tax code in the transfer reason was invisible to two of the three matchers. Both are fixed. If you have invoices that look over- or under-paid from before the update, they may be artefacts of those bugs — but note that 2.0.4 does not retroactively correct them, so manually reconcile affected historical invoices rather than assuming the fix backfilled.

New permission needs granting. Find Moons is hidden without mining-manager.moon_finder (or Director / Moon Manager). Members keep the simulator. If the search does not appear for a director, check the permission before checking the code.

Numeric precision — check the ISK columns. Now that balances, partial payments and refunds are held as money, confirm the balance and payment columns are decimal, not float. A balance carried in floating point will drift, and the drift will be attributed to the plugin.

Timezone handling on invoice periods. Mining operations are frequently multi-timezone; daily aggregations over naive timestamp columns silently corrupt. This is not new in 2.0.4, but the summation fix makes the import boundary more important than it was.

Licensing is now clearer, and less alarming. SeAT is itself GPL-2.0, so a GPL-2.0 plugin is consistent with the host ecosystem — internal use is fine, and the earlier "get legal before you commit" warning was overstated for a SeAT deployment. The copyleft obligation still attaches if you distribute modified plugin code, so keep any local patches documented and separable rather than vendoring a modified copy into a product you ship.

Debugging. Use php artisan tinker against the plugin's models first — most "the plugin doesn't work" reports resolve to an unrun migration, a missing permission, or a settings toggle. import-character-mining --dry-run is the fastest way to see what the import would do without side effects. Turn on DB::listen() in a local route when a dashboard looks wrong; you will usually find a missing index on fetched_at / worker_id, or an N+1 on payments. For webhook issues, check the settings table directly rather than trusting the UI — that was the exact failure mode this release fixed.

Still verify the release, but the "abandoned single-maintainer" framing no longer holds. A 2.0.4 release with nine migrations, a linked issue tracker, and a coherent narrative is not an abandoned repo. It is still a single-maintainer SeAT plugin, which means you are responsible for reading the release notes before every update — this one alone has five behavioural changes that no dependency resolver will warn you about. Pin versions, read the ⚠️ section, and keep a PATCHES.md if you fork.