# ApiClient 异步化（DatasetDetail 路径）实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把数据集详情路径（原数据 + 网格数据）从同步阻塞改为 Qt 原生异步，UI 全程不冻、慢请求可 abort、失败 fail-fast，作为全 App 异步化的模式样板。

**Architecture:** `ApiClient` 新增 `getAsync/postJsonAsync` 返回自管理 QObject 句柄 `ApiCall`（实现可测的 `IApiCall`）；`ApiBatch` 并发汇聚多请求并 fail-fast；data 层 `ApiDatasetRepository` 用 batch 组装 `ChartLoad`/`GridLoad` 句柄（抽象基类 + Api 实现，供 stub 测试）；`DatasetDetailController` 改 abort-and-replace + 句柄身份比对，对外信号面不变。核心安全靠「各层 `aborted_` 入口守卫 + 控制器句柄身份比对 + 一律 deleteLater」杜绝迟到信号回灌。

**Tech Stack:** Qt6 (Core/Network/Test)、QNetworkAccessManager 原生异步、CMake + Ninja + MSVC、GoogleTest/CTest、QSignalSpy。

**权威设计：** `docs/superpowers/specs/2026-06-11-apiclient-async-design.md`（含 §5.0 安全不变量、§7 错误判定、§8 测试策略）。

**构建/测试命令：**
- 构建：`powershell.exe -ExecutionPolicy Bypass -File scripts/dev-build.ps1`
  - 若报 `LNK1104 ... geopro_desktop.exe`：先 `Get-Process geopro_desktop -ErrorAction SilentlyContinue | Stop-Process -Force` 再构建。
- 全量测试：`powershell.exe -ExecutionPolicy Bypass -File scripts/dev-test.ps1`（基线 75/75 绿）
- 单测过滤：`build/release/tests/geopro_tests.exe --gtest_filter=ApiBatch.*`

---

## 文件结构

**新建：**
- `src/net/IApiCall.hpp` — 抽象 QObject 缝：`finished(ApiResponse)` 信号 + 纯虚 `abort()`。
- `src/net/ApiCall.hpp` / `src/net/ApiCall.cpp` — 包一个 `QNetworkReply` 的 `IApiCall` 实现。
- `src/net/ApiResponseParse.hpp` / `src/net/ApiResponseParse.cpp` — `buildResponse(QNetworkReply*)`（从现 `Impl::await` 抽出解析部分，sync/async 共用，DRY）。
- `src/net/ApiBatch.hpp` / `src/net/ApiBatch.cpp` — 并发汇聚 + fail-fast 原语。
- `src/data/api/DatasetLoads.hpp` — `ChartParts` / `GridParts` 结果载体（纯结构体）。
- `src/data/api/DatasetLoadHandles.hpp` / `src/data/api/DatasetLoadHandles.cpp` — 抽象 `ChartLoad`/`GridLoad`（QObject 基类）+ 具体 `ApiChartLoad`/`ApiGridLoad`（包 ApiBatch + 解析）。
- `src/data/repo/IAsyncDatasetRepository.hpp` — 详情异步仓储抽象（返回 `ChartLoad*`/`GridLoad*`）。
- `tests/net/FakeApiCall.hpp` — 测试假 call（**不声明 Q_OBJECT**，发射继承的 `finished`、记录 `abort`）。
- `tests/net/test_api_batch.cpp` — ApiBatch 离线单测。
- `tests/data/test_dataset_load_handles.cpp` — ChartLoad/GridLoad 句柄离线单测。
- `src/app/panels/LoadingOverlay.hpp` / `src/app/panels/LoadingOverlay.cpp` — 轻量「加载中」遮罩（Task 8，可后置）。

**修改：**
- `src/net/ApiClient.hpp` / `.cpp` — 加 `getAsync/postJsonAsync`；`await` 改用 `buildResponse`；`ApiResponse` 加 `Q_DECLARE_METATYPE`。
- `src/net/CMakeLists.txt` — AUTOMOC ON；加 ApiCall/ApiBatch/ApiResponseParse 源。
- `src/data/api/ApiDatasetRepository.hpp` / `.cpp` — 改实现 `IAsyncDatasetRepository`。
- `src/data/CMakeLists.txt` — AUTOMOC ON；加 DatasetLoadHandles 源。
- `src/controller/DatasetDetailController.hpp` / `.cpp` — 依赖 `IAsyncDatasetRepository`、abort-and-replace、`loadStarted` 信号。
- `tests/controller/test_dataset_detail_controller.cpp` — 改异步 stub + 回灌防护用例。
- `tests/CMakeLists.txt` — 加 test_api_batch / test_dataset_load_handles。
- `src/app/main.cpp` — `qRegisterMetaType<ApiResponse>()`；接 `loadStarted`（Task 8）。
- `src/app/CMakeLists.txt` — 加 LoadingOverlay（Task 8）。

**不动：** `src/data/repo/IDatasetRepository.hpp`（同步，留 LocalSampleRepository）、Nav/Auth/Project 路径、`src/net/AuthService.*`。

---

## Task 1: net — 抽出 `buildResponse`（纯重构，行为不变）

把现 `ApiClient::Impl::await` 里「读状态 + 读体 + 解析」的部分抽成自由函数，供同步 `await` 与异步 `ApiCall` 复用（DRY）。

**Files:**
- Create: `src/net/ApiResponseParse.hpp`, `src/net/ApiResponseParse.cpp`
- Modify: `src/net/ApiClient.cpp`, `src/net/CMakeLists.txt`

- [ ] **Step 1: 写 `ApiResponseParse.hpp`**

```cpp
#pragma once
#include "ApiClient.hpp"  // for geopro::net::ApiResponse

class QNetworkReply;

namespace geopro::net {

// 从一个【已完成】的 reply 读取状态码/响应体/错误并解析为 ApiResponse。
// 不等待、不删除 reply（调用方负责生命周期）。供同步 await 与异步 ApiCall 共用。
ApiResponse buildResponse(QNetworkReply* reply);

}  // namespace geopro::net
```

- [ ] **Step 2: 写 `ApiResponseParse.cpp`**（把现 ApiClient.cpp 的 parseBody + await 后半段搬来）

```cpp
#include "ApiResponseParse.hpp"

#include <QByteArray>
#include <QJsonDocument>
#include <QJsonParseError>
#include <QJsonValue>
#include <QNetworkReply>
#include <QNetworkRequest>

namespace geopro::net {

namespace {
constexpr int kHttpStatusUnset = 0;

void parseBody(const QByteArray& body, ApiResponse& resp) {
    if (body.isEmpty()) {
        resp.rawError = QStringLiteral("empty response body");
        return;
    }
    QJsonParseError perr{};
    const QJsonDocument doc = QJsonDocument::fromJson(body, &perr);
    if (perr.error != QJsonParseError::NoError || !doc.isObject()) {
        resp.rawError = QStringLiteral("JSON parse error: %1; body: %2")
                            .arg(perr.errorString(), QString::fromUtf8(body));
        return;
    }
    const QJsonObject obj = doc.object();
    resp.code = obj.value(QStringLiteral("code")).toInt();
    resp.msg = obj.value(QStringLiteral("msg")).toString();
    const QJsonValue dataVal = obj.value(QStringLiteral("data"));
    if (dataVal.isObject()) {
        resp.data = dataVal.toObject();
    } else {
        resp.data = QJsonObject{{QStringLiteral("value"), dataVal}};
    }
}
}  // namespace

ApiResponse buildResponse(QNetworkReply* reply) {
    ApiResponse resp;
    const QVariant statusVar = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute);
    resp.httpStatus = statusVar.isValid() ? statusVar.toInt() : kHttpStatusUnset;
    const QByteArray body = reply->readAll();
    if (reply->error() != QNetworkReply::NoError) {
        resp.rawError = reply->errorString();
    }
    if (!body.isEmpty()) {
        parseBody(body, resp);
    }
    return resp;
}

}  // namespace geopro::net
```

