Ziwei Fortune Engine

Ziwei Fortune Engine

Ziwei Fortune Engine 为紫微斗数、八字、中国黄历数据、真太阳时、大运周期、宫位格局以及关系合盘提供确定性的离线计算。它专为需要单一纯计算引擎、而不想自行维护日历和命理算法的 SP2 应用而设计。

该引擎包含超过 34,000 个全球城市，以及约 129,000 个名称和别名。可为任何地点提供精确的纬度、经度和 UTC 偏移量。未知城市名称会返回明确错误，绝不会静默回退到其他城市。

接口

所有函数均使用 include/019fad5d-36e8-767c-87b8-2ea9d1211ade.h 中声明的 C ABI。输入和输出字符串均为 UTF-8 JSON。输入和输出缓冲区始终由调用应用拥有；库绝不会保留其指针。

sp2_019fad5d_36e8_767c_87b8_2ea9d1211ade_init() -> i32

在调用引擎之前，从调用应用的 init() 中准确调用一次。成功时返回 0。

sp2_019fad5d_36e8_767c_87b8_2ea9d1211ade_invoke(...) -> i32

参数：

• input_ptr：指向 UTF-8 JSON 请求的非空指针。
• input_len：请求长度（字节）；必须大于零。
• output_ptr：指向调用方拥有的输出缓冲区的指针。用于容量查询时可为空。
• output_capacity：输出缓冲区大小（字节）。

返回：

| 返回值 | 含义 | | --- | --- | | >= 0 | 写入的响应字节数；不会添加尾随空字节。 | | < -3 | 输出缓冲区过小；其绝对值为所需大小。 | | -1 | 指针无效、输入为空或 UTF-8 无效。 | | -2 | 内部计算引擎失败。 | | -3 | 结果超过 ABI 大小限制。 |

有效请求具有以下封装结构：

{"operation":"calendar","input":{"date":"2025-01-01"}}

支持的操作：

| 操作 | 输入字段 | | --- | --- | | calendar | 可选的 YYYY-MM-DD 格式 date。 | | bazi | date、time、gender；可选 lunar 和 sect。 | | palace | date、time、gender、location、palace、scope；按需提供周期日期字段。 | | synastry_origin | A 方和 B 方的出生详情及可选姓名。 | | synastry_yearly | 相同的双方输入，另加 year。 | | solar_time | dateTime、latitude、longitude 和 timezone。 | | city_lookup | city。 |

gender 接受 male 或 female。宫位别名为 health、wealth、children、spouse、siblings、life、parents、wellbeing、property、career、friends 和 travel。宫位范围为 origin、decadal、yearly、monthly 和 daily。月度请求需要 year 和 month；日度请求还需要 day。

地点可以通过城市名称提供：

{"city":"London"}

也可以通过精确坐标和数字 UTC 偏移量提供：

{"location":{"latitude":51.5074,"longitude":-0.1278,"timezone":0}}

合盘字段使用前缀 a 和 b，例如 aDate、aTime、aGender、aCity、aName，以及对应的 b 字段。精确合盘地点使用 aLocation 和 bLocation。

成功计算会返回 {"success":true,"data":...}。产品级验证失败会返回有效 JSON，其中 success 设置为 false，并包含错误消息。响应会以 UTF-8 保留源领域词汇。

用法

将精确发布版本添加到 backend/Cargo.toml：

[dependencies]
fortune = { package = "sp2019f0de27c9e7628a7adc7d94f5cc62a-019fad5d-36e8-767c-87b8-2ea9d1211ade-sys", version = "0.1.0", registry = "sp2-cargo" }

从应用后端调用该库：

fn calculate(request: &[u8]) -> Result<Vec<u8>, i32> {
    let init_rc = unsafe {
        fortune::sp2_019fad5d_36e8_767c_87b8_2ea9d1211ade_init()
    };
    if init_rc != 0 {
        return Err(init_rc);
    }

    let probe = unsafe {
        fortune::sp2_019fad5d_36e8_767c_87b8_2ea9d1211ade_invoke(
            request.as_ptr(), request.len() as u