返回提示词目录第 1350 页

前端架构审计与渐进改进规划

梳理前端模块边界、依赖和状态归属,评估变更影响,输出架构报告与渐进重构路线。

完整提示词

I want you to perform a maximally deep, systematic, and evidence-first analysis of the frontend architecture across the entire project.

Main objective:

> Determine whether the frontend is organized to remain stable, comprehensible, scalable, and safe for future modifications, without introducing unnecessary complexity.

This is not:

- a generic code review
- a visual design review
- a formatting review
- a pursuit of "more modern" patterns purely because they exist
- an automated refactor
- a list of subjective best practices

The focus is squarely on actual architecture and its concrete consequences.

Priority:

**correctness > architectural clarity > maintainability > scalability > elegance**

Do not report an issue simply because code is not structured according to your preferred pattern.

Every serious finding must demonstrate a tangible impact.

---

# 1. ESTABLISH THE STACK

Before beginning analysis, identify:

- framework
- React/Vue/Angular/Svelte version
- TypeScript/JavaScript
- routing library
- state management
- server-state library
- form library
- styling system
- UI/component library
- build system
- test framework
- monorepo setup if present
- backend/frontend boundary

Inspect at least:

- `package.json`
- lockfile
- `src/`
- `app/`
- `pages/`
- `components/`
- `features/`
- `modules/`
- `hooks/`
- `stores/`
- `services/`
- `lib/`
- `utils/`
- `contexts/`
- tests
- build/compiler configs

Do not jump to architectural conclusions before mapping the real structure.

---

# 2. MAP THE FRONTEND SYSTEM

Construct an accurate architectural map:

```text
Routing
↓
Pages / Screens
↓
Features
↓
Components
↓
Hooks / State
↓
Services
↓
API / Backend
```

If the project uses a different paradigm, document what actually exists.

Identify:

- application shell
- route-level layer
- feature layer
- shared UI
- domain logic
- data access layer
- global state
- server state
- utilities
- integration layer

---

# 3. FEATURE BOUNDARIES

Determine how features are isolated and grouped.

For each significant feature, verify:

- where it begins
- which components it owns
- which hooks it utilizes
- where its state resides
- how it interfaces with APIs
- where its business logic lives
- which shared modules it depends upon

Look for features scattered across the entire repository without clear boundaries.

Example problematic flow:

```text
Page
↓
shared component
↓
global hook
↓
generic util
↓
global store
↓
API helper
```

where business logic is fragmented across multiple unrelated modules.

---

# 4. LAYERING

Verify whether logical layers exist:

- presentation
- feature/domain
- state
- data access
- integration

Look for:

- UI components directly implementing large amounts of business logic
- utility functions that trigger API calls and mutate UI state
- data layer depending on presentation layer
- circular architectural dependencies

A formal layered architecture is not mandatory.

What matters is that responsibilities remain clear and understandable.

---

# 5. DEPENDENCY DIRECTION

Analyze dependency direction.

Lower and more generic layers should not depend on specific features without justification.

Look for patterns like:

```text
shared
↓
imports specific feature
```

or:

```text
utility
↓
imports page component
```

or:

```text
domain logic
↓
depends on visual component
```

When such a dependency exists, explain the concrete maintainability or coupling penalty.

---

# 6. CIRCULAR DEPENDENCIES

Search for direct and indirect circular references.

Example:

```text
A imports B
B imports C
C imports A
```

Assess the consequences:

- module initialization order bugs
- `undefined` runtime exports
- bundler issues / bloated chunks
- degraded testability
- tight coupling

Do not report a tooling warning without practical consequences.

---

# 7. COMPONENT RESPONSIBILITY

For large components, evaluate their breadth of responsibility.

Look for a component that simultaneously:

- fetches data
- manages complex internal state
- validates forms
- enforces business rules
- renders a massive UI tree
- coordinates modals
- triggers navigation
- dispatches analytics
- reads and writes browser storage

Such a component represents an architectural hotspot.

