Files
eip4-platform/docs/新人上手.md
zhengwr dd3b048899 docs: 清除私有托管地址,改中性表述(取码地址向负责人索取)
- 新人上手 §1:托管地址/clone 命令改 <GIT_HOST>:<OWNER> 占位,SSH 端口细节改「向负责人索取」
- 路线图/用户管理Delta/总览 三处历史记录行、.gitea/ci.yml 注释:host 名改「私有 Gitea/私有远程」
- 全仓 grep 验证零残留

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 08:29:30 +08:00

5.0 KiB
Raw Permalink Blame History

新人上手 — 第一天路径

目标:半天内从零到「本地起全栈 + 登录看到真实页面 + 全量测试绿」。 遇到与本文不符的情况,以 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 小时)

  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、不升版本。