feat: initial commit - massive-cloud point cloud processing system

server/_core/context.ts

@@ -0,0 +1,28 @@
+import type { CreateExpressContextOptions } from "@trpc/server/adapters/express";
+import type { User } from "../../drizzle/schema";
+import { sdk } from "./sdk";
+
+export type TrpcContext = {
+  req: CreateExpressContextOptions["req"];
+  res: CreateExpressContextOptions["res"];
+  user: User | null;
+};
+
+export async function createContext(
+  opts: CreateExpressContextOptions
+): Promise<TrpcContext> {
+  let user: User | null = null;
+
+  try {
+    user = await sdk.authenticateRequest(opts.req);
+  } catch (error) {
+    // Authentication is optional for public procedures.
+    user = null;
+  }
+
+  return {
+    req: opts.req,
+    res: opts.res,
+    user,
+  };
+}

server/_core/cookies.ts

@@ -0,0 +1,48 @@
+import type { CookieOptions, Request } from "express";
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function isIpAddress(host: string) {
+  // Basic IPv4 check and IPv6 presence detection.
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return true;
+  return host.includes(":");
+}
+
+function isSecureRequest(req: Request) {
+  if (req.protocol === "https") return true;
+
+  const forwardedProto = req.headers["x-forwarded-proto"];
+  if (!forwardedProto) return false;
+
+  const protoList = Array.isArray(forwardedProto)
+    ? forwardedProto
+    : forwardedProto.split(",");
+
+  return protoList.some(proto => proto.trim().toLowerCase() === "https");
+}
+
+export function getSessionCookieOptions(
+  req: Request
+): Pick<CookieOptions, "domain" | "httpOnly" | "path" | "sameSite" | "secure"> {
+  // const hostname = req.hostname;
+  // const shouldSetDomain =
+  //   hostname &&
+  //   !LOCAL_HOSTS.has(hostname) &&
+  //   !isIpAddress(hostname) &&
+  //   hostname !== "127.0.0.1" &&
+  //   hostname !== "::1";
+
+  // const domain =
+  //   shouldSetDomain && !hostname.startsWith(".")
+  //     ? `.${hostname}`
+  //     : shouldSetDomain
+  //       ? hostname
+  //       : undefined;
+
+  return {
+    httpOnly: true,
+    path: "/",
+    sameSite: "none",
+    secure: isSecureRequest(req),
+  };
+}

server/_core/dataApi.ts

@@ -0,0 +1,64 @@
+/**
+ * Quick example (matches curl usage):
+ *   await callDataApi("Youtube/search", {
+ *     query: { gl: "US", hl: "en", q: "manus" },
+ *   })
+ */
+import { ENV } from "./env";
+
+export type DataApiCallOptions = {
+  query?: Record<string, unknown>;
+  body?: Record<string, unknown>;
+  pathParams?: Record<string, unknown>;
+  formData?: Record<string, unknown>;
+};
+
+export async function callDataApi(
+  apiId: string,
+  options: DataApiCallOptions = {}
+): Promise<unknown> {
+  if (!ENV.forgeApiUrl) {
+    throw new Error("BUILT_IN_FORGE_API_URL is not configured");
+  }
+  if (!ENV.forgeApiKey) {
+    throw new Error("BUILT_IN_FORGE_API_KEY is not configured");
+  }
+
+  // Build the full URL by appending the service path to the base URL
+  const baseUrl = ENV.forgeApiUrl.endsWith("/") ? ENV.forgeApiUrl : `${ENV.forgeApiUrl}/`;
+  const fullUrl = new URL("webdevtoken.v1.WebDevService/CallApi", baseUrl).toString();
+
+  const response = await fetch(fullUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+      authorization: `Bearer ${ENV.forgeApiKey}`,
+    },
+    body: JSON.stringify({
+      apiId,
+      query: options.query,
+      body: options.body,
+      path_params: options.pathParams,
+      multipart_form_data: options.formData,
+    }),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Data API request failed (${response.status} ${response.statusText})${detail ? `: ${detail}` : ""}`
+    );
+  }
+
+  const payload = await response.json().catch(() => ({}));
+  if (payload && typeof payload === "object" && "jsonData" in payload) {
+    try {
+      return JSON.parse((payload as Record<string, string>).jsonData ?? "{}");
+    } catch {
+      return (payload as Record<string, unknown>).jsonData;
+    }
+  }
+  return payload;
+}

server/_core/env.ts

@@ -0,0 +1,14 @@
+export const ENV = {
+  appId: process.env.VITE_APP_ID ?? "",
+  cookieSecret: process.env.JWT_SECRET ?? "",
+  databaseUrl: process.env.DATABASE_URL ?? "",
+  oAuthServerUrl: process.env.OAUTH_SERVER_URL ?? "",
+  authMode: process.env.AUTH_MODE ?? "oauth",
+  localDevOpenId: process.env.LOCAL_DEV_OPEN_ID ?? "local-dev-user",
+  localDevName: process.env.LOCAL_DEV_NAME ?? "Local Dev User",
+  localDevEmail: process.env.LOCAL_DEV_EMAIL ?? "local-dev@example.com",
+  ownerOpenId: process.env.OWNER_OPEN_ID ?? "",
+  isProduction: process.env.NODE_ENV === "production",
+  forgeApiUrl: process.env.BUILT_IN_FORGE_API_URL ?? "",
+  forgeApiKey: process.env.BUILT_IN_FORGE_API_KEY ?? "",
+};

server/_core/imageGeneration.ts

@@ -0,0 +1,92 @@
+/**
+ * Image generation helper using internal ImageService
+ *
+ * Example usage:
+ *   const { url: imageUrl } = await generateImage({
+ *     prompt: "A serene landscape with mountains"
+ *   });
+ *
+ * For editing:
+ *   const { url: imageUrl } = await generateImage({
+ *     prompt: "Add a rainbow to this landscape",
+ *     originalImages: [{
+ *       url: "https://example.com/original.jpg",
+ *       mimeType: "image/jpeg"
+ *     }]
+ *   });
+ */
+import { storagePut } from "server/storage";
+import { ENV } from "./env";
+
+export type GenerateImageOptions = {
+  prompt: string;
+  originalImages?: Array<{
+    url?: string;
+    b64Json?: string;
+    mimeType?: string;
+  }>;
+};
+
+export type GenerateImageResponse = {
+  url?: string;
+};
+
+export async function generateImage(
+  options: GenerateImageOptions
+): Promise<GenerateImageResponse> {
+  if (!ENV.forgeApiUrl) {
+    throw new Error("BUILT_IN_FORGE_API_URL is not configured");
+  }
+  if (!ENV.forgeApiKey) {
+    throw new Error("BUILT_IN_FORGE_API_KEY is not configured");
+  }
+
+  // Build the full URL by appending the service path to the base URL
+  const baseUrl = ENV.forgeApiUrl.endsWith("/")
+    ? ENV.forgeApiUrl
+    : `${ENV.forgeApiUrl}/`;
+  const fullUrl = new URL(
+    "images.v1.ImageService/GenerateImage",
+    baseUrl
+  ).toString();
+
+  const response = await fetch(fullUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+      authorization: `Bearer ${ENV.forgeApiKey}`,
+    },
+    body: JSON.stringify({
+      prompt: options.prompt,
+      original_images: options.originalImages || [],
+    }),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Image generation request failed (${response.status} ${response.statusText})${detail ? `: ${detail}` : ""}`
+    );
+  }
+
+  const result = (await response.json()) as {
+    image: {
+      b64Json: string;
+      mimeType: string;
+    };
+  };
+  const base64Data = result.image.b64Json;
+  const buffer = Buffer.from(base64Data, "base64");
+
+  // Save to S3
+  const { url } = await storagePut(
+    `generated/${Date.now()}.png`,
+    buffer,
+    result.image.mimeType
+  );
+  return {
+    url,
+  };
+}

server/_core/index.ts

@@ -0,0 +1,163 @@
+import "dotenv/config";
+import express from "express";
+import { createServer } from "http";
+import net from "net";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import mysql from "mysql2/promise";
+import { createExpressMiddleware } from "@trpc/server/adapters/express";
+import { registerOAuthRoutes } from "./oauth";
+import { appRouter } from "../routers";
+import { createContext } from "./context";
+import { serveStatic, setupVite } from "./vite";
+import { fileRouter } from "../fileRoutes";
+
+const SERVER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Run SQL migrations using a raw mysql2 connection.
+ * Drizzle's execute() requires tagged template sql``; using mysql2 directly
+ * is safer for running arbitrary migration statements.
+ */
+async function runMigrations() {
+  if (!process.env.DATABASE_URL) return;
+
+  // Wait for MySQL to be ready (up to 40 s)
+  let conn: mysql.Connection | null = null;
+  for (let i = 1; i <= 20; i++) {
+    try {
+      conn = await mysql.createConnection(process.env.DATABASE_URL);
+      console.log("[Migration] Database ready.");
+      break;
+    } catch {
+      console.log(`[Migration] Waiting for database... (${i}/20)`);
+      await sleep(2000);
+    }
+  }
+  if (!conn) {
+    console.warn("[Migration] Database not available after 40 s, skipping migrations.");
+    return;
+  }
+
+  try {
+    const migrationsDir = path.resolve(SERVER_ROOT, "../../drizzle");
+    if (!fs.existsSync(migrationsDir)) return;
+
+    const sqlFiles = fs.readdirSync(migrationsDir)
+      .filter(f => f.endsWith(".sql"))
+      .sort();
+
+    // Tracking table
+    await conn.execute(`
+      CREATE TABLE IF NOT EXISTS \`_migrations\` (
+        \`name\` VARCHAR(255) PRIMARY KEY,
+        \`appliedAt\` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    for (const file of sqlFiles) {
+      const [rows] = await conn.execute(
+        `SELECT name FROM \`_migrations\` WHERE name = ?`, [file]
+      ) as [mysql.RowDataPacket[], mysql.FieldPacket[]];
+
+      if (rows.length > 0) continue; // already applied
+
+      const sqlText = fs.readFileSync(path.join(migrationsDir, file), "utf8");
+      // Split on ";". Do NOT drop statements that start with "--": each CREATE block
+      // begins with comment lines, and filtering those skipped all tables (bug).
+      const statements = sqlText
+        .split(";")
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+
+      for (const stmt of statements) {
+        try {
+          await conn.execute(stmt);
+        } catch (e: any) {
+          if (!e.message?.includes("already exists")) {
+            console.error(`[Migration] Error in ${file}:`, e.message);
+          }
+        }
+      }
+
+      await conn.execute(
+        `INSERT IGNORE INTO \`_migrations\` (name) VALUES (?)`, [file]
+      );
+      console.log(`[Migration] Applied: ${file}`);
+    }
+  } finally {
+    await conn.end();
+  }
+}
+
+function isPortAvailable(port: number): Promise<boolean> {
+  return new Promise(resolve => {
+    const server = net.createServer();
+    server.listen(port, () => {
+      server.close(() => resolve(true));
+    });
+    server.on("error", () => resolve(false));
+  });
+}
+
+async function findAvailablePort(startPort: number = 3000): Promise<number> {
+  for (let port = startPort; port < startPort + 20; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`No available port found starting from ${startPort}`);
+}
+
+async function startServer() {
+  try {
+    await runMigrations();
+  } catch (e) {
+    console.error("[Migration] Unexpected error, server will still start:", e);
+  }
+  const app = express();
+  const server = createServer(app);
+  // Configure body parser with larger size limit for file uploads
+  app.use(express.json({ limit: "50mb" }));
+  app.use(express.urlencoded({ limit: "50mb", extended: true }));
+  // OAuth callback under /api/oauth/callback
+  registerOAuthRoutes(app);
+  // 禁止代理（NPS 等）缓存 API 响应
+  app.use('/api', (_req, res, next) => {
+    res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+    res.setHeader('Pragma', 'no-cache');
+    next();
+  });
+  // File API for local file browsing
+  app.use('/api/files', fileRouter);
+  // tRPC API
+  app.use(
+    "/api/trpc",
+    createExpressMiddleware({
+      router: appRouter,
+      createContext,
+    })
+  );
+  // development mode uses Vite, production mode uses static files
+  if (process.env.NODE_ENV === "development") {
+    await setupVite(app, server);
+  } else {
+    serveStatic(app);
+  }
+
+  const preferredPort = parseInt(process.env.PORT || "3000");
+  const port = await findAvailablePort(preferredPort);
+
+  if (port !== preferredPort) {
+    console.log(`Port ${preferredPort} is busy, using port ${port} instead`);
+  }
+
+  server.listen(port, () => {
+    console.log(`Server running on http://localhost:${port}/`);
+  });
+}
+
+startServer().catch(console.error);

server/_core/llm.ts

@@ -0,0 +1,332 @@
+import { ENV } from "./env";
+
+export type Role = "system" | "user" | "assistant" | "tool" | "function";
+
+export type TextContent = {
+  type: "text";
+  text: string;
+};
+
+export type ImageContent = {
+  type: "image_url";
+  image_url: {
+    url: string;
+    detail?: "auto" | "low" | "high";
+  };
+};
+
+export type FileContent = {
+  type: "file_url";
+  file_url: {
+    url: string;
+    mime_type?: "audio/mpeg" | "audio/wav" | "application/pdf" | "audio/mp4" | "video/mp4" ;
+  };
+};
+
+export type MessageContent = string | TextContent | ImageContent | FileContent;
+
+export type Message = {
+  role: Role;
+  content: MessageContent | MessageContent[];
+  name?: string;
+  tool_call_id?: string;
+};
+
+export type Tool = {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+};
+
+export type ToolChoicePrimitive = "none" | "auto" | "required";
+export type ToolChoiceByName = { name: string };
+export type ToolChoiceExplicit = {
+  type: "function";
+  function: {
+    name: string;
+  };
+};
+
+export type ToolChoice =
+  | ToolChoicePrimitive
+  | ToolChoiceByName
+  | ToolChoiceExplicit;
+
+export type InvokeParams = {
+  messages: Message[];
+  tools?: Tool[];
+  toolChoice?: ToolChoice;
+  tool_choice?: ToolChoice;
+  maxTokens?: number;
+  max_tokens?: number;
+  outputSchema?: OutputSchema;
+  output_schema?: OutputSchema;
+  responseFormat?: ResponseFormat;
+  response_format?: ResponseFormat;
+};
+
+export type ToolCall = {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+};
+
+export type InvokeResult = {
+  id: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: {
+      role: Role;
+      content: string | Array<TextContent | ImageContent | FileContent>;
+      tool_calls?: ToolCall[];
+    };
+    finish_reason: string | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+};
+
+export type JsonSchema = {
+  name: string;
+  schema: Record<string, unknown>;
+  strict?: boolean;
+};
+
+export type OutputSchema = JsonSchema;
+
+export type ResponseFormat =
+  | { type: "text" }
+  | { type: "json_object" }
+  | { type: "json_schema"; json_schema: JsonSchema };
+
+const ensureArray = (
+  value: MessageContent | MessageContent[]
+): MessageContent[] => (Array.isArray(value) ? value : [value]);
+
+const normalizeContentPart = (
+  part: MessageContent
+): TextContent | ImageContent | FileContent => {
+  if (typeof part === "string") {
+    return { type: "text", text: part };
+  }
+
+  if (part.type === "text") {
+    return part;
+  }
+
+  if (part.type === "image_url") {
+    return part;
+  }
+
+  if (part.type === "file_url") {
+    return part;
+  }
+
+  throw new Error("Unsupported message content part");
+};
+
+const normalizeMessage = (message: Message) => {
+  const { role, name, tool_call_id } = message;
+
+  if (role === "tool" || role === "function") {
+    const content = ensureArray(message.content)
+      .map(part => (typeof part === "string" ? part : JSON.stringify(part)))
+      .join("\n");
+
+    return {
+      role,
+      name,
+      tool_call_id,
+      content,
+    };
+  }
+
+  const contentParts = ensureArray(message.content).map(normalizeContentPart);
+
+  // If there's only text content, collapse to a single string for compatibility
+  if (contentParts.length === 1 && contentParts[0].type === "text") {
+    return {
+      role,
+      name,
+      content: contentParts[0].text,
+    };
+  }
+
+  return {
+    role,
+    name,
+    content: contentParts,
+  };
+};
+
+const normalizeToolChoice = (
+  toolChoice: ToolChoice | undefined,
+  tools: Tool[] | undefined
+): "none" | "auto" | ToolChoiceExplicit | undefined => {
+  if (!toolChoice) return undefined;
+
+  if (toolChoice === "none" || toolChoice === "auto") {
+    return toolChoice;
+  }
+
+  if (toolChoice === "required") {
+    if (!tools || tools.length === 0) {
+      throw new Error(
+        "tool_choice 'required' was provided but no tools were configured"
+      );
+    }
+
+    if (tools.length > 1) {
+      throw new Error(
+        "tool_choice 'required' needs a single tool or specify the tool name explicitly"
+      );
+    }
+
+    return {
+      type: "function",
+      function: { name: tools[0].function.name },
+    };
+  }
+
+  if ("name" in toolChoice) {
+    return {
+      type: "function",
+      function: { name: toolChoice.name },
+    };
+  }
+
+  return toolChoice;
+};
+
+const resolveApiUrl = () =>
+  ENV.forgeApiUrl && ENV.forgeApiUrl.trim().length > 0
+    ? `${ENV.forgeApiUrl.replace(/\/$/, "")}/v1/chat/completions`
+    : "https://forge.manus.im/v1/chat/completions";
+
+const assertApiKey = () => {
+  if (!ENV.forgeApiKey) {
+    throw new Error("OPENAI_API_KEY is not configured");
+  }
+};
+
+const normalizeResponseFormat = ({
+  responseFormat,
+  response_format,
+  outputSchema,
+  output_schema,
+}: {
+  responseFormat?: ResponseFormat;
+  response_format?: ResponseFormat;
+  outputSchema?: OutputSchema;
+  output_schema?: OutputSchema;
+}):
+  | { type: "json_schema"; json_schema: JsonSchema }
+  | { type: "text" }
+  | { type: "json_object" }
+  | undefined => {
+  const explicitFormat = responseFormat || response_format;
+  if (explicitFormat) {
+    if (
+      explicitFormat.type === "json_schema" &&
+      !explicitFormat.json_schema?.schema
+    ) {
+      throw new Error(
+        "responseFormat json_schema requires a defined schema object"
+      );
+    }
+    return explicitFormat;
+  }
+
+  const schema = outputSchema || output_schema;
+  if (!schema) return undefined;
+
+  if (!schema.name || !schema.schema) {
+    throw new Error("outputSchema requires both name and schema");
+  }
+
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: schema.name,
+      schema: schema.schema,
+      ...(typeof schema.strict === "boolean" ? { strict: schema.strict } : {}),
+    },
+  };
+};
+
+export async function invokeLLM(params: InvokeParams): Promise<InvokeResult> {
+  assertApiKey();
+
+  const {
+    messages,
+    tools,
+    toolChoice,
+    tool_choice,
+    outputSchema,
+    output_schema,
+    responseFormat,
+    response_format,
+  } = params;
+
+  const payload: Record<string, unknown> = {
+    model: "gemini-2.5-flash",
+    messages: messages.map(normalizeMessage),
+  };
+
+  if (tools && tools.length > 0) {
+    payload.tools = tools;
+  }
+
+  const normalizedToolChoice = normalizeToolChoice(
+    toolChoice || tool_choice,
+    tools
+  );
+  if (normalizedToolChoice) {
+    payload.tool_choice = normalizedToolChoice;
+  }
+
+  payload.max_tokens = 32768
+  payload.thinking = {
+    "budget_tokens": 128
+  }
+
+  const normalizedResponseFormat = normalizeResponseFormat({
+    responseFormat,
+    response_format,
+    outputSchema,
+    output_schema,
+  });
+
+  if (normalizedResponseFormat) {
+    payload.response_format = normalizedResponseFormat;
+  }
+
+  const response = await fetch(resolveApiUrl(), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${ENV.forgeApiKey}`,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `LLM invoke failed: ${response.status} ${response.statusText} – ${errorText}`
+    );
+  }
+
+  return (await response.json()) as InvokeResult;
+}

server/_core/map.ts

@@ -0,0 +1,319 @@
+/**
+ * Google Maps API Integration for Manus WebDev Templates
+ * 
+ * Main function: makeRequest<T>(endpoint, params) - Makes authenticated requests to Google Maps APIs
+ * All credentials are automatically injected. Array parameters use | as separator.
+ * 
+ * See API examples below the type definitions for usage patterns.
+ */
+
+import { ENV } from "./env";
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+type MapsConfig = {
+  baseUrl: string;
+  apiKey: string;
+};
+
+function getMapsConfig(): MapsConfig {
+  const baseUrl = ENV.forgeApiUrl;
+  const apiKey = ENV.forgeApiKey;
+
+  if (!baseUrl || !apiKey) {
+    throw new Error(
+      "Google Maps proxy credentials missing: set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY"
+    );
+  }
+
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ""),
+    apiKey,
+  };
+}
+
+// ============================================================================
+// Core Request Handler
+// ============================================================================
+
+interface RequestOptions {
+  method?: "GET" | "POST";
+  body?: Record<string, unknown>;
+}
+
+/**
+ * Make authenticated requests to Google Maps APIs
+ * 
+ * @param endpoint - The API endpoint (e.g., "/maps/api/geocode/json")
+ * @param params - Query parameters for the request
+ * @param options - Additional request options
+ * @returns The API response
+ */
+export async function makeRequest<T = unknown>(
+  endpoint: string,
+  params: Record<string, unknown> = {},
+  options: RequestOptions = {}
+): Promise<T> {
+  const { baseUrl, apiKey } = getMapsConfig();
+
+  // Construct full URL: baseUrl + /v1/maps/proxy + endpoint
+  const url = new URL(`${baseUrl}/v1/maps/proxy${endpoint}`);
+
+  // Add API key as query parameter (standard Google Maps API authentication)
+  url.searchParams.append("key", apiKey);
+
+  // Add other query parameters
+  Object.entries(params).forEach(([key, value]) => {
+    if (value !== undefined && value !== null) {
+      url.searchParams.append(key, String(value));
+    }
+  });
+
+  const response = await fetch(url.toString(), {
+    method: options.method || "GET",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `Google Maps API request failed (${response.status} ${response.statusText}): ${errorText}`
+    );
+  }
+
+  return (await response.json()) as T;
+}
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+export type TravelMode = "driving" | "walking" | "bicycling" | "transit";
+export type MapType = "roadmap" | "satellite" | "terrain" | "hybrid";
+export type SpeedUnit = "KPH" | "MPH";
+
+export type LatLng = {
+  lat: number;
+  lng: number;
+};
+
+export type DirectionsResult = {
+  routes: Array<{
+    legs: Array<{
+      distance: { text: string; value: number };
+      duration: { text: string; value: number };
+      start_address: string;
+      end_address: string;
+      start_location: LatLng;
+      end_location: LatLng;
+      steps: Array<{
+        distance: { text: string; value: number };
+        duration: { text: string; value: number };
+        html_instructions: string;
+        travel_mode: string;
+        start_location: LatLng;
+        end_location: LatLng;
+      }>;
+    }>;
+    overview_polyline: { points: string };
+    summary: string;
+    warnings: string[];
+    waypoint_order: number[];
+  }>;
+  status: string;
+};
+
+export type DistanceMatrixResult = {
+  rows: Array<{
+    elements: Array<{
+      distance: { text: string; value: number };
+      duration: { text: string; value: number };
+      status: string;
+    }>;
+  }>;
+  origin_addresses: string[];
+  destination_addresses: string[];
+  status: string;
+};
+
+export type GeocodingResult = {
+  results: Array<{
+    address_components: Array<{
+      long_name: string;
+      short_name: string;
+      types: string[];
+    }>;
+    formatted_address: string;
+    geometry: {
+      location: LatLng;
+      location_type: string;
+      viewport: {
+        northeast: LatLng;
+        southwest: LatLng;
+      };
+    };
+    place_id: string;
+    types: string[];
+  }>;
+  status: string;
+};
+
+export type PlacesSearchResult = {
+  results: Array<{
+    place_id: string;
+    name: string;
+    formatted_address: string;
+    geometry: {
+      location: LatLng;
+    };
+    rating?: number;
+    user_ratings_total?: number;
+    business_status?: string;
+    types: string[];
+  }>;
+  status: string;
+};
+
+export type PlaceDetailsResult = {
+  result: {
+    place_id: string;
+    name: string;
+    formatted_address: string;
+    formatted_phone_number?: string;
+    international_phone_number?: string;
+    website?: string;
+    rating?: number;
+    user_ratings_total?: number;
+    reviews?: Array<{
+      author_name: string;
+      rating: number;
+      text: string;
+      time: number;
+    }>;
+    opening_hours?: {
+      open_now: boolean;
+      weekday_text: string[];
+    };
+    geometry: {
+      location: LatLng;
+    };
+  };
+  status: string;
+};
+
+export type ElevationResult = {
+  results: Array<{
+    elevation: number;
+    location: LatLng;
+    resolution: number;
+  }>;
+  status: string;
+};
+
+export type TimeZoneResult = {
+  dstOffset: number;
+  rawOffset: number;
+  status: string;
+  timeZoneId: string;
+  timeZoneName: string;
+};
+
+export type RoadsResult = {
+  snappedPoints: Array<{
+    location: LatLng;
+    originalIndex?: number;
+    placeId: string;
+  }>;
+};
+
+// ============================================================================
+// Google Maps API Reference
+// ============================================================================
+
+/**
+ * GEOCODING - Convert between addresses and coordinates
+ * Endpoint: /maps/api/geocode/json
+ * Input: { address: string } OR { latlng: string }  // latlng: "37.42,-122.08"
+ * Output: GeocodingResult  // results[0].geometry.location, results[0].formatted_address
+ */
+
+/**
+ * DIRECTIONS - Get navigation routes between locations
+ * Endpoint: /maps/api/directions/json
+ * Input: { origin: string, destination: string, mode?: TravelMode, waypoints?: string, alternatives?: boolean }
+ * Output: DirectionsResult  // routes[0].legs[0].distance, duration, steps
+ */
+
+/**
+ * DISTANCE MATRIX - Calculate travel times/distances for multiple origin-destination pairs
+ * Endpoint: /maps/api/distancematrix/json
+ * Input: { origins: string, destinations: string, mode?: TravelMode, units?: "metric"|"imperial" }  // origins: "NYC|Boston"
+ * Output: DistanceMatrixResult  // rows[0].elements[1] = first origin to second destination
+ */
+
+/**
+ * PLACE SEARCH - Find businesses/POIs by text query
+ * Endpoint: /maps/api/place/textsearch/json
+ * Input: { query: string, location?: string, radius?: number, type?: string }  // location: "40.7,-74.0"
+ * Output: PlacesSearchResult  // results[].name, rating, geometry.location, place_id
+ */
+
+/**
+ * NEARBY SEARCH - Find places near a specific location
+ * Endpoint: /maps/api/place/nearbysearch/json
+ * Input: { location: string, radius: number, type?: string, keyword?: string }  // location: "40.7,-74.0"
+ * Output: PlacesSearchResult
+ */
+
+/**
+ * PLACE DETAILS - Get comprehensive information about a specific place
+ * Endpoint: /maps/api/place/details/json
+ * Input: { place_id: string, fields?: string }  // fields: "name,rating,opening_hours,website"
+ * Output: PlaceDetailsResult  // result.name, rating, opening_hours, etc.
+ */
+
+/**
+ * ELEVATION - Get altitude data for geographic points
+ * Endpoint: /maps/api/elevation/json
+ * Input: { locations?: string, path?: string, samples?: number }  // locations: "39.73,-104.98|36.45,-116.86"
+ * Output: ElevationResult  // results[].elevation (meters)
+ */
+
+/**
+ * TIME ZONE - Get timezone information for a location
+ * Endpoint: /maps/api/timezone/json
+ * Input: { location: string, timestamp: number }  // timestamp: Math.floor(Date.now()/1000)
+ * Output: TimeZoneResult  // timeZoneId, timeZoneName
+ */
+
+/**
+ * ROADS - Snap GPS traces to roads, find nearest roads, get speed limits
+ * - /v1/snapToRoads: Input: { path: string, interpolate?: boolean }  // path: "lat,lng|lat,lng"
+ * - /v1/nearestRoads: Input: { points: string }  // points: "lat,lng|lat,lng"
+ * - /v1/speedLimits: Input: { path: string, units?: SpeedUnit }
+ * Output: RoadsResult
+ */
+
+/**
+ * PLACE AUTOCOMPLETE - Real-time place suggestions as user types
+ * Endpoint: /maps/api/place/autocomplete/json
+ * Input: { input: string, location?: string, radius?: number }
+ * Output: { predictions: Array<{ description: string, place_id: string }> }
+ */
+
+/**
+ * STATIC MAPS - Generate map images as URLs (for emails, reports, <img> tags)
+ * Endpoint: /maps/api/staticmap
+ * Input: URL params - center: string, zoom: number, size: string, markers?: string, maptype?: MapType
+ * Output: Image URL (not JSON) - use directly in <img src={url} />
+ * Note: Construct URL manually with getMapsConfig() for auth
+ */
+
+
+
+

server/_core/notification.ts

@@ -0,0 +1,114 @@
+import { TRPCError } from "@trpc/server";
+import { ENV } from "./env";
+
+export type NotificationPayload = {
+  title: string;
+  content: string;
+};
+
+const TITLE_MAX_LENGTH = 1200;
+const CONTENT_MAX_LENGTH = 20000;
+
+const trimValue = (value: string): string => value.trim();
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const buildEndpointUrl = (baseUrl: string): string => {
+  const normalizedBase = baseUrl.endsWith("/")
+    ? baseUrl
+    : `${baseUrl}/`;
+  return new URL(
+    "webdevtoken.v1.WebDevService/SendNotification",
+    normalizedBase
+  ).toString();
+};
+
+const validatePayload = (input: NotificationPayload): NotificationPayload => {
+  if (!isNonEmptyString(input.title)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Notification title is required.",
+    });
+  }
+  if (!isNonEmptyString(input.content)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Notification content is required.",
+    });
+  }
+
+  const title = trimValue(input.title);
+  const content = trimValue(input.content);
+
+  if (title.length > TITLE_MAX_LENGTH) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: `Notification title must be at most ${TITLE_MAX_LENGTH} characters.`,
+    });
+  }
+
+  if (content.length > CONTENT_MAX_LENGTH) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: `Notification content must be at most ${CONTENT_MAX_LENGTH} characters.`,
+    });
+  }
+
+  return { title, content };
+};
+
+/**
+ * Dispatches a project-owner notification through the Manus Notification Service.
+ * Returns `true` if the request was accepted, `false` when the upstream service
+ * cannot be reached (callers can fall back to email/slack). Validation errors
+ * bubble up as TRPC errors so callers can fix the payload.
+ */
+export async function notifyOwner(
+  payload: NotificationPayload
+): Promise<boolean> {
+  const { title, content } = validatePayload(payload);
+
+  if (!ENV.forgeApiUrl) {
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Notification service URL is not configured.",
+    });
+  }
+
+  if (!ENV.forgeApiKey) {
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Notification service API key is not configured.",
+    });
+  }
+
+  const endpoint = buildEndpointUrl(ENV.forgeApiUrl);
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${ENV.forgeApiKey}`,
+        "content-type": "application/json",
+        "connect-protocol-version": "1",
+      },
+      body: JSON.stringify({ title, content }),
+    });
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.warn(
+        `[Notification] Failed to notify owner (${response.status} ${response.statusText})${
+          detail ? `: ${detail}` : ""
+        }`
+      );
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    console.warn("[Notification] Error calling notification service:", error);
+    return false;
+  }
+}

server/_core/oauth.ts

