# `luck-cycle-v1` 大运与起运规则

`luck-cycle-v1` 负责确定性地排出大运顺逆、起运年龄、交运时间和每一步十年大运干支。它只输出时间与干支事实，不判断好运、坏运、喜忌或具体事件。

## 1. 输入时间

- 使用与 `calculateBazi` 相同的中国标准时间公历输入；
- 默认 `dayBoundary: "midnight"`，也可以显式选择 `zi-hour`；
- 首版不做经度、真太阳时或夏令时修正；
- 性别参数只参与传统大运顺逆规则，不改变出生四柱。

## 2. 确定顺逆

调用方可以直接指定：

```ts
calculateLuckCycles(input, { direction: 'forward' });
```

也可以选择 `year-stem-and-sex` 传统规则：

| 年干阴阳与 sexForRule | 方向 |
| --- | --- |
| 阳年男、阴年女 | 顺排 `forward` |
| 阴年男、阳年女 | 逆排 `reverse` |

阳干为甲、丙、戊、庚、壬；阴干为乙、丁、己、辛、癸。未显式指定 `direction` 时必须提供 `sexForRule`，避免隐藏默认值。

## 3. 选择起运节令

- 顺排取出生后的下一个“节”；
- 逆排取出生前的上一个“节”；
- 采用立春、惊蛰、清明等十二节，不使用全部二十四节气；
- 节令时刻来自 `lunar-typescript`，距离保留到秒。

如果逆排命盘恰好出生在节令时刻，距离为零，第一步大运立即开始；顺排则取严格位于出生时刻之后的下一个节。

## 4. 三天一岁

首版只支持 `three-days-one-year`：

| 实际节令距离 | 起运年龄 |
| --- | --- |
| 3 天 | 1 年 |
| 6 小时 | 1 个月 |
| 12 分钟 | 1 天 |
| 30 秒 | 1 小时 |
| 1 秒 | 2 分钟 |

一年在该换算规则中按十二个月、三百六十日展开。换算完成后，依次把年、月、日、时、分加到出生民用时间，得到第一步大运的 `startsAt`。

## 5. 大运干支序列

月柱作为序列起点，但不算第一步大运。第一步大运是月柱沿六十甲子移动一位：

```text
月柱丙寅
顺排：丁卯 → 戊辰 → 己巳……
逆排：乙丑 → 甲子 → 癸亥……
```

每一步持续十个公历年，区间采用前闭后开：`[startsAt, endsAt)`。`cycleCount` 默认 10，可设置为 1 到 20。

## 6. 起运前

从出生时刻到第一步大运开始之前，输出为：

```ts
{
  label: '起运前',
  startsAt: '出生时刻',
  endsAt: '第一步大运开始时刻',
}
```

`luck-cycle-v1` 不在这一阶段自动排小运，也不生成流年时间线。

## 7. 输出与边界

结果包含：

- `direction` 与 `directionReason`；
- 本次使用的前一个或后一个节及秒级距离；
- 结构化 `startAge` 和精确 `startsAt`；
- 起运前阶段和每一步大运的干支、年龄、起止时间；
- 完整的 `appliedRules`、`trace` 和 `warnings`。

后续如增加其他顺逆或起运换算口径，应新增规则标识或模型版本，不能静默修改 `luck-cycle-v1` 的既有结果。