Hartmut/CapaKraken
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(api): explain dashboard chargeability by chapter

Browse Source
This commit is contained in:
Hartmut Nörenberg
2026-03-31 23:34:03 +02:00
parent a8fcc4dacb
commit 703406a76b
7 changed files with 403 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/api/src/__tests__/assistant-tools-dashboard-detail.test.ts
+54 -1
View File
@@ -4,6 +4,7 @@ import { SystemRole } from "@capakraken/shared";
import {
createToolContext,
executeTool,
getDashboardChargeabilityOverview,
getDashboardDemand,
getDashboardOverview,
getDashboardPeakTimes,
@@ -139,6 +140,38 @@ describe("assistant dashboard tools detail aggregation", () => {
},
},
]);
vi.mocked(getDashboardChargeabilityOverview).mockResolvedValue({
rows: [
{
id: "res_1",
eid: "pparker",
displayName: "Peter Parker",
chapter: "Delivery",
chargeabilityTarget: 78,
actualChargeability: 70,
expectedChargeability: 76,
derivation: {
weeklyAvailabilityHours: 40,
baseWorkingDays: 22,
effectiveWorkingDayEquivalent: 21,
baseAvailableHours: 176,
effectiveAvailableHours: 168,
publicHolidayCount: 1,
publicHolidayWorkdayCount: 1,
publicHolidayHoursDeduction: 8,
absenceDayEquivalent: 0,
absenceHoursDeduction: 0,
actualBookedHours: 117.6,
expectedBookedHours: 127.7,
targetBookedHours: 131,
unassignedHours: 40.3,
},
},
],
top: [],
watchlist: [],
month: "2026-03",
});
const ctx = createToolContext(
{
@@ -263,8 +296,28 @@ describe("assistant dashboard tools detail aggregation", () => {
chargeabilityByChapter: [
{
chapter: "Delivery",
headcount: 4,
headcount: 1,
avgTargetPct: 78,
avgActualPct: 70,
avgExpectedPct: 76,
gapToTargetPct: 8,
avgTarget: "78%",
avgActual: "70%",
avgExpected: "76%",
explainability: {
month: "2026-03",
resourceCount: 1,
derivedHeadcount: 1,
baseAvailableHours: 176,
effectiveAvailableHours: 168,
actualBookedHours: 117.6,
expectedBookedHours: 127.7,
targetBookedHours: 131,
publicHolidayHoursDeduction: 8,
absenceDayEquivalent: 0,
absenceHoursDeduction: 0,
unassignedHours: 40.3,
},
},
],
});
packages/api/src/__tests__/assistant-tools-dashboard-test-helpers.ts
+81
View File
@@ -0,0 +1,81 @@
import { PermissionKey, SystemRole } from "@capakraken/shared";
import { vi } from "vitest";
vi.mock("@capakraken/application", async (importOriginal) => {
const actual = await importOriginal<typeof import("@capakraken/application")>();
return {
...actual,
getDashboardDemand: vi.fn().mockResolvedValue([]),
getDashboardBudgetForecast: vi.fn().mockResolvedValue([]),
getDashboardChargeabilityOverview: vi.fn().mockResolvedValue({
rows: [],
top: [],
watchlist: [],
month: "2026-03",
}),
getDashboardOverview: vi.fn(),
getDashboardSkillGapSummary: vi.fn().mockResolvedValue({
roleGaps: [],
totalOpenPositions: 0,
skillSupplyTop10: [],
resourcesByRole: [],
}),
getDashboardProjectHealth: vi.fn().mockResolvedValue([]),
getDashboardPeakTimes: vi.fn().mockResolvedValue([]),
getDashboardTopValueResources: vi.fn().mockResolvedValue([]),
listAssignmentBookings: vi.fn().mockResolvedValue([]),
};
});
vi.mock("../lib/cache.js", () => ({
cacheGet: vi.fn().mockResolvedValue(null),
cacheSet: vi.fn().mockResolvedValue(undefined),
cacheInvalidate: vi.fn().mockResolvedValue(undefined),
invalidateDashboardCache: vi.fn().mockResolvedValue(undefined),
}));
import {
getDashboardChargeabilityOverview as getDashboardChargeabilityOverviewMock,
getDashboardDemand as getDashboardDemandMock,
getDashboardOverview as getDashboardOverviewMock,
getDashboardProjectHealth as getDashboardProjectHealthMock,
getDashboardPeakTimes as getDashboardPeakTimesMock,
getDashboardSkillGapSummary as getDashboardSkillGapSummaryMock,
getDashboardTopValueResources as getDashboardTopValueResourcesMock,
} from "@capakraken/application";
import { executeTool as executeAssistantTool, type ToolContext } from "../router/assistant-tools.js";
export const executeTool = executeAssistantTool;
export const getDashboardChargeabilityOverview = getDashboardChargeabilityOverviewMock;
export const getDashboardDemand = getDashboardDemandMock;
export const getDashboardOverview = getDashboardOverviewMock;
export const getDashboardProjectHealth = getDashboardProjectHealthMock;
export const getDashboardPeakTimes = getDashboardPeakTimesMock;
export const getDashboardSkillGapSummary = getDashboardSkillGapSummaryMock;
export const getDashboardTopValueResources = getDashboardTopValueResourcesMock;
export function createToolContext(
db: Record<string, unknown>,
options?: {
permissions?: PermissionKey[];
userRole?: SystemRole;
},
): ToolContext {
const userRole = options?.userRole ?? SystemRole.ADMIN;
return {
db: db as ToolContext["db"],
userId: "user_1",
userRole,
permissions: new Set(options?.permissions ?? []),
session: {
user: { email: "assistant@example.com", name: "Assistant User", image: null },
expires: "2026-03-29T00:00:00.000Z",
},
dbUser: {
id: "user_1",
systemRole: userRole,
permissionOverrides: null,
},
roleDefaults: null,
};
}
packages/api/src/__tests__/dashboard-procedure-support.test.ts
+62 -1
View File
@@ -225,6 +225,38 @@ describe("dashboard procedure support", () => {
},
},
]);
vi.mocked(getDashboardChargeabilityOverview).mockResolvedValue({
rows: [
{
id: "res_1",
eid: "E-001",
displayName: "Ada Lovelace",
chapter: "CGI",
chargeabilityTarget: 78,
actualChargeability: 64,
expectedChargeability: 72,
derivation: {
weeklyAvailabilityHours: 40,
baseWorkingDays: 23,
effectiveWorkingDayEquivalent: 21,
baseAvailableHours: 184,
effectiveAvailableHours: 168,
publicHolidayCount: 1,
publicHolidayWorkdayCount: 1,
publicHolidayHoursDeduction: 8,
absenceDayEquivalent: 1,
absenceHoursDeduction: 8,
actualBookedHours: 107.5,
expectedBookedHours: 121,
targetBookedHours: 131,
unassignedHours: 47,
},
},
],
top: [],
watchlist: [],
month: "2026-03",
});
try {
const result = await getDashboardDetail(createContext(), { section: "all" });
@@ -298,11 +330,40 @@ describe("dashboard procedure support", () => {
chargeabilityByChapter: [
{
chapter: "CGI",
headcount: 5,
headcount: 1,
avgTargetPct: 78,
avgActualPct: 64,
avgExpectedPct: 72,
gapToTargetPct: 14,
avgTarget: "78%",
avgActual: "64%",
avgExpected: "72%",
explainability: {
month: "2026-03",
resourceCount: 1,
derivedHeadcount: 1,
baseAvailableHours: 184,
effectiveAvailableHours: 168,
actualBookedHours: 107.5,
expectedBookedHours: 121,
targetBookedHours: 131,
publicHolidayHoursDeduction: 8,
absenceDayEquivalent: 1,
absenceHoursDeduction: 8,
unassignedHours: 47,
},
},
],
});
expect(getDashboardChargeabilityOverview).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({
includeProposed: false,
topN: 10,
watchlistThreshold: 15,
}),
);
} finally {
vi.useRealTimers();
}
packages/api/src/__tests__/dashboard-router.test.ts
+61 -1
View File
@@ -838,6 +838,38 @@ describe("dashboard router", () => {
},
},
]);
vi.mocked(getDashboardChargeabilityOverview).mockResolvedValue({
rows: [
{
id: "res_1",
eid: "pparker",
displayName: "Peter Parker",
chapter: "Delivery",
chargeabilityTarget: 78,
actualChargeability: 70,
expectedChargeability: 76,
derivation: {
weeklyAvailabilityHours: 40,
baseWorkingDays: 22,
effectiveWorkingDayEquivalent: 21,
baseAvailableHours: 176,
effectiveAvailableHours: 168,
publicHolidayCount: 1,
publicHolidayWorkdayCount: 1,
publicHolidayHoursDeduction: 8,
absenceDayEquivalent: 0,
absenceHoursDeduction: 0,
actualBookedHours: 117.6,
expectedBookedHours: 127.7,
targetBookedHours: 131,
unassignedHours: 40.3,
},
},
],
top: [],
watchlist: [],
month: "2026-03",
});
const caller = createControllerCaller({});
const result = await caller.getDetail({ section: "all" });
@@ -929,8 +961,28 @@ describe("dashboard router", () => {
chargeabilityByChapter: [
{
chapter: "Delivery",
headcount: 4,
headcount: 1,
avgTargetPct: 78,
avgActualPct: 70,
avgExpectedPct: 76,
gapToTargetPct: 8,
avgTarget: "78%",
avgActual: "70%",
avgExpected: "76%",
explainability: {
month: "2026-03",
resourceCount: 1,
derivedHeadcount: 1,
baseAvailableHours: 176,
effectiveAvailableHours: 168,
actualBookedHours: 117.6,
expectedBookedHours: 127.7,
targetBookedHours: 131,
publicHolidayHoursDeduction: 8,
absenceDayEquivalent: 0,
absenceHoursDeduction: 0,
unassignedHours: 40.3,
},
},
],
});
@@ -943,6 +995,14 @@ describe("dashboard router", () => {
groupBy: "project",
}),
);
expect(getDashboardChargeabilityOverview).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({
includeProposed: false,
topN: 10,
watchlistThreshold: 15,
}),
);
});
});
});
packages/api/src/router/dashboard-procedure-support.ts
+134 -27
View File
@@ -74,11 +74,16 @@ type DashboardTopValueResourcesInput = z.infer<typeof dashboardTopValueResources
type DashboardDemandInput = z.infer<typeof dashboardDemandInputSchema>;
type DashboardDetailInput = z.infer<typeof dashboardDetailInputSchema>;
type DashboardChargeabilityOverviewInput = z.infer<typeof dashboardChargeabilityOverviewInputSchema>;
type DashboardChargeabilityOverviewRead = Awaited<ReturnType<typeof getDashboardChargeabilityOverview>>;
function round1(value: number): number {
return Math.round(value * 10) / 10;
}
function formatPct(value: number): string {
return `${Math.round(value)}%`;
}
function mapStatisticsDetail(overview: Awaited<ReturnType<typeof getDashboardOverview>>) {
return {
activeResources: overview.activeResources,
@@ -148,6 +153,25 @@ async function getDemandCached(
return result;
}
async function getChargeabilityOverviewCached(
db: Parameters<typeof getDashboardChargeabilityOverview>[0],
input: DashboardChargeabilityOverviewInput,
): Promise<DashboardChargeabilityOverviewRead> {
const cacheKey = `chargeability:${input.includeProposed}:${input.topN}:${input.watchlistThreshold}:${(input.countryIds ?? []).join(",")}:${input.departed ?? ""}`;
const cached = await cacheGet<DashboardChargeabilityOverviewRead>(cacheKey);
if (cached) return cached;
const result = await getDashboardChargeabilityOverview(db, {
includeProposed: input.includeProposed,
topN: input.topN,
watchlistThreshold: input.watchlistThreshold,
...(input.countryIds !== undefined ? { countryIds: input.countryIds } : {}),
...(input.departed !== undefined ? { departed: input.departed } : {}),
});
await cacheSet(cacheKey, result, DEFAULT_TTL);
return result;
}
async function getTopValueResourcesCached(
db: Parameters<typeof getDashboardTopValueResources>[0],
input: { limit: number; userRole: string },
@@ -174,6 +198,101 @@ function getUserRole(ctx: DashboardProcedureContext) {
?? "USER";
}
function mapChargeabilityByChapter(
rows: DashboardChargeabilityOverviewRead["rows"],
month: string,
) {
const chapterMap = new Map<string, {
headcount: number;
avgTargetSum: number;
avgActualSum: number;
avgExpectedSum: number;
derivedHeadcount: number;
baseAvailableHours: number;
effectiveAvailableHours: number;
actualBookedHours: number;
expectedBookedHours: number;
targetBookedHours: number;
publicHolidayHoursDeduction: number;
absenceDayEquivalent: number;
absenceHoursDeduction: number;
unassignedHours: number;
}>();
for (const row of rows) {
const chapter = row.chapter ?? "Unassigned";
const summary = chapterMap.get(chapter) ?? {
headcount: 0,
avgTargetSum: 0,
avgActualSum: 0,
avgExpectedSum: 0,
derivedHeadcount: 0,
baseAvailableHours: 0,
effectiveAvailableHours: 0,
actualBookedHours: 0,
expectedBookedHours: 0,
targetBookedHours: 0,
publicHolidayHoursDeduction: 0,
absenceDayEquivalent: 0,
absenceHoursDeduction: 0,
unassignedHours: 0,
};
summary.headcount += 1;
summary.avgTargetSum += row.chargeabilityTarget;
summary.avgActualSum += row.actualChargeability;
summary.avgExpectedSum += row.expectedChargeability;
if (row.derivation) {
summary.derivedHeadcount += 1;
summary.baseAvailableHours += row.derivation.baseAvailableHours;
summary.effectiveAvailableHours += row.derivation.effectiveAvailableHours;
summary.actualBookedHours += row.derivation.actualBookedHours;
summary.expectedBookedHours += row.derivation.expectedBookedHours;
summary.targetBookedHours += row.derivation.targetBookedHours;
summary.publicHolidayHoursDeduction += row.derivation.publicHolidayHoursDeduction;
summary.absenceDayEquivalent += row.derivation.absenceDayEquivalent;
summary.absenceHoursDeduction += row.derivation.absenceHoursDeduction;
summary.unassignedHours += row.derivation.unassignedHours;
}
chapterMap.set(chapter, summary);
}
return [...chapterMap.entries()]
.map(([chapter, summary]) => ({
chapter,
headcount: summary.headcount,
avgTargetPct: Math.round(summary.avgTargetSum / summary.headcount),
avgActualPct: Math.round(summary.avgActualSum / summary.headcount),
avgExpectedPct: Math.round(summary.avgExpectedSum / summary.headcount),
gapToTargetPct: Math.round((summary.avgTargetSum - summary.avgActualSum) / summary.headcount),
avgTarget: formatPct(summary.avgTargetSum / summary.headcount),
avgActual: formatPct(summary.avgActualSum / summary.headcount),
avgExpected: formatPct(summary.avgExpectedSum / summary.headcount),
explainability: summary.derivedHeadcount > 0
? {
month,
resourceCount: summary.headcount,
derivedHeadcount: summary.derivedHeadcount,
baseAvailableHours: round1(summary.baseAvailableHours),
effectiveAvailableHours: round1(summary.effectiveAvailableHours),
actualBookedHours: round1(summary.actualBookedHours),
expectedBookedHours: round1(summary.expectedBookedHours),
targetBookedHours: round1(summary.targetBookedHours),
publicHolidayHoursDeduction: round1(summary.publicHolidayHoursDeduction),
absenceDayEquivalent: round1(summary.absenceDayEquivalent),
absenceHoursDeduction: round1(summary.absenceHoursDeduction),
unassignedHours: round1(summary.unassignedHours),
}
: null,
}))
.sort((left, right) => (
right.headcount - left.headcount
|| left.chapter.localeCompare(right.chapter)
));
}
export async function getDashboardOverviewRead(ctx: DashboardProcedureContext) {
return getOverviewCached(ctx.db);
}
@@ -211,7 +330,6 @@ export async function getDashboardDetail(ctx: DashboardProcedureContext, input:
section === "all"
|| section === "peak_times"
|| section === "demand_pipeline"
|| section === "chargeability_overview"
);
const overview = needsOverview ? await getOverviewCached(ctx.db) : null;
const now = new Date();
@@ -309,11 +427,15 @@ export async function getDashboardDetail(ctx: DashboardProcedureContext, input:
}
if (section === "all" || section === "chargeability_overview") {
result.chargeabilityByChapter = (overview?.chapterUtilization ?? []).map((chapter) => ({
chapter: chapter.chapter ?? "Unassigned",
headcount: chapter.resourceCount,
avgTarget: `${Math.round(chapter.avgChargeabilityTarget)}%`,
}));
const chargeabilityOverview = await getChargeabilityOverviewCached(ctx.db, {
includeProposed: false,
topN: 10,
watchlistThreshold: 15,
});
result.chargeabilityByChapter = mapChargeabilityByChapter(
chargeabilityOverview.rows,
chargeabilityOverview.month,
);
}
return result;
@@ -323,32 +445,17 @@ export async function getDashboardChargeabilityOverviewRead(
ctx: DashboardProcedureContext,
input: DashboardChargeabilityOverviewInput,
) {
const cacheKey = `chargeability:${input.includeProposed}:${input.topN}:${input.watchlistThreshold}:${(input.countryIds ?? []).join(",")}:${input.departed ?? ""}`;
const cached = await cacheGet<{
top: unknown[];
watchlist: unknown[];
[key: string]: unknown;
}>(cacheKey);
if (cached) return cached;
const [overview, directory] = await Promise.all([
getDashboardChargeabilityOverview(ctx.db, {
includeProposed: input.includeProposed,
topN: input.topN,
watchlistThreshold: input.watchlistThreshold,
...(input.countryIds !== undefined ? { countryIds: input.countryIds } : {}),
...(input.departed !== undefined ? { departed: input.departed } : {}),
}),
getChargeabilityOverviewCached(ctx.db, input),
getAnonymizationDirectory(ctx.db),
]);
const { rows: _rows, top, watchlist, ...rest } = overview;
const result = {
...overview,
top: anonymizeResources(overview.top, directory),
watchlist: anonymizeResources(overview.watchlist, directory),
return {
...rest,
top: anonymizeResources(top, directory),
watchlist: anonymizeResources(watchlist, directory),
};
await cacheSet(cacheKey, result, DEFAULT_TTL);
return result;
}
export async function getDashboardBudgetForecastRead(
packages/application/src/__tests__/dashboard.test.ts
+2
View File
@@ -646,6 +646,7 @@ describe("dashboard use-cases", () => {
}),
}),
);
expect(result.rows).toHaveLength(1);
expect(result.top).toHaveLength(1);
expect(result.top[0]).toEqual(
expect.objectContaining({
@@ -778,6 +779,7 @@ describe("dashboard use-cases", () => {
watchlistThreshold: 15,
});
expect(result.rows).toHaveLength(1);
expect(result.top[0]?.actualChargeability).toBe(0);
expect(result.top[0]?.expectedChargeability).toBe(0);
expect(result.top[0]).toEqual(
packages/application/src/use-cases/dashboard/get-chargeability-overview.ts
+9 -1
View File
@@ -65,6 +65,13 @@ export interface DashboardChargeabilityRow {
derivation?: DashboardChargeabilityDerivation;
}
export interface DashboardChargeabilityOverview {
rows: DashboardChargeabilityRow[];
top: DashboardChargeabilityRow[];
watchlist: DashboardChargeabilityRow[];
month: string;
}
function toIsoDate(value: Date): string {
return value.toISOString().slice(0, 10);
}
@@ -160,7 +167,7 @@ function summarizeDerivation(
export async function getDashboardChargeabilityOverview(
db: PrismaClient,
input: GetDashboardChargeabilityOverviewInput,
) {
): Promise<DashboardChargeabilityOverview> {
const now = input.now ?? new Date();
const start = new Date(now.getFullYear(), now.getMonth(), 1);
const end = new Date(now.getFullYear(), now.getMonth() + 1, 0);
@@ -294,6 +301,7 @@ export async function getDashboardChargeabilityOverview(
});
return {
rows: stats,
top: [...stats]
.sort((left, right) => right.actualChargeability - left.actualChargeability),
watchlist: [...stats]