feat: 引入可切换星历模型并扩展天象观测链路

- 新增半解析、旧模型、自定义与多源堆叠星历实例，提供 Context、Instance、SPK 读取及状态与视位置计算
- 统一太阳、月球和行星实例接口，扩展黄经穿越、留、相位、最近角距、偕日可见、任意高度升落、轨道节点及凌日等天象查询
- 完善日月食、月掩与凌日的月缘剖面、有限盘面接触、站心修正、局地可见性、全球路径和地图输出
- 新增 SVG、GeoJSON、KML 天象输出及凌日、月掩和月缘地形相关缓存与几何求解
- 新增恒星星表导入与查询，支持 CSV、Hipparcos、BSC5、Stellarium 等格式及名称、交叉标识、锥面检索和星等过滤
- 补充 IAU 2006、地球定向、折射消光、大气观测、轨道传播及半解析行星/月球数据支持
- 将默认未来民用时标切换为 TimeScaleLeapHour，更新 2027–2400 农历速查表、中文日期解析和时区边界处理
- 增加事件基线、跨模型回归、几何边界、月缘地形和输出契约测试，完善中英文手册、示例资源、NOTICE 与忽略规则

saturn/truncated.go

@@ -5,100 +5,99 @@ import (
 
 	"b612.me/astro/basic"
 	"b612.me/astro/calendar"
-	"b612.me/astro/planet"
 )
 
 // N variants keep the same semantics as the non-N APIs; n < 0 means full series.
 
