# 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-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FAKC — 题库、组卷与教学测试管理系统

> FAKC 是一个面向教学团队使用的题库与测试管理系统。前端采用 **Vue 3 + Element Plus + Pinia + ECharts**，后端采用 **Node.js + Express 5 + MongoDB**；支持多用户数据隔离、班级与花名册管理、快速听写、测试分析、组卷导出，以及 PDF 智能切题与人工校对。

---

## 当前能力

### 题目与题库

- 支持文字题、图片题、多图/多部件题目录入，题型模板可配置。
- 通过知识点树、题型、来源、难度、标签等维度组织和筛选题目。
- 题库支持搜索、浏览、编辑、批量提交与软删除。
- 题目与试卷支持图片部件，可随试卷一起导出 Word。
- 图片题 OCR/多模态文字化仍在 `docs/backlog/` 中，当前 PDF 云端识别只做版面结构分析，不做正文 OCR。

### 组卷与导出

- 按知识点、题型、来源、难度和分值等条件筛选题库。
- 支持随机抽题、拖拽调整顺序、试卷预览、打印和 Word 导出。
- 组卷参数、题型模板、导出页眉等可在系统设置中维护。

### 班级、花名册与测试记录

- 名单管理支持 Excel 导入、学生分组与组内序号、当前班级切换和班级归档。
- 花名册采用树形结构，可拆子册、复制、重命名、查看每次录入记录与达标进度。
- 学生选择和成绩录入使用“组 × 组内序号”矩阵，适配大班和多小组。
- 支持统考、补考、单题记分、试卷记分及成绩 Excel 导入。
- 已结束教学周段通过组快照固定历史分组，归档班级默认只读。

### 快速听写

- 支持单题与多题快速听写，按分数线和题型规则自动判定通过/不通过。
- 支持负分、缺考登记、迟交补录、学生验收和手动覆盖。
- 批量录入支持自动保存草稿、关闭后恢复、放弃草稿和幂等生成正式记录。
- 单题与多题均提供共享矩阵、阶段化批改/过关流程。
- 支持快速听写花名册打印，打印排版按内容自动分页。

### 测试分析与学习分析

- 首页为学习分析中心，提供总览、题目、学生、章节/知识点四个维度。
- 支持按试卷筛选、趋势与正确率统计、题目/学生详情抽屉。
- 测试记录页内提供“测试分析”主看板和“快速听写汇总册”子条目。
- 测试分析支持学期周段、小组统计、跨组加权评比与 Top10 图表。

### PDF 智能切题与校对

流程：上传 PDF → 文本层/页图检查 → 本地版面切题 → 可选云端视觉识别 → 校对台人工框选与合并 → 生成高清图片素材 → 提交为图片题草稿。

- 支持文本型、扫描型和混合型 PDF；扫描页可人工框选。
- 支持页面方向覆盖、细粒度倾斜纠偏、150/300/600 DPI 按需预览。
- 支持题框编辑、跨页续题合并、并列区域归属、批次切分和未分配片段处理。
- 云端识别使用 OpenAI 兼容接口，调用前展示页数与费用预估，按页续跑并记录用量账本。
- PDF 任务支持多用户公平调度、并发上限、取消、清理和重启恢复。

### 多用户、安全与可恢复操作

- JWT 登录，支持主账号附加受限/只读登录凭据。
- 业务数据按 owner 隔离，归档班和只读凭据受写入守卫保护。
- 成功业务写操作记录为可理解的操作日志，并采集数据库级变更快照。
- 支持回收站、对象版本历史、恢复和最近一次安全撤销。
- 云端 AI 密钥按 owner 单独保存，不进入普通设置或操作日志，不通过接口回传明文。

---

## 快速开始

### 环境要求

