feat: add invite code validity controls

- Add invite code starts/expires fields across contracts, API, Spacetime bindings, and admin UI - Enforce pending/expired invite code redemption behavior and expose admin status - Add admin write-operation confirmation guard and documentation - Add invite code contract/runtime tests
2026-05-04 12:29:33 +08:00
parent 1142e90a35
commit 9f3e34e81a
27 changed files with 1465 additions and 97 deletions
--- a/server-rs/crates/module-runtime/src/application.rs
+++ b/server-rs/crates/module-runtime/src/application.rs
@@ -223,6 +223,189 @@ pub fn runtime_profile_beijing_day_key(now_micros: i64) -> i64 {
        .div_euclid(PROFILE_RUNTIME_DAY_MICROS)
 }

+/// 从 YYYY-MM-DD 解析分析业务日 date_key。
+///
+/// 这里故意不引入时区库：date_key 本身就是“北京时间日历日期自 Unix 纪元起的天数”。
+pub fn parse_analytics_calendar_date_key(
+    calendar_date: &str,
+) -> Result<i64, RuntimeProfileFieldError> {
+    let (year, month, day) = parse_calendar_date_parts(calendar_date)?;
+    validate_calendar_date(year, month, day)?;
+    let date_key = days_from_civil(year, month, day);
+    validate_analytics_date_dimension_date_key(date_key)?;
+    Ok(date_key)
+}
+
+/// 校验分析日期维表 date_key 是否位于业务允许范围内。
+///
+/// 裸 i64 date_key 可由 reducer 直接传入，因此在进入日历算法前先限制范围，避免极端输入
+/// 生成无意义日期或触发整数边界风险。
+pub fn validate_analytics_date_dimension_date_key(
+    date_key: i64,
+) -> Result<(), RuntimeProfileFieldError> {
+    let min_date_key = days_from_civil(2000, 1, 1);
+    let max_date_key = days_from_civil(2100, 12, 31);
+    if date_key < min_date_key || date_key > max_date_key {
+        return Err(RuntimeProfileFieldError::InvalidAnalyticsCalendarDate);
+    }
+    Ok(())
+}
+
+pub fn build_analytics_date_dimension_from_date_key(
+    date_key: i64,
+) -> AnalyticsDateDimensionSnapshot {
+    let (year, month, day) = civil_from_days(date_key);
+    let weekday = weekday_from_date_key(date_key);
+    let iso_week_key = iso_week_key(year, month, day, weekday);
+    let week_start_date_key = date_key - i64::from(weekday - 1);
+    let week_end_date_key = week_start_date_key + 6;
+    let month_start_date_key = days_from_civil(year, month, 1);
+    let month_end_date_key = days_from_civil(year, month, days_in_month(year, month));
+    let quarter = (month - 1) / 3 + 1;
+    let quarter_start_month = (quarter - 1) * 3 + 1;
+    let quarter_end_month = quarter_start_month + 2;
+    let quarter_start_date_key = days_from_civil(year, quarter_start_month, 1);
+    let quarter_end_date_key = days_from_civil(
+        year,
+        quarter_end_month,
+        days_in_month(year, quarter_end_month),
+    );
+    let year_start_date_key = days_from_civil(year, 1, 1);
+    let year_end_date_key = days_from_civil(year, 12, 31);
+
+    AnalyticsDateDimensionSnapshot {
+        date_key,
+        calendar_date: format!("{year:04}-{month:02}-{day:02}"),
+        weekday,
+        iso_week_key,
+        week_start_date_key,
+        week_end_date_key,
+        month_key: year * 100 + i32::from(month),
+        month_start_date_key,
+        month_end_date_key,
+        quarter_key: year * 10 + i32::from(quarter),
+        quarter_start_date_key,
+        quarter_end_date_key,
+        year_key: year,
+        year_start_date_key,
+        year_end_date_key,
+    }
+}
+
+fn parse_calendar_date_parts(
+    calendar_date: &str,
+) -> Result<(i32, u8, u8), RuntimeProfileFieldError> {
+    let mut parts = calendar_date.trim().split('-');
+    let year = parts
+        .next()
+        .and_then(|value| value.parse::<i32>().ok())
+        .ok_or(RuntimeProfileFieldError::InvalidAnalyticsCalendarDate)?;
+    let month = parts
+        .next()
+        .and_then(|value| value.parse::<u8>().ok())
+        .ok_or(RuntimeProfileFieldError::InvalidAnalyticsCalendarDate)?;
+    let day = parts
+        .next()
+        .and_then(|value| value.parse::<u8>().ok())
+        .ok_or(RuntimeProfileFieldError::InvalidAnalyticsCalendarDate)?;
+    if parts.next().is_some() {
+        return Err(RuntimeProfileFieldError::InvalidAnalyticsCalendarDate);
+    }
+    Ok((year, month, day))
+}
+
+fn validate_calendar_date(year: i32, month: u8, day: u8) -> Result<(), RuntimeProfileFieldError> {
+    if !(1..=12).contains(&month) || day == 0 || day > days_in_month(year, month) {
+        return Err(RuntimeProfileFieldError::InvalidAnalyticsCalendarDate);
+    }
+    Ok(())
+}
+
+fn days_in_month(year: i32, month: u8) -> u8 {
+    match month {
+        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
+        4 | 6 | 9 | 11 => 30,
+        2 if is_leap_year(year) => 29,
+        2 => 28,
+        _ => 0,
+    }
+}
+
+fn is_leap_year(year: i32) -> bool {
+    (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
+}
+
+fn weekday_from_date_key(date_key: i64) -> u8 {
+    // 中文注释：1970-01-01 是周四；这里返回 ISO weekday，周一=1，周日=7。
+    (date_key + 3).rem_euclid(7) as u8 + 1
+}
+
+fn iso_week_key(year: i32, month: u8, day: u8, weekday: u8) -> i32 {
+    let ordinal = ordinal_day(year, month, day);
+    let week = (i32::from(ordinal) - i32::from(weekday) + 10).div_euclid(7);
+    let iso_year = if week < 1 {
+        year - 1
+    } else if week > iso_weeks_in_year(year) {
+        year + 1
+    } else {
+        year
+    };
+    let iso_week = if week < 1 {
+        iso_weeks_in_year(year - 1)
+    } else if week > iso_weeks_in_year(year) {
+        1
+    } else {
+        week
+    };
+    iso_year * 100 + iso_week
+}
+
+fn ordinal_day(year: i32, month: u8, day: u8) -> u16 {
+    (1..month)
+        .map(|current_month| u16::from(days_in_month(year, current_month)))
+        .sum::<u16>()
+        + u16::from(day)
+}
+
+fn iso_weeks_in_year(year: i32) -> i32 {
+    let jan_first_weekday = weekday_from_date_key(days_from_civil(year, 1, 1));
+    if jan_first_weekday == 4 || (jan_first_weekday == 3 && is_leap_year(year)) {
+        53
+    } else {
+        52
+    }
+}
+
+fn days_from_civil(year: i32, month: u8, day: u8) -> i64 {
+    // 中文注释：Howard Hinnant civil calendar 算法，返回 1970-01-01 起的日序号。
+    let adjusted_year = year - if month <= 2 { 1 } else { 0 };
+    let era = adjusted_year.div_euclid(400);
+    let year_of_era = adjusted_year - era * 400;
+    let month = i32::from(month);
+    let day = i32::from(day);
+    let month_prime = month + if month > 2 { -3 } else { 9 };
+    let day_of_year = (153 * month_prime + 2) / 5 + day - 1;
+    let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
+    i64::from(era * 146_097 + day_of_era - 719_468)
+}
+
+fn civil_from_days(date_key: i64) -> (i32, u8, u8) {
+    // 中文注释：days_from_civil 的反向算法，避免依赖运行环境时区。
+    let z = date_key + 719_468;
+    let era = z.div_euclid(146_097);
+    let day_of_era = z - era * 146_097;
+    let year_of_era = (day_of_era - day_of_era / 1_460 + day_of_era / 36_524
+        - day_of_era / 146_096)
+        .div_euclid(365);
+    let mut year = year_of_era + era * 400;
+    let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
+    let month_prime = (5 * day_of_year + 2).div_euclid(153);
+    let day = day_of_year - (153 * month_prime + 2).div_euclid(5) + 1;
+    let month = month_prime + if month_prime < 10 { 3 } else { -9 };
+    year += if month <= 2 { 1 } else { 0 };
+    (year as i32, month as u8, day as u8)
+}
+
 pub fn build_default_runtime_profile_task_config(
    updated_at_micros: i64,
    updated_by: String,
@@ -416,10 +599,21 @@ pub fn build_runtime_profile_redeem_code_record(
 pub fn build_runtime_profile_invite_code_record(
    snapshot: RuntimeProfileInviteCodeSnapshot,
 ) -> RuntimeProfileInviteCodeRecord {
+    let status = crate::commands::resolve_runtime_profile_invite_code_status(
+        snapshot.starts_at_micros,
+        snapshot.expires_at_micros,
+        snapshot.updated_at_micros,
+    );
+
    RuntimeProfileInviteCodeRecord {
        user_id: snapshot.user_id,
        invite_code: snapshot.invite_code,
        metadata_json: snapshot.metadata_json,
+        starts_at: snapshot.starts_at_micros.map(format_utc_micros),
+        starts_at_micros: snapshot.starts_at_micros,
+        expires_at: snapshot.expires_at_micros.map(format_utc_micros),
+        expires_at_micros: snapshot.expires_at_micros,
+        status,
        created_at: format_utc_micros(snapshot.created_at_micros),
        created_at_micros: snapshot.created_at_micros,
        updated_at: format_utc_micros(snapshot.updated_at_micros),
--- a/server-rs/crates/module-runtime/src/commands.rs
+++ b/server-rs/crates/module-runtime/src/commands.rs
@@ -89,8 +89,8 @@ pub fn build_runtime_tracking_event_input(
 ) -> Result<RuntimeTrackingEventInput, RuntimeProfileFieldError> {
    let event_id = normalize_required_string(event_id)
        .ok_or(RuntimeProfileFieldError::MissingTrackingEventId)?;
-    let event_key =
-        normalize_required_string(event_key).ok_or(RuntimeProfileFieldError::MissingTaskEventKey)?;
+    let event_key = normalize_required_string(event_key)
+        .ok_or(RuntimeProfileFieldError::MissingTaskEventKey)?;
    let scope_id = normalize_required_string(scope_id)
        .ok_or(RuntimeProfileFieldError::MissingTrackingScopeId)?;
    let metadata_json = normalize_tracking_metadata_json(metadata_json)?;
@@ -151,8 +151,12 @@ pub fn build_runtime_profile_task_config_admin_upsert_input(
    let task_id = normalize_profile_task_id(task_id)?;
    let title =
        normalize_required_string(title).ok_or(RuntimeProfileFieldError::MissingTaskTitle)?;
-    let event_key =
-        normalize_required_string(event_key).ok_or(RuntimeProfileFieldError::MissingTaskEventKey)?;
+    let event_key = normalize_required_string(event_key)
+        .ok_or(RuntimeProfileFieldError::MissingTaskEventKey)?;
+    // 中文注释：个人任务首版只按用户维度累计，避免 site/work/module 误复用用户桶。
+    if scope_kind != RuntimeTrackingScopeKind::User {
+        return Err(RuntimeProfileFieldError::UnsupportedProfileTaskScopeKind);
+    }
    if threshold == 0 {
        return Err(RuntimeProfileFieldError::InvalidTaskThreshold);
    }
@@ -326,17 +330,25 @@ pub fn build_runtime_profile_invite_code_admin_upsert_input(
    admin_user_id: String,
    invite_code: String,
    metadata_json: String,
+    starts_at_micros: Option<i64>,
+    expires_at_micros: Option<i64>,
    updated_at_micros: i64,
 ) -> Result<RuntimeProfileInviteCodeAdminUpsertInput, RuntimeProfileFieldError> {
    let admin_user_id = normalize_runtime_profile_user_id(admin_user_id)?;
    let invite_code =
        normalize_invite_code(invite_code).ok_or(RuntimeProfileFieldError::MissingInviteCode)?;
    let metadata_json = normalize_invite_code_metadata_json(metadata_json)?;
+    crate::commands::validate_runtime_profile_invite_code_validity_window(
+        starts_at_micros,
+        expires_at_micros,
+    )?;

    Ok(RuntimeProfileInviteCodeAdminUpsertInput {
        admin_user_id,
        invite_code,
        metadata_json,
+        starts_at_micros,
+        expires_at_micros,
        updated_at_micros,
    })
 }
@@ -639,6 +651,40 @@ pub fn normalize_invite_code_metadata_json(
    serde_json::to_string(&parsed).map_err(|_| RuntimeProfileFieldError::InvalidInviteCodeMetadata)
 }

+pub fn validate_runtime_profile_invite_code_validity_window(
+    starts_at_micros: Option<i64>,
+    expires_at_micros: Option<i64>,
+) -> Result<(), RuntimeProfileFieldError> {
+    if matches!((starts_at_micros, expires_at_micros), (Some(starts_at), Some(expires_at)) if starts_at > expires_at)
+    {
+        return Err(RuntimeProfileFieldError::InvalidInviteCodeValidityWindow);
+    }
+
+    Ok(())
+}
+
+pub fn resolve_runtime_profile_invite_code_status(
+    starts_at_micros: Option<i64>,
+    expires_at_micros: Option<i64>,
+    now_micros: i64,
+) -> RuntimeProfileInviteCodeStatus {
+    if starts_at_micros
+        .map(|starts_at| now_micros < starts_at)
+        .unwrap_or(false)
+    {
+        return RuntimeProfileInviteCodeStatus::Pending;
+    }
+
+    if expires_at_micros
+        .map(|expires_at| now_micros >= expires_at)
+        .unwrap_or(false)
+    {
+        return RuntimeProfileInviteCodeStatus::Expired;
+    }
+
+    RuntimeProfileInviteCodeStatus::Active
+}
+
 fn normalize_tracking_metadata_json(value: String) -> Result<String, RuntimeProfileFieldError> {
    let trimmed = value.trim();
    if trimmed.is_empty() {
--- a/server-rs/crates/module-runtime/src/domain.rs
+++ b/server-rs/crates/module-runtime/src/domain.rs
@@ -21,6 +21,10 @@ pub const PROFILE_INVITE_CODE_METADATA_DEFAULT_JSON: &str = "{}";
 pub const PROFILE_INVITE_CODE_METADATA_MAX_BYTES: usize = 4096;
 pub const PROFILE_RUNTIME_DAY_MICROS: i64 = 86_400_000_000;
 pub const PROFILE_TASK_BEIJING_OFFSET_MICROS: i64 = 28_800_000_000;
+pub const ANALYTICS_DATE_DIMENSION_MAX_SEED_DAYS: i64 = 3_660;
+// 中文注释：日期维表当前只预置运营统计可接受的业务日期范围，避免裸 date_key 极值进入日历算法。
+pub const ANALYTICS_DATE_DIMENSION_MIN_DATE: &str = "2000-01-01";
+pub const ANALYTICS_DATE_DIMENSION_MAX_DATE: &str = "2100-12-31";
 pub const PROFILE_TASK_ID_DAILY_LOGIN: &str = "daily_login";
 pub const PROFILE_TASK_EVENT_KEY_DAILY_LOGIN: &str = "daily_login";
 pub const PROFILE_TASK_DEFAULT_TITLE_DAILY_LOGIN: &str = "每日登录";
@@ -30,6 +34,30 @@ pub const SAVE_SNAPSHOT_VERSION: u32 = 2;
 pub const DEFAULT_SAVE_ARCHIVE_SUMMARY_TEXT: &str = "继续推进上一次保存的故事。";
 pub const PROFILE_RECHARGE_PAYMENT_CHANNEL_MOCK: &str = "mock";

+/// 分析日期维表的纯领域快照。
+///
+/// date_key 沿用现有北京时间自然日桶：floor((occurred_at_micros + 8h) / 1d)。
+/// calendar_date 使用该业务日对应的公历日期，格式固定为 YYYY-MM-DD。
+#[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AnalyticsDateDimensionSnapshot {
+    pub date_key: i64,
+    pub calendar_date: String,
+    pub weekday: u8,
+    pub iso_week_key: i32,
+    pub week_start_date_key: i64,
+    pub week_end_date_key: i64,
+    pub month_key: i32,
+    pub month_start_date_key: i64,
+    pub month_end_date_key: i64,
+    pub quarter_key: i32,
+    pub quarter_start_date_key: i64,
+    pub quarter_end_date_key: i64,
+    pub year_key: i32,
+    pub year_start_date_key: i64,
+    pub year_end_date_key: i64,
+}
+
 /// 运行时平台主题。
 ///
 /// 当前只冻结 light/dark 两种主题，避免各层散落字符串字面量。
@@ -411,6 +439,24 @@ impl RuntimeProfileTaskStatus {
    }
 }

+#[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum RuntimeProfileInviteCodeStatus {
+    Pending,
+    Active,
+    Expired,
+}
+
+impl RuntimeProfileInviteCodeStatus {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Pending => "pending",
+            Self::Active => "active",
+            Self::Expired => "expired",
+        }
+    }
+}
+
 #[cfg_attr(feature = "spacetime-types", derive(SpacetimeType))]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct RuntimeTrackingEventInput {
@@ -904,6 +950,8 @@ pub struct RuntimeProfileInviteCodeAdminUpsertInput {
    pub admin_user_id: String,
    pub invite_code: String,
    pub metadata_json: String,
+    pub starts_at_micros: Option<i64>,
+    pub expires_at_micros: Option<i64>,
    pub updated_at_micros: i64,
 }

@@ -919,6 +967,8 @@ pub struct RuntimeProfileInviteCodeSnapshot {
    pub user_id: String,
    pub invite_code: String,
    pub metadata_json: String,
+    pub starts_at_micros: Option<i64>,
+    pub expires_at_micros: Option<i64>,
    pub created_at_micros: i64,
    pub updated_at_micros: i64,
 }
@@ -1289,6 +1339,11 @@ pub struct RuntimeProfileInviteCodeRecord {
    pub user_id: String,
    pub invite_code: String,
    pub metadata_json: String,
+    pub starts_at: Option<String>,
+    pub starts_at_micros: Option<i64>,
+    pub expires_at: Option<String>,
+    pub expires_at_micros: Option<i64>,
+    pub status: RuntimeProfileInviteCodeStatus,
    pub created_at: String,
    pub created_at_micros: i64,
    pub updated_at: String,
--- a/server-rs/crates/module-runtime/src/errors.rs
+++ b/server-rs/crates/module-runtime/src/errors.rs
@@ -52,6 +52,7 @@ pub enum RuntimeProfileFieldError {
    InvalidRedeemCodeReward,
    InvalidRedeemCodeMaxUses,
    InvalidInviteCodeMetadata,
+    InvalidInviteCodeValidityWindow,
    MissingTaskId,
    MissingTaskTitle,
    MissingTaskEventKey,
@@ -59,6 +60,7 @@ pub enum RuntimeProfileFieldError {
    MissingTrackingScopeId,
    InvalidTaskCycle,
    InvalidTaskScopeKind,
+    UnsupportedProfileTaskScopeKind,
    InvalidTaskThreshold,
    InvalidTaskReward,
    TaskDisabled,
@@ -77,6 +79,7 @@ pub enum RuntimeProfileFieldError {
        actual_session_id: String,
    },
    NonPersistentRuntimeSnapshot,
+    InvalidAnalyticsCalendarDate,
 }

 impl std::fmt::Display for RuntimeProfileFieldError {
@@ -98,6 +101,7 @@ impl std::fmt::Display for RuntimeProfileFieldError {
            Self::InvalidInviteCodeMetadata => {
                f.write_str("邀请码 metadata 必须是合法 JSON object")
            }
+            Self::InvalidInviteCodeValidityWindow => f.write_str("邀请码开始时间不能晚于截止时间"),
            Self::MissingTaskId => f.write_str("profile_task.task_id 不能为空"),
            Self::MissingTaskTitle => f.write_str("profile_task.title 不能为空"),
            Self::MissingTaskEventKey => f.write_str("profile_task.event_key 不能为空"),
@@ -105,6 +109,9 @@ impl std::fmt::Display for RuntimeProfileFieldError {
            Self::MissingTrackingScopeId => f.write_str("tracking_event.scope_id 不能为空"),
            Self::InvalidTaskCycle => f.write_str("profile_task.cycle 无效"),
            Self::InvalidTaskScopeKind => f.write_str("profile_task.scope_kind 无效"),
+            Self::UnsupportedProfileTaskScopeKind => {
+                f.write_str("个人任务 scope_kind 首版仅支持 user")
+            }
            Self::InvalidTaskThreshold => f.write_str("profile_task.threshold 必须大于 0"),
            Self::InvalidTaskReward => f.write_str("profile_task.reward_points 必须大于 0"),
            Self::TaskDisabled => f.write_str("任务已停用"),
@@ -130,6 +137,9 @@ impl std::fmt::Display for RuntimeProfileFieldError {
            Self::NonPersistentRuntimeSnapshot => {
                f.write_str("预览或测试运行态不能创建正式 checkpoint")
            }
+            Self::InvalidAnalyticsCalendarDate => {
+                f.write_str("analytics_date_dimension.calendar_date 必须是合法 YYYY-MM-DD 日期")
+            }
        }
    }
 }
--- a/server-rs/crates/module-runtime/src/lib.rs
+++ b/server-rs/crates/module-runtime/src/lib.rs
@@ -1,4 +1,4 @@
-mod application;
+mod application;
 mod commands;
 mod domain;
 mod errors;
@@ -465,6 +465,57 @@ mod tests {
        );
    }

+    #[test]
+    fn analytics_date_dimension_handles_iso_week_across_year() {
+        let date_key = parse_analytics_calendar_date_key("2024-12-31").unwrap();
+        let dimension = build_analytics_date_dimension_from_date_key(date_key);
+
+        assert_eq!(dimension.calendar_date, "2024-12-31");
+        assert_eq!(dimension.weekday, 2);
+        assert_eq!(dimension.iso_week_key, 202501);
+        assert_eq!(
+            dimension.week_start_date_key,
+            parse_analytics_calendar_date_key("2024-12-30").unwrap()
+        );
+        assert_eq!(
+            dimension.week_end_date_key,
+            parse_analytics_calendar_date_key("2025-01-05").unwrap()
+        );
+    }
+
+    #[test]
+    fn analytics_date_dimension_handles_leap_day() {
+        let date_key = parse_analytics_calendar_date_key("2024-02-29").unwrap();
+        let dimension = build_analytics_date_dimension_from_date_key(date_key);
+
+        assert_eq!(dimension.calendar_date, "2024-02-29");
+        assert_eq!(dimension.weekday, 4);
+        assert_eq!(dimension.month_key, 202402);
+        assert_eq!(dimension.month_end_date_key, date_key);
+        assert_eq!(dimension.quarter_key, 20241);
+    }
+
+    #[test]
+    fn analytics_date_dimension_handles_quarter_boundary() {
+        let date_key = parse_analytics_calendar_date_key("2024-04-01").unwrap();
+        let dimension = build_analytics_date_dimension_from_date_key(date_key);
+
+        assert_eq!(dimension.quarter_key, 20242);
+        assert_eq!(dimension.quarter_start_date_key, date_key);
+        assert_eq!(
+            dimension.quarter_end_date_key,
+            parse_analytics_calendar_date_key("2024-06-30").unwrap()
+        );
+        assert_eq!(
+            dimension.year_start_date_key,
+            parse_analytics_calendar_date_key("2024-01-01").unwrap()
+        );
+        assert_eq!(
+            dimension.year_end_date_key,
+            parse_analytics_calendar_date_key("2024-12-31").unwrap()
+        );
+    }
+
    #[test]
    fn runtime_profile_task_status_matches_progress_and_claim() {
        assert_eq!(
@@ -525,6 +576,51 @@ mod tests {
        );
    }

+    #[test]
+    fn build_task_config_input_accepts_only_user_scope() {
+        let input = build_runtime_profile_task_config_admin_upsert_input(
+            "admin".to_string(),
+            PROFILE_TASK_ID_DAILY_LOGIN.to_string(),
+            "每日登录".to_string(),
+            "".to_string(),
+            PROFILE_TASK_EVENT_KEY_DAILY_LOGIN.to_string(),
+            RuntimeProfileTaskCycle::Daily,
+            RuntimeTrackingScopeKind::User,
+            1,
+            10,
+            true,
+            10,
+            1,
+        )
+        .expect("user scope should be accepted");
+        assert_eq!(input.scope_kind, RuntimeTrackingScopeKind::User);
+
+        for scope_kind in [
+            RuntimeTrackingScopeKind::Site,
+            RuntimeTrackingScopeKind::Module,
+            RuntimeTrackingScopeKind::Work,
+        ] {
+            assert_eq!(
+                build_runtime_profile_task_config_admin_upsert_input(
+                    "admin".to_string(),
+                    PROFILE_TASK_ID_DAILY_LOGIN.to_string(),
+                    "每日登录".to_string(),
+                    "".to_string(),
+                    PROFILE_TASK_EVENT_KEY_DAILY_LOGIN.to_string(),
+                    RuntimeProfileTaskCycle::Daily,
+                    scope_kind,
+                    1,
+                    10,
+                    true,
+                    10,
+                    1,
+                )
+                .expect_err("non-user scope should fail"),
+                RuntimeProfileFieldError::UnsupportedProfileTaskScopeKind
+            );
+        }
+    }
+
    #[test]
    fn recharge_product_catalog_matches_reference_prices() {
        let point_products = runtime_profile_recharge_point_products();
--- a/server-rs/crates/module-runtime/tests/invite_code_validity.rs
+++ b/server-rs/crates/module-runtime/tests/invite_code_validity.rs
@@ -0,0 +1,60 @@
+use module_runtime::{
+    RuntimeProfileFieldError, RuntimeProfileInviteCodeSnapshot, RuntimeProfileInviteCodeStatus,
+    build_runtime_profile_invite_code_record, resolve_runtime_profile_invite_code_status,
+    validate_runtime_profile_invite_code_validity_window,
+};
+
+#[test]
+fn invite_code_validity_window_rejects_start_after_expire() {
+    let result = validate_runtime_profile_invite_code_validity_window(Some(20), Some(10));
+
+    assert_eq!(
+        result,
+        Err(RuntimeProfileFieldError::InvalidInviteCodeValidityWindow)
+    );
+}
+
+#[test]
+fn invite_code_validity_window_allows_open_ended_or_equal_boundary() {
+    assert!(validate_runtime_profile_invite_code_validity_window(None, None).is_ok());
+    assert!(validate_runtime_profile_invite_code_validity_window(Some(10), None).is_ok());
+    assert!(validate_runtime_profile_invite_code_validity_window(None, Some(10)).is_ok());
+    assert!(validate_runtime_profile_invite_code_validity_window(Some(10), Some(10)).is_ok());
+}
+
+#[test]
+fn invite_code_status_uses_inclusive_start_and_exclusive_expire_boundary() {
+    assert_eq!(
+        resolve_runtime_profile_invite_code_status(Some(20), None, 19),
+        RuntimeProfileInviteCodeStatus::Pending
+    );
+    assert_eq!(
+        resolve_runtime_profile_invite_code_status(Some(20), Some(30), 20),
+        RuntimeProfileInviteCodeStatus::Active
+    );
+    assert_eq!(
+        resolve_runtime_profile_invite_code_status(Some(20), Some(30), 29),
+        RuntimeProfileInviteCodeStatus::Active
+    );
+    assert_eq!(
+        resolve_runtime_profile_invite_code_status(Some(20), Some(30), 30),
+        RuntimeProfileInviteCodeStatus::Expired
+    );
+}
+
+#[test]
+fn invite_code_record_formats_window_and_status() {
+    let record = build_runtime_profile_invite_code_record(RuntimeProfileInviteCodeSnapshot {
+        user_id: "user-1".to_string(),
+        invite_code: "SY00000001".to_string(),
+        metadata_json: "{}".to_string(),
+        starts_at_micros: Some(0),
+        expires_at_micros: Some(1_000_000),
+        created_at_micros: 0,
+        updated_at_micros: 1_000_000,
+    });
+
+    assert_eq!(record.starts_at.as_deref(), Some("1970-01-01T00:00:00Z"));
+    assert_eq!(record.expires_at.as_deref(), Some("1970-01-01T00:00:01Z"));
+    assert_eq!(record.status, RuntimeProfileInviteCodeStatus::Expired);
+}