refactor(frontend): 前端架构重构与工程化升级（TypeScript + Pinia + Router + i18n） by MF-B · Pull Request #1 · MF-B/MineDock

MF-B · 2026-03-29T04:06:05Z

主要改动

前端技术栈升级与结构重组

将前端入口由 JavaScript 迁移为 TypeScript。
引入 Pinia 统一管理容器状态与操作流程。
引入 Vue Router，完成页面级视图拆分。
统一 API 调用层，增加类型定义与错误处理路径。

界面与交互重构

应用壳层调整为侧边栏 + 顶栏 + 主内容区的布局。
新增响应式侧边栏交互（桌面伸缩、移动端抽屉与遮罩）。
新增顶栏语言切换下拉菜单。
容器列表改为卡片化展示，保留创建、启停、删除等核心操作。
日志输出与状态提示路径统一，交互反馈更一致。

国际化支持完善

接入 vue-i18n 初始化与全局注册。
补充中英文语言包，覆盖容器列表、弹窗、状态提示、导航与顶栏文案。
默认中文，英文作为回退语言。

代码质量与格式化体系

引入 ESLint Flat Config 与 Prettier 配置。
增加 lint、lint:fix、format、format:check 脚本。
Task 中补充前端安装、格式检查、Lint、构建任务，并接入全局任务链路。

CI/CD 与发布流程优化

CI 中增加前端依赖安装、格式检查、Lint 与构建步骤。
Release 流程增加前端质量检查与一次性构建，随后进行多平台产物打包。
补充仓库忽略项并更新相关文档标准与契约说明。

影响范围

前端应用初始化、路由、状态管理、页面结构、样式主题与交互逻辑。
项目级任务编排、CI 校验顺序与发布产物生成流程。
文档规范与开发协作约束。

Copilot

Pull request overview

This PR performs a major frontend refactor and engineering upgrade for MineDock: migrating the app to TypeScript, introducing Pinia + Vue Router + vue-i18n, and wiring in lint/format tooling with CI/Task integration.

Changes:

Migrate frontend entry + API layer to TypeScript and add Pinia store + Router-based view structure.
Add i18n initialization with zh-CN/en-US locale packs and a top-bar language switcher.
Introduce ESLint (flat config) + Prettier scripts, add Taskfile tasks, and extend CI/Release workflows to run format/lint checks.

Reviewed changes

Copilot reviewed 31 out of 34 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
frontend/vite.config.js	Adds dev server proxy for `/api`.
frontend/tsconfig.node.json	Adds node/TS build config (currently mismatched with existing Vite config filename).
frontend/tsconfig.json	Adds main TS config with project references.
frontend/src/views/ContainerList.vue	New container list view with create/toggle/delete flows + modal UI.
frontend/src/stores/containers.ts	New Pinia store encapsulating instance operations and output logging.
frontend/src/router/index.ts	Adds router with `/` route to the container list view.
frontend/src/main.ts	New TS entry wiring Pinia + Router + i18n.
frontend/src/main.js	Removes old JS entry.
frontend/src/locales/zh-CN.json	Adds zh-CN translations.
frontend/src/locales/en-US.json	Adds en-US translations.
frontend/src/i18n.ts	Adds vue-i18n initialization and message schema typing.
frontend/src/env.d.ts	Adds TS module declaration for `.vue`.
frontend/src/components/TopBar.vue	Adds language-switch dropdown UI.
frontend/src/components/Sidebar.vue	Adds responsive sidebar UI (mobile overlay + desktop expand/collapse).
frontend/src/assets/main.css	Reworks global theme variables and layout styling.
frontend/src/api/index.ts	New TS API wrapper and typed Instance interface.
frontend/src/api/index.js	Removes old JS API wrapper.
frontend/src/App.vue	Replaces MVP single-page UI with shell layout + `<router-view>`.
frontend/package.json	Adds deps (pinia/router/i18n) and lint/format scripts + toolchain deps.
frontend/package-lock.json	Locks new dependency graph (includes Node engine constraints for ESLint packages).
frontend/index.html	Switches app entry to `main.ts` and updates title.
frontend/eslint.config.js	Adds ESLint flat config for TS/Vue.
frontend/.prettierrc.json	Adds Prettier config.
frontend/.prettierignore	Adds Prettier ignore rules.
docs/ops_engineering_standards.md	Updates ops/CI engineering standards text.
docs/domain_instance_lifecycle.md	Simplifies lifecycle doc and links to API contracts doc.
docs/02_API_Contracts.md	Adds API contract doc for instance lifecycle endpoints.
docs/01_Frontend_Standards.md	Adds frontend standards (i18n + CSS variables, etc.).
docs/01_Backend_Standards.md	Adds backend standards (error JSON example currently inconsistent with implementation).
docs/00_Root_Context.md	Updates project scope/boundaries + directory layout; contains a typo.
Taskfile.yml	Adds frontend fmt/lint tasks and global lint wiring.
.gitignore	Adds agent-related ignore entries.
.github/workflows/release.yml	Adds frontend fmt/lint checks in release workflow.
.github/workflows/ci.yml	Runs global fmt + lint checks in CI workflow.

