# Python Web 实训项目 · 从 0 到 1

> **该打开哪个文件夹：`File → Open` 选本文件夹（`03_practicum_labs`）**；左边黄褐色的 `.venv` 是库目录，不用管。详见 `WHICH_FOLDER.md`。
>
> **PyCharm 怎么操作：双击 `pycharm_guide.html`** —— 底部终端、跑命令、运行/停止、解释器、装包、环境变量、报错处理。
>
> **每章一节理论课**：`theory/ch01.html … ch07.html`（知识点+生活案例+代码对照+易错点）；配套实践课见各 lab 手册第五节。
>
> **整门课的总入口：双击 `index.html`** —— 一页看全部：10 个实训（手册/报告/代码/截图）+ 7 章 PPT 知识点 + 环境配置图解 + 报错实战 + 文档与课件链接。

> 一本书 = 一个主文件夹；下面 `lab01` … `lab10`，每个实训文件夹里直接放代码。
> 顺序就是上课顺序：**前一个跑通，再进下一个**。10 个实训，每个都能单独打开、单独运行、单独交作业。

## 一、打开整个项目（一次就好）

1. PyCharm → `File → Open` → 选 **本文件夹**（`03_practicum_labs`），不要选里面的子目录。
2. 若顶部出现黄条「未为项目配置 Python 解释器」→ 点右侧 **解释器设置** → `添加解释器` → `添加本地解释器` → `选择现有` → 填：
   ```
   .venv\Scripts\python.exe
   ```
   点确定。黄条消失、右下角显示 `Python 3.13 (…)` 即成功。
   （也可以关掉 PyCharm 后右键 `fix_interpreter.ps1` 自动完成这一步。）
3. 依赖已经装在 `.venv` 里，**不用再 pip install**；换机器才需要双击 `setup_env.bat`。
4. 右上角运行配置下拉框里有 10 个配置，名字形如 `lab01_flask_routing（5110）`，按顺序点绿三角。

## 二、三种启动方式

| 方式 | 怎么做 |
|---|---|
| PyCharm | 右上角配置选「labNN…（端口）」→ 点 ▶（或 `Shift+F10`） |
| 双击 | 进实训文件夹 → 双击 `run.bat`（自动用项目 `.venv`） |
| 命令行 | `..\.venv\Scripts\python.exe app.py` |

## 三、十个实训（从 0 到 1）

| # | 目录 | 学什么 | 端口 | 手册 |
|---|---|---|---|---|
| 01 | `lab01_flask_routing` | 第一个页面、路由四件套、转换器、跳转、404 | 5110 | `walkthrough.html` |
| 02 | `lab02_request_response` | request 对象、Cookie、Session、自定义状态码 | 5111 | `walkthrough.html` |
| 03 | `lab03_web_frontend` | HTML/CSS/JS/Bootstrap 六节 | 5112 | `walkthrough.html` |
| 04 | `lab04_jinja2_templates` | 模板继承、宏、过滤器、include | 5113 | `walkthrough.html` |
| 05 | `lab05_forms_and_upload` | 表单校验、CSRF、安全上传、富文本 | 5101 | `walkthrough.html` |
| 06 | `lab06_sqlalchemy_crud` | 模型、建表、增删改查、分页 | 5115 | `walkthrough.html` |
| 07 | `lab07_flask_migrate` | 迁移三板斧：加列不丢数据 | 5129 | `walkthrough.html` |
| 08 | `lab08_app_factory_blueprints` | 应用工厂、扩展单例、蓝图、flask CLI | 5116 | `walkthrough.html` |
| 09 | `lab09_flask_login` | 登录/登出、密码哈希、权限保护 | 5117 | `walkthrough.html` |
| 10 | `lab10_blog_project` | 综合项目：登录+发文+列表+详情+删除 | 5118 | `walkthrough.html` |

## 三点五、每个 lab 现在有什么

| 内容 | 文件 |
|---|---|
| 代码 | `app.py`（英文标识符 + 一行中文短注释） |
| 说明 | `README.md`（运行/路由/验收/指令）、`notes.md`（知识点对照） |
| 启动 | `run.bat`（双击，自动用项目 `.venv`） |
| 图文手册 | `walkthrough.html`：**PPT 知识点 → 配解释器 → 打开并运行 → 每个路由一屏 → 报错表 → 交付物**，图片全部内嵌 |
| 实训报告 | `report_labNN.docx`：目的 / 知识点(PPT) / 环境 / 步骤(配图) / 运行结果表 / 问题与解决 / 小结，可直接打印上交 |
| 截图 | `screenshots/pycharm_editor.png`、`pycharm_run.png`（本 lab 真机）、`screenshots/pages/`（全部 GET 路由）、`screenshots/errors/`（真机复现的报错） |
| 报错实战 | 手册第六节：先把错误跑出来截屏，再给「原因 + 怎么解决」；共用案例是 `ModuleNotFoundError: flask` |

教材配套 PPT 的知识点已按章抽取到 **`knowledge/ch01..ch07.md`**（503 页要点、158 张原图），手册与报告都引用对应章节。

每个实训目录里的文件：

| 文件 | 用途 |
|---|---|
| `app.py` | 代码（英文标识符，一行中文短注释） |
| `README.md` | 运行方式 / 路由表 / 验收点 / 指令 |
| `notes.md` | 该章知识点与代码的对应（部分实训有） |
| `run.bat` | 双击启动 |
| `walkthrough.html` | 图文手册：配解释器 → 运行 → 每个页面，图片全部内嵌 |
| `screenshots/` | `page_NN.png` 原图 + `annotated/` 标注图 |

## 四、通用指令

```bat
:: 看本实训的路由清单
..\.venv\Scripts\python.exe -m flask --app app routes

:: 清空所有实训数据库，回到第一次上课的状态
..\.venv\Scripts\python.exe reset_all.py

:: 换电脑：建环境 + 修解释器
setup_env.bat
fix_interpreter.ps1
```

**lab07 额外**：`-m flask --app app db upgrade` / `db current` / `db history`
**lab08 额外**：`-m flask --app app init-db` / `shell`

## 五、配套文档

| 文件 | 内容 |
|---|---|
| `START_HERE.md` | 学生第一课：三步跑起来 + 常见问题 |
| `RUN_COMMANDS.md` | 10 个实训端口与全部指令 + 中文路径实测结论 |
| `SOP_ADD_A_LAB.md` | 再做一个实训的标准流程（脚本化） |
| `LABS_OVERVIEW.md` | 10 个实训一览 |
| `docs\` | 环境安装手册 / PyCharm 实训指南 / 逐章知识点对照表 |

## 六、给零基础学生的三条规矩

1. **一个实训一个窗口**：学到哪一步就只打开那一个文件夹，避免十个项目抢同一个数据库。
2. **所有实训共用一个解释器**：项目根 `.venv`，不要每个实训各建一个。
3. **报错先看终端最后一行**：`ModuleNotFoundError` = 解释器/依赖；`Address already in use` = 上个服务没关；404 = 地址拼错。

## 七、做完往哪走（部署上线）

`lab10` 的博客就是最小可部署系统。脚本已备在 `00_总览\_工具脚本\部署\`（Linux gunicorn+systemd+Nginx、Windows waitress+NSSM、数据库最小权限 SQL），**尚未执行**，等服务器信息再跑。