- [ ] **Step 3: 改 `ApiClient.cpp` 用 buildResponse**

删除 ApiClient.cpp 顶部 `parseBody` 匿名函数（已搬到 ApiResponseParse.cpp）与 `kHttpStatusUnset`、相关未用 include（`QJsonDocument/QJsonParseError/QJsonValue`）。在文件顶部 include 改为加 `#include "ApiResponseParse.hpp"`。把 `Impl::await` 改为：

```cpp
    static ApiResponse await(QNetworkReply* reply) {
        QEventLoop loop;
        QObject::connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);
        loop.exec();
        return buildResponse(reply);
    }
```

保留 `kContentTypeJson` / `kTokenHeader` / `buildRequest` 不动。

- [ ] **Step 4: 注册到 CMake**

`src/net/CMakeLists.txt` 的 `add_library(geopro_net STATIC ...)` 列表加一行 `ApiResponseParse.cpp`：

```cmake
add_library(geopro_net STATIC
  crypto/RsaEncryptor.cpp
  ApiClient.cpp
  ApiResponseParse.cpp
  AuthService.cpp)
```

- [ ] **Step 5: 构建 + 跑现有测试（回归安全网）**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-test.ps1`
Expected: 75/75 PASS（`AuthLiveTest.FullLoginFlowReturnsToken` 走 sync 路径会经过 buildResponse，验证重构无回归）。

- [ ] **Step 6: Commit**

```bash
git add src/net/ApiResponseParse.hpp src/net/ApiResponseParse.cpp src/net/ApiClient.cpp src/net/CMakeLists.txt
git commit -m "refactor(net): 抽出 buildResponse，sync/async 共用响应解析（DRY，行为不变）"
```

---

## Task 2: net — `IApiCall` + `ApiCall` + AUTOMOC + getAsync/postJsonAsync

**Files:**
- Create: `src/net/IApiCall.hpp`, `src/net/ApiCall.hpp`, `src/net/ApiCall.cpp`
- Modify: `src/net/ApiClient.hpp`, `src/net/ApiClient.cpp`, `src/net/CMakeLists.txt`

- [ ] **Step 1: 写 `IApiCall.hpp`**

```cpp
#pragma once
#include <QObject>
#include "ApiClient.hpp"  // geopro::net::ApiResponse

namespace geopro::net {

// 单个异步请求的抽象句柄（可测试缝）。ApiBatch 仅依赖此抽象，单测可注入假 call。
class IApiCall : public QObject {
    Q_OBJECT
public:
    using QObject::QObject;
    ~IApiCall() override = default;
    virtual void abort() = 0;   // 置 aborted_、中断、deleteLater；abort 后绝不 emit finished
signals:
    void finished(const geopro::net::ApiResponse& resp);  // 成功/错误均经此（错误写 rawError）
};

}  // namespace geopro::net
```

- [ ] **Step 2: 写 `ApiCall.hpp`**

```cpp
#pragma once
#include <QPointer>
#include "IApiCall.hpp"

class QNetworkReply;

namespace geopro::net {

// 包一个 QNetworkReply 的 IApiCall 实现。reply 完成 → buildResponse → emit finished → 自删。
// 安全不变量（spec §5.0）：abort 后绝不 emit；销毁一律 deleteLater，禁止同步 delete。
class ApiCall : public IApiCall {
    Q_OBJECT
public:
    explicit ApiCall(QNetworkReply* reply, QObject* parent = nullptr);  // 接管 reply
    void abort() override;
private:
    void onFinished();
    QPointer<QNetworkReply> reply_;
    bool aborted_ = false;
};

}  // namespace geopro::net
```

- [ ] **Step 3: 写 `ApiCall.cpp`**

```cpp
#include "ApiCall.hpp"

#include <QNetworkReply>
#include "ApiResponseParse.hpp"

namespace geopro::net {

ApiCall::ApiCall(QNetworkReply* reply, QObject* parent) : IApiCall(parent), reply_(reply) {
    QObject::connect(reply_, &QNetworkReply::finished, this, &ApiCall::onFinished);
}

void ApiCall::onFinished() {
    if (aborted_) return;                       // §5.0 入口守卫：迟到信号闸门
    ApiResponse resp = buildResponse(reply_);
    if (reply_) reply_->deleteLater();
    emit finished(resp);
    deleteLater();
}

void ApiCall::abort() {
    if (aborted_) return;
    aborted_ = true;                            // 先置标志（权威闸门）
    if (reply_) {
        QObject::disconnect(reply_, nullptr, this, nullptr);  // 尽力而为：断开未派发连接
        reply_->abort();                        // 会再触发一次 finished，已被 disconnect+aborted_ 双挡
        reply_->deleteLater();
    }
    deleteLater();                              // 禁止同步 delete
}

}  // namespace geopro::net
```

- [ ] **Step 4: 改 `ApiClient.hpp`** — 加异步方法 + 元类型声明

在 `ApiResponse` 结构体定义之后（`};` 之下、`class ApiClient` 之上）插入：

```cpp
}  // namespace geopro::net  ←★ 不要重复；见下方完整片段
```

具体改法：①在 `class ApiClient` 内 `postJson` 声明后加两行；②文件末尾 `}  // namespace geopro::net` 之后加 `Q_DECLARE_METATYPE`。

`class ApiClient` 内新增：
```cpp
    // 异步 GET / POST(JSON)：立即返回自管理句柄，不阻塞。调用方连 IApiCall::finished。
    net::IApiCall* getAsync(const QString& path);
    net::IApiCall* postJsonAsync(const QString& path, const QJsonObject& body);
```
（注意：此处在 `namespace geopro::net` 内，写 `IApiCall*` 即可，不必加 `net::` 前缀——按现文件风格用 `IApiCall*`。）

前置声明区加 `class IApiCall;`（与现有 `class QNetworkAccessManager;` 并列）。

文件最末（`}  // namespace geopro::net` 之后）加：
```cpp
#include <QMetaType>
Q_DECLARE_METATYPE(geopro::net::ApiResponse)
```

- [ ] **Step 5: 改 `ApiClient.cpp`** — 实现异步方法

顶部加 `#include "ApiCall.hpp"`。在 `postJson` 实现之后加：

```cpp
IApiCall* ApiClient::getAsync(const QString& path) {
    QNetworkRequest req = impl_->buildRequest(path);
    QNetworkReply* reply = impl_->nam.get(req);
    return new ApiCall(reply);
}

IApiCall* ApiClient::postJsonAsync(const QString& path, const QJsonObject& body) {
    QNetworkRequest req = impl_->buildRequest(path);
    const QByteArray payload = QJsonDocument(body).toJson(QJsonDocument::Compact);
    QNetworkReply* reply = impl_->nam.post(req, payload);
    return new ApiCall(reply);
}
```
（`QJsonDocument` 已被 ApiClient.cpp 使用，保留其 include。）

- [ ] **Step 6: 改 `src/net/CMakeLists.txt`** — AUTOMOC ON + 加源

