plm-backend-service/HANDOVER.md

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 (超级管理员)
• ⚠️ 首次登录后必须修改密码!

启动命令

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 状态: 移交完成 ✅