fquiz/memory/2026-06-09.md

## Work Log - 修复 Buildx 安装阶段访问 Docker Hub 超时（2026-06-09）

- 背景：
  - GitHub Actions run `27150975287` 在 `build-and-push` job 的 `安装 Buildx` 步骤失败，后续镜像构建与部署全部被跳过。
  - check-run annotation 给出的精确错误为：
    - `Head "https://registry-1.docker.io/v2/moby/buildkit/manifests/buildx-stable-1" ... Client.Timeout exceeded while awaiting headers`
  - 根因不是仓库镜像构建脚本本身，而是 `docker/setup-buildx-action` 默认 `docker-container` 驱动在启动 BuildKit builder 时，需要先从 Docker Hub 拉 `moby/buildkit:buildx-stable-1`，受外网访问抖动影响直接超时。

- 本次处理：
  - `.github/workflows/main.yml`
    - `actions/checkout` 升级到 `v6`。
    - `docker/setup-buildx-action` 升级到 `v4`，并显式指定：
      - `driver-opts: image=docker.m.daocloud.io/moby/buildkit:buildx-stable-1`
      - 避免 Buildx 初始化再访问 Docker Hub 拉默认 BuildKit 镜像。
    - `docker/login-action` 升级到 `v4`。
    - `docker/build-push-action` 升级到 `v7`。
  - 兼带收益：
    - 消除了该次 run 中出现的 `Node.js 20 actions are deprecated` 预警里的旧版 `checkout/setup-buildx`。

- 验证：
  - 基线：
    - GitHub Actions run `27150975287` 失败，且失败点固定在 `安装 Buildx`。
    - check-run annotation 可复核到 Docker Hub `moby/buildkit` 拉取超时。
  - 修改后：
    - `python3` 解析 `.github/workflows/main.yml` 通过。
    - `actionlint` 校验变更前/变更后 workflow 均可解析，变更未引入 YAML / Actions 语法问题。
    - `git diff --check -- .github/workflows/main.yml` 通过。
  - 当前环境限制：
    - 无法直接在本地实际执行 GitHub hosted runner 上的 `setup-buildx` 拉起流程，真实恢复效果需要依赖下一次 Actions 运行确认。

- 风险与关注点：
  - 本次修复只绕开 BuildKit builder 镜像对 Docker Hub 的依赖；后续若 `Dockerfile` 里的基础镜像或 `docker build --pull` 仍指向不稳定上游，构建阶段仍可能出现其他网络相关失败。

## Work Log - 修复线路管理走向图在 `/fl` 子路径下无法渲染（2026-06-09）

- 背景：
  - Issue `FL-60` 反馈“线路管理中走向图渲染不出来”。
  - 仓库部署默认启用 `NEXT_PUBLIC_APP_BASE_PATH=/fl`，但多个 Cesium 组件初始化时仍把 `window.CESIUM_BASE_URL` 硬编码为 `"/cesium"`。
  - 这会导致页面在 `/fl/admin/power-lines` 等子路径下请求错误的静态资源地址，最终触发 Cesium Viewer 初始化失败。

- 本次处理：
  - `web/src/components/power-line-cesium-map.tsx`
    - 将走向图 Cesium 静态资源根路径改为 `withBasePath("/cesium")`，修复线路管理走向图在 `/fl` 部署下的资源寻址。
  - `web/src/components/elevation-preview-cesium-map.tsx`
    - 同步改为 `withBasePath("/cesium")`，避免高程预览图在相同部署口径下继续空白。
  - `web/src/components/lightning-distribution-map.tsx`
    - 同步改为 `withBasePath("/cesium")`，保持雷电分布图与项目子路径部署口径一致。
    - 顺手补齐 `Viewer` / `CesiumNamespace` / `Cartesian3[]` 显式类型，消除本地 lint 暴露的 `no-explicit-any` 问题。

- 验证：
  - 基线：
    - 代码检查确认 `power-line-cesium-map.tsx`、`elevation-preview-cesium-map.tsx`、`lightning-distribution-map.tsx` 都存在 `window.CESIUM_BASE_URL = "/cesium"` 硬编码。
    - 部署配置检查确认 `deploy/pro-deploy/.env` 与 compose / Dockerfile 默认均为 `NEXT_PUBLIC_APP_BASE_PATH=/fl`。
    - 初次本地 lint 尝试因未安装前端依赖失败；补充执行 `NPM_CONFIG_CACHE=/tmp/npm-cache npm ci` 后继续验证。
  - 修改后：
    - `NPM_CONFIG_CACHE=/tmp/npm-cache npm --workspace web exec eslint src/components/power-line-cesium-map.tsx src/components/elevation-preview-cesium-map.tsx src/components/lightning-distribution-map.tsx src/app/admin/power-lines/page.tsx --max-warnings=0` -> 通过。
    - `NEXT_PUBLIC_APP_BASE_PATH=/fl NPM_CONFIG_CACHE=/tmp/npm-cache npm run build:web` -> 通过。

