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