dsh-lh-data 0.1.0

package/src/admin-contract.ts

@@ -0,0 +1,351 @@
+/**
+ * 设置页管理接口的**双半身契约**。
+ *
+ * 主机半身（`admin.ts` / `admin-http.ts`）与浏览器半身（`client/settings/*`）
+ * 共用本文件，因此有两条硬约束：
+ *
+ * 1. **禁止 import 任何 node 内置模块** —— 本文件会被打进浏览器 bundle
+ *    （`tsdown.config.ts` 的 client 产物）；
+ * 2. **只有常量与类型**，不含任何运行时逻辑 —— 浏览器 bundle 是 CJS 工厂包，
+ *    多引一个模块就多一份内联体积。
+ *
+ * 存在理由：浏览器拿不到主机的 `Config`。`viewRoutePrefix` 之类是用户在 dsh
+ * 配置里改的，如果路由前缀两边各写一份字面量，改配置就会让设置页悄悄失联。
+ * 下面的常量是唯一真源，主机注册路由和浏览器拼 URL 都从这里取。
+ */
+
+// ── 路由 ─────────────────────────────────────────────────────────────────
+
+/** 管理接口的路由前缀。与视图接口（可配置）解耦，固定不变。 */
+export const ADMIN_ROUTE_PREFIX = '/api/lh-data'
+
+/** 管理接口的固定挂载点：`${ADMIN_ROUTE_PREFIX}/admin`。 */
+export const ADMIN_API_BASE: string = `${ADMIN_ROUTE_PREFIX}/admin`
+
+// ── 设置菜单 ─────────────────────────────────────────────────────────────
+
+/**
+ * `settings.section` 的注册 id。既有分区用的是 0（general）/ 10（models）/
+ * 15（plugins）/ 20（agent-presets），这里取 100 排在最后。
+ */
+export const ADMIN_SECTION_ID = 'lh-data'
+export const ADMIN_SECTION_ORDER = 100
+export const ADMIN_SECTION_LABEL = '数据集'
+
+// ── 列表分页 ─────────────────────────────────────────────────────────────
+
+export const ADMIN_PAGE_SIZE = 20
+export const ADMIN_MAX_PAGE_SIZE = 100
+
+// ── 表数据分页（查看某个数据集的行） ───────────────────────────────────────
+
+/** 表数据默认每页行数。 */
+export const ADMIN_ROW_PAGE_SIZE = 20
+/** 表数据每页行数的上限。 */
+export const ADMIN_ROW_MAX_PAGE_SIZE = 100
+/** 行号列：物理表的自增主键，只用于稳定排序与前端行键，不算业务列。 */
+export const ADMIN_ROW_ID_COLUMN = '_row_id'
+
+// ── 录入上限（前端 maxLength 与后端校验共用） ─────────────────────────────
+
+export const ADMIN_MAX_NAME_LENGTH = 80
+export const ADMIN_MAX_DESCRIPTION_LENGTH = 500
+export const ADMIN_MAX_SOURCE_LENGTH = 1024
+export const ADMIN_MAX_COLUMNS = 64
+export const ADMIN_MAX_QUERY_LENGTH = 80
+/** 单列样例值的个数上限（前端拼接与后端夹紧共用）。 */
+export const ADMIN_MAX_SAMPLE_VALUES = 5
+/** 单个样例值的字符上限。 */
+export const ADMIN_MAX_SAMPLE_LENGTH = 40
+
+// ── 数据源录入上限 ───────────────────────────────────────────────────────
+
+export const ADMIN_MAX_SOURCE_NAME_LENGTH = 80
+export const ADMIN_MAX_HOST_LENGTH = 255
+export const ADMIN_MAX_DATABASE_LENGTH = 128
+export const ADMIN_MAX_USERNAME_LENGTH = 128
+export const ADMIN_MAX_PASSWORD_LENGTH = 256
+export const ADMIN_MIN_PORT = 1
+export const ADMIN_MAX_PORT = 65535
+export const ADMIN_MAX_POOL_MAX = 100
+
+/** 数据源类型下拉的可选项（顺序即展示顺序）。 */
+export const ADMIN_SOURCE_TYPES: readonly string[] = ['mysql', 'postgresql']
+
+export const ADMIN_SOURCE_TYPE_LABELS: Readonly<Record<string, string>> = {
+  mysql: 'MySQL',
+  postgresql: 'PostgreSQL',
+}
+
+/** 各类型的默认端口（前端带出与后端兜底共用）。 */
+export const ADMIN_SOURCE_DEFAULT_PORTS: Readonly<Record<string, number>> = {
+  mysql: 3306,
+  postgresql: 5432,
+}
+
+// ── 类型 ─────────────────────────────────────────────────────────────────
+
+/** 与 `parse.ts` 的 `ColumnType` 同构（本文件不能 import 主机侧的 parse）。 */
+export type AdminColumnType = 'text' | 'numeric' | 'boolean' | 'date'
+
+/** 人类可读的类型名：前端下拉与列结构表共用，避免两处各写一份中文。 */
+export const ADMIN_COLUMN_TYPE_LABELS: Readonly<Record<AdminColumnType, string>> = {
+  text: '文本',
+  numeric: '数值',
+  boolean: '布尔',
+  date: '日期',
+}
+
+/** 列类型下拉的可选项（顺序即展示顺序）。 */
+export const ADMIN_COLUMN_TYPES: readonly AdminColumnType[] = ['text', 'numeric', 'boolean', 'date']
+
+export type DatasetStatus = 'importing' | 'ready' | 'failed'
+
+/** 设置页可见的一列。列名是业务表头（可含中文），不含任何物理表信息。 */
+export interface DatasetColumnView {
+  /** 原始表头。 */
+  name: string
+  /** SQL 中使用的列名（重名时追加 `_2`）。 */
+  sanitizedName: string
+  type: AdminColumnType
+  nullable: boolean
+  description: string
+  sample: unknown[]
+}
+
+/** 新建数据集时提交的一列。 */
+export interface DatasetColumnSpec {
+  name: string
+  type: AdminColumnType
+  nullable?: boolean
+  description?: string
+}
+
+/** 列表里的一条数据集（跨工作区聚合；不含列结构，避免列表响应膨胀）。 */
+export interface DatasetAdminView {
+  id: string
+  scopeKey: string
+  name: string
+  description: string | null
+  sourcePath: string | null
+  rowCount: number
+  columnCount: number
+  status: DatasetStatus
+  error: string | null
+  createdAt: number
+  updatedAt: number
+}
+
+/** 详情 = 列表项 + 只读列结构。 */
+export interface DatasetDetailView extends DatasetAdminView {
+  columns: DatasetColumnView[]
+}
+
+/**
+ * 一页表数据（只读）。`columns` 只含业务列，`rows` 每行额外带 `_row_id`
+ * （`ADMIN_ROW_ID_COLUMN`）作为稳定行键；`page` 由服务端夹到分页边界内。
+ */
+export interface DatasetRowsResult {
+  columns: string[]
+  rows: Record<string, unknown>[]
+  page: number
+  pageSize: number
+  /** `COUNT(*)` 得到的真实行数（元数据里的 rowCount 可能与之不符）。 */
+  total: number
+  totalPages: number
+}
+
+/** 设置页可见的一个工作区。 */
+export interface ScopeView {
+  scopeKey: string
+  lastSeen: number
+}
+
+/** 单个工作区读取失败时的降级提示（不阻断整页）。 */
+export interface AdminWarning {
+  scopeKey: string
+  message: string
+}
+
+export interface ListDatasetsResult {
+  items: DatasetAdminView[]
+  total: number
+  page: number
+  pageSize: number
+  /** 命中 `adminMaxDatasets` 上限被截断。 */
+  truncated: boolean
+  warnings: AdminWarning[]
+}
+
+/** 新建空数据集：列名 / 类型 / 可空性提交后冻结，说明与样例仍可改。 */
+export interface CreateDatasetRequest {
+  scopeKey: string
+  name: string
+  description?: string
+  sourcePath?: string | null
+  columns: DatasetColumnSpec[]
+}
+
+/**
+ * 列定义的补丁：只改「说明」与「样例」这两项纯元数据。
+ * 列名 / 类型 / 可空性对应物理表 DDL，设置页不可改。
+ * 用 `sanitizedName` 定位列——原始表头 `name` 在重名列上会重复，不能当键。
+ */
+export interface DatasetColumnPatch {
+  /** 列的 SQL 名（去重后唯一）。 */
+  sanitizedName: string
+  description?: string
+  sample?: unknown[]
+}
+
+// ── 数据源 ───────────────────────────────────────────────────────────────
+
+/**
+ * 设置页可见的一条数据源。
+ * **密码永不回显**：只给 `hasPassword`，前端据此显示「已设置 · 不可查看」。
+ */
+export interface DataSourceView {
+  id: string
+  name: string
+  type: string
+  host: string
+  port: number
+  database: string
+  username: string
+  hasPassword: boolean
+  sslMode: string | null
+  poolMax: number | null
+  description: string | null
+  status: string
+  lastError: string | null
+  lastCheckedAt: number | null
+  createdAt: number
+  updatedAt: number
+}
+
+export interface ConnectionTestView {
+  success: boolean
+  latency: number
+  version: string | null
+  error: string | null
+}
+
+/** 新建数据源。`test` 为 true 时先测连，不通就不落库。 */
+export interface CreateDataSourceRequest {
+  name: string
+  type: string
+  host: string
+  port?: number | null
+  database: string
+  username: string
+  password?: string
+  sslMode?: string | null
+  poolMax?: number | null
+  description?: string | null
+  test?: boolean
+}
+
+/** 改数据源：字段缺省表示不改；`password` 给了字符串就替换（空串表示置空）。 */
+export interface PatchDataSourceRequest {
+  name?: string
+  type?: string
+  host?: string
+  port?: number | null
+  database?: string
+  username?: string
+  password?: string
+  sslMode?: string | null
+  poolMax?: number | null
+  description?: string | null
+  test?: boolean
+}
+
+/** `POST /sources/test` 的请求体：给 `source` 就测已登记的，给全参数就测未保存的草稿。 */
+export interface TestDataSourceRequest {
+  source?: string
+  type?: string
+  host?: string
+  port?: number | null
+  database?: string
+  username?: string
+  password?: string
+  sslMode?: string | null
+  poolMax?: number | null
+}
+
+export interface SourceTableView {
+  tableName: string
+  schemaName: string | null
+  /** 远端估计行数；-1 表示未知。 */
+  rowCount: number
+  primaryKey: string | null
+  columns: {
+    name: string
+    type: AdminColumnType
+    nullable: boolean
+    description: string | null
+  }[]
+}
+
+export interface ListSourceTablesResult {
+  /** 实际使用的 schema（MySQL 为库名，PostgreSQL 默认 public）。 */
+  schema: string | null
+  /** 可选 schema 列表（PostgreSQL 多个，MySQL 一个）。 */
+  schemas: string[]
+  tables: SourceTableView[]
+}
+
+/** `POST /sources/:id/import`。 */
+export interface ImportSourceTableRequest {
+  scopeKey: string
+  tableName: string
+  schemaName?: string | null
+  name?: string | null
+  limit?: number | null
+}
+
+export interface ImportSourceTableResult {
+  datasetId: string
+  name: string
+  rowCount: number
+  columnCount: number
+  status: 'ready' | 'running'
+  jobId?: string
+}
+
+/** 字段缺省表示不改动。 */
+export interface PatchDatasetRequest {
+  name?: string
+  description?: string | null
+  sourcePath?: string | null
+  columns?: DatasetColumnPatch[]
+}
+
+export type AdminErrorCode =
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'METHOD_NOT_ALLOWED'
+  | 'BAD_REQUEST'
+  | 'PAYLOAD_TOO_LARGE'
+  | 'READ_ONLY'
+  | 'ADMIN_DISABLED'
+  | 'SCOPE_UNKNOWN'
+  | 'DUPLICATE_NAME'
+  | 'INVALID_COLUMNS'
+  | 'QUERY_FAILED'
+  | 'SOURCE_DISABLED'
+  | 'DRIVER_MISSING'
+  | 'SOURCE_UNREACHABLE'
+  | 'IMPORT_FAILED'
+
+/** 错误响应体。主机侧统一脱敏：不回显 SQL 与物理表名。 */
+export interface AdminErrorBody {
+  error: { code: AdminErrorCode; message: string }
+}
+
+/** 管理接口是否可写（前端据此置灰按钮）。 */
+export interface AdminCapabilities {
+  writable: boolean
+  reason: string
+}