- 风险与关注点：
  - 本次修复聚焦前端静态资源路径，不涉及后端接口、数据库或权限逻辑。
  - 若后续新增 Cesium 页面，必须继续复用 `withBasePath("/cesium")`，不能再硬编码根路径。

## Work Log - 文件管理页移除索引同步时间列（2026-06-09）

- 背景：
  - Issue `FL-61` 要求文件管理页面不再展示“索引同步时间”列。
  - 代码检索确认该展示仅存在于 `web/src/app/admin/files/page.tsx` 的表格列定义中，未发现额外前端展示点。

- 本次处理：
  - `web/src/app/admin/files/page.tsx`
    - 从文件列表表格列定义中移除“索引同步时间”列。
    - 保持接口请求、返回字段与前端类型不变，仅调整页面展示。

- 验证：
  - 基线：
    - `npm ci --cache /tmp/npm-cache` 成功补齐前端依赖。
    - `npm --workspace web exec eslint src/app/admin/files/page.tsx --max-warnings=0` -> 通过。
    - `npm run lint:web` 当前因仓库既有问题失败，主要包含 `web/public/cesium/**` 生成资源与 `web/src/app/admin/syslog/page.tsx` 的现存 lint error，和本次改动无关。
  - 修改后：
    - `npm --workspace web exec eslint src/app/admin/files/page.tsx --max-warnings=0` -> 通过。

- 风险与关注点：
  - 本次变更仅影响文件管理页列表展示，不涉及后端索引同步逻辑，也不影响其它复用该接口的页面读取 `synced_at` 字段。

## Work Log - ATP/EGM/Wine 生产计算链路接入 legacy_atp worker 适配（2026-06-09）

- 背景：
  - Issue `FL-69` 要求把 `fl-knowledge` 的旧 ATP/EGM 生产计算协议接入 `fquiz`，并确保真实计算执行在 worker 中异步完成。
  - 现状是：
    - `fl_analysis_service` 已有 Celery worker 链路，但 `external_adapter` 仅支持 `placeholder/atp/wine`。
    - 通用 `fl_analysis_external.py` 只覆盖“ATP 模板渲染 + 子进程执行”的简化协议，不承接旧 ATP 目录协议、特征写入和 EGM/rjtzl.exe。
    - `atp_model_service.get_engine_status()` 只能返回 ATP engine 总体可用性，不能细分 `tpbig.exe/rjtzl.exe/legacy_root/EGM子目录` 等资产状态。

- 本次处理：
  - `api/app/services/legacy_atp_adapter.py`
    - 新增独立 legacy ATP/EGM 业务适配层，不把旧链路逻辑混入通用 `wine_service.py`。
    - 支持：
      - `WINE_ALLOWED_ROOT` 下的 legacy 资产路径校验。
      - 旧模板目录解析、`fanji/raoji1/raoji2/raoji3` 模式选择。
      - ATP 特征配置读取与定长 offset/length 写入。
      - `gb18030/gbk/utf-8-sig/utf-8` 配置与结果文件解码。
      - `tpbig.exe` 与 `rjtzl.exe` 调用。
      - EGM 子目录存在性校验、`rjtzl.exe运行失败，所得绕击跳闸率无效` 错误归一化。
      - 结果文件 / stdout 解析并映射到现有防雷分析结果结构。
    - 同时补了 legacy 资产状态检查构建函数，给 ATP 状态接口复用。
  - `api/app/services/fl_analysis_service.py`
    - 扩展 `external_adapter` 支持 `legacy_atp`。
    - 在 `normal/tongtiao` worker 执行链路中直接调用 `resolve_legacy_atp_job()` / `execute_legacy_atp_tower_analysis()`。
    - `scenario` 复算场景会沿用基线任务的 `external_adapter + adapter_config_json`，因此也能复用 `legacy_atp`。
    - 保持长耗时执行仍在现有 `execute_fl_analysis_job` worker 中完成，API 侧只负责校验和派发。
  - `api/app/services/atp_model_service.py`
    - ATP 状态响应新增 `checks` 明细，细分返回：
      - `wine`
      - `legacy_root`
      - `template_root`
      - `run_root`
      - `tpbig_executable`
      - `rjtzl_executable`
      - `egm_subdir`
  - `api/app/core/config.py`
    - 新增 legacy ATP/EGM 资产配置项：
      - `atp_legacy_root`
      - `atp_tpbig_executable`
      - `atp_rjtzl_executable`
      - `atp_template_root`
      - `atp_run_root`
      - `atp_egm_subdir`
  - `api/app/schemas/fl_analysis.py` / `api/app/schemas/atp_model.py`
    - 扩展 adapter 枚举和 ATP 状态响应字段，补齐接口契约。
  - 新增测试：
    - `api/tests/test_legacy_atp_adapter_paths.py`
    - `api/tests/test_legacy_atp_feature_set.py`
    - `api/tests/test_fl_analysis_legacy_atp_adapter.py`
    - `api/tests/test_atp_engine_task.py`

