# -*- coding: utf-8 -*-
"""lab05_forms_and_upload · 第4章 与用户交互（端口 5101）

本节重点（对应教材配套 PPT，授课：谢福财）：
    - GET 与 POST：参数在 URL 还是请求体，能不能重复提交
    - Flask-WTF：表单类 + 校验器，错误信息在模板里显示
    - CSRF 防护：表单必须带 csrf_token，否则 400
    - 安全上传：后缀 + MIME + 大小三重校验，重命名后落盘
    - 富文本：CKEditor 接入与内容回显

运行：
    ..\\.venv\\Scripts\\python.exe app.py      # 或双击 run.bat / PyCharm 点绿三角
    浏览器打开 http://127.0.0.1:5101/

说明：本文件每一段都有注释；带 ★ 的行是这一讲要重点看的代码。
"""

import os
import uuid

from flask import Flask, render_template, request, redirect, url_for, flash
from flask_wtf import FlaskForm                              # 声明式表单基类
from flask_wtf.file import FileField, FileAllowed, FileRequired, FileSize  # 文件字段+校验器
from wtforms import SubmitField, StringField
from wtforms.validators import DataRequired
from flask_ckeditor import CKEditor, CKEditorField, upload_success
from werkzeug.utils import secure_filename                   # 安全文件名过滤
from flask_bootstrap import Bootstrap5                       # 本地 Bootstrap5 静态资源

BASE_DIR = os.path.dirname(os.path.abspath(__file__))
UPLOAD_DIR = os.path.join(BASE_DIR, 'uploads')               # 上传保存目录
os.makedirs(UPLOAD_DIR, exist_ok=True)                       # 目录不存在就创建

ALLOWED_EXT = {'png', 'jpg', 'jpeg', 'gif', 'pdf', 'txt', 'zip'}  # 允许的扩展名白名单

app = Flask(__name__)
app.config['SECRET_KEY'] = 'shefucai-classroom'              # CSRF 与表单需要密钥
app.config['MAX_CONTENT_LENGTH'] = 2 * 1024 * 1024           # 上传大小上限：2MB
app.config['CKEDITOR_PKG_TYPE'] = 'full'                     # CKEditor 工具栏类型
app.config['CKEDITOR_SERVE_LOCAL'] = True                    # CKEditor 用本地资源（教室断网也能跑）
app.config['BOOTSTRAP_SERVE_LOCAL'] = True                   # Bootstrap 也用本地资源

ckeditor = CKEditor(app)                                     # 富文本初始化
bootstrap = Bootstrap5(app)                                  # bootstrap.load_css() 可用


# ---------- 表单类（声明式） ----------
class UploadForm(FlaskForm):
    """文件上传表单：文件字段 + 两道校验器"""
    file = FileField('选择文件', validators=[
        FileRequired(message='请先选择一个文件'),      # 文件字段专用"必填"校验器
        FileAllowed(ALLOWED_EXT, message='只允许上传：png/jpg/jpeg/gif/pdf/txt/zip'),
        FileSize(max_size=2 * 1024 * 1024, message='文件不能超过 2MB'),
    ])
    submit = SubmitField('开始上传')


class PostForm(FlaskForm):
    """富文本编辑表单"""
    title = StringField('文章标题', validators=[DataRequired(message='标题不能为空')])
    body = CKEditorField('正文（富文本）', validators=[DataRequired(message='正文不能为空')])
    submit = SubmitField('保存文章')


# ---------- 页面路由 ----------
# ★ 本节重点：四小节导航
@app.route('/')
def index():
    return render_template('index.html')                     # 课首页：实验入口


# ★ 本节重点：GET 与 POST 的区别
@app.route('/basic', methods=['GET', 'POST'])
def basic():
    """4.1 GET 与 POST 的数据到底放在哪
    同一个路由同时处理两种方法，模板里用 request.args / request.form 对比查看。
    """
    return render_template('basic.html')


# ★ 本节重点：安全上传表单（三重校验）
@app.route('/upload', methods=['GET', 'POST'])
def upload():
    form = UploadForm()
    info = None
    if form.validate_on_submit():                            # 校验通过才保存
        f = form.file.data                                   # 取上传的文件对象
        safe_name = secure_filename(f.filename)              # ① 安全过滤文件名
        ext = safe_name.rsplit('.', 1)[-1].lower() if safe_name else ''
        if not safe_name or ext not in ALLOWED_EXT:          # ② 白名单再查一次
            flash('不安全的文件类型，已被拦截！')
        else:
            new_name = f'{uuid.uuid4().hex[:8]}_{safe_name}' # ③ 重命名，避免重名覆盖
            f.save(os.path.join(UPLOAD_DIR, new_name))       # ④ 保存到 uploads/
            info = {                                         # 展示给学生看的对照信息
                '原名': f.filename,
                '安全名': safe_name or '（中文名被过滤为空，已自动改名）',
                '最终保存名': new_name,
                '大小KB': round(len(f.read()) / 1024, 1),
                '类型': f.content_type,
            }
            f.seek(0)
    return render_template('upload.html', form=form, info=info)


# ★ 本节重点：已上传文件列表
@app.route('/files')
def files():
    names = sorted(os.listdir(UPLOAD_DIR))                   # 已上传文件清单
    return render_template('files.html', names=names)


# ★ 本节重点：CKEditor 富文本发帖
@app.route('/post', methods=['GET', 'POST'])
def post():
    form = PostForm()
    saved = None
    if form.validate_on_submit():
        saved = {'title': form.title.data, 'body': form.body.data}  # 富文本HTML
    return render_template('post.html', form=form, saved=saved)


@app.route('/ckupload', methods=['POST'])
def ckupload():
    """CKEditor 编辑器里'上传图片'按钮的后端接口"""
    f = request.files.get('upload')
    if not f:
        return upload_fail('未收到文件')
    ext = f.filename.rsplit('.', 1)[-1].lower()
    if ext not in {'png', 'jpg', 'jpeg', 'gif'}:             # 图片白名单
        return upload_fail('只允许图片文件')
    name = f'{uuid.uuid4().hex[:8]}_{secure_filename(f.filename)}'
    f.save(os.path.join(UPLOAD_DIR, name))
    url = url_for('static', filename=f'../uploads/{name}')   # 回传给编辑器的图片地址
    return upload_success(url, filename=name)                # flask-ckeditor 规定应答


def upload_fail(message):
    """上传失败的应答（CKEditor 约定的格式）"""
    from flask import jsonify
    return jsonify({'uploaded': 0, 'error': {'message': message}}), 400


if __name__ == '__main__':
    app.run(debug=True, port=5101)
