# 数据管理

<cite>
**本文引用的文件**
- `src-tauri/Cargo.toml`
- `src-tauri/src/main.rs`
- `README.md`
- `docs/README.md`
- `docs/项目开发说明书大纲.md`
- `docs/migration-history`
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向GSDJGXApp数据管理系统的使用者与维护者，围绕数据库设计（SeaORM模型与实体关系）、数据模型（Project、Fund、ValuationDate、FinancialStatement、CalculationResult等）的字段与业务规则、数据访问模式（CRUD、事务、并发控制）、Excel批量导入流程与校验、缓存策略、数据生命周期（清理、归档、备份恢复）、以及数据迁移（结构变更与版本升级）进行系统化说明。由于当前仓库中未包含具体SeaORM模型定义与数据管理模块源码，本文在“已知范围”内基于现有依赖与文档进行严谨描述，并在无法定位到具体实现时明确标注“依据现有依赖与文档推断”。

## 项目结构
- 前端采用Angular框架，位于src/app目录下，包含计算引擎、可比公司选择、财务报表、报告生成等功能模块。
- 后端为Tauri应用，使用Rust语言，集成SeaORM作为ORM，支持SQLite（通过sqlx-sqlite特性），并引入calamine用于Excel读取、rust_xlsxwriter用于Excel写入。
- 文档位于docs目录，包含开发说明书、迁移历史等资料。

```mermaid
graph TB
subgraph "前端(Angular)"
FE_App["src/app/*"]
end
subgraph "后端(Tauri/Rust)"
RT_Main["src-tauri/src/main.rs"]
RT_Cargo["src-tauri/Cargo.toml"]
end
subgraph "文档(docs)"
DOC_Readme["docs/README.md"]
DOC_Spec["docs/项目开发说明书大纲.md"]
DOC_Mig["docs/migration-history/*"]
end
FE_App --> RT_Main
RT_Main --> RT_Cargo
DOC_Readme -. 参考 .-> FE_App
DOC_Spec -. 参考 .-> FE_App
DOC_Mig -. 参考 .-> RT_Cargo
```

**图示来源**
- `src-tauri/src/main.rs#L1-L9`
- `src-tauri/Cargo.toml#L1-L66`
- `README.md`
- `docs/README.md`
- `docs/项目开发说明书大纲.md`
- `docs/migration-history`

**章节来源**
- `src-tauri/src/main.rs#L1-L9`
- `src-tauri/Cargo.toml#L1-L66`
- `README.md`
- `docs/README.md`
- `docs/项目开发说明书大纲.md`
- `docs/migration-history`

## 核心组件
- ORM与数据库：通过Cargo.toml可见，项目使用SeaORM 2.0.x，启用sqlx-sqlite运行时以支持SQLite；同时启用with-chrono宏以便处理时间类型。
- Excel处理：calamine用于读取Excel，rust_xlsxwriter用于写入Excel，满足批量导入导出需求。
- 并发与异步：Tokio全栈异步运行时，Rayon用于CPU密集型并行任务，适合计算引擎与数据处理场景。
- 存储与配置：tauri-plugin-store用于持久化键值存储；tauri-plugin-fs提供文件系统能力；tauri-plugin-log记录日志。

上述组件共同构成数据管理的基础设施层，支撑后续数据模型、访问模式与生命周期管理的实现。

**章节来源**
- `src-tauri/Cargo.toml#L26-L66`

## 架构总览
下图展示数据管理在系统中的位置与交互关系：前端通过Tauri桥接调用后端服务，后端通过SeaORM访问SQLite数据库；Excel读写由calamine与rust_xlsxwriter完成；日志与存储插件提供可观测性与持久化能力。

```mermaid
graph TB
FE_UI["前端界面<br/>Angular"] --> Tauri["Tauri桥接<br/>Rust后端"]
Tauri --> SeaORM["SeaORM ORM<br/>SQLite"]
Tauri --> Calamine["calamine<br/>Excel读取"]
Tauri --> XlsxWriter["rust_xlsxwriter<br/>Excel写入"]
Tauri --> Store["tauri-plugin-store<br/>键值存储"]
Tauri --> FS["tauri-plugin-fs<br/>文件系统"]
Tauri --> LogP["tauri-plugin-log<br/>日志"]
```

**图示来源**
- `src-tauri/Cargo.toml#L26-L66`
- `src-tauri/src/main.rs#L1-L9`

## 详细组件分析

