# <<project_name>>

这是一份由 `scafgen` 生成的现代 Vue 3 前端应用骨架。

## 技术栈 (Tech Stack)

- **Framework:** Vue 3 (Composition API / `<script setup>`)
- **Build Tool:** Vite
- **Language:** TypeScript
- **Styling:** Tailwind CSS (v3)
- **Routing:** Vue Router 4
- **State Management:** Pinia 2

## 环境要求 (Prerequisites)

- Node.js (>= 18.x)
- pnpm (>= 8.x) - _推荐使用的包管理器_

## 开发流程 (Development)

1. **安装依赖 (Install Dependencies):**

   ```bash
   pnpm install
   ```

2. **启动本地开发服务器 (Start Dev Server):**

   ```bash
   pnpm dev
   ```

3. **构建生产版本 (Build for Production):**

   ```bash
   pnpm build
   ```

4. **本地预览生产构建 (Preview Production Build):**
   ```bash
   pnpm preview
   ```

## 配置 (Configuration)

开发服务器与 API 地址全部由 `.env` 驱动，**改配置不用改代码**。脚手架已自带一份可直接运行的 `.env`（安全的 localhost 默认值），另有带注释的 `.env.example` 作为参考：

```bash
# 直接编辑 .env，或从示例复制一份
cp .env.example .env
```

`vite.config.ts` 通过 Vite 的 `loadEnv` 读取以下键来配置开发服务器：

| 键 (Key)                 | 作用 (Purpose)                                                          | 默认值 (Default)        |
| ------------------------ | ----------------------------------------------------------------------- | ----------------------- |
| `VITE_DEV_HOST`          | 开发服务器监听地址（`0.0.0.0` 对外暴露 / `127.0.0.1` 仅本机）           | `0.0.0.0`               |
| `VITE_DEV_PORT`          | 开发服务器端口                                                          | `5173`                  |
| `VITE_DEV_ALLOWED_HOSTS` | 允许访问的 Host 列表（逗号分隔；填 `all` 放行任意 Host）                | `localhost,127.0.0.1`   |
| `VITE_API_BASE_URL`      | 应用调用的后端 API 地址，注入客户端 `import.meta.env.VITE_API_BASE_URL` | `http://localhost:8000` |
| `VITE_DEV_PROXY_TARGET`  | 可选：非空时把 `/api` 反向代理到该地址（绕过 CORS），留空禁用           | （空 / empty）          |

- `pnpm dev` 会绑定到 `VITE_DEV_HOST:VITE_DEV_PORT`，并按 `VITE_DEV_ALLOWED_HOSTS` 放行。
- `VITE_API_BASE_URL` 已在 `src/lib/api.ts` 中读取并由 `apiFetch()` 使用，在 `HomeView` 中展示当前值；客户端可见的 `VITE_` 变量类型定义在 `env.d.ts`。
- `.env.local` / `.env.*.local` 已被 `.gitignore` 忽略（个人覆盖），而 `.env` / `.env.example` 默认跟踪，保证克隆即可运行。

## 项目结构 (Project Structure)

- `src/views/` - 页面组件。路由的顶层入口。
- `src/components/` - 可复用的 UI 组件。
- `src/stores/` - Pinia 状态管理模块。
- `src/router/` - Vue Router 配置。
- `src/composables/` - Vue 组合式函数 (如 `useDarkMode`)。
- `src/lib/` - 通用库代码 (如读取 `VITE_API_BASE_URL` 的 `api.ts`)。
- `src/styles/` - 全局样式文件。

## 构建与容器化 (Makefile + Docker)

> 本节内容仅在项目生成时选择了 `--with-build`（或在交互提示"生成配套 Makefile + Dockerfile？"中选择了是）时才会生成。
> 若当前项目没有 `Makefile` / `Dockerfile`，用 `scafgen new <name> --framework vue3 --with-build` 重新生成即可。

Makefile + 多阶段 Dockerfile 由 `scafgen` 自动生成，覆盖从本地构建到容器化的完整流程，
**全部通过 `make` 完成，不依赖 GitHub Actions / CI 平台**。

```bash
make help          # 列出所有可用目标
make build         # 生产构建（pnpm build，输出到 dist/）
make run           # 启动开发服务器（pnpm dev）
make test          # 运行测试
make fmt           # 格式化代码
make lint          # ESLint / 类型检查
make check         # fmt + lint + test（一键本地校验）
make docker-build  # 构建容器镜像（docker build -t <<project_name>>:latest .）
make docker-run    # 运行容器（nginx 静态服务）
```

---

## 推荐工具：CodeGraph (Recommended)

当项目变大、或你用 AI 编程助手时，推荐集成
**[codegraph-rust](https://github.com/sunerpy/codegraph-rust)** 作为代码分析工具：

- 基于 **tree-sitter + SQLite/FTS5** 的确定性代码知识图谱，**不含任何 AI/LLM**，输出字节级稳定。
- 提供符号 / 调用 / 依赖关系图，支持 **CLI 与 MCP server** 两种用法，可直接喂给 AI 编程 Agent。
- **单一二进制、易用、极高性能**：显著提升开发效率，同时大幅降低 token 消耗。
- 接入后 Agent **自动**通过 MCP 探索符号/调用关系，并**自动检测文件变更增量同步**，无需手动维护索引。

在 opencode、Claude、Kiro、Cursor 等支持 MCP 的 AI 编程工具中，只需：

```bash
codegraph install   # 安装并自动接入 opencode / Claude / Kiro / Cursor 等工具的 MCP
```

重启编辑器 / Agent 工具后即自动接入 MCP，Agent 会自动调用 CodeGraph 检索，并在文件变更时自动增量同步（无需手动 sync/explore）。
