create-next-imagicma 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-next-imagicma",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "bin": {
     "create-next-imagicma": "./bin/create-next-imagicma.mjs"

package/template-hono/.env.example

@@ -1,5 +1,18 @@
 # 复制为 .env.local 后按需覆盖（.env.local 不会被提交）
 #
-# 可选：自定义 SQLite 文件位置；默认使用 ./.data/app.db
-# DATABASE_FILE="./.data/app.db"
-
+# 必填：PostgreSQL 连接串
+# DATABASE_URL="postgresql://postgres:password@127.0.0.1:5432/hono_app"
+#
+# AI 网关配置
+# 可选：提供商，支持 openai / openai-compatible / minimax / kimi
+# AI_PROVIDER="minimax"
+# 必填：模型访问密钥
+# AI_API_KEY="<your-api-key>"
+# 可选：自定义网关地址；minimax / kimi 留空时会自动使用官方兼容地址
+# AI_BASE_URL="https://api.minimaxi.com/v1"
+# 可选：模型 ID；未设置时默认 gpt-4o-mini
+# AI_MODEL="MiniMax-M2.7"
+#
+# 兼容旧变量名：
+# OPENAI_API_KEY="<your-api-key>"
+# OPENAI_BASE_URL="https://api.openai.com/v1"

package/template-hono/AGENTS.md

@@ -2,17 +2,51 @@
 
 ## Project Structure & Module Organization
 
-This is a `Hono + Vite + React` app. Keep browser code in `client/src`, server entrypoints in `server/`, and shared contracts in `shared/`.
-
-- `client/src/pages/`: route-level pages such as `home.tsx`
-- `client/src/components/`: reusable UI, with shadcn/ui primitives under `components/ui/`
-- `client/src/lib/` and `client/src/hooks/`: client utilities and hooks
-- `server/routes/`: Hono route modules
+This is a `Hono + Vite + React` app designed for enterprise-level product development. Keep browser code in `client/src`, server entrypoints in `server/`, and shared contracts in `shared/`.
+
+### Documentation Structure (Design Phase)
+All design artifacts are stored under `docs/designer/`:
+
+- `docs/designer/project_state.json`: project state and version tracking
+- `docs/designer/prd/prd.md`: Product Requirements Document
+- `docs/designer/persona/persona_*.md`: user personas (one file per persona)
+- `docs/designer/feature_plan/`: feature module planning
+  - `feature_modules.md`: module list, relationship diagrams, and shared/common components (may contain full details if ≤4 modules)
+  - `feature_module_[name].md`: detailed module specifications for large apps (pages, layouts, components, business rules, and navigation)
+- `docs/designer/style_guide/*.style-guide.md`: visual design guidelines
+- `docs/designer/db/`: database schema documentation
+  - `db_schema.md`: global ER diagram and module index
+  - `db_schema_[module].md`: per-module database schemas
+
+### Application Code Structure
+- `client/src/pages/`: route-level pages (e.g., `home.tsx`)
+- `client/src/components/`: reusable UI components, with shadcn/ui primitives under `components/ui/`
+- `client/src/lib/` and `client/src/hooks/`: client utilities and custom hooks
+- `client/src/main.tsx`: frontend entry point
+- `client/src/App.tsx`: React Router configuration
+- `client/src/globals.css`: global styles
+- `client/public/`: static assets
+- `server/app.ts`: Hono application entry point
+- `server/routes/`: route registration only; bind paths and hand off to controllers
+- `server/middlewares/`: cross-cutting HTTP middleware such as auth, request-id, logging, and rate-limit
+- `server/controllers/`: HTTP layer; parse requests, call repositories/lib, and map errors to responses
+- `server/repositories/`: data access only; wrap Drizzle/SQL queries
+- `server/db/`: database client and database-level infrastructure
+- `server/lib/`: external integrations and reusable backend helpers
+- `server/env.ts`: environment loading and config validation
 - `shared/routes.ts` and `shared/schema.ts`: Zod-backed API contracts and shared schema
 - `scripts/`: guarded dev/start scripts; do not bypass them
