PersonaQuest —— AI 编码代理项目指南

本文档供 AI 编码代理阅读。读者被假设对该项目一无所知。所有信息均基于实际代码与配置，不做假设或泛化。

项目概述

PersonaQuest（超级AI大学人格测试）是一个面向港科广学生的 4 维度人格测试 Web 平台。学生完成 31 道校园情境题后，系统根据四个维度（E/I、S/N、J/P、A/H）的得分组合出 16 种人格之一，并展示个性化解读、像素艺术形象与四维度光谱对比条。

核心用户流程：

首页 → 选择测试模板 → 答题（31题，乱序/正序） → 提交 → 结果页（人格卡片 + 四维度光谱）

项目采用中文作为界面与文档的主要语言。所有用户可见文本、代码注释、文档均使用中文。

技术栈

项目结构

├── data/                       # 可编辑数据源
│   ├── questions.json          # 题库（31道情境题、选项、分值）
│   └── personalities.json      # 人格库（16型人格定义、描述、像素画）
├── docs/                       # 人工撰写文档
│   ├── README.md               # 项目框架文档（面向项目 owner）
│   ├── question_design.md      # 原始题库设计稿
│   ├── scoring_criteria.md     # 评分与划分标准
│   └── todo.md                 # 协作任务清单
├── prisma/
│   ├── schema.prisma           # 数据库模型定义（SQLite）
│   ├── seed.ts                 # 种子脚本：从 data/*.json 导入数据，并创建默认账号
│   └── migrations/             # Prisma 迁移文件
├── src/
│   ├── client/                 # 前端（React + Vite）
│   │   ├── App.tsx             # 路由配置 + ProtectedRoute 守卫
│   │   ├── main.tsx            # 前端入口（StrictMode + BrowserRouter）
│   │   ├── index.css           # Tailwind 导入 + 自定义主题色 + 动画 keyframes
│   │   ├── pages/              # 页面组件
│   │   │   ├── HomePage.tsx
│   │   │   ├── TestPage.tsx
│   │   │   ├── ResultPage.tsx
│   │   │   ├── GalleryPage.tsx
│   │   │   ├── PersonalityDetailPage.tsx
│   │   │   ├── LoginPage.tsx / RegisterPage.tsx
│   │   │   ├── admin/          # AdminDashboard, QuestionManager, PersonalityManager
│   │   │   └── creator/        # CreatorDashboard, SubmitPage
│   │   ├── components/         # 可复用组件
│   │   │   ├── layout/         # Header.tsx, Footer.tsx
│   │   │   ├── test/           # QuestionCard.tsx, ProgressBar.tsx
│   │   │   └── result/         # PersonalityCard.tsx, PixelAvatar.tsx
│   │   ├── stores/             # Zustand 状态管理
│   │   │   ├── authStore.ts    # 用户登录态、token、localStorage 同步
│   │   │   └── testStore.ts    # 答题进度、题目、答案、当前索引
│   │   ├── hooks/              # React Hooks
│   │   │   ├── useAuth.ts      # 挂载时自动校验 token 并拉取 /auth/me
│   │   │   └── useMobile.ts    # 响应式断点检测（默认 768px）
│   │   └── lib/                # 工具与常量
│   │       ├── api.ts          # fetch 封装：自动注入 Bearer token、统一 ApiResponse 解析
│   │       ├── utils.ts        # cn (clsx + twMerge)、formatDate、角色/状态标签映射
│   │       └── constants.ts    # APP_NAME、ROUTES 常量表
│   ├── server/                 # 后端（Express + Prisma）
│   │   ├── index.ts            # 服务入口：启动 HTTP 监听
│   │   ├── app.ts              # Express 应用配置：中间件、路由挂载、全局错误处理
│   │   ├── routes/             # API 路由（按领域拆分）
│   │   │   ├── auth.routes.ts
│   │   │   ├── test.routes.ts      # 模板/题目获取、提交计分、结果查询
│   │   │   ├── personality.routes.ts
│   │   │   ├── admin.routes.ts     # 审核、题目/人格 CRUD（需 ADMIN）
│   │   │   └── creator.routes.ts   # 提交新内容、查看自己的提交（需 CREATOR/ADMIN）
│   │   ├── controllers/        # 请求处理层（目前仅 auth.controller.ts 使用）
│   │   ├── services/           # 业务逻辑层（目前仅 auth.service.ts 使用）
│   │   ├── middleware/
│   │   │   ├── auth.middleware.ts   # JWT 校验，将用户信息注入 req.user
│   │   │   ├── role.middleware.ts   # 角色权限守卫（requireRole）
│   │   │   └── error.middleware.ts  # 全局错误处理中间件
│   │   ├── config/
│   │   │   └── auth.ts              # JWT_SECRET、JWT_EXPIRES_IN 配置
│   │   └── utils/
│   │       └── prisma.ts            # PrismaClient 单例（开发环境复用全局实例）
│   └── shared/                 # 前后端共享代码
│       └── types.ts            # TypeScript 类型定义（User、Question、Personality、TestResult 等）
├── public/                     # 静态资源
├── index.html                  # Vite 入口 HTML（lang="zh-CN"）
├── package.json
├── tsconfig.json               # 前端 TS 配置（noEmit，含路径别名 @/*、@shared/*）
├── tsconfig.server.json        # 后端 TS 配置（emit 到 dist/server，模块 NodeNext）
├── vite.config.ts              # Vite 配置：React 插件、路径别名、端口 5173、/api 代理到 3001
├── tailwind.config.js          # Tailwind v4 主题扩展（primary 色阶、自定义动画）
├── postcss.config.js           # PostCSS：仅 @tailwindcss/postcss 插件
└── .env.example                # 环境变量模板

