suncalc

项目背景与战略目标

在后端服务中，基于地理位置和时间的光照计算是智慧农业（光照时长分析）、新能源（光伏板角度调整、发电量预测）、物流调度（夜间行车限制）及地理信息系统（GIS）的核心需求。现有的天文计算库（如 JS 的 suncalc 或 Python 的 pysolar）多采用动态语言实现，浮点运算效率较低，且在高并发场景下（如百万级设备同时请求日出日落时间）容易成为 CPU 瓶颈。此外，动态类型的隐式转换可能导致精度丢失或运行时错误。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 suncalc，打造一款高精度、向量化加速、强类型安全的后端天文计算基础库。

• 极致计算性能：利用仓颉的静态编译优化和 SIMD 指令集（针对浮点运算），实现毫秒级甚至微秒级的单点计算，支持批量向量化计算，性能较动态语言提升 20-100 倍。

• 内存安全与零分配：依托仓颉值类型（Value Types）和栈分配机制，在计算过程中避免堆内存分配，杜绝 GC 压力，适合高频调用的实时计算场景。

• 高精度数学模型：内置多种天文算法模型（如 SPA, Meeus），支持双精度甚至更高精度的浮点运算，确保长期运行下的累积误差最小化。

• 强类型错误处理：利用代数数据类型（ADT）显式表达计算成功、极昼/极夜等特殊情况，杜绝隐式的 null 或无效时间戳，提升系统稳定性。

• 时区与地点无关性：纯数学计算核心，无外部依赖，完美适配分布式微服务架构，支持任意时区和经纬度输入。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单线程计算吞吐量 > 10M OPS，P99 延迟 < 1μs，内存峰值为 O(1)（无堆分配）。

• 安全要求：严格处理非法经纬度输入（如超出范围），防止除零错误或 NaN 传播；所有数学函数需经过边界值测试。

• 可靠性：能够处理闰秒、时区切换及极端地理坐标（南北极点），保证计算结果数学上合理或服务不挂起。

• 可维护性：算法实现与业务逻辑解耦，支持插拔式天文模型（如切换高精度模型），代码具备完善的数学公式注释。

核心接口设计示例 (伪代码)

// 定义地理坐标
struct GeoLocation {
    latitude: Float64 // -90 to 90
    longitude: Float64 // -180 to 180
    altitude: Float64 // meters, default 0
}

// 定义天文计算结果
struct SunPosition {
    azimuth: Float64 // degrees, 0-360
    altitude: Float64 // degrees, -90-90
    distance: Float64 // AU
}

struct SunTimes {
    sunrise: Option<TimePoint> // None if polar night
    sunset: Option<TimePoint>  // None if polar day
    solarNoon: TimePoint
    goldenHourStart: Option<TimePoint>
    goldenHourEnd: Option<TimePoint>
    civilDawn: Option<TimePoint>
    civilDusk: Option<TimePoint>
}

// 定义计算错误
enum AstroError {
    case InvalidCoordinates(String)
    case PolarDayOrNight(String)
    case CalculationDiverged
}

// 核心计算接口
interface AstroEngine {
    // 计算太阳位置
    func getSunPosition(time: TimePoint, location: GeoLocation): SunPosition
    
    // 计算日出日落时间
    func getSunTimes(date: LocalDate, location: GeoLocation): SunTimes
    
    // 计算月相 (0.0 - 1.0)
    func getMoonPhase(time: TimePoint): Float64
    
    // 批量计算 (向量化优化)
    func batchGetSunPositions(times: List<TimePoint>, location: GeoLocation): List<SunPosition>
    
    // 计算日照时长 (分钟)
    func getDaylightDuration(date: LocalDate, location: GeoLocation): Int32
}

// 工厂类
object SunCalcFactory {
    static func createStandard(): AstroEngine // 标准精度
    static func createHighPrecision(): AstroEngine // 高精度模型 (SPA)
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：核心太阳位置算法 + 日出日落计算 + 单元测试 (覆盖率≥95%) + 精度验证报告。

• 第二阶段：月球计算模块 + 批量向量化优化 + 极昼极夜处理 + 性能基准测试。

• 第三阶段：完整坐标系转换 + 模糊测试 + cjpm 发布包 + 最佳实践文档（含农业/光伏场景案例）。

项目实施路线图

技术实现规范与质量认证体系

仓颉语言专项质量规范

• 编码规范：100% 符合仓颉语言官方编码规范，通过 cjfmt 自动格式化校验。

• 类型安全：充分利用 Float64 类型确保精度，利用 Option 类型处理极昼极夜等无解情况，杜绝 null。

• 错误处理：所有非法输入必须通过 Result 类型返回，严禁抛出未捕获的运行时异常。

• 数值稳定性：关键三角函数计算需考虑数值稳定性，避免大数吃小数问题。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖两极地区、赤道、闰年、夏令时切换等边界情况。

• 精度验证：与美国海军天文台（USNO）或 NASA JPL 星历表数据进行对比，确保误差在允许范围内。

• 性能基准：建立与 suncalc (JS), pysolar (Python), PyEphem 的性能对比基准。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明各算法模型的来源及适用精度范围。

• 架构决策记录：记录天文模型选型（如 Meeus vs SPA）及优化策略的依据。

• 贡献指南：明确仓颉项目构建、调试、提交全流程规范。

持续集成质量门禁

#!/bin/bash
# PR 自动化流水线脚本

# 1. 格式检查
cjpm fmt --check

# 2. 构建检查
cjpm build
cjpm build --release

# 3. 静态 lint 检查
cjpm lint --deny-warnings

# 4. 全量测试与覆盖率
cjpm test --all-features --coverage

# 5. 精度验证测试 (对比权威数据)
cjpm test --suite astronomical-accuracy-validation

# 6. 性能基准测试
cjpm bench --threshold 5%

技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0 及以上版本（强制）。

• 构建与包管理：CJPM (Cangjie Package Manager)。

• 测试框架：仓颉原生测试框架。

• 质量工具：cjfmt, cjpm lint, cjpm bench。

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 环境需预置权威天文星历表数据集用于精度回归测试。

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求