export type FiveElement = 'wood' | 'fire' | 'earth' | 'metal' | 'water';

export type YinYang = 'yang' | 'yin';

export type HeavenlyStemName =
  | '甲'
  | '乙'
  | '丙'
  | '丁'
  | '戊'
  | '己'
  | '庚'
  | '辛'
  | '壬'
  | '癸';

export type EarthlyBranchName =
  | '子'
  | '丑'
  | '寅'
  | '卯'
  | '辰'
  | '巳'
  | '午'
  | '未'
  | '申'
  | '酉'
  | '戌'
  | '亥';

export type TenGod =
  | '比肩'
  | '劫财'
  | '食神'
  | '伤官'
  | '偏财'
  | '正财'
  | '七杀'
  | '正官'
  | '偏印'
  | '正印';

export type Relation =
  | 'companion'
  | 'resource'
  | 'output'
  | 'wealth'
  | 'officer';

export interface CivilTime {
  year: number;
  month: number;
  day: number;
  hour?: number;
  minute?: number;
  second?: number;
}

export type DayBoundary = 'midnight' | 'zi-hour';

export interface CalculateBaziOptions {
  /**
   * midnight: 00:00 换日；zi-hour: 23:00 换日。
   * 默认 midnight。
   */
  dayBoundary?: DayBoundary;
}

export interface BaziInput {
  /** 中国标准时间（UTC+08:00）的当地民用时间，不接受 JavaScript Date。 */
  civilTime: CivilTime;
}

export interface HeavenlyStem {
  name: HeavenlyStemName;
  element: FiveElement;
  yinYang: YinYang;
  tenGod: TenGod | '日主';
}

export type HiddenStemOrder = 'main' | 'middle' | 'residual';

export interface HiddenStem extends HeavenlyStem {
  order: HiddenStemOrder;
}

export interface EarthlyBranch {
  name: EarthlyBranchName;
  element: FiveElement;
  hiddenStems: HiddenStem[];
}

export type PillarKey = 'year' | 'month' | 'day' | 'hour';

export interface Pillar {
  key: PillarKey;
  ganZhi: string;
  stem: HeavenlyStem;
  branch: EarthlyBranch;
}

export interface FourPillarsInput {
  year: string;
  month: string;
  day: string;
  hour: string;
}

export interface DayMaster {
  stem: HeavenlyStemName;
  element: FiveElement;
  yinYang: YinYang;
}

export interface StemRelationMember {
  pillar: PillarKey;
  position: 'stem';
  value: HeavenlyStemName;
}

export interface BranchRelationMember {
  pillar: PillarKey;
  position: 'branch';
  value: EarthlyBranchName;
}

export interface StemCombinationRelation {
  id: string;
  type: 'stem-combination';
  subtype: 'five-combination';
  members: [StemRelationMember, StemRelationMember];
  candidateElement: FiveElement;
  description: string;
}

export interface StemControlRelation {
  id: string;
  type: 'stem-control';
  members: [StemRelationMember, StemRelationMember];
  controller: StemRelationMember;
  controlled: StemRelationMember;
  description: string;
}

export type StemChartRelation = StemCombinationRelation | StemControlRelation;

export interface BranchSixCombinationRelation {
  id: string;
  type: 'branch-six-combination';
  members: [BranchRelationMember, BranchRelationMember];
  candidateElement: FiveElement;
  description: string;
}

export interface BranchThreeCombinationRelation {
  id: string;
  type: 'branch-three-combination';
  members: [BranchRelationMember, BranchRelationMember, BranchRelationMember];
  candidateElement: FiveElement;
  description: string;
}

export interface BranchClashRelation {
  id: string;
  type: 'branch-clash';
  members: [BranchRelationMember, BranchRelationMember];
  description: string;
}

export interface BranchHarmRelation {
  id: string;
  type: 'branch-harm';
  members: [BranchRelationMember, BranchRelationMember];
  description: string;
}

export interface BranchPunishmentRelation {
  id: string;
  type: 'branch-punishment';
  subtype: 'mutual' | 'triple' | 'self';
  pattern: 'zi-mao' | 'yin-si-shen' | 'chou-xu-wei' | 'self';
  members: BranchRelationMember[];
  description: string;
}

