# 后端API接口

<cite>
**本文档引用的文件**
- `src-tauri/src/lib.rs`
- `src-tauri/src/commands/mod.rs`
- `src-tauri/src/commands/general_commands.rs`
- `src-tauri/src/commands/db_commands.rs`
- `src-tauri/src/commands/project_commands.rs`
- `src-tauri/src/commands/calculation_commands.rs`
- `src-tauri/src/commands/entropy_weight_commands.rs`
- `src-tauri/src/commands/excel_import_commands.rs`
- `src-tauri/src/commands/pdf_print_commands.rs`
- `src-tauri/tauri.conf.json`
- `src-tauri/Cargo.toml`
</cite>

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

## 简介
本文件面向后端开发者与集成工程师，系统性梳理基于 Tauri + Rust 的后端 API 接口，覆盖金融估值计算、项目管理、数据操作、文件系统与打印等能力。文档重点说明：
- Tauri 命令系统架构与 IPC 通信机制
- 各类命令的函数签名、参数校验、返回值结构与异常处理
- 数据库操作（SeaORM + SQLite）与事务、批量执行
- 文件系统操作（工作区文件读写、下载代理）
- 打印与导出（HTML → PDF、Excel 导入）
- 性能优化、并发与内存管理最佳实践

## 项目结构
后端位于 src-tauri 目录，采用“命令模块 + 服务层 + 模型层”的分层设计：
- 命令层：通过 #[tauri::command] 暴露给前端的 API
- 服务层：封装业务逻辑与数据访问
- 模型层：SeaORM 实体与 DTO
- 插件与配置：日志、存储、剪贴板、进程、HTTP、深链、更新器等

```mermaid
graph TB
FE["前端应用<br/>Web/桌面UI"] --> IPC["Tauri IPC<br/>invokeHandler"]
IPC --> CMD["命令模块<br/>src/commands/*"]
CMD --> SVC["服务层<br/>业务逻辑"]
CMD --> DB["数据库层<br/>SeaORM/SQLite"]
CMD --> FS["文件系统<br/>工作区/下载代理"]
CMD --> NET["网络请求<br/>HTTP/代理"]
CMD --> PRINT["打印/导出<br/>WebView/PDF"]
```

**图示来源**
- `src-tauri/src/lib.rs#L77-L304`
- `src-tauri/Cargo.toml#L26-L60`

**章节来源**
- `src-tauri/src/lib.rs#L1-L308`
- `src-tauri/src/commands/mod.rs#L1-L70`

## 核心组件
- Tauri 命令注册：统一在 lib.rs 的 invoke_handler 中注册所有命令
- 状态管理：登录状态、独立登录状态、代理模式状态、域名配置、工作区路径
- 插件生态：日志、更新器、剪贴板、进程、存储、HTTP、深链、文件系统
- 数据库：SeaORM + SQLite，连接池、事务、批量执行
- 文件系统：工作区目录管理、下载代理、文件写入、唯一路径生成
- 打印导出：HTML 转 PDF、打印预览、浏览器打印

**章节来源**
- `src-tauri/src/lib.rs#L14-L77`
- `src-tauri/Cargo.toml#L26-L60`

## 架构总览
Tauri 在后端运行 Rust 代码，前端通过 IPC 调用命令。命令函数通过 State 注入全局状态，通过服务层访问数据库与文件系统，必要时发起网络请求。

```mermaid
sequenceDiagram
participant FE as "前端"
participant IPC as "Tauri IPC"
participant CMD as "命令函数"
participant SVC as "服务层"
participant DB as "数据库"
participant FS as "文件系统"
FE->>IPC : invoke("命令名", payload)
IPC->>CMD : 调用对应 #[tauri : : command]
CMD->>SVC : 业务处理可选
SVC->>DB : SeaORM 查询/执行可选
SVC->>FS : 文件读写/下载可选
CMD-->>IPC : Result<T, String>
IPC-->>FE : 返回结果
```

