- 新人上手 §1:托管地址/clone 命令改 <GIT_HOST>:<OWNER> 占位,SSH 端口细节改「向负责人索取」 - 路线图/用户管理Delta/总览 三处历史记录行、.gitea/ci.yml 注释:host 名改「私有 Gitea/私有远程」 - 全仓 grep 验证零残留 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.0 KiB
5.0 KiB
新人上手 — 第一天路径
目标:半天内从零到「本地起全栈 + 登录看到真实页面 + 全量测试绿」。 遇到与本文不符的情况,以
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 三个仓到同一父目录(前后端脚本按兄弟目录相互引用):
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. 后端:构建 + 开发库 + 起服务
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
cd ../eip4-web
npm install
npm run dev # :5173,/api 反代 dev 后端 :8093(.env 已配)
浏览器 http://localhost:5173/login,dev 库账号 admin / 111111。
登录后随便开几个菜单(如 新闻管理/用户管理),列表能出数据即全链路通。
npx vitest run && npm run build # 前端测试 + 生产构建绿=环境 OK 第二证
4. 必读文档(按序,约 1-2 小时)
- 仓根
README.md— 模块地图、双层制纪律、三套 profile、JDK 红线 docs/架构设计.md— 双层制(保真层供奉/现代层生长)全部架构决策docs/迁移手册.md— 引擎坑位台账(§5 引擎行为契约最常用)docs/README.md— 全文档索引与状态分级(历史/归档文档勿据以判断进度)docs/项目进度与路线-总览-2026-06-21.md— 进度权威(A/B 矩阵 + 待拍板)- 仓根
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、不升版本。