FastapiAdmin/docs/BUG_AND_ROADMAP.md

# 缺陷与需求梳理 / 解决顺序排期

> 来源：产品与用户反馈整理（持续更新）  
> 说明：**BUG** 为缺陷或错误行为；**需求** 为功能增强或非缺陷类诉求。排期优先：**安全 → 阻断使用类缺陷 → 性能 → 大型能力**。

---

## 一、BUG（缺陷 / 错误行为）


| 编号     | 简述                                       | 说明                            | 状态 |
| ------ | ---------------------------------------- | ----------------------------- | -- |
| **1**  | 角色授权：动子权限后丢父菜单，入口消失；分配后左侧能显示，点进页面后左侧导航没了 | 保存时补全祖先菜单 id；授权树节点用 `value ?? id` 建父链（`PermissonDrawer`） | **已验证解决** |
| **2**  | 左侧 / 顶部 / 混合三种布局下：兄弟目录同时高亮、或父级不亮、混合布局展开被收起等 | **`MenuItem.menuItemIndex`**：目录（有可见子节点）的 `el-menu` **index** 仅用菜单树 `path.resolve` 结果，禁止对目录用 `router.resolve(name)`（易解析成父级短路径如 `/task`，触发兄弟分支误亮）；**叶子** `index` 用 `router.resolve(name).path`，与 `route.path`、`default-active` 同源。**`BasicMenu`**：`default-active` = `meta.activeMenu` 或规范化 `route.path`；去掉 `el-menu` 按 `route.path` 的 **`:key`**（避免每次跳转整表重建）；`watch` 仅在 **`nextTick` 内一次** `updateActiveIndex`。**`MixLayout`**：`BasicMenu` 使用 **`:key="mixSideMenuKey"`**，仅切换顶级模块时重建侧栏。父级标题高亮依赖 **Element Plus** `el-sub-menu.is-active`。另：目录 **redirect** 必填见前后端校验（数据规范）。 | **已验证解决** |
| **7**  | 混合布局下点「AI 智能助手」会跳到应用管理                   | 顶栏当前模块与路由前缀误匹配（如 `/app` 与 `/application`）；已用最长前缀匹配修复 | **已验证解决** |
| **8**  | 历史对话内容不全（仅首条）等                         | **附件**：**非缺陷**，系当前**模型/后端能力不支持附件**，非前端逻辑错误；对话输入已关闭实际上传并提示「附件功能开发中」。若后续接入支持多模态/文件的模型，再按**需求**迭代。历史会话展示不全等问题另计 | — |
| **14** | 建普通用户分配权限：未全选二级时一级消失，二级变一级               | 与 **#1** 同类；随 **#1** 一并修复与验证        | **已验证解决** |
| **15** | 先查库再分页，应改为数据库分页                          | 列表接口已改为 `CRUDBase.page`（OFFSET/LIMIT + COUNT）；**仍用内存分页**：在线用户（Redis）、资源目录（本地文件）、代码生成「数据库表」列表（Inspector 全量）、AI 会话（Agno） | **已验证解决** |
| **21** | 代码生成不识别表主键，强制 `id`                       | 代码生成 BUG                      | — |
| **24** | 登录慢，因查 IP 等，希望优化                         | ``LOGIN_RESOLVE_IP_LOCATION`` 关闭时，操作日志路由曾仍调外网解析 IP；已改为 ``IpLocalUtil.resolve_location_for_log`` 与发 token 逻辑一致 | **已验证解决** |
| **27** | 新增用户密码明文传输                               | **安全漏洞**，需 HTTPS + 传输层防护或密码策略 | — |
| **28** | PG 下 date 类型新增报错                         | PostgreSQL `DATE` 与 ORM/校验对齐后新增正常；**已验证解决**（仍建议 PG 环境做回归） | **已验证解决** |


---

## 二、需求（功能 / 增强 / 非缺陷）


