121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# g3soft-erp
|
||
|
||
G3Soft ERP 前后端同仓。业务域：海运 / 空运 / 箱管 / 财务 / CRM。
|
||
|
||
> **当前状态：前端骨架已搭好并可运行；后端尚未开始。**
|
||
> 元数据驱动引擎（通用查询 / 保存 / 权限）**未开始设计**，属后续独立立项。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
g3soft-erp/
|
||
├── pnpm-workspace.yaml # 仓库唯一配置文件：overrides + allowBuilds
|
||
├── web/ # 前端应用（前端唯一的 package.json 在这里）
|
||
│ ├── package.json
|
||
│ ├── vite.config.ts
|
||
│ ├── vitest.config.ts
|
||
│ ├── tsconfig.json
|
||
│ ├── .oxlintrc.json
|
||
│ ├── .oxfmtrc.json
|
||
│ └── src/
|
||
├── server/ # 后端占位（Maven + Spring Boot，未开始）
|
||
├── docs/ # 设计文档
|
||
└── README.md
|
||
```
|
||
|
||
**根目录刻意不放 `package.json`** —— 前端可交付物只有 `web/` 一个包，那个 `package.json` 就是 `web/package.json`。根目录只有 `pnpm-workspace.yaml` 一个配置文件。
|
||
|
||
## 环境要求
|
||
|
||
- Node.js >= 20.19
|
||
- pnpm 11
|
||
- **`g3soft-libs` 需与 `g3soft-erp` 平级**（同在 `D:\workspace\code\` 下），因为 `overrides` 用相对路径 link 组件库
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1) 先构建组件库（@g3soft/ui 的 exports 指向 dist，必须先有产物）
|
||
cd ../g3soft-libs && pnpm --filter @g3soft/tokens build && pnpm --filter @g3soft/ui build
|
||
|
||
# 2) 回到本项目
|
||
cd ../g3soft-erp/web
|
||
pnpm install
|
||
pnpm dev # http://localhost:5090
|
||
```
|
||
|
||
> **命令都在 `web/` 下跑**，根目录没有 `package.json`，所以根目录敲不了 `pnpm dev`。
|
||
|
||
## 脚本（在 `web/` 下执行）
|
||
|
||
| 命令 | 说明 |
|
||
|---|---|
|
||
| `pnpm dev` | 开发服务器（端口 5090，`/api` 代理到 8088） |
|
||
| `pnpm build` | 类型检查 + 生产构建 |
|
||
| `pnpm typecheck` | 仅 `vue-tsc --noEmit` |
|
||
| `pnpm test` | Vitest |
|
||
| `pnpm lint` / `pnpm fmt` | oxlint / oxfmt |
|
||
| `pnpm check` | lint + fmt:check + build（提交前跑这个） |
|
||
|
||
## `@g3soft/ui` 接入方式
|
||
|
||
组件库的 `exports` 指向 `dist/`，所以**改完组件库必须重新 build**。
|
||
|
||
开发期通过 `pnpm-workspace.yaml` 的 `overrides` 指向本地包：
|
||
|
||
```yaml
|
||
overrides:
|
||
'@g3soft/tokens': link:../g3soft-libs/packages/tokens
|
||
'@g3soft/ui': link:../g3soft-libs/packages/ui
|
||
```
|
||
|
||
**三个注意点**：
|
||
|
||
1. **`overrides` 只在 workspace 根生效**，写在 `web/package.json` 里无效。
|
||
2. **`vite.config.ts` 必须保留 `dedupe: ['vue', ...]`**。link 进来的包会带自己的 Vue 副本，不去重会导致组件内响应式失效（组件内部 ref 变化不触发外部渲染）——link 方案最经典的坑。
|
||
3. **CI / 其他机器**：相对路径依赖目录层级。私库就绪后应把开发期 `link:` 换成私库版本号。
|
||
|
||
### 想要组件库热更新？
|
||
|
||
`link:` 指向**已构建的 `dist/`**，改源码不会即时生效。若要像 `g3soft-libs/docs` 那样直连源码，在 `vite.config.ts` 里加 alias：
|
||
|
||
```ts
|
||
resolve: {
|
||
alias: {
|
||
'@g3soft/ui': fileURLToPath(new URL('../../g3soft-libs/packages/ui/src/index.ts', import.meta.url)),
|
||
},
|
||
}
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `VITE_PROXY_TARGET` | `http://127.0.0.1:8088` | 开发环境 `/api` 代理目标 |
|
||
| `VITE_API_BASE` | `/api` | 接口基础路径 |
|
||
| `VITE_APP_TITLE` | `G3Soft ERP` | 应用标题 |
|
||
|
||
## 将来加 H5 端
|
||
|
||
**`@g3soft/ui` 只给 web 用，H5 不用。** 所以两端是基本独立的应用，只是碰巧同仓，**不需要抽任何共享层**。
|
||
|
||
加 H5 时的步骤：
|
||
|
||
1. 建 `h5/` 目录（与 `web/` 平级），它有自己的 `package.json`
|
||
2. `pnpm-workspace.yaml` 的 `packages` 改为 `['web', 'h5']`
|
||
3. 若 H5 也要用某个 g3soft 包，在 `overrides` 里加一条；不用就不用加
|
||
4. 各端独立构建、独立部署
|
||
|
||
## 仓库纪律（重要）
|
||
|
||
前后端同仓，但**必须各自独立**：
|
||
|
||
1. **独立构建** —— 前端 `pnpm build` 不管后端，后端 `mvn package` 不管前端，**任何一方都不触发另一方构建**（不要引入 `frontend-maven-plugin` 这类东西）。
|
||
2. **独立版本** —— tag 分开打（`web-v1.2.0` / `api-v1.2.0`）。
|
||
3. **唯一契约是 HTTP 接口** —— 前端不读后端源码，后端不管前端怎么调；契约写进 `docs/`。
|
||
|
||
破坏这三条，同仓的好处立刻变成耦合的代价。
|
||
|
||
## 相关仓库
|
||
|
||
- **`g3soft-libs`** —— `@g3soft/ui`（组件库）、`@g3soft/tokens`（设计变量）。web 端 UI 一律用组件库，不另起一套。
|