# API参考

<cite>
**本文引用的文件**
- `README.md`
- `package.json`
- `src-tauri/Cargo.toml`
- `src-tauri/tauri.conf.json`
- `src-tauri/src/lib.rs`
- `src-tauri/src/main.rs`
- `src-tauri/src/commands/mod.rs`
- `src-tauri/sql/src/lib.rs`
</cite>

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

## 简介
本文件为 GSDJGXApp 的完整 API 参考文档，面向前端与后端交互的 Tauri 命令接口、Rust 后端公开函数、数据库与文件系统操作、Excel/CSV 报表处理、API 版本与兼容性策略、错误码与调试工具、以及客户端集成最佳实践进行系统化说明。项目采用 Angular 22 + Tauri 2 + Rust 架构，后端通过 SeaORM 访问 SQLite，提供高性能、可移植的桌面应用。

## 项目结构
- 前端（Angular 22 + TypeScript）通过 @tauri-apps/api 与后端通信，使用 Tauri 命令通道进行请求/响应交互。
- 后端（Rust/Tauri）集中注册大量命令模块，覆盖通用、认证、代理、数据库、项目与财务、计算分析、报告与导出、PDF 打印等业务域。
- 数据层采用 SeaORM + SQLite，提供结构化查询、事务与批量执行能力；同时内置轻量 SQL 插件用于扩展场景。
- 文件系统与外部资源通过 Tauri 插件访问，支持文件读写、打开 URL、剪贴板、进程控制、日志、深链等。

```mermaid
graph TB
FE["前端<br/>Angular 22 + @tauri-apps/api"] --> Tauri["Tauri 应用层<br/>命令注册与桥接"]
Tauri --> Cmds["命令模块集合<br/>commands/*"]
Cmds --> DB["数据库层<br/>SeaORM + SQLite"]
Cmds --> FS["文件系统/外部资源<br/>Tauri 插件"]
Cmds --> Calc["计算引擎<br/>熵权法/TOPSIS/归一化等"]
Cmds --> IO["导入导出<br/>Excel/CSV/报告/PDF"]
```

图表来源
- `src-tauri/src/lib.rs#L77-L304`
- `src-tauri/Cargo.toml#L26-L65`
- `package.json#L54-L64`

章节来源
- `README.md#L1-L118`
- `src-tauri/tauri.conf.json#L1-L70`

## 核心组件
- Tauri 命令总表：后端集中注册了超过 120 个命令，涵盖通用、认证、代理、数据库、项目与财务、计算分析、报告与导出、PDF 打印等模块。命令统一通过 generate_handler! 宏注册到应用生命周期中。
- 数据库接口：通过 SeaORM 提供 ORM 查询、事务、批量执行、表信息查询等；同时提供轻量 SQL 插件（gsdj-sql）用于 select/execute/load/close 等基础操作。
- 文件系统与外部资源：通过 @tauri-apps/plugin-fs、@tauri-apps/plugin-opener、@tauri-apps/plugin-dialog、@tauri-apps/plugin-clipboard-manager、@tauri-apps/plugin-process、@tauri-apps/plugin-log 等插件提供能力。
- 计算引擎：包含矩阵归一化、熵权法、距离矩阵、加权得分、自动穷举组合、贪心扫描、全局最优搜索等算法命令。
- 报告与导出：提供工作底稿 Excel 导出、Excel 智能识别财务报表导入、HTML 打印与 PDF 输出等。

章节来源
- `src-tauri/src/lib.rs#L77-L304`
- `src-tauri/sql/src/lib.rs#L137-L186`

## 架构总览
下图展示前端与后端的典型交互流程：前端发起命令请求，后端根据命令路由到对应模块，执行业务逻辑（数据库/文件系统/计算），最终返回结构化 JSON 响应。

```mermaid
sequenceDiagram
participant FE as "前端"
participant T as "Tauri 应用"
participant CMD as "命令处理器"
participant DB as "数据库/文件系统"
participant CAL as "计算引擎"
FE->>T : "invoke('命令名', 参数)"
T->>CMD : "路由到具体命令"
alt "数据库/文件操作"
CMD->>DB : "执行查询/事务/批量/IO"
DB-->>CMD : "返回结果/影响行数"
else "计算分析"
CMD->>CAL : "调用算法函数"
CAL-->>CMD : "返回计算结果"
end
CMD-->>FE : "返回 JSON 结果"
```

