# NumberCraft

**Repository Path**: he7/number-craft

## Basic Information

- **Project Name**: NumberCraft
- **Description**: 小小数匠（5～7 岁儿童 10 以内数感与加减法理解游戏）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小小数匠 · NumberCraft

这是依据 V1/V2 产品需求搭建的 H5/PWA 离线学习应用。

当前范围：

- 可复用内容运行时与 `.mathgame` 内容包格式；
- 本地儿童档案、学习事件、能力分数、错误降阶和复习占位接口；
- 本地每日计划：到期复习优先，最多安排 3 项任务，并按 1/3/7 天节奏复现已完成关卡；
- 六个完整可玩工坊：点点观察间 N01/N02（L001～L010）、数字轨道坊 N03/N04（L011～L020）、拆数木工台 N05/N06（L021～L030）、合数装配间 N07/N08（L031～L040）、加法搬运站 N09/N10（L041～L050）与减法修理铺 N11/N12（L051～L060），共 60 关；
- V2 新增六个 20 以内进阶工坊：十位建造站、二十轨道桥、凑十动力炉、破十修理场、策略机关屋和二十挑战塔（L061～L120），累计 120 关；
- 浏览器离线运行、JSON 导出、内容包构建/校验、静态打包。
- 可选跨设备账号：不登录时完全本地运行；登录后通过用户名 + 密码同步学习档案，不使用手机号或验证码。

功能核对见 [`FEATURE_CHECKLIST.md`](./FEATURE_CHECKLIST.md)，本轮代码审查、已修复问题和剩余风险见 [`AUDIT_REPORT.md`](./AUDIT_REPORT.md)。

## 运行

```powershell
npm run dev
```

打开 `http://localhost:4173`。所有学习数据仅保存在浏览器 `localStorage`，没有网络请求、登录、广告或第三方 SDK。

## 测试与打包

```powershell
npm test
npm run build
npm run package:game
npm run package:online
```

输出：

- `dist/`：可部署的离线 Web 原型；
- `C:\application\phpstudy_pro\WWW\www.numbercraft.com\release/`：线上部署版，默认使用 `/addons/numbercraft/version/1.0.2/` 和 `v=4.5.0` 资源路径；应用内容仍为当前 V2 构建；
- `artifacts/w01_flash_count_1.0.0.mathgame` ～ `artifacts/w06_subtract_repair_1.0.0.mathgame`：V1 六个游戏包的 ZIP 容器；
- `artifacts/w07_ten_builder_2.0.0.mathgame` ～ `artifacts/w12_challenge_20_2.0.0.mathgame`：V2 六个游戏包的 ZIP 容器；
- `artifacts/numbercraft-web-v2.0.0.zip`：V2 网页原型打包物。

本环境没有 Flutter/Android SDK，因此本次“初步打包测试”验证的是离线 Web 包和 `.mathgame` 内容包；Android APK 工程将在 Flutter 工具链可用后接入同一内容协议。

## 可选账号同步

后端模块已按 `C:\application\phpstudy_pro\WWW\xingshu\xsframe\app\hq_numbercraft\` 的 xsframe 模块结构提供，模块标识为 `hq_numbercraft`。安装模块后执行 `packages/install.php` 创建账号、令牌和云端档案表，API 默认地址为 `/hq_numbercraft/api/*.html`。H5 不登录时不会请求这些接口；注册或登录后，当前本地记录与云端记录自动合并，换设备登录同一账号即可继续。若后端地址不同，可在页面加载前设置 `window.NUMBERCRAFT_API_BASE`。

线上子目录发布：`npm run package:online` 会先构建并校验 `dist/`，再覆盖生成上述 `release/` 目录。根部 `index.html` 使用服务器要求的 `/addons/numbercraft/version/1.0.2/` 绝对路径，并同步生成对应的 `release/addons/numbercraft/version/1.0.2/` 资源镜像。上传 `release` 内部全部文件到服务器即可；可通过 `NUMBERCRAFT_ONLINE_BASE` 和 `NUMBERCRAFT_ONLINE_QUERY` 调整部署路径与查询版本。