# 开发指南

本文档说明项目开发时的基本流程、推荐实践和常见约定，帮助开发者快速上手并保持代码风格一致。

## 目标

- 统一开发流程和文档表达。
- 为新成员提供可直接遵循的实施说明。
- 降低项目协作中的理解成本。

## 开发前准备

1. 确认本地环境与依赖已正确安装。
2. 阅读相关模块说明和接口约定。
3. 以最小改动完成功能验证后再提交修改。

## 代码与文档要求

- 保持改动范围聚焦，避免无关变更。
- 变更完成后补充必要说明，确保文档和实现一致。
- 对关键流程和接口变更，应同步更新相关文档。

<cite>
**本文引用的文件**
- `package.json`
- `angular.json`
- `tsconfig.json`
- `tsconfig.app.json`
- `karma.conf.js`
- `src/main.ts`
- `src/app/app.component.ts`
- `src/app/app.config.ts`
- `src/app/app.routes.ts`
- `src/app/menu-items.ts`
- `src-tauri/Cargo.toml`
- `src-tauri/tauri.conf.json`
- `src-tauri/src/main.rs`
- `src-tauri/build.rs`
- `.gitignore`
- `README.md`
</cite>

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

## 简介
本指南面向GSDJGXApp（基金标的估值系统）的开发者，覆盖代码规范与最佳实践、开发工作流程、项目结构与模块划分、构建与开发工具链、调试技巧与工具使用、文档维护规范、常见问题与性能优化建议，以及贡献指南与协作规范。项目采用Angular 22 + Tauri 2 + Rust技术栈，结合pnpm与Cargo进行高效开发与构建。

## 项目结构
项目采用前后端分离的混合架构：
- 前端（Angular）：负责UI交互、路由与状态管理，构建产物由Tauri托管。
- 后端（Rust/Tauri）：提供高性能计算、系统能力访问、数据库与网络请求封装。
- 资源与脚本：统一通过pnpm与Angular CLI管理；Rust侧通过Cargo与Tauri CLI管理。

```mermaid
graph TB
subgraph "前端Angular"
FE_MAIN["src/main.ts"]
FE_APP["src/app/app.component.ts"]
FE_ROUTER["src/app/app.routes.ts"]
FE_CFG["angular.json<br/>tsconfig.json"]
end
subgraph "后端Tauri/Rust"
RS_MAIN["src-tauri/src/main.rs"]
RS_CARGO["src-tauri/Cargo.toml"]
RS_CONF["src-tauri/tauri.conf.json"]
RS_BUILD["src-tauri/build.rs"]
end
subgraph "工具与脚本"
PKG["package.json"]
GIT["gitignore"]
end
FE_MAIN --> FE_APP
FE_APP --> FE_ROUTER
FE_CFG --> FE_APP
FE_APP --> RS_CONF
RS_MAIN --> RS_CARGO
RS_BUILD --> RS_CARGO
PKG --> FE_CFG
PKG --> RS_CONF
GIT --> FE_CFG
GIT --> RS_CARGO
```

图表来源
- `src/main.ts#L1-L23`
- `src/app/app.component.ts#L1-L851`
- `src/app/app.routes.ts#L1-L104`
- `angular.json#L1-L79`
- `tsconfig.json#L1-L39`
- `src-tauri/src/main.rs#L1-L9`
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/tauri.conf.json#L1-L70`
- `src-tauri/build.rs#L1-L4`
- `package.json#L1-L90`
- `.gitignore#L1-L53`

章节来源
- `README.md#L1-L118`
- `package.json#L1-L90`
- `angular.json#L1-L79`
- `tsconfig.json#L1-L39`
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/tauri.conf.json#L1-L70`
- `.gitignore#L1-L53`

## 核心组件
- 应用入口与引导
  - 前端入口：注册语言与第三方库许可证，引导应用启动。
  - 后端入口：调用库函数运行应用。
- 路由与视图
  - Hash路由与多面板布局（左侧面板/主面板），支持默认与通配符重定向。
- 插件与系统能力
  - Tauri插件：进程、对话框、文件系统、剪贴板、日志、深链、更新器等。
- 配置与构建
  - Angular构建配置、TypeScript严格模式、Karma测试配置。
  - Tauri开发/生产配置、打包目标与签名密钥。

章节来源
- `src/main.ts#L1-L23`
- `src/app/app.config.ts#L1-L13`
- `src/app/app.routes.ts#L1-L104`
- `src/app/app.component.ts#L1-L851`
- `src-tauri/src/main.rs#L1-L9`
- `src-tauri/tauri.conf.json#L1-L70`
- `angular.json#L1-L79`
- `tsconfig.json#L1-L39`
- `karma.conf.js#L1-L62`

## 架构总览
应用采用“前端UI + 后端计算/系统能力”的双层架构，通过Tauri桥接前后端通信，实现桌面端原生体验与高性能计算能力。

