# 项目信息管理系统 - 设计文档

## 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 第三阶段（可选）
- 高级功能扩展
- 性能优化
- 用户体验优化