# 标签组 (Tag Group) 功能

## 目标

为 `Tag` 引入分组（TagGroup）概念，覆盖三个分组：**物流渠道 / 印刷位置 / 印刷工艺**。
分组可在后台通过标签筛选下拉的树形结构直接管理（增/删/重命名/拖动排序），同时在官网商品卡片上按组排序展示 tag chip，国家 chip 放在最后。

## 用户故事

1. 运营在「官网后台 → 商品配置 → 标签筛选」打开下拉，看到一个两层树：分组 → 标签，自动展开
2. 运营可以拖动分组调整顺序，也可以拖动组内 tag 调整顺序（支持跨组拖动）
3. 运营双击分组名直接 inline 编辑，按 Enter 提交
4. 运营点击分组底部「+ 在此组下新建标签」在该组下创建新 tag
5. 运营点击分组右上角删除按钮删除分组（组内 tag 自动归入「未分组」）
6. 顾客在前端产品中心看到商品卡片的 tag chip 按 `物流渠道 → 印刷位置 → 印刷工艺` 顺序排列，国家 chip 排在最后

## 数据模型

### 新表 `tag_groups`

```prisma
model TagGroup {
  id         BigInt   @id @default(autoincrement()) @map("tag_group_id")
  groupName  String   @unique @map("group_name")
  groupIcon  String?  @map("group_icon")
  groupColor String?  @map("group_color")
  sortOrder  Int      @default(0) @map("sort_order")
  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
  updatedAt  DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(6)

  tags Tag[]

  @@map("tag_groups")
}
```

### `Tag` 表加字段

```prisma
model Tag {
  // ... 现有字段
  tagGroupId BigInt?   @map("tag_group_id")
  sortOrder  Int       @default(0) @map("sort_order")

  tagGroup TagGroup? @relation(fields: [tagGroupId], references: [id], onDelete: SetNull, onUpdate: NoAction)

  @@index([tagGroupId])
  @@index([tagGroupId, sortOrder])
}
```

### 种子数据

```sql
INSERT INTO tag_groups (group_name, sort_order) VALUES
  ('物流渠道', 1),
  ('印刷位置', 2),
  ('印刷工艺', 3);

UPDATE tags SET tag_group_id = (SELECT tag_group_id FROM tag_groups WHERE group_name = '物流渠道')
  WHERE tag_name IN ('包邮', '不包邮');
UPDATE tags SET tag_group_id = (SELECT tag_group_id FROM tag_groups WHERE group_name = '印刷位置')
  WHERE tag_name IN ('单面印花', '双面印');
UPDATE tags SET tag_group_id = (SELECT tag_group_id FROM tag_groups WHERE tag_group_name = '印刷工艺')
  WHERE tag_name IN ('烫画', '直喷', '不打印');

-- 同组内的 tag 按现有 id 升序分配 sortOrder
WITH ordered AS (
  SELECT t.tag_id,
         ROW_NUMBER() OVER (PARTITION BY t.tag_group_id ORDER BY t.tag_id) AS rn
  FROM tags t
  WHERE t.tag_group_id IS NOT NULL
)
UPDATE tags SET sort_order = ordered.rn
FROM ordered
WHERE tags.tag_id = ordered.tag_id;
```

## 后端 API

### TagGroup CRUD
- `GET /tag-groups` — 列表（含 tags）
- `POST /tag-groups` — 创建
- `PATCH /tag-groups/:id` — 更新（重命名、颜色、图标）
- `DELETE /tag-groups/:id` — 删除（级联 SetNull）
- `PATCH /tag-groups/sort` — 批量更新 `sortOrder`

### Tag 扩展
- `POST /tags` / `PATCH /tags/:id` — 支持 `tagGroupId` / `sortOrder`
- `PATCH /tags/sort` — 批量更新 `sortOrder`（跨组时同时更新 `tagGroupId`）

### Public 公开接口
- `GET /public/tag-groups` — 公开的分组列表
- `GET /public/tags` 返回的 `PublicTagDto` 增加：
  ```ts
  group: { id: string; name: string } | null
  ```

## 后端文件改动