```cmake
add_library(geopro_net STATIC
  crypto/RsaEncryptor.cpp
  ApiClient.cpp
  ApiResponseParse.cpp
  ApiCall.cpp
  AuthService.cpp)
```
并把末行改为：
```cmake
set_target_properties(geopro_net PROPERTIES AUTOMOC ON AUTOUIC OFF AUTORCC OFF)
```
（AUTOMOC ON 仅对含 Q_OBJECT 的新文件生效，现有文件无 Q_OBJECT，无副作用。`IApiCall.hpp`/`ApiCall.hpp` 经 `ApiCall.cpp` 的 `#include` 被 AUTOMOC 扫描到。）

- [ ] **Step 7: 构建（无新测试，验证编译/链接/moc）**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-build.ps1`
Expected: 链接通过（moc 为 IApiCall/ApiCall 生成成功）。
> ApiCall 直接包 QNetworkReply，离线无法稳定单测，由 Task 3（ApiBatch + FakeApiCall）与 Task 6（控制器集成）+ Task 8 手动验证覆盖。

- [ ] **Step 8: Commit**

```bash
git add src/net/IApiCall.hpp src/net/ApiCall.hpp src/net/ApiCall.cpp src/net/ApiClient.hpp src/net/ApiClient.cpp src/net/CMakeLists.txt
git commit -m "feat(net): ApiClient.getAsync/postJsonAsync + IApiCall/ApiCall 异步句柄（abort+aborted_ 闸门，AUTOMOC ON）"
```

---

## Task 3: net — `ApiBatch`（fail-fast 汇聚）+ 离线单测（TDD）

**Files:**
- Create: `src/net/ApiBatch.hpp`, `src/net/ApiBatch.cpp`, `tests/net/FakeApiCall.hpp`, `tests/net/test_api_batch.cpp`
- Modify: `src/net/CMakeLists.txt`, `tests/CMakeLists.txt`

- [ ] **Step 1: 写 `tests/net/FakeApiCall.hpp`**（不声明 Q_OBJECT：发射继承自 IApiCall 的 finished）

```cpp
#pragma once
#include "IApiCall.hpp"

namespace geopro::net::test {

// 测试假 call。不加 Q_OBJECT —— 仅发射继承自 IApiCall 的 finished 信号、override abort。
class FakeApiCall : public IApiCall {
public:
    using IApiCall::IApiCall;
    bool aborted = false;
    void abort() override { aborted = true; }
    void fire(const ApiResponse& r) { emit finished(r); }  // 发射继承的信号（无需自身 moc）
};

}  // namespace geopro::net::test
```

- [ ] **Step 2: 写失败测试 `tests/net/test_api_batch.cpp`**

```cpp
#include <gtest/gtest.h>
#include <QSignalSpy>
#include "ApiBatch.hpp"
#include "net/FakeApiCall.hpp"

using namespace geopro::net;
using geopro::net::test::FakeApiCall;

namespace {
ApiResponse ok(int code = 200) { ApiResponse r; r.code = code; r.httpStatus = 200; return r; }
ApiResponse bad() { ApiResponse r; r.code = 500; r.httpStatus = 200; r.msg = QStringLiteral("boom"); return r; }
// repo 注入的失败谓词：业务码 != 200 或传输错误。
auto isFailure = [](const ApiResponse& r) { return r.code != 200 || !r.rawError.isEmpty(); };
}

TEST(ApiBatch, SucceedsWhenAllOk) {
    auto* a = new FakeApiCall;
    auto* b = new FakeApiCall;
    auto* batch = new ApiBatch({a, b}, isFailure);
    QSignalSpy okSpy(batch, &ApiBatch::succeeded);
    QSignalSpy failSpy(batch, &ApiBatch::failed);
    a->fire(ok());
    EXPECT_EQ(okSpy.count(), 0);   // 还差 b
    b->fire(ok());
    EXPECT_EQ(okSpy.count(), 1);   // 全到齐
    EXPECT_EQ(failSpy.count(), 0);
}

TEST(ApiBatch, FailFastAbortsOthers) {
    auto* a = new FakeApiCall;
    auto* b = new FakeApiCall;   // 慢的（永不 fire）
    auto* batch = new ApiBatch({a, b}, isFailure);
    QSignalSpy failSpy(batch, &ApiBatch::failed);
    QSignalSpy okSpy(batch, &ApiBatch::succeeded);
    a->fire(bad());                // 首个失败
    EXPECT_EQ(failSpy.count(), 1);
    EXPECT_EQ(okSpy.count(), 0);
    EXPECT_TRUE(b->aborted);       // 其余在飞被 abort
}

TEST(ApiBatch, AbortGateSuppressesLateSignals) {
    auto* a = new FakeApiCall;
    auto* b = new FakeApiCall;
    auto* batch = new ApiBatch({a, b}, isFailure);
    QSignalSpy okSpy(batch, &ApiBatch::succeeded);
    QSignalSpy failSpy(batch, &ApiBatch::failed);
    batch->abort();
    EXPECT_TRUE(a->aborted);
    EXPECT_TRUE(b->aborted);
    a->fire(ok());                 // 迟到信号
    b->fire(ok());
    EXPECT_EQ(okSpy.count(), 0);   // aborted_ 闸门：不 emit
    EXPECT_EQ(failSpy.count(), 0);
}
```

- [ ] **Step 3: 注册测试到 CMake**

`tests/CMakeLists.txt`，在 net 段（`target_sources(geopro_tests PRIVATE net/test_auth.cpp)` 之后）加：
```cmake
target_sources(geopro_tests PRIVATE net/test_api_batch.cpp)
```
并确保 net 段链接含 `Qt6::Test`（用于 QSignalSpy）。把第 50 行链接行改为：
```cmake
target_link_libraries(geopro_tests PRIVATE geopro_net OpenSSL::SSL OpenSSL::Crypto Qt6::Core Qt6::Network Qt6::Test)
```
（`find_package(Qt6 COMPONENTS Test REQUIRED)` 在 controller 段已有；若 net 段在其之前编译报错，把该 find_package 上移到文件 net 段之前。）
`tests/net/` 头由 `target_include_directories(geopro_tests PRIVATE ${CMAKE_SOURCE_DIR}/tests)` 提供——若不存在则加：
```cmake
target_include_directories(geopro_tests PRIVATE ${CMAKE_SOURCE_DIR}/tests)
```

- [ ] **Step 4: 跑测试确认失败**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-build.ps1`
Expected: 编译失败（`ApiBatch.hpp` 不存在）。

- [ ] **Step 5: 写 `src/net/ApiBatch.hpp`**

```cpp
#pragma once
#include <functional>
#include <QList>
#include <QPointer>
#include <QObject>
#include "IApiCall.hpp"

namespace geopro::net {

// 并发汇聚 N 个 IApiCall：全成功 → succeeded(按下标对齐)；任一失败 → fail-fast：
// failed(index,resp) + abort 其余在飞 call。安全不变量见 spec §5.0。
class ApiBatch : public QObject {
    Q_OBJECT
public:
    using Predicate = std::function<bool(const ApiResponse&)>;
    ApiBatch(QList<IApiCall*> calls, Predicate isFailure, QObject* parent = nullptr);  // 接管 calls
    void abort();
signals:
    void succeeded(const QList<geopro::net::ApiResponse>& responses);
    void failed(int index, const geopro::net::ApiResponse& resp);
private:
    QList<QPointer<IApiCall>> calls_;
    QList<ApiResponse> responses_;
    Predicate isFailure_;
    int remaining_ = 0;
    bool aborted_ = false;
};

}  // namespace geopro::net
```

- [ ] **Step 6: 写 `src/net/ApiBatch.cpp`**

