feat(admin): country drag-sort + always-available member detail sync

- Country 加 sort_order（默认 0 保持 id 序）；PATCH /countries/sort 批量保存
  顺序（对齐 /tags/sort 模式）；findAll 与公开 /public/countries 均按
  sortOrder 排序
- CountriesView 表格改为可拖拽行列表：拖动松开即全量保存新顺序，失败回滚
- 商品编辑弹窗成员展开面板：同步详情按钮常驻（已同步显示 重新同步详情），
  不再只在未同步态出现
- goods.service.spec 的 FamilyRecomputeService mock 补齐 syncFamilyTags 等
  方法（全量并行时其他套件的扫名归族会把本套件夹具收进族，create/update
  会调用到，mock 缺方法导致偶发 TypeError）
- api 164/164、admin typecheck+22/22+构建全绿

apps/admin/src/api/countries.ts

@@ -32,4 +32,9 @@ export const countriesApi = {
   deleteCountry: (id: string) => {
     return request.delete(`/countries/${id}`)
   },
+
+  // Batch save drag-reorder (items = full list in the new order)
+  sortCountries: (items: Array<{ id: string; sortOrder: number }>) => {
+    return request.patch<any, Country[]>('/countries/sort', { items })
+  },
 }

apps/admin/src/views/countries/CountriesView.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { onMounted, reactive, ref } from 'vue'
 import { ElMessage, ElMessageBox } from 'element-plus'
-import { Plus, Edit, Delete, Refresh, Search } from '@element-plus/icons-vue'
+import { Plus, Edit, Delete, Refresh, Search, Rank } from '@element-plus/icons-vue'
 import type {
   Country,
   CreateCountryRequest,
@@ -44,6 +44,38 @@ function handleReset() {
   fetchList()
 }
 
+// ─── 拖拽排序：松开即按新顺序全量保存（sortOrder = 下标） ───
+const dragIndex = ref<number | null>(null)
+const sorting = ref(false)
+
+function onRowDragStart(index: number) {
+  dragIndex.value = index
+}
+
+async function onRowDrop(index: number) {
+  const from = dragIndex.value
+  dragIndex.value = null
+  if (from === null || from === index || sorting.value) return
+  const next = [...list.value]
+  const [moved] = next.splice(from, 1)
+  next.splice(index, 0, moved)
+  list.value = next
+  sorting.value = true
+  try {
+    const updated = await countriesApi.sortCountries(
+      next.map((c, i) => ({ id: String(c.id), sortOrder: i })),
+    )
+    const arr = Array.isArray(updated) ? updated : []
+    if (arr.length) list.value = arr
+    ElMessage.success('排序已保存')
+  } catch {
+    ElMessage.error('排序保存失败')
+    await fetchList()
+  } finally {
+    sorting.value = false
+  }
+}
+
 const dialogRef = ref()
 const dialogVisible = ref(false)
 const dialogMode = ref<'create' | 'edit'>('create')
@@ -145,54 +177,43 @@ onMounted(fetchList)
         </el-button>
       </div>
 
-      <el-table v-loading="loading" :data="list" border stripe>
+      <ul v-loading="loading" class="country-list">
-        <el-table-column label="图标" width="80">
+        <li
-          <template #default="{ row }: any">
+          v-for="(row, index) in list"
-            <el-image
+          :key="row.id"
-              v-if="row.countryIcon"
+          class="country-row"
-              :src="row.countryIcon"
+          :class="{ 'is-dragging': dragIndex === index }"
-              :preview-src-list="[row.countryIcon]"
+          draggable="true"
-              fit="cover"
+          title="拖拽调整顺序，松开即保存"
-              style="width: 32px; height: 32px; border-radius: 4px;"
+          @dragstart="onRowDragStart(index)"
-            />
+          @dragover.prevent
-            <span v-else>-</span>
+          @drop="onRowDrop(index)"
-          </template>
+          @dragend="dragIndex = null"
-        </el-table-column>
+        >
-        <el-table-column prop="countryName" label="名称" min-width="200" />
+          <el-icon class="drag-handle"><Rank /></el-icon>
-        <el-table-column label="创建时间" width="180">
+          <el-image
-          <template #default="{ row }: any">
+            v-if="row.countryIcon"
-            {{ new Date(row.createdAt).toLocaleString() }}
+            :src="row.countryIcon"
-          </template>
+            :preview-src-list="[row.countryIcon]"
-        </el-table-column>
+            fit="cover"
-        <el-table-column label="操作" width="180" fixed="right">
+            class="row-icon"
-          <template #default="{ row }: any">
+          />
-            <div class="table-actions">
+          <span v-else class="row-icon row-icon-placeholder">-</span>
-              <el-button size="small" type="primary" plain @click="openEditDialog(row)">
+          <span class="row-name">{{ row.countryName }}</span>
-                <el-icon><Edit /></el-icon>
+          <span class="row-time">{{ new Date(row.createdAt).toLocaleString() }}</span>
-                <span>编辑</span>
+          <div class="table-actions">
-              </el-button>
+            <el-button size="small" type="primary" plain @click="openEditDialog(row)">
-              <el-button size="small" type="danger" plain @click="handleDelete(row)">
+              <el-icon><Edit /></el-icon>
-                <el-icon><Delete /></el-icon>
+              <span>编辑</span>
-                <span>删除</span>
+            </el-button>
-              </el-button>
+            <el-button size="small" type="danger" plain @click="handleDelete(row)">
-            </div>
+              <el-icon><Delete /></el-icon>
-          </template>
+              <span>删除</span>
-        </el-table-column>
+            </el-button>
-        <template #empty>
+          </div>
-          <el-empty description="暂无国家" />
+        </li>
-        </template>
+        <li v-if="!loading && !list.length" class="country-empty">暂无国家</li>
-      </el-table>
+      </ul>
-
-      <el-pagination
-        class="pagination"
-        v-model:current-page="filter.page"
-        v-model:page-size="filter.pageSize"
-        :total="total"
-        :page-sizes="[10, 20, 50, 100]"
-        layout="total, sizes, prev, pager, next, jumper"
-        @current-change="(p: number) => { filter.page = p; fetchList() }"
-        @size-change="(s: number) => { filter.pageSize = s; filter.page = 1; fetchList() }"
-      />
     </div>
 
     <el-dialog
@@ -224,8 +245,81 @@ onMounted(fetchList)
   flex: 1;
 }
 