-// ApparentLoN 视黄经（截断版） / truncated apparent ecliptic longitude.
-func ApparentLoN(date time.Time, n int) float64 {
+// ApparentLoN 视黄经（n 变体） / n-parameterised apparent ecliptic longitude.
+func (module *Saturn) ApparentLoN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.SaturnApparentLoN(basic.UTC2TT(jd), n)
+	return basic.SaturnApparentLoNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// ApparentBoN 视黄纬（截断版） / truncated apparent ecliptic latitude.
-func ApparentBoN(date time.Time, n int) float64 {
+// ApparentBoN 视黄纬（n 变体） / n-parameterised apparent ecliptic latitude.
+func (module *Saturn) ApparentBoN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.SaturnApparentBoN(basic.UTC2TT(jd), n)
+	return basic.SaturnApparentBoNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// ApparentRaN 视赤经（截断版） / truncated apparent right ascension.
-func ApparentRaN(date time.Time, n int) float64 {
+// ApparentRaN 视赤经（n 变体） / n-parameterised apparent right ascension.
+func (module *Saturn) ApparentRaN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.SaturnApparentRaN(basic.UTC2TT(jd), n)
+	return basic.SaturnApparentRaNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// ApparentDecN 视赤纬（截断版） / truncated apparent declination.
-func ApparentDecN(date time.Time, n int) float64 {
+// ApparentDecN 视赤纬（n 变体） / n-parameterised apparent declination.
+func (module *Saturn) ApparentDecN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.SaturnApparentDecN(basic.UTC2TT(jd), n)
+	return basic.SaturnApparentDecNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// ApparentRaDecN 视赤经赤纬（截断版） / truncated apparent right ascension and declination.
-func ApparentRaDecN(date time.Time, n int) (float64, float64) {
+// ApparentRaDecN 视赤经赤纬（n 变体） / n-parameterised apparent right ascension and declination.
+func (module *Saturn) ApparentRaDecN(date time.Time, n int) (float64, float64) {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.SaturnApparentRaDecN(basic.UTC2TT(jd), n)
+	return basic.SaturnApparentRaDecNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// ApparentMagnitudeN 视星等（截断版） / truncated apparent magnitude.
-func ApparentMagnitudeN(date time.Time, n int) float64 {
+// ApparentMagnitudeN 视星等（n 变体） / n-parameterised apparent magnitude.
+func (module *Saturn) ApparentMagnitudeN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.SaturnMagN(basic.UTC2TT(jd), n)
+	return basic.SaturnMagNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// EarthDistanceN 地球距离（截断版） / truncated Earth distance.
-func EarthDistanceN(date time.Time, n int) float64 {
+// EarthDistanceN 地球距离（n 变体） / n-parameterised Earth distance.
+func (module *Saturn) EarthDistanceN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return basic.EarthSaturnAwayN(basic.UTC2TT(jd), n)
+	return basic.EarthSaturnAwayNWithInstance(basic.UTC2TT(jd), n, module.inst)
 }
 
-// SunDistanceN 太阳距离（截断版） / truncated Sun distance.
-func SunDistanceN(date time.Time, n int) float64 {
+// SunDistanceN 太阳距离（n 变体） / n-parameterised Sun distance.
+func (module *Saturn) SunDistanceN(date time.Time, n int) float64 {
 	jd := calendar.Date2JD(date.UTC())
-	return planet.WherePlanetN(5, 2, basic.UTC2TT(jd), n)
+	return basic.PlanetCoordinateNWithInstance(5, 2, basic.UTC2TT(jd), n, module.inst)
 }
 
-// AltitudeN 高度角（截断版） / truncated altitude angle.
-func AltitudeN(date time.Time, lon, lat float64, n int) float64 {
+// AltitudeN 站心视高度角（n 变体） / n-parameterised topocentric apparent altitude.
+func (module *Saturn) AltitudeN(date time.Time, lon, lat float64, n int) float64 {
 	localJD := basic.Date2JD(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	return basic.SaturnHeightN(localJD, lon, lat, timezone, n)
+	return basic.SaturnHeightNWithInstance(localJD, lon, lat, timezone, n, module.inst)
 }
 
-// ZenithN 天顶距（截断版） / truncated zenith distance.
-func ZenithN(date time.Time, lon, lat float64, n int) float64 {
-	return 90 - AltitudeN(date, lon, lat, n)
+// ZenithN 天顶距（n 变体） / n-parameterised zenith distance.
+func (module *Saturn) ZenithN(date time.Time, lon, lat float64, n int) float64 {
+	return 90 - module.AltitudeN(date, lon, lat, n)
 }
 
-// AzimuthN 方位角（截断版） / truncated azimuth angle.
-func AzimuthN(date time.Time, lon, lat float64, n int) float64 {
+// AzimuthN 站心方位角（n 变体） / n-parameterised topocentric azimuth.
+func (module *Saturn) AzimuthN(date time.Time, lon, lat float64, n int) float64 {
 	localJD := basic.Date2JD(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	return basic.SaturnAzimuthN(localJD, lon, lat, timezone, n)
+	return basic.SaturnAzimuthNWithInstance(localJD, lon, lat, timezone, n, module.inst)
 }
 
-// HourAngleN 时角（截断版） / truncated hour angle.
-func HourAngleN(date time.Time, lon float64, n int) float64 {
+// HourAngleN 时角（n 变体） / n-parameterised hour angle.
+func (module *Saturn) HourAngleN(date time.Time, lon float64, n int) float64 {
 	localJD := basic.Date2JD(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	return basic.SaturnHourAngleN(localJD, lon, timezone, n)
+	return basic.SaturnHourAngleNWithInstance(localJD, lon, timezone, n, module.inst)
 }
 
-// CulminationTimeN 中天时间（截断版） / truncated culmination time.
-func CulminationTimeN(date time.Time, lon float64, n int) time.Time {
+// CulminationTimeN 中天时间（n 变体） / n-parameterised culmination time.
+func (module *Saturn) CulminationTimeN(date time.Time, lon float64, n int) time.Time {
 	date = time.Date(date.Year(), date.Month(), date.Day(), 0, 0, 0, 0, date.Location())
 	localJD := basic.Date2JD(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	calcJD := basic.SaturnCulminationTimeN(localJD, lon, timezone, n) - timezone/24.0
+	calcJD := basic.SaturnCulminationTimeNWithInstance(localJD, lon, timezone, n, module.inst) - timezone/24.0
 	return basic.JD2DateByZone(calcJD, date.Location(), false)
 }
 
-// RiseTimeN 升起时间（截断版） / truncated rise time.
-func RiseTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
+// RiseTimeN 升起时间（n 变体） / n-parameterised rise time.
+func (module *Saturn) RiseTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
 	var aeroFloat float64
 	if aero {
 		aeroFloat = 1
@@ -107,17 +106,17 @@ func RiseTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time
 	localJD := basic.Date2JD(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	riseJD, err := basic.SaturnRiseTimeN(localJD, lon, lat, timezone, aeroFloat, height, n)
+	riseJD, err := basic.SaturnRiseTimeNWithInstance(localJD, lon, lat, timezone, aeroFloat, height, n, module.inst)
 	return riseSetResult(date, riseJD, err)
 }
 
-// DownTimeN 落下时间别名（截断版） / truncated down-time alias.
-func DownTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
-	return SetTimeN(date, lon, lat, height, aero, n)
+// DownTimeN 落下时间别名（n 变体） / n-parameterised down-time alias.
+func (module *Saturn) DownTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
+	return module.SetTimeN(date, lon, lat, height, aero, n)
 }
 
-// SetTimeN 落下时间（截断版） / truncated set time.
-func SetTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
+// SetTimeN 落下时间（n 变体） / n-parameterised set time.
+func (module *Saturn) SetTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
 	var aeroFloat float64
 	if aero {
 		aeroFloat = 1
@@ -126,6 +125,6 @@ func SetTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.
 	localJD := basic.Date2JD(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	riseJD, err := basic.SaturnSetTimeN(localJD, lon, lat, timezone, aeroFloat, height, n)
+	riseJD, err := basic.SaturnSetTimeNWithInstance(localJD, lon, lat, timezone, aeroFloat, height, n, module.inst)
 	return riseSetResult(date, riseJD, err)
 }