However, a large component is not inherently bad.

Only file an issue if the size causes:

- high coupling
- testability barriers
- duplicated logic
- frequent regressions
- cognitive difficulty tracing flow

---

# 8. SMART VS PRESENTATIONAL COMPONENTS

Do not enforce an obsolete, dogmatic separation.

Instead ask:

> Does this component have a single, coherent responsibility?

If a UI component contains domain-specific rules that duplicate across multiple screens, report the defect.

---

# 9. REUSABILITY

Do not attempt to turn everything into a reusable component.

Look for two opposite failure modes:

## Under-abstraction

- identical logic copy-pasted across multiple features
- same UI pattern implemented redundantly
- validation drift
- styling divergence

## Over-abstraction

- generic components burdened with dozens of configuration props
- excessive boolean flags
- hard-to-understand "universal" components
- abstractions that obscure fundamentally distinct business use cases

---

# 10. BOOLEAN PROP EXPLOSION

Search for components like:

```tsx
<Component
  compact
  dark
  editable
  searchable
  admin
  mobile
  bordered
  collapsible
/>
```

Check if flag combinations yield:

- unpredictable edge-case behaviors
- mutually invalid combinations
- convoluted conditional branches
- an unintuitive component API

Do not report a handful of well-reasoned boolean props as an issue.

---

# 11. COMPONENT API DESIGN

For shared components, review:

- prop naming clarity
- required vs optional props
- sensible default values
- event callback contracts
- controlled vs uncontrolled patterns
- component composition
- usage of `children`
- prop leakage

Look for APIs that permit invalid states to be constructed.

---

# 12. INVALID STATES

A core goal of solid architecture is to make invalid states unrepresentable or difficult to construct.

Look for:

```ts
loading: boolean
error: boolean
success: boolean
```

where it is possible to produce:

```text
loading = true
error = true
success = true
```

when their actual meanings are mutually exclusive.

Assess whether the state model should be made explicit (e.g. union types or state machines).

---

# 13. STATE OWNERSHIP

For every critical piece of state ask:

> Who owns this state?

Check whether state is:

- lifted too high
- buried too low
- duplicated across siblings
- global without justification
- local despite being required by multiple independent features

Do not critique state placement on style alone.

Cite concrete consequences.

---

# 14. GLOBAL STATE AUDIT

Map everything stored globally.

Classify:

- auth
- user preferences
- UI state
- domain state
- server state
- transient state

Look for:

- global state that belongs strictly to a single screen
- server responses mirrored into global stores without reason
- global modal state creating unnecessary coupling
- stores evolving into catch-all "god objects"

---

# 15. GLOBAL STORE GOD OBJECT

If a single store manages numerous unrelated domains, assess:

- coupling
- unnecessary re-renders
- reset and logout behavior
- ownership ambiguity
- test complexity
- persistence pitfalls

Do not suggest splitting based on line count alone.

Highlight the feature boundaries that the store currently blurs.

---

# 16. SERVER STATE VS CLIENT STATE

Strictly distinguish between:

**Server state**

- API responses
- database records
- remote resources

**Client state**

- modal visibility
- selected tab index
- transient form input
- local user interactions

Look for server state manually duplicated into:

- Redux
- Zustand
- Context
- `useState`

and subsequently synchronized by hand.

---

# 17. SOURCE OF TRUTH

Identify the single primary source of truth for each key domain entity.

Problematic example:

```text
API response
↓
query cache
↓
Redux
↓
component state
↓
form state
```

When all layers can be mutated independently, data drift is nearly inevitable.

---

# 18. STATE SYNCHRONIZATION

Look for `useEffect` hooks whose sole purpose is synchronizing two states.

Example:

```tsx
useEffect(() => {
  setLocalValue(globalValue)
}, [globalValue])
```

This is not automatically bad, but verify whether it leads to:

- infinite loops
- stale state reads
- overwriting active user input
- subtle race conditions and timing glitches

---

# 19. DOMAIN LOGIC

