lijiaoqiao/docs/experts/00_PROJECT_OVERVIEW.md

# 立交桥项目专家评审 — 项目概况

## 1. 项目基本信息

- **项目名称**：立交桥（lijiaoqiao）
- **路径**：`/home/long/project/立交桥`
- **语言**：Go 1.21/1.22
- **架构**：单体服务（3 个独立进程），保持单体架构不变
- **总规模**：约 170,000 行 Go 代码（不含竞品目录），112 个 .go 文件
- **依赖**：Go modules，无 vendor 目录

---

## 2. 三个核心服务

### 2.1 Gateway（入口网关）

**定位**：OpenAI 兼容入口网关，负责接入鉴权、限流、上游路由、基础审计。

**端口**：8080

**技术栈**：
- 标准库 `net/http`（无 Gin）
- 中间件：Auth、CORS、RateLimit、RequestID 注入
- 路由策略：`latency` / `round_robin` / `weighted` / `availability`（已接入主链路）；`cost_based` / `cost_aware` / `fallback`（实验性，未接入）
- Provider 注册：支持多 provider 配置，动态路由
- 审计发射器：PostgreSQL 或内存

**关键文件**：
- `internal/handler/handler.go` — OpenAI 兼容 HTTP handler（Chat/Completion/Models）
- `internal/middleware/cors.go` — CORS 配置（生产要求显式白名单）
- `internal/app/bootstrap.go` — 启动装配，`BuildMux`
- `internal/router/router.go` — 路由选择、打分

**环境变量**：
- `GATEWAY_ENV`（dev/staging/production）
- `PASSWORD_ENCRYPTION_KEY`（生产必填）
- `GATEWAY_CORS_ALLOW_ORIGINS`（生产必填）
- `GATEWAY_TRUSTED_PROXIES`
- `GATEWAY_TOKEN_RUNTIME_MODE`（inmemory / remote_introspection）

**已修复的安全问题**：
- 生产环境默认密钥检测并 panic
- CORS 生产模式强制显式白名单
- X-Request-ID 字符白名单过滤（防日志注入）
- IP 伪造防护（TrustedProxies 检查）

---

### 2.2 Platform Token Runtime

**定位**：平台级 token 生命周期管理、introspection 与审计查询。

**端口**：18081

**技术栈**：
- 标准库 `net/http`
- Token 生命周期：issue / refresh / revoke / introspect
- Store 实现：内存（dev 默认）+ PostgreSQL（staging/prod 可选）
- 审计事件：内存 / PostgreSQL

**关键文件**：
- `internal/httpapi/token_api.go` — HTTP API（issue/refresh/revoke/introspect/audit-events）
- `internal/auth/service/runtime_store.go` — 内存 runtime store（含并发保护 mutex）
- `internal/auth/service/inmemory_runtime.go` — token 生命周期实现
- `internal/auth/middleware/token_auth_middleware.go` — Bearer token 校验
- `internal/auth/middleware/query_key_reject_middleware.go` — 拒绝外部 query key
- `internal/auth/service/postgres_runtime_store.go` — PostgreSQL 持久化
- `internal/auth/service/postgres_audit_store.go` — PostgreSQL audit store

**环境变量**：
- `TOKEN_RUNTIME_ENV`（dev/staging/production）
- `TOKEN_RUNTIME_DATABASE_URL`（PostgreSQL DSN）

**已修复的安全问题**：
- Refresh 后 TTL 变更持久化到 store
- InMemoryRuntimeStore 并发读写加 RWMutex 保护
- audit-events 接口强制 Bearer token 鉴权

---

### 2.3 Supply API

**定位**：供应链业务服务，负责账户、套餐、结算、审计、IAM、Outbox 与补偿链路。

**端口**：18080

**技术栈**：
- 标准库 `net/http`
- 数据库：PostgreSQL（必选，dev 模式可部分降级）
- SMS 验证（默认关闭态）
- Outbox pattern（事务性发件箱）
- 补偿框架（account.create / package.publish / settlement.withdraw / quota.deduct）

**关键文件**：
- `internal/httpapi/supply_api.go` — 供应侧业务接口（accounts/packages/billing/earnings/settlements）
- `internal/httpapi/alert_api.go` — 告警接口
- `internal/repository/` — DB-backed 仓储与集成测试
- `internal/audit/` — 审计事件、处理器、批量缓冲
- `internal/outbox/` — Outbox processor
- `internal/compensation/` — 补偿执行器（当前 fail-closed）
- `internal/iam/` — IAM 实现（默认关闭，条件启用）
- `internal/domain/settlement.go` — 结算领域模型（含提现门禁）
- `internal/security/kms_service.go` — DEK 派生（HKDF-SHA256）
- `internal/app/bootstrap.go` — 启动装配
- `internal/app/runtime.go` — runtime 构造与依赖注入

