# ADR-001: 生辰信息与出生地存储设计

## 状态
✅ 已采纳

## 日期
2026-08-13

## 背景
纯客户端软件需要支持真太阳时计算功能，用户需输入生辰八字（公历日期时间）和出生地。这些数据需要持久化存储，以便后续使用（如紫微斗数排盘、运势推算）。

## 需求
1. 用户输入：公历日期时间、出生地（城市名）、经纬度、性别
2. 系统计算：真太阳时、八字四柱（年柱、月柱、日柱、时柱）
3. 纯客户端无服务端依赖
4. 用户仅需输入一次

## 数据模型

### 用户输入层（持久化存储）
```typescript
interface BirthInfoInput {
  birthDate: string    // 公历出生日期 YYYY-MM-DD
  birthHour: number    // 出生小时 (0-23)
  birthMinute: number  // 出生分钟 (0-59)
  birthPlace: string   // 出生地名称（如"北京市"）
  longitude: number    // 出生地经度
  latitude: number     // 出生地纬度
  gender: 'MALE' | 'FEMALE'
}
```

### 系统计算结果层（运行时计算）
```typescript
interface BirthInfo {
  birthTime: string           // 组合后的 ISO 格式时间
  yearStem: HeavenlyStem
  monthStem: HeavenlyStem
  dayStem: HeavenlyStem
  hourStem: HeavenlyStem
  yearBranch: EarthlyBranch
  monthBranch: EarthlyBranch
  dayBranch: EarthlyBranch
  hourBranch: EarthlyBranch
  gender: 'MALE' | 'FEMALE'
  timezone: string
  longitude?: number
  latitude?: number
  birthPlace?: string
  trueSolarTime?: string
  lunarDate?: LunarDate
}
```

## 决策

### 存储方案：UniApp Storage (uni.getStorageSync/uni.setStorageSync)
- **理由**：数据量极小（单用户 < 1KB），纯客户端无网络依赖，跨平台兼容（H5/小程序/App），已有 `StorageService` 封装
- **替代方案排除**：SQLite（过重）、文件存储（JSON 文件，无需引入）、localStorage（仅限 H5，不跨平台）

### 存储键设计
| Key | 类型 | 存储内容 | 生命周期 |
|-----|------|---------|---------|
| `eis_birth_info` | `BirthInfoInput` | 用户输入的原值 | 持久化，用户修改时更新 |
| `eis_ziwei_chart` | `ZiweiChart` | 最近一次排盘结果 | 持久化，新建排盘时更新 |

### 数据分层
- 用户输入和系统计算结果严格分层
- `BirthInfoInput` 仅包含用户输入的原始值，用于持久化
- `BirthInfo` 包含完整计算后的生辰信息，用于排盘算法
- `BirthInfoInput` → 计算真太阳时 → 计算八字四柱 → 构建 `BirthInfo` → 排盘

### 真太阳时计算
- 独立模块 `src/algorithms/solarTime.ts`
- 公式：真太阳时 = 平太阳时 + 经度修正 + 时差方程
  - 经度修正：(本地经度 - 时区中央经度) × 4 分钟/度
  - 时差方程：基于地球公转轨道离心率和黄赤交角的天文修正

## 影响
1. 紫微页面需增加出生地输入字段
2. 排盘后自动持久化用户输入和排盘结果
3. 运势页面从持久化读取排盘结果
4. 不影响现有测试用例

## 术语表

| 术语 | 定义 |
|------|------|
| 公历时间 | 用户输入的 Gregorian calendar 日期时间 |
| 出生地 | 用户出生的城市/行政区划名称 |
| 经纬度 | 出生地对应的地理坐标 |
| 真太阳时 | 基于地球真实公转位置的时间，由公历时间 + 经度修正计算得出 |
| 八字四柱 | 年柱、月柱、日柱、时柱的干支组合 |
| 排盘 | 根据生辰信息推算紫微斗数命盘 |