Locate business rules such as:

- permission checks
- pricing algorithms
- status transition rules
- eligibility criteria
- operational limits
- domain calculations

Check where they reside.

Look for identical domain logic dispersed across:

- UI components
- custom hooks
- generic utility files
- backend routes

When the same rules exist in multiple frontend places, audit them for drift.

---

# 20. BUSINESS LOGIC IN COMPONENTS

Example:

```tsx
if (
  user.role === "admin" &&
  order.status !== "cancelled" &&
  order.total > 1000
) {
  ...
}
```

If this identical rule appears across multiple components, it warrants domain abstraction.

Do not, however, extract an abstraction for every trivial `if` check.

---

# 21. DUPLICATED LOGIC

Search repository-wide for parallel implementations of:

- permissions
- validation schemas
- formatting logic
- numerical calculations
- date handling
- route builders
- API payload transforms
- status mappings

The critical question:

> Do these copies already exhibit divergent behavior?

Behavioral drift is a significantly stronger finding than syntactic duplication.

---

# 22. SHARED UTILITIES

Review `utils/` and `lib/`.

Look for "junk drawer" modules where unrelated helpers accumulate.

Example:

```text
utils.ts
```

containing:

- date formatters
- auth utilities
- API calls
- string helpers
- business rules
- analytics trackers

Propose refactoring only if the current structure hinders ownership or introduces circular coupling.

---

# 23. GENERIC HELPERS

Look for helper functions that have become excessively generic.

Symptoms:

- numerous optional parameters
- options object packed with boolean flags
- polymorphic return types
- branched logic catering to different features

Determine whether a single function is secretly handling distinct, unrelated responsibilities.

---

# 24. CUSTOM HOOK ARCHITECTURE

Map all custom hooks.

For each significant hook verify:

- single responsibility
- side effects
- API communications
- internal state
- returned API contract
- reusability

Look for hooks that have evolved into mini-application layers without defined boundaries.

---

# 25. HOOK COMPOSITION

Verify whether hooks:

- compose smaller, cohesive behaviors cleanly
- or construct deeply coupled dependency chains

Example:

```text
useFeature
↓
useAccount
↓
usePermissions
↓
useSettings
↓
useUser
```

Evaluate:

- how much hidden work a single invocation triggers
- whether duplicate network queries are spawned
- how difficult it is to trace data and error flows

---

# 26. HIDDEN SIDE EFFECTS

A function named:

```ts
getUserPreferences()
```

should not unexpectedly:

- write to browser storage
- dispatch analytics events
- mutate a global store

Look for APIs with misleading or covert side effects.

---

# 27. SERVICE LAYER

If a `services/` directory exists, verify its purpose.

Look for:

- passthrough thin wrappers offering zero value
- business logic awkwardly split between services and components
- services directly mutating UI stores
- services bundling unrelated business domains together

---

# 28. API CLIENT ARCHITECTURE

Review:

- base URL configuration
- request headers
- authentication handling
- error interception
- response parsing
- retry mechanisms
- network interceptors
- TypeScript typing

Look for:

- multiple independent API client instances
- inconsistent error handling patterns across features
- duplicated auth token injection logic
- raw response parsing happening inside presentation components

---

# 29. NETWORK BOUNDARY

The frontend must clearly delineate where local logic ends and network communication begins.

Look for components constructing complex backend payloads inline across multiple places.

If payload transformation constitutes domain logic, it belongs in a dedicated boundary layer.

---

# 30. TYPES

Review type architecture.

Look for:

- identical entities defined multiple times with subtle differences
- API DTO types used directly as UI models without explicit mapping
- widespread usage of `any`
- overly broad types
- type assertions that bypass runtime contracts

Do not demand excessive type complexity.

Types should primarily serve to prevent real bugs and clarify contracts.

---

# 31. DOMAIN TYPES VS API TYPES

Not every API response should directly dictate the UI data model.

Check whether an explicit mapper layer is warranted, particularly when the API returns:

- deeply nested nullable fields
- foreign naming conventions (e.g. snake_case vs camelCase)
- raw timestamps requiring formatting
- opaque status codes

Example:

```text
API UserDTO
↓
mapper
↓
User model
↓
UI
```

---

# 32. TYPE ASSERTIONS

Search for:

```ts
as SomeType
```

Especially:

```ts
as any
as unknown as
```

For every occurrence, check whether the assertion masks an actual interface mismatch or potential runtime crash.

---

# 33. ENUMS AND STATUSES

If an entity progresses through statuses, check whether they are modeled consistently.

Look for:

```text
"active"
"ACTIVE"
1
Status.Active
```

mixed across different files.

Status drift is a frequent source of cross-layer bugs.

---

# 34. ROUTING ARCHITECTURE

Inspect:

- route layout organization
- route nesting
- path parameters
- search/query parameters
- route guards and protection
- layout boundaries

Look for routing logic haphazardly scattered inside components.

---

# 35. HARD-CODED ROUTES

Look for:

```ts
"/users/" + id
```

scattered across dozens of files.

If route patterns appear frequently, consider a centralized route builder.

Do not, however, build a heavyweight routing abstraction for three static links.

---

# 36. NAVIGATION LOGIC

Verify whether business logic assumes a specific prior user journey.

Unsafe assumption:

```text
Screen B only works if user visited Screen A first
```

Direct URL access and deep linking must be analyzed where applicable.

---

# 37. FORM ARCHITECTURE

Map major forms across the application.

Check:

- schema definition
- form state management
- validation execution
- domain transformation
- API payload creation
- error handling

Look for giant multi-hundred-line form components conflating all of these layers into one file.

---

# 38. VALIDATION ARCHITECTURE

Establish where validation occurs:

- client-side
- shared schemas
- server-side

Architecturally, the frontend must distinguish:

- UX validation (instant user feedback)
- authoritative validation (enforced on server)

Never treat client-side validation as authoritative.

---

# 39. ERROR ARCHITECTURE

Map how errors propagate:

```text
API
↓
service
↓
query/mutation
↓
component
↓
user
```

Look for:

- each component interpreting identical errors differently
- raw backend exception strings displayed directly to users
- silently swallowed errors
- global error handlers that strip necessary context

---

# 40. ERROR TYPES

If every error is reduced to:

```text
Something went wrong
```

check whether the app discards actionable error classifications:

- validation errors
- authentication errors
- permission denials
- rate limits
- network disconnects
- server crashes
- conflict states

Do not introduce an elaborate error taxonomy without practical need.

---

# 41. LOADING ARCHITECTURE

Verify whether loading state is handled:

- globally
- per-route
- per-component
- per-query

Look for a single global `loading` indicator coordinating multiple unrelated operations.

---

# 42. MODAL ARCHITECTURE

Review how modals and dialogs are managed:

- local component state
- route-driven URLs
- global store
- modal service / manager

No single pattern is universally superior.

Assess whether the chosen approach introduces tight coupling or state synchronization bugs.

---

# 43. NOTIFICATION AND TOAST ARCHITECTURE

Look for:

- duplicate success/error alerts
- business logic directly coupled to toast notifications
- workflows relying on UI toasts to trigger subsequent business operations

Toasts should announce events, not coordinate business control flow.

---

# 44. PERMISSION ARCHITECTURE

Map the frontend permission system.

Check:

- central authorization source
- role checks
- capability/permission checks
- UI route/button guards

Look for:

```tsx
user.role === "admin"
```

scattered across dozens of presentation files when a granular capability model exists.

Always remember:

Frontend permission checks are purely a UX enhancement, never a security boundary.

---

# 45. FEATURE FLAGS

If feature flags are used:

- where are they read
- how can they be overridden for testing
- fallback behavior when uninitialized
- stale flag accumulation
- removal process for retired flags

Look for:

- permanent dead branches
- flag checks scattered arbitrarily across UI primitives
- client flags mistakenly treated as access control