-- `.data/`: local SQLite data; treat as runtime state, not source
+- `.env.local`: local runtime secrets such as `DATABASE_URL`; do not commit it
+
+**Critical**: The homepage must never ship blank. `client/src/pages/home.tsx` should render visible, meaningful content on first load, not hidden placeholders or empty shells.
+
+## Development Preparation
+
+Before starting development, agents must confirm the database connection with the user by using `question`. Ask for the PostgreSQL connection string that should be used locally, for example:
 
-The homepage must never ship blank. `client/src/pages/home.tsx` should render visible, meaningful content on first load, not hidden placeholders or empty shells.
+- `DATABASE_URL="postgresql://postgres:password@127.0.0.1:5432/hono_app"`
+
+Do not assume the database host, port, username, password, or database name. After the user confirms the value, place it in `.env.local` (or ensure it is already available in the environment) before running database-related work such as `pnpm db:push`, server development, or any feature that depends on persistence.
 
 ## Build, Test, and Development Commands
 
@@ -21,24 +55,65 @@ The homepage must never ship blank. `client/src/pages/home.tsx` should render vi
 - `pnpm start`: runs the production server through the guarded startup script
 - `pnpm check`: TypeScript type-check for both client and server configs
 - `pnpm lint`: runs ESLint across the repository
-- `pnpm db:push`: applies Drizzle schema changes to the local SQLite database
+- `pnpm db:push`: applies Drizzle schema changes to the PostgreSQL database from `DATABASE_URL`
+
+### AI Feature Rule
+- If you are developing AI-related features in this template, you must use the `ai-feature` skill before implementation.
 
 ## Coding Style & Naming Conventions
 
 Use TypeScript and ESM throughout. Follow the existing style: 2-space indentation, double quotes, semicolons, and trailing commas. Prefer:
 
-- PascalCase for React components, for example `HelloClient.tsx`
-- kebab-case for route/page files, for example `not-found.tsx`
-- colocated logic in `hooks/`, `lib/`, and `routes/` before creating new top-level folders
+- PascalCase for React components (e.g., `HelloClient.tsx`)
+- kebab-case for route/page files (e.g., `not-found.tsx`)
+- snake_case for database schema files (e.g., `db_schema_user.md`)
+- Colocate logic in `hooks/`, `lib/`, and `routes/` before creating new top-level folders
 
 Reuse the `@/` import alias for client code where it improves readability.
 
-## Testing Guidelines
-
-This template does not currently ship with a committed automated test runner or `pnpm test` script. Before opening a PR, run `pnpm check` and `pnpm lint`, then manually verify the main page and `GET /api/greeting`.
+### Backend Layering Rules
+- Backend request flow must follow `routes -> middlewares -> controllers -> repositories -> db`.
+- `routes/` may define paths and middleware, but must not contain business logic or direct database access.
+- `middlewares/` are for cross-cutting concerns such as auth, request-id, logging, and rate-limit; they may read/write Hono Context and short-circuit requests when needed.
+- Auth-related checks should be implemented as middleware and mounted in `routes/`, not reimplemented inside controllers.
+- `controllers/` may read/write HTTP details, call repositories or `lib/`, and map errors, but must not contain SQL.
+- `repositories/` own database reads/writes only and must not shape HTTP responses.
+- `db/` is limited to connection setup, schema wiring, and database infrastructure helpers.
+- `lib/` is for external providers or shared backend utilities; routes should reach it through middleware or controllers, not directly.
+- Controllers should consume auth context that middleware has already prepared instead of parsing tokens again.
+- New backend features should default to adding files along the same chain: route, middleware when needed, controller, repository.
+- Do not mock backend data for feature development. Implement against real backend flows, real repositories, and real interfaces unless the user explicitly asks for a temporary test double.
+
+### Shared Schema Rules
+- Always split shared schema by business module in `shared/schema/*.ts`, not by individual table.
+- `shared/schema.ts` must remain the unified export entry so existing imports and Drizzle config stay stable.
+- Each schema module should contain the tables, Zod schema exports, and inferred TS types for that module.
+- Avoid one-file-per-table unless the user explicitly asks for it or a single module is exceptionally large.
+
+### Design Documentation Standards
+- All Mermaid diagrams must NOT include styling elements (no style definitions, classDef, linkStyle or fill colors)
+- Use basic graph syntax only: `graph TD`/`graph TB` for architecture, and `erDiagram` for schemas
+- File naming must strictly follow the patterns defined in File Structure section
+
+### Technical Selection Policy
+Technical selection is strictly an engineering responsibility, governed globally:
+- When evaluating complex system requirements (e.g., OCR, Payments, AI integrations, Auth), propose solutions contrasting self-built vs. commercial options.
+- Strip away meaningless basic scaffolding choices; focus squarely on domain-specific system blockers.
+- When human input is mandatory to finalize a route, translate technical jargon into business dimensions for the stakeholders: "Development Time, Cost, and Product Experience".
+- Final architectural decisions must be persisted into `docs/designer/tech_design/tech_design.md`.
+
+## Testing & Quality Assurance
+
+Before opening a PR, complete manual verification to ensure the application is usable end to end.
 
 If you add tests, keep them as `*.test.ts` or `*.test.tsx`, or add a `tests/` folder and document the new command in `package.json`.
 
