Initial commit

Author: YKDZ

.claude/CLAUDE.md

@@ -0,0 +1,88 @@
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`.
+
+## Vite+ Workflow
+
+`vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+### Start
+
+- create - Create a new project from a template
+- migrate - Migrate an existing project to Vite+
+- config - Configure hooks and agent integration
+- staged - Run linters on staged files
+- install (`i`) - Install dependencies
+- env - Manage Node.js versions
+
+### Develop
+
+- dev - Run the development server
+- check - Run format, lint, and TypeScript type checks
+- lint - Lint code
+- fmt - Format code
+- test - Run tests
+
+### Execute
+
+- run - Run monorepo tasks
+- exec - Execute a command from local `node_modules/.bin`
+- dlx - Execute a package binary without installing it as a dependency
+- cache - Manage the task cache
+
+### Build
+
+- build - Build for production
+- pack - Build libraries
+- preview - Preview production build
+
+### Manage Dependencies
+
+Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the `packageManager` field in `package.json` or package manager-specific lockfiles.
+
+- add - Add packages to dependencies
+- remove (`rm`, `un`, `uninstall`) - Remove packages from dependencies
+- update (`up`) - Update packages to latest versions
+- dedupe - Deduplicate dependencies
+- outdated - Check for outdated packages
+- list (`ls`) - List installed packages
+- why (`explain`) - Show why a package is installed
+- info (`view`, `show`) - View package information from the registry
+- link (`ln`) / unlink - Manage local package links
+- pm - Forward a command to the package manager
+
+### Maintain
+
+- upgrade - Update `vp` itself to the latest version
+
+These commands map to their corresponding tools. For example, `vp dev --port 3000` runs Vite's dev server and works the same as Vite. `vp test` runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using `vp --version`. This is useful when researching documentation, features, and bugs.
+
+## Common Pitfalls
+
+- **Using the package manager directly:** Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
+- **Always use Vite commands to run tools:** Don't attempt to run `vp vitest` or `vp oxlint`. They do not exist. Use `vp test` and `vp lint` instead.
+- **Running scripts:** Vite+ built-in commands (`vp dev`, `vp build`, `vp test`, etc.) always run the Vite+ built-in tool, not any `package.json` script of the same name. To run a custom script that shares a name with a built-in command, use `vp run <script>`. For example, if you have a custom `dev` script that runs multiple services concurrently, run it with `vp run dev`, not `vp dev` (which always starts Vite's dev server).
+- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly:** Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
+- **Use Vite+ wrappers for one-off binaries:** Use `vp dlx` instead of package-manager-specific `dlx`/`npx` commands.
+- **Import JavaScript modules from `vite-plus`:** Instead of importing from `vite` or `vitest`, all modules should be imported from the project's `vite-plus` dependency. For example, `import { defineConfig } from 'vite-plus';` or `import { expect, test, vi } from 'vite-plus/test';`. You must not install `vitest` to import test utilities.
+- **Type-Aware Linting:** There is no need to install `oxlint-tsgolint`, `vp lint --type-aware` works out of the box.
+
+## CI Integration
+
+For GitHub Actions, consider using [`voidzero-dev/setup-vp`](https://github.com/voidzero-dev/setup-vp) to replace separate `actions/setup-node`, package-manager setup, cache, and install steps with a single action.
+
+```yaml
+- uses: voidzero-dev/setup-vp@v1
+  with:
+    cache: true
+- run: vp check
+- run: vp test
+```
+
+## Review Checklist for Agents
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to validate changes.
+<!--VITE PLUS END-->

.claude/rules/component.md

@@ -0,0 +1,21 @@
+---
+description: Guidelines for creating and modifying Vue components.
+paths: ["**/*.{vue}"]
+---
+
+# Vue Components
+
+## Reuse
+
+Most native HTML elements (`<table>`, `<input>`, `<button>`, `<textarea>`, etc.) have shadcn-vue replacements. Always use the shadcn-vue equivalents instead of raw HTML elements; only fall back to native elements when absolutely necessary.
+
+When creating a new component (especially a reusable one), always check shadcn-vue first for an equivalent component (install it via tooling if needed). If shadcn-vue does not provide one, check reka-ui next and apply custom styles on top. Only build a component from scratch (placed in `components/`) as a last resort.
+
+## Modification
+
+Never modify the source code of components under `components/ui/` (i.e. shadcn-vue components). Override styles at the usage site with `:deep` selectors. For behavioral changes, prefer creating a wrapper component.
+
+## Placement
+
+- **Page-specific components**: Components with no reuse value should NOT be placed in `components/`. Instead, co-locate them alongside the `+Page.vue` or `+Layout.vue` that uses them inside the `pages/` directory.
+- **`components/ui/` is reserved for shadcn-vue**: Never place custom components in `components/ui/`. Only shadcn-vue generated components belong there.

.claude/rules/css.md

@@ -0,0 +1,57 @@
+---
+description: Styling guidelines for Vue components emphasizing Tailwind CSS v4 utility-first approach.
+paths: ["**/*.{vue,css,scss,sass,less}"]
+---
+
+# Vue Component Styling Guidelines (Tailwind CSS v4)
+
+## 1. Utility-First Preference
+
+- **Template-Driven Styling:** You **must** prioritize styling elements directly in the `<template>` using Tailwind CSS v4 utility classes.
+- **Avoid Style Blocks:** Do not create a `<style>` block unless the styling requirements cannot be reasonably achieved using inline utility classes in the template.
+
+## 2. Managing Vue-Specific Selectors
+
+- **Scoped Styling for Internals:** When you need to style deeply nested child components or injected slot content using Vue's specific pseudo-classes (`:deep()`, `:slotted()`, `:global()`), you are permitted to use a `<style scoped>` block.
+
+## 3. Use of `@apply` and Native CSS
+
+- **Prefer Tailwind utilities in `<template>`.**
+- **Scoped `<style>` blocks:** Use `@apply` for deep selectors only if your Tailwind config and main CSS do not break build (see below).
+- **Compatibility warning:** If your main CSS (e.g. `tailwind.css`) contains `@apply` rules, using `@reference` in scoped styles may cause build errors (e.g. `Cannot apply unknown utility class 'border-border'`).
+- **Fallback:** If `@apply` fails in scoped styles, use native CSS properties instead.
+
+**Example:**
+
+```vue
+<template>
+  <div class="p-4 bg-white rounded-xl shadow-md">
+    <button class="px-4 py-2 text-white bg-blue-500 rounded hover:bg-blue-600">
+      Toggle
+    </button>
+    <ChildComponent class="custom-wrapper" />
+  </div>
+</template>
+
+<style scoped>
+/* Prefer @apply, but use native CSS if build fails */
+.custom-wrapper :deep(.child-inner-element) {
+  /* @apply flex items-center justify-between p-2 mt-4 bg-gray-50 rounded-lg hover:bg-gray-100 transition-colors; */
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem;
+  margin-top: 1rem;
+  background-color: #f8fafc;
+  border-radius: 0.5rem;
+  transition: background-color 0.2s;
+}
+</style>
+```
+
+## 4. Exceptional Cases for Native CSS
+
+- Use native CSS only for:
+  - Complex custom animations
+  - Dynamic `calc()` with injected variables
+  - CSS features not supported by Tailwind

.claude/rules/i18n.md

@@ -0,0 +1,50 @@
+---
+description: Internationalization (i18n) coding guidelines for Vue components.
+paths: ["**/*.{vue,ts}"]
+---
+
+# Vue-i18n Coding Guidelines
+
+## 1. Mandatory i18n Usage
+
+- **No Hardcoded Strings:** **Never** hardcode user-facing text (Chinese or otherwise) directly into the `<template>` or `<script setup>`. All display text must be processed through the `vue-i18n` API.
+
+## 2. Setup & Initialization
+
+- **Import Requirement:** Always import `useI18n` from `vue-i18n` in the script block.
+- **Instantiation:** Initialize the translation function at the top level of `<script setup lang="ts">`.
+
+```typescript
+import { useI18n } from "vue-i18n";
+const { t } = useI18n();
+```
+
+## 3. Translation Key Convention
+
+- **Natural Language Base (Chinese):** Use the exact Chinese display text as the translation key. Do not use abstract dot-notation keys unless explicitly required by a specific module.
+- ✅ **Correct:** `t("概念模式")`, `t("上一页")`
+- ❌ **Incorrect:** `t("glossary.conceptMode")`, `t("pagination.prev")`
+
+## 4. String Interpolation & Formatting
+
+- **Named Variables:** Use curly braces `{}` for dynamic variables within the translation string.
+- **Data Object:** Pass the variables as an object in the second argument of the `t()` function.
+- ✅ **Correct:** `t("{amount} 个术语", { amount: concept.termCount })`
+- ✅ **Correct (Math/Logic):** `t("显示 {from} - {to} 条，共 {total} 条", { from: pageIndex * pageSize + 1, to: Math.min((pageIndex + 1) * pageSize, total), total: total })`
+
+## 5. Attribute & Prop Localization
+
+- **Dynamic Binding:** When localizing HTML attributes (like `title`, `placeholder`, `alt`) or component props, you must use `v-bind` (e.g., `:title`) and execute the `t()` function.
+- **Nested Translations:** If the variables themselves need translation (e.g., dynamic statuses or types), wrap them in `t()` before passing them into the main translation string's data object.
+- ✅ **Correct:**
+
+```vue
+:title="t('类型：{type} | 状态：{status}', { type: t(termItem.type), status:
+t(termItem.status) })"
+```
+
+## 6. Fallback & Conditional Rendering
+
+- **Inline Fallbacks:** When dealing with potentially undefined data that requires a localized fallback, combine the logical OR `||` operator with `t()`.
+- ✅ **Correct:** `{{ concept.definition || t("—") }}`
+- ✅ **Correct:** `{{ concept.subject || t("（未命名）") }}`

.claude/rules/type-safety.md

@@ -0,0 +1,22 @@
+---
+description: Project context and coding guidelines for AI to follow when generating code or answering questions.
+paths: ["**/*.{ts,vue,js}"]
+---
+
+# Function Syntax Preference
+
+- **Arrow Functions Only:** **Never** generate `function` declarations or expressions. Always default to arrow functions.
+- **Exceptions:** If you firmly believe `function` is strictly required (e.g., for generator functions or specific `this` binding contexts):
+  1.  Stop and re-evaluate the design.
+  2.  Attempt a structural rewrite using arrow functions.
+  3.  Only proceed with `function` if JavaScript/TypeScript semantics make arrow functions impossible.
+  4.  **Mandatory:** You must annotate the reason explicitly in a comment alongside the generated `function`.
+
+# Type Safety Restrictions
+
+- **No Explicit `any`:** **Never** use the explicit `any` type or unsafe type assertions (e.g., `as any`, `as unknown as T`). Strict type safety is mandatory.
+- **Exceptions:** If you believe `any` or an unsafe cast is unavoidable:
+  1.  Stop and re-evaluate the type definitions.
+  2.  Attempt to use `unknown`, generics, or proper type narrowing/guards.
+  3.  Only proceed if external library types are inherently broken or strictly demand it.
+  4.  **Mandatory:** You must annotate the reason explicitly in a comment explaining why a safe type cannot be used.

.devcontainer/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:24-bookworm
+
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+ENV SHELL=/bin/bash
+
+RUN corepack enable
+
+ENV PNPM_HOME="/root/.local/share/pnpm"
+ENV PATH="${PNPM_HOME}:${PATH}"
+
+RUN pnpm setup \
+    && pnpm add --global nx
+
+RUN curl -fsSL https://vite.plus | bash

.devcontainer/devcontainer.json

@@ -0,0 +1,67 @@
+{
+  "name": "HRecipe",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": false,
+      "installOhMyZsh": false,
+      "installOhMyZshConfig": false,
+      "upgradePackages": true,
+      "installSsl": true,
+      "username": "automatic",
+      "userUid": "automatic",
+      "userGid": "automatic"
+    },
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+      "moby": true,
+      "installDockerBuildx": true,
+      "installDockerComposeSwitch": true,
+      "version": "latest",
+      "dockerDashComposeVersion": "v2"
+    },
+    "ghcr.io/devcontainers/features/git-lfs:1": {
+      "autoPull": true,
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "installDirectlyFromGitHubRelease": true,
+      "version": "latest"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "Selemondev.shadcn-vue",
+        "nrwl.angular-console",
+        "antfu.iconify",
+        "Vue.volar",
+        "bradlc.vscode-tailwindcss",
+        "ms-playwright.playwright",
+        "oxc.oxc-vscode",
+        "GitHub.copilot-chat",
+        "ms-azuretools.vscode-docker",
+        "ms-azuretools.vscode-containers",
+        "vitest.explorer",
+        "VoidZero.vite-plus-extension-pack"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "oxc.oxc-vscode",
+        "[json]": {
+          "editor.defaultFormatter": "oxc.oxc-vscode"
+        },
+        "[jsonc]": {
+          "editor.defaultFormatter": "oxc.oxc-vscode"
+        },
+        "editor.codeActionsOnSave": {
+          "source.fixAll.oxc": "always"
+        }
+      }
+    }
+  },
+  "remoteUser": "root",
+  "postCreateCommand": "pnpm install",
+  "forwardPorts": []
+}

