产品标签关联接口实现

李曜臣
1 parent 13b6d2e3
Showing 17 changed files with 910 additions and 42 deletions
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/Label/LabelGetListOutputDto.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/Picture/PictureUploadInputVo.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/Picture/PictureUploadOutputDto.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/ProductCategory/ProductCategoryCreateInputVo.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/ProductCategory/ProductCategoryGetListInputVo.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/ProductCategory/ProductCategoryGetListOutputDto.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/ProductCategory/ProductCategoryGetOutputDto.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/Dtos/ProductCategory/ProductCategoryUpdateInputVo.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/IServices/IPictureAppService.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application.Contracts/IServices/IProductCategoryAppService.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application/Services/LabelAppService.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application/Services/PictureAppService.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/module/food-labeling-us/FoodLabeling.Application/Services/ProductCategoryAppService.cs
美国版/Food Labeling Management Code/Yi.Abp.Net8/src/Yi.Abp.Web/YiAbpWebModule.cs
项目相关文档/产品模块Categories接口对接说明.md
项目相关文档/平台端Categories图片上传接口说明.md
项目相关文档/标签模块接口对接说明.md
@@ -12,7 +12,10 @@ public class LabelGetListOutputDto
     public string ProductCategoryName { get; set; } = string.Empty;
-    public string ProductName { get; set; } = string.Empty;
+    /// <summary>
+    /// 同一个标签绑定的产品名称，用 “,” 分割
+    /// </summary>
+    public string Products { get; set; } = string.Empty;
     public string TemplateName { get; set; } = string.Empty;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace FoodLabeling.Application.Contracts.Dtos.Picture;
+
+public class PictureUploadInputVo
+{
+    [FromForm(Name = "file")]
+    public IFormFile File { get; set; } = default!;
+
+    /// <summary>
+    /// 可选子目录（相对路径），例如：category、category/2026-03
+    /// </summary>
+    [FromForm(Name = "subDir")]
+    public string? SubDir { get; set; }
+}
+
+namespace FoodLabeling.Application.Contracts.Dtos.Picture;
+
+public class PictureUploadOutputDto
+{
+    /// <summary>
+    /// 可直接保存到业务表的访问 URL（相对路径）
+    /// </summary>
+    public string Url { get; set; } = string.Empty;
+
+    public string FileName { get; set; } = string.Empty;
+
+    public long Size { get; set; }
+}
+
+namespace FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+
+/// <summary>
+/// 产品模块：新增类别入参
+/// </summary>
+public class ProductCategoryCreateInputVo
+{
+    public string CategoryCode { get; set; } = string.Empty;
+
+    public string CategoryName { get; set; } = string.Empty;
+
+    public string? CategoryPhotoUrl { get; set; }
+
+    public bool State { get; set; } = true;
+
+    public int OrderNum { get; set; } = 0;
+}
+
+using Volo.Abp.Application.Dtos;
+
+namespace FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+
+/// <summary>
+/// 产品模块：类别分页列表入参
+/// </summary>
+public class ProductCategoryGetListInputVo : PagedAndSortedResultRequestDto
+{
+    /// <summary>
+    /// 模糊搜索（CategoryCode/CategoryName）
+    /// </summary>
+    public string? Keyword { get; set; }
+
+    /// <summary>
+    /// 启用状态过滤
+    /// </summary>
+    public bool? State { get; set; }
+}
+
+namespace FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+
+/// <summary>
+/// 产品模块：类别列表行
+/// </summary>
+public class ProductCategoryGetListOutputDto
+{
+    public string Id { get; set; } = string.Empty;
+
+    public string CategoryCode { get; set; } = string.Empty;
+
+    public string CategoryName { get; set; } = string.Empty;
+
+    public string? CategoryPhotoUrl { get; set; }
+
+    public bool State { get; set; }
+
+    public int OrderNum { get; set; }
+
+    public DateTime LastEdited { get; set; }
+}
+
+namespace FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+
+/// <summary>
+/// 产品模块：类别详情
+/// </summary>
+public class ProductCategoryGetOutputDto
+{
+    public string Id { get; set; } = string.Empty;
+
+    public string CategoryCode { get; set; } = string.Empty;
+
+    public string CategoryName { get; set; } = string.Empty;
+
+    public string? CategoryPhotoUrl { get; set; }
+
+    public bool State { get; set; }
+
+    public int OrderNum { get; set; }
+}
+
+namespace FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+
+/// <summary>
+/// 产品模块：编辑类别入参
+/// </summary>
+public class ProductCategoryUpdateInputVo : ProductCategoryCreateInputVo
+{
+}
+
+using FoodLabeling.Application.Contracts.Dtos.Picture;
+
+namespace FoodLabeling.Application.Contracts.IServices;
+
+public interface IPictureAppService
+{
+    Task<PictureUploadOutputDto> UploadCategoryAsync(PictureUploadInputVo input);
+}
+
+using FoodLabeling.Application.Contracts.Dtos.Common;
+using FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+using Volo.Abp.Application.Services;
+
+namespace FoodLabeling.Application.Contracts.IServices;
+
+/// <summary>
+/// 产品模块：类别（Categories）接口
+/// </summary>
+public interface IProductCategoryAppService : IApplicationService
+{
+    Task<PagedResultWithPageDto<ProductCategoryGetListOutputDto>> GetListAsync(ProductCategoryGetListInputVo input);
+
+    Task<ProductCategoryGetOutputDto> GetAsync(string id);
+
+    Task<ProductCategoryGetOutputDto> CreateAsync(ProductCategoryCreateInputVo input);
+
+    Task<ProductCategoryGetOutputDto> UpdateAsync(string id, ProductCategoryUpdateInputVo input);
+
+    Task DeleteAsync(string id);
+}
+
@@ -39,55 +39,122 @@ public class LabelAppService : ApplicationService, ILabelAppService
         var labelTypeId = input.LabelTypeId?.Trim();
         var templateCode = input.TemplateCode?.Trim();
