更新：1、新增数据记录功能，将过程数据录入数据库；

2、增加输入点迹数据、凝聚后点迹数据记录； Signed-off-by: waiwaylee <waiwaylee@foxmail.com>
2026-09-30 09:02:28 +08:00
parent ff9b111d34
commit a4f32e4036
111 changed files with 321343 additions and 262 deletions
@@ -63,6 +63,7 @@
 - **航迹生命周期管理**：外推轮数计数、超时消亡、手动删除、全清空（含各模块 reset，防重连后幽灵航迹）。
 - **防御性加固**：见 archived_docs/BUG_FIX_REPORT.md——越界防护、时间戳正序校验、方位角 ±π 环绕、asin 定义域钳位、IMM 概率奇异保护等已修复项。
 - **日志文件输出**：`RDP_LOG_ENABLE` 定义时，首次 `Data_Process_Factory::GetB()` 自动用 `rdbuf()` 将 `std::cout` 重定向到 `RDP_LOG_DIR`（`.\rdp_logs\`）下按日期+时间命名的日志文件，`Destroy()` 时恢复控制台并关闭文件；`RDP_LOG` 日志宏在每条日志前附加 `[时间戳][文件:行号]`。该宏在 `parameters.h` 中**当前为注释状态（默认不启用）**，即默认不做重定向、日志输出到控制台（见 10.1）。
+- **数据记录调试功能（可选编译）**：`rdp_record` 模块把结构体按「一个记录实体一张表」写入 SQLite（一次运行一个 db 文件、多张表），结构体到表的映射由内置的 ormpp（`third_party/ormpp`，含 iguana、frozen 与 SQLite 3.49.1 amalgamation）完成；由 CMake 选项 `RDP_DATA_RECORD`（`AUTO`/`ON`/`OFF`）控制，**AUTO 时 Debug 构建启用、Release（交付）构建完全不编译**——记录模块源码不参与编译、`RDP_RECORD`/`RDP_RECORD_BATCH` 宏展开为 `((void)0)`（实参不求值），DLL 不新增依赖与导出符号、无性能损失。启用时 `GetB()` 建目录并开库（`.\rdp_records\rdp_record_YYYYMMDD_HHMMSS.db`），首次写入某实体时自动 `CREATE TABLE IF NOT EXISTS`，同步写入、失败降级（不抛出、不影响雷达处理）。当前内置 2 个示例记录点（TWS 输入点迹 → `RdpRecPointTws`；输出航迹 → `RdpRecTrackOut`），新增记录数据只需「加结构体 + 注册 + 一行记录点」，详见 docs/data_record_debug.md（见 4.3、10.1、11.3）。

 ---

@@ -73,13 +74,14 @@
 ├── CMakeLists.txt                       # CMake 构建脚本（扫描模式切换、导出宏、输出目录）
 ├── CHANGELOG.md                         # 变更日志（Keep a Changelog 格式，按 git 提交记录维护）
 ├── README.md                            # 本文件：项目说明（架构、接口、流程、算法、参数）
-├── requirements.md                      # 需求说明：日志文件输出功能修改要求（含 rdbuf() 重定向参考示例；原在 archived_docs/，现置于仓库根目录）
+├── requirements.md                      # 需求说明：数据记录调试功能修改要求（结构体经 ormpp 写入 SQLite、Release 可屏蔽、数据分类入不同表、宏记录点；原日志文件输出需求已实现）
 ├── archived_docs/                       # 过期文档留档（仅作历史参考；接口与流程以本 README 与 docs/ 专项说明为准）
 │   ├── BUG_REPORT.md                    # 全量逻辑 BUG 分析报告（P0~P3，37 项）
 │   └── BUG_FIX_REPORT.md                # BUG 修复报告（修复明细 + 编译验证结果）
 ├── docs/                                # 专项说明文档（按当前源码整理，与 README 互补）
 │   ├── data_process_flow_report.md      # 数据处理流程与关键逻辑说明（前处理/判圈、凝聚、关联与滤波、起始、外推消亡、TAS 波束、参数脉络）
-│   └── track_init_readme.md             # 航迹起始（Track Init）详细逻辑说明（阶段流程、条件汇总、输出字段映射、风险点、代码索引）
+│   ├── track_init_readme.md             # 航迹起始（Track Init）详细逻辑说明（阶段流程、条件汇总、输出字段映射、风险点、代码索引）
+│   └── data_record_debug.md             # 数据记录调试功能说明（开关与构建、运行期行为、表结构约定、新增记录点四步配方、示例记录点、查询示例）
 ├── design_docs/                         # 设计与讨论资料留档（被 .gitignore 忽略、不入库；含设计讨论、产品介绍与 README/流程报告的导出、渲染版本）
 ├── .vscode/                             # VS Code 工程配置
 │   ├── settings.json                    # cmake.generator=NMake、MSVC2022 x64 环境变量、compile_commands
@@ -94,11 +96,15 @@
 │   └── data_process_class_dll/
 │       ├── data_process_class_dll.pro   # 迁移前的 Qt/qmake 工程文件（备份）
 │       └── data_process_class_dll.pro.user
+├── third_party/                         # 内置第三方源码（按上游原样保存，来源/版本/升级方式见其 UPSTREAM.md）
+│   └── ormpp/                           # ormpp 0.2.0 + iguana 1.0.5 + frozen + SQLite 3.49.1 amalgamation（Apache-2.0 / 公有领域）
 ├── data_process_class_dll/              # 源码目录
 │   ├── data_process_class_dll.h         # 对外接口：DataRev/Track/TrackingBeam/RadarPara 结构体、抽象基类、工厂类
 │   ├── data_process_class_dll_global.h  # DLL 导入导出宏
 │   ├── data_process_class_dll.cpp       # 工厂实现（GetB/Destroy 单例）
 │   ├── rdp_log.h / .cpp                 # 日志输出模块：rdbuf() 重定向 std::cout、RDP_LOG 宏（开关宏在 parameters.h）
+│   ├── rdp_record.h / .cpp              # 数据记录调试模块：结构体→SQLite 表（内置 ormpp）、RDP_RECORD/RDP_RECORD_BATCH 宏、按实体自动建表、失败降级（开关由 CMake 选项 RDP_DATA_RECORD 控制；实现以 C++20 独立编译）
+│   ├── rdp_record_entity.h              # 记录实体（=数据表）定义区：新增需要记录的数据在此加结构体并写 RDP_RECORD_DECLARE
 │   ├── data_process.h / .cpp            # Data_Process 实现：接口分发、TWS/TAS 主流程、参数管理、清空/删除/转跟踪
 │   ├── struct.h                         # 内部结构体：PointRecv / Trust_Track / Temp_track / Tracking_Target
 │   ├── parameters.h                     # 编译期宏参数（按 MECHANICAL_SCANNING / PHASE_SCANNING 分两组）
@@ -121,6 +127,7 @@
 │   ├── X256_MS/                         # 机扫构建目录
 │   └── output/                          # 早期打包导出（其中 data_process_class_dll.h 为旧版 32 位时间戳接口，勿作为当前 API 依据）
 ├── rdp_logs/                            # 日志输出目录（运行时自动创建于宿主进程当前工作目录下，被 .gitignore 忽略）
+├── rdp_records/                         # 数据记录库输出目录（运行时自动创建于宿主进程当前工作目录下，被 .gitignore 忽略；仅记录功能启用时产生）
 └── .gitignore
 ```

