# Kra 与官方 GVA 接口一致性审查与整改计划

## 1. 审查结论

本计划以官方 GVA 快照
`C:\Users\Yvan\AppData\Local\Temp\gva-parity-02f3783`、commit
`02f37833255e0e339c3d69199cb5a468f17de9fc`（2026-08-06）为唯一行为基准，
逐项比较当前 Kra 的方法/路径、请求绑定与默认值、边界校验、鉴权与数据
范围、事务与副作用、响应 envelope，以及前端调用覆盖。

当前本地路由契约测试固定了 **178 条已注册 Gin 路由**。这 178 条包含
`/health` 与 Swagger；本地上传文件的 `GET`/`HEAD` 通过
`NoRoute -> serveLocalStorage` 动态处理，不计入 `engine.Routes()`。GVA 则
用 `StaticFS` 注册静态 wildcard，因此“178”只能表示本地注册表大小，不能
作为两端完整路由集合相等的证明。

审查结果可以概括为：

- 纳入范围的普通业务接口，在正常成功/失败路径上的绑定、权限、主要数据
  变更、事务和 JSON envelope 基本与 GVA 一致；逐接口证据见下方三份矩阵。
- 没有发现需要判为 P0 的已确认缺陷。
- 有 4 项 P1 路由/管理契约差异、3 项 P2 部署或故障语义差异、2 项 P3
  文档/输入兼容差异，详见第 4 节。
- “操作审计额外脱敏/trace 元数据”不是缺口：复核后确认 GVA 与 Kra 都
  具备同一组敏感字段脱敏、1 MiB 响应捕获上限以及 request/trace/device
  元数据；只需保留回归测试。

## 2. 范围与排除项

### 纳入范围

纳入所有已经迁移到 Kra 的系统、媒体、公告和邮件接口。模块级路由计数
如下，合计 178 条：

| 模块 | 路由数 | 逐接口矩阵 |
| --- | ---: | --- |
| Bootstrap/public（health、base、init、Swagger） | 6 | [identity/access](./parity-identity-access.md)、[crosscut](./parity-crosscut.md) |
| API registry + Casbin | 16 | [identity/access](./parity-identity-access.md) |
| User + JWT session | 14 | [identity/access](./parity-identity-access.md) |
| Authority + menu + button permission | 23 | [identity/access](./parity-identity-access.md) |
| Department + position | 14 | [identity/access](./parity-identity-access.md) |
| Dictionary + dictionary detail | 17 | [ops/content](./parity-ops-content.md) |
| Parameters + security + system + API token | 16 | [ops/content](./parity-ops-content.md) |
| Operation/login/data-access/log viewer/error audit | 19 | [ops/content](./parity-ops-content.md) |
| Export template + version | 19 | [ops/content](./parity-ops-content.md) |
| Timed task + SSE | 9 | [ops/content](./parity-ops-content.md) |
| Media files + categories + chunk upload | 15 | [ops/content](./parity-ops-content.md)、[crosscut](./parity-crosscut.md) |
| Announcement + email | 10 | [ops/content](./parity-ops-content.md) |

完整的本地调用链、前端覆盖、未被前端调用的后端接口和 178 条逐行路由
清单见 [local-api-inventory.md](./local-api-inventory.md)。其中除
`GET /health`、`GET /swagger/*any` 两条平台路由外，其余 176 条已迁移业务
路由都在 identity/access 或 ops/content 表中逐行出现；ops 表额外保留一行
GVA 的 AI `getSysErrorSolution` 作为 `EXCLUDED` 对照，因此不能用该表的
原始行数直接当作纳入计数。

覆盖核对结果：两个逐接口矩阵合计 177 行、去重后仍为 177 行；与本地
178 条注册路由比较时，仅缺少上面两条平台路由，且唯一多出的行正是被标记
为 `EXCLUDED` 的 GVA AI action。平台路由由 crosscut 审查，未被遗漏。

### 明确排除

按用户要求，不把下列未迁移或明确不需要迁移的模块计入一致性缺口：

- `system/sys_auto_code.go`、`sys_auto_code_history.go`、`sys_skills.go`；
- GVA plugin 下的 AI/LLM/MCP/CLI/skills、auto/plugin-management 路由；
- `example/exa_customer.go` 及 customer/example 功能；
- `GET /sysError/getSysErrorSolution`：它调用 `AutoCodeService.LLMAuto`，
  仅在 ops 矩阵中标记为 `EXCLUDED`，不要求补迁移、Casbin seed 或前端动作。

公告和邮件虽然在 GVA 中以 plugin 目录组织，但 Kra 已迁移且存在对应路由，
因此纳入审查。

## 3. 逐接口审查口径

每一行接口都按以下顺序对照：

