justinzeus/scholarr
1
0
Fork 0
Code Issues 1 Pull requests 18 Projects Releases Packages Wiki Activity Actions

Merge pull request #9 from JustinZeus/feature/publication-status-rework

Browse source 
m
This commit is contained in:
JustinZeus 2026-02-19 22:50:35 +01:00 • committed by GitHub
commit 8c9f74ee7e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 271 additions and 356 deletions
Download patch file Download diff file Expand all files Collapse all files

342
AGENTS.MD
View file

@ -1,314 +1,28 @@
# scholarr Agent Handbook
This file is the consolidated source of truth for project scope, constraints, scrape contract, and UI implementation flow.
## 1. Product Objective
- Build a self-hosted scholar tracking system ("scholarr") with reliable, low-cost scraping and clear, actionable UI.
- Keep the MVP scope intentionally small.
- Prioritize reliability and ease of use over advanced/fancy processing.
## 2. Locked Constraints and Preferences
- Multi-user system with strict tenant isolation.
- Users are admin-created only.
- Users can change their own password.
- Admin features are shown only to admin users.
- Same-origin cookie session model with CSRF protection.
- Container-first development workflow (`docker compose`, `uv`).
- Test while developing; avoid shipping untested flows.
- Keep backend modular and DRY.
- UI is being rebuilt from scratch against API contracts.
## 3. Current Backend Architecture
- Runtime: Python + FastAPI.
- DB: PostgreSQL + SQLAlchemy + Alembic migrations.
- Scheduler: background scheduler + continuation queue processing.
- Auth:
- Argon2 password hashing.
- Session cookie (`HttpOnly`, `SameSite=Lax`, secure flag configurable).
- CSRF required for unsafe methods via `X-CSRF-Token`.
- Logging:
- structured request logging with request IDs.
- redaction controls for sensitive fields.
## 4. Scraping Contract (Probe-Based)
Status: sufficient for MVP implementation with graceful degradation.
Target endpoint:
- `https://scholar.google.com/citations?hl=en&user=<scholar_id>`
Primary selectors:
- Row: `tr.gsc_a_tr`
- Title/link: `a.gsc_a_at`
- Citation count: `a.gsc_a_ac`
- Year: `span.gsc_a_h` (fallback regex on year cell text)
- Metadata lines: first/second `div.gs_gray` -> authors/venue
- Cluster ID: from `citation_for_view=<user>:<cluster_id>` in title URL
Required parser states:
- `ok`
- `no_results`
- `blocked_or_captcha`
- `layout_changed`
- `network_error`
Required page flags:
- `has_show_more_button`
- `articles_range`
Quality assumptions from probe:
- title/cluster_id/citation/authors coverage observed near 100%
- year and venue may be missing and must remain nullable
Guardrails:
- Never crash the full run when one scholar fails.
- Persist structured failure/debug information for diagnosis.
- Handle inaccessible/redirected IDs as states, not exceptions.
## 5. Current API Scope
Base path: `/api/v1`
Envelope model:
- success: `{"data": ..., "meta": {"request_id": "..."}}`
- error: `{"error": {"code": "...", "message": "...", "details": ...}, "meta": {"request_id": "..."}}`
Auth/session:
- `GET /api/v1/auth/csrf`
- `POST /api/v1/auth/login`
- `GET /api/v1/auth/me`
- `POST /api/v1/auth/change-password`
- `POST /api/v1/auth/logout`
Admin users:
- `GET /api/v1/admin/users`
- `POST /api/v1/admin/users`
- `PATCH /api/v1/admin/users/{id}/active`
- `POST /api/v1/admin/users/{id}/reset-password`
Scholars:
- `GET /api/v1/scholars`
- `POST /api/v1/scholars`
- `GET /api/v1/scholars/search`
- `PATCH /api/v1/scholars/{id}/toggle`
- `PUT /api/v1/scholars/{id}/image/url`
- `POST /api/v1/scholars/{id}/image/upload`
- `GET /api/v1/scholars/{id}/image/upload`
- `DELETE /api/v1/scholars/{id}/image`
- `DELETE /api/v1/scholars/{id}`
Settings:
- `GET /api/v1/settings`
- `PUT /api/v1/settings`
Runs/diagnostics/queue:
- `GET /api/v1/runs`
- `GET /api/v1/runs/{id}`
- `POST /api/v1/runs/manual` (`Idempotency-Key` supported)
- `GET /api/v1/runs/queue/items`
- `POST /api/v1/runs/queue/{id}/retry`
- `POST /api/v1/runs/queue/{id}/drop`
- `DELETE /api/v1/runs/queue/{id}`
Publications:
- `GET /api/v1/publications`
- `POST /api/v1/publications/mark-read`
- `POST /api/v1/publications/mark-all-read`
Ops:
- `GET /healthz`
## 5.1 Runtime Semantics (Locked)
Manual run idempotency:
- `Idempotency-Key` is optional on `POST /api/v1/runs/manual`.
- Idempotency scope is `(user_id, idempotency_key)`.
- Replaying the same key for the same user returns the same run payload after completion.
- If the keyed run is still in progress, respond with `409 run_in_progress` and include `run_id`.
- Enforcement is database-backed, not best-effort in-memory logic.
- Frontend triggers generate keys internally; key input is not user-facing.
Continuation queue attempt policy:
- `attempt_count` is a failed-attempt budget, not a total execution counter.
- Increment attempts only when a continuation execution fails to make progress.
- Reset attempts to `0` after successful progress (success or resumable partial progress).
- Drop queue items only after failed-attempt threshold is reached.
Scholar no-change skip policy:
- Persist first-page fingerprint snapshots per scholar.
- If the first-page fingerprint is unchanged for a normal run (`cstart=0`), skip deep pagination/upsert work.
- Record run scholar result `state_reason` as `no_change_initial_page_signature`.
Scholar create naming policy:
- Do not accept custom display names during scholar create.
- Hydrate names from scraped profile metadata.
Scholar name-search safety policy:
- Treat name search as best-effort only.
- Apply single-flight execution, pacing/jitter, cache, and cooldown circuit breaker after repeated blocked responses.
- Prefer Scholar URL/ID adds for reliable ingestion onboarding.
## 6. Required UI Behavior (MVP)
Core UX entities:
- scholars
- publications (`all` and `new`)
- runs + run diagnostics
- queue visibility/actions
- settings/account
- admin users (role-gated)
Critical semantics:
- Keep `is_new_in_latest_run` separate from `is_read`.
- First-time ingestion should not imply user read-state.
- Surface partial runs and warnings clearly.
- Show loading, empty, and error states explicitly.
- Support both light and dark modes with consistent status semantics.
## 7. UI Information Architecture
Public:
- Login
Authenticated:
- Dashboard
- Scholars
- Publications
- Settings
- Admin Users (admin only)
## 8. End-to-End UI Flow Plan
## 8.1 Session bootstrap
1. On load call `GET /api/v1/auth/csrf`.
2. Call `GET /api/v1/auth/me`.
3. Route to login or dashboard based on auth state.
## 8.2 Login/logout
1. Login form submits `POST /api/v1/auth/login` with `X-CSRF-Token`.
2. Store CSRF token from response for future unsafe requests.
3. Logout calls `POST /api/v1/auth/logout`.
## 8.3 Dashboard
1. Fetch latest publications summary from `GET /api/v1/publications?mode=new&limit=20`.
2. Fetch recent runs from `GET /api/v1/runs?limit=5`.
3. Fetch queue status from `GET /api/v1/runs/queue/items?limit=200` (aggregate in UI).
4. Show:
- new publications count (`new_count`)
- total tracked publications (`total_count`)
- latest run status/started time
- queue badges (`queued`, `retrying`, `dropped`)
5. Admin users additionally see a diagnostics shortcut block to full runs/queue page.
6. Every dashboard error panel must display request-id for support.
## 8.4 Scholars
1. List via `GET /api/v1/scholars`.
2. Add/toggle/delete actions mapped to scholar endpoints.
3. Search by name via `GET /api/v1/scholars/search` with candidate add actions.
4. Profile image controls:
- scraped image fallback from Scholar metadata
- custom URL override
- image upload + reset to scraped/default
5. Per-row quick links:
- all publications filtered by scholar
- new publications filtered by scholar
## 8.5 Publications
1. Default view mode is `new` (`GET /api/v1/publications?mode=new`).
2. Support mode toggle:
- `new`: scoped to latest completed run
- `all`: full history
3. Support scholar filter via `scholar_profile_id` query param.
4. Render both badges independently:
- `is_new_in_latest_run`
- `is_read`
5. "Mark all read" action calls `POST /api/v1/publications/mark-all-read` with CSRF.
6. Show explicit empty states:
- no publications tracked
- no new publications in latest run
- filtered scholar has no items
7. Surface run recency context when mode is `new` (latest completed run semantics).
## 8.6 Runs and diagnostics (admin)
1. List runs from `GET /api/v1/runs`.
2. Run details from `GET /api/v1/runs/{id}`:
- scholar result state/reason
- warnings
- page logs + attempt logs
- debug metadata
3. Queue operations from queue endpoints (`retry`, `drop`, `clear`).
## 8.7 Settings + account
1. User ingest settings from `/api/v1/settings`.
2. Password change via `/api/v1/auth/change-password`.
## 8.8 Admin user management
1. Show section only when `current_user.is_admin=true`.
2. Use admin user endpoints for create/activate/deactivate/reset password.
## 9. Development Method
- API-contract-first frontend.
- Vertical slices (complete flow before moving on).
- Shared API client module:
- always send credentials
- inject CSRF header for unsafe methods
- normalize envelope parsing and error handling
- Keep frontend modules separate (`auth`, `scholars`, `publications`, `runs`, `settings`, `admin`).
- Write tests while implementing each slice.
## 10. Definition of Done (UI Readiness)
- All main flows above implemented and mapped to existing API endpoints.
- Role-gated admin experience enforced in UI.
- Distinct new-vs-read publication semantics visible.
- Run/queue diagnostics visible and actionable.
- Reliable loading/empty/error states with request-id surfaced for support.
- No dependence on removed server-rendered UI layer.
## 11. Open Items (Known Future Work)
- API contract freeze/changelog discipline for external UI clients.
- Additional API-first smoke coverage for end-to-end UI critical flows.
- Optional background image enrichment/refresh jobs for already-tracked scholars.
## 12. UI Rebuild Program Artifacts
- Phase 0 through Phase 3 decisions are consolidated into this handbook and `README.md`.
- Local scratch notes, probes, and temporary planning artifacts are intentionally not tracked in git.
## 13. Frontend Scaffold Status (Implemented)
- Frontend scaffold path: `frontend/`
- Implemented core:
- App shell + routing + auth/role route guards
- Shared API client with envelope parsing, credentials, and CSRF header injection
- Pinia stores for auth, theme, and global UI errors
- Tailwind-first design foundation with light/dark themes and pre-paint theme initialization
- Page shells for login, dashboard, scholars, publications, runs, run detail, settings, and admin users
- Initial feature modules under `frontend/src/features/*` mapped to current API endpoints
- Deployment boundary:
- No in-repo reverse-proxy implementation
- Frontend edge/proxy routing is managed externally (for example, Caddy)
## 14. Frontend Quality Gates (Phase 3 Implemented)
- CI now includes frontend quality gates in `.github/workflows/ci.yml`:
- API contract drift check (`scripts/check_frontend_api_contract.py`)
- frontend typecheck (`npm run typecheck`)
- frontend unit tests (`npm run test:run`)
- frontend build (`npm run build`)
- Frontend test harness:
- `vitest` configured in `frontend/vitest.config.ts`
- baseline tests in `frontend/src/lib/api/envelope.test.ts` and `frontend/src/lib/api/errors.test.ts`
# AI Agent Instructions: Scholarr
Adhere strictly to these constraints.
## 1. Coding Standards (Strict Enforcement)
* **Function Length:** Maximum 50 lines of code per function. Break down complex logic into small, testable, single-responsibility functions.
* **DRY (Don't Repeat Yourself):** Abstract repetitive logic immediately. No duplicate boilerplate for database queries, API responses, or error handling.
* **Negative Space Programming:** Utilize explicit assertions and constraints to define invalid states. Fail fast and early. Do not allow silent failures or cascading malformed data, especially in DOM parsing.
* **Cyclomatic Complexity:** Flatten logic. Use early returns and guard clauses instead of deep nesting.
## 2. Domain Architecture & Data Model
* **Data Isolation:** Scholar tracking is **user-scoped**. Validate mapping/join tables; never assume global links between users and Scholar IDs.
* **Data Deduplication:** Publications are **global records**. Deduplicate via Scholar cluster ID and normalized fingerprinting prior to database insertion.
* **State Management:** Visibility and "read/unread" states exist exclusively on the scholar-publication link table, not the global publication table.
* **API Contract:** Exact envelope format required:
* Success: `{"data": ..., "meta": {"request_id": "..."}}`
* Error: `{"error": {"code": "...", "message": "...", "details": ...}, "meta": {"request_id": "..."}}`
## 3. Scrape Safety & Rate Limiting (Immutable)
These limits prevent IP bans and are not to be optimized away.
* **Minimum Delay:** Enforce `INGESTION_MIN_REQUEST_DELAY_SECONDS` (default 2s) between all external requests.
* **Anti-Detection:** Default to direct ID or profile URL ingestion. Name searches trigger CAPTCHAs.
* **Cooldowns:** Respect `INGESTION_SAFETY_COOLDOWN_BLOCKED_SECONDS` (1800s) and `INGESTION_SAFETY_COOLDOWN_NETWORK_SECONDS` (900s) upon threshold breaches.
## 4. Current Environment & Stack
* **Backend:** Python 3.12+, FastAPI, SQLAlchemy (Async/asyncpg), Alembic.
* **Frontend:** TypeScript, React, Vite.
* **Infrastructure:** Multi-stage Docker.

10
README.md
View file

@ -266,3 +266,13 @@ Scheduled fixture probes run in GitHub Actions via `.github/workflows/scheduled-
- Base path: `/api/v1`
- Success envelope: `{"data": ..., "meta": {"request_id": "..."}}`
- Error envelope: `{"error": {"code": "...", "message": "...", "details": ...}, "meta": {"request_id": "..."}}`
### Publications semantics
- `GET /api/v1/publications` supports `mode=all|unread|latest` (plus temporary alias `mode=new`).
- `unread` = actionable read-state (`is_read=false`).
- `latest` = discovery-state (`first seen in the latest completed check`).
- Response counters:
- `unread_count`: unread publications in current scope.
- `latest_count`: publications discovered in latest completed check.
- `new_count`: compatibility alias for `latest_count` (temporary).

16
app/api/routers/publications.py
View file

@ -31,13 +31,13 @@ router = APIRouter(prefix="/publications", tags=["api-publications"])
)
async def list_publications(
request: Request,
mode: Literal["all", "new"] | None = Query(default=None),
mode: Literal["all", "unread", "latest", "new"] | None = Query(default=None),
scholar_profile_id: int | None = Query(default=None, ge=1),
limit: int = Query(default=300, ge=1, le=1000),
db_session: AsyncSession = Depends(get_db_session),
current_user: User = Depends(get_api_current_user),
):
resolved_mode = publication_service.resolve_mode(mode)
resolved_mode = publication_service.resolve_publication_view_mode(mode)
selected_scholar_id = scholar_profile_id
if selected_scholar_id is not None:
selected_profile = await scholar_service.get_user_scholar_by_id(
@ -59,10 +59,14 @@ async def list_publications(
scholar_profile_id=selected_scholar_id,
limit=limit,
)
new_count = await publication_service.count_for_user(
unread_count = await publication_service.count_unread_for_user(
db_session,
user_id=current_user.id,
scholar_profile_id=selected_scholar_id,
)
latest_count = await publication_service.count_latest_for_user(
db_session,
user_id=current_user.id,
mode=publication_service.MODE_NEW,
scholar_profile_id=selected_scholar_id,
)
total_count = await publication_service.count_for_user(
@ -76,7 +80,9 @@ async def list_publications(
data={
"mode": resolved_mode,
"selected_scholar_profile_id": selected_scholar_id,
"new_count": new_count,
"unread_count": unread_count,
"latest_count": latest_count,
"new_count": latest_count,
"total_count": total_count,
"publications": [
{

2
app/api/schemas.py
View file

@ -515,6 +515,8 @@ class PublicationItemData(BaseModel):
class PublicationsListData(BaseModel):
mode: str
selected_scholar_profile_id: int | None
unread_count: int
latest_count: int
new_count: int
total_count: int
publications: list[PublicationItemData]

64
app/services/publications.py
View file

@ -14,8 +14,10 @@ from app.db.models import (
ScholarPublication,
)
MODE_NEW = "new"
MODE_ALL = "all"
MODE_UNREAD = "unread"
MODE_LATEST = "latest"
MODE_NEW = "new" # compatibility alias for MODE_LATEST
@dataclass(frozen=True)
@ -45,10 +47,16 @@ class UnreadPublicationItem:
pub_url: str | None
def resolve_publication_view_mode(value: str | None) -> str:
if value == MODE_UNREAD:
return MODE_UNREAD
if value in {MODE_LATEST, MODE_NEW}:
return MODE_LATEST
return MODE_ALL
def resolve_mode(value: str | None) -> str:
if value == MODE_ALL:
return MODE_ALL
return MODE_NEW
return resolve_publication_view_mode(value)
async def get_latest_completed_run_id_for_user(
@ -99,8 +107,10 @@ def publications_query(
)
if scholar_profile_id is not None:
stmt = stmt.where(ScholarProfile.id == scholar_profile_id)
if mode == MODE_NEW:
# "New" means discovered in the latest completed run.
if mode == MODE_UNREAD:
stmt = stmt.where(ScholarPublication.is_read.is_(False))
if mode == MODE_LATEST:
# "Latest" means discovered in the latest completed run.
if latest_run_id is None:
stmt = stmt.where(False)
else:
@ -116,7 +126,7 @@ async def list_for_user(
scholar_profile_id: int | None = None,
limit: int = 300,
) -> list[PublicationListItem]:
resolved_mode = resolve_mode(mode)
resolved_mode = resolve_publication_view_mode(mode)
latest_run_id = await get_latest_completed_run_id_for_user(
db_session,
user_id=user_id,
@ -177,11 +187,11 @@ async def list_unread_for_user(
result = await db_session.execute(
publications_query(
user_id=user_id,
mode=MODE_ALL,
mode=MODE_UNREAD,
latest_run_id=None,
scholar_profile_id=None,
limit=limit,
).where(ScholarPublication.is_read.is_(False))
)
)
rows = result.all()
items: list[UnreadPublicationItem] = []
@ -224,7 +234,7 @@ async def list_new_for_latest_run_for_user(
rows = await list_for_user(
db_session,
user_id=user_id,
mode=MODE_NEW,
mode=MODE_LATEST,
scholar_profile_id=None,
limit=limit,
)
@ -250,7 +260,7 @@ async def count_for_user(
mode: str = MODE_ALL,
scholar_profile_id: int | None = None,
) -> int:
resolved_mode = resolve_mode(mode)
resolved_mode = resolve_publication_view_mode(mode)
latest_run_id = await get_latest_completed_run_id_for_user(
db_session,
user_id=user_id,
@ -263,7 +273,9 @@ async def count_for_user(
)
if scholar_profile_id is not None:
stmt = stmt.where(ScholarProfile.id == scholar_profile_id)
if resolved_mode == MODE_NEW:
if resolved_mode == MODE_UNREAD:
stmt = stmt.where(ScholarPublication.is_read.is_(False))
if resolved_mode == MODE_LATEST:
if latest_run_id is None:
return 0
stmt = stmt.where(ScholarPublication.first_seen_run_id == latest_run_id)
@ -271,6 +283,34 @@ async def count_for_user(
return int(result.scalar_one() or 0)
async def count_unread_for_user(
db_session: AsyncSession,
*,
user_id: int,
scholar_profile_id: int | None = None,
) -> int:
return await count_for_user(
db_session,
user_id=user_id,
mode=MODE_UNREAD,
scholar_profile_id=scholar_profile_id,
)
async def count_latest_for_user(
db_session: AsyncSession,
*,
user_id: int,
scholar_profile_id: int | None = None,
) -> int:
return await count_for_user(
db_session,
user_id=user_id,
mode=MODE_LATEST,
scholar_profile_id=scholar_profile_id,
)
async def mark_all_unread_as_read_for_user(
db_session: AsyncSession,
*,

4
frontend/src/features/dashboard/index.ts
View file

@ -41,7 +41,7 @@ function countQueueStatuses(statuses: string[]): QueueHealth {
export async function fetchDashboardSnapshot(): Promise<DashboardSnapshot> {
const [publications, runsPayload, queueItems] = await Promise.all([
listPublications({ mode: "new", limit: 20 }),
listPublications({ mode: "latest", limit: 20 }),
listRuns({ limit: 20 }),
listQueueItems(200),
]);
@ -50,7 +50,7 @@ export async function fetchDashboardSnapshot(): Promise<DashboardSnapshot> {
const queueHealth = countQueueStatuses(queueItems.map((item) => item.status));
return {
newCount: publications.new_count,
newCount: publications.latest_count,
totalCount: publications.total_count,
mode: publications.mode,
latestRun: runs[0] ?? null,

5
frontend/src/features/publications/index.ts
View file

@ -1,6 +1,6 @@
import { apiRequest } from "@/lib/api/client";
export type PublicationMode = "all" | "new";
export type PublicationMode = "all" | "unread" | "latest";
export interface PublicationItem {
publication_id: number;
@ -19,6 +19,9 @@ export interface PublicationItem {
export interface PublicationsResult {
mode: PublicationMode;
selected_scholar_profile_id: number | null;
unread_count: number;
latest_count: number;
// Compatibility alias for latest_count; retained while API clients migrate.
new_count: number;
total_count: number;
publications: PublicationItem[];

42
frontend/src/pages/PublicationsPage.vue
View file

@ -186,7 +186,7 @@ const visibleCount = computed(() => sortedPublications.value.length);
const visibleUnreadCount = computed(() => visibleUnreadKeys.value.size);
const actionBusy = computed(() => loading.value || publishingAll.value || publishingSelected.value);
const showingEmptyList = computed(() => Boolean(listState.value) && sortedPublications.value.length === 0);
const modeLabel = computed(() => (mode.value === "new" ? "Needs review" : "All records"));
const modeLabel = computed(() => (mode.value === "unread" ? "Unread" : "All records"));
const emptyTitle = computed(() =>
searchQuery.value.trim().length > 0 ? "No publications match this search" : "No publications found",
@ -196,8 +196,8 @@ const emptyBody = computed(() => {
if (searchQuery.value.trim().length > 0) {
return "Try another title, scholar, venue, or year.";
}
if (mode.value === "new") {
return `No publications currently need review for ${selectedScholarName.value}.`;
if (mode.value === "unread") {
return `No unread publications for ${selectedScholarName.value}.`;
}
return `No publication records for ${selectedScholarName.value}.`;
});
@ -340,14 +340,14 @@ async function onMarkSelectedRead(): Promise<void> {
try {
const response = await markSelectedRead(selections);
successMessage.value = `${response.updated_count} publication${response.updated_count === 1 ? "" : "s"} marked as reviewed.`;
successMessage.value = `${response.updated_count} publication${response.updated_count === 1 ? "" : "s"} marked as read.`;
await loadPublications();
} catch (error) {
if (error instanceof ApiRequestError) {
errorMessage.value = error.message;
errorRequestId.value = error.requestId;
} else {
errorMessage.value = "Unable to mark selected publications as reviewed.";
errorMessage.value = "Unable to mark selected publications as read.";
}
} finally {
publishingSelected.value = false;
@ -362,14 +362,14 @@ async function onMarkAllRead(): Promise<void> {
try {
const response = await markAllRead();
successMessage.value = `${response.updated_count} publication${response.updated_count === 1 ? "" : "s"} marked as reviewed.`;
successMessage.value = `${response.updated_count} publication${response.updated_count === 1 ? "" : "s"} marked as read.`;
await loadPublications();
} catch (error) {
if (error instanceof ApiRequestError) {
errorMessage.value = error.message;
errorRequestId.value = error.requestId;
} else {
errorMessage.value = "Unable to mark publications as reviewed.";
errorMessage.value = "Unable to mark publications as read.";
}
} finally {
publishingAll.value = false;
@ -400,7 +400,7 @@ watch(
<template>
<AppPage
title="Publications"
subtitle="Filter and review discovered publications, then mark what you have handled so the next check stays focused."
subtitle="Filter discovered publications, then mark what you have read so upcoming checks stay focused."
>
<AppCard class="space-y-4">
<div class="flex flex-wrap items-center justify-between gap-2">
@ -408,11 +408,11 @@ watch(
<div class="flex items-center gap-1">
<h2 class="text-lg font-semibold text-ink-primary">What you can do here</h2>
<AppHelpHint
text="Publications are discovered records from tracked scholar profiles. Review mode helps focus only on newly detected items."
text="Publications are records discovered from tracked scholar profiles. Unread mode focuses only on items you have not marked as read."
/>
</div>
<p class="text-sm text-secondary">
Select a scholar or time scope, search within results, and mark items reviewed when you are done.
Select a scholar or scope, search within results, and mark items as read when you are done.
</p>
</div>
@ -426,12 +426,12 @@ watch(
<span>View mode</span>
<div class="flex min-h-10 flex-wrap items-center gap-2">
<AppButton
:variant="mode === 'new' ? 'primary' : 'secondary'"
:variant="mode === 'unread' ? 'primary' : 'secondary'"
class="min-w-16 justify-center"
:disabled="actionBusy"
@click="setMode('new')"
@click="setMode('unread')"
>
Needs review
Unread
</AppButton>
<AppButton
:variant="mode === 'all' ? 'primary' : 'secondary'"
@ -485,7 +485,7 @@ watch(
<div class="flex flex-wrap items-center gap-2">
<AppBadge tone="info">Mode: {{ modeLabel }}</AppBadge>
<AppBadge tone="neutral">Visible: {{ visibleCount }}</AppBadge>
<AppBadge tone="warning">Needs review: {{ visibleUnreadCount }}</AppBadge>
<AppBadge tone="warning">Unread: {{ visibleUnreadCount }}</AppBadge>
<AppBadge tone="success">Selected: {{ selectedCount }}</AppBadge>
</div>
@ -495,10 +495,10 @@ watch(
:disabled="selectedCount === 0 || actionBusy"
@click="onMarkSelectedRead"
>
{{ publishingSelected ? "Updating..." : `Mark selected reviewed (${selectedCount})` }}
{{ publishingSelected ? "Updating..." : `Mark selected as read (${selectedCount})` }}
</AppButton>
<AppButton variant="secondary" :disabled="actionBusy || visibleUnreadCount === 0" @click="onMarkAllRead">
{{ publishingAll ? "Updating..." : "Mark all as reviewed" }}
{{ publishingAll ? "Updating..." : "Mark all unread as read" }}
</AppButton>
</div>
</div>
@ -518,7 +518,7 @@ watch(
<div class="flex items-center gap-1">
<h2 class="text-lg font-semibold text-ink-primary">Publication List</h2>
<AppHelpHint
text="Use sorting, search, and bulk actions here to move discovered records from needs-review into reviewed history."
text="Use sorting, search, and bulk actions here to move discovered records from unread into read history."
/>
</div>
<span class="text-xs text-secondary">Currently showing {{ selectedScholarName }}</span>
@ -541,7 +541,7 @@ watch(
class="h-4 w-4 rounded border-stroke-interactive bg-surface-input text-brand-600 focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-focus-offset"
:checked="allVisibleUnreadSelected"
:disabled="visibleUnreadKeys.size === 0"
aria-label="Select all visible publications that need review"
aria-label="Select all visible unread publications"
@change="onToggleAllVisible"
/>
</th>
@ -567,7 +567,7 @@ watch(
</th>
<th scope="col">
<button type="button" class="table-sort" @click="toggleSort('status')">
Review status <span aria-hidden="true">{{ sortMarker("status") }}</span>
Read status <span aria-hidden="true">{{ sortMarker("status") }}</span>
</button>
</th>
<th scope="col">
@ -607,10 +607,10 @@ watch(
<td>
<div class="flex flex-wrap items-center gap-2">
<AppBadge :tone="item.is_new_in_latest_run ? 'info' : 'neutral'">
{{ item.is_new_in_latest_run ? "New this check" : "Previously seen" }}
{{ item.is_new_in_latest_run ? "New this check" : "Seen before" }}
</AppBadge>
<AppBadge :tone="item.is_read ? 'success' : 'warning'">
{{ item.is_read ? "Reviewed" : "Needs review" }}
{{ item.is_read ? "Read" : "Unread" }}
</AppBadge>
</div>
</td>

2
frontend/src/pages/StyleGuidePage.vue
View file

@ -277,7 +277,7 @@ function onToggleTheme(): void {
<div class="flex flex-wrap gap-2">
<AppButton>Primary action</AppButton>
<AppButton variant="secondary">Secondary</AppButton>
<AppBadge tone="warning">Needs review</AppBadge>
<AppBadge tone="warning">Unread</AppBadge>
</div>
<AppTable label="Shell preview table">
<thead>

140
tests/integration/test_api_v1.py
View file

@ -1222,9 +1222,32 @@ async def test_api_publications_list_and_mark_read(db_session: AsyncSession) ->
assert list_response.status_code == 200
data = list_response.json()["data"]
assert data["mode"] == "all"
assert data["total_count"] == 2
assert data["unread_count"] == 2
assert data["latest_count"] == 0
assert data["new_count"] == data["latest_count"]
assert isinstance(data["publications"], list)
assert len(data["publications"]) == 2
latest_response = client.get("/api/v1/publications?mode=latest")
assert latest_response.status_code == 200
latest_data = latest_response.json()["data"]
assert latest_data["mode"] == "latest"
assert latest_data["latest_count"] == 0
unread_response = client.get("/api/v1/publications?mode=unread")
assert unread_response.status_code == 200
unread_data = unread_response.json()["data"]
assert unread_data["mode"] == "unread"
assert unread_data["unread_count"] == 2
alias_response = client.get("/api/v1/publications?mode=new")
assert alias_response.status_code == 200
alias_data = alias_response.json()["data"]
assert alias_data["mode"] == "latest"
assert alias_data["latest_count"] == latest_data["latest_count"]
assert alias_data["publications"] == latest_data["publications"]
mark_selected_response = client.post(
"/api/v1/publications/mark-read",
json={
@ -1259,3 +1282,120 @@ async def test_api_publications_list_and_mark_read(db_session: AsyncSession) ->
mark_response = client.post("/api/v1/publications/mark-all-read", headers=headers)
assert mark_response.status_code == 200
assert mark_response.json()["data"]["updated_count"] == 1
@pytest.mark.integration
@pytest.mark.db
@pytest.mark.asyncio
async def test_api_publications_unread_and_latest_modes_can_diverge(
db_session: AsyncSession,
) -> None:
user_id = await insert_user(
db_session,
email="api-pubs-mismatch@example.com",
password="api-password",
)
scholar_result = await db_session.execute(
text(
"""
INSERT INTO scholar_profiles (user_id, scholar_id, display_name, is_enabled)
VALUES (:user_id, :scholar_id, :display_name, true)
RETURNING id
"""
),
{
"user_id": user_id,
"scholar_id": "mismatchScholar01",
"display_name": "Mismatch Scholar",
},
)
scholar_profile_id = int(scholar_result.scalar_one())
older_run_result = await db_session.execute(
text(
"""
INSERT INTO crawl_runs (user_id, trigger_type, status, scholar_count, new_pub_count)
VALUES (:user_id, 'manual', 'success', 1, 1)
RETURNING id
"""
),
{"user_id": user_id},
)
older_run_id = int(older_run_result.scalar_one())
latest_run_result = await db_session.execute(
text(
"""
INSERT INTO crawl_runs (user_id, trigger_type, status, scholar_count, new_pub_count)
VALUES (:user_id, 'scheduled', 'success', 1, 0)
RETURNING id
"""
),
{"user_id": user_id},
)
latest_run_id = int(latest_run_result.scalar_one())
assert latest_run_id > older_run_id
publication_result = await db_session.execute(
text(
"""
INSERT INTO publications (fingerprint_sha256, title_raw, title_normalized, citation_count)
VALUES (:fingerprint, :title_raw, :title_normalized, 12)
RETURNING id
"""
),
{
"fingerprint": f"{(user_id + 99):064x}",
"title_raw": "Unread But Not Latest",
"title_normalized": "unread but not latest",
},
)
publication_id = int(publication_result.scalar_one())
await db_session.execute(
text(
"""
INSERT INTO scholar_publications (
scholar_profile_id,
publication_id,
is_read,
first_seen_run_id
)
VALUES (:scholar_profile_id, :publication_id, false, :first_seen_run_id)
"""
),
{
"scholar_profile_id": scholar_profile_id,
"publication_id": publication_id,
"first_seen_run_id": older_run_id,
},
)
await db_session.commit()
client = TestClient(app)
login_user(client, email="api-pubs-mismatch@example.com", password="api-password")
unread_response = client.get("/api/v1/publications?mode=unread")
assert unread_response.status_code == 200
unread_data = unread_response.json()["data"]
assert unread_data["mode"] == "unread"
assert unread_data["unread_count"] == 1
assert unread_data["latest_count"] == 0
assert unread_data["new_count"] == 0
assert len(unread_data["publications"]) == 1
assert int(unread_data["publications"][0]["publication_id"]) == publication_id
assert unread_data["publications"][0]["is_new_in_latest_run"] is False
latest_response = client.get("/api/v1/publications?mode=latest")
assert latest_response.status_code == 200
latest_data = latest_response.json()["data"]
assert latest_data["mode"] == "latest"
assert latest_data["latest_count"] == 0
assert len(latest_data["publications"]) == 0
alias_response = client.get("/api/v1/publications?mode=new")
assert alias_response.status_code == 200
alias_data = alias_response.json()["data"]
assert alias_data["mode"] == "latest"
assert alias_data["latest_count"] == latest_data["latest_count"]
assert alias_data["publications"] == latest_data["publications"]