开发十步 · 从空文件夹到上线

# 古典文学网 · 需求文档
## 1. 一句话定位   面向文学爱好者的赏析阅读站（纯展示 + 轻互动）
## 2. 用户与场景   谁来用？在什么情况下打开？
## 3. 功能清单     板块 / 功能点 / 优先级（照上表抄）
## 4. 不做清单     明确写「为什么不做」，防止后期无限膨胀
## 5. 页面结构     五页原型缩略图 + 每页调用的接口
## 6. 变更记录      后期每次改需求都记一行

CREATE TABLE `user` (
  `id`       INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '用户ID，主键自增',
  `username` VARCHAR(50)  NOT NULL               COMMENT '登录名（唯一）',
  `password` VARCHAR(255) NOT NULL               COMMENT '密码哈希——绝不存明文',
  `nickname` VARCHAR(50)                          COMMENT '昵称',
  `avatar`   VARCHAR(255) DEFAULT ''             COMMENT '头像路径',
  `status`   TINYINT NOT NULL DEFAULT 1           COMMENT '1正常 0禁用（软删除）',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`), UNIQUE KEY `uk_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户';

CREATE TABLE `article` (
  `id`          INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `title`       VARCHAR(150) NOT NULL            COMMENT '标题',
  `category_id` INT UNSIGNED                     COMMENT '所属分类，外键',
  `views`       INT NOT NULL DEFAULT 0            COMMENT '浏览量（冗余计数）',
  `likes`       INT NOT NULL DEFAULT 0            COMMENT '点赞数（冗余计数）',
  `content`     TEXT                             COMMENT '正文',
  PRIMARY KEY (`id`),
  CONSTRAINT `fk_article_category` FOREIGN KEY (`category_id`)
    REFERENCES `category`(`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

mkdir hiflask && cd hiflask
python -m venv venv                  # 每个项目一个虚拟环境，依赖互不打架
venv/bin/pip install flask flask-sqlalchemy flask-migrate \
    flask-jwt-extended flask-cors python-dotenv pymysql
venv/bin/pip freeze > requirements.txt   # 锁版本，别人拿到就能装

hiflask/
├── app.py            # 工厂 create_app：装配扩展、蓝图、错误处理
├── config.py         # 三套配置：dev / prod / testing，读 .env
├── extensions.py     # db / jwt / cors / migrate 只在这里 new 出来
├── models/           # 7 张表 → 7 个模型类（第 4 步）
├── views/            # 蓝图：home / user / article / comment / favorite
├── utils/            # 统一响应 response.py、鉴权 auth.py（第 5 步）
├── static/upload/    # 头像等上传文件
├── requirements.txt
└── .env              # 密码密钥，绝不进版本库（.env.example 是模板）

# 模型文件要 import db，app.py 又要 import 模型——
# 如果 db 在 app.py 里创建，就形成「app → models → app」循环导入。
# 单独一个 extensions.py 打破循环：谁都来拿，但它谁也不依赖。
from flask_sqlalchemy import SQLAlchemy
from flask_jwt_extended import JWTManager
from flask_cors import CORS
from flask_migrate import Migrate

db, jwt, cors, migrate = SQLAlchemy(), JWTManager(), CORS(), Migrate()

def create_app(config_name: str = "dev") -> Flask:
    app = Flask(__name__)
    app.config.from_object(config_map[config_name])

    # ① 初始化扩展（db/jwt/cors 绑到 app 上）
    db.init_app(app); jwt.init_app(app)
    cors.init_app(app, resources={r"/api/*": {"origins": "*"}})
    migrate.init_app(app, db)

    # ② 注册蓝图（18 个接口在这里挂上去）
    register_blueprints(app)

    # ③ JWT 异常统一成 {code:401} + 全局错误兜底
    register_jwt_handlers(); register_error_handlers(app)
    return app

home_bp = Blueprint("home", __name__, url_prefix="/api")

@home_bp.get("/health")
def health():
    db.session.execute(db.text("SELECT 1"))   # 顺带探数据库连通性
    return success({"service": "hiflask", "status": "up"})

class User(db.Model):
    __tablename__ = "user"

    id       = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(50), nullable=False, unique=True)
    password = db.Column(db.String(255), nullable=False)   # 只存哈希
    status   = db.Column(db.SmallInteger, nullable=False, default=1)
    created_at = db.Column(db.DateTime, nullable=False, default=datetime.now)

    # lazy="dynamic"：拿到的是可继续筛选的 Query，适合一对多
    comments  = db.relationship("Comment", back_populates="user", lazy="dynamic")

    # —— 密码 ——
    def set_password(self, raw): # 自动加盐的哈希，绝不存明文
        self.password = generate_password_hash(raw)
    def check_password(self, raw):
        return check_password_hash(self.password, raw)

    # —— 序列化：白名单写法，password 永远不会出现在响应里 ——
    def to_dict(self):
        return {"id": self.id, "username": self.username,
                "nickname": self.nickname, "avatar": self.avatar or "", ...}

def success(data=None, msg="success"):
    return jsonify(code=200, msg=msg, data=data)

def fail(msg="参数错误", code=400):
    return jsonify(code=code, msg=msg, data=None)   # msg 可直接展示给用户

def page_data(items, total, page, page_size):
    # 所有分页接口共用这一种 data 结构
    return {"list": items, "total": total, "page": page, "page_size": page_size}

def login_required(view_func):
    @wraps(view_func)
    def wrapper(*args, **kwargs):
        verify_jwt_in_request()               # ① 校验请求头里的 Bearer token
        uid = int(get_jwt_identity())         # ② identity → 用户 id
        user = db.session.get(User, uid)
        if user is None or user.status != 1:  # ③ 账号还在吗？被禁用了吗？
            return fail("请先登录", code=401)
        g.current_user = user                 # ④ 挂到 g 上，视图直接用
        return view_func(*args, **kwargs)
    return wrapper

# 用法：写在哪个视图上，哪个接口就要登录
@comment_bp.post("/add")
@login_required
def comment_add(): ...

@jwt.expired_token_loader
def expired(header, payload):
    return fail("登录已过期，请重新登录", code=401)
# unauthorized / invalid / revoked 三种异常同理。
# 前端拦截器只要看到 code===401：清登录态 → 跳登录页 → 记住回来的地址。

page, page_size = parse_page()          # 夹取：page≥1，page_size≤50，防手滑打崩库
category_id = request.args.get("category_id", type=int)
keyword     = request.args.get("keyword")
order_by    = request.args.get("order_by", "latest")

query = select(Article).where(Article.status == 1)     # 从「已发布」这条主线开始
if category_id:                        # 条件逐段叠加到同一个 query 上
    query = query.where(Article.category_id == category_id)
if keyword:
    like = f"%{keyword}%"
    query = query.where(db.or_(Article.title.like(like), Article.summary.like(like)))

# 排序必须带次关键字 id：否则同值记录顺序不保证，翻页会重复 / 漏条
if order_by == "hot":
    query = query.order_by(Article.views.desc(), Article.id.desc())

page_obj = db.paginate(query, page=page, per_page=page_size, error_out=False)
return success(page_data([a.to_list_dict() for a in page_obj.items],
                         page_obj.total, page, page_size))

npm create vite@latest hivue -- --template vue
cd hivue && npm install
npm install element-plus @element-plus/icons-vue axios pinia vue-router

import { createPinia } from 'pinia'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import router from '@/router'
import App from './App.vue'

createApp(App)
  .use(createPinia())      // 全局账本（登录态住这里）
  .use(router)             // 游园动线
  .use(ElementPlus)        // 预制构件厂
  .mount('#app')           // 开门

const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE,  // '/api'——写配置不写死 IP
  timeout: 10000,
})

// 请求拦截器：有 token 就自动带上——页面代码永远不用手写 Authorization
request.interceptors.request.use((config) => {
  const token = useUserStore().token
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

// 响应拦截器：只认 code。200 → 直接返回 data；401 → 清登录态跳登录页；其它 → 弹 msg
request.interceptors.response.use((response) => {
  const { code, msg, data } = response.data
  if (code === 200) return data
  if (code === 401) { userStore.logout(false); router.push('/login') }
  else ElMessage.error(msg || '操作失败')
  return Promise.reject(new Error(msg))
})

onMounted(async () => {
  loading.value = true
  // 三个接口互不依赖 → 并发请求，比串行 await 快两倍
  const [bannerData, categoryData, recommendData] = await Promise.all([
    getBannerList(), getCategoryList(), getRecommend(),
  ])
  banners.value = bannerData || []
  categories.value = categoryData || []
  recommends.value = recommendData?.list || []
  loading.value = false
})

// 用户改了筛选条件 → 当前页码很可能已越界 → 强制回第 1 页再查
watch([selectedCategory, keyword], () => {
  page.value = 1
  fetchList()
})

const props = defineProps({ article: { type: Object, required: true } })

// 后端两种接口给的字段名不同（category_name vs categoryName）——
// 兼容逻辑写在 computed 里，模板永远只写一个名字
const categoryName = computed(() =>
  props.article.category_name || props.article.categoryName || '')

登录成功 → Pinia 存 token → localStorage 持久化（刷新不丢）
  ↓ 发请求
请求拦截器自动加 Authorization: Bearer <token>
  ↓ 后端
@login_required 校验 → 过期/无效统一返回 code 401
  ↓ 前端
响应拦截器看到 401 → 清登录态 → 跳 /login?redirect=原地址 → 登录后跳回

@pytest.fixture()
def client():
    app = create_app("testing")     # config 里 testing 用内存 SQLite，不碰开发库
    with app.app_context(): db.create_all()
    yield app.test_client()

def test_health(client):
    assert client.get("/api/health").get_json()["code"] == 200

def test_register_login_profile(client):
    r = client.post("/api/user/register", json={...})
    tok = client.post("/api/user/login", json={...}).get_json()["data"]["token"]
    r = client.get("/api/user/profile", headers={"Authorization": f"Bearer {tok}"})
    assert r.get_json()["code"] == 200

npx vite build --base=/mysite/   # 部署在子目录时必须指定 base！根路径部署则省略
# 产物 dist/：带指纹的 assets + 单页 index.html，扔给 nginx 就行

ExecStart=/opt/hiwen-api/venv/bin/gunicorn --workers 2 --timeout 30 \
    --bind 127.0.0.1:5099 --access-logfile - --error-logfile - 'app:create_app()'

# Vue 演示站：history 路由刷新不 404 的关键就是 try_files 回落 index.html
location ^~ /mysite/ {
    try_files $uri $uri/ /mysite/index.html;
}
# 接口反代：同域名 → 天然同源，浏览器无跨域问题
location ^~ /api/ {
    proxy_pass http://127.0.0.1:5099;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
location ^~ /static/ {
    proxy_pass http://127.0.0.1:5099;   # 轮播图 / 上传头像
}