smart_grid_iot/.trae/specs/refactor-system-auth-pg/spec.md

# 系统管理与认证授权模块对齐新设计 Spec

## Why
系统设计已完成调整（鑫潼智电系统）：数据库从 MySQL 6 表升级为 PostgreSQL 37 表；系统管理域改为 7 张 `sys_` 前缀表；RBAC 由"权限码"模型改为"菜单级"模型（`sys_menu`/`sys_role_menu`）；新增数据字典（`sys_dict`）；原"系统设置"模块在新设计中无对应表。现有系统管理与认证授权代码仍基于旧模型，需要整体对齐新设计。

## What Changes
- **数据库引擎切换**：MySQL → PostgreSQL 15+（连接配置、安装 `pg`/`pg-hstore` 驱动；`database/db_init.sql` 已更新为 PostgreSQL 脚本）
- **系统域数据模型重构**（7 张表，替代原 6 张表）：
  - `sys_user`：username / password_hash / real_name / phone / email / status / last_login_at（移除 nickname、avatar、last_login_ip）
  - `sys_role`：role_code / role_name / description / sort_order（移除 status）
  - `sys_user_role`：user_id / role_id（不变）
  - `sys_menu`：菜单级 RBAC，menu_type 1目录/2菜单（本次不启用 3按钮），含 menu_path / component / icon / sort_order / permission / visible（替代 permissions 表）
  - `sys_role_menu`：role_id / menu_id（替代 role_permissions 表）
  - `sys_dict`：**新增**数据字典表
  - `sys_operation_log`：字段精简为 user_id / module / action / method / params / ip / created_at（移除 username、url、user_agent、request_params、response_data、status_code、duration、error_message）
- **认证逻辑适配**：登录基于 `sys_user` + `password_hash` 比对，更新 `last_login_at`；登录返回 userInfo（含 realName）、roles（role_code）、menus（角色菜单树）
- **RBAC 重构**：菜单级权限。前端由菜单树驱动侧边栏与路由；后端接口鉴权按"接口路径 → 菜单 permission 标识"校验，ADMIN 角色全量放行；**按钮级权限暂不保留**（v-permission 指令移除）
- **系统设置模块移除**：删除前后端系统设置代码（settings 页面、system.controller/system.service、api/system.ts）
- **新增菜单管理模块**：sys_menu 树形 CRUD（目录/菜单两级）
- **新增数据字典模块**：sys_dict CRUD 与类型分组查询
- **操作日志对齐**：实体、中间件、接口、前端页面字段更新
- **初始数据补齐**：4 个角色（ADMIN/SALESMAN/WORKER/CUSTOMER）、6 个顶级业务菜单 + 5 个系统管理子菜单、19 条字典数据、管理员账户 admin/admin123456（ADMIN 角色）及角色-菜单绑定

## Impact
- Affected specs: smart-grid-iot-admin（已完成项目，本次为增量调整）
- Affected code:
  - server：config/config.default.ts、package.json、entity 全部系统域实体、controller（auth/user/role/log/menu/dict）、service（auth/user/role/log/menu/dict）、middleware（auth/rbac/log）、dto
  - client：api（auth/user/role/log/menu/dict）、stores/permission.ts、router/index.ts、layouts/index.vue、views（system/user、system/role、log/operation、新增 system/menu、system/dict）、删除 views/settings
  - database/db_init.sql：补充初始数据（管理员账户、角色菜单绑定、系统管理子菜单）

## ADDED Requirements

### Requirement: PostgreSQL 数据库连接
系统 SHALL 使用 PostgreSQL 15+ 作为数据库：
- server 依赖安装 `pg`、`pg-hstore`
- `config.default.ts` 的 sequelize 数据源 dialect 为 `postgres`，连接 xintong 库
- 系统域 7 张表通过 `database/db_init.sql` 创建（Sequelize `sync: false`）

#### Scenario: 服务连接 PostgreSQL 成功
- **WHEN** 启动后端服务且本机已按 db_init.sql 建好库表
- **THEN** 服务正常启动，登录、查询等接口可正常读写 sys_ 系列表

### Requirement: 菜单级 RBAC（sys_menu）
系统 SHALL 以菜单为权限载体：
- `sys_menu` 支持两级树：目录（menu_type=1）、菜单（menu_type=2）；字段含 menu_path、component、icon、sort_order、permission、visible
- 用户登录返回其角色（经 `sys_role_menu`）关联的菜单树；前端据此渲染侧边栏与动态路由
- 后端接口鉴权：RbacMiddleware 将请求路径映射为权限标识，校验用户角色关联菜单的 permission 集合；ADMIN 角色（role_code=ADMIN）直接放行
- 本次不做按钮级权限（menu_type=3、v-permission 指令移除）

