yeuimu
f1e81872e7
问题2（SKU 无法自动合并，GBIU017 案例）四处叠加根因修复： - 人工标签旧词「热转印」被封闭词表静默踢出合并矩阵 → CRAFT_TAG_ALIASES 别名归一为「烫画」（矩阵归因与 CUSTOM 标签同路径生效） - updateTags 缺任一定价维度组即整链掉出矩阵且人工接管后永不恢复 → 缺啥补啥（按链接名派生补齐，人工勾选值不动，响应带 filledDimensionTags） - autoGroup 只建新族从不并入已有族（产生 USIU005-2 类碎片）→ 并入已有 autoManaged 同款族优先，无匹配才新建；同款仅人工锁定族则跳过并报告 - 名称回退分组键含物流备注，包邮/不包邮永不同组 → 新增族语义键 familyNameKey（国家+品名+SKU），api/admin 两侧同构，合并默认勾选随之修复 附加： - updateTags 后未归族链接自动并入匹配族（attachToMatchingFamily，响应带 attachedFamilyId） - 整理新增碎片族合并 consolidateFragments：纯碎片族并入带商品族并删除 （保公开 goodId=族ID 稳定），带商品/覆盖价/人工锁定进人工复审报告 - admin：保存标签提示补齐明细，整理完成消息含并入/碎片合并/待人工数 问题1（后台频繁 Unauthorized 掉线）： - refresh cookie path '/auth' 与代理前缀（/api、/v2-api）不匹配导致浏览器 永远带不上 refresh cookie → 两 cookie path 统一为 '/' - v2 构建基址带尾斜杠 + 手工拼接产生 /v2-api//auth/refresh 双斜杠 404 → request.ts 规范拼接 测试：api jest 187/187、admin vitest 22/22、双侧 tsc 0 错误； public.service 夹具改为自包含（不依赖共享库既有数据）。
Inkreach
pnpm workspaces + Turborepo monorepo，包含三个协同工作的子项目和共享包：
| 子项目 | 包名 | 技术栈 | 端口 | 角色 |
|---|---|---|---|---|
apps/api |
@inkreach/api |
NestJS 10 + Prisma 5 + PostgreSQL | 3001 | 后端 API（鉴权 / CRUD / SDS 同步 / 公开 API / Swagger） |
apps/admin |
@inkreach/admin |
Vue 3 + Vite + Element Plus + Pinia | 5173 | 后台管理（登录 / 商品 / 品类 / 国家 / 标签 / 坑位 / 同步） |
apps/website |
@inkreach/website |
Nuxt 4 + Vue 3 + Tailwind v4 | 3000 | 官方展示站 + 产品中心页 |
| 共享包 | 说明 |
|---|---|
packages/tsconfig |
共享 TypeScript 配置（base / api / vue） |
packages/shared-types |
共享类型定义（PaginatedResult, BackendEnvelope, 实体接口） |
快速开始
1. 安装依赖
pnpm install
2. 环境变量
在仓库根目录的 .env 中配置数据库：
DATABASE_URL=postgresql://postgres:<password>@localhost:5432/inkreach-official
后端额外需要的变量（在 apps/api/.env 中）：
JWT_SECRET=<your-secret>
SDS_API_BASE=https://api.sds.example.com
SDS_API_KEY=<your-key>
PORT=3001
官网通过 apps/website/.env 的 NUXT_PUBLIC_BACKEND_URL=http://localhost:3001 指向后端。
后台无需额外环境变量；Vite 代理已把 /api/* 转给 http://localhost:3001。
3. 部署
启动顺序：先启动后端，再启动另两个。
# Terminal 1：后端（需要 PostgreSQL）
cd apps/api
pnpm prisma:generate
pnpm prisma:migrate
pnpm --filter @inkreach/api dev
# → http://localhost:3001 · Swagger: http://localhost:3001/api/docs
# Terminal 2：官网
pnpm --filter @inkreach/website dev
# → http://localhost:3000
# Terminal 3：后台
pnpm --filter @inkreach/admin dev
# → http://localhost:5173
或者使用 Turborepo 同时启动所有开发服务器：
pnpm dev # turbo run dev
端口分配
| 端口 | 项目 | 入口 |
|---|---|---|
| 3001 | NestJS 后端 | apps/api/src/main.ts |
| 5173 | Vue Admin | apps/admin/vite.config.ts |
| 3000 | Nuxt 官网 | apps/website/nuxt.config.ts |
数据流概览
[SDS 外部 API]
│ (同步)
▼
[NestJS 后端 :3001] ── public/goods ──► [Nitro 代理 /api/backend/*] ──► [Nuxt 官网 :3000]
│ ▲
├── /auth /goods /categories ... ──► │ Vite proxy /api/*
│ │
[PostgreSQL] [Vue Admin :5173]
常用命令
# 根目录（使用 pnpm workspace filter）
pnpm install # 安装所有依赖
pnpm dev # 启动所有 dev 服务器 (turbo)
pnpm build # 构建所有项目 (turbo)
pnpm format # 格式化所有文件 (prettier)
# 后端
pnpm --filter @inkreach/api start:dev # 开发
pnpm --filter @inkreach/api build # 编译
pnpm --filter @inkreach/api test # 单元测试
pnpm --filter @inkreach/api prisma:generate # 生成 Prisma Client
pnpm --filter @inkreach/api prisma:migrate # 运行迁移
pnpm --filter @inkreach/api prisma:studio # 打开 Prisma Studio
pnpm --filter @inkreach/api backfill:product-families # 产品族回填（解析链接名→自动建族→全量重算，幂等）
# 官网
pnpm --filter @inkreach/website dev # 开发
pnpm --filter @inkreach/website build # 构建
pnpm --filter @inkreach/website generate # 静态站点生成
# 后台
pnpm --filter @inkreach/admin dev # 开发
pnpm --filter @inkreach/admin build # 构建
文档
- 整体目录结构：
docs/references/structs.md - 数据库表设计：
docs/dev/database-table-design.md - 产品中心 PRD：
docs/dev/product-center-prd.md - 官网子项目结构：
apps/website/docs/references/structs.md - 开发规范：
AGENTS.md