```cpp
#include "ApiBatch.hpp"

namespace geopro::net {

ApiBatch::ApiBatch(QList<IApiCall*> calls, Predicate isFailure, QObject* parent)
    : QObject(parent), isFailure_(std::move(isFailure)) {
    responses_.resize(calls.size());
    remaining_ = static_cast<int>(calls.size());
    for (int i = 0; i < calls.size(); ++i) {
        IApiCall* c = calls[i];
        calls_.append(c);
        QObject::connect(c, &IApiCall::finished, this, [this, i](const ApiResponse& resp) {
            if (aborted_) return;                       // §5.0 入口守卫
            if (isFailure_(resp)) {
                aborted_ = true;
                for (const auto& other : calls_) {      // fail-fast：abort 其余在飞
                    if (other) other->abort();
                }
                emit failed(i, resp);
                deleteLater();
                return;
            }
            responses_[i] = resp;
            if (--remaining_ == 0) {
                emit succeeded(responses_);
                deleteLater();
            }
        });
    }
}

void ApiBatch::abort() {
    if (aborted_) return;
    aborted_ = true;
    for (const auto& c : calls_) {
        if (c) c->abort();
    }
    deleteLater();
}

}  // namespace geopro::net
```

- [ ] **Step 7: 加 ApiBatch.cpp 到 net 库**

`src/net/CMakeLists.txt` 的源列表加 `ApiBatch.cpp`：
```cmake
add_library(geopro_net STATIC
  crypto/RsaEncryptor.cpp
  ApiClient.cpp
  ApiResponseParse.cpp
  ApiCall.cpp
  ApiBatch.cpp
  AuthService.cpp)
```

- [ ] **Step 8: 跑测试确认通过**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-test.ps1`
Expected: `ApiBatch.SucceedsWhenAllOk` / `FailFastAbortsOthers` / `AbortGateSuppressesLateSignals` PASS；总数 78/78。

- [ ] **Step 9: Commit**

```bash
git add src/net/ApiBatch.hpp src/net/ApiBatch.cpp src/net/CMakeLists.txt tests/net/FakeApiCall.hpp tests/net/test_api_batch.cpp tests/CMakeLists.txt
git commit -m "feat(net): ApiBatch 并发汇聚+fail-fast+abort闸门 + 离线单测"
```

---

## Task 4: data — 结果载体 + 异步接口 + 句柄（抽象基 + Api 实现）+ 句柄单测（TDD）

**Files:**
- Create: `src/data/api/DatasetLoads.hpp`, `src/data/repo/IAsyncDatasetRepository.hpp`, `src/data/api/DatasetLoadHandles.hpp`, `src/data/api/DatasetLoadHandles.cpp`, `tests/data/test_dataset_load_handles.cpp`
- Modify: `src/data/CMakeLists.txt`, `tests/CMakeLists.txt`

- [ ] **Step 1: 写 `src/data/api/DatasetLoads.hpp`**（纯结构体）

```cpp
#pragma once
#include <vector>
#include "model/Field.hpp"
#include "model/ColorScale.hpp"
#include "model/Anomaly.hpp"

namespace geopro::data {

// 原数据加载结果：scatter + 散点色阶(type1)。
struct ChartParts {
    geopro::core::ScatterField scatter;
    geopro::core::ColorScale scatterScale;
};
// 网格数据加载结果：grid(rows) + 网格色阶(type2) + 异常。
struct GridParts {
    geopro::core::Grid grid{1, 1};   // Grid 无默认构造；占位
    geopro::core::ColorScale gridScale;
    std::vector<geopro::core::Anomaly> anomalies;
};

}  // namespace geopro::data
```

- [ ] **Step 2: 写 `src/data/api/DatasetLoadHandles.hpp`**（抽象基 + Api 实现）

```cpp
#pragma once
#include <functional>
#include <QList>
#include <QObject>
#include <QPointer>
#include <QString>
#include "ApiBatch.hpp"
#include "DatasetLoads.hpp"

namespace geopro::data {

// ── 抽象句柄（可测试缝，类比 IApiCall）：仓储返回基类指针，控制器/测试只依赖它 ──
class ChartLoad : public QObject {
    Q_OBJECT
public:
    using QObject::QObject;
    ~ChartLoad() override = default;
    virtual void abort() = 0;
signals:
    void done(const geopro::data::ChartParts& parts);
    void failed(const QString& message);
};

class GridLoad : public QObject {
    Q_OBJECT
public:
    using QObject::QObject;
    ~GridLoad() override = default;
    virtual void abort() = 0;
signals:
    void done(const geopro::data::GridParts& parts);
    void failed(const QString& message);
};

// ── Api 实现：包一个 ApiBatch + 注入的解析函数。batch.succeeded→解析→done；failed→failed ──
class ApiChartLoad : public ChartLoad {
    Q_OBJECT
public:
    using Parser = std::function<ChartParts(const QList<geopro::net::ApiResponse>&)>;
    ApiChartLoad(geopro::net::ApiBatch* batch, Parser parse, QObject* parent = nullptr);
    void abort() override;
private:
    QPointer<geopro::net::ApiBatch> batch_;
    Parser parse_;
    bool aborted_ = false;
};

class ApiGridLoad : public GridLoad {
    Q_OBJECT
public:
    using Parser = std::function<GridParts(const QList<geopro::net::ApiResponse>&)>;
    ApiGridLoad(geopro::net::ApiBatch* batch, Parser parse, QObject* parent = nullptr);
    void abort() override;
private:
    QPointer<geopro::net::ApiBatch> batch_;
    Parser parse_;
    bool aborted_ = false;
};

}  // namespace geopro::data
```

- [ ] **Step 3: 写 `src/data/api/DatasetLoadHandles.cpp`**

```cpp
#include "api/DatasetLoadHandles.hpp"
#include <stdexcept>

namespace geopro::data {

namespace {
QString reasonOf(const geopro::net::ApiResponse& r) {
    return r.msg.isEmpty() ? r.rawError : r.msg;
}
}  // namespace

ApiChartLoad::ApiChartLoad(geopro::net::ApiBatch* batch, Parser parse, QObject* parent)
    : ChartLoad(parent), batch_(batch), parse_(std::move(parse)) {
    QObject::connect(batch, &geopro::net::ApiBatch::succeeded, this,
                     [this](const QList<geopro::net::ApiResponse>& resps) {
        if (aborted_) return;                       // §5.0
        try {
            emit done(parse_(resps));
        } catch (const std::exception& e) {
            emit failed(QString::fromUtf8(e.what()));
        }
        deleteLater();
    });
    QObject::connect(batch, &geopro::net::ApiBatch::failed, this,
                     [this](int, const geopro::net::ApiResponse& r) {
        if (aborted_) return;
        emit failed(reasonOf(r));
        deleteLater();
    });
}

void ApiChartLoad::abort() {
    if (aborted_) return;
    aborted_ = true;
    if (batch_) batch_->abort();
    deleteLater();
}

ApiGridLoad::ApiGridLoad(geopro::net::ApiBatch* batch, Parser parse, QObject* parent)
    : GridLoad(parent), batch_(batch), parse_(std::move(parse)) {
    QObject::connect(batch, &geopro::net::ApiBatch::succeeded, this,
                     [this](const QList<geopro::net::ApiResponse>& resps) {
        if (aborted_) return;
        try {
            emit done(parse_(resps));
        } catch (const std::exception& e) {
            emit failed(QString::fromUtf8(e.what()));
        }
        deleteLater();
    });
    QObject::connect(batch, &geopro::net::ApiBatch::failed, this,
                     [this](int, const geopro::net::ApiResponse& r) {
        if (aborted_) return;
        emit failed(reasonOf(r));
        deleteLater();
    });
}

void ApiGridLoad::abort() {
    if (aborted_) return;
    aborted_ = true;
    if (batch_) batch_->abort();
    deleteLater();
}

}  // namespace geopro::data
```

- [ ] **Step 4: 写 `src/data/repo/IAsyncDatasetRepository.hpp`**

```cpp
#pragma once
#include <string>

