# 前端API接口

<cite>
**本文档引用的文件**
- `src/app/services/navigation.service.ts`
- `src/app/services/globalvariable.service.ts`
- `src/app/calculation-engine/services/financial-calculation.service.ts`
- `src/app/calculation-engine/services/parameter-settings.service.ts`
- `src/app/calculation-engine/services/financial-indicator.service.ts`
- `src/app/calculation-engine/services/financial-indicators-analysis.service.ts`
- `src/app/services/ifind-query-builder.service.ts`
- `src/app/calculation-engine/constants/adjustment-parameters.constants.ts`
- `src/app/calculation-engine/types/financial-indicators-analysis-data.interface.ts`
- `src/app/calculation-engine/types/financial-indicators-data.interface.ts`
</cite>

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

## 简介

本文档详细记录了GSDJGXApp Angular项目前端API接口的完整规范，涵盖导航控制、全局状态管理和金融计算三大核心服务层。该系统采用模块化设计，通过服务依赖注入实现松耦合架构，支持复杂的财务数据分析和企业估值计算。

系统主要特性包括：
- 多面板导航管理（左右侧边栏）
- 全局状态管理（应用模式、项目状态、服务状态）
- 统一的金融计算引擎
- 参数化配置管理
- 动态查询构建
- 数据持久化和分析

## 项目结构

项目采用基于功能域的模块化组织方式，核心结构如下：

```mermaid
graph TB
subgraph "服务层"
A[NavigationService<br/>导航控制]
B[GlobalVariableService<br/>全局状态管理]
C[FinancialCalculationService<br/>金融计算引擎]
end
subgraph "计算引擎模块"
D[DataTransformModule<br/>数据转换]
E[CalculationEngineModule<br/>计算引擎]
F[DataQueryModule<br/>数据查询]
end
subgraph "配置管理"
G[ParameterSettingsService<br/>参数设置]
H[IFindQueryBuilderService<br/>查询构建器]
I[AdjustmentParameters<br/>调整参数]
end
subgraph "分析服务"
J[FinancialIndicatorService<br/>财务指标计算]
K[FinancialIndicatorsAnalysisService<br/>分析数据管理]
end
A --> C
B --> C
C --> D
C --> E
C --> F
G --> H
G --> I
J --> C
K --> C
```

**图表来源**
- `src/app/services/navigation.service.ts#L1-L228`
- `src/app/services/globalvariable.service.ts#L1-L442`
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`

## 核心组件

### NavigationService 导航控制接口

NavigationService提供完整的多面板导航管理功能，支持复杂的路由状态控制和面板独立操作。

**核心方法概览：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| navigateFromRoot | newOutlets: object, preserveOthers?: boolean, extras?: NavigationExtras | Promise<boolean> | 从根路径导航到指定outlets |
| navigateToLeftPane | path: string, params?: string[], extras?: NavigationExtras | Promise<boolean> | 导航到左侧面板 |
| navigateToMainPane | path: string, params?: string[], extras?: NavigationExtras | Promise<boolean> | 导航到主面板 |
| navigateToBothPanes | leftPath: string, mainPath: string, leftParams?: string[], mainParams?: string[], extras?: NavigationExtras | Promise<boolean> | 同时导航到双面板 |
| navigateToWelcome | preserveLeftPane?: boolean | Promise<boolean> | 导航到欢迎页面 |
| navigateToMainPaneOnly | path: string, params?: string[], extras?: NavigationExtras | Promise<boolean> | 仅导航到主面板 |
| navigateToLeftPaneOnly | path: string, params?: string[], extras?: NavigationExtras | Promise<boolean> | 仅导航到左侧面板 |
| navigateToDefault | extras?: NavigationExtras | Promise<boolean> | 导航到默认状态 |
| clearAllOutlets |  | Promise<boolean> | 清除所有outlets |

**异步操作处理：**
- 所有导航方法均返回Promise<boolean>，用于异步等待导航完成
- 内部使用Angular Router的navigate和navigateByUrl方法
- 支持NavigationExtras配置，包括queryParams、fragment等

**使用示例：**
```typescript
// 导航到左侧面板
await navigationService.navigateToLeftPane('fund-list', ['fund-001']);

