feat: 扩展天文计算能力

- 新增日食、月食、本地可见性、中心线、半影区域、SVG 图示与沙罗周期信息
- 新增行星冲合、留、方照、物理星历、视直径、相位、亮肢角、轨道节点等计算
- 新增木星伽利略卫星位置、现象与接触事件计算
- 新增恒星星表、星座判定、自行修正与观测辅助能力
- 新增 coord、formula、orbit、sundial、lite/sun、lite/moon 等扩展包
- 完善农历年号、月相英文别名、视差角、大气质量、折射、日晷与双星计算
- 增加 NASA、JPL Horizons、IMCCE 等回归测试数据与基线测试
- 重构基础算法文件组织，补充大量公开 API 注释和语义回归测试
- 更新中文和英文 README，补充示例、精度说明、SVG 配图

venus/diameter.go

@@ -0,0 +1,30 @@
+package venus
+
+import (
+	"time"
+
+	"b612.me/astro/basic"
+	"b612.me/astro/calendar"
+)
+
+// Semidiameter 金星视半径，单位角秒 / apparent Venus semidiameter in arcseconds.
+func Semidiameter(date time.Time) float64 {
+	return SemidiameterN(date, -1)
+}
+
+// SemidiameterN 金星视半径（截断版），单位角秒 / truncated apparent Venus semidiameter in arcseconds.
+func SemidiameterN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusSemidiameterN(basic.TD2UT(jde, true), n)
+}
+
+// Diameter 金星视直径，单位角秒 / apparent Venus diameter in arcseconds.
+func Diameter(date time.Time) float64 {
+	return DiameterN(date, -1)
+}
+
+// DiameterN 金星视直径（截断版），单位角秒 / truncated apparent Venus diameter in arcseconds.
+func DiameterN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusDiameterN(basic.TD2UT(jde, true), n)
+}

venus/nodes.go

@@ -0,0 +1,30 @@
+package venus
+
+import (
+	"time"
+
+	"b612.me/astro/basic"
+	"b612.me/astro/calendar"
+)
+
+// AscendingNode 金星升交点黄经 / ascending node longitude of Venus.
+func AscendingNode(date time.Time) float64 {
+	return AscendingNodeN(date, -1)
+}
+
+// AscendingNodeN 金星升交点黄经（截断版） / truncated ascending node longitude of Venus.
+func AscendingNodeN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusAscendingNodeN(basic.TD2UT(jde, true), n)
+}
+
+// DescendingNode 金星降交点黄经 / descending node longitude of Venus.
+func DescendingNode(date time.Time) float64 {
+	return DescendingNodeN(date, -1)
+}
+
+// DescendingNodeN 金星降交点黄经（截断版） / truncated descending node longitude of Venus.
+func DescendingNodeN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusDescendingNodeN(basic.TD2UT(jde, true), n)
+}

venus/observation_n_test.go

