凭证期限

本文档定义凭证的有效期和使用限制规范。

概述

凭证的使用受以下条件限制：

限制类型	说明
时间范围	凭证的生效和失效时间
周期限制	每周特定日期和时段
次数限制	最大使用次数

有效期

结构体：ValidityPeriod

时间维度的有效期定义。

message ValidityPeriod {
  uint64 valid_from = 1;        // 生效时间（UNIX毫秒时间戳，0=立即生效）
  uint64 valid_until = 2;       // 失效时间（UNIX毫秒时间戳，0=永久有效）
  Schedule schedule = 3;        // 周期性时间表
}

字段	类型	说明
valid_from	uint64	生效时间，0 表示立即生效
valid_until	uint64	失效时间，0 表示永久有效
schedule	Schedule	周期性时间表，用于限制每周/每天的生效时段

周期时间表

结构体：Schedule

周期性时间表，用于限制凭证在每周特定时段内生效。

message Schedule {
  uint32 week_days = 1;         // 生效的星期（位掩码）
  uint32 start_minutes = 2;     // 每日开始时间（从0点起的分钟数）
  uint32 end_minutes = 3;       // 每日结束时间（从0点起的分钟数）
}

字段	类型	说明
week_days	uint32	位掩码，bit0=周日，bit1=周一，...，bit6=周六
start_minutes	uint32	每日开始时间，0-1439（0:00-23:59）
end_minutes	uint32	每日结束时间，0-1439（0:00-23:59）

星期位掩码

字段名：week_days

星期	位	值
周日	bit0	1
周一	bit1	2
周二	bit2	4
周三	bit3	8
周四	bit4	16
周五	bit5	32
周六	bit6	64

常用组合

场景	week_days	说明
每天	0	不限制星期
每周一	2	仅周一
工作日	62	周一至周五
周末	65	周六周日

次数限制

次数限制定义在 Credential 结构中：

字段	类型	说明
use_count_limit	uint32	使用次数限制，0 表示不限
use_count	uint32	已使用次数

当 use_count >= use_count_limit（且 use_count_limit > 0）时，凭证失效。

有效性判断

凭证在某时刻可用，需同时满足以下条件：

1. 时间范围：valid_from <= 当前时间 <= valid_until（0 值表示无限制）
2. 周期限制：若设置了 schedule，当前时刻需在允许的星期和时段内
3. 次数限制：use_count < use_count_limit（若 use_count_limit > 0）

可用 = 在时间范围内
     AND (无周期限制 OR 在周期时段内)
     AND (无次数限制 OR 未达上限)

示例

永久有效

{
  "validity": {
    "valid_from": 0,
    "valid_until": 0
  },
  "use_count_limit": 0
}

固定时间段

2025年1月1日至2025年12月31日：

{
  "validity": {
    "valid_from": 1735689600000,
    "valid_until": 1767225599000
  }
}

工作日限时

工作日 9:00-18:00：

{
  "validity": {
    "valid_from": 0,
    "valid_until": 0,
    "schedule": {
      "week_days": 62,
      "start_minutes": 540,
      "end_minutes": 1080
    }
  }
}

一次性密码

仅可使用 1 次：

{
  "validity": {
    "valid_from": 0,
    "valid_until": 0
  },
  "use_count_limit": 1
}

组合限制

2025年内，仅周末 10:00-22:00 有效，最多使用 10 次：

{
  "validity": {
    "valid_from": 1735689600000,
    "valid_until": 1767225599000,
    "schedule": {
      "week_days": 65,
      "start_minutes": 600,
      "end_minutes": 1320
    }
  },
  "use_count_limit": 10
}