@downcity/services 0.1.6

package/bin/balance/types.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Balance 服务对外类型定义。
+ *
+ * 关键说明（中文）
+ * - 余额单位仍然由业务侧决定，默认值是 `credits`
+ * - `redeem_code` 是一次性兑换码，用于直接给用户充值
+ * - 充值单 `topup` 与 `redeem_code` 是两条不同语义的充值链路
+ */
+/**
+ * Balance 服务配置。
+ */
+export interface BalanceServiceOptions {
+    /**
+     * 首次自动开户时要发放的初始余额。
+     *
+     * 默认值为 `0`。使用整数，避免浮点金额误差。
+     */
+    init?: number;
+    /**
+     * 余额单位名称。
+     *
+     * 例如：`credits`、`points`、`tokens`。
+     * 默认值为 `credits`。
+     */
+    unit?: string;
+}
+/**
+ * 余额附加信息。
+ */
+export interface BalanceExtra {
+    /**
+     * 写入流水、充值单或兑换码的人类可读说明。
+     */
+    note?: string;
+    /**
+     * 外部引用 ID。
+     *
+     * 例如业务请求 ID、订单 ID、支付回调 ID。
+     */
+    ref?: string;
+    /**
+     * 结构化扩展字段。
+     *
+     * 服务会序列化为 JSON 文本存储。
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 余额流水类型。
+ */
+export type BalanceLedgerKind = "init" | "add" | "sub" | "topup" | "redeem";
+/**
+ * 充值单状态。
+ */
+export type BalanceTopupStatus = "pending" | "paid" | "canceled";
+/**
+ * redeem_code 状态。
+ */
+export type BalanceRedeemCodeStatus = "active" | "redeemed" | "disabled";
+/**
+ * 用户余额账户。
+ */
+export interface BalanceAccount extends Record<string, unknown> {
+    /**
+     * 用户 ID。
+     */
+    user_id: string;
+    /**
+     * 当前可用余额。
+     */
+    balance: number;
+    /**
+     * 余额单位。
+     */
+    unit: string;
+    /**
+     * 账户创建时间。
+     */
+    created_at: string;
+    /**
+     * 账户最近更新时间。
+     */
+    updated_at: string;
+}
+/**
+ * 余额流水记录。
+ */
+export interface BalanceLedgerEntry extends Record<string, unknown> {
+    /**
+     * 流水主键。
+     */
+    entry_id: string;
+    /**
+     * 用户 ID。
+     */
+    user_id: string;
+    /**
+     * 流水类型。
+     */
+    kind: BalanceLedgerKind;
+    /**
+     * 本次变动金额。
+     *
+     * 约定：
+     * - 加款为正数
+     * - 扣款为负数
+     */
+    amount: number;
+    /**
+     * 本次变动后的余额快照。
+     */
+    balance_after: number;
+    /**
+     * 余额单位。
+     */
+    unit: string;
+    /**
+     * 流水说明。
+     */
+    note: string;
+    /**
+     * 外部引用 ID。
+     */
+    ref: string;
+    /**
+     * 扩展字段 JSON 文本。
+     */
+    metadata_json: string;
+    /**
+     * 流水创建时间。
+     */
+    created_at: string;
+}
+/**
+ * 充值单。
+ */
+export interface BalanceTopup extends Record<string, unknown> {
+    /**
+     * 充值单 ID。
+     */
+    topup_id: string;
+    /**
+     * 用户 ID。
+     */
+    user_id: string;
+    /**
+     * 充值金额。
+     */
+    amount: number;
+    /**
+     * 余额单位。
+     */
+    unit: string;
+    /**
+     * 当前状态。
+     */
+    status: BalanceTopupStatus;
+    /**
+     * 充值说明。
+     */
+    note: string;
+    /**
+     * 外部引用 ID。
+     */
+    ref: string;
+    /**
+     * 扩展字段 JSON 文本。
+     */
+    metadata_json: string;
+    /**
+     * 充值单创建时间。
+     */
+    created_at: string;
+    /**
+     * 充值单更新时间。
+     */
+    updated_at: string;
+}
+/**
+ * redeem_code 记录。
+ */
+export interface BalanceRedeemCode extends Record<string, unknown> {
+    /**
+     * redeem_code 主键。
+     */
+    redeem_code_id: string;
+    /**
+     * 充值金额。
+     */
+    amount: number;
+    /**
+     * 余额单位。
+     */
+    unit: string;
+    /**
+     * 当前状态。
+     */
+    status: BalanceRedeemCodeStatus;
+    /**
+     * 脱敏后的兑换码文本。
+     */
+    code_mask: string;
+    /**
+     * redeem_code 说明。
+     */
+    note: string;
+    /**
+     * 外部引用 ID。
+     */
+    ref: string;
+    /**
+     * 扩展字段 JSON 文本。
+     */
+    metadata_json: string;
+    /**
+     * 被哪个用户兑换。
+     *
+     * 未兑换时为空字符串。
+     */
+    redeemed_by_user_id: string;
+    /**
+     * 兑换时间。
+     *
+     * 未兑换时为空字符串。
+     */
+    redeemed_at: string;
+    /**
+     * 创建时间。
+     */
+    created_at: string;
+    /**
+     * 更新时间。
+     */
+    updated_at: string;
+}
+/**
+ * 管理端创建 redeem_code 的输入。
+ */
+export interface BalanceCreateRedeemCodeInput extends BalanceExtra {
+    /**
+     * 兑换成功后要充值到用户账户的额度。
+     */
+    amount: number;
+    /**
+     * 可选自定义兑换码明文。
+     *
+     * 为空时由系统自动生成。
+     */
+    code?: string;
+}
+/**
+ * 创建 redeem_code 后返回的结果。
+ */
+export interface BalanceRedeemCodeIssueResult extends BalanceRedeemCode {
+    /**
+     * redeem_code 明文。
+     *
+     * 只在创建时返回一次，后续列表接口不会再返回。
+     */
+    code: string;
+}
+/**
+ * 用户兑换 redeem_code 成功后的结果。
+ */
+export interface BalanceRedeemCodeRedeemResult extends Record<string, unknown> {
+    /**
+     * 兑换成功后的最新账户快照。
+     */
+    account: BalanceAccount;
+    /**
+     * 被兑换的 redeem_code 记录。
+     */
+    redeem_code: BalanceRedeemCode;
+}
+/**
+ * 历史查询条件。
+ */
+export interface BalanceHistoryQuery {
+    /**
+     * 可选用户 ID。
+     *
+     * 为空时返回全局流水。
+     */
+    user_id?: string;
+    /**
+     * 返回条数上限。
+     */
+    limit?: number | string;
+}
+/**
+ * 充值单查询条件。
+ */
+export interface BalanceTopupQuery {
+    /**
+     * 可选用户 ID。
+     *
+     * 为空时返回全局充值单。
+     */
+    user_id?: string;
+    /**
+     * 返回条数上限。
+     */
+    limit?: number | string;
+}
+/**
+ * redeem_code 查询条件。
+ */
+export interface BalanceRedeemCodeQuery {
+    /**
+     * 可选兑换状态。
+     *
+     * 为空时返回所有状态。
+     */
+    status?: BalanceRedeemCodeStatus | string;
+    /**
+     * 可选兑换用户 ID。
+     *
+     * 为空时返回所有用户。
+     */
+    user_id?: string;
+    /**
+     * 返回条数上限。
+     */
+    limit?: number | string;
+}
+//# sourceMappingURL=types.d.ts.map

package/bin/balance/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/balance/types.ts"],"names":[],"mappings":"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"}

package/bin/balance/types.js

@@ -0,0 +1,10 @@
+/**
+ * Balance 服务对外类型定义。
+ *
+ * 关键说明（中文）
+ * - 余额单位仍然由业务侧决定，默认值是 `credits`
+ * - `redeem_code` 是一次性兑换码，用于直接给用户充值
+ * - 充值单 `topup` 与 `redeem_code` 是两条不同语义的充值链路
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/bin/balance/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/balance/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/balance/utils.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Balance 服务通用工具。
+ *
+ * 关键说明（中文）
+ * - 所有输入都在这里统一做标准化
+ * - redeem_code 明文只在创建时短暂存在，落库前必须哈希
+ */
+import type { BalanceAccount, BalanceLedgerEntry, BalanceTopup, BalanceRedeemCode, BalanceRedeemCodeStatus } from "./types.js";
+/**
+ * 读取必填字符串。
+ */
+export declare function readRequired(value: unknown, label: string): string;
+/**
+ * 标准化用户 ID。
+ */
+export declare function normalizeUserId(value: string): string;
+/**
+ * 标准化正整数。
+ */
+export declare function normalizePositiveInteger(value: unknown, label: string): number;
+/**
+ * 标准化非负整数。
+ */
+export declare function normalizeNonNegativeInteger(value: unknown, label: string): number;
+/**
+ * 标准化 limit。
+ */
+export declare function normalizeLimit(value: unknown): number;
+/**
+ * 标准化普通文本。
+ */
+export declare function normalizeText(value: unknown): string;
+/**
+ * 序列化 meta。
+ */
+export declare function stringifyMeta(meta: Record<string, unknown> | undefined): string;
+/**
+ * 解析 meta JSON。
+ */
+export declare function parseMetaJSON(value: string): Record<string, unknown>;
+/**
+ * 合并 meta JSON。
+ */
+export declare function mergeMetaJSON(current: string, next: Record<string, unknown> | undefined): string;
+/**
+ * 生成随机 ID。
+ */
+export declare function randomId(): string;
+/**
+ * 标准化 redeem_code 明文。
+ *
+ * 关键说明（中文）
+ * - 允许用户输入时带空格或连字符
+ * - 最终统一成不带分隔符的大写文本再做哈希
+ */
+export declare function normalizeRedeemCode(value: unknown, label?: string): string;
+/**
+ * 生成 redeem_code 明文。
+ */
+export declare function generateRedeemCode(): string;
+/**
+ * 生成脱敏 redeem_code。
+ */
+export declare function maskRedeemCode(code: string): string;
+/**
+ * 计算 redeem_code 哈希值。
+ */
+export declare function hashRedeemCode(code: string): Promise<string>;
+/**
+ * 标准化 redeem_code 状态。
+ */
+export declare function normalizeRedeemCodeStatus(value: unknown): BalanceRedeemCodeStatus | undefined;
+/**
+ * 解析账户行。
+ */
+export declare function parseAccountRow(row: BalanceAccount): BalanceAccount;
+/**
+ * 解析流水行。
+ */
+export declare function parseLedgerRow(row: BalanceLedgerEntry): BalanceLedgerEntry;
+/**
+ * 解析充值单行。
+ */
+export declare function parseTopupRow(row: BalanceTopup): BalanceTopup;
+/**
+ * 解析 redeem_code 行。
+ */
+export declare function parseRedeemCodeRow(row: BalanceRedeemCode & {
+    code_hash?: string;
+}): BalanceRedeemCode;
+//# sourceMappingURL=utils.d.ts.map

package/bin/balance/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/balance/utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAElB,YAAY,EAEZ,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM9E;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAE/E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAKhG;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAOjC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAS,GAAG,MAAM,CAe1E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAW3C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,SAAS,CAO7F;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAQnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,kBAAkB,GAAG,kBAAkB,CAa1E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAa7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAerG"}

package/bin/balance/utils.js

@@ -0,0 +1,231 @@
+/**
+ * Balance 服务通用工具。
+ *
+ * 关键说明（中文）
+ * - 所有输入都在这里统一做标准化
+ * - redeem_code 明文只在创建时短暂存在，落库前必须哈希
+ */
+const REDEEM_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/**
+ * 读取必填字符串。
+ */
+export function readRequired(value, label) {
+    const normalized = String(value ?? "").trim();
+    if (!normalized)
+        throw new TypeError(`${label} is required`);
+    return normalized;
+}
+/**
+ * 标准化用户 ID。
+ */
+export function normalizeUserId(value) {
+    return readRequired(value, "user_id");
+}
+/**
+ * 标准化正整数。
+ */
+export function normalizePositiveInteger(value, label) {
+    const normalized = Number(value);
+    if (!Number.isInteger(normalized) || normalized <= 0) {
+        throw new TypeError(`${label} must be a positive integer`);
+    }
+    return normalized;
+}
+/**
+ * 标准化非负整数。
+ */
+export function normalizeNonNegativeInteger(value, label) {
+    const normalized = Number(value);
+    if (!Number.isInteger(normalized) || normalized < 0) {
+        throw new TypeError(`${label} must be a non-negative integer`);
+    }
+    return normalized;
+}
+/**
+ * 标准化 limit。
+ */
+export function normalizeLimit(value) {
+    const normalized = Number(value ?? 20);
+    if (!Number.isInteger(normalized) || normalized <= 0)
+        return 20;
+    return Math.min(normalized, 200);
+}
+/**
+ * 标准化普通文本。
+ */
+export function normalizeText(value) {
+    return String(value ?? "").trim();
+}
+/**
+ * 序列化 meta。
+ */
+export function stringifyMeta(meta) {
+    return JSON.stringify(meta ?? {});
+}
+/**
+ * 解析 meta JSON。
+ */
+export function parseMetaJSON(value) {
+    try {
+        const parsed = JSON.parse(value || "{}");
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 合并 meta JSON。
+ */
+export function mergeMetaJSON(current, next) {
+    return JSON.stringify({
+        ...parseMetaJSON(current),
+        ...(next ?? {}),
+    });
+}
+/**
+ * 生成随机 ID。
+ */
+export function randomId() {
+    const bytes = new Uint8Array(12);
+    crypto.getRandomValues(bytes);
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * 标准化 redeem_code 明文。
+ *
+ * 关键说明（中文）
+ * - 允许用户输入时带空格或连字符
+ * - 最终统一成不带分隔符的大写文本再做哈希
+ */
+export function normalizeRedeemCode(value, label = "code") {
+    const normalized = String(value ?? "")
+        .trim()
+        .toUpperCase()
+        .replace(/[\s-]+/g, "");
+    if (!normalized) {
+        throw new TypeError(`${label} is required`);
+    }
+    if (!/^[A-Z0-9]+$/.test(normalized)) {
+        throw new TypeError(`${label} must contain only letters and numbers`);
+    }
+    return normalized;
+}
+/**
+ * 生成 redeem_code 明文。
+ */
+export function generateRedeemCode() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    const chars = Array.from(bytes, (value) => REDEEM_CODE_ALPHABET[value % REDEEM_CODE_ALPHABET.length]);
+    return [
+        chars.slice(0, 4).join(""),
+        chars.slice(4, 8).join(""),
+        chars.slice(8, 12).join(""),
+        chars.slice(12, 16).join(""),
+    ].join("-");
+}
+/**
+ * 生成脱敏 redeem_code。
+ */
+export function maskRedeemCode(code) {
+    const normalized = normalizeRedeemCode(code);
+    const head = normalized.slice(0, 4);
+    const tail = normalized.slice(-4);
+    const middleLength = Math.max(0, normalized.length - head.length - tail.length);
+    return `${head}${middleLength > 0 ? `-${"*".repeat(middleLength)}` : ""}${tail ? `-${tail}` : ""}`;
+}
+/**
+ * 计算 redeem_code 哈希值。
+ */
+export async function hashRedeemCode(code) {
+    const normalized = normalizeRedeemCode(code);
+    const data = new TextEncoder().encode(normalized);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(digest))
+        .map((item) => item.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * 标准化 redeem_code 状态。
+ */
+export function normalizeRedeemCodeStatus(value) {
+    const normalized = String(value ?? "").trim();
+    if (!normalized)
+        return undefined;
+    if (normalized === "active" || normalized === "redeemed" || normalized === "disabled") {
+        return normalized;
+    }
+    throw new TypeError("status must be one of: active, redeemed, disabled");
+}
+/**
+ * 解析账户行。
+ */
+export function parseAccountRow(row) {
+    return {
+        user_id: String(row.user_id),
+        balance: Number(row.balance),
+        unit: String(row.unit),
+        created_at: String(row.created_at),
+        updated_at: String(row.updated_at),
+    };
+}
+/**
+ * 解析流水行。
+ */
+export function parseLedgerRow(row) {
+    return {
+        entry_id: String(row.entry_id),
+        user_id: String(row.user_id),
+        kind: String(row.kind),
+        amount: Number(row.amount),
+        balance_after: Number(row.balance_after),
+        unit: String(row.unit),
+        note: String(row.note ?? ""),
+        ref: String(row.ref ?? ""),
+        metadata_json: String(row.metadata_json ?? "{}"),
+        created_at: String(row.created_at),
+    };
+}
+/**
+ * 解析充值单行。
+ */
+export function parseTopupRow(row) {
+    return {
+        topup_id: String(row.topup_id),
+        user_id: String(row.user_id),
+        amount: Number(row.amount),
+        unit: String(row.unit),
+        status: String(row.status),
+        note: String(row.note ?? ""),
+        ref: String(row.ref ?? ""),
+        metadata_json: String(row.metadata_json ?? "{}"),
+        created_at: String(row.created_at),
+        updated_at: String(row.updated_at),
+    };
+}
+/**
+ * 解析 redeem_code 行。
+ */
+export function parseRedeemCodeRow(row) {
+    return {
+        redeem_code_id: String(row.redeem_code_id),
+        amount: Number(row.amount),
+        unit: String(row.unit),
+        status: String(row.status),
+        code_mask: String(row.code_mask ?? ""),
+        note: String(row.note ?? ""),
+        ref: String(row.ref ?? ""),
+        metadata_json: String(row.metadata_json ?? "{}"),
+        redeemed_by_user_id: String(row.redeemed_by_user_id ?? ""),
+        redeemed_at: String(row.redeemed_at ?? ""),
+        created_at: String(row.created_at),
+        updated_at: String(row.updated_at),
+    };
+}
+//# sourceMappingURL=utils.js.map

package/bin/balance/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/balance/utils.ts"],"names":[],"mappings":"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"}