5.6 KiB
5.6 KiB
hyb-oa 系统架构概览
版本：1.3
日期：2026-05-04
目的：描述系统当前实现、当前部署基线和仍待外部环境闭环的部分，为试运行与后续演进提供参考。
相关文档：
2026-05-04 已核实部署基线：
- 公网入口：
https://oa.hyinda.com - 反向代理：
caddy，当前配置为oa.hyinda.com -> reverse_proxy 127.0.0.1:3000 - 部署用户：
deploy（常规） /root（系统配置），shunli当前不可免密登录 - 部署目录：
/opt/hyb-oa-trialrun - 部署方式：本地执行
deploy/trialrun/deploy.sh，通过rsync同步到远端；远端目录不是 git 工作树 - 容器编排：脚本兼容
docker compose与docker-compose，当前服务器实际为docker-compose 1.29.2
1. 部署视图 (As-Is)
现状特点：单机/集群兼容、进程级别拆分、支持云原生存储与监控。
graph TB
subgraph Client["客户端"]
Browser["浏览器 (React SPA)"]
end
subgraph Cluster["部署环境 (Docker Compose Profiles)"]
Proxy["Caddy\nTLS/反代/前端托管"]
subgraph Server_Nodes["计算层"]
API["Fastify API\n(JOBS_ENABLED=false)"]
Worker["Worker 进程\n(npm run worker)"]
end
subgraph Infra_Services["基础设施"]
PG["PostgreSQL (16) + pg-boss"]
OSS["MinIO (S3 兼容) / Local FS"]
end
end
subgraph External["外部服务 / 可选集"]
TencentOCR["腾讯云 OCR"]
OIDC["OIDC Provider (Okta/Authing等)"]
Prom["可选：Prometheus (抓取 /metrics)"]
end
Browser -->|HTTPS/HTTP| Proxy
Proxy -->|/api/*| API
Proxy -->|/*| API
API -->|Prisma| PG
Worker -->|pg-boss| PG
API -->|Storage Service| OSS
Worker -->|Storage Service| OSS
Worker -->|API 调用| TencentOCR
API -->|OIDC Auth| OIDC
Prom -.->|Scrape| API
关键变更说明：
- Worker 进程独立：支持通过
docker compose --profile worker或docker-compose --profile worker拆分 API 与定时作业进程。 - 存储抽象层：适配本地文件系统与 S3/MinIO，通过
STORAGE_DRIVER切换。 - 治理接入：内置 Prometheus 指标采集
/metrics。 - 远端发布模型：当前生产化试运行通过
deploy/trialrun/deploy.sh从本地rsync到服务器，不依赖远端git pull。
2. 核心业务流程 (As-Is / 异步作业)
sequenceDiagram
participant E as 员工/行政
participant API as API Server
participant Q as pg-boss (Postgres)
participant W as Worker
participant O as 腾讯云/Mock OCR
participant WF as Workflow Engine
E->>API: 上传票据 (invoice_pool: pending_ocr)
API->>Q: 发布 ocr.tick 任务
API-->>E: 返回票据 ID (状态: pending_ocr)
W->>Q: 获取任务 (Fetch Job)
W->>W: 获取票据缓存或文件
W->>O: 调用 OCR
O-->>W: 结果
W->>API: 更新数据库 (available / ocr_failed)
E->>API: 提交报销 (submit)
API->>WF: 初始化实例 (0..n 关系)
WF-->>API: 创建 Task
API->>API: 触发通知 (邮件/站内)
3. 数据模型 (ER 图)
3.1 核心业务与工作流
erDiagram
REIMBURSEMENT_FORM ||--o{ WORKFLOW_INSTANCE : instances
LEAVE_REQUEST ||--o{ WORKFLOW_INSTANCE : instances
WORKFLOW_INSTANCE ||--|{ WORKFLOW_TASK : contains
WORKFLOW_INSTANCE ||--|{ WORKFLOW_HISTORY : logs
REIMBURSEMENT_FORM {
uuid id PK
string form_number UK
string status
decimal total_amount
}
WORKFLOW_INSTANCE {
uuid id PK
uuid entity_id FK
string entity_type "reimbursement | leave"
string current_status
}
WORKFLOW_TASK {
uuid id PK
uuid instance_id FK
uuid assignee_id FK
string assignee_role
string status
}
3.2 治理、安全与存储
erDiagram
EMPLOYEE ||--o{ DELEGATION_GRANT : principal
EMPLOYEE ||--o{ AUTH_SESSION : sessions
EMPLOYEE ||--o{ AUDIT_LOG : actor
INVOICE_POOL ||--o| OCR_RESULT : caches
EMPLOYEE {
uuid id PK
string bank_account "Encrypted"
string id_number "Encrypted"
int token_version
}
DELEGATION_GRANT {
uuid id PK
uuid principal_id FK
uuid delegate_id FK
datetime valid_to
}
AUDIT_LOG {
uuid id PK
string action
json extra "Context snapshot"
}
INVOICE_POOL {
uuid id PK
string file_sha256 UK-Index
string storage_path "local: or s3:"
uuid linked_reimbursement_id FK "Nullable"
}
4. 目录结构
hyb-oa/
├── server/
│ ├── src/
│ │ ├── services/
│ │ │ ├── storage/ # S3/Local 抽象
│ │ │ ├── crypto/ # AES-256 敏感字段加密
│ │ │ └── oidc/ # OIDC 客户端逻辑
│ │ ├── observability/ # Metrics & Logging
│ │ └── worker.js # Worker 进程入口
│ └── prisma/schema.prisma # 统一模型定义
├── deploy/trialrun/ # 多 Profile Compose & Runbook
└── docs/ # 规格书与本架构图
5. 展望 (To-Be / P7+)
- 分布式作业调度：从
pg-boss演进到支持 Dapr 或 Temporal（针对复杂长流程）。 - 多租户/物理隔离：支持更复杂的组织架构隔离方案。
- 前端微模块化：针对行政、财务、业务员拆分不同的前端 Bundle。