Python 零基础教学项目协作规范

一、项目定位

本项目用于帮助没有 Python 基础的学习者，从基础语法开始，逐步掌握面向对象、数据库编程、FastAPI、Django，以及后端项目工程化与部署知识。

教学过程必须循序渐进。不得在没有解释基础概念的情况下，直接使用复杂语法、框架功能或专业术语。

二、语言要求

所有回答、课程文档、练习说明和代码注释必须使用中文。
变量名、函数名、类名等代码标识符使用规范的英文命名，避免使用拼音。
专业术语第一次出现时，必须同时给出中文解释和英文原词。例如：对象关系映射（Object Relational Mapping，ORM）。
错误信息可以保留英文原文，但必须补充中文解释。

三、教学对象

默认学习者是零基础新手，不假设学习者已经掌握以下知识：

编程语言基础；
命令行操作；
Git；
HTTP；
SQL；
数据库；
Web 框架；
软件测试与部署。

讲解新知识时，应先说明“它是什么”“为什么需要它”，再说明“如何使用它”。

四、课程组织规范

每一课原则上包含以下内容：

本课目标：说明完成本课后能够做什么。
前置知识：列出学习本课需要掌握的内容。
概念讲解：使用通俗语言解释核心概念。
示例代码：提供可以独立运行的完整示例。
运行方法：明确说明在哪个目录、执行什么命令。
运行结果：展示正常情况下应看到的结果。
逐行解析：解释关键代码的作用和执行顺序。
常见错误：说明新手容易遇到的问题、原因和解决办法。
课堂练习：提供由浅入深的练习题。
参考答案：与题目适当分隔，避免学习者直接照抄。
本课小结：回顾本课最重要的知识点。
验收标准：提供可检查、可验证的完成条件。

每次课程只引入少量新概念。引用尚未讲解的知识时，必须补充简短说明或明确标注将在后续章节学习。

五、代码编写规范

示例代码必须优先保证清晰、易懂和可运行，再考虑简写或高级技巧。
编写的代码必须参考项目原有注释格式，并为新手提供详尽的中文注释。
注释应重点解释代码的目的、关键步骤和容易误解的地方，避免只把代码逐字翻译成中文。
每个示例应尽量只演示一个主要知识点。
文件名、变量名、函数名和类名应做到见名知意。
Python 代码遵循 PEP 8 基本风格规范。
函数和类应根据当前课程进度逐步添加类型注解，不得在入门阶段堆叠复杂类型。
涉及密码、密钥和数据库连接信息时，必须使用环境变量或示例配置，不得提交真实敏感信息。
数据库写入、文件删除等可能产生副作用的操作，必须提前说明影响并提供安全的练习方式。

六、变更流程

修改或新增文件前，必须先说明修改方案、涉及文件和预期结果。
对本教学项目范围内的常规课程文档、示例代码和练习，说明方案后可以直接执行，无需逐次等待学习者确认。
不得一次性创建大量后续课程代码，课程内容必须跟随学习者的实际进度逐课创建。
每次修改完成后，应检查文件状态，并执行与改动范围相匹配的验证。
不得擅自删除、覆盖学习者已有的练习代码。
如果学习者的代码存在问题，应先解释原因，再提出修改方案。
删除文件、覆盖学习者已有内容、大范围重构或执行其他可能难以恢复的操作前，仍须先说明影响并取得学习者确认。
课程文档和代码默认只写入本地工作区，不自动执行 Git 暂存或提交。
只有学习者明确说“提交”时，才能执行 git add 和本地 git commit。
本项目只创建本地提交，不执行 git push，除非学习者以后重新明确授权推送。

七、目录规划规范

课程内容按“阶段目录 → 课程目录”的层级存放，并遵循以下统一命名规范：

阶段目录格式为 两位阶段编号_阶段名称，例如 01_python基础。
课程目录格式为 阶段号_课程序号_课程主题，例如 1_1_hello_world、1_2_变量与数据类型。
编号、单词和主题之间统一使用半角下划线 _，不得使用空格或连字符。
课程主题优先使用中文，例如 变量与数据类型、类与对象。
Python、Web、HTTP、JSON、SQL、FastAPI、Django、Git、Docker、hello_world 等通用技术名或教学惯例，可以保留规范英文名称。
英文名称统一采用业界常见写法；目录中的普通英文单词使用小写，避免同一名称出现多套写法。
综合项目放在所属阶段内，不另外创建脱离阶段编号的项目目录。

规划中的阶段目录如下：

Python/
├── README.md
├── AGENTS.md
├── 01_python基础/
│   ├── 1_1_hello_world/
│   └── 1_2_变量与数据类型/
├── 02_python进阶/
├── 03_面向对象/
├── 04_数据库/
├── 05_web基础/
├── 06_fastapi/
├── 07_django/
└── 08_工程化与部署/

以上结构是课程规划示意，不代表需要提前创建全部目录。目录必须按照学习者的实际学习进度依次创建：

正式开始某一课时，才创建该课所属的阶段目录和课程目录。
每个课程目录应随课程一起创建中文讲义、示例代码和练习，不单独预建空目录。
当前课程尚未开始或尚未完成时，不得批量创建后续课程目录。
完成当前课程并经学习者确认继续后，才能准备下一课目录。
根目录 README.md 应同步记录当前学习进度和下一课内容。

八、教学互动规范

默认一次推进一课，并等待学习者完成练习或确认继续。
不直接替学习者完成所有练习，应优先提供提示和思考方向。
学习者提交代码后，应从正确性、可读性和知识掌握情况三个方面反馈。
发现知识断层时，应回到对应基础内容补充讲解。
学习者说“继续”时，应先简短回顾上一课，再开始下一课。
每完成一个阶段，应安排复习、测试和综合小项目。

九、阶段验收目标

Python 基础：能够独立编写命令行小程序。
Python 进阶：能够组织多文件程序并处理文件和异常。
面向对象：能够用类设计一个小型业务模型。
数据库：能够使用 SQL 和 Python 完成安全的增删改查。
Web 基础：能够解释一次 HTTP 请求和响应的基本过程。
FastAPI：能够开发带数据库和身份认证的 RESTful API。
Django：能够开发包含后台管理和用户系统的 Web 应用。
工程化：能够为项目编写测试、管理配置并完成基础部署。

7.0 KiB Raw Permalink Blame History Unescape Escape