发货与退还增加

apps/backend/config/default.cjs

@@ -87,6 +87,7 @@ module.exports = {
       categoriesPath: '/categories/get',
       skuListPath: '/sku/list',
       skuBuyPath: '/sku/buy',
+      skuUsePath: '/sku/use',
       knapsackPath: '/user/get_knapsack',
       vnListPath: '/vn/list',
       vnAppointPath: '/vn/appoint',
@@ -94,6 +95,7 @@ module.exports = {
       vnVerifCodePath: '/public/vn_verif_code',
       vnVerifyLoginCodePath: '/vn/verify_login_code',
       vnBindUrlPath: '/vn/bind_url',
+      vnBackPath: '/vn/back',
       clientSource: 'ct-client',
       deviceId: '-',
       deviceType: 0,

apps/backend/data/khhao-sync-state.json

@@ -1,11 +1,11 @@
 {
   "syncFromCreatedAt": "2026-05-02T10:53:28.550Z",
-  "lastRunStartedAt": "2026-05-03T08:34:17.211Z",
+  "lastRunStartedAt": "2026-05-03T09:15:36.131Z",
-  "lastRunFinishedAt": "2026-05-03T08:34:17.844Z",
+  "lastRunFinishedAt": "2026-05-03T09:15:37.160Z",
   "lastRunStatus": "success",
   "lastErrorMessage": "",
   "fetchedCount": 40,
   "syncedCount": 0,
   "ignoredCount": 40,
-  "lastOrderCreatedAt": "2026-05-03T08:33:37.000Z"
+  "lastOrderCreatedAt": "2026-05-03T09:15:32.000Z"
 }

apps/backend/src/routes/admin/platform-config.js

@@ -4,6 +4,7 @@ import { Router } from 'express'
 
 import {
   appointAdminCloudtentaclesVirtualNumber,
+  backAdminCloudtentaclesVirtualNumber,
   buyAdminCloudtentaclesSku,
   fetchAdminCloudtentaclesVirtualNumberCode,
   generateAdminCloudtentaclesLoginCode,
@@ -14,6 +15,7 @@ import {
   getAdminCloudtentaclesKnapsack,
   getAdminCloudtentaclesSourceConfig,
   getAdminCloudtentaclesSkuList,
+  useAdminCloudtentaclesSku,
   getAdminAgisoShopConfigs,
   getAdminFulfillmentBindingConfigs,
   getAdminKhhaoSourceConfig,
@@ -54,6 +56,7 @@ import { createJsonHandler, requireAdminRoles } from './shared.js'
 /** @typedef {import('../../types/admin-route-inputs.js').AdminCloudtentaclesValidateSessionRouteBody} AdminCloudtentaclesValidateSessionRouteBody */
 /** @typedef {import('../../types/admin-route-inputs.js').AdminCloudtentaclesCatalogQueryRouteBody} AdminCloudtentaclesCatalogQueryRouteBody */
 /** @typedef {import('../../types/admin-route-inputs.js').AdminCloudtentaclesSkuBuyRouteBody} AdminCloudtentaclesSkuBuyRouteBody */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminCloudtentaclesSkuUseRouteBody} AdminCloudtentaclesSkuUseRouteBody */
 /** @typedef {import('../../types/admin-route-inputs.js').AdminCloudtentaclesVirtualNumberRouteBody} AdminCloudtentaclesVirtualNumberRouteBody */
 /** @typedef {import('../../types/admin-route-inputs.js').AdminCloudtentaclesFullFlowRouteBody} AdminCloudtentaclesFullFlowRouteBody */
 /** @typedef {import('../../types/admin-write-models.js').AdminAgisoShopConfigSaveResponse} AdminAgisoShopConfigSaveResponse */
@@ -429,6 +432,15 @@ router.post('/platform-config/cloudtentacles/sku/buy', createJsonHandler(
   },
 ))
 
+router.post('/platform-config/cloudtentacles/sku/use', createJsonHandler(
+  (req) => useAdminCloudtentaclesSku(/** @type {AdminCloudtentaclesSkuUseRouteBody} */ (req.body)),
+  {
+    successMessage: 'cloudtentacles 发货成功',
+    errorMessage: 'cloudtentacles 发货失败',
+    scope: '[admin/platform-config/cloudtentacles/sku/use]',
+  },
+))
+
 router.post('/platform-config/cloudtentacles/knapsack', createJsonHandler(
   (req) => getAdminCloudtentaclesKnapsack(/** @type {AdminCloudtentaclesCatalogQueryRouteBody} */ (req.body)),
   {
@@ -492,6 +504,15 @@ router.post('/platform-config/cloudtentacles/vn/bind-url', createJsonHandler(
   },
 ))
 
+router.post('/platform-config/cloudtentacles/vn/back', createJsonHandler(
+  (req) => backAdminCloudtentaclesVirtualNumber(/** @type {AdminCloudtentaclesVirtualNumberRouteBody} */ (req.body)),
+  {
+    successMessage: 'cloudtentacles 号码退还成功',
+    errorMessage: 'cloudtentacles 号码退还失败',
+    scope: '[admin/platform-config/cloudtentacles/vn/back]',
+  },
+))
+
 router.post('/platform-config/cloudtentacles/debug/full-flow', createJsonHandler(
   (req) => runAdminCloudtentaclesFullFlow(/** @type {AdminCloudtentaclesFullFlowRouteBody} */ (req.body)),
   {

apps/backend/src/services/admin/admin-platform-config-service.js

@@ -49,10 +49,12 @@ import {
   getCloudtentaclesAsset,
   getCloudtentaclesCategories,
   listCloudtentaclesSku,
+  useCloudtentaclesSku,
 } from '../platforms/cloudtentacles/catalog-service.js'
 import { getCloudtentaclesKnapsack } from '../platforms/cloudtentacles/knapsack-service.js'
 import {
   appointCloudtentaclesVirtualNumber,
+  backCloudtentaclesVirtualNumber,
   fetchCloudtentaclesVirtualNumberCode,
   generateCloudtentaclesLoginCode,
   getCloudtentaclesBindUrl,
@@ -87,6 +89,7 @@ import { resolveDisplayShopName } from './admin-read-shared-helpers.js'
 /** @typedef {import('../../types/admin-write-inputs.js').AdminCloudtentaclesValidateSessionInput} AdminCloudtentaclesValidateSessionInput */
 /** @typedef {import('../../types/admin-write-inputs.js').AdminCloudtentaclesCatalogQueryInput} AdminCloudtentaclesCatalogQueryInput */
 /** @typedef {import('../../types/admin-write-inputs.js').AdminCloudtentaclesSkuBuyInput} AdminCloudtentaclesSkuBuyInput */
+/** @typedef {import('../../types/admin-write-inputs.js').AdminCloudtentaclesSkuUseInput} AdminCloudtentaclesSkuUseInput */
 /** @typedef {import('../../types/admin-write-inputs.js').AdminCloudtentaclesVirtualNumberInput} AdminCloudtentaclesVirtualNumberInput */
 /** @typedef {import('../../types/admin-write-inputs.js').AdminCloudtentaclesFullFlowInput} AdminCloudtentaclesFullFlowInput */
 /** @typedef {import('../../types/admin-write-inputs.js').AdminFulfillmentBindingConfigSaveInput} AdminFulfillmentBindingConfigSaveInput */
@@ -629,6 +632,17 @@ export async function buyAdminCloudtentaclesSku(payload = /** @type {AdminCloudt
   })
 }
 
+/** @param {AdminCloudtentaclesSkuUseInput} [payload] */
+export async function useAdminCloudtentaclesSku(payload = /** @type {AdminCloudtentaclesSkuUseInput} */ ({})) {
+  const context = resolveCloudtentaclesAdminContext(payload)
+  return useCloudtentaclesSku({
+    ...context,
+    id: payload.id,
+    virtualNumberId: payload.virtualNumberId,
+    phone: payload.phone,
+  })
+}
+
 /** @param {AdminCloudtentaclesCatalogQueryInput} [payload] */
 export async function getAdminCloudtentaclesKnapsack(payload = /** @type {AdminCloudtentaclesCatalogQueryInput} */ ({})) {
   const context = resolveCloudtentaclesAdminContext(payload)
@@ -694,6 +708,16 @@ export async function getAdminCloudtentaclesBindUrl(payload = /** @type {AdminCl
   })
 }
 
+/** @param {AdminCloudtentaclesVirtualNumberInput} [payload] */
+export async function backAdminCloudtentaclesVirtualNumber(payload = /** @type {AdminCloudtentaclesVirtualNumberInput} */ ({})) {
+  const context = resolveCloudtentaclesAdminContext(payload)
+  return backCloudtentaclesVirtualNumber({
+    ...context,
+    key: payload.key,
+    id: payload.id,
+  })
+}
+
 /** @param {AdminCloudtentaclesFullFlowInput} [payload] */
 export async function runAdminCloudtentaclesFullFlow(payload = /** @type {AdminCloudtentaclesFullFlowInput} */ ({})) {
   const context = resolveCloudtentaclesAdminContext(payload)

apps/backend/src/services/platforms/cloudtentacles/catalog-service.js

@@ -96,6 +96,50 @@ export async function buyCloudtentaclesSku(payload = {}) {
   }
 }
 
+export async function useCloudtentaclesSku(payload = {}) {
+  const token = requireToken(payload.token, 'cloudtentacles 发货缺少 token', 'cloudtentacles_sku_use_missing_token')
+  const skuId = requireId(payload.id, 'cloudtentacles 发货缺少商品 id', 'cloudtentacles_sku_use_missing_id')
+  const virtualNumberId = requireId(
+    payload.virtualNumberId,
+    'cloudtentacles 发货缺少虚拟号 id',
+    'cloudtentacles_sku_use_missing_virtual_number_id',
+  )
+  const phone = String(payload.phone || '').trim()
+  if (!phone) {
+    throw createHttpError('cloudtentacles 发货缺少手机号', {
+      statusCode: 400,
+      errorCode: 'cloudtentacles_sku_use_missing_phone',
+    })
+  }
+
+  const config = resolveCloudtentaclesConfig(payload)
+  const result = await cloudtentaclesRequest(config.skuUsePath, {
+    ...config,
+    method: 'POST',
+    token,
+    body: {
+      id: skuId,
+      virtual_number_id: virtualNumberId,
+      phone,
+    },
+    businessErrorStatusCode: 401,
+    businessErrorCode: 'cloudtentacles_sku_use_failed',
+  })
+
+  const responseData = isPlainObject(result.payload?.data) ? result.payload.data : {}
+
+  return {
+    baseUrl: config.baseUrl,
+    id: skuId,
+    virtualNumberId,
+    phone,
+    sendType: Number(responseData.send_type || 0),
+    note: String(responseData.note || '').trim(),
+    responseMessage: String(result.payload?.message || result.payload?.msg || 'success'),
+    raw: result.payload ?? null,
+  }
+}
+
 function mapCategoryItem(item) {
   const source = isPlainObject(item) ? item : {}
 

apps/backend/src/services/platforms/cloudtentacles/shared.js

@@ -17,6 +17,7 @@ export function resolveCloudtentaclesConfig(overrides = {}) {
     categoriesPath: '/categories/get',
     skuListPath: '/sku/list',
     skuBuyPath: '/sku/buy',
+    skuUsePath: '/sku/use',
     knapsackPath: '/user/get_knapsack',
     vnListPath: '/vn/list',
     vnAppointPath: '/vn/appoint',
@@ -24,6 +25,7 @@ export function resolveCloudtentaclesConfig(overrides = {}) {
     vnVerifCodePath: '/public/vn_verif_code',
     vnVerifyLoginCodePath: '/vn/verify_login_code',
     vnBindUrlPath: '/vn/bind_url',
+    vnBackPath: '/vn/back',
     publicKeyPem: '',
     clientSource: 'ct-client',
     deviceId: '-',
@@ -41,6 +43,7 @@ export function resolveCloudtentaclesConfig(overrides = {}) {
     categoriesPath: normalizePath(overrides.categoriesPath || baseConfig.categoriesPath, '/categories/get'),
     skuListPath: normalizePath(overrides.skuListPath || baseConfig.skuListPath, '/sku/list'),
     skuBuyPath: normalizePath(overrides.skuBuyPath || baseConfig.skuBuyPath, '/sku/buy'),
+    skuUsePath: normalizePath(overrides.skuUsePath || baseConfig.skuUsePath, '/sku/use'),
     knapsackPath: normalizePath(overrides.knapsackPath || baseConfig.knapsackPath, '/user/get_knapsack'),
     vnListPath: normalizePath(overrides.vnListPath || baseConfig.vnListPath, '/vn/list'),
     vnAppointPath: normalizePath(overrides.vnAppointPath || baseConfig.vnAppointPath, '/vn/appoint'),
@@ -54,6 +57,7 @@ export function resolveCloudtentaclesConfig(overrides = {}) {
       '/vn/verify_login_code',
     ),
     vnBindUrlPath: normalizePath(overrides.vnBindUrlPath || baseConfig.vnBindUrlPath, '/vn/bind_url'),
+    vnBackPath: normalizePath(overrides.vnBackPath || baseConfig.vnBackPath, '/vn/back'),
     publicKeyPem: normalizePem(overrides.publicKeyPem || baseConfig.publicKeyPem),
     clientSource: String(overrides.clientSource || baseConfig.clientSource || 'ct-client').trim() || 'ct-client',
     deviceId: String(overrides.deviceId ?? baseConfig.deviceId ?? '-').trim() || '-',

apps/backend/src/services/platforms/cloudtentacles/virtual-number-service.js

@@ -159,6 +159,30 @@ export async function getCloudtentaclesBindUrl(payload = {}) {
   }
 }
 
+export async function backCloudtentaclesVirtualNumber(payload = {}) {
+  const token = requireToken(payload.token, 'cloudtentacles 退还号码缺少 token', 'cloudtentacles_vn_back_missing_token')
+  const key = requireKey(payload.key, 'cloudtentacles 退还号码缺少 key', 'cloudtentacles_vn_back_missing_key')
+  const id = requireId(payload.id, 'cloudtentacles 退还号码缺少 id', 'cloudtentacles_vn_back_missing_id')
+  const config = resolveCloudtentaclesConfig(payload)
+
+  const result = await cloudtentaclesRequest(config.vnBackPath, {
+    ...config,
+    method: 'POST',
+    token,
+    body: { key, id },
+    businessErrorStatusCode: 401,
+    businessErrorCode: 'cloudtentacles_vn_back_failed',
+  })
+
+  return {
+    baseUrl: config.baseUrl,
+    key,
+    id,
+    responseMessage: String(result.payload?.message || result.payload?.msg || 'success'),
+    raw: result.payload ?? null,
+  }
+}
+
 function mapVirtualNumberItem(item) {
   const source = isPlainObject(item) ? item : {}
   const bindInfoText = String(source.bind_info || '').trim()

apps/backend/src/types/admin-route-inputs.js

@@ -86,6 +86,10 @@ export {}
  * @typedef {import('./admin-write-inputs.js').AdminCloudtentaclesSkuBuyInput} AdminCloudtentaclesSkuBuyRouteBody
  */
 
+/**
+ * @typedef {import('./admin-write-inputs.js').AdminCloudtentaclesSkuUseInput} AdminCloudtentaclesSkuUseRouteBody
+ */
+
 /**
  * @typedef {import('./admin-write-inputs.js').AdminCloudtentaclesVirtualNumberInput} AdminCloudtentaclesVirtualNumberRouteBody
  */

apps/backend/src/types/admin-write-inputs.js

@@ -215,6 +215,18 @@ export {}
  * }} AdminCloudtentaclesSkuBuyInput
  */
 
+/**
+ * @typedef {{
+ *   baseUrl?: string
+ *   token?: string
+ *   deviceId?: string
+ *   deviceType?: number | string
+ *   id?: number | string
+ *   virtualNumberId?: number | string
+ *   phone?: string
+ * }} AdminCloudtentaclesSkuUseInput
+ */
+
 /**
  * @typedef {{
  *   baseUrl?: string

apps/backend/src/types/runtime-config.js

@@ -107,6 +107,7 @@ export {}
  *       categoriesPath: string
  *       skuListPath: string
  *       skuBuyPath: string
+ *       skuUsePath: string
  *       knapsackPath: string
  *       vnListPath: string
  *       vnAppointPath: string
@@ -114,6 +115,7 @@ export {}
  *       vnVerifCodePath: string
  *       vnVerifyLoginCodePath: string
  *       vnBindUrlPath: string
+ *       vnBackPath: string
  *       publicKeyPem: string
  *       clientSource: string
  *       deviceId: string

apps/frontend/src/services/admin.ts

@@ -285,6 +285,18 @@ export function buyAdminCloudtentaclesSku(payload: {
   return apiPost<Record<string, unknown>>('/api/v1/admin/platform-config/cloudtentacles/sku/buy', payload)
 }
 
+export function useAdminCloudtentaclesSku(payload: {
+  baseUrl?: string
+  token?: string
+  deviceId?: string
+  deviceType?: number
+  id?: number
+  virtualNumberId?: number
+  phone?: string
+}) {
+  return apiPost<Record<string, unknown>>('/api/v1/admin/platform-config/cloudtentacles/sku/use', payload)
+}
+
 export function fetchAdminCloudtentaclesKnapsack(payload: {
   baseUrl?: string
   token?: string
@@ -359,6 +371,17 @@ export function fetchAdminCloudtentaclesBindUrl(payload: {
   return apiPost<Record<string, unknown>>('/api/v1/admin/platform-config/cloudtentacles/vn/bind-url', payload)
 }
 
+export function backAdminCloudtentaclesVn(payload: {
+  baseUrl?: string
+  token?: string
+  deviceId?: string
+  deviceType?: number
+  key?: string
+  id?: number
+}) {
+  return apiPost<Record<string, unknown>>('/api/v1/admin/platform-config/cloudtentacles/vn/back', payload)
+}
+
 export function runAdminCloudtentaclesFullFlow(payload: {
   baseUrl?: string
   token?: string

apps/frontend/src/views/admin/AdminPlatformShopsView.vue

@@ -4,6 +4,7 @@ import { computed, onMounted, ref } from 'vue'
 import { showError, showSuccess } from '@/lib/feedback'
 import {
   appointAdminCloudtentaclesVn,
+  backAdminCloudtentaclesVn,
   buyAdminCloudtentaclesSku,
   consumeAdminKuaishouEticket,
   fetchAdminCloudtentaclesAsset,
@@ -30,6 +31,7 @@ import {
   syncAdminKhhaoOrders,
   testAdminCloudtentaclesLogin,
   testAdminKhhaoLogin,
+  useAdminCloudtentaclesSku,
   validateAdminCloudtentaclesSession,
   verifyAdminCloudtentaclesVnCode,
 } from '@/services/admin'
@@ -1023,6 +1025,16 @@ async function handleCloudtentaclesBuySku() {
   }))
 }
 
+async function handleCloudtentaclesUseSku() {
+  if (!ensureCloudtentaclesToken()) return
+  await runCloudtentaclesDebugAction('执行发货', () => useAdminCloudtentaclesSku({
+    ...buildCloudtentaclesTokenPayload(),
+    id: Number(cloudtentaclesForm.value.skuId || 0),
+    virtualNumberId: Number(cloudtentaclesForm.value.vnId || 0),
+    phone: cloudtentaclesForm.value.phone.trim(),
+  }))
+}
+
 async function handleCloudtentaclesFetchKnapsack() {
   if (!ensureCloudtentaclesToken()) return
   await runCloudtentaclesDebugAction('查询背包', () => fetchAdminCloudtentaclesKnapsack(buildCloudtentaclesTokenPayload()))
@@ -1098,6 +1110,15 @@ async function handleCloudtentaclesFetchBindUrl() {
   }))
 }
 
+async function handleCloudtentaclesBackVn() {
+  if (!ensureCloudtentaclesToken()) return
+  await runCloudtentaclesDebugAction('退还号码', () => backAdminCloudtentaclesVn({
+    ...buildCloudtentaclesTokenPayload(),
+    key: cloudtentaclesForm.value.vnKey.trim(),
+    id: Number(cloudtentaclesForm.value.vnId || 0),
+  }))
+}
+
 async function handleCloudtentaclesRunFullFlow() {
   if (!ensureCloudtentaclesToken()) return
   await runCloudtentaclesDebugAction('完整测试流程', () => runAdminCloudtentaclesFullFlow({
@@ -2025,20 +2046,22 @@ onMounted(loadConfigs)
             <div class="section-title-row">
               <div>
                 <h3>cloudtentacles 开发调试工具</h3>
-                <p>仅开发模式展示。用于调试分类、SKU、购买、背包、虚拟号和兑换链接链路。</p>
+                <p>仅开发模式展示。用于调试分类、SKU、购买、发货、虚拟号、兑换链接和结束退还链路。</p>
               </div>
               <div class="section-actions">
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchAsset">余额</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchCategories">分类</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchSkuList">SKU</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesBuySku">购买</el-button>
+                <el-button :loading="cloudtentaclesDebugLoading" round type="primary" @click="handleCloudtentaclesUseSku">发货</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchKnapsack">背包</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchVnList">虚拟号列表</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesAppointVn">申请虚拟号</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesGenerateVnLoginCode">生成登录码</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchVnCode">获取验证码</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesVerifyVnCode">校验验证码</el-button>
-                <el-button :loading="cloudtentaclesDebugLoading" round type="primary" @click="handleCloudtentaclesFetchBindUrl">兑换链接</el-button>
+                <el-button :loading="cloudtentaclesDebugLoading" round @click="handleCloudtentaclesFetchBindUrl">兑换链接</el-button>
+                <el-button :loading="cloudtentaclesDebugLoading" round type="warning" @click="handleCloudtentaclesBackVn">退还号码</el-button>
                 <el-button :loading="cloudtentaclesDebugLoading" round type="success" @click="handleCloudtentaclesRunFullFlow">完整流程</el-button>
               </div>
             </div>