feat(edit): 服务端代码拆分、优化

apps/api/src/product-editor/product-editor.controller.ts

@@ -25,11 +25,13 @@ type Response = { status: (value: number) => Response };
 
 @Controller()
 export class ProductEditorController {
+    /** 注入所有商品编辑接口共用的工作流服务。 */
     public constructor(
         @Inject(ProductEditorService)
         private readonly editor: ProductEditorService,
     ) {}
 
+    /** 为采集记录创建或复用当前平台的商品编辑上下文。 */
     @Post('collection-items/:collectionItemId/editor-contexts')
     async enter(
         @Param('collectionItemId') collectionItemId: string,
@@ -50,6 +52,7 @@ export class ProductEditorController {
         return result.body;
     }
 
+    /** 返回当前平台下完整的商品编辑读模型。 */
     @Get('products/:productId/editor')
     async read(
         @Param('productId') productId: string,
@@ -65,6 +68,7 @@ export class ProductEditorController {
         };
     }
 
+    /** 返回目标店铺已缓存的类目树，供编辑器选择。 */
     @Get('product-platform-profiles/:profileId/category-options')
     async categoryOptions(
         @Param('profileId') profileId: string,
@@ -84,6 +88,7 @@ export class ProductEditorController {
         };
     }
 
+    /** 返回所选类目的缓存动态属性定义。 */
     @Get('product-platform-profiles/:profileId/attribute-schema')
     async attributeSchema(
         @Param('profileId') profileId: string,
@@ -103,6 +108,7 @@ export class ProductEditorController {
         };
     }
 
+    /** 幂等地创建所选类目属性定义的刷新任务。 */
     @Post('product-platform-profiles/:profileId/attribute-schema-syncs')
     async attributeSchemaSync(
         @Param('profileId') profileId: string,
@@ -125,6 +131,7 @@ export class ProductEditorController {
         return result.body;
     }
 
+    /** 从本地缓存中查询属性字典值。 */
     @Get(
         'product-platform-profiles/:profileId/attribute-dictionaries/:dictionaryId',
     )
@@ -152,6 +159,7 @@ export class ProductEditorController {
         };
     }
 
+    /** 本地缓存不足时幂等地创建远程字典查询任务。 */
     @Post(
         'product-platform-profiles/:profileId/attribute-dictionaries/:dictionaryId/syncs',
     )
@@ -182,6 +190,7 @@ export class ProductEditorController {
         return result.body;
     }
 
+    /** 校验并原子保存商品及其上架草稿。 */
     @Put('products/:productId/editor-draft')
     async save(
         @Param('productId') productId: string,
@@ -219,6 +228,7 @@ export class ProductEditorController {
     }
 }
 
+/** 校验路由参数或请求头中的 UUID，并返回原始值。 */
 function requiredUuid(field: string, value: string | undefined) {
     if (value && z.uuid().safeParse(value).success) return value;
     throw new ApiError(400, 'VALIDATION_FAILED', '请求参数不符合要求', [
@@ -226,11 +236,13 @@ function requiredUuid(field: string, value: string | undefined) {
     ]);
 }
 
+/** 将缺省查询参数保留为 undefined；有值时校验其 UUID 格式。 */
 function optionalUuid(field: string, value: string | undefined) {
     if (value === undefined || value === '') return undefined;
     return requiredUuid(field, value);
 }
 
+/** 解析 If-Match 中成对传递的商品和发布配置版本号。 */
 function parseEditorRevision(value: string | undefined) {
     const match = value?.match(/^"([1-9]\d*):([1-9]\d*)"$/);
     if (!match)