520 行
14 KiB
Markdown
520 行
14 KiB
Markdown
# hyb-oa 系统架构概览
|
||
|
||
**版本**：1.1
|
||
**日期**：2026-02-09
|
||
**目的**：帮助新成员快速理解系统"怎么做"的全貌（并提供演进方向）。
|
||
|
||
---
|
||
|
||
## 阅读指南：As‑Is vs To‑Be
|
||
|
||
- **As‑Is（现状）**：以当前仓库代码、试运行部署包为准，用于回归、排障、交接。
|
||
- **To‑Be（前瞻）**：面向 P5+ 的演进目标，用于指导架构升级；所有未来项都会明确标注 **[To‑Be/未实现]**，避免误解为已交付。
|
||
|
||
---
|
||
|
||
## 1. 系统架构（部署视图）
|
||
|
||
### 1.1 部署视图（As‑Is / 单机试运行）
|
||
|
||
> 现状特点：**单机可运行、同域可部署、作业同进程**（node-cron），外部依赖最小。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Client["客户端"]
|
||
Browser["浏览器 (React SPA)"]
|
||
end
|
||
|
||
subgraph Node["单机（dev/trialrun）"]
|
||
Proxy["可选：Nginx/Caddy\nTLS/反代/限流/上传体积控制"]
|
||
App["Fastify Server\n(API + 可选静态托管 client/dist)"]
|
||
Jobs["同进程 Jobs (node-cron)\nOCR Job / 委派回收 Job"]
|
||
PG["PostgreSQL (15+/16)"]
|
||
Storage["本地存储 (票据文件)"]
|
||
end
|
||
|
||
subgraph External["外部服务（可选）"]
|
||
TencentOCR["腾讯云 OCR"]
|
||
end
|
||
|
||
Browser -.->|可选 HTTPS| Proxy
|
||
Browser -->|dev 可直连| App
|
||
Proxy -->|/api/*| App
|
||
Proxy -->|/*| App
|
||
|
||
App -->|Prisma| PG
|
||
Jobs -->|Prisma| PG
|
||
App -->|文件读写| Storage
|
||
Jobs -->|文件读写| Storage
|
||
Jobs -->|API 调用| TencentOCR
|
||
```
|
||
|
||
**说明**
|
||
- `PostgreSQL` 版本口径：开发 compose 可为 15，试运行包建议 16（两者均可）。
|
||
- `Proxy`（Nginx/Caddy）是可选项：试运行/上线建议配置（TLS、上传限制、限流），开发联调可跳过。
|
||
- `App` 可通过 `SERVE_CLIENT_DIST=true` 托管 `client/dist`，实现同域 cookie 与 SPA fallback。
|
||
- `Jobs` 现状与 `App` 同进程（node-cron）；未来可拆分独立 Worker（见 To‑Be）。
|
||
|
||
### 1.2 部署视图（To‑Be / 可扩展但仍可单机）
|
||
|
||
> 目标：在不改变“单机可跑”前提下，逐步具备“可横向扩展、可观测、可运维”的形态。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Client["客户端"]
|
||
Browser["浏览器 (React SPA)"]
|
||
end
|
||
|
||
subgraph Edge["边缘层 [To‑Be/未实现]"]
|
||
Proxy["Nginx/Caddy/WAF\nTLS/反代/限流/上传策略"]
|
||
end
|
||
|
||
subgraph App["应用层"]
|
||
API["Fastify API (stateless)\n可选静态托管 client/dist"]
|
||
Worker["Job Worker [To‑Be/未实现]\nOCR / 委派回收 / 清理作业"]
|
||
Queue["队列/Redis [To‑Be/未实现]\nBullMQ/Streams（可选）"]
|
||
end
|
||
|
||
subgraph Data["数据层"]
|
||
PG["PostgreSQL\nPgBouncer [To‑Be/未实现]"]
|
||
ObjectStorage["对象存储 [To‑Be/未实现]\nS3/OSS/MinIO"]
|
||
end
|
||
|
||
subgraph Obs["可观测性 [To‑Be/未实现]"]
|
||
Logs["结构化日志聚合\nLoki/ELK"]
|
||
Metrics["metrics\nPrometheus"]
|
||
end
|
||
|
||
subgraph External["外部服务"]
|
||
TencentOCR["腾讯云 OCR"]
|
||
end
|
||
|
||
Browser --> Proxy
|
||
Proxy --> API
|
||
|
||
API --> PG
|
||
Worker --> PG
|
||
|
||
API --> ObjectStorage
|
||
Worker --> ObjectStorage
|
||
|
||
Worker <--> Queue
|
||
Worker --> TencentOCR
|
||
|
||
API --> Logs
|
||
Worker --> Logs
|
||
API --> Metrics
|
||
Worker --> Metrics
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 核心业务流程（报销审批 / As‑Is）
|
||
|
||
> 核心链路：**票据上传 →（异步）OCR → 绑定票据 → 提交报销 → 工作流审批 → 财务付款 → 票据归档**。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant E as 员工
|
||
participant S as Server(Fastify)
|
||
participant J as OCR Job(node-cron)
|
||
participant O as 腾讯云OCR
|
||
participant WF as 工作流引擎
|
||
participant M as 经理
|
||
participant F as 财务
|
||
|
||
E->>S: 上传票据 (invoice_pool: pending_ocr/available)
|
||
S-->>E: 返回 invoiceId + status
|
||
|
||
J->>S: 认领 pending_ocr (FOR UPDATE SKIP LOCKED + 原子回写锁)
|
||
J->>O: OCR 识别（可 mock/off）
|
||
O-->>J: 识别结果/错误
|
||
J->>S: 更新 invoice_pool (available/ocr_failed)
|
||
|
||
E->>S: GET /api/invoice-pool/:id (轮询/刷新)
|
||
S-->>E: 返回最新 status 与字段
|
||
|
||
E->>S: 绑定票据到报销单 (available -> bound)
|
||
E->>S: 提交报销 (draft -> reviewing)
|
||
S->>WF: 创建 workflow_instance + 首个 task
|
||
WF-->>M: 待办 task（assignee_id 或 assignee_role）
|
||
|
||
M->>S: approve / return / reject / transfer
|
||
WF->>WF: 推进流程并写 workflow_history
|
||
|
||
F->>S: pay (approved -> paid)
|
||
S->>S: bound 票据 -> archived (used_complete)
|
||
S->>S: 写 audit_logs（关键运营/安全动作）
|
||
```
|
||
|
||
**证据链边界（现状）**
|
||
- `workflow_history`：流程证据（针对某个 workflow_instance/task 的动作轨迹），用于还原审批过程。
|
||
- `audit_logs`：合规/安全证据（登录、委派回收、用户管理等跨域操作），用于审计与风控追踪。
|
||
|
||
---
|
||
|
||
## 3. 数据模型（ER 图 / As‑Is）
|
||
|
||
> 说明：为可读性仅列关键字段与关系；具体字段以 Prisma schema 为准。
|
||
|
||
### 3.1 组织 / 权限 / 会话 / 审计
|
||
|
||
```mermaid
|
||
erDiagram
|
||
Department ||--o{ Employee : contains
|
||
Department ||--o{ Department : children
|
||
|
||
Employee ||--o{ EmployeeRole : has
|
||
Employee ||--o{ AuthSession : sessions
|
||
Employee ||--o{ PasswordResetCode : resets
|
||
Employee ||--o{ AuditLog : writes
|
||
Employee ||--o{ DelegationGrant : principal
|
||
Employee ||--o{ DelegationGrant : delegate
|
||
|
||
Department {
|
||
uuid id PK
|
||
string name
|
||
uuid parent_id FK
|
||
}
|
||
|
||
Employee {
|
||
uuid id PK
|
||
string employee_no UK
|
||
uuid department_id FK
|
||
uuid direct_manager_id FK
|
||
string status
|
||
int token_version
|
||
}
|
||
|
||
EmployeeRole {
|
||
uuid employee_id PK,FK
|
||
string role_code PK
|
||
}
|
||
|
||
AuthSession {
|
||
uuid id PK
|
||
uuid employee_id FK
|
||
string device_fingerprint
|
||
datetime expires_at
|
||
datetime revoked_at
|
||
}
|
||
|
||
PasswordResetCode {
|
||
uuid id PK
|
||
uuid employee_id FK
|
||
datetime expires_at
|
||
datetime used_at
|
||
}
|
||
|
||
DelegationGrant {
|
||
uuid id PK
|
||
uuid principal_employee_id FK
|
||
uuid delegate_employee_id FK
|
||
datetime valid_from
|
||
datetime valid_to
|
||
datetime revoked_at
|
||
}
|
||
|
||
AuditLog {
|
||
uuid id PK
|
||
string request_id
|
||
uuid actor_id FK
|
||
string action
|
||
string target_type
|
||
uuid target_id
|
||
datetime created_at
|
||
}
|
||
```
|
||
|
||
### 3.2 报销与票据（含 OCR 缓存）
|
||
|
||
```mermaid
|
||
erDiagram
|
||
Employee ||--o{ ReimbursementForm : owns
|
||
Employee ||--o{ ReimbursementForm : submits
|
||
Department ||--o{ ReimbursementForm : belongs
|
||
|
||
ReimbursementForm ||--o{ ReimbursementItem : contains
|
||
ExpenseType ||--o{ ReimbursementItem : categorizes
|
||
|
||
Employee ||--o{ InvoicePool : owns
|
||
Employee ||--o{ InvoicePool : uploads
|
||
ReimbursementForm ||--o{ InvoicePool : links
|
||
ReimbursementItem ||--o{ InvoicePool : linksItem
|
||
OcrResult ||--o{ InvoicePool : cachedFor
|
||
|
||
ReimbursementForm {
|
||
uuid id PK
|
||
string form_number UK
|
||
uuid owner_id FK
|
||
uuid submitter_id FK
|
||
uuid department_id FK
|
||
string status
|
||
decimal total_amount
|
||
string payment_voucher_no
|
||
}
|
||
|
||
ReimbursementItem {
|
||
uuid id PK
|
||
uuid reimbursement_id FK
|
||
uuid expense_type_id FK
|
||
decimal amount
|
||
string description
|
||
}
|
||
|
||
ExpenseType {
|
||
uuid id PK
|
||
string code UK
|
||
string name
|
||
string category
|
||
}
|
||
|
||
InvoicePool {
|
||
uuid id PK
|
||
uuid owner_employee_id FK
|
||
uuid uploaded_by_employee_id FK
|
||
string storage_path
|
||
string file_sha256
|
||
string status
|
||
uuid linked_reimbursement_id FK
|
||
uuid linked_item_id FK
|
||
uuid ocr_result_id FK
|
||
}
|
||
|
||
OcrResult {
|
||
uuid id PK
|
||
string file_sha256
|
||
string ocr_provider
|
||
string ocr_type
|
||
json result_json
|
||
}
|
||
```
|
||
|
||
**关系备注（关键纠偏）**
|
||
- `InvoicePool.linked_reimbursement_id / linked_item_id / ocr_result_id` 均为 **可空字段**（票据可长期处于 available/pending_ocr 未绑定状态）。
|
||
|
||
### 3.3 工作流引擎（含转审证据）
|
||
|
||
```mermaid
|
||
erDiagram
|
||
WorkflowDefinition ||--o{ WorkflowInstance : creates
|
||
ReimbursementForm ||--o{ WorkflowInstance : instances
|
||
WorkflowInstance ||--o{ WorkflowTask : tasks
|
||
WorkflowInstance ||--o{ WorkflowHistory : history
|
||
WorkflowTask ||--o{ WorkflowHistory : taskHistory
|
||
|
||
Employee ||--o{ WorkflowTask : assigned
|
||
Employee ||--o{ WorkflowTask : completed
|
||
Employee ||--o{ WorkflowHistory : actions
|
||
|
||
ReimbursementForm ||--o{ ApprovalTransfer : transfers
|
||
Employee ||--o{ ApprovalTransfer : from
|
||
Employee ||--o{ ApprovalTransfer : to
|
||
|
||
WorkflowDefinition {
|
||
uuid id PK
|
||
string entity_type
|
||
int version
|
||
bool is_active
|
||
json definition_json
|
||
}
|
||
|
||
WorkflowInstance {
|
||
uuid id PK
|
||
uuid workflow_id FK
|
||
string entity_type
|
||
uuid entity_id FK
|
||
uuid submitter_id FK
|
||
string current_status
|
||
string current_step_id
|
||
json context_data
|
||
}
|
||
|
||
WorkflowTask {
|
||
uuid id PK
|
||
uuid instance_id FK
|
||
string step_id
|
||
string step_name
|
||
uuid assignee_id FK
|
||
string assignee_role
|
||
string status
|
||
string outcome
|
||
}
|
||
|
||
WorkflowHistory {
|
||
uuid id PK
|
||
uuid instance_id FK
|
||
uuid task_id FK
|
||
uuid actor_id FK
|
||
string action
|
||
json payload
|
||
}
|
||
|
||
ApprovalTransfer {
|
||
uuid id PK
|
||
uuid reimbursement_id FK
|
||
uuid from_approver_id FK
|
||
uuid to_approver_id FK
|
||
string reason
|
||
string status
|
||
}
|
||
|
||
ApprovalRule {
|
||
uuid id PK
|
||
string name
|
||
decimal min_amount
|
||
decimal max_amount
|
||
string level1_role
|
||
string level2_role
|
||
string level3_role
|
||
bool enabled
|
||
int priority
|
||
}
|
||
```
|
||
|
||
**关系备注（关键纠偏）**
|
||
- `ReimbursementForm -> WorkflowInstance` 是 **0..n**（同一报销单可能多次提交产生多个实例）。
|
||
- `WorkflowTask.assignee_id` 与 `assignee_role` 在语义上通常 **互斥**（实现允许为空/组合以支持候选/角色任务）。
|
||
- `WorkflowHistory.task_id` 在实现中为 **可空字段**（例如非 task 维度的历史事件）。
|
||
- `ApprovalRule` 是规则配置表：用于构建审批步骤，通常以 `workflow_history.payload` 等形式被引用（并非强制外键关联）。
|
||
|
||
### 3.4 单号序列（系统表）
|
||
|
||
```mermaid
|
||
erDiagram
|
||
DocumentSequence {
|
||
string document_type PK
|
||
string prefix
|
||
string separator
|
||
int current_number
|
||
string reset_period
|
||
datetime updated_at
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 状态机
|
||
|
||
### 4.1 报销单状态（As‑Is）
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> draft: create
|
||
draft --> reviewing: submit
|
||
reviewing --> draft: return / withdraw
|
||
reviewing --> rejected: reject
|
||
reviewing --> approved: final approve
|
||
approved --> paid: pay
|
||
rejected --> draft: edit & resubmit
|
||
paid --> [*]
|
||
```
|
||
|
||
### 4.2 报销单状态（To‑Be/未实现）
|
||
|
||
> 预留方向：补齐“作废/取消”语义，支持运营或系统终止（例如提交后发现异常、关账等）。
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> draft
|
||
draft --> reviewing: submit
|
||
reviewing --> cancelled: cancel [To‑Be]
|
||
approved --> cancelled: cancel [To‑Be]
|
||
cancelled --> [*]
|
||
```
|
||
|
||
### 4.3 票据池状态（As‑Is）
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> pending_ocr: upload (OCR enabled)
|
||
[*] --> available: upload (OCR off/mock)
|
||
pending_ocr --> available: OCR success
|
||
pending_ocr --> ocr_failed: OCR failed / duplicate
|
||
available --> bound: bind
|
||
bound --> archived: pay (used_complete)
|
||
```
|
||
|
||
### 4.4 票据池状态（To‑Be/未实现）
|
||
|
||
> 预留方向：增加“解绑、超时归档、人工纠错”能力（需要额外 API/作业/运营策略支撑）。
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
bound --> available: unbind [To‑Be]
|
||
available --> archived: unused_timeout [To‑Be]
|
||
ocr_failed --> available: manual_fix [To‑Be]
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 目录结构（简化视图）
|
||
|
||
```
|
||
hyb-oa/
|
||
├── client/ # 前端 (React + Vite + Tailwind)
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 封装
|
||
│ │ ├── auth/ # 会话与权限映射
|
||
│ │ ├── components/ # UI 组件
|
||
│ │ ├── layouts/ # 布局
|
||
│ │ ├── pages/ # 页面
|
||
│ │ ├── query/ # React Query 统一封装
|
||
│ │ ├── router/ # 路由与守卫
|
||
│ │ └── styles/ # Token/基础样式
|
||
│ └── tests/e2e/ # Playwright E2E
|
||
│
|
||
├── server/ # 后端 (Fastify + Prisma)
|
||
│ ├── src/
|
||
│ │ ├── routes/ # API 路由
|
||
│ │ ├── services/ # 业务逻辑 (OCR 等)
|
||
│ │ ├── jobs/ # 定时任务 (OCR/委派回收)
|
||
│ │ └── utils/ # 工具函数
|
||
│ ├── prisma/ # 数据库 Schema & 迁移
|
||
│ └── scripts/ # 回归脚本
|
||
│
|
||
├── deploy/trialrun/ # 试运行部署包
|
||
├── docs/ # 文档 (需求/实施/架构)
|
||
├── issues/ # Issue CSV 执行合同
|
||
└── scripts/ # 门禁/备份恢复脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 技术栈速览（As‑Is）
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|---|---|---|
|
||
| 前端 | React 18 + Vite + Tailwind | SPA；配套 React Query、Radix primitives、Playwright E2E |
|
||
| 后端 | Fastify + Prisma | Node.js；JWT + refresh cookie；RBAC 权限 |
|
||
| 数据库 | PostgreSQL 15+（试运行建议 16） | Prisma ORM；关键队列/作业依赖 SQL 锁语义 |
|
||
| OCR | 腾讯云（可 mock/off） | 异步作业 + 并发锁；失败降级不阻塞上传 |
|
||
| 部署 | Docker Compose | 单机试运行；可选反代同域 |
|
||
| CI | GitHub Actions | 最小门禁 + 回归 + E2E（按开关分层执行） |
|
||
|
||
---
|
||
|
||
## 7. 相关文档
|
||
|
||
- [需求规格说明书](./requirements-specification.md) - 完整的 P0 需求定义
|
||
- [实施计划](./implementation_plan.md) - 里程碑与验收标准
|
||
- [技术栈报告](./tech_stack_report.md) - 选型依据
|
||
|
||
---
|
||
|
||
## 8. 对标与演进（不造轮子）
|
||
|
||
> 本节只列“可借鉴能力清单”，不代表已实现。
|
||
|
||
### 8.1 工作流（Camunda / Flowable / Activiti 思想）
|
||
- **Candidate / Claim / Unclaim**：候选人/候选组与认领机制（减少“角色任务抢占冲突”，提升可控性）。
|
||
- **SLA / Due date / Escalation**：任务期限与超时升级（试运行后期高频诉求）。
|
||
- **History & Audit 分层**：流程历史（workflow_history）与合规审计（audit_logs）职责边界清晰。
|
||
|
||
### 8.2 费用报销（Odoo / ERPNext 的单据分层）
|
||
- **业务单据 vs 付款凭证/对账**：先保持 `payment_voucher_no/payment_date/channel` 的轻量字段；后续可演进独立 `payment_transactions` 与对账状态，不影响现有 API。
|
||
|
||
### 8.3 合规审计（企业级通用实践）
|
||
- **统一 request_id/trace_id**：贯穿 API 与作业日志（便于追踪、复盘、举证）。
|
||
- **最小可观测性**：ready/metrics/log 聚合（先最小可用，后续再引入 OpenTelemetry 等体系化方案）。
|