# <<project_name>>

一份由 `scafgen`（[scaffold-gen](https://github.com/sunerpy/scaffold-gen)）生成的现代 **React + TypeScript + Vite** 前端应用骨架。

> 本项目由 scaffold-gen **内嵌模板离线生成**：不联网、不依赖 `pnpm create vite` 等外部脚手架，结果字节级可复现。生成时若检测到 `pnpm` 会自动执行一次 `pnpm install`；未检测到 `pnpm` 则会提示你手动安装，产物依旧完整可用。

## 技术栈 (Tech Stack)

- **Framework:** React 18 (Function Components + Hooks)
- **Build Tool:** Vite 5
- **Language:** TypeScript
- **Styling:** Tailwind CSS (v3, `darkMode: 'class'`)
- **Routing:** React Router 6 (`createBrowserRouter`)
- **State Management:** Zustand

## 必要工具 (Requirements)

- **Node.js 18+**
- **pnpm**（安装：`npm install -g pnpm`，或参见 https://pnpm.io/installation）

## 使用方法 (Usage)

```bash
# 1. 安装依赖（生成时若检测到 pnpm 已自动执行；无 pnpm 时请手动运行）
pnpm install

# 2. 启动开发服务器（热重载）
pnpm dev

# 3. 生产构建（输出到 dist/）
pnpm build

# 4. 预览生产构建
pnpm preview
```

## .env 驱动配置 (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_DEV_ALLOWED_HOSTS=all` 放行任意 Host。
- `VITE_API_BASE_URL` 已在 `src/lib/api.ts` 中读取并由 `apiFetch()` 使用，`HomePage` 会展示当前值；客户端可见的 `VITE_` 变量类型定义在 `env.d.ts`。
- `.env.local` / `.env.*.local` 已被 `.gitignore` 忽略（个人覆盖），而 `.env` / `.env.example` 默认跟踪，保证克隆即可运行。

## 项目结构 (Project Structure)

下面的结构与脚手架实际生成的产物一致：

```
<<project_name>>/
├── index.html              # HTML 入口（挂载点 + 加载 /src/main.tsx）
├── package.json            # 依赖与脚本（pnpm 管理，版本已锁定）
├── vite.config.ts          # Vite 配置（读取 .env：host/port/allowedHosts/proxy）
├── tailwind.config.ts      # Tailwind CSS v3 配置（darkMode: 'class'）
├── postcss.config.js       # PostCSS（tailwindcss + autoprefixer）
├── tsconfig.json           # TypeScript 配置（应用）
├── tsconfig.node.json      # TypeScript 配置（vite.config 用）
├── env.d.ts                # Vite 客户端环境变量类型声明（VITE_API_BASE_URL）
├── .env                    # 本地开发配置（可直接运行，被 git 跟踪）
├── .env.example            # 配置示例（带注释的参考版）
├── .gitignore              # 忽略 .env.local / .env.*.local、node_modules、dist 等
└── src/
    ├── main.tsx            # 应用入口（createRoot + RouterProvider）
    ├── App.tsx             # 根布局组件（导航 + <Outlet /> + 暗色切换）
    ├── router/
    │   └── index.tsx       # 路由配置（createBrowserRouter，React Router）
    ├── store/
    │   └── counter.ts      # 状态管理（Zustand，单数目录）
    ├── pages/
    │   ├── HomePage.tsx    # 首页（展示 API_BASE_URL + counter）
    │   └── AboutPage.tsx   # 关于页
    ├── lib/
    │   └── api.ts          # API 封装（读取 import.meta.env.VITE_API_BASE_URL）
    ├── hooks/
    │   └── useDarkMode.ts  # 暗色模式 Hook（切换 documentElement 的 .dark 类）
    ├── components/
    │   └── Skeleton.tsx    # 骨架屏组件（依赖 utils/cn）
    ├── styles/
    │   └── index.css       # 全局样式（Tailwind 指令 + .dark 变体 + primary 色）
    └── utils/
        └── cn.ts           # className 合并工具（clsx + tailwind-merge）
```

> React 命名约定：使用 `src/hooks/`（非 `composables/`）、`src/store/`（单数）、`src/pages/`（非 `views/`）、`src/styles/index.css`（非 `main.css`）。

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

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