+### Manual Verification Checklist
+- All API endpoints work correctly
+- All pages are accessible without 404 errors
+- All buttons are clickable and trigger the expected behavior
+- All links navigate to the correct destination
+
 ## Commit & Pull Request Guidelines
 
 Recent history uses Conventional Commit prefixes such as `feat:`, `fix:`, and `chore:`; keep that format and write concise subjects. PRs should include:
@@ -50,4 +125,4 @@ Recent history uses Conventional Commit prefixes such as `feat:`, `fix:`, and `c
 
 ## Runtime & Configuration Notes
 
-Agents must use `restart_workflow` instead of invoking `pnpm dev` manually. Do not pass a port on the command line or by prefixing `pnpm dev` with `PORT=...`; keep runtime port configuration in `.imagicma/runtime.env`. Database defaults to `./.data/app.db`, and overrides belong in `.env.local`, not committed secrets.
+Agents must use `restart_workflow` instead of invoking `pnpm dev` manually. Do not pass a port on the command line or by prefixing `pnpm dev` with `PORT=...`; keep runtime port configuration in `.imagicma/runtime.env`. Database access must come from `DATABASE_URL` in `.env.local` (or process env), and secrets must never be committed.

package/template-hono/README.md

@@ -6,7 +6,8 @@
 
 - 前端：React 19、React Router、Tailwind CSS v4、shadcn/ui、React Query
 - 后端：Hono（Node runtime）
-- 数据层：Drizzle ORM + SQLite（默认 `./.data/app.db`）
+- 数据层：Drizzle ORM + PostgreSQL（默认通过 `DATABASE_URL` 连接）
+- AI 网关：Vercel AI SDK 5（`ai` + `@ai-sdk/openai` + `@ai-sdk/openai-compatible`）
 - 校验契约：Zod（`shared/routes.ts`）
 
 ## 目录结构（重点）
@@ -19,6 +20,24 @@
 - `server/`：Hono 后端入口与路由
 - `shared/`：前后端共享契约与 schema
 
+## AI 网关基础设施
+
+模板已内置最薄的 AI 基础设施，不带默认业务页面：
+
+- 服务端统一入口：`POST /api/ai/chat`
+- 服务端默认架构：Hono API -> Vercel AI SDK -> OpenAI / OpenAI 兼容模型
+- 当前默认支持的小文件附件类型：`image/*`、`text/*`、`application/pdf`
+- 附件限制：最多 3 个文件，总大小不超过 5MB，且必须以内联 data URL 提交
+
+推荐做法：
+
+- 前端页面调用项目内 `/api/ai/chat`
+- 不要把模型密钥暴露到浏览器
+- 需要聊天 UI 时，优先使用 `@ai-sdk/react` 的 `useChat` / `DefaultChatTransport` 对接服务端 UI message stream
+- 如果暂时不引入 `@ai-sdk/react`，请复用 `client/src/lib/ai-ui-stream.ts`，不要手写 SSE 解析器
+- OpenAI 官方走 `AI_PROVIDER=openai`
+- MiniMax / Kimi 这类 OpenAI 兼容供应商，优先走 `AI_PROVIDER=minimax|kimi` 或 `openai-compatible`
+
 ## 开发
 
 ```bash
@@ -54,8 +73,74 @@ PORT=6424
 pnpm db:push
 ```
 
-- 默认数据库文件：`./.data/app.db`
-- 如需自定义位置，可复制 `.env.example` 为 `.env.local` 后设置 `DATABASE_FILE`
+- 请先复制 `.env.example` 为 `.env.local`
+- 在 `.env.local` 中设置 `DATABASE_URL`
+- `pnpm db:push` 会将 schema 推送到该 PostgreSQL 数据库
+
+## AI 配置
+
+请在 `.env.local` 中配置：
+
+- `AI_PROVIDER`：可选；支持 `openai`、`openai-compatible`、`minimax`、`kimi`
+- `AI_API_KEY`：必填
+- `AI_BASE_URL`：可选；接 OpenAI 兼容网关时填写。`minimax` / `kimi` 留空时自动走官方默认地址
+- `AI_MODEL`：可选；默认 `gpt-4o-mini`
+
+兼容说明：
+
+- 旧变量 `OPENAI_API_KEY` / `OPENAI_BASE_URL` 仍然可用，但新项目建议改用通用命名的 `AI_*`
+- `minimax` 与 `kimi` 默认都走 OpenAI 兼容模式，不需要额外改代码
+- 如果接其它兼容供应商，使用 `AI_PROVIDER=openai-compatible` 并填写 `AI_BASE_URL`
+
+模板内置的 AI 路由会优先读取这些环境变量，再由服务端统一调用模型供应商。
+
+补充说明：
+
+- `/api/ai/chat` 返回的是 AI SDK 5 的 UI message stream（SSE `data:` 事件，不是旧的 `0:"..."` 文本流）
+- 如果模型网关不可达，优先检查 `AI_BASE_URL`、网络连通性与服务商侧配置
+
+最小请求示例：
+
+```bash
+curl -N \
+  -X POST http://127.0.0.1:6424/api/ai/chat \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "messages": [
+      {
+        "role": "user",
+        "parts": [
+          { "type": "text", "text": "请用一句话介绍这个项目的 AI 网关职责。" }
+        ]
+      }
+    ]
+  }'
+```
+
+常见配置示例：
+
+```bash
+# OpenAI 官方
+AI_PROVIDER=openai
+AI_API_KEY=<your-openai-key>
+AI_MODEL=gpt-4o-mini
+
+# MiniMax
+AI_PROVIDER=minimax
+AI_API_KEY=<your-minimax-key>
+AI_MODEL=MiniMax-M2.7
+
+# Kimi
+AI_PROVIDER=kimi
+AI_API_KEY=<your-kimi-key>
+AI_MODEL=kimi-k2.5
+
+# 其它 OpenAI 兼容供应商
+AI_PROVIDER=openai-compatible
+AI_API_KEY=<your-provider-key>
+AI_BASE_URL=https://api.provider.com/v1
+AI_MODEL=<provider-model-id>
+```
 
 ## 运行时文件
 
@@ -64,4 +149,5 @@ pnpm db:push
 ## 验证路径
 
 - API：`GET /api/greeting`
+- AI：`POST /api/ai/chat`
 - 页面：`/hello`

package/template-hono/client/src/components/HelloClient.tsx

@@ -62,7 +62,7 @@ function EnvHint() {
   return (
     <div className="text-sm text-muted-foreground">
       <p>
-        默认使用 <code>./.data/app.db</code>。若 API 报错，请先执行 <code>pnpm db:push</code> 初始化 SQLite；需要自定义位置时可在 <code>.env.local</code> 设置 <code>DATABASE_FILE</code>。
+        默认使用 PostgreSQL。若 API 报错，请先在 <code>.env.local</code> 设置 <code>DATABASE_URL</code>，再执行 <code>pnpm db:push</code> 初始化数据库。
       </p>
     </div>
   );