namespace geopro::data {

class ChartLoad;
class GridLoad;

// 数据集详情异步仓储抽象。返回自管理句柄（完成/失败后 deleteLater）。
class IAsyncDatasetRepository {
public:
    virtual ~IAsyncDatasetRepository() = default;
    virtual ChartLoad* loadChartAsync(const std::string& dsId) = 0;  // scatter + 散点色阶(type1)
    virtual GridLoad*  loadGridAsync(const std::string& dsId)  = 0;  // grid(rows) + 色阶(type2) + 异常
};

}  // namespace geopro::data
```

- [ ] **Step 5: 写失败测试 `tests/data/test_dataset_load_handles.cpp`**（用真 ApiBatch + FakeApiCall + 桩解析，验证句柄 done/failed/abort 接线）

```cpp
#include <gtest/gtest.h>
#include <QSignalSpy>
#include "api/DatasetLoadHandles.hpp"
#include "net/FakeApiCall.hpp"

using namespace geopro::data;
using geopro::net::ApiBatch;
using geopro::net::ApiResponse;
using geopro::net::test::FakeApiCall;

namespace {
ApiResponse ok() { ApiResponse r; r.code = 200; r.httpStatus = 200; return r; }
ApiResponse bad() { ApiResponse r; r.code = 500; r.httpStatus = 200; r.msg = QStringLiteral("boom"); return r; }
auto isFailure = [](const ApiResponse& r) { return r.code != 200 || !r.rawError.isEmpty(); };
}

TEST(DatasetLoadHandles, ChartLoadEmitsDoneOnSuccess) {
    auto* a = new FakeApiCall;
    auto* b = new FakeApiCall;
    auto* batch = new ApiBatch({a, b}, isFailure);
    bool parsed = false;
    auto* load = new ApiChartLoad(batch, [&](const QList<ApiResponse>& resps) {
        parsed = (resps.size() == 2);
        return ChartParts{};
    });
    QSignalSpy doneSpy(load, &ChartLoad::done);
    a->fire(ok());
    b->fire(ok());
    EXPECT_EQ(doneSpy.count(), 1);
    EXPECT_TRUE(parsed);
}

TEST(DatasetLoadHandles, ChartLoadEmitsFailedOnBatchFailure) {
    auto* a = new FakeApiCall;
    auto* b = new FakeApiCall;
    auto* batch = new ApiBatch({a, b}, isFailure);
    auto* load = new ApiChartLoad(batch, [](const QList<ApiResponse>&) { return ChartParts{}; });
    QSignalSpy failSpy(load, &ChartLoad::failed);
    a->fire(bad());
    EXPECT_EQ(failSpy.count(), 1);
}

TEST(DatasetLoadHandles, GridLoadAbortSuppressesLateDone) {
    auto* a = new FakeApiCall;
    auto* batch = new ApiBatch({a}, isFailure);
    auto* load = new ApiGridLoad(batch, [](const QList<ApiResponse>&) { return GridParts{}; });
    QSignalSpy doneSpy(load, &GridLoad::done);
    load->abort();
    a->fire(ok());                 // 迟到
    EXPECT_EQ(doneSpy.count(), 0); // batch.aborted_ + load.aborted_ 双闸门
}
```

- [ ] **Step 6: 注册 data 源 + 测试 + AUTOMOC**

`src/data/CMakeLists.txt`：源列表加 `api/DatasetLoadHandles.cpp`，末行 AUTOMOC 改 ON：
```cmake
add_library(geopro_data STATIC
  parse/SampleParsers.cpp
  repo/LocalSampleRepository.cpp
  dto/NavDto.cpp
  dto/DatasetChartDto.cpp
  api/ApiProjectRepository.cpp
  api/ApiDatasetRepository.cpp
  api/DatasetLoadHandles.cpp)
...
set_target_properties(geopro_data PROPERTIES AUTOMOC ON AUTOUIC OFF AUTORCC OFF)
```
`tests/CMakeLists.txt` data 段（`target_sources(... data/test_dataset_chart_dto.cpp)` 之后）加：
```cmake
target_sources(geopro_tests PRIVATE data/test_dataset_load_handles.cpp)
```
（data 测试段已 `target_link_libraries(... geopro_data)`；`geopro_data` PUBLIC 链 `geopro_net`，故 ApiBatch 头/符号可见。QSignalSpy 需 `Qt6::Test`——Task 3 已加到链接行。）

- [ ] **Step 7: 跑测试确认通过**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-test.ps1`
Expected: 3 个 `DatasetLoadHandles.*` PASS；总 81/81。

- [ ] **Step 8: Commit**

```bash
git add src/data/api/DatasetLoads.hpp src/data/api/DatasetLoadHandles.hpp src/data/api/DatasetLoadHandles.cpp src/data/repo/IAsyncDatasetRepository.hpp src/data/CMakeLists.txt tests/data/test_dataset_load_handles.cpp tests/CMakeLists.txt
git commit -m "feat(data): 异步仓储接口 + ChartLoad/GridLoad 句柄(抽象基+Api实现) + 离线单测"
```

---

## Task 5: data — `ApiDatasetRepository` 改实现 `IAsyncDatasetRepository`

**Files:**
- Modify: `src/data/api/ApiDatasetRepository.hpp`, `src/data/api/ApiDatasetRepository.cpp`

- [ ] **Step 1: 改 `ApiDatasetRepository.hpp`**

```cpp
#pragma once
#include "repo/IAsyncDatasetRepository.hpp"
namespace geopro::net { class ApiClient; }
namespace geopro::data {

// 真实 API 实现 IAsyncDatasetRepository（ERT 反演）。每次加载返回自管理句柄。
class ApiDatasetRepository : public IAsyncDatasetRepository {
public:
    explicit ApiDatasetRepository(net::ApiClient& api);
    ChartLoad* loadChartAsync(const std::string& dsId) override;
    GridLoad*  loadGridAsync(const std::string& dsId)  override;
private:
    net::ApiClient& api_;
};
}  // namespace geopro::data
```

- [ ] **Step 2: 改 `ApiDatasetRepository.cpp`**（保留 `enc`；`must` 改为复用 `isFailure` 谓词；用 getAsync/postJsonAsync + ApiBatch + ApiChartLoad/ApiGridLoad）

