# 核心功能

<cite>
**本文引用的文件**
- `README.md`
- `package.json`
- `src/main.ts`
- `src-tauri/Cargo.toml`
- `src-tauri/tauri.conf.json`
- `src/app/calculation-engine/services/financial-data-query.service.ts`
- `src/app/calculation-engine/services/financial-calculation.service.ts`
- `src/app/calculation-engine/services/financial-indicator.service.ts`
- `src/app/calculation-engine/constants/financial-indicators.constants.ts`
- `src/app/calculation-engine/constants/ths-formula-aliases.constants.ts`
</cite>

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

## 简介
本文件面向GSDJGXApp的核心功能模块，围绕以下主题提供系统化文档：
- 财务数据集成：对接同花顺（THS）API、实时数据获取流程、数据格式转换与校验
- 可比公司选择：贪婪搜索与全局最优搜索两种策略的实现原理与适用场景
- 多维度指标计算：支持900+ THS公式、指标归一化与计算精度保障
- 熵权法与TOPSIS综合评价：权重分配、排序计算与结果解释
- 报告自动生成：模板系统、数据填充与格式化输出
- 跨平台桌面应用：基于Tauri框架的实现与平台特性处理
- 使用示例与最佳实践：各模块的典型用法与注意事项

## 项目结构
项目采用前后端分离的模块化架构：
- 前端：Angular 22 + Syncfusion/ECharts UI，负责交互与可视化
- 后端：Rust + Tauri 2，提供高性能计算与系统能力
- 数据层：SQLite + SeaORM，本地持久化与结构化查询
- 状态管理：RxJS服务组合，避免引入复杂状态库
- 数学计算：Rust实现的归一化、熵权法、TOPSIS排序、贪婪/全局最优搜索
- 构建工具：pnpm + Cargo，提升开发与打包效率

```mermaid
graph TB
subgraph "前端(Angular)"
FE_UI["UI组件<br/>Syncfusion/ECharts"]
FE_Services["计算服务<br/>FinancialCalculationService"]
FE_DataQuery["数据查询服务<br/>FinancialDataQueryService"]
end
subgraph "后端(Tauri/Rust)"
BE_API["Tauri API<br/>插件: http/fs/store/process/log/updater"]
BE_DB["SeaORM + SQLite"]
BE_Algorithms["算法引擎<br/>熵权法/TOPSIS/搜索策略"]
end
subgraph "数据与配置"
THS_API["同花顺(THS) API"]
Configs["指标与公式配置<br/>本地TS常量/远程JSON"]
end
FE_UI --> FE_Services
FE_Services --> FE_DataQuery
FE_Services --> BE_API
FE_DataQuery --> BE_API
BE_API --> BE_DB
BE_API --> THS_API
FE_Services --> Configs
FE_DataQuery --> Configs
```

图示来源
- `package.json#L19-L87`
- `src-tauri/Cargo.toml#L26-L59`
- `src-tauri/tauri.conf.json#L1-L70`

章节来源
- `README.md#L1-L118`
- `package.json#L1-L90`
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/tauri.conf.json#L1-L70`

## 核心组件
- 财务数据查询与转换：从财务报表数据中提取指标、构建时间序列、执行本地计算与模板化计算
- 多维度指标计算：统一的公式引擎，支持时间序列、同比、TTM等多种计算模式
- 指标配置与映射：900+ THS公式别名与参数配置，支持远程/本地双轨配置与版本对比
- 可比公司选择：提供贪婪搜索与全局最优搜索策略，辅助筛选相似公司
- 熵权法与TOPSIS：基于Rust高精度实现的权重分配与综合排序
- 报告自动生成：模板驱动的数据填充与格式化输出
- 跨平台桌面应用：Tauri + 插件体系，支持Windows/macOS/Linux

章节来源
- `src/app/calculation-engine/services/financial-data-query.service.ts#L1-L472`
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`
- `src/app/calculation-engine/constants/financial-indicators.constants.ts#L1-L489`
- `src/app/calculation-engine/constants/ths-formula-aliases.constants.ts#L1-L731`

## 架构总览
下图展示从“前端请求”到“THS数据获取与本地计算”的端到端流程。

```mermaid
sequenceDiagram
participant UI as "前端UI"
participant Calc as "FinancialCalculationService"
participant Query as "FinancialDataQueryService"
participant Engine as "增强公式引擎"
participant Tauri as "Tauri API"
participant THS as "同花顺(THS) API"
UI->>Calc : 发起计算请求
Calc->>Query : 提取/转换财务数据
Query->>Tauri : 查询财务报表数据
Tauri->>THS : 请求THS数据
THS-->>Tauri : 返回财务数据
Tauri-->>Query : 返回报表数据
Query->>Engine : 执行公式/时间序列/同比/TTM
Engine-->>Calc : 返回计算结果
Calc-->>UI : 展示指标与图表
```

图示来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L184-L206`
- `src/app/calculation-engine/services/financial-data-query.service.ts#L356-L369`
- `src-tauri/Cargo.toml#L31-L35`