// 同时导航到双面板
await navigationService.navigateToBothPanes(
  'fund-tree', 
  'financial-statement'
);

// 从根路径导航
await navigationService.navigateFromRoot({
  'left-pane': ['fund-tree'],
  'main-pane': ['welcome']
});
```

### GlobalVariableService 全局状态管理接口

GlobalVariableService提供应用级别的状态管理，通过RxJS BehaviorSubject实现响应式状态更新。

**核心状态属性：**

| 属性名 | 类型 | 描述 |
|--------|------|------|
| appMode$ | Observable<AppMode> | 应用模式流（fund-tree/directory-browser） |
| currentProjectId$ | Observable<number \| null> | 当前项目ID流 |
| tempFundInfo$ | Observable<{name, code} \| null> | 临时基金信息流 |
| thsServiceStatus$ | Observable<ThsServiceStatusInfo> | 同花顺服务状态流 |
| officeServiceStatus$ | Observable<OfficeServiceStatusInfo> | 办公系统服务状态流 |

**状态管理方法：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| setAppMode | mode: AppMode | void | 设置应用模式 |
| setCurrentProjectId | projectId: number \| null | void | 设置当前项目ID |
| setTempFundInfo | fundInfo: {name, code} \| null | void | 设置临时基金信息 |
| setThsServiceStatus | status: ThsServiceStatus, message: string | void | 设置同花顺服务状态 |
| setOfficeServiceStatus | status: OfficeServiceStatus, message: string | void | 设置办公系统服务状态 |
| resetToFundTreeMode |  | void | 重置到基金树模式 |

**响应式编程模式：**
- 使用BehaviorSubject确保新订阅者能立即获得最新状态
- 自动发送全局事件通知其他组件
- 支持状态变更的链式反应

**使用示例：**
```typescript
// 订阅应用模式变化
globalVariableService.appMode$.subscribe(mode => {
  console.log('应用模式:', mode);
});

// 设置当前项目
globalVariableService.setCurrentProjectId(123);