```cpp
#include "api/ApiDatasetRepository.hpp"
#include <stdexcept>
#include <QJsonObject>
#include <QString>
#include <QUrl>
#include "ApiClient.hpp"
#include "ApiBatch.hpp"
#include "api/DatasetLoadHandles.hpp"
#include "dto/DatasetChartDto.hpp"

namespace geopro::data {
namespace {

QString enc(const std::string& s) {
    return QString::fromUtf8(QUrl::toPercentEncoding(QString::fromStdString(s)));
}

// 失败判定（原 must() 口径）：业务码 != 200 或传输错误。
bool isFailure(const geopro::net::ApiResponse& r) {
    return r.code != 200 || !r.rawError.isEmpty();
}

QJsonObject colorBody(const std::string& dsId, int type) {
    return QJsonObject{{"dsObjectId", QString::fromStdString(dsId)}, {"businessCode", ""}, {"type", type}};
}

}  // namespace

ApiDatasetRepository::ApiDatasetRepository(net::ApiClient& api) : api_(api) {}

ChartLoad* ApiDatasetRepository::loadChartAsync(const std::string& dsId) {
    // index 0 = scatter(GET)，index 1 = 散点色阶 type1(POST)
    QList<net::IApiCall*> calls{
        api_.getAsync(QStringLiteral("/business/dd/ert/inversion/getErtRawDataScatterGraph/%1").arg(enc(dsId))),
        api_.postJsonAsync(QStringLiteral("/business/lvl/colorGradation/getDetail"), colorBody(dsId, 1)),
    };
    auto* batch = new net::ApiBatch(calls, &isFailure);
    return new ApiChartLoad(batch, [](const QList<net::ApiResponse>& r) {
        ChartParts p;
        p.scatter = dto::parseScatterGraph(r[0].data);
        p.scatterScale = dto::parseColorBar(r[1].data);
        return p;
    });
}

GridLoad* ApiDatasetRepository::loadGridAsync(const std::string& dsId) {
    // index 0 = rows(GET,慢)，1 = 色阶 type2(POST)，2 = 异常(GET)
    QList<net::IApiCall*> calls{
        api_.getAsync(QStringLiteral("/business/dd/ert/inversion/rows/%1").arg(enc(dsId))),
        api_.postJsonAsync(QStringLiteral("/business/lvl/colorGradation/getDetail"), colorBody(dsId, 2)),
        api_.getAsync(QStringLiteral("/business/exception/queryException/%1").arg(enc(dsId))),
    };
    auto* batch = new net::ApiBatch(calls, &isFailure);
    return new ApiGridLoad(batch, [](const QList<net::ApiResponse>& r) {
        GridParts p;
        p.grid = dto::parseInversionGrid(r[0].data);
        p.gridScale = dto::parseColorBar(r[1].data);
        p.anomalies = dto::parseDatasetAnomalies(r[2].data.value(QStringLiteral("value")).toArray());
        return p;
    });
}

}  // namespace geopro::data
```
> 解析函数名/用法与原同步实现逐一对齐：`parseScatterGraph`/`parseColorBar`/`parseInversionGrid`/`parseDatasetAnomalies`（见原 ApiDatasetRepository.cpp）。`GridParts.grid` 由 `parseInversionGrid` 返回值覆盖（赋值即可，Grid 无默认构造但成员赋值用拷贝赋值合法）。

- [ ] **Step 3: 构建（真实 API 方法离线不可单测，验证编译/链接）**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-build.ps1`
Expected: 链接通过。
> 真实端点行为由 Task 8 手动验证覆盖（与现有 ApiProjectRepository 同：无离线单测）。

- [ ] **Step 4: Commit**

```bash
git add src/data/api/ApiDatasetRepository.hpp src/data/api/ApiDatasetRepository.cpp
git commit -m "feat(data): ApiDatasetRepository 改异步(loadChartAsync/loadGridAsync, ApiBatch+句柄, code==200判定)"
```

---

## Task 6: controller — `DatasetDetailController` 异步化（abort-and-replace + 身份比对）+ 改测试（TDD）

**Files:**
- Modify: `src/controller/DatasetDetailController.hpp`, `src/controller/DatasetDetailController.cpp`, `tests/controller/test_dataset_detail_controller.cpp`

- [ ] **Step 1: 改 `DatasetDetailController.hpp`**

```cpp
#pragma once
#include <string>
#include <QObject>
#include <QPointer>
#include <QString>
#include "model/Field.hpp"
#include "model/ColorScale.hpp"
#include "model/Anomaly.hpp"
namespace geopro::data { class IAsyncDatasetRepository; class ChartLoad; class GridLoad; }
namespace geopro::controller {

class DatasetDetailController : public QObject {
    Q_OBJECT
public:
    enum class LoadPhase { Chart, Grid };
    Q_ENUM(LoadPhase)

    struct ChartData {
        QString dsId, ddCode;
        geopro::core::ScatterField scatter;
        geopro::core::ColorScale scatterScale;
        geopro::core::Grid grid{1, 1};
        geopro::core::ColorScale gridScale;
        std::vector<geopro::core::Anomaly> anomalies;
    };
    struct GridData {
        QString dsId;
        geopro::core::Grid grid{1, 1};
        geopro::core::ColorScale gridScale;
        std::vector<geopro::core::Anomaly> anomalies;
    };

    explicit DatasetDetailController(data::IAsyncDatasetRepository& repo, QObject* parent = nullptr);
public slots:
    void openDataset(const QString& dsId, const QString& ddCode);
    void focusDataset(const QString& dsId);
    void loadGridData(const QString& dsId, const QString& ddCode);
signals:
    void loadStarted(const QString& dsId, LoadPhase phase);
    void chartReady(const ChartData& data);
    void gridReady(const GridData& data);
    void focusRequested(const QString& dsId);
    void loadFailed(const QString& dsId, const QString& message);
private:
    data::IAsyncDatasetRepository& repo_;
    QPointer<data::ChartLoad> chartLoad_;
    QPointer<data::GridLoad> gridLoad_;
};
}  // namespace geopro::controller
```

- [ ] **Step 2: 改 `DatasetDetailController.cpp`**

```cpp
#include "DatasetDetailController.hpp"
#include "repo/IAsyncDatasetRepository.hpp"
#include "api/DatasetLoadHandles.hpp"
namespace geopro::controller {

DatasetDetailController::DatasetDetailController(data::IAsyncDatasetRepository& repo, QObject* parent)
    : QObject(parent), repo_(repo) {}

void DatasetDetailController::openDataset(const QString& dsId, const QString& ddCode) {
    if (ddCode != QLatin1String("dd_inversion_data")) {
        emit loadFailed(dsId, QStringLiteral("暂不支持该数据类型的预览"));
        return;
    }
    if (chartLoad_) chartLoad_->abort();                 // abort-and-replace
    data::ChartLoad* load = repo_.loadChartAsync(dsId.toStdString());
    chartLoad_ = load;
    emit loadStarted(dsId, LoadPhase::Chart);
    QObject::connect(load, &data::ChartLoad::done, this,
                     [this, load, dsId, ddCode](const data::ChartParts& parts) {
        if (load != chartLoad_) return;                  // §5.0 句柄身份比对：丢弃迟到信号
        chartLoad_.clear();
        ChartData d;
        d.dsId = dsId;
        d.ddCode = ddCode;
        d.scatter = parts.scatter;
        d.scatterScale = parts.scatterScale;
        emit chartReady(d);
    });
    QObject::connect(load, &data::ChartLoad::failed, this,
                     [this, load, dsId](const QString& msg) {
        if (load != chartLoad_) return;
        chartLoad_.clear();
        emit loadFailed(dsId, msg);
    });
}

void DatasetDetailController::loadGridData(const QString& dsId, const QString& ddCode) {
    if (ddCode != QLatin1String("dd_inversion_data")) return;
    if (gridLoad_) gridLoad_->abort();
    data::GridLoad* load = repo_.loadGridAsync(dsId.toStdString());
    gridLoad_ = load;
    emit loadStarted(dsId, LoadPhase::Grid);
    QObject::connect(load, &data::GridLoad::done, this,
                     [this, load, dsId](const data::GridParts& parts) {
        if (load != gridLoad_) return;
        gridLoad_.clear();
        GridData d;
        d.dsId = dsId;
        d.grid = parts.grid;
        d.gridScale = parts.gridScale;
        d.anomalies = parts.anomalies;
        emit gridReady(d);
    });
    QObject::connect(load, &data::GridLoad::failed, this,
                     [this, load, dsId](const QString& msg) {
        if (load != gridLoad_) return;
        gridLoad_.clear();
        emit loadFailed(dsId, msg);
    });
}

void DatasetDetailController::focusDataset(const QString& dsId) { emit focusRequested(dsId); }
}  // namespace geopro::controller
```
> 析构：`chartLoad_`/`gridLoad_` 是 `QPointer`，控制器析构时若句柄仍在飞，句柄自身在完成/abort 后 deleteLater；为稳妥可在析构中 abort（可选，Qt 退出会清理）。本期不显式写析构（栈析构逆序 ctrl→repo→api 已保证安全，见 spec §7）。

- [ ] **Step 3: 改测试 `tests/controller/test_dataset_detail_controller.cpp`**（异步 stub + 回灌防护）

```cpp
#include <gtest/gtest.h>
#include <QSignalSpy>
#include "DatasetDetailController.hpp"
#include "repo/IAsyncDatasetRepository.hpp"
#include "api/DatasetLoadHandles.hpp"
using namespace geopro;

