158 lines
6.6 KiB
Markdown
158 lines
6.6 KiB
Markdown
# `macro_split` 重构为可安装包 `macro_lactone_toolkit` 的实施计划
|
||
|
||
## Summary
|
||
|
||
采用“渐进式重构，不推倒重写”的方案：保留仓库里已经可用的 12-20 元环识别、通用编号、侧链 BFS 提取和 dummy 原子思路，删除或降级 16 元环专用路径，把核心能力统一收敛到一个正式可安装、可测试、可 CLI 调用的包。
|
||
|
||
本次重构完成后，项目要满足这几个结果：
|
||
- 可以作为正式 Python 包安装和导入，主包名为 `macro_lactone_toolkit`
|
||
- 默认自动识别 12-20 元有效大环内酯；也允许显式传 `ring_size`
|
||
- 支持环编号和侧链裂解
|
||
- 裂解结果同时提供“带位置编号 dummy”与“普通 `*` dummy”两套 SMILES，且都能被 RDKit 读取保存
|
||
- 用 `pixi` 管理环境和测试
|
||
- 先执行 `git pull --ff-only` 同步远端，再开始任何代码改动
|
||
|
||
## Key Changes
|
||
|
||
### 1. 仓库与包结构正规化
|
||
|
||
- 第一动作不是改代码，而是在仓库根目录执行：
|
||
- `git status --short`
|
||
- `git pull --ff-only`
|
||
- 将当前直接放在顶层 `src/` 下的运行时代码，改成标准包布局：`src/macro_lactone_toolkit/`
|
||
- 不保留 `src.*` 兼容层；README、测试、脚本、入口点全部切到新导入路径
|
||
- `pyproject.toml` 改为标准 setuptools `src` layout 配置，修正：
|
||
- 包发现
|
||
- 项目名与版本元数据
|
||
- console scripts
|
||
- pytest 配置
|
||
- `pixi.toml` 统一为 Python 3.12，并支持至少：
|
||
- `osx-arm64`
|
||
- `linux-64`
|
||
- `pixi.toml` 补齐测试依赖和常用任务：
|
||
- `test`
|
||
- `lint`（只做检查，不自动改写文件）
|
||
- `smoke-import`
|
||
- README 中所有 `from src...` 示例全部替换为 `from macro_lactone_toolkit...`
|
||
|
||
### 2. 统一核心领域模型与 API
|
||
|
||
以 `ring_visualization.py` 的通用逻辑和参考脚本的编号思路为基础，重构出清晰边界的核心模块，避免“16 元环专用”和“12-20 元环通用”并存。
|
||
|
||
公开 API 统一为：
|
||
|
||
- `macro_lactone_toolkit.MacroLactoneAnalyzer`
|
||
- `macro_lactone_toolkit.MacrolactoneFragmenter`
|
||
- `macro_lactone_toolkit.RingNumberingResult`
|
||
- `macro_lactone_toolkit.SideChainFragment`
|
||
- `macro_lactone_toolkit.FragmentationResult`
|
||
|
||
行为约定固定如下：
|
||
|
||
- `MacroLactoneAnalyzer`
|
||
- 负责识别 12-20 元环
|
||
- 验证环上是否存在有效内酯酯键
|
||
- 返回所有命中的有效环尺寸
|
||
- `MacrolactoneFragmenter`
|
||
- 默认自动识别有效环尺寸
|
||
- 若检测到 0 个有效环，抛出明确异常
|
||
- 若检测到多个有效环尺寸，默认抛出“歧义异常”，要求调用者显式传 `ring_size`
|
||
- 若调用者传了 `ring_size`，则只处理该环
|
||
- `RingNumberingResult`
|
||
- 至少包含：`ring_size`、`ring_atoms`、`ordered_atoms`、`carbonyl_carbon_idx`、`ester_oxygen_idx`、`atom_to_position`、`position_to_atom`
|
||
- `SideChainFragment`
|
||
- 至少包含：`parent_id`、`cleavage_position`、`attachment_atom_idx`、`fragment_smiles_labeled`、`fragment_smiles_plain`、`atom_count`、`molecular_weight`
|
||
- `FragmentationResult`
|
||
- 至少包含：母分子信息、选定环尺寸、编号结果、所有碎片、错误/警告信息
|
||
|
||
异常策略固定为：
|
||
|
||
- `MacrolactoneError`
|
||
- `MacrolactoneDetectionError`
|
||
- `AmbiguousMacrolactoneError`
|
||
- `RingNumberingError`
|
||
- `FragmentationError`
|
||
|
||
### 3. 编号与裂解算法收敛
|
||
|
||
编号逻辑以“通用 12-20 元环”作为唯一正式实现，不再让旧的 16 元环 `ring_numbering.py` 充当主入口。
|
||
|
||
- 编号规则固定：
|
||
- 位置 1 = 环上的内酯羰基碳
|
||
- 位置 2 = 环上的酯键氧
|
||
- 位置 3-N = 沿确定方向依次编号剩余环原子
|
||
- 编号实现使用统一入口，不能再出现批处理脚本内部偷偷调用 `[r16]` 专用函数的情况
|
||
- 自动识别时，先找所有 12-20 元环，再验证该环是否为有效大环内酯
|
||
- 侧链识别统一用“环原子邻居中不在环内的原子即侧链起点”
|
||
- 侧链提取统一用 BFS，只沿非环原子扩展
|
||
- dummy 原子输出固定两套：
|
||
- `fragment_smiles_labeled`：带位置编号 dummy，例如 `[5*]`
|
||
- `fragment_smiles_plain`：普通 `*`
|
||
- dummy 与连接原子的键型必须保留原始键型，不能强制都变成单键
|
||
- 所有裂解结果必须通过 RDKit round-trip：
|
||
- `Chem.MolFromSmiles(...)` 成功
|
||
- `Chem.MolToSmiles(...)` 可再次序列化
|
||
|
||
### 4. CLI、批处理与现有脚本归并
|
||
|
||
交付范围包含正式 CLI，不再依赖散乱脚本作为主要入口。
|
||
|
||
CLI 设计固定为 3 个命令：
|
||
|
||
- `macro-lactone-toolkit analyze`
|
||
- 输入单个 SMILES 或 CSV
|
||
- 输出有效环尺寸、是否歧义、选中的环尺寸
|
||
- `macro-lactone-toolkit number`
|
||
- 输入单个 SMILES
|
||
- 输出编号结果 JSON
|
||
- `macro-lactone-toolkit fragment`
|
||
- 输入单个 SMILES 或 CSV
|
||
- 输出碎片 JSON/CSV，包含 labeled/plain 两套 SMILES
|
||
|
||
批处理行为固定为：
|
||
|
||
- CSV 默认读取 `smiles` 列
|
||
- 可选 `id` 列；未提供则自动生成
|
||
- 自动识别歧义分子时：
|
||
- 默认跳过并记录错误
|
||
- 显式传 `--ring-size` 时按指定环处理
|
||
- 旧 `scripts/` 中保留价值的逻辑迁入正式 CLI；剩余脚本改成薄封装或标记为 legacy，不再承担核心实现
|
||
|
||
## Test Plan
|
||
|
||
必须用 `pixi` 跑完整验证，至少覆盖下面这些场景：
|
||
|
||
- 包安装与导入
|
||
- `pixi run python -c "import macro_lactone_toolkit"`
|
||
- `pixi run pytest`
|
||
- 环识别
|
||
- 单一有效环尺寸的 12、14、16、20 元环样例
|
||
- 无效分子
|
||
- 无内酯键分子
|
||
- 多有效环尺寸分子，确认抛出 `AmbiguousMacrolactoneError`
|
||
- 编号
|
||
- 位置 1 必须是羰基碳
|
||
- 位置 2 必须是酯键氧
|
||
- 编号范围必须连续覆盖 `1..N`
|
||
- 同一分子多次运行结果一致
|
||
- 裂解
|
||
- 无侧链位置返回空列表
|
||
- 有侧链位置返回碎片
|
||
- `fragment_smiles_labeled` 与 `fragment_smiles_plain` 都能被 RDKit 成功读取
|
||
- labeled dummy 保留位置号
|
||
- dummy 键型与原键型一致
|
||
- CLI
|
||
- `analyze`、`number`、`fragment` 的基本 smoke test
|
||
- CSV 批处理
|
||
- 歧义分子跳过与错误日志行为
|
||
- 回归
|
||
- 现有 splicing engine 若继续保留，至少保留一个 dummy 拼接回组装测试，确保 labeled dummy 方案可持续扩展
|
||
|
||
## Assumptions
|
||
|
||
- `git pull` 使用 `--ff-only`，避免在重构开始前引入不透明 merge commit
|
||
- 本次不保留 `src.*` 导入兼容层，全面切换到 `macro_lactone_toolkit`
|
||
- 本次把“正式库 API + 正式 CLI + pixi 测试”作为主交付；notebooks 只做参考，不作为正式接口
|
||
- 发现多个有效大环尺寸时，默认视为歧义并失败，不自动猜测
|
||
- 继续使用 RDKit 作为唯一结构解析与序列化基础
|