# 通用AI工作台底座平台 — 需求文档

> 文档编号：REQ-COMMONSP-001
> 版本：v2.0.0
> 日期：2026-03-14
> 状态：单租户优先架构
> 项目缩写：COMMONSP（Commons Platform）

---

## 1. 引言

### 1.1 背景

nomifun-tauri 是目前已有的通用AI工作台底座，采用 Rust(axum) + Vue 前端架构，本地优先（SQLite）+ 插件驱动。核心能力包括 Agent Engine、Skills System、Knowledge RAG、MCP Gateway、Channels Bus。

现有系统是**单租户单用户**架构，需要演进为**单租户优先 + 可扩展租户模型**平台，支持政府/企业/教育三大领域定制，即 PrivBox-AIStation 软硬一体化产品的软件核心。

**架构决策**：PrivBox 典型部署场景为单台设备私有化部署（医院/学校/企业），物理隔离已满足数据安全需求。因此 Phase 1 采用**单租户优先**模式，保留租户抽象作为扩展点，未来需要多租户 SaaS 时改动最小。

本文档定义 **Phase 1 MVP** 的完整需求，目标是建立单租户定制框架（主题/领域/品牌）、多用户管理体系、审计日志能力，为后续三大领域包奠定底座。

### 1.2 范围

| 范围 | 说明 |
|------|------|
| **本文档** | Phase 1 MVP 软件系统需求 |
| **不包括** | 硬件适配（PrivBox HAL）、领域包开发（GovPack/EntPack/EduPack）、插件市场 |
| **技术栈** | Rust(axum) + Vue + SQLite/sqlx（复用 nomifun-tauri 技术栈） |

### 1.3 与现有 nomifun-tauri 的关系

```
nomifun-tauri (当前)
    │
    │  Phase 1: 单租户优先 + 主题引擎 + 领域框架 + 多用户
    ▼
nomifun-tauri (演进后) = Commons Platform v1.0
    │  - 默认单租户，数据天然隔离
    │  - 保留 tenant_id 字段，未来扩展多租户成本低
    │
    │  Phase 2: 三大领域包
    ▼
PrivBox-AIStation 软件层
```

### 1.4 架构决策

| 决策项 | 选择 | 理由 |
|--------|------|------|
| 租户隔离策略 | 无需激活 | 单机部署物理隔离已满足需求 |
| 数据层 tenant_id | 保留字段 | 未来扩展多租户 SaaS 成本最低 |
| 默认租户 | 自动创建 | 首次启动自动初始化，无需手动注册 |
| 租户配置 | 保留 | 用于单租户的品牌定制、主题切换 |

---

## 2. 术语表

| 术语 | 英文 | 定义 |
|------|------|------|
| **租户配置** | Tenant Config | 单租户场景下的全局配置，包含品牌、主题、功能开关 |
| **主题** | Theme | 视觉定制包，包含配色、Logo、品牌元素 |
| **领域** | Domain | 行业分类（Government/Enterprise/Education/Custom） |
| **领域配置** | Domain Config | 领域特定的初始化参数、分类体系、模板 |
| **技能包** | Skill Pack | 一组相关技能的集合，可按领域打包 |
| **知识库模板** | Knowledge Template | 领域特定的知识库分类和初始数据 |
| **RBAC** | Role-Based Access Control | 基于角色的访问控制 |
| **审计日志** | Audit Log | 记录所有敏感操作的不可篡改日志 |

---

## 3. 角色定义

| 角色 | 说明 | 权限范围 |
|------|------|---------|
| **系统管理员** | 安装部署后的初始管理员 | 所有配置、用户管理、功能开关 |
| **普通用户** | 终端用户 | 使用 AI 对话、技能、知识库等业务功能 |

> **说明**：单租户模式下，"租户管理员"等价于"系统管理员"。保留"系统管理员"角色，未来扩展多租户时再区分"系统管理员"和"租户管理员"。

---

## 4. 功能性需求

### 4.1 租户系统（单租户优先）

#### FR-TENANT-001：默认租户自动初始化
- WHEN 首次启动系统，THEN 系统 SHALL 自动创建默认租户配置
- WHEN 初始化时，THEN 用户 SHALL 提供组织名称、选择领域类型（Government/Enterprise/Education/Custom）
- WHEN 初始化完成后，THEN 系统 SHALL 自动应用对应的预设主题和领域配置

#### FR-TENANT-002：租户配置（系统配置）
- WHEN 系统管理员访问配置页，THEN 系统 SHALL 展示并允许修改：组织名称、品牌定制、功能开关、数据策略
- WHEN 功能开关变更时，THEN 系统 SHALL 实时生效，无需重启
- **说明**：单租户模式下，所有配置直接生效，无需租户上下文路由