namespace {
// 桩句柄：不声明 Q_OBJECT —— 发射继承自 data::ChartLoad/GridLoad 的信号、override abort。
struct StubChartLoad : data::ChartLoad {
    bool aborted = false;
    void abort() override { aborted = true; }
    void fireDone() { emit done(data::ChartParts{}); }
    void fireFailed() { emit failed(QStringLiteral("x")); }
};
struct StubGridLoad : data::GridLoad {
    bool aborted = false;
    void abort() override { aborted = true; }
    void fireDone() { emit done(data::GridParts{}); }
};
struct StubAsyncRepo : data::IAsyncDatasetRepository {
    StubChartLoad* lastChart = nullptr;
    StubGridLoad* lastGrid = nullptr;
    data::ChartLoad* loadChartAsync(const std::string&) override {
        lastChart = new StubChartLoad; return lastChart;
    }
    data::GridLoad* loadGridAsync(const std::string&) override {
        lastGrid = new StubGridLoad; return lastGrid;
    }
};
}

TEST(DatasetDetailController, EmitsChartReadyOnDone) {
    StubAsyncRepo repo;
    controller::DatasetDetailController c(repo);
    QSignalSpy spy(&c, &controller::DatasetDetailController::chartReady);
    c.openDataset("ds1", "dd_inversion_data");
    repo.lastChart->fireDone();
    EXPECT_EQ(spy.count(), 1);
}

TEST(DatasetDetailController, EmitsLoadFailedOnFailed) {
    StubAsyncRepo repo;
    controller::DatasetDetailController c(repo);
    QSignalSpy spy(&c, &controller::DatasetDetailController::loadFailed);
    c.openDataset("ds1", "dd_inversion_data");
    repo.lastChart->fireFailed();
    EXPECT_EQ(spy.count(), 1);
}

TEST(DatasetDetailController, UnsupportedTypeFailsImmediately) {
    StubAsyncRepo repo;
    controller::DatasetDetailController c(repo);
    QSignalSpy spy(&c, &controller::DatasetDetailController::loadFailed);
    c.openDataset("ds1", "dd_other");
    EXPECT_EQ(spy.count(), 1);
    EXPECT_EQ(repo.lastChart, nullptr);   // 未发起加载
}

TEST(DatasetDetailController, AbortsPreviousOnReopen) {
    StubAsyncRepo repo;
    controller::DatasetDetailController c(repo);
    c.openDataset("dsA", "dd_inversion_data");
    StubChartLoad* a = repo.lastChart;
    c.openDataset("dsB", "dd_inversion_data");   // 替换
    EXPECT_TRUE(a->aborted);                      // 旧句柄被 abort
}

TEST(DatasetDetailController, DropsLateSignalFromAbortedLoad) {
    StubAsyncRepo repo;
    controller::DatasetDetailController c(repo);
    QSignalSpy spy(&c, &controller::DatasetDetailController::chartReady);
    c.openDataset("dsA", "dd_inversion_data");
    StubChartLoad* a = repo.lastChart;
    c.openDataset("dsB", "dd_inversion_data");
    StubChartLoad* b = repo.lastChart;
    a->fireDone();                 // 旧句柄迟到 → 身份比对丢弃
    EXPECT_EQ(spy.count(), 0);
    b->fireDone();                 // 当前句柄 → 正常
    EXPECT_EQ(spy.count(), 1);
}
```

- [ ] **Step 4: 跑测试确认通过**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-test.ps1`
Expected: 5 个 `DatasetDetailController.*` PASS（替换原 2 个）；总 84/84。

- [ ] **Step 5: Commit**

```bash
git add src/controller/DatasetDetailController.hpp src/controller/DatasetDetailController.cpp tests/controller/test_dataset_detail_controller.cpp
git commit -m "feat(controller): DatasetDetailController 异步化(abort-and-replace+句柄身份比对+loadStarted, 移除busy_/catch) + 回灌防护测试"
```

---

## Task 7: app — 装配接线 + qRegisterMetaType

**Files:**
- Modify: `src/app/main.cpp`

- [ ] **Step 1: 注册元类型**（在 `main()` 早期、首次发起网络前，如 `QApplication app(...)` 之后）

在 main.cpp 顶部 include 区确保有 `#include "ApiClient.hpp"`（已有，经 ApiDatasetRepository）。在 `QApplication` 构造之后加：

```cpp
    qRegisterMetaType<geopro::net::ApiResponse>();
```

- [ ] **Step 2: 确认装配无需改动**

`geopro::data::ApiDatasetRepository datasetRepo(api);`（main.cpp:847）与 `DatasetDetailController detailCtrl(datasetRepo);`（:848）——`datasetRepo` 现是 `IAsyncDatasetRepository`，控制器形参已改为该类型，**引用绑定无需改动**。第 505–527 行 chartReady/gridReady/loadFailed/focusRequested/gridDataNeeded 接线**全部不变**（信号面未变）。

- [ ] **Step 3: 构建 + 全量测试**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-test.ps1`
Expected: 84/84 PASS。构建出 `geopro_desktop.exe`。

- [ ] **Step 4: 手动验证（核心收益）**

启动 `build/release/src/app/geopro_desktop.exe`，登录 → 打开标准 ds `id=1458990939709440`：
- 双击数据集 → 原数据加载期间 **UI 不冻**（可拖窗口/切其他）。
- 切到「网格数据」页签 → rows 1–4s 加载期间 **UI 不冻**。
- rows 加载中**快速切换到另一数据集 / 关闭页签** → 旧请求被 abort（无旧数据回灌、无崩溃）。
- 并发：原数据 2 请求、网格 3 请求并发发出（网络面板可见）。

- [ ] **Step 5: Commit**

```bash
git add src/app/main.cpp
git commit -m "feat(app): 装配异步详情仓储 + qRegisterMetaType<ApiResponse>"
```

---

## Task 8: UI — `LoadingOverlay` + 加载反馈（可后置/并行）

> 与异步内核无依赖，可在 Task 1–7 全绿后再做。先读 `src/app/panels/DatasetDetailPage.{hpp,cpp}` 确认 `gridView_` 容器与布局，再放遮罩。

**Files:**
- Create: `src/app/panels/LoadingOverlay.hpp`, `src/app/panels/LoadingOverlay.cpp`
- Modify: `src/app/panels/DatasetDetailPage.hpp`, `src/app/panels/DatasetDetailPage.cpp`, `src/app/panels/DatasetDetailPanel.hpp`, `src/app/panels/DatasetDetailPanel.cpp`, `src/app/main.cpp`, `src/app/CMakeLists.txt`

- [ ] **Step 1: 写 `LoadingOverlay.hpp`**

```cpp
#pragma once
#include <QWidget>
class QLabel;
namespace geopro::app {

// 半透明「加载中…」遮罩。贴在目标视图上层，show()/hide() 切换，几何随父 resize 跟随。
class LoadingOverlay : public QWidget {
    Q_OBJECT
public:
    explicit LoadingOverlay(QWidget* parent);
    void showOver();   // 提到父尺寸、置顶、显示
protected:
    bool eventFilter(QObject* obj, QEvent* ev) override;  // 跟随父 resize
private:
    QLabel* label_;
};

}  // namespace geopro::app
```

- [ ] **Step 2: 写 `LoadingOverlay.cpp`**

```cpp
#include "panels/LoadingOverlay.hpp"
#include <QEvent>
#include <QLabel>
#include <QResizeEvent>
#include <QVBoxLayout>