// 检查服务状态
if (globalVariableService.isThsServiceOk()) {
  // 执行相关操作
}
```

### OfficeBindingStore 办公系统绑定共享状态接口

OfficeBindingStore 是绑定状态的**全局共享 Signal 存储（单一数据源）**。项目汇总表、数据校验、报告管理三个页面（同处基金管理 ejs-tab 内，组件常驻不销毁）都通过它读取绑定状态；绑定/换绑/解绑/确认数据后调用 `upsert`/`remove`，其他页面通过 signal 依赖即时刷新（Zoneless 下 signal 写入自动调度变更检测）。

**核心属性：**

| 属性名 | 类型 | 描述 |
|--------|------|------|
| bindings | Signal\<ReadonlyMap\<number, OfficeDataBindingInfo\>\> | 全部绑定关系（只读 signal，以 project_id 为键） |

**主要方法：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| loadAll |  | Promise\<void\> | 从后端加载全部绑定并整体替换 |
| loadByProjectIds | projectIds: number[] | Promise\<void\> | 按项目 ID 集合加载并合并（保留其他项目记录） |
| upsert | binding: OfficeDataBindingInfo | void | 新增/更新一条绑定（绑定、换绑、确认数据后调用） |
| remove | projectId: number | void | 移除一条绑定（解绑后调用） |
| isBound | projectId: number | boolean | 项目是否已绑定 |
| get | projectId: number | OfficeDataBindingInfo \| undefined | 获取绑定信息 |

**使用约定：**
- 内部 Map 采用**不可变更新**（整体替换），原地 mutate 不会触发 signal 通知；
- 任何修改绑定表的后端调用成功后，必须调用 `upsert`/`remove` 同步 store，禁止在组件内私有缓存绑定快照（历史上因此导致跨标签页按钮状态过期）。

### OfficeDataBindingService 办公系统绑定 IPC 接口

OfficeDataBindingService 封装与 Rust 后端的 Tauri invoke 调用，管理本地项目与办公系统（Luculent）远程项目的绑定关系与数据确认状态。

**绑定关系方法：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| initTable |  | Promise\<void\> | 初始化绑定表 |
| createBinding | dto: CreateOfficeDataBindingDto | Promise\<OfficeDataBindingInfo\> | 创建绑定关系 |
| getBindingByProjectId | projectId: number | Promise\<OfficeDataBindingInfo \| null\> | 按项目 ID 查询绑定 |
| getBindingByProjectCode | projectCode: string | Promise\<OfficeDataBindingInfo \| null\> | 按项目代号查询绑定 |
| unbindByProjectId | projectId: number | Promise\<boolean\> | 解除绑定 |
| getAllBindings |  | Promise\<OfficeDataBindingInfo[]\> | 获取全部绑定 |
| getBindingsByProjectIds | projectIds: number[] | Promise\<OfficeDataBindingInfo[]\> | 批量获取绑定状态 |
| checkRemoteProjectBound | remoteProNo, remoteZbNo, excludeProjectId? | Promise\<OfficeDataBindingInfo \| null\> | 检查远程项目是否已被其他本地项目绑定（换绑场景排除自身） |

**数据确认方法：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| updateDataStatus | projectId, dataStatus: DataStatusPayload | Promise\<OfficeDataBindingInfo\> | 写入确认快照（data_status 数组按 project_code + assessment_base_date 联合唯一，自动合并去重） |
| buildDataStatusFromGridRow | row, remoteProNo, projectName | Promise\<DataStatusPayload\> | 从数据校验 Grid 行构建确认快照（非市场比较法时自动附带方法与原因备注） |
| isDataStatusConfirmed | savedDataStatus, remoteProNo, assessmentBaseDate | boolean | 指定基准日是否已确认 |
| checkDataStatusConsistency | savedDataStatus, currentRow, remoteProNo | boolean | 已确认数据与当前行是否一致（不一致时按钮显示"需重新确认"） |
| updateInvestmentDate | projectId, investmentDate | Promise\<OfficeDataBindingInfo\> | 更新投资日期 |
| clearDataStatus | projectId | Promise\<OfficeDataBindingInfo\> | 清除数据状态 |

**工具方法：** `normalizeDateToYYYYMMDD`、`normalizeRemoteInvestmentDate`（多格式日期归一化为 YYYY-MM-DD）、`createBindingDtoFromRemote`（远程项目信息转绑定 DTO）。

### FinancialCalculationService 金融计算接口

FinancialCalculationService提供统一的财务计算API，整合数据转换、计算引擎和数据查询功能。

**数据转换功能：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| extractConfiguredFieldsFromStatement | statement: any | any | 从财务报表提取配置字段 |
| transformStatementToDataPoints | statement: any | any[] | 转换报表为数据点 |
| transformStatementsToTimeSeries | statements: any[], groupByIndicator?: boolean | any[] | 转换报表为时间序列 |
| createTimePointFromDate | dateString: string | any | 从日期创建时间点 |
| parseNumericValue | value: any | number \| null | 解析数值 |

**计算引擎功能：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| calculateIndicator | config: any, context: any | any | 计算单个指标 |
| calculateMultipleIndicators | configs: any[], context: any | any[] | 计算多个指标 |
| calculateTTM | formula: string, context: any | number \| null | TTM计算 |
| calculateYoY | formula: string, context: any | number \| null | YoY计算 |
| calculateFormula | formula: string, context: any | number \| null | 公式计算 |
| getDirectValue | fieldName: string, context: any | number \| null | 直接取值 |

**数据查询功能：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| extractMultipleIndicatorTimeSeries | statements: any[], indicatorNames: string[], projectId?: number | any[] | 提取多个指标时间序列 |
| extractIndicatorTimeSeries | statements: any[], indicatorName: string, projectId?: number | any[] | 提取单个指标时间序列 |
| getFinancialStatements | projectId: number | Promise<any[]> | 获取财务报表数据 |
| calculateFinancialIndicators | projectId: number, targetTimePoint?: any | Promise<any> | 一站式财务指标计算 |

**增强公式计算：**

| 方法名 | 参数 | 返回值 | 描述 |
|--------|------|--------|------|
| calculateFormulaEnhanced | formula: string, context: FormulaContext \| TimeSeriesContext, options?: any | FormulaResult | 增强版公式计算 |
| calculateMultipleFormulas | formulas: any[], context: FormulaContext \| TimeSeriesContext | {id: FormulaResult} | 批量计算公式 |
| createTimeSeriesContext | currentPeriodData: FormulaContext, historicalData?: any | TimeSeriesContext | 创建时间序列上下文 |

**使用示例：**
```typescript
// 获取财务报表数据
const statements = await financialCalculationService.getFinancialStatements(123);

