CLAUDE.mdjavascript

hetong CLAUDE.md

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

View Source

CLAUDE.md

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

项目概述

这是一个基于 Vue 3 + Express.js 的现代化合同审核管理系统，提供完整的合同提交、审核、管理功能。系统采用前后端分离架构，使用 SQLite 作为数据库，实现了基于角色的访问控制（RBAC）。

开发环境设置

启动后端服务

cd backend
npm install
npm run init-db  # 初始化数据库（仅首次运行）
npm run dev      # 启动开发服务器（端口 3000）

启动前端服务

cd frontend
npm install
npm run dev      # 启动开发服务器（端口 5173）

生产环境构建

# 构建前端
cd frontend
npm run build

# 启动生产服务器
cd backend
NODE_ENV=production npm start

项目架构

后端架构 (backend/)

  • Express.js 应用，主入口文件：src/app.js
  • SQLite 数据库，位于 database.sqlite
  • JWT 认证系统，配置在 src/utils/constants.js
  • 中间件系统：
    • src/middleware/auth.js - JWT 认证中间件
    • src/middleware/rbac.js - 基于角色的访问控制
    • src/middleware/permission.js - 权限检查
    • src/middleware/upload.js - 文件上传处理
  • 路由系统：RESTful API 设计，所有路由在 src/routes/ 目录下
  • 数据库操作：src/utils/database.js 提供统一的数据库操作类

前端架构 (frontend/)

  • Vue 3 + Composition API + Element Plus UI 库
  • Vite 构建工具，配置文件：vite.config.js
  • Vue Router 4 路由管理
  • Pinia 状态管理，主要存储在 src/stores/
  • 组件系统：
    • src/components/common/ - 通用组件
    • src/components/contract/ - 合同相关组件
    • src/components/layout/ - 布局组件
    • src/components/user/ - 用户相关组件
  • Composables：业务逻辑复用，位于 src/composables/

数据库结构

主要数据表：

  • users - 用户表（用户名、密码、角色、状态等）
  • contracts - 合同表（流水号、文件信息、状态、审核信息等）
  • notifications - 通知表
  • operation_logs - 操作日志表

用户权限系统

角色定义

  • employee - 员工：可提交合同、查看自己的合同
  • reviewer - 审核员：可审核分配的合同
  • admin - 管理员：拥有所有权限

权限控制

  • 后端：基于 JWT token 和角色检查
  • 前端：路由守卫 + 组件权限指令
  • 权限配置在 backend/src/utils/constants.js 中定义

核心功能模块

合同管理

  • 流水号生成：自动生成 HT001 格式的流水号
  • 文件上传：支持 PDF 文件上传，限制 10MB
  • 状态流转：pending → reviewing → approved/rejected
  • 审核流程：支持审核员分配、审核意见、审核历史

文件处理

  • 上传目录：backend/uploads/
  • 文件预览：前端 PDF 预览组件
  • 文件下载：权限控制的文件下载接口

开发规范

API 设计

  • RESTful 风格，统一返回格式
  • 错误处理：统一的错误码和消息
  • 分页：默认 page=1, pageSize=10

数据验证

  • 后端：express-validator 进行参数验证
  • 前端：Element Plus 表单验证

日志记录

  • 操作日志：记录用户操作到 operation_logs 表
  • 服务器日志：使用 morgan 中间件

测试与调试

默认测试账号

  • 管理员：admin / admin123
  • 员工：employee / 123456
  • 审核员：reviewer / 123456

数据库重置

cd backend
rm database.sqlite  # 删除现有数据库
npm run init-db     # 重新初始化

开发调试

  • 前端开发模式：热重载，代理到后端 API
  • 后端开发模式：使用 nodemon 自动重启

部署注意事项

环境变量

后端支持的环境变量：

  • NODE_ENV - 运行环境
  • PORT - 服务端口（默认 3000）
  • JWT_SECRET - JWT 密钥
  • FRONTEND_URL - 前端地址（CORS 配置）

生产环境

  • 前端构建后静态文件在 frontend/dist/
  • 后端使用 PM2 或类似工具管理进程
  • 文件上传目录需要适当的权限设置

常见问题

文件上传失败

  • 检查文件大小是否超过 10MB
  • 检查文件类型是否为 PDF
  • 检查上传目录权限

数据库连接问题

  • 确保 SQLite 文件权限正确
  • 检查数据库初始化是否完成

权限相关问题

  • 检查 JWT token 是否过期
  • 确认用户角色和权限配置
  • 验证路由权限中间件配置