namespace geopro::app {

LoadingOverlay::LoadingOverlay(QWidget* parent) : QWidget(parent), label_(new QLabel(this)) {
    setAttribute(Qt::WA_StyledBackground, true);
    setStyleSheet(QStringLiteral("background: rgba(255,255,255,160);"));
    label_->setText(QStringLiteral("加载中…"));
    label_->setAlignment(Qt::AlignCenter);
    auto* lay = new QVBoxLayout(this);
    lay->addWidget(label_);
    if (parent) parent->installEventFilter(this);
    hide();
}

void LoadingOverlay::showOver() {
    if (parentWidget()) setGeometry(parentWidget()->rect());
    raise();
    show();
}

bool LoadingOverlay::eventFilter(QObject* obj, QEvent* ev) {
    if (obj == parentWidget() && ev->type() == QEvent::Resize && isVisible()) {
        setGeometry(parentWidget()->rect());
    }
    return QWidget::eventFilter(obj, ev);
}

}  // namespace geopro::app
```

- [ ] **Step 3: DatasetDetailPage 暴露加载状态接口**

`DatasetDetailPage.hpp` 加方法声明（`setGridData` 附近）：
```cpp
    void setGridLoading(bool on);   // 网格视图遮罩开关
```
`DatasetDetailPage.cpp`：在构造里于 `gridView_` 之上建一个 `LoadingOverlay* gridOverlay_`（父为 gridView_ 的容器或 gridView_ 本身），实现：
```cpp
void DatasetDetailPage::setGridLoading(bool on) {
    if (on) gridOverlay_->showOver(); else gridOverlay_->hide();
}
```
（成员加 `LoadingOverlay* gridOverlay_;`，头部 `#include "panels/LoadingOverlay.hpp"` 或前置声明 + cpp include。`setGridData` 末尾调 `setGridLoading(false)`。）

- [ ] **Step 4: DatasetDetailPanel 转发加载状态**

`DatasetDetailPanel.hpp` 加：
```cpp
    void setGridLoading(const QString& dsId, bool on);
```
`DatasetDetailPanel.cpp` 实现：`pageFor(dsId)` 找到页 → `page->setGridLoading(on)`。

- [ ] **Step 5: main.cpp 接 loadStarted**

在第 518 行 gridReady 接线附近加：
```cpp
    QObject::connect(&detailCtrl, &geopro::controller::DatasetDetailController::loadStarted, detailPanel,
        [detailPanel](const QString& dsId, geopro::controller::DatasetDetailController::LoadPhase phase) {
            if (phase == geopro::controller::DatasetDetailController::LoadPhase::Grid)
                detailPanel->setGridLoading(dsId, true);
        });
```
（原数据初次加载的 busy 反馈：页面于 chartReady 创建，加载期可设 `window.setCursor(Qt::BusyCursor)`，chartReady/loadFailed 复位——可选，最小化先不做。）

- [ ] **Step 6: 注册 LoadingOverlay 到 app CMake**

`src/app/CMakeLists.txt` 找到 panels 源列表，加 `panels/LoadingOverlay.cpp`（geopro app 目标已 AUTOMOC ON——确认；若否则比照现有 panel 文件加法）。

- [ ] **Step 7: 构建 + 手动验证遮罩**

Run: `powershell.exe -ExecutionPolicy Bypass -File scripts/dev-build.ps1`
启动 app → 切网格页签：rows 加载期间网格区显示「加载中…」遮罩、到达后消失；切走/关页遮罩随页消失。

- [ ] **Step 8: Commit**

```bash
git add src/app/panels/LoadingOverlay.hpp src/app/panels/LoadingOverlay.cpp src/app/panels/DatasetDetailPage.hpp src/app/panels/DatasetDetailPage.cpp src/app/panels/DatasetDetailPanel.hpp src/app/panels/DatasetDetailPanel.cpp src/app/main.cpp src/app/CMakeLists.txt
git commit -m "feat(app): 网格懒加载「加载中」遮罩(LoadingOverlay) 接 loadStarted"
```

---

## Self-Review（spec 覆盖核对）

- **§2 目标 1（不冻 UI）** → Task 2/5/7（getAsync 去 QEventLoop）+ Task 7 手动验证。✓
- **§2 目标 2（abort 过期）** → Task 2 ApiCall.abort / Task 3 ApiBatch.abort / Task 6 abort-and-replace + 身份比对。✓
- **§2 目标 3（并发）** → Task 5 ApiBatch 同时发 2/3 请求。✓
- **§2 目标 4（加载反馈）** → Task 6 loadStarted + Task 8 LoadingOverlay。✓
- **§2 目标 5（可复用原语）** → Task 2/3 IApiCall/ApiCall/ApiBatch。✓
- **§2 目标 6（测试不退化、离线可测）** → Task 1/3/4/6 单测，全程 dev-test。✓
- **§5.0 安全不变量** → 各层 `aborted_`（ApiCall/ApiBatch/ApiChartLoad/ApiGridLoad）+ 控制器身份比对 + 全 deleteLater；回归用例 Task 3 AbortGate / Task 4 GridLoadAbort / Task 6 DropsLateSignal。✓
- **§5.1 buildResponse 复用** → Task 1。✓
- **§7 失败判定 code==200** → Task 5 isFailure。✓
- **§5.2 旧方法去向 / 不碰 LocalSampleRepository** → Task 5 仅改 ApiDatasetRepository，IDatasetRepository 不动。✓
- **§5.2 fail-fast** → Task 3 FailFastAbortsOthers。✓
- **AUTOMOC** → Task 2（net ON）/ Task 4（data ON）。✓
- **qRegisterMetaType** → Task 7。✓

类型/签名一致性核对：`IApiCall::finished(ApiResponse)`、`ApiBatch::succeeded(QList<ApiResponse>)`/`failed(int,ApiResponse)`、`ChartLoad::done(ChartParts)`/`failed(QString)`、`IAsyncDatasetRepository::loadChartAsync→ChartLoad*`、控制器 `loadStarted(QString,LoadPhase)` 全程一致。

---

## Execution Handoff

计划已保存 `docs/superpowers/plans/2026-06-11-apiclient-async-datasetdetail.md`。两种执行方式：

1. **Subagent-Driven（推荐）** — 每个 Task 派新 subagent 实现，任务间审查，迭代快。
2. **Inline Execution** — 本会话内按 executing-plans 批量执行 + 检查点。

选哪个？
</content>