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

- 移除 GovAI, nomifun-tauri, 算力盒子的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
2026-07-04 19:20:46 +08:00
parent 54d6465fa7
commit f7a720204a
3360 changed files with 802660 additions and 3 deletions
@@ -0,0 +1,470 @@
+# 通用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 可视化可选
+
+---
+
+> 文档结束 — 已调整为**单租户优先**架构，请检查确认。