# Python Web 程序开发 · 材料结构说明（STRUCTURE）

> 课程编码 1061100024　教材《Python Web 开发技术与应用（Flask 版）》　授课：谢福财
> 这份文件回答三个问题：**东西都在哪、每章对应哪个实训、按什么顺序用**。

---

## 一、顶层目录（全英文路径）

```
D:\JR 区块链\
└─ 01_python_web_1061100024\            ← 这门课的全部材料
   ├─ 01_html_slides\                   HTML 课件（56 套 / 1287 页）+ 生成器
   ├─ 02_classroom_handouts\            课堂上发给学生的版本
   ├─ 03_practicum_labs\               ★ 实训工程（下面详细展开）
   ├─ 04_teaching_docs\                 教学大纲、进度表、教案、实验指导书
   ├─ 05_my_prep\                       备课指南、精讲 PDF、授课 PPT
   ├─ 06_textbook_assets\               教材配套 PPT、示例源码、参考答案
   ├─ 07_attendance\                    考勤、课表
   └─ 08_archive\                       归档（改版前的备份）
```

**要给学生/自己用的，只有一个入口**：`03_practicum_labs\index.html`

---

## 二、实训工程 `03_practicum_labs` 的结构

```
03_practicum_labs\
├─ index.html                 ★ 总入口（一页看全部：理论课 + 10 个实训 + 配置 + 报错）
├─ pycharm_guide.html         PyCharm 操作图解（终端 / 运行 / 解释器 / 装包 / 环境变量 / 报错）
├─ SHOW_ME_FIRST.md           新手 3 分钟：打开哪个文件夹、点哪、看什么
├─ COURSE_MAP.md              材料位置清单（一页表格）
├─ README.md                  项目说明
├─ RUN_COMMANDS.md            10 个实训的端口与命令
├─ SOP_ADD_A_LAB.md           再加一个实训的标准流程
├─ LABS_OVERVIEW.md           十个实训一览
├─ setup_env.bat              换电脑一键装环境
├─ fix_interpreter.ps1        黄条一键修复解释器
├─ reset_all.py               清空所有实训数据库
├─ requirements.txt           依赖清单
│
├─ theory\                    ★ 七节理论课
│  ├─ ch01.html … ch07.html   每节：学习目标 → 知识点(是什么/生活案例/代码/易错点) → 课堂演示 → 练习 → 小结
│
├─ knowledge\                 ★ 教材 PPT 抽取
│  ├─ ch01.md … ch07.md       每章要点（503 页里挑出来的）
│  └─ media\ch01..ch07\       PPT 原图 158 张
│
├─ 00_setup_screenshots\      ★ 环境配置图解 9 张（含"该打开哪个文件夹"）
│  └─ ops\                    PyCharm 操作截图（终端/运行/设置）
│
├─ lab01_flask_routing\       ★ 一个实训 = 一个文件夹（英文名，端口固定）
│  ├─ app.py                  代码（头部写本节重点，每个路由上方 ★ 注释）
│  ├─ README.md               怎么跑 / 路由表 / 验收点
│  ├─ notes.md                知识点与代码对应
│  ├─ run.bat                 双击启动
│  ├─ walkthrough.html        图文手册（PPT要点→配解释器→运行→每屏+对应代码→喂饭步骤→报错→交付物）
│  ├─ report_lab01.docx       实训报告（可直接打印上交）
│  └─ screenshots\
│     ├─ pycharm_editor.png   本 lab 在 PyCharm 里打开（左侧树高亮该文件）
│     ├─ pycharm_run.png      运行面板 Running on 本端口
│     ├─ pages\               每个 GET 路由的浏览器截图 + index.json
│     ├─ code\                每条路由对应的代码定位图（Ctrl+G 跳行）+ index.json
│     ├─ errors\              真机复现的报错截图
│     └─ annotated\           带红框编号的版本
│
├─ lab02 … lab10              同 lab01 的结构
├─ preview\                   预览图
├─ docs\                      补充文档（PyCharm 指南 / 环境手册 / 知识点对照 / 截图索引）
└─ tools\                     小工具脚本
```

