✨ feat: 实现 ControllerClient HTTP 兼容层及 FANUC 运行时

- 新增 Flyshot.ControllerClientCompat 兼容层模块
  - 新增 Flyshot.Runtime.Fanuc 运行时模块
  - 新增 LegacyHttpApiController 暴露 HTTP 兼容 API
  - 补充 RuntimeOrchestrationTests 等测试覆盖
  - 补充 docs/ 兼容性需求与逆向工程文档
  - 更新 Host 注册、配置及解决方案引用

  变更概览：
  - Flyshot.ControllerClientCompat — 旧 ControllerClient 语义的 HTTP 适配
  - Flyshot.Runtime.Fanuc — IControllerRuntime 的 FANUC 真机实现
  - LegacyHttpApiController — HTTP API 兼容旧 SDK
  - docs/ — 兼容性需求与逆向工程分析文档
  - 测试：RuntimeOrchestrationTests、LegacyHttpApiCompatibilityTests

tests/Flyshot.Core.Tests/Flyshot.Core.Tests.csproj

@@ -23,10 +23,12 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\src\Flyshot.ControllerClientCompat\Flyshot.ControllerClientCompat.csproj" />
     <ProjectReference Include="..\..\src\Flyshot.Core.Config\Flyshot.Core.Config.csproj" />
     <ProjectReference Include="..\..\src\Flyshot.Core.Domain\Flyshot.Core.Domain.csproj" />
     <ProjectReference Include="..\..\src\Flyshot.Core.Planning\Flyshot.Core.Planning.csproj" />
     <ProjectReference Include="..\..\src\Flyshot.Core.Triggering\Flyshot.Core.Triggering.csproj" />
+    <ProjectReference Include="..\..\src\Flyshot.Runtime.Fanuc\Flyshot.Runtime.Fanuc.csproj" />
   </ItemGroup>
 
 </Project>

tests/Flyshot.Core.Tests/RuntimeOrchestrationTests.cs

