opc-backup/云超服一体化架构设计方案.md

# 云超服一体化平台架构设计方案

> 版本：v0.1（2026-08-23）
> 定位：在现有全部代码资产基础上，面向「统一身份 · 统一后端 · 多端互通 · 智慧园区」的一体化架构设计。
> 阅读对象：架构 / 前后端 / 园区端 / 算力相关开发。
> 关联文档：`design/云超服平台/`（身份体系与端口权限、全量方案、架构初步设计）、`materials/培训计划/课程体系0.1/三端架构设计.md`、各代码仓库 `README.md`。

---

## 〇、设计原则

1. **一个身份**：全平台（桌面端 / Web / 小程序 / 园区大屏）共享一套账号与端口身份，数据全部归属到身份。
2. **一个后端、模块化拆分**：业务与身份收敛到后端 server（现 `server-core` 演进），内部按业务域拆模块，可演进为微服务，消除多后端多账号并存。
3. **专业服务外置**：算力引擎（`new-api`，仅服务、管理/页面自研）、Agent 运行时（智能体桌面应用内）作为专业服务，通过明确 API 与后端协作，不混业务。
4. **算力额度服务端统一管控**：架构上预留充值链路，**当前流程由服务端统一增减额度**，用户端只读展示。
5. **契约可校验**：后端出 OpenAPI → 多端前端生成 TS client，消灭手写契约漂移。
6. **迁移渐进**：先统一身份 → 再迁业务域 → 再补用户端功能 → 最后升级大屏，全程可回滚。

---

## 一、设计目标与六条要求映射

| # | 要求 | 落地主体 | 本文档章节 |
|---|------|---------|-----------|
| 1 | 全局统一身份系统 | 核心服务端七端口 RBAC（已有） + 六端登录归一 | §三 |
| 2 | 后端集成算力调度、用户管理；运营端迁移 web 课程/活动管理 | 核心服务端业务域扩展 + `new-api` 集成 | §四 |
| 3 | 多端（小程序 / web业务 / web官网 / admin管理平台 / 智能体桌面 / 大屏）数据互通 | 统一身份 + 统一后端 + 统一契约 | §四.4 |
| 4 | 用户端完整功能：算力/园区入驻/智能体/政策/财务/工商 | 核心服务端 `opc` 端口 + 各业务域 router | §五 |
| 5 | 园区端智慧大屏增强，数据由后端园区端管理可换 | `dpm` 数据源改造 + 核心服务端园区数据域 | §六 |
| 6 | 大屏真实展示人员、智能体实时消耗（token/流水） | `dpm` 对接核心服务端 + `new-api` 实时数据 | §六 |

---

## 二、总体架构（目标态）

![总体架构图](figures/01-overview.svg)

### 2.1 前端（6 端）

| 端 | 定位 | 代码资产 | 后端接入 |
|----|------|---------|---------|
| **小程序** | 移动 C 端（OPC AI：测评/政策/报名/算力） | training/miniprogram | gateway · `/auth` `/opc/*` `/tests/*` |
| **web业务** | 业务 C 端（培训/课程/活动/测评/政策） | training/website/user | gateway |
| **web官网** | 公开展示站（产品/政策/招生/案例） | web-official（原 PineAgentsWeb） | gateway（公开接口 + 静态内容） |
| **admin管理平台** | 运营/政务/企业/载体/服务商/投资人管理 | console 管理端（operator/government/…端口） | gateway · `/admin/*` |
| **智能体桌面应用** | 智能体工作台（Agent OS + Tauri 壳） | agent-desktop（原 PineAgents，console + Tauri） | gateway（`/auth` `/agents`）+ 算力服务 → 引擎 `/v1` |
| **大屏桌面应用** | 多园区通用大屏（园区账号登录显示本园区） | park-desktop（原 dpm，Tauri） | gateway（`/api/park/*`，org_id 隔离） |

### 2.2 后端（server · 完整服务群）

> **后端是一组完整服务构成的服务群**，可整体一个进程部署（模块化单体），亦可按需拆成独立微服务（分库 + 网关路由）。模块边界即微服务拆分边界。

**应用服务（业务域）**

| 服务 | 职责 | 现状基础 |
|------|------|---------|
| **核心服务** | 统一入口（gateway）+ 身份（auth）+ 业务模块（business/agent/task/gov/park/notify/file） | server-core 演进 + training 业务迁移 |
| **算力服务** | 封装 new-api 引擎：令牌/额度/流水聚合、用户算力自助；**仅消费 new-api 的服务（relay 与程序化管理 API），管理与页面全部自研** | compute_client → new-api |

**基础设施服务**

| 服务 | 职责 | 说明 |
|------|------|------|
| **MQTT 消息服务** | 实时消息/指令/推送总线 | EMQX；大屏（dpm）、桌面端通知、控制指令复用 |
| **缓存服务** | 会话/限流/聚合缓存 | Redis；多节点共享额度与状态 |
| **数据库服务** | 主库 + 分库 | 模块化单体用 SQLite；微服务演进用 MySQL / PostgreSQL |

**核心服务内部模块（微服务拆分边界）**

