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
parent 98d862dbd4
commit 66255368b7
560 changed files with 70424 additions and 52353 deletions
--- a/docs/03-业务模块/DC-数据清洗整理/04-开发计划/工具C_Bug修复总结_2025-12-08.md
+++ b/docs/03-业务模块/DC-数据清洗整理/04-开发计划/工具C_Bug修复总结_2025-12-08.md
@@ -1,46 +1,46 @@
 # 工具C - Bug修复与优化总结

 **修复日期**: 2025-12-08  
-**菫ｮ螟堺ｺ?*: AI Assistant  
-**菫ｮ螟崎激蝗ｴ**: 7荳ｪ荳･驥埼琉鬚?+ 5荳ｪ菴馴ｪ御ｼ伜<EFBDBC>?
+**修复人**: AI Assistant  
+**修复范围**: 7个严重问题 + 5个体验优化

 ---

 ## 📋 修复清单

-### 笨?髣ｮ鬚<EFBDAE>1<EFBFBD>夊｡ｨ螟ｴ迚ｹ谿雁ｭ礼ｬｦ蟇ｼ閾ｴ蜉溯<E89C89>蠑ょｸ?
+### ✅ 问题1：表头特殊字符导致功能异常

-#### 1-1. Pivot霓ｬ謐｢蜿ｪ譛<EFBFBD>1蛻?<3F>閥 **蟾ｲ菫ｮ螟?*
+#### 1-1. Pivot转换只有1列 🔴 **已修复**

 **问题描述**:
- 陦ｨ螟ｴ蛹<EFBFBD>性諡ｬ蜿ｷ縲∫ｭ牙捷遲臥音谿雁ｭ礼ｬｦ<EFBFBD>亥ｦＡ菴馴㍾<EFBFBD><EFBFBD>g<EFBFBD>荏縲～1.鬮倩｡蜴狗羅<E78B97>域裏=0<>梧怏=1<>荏<EFBFBD>?
- 蟇ｼ閾ｴPivot霓ｬ謐｢譌ｶ蛻怜錐螟<EFBFBD>炊螟ｱ雍･<EFBFBD>悟宵逕滓<EFBFBD>?蛻苓御ｸ肴弍謖蛾剰ｧ<E589B0><EFBDA7>螻募ｼ
+- 表头包含括号、等号等特殊字符（如`体重（kg）`、`1.高血压病（无=0，有=1）`）
+- 导致Pivot转换时列名处理失败，只生成1列而不是按透视列展开

 **根本原因**:
 - Python的`pivot_table`列名展平逻辑无法处理特殊字符

 **解决方案**:
 ```python
-# 譁<EFBFBD>ｻｶ: extraction_service/operations/pivot.py (73-95陦?
-# 蠅槫ｼｺ蛻怜錐螻募ｹｳ騾ｻ霎托ｼ梧ｸ<EFBFBD>炊迚ｹ谿雁ｭ礼ｬ?
+# 文件: extraction_service/operations/pivot.py (73-95行)
+# 增强列名展平逻辑，清理特殊字符
 if len(value_columns) == 1:
    value_col_clean = str(value_columns[0]).replace('(', '').replace(')', '').strip()
    df_pivot.columns = [f'{value_col_clean}___{str(col).replace(" ", "_")}' for col in df_pivot.columns]
 ```

-#### 1-2. 隶｡邂怜<EFBFBD>蜉溯<EFBFBD>謚･髞?<3F>閥 **蟾ｲ菫ｮ螟?*
+#### 1-2. 计算列功能报错 🔴 **已修复**

 **问题描述**:
- 轤ｹ蜃ｻ"謇ｧ陦瑚ｮ｡邂<EFBDA1>"謚･髞呻ｼ?蜈ｬ蠑丞桁蜷ｫ荳榊<E88DB3>隶ｸ逧<EFBDB8>ｭ礼ｬｦ"
+- 点击"执行计算"报错："公式包含不允许的字符"
 - 无法使用包含中文括号、等号、冒号的列名

 **根本原因**:
- `compute.py`逧<EFBFBD>ｭ｣蛻咎ｪ瑚ｯ∬ｿ<EFBFBD>ｺ惹ｸ･譬ｼ<EFBFBD>悟宵蜈∬ｮｸ闍ｱ譁<EFBFBD>峡蜿?
+- `compute.py`的正则验证过于严格，只允许英文括号

 **解决方案**:
 ```python
-# 譁<EFBFBD>ｻｶ: extraction_service/operations/compute.py (63-67陦?
-# 1. 謾ｾ螳ｽ蟄礼ｬｦ鬪瑚ｯ<EFBFBD>ｼ梧髪謖∽ｸｭ譁<EFBFBD>峡蜿ｷ縲∫ｭ牙捷縲∝<EFBFBD>蜿?
+# 文件: extraction_service/operations/compute.py (63-67行)
+# 1. 放宽字符验证，支持中文括号、等号、冒号
 allowed_chars = r'[a-zA-Z0-9_\u4e00-\u9fa5\s\+\-\*/\(\)\[\]\{\}\.,:\*\*=（）【】、。：；！？]'

 # 2. 使用列名映射，将特殊字符列名替换为安全变量名
@@ -52,29 +52,29 @@ for i, col in enumerate(result.columns):

 ---

-### 笨?髣ｮ鬚<EFBDAE>2<EFBFBD>壽焚蛟ｼ譏<EFBDBC>蟆<EFBFBD>宵謠仙叙1荳ｪ蜚ｯ荳蛟?<3F>閥 **蟾ｲ菫ｮ螟?*
+### ✅ 问题2：数值映射只提取1个唯一值 🔴 **已修复**

-#### 2-1. 蟀壼ｧｻ迥ｶ蜀ｵ蜿ｪ譏ｾ遉?荳ｪ蛟ｼ<E89B9F>亥ｮ樣刔譛?遘搾ｼ解沐ｴ **蟾ｲ菫ｮ螟?*
+#### 2-1. 婚姻状况只显示1个值（实际有4种）🔴 **已修复**

 **问题描述**:
- 騾画叫"蟀壼ｧｻ迥ｶ蜀ｵ"蛻玲慮<E78EB2>悟宵謠仙叙蛻?荳ｪ蜚ｯ荳蛟?
- 螳樣刔謨ｰ謐ｮ譛?遘搾ｼ壼ｷｲ蟀壹∵悴蟀壹∝<C280>莉悶?遨ｺ逋ｽ)
+- 选择"婚姻状况"列时，只提取到1个唯一值
+- 实际数据有4种：已婚、未婚、其他、(空白)

 **根本原因**:
- 蜑咲ｫｯ莉餐data`謨ｰ扈<EFBDB0>署蜿門髪荳蛟ｼ<E89B9F>御ｽ<E5BEA1>data`蜿ｪ譛牙<EFBFBD>?0陦?
- 螳梧紛謨ｰ謐ｮ譛?668陦鯉ｼ悟ｩ壼ｧｻ迥ｶ蜀ｵ逧<EFBDB5><E980A7>蟶<EFBFBD>ｸ榊<EFBDB8>?
+- 前端从`data`数组提取唯一值，但`data`只有前50行
+- 完整数据有3668行，婚姻状况的分布不均

 **解决方案**:
 ```typescript
-// 譁<EFBFBD>ｻｶ: frontend-v2/src/modules/dc/pages/tool-c/components/RecodeDialog.tsx (45-72陦?
-// 隹<EFBFBD>畑蜷守ｫｯAPI莉主ｮ梧紛謨ｰ謐ｮ荳ｭ謠仙叙蜚ｯ荳蛟?
+// 文件: frontend-v2/src/modules/dc/pages/tool-c/components/RecodeDialog.tsx (45-72行)
+// 调用后端API从完整数据中提取唯一值
 const response = await fetch(
  `/api/v1/dc/tool-c/sessions/${sessionId}/unique-values?column=${encodeURIComponent(selectedColumn)}`
 );
 ```

 ```typescript
