项目架构说明

这份说明描述的是当前 ALIAPI Web Monorepo 的整体结构、模块边界、数据流和部署方式，目的是让新成员能快速定位代码，并避免把职责写乱。

总览

项目采用 pnpm workspace + Turbo 管理多个前端应用和共享包，核心技术栈是：

• React Router
• Vite
• TypeScript
• Tailwind CSS
• shadcn/ui

仓库当前的主要交付对象有 3 个：

• apps/portal：面向外部用户的业务门户
• apps/admin：面向内部团队的管理后台
• apps/docs：项目文档站和组件说明站

共享能力沉淀在 packages/ 下，优先复用，不建议在应用里复制实现。

代码分层

应用层

apps/portal 和 apps/admin 都是独立的 React Router 应用，目录结构保持一致，便于共享模式和迁移。

应用层主要负责：

• 路由编排
• 页面组合
• 表单和交互逻辑
• 页面级状态管理
• 接口适配

应用层不负责沉淀通用 UI，也不直接承载跨应用工具。

共享组件层

packages/ui 是统一 UI 组件库，承载基础组件和复合组件。

约定是：

• 页面里优先从 @realtech/ui/* 引用
• 如果缺组件，先补到 packages/ui
• 不要在 apps/* 里重复拷贝 shadcn 组件

工具层

packages/utils 放跨应用纯工具，例如公共 fetch 封装、通用序列化逻辑等。

它的原则是：

• 不依赖具体页面
• 不包含业务流程
• 不持有 UI 状态

文档层

apps/docs 用于解释项目约定、组件使用方式和工程知识。

它的作用不是展示业务功能，而是沉淀：

• 架构说明
• 组件规范
• 开发指南
• 部署和环境说明

目录职责

apps/
  portal/   外部用户门户
  admin/    内部管理后台
  docs/     文档站
packages/
  ui/       共享 UI 组件
  utils/    共享工具
  pro-table/表格能力封装
  tiptap/   富文本相关封装
  cli/      命令行工具

apps/portal

门户端负责对外用户能直接接触到的功能，例如：

• 登录和注册
• 个人中心
• 模型广场
• 业务查询和操作页面

这里的页面通常会组合：

• app/routes/ 中的路由页面
• app/components/ 中的页面级组件
• app/lib/ 中的接口适配层
• @realtech/ui 提供的通用组件

apps/admin

管理端面向内部运营和管理使用，结构与 portal 基本一致，但页面职责不同。

这里通常承载：

• 配置管理
• 模型管理
• 权限和组织管理
• 数据查看和运营后台能力

apps/docs

文档站用于对外说明项目结构和开发约定，目前包含：

• 快速开始
• 路由与布局
• 数据流和状态管理
• 环境变量
• 部署方式
• 项目配置

核心数据流

请求链路

业务页面不直接调用裸 fetch，而是走应用适配层：

页面 -> app/lib/realapi-request.ts -> packages/utils/fetch.ts -> 后端接口

这样做的目的有三个：

• 把鉴权和 token 注入收口
• 统一错误处理
• 让不同应用只保留环境差异

状态流

项目里存在两类状态：

• 局部 UI 状态：例如弹窗、表单、筛选条件
• 跨组件共享状态：例如登录态、主题、轻量页面状态

一般原则是：

• 局部状态优先放在组件内
• 轻量共享状态可用 Jotai 等工具
• 不要把能局部处理的状态抬到全局

路由与布局

apps/portal 和 apps/admin 使用基于文件的路由组织方式，页面通常按业务域分组。

典型结构是：

app/routes/
  (admin)/
  (aliapi)/
  (external)/

路由分组的作用是：

• 让布局复用更清晰
• 隔离不同业务域
• 保持 URL 结构和视觉布局解耦

布局通常分为三层：

• 根布局：注入全局 provider、主题、国际化
• 业务布局：侧边栏、顶栏、导航壳
• 页面布局：具体页面内部的卡片、表单、表格

UI 规范

项目的 UI 约束比较明确：

• 优先使用 @realtech/ui
• 新组件优先下沉到 packages/ui
• 页面层不要直接拼装过多样式原子类
• 颜色和背景应使用主题 token

这保证了 portal、admin、docs 三个入口在视觉和交互上保持一致。

构建与部署

根目录部署脚本是：

./deploy-frontends.sh

它会做这些事：

1. 本地构建各前端应用
2. 把产物同步到服务器
3. 在远端重新构建静态 nginx 镜像
4. 重启 realapi-web 容器
5. 重载 edge nginx

当前对外部署地址是：

• Portal: https://limapi.com/
• Admin: https://limapi.com/admin
• Docs: https://limapi.com/docs

维护建议

• 新增 UI 先检查 packages/ui 是否已有可复用实现
• 新增请求先检查 packages/utils/fetch.ts 是否足够扩展
• 业务代码尽量不要引用跨应用私有实现
• 页面逻辑、接口适配、通用组件要保持边界清晰

如果后续架构继续演进，建议把更稳定的约定拆成单独的 reference 文档，例如：

• 认证与登录态
• 接口分层
• 权限模型
• 路由规范