@@ -0,0 +1,94 @@
+package venus
+
+import (
+	"math"
+	"testing"
+	"time"
+)
+
+func TestObservationNFullMatchesDefault(t *testing.T) {
+	date := time.Date(2026, 4, 26, 9, 30, 45, 123456789, time.FixedZone("CST", 8*3600))
+	lon := 116.391
+	lat := 39.907
+	height := 45.0
+
+	assertSame := func(name string, got, want float64) {
+		t.Helper()
+		if math.Float64bits(got) != math.Float64bits(want) {
+			t.Fatalf("%s full-n mismatch", name)
+		}
+	}
+	assertSamePair := func(name string, got1, got2, want1, want2 float64) {
+		t.Helper()
+		assertSame(name+".1", got1, want1)
+		assertSame(name+".2", got2, want2)
+	}
+	assertTimeSame := func(name string, got, want time.Time) {
+		t.Helper()
+		if got.UnixNano() != want.UnixNano() || got.Location().String() != want.Location().String() {
+			t.Fatalf("%s full-n mismatch", name)
+		}
+	}
+	assertErrSame := func(name string, got, want error) {
+		t.Helper()
+		switch {
+		case got == nil && want == nil:
+			return
+		case got == nil || want == nil:
+			t.Fatalf("%s full-n mismatch", name)
+		case got.Error() != want.Error():
+			t.Fatalf("%s full-n mismatch", name)
+		}
+	}
+
+	floatChecks := []struct {
+		name string
+		got  func() float64
+		want func() float64
+	}{
+		{"ApparentLo", func() float64 { return ApparentLo(date) }, func() float64 { return ApparentLoN(date, -1) }},
+		{"ApparentBo", func() float64 { return ApparentBo(date) }, func() float64 { return ApparentBoN(date, -1) }},
+		{"ApparentRa", func() float64 { return ApparentRa(date) }, func() float64 { return ApparentRaN(date, -1) }},
+		{"ApparentDec", func() float64 { return ApparentDec(date) }, func() float64 { return ApparentDecN(date, -1) }},
+		{"ApparentMagnitude", func() float64 { return ApparentMagnitude(date) }, func() float64 { return ApparentMagnitudeN(date, -1) }},
+		{"PhaseAngle", func() float64 { return PhaseAngle(date) }, func() float64 { return PhaseAngleN(date, -1) }},
+		{"IlluminatedFraction", func() float64 { return IlluminatedFraction(date) }, func() float64 { return IlluminatedFractionN(date, -1) }},
+		{"Phase", func() float64 { return Phase(date) }, func() float64 { return PhaseN(date, -1) }},
+		{"BrightLimbPositionAngle", func() float64 { return BrightLimbPositionAngle(date) }, func() float64 { return BrightLimbPositionAngleN(date, -1) }},
+		{"EarthDistance", func() float64 { return EarthDistance(date) }, func() float64 { return EarthDistanceN(date, -1) }},
+		{"SunDistance", func() float64 { return SunDistance(date) }, func() float64 { return SunDistanceN(date, -1) }},
+		{"Altitude", func() float64 { return Altitude(date, lon, lat) }, func() float64 { return AltitudeN(date, lon, lat, -1) }},
+		{"Zenith", func() float64 { return Zenith(date, lon, lat) }, func() float64 { return ZenithN(date, lon, lat, -1) }},
+		{"Azimuth", func() float64 { return Azimuth(date, lon, lat) }, func() float64 { return AzimuthN(date, lon, lat, -1) }},
+		{"HourAngle", func() float64 { return HourAngle(date, lon) }, func() float64 { return HourAngleN(date, lon, -1) }},
+		{"ParallacticAngle", func() float64 { return ParallacticAngle(date, lon, lat) }, func() float64 { return ParallacticAngleN(date, lon, lat, -1) }},
+	}
+	for _, tc := range floatChecks {
+		assertSame(tc.name, tc.got(), tc.want())
+	}
+
+	if math.Abs((Altitude(date, lon, lat)+Zenith(date, lon, lat))-90) > 1e-12 {
+		t.Fatal("altitude + zenith should equal 90 degrees")
+	}
+
+	gotRa, gotDec := ApparentRaDec(date)
+	wantRa, wantDec := ApparentRaDecN(date, -1)
+	assertSamePair("ApparentRaDec", gotRa, gotDec, wantRa, wantDec)
+
+	assertTimeSame("CulminationTime", CulminationTime(date, lon), CulminationTimeN(date, lon, -1))
+
+	rise1, err1 := RiseTime(date, lon, lat, height, true)
+	rise2, err2 := RiseTimeN(date, lon, lat, height, true, -1)
+	assertTimeSame("RiseTime", rise1, rise2)
+	assertErrSame("RiseTime.err", err1, err2)
+
+	set1, err1 := SetTime(date, lon, lat, height, true)
+	set2, err2 := SetTimeN(date, lon, lat, height, true, -1)
+	assertTimeSame("SetTime", set1, set2)
+	assertErrSame("SetTime.err", err1, err2)
+
+	down1, err1 := DownTime(date, lon, lat, height, true)
+	down2, err2 := DownTimeN(date, lon, lat, height, true, -1)
+	assertTimeSame("DownTime", down1, down2)
+	assertErrSame("DownTime.err", err1, err2)
+}

venus/parallactic.go

@@ -0,0 +1,17 @@
+package venus
+
+import (
+	"time"
+
+	"b612.me/astro/basic"
+)
+
+// ParallacticAngle 金星视差角（天顶方向角） / Venus parallactic angle.
+func ParallacticAngle(date time.Time, lon, lat float64) float64 {
+	return basic.ParallacticAngleByHourAngle(HourAngle(date, lon), ApparentDec(date), lat)
+}
+
+// ParallacticAngleN 截断项金星视差角（天顶方向角） / truncated Venus parallactic angle.
+func ParallacticAngleN(date time.Time, lon, lat float64, n int) float64 {
+	return basic.ParallacticAngleByHourAngle(HourAngleN(date, lon, n), ApparentDecN(date, n), lat)
+}

venus/phase.go