路径别名

前后端均使用 .js 扩展名进行模块导入（"type": "module" + TypeScript 编译要求），即使源文件是 .ts。

环境变量

复制 .env.example 为 .env 并根据需要修改：

PORT=3001                           # Express 服务端口号
DATABASE_URL="file:./dev.db"        # SQLite 数据库路径
JWT_SECRET="..."                    # JWT 签名密钥（生产环境务必更换）
JWT_EXPIRES_IN="7d"                 # Token 有效期
VITE_API_BASE_URL="http://localhost:3001/api"   # 前端 API 基地址

安全提示：JWT_SECRET 在生产环境中必须替换为强随机字符串。当前默认种子账号密码仅用于本地开发。

常用命令

# 安装依赖
npm install

# 开发模式（前后端同时启动）
npm run dev

# 仅启动前端（Vite，端口 5173）
npm run dev:client

# 仅启动后端（nodemon + tsx，端口 3001）
npm run dev:server

# 数据库迁移（修改 schema.prisma 后执行）
npm run db:migrate

# 生成 Prisma Client（schema 变更后）
npm run db:generate

# 导入题库与人格数据（修改 data/*.json 后执行）
npm run db:seed

# Prisma Studio（可视化查看/编辑数据库）
npm run db:studio

# 构建生产包（客户端 + 服务端）
npm run build

# 生产环境启动服务端（需先 build）
npm start