-        // 先查 label-product 映射（按产品）
-        var query = _dbContext.SqlSugarClient.Queryable<FlLabelProductDbEntity, FlLabelDbEntity, FlProductDbEntity, FlLabelCategoryDbEntity, FlLabelTypeDbEntity, FlLabelTemplateDbEntity>(
-                (lp, l, p, c, t, tpl) =>
-                    lp.LabelId == l.Id &&
-                    lp.ProductId == p.Id &&
-                    l.LabelCategoryId == c.Id &&
-                    l.LabelTypeId == t.Id &&
-                    l.TemplateId == tpl.Id)
-            .Where((lp, l, p, c, t, tpl) => l.IsDeleted == false)
-            .Where((lp, l, p, c, t, tpl) => !c.IsDeleted)
-            .Where((lp, l, p, c, t, tpl) => !t.IsDeleted)
-            .Where((lp, l, p, c, t, tpl) => !tpl.IsDeleted)
-            .Where((lp, l, p, c, t, tpl) => !p.IsDeleted)
-            .WhereIF(!string.IsNullOrWhiteSpace(productId), (lp, l, p, c, t, tpl) => lp.ProductId == productId)
-            .WhereIF(!string.IsNullOrWhiteSpace(locationId), (lp, l, p, c, t, tpl) => l.LocationId == locationId)
-            .WhereIF(!string.IsNullOrWhiteSpace(labelCategoryId), (lp, l, p, c, t, tpl) => l.LabelCategoryId == labelCategoryId)
-            .WhereIF(!string.IsNullOrWhiteSpace(labelTypeId), (lp, l, p, c, t, tpl) => l.LabelTypeId == labelTypeId)
-            .WhereIF(!string.IsNullOrWhiteSpace(templateCode), (lp, l, p, c, t, tpl) => tpl.TemplateCode == templateCode)
-            .WhereIF(!string.IsNullOrWhiteSpace(keyword),
-                (lp, l, p, c, t, tpl) =>
+        // 目标：列表每行是“标签”，同一个标签下的 products 以 “,” 拼接展示
+        // 因此需要按 label 维度分页（避免 label-product join 导致重复行与分页错乱）。
+
+        var labelIdsQuery = _dbContext.SqlSugarClient.Queryable<FlLabelDbEntity>()
+            .Where(l => !l.IsDeleted)
+            .WhereIF(!string.IsNullOrWhiteSpace(locationId), l => l.LocationId == locationId)
+            .WhereIF(!string.IsNullOrWhiteSpace(labelCategoryId), l => l.LabelCategoryId == labelCategoryId)
+            .WhereIF(!string.IsNullOrWhiteSpace(labelTypeId), l => l.LabelTypeId == labelTypeId)
+            .WhereIF(input.State != null, l => l.State == input.State);
+
+        if (!string.IsNullOrWhiteSpace(templateCode))
+        {
+            labelIdsQuery = labelIdsQuery
+                .InnerJoin<FlLabelTemplateDbEntity>((l, tpl) => l.TemplateId == tpl.Id)
+                .Where((l, tpl) => !tpl.IsDeleted && tpl.TemplateCode == templateCode)
+                .Select((l, tpl) => l);
+        }
+
+        // 按产品筛选：存在 label-product 关联即可
+        if (!string.IsNullOrWhiteSpace(productId))
+        {
+            labelIdsQuery = labelIdsQuery
+                .InnerJoin<FlLabelProductDbEntity>((l, lp) => lp.LabelId == l.Id)
+                .Where((l, lp) => lp.ProductId == productId)
+                .Select((l, lp) => l);
+        }
+
+        // 关键字：匹配 labelName/categoryName/typeName/templateName/productName
+        if (!string.IsNullOrWhiteSpace(keyword))
+        {
+            labelIdsQuery = labelIdsQuery
+                .LeftJoin<FlLabelCategoryDbEntity>((l, c) => l.LabelCategoryId == c.Id)
+                .LeftJoin<FlLabelTypeDbEntity>((l, c, t) => l.LabelTypeId == t.Id)
+                .LeftJoin<FlLabelTemplateDbEntity>((l, c, t, tpl) => l.TemplateId == tpl.Id)
+                .LeftJoin<FlLabelProductDbEntity>((l, c, t, tpl, lp) => lp.LabelId == l.Id)
+                .LeftJoin<FlProductDbEntity>((l, c, t, tpl, lp, p) => lp.ProductId == p.Id)
+                .Where((l, c, t, tpl, lp, p) =>
                     l.LabelName.Contains(keyword!) ||
-                    p.ProductName.Contains(keyword!) ||
-                    c.CategoryName.Contains(keyword!) ||
-                    t.TypeName.Contains(keyword!))
-            .WhereIF(input.State != null, (lp, l, p, c, t, tpl) => l.State == input.State)
-            .OrderByDescending((lp, l, p, c, t, tpl) => l.LastModificationTime ?? l.CreationTime);
+                    (c.CategoryName != null && c.CategoryName.Contains(keyword!)) ||
+                    (t.TypeName != null && t.TypeName.Contains(keyword!)) ||
+                    (tpl.TemplateName != null && tpl.TemplateName.Contains(keyword!)) ||
+                    (p.ProductName != null && p.ProductName.Contains(keyword!)))
+                .Select((l, c, t, tpl, lp, p) => l);
+        }
+        // 排序（优先外部 Sorting，否则按最后编辑倒序）
         if (!string.IsNullOrWhiteSpace(input.Sorting))
         {
-            query = query.OrderBy(input.Sorting);
+            labelIdsQuery = labelIdsQuery.OrderBy(input.Sorting);
+        }
+        else
+        {
+            labelIdsQuery = labelIdsQuery.OrderByDescending(l => l.LastModificationTime ?? l.CreationTime);
+        }
+
+        var pageLabelIds = await labelIdsQuery
+            .Select(l => l.Id)
+            .Distinct()
+            .ToPageListAsync(input.SkipCount, input.MaxResultCount, total);
+
+        if (pageLabelIds.Count == 0)
+        {
+            return new PagedResultWithPageDto<LabelGetListOutputDto>
+            {
+                PageIndex = 1,
+                PageSize = input.MaxResultCount,
+                TotalCount = total,
+                TotalPages = 0,
+                Items = new List<LabelGetListOutputDto>()
+            };
         }