---

# 46. CONFIGURATION ARCHITECTURE

Map:

- environment variables
- runtime configuration
- build-time configuration
- feature configurations

Look for:

- hardcoded URLs
- redundant parsing of environment variables
- inconsistent fallback handling
- client-side code accessing server-only config

---

# 47. DESIGN SYSTEM BOUNDARIES

If a design system exists, inspect:

- primitive components
- composed patterns
- feature-specific components

Look for domain-specific logic leaking into generic Button, Input, or Dialog primitives.

---

# 48. UI PRIMITIVES

Primitive UI components must remain strictly generic.

If a shared `Button` knows about:

- subscriptions
- user roles
- business order status
- API endpoints

architectural boundaries are compromised.

---

# 49. FEATURE COMPONENTS

Conversely, do not force a business-specific component into the design system simply because it is used twice.

Distinguish:

- reusable visual primitives
- reusable domain components

---

# 50. STYLING ARCHITECTURE

Without conducting a subjective design review, check for:

- global CSS leakage
- specificity wars
- duplicated theme tokens and magic values
- inconsistent responsive breakpoints

Only report styling issues that measurably harm maintainability or runtime behavior.

---

# 51. RESPONSIVE LOGIC

Look for JavaScript-based responsive checks where CSS media queries or container queries would suffice, especially if the JS approach introduces:

- SSR hydration mismatches
- unthrottled resize event listeners
- duplicate breakpoint definitions

Do not flag JS-based responsive logic when it is genuinely required.

---

# 52. FEATURE FOLDER COHESION

For each feature, check how many files must be examined to comprehend its behavior.

If a developer must bounce across:

```text
components/
hooks/
utils/
services/
stores/
types/
```

for a single small feature, evaluate whether the structure fragments ownership.

---

# 53. TYPE-BASED VS FEATURE-BASED STRUCTURE

Do not enforce a single dogmatic folder layout.

Evaluate the project in context:

Type-based structures (all hooks together, all components together) work well for small apps.

Feature-based structures scale better as the domain expands.

A finding requires tangible evidence that the current structure hinders modifications.

---

# 54. MONOREPO FRONTEND BOUNDARIES

If a monorepo is used, check:

- shared packages
- UI packages
- types package
- API client package
- feature packages

Look for:

- shared packages harboring app-specific domain knowledge
- circular workspace dependencies
- duplicate package versions across workspaces
- dependency drift

---

# 55. BARREL EXPORTS

Review `index.ts` barrel files.

Look for:

- circular import loops
- hidden cross-module dependencies
- massive public API surfaces
- accidental bundling of server code into client chunks

Do not condemn barrel exports by default.

---

# 56. PUBLIC MODULE API

For key feature and module folders, verify whether a clear public API exists.

If any file can import any private internal file of another module, architectural boundaries are non-existent.

---

# 57. INTERNAL IMPLEMENTATION LEAKAGE

Example:

```text
Feature B
↓
imports Feature A internal private hook
```

instead of Feature A's declared public interface.

Assess the resulting coupling.

---

# 58. CROSS-FEATURE DEPENDENCIES

Map imports between features.

Look for:

- bidirectional feature dependencies
- cascading change ripples
- features that cannot be isolated or tested independently

---

# 59. SHARED FOLDER AUDIT

The `shared/` directory frequently becomes a dumping ground.

Classify its contents:

- truly generic utilities
- cross-domain primitives
- misplaced domain-specific features

Do not relocate code without clear justification.

---

# 60. DEAD ABSTRACTIONS

Look for abstractions created for speculative future requirements that never arrived.

Examples:

- an interface with exactly one implementation
- a factory with a single case branch
- a plugin system serving two hardcoded features

Do not eliminate an abstraction if it serves as a stable, decoupled boundary.

---

# 61. PREMATURE GENERALIZATION

Symptoms:

- complex generics that nobody actually leverages
- configuration objects with dozens of unneeded knobs
- generic entity renderers
- meta-driven form engines without actual need

Assess cognitive overhead.

---

# 62. LEAKY ABSTRACTIONS

If a consumer must understand the internal implementation details of an abstraction to use it safely, the boundary is broken.

Example:

An API abstraction exists, yet callers must manually check raw HTTP status codes.

---

# 63. COUPLING

Identify modules with high incoming and outgoing dependency counts.

These are architectural hotspots.

For each, explain:

- why it is central
- what breaking changes it could trigger

---

# 64. COHESION

Modules should group elements that change together for the same business reasons.

Look for files combining unrelated business domains.

---

# 65. CHANGE AMPLIFICATION

Ask:

> If I modify one business rule, how many files must I touch?

Changing a status label or business limit should not require updating ten disparate files.

---

# 66. SHOTGUN SURGERY

Identify changes that require editing many loosely connected files:

- permissions
- route definitions
- status mappings
- API payload shapes
- feature flags
- analytics events

---

# 67. DIVERGENT CHANGE

The inverse problem:

A single file frequently modified for completely unrelated features.

Example:

`utils.ts` edited for auth, checkout, reporting, and notifications.

---

# 68. GOD COMPONENTS

A finding requires more than high line counts.

Identify components possessing numerous distinct reasons to change.

Document those reasons.

---

# 69. GOD HOOKS

The same applies to custom hooks.

Example:

`useDashboard()` fetching five resources, checking permissions, managing modal state, formatting tables, and logging analytics.

---

# 70. GOD SERVICES

Identify service modules acting as a bottleneck dependency for the whole application.

Assess the blast radius.

---

# 71. TESTABILITY

For any architectural hotspot ask:

> How easily can this unit be tested in isolation?

Look for:

- hidden global state dependencies
- direct browser API invocations
- hardcoded network calls
- implicit environment assumptions
- module singletons

---

# 72. MOCKING COMPLEXITY

If a test must mock 15 different dependencies to test a single function, high coupling is present.

Do not judge without inspecting both the test and the subject code.

---

# 73. TEST ARCHITECTURE

Evaluate the balance between:

- unit tests
- component tests
- integration tests
- E2E tests

Ensure the architecture facilitates testing critical boundaries.

---

# 74. DUPLICATED TEST SETUP

Extensive boilerplate across test suites indicates the module's public API is difficult to consume.

Do not, however, elevate a test helper refactor to a critical finding without tangible impact.

---

# 75. MOCK SERVICE LAYER

Ensure tests and development environments use contracts matching production.

Look for mocked APIs that have drifted away from real backend behavior.

---

# 76. DOCUMENTATION VS ARCHITECTURE

Compare:

- README
- architecture diagrams
- inline comments
- directory notes

against the actual dependency flow.

If docs claim "components are purely presentational" while components invoke APIs directly, report documentation drift.

---

# 77. NAMING

Do not critique subjective style.

Report misleading names that elevate the risk of developer error.

Example:

`getUser()` that actually fetches a user, writes to local storage, and refreshes an auth token.

The name conceals significant side effects.

---

# 78. MODULE SIZE

Line count is an indicator, not proof.

For large modules analyze:

- responsibilities
- dependencies
- reasons to change
- testability

---

# 79. FILE GRANULARITY

Do not enforce "one component per file" dogmatically.

Assess whether the file organization aids or impedes understanding the feature locally.

---

# 80. ABSTRACTION DEPTH

Trace a critical flow:

```text
Page
↓
Container
↓
Feature
↓
Provider
↓
Hook
↓
Service
↓
Repository
↓
Client
```

If every layer simply forwards calls without adding validation, mapping, or isolation, assess accidental complexity.

---

# 81. PASS-THROUGH LAYERS

Look for modules that merely execute:

```ts
return otherFunction(args)
```

without adding value.

A single wrapper is harmless; many wrappers accumulate cognitive overhead.

---

# 82. ARCHITECTURAL CONSISTENCY

