SystemSimulationApp/docs/standard/跨平台交付约定.md

Windows 与 Linux 功能交付约定

2026-09-12 用户明确要求：后续功能补全同时注意 Windows 平台适配。

Windows x64 与 Linux x86_64 都是当前应用的使用平台。涉及文件系统、缓存、编译器、进程、动态库、环境安装或启动脚本的功能修改，应同时检查两侧的实现和测试入口。

• 文件系统可选能力应按运行环境检测，例如 os.supports_follow_symlinks，不能因为 Linux 接受某个参数就假设 Windows 也接受。缓存目录仍需验证普通目录、符号链接与 Windows reparse point；权限和真实 I/O 错误不能当成兼容问题随意吞掉。
• 编译与运行应覆盖 Windows 的 .exe、导入库/DLL、工具链路径、带空格路径和换行行为。进程锁、并发清理、异常退出应有可在 Windows 执行的测试。
• 平台专用的小型测试夹具可以明确限定平台，但不能代替跨平台集成测试。Windows CI 中必需的工具链缺失应失败，不能以整组跳过得到成功结论。
• 交付记录分别列出兼容代码、模拟测试、实际 Windows 测试的状态。只有实际 Windows 运行通过，才能声称 Windows 验收通过。缺少 Windows 环境时继续完成可做的修复和测试准备，并明确实机验证仍待完成。
• 本地虚拟环境、编译器、便携运行时和构建缓存保留在 Git 忽略目录，不随源码提交。

当前缓存检查入口：

$env:SIMULATION_NATIVE_REQUIRE_TOOLCHAIN = '1'
.\.venv-win\Scripts\python.exe -m unittest tests.test_native_cache_storage tests.test_native_cache_platform -v

该入口使用现有 SIMULATION_NATIVE_CC / SUNDIALS_ROOT 或构建器的默认探测；CI 配置在 .github/workflows/solver-regression.yml 的 native-windows 作业。