dsh-lh-data 0.1.0

package/lib/admin-validate.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 设置页管理接口的入参校验（纯函数，无 IO）。
+ *
+ * 所有校验失败都抛 `AdminValidationError`，由 `admin-http.ts` 统一转成 400。
+ * 校验目标：把浏览器传来的任意字符串收口成「类型正确、长度受控、范围合法」
+ * 的值——写库前最后一道闸门，尤其要防止凭空造工作区、列结构越界、字段溢出。
+ */
+import { type ColumnInfo } from './parse';
+import type { DataSourceInput, DataSourcePatch, DataSourceType } from './datasource/types';
+import type { ConnectionDraft } from './datasource/connection';
+import { type AdminErrorCode } from './admin-contract';
+/** 校验失败：对应 HTTP 400。 */
+export declare class AdminValidationError extends Error {
+    readonly code: AdminErrorCode;
+    constructor(code: AdminErrorCode, message: string);
+}
+export declare function validateScopeKey(value: unknown): string;
+export declare function validateDatasetName(value: unknown): string;
+export declare function validateDescription(value: unknown): string | null;
+export declare function validateSourcePath(value: unknown): string | null;
+/**
+ * 校验列定义：非空数组、数量受控、类型白名单、列名消毒并去重。
+ * 返回可直接交给 `createDatasetTable` 的 `ColumnInfo[]`。
+ */
+export declare function validateColumnSpecs(raw: unknown): ColumnInfo[];
+/**
+ * 校验列的「说明 / 样例」补丁，返回合并后的完整 `ColumnInfo[]`。
+ *
+ * 只从补丁里读 `description` 与 `sample` 两项，其余字段（name / sanitizedName /
+ * type / nullable）一律沿用既有列——它们对应物理表 DDL，设置页改不了。
+ * 按 `sanitizedName` 定位列：原始表头 `name` 在重名列上会重复，不能当键。
+ */
+export declare function validateColumnPatches(raw: unknown, existing: ColumnInfo[]): ColumnInfo[];
+export interface ParsedListQuery {
+    q: string;
+    page: number;
+    pageSize: number;
+}
+/** 解析并夹紧列表查询参数（关键字裁剪、页码与页大小封顶）。 */
+export declare function parseListQuery(params: Record<string, string | undefined>): ParsedListQuery;
+export interface ParsedRowsQuery {
+    page: number;
+    pageSize: number;
+}
+/**
+ * 解析并夹紧表数据分页参数。页码上限只是防御（真实边界由 `COUNT(*)` 决定），
+ * 页大小封顶避免一次捞走整表。
+ */
+export declare function parseRowsQuery(params: Record<string, string | undefined>): ParsedRowsQuery;
+export declare function validateSourceName(value: unknown): string;
+export declare function validateSourceType(value: unknown): DataSourceType;
+export declare function validateHost(value: unknown): string;
+export declare function validatePort(value: unknown, type: DataSourceType): number;
+export declare function validateDatabaseName(value: unknown): string;
+export declare function validateUsername(value: unknown): string;
+/** 密码允许为空串（部分库无口令），但不能超过上限。 */
+export declare function validatePassword(value: unknown): string;
+export interface ParsedCreateSource extends DataSourceInput {
+    test: boolean;
+}
+export declare function parseCreateDataSource(raw: unknown): ParsedCreateSource;
+export interface ParsedPatchSource extends DataSourcePatch {
+    test: boolean;
+}
+/** 只校验出现的字段；`password` 给了字符串才替换。 */
+export declare function parsePatchDataSource(raw: unknown): ParsedPatchSource;
+export interface ParsedTestSource {
+    /** 测已登记的数据源（id 或登记名）。 */
+    reference?: string;
+    /** 测未保存的草稿。 */
+    draft?: ConnectionDraft;
+}
+/** `source` 与「完整连接参数」二选一。 */
+export declare function parseTestDataSource(raw: unknown): ParsedTestSource;
+export interface ParsedTablesQuery {
+    schema: string | null;
+    q: string;
+}
+export declare function parseTablesQuery(params: Record<string, string | undefined>): ParsedTablesQuery;
+export interface ParsedImportRequest {
+    scopeKey: string;
+    tableName: string;
+    schemaName: string | null;
+    name: string | null;
+    limit: number | null;
+}
+export declare function parseImportRequest(raw: unknown): ParsedImportRequest;

