# Mech1Cloud

**Repository Path**: gcoulu/Mech1Cloud

## Basic Information

- **Project Name**: Mech1Cloud
- **Description**: 岚序计划手机客户端 基于 uni-app x 构建的跨平台班级应用，面向 H5、微信小程序、Android、iOS 与 HarmonyOS 场景，提供首页聚合、班级日程、文档浏览、本地工具、公告提醒与后台管理等能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mech1Cloud / 机制一班云

基于 `uni-app x` 构建的跨平台班级应用，面向 H5、微信小程序、Android、iOS 与 HarmonyOS 场景，提供首页聚合、班级日程、文档浏览、本地工具、公告提醒与后台管理等能力。

## 项目概览

- 当前版本：`1.0.1`
- 技术栈：`uni-app x`、`Vue 3`、`UTS`、`uniCloud`
- 启动页：`pages/index/index`
- 主壳页：`pages/tabs/layout`
- 自定义导航：统一使用 `navigationStyle: custom`
- 当前定位：班级信息聚合与轻协作服务平台

## 核心能力

### 前台能力

- 首页聚合：每日一句、新闻中心、作业统计、模块排序与可见性配置
- 日程服务：班级日程浏览、自动关闭、日历联动
- 文档与工具：文档列表、云端工具、本地工具统一入口
- 更新与公告：更新日志页、组件档案页、公告弹窗与历史公告页
- 主题体验：日夜模式、背景色切换、动效开关、部分岚序风格浮层

### 本地工具

- 番茄钟
- 闹钟
- 备忘录
- 课程表
- 科学计算器
- 班级日历
- 通讯录
- 跳一跳
- 木鱼
- `mech1-time-filter-picker` 示例页

### 后台能力

- 日程、文档、工具、公告等内容管理
- 首页模块配置与每日一句配置
- 课程表模板与节次管理
- 小游戏账号、记录与统计管理
- 管理员二次验证、排序保存与批量导入

## 目录结构

```text
Mech1Cloud/
├─ App.uvue
├─ main.uts
├─ pages.json
├─ manifest.json
├─ pages/
│  ├─ index/
│  ├─ tabs/
│  ├─ template/
│  └─ web/
├─ components/
│  ├─ tabs/
│  ├─ home/
│  ├─ common/
│  ├─ admin/
│  └─ template/
├─ store/
├─ utils/
├─ static/
├─ screenshots/
├─ uniCloud-alipay/
│  ├─ cloudfunctions/
│  └─ database/
├─ changelog.md
└─ Privacy_Policy.md
```

## 主要页面

- `pages/index/index`：启动动画与入口跳转
- `pages/tabs/layout`：应用主壳，承载五个 Tab 与首页聚合布局
- `pages/template/template`：本地工具统一承载页
- `pages/web/web`：外链与网页内容承载页
- `pages/tabs/more/admin/admin`：后台管理页
- `pages/tabs/more/changelog/changelog`：更新日志页
- `pages/tabs/more/announcements/announcements`：公告历史页

## 技术与约定

- 页面与组件以 `.uvue` 为主，逻辑工具以 `.uts` 为主
- 项目避免使用浏览器专有 API，统一使用 `uni` 提供的跨平台能力
- 样式使用 `SCSS`，并遵循类选择器优先的 uni-app x 约束
- 云端能力位于 `uniCloud-alipay/`，包含云函数、数据表结构与索引定义
- `uni_modules/` 视为第三方模块目录，除 `mech1` 自有模块外不要直接修改

## 快速开始

### 环境准备

- 安装 HBuilderX，建议使用支持 uni-app x 的较新版本
- 准备对应平台运行环境：H5 浏览器、微信开发者工具、Android/iOS/Harmony 真机或模拟器
- 如需云端功能，请准备已绑定的 uniCloud 服务空间

### 本地运行

