From 027ef2b296cfe405f448b39f44db7f1fd2e1b119 Mon Sep 17 00:00:00 2001 From: yeuimu <2197651308@qq.com> Date: Thu, 3 Sep 2026 03:40:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=80=A7=E8=83=BD=E6=95=B4=E6=94=B9?= =?UTF-8?q?=E8=90=BD=E5=9C=B0=E6=96=87=E6=A1=A3=E2=80=94=E2=80=94structs?= =?UTF-8?q?=20=E8=A1=A5=E7=BC=93=E5=AD=98=E5=B1=82=E4=B8=8E=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E5=8F=82=E6=95=B0=E8=AF=B4=E6=98=8E=E3=80=81=E6=8A=A5?= =?UTF-8?q?=E5=91=8A=E6=A0=87=E6=B3=A8=20P0=20=E5=AE=9E=E6=96=BD=E8=BF=9B?= =?UTF-8?q?=E5=BA=A6=E3=80=81AGENTS=20=E6=B2=89=E6=B7=80=E5=88=87=E7=89=87?= =?UTF-8?q?=E7=BC=93=E5=AD=98=E9=99=B7=E9=98=B1=E4=B8=8E=20bullseye=20?= =?UTF-8?q?=E8=B7=91=E6=B5=8B=E7=BB=8F=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 ++- docs/references/structs.md | 9 ++++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3004acf..3a328c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,7 +98,8 @@ Prisma Postgres 最佳实践: prisma-postgres 技能 - **连真实库的集成测试隔离**：jest 并行套件共用一个数据库时，(a) 夹具的天然键（sdsCategoryId、名称等）必须带运行时间戳唯一化，禁止跨运行共享字面量；(b) 全量型操作（如 auto-group 扫全库）会顺带扫到其他并行套件的夹具，其写入路径必须对"成员中途消失"宽容（跳过而非抛错），否则会随机挂测试。 - **跑全量 jest 前先停 dev server**：`nest start --watch` 等常驻进程与测试共用数据库时，其重编译窗口/后台钩子会与测试写入竞争，造成"单跑绿、全量偶发红"的假阳性；验证基线前先停掉所有 watch 进程再跑。 - **中文断言勿手写字面量排序**：JS `Array.sort()` 对中文按 UTF-16 码位排（如 烫 U+70EB < 直 U+76F4），手写期望序列容易按拼音/习惯顺序写反；比较选项集合时用 `expect.arrayContaining` + 长度，或从同一排序函数生成期望。 -- **pnpm 仓库容器化执行要挂仓库根**：pnpm 的 node_modules 是相对符号链接指向根 `.pnpm` store，容器里只挂子包目录（如 `apps/api:/app`）会断链报 "Cannot find module"；必须挂整个仓库根并 `-w` 到子包。另外 Prisma 引擎与系统 libssl 版本强绑定：node:20-alpine 缺 libssl1.1 会报 engine 加载失败，直接复用项目自身的运行镜像（如 deploy-v2-api）跑 prisma/jest 最稳。 +- **pnpm 仓库容器化执行要挂仓库根**：pnpm 的 node_modules 是相对符号链接指向根 `.pnpm` store，容器里只挂子包目录（如 `apps/api:/app`）会断链报 "Cannot find module"；必须挂整个仓库根并 `-w` 到子包。另外 Prisma 引擎与系统 libssl 版本强绑定：node:20-alpine 缺 libssl1.1 会报 engine 加载失败；仓库 `.pnpm` store 里生成的 client 是 openssl-1.1.x target，**bookworm 系镜像（node:20-slim）同样跑不了**，用 `node:20-bullseye-slim` 挂仓库根 + `--network host`（连本机一次性测试库）跑 jest/prisma 即可，无需依赖项目运行镜像。 +- **缓存值里绝不能带请求级切片（分页/字段裁剪）**：把 `items.slice(page…)` 的结果整个塞进缓存后，缓存键不含 page → 所有页码命中同一条目、页页返回第一页（total 对得上更具迷惑性）；正确做法是缓存"全量物化结果"，切片在缓存命中后按请求执行。TDD 用例必须包含"同键翻页 + 页内容随页码变化"的断言才能抓住这类错。 - **Prisma 唯一查询用字段名而非列名**：`where: { id }` 而非 `@map("category_id")` 映射后的 `categoryId`；schema `@map` 只影响 SQL 列名，Prisma Client 的唯一输入类型永远用 model 字段名。 - **跨套件分页断言要圈定夹具**：真实库上测"列表排序"时全库数据可能远超 pageSize，夹具根本进不了第一页；给夹具商品名加唯一前缀 + `keyword` 过滤圈定，断言既稳定又能看到完整顺序。 - **"绝对排序键 + 子集过滤"模式**：需要"任意筛选组合下顺序都正确"时，给每条数据算好一组绝对排序键（如 国家→二级→款→priority，缺失沉底），筛选只做子集过滤不做特殊排序分支——比每个筛选组合写一套 orderBy 逻辑可靠得多。 diff --git a/docs/references/structs.md b/docs/references/structs.md index 043d57e..ad0d29c 100644 --- a/docs/references/structs.md +++ b/docs/references/structs.md @@ -47,6 +47,13 @@ inkreach-official/ `v2-postgres`（数据卷 `deploy-v2_pgdata` external 引用，v2 数据未迁移）。 - 域名路由：`/v2/admin/`（SPA）、`/v2-api/`（小程序/后台 API，去前缀转发）、`/public/` （H5 同源 API）、`/uploads/`、`/assets/` 均由 v2-api 服务；`/` 302 到 `/v2/admin/`。 +- 性能整改 P0（2026-09-03，plans/refactor/public-capacity-10k-refactor.md）：边缘 nginx + 主配置改为仓库文件 `deploy/nginx/nginx.conf`（worker_connections 16384 + gzip + 访问日志， + 经 admin.Dockerfile COPY，改后须重建镜像）；admin.conf 含 upstream keepalive/限流(429)/ + 代理超时/静态缓存头；v2-postgres 显式参数（statement_timeout=10s、max_connections=200、 + shared_buffers=512MB）；v2-api 的 DATABASE_URL 带 `connection_limit=50&pool_timeout=3` + （pool_timeout 单位为秒）；admin 服务 ulimits nofile 65536。改 PG 参数/重启前按全局约束 + 先 pg_dump + 配置快照落 `deploy/backups/<时间戳>/`。 - v1（旧 api+postgres，曾支撑 `/public/` 与旧后台）已退役：切换时容器停用未删， 库终档与全部配置快照及回滚手册见 `deploy/backups/consolidation-*/RESTORE.md`。 - 原 v2 独立栈（`docker-compose.v2.yml`、`/opt/inkreach-v2` 检出）已并入单栈并删除， @@ -76,7 +83,7 @@ apps/api/ │ ├── product-families/ # 产品族（SPU 层）：CRUD / auto-group（并入已有族优先，familyNameKey 族语义键）/ attachToMatchingFamily（单链接自动归族）/ consolidateFragments（碎片族合并）/ 成员管理 / 自定义成员 / 价格覆盖 / 重算 / 按链接名称派生标签（auto-tag-rules，含 热转印→烫画 别名）。数据约定（2026-09-03 起）：光板/不打印链接不入族、矩阵不计算不打印工艺；auto-group/organize/人工改标签会把散链接回挂，运行前须排查（备份见 deploy/backups/20260903-noprint-removal/） │ ├── goods/ # 商品 CRUD + 批量优先级 + 批量创建 + 展示名规范化（品名 SKU，剥 ASCII 型号限定词，纯款号按 SDS 分类名补描述） │ ├── sync/ # SDS 同步：分类 / 商品 / 同步日志 -│ ├── public/ # 公开 API：分类树 / 国家 / 商品分页 / 商品详情 +│ ├── public/ # 公开 API：分类树 / 国家 / 商品分页 / 商品详情；public-cache.service.ts 为进程内分域缓存（meta/goods/matrix 版本域 + TTL 兜底 + in-flight 合并，P0-1 性能整改），全部写路径（admin CRUD/sync/族重算/整理）事务提交后 bump 对应域即时失效；env 开关 PUBLIC_CACHE_DISABLED / PUBLIC_CACHE_TTL_MS / PUBLIC_CACHE_MAX_ENTRIES │ └── common/ # 全局装饰器 / 过滤器 / 拦截器 │ ├── decorators/current-user.decorator.ts │ ├── filters/http-exception.filter.ts