-        var entities = await query.Select((lp, l, p, c, t, tpl) => new
+        // 查询标签基础信息（分类/类型/模板）
+        var labelRows = await _dbContext.SqlSugarClient
+            .Queryable<FlLabelDbEntity, FlLabelCategoryDbEntity, FlLabelTypeDbEntity, FlLabelTemplateDbEntity>(
+                (l, c, t, tpl) => l.LabelCategoryId == c.Id && l.LabelTypeId == t.Id && l.TemplateId == tpl.Id)
+            .Where((l, c, t, tpl) => pageLabelIds.Contains(l.Id))
+            .Where((l, c, t, tpl) => !l.IsDeleted && !c.IsDeleted && !t.IsDeleted && !tpl.IsDeleted)
+            .Select((l, c, t, tpl) => new
             {
-                LabelCode = l.LabelCode,
-                LabelName = l.LabelName,
-                LocationId = l.LocationId,
-                LocationName = (string?)null, // later fill
+                l.Id,
+                l.LabelCode,
+                l.LabelName,
+                l.LocationId,
                 LabelCategoryName = c.CategoryName,
-                ProductCategoryName = p.CategoryName,
-                ProductName = p.ProductName,
-                TemplateName = tpl.TemplateName,
                 LabelTypeName = t.TypeName,
-                State = l.State,
+                TemplateName = tpl.TemplateName,
+                l.State,
                 LastEdited = l.LastModificationTime ?? l.CreationTime
             })
-            .ToPageListAsync(input.SkipCount, input.MaxResultCount, total);
+            .ToListAsync();
+
+        // 按分页顺序输出
+        var labelMap = labelRows.ToDictionary(x => x.Id, x => x);
+        var orderedLabels = pageLabelIds.Where(id => labelMap.ContainsKey(id)).Select(id => labelMap[id]).ToList();
+
+        // 查询 products 并拼接
+        var productRows = await _dbContext.SqlSugarClient
+            .Queryable<FlLabelProductDbEntity, FlLabelDbEntity, FlProductDbEntity>(
+                (lp, l, p) => lp.LabelId == l.Id && lp.ProductId == p.Id)
+            .Where((lp, l, p) => pageLabelIds.Contains(lp.LabelId))
+            .Where((lp, l, p) => !l.IsDeleted && !p.IsDeleted)
+            .Select((lp, l, p) => new { lp.LabelId, p.ProductName, p.CategoryName })
+            .ToListAsync();
+
+        var productsMap = productRows
+            .GroupBy(x => x.LabelId)
+            .ToDictionary(
+                g => g.Key,
+                g => new
+                {
+                    Products = string.Join(",", g.Select(x => x.ProductName ?? string.Empty).Select(x => x.Trim()).Where(x => !string.IsNullOrWhiteSpace(x)).Distinct()),
+                    ProductCategoryName = string.Join(",", g.Select(x => x.CategoryName ?? string.Empty).Select(x => x.Trim()).Where(x => !string.IsNullOrWhiteSpace(x)).Distinct())
+                });
-        var locationIds = entities
+        var locationIds = orderedLabels
             .Select(x => x.LocationId)
             .Where(x => !string.IsNullOrWhiteSpace(x))
             .Select(x => x!.Trim())
@@ -108,21 +175,23 @@ public class LabelAppService : ApplicationService, ILabelAppService
             }
         }