- Node.js 22 及以上。
- MongoDB，默认连接 `mongodb://localhost:27017/kafc`。
- 使用 PDF 智能切题时需安装 Poppler：`pdfinfo`、`pdftotext`、`pdftoppm`。
- 使用 PDF 智能切题时需安装 **Tesseract OCR 5.x**（含 `eng` 与 `osd` 数据，分别用于稳定定位题号行和识别前方向预检）：
  - Debian/Ubuntu：`sudo apt-get install -y tesseract-ocr`
  - 校验：`tesseract --version`、`tesseract --list-langs`（应包含 `eng` 与 `osd`）
  - 未安装时云端识别仍能运行，但题框位置会退回到大模型给出的坐标、可能逐次漂移（不会报错）。

### 安装依赖

```bash
npm install
npm --prefix backend install
npm --prefix frontend-src install
```

### 环境变量

在仓库根目录准备 `.env`，不要提交真实密钥。常用变量：

| 变量             | 用途             | 开发默认/注意                                                      |
| ---------------- | ---------------- | ------------------------------------------------------------------ |
| `MONGO_URI`      | MongoDB 连接串   | `mongodb://localhost:27017/kafc`                                   |
| `DB_NAME`        | 数据库名         | `kafc`                                                             |
| `EXPRESS_PORT`   | 后端监听端口     | 源码默认 `3001`；Vite 代理固定指向 `3000`，本地联调建议设为 `3000` |
| `JWT_SECRET`     | JWT 签名密钥     | 开发有弱默认值；生产环境必须显式设置                               |
| `JWT_EXPIRES_IN` | JWT 有效期       | `7d`                                                               |
| `CORS_ORIGIN`    | 生产 CORS 白名单 | 逗号分隔多个来源；未设置时开发环境放开                             |
| `NODE_ENV`       | 运行环境         | 生产环境设为 `production`                                          |

AI 云端识别支持多套自定义服务商档案，每套包含完整接口地址、模型和独立密钥，可在“系统设置 → AI 识别”中新增、编辑、测试和切换；系统不做 URL 路径拼接，密钥不写入仓库文件且任何接口都不回传明文。预算和预置提示规则为全局配置，提示规则只允许复选后端白名单项。

### 启动开发环境

```bash
npm run dev
```

- 前端：`http://localhost:5173`
- 后端 API：`http://localhost:3000/api`（当 `EXPRESS_PORT=3000`）
- Swagger 可视化文档：`http://localhost:3000/api/doc`
- Swagger JSON：`http://localhost:3000/api/doc/json`

也可以分别启动：

```bash
npm run dev:backend
npm run dev:frontend
```

### 生成 Mock 数据

```bash
npm --prefix backend run seed:mock
npm --prefix backend run db:reset
```

- `seed:mock`：按模块生成演示数据。
- `db:reset`：重置业务数据并保留题型等必要基础数据。

### 生产构建

```bash
npm --prefix frontend-src run build
NODE_ENV=production npm --prefix backend start
```

前端构建输出到 `backend/public/`，由 Express 直接托管。生产环境必须在启动前注入 `JWT_SECRET` 等敏感配置。

---

## 常用命令

### 根目录

| 命令                                | 说明                         |
| ----------------------------------- | ---------------------------- |
| `npm run dev`                       | 同时启动前后端开发服务       |
| `npm run dev:backend`               | 只启动后端                   |
| `npm run dev:frontend`              | 只启动前端                   |
| `npm run check:validation:contract` | 检查前后端题目验证契约一致性 |

### 后端

| 命令                                            | 说明                     |
| ----------------------------------------------- | ------------------------ |
| `npm --prefix backend start`                    | 生产启动                 |
| `npm --prefix backend run dev`                  | nodemon 开发启动         |
| `npm --prefix backend test`                     | Mocha 测试，需要 MongoDB |
| `npm --prefix backend run test:coverage`        | 后端覆盖率门禁           |
| `npm --prefix backend run seed:mock`            | 生成 Mock 数据           |
| `npm --prefix backend run db:reset`             | 重置 Mock/业务数据       |
| `npm --prefix backend run migrate:multiuser`    | 多用户历史数据迁移       |
| `npm --prefix backend run migrate:upload-paths` | 历史上传路径迁移         |
| `npm --prefix backend run lint`                 | ESLint                   |
| `npm --prefix backend run format:check`         | Prettier 检查            |