@@ -0,0 +1,52 @@
+package venus
+
+import (
+	"time"
+
+	"b612.me/astro/basic"
+	"b612.me/astro/calendar"
+)
+
+// PhaseAngle 相位角，单位度 / phase angle in degrees.
+func PhaseAngle(date time.Time) float64 {
+	return PhaseAngleN(date, -1)
+}
+
+// PhaseAngleN 相位角（截断版），单位度 / truncated phase angle in degrees.
+func PhaseAngleN(date time.Time, n int) float64 {
+	return basic.VenusPhaseAngleN(phaseJD(date), n)
+}
+
+// IlluminatedFraction 被照亮比例 / illuminated fraction.
+func IlluminatedFraction(date time.Time) float64 {
+	return IlluminatedFractionN(date, -1)
+}
+
+// IlluminatedFractionN 被照亮比例（截断版） / truncated illuminated fraction.
+func IlluminatedFractionN(date time.Time, n int) float64 {
+	return basic.VenusIlluminatedFractionN(phaseJD(date), n)
+}
+
+// Phase 相位，被照亮比例 / phase, illuminated fraction.
+func Phase(date time.Time) float64 {
+	return IlluminatedFraction(date)
+}
+
+// PhaseN 相位（截断版），被照亮比例 / truncated phase, illuminated fraction.
+func PhaseN(date time.Time, n int) float64 {
+	return IlluminatedFractionN(date, n)
+}
+
+// BrightLimbPositionAngle 亮面中心位置角，单位度 / bright limb position angle in degrees.
+func BrightLimbPositionAngle(date time.Time) float64 {
+	return BrightLimbPositionAngleN(date, -1)
+}
+
+// BrightLimbPositionAngleN 亮面中心位置角（截断版），单位度 / truncated bright limb position angle in degrees.
+func BrightLimbPositionAngleN(date time.Time, n int) float64 {
+	return basic.VenusBrightLimbPositionAngleN(phaseJD(date), n)
+}
+
+func phaseJD(date time.Time) float64 {
+	return basic.TD2UT(calendar.Date2JDE(date.UTC()), true)
+}

venus/physical.go

@@ -0,0 +1,39 @@
+package venus
+
+import (
+	"time"
+
+	"b612.me/astro/basic"
+)
+
+// PhysicalInfo 金星物理观测参数 / physical observing parameters of Venus.
+type PhysicalInfo struct {
+	// SubEarthLongitude 子地经度，单位度；采用 Venus 当前 IAU/Horizons 东经为正约定。
+	SubEarthLongitude float64
+	// SubEarthLatitude 子地纬度，单位度。
+	SubEarthLatitude float64
+	// SubSolarLongitude 子日经度，单位度；采用 Venus 当前 IAU/Horizons 东经为正约定。
+	SubSolarLongitude float64
+	// SubSolarLatitude 子日纬度，单位度。
+	SubSolarLatitude float64
+	// NorthPolePositionAngle 金星北极位置角，单位度。
+	NorthPolePositionAngle float64
+}
+
+// Physical 金星物理观测参数 / physical observing parameters of Venus.
+func Physical(date time.Time) PhysicalInfo {
+	return PhysicalN(date, -1)
+}
+
+// PhysicalN 金星物理观测参数（截断版） / truncated physical observing parameters of Venus.
+func PhysicalN(date time.Time, n int) PhysicalInfo {
+	jde := basic.Date2JDE(date.UTC())
+	info := basic.VenusPhysicalN(basic.TD2UT(jde, true), n)
+	return PhysicalInfo{
+		SubEarthLongitude:      info.SubEarthLongitude,
+		SubEarthLatitude:       info.SubEarthLatitude,
+		SubSolarLongitude:      info.SubSolarLongitude,
+		SubSolarLatitude:       info.SubSolarLatitude,
+		NorthPolePositionAngle: info.NorthPolePositionAngle,
+	}
+}

venus/physical_test.go

@@ -0,0 +1,37 @@
+package venus
+
+import (
+	"math"
+	"testing"
+	"time"
+
+	"b612.me/astro/basic"
+)
+
+func TestPhysicalWrapperMatchesBasic(t *testing.T) {
+	date := time.Date(2026, 4, 28, 9, 30, 45, 0, time.UTC)
+	jde := basic.Date2JDE(date.UTC())
+
+	got := Physical(date)
+	gotN := PhysicalN(date, -1)
+	want := basic.VenusPhysicalN(basic.TD2UT(jde, true), -1)
+
+	assertSamePhysicalFloat(t, "SubEarthLongitude", got.SubEarthLongitude, want.SubEarthLongitude)
+	assertSamePhysicalFloat(t, "SubEarthLatitude", got.SubEarthLatitude, want.SubEarthLatitude)
+	assertSamePhysicalFloat(t, "SubSolarLongitude", got.SubSolarLongitude, want.SubSolarLongitude)
+	assertSamePhysicalFloat(t, "SubSolarLatitude", got.SubSolarLatitude, want.SubSolarLatitude)
+	assertSamePhysicalFloat(t, "NorthPolePositionAngle", got.NorthPolePositionAngle, want.NorthPolePositionAngle)
+
+	assertSamePhysicalFloat(t, "PhysicalN.SubEarthLongitude", got.SubEarthLongitude, gotN.SubEarthLongitude)
+	assertSamePhysicalFloat(t, "PhysicalN.SubEarthLatitude", got.SubEarthLatitude, gotN.SubEarthLatitude)
+	assertSamePhysicalFloat(t, "PhysicalN.SubSolarLongitude", got.SubSolarLongitude, gotN.SubSolarLongitude)
+	assertSamePhysicalFloat(t, "PhysicalN.SubSolarLatitude", got.SubSolarLatitude, gotN.SubSolarLatitude)
+	assertSamePhysicalFloat(t, "PhysicalN.NorthPolePositionAngle", got.NorthPolePositionAngle, gotN.NorthPolePositionAngle)
+}
+
+func assertSamePhysicalFloat(t *testing.T, name string, got, want float64) {
+	t.Helper()
+	if math.Float64bits(got) != math.Float64bits(want) {
+		t.Fatalf("%s mismatch: got %.18f want %.18f", name, got, want)
+	}
+}

