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/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;