### 前端

| 命令                                          | 说明                     |
| --------------------------------------------- | ------------------------ |
| `npm --prefix frontend-src run dev`           | Vite 开发服务            |
| `npm --prefix frontend-src run build`         | 构建到 `backend/public/` |
| `npm --prefix frontend-src run build:check`   | 构建并执行体积性能门禁   |
| `npm --prefix frontend-src run test`          | Vitest watch             |
| `npm --prefix frontend-src run test:run`      | Vitest 单次运行          |
| `npm --prefix frontend-src run test:coverage` | 前端覆盖率门禁           |
| `npm --prefix frontend-src run test:e2e`      | Playwright E2E           |
| `npm --prefix frontend-src run lint`          | ESLint                   |
| `npm --prefix frontend-src run format:check`  | Prettier 检查            |

### 权威质量门禁

```bash
bash scripts/ci-local.sh
```

该脚本串行执行后端测试、前端测试、契约检查、构建体积门禁、前后端 lint/format/覆盖率，以及技能和 Skill Router 检查。后端测试需要本机 MongoDB `27017`。

---

## 系统架构

```text
浏览器
  └─ Vue views / components
       └─ services（业务请求与响应映射）
            └─ api.js（Axios、token、错误拦截）
                 └─ /api
                      └─ Express routes
                           ├─ auth / tenant / permission / read-only guards
                           └─ controllers
                                ├─ models（MongoDB）
                                ├─ utils / validators
                                └─ services（PDF、AI、恢复等基础设施）
```

设计原则：

- 前端组件不直接发 HTTP，统一经 `services/` 调用 `api.js`。
- 后端控制器负责业务编排，模型负责持久化约束，PDF/AI 等复杂能力下沉到 `services/`。
- 业务数据以 owner 为隔离边界；写操作进入租户上下文、权限守卫和操作审计链路。
- 前端样式按 `design-tokens → global → layout → components → controls → utilities` 分层组织，其中 `controls.css` 统一输入类控件皮肤。

---

## 目录总览

```text
fakc/
├── .codex/skills/                 # 项目级 AI Agent 技能与 references
├── docs/                          # 当前有效规范、契约、基线和业务规格
│   ├── backlog/                   # 活跃待办与待实施功能
│   ├── shared/                    # 前后端共享字段/验证契约
│   └── superpowers/specs/         # 现行业务规则与设计规格
├── scripts/                       # 本地 CI、技能检查和 Skill Router
├── backend/
│   ├── src/
│   │   ├── controllers/           # 题目、练习、分析、PDF、审计等控制器
│   │   ├── models/                # Mongoose 模型与公共插件
│   │   ├── routes/                # API 路由与权限挂载
│   │   ├── middleware/            # 错误、上传、操作上下文等中间件
│   │   ├── validators/            # 请求与业务规则校验
│   │   ├── services/ai/           # OpenAI 兼容客户端、预算与用量
│   │   ├── services/pdf/          # PDF 检查、切题、渲染、纠偏、队列
│   │   ├── swagger/               # OpenAPI 配置与 paths
│   │   └── utils/                 # 数据库、树、分析、恢复、AI 等工具
│   ├── scripts/mock/              # Mock 数据与迁移脚本
│   ├── test/                      # Mocha 单元/集成/PDF 链路测试
│   ├── public/                    # 前端构建产物（gitignore）
│   └── uploads/                   # 用户上传文件（gitignore）
└── frontend-src/
    ├── src/
    │   ├── views/                 # 页面级路由组件
    │   ├── components/            # 按功能域拆分的可复用组件
    │   ├── composables/           # 状态、表单、拖拽、PDF 校对等逻辑
    │   ├── services/              # 业务 API 服务层
    │   ├── stores/                # Pinia store
    │   ├── styles/                # 五层 CSS
    │   ├── utils/                 # 纯函数与导出/打印/图像工具
    │   └── validators/            # 前端表单校验
    ├── tests/                     # Vitest 单测
    ├── e2e/                       # Playwright E2E
    └── scripts/                   # 构建体积检查
```

