Flask + Vue.js 项目创建器

搭建 Flask 3.1 + Vue.js 全栈项目，采用单端口架构、结构化日志和独特的前端设计。

架构概述

单端口架构

所有请求由 Flask 在 80 端口统一处理。静态文件（HTML/CSS/JS）通过 Flask 路由从 templates/ 目录提供。

项目创建工作流

按顺序执行以下步骤：

1. 收集需求 - 询问项目名称和简要描述
2. 初始化项目结构 - 运行 scripts/init_project.py
3. 配置依赖 - 使用 uv 设置 pyproject.toml
4. 创建 Flask 入口 - 生成包含日志的主应用文件
5. 设计前端 - 遵循前端设计指南（见下文）
6. 更新 AGENTS.md - 任何更改后同步项目文档
7. 验证并运行 - 测试项目正常启动

步骤 1：收集需求

向用户询问：

• 项目名称（用于目录、文件名和应用标题）
• 应用功能的简要描述
• 任何特定的设计偏好（配色方案、风格方向）

步骤 2：初始化项目结构

运行初始化脚本：

python scripts/init_project.py  --path 

这将创建：

/
├── AGENTS.md                    # AI Agent 项目指南（自动生成）
├── pyproject.toml               # uv 项目配置
├── uv.lock                      # uv 锁定文件（自动生成）
├── src/
│   ├── .py        # Flask 主入口（含日志）
│   ├── templates/               # 前端资源
│   │   ├── .html  # 主页面 (Vue.js)
│   │   ├── css/                 # 样式文件
│   │   ├── js/                  # JavaScript 文件
│   │   └── assets/              # 静态资源（图片、字体等）
│   ├── utils/                   # 核心工具模块
│   │   ├── __init__.py
│   │   └── logger.py            # 日志模块
│   └── log/                     # 日志输出目录
│       └── *.log                # 按模块分日志文件（按天轮转）

步骤 3：配置依赖

pyproject.toml 自动生成，包含 uv 镜像配置：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

核心依赖：

dependencies = [
    "flask>=3.1.0",
]

步骤 4：创建 Flask 入口

生成的 .py 包含集成的日志功能：

from flask import Flask, send_from_directory, send_file
from utils.logger import get_logger

app = Flask(__name__)
logger = get_logger('')

@app.route('/')
def index():
    return send_file('templates/.html')

# ... 静态文件路由 ...

if __name__ == '__main__':
    logger.info('启动服务器，端口 80...')
    app.run(host='0.0.0.0', port=80, debug=True)

步骤 5：设计前端

创建 HTML/CSS/JS 时应用前端设计指南。完整设计系统参见 references/frontend-design.md。

核心原则：

• 反 AI 风格：避免 Inter、Roboto、Arial、紫色渐变、emoji 图标
• 独特字体：使用独特的 Google Fonts 组合（参见 references/frontend-design.md "字体" 部分）
• 有意配色：选择特定场景的配色方案，而非通用渐变
• 仅用 SVG 图标：使用 Heroicons、Lucide 或 Simple Icons — 不用 emoji
• Vue.js CDN 引入：在 HTML 中使用 Vue 3 CDN，Composition API 配合

  详细的 Vue.js 最佳实践参见 references/vue-guidelines.md。

  步骤 6：更新 AGENTS.md

  重要：任何项目修改后，更新 AGENTS.md 以反映变更。

  AGENTS.md 文件在项目创建时自动生成，作为 AI Agent 项目指南。必须与实际项目状态保持同步。

  何时更新 AGENTS.md：

  • 添加新路由或 API 端点
  • 添加新工具模块或文件
  • 更改项目结构
  • 添加新依赖
  • 修改日志配置
  • 任何架构变更

  更新内容：

  • 项目结构树（添加/删除文件和目录）
  • 架构描述（新路由、模块、功能）
  • 开发指南（新约定或模式）
  • 更新日志表（添加日期、版本、描述条目）

  更新日志格式：

  ## 更新日志
  
  | 日期 | 版本 | 变更内容 |
  |------|------|---------|
  | 2026-06-07 | 0.1.0 | 初始项目创建 |
  | 2026-06-08 | 0.2.0 | 新增用户认证模块 |
  

  步骤 7：验证并运行

  cd 
  uv sync
  uv run python src/.py
  

  日志模块

  概述

  • 位置：src/utils/logger.py
  • 日志目录：src/log/
  • 格式：%(asctime)s | %(levelname)-8s | %(name)s | %(message)s
  • 轮转：按天 (TimedRotatingFileHandler)，保留 30 天
  • 输出：同时输出到控制台和文件

  使用方法

  from utils.logger import get_logger
  
  logger = get_logger('module_name')
  logger.info('操作成功完成')
  logger.warning('发生了意外情况')
  logger.error('发生错误: %s', error_detail)
  

  日志文件

  每个日志记录器名称创建单独的日志文件：src/log/.log

  文件在午夜轮转，命名模式：.log.YYYY-MM-DD

  交付前检查清单

  交付前验证：

  • 项目结构符合指定布局
  • pyproject.toml 包含 [tool.uv] 清华镜像配置
  • pyproject.toml 位于项目根目录（与 src 同级）
  • Flask 路由服务所有静态文件目录
  • 日志模块已集成到 Flask 入口
  • src/log/ 目录存在且包含 .gitkeep
  • AGENTS.md 存在且反映当前项目状态
  • HTML 使用 Vue 3 CDN 和 Composition API
  • 无 emoji 图标（仅用 SVG）
  • 字体独特（非 Inter/Roboto/Arial）
  • 配色方案符合场景
  • 所有交互元素有 cursor-pointer
  • 文本对比度达到 4.5:1 最低要求
  • 在 375px、768px、1024px、1440px 响应式适配