201 行
5.7 KiB
Markdown
201 行
5.7 KiB
Markdown
# hyb-oa 系统架构概览
|
||
|
||
**版本**：1.3
|
||
**日期**：2026-05-04
|
||
**目的**：描述系统当前实现、当前部署基线和仍待外部环境闭环的部分，为试运行与后续演进提供参考。
|
||
|
||
**相关文档**：
|
||
- [文档索引](./文档索引.md)
|
||
- [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)
|
||
- [实现状态矩阵](./历史功能状态矩阵.md)
|
||
- [试运行覆盖矩阵](trialrun/试运行覆盖矩阵.csv)
|
||
- [人工试运行报告](trialrun/人工试运行报告.md)
|
||
|
||
**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)
|
||
|
||
> 现状特点：**单机/集群兼容、进程级别拆分、支持云原生存储与监控。**
|
||
|
||
```mermaid
|
||
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 / 异步作业)
|
||
|
||
```mermaid
|
||
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 核心业务与工作流
|
||
|
||
```mermaid
|
||
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 治理、安全与存储
|
||
|
||
```mermaid
|
||
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。
|