第一集：商品接口演示体验包
========================

你下载的是源代码ZIP，不是Python安装包，也不是老师的在线网站。
这个小程序供你运行后体验“填写编号→发送请求→收到回答”。
本集先认识接口；第二集才从空文件亲手写hello。这里是提前提供的完成态演示，不能当成自己已经独立完成的证明；本集六道场景题另做。
当前包面向Windows，使用Python 3.11；首次安装依赖需要联网。

一、先解压，再打开终端

1. 在ZIP上点右键→“全部解压缩”。不要在压缩包预览里直接运行。
2. 打开解压后的“第一集-商品演示”文件夹。应看见：
   product_api.py、initialize_once.py、requirements.txt、constraints.txt和本说明。
3. 点击这个【文件夹窗口】最上方的地址栏，输入 powershell，再按回车。
   打开的是终端；它和稍后输入网址的【浏览器地址栏】是两个位置。
4. 在终端输入 Get-ChildItem 并回车，确认输出里有上面四个文件。
   下面的命令都在这个终端里逐条输入、回车；一条成功后再做下一条。

二、确认Python

输入：
py -3.11 --version

看到 Python 3.11.x 才继续。这里的x是你实际安装的补丁版本，不用输入字母x。
如果提示找不到py或Python3.11，不要继续粘贴后面的命令，先看包内“安装Python.txt”。

三、创建本文件夹专用的环境

输入：
py -3.11 -m venv .venv

没有报错、重新出现PS提示符后，再输入：
.\.venv\Scripts\python.exe --version

看到 Python 3.11.x，说明后续要用的解释器已准备好。
“.venv”是本文件夹的隔离环境；后面的长路径就是明确使用它。
无需激活环境，也无需更改PowerShell执行策略。

四、安装演示依赖，等它返回

输入：
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -c constraints.txt

安装时终端会打印下载和安装进度。先等这条命令完成，不要边安装边输入下一条。
首次安装通常会看到 Successfully installed；已安装时也可能看到 Requirement already satisfied。
这两个词不能代替核查。命令成功返回PS提示符后，继续输入：

.\.venv\Scripts\python.exe -m pip check

预期：No broken requirements found.
若有红色报错、ERROR或网络失败，先保留完整输出，按末尾的排错说明处理。

五、仅在第一次创建教学数据

输入：
.\.venv\Scripts\python.exe initialize_once.py --yes

首次成功输出的JSON中应有："passed": true 和 "row_count": 2。
它会在这个文件夹生成 products.sqlite3：
编号1：示例笔记本，1200分，文具。
编号2：示例水杯，2800分，日用。

务必先初始化，再启动服务。只启动服务会创建空表，不会自动生成两条示例。
再次使用已有数据时跳过本步骤。若提示“数据库已存在，拒绝重复初始化”，
请保留已有库，核对自己此前做过什么，不要删除或反复运行旧reset脚本。

六、真正启动服务

输入完整一行：
.\.venv\Scripts\python.exe -m uvicorn product_api:app --host 127.0.0.1 --port 8004

预期在终端看见：
Uvicorn running on http://127.0.0.1:8004
Application startup complete.

这些日志可能以不同顺序出现。看到启动完成，并且没有报错退出，才进入下一步。
此时终端不回到PS提示符是正常的：服务正在前台运行。
保留这个窗口，不关闭，也不要按Ctrl+C。

七、现在才打开浏览器

打开Chrome或Edge，点击【浏览器顶部地址栏】，输入完整地址并回车：
http://127.0.0.1:8004/docs

127.0.0.1访问的是你自己的电脑。只有你自己的服务成功运行后，这个地址才可用。
看到标题“第一集独立商品练习”和接口列表，说明测试页已打开。
Swagger测试页和输入框由FastAPI生成，不是需要另行购买或安装的软件。

八、发出两次真实查询

1. 找到 GET /api/products/{id}，点击这一行展开。
2. 点击 Try it out，让参数可以编辑。
3. 在 id 输入框填1。此时只是填写，还没发送。
4. 点击 Execute，再向下滚动查看。
5. 核对 Request URL 末尾是 /api/products/1，Code是200，正文应有：
   "id": 1，"name": "示例笔记本"，"price_cents": 1200，"category": "文具"。
6. 回到id输入框，把1改成2。旧回答可能还在；要再次点击Execute。
7. 核对新的Request URL末尾是 /api/products/2，Code是200，正文应有：
   "id": 2，"name": "示例水杯"，"price_cents": 2800，"category": "日用"。

1200和2800的单位是分，分别对应12元和28元。
本集只用查询体验；先不要在POST里执行新增。后续课再解释请求体与写入。

九、结束和下次启动

结束时回到刚才运行服务的终端，按一次Ctrl+C。
等到 Application shutdown complete、Finished server process 和PS提示符后再关窗口。
下次进入同一文件夹并打开PowerShell，已有环境和数据库时，直接执行第六步启动命令。
不要再次初始化，也不用重装依赖。

十、如果失败，可以让AI协助排查

把“在哪一步、完整命令、完整报错、文件夹位置、Python版本”一起给AI，
并说明：“我正在运行FastAPI商品教学演示，请先判断原因，保留已有数据库。”
不要只发“打不开”。不要给AI发送账号密码、访问令牌或私人文件。
若端口8004被占用，先核对是否自己已经打开了一个服务窗口，
不要直接结束不认识的进程。若启动失败，先解决终端报错，再刷新浏览器。

本说明是操作入口，不代替视频中的真实演示。代码与片中商品数据保持一致。
