inkreach-official-website/plans/feature/product-center-feature.md

产品中心 (Product Center) Feature Plan

需求描述

为 InkReach 官网新增"产品中心"二级页面，串联三个子系统：

1. NestJS 后端 (inkreach-official-nestjs/)：Prisma + PostgreSQL，提供 Admin RESTful API、Website Public API、SDS 定时同步
2. Vue 3 Admin (inkreach-official-admin/)：Element Plus，管理商品/品类/国家/标签/位置/同步
3. Nuxt 4 官网页 (inkreach-official-website/)：在已有首页基础上新增 /product-center 二级页

实施顺序：后端 → Admin → 官网。所有任务按 TDD 流程开发：先写测试，再写实现，再重构。

架构与端口

项目	端口	直连方式
NestJS Backend	3001	Admin 直连（Vite proxy），Website 通过 Nitro 代理
Admin (Vite dev)	5173	-
Website (Nuxt dev)	3000	-

跨项目环境变量

文件	变量	值
inkreach-official-nestjs/.env	DATABASE_URL	postgresql://postgres:yoyoki219765.@localhost:5432/inkreach-official
inkreach-official-nestjs/.env	JWT_SECRET	随机字符串（运行前生成）
inkreach-official-nestjs/.env	SDS_API_BASE	https://mapi.sdspod.com
inkreach-official-nestjs/.env	PORT	3001
inkreach-official-admin/.env	VITE_API_BASE	http://localhost:3001
inkreach-official-website/.env	NUXT_PUBLIC_BACKEND_URL	http://localhost:3001

任务列表

阶段一：NestJS 后端 (inkreach-official-nestjs/)

• B1: 初始化 NestJS + TypeScript 项目骨架
• B2: 配置 Prisma + 数据库连接
• B3: 编写 Prisma Schema 并执行 initial migration
• B4: 实现 PrismaService 和全局 DatabaseModule
• B5: 实现 Auth 模块（JWT + Guard + 注册/登录）
• B6: 实现 Countries 模块（CRUD + 测试）
• B7: 实现 Categories 模块（树形 CRUD + 测试）
• B8: 实现 Tags 模块（CRUD + 测试）
• B9: 实现 Positions 模块（CRUD + 测试）
• B10: 实现 OriginGoods 模块（只读 + 测试）
• B11: 实现 Goods 模块（CRUD + 批量 + 筛选 + 测试）
• B12: 实现 SDS 同步模块（cron + 手动触发 + 测试）
• B13: 实现 Public API 模块（无需鉴权 + 测试）
• B14: 全局异常过滤器、响应拦截器、CORS
• B15: 启动验证 + Swagger 文档生成

阶段二：Admin 后台 (inkreach-official-admin/)

• A1: 初始化 Vite + Vue 3 + TS + Element Plus
• A2: 配置 Vite proxy、环境变量、Tailwind（可选）
• A3: 建立 Axios 实例与 API 模块层
• A4: 建立 Pinia stores（auth/app）
• A5: 建立路由 + 鉴权守卫
• A6: 实现 LoginView
• A7: 实现 DefaultLayout（侧边栏 + 头部）
• A8: 实现 GoodsView（列表 + 筛选 + 增删改 + 批量添加 + 测试）
• A9: 实现 CategoriesView（树形表格 + 测试）
• A10: 实现 CountriesView（含图标上传/URL + 测试）
• A11: 实现 TagsView（含颜色选择 + 测试）
• A12: 实现 PositionsView（含国家/品类联动 + 测试）
• A13: 实现 SyncView（同步状态 + 手动触发 + 测试）

阶段三：官网产品中心页 (inkreach-official-website/)

• W1: 配置 runtimeConfig 与 .env
• W2: 新增 Nitro 后端代理 routes
• W3: 创建 useProductCenter composable
• W4: 创建 ProductSidebar.vue 组件
• W5: 创建 ProductCountryFilter.vue 组件
• W6: 创建 ProductFilterBar.vue 组件
• W7: 创建 ProductCard.vue 与 ProductCardSkeleton.vue
• W8: 创建 ProductGrid.vue 组件
• W9: 创建 ProductPagination.vue 组件
• W10: 创建 app/pages/product-center.vue 页面 + 启用 Nuxt 路由
• W11: 更新 AppHeader.vue 与 PodProducts.vue 内部跳转链接
• W12: 三断点视觉验证