**图示来源**
- `src-tauri/src/lib.rs#L77-L304`
- `src-tauri/src/commands/general_commands.rs#L166-L263`
- `src-tauri/src/commands/db_commands.rs#L9-L23`

## 详细组件分析

### 通用命令与工作区管理
- 初始化工作区数据库：创建 .workdata 目录，初始化 SQLite 连接池与表结构，记录工作区路径
- 初始化所有/指定表：调用服务化初始化器
- 获取支持的数据库表：返回受支持的表清单
- AI 聊天：基于域名配置与环境变量，调用第三方 AI 服务
- 打开外部链接：通过 opener 插件调用系统默认应用
- 通用下载代理：支持自定义方法、请求头、请求体，自动解析文件名并去重保存
- 保存文件到工作区：清理非法字符、生成唯一路径、写入内容

参数与返回要点
- init_workspace_database：输入工作区路径；返回数据库文件路径或错误
- fetch_to_workspace_file：输入 URL、文件名、子目录、可选覆盖工作区路径、HTTP 方法、请求头、请求体；返回保存的绝对路径或错误
- save_file_to_workspace：输入文件名、字节数组、可选子目录、可选覆盖工作区路径；返回保存的绝对路径或错误

异常处理
- 路径未设置、目录创建失败、HTTP 请求失败、写入失败、文件名解析失败等均返回错误字符串

**章节来源**
- `src-tauri/src/commands/general_commands.rs#L29-L100`
- `src-tauri/src/commands/general_commands.rs#L103-L161`
- `src-tauri/src/commands/general_commands.rs#L166-L263`
- `src-tauri/src/commands/general_commands.rs#L305-L346`

### 数据库操作命令（SeaORM + SQLite）
- 查询：query_sqlite(sql, params?) → 返回行数组（JSON）
- 执行：execute_sqlite(sql, params?) → 返回受影响行数
- 获取表信息：get_table_info(table_name) → PRAGMA 结果
- 获取所有表：get_all_tables() → 表名列表
- 批量执行：batch_execute_sqlite(sql_statements) → 每条语句受影响行数
- 事务执行：execute_transaction(sql_statements) → 成功/失败
- 初始化连接池：init_database_pool(db_path) → 布尔
- 检查状态：check_database_status() → 布尔

参数与返回要点
- params 为可选 JSON 数组，内部转换为 SeaORM Value
- 返回值统一为 Result<T, String>，错误转为字符串

事务与批量
- execute_transaction 使用 SeaORM 事务包装多条语句，任一失败回滚
- batch_execute_sqlite 顺序执行，逐条记录受影响行数

**章节来源**
- `src-tauri/src/commands/db_commands.rs#L9-L23`
- `src-tauri/src/commands/db_commands.rs#L27-L43`
- `src-tauri/src/commands/db_commands.rs#L47-L59`
- `src-tauri/src/commands/db_commands.rs#L63-L94`
- `src-tauri/src/commands/db_commands.rs#L199-L216`

### 项目管理命令
- 获取全部项目、按 ID 获取、创建、更新、删除
- 按基金名称查询项目
- 批量更新基金信息（旧名称 → 新名称，可选代码）

参数与返回要点
- DTO 类型由模型层定义，命令层仅做参数透传与错误包装
- 返回值为 Result<T, String>，成功返回实体或影响行数

**章节来源**
- `src-tauri/src/commands/project_commands.rs#L6-L57`

### 金融估值计算命令
- 标准化计算：matrix_normalize(companies, 指标方向映射, 标准化方法, 指标中文名映射) → 返回标准化结果结构
- 财务指标均值：calculate_financial_metrics_averages(projectId, valuationDateId) → 返回均值统计与表格数据
- 多期平均值：calculate_multi_period_averages(multiPeriodData) → 返回均值统计与表格数据
- 本地原始数据：get_local_company_raw_financial_data(projectId, valuationDateId) → 返回时间序列与指标映射

