Frontend Code Development and Output Standards

General Requirements

• Language: All thought processes and output must be in Chinese.
• Context Reference: Each dialogue must explicitly reference relevant content from the project's README.md to ensure development aligns with project goals.
• Project Architecture: Based on Vue.js + ElementUI + Vue Router + Vuex + Axios.
• Documentation Location: Project documentation is stored in the /docs directory using .md format.
• Git Commit Standards: All code commits must follow the specifications defined in GIT_COMMIT.md. The AI assistant must refer to this document when generating commit messages.

Coding Style

• Maintain consistent style (e.g., 2-space indentation, semicolon usage, line breaks).
• Follow the official Vue.js Style Guide and ESLint rules.
• Prioritize code readability; avoid overly compact or clever code.

Naming and Commenting

Naming Conventions

• Variables and Functions: Use camelCase.
• Component Names: Use PascalCase, e.g., UserList.vue.
• File Names: Use PascalCase for Vue components; use camelCase or kebab-case for others.
• Constants: Use UPPER_SNAKE_CASE, e.g., API_BASE_URL.
• CSS Class Names: Use kebab-case, e.g., user-list-item.

Commenting Standards

• All functions, components, and key logic blocks must have clear, accurate, and concise Chinese comments.
• Comments should explain the "why" beyond just the "what".
• @author format: username / useremail (obtained from Git config).
• @since format: yyyy-MM-dd HH:mm:ss (timestamp when code is generated).

Vue Component Comment Example

<template>
  <!-- User list page -->
  <div class="user-list">
    <!-- Search area -->
    <el-form :model="queryForm" inline>
      <el-form-item label="Username">
        <el-input v-model="queryForm.name" placeholder="Enter username"></el-input>
      </el-form-item>
    </el-form>
  </div>
</template>

<script>
/**
 * User List Component
 * @author zhangsan / zhangsan@example.com
 * @since 2025-01-15 14:30:25
 */
export default {
  componentName: 'UserList',
  data() {
    return {
      queryForm: {
        name: ''
      }
    }
  },
  methods: {
    /**
     * Fetch user list
     * Retrieves user data based on query conditions and updates the table
     * @author zhangsan / zhangsan@example.com
     * @since 2025-01-15 14:30:25
     */
    loadUsers() {
      // Implementation logic
    }
  }
}
</script>

Development Standards

Vue Component Standards

• Single function length should not exceed 50 lines; consider splitting or refactoring if longer.
• Component files should not exceed 300 lines; split into sub-components if longer.
• Do not use global variables; prioritize Vuex state management or props/emit for data flow.
• Module Imports: Use ES6 import/export syntax; avoid require.
• Code Formatting: Use 2-space indentation and trailing semicolons.

JavaScript Standards

• Use ES6+ syntax (arrow functions, destructuring, template literals, etc.).
• Prefer const, then let; avoid var.
• Function parameters should not exceed 3; use an object parameter if more are needed.
• Avoid deep nesting; limit to 3 levels maximum.

Vue-Specific Stendards

• Component props must have defined types and default values.
• Use computed properties for complex logic; avoid complex expressions in templates.
• Use lifecycle hooks appropriately; avoid DOM operations in created.
• Clean up timers and event listeners when components are destroyed.

Styling Standards

CSS/SCSS Standards

• Use the SCSS preprocessor, supporting variables and nesting.
• Class names should use kebab-case.
• Avoid !important; resolve specificity by increasing selector weight.
• Use CSS variables appropriately to define theme colors.

ElementUI Usage Standards

• Prioritize using ElementUI components; avoid reinventing the wheel.
• When adding custom styles, use scoped to avoid global pollution.
• Manage theme customization through a unified variables.scss file.

Responsive Design

• Implement responsive layouts using ElementUI's grid system.
• Use media queries for mobile adaptation.
• Use relative units for images to support high-resolution screens.

Testing Requirements

Unit Testing

• Write unit tests for core business logic and utility functions.
• Use Jest + Vue Test Utils for component testing.
• Test coverage should be no less than 70% (considering frontend project characteristics).
• Test cases must cover normal paths, edge cases, and error scenarios.

End-to-End Testing

• Write end-to-end tests for critical business workflows.
• Use Cypress or Playwright for automated E2E testing.
• Cover primary user interaction paths.

