chore: pin NumPy 1.26.4

docs/03-tech-stack.md

@@ -81,7 +81,8 @@ set AUTO=1 && python prototypes/demo.py
 - 运行时第三方依赖统一写入根目录 `requirements.txt` 并锁定版本；换机或 CI 使用 `python -m pip install -r requirements.txt` 安装。
 - 开发检查依赖写入 `requirements-dev.txt`；当前只包含 ruff，不属于运行时或打包依赖。
 - 打包依赖只写入 `requirements-build.txt`；PyInstaller 不属于运行时依赖，不写进 `requirements.txt`。
-- 当前直接依赖锁定：PySide6 6.5.3、openpyxl 3.1.3、requests 2.31.0、websocket-client 1.6.1、Pillow 9.5.0。
+- 当前直接依赖锁定：PySide6 6.5.3、NumPy 1.26.4、openpyxl 3.1.3、requests 2.31.0、websocket-client 1.6.1、Pillow 9.5.0。
+- NumPy 1.26.4 是 PySide6/Shiboken 6.5.3 的二进制兼容约束。项目目前不直接调用 NumPy API，但不得让其他依赖把运行或打包环境升级到 NumPy 2.x，否则可能在 GUI 启动导入阶段触发 ABI 不兼容错误。
 - 新增第三方依赖前，先在本文说明用途、替代方案和维护成本，并同步更新 `requirements.txt`。
 - GUI 框架固定为 PySide6，不允许混入 Tkinter/PyQt/Web 形成两套 UI。
 - 不引入第二套浏览器自动化方案（不要 `app/cdp.py` 之外再混入 selenium/playwright）。

docs/packaging.md

@@ -13,7 +13,7 @@
 py -3.10 -m pip install -r requirements-build.txt
 ```
 
-`requirements-build.txt` 会先安装 `requirements.txt` 的运行依赖，再安装 PyInstaller。依赖必须安装到 Python 3.10 环境里，避免 PATH 上的 Python 3.7/3.12/3.14 打出不可比对的包。
+`requirements-build.txt` 会先安装 `requirements.txt` 的运行依赖，再安装 PyInstaller。依赖必须安装到 Python 3.10 环境里，避免 PATH 上的 Python 3.7/3.12/3.14 打出不可比对的包。运行依赖固定使用 NumPy 1.26.4，以兼容 PySide6/Shiboken 6.5.3；正式打包前不得单独升级到 NumPy 2.x。
 
 ## 二、打包命令
 

docs/tasks/T-699.md

@@ -0,0 +1,47 @@
+---
+id: T-699
+title: 锁定 NumPy 1.26.4 兼容 PySide6
+phase: 7
+deps: [T-521, T-540]
+status: DONE
+created: 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`。

requirements.txt

@@ -1,5 +1,6 @@
 PySide6==6.5.3
+numpy==1.26.4
 openpyxl==3.1.3
 requests==2.31.0
 websocket-client==1.6.1
-Pillow==9.5.0
+Pillow==9.5.0

tests/test_dependency_constraints.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+import unittest
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+class DependencyConstraintsTest(unittest.TestCase):
+    def test_numpy_is_pinned_to_compatible_version(self) -> None:
+        requirements = (PROJECT_ROOT / "requirements.txt").read_text(
+            encoding="utf-8"
+        )
+        numpy_constraints = [
+            line.strip()
+            for line in requirements.splitlines()
+            if line.strip().lower().startswith("numpy")
+        ]
+
+        self.assertEqual(["numpy==1.26.4"], numpy_constraints)
+
+
+if __name__ == "__main__":
+    unittest.main()