xsl/ocean_project_manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f33a902c95be0c9cea26a87888967f1d721503e2
ocean_project_manager/docs/plans/2026-01-24-project-management-system-design.md
T
xsl f33a902c95 save code
2026-01-25 00:02:54 +08:00

20 KiB
Raw Blame History

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

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 更新时间 
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 更新时间 
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>）
  • 响应格式:
{
  "success": true,
  "message": "操作成功",
  "data": {}
}

5.2 认证相关API

5.2.1 用户登录

  • URL: POST /api/v1/auth/login
  • 请求体:
{
  "username": "admin",
  "password": "password123"
}
  • 响应:
{
  "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>
  • 响应:
{
  "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>
  • 响应:
{
  "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: 角色筛选
  • 响应:
{
  "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
  • 请求体:
{
  "username": "zhangsan",
  "password": "password123",
  "real_name": "张三",
  "department": "市场部",
  "role": "market",
  "email": "zhangsan@example.com",
  "phone": "13800138000"
}
  • 响应:
{
  "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
  • 请求体:
{
  "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
  • 请求体:
{
  "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: 部门筛选
  • 响应:
{
  "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
  • 请求体:
{
  "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>
  • 权限: 所有用户
  • 请求体:
{
  "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

全局认证状态管理：

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 开发环境

后端：

cd backend
pipenv install
pipenv shell
python run.py
# 服务运行在 http://localhost:5000

前端：

cd frontend
npm install
npm start
# 服务运行在 http://localhost:3000

数据库：

  • 本地MySQL数据库
  • 数据库名：project_manager
  • 配置文件：.env

8.2 生产环境（推荐方案）

使用Docker Compose：

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 第三阶段（可选）

  • 高级功能扩展
  • 性能优化
  • 用户体验优化
Reference in New Issue View Git Blame Copy Permalink