Manual Testing

• Perform browser compatibility testing after developing new features.
• Test responsive effects on different screen sizes.
• Verify accessibility (a11y) compliance.

Code Optimization

• Optimizations must be based on performance bottlenecks or maintainability issues; avoid premature or meaningless "optimization".
• Any optimization must pass complete testing verification to ensure functional correctness.
• Prioritize readability over performance unless performance is a confirmed bottleneck.

Code Refactoring

• Define clear goals before refactoring (e.g., improving readability, eliminating duplication, enhancing structure).
• After refactoring, all existing tests must pass, and necessary new tests should be added.
• Refactoring must not reduce code readability or introduce hidden complexity.

Documentation Requirements

• All modules, interfaces, and key algorithms must have accompanying detailed technical documentation.
• Documentation should include: functionality description, usage examples, input/output definitions, dependencies, etc.
• Documentation must be updated in sync with code changes to avoid "documentation rot".

Development Tools and Scripts

Code Generation Information Script

The project provides scripts to automatically fetch code generation information for creating standardized @author and @since comments.

Script Location:

• Windows: scripts/get-code-info.bat
• Linux/macOS: scripts/get-code-info.sh

Usage Scenarios:

• When generating a new Vue component.
• When adding a new utility function.
• When author and timestamp information is required.

Development Tool Configuration

ESLint Configuration

• Use the official Vue ESLint configuration.
• Customize rules to fit project needs.
• Enable auto-formatting on save.

Prettier Configuration

• Unify code formatting rules.
• Configuration file: .prettierrc.
• Integrate with ESLint to avoid conflicts.

VS Code Configuration

Recommended extensions:

• Vetur (Vue syntax highlighting)
• ESLint (code linting)
• Prettier (code formatting)
• Auto Rename Tag (automatic tag renaming)

Git Commit Standards

Specification Document Reference

Refer to the complete Git commit specifications in: GIT_COMMIT.md

AI Assistant Responsibilities

When a developer requests a Git commit message, the AI assistant must:

1. Automatically Analyze Code Changes
   • Execute git status to review changed files.
   • Execute git diff to analyze specific changes.
   • Identify the type of change (new feature, bug fix, refacter, etc.).
2. Generate a Standard Commit Message
   • Format: [no] [type] [subject]
   • Use the current weekly task number (provided by the developer).
   • Select the correct commit type.
   • Keep the subject under 50 characters.
   • List all key changes in the body (using - bullets).
3. Quality Assurance
   • ✅ Includes task number.
   • ✅ Correct commit type.
   • ✅ Concise subject line.
   • ✅ Complete body.
   • ✅ Proper formatting.

Commit Type Quick Reference

type	Description	Usage Scenario
feat	New feature	New page, component, business function
fix	Bug fix	Fixing bugs, styling issues, logic errors
refactor	Code refactoring	Refactoring components, optimizing code structure
docs	Documentation changes	Modifying README, comments, development docs
style	Style adjustments	CSS style modifications, UI adjustments
perf	Performance optimization	Optimizing load speed, reducing bundle size
test	Test code	Adding or modifying unit tests, E2E tests
build	Build adjustments	Webpack config, dependency management, bundle optimization
chore	Other changes	Config files, development tool configuration

Usage Example

[sop-72] feat Add user management page

- Add UserList.vue user list component
- Implement user query, add, and edit functions
- Add user state management and permission control
- Integrate ElementUI table and pagination components

Task Number Management

• Developers provide a weekly task number.
• The AI assistant automatically records it in the GIT_COMMIT.md document.
• The current task number is used automatically when generating commit messages.

Trigger Scenarios

The AI assistant should proactively offer Git commit message generation in these scenarios:

• When a developer explicitly requests commit message generation.
• After completing a coding task.
• When a developer asks how to commit code.

Automated Git Operations

Important: AI Proactive Inquiry Mechanism

• After generating a commit message, the AI must proactively ask: "Would you like me to directly execute the git commit and push to the remote repository?"
• The developer does not need to initiate this request; the AI will prompt automatically.
• Upon developer confirmation, the AI automatically executes:
  • git add to stage files.
  • git commit to commit locally.
  • git push to push to the remote repository.
  • Provide detailed feedback on the execution results.