工程規格與改動清單

1 · 票券資料模型（核心）

目前票券只有名稱與價格，缺少「販售時間」與「數量」。建議把 feeItems 從 { name, price } 擴充為完整票券物件。

// 建議的票券型別（新增 data/ticket.ts，或擴充 activity.ts）
interface Ticket {
  id: string;
  name: string;            // 票種名稱
  price: number;           // 0 = 免費
  quantity: number | null;  // + 數量上限，null = 不限
  sold: number;             // + 已售（後端維護，前端唯讀）
  saleStart: Timestamp;     // + 販售開始
  saleEnd: Timestamp;       // + 販售結束
  description?: string;
  order: number;           // 排序用
}

狀態由系統計算，不另存欄位

報名端與編輯端共用同一個函式，避免主辦方手動上下架。

function ticketStatus(t: Ticket, now = new Date()) {
  if (t.quantity != null && t.sold >= t.quantity) return 'soldout';  // 已售完
  if (now < t.saleStart) return 'soon';                            // 尚未開賣
  if (now > t.saleEnd)   return 'ended';                           // 販售已截止
  return 'live';                                                  // 販售中（唯一可購買）
}

2 · 表單驗證調整

activity-form-schema.ts 的 feeItems.validation 需加上時間與數量檢查：

原本獨立的 feeAmount（單一費用）與 參加名額上限（schema:371）可由票券模型取代；保留與否視既有報名資料相容性決定。

3 · 報名表單排序：用拖曳（@dnd-kit）

npm i @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

// FormPreview：用 SortableContext 包欄位，handleReorderFields 不用改
<DndContext onDragEnd={({ active, over }) => {
  if (over && active.id !== over.id) {
    const from = fields.findIndex(f => f.id === active.id);
    const to   = fields.findIndex(f => f.id === over.id);
    handleReorderFields(from, to);   // 既有函式直接重用
  }
}}>
  <SortableContext items={fields.map(f => f.id)}>
    {fields.map(f => <SortableFieldRow key={f.id} field={f} />)}
  </SortableContext>
</DndContext>
// SortableFieldRow 用 useSortable({id}) 取得把手 listeners，套到 grip 圖示上。

系統必填欄位（姓名 / Email）標記 locked：不給拖曳把手、固定最上方，並用 dnd-kit 的 modifiers 限制不可被拖到其上方。完整步驟見 INTEGRATION.md。

4 · 報名表單欄位型別（FormField）

報名者端依此 schema 渲染與驗證。對應 components/Activities/FormBuilder/types.ts。

type FieldType =
  'text' | 'textarea' | 'email' | 'phone' | 'number'
  | 'select' | 'radio' | 'checkbox' | 'date' | 'file' | 'agreement';

interface FormField {
  id: string; type: FieldType; label: string;
  required: boolean; locked?: boolean;     // 系統必填(姓名/Email)：不可刪/拖、固定最上
  order: number; placeholder?: string; helperText?: string;
  options?: string[]; allowOther?: boolean;        // 選項型
  accept?: string; maxFileSize?: number; maxFiles?: number;  // 檔案型
  allowedDomains?: string[];                       // Email 限定網域
  min?: number; max?: number;                       // 數字
  agreementText?: string;                          // 同意條款
}

5 · 報名資料模型與狀態機

「報名者審核」是這次新增的概念，與「活動發布審核」(approvalStatus) 不同：前者主辦方審個別報名者，後者平台審活動能否上架。對應 data/registration.ts。

type RegistrationStatus =
  'pending'    // 待主辦方審核
  | 'approved' // 已通過，待繳費（系統已寄通知）
  | 'paid'     // 已繳費（付款 webhook 回寫）
  | 'rejected' | 'cancelled' | 'refunded';

interface Registration {
  id: string; activityId: string; userUid: string;
  ticketId: string; qty: number; amount: number;   // 送出當下金額快照
  answers: Record<string, unknown>;                 // key = FormField.id
  status: RegistrationStatus;
  createdAt: Timestamp; approvedAt?: Timestamp; paidAt?: Timestamp;
  rejectedAt?: Timestamp; rejectReason?: string;
  paymentId?: string; reviewerUid?: string;
}

// 狀態機
送出 ──▶ pending ──(主辦通過)──▶ approved ──(線上繳費)──▶ paid
            │ (主辦拒絕)              │ (逾期/取消)
            ▼                       ▼
         rejected               cancelled         paid ──(退款)──▶ refunded

6 · 金流：平台代收代付（主辦方不對帳）

金流由實習通統一處理，主辦方只審核、不碰錢。沿用 components/Payments/Payments.tsx。

7 · 帳號與認證：並行邏輯

沒有「創作者帳號」這種東西。一個帳號 ＋ 一個 verified-creator 標章；「主辦單位 ＝ 認證創作者 ＝ 同一標章」。取得標章有兩個可並行的入口，共用同一套審核（verifiedRoleApplications）。