| 编号      | 简述                                   |
| ------- | ------------------------------------ |
| **3**   | 企业微信、飞书等移动端快捷登录                      |
| **4**   | 同步企业微信、蓝凌等 OA 组织架构（部门、人员）            |
| **5**   | 按岗位授权（非角色），与 OA/企微组织同步               |
| **6**   | 菜单很多时载入/修改很慢                         |
| **9**   | 数据权限按菜单/模块细分（如公告全量、用户本部门及以下）         |
| **10**  | 前端中英文大量未翻译                           |
| **11**  | 上传封装 OSS、S3、FTP/FTPS 等               |
| **12**  | 适配 Python 3.13；升级 asyncmy、pandas 等版本 |
| **13**  | 多租户                                  |
| **16**  | AI：知识库 + Skills 管理                   |
| **17**  | 钉钉登录与消息推送                            |
| **18**  | 工作流编排 + 应用上传，类似 Dify                 |
| **19**  | BPM 在线表单、树表、主子表                      |
| **20**  | 菜单升级：导出个人菜单、清空、升级系统菜单再导入             |
| **22**  | WebSocket + 类 MQTT，通知/工作项与前端处理接口     |
| **23**  | 简单博客 Demo（前端免鉴权读数据 + 规范示例）           |
| **25**  | 免登录能力加总开关                            |
| **26a** | 有 `order` 字段时统一按 `order` 排序          |
| **26b** | 布局：分系统式，点目录弹出子系统菜单                   |


> 原反馈中有两条均标为「26」，此处拆为 **26a（排序）**、**26b（布局）**。

---

## 三、合并与依赖说明

- **#1 + #14**：同一类「权限勾选 ↔ 菜单树」问题；**已验证解决**（前端树 `value`/父链与保存补祖先），后续大改菜单数据结构时可做回归。
- **#7**：与布局/路由强相关；**已验证解决**（混合顶栏最长前缀匹配）。**#2** 已验证解决，三种布局菜单可一起做回归。
- **#15**：列表接口已切数据库分页；无法在 SQL 层分页的数据源仍用 `PaginationService`（见 BUG 表说明）。
- **#9、#5、#4**：组织/岗位/数据权限有产品依赖，宜在方案定稿后再开发。
- **#8 附件**：不作为缺陷跟进；与模型能力对齐后再立项。

---

## 四、建议解决顺序（排期）

### 第一阶段（优先：安全 + 阻断使用 + 明确 BUG）

1. **#27 密码明文传输** — 安全最高优先级（HTTPS、前端摘要/后端策略、接口审计）。
2. ~~**#1 + #14 权限与菜单树**~~ — **已验证解决**（回显、保存补祖先、`menuTreeNodeId`）。
3. ~~**#7 混合布局 + AI 助手跳转错误**~~ — **已验证解决**（`MixTopMenu` 最长前缀匹配顶栏路径）。
4. **#21 代码生成主键** — 影响生成代码正确性，改动面相对可控。
5. ~~**#28 PG date**~~ — **已验证解决**（PG 环境可做回归用例）。

### 第二阶段（体验与性能）

1. ~~**#24 登录慢（IP 等）**~~ — **已验证解决**（操作日志与登录共用可配置 IP 归属地；默认不查外网）。
2. ~~**#15 数据库分页**~~ — **已验证解决**（见 BUG 表；例外场景保留内存分页）。
3. **#6 菜单多卡顿** — 前端虚拟列表/懒加载 + 接口按需加载 + 后端必要索引。
4. ~~**#2 三种布局下菜单高亮与混合侧栏展开**~~ — **已验证解决**（见 BUG 表 **#2** 说明）。
5. **#8 AI 历史会话** — 附件已澄清为非缺陷（模型不支持）；仅「历史不全」等若仍存在则独立排 AI 子迭代。

### 第三阶段（规范与国际化）

1. **#26a 统一 order 排序** — 约定 + 扫描替换高风险点。
2. **#10 中英文** — 可持续迭代，可先列文案清单再分批补全。

### 第四阶段（架构与集成类，需立项/分期）

1. **#11 存储抽象（OSS/S3/FTP…）**
2. **#12 Python 3.13 + 依赖升级** — 全量测试后再上生产。
3. **#22 WebSocket 通知机制**
4. **#25 免登录开关**
5. **#3、#4、#17** 企微/飞书/钉钉/OA 同步（常分多期：登录 → 组织 → 消息）

### 第五阶段（大功能，单独路线图）

1. **#13 多租户**
2. **#9 菜单级数据权限**（与 #5、#4 联动）
3. **#16 AI 知识库/Skills**
4. **#18 工作流 + 应用编排**
5. **#19 BPM 表单**
6. **#20 菜单导入导出升级**
7. **#23 博客 Demo**
8. **#26b 分系统布局模式**