venus/physical_timezone_test.go

@@ -0,0 +1,21 @@
+package venus
+
+import (
+	"math"
+	"testing"
+	"time"
+)
+
+func TestPhysicalPreservesInstantAcrossTimezones(t *testing.T) {
+	utc := time.Date(2026, 4, 28, 9, 30, 45, 123000000, time.UTC)
+	shanghai := utc.In(time.FixedZone("UTC+8", 8*3600))
+	got := Physical(shanghai)
+	want := Physical(utc)
+	valuesGot := []float64{got.SubEarthLongitude, got.SubEarthLatitude, got.SubSolarLongitude, got.SubSolarLatitude, got.NorthPolePositionAngle}
+	valuesWant := []float64{want.SubEarthLongitude, want.SubEarthLatitude, want.SubSolarLongitude, want.SubSolarLatitude, want.NorthPolePositionAngle}
+	for i := range valuesGot {
+		if math.Float64bits(valuesGot[i]) != math.Float64bits(valuesWant[i]) {
+			t.Fatalf("timezone instant mismatch at index %d: got %.18f want %.18f", i, valuesGot[i], valuesWant[i])
+		}
+	}
+}

venus/truncated.go

@@ -0,0 +1,137 @@
+package venus
+
+import (
+	"time"
+
+	"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 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusApparentLoN(basic.TD2UT(jde, true), n)
+}
+
+// ApparentBoN 视黄纬（截断版） / truncated apparent ecliptic latitude.
+func ApparentBoN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusApparentBoN(basic.TD2UT(jde, true), n)
+}
+
+// ApparentRaN 视赤经（截断版） / truncated apparent right ascension.
+func ApparentRaN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusApparentRaN(basic.TD2UT(jde, true), n)
+}
+
+// ApparentDecN 视赤纬（截断版） / truncated apparent declination.
+func ApparentDecN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusApparentDecN(basic.TD2UT(jde, true), n)
+}
+
+// ApparentRaDecN 视赤经赤纬（截断版） / truncated apparent right ascension and declination.
+func ApparentRaDecN(date time.Time, n int) (float64, float64) {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusApparentRaDecN(basic.TD2UT(jde, true), n)
+}
+
+// ApparentMagnitudeN 视星等（截断版） / truncated apparent magnitude.
+func ApparentMagnitudeN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.VenusMagN(basic.TD2UT(jde, true), n)
+}
+
+// EarthDistanceN 地球距离（截断版） / truncated Earth distance.
+func EarthDistanceN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return basic.EarthVenusAwayN(basic.TD2UT(jde, true), n)
+}
+
+// SunDistanceN 太阳距离（截断版） / truncated Sun distance.
+func SunDistanceN(date time.Time, n int) float64 {
+	jde := calendar.Date2JDE(date.UTC())
+	return planet.WherePlanetN(2, 2, basic.TD2UT(jde, true), n)
+}
+
+// AltitudeN 高度角（截断版） / truncated altitude angle.
+func AltitudeN(date time.Time, lon, lat float64, n int) float64 {
+	jde := basic.Date2JDE(date)
+	_, loc := date.Zone()
+	timezone := float64(loc) / 3600.0
+	return basic.VenusHeightN(jde, lon, lat, timezone, n)
+}
+
+// ZenithN 天顶距（截断版） / truncated zenith distance.
+func ZenithN(date time.Time, lon, lat float64, n int) float64 {
+	return 90 - AltitudeN(date, lon, lat, n)
+}
+
+// AzimuthN 方位角（截断版） / truncated azimuth angle.
+func AzimuthN(date time.Time, lon, lat float64, n int) float64 {
+	jde := basic.Date2JDE(date)
+	_, loc := date.Zone()
+	timezone := float64(loc) / 3600.0
+	return basic.VenusAzimuthN(jde, lon, lat, timezone, n)
+}
+
+// HourAngleN 时角（截断版） / truncated hour angle.
+func HourAngleN(date time.Time, lon float64, n int) float64 {
+	jde := basic.Date2JDE(date)
+	_, loc := date.Zone()
+	timezone := float64(loc) / 3600.0
+	return basic.VenusHourAngleN(jde, lon, timezone, n)
+}
+
+// CulminationTimeN 中天时间（截断版） / truncated culmination time.
+func CulminationTimeN(date time.Time, lon float64, n int) time.Time {
+	if date.Hour() > 12 {
+		date = date.Add(time.Hour * -12)
+	}
+	jde := basic.Date2JDE(date)
+	_, loc := date.Zone()
+	timezone := float64(loc) / 3600.0
+	calcJde := basic.VenusCulminationTimeN(jde, lon, timezone, n) - timezone/24.0
+	return basic.JDE2DateByZone(calcJde, date.Location(), false)
+}
+
+// RiseTimeN 升起时间（截断版） / truncated rise time.
+func RiseTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
+	var aeroFloat float64
+	if aero {
+		aeroFloat = 1
+	}
+	if date.Hour() > 12 {
+		date = date.Add(time.Hour * -12)
+	}
+	jde := basic.Date2JDE(date)
+	_, loc := date.Zone()
+	timezone := float64(loc) / 3600.0
+	riseJde, err := basic.VenusRiseTimeN(jde, lon, lat, timezone, aeroFloat, height, n)
+	return riseSetResult(date, riseJde, 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)
+}
+
+// SetTimeN 落下时间（截断版） / truncated set time.
+func SetTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {
+	var aeroFloat float64
+	if aero {
+		aeroFloat = 1
+	}
+	if date.Hour() > 12 {
+		date = date.Add(time.Hour * -12)
+	}
+	jde := basic.Date2JDE(date)
+	_, loc := date.Zone()
+	timezone := float64(loc) / 3600.0
+	riseJde, err := basic.VenusSetTimeN(jde, lon, lat, timezone, aeroFloat, height, n)
+	return riseSetResult(date, riseJde, err)
+}