### 数据模型设计与实体关系
以下为Project、Fund、ValuationDate、FinancialStatement、CalculationResult等核心实体的字段与业务规则设计建议（依据系统目标与常见金融建模实践）。由于当前仓库未提供具体SeaORM模型定义，以下为概念性设计说明，便于指导后续实现与对齐。

- Project（项目）
  - 字段建议：项目编号、名称、所属基金ID、状态、创建/更新时间等。
  - 约束：项目编号唯一；状态枚举；外键关联Fund。
  - 业务规则：项目状态流转、与估值日期绑定、参与指标计算。

- Fund（基金）
  - 字段建议：基金编号、名称、管理机构、成立日期、状态等。
  - 约束：基金编号唯一；管理机构信息必填。
  - 业务规则：一个基金可包含多个项目；影响项目估值口径与参数设置。

- ValuationDate（估值日期）
  - 字段建议：日期、周期类型（季度/年度）、是否基准日等。
  - 约束：日期唯一；周期类型枚举。
  - 业务规则：决定财务报表与指标计算的时间窗口；支持多期对比。

- FinancialStatement（财务报表）
  - 字段建议：项目ID、报表类型（资产负债表/利润表/现金流量表）、报表期间、数据JSON或明细行。
  - 约束：同一项目+报表类型+期间唯一；数据完整性校验。
  - 业务规则：按估值日期组织；支持多期滚动分析。

- CalculationResult（计算结果）
  - 字段建议：项目ID、指标名称、指标值、计算参数、计算时间、备注等。
  - 约束：指标名称+项目+日期组合唯一；数值精度与单位规范。
  - 业务规则：结果与ValuationDate强关联；支持导出与报告生成。

```mermaid
erDiagram
FUND {
string 编号 UK
string 名称
string 管理机构
date 成立日期
enum 状态
}
PROJECT {
string 编号 UK
string 名称
string 基金编号 FK
enum 状态
timestamp 创建时间
timestamp 更新时间
}
VALUATION_DATE {
date 日期 PK
enum 周期类型
boolean 是否基准日
}
FINANCIAL_STATEMENT {
uuid ID PK
string 项目编号 FK
enum 报表类型
date 报表期间 FK
json 数据
}
CALCULATION_RESULT {
uuid ID PK
string 项目编号 FK
string 指标名称
float 数值
json 计算参数
timestamp 计算时间
text 备注
}
FUND ||--o{ PROJECT : "拥有"
PROJECT ||--o{ FINANCIAL_STATEMENT : "产生"
VALUATION_DATE ||--o{ FINANCIAL_STATEMENT : "限定期间"
PROJECT ||--o{ CALCULATION_RESULT : "产生"
```

说明
- 上述ER图基于概念设计，用于指导SeaORM实体与关系映射。
- 实际字段与约束需结合业务需求与数据治理策略确定。

### 数据访问模式
- CRUD操作：通过SeaORM实体与Repository模式实现标准增删改查；对高频查询建立索引以提升性能。
- 事务处理：对批量导入、指标重算等长事务场景，使用事务包裹以保证一致性。
- 并发控制：利用Tokio异步与Rayon并行，避免阻塞UI线程；对共享资源使用互斥或无锁结构，防止竞态。

```mermaid
sequenceDiagram
participant UI as "前端界面"
participant Tauri as "Tauri后端"
participant ORM as "SeaORM"
participant DB as "SQLite"
UI->>Tauri : "请求导入Excel"
Tauri->>Tauri : "解析Excel(calamine)"
Tauri->>ORM : "校验与转换"
ORM->>DB : "事务插入/更新"
DB-->>ORM : "提交成功"
ORM-->>Tauri : "返回结果"
Tauri-->>UI : "进度与结果"
```

说明
- 该序列图展示从Excel导入到数据库写入的典型流程，具体实现需参考实际后端服务代码。

### Excel数据批量导入
- 导入实现要点
  - 使用calamine读取Excel工作簿，逐表扫描并解析标题行与数据行。
  - 对关键字段进行格式与范围校验（如日期、数值、枚举值）。
  - 将原始数据映射到SeaORM实体，构建批量插入/更新语句。
  - 错误处理：分条记录记录错误原因，汇总后反馈给前端；对异常中断的批次支持断点续传。
- 导出实现要点
  - 使用rust_xlsxwriter生成Excel，按报表类型与指标维度组织Sheet。
  - 支持筛选与排序导出，便于下游分析。

