calendar-tool

项目背景与战略目标

在后端服务中，涉及中国传统节日安排、生辰八字计算、农业节气调度、民俗活动预约及历史数据归档等场景时，公历（阳历）与农历（阴历）的精确换算是基础且高频的需求。现有的农历算法库（如 JS 的 lunar-javascript 或 Python 的 chinesecalendar）多基于查表法或动态语言实现，存在内存占用大、闰月计算逻辑复杂、长周期推算精度不足等问题。特别是在高并发微服务架构下，低效的历法转换逻辑极易成为系统吞吐量的瓶颈，且动态语言的弱类型特性容易导致闰月、节气边界处理错误，引发生产事故。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 calendar-tool，打造一款零分配、高精度、强类型安全的后端历法处理基础库。

• 极致换算性能：利用仓颉的静态编译优化和位运算潜力，实现无依赖查表的快速天文算法推算（或压缩表查询），避免字符串频繁创建，性能较动态语言提升 10-50 倍。

• 内存安全与零拷贝：依托仓颉所有权机制，在日期结构转换中实现零拷贝解析，直接操作底层整型数据，大幅降低 GC 压力，适合长运行时的微服务。

• 全周期高精度支持：内置 1900-2100 年（可扩展至前后 500 年）的精确闰月、节气、干支纪年算法，支持正负闰月输入，确保历史及未来日期换算无误。

• 强类型错误处理：利用代数数据类型（ADT）显式表达解析成功、非法日期或超出范围错误，杜绝隐式的 null 或异常崩溃，提升系统稳定性。

• 丰富的文化属性扩展：自动计算生肖、星座、干支（年月日时）、彭祖百忌、宜忌等传统历法属性，满足全球化后端服务的本地化需求。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单线程转换吞吐量 > 20M OPS，P99 延迟 < 10ns，内存峰值控制在输入大小的 1.2 倍以内（零拷贝模式下更低）。

• 安全要求：严格防止非法输入导致的数组越界或死循环；限制递归深度防止栈溢出；支持白名单过滤非法字符。

• 可靠性：能够处理截断的日期字符串、非法闰月及非标准格式，保证服务不挂起；支持线程安全的多线程并发调用。

• 可维护性：历法规则与核心引擎解耦，支持热加载历法数据表，代码具备完善的文档注释。

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

// 定义农历日期结构 (不可变)
struct LunarDate {
    year: Int32 // 农历年份
    month: Int32 // 农历月份 (1-12, 闰月为负数或特定标记)
    day: Int32 // 农历日期
    isLeapMonth: Bool // 是否闰月
    
    // 获取传统属性
    func getYearGanZhi(): String // 如 "丙午"
    func getMonthGanZhi(): String
    func getDayGanZhi(): String
    func getZodiac(): String // 生肖
    func getConstellation(): String // 星座 (基于公历)
}

// 定义公历日期结构
struct SolarDate {
    year: Int32
    month: Int32
    day: Int32
    
    // 转换为农历
    func toLunar(): LunarDate
}

// 定义节气信息
struct SolarTerm {
    name: String
    time: TimePoint // 精确到秒
}

// 定义解析结果
enum ParseResult<T> {
    case Success(T)
    case Failure(ParseError)
}

// 定义错误类型
enum ParseError {
    case InvalidFormat(String)
    case OutOfRange(String)
    case InvalidLunarDate(String) // 如农历二月三十
    case LeapMonthError(String)
}

// 核心转换接口
interface CalendarEngine {
    // 公历转农历
    func solarToLunar(date: SolarDate): ParseResult<LunarDate>
    
    // 农历转公历
    func lunarToSolar(year: Int32, month: Int32, day: Int32, isLeap: Bool): ParseResult<SolarDate>
    
    // 获取指定年份的节气列表
    func getSolarTerms(year: Int32): List<SolarTerm>
    
    // 批量公历转农历
    func batchSolarToLunar(dates: List<SolarDate>): List<ParseResult<LunarDate>>
    
    // 获取指定日期的宜忌
    func getDailyYiJi(date: SolarDate): Map<String, List<String>>
}

// 工厂类
object CalendarFactory {
    static func createStandard(): CalendarEngine
    static func createExtendedRange(): CalendarEngine // 支持更大年份范围
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：核心双向转换引擎 + 基础干支/生肖计算 + 单元测试 (覆盖率≥95%)。

• 第二阶段：节气精确计算 + 传统属性扩展（宜忌/彭祖百忌）+ 批量转换优化 + 性能基准测试。

• 第三阶段：长周期支持（前后 500 年）+ 模糊测试 + cjpm 发布包 + 最佳实践文档。

项目实施路线图

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

仓颉语言专项质量规范

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

• 类型安全：充分利用泛型定义解析结果，利用模式匹配 exhaustive check 确保所有错误分支被处理。

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

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖闰月、月末、节气交接时刻、非法日期及边界年份（1900, 2100等）。

• 兼容性测试：使用权威万年历数据集（如中国科学院紫金山天文台数据）进行回归测试，确保转换结果 100% 一致。

• 性能基准：建立与 lunar-javascript, chinesecalendar 的性能对比基准，确保在同等功能下性能最优。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明历法规则、闰月处理逻辑及传统属性含义。

• 架构决策记录：记录算法选型（查表法 vs 天文算法）及内存管理策略的依据。

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

持续集成质量门禁

#!/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 authoritative-lunar-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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求