# -*- coding: utf-8 -*-
"""lab07_flask_migrate · 第5章 数据库存储（迁移）（端口 5129）

本节重点（对应教材配套 PPT，授课：谢福财）：
    - 为什么需要迁移：直接改模型不会改已存在的表
    - 三板斧：flask db init / migrate / upgrade
    - 迁移脚本：migrations/versions 下 upgrade() 与 downgrade() 成对
    - 加列不丢数据：nullable=True 或给默认值
    - 回退：flask db downgrade 退回上一版

运行：
    ..\\.venv\\Scripts\\python.exe app.py      # 或双击 run.bat / PyCharm 点绿三角
    浏览器打开 http://127.0.0.1:5129/

说明：本文件每一段都有注释；带 ★ 的行是这一讲要重点看的代码。
"""

import os

# ---------- Flask 相关导入 ----------
from flask import Flask, render_template, redirect, url_for, flash
# Flask       → Web 框架核心
# render_template → 渲染 Jinja2 模板（第3章学的）
# redirect/url_for → 重定向和路由反查（第1章学的）
# flash           → 消息闪现（第4章学的消息反馈）

from flask_sqlalchemy import SQLAlchemy
# SQLAlchemy → ORM 框架（第5章 5.3 上周学的）
# 作用：把 Python 类映射为数据库表，对象映射为行

from flask_migrate import Migrate
# Migrate → 数据库迁移扩展（本节课 5.4 的主角）
# 作用：管理表结构的版本变更（加列/删列/改列），不丢数据

from flask_bootstrap import Bootstrap5
# Bootstrap5 → 前端框架（第2章学的），本地资源模式

# ---------- 应用配置 ----------
BASE = os.path.dirname(os.path.abspath(__file__))
# 获取当前文件所在目录的绝对路径（不依赖运行位置）

app = Flask(__name__)
# 创建 Flask 应用实例；__name__ 帮 Flask 定位模板和静态文件

app.config['SECRET_KEY'] = 'shefucai-classroom'
# 密钥：用于 session 加密和 CSRF 令牌签名（第4章学的）
# 生产环境应从环境变量读取，不要硬编码

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + os.path.join(BASE, 'migrate.db')
# 数据库连接地址：使用 SQLite 文件库（入门最简单）
# 'sqlite:///D:/JR/PythonWeb课件/ch5m/migrate.db'
# 如果换 MySQL：'mysql://用户名:密码@localhost/数据库名'

app.config['BOOTSTRAP_SERVE_LOCAL'] = True
# Bootstrap 资源本地化：教室断网也能正常显示样式

# ---------- 扩展初始化 ----------
db = SQLAlchemy(app)
# 初始化 SQLAlchemy：获得 db 对象
# db.Model  → 所有模型的基类（定义表）
# db.Column → 定义字段（列）
# db.session → 会话（增删改查的事务管理）
# db.session.add(对象) → 添加一行
# db.session.commit()  → 提交事务

migrate = Migrate(app, db)
# ★ 本节课核心：初始化 Flask-Migrate
# 把 app 和 db 绑定给 Migrate 管理
# Migrate 会扫描 db.Model 的变化，生成迁移脚本
# 底层使用 Alembic 引擎（SQLAlchemy 官方迁移工具）

Bootstrap5(app)
# 初始化 Bootstrap-Flask：让模板里能用 {{ bootstrap.load_css() }}

# ---------- 模型定义 ----------
class Student(db.Model):
    """学生表模型：一个类 = 一张表，一个属性 = 一个字段

    迁移实验步骤：
    1. 先用当前三列跑 migrate + upgrade（建表）
    2. 在下面加一行 email = db.Column(db.String(50))
    3. 再跑 flask --app app db migrate -m "add email"
    4. 再跑 flask --app app db upgrade
    5. 重启应用，页面上就会多出 email 列
    """
    __tablename__ = 'students'       # 指定表名（不写则默认类名小写）

    # 主键：自增整数，每行唯一标识
    id = db.Column(db.Integer, primary_key=True)

    # 姓名：字符串最多20字符，不能为空（NOT NULL）
    name = db.Column(db.String(20), nullable=False)

    # 成绩：浮点数（可以为空）
    score = db.Column(db.Float)

    # ★ 实验开关：这一行现在是注释状态，表里只有 3 列
    #   把它取消注释 → 执行 migrate + upgrade → 表里会多出 email 列（数据不丢）
    # email = db.Column(db.String(50))  # 邮箱：本次要给 students 表新增的列

    def __repr__(self):
        # 打印对象时的显示格式（调试用）
        return f'<Student {self.name}>'


# ---------- 路由（页面） ----------
# ★ 本节重点：学生列表（含迁移新增的 email 列）
@app.route('/')
def index():
    """首页：显示所有学生"""
    # db.session.execute(db.select(Student)) → SQLAlchemy 2.x 查询写法
    # .scalars() → 把结果行转为 Student 对象
    # .all() → 取出全部
    students = db.session.execute(db.select(Student)).scalars().all()
    return render_template('index.html', students=students, has_email=hasattr(Student, 'email'))
    # 把 students 列表传给模板，模板里用 Jinja2 for 循环渲染


# ★ 本节重点：用 URL 快速加一条数据（方便看迁移效果）
@app.route('/add/<name>/<float:score>')
def add(name, score):
    """添加学生（动态路由：<name> 和 <score> 从 URL 取值）"""
    db.session.add(Student(name=name, score=score))
    # db.session.add() → 把新对象加入会话（还没写入数据库）
    db.session.commit()
    # db.session.commit() → 提交事务，真正写入数据库（INSERT）
    flash(f'已添加：{name} {score}分')
    # flash → 消息闪现，下次请求时模板可以显示
    return redirect(url_for('index'))
    # 重定向回首页（PRG模式：Post-Redirect-Get，防止刷新重复提交）


# ---------- 启动 ----------
if __name__ == '__main__':
    # 实训课：不调用 db.create_all()，表结构完全由 flask db upgrade 创建
    # （平时开发可以用 create_all；正式项目/本节课必须用 Flask-Migrate）
    app.run(debug=False, port=5129)
    # debug=True → 代码改动自动重启（开发模式）
    # port=5129 → 端口号（不和其他演示项目冲突）
