DevEnchantments/ptrack
GitHub: DevEnchantments/ptrack
基于 React、NestJS 和 Supabase 重建的项目组合管理应用，提供九种记录类型的完整 CRUD、字段级审计历史和文件附件管理。
Stars: 2 | Forks: 0
[](https://github.com/DevEnchantments/ptrack/actions/workflows/ci.yml)
**将企业级 Oracle APEX PPM 应用从头重建为现代 Web 技术栈。**
## ✨ 包含内容
| | 功能 | 说明 |
|---|---|---|
| 📁 | **完整的 CRUD，9 种记录类型** | 里程碑、行动项、问题、链接、资源、更新、状态报告、附件、人员 |
| 🧙 | **4 步项目向导** | 外加编辑、删除、受限项目锁定和孤立的 Storage 清理 |
| 🕓 | **字段级历史记录** | Postgres trigger 为每个更改的字段写入一条审计行——值在写入时解析，因此历史记录显示的是该值过去的*真实状态* |
| 🗑️ | **删除审计** | 每次删除都会记录*谁*删除了*什么*，并在 UI 中进行二次确认 |
| 📎 | **文件附件** | 由 Supabase Storage 支持，带有星标和标签功能 |
| 📖 | **实时 API 文档** | 位于 `/api/docs` 的 Swagger，带有可运行的请求示例 |
| 🔐 | **本地 JWT 验证** | Supabase token 在进程内通过 (JWKS) 验证——无需每次请求都进行认证往返 |
| ✅ | **CI 门控** | 在每次推送时进行类型检查、lint、构建和测试 |
## 🏗 架构
```
flowchart LR
subgraph Browser
R["⚛️ React + Vite
Tailwind · shadcn/ui"]
end
subgraph API [":3000"]
N["🪺 NestJS
business logic · authz
feature-first modules"]
end
subgraph Supabase
P[("🐘 Postgres
+ history triggers")]
A["🔑 Auth"]
S["🗄️ Storage"]
end
R -- "REST + Bearer JWT" --> N
N -- "service-role key" --> P
N --> S
R -. "sign-in only" .-> A
```
## 🚀 快速开始
**前提条件：** Node 22+，一个 [Supabase](https://supabase.com) 项目。
### 1 · 数据库 —— Supabase SQL 编辑器
按顺序运行一次以下脚本：
| 脚本 | 用途 |
|---|---|
| `backend/db/ptrack_phase1_schema.sql` | 全部 28 张表、触发器、索引 |
| `backend/db/record_history.sql` | 字段级审计捕获 + 数据回填 |
| `backend/db/record_history_deleted.sql` | 将审计扩展到删除操作 |
### 2 · 后端 —— `:3000`
```
cd backend
npm install
npm run dev
```
创建 `backend/.env`：
| 变量 | 必需 | 用途 |
|---|---|---|
| `SUPABASE_URL` | ✅ | 项目 URL — 仪表盘 → Settings → API |
| `SUPABASE_SECRET_KEY` | ✅ | 服务角色 / 密钥（**仅限服务器使用，绝不要暴露给浏览器**） |
| `SUPABASE_JWT_SECRET` | 可选 | 仅适用于旧版 HS256 项目；现代项目会自动通过公共 JWKS 进行验证 |
### 3 · 前端 —— `:5173`
```
cd frontend
npm install
npm run dev
```
创建 `frontend/.env.local`：
| 变量 | 必需 | 用途 |
|---|---|---|
| `VITE_SUPABASE_URL` | ✅ | 同上的项目 URL |
| `VITE_SUPABASE_PUBLISHABLE_KEY` | ✅ | *publishable* (anon) key —— 对浏览器安全 |
### 4 · 探索
- 应用 →
- API 文档（Swagger，仅限非生产环境）→
## 🧪 质量
```
cd backend && npm test # unit tests (audit diffing, auth guard verify/fallback)
npx tsc --noEmit # typecheck — clean in both halves
npx eslint "src/**/*.ts" # backend lint — zero errors, CI-blocking
```
CI 会在每次推送和 pull request 时运行上述所有检查以及完整的构建。
## 🗺 路线图
第一阶段（完整的 CRUD + 审计历史）已完成。接下来，大致按优先级排列：
**仪表盘和报告**（甘特图 · 时间线 · 热力图） · **码表管理** ·
**搜索和已保存的搜索** · **电子邮件/通知子系统** · **弹性列**
（无代码自定义字段） · **RLS 强制执行**。
## 📚 更多文档
| 文件 | 涵盖内容 |
|---|---|
| [`CLAUDE.md`](CLAUDE.md) | 架构规则、约定、已知的坑 —— 贡献前必读 |
| [`original-app-features.md`](original-app-features.md) | 正在重建的原始 Oracle APEX 应用程序的功能参考 |
作为独立的重建项目构建——无法访问原始数据库，仅能访问其演示。1:1 的复刻不是目标；打造一个更好的 P-Track 才是。
标签：Linux 内核安全, NestJS, React, Supabase, Syscalls, TypeScript, 企业应用, 后端开发, 安全插件, 测试用例, 项目管理
