Files
knowledge-governance/web/src/qaDashboardData.ts
T
姚章浩 cb9f0c389f
build / build (push) Successful in 1m10s
feat(qaops): 看板改用自然月质量指标并增加统计口径
去掉看板个人月明细;十一卡悬停和键盘可读的真实统计范围、公式与排除数。
自然月独立计算;跨月周取周一所在月,保留旧周证据和已存周报正文。

验证:make verify;一次性PG全镜像套件-race;真实恢复数据7个月与周报calc_metrics对拍。
真实浏览器十一卡逐项悬停、Tab/Escape、30秒刷新、跨月周、390px和完整PNG通过。
没有写DobotAI源问答、触发付费模型、外发或应用新迁移。
2026-10-21 08:48:55 +08:00

509 lines
18 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { parseQAOrganizationVersion } from './qaOps'
import { currentQAWeek } from './qaWeeks'
import type { QAOrganizationVersion, QAQuery } from './qaOps'
import { parseQualitySummary, parseQualityRate } from './qaQuality'
import type { QualitySummary, QualityRate } from './qaQuality'
export interface DashboardCount {
label: string
count: number
}
export interface DashboardReported {
week: string
week_start: string
week_end: string
coverage_percent: number
correctness_percent: number
source: 'user_provided_history'
}
export interface DashboardFrozen {
week_start: string
week_end: string
frozen_at: string | null
policy_version: string
records: number
coverage: QualityRate
correctness: QualityRate
}
export interface DashboardCumulative {
week: string
week_start: string
week_end: string
cutoff_at: string
calculated_at: string
records: number
coverage: QualityRate
correctness: QualityRate
source: 'master_live_cumulative_v1'
policy_version: 'weekly-strict-yes-over-yes-no-v1'
}
export interface DashboardStrictQuality {
records: number
coverage: QualityRate
correctness: QualityRate
}
export interface DashboardQualityPeriod {
month: string
start: string
cutoff_at: string
calculated_at: string
source: 'master_live_calendar_month_v1'
policy_version: 'calendar-month-strict-yes-over-yes-no-v1'
}
export interface DashboardMonth extends DashboardStrictQuality {
month: string
month_start: string
month_end: string
cutoff_at: string
calculated_at: string
source: 'master_live_calendar_month_v1'
policy_version: 'calendar-month-strict-yes-over-yes-no-v1'
}
export interface DashboardRegion {
id: string
name: string
questions: number
users: number | null
roster_people: number | null
frequency: number | null
usage_coverage: QualityRate
}
export interface QADashboardData {
start: string
end: string
keyword: string
as_of: string
local_revision: number
organization: QAOrganizationVersion
total_issues: number
new_this_week: number
week_start: string
month_start: string
quality: QualitySummary['summary']
issue_types: DashboardCount[]
products: DashboardCount[]
daily: { date: string; count: number }[]
regions: DashboardRegion[]
frozen_weeks: DashboardFrozen[]
reported_weeks: DashboardReported[]
cumulative_weeks?: DashboardCumulative[]
quality_period?: DashboardQualityPeriod
monthly_quality?: DashboardStrictQuality
calendar_months?: DashboardMonth[]
}
const bad = (): never => {
throw new Error('统计看板响应无效,未展示可能失真的指标')
}
const obj = (v: unknown): Record<string, unknown> =>
v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : bad()
const text = (v: unknown): string => (typeof v === 'string' ? v : bad())
const count = (v: unknown): number => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : bad())
const stamp = (v: unknown): string => {
const s = text(v)
return Number.isFinite(Date.parse(s)) ? s : bad()
}
const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : bad())
const dayMS = 86400000,
offset = 8 * 3600000
const day = (at: number) => Math.floor((at + offset) / dayMS) * dayMS - offset
const monday = (at: number) => {
const d = day(at)
return d - ((new Date(d + offset).getUTCDay() + 6) % 7) * dayMS
}
const month = (at: number) => {
const d = new Date(at + offset)
return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1) - offset
}
function categories(value: unknown, total: number): DashboardCount[] {
const seen = new Set<string>()
const out = list(value).map((raw) => {
const v = obj(raw),
label = text(v.label),
n = count(v.count)
if (!label || seen.has(label) || !n) return bad()
seen.add(label)
return { label, count: n }
})
if (out.reduce((n, r) => n + r.count, 0) !== total) return bad()
return out
}
export function parseQADashboard(value: unknown): QADashboardData {
const v = obj(value),
start = stamp(v.start),
end = stamp(v.end),
keyword = text(v.keyword),
as_of = stamp(v.as_of),
week_start = stamp(v.week_start),
month_start = stamp(v.month_start)
if (
Date.parse(start) >= Date.parse(end) ||
Date.parse(week_start) !== monday(Date.parse(end) - 1) ||
Date.parse(month_start) !== month(Date.parse(end) - 1)
)
return bad()
const quality = parseQualitySummary({
summary: v.quality,
start,
end,
keyword,
as_of,
scope: 'whole_filter',
ai_state: 'not_configured',
}).summary
const organization = parseQAOrganizationVersion(v.organization),
total_issues = count(v.total_issues),
new_this_week = count(v.new_this_week)
if (new_this_week > total_issues || quality.total > total_issues) return bad()
const regionIDs = new Set<string>(),
regionNames = new Set<string>()
const regions = list(v.regions).map((raw) => {
const r = obj(raw),
id = text(r.id),
name = text(r.name),
questions = count(r.questions),
users = r.users === null ? null : count(r.users),
roster_people = r.roster_people === null ? null : count(r.roster_people),
usage_coverage = parseQualityRate(r.usage_coverage)
if (!id || !name || regionIDs.has(id) || regionNames.has(name) || !organization.region_names?.includes(name))
return bad()
regionIDs.add(id)
regionNames.add(name)
if (
(users === null) !== (roster_people === null) ||
(users !== null && roster_people !== null && users > roster_people)
)
return bad()
if (usage_coverage.numerator !== (users ?? 0) || usage_coverage.denominator !== (roster_people ?? 0)) return bad()
let frequency: number | null = null
if (roster_people !== null && roster_people > 0) {
if (
typeof r.frequency !== 'number' ||
!Number.isFinite(r.frequency) ||
r.frequency < 0 ||
Math.abs(r.frequency - questions / roster_people) > 1e-8
)
return bad()
frequency = r.frequency
} else if (r.frequency !== null) return bad()
return { id, name, questions, users, roster_people, frequency, usage_coverage }
})
if (regions.length !== (organization.region_names?.length ?? 0)) return bad()
const daily = list(v.daily).map((raw, i) => {
const d = obj(raw),
date = text(d.date),
n = count(d.count)
if (
!/^\d{4}-\d{2}-\d{2}$/.test(date) ||
Date.parse(date + 'T00:00:00+08:00') !== Date.parse(week_start) + i * dayMS
)
return bad()
return { date, count: n }
})
if (
daily.length < 1 ||
daily.length > 7 ||
daily.reduce((n, r) => n + r.count, 0) !== new_this_week ||
Date.parse(daily[daily.length - 1].date + 'T00:00:00+08:00') >= Date.parse(end)
)
return bad()
const frozen_weeks = list(v.frozen_weeks).map((raw, i) => {
const p = obj(raw),
week_start = stamp(p.week_start),
week_end = stamp(p.week_end),
frozen_at = p.frozen_at === null ? null : stamp(p.frozen_at),
policy_version = text(p.policy_version),
records = count(p.records),
coverage = parseQualityRate(p.coverage),
correctness = parseQualityRate(p.correctness)
if (
monday(Date.parse(week_start)) !== Date.parse(week_start) ||
Date.parse(week_end) - Date.parse(week_start) !== 7 * dayMS ||
Date.parse(week_start) >= Date.parse(end) ||
coverage.denominator > records ||
correctness.denominator > records
)
return bad()
if (frozen_at === null) {
if (policy_version || records || coverage.denominator || correctness.denominator) return bad()
} else if (!policy_version || Date.parse(frozen_at) < Date.parse(week_end)) return bad()
const previous = list(v.frozen_weeks)[i - 1]
if (i > 0 && Date.parse(week_start) !== Date.parse(text(obj(previous).week_end))) return bad()
return { week_start, week_end, frozen_at, policy_version, records, coverage, correctness }
})
if (
frozen_weeks.length > 5200 ||
(frozen_weeks.length && Date.parse(frozen_weeks[frozen_weeks.length - 1].week_end) < Date.parse(end))
)
return bad()
const reported_weeks = list(v.reported_weeks === undefined ? [] : v.reported_weeks).map((raw, i) => {
const p = obj(raw),
week = text(p.week),
begin = stamp(p.week_start),
finish = stamp(p.week_end)
const iso = currentQAWeek(new Date(begin))
const percent = (value: unknown) =>
typeof value === 'number' &&
Number.isFinite(value) &&
value >= 0 &&
value <= 100 &&
Math.abs(value * 100 - Math.round(value * 100)) < 1e-8
? value
: bad()
if (
Object.keys(p).some(
(k) => !['week', 'week_start', 'week_end', 'coverage_percent', 'correctness_percent', 'source'].includes(k)
) ||
keyword !== '' ||
p.source !== 'user_provided_history' ||
week !== `${iso.year}WK${String(iso.week).padStart(2, '0')}` ||
monday(Date.parse(begin)) !== Date.parse(begin) ||
Date.parse(finish) - Date.parse(begin) !== 7 * dayMS ||
Date.parse(finish) > Date.parse(end)
)
return bad()
if (i > 0 && Date.parse(begin) <= Date.parse(text(obj(list(v.reported_weeks)[i - 1]).week_start))) return bad()
return {
week,
week_start: begin,
week_end: finish,
coverage_percent: percent(p.coverage_percent),
correctness_percent: percent(p.correctness_percent),
source: 'user_provided_history' as const,
}
})
if (reported_weeks.length > 5200) return bad()
const cumulative_weeks = list(v.cumulative_weeks === undefined ? [] : v.cumulative_weeks).map(
(raw, i): DashboardCumulative => {
const p = obj(raw),
begin = stamp(p.week_start),
finish = stamp(p.week_end),
cutoff = stamp(p.cutoff_at),
calculated = stamp(p.calculated_at),
records = count(p.records),
coverage = parseQualityRate(p.coverage),
correctness = parseQualityRate(p.correctness),
iso = currentQAWeek(new Date(begin))
const previous = i ? obj(list(v.cumulative_weeks)[i - 1]) : null
if (
i >= 4 ||
Date.parse(begin) !== Date.parse('2026-09-28T00:00:00+08:00') + i * 7 * dayMS ||
text(p.week) !== `${iso.year}WK${String(iso.week).padStart(2, '0')}` ||
Date.parse(finish) - Date.parse(begin) !== 7 * dayMS ||
Date.parse(cutoff) <= Date.parse(begin) ||
Date.parse(cutoff) !== Math.min(Date.parse(finish), Date.parse(end), Date.parse(calculated)) ||
p.source !== 'master_live_cumulative_v1' ||
p.policy_version !== 'weekly-strict-yes-over-yes-no-v1' ||
records > total_issues ||
coverage.denominator > records ||
correctness.denominator > records ||
Object.keys(p).some(
(k) =>
![
'week',
'week_start',
'week_end',
'cutoff_at',
'calculated_at',
'records',
'coverage',
'correctness',
'source',
'policy_version',
].includes(k)
) ||
(previous &&
(Date.parse(text(previous.cutoff_at)) !== Date.parse(text(previous.week_end)) ||
records < count(previous.records) ||
Date.parse(calculated) !== Date.parse(text(previous.calculated_at))))
)
return bad()
return {
week: text(p.week),
week_start: begin,
week_end: finish,
cutoff_at: cutoff,
calculated_at: calculated,
records,
coverage,
correctness,
source: 'master_live_cumulative_v1',
policy_version: 'weekly-strict-yes-over-yes-no-v1',
}
}
)
let quality_period: DashboardQualityPeriod | undefined
let monthly_quality: DashboardStrictQuality | undefined
let calendar_months: DashboardMonth[] | undefined
const monthlySource = 'master_live_calendar_month_v1' as const,
monthlyPolicy = 'calendar-month-strict-yes-over-yes-no-v1' as const,
nextMonth = (at: number) => {
const d = new Date(at + offset)
return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1) - offset
},
monthLabel = (at: number) => new Date(at + offset).toISOString().slice(0, 7),
strictRates = (raw: Record<string, unknown>): DashboardStrictQuality => {
const records = count(raw.records),
coverage = parseQualityRate(raw.coverage),
correctness = parseQualityRate(raw.correctness)
if (records > total_issues || coverage.denominator > records || correctness.denominator > records) return bad()
return { records, coverage, correctness }
}
if (
v.quality_period !== undefined ||
v.monthly_quality !== undefined ||
(v.calendar_months !== undefined && list(v.calendar_months).length)
) {
const p = obj(v.quality_period),
begin = stamp(p.start),
cutoff = stamp(p.cutoff_at),
calculated = stamp(p.calculated_at),
expectedBegin = month(Date.parse(week_start))
if (
p.source !== monthlySource ||
p.policy_version !== monthlyPolicy ||
text(p.month) !== monthLabel(expectedBegin) ||
Date.parse(begin) !== expectedBegin ||
Date.parse(cutoff) <= expectedBegin ||
Date.parse(cutoff) !== Math.min(nextMonth(expectedBegin), Date.parse(end), Date.parse(calculated))
)
return bad()
if (
Object.keys(p).some(
(key) => !['month', 'start', 'cutoff_at', 'calculated_at', 'source', 'policy_version'].includes(key)
)
)
return bad()
const rawQuality = obj(v.monthly_quality)
if (Object.keys(rawQuality).some((key) => !['records', 'coverage', 'correctness'].includes(key))) return bad()
quality_period = {
month: text(p.month),
start: begin,
cutoff_at: cutoff,
calculated_at: calculated,
source: monthlySource,
policy_version: monthlyPolicy,
}
monthly_quality = strictRates(rawQuality)
const rawMonths = list(v.calendar_months)
calendar_months = rawMonths.map((raw, i): DashboardMonth => {
const point = obj(raw),
month_start = stamp(point.month_start),
month_end = stamp(point.month_end),
cutoff_at = stamp(point.cutoff_at),
calculated_at = stamp(point.calculated_at),
at = Date.parse(month_start),
rates = strictRates(point)
if (
at !== month(at) ||
text(point.month) !== monthLabel(at) ||
Date.parse(month_end) !== nextMonth(at) ||
Date.parse(cutoff_at) <= at ||
Date.parse(cutoff_at) !== Math.min(Date.parse(month_end), Date.parse(cutoff), Date.parse(calculated_at)) ||
calculated_at !== calculated ||
point.source !== monthlySource ||
point.policy_version !== monthlyPolicy ||
(i > 0 && at !== Date.parse(text(obj(rawMonths[i - 1]).month_end)))
)
return bad()
if (
Object.keys(point).some(
(key) =>
![
'month',
'month_start',
'month_end',
'cutoff_at',
'calculated_at',
'records',
'coverage',
'correctness',
'source',
'policy_version',
].includes(key)
)
)
return bad()
return {
month: text(point.month),
month_start,
month_end,
cutoff_at,
calculated_at,
...rates,
source: monthlySource,
policy_version: monthlyPolicy,
}
})
if (calendar_months.length > 1200 || calendar_months.reduce((n, point) => n + point.records, 0) > total_issues)
return bad()
const last = calendar_months.at(-1)
if (last) {
if (
last.month !== quality_period.month ||
last.cutoff_at !== quality_period.cutoff_at ||
last.records !== monthly_quality.records ||
JSON.stringify(last.coverage) !== JSON.stringify(monthly_quality.coverage) ||
JSON.stringify(last.correctness) !== JSON.stringify(monthly_quality.correctness)
)
return bad()
} else if (monthly_quality.records !== 0) return bad()
}
return {
quality_period,
monthly_quality,
calendar_months,
start,
end,
keyword,
as_of,
week_start,
month_start,
reported_weeks,
cumulative_weeks,
local_revision: count(v.local_revision),
organization,
total_issues,
new_this_week,
quality,
issue_types: categories(v.issue_types, quality.total),
products: categories(v.products, quality.total),
daily,
regions,
frozen_weeks,
}
}
export function liveDashboardQuery(query: QAQuery, now: Date): QAQuery {
const last = currentQAWeek(new Date(Date.parse(query.end) - 1)),
current = currentQAWeek(now)
if (
last.year !== current.year ||
last.week !== current.week ||
Date.parse(query.end) >= now.getTime() ||
now.getTime() - Date.parse(query.start) > 90 * dayMS
)
return query
return { ...query, end: now.toISOString() }
}
export async function fetchQADashboard(query: QAQuery, signal?: AbortSignal): Promise<QADashboardData> {
const response = await fetch('/api/v1/qa-ops/dashboard', {
method: 'POST',
credentials: 'same-origin',
cache: 'no-store',
signal,
headers: { 'Content-Type': 'application/json', 'X-Governance-Action': 'qa-dashboard' },
body: JSON.stringify({ start: query.start, end: query.end, keyword: query.keyword }),
})
const body: unknown = await response.json().catch(() => null)
if (!response.ok) {
const message = body && typeof body === 'object' ? (body as Record<string, unknown>).error : undefined
throw new Error(typeof message === 'string' ? message : `统计看板读取失败(HTTP ${response.status})`)
}
const data = parseQADashboard(obj(body).data)
if (
Date.parse(data.start) !== Date.parse(query.start) ||
Date.parse(data.end) !== Date.parse(query.end) ||
data.keyword !== query.keyword
)
throw new Error('看板返回范围与当前查询不一致,请重新读取')
return data
}