feat: индекс на качеството на договорите (ETL оценка 0..1 + страница)

apps/web/app/components/ComboTrendChart.tsx

@@ -0,0 +1,158 @@
+import { useState } from 'react';
+import type { TrendGranularity, TrendPoint } from '@sigma/api-contract';
+import { count, money, monthYear } from '@sigma/shared';
+import { yearAxisTicks } from '../lib/trendAxis';
+
+// Bar + line combo for the contracts overview (/trends): bars carry the contract count, the ink line
+// the € volume. Server-rendered SVG like TrendChart; the only client behavior is the hover tooltip
+// (React state after hydration — SSR renders the chart without it, so no-JS still gets the picture).
+// The accessible data lives in the year cards next to the chart, matching the TrendChart pattern.
+
+const W = 1000;
+const H = 300;
+const TOP = 10;
+const BOT = 272;
+const PAD = 8;
+
+/** 'YYYY-MM' → 'март 2024', 'YYYY-Qn' → 'Q1 2024', 'YYYY' → '2024'. */
+export function periodLabel(period: string, granularity: TrendGranularity): string {
+  if (granularity === 'year') return period;
+  if (granularity === 'quarter') {
+    const [y, q] = period.split('-Q');
+    return `Q${q} ${y}`;
+  }
+  return monthYear(period);
+}
+
+export function ComboTrendChart({
+  points,
+  granularity,
+  cssHeight = 240,
+  interactive = true,
+  ariaLabel = 'Брой договори и € обем във времето',
+}: {
+  points: TrendPoint[];
+  granularity: TrendGranularity;
+  cssHeight?: number;
+  interactive?: boolean;
+  ariaLabel?: string;
+}) {
+  const [hover, setHover] = useState<number | null>(null);
+  if (points.length < 2) return null;
+
+  const n = points.length;
+  const vMax = Math.max(1, ...points.map((p) => p.valueEur)) * 1.12;
+  const cMax = Math.max(1, ...points.map((p) => p.contracts));
+  const x = (i: number) => (n > 1 ? PAD + (i * (W - 2 * PAD)) / (n - 1) : W / 2);
+  const yV = (v: number) => BOT - (v / vMax) * (BOT - TOP);
+  const yC = (c: number) => BOT - (c / cMax) * (BOT - TOP) * 0.62;
+  const bw = Math.max(2, ((W - 2 * PAD) / n) * 0.66);
+  // Bars are centred on x(i), and x(0)/x(n-1) sit on the plot edges — so the first/last bar would
+  // overflow the viewBox by bw/2 (severe at n=2, bw≈324). Inset just the bar x-position at the ends;
+  // the line/cursor/dot keep using x(i) so the value series stays anchored to the true period edges.
+  const barX = (i: number) => Math.min(W - PAD - bw / 2, Math.max(PAD + bw / 2, x(i)));
+
+  // Final period is partial (still filling): dashed line tail + faded bar, like TrendChart.
+  const partialIdx = points.findIndex((p) => p.partial);
+  // partialIdx > 0 also treats "no partial point" (findIndex returns -1) as non-partial, and a
+  // partial flag on the very first point (index 0) as non-partial too — the latter never happens
+  // in practice (the first period is never still-filling), matching TrendChart's same assumption.
+  const hasPartial = partialIdx > 0;
+  const solidEnd = hasPartial ? partialIdx - 1 : n - 1;
+  const xy = (i: number) => `${x(i).toFixed(1)} ${yV(points[i]!.valueEur).toFixed(1)}`;
+  const line = points
+    .slice(0, solidEnd + 1)
+    .map((_p, i) => `${i ? 'L' : 'M'}${xy(i)}`)
+    .join(' ');
+  const dashed = hasPartial ? `M${xy(solidEnd)} L${xy(partialIdx)}` : '';
+
+  const ticks = yearAxisTicks(points, granularity);
+
+  const hp = hover != null ? points[hover] : null;
+
+  return (
+    <div className="combo-chart" onMouseLeave={() => interactive && setHover(null)}>
+      <svg
+        viewBox={`0 0 ${W} ${H}`}
+        preserveAspectRatio="none"
+        style={{ display: 'block', width: '100%', height: cssHeight }}
+        role="img"
+        aria-label={ariaLabel}
+      >
+        {[0, 1 / 3, 2 / 3, 1].map((f) => (
+          <line
+            key={f}
+            className="combo-grid"
+            x1={0}
+            y1={yV(vMax * f).toFixed(1)}
+            x2={W}
+            y2={yV(vMax * f).toFixed(1)}
+            vectorEffect="non-scaling-stroke"
+          />
+        ))}
+        {points.map((p, i) => (
+          <rect
+            key={p.period}
+            className={`combo-bar${hover === i ? ' is-hover' : ''}${p.partial ? ' is-partial' : ''}`}
+            x={(barX(i) - bw / 2).toFixed(1)}
+            y={yC(p.contracts).toFixed(1)}
+            width={bw.toFixed(1)}
+            height={(BOT - yC(p.contracts)).toFixed(1)}
+            onMouseEnter={interactive ? () => setHover(i) : undefined}
+          />
+        ))}
+        <path className="combo-line" d={line} vectorEffect="non-scaling-stroke" />
+        {hasPartial && (
+          <path className="combo-line-partial" d={dashed} vectorEffect="non-scaling-stroke" />
+        )}
+        {hp && hover != null && (
+          <>
+            <line
+              className="combo-cursor"
+              x1={x(hover).toFixed(1)}
+              y1={6}
+              x2={x(hover).toFixed(1)}
+              y2={BOT}
+              vectorEffect="non-scaling-stroke"
+            />
+            <circle
+              className="combo-dot"
+              cx={x(hover).toFixed(1)}
+              cy={yV(hp.valueEur).toFixed(1)}
+              r={4}
+              vectorEffect="non-scaling-stroke"
+            />
+          </>
+        )}
+      </svg>
+      <div className="combo-xlab" aria-hidden="true">
+        {ticks.map((t) => (
+          <span key={t.i}>{t.year}</span>
+        ))}
+      </div>
+      {hp && hover != null && (
+        <div
+          className="combo-tip"
+          role="status"
+          style={{
+            left: `${((x(hover) / W) * 100).toFixed(1)}%`,
+            top: (yV(hp.valueEur) / H) * cssHeight - 4,
+          }}
+        >
+          <div className="combo-tip-label">
+            {periodLabel(hp.period, granularity)}
+            {hp.partial ? ' · частично' : ''}
+          </div>
+          <div className="combo-tip-row">
+            <span>€ обем</span>
+            <strong>{money(hp.valueEur)}</strong>
+          </div>
+          <div className="combo-tip-row">
+            <span>договори</span>
+            <strong>{count(hp.contracts)}</strong>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/app/components/MetricInfo.tsx

@@ -0,0 +1,94 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+// SSR has no DOM, so useLayoutEffect on the server both does nothing useful and logs React's
+// "useLayoutEffect does nothing on the server" warning. Swap to useEffect during SSR (typeof
+// window guards it) while keeping the client on useLayoutEffect for its pre-paint clamp.
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+// A small ⓘ affordance next to a metric label. For pointer users it reveals an elegant popover on
+// hover or keyboard focus (pure CSS `:hover` / `:focus-within`). Because hover does not exist on
+// touch, a click also toggles the popover open via an `is-open` class — and an outside-click or Esc
+// closes it again. The button carries the full text as its aria-label, so screen-reader users get the
+// same information without the visual popover (which is aria-hidden). SSR-safe: the initial render is
+// closed and the toggle/effects only run on the client.
+export function MetricInfo({
+  title,
+  summary,
+  readout,
+  align = 'start',
+}: {
+  title: string;
+  summary: string;
+  // Plain string so the readout is always reflected verbatim into the aria-label (all callers pass a
+  // string — the screen-reader text must never silently drop a non-string interpretation).
+  readout?: string;
+  // Which edge the popover anchors to — use 'end' for right-most metrics so it doesn't clip.
+  align?: 'start' | 'end';
+}) {
+  const aria = readout ? `${title}. ${summary} ${readout}`.trim() : `${title}. ${summary}`;
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLSpanElement>(null);
+  const popRef = useRef<HTMLSpanElement>(null);
+  // Horizontal shift (px) that keeps the click-opened popover inside the viewport on small screens
+  // (mobile audit: at 320px the fixed-width popover clips off-screen for edge-column metrics).
+  const [shift, setShift] = useState(0);
+
+  useIsomorphicLayoutEffect(() => {
+    if (!open) {
+      setShift(0);
+      return;
+    }
+    const pop = popRef.current;
+    if (!pop) return;
+    const rect = pop.getBoundingClientRect();
+    const vw = document.documentElement.clientWidth;
+    let dx = 0;
+    if (rect.right > vw - 8) dx = vw - 8 - rect.right;
+    if (rect.left + dx < 8) dx = 8 - rect.left;
+    setShift(Math.round(dx));
+  }, [open]);
+
+  // Close on outside-click / Esc while open (touch path — pointer users rely on CSS hover/focus).
+  useEffect(() => {
+    if (!open) return;
+    const onPointer = (e: PointerEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('pointerdown', onPointer);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointer);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <span className={`metric-info${open ? ' is-open' : ''}`} ref={ref}>
+      <button
+        type="button"
+        className="metric-info-btn"
+        aria-label={aria}
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+      >
+        <span className="metric-info-glyph" aria-hidden="true">
+          ⓘ
+        </span>
+      </button>
+      <span
+        className={`metric-info-pop${align === 'end' ? ' is-end' : ''}`}
+        aria-hidden="true"
+        ref={popRef}
+        // `translate` composes with the CSS `transform` reveal transition instead of replacing it
+        style={shift !== 0 ? { translate: `${shift}px 0` } : undefined}
+      >
+        <span className="metric-info-title">{title}</span>
+        <span className="metric-info-summary">{summary}</span>
+        {readout ? <span className="metric-info-readout">{readout}</span> : null}
+      </span>
+    </span>
+  );
+}

apps/web/app/components/TrendChart.tsx

@@ -1,4 +1,5 @@
-import type { TrendPoint } from '@sigma/api-contract';
+import type { TrendGranularity, TrendPoint } from '@sigma/api-contract';
+import { yearAxisTicks } from '../lib/trendAxis';
 
 // Server-rendered area + line of spend over time (no chart JS, like SankeyDiagram). The accessible
 // data is the per-year table beside it; this SVG is a visual summary (role="img" + aria-label) with
@@ -13,7 +14,7 @@ export function TrendChart({
   granularity,
 }: {
   points: TrendPoint[];
-  granularity: 'month' | 'year';
+  granularity: TrendGranularity;
 }) {
   if (points.length < 2) return null;
   const max = Math.max(1, ...points.map((p) => p.valueEur));
@@ -32,10 +33,7 @@ export function TrendChart({
     .join('');
   const area = `${line}L${x(solidEnd).toFixed(1)},${H - PAD_B}L0,${H - PAD_B}Z`;
   const dashed = hasPartial ? `M${xy(solidEnd)}L${xy(partialIdx)}` : '';
-  // x-axis ticks at the first month of each year (month granularity) or at every point (year).
-  const ticks = points
-    .map((p, i) => ({ i, year: p.period.slice(0, 4) }))
-    .filter((t, idx) => granularity === 'year' || points[idx]!.period.endsWith('-01'));
+  const ticks = yearAxisTicks(points, granularity);
 
   // viewBox carries 14px of horizontal bleed on each side so the first and last year labels, which are
   // centred on the edge ticks, are not clipped.

apps/web/app/lib/analytics-lenses.ts

@@ -11,14 +11,19 @@ export const ANALYTICS_LENSES = [
   },
   {
     href: '/trends',
-    title: 'Тренд',
-    desc: 'Как се движат разходите във времето по месеци и години.',
+    title: 'Договори — обзор',
+    desc: 'Договорите във времето, по CPV код, или двете наведнъж — с типичните цени по група.',
   },
   {
     href: '/competition',
     title: 'Конкуренция',
     desc: 'Къде има висок дял „една оферта“ и концентрация на доставчици.',
   },
+  {
+    href: '/quality',
+    title: 'Индекс на качеството',
+    desc: 'Колко здрав е процесът по всеки договор: пет измерения, една оценка 0–100.',
+  },
 ] as const;
 
 export const ANALYTICS_NAV_PATHS = [

apps/web/app/lib/etl.ts

@@ -0,0 +1,5 @@
+/** True for the expected "table doesn't exist yet" error the daily ETL derive can leave behind
+ * (before the first derive, or mid-rebuild since ship-domain drops+recreates contract_features). */
+export function isMissingDerivedTableError(err: unknown): boolean {
+  return /no such table/i.test(err instanceof Error ? err.message : String(err));
+}

apps/web/app/lib/filters.test.ts

@@ -9,6 +9,7 @@ import {
   MAX_MULTI_VALUES,
   pageNav,
   PARAM_ORDER,
+  qualityRankingControls,
   searchHref,
   withParams,
 } from './filters';
@@ -344,6 +345,53 @@ describe('pageNav', () => {
   });
 });
 
+describe('qualityRankingControls', () => {
+  it('parses the /quality „Разбивка" controls the loader consumes', () => {
+    expect(qualityRankingControls(sp('rdir=desc&rfrom=10&rto=60'))).toEqual({
+      rankDir: 'desc',
+      rankFrom: 10,
+      rankTo: 60,
+    });
+    expect(qualityRankingControls(sp(''))).toEqual({
+      rankDir: null,
+      rankFrom: null,
+      rankTo: null,
+    });
+  });
+
+  it('accepts only asc|desc for ?rdir — anything else falls back to the default order', () => {
+    expect(qualityRankingControls(sp('rdir=asc')).rankDir).toBe('asc');
+    expect(qualityRankingControls(sp('rdir=down')).rankDir).toBeNull();
+    expect(qualityRankingControls(sp('rdir=DESC')).rankDir).toBeNull();
+    expect(qualityRankingControls(sp("rdir=asc'--")).rankDir).toBeNull();
+  });
+
+  it('validates ?rfrom/?rto as ints in [0, 100] and drops malformed bounds (CWE-349)', () => {
+    expect(qualityRankingControls(sp('rfrom=0&rto=100'))).toMatchObject({
+      rankFrom: 0,
+      rankTo: 100,
+    });
+    expect(qualityRankingControls(sp('rfrom=35')).rankFrom).toBe(35); // one-sided range is fine
+    expect(qualityRankingControls(sp('rto=35')).rankTo).toBe(35);
+    expect(qualityRankingControls(sp('rfrom=101')).rankFrom).toBeNull();
+    expect(qualityRankingControls(sp('rfrom=-1')).rankFrom).toBeNull();
+    expect(qualityRankingControls(sp('rfrom=1.5')).rankFrom).toBeNull();
+    expect(qualityRankingControls(sp('rfrom=abc')).rankFrom).toBeNull();
+    expect(qualityRankingControls(sp('rfrom=5 OR 1=1')).rankFrom).toBeNull();
+    expect(qualityRankingControls(sp('rfrom=1000')).rankFrom).toBeNull();
+  });
+
+  it('swaps an inverted ?rfrom/?rto pair so the range is always from ≤ to', () => {
+    const f = qualityRankingControls(sp('rfrom=60&rto=10'));
+    expect(f.rankFrom).toBe(10);
+    expect(f.rankTo).toBe(60);
+    // from = to pins a single display value — kept, not dropped
+    const pin = qualityRankingControls(sp('rfrom=69&rto=69'));
+    expect(pin.rankFrom).toBe(69);
+    expect(pin.rankTo).toBe(69);
+  });
+});
+
 describe('withParams', () => {
   it('drops unknown params — including repeated ones — so none can ride a link into the edge cache (#197)', () => {
     expect(withParams(sp('sort=value-desc&x=poison'), {})).toBe('?sort=value-desc');