build: establish unified project entry

docs/03-tech-stack.md

@@ -59,25 +59,33 @@
 
 ## 五、构建与运行命令
 
-> 采购服务命令已由 T-001 实际验证。采购工具以下离线测试、编译和 wheel 元数据命令已由
-> Python 3.12 实际验证；桌面 GUI 和真机流程不属于 T-002 验收范围。
+> `init.ps1` 已由 T-003 在 Windows PowerShell 实际验证：它优先复用合规的既有采购工具虚拟环境
+> （本机实际为 Python 3.12）；仅在虚拟环境不存在时，才从 Python Launcher 的已安装版本中确定性选择
+> 最高的 Python 3.11+ 创建它，以 editable 方式安装采购工具，并跑两端
+> 离线门禁。桌面 GUI 和真机流程不属于该入口的验收范围。
 
 | 用途 | 采购服务（`admin/`） | 采购工具（`client/`） |
 | --- | --- | --- |
-| 安装依赖 | `go mod download` | `py -3.12 -m venv .venv` 后运行 `.\.venv\Scripts\python.exe -m pip install -e .` |
+| 安装依赖 | `go mod download` | Windows 运行 `./init.ps1`；它复用合规 venv，或选择 Python Launcher 中最高的 Python 3.11+ 创建 venv 后执行 `pip install -e .` |
 | 本地开发 | `go run ./cmd/server` | `.\.venv\Scripts\python.exe -m cmbuyer_client` |
-| 构建 | `go build ./...` | `py -3.12 -m pip wheel --no-deps . --wheel-dir <输出目录>`，再运行 `py -3.12 scripts/verify_wheel_metadata.py <wheel 路径>` |
-| 测试 | `go test ./...` | `py -3.12 -m unittest discover -s tests -t .` |
-| 静态检查 | `go vet ./...` | `py -3.12 -m compileall -q src tests scripts` |
+| 构建 | `go build ./...` | `.\.venv\Scripts\python.exe -m pip wheel --no-deps . --wheel-dir <输出目录>`，再运行 `.\.venv\Scripts\python.exe scripts/verify_wheel_metadata.py <wheel 路径>` |
+| 测试 | `go test ./...` | `.\.venv\Scripts\python.exe -m unittest discover -s tests -t .` |
+| 静态检查 | `go vet ./...` | `.\.venv\Scripts\python.exe -m compileall -q src tests scripts` |
+
+Windows 的标准入口是仓库根 `./init.ps1`。它要求 Go、两端目录及其哨兵文件存在；已有合规
+`client/.venv` 时，所有采购工具检查与 validator 都使用该解释器。只有 venv 不存在时，才从 `py -0p`
+枚举的版本中确定性选择最高的 Python 3.11+ 创建它；没有合规版本时明确失败，绝不回退默认 `python`。
+它执行 admin 的 `go mod download` / test / vet / build、client 的 editable install / 包导入 / unittest /
+compileall。既有 `client/.venv` 若不是 Python 3.11+ 会明确失败，不会自动覆盖用户环境。`init.sh` 保持等价门禁语义；WSL 或 Unix 环境缺少所需 Go、Python 3.11+
+或项目文件时必须非零退出，语法通过或 Unix 成功不构成 Windows / 真机验收。
 
 采购工具的运行时依赖只维护在 `client/requirements.txt`。`client/pyproject.toml` 通过 setuptools
 动态读取该文件生成 wheel 的 `Requires-Dist`，避免两份依赖列表漂移；
 `scripts/verify_wheel_metadata.py` 会验证生成 wheel 已声明全部这些依赖。
 
-当前 Windows 默认 `python` 指向 Python 3.10.11，不满足采购工具的 Python 3.11+ 下限，
-不得把未加版本选择器的 `python` 当作采购工具的已验证命令。T-003 负责统一入口与解释器选择；
-在此之前使用 `py -3.12` 或 Python 3.11+ 虚拟环境。Python 3.12 虚拟环境中的完整
-`pip install -e .` 已验证通过；桌面 GUI 与真机流程不属于 T-002 验收范围。
+当前 Windows 默认 `python` 仍可能指向 Python 3.10，不满足采购工具的 Python 3.11+ 下限；
+不得把未加版本选择器的 `python` 当作采购工具命令。统一入口优先使用既有合规 venv，仅在需要创建时
+自动选择 Launcher 中最高的合规版本；本机现有 venv 实际为 Python 3.12。桌面 GUI 与真机流程不属于 T-003 验收范围。
 
 Windows PowerShell 差异：
 
@@ -90,7 +98,7 @@ $env:GOTOOLCHAIN = "local"
 
 | 层级 | 触发条件 | 命令 / 操作 | 通过证据 |
 | --- | --- | --- | --- |
-| 任务相关验证 | 每个任务必跑 | 改 `admin/` 跑 `go test ./...` + `go vet ./...`；改 `client/` 跑 `py -3.12 -m unittest discover -s tests -t .` + `py -3.12 -m compileall -q src tests scripts` | 退出码 0、测试数 |
+| 任务相关验证 | 每个任务必跑 | 改 `admin/` 跑 `go test ./...` + `go vet ./...`；改 `client/` 跑 `.venv\Scripts\python.exe -m unittest discover -s tests -t .` + `.venv\Scripts\python.exe -m compileall -q src tests scripts` | 退出码 0、测试数 |
 | 完整门禁 | 发布前；修改 HTTP 契约、数据库 schema、依赖或构建配置时；跨端改动时 | 两端全部测试 + 静态检查 + 两端构建 | 退出码 0、测试数、产物路径 |
 | 人工 / 设备验收 | 任何涉及真机页面判据、下单动作或付款路径的任务 | 连接真机执行，记录设备型号、Android 版本、拼多多版本、goods_id、截图与页面 XML 路径 | 人工结论 + 证据文件路径 |