docs: add handover document and update README for jinhua takeover
This commit is contained in:
admin
219
HANDOVER.md
Normal file
219
HANDOVER.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# PLM Backend 开发移交文档
|
||||
|
||||
**移交时间**: 2026-03-31 07:28:09 GMT+8
|
||||
**移交人**: 小哈
|
||||
**接收人**: 进化官CTO
|
||||
|
||||
---
|
||||
|
||||
## 一、项目概览
|
||||
|
||||
### 项目名称
|
||||
PLM System - 产品生命周期管理系统后端服务
|
||||
|
||||
### 技术栈
|
||||
| 组件 | 技术选型 |
|
||||
|------|---------|
|
||||
| 框架 | FastAPI (Python 3.11+) |
|
||||
| ORM | SQLAlchemy 2.0 (async) |
|
||||
| 数据库 | PostgreSQL 15 |
|
||||
| 缓存 | Redis 7 |
|
||||
| 认证 | JWT (RS256/HS256) |
|
||||
| 容器化 | Docker + Docker Compose |
|
||||
| CI/CD | Drone CI |
|
||||
|
||||
### 项目位置
|
||||
```
|
||||
/home/serveradmin/plm-system/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、已完成功能模块
|
||||
|
||||
### ✅ M0-S0-T04: Auth-Service (认证服务)
|
||||
- JWT 认证 (RS256/HS256)
|
||||
- 登录/登出接口
|
||||
- Token 刷新机制
|
||||
- 密码管理 (修改、验证)
|
||||
- API Key 生成 (程序化访问)
|
||||
- Session 验证接口
|
||||
|
||||
**API 端点**: 8个
|
||||
|
||||
### ✅ M0-S0-T05: User-Service (用户服务)
|
||||
- 用户 CRUD 操作
|
||||
- 用户资料管理
|
||||
- 基于角色的访问控制 (RBAC)
|
||||
- 用户状态管理 (active/inactive/suspended/pending)
|
||||
- 用户管理 (管理员操作)
|
||||
- 密码强度验证
|
||||
|
||||
**API 端点**: 7个
|
||||
|
||||
### ✅ M0-S0-T06: Project-Service (项目服务)
|
||||
- 项目 CRUD 操作
|
||||
- 项目生命周期管理
|
||||
- 成员管理 (添加/移除)
|
||||
- 权限访问控制
|
||||
- 项目筛选和搜索
|
||||
- 预算和时间线追踪
|
||||
|
||||
**API 端点**: 7个
|
||||
|
||||
### ✅ M0-S0-T07: Config-Service (配置服务)
|
||||
- 系统配置 CRUD
|
||||
- 分类组织
|
||||
- 值类型验证 (string, int, float, boolean, JSON, enum)
|
||||
- 配置审计日志
|
||||
- 变更版本追踪
|
||||
- 公开/私有配置支持
|
||||
|
||||
**API 端点**: 9个
|
||||
|
||||
### ✅ M0-S0-T08: CI/CD 部署
|
||||
- Drone CI 管道配置 (`.drone.yml`)
|
||||
- Dockerfile 容器化
|
||||
- API 单元测试
|
||||
- 多阶段管道 (test, build, deploy)
|
||||
|
||||
---
|
||||
|
||||
## 三、项目结构
|
||||
|
||||
```
|
||||
plm-system/
|
||||
├── app/
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # FastAPI 应用入口
|
||||
│ ├── init_db.py # 数据库初始化脚本
|
||||
│ ├── requirements.txt # Python 依赖
|
||||
│ ├── .env.example # 环境配置模板
|
||||
│ ├── core/
|
||||
│ │ ├── config.py # 设置管理
|
||||
│ │ ├── database.py # 异步 SQLAlchemy 配置
|
||||
│ │ ├── security.py # JWT 和密码处理
|
||||
│ │ └── redis.py # Redis 缓存 (预留)
|
||||
│ ├── models/
|
||||
│ │ ├── user.py # User ORM 模型
|
||||
│ │ ├── project.py # Project ORM 模型
|
||||
│ │ └── config.py # SystemConfig ORM 模型
|
||||
│ ├── schemas/
|
||||
│ │ ├── common.py # 共享 schemas
|
||||
│ │ ├── user.py # User 请求/响应
|
||||
│ │ ├── project.py # Project 请求/响应
|
||||
│ │ ├── config.py # Config 请求/响应
|
||||
│ │ └── audit.py # 审计日志响应
|
||||
│ └── api/
|
||||
│ ├── auth.py # 认证路由
|
||||
│ ├── users.py # 用户管理路由
|
||||
│ ├── projects.py # 项目路由
|
||||
│ └── configs.py # 配置路由
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ └── test_api.py # 单元测试
|
||||
├── .drone.yml # CI/CD 管道
|
||||
├── Dockerfile # 容器构建
|
||||
├── docker-compose.yml # 容器编排
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、环境配置
|
||||
|
||||
### 依赖服务
|
||||
| 服务 | 地址 | 凭据 |
|
||||
|------|------|------|
|
||||
| PostgreSQL | localhost:5432 | 用户: `plm` / 密码: `plm123456` |
|
||||
| Redis | localhost:6379 | 无密码 |
|
||||
| Gitea | http://localhost:3000 | 已配置 API Token |
|
||||
|
||||
### 默认管理员账户
|
||||
- **用户名**: `admin`
|
||||
- **密码**: `Admin@123456`
|
||||
- **角色**: `admin` (超级管理员)
|
||||
- ⚠️ **首次登录后必须修改密码!**
|
||||
|
||||
### 启动命令
|
||||
```bash
|
||||
cd /home/serveradmin/plm-system
|
||||
python3 -m app.main
|
||||
```
|
||||
|
||||
### API 文档
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
- Health Check: http://localhost:8000/health
|
||||
|
||||
---
|
||||
|
||||
## 五、Git 提交状态 ✅ 已完成
|
||||
|
||||
### 本地提交 (已完成)
|
||||
```
|
||||
16215ff merge: resolve README conflict with remote
|
||||
2d7d5d0 feat: add CI/CD pipeline and Docker support
|
||||
b9db4d3 fix: datetime timezone compatibility, env loading, database connection
|
||||
0efeaff feat: PLM backend services - auth, user, project, config services
|
||||
```
|
||||
|
||||
### 远程推送 ✅ 已完成
|
||||
- **仓库**: http://localhost:3000/plm-team/plm-backend-service.git
|
||||
- **分支**: master → main
|
||||
- **状态**: 推送成功
|
||||
|
||||
### Gitea API Token (已生成)
|
||||
- Token: `0ef6325811f125f45edec6a630ea069d2e393ec6`
|
||||
- Scope: all
|
||||
- 用户: admin
|
||||
|
||||
---
|
||||
|
||||
## 六、已知问题状态
|
||||
|
||||
### ✅ 已修复
|
||||
1. **datetime 序列化问题** - 已在 commit `b9db4d3` 中修复
|
||||
- 原因: datetime.utcnow() 使用方式
|
||||
- 解决: 使用 timezone-aware datetime
|
||||
|
||||
2. **Git 远程推送** - 已完成
|
||||
- 解决: 生成 Gitea API Token 进行认证
|
||||
- 远程仓库: plm-team/plm-backend-service
|
||||
|
||||
### 🟡 中优先级 (待处理)
|
||||
1. 容器名称冲突 - `plm-postgres` 已存在，需清理旧容器
|
||||
2. 环境变量加载顺序优化
|
||||
|
||||
### 🟢 低优先级 (技术债务)
|
||||
1. Redis 缓存功能预留但未实现
|
||||
2. 单元测试覆盖率需提升 (当前 3 个测试)
|
||||
|
||||
---
|
||||
|
||||
## 七、下一步开发计划
|
||||
|
||||
### Sprint 1 建议
|
||||
1. **M0-S0-T09**: 前端基础框架对接
|
||||
2. **BOM 管理模块**: 物料清单管理
|
||||
3. **工作流引擎**: 流程审批功能
|
||||
|
||||
### 技术债务清理
|
||||
- [ ] 完善 API 测试覆盖率
|
||||
- [ ] 实现 Redis 缓存层
|
||||
- [ ] 添加 API 限流
|
||||
- [ ] 完善错误处理和日志
|
||||
|
||||
---
|
||||
|
||||
## 八、服务验证
|
||||
|
||||
### 已验证功能 ✅
|
||||
- Health Check: `{"status":"healthy"}`
|
||||
- Login API: JWT Token 生成成功
|
||||
- Database: PostgreSQL 连接正常
|
||||
|
||||
---
|
||||
|
||||
**文档更新时间**: 2026-03-31 07:25 GMT+8
|
||||
**状态**: 移交完成 ✅
|
||||
Reference in New Issue
Block a user