```mermaid
flowchart TD
Start(["开始导入"]) --> OpenXLSX["打开Excel文件"]
OpenXLSX --> ParseSheets["解析工作表"]
ParseSheets --> ValidateHeaders["校验表头字段"]
ValidateHeaders --> |不匹配| ReportHeaderErr["上报表头错误"]
ValidateHeaders --> |匹配| ParseRows["逐行解析数据"]
ParseRows --> ValidateData["字段级校验"]
ValidateData --> |失败| CollectErrors["收集错误并跳过"]
ValidateData --> |通过| MapToModel["映射到实体模型"]
MapToModel --> BatchWrite["批量写入数据库"]
BatchWrite --> CommitTxn["事务提交"]
CommitTxn --> Done(["结束"])
ReportHeaderErr --> Done
CollectErrors --> ParseRows
```

说明
- 以上流程图用于指导导入实现，具体字段与校验规则需结合业务文档与模型定义。

### 数据缓存策略
- 内存缓存：针对热点查询（如最近估值日期、常用指标清单）使用内存缓存，降低数据库压力。
- 磁盘缓存：对大体量中间结果或报表快照进行磁盘缓存，结合文件系统插件实现持久化。
- 缓存失效：基于时间窗口与数据变更事件触发失效，确保一致性。

### 数据生命周期管理
- 清理策略：定期清理过期或无效数据（如历史冗余报表、临时中间结果），保留必要审计日志。
- 归档策略：对历史数据按年/季归档，压缩存储，降低在线库体积。
- 备份恢复：定期全量备份，增量备份配合日志，支持快速回滚与灾备演练。

### 数据迁移指南
- 结构变更：通过迁移脚本或ORM工具生成迁移文件，先在测试环境验证，再灰度发布。
- 版本升级：遵循语义化版本，记录破坏性变更；提供向后兼容的过渡方案与数据转换脚本。
- 迁移历史：参考docs/migration-history目录下的记录，形成可追溯的演进路径。

**章节来源**
- `src-tauri/Cargo.toml#L26-L66`
- `docs/migration-history`

## 依赖分析
- ORM与数据库：SeaORM启用sqlx-sqlite与with-chrono，适配SQLite与时间类型。
- 文件与日志：tauri-plugin-fs与tauri-plugin-log提供文件系统与日志能力。
- Excel处理：calamine与rust_xlsxwriter分别负责读取与写入。
- 异步与并行：Tokio全栈异步、Rayon并行，支撑高吞吐数据处理。
- 配置与存储：tauri-plugin-store提供键值持久化。

```mermaid
graph LR
SeaORM["SeaORM"] --> SQLite["SQLite"]
Calamine["calamine"] --> Excel["Excel文件"]
XlsxWriter["rust_xlsxwriter"] --> Excel
Store["tauri-plugin-store"] --> KV["键值存储"]
FS["tauri-plugin-fs"] --> Files["文件系统"]
LogP["tauri-plugin-log"] --> Logs["日志"]
Tokio["Tokio"] --> AsyncOps["异步操作"]
Rayon["Rayon"] --> ParOps["并行计算"]
```

**图示来源**
- `src-tauri/Cargo.toml#L26-L66`

**章节来源**
- `src-tauri/Cargo.toml#L26-L66`

## 性能考虑
- 查询优化：为高频过滤字段（如项目编号、报表期间、指标名称）建立索引；合理拆分宽表与明细表。
- 批量操作：导入/导出采用批量写入与流式输出，减少内存占用与I/O次数。
- 并发与限流：对数据库连接池与并发任务数进行上限控制，避免资源争用。
- 缓存命中：根据访问模式调整缓存粒度与失效策略，平衡一致性与性能。

## 故障排查指南
- 日志定位：启用tauri-plugin-log，结合错误码与上下文信息快速定位问题。
- 数据一致性：检查事务边界与回滚逻辑，确保批量导入失败时整体回滚。
- Excel解析：确认表头与数据类型一致，异常数据单独隔离并记录。
- 性能瓶颈：通过Tokio任务监控与数据库慢查询日志识别热点。

**章节来源**
- `src-tauri/Cargo.toml#L26-L66`

## 结论
本文件基于现有依赖与文档，对GSDJGXApp数据管理系统进行了全面梳理与设计建议。由于当前仓库未包含具体SeaORM模型与数据管理模块源码，建议后续在实现阶段严格遵循本文的实体关系、访问模式与生命周期策略，并在docs/migration-history中持续沉淀迁移经验，确保系统可维护性与可扩展性。

## 附录
- 开发与使用说明可参考项目根目录与docs目录下的README与开发说明书大纲。
- 迁移历史与版本演进请参阅docs/migration-history目录。

**章节来源**
- `README.md`
- `docs/README.md`
- `docs/项目开发说明书大纲.md`
- `docs/migration-history`