feat(numbering): unify daily business document numbers (backend)

2026-10-21 07:39:31 +08:00
parent 5d2a1d5b72
commit 8cd822ef8e
158 changed files with 1801 additions and 972 deletions
@@ -0,0 +1,44 @@
+package com.baiyue.common.core.number;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import java.time.Clock;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.time.format.DateTimeFormatter;
+import java.util.Locale;
+import java.util.function.ToLongFunction;
+
+/** 统一业务单号格式；序列仍由各服务自己的 Repository/Mapper 分配。 */
+public final class DailyDocumentNumber {
+    public static final ZoneId BUSINESS_ZONE = ZoneId.of("Asia/Shanghai");
+
+    /** 工具类不允许实例化。 */
+    private DailyDocumentNumber() {}
+
+    /** 先固定北京时间业务日，再使用前缀和日期分配跨客户、跨仓库日流水。 */
+    public static String next(String prefix, Clock clock, ToLongFunction<String> sequences) {
+        requirePrefix(prefix);
+        LocalDate date = LocalDate.now(clock.withZone(BUSINESS_ZONE));
+        String dateText = date.format(DateTimeFormatter.BASIC_ISO_DATE);
+        long value = sequences.applyAsLong(prefix + ":" + dateText);
+        return format(prefix, date, value);
+    }
+
+    /** 严格四位流水，不允许溢出后产生五位号码或退回随机编号。 */
+    public static String format(String prefix, LocalDate date, long value) {
+        requirePrefix(prefix);
+        if (value < 1 || value > 9999) {
+            throw new BizException(ResultCode.CONFLICT, "当日" + prefix + "单据四位流水号已用尽或分配失败");
+        }
+        return prefix + date.format(DateTimeFormatter.BASIC_ISO_DATE)
+            + String.format(Locale.ROOT, "%04d", value);
+    }
+
+    /** 业务类型只能使用两至四位大写字母。 */
+    private static void requirePrefix(String prefix) {
+        if (prefix == null || !prefix.matches("[A-Z]{2,4}")) {
+            throw new IllegalArgumentException("业务单据前缀必须为2至4位大写字母");
+        }
+    }
+}
@@ -0,0 +1,45 @@
+package com.baiyue.common.core.number;
+
+import com.baiyue.common.core.exception.BizException;
+import org.junit.jupiter.api.Test;
+import java.time.*;
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.concurrent.atomic.AtomicReference;
+import static org.assertj.core.api.Assertions.*;
+
+class DailyDocumentNumberTest {
+    /** 午夜前后取号使用北京时间日期，与主机和 Clock 的时区无关。 */
+    @Test void rollsAtShanghaiMidnightAndKeepsPrefixesIndependent() {
+        var values = new HashMap<String, Long>();
+        java.util.function.ToLongFunction<String> allocate = key -> values.merge(key, 1L, Long::sum);
+        var before = Clock.fixed(Instant.parse("2026-10-19T15:59:59Z"), ZoneOffset.UTC);
+        var after = Clock.fixed(Instant.parse("2026-10-19T16:00:00Z"), ZoneId.of("America/Los_Angeles"));
+        assertThat(DailyDocumentNumber.next("FL", before, allocate)).isEqualTo("FL202610190001");
+        assertThat(DailyDocumentNumber.next("FL", after, allocate)).isEqualTo("FL202610200001");
+        assertThat(DailyDocumentNumber.next("FL", after, allocate)).isEqualTo("FL202610200002");
+        assertThat(DailyDocumentNumber.next("ZGRK", after, allocate)).isEqualTo("ZGRK202610200001");
+    }
+
+    /** 字符集和流水上限为硬边界，未知输入不能生成近似号码。 */
+    @Test void rejectsInvalidPrefixAndSequence() {
+        for (String prefix : new String[]{"F", "ABCDE", "Fl", "F1", " FL", ""}) {
+            assertThatThrownBy(() -> DailyDocumentNumber.format(prefix, LocalDate.of(2026, 10, 20), 1))
+                .isInstanceOf(IllegalArgumentException.class);
+        }
+        for (long value : new long[]{-1, 0, 10000}) {
+            assertThatThrownBy(() -> DailyDocumentNumber.format("FL", LocalDate.of(2026, 10, 20), value))
+                .isInstanceOf(BizException.class);
+        }
+        assertThat(DailyDocumentNumber.format("FL", LocalDate.of(2026, 10, 20), 9999)).isEqualTo("FL202610209999");
+    }
+
+    /** 全局 Locale 不得让数字变为本地化字符。 */
+    @Test void alwaysUsesAsciiDigits() {
+        Locale old = Locale.getDefault();
+        try {
+            Locale.setDefault(Locale.forLanguageTag("ar"));
+            assertThat(DailyDocumentNumber.format("FL", LocalDate.of(2026, 10, 20), 1)).isEqualTo("FL202610200001");
+        } finally { Locale.setDefault(old); }
+    }
+}