// 创建时间序列上下文
const context = financialCalculationService.createTimeSeriesContextFromStatements(statements);

// 计算多个指标
const results = await financialCalculationService.calculateMultipleFormulas([
  {
    id: 'revenue_growth',
    formula: 'revenue_ttm / revenue_previous_year - 1',
    calculationType: 'yoy'
  },
  {
    id: 'roic',
    formula: '(ebit - taxes) / (total_assets - current_liabilities)',
    calculationType: 'formula'
  }
], context);

// 增强公式计算
const enhancedResult = financialCalculationService.calculateFormulaEnhanced(
  'ev_ebitda_ttm',
  context,
  {
    calculationType: 'ttm',
    timeContext: 'single-point'
  }
);
```

## 架构概览

系统采用分层架构设计，各层职责清晰分离：

```mermaid
graph TB
subgraph "表现层"
A[组件层]
B[指令层]
C[管道层]
end
subgraph "服务层"
D[NavigationService]
E[GlobalVariableService]
F[ParameterSettingsService]
end
subgraph "计算引擎层"
G[FinancialCalculationService]
H[DataTransformModule]
I[CalculationEngineModule]
J[DataQueryModule]
end
subgraph "分析层"
K[FinancialIndicatorService]
L[FinancialIndicatorsAnalysisService]
end
subgraph "基础设施层"
M[IFindQueryBuilderService]
N[AdjustmentParameters]
O[数据库服务]
end
A --> D
A --> E
A --> F
D --> G
E --> G
F --> M
G --> H
G --> I
G --> J
K --> G
L --> G
M --> N
G --> O
```

**图表来源**
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`
- `src/app/calculation-engine/services/parameter-settings.service.ts#L1-L800`

## 详细组件分析

### NavigationService 详细分析

NavigationService实现了复杂的多面板路由管理，支持以下核心功能：

**URL解析机制：**
- 支持Angular多outlet格式：`/(left-pane:fund-tree//main-pane:welcome)`
- 自动解析当前URL中的outlet状态
- 提供默认状态回退机制

**导航策略：**
- `preserveOthers`: 控制是否保持其他面板状态
- `skipLocationChange`: 清除路由状态避免历史记录污染
- 支持相对路径和绝对路径导航

```mermaid
sequenceDiagram
participant Component as 组件
participant NavService as NavigationService
participant Router as Angular Router
participant URL as URL状态
Component->>NavService : navigateToBothPanes(left, main)
NavService->>NavService : getCurrentOutlets()
NavService->>NavService : 构建finalOutlets
NavService->>Router : navigateByUrl('/', {skipLocationChange : true})
Router->>URL : 清除当前状态
NavService->>Router : navigate([{outlets : finalOutlets}])
Router-->>Component : 导航完成
```

