# fakc

**Repository Path**: xfnotes/fa

## Basic Information

- **Project Name**: fakc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-28
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FAKC — 刷题库管理系统

> 题库管理系统，采用 **Node.js/Express 后端 + Vue 3 前端** 架构，使用 MongoDB 作为数据库。

---

## 核心业务流程

1. **题目录入**：通过文字表单或图片 OCR 录入题目 → 关联知识点和来源 → 保存到 MongoDB
2. **题库浏览**：按知识点树/题型/来源/难度筛选题目 → 查看/编辑/删除
3. **智能组卷**：设定筛选条件 → 从题库抽题 → 预览/调整顺序 → 生成试卷
4. **在线做题**：学生作答 → 系统记录答案 → 自动/手动评分
5. **数据分析**：按知识点/题目/学生三维度统计 → 可视化展示 → 导出成绩

---

## 项目结构总览

```
fakc/
├── .codex/skills/              # AI Agent 技能定义
├── docs/                       # 项目文档
│   ├── backlog/                #   待办优化计划
│   ├── design-spec.md          #   设计规范
│   ├── shared/                 #   前后端共享契约
│   └── superpowers/specs/      #   现行开发规格
│
├── backend/                    # ===== 后端 =====
│   ├── src/
│   │   ├── server.js           #   启动入口
│   │   ├── app.js              #   Express 应用配置
│   │   ├── controllers/        #   业务逻辑 (11 个控制器)
│   │   ├── models/             #   数据模型 (9 个 Mongoose 模型)
│   │   ├── routes/             #   API 路由 (13 个路由文件)
│   │   ├── middleware/          #   中间件 (错误处理/上传/JSON 解析)
│   │   ├── validators/         #   输入验证 (6 个验证器)
│   │   ├── utils/              #   工具函数 (含数据库连接)
│   │   └── swagger/            #   API 文档
│   ├── scripts/                #   Mock 数据 & 种子脚本
│   ├── test/                   #   单元/集成测试 (21 个测试文件)
│   ├── public/                 #   前端构建产物 (Vite 输出)
│   └── uploads/                #   用户上传文件
│
└── frontend-src/               # ===== 前端 =====
    └── src/
        ├── main.js             #   Vue 应用入口
        ├── App.vue             #   根组件
        ├── router/             #   路由配置
        ├── views/              #   页面组件 (8 个页面)
        ├── components/         #   可复用组件 (50+ 组件)
        │   ├── analysis/       #     分析统计 (12 个)
        │   ├── common/         #     通用组件 (7 个)
        │   ├── question-fields/#     题目字段 (16 个)
        │   ├── question-browser/#    题库浏览 (3 个)
        │   ├── question-filter/#     组卷筛选 (5 个)
        │   ├── metadata/       #     元数据管理 (4 个)
        │   └── image-question-input/# 图片录入 (2 个)
        ├── composables/        #   组合式函数 (11 个)
        ├── services/           #   API 服务层 (12 个)
        ├── stores/             #   Pinia 状态管理 (3 个)
        ├── styles/             #   CSS 样式 (5 个)
        ├── utils/              #   工具函数 (11 个)
        └── validators/         #   表单验证 (3 个)
```

---

## 根目录文件

| 文件/文件夹 | 说明 |
|---|---|
| `AGENTS.md` | Codex AI Agent 指令文件，定义自动化编码代理的行为规范和项目约束 |
| `.env` | 环境变量配置（数据库连接串、端口号等），不纳入版本控制 |
| `fakc.code-workspace` | VS Code 工作区配置，多根目录（backend + frontend-src）联合开发 |
| `backend.log` | 后端服务运行日志输出 |

> 历史说明（2026-08-24）：旧 `readme.md` 已核对并入本文件后删除——其内容（早期目录树、
> cnpm 启动方式、tinymce 富文本方案、2025 年控制器 TODO）均已被当前 README / `docs/` /
> AGENTS.md 取代或修复；完整历史版本可从 git 追溯。

---

## 后端 `backend/`

### 入口与启动

| 文件 | 说明 |
|---|---|
| `package.json` | NPM 依赖清单与脚本（`start`、`test`、`seed:mock` 等） |
| `src/server.js` | 服务器启动入口：读取环境变量、连接 MongoDB、启动 HTTP 监听 |
| `src/app.js` | Express 应用初始化：注册中间件、挂载路由、配置静态文件服务 |

### `src/controllers/` — 控制器（业务逻辑层）