参数与返回要点
- 输入 companies 为通用结构，包含公司编码与指标映射
- 标准化支持线性与对数两种方法，正负向指标分别处理
- 输出包含统计摘要、表格行、指标元信息与计算时间戳

**章节来源**
- `src-tauri/src/commands/calculation_commands.rs#L58-L315`
- `src-tauri/src/commands/calculation_commands.rs#L368-L562`
- `src-tauri/src/commands/calculation_commands.rs#L610-L822`
- `src-tauri/src/commands/calculation_commands.rs#L840-L956`

### 熵权法与距离矩阵命令
- 计算熵权：calculate_entropy_weights(request) → 权重结果
- 计算原始距离矩阵：calculate_raw_distance_matrix(request) → 距离矩阵
- 计算加权得分：calculate_weighted_scores(data_matrix, weights) → 加权行
- 组合分析：calculate_entropy_analysis(request) → {熵权, 加权矩阵}

参数与返回要点
- request 为服务层定义的请求结构
- 输出结构化结果，便于前端二次处理（如标准化、排序）

**章节来源**
- `src-tauri/src/commands/entropy_weight_commands.rs#L21-L77`

### Excel 导入命令
- read_excel_to_json(file_path) → 返回资产负债表/利润表识别结果

功能说明
- 自动识别含关键字的工作表（资产负债、利润）
- 多匹配时取首个
- 返回结构体字段可能为 None

**章节来源**
- `src-tauri/src/commands/excel_import_commands.rs#L18-L27`

### PDF 打印与导出命令
- print_html_to_pdf(app, request, workspace_state) → 返回结果结构
- open_html_for_print(app, request, workspace_state) → 返回结果结构
- show_print_preview(app, request) → 返回结果结构

请求结构
- PdfPrintRequest：HTML 内容、输出路径/文件名、子目录、页面设置
- PdfPageSettings：方向、纸张、页边距、背景、缩放
- PdfPrintResult：成功标志、文件路径、错误信息

实现要点
- 构建完整 HTML 文档，包含打印样式
- 使用 WebView 打印或系统浏览器打印
- 临时文件管理与清理

**章节来源**
- `src-tauri/src/commands/pdf_print_commands.rs#L9-L52`
- `src-tauri/src/commands/pdf_print_commands.rs#L57-L324`
- `src-tauri/src/commands/pdf_print_commands.rs#L335-L438`
- `src-tauri/src/commands/pdf_print_commands.rs#L447-L493`
- `src-tauri/src/commands/pdf_print_commands.rs#L498-L621`

### 办公系统绑定与上传命令
本地项目与办公系统（Luculent）远程项目的绑定、数据确认与报告上传：

- init_office_data_binding_table() → 初始化绑定表
- create_office_data_binding(dto) → 创建绑定（CreateOfficeDataBindingDto：项目 ID/代号、远程项目/基金编号与名称、办公系统类型、投资日期）
- get_office_data_binding_by_project_id(projectId) / get_office_data_binding_by_project_code(projectCode) → 查询绑定
- get_all_office_data_bindings() / get_office_bindings_by_project_ids(projectIds) → 批量查询
- is_project_office_bound(projectId) → 是否已绑定
- check_remote_project_bound(remoteProNo, remoteZbNo, excludeProjectId?) → 检查远程项目是否已被其他本地项目绑定（换绑时排除自身）
- update_office_data_status(projectId, dataStatus) → 写入数据确认快照（JSON 数组，按 project_code + assessment_base_date 联合唯一）
- clear_office_data_status(projectId) / update_office_investment_date(projectId, investmentDate) → 清除状态 / 更新投资日期
- unbind_office_data_by_project_id(projectId) → 解除绑定
- ths_fetch_luculent_project_list(pageNo, pageSize) → 拉取办公系统远程项目列表（含项目名、基金名、投资日期 tz_dat 等）
- ths_upload_to_luculent(request) → 上传估值数据 + 估值报告（HTML Base64）+ 工作底稿（Excel Base64）到办公系统
- export_working_paper_excel_base64(request) → 在内存中生成工作底稿 Excel（Base64，供上传）
- save_office_username(username) / get_office_username() → 记住办公系统用户名（全局存储）

