# 经验日志 记录已捕获的 learnings、纠正信息和新发现。开始重大任务前建议先回顾。 --- ## [LRN-20260424-001] best_practice **Logged**: 2026-04-24 **Priority**: high **Status**: pending **Area**: infra ### Summary OpenSSL 3.x 无法直接使用旧版 `.pfx` 证书，需要 `-legacy` flag 先转换为 PEM 再使用。 ### Details ADP API 的 mTLS 证书为 `.pfx`（PKCS#12）格式，使用旧版加密算法（RC2/3DES）。在 OpenSSL 3.x 环境下直接使用会报：`error:0308010C:digital envelope routines::unsupported` 解决方法：先用 `-legacy` flag 提取 PEM 证书，再配合 `.key` 私钥使用： ```bash openssl pkcs12 -legacy -in cert.pfx -nokeys -clcerts -out /tmp/cert.pem -passin pass: ``` 然后用 `/tmp/cert.pem` + `.key` 组合调用 API。Node.js 代码也需要同样处理，不能直接读 `.pfx`。 ### Metadata - Source: conversation - Pattern-Key: infra.openssl3-pfx-legacy-flag - Tags: openssl, mtls, certificate, adp-api --- ## [LRN-20260424-002] best_practice **Logged**: 2026-04-24 **Priority**: medium **Status**: pending **Area**: backend ### Summary ADP API 的总数参数是 `count=true`（不带 `$`），与其他 OData 参数（`$top`、`$skip`、`$filter`）规范不一致。 ### Details ADP `/hr/v2/workers` 的分页参数遵循 OData 规范（带 `$`），但总数参数是例外：正确写法是 `?count=true`，写成 `?$count=true` 不生效，meta 返回 None。另外 `$filter` 与 `count=true` 不能同时使用，无法做到 filter + count 组合查询。 ### Metadata - Source: conversation - Pattern-Key: adp-api.count-param-no-dollar-sign - Tags: adp-api, odata, pagination --- ## [LRN-20260330-001] best_practice **Logged**: 2026-03-30T08:37:44Z **Priority**: high **Status**: promoted **Area**: infra ### Summary 本仓库本地开发启动应优先使用 `scripts/dev/dev.sh`，不要把 `scripts/deploy/deploy.sh` 当作默认本地启动入口。 ### Details 本次本地启动排查中，真实可用路径是先启动 Docker 基础服务，再执行 `backend` 的 `prisma generate`、`db:push`，最后分别启动后端和前端。`scripts/deploy/deploy.sh` 虽然存在，但职责偏部署与运维编排；直接拿它作为本地开发主入口，容易和当前 `.env` 的 Docker 变量缺口、开发服务行为混淆。另一个实际坑点是：当前 `.env` 可能只覆盖应用读取所需变量，未覆盖 `docker compose` 所需的 `POSTGRES_PORT`、`CONTAINER_PREFIX` 等变量。 ### Suggested Action 进入仓库后，优先按以下顺序判断本地启动方式：`bash scripts/dev/dev.sh up` → `cd backend && npm run prisma:generate` → `cd backend && npm run db:push` → `cd backend && npm run start:dev` → `cd frontend && npm run dev`。如 Docker 端变量缺失，先补 `.env` 或在命令行临时注入。 ### Metadata - Source: conversation - Pattern-Key: local-dev-startup-entrypoint-dev-sh - Promoted: AGENTS.md, CLAUDE.md --- ## [LRN-20260330-002] best_practice **Logged**: 2026-03-30T10:10:00Z **Priority**: high **Status**: pending **Area**: tests ### Summary 会议出勤这类依赖外部同步的联调验证，在本地无样本数据时应先构造“最小受控样本”，再走真实 API 链路。 ### Details 本次要验证“删除参会人后冻结 Outlook 同步”和“已有出勤记录禁止删除”，本地开发库没有任何会议或 Outlook 纳管记录。直接等待真实样本会阻塞验证，也无法区分代码问题还是数据缺失。更稳的方式是：先用真实 API 创建会议与参会人，再用 Prisma 插入最小 Outlook mailbox/binding 样本，最后调用真实删除接口和历史查询接口验证状态、返回码与日志。这种做法既覆盖了真实控制器/服务层，又避免依赖外部 Outlook 数据源。 ### Suggested Action 后续凡是验证“本地业务对象 + 外部同步状态”联动场景，优先采用“真实 API 创建业务对象 + 最小测试 binding/fixture”策略，而不是手工猜测现有库里是否有可复用数据。 ### Metadata - Source: conversation - Related Files: backend/src/modules/meeting-attendance/services/meetings.service.ts, backend/src/modules/meeting-attendance/services/outlook-sync.service.ts - Tags: meeting-attendance, local-validation, outlook-sync - Pattern-Key: local-validation.minimal-controlled-fixture --- ## [LRN-20260408-001] best_practice **Logged**: 2026-04-08T02:30:00Z **Priority**: high **Status**: pending **Area**: infra ### Summary 多品牌部署：通过 `NEXT_PUBLIC_*` 环境变量 + `brand.ts` 配置中心抽离品牌标识，不同实例用不同 `.env` 即可切换品牌。 ### Details 项目原为 FF 公司定制，需支持 AIxC 部署。品牌标识散落在 locales、layout、组件、邮件模板、初始化脚本等 13+ 个文件中。解决方案： 1. 新建 `frontend/src/lib/brand.ts` 作为品牌配置中心，集中读取 `NEXT_PUBLIC_*` 环境变量并提供默认值 2. 所有前端硬编码（Logo路径、品牌名、Slogan、示例邮箱域名）改为引用 `brand.*` 3. 后端在 `configuration.ts` 新增 `brand` 区块，邮件页脚、User-Agent 等改为从 ConfigService 读取 4. 所有新变量都有 FF 默认值，不设置时行为完全不变 关键注意点：`NEXT_PUBLIC_*` 是 Next.js **构建时**内联的，改了 `.env` 必须重新 `next build`，仅 restart PM2 不会生效。 ### Suggested Action 后续新增用户可见文案时，先检查是否属于品牌标识（公司名、Logo、Slogan、邮件签名等），如果是则必须通过 `brand.ts` / `configuration.ts` 的环境变量控制，不能硬编码。 ### Metadata - Source: conversation - Related Files: frontend/src/lib/brand.ts, backend/src/config/configuration.ts, .env.example - Tags: multi-brand, white-label, deployment - Pattern-Key: multi-brand.env-driven-branding --- ## [LRN-20260408-002] best_practice **Logged**: 2026-04-08T02:30:00Z **Priority**: high **Status**: pending **Area**: infra ### Summary Azure 全新服务器部署清单：安装依赖 → 克隆代码 → 上传 .env → 修复 lockfile 镜像 → db push + resolve migrations → 种子 → PM2 启动 → Nginx 反代 → 开 NSG 端口。 ### Details 在两台全新 Azure VM (Ubuntu 24.04) 上从零部署项目，总结出的完整流程： 1. **基础依赖**：Node.js 20 (nodesource)、Docker CE、PM2、build-essential 2. **Docker 权限**：`usermod -aG docker $USER`，但 SSH session 不会立刻生效，必须用 `sg docker -c "命令"` 包裹 3. **代码克隆**：用 Gitea token URL 克隆，checkout 到 develop 4. **环境配置**：上传 `.env.uat` 或 `.env.pro`，含品牌变量、数据库密码、JWT Secret 等 5. **lockfile 修复**：`package-lock.json` 含腾讯云镜像 URL，Azure 服务器访问不了，每次 git pull 后都要 `sed` 替换 6. **数据库初始化**：全新数据库不用 `migrate deploy`（历史迁移有嵌套事务问题），改用 `prisma db push` + 逐个 `migrate resolve --applied` 7. **Nginx**：反向代理 80 端口到内部前端/后端端口，对外只暴露 80/443 8. **Azure NSG**：必须在 Azure Portal 手动开放 80/443 端口，VM 本地防火墙 (ufw) 默认 inactive 不阻挡 ### Suggested Action 下次部署新环境时，按此清单执行。特别注意 `sg docker` 包裹命令、lockfile sed 替换时机（git pull 之后）、以及 db push 替代 migrate deploy 的策略。 ### Metadata - Source: conversation - Related Files: scripts/deploy/deploy.sh, docker/docker-compose.yml - Tags: azure, deployment, fresh-server, checklist - Pattern-Key: deployment.azure-fresh-server-checklist --- ## [LRN-20260408-003] best_practice **Logged**: 2026-04-08T02:30:00Z **Priority**: medium **Status**: pending **Area**: infra ### Summary Gitea 分支保护绕过：紧急合并时需同时禁用 `required_approvals` 和 `enable_status_check`，合并后立即恢复。 ### Details 项目 develop 分支有三层保护：1 个 approval + 3 个 status check。当需要紧急合并且无法自我 approve 时： 1. 仅禁用 approvals 不够 — status check 可能还在 pending 2. 仅设置 status 为 success 不够 — 新 commit 会触发新 CI run 覆盖状态 3. 正确做法：通过 API 同时 `PATCH` 分支保护，设 `required_approvals: 0` + `enable_status_check: false`，合并后立即恢复原值 另外注意：Gitea merge API 成功时可能返回 204 No Content（空响应体），不是 JSON，不要用 json.load 解析。 ### Suggested Action 紧急合并时使用此三步法：禁用保护 → 合并 → 恢复保护。合并前确认分支不落后 base（否则需要先 rebase）。 ### Metadata - Source: conversation - Related Files: .gitea/workflows/ - Tags: gitea, branch-protection, emergency-merge - Pattern-Key: gitea.emergency-merge-bypass --- ## [LRN-20260416-001] correction **Logged**: 2026-04-16T06:30:00Z **Priority**: critical **Status**: resolved **Area**: backend ### Summary v2.2 user-effective API 没处理 effect=revoke，导致 sync 脚本无法将用户级工具取消同步到 OpenClaw ### Details 用户在 Workspace UI 给 Hongwei 取消了 image 工具（effect=revoke），但 OpenClaw agent config 仍然保留 image。根因：v2.2 `getUserEffectiveTools` 方法查 `AIToolGrantUser` 时没有区分 `effect` 字段，把 revoke 记录也当作 grant 加入了结果。sync 脚本调的是 v2.2 API，所以用户取消的工具永远不会从 OpenClaw 移除。同样的问题也存在于 `getToolSubjects` 反查接口。 ### Suggested Action **新增 effect 字段时，必须同时审查所有消费该表数据的方法。** DB schema 加字段容易遗漏下游读取方的过滤条件。应该在加字段的 PR review 阶段强制检查所有 `findMany({ where: { toolName } })` 类查询。 ### Resolution - **Resolved**: 2026-04-16T06:10:00Z - **Notes**: 修复了 getUserEffectiveTools、getUserEffectiveToolsV2、getToolSubjects 三处 ### Metadata - Source: user_feedback - Related Files: backend/src/modules/organization/ai-tools/ai-tools.service.ts - Tags: data-integrity, schema-migration, sync-pipeline - Pattern-Key: schema.field_add_downstream_audit --- ## [LRN-20260416-002] correction **Logged**: 2026-04-16T06:30:00Z **Priority**: high **Status**: resolved **Area**: frontend ### Summary label 包裹 Radix Checkbox 导致双击 bug — 点击触发两次 toggle，checkbox 状态不变 ### Details 在 Drawer 编辑器中用 `