feat(order-service): 优化用户引导图配置与展示

apps/backend/src/services/worker-platform/order-service-profile-service.test.ts

@@ -94,6 +94,19 @@ test('订单服务提交后说明：旧配置使用默认文案，新配置支
   )
 })
 
+test('用户引导图：说明文字随图片配置保存，旧配置默认不显示说明', () => {
+  assert.equal(config().guideImageDescription, '')
+  const normalized = config({
+    guideImage: {
+      objectKey: 'order-service/guide.webp',
+      url: '/api/v1/files/object?key=order-service%2Fguide.webp',
+    },
+    guideImageDescription: '请截图买家个人主页，并确认游戏 ID 清晰可见。',
+  })
+  assert.equal(normalized.guideImageDescription, '请截图买家个人主页，并确认游戏 ID 清晰可见。')
+  assert.equal(normalized.guideImage.description, '请截图买家个人主页，并确认游戏 ID 清晰可见。')
+})
+
 test('客户状态进度：四个节点支持独立标题和说明，旧配置使用默认文案', () => {
   assert.deepEqual(config().statusSteps, {
     submitted: { title: '提交资料', description: '' },

apps/backend/src/services/worker-platform/order-service-profile-service.ts

@@ -69,6 +69,7 @@ export type OrderServiceProfileConfig = {
   title: string
   description: string
   guideImage: Record<string, unknown>
+  guideImageDescription: string
   fields: OrderServiceField[]
   screenshots: OrderServiceScreenshots
   autoPublish: OrderServiceAutoPublish
@@ -157,7 +158,14 @@ export async function saveAdminOrderServiceProfile(payload: JsonObject = {}) {
     payload.materialConfirmation ?? payload.material_confirmation_json,
   )
   const statusSteps = normalizeStatusSteps(payload.statusSteps ?? payload.status_steps_json)
-  const guideImage = normalizeGuideImage(payload.guideImage ?? payload.guide_image_json)
+  const guideImageDescription = text(
+    payload.guideImageDescription ?? payload.guide_image_description,
+    200,
+  )
+  const guideImage = normalizeGuideImage(
+    payload.guideImage ?? payload.guide_image_json,
+    guideImageDescription,
+  )
   const adminUserId = Number(payload.adminUserId ?? payload.admin_user_id ?? 0) || null
 
   const saved = await upsertOrderServiceProfile({
@@ -246,6 +254,7 @@ function mapAdminProfile(row: OrderServiceProfileRow) {
     title: row.title,
     description: row.description,
     guideImage: row.guide_image_json,
+    guideImageDescription: buildProfileConfig(row).guideImageDescription,
     fields: buildProfileConfig(row).fields,
     screenshots: row.screenshots_json,
     autoPublish: row.auto_publish_json,
@@ -276,11 +285,13 @@ export function buildProfileConfig(row: {
   success_text: string
   post_submit_text: string
 }): OrderServiceProfileConfig & { guideImage: Record<string, unknown> } {
+  const guideImage = normalizeGuideImage(row.guide_image_json)
   return {
     name: row.name,
     title: row.title,
     description: row.description,
-    guideImage: normalizeGuideImage(row.guide_image_json),
+    guideImage,
+    guideImageDescription: readGuideImageDescription(guideImage),
     fields: normalizeFields(row.fields_json),
     screenshots: normalizeScreenshots(row.screenshots_json),
     autoPublish: normalizeAutoPublish(row.auto_publish_json),
@@ -330,11 +341,16 @@ export function isOrderServiceMaterialRequired(config: OrderServiceProfileConfig
 }
 
 export function normalizeProfileConfig(value: JsonObject): OrderServiceProfileConfig {
+  const guideImage = normalizeGuideImage(
+    value.guideImage ?? value.guide_image,
+    value.guideImageDescription ?? value.guide_image_description,
+  )
   return {
     name: text(value.name, 80) || '订单服务配置',
     title: text(value.title, 80),
     description: text(value.description, 300),
-    guideImage: normalizeGuideImage(value.guideImage ?? value.guide_image),
+    guideImage,
+    guideImageDescription: readGuideImageDescription(guideImage),
     fields: normalizeFields(value.fields),
     screenshots: normalizeScreenshots(value.screenshots),
     autoPublish: normalizeAutoPublish(value.autoPublish),
@@ -459,9 +475,20 @@ function normalizeStatusStep(value: unknown, fallback: { title: string; descript
   }
 }
 
-function normalizeGuideImage(value: unknown): Record<string, unknown> {
+function normalizeGuideImage(value: unknown, descriptionInput?: unknown): Record<string, unknown> {
+  const source =
+    value && typeof value === 'object' && !Array.isArray(value) ? (value as JsonObject) : {}
   const normalized = normalizeUploadedFiles([value])[0]
-  return normalized ? { ...normalized } : {}
+  if (!normalized) return {}
+  const description = text(descriptionInput ?? source.description ?? source.guideDescription, 200)
+  return {
+    ...normalized,
+    ...(description ? { description } : {}),
+  }
+}
+
+function readGuideImageDescription(value: Record<string, unknown>) {
+  return text(value.description, 200)
 }
 
 function clampInteger(value: unknown, fallback: number, min: number, max: number) {

apps/backend/src/services/worker-platform/order-service-public-service.ts

@@ -93,6 +93,7 @@ export type OrderServicePublicItem = {
   screenshots?: Array<Record<string, unknown>>
   screenshotsRule?: OrderServiceProfileConfig['screenshots']
   guideImage?: Record<string, unknown>
+  guideImageDescription?: string
   acceptanceImageUrls?: string[]
   acceptanceVideo?: OrderServiceAcceptanceVideo
   submittedAt?: string
@@ -537,6 +538,7 @@ async function mapPublicOrderItem(order: WorkOrderRow): Promise<OrderServicePubl
   return {
     ...base,
     guideImage: profile?.guideImage || {},
+    guideImageDescription: profile?.guideImageDescription || '',
   }
 }
 
@@ -565,6 +567,7 @@ async function resolveProfileConfig(
       title: '',
       description: '',
       guideImage: {},
+      guideImageDescription: '',
       fields: normalizeProfileConfig({
         name: '通用资料',
         fields: legacy.fields,