-.pagination {
+.country-list {
-  margin-top: 16px;
+  list-style: none;
-  justify-content: flex-end;
+  margin: 0;
+  padding: 0;
+}
+
+.country-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 16px;
+  background: var(--el-bg-color);
+  border: 1px solid var(--el-border-color-lighter);
+  border-top: none;
+  cursor: grab;
+}
+
+.country-row:first-child {
+  border-top: 1px solid var(--el-border-color-lighter);
+  border-radius: 4px 4px 0 0;
+}
+
+.country-row:last-child {
+  border-radius: 0 0 4px 4px;
+}
+
+.country-row:only-child {
+  border-radius: 4px;
+}
+
+.country-row.is-dragging {
+  opacity: 0.5;
+}
+
+.country-row:hover {
+  background: var(--el-fill-color-light);
+}
+
+.drag-handle {
+  color: var(--el-text-color-secondary);
+  font-size: 16px;
+}
+
+.row-icon {
+  width: 32px;
+  height: 32px;
+  border-radius: 4px;
+  flex: none;
+}
+
+.row-icon-placeholder {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--el-text-color-secondary);
+  border: 1px dashed var(--el-border-color);
+}
+
+.row-name {
+  font-weight: 500;
+}
+
+.row-time {
+  margin-left: auto;
+  color: var(--el-text-color-secondary);
+  font-size: 13px;
+}
+
+.table-actions {
+  flex: none;
+}
+
+.country-empty {
+  padding: 32px 0;
+  text-align: center;
+  color: var(--el-text-color-secondary);
 }
 </style>

apps/admin/src/views/goods/components/GoodsEditDialog.vue

