feature/analytics-suite #7
Loading…
Reference in a new issue
No description provided.
Delete branch "feature/analytics-suite"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Two corrections to the spec, both found while building the dictionary, and both the kind of error the dictionary exists to catch. There is no single "Amtelco service level". genesis-service-level-data.md emits three in adjacent columns sharing the SUM(QuickCall) numerator: QuickCall % over answered, QuickCallAssigned % over assigned, and Sys SL % over assigned + reassigns + sys abandon. On the same calls they read 66.7%, 50.0% and 28.6%. The spec previously asserted one definition and described its denominator wrongly, contradicting the formula printed two lines above it. Sys SL % is the one closest to the industry 80/20 convention. @QuickCallMax has no documented default. The spec gave 12 seconds as Amtelco's; the only values in the corpus are commented-out test lines, 12 in two reports and 18 in a third. It is operator-supplied, so it has to be configured and shown, and 0 disables the metric and makes service level read a fake 100%. Also records that Stat cannot currently execute an Amtelco report at all: Stat.php:45 uses DB::select(), which fetches the first result of the batch — the one belonging to the DECLARE, with no columns. Every existing subclass is a single-statement query, so this has never surfaced, but any metric transcribed from a report will fail on construction until the runner walks forward to the first result with columns. Same fix as the test harness. Noted alongside it that Stat queries in its constructor, so a metric's parameter handling cannot be unit-tested in isolation, and that Crystal's {?Param} placeholders are not valid T-SQL and need translating to bindings. Phases become areas, per the decision to build them together rather than in sequence. The grouping now organises navigation and access scoping; the only split that carries weight is configuration-and-change-audit versus metrics. Report contents are settled from the 119/120 review, so that open question is closed and six real ones are recorded in its place. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>Two prerequisites for every metric, neither of which existed. Stat could not execute a report, and report SQL is not valid T-SQL to begin with. App\Support\SqlServer\BatchQuery runs the multi-statement batches the reports are written as. Measuring it rather than reasoning about it corrected what an earlier commit message here claimed: - DECLARE and SET produce no result and were never the problem. The DML is: an INSERT reports an "N rows affected" result and fetching that fails with "the active result for the query contains no fields". - Connection::selectResultSets() is not a fix. It walks the batch but calls fetchAll() on every result including the counts, so it fails identically. - SET NOCOUNT ON works only if it is not sent as a prepared statement. Connection::statement() prepares, and with this driver a SET inside a prepared statement never reaches the session — @@OPTIONS & 512 stays 0. That is why adding it to the harness earlier appeared to do nothing. It has to go through unprepared(). Both measures now apply: counts suppressed for the session, and results with no columns stepped over so a batch still runs where that did not take effect. Stat and the test harness share this one implementation rather than keeping parallel copies that could drift, which also means the harness tests now exercise the production path. App\Services\Analytics\CrystalParameters translates Crystal's {?Param} syntax to bindings. Three forms, all replaced in a single left-to-right pass so values land on the markers they belong to; one pass per form would group the bindings while the markers stayed in document order and silently bind everything to the wrong place. A quoted '{?StartBilling}' has the whole literal replaced, since leaving '?' binds nothing and filters on a question mark — 43 reports use that one form. Sweeping the corpus caught a bug worth the exercise: several reports carry commented-out parameter lines, and the driver ignores a ? in a comment. Substituting there appends bindings for markers the server never sees, and surplus bindings are taken from the front, so every real parameter shifts by one — a report that runs and returns a plausible wrong answer. It is now a scanner that skips comments, nested block comments and string literals. All 118 kept reports that carry SQL translate with bindings aligned to their live markers. Missing or unusable parameters raise rather than binding NULL, because a NULL comparison is never true and the report would come back confidently empty. Full suite: 1307 passed, 10 skipped. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>The strike-outs were deliberate, so genesis-service-level-data and genesis-call-completion-summary are no longer offered to a user: Report::surfaced() returns false for both, and MetricRegistry gains surfacedReports()/surfacedMetrics() which is what anything user-facing must read. They stay registered because what depends on them would otherwise be unverifiable -- the completion summary is the only source of the completion-code enumeration, and the service level report is the citation spine of the whole metric dictionary -- so deleting them would remove the proof while leaving the claims. 5 of 7 reports and 36 of 73 metrics are surfaced. A real defect in the translator, found while cataloguing the corpus's parameters. A placeholder inside a string literal with other text around it -- `'%{?Search}%'`, which 17 reports use for LIKE patterns -- was left entirely alone, because the scanner skipped literals wholesale. The parameter was therefore silently inert: never bound, never reported by names(), so a screen would not even have offered the input. Not a wrong answer, but a filter that quietly does nothing. Now a literal containing a placeholder becomes one binding with the value interpolated inside it, so `'%{?Search}%'` binds `%abc%` and keeps its wildcards. That subsumes the old special case for `'{?Param}'`, which was the same thing without surrounding text, so the two forms are one rule and the pattern lost an alternative. Doubled quotes collapse to single ones in the bound value, as SQL means them. A list inside a literal raises, since there is no faithful substitution. All 118 reports that carry SQL still translate with their bindings aligned to their live markers. While rewriting the tests for this I deleted two correct passing tests -- the line-comment and nested-block-comment cases -- by replacing a wider region than intended. Restored; the file is back to 19 tests. Also switched TranscriptionFidelityTest to getenv, since env() returns null once the config is cached. Worth recording about static analysis: phpstan.neon.dist analyses app/ only, so the clean results reported for tests/ in earlier commits were never in scope. The configured run is 65 errors, all pre-existing in app/, none in this work. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>113 reports registered, 3,286 metrics. Every report kept in the candidates review is now transcribed verbatim, registered, and proven to execute. Writing a class per report would have been thousands of lines of near-identical declaration, so the bulk are described as data in resources/analytics/reports.php and instantiated through GeneratedReport. tools/scaffold-analytics-reports.php builds that manifest from the corpus: it transcribes each report's SQL, works out which snapshot tables it touches, creates them, runs it, and reads the real column names off the statement -- necessary because 29 reports cannot be read statically, 16 ending in SELECT * and 13 aliasing nothing detectable. REVIEWED AND SCAFFOLDED ARE NOT THE SAME THING, and Report::reviewed() carries the distinction. A reviewed report has a hand-written class with real caveats naming where a figure is not what a reader would assume; seven are reviewed and between them they turned up about a dozen material divergences. A scaffolded report has verbatim SQL and metric formulas that are the verbatim SQL EXPRESSIONS -- never invented prose, because a plausible description nobody checked is exactly how the previous attempt produced figures nobody could defend. What has not been done for those 106 is checking whether a column name means there what it means elsewhere, which is the commonest way these figures mislead. Every scaffolded metric says so, and one using a name from the dictionary's conflict list says that too. So "113 reports available" is true and "113 reports whose numbers have been argued through" is not. The spec says so plainly. Nine kept reports could not be built, each for a stated reason rather than a shrug: three read tables absent from the schema snapshot (mOnCallAlert, mOnCallDetails, mClientMaint); four return a duplicated column name from a join with no AS to rename, which no generator should silently paper over since a row read by name returns only one of the pair and leaves the other reading as null; one names a second database the test server lacks; one has no SQL at all. Supporting work: - ReportParameterCatalogue holds all 48 Crystal parameters with types DERIVED from the reports' own DECLARE statements, not guessed from names -- each `SET @Var = {?Param}` traced back to its declaration. Twelve of them only became visible once the translator started handling placeholders inside string literals. - BatchQuery::columnNames reads a batch's column shape without fetching rows, which is what lets all 113 reports be column-checked with no seed data. - IntelligentTestSchema gains tables() and tablesFor(), the latter resolving a dbo. or [dbo]. prefix -- missing that cost a scaffolding run, with eight reports failing on "Invalid object name 'dbo.agtAgents'". - MetricRegistry resolves the manifest from __DIR__ rather than resource_path, so it works unbooted. PHPUnit calls static data providers before the container exists, and a provider that throws there yields no tests at all rather than a failure anybody notices -- which is what happened. Two bugs in the generator, both found by its own failures and both of the kind that would have shipped quietly. Renaming duplicated output aliases was matching every AS in the file, including inner scopes that the outer query then referenced, breaking eight reports with "Invalid column name 'agtName'"; it now rewrites only inside the outermost SELECT list. And a metric key slug dropped % and #, so agent-ready-not-ready's "Ready" and "Ready %" collapsed to one key and one became unreachable. Integration suite: 283 passed. PHPStan unchanged at the pre-existing 65. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>A library of 113 reports nobody can view is not a feature. Two pages, gated on utility.analytics in the controller rather than the component, because Livewire swallows an abort() raised in mount() on a full-page render. /utilities/analytics lists every surfaced report grouped by area, searchable by title, key or metric label, filterable by area. /utilities/analytics/{report} runs one: parameter form prefilled from the declared defaults, then charts, the numbers, and the definition behind every column. Four decisions in there that are not defaults: - Nothing runs on load. statCallTracker alone is 27 million rows, so a page that queried on render would make opening the library expensive and do it again on every Livewire round trip. The reader sets parameters and asks. - Every column is shown with its provenance -- the Amtelco report it came from, its formula, its caveat. The previous analytics area was deleted because nobody could say where its numbers came from. - A failure is shown, not swallowed. An empty table and a query that fell over look identical otherwise, and the first is a fact about the business while the second is a bug. - The library states which reports are reviewed. Hiding the difference between "accurate about its own SQL" and "checked against the rest of the corpus" would be the most misleading thing either page could do. CHARTING. ChartPlanner reads the grain and the rows actually returned: - The grain picks the form. Interval and day data is a line, skill/agent/client is bars, and per-call data is NOT charted -- three thousand calls plotted is a solid block that looks like information and is not. - Measures of different units never share an axis. A service level of 28.6% beside a count of 12,431 makes the percentage invisible, and a second y-axis is worse: it lets whoever drew it imply any correlation by choosing the scales. Units split into separate charts, asserted by test. - Eight series maximum, coloured in fixed order, never cycled. Overflow becomes another chart rather than a ninth hue, because two series the same colour is worse than two charts. - A percentage axis is pinned to 0-100, so a two-point spread does not look like a cliff. The palette was validated, not chosen by eye: --color-chart-1..8 in both the @theme and .dark blocks pass the lightness band, chroma floor, CVD separation, normal-vision floor and contrast against each mode's own surface. The ORDER is part of what passed, since the checks are on adjacent pairs. Dark mode is selected rather than flipped -- the band is the same in both modes, so the 400-level ramp fails it. The worst adjacent pair sits at tritan 7.1, inside the 6-8 floor band, which is legal only alongside secondary encoding; hence a legend at two or more series, direct labels at four or fewer, 2px surface gaps, and the table view. The table is not a fallback. Colours leave the server as token NAMES and are resolved in the browser from the live stylesheet, so a chart repaints on a theme toggle and app.css stays the one definition. Hex in the payload would wear light-mode colours on a dark surface forever. ECharts is imported dynamically only when a chart is on the page: it builds to a separate 1.1MB chunk and app.js stays at 170KB. Analytics is not an open utility -- admin, manager and supervisor only. A team without it enabled gets 404 rather than 403, which is the house rule and the right one: a 403 would confirm the feature exists to a team that has not bought it. Host suite: 1338 passed, 409 skipped. PHPStan back at the pre-existing 65. The 409 skips are the SQL Server integration tests. Docker stopped partway through this work and cannot be restarted from here without root, so the new end-to-end viewer test -- which drives the real connection resolution, presses Run and asserts on the rows and charts -- has not yet been executed. It needs `sail up -d mssql`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJAnalytics shipped as a utility: a system feature flag, a `utility_analytics` column, a tile on the utilities grid, and an administrator switching it on team by team. That was the wrong shape. A utility is something a team opts into. Analytics is part of the application -- it belongs in the top navigation beside Dashboard and Accounts, on for every team, with the role deciding who may open it and the team's own allowances deciding what they are told. So the flag and the column are gone, `utility.analytics` becomes `analytics.view` beside `accounts.view`, and the pages move out from under /utilities: /utilities/analytics -> /analytics /utilities/analytics/{report} -> /analytics/{report} with the controller, the Livewire components and their views following the URL out of the Utilities namespace. The nav entry renders in both the desktop strip and the responsive menu -- a nav item invisible on a phone is half-built. The gate is now the capability alone, which means 403 and not the 404 a disabled utility returns. That is the right answer here: the 404 exists to avoid confirming a feature a team has not bought, and every team has this one. Two things the utility flags used to carry for free had to be restated: `Capability::requiresRealTeam()` refuses a personal team. A personal team has no account scoping, so there would be nothing to narrow a report to, and a global suffix rule can otherwise grant a capability on whatever team is current. `App\Support\AnalyticsScope` answers the harder half. Every report here is whole-operation -- Amtelco's SQL counts every call on the switch -- and nothing yet narrows a result to a team's accounts. While an administrator had to enable the utility per team that stayed theoretical; on by default it does not. A team whose account scope has never been decided cannot run a report, which is the rule CallAccess already applies to the call log. A team restricted to an account list is told on the page that the figures are not narrowed to it, rather than refused: whether an operation-wide number is acceptable for an internal team is theirs to decide, but quietly overruling their allow list is not. Both components also gained the capability themselves via AuthorizesSystemComponent. They had none -- the page controller was the only gate, and Livewire does not re-run it on POST /livewire/update, so a reader whose capability was revoked mid-session could keep pressing Run. The two migrations this replaces added the column and granted the old capability. They were never released but were on this branch long enough to have been run, so both halves are undone conditionally and an existing grant is carried across rather than dropped -- a role an admin had already edited keeps analytics. 1353 tests pass; PHPStan unchanged at its 66. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJPHPUnit 12 removed support for the `/** @test */` doc-comment annotation. Seven files in tests/Feature/Console/Commands relied on it exclusively -- not one of their methods carried a `test` prefix -- so PHPUnit saw seven empty classes: No tests found in class "Tests\Feature\Console\Commands\SyncISDataTest". That is a test-runner warning, which makes TestResult::wasSuccessful() false and exits 1. Collision's summary renders passed/failed/skipped and not warnings, so every run printed a clean "1268 passed" while returning failure, and the JUnit log agreed because the missing tests were never collected to have an outcome. Twenty test methods had not run for as long as this repository has been on PHPUnit 12. Nothing on a developer machine would ever have said so; CI found it on its first green-looking run. Renaming them to the house `test_` prefix made them run, and thirteen failed. None of the failures were what the error text first suggested. Six were a stale API: Helpers::enableSystemFeature() does not exist, and the suite drives flags through the InteractsWithFeatureFlags trait. Switched. Ten `->expectsOutput('')` calls across four files assert that a literal empty line was printed. No command here prints one and no author can have meant it -- the files that pass assert real text, like 'Checking recording wav files...'. Removed the incoherent line; every real assertion stays. PurgeBoardCheckActivityTest needed a factory, written from the `activities` migration, and also asserted against a `board_check_activities` table that is never created: the model declares no $table, so Eloquent resolves Activity to `activities`. Those assertions would have thrown even with the factory. SyncISDataTest asserts that SyncMergeCommWebHooks is dispatched. In SyncISData::handle() that dispatch is commented out, and has been since before the initial public commit, so the command is a no-op returning SUCCESS -- while still being scheduled every thirty minutes in Kernel.php:77. Uncommenting it to satisfy a test would be deciding that the sync should run, which is not a test's call to make. The test now asserts what the command does and fails if the dispatch comes back without the real assertion being restored. ConvertRecordingTest's three were never valid rather than rotted. Redis::fake() is not a Laravel feature: the facade forwards it to Redis as a command named FAKE, and predis rejects it, which killed all three in setUp. Redis::assertExists() and $this->assertDispatched() do not exist either. Past those, the command does `new Call([...])` instead of resolving from the container, so $this->mock(Call::class) cannot intercept it, and recordingData() queries Intelligent Series. Real coverage needs SQL Server, Redis and sox, which makes it an integration test. Skipped with the whole reason in the class docblock rather than deleted or faked green. Net effect, measuring the exit code rather than a pipeline's last command: before 10 skipped, 1268 passed (3517 assertions) exit 1 after 13 skipped, 1285 passed (3589 assertions) exit 0 Seventeen more tests and seventy-two more assertions actually running. PHPStan unchanged. Two things this turned up that are not test problems and are left alone: intelligent-data:sync is scheduled every thirty minutes and does nothing, and ConvertRecordingTest needs either a move to tests/Integration or a command that resolves Call through the container. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013KMc2poE9T5ufmGrg2nAFJThese are Amtelco's reports, run as Amtelco ships them. Stamping each one with our own verdict on whether it had been "reviewed" was editorialising on every page, and it is out: - the "Not yet reviewed" box on the report viewer; - the Reviewed / Not reviewed tag on every library card, and the header sentence that counted them; - the disclaimer prefixed to every column of all 106 scaffolded reports in the definitions table, some of which also pointed users at an internal developer document, docs/specs/reference/metric-dictionary.md. The library header now reads simply that the reports run exactly as Amtelco ships them and that every figure names the report it came from. Kept: the caveats the five hand-written reports carry on their own metrics -- that Assigned and Abandoned are defined differently across reports, and how the Call Theory answer-time figure departs from Amtelco's. Those are statements about particular columns, not a blanket label, and MetricRegistryTest holds them. The two page tests that asserted the labels were present now assert they are absent, so they do not drift back in. Report::reviewed() still exists internally; nothing user-facing reads it. Unit+Feature 1382 passed, Integration 287 passed, both exit 0 in Sail; TranscriptionFidelityTest 112 passed on the host against the corpus. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019DLYxPYkMy1Ezbax3x4s2KView command line instructions
Manual merge helper
Use this merge commit message when completing the merge manually.
Checkout
From your project repository, check out a new branch and test the changes.