章节来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`
- `src/app/calculation-engine/services/financial-data-query.service.ts#L1-L472`
- `src-tauri/Cargo.toml#L26-L59`

## 详细组件分析

### 财务数据集成与THS对接
- 数据来源与对接
  - 通过Tauri插件发起HTTP请求，访问THS数据接口，获取财务报表与行情数据
  - 前端通过服务封装查询逻辑，统一返回标准化的财务数据结构
- 实时数据获取流程
  - 前端触发计算 → 服务层组装上下文 → 调用Tauri API → 请求THS → 返回并缓存
- 数据格式转换与验证
  - 从电子表格JSON中抽取字段，进行数值解析与清洗
  - 支持多格式兼容（新/旧sheets结构），并提供字段映射与缺失字段诊断
  - 提供完整性校验：统计可用时间点与指标覆盖率，识别缺失项

```mermaid
flowchart TD
Start(["开始"]) --> Fetch["调用Tauri API获取THS数据"]
Fetch --> Parse["解析电子表格JSON<br/>抽取字段/数值"]
Parse --> Normalize["数值清洗与标准化"]
Normalize --> Validate{"完整性校验"}
Validate --> |通过| BuildCtx["构建计算上下文"]
Validate --> |不通过| Report["输出缺失字段与覆盖率"]
BuildCtx --> Compute["执行公式/时间序列/同比/TTM"]
Compute --> End(["结束"])
Report --> End
```

图示来源
- `src/app/calculation-engine/services/financial-data-query.service.ts#L111-L237`
- `src/app/calculation-engine/services/financial-indicator.service.ts#L116-L145`
- `src/app/calculation-engine/services/financial-indicator.service.ts#L649-L677`

章节来源
- `src/app/calculation-engine/services/financial-data-query.service.ts#L1-L472`
- `src/app/calculation-engine/services/financial-indicator.service.ts#L1-L830`
- `src-tauri/Cargo.toml#L31-L35`

### 多维度指标计算系统
- 指标配置与公式别名
  - 本地TypeScript常量提供900+ THS公式别名与参数说明，支持分类检索与变量默认值生成
  - 支持远程配置回退与版本对比，确保配置一致性与可维护性
- 计算模式
  - 支持单点、多期、滚动（TTM）、同比（YoY）等计算模式
  - 增强公式引擎统一入口，便于扩展与测试
- 归一化与精度控制
  - 通过统一的数据解析与清洗，减少噪声
  - 对百分比/比率类指标进行格式化输出，保持一致性

```mermaid
classDiagram
class FinancialCalculationService {
+calculateFormulaEnhanced()
+calculateMultipleFormulas()
+createTimeSeriesContext()
+createFormulaContextFromStatement()
}
class FinancialDataQueryService {
+extractMultipleIndicatorTimeSeries()
+calculateSingleIndicatorFromTemplate()
+validateIndicatorData()
}
class THSFormulaAliases {
+getAllThsFormulaAliases()
+getEvRelatedFormulas()
+createDefaultVariables()
}
FinancialCalculationService --> FinancialDataQueryService : "调用"
FinancialCalculationService --> THSFormulaAliases : "使用别名/变量"
```

图示来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L215-L380`
- `src/app/calculation-engine/services/financial-data-query.service.ts#L86-L139`
- `src/app/calculation-engine/constants/ths-formula-aliases.constants.ts#L575-L731`

章节来源
- `src/app/calculation-engine/constants/financial-indicators.constants.ts#L1-L489`
- `src/app/calculation-engine/constants/ths-formula-aliases.constants.ts#L1-L731`
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`

### 可比公司选择算法
- 贪婪搜索策略
  - 以某一目标指标为基准，逐步迭代选择最接近的候选公司，适合快速筛选与交互式探索
- 全局最优搜索策略
  - 在候选集合上进行穷举或启发式搜索，寻找整体最优组合，适合深度分析与稳健决策
- 适用场景
  - 贪婪：时间敏感、交互频繁的场景
  - 全局最优：对结果稳定性要求高、样本量适中的场景

```mermaid
flowchart TD
S(["开始"]) --> Init["初始化候选集与目标指标"]
Init --> Greedy{"选择策略？"}
Greedy --> |贪婪| SelectOne["选择最接近的公司"]
Greedy --> |全局最优| Enumerate["枚举/启发式搜索"]
SelectOne --> Next["更新剩余候选集"]
Enumerate --> Best["记录全局最优解"]
Next --> More{"仍有候选？"}
More --> |是| SelectOne
More --> |否| Output["输出结果"]
Best --> Output
```

图示来源
- `src/app/calculation-engine/services/financial-indicator.service.ts#L28-L98`

章节来源
- `src/app/calculation-engine/services/financial-indicator.service.ts#L1-L830`

### 熵权法与TOPSIS综合评价
- 权重分配
  - 基于熵值法计算指标客观权重，降低主观赋权偏差
- 排序计算
  - 采用TOPSIS方法，结合正理想解与负理想解进行排序
