# hyb-oa 系统架构概览

**版本**：1.3  
**日期**：2026-05-04  
**目的**：描述系统当前实现、当前部署基线和仍待外部环境闭环的部分，为试运行与后续演进提供参考。

**相关文档**：
- [文档索引](./文档索引.md)
- [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)
- [实现状态矩阵](./feature-matrix.md)
- [试运行覆盖矩阵](trialrun/coverage-matrix.csv)
- [人工试运行报告](trialrun/manual-trialrun-report.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。