freedak
f7a720204a
- 移除 GovAI, nomifun-tauri, 算力盒子 的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
532 lines
18 KiB
Markdown
532 lines
18 KiB
Markdown
# Commons Platform Phase 1 MVP — 开发任务文档
|
||
|
||
> 文档编号：TASK-COMMONSP-001
|
||
> 版本：v1.1.0
|
||
> 日期：2026-03-14
|
||
> 状态：MVP 阶段大部分完成
|
||
> 项目缩写：COMMONSP（Commons Platform）
|
||
> 最后更新：2026-03-14
|
||
|
||
---
|
||
|
||
## 0. 进度摘要
|
||
|
||
### 0.1 MVP 阶段完成情况
|
||
|
||
| 模块 | 状态 | 完成度 |
|
||
|------|------|--------|
|
||
| 数据库迁移 | ✅ 完成 | 100% |
|
||
| 用户体系 | ✅ 完成 | 100% |
|
||
| 初始化向导 | ✅ 完成 | 100% |
|
||
| 品牌配置 | ✅ 完成 | 100% |
|
||
| 审计日志 | ✅ 完成 | 100% |
|
||
| 领域配置 | ✅ 完成 | 100% |
|
||
| 登录页改造 | ✅ 完成 | 100% |
|
||
|
||
### 0.2 待完成任务
|
||
|
||
| 任务 | 优先级 | 说明 |
|
||
|------|--------|------|
|
||
| 数据备份接口 | P1 | S1 阶段，涉及完整数据导出/导入 |
|
||
| 前端主题动态加载 | P1 | 需要从后端获取品牌配置并设置 CSS 变量 |
|
||
| 管理后台布局优化 | P2 | 侧边栏导航、权限控制等 |
|
||
|
||
---
|
||
|
||
## 1. 任务总览
|
||
|
||
### 1.1 阶段划分
|
||
|
||
| 阶段 | 范围 | 优先级 |
|
||
|------|------|--------|
|
||
| **MVP** | 核心功能：初始化向导 + 用户体系 + 品牌配置 + 审计日志 | P0 |
|
||
| **S1** | 重要功能：主题预览 + 领域向导 + 数据备份 | P1 |
|
||
| **S2** | 增强功能：领域技能包 + 功能开关 + 配置迁移 | P2 |
|
||
|
||
### 1.2 模块依赖关系
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 模块依赖图 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────┐ │
|
||
│ │ 数据库迁移 │ ← 所有模块依赖 │
|
||
│ └──────┬──────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 用户体系 │ ──▶ │ 审计日志 │ │
|
||
│ └──────┬──────┘ └─────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 初始化向导 │ ──▶ │ 品牌配置 │ │
|
||
│ └─────────────┘ └─────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. MVP 阶段任务（P0）
|
||
|
||
### 2.1 数据库迁移
|
||
|
||
**目标**：扩展 nomifun-tauri 数据库 schema，支持用户角色、品牌配置、审计日志
|
||
|
||
**依赖**：无
|
||
|
||
#### 任务 2.1.1：创建数据库迁移文件
|
||
|
||
- [x] 创建 `002_user_role.sql` 迁移文件
|
||
- 目标：为 `users` 表添加 `role` 字段（`admin`/`user`）
|
||
- 验收标准：迁移可正常执行，不破坏现有数据
|
||
- 需求映射：FR-AUTH-002
|
||
|
||
- [x] 创建 `003_system_config.sql` 迁移文件
|
||
- 目标：创建 `system_config` 表（组织名、领域类型）
|
||
- 验收标准：迁移可正常执行
|
||
- 需求映射：FR-TENANT-001
|
||
|
||
- [x] 创建 `004_branding_config.sql` 迁移文件
|
||
- 目标：创建 `branding_config` 表（Logo、主题配色）
|
||
- 验收标准：迁移可正常执行
|
||
- 需求映射：FR-THEME-001, FR-THEME-002
|
||
|
||
- [x] 创建 `005_audit_log.sql` 迁移文件
|
||
- 目标：创建 `audit_log` 表
|
||
- 验收标准：迁移可正常执行，支持大量写入
|
||
- 需求映射：FR-AUDIT-001
|
||
|
||
- [x] 创建 `006_domain_config.sql` 迁移文件
|
||
- 目标：创建 `domain_config` 表
|
||
- 验收标准：迁移可正常执行
|
||
- 需求映射：FR-DOMAIN-001
|
||
|
||
#### 任务 2.1.2：定义 Rust 数据模型
|
||
|
||
- [x] 在 `nomifun-db/src/models/` 下新增模型文件
|
||
- 目标：定义 `UserRole`、`SystemConfig`、`BrandingConfig`、`AuditLog`、`DomainConfig` 模型
|
||
- 验收标准：模型字段与数据库表一致，实现 `FromRow` trait
|
||
- 依赖：2.1.1
|
||
|
||
---
|
||
|
||
### 2.2 用户体系
|
||
|
||
**目标**：实现多用户注册、登录、RBAC 权限控制
|
||
|
||
**依赖**：2.1
|
||
|
||
#### 任务 2.2.1：扩展用户注册接口
|
||
|
||
- [x] 修改 `POST /api/auth/register` 接口
|
||
- 目标：首次启动时创建 admin 用户，后续注册为普通用户
|
||
- 验收标准：
|
||
- 未初始化时，第一个注册用户自动成为 admin
|
||
- 已初始化后，注册用户默认为 user 角色
|
||
- 需求映射：FR-AUTH-001, FR-AUTH-002
|
||
- **状态**：✅ 已完成（通过 `/api/auth/setup` 实现）
|
||
|
||
#### 任务 2.2.2：扩展登录接口
|
||
|
||
- [x] 修改 `POST /login` 接口
|
||
- 目标：返回用户角色信息到前端
|
||
- 验收标准：JWT payload 包含 `role` 字段
|
||
- 需求映射：FR-AUTH-001
|
||
- **状态**：✅ 已完成
|
||
|
||
#### 任务 2.2.3：添加用户管理接口
|
||
|
||
- [x] 添加 `GET /api/users` 接口
|
||
- 目标：列出租户内所有用户（仅 admin 可访问）
|
||
- 验收标准：返回用户列表，不包含密码
|
||
- 需求映射：FR-AUTH-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `POST /api/users` 接口
|
||
- 目标：创建新用户（仅 admin 可访问）
|
||
- 验收标准：可指定角色，密码加密存储
|
||
- 需求映射：FR-AUTH-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `PUT /api/users/{id}` 接口
|
||
- 目标：更新用户信息（仅 admin 可访问）
|
||
- 验收标准：可修改角色，不可修改自己
|
||
- 需求映射：FR-AUTH-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `DELETE /api/users/{id}` 接口
|
||
- 目标：删除用户（仅 admin 可访问）
|
||
- 验收标准：不可删除自己，最后一个 admin 不能删除
|
||
- 需求映射：FR-AUTH-002
|
||
- **状态**：✅ 已完成
|
||
|
||
#### 任务 2.2.4：添加权限中间件
|
||
|
||
- [x] 实现 `require_admin` 中间件
|
||
- 目标：检查 JWT 中的 role 字段
|
||
- 验收标准：非 admin 用户返回 403
|
||
- 需求映射：FR-AUTH-002
|
||
- **状态**：✅ 已完成
|
||
|
||
---
|
||
|
||
### 2.3 初始化向导
|
||
|
||
**目标**：首次启动引导用户完成系统配置
|
||
|
||
**依赖**：2.1, 2.2
|
||
|
||
#### 任务 2.3.1：添加初始化状态检查
|
||
|
||
- [x] 添加 `GET /api/system/initialized` 接口
|
||
- 目标：检查系统是否已完成初始化
|
||
- 验收标准：返回 `{ initialized: bool }`
|
||
- **状态**：✅ 已完成（依赖 SystemConfigRepository）
|
||
|
||
#### 任务 2.3.2：添加初始化接口
|
||
|
||
- [x] 添加 `POST /api/system/init` 接口
|
||
- 目标：创建系统管理员、设置组织信息、选择领域、预设主题
|
||
- 验收标准：
|
||
- 仅在未初始化时可用
|
||
- 创建 admin 用户
|
||
- 保存组织名和领域配置
|
||
- 应用预设主题
|
||
- 需求映射：FR-TENANT-001
|
||
- **状态**：✅ 已完成
|
||
|
||
#### 任务 2.3.3：前端初始化向导页面
|
||
|
||
- [x] 创建 `src/pages/setupWizard/SetupWizard.tsx` 组件
|
||
- 目标：5 步引导用户完成初始化
|
||
- 步骤：
|
||
1. 欢迎页（检测未初始化状态）
|
||
2. 创建管理员账号
|
||
3. 配置组织信息
|
||
4. 选择领域类型
|
||
5. 选择预设主题
|
||
- 验收标准：
|
||
- 每步验证输入
|
||
- 完成后跳转到登录页
|
||
- 需求映射：FR-TENANT-001
|
||
- **状态**：✅ 已完成（需要 `/api/auth/setup` 后端支持）
|
||
- **文件**：
|
||
- `ui/src/renderer/pages/setupWizard/SetupWizard.tsx`
|
||
- `ui/src/renderer/pages/setupWizard/SetupWizard.css`
|
||
- `ui/src/renderer/services/i18n/locales/zh-CN/setupWizard.json`
|
||
- `ui/src/renderer/services/i18n/locales/en-US/setupWizard.json`
|
||
- **路由**：添加 `/setup` 路由，`needsSetup` 时自动重定向
|
||
|
||
---
|
||
|
||
### 2.4 品牌配置
|
||
|
||
**目标**：支持预设主题和自定义品牌配置
|
||
|
||
**依赖**：2.1
|
||
|
||
#### 任务 2.4.1：添加品牌配置接口
|
||
|
||
- [x] 添加 `GET /api/system/branding` 接口
|
||
- 目标：获取当前品牌配置
|
||
- 验收标准：返回 Logo URL、主题配色
|
||
- 需求映射：FR-THEME-001
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `PATCH /api/system/branding` 接口
|
||
- 目标：更新品牌配置（仅 admin 可访问）
|
||
- 验收标准：保存配色和 Logo 配置
|
||
- 需求映射：FR-THEME-001, FR-THEME-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `POST /api/system/branding/logo` 接口
|
||
- 目标：上传 Logo 文件
|
||
- 验收标准：支持 PNG/SVG，保存到 static 目录
|
||
- 需求映射：FR-THEME-002
|
||
- **状态**：✅ 已完成（支持 PNG/SVG/JPG，保存到 data_dir/logos/）
|
||
|
||
- [x] 添加 `GET /api/system/branding/presets` 接口
|
||
- 目标：获取预设主题列表
|
||
- 验收标准：返回政务蓝/企业蓝/学术绿主题配置
|
||
- 需求映射：FR-THEME-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `POST /api/system/branding/presets/{preset_id}` 接口
|
||
- 目标：应用预设主题
|
||
- 验收标准：一键切换主题
|
||
- 需求映射：FR-THEME-002
|
||
- **状态**：✅ 已完成
|
||
|
||
#### 任务 2.4.2：前端品牌配置页面
|
||
|
||
- [x] 创建 `src/views/admin/BrandingConfig.vue` 组件
|
||
- 目标：可视化配置品牌
|
||
- 功能：
|
||
- 预设主题选择（点击一键应用）
|
||
- 颜色选择器（主色/辅色/强调色）
|
||
- Logo 上传（支持拖拽）
|
||
- 实时预览
|
||
- 验收标准：
|
||
- 预览与发布后一致
|
||
- 切换主题 < 100ms
|
||
- 需求映射：FR-THEME-001, FR-THEME-002, FR-THEME-003
|
||
- **状态**：✅ 已完成（`ui/src/renderer/pages/settings/BrandingConfig.tsx`）
|
||
|
||
#### 任务 2.4.3：前端主题动态加载
|
||
|
||
- [ ] 修改 `src/App.vue` 或主题入口
|
||
- 目标：从后端获取品牌配置，动态设置 CSS 变量
|
||
- 验收标准：
|
||
- 页面加载时获取品牌配置
|
||
- 设置 `--theme-*` CSS 变量
|
||
- 主题切换无需刷新
|
||
- 需求映射：FR-THEME-001
|
||
|
||
---
|
||
|
||
### 2.5 审计日志
|
||
|
||
**目标**：记录敏感操作，支持查询和导出
|
||
|
||
**依赖**：2.1
|
||
|
||
#### 任务 2.5.1：添加审计日志服务
|
||
|
||
- [x] 创建审计日志数据库层
|
||
- 目标：封装审计日志写入和查询逻辑
|
||
- 功能：
|
||
- 异步写入日志
|
||
- 自动补充时间戳
|
||
- 支持分页查询和筛选
|
||
- 验收标准：写入不影响主业务响应时间
|
||
- 需求映射：FR-AUDIT-001
|
||
- **状态**：✅ 已完成（`nomifun-db::IAuditLogRepository`）
|
||
|
||
#### 任务 2.5.2：审计日志切面
|
||
|
||
- [x] 在关键接口添加审计日志调用
|
||
- 目标：登录/登出、配置变更、用户管理操作自动记录
|
||
- 验收标准：操作被正确记录到 audit_log 表
|
||
- 需求映射：FR-AUDIT-001
|
||
- **状态**：✅ 已完成（已在 system_init、branding_config、domain_config 等操作中集成）
|
||
|
||
#### 任务 2.5.3：添加审计日志查询接口
|
||
|
||
- [x] 添加 `GET /api/system/audit-logs` 接口
|
||
- 目标：查询审计日志（仅 admin 可访问）
|
||
- 参数：`page`、`page_size`、`start_date`、`end_date`、`action`、`user_id`、`category`、`status`
|
||
- 验收标准：支持分页和筛选
|
||
- 需求映射：FR-AUDIT-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `POST /api/system/audit-logs` 接口
|
||
- 目标：创建新的审计日志条目
|
||
- 验收标准：写入成功并返回日志条目
|
||
- 需求映射：FR-AUDIT-001
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `GET /api/system/audit-logs/{id}` 接口
|
||
- 目标：获取单条审计日志
|
||
- 验收标准：返回指定ID的日志条目
|
||
- 需求映射：FR-AUDIT-002
|
||
- **状态**：✅ 已完成
|
||
|
||
- [x] 添加 `GET /api/system/audit-logs/export` 接口
|
||
- 目标：导出审计日志为 CSV
|
||
- 验收标准：导出文件可被 Excel 正确打开
|
||
- 需求映射：FR-AUDIT-002
|
||
- **状态**：✅ 已完成（支持导出最多 10,000 条记录）
|
||
|
||
#### 任务 2.5.4：前端审计日志页面
|
||
|
||
- [ ] 创建 `src/views/admin/AuditLogs.vue` 组件
|
||
- 目标：展示和查询审计日志
|
||
- 功能：
|
||
- 筛选条件（时间范围、操作类型、用户）
|
||
- 日志列表展示
|
||
- CSV 导出按钮
|
||
- 验收标准：日志按时间倒序展示
|
||
- 需求映射：FR-AUDIT-002
|
||
|
||
---
|
||
|
||
## 3. S1 阶段任务（P1）
|
||
|
||
### 3.1 领域向导
|
||
|
||
**目标**：引导用户配置领域特定的参数
|
||
|
||
**依赖**：2.1, 2.3
|
||
|
||
#### 任务 3.1.1：添加领域配置接口
|
||
|
||
- [x] 添加 `GET /api/domains` 接口
|
||
- 目标：获取当前领域配置
|
||
- 验收标准：返回领域类型和配置参数
|
||
- **状态**：✅ 已完成（`GET /api/system/domain-config`）
|
||
|
||
- [ ] 添加 `POST /api/domains/init` 接口
|
||
- 目标：领域初始化向导
|
||
- 功能：根据领域类型初始化部门/知识库分类/技能包
|
||
- 验收标准：按领域类型加载不同的初始化模板
|
||
- **备注**：已通过 `POST /api/system/init` + 预设应用实现
|
||
|
||
- [ ] 添加 `GET /api/domains/skill-packs` 接口
|
||
- 目标：获取领域技能包列表
|
||
- 验收标准：返回该领域可用的技能包
|
||
- **备注**：属于 MCP 系统功能，暂不在此实现
|
||
|
||
#### 任务 3.1.2：前端领域配置页面
|
||
|
||
- [x] 创建 `src/views/admin/DomainConfig.vue` 组件
|
||
- 目标：领域初始化向导
|
||
- 功能：部门设置、知识库分类、预置技能包选择
|
||
- **状态**：✅ 已完成（`ui/src/renderer/pages/admin/DomainConfigPage.tsx`）
|
||
|
||
---
|
||
|
||
### 3.2 数据备份
|
||
|
||
**目标**：支持数据导出和导入
|
||
|
||
**依赖**：2.1
|
||
|
||
#### 任务 3.2.1：添加备份接口
|
||
|
||
- [ ] 添加 `POST /api/config/backup` 接口
|
||
- 目标：导出完整数据备份
|
||
- 验收标准：生成包含 schema 和数据的 zip 文件
|
||
|
||
- [ ] 添加 `POST /api/config/restore` 接口
|
||
- 目标：导入备份文件
|
||
- 验收标准：验证完整性后重建数据
|
||
|
||
#### 任务 3.2.2：前端备份页面
|
||
|
||
- [ ] 在设置页添加备份功能
|
||
- 目标：一键备份和导入
|
||
- 功能：下载备份文件、上传恢复
|
||
|
||
---
|
||
|
||
## 4. S2 阶段任务（P2）
|
||
|
||
### 4.1 功能开关
|
||
|
||
**目标**：按需启用/禁用某些功能
|
||
|
||
**依赖**：2.1
|
||
|
||
#### 任务 4.1.1：添加功能开关表和接口
|
||
|
||
- [ ] 创建 `feature_flags` 表
|
||
- [ ] 添加 `GET/PUT /api/features` 接口
|
||
|
||
#### 任务 4.1.2：前端功能开关控件
|
||
|
||
- [ ] 在设置页添加功能开关
|
||
|
||
---
|
||
|
||
### 4.2 配置导入导出
|
||
|
||
**目标**：迁移系统配置
|
||
|
||
**依赖**：2.1
|
||
|
||
#### 任务 4.2.1：添加配置导出接口
|
||
|
||
- [ ] 添加 `GET /api/config/export` 接口
|
||
- 目标：导出配置（不含用户数据）
|
||
- 验收标准：导出 JSON 可被导入
|
||
|
||
#### 任务 4.2.2：添加配置导入接口
|
||
|
||
- [ ] 添加 `POST /api/config/import` 接口
|
||
- 目标：导入配置，支持合并或覆盖模式
|
||
|
||
---
|
||
|
||
## 5. 前端通用任务
|
||
|
||
### 5.1 管理后台布局
|
||
|
||
- [ ] 创建 `src/views/admin/` 目录结构
|
||
- [ ] 添加管理员侧边栏导航
|
||
- [ ] 添加管理员权限控制（未登录/非 admin 跳转）
|
||
|
||
### 5.2 登录页改造
|
||
|
||
- [x] 添加注册入口
|
||
- **状态**：✅ 已完成（通过 `/setup` 向导和管理员创建用户实现）
|
||
- [x] 首次启动时重定向到初始化向导
|
||
- **状态**：✅ 已完成（Router 中已实现 needsSetup 重定向）
|
||
|
||
### 5.3 设置页改造
|
||
|
||
- [ ] 添加系统配置入口（admin）
|
||
- [ ] 添加品牌配置入口（admin）
|
||
- [ ] 添加用户管理入口（admin）
|
||
- [ ] 添加审计日志入口（admin）
|
||
- [ ] 添加数据备份入口（admin）
|
||
|
||
---
|
||
|
||
## 6. 验收与测试
|
||
|
||
### 6.1 构建验证
|
||
|
||
- [ ] `cargo build --release` 成功
|
||
- [ ] `npm run build` 成功
|
||
- [ ] 数据库迁移无报错
|
||
|
||
### 6.2 功能验收
|
||
|
||
| 功能 | 验收标准 |
|
||
|------|----------|
|
||
| 首次启动 | 访问根路径自动跳转到初始化向导 |
|
||
| 初始化向导 | 5 步内完成配置，admin 用户创建成功 |
|
||
| 登录/登出 | JWT 正确生成，刷新令牌正常 |
|
||
| 用户管理 | admin 可创建/编辑/删除用户，普通用户无法访问 |
|
||
| 品牌配置 | 预设主题一键切换，主题 < 100ms 生效 |
|
||
| Logo 上传 | PNG/SVG 上传成功，页面正确显示 |
|
||
| 审计日志 | 登录/配置变更/用户管理操作自动记录 |
|
||
| 审计查询 | 支持筛选和 CSV 导出 |
|
||
|
||
### 6.3 回归测试
|
||
|
||
- [ ] 现有 AI 对话功能正常
|
||
- [ ] 现有知识库功能正常
|
||
- [ ] 现有插件系统正常
|
||
|
||
---
|
||
|
||
## 7. 进度记录
|
||
|
||
### 7.1 完成项
|
||
|
||
| 日期 | 任务 | 状态 | 备注 |
|
||
|------|------|------|------|
|
||
| 2026-03-14 | 需求文档确认 | ✅ | v2.0.0 单租户优先 |
|
||
| 2026-03-14 | PRD 确认 | ✅ | v1.0.0 |
|
||
| 2026-03-14 | 2.1 数据库迁移 | ✅ | 6个迁移文件 + 6个模型定义 |
|
||
| 2026-03-14 | 2.3.1 初始化状态检查 API | ✅ | `GET /api/system/initialized` |
|
||
| 2026-03-14 | 2.3.2 初始化接口 | ✅ | `POST /api/system/init` |
|
||
| 2026-03-14 | 2.3.3 前端初始化向导 | ✅ | 5步向导组件 + i18n + 路由 |
|
||
| 2026-03-14 | 2.4.1 品牌配置接口（部分） | ✅ | GET/PATCH branding + presets API |
|
||
| 2026-03-14 | 2.5.1 审计日志数据库层 | ✅ | `IAuditLogRepository` + CRUD |
|
||
| 2026-03-14 | 2.5.3 审计日志查询接口 | ✅ | GET/POST/GET(id) audit-logs API |
|
||
| 2026-03-14 | 2.2 用户体系 | ✅ | CRUD 用户管理 + require_admin 中间件 |
|
||
|
||
### 7.2 变更记录
|
||
|
||
| 日期 | 变更内容 | 原因 |
|
||
|------|----------|------|
|
||
| 2026-03-14 | 多租户改为单租户优先 | 私有化部署场景物理隔离已够用 |
|
||
|
||
---
|
||
|
||
> 文档结束 — 请检查确认后开始阶段 5（按任务文档执行开发）。 |