export type BranchChartRelation =
  | BranchSixCombinationRelation
  | BranchThreeCombinationRelation
  | BranchClashRelation
  | BranchHarmRelation
  | BranchPunishmentRelation;

export interface ChartRelations {
  model: 'relations-v1';
  stems: StemChartRelation[];
  branches: BranchChartRelation[];
}

export interface RootPosition {
  pillar: PillarKey;
  branch: EarthlyBranchName;
  hiddenStem: HeavenlyStemName;
  order: HiddenStemOrder;
  source: string;
}

export interface RootsContext {
  model: 'roots-v1';
  dayMaster: DayMaster;
  hasRoot: boolean;
  roots: RootPosition[];
}

export type SolarTermKind = 'jie' | 'qi';

export interface SolarTermDistance {
  name: string;
  kind: SolarTermKind;
  at: string;
  direction: 'previous' | 'next';
  distanceSeconds: number;
}

export interface SolarTermContext {
  /** 前后相邻的二十四节气。 */
  previous: SolarTermDistance;
  next: SolarTermDistance;
  /** 前后相邻的十二节；八字月柱以此为边界。 */
  previousMonthBoundary: SolarTermDistance;
  nextMonthBoundary: SolarTermDistance;
}

export type TwelveGrowthStage =
  | 'changsheng'
  | 'muyu'
  | 'guandai'
  | 'linguan'
  | 'diwang'
  | 'shuai'
  | 'bing'
  | 'si'
  | 'mu'
  | 'jue'
  | 'tai'
  | 'yang';

export type TwelveGrowthLabel =
  | '长生'
  | '沐浴'
  | '冠带'
  | '临官'
  | '帝旺'
  | '衰'
  | '病'
  | '死'
  | '墓'
  | '绝'
  | '胎'
  | '养';

export interface TwelveGrowthPosition {
  pillar: PillarKey;
  branch: EarthlyBranchName;
  stage: TwelveGrowthStage;
  stageLabel: TwelveGrowthLabel;
}

export interface TwelveGrowthContext {
  subject: DayMaster;
  direction: 'forward' | 'reverse';
  byPillar: Record<PillarKey, TwelveGrowthPosition>;
}

export type FourSeason = 'spring' | 'summer' | 'autumn' | 'winter';

export type SeasonalState = 'wang' | 'xiang' | 'xiu' | 'qiu' | 'si';

export type SeasonalStateLabel = '旺' | '相' | '休' | '囚' | '死';

export interface ElementSeasonalState {
  state: SeasonalState;
  stateLabel: SeasonalStateLabel;
}

export interface SeasonalStatesContext {
  basis: 'month-branch-four-season';
  monthBranch: EarthlyBranchName;
  season: FourSeason;
  seasonLabel: '春' | '夏' | '秋' | '冬';
  byElement: Record<FiveElement, ElementSeasonalState>;
}

export interface SeasonContextRules {
  solarTermProvider: 'lunar-typescript';
  solarTermPrecision: 'second';
  monthBoundaryTerms: 'jie';
  twelveGrowth: 'ten-stem-yang-forward-yin-reverse';
  seasonalStates: 'four-season-wang-xiang-xiu-qiu-si';
  earthTransition: 'not-modeled';
}

export interface SeasonContext {
  model: 'season-context-v1';
  solarTerms: SolarTermContext;
  twelveGrowth: TwelveGrowthContext;
  seasonalStates: SeasonalStatesContext;
  appliedRules: SeasonContextRules;
  warnings: string[];
}

export type EvidenceCategory =
  | 'season'
  | 'root'
  | 'support'
  | 'pressure';

export type EvidenceSide = 'supporting' | 'opposing';

export type EvidenceImpact = 'major' | 'moderate' | 'minor';

export interface StrengthEvidence {
  id: string;
  category: EvidenceCategory;
  relation: Relation;
  side: EvidenceSide;
  impact: EvidenceImpact;
  /** 仅用于公开、确定性的分档决策，不表示五行百分比。 */
  decisionUnits: 1 | 2 | 3;
  source: string;
  description: string;
}

