使用Microsoft Graph API更新Planner清单项时如何正确生成OrderHint

核心规则说明 #

OrderHint按字典序倒序排列：值的字典序越大，对应清单项在列表中越靠前。合法格式必须满足：

• 结构为[排序前缀] ![6位长度后缀]，分隔符是半角空格紧跟半角感叹号，不能省略
• 前缀由可打印ASCII字符组成，负责主要排序权重
• 后缀为6位字母/数字组成的随机串，用于同前缀下的顺序打散，缺失会被服务端判定为不合法值，直接重写所有OrderHint和项ID，导致顺序随机

你之前踩的坑：

• 纯补零数字、纯字母拼接的写法不符合格式要求，直接被接口拦截
• 仅加 !分隔符但缺失6位后缀，服务端不认可传入的排序权重，自动重写值导致乱序
• 用递增长度的A/AA/AAA作为前缀，不仅格式不合法，字典序递增的逻辑也和倒序排序规则相反，本身顺序就是错的

适配场景的实现逻辑 #

你的场景是单次批量创建最多20个清单项，不需要预留中间插入位置，不需要支持手动调整，直接按固定规则生成即可：

• 按行号从1到N的顺序，给每个项分配字典序递减的单字符前缀：第1行（最靠前）分配前缀Z，第2行分配Y，依次类推，20个项用Z到G的单字符完全足够，不会出现数字前缀字典序10排在2前面的排序错误
• 每个项生成独立的6位随机字母数字串作为后缀
• 按格式拼接成合法OrderHint传入即可

修正后的代码 #

// OrderHint后缀可用字符集：大小写字母+数字
private const string OrderHintValidChars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
// 随机数生成器，不要放在循环内
private readonly Random _hintRandom = new Random();

private PlannerChecklistItems CheckListItemsFrom(SapPlannerSyncSalesOrder so)
{
    var checklistItems = new PlannerChecklistItems();
    var soRows = so.Rows;
    if (soRows.Count == 0) return checklistItems;

    for (var i = 0; i < soRows.Count; i++)
    {
        var row = soRows[i];
        // 生成排序前缀：行号越小，前缀字典序越大，排序越靠前
        char orderPrefix = (char)('Z' - i);
        // 生成6位随机后缀
        string orderSuffix = new string(Enumerable.Repeat(OrderHintValidChars, 6)
            .Select(charSet => charSet[_hintRandom.Next(charSet.Length)])
            .ToArray());
        // 拼接为合法格式
        string validOrderHint = $"{orderPrefix} !{orderSuffix}";

        string itemId = Guid.NewGuid().ToString("D");
        checklistItems[itemId] = new PlannerChecklistItem
        {
            Title = row.AsPlannerCheckListTitle(),
            IsChecked = row.IsClosed(),
            OrderHint = validOrderHint
        };
    }

    return checklistItems;
}

注意事项 #

• 你传入的自定义清单项ID会被服务端自动重写，属于正常行为，不影响排序结果
• 提交后服务端可能微调后缀部分的值，但前缀权重保留，最终顺序严格匹配传入的行号顺序
• 重建清单时先传null删除旧项再传新项的逻辑不受影响，新项按上述规则生成hint即可

内容的提问来源于stack exchange，提问作者szab.kel