- 验证：
  - `python3 -m py_compile app/services/legacy_atp_adapter.py app/services/fl_analysis_service.py app/services/atp_model_service.py app/schemas/fl_analysis.py app/schemas/atp_model.py app/core/config.py tests/test_legacy_atp_adapter_paths.py tests/test_legacy_atp_feature_set.py tests/test_fl_analysis_legacy_atp_adapter.py tests/test_atp_engine_task.py`
    - 通过
  - `UV_CACHE_DIR=/tmp/uv-cache uv run --with-requirements requirements.txt --with pytest --no-project env PYTHONPATH=. python -m pytest tests/test_atp_engine_task.py tests/test_wine_probe.py tests/test_legacy_atp_adapter_paths.py tests/test_legacy_atp_feature_set.py tests/test_fl_analysis_legacy_atp_adapter.py tests/test_fl_analysis_external.py tests/test_async_dispatch_services.py tests/test_atp_model_service.py tests/test_fl_analysis_service.py tests/test_fl_analysis_schema.py`
    - `19 passed, 1 warning`
    - warning 为既有 SQLAlchemy relationship overlap 提示，与本次改动无直接关系。
  - `git diff --check`
    - 通过

- 风险与关注点：
  - 当前仓库内仍没有 `tpbig.exe`、`rjtzl.exe`、旧 ATP 模型目录和 EGM 子目录等真实生产运行资产；本次交付的是代码层接入、状态检测和可测的 worker 执行协议。
  - 上线前仍需在容器/部署环境提供实际 legacy 资产挂载，并用真实资产做 smoke test。

## Work Log - 任务监控页面样式布局优化（2026-06-09）

- 背景：
  - Issue `FL-72` 要求“参考用户管理页面的样式和布局优化任务监控页面，包括 margin、padding、border 以及自适应高度”等。
  - 现状是 `web/src/app/admin/task-monitor/page.tsx` 采用“筛选卡 + 表格卡”的分离布局，和用户管理页的单卡结构不一致；任务表格也缺少在少量数据下的最小高度占位与视口自适应滚动高度。

- 本次改动：
  - `web/src/app/admin/task-monitor/page.tsx`
    - 页面主体收敛为与用户管理页一致的单卡布局，标题统一为“任务监控”。
    - 将 Worker/队列/任务/状态筛选与自动刷新开关合并进卡片顶部 `Form inline` 区域，补充“重置筛选”按钮。
    - 卡片顶部 `extra` 区域增加统一的刷新按钮和加载中的小型 `Spin`，保持和管理页操作区的交互节奏一致。
    - 增加生成时间、Worker 总数、在线/离线数、筛选后任务数的二级信息行，替代原本散落在筛选区尾部的时间文案。
    - 任务表格新增与用户管理页一致的动态高度计算（`scroll.y` + `resize` 监听 + `ResizeObserver`），避免筛选结果较少时表格区域坍塌。
    - 加载态统一为 `min-h-[240px]` 居中 `Spin`；空态文案改为“暂无符合筛选条件的任务数据。”。
    - 保持任务监控的数据请求、轮询、权限判断和表格列定义不变，仅调整布局与展示容器。
  - `web/src/app/globals.css`
    - 新增 `.admin-task-monitor-table-anchor .ant-table-body` 作用域样式，通过页面注入变量设置最小高度，避免影响其他 Ant Design 表格。

- 验证：
  - 基线：
    - `npm --workspace web exec eslint src/app/admin/task-monitor/page.tsx --max-warnings=0` -> 通过。
  - 修改后：
    - `npm --workspace web exec eslint src/app/admin/task-monitor/page.tsx --max-warnings=0` -> 通过。
    - `npm run build:web` -> 通过。

- 风险与关注点：
  - 影响范围仅 `任务监控` 页面前端展示层与局部表格样式作用域，不涉及后端接口、权限或任务监控数据口径变更。