- 结果解释
  - 输出综合得分与排名，支持可视化展示与导出

```mermaid
flowchart TD
A(["输入指标矩阵"]) --> B["归一化处理"]
B --> C["计算熵值与权重"]
C --> D["确定正/负理想解"]
D --> E["计算距离"]
E --> F["计算相对接近度"]
F --> G["综合排序"]
G --> H(["输出结果"])
```

图示来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L215-L274`

章节来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`

### 报告自动生成
- 模板系统
  - 基于模板引擎，支持占位符与动态数据绑定
- 数据填充
  - 将计算结果注入模板，生成结构化内容
- 格式化输出
  - 导出为PDF/Word等格式，满足专业报告需求

```mermaid
sequenceDiagram
participant Calc as "计算服务"
participant Template as "模板引擎"
participant Output as "导出器"
Calc->>Template : 注入指标/图表数据
Template->>Output : 渲染并生成文档
Output-->>Calc : 返回报告文件
```

图示来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L215-L274`

章节来源
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`

### 跨平台桌面应用（Tauri）
- 框架与插件
  - Tauri 2 + 多种插件（HTTP/FS/Store/Process/Log/Updater/Clipboard/DeepLink等）
- 平台特性
  - Windows/macOS/Linux统一构建；窗口样式、透明、全屏等配置
  - 自动更新与深链支持
- 安全与性能
  - 沙箱化运行，最小权限原则；Rust后端提供高性能计算

```mermaid
graph TB
App["桌面应用"]
Tauri["Tauri 2"]
Plugins["插件生态<br/>http/fs/store/process/log/updater/..."]
OS["Windows/macOS/Linux"]
App --> Tauri
Tauri --> Plugins
Tauri --> OS
```

图示来源
- `src-tauri/Cargo.toml#L26-L59`
- `src-tauri/tauri.conf.json#L1-L70`

章节来源
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/tauri.conf.json#L1-L70`
- `src/main.ts#L1-L23`

## 依赖关系分析
- 前端依赖
  - Angular 22、Syncfusion/ECharts、RxJS、mathjs等
- 后端依赖
  - Tauri 2、reqwest、sea-orm、rayon、log、rust_xlsxwriter等
- 关键耦合点
  - 前端通过Tauri API与后端通信，后端再访问THS
  - 指标与公式配置由本地TS常量与远程JSON共同维护

```mermaid
graph LR
FE["Angular 前端"] --> TAURI["Tauri API"]
TAURI --> THS["THS API"]
FE --> CFG["指标/公式配置"]
FE --> CALC["计算服务"]
CALC --> FEAT["财务指标计算"]
FEAT --> OUT["结果/报告"]
```

图示来源
- `package.json#L19-L87`
- `src-tauri/Cargo.toml#L26-L59`
- `src/app/calculation-engine/constants/financial-indicators.constants.ts#L1-L489`

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

## 性能考量
- 按需懒加载与组件级变更检测优化，降低前端渲染开销
- Rust后端采用并行计算（rayon）与高效数据结构（indexmap），提升大规模指标计算速度
- SQLite本地存储与SeaORM结构化查询，减少网络往返
- 前端使用RxJS服务组合，避免状态库带来的额外复杂度

## 故障排查指南
- 数据缺失与解析异常
  - 使用字段缺失诊断与完整性校验，定位缺失指标与时间点
  - 检查电子表格JSON结构与字段映射
- 计算异常
  - 通过增强公式引擎的错误包装，定位具体公式与上下文
  - 核对所需字段是否齐全、时间点是否匹配
- THS接口问题
  - 检查Tauri HTTP插件配置与网络连通性
  - 关注返回状态码与超时设置

章节来源
- `src/app/calculation-engine/services/financial-indicator.service.ts#L649-L677`
- `src/app/calculation-engine/services/financial-data-query.service.ts#L440-L470`
- `src/app/calculation-engine/services/financial-calculation.service.ts#L250-L274`

## 结论
本系统通过前后端协同与Rust高性能计算，实现了从THS数据接入到多维度指标计算、可比公司选择、熵权法与TOPSIS综合评价以及报告自动生成的完整闭环。模块化设计与插件化架构确保了可扩展性与可维护性，适用于专业投资分析与估值研究场景。

## 附录
- 使用示例与最佳实践
  - 财务数据集成
    - 通过查询服务获取报表数据，使用模板化计算批量提取指标
    - 对缺失字段进行补全或剔除，确保计算稳定性
  - 指标计算
    - 优先使用公式别名与参数配置，减少手写公式错误
    - 对百分比类指标统一格式化输出，便于对比
  - 可比公司选择
    - 根据场景选择贪婪或全局最优策略；注意候选集质量与指标权重
  - 熵权法与TOPSIS
    - 确保指标方向一致与量纲统一；归一化后进行权重与排序计算
  - 报告生成
    - 使用模板系统统一风格；导出前进行数据校验与格式化
  - 跨平台应用
    - 遵循Tauri配置规范；关注不同平台的窗口与更新策略