From c204fc205cbdb9ecc0c4556b35ebdcb8e6c0cedb Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Wed, 24 Jun 2026 17:48:35 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E8=BF=90=E8=A1=8C=E6=96=B9=E5=BC=8F?=
 =?UTF-8?q?=E6=94=B9=E5=9B=9E=E8=84=9A=E6=9C=AC=E5=B9=B6=E8=87=AA=E6=B3=A8?=
 =?UTF-8?q?=E5=85=A5=E9=A1=B9=E7=9B=AE=E6=A0=B9=EF=BC=8C=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=20Windows=20No=20module=20named=20'src'?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 现象：Windows(Python 3.7) python -m src.main 报 No module named 'src'，
  即便 cwd 在项目根、src/__init__.py 存在。
- 根因：该环境运行时不把当前目录加入 sys.path，python -m 找不到 cwd 下的 src 包。
- 修复：
  - src/main.py 启动时自注入项目根到 sys.path，不依赖运行环境配置；
  - 运行方式从 python -m src.main 改回脚本方式 python src/main.py；
  - dev.bat 恢复 CRLF 行尾并改用 python src\main.py；
  - 00/03/05/current-state 文档命令同步。

验证：WSL 下从不含 src 的目录脚本方式运行 exit=0；unittest 17 passed。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 dev.bat                  |  8 +++++---
 docs/00-ai-start-here.md |  2 +-
 docs/03-tech-stack.md    |  4 ++--
 docs/05-coding-rules.md  |  2 +-
 docs/current-state.md    |  2 +-
 progress.md              |  8 ++++++++
 src/main.py              | 14 ++++++++++++--
 7 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/dev.bat b/dev.bat
index 9a53e79..6a2600b 100644
--- a/dev.bat
+++ b/dev.bat
@@ -1,3 +1,5 @@
-title run
-cd /d "%~dp0" && python -m src.main
-pause
+@echo off
+pushd "%~dp0"
+python src\main.py
+pause
+popd
diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md
index 6ef93bd..363df0f 100644
--- a/docs/00-ai-start-here.md
+++ b/docs/00-ai-start-here.md
@@ -115,7 +115,7 @@ MVP 不做：
 ```powershell
 python -m compileall src
 python -m unittest discover -s tests -t .
-python -m src.main
+python src/main.py
 ```
 
 说明：
diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md
index 3e73f30..a3e235f 100644
--- a/docs/03-tech-stack.md
+++ b/docs/03-tech-stack.md
@@ -38,7 +38,7 @@
 | 创建虚拟环境 | `python -m venv .venv` |
 | 激活虚拟环境 | `.venv\Scripts\Activate.ps1` |
 | 安装依赖 | `pip install -r requirements.txt` |
-| 本地运行 | `python -m src.main` |
+| 本地运行 | `python src/main.py` |
 | 测试 | `python -m unittest discover -s tests -t .` |
 | 语法检查 | `python -m compileall src` |
 | 打包（待 T-402） | `pyinstaller app.spec` |
@@ -49,7 +49,7 @@ Windows PowerShell：
 python -m venv .venv
 .venv\Scripts\Activate.ps1
 pip install -r requirements.txt
-python -m src.main
+python src/main.py
 python -m unittest discover -s tests -t .
 ```
 
diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md
index 72fa9e9..54ec67c 100644
--- a/docs/05-coding-rules.md
+++ b/docs/05-coding-rules.md
@@ -78,7 +78,7 @@
 ```powershell
 python -m compileall src
 python -m unittest discover -s tests -t .
-python -m src.main
+python src/main.py
 ```
 
 ## 8. 绝不
diff --git a/docs/current-state.md b/docs/current-state.md
index d718942..62e7f20 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -39,7 +39,7 @@
 
 ```powershell
 # 本地运行入口
-python -m src.main
+python src/main.py
 
 # 测试
 python -m unittest discover -s tests -t .
diff --git a/progress.md b/progress.md
index b404aab..ff8abbf 100644
--- a/progress.md
+++ b/progress.md
@@ -75,6 +75,14 @@
 - 安全：日志格式不含敏感字段，并在 `logging_config`/`05` 留下「不记录支付密码/验证码/账号密码」约定。
 - 验证：`python3 -m compileall src` OK；`python3 -m unittest discover -s tests -t .` → Ran 17 tests, OK；`python3 -m src.main` exit=0 且 `logs/app.log` 正常写入。
 
+### 2026-06-24 · 修复 Windows 运行方式（No module named 'src'）
+
+- 现象：Windows（Python 3.7）下 `python -m src.main` 报 `ModuleNotFoundError: No module named 'src'`，即使 cwd 在项目根、`src/__init__.py` 存在。
+- 根因：该环境运行时未把当前目录加入 `sys.path`，`python -m` 找不到 cwd 下的 `src` 包（`os.listdir` 能看到文件属文件系统层，import 靠 `sys.path`）。
+- 修复：`src/main.py` 启动时自注入项目根到 `sys.path`；运行方式从 `python -m src.main` 改回脚本方式 `python src/main.py`（脚本目录可定位，配合自注入不依赖 cwd/环境）；同步 `dev.bat`（恢复 CRLF + `python src\main.py`）与 `00/03/05/current-state` 文档命令。
+- 教训：Windows 脚本保持 CRLF；运行方式以目标机实测为准，不臆断 `python -m` 可用。
+- 验证：WSL 下从不含 `src` 的目录脚本方式运行 exit=0、unittest 17 passed；Windows 由用户实测确认。
+
 ## 阻塞与风险
 
 - 真实 Excel 表头待提供。
diff --git a/src/main.py b/src/main.py
index 4ac46dc..bdb921d 100644
--- a/src/main.py
+++ b/src/main.py
@@ -5,8 +5,18 @@ T-001 骨架阶段的最小可运行入口，仅用于验证项目结构与运
 """
 from __future__ import annotations
 
-from src.logging_config import get_task_logger, setup_logging
-from src.paths import ensure_runtime_dirs
+import sys
+from pathlib import Path
+
+# 以 `python src/main.py` 脚本方式运行时，sys.path[0] 是 src/ 而非项目根；
+# 且部分 Python 环境的 `python -m`/默认 sys.path 不包含当前目录。
+# 这里显式把项目根加入搜索路径，确保 `from src.*` 始终可用、不依赖运行环境配置。
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+from src.logging_config import get_task_logger, setup_logging  # noqa: E402
+from src.paths import ensure_runtime_dirs  # noqa: E402
 
 APP_NAME = "拼多多批量下单执行器"
 APP_VERSION = "0.1.0"