## Work Log - 统一后台页面首屏加载效果居中（2026-06-09）

- 背景：
  - Issue `FL-73` 反馈“有些页面第一次打开时加载效果在左上角，而另一些页面在页面正中间，同一改成正中间”。
  - 代码检索确认后台页面首屏加载态存在两种实现：
    - 多数页面使用 `min-h-[240px]/[280px] + 居中 Spin`；
    - `线路管理`、`雷电流/雷电分布`、`杆塔模型管理` 仍使用 `Card + Typography.Text`，因此首屏只在左上角显示一行加载文案。

- 本次改动：
  - `web/src/components/admin-page-loading.tsx`
    - 新增后台页面通用首屏加载组件，统一输出居中 `Spin`，并支持通过 `minHeightClassName` 复用不同页面的最小高度口径。
  - `web/src/app/admin/power-lines/page.tsx`
    - 将首屏 `加载线路数据中...` 从左上角文本卡片改为居中 `Spin`。
  - `web/src/app/admin/lightning-currents/page.tsx`
    - 将 `雷电流` / `雷电分布` 首屏加载态统一改为居中 `Spin`。
  - `web/src/app/admin/tower-models/page.tsx`
    - 将 `加载杆塔模型中...` 从左上角文本卡片改为居中 `Spin`。

- 验证：
  - 基线：
    - `npm run lint` 当前因仓库既有问题失败，主要来自 `web/public/cesium/**` 生成资源和少量历史页面，不作为本次门禁。
  - 修改后：
    - `npm exec eslint src/components/admin-page-loading.tsx src/app/admin/power-lines/page.tsx src/app/admin/lightning-currents/page.tsx src/app/admin/tower-models/page.tsx`
      - 通过；仅保留 `tower-models` 既有 `<img>` warning，无新增 error。
    - `npm run build`
      - 通过。

- 风险与关注点：
  - 本次仅统一后台页面首屏加载态展示，不涉及接口、权限、数据结构或业务请求逻辑。
  - 后续新增后台页面时，若需要页面级首屏加载态，应优先复用 `AdminPageLoading`，不要再回退到左上角纯文本占位。

## Work Log - 补齐 Worker 监控页面首屏居中加载态（2026-06-09）

- 背景：
  - FL-73 在回归评论中反馈“Worker监控页面的loading还是在左上角”。
  - 排查确认上次统一的是 `web/src/app/admin/task-monitor/page.tsx`，但用户实际访问的是另一个独立路由 `web/src/app/admin/workers/page.tsx`。
  - 该页面首屏分支仍是 `py-10 + Spin`，因此加载提示停留在左上区域。

- 本次改动：
  - `web/src/app/admin/workers/page.tsx`
    - 复用 `web/src/components/admin-page-loading.tsx` 统一首屏加载态。
    - 将 `Worker监控数据加载中...` 改为 `min-h-[280px]` 的居中 `Spin`，与此前 `线路管理/雷电流/杆塔模型` 的修复口径保持一致。

- 验证：
  - `cd web && npm exec eslint -- src/app/admin/workers/page.tsx src/components/admin-page-loading.tsx`
    - 通过

- 风险与关注点：
  - 仅影响 `/admin/workers` 页面首屏展示，不涉及 Worker 数据接口、抽屉详情、权限或轮询逻辑。

## Work Log - 高程数据支持 DEM 地形瓦片预览与线路地形图（2026-06-09）

- 背景：
  - Issue `FL-74` 要求高程数据除已有样本预览与线路高程回填外，还要支持：
    - 将 DEM 栅格数据生成可供 Cesium 直接消费的地形瓦片；
    - 在高程管理页预览真实 DEM 地形；
    - 在线路管理页基于选定 DEM 显示线路地形图，并暴露地形状态与必要提示。
  - 现状是：
    - 后端已有高程数据集、分析任务和线路高程回填链路；
    - 前端已有 Cesium 预览组件，但仍以点云/网格覆层为主，没有接入真正的 Cesium terrain provider。

