From 5e3362e2b0b089f2313ec5d5f91338cf1c059c6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Sun, 22 Nov 2026 19:18:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(dev):=20=E8=A1=A5=E5=85=85=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E4=B8=8E=E6=B5=8B=E8=AF=95=E7=8E=AF=E5=A2=83=E6=8C=87?= =?UTF-8?q?=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从 README 提供依赖、前后端启动、测试命令和非生产 RDS 准备步骤。已在独立 QA 检出通过 make verify,Vite 健康代理和 Chromium 页面冒烟通过。 --- README.md | 12 +--- docs/DEVELOPMENT_AND_TESTING.md | 106 ++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 11 deletions(-) create mode 100644 docs/DEVELOPMENT_AND_TESTING.md diff --git a/README.md b/README.md index 4d8c0b2..b524e4b 100644 --- a/README.md +++ b/README.md @@ -109,17 +109,7 @@ IT、行政等是待扩展的业务资料范围,不是已经完成的新连接 ## 开发与 CI -开发环境使用 Go 1.26、Node.js 22、npm 和 Python 3。前端可独立开发。先准备一个获准用于开发的测试治理 API,在开发机的 `localhost:8088` 上确认 `/health` 可达。Vite 按仓内配置将 `/api` 和 `/health` 转给该地址,浏览器中的操作会作用于所连的环境。 - -```bash -# 仓库根目录,检查测试后端及前端依赖,再启动开发页面 -curl -fsS --max-time 5 http://localhost:8088/health -cd web -npm ci -npm run dev -- --host 127.0.0.1 -``` - -打开 Vite 打印的地址。修改组件后运行 `npm test` 和 `npm run build`。后端改动在仓库根目录用 `go test ./internal/httpapi` 这类按包测试缩小范围,再运行下方完整门禁。涉及持久化的联调使用独立测试 RDS 逻辑库,启动 API 或 worker 前核实库名和迁移版本。真实页面的通过条件见[运维手册](docs/OPERATIONS_RUNBOOK.md#开发测试和现场验收)。 +本机和 QA 虚拟机的依赖安装、前后端启动、测试命令及 PostgreSQL 测试库准备见 [开发与测试指南](docs/DEVELOPMENT_AND_TESTING.md)。 ```bash make verify # 完整检查入口:本地与 CI 使用同一套规则 diff --git a/docs/DEVELOPMENT_AND_TESTING.md b/docs/DEVELOPMENT_AND_TESTING.md new file mode 100644 index 0000000..97266cb --- /dev/null +++ b/docs/DEVELOPMENT_AND_TESTING.md @@ -0,0 +1,106 @@ +# 知识治理平台开发与测试 + +以下命令从仓库根目录运行。日常开发可在 Ubuntu 宿主进行,指定提交的回归在 `hifox-qa` 的独立检出中运行。部署到阿里云测试服后的验收按 [操作 Runbook](OPERATIONS_RUNBOOK.md) 和 [用户流程验收](USER_FLOWS_ACCEPTANCE.md) 执行。 + +## 1. 检出代码与安装依赖 + +准备 Git、Make、Python 3、Go 1.26(含同一工具链的 `gofmt`)、Node.js 22 和 npm。数据库检查另需 PostgreSQL 客户端 `psql`。首次安装依赖需要能访问 Go 和 npm 的依赖源。 + +```bash +# QA 在独立克隆中拉取提测分支,使用提测记录里的完整提交 SHA +export KG_TARGET_BRANCH='<提测分支名>' KG_TARGET_SHA='<完整提交 SHA>' +git fetch origin "$KG_TARGET_BRANCH" && git switch --detach "$KG_TARGET_SHA" && + test "$(git rev-parse HEAD)" = "$KG_TARGET_SHA" && test -z "$(git status --porcelain)" +# 上面的命令链若失败,先解决检出或工作区问题再继续 + +# 检查当前 shell 的工具链,非交互任务也应设置相同的 PATH +export PATH="$(go env GOROOT)/bin:$PATH" +go version +command -v gofmt +node --version +npm --version +python3 --version +make deps-install +``` + +`make deps-install` 通过 `go mod download` 和 `npm ci` 安装依赖。Go 依赖由 `go.mod` / `go.sum` 约束,前端由 `web/package-lock.json` 锁定。依赖安装失败时先检查工具链、依赖源和锁文件,避免临时改写清单来绕过问题。 + +## 2. 准备开发和测试数据库 + +无库检查可直接跳到第 4 节。启动 API 或执行真库测试前,由数据库管理员在**非生产 PostgreSQL RDS** 上预建专用空库和登录角色。建议分配 `kg_qa_app` 给应用冒烟,`kg_qa_it` 给 Go 集成测试,各用独立角色。开发宿主另用开发专用库,避免与 QA 共享数据。库未分配时先申请,启动流程以库已存在为前提。 + +| 用途 | 所需权限 | 数据初始化 | +| --- | --- | --- | +| 应用启动与 UI 冒烟 | `CONNECT`,以及目标 schema 内的 `USAGE`、`CREATE` 和对应用对象的读写权限。迁移角色须能修改自己创建的对象。 | 首次 API 启动执行仓库内嵌迁移。用户表为空时创建初始管理员,首次登录必须修改密码。初始口令通过测试环境负责人交接。 | +| Go PostgreSQL 集成测试 | `CONNECT` 和目标测试库的 `CREATE` 权限,用于建立各用例自己的 schema。 | 用例创建隔离 schema、执行迁移、写入测试数据并清理。相同测试不要并发指向同一个库,避免固定 schema 名冲突。 | + +两类角色均只授予对应非生产库所需的权限。使用空库和合成数据。密码由操作者在目标机配置到权限为 `0600` 的 PostgreSQL passfile,条目按 `host:port:database:user:password` 填写。使用 RDS CA 校验证书。以下命令先读回实际数据库、角色与 TLS 状态,核对三者再启动 API 或运行真库测试。 + +```bash +# 用获准的 RDS 主机名、端口、库名、角色和文件路径替换示例值 +export PGHOST='<非生产 RDS 主机名>' PGPORT=5432 +export PGDATABASE=kg_qa_app PGUSER=kg_qa_app +export PGPASSFILE="$HOME/.config/knowledge-governance/qa.pgpass" +export PGSSLROOTCERT="$HOME/.config/knowledge-governance/rds-ca.pem" +export PGSSLMODE=verify-full PGCONNECT_TIMEOUT=5 +psql -X -v ON_ERROR_STOP=1 -c \ + 'SELECT current_database(), current_user, ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid();' +``` + +如果是云厂商提供的私网地址,先确认执行机通过获准的网络路径可访问 RDS。库名、角色、TLS、连接权限或迁移权限有问题时,先交由环境负责人核对配置。实例上已有数据的库不能当作空库初始化。 + +## 3. 启动后端和前端 + +**终端 A,启动 API。** 在干净 shell 中执行第 2 节的应用库配置和连通性检查。使用独立测试配置,不加载现网 `.env`。 + +```bash +export DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslmode=verify-full&connect_timeout=5" +export APP_ADDR=127.0.0.1:8088 +export TEST_WEKNORA_ENABLED=false PP_SCAN_ENABLED=false +export RELEASE_WORKER_ENABLED=false PRODUCTION_RELEASE_REQUESTS_ENABLED=false +export DOBOTAI_OPS_READ_ENABLED=false DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED=false +go run ./cmd/api +``` + +API 会在监听前连接 PostgreSQL、应用迁移并初始化管理员。Web 页面和同步 API 联调只需运行 API 与 Vite。需要验证后台队列时,另用相同的隔离应用库配置启动普通 worker(`go run ./cmd/worker`)。涉及取件或来源刷新的任务还依赖容器内 `/app/scripts` 及获准的来源接线,按部署说明准备。发布 worker 无需启动。 + +Vite 通过 `localhost:8088` 转发 `/api` 和健康检查。如果 `8088` 已被其他部署占用,使用端口空闲的 QA 虚拟机运行本节。仅改前端时,可复用一个获准联调的测试 API,但需要先确认 `localhost:8088/health` 可达,并核对该地址指向的环境。 + +**终端 B,启动 Web。** + +```bash +npm --prefix web run dev -- --host 127.0.0.1 --port 5173 --strictPort +``` + +在运行服务的机器打开 `http://127.0.0.1:5173/`。另开终端检查 API 与前端代理,再复查迁移记录。最后一条命令需要第 2 节的应用库配置。 + +```bash +curl --fail --silent --show-error http://127.0.0.1:8088/health +curl --fail --silent --show-error http://127.0.0.1:5173/health +psql -X -v ON_ERROR_STOP=1 -c \ + 'SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1;' +``` + +空库首次启动后,用专用测试账号登录,按当次验收标准验证页面及接口。联调结束在两个终端按 `Ctrl+C` 停服务,数据库由环境管理员按测试数据保留规则管理。 + +## 4. 选择测试命令 + +| 目的 | 命令 | +| --- | --- | +| 查看检查及适用范围 | `make list` | +| 后端包测试 | `make tests-go` | +| 单个 Go 包及相关子包 | `go test -count=1 ./internal/httpapi/...` | +| 前端 Vitest 套件 | `make tests-web` | +| 单个前端测试文件 | `npm --prefix web test -- src/App.test.tsx` | +| 完整提交前检查,与 CI 共用入口 | `make verify` | + +`make verify` 包含安装、格式、静态检查、构建、测试、版本和安全检查,并写出 `ci-report.json`。在未导入真库测试配置的 shell 中运行。若检出时用了 `--no-tags`,先执行 `git fetch --tags origin`,以便版本检查读取正式标签对应的提交。依赖安装与安全检查需要相应网络或缓存。允许跳过的外部依赖用例见 [test-scope.json](../scripts/test-scope.json),真库测试应单独执行并记录结果。 + +在应用冒烟之外验证真实 PostgreSQL 行为时,重新按第 2 节切换并核对 **集成测试库和角色**,然后执行目标用例。下面以 UI 设置版本切换用例为例。 + +```bash +TEST_DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslmode=verify-full&connect_timeout=5" \ + go test -count=1 -v ./internal/platform/postgres -run '^TestUISettingsActivationRetiresPreviousRevisionIntegration$' +``` + +检查输出出现目标用例的 `PASS`。用例被跳过或没有匹配时,应补齐配置或纠正用例名后重跑。前端 Vitest 负责组件与业务逻辑检查,浏览器 E2E 应单独执行并按 Feature 保存证据。提测记录至少包括完整提交 SHA、执行命令、退出码,以及失败用例的日志或浏览器截图。