aicms-renderengine-core

跨项目命名、契约和持久化规则统一遵循 AiCMS 工程编码规范，其中的 Naming Convention 章节是全系统命名正文真源。

共享渲染核心，向 TMaker 和 Console 提供稳定的模板渲染语义、模板角色和作者诊断契约。

Packages

本仓库是唯一源码真源，并发布三个版本化包：

• AiCms.RenderEngine：运行时渲染能力。
• AiCms.TemplateRoles：无渲染依赖的 canonical 模板角色 registry、模型与 manifest preflight。
• AiCms.TemplateAuthoring：模板诊断、格式化和契约校验。

消费者默认通过固定版本的 NuGet 包引用，不使用 RenderEngine Git submodule。 允许的跨包版本组合必须在中央 package provenance 记录中明确批准。

Local Development

需要调试 RenderEngine 源码时，将 AICMS_RENDERENGINE_ROOT 指向同级仓库，并显式开启本地源码模式：

AICMS_RENDERENGINE_ROOT=/path/to/aicms-renderengine-core \
dotnet build -p:UseLocalRenderEngine=true

需要使用本地打包结果验证 NuGet 模式时，先将三个包输出到 artifacts/，再执行：

VERSION=0.0.20260805.1-local
dotnet pack src/AiCms.RenderEngine/AiCms.RenderEngine.csproj --configuration Release \
  --output artifacts -p:AiCmsRenderEngineVersion="$VERSION"
dotnet pack src/AiCms.TemplateRoles/AiCms.TemplateRoles.csproj --configuration Release \
  --output artifacts -p:AiCmsRenderEngineVersion="$VERSION"
dotnet pack src/AiCms.TemplateAuthoring/AiCms.TemplateAuthoring.csproj --configuration Release \
  --output artifacts -p:AiCmsRenderEngineVersion="$VERSION"

# Run from TemplateStarter. This remains a PackageReference verification: it
# explicitly disables the local ProjectReference mode and pins both packages.
AICMS_RENDERENGINE_ROOT=/path/to/aicms-renderengine-core \
dotnet restore TMaker.UnitTests/TMaker.UnitTests.csproj --force-evaluate --no-cache \
  -p:UseLocalRenderEngine=false \
  -p:UseLocalRenderEnginePackages=true \
  -p:AiCmsRenderEngineVersion="$VERSION" \
  -p:AiCmsTemplateAuthoringVersion="$VERSION"
AICMS_RENDERENGINE_ROOT=/path/to/aicms-renderengine-core \
dotnet test TMaker.UnitTests/TMaker.UnitTests.csproj --no-restore \
  -p:UseLocalRenderEngine=false \
  -p:UseLocalRenderEnginePackages=true \
  -p:AiCmsRenderEngineVersion="$VERSION" \
  -p:AiCmsTemplateAuthoringVersion="$VERSION"

正式 CI 和部署构建不得依赖本地源码路径或 Git submodule。

跨边界大整数标识符约束

遵循中央《跨边界大整数标识符规范》：数据库/领域模型/业务逻辑使用原生 long、int64 或 bigint；HTTP、JSON、队列、缓存快照和浏览器边界的身份字段使用十进制字符串。后端请求兼容合法 number/string 并严格校验，响应固定输出字符串。TypeScript/JavaScript ID 全程保持 string，禁止 Number、parseInt、算术、范围比较和数字排序。新增或修改身份契约必须使用大于 Number.MAX_SAFE_INTEGER 的回归值。

边界 DTO 形态与转换范围

公共请求和响应 DTO 的身份字段必须显式使用 string；领域、数据库和业务服务继续使用 long/int64。兼容窗口内仅由边界适配器额外读取合法 JSON number，输出、队列、缓存和浏览器数据始终使用字符串。不得注册“所有 long 全局转字符串”的转换器；计数、时间戳、版本、金额、状态和分页等普通数值字段必须保持其数值语义。数字协议例外必须登记消费者、版本、范围和测试。

Long ID boundary contract

Database and domain identifiers remain long/int64. Public HTTP, JSON, queue, cache, and browser identifier fields are decimal strings. Request adapters may read a strictly valid JSON string or number during the compatibility window; responses always write strings. Reject empty, negative, fractional, out-of-range, and leading-zero identifiers. TypeScript/JavaScript must keep IDs as string and must not call Number/parseInt, perform arithmetic, range comparisons, or numeric sorting on them. Ordinary counts, amounts, timestamps, versions, status values, and pagination numbers remain numeric and are not affected by ID conversion. Every protocol exception must register its consumers, version, range, and regression test in the central large-integer identifier standard.