- 本次改动：
  - 后端：
    - `api/app/models/elevation.py`
      - 为 `ElevationDataset` 增加 `terrain_status/task/error/root/url_template/min_zoom/max_zoom/bounds/metadata` 等字段。
    - `api/app/core/database.py`
      - 扩展兼容列自动补齐逻辑，为已有实例增量补地形字段，并对历史 raster/csv 数据做默认状态回填。
    - `api/app/services/elevation_service.py`
      - 新增 DEM 地形瓦片构建主链路：
        - 栅格边界转换到 WGS84；
        - 计算 TMS 瓦片层级与范围；
        - 生成 Cesium `heightmap-1.0` 瓦片二进制与 `layer.json`；
        - 分析成功后自动派发地形构建任务；
        - 提供地形状态查询、手动构建、layer/tile 读取服务。
    - `api/app/tasks/elevation_tasks.py`
      - 新增 terrain build Celery task。
    - `api/app/api/v1/elevation.py`
      - 新增接口：
        - `POST /api/v1/elevation/datasets/{id}/terrain/build`
        - `GET /api/v1/elevation/datasets/{id}/terrain/status`
        - `GET /api/v1/elevation/datasets/{id}/terrain/layer.json`
        - `GET /api/v1/elevation/datasets/{id}/terrain/{z}/{x}/{y}.terrain`
    - `api/tests/test_elevation_terrain_service.py`
      - 补充地形瓦片编码、状态查询与 layer 读取测试。
    - `api/tests/test_async_dispatch_services.py`
      - 补充 terrain task 复用与不支持格式状态断言。
  - 前端：
    - `web/src/components/elevation-preview-cesium-map.tsx`
      - 支持真实 terrain provider、指针高程读数、terrain failure 回退提示和数据集范围框。
    - `web/src/components/power-line-cesium-map.tsx`
      - 支持选定 DEM 地形、垂直夸张、塔位越界告警、地形加载失败回退和塔位高程来源展示。
    - `web/src/app/admin/elevation/page.tsx`
      - 增加地形状态列、地形层级列、地形状态弹窗、手动生成/重试地形入口；
      - 高程预览弹窗传入 dataset + access token，使预览地图优先加载真实 DEM。
    - `web/src/app/admin/power-lines/page.tsx`
      - 增加 DEM 数据集选择与垂直夸张选择；
      - 线路地图传入 terrain dataset + access token + exaggeration；
      - 增加 DEM 状态/覆盖范围提示。
    - `web/src/lib/elevation-terrain.ts`
      - 抽出地形状态判定、layer 地址解析、塔位越界统计。
    - `web/src/lib/elevation-terrain.test.js`
      - 补充地形状态与越界统计测试。
    - `web/src/lib/power-line-route.ts`
      - 扩展塔位高程溯源字段解析，用于地图弹窗展示。
    - `web/src/types/auth.ts`
      - 补齐 terrain 相关类型。

- 验证：
  - 基线：
    - `UV_CACHE_DIR=/tmp/uv-cache uv run --with-requirements requirements.txt --with pytest --no-project env PYTHONPATH=. python -m pytest tests/test_async_dispatch_services.py tests/test_line_preparation_flow.py tests/test_tower_profile_migration.py`
      - `10 passed, 1 warning`
  - 修改后：
    - `python3 -m py_compile app/api/v1/elevation.py app/tasks/elevation_tasks.py app/services/elevation_service.py app/schemas/elevation.py app/models/elevation.py app/core/database.py tests/test_async_dispatch_services.py tests/test_elevation_terrain_service.py`
      - 通过
    - `UV_CACHE_DIR=/tmp/uv-cache uv run --with-requirements requirements.txt --with pytest --no-project env PYTHONPATH=. python -m pytest tests/test_async_dispatch_services.py tests/test_line_preparation_flow.py tests/test_tower_profile_migration.py tests/test_elevation_terrain_service.py`
      - `15 passed, 1 warning`
    - `node --test web/src/lib/elevation-terrain.test.js web/src/lib/power-line-route.test.js`
      - `6 passed`
    - `cd web && NPM_CONFIG_CACHE=/tmp/npm-cache ./node_modules/.bin/eslint ./src/components/elevation-preview-cesium-map.tsx ./src/components/power-line-cesium-map.tsx ./src/app/admin/elevation/page.tsx ./src/app/admin/power-lines/page.tsx ./src/lib/elevation-terrain.ts ./src/lib/elevation-terrain.test.js ./src/lib/power-line-route.ts --max-warnings=0`
      - 通过
    - `cd web && NPM_CONFIG_CACHE=/tmp/npm-cache ./node_modules/.bin/tsc --noEmit`
      - 通过
    - `cd web && NPM_CONFIG_CACHE=/tmp/npm-cache npm run build`
      - 通过
    - `git diff --check`
      - 通过

- 风险与关注点：
  - 真实 Cesium 地形请求当前依赖 Bearer token 头传递，不能退化为 cookie-only 访问；后续若调整认证中间件，需要一并回归 terrain provider 链路。
  - 当前生成格式固定为 `heightmap-1.0` + `EPSG:4326` + `TMS`；若未来要切到 quantized-mesh，需要重新评估生成器和前端兼容层。