Files
OUCMirror-WebUI/plan.md
T

287 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 已确定的方向
- 使用 Vue 3、TypeScript 和 Vite 开发前端。
- 使用 vue-i18n,所有界面文案通过语言键引用语言文件。
- 第一版支持简体中文(`zh-CN`)和英文(`en-US`)。
- 支持亮色、暗色以及跟随系统的主题设置。
- 界面配色沿用爱特工作室官网:浅色强调蓝 `#0969DA`,暗色强调蓝 `#58A6FF`;完整色值见 [DESIGN.md](DESIGN.md)。
- 以紧凑、清晰的镜像列表为首页主体,融入中国海洋大学的海洋特色。
- 借鉴机场航班信息屏,在同步状态与时间字段变化时使用向上滚动动效。
- 根目录的 `素材/` 仅用于本地素材整理,不纳入 Git。
## 界面设计
### 布局与视觉
首页采用宽列表、窄侧栏的布局。顶部保留站点标识、主要导航、语言选择和主题切换,主体优先展示搜索与镜像列表。
```text
校徽 / MirrorOUC 使用帮助 公告 同步状态 关于 语言 主题
中国海洋大学软件镜像源
搜索镜像…… 全部 / 发行版 / 软件仓库 / 其他
镜像名称 最近同步 / 下次同步 Size / Status │ 站点公告
ubuntu 12 分钟前 / — 3.4 TB / 同步中 │ 常用下载
debian 35 分钟前 / 25 分钟后 4.2 TB / 已同步 │ 使用帮助
archlinux 58 分钟前 / 即将开始 1.3 TB / 等待同步│ 相关链接
…… │
中国海洋大学软件镜像源(MirrorOUC)由中国海洋大学爱特工作室承建。
```
上述名称、状态和时间仅用于说明布局,不表示本站实际提供的镜像或运行状态。
亮色主题使用白底、浅灰面板和蓝色重点元素;暗色主题使用 `#0D1117` 背景与 `#161B22` 面板。文字、边框及页脚与爱特工作室官网主题保持一致,品牌通过海大校徽呈现。
主体采用规整表格、细分隔线和克制的圆角。避免大面积渐变、玻璃效果、堆叠装饰卡片、空泛标语及无意义的小字脚注。正文优先使用系统字体,镜像名称与时间数字可使用等宽字体或等宽数字。
移动端同样保留三列及统一轮换机制;帮助、下载和公告入口仍应易于访问。
### 同步动效
- 后两列表头和条目共用一个 5 秒周期,在「最近同步 + Size」与「下次同步 + Status」之间切换。
- 表头每轮向上滚动一次;条目随机滚动 3~6 次,在约一秒内落定至正确值。
- 保持行高、列宽和列表顺序稳定,不因后台状态刷新自动重排列表。
- 同步中的条目使用淡蓝色背景,同步失败的条目使用淡红色背景,文字均沿用普通颜色。
- 支持系统的减少动态效果设置,后台标签页暂停动画和频繁刷新。
- 保证键盘操作、文本选择、屏幕阅读器和英文布局可用,状态不能只依赖颜色表达。
独立的同步状态页面可进一步提供大屏模式,集中展示正在执行和即将执行的任务。首页保持便于查找和点击的列表形式。
## 功能规划
### 公共网站
| 功能 | 计划内容 |
| --- | --- |
| 镜像列表 | 按名称、别名和中文描述搜索,按分类筛选,进入目录或查看帮助 |
| 同步状态 | 展示当前状态、最近成功同步时间、下次计划时间及可获得的镜像大小 |
| 使用帮助 | Markdown 文档、配置示例、代码高亮与复制 |
| 常用下载 | 常见发行版安装镜像和软件安装包的下载入口 |
| 站点公告 | 公告列表、详情、置顶和维护通知 |
| 关于与友链 | 承建信息、联系方式和相关站点链接 |
| 主题与语言 | 独立选择并保存主题、界面语言 |
同步状态与文件可用性分别表达。一次同步失败不直接等同于现有镜像文件不可下载,页面同时保留最近成功同步时间。进度百分比、传输速率等信息,仅在具有可靠数据来源时展示。
### 管理后台
| 模块 | 计划内容 |
| --- | --- |
| 公告与帮助 | Markdown 编辑、预览、草稿、发布、置顶及多语言内容 |
| 镜像信息 | 名称、分类、描述、帮助关联、公开状态与下载入口 |
| 同步配置 | 上游、同步方式、同步间隔、重试、超时及并发设置 |
| 任务操作 | 手动触发、停止、执行结果、日志和同步历史 |
| 站点设置 | 网站头像/标识、明暗主题 Logo、友链、联系方式和承建信息 |
| 账号与记录 | 管理员登录、内容与运维权限划分、操作记录 |
镜像是否公开展示与同步任务是否启用分别管理。Markdown 渲染应过滤不安全内容,公开接口只返回适合对外展示的信息。
## 国际化约定
### 界面文案
公开网站与管理后台统一使用 vue-i18n。导航、按钮、标题、占位提示、工具提示、校验错误、确认弹窗、空状态、加载状态、无障碍标签及页面标题,都必须从语言文件读取。
使用稳定、语义化的语言键,例如:
```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
</script>
<template>
<button>{{ t('common.save') }}</button>
<span>{{ t('mirrors.status.syncing') }}</span>
</template>
```
语言文件按语言和功能模块划分,以下为计划结构:
```text
src/locales/
├── index.ts
├── zh-CN/
│ ├── common.ts
│ ├── site.ts
│ ├── mirrors.ts
│ ├── announcements.ts
│ └── admin.ts
└── en-US/
├── common.ts
├── site.ts
├── mirrors.ts
├── announcements.ts
└── admin.ts
```
例如,`zh-CN/mirrors.ts` 导出 `mirrors` 命名空间对应的内容:
```ts
export default {
status: {
syncing: '同步中',
success: '已同步',
},
nextSync: '下次同步:{time}',
}
```
对应的 `en-US/mirrors.ts`:
```ts
export default {
status: {
syncing: 'Syncing',
success: 'Synced',
},
nextSync: 'Next sync: {time}',
}
```
开发时遵循以下规则:
- 组件中不硬编码可翻译文案,也不通过拼接词语生成句子;使用完整句子的参数插值。
- 使用 TypeScript 约束语言键,并检查各语言的键、插值参数是否一致。
- 使用 vue-i18n 和 `Intl` 格式化日期、相对时间、数字及复数,不手动拼接“分钟前”等单位。
- 后端返回稳定的状态码、错误码、参数和时间戳,前端映射为本地化文案。
- 不直接将后端原始错误文本展示为公共页面提示;运维日志在管理后台单独查看。
- 软件名称、仓库标识、网址、文件名、命令和用户输入保持原值。
- 滚动组件应适应不同语言的文字长度,并在减少动态效果模式下直接更新文本。
### 语言选择与回退
语言选择顺序为:用户保存的选择 → 匹配浏览器语言 → 简体中文。浏览器区域语言需映射到支持的语言,例如 `en-GB` 匹配 `en-US`。
缺少界面译文时回退至简体中文,同时在开发和检查流程中暴露缺失项。切换语言后同步更新文档的 `lang` 属性、页面标题和相关无障碍标签。
语言偏好与主题偏好独立保存。语言与时区也分别处理,切换语言不应改变时间戳所代表的实际时刻;需要展示固定调度时间时明确标注时区。
### 动态内容
公告、帮助文档、镜像介绍和可编辑站点文案按语言保存于内容数据中,不写入前端语言包。缺少译文时展示原始语言内容,并标明内容语言。
## 建议技术架构
Vue、TypeScript、Vite 和 vue-i18n 已确定;以下后台组件与部署方式作为当前推荐方案,实施时结合服务器现状确认。
| 部分 | 技术建议 | 用途 |
| --- | --- | --- |
| 公共网站 | Vue 3 + TypeScript + Vite | 镜像列表、内容页面和局部动效 |
| 管理后台 | Vue 3 + Naive UI | 表格、配置表单、编辑与管理操作 |
| 国际化 | vue-i18n + Intl | 文案、数字、日期和相对时间 |
| 管理服务 | Go + Gin | 内容管理、权限、tunasync 适配和配置发布 |
| 业务存储 | SQLite | 公告、帮助、站点配置、账号和操作记录 |
| 文件与入口服务 | Nginx | 静态前端、镜像文件、目录浏览和 API 反向代理 |
| 同步引擎 | tunasync Manager / Worker | 镜像同步、任务控制和状态上报 |
| 进程管理 | systemd | 服务启动、日志及重启管理 |
```mermaid
flowchart LR
U[访客 / 管理员] --> N[Nginx]
N --> W[公共前台 / 管理后台]
N --> F[镜像目录与文件]
N --> A[MirrorOUC 管理服务]
A --> D[(业务数据库)]
A --> T[tunasync Manager]
T --> K[tunasync Worker]
K --> F
```
镜像文件由 Nginx 直接提供,支持包管理器访问与断点续传。网站路由、业务 API 和镜像路径需明确划分,前端路由回退不能拦截镜像文件请求或将不存在的文件返回为首页。
管理服务使用独立业务数据库,不直接修改 tunasync 的内部数据库。tunasync 管理接口仅通过本机或内部网络访问,由管理服务完成鉴权、权限检查和操作记录。
应用使用专用低权限账号运行。需要写入同步配置时,仅授权指定配置目录和必要操作;SSH 密钥、访问凭据和私有部署信息不写入仓库。
## tunasync 对接
### 状态与任务控制
上游当前提供 `/jobs`、Worker 查询和 `/cmd` 等接口,并支持配置重载。实施前需要核对服务器实际安装版本,建立统一适配层,将上游状态转换为前端使用的数据结构。
管理服务集中采集并缓存同步状态,前端初期采用约 15 秒一次的轮询。采集失败时保留最近一次有效数据并显示更新时间,避免将连接故障误显示为所有镜像同步失败。
任务操作需要区分“指令已提交”与“任务实际执行结果”,通过后续状态确认执行情况。日志查看与长期同步历史需要另外采集和保存,并设置保留期限。
### 配置发布
可视化配置编辑通过以下流程应用到 Worker:
```text
编辑草稿 → 校验 → 查看差异 → 保存版本 → 应用并重载 → 检查结果
↓
失败时支持回滚
```
配置应区分草稿、已应用版本和实际运行结果。发布时采用备份与原子替换,并检测文件是否已被其他操作修改,防止覆盖服务器上的人工变更。具体配置写入与重载方式需结合现有部署确认。
### 调度边界
tunasync 的原生 `interval` 表示同步完成后等待指定分钟数再执行,不等同于固定时刻调度。
首版建议优先支持原生间隔调度。如果需要“每天凌晨两点”或“仅夜间同步”,需要补充独立的调度逻辑,处理时区、并发、重复触发和失败重试,并确保每个任务只有一个调度来源。
固定时刻调度是否进入首版,尚待确定。
## 开发计划
### 第一阶段:基础工程与界面原型
- 初始化 Vue、TypeScript、Vite、路由和国际化结构。
- 建立亮暗主题变量及基础组件。
- 完成首页、搜索筛选、移动端布局和同步信息滚动动效。
- 使用明确标识的演示数据覆盖正常、同步中、失败、暂停和未知状态。
- 检查中英文布局、键盘操作和减少动态效果模式。
### 第二阶段:真实数据与内容管理
- 核对服务器环境、tunasync 版本和现有配置。
- 建立管理服务与状态适配层,接入真实镜像列表。
- 完成公告、帮助、常用下载和站点设置。
- 完成后台登录、内容编辑与多语言内容存储。
- 配置镜像文件服务、网站路由与部署流程。
### 第三阶段:运维管理
- 完成可视化同步配置、配置版本与发布流程。
- 完成任务操作、结果确认、日志及同步历史。
- 实现确认纳入范围的调度策略。
- 验证配置错误、重载失败、状态断连及回滚场景。
## 验证重点
- 切换语言后,公开网站与后台均无遗漏的界面文案,语言键和参数完整。
- 长英文、长镜像名、窄屏以及亮暗主题下均能正常阅读和操作。
- 状态刷新不打断搜索、点击和键盘焦点,减少动态效果设置生效。
- 状态过期、无数据和同步失败能够正确区分。
- Markdown 内容渲染、管理权限与配置发布经过针对性验证。
- 镜像文件链接、错误码和断点续传行为符合实际下载需求。
## 仓库与素材
根目录 `素材/` 已通过 `.gitignore` 忽略,原始素材不提交到 Git。实际使用的发布资源应按需整理到应用资源目录,避免整体复制原始素材文件夹。
前端预览已实现,依赖版本、开发命令、构建及校验方式见 [README.md](README.md)。当前数据均为演示数据;真实接口、服务配置和部署文档将在后端接入阶段补充。
## 待明确事项
- 首版是否需要固定时刻或指定时间窗口的同步调度。
- 服务器现有服务、目录结构、tunasync 版本及配置管理方式。
- 正式访问域名、可用线路和首批镜像范围。
- 网站标识、联系方式、友链及首批帮助文档内容。
## 参考资料
- [tunasync 项目](https://github.com/tuna/tunasync)
- [tunasync Worker 配置说明](https://github.com/tuna/tunasync/blob/master/docs/zh_CN/configs.md)
- [tunasync 配置重载与操作说明](https://github.com/tuna/tunasync/blob/master/docs/zh_CN/tips.md)
- [吉林大学开源镜像站](https://mirrors.jlu.edu.cn/)
- [清华大学开源软件镜像站](https://mirrors.tuna.tsinghua.edu.cn/)
- [中国科学技术大学开源软件镜像](https://mirrors.ustc.edu.cn/)
参考站用于研究功能和信息布局,MirrorOUC 的视觉与交互围绕中国海洋大学品牌单独设计。