package/src/admin-http.ts

@@ -0,0 +1,254 @@
+/**
+ * 设置页管理接口的 HTTP 路由 —— 与视图路由同源（自建前缀 + `connection` 鉴权），
+ * 但不接受任何 SQL：所有读写都走 `admin.ts` 的服务函数，物理表名与 SQL 不出现在接口里。
+ *
+ * 路由表（固定挂在 `ADMIN_API_BASE = /api/lh-data/admin`）：
+ *   GET    /scopes                 列出已知工作区
+ *   GET    /datasets               聚合列表（?q=&page=&pageSize=）
+ *   POST   /datasets               新建空数据集（body 含 scopeKey 与列定义）
+ *   GET    /datasets/:id?scope=    单条详情
+ *   GET    /datasets/:id/rows?scope=&page=&pageSize=   分页查看表数据（只读）
+ *   PATCH  /datasets/:id?scope=    改名 / 改描述 / 改来源
+ *   DELETE /datasets/:id?scope=    连同物理表与元数据删除
+ *
+ * 数据源（datasourceEnabled=false 时整组不注册）：
+ *   GET    /sources                数据源列表（脱敏，不含密码）
+ *   POST   /sources                新建数据源（body.test=true 时先测连）
+ *   POST   /sources/test           测试连接（已登记的 source，或未保存的完整参数）
+ *   GET    /sources/:id            单条详情
+ *   PATCH  /sources/:id            改连接参数 / 密码 / 名称 / 描述
+ *   DELETE /sources/:id            删除数据源
+ *   GET    /sources/:id/tables?schema=&q=   浏览远端表
+ *   POST   /sources/:id/import     把远端表导入指定工作区
+ *
+ * scope 一律由写操作的调用方从「已知工作区列表」里回传，不接收任意路径输入。
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { ADMIN_API_BASE, type CreateDatasetRequest, type PatchDatasetRequest } from './admin-contract'
+import {
+  createDataset,
+  createDataSource,
+  deleteDataset,
+  deleteDataSource,
+  getDataset,
+  getDataSource,
+  importSourceTable,
+  listDatasetRows,
+  listDatasets,
+  listDataSources,
+  listScopes,
+  listSourceTables,
+  patchDataset,
+  patchDataSource,
+  testDataSource,
+  AdminServiceError,
+} from './admin'
+import { AdminValidationError } from './admin-validate'
+import type { DataServices } from './store'
+import {
+  authorize,
+  readJsonBody,
+  sendError,
+  sendJson,
+  type RouteRequest,
+  type RouteResponse,
+} from './http-common'
+
+type Resource =
+  | { kind: 'scopes' }
+  | { kind: 'datasets'; id?: string; rows?: boolean }
+  | { kind: 'sources'; id?: string; action?: 'test' | 'tables' | 'import' }
+
+/** `/api/lh-data/admin` 之后的路径解析。 */
+function parseAdminPath(pathname: string): Resource | undefined {
+  const base = ADMIN_API_BASE
+  const rest = pathname.slice(base.length).replace(/^\/+/, '').replace(/\/+$/, '')
+  if (rest === '' || rest === 'scopes') return { kind: 'scopes' }
+  if (rest === 'datasets') return { kind: 'datasets' }
+  if (rest === 'sources') return { kind: 'sources' }
+  // `sources/test` 必须优先于 `:id` 匹配，否则会被当成 id=test 的数据源。
+  if (rest === 'sources/test') return { kind: 'sources', action: 'test' }
+  const parts = rest.split('/')
+  if (parts[0] === 'sources' && parts[1] !== undefined && parts[1].length > 0) {
+    const id = decodeURIComponent(parts[1])
+    if (parts.length === 2) return { kind: 'sources', id }
+    if (parts.length === 3 && parts[2] === 'tables') return { kind: 'sources', id, action: 'tables' }
+    if (parts.length === 3 && parts[2] === 'import') return { kind: 'sources', id, action: 'import' }
+    return undefined
+  }
+  if (parts[0] === 'datasets' && parts[1] !== undefined && parts[1].length > 0) {
+    const id = decodeURIComponent(parts[1])
+    // `/datasets/:id/rows` —— 表数据分页；更深或别的子路径一律不认（404）。
+    if (parts.length === 2) return { kind: 'datasets', id }
+    if (parts.length === 3 && parts[2] === 'rows') return { kind: 'datasets', id, rows: true }
+  }
+  return undefined
+}
+
+function methodNotAllowed(response: RouteResponse): void {
+  sendError(response, 405, 'METHOD_NOT_ALLOWED', 'only GET / POST / PATCH / DELETE are allowed')
+}
+
+function requireScope(params: URLSearchParams): string {
+  const scope = params.get('scope')
+  if (scope === null || scope.trim().length === 0) {
+    throw new AdminValidationError('BAD_REQUEST', '缺少 scope 参数（请从工作区列表里选）')
+  }
+  return scope.trim()
+}
+
+/**
+ * 注册管理路由。宿主缺失（`webServer` / `connection`）时返回 undefined，由调用方降级。
+ * 路由路径重复会抛错（webserver 契约），与视图路由路径不同前缀，互不影响。
+ */
+export function registerAdminRoutes(services: DataServices): (() => void) | undefined {
+  const { webServer, connection } = services
+  if (webServer === undefined || connection === undefined) return undefined
+
+  const handler = async (rawRequest: unknown, rawResponse: unknown): Promise<void> => {
+    const request = rawRequest as RouteRequest & IncomingMessage
+    const response = rawResponse as RouteResponse & ServerResponse
+
+    const rejection = authorize(connection, request)
+    if (rejection !== undefined) {
+      sendError(response, rejection, rejection === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN', 'unauthorized')
+      return
+    }
+
+    const method = (request.method ?? 'GET').toUpperCase()
+    const url = new URL(request.url ?? '/', 'http://localhost')
+    const resource = parseAdminPath(url.pathname)
+    if (resource === undefined) {
+      sendError(response, 404, 'NOT_FOUND', 'not found')
+      return
+    }
+    const params = url.searchParams
+
+    try {
+      if (resource.kind === 'scopes') {
+        if (method !== 'GET') {
+          methodNotAllowed(response)
+          return
+        }
+        const scopes = await listScopes(services)
+        sendJson(response, 200, { scopes })
+        return
+      }
+
+      if (resource.kind === 'sources') {
+        if (resource.action === 'test') {
+          if (method !== 'POST') {
+            methodNotAllowed(response)
+            return
+          }
+          const body = await readJsonBody(request, services.cfg.adminMaxBodyBytes)
+          sendJson(response, 200, await testDataSource(services, body))
+          return
+        }
+        if (resource.id === undefined) {
+          if (method === 'GET') {
+            sendJson(response, 200, { sources: await listDataSources(services) })
+            return
+          }
+          if (method === 'POST') {
+            const body = await readJsonBody(request, services.cfg.adminMaxBodyBytes)
+            sendJson(response, 201, await createDataSource(services, body))
+            return
+          }
+          methodNotAllowed(response)
+          return
+        }
+        if (resource.action === 'tables') {
+          if (method !== 'GET') {
+            methodNotAllowed(response)
+            return
+          }
+          sendJson(response, 200, await listSourceTables(services, resource.id, Object.fromEntries(params)))
+          return
+        }
+        if (resource.action === 'import') {
+          if (method !== 'POST') {
+            methodNotAllowed(response)
+            return
+          }
+          const body = await readJsonBody(request, services.cfg.adminMaxBodyBytes)
+          sendJson(response, 201, await importSourceTable(services, resource.id, body))
+          return
+        }
+        if (method === 'GET') {
+          sendJson(response, 200, await getDataSource(services, resource.id))
+          return
+        }
+        if (method === 'PATCH') {
+          const body = await readJsonBody(request, services.cfg.adminMaxBodyBytes)
+          sendJson(response, 200, await patchDataSource(services, resource.id, body))
+          return
+        }
+        if (method === 'DELETE') {
+          sendJson(response, 200, await deleteDataSource(services, resource.id))
+          return
+        }
+        methodNotAllowed(response)
+        return
+      }
+
+      if (resource.id === undefined) {
+        if (method === 'GET') {
+          const result = await listDatasets(services, Object.fromEntries(params))
+          sendJson(response, 200, result)
+          return
+        }
+        if (method === 'POST') {
+          const body = await readJsonBody(request, services.cfg.adminMaxBodyBytes)
+          const created = await createDataset(services, body as CreateDatasetRequest)
+          sendJson(response, 201, created)
+          return
+        }
+        methodNotAllowed(response)
+        return
+      }
+
+      const scope = requireScope(params)
+      if (resource.rows === true) {
+        if (method !== 'GET') {
+          methodNotAllowed(response)
+          return
+        }
+        const rows = await listDatasetRows(services, scope, resource.id, Object.fromEntries(params))
+        sendJson(response, 200, rows)
+        return
+      }
+      if (method === 'GET') {
+        const detail = await getDataset(services, scope, resource.id)
+        sendJson(response, 200, detail)
+        return
+      }
+      if (method === 'PATCH') {
+        const body = await readJsonBody(request, services.cfg.adminMaxBodyBytes)
+        const patched = await patchDataset(services, scope, resource.id, body as PatchDatasetRequest)
+        sendJson(response, 200, patched)
+        return
+      }
+      if (method === 'DELETE') {
+        const result = await deleteDataset(services, scope, resource.id)
+        sendJson(response, 200, result)
+        return
+      }
+      methodNotAllowed(response)
+    } catch (error) {
+      if (error instanceof AdminValidationError) {
+        sendError(response, 400, error.code, error.message)
+        return
+      }
+      if (error instanceof AdminServiceError) {
+        sendError(response, error.status, error.code, error.message)
+        return
+      }
+      // 脱敏：不回显 SQL 与物理表名。
+      sendError(response, 500, 'QUERY_FAILED', '管理接口内部错误')
+    }
+  }
+
+  return webServer.register({ kind: 'prefix', path: ADMIN_API_BASE, handler })
+}