TECH-08 · 接口签名与决策日志

1. 核心接口#

ContentCompiler.compile(source_root) -> CompileReport
ContentStore.load(manifest) -> ContentHandle
CommandBus.submit(command) -> CommandResult
QueryService.query(request) -> ReadOnlyDto
Simulation.step(step_input) -> EventBatch
SaveService.save(snapshot) -> SaveResult
PlatformService.unlock_achievement(api_name) -> PlatformResult

2. 命令合同#

CheckStructureCommand 扫描指定地块并返回 StructureReport；ApproveBuildCommand 只有在报告通过后才能创建施工队列；施工阶段不重复结构计算。

每个命令声明类型、参数 Schema、前置 revision、错误码和副作用。错误返回结构化 reason_key 和字段路径，UI 只负责翻译显示，不自行拼接规则。

3. 查询合同#

查询只能返回不可变 DTO，必须支持分页、排序、过滤和 revision。大列表禁止把全部实体复制到 UI；查询结果过期时界面重新请求。

4. 平台接口#

接口	本地替身	Steam 实现
用户身份	固定测试用户	SteamID
成就	写本地日志	Steam achievement API
Cloud	本地 cloud 目录	Steam Remote Storage
Workshop	本地包目录	Steam UGC
Overlay	记录调用	打开 Steam Overlay

5. 决策变更规则#

本册只保留 v4.1 当前合同。早期 ADR 中与已废止性能承诺、已废止引擎方案、固定模块拆分或任意脚本 MOD 相关的结论全部失效，不再作为实现依据。新接口变更必须同步实现、测试和存档版本。