rory
/
deadhead-space-freight-tycoon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
deadhead-space-freight-tycoon/memory-bank/change-requests/CR-025-short-away-summary.md

8.0 KiB
Raw Blame History

Change Request CR-025 — Short "While You Were Away" Summary

Numbering note (added when recorded): this request arrived titled "CR-023 — Short 'While You Were Away' Summary" for "Phase 23". CR-023 (Shop Time Counts as Rest) and CR-024 (Fleet Sleep Mode), and Phases 23 and 24, already existed, so it is stored as CR-025 and done as Phase 25: every "23.n" below means 25.n. Its references map to this repo as: "Phase 13 and CR-001 through CR-022" = Phase 13 and CR-001 to CR-024; "CR-001 faster start" (scripted contract flavor messages) is the same number; "CR-011 local-first" = CR-014 (the engine, the save, retention on save); "CR-014 leg fuel cost" = CR-015 (fuel tanks: a leg's fuel at the tank's average price, decision 0.5.98); "CR-019 independent pilots" = CR-021 (the per-pilot logbook, the NPC spending floor); "CR-022 fleet sleep" = CR-024. Plan 9.2 is the same step. Its new decisions CR-023.D1–D3 are recorded as 0.5.140 Highlights pop-up, 0.5.141 Logbook screen and 0.5.142 Net earnings.

On recording: "HQ" is the Bridge (the dashboard), as in CR-021 and CR-024.

Project: Deadhead: Space Freight Tycoon Applies to: a build with Phase 13 and CR-001 through CR-022 complete Do this: as Phase 23 Related docs: change-request-faster-start.md (CR-001), change-request-local-first.md (CR-011), change-request-independent-pilots.md (CR-019), change-request-fleet-sleep.md (CR-022), DECISIONS.md

This change request is written for the local-first engine (CR-011).

1. Why

The "while you were away" pop-up lists every delivery, and CR-019 added a full per-pilot logbook to it. With a handful of Independent pilots running for a day, it becomes a long scroll. The pop-up should show highlights only: company totals, anything that needs the player, and one line per pilot. Full detail moves to a separate Logbook screen.

2. The pop-up

Fits on one phone screen without scrolling, however many pilots there are.

Layout, top to bottom

  1. Header: "While you were away · 9 h 40 m"

  2. Sleep banner (CR-022), if the fleet went quiet, with Back to work.

  3. Company totals, one row of figures: net earned, deliveries, discoveries (if any), loan repaid (if any).

  4. Highlights, at most 3, in this priority order:

    1. New location discovered
    2. Pilot leveled up ("Rosa reached level 4 · 1 skill point")
    3. Goal ready to claim
    4. Scripted contract flavor message (CR-001)
    5. Best single delivery ("Biggest job: Helium-3 Canisters to Earth, 8,420 cr, Rosa")
    6. Problem needing attention: a ship idle with no reachable jobs, fuel too low to fly, emergency fuel available, or credits below the NPC spending floor (CR-019)

    If there are more than 3, show the top 3 and "+2 more in the Logbook".

  5. Pilots, one line each: name, deliveries, net profit, and where they are now ("Rosa · 6 jobs · +12,300 cr · Resting at Ceres"). A level-up adds a small badge.

    • Only pilots with activity during the absence are listed; others are summed in one line ("3 pilots had nothing to do").
    • Sorted by net profit, highest first.
    • At most 5 pilot lines; the rest collapse into "+7 more pilots: +18,900 cr".

  6. Buttons: View logbook and Done.

Short absences

If the absence produced 3 events or fewer in total (deliveries, discoveries, level-ups), show those events directly instead of the totals and pilot sections, so a quick check-in still reads naturally ("Courier delivered Mail & Parcels to the Moon, +410 cr").

What counts as "net"

Payout minus pilot share, fuel used (CR-014 leg fuel cost), and loan repayment, matching the delivery summaries. Fuel bought counts when it's spent, not when it's bought.