export type StrengthState =
  | 'extremely-weak'
  | 'weak'
  | 'balanced'
  | 'strong'
  | 'extremely-strong';

export type Confidence = 'low' | 'medium' | 'high';

export interface DecisionBalance {
  supporting: number;
  opposing: number;
  delta: number;
  thresholds: {
    extremelyStrong: number;
    strong: number;
    weak: number;
    extremelyWeak: number;
  };
}

export interface SpecialPatternReview {
  status: 'not-indicated' | 'review-required';
  candidate: 'following-strong' | 'following-weak' | null;
  reason: string;
}

export interface StrengthAnalysis {
  status: 'completed' | 'needs-special-pattern-review';
  strength: StrengthState;
  strengthLabel: '极弱' | '偏弱' | '相对中和' | '偏强' | '极强';
  confidence: Confidence;
  dayMaster: DayMaster;
  supportingElements: FiveElement[];
  opposingElements: FiveElement[];
  evidence: StrengthEvidence[];
  decisionBalance: DecisionBalance;
  specialPattern: SpecialPatternReview;
}

export type StrengthV2SourceModel =
  | 'chart'
  | 'season-context-v1'
  | 'relations-v1'
  | 'roots-v1';

export type StrengthV2EvidenceCategory =
  | 'seasonal-state'
  | 'twelve-growth'
  | 'solar-term-distance'
  | 'visible-stem'
  | 'hidden-stem'
  | 'root'
  | 'stem-control'
  | 'root-clash'
  | 'relation-observation';

export interface StrengthV2Evidence {
  id: string;
  ruleId: string;
  category: StrengthV2EvidenceCategory;
  sourceModels: StrengthV2SourceModel[];
  sources: string[];
  side: EvidenceSide | 'neutral';
  applied: boolean;
  /** 仅用于公开、确定性的 v2 分档决策，不表示五行百分比。 */
  decisionUnits: number;
  description: string;
}

export interface StrengthV2Analysis {
  model: 'ziping-strength-v2';
  status: 'completed' | 'needs-special-pattern-review';
  strength: StrengthState;
  strengthLabel: StrengthAnalysis['strengthLabel'];
  confidence: Confidence;
  dayMaster: DayMaster;
  supportingElements: FiveElement[];
  opposingElements: FiveElement[];
  evidence: StrengthV2Evidence[];
  decisionBalance: DecisionBalance;
  specialPattern: SpecialPatternReview;
  warnings: string[];
}

export interface StrengthV2Facts {
  seasonContext?: SeasonContext;
  relations?: ChartRelations;
  roots?: RootsContext;
}

export type LuckCycleDirection = 'forward' | 'reverse';

export type LuckCycleSexForRule = 'male' | 'female';

export type LuckCycleDirectionRule = 'explicit' | 'year-stem-and-sex';

export type LuckCycleBoundaryRule = 'jie';

export type LuckCycleStartAgeRule = 'three-days-one-year';

export interface CalculateLuckCyclesOptions {
  /** 与原局排盘一致，默认 00:00 换日。 */
  dayBoundary?: DayBoundary;
  /** 直接指定顺排或逆排；提供后优先于 sexForRule。 */
  direction?: LuckCycleDirection;
  /** 仅用于 year-stem-and-sex 传统顺逆规则，不改变出生四柱。 */
  sexForRule?: LuckCycleSexForRule;
  /** 首版只支持以年干阴阳和 sexForRule 定顺逆。 */
  directionRule?: 'year-stem-and-sex';
  /** 首版只使用十二“节”作为起运边界。 */
  boundaryRule?: LuckCycleBoundaryRule;
  /** 首版只支持“三天一岁”的起运换算。 */
  startAgeRule?: LuckCycleStartAgeRule;
  /** 返回多少步十年大运，默认 10。 */
  cycleCount?: number;
}

export interface LuckCycleAgeOffset {
  years: number;
  months: number;
  days: number;
  hours: number;
  minutes: number;
}

export interface LuckCyclePeriod {
  index: number;
  ganZhi: string;
  startsAt: string;
  endsAt: string;
  startAge: LuckCycleAgeOffset;
  endAge: LuckCycleAgeOffset;
}

export interface BeforeFirstLuckCycle {
  label: '起运前';
  startsAt: string;
  endsAt: string;
}