---

## 后端关键模块

| 模块           | 主要文件/目录                                                                                                     | 说明                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| 认证与权限     | `controllers/authController.js`、`credentialController.js`                                                        | 登录、JWT、附加凭据、只读/权限守卫                   |
| 租户隔离       | `models/plugins/tenantPlugin.js`、`middleware/withOperation.js`                                                   | owner 注入、查询隔离、写操作上下文                   |
| 题目与元数据   | `questionController.js`、`questionTypeController.js`、`questionSourceController.js`、`knowledgeTreeController.js` | 题库、题型模板、来源树、知识点树                     |
| 学生与班级     | `studentController.js`、`models/Student.js`、`GroupSnapshot.js`                                                   | 学生分组、班级归档、周段组快照                       |
| 花名册与测试   | `controllers/practice/`、`practiceController.js`                                                                  | 花名册、Session、快速听写、草稿、缺考/迟交、跨册聚合 |
| 试卷与做题     | `paperController.js`、`attemptController.js`、`analysisController.js`、`statisticsController.js`                  | 组卷、作答、学习分析与统计                           |
| 操作审计与恢复 | `operationController.js`、`recycleBinController.js`、`entityVersionController.js`、`undoController.js`            | 操作日志、软删除、回收站、版本恢复、安全撤销         |
| PDF 智能切题   | `pdfImportJobController.js`、`services/pdf/`、`models/PdfImportJob.js`                                            | 检查、切题、云端识别、校对、渲染、队列与恢复         |
| AI 设置与用量  | `services/ai/`、`AiCredential.js`、`AiUsageLog.js`                                                                | OpenAI 兼容调用、密钥隔离、预算闸门、计费日志        |
| API 文档       | `swagger/`、`routes/swagger.js`                                                                                   | Swagger UI 与 OpenAPI JSON                           |

### 核心数据模型

- 题库：`Question`、`QuestionType`、`QuestionSource`、`KnowledgeNode`
- 教学：`Student`、`Roster`、`Session`、`PracticeDraft`、`GroupSnapshot`
- 试卷与分析：`Paper`、`Attempt`
- 系统与多用户：`User`、`Setting`、`AiCredential`、`AiUsageLog`
- 审计与恢复：`OperationLog`、`OperationChange`、`OperationHead`
- PDF：`PdfImportJob`

主要 API 前缀包括：`/api/auth`、`/api/questions`、`/api/knowledge-tree`、`/api/question-types`、`/api/question-sources`、`/api/students`、`/api/attempts`、`/api/statistics`、`/api/analysis`、`/api/papers`、`/api/settings`、`/api/practice`、`/api/pdf-import-jobs`、`/api/operations`、`/api/recycle-bin`、`/api/entity-versions`；撤销与恢复预览接口同样挂载在 `/api/operations`。

---

## 前端关键页面

| 路由                    | 页面                         | 说明                                                              |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------- |
| `/login`                | `Login.vue`                  | 登录入口                                                          |
| `/`                     | `Home.vue`                   | 学习分析中心，原 `/analysis` 已重定向至此                         |
| `/image-question-input` | `ImageQuestionInputPage.vue` | 图片题批量录入与 PDF 智能切题入口                                 |
| `/question-input`       | `TextQuestionInputPage.vue`  | 文字题录入                                                        |
| `/question-browser`     | `QuestionBrowser.vue`        | 题库浏览、筛选、编辑                                              |
| `/pdf-review/:id`       | `PdfReviewPage.vue`          | PDF 切题校对台                                                    |
| `/question-filter`      | `QuestionFilterPage.vue`     | 组卷筛选、排序、预览、导出                                        |
| `/test-records`         | `TestRecords.vue`            | 花名册、测试记录、快速听写、测试分析                              |
| `/settings`             | `SystemSettings.vue`         | 基础设置、题型/来源/知识树、名单管理、权限、审计、回收站、AI 设置 |
| `/about`                | `About.vue`                  | 版本信息                                                          |
| `/error-page`           | `ErrorPage.vue`              | 错误状态                                                          |