3. The Logbook screen

  • A new screen, reached from View logbook and from HQ.
  • Holds the full detail CR-019 put in the pop-up: per pilot, every job (good, route, payout, pilot share, fuel), deadheads, refuels, rests, upgrades finished, XP gained.
  • Filter by pilot and by time range ("This absence", "Last 24 h", "Last 7 days").
  • Keeps entries for 7 days, pruned on save (CR-011 retention), so the save stays small.

4. Rules for this change

  • All rules in implementation-plan.md §0.1 apply: steps in order, one commit per step, each step's test must pass.
  • Building the summary (totals, highlights, pilot lines, collapse) is a pure function of the logbook entries for the absence, so it can be tested without UI.
  • Highlight wording lives in content.
  • Save migration: existing summary data is converted to logbook entries where possible; otherwise it's dropped.
  • Update architecture.md and progress.md as you go. Stop for the user's review at the end of Phase 23.

5. Decisions

Record these in DECISIONS.md and implementation-plan.md §0.5, using the next free numbers (labeled CR-023.D1–D3 here; note the mapping).

  • CR-023.D1 Highlights pop-up. Per §2: totals, at most 3 highlights, at most 5 pilot lines, one screen, with a direct list for absences of 3 events or fewer.
  • CR-023.D2 Logbook screen. Full detail per §3, kept for 7 days.
  • CR-023.D3 Net earnings. Payout minus pilot share, fuel used, and loan repayment.

6. Steps — Phase 23

Step 23.1 — Engine: logbook entries and retention

  • Store every relevant event (delivery, deadhead, refuel, rest, upgrade finished, discovery, level-up, goal ready) as a logbook entry with pilot, ship, time, and amounts. Prune entries older than 7 days on save.
  • Test: Each event type creates one entry with the right fields. Entries older than 7 days are pruned; newer ones remain. Catch-up and live play produce the same entries.

Step 23.2 — Sim: summary builder

  • A pure function that turns the entries for an absence into: duration, totals, up to 3 highlights in priority order with an overflow count, up to 5 pilot lines sorted by net profit with an overflow line, the idle-pilots line, and the "short absence" direct list when there are 3 events or fewer.
  • Test: With 50 pilots' worth of entries, the result has exactly 5 pilot lines and an overflow line whose totals equal the rest. Highlights follow the priority order and cap at 3 with the right overflow count. Totals equal the sum of entries. With 2 events, the result is the direct list. Net matches the delivery-summary calculation.

Step 23.3 — Client: highlights pop-up

  • Replace the current pop-up with the §2 layout. Keep the CR-022 sleep banner and button.
  • Test: Component tests: with 50 active pilots, the pop-up fits in a 375×667 viewport without scrolling; each section renders from a seeded summary; "+N more" lines appear only when needed; a short absence shows the direct list; Done dismisses it; View logbook opens the Logbook filtered to this absence.

Step 23.4 — Client: Logbook screen

  • Add the Logbook screen per §3, with pilot and time-range filters, reachable from the pop-up and from HQ.
  • Test: Component tests: entries render per pilot with the CR-019 detail; filters narrow the list correctly; the "This absence" filter matches the pop-up's totals.

Step 23.5 — Regression

  • Run the full suite.
  • Test: CI is green. Manual check: with several Independent pilots, leave the game for a few hours, reopen on a phone, and confirm the pop-up fits on one screen and the Logbook holds the full detail.

7. Amendments

Where Change
Plan 0.5 Add CR-023.D1–D3.
Plan 9.2 "While you were away" becomes the highlights pop-up (23.3).
CR-019 The per-pilot logbook moves from the pop-up to the Logbook screen (23.4).
CR-022 Sleep banner stays at the top of the pop-up.

8. Out of scope

Charts or graphs of earnings, exporting the logbook, per-pilot notification digests, and anything else in implementation-plan.md §0.3.