kra-oa/docs/audit/parity-crosscut.md

GVA 横切接口对照审计

基准：C:/Users/Yvan/AppData/Local/Temp/gva-parity-02f3783（commit 02f37833255e0e339c3d69199cb5a468f17de9fc，2026-08-06）。 范围：只审查已迁移后台接口共用的 HTTP/router/middleware 行为；未迁移的代码生成、AI 等模块不计入缺口。 GET /sysError/getSysErrorSolution 调用 LLMAuto，按要求排除。

结论摘要

项	结论	严重度
路由实际集合	业务路由方法和路径基本对齐；本地 engine.Routes() 不含动态本地静态文件，而 GVA StaticFS 会注册静态 GET/HEAD wildcard	P1（API sync/route-table 可见集合）
静态文件 URL	GVA 以 local.store-path 注册静态路由；本地 NoRoute 以 local.path-prefix 动态处理。默认值相同，配置分离时行为不同	P1（配置不一致时）
Swagger basePath	GVA 生成文档的 docs.SwaggerInfo.BasePath 在无前缀时为空字符串；本地动态文档把空前缀规范化为 /。带 /admin 前缀时两端都输出 /admin	P3（严格文档/客户端比较）
统一响应/状态码	成功/业务失败均 HTTP 200 + {code,data,msg}；未登录 401；强制改密 409；panic 500；限流 200，和 GVA 一致	对齐
请求绑定错误	ShouldBindJSON/Query 错误均转换为 HTTP 200、code 7、data {}；与 GVA 一致	对齐
JWT/刷新/多点登录	黑名单、临近过期刷新、cookie/new-token 头、多点登录旧 token 作废逻辑对齐；本地用持久化黑名单并 singleflight，属于实现差异	P2（实现/故障语义需回归）
MustChangePwd	允许 /user/changePassword、/user/getUserInfo、/jwt/jsonInBlacklist，其余 409/code 10001；对齐	对齐
Casbin	本地每次从 casbin_rule 读取并直接 Enforce；GVA 使用内存 enforcer。freshCasbin 本地恒成功，GVA LoadPolicy 失败会返回 code 7	P1
DataScope	顺序均为 JWT -> MustChangePwd -> Casbin -> DataScope；本地额外注入 actor/request metadata，不改变已迁移接口授权规则	对齐（增强）
CORS	GVA 基准的 Cors/CorsByRules 在 router.go 中均为注释、默认未安装；本地无条件安装并按 runtime 执行 allow-all/whitelist/strict。默认 whitelist 空配置时差异不显著，但 strict/allow-all 会改变可达性与响应头	P1（启用配置时行为不兼容）
登录/验证码限流	GVA 仅在 POST /base/login、POST /base/captcha 路由挂限流；本地是全局 middleware，按 URL 后缀匹配，未匹配路由或其他方法也可能计数。超限 HTTP 200/code 7、缓存异常 fail-open；另有 key 前缀 KRA_SecLimit vs GVA_SecLimit	P2（作用面与跨版本缓存兼容）
request/trace metadata	RequestMeta 最先执行，X-Request-Id、X-Trace-Id、W3C traceparent 的校验/回写顺序一致	对齐
access log	单一 body/response capture、脱敏、1 MiB response cap、route/status/bytes/identity/trace 字段一致；版本头不同	P2
operation audit	已迁移的 GVA OperationRecord 分组路由均被本地 operationRoutes 覆盖；AI getSysErrorSolution 排除	对齐（需防漏项测试）
error audit	panic/错误级日志走单一 error sink；本地响应 envelope 的未预期业务失败由 ErrorAudit 转为 error log；GVA 由 logger core 捕捉 error level	对齐（实现不同）
panic recovery	broken-pipe 仅记录并 abort，普通 panic 返回 500；对齐	对齐
API sync/init seed	本地初始化/同步使用 engine.Routes()；本地会去掉 router-prefix，GVA 基准直接使用带 prefix 的 GVA_ROUTERS。静态 routes 缺失叠加影响 sync/seed	P1（自定义 prefix）

逐项核验

1. Router 与静态文件

GVA server/initialize/router.go 的顺序为 RequestMeta -> GinRecovery -> AccessLog -> UploadResponseHeaders -> StaticFS -> Swagger -> Public/Private；Private 依次安装 JWTAuth -> MustChangePwdGuard -> CasbinHandler -> DataScope。本地 internal/server/gin.go 为 RequestMeta -> Recovery -> AccessLog -> CORS -> ErrorAudit -> SecurityRateLimit，再建立 Public/Private；Private 依次为 Auth -> MustChangePassword -> AccessControl -> OperationAudit。已迁移业务 handler 的路径/HTTP method 与路由契约测试一致。