图表来源
- `src-tauri/src/lib.rs#L77-L304`
- `src-tauri/sql/src/lib.rs#L137-L186`

## 详细组件分析

### 通用命令
- greet：用于测试与问候。
- init_workspace_database / init_all_database_tables / init_database_table：初始化工作区与数据库表。
- fetch_to_workspace_file / save_file_to_workspace：工作区文件拉取与保存。
- open_external_url：打开外部链接。
- aichat：AI 聊天（示例命令）。

请求/响应要点
- 请求参数：根据具体命令定义（例如 init_workspace_database 可能需要工作区路径）。
- 返回值：统一为 JSON 对象，包含状态字段与数据字段；错误时包含错误码与消息。

章节来源
- `src-tauri/src/lib.rs#L77-L100`

### 域名配置命令
- update_domain_config / get_domain_config / update_single_domain / clear_custom_domain：域名配置管理。

请求/响应要点
- 参数：域名配置对象或键值对。
- 返回：配置对象或布尔状态。

章节来源
- `src-tauri/src/lib.rs#L88-L93`

### 同花顺认证命令
- ths_auto_login_and_get_user_info / ths_get_stored_user_info / ths_get_stored_cookies / ths_get_latest_user_response / ths_get_auth_verify_result / ths_get_user_tables / ths_refresh_user_info / ths_clear_auth_data / ths_save_auth_with_stored_response / ths_check_office_service_status / ths_fetch_luculent_project_list / ths_upload_to_luculent / save_office_username / get_office_username：与 THS 认证与办公服务相关的命令集合。

请求/响应要点
- 参数：登录凭据、Cookies、项目列表筛选条件等。
- 返回：用户信息、Cookies、验证结果、上传状态、项目列表等。

章节来源
- `src-tauri/src/lib.rs#L94-L108`

### 独立登录命令（测试）
- independent_login / independent_post_request / independent_get_saved_cookies / independent_clear_cookies / independent_load_and_validate_cookies：独立登录与 Cookie 管理。

请求/响应要点
- 参数：登录凭据、请求体、Cookie。
- 返回：登录状态、Cookie、校验结果。

章节来源
- `src-tauri/src/lib.rs#L109-L114`

### QuantAPI 代理命令
- quantapigw / quantapigw_get / quantapigw_post / quantapigw_put / quantapigw_delete / quantapigw_test_connection：代理请求与连通性测试。
- enhanced_proxy / enhanced_proxy_post / enhanced_proxy_test_connection：增强代理请求与测试。
- set_proxy_mode / get_proxy_mode / startup_check_proxy_mode：代理模式管理。

请求/响应要点
- 参数：目标 URL、HTTP 方法、请求头、请求体、代理模式开关。
- 返回：代理响应、连通性状态、模式状态。

章节来源
- `src-tauri/src/lib.rs#L115-L134`

### 代理缓存命令
- proxy_cache_get / proxy_cache_save：代理缓存读取与保存。

请求/响应要点
- 参数：缓存键、缓存值。
- 返回：缓存命中状态与值。

章节来源
- `src-tauri/src/lib.rs#L122-L124`

### 通知命令
- test_notification：通知测试。

请求/响应要点
- 参数：通知内容。
- 返回：发送状态。

章节来源
- `src-tauri/src/lib.rs#L135`

### 数据库命令（SeaORM）
- query_sqlite / execute_sqlite / get_table_info / get_all_tables / batch_execute_sqlite / execute_transaction / init_database_pool / check_database_status：数据库查询、执行、事务、批量、连接池与状态检查。

请求/响应要点
- 参数：SQL 语句、事务脚本、表名、批量 SQL 列表。
- 返回：查询结果集、影响行数、表信息、连接状态。

章节来源
- `src-tauri/src/lib.rs#L137-L145`

### 数据库命令（轻量 SQL 插件）
- load / execute / select / close：轻量 SQL 插件命令，用于连接管理、执行与关闭。

请求/响应要点
- 参数：数据库连接字符串、SQL、参数。
- 返回：执行结果、查询行集、连接状态。

章节来源
- `src-tauri/sql/src/lib.rs#L137-L186`

### 项目命令
- get_all_projects / get_project_by_id / create_project / update_project / delete_project / get_projects_by_fund_name / update_fund_info：项目 CRUD 与查询。

