963 lines
29 KiB
Markdown
963 lines
29 KiB
Markdown
# 项目信息管理系统 - 设计文档
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 项目背景
|
||
开发一个基于BS架构的项目信息管理系统，用于管理项目的合同、编号、名称、预算、付款等信息。系统支持多部门协作，市场部用户可以新建项目，其他部门用户可以填写和更新项目信息。
|
||
|
||
### 1.2 技术选型
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 前端 | React + React Router | 前后端分离架构 |
|
||
| UI组件库 | Ant Design | 企业级UI组件 |
|
||
| HTTP客户端 | Axios | API请求 |
|
||
| 状态管理 | Context API | 简单状态管理 |
|
||
| 后端 | Python Flask | 轻量级Web框架 |
|
||
| ORM | SQLAlchemy | 数据库ORM |
|
||
| 数据库 | MySQL | 关系型数据库 |
|
||
| 认证 | JWT Token | 无状态认证 |
|
||
| 开发工具 | Create React App, pipenv | 前后端开发环境 |
|
||
|
||
### 1.3 系统特点
|
||
- 轻量级架构，适合小并发场景
|
||
- 无需Redis缓存，降低部署复杂度
|
||
- 基于角色的权限控制（RBAC）
|
||
- 前后端分离，易于维护和扩展
|
||
|
||
## 2. 功能需求
|
||
|
||
### 2.1 用户管理
|
||
|
||
#### 2.1.1 登录功能
|
||
- 用户名/密码登录
|
||
- JWT Token认证
|
||
- 自动登录（Token存储在LocalStorage）
|
||
|
||
#### 2.1.2 用户管理（管理员）
|
||
- 创建用户：设置用户名、密码、部门、角色
|
||
- 编辑用户信息
|
||
- 删除用户
|
||
- 重置用户密码
|
||
- 查看用户列表
|
||
|
||
#### 2.1.3 权限控制
|
||
- **管理员**：所有权限
|
||
- **市场部用户**：创建项目、查看项目、编辑自己的项目
|
||
- **其他部门用户**：查看项目、编辑项目信息（如付款、状态等）
|
||
|
||
### 2.2 项目管理
|
||
|
||
#### 2.2.1 市场部权限
|
||
- **创建项目**：填写项目基本信息
|
||
- **查看项目**：浏览所有项目列表和详情
|
||
- **编辑项目**：修改自己创建的项目
|
||
|
||
#### 2.2.2 其他部门权限
|
||
- **查看项目**：浏览所有项目列表和详情
|
||
- **更新项目**：填写和更新项目信息（预算、付款、状态等）
|
||
|
||
#### 2.2.3 项目信息字段
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| project_no | String | 是 | 项目编号（唯一） |
|
||
| contract_no | String | 是 | 合同编号 |
|
||
| name | String | 是 | 项目名称 |
|
||
| budget | Decimal | 是 | 项目预算 |
|
||
| payment_amount | Decimal | 否 | 已付款金额 |
|
||
| status | String | 是 | 项目状态（灵活状态） |
|
||
| start_date | Date | 否 | 开始日期 |
|
||
| end_date | Date | 否 | 结束日期 |
|
||
| created_by | Integer | 是 | 创建人ID（外键） |
|
||
| department | String | 是 | 所属部门 |
|
||
| description | Text | 否 | 项目描述 |
|
||
| created_at | DateTime | 是 | 创建时间 |
|
||
| updated_at | DateTime | 是 | 更新时间 |
|
||
|
||
#### 2.2.4 项目状态示例
|
||
- 新建
|
||
- 进行中
|
||
- 已完成
|
||
- 已暂停
|
||
- 已取消
|
||
|
||
（支持灵活状态，可由用户自定义）
|
||
|
||
## 3. 系统架构
|
||
|
||
### 3.1 架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 浏览器 │
|
||
│ (React + Ant Design + React Router + Axios) │
|
||
└─────────────────────────────────────────────────┘
|
||
│
|
||
│ HTTP/HTTPS
|
||
│ JWT Token
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Flask 后端服务 │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ API Layer (Flask Routes) │ │
|
||
│ ├─────────────────────────────────────────┤ │
|
||
│ │ Business Logic (Services) │ │
|
||
│ ├─────────────────────────────────────────┤ │
|
||
│ │ Data Access (SQLAlchemy ORM) │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────┘
|
||
│
|
||
│ SQL
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ MySQL 数据库 │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ users │ │
|
||
│ │ projects │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 项目目录结构
|
||
|
||
```
|
||
ocean_project_manager/
|
||
├── backend/ # 后端程序员工作区
|
||
│ ├── src/ # 源代码
|
||
│ │ ├── controllers/ # 控制器层
|
||
│ │ │ ├── auth.py # 认证相关
|
||
│ │ │ ├── users.py # 用户管理
|
||
│ │ │ └── projects.py # 项目管理
|
||
│ │ ├── services/ # 业务逻辑层
|
||
│ │ │ ├── auth_service.py
|
||
│ │ │ ├── user_service.py
|
||
│ │ │ └── project_service.py
|
||
│ │ ├── models/ # 数据模型层
|
||
│ │ │ ├── user.py
|
||
│ │ │ └── project.py
|
||
│ │ ├── routes/ # 路由定义
|
||
│ │ │ ├── auth.py
|
||
│ │ │ ├── users.py
|
||
│ │ │ └── projects.py
|
||
│ │ ├── middleware/ # 中间件
|
||
│ │ │ ├── jwt_middleware.py
|
||
│ │ │ └── auth_middleware.py
|
||
│ │ └── utils/ # 工具函数
|
||
│ │ ├── jwt_utils.py
|
||
│ │ └── password_utils.py
|
||
│ ├── tests/ # 单元测试和集成测试
|
||
│ ├── docs/ # API文档和技术文档
|
||
│ │ └── api.md # API文档
|
||
│ ├── config/ # 配置文件
|
||
│ ├── requirements.txt # Python依赖
|
||
│ ├── run.py # 启动文件
|
||
│ ├── WORKSTANDARDS.md # 后端程序员工作规范
|
||
│ └── README.md # 后端开发说明
|
||
│
|
||
├── frontend/ # 前端程序员工作区
|
||
│ ├── src/ # 源代码
|
||
│ │ ├── components/ # 可复用组件
|
||
│ │ │ ├── Layout.jsx
|
||
│ │ │ ├── Header.jsx
|
||
│ │ │ └── Sidebar.jsx
|
||
│ │ ├── pages/ # 页面组件
|
||
│ │ │ ├── Login.jsx
|
||
│ │ │ ├── Dashboard.jsx
|
||
│ │ │ ├── UserList.jsx
|
||
│ │ │ ├── UserForm.jsx
|
||
│ │ │ ├── ProjectList.jsx
|
||
│ │ │ ├── ProjectForm.jsx
|
||
│ │ │ └── ProjectDetail.jsx
|
||
│ │ ├── hooks/ # 自定义Hooks
|
||
│ │ │ └── useAuth.js
|
||
│ │ ├── services/ # API服务
|
||
│ │ │ ├── api.js # Axios配置
|
||
│ │ │ ├── auth.js
|
||
│ │ │ ├── user.js
|
||
│ │ │ └── project.js
|
||
│ │ ├── utils/ # 工具函数
|
||
│ │ │ └── auth.js
|
||
│ │ ├── styles/ # 样式文件
|
||
│ │ │ └── global.css
|
||
│ │ ├── types/ # TypeScript类型定义
|
||
│ │ │ ├── user.ts
|
||
│ │ │ └── project.ts
|
||
│ │ ├── App.jsx # 根组件
|
||
│ │ └── index.js # 入口文件
|
||
│ ├── tests/ # 组件测试
|
||
│ ├── docs/ # 组件文档和开发文档
|
||
│ │ └── components.md # 组件文档
|
||
│ ├── package.json
|
||
│ ├── WORKSTANDARDS.md # 前端程序员工作规范
|
||
│ └── README.md # 前端开发说明
|
||
│
|
||
├── testing/ # 测试工程师工作区
|
||
│ ├── testcases/ # 测试用例
|
||
│ │ ├── api/ # API测试用例
|
||
│ │ │ ├── auth_test.json
|
||
│ │ │ ├── user_test.json
|
||
│ │ │ └── project_test.json
|
||
│ │ ├── ui/ # UI测试用例
|
||
│ │ │ ├── login_test.json
|
||
│ │ │ ├── user_list_test.json
|
||
│ │ │ └── project_list_test.json
|
||
│ │ └── integration/ # 集成测试用例
|
||
│ │ └── workflow_test.json
|
||
│ ├── reports/ # 测试报告
|
||
│ ├── data/ # 测试数据
|
||
│ ├── scripts/ # 自动化测试脚本
|
||
│ │ ├── api_test.py # API自动化测试
|
||
│ │ └── ui_test.js # UI自动化测试
|
||
│ ├── docs/ # 测试文档
|
||
│ │ ├── test_plan.md # 测试计划
|
||
│ │ └── test_strategy.md # 测试策略
|
||
│ ├── WORKSTANDARDS.md # 测试工程师工作规范
|
||
│ └── README.md # 测试工作说明
|
||
│
|
||
├── docs/ # 项目文档
|
||
│ ├── plans/ # 设计文档
|
||
│ │ └── 2026-01-24-project-management-system-design.md
|
||
│ ├── ui-design-spec.md # UI设计规范
|
||
│ ├── pid.md # 项目信息文档（本文档）
|
||
│ └── TEAM-COLLABORATION.md # 团队协作规范
|
||
│
|
||
├── ACCESS-CONTROL.md # 权限控制文档
|
||
├── README.md # 项目说明
|
||
└── .git/ # Git仓库
|
||
```
|
||
|
||
### 3.3 工作目录说明
|
||
|
||
#### 后端程序员工作区 (`backend/`)
|
||
- **负责**: 后端API开发、数据库设计、单元测试编写
|
||
- **主要工作**: 在 `backend/src/` 中编写业务代码
|
||
- **输出文档**: `backend/docs/api.md` - API文档
|
||
- **测试**: `backend/tests/` - 单元测试和集成测试
|
||
|
||
#### 前端程序员工作区 (`frontend/`)
|
||
- **负责**: 前端UI开发、组件封装、API集成
|
||
- **主要工作**: 在 `frontend/src/` 中编写UI组件
|
||
- **输出文档**: `frontend/docs/components.md` - 组件文档
|
||
- **测试**: `frontend/tests/` - 组件测试
|
||
|
||
#### 测试工程师工作区 (`testing/`)
|
||
- **负责**: 测试计划编写、测试用例设计、自动化测试
|
||
- **主要工作**: 在 `testing/testcases/` 中编写测试用例
|
||
- **输出文档**: `testing/reports/` - 测试报告
|
||
- **自动化**: `testing/scripts/` - 自动化测试脚本
|
||
|
||
### 3.4 权限限制
|
||
|
||
⚠️ **严格遵守工作目录限制**
|
||
|
||
- 后端程序员只能在 `backend/` 目录中工作
|
||
- 前端程序员只能在 `frontend/` 目录中工作
|
||
- 测试工程师只能在 `testing/` 目录中工作
|
||
|
||
跨目录工作需要技术总监批准，详见 [ACCESS-CONTROL.md](../ACCESS-CONTROL.md)
|
||
|
||
## 4. 团队协作
|
||
|
||
### 4.1 角色职责
|
||
|
||
#### 技术总监
|
||
- 审查设计方案和技术文档
|
||
- Review代码质量和架构设计
|
||
- 协调团队协作，解决技术分歧
|
||
- 批准重大变更和跨目录访问请求
|
||
|
||
#### 后端程序员
|
||
- **工作目录**: `backend/`
|
||
- **主要职责**:
|
||
- 设计和实现后端API接口
|
||
- 编写API文档 (`backend/docs/api.md`)
|
||
- 编写单元测试，确保测试覆盖率 > 80%
|
||
- 参与技术方案讨论和代码审查
|
||
|
||
#### 前端程序员
|
||
- **工作目录**: `frontend/`
|
||
- **主要职责**:
|
||
- 实现前端UI组件和页面
|
||
- 编写组件文档 (`frontend/docs/components.md`)
|
||
- 集成后端API，确保前后端对接
|
||
- 遵循UI设计规范 (`docs/ui-design-spec.md`)
|
||
|
||
#### 测试工程师
|
||
- **工作目录**: `testing/`
|
||
- **主要职责**:
|
||
- 编写测试计划和测试用例
|
||
- 执行功能测试、UI测试、自动化测试
|
||
- 生成测试报告和Bug报告
|
||
- 验证Bug修复效果
|
||
|
||
### 4.2 工作流程
|
||
|
||
#### 4.2.1 需求分析阶段
|
||
1. 技术总监编写设计方案 (`docs/plans/`)
|
||
2. 后端程序员和前端程序员查看设计方案
|
||
3. 测试工程师编写测试计划 (`testing/docs/`)
|
||
|
||
#### 4.2.2 后端开发流程
|
||
1. 后端程序员在 `backend/src/` 中开发API
|
||
2. 编写单元测试 (`backend/tests/`)
|
||
3. 更新API文档 (`backend/docs/api.md`)
|
||
4. 提交代码进行审查
|
||
|
||
#### 4.2.3 前端开发流程
|
||
1. 前端程序员查看API文档 (`backend/docs/api.md`)
|
||
2. 在 `frontend/src/` 中开发UI组件
|
||
3. 集成后端API
|
||
4. 编写组件测试 (`frontend/tests/`)
|
||
5. 提交代码进行审查
|
||
|
||
#### 4.2.4 测试流程
|
||
1. 测试工程师执行测试用例 (`testing/testcases/`)
|
||
2. 记录Bug和问题
|
||
3. 生成测试报告 (`testing/reports/`)
|
||
4. 后端程序员和前端程序员根据Bug报告修复问题
|
||
5. 测试工程师验证修复效果
|
||
|
||
#### 4.2.5 代码审查流程
|
||
1. 开发人员提交Pull Request
|
||
2. 技术总监审查代码质量、文档完整性、测试覆盖率
|
||
3. 如有问题，退回修改；如通过，合并到主分支
|
||
|
||
### 4.3 代码提交规范
|
||
|
||
#### 提交信息格式
|
||
- 后端程序员: `[backend] <类型>: <描述>`
|
||
- 前端程序员: `[frontend] <类型>: <描述>`
|
||
- 测试工程师: `[testing] <类型>: <描述>`
|
||
|
||
#### 类型说明
|
||
- `feat`: 新功能
|
||
- `fix`: Bug修复
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式调整
|
||
- `refactor`: 代码重构
|
||
- `test`: 测试相关
|
||
- `chore`: 构建或工具相关
|
||
|
||
#### 示例
|
||
```
|
||
[backend] feat: 添加用户认证API
|
||
[frontend] fix: 修复项目列表分页问题
|
||
[testing] test: 添加用户登录API测试用例
|
||
```
|
||
|
||
### 4.4 文档规范
|
||
|
||
#### 后端文档
|
||
- **API文档**: `backend/docs/api.md`
|
||
- 使用OpenAPI/Swagger格式
|
||
- 包含: 接口路径、请求方法、参数、返回值、错误码
|
||
|
||
#### 前端文档
|
||
- **组件文档**: `frontend/docs/components.md`
|
||
- 包含: 组件名称、Props、使用示例、截图
|
||
|
||
#### 测试文档
|
||
- **测试计划**: `testing/docs/test_plan.md`
|
||
- **测试报告**: `testing/reports/` 目录
|
||
- **Bug报告**: 包含标题、重现步骤、预期结果、实际结果、截图/日志
|
||
|
||
### 4.5 沟通机制
|
||
|
||
#### 日常沟通
|
||
- 各角色在各自目录中独立工作
|
||
- 需要协作时通过技术总监协调
|
||
|
||
#### 文档沟通
|
||
- 后端API文档作为前后端对接的桥梁
|
||
- 测试报告作为Bug修复的依据
|
||
- 所有重要决策记录在项目文档中
|
||
|
||
#### 技术总监审查
|
||
- 所有设计方案需要技术总监批准
|
||
- 所有代码合并需要技术总监审查
|
||
- 重大变更需要技术总监批准
|
||
|
||
## 5. 数据库设计
|
||
|
||
### 5.1 数据库表结构
|
||
|
||
#### 4.1.1 用户表 (users)
|
||
|
||
| 字段名 | 类型 | 约束 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
|
||
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
|
||
| password_hash | VARCHAR(255) | NOT NULL | 密码哈希 |
|
||
| real_name | VARCHAR(100) | NOT NULL | 真实姓名 |
|
||
| department | VARCHAR(50) | NOT NULL | 部门（市场部/技术部/财务部等） |
|
||
| role | ENUM | NOT NULL | 角色（admin/market/other） |
|
||
| email | VARCHAR(100) | UNIQUE | 邮箱 |
|
||
| phone | VARCHAR(20) | | 电话 |
|
||
| is_active | BOOLEAN | DEFAULT TRUE | 是否激活 |
|
||
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
|
||
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |
|
||
|
||
```sql
|
||
CREATE TABLE users (
|
||
id INT PRIMARY KEY AUTO_INCREMENT,
|
||
username VARCHAR(50) UNIQUE NOT NULL,
|
||
password_hash VARCHAR(255) NOT NULL,
|
||
real_name VARCHAR(100) NOT NULL,
|
||
department VARCHAR(50) NOT NULL,
|
||
role ENUM('admin', 'market', 'other') NOT NULL,
|
||
email VARCHAR(100) UNIQUE,
|
||
phone VARCHAR(20),
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- 索引
|
||
CREATE INDEX idx_users_username ON users(username);
|
||
CREATE INDEX idx_users_department ON users(department);
|
||
CREATE INDEX idx_users_role ON users(role);
|
||
```
|
||
|
||
#### 4.1.2 项目表 (projects)
|
||
|
||
| 字段名 | 类型 | 约束 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 项目ID |
|
||
| project_no | VARCHAR(50) | UNIQUE, NOT NULL | 项目编号 |
|
||
| contract_no | VARCHAR(50) | NOT NULL | 合同编号 |
|
||
| name | VARCHAR(200) | NOT NULL | 项目名称 |
|
||
| budget | DECIMAL(15,2) | NOT NULL | 项目预算 |
|
||
| payment_amount | DECIMAL(15,2) | DEFAULT 0 | 已付款金额 |
|
||
| status | VARCHAR(50) | NOT NULL | 项目状态 |
|
||
| start_date | DATE | | 开始日期 |
|
||
| end_date | DATE | | 结束日期 |
|
||
| created_by | INT | NOT NULL, FOREIGN KEY | 创建人ID |
|
||
| department | VARCHAR(50) | NOT NULL | 所属部门 |
|
||
| description | TEXT | | 项目描述 |
|
||
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
|
||
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |
|
||
|
||
```sql
|
||
CREATE TABLE projects (
|
||
id INT PRIMARY KEY AUTO_INCREMENT,
|
||
project_no VARCHAR(50) UNIQUE NOT NULL,
|
||
contract_no VARCHAR(50) NOT NULL,
|
||
name VARCHAR(200) NOT NULL,
|
||
budget DECIMAL(15,2) NOT NULL,
|
||
payment_amount DECIMAL(15,2) DEFAULT 0,
|
||
status VARCHAR(50) NOT NULL,
|
||
start_date DATE,
|
||
end_date DATE,
|
||
created_by INT NOT NULL,
|
||
department VARCHAR(50) NOT NULL,
|
||
description TEXT,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE RESTRICT
|
||
);
|
||
|
||
-- 索引
|
||
CREATE INDEX idx_projects_project_no ON projects(project_no);
|
||
CREATE INDEX idx_projects_contract_no ON projects(contract_no);
|
||
CREATE INDEX idx_projects_status ON projects(status);
|
||
CREATE INDEX idx_projects_department ON projects(department);
|
||
CREATE INDEX idx_projects_created_by ON projects(created_by);
|
||
```
|
||
|
||
### 5.2 角色权限矩阵
|
||
|
||
| 功能 | admin | market | other |
|
||
|------|-------|--------|-------|
|
||
| 登录 | ✓ | ✓ | ✓ |
|
||
| 创建用户 | ✓ | ✗ | ✗ |
|
||
| 编辑用户 | ✓ | ✗ | ✗ |
|
||
| 删除用户 | ✓ | ✗ | ✗ |
|
||
| 查看用户列表 | ✓ | ✗ | ✗ |
|
||
| 创建项目 | ✓ | ✓ | ✗ |
|
||
| 编辑项目信息 | ✓ | ✓ | ✓ |
|
||
| 删除项目 | ✓ | ✓ | ✗ |
|
||
| 查看所有项目 | ✓ | ✓ | ✓ |
|
||
| 查看项目详情 | ✓ | ✓ | ✓ |
|
||
|
||
## 6. API设计
|
||
|
||
### 6.1 API规范
|
||
|
||
- **Base URL**: `/api/v1`
|
||
- **Content-Type**: `application/json`
|
||
- **认证方式**: JWT Token（在Header中传递：`Authorization: Bearer <token>`）
|
||
- **响应格式**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 6.2 认证相关API
|
||
|
||
#### 5.2.1 用户登录
|
||
- **URL**: `POST /api/v1/auth/login`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "password123"
|
||
}
|
||
```
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"user": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"real_name": "管理员",
|
||
"department": "管理部",
|
||
"role": "admin"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.2.2 获取当前用户信息
|
||
- **URL**: `GET /api/v1/auth/me`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"real_name": "管理员",
|
||
"department": "管理部",
|
||
"role": "admin"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.2.3 登出
|
||
- **URL**: `POST /api/v1/auth/logout`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "登出成功"
|
||
}
|
||
```
|
||
|
||
### 6.3 用户管理API
|
||
|
||
#### 5.3.1 获取用户列表
|
||
- **URL**: `GET /api/v1/users`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin
|
||
- **查询参数**:
|
||
- `page`: 页码（默认1）
|
||
- `page_size`: 每页数量（默认10）
|
||
- `department`: 部门筛选
|
||
- `role`: 角色筛选
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"username": "admin",
|
||
"real_name": "管理员",
|
||
"department": "管理部",
|
||
"role": "admin",
|
||
"email": "admin@example.com",
|
||
"is_active": true,
|
||
"created_at": "2026-01-24T10:00:00"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.3.2 创建用户
|
||
- **URL**: `POST /api/v1/users`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"username": "zhangsan",
|
||
"password": "password123",
|
||
"real_name": "张三",
|
||
"department": "市场部",
|
||
"role": "market",
|
||
"email": "zhangsan@example.com",
|
||
"phone": "13800138000"
|
||
}
|
||
```
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "用户创建成功",
|
||
"data": {
|
||
"id": 2,
|
||
"username": "zhangsan",
|
||
"real_name": "张三",
|
||
"department": "市场部",
|
||
"role": "market"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.3.3 更新用户
|
||
- **URL**: `PUT /api/v1/users/{id}`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"real_name": "张三",
|
||
"email": "zhangsan2@example.com",
|
||
"phone": "13900139000"
|
||
}
|
||
```
|
||
|
||
#### 5.3.4 删除用户
|
||
- **URL**: `DELETE /api/v1/users/{id}`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin
|
||
|
||
#### 5.3.5 重置用户密码
|
||
- **URL**: `POST /api/v1/users/{id}/reset-password`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"new_password": "newpassword123"
|
||
}
|
||
```
|
||
|
||
### 6.4 项目管理API
|
||
|
||
#### 5.4.1 获取项目列表
|
||
- **URL**: `GET /api/v1/projects`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: 所有用户
|
||
- **查询参数**:
|
||
- `page`: 页码（默认1）
|
||
- `page_size`: 每页数量（默认10）
|
||
- `status`: 状态筛选
|
||
- `department`: 部门筛选
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"project_no": "PRJ2026001",
|
||
"contract_no": "CT2026001",
|
||
"name": "某公司官网开发",
|
||
"budget": 50000.00,
|
||
"payment_amount": 25000.00,
|
||
"status": "进行中",
|
||
"start_date": "2026-01-01",
|
||
"end_date": "2026-03-31",
|
||
"department": "市场部",
|
||
"created_by": {
|
||
"id": 2,
|
||
"real_name": "张三"
|
||
},
|
||
"created_at": "2026-01-24T10:00:00"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"page_size": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.4.2 获取项目详情
|
||
- **URL**: `GET /api/v1/projects/{id}`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: 所有用户
|
||
|
||
#### 5.4.3 创建项目
|
||
- **URL**: `POST /api/v1/projects`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin, market
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"project_no": "PRJ2026002",
|
||
"contract_no": "CT2026002",
|
||
"name": "电商平台开发",
|
||
"budget": 100000.00,
|
||
"status": "新建",
|
||
"start_date": "2026-02-01",
|
||
"end_date": "2026-06-30",
|
||
"department": "市场部",
|
||
"description": "电商平台开发项目"
|
||
}
|
||
```
|
||
|
||
#### 5.4.4 更新项目
|
||
- **URL**: `PUT /api/v1/projects/{id}`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: 所有用户
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"payment_amount": 50000.00,
|
||
"status": "进行中",
|
||
"description": "项目更新描述"
|
||
}
|
||
```
|
||
|
||
#### 5.4.5 删除项目
|
||
- **URL**: `DELETE /api/v1/projects/{id}`
|
||
- **Header**: `Authorization: Bearer <token>`
|
||
- **权限**: admin, market（只能删除自己创建的）
|
||
|
||
## 7. 前端设计
|
||
|
||
### 7.1 页面结构
|
||
|
||
```
|
||
登录页 (Login)
|
||
└─ 登录表单
|
||
|
||
主布局 (Layout)
|
||
├─ 顶部导航栏 (Header)
|
||
│ ├─ Logo
|
||
│ ├─ 用户信息
|
||
│ └─ 登出按钮
|
||
│
|
||
└─ 侧边栏 (Sidebar)
|
||
└─ 菜单
|
||
├─ 仪表盘 (Dashboard)
|
||
├─ 用户管理 (UserList) - 仅管理员
|
||
└─ 项目管理 (ProjectList)
|
||
├─ 项目列表
|
||
├─ 创建项目
|
||
└─ 项目详情
|
||
```
|
||
|
||
### 7.2 核心组件
|
||
|
||
#### 6.2.1 AuthContext
|
||
全局认证状态管理：
|
||
```javascript
|
||
const AuthContext = createContext({
|
||
user: null,
|
||
token: null,
|
||
login: () => {},
|
||
logout: () => {},
|
||
isAuthenticated: false
|
||
});
|
||
```
|
||
|
||
#### 6.2.2 ProtectedRoute
|
||
路由守卫组件，保护需要登录的页面。
|
||
|
||
#### 6.2.3 API Service
|
||
统一的API调用封装：
|
||
- 统一的错误处理
|
||
- 自动添加Token
|
||
- 请求拦截器
|
||
- 响应拦截器
|
||
|
||
### 7.3 页面设计
|
||
|
||
#### 6.3.1 登录页
|
||
- 简洁的登录表单
|
||
- 用户名/密码输入
|
||
- 记住我选项
|
||
- 错误提示
|
||
|
||
#### 6.3.2 仪表盘
|
||
- 项目统计卡片（总项目数、进行中、已完成等）
|
||
- 最近项目列表
|
||
- 快速操作入口
|
||
|
||
#### 6.3.3 用户管理页
|
||
- 用户列表表格
|
||
- 搜索和筛选功能
|
||
- 创建/编辑/删除/重置密码操作
|
||
- 分页功能
|
||
|
||
#### 6.3.4 项目列表页
|
||
- 项目列表表格
|
||
- 搜索和筛选（状态、部门）
|
||
- 创建项目按钮
|
||
- 分页功能
|
||
|
||
#### 6.3.5 项目表单
|
||
- 项目信息表单
|
||
- 表单验证
|
||
- 保存/取消按钮
|
||
|
||
#### 6.3.6 项目详情页
|
||
- 项目详细信息展示
|
||
- 编辑功能
|
||
- 操作日志（可选）
|
||
|
||
### 7.4 UI风格
|
||
- 使用Ant Design默认主题
|
||
- 响应式布局
|
||
- 简洁、专业的企业级UI
|
||
|
||
## 8. 安全设计
|
||
|
||
### 8.1 认证安全
|
||
- 密码使用bcrypt加密存储
|
||
- JWT Token有效期设置（如24小时）
|
||
- Token过期自动刷新机制
|
||
|
||
### 8.2 权限控制
|
||
- 后端基于装饰器的权限验证
|
||
- 前端路由级别的权限控制
|
||
- 前端组件级别的权限控制
|
||
|
||
### 8.3 数据安全
|
||
- SQL注入防护（使用SQLAlchemy ORM）
|
||
- XSS防护（React自动转义）
|
||
- 输入验证（前后端双重验证）
|
||
|
||
## 9. 部署方案
|
||
|
||
### 9.1 开发环境
|
||
|
||
**后端**：
|
||
```bash
|
||
cd backend
|
||
pipenv install
|
||
pipenv shell
|
||
python run.py
|
||
# 服务运行在 http://localhost:5000
|
||
```
|
||
|
||
**前端**：
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm start
|
||
# 服务运行在 http://localhost:3000
|
||
```
|
||
|
||
**数据库**：
|
||
- 本地MySQL数据库
|
||
- 数据库名：`project_manager`
|
||
- 配置文件：`.env`
|
||
|
||
### 9.2 生产环境（推荐方案）
|
||
|
||
**使用Docker Compose**：
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
mysql:
|
||
image: mysql:8.0
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: rootpassword
|
||
MYSQL_DATABASE: project_manager
|
||
volumes:
|
||
- mysql_data:/var/lib/mysql
|
||
ports:
|
||
- "3306:3306"
|
||
|
||
backend:
|
||
build: ./backend
|
||
ports:
|
||
- "5000:5000"
|
||
depends_on:
|
||
- mysql
|
||
environment:
|
||
DATABASE_URL: mysql+pymysql://root:rootpassword@mysql/project_manager
|
||
SECRET_KEY: your-secret-key
|
||
|
||
frontend:
|
||
build: ./frontend
|
||
ports:
|
||
- "80:80"
|
||
depends_on:
|
||
- backend
|
||
|
||
volumes:
|
||
mysql_data:
|
||
```
|
||
|
||
## 10. 后续优化建议
|
||
|
||
### 10.1 功能扩展
|
||
- 项目附件上传
|
||
- 操作日志记录
|
||
- 数据导出功能
|
||
- 报表统计功能
|
||
|
||
### 10.2 性能优化
|
||
- 数据库索引优化
|
||
- API响应缓存（如需要）
|
||
- 前端代码分割
|
||
|
||
### 10.3 用户体验
|
||
- 表单自动保存
|
||
- 批量操作功能
|
||
- 消息通知功能
|
||
|
||
## 11. 开发计划
|
||
|
||
### 11.1 第一阶段（MVP）
|
||
- 用户登录/登出
|
||
- 项目CRUD基础功能
|
||
- 简单的用户管理（仅管理员）
|
||
|
||
### 11.2 第二阶段
|
||
- 权限控制完善
|
||
- 项目列表筛选和搜索
|
||
- 表单验证优化
|
||
|
||
### 11.3 第三阶段（可选）
|
||
- 高级功能扩展
|
||
- 性能优化
|
||
- 用户体验优化
|
||
|
||
## 12. 相关文档
|
||
|
||
### 12.1 团队协作文档
|
||
- [团队协作规范](../TEAM-COLLABORATION.md) - 详细的团队协作流程和规范
|
||
- [权限控制文档](../ACCESS-CONTROL.md) - 各角色访问权限说明
|
||
|
||
### 12.2 角色工作规范
|
||
- [后端程序员工作规范](../backend/WORKSTANDARDS.md) - 后端开发详细规范
|
||
- [前端程序员工作规范](../frontend/WORKSTANDARDS.md) - 前端开发详细规范
|
||
- [测试工程师工作规范](../testing/WORKSTANDARDS.md) - 测试工作详细规范
|
||
|
||
### 12.3 技术文档
|
||
- [UI设计规范](../docs/ui-design-spec.md) - 前端UI设计规范
|
||
- [后端API文档](../backend/docs/api.md) - API接口文档（由后端程序员维护）
|
||
- [前端组件文档](../frontend/docs/components.md) - 前端组件文档（由前端程序员维护）
|
||
- [测试文档](../testing/docs/) - 测试计划和测试策略（由测试工程师维护）
|
||
|
||
### 12.4 项目文档
|
||
- [README.md](../README.md) - 项目说明文档
|
||
- [设计方案](../docs/plans/) - 项目设计方案和技术设计文档
|
||
|
||
---
|
||
|
||
**文档维护**: 本文档由技术总监维护，如有疑问请联系技术总监。 |