cmshoppe/docs/tasks/T-699.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-699	锁定 NumPy 1.26.4 兼容 PySide6	7	T-521 T-540	DONE	2026-07-23

问题 / 背景

Python 3.10 环境中的 NumPy 曾被其他依赖升级到 2.2.6，而当前 PySide6/Shiboken 6.5.3 包含按 NumPy 1.x ABI 编译的模块。启动 GUI 时因此出现二进制兼容警告，存在导入失败或崩溃风险。

本地降级只能修复当前机器；如果项目依赖没有明确约束，换机安装、重新打包或安装其他依赖时仍可能再次升级到 NumPy 2.x。

方案

• 在根目录 requirements.txt 精确锁定 numpy==1.26.4。
• requirements-build.txt 继续通过 -r requirements.txt 继承该约束，不重复维护第二份版本。
• 在技术栈和打包文档说明该依赖属于 PySide6/Shiboken 6.5.3 的 ABI 兼容约束。
• 增加纯逻辑回归测试，确保依赖文件只保留一条精确的 NumPy 版本约束。

验收要点

• requirements.txt 包含且仅包含 numpy==1.26.4。
• Python 3.10 环境可正常导入 NumPy、Shiboken6 和 PySide6，不再出现 NumPy 2.x ABI 警告。
• pip check 不报告依赖冲突。
• 自动验证：
  • py -3.10 -m unittest tests.test_dependency_constraints
  • py -3.10 -m unittest discover -s tests
  • py -3.10 -m ruff check app tests main.py
  • py -3.10 -m compileall app main.py
  • git diff --check

边界（不改什么）

• 不引入或恢复 OpenCV，不修改图片处理实现。
• 不升级 PySide6/Shiboken，不调整 GUI、CDP、采集、生成或更新蝦皮流程。
• 不修改用户数据、数据库 schema 或打包目录结构。

执行记录

• 2026-07-23：在 requirements.txt 增加 numpy==1.26.4 精确约束；requirements-build.txt 继续继承运行时依赖，不重复维护版本。
• 技术栈和打包文档已明确该版本用于兼容 PySide6/Shiboken 6.5.3，禁止打包环境被其他依赖隐式升级到 NumPy 2.x。
• 新增依赖约束回归测试，确保 requirements.txt 中只保留一条 numpy==1.26.4。
• Python 3.10 环境验证通过：NumPy 1.26.4、PySide6 6.5.3 和 Shiboken6 可正常导入，pip check 未发现依赖冲突。
• 验证通过：定向测试 1 项、py -3.10 -m unittest discover -s tests（684 项）、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。