Agent skills

Issue tracker

Issue 以 Markdown 文件存放在 .scratch/<feature-slug>/。详见 docs/agents/issue-tracker.md。

Triage labels

使用默认标签：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。详见 docs/agents/triage-labels.md。

Domain docs

采用单上下文布局：根目录 CONTEXT.md，ADR 位于 docs/adr/。详见 docs/agents/domain.md。

工作范围：按业务域分工，不要越界

本仓库由多人**按业务域分工**（支付链路一人，其余业务一人），彼此约定**互不越界**——越界改动会在
git 合并时产生大量冲突。本节适用于**所有**在仓库里工作的人和 AI 会话，与具体是谁无关。

• 只改用户本次指派范围内的代码、迁移和前端。 范围以用户的说明为准；用户没说清、或任务看起来横跨
  多个业务域时，先问，不要自己扩大范围。
• 范围外的业务只做只读排查：可以读代码、查库、跑 SQL、给出结论和建议，但不要直接改它的代码、
  迁移和前端。域划分大致是：**支付链路**＝汇付/斗拱进件与开通、支付、核销后的资金确认、自动结算与
  结算记录、退款；**其余业务**＝家属卡、洗车、停车、票券包、权益规则、资讯、各类申请审核等。
  （根目录 CONTEXT.md 是**术语表**，里面没有代码位置。）
• 需要修范围外的缺陷时，把「现象 + 根因 + 证据 + 建议改法」整理成 Markdown（放
  .scratch/<feature-slug>/issues/）交给用户转给该业务的负责人，不要直接动手。
• 迁移编号是全仓共享的：新增迁移前先看 talent-card-server/src/main/resources/db/migration/ 里当前
  的最大版本号，避免与他人撞号。
• 共享文件更要克制（talent-card-admin/src/api/admin.ts、src/router/index.ts、
  src/layouts/AdminLayout.vue、talent-card-server/src/main/resources/application.yml、
  AdminBusinessService.java、CONTEXT.md）：只做自己范围内的**增量小改**，不要顺手重构或格式化
  别人的区域。

服务器测试与数据库

后端测试跑在共享的 MySQL 测试库上。跑测试用 talent-card-server/scripts/run-server-tests.ps1，
重置库用 talent-card-server/scripts/reset-test-db.ps1，并遵守：已执行的迁移只追加不修改、同一
checkout 一次只跑一个 Maven 构建、不要 drop database。详见 docs/agents/testing.md（**开发库与
测试库是哪两个库、什么版本**、3 项已知基线失败，以及一类会随测试库累积而出现的环境相关失败；不要为
证明它们是"既有的"而重复造 worktree）。

攀枝花政务云服务器：操作纪律（务必遵守）

这台机器**没有公网自服务控制台**——console/VNC 只在「云管理方」手里，进去只有一条路：堡垒机
（172.18.105.9）。**一旦把这条路弄断，你和用户谁都进不去，只能求服务商。** 2026-09-21 已经发生过
一次（docker 网桥占用 172.18.0.0/16，与堡垒机网段冲突，回程路由被劫走）。以下每条都是那次事故立的：

• 只在用户明确授权后动手。 用户说"先别干活"、或语义模糊（例如只说"我们继续吧"）时，**只给方案和
  命令，不执行**。事故当天就是凭一句模糊的"继续吧"动了手。
• 改网络/路由/防火墙/端口/SSH 之前，先确认带外通道可用。 没有 console/VNC 兜底，这类改动一律不做。
• 改之前先枚举已知网段，不要只看"自己那一段"：

| 网段 | 是谁 |
|---|---|
| 172.192.19.0/24 | 服务器自己，网关 172.192.19.254 |
| 172.18.0.0/16 | 堡垒机所在网段（堡垒机连服务器的来源是 172.18.140.254） |
| 192.169.1.10 | 办公侧（VPN 客户端来源） |
| 192.168.110.0/24 | 办公室开发库 192.168.110.13 |

• 不要在这台机器上引入 docker（2026-09-21 已卸载，别再装回去）。 两个原因：一是它的网桥默认
  地址池会依次分到 172.17、172.18、172.19…，正好撞上堡垒机网段 172.18.0.0/16，回程路由被劫走
  就直接失联；二是这台机器的虚拟 CPU 缺 SSE4.2/POPCNT，以 x86-64-v2 为基线的镜像根本跑不起来（见下）。
  MySQL/Redis 一律原生装。 万一将来确实要重新引入，**必须在建任何网络之前先钉死地址池**：
  "default-address-pools": [ { "base": "10.201.0.0/16", "size": 24 } ]（同时把 data-root 指向
  /data——40G 系统盘装不下镜像）。
• 一次只改一件事，每步之后先复检堡垒机通道还在，再走下一步。
• 高危改动挂自动回滚：systemd-run --on-active=5min /bin/bash -c '<撤销命令>'，确认通道正常后再
  取消它。最坏情况 5 分钟后自己恢复，不必求人。
• 给服务商的命令要一次说准、可直接复制、并写出期望输出。 消息要经**两跳**（对接人 → 云管理方），
  每次返工就是几十分钟。事故当天给的 docker compose down 缺了 -f（本仓的 compose 叫
  docker-compose.prod.yml，不是 compose 的默认文件名），白费一跳。
• 不要把凭据写进聊天。 必须提供给执行人时，事后立刻轮换。

这台机器的硬约束（改环境前先看）：

• 虚拟 CPU 缺 SSE4.2/POPCNT/AVX（KVM 上是老的 QEMU 型号，物理 CPU 其实够用）→ 任何以
  x86-64-v2 为基线的镜像都跑不起来：官方 mysql:8.4 会 Fatal glibc error: CPU does not support x86-64-v2 循环退出（exit 127）。Redis 官方镜像正常，Ubuntu 自己的包都正常。要跑这类镜像，得请服务商
  把虚拟机的 CPU 型号改成 host-passthrough。
• 出网已开通，是**任意公网地址**（不是域名白名单）。但 Docker Hub 直连不通（registry-1.docker.io
  连接被重置），拉镜像走 public.ecr.aws/docker/library/<name>。
• 入向只有 8081/8082 开放（公网地址 117.172.73.106）；80/443/8080 要备案号才能开。
• 办公网到 172.192.19.0/24 没有路由，所以只能走堡垒机，不能直连。

Git 提交

提交信息一律用中文，沿用仓库既有风格：type(scope): 中文摘要，type 保留英文
（feat/fix/refactor/docs/test/chore），正文与说明也用中文。
只要求提交信息用中文；代码标识符、测试名、日志与错误信息保持英文。
示例：fix(merchant): 进件审核中不再被误判为拒绝。