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

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