# GDEFN V1.0 开发过程记录

## 1. 记录目的

本文档记录 GDEFN 研究代码软件化过程中的需求、设计决策、功能落地、风险处理和验证证据。本记录只描述当前项目文件可以支持的事实，不猜测作者、工时、权属或早于当前版本的具体日期。

## 2. 项目基线

| 项目 | 内容 |
| --- | --- |
| 软件名称 | GDEFN 生物关联智能预测与分析系统 |
| 简称 | GDEFN |
| 版本 | V1.0 |
| 软件化目录 | `research_software/` |
| 复用的原始核心 | `main.py`、`models.py`、`utils.py`、`datasets/`、`logs/` |
| 运行形态 | 本地 Flask 服务 + 浏览器单页界面 |
| 记录日期 | 2026-08-23 |

## 3. 初始资产审计

软件化开始时，可识别的原始资产包括：

- `main.py`：GDEFN 五折主实验与泛化实验入口。
- `models.py`：图卷积、视图注意力、MLP 编码器、CrossModalGate、UFE 与分类器。
- `utils.py`：数据加载、特征图/结构图构建、度感知加删边、超图和扩散特征。
- `datasets/mi-m`：7,611 个节点、900 维特征和五折划分。
- `datasets/dti`：2,664 个节点、500 维特征和五折划分。
- `logs/`：已有训练日志，包含五折和六指标文本，但日志不等于模型权重。

资产审计还确认了三项必须在软件中直接披露的边界：

1. 划分文件中的节点索引按 0 基使用。
2. 原始发布矩阵没有随附可直接使用的全量实体名称映射表；因此后续名称恢复必须逐项建立可复验证据链。
3. DTI 第 2 折和第 5 折存在训练/测试交叉风险，第 2 折还有训练索引重复。

## 4. 需求形成

### 4.1 功能需求

| 编号 | 需求 | 实现状态 |
| --- | --- | --- |
| FR-01 | 展示软件、模型和数据集概况 | 已实现 |
| FR-02 | 按数据集、折次和节点索引预测 | 已实现 |
| FR-03 | 对 CSV/TSV/TXT 同维特征文件批量预测 | 已实现，仅快速基线 |
| FR-04 | 在指定测试折上现场评估 | 已实现，仅快速基线 |
| FR-05 | 在有依赖与检查点时运行完整 GDEFN 推理 | 已实现条件检查与推理通道 |
| FR-06 | 从界面启动原始五折训练，将每折最优检查点写入不可变运行目录，并仅在五折全成功后原子发布活动清单 | 已实现 |
| FR-07 | 审计数据形状、重复、交叉与越界 | 已实现 |
| FR-08 | 解析原始日志并展示历史论文指标 | 已实现 |
| FR-09 | 保存每次软件运行来源，并导出结果 | 已实现 |
| FR-10 | 提供科研风格的本地可视化界面 | 已实现 |
| FR-11 | 按数据集、折次和 0 基中心节点交互浏览原始结构局部图，并导出 SVG | 已实现 |
| FR-12 | 选择数据集与 Fold 后直接预测完整测试集并下载统一关系格式 | 已实现 |
| FR-13 | 展示 `hsa-miR-139-5p` 10 个靶基因和 `BACH1` 6 个调控 miRNA 的真实名称案例 | 已实现 |
| FR-14 | 为 DTI 2,664 条关系提供药物、DrugBank、蛋白和 UniProt 映射 | 已实现 |
| FR-15 | 按全部数据文件展示特征、标签、划分、结构边、近邻图和证据快照 | 已实现 |
| FR-16 | 按实际代码展示 GCN、MLP、UFE 并行分支及门控融合架构 | 已实现 |

### 4.2 非功能需求

- 路径便携：整个项目移动后不需要修改硬编码盘符。
- 本地安全：默认只绑定回环地址，接口不缓存，上传有大小与格式限制。
- 可追溯：每次结果保留引擎、数据集、折次、阈值与时间。
- 不误导：快速基线、历史论文指标和检查点推理必须明确分离。
- 数据完整性：审计结果只读，原始划分不被默默改写。