**图表来源**
- `src/app/services/navigation.service.ts#L62-L83`

**错误处理：**
- URL解析失败时返回默认状态
- 导航失败时抛出异常
- 支持异步错误捕获

### GlobalVariableService 状态管理分析

GlobalVariableService采用响应式编程模式，提供以下状态管理能力：

**状态隔离：**
- 每个状态使用独立的BehaviorSubject
- 提供getter/setter访问器
- 支持状态变更监听

**事件驱动：**
- 自动发送CustomEvent通知
- 支持跨组件通信
- 提供状态变更历史

```mermaid
classDiagram
class GlobalVariableService {
-_workspacePath : string
-_isDirectoryLoaded : boolean
-_currentProjectId : BehaviorSubject
-_tempFundInfo : BehaviorSubject
-_thsServiceStatus : BehaviorSubject
-_officeServiceStatus : BehaviorSubject
+appMode$ : Observable
+currentProjectId$ : Observable
+tempFundInfo$ : Observable
+thsServiceStatus$ : Observable
+officeServiceStatus$ : Observable
+setAppMode(mode)
+setCurrentProjectId(id)
+setTempFundInfo(info)
+setThsServiceStatus(status, message)
+setOfficeServiceStatus(status, message)
}
class ThsServiceStatusInfo {
+status : ThsServiceStatus
+message : string
+lastUpdated : Date
}
class OfficeServiceStatusInfo {
+status : OfficeServiceStatus
+message : string
+lastUpdated : Date
}
GlobalVariableService --> ThsServiceStatusInfo
GlobalVariableService --> OfficeServiceStatusInfo
```

**图表来源**
- `src/app/services/globalvariable.service.ts#L51-L104`

**状态同步：**
- 自动数据库路径同步
- 工作区路径变更通知
- 应用模式自动切换

### FinancialCalculationService 计算引擎分析

FinancialCalculationService提供统一的计算接口，内部集成三个核心模块：

**模块化设计：**
- DataTransformModule：数据转换和预处理
- CalculationEngineModule：指标计算逻辑
- DataQueryModule：数据查询和获取

**增强公式引擎：**
- 支持TTM、YoY、时间序列等多种计算类型
- 动态公式解析和执行
- 计算上下文管理

```mermaid
flowchart TD
Start([开始计算]) --> GetData["获取财务报表数据"]
GetData --> ParseData["解析数据为上下文"]
ParseData --> BuildContext["构建计算上下文"]
BuildContext --> SelectCalc["选择计算类型"]
SelectCalc --> TTM["TTM计算"]
SelectCalc --> YoY["YoY计算"]
SelectCalc --> Formula["公式计算"]
SelectCalc --> Direct["直接取值"]
TTM --> FormatResult["格式化结果"]
YoY --> FormatResult
Formula --> FormatResult
Direct --> FormatResult
FormatResult --> StoreResult["存储计算结果"]
StoreResult --> End([结束])
```

**图表来源**
- `src/app/calculation-engine/services/financial-calculation.service.ts#L184-L206`

**批量计算优化：**
- 支持多指标并发计算
- 计算结果缓存机制
- 错误隔离和恢复

## 依赖关系分析

系统依赖关系呈现清晰的层次结构：

```mermaid
graph LR
subgraph "外部依赖"
A[Angular Router]
B[RxJS]
C[@tauri-apps/api]
end
subgraph "内部服务"
D[NavigationService]
E[GlobalVariableService]
F[ParameterSettingsService]
G[IFindQueryBuilderService]
H[FinancialCalculationService]
I[FinancialIndicatorService]
J[FinancialIndicatorsAnalysisService]
end
subgraph "工具模块"
K[EnhancedFormulaEngine]
L[DatabasePathBuilder]
M[DateUtils]
end
A --> D
B --> E
C --> F
C --> J
D --> H
E --> H
F --> G
F --> H
G --> H
H --> I
H --> J
H --> K
E --> L
I --> M
```