// 入口 B：onboarding 選身分（新增一步）
function onOnboardingIdentitySelected(role) {
  createBasicAccount();                          // 一律先建一般帳號
  if (role === 'creator') goTo('/dashboard/verified-role-apply');
  else finishOnboarding();
}
// 入口 A：事後任意時間（設定頁、或點建立活動/撰寫文章時）
function onClickApplyVerification() { goTo('/dashboard/verified-role-apply'); }
// 兩入口都送同一支 → verifiedRoleApplications(pending) → 審核 → grantVerifiedBadgeToUser
submitVerifiedRoleApplication(payload);

// 能力判斷：只看標章 / admining，不看「是不是創作者帳號」
const isCreator       = profile.badges.includes('verified-creator');
const canHostActivity = profile.admining || isCreator;
const canPublishBlog  = isCreator;

8 · API / Cloud Functions 介面（建議）

審核與金流走後端，前端只呼叫、不直接改 status，避免被繞過。

// 主辦方審核（驗 caller 是該 activity 的 admining 成員）
approveRegistration({ registrationId })       // pending→approved + 寄繳費通知；非 pending 回 409
rejectRegistration({ registrationId, reason? }) // pending→rejected + 釋放 sold
// 報名者繳費
createPaymentSession({ registrationId })      // 限 approved；金額 = registration.amount → { paymentUrl }
onPaymentSucceeded(webhook)                   // approved→paid（後端，前端不可呼叫）
refundRegistration({ registrationId })        // paid→refunded
// 報名送出（務必用 transaction，見 §1 提示）
submitRegistration({ activityId, ticketId, qty, answers }) // → { registrationId }

錯誤碼：TICKET_NOT_ON_SALE / SOLD_OUT / NOT_PENDING / NOT_APPROVED / FORBIDDEN / VALIDATION_FAILED。

9 · 通知事件（Email + 站內）

10 · Firestore 安全規則（草稿）

sold / status / paidAt 全部只由後端寫，前端唯讀；報名者只能建自己的 pending。

match /activities/{aid} {
  allow read: if true;                       // 公開活動頁
  allow write: if isActivityAdmin(aid);          // 僅該官方帳號成員
  match /tickets/{tid} {
    allow read: if true;
    allow write: if false;                  // sold 只由後端 transaction 改
  }
}
match /registrations/{rid} {
  allow create: if request.auth.uid == request.resource.data.userUid
                && request.resource.data.status == 'pending';
  allow read:   if isOwner(rid) || isActivityAdmin(resource.data.activityId);
  allow update, delete: if false;          // status 轉換走 Cloud Functions
}

11 · 話題牆（NeedsWall）串接

話題牆＝既有 data/needs-wall-live.js（依行業 forumId 分版的話題；含 branches / poll）＋論壇 data/chat.ts ChatRoom。Post / ChatMessage 已顯示 verified-creator 標章。這次只新增「活動 / 創作者 ↔ 話題牆」的關聯。

12 · 改動檔案清單

13 · 驗收標準

14 · 撥款結算 ＋ 社團（本次新增）

14.1 撥款 / 結算（代收代付的「撥款」那半）

主辦方後台（/backstage → 撥款結算）把單一「票券收入」拆成 總收款 / 已扣手續費 / 待撥款 / 已撥款 / 已退款，並列每場結算明細與撥款記錄。完整邏輯見內部規格 金流邏輯_平台代收代付.md §10。

// data/payout.ts（新）— 撥款給主辦方（一活動一批）
interface Payout {
  id; organizerId; activityId; orderIds: string[];
  gross; platformFeeTotal; gatewayFeeTotal; net;   // net = gross − 平台抽成 − 金流手續費
  status: 'pending'|'paid'|'failed';
  bankAccountRef; paidAt?;
}
// 結算週期：活動結束 T+N（如 T+7）→ settleAndPayout() 建 payout 撥款

14.2 社團＝組織型主辦帳號（多管理員 / 換屆）

把「主辦方」從個人升級為可選的組織（社團）：活動掛在 clubId 而非建立者個人。主頁見 /club、註冊見 /club-register。

interface Club {
  id; name; school; type; verified; foundedYear; currentTerm;   // 屆數
}
interface ClubMember {
  clubId; userId; role: '社長'|'副社長'|'財務長'|'活動長'|'公關長';
  term; isOwner; status: 'active'|'invited'|'alumni';
}
// 活動歸屬：activity.ownerType: 'user' | 'club' + ownerId
// 換屆 = 換 owner，不換 club：移轉只更新 isOwner 與當期 term，
// 舊成員轉 alumni；活動 / 追蹤者 / 結算全掛 clubId，永久保留。

15 · 帳號選單 / 導覽（依角色）

關鍵原則：選單不是三套，而是「共用的個人選單 ＋ 依旗標展開的條件區塊」。本次改版是往既有選單「加」東西，不是把里程碑、心得那些換掉。能力旗標存在 appStates.userData，選單定義在 lib/config.js（TOP_BAR_TABS / DASHBOARD_SERVICES / PROFESSIONAL_SERVICES / BADGES_CONFIG）與 components/TopBar/TopBar.jsx。

15.1 能力旗標（userData）

15.2 帳號下拉選單 = 共用 ＋ 條件展開