## 5. 核心设计决策

### 5.1 决策 D-01：建立双引擎而不伪造论文权重

**问题：** 历史日志可以提供论文指标，但并不包含可推理的权重；普通计算机也可能缺少 PyTorch/PyG。

**决策：** 提供一个仅需 NumPy 的 Diagonal LDA 作为快速基线，同时保留完整 GDEFN 检查点推理通道。每条结果写入 `provenance`；完整模型统一使用 `gdefn-checkpoint`，当其不可用时明确报错，不自动用基线结果替换。

### 5.2 决策 D-02：外部特征只进入快速基线

**问题：** GDEFN 依赖整图及多个派生视图，不能对独立一行特征进行等价推理。

**决策：** 文件上传接口只调用 Diagonal LDA，页面与返回结果都标明方法范围。如日后支持新实体，必须设计图接入和重新训练流程，不可只改界面标签。

### 5.3 决策 D-03：保留原始划分并显式报告泄漏

**问题：** DTI 原始划分中有重复和训练/测试交叉。直接删除会改变论文复现口径，不删除又存在指标偏乐观的风险。

**决策：** 实现只读质量报告，保留原始文件用于复现，同时在页面、手册、设计书和测试报告披露第 2 折节点 623、第 5 折节点 28 的交叉以及第 2 折的 1 项训练重复。清洗后实验如开展，必须使用新的版本化划分和独立结果名称。

### 5.4 决策 D-04：不伪造实体名称

**问题：** 原始数值矩阵没有随附可直接使用的全量节点—实体映射，错误猜测会污染科研结论。

**决策：** 真实名称只用于有证据的记录，同时保留全部原始索引。mi-m 通过论文 Table 6/7、案例重构记录和标准矩阵来源行建立 16 条精确回连；其余显示原始 0 基关系索引。DTI 使用固定上游提交的药物/蛋白嵌入字典，对 100D 与 400D 特征块按八位小数逐行唯一匹配，形成 2,664 条可复现映射。所有名称保留来源、状态和内部记录号，绝不由数值相似度猜测。

### 5.5 决策 D-05：所有路径便携化

**问题：** 硬编码开发机绝对路径会导致复制、归档和软著演示环境不可用。

**决策：** `config.py` 从自身 `__file__` 定位 `research_software` 与项目根；`main.py` 和 `utils.py` 从脚本目录定位数据、日志和检查点。对外元数据不显示绝对路径。文档使用 `<完整代码>` 占位符说明启动，而非依赖某一盘符。

### 5.6 决策 D-06：检查点不可变归档与五折原子发布

**问题：** 如果每折直接覆盖“当前检查点”，训练中断或某折失败会让推理端看到新旧运行混合的五折，破坏可复现性和原子性。

**决策：** 每次训练在 `checkpoints/<dataset>/runs/<run_id>/` 中生成不可变的五折 `.pt` 和对应 `.json` 元数据。每个文件通过“临时文件 + `os.replace`”发布。仅当同一运行的五折全部完成时，才原子替换 `checkpoints/<dataset>/active_manifest.json`。主动停止、崩溃或部分失败不会切换已激活模型；如无旧清单，完整引擎保持不可用。

推理端校验活动清单的格式、模型名、数据集和目录边界，再校验每折侧车元数据与检查点内部的 `dataset`、`fold`、`num_features`、`num_classes`、`format_version` 和 `state_dict`。权重仅使用 PyTorch `weights_only=True` 安全加载，并将 SHA-256 记入推理结果。

### 5.7 决策 D-07：图网络浏览与模型推理解耦

**问题：** 科研人员需要查看局部拓扑，但原始结构边、模型预测边和力导向布局容易在截图中被混为一谈；同时完整图较大，不适合一次性在浏览器绘制。

**决策：** 新增只读 `GraphVisualizationService`，按所选折次读取原始结构边，以内部中心记录号和排序邻接表执行确定性 BFS，返回有限规模的局部诱导子图。反向/重复边规范为唯一无向边，节点度保留完整折图口径；前端负责 SVG 力导向排布和交互。默认页面另提供真实名称案例关系图，标准图通过 `EntityService` 叠加可验证名称。两类图均明确来源，不把原始结构边或历史案例快照冒充成一次新的 GDEFN 推理。