1. 使用 HBuilderX 打开项目根目录 `Mech1Cloud`
2. 检查 `manifest.json`、`pages.json` 与 uniCloud 服务空间配置是否正确
3. 按目标平台运行：
   - H5：运行到浏览器
   - 微信小程序：运行到微信开发者工具
   - App：运行到 Android / iOS 基座
   - HarmonyOS：运行到对应设备或环境

### 云端相关

- 云函数目录：`uniCloud-alipay/cloudfunctions/`
- 数据表结构：`uniCloud-alipay/database/`
- 首次接入时，请先将 schema、index 与云函数部署到绑定的服务空间

## 常用文档

- 项目更新记录：`changelog.md`
- 页面内更新记录源：`utils/changelog-local.uts`
- 隐私政策：`Privacy_Policy.md`
- 项目规则：`AGENTS.md`

## 当前版本重点

`1.0.1` 主要围绕跳一跳积分上传与排行榜统计异常做稳定性修复，补齐单局记录唯一标识、服务端去重、旧客户端兼容指纹与时间窗口校验，让单局成绩、日榜、周榜与总榜重新共用一致的统计口径，并为后续异常数据排查保留更可靠的记录基础；同时把 `uni-app x` 样式隔离策略从 `1.0` 升级到 `2.0`，统一当前项目的样式隔离基线。

## 近期更新整理

### `1.0.1`：小游戏积分上报与排行榜统计修复

- 跳一跳每局结算改为上传稳定的本地记录 ID 与真实对局时间，避免上传瞬间时间覆盖结算时间
- 云函数新增按 `userId + clientRecordId` 的去重逻辑，重复请求会直接复用已有记录，避免同一局重复计分
- 兼容旧客户端未携带 `clientRecordId` 的情况，自动退化为基于时间、分数与完美落点次数的兼容指纹
- 为 `playedAt` 增加允许时间窗口校验，减少异常未来时间或过旧时间混入当前日榜、周榜
- 跳一跳记录表补齐 `clientRecordId` 字段与唯一索引，为后续榜单稳定性和异常数据排查提供更可靠的基础
- 将 `uni-app x` 样式隔离策略从 `1.0` 升级为 `2.0`，统一页面与组件的样式隔离基线，降低跨组件样式串扰风险

### `0.3.3.Alpha`：后台排序、鉴权与公告弹窗稳定性修复

- 修复后台管理员密码过期后保存、删除、排序和批量操作被中断的问题，改为重新验证后继续当前操作
- 重构后台内容排序保存逻辑，修复倒序保存后顺序翻转、新增内容未稳定出现在首项等问题
- 修复公告禁用后仍弹出、新公告不弹出、多条公告顺序异常与已读状态失真的问题
- 首页启动页补做轻量版启动动画勾选态与低配设备自动降级逻辑，减少首屏掉帧
- 修复 `mech1-lanxu-list-motion` 在设置页中的运行时类型告警与空指针问题

### `0.3.1.Alpha`：阶段整合与体验收口

- 默认启用岚序 UI，首页补齐每日一句、新闻中心、作业统计、模块编排与横屏时钟工作台联动
- 日程新增时间段、全天日期、自动关闭与加入日历开关，本地工具同步加入班级日历视图
- 后台补齐首页模块管理、模板批量导入、访问拦截和浮层留白整理，降低长表单压迫感
- 公告弹窗支持首页与工具页连续阅读，网页 HTTPS 检查时机、复制链接与内嵌入口逻辑统一收口
- `mech1-time-filter-picker` 补齐文档、示例、截图说明与组件档案，达到可发布状态

## 开发注意事项

- 不要修改 `uni_modules/` 下的第三方模块源码
- 不要使用 `window`、`document` 等 Web 专有对象
- 静态资源统一放在 `static/`
- 可插件化的能力优先沉淀为 `mech1` 前缀模块
- 更新版本说明时，优先同步页面内更新日志与 `changelog.md`

## 后续建议

- 持续完善 `README.md` 中的截图、部署说明与平台差异说明
- 对前后端数据结构补充更明确的类型文档
- 为常见云函数与后台配置补齐操作手册