- 新人上手 §1:托管地址/clone 命令改 <GIT_HOST>:<OWNER> 占位,SSH 端口细节改「向负责人索取」 - 路线图/用户管理Delta/总览 三处历史记录行、.gitea/ci.yml 注释:host 名改「私有 Gitea/私有远程」 - 全仓 grep 验证零残留 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
87 lines
5.0 KiB
Markdown
87 lines
5.0 KiB
Markdown
# 新人上手 — 第一天路径
|
||
|
||
> 目标:半天内从零到「本地起全栈 + 登录看到真实页面 + 全量测试绿」。
|
||
> 遇到与本文不符的情况,以 `README.md`(仓根)+ `docs/架构设计.md` 为准并回改本文。
|
||
|
||
## 0. 前置软件
|
||
|
||
| 软件 | 版本 | 说明 |
|
||
|---|---|---|
|
||
| JDK | **21(硬性,严禁 26)** | `brew install openjdk@21`。保真层 Groovy 4.0.27 不认 JDK 26 字节码,服务流会批量 500(`scripts/run-dev.sh` 有守卫,详见仓根 README) |
|
||
| Node | 22+ | 前端 Vite + amis 本地 SDK |
|
||
| PostgreSQL | 15 | 本地 `localhost:5433`(惯例 `PGDATA=~/eip4-pgdata`,非 brew 默认);psql 查业务表先 `set search_path=eip3` |
|
||
| Maven | 3.9+ | 模块化构建注意:`mvn -pl <模块>` **必须加 `-am`** |
|
||
|
||
## 1. 取码
|
||
|
||
> ⚠️ **托管现状**:三仓目前在项目负责人的**私人 Git 托管**,**非团队基础设施**。
|
||
> 团队接手前需二选一:迁移到团队代码托管(届时本节地址与 CONTRIBUTING 的 CI 段随之更新),
|
||
> 或由仓主开通协作者账号。CI runner 也应部署在团队侧而非个人机器。
|
||
|
||
取码地址与账号**向项目负责人索取**(当前为私有 Gitea,SSH 走非标准端口,需在 `~/.ssh/config` 为该 Host 配 `Port`)。
|
||
clone 三个仓到同一父目录(前后端脚本按兄弟目录相互引用):
|
||
|
||
```bash
|
||
git clone <GIT_HOST>:<OWNER>/eip4-platform.git
|
||
git clone <GIT_HOST>:<OWNER>/eip4-web.git
|
||
git clone <GIT_HOST>:<OWNER>/amis-fork.git # 渲染 SDK 源,日常开发只读,可后取
|
||
```
|
||
|
||
## 2. 后端:构建 + 开发库 + 起服务
|
||
|
||
```bash
|
||
cd eip4-platform
|
||
mvn clean install # 全 reactor 构建+单测(首次较久);绿=环境 OK 第一证
|
||
bash tools/local-devdb/build_devdb.sh --drop-target
|
||
# 构建日常开发库 eip4dev(约 6 分钟,需内网可达客户库副本 192.168.20.68:5435)
|
||
mvn -pl platform-app,flowable-service -am package -DskipTests # 出可运行 jar
|
||
bash scripts/run-dev.sh both # platform :8093(dev profile) + flowable-service :8089
|
||
curl -s localhost:8093/v3/api-docs | head -c 80 # 健康判定用这个端点(返回 JSON 即活)
|
||
```
|
||
|
||
- 日志:`/tmp/eip4-platform.log`、`/tmp/eip4-flowable.log`。
|
||
- 不在内网/没有客户库副本:用 `deploy/` 的 compose 演示栈(见 `deploy/README.md`),或 local profile + `eip4m0` 极简自举集(CI/对拍口径,账号 alice/123456)。
|
||
- 三套 profile 的含义与端口:见仓根 `README.md`「三套 profile」表。
|
||
|
||
## 3. 前端:起 dev server
|
||
|
||
```bash
|
||
cd ../eip4-web
|
||
npm install
|
||
npm run dev # :5173,/api 反代 dev 后端 :8093(.env 已配)
|
||
```
|
||
|
||
浏览器 `http://localhost:5173/login`,**dev 库账号 `admin` / `111111`**。
|
||
登录后随便开几个菜单(如 新闻管理/用户管理),列表能出数据即全链路通。
|
||
|
||
```bash
|
||
npx vitest run && npm run build # 前端测试 + 生产构建绿=环境 OK 第二证
|
||
```
|
||
|
||
## 4. 必读文档(按序,约 1-2 小时)
|
||
|
||
1. 仓根 `README.md` — 模块地图、双层制纪律、三套 profile、JDK 红线
|
||
2. `docs/架构设计.md` — 双层制(保真层供奉/现代层生长)全部架构决策
|
||
3. `docs/迁移手册.md` — 引擎坑位台账(§5 引擎行为契约最常用)
|
||
4. `docs/README.md` — 全文档索引与状态分级(**历史/归档文档勿据以判断进度**)
|
||
5. `docs/项目进度与路线-总览-2026-06-21.md` — 进度权威(A/B 矩阵 + 待拍板)
|
||
6. 仓根 `CONTRIBUTING.md` — 分支/合并/提交/质量门约定
|
||
|
||
## 5. 高频坑(前人真踩过的)
|
||
|
||
- **fat jar 不重打**:改代码后 `mvn -pl platform-app -am package` 若行为没变,加 `clean` —— 增量打包可能没把改动打进 fat jar。
|
||
- **`mvn -pl` 忘 `-am`**:兄弟模块改动没被一起构建,报旧类错误。
|
||
- **前端页面卡死/转圈**:先杀孤儿 vite 进程(端口会漂 5173→5176…),再 `rm -rf node_modules/.vite` 清 pre-bundle 缓存重起。
|
||
- **psql 查不到表**:业务 schema 是 `eip3`,先 `set search_path=eip3`。
|
||
- **登录接口取 token**:`POST /api/auth/login` 的 token 在响应**顶层** `token` 字段;引擎主键 CHAR 补白,比对/传参前 `trim`。
|
||
- **改转换器不生效**:转换器产物落 `sys_page_schema`,改完须**重转重导**(BatchConvertCli + SchemaImportCli)运行库才变。
|
||
- **CRLF + tab 的老文件**:别用 sed 改,用 python 脚本改(保字节格式)。
|
||
|
||
## 6. 红线(越线=返工)
|
||
|
||
- 保真层 `com.dsasp.*` **只移植不重写**、不改包名(ArchUnit 强制现代层→保真层单向依赖)。
|
||
- 引擎 DDL 只走守卫单点(`AlterTableSqlGuard`/`CreateTableSqlGuard`/`DropTableSqlGuard`),禁裸 JDBC DDL。
|
||
- Flowable `databaseSchemaUpdate=false`,严禁引擎自动改表。
|
||
- AI 产物终点恒人审(`READY_FOR_HUMAN_REVIEW`),平台不内置生成 LLM;**对外严禁承诺「AI 全自动开发」**。
|
||
- amis 锁 6.13.0 本地 SDK,不依赖 CDN、不升版本。
|