@@ -647,12 +647,17 @@ async function handleDeleteGood() {
               </el-table>
             </div>
             <div v-if="row.source === 'SDS'" class="member-extra">
-              <div v-if="!memberDetail(row.id) || memberDetail(row.id).loading" class="md-empty">详情加载中…</div>
+              <div class="member-detail-head">
-              <div v-else-if="!memberDetail(row.id).hasDetail" class="md-empty">
+                <span v-if="!memberDetail(row.id) || memberDetail(row.id).loading" class="md-empty">详情加载中…</span>
-                尚未同步详情
+                <span v-else-if="!memberDetail(row.id).hasDetail" class="md-empty">尚未同步详情</span>
-                <el-button size="small" :icon="Refresh" :loading="detailSyncing === row.id" @click="handleSyncMemberDetail(row)">同步详情</el-button>
+                <el-button
+                  size="small"
+                  :icon="Refresh"
+                  :loading="detailSyncing === row.id"
+                  @click="handleSyncMemberDetail(row)"
+                >{{ memberDetail(row.id)?.hasDetail ? '重新同步详情' : '同步详情' }}</el-button>
               </div>
-              <el-tabs v-else class="member-detail-tabs">
+              <el-tabs v-if="memberDetail(row.id) && memberDetail(row.id).hasDetail" class="member-detail-tabs">
                 <el-tab-pane label="商品详情">
                   <el-descriptions :column="2" border size="small">
                     <el-descriptions-item label="商品编码">{{ memberDetail(row.id).detail.productCode || '-' }}</el-descriptions-item>
@@ -908,6 +913,11 @@ async function handleDeleteGood() {
   display: flex; align-items: center; justify-content: space-between; gap: 8px;
   font-size: 12px; color: var(--el-text-color-placeholder); padding: 4px 0;
 }
+.member-detail-head {
+  display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  margin-bottom: 4px;
+}
+.member-detail-head .md-empty { padding: 0; }
 .member-detail-tabs :deep(.el-tabs__header) { margin-bottom: 8px; }
 .edit-family-loading { color: var(--el-text-color-placeholder); font-size: 12px; padding: 4px 0; }
 .family-detail-tabs { margin-top: 10px; }

apps/api/prisma/migrations/20260828194000_country_sort_order/migration.sql

@@ -0,0 +1,2 @@
+-- 国家自定义排序：默认 0 保持既有 id 序，后台可拖拽调整
+ALTER TABLE "countries" ADD COLUMN "sort_order" INTEGER NOT NULL DEFAULT 0;

apps/api/prisma/schema.prisma

@@ -143,6 +143,7 @@ model Country {
   id          BigInt   @id @default(autoincrement()) @map("country_id")
   countryName String   @unique @map("country_name")
   countryIcon String?  @map("country_icon")
+  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)
 

apps/api/src/countries/countries.controller.ts

@@ -18,6 +18,7 @@ import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { CountriesService } from './countries.service';
 import { CreateCountryDto } from './dto/create-country.dto';
 import { UpdateCountryDto } from './dto/update-country.dto';
+import { ReorderCountriesDto } from './dto/reorder-countries.dto';
 
 @ApiTags('countries')
 @ApiBearerAuth()
@@ -32,6 +33,13 @@ export class CountriesController {
     return this.service.findAll();
   }
 
+  // 注意：'sort' 静态路由必须声明在 ':id' 之前，否则会被参数路由吞掉
+  @Patch('sort')
+  @ApiOperation({ summary: 'Batch update country sort order (drag reorder)' })
+  reorder(@Body() dto: ReorderCountriesDto) {
+    return this.service.reorder(dto);
+  }
+
   @Get(':id')
   @ApiOperation({ summary: 'Get one country' })
   findOne(@Param('id', ParseIntPipe) id: string) {

apps/api/src/countries/countries.service.spec.ts

@@ -112,4 +112,30 @@ describe('CountriesService', () => {
     const idx = created.indexOf(`${name}-v2`);
     if (idx !== -1) created.splice(idx, 1);
   });
+
+  it('reorder persists sortOrder and findAll honors it', async () => {
+    const stamp = Date.now();
+    const a = await service.create({ countryName: `Sort A ${stamp}` });
+    const b = await service.create({ countryName: `Sort B ${stamp}` });
+    const c = await service.create({ countryName: `Sort C ${stamp}` });
+    created.push(a.countryName, b.countryName, c.countryName);
+
+    // 新顺序 C, A, B（id 序与 sortOrder 无关时也能稳定验证）
+    const reordered = await service.reorder({
+      items: [
+        { id: Number(c.id), sortOrder: 0 },
+        { id: Number(a.id), sortOrder: 1 },
+        { id: Number(b.id), sortOrder: 2 },
+      ],
+    });
+    const ours = reordered.filter((r) =>
+      [a.id, b.id, c.id].some((id) => id.toString() === r.id.toString()),
+    );
+    expect(ours.map((r) => r.id.toString())).toEqual([c.id.toString(), a.id.toString(), b.id.toString()]);
+
+    const list = await service.findAll();
+    const pos = (id: bigint) => list.findIndex((r) => r.id.toString() === id.toString());
+    expect(pos(c.id)).toBeLessThan(pos(a.id));
+    expect(pos(a.id)).toBeLessThan(pos(b.id));
+  });
 });

apps/api/src/countries/countries.service.ts