| 模块 | 职责 |
|------|------|
| gateway 网关 | 统一入口、鉴权校验、路由、契约、跨端限流 |
| auth 身份 | 七端口 RBAC、select-identity、审计、登录 |
| business 业务 | 课程/活动/报名/测评/政策申报/入驻/财务/工商 |
| agent 智能体 | 智能体定义/模板/桌面同步 |
| task 任务生态 | 任务/服务商/结算/合同/争议/信用 |
| gov 政务 | 补贴审批、政务三级数据范围 |
| park 园区 | 园区数据域 + 大屏聚合 |
| notify 通知 | 通知/消息/推送（可接 bark-notify） |
| file 文件 | 上传/媒体/静态托管 |

> **new-api 定位**：只作为**算力引擎服务**被算力服务消费（`/v1` 中继 + 管理 API 程序化调用）；**不使用其自带 web 管理页面/用户页面**——算力相关的管理全部在 admin管理平台（console）实现，页面风格统一。

### 2.3 专业服务（外置，不混业务）

| 服务 | 职责 | 边界 |
|------|------|------|
| **算力引擎**（new-api） | 模型网关 + 额度/令牌 + token 流水/计费 | 只做模型计量，不做身份；**仅服务，无页面暴露** |
| **Agent 运行时**（智能体桌面应用内） | 智能体执行引擎（决策/工具/频道/沙箱） | 算力统一走算力服务 → 引擎 `/v1` |

> **部署形态**：算力引擎随后端服务群一同部署（同机/同编排），**不做本地推理**——全部渠道均为**云厂商代理**（OpenAI / DeepSeek / 通义千问 / Claude / Gemini 等），无需 GPU 主机。算力服务与引擎同机互通，网络简单、凭据不扩散。**代码**：`code/compute-engine/`（new-api，启动命令见其 `README.云超服.md`）。

> **退役清单**：training `server`（业务迁后端后退役）、training `website/server`（mock，已基本废弃）、training `website/platform` 管理端（迁入 admin管理平台）。

---

## 三、统一身份系统（要求 1）

### 3.1 身份中心
沿用核心服务端已有的 **七端口 RBAC**：`users` + `user_identities`（一账号多端口身份）+ `roles/permissions/role_permissions` + `select-identity` 切换 + 政务三级数据范围。该机制已成熟（含提权防护、token_version 吊销、`require_port` 隔离）。

### 3.2 六端登录归一（同一账号 = 同一身份）

| 端 | 登录方式 | 到核心服务端的映射 |
|----|---------|------------------|
| 智能体桌面应用 | 账号密码 + select-identity | `POST /auth/login`（已有） |
| admin管理平台 | 账号密码 + RBAC | `/auth/login` + 运营/政务等端口身份 |
| web业务 | 手机号 + 验证码 | 复用 `register`/`phone-login`（补手机号登录端点） |
| 小程序 | 微信 `wx.login` + `getPhoneNumber` | 新增 `wx_openid` 绑定字段（`users`/`user_identities`），登录即建 `opc_member` 身份 |
| web官网 | 公开访问（可选登录） | 仅公开接口 + 静态内容 |
| 大屏桌面应用 | 园区账号（carrier 身份） | `/auth/login` + `select-identity` → 绑定 org_id |

**新增能力（核心服务端）**：
- `users` 表补 `wx_openid`（或经 `user_identities` 建立微信身份行）；补 `/auth/phone-login`、`/auth/send-code`、`/auth/wx-login`、`/auth/wx-phone` 端点（迁移自 training `server/app/auth.py` 的短信与微信流程，合并手机号账号逻辑）。
- 原 training `accounts` 表迁移：`username/phone/wxid/name/avatar/status_label/topics/source` → `users` + `opc_profiles`（报名画像字段挂到 `opc_member` 身份，沿用现 `opc_profiles` 表）。

### 3.3 数据归属
**所有业务数据的唯一归属 = `user_id`（+ 可选 `identity_id` 维度）**。课程报名、测评结果、算力订单、入驻申请、财务流水、政策申报一律以 `user_id` 关联，天然实现多端互通（同一人在任意端操作，数据落在同一身份上）。

![统一身份与多端互通](figures/02-identity.svg)

---

## 四、统一后端与业务域（要求 2、3）

### 4.1 核心服务端业务域扩展（数据模型）

在现有 34 张表基础上新增（继承现 `models.py` 风格）：

| 新表 | 关键字段 | 对应需求 |
|------|---------|---------|
| `courses` | id/title/category/level/chapters(JSON)/syllabus/start_end/venue/quota/price/status/cover | 课程实体（迁自 website `data/*`） |
| `activities` | id/type(free·salon·training·park)/title/subtitle/desc/location/host/image/link/start_at/end_at/checkin_at/duration_min/capacity/status/audit_mode/show_capacity | 通用活动（迁自 training `events`） |
| `bookings` | id/user_id/target_type(course·activity·park)/target_id/status(applying·approved·attended·absent)/audit_status/note/checkin_at | 统一报名（替代 roadshow_registrations + training_enrollments + training bookings） |
| `tests` + `test_results` | id/title/category/questions(JSON)/pass_score；id/user_id/test_id/score/passed/cert_id | 测评/考核（引擎迁自 `opc_engine.py`/`policy_engine.py`/`survey_data.py`） |
| `compute_accounts` + `compute_orders` | user_id/balance/token_ref；id/user_id/amount/type(add·deduct·freeze)/reason/operator_id/created_at | 算力额度与增减流水 |
| `park_admissions` | id/opc_id/carrier_id/area/station_count/purpose/status(apply·auditing·approved·settled)/contract_id | 园区入驻申请 |
| `business_services` + `business_orders` | id/name/fee/agency_id；id/user_id/service_id/status(apply·pending·done) | 工商/政务代办 |
| `invoices` + `finance_accounts` | id/org_id/amount/type；企业/服务商对公财务 | 企业/服务商财务 |
| `park_org` + `park_companies` + `park_members` | 园区信息/企业名录/人员名单（大屏数据源） | 园区端数据管理 |
| `policy_applications` | id/user_id/policy_id/status | 政策申报（补 `subsidy_applications` 之外的普通政策申报） |

