# cws **Repository Path**: john-code/cws ## Basic Information - **Project Name**: cws - **Description**: 财务系统前端 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-03-15 - **Last Updated**: 2026-03-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 家庭财务收支管理系统（前端） C 端家庭财务收支管理前端，支持登录注册、收支记录、分类与报表、成员与权限管理，界面简洁易用。前端已对接真实后端 API，需配合后端服务运行。 --- ## 目录 - [功能概览](#功能概览) - [权限与角色](#权限与角色) - [演示账号](#演示账号) - [快速开始](#快速开始) - [脚本说明](#脚本说明) - [构建与部署](#构建与部署) - [技术栈](#技术栈) - [项目结构](#项目结构) - [后端对接](#后端对接) - [后端对接：接口说明](#后端对接接口说明) --- ## 功能概览 | 功能 | 说明 | |------------|------| | 登录 / 注册 | 邮箱登录、新用户注册 | | 财务概览 | 总收入、总支出、结余与最近流水 | | 收入管理 | 按分类记录与查看收入（需「编辑收入」权限） | | 支出管理 | 按分类记录与查看支出（需「编辑支出」权限） | | 分类管理 | 收入/支出分类展示与编辑（需对应权限） | | 报表分析 | 收入/支出构成与本月汇总 | | 成员管理 | 家庭成员列表与角色（需「查看成员」/「编辑成员」） | | 权限管理 | 角色与权限矩阵说明（需「权限管理」权限） | 侧栏与各页按钮按当前用户权限显示或隐藏。 --- ## 权限与角色 | 角色 | 说明 | 权限范围 | |--------|----------|----------------------------------| | 管理员 | admin | 全部功能，含成员与权限管理 | | 成员 | member | 收支/分类/报表的查看与编辑 | | 只读 | viewer | 仅查看概览、收支、分类、报表 | --- ## 演示账号 | 邮箱 | 密码 | 角色 | |------------------|-----------|--------| | admin@home.com | admin123 | 管理员 | | member@home.com | member123 | 成员 | | viewer@home.com | viewer123 | 只读 | --- ## 快速开始 ### 环境要求 - Node.js 18+ - npm 或 pnpm ### 安装依赖 ```bash npm install ``` ### 环境变量 在项目根目录创建或编辑 `.env`，配置后端 API 地址： ```env VITE_API_BASE=http://localhost:8080/api ``` 请确保后端服务已启动（例如运行在 `http://localhost:8080`）。 ### 启动开发服务 ```bash npm run dev ``` 浏览器访问终端提示的地址（通常为 http://localhost:5173）。 ### 路由一览 | 路径 | 页面 | 说明 | |-------------|----------|----------------| | /login | 登录 | 未登录访问 / 会跳转至此 | | /register | 注册 | | | / | 财务概览 | 首页 | | /income | 收入管理 | | | /expense | 支出管理 | | | /categories | 分类管理 | | | /reports | 报表分析 | | | /users | 成员管理 | | | /permissions| 权限管理 | 角色与权限说明 | --- ## 脚本说明 | 命令 | 说明 | |----------------|------| | `npm run dev` | 启动 Vite 开发服务器 | | `npm run build`| TypeScript 编译 + Vite 构建，产物在 `dist/` | | `npm run preview` | 本地预览构建产物 | | `npm run lint` | 运行 ESLint | --- ## 构建与部署 ```bash npm run build ``` 构建产物在 `dist/` 目录，可部署到任意静态托管（如 Nginx、Vercel、OSS 等）。部署后前端通过 `.env` 中的 `VITE_API_BASE` 访问后端，生产环境需在构建前配置好该变量。 --- ## 技术栈 - React 19 + TypeScript - Vite 8 - React Router 7 - Tailwind CSS 3 - Lucide React 图标 --- ## 项目结构 ``` src/ ├── api/ # 接口封装 │ ├── client.ts # 请求客户端（Base URL、Token、错误处理） │ ├── auth.ts │ ├── records.ts │ ├── categories.ts │ ├── users.ts │ └── reports.ts ├── components/ # 通用组件 │ ├── PageHeader.tsx │ └── PermissionGuard.tsx ├── contexts/ │ └── AuthContext.tsx # 登录态与用户信息 ├── hooks/ │ └── usePermission.ts ├── layouts/ │ └── MainLayout.tsx # 侧栏 + 内容区 ├── pages/ # 页面 │ ├── Login.tsx / Register.tsx │ ├── Dashboard.tsx / Income.tsx / Expense.tsx │ ├── Categories.tsx / Reports.tsx │ ├── Users.tsx / Permissions.tsx │ └── ... ├── types/ │ ├── auth.ts # User、Role、权限常量 │ └── record.ts # RecordItem、Category ├── App.tsx ├── main.tsx └── index.css ``` --- ## 后端对接 - **Base URL**：由 `.env` 中的 `VITE_API_BASE` 指定（如 `http://localhost:8080/api`）。 - **认证**：登录/注册成功后，前端将返回的 `token` 存入 localStorage，后续请求自动携带 `Authorization: Bearer `。 - **接口约定**：路径、请求体、响应体与下方「后端对接：接口说明」一致即可；类型定义见 `src/types/auth.ts`、`src/types/record.ts`。后端接口的权威说明以后端项目文档为准（如 `docs/API-CURL-REFERENCE.md`）。 ### 已知后端问题 若某些接口异常（如记录列表报 500），请参见 **[后端问题.md](./后端问题.md)**，其中整理了需后端修复的问题与复现方式，修复后前端无需改动即可正常使用。 --- ## 后端对接：接口说明 以下为前端侧归纳的接口约定，与当前前端实现保持一致。对接时保证路径、请求体、响应体与此一致（或与 `types/auth.ts`、`types/record.ts` 兼容）即可。 ### 约定 - **Base URL**：由前端环境变量指定，例如 `VITE_API_BASE=http://localhost:8080/api`。 - **认证**：使用 **Bearer Token**。登录/注册成功后返回 `token`，前端在后续请求头中携带：`Authorization: Bearer `。 - **通用错误响应**：建议统一格式，便于前端提示： ```json { "code": 400, "message": "错误描述" } ``` - **日期格式**：`date`、`createdAt` 等建议使用 **ISO 8601**（如 `2025-03-15`、`2025-03-15T08:00:00Z`）。 --- ### 1. 认证 #### 1.1 登录 - **请求**：`POST /auth/login` - **Body**： ```json { "email": "user@example.com", "password": "plain_password" } ``` - **成功响应**（200）： ```json { "token": "jwt_or_session_token_string", "user": { "id": "1", "name": "张三", "email": "user@example.com", "role": "admin", "avatar": "https://..." } } ``` - **失败**：401 或 4xx，Body 中 `message` 说明原因。 #### 1.2 注册 - **请求**：`POST /auth/register` - **Body**： ```json { "name": "张三", "email": "user@example.com", "password": "plain_password" } ``` - **成功响应**（201 或 200）：同上，含 `token`、`user`。新注册用户建议默认角色为 `member`。 - **失败**：如邮箱已注册，建议 409 或 400，`message` 如「该邮箱已被注册」。 #### 1.3 登出（可选） - **请求**：`POST /auth/logout` - **Header**：`Authorization: Bearer ` - 前端也可仅清除本地 token；若后端有会话/黑名单，可调用此接口使服务端会话失效。 #### 1.4 获取当前用户（可选） - **请求**：`GET /auth/me` 或 `GET /users/me` - **Header**：`Authorization: Bearer ` - **成功响应**（200）：单用户对象 `{ id, name, email, role, avatar? }`。 - **失败**：401 表示未登录或 token 失效，前端跳转登录页。 --- ### 2. 收支记录 `RecordItem` 含 `id, type, amount, categoryId, category?, remark?, date, createdAt`。`type` 为 `"income"` 或 `"expense"`。 #### 2.1 记录列表 - **请求**：`GET /records` - **Header**：`Authorization: Bearer ` - **Query**（均可选）：`type`、`categoryId`、`startDate`、`endDate`、`page`、`pageSize` - **成功响应**（200）： ```json { "list": [ { "id": "r1", "type": "income", "amount": 15000, "categoryId": "c1", "category": { "id": "c1", "name": "工资", "type": "income", "icon": "Wallet", "color": "#14b8a6" }, "remark": "月薪", "date": "2025-03-10", "createdAt": "2025-03-10T09:00:00Z" } ], "total": 100 } ``` 若无分页，可只返回 `{ "list": [...] }`。 #### 2.2 创建记录 - **请求**：`POST /records` - **Body**：`{ "type", "amount", "categoryId", "remark?", "date" }` - **成功响应**（201 或 200）：返回完整单条记录（含 `id`、`createdAt`、嵌套 `category`）。 #### 2.3 更新记录 - **请求**：`PUT /records/:id` 或 `PATCH /records/:id` - **Body**：同创建，可只传要更新的字段。 - **成功响应**（200）：返回更新后的完整记录。 #### 2.4 删除记录 - **请求**：`DELETE /records/:id` - **成功响应**：204 或 200。 --- ### 3. 分类 `Category` 含 `id, name, type, icon, color`。`type` 为 `"income"` 或 `"expense"`。 #### 3.1 分类列表 - **请求**：`GET /categories` - **Query**（可选）：`type` = `income` | `expense` - **成功响应**（200）：数组，如 `[{ "id", "name", "type", "icon", "color" }, ...]`。 #### 3.2 创建 / 更新 / 删除 - **创建**：`POST /categories`，Body：`{ "name", "type", "icon", "color" }`，返回完整分类（含 `id`）。 - **更新**：`PUT /categories/:id` 或 `PATCH /categories/:id`，Body 可部分字段。 - **删除**：`DELETE /categories/:id`，成功 204 或 200。若有记录引用该分类，建议 400 并提示先处理相关记录。 --- ### 4. 成员 `User` 含 `id, name, email, role, avatar?`。`role` 为 `admin` | `member` | `viewer`。 #### 4.1 成员列表 - **请求**：`GET /users` 或 `GET /family/members` - **成功响应**（200）：用户数组。仅返回当前家庭/账户下成员。 #### 4.2 邀请成员（可选） - **请求**：`POST /users/invite` 或 `POST /family/invitations` - **Body**：`{ "email", "role" }` #### 4.3 修改成员角色 - **请求**：`PUT /users/:id/role` 或 `PATCH /users/:id` - **Body**：`{ "role": "member" }` - **成功响应**（200）：返回更新后用户或 204。建议仅 admin 可调。 --- ### 5. 报表/统计（可选） 报表页可由前端根据「记录列表」在本地聚合。若由后端汇总，可提供： - **请求**：`GET /reports/summary` - **Query**：`startDate`、`endDate` - **成功响应**（200）示例：`{ "totalIncome", "totalExpense", "incomeByCategory", "expenseByCategory" }`。 若不提供，前端继续用「记录列表 + 日期筛选」在本地计算。 --- ### 6. 接口汇总表 | 功能 | 方法 | 路径 | 说明 | |----------|--------|--------------------|------| | 登录 | POST | /auth/login | Body: email, password | | 注册 | POST | /auth/register | Body: name, email, password | | 登出 | POST | /auth/logout | 可选 | | 当前用户 | GET | /auth/me | 可选 | | 记录列表 | GET | /records | Query: type, categoryId, startDate, endDate, page, pageSize | | 创建记录 | POST | /records | Body: type, amount, categoryId, remark?, date | | 更新记录 | PUT | /records/:id | Body: 同创建 | | 删除记录 | DELETE | /records/:id | | | 分类列表 | GET | /categories | Query: type? | | 创建分类 | POST | /categories | Body: name, type, icon, color | | 更新分类 | PUT | /categories/:id | | | 删除分类 | DELETE | /categories/:id | | | 成员列表 | GET | /users | 或 /family/members | | 邀请成员 | POST | /users/invite | 可选，Body: email, role | | 修改角色 | PUT | /users/:id/role | Body: role | | 报表汇总 | GET | /reports/summary | 可选，Query: startDate, endDate |