feat(web): surface talent-graph need-coverage / gap analysis in the UI

The backend shipped GET /talent-graph/opportunities/:id/coverage and
talentGapAnalysisService (ARCHITECTURE §3.1 CQ#7 — "which required skills does
the pool cover, and which are unmet gaps?") but no web client consumed it.
Institutions could see top candidates yet not their skill gaps.

- talentGraphService: add getOpportunityCoverage() + NeedCoverageAnalysis,
  SkillCoverage, CoverageStrength types mirroring the backend contract.
- talent-network page: fetch coverage alongside matches for the selected
  opportunity and render a "Beceri kapsama" panel — per-skill strength badges
  (verified/evidenced/interest/unmet), the unmet-skill gap list, coverage ratio
  and roll-up status. Coverage is a public read (skill tokens + counts only, no
  private free text), so it renders for any viewer of the need.
- CSS: coverage panel styled in the existing Swiss/editorial system.
- tests: web service test for the coverage endpoint (path + shape).

Additive, read-only slice. No backend changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
caelum0x 2026-08-26 17:11:33 +03:00
parent d5042aae7f
commit 7275b79df9
4 changed files with 164 additions and 0 deletions

View File

@ -3,7 +3,9 @@
import { FormEvent, useEffect, useMemo, useRef, useState } from 'react'
import Link from 'next/link'
import {
CoverageStrength,
CreateTalentOpportunityInput,
NeedCoverageAnalysis,
TalentMatch,
TalentOpportunity,
TalentPilot,
@ -50,6 +52,19 @@ const GUIDE_STEPS = [
},
] as const
const COVERAGE_STRENGTH_LABELS: Record<CoverageStrength, string> = {
verified: 'Doğrulanmış',
evidenced: 'Kanıtlı',
interest: 'İlgi',
unmet: 'Boşluk',
}
const COVERAGE_STATUS_LABELS: Record<NeedCoverageAnalysis['status'], string> = {
'fully-covered': 'Tam kapsanıyor',
'partially-covered': 'Kısmen kapsanıyor',
unmet: 'Kapsanmıyor',
}
const EMPTY_FORM: CreateTalentOpportunityInput = {
organizationName: '',
title: '',
@ -133,6 +148,9 @@ export default function TalentNetworkPage() {
const [matchesLoading, setMatchesLoading] = useState(false)
const [matchesError, setMatchesError] = useState<string | null>(null)
const [matchesRequest, setMatchesRequest] = useState(0)
const [coverage, setCoverage] = useState<NeedCoverageAnalysis | null>(null)
const [coverageLoading, setCoverageLoading] = useState(false)
const [coverageError, setCoverageError] = useState<string | null>(null)
const [submitting, setSubmitting] = useState(false)
const [myPilots, setMyPilots] = useState<TalentPilot[]>([])
const [pilotsLoading, setPilotsLoading] = useState(true)
@ -258,6 +276,24 @@ export default function TalentNetworkPage() {
return () => { active = false }
}, [matchesRequest, selectedId])
useEffect(() => {
if (!selectedId) {
setCoverage(null)
setCoverageError(null)
setCoverageLoading(false)
return
}
let active = true
setCoverage(null)
setCoverageError(null)
setCoverageLoading(true)
talentGraphService.getOpportunityCoverage(selectedId)
.then((result) => active && setCoverage(result.coverage))
.catch(() => active && setCoverageError('Beceri kapsama servisi yanıt vermedi.'))
.finally(() => active && setCoverageLoading(false))
return () => { active = false }
}, [matchesRequest, selectedId])
async function createOpportunity(event: FormEvent<HTMLFormElement>) {
event.preventDefault()
const requiredSkills = skillsText.split(',').map((skill) => skill.trim().toLowerCase()).filter(Boolean)
@ -530,6 +566,42 @@ export default function TalentNetworkPage() {
)}
</article>
)}
{!opportunitiesLoading && !opportunitiesError && selected && (coverageLoading || coverageError || coverage) && (
<article className={styles.coverage} aria-live="polite" aria-busy={coverageLoading}>
<div className={styles.coverageHead}>
<span>Beceri kapsama</span>
{coverage && (
<strong data-status={coverage.status}>
{COVERAGE_STATUS_LABELS[coverage.status]} · %{Math.round(coverage.coverageRatio * 100)}
</strong>
)}
</div>
{coverageLoading && <p className={styles.empty}>GitGram aday havuzunun beceri kapsamasını hesaplıyor.</p>}
{!coverageLoading && coverageError && (
<div className={styles.resourceError} role="alert">
<p>{coverageError}</p>
<button type="button" onClick={() => setMatchesRequest((request) => request + 1)}>Kapsamayı yeniden hesapla</button>
</div>
)}
{!coverageLoading && !coverageError && coverage && (
<>
<ul className={styles.coverageSkills}>
{coverage.coverage.map((entry) => (
<li key={entry.skill} data-strength={entry.strength}>
<span className={styles.coverageSkill}>{entry.skill}</span>
<span className={styles.coverageStrength}>{COVERAGE_STRENGTH_LABELS[entry.strength]}</span>
<span className={styles.coverageCount}>{entry.candidateCount} aday</span>
</li>
))}
</ul>
{coverage.unmetSkills.length > 0 && (
<p className={styles.coverageGap}>Kapsanmayan beceriler: {coverage.unmetSkills.join(', ')}</p>
)}
<p className={styles.coverageNote}>{coverage.candidatePool} aday havuzu üzerinden hesaplandı.</p>
</>
)}
</article>
)}
{!opportunitiesLoading && matchesLoading && <p className={styles.empty}>GitGram depo ve pilot kanıtlarını karşılaştırıyor.</p>}
{!opportunitiesLoading && !matchesLoading && matchesError && selected && (
<div className={styles.resourceError} role="alert">

View File

@ -233,3 +233,21 @@
.create form { grid-template-columns: 1fr; }
.create .full { grid-column: 1; }
}
.coverage { padding: 28px 3vw; border-bottom: 1px solid var(--ink); background: var(--ground); }
.coverageHead { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; }
.coverageHead > span { color: var(--red); font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; }
.coverageHead > strong { font-size: 13px; font-weight: 700; font-variant-numeric: tabular-nums; }
.coverageHead > strong[data-status="unmet"] { color: var(--red); }
.coverageSkills { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 10px; margin: 18px 0 0; padding: 0; list-style: none; }
.coverageSkills li { display: grid; gap: 6px; padding: 12px 14px; background: var(--paper); border: 1px solid var(--rule); }
.coverageSkills li[data-strength="verified"] { border-color: var(--ink); border-left: 4px solid var(--ink); }
.coverageSkills li[data-strength="evidenced"] { border-left: 4px solid var(--ink); }
.coverageSkills li[data-strength="interest"] { border-left: 4px solid var(--rule); }
.coverageSkills li[data-strength="unmet"] { border-left: 4px solid var(--red); }
.coverageSkill { font-size: 13px; font-weight: 700; word-break: break-word; }
.coverageStrength { font-size: 10px; text-transform: uppercase; letter-spacing: 0.04em; }
.coverageSkills li[data-strength="unmet"] .coverageStrength { color: var(--red); }
.coverageCount { font-size: 10px; color: var(--ink); opacity: 0.7; font-variant-numeric: tabular-nums; }
.coverageGap { margin: 16px 0 0; font-size: 12px; font-weight: 700; color: var(--red); }
.coverageNote { margin: 8px 0 0; font-size: 10px; text-transform: uppercase; letter-spacing: 0.04em; }

View File

@ -170,6 +170,25 @@ export interface TalentMatch {
}>
}
export type CoverageStrength = 'verified' | 'evidenced' | 'interest' | 'unmet'
export interface SkillCoverage {
skill: string
strength: CoverageStrength
candidateCount: number
evidencedCount: number
verifiedCount: number
}
export interface NeedCoverageAnalysis {
requiredSkills: string[]
coverage: SkillCoverage[]
unmetSkills: string[]
coverageRatio: number
status: 'fully-covered' | 'partially-covered' | 'unmet'
candidatePool: number
}
export interface CreateTalentOpportunityInput {
organizationName: string
title: string
@ -207,6 +226,11 @@ export const talentGraphService = {
return data.data
},
getOpportunityCoverage: async (id: string): Promise<{ opportunity: TalentOpportunity; coverage: NeedCoverageAnalysis }> => {
const { data } = await api.get<{ data: { opportunity: TalentOpportunity; coverage: NeedCoverageAnalysis } }>(`/talent-graph/opportunities/${encodeURIComponent(id)}/coverage`)
return data.data
},
startPilot: async (opportunityId: string, participantId: string, milestones: string[], idempotencyKey: string): Promise<TalentPilot> => {
const { data } = await api.post<{ data: TalentPilot }>(`/talent-graph/opportunities/${encodeURIComponent(opportunityId)}/pilots`, { participantId, milestones }, mutationConfig(idempotencyKey))
return data.data

View File

@ -0,0 +1,50 @@
/// <reference types="vitest/globals" />
import { describe, it, expect, beforeEach } from 'vitest'
import MockAdapter from 'axios-mock-adapter'
import api from '@/services/api'
import { talentGraphService, type NeedCoverageAnalysis } from '@/services/talentGraphService'
const mock = new MockAdapter(api)
describe('talentGraphService.getOpportunityCoverage', () => {
beforeEach(() => {
mock.reset()
})
it('reads the coverage endpoint and returns the gap analysis for an opportunity', async () => {
const coverage: NeedCoverageAnalysis = {
requiredSkills: ['javascript', 'kubernetes'],
coverage: [
{ skill: 'javascript', strength: 'verified', candidateCount: 3, evidencedCount: 2, verifiedCount: 1 },
{ skill: 'kubernetes', strength: 'unmet', candidateCount: 0, evidencedCount: 0, verifiedCount: 0 },
],
unmetSkills: ['kubernetes'],
coverageRatio: 0.5,
status: 'partially-covered',
candidatePool: 4,
}
mock.onGet('/v1/talent-graph/opportunities/opp-1/coverage').reply(200, {
data: { opportunity: { id: 'opp-1' }, coverage },
})
const result = await talentGraphService.getOpportunityCoverage('opp-1')
expect(result.opportunity.id).toBe('opp-1')
expect(result.coverage.status).toBe('partially-covered')
expect(result.coverage.unmetSkills).toEqual(['kubernetes'])
expect(result.coverage.coverage[0].strength).toBe('verified')
})
it('encodes the opportunity id in the request path', async () => {
let requestedUrl = ''
mock.onGet(/\/talent-graph\/opportunities\/.*\/coverage/).reply((config) => {
requestedUrl = config.url || ''
return [200, { data: { opportunity: { id: 'a/b' }, coverage: { requiredSkills: [], coverage: [], unmetSkills: [], coverageRatio: 0, status: 'unmet', candidatePool: 0 } } }]
})
await talentGraphService.getOpportunityCoverage('a/b')
expect(requestedUrl).toContain('/talent-graph/opportunities/a%2Fb/coverage')
})
})