diff --git a/vendor/dsh-sansheng-liubu/workbench/core/ids.mjs b/vendor/dsh-sansheng-liubu/workbench/core/ids.mjs new file mode 100644 index 0000000..3c4817e --- /dev/null +++ b/vendor/dsh-sansheng-liubu/workbench/core/ids.mjs @@ -0,0 +1,81 @@ +// 稳定随机 ID:所有业务主键都由这里生成,名称/路径只作属性,不复用为键。 +// 随机源可注入,测试里给定字符表就能复现同一串 ID,避免断言依赖运气。 + +const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz' + +/** 方案里出现的所有前缀;拼错前缀属于开发期错误,直接抛而不是静默接受。 */ +export const ID_PREFIXES = Object.freeze({ + project: 'proj', + binding: 'bind', + config: 'cfg', + task: 'task', + dispatch: 'dsp', + attempt: 'att', + contextPacket: 'ctx', + result: 'res', + artifact: 'art', + event: 'evt', + authorization: 'auth', +}) + +export const ID_ENTITIES = Object.freeze(Object.keys(ID_PREFIXES)) + +/** 默认随机源:crypto.getRandomValues,取 0..35 的字符。 */ +export function cryptoRandom() { + const crypto = globalThis.crypto + if (!crypto || typeof crypto.getRandomValues !== 'function') { + throw new Error('缺少可用的随机源,请注入 random 参数') + } + const bytes = crypto.getRandomValues(new Uint8Array(8)) + // 除 36 取余有轻微偏差,但只用于 ID 唯一性,不用于安全令牌。 + return ALPHABET[bytes[0] % ALPHABET.length] +} + +/** + * 注入的随机源可以返回数字(映射到字母表)或单个字符(必须来自字母表)。 + * 两种都接受是为了测试能写 `() => 0` 这样最直白的桩。 + */ +function pick(random, index) { + const value = random(index) + if (typeof value === 'number') { + if (!Number.isInteger(value)) throw new Error('随机源必须返回整数或字母表内字符') + // 随机源常被测试当作递增计数器使用,数值可能超过字母表长度甚至为负; + // 先取绝对整数再取模,保证任意整数都能映射到合法字符。 + return ALPHABET[Math.abs(value) % 36] + } + const char = String(value) + if (char.length !== 1 || !ALPHABET.includes(char)) throw new Error(`随机源返回了字母表外字符: ${char}`) + return char +} + +/** + * 生成 `_<随机串>`。 + * 前缀既可用实体名('task')也可用前缀本身('task'),两者一致时可省心。 + */ +export function newId(prefix, options = {}) { + const { random = cryptoRandom, length = 12 } = options + const known = ID_PREFIXES[prefix] + const resolved = known ?? (Object.values(ID_PREFIXES).includes(prefix) ? prefix : undefined) + if (resolved === undefined) throw new Error(`未知 ID 前缀: ${prefix}`) + if (!Number.isInteger(length) || length < 4 || length > 64) throw new Error('ID 随机串长度须为 4..64') + let out = '' + for (let index = 0; index < length; index += 1) out += pick(random, index) + return `${resolved}_${out}` +} + +/** 每个实体一个绑定好随机源的生成器,便于在服务层统一注入并保持测试确定性。 */ +export function createIdFactory(options = {}) { + const { random = cryptoRandom, length = 12 } = options + const factory = {} + for (const entity of ID_ENTITIES) { + factory[entity] = () => newId(ID_PREFIXES[entity], { random, length }) + } + return Object.freeze(factory) +} + +/** 校验外部传入的 ID 形状(防伪 ID 进账;存在性仍由 store 查表)。 */ +export function isIdOf(entity, value) { + const prefix = ID_PREFIXES[entity] + if (typeof value !== 'string' || typeof prefix !== 'string') return false + return value.startsWith(`${prefix}_`) && value.length > prefix.length + 1 +}