release: bump version to 0.66.0

2026-05-26 03:41:47 +08:00
parent e65267fe21
commit 5bf5c73ca0
173 changed files with 8669 additions and 13210 deletions
--- a/docs/deprecated/README.md
+++ b/docs/deprecated/README.md
@@ -16,7 +16,24 @@
 - 已被正式实现替代、继续放在 `docs/` 根目录会误导后续开发的计划，归档
 - 仍然指导未来开发、尚未完成或仍有明确执行价值的文档，继续保留在 `docs/`

+当前替代入口：
+
+- 业务和数据产品链路见 [业务架构与数据流转](/home/ray/dev/linkong/planet/docs/technical/zh/platform-data-flows.md)。
+- 当前后端作业、outbox 和 Earth 同步实现见 [数据作业与 Outbox 技术架构](/home/ray/dev/linkong/planet/docs/technical/zh/data-job-earth-sync-architecture.md)。
+- 用户操作流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)。
+- 当前代码结构见 [技术文档索引](/home/ray/dev/linkong/planet/docs/technical/zh/README.md)。
+
 补充说明：

 - 一部分归档文档来自外部或临时工作流草案，例如 sisyphus 生成的初稿
 - 这类文档如果有可用内容，应先吸收到 `docs/plans/` 或 `docs/technical/`，再归档保留来源记录
