Files

T

freedak f7a720204a Update: 将子项目从 submodule 转为完整内容

- 移除 GovAI, nomifun-tauri, 算力盒子 的 submodule 引用
- 添加所有子项目的完整源代码
- 保留原始 .git 为 .git.bak 备份

2026-07-04 19:20:46 +08:00

16 KiB

Raw Permalink Blame History

通用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 约束

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

6.2 假设

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

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

7.1 新增数据模型

// 系统配置（单租户模式，单条记录）
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 不激活隔离逻辑

// 未来多租户场景下启用
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 变量主题方案

/* 主题变量注入点（替换原有硬编码颜色） */
: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 决策点（已确认）

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

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

16 KiB Raw Permalink Blame History Unescape Escape