| 文件 | 负责的业务 |
|---|---|
| `authController.js` | 用户认证：登录、注册、JWT token 签发与校验 |
| `questionController.js` | 题目管理：创建、查询、更新、删除题目 |
| `questionSourceController.js` | 题目来源管理：管理题目的出处/来源分类 |
| `questionTypeController.js` | 题目类型管理：管理题型定义（单选、多选、填空、判断等） |
| `knowledgeTreeController.js` | 知识点树管理：知识点的增删改查及层级操作 |
| `studentController.js` | 学生管理：学生信息的 CRUD |
| `paperController.js` | 试卷管理：试卷的组卷、查询、更新 |
| `attemptController.js` | 做题记录：记录学生答题、计算得分 |
| `analysisController.js` | 数据分析：按知识点/题目/学生维度的统计分析 |
| `statisticsController.js` | 统计总览：整体数据统计接口 |
| `settingController.js` | 系统设置：全局配置的读取与更新 |

### `src/models/` — Mongoose 数据模型

| 文件 | 集合名 | 说明 |
|---|---|---|
| `Question.js` | questions | 题目模型：题干、选项、答案、题型、知识点关联、难度等 |
| `QuestionType.js` | questiontypes | 题型模型：题型名称、对应的表单模板字段定义 |
| `questionSource.js` | questionsources | 题目来源模型：来源名称、层级结构 |
| `KnowledgeNode.js` | knowledgenodes | 知识点节点模型：树形结构、父子关系、层级路径 |
| `Student.js` | students | 学生模型：学号、姓名、班级等基本信息 |
| `User.js` | users | 用户模型：账号、密码哈希、角色、JWT 相关字段 |
| `Paper.js` | papers | 试卷模型：试卷标题、关联题目列表、分值配置 |
| `Attempt.js` | attempts | 做题记录模型：学生、试卷、每题作答内容、得分、时间戳 |
| `Setting.js` | settings | 系统设置模型：键值对形式的全局配置项 |

### `src/routes/` — API 路由

| 文件 | 路由前缀 | 说明 |
|---|---|---|
| `index.js` | `/api` | 路由总入口：汇聚并注册所有子路由 |
| `auth.js` | `/api/auth` | 认证：登录、注册、刷新 token |
| `questions.js` | `/api/questions` | 题目 CRUD |
| `questionSource.js` | `/api/question-sources` | 题目来源 CRUD |
| `questionTypes.js` | `/api/question-types` | 题型管理 |
| `knowledgeTree.js` | `/api/knowledge-tree` | 知识点树 |
| `students.js` | `/api/students` | 学生管理 |
| `papers.js` | `/api/papers` | 试卷管理 |
| `attempts.js` | `/api/attempts` | 做题记录 |
| `analysis.js` | `/api/analysis` | 数据分析 |
| `statistics.js` | `/api/statistics` | 统计总览 |
| `settings.js` | `/api/settings` | 系统设置 |
| `swagger.js` | `/api/docs` | Swagger API 文档页面 |

### `src/middleware/` — 中间件

| 文件 | 说明 |
|---|---|
| `errorHandler.js` | 全局错误处理：捕获未处理异常，返回统一错误格式 |
| `jsonErrorHandler.js` | JSON 解析错误处理：捕获请求体格式错误 |
| `uploadMiddleware.js` | 文件上传：配置 multer（大小限制、存储路径、类型过滤） |

### `src/utils/` — 工具函数

| 文件 | 说明 |
|---|---|
| `questionUtils.js` | 题目数据格式转换、字段提取 |
| `analysisUtils.js` | 统计汇总、百分比计算 |
| `knowledgeTreeUtils.js` | 树遍历、路径拼接、子节点收集 |
| `validationUtils.js` | 通用验证辅助函数 |
| `db/config.js` | 数据库连接配置：读取环境变量 |
| `db/mongoose.js` | Mongoose 连接管理 |

### `src/validators/` — 输入验证

| 文件 | 说明 |
|---|---|
| `questionValidator.js` | 题目字段合法性和完整性校验 |
| `settingValidator.js` | 设置项键值类型和范围校验 |
| `paperValidator.js` | 试卷结构、题目列表合法性校验 |
| `attemptValidator.js` | 答题数据格式和约束校验 |
| `formTemplateValidator.js` | 题型模板字段定义校验 |
| `rules/questionValidationRules.js` | 可复用的字段级验证规则集 |

### `src/swagger/` — API 文档

| 文件 | 说明 |
|---|---|
| `index.js` | OpenAPI 配置：基本信息、服务器地址、安全方案 |
| `paths.js` | 所有接口的请求/响应 Schema 定义 |

### `scripts/` — 数据库脚本

