Files

HaHafeng 66255368b7 feat(admin): Add user management and upgrade to module permission system

Features - User Management (Phase 4.1):
- Database: Add user_modules table for fine-grained module permissions
- Database: Add 4 user permissions (view/create/edit/delete) to role_permissions
- Backend: UserService (780 lines) - CRUD with tenant isolation
- Backend: UserController + UserRoutes (648 lines) - 13 API endpoints
- Backend: Batch import users from Excel
- Frontend: UserListPage (412 lines) - list/filter/search/pagination
- Frontend: UserFormPage (341 lines) - create/edit with module config
- Frontend: UserDetailPage (393 lines) - details/tenant/module management
- Frontend: 3 modal components (592 lines) - import/assign/configure
- API: GET/POST/PUT/DELETE /api/admin/users/* endpoints

Architecture Upgrade - Module Permission System:
- Backend: Add getUserModules() method in auth.service
- Backend: Login API returns modules array in user object
- Frontend: AuthContext adds hasModule() method
- Frontend: Navigation filters modules based on user.modules
- Frontend: RouteGuard checks requiredModule instead of requiredVersion
- Frontend: Remove deprecated version-based permission system
- UX: Only show accessible modules in navigation (clean UI)
- UX: Smart redirect after login (avoid 403 for regular users)

Fixes:
- Fix UTF-8 encoding corruption in ~100 docs files
- Fix pageSize type conversion in userService (String to Number)
- Fix authUser undefined error in TopNavigation
- Fix login redirect logic with role-based access check
- Update Git commit guidelines v1.2 with UTF-8 safety rules

Database Changes:
- CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled)
- ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code)
- INSERT 4 permissions + role assignments
- UPDATE PUBLIC tenant with 8 module subscriptions

Technical:
- Backend: 5 new files (~2400 lines)
- Frontend: 10 new files (~2500 lines)
- Docs: 1 development record + 2 status updates + 1 guideline update
- Total: ~4900 lines of code

Status: User management 100% complete, module permission system operational

2026-01-16 13:42:10 +08:00

5.8 KiB

Raw Blame History

PRD：Tool C - 科研数据编辑器 (MVP V1.1)

文档版本	V1.1 (工程细化版)
产品形态	Web 端数据编辑器 (AG Grid + AI Chat)
核心策略	"AI-First" + "Server-side State"。依靠 AI 生成 Python 代码完成清洗；以服务端 DataFrame 为单一数据源，前端负责渲染和轻量编辑。
技术底座	React + AG Grid + Node.js BFF + Python Sandbox (FastAPI) + DeepSeek-V3
变更记录	V1.1: 增加数据同步机制、撤销回滚策略、会话生命周期定义。

一、 MVP 核心目标 (Objectives)

验证闭环： 跑通 “自然语言 -> Python 代码 -> 后端执行 -> 前端刷新” 的完整链路。
数据一致性： 确保手动编辑与 AI 操作不冲突，状态可追溯。
可用性： 解决中文乱码、会话超时等实际工程问题。

二、详细功能需求 (Functional Requirements)

1. 界面框架与会话 (Shell & Session)

P0: 左右分栏布局： 左侧 AG Grid (70%)，右侧 AI Chat (30%)。
P0: 会话初始化 (Session Init):
- 用户上传文件 -> 后端开启 Python 进程/容器 -> 加载 df -> 返回 sessionId。
- 编码检测： 后端必须尝试 utf-8 和 gbk 解码，防止中文乱码。
P1: 心跳与保活 (Keep-alive):
- 前端每 30s 发送心跳。
- 超时策略： 若超过 30min 无操作，后端释放内存。用户再次操作时，提示“会话已过期，请重新加载文件”。

2. 超级网格 (The Grid) - 前端交互

P0: 数据展示 (View):
- 通过 API 分页拉取数据（预览模式，仅取前 100-500 行）。
- 列类型推断： 前端根据后端返回的 dtypes 渲染列头图标（数值/文本/日期）。
P0: 手动编辑 (Manual Edit):
- 支持双击修改单元格。
- 关键逻辑（脏数据标记）： 用户修改后，单元格右标红，数据暂存在前端 dirtyRows 队列中。
P0: 状态锁 (UI Locking):
- 当 AI 正在执行时，Grid 变为 只读 (Read-only)，显示 Loading 遮罩。

3. AI Copilot 智能助手 (The Brain) - 后端驱动

3.1 交互流程 (Chat Loop)

用户输入： “把年龄大于60的设为老年组”。
前置同步 (Auto-Sync): (V1.1 新增)
- 判定： 前端检查是否有未保存的手动修改 (dirtyRows).
- 动作： 如果有，先静默发送 PATCH /api/data 将手动修改同步给后端 df。确保 AI 基于最新数据操作。
代码生成： 后端调用 DeepSeek，生成 Pandas 代码。
预操作确认 (Action Card):
- 展示：代码预览 + 摘要。
- 按钮：[运行] | [取消]。

3.2 执行与回滚 (Execute & Rollback) - (V1.1 核心)

P0: 自动快照 (Auto-Checkpoint):
- 在执行 exec(code) 之前，后端必须先对当前 df 进行内存快照（或序列化备份）。
- 记录操作日志：ActionID: 101, Type: AI_CODE, Code: "..."。
P0: 执行反馈:
- 成功：返回新的预览数据 -> 刷新 Grid -> 添加一条“操作成功”消息。
- 失败：捕获 Python Traceback -> 让 AI 尝试自我修复 (Self-Correction) 一次 -> 若仍失败，向用户展示错误原因。
P0: 撤销操作 (Undo):
- 聊天框每条成功记录下显示 [撤销] 按钮。
- 逻辑：调用后端 rollback(action_id) -> 恢复到该操作前的快照 -> 刷新 Grid。

4. 快捷指令 (Prompt Chips)

P0: 顶部工具栏按钮（生成变量、长宽转换等），点击仅作为“快捷短语”填入输入框，不触发独立 UI 逻辑，保持架构统一。

5. 导出 (Export)

P0: 导出 Excel。
- 逻辑：后端直接将当前的 df (包含所有 AI 修改和手动修改) 写入 Excel 流并返回。

三、异常处理规范 (Error Handling)

异常场景	前端表现	后端处理
中文乱码	提示“编码格式识别失败，请手动选择”	尝试 chardet 检测，失败则报错
AI 代码报错	Chat 气泡变红，显示“AI 正在尝试修复...”	捕获 stderr，将错误反喂给 AI 重试 (Max 1次)
会话过期	全屏遮罩“会话已过期”	清理 Redis/内存，返回 401/404
手动修改冲突	提示“正在同步数据...”	优先处理手动 Patch，再执行 AI 任务

四、开发与测试重点 (QA Focus)

一致性测试：
- 先手动改一个值，再让 AI 删一行，确认那个值还在不在（或者是否正确被删）。
- 先让 AI 改一列，再撤销，确认是否完全恢复。
边界测试：
- 上传空文件。
- 上传全中文列名的文件。
- 让 AI 计算一个不存在的列。
性能测试：
- 连续快速发送 5 条指令，确保后端是串行队列处理，而不是并发搞乱数据。

五、附录：数据同步 API 定义 (简版)

POST /api/sync: 前端 -> 后端。发送手动修改的 Diff。
- Payload: [{ rowId: "P001", col: "age", value: 66 }]
POST /api/run: 前端 -> 后端。发送 AI 代码执行请求。
- Payload: { code: "df['new'] = 1", snapshot: true }
POST /api/undo: 前端 -> 后端。
- Payload: { step: -1 }

### 给开发团队的一句话总结

**“V1.1 的核心在于‘状态管理’。请务必保证后端 Python 内存里的 `DataFrame` 是唯一的‘真理来源 (Source of Truth)’。前端的所有操作（无论是手改还是 AI 改），本质上都是在向这个真理层发送指令和同步状态。”**

现在，您可以拿着这份文档，很有底气地去和开发团队开工了。它已经堵上了最容易翻车的几个漏洞。

5.8 KiB Raw Blame History Unescape Escape