---

## 五、执行建议

- 建议建立 **Issue / 里程碑**：P0（约 1～2 周）→ P1 → P2…，每条拆 **验收标准**。
- **#2** 已闭环；**#1/#14/#7** 菜单相关变更仍可打包回归，避免菜单逻辑反复。
- **#15** 已完成；若新增列表接口，优先 `CRUDBase.page`，非 SQL 数据源再考虑 `PaginationService`。

---

## 变更记录


| 日期         | 说明            |
| ---------- | ------------- |
| 2026-03-29 | 初版：缺陷与需求梳理及排期 |
| 2026-03-29 | **#21** 代码生成：`pk_column_name` 贯通 Vue/TS/Schema/Service/CRUD 模板；**#1/#14** 角色权限保存补全祖先菜单；**#7** 混合顶栏最长前缀匹配；**#24** 登录 IP 归属地可配置关闭（`LOGIN_RESOLVE_IP_LOCATION`） |
| 2026-03-29 | **#2** 曾尝试改 `MenuItem` 子项 `base-path`，与现有「父级 basePath 已含本段」的拼接规则冲突，导致同级全高亮；已回退为 `resolvePath(child.path)`，原「兄弟误高亮」问题仍待用 `isActiveChild` 路径边界等方式单独修 |
| 2026-03-29 | **#1/#14** 角色菜单授权：`formatTree` 后节点仅有 `value` 无 `id`，`expandMenuIdsWithAncestors` 误用 `n.id` 导致父链未补齐；改为 `menuTreeNodeId`（`value ?? id`）并修正「父子联动」检测逻辑 |
| 2026-03-29 | **#7** 混合布局下「AI 智能助手」误跳应用管理：**已验证解决**，BUG 表与排期已标注 |
| 2026-03-29 | **#1 / #14** 角色授权（回显、保存、菜单树）：**已验证解决**，BUG 表与排期已标注 |
| 2026-03-29 | 混合布局顶栏：点击目录重定向后菜单项 `:focus` 残留似悬浮背景 — `MixTopMenu` 在选中与 `router.push` 后 `blur`；**已验证解决** |
| 2026-03-29 | **#2** 左侧导航：`BasicMenu`/`MenuItem` 路径拼接实验（含 `normalizedLayoutBase` 等）引发回归，**已回退**至仓库原有 `resolveFullPath` + `resolvePath(child.path)` 实现 |
| 2026-03-29 | **#2** 再修：确认根因为「根项 basePath 重复拼段」；仅传布局基准 `normalizedLayoutBase`（空→`/`）+ 子级 `:base-path="resolvePath(item.path)"`，`resolvePath` 规范化并与 `activeMenuPath` 对齐 |
| 2026-03-29 | **#2** 三种布局菜单：**已验证解决**。最终方案：`MenuItem` 目录/叶子分流 index；`BasicMenu` 去 `route.path` 的 `el-menu` key、同步激活仅 `nextTick` 一次；`MixLayout` 侧栏 `mixSideMenuKey`；移除独立 `menu-path.ts`。目录 **redirect** 前后端必填保留。BUG 表、排期第二阶段与合并说明已同步 |
| 2026-03-29 | **#8 AI 附件**：**非缺陷**（当前模型不支持附件）；前端 `ChatInput` 关闭上传并提示「附件功能开发中」。BUG 表 **#8**、排期第二阶段与合并说明已同步 |
| 2026-03-29 | **#15 数据库分页**：系统模块、应用、代码生成业务表、工作流/节点/调度日志等列表改为 `CRUDBase.page`；`PaginationService` 仅保留于 Redis/文件/Inspector/Agno 等无法 SQL 分页场景；`request.PaginationService` 文档已注明适用范围 |
| 2026-03-29 | **#28 PG date 类型新增**：**已验证解决**；BUG 表与第一阶段排期已同步 |
| 2026-03-29 | **#24 登录慢（IP）**：``OperationLogRoute`` 写日志时尊重 ``LOGIN_RESOLVE_IP_LOCATION``，新增 ``IpLocalUtil.resolve_location_for_log`` 与 ``create_token`` 共用；BUG 表与第二阶段排期已同步 |