# 功能模块

`cpa-ext` 采用组合式模块架构。每个模块拥有清晰的职责、数据和接口，可以独立测试与演进；Core 负责组合业务，插件运行时只负责把 CLIProxyAPI 的能力调用适配到 Core 和相应模块。

## 模块列表

| 模块 | 状态 | 职责 |
| --- | --- | --- |
| [数据模块](data.md) | 设计中 | 定义整个插件流转时共同关注的数据、来源、语义、质量和输出契约 |
| [Core 核心业务模块](core.md) | 设计中 | 组合认证、准入、路由、采集、计费、持久化、统计通知和管理用例，形成完整业务闭环 |
| [插件运行时与 CPA 集成](dev.md) | 设计中 | 负责 ABI/RPC、能力注册、CPA 适配、配置、生命周期、构建和宿主验证 |
| [CPA 数据采集模块](collection.md) | 设计中 | 从 CPA 请求生命周期、用量、管理接口和上游响应取得数据并生成标准事实 |
| [上游账户与配额模块](upstream-accounts.md) | 设计中 | 将 CPA Auth 抽象为稳定上游账户，维护 priority、可绑定性、配额、订阅和账户池 |
| [本地持久化模块](persistence.md) | 设计中 | 使用 SQLite 安全保存事实、账本、目录、快照和可重建聚合 |
| [价格目录与计价政策模块](pricing.md) | 设计中 | 管理价格来源、不可变版本、模型别名、长上下文和 Fast/priority 政策 |
| [计费模块](billing.md) | 设计中 | API Key 套餐、金额额度、请求准入、费用结算和账本 |
| [Key 准入与账户路由模块](access-routing.md) | 设计中 | 决定 Key 是否可用，并可将指定 Key 路由到指定上游账户 |
| [统计分析模块](statistics.md) | 设计中 | 把不可变事实与账本增量处理为可重建聚合、实时查询和权限化展示投影 |
| [HTTP API 模块](api.md) | 设计中 | 冻结管理员与用户接口、精确路径、DTO、金额、错误、权限、分页和幂等契约 |
| [管理与展示 UI 模块](ui.md) | 设计中 | 提供用户金额视图和管理员统计、账户、配额、价格与诊断界面 |
| [安全模块](security.md) | 设计中 | 定义认证旁路防护、secret、租户、账本、网络、native 和供应链安全边界 |
| [部署与运维模块](operations.md) | 设计中 | 构建安装、配置、readiness、监控、备份恢复、升级回滚和故障 Runbook |
| [测试与发布门禁](test-plan.md) | 设计中 | 将业务闭环、故障、安全、性能、容量、soak 和平台兼容转成发布证据 |

跨模块只能通过数据模块定义的明确契约协作。数据模块定义“系统关注什么”，不负责计费、聚合或展示；计费模块不能依赖统计查询才能决定是否放行请求；统计模块不能重新决定一笔请求应该扣多少钱。

## 结构关系

```text
CLIProxyAPI
    │ ABI / JSON RPC
    ▼
Dev runtime & CPA adapters
    │
    ▼
Core application use cases
    ├─ Collection
    ├─ Upstream accounts & quota
    ├─ Access & Routing
    ├─ Pricing policy
    ├─ Billing
    ├─ Statistics query facade
    └─ Management use cases
             │
             ▼
         Persistence

Data contracts：贯穿所有模块
HTTP API：把 Core/Query 用例暴露给管理员和用户
UI：只通过 HTTP API 访问业务
Security / Operations / Test Plan：贯穿设计、实现与发布
```

## 实现顺序

Core 会从第一条纵向链路开始逐步长成，不应等所有领域模块完成后一次编写。推荐顺序：

1. P0 runtime/performance spike：验证双 Go runtime、零常驻 goroutine、SQLite driver、callback-driven pump、schema 3 协商、stream hook RPC 字节量、disable/reconfigure/restart 和 24h soak；失败则确定 sidecar 或 CPA host-contract 改造；
2. 冻结数据契约 v1；
3. 建立 Dev runtime 最小可加载骨架，并完成 required-plugin readiness + sentinel/gateway 门禁；
4. 建立 SQLite、migration、Repository、ProjectionEvent 和 Unit of Work；
5. 打通 Collection 的 durable Request/Execution/Usage 事实链，并建立 UpstreamAccount/Auth 引用目录；
6. 实现不可变 Pricing Snapshot、GPT-5.6/Fast golden cases 和发布流程；
7. 实现 Billing 纯领域计算和不可变账本；
8. 实现 Access/Route，并由 Core 组合出真实请求闭环；
9. 完成插件自管 Key、管理用例和 v1 Management/User API；
10. 实现 Statistics MVP 增量聚合和查询；
11. 实现用户金额页与管理员 UI；
12. 按 Operations 完成打包、备份、监控和升级流程，并通过 Test Plan 全部门禁。

第八步结束时必须先形成最小价值闭环：签发 Key → 金额准入 → 指定 Codex 账户 → 调用 → 按实际 Usage 扣费 → 额度耗尽拒绝。取消、失败和迟到 Usage 也必须在这个闭环中验收，不能留到 UI 阶段。

第一版 c-shared 动态库默认采用 callback-driven maintenance；复杂常驻聚合、归档、备份和 provider refresh 只有 soak gate 通过后才进入动态库，否则由 sidecar/运维命令承担。CPA `home.enabled` 整体不支持，二进制升级要求排空并重启 CPA。

Security 不是最后补做的模块：exclusive/sentinel/gateway、secret 处理、租户 scope 和 fail-closed 从第一条纵向链路就必须实现。每个阶段都执行 Test Plan 对应 gate，不能等发布前一次性补测试。