# kaogongStudio

**Repository Path**: TZ0801/kaogong-studio

## Basic Information

- **Project Name**: kaogongStudio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Octopus Kaogong PWA

张鱼烧脑🐙开发的个人考公学习工作台。它是一套可安装、可离线、真实题库驱动的 PWA：题库、练习、判分、错题、计划、申论、时政和岗位记录都可以在本机完成，CloudBase 仅保留为未来可选的云端同步适配层。

## 功能概览

- React 19 + TypeScript + Vite 8
- 1900×1020 固定逻辑画布，随浏览器窗口整体等比缩放，不改变相对布局
- 连续滚动的 3D 环绕与侧向层叠卡片场景
- 系统、亮色、暗色主题循环切换
- 五套界面强调色
- 四张流体卡片独立材质设置：预设、自定义三色、不透明度、模糊与流动速度
- 完整毛玻璃材质设置浮层和实时预览
- PWA Manifest、Service Worker、离线应用外壳和更新提示
- 按 [2026 国考公共科目笔试大纲](https://www.forestry.gov.cn/c/www/gsgg/645383.jhtml) 组织行测六部分
- 离线内置 C-Eval 公务员科目 481 道题和 LogiQA 2.0 逻辑推理 180 道题，共 661 道
- 六部分专项练习、60 题综合套卷、即时判题和错题复盘
- 本地全文搜索题干、材料、选项、模块和来源，可直接定位题目
- 每日题量、训练时长、考试日期设置和真实进度统计
- 申论草稿自动保存、时政热点记录和岗位选报雷达
- 浏览器本地持久化，刷新或离线重新打开后仍可继续学习

## 环境要求

- Node.js `20.19+`，或 `22.12+`
- npm 10 或更高版本
- 推荐使用最新版 Chrome、Edge 或 Safari

## 快速启动

题库数据已经包含在仓库中，首次启动不需要重新下载或导入数据。

```bash
git clone https://github.com/zhangyushaonao/octopus-kaogong-pwa.git
cd octopus-kaogong-pwa
npm install
npm run dev
```

浏览器访问：

```text
http://127.0.0.1:4320/
```

开发服务器支持热更新。修改源码后，浏览器会自动刷新。

## 生产构建与本地预览

```bash
npm run build
npm run preview
```

生产预览地址：

```text
http://127.0.0.1:4321/
```

如需验证 PWA 安装、Service Worker 和离线缓存，建议使用生产构建后的 `npm run preview`。

## 可用命令

| 命令 | 作用 |
| --- | --- |
| `npm run dev` | 在 `127.0.0.1:4320` 启动开发服务器 |
| `npm run build` | 执行类型检查并生成生产文件到 `dist/` |
| `npm run preview` | 在 `127.0.0.1:4321` 预览生产构建 |
| `npm run typecheck` | 执行 TypeScript 类型检查 |
| `npm run lint` | 执行 ESLint |
| `npm run test` | 执行 Vitest 测试 |
| `npm run check` | 依次运行类型检查、ESLint、测试和生产构建 |
| `npm run data:import:ceval` | 重新下载并校验 C-Eval 公务员题目数据 |

## 题库数据

内置题目来自：

- [C-Eval](https://github.com/hkust-nlp/ceval) `civil_servant` 科目全部 481 道题
- [LogiQA 2.0](https://github.com/csitfun/LogiQA2.0) 中文逻辑推理 180 道题

两套数据均遵循 CC BY-NC-SA 4.0。C-Eval 原始科目没有提供国考六部分子类，本项目使用可审计的本地关键词规则生成导航分类，不修改原始题干、选项和答案。详细归属和许可说明见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

通常不需要执行数据导入命令。如果确实需要重新获取 C-Eval 数据：

```bash
npm run data:import:ceval
```

导入脚本会校验 dev 5、val 47、test 429 三个分片，总数必须严格等于 481，否则会停止写入。

## 本地数据与隐私

学习设置、作答结果、错题、申论草稿、时政和岗位记录保存在当前浏览器的本地存储中。项目不会展示伪同步状态，也不会生成虚假的学习成绩。

当前默认配置为：

```env
VITE_SYNC_PROVIDER=local
```

CloudBase 尚未接入。未来云端能力会通过独立适配器扩展，不影响现有本地学习能力。

## 质量检查

提交代码前运行：

```bash
npm run check
```

该命令会依次执行 TypeScript、ESLint、Vitest 和生产构建。

## 开源许可

项目代码使用 [MIT License](./LICENSE)。内置第三方题库数据适用各自的 CC BY-NC-SA 4.0 许可，详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。