| 文件 | 说明 |
|---|---|
| `seedKnowledgeTree.js` | 知识点树种子数据脚本 |
| `mock/index.js` | Mock 数据生成主入口，按序执行各模块 |
| `mock/01-question-sources.js` | 生成题目来源模拟数据 |
| `mock/02-knowledge-tree.js` | 生成知识点树模拟数据 |
| `mock/04-students.js` | 生成学生信息模拟数据 |
| `mock/05-users.js` | 生成用户账号模拟数据 |
| `mock/lib/random.js` | 随机工具函数 |

### `public/` — 前端构建产物

| 文件 | 说明 |
|---|---|
| `index.html` | 前端 SPA 入口 HTML |
| `assets/` | 编译后的 JS/CSS（Vite 输出，带 hash） |

### `uploads/` — 文件上传目录

存储用户上传的题目图片（`.png`、`.svg`），文件名为时间戳格式。

### `test/` — 后端测试（Jest）

| 文件 | 测试目标 |
|---|---|
| `api.test.js` | 端到端 API 集成测试 |
| `authController.test.js` | 认证控制器 |
| `questionController.test.js` | 题目控制器 |
| `questionSourceController.test.js` | 题目来源控制器 |
| `questionTypeController.test.js` | 题型控制器 |
| `questionUtils.test.js` | 题目工具函数 |
| `questionValidator.test.js` | 题目验证器 |
| `knowledgeTreeController.test.js` | 知识点树控制器 |
| `studentController.test.js` | 学生控制器 |
| `studentModel.test.js` | 学生模型 |
| `paperController.test.js` | 试卷控制器 |
| `attemptController.test.js` | 做题记录控制器 |
| `attemptModel.test.js` | 做题记录模型 |
| `attemptValidator.test.js` | 做题记录验证器 |
| `analysisController.test.js` | 分析控制器 |
| `analysisUtils.test.js` | 分析工具函数 |
| `statisticsController.test.js` | 统计控制器 |
| `settingController.test.js` | 设置控制器 |
| `settingValidator.test.js` | 设置验证器 |
| `formTemplateValidator.test.js` | 表单模板验证器 |
| `errorHandler.test.js` | 错误处理中间件 |

---

## 前端 `frontend-src/`

### 项目配置

| 文件 | 说明 |
|---|---|
| `package.json` | NPM 依赖：Vue 3、Element Plus、Pinia、ECharts、Vue Router 等 |
| `index.html` | Vite 入口 HTML，挂载 Vue 应用根节点 |
| `jsconfig.json` | 路径别名（`@` → `src/`）、智能提示配置 |
| `playwright.config.js` | Playwright E2E 测试配置 |
| `screenshot-settings.js` | E2E 截图对比配置 |
| `scripts/check-bundle-size.mjs` | 构建产物体积检查脚本 |

### `src/main.js` & `src/App.vue`

| 文件 | 说明 |
|---|---|
| `main.js` | Vue 应用入口：注册 Router、Pinia、Element Plus，挂载根组件 |
| `App.vue` | 根组件：全局布局壳（导航栏、侧边栏、主内容区）和路由出口 |

### `src/router/` — 路由

| 文件 | 说明 |
|---|---|
| `index.js` | 路由定义、懒加载、登录检查守卫 |

### `src/views/` — 页面组件

| 文件 | 页面 | 说明 |
|---|---|---|
| `Home.vue` | 首页 | 数据概览仪表盘和快捷入口 |
| `TextQuestionInputPage.vue` | 文字题目录入 | 表单式录入文字类题目 |
| `ImageQuestionInputPage.vue` | 图片题目录入 | 上传图片 + OCR 录入题目 |
| `QuestionBrowser.vue` | 题库浏览 | 列表/卡片浏览、搜索、筛选题目 |
| `QuestionFilterPage.vue` | 组卷筛选 | 条件筛选 → 拖拽排列 → 生成试卷 |
| `SystemSettings.vue` | 系统设置 | 管理题型、来源、知识点树等元数据 |
| `About.vue` | 关于 | 系统版本信息 |
| `ErrorPage.vue` | 错误页 | 404 等错误状态展示 |

### `src/components/` — 可复用组件

#### `components/analysis/` — 分析统计