@@ -8,13 +8,29 @@ import {
 import { PrismaService } from '../prisma/prisma.service';
 import { CreateCountryDto } from './dto/create-country.dto';
 import { UpdateCountryDto } from './dto/update-country.dto';
+import { ReorderCountriesDto } from './dto/reorder-countries.dto';
 
 @Injectable()
 export class CountriesService {
   constructor(private readonly prisma: PrismaService) {}
 
   findAll() {
-    return this.prisma.country.findMany({ orderBy: { id: 'asc' } });
+    return this.prisma.country.findMany({
+      orderBy: [{ sortOrder: 'asc' }, { id: 'asc' }],
+    });
+  }
+
+  /** 批量保存拖拽后的顺序（全量提交，sortOrder = 目标下标） */
+  async reorder(dto: ReorderCountriesDto) {
+    await this.prisma.$transaction(
+      dto.items.map((item) =>
+        this.prisma.country.update({
+          where: { id: BigInt(item.id) },
+          data: { sortOrder: item.sortOrder },
+        }),
+      ),
+    );
+    return this.findAll();
   }
 
   async findOne(id: bigint) {

apps/api/src/countries/dto/reorder-countries.dto.ts

@@ -0,0 +1,30 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  ArrayMinSize,
+  IsArray,
+  IsInt,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+
+export class CountryOrderItem {
+  @ApiProperty()
+  @IsInt()
+  @Min(1)
+  id!: number;
+
+  @ApiProperty()
+  @IsInt()
+  @Min(0)
+  sortOrder!: number;
+}
+
+export class ReorderCountriesDto {
+  @ApiProperty({ type: [CountryOrderItem] })
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => CountryOrderItem)
+  items!: CountryOrderItem[];
+}

apps/api/src/goods/goods.service.spec.ts

@@ -33,7 +33,15 @@ describe('GoodsService', () => {
         },
         {
           provide: FamilyRecomputeService,
-          useValue: { enqueue: jest.fn() },
+          // 全量并行跑时其他套件的扫名归族可能把本套件夹具链接收进族，
+          // create/update 会调用 syncFamilyTags —— mock 必须覆盖全部被调方法
+          useValue: {
+            enqueue: jest.fn(),
+            recomputeFamily: jest.fn().mockResolvedValue(undefined),
+            syncFamilyTags: jest.fn().mockResolvedValue({ goodsUpdated: 0, linksUpdated: 0 }),
+            refreshLinkTags: jest.fn().mockResolvedValue(undefined),
+            mirrorLinkTagsToGoods: jest.fn().mockResolvedValue(undefined),
+          },
         },
       ],
     }).compile();

apps/api/src/public/public.service.ts

@@ -111,7 +111,7 @@ export class PublicService {
   async getCountries(): Promise<PublicCountryDto[]> {
     const rows = await this.prisma.country.findMany({
       where: { goods: { some: { familyId: { not: null }, originGood: { delisted: false } } } },
-      orderBy: { id: 'asc' },
+      orderBy: [{ sortOrder: 'asc' }, { id: 'asc' }],
     });
     return rows.map(PublicCountryDto.from);
   }

docs/references/structs.md

@@ -116,6 +116,7 @@ apps/api/
 | `/public/goods` `GET` | 分页商品（**族化契约：一族一条**，`goodId`=族ID，`price`=族起价；无族商品不返回；支持 `countryId/categoryId/tags(JSON)/keyword/minPrice/maxPrice/sort/page/pageSize`） | 公开 |
 | `/public/goods/:id` `GET` | 款级详情，`:id` = **族 ID**（唯一公开键，SDS 链接 ID 404）；公共字段取代表 Good，`variants` = 全体族成员 ∪ 旧副源（去重），`sizeChart/packageSpecs` = 族并集；默认输出 `family` 块（并集尺码表/包装 + 严格五维价格矩阵 尺码×颜色×印花数量×工艺×物流 + 族起价）；`PUBLIC_DETAIL_FROM_FAMILY=false` 应急回退 | 公开 |
 | `/categories` `/tags` `/tag-groups` `/countries` `/positions` | 后台 CRUD | JWT |
+| `/countries/sort` `PATCH` | 批量保存国家拖拽排序（`items=[{id,sortOrder}]` 全量提交；公开/后台国家列表均按 sortOrder 排序） | JWT |
 | `/tags/sort` `PATCH` | 批量更新 tag 排序和分组归属 | JWT |
 | `/tag-groups/sort` `PATCH` | 批量更新分组排序 | JWT |
 | `/origin-goods` `GET` | SDS 原始商品快照分页 | JWT |