From 1adbd6c04c6ae495092df8c6f8e11f2fdb8f38a5 Mon Sep 17 00:00:00 2001 From: fengruixiang <474182370@qq.com> Date: Wed, 4 Nov 2026 19:30:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(local-dev):=20aml-local-refresh=20?= =?UTF-8?q?=E8=A1=A5=E5=85=85=E8=81=94=E8=B0=83=E7=9B=91=E6=8E=A7=E4=B8=8E?= =?UTF-8?q?=E7=A7=9F=E6=88=B7=E8=B4=A6=E5=8F=B7=E7=BB=8F=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 宿主账号无租户，enableKYC 恒为 false；KYC 相关功能需用开了 KYC 的租户登录（附查询 SQL） - 联调中途改了几个前端文件时用 cp.sh 逐个推送到 Windows，并按 Build at 判断编译完成 - 新增「联调时监控前后端」：remote-chrome 只读看 console/网络、后端文件日志路径与 Monitor 过滤、改后端（含 JSON）需重建镜像 Co-Authored-By: Claude Opus 5.5 --- .claude/skills/aml-local-refresh/SKILL.md | 35 ++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/.claude/skills/aml-local-refresh/SKILL.md b/.claude/skills/aml-local-refresh/SKILL.md index 7731f9f..4425e42 100644 --- a/.claude/skills/aml-local-refresh/SKILL.md +++ b/.claude/skills/aml-local-refresh/SKILL.md @@ -1,6 +1,6 @@ --- name: aml-local-refresh -description: Refresh the AML local dev stack - git pull AML_Backend (and AML_Frontend), restore the newest AML-local-dev-*.bak into the mssql container as AbpAML, rebuild the httpapi-host image, and restart the API bypassing db-migrator. Also covers running AML_Frontend against that local backend (npm run start:local, login admin, on the Mac or on FG-W11-ICON-DEV via a reverse SSH tunnel). Use when asked to 更新/还原/重建/重启本地后端环境, "拉最新代码并还原数据库", "restore the latest bak", 前端连本地后端/本地登录, 在 Windows 那台跑 AML 前端, or when local portal endpoints 500 after the backend moved on. +description: Refresh the AML local dev stack - git pull AML_Backend (and AML_Frontend), restore the newest AML-local-dev-*.bak into the mssql container as AbpAML, rebuild the httpapi-host image, and restart the API bypassing db-migrator. Also covers running AML_Frontend against that local backend (npm run start:local, login admin, on the Mac or on FG-W11-ICON-DEV via a reverse SSH tunnel), hot-pushing frontend edits to that box, and watching frontend console/network (remote Chrome) plus backend file logs while the user tests by hand. Use when asked to 更新/还原/重建/重启本地后端环境, "拉最新代码并还原数据库", "restore the latest bak", 前端连本地后端/本地登录, 在 Windows 那台跑 AML 前端, 联调时看前后端日志/监控扫描仪测试, or when local portal endpoints 500 after the backend moved on. --- # AML 本地环境刷新（拉代码 + 还原库 + 重启服务） @@ -164,6 +164,8 @@ curl -s -X POST http://localhost:44331/api/amlPortal/plan/portal/GetPlanList 库里还有几十个租户下也叫 `admin` 的账号，那些是真实客户的，别拿来试。 +**有些功能宿主账号用不了，得用租户账号**：宿主账号没有租户 ID，前端不会请求 `GetTenantProperty`，所有租户开关（如 `enableKYC`）都按 false 处理。例：V2 新客户页（`#/customer-v2/...`）的 OCR 录入会打出 `[扫描仪] 租户未开通 KYC…`，不检测扫描仪。这时让用户换成开了 KYC 的测试租户登录：`million1`（用户 2026-11-03 用它测过扫描仪）、`crmTest1`、`cpa1`。查哪些租户开了 KYC：`AMLPortal_TenantPropertys.EnableKYC=1`，用 `TargetTenantID` 关联 `SaasTenants.Id`。租户密码我们不知道，由用户自己登录。 + ### 关键约束：issuer 必须是 `http://localhost:44331` - 后端的 `AuthServer__Authority` / `App__SelfUrl` 固定是 `http://localhost:44331`。IdentityServer 的 issuer 跟着**请求的主机名**走：用 IP 访问时，发现文档里的 issuer 会变成 `http://192.168.x.x:44331`，签出来的 token 会被 API 拒掉（401）。所以**无论前端跑在哪台机器上，浏览器都必须通过 `localhost:44331` 访问后端**。 @@ -213,6 +215,15 @@ $S/cp.sh push -H FG-W11-ICON-DEV "$SCRATCH/aml-frontend-src.tgz" 'C:/Tools/aml-f 覆盖解压不会删除文件。如果上游删了文件，要先清掉旧目录（node_modules 可以留着）。 +**联调中途改了几个文件**，不用重新打包，逐个推过去，ng serve 会自动重新编译： + +```bash +cd /Users/dev/projects/AML/AML_Frontend +for p in <改动的文件...>; do $S/cp.sh push -H FG-W11-ICON-DEV "$p" "C:/Projects/AML_Frontend/$p"; done +``` + +重新编译约 1–2 分钟。看日志尾部：最后一行是 `Generating browser application bundles...` 就继续等；等到出现 `Build at: ` 并且晚于推送时间，再加上 `Compiled successfully`、没有 `error TS`，才算生效。然后请用户刷新页面。 + **3. 装依赖**（首次安装，或 package.json 变了）： ```powershell @@ -237,6 +248,28 @@ Start-Sleep 8; schtasks /Delete /TN TmpAmlFrontend /F - 验证：日志里有 `Compiled successfully`，且之后没有 `FATAL` / `npm ERR`；`http://127.0.0.1:4200/` 返回 200；`main.js` 里的 issuer 是 `http://localhost:44331`。起来一分钟后再查一次，前面那次 OOM 就是在第二轮构建时才崩的。 - 用户在那台机器的浏览器里打开 `http://localhost:4200` 登录。关掉桌面上那个「AML Frontend (start:local)」窗口就停了。 +### 联调时监控前后端（用户手动操作页面，Claude 看日志、分析、修复） + +用户不想来回粘贴日志，前后端日志都由 Claude 自己取。 + +**前端**：走 `remote-chrome` skill，接入用户在 FG-W11-ICON-DEV 上的 Chrome。**只读**：不跳转、不点击，页面由用户操作。 + +```bash +C=~/.claude/skills/remote-chrome/scripts/chrome.sh +$C call browser_console_messages '{"level":"info"}' | grep '\[扫描仪\]' | tail # 前端自己打的中文日志，[扫描仪] 前缀 +$C call browser_network_requests '{"static":false,"filter":"ScanCertificateV2"}' # 列出请求，带序号 +$C call browser_network_request '{"index":<序号>,"part":"request-body"}' # 也可以取 response-body +``` + +请求体和响应体里有客户证件信息。分析时只打印字段名、来源、命中数，**不要把值打出来**；需要留样本就放 scratchpad。 + +**后端**：Release 构建只写文件日志，按级别和日期分目录，日期是 UTC：`/app/Logs///.txt`。用 Monitor 跟踪：在容器里 `tail -n 0 -F` 这三个文件，再用 awk 过滤，Information 只留 `Request finished` 里的目标接口（如 `/kyc/`）。噪音要滤掉，比如 `AuditLogCollector`、`XSRF-TOKEN`、`ABP-LIC-0013`、EF 的 `row limiting operator`。 +- Monitor 最长 30 分钟，到期后要重新挂。 +- **重建或重启 host 容器后，`docker exec` 会断，Monitor 随之结束**，要重新挂。 +- 栈追踪在 Error 日志里，按时间 `grep -A 30` 取。 + +**改后端代码 → 生效**：`docker compose -f docker-compose.local.yml build httpapi-host`（增量构建约 3–5 分钟），然后 `up -d --no-build --no-deps httpapi-host`，等 swagger 返回 200。只改 `Data/AML/...` 下的 JSON 也得重建镜像，因为这些文件是打进镜像里的。 + ## 报告给用户 刷新完说清楚五件事：后端拉到的 commit、前端拉到的 commit（及 package.json 是否变了）、用的 .bak 文件名、库里的数量（表 / Plans / Editions / Tenants）、以及冒烟结果。