planet/docs/deprecated/admin-next-parity-audit-closeout-plan.md

Admin Next Parity Audit Closeout

Last updated: 2026-05-21

Status

Admin Next has been promoted to the official admin route family. The old AntD admin, old layout helpers, antd, and @ant-design/icons remain available under /legacy/admin/* as the rollback and comparison surface.

/admin-next/* is now compatibility-only: old test links redirect to the official route. Do not add new capabilities there as a separate entry point.

This closeout document is the final work log for the second parity audit. It records what has been fixed, what still requires manual verification, and what must not be treated as complete.

Fixed In This Audit

• Restored the dual-track rule: old AntD pages and routes are not deleted and are not replaced before parity sign-off.
• Reworked management pages away from flat status tables toward business hierarchy:
  • AI: 模型供应商 / 工具调用 / 提示词 / Playground.
  • Settings: system display, notification policy, security policy, SMTP only.
  • Earth Content: brand, boundary precision, TV content.
  • Collection: collector, collection schedule, history/snapshot.
• Repaired AI provider credential semantics:
  • Provider status now comes from that provider's stored key or a runtime key that is explicitly scoped to that provider.
  • Generic .env fallback no longer marks every provider as configured.
  • Runtime fallback secrets stay masked by default; authorized administrators can reveal them through the console and each reveal must be audited without storing plaintext.
  • Secret previews preserve the prefix before the first - when the backend preview exposes it, for example sk-**********.
  • Connect-test buttons are icon-only plug actions and do not save configuration.
• Repaired key UI gaps:
  • LLM API Key, proxy token, Web Search API Key, and OCR API Key use masked input with inline eye toggle.
  • Save buttons use the disk icon.
  • Default action is disabled when the item is already default.
• Repaired SMTP test flow:
  • SMTP test has a recipient input.
  • Request payload is { to, settings }.
• Repaired Earth Content actions:
  • Brand save, upload, delete/reset actions are available in the brand section.
  • Brand preview renders with the same Earth left-top brand structure and starfield-style background.
  • Boundary build is scoped to the boundary precision section, not the global page toolbar.
  • TV default configuration is folded into item-level configuration; TV items support add/default/reset/delete semantics.
  • TV default source now follows the same default-state semantics as AI Provider: if the response does not expose an explicit default, cgtn-en is treated as the runtime default; setting a default promotes that item visually and disables the redundant default action.
• Repaired Collection actions:
  • Credential guide read/generate/reset entry points are available from collector-related panels.
  • Create collector config uses field-first form controls with advanced JSON as a secondary path.
  • Mapping propose/preview/create/activate flow is represented in the mapping workflow.
• Repaired shared UI rules:
  • Management list names can wrap and remain readable instead of being squeezed by status tags.
  • Status tags are fixed width and color-coded: default blue, configured green, unconfigured gray, error red.
  • Configuration lists with a default item sort the default item to the top after save/default changes instead of leaving it in the previous alphabetical or API order.
  • List footer actions are part of the scroll content; users see them after scrolling to the bottom.
  • Footer icon buttons use the current tactile surface direction: external shadow first, without a separate inset/base-plate treatment.
  • Detail panels use a dark neutral resize handle.
  • Tooltip, dialog, modal backdrop, textarea scrollbar, custom scrollbar, mobile detail, and one-screen layout issues from the audit have been addressed in the shared admin-next layer.
  • Multi-tab Admin Next pages now use lazy active-tab loading with local cache. Initial page load no longer requests every section endpoint; manual refresh and mutating actions refresh only the current section.
  • Markdown-producing details, AI brief content, credential tutorials, and Playground assistant output use the shared Markdown renderer where the content is meant to be read as a document. Raw metadata remains available only where the page is explicitly showing original payloads.
• Added developer workflow scripts:
  • build:watch
  • preview:auto
  • bun run build remains a production artifact build and does not reload an already-open dev page by itself.

Manual Verification Status

The code has been updated. The list below records which areas are already manually checked and which still need route-level regression before replacement:

• AI:
  • Latest manual pass marked provider status, secret reveal, and Playground behavior as checked.
• DataSources:
  • Single trigger performs old task-status precheck, handles running-conflict confirmation, supports force recollect, and refreshes task status afterward.
  • Batch trigger uses old /datasources/trigger-batch semantics for selected IDs, filters, and force.
  • Builtin, custom, and realtime source actions match old enable/disable/start/stop/restart/clear-data behavior.
  • 2026-05-20 implementation pass: Admin Next builtin datasource rows now expose task/collection status and metrics, and single trigger now performs task-status precheck with running-conflict force confirmation plus post-trigger task refresh.
  • 2026-05-20 manual pass: builtin trigger, task-status precheck, force recollect, batch trigger, enable/disable, and clear-data were verified in Admin Next.
• Collection:
  • Collector config create/update/delete, builtin connect, custom test/sample/run/stop/status, schedule save, history/snapshot, mapping propose/preview/create/activate, and credential guide read/generate/reset all work with real backend payloads.
  • 2026-05-20 implementation pass: 采集历史 / 快照 now reads real datasource snapshots from /datasources/snapshots instead of config rows.
  • 2026-05-20 implementation pass: default credential guide actions no longer call unsupported providers blindly; unsupported collectors show a clear empty state and supported providers use barentswatch / aisstream.
  • Collection action buttons must follow the AI page's single-responsibility rule: navigation/link actions do not save, save actions do not connect/test, and connect/test actions do not persist drafts.
  • 2026-05-20 manual pass: collector create/edit auth_config, mapping propose/preview/create/activate, custom test/sample/run/stop/status, credential guide read/generate/reset, and history/snapshot behavior were verified in Admin Next.
  • 2026-05-20 follow-up: dead JSON modal create/mapping code was removed so Collection creation now goes through the list-bottom draft workflow only.
• Earth Content:
  • Brand preview visually matches the Earth runtime left-top brand at the same structural level.
  • Brand upload writes back logo_src or title_src correctly.
  • 2026-05-20 implementation pass: Brand upload validates and displays accepted suffixes (png, jpg, jpeg, webp, svg) and supports drag-and-drop.
  • Boundary status/config/build and TV add/save/default/delete/reset match old behavior.
• Logs:
  • Sources, snapshot/tail, level/date/search, copy, empty/error states, and internal scrolling all work.
  • 2026-05-20 implementation pass: Logs now include database-backed system-db and audit-db sources as a fallback when file/docker/buffer logs are empty or missing, and the UI auto-selects an available source. Manual regression must still verify snapshot/tail-like reading, filters, copy, and scrolling.
• BGP / Alerts:
  • BGP overview, collectors, collect-location detail, incidents, anomalies, events, latest/detail/generate AI brief.
  • System/BGP/situational alert detail, ack, resolve with note, refresh after mutation, and AI brief details.
• Users/Auth:
  • Users CRUD, role, Gatekeeper groups.
  • 2026-05-20 implementation pass: User edit select dropdowns now use an opaque high-z-index menu surface, and Gatekeeper checkbox groups use an explicit surface background. Manual visual regression is still required.
  • Login, register, verify email, resend cooldown, forgot/reset password.
• Mobile:
  • 375px, 430px, and 768px widths default to list/group first.
  • Detail opens only after tap/click and has a visible back action.
  • Long forms, JSON, logs, and Playground messages scroll internally without body-level double scrollbars.

Explicit Non-Production Items

The old AntD page itself treated these Earth content tabs as placeholder-level capabilities. Admin Next must show a visible “backend capability pending” empty state and must not mix in unrelated data:

• basemap
• layer_resources
• models_3d
• news_anchor_strategy

If backend endpoints are later added, these items must be promoted into a new active plan under docs/plans/ with concrete API and UI acceptance criteria.

Final Gate

After the route promotion, the final gate is no longer “switch old routes.” The remaining gate is “keep legacy available until the promoted routes are stable enough to remove AntD.”

1. Run cd frontend && /home/ray/.bun/bin/bun run build.
2. Run the static checks:
   • rg "map: \\(\\) => \\[\\]|暂不支持保存|placeholder" frontend/src/admin-next
   • rg "ShadowPage|FeatureConsole|GlassPanel|InspectorDrawer" frontend/src/admin-next
3. Manually verify every official route listed in docs/deprecated/admin-next-parity-checklist.md.
4. Confirm /legacy/admin/* still opens old AntD pages during the validation window.
5. Delete old AntD pages and remove AntD dependencies only as a separate final cleanup task after explicit confirmation.

Current Build Verification

Last successful local build during this closeout, after the 2026-05-20 follow-up fixes:

cd frontend && /home/ray/.bun/bin/bun run build

Result: passed.

Backend syntax check also passed:

/home/ray/.local/bin/uv run python -m py_compile backend/app/api/v1/datasources.py backend/app/api/v1/datasource_config.py backend/app/api/v1/system_control.py