@@ -138,6 +145,7 @@
 | CMake | ≥ 3.21（VS2022 生成器自 3.21 起支持；本工程实际在 CMake 4.x 上验证） |
 | 生成器 | NMake Makefiles（VS Code 配置与脚本均使用该生成器） |
 | 线性代数 | 无需安装——Eigen 头文件已内置在源码目录 |
+| 数据记录（可选调试功能） | 无需安装——ormpp / iguana / frozen / SQLite amalgamation 已内置在 `third_party/ormpp`（版本与升级方式见该目录 UPSTREAM.md）；启用时记录模块以 C++20 独立编译，所需的 C 编译器由同一 VS 2022 工具集提供 |

 ### 4.2 扫描体制

@@ -167,6 +175,18 @@ cmake --build build/X256_PS

 configure.bat 会在构建目录中写入 `.msvc_toolset` 标记；若该目录是用其它工具集（例如旧的 MSVC 2013 缓存）配置的，脚本会先整体删除该目录再重新配置，避免新旧目标文件混链。用 `set VS2022_DIR=...`、`set MSVC_TOOLSET_VERSION=...`、`set MSVC_TARGET_ARCH=x86` 可覆盖默认的 VS 安装路径、工具集版本与目标架构。

+数据记录调试功能由缓存变量 `RDP_DATA_RECORD` 控制，`configure.bat` 的第 4 个参数即该变量（取值 `AUTO`/`ON`/`OFF`，缺省 `AUTO`）：
+
+```bat
+:: AUTO（默认）：Debug 构建启用、Release 构建关闭——交付构建不做任何记录
+.vscode\scripts\configure.bat build/X256_PS PHASE_SCANNING Debug AUTO
+:: 显式关闭（Release 交付推荐）或显式开启（临时在 Release 中排查）
+.vscode\scripts\configure.bat build/X256_PS PHASE_SCANNING Release OFF
+.vscode\scripts\configure.bat build/X256_PS PHASE_SCANNING Debug ON
+```
+
+启用时配置阶段打印 `数据记录调试功能：启用（C++20 静态库 rdp_record + 内置 SQLite）`，并额外构建静态库 `rdp_record`（记录模块 + SQLite，链接进 DLL）；关闭时打印 `...：关闭（不编译记录模块，RDP_RECORD 为空操作）`，记录模块源码完全不参与编译。开关语义、表结构约定与新增记录点配方见 docs/data_record_debug.md。
+
 在 VS Code 中可直接运行任务（tasks.json）：「CMake: 配置并构建 X256_PS (Release)」等，默认任务为 X256_PS Release。

 ### 4.4 产物