阶段四：收尾

• F1: 更新根级 docs/references/structs.md（新增 3 子项目结构）
• F2: 更新各子项目 README.md 与 docs/references/* 使用文档
• F3: 更新 skills/[项目名]/SKILL.md
• F4: 全链路联调（后端 + Admin + 官网三端跑通）

---

任务详情

B1: 初始化 NestJS + TypeScript 项目骨架

在 inkreach-official-nestjs/ 目录初始化 NestJS 工程。

操作步骤：

1. npm init 创建 package.json，包名 inkreach-official-nestjs
2. 安装核心依赖：@nestjs/core @nestjs/common @nestjs/platform-express @nestjs/config reflect-metadata rxjs
3. 安装开发依赖：@nestjs/cli @nestjs/testing typescript ts-node tsconfig-paths @types/node jest ts-jest @types/jest supertest @types/supertest
4. 创建配置文件：nest-cli.json、tsconfig.json、tsconfig.build.json、.eslintrc.js、.prettierrc
5. 创建入口文件：src/main.ts 与 src/app.module.ts，监听 process.env.PORT ?? 3001
6. package.json 中加入脚本：start/start:dev/start:debug/build/test/test:e2e/test:cov

验收：npm run start:dev 能启动并监听 3001 端口。

B2: 配置 Prisma + 数据库连接

操作步骤：

1. 安装：prisma @prisma/client（dev: prisma）
2. npx prisma init 初始化 prisma/ 与 .env
3. 在 .env 写入：

   DATABASE_URL=postgresql://postgres:yoyoki219765.@localhost:5432/inkreach-official
   JWT_SECRET=<openssl rand -hex 32 生成>
   SDS_API_BASE=https://mapi.sdspod.com
   PORT=3001
   

4. .gitignore 加入 .env、node_modules、dist
5. 在 app.module.ts 注册 ConfigModule.forRoot({ isGlobal: true })

验收：npx prisma db pull 或 prisma validate 通过。

B3: 编写 Prisma Schema 并执行 initial migration

将 docs/dev/database-table-design.md 的 DDL 翻译为 prisma/schema.prisma，严格保持 6 张表（origin_goods / countries / categories / tags / positions / goods）的字段、外键、删除策略。

关系约束（必须）：

• Good.originGoods → OriginGoods (RESTRICT)
• Good.country → Country (RESTRICT, NOT NULL)
• Good.category → Category (RESTRICT, NOT NULL)
• Good.tag → Tag (SET NULL, optional)
• Good.position → Position (SET NULL, optional)
• Category.parent → Category (RESTRICT, self-relation)
• Position.country → Country (CASCADE)
• Position.category → Category (CASCADE)

字段映射：所有 BIGINT 用 BigInt，TIMESTAMPTZ 用 DateTime @db.Timestamptz(6)，TEXT 用 String。表名通过 @@map("xxx") 映射到 snake_case，字段名同理用 @map。

额外：

• 创建 User 表用于 Admin 登录（id / username UNIQUE / passwordHash / 时间戳）
• 创建 SyncLog 表记录同步历史（id / type enum / status enum / message / startedAt / finishedAt）
• 索引按 DDL 中 CREATE INDEX 创建对应 @@index

操作：

1. 编写 schema
2. npx prisma migrate dev --name init 生成首个 migration
3. npx prisma generate 生成 Client

验收：数据库内 8 张表（6 业务表 + users + sync_logs）正确生成。

B4: 实现 PrismaService 和全局 DatabaseModule

文件：

• src/prisma/prisma.service.ts：继承 PrismaClient，在 onModuleInit 中 $connect()，在 onModuleDestroy 中 $disconnect()
• src/prisma/prisma.module.ts：@Global() + 导出 PrismaService
• 在 app.module.ts 注册 PrismaModule

测试：src/prisma/prisma.service.spec.ts，验证可注入并连接数据库。

B5: 实现 Auth 模块

文件：

• src/auth/auth.module.ts、auth.controller.ts、auth.service.ts
• src/auth/strategies/jwt.strategy.ts、src/auth/guards/jwt-auth.guard.ts
• src/auth/dto/login.dto.ts、register.dto.ts

依赖：@nestjs/jwt @nestjs/passport passport passport-jwt bcrypt class-validator class-transformer

接口：

方法	路径	描述
POST	/auth/register	注册（仅初始化用，可加环境变量门禁）
POST	/auth/login	登录返回 { accessToken, user }

实现要点：

• 密码用 bcrypt hash（rounds=10）
• JWT payload: { sub: userId, username }，过期 7 天
• JwtAuthGuard 默认作用于 Admin 路由

测试 (src/auth/auth.service.spec.ts)：

1. 注册新用户 → 数据库存在记录，密码已 hash
2. 重复用户名 → 抛 ConflictException
3. 登录正确密码 → 返回 token
4. 登录错误密码 → 抛 UnauthorizedException

B6: Countries 模块

文件：src/countries/{countries.module.ts, countries.controller.ts, countries.service.ts, dto/create-country.dto.ts, dto/update-country.dto.ts}

接口：

方法	路径	描述
GET	/countries	列表
POST	/countries	创建 ({ countryName, countryIcon? })
PATCH	/countries/:id	更新
DELETE	/countries/:id	删除（被引用时抛错）

所有路由加 @UseGuards(JwtAuthGuard)。DELETE 在数据库 RESTRICT 抛错时返回 409 Conflict + 友好信息。

测试 (countries.service.spec.ts)：

1. CRUD 正常路径
2. 重名 → ConflictException
3. 被 goods 引用时删除 → 抛 BadRequestException

B7: Categories 模块（树形）

文件：src/categories/{categories.module.ts, ...}

接口：

方法	路径	描述
GET	/categories	返回树形结构（按 parentCategoryId 递归拼接）
GET	/categories/flat	扁平列表（用于下拉选择）
GET	/categories/:id	详情
POST	/categories	创建（parentCategoryId 可空）
PATCH	/categories/:id	更新
DELETE	/categories/:id	删除（含子节点 → 抛错）

树形构建：一次查询所有记录 → 在内存中按 parentCategoryId 分组拼装。

测试：CRUD + 树结构组装 + 删除存在子项时报错。

B8: Tags 模块

文件：src/tags/{tags.module.ts, ...}

接口：GET / POST / PATCH /:id / DELETE /:id（同 Countries）

字段：tagName（唯一）、tagColor（hex 字符串验证 /^#[0-9A-Fa-f]{6}$/）、timing

测试：CRUD + 颜色格式验证。

B9: Positions 模块

文件：src/positions/{positions.module.ts, ...}

接口：GET / POST / PATCH /:id / DELETE /:id

字段：indexVal、countryId (可空)、categoryId (可空)

查询参数：GET /positions?countryId=&categoryId=

测试：CRUD + 联表返回 country/category 名称。

B10: OriginGoods 模块（只读）

文件：src/origin-goods/{origin-goods.module.ts, ...}

接口：

方法	路径	描述
GET	/origin-goods	分页 + 关键词搜索 (page/pageSize/keyword)

只读模块（数据由 SDS 同步生成），无 POST/PATCH/DELETE。

测试：分页 + 关键词搜索。

B11: Goods 模块

文件：src/goods/{goods.module.ts, goods.controller.ts, goods.service.ts, dto/...}

接口：

方法	路径	描述
GET	/goods	分页 + 多维筛选 (countryId/categoryId/tagId/positionId/keyword/page/pageSize)
GET	/goods/:id	详情（含关联 country/category/tag/position/originGoods）
POST	/goods	创建
PATCH	/goods/:id	更新
DELETE	/goods/:id	删除
PATCH	/goods/batch-priority	批量更新优先级 ([{ id, priority }])
POST	/goods/batch	从 origin_goods 批量创建（统一国家/品类/标签/位置/起始优先级）

关键实现：

• 筛选 categoryId 时，递归查出所有子品类 ID，用 IN 查询
• 关键词搜索 goodName 用 contains mode insensitive
• 排序：goodPriority DESC + createdAt DESC
• 关联返回用 Prisma include

测试 (goods.service.spec.ts)：

1. 单个 CRUD
2. 筛选（每种参数）
3. categoryId 包含子品类
4. 批量优先级更新（事务）
5. 批量创建（事务，全成或全败）

B12: SDS 同步模块

文件：src/sync/{sync.module.ts, sync.controller.ts, sync.service.ts, sds-client.service.ts}

依赖：@nestjs/schedule @nestjs/axios axios

SDS Client：复用现网逻辑（参考 inkreach-official-website/server/utils/pod-api.ts）：

const POD_API_BASE = 'https://mapi.sdspod.com';
const POD_HEADERS = {
  'Content-Type': 'application/json;charset=UTF-8',
  'Origin': 'https://inkpod.vip',
  'Referer': 'https://inkpod.vip/',
};

接口：

方法	路径	描述
POST	/sync/categories	手动触发品类同步
POST	/sync/products	手动触发产品同步
GET	/sync/status	最近 N 条 sync_logs

同步逻辑：

1. 品类同步 syncCategories()：调用 POST /category/tree/3 body { withActivityArea:true, withPrivate:true, onlyHaveProduct:true }，递归扁平化结果，按 sdsId 去重写入/更新 categories 表（需扩展 schema 增 sdsCategoryId TEXT UNIQUE 字段，B3 步骤已含）
2. 产品同步 syncProducts()：遍历叶子品类，调用 GET /products/page?categoryId=&page=&size=50，去重写入 origin_goods 表（按 sdsGoodId）
3. Cron：@Cron('0 * * * *') 每小时执行一次完整同步
4. 日志：每次同步开始写入 sync_logs（status=RUNNING），完成后更新为 SUCCESS/FAILED

测试：mock axios，验证 mapper 与去重逻辑（不真实调用 SDS）。

B13: Public API 模块

文件：src/public/{public.module.ts, public.controller.ts, public.service.ts}

接口（无需鉴权）：

方法	路径	描述
GET	/public/categories	品类树，仅含有商品的品类
GET	/public/countries	国家列表，仅含有商品的国家
GET	/public/goods	分页商品 (countryId/categoryId/tagId/keyword/page/pageSize)
GET	/public/goods/:id	商品详情

实现要点：

• 排序：goodPriority DESC → position.indexVal ASC → createdAt DESC
• 仅返回 Public 字段（排除内部 originGoodId 等），DTO 转换在 service 完成
• 接受 countryId 与 categoryId 多维过滤
• GET /public/categories 用 EXISTS 子查询过滤

测试：覆盖所有筛选维度 + 排序正确性。

B14: 全局异常过滤器、响应拦截器、CORS

文件：

• src/common/filters/http-exception.filter.ts：统一错误格式 { statusCode, message, error, timestamp, path }
• src/common/interceptors/transform.interceptor.ts：统一响应 { data, success: true }
• src/common/pipes/validation.pipe.ts：全局 ValidationPipe({ whitelist: true, transform: true })

在 main.ts：

app.enableCors({ origin: ['http://localhost:5173', 'http://localhost:3000'], credentials: true });
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
app.useGlobalFilters(new HttpExceptionFilter());
app.useGlobalInterceptors(new TransformInterceptor());

B15: 启动验证 + Swagger 文档

操作：

1. 安装 @nestjs/swagger
2. main.ts 中配置 SwaggerModule.setup('api/docs', app, document)
3. 每个 controller / DTO 加 @ApiTags、@ApiOperation、@ApiProperty
4. npm run start:dev 启动后访问 http://localhost:3001/api/docs 确认所有接口可见

验收：所有阶段一测试 npm run test 全绿，启动后 Swagger 完整。

---

A1: 初始化 Vite + Vue 3 + TS + Element Plus

在 inkreach-official-admin/ 执行：

1. npm create vite@latest . -- --template vue-ts（注意当前目录）
2. 安装：element-plus @element-plus/icons-vue pinia vue-router@4 axios @vueuse/core dayjs
3. 开发依赖：@types/node sass unplugin-auto-import unplugin-vue-components
4. 在 vite.config.ts 配置 AutoImport + Components 插件按需引入 Element Plus
5. main.ts 注册 Pinia、Router、Element Plus 中文 locale

验收：npm run dev 启动 5173 端口，首页可见。

A2: Vite proxy + 环境变量

.env.development：

VITE_API_BASE=/api

vite.config.ts：

server: {
  port: 5173,
  proxy: {
    '/api': {
      target: 'http://localhost:3001',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
},

A3: Axios 实例与 API 模块层

文件：

• src/api/request.ts：创建 axios 实例，请求拦截器加 Authorization: Bearer <token>，响应拦截器统一脱壳 data.data，401 跳登录
• src/api/auth.ts：login(username, password) / register(...)
• src/api/goods.ts、categories.ts、countries.ts、tags.ts、positions.ts、origin-goods.ts、sync.ts：对应后端接口，TS 类型明确

类型：src/types/index.ts 定义 Good、Country、Category、Tag、Position、OriginGoods、PaginatedResult<T> 等。

A4: Pinia stores

文件：

• src/stores/auth.ts：token、user、login()、logout()、isLoggedIn，token 持久化到 localStorage
• src/stores/app.ts：侧边栏折叠状态、面包屑

A5: 路由 + 鉴权守卫

文件：src/router/index.ts

/login                  → LoginView
/                       → DefaultLayout（重定向到 /goods）
  ├── /goods            → GoodsView
  ├── /categories       → CategoriesView
  ├── /countries        → CountriesView
  ├── /tags             → TagsView
  ├── /positions        → PositionsView
  ├── /origin-goods     → OriginGoodsView（只读列表）
  └── /sync             → SyncView

全局守卫：未登录访问受保护路由 → 跳 /login；已登录访问 /login → 跳 /goods。

A6: LoginView

文件：src/views/login/LoginView.vue

• Element Plus <el-form> 实现：用户名 + 密码 + 登录按钮
• 居中卡片布局，背景渐变 / 品牌色
• 调用 authStore.login() 成功后跳 /

A7: DefaultLayout

文件：src/layouts/DefaultLayout.vue

布局：

• 左侧 <el-menu> 侧边栏（240px 宽），可折叠
• 顶部 header：面包屑 + 用户头像下拉（含登出）
• 中间 <router-view> 内容区

菜单项与路由一一对应，使用 @element-plus/icons-vue 图标。

A8: GoodsView

文件：src/views/goods/{GoodsView.vue, components/GoodFormDialog.vue, components/BatchAddDialog.vue}

功能：

• 顶部筛选栏：国家下拉 + 品类级联 + 标签下拉 + 关键词输入 + 搜索/重置按钮
• 表格列：商品名、国家、品类、标签、位置、优先级、创建时间、操作（编辑/删除）
• 分页器（Element Plus <el-pagination>）
• 工具栏：新增按钮 + 批量添加按钮 + 批量调优先级按钮
• 新增/编辑对话框：商品名、关联 originGood（远程搜索）、国家、品类（级联）、标签、位置、优先级
• 批量添加对话框：左侧 originGoods 多选表格，右侧统一配置（国家/品类/标签/位置/优先级），保存调 POST /goods/batch

测试 (GoodsView.spec.ts)：

• mount 后展示列表
• 筛选触发重新请求
• 删除二次确认后调接口

A9: CategoriesView

文件：src/views/categories/{CategoriesView.vue, components/CategoryFormDialog.vue}

功能：

• Element Plus <el-table> :tree-props 树形展示
• 列：品类名、图标预览、子品类数、操作
• 新增/编辑：品类名、父品类（级联，可空）、图标 URL
• 删除：如有子品类二次确认

测试：树形展开、新增子品类后刷新。

A10: CountriesView

文件：src/views/countries/{CountriesView.vue, components/CountryFormDialog.vue}

• 表格：国家名、图标预览、操作
• 表单：国家名（唯一校验）、图标 URL（可选）

测试：CRUD 流程。

A11: TagsView

文件：src/views/tags/{TagsView.vue, components/TagFormDialog.vue}

• 表格：标签名、颜色色块、timing、操作
• 表单：标签名（唯一）、颜色（<el-color-picker>）、timing

测试：颜色验证、唯一冲突提示。

A12: PositionsView

文件：src/views/positions/{PositionsView.vue, components/PositionFormDialog.vue}

• 表格：index_val、关联国家、关联品类、操作
• 表单：index_val（整数）、国家下拉（可空）、品类级联（可空）
• 筛选：按国家/品类筛选

测试：国家/品类联动加载。

A13: SyncView

文件：src/views/sync/SyncView.vue

• 卡片 1：品类同步 — 按钮 + 最近同步时间/状态
• 卡片 2：产品同步 — 按钮 + 最近同步时间/状态
• 表格：最近 20 条 sync_logs
• 触发后调 POST /sync/categories 或 POST /sync/products，加 loading + 成功/失败提示
• 自动每 30s 拉取一次状态（useIntervalFn from VueUse）

测试：触发同步 + 状态刷新。

---

W1: Nuxt runtimeConfig 与 .env

文件：inkreach-official-website/.env（追加）

NUXT_PUBLIC_BACKEND_URL=http://localhost:3001

nuxt.config.ts 追加：

runtimeConfig: {
  public: {
    backendUrl: 'http://localhost:3001',
  },
},

W2: Nitro 后端代理 routes

新建文件：

路径	转发到
server/api/backend/categories.get.ts	GET :3001/public/categories
server/api/backend/countries.get.ts	GET :3001/public/countries
server/api/backend/goods.get.ts	GET :3001/public/goods?...
server/api/backend/goods/[id].get.ts	GET :3001/public/goods/:id

所有 handler 用 defineCachedEventHandler 缓存 60s，透传 query 参数。参考现有 server/api/pod/categories.post.ts 写法。

示例 server/api/backend/goods.get.ts：

export default defineCachedEventHandler(async (event) => {
  const config = useRuntimeConfig();
  const query = getQuery(event);
  return $fetch(`${config.public.backendUrl}/public/goods`, { query });
}, {
  maxAge: 60,
  swr: true,
  name: 'backend-goods',
  getKey: (event) => JSON.stringify(getQuery(event)),
});

W3: useProductCenter composable

文件：app/composables/useProductCenter.ts

类型：

export interface Country { id: number; name: string; icon?: string; }
export interface Category {
  id: number;
  name: string;
  icon?: string;
  parentId: number | null;
  children: Category[];
}
export interface Tag { id: number; name: string; color?: string; }
export interface Product {
  id: number;
  name: string;
  image: string;
  price: number;
  country: Country;
  category: Category;
  tag?: Tag;
}
export interface ProductQuery {
  countryId?: number;
  categoryId?: number;
  tagId?: number;
  keyword?: string;
  page: number;
  pageSize: number;
}

API：

• categories / countries（用 useFetch SSR 拉取）
• products / total / loading
• query（reactive 筛选条件）
• selectedCategory、selectedCountry、selectedTags
• setCategory(id)、setCountry(id)、setKeyword(v)、setPage(n)、setPageSize(n)
• fetchProducts() watch query 变化自动触发

W4: ProductSidebar.vue

文件：app/components/product/ProductSidebar.vue

按设计稿 product-center-1.png 还原：

• 顶级品类带 emoji/图标 + 名称 + 右侧折叠箭头
• 点击顶级展开/收起子品类
• 子品类列表带缩进；选中项左侧 4px 橙色竖条 + bg-inkreach-homepage-3 + 橙色文字
• 未选中：灰色文字 + hover 浅灰背景
• 宽度 240px，背景白色，圆角 12px

Props：categories、activeCategoryId，emit update:activeCategoryId

W5: ProductCountryFilter.vue

文件：app/components/product/ProductCountryFilter.vue

• 横向 pill 按钮组，每个 pill：国旗图标 + 国家名
• "全部"为默认项，selected 时橙色边框 + 橙色文字 + 白底
• 未选中：灰色边框 + 灰色文字
• 横向溢出可滚动

Props：countries、activeCountryId (null 表示"全部")

W6: ProductFilterBar.vue

文件：app/components/product/ProductFilterBar.vue

按设计稿 product-center-2.png：

• 左侧：筛选下拉（如"价格区间"等占位）+ 已选标签 chips（可点击 × 清除）
• 右侧：分体式搜索框 — 灰色输入框 + 橙色"搜索"按钮（圆角矩形）

Props/Emits：keyword v-model、selectedTags、onSearch

W7: ProductCard + ProductCardSkeleton

ProductCard.vue：

• 整卡白底圆角 12px，hover 浮起阴影
• 顶部 1:1 商品图（背景 bg-inkreach-homepage-1）
• 商品名（单行 truncate）
• 标签行：横向 pill 标签，颜色按 tag.color 渲染；约定：绿=包邮，橙=工艺，灰=其他
• 价格："¥XX.XX 起"，粗体橙色

ProductCardSkeleton.vue：

• 与 ProductCard 同尺寸
• 图片区灰色 + animate-pulse
• 标题/价格行用灰色矩形条 + animate-pulse

W8: ProductGrid.vue

文件：app/components/product/ProductGrid.vue

• 4 列（lg）/ 3 列（md）/ 2 列（sm）网格
• loading=true 时渲染 12 个 ProductCardSkeleton
• products 为空时渲染空状态插画 + "暂无商品"提示

Props：products、loading

W9: ProductPagination.vue

文件：app/components/product/ProductPagination.vue

按设计稿 product-center-3.png：

• 左侧："总计 N 个产品"
• 中间：上一页 / 页码方形按钮（当前页橙色填充） / 下一页
• 右侧：<select> 每页条数（12/24/48） + 跳转到 input + Go 按钮

Props/Emits：total、page、pageSize，emit update:page、update:pageSize

W10: app/pages/product-center.vue

文件：app/pages/product-center.vue

布局：

<AppHeader />
<main class="bg-inkreach-homepage-2 min-h-screen pt-6 pb-12">
  <div class="max-w-7xl mx-auto px-4 lg:px-6 flex gap-6">
    <ProductSidebar :categories="..." v-model:activeCategoryId="..." />
    <div class="flex-1 flex flex-col gap-4">
      <ProductCountryFilter ... />
      <ProductFilterBar ... />
      <ProductGrid ... />
      <ProductPagination v-if="!loading" ... />
    </div>
  </div>
</main>
<AppFooter />

由于 Nuxt 4 项目目前用 app.vue 单入口，需在 app.vue 替换为 <NuxtPage /> 并把首页改成 app/pages/index.vue（迁移现有 app.vue 内容到 pages/index.vue），同时新增 pages/product-center.vue。

响应式：移动端侧边栏改为顶部折叠 <details>，国家筛选可横向滚动。

SEO：useSeoMeta({ title: '产品中心 | InkReach', description: '...' })

W11: AppHeader + PodProducts 链接更新

改动：

• app/components/AppHeader.vue：将"产品中心"的 <a :href="PORTAL_URL"> 替换为 <NuxtLink to="/product-center">，桌面端 + 移动端两处
• app/components/PodProducts.vue：把底部"更多产品"按钮改为 <NuxtLink to="/product-center">，并补样式（橙色边框/填充等品牌按钮样式）

W12: 三断点视觉验证

依次在 375 / 768 / 1440 宽度验证：

• 侧边栏在移动端是否正常折叠
• 国家筛选横向滚动是否流畅
• 商品网格列数响应正确（2/3/4）
• 分页器在移动端单行显示

---

F1: 更新 docs/references/structs.md

更新根级 docs/references/structs.md（若无则新建），按以下结构记录：

inkreach-official/
├── inkreach-official-nestjs/    # NestJS 后端，:3001
│   └── src/
│       ├── auth/                # JWT 认证
│       ├── countries/           # 国家 CRUD
│       ├── categories/          # 品类树 CRUD
│       ├── ...
│       ├── sync/                # SDS 定时同步
│       └── public/              # 官网公开 API
├── inkreach-official-admin/     # Vue 3 Admin, :5173
│   └── src/
│       ├── views/               # 各管理页
│       ├── api/                 # API 调用
│       └── stores/              # Pinia
└── inkreach-official-website/   # Nuxt 4 官网, :3000
    └── app/
        ├── pages/
        │   ├── index.vue
        │   └── product-center.vue  # ← 新增
        └── components/
            └── product/             # ← 新增

每个子项目下也维护自己的 docs/references/structs.md。

F2: 更新 README 与 docs/references

• 根目录 README.md：补充三子项目启动方式与端口
• 每个子项目的 README.md：补充本子项目快速启动
• 各子项目 docs/references/index.md：详细使用说明（接口、命令、配置）

F3: 更新 SKILL.md

• skills/inkreach-official-nestjs/SKILL.md：后端开发约定（如何加模块、TDD 流程）
• skills/inkreach-official-admin/SKILL.md：Admin 开发约定（如何加页面、API 层）
• skills/inkreach-official-website/SKILL.md：补充产品中心页面与代理路由相关说明

F4: 全链路联调

1. 启动 Postgres + 后端：cd inkreach-official-nestjs && npm run start:dev
2. 手动调用 POST /auth/register 创建管理员
3. 手动调用 POST /sync/categories 和 /sync/products 拉取 SDS 数据到 origin_goods
4. 启动 Admin：cd inkreach-official-admin && npm run dev，登录后在各页配置国家/品类/标签/位置，并批量从 origin_goods 创建 goods
5. 启动 Website：cd inkreach-official-website && npm run dev，访问 /product-center 验证侧边栏、筛选、分页、跳转
6. 三端同时运行无 console 报错，所有筛选条件返回正确数据

完成标准：

• 三个子项目均能 npm run test 全绿
• 三端联调跑通完整业务流
• 文档与结构图已更新