开发时，Vite 开发服务器会将 /api/* 请求代理到 http://localhost:3001，因此前后端可以独立运行而不产生 CORS 问题。

数据库模型

SQLite 数据库，通过 Prisma 管理。核心表：

重要约定：options、traits、scores、answers、pixelArt 等字段在数据库中以 JSON 字符串存储，读写时需要通过 JSON.parse / JSON.stringify 转换。前后端共享类型定义在 src/shared/types.ts 中，这些字段在 TypeScript 层面已经是结构化对象。

API 接口概览

所有 API 返回统一格式：{ success: boolean, data?: T, message?: string, error?: string }。

• POST /api/auth/register / POST /api/auth/login / GET /api/auth/me
• GET /api/test/templates / GET /api/test/templates/:id/questions / POST /api/test/submit / GET /api/test/results/:id
• GET /api/personalities?status=APPROVED / GET /api/personalities/:id
• GET|POST|PUT|DELETE /api/admin/*（需 ADMIN 角色）
• POST|GET /api/creator/*（需 CREATOR 或 ADMIN 角色）

详细接口列表见 docs/README.md。

用户角色与权限

默认种子账号（由 prisma/seed.ts 创建）：

• 管理员：admin@example.com / admin123
• 创作者：creator@example.com / creator123

计分逻辑

核心代码位于 src/server/routes/test.routes.ts。

1. 遍历用户提交的答案。
2. 每个选项的 scores 累加到对应维度（E、I、S、N、J、P、A、H）。
3. 每个维度比较两边得分，高者胜（同分默认左极）。
4. 组合成 4 位人格代码（如 ENJA）。
5. 查询 Personality 表返回结果并持久化到 TestResult。

评分标准细节见 docs/scoring_criteria.md。

代码风格与约定

• 语言：TypeScript（严格模式开启）。
• 模块系统：ESM（"type": "module"）。
• 导入扩展名：所有相对导入必须使用 .js 扩展名（包括指向 .ts 文件）。
• 前端严格检查：noUnusedLocals: true、noUnusedParameters: true。
• 命名：React 组件使用 PascalCase 默认导出；hooks 使用 useXxx 命名；store 使用 camelCase。
• 样式：优先使用 Tailwind 工具类；复杂条件类名通过 cn()（clsx + tailwind-merge）合并。
• 状态管理：
  • 全局共享状态使用 Zustand（authStore、testStore）。
  • 局部状态使用 useState / useEffect。
• API 调用：统一使用 src/client/lib/api.ts 中的 api.get/post/put/del，禁止直接写裸 fetch。
• 类型复用：前后端共享类型必须放在 src/shared/types.ts，通过 @shared/types 导入。
• 中文内容：所有用户界面文本、错误提示、日志输出均使用中文。

测试策略

当前项目未配置任何测试框架。 没有单元测试、集成测试或 E2E 测试。

若需添加测试，建议：

• 后端 API：使用 Vitest + supertest 测试 Express 路由。
• 前端组件：使用 Vitest + React Testing Library。
• 数据库测试：使用独立测试数据库或 Prisma 的 jest/vitest 环境重置方案。

部署说明

1. 设置环境变量（.env）。
2. 执行 npm run build：
   • tsc（前端类型检查）
   • vite build（构建客户端到 dist/client）
   • tsc -p tsconfig.server.json（编译服务端到 dist/server）
3. 执行数据库迁移：npx prisma migrate deploy。
4. 执行种子（可选）：npm run db:seed。
5. 启动服务：npm start（运行 dist/server/index.js）。

注意：构建产物中 dist/client 为静态前端资源，需要由外部 Web 服务器（如 Nginx）或 Express 自行托管。当前代码中 Express 并未内置静态文件托管逻辑，生产部署时需额外配置。

关键文件速查

扩展中的功能（参考 docs/todo.md）

根据 docs/todo.md，以下功能已在计划中或部分实现：

• 题目乱序（固定抽取全部题目，仅打乱顺序）
• 人格详情页（PersonalityDetailPage.tsx 已存在）
• 结果页分享卡片生成（适合朋友圈传播的图片导出）
• 测试历史记录（学生查看过往结果）
• 管理员数据统计（各人格占比、各题选项分布）
• 多模板支持（除默认模板外创建不同主题测试）

安全注意事项

• JWT 密钥：生产环境必须将 JWT_SECRET 替换为强随机字符串。
• 密码存储：使用 bcryptjs 加盐哈希（默认 10 rounds）。
• CORS：当前配置为 app.use(cors())，生产环境应限制为具体域名。
• SQL 注入：通过 Prisma ORM 参数化查询天然防护。
• 认证中间件：authMiddleware 校验 Bearer token 后将用户信息挂载到 req.user；后续路由通过 req.user! 访问，需确保中间件已正确挂载。
• 权限校验：requireRole 中间件必须在 authMiddleware 之后挂载，否则 req.user 为空会导致拒绝访问。