export interface LuckCycleAppliedRules {
  calendar: 'solar';
  timeStandard: 'china-standard-time';
  dayBoundary: DayBoundary;
  directionRule: LuckCycleDirectionRule;
  boundaryRule: LuckCycleBoundaryRule;
  startAgeRule: LuckCycleStartAgeRule;
  cycleLengthYears: 10;
  cycleInterval: 'start-inclusive-end-exclusive';
  solarTermProvider: 'lunar-typescript';
  solarTermPrecision: 'second';
}

export interface LuckCycleResult {
  model: 'luck-cycle-v1';
  input: {
    civilTime: Required<CivilTime>;
    sexForRule?: LuckCycleSexForRule;
  };
  sourcePillars: FourPillarsInput;
  direction: LuckCycleDirection;
  directionReason: string;
  boundaryTerm: SolarTermDistance;
  startAge: LuckCycleAgeOffset;
  startsAt: string;
  beforeStart: BeforeFirstLuckCycle;
  cycles: LuckCyclePeriod[];
  appliedRules: LuckCycleAppliedRules;
  trace: TraceStep[];
  warnings: string[];
}

export type LuckAnalysisPillarKey = PillarKey | 'luck';

export interface LuckAnalysisStemMember {
  source: 'natal' | 'luck';
  pillar: LuckAnalysisPillarKey;
  position: 'stem';
  value: HeavenlyStemName;
}

export interface LuckAnalysisBranchMember {
  source: 'natal' | 'luck';
  pillar: LuckAnalysisPillarKey;
  position: 'branch';
  value: EarthlyBranchName;
}

export interface LuckAnalysisStemCombinationRelation {
  id: string;
  type: 'stem-combination';
  subtype: 'five-combination';
  members: [LuckAnalysisStemMember, LuckAnalysisStemMember];
  candidateElement: FiveElement;
  transformationStatus: 'candidate-only';
  description: string;
}

export interface LuckAnalysisStemControlRelation {
  id: string;
  type: 'stem-control';
  members: [LuckAnalysisStemMember, LuckAnalysisStemMember];
  controller: LuckAnalysisStemMember;
  controlled: LuckAnalysisStemMember;
  description: string;
}

export type LuckAnalysisStemRelation =
  | LuckAnalysisStemCombinationRelation
  | LuckAnalysisStemControlRelation;

export interface LuckAnalysisBranchSixCombinationRelation {
  id: string;
  type: 'branch-six-combination';
  members: [LuckAnalysisBranchMember, LuckAnalysisBranchMember];
  candidateElement: FiveElement;
  transformationStatus: 'candidate-only';
  description: string;
}

export interface LuckAnalysisBranchThreeCombinationRelation {
  id: string;
  type: 'branch-three-combination';
  members: [
    LuckAnalysisBranchMember,
    LuckAnalysisBranchMember,
    LuckAnalysisBranchMember,
  ];
  candidateElement: FiveElement;
  transformationStatus: 'candidate-only';
  description: string;
}

export interface LuckAnalysisBranchClashRelation {
  id: string;
  type: 'branch-clash';
  members: [LuckAnalysisBranchMember, LuckAnalysisBranchMember];
  description: string;
}

export interface LuckAnalysisBranchHarmRelation {
  id: string;
  type: 'branch-harm';
  members: [LuckAnalysisBranchMember, LuckAnalysisBranchMember];
  description: string;
}

export interface LuckAnalysisBranchPunishmentRelation {
  id: string;
  type: 'branch-punishment';
  subtype: 'mutual' | 'triple' | 'self';
  pattern: 'zi-mao' | 'yin-si-shen' | 'chou-xu-wei' | 'self';
  members: LuckAnalysisBranchMember[];
  description: string;
}

export type LuckAnalysisBranchRelation =
  | LuckAnalysisBranchSixCombinationRelation
  | LuckAnalysisBranchThreeCombinationRelation
  | LuckAnalysisBranchClashRelation
  | LuckAnalysisBranchHarmRelation
  | LuckAnalysisBranchPunishmentRelation;

export interface LuckAnalysisStem {
  name: HeavenlyStemName;
  element: FiveElement;
  yinYang: YinYang;
  tenGod: TenGod;
}