```mermaid
graph TB
UI["前端UIAngular"]
ROUTER["路由与多面板布局"]
TAURI["Tauri桥接"]
RUST["Rust后端Tauri插件"]
DB["SQLiteSeaORM"]
NET["HTTP/网络请求"]
FS["文件系统/剪贴板/日志"]
UI --> ROUTER
UI --> TAURI
ROUTER --> TAURI
TAURI --> RUST
RUST --> DB
RUST --> NET
RUST --> FS
```

图表来源
- `src/app/app.component.ts#L1-L851`
- `src-tauri/Cargo.toml#L26-L66`
- `src-tauri/tauri.conf.json#L1-L70`

## 详细组件分析

### 前端应用组件（AppComponent）
AppComponent作为根组件，承担以下职责：
- 初始化与生命周期管理（启动代理模式检查、用户信息刷新、默认路由跳转）。
- 多面板导航与视图切换（左侧面板与主面板联动）。
- 通知系统（前端与后端通知聚合展示）。
- 窗口控制（最小化/最大化/关闭）。
- 事件监听与自定义事件派发（项目汇总、基金管理、节点选择等）。

```mermaid
classDiagram
class AppComponent {
+navigateFromRoot(outlets, preserveOthers, options)
+dockItem(event, data)
+onMenuSelect(event)
+setupBackendNotificationListener()
+refreshUserInfoOnStartup()
+handleAuthError()
+onMinimize()
+onMaximize()
+onCloseWindow()
+ngAfterViewInit()
+ngOnDestroy()
}
```

图表来源
- `src/app/app.component.ts#L59-L800`

章节来源
- `src/app/app.component.ts#L1-L851`

### 路由与多面板布局
- 路由定义：左右面板独立路由，支持参数化路由与默认/通配符重定向。
- 布局策略：通过命名出口（left-pane/main-pane）实现双面板布局，配合导航服务实现面板内切换。

```mermaid
flowchart TD
Start(["进入应用"]) --> DefaultRoute["默认重定向到<br/>左侧面板: fundtreeview<br/>主面板: welcome"]
DefaultRoute --> PanelLeft["左侧面板内容更新"]
DefaultRoute --> PanelMain["主面板内容更新"]
PanelLeft --> DockNav{"点击停靠项?"}
DockNav --> |是| SwitchPane["切换面板内容"]
DockNav --> |否| KeepDefault["保持默认视图"]
SwitchPane --> PanelMain
KeepDefault --> End(["完成"])
PanelMain --> End
```

图表来源
- `src/app/app.routes.ts#L16-L103`
- `src/app/app.component.ts#L88-L122`

章节来源
- `src/app/app.routes.ts#L1-L104`
- `src/app/app.component.ts#L88-L122`

### Tauri配置与插件
- 开发/构建配置：devUrl、beforeDevCommand、beforeBuildCommand、frontendDist。
- 安全与窗口：CSP禁用、透明窗口、标题栏样式等。
- 打包与更新：NSIS目标、更新器端点与公钥、图标资源。
- 插件：深链、更新器、进程、对话框、文件系统、剪贴板、日志等。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant CLI as "Tauri CLI"
participant FE as "前端构建"
participant TAURI as "Tauri配置"
participant APP as "桌面应用"
Dev->>CLI : "tauri dev"
CLI->>FE : "pnpm start"
FE-->>CLI : "dev server 启动"
CLI->>TAURI : "读取 tauri.conf.json"
TAURI-->>APP : "加载前端产物并运行"
Dev->>APP : "交互与调试"
```

图表来源
- `src-tauri/tauri.conf.json#L6-L11`
- `package.json#L12-L16`

章节来源
- `src-tauri/tauri.conf.json#L1-L70`
- `package.json#L1-L90`

### Rust后端与构建
- 包与特性：名称、版本、特性（macOS私有API、devtools）、依赖（Tauri、SeaORM、reqwest、log等）。
- 构建脚本：tauri-build集成。
- 入口：main调用库函数运行。

```mermaid
flowchart TD
Cargo["Cargo.toml 依赖与特性"] --> Build["build.rs 集成 tauri_build"]
Build --> Run["main.rs 调用库函数"]
Run --> App["应用运行Tauri上下文"]
```

图表来源
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/build.rs#L1-L4`
- `src-tauri/src/main.rs#L1-L9`

章节来源
- `src-tauri/Cargo.toml#L1-L66`
- `src-tauri/build.rs#L1-L4`
- `src-tauri/src/main.rs#L1-L9`

## 依赖关系分析
- 前端依赖：Angular核心、Syncfusion组件库、ECharts、RxJS、数学库等。
- 后端依赖：Tauri生态、SeaORM、reqwest、log、serde/json等。
- 构建与工具：Angular CLI、@angular-devkit、@tauri/cli、pnpm、TypeScript。

```mermaid
graph LR
Pkg["package.json 依赖"] --> FE["Angular 前端"]
Pkg --> TauriCLI["@tauri/cli"]
Cargo["Cargo.toml 依赖"] --> BE["Rust 后端"]
FE --> TauriConf["tauri.conf.json"]
BE --> TauriConf
```

