《独立开发者的商业指南·收入与财务工程》10.3 复盘会与决策记录

// file: src/fin/review.ts
// tier: L1
// verify: node --test test/fin/review.test.ts

import { type Cents } from "../core/money.ts";
import { type Result, fail, ok } from "../core/result.ts";
import {
  type Variance,
  type VarianceDirection,
  measureVariance,
} from "./variance.ts";

export type ReasonKind =
  | "volume"
  | "price"
  | "mix"
  | "cost"
  | "timing"
  | "one_off";

export const REASON_KINDS: ReasonKind[] = [
  "volume",
  "price",
  "mix",
  "cost",
  "timing",
  "one_off",
];

export type Reason = {
  kind: ReasonKind;
  statement: string;
  evidence: string;
  falsifier: string;
};

export type Decision = {
  statement: string;
  owner: string;
  dueDate: string;
};

export type Verification = {
  metric: string;
  target: string;
  dueDate: string;
};

export type ReviewInput = {
  period: string;
  actual: Cents;
  budget: Cents;
  direction: VarianceDirection;
  reasons: Reason[];
  decision: Decision | null;
  verification: Verification[];
};

export type ReviewRecord = {
  period: string;
  variance: Variance;
  reasons: Reason[];
  decision: Decision | null;
  verification: Verification[];
  missing: string[];
  complete: boolean;
};

function filled(value: string): boolean {
  return typeof value === "string" && value.trim().length > 0;
}

function checkDecision(decision: Decision): string | null {
  if (!filled(decision.statement)) {
    return "decision statement is required";
  }
  if (!filled(decision.owner)) {
    return "decision owner is required";
  }
  if (!filled(decision.dueDate)) {
    return "decision due date is required";
  }
  return null;
}

function checkVerification(item: Verification): string | null {
  if (!filled(item.metric)) {
    return "verification metric is required";
  }
  if (!filled(item.target)) {
    return "verification target is required";
  }
  if (!filled(item.dueDate)) {
    return "verification due date is required";
  }
  return null;
}

/**
 * A review record is allowed to be incomplete. Structural errors fail, but a
 * missing reason, decision or verification point is recorded in `missing`
 * instead of being rejected. The draft is still worth keeping: next month it
 * shows exactly what the review could not answer at the time.
 */
export function buildReview(input: ReviewInput): Result<ReviewRecord> {
  if (!filled(input.period)) {
    return fail("period is required");
  }
  if (!Array.isArray(input.reasons)) {
    return fail("reasons must be an array");
  }
  if (!Array.isArray(input.verification)) {
    return fail("verification must be an array");
  }
  for (const reason of input.reasons) {
    if (!reason || !REASON_KINDS.includes(reason.kind)) {
      return fail("unknown reason kind");
    }
    if (
      !filled(reason.statement) ||
      !filled(reason.evidence) ||
      !filled(reason.falsifier)
    ) {
      return fail("each reason needs a statement, evidence and falsifier");
    }
  }
  const decision = input.decision ?? null;
  if (decision !== null) {
    const decisionError = checkDecision(decision);
    if (decisionError) {
      return fail(decisionError);
    }
  }
  for (const item of input.verification) {
    const verificationError = checkVerification(item);
    if (verificationError) {
      return fail(verificationError);
    }
  }
  const variance = measureVariance(input.actual, input.budget, input.direction);
  if (!variance.ok) {
    return variance;
  }
  const missing: string[] = [];
  if (input.reasons.length !== 3) {
    missing.push("exactly three reasons");
  }
  if (decision === null) {
    missing.push("one decision");
  }
  if (input.verification.length === 0) {
    missing.push("at least one verification");
  }
  const record: ReviewRecord = {
    period: input.period,
    variance: variance.value,
    reasons: input.reasons,
    decision,
    verification: input.verification,
    missing,
    complete: missing.length === 0,
  };
  return ok(record);
}

/**
 * The first line of the next review. Its job is to force a re-computation of
 * last month's decision, not to summarize the record.
 */
export function nextReviewPrompt(record: ReviewRecord): string {
  if (record.decision === null) {
    return "上一期没有决策，本期只做复算，不追责。";
  }
  const metrics = record.verification.map((item) => item.metric).join("、");
  return `复算：${record.decision.statement}；验证点：${metrics}。`;
}