venus/venus.go

@@ -15,63 +15,115 @@ var (
 	ERR_VENUS_NEVER_DOWN = ERR_VENUS_NEVER_SET
 )
 
-// ApparentLo 视黄经
+func riseSetResult(date time.Time, jde float64, err error) (time.Time, error) {
+	if err != nil {
+		switch {
+		case errors.Is(err, basic.ErrNeverRise):
+			return time.Time{}, ERR_VENUS_NEVER_RISE
+		case errors.Is(err, basic.ErrNeverSet):
+			return time.Time{}, ERR_VENUS_NEVER_SET
+		default:
+			return time.Time{}, err
+		}
+	}
+	return basic.JDE2DateByZone(jde, date.Location(), true), nil
+}
+
+// ApparentLo 视黄经 / apparent ecliptic longitude.
+//
+// 返回金星在 date 对应绝对时刻的瞬时视黄经，单位度。
+// Returns the apparent ecliptic longitude of Venus at the instant represented by date, in degrees.
 func ApparentLo(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.VenusApparentLo(basic.TD2UT(jde, true))
 }
 
-// ApparentBo 视黄纬
+// ApparentBo 视黄纬 / apparent ecliptic latitude.
+//
+// 返回金星在 date 对应绝对时刻的瞬时视黄纬，单位度。
+// Returns the apparent ecliptic latitude of Venus at the instant represented by date, in degrees.
 func ApparentBo(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.VenusApparentBo(basic.TD2UT(jde, true))
 }
 
-// ApparentRa 视赤经
+// ApparentRa 视赤经 / apparent right ascension.
+//
+// 返回金星在 date 对应绝对时刻的瞬时视赤经，单位度。
+// Returns the apparent right ascension of Venus at the instant represented by date, in degrees.
 func ApparentRa(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.VenusApparentRa(basic.TD2UT(jde, true))
 }
 
-// ApparentDec 视赤纬
+// ApparentDec 视赤纬 / apparent declination.
+//
+// 返回金星在 date 对应绝对时刻的瞬时视赤纬，单位度。
+// Returns the apparent declination of Venus at the instant represented by date, in degrees.
 func ApparentDec(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.VenusApparentDec(basic.TD2UT(jde, true))
 }
 
-// ApparentRaDec 视赤经赤纬
+// ApparentRaDec 视赤经、视赤纬 / apparent right ascension and declination.
+//
+// 返回金星在 date 对应绝对时刻的瞬时视赤经与视赤纬，单位度。
+// Returns the apparent right ascension and declination of Venus at the instant represented by date, in degrees.
 func ApparentRaDec(date time.Time) (float64, float64) {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.VenusApparentRaDec(basic.TD2UT(jde, true))
 }
 
-// ApparentMagnitude 视星等
+// ApparentMagnitude 视星等 / apparent magnitude.
+//
+// 返回金星在 date 对应绝对时刻的视星等。
+// Returns the apparent visual magnitude of Venus at the instant represented by date.
 func ApparentMagnitude(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.VenusMag(basic.TD2UT(jde, true))
 }
 
