Peach: Local-first video metadata scraper and media manager.
/* 人工复核页的数据契约、分组分页纯函数与写操作。三条端点在 `frontend/src` 里都只在这里
* 声明一次(`tests/test_frontend_build.py` 盯着)。
*
* `['review']` 是整条复核队列。接口一次给出全部分类的可复核行,不重复传候选 CSV 的
* JSON 字符串;各分类合在一个响应里,所以也只用一个 `queryKey`:分类切换是翻这一份的
* 不同段落,不是另一份真相。判定写回来时只把那几行从缓存里摘掉(`dropReviewRows`),
* 不为一次判定把整条队列重取一遍。
*
* 分组、筛选、分页都是纯函数:工具条上的计数说的是整条队列,卡片只画当前这一页,两边
* 用同一套判据算,各写一份迟早对不上。 */
import { apiGet, apiSend } from '../../api';
import { clampPage, pageCount } from '../../pagination';
import { selectRange } from '../../selection';
import { queryClient } from '../query';
import { localTime } from '../time';
export const REVIEW_URL = '/api/review';
export const REVIEW_DECISION_URL = '/api/review/decision';
export const REVIEW_GENRE_URL = '/api/review/genre';
/** 整条复核队列。 */
export const REVIEW_KEY = ['review'] as const;
/** 复核分类与它们在界面上的名字。次序就是页签次序。 */
export const REVIEW_LABELS = {
metadata_fields: '元数据字段',
creator_tags: '创作者标签',
studio_logos: '厂牌 Logo',
performer_avatars: '女优头像',
western_identity: '西方身份回配',
code_creators: '番号目录存疑',
fc2_markings: 'FC2 评论标记',
fc2_similarity: 'FC2 跨号相似',
video_endcards: '片尾/出处证据',
} as const;
export type ReviewCategory = keyof typeof REVIEW_LABELS;
export const REVIEW_CATEGORIES = Object.keys(REVIEW_LABELS) as ReviewCategory[];
export const DEFAULT_CATEGORY: ReviewCategory = 'metadata_fields';
export const isReviewCategory = (value: unknown): value is ReviewCategory =>
typeof value === 'string' && Object.hasOwn(REVIEW_LABELS, value);
/** 主体是实体而不是单条作品的分类,值就是实体 kind。这张表与 `web_review.py` 的
* `ENTITY_REVIEW_KINDS` 必须逐字一致:这边判成 creator、取图按 performer,
* 就是标志说有图而请求照样 404。 */
export const ENTITY_REVIEW_KINDS: Partial<Record<ReviewCategory, string>> = {
creator_tags: 'creator', western_identity: 'creator',
};
/** 默认每页 20 张;接口读取整条队列,页面按所选数量挂载候选表单。 */
export const REVIEW_PAGE_SIZE = 20;
export interface CatalogEvidence { display_value?: string; warnings?: string[] }
/** 一个来源给出的候选值。选中它就是把 `display_value` 写进数据库。 */
export interface ReviewCandidate {
candidate_key: string;
source?: string;
official?: boolean;
content_id?: string;
provider_id?: string;
display_value?: string;
warnings?: string[];
/** 同一来源顺带交回来的其它字段,只作判断依据。 */
catalog_evidence?: Record<string, CatalogEvidence>;
/** 静态词表还没收录的 genre。 */
unmapped_genres?: string[];
}
/** 卡片上那几张图背后的作品。 */
export interface ReviewAsset {
id: number;
name?: string;
code?: string;
preview_url?: string;
has_preview?: boolean;
}
/** 队列里的一行。字段以 `src/peach/web_review.py` 的 `_review_rows` 为准,各分类共用这一份
* 形状,用不上的项缺席。 */
export interface ReviewRow {
item_key: string;
queue_order?: number;
decision?: string;
status?: string;
candidates?: ReviewCandidate[];
field?: string;
field_label?: string;
current_value?: string;
current_owner?: string;
query?: string;
code?: string;
creator?: string;
studio?: string;
current_name?: string;
name?: string;
board?: string;
source?: string;
/** 数据库规范名当标题时,来源自己的写法留在这里。 */
source_name?: string;
/** 竖线分隔的候选标签。 */
tags?: string;
reason?: string;
evidence?: string;
note?: string;
decision_note?: string;
japanese_name?: string;
path?: string;
suggested_query?: string;
preview_url?: string;
preview_assets?: ReviewAsset[];
comparison_assets?: ReviewAsset[];
asset_id?: number;
asset_name?: string;
asset_preview_url?: string;
asset_path?: string;
asset_mutation_revision?: number | null;
entity_id?: number;
has_image?: boolean;
image_version?: string;
avatar_focus?: unknown;
avatar_url?: string;
video_count?: number;
videos?: number | string;
assets?: number;
babepedia_name?: string;
profile_url?: string;
}
/** 只读端读到的是写入端队列的镜像,页面要说清这一份是实时的还是缓存的。 */
export interface ReviewMirror {
state?: string;
origin?: string | null;
fetched_at?: string | null;
error?: string | null;
read_only?: boolean;
}
export const REVIEW_QUEUES = ['pending', 'later', 'ignored'] as const;
export type ReviewQueue = typeof REVIEW_QUEUES[number];
export const REVIEW_QUEUE_LABELS: Record<ReviewQueue, string> = {
pending: '待处理', later: '稍后处理', ignored: '已忽略',
};
export const REVIEW_DECISION_LABELS: Record<string, string> = {
approved: '已通过', rejected: '已忽略', skipped: '稍后处理',
};
export const reviewQueueOf = (value: unknown): ReviewQueue =>
value === 'later' || value === 'ignored' ? value : 'pending';
export interface ReviewQueueData {
sections: Partial<Record<ReviewCategory, ReviewRow[]>>;
counts: Partial<Record<ReviewCategory, number>>;
}
export interface ReviewData extends ReviewQueueData {
queues: Record<Exclude<ReviewQueue, 'pending'>, ReviewQueueData>;
/** 收录 genre 时的候选词表:静态表已经投影到的那批内容标签。 */
genre_tags?: string[];
mirror?: ReviewMirror | null;
}
export const reviewQueueData = (data: ReviewData, queue: ReviewQueue): ReviewQueueData =>
queue === 'pending' ? { sections: data.sections, counts: data.counts } : data.queues[queue];
function mapReviewQueues(data: ReviewData, transform: (snapshot: ReviewQueueData) => ReviewQueueData): ReviewData {
return { ...data, ...transform(reviewQueueData(data, 'pending')),
queues: { later: transform(data.queues.later), ignored: transform(data.queues.ignored) } };
}
/* ── 分组、筛选、分页 ── */
export type ReviewGrouping = 'candidates' | 'source' | 'field';
export interface ReviewGroup { key: string; title: string; rows: ReviewRow[] }
/** 这一批队列能按什么分组。按来源、按字段两档要队列里真有那一项才出现。 */
export function reviewGroupingOptions(rows: ReviewRow[], metadata: boolean): [ReviewGrouping, string][] {
const options: [ReviewGrouping, string][] = [
['candidates', metadata ? '按来源数量' : '不分组'],
];
if (rows.some((row) => row.source || row.candidates?.some((candidate) => candidate.source))) {
options.push(['source', '按来源']);
}
if (rows.some((row) => row.field)) options.push(['field', '按字段']);
return options;
}
/** 按来源组合分组,每个作品字段只出现一次。 */
export function groupReviewRows(rows: ReviewRow[], by: ReviewGrouping): ReviewGroup[] {
const groups = new Map<string, ReviewGroup>();
for (const row of rows) {
let key: string;
let title: string;
if (by === 'field') {
key = row.field || '__unspecified_field';
title = row.field_label || row.field || '未标注字段';
} else if (by === 'source') {
const sources = [...new Set((row.candidates?.map((candidate) => candidate.source || '')
|| [row.source || '']).filter(Boolean))].sort();
key = JSON.stringify(sources);
title = sources.join(' / ') || '未标注来源';
} else {
key = row.candidates ? (row.candidates.length === 1 ? 'single' : 'multiple') : 'pending';
title = key === 'single' ? '单一来源' : key === 'multiple' ? '需选择来源' : '资料';
}
if (!groups.has(key)) groups.set(key, { key, title, rows: [] });
groups.get(key)!.rows.push(row);
}
return [...groups.values()];
}
/** 先按分组筛,再切页。顺序反过来的话,筛选说的就成了「这一屏里符合的那几条」。 */
export function filterReviewRows(
rows: ReviewRow[], by: ReviewGrouping, filter: string,
): ReviewRow[] {
if (!filter) return rows;
return groupReviewRows(rows, by).find((group) => group.key === filter)?.rows || rows;
}
export interface ReviewWindow { page: number; pages: number; rows: ReviewRow[] }
/** 按每页数量切片,页码越界时收回到最后一页。 */
export function reviewWindow(rows: ReviewRow[], page: number, pageSize = REVIEW_PAGE_SIZE): ReviewWindow {
const pages = pageCount(rows.length, pageSize);
const current = clampPage(page, pages);
return {
page: current,
pages,
rows: rows.slice((current - 1) * pageSize, current * pageSize),
};
}
/** 所选项目都有、且各自只出现一次的来源。统一选来源只能在这些里选:同一来源在一行里
* 给了两个值时,「统一选 javdb」就没有唯一答案。 */
export function commonReviewSources(rows: ReviewRow[]): string[] {
if (!rows.length) return [];
return [...new Set(rows.flatMap((row) => row.candidates?.map((candidate) => candidate.source || '') || []))]
.filter((source) => source && rows.every(
(row) => row.candidates?.filter((candidate) => candidate.source === source).length === 1));
}
/** Shift 按当前显示顺序扩展选择,与馆藏页同一套语义。返回新的锚点。 */
export function selectReviewRange(
selected: Set<string>, keys: string[], anchor: string | null,
key: string, range: boolean, checked: boolean,
): string {
return selectRange(selected, keys, anchor, key, range, checked);
}
/* ── 一行能做什么 ── */
/** 这一行能不能通过。元数据字段要有候选;创作者标签只判 `candidate` 状态的那些。 */
export function canApprove(category: ReviewCategory, row: ReviewRow): boolean {
if (category === 'metadata_fields') return (row.candidates?.length || 0) > 0;
if (category === 'creator_tags') return String(row.status || '').trim() === 'candidate';
return true;
}
/** 这一行的标题读作「问的是什么」。字段名是问题本身,作品标识只是它问的对象。 */
export function rowSubject(category: ReviewCategory, row: ReviewRow): string {
if (category === 'metadata_fields') return String(row.query || row.code || '');
return String(row.creator || row.studio || row.current_name || row.name || row.item_key);
}
export const rowFieldName = (category: ReviewCategory, row: ReviewRow): string =>
(category === 'metadata_fields' ? String(row.field_label || row.field || '').trim() : '');
export function rowTitle(category: ReviewCategory, row: ReviewRow): string {
const subject = rowSubject(category, row);
const field = rowFieldName(category, row);
return field ? `${subject} · ${field}` : subject;
}
export const rowEvidence = (row: ReviewRow): string =>
row.reason || row.evidence || row.note || row.decision_note || '';
export const rowTags = (row: ReviewRow): string[] =>
String(row.tags || '').split('|').filter(Boolean);
/** 这一行等着被收录的 genre。同一个词在几个来源里各出现一次时只问一遍。 */
export const pendingGenres = (row: ReviewRow): string[] =>
[...new Set((row.candidates || []).flatMap((candidate) => candidate.unmapped_genres || []))];
/** 一行此刻的选择:选了哪个来源值、勾了哪几条作品。 */
export interface RowChoice { candidateKey: string; assets: number[] }
/** 还没动过的行按默认值算:只有一个候选时它就是选中的那个,作品样本默认全勾。 */
export function defaultChoice(row: ReviewRow): RowChoice {
const candidates = row.candidates || [];
return {
candidateKey: candidates.length === 1 ? candidates[0]!.candidate_key : '',
assets: (row.preview_assets || []).map((asset) => asset.id),
};
}
export type DecisionStatus = 'approved' | 'rejected' | 'skipped' | 'restore';
/** 交给 `/api/review/decision` 的那一份。
*
* 乐观并发只在这一行钉死了一条资产时带上:按番号命中多条的组没有单一 revision 可报,
* 硬报一个只会在同番号分卷上换来一串假冲突。 */
export function decisionPayload(
category: ReviewCategory, row: ReviewRow, status: DecisionStatus, choice: RowChoice,
): Record<string, unknown> {
const pinned = !!row.asset_path && row.asset_mutation_revision != null;
return {
category,
item_key: row.item_key,
status,
candidate_key: choice.candidateKey,
creator: row.creator,
tags: row.tags,
studio: row.studio,
entity_id: row.entity_id,
avatar_url: row.avatar_url,
selected_ids: choice.assets,
...(pinned ? { expected_revision: row.asset_mutation_revision } : {}),
};
}
export const decisionReceipt = (status: DecisionStatus): string => ({
approved: '已通过资料', rejected: '已忽略资料', skipped: '已移至稍后处理', restore: '已恢复待处理',
})[status];
/* ── 取数与写操作 ── */
export async function fetchReview(signal?: AbortSignal): Promise<ReviewData> {
const data = await apiGet<ReviewData>(REVIEW_URL, signal);
for (const key of ['later', 'ignored'] as const) {
if (!data.queues?.[key]?.sections || !data.queues[key].counts) {
throw new Error(`${REVIEW_QUEUE_LABELS[key]}状态未取得,请刷新或更新写入端`);
}
}
return data;
}
export interface DecisionResult {
ok: boolean;
error?: string;
asset_revisions?: Record<string, { before: number; after: number }>;
}
export async function submitDecision(payload: Record<string, unknown>): Promise<DecisionResult> {
const result = await apiSend<DecisionResult>(REVIEW_DECISION_URL, payload);
if (result.ok && result.asset_revisions) {
const revisions = result.asset_revisions;
queryClient.setQueryData<ReviewData>(REVIEW_KEY, (data) => data && mapReviewQueues(data, snapshot => ({
...snapshot,
sections: {
...snapshot.sections,
metadata_fields: snapshot.sections.metadata_fields?.map((row) => {
const change = revisions[String(row.asset_id)];
return row.asset_path && change && row.asset_mutation_revision === change.before
? { ...row, asset_mutation_revision: change.after } : row;
}),
},
})));
}
return result;
}
/** 批量队列保留行身份;并发凭据来自共享缓存里的最新回执。 */
export function currentReviewRow(category: ReviewCategory, row: ReviewRow): ReviewRow {
const data = queryClient.getQueryData<ReviewData>(REVIEW_KEY);
return data ? REVIEW_QUEUES.flatMap(key => reviewQueueData(data, key).sections[category] || [])
.find(item => item.item_key === row.item_key) || row : row;
}
/** 收录一个 genre(给中文名)或把它判成非内容(`tag` 留空)。 */
export const recordGenre = (genre: string, tag: string) =>
apiSend<DecisionResult>(REVIEW_GENRE_URL, { genre, tag });
/** 首屏只读复核队列。符合 ADR-0018 的候选已在扫描与资料处理结束时落库。 */
export async function prefetchReview(signal: AbortSignal): Promise<void> {
await queryClient.fetchQuery({ queryKey: REVIEW_KEY, queryFn: () => fetchReview(signal) });
}
/** 判过的行从缓存里摘掉并同步计数。留在队列里的话,看起来就像这一次判定没生效。
*
* 失败的那几条不动:它们还要留在屏幕上供重试。 */
export function dropReviewRows(category: ReviewCategory, keys: string[]): void {
settleReviewRows(category, keys, 'approved');
}
/** 一份响应内移动状态,三个队列的行与计数同时更新;失败的行保持原位。 */
export function settleReviewRows(category: ReviewCategory, keys: string[], status: DecisionStatus): void {
const gone = new Set(keys);
if (!gone.size) return;
queryClient.setQueryData<ReviewData>(REVIEW_KEY, (data) => {
if (!data) return data;
const moved = REVIEW_QUEUES.flatMap(key => reviewQueueData(data, key).sections[category] || [])
.filter(row => gone.has(row.item_key));
if (!moved.length) return data;
const target = { skipped: 'later', rejected: 'ignored', restore: 'pending', approved: null }[status];
const snapshots = Object.fromEntries(REVIEW_QUEUES.map(key => {
const snapshot = reviewQueueData(data, key);
const kept = (snapshot.sections[category] || []).filter(row => !gone.has(row.item_key));
const rows = target === key ? [...kept, ...moved.map(row => ({ ...row,
decision: status === 'restore' ? 'pending' : status, decision_note: '' }))] : kept;
rows.sort((a, b) => (a.queue_order ?? 0) - (b.queue_order ?? 0));
return [key, { ...snapshot, sections: { ...snapshot.sections, [category]: rows },
counts: { ...snapshot.counts, [category]: rows.length } }];
})) as Record<ReviewQueue, ReviewQueueData>;
return { ...data, ...snapshots.pending, queues: { later: snapshots.later, ignored: snapshots.ignored } };
});
}
/** 收录一个 genre 改的是词表,不是某一条候选:服务端按新词表重新折一遍整条队列
* (`_fold_genre_decisions`),所以这里重取队列而不是在前端自己折。同一份判据写两遍
* 迟早对不上,而对不上的表现是「页面上标签多了一个,批准写下去的还是旧的」。 */
export const reloadReview = (): Promise<void> =>
queryClient.invalidateQueries({ queryKey: REVIEW_KEY, exact: true });
/** 只读端那句话:实时镜像、缓存快照,还是连镜像都没取到。 */
export function mirrorText(
mirror: ReviewMirror | null | undefined, readOnlyMessage: string,
): string {
if (mirror?.state === 'live') return '正在显示写入端的实时复核队列';
if (mirror?.state === 'cached') return `写入端暂时不可达,显示 ${localTime(mirror.fetched_at)} 的缓存`;
return mirror?.error || readOnlyMessage;
}