Wx_WxCheck_Prod/openspec/changes/add-admin-web/design.md

Context

The admin web system needs to provide a responsive, user-friendly interface for administrators to manage users and conversation records from the WeChat mini-program. The system should work seamlessly with the existing ASP.NET Core backend API.

Goals / Non-Goals

• Goals:
  • Provide a modern, responsive admin interface
  • Support dark/light theme switching
  • Implement secure authentication
  • Provide efficient data management with search and pagination
  • Follow Vue 3.x best practices with Composition API
• Non-Goals:
  • Real-time notifications
  • Advanced analytics and reporting
  • Multi-language support

Decisions

• Decision: Use Vue 3.x with Composition API and <script setup> syntax
  • Rationale: Modern Vue approach, better TypeScript support, more organized code
• Decision: Use Element Plus as UI framework
  • Rationale: Comprehensive component library, excellent documentation, Vue 3 support
• Decision: Use Pinia for state management
  • Rationale: Official Vue 3 state management, simpler than Vuex, better TypeScript support
• Decision: Use Vite as build tool
  • Rationale: Fast development server, optimized build, modern tooling
• Decision: Implement client-side authentication with fixed credentials
  • Rationale: Simplified approach for initial implementation; can be enhanced with JWT later
• Decision: Responsive design with mobile-first approach
  • Rationale: Admins may need to access system from mobile devices
• Decision: Dark/light theme switching
  • Rationale: Modern UX requirement, reduces eye strain for extended use

Technical Architecture

• Frontend Framework: Vue 3.x with Composition API
• UI Library: Element Plus
• Build Tool: Vite
• Routing: vue-router 4.x
• State Management: Pinia
• HTTP Client: axios
• Styling: Scoped CSS with responsive design
• Authentication: Token-based with localStorage

Component Structure

src/
├── components/
│   └── Layout/
│       ├── Layout.vue (main layout with sidebar)
│       ├── Sidebar.vue (navigation menu)
│       └── Header.vue (top bar with user info and theme toggle)
├── views/
│   ├── Login.vue (login page)
│   ├── Home.vue (dashboard)
│   ├── UserList.vue (user management)
│   └── ConversationList.vue (conversation management)
├── router/
│   └── index.js (routing configuration)
├── store/
│   ├── auth.js (authentication state)
│   └── theme.js (theme state)
├── utils/
│   └── request.js (axios configuration)
└── styles/
    ├── main.css (global styles)
    └── variables.css (CSS variables for theming)

API Integration

The admin web will integrate with existing backend APIs:

• /api/Admin/QueryUsers - User management
• /api/Admin/QueryConversations - Conversation management
• Future: Authentication endpoints

Risks / Trade-offs

• Risk: Fixed authentication credentials are not secure
  • Mitigation: Document this limitation; plan to implement proper JWT authentication
• Risk: No real-time updates
  • Mitigation: Manual refresh for data updates; can be enhanced later
• Trade-off: Simplified authentication vs security
  • Decision: Start with simple implementation, enhance security in future iterations

Migration Plan

No migration required as this is a new system.

Open Questions

• Should we implement proper JWT authentication from the start?
• Should we add role-based access control (RBAC)?
• Should we implement real-time updates using WebSocket or polling?