本地没有调用 StaticFS，而是在 NoRoute 中用 serveLocalStorage 按 local.path-prefix 动态匹配；因此动态静态文件不会出现在 engine.Routes() 或 /api/syncApi 输入中。GVA StaticFS(global.GVA_CONFIG.Local.StorePath, ...) 会注册静态 wildcard 的 GET 和 HEAD，并进入 GVA_ROUTERS。默认配置两者都为 uploads/file，但如果 store-path != path-prefix，两端暴露的 URL 集合不同。基准 GVA 的预生成 Swagger 文档也没有 /uploads/file/*filepath，而 Kra 的动态 Swagger 同样不会把 NoRoute fallback 当作文档路由，因此 Swagger 本身不单独计为已确认差异。静态响应头（nosniff，非安全媒体 Content-Disposition: attachment）的效果一致；本地额外拒绝目录。

Swagger 文档的根路径还有一个低等级差异：基准 server/docs/docs.go 的 BasePath 默认值为空字符串，server/initialize/router.go 仅在配置有前缀时写入；本地 internal/server/swagger.go:59-63 将空前缀强制写成 "/"。这通常不会改变浏览器请求，但会影响严格 JSON 快照或按 basePath 拼接 URL 的客户端。

测试建议：构造临时目录和 store-path != path-prefix；断言 GVA 期望的 GET/HEAD /<store-path>/*filepath 是否进入 route table 与 sync diff，且确认两端 Swagger 文档的静态路由口径；断言本地动态静态响应仍支持 GET/HEAD、目录 404/403、头部一致。

2. 统一响应与绑定错误

本地 internal/server/httpx/response.go 与 GVA server/model/common/response/response.go 均定义 CodeSuccess=0、CodeError=7、CodePasswordChangeRequired=10001，正常/业务失败均 HTTP 200 envelope。NoAuth 是 401 且 data:null；MustChangePwd 是 409；Recovery 普通 panic 是 500 空响应；CORS 拒绝 403；限流是 200 + code 7。handler 统一在 ShouldBindJSON/ShouldBindQuery 失败时写 code 7，未引入 Gin 默认 400。

测试建议：每类 endpoint 发送 malformed JSON、类型错误 query、缺字段 JSON，比较 status、code、data 和 msg；覆盖 401/409/403/429-like（实际 200）/500。

3. JWT、刷新和多点登录

GVA middleware/jwt.go 先检查 blacklist，再解析 token；临近过期时签发新 token，并回写 new-token、new-expires-at 和 cookie。登录在多点模式下将旧 Redis JWT 加入 blacklist，再写入新 active token。Kra middleware/auth.go 通过 AuthService.AuthenticateToken 完成同一顺序，并在刷新时回写相同 headers/cookie；登录 usecase 的 RotateActiveToken 在多点模式作废旧 token，刷新则传空 old token 保持旧 token 不被提前作废。Kra 用 jwt_blacklists 持久化查询并对同一 token 使用 singleflight，GVA 使用无错误返回的缓存 blacklist；因此数据库故障时 Kra 会把所有 token 映射为“异地登陆或令牌失效”并拒绝请求，而 GVA 仍可能继续 JWT 解析。这是故障语义差异，需在部署策略和回归测试中明确。

4. MustChangePwd、Casbin、DataScope

两端允许列表完全一致：/user/changePassword、/user/getUserInfo、/jwt/jsonInBlacklist。Kra AccessControl 会去掉 router-prefix 后按 authority_id + path + method 授权，并在同一 request context 注入 DataScope/Actor；GVA CasbinHandler 做相同 prefix trim，随后 DataScope 注入数据域身份。Kra 的授权实现每请求读取数据库并构造 Casbin model，GVA 使用全局 enforcer 缓存；所以 Kra 写策略后即时可见，而 GVA 依赖 FreshCasbin 或写路径主动 reload。

GET /api/freshCasbin 是明确缺口：GVA 调 e.LoadPolicy()，失败返回 HTTP 200/code 7/“刷新失败”；Kra handler 直接 HTTP 200/code 0/“刷新成功”，且不会暴露加载失败。即便 Kra 当前无内存 enforcer，该接口的可观察错误语义仍不一致。

5. CORS、限流与 metadata

CORS 代码实现本身的 allow-all、strict-whitelist、匹配 origin、OPTIONS 204、GET /health 例外和头部名称与 GVA helper 相近，但基准 server/initialize/router.go 将 Cors/CorsByRules 两行都保留为注释，默认并未安装该 middleware；Kra 在 NewGinEngine 中无条件安装并每次读取 runtime。因此在 strict-whitelist 或 allow-all 配置下，Kra 会拒绝/放行并添加 CORS 头，而基准仍按普通路由处理。若部署契约要求启用 CORS，应在基准与本地明确同样的安装开关；否则应把该差异视为 P1。

登录/验证码限流的窗口、超限响应、缓存异常 fail-open 一致，但作用面不完全相同：GVA 只在 POST /base/login、POST /base/captcha 路由挂 SecurityLimit()，Kra 则在全局 middleware 中按 URL 后缀匹配，未匹配路由或其他方法也可能读取/递增计数。两端 key 前缀仍不同：Kra KRA_SecLimit，GVA GVA_SecLimit。滚动部署共享缓存时会导致计数不共享，建议统一前缀或明确迁移策略。

RequestMeta 两端都位于最前，生成/透传 request id、trace id、span id，并按合法 traceparent 优先、X-Trace-Id 回退；响应头和 context 字段一致。AccessLog 都只读一次 body、包装一次 writer、脱敏敏感 JSON/header、响应捕获上限 1 MiB，并记录 route/status/latency/bytes/identity/request/trace metadata。

版本响应头是第二个明确可见差异：GVA 写 X-Gva-Version，Kra 写 X-Kra-Version。如果前端、网关或探针按 GVA header 读取版本，这会造成兼容性缺口；建议双写过渡或在契约中明确新 header。

6. Operation/Error audit 与 recovery

GVA 通过各资源 router group 的 Use(middleware.OperationRecord()) 选择写操作；Kra 在全局 Private 后通过 recordsOperation 白名单按 method+route suffix 选择，已迁移的 user/api/authority/menu/department/position/dictionary/params/security/system/token/version/export/error/login-log/data-access/timed-task/info/email 路径均有覆盖。sysError/getSysErrorSolution 属 LLMAuto，按要求不纳入。

两端 operation audit 均复用 AccessLog 的 request/response capture，GET 将 query 转为 JSON，multipart 写 [文件]，下载响应超限写 [超出记录长度]，并记录 request/trace/device metadata。GVA logger core 和 Kra logging error sink 都会将 Error 级别日志落入 sys_error；Kra ErrorAudit 额外把未预期的 code 7 envelope 提升为 error log，并排除已知客户端失败、sysError/logViewer 自记录，避免重复。

Recovery 对 broken pipe 只记录并 abort，普通 panic 记录请求/stack 并返回 500；行为一致。

修复/验证计划（按优先级）

1. P1 路由集合与 API sync/seed：决定静态文件是否应纳入 API/route-table 同步。若要严格 GVA parity，应注册与 GVA 同形的 GET/HEAD static wildcard，并以 store-path 作为 URL；若保留动态 NoRoute，应在 sync/seed 明确排除并补文档/测试。额外覆盖非空 router-prefix，并保留两端 Swagger 对静态路由的已验证口径。
2. P1 FreshCasbin：让 freshCasbin 调用实际策略刷新或至少执行数据库/缓存可用性检查；失败返回 GVA 相同的 code 7 envelope。增加故障注入测试。
3. P1 router-prefix sync：明确数据库中的 API path 是带前缀还是无前缀；当前 Kra NormalizeRoutePath 去前缀，而 GVA GVA_ROUTERS 直接保留前缀。选择兼容策略并覆盖初始化、syncApi、Casbin authorize 三条链路。
4. P1 CORS 启用策略：让 CORS 是否安装由与 GVA 相同的部署开关决定，或把 Kra 的无条件 CORS 明确记录为专有契约；覆盖 strict/allow-all/OPTIONS。
5. P2 版本头：兼容期双写 X-Gva-Version 与 X-Kra-Version，并增加 header contract test。
6. P2 限流与黑名单故障：收窄限流到两个 POST route，统一/双读 GVA_SecLimit key，并明确黑名单存储故障的 fail-open/fail-closed 行为。
7. P2 横切回归：运行 malformed binding、JWT expired/refresh/multipoint/blacklist-store failure、MustChangePwd allow-list、Casbin deny/fresh failure、DataScope ownership、CORS strict/OPTIONS、rate-limit fail-open、GET/HEAD static、operation/error audit、panic/broken-pipe 的 HTTP 集成测试。
8. P3 文档兼容：决定是否把无前缀 Swagger basePath 从 "/" 调整为空字符串，并固定 snapshot 规则。