#### FR-TENANT-003：数据迁移与备份
- WHEN 系统管理员触发数据备份，THEN 系统 SHALL 导出全部数据（SQLite schema + 文件存储）
- WHEN 导入备份时，THEN 系统 SHALL 验证数据完整性并重建

#### FR-TENANT-004：多租户扩展点（预留）
- WHEN 未来需要支持多租户 SaaS，THEN 系统 SHALL 可通过 tenant_id 字段实现数据隔离
- **说明**：Phase 1 所有表保留 tenant_id 字段，但默认不激活隔离逻辑

### 4.2 主题引擎

#### FR-THEME-001：动态主题切换
- WHEN 系统管理员切换主题，THEN 系统 SHALL 在 100ms 内完成切换，前端无需刷新
- WHEN 用户访问工作台时，THEN 系统 SHALL 自动应用当前配置的主题

#### FR-THEME-002：预设主题包
- WHEN 选择预设主题，THEN 系统 SHALL 支持以下主题：
  - **政务蓝主题**：GovAI 政务配色体系
  - **企业专业主题**：商务蓝色调
  - **学术清新主题**：简洁学术风格
- WHEN 主题包含 Logo 定制，THEN 系统 SHALL 支持上传 PNG/SVG 格式

#### FR-THEME-003：主题预览
- WHEN 系统管理员在主题编辑器中修改，THEN 系统 SHALL 提供实时预览
- WHEN 预览满意后，THEN 管理员 SHALL 一键发布生效

### 4.3 领域框架

#### FR-DOMAIN-001：领域配置 Schema
- WHEN 初始化系统时，THEN 系统 SHALL 根据选择的领域类型加载对应的领域配置 Schema
- WHEN 领域配置包含分类体系时，THEN 系统 SHALL 自动创建对应的知识库分类和应用模板入口

#### FR-DOMAIN-002：领域初始化向导
- WHEN 首次配置系统，THEN 系统 SHALL 提供领域初始化向导，引导配置：
  - 部门/科室设置（如适用）
  - 知识库分类初始化
  - 预置技能包选择

#### FR-DOMAIN-003：领域特定技能包注册
- WHEN 安装领域技能包时，THEN 系统 SHALL 自动注册到该领域的技能目录
- WHEN 技能包与领域不兼容时，THEN 系统 SHALL 提示警告但不阻止安装

### 4.4 多用户认证与权限

#### FR-AUTH-001：用户注册与登录
- WHEN 新用户注册时，THEN 系统 SHALL 支持用户名+密码方式
- WHEN 用户登录时，THEN 系统 SHALL 使用现有的 JWT 认证机制
- WHEN 登录失败时，THEN 系统 SHALL 返回错误信息，不泄露账户是否存在

#### FR-AUTH-002：角色权限模型（RBAC）
- WHEN 系统管理员创建用户时，THEN 系统 SHALL 支持分配角色（普通用户/系统管理员）
- WHEN 普通用户访问管理员功能时，THEN 系统 SHALL 返回 403 权限不足
- WHEN 角色权限变更时，THEN 系统 SHALL 实时生效

#### FR-AUTH-003：会话管理
- WHEN 用户登录后，THEN 系统 SHALL 生成带刷新令牌的 JWT
- WHEN JWT 过期时，THEN 系统 SHALL 支持静默刷新
- WHEN 用户登出时，THEN 系统 SHALL 使 refresh token 失效

### 4.5 审计日志

#### FR-AUDIT-001：操作审计记录
- WHEN 用户执行以下操作时，THEN 系统 SHALL 记录审计日志：
  - 用户登录/登出
  - 系统配置变更
  - 用户创建/删除/权限变更
  - 知识库上传/删除
  - 敏感技能包安装/卸载
- WHEN 记录审计日志时，THEN 系统 SHALL 包含：操作时间、操作用户、操作类型、操作对象、操作结果、来源IP

#### FR-AUDIT-002：审计日志查询
- WHEN 系统管理员访问审计日志页，THEN 系统 SHALL 支持按时间范围、操作类型、用户筛选
- WHEN 导出审计日志时，THEN 系统 SHALL 支持 CSV 格式导出

#### FR-AUDIT-003：审计日志不可篡改
- WHEN 审计日志写入后，THEN 系统 SHALL 保证不可修改、不可删除
- WHEN 需要追加日志时，THEN 系统 SHALL 仅允许追加操作

### 4.6 配置导入导出

#### FR-CONFIG-001：配置导出
- WHEN 系统管理员触发配置导出，THEN 系统 SHALL 导出完整配置（不含敏感数据）
- WHEN 导出时，THEN 系统 SHALL 包含系统配置、用户列表、知识库索引、主题配置

