From 2f97124ba1b96ff4a3f33a41dcd8e2d8960de408 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Thu, 2 Jul 2026 08:15:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E4=BA=BA=E4=B8=8A=E6=89=8B?= =?UTF-8?q?=E4=B8=80=E9=A1=B5=E7=BA=B8=20+=20CONTRIBUTING=20=E5=8D=8F?= =?UTF-8?q?=E4=BD=9C=E7=BA=A6=E5=AE=9A(=E5=9B=A2=E9=98=9F=E6=8E=A5?= =?UTF-8?q?=E6=89=8B=E5=87=86=E5=A4=87)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CONTRIBUTING.md | 38 ++++++++++++++++++++++ docs/README.md | 2 ++ docs/新人上手.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/新人上手.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9e86f3f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,38 @@ +# 贡献约定(eip4-platform / eip4-web 通用) + +> 新人先读 `docs/新人上手.md`(环境)与 `docs/架构设计.md`(红线)。本文只讲协作流程。 + +## 分支与合并 + +- **main 不直接提交功能代码**;从 main 拉分支,前缀语义:`feat/`、`fix/`、`docs/`、`chore/`、`deploy/` + 短横线主题(如 `feat/approval-closure`)。 +- 完成后 **`--no-ff` 合回 main 并 push**(保留合并节点,按批次可回溯),或走 Gitea Web UI 发 PR。合并后**删除本地/远端特性分支**。 +- 一个分支一个主题;跨仓联动改动(platform+web)用同名分支便于对照。 + +## 提交信息 + +- 格式:`type(scope): 中文摘要`(如 `fix(report): 套打打印按选中行主键直接渲染`)。 +- 正文写清:做了什么 / 为什么 / **验证证据**(单测数、live e2e 结论)。没验证的事不写「已完成」。 + +## 质量门(合并前自查清单) + +1. **TDD**:新功能/修 bug 先写测试看它红,再实现变绿;禁止事后补「恒绿」测试。 +2. **后端**:改动模块 `mvn -pl <模块> -am test` 绿;合并前全 reactor `mvn clean install` 绿(含 ArchUnit 边界规则)。 +3. **前端**:`tsc -b` 干净 + `npx vitest run` 绿 + `npm run build` 成功。 +4. **作者/评审分离**:合并前过一遍独立 code review(他人或 agent 对抗评审);涉及鉴权/SQL/脚本执行/DDL 的改动**必须加安全评审**。 +5. **转换器改动**:重转重导后在运行库 live 验证(浏览器真渲染,不止单测),再合并。 +6. **保真层改动**:默认禁止重写;确需改(如安全修)须登记 `docs/迁移手册.md` 并跑对拍回归。 + +## CI + +- `.gitea/workflows/ci.yml`(构建+测试)与 `parity-nightly.yml`(夜间对拍)已就位,**待 Gitea 注册 act_runner 后生效**。 +- runner 生效前,合并到 main 前请手跑 `bash scripts/ci.sh` 等价把关。 + +## 文档纪律 + +- 进度只回写 `docs/项目进度与路线-总览-*.md`(唯一权威);README 索引随之更新。 +- 一次性 plan/报告完成后 `git mv` 入 `docs/归档/`,并同步改所有引用路径(grep 验证零断链)。 +- 文档声明「已完成」必须附 git 证据(commit/merge 哈希)。 + +## 红线速查(详见 docs/架构设计.md 与 docs/新人上手.md §6) + +JDK 21(严禁 26)|保真层不重写不改包名|DDL 走守卫单点|Flowable 不自动改表|AI 恒人审、对外严禁承诺全自动开发|amis 锁 6.13.0 本地 SDK。 diff --git a/docs/README.md b/docs/README.md index 0653be8..ad73894 100644 --- a/docs/README.md +++ b/docs/README.md @@ -68,6 +68,8 @@ | 文档 | 用途 | |---|---| | **`项目进度与路线-总览-2026-06-21.md`** | **全项目进度权威**:A/B 矩阵 + 增量交付 + 下一步 + 待拍板决策 | +| `新人上手.md` | 新成员第一天路径(环境→起服务→验证→必读序→高频坑→红线) | +| `../CONTRIBUTING.md` | 分支/合并/提交/质量门/文档纪律约定(两仓通用) | | `架构设计.md` | 双层制架构 / 工程结构 / 选型 / 红线(架构基线) | | `迁移手册.md` | 双层制纪律 + 踩坑四栏制(知识转移手册) | | `plans/2026-06-19-EIP4开发平台-架构方向-design.md` | 开发平台方向级 design(锁定 D1-D7) | diff --git a/docs/新人上手.md b/docs/新人上手.md new file mode 100644 index 0000000..90051f7 --- /dev/null +++ b/docs/新人上手.md @@ -0,0 +1,82 @@ +# 新人上手 — 第一天路径 + +> 目标:半天内从零到「本地起全栈 + 登录看到真实页面 + 全量测试绿」。 +> 遇到与本文不符的情况,以 `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、不升版本。