@@ -177,6 +197,7 @@ configure.bat 会在构建目录中写入 `.msvc_toolset` 标记；若该目录
 | 导入库 data_process_class_dll.lib | build/<X256_XX>/lib/ |
 | 安装（cmake --install） | DLL/导入库 → bin、lib，公开头文件 → include |
 | compile_commands.json | 构建根目录（供 VS Code IntelliSense 使用） |
+| rdp_record.lib（仅记录功能启用时） | build/<X256_XX>/lib/ —— 记录模块静态库（含 SQLite），已链接进 DLL，**无需随 DLL 分发** |

 产物为 **x64（AMD64）** 目标。宿主程序必须是 64 位、且使用与本 DLL 同一版本头文件重新编译——MSVC 2013 → MSVC 2022 同时伴随 x86 → x64 的 ABI 变化，旧的 32 位宿主无法加载该 DLL。

@@ -190,6 +211,7 @@ configure.bat 会在构建目录中写入 `.msvc_toolset` 标记；若该目录
 - MSVC 2022 在 `/W3` 下新增报出的 C4267（`size_t` → `int` 窄化）共 17 处已按同一约定修复（`track_asso.cpp`、`track_asso_tas.cpp`、`track_init.cpp`、`track_init_direct_tracking.cpp`、`tas_ctrl.cpp` 中改为 `static_cast<int>(...)`），同样不改变计算逻辑。
 - 当前四种配置（X256_PS / X256_MS × Release / Debug）均以 **0 warning、0 error** 通过编译。
 - cl.exe 的诊断信息为中文（跟随 VS 安装语言，`VSLANG=1033` 对 VS2022 的 cl.exe 无效），构建日志中偶见 `注意: 包含文件:` 行泄漏，属 CMake 依赖扫描的显示噪声，头文件依赖（`CMakeFiles/*.dir/**/*.obj.d`）记录完整，不影响增量编译。