-        var items = entities.Select(x =>
+        var items = orderedLabels.Select(x =>
         {
             var locationName = string.Empty;
             if (!string.IsNullOrWhiteSpace(x.LocationId) && locationMap.TryGetValue(x.LocationId!, out var loc))
             {
                 locationName = loc.LocationName ?? loc.LocationCode;
             }
+            var products = productsMap.TryGetValue(x.Id, out var prod) ? prod.Products : string.Empty;
+            var productCategoryNameValue = productsMap.TryGetValue(x.Id, out var prod2) ? prod2.ProductCategoryName : string.Empty;
             return new LabelGetListOutputDto
             {
                 Id = x.LabelCode ?? string.Empty,
                 LabelName = x.LabelName ?? string.Empty,
                 LocationName = string.IsNullOrWhiteSpace(locationName) ? "无" : locationName,
                 LabelCategoryName = x.LabelCategoryName ?? string.Empty,
-                ProductCategoryName = x.ProductCategoryName ?? string.Empty,
-                ProductName = x.ProductName ?? string.Empty,
+                ProductCategoryName = string.IsNullOrWhiteSpace(productCategoryNameValue) ? "无" : productCategoryNameValue,
+                Products = products,
                 TemplateName = x.TemplateName ?? string.Empty,
                 LabelTypeName = x.LabelTypeName ?? string.Empty,
                 State = x.State,
+using FoodLabeling.Application.Contracts.Dtos.Picture;
+using FoodLabeling.Application.Contracts.IServices;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Hosting;
+using Volo.Abp;
+using Volo.Abp.Application.Services;
+using Volo.Abp.Guids;
+
+namespace FoodLabeling.Application.Services;
+
+public class PictureAppService : ApplicationService, IPictureAppService
+{
+    private const long MaxSizeBytes = 5 * 1024 * 1024;
+    private static readonly HashSet<string> AllowedExtensions = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ".jpg",
+        ".jpeg",
+        ".png",
+        ".webp",
+        ".gif"
+    };
+
+    private readonly IGuidGenerator _guidGenerator;
+    private readonly IHostEnvironment _hostEnvironment;
+
+    public PictureAppService(IGuidGenerator guidGenerator, IHostEnvironment hostEnvironment)
+    {
+        _guidGenerator = guidGenerator;
+        _hostEnvironment = hostEnvironment;
+    }
+
+    /// <summary>
+    /// 上传类别图片（保存到 /www/wwwroot/FoodLabelingManagementUs/picture）
+    /// </summary>
+    /// <remarks>返回的 Url 可直接保存到 CategoryPhotoUrl。</remarks>
+    [HttpPost]
+    [Consumes("multipart/form-data")]
+    [Route("/api/app/picture/category/upload")]
+    public async Task<PictureUploadOutputDto> UploadCategoryAsync([FromForm] PictureUploadInputVo input)
+    {
+        if (input.File is null || input.File.Length <= 0)
+        {
+            throw new UserFriendlyException("请选择要上传的图片文件");
+        }
+
+        if (input.File.Length > MaxSizeBytes)
+        {
+            throw new UserFriendlyException("图片大小不能超过5MB");
+        }
+
+        var ext = Path.GetExtension(input.File.FileName ?? string.Empty);
+        if (string.IsNullOrWhiteSpace(ext) || !AllowedExtensions.Contains(ext))
+        {
+            throw new UserFriendlyException("仅支持上传 jpg/jpeg/png/webp/gif 格式图片");
+        }
+
+        var subDir = NormalizeSubDir(input.SubDir);
+        var saveRoot = ResolvePictureRoot();
+        var saveDir = string.IsNullOrWhiteSpace(subDir) ? saveRoot : Path.Combine(saveRoot, subDir);
+        Directory.CreateDirectory(saveDir);
+
+        var fileName = $"{DateTime.Now:yyyyMMddHHmmss}_{_guidGenerator.Create():N}{ext.ToLowerInvariant()}";
+        var savePath = Path.Combine(saveDir, fileName);
+
+        await using (var stream = new FileStream(savePath, FileMode.CreateNew, FileAccess.Write, FileShare.None))
+        {
+            await input.File.CopyToAsync(stream);
+        }
+
+        var url = BuildPictureUrl(subDir, fileName);
+        return new PictureUploadOutputDto
+        {
+            Url = url,
+            FileName = fileName,
+            Size = input.File.Length
+        };
+    }
+
+    private string ResolvePictureRoot()
+    {
+        var linuxPictureRoot = "/www/wwwroot/FoodLabelingManagementUs/picture";
+        var webRootPicture = Path.Combine(_hostEnvironment.ContentRootPath, "wwwroot", "FoodLabelingManagementUs", "picture");
+        return Directory.Exists(linuxPictureRoot) ? linuxPictureRoot : webRootPicture;
+    }
+
+    private static string NormalizeSubDir(string? subDir)
+    {
+        if (string.IsNullOrWhiteSpace(subDir))
+        {
+            return string.Empty;
+        }
+
+        var s = subDir.Trim().Replace('\\', '/');
+        while (s.StartsWith('/'))
+        {
+            s = s[1..];
+        }
+
+        if (s.Contains("..", StringComparison.Ordinal))
+        {
+            throw new UserFriendlyException("subDir 不能包含 ..");
+        }
+
+        return s;
+    }
+
+    private static string BuildPictureUrl(string? subDir, string fileName)
+    {
+        var s = string.IsNullOrWhiteSpace(subDir) ? string.Empty : $"/{subDir.Trim().Replace('\\', '/').Trim('/')}";
+        return $"/picture{s}/{fileName}";
+    }
+}
+
+using FoodLabeling.Application.Contracts.Dtos.Common;
+using FoodLabeling.Application.Contracts.Dtos.ProductCategory;
+using FoodLabeling.Application.Contracts.IServices;
+using FoodLabeling.Application.Services.DbModels;
+using SqlSugar;
+using Volo.Abp;
+using Volo.Abp.Application.Services;
+using Volo.Abp.Guids;
+using Yi.Framework.SqlSugarCore.Abstractions;
+
+namespace FoodLabeling.Application.Services;
+
+/// <summary>
+/// 产品模块：类别（Categories）服务，对外仅在 food-labeling-us 暴露
+/// </summary>
+public class ProductCategoryAppService : ApplicationService, IProductCategoryAppService
+{
+    private readonly ISqlSugarDbContext _dbContext;
+    private readonly IGuidGenerator _guidGenerator;
+
+    public ProductCategoryAppService(ISqlSugarDbContext dbContext, IGuidGenerator guidGenerator)
+    {
+        _dbContext = dbContext;
+        _guidGenerator = guidGenerator;
+    }
+
+    /// <summary>
+    /// 类别分页列表
+    /// </summary>
+    public async Task<PagedResultWithPageDto<ProductCategoryGetListOutputDto>> GetListAsync(ProductCategoryGetListInputVo input)
+    {
+        RefAsync<int> total = 0;
+        var keyword = input.Keyword?.Trim();
+
+        var query = _dbContext.SqlSugarClient.Queryable<FlLabelCategoryDbEntity>()
+            .Where(x => !x.IsDeleted)
+            .WhereIF(!string.IsNullOrWhiteSpace(keyword),
+                x => x.CategoryCode.Contains(keyword!) || x.CategoryName.Contains(keyword!))
+            .WhereIF(input.State != null, x => x.State == input.State);
+
+        if (!string.IsNullOrWhiteSpace(input.Sorting))
+        {
+            query = query.OrderBy(input.Sorting);
+        }
+        else
+        {
+            query = query.OrderByDescending(x => x.OrderNum).OrderByDescending(x => x.CreationTime);
+        }
+
+        var entities = await query.ToPageListAsync(input.SkipCount, input.MaxResultCount, total);
+
+        var items = entities.Select(x => new ProductCategoryGetListOutputDto
+        {
+            Id = x.Id,
+            CategoryCode = x.CategoryCode,
+            CategoryName = x.CategoryName,
+            CategoryPhotoUrl = x.CategoryPhotoUrl,
+            State = x.State,
+            OrderNum = x.OrderNum,
+            LastEdited = x.LastModificationTime ?? x.CreationTime
+        }).ToList();
+
+        return BuildPagedResult(input.SkipCount, input.MaxResultCount, total, items);
+    }
+
+    /// <summary>
+    /// 类别详情
+    /// </summary>
+    public async Task<ProductCategoryGetOutputDto> GetAsync(string id)
+    {
+        var entity = await _dbContext.SqlSugarClient.Queryable<FlLabelCategoryDbEntity>()
+            .FirstAsync(x => x.Id == id && !x.IsDeleted);
+        if (entity is null)
+        {
+            throw new UserFriendlyException("类别不存在");
+        }
+
+        return MapToGetOutput(entity);
+    }
+
+    /// <summary>
+    /// 新增类别
+    /// </summary>
+    public async Task<ProductCategoryGetOutputDto> CreateAsync(ProductCategoryCreateInputVo input)
+    {
+        var code = input.CategoryCode?.Trim();
+        var name = input.CategoryName?.Trim();
+        if (string.IsNullOrWhiteSpace(code) || string.IsNullOrWhiteSpace(name))
+        {
+            throw new UserFriendlyException("类别编码和名称不能为空");
+        }
+
+        var duplicated = await _dbContext.SqlSugarClient.Queryable<FlLabelCategoryDbEntity>()
+            .AnyAsync(x => !x.IsDeleted && (x.CategoryCode == code || x.CategoryName == name));
+        if (duplicated)
+        {
+            throw new UserFriendlyException("类别编码或名称已存在");
+        }
+
+        var entity = new FlLabelCategoryDbEntity
+        {
+            Id = _guidGenerator.Create().ToString(),
+            CategoryCode = code,
+            CategoryName = name,
+            CategoryPhotoUrl = input.CategoryPhotoUrl?.Trim(),
+            State = input.State,
+            OrderNum = input.OrderNum
+        };
+
+        await _dbContext.SqlSugarClient.Insertable(entity).ExecuteCommandAsync();
+        return await GetAsync(entity.Id);
+    }
+
+    /// <summary>
+    /// 编辑类别
+    /// </summary>
+    public async Task<ProductCategoryGetOutputDto> UpdateAsync(string id, ProductCategoryUpdateInputVo input)
+    {
+        var entity = await _dbContext.SqlSugarClient.Queryable<FlLabelCategoryDbEntity>()
+            .FirstAsync(x => x.Id == id && !x.IsDeleted);
+        if (entity is null)
+        {
+            throw new UserFriendlyException("类别不存在");
+        }
+
+        var code = input.CategoryCode?.Trim();
+        var name = input.CategoryName?.Trim();
+        if (string.IsNullOrWhiteSpace(code) || string.IsNullOrWhiteSpace(name))
+        {
+            throw new UserFriendlyException("类别编码和名称不能为空");
+        }
+
+        var duplicated = await _dbContext.SqlSugarClient.Queryable<FlLabelCategoryDbEntity>()
+            .AnyAsync(x => !x.IsDeleted && x.Id != id && (x.CategoryCode == code || x.CategoryName == name));
+        if (duplicated)
+        {
+            throw new UserFriendlyException("类别编码或名称已存在");
+        }
+
+        entity.CategoryCode = code;
+        entity.CategoryName = name;
+        entity.CategoryPhotoUrl = input.CategoryPhotoUrl?.Trim();
+        entity.State = input.State;
+        entity.OrderNum = input.OrderNum;
+        entity.LastModificationTime = DateTime.Now;
+        entity.LastModifierId = CurrentUser?.Id?.ToString();
+
+        await _dbContext.SqlSugarClient.Updateable(entity).ExecuteCommandAsync();
+        return await GetAsync(id);
+    }
+
+    /// <summary>
+    /// 删除类别（逻辑删除）
+    /// </summary>
+    public async Task DeleteAsync(string id)
+    {
+        var entity = await _dbContext.SqlSugarClient.Queryable<FlLabelCategoryDbEntity>()
+            .FirstAsync(x => x.Id == id && !x.IsDeleted);
+        if (entity is null)
+        {
+            return;
+        }
+
+        // 若被标签引用则不允许删除（保持与 LabelCategory 一致的约束）
+        var used = await _dbContext.SqlSugarClient.Queryable<FlLabelDbEntity>()
+            .AnyAsync(x => !x.IsDeleted && x.LabelCategoryId == id);
+        if (used)
+        {
+            throw new UserFriendlyException("该类别已被标签引用，无法删除");
+        }
+
+        entity.IsDeleted = true;
+        entity.LastModificationTime = DateTime.Now;
+        entity.LastModifierId = CurrentUser?.Id?.ToString();
+        await _dbContext.SqlSugarClient.Updateable(entity).ExecuteCommandAsync();
+    }
+
+    private static ProductCategoryGetOutputDto MapToGetOutput(FlLabelCategoryDbEntity x)
+    {
+        return new ProductCategoryGetOutputDto
+        {
+            Id = x.Id,
+            CategoryCode = x.CategoryCode,
+            CategoryName = x.CategoryName,
+            CategoryPhotoUrl = x.CategoryPhotoUrl,
+            State = x.State,
+            OrderNum = x.OrderNum
+        };
+    }
+
+    private static PagedResultWithPageDto<T> BuildPagedResult<T>(int skipCount, int maxResultCount, int total, List<T> items)
+    {
+        var pageSize = maxResultCount <= 0 ? items.Count : maxResultCount;
+        var pageIndex = pageSize <= 0 ? 1 : (skipCount / pageSize) + 1;
+        var totalPages = pageSize <= 0 ? 0 : (int)Math.Ceiling(total / (double)pageSize);
+        return new PagedResultWithPageDto<T>
+        {
+            PageIndex = pageIndex,
+            PageSize = pageSize,
+            TotalCount = total,
+            TotalPages = totalPages,
+            Items = items
+        };
+    }
+}
+
@@ -12,6 +12,7 @@ using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.StaticFiles;
 using Microsoft.IdentityModel.Tokens;
 using Microsoft.OpenApi.Models;
+using Microsoft.Extensions.FileProviders;
 using StackExchange.Redis;
 using Volo.Abp.AspNetCore.Auditing;
 using Volo.Abp.AspNetCore.Authentication.JwtBearer;
@@ -397,6 +398,19 @@ namespace Yi.Abp.Web
             });
             app.UseDirectoryBrowser("/api/app/wwwroot");
+            // 类别图片静态资源（物理目录 /www/wwwroot/FoodLabelingManagementUs/picture）
+            // - Linux：通常可直接写入与访问
+            // - Windows：如该目录不存在，则使用项目 wwwroot/FoodLabelingManagementUs/picture 作为落盘目录
+            var linuxPictureRoot = "/www/wwwroot/FoodLabelingManagementUs/picture";
+            var webRootPicture = Path.Combine(env.WebRootPath ?? string.Empty, "FoodLabelingManagementUs", "picture");
+            var pictureRoot = Directory.Exists(linuxPictureRoot) ? linuxPictureRoot : webRootPicture;
+            Directory.CreateDirectory(pictureRoot);
+            app.UseStaticFiles(new StaticFileOptions
+            {
+                FileProvider = new PhysicalFileProvider(pictureRoot),
+                RequestPath = "/picture"
+            });
+
             app.Properties.Add("_AbpExceptionHandlingMiddleware_Added", false);
             //工作单元
             app.UseUnitOfWork();
+# 产品模块 Categories（类别）接口对接说明（美国版）
+
+## 概述
+
+本模块用于平台端（H5）Products → **Categories** 页签的数据对接。
+
+- **模块**：`food-labeling-us`
+- **接口前缀**：宿主统一前缀为 `/api/app`
+- **分类表**：`fl_label_category`
+- **图片字段**：`CategoryPhotoUrl`（前端字段：`categoryPhotoUrl`）
+
+> 说明：本文以 Swagger 为准（本地示例：`http://localhost:19001/swagger`，搜索 `ProductCategory`）。
+
+---
+
+## 接口 1：类别分页列表
+
+### HTTP
+
+- **方法**：`GET`
+- **路径**：`/api/app/product-category`
+- **鉴权**：需要登录（Header：`Authorization: Bearer {token}`）
+
+### 入参（Query 参数）
+
+| 参数名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `skipCount` | number | 是 | 跳过条数（分页） |
+| `maxResultCount` | number | 是 | 每页条数（分页） |
+| `sorting` | string | 否 | 排序字段（如 `OrderNum desc`），不传则按 `OrderNum desc, CreationTime desc` |
+| `keyword` | string | 否 | 模糊搜索（匹配 `CategoryCode/CategoryName`） |
+| `state` | boolean | 否 | 启用状态过滤 |
+
+### 请求示例
+
+```http
+GET /api/app/product-category?skipCount=0&maxResultCount=10&keyword=Prep HTTP/1.1
+Host: localhost:19001
+Authorization: Bearer eyJhbGciOi...
+```
+
+### 出参（PagedResultWithPageDto<ProductCategoryGetListOutputDto>）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `pageIndex` | number | 当前页（从 1 开始） |
+| `pageSize` | number | 每页条数 |
+| `totalCount` | number | 总数 |
+| `totalPages` | number | 总页数 |
+| `items` | array | 当前页数据 |
+
+`items[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 主键 |
+| `categoryCode` | string | 类别编码 |
+| `categoryName` | string | 类别名称 |
+| `categoryPhotoUrl` | string \| null | 类别图片 URL（建议用 `/picture/...`） |
+| `state` | boolean | 是否启用 |
+| `orderNum` | number | 排序 |
+| `lastEdited` | string | 最后编辑时间 |
+
+### 响应示例
+
+```json
+{
+  "pageIndex": 1,
+  "pageSize": 10,
+  "totalCount": 1,
+  "totalPages": 1,
+  "items": [
+    {
+      "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
+      "categoryCode": "CAT_PREP",
+      "categoryName": "Prep",
+      "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
+      "state": true,
+      "orderNum": 100,
+      "lastEdited": "2026-03-25 12:30:10"
+    }
+  ]
+}
+```
+
+---
+
+## 接口 2：类别详情
+
+### HTTP
+
+- **方法**：`GET`
+- **路径**：`/api/app/product-category/{id}`
+
+### 请求示例
+
+```http
+GET /api/app/product-category/a2696b9e-2277-11f1-b4c6-00163e0c7c4f HTTP/1.1
+Host: localhost:19001
+Authorization: Bearer eyJhbGciOi...
+```
+
+### 响应示例（ProductCategoryGetOutputDto）
+
+```json
+{
+  "id": "a2696b9e-2277-11f1-b4c6-00163e0c7c4f",
+  "categoryCode": "CAT_PREP",
+  "categoryName": "Prep",
+  "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
+  "state": true,
+  "orderNum": 100
+}
+```
+
+---
+
+## 接口 3：新增类别
+
+### HTTP
+
+- **方法**：`POST`
+- **路径**：`/api/app/product-category`
+- **Content-Type**：`application/json`
+
+### 入参（Body JSON：ProductCategoryCreateInputVo）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `categoryCode` | string | 是 | 类别编码（唯一） |
+| `categoryName` | string | 是 | 类别名称（唯一） |
+| `categoryPhotoUrl` | string \| null | 否 | 图片 URL（建议先上传图片拿到 `/picture/...` 再保存） |
+| `state` | boolean | 否 | 是否启用（默认 true） |
+| `orderNum` | number | 否 | 排序（默认 0） |
+
+### 请求示例
+
+```json
+{
+  "categoryCode": "CAT_PREP",
+  "categoryName": "Prep",
+  "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
+  "state": true,
+  "orderNum": 100
+}
+```
+
+---
+
+## 接口 4：编辑类别
+
+### HTTP
+
+- **方法**：`PUT`
+- **路径**：`/api/app/product-category/{id}`
+- **Content-Type**：`application/json`
+
+### 请求示例
+
+```json
+{
+  "categoryCode": "CAT_PREP",
+  "categoryName": "Prep",
+  "categoryPhotoUrl": "/picture/category/20260325123010_xxx.png",
+  "state": true,
+  "orderNum": 100
+}
+```
+
+---
+
+## 接口 5：删除类别（逻辑删除）
+
+### HTTP
+
+- **方法**：`DELETE`
+- **路径**：`/api/app/product-category/{id}`
+
+### 约束
+
+- 若该类别已被 `fl_label` 引用（`fl_label.LabelCategoryId = id`），删除会失败并返回友好提示：`该类别已被标签引用，无法删除`。
+
+### 请求示例
+
+```http
+DELETE /api/app/product-category/a2696b9e-2277-11f1-b4c6-00163e0c7c4f HTTP/1.1
+Host: localhost:19001
+Authorization: Bearer eyJhbGciOi...
+```
+
+---
+
+## 配套：类别图片上传接口
+
+类别图片上传接口见文档：
+
+- `项目相关文档/平台端Categories图片上传接口说明.md`
+
+推荐前端流程：
+
+1. 调用上传接口 `POST /api/app/picture/category/upload` 拿到响应 `url`
+2. 新增/编辑类别时把 `categoryPhotoUrl` 设为该 `url`
+
+# 平台端 Categories 图片上传接口说明
+
+## 概述
+
+平台端（H5）Products 模块的 **Categories** 页面，类别图片字段为 **`CategoryPhotoUrl`**（后端已在 `fl_label_category` 与分类 CRUD 接口中贯通）。
+
+图片上传由 `food-labeling-us` 模块提供上传接口，文件会保存到服务器目录，并通过静态资源路径 `/picture/...` 直接访问。
+
+---
+
+## 接口：上传类别图片
+
+### HTTP
+
+- **方法**：`POST`
+- **路径**：`/api/app/picture/category/upload`
+- **Content-Type**：`multipart/form-data`
+- **鉴权**：需要登录（Header：`Authorization: Bearer {token}`）
+
+### 表单参数（multipart/form-data）
+
+| 参数名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file` | file | 是 | 图片文件 |
+| `subDir` | string | 否 | 可选子目录（相对路径），例如 `category`、`category/2026-03`；**禁止包含 `..`** |
+
+### 限制
+
+- **大小**：最大 5MB
+- **格式**：仅支持 `jpg/jpeg/png/webp/gif`
+- **文件名策略**：后端自动生成唯一文件名（避免覆盖）
+
+### 请求示例（curl）
+
+Windows（PowerShell/命令行注意路径转义）：
+
+```bash
+curl -X POST "http://localhost:19001/api/app/picture/category/upload" ^
+  -H "Authorization: Bearer <token>" ^
+  -F "file=@C:\\tmp\\category.png" ^
+  -F "subDir=category"
+```
+
+### 请求示例（Postman/Apifox）
+
+- 选择 `POST`
+- URL：`http://localhost:19001/api/app/picture/category/upload`
+- Headers：`Authorization: Bearer <token>`
+- Body：`form-data`
+  - Key=`file`，类型选 `File`，选择图片文件
+  - Key=`subDir`，类型 `Text`，填 `category`（可选）
+
+### 响应体（PictureUploadOutputDto）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | 图片访问的相对路径，可直接保存到 `CategoryPhotoUrl`（例如：`/picture/category/xxx.png`） |
+| `fileName` | string | 服务器保存的文件名 |
+| `size` | number | 文件大小（字节） |
+
+### 响应示例
+
+```json
+{
+  "url": "/picture/category/20260325123010_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png",
+  "fileName": "20260325123010_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png",
+  "size": 123456
+}
+```
+
+---
+
+## 文件保存位置与访问方式
+
+### 落盘目录
+
+后端会按环境自动选择落盘目录（不存在会自动创建）：
+
+- 优先：`/www/wwwroot/FoodLabelingManagementUs/picture`
+- 否则（Windows 本地开发）：`<项目根>/wwwroot/FoodLabelingManagementUs/picture`
+
+### 访问 URL
+
+静态资源映射为：
+
+- `GET /picture/{subDir}/{fileName}`
+
+举例：
+
+- `http://localhost:19001/picture/category/20260325123010_xxx.png`
+
+---
+
+## 如何写入 Categories（CategoryPhotoUrl）
+
+推荐前端流程：
+
+1. 调用本上传接口，拿到返回的 `url`
+2. 再调用分类新增/编辑接口，把 `categoryPhotoUrl` 设置为该 `url`
+
+> 说明：分类 CRUD 已支持 `CategoryPhotoUrl` 字段；你只需要在页面表单里新增该字段即可。
+
@@ -355,7 +355,8 @@ Swagger 地址：
 ## 接口 5：Labels（按产品展示多个标签）
 说明：
-- 列表接口按 `ProductId` 查询，一个产品会对应多条标签记录。
+- 列表接口以“标签”为维度分页展示（同一个标签会绑定多个产品）。
+- 列表支持按 `ProductId` 过滤：仅返回“绑定了该产品”的标签。
 - 标签详情/编辑/删除的 `id` 使用 `fl_label.LabelCode`。
 ### 5.1 分页列表（按产品）
@@ -379,6 +380,11 @@ Swagger 地址：
 }
 ```
+列表出参要点（`LabelGetListOutputDto`）：
+
+- `products`：同一个标签下绑定的产品名称，用 `,` 分割（例如：`Chicken,Sandwich`）
+- 其他字段与之前一致：`labelName/locationName/category/type/template/state/lastEdited...`
+
 ### 5.2 详情
 方法：`GET /api/app/label/{id}`