-// EarthDistance 与地球距离（天文单位）
+// EarthDistance 地心距离 / Earth distance.
+//
+// 返回金星在 date 对应绝对时刻到地球的距离，单位 AU。
+// Returns the distance from Venus to Earth at the instant represented by date, in astronomical units.
 func EarthDistance(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return basic.EarthVenusAway(basic.TD2UT(jde, true))
 }
 
-// EarthDistance 与太阳距离（天文单位）
+// SunDistance 日心距离 / Sun distance.
+//
+// 返回金星在 date 对应绝对时刻到太阳的距离，单位 AU。
+// Returns the distance from Venus to the Sun at the instant represented by date, in astronomical units.
 func SunDistance(date time.Time) float64 {
-	jde := calendar.Date2JDE(date)
+	jde := calendar.Date2JDE(date.UTC())
 	return planet.WherePlanet(2, 2, basic.TD2UT(jde, true))
 }
 
-// Zenith 高度角
-func Zenith(date time.Time, lon, lat float64) float64 {
+// Altitude 高度角 / altitude.
+//
+// date 表示观测时刻，会读取其时区参与地方时计算；lon 为观测者经度，东正西负；lat 为观测者纬度，北正南负。返回值单位度。
+// date is the observing instant and its zone offset participates in local-time calculations. lon is east-positive longitude, lat is north-positive latitude, and the result is in degrees.
+func Altitude(date time.Time, lon, lat float64) float64 {
 	jde := basic.Date2JDE(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
 	return basic.VenusHeight(jde, lon, lat, timezone)
 }
 
-// Azimuth 方位角
+// Zenith 天顶距 / zenith distance.
+//
+// 参数与 Altitude 相同，返回值为对应时刻的天顶距，单位度。
+// Uses the same inputs as Altitude and returns the zenith distance in degrees.
+func Zenith(date time.Time, lon, lat float64) float64 {
+	return 90 - Altitude(date, lon, lat)
+}
+
+// Azimuth 方位角 / azimuth.
+//
+// date 表示观测时刻，会读取其时区参与地方时计算；lon 为观测者经度，东正西负；lat 为观测者纬度，北正南负。返回值按正北为 0°、向东增加。
+// date is the observing instant and its zone offset participates in local-time calculations. lon is east-positive longitude, lat is north-positive latitude, and azimuth is measured from north toward east.
 func Azimuth(date time.Time, lon, lat float64) float64 {
 	jde := basic.Date2JDE(date)
 	_, loc := date.Zone()
@@ -79,8 +131,10 @@ func Azimuth(date time.Time, lon, lat float64) float64 {
 	return basic.VenusAzimuth(jde, lon, lat, timezone)
 }
 
-// HourAngle 时角
-// 返回给定经纬度、对应date时区date时刻的时角（
+// HourAngle 时角 / hour angle.
+//
+// date 表示观测时刻，会读取其时区参与地方时计算；lon 为观测者经度，东正西负。返回值单位度。
+// date is the observing instant and its zone offset participates in local-time calculations. lon is east-positive longitude and the returned hour angle is in degrees.
 func HourAngle(date time.Time, lon float64) float64 {
 	jde := basic.Date2JDE(date)
 	_, loc := date.Zone()
@@ -88,8 +142,10 @@ func HourAngle(date time.Time, lon float64) float64 {
 	return basic.VenusHourAngle(jde, lon, timezone)
 }
 
-// CulminationTime 中天时间
-// 返回给定经纬度、对应date时区date时刻的中天日期
+// CulminationTime 中天时刻 / culmination time.
+//
+// date 取其所在时区的当地日期，返回值保持相同时区；lon 为观测者经度，东正西负。
+// date is interpreted on its local civil day and the result keeps the same time zone. lon is east-positive longitude.
 func CulminationTime(date time.Time, lon float64) time.Time {
 	if date.Hour() > 12 {
 		date = date.Add(time.Hour * -12)
@@ -101,14 +157,11 @@ func CulminationTime(date time.Time, lon float64) time.Time {
 	return basic.JDE2DateByZone(calcJde, date.Location(), false)
 }
 
-// RiseTime 升起时间
-// date，取日期，时区忽略
-// lon，经度，东正西负
-// lat，纬度，北正南负
-// height，高度
-// aero，true时进行大气修正
+// RiseTime 升起时间 / rise time.
+//
+// date 取其所在时区的当地日期，返回值保持相同时区；lon 为东正西负经度，lat 为北正南负纬度；height 为观测点海拔高度（米）；aero 为 true 时加入标准大气折射。
+// date is interpreted on its local civil day and the result keeps the same time zone. lon is east-positive longitude, lat is north-positive latitude, height is observer elevation in meters, and aero enables standard atmospheric refraction.
 func RiseTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
-	var err error
 	var aeroFloat float64
 	if aero {
 		aeroFloat = 1
@@ -119,35 +172,25 @@ func RiseTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, e
 	jde := basic.Date2JDE(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	riseJde := basic.VenusRiseTime(jde, lon, lat, timezone, aeroFloat, height)
-	if riseJde == -2 {
-		err = ERR_VENUS_NEVER_RISE
-	}
-	if riseJde == -1 {
-		err = ERR_VENUS_NEVER_SET
-	}
-	return basic.JDE2DateByZone(riseJde, date.Location(), true), err
+	riseJde, err := basic.VenusRiseTime(jde, lon, lat, timezone, aeroFloat, height)
+	return riseSetResult(date, riseJde, err)
 }
 
-// deprecated: -- use SetTime instead
-// DownTime 落下时间
-// date，取日期，时区忽略
-// lon，经度，东正西负
-// lat，纬度，北正南负
-// height，高度
-// aero，true时进行大气修正
+// DownTime 落下时间别名 / deprecated set-time alias.
+//
+// Deprecated: use SetTime instead.
+//
+// 参数与 SetTime 相同，仅为兼容旧接口保留。
+// Same as SetTime and kept only for backward compatibility.
 func DownTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
 	return SetTime(date, lon, lat, height, aero)
 }
 
-// SetTime 落下时间
-// date，取日期，时区忽略
-// lon，经度，东正西负
-// lat，纬度，北正南负
-// height，高度
-// aero，true时进行大气修正
+// SetTime 落下时间 / set time.
+//
+// 参数与 RiseTime 相同，返回给定当地日期内的落下时刻。
+// Uses the same inputs as RiseTime and returns the set time on the corresponding local civil day.
 func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, error) {
-	var err error
 	var aeroFloat float64
 	if aero {
 		aeroFloat = 1
@@ -158,137 +201,167 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 	jde := basic.Date2JDE(date)
 	_, loc := date.Zone()
 	timezone := float64(loc) / 3600.0
-	riseJde := basic.VenusDownTime(jde, lon, lat, timezone, aeroFloat, height)
-	if riseJde == -2 {
-		err = ERR_VENUS_NEVER_RISE
-	}
-	if riseJde == -1 {
-		err = ERR_VENUS_NEVER_SET
-	}
-	return basic.JDE2DateByZone(riseJde, date.Location(), true), err
+	riseJde, err := basic.VenusSetTime(jde, lon, lat, timezone, aeroFloat, height)
+	return riseSetResult(date, riseJde, err)
 }
 
-// LastConjunction 上次合日时间
-// 返回上次合日时间，不区分上合下合
+// LastConjunction 上一次合日 / previous conjunction with the Sun.
+//
+// 返回 date 之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the most recent conjunction with the Sun relative to date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusConjunction(jde), date.Location(), false)
 }
 
-// NextConjunction 下次合日时间
-// 返回下次合日时间，不区分上合下合
+// NextConjunction 下一次合日 / next conjunction with the Sun.
+//
+// 返回 date 之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the next conjunction with the Sun relative to date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusConjunction(jde), date.Location(), false)
 }
 
-// LastInferiorConjunction 上次下合时间
-// 返回上次下合日时间
+// LastInferiorConjunction 上一次下合 / previous inferior conjunction.
+//
+// 返回 date 之前最近一次下合时刻，结果保持 date 的时区。
+// Returns the most recent inferior conjunction relative to date, keeping date's time zone.
 func LastInferiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusInferiorConjunction(jde), date.Location(), false)
 }
 
-// NextInferiorConjunction 下次下合时间
-// 返回下次合日时间
+// NextInferiorConjunction 下一次下合 / next inferior conjunction.
+//
+// 返回 date 之后最近一次下合时刻，结果保持 date 的时区。
+// Returns the next inferior conjunction relative to date, keeping date's time zone.
 func NextInferiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusInferiorConjunction(jde), date.Location(), false)
 }
 
