Files

Your Name 687c4535f8 fix: P0-1 RateLimiter并发写安全 + P0-2工单操作错误码区分 + P1 rows.Close修复

P0-1 (limits.go): Allow()方法改为全程使用写锁保护counters map读写，避免RLock写入时的data race
P0-2 (ticket_workflow.go+ticket_handler.go): Assign/Resolve/Close操作先查询ticket存在性和状态，返回明确的CS_TICKET_4001/CS_TKT_4002/CS_TICKET_4092/CS_TICKET_4093错误码，handler根据错误前缀路由HTTP状态码
P1-1 (ticket_store.go): 移除GetStats中3处手动rows.Close()，只保留defer Close()

2026-05-01 20:56:25 +08:00

2.9 KiB

Raw Blame History

Gateway 模块规则

模块定位

gateway 是对外入口控制层，不是业务真源，也不是 token authority。它的职责是把入口请求安全、稳定、可观测地接进系统，并把鉴权、限流、上游路由、基础审计这些横切关注点处理干净。

这里最重要的是边界清晰、失败可控、兼容性稳定。不要把业务逻辑、授权真相、一次性试验代码偷偷塞进入口层。

第一原则

入口层必须克制。 gateway 负责接入和控制，不负责复制业务语义。尤其不要在这里重新发明 token authority 或供应链业务逻辑。
兼容性是核心资产。对外 OpenAI 兼容接口、状态码、字段格式、错误行为的变更，默认视为高风险变更。
默认保护共享环境。 inmemory、弱鉴权、宽松 CORS、默认密钥等只允许开发环境使用；共享环境和生产环境必须显式 fail-closed。
主链路优先于实验模块。只有接入 cmd/gateway/main.go 启动链路并通过关键验证的能力，才算当前真实交付范围。

运行边界

token authority 的真源在 platform-token-runtime
gateway 只在 remote_introspection 模式下消费 introspection 结果
未显式接入主链路的策略、fallback 模块或实验代码，不得在文档和结论中包装成“已上线能力”

变更前必须先判断

这是协议兼容变更、鉴权变更、路由变更、可观测性变更，还是部署/配置变更？
会不会改变默认安全边界？
会不会影响 /v1/chat/completions、/v1/completions、/v1/models 的兼容性？
会不会影响与 platform-token-runtime 的接口契约？

高风险变更类型

鉴权模式切换
principal 字段语义变化
provider 装配逻辑变化
路由策略默认值变化
CORS、密钥、审计、模型返回结构变化

这些改动默认要求更强验证，不接受“应该没问题”。

验证要求

至少覆盖

主接口 happy path
认证失败路径
上游错误或不可用路径
配置缺失或非法配置路径

涉及兼容层时

必须验证 OpenAI 兼容路径和 /api/v1/* 兼容路径
必须确认响应结构、错误码和关键字段没有无意漂移

涉及安全边界时

必须验证 dev 与非 dev 环境行为不同点
必须确认条件能力未满足时明确拒绝，而不是静默放行

文档规则

README 只记录“当前真实状态”，不要把实验能力写成默认行为
新增策略或接口时，要明确说明是否已经接入主启动链路
对降级、回退、默认值必须写清楚触发条件

禁止事项

不要在 gateway 内承载 token authority
不要把实验路由策略伪装成正式能力
不要让共享环境落到 inmemory 或宽松安全默认值
不要把入口层改成难以观察和排障的黑盒

2.9 KiB Raw Blame History Unescape Escape