更新

CLAUDE.md

@@ -92,6 +92,116 @@ This is the **GFast UI** project (`gfast-ui`), a Vue 3 admin management system b
 
 5. **Keep-alive**: Route components can be cached via keep-alive, managed by the `useKeepALiveNames` store.
 
+## Repository Collaboration Rules
+
+These rules capture long-term repository preferences confirmed by the user and should be applied in future sessions unless the user explicitly overrides them.
+
+### Pagination Rules
+
+- Prefer the project global `pagination` component by default.
+- Pagination should be fixed and visible as part of the page or dialog layout, not conditionally hidden only because the dataset is small.
+- In single-page scenarios, the UI should still show total count together with the pagination area.
+- Avoid designs where pagination only appears after data exceeds one page.
+
+### Dialog Layout Rules
+
+- For dialogs that contain searchable tabular data, prefer this structure:
+  1. search area
+  2. table/content area
+  3. pagination area placed under the table inside the dialog body
+  4. footer action buttons
+- The pagination area should remain visually stable and should not be omitted just because the current result set is small.
+
+### Theme and Style Rules
+
+- When functionality and existing theme style conflict, prioritize making the feature clearly visible and usable first.
+- After ensuring usability, align the implementation with the repository's existing theme and style system as much as possible.
+- Be cautious about global theme styles that may affect local pagination, dialog, or table layouts.
+
+### Problem-solving Workflow
+
+- For repeated UI issues, analyze in this order:
+  1. interface/request data and returned structure
+  2. component logic and render conditions
+  3. theme and style coverage/conflicts
+  4. then decide whether a rewrite is necessary
+- Do not jump straight to a rewrite before checking interface behavior and style interference.
+
+### Execution Workflow Rules
+
+- When modifying a feature, locate it in this order: usage location, component definition, API definition, then at least one similar implementation in the project.
+- For common UI features such as pagination, dialogs, and tables, align with an existing similar implementation before making changes.
+- Prefer componentization. If a page or Vue SFC is already large, or a block has a clear independent responsibility, split it into components instead of continuing to extend the same file.
+- For very long files such as complex page-level `index.vue` files, treat further component splitting as the default direction rather than the exception.
+- Before editing large files or complex Vue SFCs, first read the target context; if a replacement fails once, do not repeat the same replacement blindly, and instead expand the context or switch to smaller targeted edits.
+- After UI or interaction changes, verify not only lint status for edited files but also render conditions, interface fields, and possible style impact.
+- If the same issue is not resolved after one attempt, pause and ask the user before continuing with more speculative changes.
+- Do not proactively rewrite a component unless the user explicitly asks for a rewrite.
+- At the start of a new conversation, read `CLAUDE.md` before making changes.
+- When code changes appear not to take effect, check in this order: compile/HMR status, render conditions, API data, then style overrides.
+- Turn repeated low-level mistakes into explicit workflow checks and follow those checks in future edits.
+
+### Componentization and Structure Rules
+
+- If a view block has an independent responsibility, prefer extracting it into a component instead of keeping it inside a large page file.
+- When a file is already long, or a new feature would further expand responsibilities, proactively split it into components.
+- Child components may keep their own local logic when that logic belongs clearly to the child’s responsibility; only shared state and necessary events should stay in the parent.
+- For complex pages, small-scale components can stay in `component/`, while larger feature areas may be grouped by responsibility in subdirectories.
+- For very long page files, prefer keeping the parent focused on composition, state orchestration, and data flow, while moving feature UI and local behavior into child components.
+- When extracting new child components from a large file, move their related local styles with them to avoid continued growth of the parent file.
+
+### API and Data Handling Rules
+
+- Follow the project’s common response structure by default, but add moderate component-side compatibility handling when equivalent APIs return slightly inconsistent fields.
+- For page-level error handling, use global handling by default, but use page-level or silent handling when the interaction requires local control.
+- Prefer a unified parameter-building entry for request params instead of assembling the same parameters across multiple functions.
+
+### Form and Interaction Rules
+
+- Follow the project’s existing form behavior style: required fields should be clearly validated on submit, while avoiding unnecessarily disruptive validation during input.
+- For shared create/edit forms, initialize, patch, and reset form state through a unified initialization path to avoid stale state.
+- Search interactions should behave consistently across button click, Enter key, and clear actions, and should reset to the first page by default.
+
+### Dialog and Selector Rules
+
+- Dialogs should clear temporary internal state on close by default; any state that needs to persist should be explicitly provided back by the parent.
+- Selector components should follow a consistent pattern: `v-model` for visibility, a default value prop, and a `confirm` event for returning the selected result.
+- For temporary selectors and lightweight dialogs, prefer `destroy-on-close`; for more complex stateful forms, decide deliberately rather than applying it blindly.
+
+### Styling Rules
+
+- Prefer local scoped style changes first; only modify global theme styles after confirming the issue is truly shared across multiple places.
+- When overriding Element Plus internals, prefer local `:deep()` overrides before considering global style changes.
+- Use semantic, area-based class names instead of short or overly generic names.
+
+### Debugging and Validation Rules
+
+- Minimal temporary debugging is allowed when necessary, but all temporary debugging code must be removed before final delivery.
+- Temporary `console` output is acceptable only when debugging is genuinely needed and must be removed before final delivery.
+- For UI and interaction changes, verify lint, key render conditions, interface fields, and style impact before considering the task complete.
+
+### Change Scope and Consistency Rules
+
+- Prefer the smallest necessary change set, but do not pretend a local-only fix is sufficient when the real root cause is elsewhere in the chain.
+- Only fix nearby issues when they are strongly related to the current task; otherwise ask the user before expanding the scope.
+- Within the current modification scope, move code toward repository rules when practical, but avoid broad unrelated refactors.
+
+### Communication and Risk Rules
+
+- Before changing code, confirm with the user when a change involves a rewrite, global side effects, unclear requirements, or a second attempt that still has not solved the issue.
+- After changes, explain what changed, why it was changed that way, and any remaining risks or points worth confirming.
+- When a requirement still depends on a meaningful assumption, ask the user first instead of silently choosing a direction.
+
+### Repository Memory Rules
+
+- When collaboration reveals a repeated problem pattern, proactively suggest turning it into an explicit repository rule in `CLAUDE.md`.
+- Project-specific experience or pitfall notes may be added when they become necessary, but do not expand them prematurely without clear recurring value.
+
+### Rule Documentation Style
+
+- Keep long-term repository rules concise and practical.
+- Prefer short rule lists with a small amount of explanation over overly long documentation.
+
 ## Environment Variables
 
 - `.env.development` - Development environment settings