147 lines
6.1 KiB
Markdown
Executable File
147 lines
6.1 KiB
Markdown
Executable File
# PPI ID 修订代码收敛设计
|
||
|
||
日期：2026-07-10
|
||
|
||
## 目标
|
||
|
||
在不丢失已经生效的 PPI ID 功能、不增加新功能的前提下，收敛本轮修订产生的代码和测试复杂度，使生产执行路径易读、可维护、可用真实 Ft→soe 数据验证。
|
||
|
||
本轮要保留的用户价值只有：
|
||
|
||
1. 目标 canonical ID 始终保留，不被参考物种或 STRING ID 替换。
|
||
2. 保留 canonical ID → Ortholog reference ID 的逐关系证据。
|
||
3. 使用参考注释包中的 accession、NCBI GeneID 等本地证据完成 STRING ID 映射。
|
||
4. 输出 STRING `preferredName` 和完整 ID 对照表。
|
||
5. 区分“STRING 正常返回空网络”和“HTTP/JSON/API 请求失败”。
|
||
|
||
## 当前基线
|
||
|
||
只读盘点显示：
|
||
|
||
- `skills/ppi/run.py`：Task 3 前 574 行，当前约 1301 行，净增加约 690 行。
|
||
- 新增 `gfa_core/id_resolution.py`：约 396 行。
|
||
- 新增 `gfa_core/string_rate_gate.py`：约 163 行。
|
||
- `tests/unit/test_ppi_id_resolution.py`：约 1523 行。
|
||
- `tests/unit/test_id_resolution.py`：约 281 行。
|
||
|
||
这些数字用于发现复杂度，不作为机械删代码指标。任何收敛都必须以功能等价和真实数据验证为前提。
|
||
|
||
## 约束
|
||
|
||
### 必须保留
|
||
|
||
- 已由生产路径实际调用、并直接支持上述五项用户价值的行为。
|
||
- 已经生效的空网络与 API 失败分类。
|
||
- 已经生效的 ID provenance 和 preferred name 输出。
|
||
- 当前确实参与生产请求的基本超时、请求节流和错误处理。
|
||
- 参考包 `ncbi_gene_id` 字段以及共享本地别名读取能力。
|
||
|
||
### 不得发生
|
||
|
||
- 不整体回滚 PPI 修订。
|
||
- 不永久删除本轮已有实现或测试；移出活跃路径的内容必须先归档。
|
||
- 不增加 Reset、CLI 新参数、Manifest 新结构、前端新展示或新的 STRING 协议能力。
|
||
- 不为单一调用点创建新的通用框架、插件层、配置层或额外兼容层。
|
||
- 不因为追求行数而改坏已经通过的科学语义。
|
||
|
||
## 归档策略
|
||
|
||
修改前，将本轮相关文件完整复制到：
|
||
|
||
`项目记录/代码归档/2026-07-10_PPI_ID修订收敛前快照/`
|
||
|
||
归档至少包含：
|
||
|
||
- `skills/ppi/run.py`
|
||
- `gfa_core/id_resolution.py`
|
||
- `gfa_core/string_rate_gate.py`
|
||
- `gfa_core/ppi_string_policy.py`
|
||
- `apps/web/pipeline_backend.py` 的完整快照
|
||
- 三个相关单元测试文件
|
||
- 当前测试命令、结果和代码行数记录
|
||
|
||
活跃文件中不保留数百行被注释代码。确认不参与生产路径的实现进入归档，原位置只保留必要的简短说明。
|
||
|
||
## 收敛方法
|
||
|
||
### 1. 建立可信基线
|
||
|
||
当前会话曾在修改过程中被中断，因此不得直接假设磁盘状态仍是最后一次绿色状态。
|
||
|
||
先运行现有聚焦测试、后端相关测试和静态检查。若当前状态不绿，只处理被中断的局部修改，使其回到可验证基线；不得借此增加新功能。
|
||
|
||
### 2. 标记真实生产路径
|
||
|
||
以 CodeGraph 和直接调用检查确认唯一活跃流程：
|
||
|
||
`pipeline_backend → skills/ppi/run.py → 本地 ID map → STRING mapping → STRING network → resolution/network artifacts`
|
||
|
||
每个保留的类、函数和字段必须至少满足一项：
|
||
|
||
- 位于这条生产调用链；
|
||
- 直接生成用户需要的 ID/provenance 产物；
|
||
- 是保证现有请求成功、空网络分类或错误分类所必需的最小逻辑。
|
||
|
||
### 3. 简化而不改变行为
|
||
|
||
- 合并只在一个位置使用的薄封装。
|
||
- 合并重复的字符串、taxon、候选 ID 转换。
|
||
- 减少只为中间状态存在的数据对象；保留最终逐关系结果结构。
|
||
- 删除活跃路径中已经确认无调用的兼容分支，但在归档中保存原实现。
|
||
- 保留共享别名模块边界，但把单用途证据对象和重复索引压缩为最小实现。
|
||
- 保留请求节流能力；若现有实现能在更少代码下保持相同并发行为，允许等价重写，否则原样保留。
|
||
|
||
每次重写必须先有等价测试，不能一次性重写整个 PPI 文件。
|
||
|
||
### 4. 测试收敛
|
||
|
||
活跃测试重点保留约 15–25 个行为场景：
|
||
|
||
- canonical/Ortholog 逐关系保留；
|
||
- exact accession 与 versionless accession；
|
||
- GeneID fallback；
|
||
- 收敛与歧义；
|
||
- 部分映射和零映射；
|
||
- 24 条关系、12 个查询的真实形状；
|
||
- preferredName 输出；
|
||
- 空网络成功；
|
||
- HTTP/JSON 失败；
|
||
- 生产路径确实使用解析后的 STRING ID；
|
||
- 参考包 numeric GeneID 不覆盖 LOC gene ID；
|
||
- 一个节流/并发核心测试。
|
||
|
||
重复验证同一内部实现、只覆盖极端伪造协议响应的测试移入归档。核心测试必须面向行为，不绑定可以被简化的内部类和私有方法。
|
||
|
||
## 验证
|
||
|
||
### 分步验证
|
||
|
||
1. 收敛前基线：记录测试结果、行数和生产调用路径。
|
||
2. 每个小改动：运行相关最小测试集合。
|
||
3. 收敛完成：运行 PPI/ID/backend 聚焦回归和 Python 静态检查。
|
||
4. 真实数据：使用现有 Ft→soe 项目数据执行 PPI ID 解析和网络阶段。
|
||
|
||
### 真实数据验收
|
||
|
||
真实 Ft→soe 结果必须证明：
|
||
|
||
- canonical target ID 数量和原输入一致；
|
||
- 每条 Ortholog relationship 都保留 exact reference accession；
|
||
- raw accession 和 GeneID fallback 均能在对照表中解释；
|
||
- 输出包含 STRING ID 和 `preferredName`；
|
||
- 网络为 0 条时，如果 API 正常返回空列表，阶段仍为成功且标记 empty network；
|
||
- API 故障不能伪装成 0 interactions；
|
||
- 不依赖测试 fake 得出最终结论。
|
||
|
||
如果当前环境无法访问 STRING，必须如实报告，并至少完成真实本地 ID map 与请求前 selected STRING ID 验证；不得声称完成在线网络验证。
|
||
|
||
## 完成标准
|
||
|
||
- 已生成可恢复的收敛前归档。
|
||
- 活跃生产路径没有确认无调用的兼容分支或重复实现。
|
||
- 活跃测试聚焦用户行为，重复/极端内部测试已归档。
|
||
- 所有保留功能通过收敛前后对比验证。
|
||
- 完成真实 Ft→soe 验证或明确记录唯一外部阻塞。
|
||
- 最终报告给出：归档位置、修改文件、收敛前后行数、测试结果、真实数据结果和未验证风险。
|
||
- 不以达到某个行数为完成条件，但不得再出现与一个 PPI ID 功能不成比例的新增框架。
|