# quick-project-template

**Repository Path**: numen06/quick-project-template

## Basic Information

- **Project Name**: quick-project-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Web 应用项目模板

面向「管理类全栈 Web + Docker 交付」的**可拷贝起点**，风格与目录约定对齐 [app2docker](https://gitee.com/numen06/app2docker)、[nginx-webui](https://gitee.com/numen06/nginx-webui)、[frp-agent](https://gitee.com/numen06/frp-agent) 三个 Gitee 项目的常见实践。

## 文档导航

`docs/` 下维护各类约定与设计文档，按需查阅：

| 文档 | 说明 |
|------|------|
| [`样式标准.md`](docs/样式标准.md) | 风格总纲：技术栈、API 前缀、Docker、安全等仓库级约定 |
| [`版本标准.md`](docs/版本标准.md) | 版本号（SemVer）与 Git 工作流：分支、标签、发行说明 |
| [`调试标准.md`](docs/调试标准.md) | 本地与联调调试规范：固定端口、先清理旧进程、最小复现与排查顺序 |
| [`后台架构标准.md`](docs/后台架构标准.md) | 后端架构边界：目录分层、接口规范、认证授权、可观测性与发布检查 |
| [`前端框架标准.md`](docs/前端框架标准.md) | 前端通用能力：认证模式、用户管理、API Key、UI 组件库选型 |
| [`单管理员模式/SINGLE_ADMIN_AUTH_DESIGN.md`](docs/单管理员模式/SINGLE_ADMIN_AUTH_DESIGN.md) | 单管理员 JWT 认证：完整前后端设计、本地快捷登录、强制改密流程 |
| [`单管理员模式/USER_API_KEY_DESIGN.md`](docs/单管理员模式/USER_API_KEY_DESIGN.md) | 用户级 API Key 生命周期：创建、复制、轮换、禁用、审计 |
| [`团队体系模式/团队体系设计模式.md`](docs/团队体系模式/团队体系设计模式.md) | 多用户多团队模式：注册/登录、团队加入审批、API Key 与 RBAC 体系 |

> **新增文档时**：在 `docs/` 下创建 Markdown 文件，并在上表中添加一行即可。

## 技术栈

| 层级 | 选型 |
|------|------|
| 后端 | Python 3.11、FastAPI、`pydantic-settings` |
| 前端 | Vue 3、Vite、TypeScript、Pinia |
| 数据 | 默认 SQLite（`data/app.db`，可改为其他 `DATABASE_URL`） |
| 容器 | 多阶段 Dockerfile（Node 构建前端 + Python 运行） |

## 仓库结构

```
.
├── backend/                 # FastAPI
│   ├── app/
│   │   ├── api/             # 路由模块
│   │   ├── core/config.py   # 配置（读仓库根 .env）
│   │   └── main.py
│   └── requirements.txt
├── frontend/                # Vue + Vite（最小脚手架，见 frontend/README.md）
├── data/                    # 持久化（勿提交业务数据）
├── VERSION                  # 应用版本号（SemVer，唯一真源）
├── Dockerfile               # 多阶段镜像构建
├── CHANGELOG.md             # 变更日志（可选维护）
├── release-notes/           # 按版本发行说明（对接 Gitee/GitHub Release）
├── scripts/                 # 本地与打包入口
├── docs/                    # 风格、版本、前端约定等
├── docker-compose.yml
├── .vscode/                 # VS Code / Cursor：launch.json 等
└── .cursor/skills/          # Cursor Skill：栈约定摘要
```

## 本地开发

1. 复制环境变量：`cp .env.example .env`（按需修改）。
2. 后端（建议使用虚拟环境）：

   ```bash
   cd backend && python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   cd .. && bash scripts/start-backend.sh
   ```

3. 前端（新终端）：

   ```bash
   cd frontend && npm install && cd .. && bash scripts/start-frontend.sh
   ```

4. 浏览器：前端开发服务器默认 `http://127.0.0.1:5173`（通过代理访问 `/api/*`）。

### 默认账号（开发占位）

与参考项目一致，环境变量默认：

| 项 | 值 |
|----|-----|
| 用户名 | `admin` |
| 密码 | `admin` |

对应 `AUTH_USERNAME`、`AUTH_PASSWORD`（见 `.env.example` 与 `backend/app/core/config.py`）。**生产环境必须修改**；接入真实登录后由业务代码读取这些配置或替换为数据库用户。

## VS Code / Cursor 调试

1. 安装推荐扩展：打开命令面板 → **Extensions: Show Recommended Extensions**（见 `.vscode/extensions.json`）。
2. 后端：在 `backend` 下创建并选中解释器（如 `backend/.venv`），安装 `pip install -r requirements.txt`。
3. **运行和调试**（或 `F5`）中选择：
   - **Python: FastAPI (后端)**：无 `--reload`，断点最稳定。
   - **Python: FastAPI (后端, 热重载)**：改代码自动重启（子进程下断点行为因版本而异）。
   - **npm: 前端开发 (Vite)**：启动 Vite。
   - **pwa-chrome: 前端页面**：需已运行 Vite，用于在浏览器里调试 Vue/TS（需内置 JavaScript Debugger）。
   - **全栈: 后端调试 + Vite**：同时启动后端调试会话与 `npm run dev`。

配置见根目录 `.vscode/launch.json`。

## Docker

构建并运行：

```bash
bash scripts/package.sh
# 或
docker compose up -d --build
```

访问：`http://localhost:8000`（镜像内前后端同端口，静态资源由 FastAPI 挂载）。

**默认账号**：`admin` / `admin`（可通过环境变量 `AUTH_USERNAME`、`AUTH_PASSWORD` 覆盖；生产务必修改）。

**务必挂载数据目录**，避免数据库与上传丢失：

```bash
docker run -d --name ai-webapp-template -p 8000:8000 -v "$(pwd)/data:/app/data" ai-webapp-template:latest
```

## Cursor / AI 协作

- **栈与目录**：`.cursor/skills/numen-web-stack/SKILL.md`
- **登录 / 用户 / API Key / UI 风格**：`.cursor/skills/numen-web-admin-features/SKILL.md`（对应 `docs/前端框架标准.md`）
- **版本号与 Git / 发版**：`.cursor/skills/numen-web-versioning/SKILL.md`（对应 `docs/版本标准.md`）

详细约定与设计见上方 [文档导航](#文档导航)。

## 许可证

MIT，见 `LICENSE`。