**环境变量**：
- `SUPPLY_API_ENV`（dev/staging/production）
- `SMS_VERIFIER_IMPL`（可选）
- `SETTLEMENT_WITHDRAW_ENABLED`（默认 false）
- `SERVER_IAM_ENABLED`（默认 false）

**已修复的安全问题**：
- KMS DEK 派生从简单字节轮换升级为 HKDF-SHA256
- 生产环境强制拒绝 HS256/HS384/HS512（只接受 RSA）
- 补偿执行器从假成功改为 fail-closed
- IP 伪造防护（TrustedProxies 注入）
- BruteForce 暴力破解保护（5 次失败 / 15 分钟锁定）

---

## 3. 数据库

### 3.1 DDL 文件

- `sql/postgresql/token_runtime_schema_v1.sql` — token runtime 表结构
- `sql/postgresql/platform_core_schema_v1.sql` — 平台侧审计事件
- `sql/postgresql/supply_core_schema_v2.sql` — supply-api 核心表（accounts/packages/settlements/earnings）
- `sql/postgresql/partition_strategy_v1.sql` — 分区策略
- `sql/postgresql/outbox_pattern_v1.sql` — Outbox 表
- `sql/postgresql/token_status_registry_v1.sql` — token 状态注册表
- `sql/postgresql/audit_alerts_v1.sql` — 告警审计表

### 3.2 关键数据库模式观察

- `auth_token_runtime` 表存储 token 生命周期数据
- `auth_token_audit_events` 表存储 token 审计事件（token runtime 侧）
- `supply_*` 系列表存储供应侧业务数据
- `outbox` 表实现事务性发件箱模式
- 分区策略：按时间或哈希分区

---

## 4. 测试现状

### 4.1 测试类型

- **单元测试**：各模块内部逻辑测试（`*_test.go`）
- **集成测试**：`supply-api` 仓储层有 `bash scripts/run_integration_tests.sh`
- **E2E 测试**：`supply-api/e2e/production_flow_test.go`（使用 mock 替身，非真实外部依赖）

### 4.2 测试覆盖的关键功能

- Gateway handler 测试（Chat/Completion/Models/error response）
- Token lifecycle 测试（issue/refresh/revoke/introspect）
- Token audit events 测试（query / authorization enforcement）
- Supply API 核心业务流程测试

### 4.3 环境状态 — 无已知环境问题

**所有测试均为纯内存或 PostgreSQL 驱动**，三服务 `go test -count=1 ./...` 全部通过，无任何外部中间件运行时依赖。

以下内容**历史上曾被错误填入**，现已全部清除：
- ~~etcd broker 在 2379~~ — 代码中无 etcd 引用
- ~~Kafka broker 在 9092~~ — 代码中无 Kafka 引用
- ~~AWS CloudWatch 凭据~~ — 代码中无 CloudWatch 引用

早期架构文档（`technical_architecture_design_v1`、`llm_gateway_product_technical_blueprint_v1` 等）中确有 Kafka/etcd 讨论，但那属于**早期设计规划**，实际代码实现时已弃用，文档与实现存在不一致，详见 `TEST_ENVIRONMENT_ISSUES.md`。

---

## 5. CI/CD 与验证

- `scripts/ci/repo_integrity_check.sh` — 仓库级统一验证（已升级为 `go test -count=1`）
- 各模块独立验证：`go test -count=1 ./...`
- Supply API 额外：`bash scripts/run_integration_tests.sh ./internal/repository`
- 迁移脚本：`scripts/migrate.sh`

---

## 6. 文档

- `TEST_ENVIRONMENT_ISSUES.md` — 5 个环境问题记录
- `review/SYSTEMATIC_REPAIR_PLAN_2026-04-17.md` — 21 个问题的修复计划
- `review/REPORT_CORRECTION_2026-04-17.md` — 纠偏版报告
- `docs/plans/2026-04-17-remediation-execution-checklist.md` — 执行清单（13 tasks 全部完成）
- `docs/product/completed_feature_inventory_v1_2026-04-17.md` — 已完成功能清单 v1
- 各服务 README 记录了"当前真实状态"

---

## 7. 项目约束

- **架构约束**：保持单体服务架构，不拆分为微服务
- **优化目标**：代码质量、性能、可靠性、运维简单性
- **已知技术债务**：
  - 立交桥项目是单体架构但实际上代码规模不小，三个服务各自独立，有各自的 DB
  - 有些能力"已写出但未接入主链路"（如高级路由策略）
  - E2E 测试依赖 mock，不等价于真实环境全链路
  - 部分 Go module path 为 `lijiaoqiao/<module>`，对 GOPATH 有一定要求