xiaojiawang/WCTDataMiner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新项目架构与数据模型文档

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Scottxjw
2026-08-13 15:01:32 +08:00
parent a3100c73c5
commit 2b031995e1
9 changed files with 678 additions and 885 deletions
Download Patch File Download Diff File Expand all files Collapse all files

277
docs/architecture/模块划分.md
View File

@@ -4,167 +4,172 @@
---
## 1. 模块总览
## 1. 分层架构
```
┌─────────────────────────────────────────────────────────────┐
│ CLI Entry Point │
│ (Program.cs / System.CommandLine) │
├─────────────────────────────────────────────────────────────┤
│ Service Layer │
├─────────────────────────────────────────────────────────────┤
│ ParseService │ ScenarioService │ DimensionService │ ThresholdCalc │
├─────────────────────────────────────────────────────────────┤
│ Parser Layer │
├─────────────────────────────────────────────────────────────┤
│ QfodParser │ PlossParser │ FileNameParser │
├─────────────────────────────────────────────────────────────┤
│ Data Layer │
├─────────────────────────────────────────────────────────────┤
│ Models │ WctMinerDbContext │ IDbContextFactory │
├─────────────────────────────────────────────────────────────┤
│ Infrastructure │
├─────────────────────────────────────────────────────────────┤
│ Configuration │ Serilog │ AppSettings │
└─────────────────────────────────────────────────────────────┘
```
| 层级 | 目录 | 职责 | 依赖 |
|------|------|------|------|
| CLI | `Gpulse.WCT.DataAnalyzer/Commands/` | 接收参数、流程调度、结果输出 | Application |
| Application | `Core/Application/` | 业务流程编排 | Domain, Infrastructure |
| Domain | `Core/Domain/Models/` | 实体定义，无行为 | 无 |
| Infrastructure | `Core/Infrastructure/` | 数据持久化、配置、安全 | Domain |
**依赖规则:**
- 上层可依赖下层，下层不可依赖上层
- Application 依 Domain 和 Infrastructure
- Infrastructure 依 Domain
- Domain 不依赖任何其他层
- 解析器之间不可互相调用
---
## 2. 模块职责
## 2. Application 模块职责
| 模块名 | 职责 | 依赖模块 |
|--------|------|----------|
| CLI Entry | 接收命令行参数、调度解析流程 | ParseService, Infrastructure |
| ParseService | 协调解析流程、批量写入、场景关联 | Parser Layer, ScenarioService, DbContext |
| ScenarioService | 创建/查询测试场景，解析文件名获取场景信息 | DimensionService, DbContext |
| DimensionService | 维度表 CRUD（获取或创建维度记录） | DbContext |
| FileNameParser | 解析文件名提取场景信息（面板、版本、RX类型等） | 无 |
| LogFileReader | 读取日志文件、行过滤、文件遍历 | 无 |
| QfodParser | 解析 Qfod 格式日志，返回 QfodRecord | 无 |
| PlossParser | 解析 Ploss 格式日志，返回 PlossRecord | 无 |
| Models | 定义数据实体结构（维度表 + 事实表） | 无 |
| WctMinerDbContext | EF Core 数据库上下文 | Models, Configurations |
| Configuration | 加载配置文件 | 无 |
| Serilog | 结构化日志输出（含解析错误日志） | 无 |
| ThresholdCalculator | 根据 RxPower 计算动态阈值 | 无 |
### 2.1 Parsing — 解析
| 类 | 职责 |
|----|------|
| `FileNameParser` | 从文件名提取场景信息（面板、硬件、软件、RX类型、日期、序号） |
| `QfodParser` | 解析 Qfod 格式日志行 → `QfodRecord` |
| `PlossParser` | 解析 Ploss 单行/两行格式日志 → `PlossRecord` |
### 2.2 LocalIngestion — 本地解析
| 类 | 职责 |
|----|------|
| `ParseService` | 协调解析流程：读取文件 → 解析 → 批量写入 local.db |
| `ScenarioService` | 创建/查询测试场景，并发安全 upsert |
| `DimensionService` | 维度表 get-or-create |
### 2.3 Publishing — 发布汇总
| 类 | 职责 |
|----|------|
| `AggregationService` | 读取 local.db → 按业务键分组计算 → upsert 到 release.db |
| `ThresholdCalculator` | 动态阈值计算 |
### 2.4 Exporting — 导出
| 类 | 职责 |
|----|------|
| `ExportService` | 导出 release.db 到固定 CSV，也支持 legacy Qfod/Ploss 导出 |
### 2.5 Administration — 管理
| 类 | 职责 |
|----|------|
| `StatsService` | 本地库统计查询 |
| `CleanService` | 软删除管理 |
---
## 3. 分层架构
## 3. Domain 实体
### 3.1 分层定义
### 3.1 本地实体（local.db）
| 层级 | 职责 | 允许调用 |
|------|------|----------|
| CLI Entry | 接收参数、流程调度、结果输出 | Service, Infrastructure |
| Service | 协调解析流程、场景管理、维度管理、批量写入 | Parser, Data, Infrastructure |
| Parser | 日志解析、文件名解析、数据提取 | 无 |
| Data | 数据持久化、DbContext 管理、实体配置 | Infrastructure |
| Infrastructure | 配置、日志 | 无 |
| 实体 | 表 | 说明 |
|------|----|------|
| `TxPanel` | tx_panel | TX 面板类型维度 |
| `TxHardware` | tx_hardware | TX 硬件版本维度 |
| `TxSoftware` | tx_software | TX 软件版本维度 |
| `RxType` | rx_type | RX 类型维度 |
| `TestScenario` | test_scenario | 测试场景（4 个维度外键 + 日期 + 序号） |
| `QfodRecord` | qfod_record | Qfod 检测数据 |
| `PlossRecord` | ploss_record | Ploss FOD 数据 |
### 3.2 依赖规则
关系：维度表 1:N TestScenario 1:N QfodRecord/PlossRecord（星型模型）
- 上层可调用下层
- 下层不可调用上层
- Parser 之间不可互相调用（独立解析器）
- Service 层协调 Parser 和 Data 层
- 解析错误通过 Serilog 记录，不存入业务数据库
### 3.2 发布实体（release.db）
| 实体 | 表 | 唯一键 |
|------|----|--------|
| `ChargingParameterRecord` | charging_parameter | (car_factory, car_model, phone_brand, phone_model) |
**两个数据库不建立外键或导航属性关联。**
---
## 4. 模块依赖图
## 4. Infrastructure 模块
### 4.1 LocalData — 本地数据库
| 类 | 职责 |
|----|------|
| `WctMinerDbContext` | 本地解析库 EF Core 上下文 |
| `DbContextFactory` | 根据配置创建 SQLite/PostgreSQL 本地上下文 |
| `IDbContextFactory` | 工厂接口 |
| `SeedData` | 默认维度数据初始化 |
| `Configurations/*` | EF Core `IEntityTypeConfiguration` 实现 |
### 4.2 ReleaseData — 发布数据库
| 类 | 职责 |
|----|------|
| `ReleaseDbContext` | 发布库 EF Core 上下文 |
| `ReleaseDbContextFactory` | 创建发布库上下文 |
| `IReleaseDbContextFactory` | 工厂接口 |
| `Configurations/*` | 发布实体配置 |
### 4.3 Configuration
| 类 | 职责 |
|----|------|
| `AppSettings` | 应用配置 POCO |
### 4.4 Security
| 类 | 职责 |
|----|------|
| `PathValidator` | 路径安全校验（遍历保护、白名单、应用目录限制） |
| `SecurityConstants` | 安全常量 |
### 4.5 Extensions
| 类 | 职责 |
|----|------|
| `ServiceCollectionExtensions` | `AddDatabaseServices` / `AddApplicationServices` DI 注册 |
---
## 5. 依赖图
```mermaid
graph TD
CLI[CLI Entry] --> PS[ParseService]
CLI --> Serilog
CLI[CLI Commands] --> Parsing[Parsing]
CLI --> LocalIngestion[LocalIngestion]
CLI --> Publishing[Publishing]
CLI --> Exporting[Exporting]
CLI --> Admin[Administration]
PS --> SS[ScenarioService]
PS --> QP[QfodParser]
PS --> PP[PlossParser]
PS --> DBM[WctMinerDbContext]
PS --> Serilog
LocalIngestion --> Parsing
LocalIngestion --> LocalData[LocalData]
Publishing --> LocalData
Publishing --> ReleaseData[ReleaseData]
Exporting --> LocalData
Exporting --> ReleaseData
Admin --> LocalData
SS --> DS[DimensionService]
SS --> FNP[FileNameParser]
SS --> DBM
LocalData --> Domain[Domain Models]
ReleaseData --> Domain
Parsing --> Domain
DS --> DBM
QP --> Serilog
PP --> Serilog
FNP --> Serilog
DBM --> Models[Models]
DBM --> Configs[Configurations]
subgraph Parser Layer
QP
PP
FNP
subgraph Application
Parsing
LocalIngestion
Publishing
Exporting
Admin
end
subgraph Data Layer
DBM
Models
Configs
subgraph Domain
Domain
end
subgraph Infrastructure
Serilog
LocalData
ReleaseData
Configuration
Security
Extensions
end
subgraph Service Layer
PS
SS
DS
end
```
---
## 5. 目录结构
```
src/Gpulse.WCT.DataAnalyzer/
├── Parsers/
│ ├── IParser.cs
│ ├── QfodParser.cs
│ ├── PlossParser.cs
│ ├── FileNameParser.cs # 解析文件名获取场景信息（Parser Layer）
│ └── LogFileReader.cs # 读取日志文件（可选）
├── Models/
│ ├── TxPanel.cs # TX面板维度
│ ├── TxHardware.cs # TX硬件版本维度
│ ├── TxSoftware.cs # TX软件版本维度
│ ├── RxType.cs # RX类型维度
│ ├── TestScenario.cs # 测试场景
│ ├── QfodRecord.cs # Qfod记录
│ └── PlossRecord.cs # Ploss记录
├── Data/
│ ├── WctMinerDbContext.cs
│ ├── IDbContextFactory.cs
│ └── Configurations/ # IEntityTypeConfiguration 配置类
│ ├── TxPanelConfiguration.cs
│ ├── TxHardwareConfiguration.cs
│ ├── TxSoftwareConfiguration.cs
│ ├── RxTypeConfiguration.cs
│ ├── TestScenarioConfiguration.cs
│ ├── QfodRecordConfiguration.cs
│ └── PlossRecordConfiguration.cs
├── Services/
│ ├── ParseService.cs # 解析流程协调
│ ├── ScenarioService.cs # 场景创建/查询
│ ├── DimensionService.cs # 维度表管理
│ └── ThresholdCalculator.cs # 阈值计算
├── Configuration/
│ ├── AppSettings.cs
│ └── appsettings.json
├── Commands/
│ ├── ParseCommand.cs
│ ├── StatsCommand.cs
│ ├── ExportCommand.cs
│ └── CleanCommand.cs
└── Program.cs
```