Compare parallel features:

```text
Users
Orders
Products
```

If each feature handles fetching, state, errors, and forms in entirely different ways, determine if this is justified or historical drift.

---

# 83. PATTERN DRIFT

Look for old and new patterns coexisting without a migration plan.

Example:

Axios + Redux for legacy features vs fetch + TanStack Query for new ones.

Assess migration debt and cognitive burden.

---

# 84. LEGACY LAYERS

Classify into:

```text
LEGACY BUT USED
LIKELY OBSOLETE
CONFIRMED DEAD
```

Do not delete code simply because it is old.

---

# 85. MIGRATION BOUNDARIES

If the project is migrating technologies, verify whether a clean boundary exists.

An adapter pattern bridging legacy stores to modern query layers is usually superior to a chaotic mixture.

---

# 86. FEATURE EVOLUTION

Use git history if available.

Look for modules repeatedly modified due to regressions.

High-churn + high-coupling marks an architectural hotspot.

---

# 87. FRONTEND SECURITY BOUNDARY

The architecture audit must identify where the frontend improperly assumes security authority:

- role checks existing only in the UI
- hiding admin links as "access control"
- trusting client-calculated price totals
- client-derived permission bypasses

The server must be the ultimate authority.

---

# 88. DATA EXPOSURE

Check if the UI receives significantly more data than it requires:

API returns a full user entity with sensitive metadata when the component only needs `name` and `avatar`.

Assess privacy and coupling implications.

---

# 89. PERFORMANCE ARCHITECTURE

Without conducting a full performance audit, highlight architectural roots:

- bloated global providers
- client-heavy application roots
- massive monolithic bundles
- central context triggering app-wide re-renders
- serial data waterfalls
- heavy dependencies imported globally

---

# 90. BUNDLE BOUNDARIES

If tooling permits, inspect what ends up in the initial bundle.

Look for:

- heavy feature dependencies imported at the root
- admin-only libraries in public visitor bundles
- rich text editors or chart libraries bundled on landing pages

---

# 91. LAZY LOADING BOUNDARIES

Verify whether heavy, infrequently accessed features are deferred from the critical path.

Do not suggest lazy loading everything indiscriminately.

---

# 92. FRAMEWORK-AWARE ARCHITECTURE

If the framework natively provides:

- routing
- data loading
- layout boundaries
- server-state management
- caching

ensure the project has not built a redundant custom framework on top without necessity.

---

# 93. ARCHITECTURAL FALSE POSITIVES

Before finalizing a finding, consider:

1. project size
2. team size
3. framework conventions
4. actual code reuse
5. test coverage
6. historical migrations
7. performance requirements
8. domain complexity

A small application does not require enterprise-tier architecture.

---

# 94. SEVERITY

Use:

## P1 - HIGH

Architectural flaw actively causing:

- regressions
- correctness bugs
- security vulnerabilities
- severe risk on future changes

## P2 - MEDIUM

Real architectural weakness with substantial maintainability consequences.

## P3 - LOW

Localized design issue with bounded impact.

## P4 - IMPROVEMENT

Justifiable architectural enhancement without an active defect.

P0 is reserved strictly for architectural flaws directly enabling critical data loss or security breaches.

---

# 95. CONFIDENCE

Use:

```text
HIGH
MEDIUM
LOW
```

HIGH:

clearly proven by dependency flow and code evidence.

MEDIUM:

structure strongly indicates an issue, but long-term impact cannot be fully proven without runtime/team data.

LOW:

requires inaccessible context regarding team scaling or deployment targets.

---

# 96. FINDING FORMAT

For every serious finding:

```text
ID:
Severity:
Category:
Confidence:
Status:

Affected area:
Files/modules:

Architectural problem:

Evidence:

Dependency flow:

Current consequence:

Future change risk:

Root cause:

Recommended direction:

Migration risk:

Complexity:
XS / S / M / L / XL
```

---

# 97. DO NOT REFACTOR AUTOMATICALLY

