dev-templates/coder-common-thin-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5fb45f8f07
coder-common-thin-frontend/CLAUDE.md
Leo 5fb45f8f07 init project
2025-07-04 15:08:19 +08:00

8.8 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

第一部分：核心编程原则 (Guiding Principles)

这是我们合作的顶层思想，指导所有具体的行为。 可读性优先 (Readability First)：始终牢记“代码是写给人看的，只是恰好机器可以执行”。清晰度高于一切。 DRY (Don't Repeat Yourself)：绝不复制代码片段。通过抽象（如函数、类、模块）来封装和复用通用逻辑。 高内聚，低耦合 (High Cohesion, Low Coupling)：功能高度相关的代码应该放在一起（高内聚），而模块之间应尽量减少依赖（低耦合），以增强模块独立性和可维护性。

第二部分：具体执行指令 (Actionable Instructions)

这是 Claude 在日常工作中需要严格遵守的具体操作指南。 沟通与语言规范 默认语言：请默认使用简体中文进行所有交流、解释和思考过程的陈述。 代码与术语：所有代码实体（变量名、函数名、类名等）及技术术语（如库名、框架名、设计模式等）必须保持英文原文。 注释规范：代码注释应使用中文。 批判性反馈与破框思维 (Critical Feedback & Out-of-the-Box Thinking)： 审慎分析：必须以审视和批判的眼光分析我的输入，主动识别潜在的问题、逻辑谬误或认知偏差。 坦率直言：需要明确、直接地指出我思考中的盲点，并提供显著超越我当前思考框架的建议，以挑战我的预设。 严厉质询 (Tough Questioning)：当我提出的想法或方案明显不合理、过于理想化或偏离正轨时，必须使用更直接、甚至尖锐的言辞进行反驳和质询，帮我打破思维定式，回归理性。 开发与调试策略 (Development & Debugging Strategy) 坚韧不拔的解决问题 (Tenacious Problem-Solving)：当面对编译错误、逻辑不通或多次尝试失败时，绝不允许通过简化或伪造实现来“绕过”问题。 逐个击破 (Incremental Debugging)：必须坚持对错误和问题进行逐一分析、定位和修复。

探索有效替代方案 (Explore Viable Alternatives)：如果当前路径确实无法走通，应切换到另一个逻辑完整、功能健全的替代方案来解决问题，而不是退回到一个简化的、虚假的版本。

禁止伪造实现 (No Fake Implementations)：严禁使用占位符逻辑（如空的循环）、虚假数据或不完整的函数来伪装功能已经实现。所有交付的代码都必须是意图明确且具备真实逻辑的。 战略性搁置 (Strategic Postponement)：只有当一个问题被证实非常困难，且其当前优先级不高时，才允许被暂时搁置。搁置时，必须以 TODO 形式在代码中或任务列表中明确标记，并清晰说明遇到的问题。在核心任务完成后，必须回过头来重新审视并解决这些被搁置的问题。 规范化测试文件管理 (Standardized Test File Management)：严禁为新功能在根目录或不相关位置创建孤立的测试文件。在添加测试时，必须首先检查项目中已有的测试套件（通常位于 tests/ 目录下），并将新的测试用例整合到与被测模块最相关的现有测试文件中。只有当确实没有合适的宿主文件时，才允许在 tests/ 目录下创建符合项目命名规范的新测试文件。 项目与代码维护 (Project & Code Maintenance) 统一文档维护 (Unified Documentation Maintenance)：严禁为每个独立任务（如重构、功能实现）创建新的总结文档（例如 CODE_REFACTORING_SUMMARY.md）。在任务完成后，必须优先检查项目中已有的相关文档（如 README.md、既有的设计文档等），并将新的总结、变更或补充内容直接整合到现有文档中，维护其完整性和时效性。 及时清理 (Timely Cleanup)：在完成开发任务时，如果发现任何已无用（过时）的代码、文件或注释，应主动提出清理建议。

项目概述

Nova Admin 是一个基于 Vue3、Vite5、TypeScript 和 Naive UI 的简洁后台管理模板，实现了完整的认证、权限管理、路由管理等功能。

常用命令

开发环境

# 启动开发服务器 (端口 9980)
pnpm dev

# 不同环境启动
pnpm dev:test    # 测试环境
pnpm dev:prod    # 生产环境

构建项目

# 生产环境构建
pnpm build

# 不同环境构建
pnpm build:dev   # 开发环境
pnpm build:test  # 测试环境

代码检查

# 运行 ESLint 检查和类型检查
pnpm lint

# 自动修复代码问题
pnpm lint:fix

# 检查 ESLint 配置
pnpm lint:check

其他工具

# 预览构建结果 (端口 9981)
pnpm preview

# 查看打包体积分析
pnpm sizecheck

项目架构

核心技术栈

  • Vue 3.5.16 + Composition API
  • Vite 6.3.5 构建工具
  • TypeScript 5.8.3 类型安全
  • Naive UI 2.41.1 组件库
  • Pinia 3.0.3 状态管理
  • Vue Router 4.5.1 路由管理
  • UnoCSS 66.2.0 原子化CSS
  • Alova 3.3.2 HTTP客户端

目录结构要点

src/
├── store/              # Pinia状态管理
│   ├── auth.ts        # 认证状态（登录、用户信息）
│   ├── router/        # 路由状态和菜单管理
│   ├── tab.ts         # 标签页状态
│   └── app/           # 应用全局状态
├── router/             # 路由配置
│   ├── index.ts       # 路由实例
│   ├── guard.ts       # 路由守卫
│   ├── routes.inner.ts # 内置路由（登录、错误页等）
│   └── routes.static.ts # 静态路由配置
├── views/              # 页面组件
├── layouts/            # 布局组件
├── components/         # 通用组件
├── service/            # API服务层
│   ├── api/           # 接口定义
│   └── http/          # HTTP配置
├── hooks/              # 组合式函数
├── utils/              # 工具函数
├── typings/            # 类型定义
└── constants/          # 常量定义

核心系统架构

1. 认证系统

  • 基于JWT Token的认证机制
  • 支持双Token（AccessToken + RefreshToken）
  • 自动Token刷新和过期处理
  • 本地存储管理（localStorage）

关键文件:

  • src/store/auth.ts - 认证状态管理
  • src/views/login/ - 登录页面组件
  • src/service/api/login.ts - 登录API接口

2. 权限系统

  • 基于角色的访问控制（RBAC）
  • 多层权限验证：路由级、组件级、API级
  • 权限指令 v-permission 和组合函数 usePermission
  • 支持super角色绕过所有权限检查

关键文件:

  • src/hooks/usePermission.ts - 权限验证组合函数
  • src/directives/permission.ts - 权限指令

3. 路由系统

  • 支持静态路由和动态路由
  • 路由守卫实现权限验证
  • 自动菜单生成和路由缓存
  • 多种布局模式支持

关键文件:

  • src/router/guard.ts - 路由守卫逻辑
  • src/store/router/ - 路由状态管理
  • src/store/router/helper.ts - 路由处理工具函数

4. 状态管理

  • 使用Pinia进行状态管理
  • 支持状态持久化
  • 模块化状态设计

状态模块:

  • authStore - 用户认证状态
  • routeStore - 路由和菜单状态
  • tabStore - 标签页状态
  • appStore - 应用全局状态

重要配置文件

环境配置

  • 支持多环境配置：dev、test、prod
  • 环境变量通过 .env.* 文件管理
  • 服务配置通过 service.config.ts 统一管理

路由配置

  • 通过 VITE_ROUTE_LOAD_MODE 控制路由加载模式
  • 静态路由配置在 src/router/routes.static.ts
  • 动态路由通过API从后端获取

权限配置

  • 角色类型：super、admin、user、editor
  • 权限验证支持单角色和多角色
  • 默认无权限要求时直接通过

开发注意事项

添加新页面

  1. 在 src/views/ 创建页面组件
  2. 在 src/router/routes.static.ts 添加路由配置
  3. 配置权限要求（roles字段）

添加新API

  1. 在 src/service/api/ 定义接口
  2. 使用项目封装的alova实例
  3. 遵循统一的响应处理格式

状态管理

  1. 新增状态优先考虑使用现有store
  2. 需要持久化的状态使用pinia-plugin-persist
  3. 计算属性优先使用computed缓存

组件开发

  1. 优先使用Naive UI组件
  2. 自定义组件放在 src/components/ 下
  3. 使用TypeScript定义组件Props和Emits

文档资源

项目包含完整的文档系统：

  • doc/auth-system.md - 认证系统文档
  • doc/permission-system.md - 权限系统文档
  • doc/router-system.md - 路由系统文档
  • doc/architecture.md - 整体架构文档

API接口

项目使用ApiFox进行接口Mock，在线文档：https://nova-admin.apifox.cn

开发环境要求

  • Node.js 21.x
  • pnpm 10.x
  • 现代浏览器支持ES6+