# `annual-cycle-v1` 流年时间线

`annual-cycle-v1` 只负责确定每个流年的干支和精确时间边界，不判断吉凶。

## 调用方式

```ts
import { calculateAnnualCycles } from 'bazi-core';

const result = calculateAnnualCycles({
  fromYear: 2024,
  toYear: 2026,
});

console.log(result.cycles);
```

`fromYear` 和 `toYear` 是包含首尾的公历锚点年，不是说流年从公历元旦开始。例如 `anchorYear: 2024` 表示从 2024 年立春开始的甲辰流年。

## 换年边界

每个流年是左闭右开区间：

```text
[anchorYear 立春, anchorYear + 1 立春)
```

例如 2024 甲辰流年为：

```text
[2024-02-04T16:27:07+08:00, 2025-02-03T22:10:28+08:00)
```

因此：

- 不以公历 1 月 1 日换流年；
- 不以农历正月初一换流年；
- 边界按中国标准时间 `UTC+08:00` 输出，精度到秒；
- 立春时刻本身已属于新流年。

## 输出字段

每个 `cycles` 项包含：

- `index`：本次结果中的序号，从 1 开始；
- `anchorYear`：该流年立春所在的公历年；
- `ganZhi`：该流年干支；
- `startsAt`：包含的起点；
- `endsAt`：不包含的结束点。

结果同时保留 `appliedRules`、`trace` 和 `warnings`，用于审查本次时间线采用的换年口径。

## 能力边界

`annual-cycle-v1` 不需要出生时间或性别，因为同一时刻的流年干支对所有人相同。出生四柱、大运和性别只会影响后续如何将流年与个人命局组合分析。

本版本不做：

- 流年与原局的生克、十神、刑冲合害分析；
- 流年与大运的叠加分析；
- 好运、坏运、事件或应期断语。

这些应当作为后续独立、可版本化的解释层，不会隐藏在流年时间计算中。