| 文件 | 操作 |
|---|---|
| `prisma/schema.prisma` | 新表 + Tag 字段 |
| `prisma/migrations/<timestamp>_tag_groups/migration.sql` | 自动生成 + 种子 |
| `src/tag-groups/tag-groups.module.ts` | 新建 |
| `src/tag-groups/tag-groups.service.ts` | 新建 |
| `src/tag-groups/tag-groups.controller.ts` | 新建 |
| `src/tag-groups/dto/create-tag-group.dto.ts` | 新建 |
| `src/tag-groups/dto/update-tag-group.dto.ts` | 新建 |
| `src/tag-groups/dto/reorder-tag-groups.dto.ts` | 新建（批量排序） |
| `src/tags/tags.service.ts` | 改：create/update 支持 `tagGroupId`/`sortOrder`；新增 `reorder` |
| `src/tags/tags.controller.ts` | 改：加 `PATCH /tags/sort` |
| `src/tags/dto/create-tag.dto.ts` | 改 |
| `src/tags/dto/update-tag.dto.ts` | 改 |
| `src/tags/dto/reorder-tags.dto.ts` | 新建 |
| `src/public/dto/public-tag-group.dto.ts` | 新建 |
| `src/public/dto/public-tag.dto.ts` | 改：加 `group` |
| `src/public/dto/public-good.dto.ts` | 改：tag 类型加 group |
| `src/public/public.service.ts` | 改：getTags include group、按 sortOrder 排序；新增 getTagGroups |
| `src/public/public.controller.ts` | 改：加 `GET /public/tag-groups` |
| `src/app.module.ts` | 改：注册 TagGroupsModule |
| `src/tags/tags.service.spec.ts` | 改：加 tagGroupId 关联测试 |
| `src/public/public.service.spec.ts` | 改：加 tag 排序测试 |

## Admin 前端

### 核心：`GoodsView.vue` 标签筛选改 X2

位置：第 661-668 行的 `<el-select multiple>` 标签筛选。

**新结构**：
```vue
<el-popover
  v-model:visible="tagTreeVisible"
  placement="bottom-start"
  :width="320"
  trigger="click"
  popper-class="tag-tree-popper"
>
  <template #reference>
    <el-button size="small" plain>
      <i class="fa-solid fa-tags" />
      标签筛选 ({{ selectedTagIds.length }})
      <i class="fa-solid fa-chevron-down" />
    </el-button>
  </template>

  <div class="tag-tree-panel">
    <div class="tag-tree-header">
      <span>标签分组</span>
      <el-button text size="small" :icon="Plus" @click="quickAddGroup">新建分组</el-button>
    </div>

    <el-tree
      ref="tagTreeRef"
      :data="tagTreeData"
      node-key="id"
      default-expand-all
      draggable
      :allow-drop="allowDrop"
      :props="{ label: 'label', children: 'children' }"
      @node-drop="onNodeDrop"
    >
      <template #default="{ data }">
        <div
          class="tree-node"
          @mouseenter="hoveredId = data.id"
          @mouseleave="hoveredId = null"
        >
          <!-- 分组节点 -->
          <template v-if="data.type === 'group'">
            <i class="fa-solid fa-folder node-icon" />
            <input
              v-if="editingId === data.id"
              ref="editInputRef"
              v-model="editValue"
              class="node-edit-input"
              @blur="commitEdit(data)"
              @keydown.enter="commitEdit(data)"
              @keydown.esc="cancelEdit"
            />
            <span v-else class="node-label" @dblclick="startEdit(data)">
              {{ data.label }}
            </span>
            <span v-show="hoveredId === data.id && data.id !== 'g-ungrouped'" class="node-actions">
              <el-button text size="small" :icon="Delete" @click.stop="removeGroup(data)" />
            </span>
            <!-- 分组底部：+ 新建标签 -->
            <div v-if="data.id !== 'g-ungrouped' && hoveredId === data.id" class="group-add-tag">
              <el-button text size="small" :icon="Plus" @click.stop="quickAddTag(data)">在此组下新建标签</el-button>
            </div>
          </template>

          <!-- 标签节点 -->
          <template v-else>
            <span
              class="node-chip"
              :style="{ background: data.tagColor + '4d', borderColor: data.tagColor + '99', color: data.fontColor || data.tagColor }"
            >
              {{ data.label }}
            </span>
            <span v-show="hoveredId === data.id" class="node-actions">
              <el-button text size="small" :icon="Edit" @click.stop="openTagEdit(data)" />
              <el-button text size="small" :icon="Delete" @click.stop="removeTag(data)" />
            </span>
          </template>
        </div>
      </template>
    </el-tree>
  </div>
</el-popover>
```

