<!-- OPENSPEC:START -->
# OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open `@/openspec/AGENTS.md` when the request:
- Mentions planning or proposals (words like proposal, spec, change, plan)
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- Sounds ambiguous and you need the authoritative spec before coding

Use `@/openspec/AGENTS.md` to learn:
- How to create and apply change proposals
- Spec format and conventions
- Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

<!-- OPENSPEC:END -->

# 项目约束：发布/打包流程（强制）

以后只要涉及“发布 / 打包 / 上线 / 部署”，默认目标产物必须生成到 `deploy_bundle/`（无需用户再次强调）。

## 一键口径

- **发布前**：`npm ci` → `npm run check` → `npm test`
- **构建**：`npm run build`（包含：`vite build` + `scripts/build-api.mjs` + `postbuild` 复制 `init.sql`）
- **产物**：同步到 `deploy_bundle/`（见下方“产物映射”）

## 产物映射（从仓库根目录执行）

构建完成后，仓库根目录的 `dist/` 同时包含：
- 前端静态资源：`dist/index.html`、`dist/assets/`、`dist/favicon.svg` 等
- 后端产物：`dist/api/server.js`、`dist/api/server.js.map`、`dist/api/database/init.sql`

发布时必须把它们整理为：

- `deploy_bundle/web/`：放“前端静态资源”（复制 `dist/` 下除 `api/` 之外的所有内容）
- `deploy_bundle/server/`：放“后端可运行目录”
	- `deploy_bundle/server/dist/api/`：复制整个 `dist/api/`
	- `deploy_bundle/server/package.json`、`deploy_bundle/server/package-lock.json`：与根目录依赖保持同步
	- `deploy_bundle/server/ecosystem.config.cjs`：PM2 配置（通常无需改动，按环境变量/路径调整）

## 服务器侧部署（默认 PM2）

- 将 `deploy_bundle/server/` 上传/同步到服务器运行目录（由 `ecosystem.config.cjs` 的 `cwd` 决定）
- 在服务器运行目录执行：`npm ci --omit=dev`
- 启动/重启：`pm2 start ecosystem.config.cjs` 或 `pm2 reload ecosystem.config.cjs`

## 发布注意事项（必须检查）

- Node 版本与构建目标一致（当前后端构建目标：Node 20）
- 数据库文件是外置持久化（由 `DB_PATH` 指定），发布不覆盖 DB 文件
- 构建后确认 `deploy_bundle/server/dist/api/database/init.sql` 存在（用于首次初始化/新环境）