---

## 三、章 ↔ 实训 ↔ 端口

| 章 | 理论课 | 实践实训 | 端口 | 这节课的核心 |
|---|---|---|---|---|
| 第1章 Flask 基础 | `theory/ch01.html` | lab01 / lab02 | 5110 / 5111 | 路由、请求响应、Cookie/Session |
| 第2章 Web 前端基础 | `theory/ch02.html` | lab03 | 5112 | HTML / CSS / JS / Bootstrap |
| 第3章 模板 Jinja2 | `theory/ch03.html` | lab04 | 5113 | 变量、控制、继承、宏、过滤器 |
| 第4章 与用户交互 | `theory/ch04.html` | lab05 | 5101 | 表单校验、CSRF、上传、富文本 |
| 第5章 数据库存储 | `theory/ch05.html` | lab06 / lab07 | 5115 / 5129 | SQLAlchemy CRUD、迁移 |
| 第6章 可维护性 | `theory/ch06.html` | lab08 / lab09 | 5116 / 5117 | 工厂、蓝图、Flask-Login |
| 第7章 综合实例 | `theory/ch07.html` | lab10 | 5118 | 博客完整闭环 |

**递进关系**：第2章起每节课都复用第1章的"打开项目→运行→停止"；第5章起复用第3章的模板；第6章把前面的路由搬进蓝图；第7章把前六章全部装上。

---

## 四、一次课怎么用（45 分钟 × 2）

**理论课（45 分钟）**
1. 打开 `theory/chXX.html`，按知识点逐个讲（每个都有生活案例）
2. 讲完一个知识点，切到 PyCharm 演示一次（理论课页面里有课堂演示截图）

**实践课（45 分钟）**
1. 学生打开 `labNN\walkthrough.html`
2. 照第二节配解释器（只有第一次要做）
3. 照第三节打开并运行
4. 照第四节逐个地址打开，**每屏都配一张"对应代码"截图**，让学生知道这段页面是哪个函数渲染的
5. 照第五节喂饭级步骤做（每步写清点哪、按什么键、看到什么）
6. 卡住了看第六节报错实战（真机截图 + 原因 + 解决）

---

## 五、命名与代码规范

| 项 | 规范 | 例子 |
|---|---|---|
| 目录 | 全小写 + 下划线，英文 | `lab07_flask_migrate` |
| Python 文件 | 小写 + 下划线 | `app.py`、`extensions.py`、`models.py` |
| 路由函数 | 动词或名词，小写 | `index()`、`detail()`、`new_post()` |
| 模板 | 小写 + 下划线，放 `templates\` | `index.html`、`detail.html` |
| 静态文件 | 放 `static\` | `site.css` |
| 端口 | 每个 lab 固定，写在 `app.py` 最后一行 | lab01=5110 … lab10=5118 |
| 注释 | 中文短句，讲"这行在干什么" | `# ③ 把新计数写回 Cookie（1天有效）` |
| 本节重点 | 文件头 5 条 + 每个路由上方 `# ★ 本节重点：…` | 见 lab01 app.py |

---

## 六、Markdown 文件清单（怕乱就按这个找）

| 文件 | 什么时候看 |
|---|---|
| `SHOW_ME_FIRST.md` | 第一次打开，3 分钟 |
| `COURSE_MAP.md` | 想知道某类材料在哪 |
| `STRUCTURE.md`（本文件） | 想知道整体架构 |
| `README.md` | 项目说明与验收 |
| `RUN_COMMANDS.md` | 忘了端口/命令 |
| `LABS_OVERVIEW.md` | 十个实训一览 |
| `SOP_ADD_A_LAB.md` | 要加新实训 |
| 各 lab 的 `README.md` / `notes.md` | 当天上课前 5 分钟 |