**关键逻辑**：
- `tagTreeData` computed：从 `tagGroups` + `tags` 构造两层树，组内按 `sortOrder`，未分组追加末尾（`disabled: true`）
- `allowDrop(draggingNode, dropNode, type)`：
  - 拖动到分组节点上 → `type === 'inner'`（加入该组）
  - 拖动到 tag 节点上 → `type === 'before'/'after'`（同组排序）
  - 未分组节点不允许 drop
- `onNodeDrop`：根据拖动结果调 `PATCH /tags/sort`（组内排序）或 `PATCH /tag-groups/sort`（分组排序），或更新 `tagGroupId`（跨组移动）
- `startEdit(data)`：双击触发，记录 `editingId`，nextTick 聚焦输入框
- `commitEdit(data)`：调 `PATCH /tag-groups/:id` 或 `PATCH /tags/:id` 保存新名称
- `quickAddGroup`：弹小输入框 → 调 `POST /tag-groups`
- `quickAddTag(group)`：弹小输入框 → 调 `POST /tags`，传入 `tagGroupId`
- `removeGroup(data)`：`ElMessageBox.confirm` → 调 `DELETE /tag-groups/:id`
- `removeTag(data)`：调 `DELETE /tags/:id`

**`selectedTagIds` 与树的勾选**：
- 树上的勾选用 `show-checkbox` 即可
- 但用户更倾向"单选即勾选 / 取消勾选"——可以省略勾选框，用 `@node-click` 处理
- 简化方案：分组节点不可点击勾选（disabled），tag 节点单击切换 `selectedTagIds` 中是否包含该 id

### `TagsView.vue` 同步
- 表格加「所属分组」列
- 创建/编辑弹窗加「所属分组」`<el-select>` 字段（数据来自 `/tag-groups`）

### 类型与 API
| 文件 | 改动 |
|---|---|
| `src/types/index.ts` | 加 `TagGroup`、`CreateTagGroupRequest`、`UpdateTagGroupRequest` |
| `src/api/tag-groups.ts` | 新建（含 `getList/create/update/remove/reorder`） |
| `src/api/tags.ts` | 扩展支持 `tagGroupId`/`sortOrder` |

## 官网前端

### 数据加载
| 文件 | 改动 |
|---|---|
| `server/api/backend/tag-groups.get.ts` | 新建代理 |
| `composables/useProductCenter.ts` | `BackendTag` 加 `tagGroupId`、`tagGroup: { id, name } \| null`；`Tag` 接口加 `group`；新增 `loadTagGroups()` + `useState('pc-tag-groups')`；新增 `sortTagsByGroup()` 工具函数 |

### `ProductCard.vue` chip 排序

**国家 chip 移到 tag 之后**：
```vue
<div v-if="product.tags.length > 0 || showCountry" class="chips">
  <span
    v-for="tag in sortedTags"
    :key="tag.id"
    class="chip"
    :style="{ color: tag.fontColor || tag.color || '#ff6a00', background: (tag.color || '#ff6a00') + '4d', borderColor: (tag.color || '#ff6a00') + '99' }"
  >
    {{ tag.name }}
  </span>
  <span v-if="showCountry" class="chip country-chip">
    <img v-if="product.country.icon" :src="product.country.icon" :alt="product.country.name" class="country-flag" />
    {{ product.country.name }}
  </span>
</div>
```

`sortedTags` computed：
```ts
const sortedTags = computed(() => {
  const groupOrder = new Map(tagGroups.value.map((g, i) => [g.id, i]));
  return [...props.product.tags]
    .sort((a, b) => {
      const ao = a.group ? (groupOrder.get(a.group.id) ?? 999) : 999;
      const bo = b.group ? (groupOrder.get(b.group.id) ?? 999) : 999;
      return ao - bo;
    })
    .slice(0, 4);
});
```

### `product-center.vue` 已选 chip 排序
- `.selected-tags` 区域按相同规则排序
- country chip 排在已选 tag 之后

## 测试与文档

