# 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（按任务文档执行开发）。