docs(kdoc): 其余模块注释统一为直白说明
把上一提交没覆盖到的模块也改完,至此仓库内不再有"只写编号、不写说明"的注释。 涉及 33 个文件(生产 24 + 测试 9),包括航班状态模型与合并引擎、事件与留痕模型、 运营日计算、投递器、历史归档作业、编解码与身份、重试与重放、健康指示器、 生命周期装配、以及各自的测试类。 改法与前面一致:先说这段代码做什么,再说为什么这么做,术语第一次出现就地解释 (FLID、OPERATION_DAY、航班版本号、删除通知、待发事件表等)。工单编号 (U07/N02/ACM2-10 之类)已全部移除;段落编号只剩 10 处,全部带文件名位于句尾, 用作延伸阅读,例如"见 docs/flight-state.md §5"。 保留了本来就自解释的行内注释、PgTestSupport 顶部的环境变量默认值表格, 以及 InboxController 里描述待补接口的 TODO。 校验:逐文件做"去注释后比对"(块注释 + 行注释清除、空白归一),33 个文件代码 零差异;另做逐行非注释代码比对,同样零差异。clean test 为 78 passed / 1 skipped。
This commit is contained in:
@@ -5,19 +5,21 @@ import java.time.LocalDateTime
|
||||
import java.time.ZoneId
|
||||
|
||||
/**
|
||||
* 运营日计算(docs/flight-state.md §2.1):由计划运行时间字段 SODT(ddMMMyyHHmm)
|
||||
* 与机场时区按切日边界推导;OPERATION_DAY 不是消息接收日或落库日,一经确定不可变。
|
||||
* 切日边界由 msgx.operation-day.cutoff-hour 配置(默认 0 = 自然日零点,业务口径待确认)。
|
||||
* 算航班的运营保障日(OPERATION_DAY):拿计划运行时间 SODT 和机场时区推出来。它不是消息
|
||||
* 接收日、也不是落库日,算出来之后就固定不变。
|
||||
*
|
||||
* 民航的一天不一定从零点开始,切日边界由 msgx.operation-day.cutoff-hour 配。默认 0 点只是
|
||||
* 占位,真实口径还要业务确认。见 docs/flight-state.md §2.1。
|
||||
*/
|
||||
class OperationDayCalculator(
|
||||
zone: ZoneId,
|
||||
cutoffHour: Int,
|
||||
) {
|
||||
private val zone: ZoneId = zone
|
||||
/** 切日边界:SODT 本地时刻早于该小时的归属前一运营日(0–23,越界收敛到边界值)。 */
|
||||
/** 切日边界小时:SODT 的本地时刻早于这个点就归属前一个运营日。取值 0–23,超出范围会被夹到边界值。 */
|
||||
private val cutoffHour: Int = cutoffHour.coerceIn(0, 23)
|
||||
|
||||
/** SODT → 运营日;输入 null/空/非法返回 null(不抛异常,调用方按"运营日不可计算"处理)。 */
|
||||
/** 把 SODT 换算成运营日;入参为空、全空白或格式不对时返回 null 而不抛异常,由调用方按"运营日算不出来"处理。 */
|
||||
fun compute(sodt: String?): LocalDate? {
|
||||
if (sodt.isNullOrBlank()) return null
|
||||
val local = parseSodt(sodt.trim()) ?: return null
|
||||
@@ -27,9 +29,10 @@ class OperationDayCalculator(
|
||||
|
||||
companion object {
|
||||
/**
|
||||
* SIS SODT 线格式:ddMMMyyHHmm(如 15DEC031723),月份英文三字母、大小写不敏感。
|
||||
* 两位年显式按 2000 基准展开(java.time 的 yy reduced-value 解析跨实现不一致,
|
||||
* 显式展开保证 AODB 侧年份窗口唯一口径;基准年待真实报文验收确认)。
|
||||
* SODT 的报文格式:ddMMMyyHHmm,比如 15DEC031723,月份是三字母英文缩写、大小写都认。
|
||||
*
|
||||
* 两位年份显式按 2000 年展开,不交给 java.time 的 yy 解析——不同实现对两位年的处理
|
||||
* 不一致,自己展开才能保证各方对年份窗口的理解相同。基准年等真实报文到了再确认。
|
||||
*/
|
||||
private val SODT_REGEX = Regex("(\\d{1,2})([A-Za-z]{3})(\\d{2})(\\d{2})(\\d{2})")
|
||||
|
||||
|
||||
Reference in New Issue
Block a user