| 文件 | 说明 |
|---|---|
| `AnalysisOverview.vue` | 分析总览面板 |
| `AnalysisStatCards.vue` | 统计数字卡片 |
| `KnowledgeProgressTree.vue` | 知识点掌握进度树 |
| `NodeDimension.vue` | 按知识点维度分析 |
| `QuestionDimension.vue` | 按题目维度分析 |
| `StudentDimension.vue` | 按学生维度分析 |
| `QuestionContent.vue` | 题目内容渲染（文本+图片+选项） |
| `QuestionDetailDrawer.vue` | 题目详情侧滑面板 |
| `StudentDetailDrawer.vue` | 学生做题记录侧滑面板 |
| `PaperScoreDialog.vue` | 试卷整体评分对话框 |
| `RecordScoreDialog.vue` | 手动录入/修改分数对话框 |
| `ScoreImportDialog.vue` | Excel 批量导入成绩对话框 |

#### `components/common/` — 通用组件

| 文件 | 说明 |
|---|---|
| `QuestionDisplay.vue` | 统一的题目展示（文本+图片+选项+答案） |
| `QuestionOptions.vue` | 单选/多选/判断选项交互 |
| `QuestionTypeSelect.vue` | 题型下拉选择器 |
| `ImageAnswerDialog.vue` | 图片题参考答案查看 |
| `RichEditor.vue` | 富文本编辑器封装 |
| `SourceCascader.vue` | 题目来源级联选择器 |
| `TreeNodeLabel.vue` | 知识点树/来源树节点自定义渲染 |

#### `components/question-fields/` — 题目表单字段

| 文件 | 说明 |
|---|---|
| `registry.js` | 字段名 → 组件的映射注册表 |
| `DynamicQuestionFields.vue` | 根据题型模板动态加载字段组件 |
| `ContentField.vue` | 题干内容 |
| `HtmlContentField.vue` | HTML 富文本题干 |
| `RichTextField.vue` | 富文本编辑 |
| `OptionsField.vue` | 选项列表（单选/多选） |
| `AnswerOptionsField.vue` | 答案选项 |
| `JudgeField.vue` | 判断题（对/错） |
| `BlankField.vue` | 填空题（空格答案） |
| `TextField.vue` | 简单文本输入 |
| `ImageField.vue` | 图片上传 |
| `DifficultyField.vue` | 难度选择 |
| `ScoreField.vue` | 分值输入 |
| `TagsField.vue` | 标签输入 |
| `SourceField.vue` | 来源选择 |

#### `components/question-browser/` — 题库浏览

| 文件 | 说明 |
|---|---|
| `Question.vue` | 题目卡片 |
| `QuestionEdit.vue` | 题目内联/抽屉编辑 |
| `TreePanel.vue` | 左侧知识点筛选树 |

#### `components/question-filter/` — 组卷筛选

| 文件 | 说明 |
|---|---|
| `DragDropLayout.vue` | 拖拽调整题目顺序容器 |
| `GeneratePaperDialog.vue` | 确认组卷参数并生成试卷 |
| `PaperPreview.vue` | 生成后试卷内容预览 |
| `PaperPrint.vue` | 打印样式试卷渲染 |
| `ImageCropper.vue` | 上传图片裁剪器 |

#### `components/metadata/` — 元数据管理

| 文件 | 说明 |
|---|---|
| `TypeManagement.vue` | 题型增删改查 |
| `TypeFormTemplate.vue` | 题型表单模板定义/预览 |
| `SourceManagement.vue` | 题目来源树形分类管理 |
| `ListManagement.vue` | 通用 CRUD 列表容器 |

#### `components/image-question-input/` — 图片题目录入

| 文件 | 说明 |
|---|---|
| `UploadPanel.vue` | 图片拖拽/选择上传面板 |
| `TreePanel.vue` | 录入时关联知识点 |

### `src/composables/` — 组合式函数

| 文件 | 说明 |
|---|---|
| `useAnswerManagement.js` | 答案选择与校验 |
| `useChart.js` | ECharts 初始化、更新、resize 监听 |
| `useImageUpload.js` | 图片上传、预览、删除 |
| `useLocalCache.js` | 基于 localforage 的本地缓存 |
| `useLogger.js` | 统一前端日志记录 |
| `useMessage.js` | 封装 ElMessage 消息提示 |
| `usePaperPagination.js` | 试卷列表分页 |
| `usePaperPrint.js` | 打印前格式处理 |
| `useResizablePanels.js` | 拖拽调整面板宽度 |
| `useTypeTemplates.js` | 题型模板加载与管理 |
| `knowledgeTree/fetchWithRetry.js` | 知识点树获取（含重试） |

### `src/services/` — API 服务层