-// LastSuperiorConjunction 上次上合时间
-// 返回上次下合时间
+// LastSuperiorConjunction 上一次上合 / previous superior conjunction.
+//
+// 返回 date 之前最近一次上合时刻，结果保持 date 的时区。
+// Returns the most recent superior conjunction relative to date, keeping date's time zone.
 func LastSuperiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusSuperiorConjunction(jde), date.Location(), false)
 }
 
-// NextSuperiorConjunction 下次上合时间
-// 返回下次上合时间
+// NextSuperiorConjunction 下一次上合 / next superior conjunction.
+//
+// 返回 date 之后最近一次上合时刻，结果保持 date 的时区。
+// Returns the next superior conjunction relative to date, keeping date's time zone.
 func NextSuperiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusSuperiorConjunction(jde), date.Location(), false)
 }
 
-// LastRetrograde 上次留的时间
-// 返回上次留时间，不区分顺逆
+// LastRetrograde 上一次留 / previous stationary point.
+//
+// 返回 date 之前最近一次留时刻，不区分顺转逆还是逆转顺，结果保持 date 的时区。
+// Returns the most recent stationary point relative to date without distinguishing direction, keeping date's time zone.
 func LastRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusRetrograde(jde), date.Location(), false)
 }
 
-// NextRetrograde 下次留时间
-// 返回下次留的时间，不区分顺逆
+// NextRetrograde 下一次留 / next stationary point.
+//
+// 返回 date 之后最近一次留时刻，不区分顺转逆还是逆转顺，结果保持 date 的时区。
+// Returns the next stationary point relative to date without distinguishing direction, keeping date's time zone.
 func NextRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusRetrograde(jde), date.Location(), false)
 }
 