#### FR-CONFIG-002：配置导入
- WHEN 管理员导入配置文件，THEN 系统 SHALL 验证配置合法性
- WHEN 配置导入时，THEN 系统 SHALL 支持合并或覆盖模式

---

## 5. 非功能性需求

### 5.1 性能

| 指标 | 目标值 |
|------|--------|
| 冷启动时间 | < 3s |
| 主题切换延迟 | < 100ms |
| 租户创建时间 | < 1min |
| 对话响应延迟 | < 500ms（不含模型推理） |

### 5.2 安全

| 需求 | 说明 |
|------|------|
| 数据隔离 | 单机部署物理隔离已满足，无需额外租户隔离 |
| 传输加密 | HTTPS/TLS 1.3（WebSocket + REST） |
| 存储加密 | SQLite 数据库加密（AES-256，可选） |
| 密钥管理 | JWT secret 独立存储，不硬编码 |

### 5.3 可用性

| 需求 | 说明 |
|------|------|
| 离线优先 | 网络中断时核心功能可用 |
| 错误恢复 | 异常操作自动回滚，不破坏数据完整性 |
| 日志诊断 | 完整的错误日志，便于问题定位 |

### 5.4 可扩展性

| 需求 | 说明 |
|------|------|
| 领域扩展 | 新增领域类型时，无需修改核心代码 |
| 插件集成 | 保持与现有 MCP 插件系统的兼容性 |
| 数据迁移 | 未来可平滑迁移到 PostgreSQL |

---

## 6. 关键约束与假设

### 6.1 约束

1. **复用 nomifun-tauri**：Phase 1 不重写现有模块，在现有架构上扩展单租户定制能力
2. **SQLite 本地优先**：继续使用 SQLite 作为主要数据存储，暂不引入 PostgreSQL
3. **前端改动最小化**：主题引擎优先通过 CSS 变量 + 动态加载实现，减少 Vue 组件改动
4. **不涉及硬件**：本文档不包含 PrivBox 硬件适配内容
5. **单租户优先**：不激活多租户隔离逻辑，简化开发和部署

### 6.2 假设

1. 假设 Phase 1 部署场景为单机私有化部署
2. 假设物理隔离已满足数据安全需求
3. 假设管理员可通过管理后台完成所有配置操作（无需命令行）
4. 假设审计日志存储在 SQLite 中

---

## 7. 数据模型（核心扩展）

### 7.1 新增数据模型

```rust
// 系统配置（单租户模式，单条记录）
struct SystemConfig {
    id: String,              // "default"
    org_name: String,         // 组织名称
    domain: DomainType,       // Government / Enterprise / Education / Custom
    created_at: TimestampMs,
    updated_at: TimestampMs,
}

// 品牌配置（单租户模式）
struct BrandingConfig {
    config_id: String,        // "default"
    logo_url: Option<String>,
    logo_svg: Option<String>, // SVG 内联
    primary_color: String,
    secondary_color: String,
    accent_color: String,
    theme_preset: ThemePreset,
}

// 功能开关（单租户模式）
struct FeatureFlags {
    config_id: String,
    app_store: bool,
    skill_market: bool,
    multi_user: bool,
    cloud_sync: bool,
}

// 领域配置
struct DomainConfig {
    id: i64,                  // 自增主键
    domain_type: DomainType,
    config_json: String,      // 领域特定配置的 JSON 序列化
    created_at: TimestampMs,
}

// 审计日志
struct AuditLog {
    id: i64,                 // 自增主键
    user_id: String,
    action: String,
    object_type: String,
    object_id: Option<String>,
    result: String,          // success / failure
    source_ip: Option<String>,
    extra: String,           // JSON 额外信息
    created_at: TimestampMs,
}

// 扩展：用户表新增角色
struct User {
    // ... 现有字段 ...
    role: UserRole,          // admin / user
}
```

### 7.2 现有模型扩展

| 现有表 | 扩展字段 | 说明 |
|--------|---------|------|
| `users` | `role` | 用户角色（保留 tenant_id 字段但不使用） |
| `conversations` | - | 保持不变（单租户无需隔离） |
| `messages` | - | 保持不变 |
| `knowledge_bases` | - | 保持不变 |
| `providers` | - | 保持不变 |
| `assistants` | - | 保持不变 |

### 7.3 多租户扩展点（预留）

> 以下字段保留以备未来扩展，Phase 1 不激活隔离逻辑

```rust
// 未来多租户场景下启用
struct FutureMultiTenant {
    tenant_id: String,       // 保留字段
}

// 所有表可选添加 tenant_id
ALTER TABLE users ADD COLUMN tenant_id TEXT;  -- 保留但默认填充 "default"
```

