chenxin
3fbcd0437c
- Makefile：统一命令入口（backend/engine/docker/openapi/generate，含 make help） - backend：FastAPI + uv 最小工程，统一错误体（契约第 7 节）、ADR-015 平台 ID 生成与校验（uuid-utils）；pytest 7 项、ruff、mypy strict、启动冒烟全部通过 - engine：灵台引擎 C++23/CMake 骨架，按 Lingtai C ABI 契约实现 lingtai.h（13 个 HjStatus、版本协商、句柄表防二次释放、线程局部错误上下文）；doctest 5 用例通过，nm 验证仅导出 hj_* 符号 - openapi：OpenAPI 3.1 单一真源初始版（错误体/分页/Money/首批平台 ID/ContentBlock 全 21 类型/流事件 envelope），Redocly lint 0 错误、bundle 通过 - frontend：Next.js 最小骨架，openapi-typescript 生成 API 类型并通过 strict tsc - docker：hunjing-postgres（pgvector:17）compose；.env.example 与 config 示例 - ADR-025：登记测试与契约工具链（doctest/libFuzzer/Redocly/openapi-typescript/uuid-utils） - desktop：Tauri v2 占位与初始化说明（WP-10 启动）
40 lines
1.3 KiB
Python
40 lines
1.3 KiB
Python
"""平台 ID 生成与校验（ADR-015 与 docs/contracts/README.md 生成规则）。
|
|
|
|
格式固定为 ``<prefix><lowercase-canonical-uuid>``；解析时必须校验前缀与
|
|
UUID version。UUID 生成使用成熟实现 uuid-utils，不自行拼位。
|
|
"""
|
|
|
|
import re
|
|
from uuid import UUID
|
|
|
|
from uuid_utils import uuid4, uuid7
|
|
|
|
_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
|
|
|
|
|
|
def new_id(prefix: str, *, version: int = 7) -> str:
|
|
"""生成带登记前缀的平台 ID；持久化资源默认 UUIDv7。"""
|
|
value = uuid7() if version == 7 else uuid4()
|
|
return f"{prefix}{value}"
|
|
|
|
|
|
def parse_id(value: str, prefix: str, *, version: int = 7) -> UUID:
|
|
"""校验并解析平台 ID：前缀与 UUID version 均须匹配，否则抛 ValueError。"""
|
|
if not value.startswith(prefix):
|
|
raise ValueError(f"ID 前缀不合法：期望 {prefix!r}")
|
|
raw = value[len(prefix) :]
|
|
if not _UUID_RE.match(raw):
|
|
raise ValueError("ID 不是 canonical 小写 UUID 文本")
|
|
parsed = UUID(raw)
|
|
if parsed.version != version:
|
|
raise ValueError(f"ID version 不合法：期望 UUIDv{version}")
|
|
return parsed
|
|
|
|
|
|
def is_valid_id(value: str, prefix: str, *, version: int = 7) -> bool:
|
|
try:
|
|
parse_id(value, prefix, version=version)
|
|
except ValueError:
|
|
return False
|
|
return True
|