| 文件 | 改动 |
|---|---|
| `src/tags/tags.service.spec.ts` | 加 tagGroupId 关联测试 |
| `src/tags/tags.service.ts` create/update 单测 | 加 `tagGroupId` 字段 |
| `src/public/public.service.spec.ts` | 加 `/public/tag-groups` + tag 排序测试 |
| `docs/references/structs.md` | 更新项目结构 |
| `docs/references/admin/tags.md`（如有） | 新建或更新标签管理文档 |
| `skills/inkreach-official-admin/SKILL.md` | 加标签分组管理说明 |
| `skills/inkreach-official-website/SKILL.md` | 加 tag 排序说明 |

## 任务列表

- [ ] **T1**：后端 schema + migration
  - 改 `prisma/schema.prisma` 新增 TagGroup + Tag 字段
  - 跑 `npx prisma migrate dev --name add_tag_groups` 生成 migration
  - 在 migration.sql 末尾追加种子数据（3 个分组 + 关联现有 tag + 分配 sortOrder）
  - 跑 `npx prisma generate` 重新生成 client
- [ ] **T2**：后端 tag-groups module
  - 新建 `tag-groups.module.ts` / `service.ts` / `controller.ts` / dto
  - 注册到 `app.module.ts`
  - 实现 CRUD + 批量排序
- [ ] **T3**：后端 tags 扩展
  - `create/update` DTO 加 `tagGroupId` / `sortOrder`
  - `tags.service.ts` 处理新字段
  - 加 `PATCH /tags/sort` 端点
- [ ] **T4**：后端 public 接口
  - 新建 `public-tag-group.dto.ts`
  - `PublicTagDto` 加 `group` 字段
  - `public.service.ts` `getTags` 用 `include: { tagGroup: true }`，按 `tagGroup.sortOrder, sortOrder` 排序
  - `public.service.ts` 新增 `getTagGroups()`
  - `public.controller.ts` 加 `GET /public/tag-groups`
- [ ] **T5**：后端测试更新
  - 更新 `tags.service.spec.ts` 现有测试，加 `tagGroupId` 关联
  - 更新 `public.service.spec.ts` 加 tag group 关联 + 排序测试
- [ ] **T6**：Admin 类型 + API
  - `types/index.ts` 加 `TagGroup` 类型
  - 新建 `api/tag-groups.ts`
  - `api/tags.ts` 扩展支持新字段
- [ ] **T7**：Admin GoodsView 标签筛选（X2）
  - `GoodsView.vue:661-668` 改为 `<el-popover>` + `<el-tree>`
  - 实现 `tagTreeData` computed
  - 实现拖动（`@node-drop` + `allow-drop`）
  - 实现 inline 编辑（双击 + 失焦/Enter 提交）
  - 实现 quick add group / quick add tag
  - 实现 remove group / remove tag
  - `selectedTagIds` 与树节点单击同步
  - "未分组" 虚拟节点追加在最后（`disabled: true`）
- [ ] **T8**：Admin TagsView 同步
  - 表格加「所属分组」列
  - 创建/编辑弹窗加「所属分组」下拉
- [ ] **T9**：官网数据加载
  - 新建 `server/api/backend/tag-groups.get.ts` 代理
  - `useProductCenter.ts` 加载 tagGroups
  - 给 `Tag` 接口加 `group` 字段
  - 新增 `sortTagsByGroup()` 工具函数
- [ ] **T10**：官网 ProductCard 排序
  - `ProductCard.vue` chip 顺序：tag 们 → 国家
  - 用 `sortedTags` computed
- [ ] **T11**：官网 product-center 已选 chip 排序
  - `.selected-tags` 区域按组排序
  - country chip 排在最后
- [ ] **T12**：文档
  - 更新 `docs/references/structs.md`
  - 更新 `skills/inkreach-official-admin/SKILL.md`
  - 更新 `skills/inkreach-official-website/SKILL.md`

## 风险与权衡

1. **拖动跨组 vs 同组**：用户允许跨组，但 UI 上要明确提示（鼠标 cursor + 节点高亮）
2. **删除分组的级联**：用户确认 SetNull，但要在 UI 上二次确认（避免误删）
3. **"+ 在此组下新建标签"位置**：用户说"底部"，意味着每个组节点下方有固定行（hover 时显示）
4. **未分组虚拟节点**：不可拖动、不可编辑/删除，仅作展示
5. **数据库 seed 在 production 的处理**：seed 数据只在 migration 中执行一次，production 已有数据时迁移需谨慎