.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+.git
+.env
+*.db
+data/
+.agents
+.claude
+.devcontainer
+.github
+.pnpm-store
+.vscode
+uploads/

.env

@@ -0,0 +1,31 @@
+# SQLite database file path (absolute or relative to the working directory). Default: ./data/recipes.db
+# SQLite 数据库文件路径（绝对路径或相对于工作目录的相对路径）。默认：./data/recipes.db
+DATABASE_URL=./data/recipes.db
+# Directory for user-uploaded files (absolute or relative to the working directory). Default: ./data/uploads
+# 用户上传文件的储存目录（绝对路径或相对于工作目录的相对路径）。默认：./data/uploads
+UPLOAD_DIR=./data/uploads
+# Maximum upload file size in bytes. Default: 52428800 (50 MB)
+# 上传文件的最大大小（单位：字节）。默认：52428800（50 MB）
+MAX_FILE_SIZE=52428800
+
+# Title of the application, displayed in the header and page title. Default: HRecipe
+# 应用的标题，显示在页面标题和 Header 中。默认：HRecipe
+TITLE=HRecipe
+
+# Whether to enable reviews for recipes. Default: true
+# 是否启用食谱评论功能。默认：true
+REVIEWS_ENABLED=true
+
+# Fallback locale when the user's browser language is not supported. Default: zh-CN
+# 当用户的浏览器语言不受支持时使用的回退语言。默认：zh-CN
+FALLBACK_LOCALE=zh-CN
+# Whether to hide the language switcher in the header (true = infer language from browser only). Default: false
+# 是否隐藏前端 Header 中的语言切换器（设为 true 则仅从浏览器环境推断语言）。默认：false
+HIDE_LANGUAGE_SWITCHER=false
+# Whether to lock the app language to FALLBACK_LOCALE (true = ignore browser language entirely). Default: false
+# 是否将应用语言固定为 FALLBACK_LOCALE 指定的语言（设为 true 则完全忽略浏览器语言）。默认：false
+FORCE_FALLBACK_LOCALE=false
+
+# Port the application listens on. Default: 3000
+# 应用监听的端口。默认：3000
+PORT=3000