工业管道法兰盲板管理系统 - 采用 Gateflow 工作流模式开发

一套面向大型工厂（>1000 个盲板）的工业管道法兰盲板管理系统，覆盖盲板信息记录、安装/拆卸/巡检流程管理、库存管理。

本项目采用 Gateflow 工作流模式（源自 code-is-cheap 项目），通过严格的 gate-based 推进机制确保代码质量：

• 需求澄清 → 计划制定 → 计划审查 → 切片实施 → 代码审查 → 深度审查 → 优化迭代
• 每个阶段都有明确的门禁标准和验收条件
• 第三方审查评分：6.8/10（中等偏上）

• 当前实现：基于内存（collections.defaultdict）
• 限制：仅适用于单实例部署，多实例部署时速率限制不共享
• 重启丢失：服务器重启后速率限制计数器清零
• 生产建议：多实例部署需要集成 Redis 实现持久化速率限制

• 开发环境：使用 SQLite，与生产环境 PostgreSQL 存在行为差异
• 测试覆盖：单元测试在 SQLite 上运行，未在 PostgreSQL 上验证
• 生产建议：上线前必须在 PostgreSQL 环境测试

• 密码修改：修改密码后旧令牌立即失效（基于 password_changed_at 字段）
• 令牌吊销：支持黑名单机制，但高频检查时增加数据库压力
• 生产建议：考虑将黑名单迁移到 Redis

• 实现方式：使用 BaseHTTPMiddleware
• 限制：不支持流式响应和 WebSocket
• 适用场景：当前仅用于速率限制，不影响核心功能

测试总计：62 passed, 0 failed

• Python 3.11+
• Node.js 18+
• PostgreSQL 15（生产环境）
• Redis 7（可选）

# 进入后端目录
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -e ".[dev]"

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 SECRET_KEY

# 初始化数据库（开发环境）
python scripts/init_db.py

# 或使用 Alembic 迁移（生产环境）
alembic upgrade head

# 启动后端服务
uvicorn app.main:app --reload

访问 http://localhost:8000/docs 查看 API 文档。

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

访问 http://localhost:3000 查看前端页面。

# 创建管理员用户
curl -X POST http://localhost:8000/api/v1/users/init-admin \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123","real_name":"管理员"}'

blind-flange-manager/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/v1/           # API 路由
│   │   │   ├── user.py       # 用户管理
│   │   │   ├── blind_flange.py  # 盲板管理
│   │   │   ├── scan.py       # 扫码功能
│   │   │   ├── workflow.py   # 流程管理
│   │   │   ├── inventory.py  # 库存管理
│   │   │   ├── inspection.py # 巡检管理
│   │   │   └── dashboard.py  # 仪表盘
│   │   ├── core/             # 配置、数据库、安全
│   │   ├── models/           # 数据模型（10个）
│   │   ├── schemas/          # Pydantic schemas
│   │   ├── services/         # 业务逻辑
│   │   └── utils/            # 工具函数
│   ├── alembic/              # 数据库迁移
│   ├── tests/                # 测试（57个）
│   ├── scripts/              # 脚本
│   └── pyproject.toml
├── frontend/                  # 前端应用
│   ├── src/
│   │   ├── views/            # 页面（7个）
│   │   ├── components/       # 组件
│   │   ├── api/              # API 调用
│   │   ├── stores/           # 状态管理
│   │   └── router/           # 路由
│   └── package.json
├── docs/
│   ├── plan.md               # 实施计划
│   └── REVIEW_REPORT.md      # 第三方审查报告
├── docker/
│   └── docker-compose.yml
├── .env.example               # 环境变量模板
├── .gitignore
├── PR_DESCRIPTION.md
└── README.md

• ✅ JWT 认证 + 过期验证
• ✅ bcrypt 密码哈希
• ✅ 角色权限控制（admin/operator/inspector）
• ✅ SECRET_KEY 环境变量
• ✅ 令牌吊销机制（TokenBlacklist）
• ✅ 速率限制（登录接口 5次/分钟）
• ✅ 数据库外键约束（15个）
• ✅ CORS 配置
• ✅ .env 文件不提交到仓库

# 运行所有测试
cd backend && python -m pytest tests/ -v

# 运行特定测试
python -m pytest tests/test_user.py -v

# 查看测试覆盖率
python -m pytest tests/ --cov=app --cov-report=html

# 启动服务
cd docker
docker compose up -d

# 查看日志
docker compose logs -f

# 配置环境变量
cp .env.example .env
# 编辑 .env，设置：
# - DATABASE_URL (PostgreSQL)
# - SECRET_KEY (随机密钥)
# - DEBUG=false

# 运行数据库迁移
cd backend
alembic upgrade head

# 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

启动后端服务后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

本项目采用 Gateflow 工作流模式：

需求澄清 → 计划制定 → 计划审查 → 切片实施 → 代码审查 → 深度审查 → 优化迭代

关键架构决策已记录在 docs/adr/ 目录：

• ADR-001: 选择 FastAPI 作为 Web 框架
• ADR-002: 开发环境使用 SQLite
• ADR-003: 选择 JWT 作为认证方案
• ADR-004: 选择 Gateflow 工作流模式

1. ✅ 需求澄清（3轮）
2. ✅ 计划制定（12个切片）
3. ✅ 计划审查（11个问题，修复9个）
4. ✅ 切片实施（7个切片）
5. ✅ 代码审查（8个安全问题，全部修复）
6. ✅ 深度审查（架构8/10，安全5/10）
7. ✅ 优化迭代（4轮优化）
8. ✅ 前端开发（7个页面）
9. ✅ P0 问题修复
10. ✅ 推送到 GitHub

第三方审查评分：6.8/10（中等偏上）

详见 REVIEW_REPORT.md

⚠️ 以下内容等待用户审核：

• 登录页面功能
• 仪表盘数据显示
• 盲板列表 CRUD
• 盲板详情展示
• 流程管理操作
• 库存管理功能
• 巡检管理流程

• 用户认证流程
• 盲板导入导出
• 流程状态机
• 库存预警逻辑
• 巡检计划功能

• PostgreSQL 环境验证
• 速率限制中间件重构
• 令牌管理增强

• 移动端开发（Vant + Capacitor）
• 文件上传功能
• 通知模块
• Redis 集成
• CI/CD 配置

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/xxx)
3. 提交更改 (git commit -m 'feat: add xxx')
4. 推送到分支 (git push origin feature/xxx)
5. 创建 Pull Request

MIT License

• GitHub: feiyu169
• 仓库: blind-flange-manager