**迁移自 training 的数据**：`events → activities`、`bookings → bookings`、`tests/policy_logs/plan_logs/survey_logs → tests + test_results`（测评结果）、`policy_data/plan_data/survey_data → 核心服务端 `content_items`(policy 类型) + 引擎服务。

> **多园区维度**：园区相关数据（`park_*`、园区活动、报名、播放列表）均以 **`org_id` 隔离**；园区 = `organizations(type=carrier)`。详见 §六。

### 4.2 运营端：web 课程/活动管理迁移（要求 2）

把 training `website/platform` 的管理功能整体迁入 **console 运营端（operator 端口）**，新增 router `rbac_operator` 端点（沿用现 `/admin` 前缀）：

| 管理能力 | 现所在（web platform） | 迁至端点 |
|---------|----------------------|---------|
| 课程管理 | `Schedule/Structures/Cards/Tools`（静态内容页） | `GET/POST/PUT/DELETE /admin/courses`、`/admin/courses/{id}/status` |
| 活动/排期管理 | `PineEvents` | `GET/POST/PUT/DELETE /admin/activities`、`/admin/activities/{id}/status` |
| 报名管理 | `PineBookings`（名单/状态/审核/导出 CSV） | `GET /admin/bookings`、`PATCH /admin/bookings/{id}`、`POST /admin/bookings/export` |
| 测评管理 | `PineTests` | `GET /admin/tests`、`POST /admin/tests`、`GET /admin/test-results`、`POST /admin/test-results/export` |
| 签到 | `checkins` | `POST /admin/checkins`（时间闸复用） |
| 运营统计 | `PineOps` | `GET /admin/stats/overview`（扩展课程/活动/测评/算力维度） |

**前端**：console 新增 `Operator/Courses|Activities|Bookings|Tests` 页面（复用现有 `pineAdmin.jsx` 的 `useOps` hook 模式 + 原子组件），调上述端点。

### 4.3 算力调度与用户管理（要求 2）

**算力服务接入**（后端新增 `compute_client.py`，照抄 `server_client.py` 的 httpx 转发模式；**new-api 仅作引擎被消费，管理/页面全部自研**）：
- **平台管理 token**：算力服务持有 new-api 管理令牌，作为统一入口（仅程序化调用，不暴露其管理 UI）。
- **建号发 token**：用户开通算力时 → `POST /api/user` 建 new-api 用户（`username = 云超服 uid`）+ `POST /api/token` 签发 PAT，映射存 `compute_accounts`。
- **额度增减（服务端统一，无用户充值）**：运营端 `POST /admin/compute/orders`（add/deduct/freeze）→ 算力服务调 new-api 调整额度 → 写 `compute_orders` 流水 → 通知用户。**当前不暴露任何用户充值接口**；架构上预留 `POST /api/user/topup` 转发能力（`new-api` 已支持），待支付渠道/合规就绪再启用。
- **用户读端**：`GET /opc/compute` 聚合返回 { 余额（`/api/user/self`）、本月消耗（`/api/data/self`）、流水（`/api/log/self`）}，30s 缓存 + 消耗预警。
- **Agent 算力**：桌面端 `PROVIDER_PINEAGENTS.base_url` 指向算力引擎 `/v1`（环境变量化），登录/换身份时算力服务下发该用户 PAT 注入 provider（`require_api_key=False` 改为用户级 token）。

**用户管理**：运营端 `POST /admin/users`（已有）+ 扩展「开通算力/分配端口/发放公益额度」一体化流程。

![算力额度管控流程](figures/03-compute.svg)

### 4.4 多端数据互通（要求 3）

统一后端 + 统一身份后，六端天然互通。前端统一契约：
- 核心服务端补全 Pydantic 模型 → `openapi.json` → 生成 TS client（小程序 / web业务 / web官网 / admin管理平台 / 智能体桌面 / 大屏共用）。
- 双端 `API_BASE` 收敛为构建期注入的单一配置。
- 数据一致性：报名/测评/算力/政策结果以 `user_id` 为键，多端读写同一后端。

---

## 五、用户端功能全集（要求 4）

> 全部落在 OPC 端口（`rbac_opc` 扩展）+ 关联端口协作。前端：console `Opc/` 页面（主）+ 小程序/Web 复用同一组 API。

| 功能 | 核心服务端端点 | 数据/引擎 | 交互要点 |
|------|--------------|----------|---------|
| **算力管理** | `GET /opc/compute`、`GET /opc/compute/usage`、`GET /opc/compute/orders` | `compute_client` → new-api | 只读余额/消耗/流水；额度不足引导联系运营；**无充值** |
| **园区入驻** | `POST /opc/park-admission`、`GET /opc/park-admission` | `park_admissions` | 提交入驻申请 → 载体 `POST /carrier/admissions/{id}/approve` → 签约（复用 contracts）→ settled |
| **智能体** | `GET /opc/agent`（已有）、`POST /opc/agent/{id}/chat` | agent-desktop（智能体桌面）（算力走 new-api）+ `agents` 表 | 一键唤起本机/云端 Agent，消耗计入本用户算力 |
| **政策管理** | `GET /opc/policy`（已有）、`POST /opc/policy/{id}/match`、`POST /opc/policy/{id}/apply` | `content_items`(policy) + 匹配引擎（迁自 `policy_engine.py`）+ `policy_applications` | 政策匹配 → 申报 → 政务三级审批（复用现 subsidy 链路） |
| **财务管理** | `GET /opc/finance`、`POST /opc/finance/record`（已有）、`GET /opc/invoices` | `finance_records` + `invoices` | OPC 收支 + 发票申请 |
| **工商注册/代办** | `GET /opc/affairs`（改造）、`POST /opc/business/{service}/apply`、`GET /opc/business-orders` | `business_services/business_orders` | OPC 提交代办 → 服务商 `GET/POST /provider/business-orders` 接单办结 |
| **课程/测评** | `GET /opc/courses`、`POST /opc/courses/{id}/enroll`、`GET/POST /opc/tests/{id}`、`POST /opc/tests/{id}/submit` | `courses/tests/test_results` | 培训报名 + 测评，结果入 `test_results` 可二次查看 |

**新增 `rbac_opc` 端点清单**（增量）：
`/opc/courses`、`/opc/courses/{id}`、`/opc/courses/{id}/enroll`、`/opc/activities`、`/opc/activities/{id}`、`/opc/activities/{id}/signup`、`/opc/bookings`（我的报名）、`/opc/tests/{id}`、`/opc/tests/{id}/submit`、`/opc/compute`、`/opc/compute/usage`、`/opc/compute/orders`、`/opc/park-admission`、`/opc/business/{service}/apply`、`/opc/business-orders`、`/opc/policy/{id}/match`、`/opc/policy/{id}/apply`、`/opc/invoices`。

**新增权限码**（seed.py）：`action:course.manage`、`action:activity.manage`、`action:enrollment.manage`、`action:test.manage`、`action:compute.manage`、`action:admission.manage`、`action:business.manage`、`action:park.manage` → 挂到 `operator|op_super_admin`/`op_admin`/`op_customer_service`；用户侧 `opc_member` 只读/申请权限。

---

## 六、园区端智慧大屏（要求 5、6）

> **新定位**：dpm 是**多园区通用**的大屏客户端（一套 Tauri + React 代码，任何园区部署即用）。**园区账号（carrier 端口身份）登录后，只显示本园区的内容**——园区信息 / 企业 / 人员 / 活动 / 媒体轮播 / 真实 token 消耗与流水，全部按 `org_id` 隔离。

### 6.1 现状缺口（已核实）
dpm 现为"单园区固定大屏"：数据 100% 来自 `sim_engine.py` 静态常量 + TOKEN 测算演示（`random` 波动）；无数据库、无登录、无外部系统对接；`/admin` 只能管本机媒体/播放列表，不能改园区数据；`/wall` 企业墙是前端硬编码静态数组。**实现"多园区通用 + 真实数据"需三步改造：多租户数据维度 → 园区账号登录 → 真实数据源接入。**

### 6.2 多园区数据维度（org_id 隔离）
- **每个园区 = 核心服务端一个 `organizations(type=carrier)`**（园区即载体）。园区数据域 `park_org`/`park_companies`/`park_members`、活动、报名、播放列表、算力聚合**全部以 `org_id` 隔离**。
- 核心服务端 `GET /api/park/*` 用 carrier 身份 + `org_id` 数据范围只返回本园区数据（复用现有范围机制 `require_port(carrier)` + `visible_region_ids/org 范围`），跨园区越权一律 403。
- 新增表：`park_org(org_id PK)`、`park_companies(org_id, …)`、`park_members(org_id, …)`、`park_playlists(org_id, …)`（媒体轮播内容归园区）。

### 6.3 园区账号登录（统一身份）
- **园区账号 = 核心服务端 carrier 端口身份**（可含 `park_admin` 子角色）。dpm 大屏（Tauri 壳内）提供登录入口：`POST /auth/login` + `select-identity` → 取 carrier 身份 token → 绑定该园区。
- token 由 dpm 后端安全存储（复用 agent-desktop（智能体桌面） `auth_token_store` 思路），启动时校验并拉取本园区数据；失效自动跳登录。
- **一套 dpm 代码，换园区即换账号**——"所有园区通用，园区账号登录后显示园区自己的内容"。

### 6.4 园区数据管理（要求 5）
- 核心服务端扩展园区数据域端点：`GET/POST/PUT /admin/park`、`/admin/park/companies`、`/admin/park/members`。
  - **运营端（operator）**：可管理所有园区；
  - **载体端（carrier）**：只能维护本园区数据（`org_id` 范围）——"后端园区端实现数据的更换"落地。
- 数据来源：`materials/园区数据资料/` 定稿数据按园区导入 `park_*` 表（不再硬编码）。

### 6.5 大屏真实数据（要求 6）
dpm 后端新增数据源层，以**园区账号 token** 拉取**本园区**数据（替代 `sim_engine` 模拟部分）：

| 大屏维度 | 数据源 | 接口（org_id 过滤） |
|---------|--------|------|
| 园区概况/企业/人员 | 核心服务端 | `GET /api/park/data`（园区信息 + 企业 + 人员 + 入驻统计） |
| **真实 token 消耗/流水** | **new-api** | 本园区用户经 `compute_client` 聚合 `/api/log`（按 org 分组），实时 2.2s tick + MQTT `opc/dashboard/tick` |
| 实时智能体消耗 | 核心 + new-api | `GET /api/park/agents/usage`（本园区人员 × 智能体 × token 聚合） |
| 活动/报名/测评统计 | 核心服务端 | `GET /api/park/biz`（本园区活动/报名/测评） |
| 媒体轮播 | dpm 自身 | `park_playlists`（本园区播放列表） |

**改造要点**：
- `dpm/backend/app/` 新增 `data_source.py`：带园区 token 轮询核心服务端聚合端点 + 算力聚合，内存缓存，tick 推进；`sim_engine.py` 删除随机模拟 token，只保留通用布局骨架。
- 新增 REST：`GET /api/agents/usage`、`GET /api/park/real`；前端 `useParkSim` 接入真实快照。
- `/wall` 企业墙改为 `GET /api/park/companies`（本园区，不再硬编码）。
- 实时链路：沿用 REST 轮询(2.2s) + MQTT `opc/dashboard/tick` + SSE 兜底；token 流水经核心代取（避免 dpm 直连 new-api 凭据扩散）。

### 6.6 大屏页面增强
`DataScreen` 增加「人员在线/智能体运行中/实时 token 消耗/分企业 token 排行/今日流水」区块；`DigitalTwin` 3D 右侧面板绑定本园区真实企业/人员数据；`/twin`、`/screen`、`/wall` 数据全部走后端且按园区隔离。

![园区大屏真实数据流](figures/04-park-screen.svg)

---

## 七、数据模型总表（核心服务端目标态）

**身份域**（已有）：users、user_identities、roles、permissions、role_permissions、regions、sessions、audit_logs、organizations、organization_members
**Agent/生态**（已有）：agents、opc_profiles、tasks、bids、escrows、contracts、disputes、ratings、notifications、messages、opc_tasks、service_providers、service_referrals、roadshows、roadshow_registrations、investment_intents、investor_preferences、training_enrollments
**内容/政务**（已有）：content_items、system_configs、portal_dashboards、portal_pages、subsidy_applications
**新增业务域**：courses、activities、bookings、tests、test_results、compute_accounts、compute_orders、park_admissions、business_services、business_orders、invoices、finance_accounts、policy_applications、park_org、park_companies、park_members
**外部数据（不落核心库）**：new-api 用户/token/日志（经 compute_client 访问）、PineAgents 会话/记忆（本地）、dpm 播放列表/设置（本地 data.json）

> 迁移对照：training `events→activities`、`bookings→bookings`、`tests/policy_logs/plan_logs/survey_logs→tests/test_results`、`policy_data→content_items+policy_applications`。

---

## 八、统一契约与跨服务接口

### 8.1 契约机制（OpenAPI 生成，消灭手写漂移）

- **单一事实源**：核心服务、算力服务全部 router 用 Pydantic 请求/响应模型，自动产出 `openapi.json`。
- **聚合与生成**：gateway 汇总各服务 OpenAPI → 生成 TS client（小程序 / web业务 / web官网 / admin管理平台 / 智能体桌面 / 大屏共用）；接口语义化版本 `/api/v1`。
- **契约治理**：CI 加「契约变更 → 重新生成 → diff」检查，双端锁版本；破坏性变更走新版本而非原地修改。

### 8.2 服务间接口矩阵

| 调用方 | 被调方 | 接口 | 协议 / 鉴权 |
|--------|--------|------|-------------|
| 小程序 / web业务 / web官网 / admin管理平台 | gateway | `/api/v1/*` | HTTPS · Bearer 用户 token |
| 大屏桌面（dpm） | gateway | `/api/park/*` | HTTPS · 园区账号 token（org_id 只返回本园区） |
| 智能体桌面应用 | gateway | `/auth/*` `/agents/*` | HTTPS · 用户 token |
| gateway | 核心服务 | `/auth` `/opc` `/admin` `/agent` 等 | 内网 HTTP · 服务账号 token + 透传用户身份 |
| gateway | 算力服务 | `/compute/*` | 内网 HTTP · 服务账号 token |
| 核心服务 | 算力服务 | `/compute/*`（额度/聚合） | 内网 · 服务账号 |
| 算力服务 | 算力引擎（new-api） | `/v1/*` + `/api/*`（管理） | **loopback** · 管理令牌（程序化） |
| 智能体桌面应用 | 算力引擎（经算力服务代理） | `/v1/*`（模型调用） | loopback 代理 · 用户 PAT |
| 核心服务 | MQTT 消息服务 | 主题发布/订阅 | 内网 · MQTT 凭据 |
| 核心服务 | 缓存服务 | key 操作 | 内网 · 密码 |
| 核心服务 | 数据库服务 | SQL | 内网 · DSN |

### 8.3 鉴权分层

| 层 | 凭据 | 范围 |
|----|------|------|
| 用户层 | 六端统一 `Authorization: Bearer <用户token>` | gateway 校验，按身份/端口 |
| 服务层 | 服务账号 token（环境变量注入，不硬编码） | 服务间调用，按服务/权限 scope 隔离 |
| 数据层 | org_id / region 数据范围（已有机制） | 园区/政务数据越权 403 |

- **算力接口**：算力服务 ↔ new-api 走管理 API（建号/发 token/额度调整/日志）；`compute_client.py` 统一封装，含超时/重试/502 兜底（照 `server_client.py`）。引擎与服务群同机部署，loopback 互通。
- **大屏数据**：`dpm → 核心 /api/park/*` 经核心代取 new-api 日志（避免 dpm 直连 new-api 凭据扩散）。

### 8.4 实时通道

| 通道 | 用途 | 出口 |
|------|------|------|
| MQTT（EMQX） | 大屏/桌面实时数据、控制指令、通知 | 经 gateway WS 出口，内网不直接暴露 |
| SSE | 大屏快照回退（现 dpm 已有） | gateway |
| WebSocket | 桌面 Agent 会话、语音 | gateway |

### 8.5 通知/消息

业务事件（额度到账 / 入驻审核 / 报名结果 / 测评完成）统一走 `notifications`（现缺写入端点，补 `notifications.create` service），支持站内信 + 可接 `bark-notify` 手机推送。

---

## 九、迁移与演进路线

| 阶段 | 内容 | 退出条件 | 涉及 |
|------|------|---------|------|
| **0 · 基座** | 后端补 Pydantic 模型 + OpenAPI；`compute_client` 打通 new-api；users 补 wx_openid + 手机号/微信登录端点 | 六端能连后端登录 | server-core、new-api |
| **1 · 身份统一** | training accounts 迁移 → users/opc_profiles；六端登录全部走后端；小程序/Web 改 `API_BASE` | 同一账号六端互通 | training web/miniprogram、server-core |
| **2 · 业务域迁移** | courses/activities/bookings/tests 建表 + rbac_operator 端点 + 数据迁移；web platform 管理迁入 console 运营端 | 运营端可完整管理课程/活动/报名/测评 | server-core、console、training website |
| **3 · 用户端补全** | 算力管理/园区入驻/政策申报/财务/工商代办 + `rbac_opc` 端点 + console `Opc/*` 页面 | OPC 用户端六功能可用 | server-core、console |
| **4 · 园区大屏** | dpm 多租户化（园区账号登录 + org_id 隔离）；data_source 接核心+new-api，替换 sim_engine 模拟；园区数据管理页 | 大屏真实人员 + 实时 token/流水 | dpm、server-core |
| **5 · 收尾** | 退役 training `server`、`website/server` mock、`website/platform`；README/文档同步 | 单后端 + 四前端稳定运行 | 全仓 |

> 每阶段独立可交付、可回滚；阶段 1 后数据即以 `user_id` 归位，阶段 2 后运营单入口。

![迁移与演进路线](figures/05-migration.svg)

---

## 十、风险与依赖

1. **合规**：向公众提供生成式 AI 的备案/内容安全/实名/日志留存义务（new-api README 有明确提示）；算力额度发放涉及收费边界，需政策/法务确认。参考 `materials/搜集资料/政策汇总.md`。
2. **迁移期双写**：阶段 1-2 需 training server 与核心服务端双写/一次性迁移脚本，避免丢数据；测评引擎移植需同一组测试用例双端验证（沿用 `小程序同步约束.md` 思路）。
3. **new-api 自研依赖**：new-api 是 AGPLv3 开源（One API 的 fork），需确认许可合规与自研维护成本；额度调整用其管理 API，锁定版本。
4. **桌面端离线/断网**：**不做本地推理**，Agent 算力完全依赖云端（new-api → 云厂商渠道）；断网或云厂商不可用时智能体不可用，需明确降级提示、超时与重试策略。
5. **性能**：核心服务端承载全业务，SQLite 在并发大时需评估；大屏 2.2s 轮询建议走独立只读副本或缓存（现有 dpm tick 机制可承担）。
6. **品牌未接线**：PineAgents console 品牌常量未消费（storage key 仍 qwenpaw_*），统一后需一并收敛。

---

## 十一、部署拓扑（服务群编排）

![服务群部署拓扑](figures/06-deployment.svg)

### 11.1 端口清单

| 服务 | 端口 | 暴露范围 | 说明 |
|------|------|---------|------|
| gateway 网关 | `:443`（HTTPS）/ `:80` | 公网 | TLS 终结、统一入口；WS/WSS 供大屏/桌面 |
| 核心服务 | `:8090` | 内网 | 身份 + 业务域 + 园区聚合 |
| 算力服务 | `:8092` | 内网 | 额度/令牌/流水聚合，封装 new-api |
| 算力引擎 new-api | `:3000` | **仅内网 loopback** | 仅服务（relay /v1 + 管理 API），无页面暴露 |
| MQTT 消息服务 | `:1883` / `:8083`(WS) | 内网（大屏/桌面经网关 WS） | EMQX，实时消息/指令/推送 |
| 缓存服务 | `:6379` | 内网 | Redis，会话/限流/聚合缓存 |
| 数据库服务 | `:3306`（MySQL/PG）或 SQLite 文件 | 内网 | 模块化单体用 SQLite；微服务演进用 MySQL/PostgreSQL 分库 |

### 11.2 依赖与启动顺序

```
数据库 / Redis / EMQX  ──→  核心服务 + 算力服务  ──→  算力引擎 new-api  ──→  gateway 网关
（先起基础设施）            （业务就绪）           （消费其服务）           （最后对外）
```

- 算力引擎随后端一起部署（同一 Docker Compose），算力服务经 loopback `:3000` 调用，无跨网凭据扩散。
- 大屏/桌面端的实时通道（MQTT / SSE / WS）统一经 gateway 出口，内网不直接暴露 EMQX / new-api。

### 11.3 存储与卷

| 数据 | 存放 | 备份策略 |
|------|------|---------|
| 业务库（身份/业务/园区/算力流水） | SQLite `data/app.db` → MySQL/PG | 定时快照 + WAL |
| 缓存/会话 | Redis | 可重建，无需备份 |
| 文件/媒体（上传、大屏播放列表） | `uploads/` + `park_playlists` | 对象存储或卷备份 |
| new-api 数据（引擎侧） | 卷挂载 `/data` | 随服务群备份 |

### 11.4 网络与安全

- 公网仅暴露 gateway；EMQX / Redis / DB / new-api 全部内网，凭据不扩散。
- 服务间调用用服务账号 token（环境变量注入），算力服务 → new-api 用其管理令牌（仅程序化）。
- 出站仅算力引擎需要访问云厂商 API；其余服务禁出站（或白名单）。

---

## 十二、当前 code 各项目如何工作

> 每个子项目均为独立仓库（组织 Pine），位于 `code/`。以下为职责 / 关键文件 / 启动命令 / 工作流。

### 12.1 `server-core` — 核心服务端（总后端）
- **职责**：身份/平台 API + 培训子应用，对外统一 `opc.pinesound.cn`。
- **关键文件**：`dispatcher.py`（统一入口，按路径路由 `/api/*`→培训子应用、其余→平台应用）、`app/main.py`（身份 + 业务域）、`app/training/`（培训子应用，独立库 `data/opc.db`）、`app/routers/`（auth/opc/admin/government…）。
- **启动**：`cd code/server-core && uv run uvicorn dispatcher:app --host 0.0.0.0 --port 8090 --reload`
- **工作流**：前端请求 → dispatcher → `/api/*` 走培训子应用（报名/测评/政策），`/auth` `/opc` `/admin` 走平台应用（七端口 RBAC / 业务域）。

### 12.2 `compute-engine` — 算力引擎（new-api 微服务）
- **职责**：OpenAI 兼容 `/v1` 模型中继 + 额度/令牌/token 流水；**仅服务，管理/页面自研**。
- **关键文件**：`main.go`（入口）、`relay/`（模型中继）、`controller/`（管理 API）、`docker-compose.yml`；启动说明见 `README.云超服.md`。
- **启动**：`cd code/compute-engine && cp .env.example .env && docker compose up -d`
- **工作流**：智能体/算力服务经 loopback `:3000` 调用 `/v1/*`（模型）与 `/api/*`（管理，程序化）；引擎代理云厂商渠道（OpenAI/DeepSeek/通义千问/Claude/Gemini），不做本地推理。

### 12.3 `agent-desktop` — 智能体桌面应用（PineAgents）
- **职责**：智能体工作台（Agent OS）：对话、Skills/插件、定时任务、代码模式、多频道。
- **关键文件**：`src/pineagents/`（Python 后端运行时：agents/runtime/governance/sandbox/memory）、`console/`（React 前端）、`console/src-tauri/`（Tauri 壳）、`src/pineagents/app/routers/auth.py`（认证转发到 server-core）。
- **启动**：`cd code/agent-desktop/console && yarn dev`；后端 `pineagents app`（:8088）。
- **工作流**：用户从 console / CLI / 频道发消息 → 后端运行时编排 → 智能体决策（ReAct）→ 工具执行（治理/沙箱）→ 模型调用经 **compute-engine** `/v1` 计量。

### 12.4 `park-desktop` — 园区大屏桌面应用（dpm）
- **职责**：多园区通用大屏：数据大屏、数字孪生、AI/语音助手、媒体轮播、企业墙；园区账号登录只显示本园区。
- **关键文件**：`src/`（React 前端，路由 / /twin /ai /screen /voice /wall）、`src-tauri/`（桌面壳）、`backend/`（FastAPI :10085 + MQTT + sim_engine）、`app/data_source.py`（规划：接核心服务端 + 算力引擎真实数据）。
- **启动**：`cd code/park-desktop && yarn dev`；后端 `cd backend && uv run python main.py`（:10085）。
- **工作流**：大屏经 REST/MQTT/SSE 拉快照 → 园区账号登录（carrier 身份，org_id 隔离）→ 只展示本园区数据；真实 token 消耗经 server-core 代取 compute-engine。

### 12.5 `web-official` — 官网展示端（PineAgentsWeb）
- **职责**：公开展示站（产品/政策/招生/案例），静态 SPA。
- **关键文件**：`src/`（Vite + React）、`vite.config.ts`、`package.json`。
- **启动**：`cd code/web-official && pnpm install && pnpm run dev`
- **工作流**：纯展示，公开接口 + 静态内容；可选登录走后端。

### 12.6 `training` — 培训前端（小程序 + 网站）
- **职责**：C 端培训业务（课程/活动/报名/测评/政策/算力），后端已并入 server-core 培训子应用。
- **关键文件**：`miniprogram/`（Taro 小程序）、`website/`（Vite React，`src/user/` C 端）；`API_BASE = https://opc.pinesound.cn`。
- **启动**：`cd code/training/miniprogram && yarn dev:weapp`；`cd code/training/website && pnpm dev`
- **工作流**：小程序/网站调 `opc.pinesound.cn/api/*` → server-core dispatcher → 培训子应用（报名/测评/政策/算力）；与 server-core 身份互认（统一身份）。

### 12.7 临时项目（不入库）
- `code/bark-notify/`：临时测试的 Bark 推送工具，与云超服无关，不纳入项目范围。

---

## 十三、server-core 分层架构与算力通信规范

### 13.1 FastAPI 四层架构（单向依赖）

| 层 | 职责 | server-core 目录（规划） |
|----|------|------------------------|
| **接口层** | 接收请求、返回响应、参数校验、路由 | `app/routers/` + `app/schemas/`（Pydantic） |
| **业务层** | 业务逻辑编排、用例（用领域对象实现用例） | `app/services/` |
| **领域层** | 核心业务模型与规则（实体 / 值对象 / 领域服务） | `app/domain/` |
| **基础设施层**（含数据模型层） | 数据库访问、缓存、消息队列、外部服务适配 | `app/infrastructure/`（`repositories/`、`models/`、`cache/`、`mq/`） |

**依赖方向（单向，禁止反向依赖）**：
```
接口层 → 业务层 → 领域层
  ↘        ↘        ↘
    基础设施层（数据模型 / DB / 缓存 / MQ / 外部服务）
```
- 接口层只做「收请求 → 调业务层 → 返回响应」；业务层不依赖接口层。
- 领域层是核心模型与规则，**不依赖**业务层 / 接口层 / 基础设施层的具体实现（只面向其接口）。
- 基础设施层实现接口，**不得反向依赖**上层。

**全异步**：接口层 `async def` → 业务层 async → 仓储 async（SQLAlchemy async），事件循环内杜绝阻塞调用；外部 HTTP 用 `httpx.AsyncClient`。见 13.4。

### 13.2 算力通信规范

- **内部**：FastAPI（server-core）与**算力调度服务**（compute-engine / 算力引擎）经**内部 IP / loopback** 交互（`http://127.0.0.1:3000`），不经过公网。
- **对外**：前端 / 用户的算力调用统一走**服务端 `/api/v1`**（server-core 统一入口），**不直连**算力引擎。
- 算力引擎（new-api）仅作服务被消费，无页面暴露；额度 / 令牌 / 流水由服务端算力服务程序化管理（见 §4.3）。

### 13.3 参考工程化：PineSoundServer

server-core 的工程化（数据目录 / 容器启动 / 运维脚本）参考 `C:\Users\Administrator\MyCode\PineSoundServer`：
- **`serverdata/`**：数据目录规范（`logs/ data/ files/ keys/ prompts/` + 各中间件数据 `emqx-data/ redis-data/ minio/ milvus/`）。
- **`serverrun/`**：容器与微服务启动（`start-all.sh` 编排、各服务 `docker-compose.yml`、`envcopy.sh` 配置加密、`encrypt-certs.sh` 证书加密）。
- **`ops/`**：运维脚本（`init_admin` / `db_backup` / 数据迁移 / `clear_redis_tokens` / 算力套餐与分区初始化等）。

### 13.4 异步与并发（设计之初即考虑）

**全异步调用链**：接口层 `async def` → 业务层 async → 仓储 async（SQLAlchemy async）。事件循环内**杜绝阻塞**（不用 `time.sleep` / 同步 IO；外部调用统一 `httpx.AsyncClient` 带超时 / 重试 / 熔断）。

| 服务 | 异步方案 | 要点 |
|------|---------|------|
| **MySQL** | SQLAlchemy 2.0 `create_async_engine` + async session（`asyncmy` / `aiomysql`） | 连接池（`pool_size` / `max_overflow` / `pool_pre_ping`）；**每请求独立 async session**（`async with` 管事务边界）；开发环境 `aiosqlite` |
| **Redis** | `redis.asyncio` | 会话 / 缓存 / 限流 / **分布式锁**（`SET NX EX`）；连接池 |
| **OSS 对象存储** | 异步封装（阿里云 OSS / MinIO，`aioboto3` 或 oss2 线程池包装） | 上传异步、断点续传、回调通知，不阻塞请求线程 |

**并发正确性**：
- 写操作（抢单 / 扣款 / 报名 / 领券）用**行锁**（`SELECT ... FOR UPDATE`）+ 幂等键，防并发重复。
- 乐观锁（`version` 字段）处理并发更新冲突。
- 事务边界清晰：多表写（如 `_adopt_phone`、结算 + 佣金）包在一个事务内。
- 外部依赖（算力引擎 / 云厂商）异步调用 + 超时重试，失败可降级。

---

## 附：与既有设计文档的关系

- 本设计是「`三端架构设计.md`（培训三端）」与「`身份体系与端口权限设计方案.md`（云超服七端口）」的**合一演进**：培训业务并入云超服端口体系。
- `云超服平台全量方案设计.md` 的六端口管理功能，本设计以「已实现（RBAC/任务/内容/补贴）+ 本次新增（课程/活动/报名/测评/算力/入驻/财务/工商/园区）」两栏承接。
- 大屏升级以 `code/park-desktop/backend/README.md` 为权威基线，本设计只描述数据源与对接改造。