inkreach-official-website/apps/website/AGENTS.md

AGENTS.md - AI Agent 开发规范

项目概述

InkReach 官网项目，基于 Nuxt 4 + Vue 3 + Tailwind CSS v4 的静态展示站点。

开发流程

• 包管理器：npm
• TypeScript strict 模式，所有代码必须通过类型检查
• 页面与组件代码放在 app/ 目录下，符合 Nuxt 约定

1. 梳理需求

开发前确定好需求类型，在对应的 plans/ 子目录下创建计划文档：

需求类型	计划目录	命名规则	示例
新功能	plans/feature/	xxx-xxx-feature.md	hero-banner-feature.md
修 Bug	plans/fix/	xxx-xxx-fix.md	layout-overflow-fix.md
重构	plans/refactor/	xxx-xxx-refactor.md	component-split-refactor.md

计划文档最末尾是开发任务表，每个任务项都有一个对应的二级标题的任务详情描述；当需求完成时任务项也标记勾选了。

2. 建立开发分支

使用 enterprise-git-spec 技能来建立分支。分支命名：

• 新功能：feature/xxx-xxx
• 修 Bug：bugfix/xxx-xxx
• 重构：refactor/xxx-xxx

3. 按照需求开发

按照计划文档的任务项逐步实现功能。

重要原则：所有测试必须通过

• 开发过程中，确保所有测试用例通过
• 如果发现现有测试失败，必须立即修复
• 只有在所有测试都通过的情况下，才能认为开发完成

4. 合并到开发分支

所有测试通过后，使用 enterprise-git-spec 技能提交分支，然后合并回 develop 分支。

5. 沉淀开发经验

实现功能过程中，将通用的编码好想法、好思想、注意点等及时追加到本文件中。

6. 更新项目结构文档

每次功能开发完成后，更新 docs/references/structs.md 文件，记录项目目录结构和模块功能描述。

7. 更新使用文档

1. README.md - 快速上手，新功能开发完成后更新
2. docs/references/* - 详细使用指南，每次功能变更后更新
3. skills/inkreach-official-website/SKILL.md - AI Agent 使用文档

技术栈

技术	版本	用途
Nuxt	4.x	SSR/SSG 框架
Vue	3.x	UI 框架
Tailwind CSS	4.x	原子化 CSS
@nuxtjs/seo	5.x	SEO 模块
FontAwesome	7.x	图标库

开发规范

Vue / Nuxt 规范

• 使用 <script setup> + Composition API + TypeScript
• 组件文件命名：PascalCase（如 ProductCard.vue）
• 页面放在 app/pages/，组件放在 app/components/
• 布局放在 app/layouts/
• 使用 Nuxt 自动导入，无需手动 import 组件和 composables

代码风格

• 缩进：2 空格
• 分号：必须
• 引号：单引号
• 行宽：100 字符
• 末尾逗号：es5

TypeScript 规范

• 所有函数必须声明参数和返回值类型
• 优先使用 interface，交叉类型时用 type
• 避免使用 any，必须使用时用 unknown 替代

Tailwind CSS 规范

• 自定义主题颜色在 app/assets/css/tailwind.css 的 @theme 中定义
• 自定义动画也在 @theme 中通过 --animate-* 和 @keyframes 注册
• 优先使用 Tailwind 工具类，必要时使用 @apply 或 [任意值] 语法

现有主题色

变量名	色值	用途
--color-primary	#fd6a03	主色调
--color-inkreach-homepage-1	#f3f4f5	浅灰背景
--color-inkreach-homepage-2	#f8f9fb	次浅灰背景
--color-inkreach-homepage-3	#fff6f0	暖色浅背景
--color-inkreach-homepage-4	#FF6800	橙色强调
--color-inkreach-homepage-5	#0C0501	深色/页脚

常用命令

npm run dev        # 开发模式（nuxt dev --host）
npm run build      # 构建（nuxt build）
npm run generate   # 静态站点生成（nuxt generate）
npm run preview    # 预览构建产物

经验沉淀

启用 Nuxt 文件式路由

项目原先用 app/app.vue 作为整页入口。要新增独立路由页（如 /product-center）：

1. 把 app/app.vue 现有内容迁移到 app/pages/index.vue（保持 / 渲染原首页）。

2. 将 app/app.vue 替换为最小容器：

   <template>
     <NuxtPage />
   </template>
   

3. 新建 app/pages/<name>.vue 即可通过 /<name> 访问。

Nitro 后端代理模式

若要把外部 HTTP API（如 NestJS 后端）包装为同源 /api/* 路由：

// server/api/backend/categories.get.ts
export default defineCachedEventHandler(
  async (event) => {
    const config = useRuntimeConfig();
    return $fetch(`${config.public.backendUrl}/public/categories`);
  },
  {
    maxAge: 60,
    swr: true,
    name: 'backend-categories',
    getKey: () => 'tree',
  },
);

runtimeConfig.public.backendUrl 通过 .env 的 NUXT_PUBLIC_BACKEND_URL 注入，可被前端直接 $fetch('/api/backend/...') 调用且保持 SSR 工作。

注意：带 query 的列表接口（如 goods）需在 getKey 中将 getQuery(event) JSON 序列化作为缓存键，避免不同筛选条件互相污染。

后端响应包络

NestJS 全局 TransformInterceptor 把所有响应包成 { data: T, success: true }。前端 $fetch 必须读取 response.data，类型定义也要带 BackendEnvelope<T> 包装层。

defineModel 用于组件 v-model

Nuxt 4 内置 defineModel 支持双向绑定，比手写 modelValue/update:modelValue props+emit 更简洁：

const keyword = defineModel<string>('keyword', { default: '' });
const emit = defineEmits<{ search: [] }>();

父组件用法：<ProductFilterBar v-model:keyword="searchKeyword" @search="onSearch" />

SSR 期间 watch query 触发请求

在 <script setup> 中用 await loadFilters() 等顶层 await 时，Nuxt 会等待 Promise 解析才渲染首屏 HTML；之后用 watch(() => [query.countryId, ...], fetchProducts) 监听筛选条件变化，重新拉取数据。Top-level await 在 Nuxt 中是合法的（会变为异步 setup）。

npm install 与 node_modules

首次 clone 项目后必须 npm install 安装依赖（项目使用 package-lock.json），否则 node_modules 为空。npm install 会自动触发 postinstall: nuxt prepare 生成 .nuxt/ 类型与组件清单。

类型检查

项目使用 Nuxt 4 默认的 TS 配置（.nuxt/tsconfig.app.json 等）。运行类型检查：

npx vue-tsc --noEmit -p ./.nuxt/tsconfig.app.json

退出码 0 表示无类型错误，可作为合并前的本地验证步骤。