## Context

`origin/master` at `27c7b6d` contains device, phone, and WeCom management but not the authentication module. The source chain is `1cd0087`, `9d5953f`, `3f7c655`, `52071f0`, and `7a452f3`; `52071f0` changes only a historical OpenSpec document and is intentionally excluded under the approved documentation policy.

### Scope-file purpose notes

| Files | Purpose |
|---|---|
| `backend/src/main/java/com/xyw/console/auth/**` and `config/{SecurityConfig,WebConfig}.java` | Login, token/session validation, authorization, system-user administration, and HTTP security policy. |
| `backend/src/main/resources/db/migration/V1__system_user_auth_permissions.sql` | Adds permission/session fields required by authentication. |
| `backend/src/main/java/com/xyw/console/asset/**` changed files | Applies authentication and CSRF checks to existing asset APIs. |
| `frontend/src/modules/auth/**`, `router/index.js`, `main.js`, `App.js`, `index.html` | Login UI, browser state, first-load route decision, and neutral startup display. |
| Changed device, phone, WeCom, system-user frontend files and test files | Keep protected workspaces compatible and prove regressions are avoided. |
| `openspec/changes/integrate-authentication-to-master/**` | Sole planning record for this integration. |

## Goals / Non-Goals

**Goals:**

- Use a neutral first paint while the router validates the session.
- Send unauthenticated visitors to login without showing a protected shell.
- Keep a network failure at the requested URL with a retry path.
- Preserve asset management workflows for permitted users.

**Non-Goals:**

- Do not push, merge to `master`, deploy, or run a database migration without a further user approval.
- Do not include historical source-branch OpenSpec records.
- Do not redesign unrelated asset features.

## Decisions

1. Integrate four runtime commits on a new branch based on `origin/master`; omit `52071f0` because it affects only excluded historical documentation.
2. The router owns the initial current-user decision. The API client handles later expired sessions, avoiding competing redirects.
3. `index.html` provides a neutral boot screen and `main.js` waits for router readiness, avoiding the dashboard-to-login flash.
4. Backend and frontend are a paired release. A database without production data lowers data-risk now, but the inserted administrator's password hash, role, and page permissions must match backend rules before release.
5. Every new or modified method, object method, arrow function, and business callback in scope retains a plain-language comment describing its purpose, related files, and call/data flow.

## Risks / Trade-offs

- [Administrator cannot log in] -> verify password hash, administrator role, and page permissions against the implemented backend before release.
- [Asset regression] -> retain current `master` behavior and run device, phone, WeCom, and frontend regression suites.
- [Refresh flash returns] -> preserve the neutral boot contract and run the dedicated browser checks.
- [Session/CSRF mismatch] -> test authenticated and rejected writes in backend and browser suites.
- [Future production migration] -> approve migration execution separately; application rollback must not blindly delete user/role/permission data.

## Migration Plan

1. Use the isolated integration branch and verify its test evidence.
2. Before any release, insert a verified administrator using the backend-compatible password hash, role, and permissions.
3. Review and run the database migration only after explicit approval.
4. Deploy matching backend and frontend artifacts together.
5. If authentication or core asset behavior fails, roll back application artifacts together; preserve database data for review.

## Open Questions

1. Which exact administrator username, password hash process, role, and page permissions will be inserted before the first release?
2. When the branch is reviewed, do you approve a remote push and a new MR? Those actions remain out of scope for the current execution.