## 6. 实施阶段记录

| 阶段 | 实施内容 | 产出/代码证据 |
| --- | --- | --- |
| A. 资产检查 | 核对原始模型、数据形状、折次、日志与依赖 | `README.md`、`main.py`、`models.py`、`utils.py`、`datasets/` |
| B. 应用配置 | 定义软件元数据、数据集元数据和便携路径 | `research_software/config.py` |
| C. 数据层 | 实现懒加载、标签标准化、折次索引、概况和质量审计 | `DataRepository` |
| D. 快速预测 | 实现 Diagonal LDA、缓存、节点/文件预测、指标与 ROC | `BaselinePredictionService`、`binary_metrics`、`parse_feature_upload` |
| E. 完整模型 | 实现依赖/安全加载/活动清单/元数据可用性检查、检查点内部强校验、SHA-256 溯源和 GDEFN 整图推理 | `predictor.py` 完整模型服务 |
| F. 训练集成 | 实现参数校验、独立进程、任务快照、日志与停止；原始训练入口实现不可变运行目录与五折活动清单原子发布 | `training.py`、`main.py` |
| G. 日志与溯源 | 解析原始日志，生成运行编号，保存 JSONL 并导出 CSV | `research_log.py`、`app.py` |
| H. 图网络可视化 | 实现原始图严格解析、LRU 缓存、确定性 BFS、诱导子图 API、SVG 力导向交互与导出 | `graph_service.py`、`app.py`、`research_software/web/` |
| I. 前端交互 | 建立科研总览、预测、图网络、评估、训练、质检、记录、架构与关于页 | `research_software/web/` |
| J. 文档与验证 | 编写设计、使用、软著、过程和测试文档，执行只读功能验证 | `research_software/docs/`、测试命令记录 |
| K. 实名关系层 | 固化 16 条 mi-m 论文案例，构建 DTI 2,664 条可复现实体映射，提供模板导入与来源优先级 | `entity_service.py`、`data/case_studies.json`、`data/dti_entity_pairs.csv` |
| L. 测试集与可视化升级 | 增加整折直接预测、案例预测、关系式 CSV、真实名称网络、全文件图谱和交互式 GDEFN 架构图 | `app.py`、`web/`、`docs/06_真实名称测试集与可视化升级说明.md` |

## 7. 实现细节记录

### 7.1 Diagonal LDA

- 使用选定折的原始训练索引。
- 分别计算正负类的均值与方差。
- 以池化对角方差代替完整协方差，降低高维反演成本。
- 根据非零方差中位数添加小正则项，最小方差被截断到 `1e-8`。
- 将线性得分截断到 [-30, 30] 后经 Sigmoid 转换，减少浮点溢出。
- 记录拟合样本数、训练正类比例和绝对权重最大的 12 个特征。

### 7.2 DTI 验证划分

DTI 无独立 `val*.txt`。原始 `load_data` 使用 `RandomState` 兼容的固定随机划分，对第 1–5 折分别采用与 `42 + fold_index` 等价的种子，将 2,000 个原始训练位置分成 1,600/400。软件质检与完整模型按同一划分逻辑解释验证归属。

快速基线有意使用原始 `train*.txt` 全部位置，因此其拟合数与原始 GDEFN 每折实际训练位置数不同。这一差异已被纳入文档，并作为不混用指标的原因之一。

### 7.3 图网络可视化

- 标签、划分和原始边文件按严格 UTF-8/整数格式只读解析，节点端点必须位于数据集的 0 基范围内。
- 邻接表使用集合去重并冻结为有序元组，确定性 BFS 对相同参数返回相同节点集合；响应边是所选节点之间的完整诱导边。
- 节点 `degree` 是完整折图的唯一邻居数，响应同时提供节点/边数量、标签与划分计数、平均度、最大度、孤立节点数和是否截断。
- 进程级线程安全 LRU 默认只保留有限个不可变折图包；并发首次请求只构建一次，响应每次重新生成，调用方不能修改共享缓存。
- 前端使用原生 SVG 绘制，支持按标签/划分/度着色、拖拽节点、平移缩放、属性检查和 SVG 导出；布局坐标不回写原始数据。

### 7.4 历史记录

预测结果以每行一个 JSON 的方式追加保存。读取时忽略个别损坏行，写入时使用进程内可重入锁保护。该设计适合单机运行，未声称支持多机分布式并发写入。

### 7.5 安全与隐私

- 服务默认绑定 `127.0.0.1`。
- 文件上传限制 20 MB，节点/样本批量限制 5,000。
- 仅支持 UTF-8 文本特征文件与白名单扩展名。
- 导出 CSV 对可能触发公式解析的文本前置单引号。
- 结构化错误不将服务器完整异常堆栈发送到页面。
- 本地历史可能包含用户上传的样本 ID，对外打包前应根据需要清理或脱敏。

## 8. 问题与风险登记

| 编号 | 问题/风险 | 影响 | 当前处理 | 后续建议 |
| --- | --- | --- | --- | --- |
| R-01 | 缺少完整模型检查点时无法按论文模型推理 | 完整引擎不可用 | 返回明确的引擎不可用错误 | 在兼容环境完成五折训练，并原子发布活动清单 |
| R-02 | 快速基线被误当作论文结果 | 科研结论误导 | 引擎选择、来源字段、页面警示和文档反复区分 | 导出图表时继续保留来源 |
| R-03 | DTI 第 2/5 折训练/测试交叉 | 评估可能偏乐观 | 只读审计并显式警告 | 新增无泄漏清洗划分作为独立实验 |
| R-04 | 第 2 折 DTI 训练索引重复 | 样本权重隐式增大 | 质检报告显示 1 项重复 | 清洗实验中去重并版本化 |
| R-05 | mi-m 缺少全量节点到实体名称映射 | 大多数标准样本不能按实体名解释 | 7,611 条均显示原始 0 基索引，16 条精确案例覆盖为实名；DTI 已全量映射 | 后续只导入有来源、有版本且冲突规则明确的 mi-m 映射 |
| R-06 | 检查点命名错配或被替换 | 可能加载错误折次/数据集 | 已实现活动清单路径边界、侧车元数据、检查点内部 `dataset`/`fold`/format/特征数/类别数强校验，以及 SHA-256 溯源 | 正式发布时可将活动清单与所有折的 SHA-256 额外纳入签名归档 |
| R-07 | 本地 JSONL 不适合多用户分布式写入 | 扩展部署时存在并发与权限风险 | 当前定位为单机本地软件 | 多用户版使用数据库、认证和审计日志 |
| R-08 | 原始数据和代码的权属/许可需单独核验 | 影响分发和软著声明 | 软著参考文档不作无证据原创声称 | 由权利人归档仓库来源、合同和许可 |
| R-09 | 新五折训练中断或部分失败 | 如直接覆盖可造成活动模型新旧折次混合 | 每次运行不可变归档，仅五折全成功后原子切换 `active_manifest.json` | 定期清理经确认不再需要的未激活部分运行，清理前保留日志 |
| R-10 | 原始划分冲突或可视化被误读为预测 | DTI 问题折次可能无法构图，截图也可能造成科研误解 | 图服务严格拒绝冲突划分；界面区分原始结构图、历史案例图与现场预测 | 对外截图保留折次、名称证据和语义说明；如需清洗图，使用独立版本化数据 |

## 9. 验证记录摘要

2026-08-23 在 Windows、Python 3.12.9 环境执行只读验证，主要证据如下：