1. HTTP method/path、router prefix、公共/私有分组和 operation-record 选择；
2. JSON/query/multipart/SSE 绑定、字段名、默认值及必填校验；
3. JWT、强制改密、Casbin、DataScope 和错误码/HTTP 状态；
4. usecase/repository 的数据变更、事务边界、缓存/黑名单/调度器/文件/邮件
   等副作用；
5. 成功与失败的 `{code,data,msg}` envelope、特殊下载/流式响应和前端调用。

`OK` 只表示在该接口的正常行为和已检查的边界行为上未发现材料差异，
不表示两端内部实现必须相同。持久化黑名单取代 GVA 内存缓存、每请求读取
Casbin 数据库、动态配置热加载等属于可接受实现差异，但必须覆盖故障测试。

## 4. 已确认差异与整改顺序

### P1-01：静态上传 URL 没有进入本地路由表

**接口/范围**：GVA `GET /uploads/file/*filepath`、`HEAD /uploads/file/*filepath`；
以及所有依赖 `engine.Routes()` 的 `/api/syncApi`、`/init/initdb`、启动路由
日志和 API registry。

- GVA 在 `server/initialize/router.go:60-61` 用
  `StaticFS(global.GVA_CONFIG.Local.StorePath, ...)` 注册 GET/HEAD wildcard，
  并把它们放进 `global.GVA_ROUTERS`。
- Kra 在 `internal/server/gin.go:63-69,117-141` 只在 `NoRoute` 中按
  `Local.PathPrefix` 动态服务文件，所以文件能下载，但不出现在
  `engine.Routes()` 或 `/api/syncApi` 输入；访问日志的 route 也会是
  `unmatched`。
- 默认配置中 `store-path` 与 `path-prefix` 都是 `uploads/file`，但配置
  分离时两端暴露的 URL 集合不同。基准 GVA 的预生成 Swagger 同样没有
  静态 wildcard，故 Swagger 不单独计为已确认差异。

**整改选择**：

- 严格兼容方案：注册与 GVA 同形的 GET/HEAD wildcard，以 `store-path` 为
  URL 前缀，同时保留 `nosniff`、非安全媒体 attachment 和目录拒绝；或
- 保留 NoRoute 方案，但把静态 URL 明确列为“非 API registry 路由”，在
  sync/init/日志契约中固定排除并补充迁移说明。

**验收测试**：临时目录、`store-path != path-prefix`、GET/HEAD、目录、
  不安全扩展名、router prefix、`syncApi` route diff、初始化 API seed。

### P1-02：`GET /api/freshCasbin` 的失败语义不一致

- GVA `server/api/v1/system/sys_api.go:314-329` 调用
  `CasbinService.FreshCasbin()`；`LoadPolicy`/enforcer 不可用时返回 HTTP
  200、`code=7`、`刷新失败`。
- Kra `internal/server/handler/api.go:201-206` 把该接口实现为恒定成功的
  DB-policy no-op，返回 `code=0`、`刷新成功`，不会暴露策略存储故障。

**计划**：决定该兼容接口是执行实际策略加载/可用性检查，还是正式声明
  “无内存 enforcer 的 no-op”。若目标是 GVA parity，应在失败时返回同样的
  code/message；至少增加数据库故障注入测试，保证行为不是静默成功。

**验收测试**：正常刷新、策略表不可读、事务中断、无 enforcer/空连接，
  比较 status/code/msg 和后续授权是否生效。

### P1-03：非空 `routerPrefix` 时 API sync/init 的路径规范不同

**接口**：`GET /api/syncApi`、`POST /api/enterSyncApi`、`POST /init/initdb`，
以及由 API path 进入 Casbin policy 的授权链路。

- Kra `internal/service/api.go:20-27,136-145` 和
  `internal/service/system_init.go:40-48` 会去掉 `routerPrefix`，把路径
  存成 `/api/...`；授权中间件也按无前缀路径查策略。
- GVA 直接比较带前缀的 `global.GVA_ROUTERS`，因此配置 `/admin` 时
  `syncApi`/初始化看到的是 `/admin/api/...`；默认的无前缀 ignore seed
  可能无法命中。

**计划**：先确定数据库 API path 的唯一规范（带前缀或不带前缀），然后
  同时修改 sync、init seed、ignore、enterSync 和 Casbin authorize；禁止只
  修一个接口导致数据库与运行时策略混用两种 path。保留旧数据迁移/回滚
  策略。

**验收测试**：空前缀、`/admin` 前缀、前缀尾斜杠、Swagger、sync diff、
  initdb seed、ignoreApi、setApiRoles/updateCasbin 和真实授权请求。

### P1-04：CORS 中间件的启用状态与基准不同

**接口/范围**：所有 HTTP 接口，尤其 `OPTIONS` 预检、strict-whitelist 和
  `allow-all` 配置。

