# lambda-fusion-web

**Repository Path**: westboy/lambda-fusion-web

## Basic Information

- **Project Name**: lambda-fusion-web
- **Description**: Lambda Fusion 配套前端项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 3
- **Created**: 2025-08-01
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Lambda Fusion 前端开发指南（使用导向）

本 README 重点回答三个问题：

- 🏃 如何在本地跑起来？
- 🎯 新功能应该写在哪里？
- 🛡️ 如何保证变更可维护、可上线？

---

## 1. ⚡ 快速开始

### 1.1 📦 环境要求

- Node.js `>=20.19.0`
- pnpm `>=10.0.0`

### 1.2 ⚙️ 安装与启动

在 `lambda_fusion_web` 根目录执行：

```bash
pnpm install
pnpm dev:tdesign
```

默认开发代理配置见 [vite.config.mts](./apps/web-tdesign/vite.config.ts)。

移动端 H5 使用独立 AI 应用壳：`pnpm --filter @vben/web-tdesign-ai dev`（默认端口 5777）。

- 桌面发布入口：`/app/:publishCode`；移动端专用入口：`/m/app/:publishCode`。管理端宿主与独立 AI 宿主均提供这两个入口，使用同一宿主地址即可沿用其当前登录态。生产环境若使用 hash 路由，路径位于 `/#/` 之后。
- 管理端「对话体验」的应用选择器下提供「移动端预览」，可使用当前登录态验证移动端组件；正式 H5 入口仍须通过发布校验。
- 移动页保留发送、停止、附件、会话记录、结果卡及必要的人机确认；回复下方使用无边框的「复制 / 更多」操作行，反馈和重新回答放在底部菜单，旧回复不提供重新回答；模型选择位于输入栏的更多选项中。
- 移动页复用当前 H5 登录态。无凭据或失效时展示重新连接入口，并向当前窗口发出不携带凭据的 `lambda-fusion:auth-required` 事件，由宿主完成认证后重新连接；页面离开不调用共享账号登出接口。
- App、小程序存储与 H5 存储不假定互通。下游复用源码时，通过 `provideAiContext` 注入同一凭据来源的请求客户端和 `tokenProvider`，Token 不通过 URL 传递。

`MobileChatWorkspace` 已从 `@vben/ai-ui` 导出。自有宿主在完成应用访问校验后传入应用视图，并处理组件的 `authRequired` 事件：

```vue
<MobileChatWorkspace :app="authorizedApp" @auth-required="requestHostLogin" />
```

`requestClient` 和 SSE 使用的 `tokenProvider` 必须读取同一份当前凭据。默认独立 H5 应用和管理端采用不同的缓存命名空间，不能把在 5999 登录等同于在 5777 已登录。

### 1.3 ⌨️ 常用命令

```bash
pnpm dev:tdesign
pnpm --filter @vben/web-tdesign typecheck
pnpm lint
pnpm build:tdesign
```

---

## 2. 🏗️ 项目结构与职责

```text
lambda_fusion_web/
├─ apps/web-tdesign        # 应用壳：启动、路由、鉴权、布局、业务编排
└─ packages/system-ui      # 模块层：系统管理页面、API、适配器、字典能力
```

- `apps/web-tdesign` 负责“运行时入口与体验”。
- `packages/system-ui` 负责“可复用系统能力”。

启动注入关系见 [bootstrap.ts](./apps/web-tdesign/src/bootstrap.ts)：应用会调用 `setSystemRequestClient(requestClient)`，把请求能力注入 system-ui 模块。

---

## 3. 🎯 新功能应该写在哪里

这是最常见问题，按下面规则判断.

### 3.1 📏 决策规则

- **仅当前应用使用的页面/流程**：写在 `apps/web-tdesign/src/**`
- **系统管理通用能力（可复用）**：写在 `packages/system-ui/src/**`
- **接口调用逻辑**：
  - 应用级接口：建议新增到 `apps/web-tdesign/src/api/custom/**`，避免直接改动 `core/**`
  - 系统模块接口：`packages/system-ui/src/api/system/**`
- **组件库适配相关**：`apps/web-tdesign/src/adapter/**` 或 `packages/system-ui/src/adapter/**`
- **登录、鉴权、会话生命周期**：优先落在 `apps/web-tdesign/src/store/auth.ts` + `src/router/**`

### 3.2 💡 典型场景落点

- **新增业务看板模块（如统计卡片、趋势图、筛选器）**
  - 页面：建议新增 `apps/web-tdesign/src/views/dashboard/custom-overview.vue`
  - Store：建议新增 `apps/web-tdesign/src/store/dashboard-custom.ts`
  - API：建议新增 `apps/web-tdesign/src/api/custom/dashboard.ts`

- **新增“系统管理”页面（如租户扩展、角色扩展）**
  - 页面：`packages/system-ui/src/views/system/**`
  - API：`packages/system-ui/src/api/system/**`
  - 如需后端菜单映射：确认 `systemPageMap` 可解析对应 component 路径，见 [page-map.ts](./packages/system-ui/src/page-map.ts)。

- **新增全局请求处理（统一报错、token策略）**
  - `apps/web-tdesign/src/api/request.ts`

---

## 4. 🛠️ 推荐开发流程

### 4.1 📝 实现顺序

1. 定义 API 类型与请求函数
2. 实现页面/组件交互
3. 接入 store（如需跨页面状态）
4. 补齐路由与权限（如需菜单可见）
5. 本地验证 lint/typecheck

### 4.2 ✅ 合并前检查项

- 类型检查通过：`pnpm --filter @vben/web-tdesign typecheck`
- 代码风格通过：`pnpm lint`
- 新增接口是否已加类型定义
- 新增页面是否符合目录分层（应用层 vs 模块层）

---

## 5. 🔍 关键代码入口（建议先读）

- 应用启动：[main.ts](./apps/web-tdesign/src/main.ts)
- 应用装配：[bootstrap.ts](./apps/web-tdesign/src/bootstrap.ts)
- 路由守卫：[guard.ts](./apps/web-tdesign/src/router/guard.ts)
- 动态路由生成：[access.ts](./apps/web-tdesign/src/router/access.ts)
- 请求封装：[request.ts](./apps/web-tdesign/src/api/request.ts)
- 登录会话：[auth.ts](./apps/web-tdesign/src/store/auth.ts)
- system-ui 入口：[index.ts](./packages/system-ui/src/index.ts)
- system-ui 请求注入：[request.ts](./packages/system-ui/src/api/request.ts)

---

## 6. 🤝 当前约定（请保持）

- 路由组件映射必须合并 `systemPageMap`，否则后端系统菜单可能无法解析组件。
- system-ui 不直接依赖具体请求实例，统一通过注入获取。
- 新增系统管理能力优先放 `packages/system-ui`，避免长期耦合在 app 内。