---

## 8. API 设计（核心接口）

### 8.1 系统配置

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/config` | GET | 获取系统配置（组织名、领域） |
| `/api/config` | PUT | 更新系统配置 |
| `/api/config/init` | POST | 初始化系统（首次启动） |
| `/api/config/backup` | POST | 触发数据备份 |
| `/api/config/restore` | POST | 导入备份 |

### 8.2 用户与认证

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/register` | POST | 用户注册 |
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/logout` | POST | 用户登出 |
| `/api/auth/refresh` | POST | 刷新 Token |
| `/api/users` | GET | 列出所有用户（管理员） |
| `/api/users` | POST | 创建用户（管理员） |
| `/api/users/{id}` | PUT | 更新用户（管理员） |
| `/api/users/{id}` | DELETE | 删除用户（管理员） |

### 8.3 主题与品牌配置

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/branding` | GET | 获取当前品牌配置 |
| `/api/branding` | PUT | 更新品牌配置 |
| `/api/branding/presets` | GET | 获取预设主题列表 |
| `/api/branding/preview` | POST | 预览主题 |

### 8.4 审计日志

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/audit-logs` | GET | 查询审计日志 |
| `/api/audit-logs/export` | GET | 导出审计日志（CSV） |

### 8.5 领域配置

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/domains` | GET | 获取当前领域配置 |
| `/api/domains/init` | POST | 领域初始化向导 |
| `/api/domains/skill-packs` | GET | 获取领域技能包列表 |

---

## 9. 前端改造要点

### 9.1 视图层新增

| 视图 | 说明 |
|------|------|
| 系统初始化向导 | 首次启动引导创建管理员、选择领域 |
| 用户管理 | 管理员管理系统内用户 |
| 品牌配置 | 可视化配置 Logo、主题配色 |
| 审计日志查看 | 筛选和导出审计日志 |
| 领域初始化向导 | 创建后引导配置部门/知识库/技能包 |

### 9.2 现有视图改造

| 视图 | 改造内容 |
|------|---------|
| 登录页 | 新增注册入口、首次启动引导 |
| 工作台 | 顶部栏根据品牌配置动态渲染 Logo/配色 |
| 设置页 | 新增系统配置、用户管理、品牌配置入口 |

### 9.3 CSS 变量主题方案

```css
/* 主题变量注入点（替换原有硬编码颜色） */
:root {
    --color-primary: var(--theme-primary, #1a56db);
    --color-secondary: var(--theme-secondary, #6b7280);
    --color-bg: var(--theme-bg, #ffffff);
    --color-surface: var(--theme-surface, #f9fafb);
    --color-text: var(--theme-text, #111827);
    --color-border: var(--theme-border, #e5e7eb);
    --logo-url: var(--theme-logo, url('/assets/default-logo.png'));
}

/* 动态切换 */
.theme-gov {
    --theme-primary: #1e3a8a;    /* 政务蓝 */
    --theme-bg: #f0f4f8;
    --theme-surface: #ffffff;
    --theme-text: #1a202c;
}

.theme-enterprise {
    --theme-primary: #2563eb;    /* 企业蓝 */
    --theme-bg: #f8fafc;
    --theme-surface: #ffffff;
    --theme-text: #0f172a;
}

.theme-academic {
    --theme-primary: #059669;    /* 学术绿 */
    --theme-bg: #fafaf9;
    --theme-surface: #f5f5f4;
    --theme-text: #1c1917;
}
```

---

## 10. 风险与依赖

### 10.1 技术风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 单租户限制 | 未来需要多租户时改动成本 | 保留 tenant_id 字段，隔离逻辑模块化 |
| SQLite 并发限制 | 多用户同时使用性能下降 | 监控慢查询，必要时迁移 PostgreSQL |
| 前端主题系统侵入性 | 改动范围过大 | 使用 CSS 变量 + 动态类名，避免大规模重构 |

### 10.2 依赖项

| 依赖 | 说明 |
|------|------|
| nomifun-tauri 主分支 | Phase 1 基于最新 stable 版本开发 |
| nomifun-auth | 复用现有 JWT 认证，扩展角色体系 |
| nomifun-db | 复用现有 sqlx 基础设施，扩展 schema |

### 10.3 决策点（已确认）

- [x] 租户隔离策略：**单租户优先**，不激活数据层隔离
- [x] 是否需要多租户 SaaS 支持：**Phase 1 不支持**，保留扩展点
- [x] 审计日志存储：**同库单表**，按用户筛选
- [x] 主题编辑器：**先做配置文件形式**，UI 可视化可选

---

> 文档结束 — 已调整为**单租户优先**架构，请检查确认。