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/.hermes/plans/2026-05-04_032321-invite-code-validity-and-admin-confirmation.md
+++ b/.hermes/plans/2026-05-04_032321-invite-code-validity-and-admin-confirmation.md
@@ -0,0 +1,271 @@
+# 邀请码有效期与后台二次确认实施计划
+
+> **For Hermes:** 按 plan 模式，仅输出并保存实施计划，不直接改业务代码。
+
+**Goal:** 为邀请码新增开始日期与截止日期，并让后台所有会修改数据的操作在提交前增加二次确认，降低误操作风险。
+
+**Architecture:**
+邀请码仍作为“用户稳定邀请身份码”保留，不做停用删除；在数据层增加 `starts_at` / `expires_at`，前台填写邀请码时按时间窗校验，后台列表与编辑页展示状态。后台所有写操作统一先弹二次确认，再真正调用 API，避免对兑换码、邀请码、任务配置等管理动作误触发。
+
+**Tech Stack:**
+Rust / SpacetimeDB / Axum / shared-contracts / TS + React 的 admin-web。
+
+---
+
+## 当前上下文
+
+- 邀请码当前只有 `user_id`、`invite_code`、`metadata_json`、`created_at`、`updated_at`，没有状态字段。
+- 目前后台存在邀请码管理入口，但没有停用能力，也没有有效期概念。
+- 邀请码用于 `redeem_profile_referral_invite_code` 时的实时校验，适合增加“时间窗”而不是“禁用删除”。
+- 后台已存在兑换码、任务配置等可写操作；本次要求把所有后台操作统一加二次确认，包括新增、编辑、禁用、删除等写入口。
+
+---
+
+## 设计原则
+
+1. **邀请码不做软删除**：保留历史记录和邀请链路。
+2. **有效期由时间窗推导**：
+   - `starts_at` 为空表示立即生效。
+   - `expires_at` 为空表示长期有效。
+3. **前台只拒绝新绑定**：已绑定关系不回溯修改。
+4. **后台写操作统一确认**：所有会触发 POST / PATCH / DELETE 的管理动作，在真正提交前必须弹出二次确认。
+5. **尽量少改接口语义**：优先在现有 admin upsert/list 体系内扩展字段，而不是新增一套并行 API。
+
+---
+
+## 方案概要
+
+### 邀请码时间窗
+
+新增字段：
+- `starts_at: Option<Timestamp>`
+- `expires_at: Option<Timestamp>`
+
+校验规则：
+- 当前时间 `< starts_at`：返回“邀请码未生效”
+- 当前时间 `>= expires_at`：返回“邀请码已过期”
+- 其他情况允许填写
+
+建议把状态展示为：
+- 未生效
+- 有效
+- 已过期
+- 长期有效（两个字段都为空或仅无截止）
+
+### 后台二次确认
+
+对 admin-web 所有管理动作统一加确认弹窗/对话框，至少覆盖：
+- 兑换码新增/更新
+- 兑换码停用
+- 邀请码新增/更新
+- 任务配置新增/更新
+- 任务配置停用
+- 其他后续新增的后台写操作
+
+确认文案要求：
+- 显示对象标识（如 code / inviteCode / taskId）
+- 显示操作类型（新增 / 更新 / 停用）
+- 明确提醒“该操作会立即影响线上数据”
+- 允许取消返回，不调用 API
+
+---
+
+## 预期修改文件
+
+### 1. 服务端领域与契约
+- `server-rs/crates/spacetime-module/src/runtime/profile.rs`
+  - `ProfileInviteCode` 表结构新增开始/截止字段
+  - 邀请码 upsert 逻辑写入时间窗
+  - 邀请码 redeem 逻辑增加时间窗校验
+  - 邀请中心快照补充时间窗/状态
+- `server-rs/crates/spacetime-module/src/migration.rs`
+  - 兼容旧表数据，给旧邀请码补默认空值
+- `server-rs/crates/shared-contracts/src/runtime*.rs` 或对应生成/手写契约文件
+  - `AdminUpsertProfileInviteCodeRequest` 扩展字段
+  - `ProfileInviteCodeAdminResponse` 扩展字段
+  - 如需要，增加时间窗相关状态枚举或派生字段
+- `server-rs/crates/spacetime-client/src/module_bindings/*`
+  - 重新生成 bindings
+  - mapper 补齐新字段
+
+### 2. API Server
+- `server-rs/crates/api-server/src/runtime_profile.rs`
+  - 接收/转发邀请码时间窗参数
+  - 返回新增字段给后台
+  - 如需要，调整校验错误文案
+- `server-rs/crates/api-server/src/app.rs`
+  - 若有新路由或错误码需挂接，在此统一登记
+
+### 3. Admin Web
+- `apps/admin-web/src/api/adminApiTypes.ts`
+  - 增加邀请码时间窗字段
+  - 如有需要，增加后台操作请求结构字段
+- `apps/admin-web/src/api/adminApiClient.ts`
+  - 透传新的请求/响应字段
+- `apps/admin-web/src/app/adminRoutes.ts`
+  - 不一定需要改，但如果新增独立页面/子面板，需要在此登记
+- `apps/admin-web/src/styles/admin.css`
+  - 确认弹窗与时间窗展示样式
+- `apps/admin-web/src/**` 实际管理页面组件
+  - 邀请码编辑表单
+  - 邀请码列表状态展示
+  - 所有写操作前的二次确认弹窗
+
+### 4. 文档
+- `docs/technical/` 或 `docs/design/`
+  - 补一份邀请码时间窗与后台确认交互说明
+- 如现有文档已经覆盖后台管理规范，则优先补充现有文档，不重复造新说明页
+
+---
+
+## 分步实施计划
+
+### Task 1: 明确数据模型与契约扩展
+**Objective:** 定义邀请码开始/截止日期字段及其在响应中的展示方式。
+
+**要点：**
+- 确认字段名采用 `starts_at` / `expires_at`，避免与现有字段语义冲突。
+- 确认时间类型统一用 `Timestamp` / 毫秒微秒整数转换策略。
+- 明确返回给后台的字段是否需要附带派生状态（如 `status`）。
+
+**产出：**
+- 契约字段定义
+- 状态枚举/派生规则
+
+---
+
+### Task 2: 更新 SpacetimeDB 表与迁移
+**Objective:** 让邀请码表可保存有效期，并兼容旧数据。
+
+**要点：**
+- 修改 `ProfileInviteCode` 表结构。
+- 更新迁移逻辑，旧记录默认无开始/截止。
+- 检查是否需要补充索引或查询辅助字段。
+
+**验证：**
+- 旧数据能正常读取。
+- 新数据能写入开始/截止。
+
+---
+
+### Task 3: 实现邀请填写时的时间窗校验
+**Objective:** 在邀请码被填写时正确拒绝未生效或已过期的邀请码。
+
+**要点：**
+- 在 `redeem_profile_referral_invite_code_record` 内增加开始/截止校验。
+- 保持“自己的邀请码不能填”“邀请码不存在”等原有错误优先级清晰。
+- 保留历史绑定关系不受影响。
+
+**验证：**
+- 未到开始时间时返回明确错误。
+- 超过截止时间时返回明确错误。
+- 正常区间可绑定成功。
+
+---
+
+### Task 4: 扩展后台邀请码管理接口
+**Objective:** 让后台可以创建/修改邀请码时间窗，并在列表中查看状态。
+
+**要点：**
+- 扩展 `AdminUpsertProfileInviteCodeRequest`。
+- 扩展 `ProfileInviteCodeAdminResponse`。
+- `api-server` 接口负责接收新字段并转发。
+- 列表接口返回可读时间字段与状态。
+
+**验证：**
+- 后台表单提交后，返回结果包含时间窗信息。
+- 列表页能看到状态与时间。
+
+---
+
+### Task 5: 给后台所有写操作加二次确认
+**Objective:** 统一拦截所有后台写动作，避免误点直接生效。
+
+**覆盖范围建议：**
+- 邀请码新增/更新
+- 兑换码新增/更新/停用
+- 任务配置新增/更新/停用
+- 后续新增的管理写操作
+
+**实现要求：**
+- 在真正调用 API 之前弹出确认框。
+- 确认框需要展示对象名、操作类型、影响范围。
+- 取消后不发送请求。
+- 尽量抽象出通用确认组件/通用 action 包装函数，避免每个页面重复写。
+
+**验证：**
+- 点击“保存”不会直接提交，需先确认。
+- 点击“取消”不会发请求。
+- 所有后台写入口行为一致。
+
+---
+
+### Task 6: 补充文档与交互说明
+**Objective:** 把新规则写进项目文档，避免后续实现偏差。
+
+**要点：**
+- 记录邀请码时间窗语义。
+- 记录后台二次确认规范。
+- 说明哪些动作属于“必须确认”的写操作。
+
+---
+
+## 测试与验证
+
+### 服务端
+- 邀请码时间窗单测 / 集成测试
+- 邀请码 redeem 流程回归测试
+- 旧数据兼容测试
+
+### API / 前端
+- 管理后台列表展示正确
+- 表单提交能回传新字段
+- 二次确认取消后不请求接口
+- 二次确认确认后正常提交
+
+### 推荐验证命令
+- 视项目现有脚本执行对应后端测试
+- 前端按 admin-web 构建/测试脚本验证
+- 如涉及生成绑定，先确认生成产物无漏字段
+
+---
+
+## 风险与权衡
+
+1. **时间字段格式不统一**
+   - 风险：前后端对时间单位理解不一致。
+   - 处理：在契约层明确是 ISO 字符串还是微秒整数，并全链路统一。
+
+2. **后台“所有操作”范围过大**
+   - 风险：遗漏某些写入口。
+   - 处理：先枚举现有写 API，再做统一确认封装。
+
+3. **邀请码过期后历史链接解释成本**
+   - 风险：用户误以为历史邀请码失效影响已绑定关系。
+   - 处理：文案明确“仅影响新填写，不影响已绑定记录”。
+
+4. **契约与生成绑定联动较多**
+   - 风险：字段变更后生成文件数量较多。
+   - 处理：先改源契约与服务端，再统一重生成 bindings。
+
+---
+
+## 待确认问题
+
+1. `starts_at` / `expires_at` 在接口里要返回 **ISO 字符串** 还是 **微秒整数**？
+2. 后台二次确认是否统一用一个全局弹窗组件，还是页面级本地实现？
+3. 邀请码列表是否需要直接展示“状态标签”还是只展示时间字段由前端推导？
+4. 现有后台所有写操作里，是否还要覆盖调试类接口，还是仅覆盖业务管理接口？
+
+---
+
+## 建议执行顺序
+
+1. 先确认时间字段格式与确认弹窗范围。
+2. 再改服务端契约与迁移。
+3. 再改 redeem 校验与后台接口。
+4. 最后统一改 admin-web 的二次确认与表单展示。
+
+---
+
+**结论：** 这是一个适合分阶段落地的改动，建议先做“邀请码时间窗 + 后台统一二次确认”的基础能力，再补交互细节。
--- a/apps/admin-web/src/api/adminApiTypes.ts
+++ b/apps/admin-web/src/api/adminApiTypes.ts
@@ -122,6 +122,8 @@ export interface AdminUpsertProfileRedeemCodeRequest {
 export interface AdminUpsertProfileInviteCodeRequest {
  inviteCode: string;
  metadata?: Record<string, unknown>;
+  startsAt?: string | null;
+  expiresAt?: string | null;
 }

 export interface AdminDisableProfileRedeemCodeRequest {
@@ -166,6 +168,9 @@ export interface ProfileInviteCodeAdminResponse {
  userId: string;
  inviteCode: string;
  metadata: Record<string, unknown>;
+  startsAt?: string | null;
+  expiresAt?: string | null;
+  status: 'pending' | 'active' | 'expired';
  createdAt: string;
  updatedAt: string;
 }
--- a/apps/admin-web/src/components/useAdminWriteConfirm.tsx
+++ b/apps/admin-web/src/components/useAdminWriteConfirm.tsx
@@ -0,0 +1,105 @@
+import {useCallback, useEffect, useRef, useState} from 'react';
+
+interface AdminWriteConfirmOptions {
+  action: string;
+  target: string;
+}
+
+interface PendingConfirm extends AdminWriteConfirmOptions {
+  resolve: (confirmed: boolean) => void;
+}
+
+export function useAdminWriteConfirm() {
+  const [pendingConfirm, setPendingConfirm] = useState<PendingConfirm | null>(null);
+  const cancelButtonRef = useRef<HTMLButtonElement | null>(null);
+
+  const confirmWrite = useCallback((options: AdminWriteConfirmOptions) => {
+    return new Promise<boolean>((resolve) => {
+      setPendingConfirm((current) => {
+        if (current) {
+          current.resolve(false);
+        }
+        return {...options, resolve};
+      });
+    });
+  }, []);
+
+  const closeConfirm = useCallback(
+    (confirmed: boolean) => {
+      const current = pendingConfirm;
+      if (!current) {
+        return;
+      }
+      setPendingConfirm(null);
+      current.resolve(confirmed);
+    },
+    [pendingConfirm],
+  );
+
+  useEffect(() => {
+    if (!pendingConfirm) {
+      return;
+    }
+
+    cancelButtonRef.current?.focus();
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        closeConfirm(false);
+      }
+    };
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [closeConfirm, pendingConfirm]);
+
+  const confirmDialog = pendingConfirm ? (
+    <div
+      aria-modal="true"
+      aria-labelledby="admin-write-confirm-title"
+      className="admin-confirm-backdrop"
+      role="dialog"
+      onMouseDown={(event) => {
+        if (event.target === event.currentTarget) {
+          closeConfirm(false);
+        }
+      }}
+    >
+      <section className="admin-confirm-panel">
+        <div className="admin-panel-heading">
+          <h3 id="admin-write-confirm-title">确认操作</h3>
+          <span>{pendingConfirm.action}</span>
+        </div>
+        <dl className="admin-info-list">
+          <div>
+            <dt>操作</dt>
+            <dd>{pendingConfirm.action}</dd>
+          </div>
+          <div>
+            <dt>对象</dt>
+            <dd>{pendingConfirm.target}</dd>
+          </div>
+        </dl>
+        <div className="admin-confirm-warning">该操作会立即影响线上数据</div>
+        <div className="admin-confirm-actions">
+          <button
+            className="admin-secondary-button"
+            ref={cancelButtonRef}
+            type="button"
+            onClick={() => closeConfirm(false)}
+          >
+            取消
+          </button>
+          <button
+            className="admin-danger-button"
+            type="button"
+            onClick={() => closeConfirm(true)}
+          >
+            确认
+          </button>
+        </div>
+      </section>
+    </div>
+  ) : null;
+
+  return {confirmWrite, confirmDialog};
+}
--- a/apps/admin-web/src/pages/AdminDebugHttpPage.tsx
+++ b/apps/admin-web/src/pages/AdminDebugHttpPage.tsx
@@ -7,6 +7,7 @@ import type {
  AdminDebugHttpMethod,
  AdminDebugHttpResponse,
 } from '../api/adminApiTypes';
+import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm';
 import {formatUnknownJson, handlePageError} from './pageUtils';

 interface AdminDebugHttpPageProps {
@@ -33,6 +34,7 @@ export function AdminDebugHttpPage({
  const [result, setResult] = useState<AdminDebugHttpResponse | null>(null);
  const [errorMessage, setErrorMessage] = useState('');
  const [isSubmitting, setIsSubmitting] = useState(false);
+  const {confirmWrite, confirmDialog} = useAdminWriteConfirm();

  const jsonPreview = useMemo(
    () => formatUnknownJson(result?.bodyJson),
@@ -46,6 +48,16 @@ export function AdminDebugHttpPage({
    }

    setErrorMessage('');
+    if (method !== 'GET') {
+      const confirmed = await confirmWrite({
+        action: `${method} 调试请求`,
+        target: path.trim(),
+      });
+      if (!confirmed) {
+        return;
+      }
+    }
+
    setIsSubmitting(true);
    try {
      const response = await debugAdminHttp(token, {
@@ -209,6 +221,7 @@ export function AdminDebugHttpPage({
          )}
        </section>
      </div>
+      {confirmDialog}
    </section>
  );
 }
--- a/apps/admin-web/src/pages/AdminInviteCodePage.tsx
+++ b/apps/admin-web/src/pages/AdminInviteCodePage.tsx
@@ -5,7 +5,11 @@ import {
  listProfileInviteCodes,
  upsertProfileInviteCode,
 } from '../api/adminApiClient';
-import type {ProfileInviteCodeAdminResponse} from '../api/adminApiTypes';
+import type {
+  AdminUpsertProfileInviteCodeRequest,
+  ProfileInviteCodeAdminResponse,
+} from '../api/adminApiTypes';
+import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm';
 import {handlePageError} from './pageUtils';

 interface AdminInviteCodePageProps {
@@ -22,12 +26,15 @@ export function AdminInviteCodePage({
  onResultChange,
 }: AdminInviteCodePageProps) {
  const [inviteCode, setInviteCode] = useState('');
+  const [startsAt, setStartsAt] = useState('');
+  const [expiresAt, setExpiresAt] = useState('');
  const [metadataText, setMetadataText] = useState('{}');
  const [errorMessage, setErrorMessage] = useState('');
  const [listErrorMessage, setListErrorMessage] = useState('');
  const [entries, setEntries] = useState<ProfileInviteCodeAdminResponse[]>([]);
  const [isSaving, setIsSaving] = useState(false);
  const [isLoading, setIsLoading] = useState(false);
+  const {confirmWrite, confirmDialog} = useAdminWriteConfirm();

  useEffect(() => {
    void refreshInviteCodes();
@@ -54,12 +61,29 @@ export function AdminInviteCodePage({
    }

    setErrorMessage('');
+    const validityError = validateValidityWindow(startsAt, expiresAt);
+    if (validityError) {
+      setErrorMessage(validityError);
+      return;
+    }
+
+    const confirmed = await confirmWrite({
+      action: '保存邀请码',
+      target: inviteCode.trim(),
+    });
+    if (!confirmed) {
+      return;
+    }
+
    setIsSaving(true);
    try {
-      const response = await upsertProfileInviteCode(token, {
+      const payload: AdminUpsertProfileInviteCodeRequest = {
        inviteCode: inviteCode.trim(),
        metadata: parseMetadata(metadataText),
-      });
+        startsAt: startsAt ? toIsoDateTime(startsAt) : null,
+        expiresAt: expiresAt ? toIsoDateTime(expiresAt) : null,
+      };
+      const response = await upsertProfileInviteCode(token, payload);
      onResultChange(response);
      upsertEntry(response);
      fillForm(response);
@@ -89,9 +113,13 @@ export function AdminInviteCodePage({

  function fillForm(entry: ProfileInviteCodeAdminResponse) {
    setInviteCode(entry.inviteCode);
+    setStartsAt(toDateTimeLocalValue(entry.startsAt));
+    setExpiresAt(toDateTimeLocalValue(entry.expiresAt));
    setMetadataText(JSON.stringify(entry.metadata, null, 2));
  }

+  const validityError = validateValidityWindow(startsAt, expiresAt);
+
  return (
    <section className="admin-page">
      <div className="admin-page-heading">
@@ -127,6 +155,25 @@ export function AdminInviteCodePage({
            />
          </label>

+          <div className="admin-form-row">
+            <label className="admin-field">
+              <span>开始时间</span>
+              <input
+                type="datetime-local"
+                value={startsAt}
+                onChange={(event) => setStartsAt(event.target.value)}
+              />
+            </label>
+            <label className="admin-field">
+              <span>截止时间</span>
+              <input
+                type="datetime-local"
+                value={expiresAt}
+                onChange={(event) => setExpiresAt(event.target.value)}
+              />
+            </label>
+          </div>
+
          <label className="admin-field">
            <span>Metadata JSON</span>
            <textarea
@@ -142,10 +189,20 @@ export function AdminInviteCodePage({
              {errorMessage}
            </div>
          ) : null}
+          {validityError ? (
+            <div className="admin-alert" role="status">
+              {validityError}
+            </div>
+          ) : null}

          <button
            className="admin-primary-button"
-            disabled={isSaving || !inviteCode.trim() || !isMetadataReady(metadataText)}
+            disabled={
+              isSaving ||
+              !inviteCode.trim() ||
+              !isMetadataReady(metadataText) ||
+              Boolean(validityError)
+            }
            type="submit"
          >
            <Save size={17} aria-hidden="true" />
@@ -165,8 +222,8 @@ export function AdminInviteCodePage({
                  <thead>
                    <tr>
                      <th>邀请码</th>
+                      <th>有效期</th>
                      <th>创建</th>
-                      <th>更新</th>
                    </tr>
                  </thead>
                  <tbody>
@@ -181,8 +238,13 @@ export function AdminInviteCodePage({
                            {entry.inviteCode}
                          </button>
                        </td>
+                        <td>
+                          <span className={`admin-status ${inviteValidityClass(entry)}`}>
+                            {inviteValidityLabel(entry)}
+                          </span>
+                          <small>{formatValidityWindow(entry)}</small>
+                        </td>
                        <td>{entry.createdAt}</td>
-                        <td>{entry.updatedAt}</td>
                      </tr>
                    ))}
                  </tbody>
@@ -206,6 +268,10 @@ export function AdminInviteCodePage({
                  <dt>邀请码</dt>
                  <dd>{result.inviteCode}</dd>
                </div>
+                <div>
+                  <dt>有效期</dt>
+                  <dd>{formatValidityWindow(result)}</dd>
+                </div>
                <div>
                  <dt>创建</dt>
                  <dd>{result.createdAt}</dd>
@@ -229,6 +295,7 @@ export function AdminInviteCodePage({
          </section>
        </div>
      </div>
+      {confirmDialog}
    </section>
  );
 }
@@ -255,6 +322,84 @@ function isMetadataReady(value: string) {
  }
 }

+function validateValidityWindow(startsAt: string, expiresAt: string) {
+  if (!startsAt || !expiresAt) {
+    return '';
+  }
+
+  const startsAtTime = Date.parse(toIsoDateTime(startsAt));
+  const expiresAtTime = Date.parse(toIsoDateTime(expiresAt));
+  if (!Number.isFinite(startsAtTime) || !Number.isFinite(expiresAtTime)) {
+    return '有效期时间无效';
+  }
+
+  return startsAtTime < expiresAtTime ? '' : '截止时间必须晚于开始时间';
+}
+
+function toIsoDateTime(value: string) {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) {
+    throw new Error('有效期时间无效');
+  }
+  return new Date(time).toISOString();
+}
+
+function toDateTimeLocalValue(value?: string | null) {
+  if (!value) {
+    return '';
+  }
+
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) {
+    return '';
+  }
+
+  const offsetMs = date.getTimezoneOffset() * 60 * 1000;
+  return new Date(date.getTime() - offsetMs).toISOString().slice(0, 16);
+}
+
+function inviteValidityLabel(entry: ProfileInviteCodeAdminResponse) {
+  const now = Date.now();
+  const startsAtTime = entry.startsAt ? Date.parse(entry.startsAt) : null;
+  const expiresAtTime = entry.expiresAt ? Date.parse(entry.expiresAt) : null;
+
+  if (startsAtTime && Number.isFinite(startsAtTime) && now < startsAtTime) {
+    return '未生效';
+  }
+  if (expiresAtTime && Number.isFinite(expiresAtTime) && now >= expiresAtTime) {
+    return '已过期';
+  }
+  if (entry.startsAt || entry.expiresAt) {
+    return '有效';
+  }
+  return '长期有效';
+}
+
+function inviteValidityClass(entry: ProfileInviteCodeAdminResponse) {
+  const label = inviteValidityLabel(entry);
+  if (label === '已过期') {
+    return 'admin-status-error';
+  }
+  if (label === '未生效') {
+    return 'admin-status-pending';
+  }
+  return 'admin-status-ok';
+}
+
+function formatValidityWindow(entry: ProfileInviteCodeAdminResponse) {
+  const startsAt = entry.startsAt ? formatDateTime(entry.startsAt) : '立即';
+  const expiresAt = entry.expiresAt ? formatDateTime(entry.expiresAt) : '长期';
+  return `${startsAt} / ${expiresAt}`;
+}
+
+function formatDateTime(value: string) {
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) {
+    return value;
+  }
+  return date.toLocaleString('zh-CN', {hour12: false});
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
--- a/apps/admin-web/src/pages/AdminRedeemCodePage.tsx
+++ b/apps/admin-web/src/pages/AdminRedeemCodePage.tsx
@@ -10,6 +10,7 @@ import type {
  ProfileRedeemCodeAdminResponse,
  ProfileRedeemCodeMode,
 } from '../api/adminApiTypes';
+import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm';
 import {handlePageError, splitLines} from './pageUtils';

 interface AdminRedeemCodePageProps {
@@ -46,6 +47,7 @@ export function AdminRedeemCodePage({
  const [isSaving, setIsSaving] = useState(false);
  const [isDisabling, setIsDisabling] = useState(false);
  const [isLoading, setIsLoading] = useState(false);
+  const {confirmWrite, confirmDialog} = useAdminWriteConfirm();

  useEffect(() => {
    void refreshRedeemCodes();
@@ -72,6 +74,14 @@ export function AdminRedeemCodePage({
    }

    setErrorMessage('');
+    const confirmed = await confirmWrite({
+      action: '保存兑换码',
+      target: code.trim(),
+    });
+    if (!confirmed) {
+      return;
+    }
+
    setIsSaving(true);
    try {
      const response = await upsertProfileRedeemCode(token, {
@@ -101,6 +111,14 @@ export function AdminRedeemCodePage({
    }

    setDisableErrorMessage('');
+    const confirmed = await confirmWrite({
+      action: '停用兑换码',
+      target: disableCode.trim(),
+    });
+    if (!confirmed) {
+      return;
+    }
+
    setIsDisabling(true);
    try {
      const response = await disableProfileRedeemCode(token, {
@@ -376,6 +394,7 @@ export function AdminRedeemCodePage({
          </section>
        </div>
      </div>
+      {confirmDialog}
    </section>
  );
 }
--- a/apps/admin-web/src/pages/AdminTaskConfigPage.tsx
+++ b/apps/admin-web/src/pages/AdminTaskConfigPage.tsx
@@ -11,6 +11,7 @@ import type {
  ProfileTaskCycle,
  TrackingScopeKind,
 } from '../api/adminApiTypes';
+import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm';
 import {
  filterAdminTrackingEventDefinitions,
  findAdminTrackingEventDefinition,
@@ -28,12 +29,7 @@ const taskCycles: Array<{value: ProfileTaskCycle; label: string}> = [
  {value: 'daily', label: '每日'},
 ];

-const scopeKinds: Array<{value: TrackingScopeKind; label: string}> = [
-  {value: 'user', label: '用户'},
-  {value: 'site', label: '整站'},
-  {value: 'work', label: '作品'},
-  {value: 'module', label: '模块'},
-];
+const profileTaskScopeKind = 'user' satisfies TrackingScopeKind;

 export function AdminTaskConfigPage({
  token,
@@ -49,7 +45,6 @@ export function AdminTaskConfigPage({
  const [eventKeySearch, setEventKeySearch] = useState('每日登录');
  const [isEventKeyPickerOpen, setIsEventKeyPickerOpen] = useState(false);
  const [cycle, setCycle] = useState<ProfileTaskCycle>('daily');
-  const [scopeKind, setScopeKind] = useState<TrackingScopeKind>('user');
  const [threshold, setThreshold] = useState('1');
  const [rewardPoints, setRewardPoints] = useState('10');
  const [sortOrder, setSortOrder] = useState('10');
@@ -61,6 +56,7 @@ export function AdminTaskConfigPage({
  const [isSaving, setIsSaving] = useState(false);
  const [isDisabling, setIsDisabling] = useState(false);
  const [isLoading, setIsLoading] = useState(false);
+  const {confirmWrite, confirmDialog} = useAdminWriteConfirm();

  useEffect(() => {
    void refreshTaskConfigs();
@@ -102,6 +98,14 @@ export function AdminTaskConfigPage({
    }

    setErrorMessage('');
+    const confirmed = await confirmWrite({
+      action: '保存任务配置',
+      target: taskId.trim(),
+    });
+    if (!confirmed) {
+      return;
+    }
+
    setIsSaving(true);
    try {
      const response = await upsertProfileTaskConfig(token, {
@@ -110,7 +114,7 @@ export function AdminTaskConfigPage({
        description,
        eventKey: eventKey.trim(),
        cycle,
-        scopeKind,
+        scopeKind: profileTaskScopeKind,
        threshold: parsePositiveInteger(threshold),
        rewardPoints: parsePositiveInteger(rewardPoints),
        enabled,
@@ -132,6 +136,14 @@ export function AdminTaskConfigPage({
    }

    setDisableErrorMessage('');
+    const confirmed = await confirmWrite({
+      action: '停用任务配置',
+      target: disableTaskId.trim(),
+    });
+    if (!confirmed) {
+      return;
+    }
+
    setIsDisabling(true);
    try {
      const response = await disableProfileTaskConfig(token, {
@@ -165,7 +177,6 @@ export function AdminTaskConfigPage({
    setDescription(entry.description);
    setEventKey(entry.eventKey);
    setCycle(entry.cycle);
-    setScopeKind(entry.scopeKind);
    setThreshold(String(entry.threshold));
    setRewardPoints(String(entry.rewardPoints));
    setSortOrder(String(entry.sortOrder));
@@ -181,7 +192,6 @@ export function AdminTaskConfigPage({
    setEventKey(nextEventKey);
    if (nextDefinition) {
      setEventKeySearch(nextDefinition.title);
-      setScopeKind(nextDefinition.scopeKind);
    } else {
      setEventKeySearch(nextEventKey);
    }
@@ -349,21 +359,6 @@ export function AdminTaskConfigPage({
                ))}
              </select>
            </label>
-            <label className="admin-field">
-              <span>埋点范围</span>
-              <select
-                value={scopeKind}
-                onChange={(event) =>
-                  setScopeKind(event.target.value as TrackingScopeKind)
-                }
-              >
-                {scopeKinds.map((item) => (
-                  <option key={item.value} value={item.value}>
-                    {item.label}
-                  </option>
-                ))}
-              </select>
-            </label>
          </div>

          <div className="admin-form-row">
@@ -530,6 +525,7 @@ export function AdminTaskConfigPage({
          </section>
        </div>
      </div>
+      {confirmDialog}
    </section>
  );
 }
--- a/apps/admin-web/src/styles/admin.css
+++ b/apps/admin-web/src/styles/admin.css
@@ -457,6 +457,47 @@ button:disabled {
  font-weight: 700;
 }

+.admin-confirm-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 80;
+  display: grid;
+  place-items: center;
+  background: rgba(23, 33, 43, 0.42);
+  padding: 16px;
+}
+
+.admin-confirm-panel {
+  display: grid;
+  width: min(100%, 420px);
+  gap: 16px;
+  border: 1px solid #d8e2e8;
+  border-radius: 10px;
+  background: #ffffff;
+  box-shadow: 0 22px 60px rgba(23, 33, 43, 0.24);
+  padding: 18px;
+}
+
+.admin-confirm-warning {
+  border: 1px solid #efc894;
+  border-radius: 8px;
+  color: #8a5a1b;
+  background: #fffaf3;
+  padding: 10px 12px;
+  font-size: 13px;
+  font-weight: 650;
+}
+
+.admin-confirm-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+}
+
+.admin-confirm-actions button {
+  min-width: 92px;
+}
+
 .admin-primary-button {
  color: #ffffff;
  background: #126e82;
@@ -575,6 +616,11 @@ button:disabled {
  background: #e6f5ed;
 }

+.admin-status-pending {
+  color: #8a5a1b;
+  background: #fff4df;
+}
+
 .admin-status-error {
  color: #8a2f2f;
  background: #fff1ef;
@@ -755,6 +801,14 @@ button:disabled {
    padding: 16px;
  }

+  .admin-confirm-panel {
+    padding: 16px;
+  }
+
+  .admin-confirm-actions {
+    display: grid;
+  }
+
  .admin-login-brand h1,
  .admin-page-heading h2 {
    font-size: 22px;
--- a/docs/technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md
+++ b/docs/technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md
@@ -192,6 +192,8 @@ export interface AdminDisableProfileRedeemCodeRequest {

 export interface AdminUpsertProfileInviteCodeRequest {
  inviteCode: string;
+  startsAt?: string | null;
+  expiresAt?: string | null;
  metadata?: Record<string, unknown>;
 }

@@ -215,6 +217,9 @@ export interface ProfileRedeemCodeAdminListResponse {
 export interface ProfileInviteCodeAdminResponse {
  userId: string;
  inviteCode: string;
+  startsAt: string | null;
+  expiresAt: string | null;
+  status: 'pending' | 'active' | 'expired';
  metadata: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
@@ -376,6 +381,9 @@ export interface ProfileInviteCodeAdminListResponse {
    {
      "userId": "admin:root:SPRING2026",
      "inviteCode": "SPRING2026",
+      "startsAt": "2026-05-01T00:00:00Z",
+      "expiresAt": "2026-06-01T00:00:00Z",
+      "status": "active",
      "metadata": {
        "batch": "spring"
      },
@@ -393,6 +401,8 @@ export interface ProfileInviteCodeAdminListResponse {
 ```json
 {
  "inviteCode": "SPRING2026",
+  "startsAt": "2026-05-01T00:00:00Z",
+  "expiresAt": "2026-06-01T00:00:00Z",
  "metadata": {
    "batch": "spring"
  }
@@ -405,6 +415,9 @@ export interface ProfileInviteCodeAdminListResponse {
 {
  "userId": "admin",
  "inviteCode": "SPRING2026",
+  "startsAt": "2026-05-01T00:00:00Z",
+  "expiresAt": "2026-06-01T00:00:00Z",
+  "status": "active",
  "metadata": {
    "batch": "spring"
  },
@@ -415,6 +428,118 @@ export interface ProfileInviteCodeAdminListResponse {

 邀请码页的 metadata 输入必须先在前端解析为 JSON 对象；空字符串按 `{}` 处理，数组、字符串、数字等非对象值直接提示错误。最终标准化、长度限制和邀请码合法性以 `server-rs` 为准。

+#### 4.8.1 邀请码有效期语义
+
+邀请码仍然是“用户稳定邀请身份码”，不做删除或软删除。本轮只增加时间窗字段，用于控制**新填写邀请码**是否允许绑定：
+
+1. `startsAt` / 后端 `starts_at`：邀请码开始生效时间；为空表示立即生效。
+2. `expiresAt` / 后端 `expires_at`：邀请码截止时间；为空表示长期有效。
+3. 两个字段都为空时，邀请码视为长期有效。
+4. `expiresAt` 采用左闭右开语义：当前时间 `>= expiresAt` 时视为已过期。
+5. 时间字段在管理 API JSON 中统一使用 ISO 8601 UTC 字符串或 `null`；SpacetimeDB 内部仍按 `Timestamp` 存储，契约层负责转换，前端不得自行假设微秒/毫秒整数。
+6. 有效期只影响用户之后调用填写邀请码接口建立新邀请关系；已绑定的邀请关系、历史奖励、统计和审计记录不回溯修改。
+
+字段合法性要求：
+
+1. `startsAt` 和 `expiresAt` 均允许为空。
+2. 若两者都存在，必须满足 `startsAt < expiresAt`；相等或开始晚于截止应由后端拒绝，前端可提前提示但不能替代后端校验。
+3. 后台编辑已有邀请码时，空值代表清空该边界；不要用空字符串写入契约。
+
+#### 4.8.2 用户填写邀请码的错误优先级与校验逻辑
+
+填写邀请码时，后端是唯一业务真相。前端只展示后端错误，不复制完整业务规则。推荐校验优先级如下：
+
+1. **请求身份与输入基础校验**：未登录、空邀请码、格式不合法等请求级错误优先返回。
+2. **用户自身状态校验**：用户不存在、用户资料不可用、已绑定过邀请关系等与当前用户直接相关的错误优先于邀请码时间窗。
+3. **邀请码查找**：按标准化后的邀请码查找记录；不存在时返回“邀请码不存在或不可用”。
+4. **自邀请校验**：邀请码归属用户等于当前用户时，返回“不能填写自己的邀请码”。
+5. **时间窗校验**：
+   - `starts_at` 存在且当前时间 `< starts_at`，返回“邀请码未生效”。
+   - `expires_at` 存在且当前时间 `>= expires_at`，返回“邀请码已过期”。
+6. **绑定写入与奖励发放**：只有以上校验全部通过，才写入邀请绑定、奖励或相关流水。
+
+该顺序的目标是避免用“未生效/已过期”泄露不该暴露的用户状态，同时保证用户看到的错误与实际阻断原因一致。若后续新增风控、封禁、黑名单等规则，应在写入前补入，并在本节同步明确优先级。
+
+#### 4.8.3 后台邀请码列表状态展示规则
+
+后台列表状态可由后端返回 `status`，也可在前端用同一规则从 `startsAt` / `expiresAt` 派生；如果两者同时存在，列表展示以后端 `status` 为准，并仅把前端派生结果用于兜底。
+
+| 条件 | 状态值 | 中文标签 | 展示建议 |
+| --- | --- | --- | --- |
+| `startsAt` 存在且当前时间 `< startsAt` | `pending` | 未生效 | 展示开始时间，提示尚不能被新用户填写 |
+| `expiresAt` 存在且当前时间 `>= expiresAt` | `expired` | 已过期 | 展示截止时间，提示不再允许新绑定 |
+| 其他情况 | `active` | 有效 | 正常高亮展示 |
+
+补充展示规则：
+
+1. 两个字段都为空时状态为 `active`，中文可展示为“长期有效”。
+2. `startsAt` 为空、`expiresAt` 未来存在时状态为 `active`，中文可展示为“有效至 YYYY-MM-DD HH:mm”。
+3. `startsAt` 未来、`expiresAt` 为空时状态为 `pending`，中文可展示为“YYYY-MM-DD HH:mm 生效”。
+4. 列表至少展示邀请码、状态、开始时间、截止时间、更新时间；metadata 可保留折叠/摘要展示，避免挤占移动端宽度。
+5. 列表状态只用于运营理解，不作为安全边界；真正是否可填写仍以后端 redeem 校验为准。
+
+### 4.9 后台写操作二次确认规范
+
+后台所有会修改线上数据的操作，在真正调用 API 前必须二次确认；取消确认时不得发送任何请求。该规范覆盖当前和未来新增的管理写入口，不限于 profile 模块。
+
+必须二次确认的操作包括但不限于：
+
+1. 创建/更新兑换码：`POST /admin/api/profile/redeem-codes`。
+2. 停用兑换码：`POST /admin/api/profile/redeem-codes/disable`。
+3. 创建/更新邀请码：`POST /admin/api/profile/invite-codes`。
+4. 创建/更新个人任务配置：`POST /admin/api/profile/tasks`。
+5. 停用个人任务配置：`POST /admin/api/profile/tasks/disable`。
+6. 后续任何 `POST` / `PATCH` / `PUT` / `DELETE` 管理接口，只要会修改数据、触发任务、写审计或影响线上配置，均默认纳入确认。
+
+交互要求：
+
+1. 确认弹窗必须在 API 调用前出现，确认后才进入 loading 和提交状态。
+2. 弹窗必须展示操作类型（新增、更新、停用、删除、发布等）、对象标识（如 `code`、`inviteCode`、`taskId`）和影响说明。
+3. 默认按钮顺序为“取消 / 确认”，取消不应有危险色；危险操作（停用、删除、覆盖线上配置）确认按钮使用警示样式。
+4. 弹窗文案统一提示“该操作会立即影响线上数据”，但不要在页面常驻展示大段规则说明。
+5. 支持键盘和移动端：Esc 或取消按钮关闭；移动端弹窗宽度自适应，不遮挡关键对象信息。
+6. loading 期间锁定确认按钮和原页面提交按钮，避免重复写入。
+7. 成功后按现有页面规则刷新列表或合并返回记录；失败时展示后端错误，不能静默关闭为成功。
+
+建议抽象通用确认能力，例如 `confirmAdminWriteAction({ actionLabel, targetLabel, riskLevel, onConfirm })` 或通用 `AdminConfirmDialog`，页面只传入对象与回调，避免每个页面重复实现不同交互。
+
+#### 4.9.1 二次确认文案模板
+
+```text
+标题：确认{操作类型}{对象类型}
+正文：即将{操作类型}「{对象标识}」。该操作会立即影响线上数据。
+取消按钮：取消
+确认按钮：确认{操作类型}
+```
+
+示例：
+
+1. `确认更新邀请码`：即将更新「SPRING2026」的有效期与 metadata。该操作会立即影响线上数据。
+2. `确认停用兑换码`：即将停用「WELCOME2026」。该操作会立即影响线上数据。
+3. `确认更新任务配置`：即将更新「daily_login」。该操作会立即影响线上数据。
+
+### 4.10 邀请码有效期与二次确认改动范围
+
+实现本设计时预期改动范围如下，未列出的层级不要擅自承接业务规则：
+
+1. `server-rs/crates/spacetime-module/src/runtime/profile.rs`：邀请码表结构、upsert、redeem 时间窗校验与后台列表投影。
+2. `server-rs/crates/spacetime-module/src/migration.rs`：旧邀请码记录迁移，默认 `starts_at = None`、`expires_at = None`。
+3. `server-rs/crates/shared-contracts/src/**`：管理请求/响应 DTO 增加 `startsAt`、`expiresAt`、`status` 等字段。
+4. `server-rs/crates/spacetime-client/src/module_bindings/**` 与 mapper：按表结构变更重新生成/补齐绑定字段。
+5. `server-rs/crates/api-server/src/runtime_profile.rs`：接收、校验、转发并返回邀请码时间窗字段；保持错误 envelope 兼容后台读取逻辑。
+6. `apps/admin-web/src/api/adminApiTypes.ts` 与 `adminApiClient.ts`：同步契约字段，不在 client 层写业务判断。
+7. `apps/admin-web/src/pages/AdminInviteCodePage.tsx`：有效期表单、列表状态展示、保存前确认。
+8. `apps/admin-web/src/pages/AdminRedeemCodePage.tsx`、`AdminTaskConfigPage.tsx` 及后续写页面：统一接入写操作二次确认。
+9. `apps/admin-web/src/styles/admin.css`：状态标签、确认弹窗与移动端样式。
+
+验证建议：
+
+1. 服务端单测覆盖：未生效邀请码拒绝、已过期邀请码拒绝、有效时间窗可绑定、空时间窗长期有效、已绑定关系不受后续过期影响。
+2. 管理 API 覆盖：upsert 能写入/清空 `startsAt`、`expiresAt`；列表返回状态正确；`startsAt >= expiresAt` 被拒绝。
+3. 前端交互覆盖：点击保存/停用不会直接请求，取消确认不请求，确认后只请求一次，失败展示后端错误。
+4. 回归兑换码与任务配置页面，确认所有写操作均有统一二次确认。
+5. 修改后端时按项目约束运行对应 Rust 测试、`npm run api-server` 联调和 `/healthz`；修改前端时运行 `npm run admin-web:typecheck`、`npm run admin-web:build`；文档或中文改动后运行 `npm run check:encoding`。
+
 ## 5. 鉴权与会话

 1. token key 固定为 `genarrative_admin_token`。
--- a/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+++ b/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
@@ -24,7 +24,7 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
 | --- | --- |
 | 运维迁移 | `database_migration_operator`, `database_migration_import_chunk` |
 | 认证 | `auth_store_snapshot`, `user_account`, `auth_identity`, `refresh_session` |
-| 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `tracking_event`, `tracking_daily_stat`, `profile_task_config`, `profile_task_progress`, `profile_task_reward_claim`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_invite_code`, `profile_referral_relation`, `profile_played_world`, `profile_membership`, `profile_recharge_order`, `profile_save_archive` |
+| 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `analytics_date_dimension`, `tracking_event`, `tracking_daily_stat`, `profile_task_config`, `profile_task_progress`, `profile_task_reward_claim`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_invite_code`, `profile_referral_relation`, `profile_played_world`, `profile_membership`, `profile_recharge_order`, `profile_save_archive` |
 | RPG 运行时 | `story_session`, `story_event`, `npc_state`, `inventory_slot`, `battle_state`, `treasure_record`, `quest_record`, `quest_log`, `player_progression`, `chapter_progression` |
 | 世界创作 | `custom_world_profile`, `custom_world_session`, `custom_world_agent_session`, `custom_world_agent_message`, `custom_world_agent_operation`, `custom_world_draft_card`, `custom_world_gallery_entry` |
 | 拼图 | `puzzle_agent_session`, `puzzle_agent_message`, `puzzle_work_profile`, `puzzle_event`, `puzzle_runtime_run`, `puzzle_leaderboard_entry` |
@@ -158,6 +158,20 @@ SELECT * FROM profile_wallet_ledger WHERE user_id = '<user_id>';
 SELECT * FROM profile_wallet_ledger WHERE user_id = '<user_id>' ORDER BY created_at DESC;
 ```

+### `analytics_date_dimension`
+
+- 作用：分析日期维表，每个北京时间业务自然日一行，用于把日桶映射到周、月、季度和年。
+- 结构：`date_key PK: i64`, `calendar_date: String`, `weekday: u8`, `iso_week_key: i32`, `week_start_date_key: i64`, `week_end_date_key: i64`, `month_key: i32`, `month_start_date_key: i64`, `month_end_date_key: i64`, `quarter_key: i32`, `quarter_start_date_key: i64`, `quarter_end_date_key: i64`, `year_key: i32`, `year_start_date_key: i64`, `year_end_date_key: i64`, `created_at: Timestamp`, `updated_at: Timestamp`。
+- 索引：主键 `date_key`，`iso_week_key`，`month_key`，`quarter_key`，`year_key`。
+- 写入口：`ensure_analytics_date_dimension_for_date({ date_key })` 幂等补单日；`seed_analytics_date_dimensions({ start_date, end_date })` 按 `YYYY-MM-DD` 闭区间幂等批量补种，单次最多 `3660` 天。
+- 口径：`date_key` 沿用当前埋点日桶 `floor((occurred_at_micros + 8h) / 1d)`，`calendar_date` 是该北京时间业务日的公历日期。
+
+```sql
+SELECT * FROM analytics_date_dimension WHERE date_key = <date_key>;
+SELECT * FROM analytics_date_dimension WHERE iso_week_key = 202501 ORDER BY date_key;
+SELECT * FROM analytics_date_dimension WHERE month_key = 202402 ORDER BY date_key;
+```
+
 ### `tracking_event`

 - 作用：埋点原始事件表，保存整站、作品、模块和用户层的原始事实。
--- a/server-rs/crates/api-server/src/runtime_profile.rs
+++ b/server-rs/crates/api-server/src/runtime_profile.rs
@@ -44,6 +44,7 @@ use shared_contracts::runtime::{
    RedeemProfileRewardCodeRequest, RedeemProfileRewardCodeResponse, TRACKING_SCOPE_KIND_MODULE,
    TRACKING_SCOPE_KIND_SITE, TRACKING_SCOPE_KIND_USER, TRACKING_SCOPE_KIND_WORK,
 };
+use shared_kernel::{offset_datetime_to_unix_micros, parse_rfc3339};
 use spacetime_client::SpacetimeClientError;
 use time::OffsetDateTime;

@@ -369,6 +370,14 @@ pub async fn admin_upsert_profile_task_config(
            AppError::from_status(StatusCode::BAD_REQUEST).with_message(error),
        )
    })?;
+    // 中文注释：个人任务配置首版只开放 User scope，HTTP 层先返回清晰错误，领域层再兜底。
+    if scope_kind != RuntimeTrackingScopeKind::User {
+        return Err(runtime_profile_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST)
+                .with_message("个人任务 scopeKind 首版仅支持 user"),
+        ));
+    }
    let updated_at_micros = OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000;
    let record = state
        .spacetime_client()
@@ -558,6 +567,10 @@ pub async fn admin_upsert_profile_invite_code(
 ) -> Result<Json<Value>, Response> {
    let metadata_json = normalize_admin_invite_code_metadata(payload.metadata)
        .map_err(|error| runtime_profile_error_response(&request_context, error))?;
+    let starts_at_micros = parse_admin_invite_code_time_field("startsAt", payload.starts_at)
+        .map_err(|error| runtime_profile_error_response(&request_context, error))?;
+    let expires_at_micros = parse_admin_invite_code_time_field("expiresAt", payload.expires_at)
+        .map_err(|error| runtime_profile_error_response(&request_context, error))?;
    let updated_at_micros = OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000;
    let record = state
        .spacetime_client()
@@ -565,6 +578,8 @@ pub async fn admin_upsert_profile_invite_code(
            admin.session().username.clone(),
            payload.invite_code,
            metadata_json,
+            starts_at_micros,
+            expires_at_micros,
            updated_at_micros as i64,
        )
        .await
@@ -873,6 +888,27 @@ fn normalize_admin_invite_code_metadata(metadata: Option<Value>) -> Result<Strin
    Ok(metadata_json)
 }

+fn parse_admin_invite_code_time_field(
+    field: &'static str,
+    value: Option<String>,
+) -> Result<Option<i64>, AppError> {
+    let Some(value) = value else {
+        return Ok(None);
+    };
+    let value = value.trim();
+    if value.is_empty() {
+        return Ok(None);
+    }
+
+    let parsed = parse_rfc3339(value).map_err(|error| {
+        AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_message(format!("邀请码 {field} 必须是 RFC3339 时间字符串"))
+            .with_details(json!({ "field": field, "message": error }))
+    })?;
+
+    Ok(Some(offset_datetime_to_unix_micros(parsed)))
+}
+
 fn parse_profile_redeem_code_mode(raw: &str) -> Result<RuntimeProfileRedeemCodeMode, String> {
    match raw.trim().to_ascii_lowercase().as_str() {
        "public" => Ok(RuntimeProfileRedeemCodeMode::Public),
@@ -932,6 +968,9 @@ fn build_profile_invite_code_admin_response(
        user_id: record.user_id,
        invite_code: record.invite_code,
        metadata,
+        starts_at: record.starts_at,
+        expires_at: record.expires_at,
+        status: record.status.as_str().to_string(),
        created_at: record.created_at,
        updated_at: record.updated_at,
    }
@@ -1256,9 +1295,8 @@ mod tests {

    #[tokio::test]
    async fn admin_profile_task_routes_require_admin_authentication() {
-        let app = build_router(
-            AppState::new(admin_enabled_test_config()).expect("state should build"),
-        );
+        let app =
+            build_router(AppState::new(admin_enabled_test_config()).expect("state should build"));

        let list_response = app
            .clone()
@@ -1302,9 +1340,8 @@ mod tests {

    #[tokio::test]
    async fn admin_profile_code_list_routes_require_admin_authentication() {
-        let app = build_router(
-            AppState::new(admin_enabled_test_config()).expect("state should build"),
-        );
+        let app =
+            build_router(AppState::new(admin_enabled_test_config()).expect("state should build"));

        for uri in [
            "/admin/api/profile/redeem-codes",
--- 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);
+}
--- a/server-rs/crates/shared-contracts/src/runtime.rs
+++ b/server-rs/crates/shared-contracts/src/runtime.rs
@@ -412,6 +412,10 @@ pub struct AdminUpsertProfileInviteCodeRequest {
    pub invite_code: String,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
+    #[serde(default)]
+    pub starts_at: Option<String>,
+    #[serde(default)]
+    pub expires_at: Option<String>,
 }

 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -447,6 +451,9 @@ pub struct ProfileInviteCodeAdminResponse {
    pub user_id: String,
    pub invite_code: String,
    pub metadata: serde_json::Value,
+    pub starts_at: Option<String>,
+    pub expires_at: Option<String>,
+    pub status: String,
    pub created_at: String,
    pub updated_at: String,
 }
--- a/server-rs/crates/shared-contracts/tests/invite_code_contract.rs
+++ b/server-rs/crates/shared-contracts/tests/invite_code_contract.rs
@@ -0,0 +1,37 @@
+use serde_json::json;
+use shared_contracts::runtime::{
+    AdminUpsertProfileInviteCodeRequest, ProfileInviteCodeAdminResponse,
+};
+
+#[test]
+fn admin_upsert_invite_code_request_accepts_optional_validity_window() {
+    let request: AdminUpsertProfileInviteCodeRequest = serde_json::from_value(json!({
+        "inviteCode": "SY00000001",
+        "metadata": { "note": "测试" },
+        "startsAt": "2026-05-04T00:00:00Z",
+        "expiresAt": null
+    }))
+    .expect("邀请码管理请求应接受 startsAt/expiresAt");
+
+    assert_eq!(request.starts_at.as_deref(), Some("2026-05-04T00:00:00Z"));
+    assert_eq!(request.expires_at, None);
+}
+
+#[test]
+fn admin_invite_code_response_serializes_window_and_status_as_camel_case() {
+    let response = ProfileInviteCodeAdminResponse {
+        user_id: "user-1".to_string(),
+        invite_code: "SY00000001".to_string(),
+        metadata: json!({}),
+        starts_at: Some("2026-05-04T00:00:00Z".to_string()),
+        expires_at: None,
+        status: "active".to_string(),
+        created_at: "2026-05-04T00:00:00Z".to_string(),
+        updated_at: "2026-05-04T00:00:00Z".to_string(),
+    };
+
+    let value = serde_json::to_value(response).expect("邀请码管理响应应可序列化");
+    assert_eq!(value["startsAt"], json!("2026-05-04T00:00:00Z"));
+    assert_eq!(value["expiresAt"], json!(null));
+    assert_eq!(value["status"], json!("active"));
+}
--- a/server-rs/crates/spacetime-client/src/mapper.rs
+++ b/server-rs/crates/spacetime-client/src/mapper.rs
@@ -281,6 +281,8 @@ impl From<module_runtime::RuntimeProfileInviteCodeAdminUpsertInput>
            admin_user_id: input.admin_user_id,
            invite_code: input.invite_code,
            metadata_json: input.metadata_json,
+            starts_at_micros: input.starts_at_micros,
+            expires_at_micros: input.expires_at_micros,
            updated_at_micros: input.updated_at_micros,
        }
    }
@@ -1997,6 +1999,8 @@ pub(crate) fn map_runtime_profile_invite_code_snapshot(
        user_id: snapshot.user_id,
        invite_code: snapshot.invite_code,
        metadata_json: snapshot.metadata_json,
+        starts_at_micros: snapshot.starts_at_micros,
+        expires_at_micros: snapshot.expires_at_micros,
        created_at_micros: snapshot.created_at_micros,
        updated_at_micros: snapshot.updated_at_micros,
    }
--- a/server-rs/crates/spacetime-client/src/module_bindings/profile_invite_code_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/profile_invite_code_type.rs
@@ -12,6 +12,8 @@ pub struct ProfileInviteCode {
    pub metadata_json: String,
    pub created_at: __sdk::Timestamp,
    pub updated_at: __sdk::Timestamp,
+    pub starts_at: Option<__sdk::Timestamp>,
+    pub expires_at: Option<__sdk::Timestamp>,
 }

 impl __sdk::InModule for ProfileInviteCode {
@@ -27,6 +29,8 @@ pub struct ProfileInviteCodeCols {
    pub metadata_json: __sdk::__query_builder::Col<ProfileInviteCode, String>,
    pub created_at: __sdk::__query_builder::Col<ProfileInviteCode, __sdk::Timestamp>,
    pub updated_at: __sdk::__query_builder::Col<ProfileInviteCode, __sdk::Timestamp>,
+    pub starts_at: __sdk::__query_builder::Col<ProfileInviteCode, Option<__sdk::Timestamp>>,
+    pub expires_at: __sdk::__query_builder::Col<ProfileInviteCode, Option<__sdk::Timestamp>>,
 }

 impl __sdk::__query_builder::HasCols for ProfileInviteCode {
@@ -38,6 +42,8 @@ impl __sdk::__query_builder::HasCols for ProfileInviteCode {
            metadata_json: __sdk::__query_builder::Col::new(table_name, "metadata_json"),
            created_at: __sdk::__query_builder::Col::new(table_name, "created_at"),
            updated_at: __sdk::__query_builder::Col::new(table_name, "updated_at"),
+            starts_at: __sdk::__query_builder::Col::new(table_name, "starts_at"),
+            expires_at: __sdk::__query_builder::Col::new(table_name, "expires_at"),
        }
    }
 }
--- a/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_admin_upsert_input_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_admin_upsert_input_type.rs
@@ -10,6 +10,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,
 }

--- a/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_snapshot_type.rs
+++ b/server-rs/crates/spacetime-client/src/module_bindings/runtime_profile_invite_code_snapshot_type.rs
@@ -10,6 +10,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,
 }
--- a/server-rs/crates/spacetime-client/src/runtime.rs
+++ b/server-rs/crates/spacetime-client/src/runtime.rs
@@ -533,12 +533,16 @@ impl SpacetimeClient {
        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<RuntimeProfileInviteCodeRecord, SpacetimeClientError> {
        let procedure_input = build_runtime_profile_invite_code_admin_upsert_input(
            admin_user_id,
            invite_code,
            metadata_json,
+            starts_at_micros,
+            expires_at_micros,
            updated_at_micros,
        )
        .map_err(|error| SpacetimeClientError::Runtime(error.to_string()))?
--- a/server-rs/crates/spacetime-module/src/migration.rs
+++ b/server-rs/crates/spacetime-module/src/migration.rs
@@ -1,3 +1,4 @@
+use crate::runtime::analytics_date_dimension::analytics_date_dimension;
 use crate::*;
 use serde::{Deserialize, Serialize};
 use spacetimedb_lib::sats::de::serde::DeserializeWrapper;
@@ -161,6 +162,7 @@ macro_rules! migration_tables {
            user_browse_history,
            profile_dashboard_state,
            profile_wallet_ledger,
+            analytics_date_dimension,
            tracking_event,
            tracking_daily_stat,
            profile_task_config,
--- a/server-rs/crates/spacetime-module/src/runtime/mod.rs
+++ b/server-rs/crates/spacetime-module/src/runtime/mod.rs
@@ -1,8 +1,10 @@
+pub mod analytics_date_dimension;
 mod browse_history;
 mod profile;
 mod settings;
 mod snapshots;

+pub use analytics_date_dimension::*;
 pub use browse_history::*;
 pub use profile::*;
 pub use settings::*;
--- a/server-rs/crates/spacetime-module/src/runtime/profile.rs
+++ b/server-rs/crates/spacetime-module/src/runtime/profile.rs
@@ -6,7 +6,6 @@ const PROFILE_REFERRAL_INVITED_USERS_LIMIT: usize = 20;
 const PROFILE_NEW_USER_REGISTRATION_LEDGER_PREFIX: &str = "new-user-registration";
 const PROFILE_TASK_SYSTEM_USER_ID: &str = "system:profile-task";
 const PROFILE_TASK_LOGIN_EVENT_ID_PREFIX: &str = "daily-login";
-const PROFILE_TRACKING_SITE_SCOPE_ID: &str = "site";
 const PROFILE_TRACKING_PROFILE_MODULE_KEY: &str = "profile";

 #[spacetimedb::table(accessor = profile_dashboard_state)]
@@ -188,6 +187,10 @@ pub struct ProfileInviteCode {
    pub(crate) metadata_json: String,
    pub(crate) created_at: Timestamp,
    pub(crate) updated_at: Timestamp,
+    #[default(None::<Timestamp>)]
+    pub(crate) starts_at: Option<Timestamp>,
+    #[default(None::<Timestamp>)]
+    pub(crate) expires_at: Option<Timestamp>,
 }

 #[spacetimedb::table(
@@ -1902,6 +1905,7 @@ fn redeem_profile_referral_invite_code_record(
        .invite_code()
        .find(&invite_code)
        .ok_or_else(|| "邀请码不存在".to_string())?;
+    validate_profile_invite_code_redeem_time(&inviter_code, validated_input.updated_at_micros)?;
    if inviter_code.user_id == invitee_user_id {
        return Err("不能填写自己的邀请码".to_string());
    }
@@ -2124,6 +2128,8 @@ fn admin_upsert_profile_invite_code_record(
        input.admin_user_id,
        input.invite_code,
        input.metadata_json,
+        input.starts_at_micros,
+        input.expires_at_micros,
        input.updated_at_micros,
    )
    .map_err(|error| error.to_string())?;
@@ -2152,6 +2158,12 @@ fn admin_upsert_profile_invite_code_record(
            metadata_json: validated_input.metadata_json,
            created_at: existing.created_at,
            updated_at,
+            starts_at: validated_input
+                .starts_at_micros
+                .map(Timestamp::from_micros_since_unix_epoch),
+            expires_at: validated_input
+                .expires_at_micros
+                .map(Timestamp::from_micros_since_unix_epoch),
        });
        return Ok(build_profile_invite_code_snapshot_from_row(&inserted));
    }
@@ -2162,6 +2174,12 @@ fn admin_upsert_profile_invite_code_record(
        metadata_json: validated_input.metadata_json,
        created_at: updated_at,
        updated_at,
+        starts_at: validated_input
+            .starts_at_micros
+            .map(Timestamp::from_micros_since_unix_epoch),
+        expires_at: validated_input
+            .expires_at_micros
+            .map(Timestamp::from_micros_since_unix_epoch),
    });
    Ok(build_profile_invite_code_snapshot_from_row(&inserted))
 }
@@ -2286,9 +2304,34 @@ fn ensure_profile_invite_code(ctx: &ReducerContext, user_id: &str) -> ProfileInv
        metadata_json: PROFILE_INVITE_CODE_METADATA_DEFAULT_JSON.to_string(),
        created_at: ctx.timestamp,
        updated_at: ctx.timestamp,
+        starts_at: None,
+        expires_at: None,
    })
 }

+fn validate_profile_invite_code_redeem_time(
+    invite_code: &ProfileInviteCode,
+    now_micros: i64,
+) -> Result<(), String> {
+    if invite_code
+        .starts_at
+        .map(|starts_at| now_micros < starts_at.to_micros_since_unix_epoch())
+        .unwrap_or(false)
+    {
+        return Err("邀请码未生效".to_string());
+    }
+
+    if invite_code
+        .expires_at
+        .map(|expires_at| now_micros >= expires_at.to_micros_since_unix_epoch())
+        .unwrap_or(false)
+    {
+        return Err("邀请码已过期".to_string());
+    }
+
+    Ok(())
+}
+
 fn count_today_profile_referral_inviter_rewards(
    ctx: &ReducerContext,
    user_id: &str,
@@ -2397,11 +2440,7 @@ fn get_profile_task_center_snapshot(
        record_daily_login_tracking_event(ctx, &validated_input.user_id)?;
    }

-    Ok(build_profile_task_center_snapshot(
-        ctx,
-        &validated_input.user_id,
-        ctx.timestamp,
-    ))
+    build_profile_task_center_snapshot(ctx, &validated_input.user_id, ctx.timestamp)
 }

 fn claim_profile_task_reward_record(
@@ -2438,7 +2477,7 @@ fn claim_profile_task_reward_record(
        return Err(RuntimeProfileFieldError::TaskAlreadyClaimed.to_string());
    }

-    let progress_count = profile_task_progress_count(ctx, &validated_input.user_id, &config);
+    let progress_count = profile_task_progress_count(ctx, &validated_input.user_id, &config)?;
    if progress_count < config.threshold {
        return Err(RuntimeProfileFieldError::TaskNotClaimable.to_string());
    }
@@ -2469,7 +2508,7 @@ fn claim_profile_task_reward_record(
            claimed_at: ctx.timestamp,
        });

-    refresh_profile_task_progress(ctx, &validated_input.user_id, &config, day_key);
+    refresh_profile_task_progress(ctx, &validated_input.user_id, &config, day_key)?;
    let ledger_entry = ctx
        .db
        .profile_wallet_ledger()
@@ -2484,7 +2523,7 @@ fn claim_profile_task_reward_record(
        reward_points: claim.reward_points,
        wallet_balance,
        ledger_entry: build_profile_wallet_ledger_snapshot_from_row(&ledger_entry),
-        center: build_profile_task_center_snapshot(ctx, &validated_input.user_id, ctx.timestamp),
+        center: build_profile_task_center_snapshot(ctx, &validated_input.user_id, ctx.timestamp)?,
    })
 }

@@ -2640,7 +2679,7 @@ fn build_profile_task_center_snapshot(
    ctx: &ReducerContext,
    user_id: &str,
    updated_at: Timestamp,
-) -> RuntimeProfileTaskCenterSnapshot {
+) -> Result<RuntimeProfileTaskCenterSnapshot, String> {
    ensure_default_profile_task_config(ctx);
    let day_key = runtime_profile_beijing_day_key(updated_at.to_micros_since_unix_epoch());
    let mut configs = ctx.db.profile_task_config().iter().collect::<Vec<_>>();
@@ -2649,43 +2688,42 @@ fn build_profile_task_center_snapshot(
            .cmp(&right.sort_order)
            .then_with(|| left.task_id.cmp(&right.task_id))
    });
-    let tasks = configs
-        .into_iter()
-        .map(|config| {
-            let progress_count = profile_task_progress_count(ctx, user_id, &config);
-            refresh_profile_task_progress(ctx, user_id, &config, day_key);
-            let claim = ctx.db.profile_task_reward_claim().claim_id().find(
-                &build_runtime_profile_task_claim_id(user_id, &config.task_id, day_key),
-            );
-            RuntimeProfileTaskItemSnapshot {
-                task_id: config.task_id,
-                title: config.title,
-                description: config.description,
-                event_key: config.event_key,
-                cycle: config.cycle,
-                threshold: config.threshold,
+    let mut tasks = Vec::with_capacity(configs.len());
+    for config in configs {
+        validate_profile_task_user_scope(&config)?;
+        let progress_count = profile_task_progress_count(ctx, user_id, &config)?;
+        refresh_profile_task_progress(ctx, user_id, &config, day_key)?;
+        let claim = ctx.db.profile_task_reward_claim().claim_id().find(
+            &build_runtime_profile_task_claim_id(user_id, &config.task_id, day_key),
+        );
+        tasks.push(RuntimeProfileTaskItemSnapshot {
+            task_id: config.task_id,
+            title: config.title,
+            description: config.description,
+            event_key: config.event_key,
+            cycle: config.cycle,
+            threshold: config.threshold,
+            progress_count,
+            reward_points: config.reward_points,
+            status: resolve_runtime_profile_task_status(
+                config.enabled,
                progress_count,
-                reward_points: config.reward_points,
-                status: resolve_runtime_profile_task_status(
-                    config.enabled,
-                    progress_count,
-                    config.threshold,
-                    claim.is_some(),
-                ),
-                day_key,
-                claimed_at_micros: claim.map(|row| row.claimed_at.to_micros_since_unix_epoch()),
-                updated_at_micros: updated_at.to_micros_since_unix_epoch(),
-            }
-        })
-        .collect();
+                config.threshold,
+                claim.is_some(),
+            ),
+            day_key,
+            claimed_at_micros: claim.map(|row| row.claimed_at.to_micros_since_unix_epoch()),
+            updated_at_micros: updated_at.to_micros_since_unix_epoch(),
+        });
+    }

-    RuntimeProfileTaskCenterSnapshot {
+    Ok(RuntimeProfileTaskCenterSnapshot {
        user_id: user_id.to_string(),
        day_key,
        wallet_balance: profile_wallet_balance(ctx, user_id),
        tasks,
        updated_at_micros: updated_at.to_micros_since_unix_epoch(),
-    }
+    })
 }

 fn refresh_profile_task_progress(
@@ -2693,7 +2731,7 @@ fn refresh_profile_task_progress(
    user_id: &str,
    config: &ProfileTaskConfig,
    day_key: i64,
-) -> ProfileTaskProgress {
+) -> Result<ProfileTaskProgress, String> {
    let progress_id = build_runtime_profile_task_progress_id(user_id, &config.task_id, day_key);
    if let Some(existing) = ctx
        .db
@@ -2706,7 +2744,7 @@ fn refresh_profile_task_progress(
            .progress_id()
            .delete(&existing.progress_id);
    }
-    let progress_count = profile_task_progress_count(ctx, user_id, config);
+    let progress_count = profile_task_progress_count(ctx, user_id, config)?;
    let claimed = ctx
        .db
        .profile_task_reward_claim()
@@ -2717,7 +2755,7 @@ fn refresh_profile_task_progress(
            day_key,
        ))
        .is_some();
-    ctx.db.profile_task_progress().insert(ProfileTaskProgress {
+    Ok(ctx.db.profile_task_progress().insert(ProfileTaskProgress {
        progress_id,
        user_id: user_id.to_string(),
        task_id: config.task_id.clone(),
@@ -2731,17 +2769,19 @@ fn refresh_profile_task_progress(
            claimed,
        ),
        updated_at: ctx.timestamp,
-    })
+    }))
 }

 fn profile_task_progress_count(
    ctx: &ReducerContext,
    user_id: &str,
    config: &ProfileTaskConfig,
-) -> u32 {
+) -> Result<u32, String> {
+    validate_profile_task_user_scope(config)?;
    let day_key = runtime_profile_beijing_day_key(ctx.timestamp.to_micros_since_unix_epoch());
-    let scope_id = profile_task_tracking_scope_id(user_id, config);
-    ctx.db
+    let scope_id = profile_task_tracking_scope_id(user_id, config)?;
+    Ok(ctx
+        .db
        .tracking_daily_stat()
        .stat_id()
        .find(&build_runtime_tracking_daily_stat_id(
@@ -2751,15 +2791,26 @@ fn profile_task_progress_count(
            day_key,
        ))
        .map(|row| row.count)
-        .unwrap_or(0)
+        .unwrap_or(0))
 }

-fn profile_task_tracking_scope_id(user_id: &str, config: &ProfileTaskConfig) -> String {
-    match config.scope_kind {
-        RuntimeTrackingScopeKind::Site => PROFILE_TRACKING_SITE_SCOPE_ID.to_string(),
-        RuntimeTrackingScopeKind::Module => PROFILE_TRACKING_PROFILE_MODULE_KEY.to_string(),
-        RuntimeTrackingScopeKind::User => user_id.to_string(),
-        RuntimeTrackingScopeKind::Work => user_id.to_string(),
+fn profile_task_tracking_scope_id(
+    user_id: &str,
+    config: &ProfileTaskConfig,
+) -> Result<String, String> {
+    validate_profile_task_user_scope(config)?;
+    Ok(user_id.to_string())
+}
+
+fn validate_profile_task_user_scope(config: &ProfileTaskConfig) -> Result<(), String> {
+    if config.scope_kind == RuntimeTrackingScopeKind::User {
+        Ok(())
+    } else {
+        Err(format!(
+            "个人任务 scope_kind 首版仅支持 user，当前 task_id={} scope_kind={}",
+            config.task_id,
+            config.scope_kind.as_str()
+        ))
    }
 }

@@ -3242,6 +3293,12 @@ fn build_profile_invite_code_snapshot_from_row(
        user_id: row.user_id.clone(),
        invite_code: row.invite_code.clone(),
        metadata_json: row.metadata_json.clone(),
+        starts_at_micros: row
+            .starts_at
+            .map(|value| value.to_micros_since_unix_epoch()),
+        expires_at_micros: row
+            .expires_at
+            .map(|value| value.to_micros_since_unix_epoch()),
        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
    }