Files not reviewed (1)

frontend/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-29T04:09:40Z

frontend/eslint.config.js

+        parser: tsParser,
+        project: "./tsconfig.json",
+        tsconfigRootDir: import.meta.dirname,
+        sourceType: "module",
+        ecmaVersion: "latest",


eslint.config.js uses import.meta.dirname for tsconfigRootDir. This property is not available in all Node 20 runtimes and can cause ESLint to crash in CI/local. Prefer deriving an absolute path from import.meta.url (via fileURLToPath/path.dirname) or use process.cwd() if the config is always run from the frontend directory.

Copilot · 2026-03-29T04:09:40Z

frontend/src/api/index.ts

+  const resp = await fetch(`${BASE_URL}${path}`, {
+    headers: { "Content-Type": "application/json" },
+    ...options,


The request() helper overwrites headers with a fixed { "Content-Type": "application/json" } and then spreads options. If callers pass options.headers, it will replace the entire header object (dropping Content-Type) rather than merging. Consider merging default headers with options.headers so custom headers can be added without accidentally removing defaults.

Suggested change

const resp = await fetch(`${BASE_URL}${path}`, {

headers: { "Content-Type": "application/json" },

...options,

const { headers, ...restOptions } = options;

const resp = await fetch(`${BASE_URL}${path}`, {

...restOptions,

headers: {

"Content-Type": "application/json",

...(headers ?? {}),

},

Copilot · 2026-03-29T04:09:41Z

frontend/src/stores/containers.ts

+    } catch (err) {
+      printError(err as Error);
+      return false;
+    }


Several catches cast err as Error and then read .message. If a non-Error value is thrown (common with fetch/third-party libs), this will print ERROR: undefined and lose context. Consider normalizing unknown errors (e.g., err instanceof Error ? err : new Error(String(err))) before calling printError.

Copilot · 2026-03-29T04:09:41Z

frontend/src/components/Sidebar.vue

+        <a href="#" class="menu-item active" @click.prevent>
+          <div class="menu-icon">
+            <svg viewBox="0 0 24 24" fill="currentColor">
+              <!-- 象征“容器/集装箱”的图标 -->
+              <path d="M4 8h16v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V8zm0-4h16v2H4V4z" />
+            </svg>
+          </div>
+          <div class="menu-text">{{ $t("sidebar.containerList") }}</div>
+        </a>


Sidebar navigation uses <a href="#" @click.prevent> even though Vue Router is introduced in this refactor. Using <RouterLink> (or a <button> when it isn't a real navigation) avoids dummy hrefs, improves accessibility, and keeps navigation consistent with router state (active class, history, etc.).

Copilot · 2026-03-29T04:09:41Z

.github/workflows/release.yml

+      - name: Run frontend format checks
+        run: task frontend:fmt
+
+      - name: Run frontend lint checks
+        run: task frontend:lint
+
      - name: Build frontend once
        run: task frontend:build


The added frontend fmt/lint steps can fail under Node "20" because some ESLint dependencies in package-lock.json require Node >=20.19.0. Consider pinning setup-node to >=20.19.x for the release workflow (or adjust the ESLint dependency versions to match the Node version constraint).

Copilot · 2026-03-29T04:09:42Z

frontend/package-lock.json

+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.13.0 || >=24"
+      }


This lockfile entry requires Node ^20.19.0 || ^22.13.0 || >=24, which will cause npm install to fail on Node 20.0.x (including GitHub Actions setup-node: 20). Align CI/runtime Node versions accordingly or pin toolchain versions that support the intended Node baseline.

Copilot · 2026-03-29T04:09:42Z

.github/workflows/ci.yml

+      - name: Run formatting checks
        run: task fmt

+      - name: Run lint checks
+        run: task lint


The new lint/format steps can fail under the configured Node "20" because the newly added ESLint toolchain in frontend/package-lock.json declares engines like ^20.19.0 || .... Consider pinning the workflow Node version to >=20.19.x (or downgrading ESLint deps to versions compatible with Node 20.0.x).

Copilot · 2026-03-29T04:09:42Z

docs/00_Root_Context.md

+- 容器的生命周期管理与资源配额调度
+- 容器内游戏服务器的快速安装与运行
+- 在线终端交互与控制指令下发
+- 游戏数据的持久化与灾灾备 (快照、备份与回档)


Typo: "灾灾备" looks like a duplicated word. If this is meant to be "灾备" (disaster recovery) or "容灾备份", please correct to avoid confusion in the project scope description.

Suggested change

- 游戏数据的持久化与灾灾备 (快照、备份与回档)

- 游戏数据的持久化与灾备 (快照、备份与回档)

Copilot · 2026-03-29T04:09:42Z

docs/01_Backend_Standards.md

+## 编码质量与规范
+- **代码格式化与校验**：`go fmt` 与 `go vet`
+- **错误处理**：
+  - 核心逻辑层要求显式返回 `error`，并在合适的网络层封装为统一规范的 JSON HTTP 响应体（如 `{"status": "error", "message": "..."}`）。


The error response example uses {"status": "error", "message": "..."}, but the current backend handlers actually serialize errors under the error field (e.g., {"status":"error","error":"..."}). Please align this doc example with the implemented contract to avoid misleading API consumers.

Suggested change

- 核心逻辑层要求显式返回 `error`，并在合适的网络层封装为统一规范的 JSON HTTP 响应体（如 `{"status": "error", "message": "..."}`）。

- 核心逻辑层要求显式返回 `error`，并在合适的网络层封装为统一规范的 JSON HTTP 响应体（如 `{"status": "error", "error": "..."}`）。

Copilot · 2026-03-29T04:09:42Z

frontend/tsconfig.node.json

+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["vite.config.ts"]


tsconfig.node.json only includes "vite.config.ts", but this repo currently has vite.config.js (no vite.config.ts). This makes the Node TS project reference effectively empty and can break typechecking/linting expectations for the Vite config. Either rename/migrate the Vite config to vite.config.ts, or update the include to match the actual filename(s).

MF-B added 12 commits March 26, 2026 23:21

docs: 重构了项目文档

40b7c53

style: 修改前端背景

fa92cdc

style: 为前端添加侧边栏, 并添加顶部标题

613b1a0

feat(ui): 将前端重构为卡片式风格并添加机械动力风格

8b06ac7

refactor: 重构全局样式系统并引入语义化变量

e735888

feat: 引入 i18n 国际化支持并完成基础文案适配

0a00c15

chore: 迁移项目至 TypeScript

6b1ed99

refactor: 引入 Pinia 与 Vue Router，拆分容器列表视图并修复启停提示逻辑

0495f47

refactor(frontend): 引入 ESLint + Prettier 并接入 Task 质量检查

fd93b42

style(frontend): 全量格式化前端代码并统一风格

2285460

chore: 将前端格式化与 Lint 检查接入 CI/CD 流程

e85ace9

feat(frontend): 添加包含多语言切换功能的全局顶栏

d1f9175

Copilot AI review requested due to automatic review settings March 29, 2026 04:06

Copilot started reviewing on behalf of MF-B March 29, 2026 04:06 View session

Copilot AI reviewed Mar 29, 2026

View reviewed changes

chore: 升级前端依赖并完善导航与请求错误处理

c7f44e7

MF-B merged commit 1cab4a4 into main Mar 29, 2026
2 checks passed

MF-B deleted the refactor/frontend branch April 4, 2026 15:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(frontend): 前端架构重构与工程化升级（TypeScript + Pinia + Router + i18n）#1

refactor(frontend): 前端架构重构与工程化升级（TypeScript + Pinia + Router + i18n）#1
MF-B merged 13 commits intomainfrom
refactor/frontend

MF-B commented Mar 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- 游戏数据的持久化与灾灾备 (快照、备份与回档)
	- 游戏数据的持久化与灾备 (快照、备份与回档)

	- 核心逻辑层要求显式返回 `error`，并在合适的网络层封装为统一规范的 JSON HTTP 响应体（如 `{"status": "error", "message": "..."}`）。
	- 核心逻辑层要求显式返回 `error`，并在合适的网络层封装为统一规范的 JSON HTTP 响应体（如 `{"status": "error", "error": "..."}`）。

Conversation

MF-B commented Mar 29, 2026

主要改动

影响范围

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants