# CSP 系统架构（Architecture）

| 项 | 值 |
|---|---|
| 文档类型 | 系统级架构总览 |
| 版本 | v0.7（Draft） |
| 更新 | v0.6：新增 §13 许可与成本；v0.7：**搜索后备定 OpenSearch**（Apache 2.0，替代 ES）——许可灰区仅剩 Redis（内部免费/可换 Valkey） |
| 上级 | [需求分析总纲](需求分析总纲.md) |
| 说明 | 跨模块的系统架构与技术选型；**模块级实现设计见将来的 SDD（`docs/sdd/`）**。图例：✅ 已决策 / 🟡 建议待确认 / ⚪ 待决 |

> 定位于四层文档链路 **PRD → FSD → LDD → SDD** 之外的**横切总览**：回答"整个系统用什么技术、怎么分层、各端怎么接、集成/数据/安全怎么做"。

## 1. 目标与原则
- 支撑 6 域 13 模块、服务 TAM/PS/CSM 全组织；多端接入（Web / 飞书 App / 飞书 Bot / 手机 / CLI / AI）。
- **架构原则**：
  - **API-First**：业务层收口到一套 REST API（OpenAPI 契约），多端复用。
  - **模块化单体（Modular Monolith）**：高内聚低耦合（NFR-11），清晰模块边界 + 平台共有服务；少数能力可插拔（工时/Time，Tempo 式）。**不过早微服务**。
  - **集成防腐**：外部系统经 Adapter 隔离，统一重试/幂等/对账。
  - **配置化**：模板/工作流/审批链/权限/健康度模型等均可配（NFR-05）。
  - **可观测、可审计**：审计为一等能力（NFR-04）。
  - **可演进**：不阻断将来微服务化与物理分区域部署。

## 2. 技术栈选型

| 层 | 选型 | 状态 | 理由 |
|---|---|---|---|
| 前端 | **TypeScript + React + Ant Design Pro + Vite + TanStack Query** | ✅ | 企业中后台标准现代栈；构建用 Vite、服务端状态用 TanStack Query |
| 飞书 App | Lark 容器内 **H5 复用 Web SPA** + Lark JS SDK | 🟡 | 不重写前端；鉴权/原生桥走 SDK |
| 后端 | **Go + Gin**（REST + 业务层） | ✅ | PingCAP 母语、TiDB 生态、单二进制部署、并发适合同步/定时、顺手出 CLI（框架 Gin，OQ-A1） |
| API | **REST + OpenAPI 契约** | ✅ | 一处定义 → 生成前端 SDK / CLI / 文档 / AI 可用 |
| 数据库 | **TiDB**（MySQL 协议）；**HTAP**：OLTP 行存 + 报表走 TiFlash 列存 | ✅ | 已定；看板聚合吃 TiFlash 是架构红利 |
| DAL | **GORM**（ent 备选） | ✅ | Go 最主流 ORM、**PingCAP 内部/TiDB 生态惯用**、上手快；TiDB 讲 MySQL 协议，无需"专用 TiDB DAL" |
| CLI | **Cobra**（从 OpenAPI 生成/薄封装） | 🟡 | API-First 后近乎白送 |
| AI 接口 | **MCP Server / Agent API**（预留 seam） | 🟡 | 接 OQ-S9 协作、FR-ENG-13 采集、M10 草稿生成 |

**TiDB 使用约束（写进开发规范）**：① 主键避免连续 `AUTO_INCREMENT`（写热点）→ 用 `AUTO_RANDOM` 或应用侧分布式 ID；② 乐观/悲观事务按场景选；③ 外键倾向**应用层保证**；④ 控制大事务批量。

**前端栈说明**：CSP 是登录后的内部工具、**不需要 SEO** → 用 **SPA（纯 CSR）** 即可，无需 SSR/Next.js。前端从"HTML+jQuery→SPA(React/Vue)→今天 TS+组件化+Vite+服务端状态"一路演进；我们取当前主流。**可插拔场景的前端形态 = 微前端（Module Federation）**，即"前端版 WebPart"，见 §3.1。

## 3. 架构分层与模块

```
┌───────────────────────────────────────────────────────────────┐
│ 接入层  Web SPA · 飞书 H5 · 飞书 Bot · 手机 App · CLI · AI(MCP) │
├───────────────────────────────────────────────────────────────┤
│ API 层  REST(OpenAPI) + 统一鉴权(SSO/JWT · RBAC+ABAC) + 审计   │
├───────────────────────────────────────────────────────────────┤
│ 业务层  6 域 13 模块（M1..M13）                                │
│ 平台共有服务  工作流·审批(M9)·通知·事件时间线·配置中心·        │
│              签署·权益引擎·权限·搜索·审计                      │
│ 可插拔 App   工时/Time（Tempo 式，NFR-11）                     │
├───────────────────────────────────────────────────────────────┤
│ 集成层  Adapter：Nexus · 飞书 · Jira/JSM · GitHub · Ops/Clinic │
│         · 告警（防腐 + 重试/幂等/对账 + Outbox）               │
├───────────────────────────────────────────────────────────────┤
│ 数据层  TiDB(行存) + TiFlash(列存) · Redis(缓存) · 对象存储 · 搜索 │
└───────────────────────────────────────────────────────────────┘
```

- 部署上是**单体**（一个/少数部署单元），代码内按模块与共有服务清晰分包，模块间经**接口/领域事件**协作，不直接互相 import 内部实现。

### 3.1 插件 / App 契约（Plugin SPI，先订标准再开发）
> 后期可插拔 App 会变多——**契约必须一开始订死**（参考 **Backstage** / VS Code 扩展 / SharePoint WebPart）。新插件必须实现：

- **清单 Manifest**：`id / version / 依赖 / 声明所需权限 / 声明数据命名空间`。
- **生命周期**：install / enable / disable / uninstall / **upgrade + 版本兼容策略**。
- **扩展点（能挂哪）**：
  - 后端：注册 **API 路由 / 领域事件订阅 / 定时任务 / 配置 schema / 数据表命名空间**。
  - 前端：**微前端挂载槽（UI slot）** + Module Federation 暴露模块 + 共享设计 token。
- **隔离与权限**：声明式权限、数据边界、（必要时）沙箱。
- **打包与部署**：包格式、**插件注册中心**、部署方式。
- **首个参考实现**：工时/Time（Tempo 式，NFR-11）——用它验证这套 SPI。

## 4. 多端接入与 API-First
- 一套 REST API（OpenAPI 定义）服务全部端；**契约先行** → 生成前端 SDK、CLI、文档。
- **API 规范**：版本化、统一错误模型、分页、**幂等键**。

### 4.1 认证与授权（绝不匿名，deny-by-default）
> **证书认证"哪个客户端/设备"，OIDC/JWT 认证"哪个用户"——互补不互替**；RBAC/ABAC/审计都需要用户身份，证书替代不了登录。

| 访问方 | 用户身份（谁） | 客户端/传输（哪个端） | 状态 |
|---|---|---|---|
| Web / 飞书 H5 / 手机 | **OIDC SSO → 短时 JWT**（+PKCE，httpOnly cookie/安全存储） | mTLS 设备证书为**可选/后期**零信任加强层 | ✅ / 🟡 后期 |
| 直连 API / CLI / AI / Bot | **Bearer**（服务令牌 / OAuth2 client-credentials，scoped、可轮换） | 可叠加 mTLS | ✅ |
| 内部服务间 | 服务身份 | **mTLS（证书）** | 🟡 |

- 每端点必须有已认证主体；**deny-by-default**；统一 **RBAC（功能）+ ABAC（数据范围）**（M2）+ 全量审计（NFR-04）。
- 本期用户端主用 OIDC/JWT；设备证书层预留、后期按需。
- **飞书 Bot**：不是 REST 客户端，而是**事件订阅方**——飞书事件（消息/审批/卡片回调）→ 幂等事件入口 → 调同一业务 API。
- **飞书 App**：Lark 容器 H5 复用 Web SPA。
- **手机 App**：⚪ OQ-A6 原生 vs H5/PWA 复用。

## 5. 集成层（防腐 + 同步）

| 外部系统 | 方向 | 机制 |
|---|---|---|
| Nexus CRM（INT-01） | 只读 | 定时轮询 + 变化检测 + 每日对账；无事件推送 |
| 飞书（INT-05/12） | 读写 | 通知/加急/审批/建群/日历/Wiki 关联/**Bot 事件** |
| TiDB Support/JSM（INT-02） | 读 + 唯一写 | 工单/FRM/Bug 聚合（只读）+ 代客建单（唯一写路径） |
| GitHub / 告警（INT-07/08） | 读 | Bug 关联 / 告警聚合 |
| Ops / Clinic（INT-03/11） | 读 + 动作 | 集群/用量读；Ops 动作类集成（INT-10，含权限+审计） |

- 每源一 **Adapter（防腐层）**，统一 **重试 / 幂等 / 失败可重放 / 对账兜底**；写外部经 **Outbox** 与本地事务一致。

### 5.1 集成适配器契约（Adapter SPI，可扩展）
> 集成层必须**可扩展**：新接一个外部系统 = 实现标准接口 + 配置，**不改核心**。

- Adapter 声明：**能力**（read / write / event）、**同步机制**（轮询 / webhook）、**字段映射**（配置驱动）、**认证/密钥**、**重试/幂等/退避**、**对账 hook**、**健康/可观测**、**限流**。
- **集成注册中心**：Adapter 即插即用（概念类比 Airbyte connector / Camel component）。

## 6. 异步、事件与调度
- **定时调度**：Nexus 轮询、每日对账、SLA/提醒（M10）、报表定时、Check-in 待办生成。
- **内部事件总线（领域事件）**：驱动**事件时间线**（M1 FR-CUST-10）+ **Automations**（M9 触发→动作）。
- **队列**：✅ 起步用**轻量方案**（**asynq**，Redis 支撑 + Go Worker）；规模上来再引入 Kafka/RocketMQ（OQ-A3）。

## 7. 数据架构
- **OLTP**：TiDB 行存；**分析/看板**（M10）：TiFlash 列存副本（HTAP，一套库两负载）。
- **缓存**：Redis（会话/热数据/限流）。
- **全局搜索**：✅ **优先 TiDB 全文搜索**（数据不出库、少运维一个搜索集群）；若中文分词/相关性/规模不够，再引 **OpenSearch**（Apache 2.0，纯开源）作后备（OQ-A4；选型时需实测 TiDB 中文分词与相关性）。
- **对象存储**：S3 兼容（交付物版本/附件）；知识归档仍走**飞书 Wiki**（不自建知识库，M8）。
- 逻辑数据模型见各模块 **LDD + 数据字典**；**物理 DDL 留待 SDD**。

## 8. 认证、授权与安全
- **SSO OIDC**（飞书 + Google），email 合并（M2）。
- **AuthZ**：RBAC + ABAC 统一鉴权中间件；外部账号受限只读 + 签署。
- **安全**：全站 HTTPS、敏感字段/客户 PII **字段级加密**、密钥管理、最小权限、越权拦截。
- **审计**（NFR-04）：工时修改/依赖 override/状态流转/权限变更/审批/签署 全量审计，作一等能力。

## 9. 可观测性与部署
- **可观测**：日志 / 指标 / 链路（**OpenTelemetry**）+ 业务审计。
- **部署**：**云托管**——容器化（Docker）+ **Managed K8s**（EKS/GKE/ACK 之一，随公司/TiDB Cloud 对齐，OQ-A7）；CI/CD；环境 dev/staging/prod；**配置中心** + 密钥管理。
- **可用性**：核心服务 ≥ 99.5%（NFR-02），关键写幂等。

## 10. Region / 多租户
- 本期：**逻辑隔离**（单实例 + Region 字段 + ABAC，NFR-10）。
- 演进：架构不阻断将来**物理分区域部署**。

## 11. AI 集成（OQ-S9）
- **seam**：MCP Server / Agent API，走同一套 API + 权限 + 审计。
- 用例：AI 协作分析、FR-ENG-13 信息采集（群/纪要/工单抽取）、M10 Kickoff/RCA/QBR 草稿生成。
- 定位：**协作方而非下游**，本期预留接口、不强绑定实现。

## 12. NFR 落地映射（摘要）
| NFR | 架构手段 |
|---|---|
| 性能（NFR-01） | 缓存、TiFlash 分析、分页、连接池 |
| 可用性（NFR-02） | K8s 多副本、幂等、健康检查 |
| 安全（NFR-03） | HTTPS、加密、统一鉴权、越权拦截 |
| 审计（NFR-04） | 审计服务 + 领域事件 |
| 可扩展（NFR-05） | 配置中心、规则/模板配置化 |
| 集成（NFR-06） | Adapter + 重试/告警/Outbox |
| 一致性（NFR-07） | 工时→额度口径唯一、对账 |
| 多端开放（NFR-09） | API-First + OpenAPI + SDK/CLI |
| 数据驻留（NFR-10） | 逻辑隔离，演进物理分区 |
| 模块化/可插拔（NFR-11） | 模块化单体 + App/Plugin |

## 13. 许可与成本

| 组件 | 许可 | 软件免费 | 备注 |
|---|---|---|---|
| React / TS / Vite / Ant Design(Pro) / TanStack Query | MIT / Apache | ✅ | 商用免费 |
| Go / Gin / GORM | BSD / MIT | ✅ | |
| TiDB / TiFlash | Apache 2.0 | ✅ | 自建免费（PingCAP 自研，内部零成本） |
| asynq / OpenTelemetry / Kubernetes | MIT / Apache | ✅ | |
| **OpenSearch**（搜索后备，已选） | Apache 2.0 | ✅ | 替代 Elasticsearch（SSPL），避开许可灰区；主用仍是 TiDB 全文 |
| **Redis** | ⚠️ 7.4+ RSALv2/SSPL（源码可用、非 OSI） | 内部自用免费 | 有顾虑→用 **Valkey**（BSD 分叉，drop-in） |

- **软件许可 vs 托管成本**：软件本身几乎全免费；**花钱的是云托管/基础设施**（Managed K8s、云上 Redis/搜索集群等），属运维成本非授权费。
- **搜索已选 OpenSearch**（Apache 2.0）避开 ES 的 SSPL；仅剩 **Redis** 为源码可用许可（内部自用免费，顾虑可换 Valkey）。

## 14. 架构决策（OQ-A）

| 编号 | 问题 | 决策 | 状态 |
|---|---|---|---|
| OQ-A1 | Go Web 框架 | **Gin**——模块化单体够用、生态最大、低仪式；若团队偏好 DDD 脚手架可换 Kratos | ✅ |
| OQ-A2 | 数据访问层 DAL | **GORM**——Go 最主流 ORM、**PingCAP 内部/TiDB 生态惯用**、上手快（ent 类型安全为备选） | ✅ |
| OQ-A3 | 异步/消息队列 | **起步轻量**：asynq（Redis 支撑）+ Go Worker；规模化再引入 Kafka/RocketMQ | ✅ |
| OQ-A4 | 全局搜索 | **优先 TiDB 全文搜索**（少运维、数据不出库）；不足再引 **OpenSearch**（Apache 2.0）后备（选型需实测中文分词/相关性） | ✅ |
| OQ-A5 | API 网关（挡在 API 前的统一入口：路由/鉴权/限流/mTLS 终止，如 Kong/APISIX） | **应用内中间件为主**（写成 Gin 中间件，少养一个组件）；独立网关待拆服务/要 mTLS 时再加 | ✅ |
| OQ-A6 | 手机端 | **本期复用飞书 H5 / PWA，不做原生**；确有原生诉求再评估 | ✅ |
| OQ-A7 | 部署目标 | **云托管**：容器化 + **Managed K8s**（如 EKS/GKE/ACK）；具体云厂商随公司/TiDB Cloud 对齐 | ✅ |