xsl/ocean_project_manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

save code

Browse Source
This commit is contained in:
xsl
2026-01-25 12:47:29 +08:00
parent f33a902c95
commit 688adc32d3
13 changed files with 1014 additions and 1122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/TEAM-COLLABORATION.md
+157
View File
@@ -0,0 +1,157 @@
# 海洋项目管理系统 - 团队协作规范
## 项目结构
```
ocean_project_manager/
├── backend/ # 后端程序员工作区
│ ├── src/ # 后端源代码
│ ├── tests/ # 后端测试
│ ├── docs/ # API文档
│ └── WORKSTANDARDS.md
├── frontend/ # 前端程序员工作区
│ ├── src/ # 前端源代码
│ ├── tests/ # 前端测试
│ ├── docs/ # 组件文档
│ └── WORKSTANDARDS.md
├── testing/ # 测试工程师工作区
│ ├── testcases/ # 测试用例
│ ├── reports/ # 测试报告
│ ├── scripts/ # 自动化测试脚本
│ └── WORKSTANDARDS.md
└── docs/ # 项目文档
├── plans/ # 设计方案
└── ui-design-spec.md
```
## 角色职责
### 技术总监
- 审查设计和文档
- Review代码质量
- 协调团队协作
- 批准重大变更
### 后端程序员
- 负责后端API开发和维护
- 编写API文档
- 确保代码质量和测试覆盖率
- 工作目录: `backend/`
### 前端程序员
- 负责前端UI开发和维护
- 编写组件文档
- 集成后端API
- 工作目录: `frontend/`
### 测试工程师
- 编写测试计划和测试用例
- 执行功能测试、UI测试、自动化测试
- 生成测试报告和Bug报告
- 工作目录: `testing/`
## 协作流程
### 1. 需求分析阶段
- 技术总监编写设计方案
- 后端程序员和前端程序员查看设计方案
- 测试工程师编写测试计划
### 2. 开发阶段
**后端开发流程:**
1. 后端程序员开发API
2. 编写单元测试
3. 更新API文档 (`backend/docs/api.md`)
4. 提交代码审查
**前端开发流程:**
1. 前端程序员查看API文档
2. 开发UI组件
3. 集成API
4. 编写组件测试
5. 提交代码审查
### 3. 测试阶段
1. 测试工程师执行测试用例
2. 记录Bug和问题
3. 生成测试报告
4. 后端程序员和前端程序员修复Bug
### 4. 发布阶段
1. 技术总监审查代码和测试报告
2. 合并代码到主分支
3. 部署上线
## 代码审查流程
### 提交PR要求
1. 代码必须通过所有测试
2. 必须有对应文档更新
3. 提交信息符合规范
4. Pull Request描述清晰
### 审查检查项
- [ ] 代码符合规范
- [ ] 测试覆盖率达标
- [ ] 文档完整
- [ ] 无安全漏洞
- [ ] 性能可接受
## 文档要求
### 设计文档
- 存储位置: `docs/plans/`
- 包含: 需求分析、架构设计、数据库设计
### API文档
- 存储位置: `backend/docs/api.md`
- 使用OpenAPI/Swagger格式
### 测试文档
- 存储位置: `testing/docs/`
- 包含: 测试计划、测试用例、Bug报告
## 沟通机制
### 每日站会
- 各角色汇报工作进展
- 讨论遇到的问题
### 周会
- 代码审查
- 设计方案讨论
- 进度同步
### 紧急沟通
- 重大Bug立即通知技术总监
- 设计变更需要技术总监批准
## 版本管理
### 分支策略
- `main`: 生产环境
- `develop`: 开发环境
- `feature/<功能名>`: 功能分支
- `bugfix/<bug编号>`: Bug修复分支
### 提交规范
- 后端: `[backend] <类型>: <描述>`
- 前端: `[frontend] <类型>: <描述>`
- 测试: `[testing] <类型>: <描述>`
## 质量保证
### 代码质量
- 后端测试覆盖率 > 80%
- 前端关键组件必须有测试
- 代码必须通过Linter检查
### 测试质量
- 功能测试覆盖率 100%
- 关键流程必须有自动化测试
- Bug修复必须经过验证
### 文档质量
- API文档与代码同步
- 组件文档包含使用示例
- 测试用例清晰可执行
docs/pid-update-log.md
+93
View File
@@ -0,0 +1,93 @@
# docs/pid.md 文档更新说明
## 更新时间
2026-01-25
## 更新内容
### 1. 更新了第3.2节 - 项目目录结构
**更新前**: 使用传统的Flask项目结构（app目录）
**更新后**: 采用新的团队协作目录结构
**变更说明**:
- 后端结构从 `backend/app/` 更新为 `backend/src/`，包含更清晰的分层架构（controllers, services, models, routes, middleware, utils）
- 前端结构从基本的React项目结构更新为包含types、hooks、styles等子目录的现代React项目结构
- 新增了 `testing/` 目录，包含testcases、reports、data、scripts、docs等子目录
- 为每个工作区添加了WORKSTANDARDS.md和README.md
### 2. 新增第3.3节 - 工作目录说明
**新增内容**:
- 后端程序员工作区职责和主要工作
- 前端程序员工作区职责和主要工作
- 测试工程师工作区职责和主要工作
### 3. 新增第3.4节 - 权限限制
**新增内容**:
- 明确规定各角色只能在指定目录中工作
- 添加权限控制文档链接
- 强调跨目录工作需要技术总监批准
### 4. 新增第4章 - 团队协作
**新增内容**:
- 4.1 角色职责: 详细说明各角色的工作职责
- 4.2 工作流程: 包含需求分析、后端开发、前端开发、测试、代码审查五个阶段的详细流程
- 4.3 代码提交规范: 明确各角色的提交信息格式和类型说明
- 4.4 文档规范: 说明后端、前端、测试的文档规范
- 4.5 沟通机制: 说明日常沟通、文档沟通、技术总监审查的方式
### 5. 更新章节编号
由于新增了第4章"团队协作"，后续章节编号全部+1:
- 原第4章"数据库设计" → 现第5章
- 原第5章"API设计" → 现第6章
- 原第6章"前端设计" → 现第7章
- 原第7章"安全设计" → 现第8章
- 原第8章"部署方案" → 现第9章
- 原第9章"后续优化建议" → 现第10章
- 原第10章"开发计划" → 现第11章
### 6. 新增第12章 - 相关文档
**新增内容**:
- 12.1 团队协作文档链接
- 12.2 角色工作规范链接
- 12.3 技术文档链接
- 12.4 项目文档链接
### 7. 更新所有子章节编号
所有子章节编号根据父章节编号进行了相应更新:
- 数据库设计: 4.1-4.2 → 5.1-5.2
- API设计: 5.1-5.4 → 6.1-6.4
- 前端设计: 6.1-6.4 → 7.1-7.4
- 安全设计: 7.1-7.3 → 8.1-8.3
- 部署方案: 8.1-8.2 → 9.1-9.2
- 后续优化建议: 9.1-9.3 → 10.1-10.3
- 开发计划: 10.1-10.3 → 11.1-11.3
## 影响范围
1. **文档结构**: 文档从10章扩展到12章，新增了团队协作和相关文档两章
2. **项目架构**: 完全按照当前的项目目录结构更新，与实际的backend/、frontend/、testing/目录保持一致
3. **角色分工**: 明确了后端程序员、前端程序员、测试工程师的具体职责和工作范围
4. **协作流程**: 提供了详细的团队协作流程，从前端到后端再到测试的完整工作链
## 后续维护
- 后端程序员需要在 `backend/docs/api.md` 中维护API文档
- 前端程序员需要在 `frontend/docs/components.md` 中维护组件文档
- 测试工程师需要在 `testing/docs/` 中维护测试文档
- 技术总监负责维护本设计文档 (`docs/pid.md`)
## 文档状态
✅ 已完成更新，文档与当前项目架构保持一致
---
**更新人**: 技术总监
**审核**: 待审核
docs/plans/2026-01-24-project-management-system-design.md → docs/pid.md
+282 -67
View File
@@ -123,74 +123,264 @@
```
ocean_project_manager/
├── backend/ # 后端代码
│ ├── app/
│ │ ├── __init__.py # Flask应用初始化
│ │ ├── config.py # 配置文件
│ │ ├── models/ # 数据库模型
│ │ │ ├── __init__.py
│ │ │ ├── user.py
│ │ │ └── project.py
│ │ ├── routes/ # API路由
│ │ │ ├── __init__.py
├── backend/ # 后端程序员工作区
│ ├── src/ # 源代码
│ │ ├── controllers/ # 控制器层
│ │ │ ├── auth.py # 认证相关
│ │ │ ├── users.py # 用户管理
│ │ │ └── projects.py # 项目管理
│ │ ├── services/ # 业务逻辑
│ │ │ ├── __init__.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/ # 工具函数
│ │ ├── __init__.py
│ │ ├── jwt_utils.py
│ │ └── decorators.py
│ │ └── password_utils.py
│ ├── tests/ # 单元测试和集成测试
│ ├── docs/ # API文档和技术文档
│ │ └── api.md # API文档
│ ├── config/ # 配置文件
│ ├── requirements.txt # Python依赖
│ ├── run.py # 启动文件
│ └── .env # 环境变量
│ ├── WORKSTANDARDS.md # 后端程序员工作规范
│ └── README.md # 后端开发说明
│
├── frontend/ # 前端代码
│ ├── public/
│ │ └── index.html
│ ├── src/
│ │ ├── components/ # 公共组件
│ │ │ ├── Layout.js
│ │ │ ├── Header.js
│ │ │ └── Sidebar.js
├── frontend/ # 前端程序员工作区
│ ├── src/ # 源代码
│ │ ├── components/ # 可复用组件
│ │ │ ├── Layout.jsx
│ │ │ ├── Header.jsx
│ │ │ └── Sidebar.jsx
│ │ ├── pages/ # 页面组件
│ │ │ ├── Login.js
│ │ │ ├── Dashboard.js
│ │ │ ├── UserList.js
│ │ │ ├── UserForm.js
│ │ │ ├── ProjectList.js
│ │ │ ├── ProjectForm.js
│ │ │ └── ProjectDetail.js
│ │ │ ├── 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
│ │ ├── contexts/ # Context
│ │ │ └── AuthContext.js
│ │ ├── utils/ # 工具函数
│ │ │ └── auth.js
│ │ ├── App.js # 根组件
│ │ ├── index.js # 入口文件
│ │ └── App.css
│ │ ├── styles/ # 样式文件
│ │ │ └── global.css
│ │ ├── types/ # TypeScript类型定义
│ │ │ ├── user.ts
│ │ │ └── project.ts
│ │ ├── App.jsx # 根组件
│ │ └── index.js # 入口文件
│ ├── tests/ # 组件测试
│ ├── docs/ # 组件文档和开发文档
│ │ └── components.md # 组件文档
│ ├── package.json
│ └── .env # 环境变量
│ ├── WORKSTANDARDS.md # 前端程序员工作规范
│ └── README.md # 前端开发说明
│
├── docs/ # 文档
├── 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
│ └── api/ # API文档
│ ├── ui-design-spec.md # UI设计规范
│ ├── pid.md # 项目信息文档（本文档）
│ └── TEAM-COLLABORATION.md # 团队协作规范
│
└── README.md
├── ACCESS-CONTROL.md # 权限控制文档
├── README.md # 项目说明
└── .git/ # Git仓库
```
## 4. 数据库设计
### 3.3 工作目录说明
### 4.1 数据库表结构
#### 后端程序员工作区 (`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)
@@ -275,7 +465,7 @@ CREATE INDEX idx_projects_department ON projects(department);
CREATE INDEX idx_projects_created_by ON projects(created_by);
```
### 4.2 角色权限矩阵
### 5.2 角色权限矩阵
| 功能 | admin | market | other |
|------|-------|--------|-------|
@@ -290,9 +480,9 @@ CREATE INDEX idx_projects_created_by ON projects(created_by);
| 查看所有项目 | ✓ | ✓ | ✓ |
| 查看项目详情 | ✓ | ✓ | ✓ |
## 5. API设计
## 6. API设计
### 5.1 API规范
### 6.1 API规范
- **Base URL**: `/api/v1`
- **Content-Type**: `application/json`
@@ -306,7 +496,7 @@ CREATE INDEX idx_projects_created_by ON projects(created_by);
}
```
### 5.2 认证相关API
### 6.2 认证相关API
#### 5.2.1 用户登录
- **URL**: `POST /api/v1/auth/login`
@@ -363,7 +553,7 @@ CREATE INDEX idx_projects_created_by ON projects(created_by);
}
```
### 5.3 用户管理API
### 6.3 用户管理API
#### 5.3.1 获取用户列表
- **URL**: `GET /api/v1/users`
@@ -458,7 +648,7 @@ CREATE INDEX idx_projects_created_by ON projects(created_by);
}
```
### 5.4 项目管理API
### 6.4 项目管理API
#### 5.4.1 获取项目列表
- **URL**: `GET /api/v1/projects`
@@ -542,9 +732,9 @@ CREATE INDEX idx_projects_created_by ON projects(created_by);
- **Header**: `Authorization: Bearer <token>`
- **权限**: admin, market（只能删除自己创建的）
## 6. 前端设计
## 7. 前端设计
### 6.1 页面结构
### 7.1 页面结构
```
登录页 (Login)
@@ -566,7 +756,7 @@ CREATE INDEX idx_projects_created_by ON projects(created_by);
└─ 项目详情
```
### 6.2 核心组件
### 7.2 核心组件
#### 6.2.1 AuthContext
全局认证状态管理：
@@ -590,7 +780,7 @@ const AuthContext = createContext({
- 请求拦截器
- 响应拦截器
### 6.3 页面设计
### 7.3 页面设计
#### 6.3.1 登录页
- 简洁的登录表单
@@ -625,31 +815,31 @@ const AuthContext = createContext({
- 编辑功能
- 操作日志（可选）
### 6.4 UI风格
### 7.4 UI风格
- 使用Ant Design默认主题
- 响应式布局
- 简洁、专业的企业级UI
## 7. 安全设计
## 8. 安全设计
### 7.1 认证安全
### 8.1 认证安全
- 密码使用bcrypt加密存储
- JWT Token有效期设置（如24小时）
- Token过期自动刷新机制
### 7.2 权限控制
### 8.2 权限控制
- 后端基于装饰器的权限验证
- 前端路由级别的权限控制
- 前端组件级别的权限控制
### 7.3 数据安全
### 8.3 数据安全
- SQL注入防护（使用SQLAlchemy ORM）
- XSS防护（React自动转义）
- 输入验证（前后端双重验证）
## 8. 部署方案
## 9. 部署方案
### 8.1 开发环境
### 9.1 开发环境
**后端**：
```bash
@@ -673,7 +863,7 @@ npm start
- 数据库名：`project_manager`
- 配置文件：`.env`
### 8.2 生产环境（推荐方案）
### 9.2 生产环境（推荐方案）
**使用Docker Compose**：
@@ -712,37 +902,62 @@ volumes:
mysql_data:
```
## 9. 后续优化建议
## 10. 后续优化建议
### 9.1 功能扩展
### 10.1 功能扩展
- 项目附件上传
- 操作日志记录
- 数据导出功能
- 报表统计功能
### 9.2 性能优化
### 10.2 性能优化
- 数据库索引优化
- API响应缓存（如需要）
- 前端代码分割
### 9.3 用户体验
### 10.3 用户体验
- 表单自动保存
- 批量操作功能
- 消息通知功能
## 10. 开发计划
## 11. 开发计划
### 10.1 第一阶段（MVP）
### 11.1 第一阶段（MVP）
- 用户登录/登出
- 项目CRUD基础功能
- 简单的用户管理（仅管理员）
### 10.2 第二阶段
### 11.2 第二阶段
- 权限控制完善
- 项目列表筛选和搜索
- 表单验证优化
### 10.3 第三阶段（可选）
### 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/) - 项目设计方案和技术设计文档
---
**文档维护**: 本文档由技术总监维护，如有疑问请联系技术总监。