export interface LuckAnalysisHiddenStem extends LuckAnalysisStem {
  order: HiddenStemOrder;
}

export interface LuckAnalysisRootFact {
  hiddenStem: HeavenlyStemName;
  order: HiddenStemOrder;
  source: string;
}

export interface LuckAnalysisBranch {
  name: EarthlyBranchName;
  element: FiveElement;
  hiddenStems: LuckAnalysisHiddenStem[];
  twelveGrowth: {
    stage: TwelveGrowthStage;
    stageLabel: TwelveGrowthLabel;
  };
  root: {
    hasRoot: boolean;
    roots: LuckAnalysisRootFact[];
  };
}

export interface LuckAnalysisPeriod {
  cycle: LuckCyclePeriod;
  stem: LuckAnalysisStem;
  branch: LuckAnalysisBranch;
  relations: {
    stems: LuckAnalysisStemRelation[];
    branches: LuckAnalysisBranchRelation[];
  };
}

export interface LuckAnalysisAppliedRules {
  luckCycleModel: 'luck-cycle-v1';
  relationsModel: 'luck-to-natal-relations-v1';
  tenGod: 'day-master-relative';
  twelveGrowth: 'ten-stem-yang-forward-yin-reverse';
  root: 'same-element-hidden-stem';
  tripleRelations: 'complete-only';
  transformations: 'candidate-only';
  interpretation: 'none';
}

export interface LuckAnalysisResult {
  model: 'luck-analysis-v1';
  input: LuckCycleResult['input'];
  sourcePillars: FourPillarsInput;
  dayMaster: DayMaster;
  direction: LuckCycleDirection;
  directionReason: string;
  startsAt: string;
  cycles: LuckAnalysisPeriod[];
  appliedRules: LuckAnalysisAppliedRules;
  trace: TraceStep[];
  warnings: string[];
}

export interface CalculateAnnualCyclesInput {
  /** 按公历年编号选择起始流年，包含该年。 */
  fromYear: number;
  /** 按公历年编号选择结束流年，包含该年。 */
  toYear: number;
}

export interface AnnualCyclePeriod {
  index: number;
  /** 该流年立春所在的公历年。 */
  anchorYear: number;
  ganZhi: string;
  startsAt: string;
  endsAt: string;
}

export interface AnnualCycleAppliedRules {
  calendarInput: 'gregorian-year-range';
  timeStandard: 'china-standard-time';
  yearBoundary: 'beginning-of-spring';
  cycleInterval: 'start-inclusive-end-exclusive';
  solarTermProvider: 'lunar-typescript';
  solarTermPrecision: 'second';
}

export interface AnnualCycleResult {
  model: 'annual-cycle-v1';
  input: CalculateAnnualCyclesInput;
  cycles: AnnualCyclePeriod[];
  appliedRules: AnnualCycleAppliedRules;
  trace: TraceStep[];
  warnings: string[];
}

export interface AppliedRules {
  calendar: 'solar';
  timeStandard: 'china-standard-time';
  yearBoundary: 'beginning-of-spring';
  monthBoundary: 'major-solar-terms';
  dayBoundary: DayBoundary;
  seasonContextModel: 'season-context-v1';
  relationsModel: 'relations-v1';
  rootsModel: 'roots-v1';
  strengthModel: 'ziping-strength-v1';
  strengthV2Model: 'ziping-strength-v2';
  specialPatterns: 'flag-only';
}

export interface TraceStep {
  ruleId: string;
  description: string;
  input: Record<string, unknown>;
  output: Record<string, unknown>;
}

export interface BaziChart {
  pillars: {
    year: Pillar;
    month: Pillar;
    day: Pillar;
    hour: Pillar;
  };
  dayMaster: DayMaster;
}

export interface BaziResult extends BaziChart {
  input: {
    civilTime: Required<CivilTime>;
  };
  seasonContext: SeasonContext;
  relations: ChartRelations;
  roots: RootsContext;
  analysis: StrengthAnalysis;
  analysisV2: StrengthV2Analysis;
  appliedRules: AppliedRules;
  trace: TraceStep[];
  warnings: string[];
}