主要组件域：

- `analysis/`：学习分析图表、维度面板和详情抽屉。
- `question-browser/`、`question-filter/`、`question-fields/`：题库浏览、组卷和动态题型表单。
- `image-question-input/`、`pdf-import/`：图片题录入、PDF 导入和校对台。
- `test-records/`、`test-analysis/`：花名册矩阵、快速听写、打印和测试分析。
- `settings/`：系统设置、访问凭据、操作记录、回收站、版本恢复和 AI 设置。
- `metadata/`、`common/`：元数据管理和通用展示/编辑组件。

---

## 测试与质量

- 后端：Mocha + Chai + Supertest + Sinon，覆盖控制器、模型、路由、校验器和 PDF 服务。
- 前端：Vitest + Vue Test Utils，覆盖 views、components、composables、services、stores、utils 和样式约束。
- E2E：Playwright，覆盖核心冒烟流程、PDF 校对、打印分页、分析图和学生明细等。
- 契约：`docs/shared/question-validation-contract.json` 通过 `scripts/check-validation-contract.mjs` 与前后端同步检查。
- 性能：`frontend-src/scripts/check-bundle-size.mjs` 执行构建体积门禁；权威预算与实测值见 `docs/性能基线.md`。
- 技能治理：`scripts/check-skills.mjs`、`scripts/check-router-overlays.mjs` 和 `scripts/eval/skill-compliance/` 负责技能结构、路由 overlay 与评测。

---

## 文档与 AI 技能

文档索引见 `docs/README.md`。当前权威来源：

| 内容                | 位置                                        |
| ------------------- | ------------------------------------------- |
| 前端视觉规范        | `docs/design-spec.md`                       |
| 性能预算与基线      | `docs/性能基线.md`                          |
| 文档放置与规则治理  | `docs/README.md`、`docs/rule-governance.md` |
| Mock 造数           | `docs/mock数据填充方案.md`                  |
| 前后端字段/验证契约 | `docs/shared/`                              |
| 现行业务规格        | `docs/superpowers/specs/`                   |
| 活跃待办            | `docs/backlog/`                             |

项目级 Codex 技能位于 `.codex/skills/`，主要包括：

- `fakc-project-guide`：目录、约定、命令与联动范围。
- `backend-best-practices`：Express、Mongoose、错误处理、安全和测试。
- `vue-best-practices`、`frontend-testing`：Vue 3 架构、竞态、状态与测试。
- `css-best-practices`、`controls-best-practices`、`ui-design-language`：CSS 架构、输入控件和设计语言。
- `frontend-semantic-audit`：前端语义层级审计。
- `pdf-pipeline-guards`：PDF 导入、校对、队列和扫描页护栏。
- `fakc-skill-router-creator`：Skill Router overlay、章节路由和校验门禁。

---

## 项目约定

- 修改功能或修复 bug 前，先加载 `AGENTS.md` 路由中对应的项目技能。
- 禁止使用 git worktree；所有分支工作在主工作区完成。
- 禁止修改或提交 `.env`、密钥、令牌、代理订阅链接、节点凭据及个人隐私。
- 变更后按范围运行测试、lint、format 和构建检查；提交前优先运行 `bash scripts/ci-local.sh`。
- 文档中的文件清单、性能数字和规则必须来自当前工作区实测或唯一权威来源。
- 默认提交前缀：`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`。