From 10a87d2cee976a1b4a77c4a05600c031fa475ed2 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 9 Oct 2026 19:53:38 +0800 Subject: [PATCH] docs: record approved PDF exporter design and implementation plan --- .gitattributes | 5 +++ .gitignore | 17 ++++++++ .../plans/2026-10-09-mentor-pdf-export.md | 40 +++++++++++++++++++ .../2026-10-09-mentor-pdf-export-design.md | 24 +++++++++++ 4 files changed, 86 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 docs/superpowers/plans/2026-10-09-mentor-pdf-export.md create mode 100644 docs/superpowers/specs/2026-10-09-mentor-pdf-export-design.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..898b8d7 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +* text=auto +*.py text eol=lf +*.md text eol=lf +*.json text eol=lf +*.cmd text eol=crlf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dc09333 --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +/.venv/ +/build/ +/dist/ +/release/ +/runs/ +/output/ +/artifacts/ +/.pytest_cache/ +/.coverage +__pycache__/ +*.py[cod] +*.egg-info/ +*.doc +*.docx +*.prj +*.pdf +*.zip diff --git a/docs/superpowers/plans/2026-10-09-mentor-pdf-export.md b/docs/superpowers/plans/2026-10-09-mentor-pdf-export.md new file mode 100644 index 0000000..0b0cd5d --- /dev/null +++ b/docs/superpowers/plans/2026-10-09-mentor-pdf-export.md @@ -0,0 +1,40 @@ +# Mentor PDF Exporter Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking. + +**Goal:** Deliver a portable Windows test tool with simple UI and evidence-backed native PDF export. +**Architecture:** Isolated project copy -> deterministic native profile -> sequential sch2pdf subprocess -> PDF validation -> atomic output. Qt worker never modifies the UI directly. +**Tech Stack:** Python 3.12, PySide6 6.x, pypdf, pytest/pytest-qt, PyInstaller, local Mentor EE 7.9.5. +**Spec:** docs/superpowers/specs/2026-10-09-mentor-pdf-export-design.md + +## Global Constraints +- No source Mentor project/config modification; export from copy only. +- Windows / Python 3.12 / PySide6 6.x / native Mentor EE 7.9.5. +- Git feature branch in fresh requested directory; no unrequested worktree. +- Runs, private source docs, source CAD projects, output PDFs and releases excluded from Git. +- No overwrite without explicit opt-in; no parallel Mentor export. + +### Task 1: Native feasibility and safe core +Files: tests/test_scanner.py, tests/test_profiles.py, tests/test_workspace.py, src/mentor_pdf_export/{models,scanner,profiles,workspace,engine}.py, tools/live_smoke.py. +Interfaces: scan_projects(root, excluded_roots=()) -> list[ProjectInfo]; ExportOptions; prepare_workspace(project, run_dir, options) -> Path; build_command(engine, project, output, options) -> list[str]. +- [ ] Write failing tests for recursive discovery/pruning, profile values and safe isolated workspace. +- [ ] Run pytest and confirm intended import/behavior failures. +- [ ] Implement core, rerun tests until passing. +- [ ] Export the local PON example ONLY from a copied workspace; retain logs and compare source hashes. +- [ ] Investigate config/ICT/font behavior and record actual evidence/limits. + +### Task 2: Reliable export transaction +Files: tests/test_exporter.py, tests/test_engine.py, src/mentor_pdf_export/{exporter,validation}.py. +Interfaces: Exporter.export(ProjectInfo, output_root, ExportOptions, cancel_event, event_callback) -> ExportResult; discover_engine(explicit=None) -> Path. +- [ ] Write failing tests for valid/invalid PDF, old output preservation, source changes, timeout/cancel and duplicate names. +- [ ] Run red, implement, then run green. +- [ ] Include isolated output staging, JSON run report and retained stdout/stderr. + +### Task 3: Simple UI and portable release +Files: tests/test_ui.py, src/mentor_pdf_export/{ui,__main__,cli}.py, packaging/mentor_pdf.spec, README.md, Start-MentorPDF.cmd. +Interfaces: MainWindow(root=None, output=None); CLI --self-check/--export/--ui-smoke. +- [ ] Write failing Qt tests: scan checkbox state, settings locking, background signals, cancel, result display. +- [ ] Implement minimal usable UI; run Qt tests and capture window PNG. +- [ ] Run real UI batch on sample copy, render native PDF and check pages/text/colors visually. +- [ ] Build PyInstaller onedir and ZIP; execute packaged --self-check and UI smoke. +- [ ] Run full tests, review diff and document release limitations/evidence. diff --git a/docs/superpowers/specs/2026-10-09-mentor-pdf-export-design.md b/docs/superpowers/specs/2026-10-09-mentor-pdf-export-design.md new file mode 100644 index 0000000..a9e72d0 --- /dev/null +++ b/docs/superpowers/specs/2026-10-09-mentor-pdf-export-design.md @@ -0,0 +1,24 @@ +# Mentor 批量 PDF 导出测试版设计 + +## 已批准的目标 +Windows 上独立简易 UI,扫描多个 DxDesigner 工程、勾选队列、统一配置、串行调用原生 sch2pdf,验证结果并打包便携测试版。先以工程副本做真实验证,再进行 UI 测试。 + +## 平台与边界 +Python 3.12,PySide6 6.x,本机 Mentor EE 7.9.5;需要有效许可证和工程依赖。不是脱离 Mentor 的 PDF 转换器。源码在当前新工程目录,Git 使用 feature 分支,不创建未经请求的 worktree。工程操作仅在独立副本中,源工程不保存、不改配置、不关闭用户 CAD。所有运行数据和 PDF 不入 Git。 + +## 实现结构 +scanner.py 识别 FrontEndSnapshot=DxD/iCDBDir,完整递归且剪枝 PCB/备份/输出,拒绝链接与路径越界。 +models.py 定义 ExportOptions/ProjectInfo/ExportResult。profiles.py 写副本 dxpdf.ini,生成已验证命令参数。 +workspace.py 在运行目录复制原理图工程,排除 PCB/备份/日志,不复制链接;检查 iCDBDir 的相对、内部约束;保存源内容指纹,前后核验。 +engine.py 发现引擎/运行子进程/超时取消/日志。exporter.py 单任务串联、输出临时文件、PDF 校验后原子提交、JSON 结果与可重试状态。 +ui.py PySide6 工程表、配置栏、后台串行任务、日志、停止、结果打开。批量任务禁止重复启动,执行期间配置与工程选择锁定。 + +## 默认配置 +白底彩色文字 Color=4,AddPopup=1,VisibleHLs=0,UrlProperties 空,StartAcrobat=0,ChangeIct2Sch=1,LineThickness=1,StrokeThickness=1,UseExclusion=1(跟截图),UseDxDMapping=1。不擅改字体成新字体;现有字体映射保持。掩盖文字效果待样张核验。 +导出范围默认整工程;可选明确原理图名称。Stop At=STD。引擎未验证的 ICT 参数需实测,不能宣称完成。现有 PDF 默认不覆盖。 + +## 输出安全 +单工程工作副本;生成到独立 staging 输出;解析 PDF、检查页数和内容资源后才发布。失败/取消/超时不发布。旧输出只有显式勾选覆盖后才能替换。输出不允许进入工程数据库或工作副本。源文件指纹异常标记待人工核验,不报告成功。 + +## 验收 +自动测试覆盖扫描、配置、复制路径安全、错误处理、输出冲突、取消超时、PDF 校验、UI 按钮与后台任务。真实副本导出记录参数、配置、日志、页数与源工程前后指纹,并渲染检查。UI 做 offscreen 行为测试及真实窗口截图。打包后 exe 至少做自检和 UI 启动,不以源码运行替代 exe 验收。