实现要点
- 绑定表 office_data_binding 以本地 project_id 为键；data_status 字段为确认快照数组
- 上传前在前端按"报告基准日"匹配已确认的快照记录；上传产物名支持中文（R2 上传对 key 做 URI 编码）

**章节来源**
- `src-tauri/src/commands/office_data_binding_commands.rs`
- `src-tauri/src/commands/office_url_commands.rs`
- `src-tauri/src/commands/working_paper_excel_commands.rs`

## 依赖分析
- Tauri 核心：tauri = "2.11"，启用 macOS 私有 API 与 devtools
- 插件：日志、更新器、剪贴板、进程、存储、HTTP、深链、文件系统
- 数据库：sea-orm = "2.0"（sqlx-sqlite、runtime-tokio-rustls、with-chrono，要求 rustc ≥ 1.94）
- 网络：reqwest = "0.13"（json、cookies、gzip）
- 工具：serde/serde_json、tokio、chrono、url、base64、calamine、rust_xlsxwriter 等

```mermaid
graph LR
Tauri["tauri"] --> Plugins["插件集合"]
SeaORM["sea-orm"] --> SQLite["SQLite"]
Reqwest["reqwest"] --> HTTP["HTTP客户端"]
Serde["serde/json"] --> JSON["序列化/反序列化"]
Tokio["tokio"] --> Async["异步运行时"]
```

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

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

## 性能考虑
- 异步与并发
  - 命令函数广泛使用 async/await，配合 tokio 全栈运行时
  - SeaORM 默认异步查询，适合高并发场景
- 数据库优化
  - 使用连接池（init_database_pool），避免频繁创建连接
  - 事务批量提交（execute_transaction），减少磁盘写入次数
  - 批量执行（batch_execute_sqlite）按需使用
- 文件系统优化
  - 下载代理与保存采用流式写入，避免大文件内存占用
  - 唯一文件路径生成避免覆盖，同时限制重试上限
- 网络优化
  - 代理请求支持自定义方法、头与体，减少中间层开销
  - 合理设置超时与错误处理，避免阻塞
- 打印与导出
  - WebView 预览与系统打印分离，降低前端渲染压力
  - 临时文件及时清理，避免磁盘膨胀

[本节为通用指导，无需具体文件分析]

## 故障排除指南
常见错误与定位
- 工作区路径未设置：初始化工作区数据库前需先设置工作区路径
- 数据库连接失败：检查数据库文件路径与权限，确认连接池初始化成功
- SQL 参数类型不匹配：确保传入的 JSON 值可转换为 SeaORM Value
- 文件写入失败：检查目标目录权限与磁盘空间
- HTTP 请求失败：检查 URL、代理、证书与网络连通性
- 打印失败：确认系统打印机可用，WebView 窗口可见且已渲染

日志与调试
- 使用 tauri-plugin-log，过滤 SQLX 查询日志，便于定位性能瓶颈
- 命令函数内部使用 log::info/log::warn 记录关键步骤

**章节来源**
- `src-tauri/src/commands/general_commands.rs#L180-L190`
- `src-tauri/src/commands/db_commands.rs#L200-L216`
- `src-tauri/src/commands/pdf_print_commands.rs#L404-L438`

## 结论
本后端 API 以 Tauri 命令系统为核心，结合 SeaORM 数据库、插件生态与文件系统能力，提供了从金融估值计算到项目管理、数据导入导出与打印导出的完整后端支撑。通过异步并发、连接池与事务机制，兼顾性能与可靠性。建议在生产环境中：
- 明确参数校验与错误码约定
- 对大文件与长耗时任务增加进度反馈
- 严格控制日志级别与敏感信息脱敏
- 定期备份工作区与数据库