-// 譁ｰ蠅暸PI: backend/src/modules/dc/tool-c/controllers/SessionController.ts (366-428陦?
+// 新增API: backend/src/modules/dc/tool-c/controllers/SessionController.ts (366-428行)
 // GET /api/v1/dc/tool-c/sessions/:id/unique-values?column=xxx
 async getUniqueValues(...) {
  const data = await sessionService.getFullData(id);
@@ -85,50 +85,50 @@ async getUniqueValues(...) {
 }
 ```

-#### 2-2. 遐皮ｩｶ荳ｭ蠢<EFBFBD>ｼ壼宵譏ｾ遉ｺ1荳ｪ蛟ｼ<EFBFBD>亥ｮ樣刔譛?遘搾ｼ解沐ｴ **蟾ｲ菫ｮ螟?*
+#### 2-2. 研究中心：只显示1个值（实际有4种）🔴 **已修复**

-蜷御ｸ奇ｼ御ｽｿ逕ｨ逶ｸ蜷瑚ｧ｣蜀ｳ譁ｹ譯医?
+同上，使用相同解决方案。

 ---

-### 笨?菴馴ｪ御ｼ伜喧<E4BC9C>?鬘ｹ<E9AC98><EFBDB9>
+### ✅ 体验优化（5项）

-#### 笨?莨伜喧1<E596A7>夊｡ｨ譬ｼ郤ｿ譯<EFBDBF>｢懆牡蜉<E789A1>豺?笞?**蟾ｲ螳梧<E89EB3>?*
+#### ✅ 优化1：表格线框颜色加深 ⚪ **已完成**

-**髴豎?*: 郤ｿ譯<EFBDBF>､ｪ豺｡<E8B1BA>檎恚荳肴ｸ<E882B4>･?
+**需求**: 线框太淡，看不清楚

 **修改**:
 ```css
-/* 譁<EFBFBD>ｻｶ: frontend-v2/src/modules/dc/pages/tool-c/components/ag-grid-custom.css (24-26陦? */
--ag-border-color: #d1d5db;        /* 蜴?e5e7eb -> #d1d5db */
--ag-row-border-color: #e5e7eb;     /* 蜴?f1f5f9 -> #e5e7eb */
+/* 文件: frontend-v2/src/modules/dc/pages/tool-c/components/ag-grid-custom.css (24-26行) */
+--ag-border-color: #d1d5db;        /* 原#e5e7eb -> #d1d5db */
+--ag-row-border-color: #e5e7eb;     /* 原#f1f5f9 -> #e5e7eb */
 border-bottom: 2px solid #d1d5db;   /* 表头底部边框加深 */
 ```

-#### 笨?莨伜喧2<E596A7>夊｡ｨ螟ｴ螳ｽ蠎ｦ蜃丞ｰ?0% + Tooltip 笞?**蟾ｲ螳梧<E89EB3>?*
+#### ✅ 优化2：表头宽度减小40% + Tooltip ⚪ **已完成**

-**髴豎?*: 蛻怜ｮｽ螟ｪ螟ｧ<E89E9F>悟酔荳螻乗裏豕墓仞遉ｺ螟ｪ螟壼<E89E9F>
+**需求**: 列宽太大，同一屏无法显示太多列

 **修改**:
 ```typescript
-// 譁<EFBFBD>ｻｶ: frontend-v2/src/modules/dc/pages/tool-c/components/DataGrid.tsx (32-53陦?
+// 文件: frontend-v2/src/modules/dc/pages/tool-c/components/DataGrid.tsx (32-53行)
 {
  headerName: col.name,
-  headerTooltip: col.name,  // 笨?鮠<>譬<EFBFBD>ぎ蛛懈仞遉ｺ螳梧紛蛻怜錐
-  width: 90,                // 笨?蜴?50 -> 90<EFBFBD>亥㍼蟆?0%<25>?
-  minWidth: 60,             // 笨?蜴?00 -> 60
+  headerTooltip: col.name,  // ✅ 鼠标悬停显示完整列名
+  width: 90,                // ✅ 原150 -> 90（减少40%）
+  minWidth: 60,             // ✅ 原100 -> 60
 }
 ```

-#### 笨?莨伜喧3<E596A7>壽眠蛻玲仞遉ｺ蝨ｨ蜴溷<E89CB4>譌∬ｾｹ 笞?**蟾ｲ螳梧<E89EB3>?*
+#### ✅ 优化3：新列显示在原列旁边 ⚪ **已完成**

-**髴豎?*: 逕滓<E98095>譁ｰ蛻玲慮<E78EB2>悟ｸ梧悍邏ｧ驍ｻ蜴溷<E89CB4><E6BAB7>梧婿萓ｿ蟇ｹ豈?
+**需求**: 生成新列时，希望紧邻原列，方便对比

 **修改**:
- `binning.py` (139-148陦?: 蛻<>ｻ<EFBFBD><EFBDBB>謠貞<E8ACA0>蛻ｰ蜴溷<E89CB4>譌∬ｾｹ
- `recode.py` (56-63陦?: 郛也<E9839B>∝<EFBFBD>謠貞<E8ACA0>蛻ｰ蜴溷<E89CB4>譌∬ｾｹ
- `compute.py` (149-161陦?: 隶｡邂怜<E98282>謠貞<E8ACA0>蛻ｰ隨ｬ荳荳ｪ蠑慕畑蛻玲浴霎ｹ
- `conditional.py` (131-139陦?: 譚｡莉ｶ蛻玲薯蜈･蛻ｰ蜿り<E3828A><C280>譌∬ｾｹ
+- `binning.py` (139-148行): 分组列插入到原列旁边
+- `recode.py` (56-63行): 编码列插入到原列旁边
+- `compute.py` (149-161行): 计算列插入到第一个引用列旁边
+- `conditional.py` (131-139行): 条件列插入到参考列旁边

 ```python
 # 示例: binning.py
@@ -139,13 +139,13 @@ cols.insert(original_col_index + 1, new_column_name)
 result = result[cols]
 ```

-#### 笨?莨伜喧4<E596A7>壻ｿ晄戟蜴溷ｧ玖｡碁｡ｺ蠎<EFBDBA> 笞?**蟾ｲ螳梧<E89EB3>?*
+#### ✅ 优化4：保持原始行顺序 ⚪ **已完成**

-**髴豎?*: 謨ｰ謐ｮ螟<EFBDAE>炊蜷趣ｼ瑚｡碁｡ｺ蠎剰ｦ∽ｿ晄戟荳主次Excel荳閾?
+**需求**: 数据处理后，行顺序要保持与原Excel一致

 **修改**:
 ```python
-# 譁<EFBFBD>ｻｶ: extraction_service/operations/pivot.py (90-97陦?
+# 文件: extraction_service/operations/pivot.py (90-97行)
 # Pivot后按原始顺序排序
 original_order = result[index_column].drop_duplicates().tolist()
 order_map = {val: idx for idx, val in enumerate(original_order)}
@@ -153,51 +153,51 @@ df_pivot['_sort_order'] = df_pivot[index_column].map(order_map)
 df_pivot = df_pivot.sort_values('_sort_order').drop(columns=['_sort_order'])
 ```

-#### 笨?莨伜喧5<E596A7>壽署遉ｺ蜿ｪ譏ｾ遉ｺ蜑?0陦?笞?**蟾ｲ螳梧<E89EB3>?*
+#### ✅ 优化5：提示只显示前50行 ⚪ **已完成**

-**髴豎?*: 逕ｨ謌ｷ諡<EFBDB7>ｿ<EFBFBD>焚謐ｮ螟<EFBDAE>炊譌ｶ謨ｰ謐ｮ荳｢螟?
+**需求**: 用户担心数据处理时数据丢失

 **修改**:
 ```typescript
-// 譁<EFBFBD>ｻｶ: frontend-v2/src/modules/dc/pages/tool-c/index.tsx (256-264陦?
+// 文件: frontend-v2/src/modules/dc/pages/tool-c/index.tsx (256-264行)
 <div className="mb-2 px-3 py-2 bg-blue-50 border border-blue-200 rounded-lg">
-  <strong>謠千､ｺ<EFBFBD>?/strong>陦ｨ譬ｼ莉<EFBFBD>ｱ慕､ｺ蜑<EFBFBD> <strong>50陦?/strong> 謨ｰ謐ｮ鬚<EFBFBD>ｧ茨ｼ?
-  蟇ｼ蜃ｺ蜉溯<EFBFBD>蟆<EFBFBD>桁蜷?<strong>蜈ｨ驛ｨ</strong> 螟<EFBFBD>炊扈捺棡
+  <strong>提示：</strong>表格仅展示前 <strong>50行</strong> 数据预览，
+  导出功能将包含 <strong>全部</strong> 处理结果
 </div>
 ```

 ---

-## <EFBFBD>女<EFBFBD>?譫ｶ譫<EFBDB6>合郤ｧ<E983A4>壼<EFBFBD>蜷肴<E89CB7><E882B4>㊥蛹匁惻蛻ｶ
+## 🏗️ 架构升级：列名标准化机制

-荳ｺ蠖ｻ蠎戊ｧ｣蜀ｳ迚ｹ谿雁ｭ礼ｬｦ髣ｮ鬚假ｼ悟ｼ募<EFBFBD>莠?*蛻怜錐譏<E98C90>蟆<EFBFBD>**譛ｺ蛻ｶ<E89BBB>?
+为彻底解决特殊字符问题，引入了**列名映射**机制：

 ### 新增字段: `columnMapping`

 ```typescript
-// backend/src/modules/dc/tool-c/services/SessionService.ts (21-24陦?
+// backend/src/modules/dc/tool-c/services/SessionService.ts (21-24行)
 interface ColumnMapping {
-  originalName: string;  // 蜴溷ｧ句<EFBFBD>蜷搾ｼ壻ｽ馴㍾<EFBFBD><EFBFBD>g<EFBFBD>?
+  originalName: string;  // 原始列名：体重（kg）
  safeName: string;      // 安全列名：col_5
-  displayName: string;   // 譏ｾ遉ｺ蜷咲ｧｰ<EFBFBD>壻ｽ馴㍾<EFBFBD><EFBFBD>g<EFBFBD>?
+  displayName: string;   // 显示名称：体重（kg）
 }
 ```

 ### 数据库Schema变更

 ```prisma
-// backend/prisma/schema.prisma (864陦?
+// backend/prisma/schema.prisma (864行)
 model DcToolCSession {
  // ...
-  columnMapping Json? @map("column_mapping") // 笨?譁ｰ蠅槫ｭ玲ｮｵ
+  columnMapping Json? @map("column_mapping") // ✨ 新增字段
  // ...
 }
 ```

-### Session蛻帛ｻｺ譌ｶ閾ｪ蜉ｨ逕滓<EFBFBD>譏<EFBFBD>蟆?
+### Session创建时自动生成映射

 ```typescript
-// SessionService.ts (520-535陦?
+// SessionService.ts (520-535行)
 private generateColumnMapping(originalColumns: string[]): ColumnMapping[] {
  return originalColumns.map((originalName, index) => ({
    originalName,
@@ -211,29 +211,29 @@ private generateColumnMapping(originalColumns: string[]): ColumnMapping[] {

 ## 📦 修改文件清单

-### 蜷守ｫｯ (5荳ｪ譁<EFBDAA>ｻ?
+### 后端 (5个文件)

-1. 笨?`backend/prisma/schema.prisma` - 譁ｰ蠅枋olumnMapping蟄玲ｮｵ
-2. 笨?`backend/src/modules/dc/tool-c/services/SessionService.ts` - 蛻怜錐譏<EFBFBD>蟆<EFBFBD>函謌<EFBFBD>
-3. 笨?`backend/src/modules/dc/tool-c/controllers/SessionController.ts` - 譁ｰ蠅櫁執蜿門髪荳蛟ｼAPI
-4. 笨?`backend/src/modules/dc/tool-c/routes/index.ts` - 譁ｰ蠅櫁ｷｯ逕ｱ
+1. ✅ `backend/prisma/schema.prisma` - 新增columnMapping字段
+2. ✅ `backend/src/modules/dc/tool-c/services/SessionService.ts` - 列名映射生成
+3. ✅ `backend/src/modules/dc/tool-c/controllers/SessionController.ts` - 新增获取唯一值API
+4. ✅ `backend/src/modules/dc/tool-c/routes/index.ts` - 新增路由

-### Python譛榊苅 (5荳ｪ譁<EFBDAA>ｻ?
+### Python服务 (5个文件)

-5. 笨?`extraction_service/operations/pivot.py` - 蠅槫ｼｺ蛻怜錐螟<EFBFBD>炊 + 菫晄戟陦碁｡ｺ蠎?
-6. 笨?`extraction_service/operations/compute.py` - 謾ｾ螳ｽ蟄礼ｬｦ鬪瑚ｯ<EFBFBD> + 蛻怜錐譏<E98C90>蟆<EFBFBD>
-7. 笨?`extraction_service/operations/recode.py` - 譁ｰ蛻玲薯蜈･菴咲ｽｮ
-8. 笨?`extraction_service/operations/binning.py` - 譁ｰ蛻玲薯蜈･菴咲ｽｮ
-9. 笨?`extraction_service/operations/conditional.py` - 譁ｰ蛻玲薯蜈･菴咲ｽｮ
+5. ✅ `extraction_service/operations/pivot.py` - 增强列名处理 + 保持行顺序
+6. ✅ `extraction_service/operations/compute.py` - 放宽字符验证 + 列名映射
+7. ✅ `extraction_service/operations/recode.py` - 新列插入位置
+8. ✅ `extraction_service/operations/binning.py` - 新列插入位置
+9. ✅ `extraction_service/operations/conditional.py` - 新列插入位置

-### 蜑咲ｫｯ (4荳ｪ譁<EFBDAA>ｻ?
+### 前端 (4个文件)

-10. 笨?`frontend-v2/src/modules/dc/pages/tool-c/components/RecodeDialog.tsx` - 隹<EFBFBD>畑譁ｰAPI
-11. 笨?`frontend-v2/src/modules/dc/pages/tool-c/components/DataGrid.tsx` - 蛻怜ｮｽ莨伜喧 + tooltip
-12. 笨?`frontend-v2/src/modules/dc/pages/tool-c/components/ag-grid-custom.css` - 郤ｿ譯<EFBFBD>｢懆牡
-13. 笨?`frontend-v2/src/modules/dc/pages/tool-c/index.tsx` - 蜑?0陦梧署遉?
+10. ✅ `frontend-v2/src/modules/dc/pages/tool-c/components/RecodeDialog.tsx` - 调用新API
+11. ✅ `frontend-v2/src/modules/dc/pages/tool-c/components/DataGrid.tsx` - 列宽优化 + tooltip
+12. ✅ `frontend-v2/src/modules/dc/pages/tool-c/components/ag-grid-custom.css` - 线框颜色
+13. ✅ `frontend-v2/src/modules/dc/pages/tool-c/index.tsx` - 前50行提示

-**諤ｻ隶｡**: 13荳ｪ譁<EFBFBD>ｻｶ菫ｮ謾?
+**总计**: 13个文件修改

 ---

@@ -250,7 +250,7 @@ npx prisma generate
 # 创建迁移文件
 npx prisma migrate dev --name add_column_mapping_to_tool_c_session

-# 螯よ棡驕<EFBFBD>芦譚<EFBFBD>剞髞呵ｯｯ<EFBFBD>瑚ｯｷ蜈ｳ髣ｭ謇譛丑ode霑帷ｨ句錘驥崎ｯ?
+# 如果遇到权限错误，请关闭所有Node进程后重试
 ```

 ### 2. 重启服务
@@ -271,103 +271,102 @@ npm run dev

 ### 3. 测试验证

-#### 豬玖ｯ<EFBFBD>1<EFBFBD>夊｡ｨ螟ｴ迚ｹ谿雁ｭ礼ｬ?
- [ ] 荳贋ｼ<EFBFBD>蛹<EFBFBD>性迚ｹ谿雁ｭ礼ｬｦ陦ｨ螟ｴ逧Еxcel<EFBFBD>亥ｦＡ菴馴㍾<EFBFBD><EFBFBD>g<EFBFBD>荏<EFBFBD>?
+#### 测试1：表头特殊字符
+- [ ] 上传包含特殊字符表头的Excel（如`体重（kg）`）
 - [ ] 使用Pivot转换功能，验证能生成多列
- [ ] 菴ｿ逕ｨ隶｡邂怜<EFBFBD>蜉溯<EFBFBD><EFBFBD>碁ｪ瑚ｯ∽ｸ肴冠髞?
+- [ ] 使用计算列功能，验证不报错

-#### 豬玖ｯ<EFBFBD>2<EFBFBD>壽焚蛟ｼ譏<EFBFBD>蟆<EFBFBD>髪荳蛟?
- [ ] 騾画叫"蟀壼ｧｻ迥ｶ蜀ｵ"蛻苓ｿ幄｡梧焚蛟ｼ譏<EFBDBC>蟆?
- [ ] 鬪瑚ｯ∬<EFBFBD>譏ｾ遉?荳ｪ蜚ｯ荳蛟ｼ<E89B9F>亥ｷｲ蟀壹∵悴蟀壹∝<C280>莉悶∫ｩｺ逋ｽ<E9808B><EFBDBD>
- [ ] 騾画叫"遐皮ｩｶ荳ｭ蠢<EFBDAD>ｼ?蛻暦ｼ碁ｪ瑚ｯ∵仞遉ｺ4荳ｪ荳ｭ蠢?
+#### 测试2：数值映射唯一值
+- [ ] 选择"婚姻状况"列进行数值映射
+- [ ] 验证能显示4个唯一值（已婚、未婚、其他、空白）
+- [ ] 选择"研究中心："列，验证显示4个中心

-#### 豬玖ｯ<EFBFBD>3<EFBFBD>壻ｽ馴ｪ御ｼ伜<EFBFBD>?
- [ ] 鬪瑚ｯ∬｡ｨ譬ｼ郤ｿ譯<EFBFBD>｢懆牡譏ｯ蜷ｦ譖ｴ貂<EFBFBD><EFBFBD>?
- [ ] 鬪瑚ｯ∝<EFBFBD>螳ｽ蜿倡ｪ<EFBFBD>ｼ碁ｼ<EFBFBD>譬<EFBFBD>ぎ蛛懈仞遉ｺ螳梧紛蛻怜<EFBFBD>?
- [ ] 鬪瑚ｯ∵眠蛻怜<EFBFBD>邇ｰ蝨ｨ蜴溷<EFBFBD>譌∬ｾ?
+#### 测试3：体验优化
+- [ ] 验证表格线框颜色是否更清晰
+- [ ] 验证列宽变窄，鼠标悬停显示完整列名
+- [ ] 验证新列出现在原列旁边
 - [ ] 验证数据处理后行顺序不变
- [ ] 鬪瑚ｯ<EFBFBD>｡ｵ髱｢鬘ｶ驛ｨ譏ｾ遉ｺ"蜿ｪ螻慕､ｺ蜑<EFBDBA>50陦?謠千､ｺ
+- [ ] 验证页面顶部显示"只展示前50行"提示

 ---

 ## 📊 影响评估

 ### 性能影响
- 笨?**譌<>諤ｧ閭ｽ謐溷､ｱ**: 蛻怜錐譏<EFBFBD>蟆<EFBFBD>惠Session蛻帛ｻｺ譌ｶ荳谺｡諤ｧ逕滓<EFBFBD><EFBFBD>悟錘扈ｭ譌<EFBFBD>鬚晏､門ｼ髞
- 笨?**API莨伜喧**: 譁ｰ蠅槫髪荳蛟ｼAPI<EFBFBD>碁∩蜈榊燕遶ｯ驥榊､榊､<EFBFBD>炊螟ｧ謨ｰ謐ｮ
+- ✅ **无性能损失**: 列名映射在Session创建时一次性生成，后续无额外开销
+- ✅ **API优化**: 新增唯一值API，避免前端重复处理大数据

-### 蜈ｼ螳ｹ諤?
- 笨?**蜷大錘蜈ｼ螳ｹ**: 譌ｧSession荳榊女蠖ｱ蜩搾ｼ<EFBFBD>olumnMapping荳ｺ蜿ｯ騾牙ｭ玲ｮｵ<EFBFBD><EFBFBD>
- 笨?**謨ｰ謐ｮ霑∫ｧｻ**: 譌<EFBFBD>髴霑∫ｧｻ邇ｰ譛画焚謐ｮ
+### 兼容性
+- ✅ **向后兼容**: 旧Session不受影响（columnMapping为可选字段）
+- ✅ **数据迁移**: 无需迁移现有数据

 ### 风险评估
- <EFBFBD>泙 **菴朱｣朱<EFBDA3>?*: 菫ｮ謾ｹ髮<EFBDB9>ｸｭ蝨ｨ謫堺ｽ懷ｱゑｼ御ｸ榊ｽｱ蜩肴<E89CA9>ｸ蠢<EFBDB8>ｭ伜お騾ｻ霎<EFBDBB>
- <EFBFBD>泙 **譏灘屓貊?*: 蜿ｯ蠢ｫ騾溷屓騾蛻ｰ菫ｮ謾ｹ蜑咲沿譛ｬ
+- 🟢 **低风险**: 修改集中在操作层，不影响核心存储逻辑
+- 🟢 **易回滚**: 可快速回退到修改前版本

 ---

-## <EFBFBD>識 逕ｨ謌ｷ莉ｷ蛟?
+## 🎯 用户价值

-1. **迚ｹ谿雁ｭ礼ｬｦ蜈ｨ髱｢謾ｯ謖<EFBFBD>** 笨?
-   - 謾ｯ謖∽ｸｭ譁<EFBFBD>峡蜿ｷ<EFBFBD>夲ｼ茨ｼ峨√舌?
+1. **特殊字符全面支持** ✅
+   - 支持中文括号：（）、【】
   - 支持等号、冒号、标点：=、：、。、！
-   - 荳榊<EFBFBD>蝗<EFBFBD>蛻怜錐譬ｼ蠑乗冠髞?
+   - 不再因列名格式报错

-2. **謨ｰ謐ｮ螳梧紛諤ｧ菫晞<EFBFBD>?* 笨?
+2. **数据完整性保障** ✅
   - 数值映射从完整数据提取（不受前50行限制）
-   - 菫晄戟蜴溷ｧ玖｡碁｡ｺ蠎擾ｼ育畑謌ｷ荳榊<EFBFBD>諡<EFBFBD>ｿ<EFBFBD>焚謐ｮ髞吩ｹｱ<EFBFBD>?
+   - 保持原始行顺序（用户不再担心数据错乱）

-3. **譖ｴ螂ｽ逧<EFBFBD>畑謌ｷ菴馴ｪ?* 笨?
-   - 貂<EFBFBD>匆逧<EFBFBD>｡ｨ譬ｼ隗<EFBFBD>ｧ画譜譫?
+3. **更好的用户体验** ✅
+   - 清晰的表格视觉效果
   - 优化的列宽，同屏显示更多数据
-   - 逶ｴ隗ら噪譁ｰ蛻嶺ｽ咲ｽｮ<EFBFBD>育ｴｧ驍ｻ蜴溷<EFBFBD><EFBFBD>?
-   - 譏守｡ｮ逧<EFBFBD>焚謐ｮ鬚<EFBFBD>ｧ域署遉?
+   - 直观的新列位置（紧邻原列）
+   - 明确的数据预览提示

 ---

-## <EFBFBD>答 謚譛ｯ莠ｮ轤?
+## 📚 技术亮点

 ### 1. 列名映射机制
- **隶ｾ隶｡逅<EFBFBD>ｿｵ**: 蜑咲ｫｯ譏ｾ遉ｺ蜴溷ｧ句錐<E58FA5>悟錘遶ｯ菴ｿ逕ｨ螳牙<E89EB3>蜷?
- **螳樒鴫譁ｹ蠑<EFBFBD>**: Session蛻帛ｻｺ譌ｶ荳谺｡諤ｧ逕滓<EFBFBD>譏<EFBFBD>蟆<EFBFBD><EFBFBD>邉?
- **謇ｩ螻墓?*: 譛ｪ譚･蜿ｯ謾ｯ謖∵峩螟夂音谿雁ｭ礼ｬｦ蝨ｺ譎?
+- **设计理念**: 前端显示原始名，后端使用安全名
+- **实现方式**: Session创建时一次性生成映射关系
+- **扩展性**: 未来可支持更多特殊字符场景

-### 2. 蜷守ｫｯ蜚ｯ荳蛟ｼ謠仙<EFBFBD>?
- **隗｣蜀ｳ逞帷せ**: 蜑咲ｫｯdata蜿鈴剞<E988B4>亥宵譛?0陦鯉ｼ<E9AF89>
- **謚譛ｯ譁ｹ譯?*: 譁ｰ蠅暸PI<50>御ｻ三SS闔ｷ蜿門ｮ梧紛謨ｰ謐ｮ
- **諤ｧ閭ｽ莨伜喧**: 蜴ｻ驥<EFBDBB>+謗貞ｺ擾ｼ瑚ｿ泌屓貂<E5B193>ｴ怜錘逧<E98C98>髪荳蛟?
+### 2. 后端唯一值提取
+- **解决痛点**: 前端data受限（只有50行）
+- **技术方案**: 新增API，从OSS获取完整数据
+- **性能优化**: 去重+排序，返回清洗后的唯一值

 ### 3. 智能列重排序
- **逕ｨ謌ｷ髴豎?*: 譁ｰ蛻怜<E89BBB>邇ｰ蝨ｨ逶ｸ蜈ｳ蛻玲浴霎ｹ
- **謚譛ｯ螳樒<EFBFBD>?*: Pandas蛻鈴㍾謗貞ｺ擾ｼ<EFBFBD>insert`譁ｹ豕包ｼ?
+- **用户需求**: 新列出现在相关列旁边
+- **技术实现**: Pandas列重排序（`insert`方法）
 - **适用场景**: Binning、Recode、Compute、Conditional

-### 4. 菫晄戟陦碁｡ｺ蠎?
- **蝨ｺ譎ｯ**: Pivot遲画桃菴應ｼ壽隼蜿倩｡碁｡ｺ蠎?
+### 4. 保持行顺序
+- **场景**: Pivot等操作会改变行顺序
 - **方案**: 记录原始顺序，操作后恢复
- **螳樒鴫**: 荳ｴ譌ｶ謗貞ｺ丞<EFBFBD>?+ `sort_values`
+- **实现**: 临时排序列 + `sort_values`

 ---

 ## 🏆 总结

-譛ｬ谺｡菫ｮ螟崎ｧ｣蜀ｳ莠?*7荳ｪ荳･驥埼琉鬚?* + **5荳ｪ菴馴ｪ御ｼ伜<EFBFBD>?*<2A>梧ｶ牙<EFBDB6>?*13荳ｪ譁<EFBDAA>ｻ?*菫ｮ謾ｹ縲?
+本次修复解决了**7个严重问题** + **5个体验优化**，涉及**13个文件**修改。

-**譬ｸ蠢<EFBFBD><EFBFBD>蟆ｱ**<EFBFBD>?
- 笨?蠖ｻ蠎戊ｧ｣蜀ｳ迚ｹ谿雁ｭ礼ｬｦ髣ｮ鬚假ｼ亥<EFBDBC>蜷肴<E89CB7><E882B4>㊥蛹匁惻蛻ｶ<E89BBB>?
- 笨?菫ｮ螟肴焚蛟ｼ譏<EFBDBC>蟆<EFBFBD>髪荳蛟ｼ謠仙叙髞呵ｯｯ<EFBDAF>域眠蠅槫錘遶ｯAPI<EFBFBD>?
- 笨?蜈ｨ髱｢謠仙合逕ｨ謌ｷ菴馴ｪ鯉ｼ?荳ｪ扈<EFBDAA>鰍莨伜喧<E4BC9C><E596A7>
+**核心成就**：
+- ✅ 彻底解决特殊字符问题（列名标准化机制）
+- ✅ 修复数值映射唯一值提取错误（新增后端API）
+- ✅ 全面提升用户体验（5个细节优化）

-**荳倶ｸ豁･蟒ｺ隶?*<2A>?
+**下一步建议**：
 1. 进行全面回归测试
-2. 譖ｴ譁ｰ逕ｨ謌ｷ譁<EFBFBD>｡｣<EFBFBD>瑚ｯｴ譏守音谿雁ｭ礼ｬｦ謾ｯ謖?
+2. 更新用户文档，说明特殊字符支持
 3. 监控生产环境性能指标

 ---

 **修复完成时间**: 2025-12-08 当前时间  
-**迥ｶ諤?*: 笨?蟾ｲ螳梧<E89EB3><E6A2A7>悟ｾ<E6829F>ｵ玖ｯ暮ｪ瑚ｯ?
-
+**状态**: ✅ 已完成，待测试验证