@@ -0,0 +1,195 @@
+using Flyshot.ControllerClientCompat;
+using Flyshot.Core.Config;
+using Flyshot.Core.Domain;
+using Flyshot.Runtime.Fanuc;
+
+namespace Flyshot.Core.Tests;
+
+/// <summary>
+/// 验证最小运行时编排链路会把规划结果交给控制器运行时，而不是停留在兼容层内存状态。
+/// </summary>
+public sealed class RuntimeOrchestrationTests
+{
+    /// <summary>
+    /// 验证 FANUC 最小运行时执行轨迹后会更新状态快照与最终关节位置。
+    /// </summary>
+    [Fact]
+    public void FanucControllerRuntime_ExecuteTrajectory_UpdatesSnapshotAndFinalJointPositions()
+    {
+        var runtime = new FanucControllerRuntime();
+        var robot = TestRobotFactory.CreateRobotProfile();
+        runtime.ResetRobot(robot, "FANUC_LR_Mate_200iD");
+        runtime.SetActiveController(sim: false);
+        runtime.Connect("192.168.10.101");
+        runtime.EnableRobot(bufferSize: 2);
+
+        var result = new TrajectoryResult(
+            programName: "demo",
+            method: PlanningMethod.Icsp,
+            isValid: true,
+            duration: TimeSpan.FromSeconds(1.2),
+            shotEvents: Array.Empty<ShotEvent>(),
+            triggerTimeline: Array.Empty<TrajectoryDoEvent>(),
+            artifacts: Array.Empty<TrajectoryArtifact>(),
+            failureReason: null,
+            usedCache: false,
+            originalWaypointCount: 4,
+            plannedWaypointCount: 4);
+
+        runtime.ExecuteTrajectory(result, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
+
+        var snapshot = runtime.GetSnapshot();
+        Assert.Equal("Connected", snapshot.ConnectionState);
+        Assert.False(snapshot.IsInMotion);
+        Assert.Equal([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], snapshot.JointPositions);
+    }
+
+    /// <summary>
+    /// 验证普通轨迹会先进入 ICSP 规划，并沿用 ICSP 对示教点数量的约束。
+    /// </summary>
+    [Fact]
+    public void ControllerClientTrajectoryOrchestrator_PlanOrdinaryTrajectory_RejectsThreeTeachPoints()
+    {
+        var orchestrator = new ControllerClientTrajectoryOrchestrator();
+        var robot = TestRobotFactory.CreateRobotProfile();
+
+        void Act() =>
+            orchestrator.PlanOrdinaryTrajectory(
+                robot,
+                [
+                    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+                    [0.5, 0.0, 0.0, 0.0, 0.0, 0.0],
+                    [1.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+                ]);
+
+        Assert.Throws<ArgumentException>(Act);
+    }
+
+    /// <summary>
+    /// 验证已上传飞拍轨迹会经过 self-adapt-icsp 并生成拍照触发时间轴。
+    /// </summary>
+    [Fact]
+    public void ControllerClientTrajectoryOrchestrator_PlanUploadedFlyshot_BuildsShotTimeline()
+    {
+        var orchestrator = new ControllerClientTrajectoryOrchestrator();
+        var robot = TestRobotFactory.CreateRobotProfile();
+        var uploaded = TestRobotFactory.CreateUploadedTrajectoryWithSingleShot();
+
+        var bundle = orchestrator.PlanUploadedFlyshot(robot, uploaded);
+
+        Assert.True(bundle.Result.IsValid);
+        Assert.Single(bundle.Result.ShotEvents);
+        Assert.Single(bundle.Result.TriggerTimeline);
+    }
+
+    /// <summary>
+    /// 验证兼容服务执行普通轨迹时会进入规划链路，而不是直接把最后一个路点写入状态。
+    /// </summary>
+    [Fact]
+    public void ControllerClientCompatService_ExecuteTrajectory_RejectsThreeTeachPointsAfterPlanningIsIntroduced()
+    {
+        var service = TestRobotFactory.CreateCompatService();
+        service.SetUpRobot("FANUC_LR_Mate_200iD");
+        service.SetActiveController(sim: false);
+        service.Connect("192.168.10.101");
+        service.EnableRobot(2);
+
+        void Act() =>
+            service.ExecuteTrajectory(
+                [
+                    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+                    [0.5, 0.0, 0.0, 0.0, 0.0, 0.0],
+                    [1.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+                ]);
+
+        Assert.Throws<ArgumentException>(Act);
+    }
+}
+
+/// <summary>
+/// 为运行时编排测试构造稳定的最小领域对象。
+/// </summary>
+internal static class TestRobotFactory
+{
+    /// <summary>
+    /// 构造六轴测试机器人配置，避免运行时测试依赖真实 .robot 文件。
+    /// </summary>
+    /// <returns>可用于规划和运行时状态校验的机器人配置。</returns>
+    public static RobotProfile CreateRobotProfile()
+    {
+        return new RobotProfile(
+            name: "TestRobot",
+            modelPath: "Models/Test.robot",
+            degreesOfFreedom: 6,
+            jointLimits: Enumerable.Range(1, 6)
+                .Select(static index => new JointLimit($"J{index}", 10.0, 20.0, 100.0))
+                .ToArray(),
+            jointCouplings: Array.Empty<JointCoupling>(),
+            servoPeriod: TimeSpan.FromMilliseconds(8),
+            triggerPeriod: TimeSpan.FromMilliseconds(8));
+    }
+
+    /// <summary>
+    /// 构造一条含单个拍照点的上传飞拍轨迹。
+    /// </summary>
+    /// <returns>可用于触发时间轴测试的上传轨迹。</returns>
+    public static ControllerClientCompatUploadedTrajectory CreateUploadedTrajectoryWithSingleShot()
+    {
+        return new ControllerClientCompatUploadedTrajectory(
+            name: "demo-flyshot",
+            waypoints:
+            [
+                [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+                [0.1, 0.0, 0.0, 0.0, 0.0, 0.0],
+                [0.2, 0.0, 0.0, 0.0, 0.0, 0.0],
+                [0.3, 0.0, 0.0, 0.0, 0.0, 0.0]
+            ],
+            shotFlags: [false, true, false, false],
+            offsetValues: [0, 1, 0, 0],
+            addressGroups:
+            [
+                Array.Empty<int>(),
+                [7, 8],
+                Array.Empty<int>(),
+                Array.Empty<int>()
+            ]);
+    }
+
+    /// <summary>
+    /// 构造一份真实依赖注入等价的兼容服务，覆盖运行时和编排器协作。
+    /// </summary>
+    /// <returns>可执行 ControllerClient 兼容语义的服务实例。</returns>
+    public static ControllerClientCompatService CreateCompatService()
+    {
+        var options = new ControllerClientCompatOptions
+        {
+            WorkspaceRoot = GetWorkspaceRoot()
+        };
+
+        return new ControllerClientCompatService(
+            options,
+            new ControllerClientCompatRobotCatalog(options, new RobotModelLoader()),
+            new FanucControllerRuntime(),
+            new ControllerClientTrajectoryOrchestrator());
+    }
+
+    /// <summary>
+    /// 定位父工作区根目录，供兼容服务加载真实机器人模型。
+    /// </summary>
+    /// <returns>父工作区根目录。</returns>
+    private static string GetWorkspaceRoot()
+    {
+        var current = new DirectoryInfo(AppContext.BaseDirectory);
+        while (current is not null)
+        {
+            if (File.Exists(Path.Combine(current.FullName, "FlyshotReplacement.sln")))
+            {
+                return Path.GetFullPath(Path.Combine(current.FullName, ".."));
+            }
+
+            current = current.Parent;
+        }
+
+        throw new DirectoryNotFoundException("Unable to locate the flyshot workspace root.");
+    }
+}

tests/Flyshot.Server.IntegrationTests/ControllerClientCompatRegistrationTests.cs

@@ -0,0 +1,21 @@
+using Flyshot.ControllerClientCompat;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Flyshot.Server.IntegrationTests;
+
+/// <summary>
+/// 锁定宿主当前应注册 HTTP-only 的 ControllerClient 兼容服务，而不是旧 TCP 网关入口。
+/// </summary>
+public sealed class ControllerClientCompatRegistrationTests(FlyshotServerFactory factory) : IClassFixture<FlyshotServerFactory>
+{
+    /// <summary>
+    /// 验证宿主能从 DI 中解析新的兼容服务。
+    /// </summary>
+    [Fact]
+    public void Host_Registers_ControllerClientCompat_Service()
+    {
+        var service = factory.Services.GetService<IControllerClientCompatService>();
+
+        Assert.NotNull(service);
+    }
+}

tests/Flyshot.Server.IntegrationTests/Flyshot.Server.IntegrationTests.csproj

@@ -24,6 +24,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\src\Flyshot.ControllerClientCompat\Flyshot.ControllerClientCompat.csproj" />
     <ProjectReference Include="..\..\src\Flyshot.Server.Host\Flyshot.Server.Host.csproj" />
   </ItemGroup>
 

tests/Flyshot.Server.IntegrationTests/HostMvcConfigurationTests.cs

@@ -0,0 +1,84 @@
+using System.Net;
+using System.Text.Json;
+using Microsoft.AspNetCore.Mvc.Testing;
+using Microsoft.Extensions.Configuration;
+
+namespace Flyshot.Server.IntegrationTests;
+
+/// <summary>
+/// 锁定标准 MVC 宿主需要提供的 Swagger 与 CORS 行为，避免后续回退成只够跑通的最小配置。
+/// </summary>
+public sealed class HostMvcConfigurationTests(FlyshotServerFactory factory) : IClassFixture<FlyshotServerFactory>
+{
+    /// <summary>
+    /// 验证宿主会公开标准 Swagger JSON，并且文档标题和旧 HTTP 兼容路径都能从配置和控制器路由中导出。
+    /// </summary>
+    [Fact]
+    public async Task SwaggerDocument_ExposesConfiguredMetadataAndLegacyRoutes()
+    {
+        using var configuredFactory = CreateConfiguredFactory(factory);
+        using var client = configuredFactory.CreateClient();
+
+        using var response = await client.GetAsync("/swagger/v1/swagger.json");
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        await using var responseStream = await response.Content.ReadAsStreamAsync();
+        using var document = await JsonDocument.ParseAsync(responseStream);
+        var root = document.RootElement;
+        var paths = root.GetProperty("paths");
+
+        Assert.Equal("3.0.1", root.GetProperty("openapi").GetString());
+        Assert.Equal("Flyshot Replacement HTTP API", root.GetProperty("info").GetProperty("title").GetString());
+        // OpenAPI 文档会把部分带尾斜杠的路由规范化为无尾斜杠形式，这里同时接受两种键。
+        Assert.True(paths.TryGetProperty("/robot_info/", out _) || paths.TryGetProperty("/robot_info", out _));
+        Assert.True(paths.TryGetProperty("/healthz", out _) || paths.TryGetProperty("/healthz/", out _));
+    }
+
+    /// <summary>
+    /// 验证宿主会按配置对旧 HTTP API 路由返回标准 CORS 预检响应。
+    /// </summary>
+    [Fact]
+    public async Task CorsPreflight_ReturnsConfiguredAllowOriginHeaders()
+    {
+        using var configuredFactory = CreateConfiguredFactory(factory);
+        using var client = configuredFactory.CreateClient();
+
+        using var request = new HttpRequestMessage(HttpMethod.Options, "/robot_info/");
+        request.Headers.Add("Origin", "http://localhost:3000");
+        request.Headers.Add("Access-Control-Request-Method", "GET");
+        request.Headers.Add("Access-Control-Request-Headers", "content-type");
+
+        using var response = await client.SendAsync(request);
+        Assert.Equal(HttpStatusCode.NoContent, response.StatusCode);
+        Assert.True(response.Headers.TryGetValues("Access-Control-Allow-Origin", out var allowedOrigins));
+        Assert.Contains("http://localhost:3000", allowedOrigins);
+        Assert.True(response.Headers.TryGetValues("Access-Control-Allow-Methods", out var allowedMethods));
+        Assert.Contains("GET", string.Join(",", allowedMethods));
+    }
+
+    /// <summary>
+    /// 为测试宿主注入标准 Swagger 与 CORS 配置，避免依赖开发机本地环境。
+    /// </summary>
+    private static WebApplicationFactory<Program> CreateConfiguredFactory(FlyshotServerFactory factory)
+    {
+        return factory.WithWebHostBuilder(builder =>
+        {
+            builder.ConfigureAppConfiguration((_, configurationBuilder) =>
+            {
+                configurationBuilder.AddInMemoryCollection(new Dictionary<string, string?>
+                {
+                    ["Swagger:Enabled"] = "true",
+                    ["Swagger:DocumentName"] = "v1",
+                    ["Swagger:Title"] = "Flyshot Replacement HTTP API",
+                    ["Swagger:Version"] = "v1",
+                    ["Cors:PolicyName"] = "LegacyHttpApi",
+                    ["Cors:AllowedOrigins:0"] = "http://localhost:3000",
+                    ["Cors:AllowedMethods:0"] = "GET",
+                    ["Cors:AllowedMethods:1"] = "POST",
+                    ["Cors:AllowedMethods:2"] = "OPTIONS",
+                    ["Cors:AllowedHeaders:0"] = "content-type"
+                });
+            });
+        });
+    }
+}

tests/Flyshot.Server.IntegrationTests/LegacyHttpApiCompatibilityTests.cs

@@ -0,0 +1,235 @@
+using System.Net;
+using System.Net.Http.Json;
+using System.Text.Json;
+
+namespace Flyshot.Server.IntegrationTests;
+
+/// <summary>
+/// 锁定 flyshot-uaes-interface 现有 FastAPI 层的 HTTP 路径、参数绑定和返回 JSON 外形。
+/// </summary>
+public sealed class LegacyHttpApiCompatibilityTests(FlyshotServerFactory factory) : IClassFixture<FlyshotServerFactory>
+{
+    /// <summary>
+    /// 验证根路径会返回旧 HTTP 服务使用的 Hello World JSON，而不是跳转到健康检查页。
+    /// </summary>
+    [Fact]
+    public async Task Root_ReturnsLegacyHelloWorldPayload()
+    {
+        using var client = factory.CreateClient();
+
+        using var response = await client.GetAsync("/");
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+
+        using var json = await ReadJsonAsync(response);
+        Assert.Equal("Hello World", json.RootElement.GetProperty("message").GetString());
+    }
+
+    /// <summary>
+    /// 验证初始化链路和机器人信息接口会保持旧 FastAPI 服务的路径与返回字段风格。
+    /// </summary>
+    [Fact]
+    public async Task InitEndpoints_ExposeLegacyRobotInfoAndSpeedRatioShape()
+    {
+        using var client = factory.CreateClient();
+
+        using (var connectServerResponse = await client.PostAsync("/connect_server/?server_ip=127.0.0.1&port=50001", content: null))
+        {
+            Assert.Equal(HttpStatusCode.OK, connectServerResponse.StatusCode);
+            using var connectServerJson = await ReadJsonAsync(connectServerResponse);
+            Assert.Equal("connected", connectServerJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var setupResponse = await client.PostAsync("/setup_robot/?robot_name=FANUC_LR_Mate_200iD", content: null))
+        {
+            Assert.Equal(HttpStatusCode.OK, setupResponse.StatusCode);
+            using var setupJson = await ReadJsonAsync(setupResponse);
+            Assert.Equal("robot setup", setupJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var isSetupResponse = await client.GetAsync("/is_setup/"))
+        {
+            Assert.Equal(HttpStatusCode.OK, isSetupResponse.StatusCode);
+            using var isSetupJson = await ReadJsonAsync(isSetupResponse);
+            Assert.True(isSetupJson.RootElement.GetProperty("is_setup").GetBoolean());
+        }
+
+        using (var activeControllerResponse = await client.PostAsync("/set_active_controller/?sim=false", content: null))
+        {
+            Assert.Equal(HttpStatusCode.OK, activeControllerResponse.StatusCode);
+            using var activeControllerJson = await ReadJsonAsync(activeControllerResponse);
+            Assert.Equal("active controller set", activeControllerJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var connectRobotResponse = await client.PostAsync("/connect_robot/?ip=192.168.10.101", content: null))
+        {
+            Assert.Equal(HttpStatusCode.OK, connectRobotResponse.StatusCode);
+            using var connectRobotJson = await ReadJsonAsync(connectRobotResponse);
+            Assert.Equal("robot connected", connectRobotJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var enableRobotResponse = await client.GetAsync("/enable_robot/"))
+        {
+            Assert.Equal(HttpStatusCode.OK, enableRobotResponse.StatusCode);
+            using var enableRobotJson = await ReadJsonAsync(enableRobotResponse);
+            Assert.True(enableRobotJson.RootElement.GetProperty("enable_robot").GetBoolean());
+        }
+
+        using (var robotInfoResponse = await client.GetAsync("/robot_info/"))
+        {
+            Assert.Equal(HttpStatusCode.OK, robotInfoResponse.StatusCode);
+            using var robotInfoJson = await ReadJsonAsync(robotInfoResponse);
+            var robotInfoRoot = robotInfoJson.RootElement;
+
+            Assert.Equal("FANUC_LR_Mate_200iD", robotInfoRoot.GetProperty("name").GetString());
+            Assert.Equal("flyshot-replacement-controller-client-compat/0.1.0", robotInfoRoot.GetProperty("server_version").GetString());
+            Assert.Equal(6, robotInfoRoot.GetProperty("dof").GetInt32());
+            Assert.Equal(1.0, robotInfoRoot.GetProperty("speed_ratio").GetDouble(), precision: 6);
+        }
+
+        using (var setSpeedRatioResponse = await client.PostAsJsonAsync("/set_speedRatio/", new { speed = 0.8 }))
+        {
+            Assert.Equal(HttpStatusCode.OK, setSpeedRatioResponse.StatusCode);
+            using var setSpeedRatioJson = await ReadJsonAsync(setSpeedRatioResponse);
+            Assert.Equal("set_speedRatio executed", setSpeedRatioJson.RootElement.GetProperty("message").GetString());
+            Assert.Equal(0, setSpeedRatioJson.RootElement.GetProperty("returnCode").GetInt32());
+        }
+
+        using var updatedRobotInfoResponse = await client.GetAsync("/robot_info/");
+        Assert.Equal(HttpStatusCode.OK, updatedRobotInfoResponse.StatusCode);
+        using var updatedRobotInfoJson = await ReadJsonAsync(updatedRobotInfoResponse);
+        Assert.Equal(0.8, updatedRobotInfoJson.RootElement.GetProperty("speed_ratio").GetDouble(), precision: 6);
+    }
+
+    /// <summary>
+    /// 验证 TCP、关节位置和位姿相关 HTTP 接口会保持旧服务的请求体与响应体结构。
+    /// </summary>
+    [Fact]
+    public async Task MotionStateEndpoints_RoundTripLegacyPayloadShapes()
+    {
+        using var client = factory.CreateClient();
+        await InitializeRobotAsync(client);
+
+        using (var setTcpResponse = await client.PostAsJsonAsync("/set_tcp/", new { x = 1.0, y = 2.0, z = 3.0 }))
+        {
+            Assert.Equal(HttpStatusCode.OK, setTcpResponse.StatusCode);
+            using var setTcpJson = await ReadJsonAsync(setTcpResponse);
+            Assert.Equal("TCP set", setTcpJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var getTcpResponse = await client.GetAsync("/get_tcp/"))
+        {
+            Assert.Equal(HttpStatusCode.OK, getTcpResponse.StatusCode);
+            using var getTcpJson = await ReadJsonAsync(getTcpResponse);
+            var tcpValues = getTcpJson.RootElement.GetProperty("tcp").EnumerateArray().Select(static value => value.GetDouble()).ToArray();
+            Assert.Equal([1.0, 2.0, 3.0], tcpValues);
+        }
+
+        using (var moveJointResponse = await client.PostAsJsonAsync("/move_joint/", new { joints = new[] { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 } }))
+        {
+            Assert.Equal(HttpStatusCode.OK, moveJointResponse.StatusCode);
+            using var moveJointJson = await ReadJsonAsync(moveJointResponse);
+            Assert.Equal("robot moved", moveJointJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var getJointPositionResponse = await client.GetAsync("/get_joint_position/"))
+        {
+            Assert.Equal(HttpStatusCode.OK, getJointPositionResponse.StatusCode);
+            using var getJointPositionJson = await ReadJsonAsync(getJointPositionResponse);
+            var root = getJointPositionJson.RootElement;
+            Assert.True(root.GetProperty("success").GetBoolean());
+            var jointValues = root.GetProperty("points").EnumerateArray().Select(static value => value.GetDouble()).ToArray();
+            Assert.Equal([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], jointValues);
+        }
+
+        using var getPoseResponse = await client.GetAsync("/get_pose");
+        Assert.Equal(HttpStatusCode.OK, getPoseResponse.StatusCode);
+        using var getPoseJson = await ReadJsonAsync(getPoseResponse);
+        Assert.Equal(7, getPoseJson.RootElement.GetProperty("pose").GetArrayLength());
+    }
+
+    /// <summary>
+    /// 验证飞拍 HTTP 接口可以按旧 API 层的路径和字段完成上传、列出、执行与删除。
+    /// </summary>
+    [Fact]
+    public async Task FlyshotEndpoints_RoundTripLegacyUploadExecuteAndDeleteFlow()
+    {
+        using var client = factory.CreateClient();
+        await InitializeRobotAsync(client);
+
+        var uploadPayload = new
+        {
+            addrs = new[]
+            {
+                new[] { 7, 8 },
+                new[] { 7, 8 }
+            },
+            name = "demo-http-flyshot",
+            offset_values = new[] { 0.0, 1.0 },
+            shot_flags = new[] { false, true },
+            waypoints = new[]
+            {
+                new[] { 0.1, 0.2, 0.3, 0.4, 0.5, 0.6 },
+                new[] { 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 }
+            }
+        };
+
+        using (var uploadResponse = await client.PostAsJsonAsync("/upload_flyshot/", uploadPayload))
+        {
+            Assert.Equal(HttpStatusCode.OK, uploadResponse.StatusCode);
+            using var uploadJson = await ReadJsonAsync(uploadResponse);
+            Assert.Equal("FlyShot uploaded", uploadJson.RootElement.GetProperty("status").GetString());
+        }
+
+        using (var listResponse = await client.GetAsync("/list_flyShotTraj/"))
+        {
+            Assert.Equal(HttpStatusCode.OK, listResponse.StatusCode);
+            using var listJson = await ReadJsonAsync(listResponse);
+            var names = listJson.RootElement.GetProperty("flyshot_trajs").EnumerateArray().Select(static value => value.GetString()).ToArray();
+            Assert.Contains("demo-http-flyshot", names);
+        }
+
+        using (var executeResponse = await client.PostAsJsonAsync("/execute_flyshot/", new { name = "demo-http-flyshot" }))
+        {
+            Assert.Equal(HttpStatusCode.OK, executeResponse.StatusCode);
+            using var executeJson = await ReadJsonAsync(executeResponse);
+            var executeRoot = executeJson.RootElement;
+            Assert.Equal("FlyShot executed", executeRoot.GetProperty("status").GetString());
+            Assert.True(executeRoot.GetProperty("success").GetBoolean());
+        }
+
+        using (var deleteResponse = await client.PostAsJsonAsync("/delete_flyshot/", new { name = "demo-http-flyshot" }))
+        {
+            Assert.Equal(HttpStatusCode.OK, deleteResponse.StatusCode);
+            using var deleteJson = await ReadJsonAsync(deleteResponse);
+            Assert.Equal("FlyShot deleted", deleteJson.RootElement.GetProperty("status").GetString());
+        }
+    }
+
+    /// <summary>
+    /// 复用旧 API 层常见的初始化顺序，把当前宿主推进到可执行动作的最小状态。
+    /// </summary>
+    private static async Task InitializeRobotAsync(HttpClient client)
+    {
+        using var initResponse = await client.PostAsJsonAsync("/init_mpc_robt", new
+        {
+            server_ip = "127.0.0.1",
+            port = 50001,
+            robot_name = "FANUC_LR_Mate_200iD",
+            robot_ip = "192.168.10.101"
+        });
+
+        Assert.Equal(HttpStatusCode.OK, initResponse.StatusCode);
+        using var initJson = await ReadJsonAsync(initResponse);
+        Assert.Equal("init_Success", initJson.RootElement.GetProperty("message").GetString());
+        Assert.Equal(0, initJson.RootElement.GetProperty("returnCode").GetInt32());
+    }
+
+    /// <summary>
+    /// 统一把 HTTP 响应体解析成 JsonDocument，便于对旧接口的字段形状做精确断言。
+    /// </summary>
+    private static async Task<JsonDocument> ReadJsonAsync(HttpResponseMessage response)
+    {
+        await using var responseStream = await response.Content.ReadAsStreamAsync();
+        return await JsonDocument.ParseAsync(responseStream);
+    }
+}