+- **第三方库告警例外（仅记录功能启用时）**：数据记录模块的第三方依赖按上游原样内置在 `third_party/ormpp`（保留上游字节，含换行符，不转 BOM/编码），其中 `third_party/ormpp/thirdparty/sqlite3/sqlite3.c` 以源文件级 `/w` 单独编译，`data_process_class_dll/rdp_record.cpp` 用 `#pragma warning(push, 0)` / `(pop)` 包裹第三方头；除此之外本工程源码仍按上一条的 `/W3` 零告警标准编译（X256_PS/X256_MS × Release/Debug 四种配置实测 0 warning、0 error）。

 ### 4.6 编译器升级说明（MSVC 2013 → MSVC 2022）

@@ -291,6 +313,7 @@ classDiagram
 | kalman | 两点/三点滤波初始化、线性卡尔曼预测/滤波、EKF（3 维量测含多普勒）、马氏统计距离 d、盲速 Bind_speed |
 | coor_trans | 极坐标 ↔ 直角坐标转换 |
 | rdp_log（rdp_log.h/.cpp） | 日志输出：按 parameters.h 的 `RDP_LOG_ENABLE` 开关，在 `Init()` 中用 `rdbuf()` 将 `std::cout` 重定向到日期+时间命名的日志文件、`Shutdown()` 恢复控制台并关闭；提供 `RDP_LOG` 宏自动附加 `[时间戳][文件:行号]` 前缀 |
+| rdp_record（rdp_record.h/.cpp、rdp_record_entity.h） | 数据记录调试（可选编译）：由 CMake 选项 `RDP_DATA_RECORD` 决定是否参与编译；开启时把「记录实体」（结构体）经内置 ormpp 映射写入 SQLite 表（一实体一表，首次写入自动 `CREATE TABLE IF NOT EXISTS`，一次运行一个 db 文件），`RDP_RECORD`/`RDP_RECORD_BATCH` 记录点宏在关闭时展开为空操作；`Init()`/`Shutdown()` 由工厂的 `GetB()`/`Destroy()` 调用；建表/插入失败一律降级（每个实体只提示一次），不影响雷达处理 |
 | Track_Init_Direct_Tracking / Track_Asso_Direct_Tracking | 引导跟踪（direct tracking）专用起批/关联。**当前入口为空实现、未启用**；track_asso_direct_tracking.cpp 未加入 CMake 源列表 |

 ---
