Vue3 Frontend Development And Integration

Page Guide

Use CasesFor developing Vue3 admin pages, integrating backend APIs, maintaining OpenAPI types, and running frontend-backend integration checks.

Source LocationThe Vue3 admin console is located in the `vue3/` directory of the source repository; the legacy Vue2 admin console is in `vue/`.

Core Commands`npm run dev`, `npm run dev:mock`, `npm run openapi`, `npm run verify:integration`.

Acceptance CriteriaPages run correctly, API contracts are consistent, Mock and real APIs match, and E2E integration checks pass.

1. Directory Structure

Directory	Purpose
vue3/src/views	Page entries, organized by business module
vue3/src/api	API request wrappers
vue3/src/router	Routes, fixed pages, and basic dynamic-route logic
vue3/src/mocks	Stable Mock data
vue3/e2e	Playwright E2E test cases
vue3/scripts	Scripts for OpenAPI, integration checks, and more
vue3/src/api/schema.d.ts	Type definitions generated from OpenAPI

2. Local Development

cd vue3
npm install
npm run dev

Common modes:

Command	Purpose
npm run dev	Local frontend connected to a local backend
npm run dev:mock	Local frontend connected to the Mock service
npm run dev:test	Local frontend connected to the shared test backend
npm run build	Production build
npm run preview	Preview the build output

The browser request prefix is always /dev-api; switch between environments through environment variables and proxy targets.

3. API Contract

The backend OpenAPI is the source of the frontend-backend API contract.

Default generation:

cd vue3
npm run openapi

Check whether the schema is outdated:

cd vue3
npm run openapi:check

Specify an OpenAPI address:

cd vue3
$env:FASTBEE_OPENAPI_URL="http://test-api.fastbee.cn/v3/api-docs"
npm run openapi

For every backend API change, confirm the URL, method, request parameters, response structure, pagination structure, upload/download behavior, and error codes.

4. Mock And Integration

Recommended flow:

1. When the backend API is not ready, develop pages with npm run dev:mock.
2. Maintain success, empty-data, business-failure, and 401/403 examples in Apifox.
3. Maintain stable Mocks in vue3/src/mocks for key flows.
4. Run integration checks after the page is complete.
5. After connecting to the real backend, rerun the E2E tests and Apifox collections.

Aggregate check:

cd vue3
npm run verify:integration

This command runs integration static checks and Playwright integration test cases.

5. Request Tracing

Vue3 Axios requests carry an X-Request-Id. Backend responses and logs should echo the same requestId.

When an API fails during integration, record:

• The requestId.
• The request URL and method.
• The request parameters.
• The response body.
• The current login user and roles.
• The page and steps to reproduce.

This lets the backend locate the issue quickly in the logs.

6. Steps For Integrating A New Module

1. Add a page directory under vue3/src/views.
2. Add an API file under vue3/src/api.
3. Confirm that the backend OpenAPI already includes the target API.
4. Run npm run openapi to update the types.
5. Add Mock examples.
6. Integrate menu and button permissions.
7. Add stable Playwright test cases.
8. Run npm run verify:integration.

7. FAQ

Page request returns 404

Check whether the API path carries the /dev-api prefix, whether the proxy target is correct, and whether the backend API is registered.

The page has permission but buttons are not displayed

Check menu permissions, button permission identifiers, role authorization, and frontend permission directives.

openapi:check fails

This means schema.d.ts was not updated after the backend contract changed. Run npm run openapi, then check whether the type changes are expected.

E2E fails but the page works manually

Check whether the Mock data changed, whether the locators are stable, whether asynchronous waits are sufficient, and whether the test environment polluted the local cache.

8. Related Docs

• Frontend Architecture
• Backend Architecture
• AI Secondary Development
• Visualization And SCADA Development