请求/响应要点
- 参数：项目实体对象、ID、名称过滤。
- 返回：项目列表/单个项目、操作结果。

章节来源
- `src-tauri/src/lib.rs#L146-L153`

### 基准日命令
- get_valuation_date_by_id / create_valuation_date / update_valuation_date / delete_valuation_date / query_valuation_dates / get_active_valuation_date / set_active_valuation_date：估值基准日管理。

请求/响应要点
- 参数：日期对象、活动状态切换。
- 返回：日期记录、活动状态。

章节来源
- `src-tauri/src/lib.rs#L154-L161`

### 项目扩展信息命令
- init_project_extension_table / create_or_update_project_extension / get_project_extension_by_project_and_valuation_date：项目扩展信息初始化与查询。

请求/响应要点
- 参数：扩展信息对象、项目与基准日组合。
- 返回：扩展信息记录。

章节来源
- `src-tauri/src/lib.rs#L162-L165`

### 投融管理命令
- init_investment_financing_table / create_investment_financing / update_investment_financing / delete_investment_financing / get_investment_financing_by_id / get_all_investment_financing / list_investment_financing：投融信息 CRUD 与列表。

请求/响应要点
- 参数：投融记录对象、ID。
- 返回：记录详情/列表。

章节来源
- `src-tauri/src/lib.rs#L166-L173`

### 统一产线状态管理命令
- init_pipeline_state_snapshot_table / save_pipeline_state_snapshot / load_pipeline_state_snapshot / pipeline_state_snapshot_exists / delete_pipeline_state_snapshot / get_all_pipeline_state_snapshots / cleanup_project_pipeline_snapshots：产线状态快照管理。

请求/响应要点
- 参数：快照对象、项目 ID。
- 返回：存在性、快照数据、清理结果。

章节来源
- `src-tauri/src/lib.rs#L174-L181`

### 财务报表命令
- init_financial_statements_table / create_financial_statement / update_financial_statement / delete_financial_statement / get_financial_statement_by_id / get_all_financial_statements / get_financial_statements_by_project_id / check_existing_financial_statement / create_or_update_financial_statement：财务报表 CRUD、查询与去重。

请求/响应要点
- 参数：报表对象、项目 ID、去重条件。
- 返回：报表记录、存在性、操作结果。

章节来源
- `src-tauri/src/lib.rs#L182-L191`

### 财务指标分析命令
- save_financial_indicators_analysis / get_financial_indicators_analysis / list_financial_indicators_analysis / get_financial_indicators_analysis_view / delete_financial_indicators_analysis：指标分析保存、查询、视图与删除。

请求/响应要点
- 参数：分析对象、视图参数。
- 返回：分析结果、视图数据。

章节来源
- `src-tauri/src/lib.rs#L192-L197`

### 方法选择命令
- init_method_selection_table / get_method_selection / create_or_update_method_selection / delete_method_selection / get_method_selections_by_project：方法选择初始化与查询。

请求/响应要点
- 参数：方法选择对象、项目 ID。
- 返回：方法选择记录。

章节来源
- `src-tauri/src/lib.rs#L198-L203`

### 参数设置命令
- init_parameter_settings_table / get_parameter_settings / create_or_update_parameter_settings / delete_parameter_settings / get_parameter_settings_by_project：参数设置初始化与查询。

请求/响应要点
- 参数：参数对象、项目 ID。
- 返回：参数记录。

章节来源
- `src-tauri/src/lib.rs#L204-L209`

### 可比公司选择命令
- init_comparable_company_selection_table / get_comparable_company_selection / create_or_update_comparable_company_selection / delete_comparable_company_selection / get_comparable_company_selections_by_project / get_selected_companies_count / comparable_company_selection_exists：可比公司选择初始化、查询与统计。

请求/响应要点
- 参数：选择对象、项目 ID、计数条件。
- 返回：选择记录、数量、存在性。

章节来源
- `src-tauri/src/lib.rs#L210-L217`

### 可比公司计算结果批次存储命令
- init_comparable_company_calc_batches_table / upsert_comparable_company_calc_batch / get_comparable_company_calc_batch / list_comparable_company_calc_aliases / get_all_comparable_company_calc_batches / delete_all_comparable_company_calc_batches：批次存储初始化与查询。

请求/响应要点
- 参数：批次对象、别名列表。
- 返回：批次记录、别名列表。

章节来源
- `src-tauri/src/lib.rs#L218-L224`

### DLOM 计算命令
- init_dlom_calculation_table / save_dlom_calculation / get_latest_dlom_calculation / get_dlom_calculation / update_dlom_selected_value / delete_dlom_calculation / get_dlom_calculation_history / sync_dlom_to_parameter_settings：DLOM 计算初始化、保存、查询、同步。

请求/响应要点
- 参数：计算对象、历史查询条件、同步参数。
- 返回：最新/历史记录、同步结果。

章节来源
- `src-tauri/src/lib.rs#L225-L233`

### 计算分析命令
- calculate_financial_metrics_averages / get_local_company_raw_financial_data / calculate_multi_period_averages / matrix_normalize：财务指标平均值、原始数据、多期平均、矩阵归一化。

请求/响应要点
- 参数：项目 ID、期间范围、归一化参数。
- 返回：平均值、原始数据、归一化矩阵。

章节来源
- `src-tauri/src/lib.rs#L234-L238`

### 熵权法与距离矩阵命令
- calculate_entropy_weights / calculate_raw_distance_matrix / calculate_weighted_scores / calculate_entropy_analysis：熵权法、原始距离矩阵、加权得分、熵分析。

请求/响应要点
- 参数：指标矩阵、权重参数。
- 返回：权重、距离矩阵、得分、分析结果。

章节来源
- `src-tauri/src/lib.rs#L239-L243`

### 验证计算 THS 数据存储命令
- save_validation_ths_data / get_validation_ths_data / cleanup_expired_validation_ths_data / list_validation_ths_data / save_validation_ths_error_data / delete_validation_ths_data / init_validation_ths_data_storage_table / get_validation_ths_data_by_project_and_date / get_validation_ths_data_by_project / get_validation_ths_data_by_type / delete_validation_ths_data_by_project_and_date / delete_validation_ths_data_by_id：THS 数据验证存储初始化、保存、查询、清理与删除。

请求/响应要点
- 参数：验证数据对象、项目与日期、类型、清理条件。
- 返回：数据记录、清理结果、存在性。

章节来源
- `src-tauri/src/lib.rs#L244-L267`

### 自动穷举组合计算命令
- auto_calculate_exhaustive_combos / stop_auto_calculate_exhaustive_combos：自动穷举组合计算与停止。

请求/响应要点
- 参数：组合参数、停止信号。
- 返回：计算进度、结果、停止状态。

章节来源
- `src-tauri/src/lib.rs#L250-L252`

### 贪婪组合计算命令
- greedy_calculate_range_search / greedy_scan_max_peer_avg：贪婪范围搜索与最大同行均值扫描。

请求/响应要点
- 参数：搜索范围、扫描参数。
- 返回：搜索结果、扫描统计。

章节来源
- `src-tauri/src/lib.rs#L253-L255`

### 全局最优搜索命令
- optimal_search_indicators / save_optimal_search_config / get_optimal_search_config / get_optimization_company_status / delete_validation_ths_data：全局最优指标、配置保存与加载、公司状态查询、数据清理。

请求/响应要点
- 参数：指标集合、配置对象、状态查询条件。
- 返回：配置、状态、清理结果。

章节来源
- `src-tauri/src/lib.rs#L256-L260`

### 报告存储命令
- init_report_storage_table / save_report / get_active_report / get_all_report_storage / delete_report_storage：报告存储初始化、保存、查询活动报告与全部报告、删除。

请求/响应要点
- 参数：报告对象、活动查询条件。
- 返回：报告记录、活动报告、删除结果。

章节来源
- `src-tauri/src/lib.rs#L268-L273`

### 工作底稿 Excel 导出命令
- export_working_paper_excel / export_working_paper_excel_base64：工作底稿导出为文件或 Base64 字符串。

请求/响应要点
- 参数：导出模板、数据集。
- 返回：文件路径或 Base64 字符串。

章节来源
- `src-tauri/src/lib.rs#L274-L276`

### Excel 导入命令（智能识别财务报表）
- read_excel_to_json：Excel 解析为 JSON。

请求/响应要点
- 参数：文件路径、工作表索引、列映射。
- 返回：解析后的 JSON 数据。

章节来源
- `src-tauri/src/lib.rs#L277`

### 项目排序命令
- get_project_sort_order_by_fund / get_project_sort_order_by_filter / get_all_project_sort_orders / update_project_sort_position / batch_update_project_sort_order / auto_assign_project_sort_position / delete_project_sort_order / normalize_project_sort_positions：项目排序查询、更新、自动分配与规范化。

请求/响应要点
- 参数：排序对象、批量更新列表、规范化参数。
- 返回：排序记录、更新结果、规范化结果。

章节来源
- `src-tauri/src/lib.rs#L279-L287`

### 办公系统数据绑定命令
- init_office_data_binding_table / create_office_data_binding / get_office_data_binding_by_project_id / get_office_data_binding_by_project_code / unbind_office_data_by_project_id / get_all_office_data_bindings / is_project_office_bound / get_office_bindings_by_project_ids / check_remote_project_bound / update_office_data_status / clear_office_data_status / update_office_investment_date：办公数据绑定初始化、CRUD、查询、状态更新与解除绑定。

请求/响应要点
- 参数：绑定对象、项目 ID/编码、状态更新。
- 返回：绑定记录、存在性、状态。

章节来源
- `src-tauri/src/lib.rs#L288-L300`

### PDF 打印命令
- print_html_to_pdf / open_html_for_print / show_print_preview：HTML 打印为 PDF、打开打印页面、显示打印预览。

请求/响应要点
- 参数：HTML 内容、打印配置。
- 返回：PDF 文件路径、打印状态。

章节来源
- `src-tauri/src/lib.rs#L301-L304`

### 计算命令（汇总）
- calculation_commands.rs：包含矩阵归一化、熵权法、TOPSIS、加权得分、多期平均、财务指标平均等命令。
- entropy_weight_commands.rs：熵权法相关命令。
- comparable_company_selection_commands.rs：可比公司选择命令。
- comparable_company_calc_batches_commands.rs：可比公司计算批次命令。
- dlom_calculation_commands.rs：DLOM 计算命令。
- financial_indicators_analysis_commands.rs：财务指标分析命令。
- financial_statements_commands.rs：财务报表命令。
- greedy_calculate_commands.rs：贪婪计算命令。
- optimal_search_commands.rs：全局最优搜索命令。

请求/响应要点
- 参数：输入矩阵、权重、时间序列、项目 ID。
- 返回：计算结果、分析报告、状态。

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

### 数据模型（SeaORM）
- comparable_company_selection、dlom_calculation、financial_indicators_analysis、financial_statements、investment_financing、method_selection、office_data_binding、parameter_settings、pipeline_state_snapshot、project_extension、project_sort_order、project_summary、report_storage、validation_ths_data_storage、valuation_date：各业务实体对应的模型定义。

请求/响应要点
- 参数：实体对象、查询条件。
- 返回：实体记录、列表、统计。

章节来源
- `src-tauri/src/models/mod.rs#L1-L20`

### 类关系图（命令与模块）
```mermaid
classDiagram
class Commands {
+命令集合
+注册 invoke_handler
}
class GeneralCmds {
+greet
+init_workspace_database
+fetch_to_workspace_file
+save_file_to_workspace
+open_external_url
}
class ThsAuthCmds {
+ths_auto_login_and_get_user_info
+ths_get_stored_user_info
+ths_get_stored_cookies
+ths_refresh_user_info
+ths_clear_auth_data
+ths_fetch_luculent_project_list
+ths_upload_to_luculent
}
class ProxyCmds {
+quantapigw*
+enhanced_proxy*
+proxy_cache_*
+set_proxy_mode
+get_proxy_mode
}
class DbCmds {
+query_sqlite
+execute_sqlite
+batch_execute_sqlite
+execute_transaction
+get_table_info
+get_all_tables
}
class ReportCmds {
+export_working_paper_excel
+export_working_paper_excel_base64
+read_excel_to_json
+print_html_to_pdf
+open_html_for_print
+show_print_preview
}
Commands --> GeneralCmds : "包含"
Commands --> ThsAuthCmds : "包含"
Commands --> ProxyCmds : "包含"
Commands --> DbCmds : "包含"
Commands --> ReportCmds : "包含"
```

图表来源
- `src-tauri/src/lib.rs#L77-L304`

## 依赖关系分析
- 前端依赖：@tauri-apps/api、@tauri-apps/plugin-* 系列插件、第三方 UI 与图表库。
- 后端依赖：tauri、sea-orm、tokio、serde、reqwest、calamine、rust_xlsxwriter、log 等。
- 数据库：SQLite（SeaORM + sqlx-sqlite）、可选 MySQL/PostgreSQL（通过特性启用）。
- 构建与打包：pnpm（前端）、Cargo（后端）、Tauri CLI。

