开发或扩展 ACGTI 动漫人格测试时：维护 Vue 3…

适用于在 ACGTI 仓库中新增题目、角色、原型，修改评分引擎，使用 useQuiz/useShare，并部署到静态托管的场景。

适用场景

解决思路

1. 确认项目形态：纯客户端 Vue 3 + TypeScript 测验，39 道七点 Likert 题映射到 E/I、S/N、T/F、J/P 四维，匹配 8 个动漫原型，再从 40+ 角色库选具体角色；无后端、不收集用户数据，全部在浏览器运行。
2. 克隆仓库并进入目录：`git clone https://github.com/tianxingleo/ACGTI.git`，然后 `cd ACGTI`。
3. 安装依赖，推荐 Node 18+：`npm install`。
4. 启动开发服务器：`npm run dev`，使用 Vite 热重载。
5. 执行类型检查：`npx tsc --noEmit`。
6. 生产构建：`npm run build`，输出到 `dist/`。
7. 本地预览生产构建：`npm run preview`。
8. 部署到任意静态托管：`dist/` 使用 `base: './'` 相对路径，可直接部署。
9. 按项目结构放置代码与内容：`src/components/` 放可复用 UI；`src/composables/` 放 `useQuiz.ts` 和 `useShare.ts`；`src/data/` 放 `questions.json`、`archetypes.json`、`characters.json`、`characterVisuals.json`、`characterProbabilities.json`；`src/pages/` 放路由级组件；`src/types/quiz.ts` 放共享类型；`src/utils/` 放 `quizEngine.ts`、`characterVisuals.ts`、`characterProbability.ts`、`storage.ts`；`src/router/index.ts` 放路由。
10. 在处理任何数据文件或引擎逻辑前，先理解并遵守 `src/types/quiz.ts` 核心类型：`Dimension` 为 `'EI'|'SN'|'TF'|'JP'`；`Question` 包含 `id`、`text`、`dimension`、`archetypeWeights`、`tags`；`Archetype` 包含 `id`、`name`、`mbtiTypes`、`description`、`strengths`、`weaknesses`、`color`；`Character` 包含 `id`、`name`、`series`、`mbtiType`、`archetypeId`、`tags`、`stats`，其中 `stats` 包含 `energy`、`intuition`、`empathy`、`logic`、`order`、`chaos`；`CharacterVisual` 包含 `characterId`、`portraitUrl`、`backgroundUrl`、`primaryColor`、`accentColor`；`QuizResult` 包含 `mbtiType`、`dimensionScores`、`archetypeId`、`characterId`。
11. 评分引擎第 1 步：在 `calcDimensionRaw` 中按题目维度累加用户答案的带符号分数，即遍历 `questions`，对每个题目执行 `raw[q.dimension as Dimension] += answers[q.id] ?? 0`，得到 EI、SN、TF、JP 的原始分。
12. 评分引擎第 2 步：在 `normaliseDimension` 中将原始分归一化到 50–100，50 表示完全平衡；最大值 `max = questionCount * 3`，先 `Math.max(-max, Math.min(max, raw))` 截断，再返回 `Math.round(50 + (Math.abs(clamped) / max) * 50)`。
13. 评分引擎第 3 步：在 `mbtiLetter` 中按维度原始分推导 MBTI 字母；正极映射为 EI→E、SN→N、TF→T、JP→J，负极映射为 EI→I、SN→S、TF→F、JP→P，`raw >= 0` 取正极，否则取负极。
14. 评分引擎完整流程 `computeResult`：按 `['EI','SN','TF','JP']` 计算原始分；统计每维题目数 `countPerDim`；计算 `dimensionScores`；用 `mbtiLetter` 拼出 `mbtiType`；在 `archetypes` 中查找 `mbtiTypes.includes(mbtiType)` 的原型，找不到则回退到 `archetypes[0]`；在 `characters` 中筛选 `archetypeId === archetype.id` 的候选；默认取 `candidates[0]` 作为角色，可扩展为概率加权。
15. 添加新角色：编辑 `src/data/characters.json`，追加一个符合 `Character` schema 的对象，字段包括 `id`、`name`、`series`、`mbtiType`、`archetypeId`、`tags`、`stats`，例如 `id: 'hatsune-miku'`、`name: '初音ミク'`、`series: 'VOCALOID'`、`mbtiType: 'ENFP'`、`archetypeId: 'chaotic-spark'`、`tags: ['vocaloid','energetic','creative']`、`stats` 各轴 0–100。
16. 为新增角色添加视觉主题：编辑 `src/data/characterVisuals.json`，追加匹配条目，字段包括 `characterId`、`portraitUrl`、`backgroundUrl`、`primaryColor`、`accentColor`，例如 `characterId: 'hatsune-miku'`、`portraitUrl: 'https://your-cdn.example.com/miku-portrait.webp'`、`backgroundUrl: 'https://your-cdn.example.com/miku-bg.webp'`、`primaryColor: '#39C5BB'`、`accentColor: '#86EFDF'`。
17. 可选：为新增角色设置先验概率：编辑 `src/data/characterProbabilities.json`，追加 `characterId` 和 `baseProbability`，例如 `characterId: 'hatsune-miku'`、`baseProbability: 0.15`。
18. 新增角色时必须遵守规则：`id` 唯一且为 kebab-case；`mbtiType` 必须是 16 种标准 MBTI 类型之一；`archetypeId` 必须匹配 `archetypes.json` 中某个 `id`；`stats` 值必须是 0–100 的整数。
19. 添加新题目：编辑 `src/data/questions.json`，向数组追加对象，字段包括 `id`、`text`、`dimension`、`archetypeWeights`、`tags`，例如 `id: 40`、`text: '在一个陌生的聚会上，你更倾向于主动找人搭话还是等别人来找你？'`、`dimension: 'EI'`、`archetypeWeights` 覆盖 8 个原型 id、`tags: ['social','introvert-extrovert']`。
20. 新增题目指南：`id` 必须唯一并顺序递增；`dimension` 必须是 `'EI' | 'SN' | 'TF' | 'JP'`；`archetypeWeights` 的 key 必须匹配全部 8 个原型 `id`；权重范围是 -3 到 +3；正权重表示回答强烈同意会推向该原型；题目文本保持简体中文，以匹配现有文案。
21. 修改原型：编辑 `src/data/archetypes.json`，对象字段包括 `id`、`name`、`mbtiTypes`、`description`、`strengths`、`weaknesses`、`color`，例如 `id: 'glowing-protagonist'`、`name: '发光主角位'`、`mbtiTypes: ['ENFJ','ENFP']`、`description: '天生的领袖与感召者，能点燃周围人的热情。'`、`strengths: ['感召力强','共情深刻','行动力高']`、`weaknesses: ['容易过度承担','情绪波动大']`、`color: '#FF6B6B'`。
22. 原型规则：16 个 MBTI 类型每个应恰好出现在一个原型的 `mbtiTypes` 数组中；引擎使用 first-match 查找，缺口会导致回退到 `archetypes[0]`。
23. 使用 `useQuiz` composable 管理答题状态：从 `@/composables/useQuiz` 导入并解构 `currentQuestion`、`currentIndex`、`totalQuestions`、`progress`、`answer`、`goBack`、`result`、`isComplete`、`resetQuiz`；其中 `answer(value)` 记录 -3 到 +3 的答案并前进。
24. 使用 `useShare` composable 导出海报：从 `@/composables/useShare` 导入 `exportPNG`、`shareNative`；`exportPNG` 包装 `html2canvas` 处理 `#share-poster` 元素，例如 `await exportPNG('#share-poster', 'my-acgti-result.png')`；`shareNative` 使用 Web Share API，失败时回退到复制到剪贴板，例如传入 `title`、`text`、`url`。
25. 配置路由：`/` 为 `home`、`/intro` 为 `intro`、`/quiz` 为 `quiz`、`/result` 为 `result`、`/characters` 为 `characters`、`/about` 为 `about`；测验完成后用 `router.push({ name: 'result' })` 跳转。
26. 使用 localStorage 工具：从 `@/utils/storage` 导入 `saveResult`、`loadResult`、`clearResult`；用 `saveResult(result)` 跨刷新持久化结果；在 `ResultPage` 挂载时用 `loadResult()` 恢复；重测时用 `clearResult()` 重置。
27. 部署到 Cloudflare Pages（推荐）：连接 GitHub 仓库到 Cloudflare Pages 面板；Build command 填 `npm run build`；Build output directory 填 `dist`；无需环境变量，因为这是纯前端项目。
28. GitHub Actions CI：仓库已有 workflow，在每次 push 到 `main`/`dev` 以及 PR 时运行，执行 `npm ci` 和 `npm run build`。
29. 发布版本：运行 `git tag v1.2.0`，再运行 `git push origin v1.2.0`；GitHub Actions 会自动构建 `dist/`、压缩并创建 Release。
30. 按原型筛选角色：在组件中导入 `characters`，使用 `characters.filter((c) => c.archetypeId === archetypeId)` 得到子集。
31. 按角色 ID 访问视觉资源：导入 `visuals` 和 `enrichCharacterVisuals`，调用 `enrichCharacterVisuals(characters, visuals)`，将角色与视觉字段合并。
32. 生成响应式维度标签：实现 `dimensionLabel(dim, score)`，标签映射为 `EI: ['E 外向','I 内向']`、`SN: ['N 直觉','S 实感']`、`TF: ['T 思考','F 情感']`、`JP: ['J 判断','P 知觉']`；按现有实现，`score >= 50` 返回正极，否则返回负极，注释中 50 表示平衡可展示两极。
33. 排查 `npm run build` 类型错误：通常是新增 JSON 数据不符合类型；运行 `npx tsc --noEmit` 并修复 `src/types/quiz.ts` 中的不匹配。
34. 排查角色不出现在结果中：通常是 `characters.json` 与 `archetypes.json` 之间的 `archetypeId` 不匹配；确保 `archetypeId` 与某个原型 `id` 完全一致。
35. 排查新题目不影响分数：通常是 `dimension` key 错误；必须精确为 `'EI'`、`'SN'`、`'TF'` 或 `'JP'`。
36. 排查海报导出空白：通常是 `html2canvas` 无法加载跨域图片；将角色图片托管在启用 CORS 的 CDN，或使用 base64 data URI。
37. 排查 Cloudflare Pages 路由 404：通常是未配置 SPA fallback；在 `public/` 添加 `_redirects` 文件，内容为 `/* /index.html 200`。
38. 排查开发服务器 `@/` 导入报错：通常是 Vite alias 未解析；检查 `vite.config.ts` 是否包含 `resolve: { alias: { '@': '/src' } }`。

适用边界 · 注意事项

• 不适用于需要后端、账号系统、服务端计算或用户答案持久化存储的场景，因为 ACGTI 是纯客户端且不收集用户数据。
• 不适用于非 Vue 3 + TypeScript + Vite 的项目；若只是做普通问卷或非 MBTI 四维映射，评分与数据结构需要重新设计。
• Cloudflare Pages、GitHub Actions、GitHub Release 等部署部分依赖对应平台或仓库账号；若不使用这些服务，可改用其他静态托管但需自行配置 SPA fallback 与构建流程。