- GVA 基准 `server/initialize/router.go:64-65` 的 `Cors/CorsByRules`
  都是注释状态，当前快照默认不安装 CORS 中间件；配置文件要求手动启用。
- Kra `internal/server/gin.go:27` 无条件安装 `CORS(runtime)`。因此默认
  `OPTIONS`、以及配置 `allow-all`/`strict-whitelist` 时的 header、204/403
  可达性都可能与 GVA 不同；strict 模式会直接拒绝 GVA 基准会继续处理的
  非白名单请求。

**计划**：决定 Kra 是否要保留这一增强。如果目标是严格 parity，应让启用
  由与 GVA 相同的部署开关控制；如果产品明确需要默认 CORS，则把它作为
  Kra 专有契约并从“GVA 一致”声明中剥离。

**验收测试**：无 Origin、allow-all、whitelist 命中/未命中、strict 未命中、
  OPTIONS、`/health` 例外、带 router prefix 的请求。

### P2-01：JWT 黑名单存储故障的 fail-open/fail-closed 语义不同

**接口/范围**：所有私有接口，以及 `POST /jwt/jsonInBlacklist`、API token
撤销后的访问。

- GVA `server/middleware/jwt.go:25-29,81-88` 只检查缓存命中；缓存读取
  没有错误返回，故障时可能继续解析普通 JWT。
- Kra `internal/data/api_token.go:128-140` 的黑名单 DB `Count` 出错会被
  `AuthenticateToken` 映射为 `ErrTokenDisabled`，把所有私有请求返回为
  401“异地登陆或令牌失效”。

**计划**：明确安全策略是 fail-closed 还是可用性优先，并在迁移说明中固定；
  若要求 GVA 可用性语义，需区分“明确命中黑名单”和“存储不可用”，不要
  把后者伪装成 token 已失效。

**验收测试**：黑名单命中/未命中、DB/Redis 超时、服务重启后的黑名单加载、
  token 刷新与多点登录。

### P2-02：安全限流 key 与作用面不同

**接口**：`POST /base/login`、`POST /base/captcha`，以及错误 method/未知
路径的边界请求。

- GVA 只在 `sys_base.go:13-14` 的两个 POST route 上安装
  `SecurityLimit()`，key 为 `GVA_SecLimit<ip><fullPath>`。
- Kra `internal/server/middleware/rate_limit.go:13-36` 通过全局 URL
  suffix 判断，key 为 `KRA_SecLimit<ip><fullPath>`，不检查 HTTP method；
  因此未知路径或错误 method 也可能递增限流计数。
- 共享 Redis/滚动部署时，前缀不同会使两端计数不连续。

**计划**：将限流收窄到精确的 POST route，并在需要滚动兼容时使用
  `GVA_SecLimit` 或双读迁移窗口；保留缓存异常 fail-open 的既有语义。

**验收测试**：正确 POST、GET/未知 path、router prefix、窗口边界、共享
  Redis key、缓存故障。

### P2-03：版本响应头名称不同

**接口/范围**：所有成功、业务失败、鉴权失败和未匹配路由响应。

- Kra `internal/server/middleware/access_log.go:35` 写 `X-Kra-Version`。
- GVA `server/middleware/access_log.go:69-73` 写 `X-Gva-Version`。

**计划**：兼容期双写两个 header，或将 GVA header 作为唯一公共契约；增加
  `/health`、`/base/captcha`、一个私有接口和 404 的 header contract test。

### 横切回归说明（不新增 parity 缺口）

以下实现差异目前未判为正常路径缺口，但应纳入同一套回归：Kra 每请求从
DB 读取 Casbin、持久化 JWT 黑名单、动态 runtime/CORS reload、`ErrorAudit`
对已知 code 7 的过滤、SSE/下载响应捕获。它们都可能在存储或中间件故障时
改变可观察结果。

### P3-01：空 `authorityIds` 的安全输入处理不同

**接口**：`POST /user/setUserAuthorities`。

GVA 在删除旧关联后直接访问 `authorityIds[0]`，空数组会变成 panic/500；
Kra 在 `internal/biz/user.go:165-170` 返回确定性的业务错误且不丢关联。
这是更安全的本地行为，不应复制 GVA 的 panic；应统一成“至少一个角色”的
显式校验，并把差异写入客户端契约。

### P3-02：Swagger 空前缀 `basePath` 字面值不同

GVA 生成文档的 `docs.SwaggerInfo.BasePath` 默认是空字符串；Kra
`internal/server/swagger.go:59-63` 在无前缀时输出 `basePath:"/"`。通常 URL
语义等价，但严格 JSON snapshot 或生成客户端可能可见。除非需要字面兼容，
可在 P3 阶段修正文档生成器或明确接受差异。

## 5. 模块级状态摘要

