fix(web): stop reporting unreported CafeF ratio periods as zero

VCB and MBB showed EPS, BVPS, ROE and ROA as 0 on the stock page, and their
Financials tab charted a plunge to zero for those years.

The cause is in the source: CafeF returns a bucket for every period but fills
unreported ones with zeros across every ratio. VCB's 2025 and 2023 buckets carry
EPS, BVPS, ROE, ROA *and* P/E at 0 — impossible for a company with a share price.
We read only the newest bucket and passed its zeros straight through, and zero is
not null, so the `?? null` fallbacks never fired.

A bucket whose ratios are all zero is now treated as "not reported". The stats
grid asks for four buckets and uses the newest one CafeF actually filled in, and
labels it with that year (`EPS ’22`) so a lagging figure is not read as current.
The Financials tab drops those periods rather than charting them.

The test is per bucket rather than per metric on purpose: a genuine zero, such as
a debt-free company's Debt/Assets, still comes through.

Verified against the raw source — VCB's 2025 and 2023 buckets are 0/8 non-zero
and are the only ones dropped; FPT's every bucket is 8/8 non-zero and nothing is
dropped (its missing 2022 is absent from CafeF's response to begin with). VCB now
reads EPS 5,820 ₫, BVPS 28,660 ₫, ROE 22.04%, ROA 1.65% for 2022, and its annual
series runs 2017–2022 with no zero columns.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: toreleon

web/README.md

@@ -74,6 +74,18 @@ Finance's information architecture and visual language. The UI defaults to the
   fails. CafeF substitutes a generic house placeholder for imageless articles; the server filters
   that out so those rows simply have no picture rather than a fake one.
 
+### A note on CafeF's ratio periods
+
+CafeF returns a bucket for every period but fills unreported ones with **zeros across every
+ratio** — VCB's 2025 and 2023 buckets carry EPS, BVPS, ROE, ROA *and* P/E at 0, which cannot be
+real for a company that has a share price. Banks lag like this routinely.
+
+The server therefore treats a bucket whose ratios are *all* zero as "not reported": the stats
+grid falls back to the newest period CafeF has actually filled in (and labels it, e.g. `EPS ’22`,
+so a lagging figure isn't read as current), and the Financials tab omits those periods instead of
+charting a plunge to zero. The test is per bucket, not per metric, so a genuine zero — a
+debt-free company's Debt/Assets — still comes through.
+
 Watchlists and portfolios are persisted in the shared Azoth SQLite database (`~/.azoth/azoth.db`)
 under `web_*` tables — no separate datastore, no broker credentials.
 
@@ -135,7 +147,7 @@ pnpm typecheck # type-check the frontend
 | `GET /api/indicators/:ticker?range=` | SMA/EMA/Bollinger/RSI/MACD |
 | `GET /api/news/:ticker` | Ticker news |
 | `GET /api/about/:ticker` | Company profile + related stocks |
-| `GET /api/financials/:ticker?period=annual` | Annual key metrics (EPS, BVPS, ROE, ROA, margins, P/E) from CafeF |
+| `GET /api/financials/:ticker?period=annual` | Annual key metrics (EPS, BVPS, ROE, ROA, margins, P/E) from CafeF. Periods CafeF hasn't reported are omitted, not charted as zero |
 
 ### Persistent (SQLite-backed `web_*` tables)
 

web/server/index.ts

@@ -31,6 +31,7 @@ import {
   getTickerNews,
   getCompanyIntro,
   getFinancialRatios,
+  type CafefRatioBucket,
 } from "../../src/data/sources/cafef.js";
 import { TICKER_UNIVERSES } from "../../src/tools/discover.js";
 import {
@@ -630,6 +631,7 @@ async function handleQuote(ticker: string) {
       bvps_thousand_vnd: fund.bvps,
       roe_pct: fund.roe,
       roa_pct: fund.roa,
+      ratios_year: fund.ratiosYear,
       dividend_yield_pct: fund.divYield,
       shares_outstanding: fund.shares,
       foreign_ownership_pct: fund.foreignOwn,
@@ -681,10 +683,13 @@ async function fundamentalsBundle(ticker: string): Promise<FundBundle> {
       latestRatio(ticker, RATIOS.FOREIGN_OWNERSHIP),
       getCompanyProfile(ticker).catch(() => null),
       getCompanyIntro(ticker).catch(() => null),
-      getFinancialRatios(ticker, "QUY", 1).catch(() => []),
+      getFinancialRatios(ticker, "QUY", 4).catch(() => []),
     ]);
+    // Newest-first, so the first reported bucket is the latest one CafeF has
+    // actually filled in. Banks routinely lag a year or two behind.
+    const reported = cafef.find(isReportedPeriod);
     const latestCafef: Record<string, number> = {};
-    for (const v of cafef[0]?.Value ?? []) latestCafef[v.Code] = v.Value;
+    for (const v of reported?.Value ?? []) latestCafef[v.Code] = v.Value;
     return {
       company: {
         nameVi: profile?.vnName,
@@ -711,6 +716,8 @@ async function fundamentalsBundle(ticker: string): Promise<FundBundle> {
       bvps: latestCafef.BV ?? null,
       roe: latestCafef.ROE ?? null,
       roa: latestCafef.ROA ?? null,
+      // Which year those four came from — they can lag, so the UI labels them.
+      ratiosYear: reported?.Year ?? null,
       divYield: round(divYield, 2),
       shares: round(shares, 0),
       foreignOwn: round(foreignOwn, 2),
@@ -1008,6 +1015,17 @@ async function handleSearch(q: string) {
 // Financials (quarterly / annual key metrics from CafeF)
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether CafeF actually reported a ratio period. It returns a bucket for every
+ * period but fills unreported ones with zeros across the board — VCB's 2025 and
+ * 2023 buckets carry EPS, BV, ROE, ROA *and* P/E at 0, which cannot be real for
+ * a company with a share price. Judging this per bucket rather than per metric
+ * keeps a genuine zero (a debt-free company's Debt/Assets) intact.
+ */
+function isReportedPeriod(bucket: CafefRatioBucket): boolean {
+  return (bucket.Value ?? []).some((v) => Number.isFinite(v.Value) && v.Value !== 0);
+}
+
 const CAFEF_METRICS: { key: string; code: string; label: string; unit: "kVND" | "%" | "x" }[] = [
   { key: "eps", code: "EPS", label: "EPS", unit: "kVND" },
   { key: "bvps", code: "BV", label: "BVPS", unit: "kVND" },
@@ -1027,9 +1045,10 @@ async function handleFinancials(ticker: string, period: string) {
     () => getFinancialRatios(ticker, reportType, 8).catch(() => []),
   );
   // CafeF returns newest-first; reverse to oldest→newest for charts/tables.
+  // Unreported periods are dropped rather than charted as a plunge to zero.
   // NB: CafeF's ratios dataset is annual (Quater is 0), so we label by year and
   // only prefix a quarter when CafeF actually reports one (1–4).
-  const ordered = [...buckets].reverse();
+  const ordered = buckets.filter(isReportedPeriod).reverse();
   const hasQuarter = (q: number | undefined): q is number => q != null && q >= 1 && q <= 4;
   const columns = ordered.map((b) => ({
     label: hasQuarter(b.Quater) ? `Q${b.Quater} ${b.Year ?? ""}`.trim() : `${b.Year ?? ""}`,

web/src/components/StatsGrid.tsx

@@ -15,6 +15,10 @@ type Cell = {
 export default function StatsGrid({ quote }: StatsGridProps) {
   const s = quote.stats;
 
+  // CafeF's ratios lag for some issuers (banks especially), so name the year
+  // these four came from rather than implying they're current.
+  const fy = s.ratios_year ? ` ’${String(s.ratios_year).slice(-2)}` : "";
+
   const cells: Cell[] = [
     { label: "Open", value: fmtPriceVnd(s.open) },
     { label: "High", value: fmtPriceVnd(s.high) },
@@ -28,10 +32,10 @@ export default function StatsGrid({ quote }: StatsGridProps) {
     { label: "P/E ratio", value: fmtNum(s.pe) },
     { label: "P/B ratio", value: fmtNum(s.pb) },
     { label: "P/S ratio", value: fmtNum(s.ps) },
-    { label: "EPS", value: fmtPriceVnd(s.eps_thousand_vnd) },
-    { label: "BVPS", value: fmtPriceVnd(s.bvps_thousand_vnd) },
-    { label: "ROE", value: fmtPctPlain(s.roe_pct) },
-    { label: "ROA", value: fmtPctPlain(s.roa_pct) },
+    { label: `EPS${fy}`, value: fmtPriceVnd(s.eps_thousand_vnd) },
+    { label: `BVPS${fy}`, value: fmtPriceVnd(s.bvps_thousand_vnd) },
+    { label: `ROE${fy}`, value: fmtPctPlain(s.roe_pct) },
+    { label: `ROA${fy}`, value: fmtPctPlain(s.roa_pct) },
     { label: "Div yield", value: fmtPctPlain(s.dividend_yield_pct) },
     { label: "Foreign own", value: fmtPctPlain(s.foreign_ownership_pct) },
     { label: "Shares out", value: fmtBigNum(s.shares_outstanding) },

web/src/lib/types.ts

@@ -151,6 +151,8 @@ export interface QuoteStats {
   bvps_thousand_vnd: number | null;
   roe_pct: number | null;
   roa_pct: number | null;
+  /** Year the EPS/BVPS/ROE/ROA above were reported for — CafeF's ratios can lag. */
+  ratios_year: number | null;
   dividend_yield_pct: number | null;
   shares_outstanding: number | null;
   foreign_ownership_pct: number | null;