@@ -857,6 +880,8 @@ $$
 |---|---|---|---|
 | RDP_LOG_ENABLE | 注释停用（默认不启用） | 同左 | 日志文件输出开关：定义时将 `std::cout` 重定向到日志文件；**当前源码中该宏为注释状态**（parameters.h 的注释文字仍写「定义（默认）」，以代码实际状态为准），不重定向、日志输出到标准输出/控制台 |
 | RDP_LOG_DIR | `.\rdp_logs\` | 同左 | 日志文件输出目录（相对宿主进程当前工作目录，目录不存在时自动创建） |
+| RDP_RECORD_ENABLE | 由 CMake 选项 `RDP_DATA_RECORD` 定义（AUTO 时 Debug 定义） | 同左 | 数据记录调试开关：**不要在 parameters.h 中手工定义**（由构建系统传入）；定义时记录模块参与编译，未定义时 `RDP_RECORD`/`RDP_RECORD_BATCH` 展开为空操作，见 4.3 与 11.3 |
+| RDP_RECORD_DB_DIR | `.\rdp_records\` | 同左 | 数据记录库输出目录（相对宿主进程当前工作目录，目录不存在时自动创建；仅记录功能启用时产生） |
 | DATA_RATE_TAS | 已停用（原 0.3） | 已停用（原 0.0625） | 编译期宏已注释停用；TAS 数据率统一由运行时参数 RadarPara.DATA_RATE_TAS 提供（见 10.2） |
 | SIGMA_R / SIGMA_A / SIGMA_E / SIGMA_V | 10.0 / 0.02 / 0.2 / 2.0（两体制相同） | 同左 | 量测误差：距离 m / 方位 rad / 俯仰 rad / 速度 m/s |
 | DOT_COH_RANGE / DOT_COH_V / DOT_COH_AZI | 80 / 2 / 6 | 同左 | 凝聚门限：距离 m / 速度 m/s / 方位 ° |
@@ -934,6 +959,7 @@ $$
 - TAS **自动**开启/退出逻辑（tas_auto_start/tas_auto_end）注释停用，仅支持手动 tracking_start/tracking_stop。
 - RadarPara 中的起批/关联波门字段未被实现读取（见 10.2）。
 - build/output/ 下为早期打包导出物，其 data_process_class_dll.h 时间戳仍为 32 位 int，与当前 64 位接口不一致，勿作为对接依据。
+- **数据记录调试功能默认只在 Debug 启用**：CMake 选项 `RDP_DATA_RECORD` 的 AUTO 默认值为「Debug 启用、Release 关闭」，交付/Release 构建下记录模块（`rdp_record.cpp`、`sqlite3.c`）不参与编译、`RDP_RECORD` 为空操作（导出符号与依赖均无变化）；如需在 Release 构建中临时排查可显式 `-DRDP_DATA_RECORD=ON`，但正式交付应保持 AUTO/OFF（见 docs/data_record_debug.md）。记录点中的字段错误只在启用记录功能的构建中才会被检查（关闭时宏丢弃实参）。

 ### 11.4 航迹起始相关的未修复观察（详见 docs/track_init_readme.md 第 15 节）

@@ -953,6 +979,7 @@ $$

 | 提交 | 内容 |
 |---|---|
+| 工作区（未提交，数据记录调试功能） | 新增可选编译的数据记录调试功能：CMake 缓存变量 `RDP_DATA_RECORD`（AUTO/ON/OFF，AUTO = Debug 启用 / Release 关闭）与独立静态库 `rdp_record`（**以 C++20 编译**，雷达代码保持 C++17）；内置第三方源码 `third_party/ormpp`（ormpp 0.2.0 + iguana 1.0.5 + frozen + SQLite 3.49.1 amalgamation，附 UPSTREAM.md）；新增 `rdp_record.h`（`Init`/`Shutdown`/`db_path` + `RDP_RECORD`/`RDP_RECORD_BATCH` 宏，关闭时展开为空操作）、`rdp_record_entity.h`（记录实体定义区）与 `rdp_record.cpp`（实体注册区、按实体自动建表、单条/批量写入、失败降级）；`Data_Process_Factory::GetB()/Destroy()` 调用 `rdp_record::Init()/Shutdown()`；`parameters.h` 新增 `RDP_RECORD_DB_DIR`（`.\rdp_records\`）；`data_process.cpp` 新增 2 个示例记录点（TWS 输入点迹 → `RdpRecPointTws`、输出航迹 → `RdpRecTrackOut`）；`configure.bat` 新增第 4 个参数（AUTO/ON/OFF）；`.gitignore` 增加 `rdp_records/`；新增 `docs/data_record_debug.md`。验证：Release（PS/MS）导出表与依赖表与改动前逐行一致、DLL 体积不变（178,688 / 178,176 字节）、构建树无记录模块目标文件；Debug（PS/MS，AUTO→启用）0 warning 0 error；运行时校验（临时程序 + Python sqlite3）确认建库、一实体一表、批量事务写入、`id` 自增、取值一致、`integrity_check` = ok，且记录目录不可创建时接口照常返回、仅提示一次 |
 | 工作区（未提交） | 编译器由 MSVC 2013（Visual Studio 12，x86）升级为 **MSVC 2022（v143，x64）**、C++ 标准提升至 **C++17**：`CMakeLists.txt` 重写（`CMAKE_CXX_STANDARD 17`、`_MSC_VER >= 1930` 强校验、`/utf-8` `/Zc:__cplusplus` `/W3`）、`.vscode/scripts/` 全部构建脚本改为 MSVC 2022（新增共享的 `msvc_env.bat`，`configure.bat` 自动清理旧工具集构建树）、VS Code 配置同步（settings / c_cpp_properties / cmake-variants / tasks 改为 MSVC2022 x64 + C++17）、修复 MSVC 2022 新增的 17 处 C4267 窄化告警；X256_PS/X256_MS × Release/Debug 四种配置均 0 warning 0 error 通过，产物为 x64 DLL（导出符号与升级前一致，仅名称修饰随架构变化） |
 | e8c56f9 | 输入/输出结构适配「归一化幅度」与「速度维 FFT 点数」：`DataRev` 新增 `amp_asv`/`prn_fftn`，`Track` 新增 `amp_asv_point`/`prn_fftn_point`，内部 `PointRecv`/`Trust_Track` 同步新增字段；`track_asso.cpp` 关联实点时写入航迹、TWS 输出时写回输出结构（输入侧未打通，见 11.2） |
 | 42b598e | 调整「向站/背站」判断条件：判据由 `acos((-x·vx − y·vy)/r/Range_V) < π/4` 改为 `acos((-x·cos(Direction_Angle) − y·sin(Direction_Angle))/r) < π/2`（去掉按合速度归一化，锥角门限由 45° 放宽到 90°），TWS/TAS 同步 |
@@ -994,9 +1021,11 @@ $$
 | CHANGELOG.md | 变更日志（Keep a Changelog 格式，按 git 提交记录维护） |
 | docs/data_process_flow_report.md | 数据处理流程与关键逻辑说明（按当前源码整理：前处理与判圈、凝聚、TWS/TAS 关联与滤波、航迹起始、外推消亡、TAS 波束控制、参数脉络；含与本文档的历史差异提示）——原同内容 HTML 渲染版（`data_process_flow_report.html`）已于 e0bf227 删除，HTML 版本在 git 忽略的 `design_docs/` 内留档 |
 | docs/track_init_readme.md | 航迹起始（Track Init）专项说明：分阶段流程、起始条件汇总、调参直觉、输出字段映射（含未赋值字段）、已知风险与代码索引 |
+| docs/data_record_debug.md | 数据记录调试功能说明：开关与构建（`RDP_DATA_RECORD`、C++20 隔离与 C 编译器要求）、运行期行为（目录/文件名、PRAGMA、失败降级、线程模型）、表结构约定、**新增记录点四步配方**、现有 2 个示例记录点、查询示例与已知限制 |
+| third_party/ormpp/UPSTREAM.md | 内置第三方源码的来源说明：ormpp / iguana / frozen / SQLite 版本、许可证、复现与升级步骤（含 blob 校验值） |
 | archived_docs/BUG_REPORT.md | 全量逻辑 BUG 分析（P0~P3 共 37 项，含位置、说明、建议、处置结论）——过期留档，仅作历史参考 |
 | archived_docs/BUG_FIX_REPORT.md | 修复明细、修复状态汇总表与 MSVC 2013 x86 编译验证记录——过期留档（对应 01d28e0 时期） |
-| requirements.md | 修改需求说明：日志文件输出功能（rdbuf() 重定向、parameters.h 日志开关宏、日期+时间命名日志、前缀日志宏，附参考示例）——已实现，现置于仓库根目录（原在 archived_docs/ 留档） |
+| requirements.md | 修改需求说明：数据记录调试功能（结构体经 ormpp 映射写入 SQLite、Release 版可屏蔽、数据分类入不同表、宏记录点、便于快速新增结构体、不使用异步写入）——已按该说明实现框架与 2 个示例记录点，详见 docs/data_record_debug.md（此前同名的日志文件输出需求亦已实现） |
 | backup/data_process_class_dll/data_process_class_dll.pro | 迁移前的 Qt/qmake 工程文件（源文件清单参考） |
 | .vscode/tasks.json、.vscode/cmake-variants.yaml | VS Code 构建任务与变体定义 |
 | build/X256_PS/bin/RadarConfigParam.ini | 回放测试工具（rdp_playback.exe）配置样例 |