| 模块 | 逐接口结论 | 需要跟踪的横切项 |
| --- | --- | --- |
| Bootstrap/base/init/Swagger | 基础绑定、响应和登录流程对齐 | P1-03、P1-04、P2-03、P3-02 |
| API/Casbin | API CRUD、策略替换、同步正常路径对齐 | P1-01、P1-02、P1-03 |
| User/JWT/session | 用户和 token 正常流程对齐 | P2-01、P2-02、P2-03、P3-01 |
| Authority/menu/button | 角色、菜单、按钮和数据范围正常路径对齐 | P1-03（path 规范） |
| Department/position | 组织树、主部门、岗位关系正常路径对齐 | P1-03（path 规范） |
| Dictionary/parameters | CRUD、树、导入导出和分页对齐 | P2 审计/故障回归 |
| System/security/config/token | 配置、reload、API token 和黑名单正常路径对齐 | P1-04、P2-01、P2-02 |
| Audit/log viewer/error | 非 AI 错误/日志接口逐项对齐 | `getSysErrorSolution` 排除；P2 回归 |
| Export/version | token 下载、模板和版本包流程对齐 | P1-01（静态下载 route table） |
| Timed task/SSE | 调度、副作用、SSE heartbeat/event 对齐 | 中间件超时/捕获回归 |
| Media/chunk upload | 文件引用、哈希、分片和权限对齐 | P1-01、存储故障回归 |
| Announcement/email | CRUD、公开数据源、邮件发送对齐 | CORS/header contract |

## 6. 实施顺序

### 阶段 A：先定兼容契约（不改业务数据）

1. 决定 API path 的规范（是否保存 router prefix）。形成一份迁移说明，
   明确旧数据库记录、Casbin policy、ignore API 和 `syncApi` 的转换规则。
2. 决定静态文件是严格注册为 GVA route，还是正式保留 NoRoute 动态路由；
   同时决定 CORS 是部署开关还是 Kra 默认能力。
3. 决定 JWT 黑名单存储故障的 fail-open/fail-closed 策略，并记录安全评审
   结论。

### 阶段 B：处理 P1

按 P1-01 -> P1-02 -> P1-03 -> P1-04 顺序实现，每项都先补失败测试，再改
实现，最后运行对应模块测试。P1-03 必须和 P1-01 一起验证，因为静态
route table 会直接进入 sync/init seed。

### 阶段 C：处理 P2/P3 兼容项

- P2：双写/统一版本 header；统一或双读限流 key；明确黑名单存储故障响应；
  收窄限流 method/path。
- P3：空角色数组显式校验；Swagger `basePath` 字面值；将所有“安全增强但
  有差异”的行为写入迁移文档。

### 阶段 D：回归与灰度

先在单实例 SQLite/内存依赖跑合同测试，再用共享 Redis/数据库做双版本滚动
测试；最后执行前端登录、切换角色、菜单/API/按钮授权、文件上传下载、版本
导入导出、任务 SSE 和公告/邮件 smoke 流程。

## 7. 回归测试清单

| 测试层 | 必测内容 |
| --- | --- |
| Route contract | 178 条注册路由；静态 GET/HEAD；空前缀与 `/admin`；重复 method/path；startup route log |
| Binding/envelope | 每个矩阵接口的缺字段、类型错误、空数组、分页边界；HTTP 200 + code 7、401、409、403、500 |
| API sync/init | `syncApi`、`enterSyncApi`、`initdb`、ignore seed、静态 route、router prefix |
| Auth/session | 登录/验证码限流、JWT 过期刷新、黑名单、API token 撤销、多点登录、MustChangePwd allow-list |
| Authorization | Casbin deny/allow、freshCasbin 失败、DataScope 1/2/4/5、角色/菜单/按钮/部门关系事务 |
| Cross-cutting | CORS modes/OPTIONS、版本 header、request/trace metadata、operation/error audit、panic/broken-pipe |
| Storage/media | GET/HEAD upload headers、对象引用计数、URL/分片 MD5、owner check、原子 complete、token 下载一次性消费 |
| Task/content | scheduler create/update/toggle/trigger、SSE heartbeat/event、字典层级、版本 staged errors、公告公开端点、邮件发送 |

## 8. 验收门槛与当前限制

完成标准：

- P1 项要么修复并有集成测试，要么由产品/运维明确签字接受为 Kra 专有
  契约；
- 每个纳入模块的逐接口矩阵仍保持一行一接口，不能用“模块整体 OK”替代；
- 共享 Redis、非空 router prefix、存储故障和数据库不可用均有可重复测试；
- 前端使用的接口和当前无前端调用但已注册的后端接口都完成契约确认。

本轮只新增审计文档，没有修改业务代码。已通过 `git diff --check`；全量
`go test ./...` 未能在当前受限环境中执行，原因是用户级 Go cache 需要沙箱外
权限且审批服务返回 503，不应把它误写成测试失败。实现阶段必须在可用的构建
环境补跑全量测试。