**图表来源**
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L30`
- `src/app/calculation-engine/services/parameter-settings.service.ts#L1-L13`

**循环依赖检测：**
- 服务间通过接口和抽象类避免直接循环依赖
- 使用延迟初始化减少启动时依赖
- 通过模块边界控制依赖传播

## 性能考虑

### 导航性能优化

**路由状态管理：**
- 使用`skipLocationChange`避免历史记录膨胀
- 批量状态更新减少路由变更次数
- 面板独立导航避免不必要的状态重置

**内存管理：**
- 及时取消Observable订阅
- 避免在导航过程中创建大量临时对象
- 使用`async`管道处理异步数据

### 计算性能优化

**数据缓存策略：**
- 财务报表数据缓存
- 计算结果缓存
- 参数配置缓存

**异步处理：**
- 批量计算使用Promise.all
- 长时间计算使用Web Workers
- 分页加载大数据集

**内存优化：**
- 及时释放大对象引用
- 使用流式处理大数据
- 避免内存泄漏

## 故障排除指南

### 常见错误类型

**导航错误：**
- URL格式错误：检查多outlet语法
- 路由配置缺失：确认路由定义
- 权限验证失败：检查认证状态

**状态管理错误：**
- 状态不一致：检查事件广播
- 内存泄漏：确认订阅取消
- 异步竞态：使用防抖处理

**计算错误：**
- 数据格式错误：验证输入数据
- 公式解析失败：检查公式语法
- 依赖字段缺失：验证必需字段

### 调试工具

**开发工具：**
- Angular DevTools监控组件状态
- RxJS Marble Diagram调试
- Network面板监控API请求

**日志记录：**
- 服务层统一错误处理
- 关键操作日志记录
- 性能指标监控

**错误码定义：**

| 错误码 | 类型 | 描述 | 处理建议 |
|--------|------|------|----------|
| NAV_001 | 导航错误 | URL格式无效 | 检查路由配置 |
| NAV_002 | 导航错误 | 导航超时 | 增加超时时间 |
| STATE_001 | 状态错误 | 状态不一致 | 检查事件处理 |
| CALC_001 | 计算错误 | 数据格式错误 | 验证输入数据 |
| CALC_002 | 计算错误 | 公式解析失败 | 检查公式语法 |
| DB_001 | 数据库错误 | 连接失败 | 检查数据库配置 |

**章节来源**
- `src/app/services/navigation.service.ts#L1-L228`
- `src/app/services/globalvariable.service.ts#L1-L442`
- `src/app/calculation-engine/services/financial-calculation.service.ts#L1-L380`

## 结论

本前端API接口体系提供了完整的财务分析和企业估值解决方案。通过模块化设计和响应式编程模式，系统实现了高内聚、低耦合的架构。核心服务层提供了丰富的API接口，支持复杂的业务场景和灵活的扩展需求。

**主要优势：**
- 清晰的职责分离和模块化设计
- 强大的响应式状态管理
- 灵活的计算引擎和参数配置
- 完善的错误处理和调试支持

**未来发展：**
- 继续优化计算性能和内存使用
- 增强API文档和类型安全性
- 扩展更多财务分析功能
- 改进用户体验和交互设计

## 附录

### 版本兼容性

**API版本：** 1.0.0
**向后兼容性：** 通过接口抽象和默认参数保证
**废弃接口：** `getIndicatorConfig()` 已标记为废弃

### 最佳实践

**组件与服务交互：**
- 使用依赖注入获取服务实例
- 通过Observable订阅状态变化
- 正确处理异步操作和错误

**性能优化建议：**
- 合理使用`ChangeDetectionStrategy.OnPush`
- 避免在模板中进行复杂计算
- 使用`trackBy`函数优化列表渲染

**安全考虑：**
- 输入数据验证和清理
- 敏感信息加密存储
- 权限控制和访问验证