```mermaid
graph LR
FE["@tauri-apps/api"] --> Tauri["Tauri 应用"]
Plugins["@tauri-apps/plugin-*"] --> Tauri
Tauri --> SeaORM["SeaORM + SQLite"]
Tauri --> Calamine["calamine (Excel)"]
Tauri --> Xlsx["rust_xlsxwriter (Excel)"]
Tauri --> Reqwest["reqwest (HTTP)"]
```

图表来源
- `package.json#L54-L64`
- `src-tauri/Cargo.toml#L26-L65`

章节来源
- `package.json#L1-L90`
- `src-tauri/Cargo.toml#L1-L66`

## 性能考虑
- 按需懒加载：前端路由与组件懒加载减少初始开销。
- 计算优化：Rust 算法（熵权法、TOPSIS、归一化）在高并发与大数据集下具备优势。
- 数据库批处理：优先使用 batch_execute_sqlite 与 execute_transaction 减少往返与锁竞争。
- 日志过滤：后端日志插件过滤 SQL 查询日志，降低 I/O 压力。
- 外部网络：代理模式与缓存（proxy_cache_*）提升网络稳定性与性能。

## 故障排查指南
- 常见错误码（示例）
  - 1001：参数校验失败
  - 1002：数据库连接失败
  - 1003：文件读写权限不足
  - 1004：Excel 解析失败
  - 1005：代理请求超时
  - 1006：计算引擎异常
- 调试工具
  - 后端日志：使用 tauri_plugin_log，按日期轮转，限制单文件大小。
  - 前端日志：结合浏览器开发者工具与 Tauri 开发模式。
  - 数据库：通过 SeaORM 日志与 SQL 插件命令定位慢查询。
  - 网络：开启代理模式与缓存，观察代理连通性测试命令返回。
- 建议流程
  - 先检查命令参数与权限
  - 查看后端日志与数据库状态
  - 使用最小复现样例（Excel/CSV/SQL）
  - 回滚最近变更并对比版本

章节来源
- `src-tauri/src/lib.rs#L34-L51`
- `src-tauri/sql/src/lib.rs#L106-L112`

## 结论
本 API 参考文档系统梳理了 GSDJGXApp 的前后端通信协议、命令注册与分类、数据库与文件系统接口、Excel/CSV 报表处理、计算分析能力、版本与兼容策略、错误码与调试工具，并提供了客户端集成与最佳实践建议。建议在生产环境中严格遵循参数校验、事务与批处理、日志与监控策略，确保系统的稳定性与可维护性。

## 附录

### API 版本管理与兼容性
- 版本号：前端与后端均使用语义化版本，当前版本为 v1.1.x。
- 发布策略：提交信息包含版本标记时自动更新版本。
- 兼容性：数据库迁移通过 SeaORM 进行，保持向后兼容；新增命令不破坏旧命令签名。
- 废弃命令迁移：保留过渡期并在变更日志中明确迁移步骤与替代方案。

章节来源
- `README.md#L1-L118`
- `src-tauri/tauri.conf.json#L3-L5`

### 请求/响应示例（结构化说明）
- 成功示例
  - 请求：invoke('create_project', { 名称: "项目A", 基金: "基A" })
  - 响应：{ 状态: "成功", 数据: { id: 1, 名称: "项目A", 创建时间: "..." } }
- 失败示例
  - 请求：invoke('read_excel_to_json', { 路径: "/invalid/path.xlsx" })
  - 响应：{ 状态: "失败", 错误码: 1004, 消息: "文件不存在或格式不支持" }

### 客户端集成最佳实践
- 前端
  - 使用 @tauri-apps/api 的 invoke 方法封装命令调用，统一处理错误与加载状态。
  - 对大文件/大批量数据采用分页或分批处理，避免阻塞 UI。
  - 对 Excel/CSV 导入增加预检与校验，提示用户修复格式问题。
- 后端
  - 对外暴露命令尽量幂等与可重入，配合唯一键与去重逻辑。
  - 对数据库操作使用事务包裹，失败回滚并记录日志。
  - 对网络请求设置超时与重试策略，必要时启用代理缓存。