#### Scenario: 登录用户仅看到被授权菜单
- **WHEN** 业务员角色登录
- **THEN** 侧边栏只渲染其角色已绑定的菜单，访问未授权接口返回 403

#### Scenario: ADMIN 全量访问
- **WHEN** 运营管理员（ADMIN 角色）登录
- **THEN** 可见全部菜单，所有受保护接口放行

### Requirement: 菜单管理模块
系统 SHALL 提供菜单管理能力：
- 菜单树查询（全部菜单，供角色配置使用）
- 目录/菜单的创建、编辑、删除、排序、可见性切换
- 权限标识（permission）维护

### Requirement: 数据字典模块
系统 SHALL 提供数据字典管理能力：
- sys_dict 的创建、编辑、删除
- 按 dict_type 分组查询、状态筛选

### Requirement: 初始数据
系统 SHALL 通过 db_init.sql 初始化：
- 4 个角色：ADMIN（运营管理员）/ SALESMAN（业务员）/ WORKER（共享电工）/ CUSTOMER（客户）
- 6 个顶级业务菜单（客户管理/项目管理/运营派单/设备监控/统计报表/系统管理）与系统管理下 5 个子菜单（用户/角色/菜单/数据字典/操作日志）
- 管理员账户 admin/admin123456（bcrypt hash，角色 ADMIN）
- 角色-菜单绑定：ADMIN 绑定全部菜单；SALESMAN 绑定客户/项目/统计报表等业务菜单；WORKER/CUSTOMER 无后台菜单
- 19 条字典数据（customer_status/equip_type/device_type/dispatch_status/pay_cycle/dispatch_type）

## MODIFIED Requirements

### Requirement: 用户管理模块
The system SHALL 管理 sys_user：
- 列表支持分页、关键词搜索（username/realName/phone）、状态筛选、角色筛选
- 新增/编辑字段：username、password、realName、phone、email、status、角色分配（roleIds）
- 删除、批量删除、状态切换（原能力保留）
- 返回数据不包含 password_hash

#### Scenario: 管理员创建用户
- **WHEN** 管理员填写 username/realName/phone/email/角色并提交
- **THEN** 系统校验唯一性与必填项，bcrypt 加密密码写入 sys_user，分配 sys_user_role，列表刷新

### Requirement: 角色管理模块
The system SHALL 管理 sys_role：
- 列表支持分页、关键词搜索（roleCode/roleName）、关联用户数统计
- 新增/编辑字段：roleCode、roleName、description、sortOrder
- 权限配置由"权限码树"改为"菜单树勾选"（sys_role_menu）
- 删除时若关联用户则禁止删除

### Requirement: 操作日志模块
The system SHALL 记录操作日志：
- 字段：user_id、module、action、method、params、ip、created_at
- 日志中间件按新字段写入，仅记录写操作（POST/PUT/DELETE）
- 查询接口支持按操作人/模块/时间范围筛选
- 前端日志页字段与接口对齐

### Requirement: 认证授权服务
The system SHALL 适配新用户模型：
- 登录：username + password 校验（sys_user.password_hash）、禁用校验、更新 last_login_at
- 登录返回：accessToken、refreshToken、userInfo（id/username/realName）、roles（role_code 数组）、menus（角色菜单树）
- 刷新 Token、当前用户信息接口同步适配

### Requirement: 前端动态菜单与路由
The system SHALL 由菜单树驱动前端：
- 侧边栏菜单由用户 menus 渲染（目录→子菜单两级，含图标）
- 动态路由按 sys_menu.menu_path/component 注册；component 缺失（未开发业务模块）时渲染"功能开发中"占位页
- 登录跳转仪表盘（仪表盘保持固定路由，不纳入菜单表）
- 移除设置页相关路由与菜单

## REMOVED Requirements

### Requirement: 系统设置模块（站点名称/Logo/会话超时/密码策略/IP白名单）
**Reason**: 新设计无对应表，模块整体移除。
**Migration**: 删除 server 端 system.controller.ts/system.service.ts、client 端 views/settings 页面与 api/system.ts，以及相关路由、菜单、日志映射与中间件引用。

### Requirement: 权限码 RBAC 与按钮级权限（permissions/role_permissions + v-permission）
**Reason**: 新设计采用菜单级 RBAC，按钮级权限暂不保留。
**Migration**: 删除 permissions/role_permissions 相关实体、服务与 DTO，由 sys_menu/sys_role_menu 替代；移除前端 v-permission 指令及按钮级权限判断；路由 meta.permission 改为基于菜单 permission 标识。