+
+## 近期归档
+
+- [Docs Gatekeeper 鉴权系统计划](/home/ray/dev/linkong/planet/docs/deprecated/docs-gatekeeper-auth-plan.md)：已落地，当前实现见技术文档。
+- [Location Resolver 共享管线计划](/home/ray/dev/linkong/planet/docs/deprecated/location-resolver-shared-pipeline-plan.md)：已落地，当前实现见技术文档。
+- [Earth Surface Hover Info Plan](/home/ray/dev/linkong/planet/docs/deprecated/earth-surface-hover-info-plan.md)：已实现，保留为历史记录。
+- [Admin Next Dual Track Full Migration Plan](/home/ray/dev/linkong/planet/docs/deprecated/admin-next-dual-track-full-migration-plan.md)：已被当前 `frontend/src/admin/` 控制台结构替代。
+- [Admin Next Soft Glass Goal Driven Plan](/home/ray/dev/linkong/planet/docs/deprecated/admin-next-soft-glass-goal-driven-plan.md)：已被当前 `frontend/src/admin/` 控制台结构替代。
+- [Admin Next Parity Checklist](/home/ray/dev/linkong/planet/docs/deprecated/admin-next-parity-checklist.md)：旧 `/admin-next/*` 验收资料，保留为迁移历史。
+- [Admin Next Parity Audit Closeout](/home/ray/dev/linkong/planet/docs/deprecated/admin-next-parity-audit-closeout-plan.md)：旧 `/admin-next/*` 审计资料，保留为迁移历史。
--- a/docs/deprecated/admin-next-dual-track-full-migration-plan.md
+++ b/docs/deprecated/admin-next-dual-track-full-migration-plan.md
@@ -0,0 +1,128 @@
+# Admin Next 双轨全量迁移修正计划
+
+## Summary
+
+`/admin-next/*` 继续作为新版影子路由开发，旧 AntD 控制台必须完整保留作为生产回退和行为对照。只有新版完成全功能 parity 并通过验收后，才能逐个切换旧路由；删除旧页面和移除 AntD 必须作为最后独立步骤，并等待明确确认。
+
+## Hard Rules
+
+- 未完成 parity checklist 前，不删除旧页面、不移除 AntD、不切旧入口。
+- “旧版能删除”只表示新版能力达到替代标准，不表示立即删除旧版。
+- 新版不能只做看板；旧版里可新增、编辑、删除、测试、触发、批量、轮询、WebSocket、权限控制、错误提示和确认弹窗的能力，都必须迁移。
+- `/admin-next/*` 可以重做交互和视觉，但业务语义、API payload、权限和危险操作保护必须对齐旧版。
+
+## Design Direction
+
+- 风格采用“朴素工具化 + 轻微立体触感”：灰白/暗色低对比背景、清晰 1px 边框、轻微凸起/按下态、克制圆角、图标少量彩色。
+- 禁止回到 soft-glass、hero、大发光、大渐变、大色块和装饰性卡片。
+- 常规动作默认 icon-only + tooltip：刷新、重启、退出、复制、查看、编辑、删除、关闭、设置。
+- 强意图动作保留实心文字按钮：保存、创建、确认、执行、测试连接。
+- 页面统一 `16px` 外边距、`16px` 主区块间距、`12px` 面板 header/body 间距；表格标题和表体不能贴边。
+- 所有页面遵守一屏工作台：`PageHeader` 之外只允许一个主内容区域吃满剩余高度；详情区、表格区和 Playground 消息区内部滚动，不能被父级裁掉。
+- 页内 tabs 必须按旧版用户心智组织，而不是按后端接口名拆散；接口状态只能作为分区内部信息。
+
+## Implementation Plan
+
+1. 恢复旧版安全网：恢复旧 AntD 页面、旧 `AppLayout`、旧 helper、AntD 依赖和旧路由；保留 `/admin-next/*` 影子路由。
+2. 建立新版基础层：整理 admin-next token、按钮、tooltip、theme switch、sidebar account、`EntityTable`、`FormDialog`、`ConfirmDialog`、`DetailPanel`、移动端表格/卡片切换。
+3. 拆掉通用看板页：每个模块建立真实业务页面、API adapter、form/mutation、轮询或 WebSocket 逻辑，不再用万能 Resource table 聚合展示。
+4. 按模块迁移：
+   - Dashboard：统计、WebSocket、健康检查、重启任务、任务日志、恢复探测。
+   - DataSources：内置源/自定义源/实时源、详情、stats、task-status、启停、触发、批量触发、清理数据。
+   - DataList：列表、summary、sources/types/countries、搜索、筛选、分页、详情、导出、分布。
+   - Collection Management：configs CRUD、builtin connect/test、target schemas、mappings、run/stop、stream status。
+   - Settings：system、notifications、security、SMTP、TV、integrations、collectors、测试连接、凭证指南。
+   - AI：provider、web search、OCR、prompt registry、playground 完整会话操作。
+   - Earth Content：brand、upload、delete/reset、boundary config/build/status、TV/content。
+   - Logs：sources、level/date/search、刷新、详情、复制、tail/snapshot。
+   - BGP：overview、collectors、incidents、anomalies、events、AI briefs。
+   - Alerts：系统告警、BGP 告警、态势告警，包含 ack/resolve/stats/brief。
+   - Users：list/create/edit/delete、role、Gatekeeper groups、权限显示。
+   - Auth：登录、注册、验证邮箱、重发、找回、重置、logout。
+5. 每完成一个模块，对照旧页面跑 checklist；只有全部模块通过后，才提出旧路由切换和旧版删除。
+
+## Test Plan
+
+- 恢复阶段：`cd frontend && /home/ray/.bun/bin/bun install && /home/ray/.bun/bin/bun run build`。
+- 旧路由检查：`/admin`、`/datasources`、`/settings`、`/ai`、`/logs` 必须继续打开旧版。
+- 新路由检查：`/admin-next/*` 必须继续打开新版。
+- 每模块 parity：读写删、测试连接、触发、批量、轮询、WebSocket、权限、错误提示、确认弹窗、移动端和滚动。
+- 视觉检查：light/dark/system、低高度窗口、125%/150% 缩放、按钮/状态/badge 等高、无双滚动条。
+
+## Parity Checklist
+
+### Dashboard
+- [x] `/dashboard/stats` 数据展示与旧版一致。
+- [x] WebSocket 连接状态、健康状态、自动刷新语义一致。
+- [x] 重启任务创建、轮询、日志查看、失败提示和恢复探测一致。
+
+### DataSources
+- [x] 内置源、自定义源、实时源分区清晰，不混表。
+- [x] 详情、stats、task-status、enable/disable、trigger、trigger-batch、trigger-all、delete-data 与旧版一致。
+- [x] 实时源 start/stop/restart、连接状态、任务状态与旧版一致。
+
+### DataList
+- [x] 列表、summary、sources/types/countries、搜索、筛选、分页参数与旧版一致。
+- [x] 详情 metadata、分布摘要、JSON/CSV 导出与旧版一致。
+- [x] 表格固定列、横向滚动、移动端卡片模式可用。
+
+### Collection Management
+- [x] configs/all、configs CRUD、builtin connect/test、custom sample 与旧版一致。
+- [x] target schemas、mappings preview/list/update/activate 与旧版一致；propose/create 已提供表单化入口。
+- [x] run-mapped、stop-mapped、stream-status 与旧版一致。
+
+### Settings
+- [x] system、notifications、security、SMTP、TV、integrations、collectors 表单字段完整。
+- [x] SMTP test、AI/Web/OCR secrets、connect tests、preset refresh 与旧版一致。
+- [x] credential guides、cache 清理、危险操作确认一致。
+
+### AI
+- [x] Provider、Web Search、OCR、Prompt Registry 配置保存/重置完整。
+- [x] Playground thread/session/messages/status/stop/resend/edit 完整。
+- [x] provider refresh、connect test、secrets 读取、错误提示和 loading 状态完整。
+- [x] 页内 tabs 按旧版心智恢复为模型供应商、工具调用、提示词、Playground。
+
+### Earth Content
+- [x] brand get/save/delete/reset/upload 完整。
+- [x] boundary status/config/build/build-status 完整。
+- [x] TV/content 配置与旧版 Settings 入口一致。
+
+### Logs
+- [x] sources、level/date/search、limit、刷新参数与旧版一致。
+- [x] 日志正文、详情展开、复制、空态和错误态完整。
+
+### BGP
+- [x] overview、collectors、incidents、anomalies、events 的 summary/list/detail 完整。
+- [x] AI brief list/detail/generate 完整。
+- [x] collector collect-location、刷新、结果详情和错误提示完整。
+
+### Alerts
+- [x] 系统告警 list/detail/ack/resolve/stats/AI brief 完整。
+- [x] BGP incidents/anomalies/brief 完整。
+- [x] 态势告警 stats/list/brief 完整。
+
+### Users
+- [x] list/create/edit/delete、role、Gatekeeper groups 完整。
+- [x] 权限显示、普通用户限制和 super admin 行为一致。
+
+### Auth
+- [x] login/register/verify/resend cooldown/forgot/reset/logout/me 完整。
+- [x] 未验证邮箱跳转、错误提示、成功跳转和 token store 行为一致。
+
+### Hierarchy Repair
+- [x] AI 不再按接口/状态拍平成一张表；模型供应商恢复为 provider -> model/API/key 层级。
+- [x] 工具调用恢复为 Web Search/OCR -> provider/API/高级参数层级。
+- [x] 提示词恢复为 group -> prompt 入口层级，保存/重置只作用于当前入口。
+- [x] Settings/Earth 配置型页面使用父级列表 + 右侧正式表单，长内容在一屏内内部滚动。
+
+### Interaction Polish
+- [x] 不会产生歧义的刷新、复制、详情、批量、状态、清理等动作优先改为 icon-only + tooltip/title。
+- [x] 强意图动作保留实心文字按钮，例如保存、创建、触发全部、生成简报、确认执行。
+- [x] 按钮字号、高度、图标容器和 hover 触感统一，接近侧栏深色模式滑块的轻微立体风格。
+- [x] 表格与详情之间增加可拖动竖向 resize handle，低高度和窄屏下不制造额外滚动条。
+
+### Page Information Architecture
+- [x] 页内 tab 默认使用中文；BGP、AI、OCR、Web Search、Playground、Schema 等专有名词按可识别性保留。
+- [x] 信息观测类页面使用列表 + 详情，例如 BGP、Alerts、Logs、DataSources。
+- [x] 配置管理类页面使用分层结构，例如 AI、Settings、Earth Content、Collection Management。
+- [x] 采集管理已从纯表格看板改为分层管理：采集器、映射模板、目标 Schema、运行状态先选父级，再编辑或执行动作。
--- a/docs/deprecated/admin-next-parity-audit-closeout-plan.md
+++ b/docs/deprecated/admin-next-parity-audit-closeout-plan.md
@@ -0,0 +1,135 @@
+# 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:
+
+```bash
+cd frontend && /home/ray/.bun/bin/bun run build
+```
+
+Result: passed.
+
+Backend syntax check also passed:
+
+```bash
+/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
+```
--- a/docs/deprecated/admin-next-parity-checklist.md
+++ b/docs/deprecated/admin-next-parity-checklist.md
@@ -0,0 +1,43 @@
+# Admin Next Parity Checklist
+
+Last updated: 2026-05-21
+
+This checklist is the hard gate for deleting the old AntD admin. Admin Next now owns the official admin routes; old AntD pages stay available under `/legacy/admin/*` until every production capability below is verified.
+
+## Route Gate
+
+- `/admin` Dashboard: stats, health probe, WebSocket status, restart task, restart logs, recovery probe.
+- `/datasources`: builtin sources, custom sources, realtime sources, detail/stat/task-status, trigger, batch trigger, enable/disable, clear data, realtime start/stop/restart, custom source test/sample/run/stop/status link.
+- `/data`: list, summary, source/type/country filters, search, pagination, detail metadata, export, distribution chart.
+- `/collection-management`: collector config, mapping templates, target schemas, collection schedule, history/snapshot, create config, propose/preview/create/activate mapping, builtin connect, run/stop/stream-status, credential guide read/generate/reset.
+- `/settings`: system display, notifications, security, SMTP get/save/test with recipient.
+- `/ai`: model providers, tool calling, prompts, key reveal, provider refresh, connect tests, OCR/WebSearch secrets, Playground thread/chat/edit/resend/stop.
+- `/earth-content`: brand preview as Earth renders it, upload/save/delete/reset, boundary status/build/config, TV source add/save/default/delete/reset.
+- `/logs`: sources, filters, snapshot, empty/error states, copy.
+- `/bgp`: overview, collectors, collect-location, incidents, anomalies, events, AI brief list/latest/detail/generate.
+- `/alerts/system`, `/alerts/bgp`, `/alerts/situational`: list/stat/detail, ack, resolve with note, AI brief generation.
+- `/users`: list/create/edit/delete, role, Gatekeeper permission groups.
+- Auth pages: login, register, verify email, resend cooldown, forgot/reset password.
+
+Compatibility routes under `/admin-next/*` should redirect to these official paths and are not a separate validation target.
+
+## Verified Manual Passes
+
+- 2026-05-20 `/admin-next/collection-management`: user verified collector create/edit payloads, mapping propose/preview/create/activate, custom collector test/sample/run/stop/status, credential guide read/generate/reset, and collection history/snapshot behavior after the draft-form and Time Capsule updates.
+- 2026-05-20 `/admin-next/datasources`: user verified builtin source trigger, task-status precheck, force recollect, batch trigger, enable/disable, and clear-data behavior.
+
+## Known Non-Production Tabs
+
+The old AntD page also marked these Earth content tabs as placeholder-level capabilities. Admin Next must show them as “backend capability pending” and must not mix in unrelated data:
+
+- `basemap`
+- `layer_resources`
+- `models_3d`
+- `news_anchor_strategy`
+
+## Replacement Rules
+
+- Keep `/legacy/admin/*` available until the matching route gate above is manually verified after promotion.
+- Do not delete old AntD pages, old layout helpers, `antd`, or `@ant-design/icons` until final explicit confirmation.
+- Do not use fake rows, unrelated endpoint data, or empty adapters for a real old capability.
+- Any backend-missing capability must be recorded here with the missing endpoint and visible UI empty state.
--- a/docs/deprecated/admin-next-soft-glass-goal-driven-plan.md
+++ b/docs/deprecated/admin-next-soft-glass-goal-driven-plan.md
@@ -0,0 +1,216 @@
+# Admin Next Soft Glass Goal-Driven Plan
+
+## Goal
+
+Rebuild `/admin-next/*` into a modern soft-glass / light-neumorphic console while keeping the legacy Ant Design admin routes available for comparison. The new console must use visual references only as design anchors, not as imported templates, and must be implemented as Planet-owned reusable components and page patterns.
+
+The redesign must cover desktop and mobile. Data display, icon semantics, table readability, and scroll behavior are first-class acceptance criteria.
+
+## Criteria For Success
+
+- This archived plan exists at `docs/deprecated/admin-next-soft-glass-goal-driven-plan.md`.
+- `/admin-next/*` has real pages for every route; route usage of `ShadowPage` is removed.
+- Admin Next supports `system`, `light`, and `dark` theme modes using the same persistence and system-theme idea as Docs.
+- The visual language reads as soft-glass / light-neumorphic instead of an AntD reskin: translucent panels, fine borders, subtle glow, cool backgrounds, restrained accent colors, crisp icons, and tactile controls.
+- Mobile is explicitly designed: mobile navigation, filter sheets/chips, card-list data views, full-screen detail sheets, and bottom action bars instead of squeezed desktop tables.
+- Tables do not show double scrollbars. Long fields are inspectable, copyable, or expandable; important columns stay readable.
+- Existing custom scrollbar components remain the default scroll experience.
+- `cd frontend && bun run build` passes.
+- Static checks can prove no route-level placeholder remains.
+
+## Reference Strategy
+
+Use references to calibrate feel, not to take over code:
+
+- User-provided soft-glass / light-neumorphic dashboard images define the desired mood.
+- Shadcn / Tailwind / glassmorphism admin templates may be inspected for shadow, spacing, panel, dark-mode, and app-shell ideas.
+- Do not import a complete template, router, auth layer, state layer, or business page.
+- Planet-specific interactions such as datasource tasks, BGP briefs, AI settings, log streams, Earth resources, and custom scrollbars are implemented in this repo.
+
+## Source-Of-Truth Mining
+
+Design content and page boundaries from existing repo history and docs:
+
+- `docs/CHANGELOG.md`
+- `docs/plans/*`
+- `docs/technical/*frontend*`
+- `TODO.md`
+
+Important current boundaries:
+
+- `DataSources` is a datasource directory and runtime-control page, not a configuration editor.
+- `Collection Management` owns collector endpoint, credential, custom source, mapping, and runtime configuration.
+- `Earth Content` owns TV livestreams, brand assets, boundary precision, basemap, and Earth display resources.
+- `AI` owns provider settings, tools, prompts, and Playground.
+- `BGP` is an observability and evidence workspace, not just tables.
+- `Alerts` is a duty/analysis workspace for system, BGP, and situational risk.
+- `Logs` should become a usable log workbench with filtering and structured detail.
+- `Settings` should keep platform settings only.
+
+## Reusable Architecture
+
+Recommended structure:
+
+- `admin-next/design`: theme tokens, theme mode, status colors, icon semantics, chart themes, scrollbar themes.
+- `admin-next/components`: primitive UI such as button, input, select, tabs, dialog, drawer, badge, status pill, icon badge.
+- `admin-next/patterns`: page patterns such as `PageFrame`, `GlassPanel`, `MetricCard`, `CommandBar`, `FilterRail`, `InspectorDrawer`, `DataWorkspace`, `SettingsWorkspace`, `ScrollableRegion`, `TableRegion`, and `MobileSheet`.
+- `admin-next/features`: business modules such as datasources, data-list, bgp, alerts, ai, logs, settings, earth-content, collection-management, users.
+- `admin-next/services`: feature API gateways and hooks. Pages should not scatter URL construction.
+- `admin-next/routes`: route manifest used by navigation, command search, breadcrumbs, and legacy links.
+
+## Interaction Rules
+
+- Row click opens an inspector; frequent row actions live in the inspector header.
+- Bulk selection opens a floating command bar.
+- Common filters stay visible; advanced filters open a sheet/drawer.
+- Detail, JSON, log context, and AI brief use inspector or reading panels instead of stacked modal dialogs.
+- Settings are split into `FormSection` blocks with local save, dirty state, connection test, and reset.
+- Dangerous actions use a confirm sheet.
+- Loading, empty, error, and retry states are shared through reusable patterns.
+
+## Mobile Rules
+
+- Do not squeeze desktop layout into mobile.
+- Use mobile navigation and sheets instead of a permanent desktop sidebar.
+- Filters collapse into a filter sheet; active filters remain visible as chips.
+- Data workspaces default to card-list mode on mobile and allow explicit table mode for dense comparison.
+- Details open in full-screen mobile sheets.
+- Batch actions use a sticky bottom command bar.
+- Long logs and JSON use full-screen reading/editing surfaces with custom scrollbars.
+
+## Table And Data Display Rules
+
+- Tables must prioritize complete data display:
+  - key columns get stable widths and priority;
+  - long fields have peek/expand or inspector detail;
+  - IDs, URLs, metadata, and errors are copyable;
+  - complex fields are rendered fully in inspector.
+- Desktop tables use one `TableRegion` scroll container.
+- Mobile defaults to card-list display and supports dense table mode.
+- Native scrollbar visuals are hidden where custom scrollbars apply.
+
+## Icon Rules
+
+- Use `lucide-react`.
+- Define icon semantics by category:
+  - navigation icon;
+  - entity icon;
+  - status icon;
+  - action icon;
+  - severity icon.
+- Icons must not be the only semantic carrier unless the icon is universally obvious; use labels or tooltips.
+- Status icons pair with `StatusPill`.
+- Colors come from tokens, not ad hoc hard-coded values.
+
+## Page Design
+
+### Dashboard
+
+- System health, realtime connection, datasource activity, task trend, alert summary, recent events, and quick commands.
+- Restart flow uses a confirm sheet and log console.
+- Mobile uses horizontal metric cards and collapsible event/command panels.
+
+### DataSources
+
+- Datasource directory and runtime control.
+- Desktop: overview rail, datasource table/list, inspector.
+- Mobile: datasource cards with status, latest task, trigger/toggle actions.
+- Batch trigger uses command bar.
+- Endpoint/config/task details are shown fully in inspector.
+
+### DataList
+
+- Collection result browsing, search, source/type filters, paging, distribution chart, and detail inspector.
+- Fix double scrollbars.
+- Mobile defaults to cards and allows table mode.
+
+### BGP
+
+- Views: collectors, incidents, anomalies, events, AI brief.
+- Emphasize severity, region, ASN/prefix, collector coverage, and evidence.
+- AI brief shows facts, judgment, and evidence gaps.
+
+### Alerts
+
+- Real pages for system, BGP, and situational alerts.
+- Shared alert workspace with stats, severity/status filters, list, and inspector.
+- AI brief appears in inspector/mobile sheet.
+
+### AI
+
+- Provider, tools, prompts, and Playground.
+- Provider and tool settings use local save and connection tests.
+- Prompt registry is grouped by task.
+- Mobile Playground uses step tabs rather than cramped columns.
+
+### Logs
+
+- Log workbench with source, level, date, search, refresh, copy, and structured detail.
+- Desktop uses a terminal-like log stream.
+- Mobile rows expand or open a full-screen reading sheet.
+
+### Users
+
+- Search, role filter, create/edit/delete, Gatekeeper groups.
+- Edit/create in drawer/sheet.
+- Gatekeeper groups use checkbox chips.
+
+### Settings
+
+- Platform settings only: system, notification, security, SMTP.
+- Each section saves independently.
+
+### Earth Content
+
+- TV livestreams, brand assets, boundary precision, basemap, and layer resources.
+- Resource previews, upload state, and boundary build status are emphasized.
+
+### Collection Management
+
+- Collector config, custom sources, mapping, runtime control.
+- Custom source creation uses a step sheet.
+- Advanced JSON is isolated in a collapsible editor.
+
+## Milestones
+
+1. Save this plan and establish goal-driven criteria.
+2. Build design/theme/pattern foundations.
+3. Remove route-level placeholders and create real pages for all `/admin-next/*` routes.
+4. Redesign layout, theme, mobile shell, scroll behavior, and table behavior.
+5. Fill core workspaces with real API calls and reusable patterns.
+6. Verify build, no `ShadowPage` route usage, and core route availability.
+
+## Verification
+
+Run:
+
+```bash
+cd frontend && bun run build
+rg "ShadowPage" frontend/src/admin-next
+rg "axios\\." frontend/src/admin-next/pages
+rg "overflow: auto|overflow-y: auto" frontend/src/admin-next
+```
+
+Manual route checks:
+
+- `/admin-next`
+- `/admin-next/datasources`
+- `/admin-next/data`
+- `/admin-next/bgp`
+- `/admin-next/alerts/system`
+- `/admin-next/alerts/bgp`
+- `/admin-next/alerts/situational`
+- `/admin-next/ai`
+- `/admin-next/logs`
+- `/admin-next/users`
+- `/admin-next/settings`
+- `/admin-next/earth-content`
+- `/admin-next/collection-management`
+
+Manual viewport checks:
+
+- desktop;
+- mobile width;
+- low height;
+- 125% / 150% browser zoom;
+- light / dark / system theme modes.
--- a/docs/deprecated/docs-gatekeeper-auth-plan.md
+++ b/docs/deprecated/docs-gatekeeper-auth-plan.md
@@ -0,0 +1,92 @@
+# Docs Gatekeeper 鉴权系统计划
+
+**状态**：已实现，当前行为见 [Docs Gatekeeper 开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/docs-gatekeeper-development.md)  
+**创建日期**：2026-05-08  
+**核心目标**：把 `/docs` 从前端公开打包 Markdown 改成后端受控读取，并通过用户 Gatekeeper 权限组划分公开文档、用户文档、开发文档和管理/运维文档。
+
+## 背景
+
+当前 Docs 页面通过前端 `import.meta.glob(...?raw)` 把 `docs/technical/{zh,en}` 中注册过的 Markdown 直接打进前端 bundle。即使在前端隐藏目录或增加路由守卫，受保护 Markdown 仍可能出现在构建产物中，无法形成真正鉴权。
+
+本阶段需要把文档正文读取迁到后端，并让后端根据当前用户身份返回可见目录和正文。Earth 仍保持公开访问，其它控制台模块暂不改变既有鉴权。
+
+## 鉴权模型
+
+保留现有 `users.role`，新增 `gatekeeper_groups` 作为可叠加的权限组。`role` 继续用于控制台和系统操作；Gatekeeper 只负责 Docs 等内容权限。
+
+默认权限：
+
+| 身份 | 默认 Docs 能力 |
+| --- | --- |
+| 未登录访客 | `public` |
+| 普通登录用户 | `public`，以及用户被分配的 Gatekeeper 组 |
+| `admin` | `docs_admin`，并隐含 `docs_developer` / `docs_user` |
+| `super_admin` | 全部 Docs 权限 |
+
+Gatekeeper 组：
+
+- `docs_user`：登录用户操作类文档。
+- `docs_developer`：开发、前端、后端、Earth 实现文档。
+- `docs_admin`：运维、服务控制、凭证、环境变量和敏感操作文档。
+
+## 初步文档划分
+
+`public`：
+
+- `README.md`
+- `quickstart.md`
+- `manual.md`
+
+`docs_developer`：
+
+- `earth-frontend-context.md`
+- `earth-interactable-usage.md`
+- `earth-layer-style-reference.md`
+- `earth-render-layer-order.md`
+- `earth-satellite-footprint-policy.md`
+- `earth-bgp-context.md`
+- `earth-news-live-streams-collector-format.md`
+- `earth-toolbar-overlay-coordination.md`
+- `frontend-admin-frontend-context.md`
+- `frontend-layout-guidelines.md`
+- `backend-collectors.md`
+- `datasource-collector-settings-connectivity.md`
+- `backend-datasources-api-performance.md`
+- `agents-aiprovider.md`
+
+`docs_admin`：
+
+- `backend-system-service-control.md`
+- `ops-docker-compose-buildx-upgrade.md`
+- `ops-planet-sh-startup.md`
+
+## 实施要点
+
+后端新增：
+
+- `GET /api/v1/docs/catalog`：返回当前用户可见文档目录；未登录只返回 `public`。
+- `GET /api/v1/docs/{lang}/{slug}`：返回单篇 Markdown；未登录访问受保护文档返回 `401`，已登录无权限返回 `403`。
+- 服务端维护文档 metadata 白名单，禁止任意路径读取。
+
+用户管理新增：
+
+- `users.gatekeeper_groups` JSON 字段。
+- 用户列表、创建和编辑支持展示/配置 Gatekeeper 权限组。
+- 只有 `super_admin` 能编辑 Gatekeeper 权限组。
+
+前端 Docs 改造：
+
+- 移除 Markdown raw import 作为正文来源。
+- 从后端 catalog 构建目录和搜索记录。
+- 从后端 content API 加载正文。
+- 对 `401` 显示登录入口，对 `403` 显示无权限提示。
+
+## 验证
+
+- 未登录用户只能看到和读取 `public` 文档。
+- 未登录直接访问受保护文档返回 `401` 并显示登录提示。
+- 无 Gatekeeper 组的普通用户访问开发文档返回 `403`。
+- `docs_developer` 用户能读开发文档，不能读管理/运维文档。
+- `admin` 和 `super_admin` 能读管理/运维文档。
+- 未知 slug、未知语言和路径穿越字符串不能读取文件。
+- 前端构建产物不再包含受保护 Markdown raw import 生成的文档模块。
--- a/docs/deprecated/earth-surface-hover-info-plan.md
+++ b/docs/deprecated/earth-surface-hover-info-plan.md
@@ -0,0 +1,105 @@
+# Earth Surface Hover Info Plan
+
+Status: Implemented.
+
+## Goal
+
+为 Earth 桌面和 compact 鼠标地表 hover 增加可配置的提示内容，让用户可以选择只看国家信息、只看位置数据，或同时查看国家和经纬海拔。
+
+当前地表 hover 已经具备两类信息：
+
+- 命中国家时显示国家、ISO、大洲，并高亮国界。
+- 未命中国家时显示纬度、经度、海拔。
+
+新方案把这两类信息合并成一个清晰的设置项：`悬停提示`。
+
+## User-facing behavior
+
+设置项放在桌面设置和移动端设置的 `视图` 区，使用分段控件：
+
+- `国家`：陆地命中国家时显示国家名、ISO、大洲；太平洋等海洋区域不显示地表 tooltip。
+- `位置`：陆地和海洋都显示纬度、经度、海拔；不触发国家 tooltip 和国家边界 hover 高亮。
+- `完整`：陆地命中国家时显示国家信息和纬度、经度、海拔；海洋区域显示纬度、经度、海拔。
+
+默认值为 `完整`，因为它保留现有国家识别价值，同时满足 hover 时查看经纬海拔的需求。
+
+海洋在 `国家` 模式下保持沉默，而不是显示大洋名称。原因是当前项目没有海域/大洋边界数据源；用经纬度粗判太平洋、大西洋等范围容易产生误导。如果用户需要海洋位置，使用 `位置` 或 `完整`。
+
+## Implementation plan
+
+### Settings state
+
+在 `frontend/public/earth/js/constants.js` 增加：
+
+```js
+export const SURFACE_HOVER_INFO_MODES = {
+  COUNTRY: "country",
+  POSITION: "position",
+  FULL: "full",
+};
+
+export const DEFAULT_SURFACE_HOVER_INFO_MODE =
+  SURFACE_HOVER_INFO_MODES.FULL;
+```
+
+在 `frontend/public/earth/js/controls.js`：
+
+- 将 `EARTH_SETTINGS_VERSION` 从 `10` 升到 `11`。
+- 在 shared settings 中新增 `surfaceHoverInfoMode`。
+- 新增导出：
+  - `getSurfaceHoverInfoMode()`
+  - `setSurfaceHoverInfoMode(mode, { persist, suppressStatus })`
+- normalize 时只接受 `country | position | full`，否则回退到 `full`。
+- reset settings 后恢复为 `full`。
+
+### Settings UI
+
+在桌面设置 `视图` 区和移动端设置 `视图` 区加入同一组按钮：
+
+```html
+<button data-surface-hover-info-mode="country">国家</button>
+<button data-surface-hover-info-mode="position">位置</button>
+<button data-surface-hover-info-mode="full">完整</button>
+```
+
+控件同步规则沿用现有卫星显示风格和巡航模块的模式：
+
+- 当前模式按钮添加 `is-active`。
+- 当前模式按钮设置 `aria-pressed="true"`。
+- 切换后保存到 Earth settings localStorage。
+
+### Hover tooltip logic
+
+在 `frontend/public/earth/js/main.js` 的地表 hover 分支中读取 `getSurfaceHoverInfoMode()`，统一构造 tooltip。
+
+行为规则：
+
+- 如果没有命中地球：清除国家 hover 并隐藏 tooltip。
+- `position`：
+  - 调用 `clearCountryBoundaryHover()`。
+  - 显示 `纬度 / 经度 / 海拔`。
+- `country`：
+  - 仅当国界图层开启并命中国家时显示国家 tooltip 和国界 hover。
+  - 海洋、国界图层关闭、未加载国界数据时隐藏地表 tooltip。
+- `full`：
+  - 国界图层开启且命中国家时显示国家信息加位置信息。
+  - 未命中国家或国界图层关闭时显示位置信息。
+
+海拔继续使用 `sampleElevationAt(lat, lon)`。暂无采样时显示 `—`，不因 hover 主动加载地形瓦片。
+
+## Acceptance criteria
+
+1. `完整` 模式下，hover 陆地显示国家信息和经纬海拔，hover 海洋显示经纬海拔。
+2. `国家` 模式下，hover 陆地显示国家信息，hover 太平洋等海洋不显示地表 tooltip。
+3. `位置` 模式下，hover 陆地和海洋都显示经纬海拔，国家边界不高亮。
+4. 关闭国界图层后，`完整` 模式回退为只显示位置。
+5. 船只、BGP、算力中心、海缆等对象 hover tooltip 优先级不变。
+6. 移动端中心国家高亮不受这个鼠标 hover 设置影响。
+7. 设置刷新后保持，重置后恢复为 `完整`。
+
+## Verification
+
+- 在 `frontend` 下运行 `/home/ray/.bun/bin/bun run build`。
+- 手动验证三种模式的陆地和海洋 hover 行为。
+- 验证设置持久化和重置。
+- 验证对象 hover 仍优先于地表 hover。
--- a/docs/deprecated/location-resolver-shared-pipeline-plan.md
+++ b/docs/deprecated/location-resolver-shared-pipeline-plan.md
@@ -0,0 +1,127 @@
+# Location Resolver Shared Pipeline Plan
+
+**状态**：已实现，当前用户流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md) 的 Earth 位置候选采集章节，开发接口见 [通用位置估算管线开发说明](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-development.md)。
+
+## Goal
+
+把"给定一条记录，决定它的 lat/lon"这件事抽象成一条统一的可插拔管线，让算力中心、BGP 观测站、BGP 事件——以及未来任何需要位置估算的实体——共用同一套接口。新算法（peeringdb 设施查询、IXP 表、用户认领的精确点位等）通过实现一个 Resolver 类即可挂入，不需要改任何上层调用方。
+
+## Background
+
+### 实施前现状
+
+- **算力中心** (`backend/app/services/compute_center_locations.py`) 早期曾使用源坐标 → 本地 JSON 注册表 → 城市兜底 → Nominatim 在线地理编码。后续为避免硬编码位置污染事实链路，算力中心本地注册表已移除；主地图只使用源坐标，手动候选采集使用 ROR 和 Nominatim。
+- **BGP 观测站** (`collectors/bgp_common.py:RIPE_RIS_COLLECTOR_COORDS`) 是一张写死的字典，26 个 RIPE RIS collector 的城市级坐标。新增 collector / 升级到设施级精度都得改 Python。
+- **BGP 事件**继承所属 collector 的城市级坐标（`BGPObservation.collector_geo`）。
+- 用户原本以为 BGP 观测站位置是通过 iptoasn 推断的——其实 iptoasn 只用于前缀级国家归属（`bgp_enrichment.py`），不影响 marker 坐标。
+
+### 痛点
+
+1. 算力中心那条 4 层链路写死在算力中心模块里，BGP 想用得复制一遍。
+2. 三类实体各走各的坐标策略，缺统一抽象。
+3. 未来要插更精的算法（peeringdb / IXP / 用户认领），现在没有挂入点。
+
+## Design
+
+### 接口契约
+
+`backend/app/services/location/`：
+
+- `models.py` —— `LocationQuery`（输入）、`LocationCandidate`（候选）、`ResolverOutput`（单 resolver 输出）、`ResolutionResult`/`ResolutionDiagnostic`（管线最终结果）
+- `pipeline.py` —— `LocationResolver` Protocol、`LocationPipeline` 编排器
+- `resolvers/source_coordinates.py` —— 记录自带 lat/lon 时直通
+- `resolvers/registry.py` —— 本地 JSON 注册表（locations + city_fallbacks），按别名得分
+- `resolvers/nominatim.py` —— 通用 Nominatim 客户端（rate-limited + LRU 缓存）+ 可注入 query plan
+- `resolvers/inherit.py` —— 从外部回调取候选（事件继承 collector 用）
+- `text.py` —— 文本规范化共享工具
+
+核心 Protocol：
+
+```python
+class LocationResolver(Protocol):
+    name: str
+    def resolve(self, query: LocationQuery) -> ResolverOutput: ...
+```
+
+`LocationPipeline.collect_candidates()` 跑全部 resolver，聚合所有候选，按 `(source_rank, precision_rank, -confidence)` 排序去重；`resolve_best()` 选 top 候选。
+
+### 各领域管线
+
+```python
+# compute_center_locations.py（重构后，公共 API 不变）
+COMPUTE_CENTER_PIPELINE = LocationPipeline([
+    SourceCoordinatesResolver(),
+])
+
+COMPUTE_CENTER_COLLECTION_PIPELINE = LocationPipeline([
+    SourceCoordinatesResolver(),
+    ROROrganizationResolver(),
+    NominatimResolver(query_plan_builder=_compute_center_query_plan,
+                      geocoder=lambda q: _geocode_online(q)),
+])
+
+# bgp_collector_locations.py（新）
+BGP_COLLECTOR_PIPELINE = LocationPipeline([
+    SourceCoordinatesResolver(),
+    StoredCollectorLocationResolver(),
+])
+
+BGP_COLLECTOR_COLLECTION_PIPELINE = LocationPipeline([
+    SourceCoordinatesResolver(),
+    NominatimResolver(query_plan_builder=_bgp_collector_query_plan,
+                      geocoder=lambda q: _geocode_online(q)),
+])
+
+# bgp_event_locations.py（新）
+BGP_EVENT_PIPELINE = LocationPipeline([
+    SourceCoordinatesResolver(),
+    InheritFromAnotherEntityResolver(source_lookup=_inherit_from_owning_collector),
+    # 占位：将来插 ASNFacilityResolver / PrefixGeoResolver
+])
+```
+
+### 关键设计决策
+
+1. **算力中心公共 API 完全不变**：`resolve_compute_center_location()`、`collect_location_candidates()`、`ComputeCenterLocation` dataclass、`_geocode_online` 模块级符号都保留，前端 / 上层调用方零改动；现有 19 个回归测试全绿。
+2. **`_geocode_online` 用 lambda 晚绑定**：`NominatimResolver(geocoder=lambda q: _geocode_online(q))` 能让测试 `monkeypatch.setattr(module, "_geocode_online", fake)` 继续生效。
+3. **`RIPE_RIS_COLLECTOR_COORDS` 自动从 DB-backed cache 重建**：启动时 seed/refresh `bgp_collector_locations` 维表，再原地刷新旧 `{rrcXX → {city, country, lat, lon}}` 字典。下游消费者（`bgp_collectors.py`、序列化、detector）不动即可获得新元数据。
+4. **修复隐藏 bug**：BGP collector 不再通过 registry/operator 模糊匹配晋升候选，避免 `operator="RIPE NCC"` 让每个事件都落到 `rrc00`。
+5. **事件继承走严格名字查询**：事件继承不跑 collector 的完整 pipeline，改成直接查 DB-backed cache。"改进位置"用户触发流程只跑源坐标和在线地理编码候选。
+
+## Files
+
+### 新增
+- `backend/app/services/location/__init__.py`
+- `backend/app/services/location/models.py`
+- `backend/app/services/location/pipeline.py`
+- `backend/app/services/location/text.py`
+- `backend/app/services/location/resolvers/__init__.py`
+- `backend/app/services/location/resolvers/source_coordinates.py`
+- `backend/app/services/location/resolvers/registry.py`
+- `backend/app/services/location/resolvers/nominatim.py`
+- `backend/app/services/location/resolvers/inherit.py`
+- `backend/app/services/bgp_collector_locations.py`
+- `backend/app/services/bgp_event_locations.py`
+- `backend/app/models/bgp_collector_location.py`
+- `backend/tests/test_location_pipeline.py`（16 用例）
+- `backend/tests/test_bgp_collector_locations.py`（11 用例）
+
+### 修改
+- `backend/app/services/compute_center_locations.py` —— 改为薄包装
+- `backend/app/services/collectors/bgp_common.py` —— 删除写死字典，改调 `resolve_bgp_event_geo_dict()`
+- `backend/app/api/v1/bgp.py` —— 新增 `POST /api/v1/bgp/collectors/{collector_id}/collect-location`
+- `frontend/public/earth/js/info-card.js` —— `renderComputeCenterCollectSection` → `renderLocationCollectSection`，BGP collector 走通用化路径
+- `frontend/public/earth/js/compute-centers.js` —— 新增通用 `collectLocationCandidates(endpoint, payload)`
+- `frontend/public/earth/js/main.js` —— `previewComputeCenterCandidate` → `previewLocationCandidate`，事件名改为 `earth:preview-location-candidate`
+
+## Verification
+
+- `uv run pytest backend/tests/test_visualization_compute_centers.py` —— 19 个用例全绿（公共 API 未改）
+- `uv run pytest backend/tests/test_location_pipeline.py backend/tests/test_bgp_collector_locations.py` —— 16 + 11 用例全绿
+- 抽象可插拔性测试：`test_pluggability_custom_resolver_works_without_changing_pipeline` —— 临时实现 `_PeeringDBStubResolver` 直接接入 `LocationPipeline`，验证管线不需要改一行就能识别新 source
+
+## Out of scope
+
+- 持久化用户认领的精确坐标（写回 JSON 注册表）—— `suggested_registry_entry` 字段已就绪，工作流单独立项
+- 真正实现 `ASNFacilityResolver` / `PrefixGeoResolver` —— 接口已留好，具体算法（peeringdb / IXP 表 / iptoasn 升级）单独立项
+- 算力中心 / 观测站 marker 合并避让 —— 上一轮已用 `SURFACE_AVOIDANCE_PROFILES.city` + halo 收敛解决