package/lib/admin.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 设置页管理接口的主机侧服务层（模块级函数，无类）。
+ *
+ * 负责跨工作区聚合、单条详情、新建/改名改描述改来源/删除等纯业务逻辑，
+ * 不含任何 HTTP 细节（路由在 `admin-http.ts`）。所有错误都收敛成
+ * `AdminServiceError`，由路由层映射到统一脱敏的 JSON 错误体。
+ *
+ * 关键约束：
+ * - 写操作先过 `assertWritable`（readOnly / adminEnabled 门禁）；
+ * - 写与读都先校验 scope 是否「已知」（来自工作区注册表），拒绝凭空造工作区；
+ * - 物理表名一律由 `generateTableName` 生成并经 `assertPhysicalTableName` 白名单，
+ *   错误信息不回显表名与 SQL。
+ */
+import type { DataServices } from './store';
+import { type AdminErrorCode, type ConnectionTestView, type CreateDatasetRequest, type DataSourceView, type DatasetDetailView, type DatasetRowsResult, type ImportSourceTableResult, type ListDatasetsResult, type ListSourceTablesResult, type PatchDatasetRequest, type ScopeView } from './admin-contract';
+/** 业务错误：携带 HTTP 状态码与脱敏后的错误信息。 */
+export declare class AdminServiceError extends Error {
+    readonly code: AdminErrorCode;
+    readonly status: number;
+    constructor(code: AdminErrorCode, status: number, message: string);
+}
+/** 只读模式或接口关闭时拒绝写操作。 */
+export declare function assertWritable(services: DataServices): void;
+export declare function listScopes(services: DataServices): Promise<ScopeView[]>;
+/**
+ * 聚合所有工作区的数据集：逐 scope 拉取后内存过滤、排序、分页。
+ * 单个工作区读取失败降级为一条 warning 而不阻断整页。
+ */
+export declare function listDatasets(services: DataServices, rawQuery: Record<string, string | undefined>): Promise<ListDatasetsResult>;
+export declare function getDataset(services: DataServices, scopeKey: string, id: string): Promise<DatasetDetailView>;
+/**
+ * 只读分页读取某个数据集的物理表行。
+ *
+ * 只按 `_row_id` 升序翻页（稳定、不重不漏），列名取自元数据登记的业务列，
+ * 系统列（`_row_id` / `_uploaded_at`）不进 `columns`，但 `_row_id` 会出现在
+ * 每行里，供前端做稳定行键。页码由 `COUNT(*)` 反推后夹紧，越界返回末页。
+ */
+export declare function listDatasetRows(services: DataServices, scopeKey: string, id: string, rawQuery: Record<string, string | undefined>): Promise<DatasetRowsResult>;
+/** 新建一张空物理表并登记元数据；列结构在提交时冻结。 */
+export declare function createDataset(services: DataServices, raw: CreateDatasetRequest): Promise<DatasetDetailView>;
+/** 改名 / 改描述 / 改来源 / 改列的说明与样例；未提供的字段保持不变；同工作区内名称唯一。 */
+export declare function patchDataset(services: DataServices, scopeKey: string, id: string, raw: PatchDatasetRequest): Promise<DatasetDetailView>;
+export interface DeleteDatasetResult {
+    id: string;
+    name: string;
+    dropped: boolean;
+}
+/** 连同物理表与元数据一起删除（等同 dataset_drop）。 */
+export declare function deleteDataset(services: DataServices, scopeKey: string, id: string): Promise<DeleteDatasetResult>;
+export declare function listDataSources(services: DataServices): Promise<DataSourceView[]>;
+export declare function getDataSource(services: DataServices, reference: string): Promise<DataSourceView>;
+export declare function createDataSource(services: DataServices, raw: unknown): Promise<DataSourceView>;
+export declare function patchDataSource(services: DataServices, reference: string, raw: unknown): Promise<DataSourceView>;
+export declare function deleteDataSource(services: DataServices, reference: string): Promise<{
+    deleted: boolean;
+}>;
+/** 测已登记的数据源（`source`）或未保存的草稿（完整连接参数）。 */
+export declare function testDataSource(services: DataServices, raw: unknown): Promise<ConnectionTestView>;
+export declare function listSourceTables(services: DataServices, reference: string, params: Record<string, string | undefined>): Promise<ListSourceTablesResult>;
+export declare function importSourceTable(services: DataServices, reference: string, raw: unknown): Promise<ImportSourceTableResult>;