// 一律顯示（已登入）— 對齊 TopBar.jsx UserDropdownPanel 的「我的 / 功能選項」
我的：里程碑徽章 /dashboard/milestones · 分享心得 /share · 收藏公司/活動 · 我的小夥伴 · 帳號設定 · 申請認證標章 · Coffee Chat
// 依旗標展開
if (badges.includes('verified-creator'))  ➜ 撰寫文章、創作者主頁
if (admining)        ➜ 官方帳號平台後台（活動管理 / 報名審核 / 撥款結算 / 活動成果）
if (adminingIsOwner) ➜ 共同管理員（多管理員）＋ 移轉擁有權（換屆）
if (admin)           ➜ 管理員工具

15.3 三種視角（旗標組合的結果）

15.4 社團 = 官方帳號的一種（重用，不是新系統）

本次的「社團多管理員 / 換屆」直接掛在既有機制上，不要另開一套：

16 · 活動個人化（領域 / 推薦 / 追蹤）

16.1 三個接點（最小改動）

16.2 資料模型

// data/activity.ts — 擴充
interface ActivityData { /* …現有… */ industryTags?: string[]; }   // 對應 INDUSTRY_CATEGORIES 的 key
// userData / profile — 擴充
preferredIndustries?: string[];   // onboarding 選；同一組 key
followedOrganizers?: string[];    // 追蹤的官方帳號 / 社團 / 創作者 id
// DashboardActivitiesFilters — 與 ActivitiesFilters 一致
industries: string[];            // 空陣列 = 全部

16.3 「綜合」排序 = 推薦分數（接在既有 sort）

// activities.jsx：comprehensive 分支從 return 0 換成 matchScore
if (sortBy === 'comprehensive') return score(b) - score(a);

function score(act) {
  let s = 0;
  const ind = userData.preferredIndustries || [];
  if (ind.length && act.industryTags?.some(t => ind.includes(t))) s += 100;   // 領域命中
  if (userData.followedOrganizers?.includes(act.ownerId)) s += 10;             // 追蹤的主辦
  s += deadlineHeat(act);   // 報名熱度 / 截止將近（沿用現有 deadline 桶邏輯）
  return s;
}

17 · InternX Academy 職涯課程平台（原型已完成；主平台整併後續排程）

17.1 入口地圖（各頁彼此怎麼進；詳版見 INTEGRATION.md §20.1）

一句話定位：職涯導向課程平台（對標 Hahow 但不做泛知識）。課程綁五類標籤（職涯方向 / 技能 / 年級 / 求職階段 / 成果），與職缺、履歷健檢、諮詢、活動互相導流；講師＝既有認證創作者，V1 金流用 Mock Payment 但資料流完整（Order → Payment → Enrollment → RevenueRecord）。

17.2 現在實作就該預留的 6 件事（重點）

Academy 本體晚點做沒關係，但下面這些「現在正在做的系統」設計時多想一步，未來就能直接共用：

17.3 新增資料（全部是新 collection，不動既有）

// Academy 專用（未來新增；User/Auth/Order/Payment/Notification/Tag 共用主平台）
Courses / CourseSections / CourseLessons / LessonResources
Enrollments / CourseProgress / CourseComments / CourseAnnouncements
RevenueRecords / CreatorPayouts / CreatorProfiles / CourseReviews / AdminReviewLogs

// 字幕（V1 單語中文；2026-07-02 由「不做」改為 V1 需求）
lesson.subtitles: { t: number /*秒*/, text: string }[]   // 原型 cue 模型
// 正式版：講師逐單元上傳 SRT/VTT → 解析為 cue；LessonVideos.subtitleTracks[]（多語預留）；CC 開關偏好存使用者設定

// 分潤紀錄（每筆付款成功自動建立；預設抽成 15%，可依創作者 / 課程覆寫）
RevenueRecord {
  orderId, courseId, creatorId,
  grossAmount: 3000,           // 售價
  platformFeeRate: 0.15,      // → platformFeeAmount: 450
  creatorIncomeAmount: 2550,
  paymentStatus, payoutStatus, paidAt, payoutAt
}

17.4 V1 購買資料流（Mock 金流、資料先完整）

點購買 → Order(pending) → Payment(pending, FakeProvider)
  → 「模擬付款成功」→ Payment(paid) → Order(paid)
  → 建 Enrollment（取得觀看權限）→ 建 RevenueRecord（分潤）

17.5 推薦 API（跨模組整合的核心）

// 職缺頁「申請前建議補強」/ 履歷健檢「下一步建議」/ 活動頁「延伸學習資源」共用一支
GET /recommendations/courses?source_type=job|company|interview_review|resume_review|event|consultation|profile|career_map&source_id=…
// 回傳 { courseId, title, reason, matchedTags, priorityScore }
// 匹配：Job.requiredSkills ↔ Course.skillTags；Job.category ↔ Course.careerTags；ResumeReview.weaknessTags ↔ Course.skillTags/outcomeTags

17.6 整併風險速查（詳版必讀：INTEGRATION.md §21）

原則：產品邏輯照抄 demo（欄位／狀態機／文案），工程實作全部重做（demo 是 localStorage 假後端）。🔴＝不解決不能上線。

17.7 範圍速記