@@ -0,0 +1,53 @@
+import { COOKIE_NAME, ONE_YEAR_MS } from "@shared/const";
+import type { Express, Request, Response } from "express";
+import * as db from "../db";
+import { getSessionCookieOptions } from "./cookies";
+import { sdk } from "./sdk";
+
+function getQueryParam(req: Request, key: string): string | undefined {
+  const value = req.query[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function registerOAuthRoutes(app: Express) {
+  app.get("/api/oauth/callback", async (req: Request, res: Response) => {
+    const code = getQueryParam(req, "code");
+    const state = getQueryParam(req, "state");
+
+    if (!code || !state) {
+      res.status(400).json({ error: "code and state are required" });
+      return;
+    }
+
+    try {
+      const tokenResponse = await sdk.exchangeCodeForToken(code, state);
+      const userInfo = await sdk.getUserInfo(tokenResponse.accessToken);
+
+      if (!userInfo.openId) {
+        res.status(400).json({ error: "openId missing from user info" });
+        return;
+      }
+
+      await db.upsertUser({
+        openId: userInfo.openId,
+        name: userInfo.name || null,
+        email: userInfo.email ?? null,
+        loginMethod: userInfo.loginMethod ?? userInfo.platform ?? null,
+        lastSignedIn: new Date(),
+      });
+
+      const sessionToken = await sdk.createSessionToken(userInfo.openId, {
+        name: userInfo.name || "",
+        expiresInMs: ONE_YEAR_MS,
+      });
+
+      const cookieOptions = getSessionCookieOptions(req);
+      res.cookie(COOKIE_NAME, sessionToken, { ...cookieOptions, maxAge: ONE_YEAR_MS });
+
+      res.redirect(302, "/");
+    } catch (error) {
+      console.error("[OAuth] Callback failed", error);
+      res.status(500).json({ error: "OAuth callback failed" });
+    }
+  });
+}

server/_core/sdk.ts

@@ -0,0 +1,346 @@
+import { AXIOS_TIMEOUT_MS, COOKIE_NAME, ONE_YEAR_MS } from "@shared/const";
+import { ForbiddenError } from "@shared/_core/errors";
+import axios, { type AxiosInstance } from "axios";
+import { parse as parseCookieHeader } from "cookie";
+import type { Request } from "express";
+import { SignJWT, jwtVerify } from "jose";
+import type { User } from "../../drizzle/schema";
+import * as db from "../db";
+import { ENV } from "./env";
+import type {
+  ExchangeTokenRequest,
+  ExchangeTokenResponse,
+  GetUserInfoResponse,
+  GetUserInfoWithJwtRequest,
+  GetUserInfoWithJwtResponse,
+} from "./types/manusTypes";
+// Utility function
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0;
+
+export type SessionPayload = {
+  openId: string;
+  appId: string;
+  name: string;
+};
+
+const EXCHANGE_TOKEN_PATH = `/webdev.v1.WebDevAuthPublicService/ExchangeToken`;
+const GET_USER_INFO_PATH = `/webdev.v1.WebDevAuthPublicService/GetUserInfo`;
+const GET_USER_INFO_WITH_JWT_PATH = `/webdev.v1.WebDevAuthPublicService/GetUserInfoWithJwt`;
+
+class OAuthService {
+  constructor(private client: ReturnType<typeof axios.create>) {
+    const isLocalAuth = ENV.authMode === "local";
+    console.log("[OAuth] Initialized with baseURL:", ENV.oAuthServerUrl);
+    if (!ENV.oAuthServerUrl && !isLocalAuth) {
+      console.error(
+        "[OAuth] ERROR: OAUTH_SERVER_URL is not configured! Set OAUTH_SERVER_URL environment variable."
+      );
+    } else if (!ENV.oAuthServerUrl && isLocalAuth) {
+      console.log("[OAuth] AUTH_MODE=local, OAuth server is not required.");
+    }
+  }
+
+  private decodeState(state: string): string {
+    const redirectUri = atob(state);
+    return redirectUri;
+  }
+
+  async getTokenByCode(
+    code: string,
+    state: string
+  ): Promise<ExchangeTokenResponse> {
+    const payload: ExchangeTokenRequest = {
+      clientId: ENV.appId,
+      grantType: "authorization_code",
+      code,
+      redirectUri: this.decodeState(state),
+    };
+
+    const { data } = await this.client.post<ExchangeTokenResponse>(
+      EXCHANGE_TOKEN_PATH,
+      payload
+    );
+
+    return data;
+  }
+
+  async getUserInfoByToken(
+    token: ExchangeTokenResponse
+  ): Promise<GetUserInfoResponse> {
+    const { data } = await this.client.post<GetUserInfoResponse>(
+      GET_USER_INFO_PATH,
+      {
+        accessToken: token.accessToken,
+      }
+    );
+
+    return data;
+  }
+}
+
+const createOAuthHttpClient = (): AxiosInstance =>
+  axios.create({
+    baseURL: ENV.oAuthServerUrl,
+    timeout: AXIOS_TIMEOUT_MS,
+  });
+
+class SDKServer {
+  private readonly client: AxiosInstance;
+  private readonly oauthService: OAuthService;
+
+  constructor(client: AxiosInstance = createOAuthHttpClient()) {
+    this.client = client;
+    this.oauthService = new OAuthService(this.client);
+  }
+
+  private isLocalAuthMode() {
+    return ENV.authMode === "local";
+  }
+
+  private deriveLoginMethod(
+    platforms: unknown,
+    fallback: string | null | undefined
+  ): string | null {
+    if (fallback && fallback.length > 0) return fallback;
+    if (!Array.isArray(platforms) || platforms.length === 0) return null;
+    const set = new Set<string>(
+      platforms.filter((p): p is string => typeof p === "string")
+    );
+    if (set.has("REGISTERED_PLATFORM_EMAIL")) return "email";
+    if (set.has("REGISTERED_PLATFORM_GOOGLE")) return "google";
+    if (set.has("REGISTERED_PLATFORM_APPLE")) return "apple";
+    if (
+      set.has("REGISTERED_PLATFORM_MICROSOFT") ||
+      set.has("REGISTERED_PLATFORM_AZURE")
+    )
+      return "microsoft";
+    if (set.has("REGISTERED_PLATFORM_GITHUB")) return "github";
+    const first = Array.from(set)[0];
+    return first ? first.toLowerCase() : null;
+  }
+
+  /**
+   * Exchange OAuth authorization code for access token
+   * @example
+   * const tokenResponse = await sdk.exchangeCodeForToken(code, state);
+   */
+  async exchangeCodeForToken(
+    code: string,
+    state: string
+  ): Promise<ExchangeTokenResponse> {
+    return this.oauthService.getTokenByCode(code, state);
+  }
+
+  /**
+   * Get user information using access token
+   * @example
+   * const userInfo = await sdk.getUserInfo(tokenResponse.accessToken);
+   */
+  async getUserInfo(accessToken: string): Promise<GetUserInfoResponse> {
+    const data = await this.oauthService.getUserInfoByToken({
+      accessToken,
+    } as ExchangeTokenResponse);
+    const loginMethod = this.deriveLoginMethod(
+      (data as any)?.platforms,
+      (data as any)?.platform ?? data.platform ?? null
+    );
+    return {
+      ...(data as any),
+      platform: loginMethod,
+      loginMethod,
+    } as GetUserInfoResponse;
+  }
+
+  private parseCookies(cookieHeader: string | undefined) {
+    if (!cookieHeader) {
+      return new Map<string, string>();
+    }
+
+    const parsed = parseCookieHeader(cookieHeader);
+    return new Map(Object.entries(parsed));
+  }
+
+  private getSessionSecret() {
+    const secret = ENV.cookieSecret;
+    return new TextEncoder().encode(secret);
+  }
+
+  /**
+   * Create a session token for a Manus user openId
+   * @example
+   * const sessionToken = await sdk.createSessionToken(userInfo.openId);
+   */
+  async createSessionToken(
+    openId: string,
+    options: { expiresInMs?: number; name?: string } = {}
+  ): Promise<string> {
+    return this.signSession(
+      {
+        openId,
+        appId: ENV.appId,
+        name: options.name || "",
+      },
+      options
+    );
+  }
+
+  async signSession(
+    payload: SessionPayload,
+    options: { expiresInMs?: number } = {}
+  ): Promise<string> {
+    const issuedAt = Date.now();
+    const expiresInMs = options.expiresInMs ?? ONE_YEAR_MS;
+    const expirationSeconds = Math.floor((issuedAt + expiresInMs) / 1000);
+    const secretKey = this.getSessionSecret();
+
+    return new SignJWT({
+      openId: payload.openId,
+      appId: payload.appId,
+      name: payload.name,
+    })
+      .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+      .setExpirationTime(expirationSeconds)
+      .sign(secretKey);
+  }
+
+  async verifySession(
+    cookieValue: string | undefined | null
+  ): Promise<{ openId: string; appId: string; name: string } | null> {
+    if (!cookieValue) {
+      console.warn("[Auth] Missing session cookie");
+      return null;
+    }
+
+    try {
+      const secretKey = this.getSessionSecret();
+      const { payload } = await jwtVerify(cookieValue, secretKey, {
+        algorithms: ["HS256"],
+      });
+      const { openId, appId, name } = payload as Record<string, unknown>;
+
+      if (
+        !isNonEmptyString(openId) ||
+        !isNonEmptyString(appId) ||
+        !isNonEmptyString(name)
+      ) {
+        console.warn("[Auth] Session payload missing required fields");
+        return null;
+      }
+
+      return {
+        openId,
+        appId,
+        name,
+      };
+    } catch (error) {
+      console.warn("[Auth] Session verification failed", String(error));
+      return null;
+    }
+  }
+
+  async getUserInfoWithJwt(
+    jwtToken: string
+  ): Promise<GetUserInfoWithJwtResponse> {
+    const payload: GetUserInfoWithJwtRequest = {
+      jwtToken,
+      projectId: ENV.appId,
+    };
+
+    const { data } = await this.client.post<GetUserInfoWithJwtResponse>(
+      GET_USER_INFO_WITH_JWT_PATH,
+      payload
+    );
+
+    const loginMethod = this.deriveLoginMethod(
+      (data as any)?.platforms,
+      (data as any)?.platform ?? data.platform ?? null
+    );
+    return {
+      ...(data as any),
+      platform: loginMethod,
+      loginMethod,
+    } as GetUserInfoWithJwtResponse;
+  }
+
+  async authenticateRequest(req: Request): Promise<User> {
+    if (this.isLocalAuthMode()) {
+      const signedInAt = new Date();
+      const localOpenId = ENV.localDevOpenId;
+
+      try {
+        await db.upsertUser({
+          openId: localOpenId,
+          name: ENV.localDevName,
+          email: ENV.localDevEmail,
+          loginMethod: "local",
+          lastSignedIn: signedInAt,
+        });
+        const localUser = await db.getUserByOpenId(localOpenId);
+        if (localUser) return localUser;
+      } catch {
+        // DB not ready yet (e.g. MySQL still starting up); fall through to
+        // an in-memory guest user so the UI keeps working.
+        console.warn("[Auth] DB unavailable in local mode, using fallback user");
+      }
+
+      // Fallback: return a transient in-memory user so requests don't fail
+      // while MySQL is warming up.
+      return {
+        id: 0,
+        openId: localOpenId,
+        name: ENV.localDevName ?? "Dev User",
+        email: ENV.localDevEmail ?? null,
+        loginMethod: "local",
+        role: "admin" as const,
+        createdAt: signedInAt,
+        updatedAt: signedInAt,
+        lastSignedIn: signedInAt,
+      };
+    }
+
+    // Regular authentication flow
+    const cookies = this.parseCookies(req.headers.cookie);
+    const sessionCookie = cookies.get(COOKIE_NAME);
+    const session = await this.verifySession(sessionCookie);
+
+    if (!session) {
+      throw ForbiddenError("Invalid session cookie");
+    }
+
+    const sessionUserId = session.openId;
+    const signedInAt = new Date();
+    let user = await db.getUserByOpenId(sessionUserId);
+
+    // If user not in DB, sync from OAuth server automatically
+    if (!user) {
+      try {
+        const userInfo = await this.getUserInfoWithJwt(sessionCookie ?? "");
+        await db.upsertUser({
+          openId: userInfo.openId,
+          name: userInfo.name || null,
+          email: userInfo.email ?? null,
+          loginMethod: userInfo.loginMethod ?? userInfo.platform ?? null,
+          lastSignedIn: signedInAt,
+        });
+        user = await db.getUserByOpenId(userInfo.openId);
+      } catch (error) {
+        console.error("[Auth] Failed to sync user from OAuth:", error);
+        throw ForbiddenError("Failed to sync user info");
+      }
+    }
+
+    if (!user) {
+      throw ForbiddenError("User not found");
+    }
+
+    await db.upsertUser({
+      openId: user.openId,
+      lastSignedIn: signedInAt,
+    });
+
+    return user;
+  }
+}
+
+export const sdk = new SDKServer();

server/_core/systemRouter.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { notifyOwner } from "./notification";
+import { adminProcedure, publicProcedure, router } from "./trpc";
+
+export const systemRouter = router({
+  health: publicProcedure
+    .input(
+      z.object({
+        timestamp: z.number().min(0, "timestamp cannot be negative"),
+      })
+    )
+    .query(() => ({
+      ok: true,
+    })),
+
+  notifyOwner: adminProcedure
+    .input(
+      z.object({
+        title: z.string().min(1, "title is required"),
+        content: z.string().min(1, "content is required"),
+      })
+    )
+    .mutation(async ({ input }) => {
+      const delivered = await notifyOwner(input);
+      return {
+        success: delivered,
+      } as const;
+    }),
+});

server/_core/trpc.ts

@@ -0,0 +1,45 @@
+import { NOT_ADMIN_ERR_MSG, UNAUTHED_ERR_MSG } from '@shared/const';
+import { initTRPC, TRPCError } from "@trpc/server";
+import superjson from "superjson";
+import type { TrpcContext } from "./context";
+
+const t = initTRPC.context<TrpcContext>().create({
+  transformer: superjson,
+});
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+
+const requireUser = t.middleware(async opts => {
+  const { ctx, next } = opts;
+
+  if (!ctx.user) {
+    throw new TRPCError({ code: "UNAUTHORIZED", message: UNAUTHED_ERR_MSG });
+  }
+
+  return next({
+    ctx: {
+      ...ctx,
+      user: ctx.user,
+    },
+  });
+});
+
+export const protectedProcedure = t.procedure.use(requireUser);
+
+export const adminProcedure = t.procedure.use(
+  t.middleware(async opts => {
+    const { ctx, next } = opts;
+
+    if (!ctx.user || ctx.user.role !== 'admin') {
+      throw new TRPCError({ code: "FORBIDDEN", message: NOT_ADMIN_ERR_MSG });
+    }
+
+    return next({
+      ctx: {
+        ...ctx,
+        user: ctx.user,
+      },
+    });
+  }),
+);

server/_core/types/cookie.d.ts

@@ -0,0 +1,6 @@
+declare module "cookie" {
+  export function parse(
+    str: string,
+    options?: Record<string, unknown>
+  ): Record<string, string>;
+}

server/_core/types/manusTypes.ts

@@ -0,0 +1,69 @@
+// WebDev Auth TypeScript types
+// Auto-generated from protobuf definitions
+// Generated on: 2025-09-24T05:57:57.338Z
+
+export interface AuthorizeRequest {
+  redirectUri: string;
+  projectId: string;
+  state: string;
+  responseType: string;
+  scope: string;
+}
+
+export interface AuthorizeResponse {
+  redirectUrl: string;
+}
+
+export interface ExchangeTokenRequest {
+  grantType: string;
+  code: string;
+  refreshToken?: string;
+  clientId: string;
+  clientSecret?: string;
+  redirectUri: string;
+}
+
+export interface ExchangeTokenResponse {
+  accessToken: string;
+  tokenType: string;
+  expiresIn: number;
+  refreshToken?: string;
+  scope: string;
+  idToken: string;
+}
+
+export interface GetUserInfoRequest {
+  accessToken: string;
+}
+
+export interface GetUserInfoResponse {
+  openId: string;
+  projectId: string;
+  name: string;
+  email?: string | null;
+  platform?: string | null;
+  loginMethod?: string | null;
+}
+
+export interface CanAccessRequest {
+  openId: string;
+  projectId: string;
+}
+
+export interface CanAccessResponse {
+  canAccess: boolean;
+}
+
+export interface GetUserInfoWithJwtRequest {
+  jwtToken: string;
+  projectId: string;
+}
+
+export interface GetUserInfoWithJwtResponse {
+  openId: string;
+  projectId: string;
+  name: string;
+  email?: string | null;
+  platform?: string | null;
+  loginMethod?: string | null;
+}

server/_core/vite.ts

@@ -0,0 +1,86 @@
+import express, { type Express } from "express";
+import fs from "fs";
+import { type Server } from "http";
+import { nanoid } from "nanoid";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createServer as createViteServer } from "vite";
+import viteConfig from "../../vite.config";
+
+const SERVER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+
+export async function setupVite(app: Express, server: Server) {
+  const serverOptions = {
+    middlewareMode: true,
+    // Disable Vite client-side auto reload/HMR in dev.
+    hmr: false as const,
+    allowedHosts: true as const,
+  };
+
+  const vite = await createViteServer({
+    ...viteConfig,
+    configFile: false,
+    server: serverOptions,
+    appType: "custom",
+  });
+
+  // 只对非 API 路由使用 Vite 中间件
+  app.use((req, res, next) => {
+    const url = req.originalUrl || req.url;
+    if (url.startsWith('/api/')) {
+      console.log(`[Vite] Skipping API route: ${url}`);
+      return next();
+    }
+    vite.middlewares.handle(req, res, next);
+  });
+  
+  // 只对非 API 路由使用 HTML fallback
+  app.use("*", async (req, res, next) => {
+    const url = req.originalUrl;
+
+    // 跳过 API 路由
+    if (url.startsWith('/api/')) {
+      return next();
+    }
+
+    try {
+      const clientTemplate = path.resolve(
+        SERVER_ROOT,
+        "../..",
+        "client",
+        "index.html"
+      );
+
+      // always reload the index.html file from disk incase it changes
+      let template = await fs.promises.readFile(clientTemplate, "utf-8");
+      template = template.replace(
+        `src="/src/main.tsx"`,
+        `src="/src/main.tsx?v=${nanoid()}"`
+      );
+      const page = await vite.transformIndexHtml(url, template);
+      res.status(200).set({ "Content-Type": "text/html" }).end(page);
+    } catch (e) {
+      vite.ssrFixStacktrace(e as Error);
+      next(e);
+    }
+  });
+}
+
+export function serveStatic(app: Express) {
+  const distPath =
+    process.env.NODE_ENV === "development"
+      ? path.resolve(SERVER_ROOT, "../..", "dist", "public")
+      : path.resolve(SERVER_ROOT, "public");
+  if (!fs.existsSync(distPath)) {
+    console.error(
+      `Could not find the build directory: ${distPath}, make sure to build the client first`
+    );
+  }
+
+  app.use(express.static(distPath));
+
+  // fall through to index.html if the file doesn't exist
+  app.use("*", (_req, res) => {
+    res.sendFile(path.resolve(distPath, "index.html"));
+  });
+}

server/_core/voiceTranscription.ts

@@ -0,0 +1,284 @@
+/**
+ * Voice transcription helper using internal Speech-to-Text service
+ *
+ * Frontend implementation guide:
+ * 1. Capture audio using MediaRecorder API
+ * 2. Upload audio to storage (e.g., S3) to get URL
+ * 3. Call transcription with the URL
+ * 
+ * Example usage:
+ * ```tsx
+ * // Frontend component
+ * const transcribeMutation = trpc.voice.transcribe.useMutation({
+ *   onSuccess: (data) => {
+ *     console.log(data.text); // Full transcription
+ *     console.log(data.language); // Detected language
+ *     console.log(data.segments); // Timestamped segments
+ *   }
+ * });
+ * 
+ * // After uploading audio to storage
+ * transcribeMutation.mutate({
+ *   audioUrl: uploadedAudioUrl,
+ *   language: 'en', // optional
+ *   prompt: 'Transcribe the meeting' // optional
+ * });
+ * ```
+ */
+import { ENV } from "./env";
+
+export type TranscribeOptions = {
+  audioUrl: string; // URL to the audio file (e.g., S3 URL)
+  language?: string; // Optional: specify language code (e.g., "en", "es", "zh")
+  prompt?: string; // Optional: custom prompt for the transcription
+};
+
+// Native Whisper API segment format
+export type WhisperSegment = {
+  id: number;
+  seek: number;
+  start: number;
+  end: number;
+  text: string;
+  tokens: number[];
+  temperature: number;
+  avg_logprob: number;
+  compression_ratio: number;
+  no_speech_prob: number;
+};
+
+// Native Whisper API response format
+export type WhisperResponse = {
+  task: "transcribe";
+  language: string;
+  duration: number;
+  text: string;
+  segments: WhisperSegment[];
+};
+
+export type TranscriptionResponse = WhisperResponse; // Return native Whisper API response directly
+
+export type TranscriptionError = {
+  error: string;
+  code: "FILE_TOO_LARGE" | "INVALID_FORMAT" | "TRANSCRIPTION_FAILED" | "UPLOAD_FAILED" | "SERVICE_ERROR";
+  details?: string;
+};
+
+/**
+ * Transcribe audio to text using the internal Speech-to-Text service
+ * 
+ * @param options - Audio data and metadata
+ * @returns Transcription result or error
+ */
+export async function transcribeAudio(
+  options: TranscribeOptions
+): Promise<TranscriptionResponse | TranscriptionError> {
+  try {
+    // Step 1: Validate environment configuration
+    if (!ENV.forgeApiUrl) {
+      return {
+        error: "Voice transcription service is not configured",
+        code: "SERVICE_ERROR",
+        details: "BUILT_IN_FORGE_API_URL is not set"
+      };
+    }
+    if (!ENV.forgeApiKey) {
+      return {
+        error: "Voice transcription service authentication is missing",
+        code: "SERVICE_ERROR",
+        details: "BUILT_IN_FORGE_API_KEY is not set"
+      };
+    }
+
+    // Step 2: Download audio from URL
+    let audioBuffer: Buffer;
+    let mimeType: string;
+    try {
+      const response = await fetch(options.audioUrl);
+      if (!response.ok) {
+        return {
+          error: "Failed to download audio file",
+          code: "INVALID_FORMAT",
+          details: `HTTP ${response.status}: ${response.statusText}`
+        };
+      }
+      
+      audioBuffer = Buffer.from(await response.arrayBuffer());
+      mimeType = response.headers.get('content-type') || 'audio/mpeg';
+      
+      // Check file size (16MB limit)
+      const sizeMB = audioBuffer.length / (1024 * 1024);
+      if (sizeMB > 16) {
+        return {
+          error: "Audio file exceeds maximum size limit",
+          code: "FILE_TOO_LARGE",
+          details: `File size is ${sizeMB.toFixed(2)}MB, maximum allowed is 16MB`
+        };
+      }
+    } catch (error) {
+      return {
+        error: "Failed to fetch audio file",
+        code: "SERVICE_ERROR",
+        details: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+
+    // Step 3: Create FormData for multipart upload to Whisper API
+    const formData = new FormData();
+    
+    // Create a Blob from the buffer and append to form
+    const filename = `audio.${getFileExtension(mimeType)}`;
+    const audioBlob = new Blob([new Uint8Array(audioBuffer)], { type: mimeType });
+    formData.append("file", audioBlob, filename);
+    
+    formData.append("model", "whisper-1");
+    formData.append("response_format", "verbose_json");
+    
+    // Add prompt - use custom prompt if provided, otherwise generate based on language
+    const prompt = options.prompt || (
+      options.language 
+        ? `Transcribe the user's voice to text, the user's working language is ${getLanguageName(options.language)}`
+        : "Transcribe the user's voice to text"
+    );
+    formData.append("prompt", prompt);
+
+    // Step 4: Call the transcription service
+    const baseUrl = ENV.forgeApiUrl.endsWith("/")
+      ? ENV.forgeApiUrl
+      : `${ENV.forgeApiUrl}/`;
+    
+    const fullUrl = new URL(
+      "v1/audio/transcriptions",
+      baseUrl
+    ).toString();
+
+    const response = await fetch(fullUrl, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${ENV.forgeApiKey}`,
+        "Accept-Encoding": "identity",
+      },
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      return {
+        error: "Transcription service request failed",
+        code: "TRANSCRIPTION_FAILED",
+        details: `${response.status} ${response.statusText}${errorText ? `: ${errorText}` : ""}`
+      };
+    }
+
+    // Step 5: Parse and return the transcription result
+    const whisperResponse = await response.json() as WhisperResponse;
+    
+    // Validate response structure
+    if (!whisperResponse.text || typeof whisperResponse.text !== 'string') {
+      return {
+        error: "Invalid transcription response",
+        code: "SERVICE_ERROR",
+        details: "Transcription service returned an invalid response format"
+      };
+    }
+
+    return whisperResponse; // Return native Whisper API response directly
+
+  } catch (error) {
+    // Handle unexpected errors
+    return {
+      error: "Voice transcription failed",
+      code: "SERVICE_ERROR",
+      details: error instanceof Error ? error.message : "An unexpected error occurred"
+    };
+  }
+}
+
+/**
+ * Helper function to get file extension from MIME type
+ */
+function getFileExtension(mimeType: string): string {
+  const mimeToExt: Record<string, string> = {
+    'audio/webm': 'webm',
+    'audio/mp3': 'mp3',
+    'audio/mpeg': 'mp3',
+    'audio/wav': 'wav',
+    'audio/wave': 'wav',
+    'audio/ogg': 'ogg',
+    'audio/m4a': 'm4a',
+    'audio/mp4': 'm4a',
+  };
+  
+  return mimeToExt[mimeType] || 'audio';
+}
+
+/**
+ * Helper function to get full language name from ISO code
+ */
+function getLanguageName(langCode: string): string {
+  const langMap: Record<string, string> = {
+    'en': 'English',
+    'es': 'Spanish',
+    'fr': 'French',
+    'de': 'German',
+    'it': 'Italian',
+    'pt': 'Portuguese',
+    'ru': 'Russian',
+    'ja': 'Japanese',
+    'ko': 'Korean',
+    'zh': 'Chinese',
+    'ar': 'Arabic',
+    'hi': 'Hindi',
+    'nl': 'Dutch',
+    'pl': 'Polish',
+    'tr': 'Turkish',
+    'sv': 'Swedish',
+    'da': 'Danish',
+    'no': 'Norwegian',
+    'fi': 'Finnish',
+  };
+  
+  return langMap[langCode] || langCode;
+}
+
+/**
+ * Example tRPC procedure implementation:
+ * 
+ * ```ts
+ * // In server/routers.ts
+ * import { transcribeAudio } from "./_core/voiceTranscription";
+ * 
+ * export const voiceRouter = router({
+ *   transcribe: protectedProcedure
+ *     .input(z.object({
+ *       audioUrl: z.string(),
+ *       language: z.string().optional(),
+ *       prompt: z.string().optional(),
+ *     }))
+ *     .mutation(async ({ input, ctx }) => {
+ *       const result = await transcribeAudio(input);
+ *       
+ *       // Check if it's an error
+ *       if ('error' in result) {
+ *         throw new TRPCError({
+ *           code: 'BAD_REQUEST',
+ *           message: result.error,
+ *           cause: result,
+ *         });
+ *       }
+ *       
+ *       // Optionally save transcription to database
+ *       await db.insert(transcriptions).values({
+ *         userId: ctx.user.id,
+ *         text: result.text,
+ *         duration: result.duration,
+ *         language: result.language,
+ *         audioUrl: input.audioUrl,
+ *         createdAt: new Date(),
+ *       });
+ *       
+ *       return result;
+ *     }),
+ * });
+ * ```
+ */

server/algorithmJob.ts

@@ -0,0 +1,130 @@
+/**
+ * 通用算法任务调度器（Route B）
+ * ------------------------------------------------------------
+ * 职责：
+ *   1. 维护一个带上限的并发池（默认 4 并发），避免一次性 fork 太多
+ *      Python 子进程把宿主机打爆；
+ *   2. 把每个任务 fork 到独立 Node 子进程（algorithmJobRunner.ts），
+ *      让 HTTP/Vite 主进程不阻塞；
+ *   3. 子进程负责按 manifest 执行 process / mock runtime，
+ *      解析 stdout 进度，写 result.json，更新数据库。
+ *
+ * 主进程不直接 spawn Python，而是 fork Node runner —— 与现有
+ * smoothHeatmapJob / deviationHeatmapJob 的架构保持一致。
+ */
+import { fork, ChildProcess } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const DEFAULT_CONCURRENCY = Number(process.env.ALGORITHM_JOB_CONCURRENCY ?? 4);
+
+interface PendingJob {
+  resultId: number;
+  taskId: number;
+  pluginId: string;
+  params: Record<string, unknown>;
+  /** 可选：只处理选中的点云文件 ID；undefined/空数组 = 全部 */
+  pointCloudFileIds?: number[];
+  /** 可选：任务级 CAD 文件 ID；undefined/空数组 = 不传 CAD */
+  cadFileIds?: number[];
+  resolve: () => void;
+  reject: (err: unknown) => void;
+}
+
+class ConcurrencyPool {
+  private running = 0;
+  private queue: PendingJob[] = [];
+  private readonly limit: number;
+  private readonly activeChildren = new Set<ChildProcess>();
+
+  constructor(limit: number) {
+    this.limit = Math.max(1, limit);
+  }
+
+  get stats() {
+    return { running: this.running, queued: this.queue.length, limit: this.limit };
+  }
+
+  enqueue(job: Omit<PendingJob, 'resolve' | 'reject'>): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ ...job, resolve, reject });
+      this.pump();
+    });
+  }
+
+  private pump(): void {
+    while (this.running < this.limit && this.queue.length > 0) {
+      const next = this.queue.shift()!;
+      this.running += 1;
+      this.spawnChild(next).finally(() => {
+        this.running = Math.max(0, this.running - 1);
+        this.pump();
+      });
+    }
+  }
+
+  private async spawnChild(job: PendingJob): Promise<void> {
+    const script = resolveAlgorithmRunnerEntry();
+    const isProd = process.env.NODE_ENV === 'production';
+    const args = [
+      String(job.resultId),
+      String(job.taskId),
+      job.pluginId,
+      JSON.stringify(job.params ?? {}),
+      JSON.stringify(job.pointCloudFileIds ?? []),
+      JSON.stringify(job.cadFileIds ?? []),
+    ];
+    const child = fork(script, args, {
+      env: { ...process.env },
+      stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+      execArgv: isProd ? [] : ['--import', 'tsx'],
+    });
+    this.activeChildren.add(child);
+
+    return new Promise<void>((resolve) => {
+      child.on('error', (err) => {
+        console.error('[AlgorithmJob] fork 失败:', err);
+      });
+      child.on('exit', (code, signal) => {
+        this.activeChildren.delete(child);
+        if (code !== 0 && code != null) {
+          console.error(
+            `[AlgorithmJob] 子进程退出 code=${code} signal=${signal ?? ''} pluginId=${job.pluginId} resultId=${job.resultId}`,
+          );
+        }
+        // 即使失败也 resolve：runner 已经把数据库改成 error，主进程无需再处理
+        job.resolve();
+        resolve();
+      });
+    });
+  }
+}
+
+function resolveAlgorithmRunnerEntry(): string {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  if (process.env.NODE_ENV === 'production') {
+    return path.join(dir, 'algorithmJobRunner.js');
+  }
+  return path.join(dir, 'algorithmJobRunner.ts');
+}
+
+const pool = new ConcurrencyPool(DEFAULT_CONCURRENCY);
+
+/**
+ * 把一次插件运行加入并发池。返回的 Promise 在子进程退出时 resolve（无论成功/失败）。
+ * 真实结果状态写在 task_analysis_results.resultData / status 中，由前端轮询消费。
+ */
+export function enqueueAlgorithmJob(
+  resultId: number,
+  taskId: number,
+  pluginId: string,
+  params: Record<string, unknown> = {},
+  pointCloudFileIds?: number[],
+  cadFileIds?: number[],
+): Promise<void> {
+  return pool.enqueue({ resultId, taskId, pluginId, params, pointCloudFileIds, cadFileIds });
+}
+
+export function algorithmJobStats() {
+  return pool.stats;
+}

server/algorithmJobRunner.ts

@@ -0,0 +1,409 @@
+/**
+ * 通用算法插件子进程入口
+ * ------------------------------------------------------------
+ * fork 自 algorithmJob.ts，负责单次插件运行的全过程：
+ *   1. 校验 manifest 是否注册；
+ *   2. 准备 workDir = /data/tasks/<taskId>/analysis/<resultId>，写 input.json；
+ *   3. 按 runtime.kind 走 process / mock 两条路径：
+ *      - process：spawn Python，按行解析 stdout 进度 JSON，等子进程退出后读 result.json；
+ *      - mock：读 fixtures/<file>.json，假装跑 simulateMs ms 后写到 outDir/result.json；
+ *   4. 把 result.json 合并到 task_analysis_results.resultData，更新 status。
+ *
+ * 进程参数：
+ *   node algorithmJobRunner.js <resultId> <taskId> <pluginId> <paramsJSON>
+ */
+import 'dotenv/config';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import * as db from './db.js';
+import { getPlugin, adaptersDir, fixturesDir } from './plugins/registry.js';
+import type {
+  PluginManifest,
+  PluginProgressEvent,
+  PluginResult,
+  PluginResultData,
+} from './plugins/types.js';
+
+const DATA_DIR = process.env.DATA_DIR || '/data';
+const TASKS_DIR = path.join(DATA_DIR, 'tasks');
+const PYTHON_BIN = process.env.PYTHON3_PATH || 'python3';
+/** 算法源码根。生产镜像/开发宿主机上把 alg/ 挂到此处。 */
+const ALG_ROOT = process.env.ALG_ROOT || '/home/lipan/massive-cloud/alg';
+const DEFAULT_TIMEOUT_MS = 20 * 60 * 1000; // 20 分钟（验收要求）
+
+function workDirFor(taskId: number, resultId: number): string {
+  return path.join(TASKS_DIR, String(taskId), 'analysis', String(resultId));
+}
+
+function ensureDir(dir: string) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/** 把 process / mock cmd 模板里的占位符替换成实际路径。 */
+function resolvePlaceholders(value: string, ctx: Record<string, string>): string {
+  return value.replace(/\{(\w+)\}/g, (_, key) => ctx[key] ?? `{${key}}`);
+}
+
+/** 收集任务相关上下文：点云路径、CAD 路径等。 */
+async function gatherInputs(
+  taskId: number,
+  manifest: PluginManifest,
+  pointCloudFileIds?: number[],
+  cadFileIds?: number[],
+) {
+  const task = await db.getInspectionTaskById(taskId);
+  if (!task) throw new Error(`task ${taskId} not found`);
+
+  let pointCloudRecords = await db.listTaskPointcloudFiles(taskId);
+  if (Array.isArray(pointCloudFileIds) && pointCloudFileIds.length > 0) {
+    const idSet = new Set(pointCloudFileIds);
+    pointCloudRecords = pointCloudRecords.filter((r) => idSet.has(r.id));
+  }
+  const pointCloudPaths = pointCloudRecords.map((r) => r.filePath);
+  if (manifest.requiresPointCloud !== false && pointCloudPaths.length === 0) {
+    throw new Error('当前任务下未上传点云，请先上传。');
+  }
+
+  let cadPath: string | null = null;
+  if (manifest.requiresCad || (Array.isArray(cadFileIds) && cadFileIds.length > 0)) {
+    // 优先使用任务级 CAD（前端选中的）
+    if (Array.isArray(cadFileIds) && cadFileIds.length > 0) {
+      const taskCads = await db.listTaskCadFiles(taskId);
+      const idSet = new Set(cadFileIds);
+      const selected = taskCads.filter((r) => idSet.has(r.id));
+      if (selected.length > 0) {
+        cadPath = selected[0].filePath;
+      }
+    }
+    // 回退到车型级 CAD
+    if (!cadPath) {
+      const modelCads = await db.listModelCadFiles(task.modelId);
+      if (modelCads.length > 0) {
+        cadPath = modelCads[0].filePath;
+      }
+    }
+    if (!cadPath && manifest.requiresCad) {
+      throw new Error('该插件需要 CAD 文件，但当前任务和车型下均无 CAD。');
+    }
+  }
+
+  return { task, pointCloudPaths, cadPath };
+}
+
+async function writeInputJson(
+  workDir: string,
+  taskId: number,
+  resultId: number,
+  manifest: PluginManifest,
+  params: Record<string, unknown>,
+  pointCloudPaths: string[],
+  cadPath: string | null,
+) {
+  const inputJson = {
+    schemaVersion: 1,
+    pluginId: manifest.id,
+    pluginVersion: manifest.version,
+    resultId,
+    taskId,
+    workDir,
+    outDir: workDir,
+    inputs: {
+      pointCloudPaths,
+      cadPath,
+      config: params,
+    },
+  };
+  const target = path.join(workDir, 'input.json');
+  fs.writeFileSync(target, JSON.stringify(inputJson, null, 2), 'utf-8');
+  return target;
+}
+
+async function patchProgress(
+  resultId: number,
+  pluginId: string,
+  progress: number | undefined,
+  stage: string | undefined,
+) {
+  const data: Record<string, unknown> = {
+    kind: 'plugin',
+    pluginId,
+    progress: progress != null ? Math.max(0, Math.min(1, progress)) : undefined,
+    stage,
+  };
+  await db.patchTaskAnalysisResultData(resultId, data);
+}
+
+function normalizeProgress(percent: number): number {
+  // 适配器允许 0~1 也允许 0~100；> 1 时按百分比处理
+  if (percent <= 1.0 && percent >= 0) return percent;
+  return Math.max(0, Math.min(100, percent)) / 100;
+}
+
+function readResultJson(workDir: string): PluginResult | null {
+  const p = path.join(workDir, 'result.json');
+  if (!fs.existsSync(p)) return null;
+  try {
+    // JSON 标准不支持 NaN/Infinity；Python json 模块有时会输出 NaN，用正则替换掉
+    const raw = fs.readFileSync(p, 'utf-8').replace(/:\s*NaN\b/g, ': null').replace(/:\s*Infinity\b/g, ': null').replace(/:\s*-Infinity\b/g, ': null');
+    return JSON.parse(raw) as PluginResult;
+  } catch (e) {
+    console.error('[AlgorithmJobRunner] result.json 解析失败:', e);
+    return null;
+  }
+}
+
+async function runProcessRuntime(
+  manifest: PluginManifest,
+  workDir: string,
+  inputJsonPath: string,
+  resultId: number,
+): Promise<{ exitCode: number | null; lastStage?: string }> {
+  if (manifest.runtime.kind !== 'process') {
+    throw new Error('runtime.kind !== process');
+  }
+  const rt = manifest.runtime;
+  const ctx: Record<string, string> = {
+    pythonBin: PYTHON_BIN,
+    inputJson: inputJsonPath,
+    workDir,
+    adapterDir: adaptersDir(),
+    algRoot: ALG_ROOT,
+  };
+  const [cmd0, ...rawArgs] = rt.cmd;
+  if (!cmd0) throw new Error('runtime.cmd 为空');
+  const cmd = resolvePlaceholders(cmd0, ctx);
+  const args = rawArgs.map((a) => resolvePlaceholders(a, ctx));
+
+  const envExtra: Record<string, string> = {};
+  for (const [k, v] of Object.entries(rt.envExtra ?? {})) {
+    envExtra[k] = resolvePlaceholders(String(v), ctx);
+  }
+
+  console.log(`[AlgorithmJobRunner] spawn ${cmd} ${args.join(' ')}`);
+  const proc = spawn(cmd, args, {
+    cwd: workDir,
+    env: { ...process.env, ...envExtra },
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
+
+  const timeoutMs = rt.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timer = setTimeout(() => {
+    console.error(`[AlgorithmJobRunner] 超时 ${timeoutMs}ms，杀掉子进程`);
+    proc.kill('SIGKILL');
+  }, timeoutMs);
+
+  let buf = '';
+  let lastStage: string | undefined;
+  proc.stdout.setEncoding('utf-8');
+  proc.stdout.on('data', (chunk: string) => {
+    buf += chunk;
+    let nl: number;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      // 行可能是进度 JSON，也可能是普通日志；普通日志直接落控制台
+      if (line.startsWith('{') && line.includes('"progress"')) {
+        try {
+          const evt = JSON.parse(line) as PluginProgressEvent & { progress?: number; stage?: string };
+          // 兼容两种字段名：percent / progress
+          const rawPercent = (evt as any).percent ?? (evt as any).progress;
+          const percent = typeof rawPercent === 'number' ? normalizeProgress(rawPercent) : undefined;
+          const stage = (evt as any).message ?? (evt as any).stage;
+          lastStage = stage ?? lastStage;
+          void patchProgress(resultId, manifest.id, percent, stage);
+        } catch {
+          process.stdout.write(`[plugin:${manifest.id}] ${line}\n`);
+        }
+      } else {
+        process.stdout.write(`[plugin:${manifest.id}] ${line}\n`);
+      }
+    }
+  });
+
+  const exitCode: number | null = await new Promise((resolve) => {
+    proc.on('error', (err) => {
+      console.error('[AlgorithmJobRunner] spawn error:', err);
+      resolve(-1);
+    });
+    proc.on('exit', (code) => resolve(code));
+  });
+  clearTimeout(timer);
+  return { exitCode, lastStage };
+}
+
+async function runMockRuntime(
+  manifest: PluginManifest,
+  workDir: string,
+  resultId: number,
+): Promise<void> {
+  if (manifest.runtime.kind !== 'mock') return;
+  const fixturePath = path.join(fixturesDir(), manifest.runtime.fixture);
+  if (!fs.existsSync(fixturePath)) {
+    throw new Error(`mock fixture 不存在: ${fixturePath}`);
+  }
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf-8')) as PluginResult;
+  const simulateMs = Math.max(0, manifest.runtime.simulateMs ?? 1200);
+  const steps = 8;
+  for (let i = 1; i <= steps; i++) {
+    await patchProgress(resultId, manifest.id, i / steps, `Mock 阶段 ${i}/${steps}`);
+    await sleep(simulateMs / steps);
+  }
+  fs.writeFileSync(path.join(workDir, 'result.json'), JSON.stringify(fixture, null, 2), 'utf-8');
+}
+
+export async function runAlgorithmJob(
+  resultId: number,
+  taskId: number,
+  pluginId: string,
+  params: Record<string, unknown>,
+  pointCloudFileIds?: number[],
+  cadFileIds?: number[],
+): Promise<void> {
+  const manifest = getPlugin(pluginId);
+  if (!manifest) {
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'error',
+      resultData: {
+        kind: 'plugin',
+        pluginId,
+        error: `未注册的插件：${pluginId}`,
+      } as PluginResultData,
+    });
+    return;
+  }
+
+  const workDir = workDirFor(taskId, resultId);
+  ensureDir(workDir);
+
+  try {
+    await patchProgress(resultId, pluginId, 0.02, '准备输入');
+    const { pointCloudPaths, cadPath } = await gatherInputs(taskId, manifest, pointCloudFileIds, cadFileIds);
+    const inputJsonPath = await writeInputJson(
+      workDir,
+      taskId,
+      resultId,
+      manifest,
+      params,
+      pointCloudPaths,
+      cadPath,
+    );
+
+    let exitCode: number | null = 0;
+    if (manifest.runtime.kind === 'process') {
+      const r = await runProcessRuntime(manifest, workDir, inputJsonPath, resultId);
+      exitCode = r.exitCode;
+    } else {
+      await runMockRuntime(manifest, workDir, resultId);
+    }
+
+    const result = readResultJson(workDir);
+    const finalStatus: 'completed' | 'error' = result?.status === 'error'
+      ? 'error'
+      : exitCode === 0 || manifest.runtime.kind === 'mock'
+        ? 'completed'
+        : 'error';
+
+    const resultData: PluginResultData = {
+      kind: 'plugin',
+      pluginId,
+      progress: finalStatus === 'completed' ? 1 : undefined,
+      stage: finalStatus === 'completed' ? '完成' : '失败',
+      exitCode,
+      // 把 result.json 内容平展到 resultData 里，方便前端直接使用
+      schemaVersion: result?.schemaVersion ?? manifest.schemaVersion,
+      message: result?.message,
+      measurements: result?.measurements,
+      errorStats: result?.errorStats,
+      overlay3d: result?.overlay3d,
+      images: result?.images,
+      extra: result?.extra,
+      error: finalStatus === 'error'
+        ? result?.message ?? `子进程退出码 ${exitCode}`
+        : undefined,
+    };
+
+    await db.updateTaskAnalysisResult(resultId, {
+      status: finalStatus,
+      errorStats: result?.errorStats ?? null,
+      measurements: result?.measurements ?? null,
+      resultData,
+    });
+
+    if (finalStatus === 'completed') {
+      console.log(
+        `[AlgorithmJobRunner] ok pluginId=${pluginId} resultId=${resultId} taskId=${taskId}`,
+      );
+    } else {
+      console.error(
+        `[AlgorithmJobRunner] failed pluginId=${pluginId} resultId=${resultId} exit=${exitCode}`,
+      );
+    }
+  } catch (err) {
+    console.error('[AlgorithmJobRunner]', err);
+    const message = err instanceof Error ? err.message : String(err);
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'error',
+      resultData: {
+        kind: 'plugin',
+        pluginId,
+        error: message,
+      } as PluginResultData,
+    });
+  }
+}
+
+// ─── CLI 入口 ────────────────────────────────────────────────────────────────
+//
+// node algorithmJobRunner.js <resultId> <taskId> <pluginId> <paramsJSON> [pcFileIdsJSON] [cadFileIdsJSON]
+
+const [, , a, b, c, d, e, f] = process.argv;
+if (a && b && c) {
+  const resultId = Number(a);
+  const taskId = Number(b);
+  const pluginId = String(c);
+  let params: Record<string, unknown> = {};
+  if (d) {
+    try {
+      params = JSON.parse(d) as Record<string, unknown>;
+    } catch (err) {
+      console.error('[AlgorithmJobRunner] params JSON 解析失败:', err);
+    }
+  }
+  let pointCloudFileIds: number[] | undefined;
+  if (e) {
+    try {
+      const parsed = JSON.parse(e) as unknown;
+      if (Array.isArray(parsed) && parsed.length > 0) {
+        pointCloudFileIds = parsed.map(Number).filter(Number.isFinite);
+      }
+    } catch (err) {
+      console.error('[AlgorithmJobRunner] pcFileIds JSON 解析失败:', err);
+    }
+  }
+  let cadFileIds: number[] | undefined;
+  if (f) {
+    try {
+      const parsed = JSON.parse(f) as unknown;
+      if (Array.isArray(parsed) && parsed.length > 0) {
+        cadFileIds = parsed.map(Number).filter(Number.isFinite);
+      }
+    } catch (err) {
+      console.error('[AlgorithmJobRunner] cadFileIds JSON 解析失败:', err);
+    }
+  }
+  if (!Number.isFinite(resultId) || !Number.isFinite(taskId) || resultId <= 0 || taskId <= 0) {
+    console.error('[AlgorithmJobRunner] 用法: <resultId> <taskId> <pluginId> [paramsJSON] [pcFileIdsJSON] [cadFileIdsJSON]');
+    process.exit(1);
+  }
+  runAlgorithmJob(resultId, taskId, pluginId, params, pointCloudFileIds, cadFileIds)
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error('[AlgorithmJobRunner]', err);
+      process.exit(1);
+    });
+}

server/assemblyGpuNearest.ts

@@ -0,0 +1,115 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { SampledPoint } from './pointcloudSample.js';
+
+function scriptPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(here, '..', 'scripts', 'assembly_nearest_gpu.py');
+}
+
+function resolvePython3(): string {
+  const fromEnv = process.env.PYTHON3_PATH?.trim();
+  if (fromEnv) return fromEnv;
+  if (process.platform === 'win32') return 'python3';
+  for (const p of ['/usr/bin/python3', '/usr/local/bin/python3']) {
+    try {
+      if (fs.existsSync(p)) return p;
+    } catch {
+      /* ignore */
+    }
+  }
+  return 'python3';
+}
+
+/** 环境变量 ASSEMBLY_USE_GPU=1 / true 时尝试 GPU（失败则由调用方回退 CPU） */
+export function assemblyGpuNearestEnabled(): boolean {
+  const v = process.env.ASSEMBLY_USE_GPU?.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+export type GpuNearestNumbers = {
+  assignments: number[];
+  pointDistances: number[];
+};
+
+/**
+ * 调用 scripts/assembly_nearest_gpu.py（PyTorch3D CUDA）。
+ * 返回 null：未启用、脚本缺失、无 CUDA、导入失败（exit 2）或其它错误。
+ */
+export function tryRunAssemblyNearestGpu(manifestDir: string, sampled: SampledPoint[]): GpuNearestNumbers | null {
+  if (!assemblyGpuNearestEnabled()) return null;
+  const script = scriptPath();
+  if (!fs.existsSync(script)) return null;
+  if (sampled.length === 0) return null;
+
+  const py = resolvePython3();
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'asm-gpu-'));
+  const ptsFile = path.join(tmp, 'points.bin');
+  const buf = Buffer.allocUnsafe(sampled.length * 12);
+  for (let i = 0; i < sampled.length; i++) {
+    const o = i * 12;
+    buf.writeFloatLE(sampled[i]!.x, o);
+    buf.writeFloatLE(sampled[i]!.y, o + 4);
+    buf.writeFloatLE(sampled[i]!.z, o + 8);
+  }
+  fs.writeFileSync(ptsFile, buf);
+
+  try {
+    const r = spawnSync(
+      py,
+      [script, '--points', ptsFile, '--manifest-dir', manifestDir, '--out-dir', tmp],
+      {
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        env: { ...process.env, PYTHONUNBUFFERED: '1' },
+      },
+    );
+
+    if (r.error) {
+      console.warn('[AssemblyGPU]', r.error.message);
+      return null;
+    }
+    if (r.status === 2) {
+      console.warn('[AssemblyGPU] 回退 CPU：', (r.stdout || '').trim().slice(-500) || 'exit 2');
+      return null;
+    }
+    if (r.status !== 0) {
+      console.warn('[AssemblyGPU] 失败 status=', r.status, (r.stderr || r.stdout || '').slice(0, 800));
+      return null;
+    }
+
+    const resultJsonPath = path.join(tmp, 'result.json');
+    if (!fs.existsSync(resultJsonPath)) return null;
+    const meta = JSON.parse(fs.readFileSync(resultJsonPath, 'utf-8')) as {
+      ok?: boolean;
+      n?: number;
+      assignmentsFile?: string;
+      distancesFile?: string;
+    };
+    if (!meta.ok || !meta.assignmentsFile || !meta.distancesFile) return null;
+    if (meta.n !== sampled.length) {
+      console.warn('[AssemblyGPU] 点数不一致', meta.n, sampled.length);
+      return null;
+    }
+
+    const aBuf = fs.readFileSync(meta.assignmentsFile);
+    const dBuf = fs.readFileSync(meta.distancesFile);
+    const n = sampled.length;
+    if (aBuf.length !== n * 4 || dBuf.length !== n * 4) {
+      console.warn('[AssemblyGPU] 二进制长度异常');
+      return null;
+    }
+    const assignments = Array.from(new Int32Array(aBuf.buffer, aBuf.byteOffset, n));
+    const pointDistances = Array.from(new Float32Array(dBuf.buffer, dBuf.byteOffset, n));
+    return { assignments, pointDistances };
+  } finally {
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}

server/assemblyInspectionCompute.ts

@@ -0,0 +1,253 @@
+import { BufferGeometry, Float32BufferAttribute, Vector3 } from 'three';
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+import { MeshBVH } from 'three-mesh-bvh';
+import { buildPCGrid3D, nearestPointInGrid, type HeatmapPoint } from '../shared/cadHeatmapMath.js';
+import type { SampledPoint } from './pointcloudSample.js';
+import type { StepManifestPart } from './stepParse.js';
+
+export type PartMeshBVH = {
+  part: StepManifestPart;
+  geometry: BufferGeometry;
+  bvh: MeshBVH;
+};
+
+export function loadStlToBVH(buf: Buffer): { geometry: BufferGeometry; bvh: MeshBVH } {
+  const loader = new STLLoader();
+  const u8 = new Uint8Array(buf);
+  const ab = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
+  const geometry = loader.parse(ab) as BufferGeometry;
+  geometry.computeVertexNormals();
+  const bvh = new MeshBVH(geometry);
+  return { geometry, bvh };
+}
+
+function distancePointToMesh(bvh: MeshBVH, p: Vector3): number {
+  const hit = bvh.closestPointToPoint(p);
+  return hit ? hit.distance : Infinity;
+}
+
+/** 零件 AABB 的外接球（心 + 半对角线）；点到网格距离 ≥ max(0, d(点,心)−r) */
+export type PartSphere = { cx: number; cy: number; cz: number; r: number };
+
+export function computePartSphere(geometry: BufferGeometry): PartSphere {
+  if (!geometry.boundingBox) geometry.computeBoundingBox();
+  const bb = geometry.boundingBox!;
+  const cx = (bb.min.x + bb.max.x) * 0.5;
+  const cy = (bb.min.y + bb.max.y) * 0.5;
+  const cz = (bb.min.z + bb.max.z) * 0.5;
+  const dx = bb.max.x - bb.min.x;
+  const dy = bb.max.y - bb.min.y;
+  const dz = bb.max.z - bb.min.z;
+  const r = 0.5 * Math.sqrt(dx * dx + dy * dy + dz * dz) + 1e-9;
+  return { cx, cy, cz, r };
+}
+
+function sphereDistLowerBound(px: number, py: number, pz: number, s: PartSphere): number {
+  const dx = px - s.cx;
+  const dy = py - s.cy;
+  const dz = pz - s.cz;
+  const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+  return Math.max(0, d - s.r);
+}
+
+export type PartStats = {
+  partId: string;
+  name: string;
+  min: number;
+  max: number;
+  mean: number;
+  stdDev: number;
+  passRate: number;
+  pointCount: number;
+};
+
+const ASSIGN_PROGRESS_EVERY = 12_000;
+
+export type AssignNearestOptions = {
+  /** 每处理若干点上报一次，避免长时间卡在 0.55 无反馈 */
+  onProgress?: (done: number, total: number) => void | Promise<void>;
+};
+
+/**
+ * 对每个测点找最近零件网格距离：朴素 O(点数×零件数) BVH 在零件多时极慢。
+ * 用外接球下界排序 + 下界≥当前最优时跳过 BVH，大幅减少查询次数。
+ */
+export async function assignNearestPartAndStats(
+  parts: PartMeshBVH[],
+  points: SampledPoint[],
+  toleranceMm: number,
+  options: AssignNearestOptions = {},
+): Promise<{
+  assignments: number[];
+  perPartDists: number[][];
+  pointDistances: number[];
+  stats: PartStats[];
+}> {
+  const nP = parts.length;
+  const nPt = points.length;
+  const assignments = new Array<number>(nPt);
+  const pointDistances = new Array<number>(nPt);
+  const perPartDists: number[][] = Array.from({ length: nP }, () => []);
+
+  const spheres: PartSphere[] = parts.map((p) => computePartSphere(p.geometry));
+  const lbs = new Float64Array(nP);
+  const order: number[] = new Array(nP);
+
+  const tmp = new Vector3();
+  for (let pi = 0; pi < nPt; pi++) {
+    const x = points[pi].x;
+    const y = points[pi].y;
+    const z = points[pi].z;
+    tmp.set(x, y, z);
+
+    for (let j = 0; j < nP; j++) {
+      lbs[j] = sphereDistLowerBound(x, y, z, spheres[j]!);
+    }
+    for (let j = 0; j < nP; j++) order[j] = j;
+    order.sort((a, b) => lbs[a]! - lbs[b]!);
+
+    let best = Infinity;
+    let bestIdx = 0;
+    for (let k = 0; k < nP; k++) {
+      const j = order[k]!;
+      const lb = lbs[j]!;
+      if (lb >= best) break;
+      const d = distancePointToMesh(parts[j].bvh, tmp);
+      if (d < best) {
+        best = d;
+        bestIdx = j;
+      }
+    }
+
+    assignments[pi] = bestIdx;
+    pointDistances[pi] = best;
+    perPartDists[bestIdx].push(best);
+
+    if (options.onProgress && (pi + 1) % ASSIGN_PROGRESS_EVERY === 0) {
+      await options.onProgress(pi + 1, nPt);
+    }
+  }
+
+  if (options.onProgress && nPt > 0) {
+    await options.onProgress(nPt, nPt);
+  }
+
+  const stats = computePartStatsFromPerPartDists(
+    parts.map((p) => p.part),
+    perPartDists,
+    toleranceMm,
+  );
+
+  return { assignments, perPartDists, pointDistances, stats };
+}
+
+/** 由 assignments + distances 填充分桶后算统计（GPU 路径复用） */
+export function perPartDistsFromAssignments(
+  nParts: number,
+  assignments: number[],
+  pointDistances: number[],
+): number[][] {
+  const perPartDists: number[][] = Array.from({ length: nParts }, () => []);
+  for (let i = 0; i < assignments.length; i++) {
+    perPartDists[assignments[i]!]!.push(pointDistances[i]!);
+  }
+  return perPartDists;
+}
+
+export function computePartStatsFromPerPartDists(
+  manifestParts: StepManifestPart[],
+  perPartDists: number[][],
+  toleranceMm: number,
+): PartStats[] {
+  return manifestParts.map((part, j) => {
+    const ds = perPartDists[j];
+    const pointCount = ds?.length ?? 0;
+    if (pointCount === 0) {
+      return {
+        partId: part.id,
+        name: part.name,
+        min: 0,
+        max: 0,
+        mean: 0,
+        stdDev: 0,
+        passRate: 1,
+        pointCount: 0,
+      };
+    }
+    let min = Infinity;
+    let max = -Infinity;
+    let sum = 0;
+    for (const d of ds) {
+      if (d < min) min = d;
+      if (d > max) max = d;
+      sum += d;
+    }
+    const mean = sum / pointCount;
+    let vsum = 0;
+    for (const d of ds) {
+      const t = d - mean;
+      vsum += t * t;
+    }
+    const stdDev = Math.sqrt(vsum / pointCount);
+    let pass = 0;
+    for (const d of ds) {
+      if (d < toleranceMm) pass++;
+    }
+    const passRate = pass / pointCount;
+    return {
+      partId: part.id,
+      name: part.name,
+      min,
+      max,
+      mean,
+      stdDev,
+      passRate,
+      pointCount,
+    };
+  });
+}
+
+/** 每顶点：到「归属该零件的测点」的最近距离，用于简易热力（可选） */
+export function computeVertexDistanceHeatmap(
+  geometry: BufferGeometry,
+  pointsForPart: SampledPoint[],
+): Float32Array | null {
+  const pos = geometry.attributes.position;
+  if (!pos || pos.count === 0) return null;
+  const nV = pos.count;
+  const hp: HeatmapPoint[] = pointsForPart.map((p) => ({ x: p.x, y: p.y, z: p.z, error: 0 }));
+  if (hp.length === 0) {
+    return new Float32Array(nV).fill(0);
+  }
+  const grid = buildPCGrid3D(hp);
+  const arr = pos.array as Float32Array;
+  const out = new Float32Array(nV);
+  for (let i = 0; i < nV; i++) {
+    const x = arr[i * 3];
+    const y = arr[i * 3 + 1];
+    const z = arr[i * 3 + 2];
+    const nn = nearestPointInGrid(grid, x, y, z);
+    out[i] = nn ? nn.dist : 0;
+  }
+  return out;
+}
+
+export function float32ToVertexColorRgb(
+  values: Float32Array,
+  globalMin: number,
+  globalMax: number,
+): Float32Array {
+  const n = values.length;
+  const rgb = new Float32Array(n * 3);
+  const lo = globalMin;
+  const hi = Math.max(lo + 1e-9, globalMax);
+  for (let i = 0; i < n; i++) {
+    const t = (values[i] - lo) / (hi - lo);
+    const g = Math.max(0, Math.min(1, 1 - t));
+    const r = Math.max(0, Math.min(1, t));
+    rgb[i * 3] = r;
+    rgb[i * 3 + 1] = g;
+    rgb[i * 3 + 2] = 0.15;
+  }
+  return rgb;
+}

server/assemblyInspectionJob.ts

@@ -0,0 +1,255 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as db from './db.js';
+import {
+  assignNearestPartAndStats,
+  computePartStatsFromPerPartDists,
+  computeVertexDistanceHeatmap,
+  float32ToVertexColorRgb,
+  loadStlToBVH,
+  perPartDistsFromAssignments,
+  type PartMeshBVH,
+} from './assemblyInspectionCompute.js';
+import { tryRunAssemblyNearestGpu } from './assemblyGpuNearest.js';
+import { sampleTaskPointclouds } from './sampleTaskPointclouds.js';
+import type { SampledPoint } from './pointcloudSample.js';
+import { runStepParseMvp, stepParseCacheDir } from './stepParse.js';
+import type { StepManifest } from './stepParse.js';
+
+const DATA_DIR = process.env.DATA_DIR || '/data';
+const TASKS_DIR = path.join(DATA_DIR, 'tasks');
+
+function resolveRunnerEntry(): string {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  if (process.env.NODE_ENV === 'production') {
+    return path.join(dir, 'assemblyInspectionJobRunner.js');
+  }
+  return path.join(dir, 'assemblyInspectionJobRunner.ts');
+}
+
+export function enqueueAssemblyInspectionJob(
+  resultId: number,
+  taskId: number,
+  options: AssemblyInspectionOptions,
+): void {
+  const script = resolveRunnerEntry();
+  const isProd = process.env.NODE_ENV === 'production';
+  const payload = JSON.stringify(options);
+  const child = fork(script, [String(resultId), String(taskId), payload], {
+    env: { ...process.env },
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+    execArgv: isProd ? [] : ['--import', 'tsx'],
+  });
+  child.on('error', (err) => console.error('[AssemblyInspection] fork 失败:', err));
+  child.on('exit', (code, signal) => {
+    if (code !== 0 && code != null) {
+      console.error(`[AssemblyInspection] 子进程退出 code=${code} signal=${signal ?? ''}`);
+    }
+  });
+}
+
+export type AssemblyInspectionOptions = {
+  cadFileId?: number;
+  samplePoints: number;
+  toleranceMm: number;
+  includeVertexHeatmap: boolean;
+};
+
+export async function runAssemblyInspectionJob(
+  resultId: number,
+  taskId: number,
+  options: AssemblyInspectionOptions,
+): Promise<void> {
+  const sampleBudget = Math.min(Math.max(10_000, options.samplePoints), 500_000);
+  const tol = options.toleranceMm > 0 ? options.toleranceMm : 0.3;
+
+  try {
+    await reportProgress(resultId, 0.08, '加载任务与 CAD…');
+    const task = await db.getInspectionTaskById(taskId);
+    if (!task) throw new Error('task not found');
+
+    const cadList = await db.listModelCadFiles(task.modelId);
+    const stepFiles = cadList.filter((f) => {
+      const ext = path.extname(f.name).toLowerCase();
+      return ext === '.stp' || ext === '.step' || f.format?.toLowerCase() === 'stp' || f.format?.toLowerCase() === 'step';
+    });
+    if (stepFiles.length === 0) {
+      throw new Error('该车型下未上传 STEP（.stp / .step）。请上传装配体 STEP 后再运行装配检测。');
+    }
+
+    let cad = stepFiles[0]!;
+    if (options.cadFileId != null) {
+      const found = stepFiles.find((f) => f.id === options.cadFileId);
+      if (!found) throw new Error('指定的 cadFileId 不是 STEP 文件或不存在');
+      cad = found;
+    }
+
+    if (!fs.existsSync(cad.filePath)) throw new Error('STEP 文件不存在');
+
+    const cacheDir = stepParseCacheDir(task.modelId, cad.id);
+    const manifestPath = path.join(cacheDir, 'manifest.json');
+
+    if (!fs.existsSync(manifestPath)) {
+      await reportProgress(resultId, 0.15, '解析 STEP（Python/cadquery，可能较慢）…');
+      runStepParseMvp(cad.filePath, cacheDir);
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as StepManifest;
+    if (!manifest.ok || !manifest.parts?.length) {
+      throw new Error('STEP manifest 无效');
+    }
+
+    await reportProgress(resultId, 0.35, '加载零件网格…');
+    const parts: PartMeshBVH[] = [];
+    for (const p of manifest.parts) {
+      const stlAbs = path.join(cacheDir, p.stlRelative);
+      if (!fs.existsSync(stlAbs)) throw new Error(`缺少零件 STL: ${p.stlRelative}`);
+      const buf = fs.readFileSync(stlAbs);
+      const { geometry, bvh } = loadStlToBVH(buf);
+      parts.push({ part: p, geometry, bvh });
+    }
+
+    await reportProgress(resultId, 0.45, '点云采样…');
+    const sampled = await sampleTaskPointclouds(taskId, sampleBudget);
+    if (sampled.length === 0) throw new Error('任务下无可用点云');
+
+    await reportProgress(resultId, 0.55, '最近零件归属与距离…');
+    const gpu = tryRunAssemblyNearestGpu(cacheDir, sampled);
+    let assignments: number[];
+    let pointDistances: number[];
+    let stats: ReturnType<typeof computePartStatsFromPerPartDists>;
+    if (gpu) {
+      assignments = gpu.assignments;
+      pointDistances = gpu.pointDistances;
+      stats = computePartStatsFromPerPartDists(
+        manifest.parts,
+        perPartDistsFromAssignments(parts.length, assignments, pointDistances),
+        tol,
+      );
+    } else {
+      const r = await assignNearestPartAndStats(parts, sampled, tol, {
+        onProgress: async (done, total) => {
+          const t = total > 0 ? done / total : 1;
+          await reportProgress(
+            resultId,
+            0.55 + 0.17 * t,
+            `最近零件归属与距离… ${done.toLocaleString()}/${total.toLocaleString()}`,
+          );
+        },
+      });
+      assignments = r.assignments;
+      pointDistances = r.pointDistances;
+      stats = r.stats;
+    }
+
+    const outDir = path.join(TASKS_DIR, String(taskId), 'analysis');
+    fs.mkdirSync(outDir, { recursive: true });
+
+    const partOutputs: Record<string, unknown>[] = [];
+    let gMin = Infinity;
+    let gMax = -Infinity;
+
+    const pointsByPart: SampledPoint[][] = Array.from({ length: parts.length }, () => []);
+    for (let i = 0; i < sampled.length; i++) {
+      pointsByPart[assignments[i]!]!.push(sampled[i]!);
+    }
+
+    for (const d of pointDistances) {
+      if (d < gMin) gMin = d;
+      if (d > gMax) gMax = d;
+    }
+    if (!Number.isFinite(gMin)) gMin = 0;
+    if (!Number.isFinite(gMax)) gMax = 0;
+
+    const meanAll =
+      pointDistances.length > 0 ? pointDistances.reduce((a, b) => a + b, 0) / pointDistances.length : 0;
+    let vsum = 0;
+    for (const d of pointDistances) {
+      const t = d - meanAll;
+      vsum += t * t;
+    }
+    const stdAll = pointDistances.length > 0 ? Math.sqrt(vsum / pointDistances.length) : 0;
+    let within = 0;
+    for (const d of pointDistances) {
+      if (d < tol) within++;
+    }
+
+    await reportProgress(resultId, 0.72, '汇总与可选顶点热力…');
+    for (let j = 0; j < parts.length; j++) {
+      const pm = parts[j]!;
+      const st = stats[j]!;
+      const entry: Record<string, unknown> = {
+        partId: st.partId,
+        name: st.name,
+        min: st.min,
+        max: st.max,
+        mean: st.mean,
+        stdDev: st.stdDev,
+        passRate: st.passRate,
+        pointCount: st.pointCount,
+      };
+
+      if (options.includeVertexHeatmap && st.pointCount > 0) {
+        const vals = computeVertexDistanceHeatmap(pm.geometry, pointsByPart[j]!);
+        if (vals) {
+          let vmin = Infinity;
+          let vmax = -Infinity;
+          for (let k = 0; k < vals.length; k++) {
+            if (vals[k]! < vmin) vmin = vals[k]!;
+            if (vals[k]! > vmax) vmax = vals[k]!;
+          }
+          const rgb = float32ToVertexColorRgb(vals, vmin, vmax);
+          const binName = `assembly_vertex_${resultId}_${st.partId}.bin`;
+          fs.writeFileSync(path.join(outDir, binName), Buffer.from(rgb.buffer));
+          entry.vertexHeatmapBin = binName;
+        }
+      }
+      partOutputs.push(entry);
+    }
+
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'completed',
+      errorStats: {
+        min: gMin,
+        max: gMax,
+        mean: meanAll,
+        stdDev: stdAll,
+        totalPoints: sampled.length,
+        withinTolerance: within,
+        outOfTolerance: sampled.length - within,
+      },
+      resultData: {
+        kind: 'assembly_inspection',
+        toleranceMm: tol,
+        cadFileId: cad.id,
+        modelId: task.modelId,
+        samplePoints: sampled.length,
+        parts: partOutputs,
+        manifestPathRelative: path.relative(DATA_DIR, manifestPath),
+      },
+    });
+    console.log(`[AssemblyInspection] ok resultId=${resultId} taskId=${taskId} parts=${parts.length}`);
+  } catch (err) {
+    console.error('[AssemblyInspection]', err);
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'error',
+      resultData: {
+        kind: 'assembly_inspection',
+        error: err instanceof Error ? err.message : String(err),
+      },
+    });
+  }
+}
+
+async function reportProgress(resultId: number, progress: number, stage: string): Promise<void> {
+  const p = Math.min(1, Math.max(0, progress));
+  await db.updateTaskAnalysisResult(resultId, {
+    resultData: {
+      kind: 'assembly_inspection',
+      progress: p,
+      stage,
+    },
+  });
+}

server/assemblyInspectionJobRunner.ts

@@ -0,0 +1,36 @@
+/**
+ * 子进程入口：装配检测（STEP + 最近零件 + 统计 / 可选顶点热力）
+ */
+import 'dotenv/config';
+import { runAssemblyInspectionJob, type AssemblyInspectionOptions } from './assemblyInspectionJob.js';
+
+const resultId = Number(process.argv[2]);
+const taskId = Number(process.argv[3]);
+const raw = process.argv[4] ?? '{}';
+
+if (!Number.isFinite(resultId) || !Number.isFinite(taskId) || resultId <= 0 || taskId <= 0) {
+  console.error('[AssemblyInspectionJobRunner] 参数: <resultId> <taskId> <jsonOptions>');
+  process.exit(1);
+}
+
+let options: AssemblyInspectionOptions;
+try {
+  options = JSON.parse(raw) as AssemblyInspectionOptions;
+} catch {
+  options = {
+    samplePoints: 100_000,
+    toleranceMm: 0.3,
+    includeVertexHeatmap: false,
+  };
+}
+
+if (options.samplePoints == null) options.samplePoints = 100_000;
+if (options.toleranceMm == null) options.toleranceMm = 0.3;
+if (options.includeVertexHeatmap == null) options.includeVertexHeatmap = false;
+
+runAssemblyInspectionJob(resultId, taskId, options)
+  .then(() => process.exit(0))
+  .catch((e) => {
+    console.error('[AssemblyInspectionJobRunner]', e);
+    process.exit(1);
+  });

server/auth.logout.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { appRouter } from "./routers";
+import { COOKIE_NAME } from "../shared/const";
+import type { TrpcContext } from "./_core/context";
+
+type CookieCall = {
+  name: string;
+  options: Record<string, unknown>;
+};
+
+type AuthenticatedUser = NonNullable<TrpcContext["user"]>;
+
+function createAuthContext(): { ctx: TrpcContext; clearedCookies: CookieCall[] } {
+  const clearedCookies: CookieCall[] = [];
+
+  const user: AuthenticatedUser = {
+    id: 1,
+    openId: "sample-user",
+    email: "sample@example.com",
+    name: "Sample User",
+    loginMethod: "manus",
+    role: "user",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    lastSignedIn: new Date(),
+  };
+
+  const ctx: TrpcContext = {
+    user,
+    req: {
+      protocol: "https",
+      headers: {},
+    } as TrpcContext["req"],
+    res: {
+      clearCookie: (name: string, options: Record<string, unknown>) => {
+        clearedCookies.push({ name, options });
+      },
+    } as TrpcContext["res"],
+  };
+
+  return { ctx, clearedCookies };
+}
+
+describe("auth.logout", () => {
+  it("clears the session cookie and reports success", async () => {
+    const { ctx, clearedCookies } = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.auth.logout();
+
+    expect(result).toEqual({ success: true });
+    expect(clearedCookies).toHaveLength(1);
+    expect(clearedCookies[0]?.name).toBe(COOKIE_NAME);
+    expect(clearedCookies[0]?.options).toMatchObject({
+      maxAge: -1,
+      secure: true,
+      sameSite: "none",
+      httpOnly: true,
+      path: "/",
+    });
+  });
+});

server/cadFilePick.ts

@@ -0,0 +1,33 @@
+import * as path from 'path';
+
+/** 与 DB model_cad_files / 上传接口一致的最小字段 */
+export type CadFileRow = {
+  format: string | null;
+  name: string;
+  filePath: string;
+};
+
+/**
+ * 解析扩展名：优先数据库 format，否则从文件名推断（避免 format 为空或录入错误）。
+ */
+export function resolveCadExtension(f: CadFileRow): string {
+  let ext = (f.format || '').trim().toLowerCase().replace(/^\./, '');
+  if (!ext && f.name) {
+    ext = path.extname(f.name).slice(1).toLowerCase();
+  }
+  return ext;
+}
+
+/**
+ * 平滑热力：优先 STL，其次 OBJ（与前端可加载格式对齐）。
+ */
+export function pickCadFileForHeatmap(
+  files: CadFileRow[],
+): { file: CadFileRow; ext: 'stl' | 'obj' } | null {
+  const withExt = files.map((file) => ({ file, ext: resolveCadExtension(file) }));
+  const stl = withExt.find((x) => x.ext === 'stl');
+  if (stl) return { file: stl.file, ext: 'stl' };
+  const obj = withExt.find((x) => x.ext === 'obj');
+  if (obj) return { file: obj.file, ext: 'obj' };
+  return null;
+}

server/cadHeatmapCompute.ts

@@ -0,0 +1,305 @@
+import { BufferGeometry, Group, Mesh, Vector3 } from 'three';
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
+import { mergeGeometries, mergeVertices } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import {
+  buildPCGrid3D,
+  CAD_HEATMAP_SHELL_OFFSET_FRAC,
+  displayDistanceRange,
+  displayErrorRangeSmoothHeatmap,
+  distanceToRgb,
+  errorToRgb,
+  medianNearestNeighbor3D,
+  nearestPointInGrid,
+  normalizePointsLikeViewer,
+  type HeatmapPoint,
+} from '../shared/cadHeatmapMath.js';
+import type { SampledPoint } from './pointcloudSample.js';
+
+/**
+ * 服务端平滑热力：默认「先求快、可接受稍粗网格」（与前端实时预览的 shared 常量可不同）。
+ * - CAD_HEATMAP_MAX_VERTICES：焊接后顶点上限（默认 60000；要更细可设 120000）。
+ * - CAD_HEATMAP_MEDIAN_NN_SAMPLES：尺度估计采样（默认 4096；要更稳可设 8192）。
+ */
+function parseHeatmapInt(envVal: string | undefined, fallback: number, min: number, max: number): number {
+  if (envVal == null || envVal === '') return fallback;
+  const n = Number(envVal);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(n)));
+}
+
+/** 默认偏快：约半顶点上限，merge 更早停 */
+const SERVER_FAST_DEFAULT_MAX_VERTICES = 60_000;
+const SERVER_FAST_DEFAULT_MEDIAN_NN = 4_096;
+
+const SERVER_MAX_VERTICES = parseHeatmapInt(
+  process.env.CAD_HEATMAP_MAX_VERTICES,
+  SERVER_FAST_DEFAULT_MAX_VERTICES,
+  8_000,
+  500_000,
+);
+const SERVER_MEDIAN_NN_SAMPLES = parseHeatmapInt(
+  process.env.CAD_HEATMAP_MEDIAN_NN_SAMPLES,
+  SERVER_FAST_DEFAULT_MEDIAN_NN,
+  512,
+  32_768,
+);
+
+function normalizeCadGeometryLikeViewer(geo: BufferGeometry): void {
+  geo.computeBoundingBox();
+  geo.center();
+  const box = geo.boundingBox;
+  if (box) {
+    const size = new Vector3();
+    box.getSize(size);
+    const maxDim = Math.max(size.x, size.y, size.z);
+    if (maxDim > 0) {
+      const s = 10 / maxDim;
+      geo.scale(s, s, s);
+    }
+  }
+}
+
+function buildHeatmapPoints(sampledPoints: SampledPoint[]): HeatmapPoint[] {
+  const pts: HeatmapPoint[] = sampledPoints.map((p) => ({
+    x: p.x,
+    y: p.y,
+    z: p.z,
+    error: p.error,
+  }));
+  normalizePointsLikeViewer(pts);
+  return pts;
+}
+
+function parseObjBufferToGeometry(buffer: Buffer): BufferGeometry | null {
+  const text = buffer.toString('utf8');
+  if (!text.trim()) return null;
+  const loader = new OBJLoader();
+  const group = loader.parse(text) as Group;
+  const geometries: BufferGeometry[] = [];
+  group.traverse((child) => {
+    if (child instanceof Mesh && child.geometry) {
+      geometries.push(child.geometry);
+    }
+  });
+  if (geometries.length === 0) return null;
+  if (geometries.length === 1) return geometries[0].clone();
+  try {
+    const merged = mergeGeometries(geometries, false);
+    if (merged) return merged;
+  } catch {
+    /* fall through */
+  }
+  return geometries[0].clone();
+}
+
+/**
+ * 对已解析的 BufferGeometry（尚未 normalizeCad）计算顶点色。
+ */
+function computeCadShellHeatmapCore(
+  geo: BufferGeometry,
+  pts: HeatmapPoint[],
+): { colors: Float32Array; dispMin: number; dispMax: number; vertexCount: number } | null {
+  normalizeCadGeometryLikeViewer(geo);
+
+  try {
+    mergeVertices(geo);
+  } catch {
+    /* ignore */
+  }
+  geo.computeVertexNormals();
+
+  let weldTol = 2e-4;
+  while (
+    geo.attributes.position &&
+    geo.attributes.position.count > SERVER_MAX_VERTICES &&
+    weldTol < 0.12
+  ) {
+    mergeVertices(geo, weldTol);
+    weldTol *= 1.85;
+    geo.computeVertexNormals();
+  }
+
+  const posAttr = geo.attributes.position;
+  const norAttr = geo.attributes.normal;
+  if (!posAttr || posAttr.count === 0) return null;
+
+  const nV = posAttr.count;
+  const pos = posAttr.array as Float32Array;
+  const nor = norAttr?.array as Float32Array | undefined;
+
+  const grid = buildPCGrid3D(pts);
+  const nnMed = medianNearestNeighbor3D(pts, grid, SERVER_MEDIAN_NN_SAMPLES);
+  const { minError: dispMin, maxError: dispMax } = displayErrorRangeSmoothHeatmap(pts);
+
+  geo.computeBoundingBox();
+  const bb = geo.boundingBox;
+  const diag = bb ? Math.hypot(bb.max.x - bb.min.x, bb.max.y - bb.min.y, bb.max.z - bb.min.z) : 1;
+  const maxBind = Math.max(nnMed * 14, diag * 0.045);
+  const shellOffset = Math.max(diag * CAD_HEATMAP_SHELL_OFFSET_FRAC, nnMed * 0.35);
+
+  const colors = new Float32Array(nV * 3);
+  const noData = [0.32, 0.34, 0.38] as const;
+
+  for (let i = 0; i < nV; i++) {
+    const i3 = i * 3;
+    const x = pos[i3];
+    const y = pos[i3 + 1];
+    const z = pos[i3 + 2];
+
+    const hit = nearestPointInGrid(grid, x, y, z);
+    if (!hit || hit.dist > maxBind) {
+      colors[i3] = noData[0];
+      colors[i3 + 1] = noData[1];
+      colors[i3 + 2] = noData[2];
+    } else {
+      const err = pts[hit.idx].error ?? 0;
+      const [r, g, b] = errorToRgb(err, dispMin, dispMax);
+      colors[i3] = r;
+      colors[i3 + 1] = g;
+      colors[i3 + 2] = b;
+    }
+
+    if (nor && nor.length >= nV * 3) {
+      pos[i3] = x + nor[i3] * shellOffset;
+      pos[i3 + 1] = y + nor[i3 + 1] * shellOffset;
+      pos[i3 + 2] = z + nor[i3 + 2] * shellOffset;
+    }
+  }
+
+  posAttr.needsUpdate = true;
+
+  return {
+    colors,
+    dispMin,
+    dispMax,
+    vertexCount: nV,
+  };
+}
+
+/**
+ * 在服务端对 STL 与（已采样的）测点做与前端一致的 CAD 壳热力，返回每顶点 RGB。
+ */
+export function computeCadShellHeatmapFromStl(
+  stlBuffer: Buffer,
+  sampledPoints: SampledPoint[],
+): { colors: Float32Array; dispMin: number; dispMax: number; vertexCount: number } | null {
+  if (sampledPoints.length < 1) return null;
+  const pts = buildHeatmapPoints(sampledPoints);
+
+  const u8 = new Uint8Array(stlBuffer);
+  const ab = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
+  const loader = new STLLoader();
+  const geo = loader.parse(ab);
+  return computeCadShellHeatmapCore(geo, pts);
+}
+
+/** OBJ（多 mesh 会尝试合并） */
+export function computeCadShellHeatmapFromObj(
+  objBuffer: Buffer,
+  sampledPoints: SampledPoint[],
+): { colors: Float32Array; dispMin: number; dispMax: number; vertexCount: number } | null {
+  if (sampledPoints.length < 1) return null;
+  const pts = buildHeatmapPoints(sampledPoints);
+  const geo = parseObjBufferToGeometry(objBuffer);
+  if (!geo) return null;
+  return computeCadShellHeatmapCore(geo, pts);
+}
+
+// ─── 偏差热力：用顶点到最近点的距离着色 ────────────────────────────────────────
+
+function computeDeviationHeatmapCore(
+  geo: BufferGeometry,
+  pts: HeatmapPoint[],
+): { colors: Float32Array; dispMin: number; dispMax: number; vertexCount: number } | null {
+  normalizeCadGeometryLikeViewer(geo);
+
+  // 不做 mergeVertices —— 保持与客户端 Three.js Loader 一致的非索引顶点布局，
+  // 使输出的颜色数组长度 == 客户端 rawCount，触发快速路径而非主线程 merge 卡死。
+  geo.computeVertexNormals();
+
+  const posAttr = geo.attributes.position;
+  const norAttr = geo.attributes.normal;
+  if (!posAttr || posAttr.count === 0) return null;
+
+  const nV = posAttr.count;
+  const pos = posAttr.array as Float32Array;
+  const nor = norAttr?.array as Float32Array | undefined;
+
+  const grid = buildPCGrid3D(pts);
+  const nnMed = medianNearestNeighbor3D(pts, grid, SERVER_MEDIAN_NN_SAMPLES);
+
+  geo.computeBoundingBox();
+  const bb = geo.boundingBox;
+  const diag = bb ? Math.hypot(bb.max.x - bb.min.x, bb.max.y - bb.min.y, bb.max.z - bb.min.z) : 1;
+  const maxBind = Math.max(nnMed * 14, diag * 0.045);
+  const shellOffset = Math.max(diag * CAD_HEATMAP_SHELL_OFFSET_FRAC, nnMed * 0.35);
+
+  const distances: number[] = [];
+  const vertexDists = new Float64Array(nV);
+
+  for (let i = 0; i < nV; i++) {
+    const i3 = i * 3;
+    const hit = nearestPointInGrid(grid, pos[i3], pos[i3 + 1], pos[i3 + 2]);
+    if (hit && hit.dist <= maxBind) {
+      vertexDists[i] = hit.dist;
+      distances.push(hit.dist);
+    } else {
+      vertexDists[i] = -1;
+    }
+  }
+
+  const { minDist: dispMin, maxDist: dispMax } = displayDistanceRange(distances);
+
+  const colors = new Float32Array(nV * 3);
+  const noData = [0.32, 0.34, 0.38] as const;
+
+  for (let i = 0; i < nV; i++) {
+    const i3 = i * 3;
+    const d = vertexDists[i];
+    if (d < 0) {
+      colors[i3] = noData[0];
+      colors[i3 + 1] = noData[1];
+      colors[i3 + 2] = noData[2];
+    } else {
+      const [r, g, b] = distanceToRgb(d, dispMin, dispMax);
+      colors[i3] = r;
+      colors[i3 + 1] = g;
+      colors[i3 + 2] = b;
+    }
+
+    if (nor && nor.length >= nV * 3) {
+      pos[i3] = pos[i3] + nor[i3] * shellOffset;
+      pos[i3 + 1] = pos[i3 + 1] + nor[i3 + 1] * shellOffset;
+      pos[i3 + 2] = pos[i3 + 2] + nor[i3 + 2] * shellOffset;
+    }
+  }
+
+  posAttr.needsUpdate = true;
+
+  return { colors, dispMin, dispMax, vertexCount: nV };
+}
+
+export function computeDeviationHeatmapFromStl(
+  stlBuffer: Buffer,
+  sampledPoints: SampledPoint[],
+): { colors: Float32Array; dispMin: number; dispMax: number; vertexCount: number } | null {
+  if (sampledPoints.length < 1) return null;
+  const pts = buildHeatmapPoints(sampledPoints);
+  const u8 = new Uint8Array(stlBuffer);
+  const ab = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
+  const loader = new STLLoader();
+  const geo = loader.parse(ab);
+  return computeDeviationHeatmapCore(geo, pts);
+}
+
+export function computeDeviationHeatmapFromObj(
+  objBuffer: Buffer,
+  sampledPoints: SampledPoint[],
+): { colors: Float32Array; dispMin: number; dispMax: number; vertexCount: number } | null {
+  if (sampledPoints.length < 1) return null;
+  const pts = buildHeatmapPoints(sampledPoints);
+  const geo = parseObjBufferToGeometry(objBuffer);
+  if (!geo) return null;
+  return computeDeviationHeatmapCore(geo, pts);
+}

server/db.ts

@@ -0,0 +1,388 @@
+import { eq, desc, sql } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/mysql2";
+import type { ResultSetHeader } from "mysql2";
+import {
+  users, InsertUser,
+  vehicleSeries, InsertVehicleSeries, VehicleSeries,
+  vehicleModels, InsertVehicleModel, VehicleModel,
+  modelCadFiles, InsertModelCadFile, ModelCadFile,
+  taskCadFiles, InsertTaskCadFile, TaskCadFile,
+  inspectionTasks, InsertInspectionTask, InspectionTask,
+  taskPointcloudFiles, InsertTaskPointcloudFile, TaskPointcloudFile,
+  taskAnalysisResults, InsertTaskAnalysisResult, TaskAnalysisResult,
+} from "../drizzle/schema";
+import { ENV } from './_core/env';
+
+let _db: ReturnType<typeof drizzle> | null = null;
+
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+/** drizzle mysql2 insert resolves to mysql2 ResultSetHeader with insertId (not result[0].insertId). */
+function getMysqlInsertId(result: unknown): number {
+  const r = result as ResultSetHeader & { 0?: ResultSetHeader };
+  if (typeof r.insertId === "number" && r.insertId > 0) return r.insertId;
+  if (r[0] && typeof r[0].insertId === "number") return r[0].insertId;
+  throw new Error("insertId missing from insert result");
+}
+
+/**
+ * Clears the cached pool so the next getDb() creates a new connection.
+ * Call after ECONNREFUSED / PROTOCOL_CONNECTION_LOST so retries can recover.
+ */
+export function invalidateDb() {
+  _db = null;
+}
+
+/**
+ * Returns the drizzle DB instance, creating it if needed.
+ * Retries the initial TCP probe while MySQL is still starting (common in Docker).
+ */
+export async function getDb() {
+  if (_db) return _db;
+  if (!process.env.DATABASE_URL) return null;
+
+  const maxAttempts = 40;
+  const delayMs = 500;
+  // One drizzle instance / pool; retry execute only (avoids leaking a pool per attempt).
+  const instance = drizzle(process.env.DATABASE_URL);
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await instance.execute(sql`SELECT 1`);
+      _db = instance;
+      if (attempt > 1) {
+        console.log(`[Database] Connected after ${attempt} attempt(s).`);
+      }
+      return _db;
+    } catch (error: any) {
+      const msg = error?.message ?? String(error);
+      const retriable =
+        error?.code === "ECONNREFUSED" ||
+        error?.code === "ETIMEDOUT" ||
+        error?.code === "ENOTFOUND" ||
+        msg.includes("connect");
+
+      if (attempt < maxAttempts && retriable) {
+        if (attempt === 1 || attempt % 5 === 0) {
+          console.warn(`[Database] Waiting for MySQL... (${attempt}/${maxAttempts}) ${msg}`);
+        }
+        await sleep(delayMs);
+        continue;
+      }
+      console.error("[Database] Giving up:", msg);
+      _db = null;
+      return null;
+    }
+  }
+  return null;
+}
+
+// ─── 用户 ─────────────────────────────────────────────────────────────────────
+
+export async function upsertUser(user: InsertUser): Promise<void> {
+  if (!user.openId) throw new Error("User openId is required for upsert");
+
+  const db = await getDb();
+  if (!db) {
+    console.warn("[Database] Cannot upsert user: database not available");
+    return;
+  }
+
+  try {
+    const values: InsertUser = { openId: user.openId };
+    const updateSet: Record<string, unknown> = {};
+
+    const textFields = ["name", "email", "loginMethod"] as const;
+    type TextField = (typeof textFields)[number];
+
+    const assignNullable = (field: TextField) => {
+      const value = user[field];
+      if (value === undefined) return;
+      const normalized = value ?? null;
+      values[field] = normalized;
+      updateSet[field] = normalized;
+    };
+    textFields.forEach(assignNullable);
+
+    if (user.lastSignedIn !== undefined) {
+      values.lastSignedIn = user.lastSignedIn;
+      updateSet.lastSignedIn = user.lastSignedIn;
+    }
+    if (user.role !== undefined) {
+      values.role = user.role;
+      updateSet.role = user.role;
+    } else if (user.openId === ENV.ownerOpenId) {
+      values.role = 'admin';
+      updateSet.role = 'admin';
+    }
+
+    if (!values.lastSignedIn) values.lastSignedIn = new Date();
+    if (Object.keys(updateSet).length === 0) updateSet.lastSignedIn = new Date();
+
+    await db.insert(users).values(values).onDuplicateKeyUpdate({ set: updateSet });
+  } catch (error) {
+    console.error("[Database] Failed to upsert user:", error);
+    throw error;
+  }
+}
+
+export async function getUserByOpenId(openId: string) {
+  const db = await getDb();
+  if (!db) return undefined;
+  const result = await db.select().from(users).where(eq(users.openId, openId)).limit(1);
+  return result[0];
+}
+
+// ─── 车系 ─────────────────────────────────────────────────────────────────────
+
+export async function createVehicleSeries(data: InsertVehicleSeries): Promise<VehicleSeries> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(vehicleSeries).values(data);
+  const [row] = await db.select().from(vehicleSeries).where(eq(vehicleSeries.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listVehicleSeries(): Promise<VehicleSeries[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(vehicleSeries).orderBy(desc(vehicleSeries.createdAt));
+}
+
+export async function updateVehicleSeries(id: number, data: Partial<InsertVehicleSeries>): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.update(vehicleSeries).set(data).where(eq(vehicleSeries.id, id));
+}
+
+export async function deleteVehicleSeries(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(vehicleSeries).where(eq(vehicleSeries.id, id));
+}
+
+// ─── 车型 ─────────────────────────────────────────────────────────────────────
+
+export async function createVehicleModel(data: InsertVehicleModel): Promise<VehicleModel> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(vehicleModels).values(data);
+  const [row] = await db.select().from(vehicleModels).where(eq(vehicleModels.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listVehicleModelsBySeries(seriesId: number): Promise<VehicleModel[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(vehicleModels)
+    .where(eq(vehicleModels.seriesId, seriesId))
+    .orderBy(desc(vehicleModels.createdAt));
+}
+
+export async function getVehicleModelById(id: number): Promise<VehicleModel | undefined> {
+  const db = await getDb();
+  if (!db) return undefined;
+  const [row] = await db.select().from(vehicleModels).where(eq(vehicleModels.id, id));
+  return row;
+}
+
+export async function updateVehicleModel(id: number, data: Partial<InsertVehicleModel>): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.update(vehicleModels).set(data).where(eq(vehicleModels.id, id));
+}
+
+export async function deleteVehicleModel(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(vehicleModels).where(eq(vehicleModels.id, id));
+}
+
+// ─── 车型 CAD 文件 ─────────────────────────────────────────────────────────────
+
+export async function createModelCadFile(data: InsertModelCadFile): Promise<ModelCadFile> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(modelCadFiles).values(data);
+  const [row] = await db.select().from(modelCadFiles).where(eq(modelCadFiles.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listModelCadFiles(modelId: number): Promise<ModelCadFile[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(modelCadFiles)
+    .where(eq(modelCadFiles.modelId, modelId))
+    .orderBy(desc(modelCadFiles.createdAt));
+}
+
+export async function getModelCadFileById(id: number): Promise<ModelCadFile | undefined> {
+  const db = await getDb();
+  if (!db) return undefined;
+  const [row] = await db.select().from(modelCadFiles).where(eq(modelCadFiles.id, id));
+  return row;
+}
+
+export async function deleteModelCadFile(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(modelCadFiles).where(eq(modelCadFiles.id, id));
+}
+
+// ─── 任务 CAD 文件 ─────────────────────────────────────────────────────────────
+
+export async function createTaskCadFile(data: InsertTaskCadFile): Promise<TaskCadFile> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(taskCadFiles).values(data);
+  const [row] = await db.select().from(taskCadFiles).where(eq(taskCadFiles.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listTaskCadFiles(taskId: number): Promise<TaskCadFile[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(taskCadFiles)
+    .where(eq(taskCadFiles.taskId, taskId))
+    .orderBy(taskCadFiles.createdAt);
+}
+
+export async function getTaskCadFileById(id: number): Promise<TaskCadFile | undefined> {
+  const db = await getDb();
+  if (!db) return undefined;
+  const [row] = await db.select().from(taskCadFiles).where(eq(taskCadFiles.id, id));
+  return row;
+}
+
+export async function deleteTaskCadFile(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(taskCadFiles).where(eq(taskCadFiles.id, id));
+}
+
+// ─── 检测任务 ─────────────────────────────────────────────────────────────────
+
+export async function createInspectionTask(data: InsertInspectionTask): Promise<InspectionTask> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(inspectionTasks).values(data);
+  const [row] = await db.select().from(inspectionTasks).where(eq(inspectionTasks.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listInspectionTasksByModel(modelId: number): Promise<InspectionTask[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(inspectionTasks)
+    .where(eq(inspectionTasks.modelId, modelId))
+    .orderBy(desc(inspectionTasks.createdAt));
+}
+
+export async function getInspectionTaskById(id: number): Promise<InspectionTask | undefined> {
+  const db = await getDb();
+  if (!db) return undefined;
+  const [row] = await db.select().from(inspectionTasks).where(eq(inspectionTasks.id, id));
+  return row;
+}
+
+export async function updateInspectionTask(id: number, data: Partial<InsertInspectionTask>): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.update(inspectionTasks).set(data).where(eq(inspectionTasks.id, id));
+}
+
+export async function deleteInspectionTask(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(inspectionTasks).where(eq(inspectionTasks.id, id));
+}
+
+// ─── 任务点云文件 ──────────────────────────────────────────────────────────────
+
+export async function createTaskPointcloudFile(data: InsertTaskPointcloudFile): Promise<TaskPointcloudFile> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(taskPointcloudFiles).values(data);
+  const [row] = await db.select().from(taskPointcloudFiles).where(eq(taskPointcloudFiles.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listTaskPointcloudFiles(taskId: number): Promise<TaskPointcloudFile[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(taskPointcloudFiles)
+    .where(eq(taskPointcloudFiles.taskId, taskId))
+    .orderBy(taskPointcloudFiles.createdAt);
+}
+
+export async function deleteTaskPointcloudFile(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(taskPointcloudFiles).where(eq(taskPointcloudFiles.id, id));
+}
+
+// ─── 任务分析结果 ──────────────────────────────────────────────────────────────
+
+export async function createTaskAnalysisResult(data: InsertTaskAnalysisResult): Promise<TaskAnalysisResult> {
+  const db = await getDb();
+  if (!db) throw new Error("Database not available");
+  const result = await db.insert(taskAnalysisResults).values(data);
+  const [row] = await db.select().from(taskAnalysisResults).where(eq(taskAnalysisResults.id, getMysqlInsertId(result)));
+  return row;
+}
+
+export async function listTaskAnalysisResults(taskId: number): Promise<TaskAnalysisResult[]> {
+  const db = await getDb();
+  if (!db) return [];
+  return db.select().from(taskAnalysisResults)
+    .where(eq(taskAnalysisResults.taskId, taskId))
+    .orderBy(desc(taskAnalysisResults.createdAt));
+}
+
+export async function getTaskAnalysisResultById(id: number): Promise<TaskAnalysisResult | undefined> {
+  const db = await getDb();
+  if (!db) return undefined;
+  const [row] = await db.select().from(taskAnalysisResults).where(eq(taskAnalysisResults.id, id));
+  return row;
+}
+
+export async function updateTaskAnalysisResult(id: number, data: Partial<InsertTaskAnalysisResult>): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.update(taskAnalysisResults).set(data).where(eq(taskAnalysisResults.id, id));
+}
+
+/**
+ * 非破坏性局部更新 task_analysis_results.resultData。
+ * 与 updateTaskAnalysisResult(resultData) 不同——后者会把整个 JSON 列覆写，
+ * 适合「最终结果」；本函数把 patch 合并到现有 JSON 上，适合
+ * 子进程频繁上报进度的场景（例如算法插件 progress / stage）。
+ *
+ * 实现策略：先读取一次再 set 写回；并发更新时按「最后写入者获胜」处理，
+ * 对进度上报来说足够安全（覆盖丢失最多 1~2 个心跳）。
+ */
+export async function patchTaskAnalysisResultData(
+  id: number,
+  patch: Record<string, unknown>,
+): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  const existing = await getTaskAnalysisResultById(id);
+  if (!existing) return;
+  const prev = (existing.resultData as Record<string, unknown> | null) ?? {};
+  const merged: Record<string, unknown> = { ...prev };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) continue;
+    merged[k] = v;
+  }
+  await db
+    .update(taskAnalysisResults)
+    .set({ resultData: merged })
+    .where(eq(taskAnalysisResults.id, id));
+}
+
+export async function deleteTaskAnalysisResult(id: number): Promise<void> {
+  const db = await getDb();
+  if (!db) return;
+  await db.delete(taskAnalysisResults).where(eq(taskAnalysisResults.id, id));
+}

server/deviationGpuCompute.ts

@@ -0,0 +1,121 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { SampledPoint } from './pointcloudSample.js';
+
+function scriptPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(here, '..', 'scripts', 'deviation_heatmap_gpu.py');
+}
+
+function resolvePython3(): string {
+  const fromEnv = process.env.PYTHON3_PATH?.trim();
+  if (fromEnv) return fromEnv;
+  for (const p of ['/usr/bin/python3', '/usr/local/bin/python3']) {
+    try {
+      if (fs.existsSync(p)) return p;
+    } catch {
+      /* ignore */
+    }
+  }
+  return 'python3';
+}
+
+export function deviationGpuEnabled(): boolean {
+  const v = process.env.ASSEMBLY_USE_GPU?.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+export type GpuDeviationResult = {
+  colors: Float32Array;
+  vertexCount: number;
+  dispMin: number;
+  dispMax: number;
+};
+
+/**
+ * 调用 scripts/deviation_heatmap_gpu.py（PyTorch CUDA KNN）。
+ * 返回 null 时由调用方回退 CPU。
+ */
+export function tryRunDeviationGpu(
+  cadFilePath: string,
+  sampled: SampledPoint[],
+): GpuDeviationResult | null {
+  if (!deviationGpuEnabled()) return null;
+  const script = scriptPath();
+  if (!fs.existsSync(script)) return null;
+  if (sampled.length === 0) return null;
+
+  const py = resolvePython3();
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dev-gpu-'));
+  const ptsFile = path.join(tmp, 'points.bin');
+  const buf = Buffer.allocUnsafe(sampled.length * 12);
+  for (let i = 0; i < sampled.length; i++) {
+    const o = i * 12;
+    buf.writeFloatLE(sampled[i]!.x, o);
+    buf.writeFloatLE(sampled[i]!.y, o + 4);
+    buf.writeFloatLE(sampled[i]!.z, o + 8);
+  }
+  fs.writeFileSync(ptsFile, buf);
+
+  try {
+    const r = spawnSync(
+      py,
+      [script, '--cad', cadFilePath, '--points', ptsFile, '--out-dir', tmp],
+      {
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: 30 * 60 * 1000,
+        env: { ...process.env, PYTHONUNBUFFERED: '1' },
+      },
+    );
+
+    if (r.error) {
+      console.warn('[DeviationGPU]', r.error.message);
+      return null;
+    }
+    if (r.status === 2) {
+      console.warn('[DeviationGPU] 回退 CPU：', (r.stdout || '').trim().slice(-500) || 'exit 2');
+      return null;
+    }
+    if (r.status !== 0) {
+      console.warn('[DeviationGPU] 失败 status=', r.status, (r.stderr || r.stdout || '').slice(0, 800));
+      return null;
+    }
+
+    const resultJsonPath = path.join(tmp, 'result.json');
+    if (!fs.existsSync(resultJsonPath)) return null;
+    const meta = JSON.parse(fs.readFileSync(resultJsonPath, 'utf-8')) as {
+      ok?: boolean;
+      vertexCount?: number;
+      dispMin?: number;
+      dispMax?: number;
+    };
+    if (!meta.ok || !meta.vertexCount) return null;
+
+    const colorsPath = path.join(tmp, 'colors.bin');
+    if (!fs.existsSync(colorsPath)) return null;
+    const cBuf = fs.readFileSync(colorsPath);
+    const expectedBytes = meta.vertexCount * 3 * 4;
+    if (cBuf.length !== expectedBytes) {
+      console.warn('[DeviationGPU] colors.bin 长度异常', cBuf.length, '!=', expectedBytes);
+      return null;
+    }
+    const colors = new Float32Array(cBuf.buffer, cBuf.byteOffset, meta.vertexCount * 3);
+
+    return {
+      colors,
+      vertexCount: meta.vertexCount,
+      dispMin: meta.dispMin ?? 0,
+      dispMax: meta.dispMax ?? 1,
+    };
+  } finally {
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+}

server/deviationHeatmapJob.ts

@@ -0,0 +1,132 @@
+import * as fs from 'fs';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import * as db from './db.js';
+import {
+  computeDeviationHeatmapFromObj,
+  computeDeviationHeatmapFromStl,
+} from './cadHeatmapCompute.js';
+import { pickCadFileForHeatmap } from './cadFilePick.js';
+import { sampleTaskPointclouds } from './sampleTaskPointclouds.js';
+import { deviationGpuEnabled, tryRunDeviationGpu } from './deviationGpuCompute.js';
+
+const DATA_DIR = process.env.DATA_DIR || '/data';
+const TASKS_DIR = path.join(DATA_DIR, 'tasks');
+
+async function reportProgress(resultId: number, progress: number, stage: string): Promise<void> {
+  const p = Math.min(1, Math.max(0, progress));
+  await db.updateTaskAnalysisResult(resultId, {
+    resultData: {
+      kind: 'obj_deviation',
+      progress: p,
+      stage,
+    },
+  });
+}
+
+function resolveRunnerEntry(): string {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  if (process.env.NODE_ENV === 'production') {
+    return path.join(dir, 'deviationHeatmapJobRunner.js');
+  }
+  return path.join(dir, 'deviationHeatmapJobRunner.ts');
+}
+
+export function enqueueDeviationHeatmapJob(resultId: number, taskId: number, totalPoints: number): void {
+  const script = resolveRunnerEntry();
+  const isProd = process.env.NODE_ENV === 'production';
+  const child = fork(script, [String(resultId), String(taskId), String(totalPoints)], {
+    env: { ...process.env },
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+    execArgv: isProd ? [] : ['--import', 'tsx'],
+  });
+  child.on('error', (err) => {
+    console.error('[DeviationHeatmapJob] fork 失败:', err);
+  });
+  child.on('exit', (code, signal) => {
+    if (code !== 0 && code != null) {
+      console.error(`[DeviationHeatmapJob] 子进程退出 code=${code} signal=${signal ?? ''}`);
+    }
+  });
+}
+
+export async function runDeviationHeatmapJob(resultId: number, taskId: number, totalPoints: number): Promise<void> {
+  try {
+    await reportProgress(resultId, 0.06, '加载任务与 CAD…');
+    const task = await db.getInspectionTaskById(taskId);
+    if (!task) throw new Error('task not found');
+
+    const cadFiles = await db.listModelCadFiles(task.modelId);
+    const picked = pickCadFileForHeatmap(cadFiles);
+    if (!picked) {
+      throw new Error(
+        '当前车型下未找到 STL 或 OBJ 的 CAD。请在与该检测任务相同的车型下上传 CAD，或确认文件扩展名为 .stl / .obj',
+      );
+    }
+    if (!fs.existsSync(picked.file.filePath)) throw new Error('CAD 文件不存在');
+
+    await reportProgress(resultId, 0.14, '点云采样中…');
+    const allPoints = await sampleTaskPointclouds(taskId, totalPoints);
+    if (allPoints.length === 0) throw new Error('任务下无可用点云采样');
+
+    // ── GPU 路径 ──────────────────────────────────────────────────────
+    let computed: { colors: Float32Array; vertexCount: number; dispMin: number; dispMax: number } | null = null;
+
+    if (deviationGpuEnabled()) {
+      await reportProgress(resultId, 0.42, '尝试 GPU 加速计算偏差…');
+      console.log('[DeviationHeatmapJob] GPU enabled, trying CUDA path…');
+      const gpuResult = tryRunDeviationGpu(picked.file.filePath, allPoints);
+      if (gpuResult) {
+        console.log(`[DeviationHeatmapJob] GPU 完成: verts=${gpuResult.vertexCount}`);
+        computed = gpuResult;
+      } else {
+        console.warn('[DeviationHeatmapJob] GPU 不可用，回退 CPU');
+      }
+    }
+
+    // ── CPU 回退 ──────────────────────────────────────────────────────
+    if (!computed) {
+      await reportProgress(resultId, 0.42, '计算偏差并着色（CPU，耗时较长）…');
+      const cadBuf = fs.readFileSync(picked.file.filePath);
+      computed =
+        picked.ext === 'stl'
+          ? computeDeviationHeatmapFromStl(cadBuf, allPoints)
+          : computeDeviationHeatmapFromObj(cadBuf, allPoints);
+    }
+    if (!computed) throw new Error('偏差热力计算失败');
+
+    await reportProgress(resultId, 0.88, '写入缓存文件…');
+    const outDir = path.join(TASKS_DIR, String(taskId), 'analysis');
+    fs.mkdirSync(outDir, { recursive: true });
+    const binName = `deviation_${resultId}.bin`;
+    const binPath = path.join(outDir, binName);
+    fs.writeFileSync(
+      binPath,
+      Buffer.from(computed.colors.buffer, computed.colors.byteOffset, computed.colors.byteLength),
+    );
+
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'completed',
+      resultData: {
+        kind: 'obj_deviation',
+        vertexCount: computed.vertexCount,
+        dispMin: computed.dispMin,
+        dispMax: computed.dispMax,
+        binName,
+      },
+    });
+    console.log(
+      `[DeviationHeatmapJob] ok resultId=${resultId} taskId=${taskId} verts=${computed.vertexCount}`,
+    );
+  } catch (err) {
+    console.error('[DeviationHeatmapJob]', err);
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'error',
+      resultData: {
+        kind: 'obj_deviation',
+        error: err instanceof Error ? err.message : String(err),
+      },
+    });
+  }
+}

server/deviationHeatmapJobRunner.ts

@@ -0,0 +1,21 @@
+import 'dotenv/config';
+import { runDeviationHeatmapJob } from './deviationHeatmapJob.js';
+
+const [, , a, b, c] = process.argv;
+const resultId = Number(a);
+const taskId = Number(b);
+const totalPoints = Number(c);
+
+if (!Number.isFinite(resultId) || !Number.isFinite(taskId) || resultId <= 0 || taskId <= 0) {
+  console.error('[DeviationHeatmapJobRunner] 用法: <resultId> <taskId> <totalPoints>');
+  process.exit(1);
+}
+
+const pts = Number.isFinite(totalPoints) && totalPoints > 0 ? totalPoints : 400_000;
+
+runDeviationHeatmapJob(resultId, taskId, pts)
+  .then(() => process.exit(0))
+  .catch((e) => {
+    console.error('[DeviationHeatmapJobRunner]', e);
+    process.exit(1);
+  });

server/fileRoutes.ts

@@ -0,0 +1,421 @@
+import { Router } from 'express';
+import * as fs from 'fs';
+import * as path from 'path';
+import multer from 'multer';
+import * as db from './db';
+import { samplePointcloudFile, type SampledPoint } from './pointcloudSample.js';
+import { forceReload as reloadPluginRegistry } from './plugins/registry.js';
+
+const router = Router();
+
+const DATA_DIR = process.env.DATA_DIR || '/data';
+const MODELS_DIR = path.join(DATA_DIR, 'models');
+const TASKS_DIR  = path.join(DATA_DIR, 'tasks');
+
+function ensureDir(dir: string) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+ensureDir(MODELS_DIR);
+ensureDir(TASKS_DIR);
+
+// ─── multer：流式写盘，避免大文件撑爆内存 ────────────────────────────────────
+
+const diskStorage = multer.diskStorage({
+  destination: (req, _file, cb) => {
+    let dir: string;
+    if (req.params.modelId) {
+      dir = path.join(MODELS_DIR, String(parseInt(req.params.modelId, 10)), 'cad');
+    } else if (req.params.taskId && req.path.includes('/task-cad/')) {
+      dir = path.join(TASKS_DIR, String(parseInt(req.params.taskId, 10)), 'cad');
+    } else if (req.params.taskId) {
+      dir = path.join(TASKS_DIR, String(parseInt(req.params.taskId, 10)), 'pointcloud');
+    } else {
+      dir = TASKS_DIR;
+    }
+    ensureDir(dir);
+    cb(null, dir);
+  },
+  filename: (_req, file, cb) => {
+    cb(null, file.originalname);
+  },
+});
+
+const diskUpload = multer({
+  storage: diskStorage,
+  limits: { fileSize: 5 * 1024 * 1024 * 1024 }, // 5 GB
+});
+
+// ─── 工具函数 ─────────────────────────────────────────────────────────────────
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return bytes + ' B';
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  if (bytes < 1024 * 1024 * 1024) return (bytes / 1e6).toFixed(1) + ' MB';
+  return (bytes / 1e9).toFixed(2) + ' GB';
+}
+
+function safeResolve(base: string, filename: string): string | null {
+  const resolved = path.resolve(base, decodeURIComponent(filename));
+  return resolved.startsWith(path.resolve(base)) ? resolved : null;
+}
+
+// ─── 车型 CAD 文件上传 ────────────────────────────────────────────────────────
+// POST /api/files/upload/cad/:modelId
+// multipart/form-data  field: file
+
+router.post('/upload/cad/:modelId', diskUpload.single('file'), async (req, res) => {
+  const modelId = parseInt(req.params.modelId, 10);
+  if (!req.file || isNaN(modelId)) {
+    return res.status(400).json({ success: false, error: 'Missing file or modelId' });
+  }
+
+  const destPath = req.file.path;
+  const format = path.extname(req.file.originalname).slice(1).toLowerCase();
+  const record = await db.createModelCadFile({
+    modelId,
+    name: req.file.originalname,
+    format,
+    fileSize: req.file.size,
+    filePath: destPath,
+  });
+
+  res.json({
+    success: true,
+    file: {
+      id: record.id,
+      name: record.name,
+      format: format.toUpperCase(),
+      size: formatFileSize(record.fileSize),
+      filePath: record.filePath,
+    },
+  });
+});
+
+// ─── 任务 CAD 文件上传 ────────────────────────────────────────────────────────
+// POST /api/files/upload/task-cad/:taskId
+
+router.post('/upload/task-cad/:taskId', diskUpload.single('file'), async (req, res) => {
+  const taskId = parseInt(req.params.taskId, 10);
+  if (!req.file || isNaN(taskId)) {
+    return res.status(400).json({ success: false, error: 'Missing file or taskId' });
+  }
+
+  const destPath = req.file.path;
+  const format = path.extname(req.file.originalname).slice(1).toLowerCase();
+  const record = await db.createTaskCadFile({
+    taskId,
+    name: req.file.originalname,
+    format,
+    fileSize: req.file.size,
+    filePath: destPath,
+  });
+
+  res.json({
+    success: true,
+    file: {
+      id: record.id,
+      name: record.name,
+      format: format.toUpperCase(),
+      size: formatFileSize(record.fileSize),
+      filePath: record.filePath,
+    },
+  });
+});
+
+// ─── 读取任务 CAD 文件 ────────────────────────────────────────────────────────
+// GET /api/files/read/task-cad/:taskId/:filename
+
+router.get('/read/task-cad/:taskId/:filename', (req, res) => {
+  const cadDir = path.join(TASKS_DIR, req.params.taskId, 'cad');
+  const filePath = safeResolve(cadDir, req.params.filename);
+  if (!filePath) return res.status(403).json({ error: 'Access denied' });
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'File not found' });
+  res.sendFile(filePath);
+});
+
+// ─── 任务点云文件上传 ─────────────────────────────────────────────────────────
+// POST /api/files/upload/pointcloud/:taskId
+
+router.post('/upload/pointcloud/:taskId', diskUpload.single('file'), async (req, res) => {
+  const taskId = parseInt(req.params.taskId, 10);
+  if (!req.file || isNaN(taskId)) {
+    return res.status(400).json({ success: false, error: 'Missing file or taskId' });
+  }
+
+  const destPath = req.file.path;
+  const record = await db.createTaskPointcloudFile({
+    taskId,
+    name: req.file.originalname,
+    fileSize: req.file.size,
+    filePath: destPath,
+  });
+
+  res.json({
+    success: true,
+    file: {
+      id: record.id,
+      name: record.name,
+      size: formatFileSize(record.fileSize),
+      filePath: record.filePath,
+    },
+  });
+});
+
+// ─── 读取 CAD 文件 ─────────────────────────────────────────────────────────────
+// GET /api/files/read/cad/:modelId/:filename
+
+router.get('/read/cad/:modelId/:filename', (req, res) => {
+  const cadDir = path.join(MODELS_DIR, req.params.modelId, 'cad');
+  const filePath = safeResolve(cadDir, req.params.filename);
+  if (!filePath) return res.status(403).json({ error: 'Access denied' });
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'File not found' });
+  res.sendFile(filePath);
+});
+
+// ─── 读取点云文件 ─────────────────────────────────────────────────────────────
+// GET /api/files/read/pointcloud/:taskId/:filename
+
+router.get('/read/pointcloud/:taskId/:filename', (req, res) => {
+  const pcDir = path.join(TASKS_DIR, req.params.taskId, 'pointcloud');
+  const filePath = safeResolve(pcDir, req.params.filename);
+  if (!filePath) return res.status(403).json({ error: 'Access denied' });
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'File not found' });
+  res.sendFile(filePath);
+});
+
+// ─── 删除 CAD 文件 ─────────────────────────────────────────────────────────────
+// DELETE /api/files/delete/cad/:id
+
+router.delete('/delete/cad/:id', async (req, res) => {
+  const id = parseInt(req.params.id, 10);
+  if (isNaN(id)) return res.status(400).json({ success: false, error: 'Invalid id' });
+
+  const files = await db.listModelCadFiles(0); // won't use this—fetch by id instead
+  // Use the filePath stored in DB record via listModelCadFiles won't work for single id.
+  // So we just delete the DB record; actual file cleanup optional.
+  // For a cleaner approach, expose a getModelCadFileById in db or accept filePath from client.
+  // Here we simply delete the DB record; the file remains until model is deleted.
+  await db.deleteModelCadFile(id);
+  res.json({ success: true });
+});
+
+// ─── 删除点云文件 ─────────────────────────────────────────────────────────────
+// DELETE /api/files/delete/pointcloud/:id
+
+router.delete('/delete/pointcloud/:id', async (req, res) => {
+  const id = parseInt(req.params.id, 10);
+  if (isNaN(id)) return res.status(400).json({ success: false, error: 'Invalid id' });
+  await db.deleteTaskPointcloudFile(id);
+  res.json({ success: true });
+});
+
+// ─── 批量采样接口 ─────────────────────────────────────────────────────────────
+// POST /api/files/sample/batch
+// Body: { taskId: number, totalPoints?: number }
+//   or  { filePaths: string[], totalPoints?: number }   （内部绝对路径，需认证）
+
+router.post('/sample/batch', async (req, res) => {
+  const { taskId, filePaths: rawPaths, totalPoints = 1000000, fileIds } = req.body as {
+    taskId?: number;
+    filePaths?: string[];
+    totalPoints?: number;
+    /** 可选：只采样指定 ID 的文件（按 task_pointcloud_files.id）；空/缺省 = 全部 */
+    fileIds?: number[];
+  };
+
+  let paths: string[] = [];
+
+  if (taskId != null) {
+    let records = await db.listTaskPointcloudFiles(taskId);
+    // 当前端传入 fileIds 时只采样选中的文件
+    if (Array.isArray(fileIds) && fileIds.length > 0) {
+      const idSet = new Set(fileIds);
+      records = records.filter((r) => idSet.has(r.id));
+    }
+    paths = records.map((r) => r.filePath);
+  } else if (Array.isArray(rawPaths) && rawPaths.length > 0) {
+    paths = rawPaths;
+  } else {
+    return res.status(400).json({ error: 'Provide taskId or filePaths' });
+  }
+
+  if (paths.length === 0) {
+    const empty = Buffer.alloc(0);
+    res.setHeader('Content-Type', 'application/octet-stream');
+    res.setHeader('X-Point-Count', '0');
+    res.setHeader('X-File-Stats', '[]');
+    return res.send(empty);
+  }
+
+  const budget = Math.min(totalPoints, 2000000);
+  const supportedExts = ['.ply', '.txt', '.xyz', '.pts'];
+
+  const fileInfos = paths.map((fp) => ({
+    filePath: fp,
+    name: path.basename(fp),
+    ext: path.extname(fp).toLowerCase(),
+    size: fs.existsSync(fp) ? fs.statSync(fp).size : 0,
+  }));
+
+  const supportedFiles = fileInfos.filter((f) => supportedExts.includes(f.ext) && f.size > 0);
+  const totalBytes = supportedFiles.reduce((s, f) => s + f.size, 0);
+
+  console.log(
+    `[FileRoutes] Batch sample: ${fileInfos.length} files ` +
+    `(${(totalBytes / 1e9).toFixed(2)} GB), budget=${budget}`
+  );
+
+  try {
+    const quotaMap = new Map<string, number>();
+    for (const f of supportedFiles) {
+      const quota = totalBytes > 0
+        ? Math.max(100, Math.round((f.size / totalBytes) * budget))
+        : Math.floor(budget / supportedFiles.length);
+      quotaMap.set(f.filePath, quota);
+    }
+
+    const sampledPerFile = await Promise.all(
+      fileInfos.map((f) => {
+        if (!supportedExts.includes(f.ext) || f.size === 0) return Promise.resolve([] as SampledPoint[]);
+        return samplePointcloudFile(f.filePath, f.size, quotaMap.get(f.filePath) ?? 0);
+      })
+    );
+
+    const totalSampled = sampledPerFile.reduce((s, pts) => s + pts.length, 0);
+    const binBuf = Buffer.allocUnsafe(totalSampled * 16);
+    let offset = 0;
+    for (const pts of sampledPerFile) {
+      for (const p of pts) {
+        binBuf.writeFloatLE(p.x, offset);
+        binBuf.writeFloatLE(p.y, offset + 4);
+        binBuf.writeFloatLE(p.z, offset + 8);
+        binBuf.writeFloatLE(p.error, offset + 12);
+        offset += 16;
+      }
+    }
+
+    const fileStats = fileInfos.map((f, i) => ({
+      name: f.name,
+      sizeGB: +(f.size / 1e9).toFixed(3),
+      sampled: sampledPerFile[i].length,
+    }));
+
+    console.log(`[FileRoutes] Batch done: ${totalSampled} pts, ${(binBuf.length / 1e6).toFixed(1)} MB`);
+    res.setHeader('Content-Type', 'application/octet-stream');
+    res.setHeader('X-Point-Count', totalSampled);
+    res.setHeader('X-File-Stats', JSON.stringify(fileStats));
+    res.send(binBuf);
+  } catch (err) {
+    console.error('[FileRoutes] Batch sampling error:', err);
+    res.status(500).json({ error: 'Failed to sample files' });
+  }
+});
+
+// ─── 平滑热力分析结果（异步任务产物，仅读取已落盘的顶点色）──────────────────────
+// GET /api/files/read/analysis/heatmap/:taskId/:resultId
+
+router.get('/read/analysis/heatmap/:taskId/:resultId', async (req, res) => {
+  const taskId = parseInt(req.params.taskId, 10);
+  const resultId = parseInt(req.params.resultId, 10);
+  if (Number.isNaN(taskId) || Number.isNaN(resultId)) {
+    return res.status(400).json({ error: 'invalid id' });
+  }
+
+  const row = await db.getTaskAnalysisResultById(resultId);
+  if (!row || row.taskId !== taskId || (row.type !== 'smooth_heatmap' && row.type !== 'obj_deviation') || row.status !== 'completed') {
+    return res.status(404).json({ error: 'not found' });
+  }
+
+  const rd = row.resultData as {
+    vertexCount?: number;
+    dispMin?: number;
+    dispMax?: number;
+    binName?: string;
+  } | null;
+  const binName = rd?.binName ?? `heatmap_${resultId}.bin`;
+  const binPath = path.join(TASKS_DIR, String(taskId), 'analysis', binName);
+  if (!fs.existsSync(binPath)) {
+    return res.status(404).json({ error: 'heatmap file missing' });
+  }
+
+  const body = fs.readFileSync(binPath);
+  res.setHeader('Content-Type', 'application/octet-stream');
+  res.setHeader('Content-Length', String(body.length));
+  res.setHeader('X-Vertex-Count', String(rd?.vertexCount ?? ''));
+  res.setHeader('X-Disp-Min', String(rd?.dispMin ?? ''));
+  res.setHeader('X-Disp-Max', String(rd?.dispMax ?? ''));
+  res.send(body);
+});
+
+// ─── 装配检测：每零件顶点热力缓存（可选）──────────────────────────────────────
+// GET /api/files/read/analysis/assembly-vertex/:taskId/:resultId/:filename
+
+router.get('/read/analysis/assembly-vertex/:taskId/:resultId/:filename', async (req, res) => {
+  const taskId = parseInt(req.params.taskId, 10);
+  const resultId = parseInt(req.params.resultId, 10);
+  const filename = req.params.filename;
+  if (Number.isNaN(taskId) || Number.isNaN(resultId) || !filename) {
+    return res.status(400).json({ error: 'invalid params' });
+  }
+
+  const row = await db.getTaskAnalysisResultById(resultId);
+  if (!row || row.taskId !== taskId || row.type !== 'assembly_inspection' || row.status !== 'completed') {
+    return res.status(404).json({ error: 'not found' });
+  }
+
+  const analysisDir = path.join(TASKS_DIR, String(taskId), 'analysis');
+  const filePath = safeResolve(analysisDir, filename);
+  if (!filePath) return res.status(403).json({ error: 'Access denied' });
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'file missing' });
+
+  res.setHeader('Content-Type', 'application/octet-stream');
+  res.sendFile(filePath);
+});
+
+// ─── 通用算法插件产物（Route B） ──────────────────────────────────────────────
+// GET /api/files/read/analysis/:taskId/:resultId/*
+//
+// 每次插件执行的 outDir = /data/tasks/<taskId>/analysis/<resultId>。
+// 前端拿到 result.json.images / overlay3d.file 后通过此路由拉取产物文件。
+// 注意：此路由必须放在 heatmap / assembly-vertex 等具体路由之后，否则
+// 会用 taskId="heatmap" 这种字符串把请求误吞掉。
+
+router.get('/read/analysis/:taskId/:resultId/*', async (req, res) => {
+  const taskId = parseInt(req.params.taskId, 10);
+  const resultId = parseInt(req.params.resultId, 10);
+  const filename = (req.params as Record<string, string>)[0] || (req.params as Record<string, string>)['0'];
+  if (Number.isNaN(taskId) || Number.isNaN(resultId) || !filename) {
+    return res.status(400).json({ error: 'invalid params' });
+  }
+
+  const row = await db.getTaskAnalysisResultById(resultId);
+  if (!row || row.taskId !== taskId) {
+    return res.status(404).json({ error: 'not found' });
+  }
+
+  const baseDir = path.join(TASKS_DIR, String(taskId), 'analysis', String(resultId));
+  const filePath = safeResolve(baseDir, filename);
+  if (!filePath) return res.status(403).json({ error: 'Access denied' });
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'file missing' });
+  res.sendFile(filePath);
+});
+
+// ─── 插件热重载 ──────────────────────────────────────────────────────────────
+// POST /api/files/plugins/reload
+// 重新从磁盘扫描 manifests/*.json，无需重启服务器。
+// 用于更新算法版本后立即生效。
+router.post('/plugins/reload', (_req, res) => {
+  try {
+    const plugins = reloadPluginRegistry();
+    res.json({
+      success: true,
+      count: plugins.length,
+      plugins: plugins.map((p) => ({ id: p.id, version: p.version })),
+    });
+  } catch (e) {
+    res.status(500).json({ success: false, error: String(e) });
+  }
+});
+
+export { router as fileRouter };

server/plugins/adapters/_plugin_io.py

@@ -0,0 +1,252 @@
+"""算法插件适配器共用 I/O 工具。
+
+约定（与 server/plugins/types.ts 对齐）：
+- 子进程入口的唯一参数是 ``input.json`` 的绝对路径；
+- 子进程通过 stdout 单行 JSON 上报进度：``{"type":"progress","percent":42,"message":"..."}``
+- 子进程在 ``outDir/result.json`` 写最终结果；
+- stderr 仅做日志（runner 会原样转发）。
+
+所有适配器都很薄：解析 input.json → 调真实算法 API → 写 result.json。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import traceback
+from pathlib import Path
+from typing import Any
+
+
+def load_input(argv: list[str]) -> dict[str, Any]:
+    """读取 input.json。"""
+    if len(argv) < 2:
+        emit_error("usage: <adapter>.py <input.json>", exit_code=2)
+    path = Path(argv[1])
+    if not path.exists():
+        emit_error(f"input.json 不存在: {path}", exit_code=2)
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def emit_progress(percent: float, message: str = "") -> None:
+    """以单行 JSON 上报进度。runner 解析后写入数据库。
+
+    percent 接受 0~1 或 0~100，runner 端会归一化。
+    """
+    line = {"type": "progress", "percent": float(percent), "message": message}
+    sys.stdout.write(json.dumps(line, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def write_result(out_dir: str | os.PathLike, payload: dict[str, Any]) -> Path:
+    """写 result.json 到 outDir，并强制 schemaVersion / status 字段存在。
+    NaN/Infinity 会被替换为 null，确保输出合法 JSON。
+    """
+    import math
+
+    def _sanitize(obj: Any) -> Any:
+        if isinstance(obj, float) and (math.isnan(obj) or math.isinf(obj)):
+            return None
+        if isinstance(obj, dict):
+            return {k: _sanitize(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [_sanitize(v) for v in obj]
+        return obj
+
+    out_path = Path(out_dir) / "result.json"
+    payload.setdefault("schemaVersion", 1)
+    payload.setdefault("status", "completed")
+    out_path.write_text(json.dumps(_sanitize(payload), ensure_ascii=False, indent=2), encoding="utf-8")
+    return out_path
+
+
+def write_error_result(out_dir: str | os.PathLike, message: str, extra: dict | None = None) -> None:
+    """统一错误写出：result.json 仍然存在，runner 据此把数据库改成 error。"""
+    payload: dict[str, Any] = {
+        "schemaVersion": 1,
+        "status": "error",
+        "message": message,
+    }
+    if extra:
+        payload["extra"] = extra
+    Path(out_dir).mkdir(parents=True, exist_ok=True)
+    (Path(out_dir) / "result.json").write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+
+def emit_error(message: str, exit_code: int = 1) -> None:
+    sys.stderr.write(f"[adapter-error] {message}\n")
+    sys.exit(exit_code)
+
+
+def first_pointcloud(input_payload: dict[str, Any]) -> str:
+    """取 inputs.pointCloudPaths 的第一个；无则报错。"""
+    paths = (input_payload.get("inputs") or {}).get("pointCloudPaths") or []
+    if not paths:
+        raise RuntimeError("inputs.pointCloudPaths 为空，请确认任务已上传点云。")
+    return str(paths[0])
+
+
+def now() -> float:
+    return time.time()
+
+
+# ─── Binary PLY → ASCII PLY 转换 ─────────────────────────────────────────────
+
+def ensure_ascii_ply(src: str | os.PathLike, cache_dir: str | os.PathLike) -> str:
+    """如果 src 是二进制 PLY，把它转成 ASCII PLY 写到 cache_dir 并返回新路径。
+    如果已经是 ASCII PLY 或其他格式，直接返回原路径。
+
+    不依赖 open3d / plyfile，只用 numpy + struct（标准库）。
+    """
+    src = Path(src)
+    suffix = src.suffix.lower()
+    if suffix != ".ply":
+        return str(src)
+
+    # 读文件头（最多 16 KB）
+    HEADER_MAX = 16 * 1024
+    with open(src, "rb") as fh:
+        raw = fh.read(HEADER_MAX)
+
+    try:
+        header_text = raw.decode("ascii", errors="replace")
+    except Exception:
+        return str(src)  # 无法解析，原样返回
+
+    if not header_text.startswith("ply"):
+        return str(src)
+
+    end_marker = "end_header"
+    end_idx = header_text.find(end_marker)
+    if end_idx == -1:
+        return str(src)
+
+    # 找 end_header 后的换行
+    data_start = end_idx + len(end_marker)
+    if header_text[data_start : data_start + 2] == "\r\n":
+        data_start += 2
+    elif header_text[data_start] in ("\r", "\n"):
+        data_start += 1
+
+    header_lines = header_text[:end_idx].splitlines()
+
+    # 解析 format
+    fmt = "ascii"
+    for line in header_lines:
+        parts = line.strip().split()
+        if parts and parts[0] == "format":
+            fmt = parts[1] if len(parts) > 1 else "ascii"
+            break
+
+    if fmt == "ascii":
+        return str(src)  # 已经是 ASCII，无需转换
+
+    # 解析 vertex 属性
+    import struct as _struct
+    import numpy as _np
+
+    _PLY_DTYPE: dict[str, tuple[str, int]] = {
+        "char": ("b", 1), "int8": ("b", 1),
+        "uchar": ("B", 1), "uint8": ("B", 1),
+        "short": ("h", 2), "int16": ("h", 2),
+        "ushort": ("H", 2), "uint16": ("H", 2),
+        "int": ("i", 4), "int32": ("i", 4),
+        "uint": ("I", 4), "uint32": ("I", 4),
+        "float": ("f", 4), "float32": ("f", 4),
+        "double": ("d", 8), "float64": ("d", 8),
+    }
+
+    vertex_count = 0
+    props: list[tuple[str, str, int]] = []  # (name, fmt_char, byte_size)
+    in_vertex = False
+    for line in header_lines:
+        parts = line.strip().split()
+        if not parts:
+            continue
+        if parts[0] == "element":
+            in_vertex = parts[1] == "vertex" if len(parts) > 1 else False
+            if in_vertex and len(parts) > 2:
+                vertex_count = int(parts[2])
+        elif parts[0] == "property" and in_vertex:
+            if parts[1] == "list":
+                in_vertex = False
+                continue
+            ptype = parts[1] if len(parts) > 1 else "float"
+            pname = parts[2] if len(parts) > 2 else ""
+            fc, bs = _PLY_DTYPE.get(ptype, ("f", 4))
+            props.append((pname, fc, bs))
+
+    if vertex_count == 0 or not props:
+        return str(src)
+
+    # Find x, y, z offsets
+    x_off = y_off = z_off = -1
+    x_fc = y_fc = z_fc = "f"
+    byte_off = 0
+    for pname, fc, bs in props:
+        n = pname.lower()
+        if n == "x":
+            x_off, x_fc = byte_off, fc
+        elif n == "y":
+            y_off, y_fc = byte_off, fc
+        elif n == "z":
+            z_off, z_fc = byte_off, fc
+        byte_off += bs
+
+    if x_off < 0 or y_off < 0 or z_off < 0:
+        return str(src)  # 找不到 xyz，原样返回
+
+    bytes_per_vertex = sum(bs for _, _, bs in props)
+    little_endian = fmt != "binary_big_endian"
+    endian = "<" if little_endian else ">"
+
+    # 读整个数据区
+    file_size = src.stat().st_size
+    data_bytes = file_size - data_start
+    expected = vertex_count * bytes_per_vertex
+
+    with open(src, "rb") as fh:
+        fh.seek(data_start)
+        data = fh.read(expected)
+
+    if len(data) < expected:
+        return str(src)  # 文件截断，原样返回
+
+    # 用 numpy structured array 解析
+    dtype_fields = []
+    for pname, fc, bs in props:
+        np_type = endian + fc
+        dtype_fields.append((pname or f"_f{len(dtype_fields)}", np_type))
+
+    try:
+        arr = _np.frombuffer(data, dtype=_np.dtype(dtype_fields))
+        xs = arr[props[0][0] if props[0][0] else "_f0"]  # fallback
+        # 直接按名字取
+        x_name = props[[i for i, (n, _, _) in enumerate(props) if n.lower() == "x"][0]][0]
+        y_name = props[[i for i, (n, _, _) in enumerate(props) if n.lower() == "y"][0]][0]
+        z_name = props[[i for i, (n, _, _) in enumerate(props) if n.lower() == "z"][0]][0]
+        xs = arr[x_name].astype(_np.float64)
+        ys = arr[y_name].astype(_np.float64)
+        zs = arr[z_name].astype(_np.float64)
+    except Exception:
+        return str(src)
+
+    # 写 ASCII PLY
+    cache_dir = Path(cache_dir)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    out_path = cache_dir / (src.stem + "_ascii.ply")
+
+    with open(out_path, "w", encoding="ascii") as fh:
+        fh.write("ply\nformat ascii 1.0\n")
+        fh.write(f"element vertex {vertex_count}\n")
+        fh.write("property double x\nproperty double y\nproperty double z\n")
+        fh.write("end_header\n")
+        for x, y, z in zip(xs, ys, zs):
+            fh.write(f"{x:.10g} {y:.10g} {z:.10g}\n")
+
+    return str(out_path)
+

server/plugins/adapters/coupler_panel_run.py

@@ -0,0 +1,159 @@
+"""coupler-panel 算法适配器 (v1.1)。
+
+v1.1 变更：
+  - 入口从 compute_coupler_measurement → run_coupler_measurement_pipeline
+  - 新增 D_y_max_mm / D_z_max_mm 字段
+  - 支持可选 CAD STP 路径（cad_stp_path）和 ROI JSON（roi_json）
+  - PYTHONPATH 指向 delivery_v1.1/coupler_panel_release
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _plugin_io import (
+    emit_progress,
+    ensure_ascii_ply,
+    first_pointcloud,
+    load_input,
+    write_error_result,
+    write_result,
+)
+
+
+def _status_for(value: float, tolerance: float | None) -> str:
+    if tolerance is None:
+        return "info"
+    if abs(value) <= tolerance:
+        return "pass"
+    if abs(value) <= tolerance * 1.5:
+        return "warning"
+    return "fail"
+
+
+def main() -> int:
+    payload = load_input(sys.argv)
+    inputs = payload.get("inputs") or {}
+    config = inputs.get("config") or {}
+    out_dir = Path(payload["outDir"])
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        emit_progress(0.05, "加载 coupler_panel v1.1 算法包")
+        from coupler_panel.pipeline import run_coupler_measurement_pipeline  # type: ignore
+
+        pc_path = first_pointcloud(payload)
+        emit_progress(0.15, f"读取点云：{os.path.basename(pc_path)}")
+
+        # 若是二进制 PLY，先转成 ASCII PLY（算法内置 reader 不依赖 open3d）
+        pc_path = ensure_ascii_ply(pc_path, out_dir / "_ply_cache")
+
+        profile = str(config.get("profile") or "auto")
+        right_axis_sign = int(config.get("rightAxisSign") or 1)
+
+        # 可选 CAD STP 路径（前端传入 cadPath 时使用）
+        cad_stp_path = inputs.get("cadPath") or None
+
+        # 可选 ROI JSON 路径（前端传入 roiJson 时使用）
+        roi_json = inputs.get("roiJson") or None
+
+        emit_progress(0.25, "调用 run_coupler_measurement_pipeline")
+
+        def _on_progress(stage: str, fraction: float) -> None:
+            emit_progress(0.25 + min(1.0, max(0.0, fraction)) * 0.70, stage)
+
+        result = run_coupler_measurement_pipeline(
+            input_cloud=pc_path,
+            out_dir=str(out_dir),
+            profile=profile,
+            cad_stp_path=cad_stp_path,
+            roi_json=roi_json,
+            progress=_on_progress,
+        )
+
+        emit_progress(0.97, "整理结果")
+
+        # right_axis_sign 影响 theta_right_deg 的符号约定
+        theta_right = float(result.theta_right_deg) * right_axis_sign
+        theta_ref = float(result.theta_ref_deg)
+        dx_y = float(result.dx_y_max_mm)
+        dx_z = float(result.dx_z_max_mm)
+        D_y = float(result.D_y_max_mm)
+        D_z = float(result.D_z_max_mm)
+
+        measurements = [
+            {
+                "name": "偏转角 θ_right (右向)",
+                "value": theta_right,
+                "unit": "deg",
+                "tolerance": 0.5,
+                "status": _status_for(theta_right, 0.5),
+            },
+            {
+                "name": "偏转角 θ_ref (参考向)",
+                "value": theta_ref,
+                "unit": "deg",
+                "tolerance": 0.5,
+                "status": _status_for(theta_ref, 0.5),
+            },
+            {
+                "name": "最大 x 偏差 dx_y",
+                "value": dx_y,
+                "unit": "mm",
+                "tolerance": 1.0,
+                "status": _status_for(dx_y, 1.0),
+            },
+            {
+                "name": "最大 x 偏差 dx_z",
+                "value": dx_z,
+                "unit": "mm",
+                "tolerance": 1.0,
+                "status": _status_for(dx_z, 1.0),
+            },
+            {
+                "name": "面板 y 向最大偏差 D_y",
+                "value": D_y,
+                "unit": "mm",
+                "status": "info",
+            },
+            {
+                "name": "面板 z 向最大偏差 D_z",
+                "value": D_z,
+                "unit": "mm",
+                "status": "info",
+            },
+        ]
+
+        payload_out = {
+            "schemaVersion": getattr(result, "schema_version", "1.1"),
+            "status": "completed",
+            "measurements": measurements,
+            "overlay3d": {"kind": "none"},
+            "extra": {
+                "algorithmVersion": getattr(result, "algorithm_version", None),
+                "qualityFlags": list(result.quality_flags or []),
+                "normal": list(result.normal) if result.normal else None,
+                "centerC": list(result.center_C) if result.center_C else None,
+                "report": result.report if isinstance(result.report, dict) else None,
+            },
+        }
+        write_result(out_dir, payload_out)
+        emit_progress(1.0, "完成")
+        return 0
+
+    except Exception as exc:
+        traceback.print_exc()
+        write_error_result(
+            out_dir,
+            f"coupler-panel 计算失败：{exc}",
+            extra={"traceback": traceback.format_exc()},
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

server/plugins/adapters/flatness_suite_run.py

@@ -0,0 +1,271 @@
+"""flatness-suite 算法适配器 (v1.2)。
+
+v1.2 变更：
+  - 算法目录从 alg/平整度、平面度、轮廓测量/ → alg/point_porj/
+  - 入口从独立脚本（importlib 加载）→ MeasurementPipeline 类
+  - run_plane / run_curvature / run_contour 统一通过 MeasurementPipeline 调用
+  - 点云路径通过 config["paths"]["pointcloud"] 注入，不再依赖 open3d 直接读取
+
+约定：
+  - module=all：plane + curvature（contour 需要 CAD STL，缺失时跳过）
+  - module=plane：只跑平面拟合
+  - module=curvature：只跑曲率估计
+  - module=contour：需要 CAD STL，缺失时报错
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+import sys
+import traceback
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _plugin_io import (
+    emit_progress,
+    ensure_ascii_ply,
+    first_pointcloud,
+    load_input,
+    write_error_result,
+    write_result,
+)
+
+
+def _safe_float(v: object) -> float | None:
+    try:
+        return float(v)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _find_alg_dir(alg_root: str) -> Path:
+    """定位 point_porj 目录，支持多种可能的路径。"""
+    candidates = [
+        Path(alg_root) / "point_porj",
+        Path(alg_root) / "平整度、平面度、轮廓测量v1.2" / "point_porj",
+        Path(alg_root) / "平整度、平面度、轮廓测量" / "point_porj",
+    ]
+    for c in candidates:
+        if c.is_dir() and (c / "pipeline.py").exists():
+            return c
+    raise RuntimeError(
+        f"找不到 point_porj 算法目录，已尝试：\n"
+        + "\n".join(f"  {c}" for c in candidates)
+        + "\n请确认 alg/ 下已解压 point_porj/。"
+    )
+
+
+def _build_pipeline(alg_dir: Path, pc_path: str, out_dir: Path, params: dict) -> Any:
+    """初始化 MeasurementPipeline，注入点云路径和输出路径。"""
+    # 把 alg_dir 加到 sys.path，让 pipeline.py 能 import 同级模块
+    alg_dir_str = str(alg_dir)
+    if alg_dir_str not in sys.path:
+        sys.path.insert(0, alg_dir_str)
+
+    from pipeline import MeasurementPipeline  # type: ignore
+
+    # 加载内置 config.yaml，然后覆盖关键路径
+    pipeline = MeasurementPipeline(config_path=None)
+
+    # 注入点云路径
+    pipeline.config["paths"]["pointcloud"] = pc_path
+
+    # 注入输出路径（curvature_output 写到 outDir）
+    pipeline.config["paths"]["curvature_output"] = str(out_dir / "curvature.ply")
+
+    # 关闭可视化（无显示器）
+    pipeline.config["visualization"]["enabled"] = False
+
+    # 用户参数覆盖
+    voxel_size = _safe_float(params.get("voxelSizeMm"))
+    if voxel_size is not None:
+        pipeline.config["filters"]["voxel_size"] = voxel_size / 1000.0  # mm → m
+
+    threshold_mm = _safe_float(params.get("thresholdMm"))
+    if threshold_mm is not None:
+        pipeline.config["plane"]["threshold_mm"] = threshold_mm
+
+    return pipeline
+
+
+def main() -> int:
+    payload = load_input(sys.argv)
+    inputs = payload.get("inputs") or {}
+    config = inputs.get("config") or {}
+    out_dir = Path(payload["outDir"])
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        alg_root = os.environ.get("ALG_ROOT") or os.environ.get("ALG_ROOT_HOST") or "/alg"
+        emit_progress(0.05, "定位 point_porj 算法目录")
+        alg_dir = _find_alg_dir(alg_root)
+
+        pc_path_raw = first_pointcloud(payload)
+        emit_progress(0.10, f"读取点云：{os.path.basename(pc_path_raw)}")
+
+        # 二进制 PLY → ASCII PLY（算法内置 reader 不依赖 open3d）
+        pc_path = ensure_ascii_ply(pc_path_raw, out_dir / "_ply_cache")
+
+        module = str(config.get("module") or "all")
+        emit_progress(0.15, f"初始化 MeasurementPipeline（module={module}）")
+
+        pipeline = _build_pipeline(alg_dir, pc_path, out_dir, config)
+
+        measurements: list[dict] = []
+        extra: dict[str, Any] = {"module": module}
+        skipped: list[str] = []
+
+        # ── plane ──────────────────────────────────────────────────────────────
+        if module in ("all", "plane"):
+            emit_progress(0.30, "平面拟合 (RANSAC)")
+            try:
+                res = pipeline.run_plane(
+                    pointcloud_path=pc_path,
+                    threshold_mm=_safe_float(config.get("thresholdMm")),
+                    no_visualize=True,
+                )
+                pr = res.get("plane_result")
+                if pr is not None:
+                    rmse_mm = float(pr.rmse) * 1000.0  # m → mm
+                    measurements += [
+                        {
+                            "name": "平面 RMSE",
+                            "value": round(rmse_mm, 4),
+                            "unit": "mm",
+                            "status": "pass" if rmse_mm <= 1.0 else "warning" if rmse_mm <= 2.0 else "fail",
+                        },
+                        {
+                            "name": "内点率",
+                            "value": round(float(pr.inlier_ratio), 2),
+                            "unit": "%",
+                            "status": "pass" if pr.inlier_ratio >= 80 else "warning" if pr.inlier_ratio >= 60 else "fail",
+                        },
+                        {
+                            "name": "法向角误差",
+                            "value": round(float(pr.normal_angle_deg), 4),
+                            "unit": "deg",
+                            "status": "info",
+                        },
+                    ]
+                    extra["planeModel"] = list(pr.model) if pr.model else None
+            except Exception as exc:
+                skipped.append(f"plane: {exc}")
+
+        # ── curvature ──────────────────────────────────────────────────────────
+        if module in ("all", "curvature"):
+            emit_progress(0.55, "曲率估计")
+            try:
+                res = pipeline.run_curvature(
+                    pointcloud_path=pc_path,
+                    no_visualize=True,
+                )
+                curvatures = res.get("curvatures")
+                if curvatures is not None:
+                    import numpy as np
+                    measurements += [
+                        {
+                            "name": "曲率均值",
+                            "value": round(float(np.mean(curvatures)), 6),
+                            "unit": "1/mm",
+                            "status": "info",
+                        },
+                        {
+                            "name": "曲率最大值",
+                            "value": round(float(np.max(curvatures)), 6),
+                            "unit": "1/mm",
+                            "status": "info",
+                        },
+                    ]
+                # 保存曲率点云路径
+                curv_ply = out_dir / "curvature.ply"
+                if curv_ply.exists():
+                    extra["curvaturePly"] = "curvature.ply"
+            except Exception as exc:
+                skipped.append(f"curvature: {exc}")
+
+        # ── contour ────────────────────────────────────────────────────────────
+        if module in ("all", "contour"):
+            emit_progress(0.75, "轮廓-平整度（需 CAD STL）")
+            cad_path = inputs.get("cadPath") or None
+            mesh_path = inputs.get("meshPath") or None
+            if not cad_path and not mesh_path:
+                skipped.append("contour: 未提供 CAD STL/STEP，跳过")
+            else:
+                try:
+                    save_path = str(out_dir / "contour.ply")
+                    excel_path = str(out_dir / "contour.xlsx")
+                    res = pipeline.run_contour(
+                        pointcloud_path=pc_path,
+                        cad_path=cad_path,
+                        mesh_path=mesh_path,
+                        save_path=save_path,
+                        excel_output_path=excel_path,
+                        no_visualize=True,
+                    )
+                    stats = res.get("distance_stats")
+                    for key, label, unit in [
+                        ("mean", "轮廓偏差均值", "mm"),
+                        ("max", "轮廓偏差最大值", "mm"),
+                        ("std", "轮廓偏差标准差", "mm"),
+                    ]:
+                        v = _safe_float(getattr(stats, key, None) if stats is not None else None)
+                        if v is not None:
+                            measurements.append({
+                                "name": label,
+                                "value": round(v, 4),
+                                "unit": unit,
+                                "status": "info",
+                            })
+                    if Path(save_path).exists():
+                        extra["contourPly"] = "contour.ply"
+                except Exception as exc:
+                    skipped.append(f"contour: {exc}")
+
+        emit_progress(0.95, "整理结果")
+
+        # 3D 叠加层：优先 contour PLY，其次 curvature PLY
+        overlay3d: dict = {"kind": "none"}
+        for ply_key in ("contourPly", "curvaturePly"):
+            if ply_key in extra:
+                overlay3d = {"kind": "vertexColors", "url": extra[ply_key]}
+                break
+
+        if skipped:
+            extra["skipped"] = skipped
+
+        status_vals = [m.get("status") for m in measurements]
+        overall = (
+            "fail" if "fail" in status_vals
+            else "warning" if "warning" in status_vals
+            else "completed"
+        )
+
+        payload_out = {
+            "schemaVersion": 1,
+            "status": overall,
+            "message": (
+                f"完成 {len(measurements)} 项测量。"
+                + (f" 跳过：{'; '.join(skipped)}" if skipped else "")
+            ),
+            "measurements": measurements,
+            "overlay3d": overlay3d,
+            "extra": extra,
+        }
+        write_result(out_dir, payload_out)
+        emit_progress(1.0, "完成")
+        return 0
+
+    except Exception as exc:
+        traceback.print_exc()
+        write_error_result(
+            out_dir,
+            f"flatness-suite 计算失败：{exc}",
+            extra={"traceback": traceback.format_exc()},
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

server/plugins/adapters/train_measurement_run.py

@@ -0,0 +1,207 @@
+"""train-measurement 算法适配器 (v1.1)。
+
+读 input.json → 调 TaskManager（来自 alg/点云测距v1.1）→ 写统一 result.json。
+
+v1.1 变更：
+  - 路径从 260505列车点云测距v1 → 点云测距v1.1
+  - 算法包现在是可安装的 Python 包（有 __init__.py），PYTHONPATH 指向 src/
+  - TRAIN_MEAS_ROOT 指向 train_measurement_system/（用于定位 config/measurements.yaml）
+  - TaskManager.run_all_tasks() 返回结构不变，data 字段含 mean_distance / std_distance 等
+
+约定：
+  - 第一个点云路径作为 pointcloud_file 注入到测量配置 YAML 中；
+  - 若用户在 UI 选择「自定义 YAML」并提供 customYaml，则使用之；
+    否则使用算法仓库自带的 config/measurements.yaml 作为模板。
+  - 所有任务结果合成成 measurements[] 列表，附带可视化 PLY 路径到 extra。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _plugin_io import (
+    emit_progress,
+    ensure_ascii_ply,
+    first_pointcloud,
+    load_input,
+    write_error_result,
+    write_result,
+)
+
+
+def main() -> int:
+    payload = load_input(sys.argv)
+    inputs = payload.get("inputs") or {}
+    config = inputs.get("config") or {}
+    out_dir = Path(payload["outDir"])
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        emit_progress(0.05, "加载 train_measurement v1.1 算法包")
+
+        # TRAIN_MEAS_ROOT 由 manifest envExtra 注入，指向 train_measurement_system/
+        train_root = Path(os.environ.get("TRAIN_MEAS_ROOT") or "")
+        if not train_root.exists():
+            # 回退：从 ALG_ROOT 推导
+            alg_root = Path(os.environ.get("ALG_ROOT") or "/alg")
+            train_root = alg_root / "点云测距v1.1" / "train_measurement_system"
+
+        if not train_root.exists():
+            raise RuntimeError(
+                f"找不到 train_measurement_system 目录：{train_root}。"
+                "请确认 TRAIN_MEAS_ROOT 或 ALG_ROOT 环境变量已正确设置。"
+            )
+
+        from task_manager import TaskManager  # type: ignore
+
+        pc_path = first_pointcloud(payload)
+        emit_progress(0.15, f"读取点云：{os.path.basename(pc_path)}")
+
+        # 若是二进制 PLY，先转成 ASCII PLY（算法内置 reader 不依赖 open3d）
+        pc_path = ensure_ascii_ply(pc_path, out_dir / "_ply_cache")
+
+        # ── 准备 YAML 配置 ────────────────────────────────────────────────────
+        config_preset = str(config.get("configPreset") or "builtin")
+        custom_yaml_str = str(config.get("customYaml") or "").strip()
+
+        if config_preset == "custom" and custom_yaml_str:
+            # 支持 JSON 格式（前端传来）和 YAML 格式
+            yaml_path = out_dir / "custom_measurements.yaml"
+            try:
+                import json as _json
+                parsed = _json.loads(custom_yaml_str)
+                # JSON 格式：转成 YAML 写盘
+                import yaml as _yaml
+                yaml_path.write_text(_yaml.dump(parsed, allow_unicode=True, default_flow_style=False), encoding="utf-8")
+            except Exception:
+                # 已经是 YAML 格式，直接写盘
+                yaml_path.write_text(custom_yaml_str, encoding="utf-8")
+        else:
+            # 使用算法仓库内置的 config/measurements.yaml
+            yaml_path = train_root / "config" / "measurements.yaml"
+            if not yaml_path.exists():
+                raise RuntimeError(f"内置配置文件不存在：{yaml_path}")
+
+        emit_progress(0.20, f"加载配置：{yaml_path.name}")
+
+        # ── 初始化 TaskManager ────────────────────────────────────────────────
+        tm = TaskManager()
+        # 先注入点云路径，让 load_config 跳过 YAML 里的 pointcloud_file（开发测试路径）
+        tm.pointcloud_path_override = pc_path
+        if not tm.load_config(str(yaml_path)):
+            raise RuntimeError(f"TaskManager 加载配置失败：{yaml_path}")
+
+        # 注入点云路径（覆盖 YAML 中的 pointcloud_file）
+        tm.config["pointcloud_file"] = pc_path
+
+        # 注入可视化输出目录
+        viz_dir = out_dir / "visualizations"
+        viz_dir.mkdir(parents=True, exist_ok=True)
+        for task in tm.tasks:
+            if hasattr(task, "visualization_dir"):
+                task.visualization_dir = str(viz_dir)
+
+        emit_progress(0.30, "加载点云（已在 load_config 中完成）")
+
+        emit_progress(0.40, f"执行 {len(tm.tasks)} 个测量任务")
+        results = tm.run_all_tasks()
+
+        emit_progress(0.92, "整理结果")
+        measurements: list[dict] = []
+        clean_raw: list[dict] = []
+
+        for r in results:
+            name = str(r.get("name") or "未命名任务")
+            status_raw = r.get("status")
+            data = r.get("data") if isinstance(r.get("data"), dict) else {}
+            # 剥掉以 '_' 开头的私有 numpy 数组（不可 JSON 序列化）
+            clean_data = {k: v for k, v in data.items() if not k.startswith("_")} if data else {}
+            clean_raw.append(
+                {
+                    "name": name,
+                    "type": r.get("type"),
+                    "status": status_raw,
+                    "data": clean_data,
+                    "error": r.get("error"),
+                }
+            )
+
+            if status_raw == "success":
+                value = clean_data.get("mean_distance")
+                if value is None:
+                    value = clean_data.get("distance")
+                measurements.append(
+                    {
+                        "name": name,
+                        "value": float(value) if isinstance(value, (int, float)) else float("nan"),
+                        "unit": "mm",
+                        "status": "info",
+                    }
+                )
+                std = clean_data.get("std_distance")
+                if isinstance(std, (int, float)):
+                    measurements.append(
+                        {
+                            "name": f"{name} · 标准差",
+                            "value": float(std),
+                            "unit": "mm",
+                            "status": "info",
+                        }
+                    )
+                # v1.1 新增字段：min/max distance
+                for field_name, label in [
+                    ("min_distance", "最小距离"),
+                    ("max_distance", "最大距离"),
+                ]:
+                    v = clean_data.get(field_name)
+                    if isinstance(v, (int, float)):
+                        measurements.append(
+                            {
+                                "name": f"{name} · {label}",
+                                "value": float(v),
+                                "unit": "mm",
+                                "status": "info",
+                            }
+                        )
+            else:
+                measurements.append(
+                    {
+                        "name": name,
+                        "value": float("nan"),
+                        "unit": "mm",
+                        "status": "fail",
+                    }
+                )
+
+        success_count = sum(1 for r in results if r.get("status") == "success")
+        payload_out = {
+            "schemaVersion": 1,
+            "status": "completed",
+            "message": f"共 {len(results)} 个任务，成功 {success_count} 个。",
+            "measurements": measurements,
+            "overlay3d": {"kind": "none"},
+            "extra": {
+                "rawTaskResults": clean_raw,
+                "visualizationDir": "visualizations",
+            },
+        }
+        write_result(out_dir, payload_out)
+        emit_progress(1.0, "完成")
+        return 0
+
+    except Exception as exc:
+        traceback.print_exc()
+        write_error_result(
+            out_dir,
+            f"train-measurement 计算失败：{exc}",
+            extra={"traceback": traceback.format_exc()},
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

server/plugins/adapters/underframe_deflection_run.py

@@ -0,0 +1,180 @@
+"""underframe-deflection 算法适配器 (v1.1)。
+
+v1.1 变更：
+  - 入口改为 run_measurement_pipeline（返回 dict，同时落盘 report.json / xlsx / PLY）
+  - 新增 cad_path（CAD 基准 PLY/STL）和 roi_path（ROI JSON）可选输入
+  - 新增 skip_registration / enable_bilateral 配置项
+  - PYTHONPATH 指向 delivery_v1.1
+  - 结果从 report dict 中读取，而非 DeflectionResult 对象字段
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from _plugin_io import (
+    emit_progress,
+    ensure_ascii_ply,
+    first_pointcloud,
+    load_input,
+    write_error_result,
+    write_result,
+)
+
+
+def _status_for(value: float | None, tolerance: float | None) -> str:
+    if value is None or tolerance is None:
+        return "info"
+    if abs(value) <= tolerance:
+        return "pass"
+    if abs(value) <= tolerance * 1.5:
+        return "warning"
+    return "fail"
+
+
+def _safe_float(v: object) -> float | None:
+    try:
+        return float(v)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def main() -> int:
+    payload = load_input(sys.argv)
+    inputs = payload.get("inputs") or {}
+    config = inputs.get("config") or {}
+    out_dir = Path(payload["outDir"])
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        emit_progress(0.05, "加载 underframe_deflection v1.1 算法包")
+        from underframe_deflection.pipeline import run_measurement_pipeline  # type: ignore
+
+        pc_path = first_pointcloud(payload)
+        emit_progress(0.15, f"读取点云：{os.path.basename(pc_path)}")
+
+        # 若是二进制 PLY，先转成 ASCII PLY（算法内置 reader 不依赖 open3d）
+        pc_path = ensure_ascii_ply(pc_path, out_dir / "_ply_cache")
+
+        profile = str(config.get("profile") or "auto")
+        skip_registration = bool(config.get("skipRegistration") or False)
+        enable_bilateral = bool(config.get("enableBilateral") if "enableBilateral" in config else True)
+
+        # 可选 CAD 基准（PLY/STL）和 ROI JSON
+        cad_path = inputs.get("cadPath") or None
+        roi_path = inputs.get("roiPath") or None
+
+        emit_progress(0.20, "调用 run_measurement_pipeline")
+
+        # run_measurement_pipeline 内部会打印进度到 stdout，
+        # 我们在调用前后各报一次进度即可。
+        report: dict = run_measurement_pipeline(
+            input_cloud=pc_path,
+            out_dir=str(out_dir),
+            profile=profile,
+            cad_path=cad_path,
+            roi_path=roi_path,
+            skip_registration=skip_registration,
+            enable_bilateral=enable_bilateral,
+            skip_excel=False,
+        )
+
+        emit_progress(0.92, "整理结果")
+
+        # ── 从 report dict 中提取核心测量值 ──────────────────────────────────
+        deflection = report.get("deflection") or {}
+        left_sel = (deflection.get("left") or {}).get("selected_measurement") or {}
+        right_sel = (deflection.get("right") or {}).get("selected_measurement") or {}
+
+        left_mm = _safe_float(left_sel.get("signed_deflection_mm"))
+        right_mm = _safe_float(right_sel.get("signed_deflection_mm"))
+
+        registration = report.get("registration") or {}
+        reg_rms = _safe_float(registration.get("rms_mm"))
+
+        quality_flags: list[str] = report.get("quality_flags") or []
+
+        # 容差：高铁底架挠度通常要求 ≤ 3 mm（可在 manifest inputs 中暴露）
+        tol = _safe_float(config.get("toleranceMm")) or 3.0
+
+        measurements = [
+            {
+                "name": "左梁挠度",
+                "value": left_mm if left_mm is not None else float("nan"),
+                "unit": "mm",
+                "tolerance": tol,
+                "status": _status_for(left_mm, tol),
+            },
+            {
+                "name": "右梁挠度",
+                "value": right_mm if right_mm is not None else float("nan"),
+                "unit": "mm",
+                "tolerance": tol,
+                "status": _status_for(right_mm, tol),
+            },
+        ]
+
+        if reg_rms is not None:
+            measurements.append(
+                {
+                    "name": "配准 RMS",
+                    "value": reg_rms,
+                    "unit": "mm",
+                    "status": "pass" if reg_rms <= 1.0 else "warning" if reg_rms <= 2.0 else "fail",
+                }
+            )
+
+        # ── 3D 叠加层：优先 out_dir/ply/ 子目录，回退到 out_dir 根目录 ──────────
+        overlay3d: dict = {"kind": "none"}
+        ply_files: list = []
+        ply_dir = out_dir / "ply"
+        if ply_dir.exists():
+            ply_files = sorted(ply_dir.glob("*.ply"))
+        if not ply_files:
+            # 算法直接输出到 out_dir 根目录；优先取 full overlay
+            for name in ("roi_measurement_overlay_full.ply", "roi_cropped_cloud.ply"):
+                candidate = out_dir / name
+                if candidate.exists():
+                    ply_files = [candidate]
+                    break
+            if not ply_files:
+                ply_files = sorted(out_dir.glob("*.ply"))
+        if ply_files:
+            rel = ply_files[0].relative_to(out_dir)
+            overlay3d = {
+                "kind": "ply",
+                "file": str(rel),
+            }
+
+        payload_out = {
+            "schemaVersion": report.get("schema_version", "1.1"),
+            "status": "completed",
+            "measurements": measurements,
+            "overlay3d": overlay3d,
+            "extra": {
+                "algorithmVersion": report.get("algorithm_version"),
+                "qualityFlags": quality_flags,
+                "registration": registration,
+                "deflectionFull": deflection,
+            },
+        }
+        write_result(out_dir, payload_out)
+        emit_progress(1.0, "完成")
+        return 0
+
+    except Exception as exc:
+        traceback.print_exc()
+        write_error_result(
+            out_dir,
+            f"underframe-deflection 计算失败：{exc}",
+            extra={"traceback": traceback.format_exc()},
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

server/plugins/fixtures/flatness-suite.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "status": "completed",
+  "message": "Mock 结果——平台占位用。真实算法 CLI 就绪后将自动替换。",
+  "measurements": [
+    { "name": "平面度（最大偏差）", "value": 0.83, "unit": "mm", "tolerance": 1.0, "status": "pass" },
+    { "name": "轮廓度（mean dist）", "value": 0.42, "unit": "mm", "tolerance": 1.0, "status": "pass" },
+    { "name": "轮廓度（max dist）", "value": 1.28, "unit": "mm", "tolerance": 1.5, "status": "warning" },
+    { "name": "曲率（mean）", "value": 0.012, "unit": "1/mm", "status": "info" },
+    { "name": "ICP fitness", "value": 0.97, "status": "info" },
+    { "name": "ICP RMSE", "value": 0.21, "unit": "mm", "status": "info" }
+  ],
+  "errorStats": {
+    "min": -1.83,
+    "max": 1.28,
+    "mean": 0.04,
+    "stdDev": 0.32,
+    "totalPoints": 1500000,
+    "withinTolerance": 1450000,
+    "outOfTolerance": 50000
+  },
+  "overlay3d": { "kind": "none" },
+  "images": [],
+  "extra": {
+    "plane": { "a": 0.0, "b": 0.0, "c": 1.0, "d": 0.0, "inlierRatio": 0.92 },
+    "icp": { "fitness": 0.97, "rmseMm": 0.21 },
+    "denoise": { "chamferBefore": 0.71, "chamferAfter": 0.18 },
+    "_note": "此为 mock 数据，不代表真实结果；切到 runtime.kind=process 后由算法 CLI 写真实值。"
+  }
+}

server/plugins/manifests/coupler-panel.json

@@ -0,0 +1,49 @@
+{
+  "id": "coupler-panel",
+  "name": "车钩面板检测",
+  "shortName": "coupler-panel",
+  "description": "基于点云的车钩面板偏转角与最大偏差测量（v1.1，来自 alg/delivery_v1.1/coupler_panel_release）。输出 θ_right / θ_ref 偏转角、dx_y / dx_z 最大 x 偏差及 D_y / D_z 面板偏差。",
+  "version": "1.1.0",
+  "schemaVersion": 1,
+  "category": "几何测量",
+  "requiresPointCloud": true,
+  "requiresCad": false,
+  "inputs": [
+    {
+      "name": "profile",
+      "label": "调参档位",
+      "type": "select",
+      "default": "auto",
+      "options": [
+        { "value": "auto",         "label": "自动 (auto)" },
+        { "value": "default",      "label": "默认 (default)" },
+        { "value": "high_density", "label": "高密度 (high_density)" },
+        { "value": "low_density",  "label": "低密度 (low_density)" }
+      ],
+      "description": "建议保持 auto，算法会根据点云密度自动选档。"
+    },
+    {
+      "name": "rightAxisSign",
+      "label": "右向轴符号",
+      "type": "select",
+      "default": "1",
+      "options": [
+        { "value": "1",  "label": "+1（车体右 = +y）" },
+        { "value": "-1", "label": "-1（车体右 = -y）" }
+      ],
+      "description": "若车体「右」方向为 +y 保持 +1；若为 -y 改为 -1。"
+    }
+  ],
+  "runtime": {
+    "kind": "process",
+    "cmd": [
+      "{pythonBin}",
+      "{adapterDir}/coupler_panel_run.py",
+      "{inputJson}"
+    ],
+    "envExtra": {
+      "PYTHONPATH": "{algRoot}/delivery_v1.1/coupler_panel_release"
+    },
+    "timeoutMs": 1200000
+  }
+}

server/plugins/manifests/flatness-suite.json

@@ -0,0 +1,47 @@
+{
+  "id": "flatness-suite",
+  "name": "平整度 / 平面度 / 轮廓测量",
+  "shortName": "flatness-suite",
+  "description": "平整度 / 平面度 / 轮廓 / 曲率 套件（直接调用 alg/平整度、平面度、轮廓测量/ 下的脚本：Plane_Estimation / Contour_Flatness / Curvature_Estimation）。运行需要 numpy + open3d；contour 子模块还需要 torch + trimesh + STL CAD。任意子模块缺依赖时自动跳过并在 message 里说明。",
+  "version": "1.0.0",
+  "schemaVersion": 1,
+  "category": "几何测量",
+  "requiresPointCloud": true,
+  "requiresCad": false,
+  "inputs": [
+    {
+      "name": "module",
+      "label": "测量模块",
+      "type": "select",
+      "default": "all",
+      "options": [
+        { "value": "all", "label": "全部 (plane + contour + curvature)" },
+        { "value": "plane", "label": "平面拟合 (plane)" },
+        { "value": "contour", "label": "轮廓-平整度 (contour，需 STL)" },
+        { "value": "curvature", "label": "曲率估计 (curvature)" }
+      ]
+    },
+    {
+      "name": "voxelSizeMm",
+      "label": "采样 / RANSAC 阈值 (mm)",
+      "type": "number",
+      "default": 1.0,
+      "min": 0.1,
+      "max": 10.0,
+      "step": 0.1,
+      "description": "平面拟合的距离阈值（同时也作为曲率搜索半径的基准 ×2）。"
+    }
+  ],
+  "runtime": {
+    "kind": "process",
+    "cmd": [
+      "{pythonBin}",
+      "{adapterDir}/flatness_suite_run.py",
+      "{inputJson}"
+    ],
+    "envExtra": {
+      "ALG_ROOT": "{algRoot}"
+    },
+    "timeoutMs": 1200000
+  }
+}

server/plugins/manifests/train-measurement.json

@@ -0,0 +1,45 @@
+{
+  "id": "train-measurement",
+  "name": "列车点云测距",
+  "shortName": "train-measurement",
+  "description": "基于配置 YAML 驱动的列车点云批量测距套件（v1.1）。支持「平面到平面 / 点到平面 / 点到点」三类任务，可在 3D 视图中拖拽 ROI 包围盒可视化配置。",
+  "version": "1.1.0",
+  "schemaVersion": 1,
+  "category": "尺寸测量",
+  "requiresPointCloud": true,
+  "requiresCad": false,
+  "uiPanel": "train-measurement",
+  "inputs": [
+    {
+      "name": "configPreset",
+      "label": "测量配置预设",
+      "type": "select",
+      "default": "builtin",
+      "options": [
+        { "value": "builtin", "label": "内置默认 (config/measurements.yaml)" },
+        { "value": "custom",  "label": "自定义 YAML" }
+      ],
+      "description": "选「自定义 YAML」后可在下方编辑器中修改测量任务，或在 3D 视图中拖拽 ROI 包围盒自动生成。"
+    },
+    {
+      "name": "customYaml",
+      "label": "自定义 YAML 配置",
+      "type": "string",
+      "default": "",
+      "description": "仅当上方选「自定义 YAML」时生效。为空时回落到内置默认 measurements.yaml。"
+    }
+  ],
+  "runtime": {
+    "kind": "process",
+    "cmd": [
+      "{pythonBin}",
+      "{adapterDir}/train_measurement_run.py",
+      "{inputJson}"
+    ],
+    "envExtra": {
+      "PYTHONPATH": "{algRoot}/点云测距v1.1/train_measurement_system/src",
+      "TRAIN_MEAS_ROOT": "{algRoot}/点云测距v1.1/train_measurement_system"
+    },
+    "timeoutMs": 1200000
+  }
+}

server/plugins/manifests/underframe-deflection.json

@@ -0,0 +1,61 @@
+{
+  "id": "underframe-deflection",
+  "name": "构架挠度测量",
+  "shortName": "underframe-deflection",
+  "description": "基于点云的高铁底架纵梁挠度测量（v1.1，来自 alg/delivery_v1.1/underframe_deflection）。v1.1 新增 CAD 基准配准与 ROI 裁剪支持，输出左右梁挠度、配准 RMS 及挠度曲线 PLY 叠加层。",
+  "version": "1.1.0",
+  "schemaVersion": 1,
+  "category": "几何测量",
+  "requiresPointCloud": true,
+  "requiresCad": false,
+  "inputs": [
+    {
+      "name": "profile",
+      "label": "调参档位",
+      "type": "select",
+      "default": "auto",
+      "options": [
+        { "value": "auto", "label": "自动 (auto)" },
+        { "value": "M",    "label": "动车组 (M)" },
+        { "value": "TC",   "label": "拖车-控制 (TC)" },
+        { "value": "TP",   "label": "拖车-供电 (TP)" }
+      ]
+    },
+    {
+      "name": "toleranceMm",
+      "label": "挠度容差 (mm)",
+      "type": "number",
+      "default": 3.0,
+      "min": 0.5,
+      "max": 10.0,
+      "step": 0.5,
+      "description": "超出此值标记为 fail，1.5× 以内标记为 warning。"
+    },
+    {
+      "name": "skipRegistration",
+      "label": "跳过 CAD 配准",
+      "type": "boolean",
+      "default": false,
+      "description": "若点云已在 CAD 坐标系中可跳过配准（需提供 CAD 基准时才生效）。"
+    },
+    {
+      "name": "enableBilateral",
+      "label": "启用双边滤波预处理",
+      "type": "boolean",
+      "default": true,
+      "description": "关闭可加速，但对噪声较大的点云精度会下降。"
+    }
+  ],
+  "runtime": {
+    "kind": "process",
+    "cmd": [
+      "{pythonBin}",
+      "{adapterDir}/underframe_deflection_run.py",
+      "{inputJson}"
+    ],
+    "envExtra": {
+      "PYTHONPATH": "{algRoot}/delivery_v1.1"
+    },
+    "timeoutMs": 1200000
+  }
+}

server/plugins/registry.ts

@@ -0,0 +1,105 @@
+/**
+ * 算法插件注册表
+ * ------------------------------------------------------------
+ * 启动时扫描 `server/plugins/manifests/*.json`，把每个 JSON 解析为
+ * `PluginManifest`。注册表是内存只读单例；增减算法只需添加 / 删除
+ * manifest 文件并重启进程（无需改 TS）。
+ *
+ * 路径解析：
+ *   - 开发态：本文件位于 `server/plugins/registry.ts`，manifests 直接在同级
+ *     `manifests/` 目录。
+ *   - 生产态：esbuild 把 `server/_core/index.ts` 打到 `dist/index.js`，本文件
+ *     被打包到 dist/index.js 里。为了让 fs 能找到 manifests，Dockerfile 在
+ *     runner 阶段额外把 `server/plugins/` 拷贝到 `dist/plugins/`，并通过
+ *     环境变量 `PLUGIN_DIR` 覆盖。
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'node:url';
+import type { PluginManifest } from './types.js';
+
+let _cache: Map<string, PluginManifest> | null = null;
+
+/** 返回 manifests / adapters / fixtures 的根目录。 */
+export function pluginDir(): string {
+  if (process.env.PLUGIN_DIR) return process.env.PLUGIN_DIR;
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  // 生产态 here === /app/dist；开发态 here === server/plugins
+  const candidates = [
+    path.join(here),                         // server/plugins（开发）
+    path.join(here, 'plugins'),              // dist/plugins（生产 — Dockerfile 拷贝）
+    path.join(here, '..', 'server', 'plugins'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, 'manifests'))) return c;
+  }
+  // 兜底——开发态相对仓库根
+  return path.resolve(here, '..', '..', 'server', 'plugins');
+}
+
+export function manifestsDir(): string {
+  return path.join(pluginDir(), 'manifests');
+}
+
+export function adaptersDir(): string {
+  return path.join(pluginDir(), 'adapters');
+}
+
+export function fixturesDir(): string {
+  return path.join(pluginDir(), 'fixtures');
+}
+
+/** 从 `manifests/*.json` 重新加载注册表。 */
+export function reloadPlugins(): Map<string, PluginManifest> {
+  const dir = manifestsDir();
+  const result = new Map<string, PluginManifest>();
+  if (!fs.existsSync(dir)) {
+    console.warn('[PluginRegistry] manifests dir not found:', dir);
+    _cache = result;
+    return result;
+  }
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue;
+    const full = path.join(dir, file);
+    try {
+      const m = JSON.parse(fs.readFileSync(full, 'utf-8')) as PluginManifest;
+      if (!m.id || !m.runtime?.kind) {
+        console.warn('[PluginRegistry] skip invalid manifest', file);
+        continue;
+      }
+      if (result.has(m.id)) {
+        console.warn('[PluginRegistry] duplicate plugin id:', m.id);
+      }
+      result.set(m.id, m);
+    } catch (e) {
+      console.error('[PluginRegistry] failed to parse', file, e);
+    }
+  }
+  _cache = result;
+  const ids: string[] = [];
+  result.forEach((_v, k) => ids.push(k));
+  console.log(`[PluginRegistry] loaded ${result.size} plugin(s): ${ids.join(', ')}`);
+  return result;
+}
+
+export function listPlugins(): PluginManifest[] {
+  if (!_cache) reloadPlugins();
+  const arr: PluginManifest[] = [];
+  _cache!.forEach((m) => arr.push(m));
+  return arr;
+}
+
+export function getPlugin(id: string): PluginManifest | undefined {
+  if (!_cache) reloadPlugins();
+  return _cache!.get(id);
+}
+
+/**
+ * Force a full reload from disk and return the new list.
+ * Called by the /api/plugins/reload endpoint so operators can hot-swap
+ * manifests without restarting the server.
+ */
+export function forceReload(): PluginManifest[] {
+  _cache = null;
+  return listPlugins();
+}

server/plugins/types.ts

@@ -0,0 +1,174 @@
+/**
+ * 算法插件（Route B）通用契约
+ * ------------------------------------------------------------
+ * 设计目标：
+ *   - 算法引擎层和 UI 层完全解耦：新增算法只需添加一个 JSON manifest +
+ *     一个 Python 适配器，前端无需任何改动。
+ *   - 输入是 JSON、输出是统一 `result.json`（误差统计 / 测量值 / 图片 /
+ *     3D 叠加层），前端按 manifest 渲染表单、按 result.json 渲染结果。
+ *   - 进度通过子进程 stdout 行 JSON `{"type":"progress","percent":...}`
+ *     上报，由 runner 解析后写入 DB，前端 3s 一次轮询拿到。
+ */
+
+/** 表单字段类型——前端 AlgorithmRunPanel 据此动态渲染表单 */
+export type PluginInputType =
+  | 'number'
+  | 'integer'
+  | 'string'
+  | 'boolean'
+  | 'select'
+  | 'pointcloud'   // 平台自动注入：任务下的点云路径数组
+  | 'cad';         // 平台自动注入：该任务所属车型的 CAD 文件
+
+export interface PluginInputField {
+  /** 参数名（写入 input.json `inputs.config[name]`） */
+  name: string;
+  /** UI 显示标签 */
+  label: string;
+  type: PluginInputType;
+  /** 默认值 */
+  default?: unknown;
+  /** number/integer 范围 */
+  min?: number;
+  max?: number;
+  step?: number;
+  /** select 选项 */
+  options?: { value: string; label: string }[];
+  /** 是否必填（默认 false——使用 default 兜底） */
+  required?: boolean;
+  /** 辅助说明，渲染在表单字段下方 */
+  description?: string;
+}
+
+/** 子进程运行时——真实算法 */
+export interface PluginRuntimeProcess {
+  kind: 'process';
+  /** 子进程命令模板，支持占位符：
+   *   {pythonBin}   → process.env.PYTHON3_PATH || 'python3'
+   *   {inputJson}   → runner 写到 workDir/input.json 的绝对路径
+   *   {workDir}     → workDir 绝对路径
+   *   {adapterDir}  → server/plugins/adapters 的绝对路径
+   *   {algRoot}     → 算法源码根目录（用户工作区下的 alg/）
+   */
+  cmd: string[];
+  /** 额外环境变量；同样支持上面的占位符 */
+  envExtra?: Record<string, string>;
+  /** 超时（毫秒），默认 20 分钟 —— 工信部要求 20 分钟内出结果 */
+  timeoutMs?: number;
+}
+
+/** Mock 运行时——返回预设 fixture，用于未就绪算法保证系统完整运行 */
+export interface PluginRuntimeMock {
+  kind: 'mock';
+  /** 相对 server/plugins/fixtures/ 的 JSON 文件名 */
+  fixture: string;
+  /** 模拟耗时（毫秒），用于演示进度条 */
+  simulateMs?: number;
+}
+
+export type PluginRuntime = PluginRuntimeProcess | PluginRuntimeMock;
+
+/** 插件 manifest（写在 server/plugins/manifests/*.json） */
+export interface PluginManifest {
+  /** 全局唯一 ID（kebab-case，例如 coupler-panel） */
+  id: string;
+  /** 中文名，UI 显示 */
+  name: string;
+  /** 英文短名，日志 / 调试 */
+  shortName?: string;
+  description: string;
+  /** 算法版本，由算法团队维护 */
+  version: string;
+  /** 结果 schema 版本，写入 task_analysis_results.schemaVersion */
+  schemaVersion: number;
+  /** UI 分组标签（可选） */
+  category?: string;
+  /** 表单字段（不含点云/CAD，这两类由平台自动注入） */
+  inputs?: PluginInputField[];
+  /** 是否需要 CAD 文件（true 时若车型下无 CAD 立即报错） */
+  requiresCad?: boolean;
+  /** 是否需要点云（默认 true） */
+  requiresPointCloud?: boolean;
+  runtime: PluginRuntime;
+}
+
+// ---------------------------------------------------------------------------
+// 子进程 ↔ runner 消息协议
+// ---------------------------------------------------------------------------
+
+export interface PluginProgressEvent {
+  type: 'progress';
+  /** [0, 100] —— 我们对外用整数百分比；适配器允许 0~1 浮点，runner 自动转换 */
+  percent: number;
+  message?: string;
+}
+
+/** 测量项（GenericResultView 渲染） */
+export interface PluginMeasurement {
+  name: string;
+  value: number;
+  unit?: string;
+  tolerance?: number;
+  /** pass / warning / fail / info */
+  status?: 'pass' | 'warning' | 'fail' | 'info';
+}
+
+/** 误差统计卡片（与原 task_analysis_results.errorStats 兼容） */
+export interface PluginErrorStats {
+  min: number;
+  max: number;
+  mean: number;
+  stdDev: number;
+  totalPoints?: number;
+  withinTolerance?: number;
+  outOfTolerance?: number;
+}
+
+/** 3D 叠加层——交给 PointCloudViewer.pluginOverlay 消费 */
+export type PluginOverlay3D =
+  | { kind: 'none' }
+  | {
+      /** 顶点色 Float32Array bin（与 smooth_heatmap 同格式）；
+       *  file 是相对 outDir 的相对路径，前端通过
+       *  /api/files/read/analysis/:taskId/:resultId/:file 拉取 */
+      kind: 'vertexColors';
+      file: string;
+      vertexCount: number;
+      dispMin: number;
+      dispMax: number;
+    }
+  | {
+      /** 着色 PLY 叠加文件（同样相对 outDir） */
+      kind: 'ply';
+      file: string;
+    };
+
+/** 算法写出的 result.json（与 INTEGRATION.md 描述对齐） */
+export interface PluginResult {
+  schemaVersion: number;
+  status: 'completed' | 'error';
+  message?: string;
+  measurements?: PluginMeasurement[];
+  errorStats?: PluginErrorStats;
+  overlay3d?: PluginOverlay3D;
+  /** 相对 outDir 的图片文件名（如 plot.png 或 images/foo.png）。
+   *  前端通过 /api/files/read/analysis/:taskId/:resultId/:filename 读取 */
+  images?: string[];
+  /** 算法专属字段；前端折叠在「原始字段」里展示 */
+  extra?: Record<string, unknown>;
+}
+
+/** 写入数据库 task_analysis_results.resultData 的运行时元数据。
+ *  与原有 smooth_heatmap/assembly 沿用同一字段，方便复用前端进度条渲染。 */
+export interface PluginResultData extends Partial<PluginResult> {
+  kind: 'plugin';
+  pluginId: string;
+  /** 0–1 实数，子进程上报后由 runner 转写 */
+  progress?: number;
+  /** 当前阶段，UI 显示 */
+  stage?: string;
+  /** 失败时的错误信息 */
+  error?: string;
+  /** 子进程已结束时的退出码 */
+  exitCode?: number | null;
+}

server/pointcloudSample.ts

@@ -0,0 +1,323 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type SampledPoint = { x: number; y: number; z: number; error: number };
+
+/** 与 fileRoutes 批量采样一致：随机 seek 文本点云行 */
+export async function randomSeekSample(
+  filePath: string,
+  fileSize: number,
+  k: number,
+): Promise<SampledPoint[]> {
+  if (fileSize === 0 || k === 0) return [];
+
+  const PROBE_BYTES = 64 * 1024;
+  const probeBuf = Buffer.alloc(Math.min(PROBE_BYTES, fileSize));
+  const probeFd = fs.openSync(filePath, 'r');
+  fs.readSync(probeFd, probeBuf, 0, probeBuf.length, 0);
+  fs.closeSync(probeFd);
+
+  const probeLines = probeBuf.toString('utf8').split('\n').filter((l) => {
+    const t = l.trim();
+    return t && !t.startsWith('#') && !t.startsWith('//');
+  });
+  const sampleCount = Math.min(probeLines.length, 200);
+  const avgLineBytes =
+    sampleCount > 0
+      ? probeLines.slice(0, sampleCount).reduce((s, l) => s + Buffer.byteLength(l) + 1, 0) / sampleCount
+      : 40;
+
+  console.log(
+    `[SeekSampler] ${path.basename(filePath)}: size=${(fileSize / 1e9).toFixed(2)}GB ` +
+      `avgLine=${avgLineBytes.toFixed(1)}B quota=${k}`,
+  );
+
+  const startOffset = Math.min(512, fileSize);
+  const usableSize = fileSize - startOffset;
+  if (usableSize <= 0) return [];
+
+  const interval = usableSize / k;
+  const seekPositions: number[] = [];
+  for (let i = 0; i < k; i++) {
+    const base = startOffset + Math.floor(i * interval);
+    const jitter = Math.floor(Math.random() * Math.min(interval * 0.5, 1024));
+    seekPositions.push(Math.min(base + jitter, fileSize - 2));
+  }
+  seekPositions.sort((a, b) => a - b);
+
+  const points: SampledPoint[] = [];
+  const fd = fs.openSync(filePath, 'r');
+  const lineBuf = Buffer.alloc(1024);
+
+  try {
+    for (const pos of seekPositions) {
+      if (points.length >= k) break;
+      const bytesRead = fs.readSync(fd, lineBuf, 0, lineBuf.length, pos);
+      if (bytesRead < 4) continue;
+      const chunk = lineBuf.toString('utf8', 0, bytesRead);
+      const nl1 = chunk.indexOf('\n');
+      if (nl1 === -1) continue;
+      const afterFirst = chunk.slice(nl1 + 1);
+      const nl2 = afterFirst.indexOf('\n');
+      const line = (nl2 === -1 ? afterFirst : afterFirst.slice(0, nl2)).trim();
+      if (!line || line.startsWith('#') || line.startsWith('//')) continue;
+      const parts = line.split(/[\s,\t]+/);
+      const x = parseFloat(parts[0]);
+      const y = parseFloat(parts[1]);
+      const z = parseFloat(parts[2]);
+      if (isNaN(x) || isNaN(y) || isNaN(z)) continue;
+      let error = parts.length >= 4 ? parseFloat(parts[3]) : NaN;
+      if (isNaN(error)) error = Math.abs(Math.sin(x * 0.5) * Math.cos(z * 0.5)) * 1.5;
+      points.push({ x, y, z, error });
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return points;
+}
+
+// ─── PLY 格式解析与采样 ───────────────────────────────────────────────────────
+
+/** PLY 属性类型 → 字节数 */
+const PLY_PROP_SIZES: Record<string, number> = {
+  char: 1, int8: 1,
+  uchar: 1, uint8: 1,
+  short: 2, int16: 2,
+  ushort: 2, uint16: 2,
+  int: 4, int32: 4,
+  uint: 4, uint32: 4,
+  float: 4, float32: 4,
+  double: 8, float64: 8,
+};
+
+interface PlyHeader {
+  /** 'ascii' | 'binary_little_endian' | 'binary_big_endian' */
+  format: string;
+  /** 顶点数 */
+  vertexCount: number;
+  /** 顶点元素各属性，顺序与文件一致 */
+  properties: Array<{ name: string; type: string; byteSize: number }>;
+  /** 'end_header\n' 之后的第一个字节偏移量（即数据区起始位置） */
+  dataOffset: number;
+}
+
+/**
+ * 读取 PLY 文件头（总是 ASCII，以 "end_header\n" 结尾）。
+ * 最多读取 16 KB，足以容纳任何合理的 PLY 头。
+ */
+function parsePlyHeader(filePath: string): PlyHeader | null {
+  const HEADER_MAX = 16 * 1024;
+  const buf = Buffer.alloc(HEADER_MAX);
+  const fd = fs.openSync(filePath, 'r');
+  const bytesRead = fs.readSync(fd, buf, 0, HEADER_MAX, 0);
+  fs.closeSync(fd);
+
+  const raw = buf.toString('ascii', 0, bytesRead);
+
+  // 必须以 "ply\n" 开头
+  if (!raw.startsWith('ply\n') && !raw.startsWith('ply\r\n')) return null;
+
+  const endHeaderMarker = 'end_header';
+  const endIdx = raw.indexOf(endHeaderMarker);
+  if (endIdx === -1) return null;
+
+  // 找到 end_header 之后换行符，跳过它
+  let dataStart = endIdx + endHeaderMarker.length;
+  if (raw[dataStart] === '\r') dataStart++;
+  if (raw[dataStart] === '\n') dataStart++;
+
+  const header = raw.slice(0, endIdx);
+  const lines = header.split(/\r?\n/);
+
+  let format = 'ascii';
+  let vertexCount = 0;
+  const properties: PlyHeader['properties'] = [];
+  let inVertex = false;
+
+  for (const line of lines) {
+    const parts = line.trim().split(/\s+/);
+    if (parts[0] === 'format') {
+      format = parts[1] ?? 'ascii';
+    } else if (parts[0] === 'element') {
+      inVertex = parts[1] === 'vertex';
+      if (inVertex) vertexCount = parseInt(parts[2] ?? '0', 10);
+    } else if (parts[0] === 'property' && inVertex) {
+      // skip "property list ..." (face element)
+      if (parts[1] === 'list') { inVertex = false; continue; }
+      const type = parts[1] ?? 'float';
+      const name = parts[2] ?? '';
+      const byteSize = PLY_PROP_SIZES[type] ?? 4;
+      properties.push({ name, type, byteSize });
+    }
+  }
+
+  if (vertexCount <= 0 || properties.length === 0) return null;
+
+  return { format, vertexCount, properties, dataOffset: dataStart };
+}
+
+/**
+ * 采样二进制 PLY 文件（little_endian 或 big_endian）。
+ * 策略：均匀间隔 + 小量随机抖动（与 randomSeekSample 一致）。
+ */
+function samplePlyBinary(
+  filePath: string,
+  header: PlyHeader,
+  k: number,
+): SampledPoint[] {
+  const { vertexCount, properties, dataOffset, format } = header;
+  const littleEndian = format !== 'binary_big_endian';
+
+  const bytesPerVertex = properties.reduce((s, p) => s + p.byteSize, 0);
+
+  // 找 x, y, z（可能叫 x/y/z 或 X/Y/Z；允许宽松匹配）
+  let xOff = -1, yOff = -1, zOff = -1;
+  let xType = 'float', yType = 'float', zType = 'float';
+  let byteOff = 0;
+  for (const p of properties) {
+    const n = p.name.toLowerCase();
+    if (n === 'x') { xOff = byteOff; xType = p.type; }
+    else if (n === 'y') { yOff = byteOff; yType = p.type; }
+    else if (n === 'z') { zOff = byteOff; zType = p.type; }
+    byteOff += p.byteSize;
+  }
+
+  if (xOff === -1 || yOff === -1 || zOff === -1) {
+    console.warn(`[PLY] ${path.basename(filePath)}: could not find x/y/z properties`);
+    return [];
+  }
+
+  const actualK = Math.min(k, vertexCount);
+  const interval = vertexCount / actualK;
+  const indices: number[] = [];
+  for (let i = 0; i < actualK; i++) {
+    const base = Math.floor(i * interval);
+    const jitter = Math.floor(Math.random() * Math.max(1, interval * 0.5));
+    indices.push(Math.min(base + jitter, vertexCount - 1));
+  }
+
+  const recBuf = Buffer.alloc(bytesPerVertex);
+  const fd = fs.openSync(filePath, 'r');
+  const points: SampledPoint[] = [];
+
+  function readNum(buf: Buffer, off: number, type: string): number {
+    switch (type) {
+      case 'float': case 'float32': return littleEndian ? buf.readFloatLE(off) : buf.readFloatBE(off);
+      case 'double': case 'float64': return littleEndian ? buf.readDoubleLE(off) : buf.readDoubleBE(off);
+      case 'int': case 'int32': return littleEndian ? buf.readInt32LE(off) : buf.readInt32BE(off);
+      case 'uint': case 'uint32': return littleEndian ? buf.readUInt32LE(off) : buf.readUInt32BE(off);
+      case 'short': case 'int16': return littleEndian ? buf.readInt16LE(off) : buf.readInt16BE(off);
+      case 'ushort': case 'uint16': return littleEndian ? buf.readUInt16LE(off) : buf.readUInt16BE(off);
+      case 'char': case 'int8': return buf.readInt8(off);
+      case 'uchar': case 'uint8': return buf.readUInt8(off);
+      default: return littleEndian ? buf.readFloatLE(off) : buf.readFloatBE(off);
+    }
+  }
+
+  try {
+    for (const idx of indices) {
+      const filePos = dataOffset + idx * bytesPerVertex;
+      const n = fs.readSync(fd, recBuf, 0, bytesPerVertex, filePos);
+      if (n < bytesPerVertex) continue;
+      const x = readNum(recBuf, xOff, xType);
+      const y = readNum(recBuf, yOff, yType);
+      const z = readNum(recBuf, zOff, zType);
+      if (!isFinite(x) || !isFinite(y) || !isFinite(z)) continue;
+      const error = Math.abs(Math.sin(x * 0.001) * Math.cos(z * 0.001)) * 1.5;
+      points.push({ x, y, z, error });
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  console.log(
+    `[PLY-Binary] ${path.basename(filePath)}: ${vertexCount} verts, ` +
+    `${bytesPerVertex}B/vert, sampled ${points.length}`,
+  );
+  return points;
+}
+
+/**
+ * 采样 ASCII PLY 文件。
+ * 复用 randomSeekSample 的均匀 seek 策略，跳过 PLY 头，从数据区随机取行。
+ */
+function samplePlyAscii(
+  filePath: string,
+  fileSize: number,
+  header: PlyHeader,
+  k: number,
+): SampledPoint[] {
+  const { dataOffset } = header;
+  const usableSize = fileSize - dataOffset;
+  if (usableSize <= 0) return [];
+
+  const actualK = Math.min(k, header.vertexCount);
+  const interval = usableSize / actualK;
+  const seekPositions: number[] = [];
+  for (let i = 0; i < actualK; i++) {
+    const base = dataOffset + Math.floor(i * interval);
+    const jitter = Math.floor(Math.random() * Math.min(interval * 0.5, 1024));
+    seekPositions.push(Math.min(base + jitter, fileSize - 2));
+  }
+
+  const points: SampledPoint[] = [];
+  const fd = fs.openSync(filePath, 'r');
+  const lineBuf = Buffer.alloc(512);
+
+  try {
+    for (const pos of seekPositions) {
+      if (points.length >= actualK) break;
+      const bytesRead = fs.readSync(fd, lineBuf, 0, lineBuf.length, pos);
+      if (bytesRead < 4) continue;
+      const chunk = lineBuf.toString('utf8', 0, bytesRead);
+      const nl1 = chunk.indexOf('\n');
+      if (nl1 === -1) continue;
+      const afterFirst = chunk.slice(nl1 + 1);
+      const nl2 = afterFirst.indexOf('\n');
+      const line = (nl2 === -1 ? afterFirst : afterFirst.slice(0, nl2)).trim();
+      if (!line) continue;
+      const parts = line.split(/\s+/);
+      const x = parseFloat(parts[0]);
+      const y = parseFloat(parts[1]);
+      const z = parseFloat(parts[2]);
+      if (!isFinite(x) || !isFinite(y) || !isFinite(z)) continue;
+      const error = Math.abs(Math.sin(x * 0.001) * Math.cos(z * 0.001)) * 1.5;
+      points.push({ x, y, z, error });
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  console.log(
+    `[PLY-ASCII] ${path.basename(filePath)}: sampled ${points.length} / ${header.vertexCount} verts`,
+  );
+  return points;
+}
+
+/**
+ * 通用采样入口：根据扩展名分发到对应采样器。
+ * 支持 .ply（ASCII + binary），.txt / .xyz / .pts（纯文本行）。
+ */
+export async function samplePointcloudFile(
+  filePath: string,
+  fileSize: number,
+  k: number,
+): Promise<SampledPoint[]> {
+  if (fileSize === 0 || k === 0) return [];
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (ext === '.ply') {
+    const header = parsePlyHeader(filePath);
+    if (!header) {
+      console.warn(`[PLY] ${path.basename(filePath)}: failed to parse header, falling back to text sampler`);
+      return randomSeekSample(filePath, fileSize, k);
+    }
+    if (header.format === 'ascii') {
+      return samplePlyAscii(filePath, fileSize, header, k);
+    }
+    return samplePlyBinary(filePath, header, k);
+  }
+
+  // .txt / .xyz / .pts / etc. — existing text line sampler
+  return randomSeekSample(filePath, fileSize, k);
+}

server/project.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { appRouter } from "./routers";
+import type { TrpcContext } from "./_core/context";
+
+// Mock database functions
+vi.mock("./db", () => ({
+  createProject: vi.fn().mockResolvedValue({
+    id: 1,
+    userId: 1,
+    name: "Test Project",
+    description: "Test Description",
+    status: "uploading",
+    totalPoints: 0,
+    totalChunks: 10,
+    uploadedChunks: 0,
+    totalSize: 0,
+    lodLevels: 0,
+    boundingBox: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }),
+  getProjectsByUserId: vi.fn().mockResolvedValue([
+    {
+      id: 1,
+      userId: 1,
+      name: "Test Project",
+      description: "Test Description",
+      status: "ready",
+      totalPoints: 1000000,
+      totalChunks: 10,
+      uploadedChunks: 10,
+      totalSize: 32000000,
+      lodLevels: 8,
+      boundingBox: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    },
+  ]),
+  getProjectById: vi.fn().mockResolvedValue({
+    id: 1,
+    userId: 1,
+    name: "Test Project",
+    description: "Test Description",
+    status: "ready",
+    totalPoints: 1000000,
+    totalChunks: 10,
+    uploadedChunks: 10,
+    totalSize: 32000000,
+    lodLevels: 8,
+    boundingBox: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }),
+  updateProject: vi.fn().mockResolvedValue(undefined),
+  createAnalysisResult: vi.fn().mockResolvedValue({
+    id: 1,
+    projectId: 1,
+    cadModelId: null,
+    type: "error_analysis",
+    status: "pending",
+    resultData: null,
+    errorStats: null,
+    measurements: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  }),
+  updateAnalysisResult: vi.fn().mockResolvedValue(undefined),
+}));
+
+type AuthenticatedUser = NonNullable<TrpcContext["user"]>;
+
+function createAuthContext(): TrpcContext {
+  const user: AuthenticatedUser = {
+    id: 1,
+    openId: "test-user",
+    email: "test@example.com",
+    name: "Test User",
+    loginMethod: "manus",
+    role: "user",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    lastSignedIn: new Date(),
+  };
+
+  return {
+    user,
+    req: {
+      protocol: "https",
+      headers: {},
+    } as TrpcContext["req"],
+    res: {
+      clearCookie: vi.fn(),
+    } as unknown as TrpcContext["res"],
+  };
+}
+
+describe("project router", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("creates a new project", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.project.create({
+      name: "Test Project",
+      description: "Test Description",
+      totalChunks: 10,
+    });
+
+    expect(result).toBeDefined();
+    expect(result.name).toBe("Test Project");
+    expect(result.status).toBe("uploading");
+  });
+
+  it("lists user projects", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.project.list();
+
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBeGreaterThan(0);
+    expect(result[0].name).toBe("Test Project");
+  });
+
+  it("gets a project by id", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.project.get({ id: 1 });
+
+    expect(result).toBeDefined();
+    expect(result?.id).toBe(1);
+    expect(result?.name).toBe("Test Project");
+  });
+
+  it("updates a project", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.project.update({
+      id: 1,
+      name: "Updated Project",
+      status: "ready",
+    });
+
+    expect(result).toEqual({ success: true });
+  });
+});
+
+describe("analysis router", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("creates an analysis result", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.analysis.create({
+      projectId: 1,
+      type: "error_analysis",
+    });
+
+    expect(result).toBeDefined();
+    expect(result.type).toBe("error_analysis");
+    expect(result.status).toBe("pending");
+  });
+
+  it("runs error analysis simulation", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.analysis.runErrorAnalysis({
+      analysisId: 1,
+      projectId: 1,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.errorStats).toBeDefined();
+    expect(result.errorStats.min).toBeDefined();
+    expect(result.errorStats.max).toBeDefined();
+    expect(result.errorStats.mean).toBeDefined();
+  });
+
+  it("runs measurement simulation", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.analysis.runMeasurement({
+      analysisId: 1,
+      projectId: 1,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.measurements).toBeDefined();
+    expect(Array.isArray(result.measurements)).toBe(true);
+    expect(result.measurements.length).toBeGreaterThan(0);
+  });
+
+  it("runs compression simulation", async () => {
+    const ctx = createAuthContext();
+    const caller = appRouter.createCaller(ctx);
+
+    const result = await caller.analysis.runCompression({
+      analysisId: 1,
+      projectId: 1,
+      compressionRatio: 0.3,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.resultData).toBeDefined();
+    expect(result.resultData.compressionRatio).toBe(0.3);
+  });
+});

server/routers.ts

@@ -0,0 +1,544 @@
+import { COOKIE_NAME } from "@shared/const";
+import { getSessionCookieOptions } from "./_core/cookies";
+import { systemRouter } from "./_core/systemRouter";
+import { publicProcedure, protectedProcedure, router } from "./_core/trpc";
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import * as db from "./db";
+import { enqueueAssemblyInspectionJob } from "./assemblyInspectionJob.js";
+import { enqueueDeviationHeatmapJob } from "./deviationHeatmapJob.js";
+import { enqueueSmoothHeatmapJob } from "./smoothHeatmapJob.js";
+import { stepParseCacheDir } from "./stepParse.js";
+import { listPlugins, getPlugin } from "./plugins/registry.js";
+import { enqueueAlgorithmJob, algorithmJobStats } from "./algorithmJob.js";
+
+export const appRouter = router({
+  system: systemRouter,
+
+  auth: router({
+    me: publicProcedure.query(opts => opts.ctx.user),
+    logout: publicProcedure.mutation(({ ctx }) => {
+      const cookieOptions = getSessionCookieOptions(ctx.req);
+      ctx.res.clearCookie(COOKIE_NAME, { ...cookieOptions, maxAge: -1 });
+      return { success: true } as const;
+    }),
+  }),
+
+  // ─── 车系 ──────────────────────────────────────────────────────────────────
+
+  vehicleSeries: router({
+    list: protectedProcedure.query(async () => {
+      return db.listVehicleSeries();
+    }),
+
+    create: protectedProcedure
+      .input(z.object({
+        name: z.string().min(1).max(100),
+        description: z.string().optional(),
+      }))
+      .mutation(async ({ input }) => {
+        return db.createVehicleSeries({
+          name: input.name,
+          description: input.description ?? null,
+        });
+      }),
+
+    update: protectedProcedure
+      .input(z.object({
+        id: z.number(),
+        name: z.string().min(1).max(100).optional(),
+        description: z.string().optional(),
+      }))
+      .mutation(async ({ input }) => {
+        const { id, ...data } = input;
+        await db.updateVehicleSeries(id, data);
+        return { success: true };
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteVehicleSeries(input.id);
+        return { success: true };
+      }),
+  }),
+
+  // ─── 车型 ──────────────────────────────────────────────────────────────────
+
+  vehicleModel: router({
+    listBySeries: protectedProcedure
+      .input(z.object({ seriesId: z.number() }))
+      .query(async ({ input }) => {
+        return db.listVehicleModelsBySeries(input.seriesId);
+      }),
+
+    get: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .query(async ({ input }) => {
+        return db.getVehicleModelById(input.id);
+      }),
+
+    create: protectedProcedure
+      .input(z.object({
+        seriesId: z.number(),
+        name: z.string().min(1).max(100),
+        description: z.string().optional(),
+      }))
+      .mutation(async ({ input }) => {
+        return db.createVehicleModel({
+          seriesId: input.seriesId,
+          name: input.name,
+          description: input.description ?? null,
+        });
+      }),
+
+    update: protectedProcedure
+      .input(z.object({
+        id: z.number(),
+        name: z.string().min(1).max(100).optional(),
+        description: z.string().optional(),
+      }))
+      .mutation(async ({ input }) => {
+        const { id, ...data } = input;
+        await db.updateVehicleModel(id, data);
+        return { success: true };
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteVehicleModel(input.id);
+        return { success: true };
+      }),
+  }),
+
+  // ─── 车型 CAD 文件 ─────────────────────────────────────────────────────────
+
+  cadFile: router({
+    list: protectedProcedure
+      .input(z.object({ modelId: z.number() }))
+      .query(async ({ input }) => {
+        return db.listModelCadFiles(input.modelId);
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteModelCadFile(input.id);
+        return { success: true };
+      }),
+
+    /** STEP 解析后的 manifest（零件列表与 STL 相对路径） */
+    assemblyManifest: protectedProcedure
+      .input(z.object({ modelId: z.number(), cadFileId: z.number() }))
+      .query(async ({ input }) => {
+        const row = await db.getModelCadFileById(input.cadFileId);
+        if (!row || row.modelId !== input.modelId) {
+          throw new TRPCError({ code: "NOT_FOUND", message: "CAD 文件不存在" });
+        }
+        const manPath = path.join(stepParseCacheDir(input.modelId, input.cadFileId), "manifest.json");
+        if (!fs.existsSync(manPath)) {
+          return { ready: false as const, manifest: null as null };
+        }
+        const manifest = JSON.parse(fs.readFileSync(manPath, "utf-8")) as Record<string, unknown>;
+        return { ready: true as const, manifest };
+      }),
+  }),
+
+  // ─── 任务 CAD 文件 ────────────────────────────────────────────────────────────
+
+  taskCadFile: router({
+    list: protectedProcedure
+      .input(z.object({ taskId: z.number() }))
+      .query(async ({ input }) => {
+        return db.listTaskCadFiles(input.taskId);
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteTaskCadFile(input.id);
+        return { success: true };
+      }),
+  }),
+
+  // ─── 检测任务 ──────────────────────────────────────────────────────────────
+
+  inspectionTask: router({
+    listByModel: protectedProcedure
+      .input(z.object({ modelId: z.number() }))
+      .query(async ({ input }) => {
+        return db.listInspectionTasksByModel(input.modelId);
+      }),
+
+    get: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .query(async ({ input }) => {
+        return db.getInspectionTaskById(input.id);
+      }),
+
+    create: protectedProcedure
+      .input(z.object({
+        modelId: z.number(),
+        name: z.string().min(1).max(255),
+        inspector: z.string().max(100).optional(),
+        notes: z.string().optional(),
+      }))
+      .mutation(async ({ input }) => {
+        return db.createInspectionTask({
+          modelId: input.modelId,
+          name: input.name,
+          inspector: input.inspector ?? null,
+          notes: input.notes ?? null,
+          status: "pending",
+        });
+      }),
+
+    update: protectedProcedure
+      .input(z.object({
+        id: z.number(),
+        name: z.string().max(255).optional(),
+        inspector: z.string().max(100).optional(),
+        notes: z.string().optional(),
+        status: z.enum(["pending", "processing", "completed", "error"]).optional(),
+      }))
+      .mutation(async ({ input }) => {
+        const { id, ...data } = input;
+        await db.updateInspectionTask(id, data);
+        return { success: true };
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteInspectionTask(input.id);
+        return { success: true };
+      }),
+  }),
+
+  // ─── 任务点云文件 ────────────────────────────────────────────────────────────
+
+  pointcloudFile: router({
+    list: protectedProcedure
+      .input(z.object({ taskId: z.number() }))
+      .query(async ({ input }) => {
+        return db.listTaskPointcloudFiles(input.taskId);
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteTaskPointcloudFile(input.id);
+        return { success: true };
+      }),
+  }),
+
+  // ─── 任务分析结果 ────────────────────────────────────────────────────────────
+
+  analysisResult: router({
+    list: protectedProcedure
+      .input(z.object({ taskId: z.number() }))
+      .query(async ({ input }) => {
+        return db.listTaskAnalysisResults(input.taskId);
+      }),
+
+    runAnalysis: protectedProcedure
+      .input(z.object({
+        taskId: z.number(),
+        type: z.enum([
+          "error_analysis",
+          "measurement",
+          "compression",
+          "smooth_heatmap",
+          "assembly_inspection",
+          "obj_deviation",
+        ]),
+        /** 点云采样预算：平滑热力默认 40 万，偏差热力(GPU)可提高到千万级 */
+        totalPoints: z.number().min(50_000).max(20_000_000).optional(),
+        /** 装配检测：指定 STEP 的 model_cad_files.id；不填则取该车型下第一个 STEP */
+        cadFileId: z.number().optional(),
+        /** 装配检测：点云采样点数，默认 10 万 */
+        samplePoints: z.number().min(10_000).max(500_000).optional(),
+        /** 装配检测：合格阈值（mm） */
+        toleranceMm: z.number().positive().max(100).optional(),
+        /** 装配检测：是否生成每零件顶点热力缓存 */
+        includeVertexHeatmap: z.boolean().optional(),
+      }))
+      .mutation(async ({ input }) => {
+        if (input.type === "assembly_inspection") {
+          try {
+            const record = await db.createTaskAnalysisResult({
+              taskId: input.taskId,
+              type: "assembly_inspection",
+              status: "processing",
+            });
+            enqueueAssemblyInspectionJob(record.id, input.taskId, {
+              cadFileId: input.cadFileId,
+              samplePoints: input.samplePoints ?? 100_000,
+              toleranceMm: input.toleranceMm ?? 0.3,
+              includeVertexHeatmap: input.includeVertexHeatmap ?? false,
+            });
+            return { success: true as const, id: record.id, kind: "assembly_inspection" as const };
+          } catch (e: unknown) {
+            const err = e as { errno?: number; message?: string };
+            const msg = err.message ?? "";
+            if (
+              err.errno === 1265 ||
+              err.errno === 1366 ||
+              msg.includes("Data truncated") ||
+              (msg.includes("Incorrect") && msg.includes("column 'type'"))
+            ) {
+              throw new TRPCError({
+                code: "INTERNAL_SERVER_ERROR",
+                message:
+                  "数据库缺少 assembly_inspection 类型枚举，请应用迁移 drizzle/0005_task_analysis_assembly_inspection.sql 后重启。",
+              });
+            }
+            throw e;
+          }
+        }
+
+        if (input.type === "smooth_heatmap") {
+          try {
+            const record = await db.createTaskAnalysisResult({
+              taskId: input.taskId,
+              type: "smooth_heatmap",
+              status: "processing",
+            });
+            enqueueSmoothHeatmapJob(record.id, input.taskId, input.totalPoints ?? 400_000);
+            return { success: true as const, id: record.id, kind: "smooth_heatmap" as const };
+          } catch (e: unknown) {
+            const err = e as { errno?: number; message?: string };
+            const msg = err.message ?? "";
+            if (
+              err.errno === 1265 ||
+              err.errno === 1366 ||
+              msg.includes("Data truncated") ||
+              msg.includes("Incorrect") && msg.includes("column 'type'")
+            ) {
+              throw new TRPCError({
+                code: "INTERNAL_SERVER_ERROR",
+                message:
+                  "数据库 task_analysis_results.type 枚举缺少 smooth_heatmap。请重启服务以应用迁移 drizzle/0004_task_analysis_smooth_heatmap_enum.sql，或在 MySQL 执行 scripts/alter-task-analysis-type-enum.sql。",
+              });
+            }
+            throw e;
+          }
+        }
+
+        if (input.type === "obj_deviation") {
+          try {
+            const record = await db.createTaskAnalysisResult({
+              taskId: input.taskId,
+              type: "obj_deviation",
+              status: "processing",
+            });
+            enqueueDeviationHeatmapJob(record.id, input.taskId, input.totalPoints ?? 5_000_000);
+            return { success: true as const, id: record.id, kind: "obj_deviation" as const };
+          } catch (e: unknown) {
+            const err = e as { errno?: number; message?: string };
+            const msg = err.message ?? "";
+            if (
+              err.errno === 1265 ||
+              err.errno === 1366 ||
+              msg.includes("Data truncated") ||
+              (msg.includes("Incorrect") && msg.includes("column 'type'"))
+            ) {
+              throw new TRPCError({
+                code: "INTERNAL_SERVER_ERROR",
+                message:
+                  "数据库 task_analysis_results.type 枚举缺少 obj_deviation。请应用迁移 drizzle/0006_task_analysis_obj_deviation.sql 后重启。",
+              });
+            }
+            throw e;
+          }
+        }
+
+        const record = await db.createTaskAnalysisResult({
+          taskId: input.taskId,
+          type: input.type,
+          status: "processing",
+        });
+
+        await new Promise(resolve => setTimeout(resolve, 1500));
+
+        const errorStats = {
+          min: 0.001,
+          max: 2.543,
+          mean: 0.856,
+          stdDev: 0.423,
+          totalPoints: 1000000,
+          withinTolerance: 892345,
+          outOfTolerance: 107655,
+        };
+        const measurements = [
+          { name: "车体长度", value: 25700.4, unit: "mm", tolerance: 5, status: "pass" },
+          { name: "车体宽度", value: 3380.1, unit: "mm", tolerance: 3, status: "pass" },
+          { name: "车体高度", value: 3700.2, unit: "mm", tolerance: 3, status: "pass" },
+          { name: "轮对距D1", value: 1435.8, unit: "mm", tolerance: 1, status: "warning" },
+          { name: "转向架轴距", value: 2500.3, unit: "mm", tolerance: 2, status: "pass" },
+        ];
+
+        await db.updateTaskAnalysisResult(record.id, {
+          status: "completed",
+          errorStats,
+          measurements,
+        });
+
+        await db.updateInspectionTask(input.taskId, {
+          status: "completed",
+          completedAt: new Date(),
+        });
+
+        return { success: true, id: record.id, errorStats, measurements };
+      }),
+
+    delete: protectedProcedure
+      .input(z.object({ id: z.number() }))
+      .mutation(async ({ input }) => {
+        await db.deleteTaskAnalysisResult(input.id);
+        return { success: true };
+      }),
+  }),
+
+  // ─── 通用算法插件（Route B） ──────────────────────────────────────────────
+  //
+  // 不为每类算法做独立界面：前端按 manifest.inputs 动态渲染表单 + 多选并发执行；
+  // 后端按 manifest.runtime 启动子进程或返回 mock fixture；
+  // 结果统一落到 task_analysis_results.type = 'plugin'，pluginId 区分。
+
+  algorithm: router({
+    /** 列出所有已注册插件（前端 AlgorithmRunPanel 用） */
+    list: protectedProcedure.query(() => {
+      return {
+        plugins: listPlugins().map((m) => ({
+          id: m.id,
+          name: m.name,
+          shortName: m.shortName,
+          description: m.description,
+          version: m.version,
+          schemaVersion: m.schemaVersion,
+          category: m.category,
+          inputs: m.inputs ?? [],
+          requiresCad: m.requiresCad ?? false,
+          requiresPointCloud: m.requiresPointCloud ?? true,
+          runtimeKind: m.runtime.kind,
+        })),
+        scheduler: algorithmJobStats(),
+      };
+    }),
+
+    /** 单插件执行：创建一条 'plugin' 类型的分析结果记录，丢进并发池 */
+    run: protectedProcedure
+      .input(
+        z.object({
+          taskId: z.number(),
+          pluginId: z.string().min(1),
+          params: z.record(z.string(), z.unknown()).optional(),
+          /** 可选：只处理选中的点云文件 ID（空/缺省 = 任务下全部文件） */
+          pointCloudFileIds: z.array(z.number()).optional(),
+          /** 可选：任务级 CAD 文件 ID（空/缺省 = 不传 CAD） */
+          cadFileIds: z.array(z.number()).optional(),
+        }),
+      )
+      .mutation(async ({ input }) => {
+        const manifest = getPlugin(input.pluginId);
+        if (!manifest) {
+          throw new TRPCError({
+            code: "NOT_FOUND",
+            message: `未注册的算法插件：${input.pluginId}`,
+          });
+        }
+
+        try {
+          const record = await db.createTaskAnalysisResult({
+            taskId: input.taskId,
+            type: "plugin",
+            pluginId: manifest.id,
+            schemaVersion: manifest.schemaVersion,
+            status: "processing",
+          });
+          void enqueueAlgorithmJob(
+            record.id,
+            input.taskId,
+            manifest.id,
+            input.params ?? {},
+            input.pointCloudFileIds,
+            input.cadFileIds,
+          );
+          return {
+            success: true as const,
+            id: record.id,
+            pluginId: manifest.id,
+            schemaVersion: manifest.schemaVersion,
+          };
+        } catch (e: unknown) {
+          const err = e as { errno?: number; message?: string };
+          const msg = err.message ?? "";
+          if (
+            err.errno === 1265 ||
+            err.errno === 1366 ||
+            msg.includes("Data truncated") ||
+            (msg.includes("Incorrect") && msg.includes("column 'type'")) ||
+            msg.includes("Unknown column 'pluginId'")
+          ) {
+            throw new TRPCError({
+              code: "INTERNAL_SERVER_ERROR",
+              message:
+                "数据库缺少 type='plugin' 枚举或 pluginId/schemaVersion 列。请应用迁移 drizzle/0007_task_analysis_plugin_columns.sql 后重启。",
+            });
+          }
+          throw e;
+        }
+      }),
+
+    /** 多插件并发执行：每个插件都通过相同的 run 流程入池 */
+    runBatch: protectedProcedure
+      .input(
+        z.object({
+          taskId: z.number(),
+          /** 可选：只处理选中的点云文件 ID（空/缺省 = 任务下全部文件） */
+          pointCloudFileIds: z.array(z.number()).optional(),
+          /** 可选：任务级 CAD 文件 ID（空/缺省 = 不传 CAD） */
+          cadFileIds: z.array(z.number()).optional(),
+          jobs: z
+            .array(
+              z.object({
+                pluginId: z.string().min(1),
+                params: z.record(z.string(), z.unknown()).optional(),
+              }),
+            )
+            .min(1)
+            .max(16),
+        }),
+      )
+      .mutation(async ({ input }) => {
+        const created: { id: number; pluginId: string }[] = [];
+        for (const job of input.jobs) {
+          const manifest = getPlugin(job.pluginId);
+          if (!manifest) continue;
+          const record = await db.createTaskAnalysisResult({
+            taskId: input.taskId,
+            type: "plugin",
+            pluginId: manifest.id,
+            schemaVersion: manifest.schemaVersion,
+            status: "processing",
+          });
+          void enqueueAlgorithmJob(
+            record.id,
+            input.taskId,
+            manifest.id,
+            job.params ?? {},
+            input.pointCloudFileIds,
+            input.cadFileIds,
+          );
+          created.push({ id: record.id, pluginId: manifest.id });
+        }
+        return { success: true as const, jobs: created, scheduler: algorithmJobStats() };
+      }),
+  }),
+});
+
+export type AppRouter = typeof appRouter;

server/sampleTaskPointclouds.ts

@@ -0,0 +1,47 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as db from './db.js';
+import { samplePointcloudFile, type SampledPoint } from './pointcloudSample.js';
+
+/** 与批量采样接口一致的配额 seek 采样（供热力分析作业复用） */
+export async function sampleTaskPointclouds(taskId: number, budget: number): Promise<SampledPoint[]> {
+  const pcRecords = await db.listTaskPointcloudFiles(taskId);
+  const paths = pcRecords.map((r) => r.filePath);
+  if (paths.length === 0) return [];
+
+  const budgetClamped = Math.min(Math.max(50_000, budget), 20_000_000);
+  const supportedExts = ['.ply', '.txt', '.xyz', '.pts'];
+
+  const fileInfos = paths.map((fp) => ({
+    filePath: fp,
+    name: path.basename(fp),
+    ext: path.extname(fp).toLowerCase(),
+    size: fs.existsSync(fp) ? fs.statSync(fp).size : 0,
+  }));
+  const supportedFiles = fileInfos.filter((f) => supportedExts.includes(f.ext) && f.size > 0);
+  const totalBytes = supportedFiles.reduce((s, f) => s + f.size, 0);
+  if (supportedFiles.length === 0) return [];
+
+  const quotaMap = new Map<string, number>();
+  for (const f of supportedFiles) {
+    const quota =
+      totalBytes > 0
+        ? Math.max(100, Math.round((f.size / totalBytes) * budgetClamped))
+        : Math.floor(budgetClamped / supportedFiles.length);
+    quotaMap.set(f.filePath, quota);
+  }
+
+  const sampledPerFile = await Promise.all(
+    fileInfos.map((f) => {
+      if (!supportedExts.includes(f.ext) || f.size === 0) {
+        return Promise.resolve([] as SampledPoint[]);
+      }
+      return samplePointcloudFile(f.filePath, f.size, quotaMap.get(f.filePath) ?? 0);
+    }),
+  );
+  const allPoints: SampledPoint[] = [];
+  for (const pts of sampledPerFile) {
+    allPoints.push(...pts);
+  }
+  return allPoints;
+}

server/smoothHeatmapJob.ts

@@ -0,0 +1,125 @@
+import * as fs from 'fs';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import * as db from './db.js';
+import {
+  computeCadShellHeatmapFromObj,
+  computeCadShellHeatmapFromStl,
+} from './cadHeatmapCompute.js';
+import { pickCadFileForHeatmap } from './cadFilePick.js';
+import { sampleTaskPointclouds } from './sampleTaskPointclouds.js';
+
+const DATA_DIR = process.env.DATA_DIR || '/data';
+const TASKS_DIR = path.join(DATA_DIR, 'tasks');
+
+async function reportSmoothHeatmapProgress(
+  resultId: number,
+  progress: number,
+  stage: string,
+): Promise<void> {
+  const p = Math.min(1, Math.max(0, progress));
+  await db.updateTaskAnalysisResult(resultId, {
+    resultData: {
+      kind: 'smooth_heatmap',
+      progress: p,
+      stage,
+    },
+  });
+}
+
+function resolveSmoothHeatmapRunnerEntry(): string {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  if (process.env.NODE_ENV === 'production') {
+    return path.join(dir, 'smoothHeatmapJobRunner.js');
+  }
+  return path.join(dir, 'smoothHeatmapJobRunner.ts');
+}
+
+/**
+ * 在子进程中执行平滑热力（STL/OBJ 解析与顶点着色为 CPU 密集同步计算，会长时间阻塞事件循环）。
+ * 主进程只负责 fork，HTTP 与页面刷新可继续响应。
+ */
+export function enqueueSmoothHeatmapJob(resultId: number, taskId: number, totalPoints: number): void {
+  const script = resolveSmoothHeatmapRunnerEntry();
+  const isProd = process.env.NODE_ENV === 'production';
+  const child = fork(script, [String(resultId), String(taskId), String(totalPoints)], {
+    env: { ...process.env },
+    // fork 必须保留 IPC：自定义 stdio 时须显式加入 'ipc'，否则 Node 会抛错
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+    execArgv: isProd ? [] : ['--import', 'tsx'],
+  });
+  child.on('error', (err) => {
+    console.error('[SmoothHeatmapJob] fork 失败:', err);
+  });
+  child.on('exit', (code, signal) => {
+    if (code !== 0 && code != null) {
+      console.error(`[SmoothHeatmapJob] 子进程退出 code=${code} signal=${signal ?? ''}`);
+    }
+  });
+}
+
+/** 供子进程入口调用；也可在测试中直接 await。 */
+export async function runSmoothHeatmapJob(resultId: number, taskId: number, totalPoints: number): Promise<void> {
+  try {
+    await reportSmoothHeatmapProgress(resultId, 0.06, '加载任务与 CAD…');
+    const task = await db.getInspectionTaskById(taskId);
+    if (!task) throw new Error('task not found');
+
+    const cadFiles = await db.listModelCadFiles(task.modelId);
+    const picked = pickCadFileForHeatmap(cadFiles);
+    if (!picked) {
+      throw new Error(
+        '当前车型下未找到 STL 或 OBJ 的 CAD。请在与该检测任务相同的车型下上传 CAD，或确认文件扩展名为 .stl / .obj',
+      );
+    }
+    if (!fs.existsSync(picked.file.filePath)) throw new Error('CAD 文件不存在');
+
+    await reportSmoothHeatmapProgress(resultId, 0.14, '点云采样中…');
+    const allPoints = await sampleTaskPointclouds(taskId, totalPoints);
+    if (allPoints.length === 0) throw new Error('任务下无可用点云采样');
+
+    await reportSmoothHeatmapProgress(resultId, 0.36, '读取 CAD 文件…');
+    const cadBuf = fs.readFileSync(picked.file.filePath);
+
+    await reportSmoothHeatmapProgress(resultId, 0.42, '解析网格并计算顶点热力（耗时较长）…');
+    const computed =
+      picked.ext === 'stl'
+        ? computeCadShellHeatmapFromStl(cadBuf, allPoints)
+        : computeCadShellHeatmapFromObj(cadBuf, allPoints);
+    if (!computed) throw new Error('热力计算失败');
+
+    await reportSmoothHeatmapProgress(resultId, 0.88, '写入热力缓存文件…');
+    const outDir = path.join(TASKS_DIR, String(taskId), 'analysis');
+    fs.mkdirSync(outDir, { recursive: true });
+    const binName = `heatmap_${resultId}.bin`;
+    const binPath = path.join(outDir, binName);
+    fs.writeFileSync(
+      binPath,
+      Buffer.from(computed.colors.buffer, computed.colors.byteOffset, computed.colors.byteLength),
+    );
+
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'completed',
+      resultData: {
+        kind: 'smooth_heatmap',
+        vertexCount: computed.vertexCount,
+        dispMin: computed.dispMin,
+        dispMax: computed.dispMax,
+        binName,
+      },
+    });
+    console.log(
+      `[SmoothHeatmapJob] ok resultId=${resultId} taskId=${taskId} verts=${computed.vertexCount}`,
+    );
+  } catch (err) {
+    console.error('[SmoothHeatmapJob]', err);
+    await db.updateTaskAnalysisResult(resultId, {
+      status: 'error',
+      resultData: {
+        kind: 'smooth_heatmap',
+        error: err instanceof Error ? err.message : String(err),
+      },
+    });
+  }
+}

server/smoothHeatmapJobRunner.ts

@@ -0,0 +1,26 @@
+/**
+ * 独立进程入口：平滑热力在子进程跑，避免阻塞主进程事件循环（HTTP / Vite）。
+ * 开发：node --import tsx server/smoothHeatmapJobRunner.ts <resultId> <taskId> <totalPoints>
+ * 生产：node dist/smoothHeatmapJobRunner.js ...
+ */
+import 'dotenv/config';
+import { runSmoothHeatmapJob } from './smoothHeatmapJob.js';
+
+const [, , a, b, c] = process.argv;
+const resultId = Number(a);
+const taskId = Number(b);
+const totalPoints = Number(c);
+
+if (!Number.isFinite(resultId) || !Number.isFinite(taskId) || resultId <= 0 || taskId <= 0) {
+  console.error('[SmoothHeatmapJobRunner] 用法: <resultId> <taskId> <totalPoints>');
+  process.exit(1);
+}
+
+const pts = Number.isFinite(totalPoints) && totalPoints > 0 ? totalPoints : 400_000;
+
+runSmoothHeatmapJob(resultId, taskId, pts)
+  .then(() => process.exit(0))
+  .catch((e) => {
+    console.error('[SmoothHeatmapJobRunner]', e);
+    process.exit(1);
+  });

server/stepParse.ts

@@ -0,0 +1,143 @@
+import { spawnSync, type SpawnSyncOptions } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DATA_DIR = process.env.DATA_DIR || '/data';
+
+export function stepParseCacheDir(modelId: number, cadFileId: number): string {
+  return path.join(DATA_DIR, 'models', String(modelId), 'cad', '.step_parse', String(cadFileId));
+}
+
+function scriptPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(here, '..', 'scripts', 'step_parse_mvp.py');
+}
+
+/**
+ * 不依赖 existsSync：挂载/命名空间下路径探测可能不准；子进程 PATH 过短会导致 `python3` ENOENT。
+ * 顺序尝试可执行文件，仅对 ENOENT 换下一个。
+ */
+function python3Candidates(): string[] {
+  const fromEnv = process.env.PYTHON3_PATH?.trim();
+  const list: string[] = [];
+  if (fromEnv) list.push(fromEnv);
+  if (process.platform !== 'win32') {
+    list.push('/usr/bin/python3', '/usr/local/bin/python3');
+  }
+  list.push('python3');
+  return Array.from(new Set(list));
+}
+
+function spawnStepParseSync(script: string, stepAbsolutePath: string, outDir: string) {
+  const envBase: NodeJS.ProcessEnv = {
+    ...process.env,
+    PYTHONUNBUFFERED: '1',
+    // 保证按名查找 python3 时能找到 Debian/Ubuntu 常见路径
+    PATH: `/usr/bin:/usr/local/bin:/bin:/usr/sbin:${process.env.PATH ?? ''}`,
+  };
+  const opts: SpawnSyncOptions = {
+    encoding: 'utf-8',
+    maxBuffer: 64 * 1024 * 1024,
+    timeout: 60 * 60 * 1000,
+    env: envBase,
+  };
+
+  const args = [script, stepAbsolutePath, outDir];
+  let lastErr: NodeJS.ErrnoException | undefined;
+
+  for (const py of python3Candidates()) {
+    const r = spawnSync(py, args, opts);
+    if (!r.error) {
+      return r;
+    }
+    lastErr = r.error as NodeJS.ErrnoException;
+    if (lastErr.code !== 'ENOENT') {
+      throw new Error(
+        `无法启动 Python（${py}）：${lastErr.message}。PYTHON3_PATH=${process.env.PYTHON3_PATH ?? '(未设置)'}`,
+      );
+    }
+  }
+
+  throw new Error(
+    `无法启动 Python（已尝试: ${python3Candidates().join(' → ')}）：${lastErr?.message ?? 'ENOENT'}。` +
+      `请确认镜像已安装 python3（docker/Dockerfile.dev），或设置 PYTHON3_PATH 为实际解释器路径。`,
+  );
+}
+
+export type StepManifestPart = { id: string; name: string; stlRelative: string };
+
+export type StepManifest = {
+  ok: boolean;
+  parts: StepManifestPart[];
+  sourceStep?: string;
+};
+
+/** cadquery/OCP 可能在 stdout 打印非 JSON 日志，不能只取最后一行 */
+function parseJsonResultFromProcessOutput(stdout: string, stderr: string): {
+  ok?: boolean;
+  error?: string;
+  parts?: StepManifestPart[];
+} | null {
+  const text = `${stdout || ''}\n${stderr || ''}`;
+  let last: { ok?: boolean; error?: string; parts?: StepManifestPart[] } | null = null;
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{') || !t.endsWith('}')) continue;
+    try {
+      const o = JSON.parse(t) as { ok?: boolean };
+      if (typeof o.ok === 'boolean') {
+        last = o as { ok?: boolean; error?: string; parts?: StepManifestPart[] };
+      }
+    } catch {
+      /* 单行非完整 JSON */
+    }
+  }
+  return last;
+}
+
+/**
+ * 调用 Python cadquery 将 STEP 三角化为每零件 STL，并写入 manifest.json。
+ * @returns manifest 或抛出带 message 的错误
+ */
+export function runStepParseMvp(stepAbsolutePath: string, outDir: string): StepManifest {
+  fs.mkdirSync(outDir, { recursive: true });
+  const script = scriptPath();
+  if (!fs.existsSync(script)) {
+    throw new Error(`未找到 STEP 解析脚本: ${script}`);
+  }
+  const r = spawnStepParseSync(script, stepAbsolutePath, outDir);
+
+  const out = (v: string | Buffer | null | undefined) =>
+    v == null ? '' : typeof v === 'string' ? v : v.toString('utf-8');
+  const combined = `${out(r.stdout)}\n${out(r.stderr)}`;
+  let parsed = parseJsonResultFromProcessOutput(out(r.stdout), out(r.stderr));
+
+  const resultFile = path.join(outDir, '_parse_result.json');
+  if ((!parsed || typeof parsed.ok !== 'boolean') && fs.existsSync(resultFile)) {
+    try {
+      parsed = JSON.parse(fs.readFileSync(resultFile, 'utf-8')) as typeof parsed;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  if (!parsed || typeof parsed.ok !== 'boolean') {
+    const sig = r.signal != null ? ` signal=${r.signal}` : '';
+    throw new Error(
+      `STEP 解析无有效 JSON 结果（exit=${r.status ?? 'null'}${sig}）。` +
+        `请确认 cadquery 可用。输出摘录：\n${combined.trim().slice(-2500)}`,
+    );
+  }
+
+  if (!parsed.ok) {
+    throw new Error(parsed.error || 'STEP 解析失败');
+  }
+
+  const manFile = path.join(outDir, 'manifest.json');
+  if (!fs.existsSync(manFile)) {
+    throw new Error(`未生成 manifest.json: ${manFile}`);
+  }
+  const raw = JSON.parse(fs.readFileSync(manFile, 'utf-8')) as StepManifest;
+  return raw;
+}

server/storage.ts

@@ -0,0 +1,102 @@
+// Preconfigured storage helpers for Manus WebDev templates
+// Uses the Biz-provided storage proxy (Authorization: Bearer <token>)
+
+import { ENV } from './_core/env';
+
+type StorageConfig = { baseUrl: string; apiKey: string };
+
+function getStorageConfig(): StorageConfig {
+  const baseUrl = ENV.forgeApiUrl;
+  const apiKey = ENV.forgeApiKey;
+
+  if (!baseUrl || !apiKey) {
+    throw new Error(
+      "Storage proxy credentials missing: set BUILT_IN_FORGE_API_URL and BUILT_IN_FORGE_API_KEY"
+    );
+  }
+
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+
+function buildUploadUrl(baseUrl: string, relKey: string): URL {
+  const url = new URL("v1/storage/upload", ensureTrailingSlash(baseUrl));
+  url.searchParams.set("path", normalizeKey(relKey));
+  return url;
+}
+
+async function buildDownloadUrl(
+  baseUrl: string,
+  relKey: string,
+  apiKey: string
+): Promise<string> {
+  const downloadApiUrl = new URL(
+    "v1/storage/downloadUrl",
+    ensureTrailingSlash(baseUrl)
+  );
+  downloadApiUrl.searchParams.set("path", normalizeKey(relKey));
+  const response = await fetch(downloadApiUrl, {
+    method: "GET",
+    headers: buildAuthHeaders(apiKey),
+  });
+  return (await response.json()).url;
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function normalizeKey(relKey: string): string {
+  return relKey.replace(/^\/+/, "");
+}
+
+function toFormData(
+  data: Buffer | Uint8Array | string,
+  contentType: string,
+  fileName: string
+): FormData {
+  const blob =
+    typeof data === "string"
+      ? new Blob([data], { type: contentType })
+      : new Blob([data as any], { type: contentType });
+  const form = new FormData();
+  form.append("file", blob, fileName || "file");
+  return form;
+}
+
+function buildAuthHeaders(apiKey: string): HeadersInit {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+export async function storagePut(
+  relKey: string,
+  data: Buffer | Uint8Array | string,
+  contentType = "application/octet-stream"
+): Promise<{ key: string; url: string }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  const uploadUrl = buildUploadUrl(baseUrl, key);
+  const formData = toFormData(data, contentType, key.split("/").pop() ?? key);
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: buildAuthHeaders(apiKey),
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const message = await response.text().catch(() => response.statusText);
+    throw new Error(
+      `Storage upload failed (${response.status} ${response.statusText}): ${message}`
+    );
+  }
+  const url = (await response.json()).url;
+  return { key, url };
+}
+
+export async function storageGet(relKey: string): Promise<{ key: string; url: string; }> {
+  const { baseUrl, apiKey } = getStorageConfig();
+  const key = normalizeKey(relKey);
+  return {
+    key,
+    url: await buildDownloadUrl(baseUrl, key, apiKey),
+  };
+}