图表来源
- `package.json#L19-L88`
- `src-tauri/Cargo.toml#L26-L66`
- `src-tauri/tauri.conf.json#L1-L70`

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

## 性能考虑
- 前端
  - 严格类型与编译选项提升质量与性能。
  - 开发配置启用SourceMap便于调试。
  - 生产配置开启优化与输出哈希。
- 后端
  - 开发配置禁用增量编译以保证一致性。
  - 使用高性能库（如SeaORM、reqwest、rayon）提升计算与IO性能。
- 构建
  - pnpm与Cargo分别管理前端与后端依赖，减少冗余与冲突。

章节来源
- `tsconfig.json#L1-L39`
- `angular.json#L28-L45`
- `src-tauri/Cargo.toml#L61-L66`

## 故障排查指南
- 启动与构建
  - 前端：确认Node.js与pnpm版本满足要求，执行安装与启动脚本。
  - 后端：确认Rust工具链版本与Tauri依赖，按平台安装系统依赖。
- 调试
  - 前端：使用浏览器开发者工具检查网络、控制台与性能。
  - 后端：利用Rust日志与Tauri devtools，结合日志插件定位问题。
  - 集成：通过Tauri事件与通知系统验证前后端通信。
- 测试
  - 使用Karma/Jasmine进行单元测试与覆盖率统计，建议覆盖率门槛≥70%。

章节来源
- `README.md#L35-L87`
- `karma.conf.js#L1-L62`
- `src-tauri/tauri.conf.json#L12-L29`

## 结论
本指南提供了GSDJGXApp的开发规范、工作流程、项目结构与工具链的系统性说明，并结合实际配置文件给出可操作的实践建议。建议开发者在日常开发中遵循本文规范，确保代码质量与协作效率。

## 附录

### 代码规范与最佳实践
- Angular代码风格
  - 使用严格类型与编译选项，启用模板与输入严格模式。
  - 组件职责单一，服务组合式状态管理，避免全局状态滥用。
  - 路由采用Hash策略，便于桌面端部署与更新。
- Rust编程规范
  - 使用稳定的特性集与明确的依赖版本，避免不必要的特性开销。
  - 日志分级明确，错误处理统一，必要时使用错误码与消息体。
- 命名约定
  - 前端：组件与服务采用帕斯卡命名，变量与方法采用驼峰命名。
  - 后端：模块与函数采用蛇形命名，常量采用大写蛇形。
- 注释标准
  - 关键逻辑与公共接口添加注释，说明输入、输出与异常场景。
  - 复杂算法与业务规则提供背景说明与参考链接。

章节来源
- `tsconfig.json#L31-L37`
- `angular.json#L24-L26`
- `src/app/app.config.ts#L1-L13`
- `src-tauri/Cargo.toml#L26-L66`

### 开发工作流程
- 分支管理
  - 功能分支：feature/<模块>-<简述>
- 提交信息
  - 格式：<scope>: <简要动词描述>（例如：calculation: add entropy weight edge cases）
- 代码审查
  - 提交PR前运行测试与构建，确保通过CI检查。
- 文档维护
  - 重要结构变更需在docs/目录新增说明文档。

章节来源
- `README.md#L99-L108`

### 构建与开发工具链
- pnpm
  - 依赖管理与脚本执行，统一前端与脚本工具链。
- Angular CLI
  - 构建、开发服务器与测试配置，严格TS配置保障质量。
- Rust Cargo
  - 编译与依赖管理，集成Tauri构建脚本。
- Tauri
  - 开发/生产配置、打包目标与更新器配置。

章节来源
- `package.json#L4-L16`
- `angular.json#L14-L75`
- `tsconfig.app.json#L1-L10`
- `src-tauri/Cargo.toml#L23-L24`
- `src-tauri/tauri.conf.json#L6-L11`

### 调试技巧与工具使用
- 浏览器开发者工具
  - 检查网络请求、控制台错误、性能与内存占用。
- Rust调试器
  - 使用日志与断点，结合Tauri devtools查看事件与状态。
- 性能分析
  - 前端：关注路由懒加载与组件变更检测优化。
  - 后端：对高耗时计算使用并行与缓存策略。

章节来源
- `README.md#L80-L87`
- `src-tauri/tauri.conf.json#L12-L29`

### 常见问题与性能优化建议
- 常见问题
  - 依赖版本不匹配导致构建失败，优先核对Node.js、pnpm与Rust版本。
  - Tauri开发时前端未热更新，检查devUrl与beforeDevCommand配置。
- 性能优化
  - 前端：按需加载、组件级变更检测优化、CSS体积优化。
  - 后端：合理使用并发与缓存，避免阻塞主线程。

章节来源
- `README.md#L35-L38`
- `README.md#L31-L31`

### 贡献指南与协作规范
- 私有项目协作
  - 遵循分支与提交规范，重要变更同步文档。
- 版本发布
  - 在提交信息中包含版本标记时自动更新版本号。

章节来源
- `README.md#L99-L108`