save code

2026-01-25 00:02:54 +08:00
commit f33a902c95
4 changed files with 2561 additions and 0 deletions
@@ -0,0 +1,748 @@
+# 项目信息管理系统 - 设计文档
+
+## 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/                          # 后端代码
+│   ├── app/
+│   │   ├── __init__.py              # Flask应用初始化
+│   │   ├── config.py                 # 配置文件
+│   │   ├── models/                   # 数据库模型
+│   │   │   ├── __init__.py
+│   │   │   ├── user.py
+│   │   │   └── project.py
+│   │   ├── routes/                   # API路由
+│   │   │   ├── __init__.py
+│   │   │   ├── auth.py               # 认证相关
+│   │   │   ├── users.py              # 用户管理
+│   │   │   └── projects.py           # 项目管理
+│   │   ├── services/                 # 业务逻辑
+│   │   │   ├── __init__.py
+│   │   │   ├── auth_service.py
+│   │   │   ├── user_service.py
+│   │   │   └── project_service.py
+│   │   └── utils/                    # 工具函数
+│   │       ├── __init__.py
+│   │       ├── jwt_utils.py
+│   │       └── decorators.py
+│   ├── requirements.txt              # Python依赖
+│   ├── run.py                        # 启动文件
+│   └── .env                          # 环境变量
+│
+├── frontend/                         # 前端代码
+│   ├── public/
+│   │   └── index.html
+│   ├── src/
+│   │   ├── components/               # 公共组件
+│   │   │   ├── Layout.js
+│   │   │   ├── Header.js
+│   │   │   └── Sidebar.js
+│   │   ├── pages/                    # 页面组件
+│   │   │   ├── Login.js
+│   │   │   ├── Dashboard.js
+│   │   │   ├── UserList.js
+│   │   │   ├── UserForm.js
+│   │   │   ├── ProjectList.js
+│   │   │   ├── ProjectForm.js
+│   │   │   └── ProjectDetail.js
+│   │   ├── services/                 # API服务
+│   │   │   ├── api.js                # Axios配置
+│   │   │   ├── auth.js
+│   │   │   ├── user.js
+│   │   │   └── project.js
+│   │   ├── contexts/                 # Context
+│   │   │   └── AuthContext.js
+│   │   ├── utils/                    # 工具函数
+│   │   │   └── auth.js
+│   │   ├── App.js                    # 根组件
+│   │   ├── index.js                  # 入口文件
+│   │   └── App.css
+│   ├── package.json
+│   └── .env                          # 环境变量
+│
+├── docs/                             # 文档
+│   ├── plans/                        # 设计文档
+│   │   └── 2026-01-24-project-management-system-design.md
+│   └── api/                          # API文档
+│
+└── README.md
+```
+
+## 4. 数据库设计
+
+### 4.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);
+```
+
+### 4.2 角色权限矩阵
+
+| 功能 | admin | market | other |
+|------|-------|--------|-------|
+| 登录 | ✓ | ✓ | ✓ |
+| 创建用户 | ✓ | ✗ | ✗ |
+| 编辑用户 | ✓ | ✗ | ✗ |
+| 删除用户 | ✓ | ✗ | ✗ |
+| 查看用户列表 | ✓ | ✗ | ✗ |
+| 创建项目 | ✓ | ✓ | ✗ |
+| 编辑项目信息 | ✓ | ✓ | ✓ |
+| 删除项目 | ✓ | ✓ | ✗ |
+| 查看所有项目 | ✓ | ✓ | ✓ |
+| 查看项目详情 | ✓ | ✓ | ✓ |
+
+## 5. API设计
+
+### 5.1 API规范
+
+- **Base URL**: `/api/v1`
+- **Content-Type**: `application/json`
+- **认证方式**: JWT Token（在Header中传递：`Authorization: Bearer <token>`）
+- **响应格式**:
+```json
+{
+  "success": true,
+  "message": "操作成功",
+  "data": {}
+}
+```
+
+### 5.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": "登出成功"
+}
+```
+
+### 5.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"
+}
+```
+
+### 5.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（只能删除自己创建的）
+
+## 6. 前端设计
+
+### 6.1 页面结构
+
+```
+登录页 (Login)
+  └─ 登录表单
+
+主布局 (Layout)
+  ├─ 顶部导航栏 (Header)
+  │   ├─ Logo
+  │   ├─ 用户信息
+  │   └─ 登出按钮
+  │
+  └─ 侧边栏 (Sidebar)
+      └─ 菜单
+          ├─ 仪表盘 (Dashboard)
+          ├─ 用户管理 (UserList) - 仅管理员
+          └─ 项目管理 (ProjectList)
+              ├─ 项目列表
+              ├─ 创建项目
+              └─ 项目详情
+```
+
+### 6.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
+- 请求拦截器
+- 响应拦截器
+
+### 6.3 页面设计
+
+#### 6.3.1 登录页
+- 简洁的登录表单
+- 用户名/密码输入
+- 记住我选项
+- 错误提示
+
+#### 6.3.2 仪表盘
+- 项目统计卡片（总项目数、进行中、已完成等）
+- 最近项目列表
+- 快速操作入口
+
+#### 6.3.3 用户管理页
+- 用户列表表格
+- 搜索和筛选功能
+- 创建/编辑/删除/重置密码操作
+- 分页功能
+
+#### 6.3.4 项目列表页
+- 项目列表表格
+- 搜索和筛选（状态、部门）
+- 创建项目按钮
+- 分页功能
+
+#### 6.3.5 项目表单
+- 项目信息表单
+- 表单验证
+- 保存/取消按钮
+
+#### 6.3.6 项目详情页
+- 项目详细信息展示
+- 编辑功能
+- 操作日志（可选）
+
+### 6.4 UI风格
+- 使用Ant Design默认主题
+- 响应式布局
+- 简洁、专业的企业级UI
+
+## 7. 安全设计
+
+### 7.1 认证安全
+- 密码使用bcrypt加密存储
+- JWT Token有效期设置（如24小时）
+- Token过期自动刷新机制
+
+### 7.2 权限控制
+- 后端基于装饰器的权限验证
+- 前端路由级别的权限控制
+- 前端组件级别的权限控制
+
+### 7.3 数据安全
+- SQL注入防护（使用SQLAlchemy ORM）
+- XSS防护（React自动转义）
+- 输入验证（前后端双重验证）
+
+## 8. 部署方案
+
+### 8.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`
+
+### 8.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:
+```
+
+## 9. 后续优化建议
+
+### 9.1 功能扩展
+- 项目附件上传
+- 操作日志记录
+- 数据导出功能
+- 报表统计功能
+
+### 9.2 性能优化
+- 数据库索引优化
+- API响应缓存（如需要）
+- 前端代码分割
+
+### 9.3 用户体验
+- 表单自动保存
+- 批量操作功能
+- 消息通知功能
+
+## 10. 开发计划
+
+### 10.1 第一阶段（MVP）
+- 用户登录/登出
+- 项目CRUD基础功能
+- 简单的用户管理（仅管理员）
+
+### 10.2 第二阶段
+- 权限控制完善
+- 项目列表筛选和搜索
+- 表单验证优化
+
+### 10.3 第三阶段（可选）
+- 高级功能扩展
+- 性能优化
+- 用户体验优化