Files
eip4-platform/docs/新人上手.md
zhengwr 2f97124ba1 docs: 新人上手一页纸 + CONTRIBUTING 协作约定(团队接手准备)
- docs/新人上手.md:第一天路径(前置软件/取码/构建/eip4dev/起服务/前端/必读序/高频坑/红线)
- CONTRIBUTING.md:分支命名/--no-ff 合并/提交格式/质量门(TDD+全 reactor 绿+作者评审分离+转换器重转重导)/CI 现状/文档归档纪律(两仓通用)
- docs/README.md §2 登记两份新文档

配套(仓外):工作区根 README 刷新至 07-02(原停 06-11);eip4-web README 联调指引修正另仓提交;两仓本地已合并分支清理(platform 40/web 7,含 ai-agent worktree)+远端 8 个已合并分支删除

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

83 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 新人上手 — 第一天路径
> 目标:半天内从零到「本地起全栈 + 登录看到真实页面 + 全量测试绿」。
> 遇到与本文不符的情况,以 `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. 取码
Gitea:`https://git.latent.chat`(**SSH 端口 2222**,`~/.ssh/config` 里给该 Host 配 `Port 2222`)。
clone 三个仓到同一父目录(前后端脚本按兄弟目录相互引用):
```bash
git clone git.latent.chat:zhengweirong/eip4-platform.git
git clone git.latent.chat:zhengweirong/eip4-web.git
git clone git.latent.chat:zhengweirong/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、不升版本。