- `app.py`、`config.py`、`graph_service.py`、`predictor.py`、`research_log.py`、`training.py` 均通过 Python `compile()` 语法编译。
- `/`、`/api/status`、`/api/model`、`/api/datasets`、`/api/graph/sample`、`/api/research/metrics`、`/api/research/experiments` 与两个数据集模板接口通过自动化合约或真实数据只读检查。
- mi-m 五折审计未发现重复、训练/测试交叉或越界索引。
- DTI 审计产生 3 条警告：第 2 折训练重复 1 项、第 2 折交叉节点 623、第 5 折交叉节点 28。
- 快速基线在 mi-m 和 DTI 各对 3 个合法节点完成预测，概率位于 [0, 1]，来源为 `baseline-diagonal-lda`。
- 负索引和错误特征列数均触发 `InputValidationError`。
- 图服务在 mi-m Fold 01 与 DTI Fold 01 完成真实数据只读抽样；DTI Fold 02/05 的冲突划分被严格拒绝，没有静默归类。
- 60 项自动化 `unittest` 全部通过，新增覆盖 7,611 条关系索引目录、分页接口、完整测试折预测、历史案例来源标识、真实名称案例网络、DTI 全量映射、映射原子导入与数据资产扫描。
- 当前验证环境未安装 PyTorch、SciPy、scikit-learn 与 PyTorch Geometric，且无活动清单所指检查点；完整引擎正确显示不可用，未冒充通过。

详细测试用例和限制见 `05_测试报告.md`。

## 10. 可追溯矩阵

| 需求 | 设计/代码 | 用户文档 | 测试证据 |
| --- | --- | --- | --- |
| 双引擎严格分离 | `predictor.py` 两个 Service + `provenance` | 手册第 5、6、9、12 节 | SMK-P01/02 与测试报告第 8 节 |
| 0 基节点索引 | `_require`/节点范围校验 | 手册第 5.4、7 节 | UT-V04、GV-03、SMK-P03 |
| 可验证实体名称与未映射披露 | `EntityService`、案例快照、DTI 映射快照 | 手册第 5、7、10 节 | 实体服务测试、API 合约与界面审查 |
| 图网络只读浏览 | `graph_service.py` + `/api/graph/sample` + SVG 前端 | 手册第 7 节 | GV-01–GV-05、API-08 与真实数据抽样 |
| DTI 划分泄漏审计 | `quality_report()` | 手册第 7.3、8、10 节 | 测试报告第 6.3、6.4 节 |
| 路径便携 | `config.py`、`SCRIPT_DIR` | 手册第 3 节 | INT-03/04 与静态路径审查 |
| 特征文件校验 | `parse_feature_upload()` | 手册第 6 节 | UT-F01–UT-F04、UT-V03 |
| 历史与 CSV 导出 | `_save_history()`、`export_history()` | 手册第 11 节 | 需在最终集成环境复测写入流程 |
| 后台训练与原子发布 | `TrainingManager` + `main.py --save-checkpoints` + `runs/<run_id>` + `active_manifest.json` | 手册第 9 节 | 路径/清单逻辑自动化测试；数值训练仍需在完整 PyTorch/PyG 环境复测 |

## 11. 版本变更记录

| 版本 | 日期 | 变更摘要 |
| --- | --- | --- |
| V1.0 | 2026-08-23 | 完成本地科研 Web 工作台、双预测引擎、原始结构图局部可视化、快速评估、五折训练集成、数据质检、日志/历史溯源、便携式路径和配套文档 |
| V1.0 实名可视化增补 | 2026-08-23 | 增加整折测试集直接预测、16 条真实名称 mi-m 案例、DTI 全量实体映射、案例关系图、全文件图谱与代码一致的交互式 GDEFN 架构图 |

## 12. 后续维护流程

1. 修改代码前，先确定变更属于软件层、原始模型层还是数据资产层。
2. 数据划分的任何修改必须新建版本，不覆盖原划分后继续引用原指标。
3. 模型架构或超参数变更后，在新 `run_id` 目录生成五折，更新 format version，并仅在兼容性验证与五折全部成功后切换活动清单；不就地覆盖旧运行。
4. 增加新实体映射时，保留映射的来源、版本、许可、时间和冲突规则。
5. 每次发布前执行语法、API、图抽样、数据质检、基线预测、前端资源/SVG 导出、便携性和安全响应头测试。
6. 仅在具备完整依赖、检查点和资源预算的环境执行完整训练/推理回归测试。
7. 同步更新设计书、手册、软著材料参考、开发记录和测试报告。