顶层目录

legendary-invention/
├── frontend/                  前端工程
├── services/                  后端模块
├── libs/                      公共基础库与跨模块契约
├── deploy/                    Docker Compose、Nginx、观测配置
├── scripts/                   启停、部署、检查脚本
├── docs/                      原始设计文档与架构说明
└── database/                  数据库相关资源

怎么读这个仓库最不容易迷路

第一次进入仓库时，建议不要按“哪个目录最大先看哪个”来读，而是按下面这条路径建立心智模型：

  1. 先看 README.md，确认当前运行形态

  2. 再看 services/legendary-server/，理解后端真实启动入口

  3. 然后看 frontend/，理解前端如何通过 /api 接入后端

  4. 再看 services/*-service 和 libs/*，理解模块边界和契约位置

  5. 最后看 deploy/、scripts/、docs/，理解发布与历史设计

这样读，你会更容易区分“当前生效的东西”和“为未来拆分预留的东西”。

前端目录

  • frontend/src/layouts/：壳层布局

  • frontend/src/pages/：业务页面

  • frontend/src/services/：请求封装与接口类型

  • frontend/src/auth/：认证、会话、登录态恢复

  • frontend/src/features/：页面级通用能力

  • frontend/src/theme/：主题、视觉令牌、反馈桥接

前端建议按三层来理解：

  • 壳层：布局、导航、用户菜单、全局抽屉、系统级交互

  • 基础能力层：请求、认证、权限、响应式、hooks、通用组件

  • 业务页面层：真正承载列表、表单、详情、配置页

后端目录

  • services/legendary-server/：正式运行入口，聚合全部模块

  • services/auth-service/：登录、刷新、Passkey、微信登录

  • services/system-service/：系统控制面、IAM、菜单、配置、AI、审计

  • services/file-service/：文件、图片、存储空间、上传校验

  • services/message-service/：站内信、WebSocket 推送、消息 outbox

  • services/plugin-service/：插件管理与插件运行时

  • services/localization-service/：多语言内容管理

  • services/job-executor/：XXL-JOB 执行器

后端最重要的阅读原则是：运行入口和代码 owner 不是一回事。

  • 看启动方式、健康检查、容器编排时，以 legendary-server 为准

  • 看业务归属、数据库 owner、权限边界时，以具体 *-service 模块为准

公共库

  • libs/common-core：异常、错误码、基础常量

  • libs/common-web：统一响应、全局异常、Web 基础约定

  • libs/common-security：安全上下文、权限、JWT 通用能力

  • libs/legendary-api：跨模块 API 契约

这些公共库的意义，是把“所有模块都会反复用到，但不应该重复实现”的东西收敛起来。常见包括：

  • 统一响应模型

  • 通用异常体系

  • 安全上下文与当前用户

  • 跨模块 API 契约

  • 插件或平台级公共接口

基本理解方式

  • 看“运行形态”时，以 legendary-server 为准

  • 看“代码边界”时，以 services/*-service 和 libs/* 为准

  • 看“生产发布”时，以 deploy/ 和 scripts/ 为准

  • 看“历史设计决策”时，再去翻 docs/

值得重点关注的几个目录

deploy/

这里放的是现在真正影响线上部署的文件：

  • docker-compose.prod.yml

  • .env

  • Nginx 配置

  • 观测配置

  • 备份恢复脚本

scripts/

这里决定了你日常怎么启动、停止、部署、检查系统，通常比手工敲一长串命令更值得优先读。尤其是：

  • start-platform.mjs

  • stop-platform.mjs

  • deploy-container.mjs

  • check-deployment.mjs

  • install-platform.mjs

docs/

这里是原始设计资料库，不一定每一份都代表当前最新运行形态，但它对理解以下主题仍然很有价值：

  • 数据模型与 RBAC

  • 前端架构

  • 模块边界

  • Outbox 事件

  • 部署与运维手册

开发中的边界规则

  • 不要让页面直接拼接后端域名

  • 不要让 controller 直接操作 mapper

  • 不要跨模块直接读写别人 owner 的表

  • 新增能力时，先明确 owner，再决定代码放哪里

新人最容易搞混的三组概念

1. frontend/ 和 deploy/

frontend/ 负责应用本身，deploy/ 负责应用怎么被运行起来。前者是业务实现，后者是交付方式。

2. services/legendary-server/ 和 services/*-service/

前者是运行入口，后者是模块边界。不要因为只启动一个入口，就把所有业务继续往一个模块里堆。

3. libs/* 和“随便跨模块调用”

有公共库，不代表所有代码都应该进公共库。只有真正跨模块稳定复用、并且值得被抽象的能力，才应该沉淀到 libs/*。