| 文件 | 对应后端模块 | 说明 |
|---|---|---|
| `api.js` | — | Axios 实例：baseURL、拦截器、token 注入 |
| `withError.js` | — | 统一请求异常处理并弹出提示 |
| `auth.js` | auth | 登录、注册、刷新 |
| `questions.js` | questions | 题目 CRUD |
| `questionSource.js` | question-sources | 题目来源 |
| `questionTypes.js` | question-types | 题型管理 |
| `knowledgeTree.js` | knowledge-tree | 知识点树 |
| `students.js` | students | 学生管理 |
| `papers.js` | papers | 试卷管理 |
| `analysis.js` | analysis | 数据分析 |
| `statistics.js` | statistics | 统计总览 |
| `settings.js` | settings | 系统设置 |

### `src/stores/` — Pinia 状态管理

| 文件 | 说明 |
|---|---|
| `user.js` | 登录状态、用户信息、token |
| `knowledgeTree.js` | 树形数据缓存、当前选中节点 |
| `settings.js` | 全局配置项本地缓存 |

### `src/styles/` — CSS 样式

| 文件 | 说明 |
|---|---|
| `design-tokens.css` | 设计令牌：全局 CSS 变量（颜色、间距、字号、圆角） |
| `global.css` | 全局重置、基础排版 |
| `layout.css` | 页面骨架布局（侧边栏、顶栏、内容区） |
| `components.css` | Element Plus 组件样式覆盖/增强 |
| `utilities.css` | 原子化工具类（`.mt-4`、`.flex` 等） |

### `src/utils/` — 工具函数

| 文件 | 说明 |
|---|---|
| `answerParser.js` | 答案字符串 → 结构化数据 |
| `chartTheme.js` | ECharts 配色方案 |
| `htmlSanitize.js` | HTML 内容 XSS 过滤 |
| `imageHelper.js` | 图片压缩、格式转换、base64 |
| `optionImages.js` | 选项图片资源管理 |
| `paperExportWord.js` | 试卷导出 `.docx` |
| `previewFit.js` | 图片/内容自适应缩放 |
| `progressColor.js` | 根据正确率返回颜色 |
| `questionSampler.js` | 按条件随机抽题 |
| `questionTemplate.js` | 根据题型生成默认数据结构 |
| `scoreImport.js` | Excel 解析提取成绩 |

### `src/validators/` — 前端表单验证

| 文件 | 说明 |
|---|---|
| `questionValidationRules.js` | Element Plus 表单验证规则 |
| `templateValidator.js` | 题型模板定义合法性校验 |
| `validationUtils.js` | 通用验证辅助方法 |

### `src/prototypes/` — 原型组件

| 文件 | 说明 |
|---|---|
| `QuestionFilterPagePrototype.vue` | 组卷筛选页原型版本，用于设计迭代 |

### `tests/` — 前端测试（Vitest）

覆盖所有主要组件和工具函数，按 `tests/components/` 和 `tests/utils/` 组织。

### `e2e/` — 端到端测试（Playwright）

| 文件 | 说明 |
|---|---|
| `smoke.spec.js` | 冒烟测试：核心页面加载和基本交互 |
| `glass-style.spec.js` | 样式回归测试：截图对比验证 UI |

---

## `docs/` — 项目文档

| 文件 | 说明 |
|---|---|
| `README.md` | 文档索引 |
| `design-spec.md` | 前端设计规范（配色/字体/图标），`ui-design-language` 技能唯一权威文档 |
| `性能基线.md` | 性能基线/门禁/历史结论（唯一权威） |
| `mock数据填充方案.md` | 全库 8 集合 mock 造数方案（脚本：`npm run seed:mock`） |

### `docs/backlog/` — 待办与优化计划

| 文件 | 说明 |
|---|---|
| `待优化事项.md` | 按优先级排序的待优化问题清单 |
| `待实现图片题目识别方案.md` | 图片题 OCR/多模态识别方案 |

### `docs/shared/` — 前后端共享契约

| 文件 | 说明 |
|---|---|
| `field-contracts.md` | 字段命名和类型约定 |
| `question-validation-contract.json` | 题目验证规则（JSON，前后端共用） |

---

## `.codex/skills/` — AI Agent 技能定义

| 文件 | 说明 |
|---|---|
| `backend-best-practices/SKILL.md` | Node.js/Express 编码规范 |
| `css-best-practices/SKILL.md` | CSS 样式编写规范 |
| `fakc-project-guide/SKILL.md` | 项目结构与约定指南 |
| `frontend-semantic-audit/SKILL.md` | HTML/组件语义化审查规范 |
| `ui-design-language/SKILL.md` | 设计系统与视觉规范 |
| `vue-best-practices/SKILL.md` | Vue 3 Composition API 编码规范 |