commit b554c14ce625f2f03f21ba9330c5500304c43336 Author: bf1942 Date: Thu Nov 13 01:00:27 2025 +0800 Initial commit: Complete工时统计系统 implementation diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..be8ba0e --- /dev/null +++ b/.gitignore @@ -0,0 +1,40 @@ +node_modules + +# Build output +dist +build + +# Environment variables +.env +.env.local +.env.development.local +.env.test.local +.env.production.local + +# IDE directories and files +.vscode/* +!.vscode/extensions.json +.idea +.DS_Store +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? + +# Testing +coverage +*.lcov +.nyc_output + +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Misc +*.local +.cache diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..71a0f69 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,32 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview +This repository is a newly initialized Node.js project focused on time-related functionality (exact scope TBD). It currently contains only core configuration files with no source code, tests, or build tools implemented yet. + +## Core Technologies +- **Node.js**: JavaScript runtime environment (type: commonjs) +- **npm**: Package manager (no dependencies installed yet) + +## Key Commands +As the project is in its early stages, only basic npm commands are available: + +```bash +# Initialize npm and install dependencies (when package.json evolves) +npm install + +# Run tests (placeholder script currently) +npm test +``` + +Future instances should update this section with actual commands for: +1. Building/linting (e.g., with TypeScript, ESLint) +2. Testing (e.g., with Jest, Mocha) +3. Development workflows (e.g., nodemon for hot reloading) + +## Architecture +No code architecture exists yet. As the repository evolves, document the high-level architecture here, focusing on: +- Major components for time-related functionality +- Core data models and algorithms +- Integration with external libraries or APIs (if any) \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..715d14f --- /dev/null +++ b/README.md @@ -0,0 +1,166 @@ +# 工时统计系统 + +一个基于 React 的现代化工时统计与管理系统，帮助团队高效追踪和管理工时记录。 + +## 功能特性 + +### 核心功能 +- 📅 **工时录入**: 便捷的表单界面，支持选择日期、项目、任务类型和时长 +- 📊 **统计报表**: 多维度的数据可视化，包括月度趋势图和项目占比环形图 +- 📈 **仪表板**: 实时显示本周、本月和累计工时，以及记录总数 +- 📋 **记录查询**: 完整的工时记录列表，支持筛选和分页 +- 💾 **数据持久化**: 使用本地存储保存数据，无需后端支持 +- 🎨 **响应式设计**: 完美适配各种屏幕尺寸 + +### 技术亮点 +- **组件化架构**: 使用 Material-UI 构建美观且一致的用户界面 +- **状态管理**: React Context API 实现全局状态共享 +- **数据可视化**: Recharts 提供强大的图表功能 +- **表单验证**: 完善的前端验证确保数据完整性 +- **类型安全**: 清晰的数据结构设计 + +## 技术栈 + +| 技术栈 | 版本 | 用途 | +|--------------|----------|-----------------------------| +| React | ^19.2.0 | 前端框架 | +| React Router | ^7.9.5 | 路由管理 | +| Material-UI | ^7.3.5 | UI 组件库 | +| Recharts | ^2.13.0 | 图表库 | +| Vite | ^6.0.1 | 构建工具 | + +## 快速开始 + +### 安装依赖 + +```bash +npm install +``` + +### 启动开发服务器 + +```bash +npm run dev +``` + +应用将在 http://localhost:3000 自动打开。 + +### 构建生产版本 + +```bash +npm run build +``` + +### 预览生产版本 + +```bash +npm run preview -- --port 3000 +``` + +## 项目结构 + +``` +time-tracking-system/ +├── src/ +│ ├── components/ # 通用组件 +│ │ └── AppLayout.jsx # 应用布局组件 +│ ├── context/ # React Context +│ │ └── TimesheetContext.jsx # 工时记录上下文 +│ ├── pages/ # 页面组件 +│ │ ├── DashboardPage.jsx # 仪表板 +│ │ ├── TimesheetPage.jsx # 工时录入 +│ │ ├── RecordsPage.jsx # 记录查询 +│ │ └── ReportsPage.jsx # 统计报表 +│ ├── App.jsx # 应用入口 +│ ├── index.jsx # React 渲染入口 +│ └── index.css # 全局样式 +├── .gitignore # Git 忽略文件 +├── package.json # 项目配置 +└── vite.config.js # Vite 配置 +``` + +## 使用指南 + +### 1. 工时录入 + +1. 进入「工时录入」页面 +2. 选择工作日期（默认为当天） +3. 选择项目（项目1/项目2/项目3） +4. 输入任务内容（详细描述工作内容） +5. 输入时长（0-24小时，支持0.5小时为单位） +6. 选择任务类型（开发/测试/文档/会议/其他） +7. 点击「保存记录」按钮完成录入 + +### 2. 仪表板 + +- **本周工时**: 显示本周累计工时 +- **本月工时**: 显示本月累计工时 +- **累计工时**: 显示所有记录的累计工时 +- **记录总数**: 显示总记录条数 +- **项目工时分布**: 按项目分类的工时占比 +- **最近记录**: 显示最新的5条工时记录 + +### 3. 记录查询 + +- 显示所有工时记录的完整列表 +- 支持分页查询（每页5/10/20条） +- 支持多选操作，可以批量删除记录 +- 点击「查看详情」可以查看记录的完整信息 +- 点击「删除」可以删除单条记录 + +### 4. 统计报表 + +- **月度趋势图**: 按周显示不同项目的工时分布 +- **项目占比环形图**: 显示各项目的工时占比情况 +- 支持按时间范围筛选数据（本周/上周/本月/上月/本季度/上季度） +- 支持生成不同类型的报表 + +## 数据结构 + +### 工时记录数据结构 + +```javascript +{ + id: 'string', // 唯一标识 + date: Date, // 工作日期 + project: 'string', // 项目名称 + task: 'string', // 任务内容 + hours: 'number', // 时长（小时） + taskType: 'string', // 任务类型 + createdAt: Date // 创建时间 +} +``` + +## 浏览器支持 + +- Chrome (推荐) +- Firefox +- Safari +- Edge + +## 许可证 + +ISC + +## 开发说明 + +### 表单验证规则 + +1. 日期：必填 +2. 项目：必填 +3. 任务内容：必填，不能为空 +4. 时长：必填，必须是0-24之间的数字，支持0.5小时为单位 +5. 任务类型：必填 + +### 数据持久化 + +- 使用 `localStorage` 保存工时记录 +- 数据自动格式化： + - `date` 和 `createdAt` 转换为 Date 对象 + - 确保数据的一致性和正确性 + +## 更新日志 + +### v1.0.0 (2025-01-13) +- 初始版本发布 +- 实现所有核心功能 \ No newline at end of file diff --git a/docs/1.md b/docs/1.md new file mode 100644 index 0000000..9e68870 --- /dev/null +++ b/docs/1.md @@ -0,0 +1,262 @@ + +# 🧭 工时统计系统 Web UI 设计建议（供实现参考） + +## 一、总体设计思路 + +目标： +构建一个简洁、专业、响应式的企业级工时统计系统前端界面，满足以下目标： + +* 清晰展示工时记录、统计趋势与项目分布； +* 操作流程自然，减少学习成本； +* 支持桌面端优先设计（Desktop-first），后续可拓展移动端适配。 + +整体风格参考 **IBM Carbon Design System** 与 **Material 3** 规范。 + +--- + +## 二、界面架构结构 + +**顶层结构（Layout Skeleton）** + +``` +┌───────────────────────────────────────────────────────┐ +│ 顶部导航栏（Header / Navbar） │ +├───────────────────────────────────────────────────────┤ +│ 主内容区（Main Content） │ +│ ├─ 侧边导航栏（可选） │ +│ └─ 内容容器（根据页面不同加载不同模块） │ +├───────────────────────────────────────────────────────┤ +│ 页脚（Footer） │ +└───────────────────────────────────────────────────────┘ +``` + +--- + +## 三、导航栏设计（Header） + +**内容结构** + +``` +[Logo 工时统计系统] 首页 | 工时记录 | 添加记录 | 报表 | 设置 [用户头像 ⬇] +``` + +**功能要求：** + +* Logo + 系统标题在左侧。 +* 中间为导航菜单，使用高亮（底部边框或字体加粗）指示当前页面。 +* 右上角为用户区域，下拉菜单包含：个人信息、登出。 +* 固定顶部（sticky header）。 + +**样式建议：** + +* 背景：#0F62FE（IBM 蓝）或白底 + 蓝色字体 +* 字体颜色：白色（深色模式）或深灰（亮色模式） +* 高度：64px +* 阴影：`box-shadow: 0 2px 4px rgba(0,0,0,0.1)` + +--- + +## 四、主要页面设计 + +### 1️⃣ 首页（Dashboard） + +**布局结构：** + +``` +┌──────────────────────────────────────────────────┐ +│ 工时总览（Summary Cards） │ +│ [本周工时] [本月工时] [平均每日工时] │ +├──────────────────────────────────────────────────┤ +│ 项目统计（Project Distribution） │ +│ 条形图或环形图展示各项目工时占比 │ +├──────────────────────────────────────────────────┤ +│ 本月趋势（Trend Chart） │ +│ 折线图：X轴=日期 / Y轴=工时 │ +└──────────────────────────────────────────────────┘ +``` + +**交互说明：** + +* 图表悬浮时显示 Tooltip（项目名 + 工时数）。 +* 点击项目可跳转至“工时记录”并自动筛选该项目。 + +**组件建议：** + +* 使用 ECharts 或 Chart.js 实现可视化。 +* 三列信息卡使用相同宽度与阴影，居中排列。 + +--- + +### 2️⃣ 工时记录页（Timesheet List） + +**布局结构：** + +``` +筛选栏 +┌─────────────────────────────┐ +│ 日期范围 | 员工 | 项目 | 状态 | [查询] [重置] │ +└─────────────────────────────┘ + +工时表格 +┌────────────────────────────────────────────────────┐ +│ 日期 | 员工 | 项目 | 工时 | 状态 | 备注 | 操作 │ +├────────────────────────────────────────────────────┤ +│ ... 数据 ... │ +└────────────────────────────────────────────────────┘ + +操作区 +[ 添加记录 ] [ 编辑选中 ] [ 删除选中 ] [ 导出 Excel ] +``` + +**交互说明：** + +* 表格支持分页、排序、筛选。 +* 点击行可展开详细信息。 +* “导出 Excel”按钮执行文件下载。 + +--- + +### 3️⃣ 添加工时记录页（Form） + +**布局：** + +``` +员工姓名: [___________] 日期: [YYYY-MM-DD] +项目选择: [___________ ▼] 工时(小时): [____] +备注: [__________________________________________] + +[ 保存记录 ] [ 重置表单 ] [ 返回列表 ] +``` + +**交互逻辑：** + +* 保存前表单验证：必填项（姓名、日期、项目、工时）； +* 保存成功后提示 “保存成功” Toast； +* 重置按钮清空输入； +* 返回列表跳转至工时记录页。 + +--- + +### 4️⃣ 报表页（Reports） + +**布局建议：左右分栏结构** + +``` +┌──────────────┬──────────────────────────┐ +│ 月度趋势图 │ 项目占比环形图 │ +│ 折线图 │ 饼/环形图 │ +│ 周1~周4数据 │ 各项目百分比 │ +└──────────────┴──────────────────────────┘ + +[ 导出 PDF ] [ 返回首页 ] +``` + +**说明：** + +* 图表均带 Hover Tooltip； +* 支持导出 PNG / PDF 报表。 + +--- + +### 5️⃣ 设置页（Settings） + +**模块划分：** + +1. 个人信息（可编辑姓名、邮箱、部门） +2. 系统偏好（主题、语言、时间格式） + +**UI 布局：** + +``` +┌────────────────────────────────┐ +│ 个人信息 │ +│ 姓名: [张三] 邮箱: [zhang@ibm.com] │ +│ 部门: [开发部] 角色: [管理员] │ +└────────────────────────────────┘ + +┌────────────────────────────────┐ +│ 系统设置 │ +│ 语言: [中文 ▼] │ +│ 主题: [亮色 ☐ 暗色 ☑] │ +│ 时间显示: [24小时制 ☑] │ +└────────────────────────────────┘ + +[ 保存设置 ] +``` + +--- + +## 五、页脚（Footer） + +**内容：** + +``` +© 2025 工时统计系统 | Powered by IBM Engineering +``` + +固定在底部，字体较小、灰色，左右居中。 + +--- + +## 六、视觉规范（Visual Guideline） + +| 元素类型 | 建议样式 | +| ---- | ----------------------------------- | +| 主色调 | IBM 蓝 #0F62FE | +| 辅助色 | 灰色背景 #F4F4F4 | +| 字体 | IBM Plex Sans, 14px, 400 weight | +| 卡片 | 白底 + 阴影 `0 1px 3px rgba(0,0,0,0.1)` | +| 按钮 | 圆角 6px，主按钮蓝底白字，次按钮灰底黑字 | +| 表格 | 条纹行、悬浮高亮行、分页控件底部对齐 | +| 表单控件 | 输入框圆角 4px，聚焦高亮边框蓝色 | +| 动效 | Hover、点击反馈 100ms ease-in-out | + +--- + +## 七、响应式设计 + +* **≥1280px（桌面端）**：三列卡片布局，图表并列显示。 +* **768px–1279px（平板端）**：卡片两列布局，图表堆叠。 +* **≤767px（手机端）**：所有模块垂直排列，表格滚动横向显示。 + +--- + +## 八、交互与反馈 + +| 事件 | 响应 | +| ---- | ------------ | +| 保存成功 | Toast 弹窗提示 | +| 删除操作 | 二次确认对话框 | +| 表单错误 | 红色提示文本 | +| 导出操作 | 文件下载 | +| 数据加载 | Skeleton 骨架屏 | + +--- + +## 九、技术栈建议（可选） + +前端建议： + +* 框架：React + Vite 或 Next.js +* UI 库：IBM Carbon Components / MUI +* 图表：ECharts / Chart.js +* 状态管理：Zustand 或 Redux Toolkit +* 样式：Tailwind / SCSS + +--- + +## 十、补充说明 + +为方便后续扩展，建议在 UI 层使用组件化设计： + +* `` +* `` +* `` +* `` +* `` + +所有交互（保存、查询、导出）应以统一的消息提示组件反馈。 + +--- + + diff --git a/docs/2.md b/docs/2.md new file mode 100644 index 0000000..aeecb3e --- /dev/null +++ b/docs/2.md @@ -0,0 +1,148 @@ +# 🧭 工时统计系统 Web UI 设计文档 + +## 一、页面流转逻辑（Page Flow） + +```mermaid +graph TD + A[登录页 /login] --> B[首页 /dashboard] + B --> C[工时录入 /timesheet] + B --> D[工时查询 /records] + B --> E[统计报表 /reports] + B --> F[个人设置 /settings] + + C --> B + D --> G[记录详情 /records/:id] + G --> D + E --> H[导出报表 /reports/export] + H --> E + F --> B +``` + +### 页面说明 + +* **登录页**：用户输入账号密码后跳转到首页。 +* **首页**：展示个人本周工时概览和快捷入口。 +* **工时录入页**：填写日期、项目、任务内容和时长。 +* **工时查询页**：查看历史工时，可筛选、分页、导出。 +* **统计报表页**：按项目、成员或时间段汇总展示。 +* **个人设置页**：修改密码、偏好、通知等。 + +--- + +## 二、组件层级结构（Component Hierarchy） + +### 1. 顶层布局 + +```plaintext + + ├──
# 顶部导航栏（系统名 + 用户信息 + 退出按钮） + ├── # 左侧菜单栏（首页/录入/查询/报表/设置） + ├── # 主内容区（根据路由动态切换） + └──