-// LastProgradeToRetrograde 上次留（顺转逆）
-// 返回上次顺转逆留的时间
+// LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
+//
+// 返回 date 之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the most recent stationary point where motion changes from prograde to retrograde relative to date, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusProgradeToRetrograde(jde), date.Location(), false)
 }
 
-// NextProgradeToRetrograde 下次留（顺转逆）
-// 返回下次顺转逆留的时间
+// NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
+//
+// 返回 date 之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the next stationary point where motion changes from prograde to retrograde relative to date, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusProgradeToRetrograde(jde), date.Location(), false)
 }
 
-// LastRetrogradeToPrograde 上次留（逆转瞬）
-// 返回上次逆转瞬留的时间
+// LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
+//
+// 返回 date 之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the most recent stationary point where motion changes from retrograde to prograde relative to date, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusRetrogradeToPrograde(jde), date.Location(), false)
 }
 
-// NextRetrogradeToPrograde 上次留（逆转瞬）
-// // 返回上次逆转瞬留的时间
+// NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
+//
+// 返回 date 之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the next stationary point where motion changes from retrograde to prograde relative to date, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusRetrogradeToPrograde(jde), date.Location(), false)
 }
 
-// LastGreatestElongation 上次大距时间
-// 返回上次大距时间，不区分东西大距
+// LastGreatestElongation 上一次大距 / previous greatest elongation.
+//
+// 返回 date 之前最近一次大距时刻，不区分东西大距，结果保持 date 的时区。
+// Returns the most recent greatest elongation relative to date without distinguishing east or west, keeping date's time zone.
 func LastGreatestElongation(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusGreatestElongation(jde), date.Location(), false)
 }
 
-// NextGreatestElongation  下次大距时间
-// 返回下次大距时间，不区分东西大距
+// NextGreatestElongation 下一次大距 / next greatest elongation.
+//
+// 返回 date 之后最近一次大距时刻，不区分东西大距，结果保持 date 的时区。
+// Returns the next greatest elongation relative to date without distinguishing east or west, keeping date's time zone.
 func NextGreatestElongation(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusGreatestElongation(jde), date.Location(), false)
 }
 
-// LastGreatestElongationEast 上次东大距时间
-// 返回上次东大距时间
+// LastGreatestElongationEast 上一次东大距 / previous greatest eastern elongation.
+//
+// 返回 date 之前最近一次东大距时刻，结果保持 date 的时区。
+// Returns the most recent greatest eastern elongation relative to date, keeping date's time zone.
 func LastGreatestElongationEast(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusGreatestElongationEast(jde), date.Location(), false)
 }
 
-// NextGreatestElongationEast 下次东大距时间
-// 返回下次东大距时间
+// NextGreatestElongationEast 下一次东大距 / next greatest eastern elongation.
+//
+// 返回 date 之后最近一次东大距时刻，结果保持 date 的时区。
+// Returns the next greatest eastern elongation relative to date, keeping date's time zone.
 func NextGreatestElongationEast(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusGreatestElongationEast(jde), date.Location(), false)
 }
 
-// LastGreatestElongationWest 上次西大距时间
-// 返回上次西大距时间
+// LastGreatestElongationWest 上一次西大距 / previous greatest western elongation.
+//
+// 返回 date 之前最近一次西大距时刻，结果保持 date 的时区。
+// Returns the most recent greatest western elongation relative to date, keeping date's time zone.
 func LastGreatestElongationWest(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusGreatestElongationWest(jde), date.Location(), false)
 }
 
-// NextGreatestElongationWest 下次西大距时间
-// 返回下次西大距时间
+// NextGreatestElongationWest 下一次西大距 / next greatest western elongation.
+//
+// 返回 date 之后最近一次西大距时刻，结果保持 date 的时区。
+// Returns the next greatest western elongation relative to date, keeping date's time zone.
 func NextGreatestElongationWest(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusGreatestElongationWest(jde), date.Location(), false)

venus/venus_test.go

@@ -1,14 +0,0 @@
-package venus
-
-import (
-	"fmt"
-	"testing"
-	"time"
-)
-
-func TestVenus(t *testing.T) {
-	date := time.Now().Add(time.Hour * -24)
-	fmt.Println(CulminationTime(date, 115))
-	fmt.Println(RiseTime(date, 115, 23, 0, false))
-	fmt.Println(SetTime(date, 115, 23, 0, false))
-}