# Hile + Next.js

基于 [Hile](https://github.com/cevio/hile) 与 Next.js 的全栈项目。API 路由（`/-` 前缀）与页面路由共享同一端口。

## 快速开始

```bash
pnpm install
pnpm run dev
```

浏览器打开 [http://localhost:3000](http://localhost:3000)。示例 API：`curl http://localhost:3000/-/post`。

## 全局 CLI `zlooks`（可选）

安装本包后可用 `zlooks` 命令；生产构建的 Next 产物固定在 **`~/.zlooks/.next`**（由 **`zlooks compile`** 写入；与仓库内可选的 **`pnpm run build:next`** 写入包根 `.next` 不同）。

推荐顺序：

1. **`zlooks setup`** — 初始化 `~/.zlooks`：写入 **`.env`**，并创建或补齐 **`package.json`**（`name: zlooks-workspace`、`dependencies` / **`devDependencies`** 与根级 **`zlooks`** 插件清单占位，供后续 `zlooks plugins` 与 `next.config` 读取）
2. **`zlooks compile`** — 在包安装根执行 `next build`，产物写入 `~/.zlooks/.next`
3. **`zlooks start`** — 启动服务（若缺少 `~/.zlooks/.next/BUILD_ID` 会提示先执行 `compile`）

**插件（实现后）**：**`zlooks plugins install <registry 包名>`** → **`dependencies`**；**`zlooks plugins install <本地文件夹路径> --dev`** → 仅开发嵌入，**`devDependencies`**（**`file:`**），包名以该目录 **`package.json#name`** 为准。见 [`docs/superpowers/specs/2026-04-22-zlooks-plugins-protocol-design.md`](docs/superpowers/specs/2026-04-22-zlooks-plugins-protocol-design.md) §5.1。

## 发布到 npm

- **`package.json` 的 `files`**： tarball 含 `dist`、`src`、`public/**/*`（**显式排除** `public/uploads/**`，用户上传不落 npm 包）、Next/TS 根配置与 `README.md`；**不包含** `next-env.d.ts`（由本机 `next dev` / `next build` / `zlooks compile` 自动生成）、**不包含** 根目录 `.next`（安装后由 **`zlooks compile`** 写入 `~/.zlooks/.next`）。
- **`prepublishOnly`**：发布前自动执行 **`pnpm run build:base`**（生成 `dist/`，含 CLI 与 Hile 侧编译产物）。
- **发布前自检（推荐）**：在仓库根执行 **`pnpm run release:verify`**（`tsc` + `build:base` + `build:next`，确认整站可构建）。
- **打包预览**：`npm pack --dry-run` 查看将打进包的文件列表（pnpm 的 `pack` 无 `--dry-run` 时可用此命令）。

## 常用命令

| 命令 | 说明 |
|------|------|
| `pnpm run dev` | 构建 Next.js 并以开发模式启动 Hile 服务 |
| `pnpm run build` | 仅编译 **Hile 侧**（`tsc` → `dist/`，含 `zlooks` CLI）；**不包含** Next 生产构建 |
| `pnpm run build:next` | 可选：在包根生成 **`.next`**（本地/CI 验证 Next 能否通过 `next build`） |
| `pnpm run release:verify` | 发布前自检：`tsc` + `build:base` + `build:next`（整站可构建） |
| `pnpm run start` | 生产模式启动：若走全局 **`zlooks start`**，需先 **`zlooks compile`**；若坚持仓库内 `pnpm run start` 且读包根 `.next`，需先 **`pnpm run build:next`** |

## 项目结构

```
src/
├── app/                 # Next.js App Router（禁止 loadService / defineModel）
├── controllers/         # *.controller.ts → 默认 GET /-/…（可 loadService / loadModel）
├── models/              # <领域>/*.model.ts：单文件 export default defineModel
└── services/            # *.boot.ts | *.service.ts（*.boot 由 CLI 自启动）
```

- **`src/services/index.boot.ts`**：`HttpNext` 与 **`cwd`**（见 **`packages/http-next/SKILL.md`**）。
- **`src/models/<领域>/*.model.ts`**：领域数据；**`src/app/page.tsx`** 示范 **`loadModel`** + **`export const dynamic = "force-dynamic"`**（凡 **`page.tsx`** 使用 **`loadModel`** 时强制）。
- **`src/controllers/post.controller.ts`**：示范 **`loadModel(postModel, …)`**。

**`loadService`** 仅可在 **`src/services`**、**`src/models`**、**`src/controllers`** 中使用，**禁止**在 **`src/app`**。

详见 **`packages/http-next/SKILL.md`** 与 [Hile 文档](https://pulian.mintlify.app/packages/http-next)。
