Excel 导入改造期 1:止血与版本底座——写错的列名不再静默得 0,导入不再悄悄读错,每次上传生成不可变的版本,运行固定发起时的数据版本

连接层
- 所有 SQLite 数据源关闭双引号字符串兼容(DQS),写错的双引号列名直接报错;设置失败就拒绝连接,启动时自检
- 连接缓存按数据源加版本快照分键、按源整体失效、最多 32 个;版本快照以 immutable 只读打开,建连接前核对文件哈希,并在借出连接时核对文件指纹,被改过就拒绝查询
- 结构探查遇到取不了列的视图时逐个对象重取,只跳过坏的那个并注明原因

解析(新 xlsx_scan + tabular)
- 先流式扫描真实边界和版式(不信 dimension),再按边界读值,不整表进内存;按 Excel 自身上限设硬上限,并发解析最多两个
- 隐藏和深度隐藏的工作表不导入;稀疏区域、无缓存值的公式、同名工作表、DTD 拒收
- 去掉空行和两侧空列;列名表名统一规范化(新 names 模块)并保留原表头,撞名不再互相覆盖
- 前导零、超长数字按文本;千分位按数字;日期不带 T;带单位的数字文本写进回执
- 数字列混入非数字、交叉表和多块结构必须由用户决定(422),可选存空值或按原样导入(未规整);STRICT 建表,整份在一个事务里写完

版本底座(新 table_versions、raw_store)
- 每次上传写新库文件、落盘、0444,事务里写构建、导入记录、快照后才切指针;失败时旧版完整可查
- 原件按哈希存档,不提供下载,可以清除;上传源不许改连接字段、不再重新探查;手工 SQLite 源不许指向上传目录和应用自己的数据文件(按文件身份判断)
- 启动时清理半成品与孤儿文件、给老上传补初始版本;被运行引用的版本不回收,发起运行与回收互斥
- 上传接口的解析移到线程池

运行固定数据版本
- 发起时把图里(含子工作流)用到的上传源的当前快照记进运行记录和 run.started,续跑、审批恢复沿用;数据源工具按固定的快照生成描述、表结构并查询
- 固定的版本没了、源被删除后同名重建,都明确报错,不改用当前版本或同名的新源;查询快照记 data_version

证据层
- 新报告记 entity_syntax: 2,[[t:明细]]、[[c:明细.金额]] 和 SQL 里不加引号的中文表名都认得,名字按 SQLite 的口径查找;老报告按原规则复核,结果不变
- 写作规则改为中文表名、字段名一律用 [[t:]] / [[c:]];未规整的表在工具描述、写作目录和裁判摘录里标出

前端
- 上传弹窗接上导入前的决定(混合列、交叉表)和导入回执(跳过的隐藏表、类型转换、警告、原表头对照、未规整标记),上传前告知原件会保存
- 数据源卡片按 origin 认上传的表格,显示当前版本;上传的表格不再给「探查结构」
This commit is contained in:
ThearchyHelios
2026-10-01 13:42:04 +08:00
parent c837cdbfa3
commit 8059cd5147
38 changed files with 12465 additions and 535 deletions
+102
View File
@@ -227,6 +227,108 @@ export interface DataSource extends ServerHealth {
tools?: string[]
/** 缓存按哪个 schema 探的:'' 默认 schema,null 没有缓存 */
cached_schema?: string | null
/**
* upload:上传的表格(连接信息由系统维护,不能手改、不能重新探查,更新数据靠同名重新上传);
* manual:手工登记的连接。卡片按它分到「表格」「数据库」两个标签,不再按库文件路径猜
*/
origin?: 'upload' | 'manual' | (string & {})
/** 上传表格当前启用的版本。手工登记的源恒为 null */
current_snapshot?: CurrentSnapshot | null
}
/** 上传表格当前启用的版本(DataSource.current_snapshot) */
export interface CurrentSnapshot {
id: string
/**
* 这一版导入(发布)的时间。迁移补建的初始版本(raw_state 为 absent、没有文件名)例外:
* 这里是迁移那一刻(升级后服务启动的时间),不是导入时间
*/
created_at: string | null
/** 上传时的文件名。迁移前上传的老版本没有记录,是空串 */
file_name: string
/** 原件:kept 保存在服务端;purged 已清除;absent 没有保存(迁移前上传的老版本) */
raw_state: 'kept' | 'purged' | 'absent' | (string & {})
}
/**
* 上传表格时解析器要用户先拍板的事(POST /api/datasources/upload 回 422,body 是
* {detail, decision})。mixed:数字列混入非数字;shape:交叉表、多块结构
*/
export type UploadDecision =
| { kind: 'mixed'; details: { columns: UploadMixedColumn[] } }
| {
kind: 'shape'
details: {
reasons: UploadShapeReason[]
/** 预告:选了按原样导入之后还会问的混合列(没有就是 undefined) */
mixed?: UploadMixedColumn[]
/** 预告是不是看完了整张表;为假时之后的混合列可能比这里多 */
mixed_complete?: boolean
}
}
/** 一列以数字为主、混有非数字的值。values 是非数字的取值和个数(最多五种) */
export interface UploadMixedColumn {
sheet: string
table: string
/** SQL 列名 */
column: string
/** 原表头 */
header: string
numeric: number
nonnumeric: number
values: { value: string; count: number }[]
}
/** 这张表不是一行一条记录的一条理由。cells 是 A1 坐标或区域,message 是给人看的一句话(已含坐标) */
export interface UploadShapeReason {
sheet: string
/** date_header / date_row / section_title / table_totals / formula_above */
kind: string
cells: string[]
message: string
}
/** 导入回执里的一张表 */
export interface UploadedTable {
name: string
/** 原工作表名(CSV 是文件名) */
sheet: string
rows: number
/** name 是 SQL 列名,header 是原表头(表头格为空时是空串) */
columns: { name: string; type: string; header?: string | null }[]
/** 导入区域(A1,表头行到最后一行数据) */
region?: string | null
/** 按原样导入、未经规整 */
unshaped?: boolean
blank_rows_skipped?: number
/** 去掉的左右两侧整列为空的列(列字母) */
columns_trimmed?: string[]
}
/** 导入时做过的类型转换:kind 是 thousands_separator / nonnumeric_to_null / kept_as_text */
export interface UploadConversion {
table: string
column: string
kind: string
count: number
examples: unknown[]
}
/** POST /api/datasources/upload 成功时的回执 */
export interface UploadResult {
source: DataSource
/** 同名就地更新(新版本替换了旧版本),不是新建 */
replaced: boolean
import_id?: string
snapshot_id?: string
/** 同一份文件、同样的选项以前导入过,沿用了那次的库 */
build_reused?: boolean
/** reason:hidden 隐藏工作表不导入;empty 没有内容。state:visible / hidden / veryHidden */
skipped_sheets?: { sheet: string; state: string; reason: string }[]
conversions?: UploadConversion[]
warnings?: string[]
tables: UploadedTable[]
}
/** 自定义工具(GET /api/custom-tools 的一行;POST / PATCH 的返回同形) */