During the audit:

- do not move files
- do not rewrite imports
- do not invent new abstractions
- do not swap state managers
- do not reorganize folder trees

Document the architecture first.

---

# 98. OUTPUT - FRONTEND_ARCHITECTURE_AUDIT.md

Structure:

## 1. Executive Summary

- stack
- architecture style
- major strengths
- primary architectural risks
- overall maintainability rating

## 2. Architecture Map

## 3. Dependency Map

## 4. Feature Boundaries

## 5. State Architecture

## 6. Data Flow

## 7. Component Architecture

## 8. Hooks Architecture

## 9. API / Data Layer

## 10. Routing Architecture

## 11. Form Architecture

## 12. Error Architecture

## 13. Shared Code

## 14. Design System Boundaries

## 15. Cross-Feature Dependencies

## 16. Legacy / Migration Layers

## 17. Testing Architecture

## 18. Architectural Hotspots

Table:

| Module | Responsibilities | Incoming dependencies | Outgoing dependencies | Risk |
|---|---|---|---|---|

## 19. Findings Summary

| ID | Severity | Area | Problem | Confidence | Complexity |
|---|---|---|---|---|---|

## 20. Detailed Findings

## 21. Things Done Well

## 22. Technical Debt

## 23. Unknown / Not Verified

## 24. Recommended Architecture Direction

Do not suggest rewrites.

Explain an evolutionary roadmap.

## 25. Refactoring Roadmap

### Phase 1 - High-risk boundaries

### Phase 2 - State/data consistency

### Phase 3 - Feature ownership

### Phase 4 - Shared architecture cleanup

### Phase 5 - Optional improvements

---

# 99. CHANGE SCENARIO TEST

After the initial audit, stress-test the architecture through hypothetical modification scenarios:

### Scenario A

> Add a new field to an existing critical entity.

How many layers and files must be modified?

### Scenario B

> Modify one permission rule.

How many places must be updated?

### Scenario C

> Replace one API endpoint.

Does the UI know too much about backend contracts?

### Scenario D

> Add a new screen to an existing feature.

Can the feature be extended smoothly?

### Scenario E

> Switch the state management library for one feature.

Is the entire application coupled to that library?

### Scenario F

> Replace the UI component library.

Does business logic depend directly on UI primitives?

### Scenario G

> Introduce a new user role with different capabilities.

Are permissions centralized or scattered?

Use these scenarios to uncover real change amplification.

---

# 100. SECOND PASS - ARCHITECTURAL PRESSURE TEST

Execute an additional review through four lenses:

## New developer pass

Ask:

> If a new engineer needs to modify a feature, how much of the entire system must they understand?

## Change pass

Ask:

> Which small modification has the largest blast radius?

## Failure pass

Ask:

> If one shared module changes behavior, how many features silently break?

## Growth pass

Ask:

> What works adequately today, but will definitively break if the feature count triples?

Explain specifically what grows out of control:

- dependency count
- branch complexity
- shared mutable state
- re-render surface
- change amplification
- testing friction

---

# FINAL QUALITY GATE

Before returning your report, verify:

- you did not impose your personal favorite folder structure
- you did not propose a microfrontend without clear necessity
- you did not suggest Redux/Zustand merely because substantial state exists
- you did not flag large files solely due to line count
- you did not report duplication without verifying behavioral drift
- every P1/P2 finding has clear evidence and dependency flow
- architectural risks are separated from minor stylistic preferences
- every proposed refactoring is evolutionary, not a full rewrite

---

# FINAL RULE

Do not return a report recommending complete rewrites or purely subjective design patterns.

Focus on real architectural health:
- clear boundaries
- unambiguous state ownership
- predictable dependency direction
- manageable change blast radius
- high testability

Every finding must demonstrate real maintainability, reliability, or scalability consequences.

可替换内容

  • [globalValue]

分类与标签

编程开发、前端架构、模块边界、状态管理、渐进重构

前往 AI 图片创作