# Supply API

> 供应链管理 API 服务

## 项目概述

Supply API 是一个基于 Go 的微服务，提供供应链管理功能，包括：

- **账户管理** - 供应商和消费者账户的 CRUD 操作
- **套餐管理** - 供应链套餐的发布、下架和管理
- **结算服务** - 供应链结算和提现处理
- **收益服务** - 收益记录和账单汇总
- **审计日志** - 完整的审计日志记录和查询
- **IAM (身份和访问管理)** - 多角色权限系统

## 技术栈

- **语言**: Go 1.21+
- **数据库**: PostgreSQL 15+
- **缓存**: Redis
- **框架**: 标准库 + 自定义中间件
- **测试**: Go testing + testify

## 项目结构

```
supply-api/
├── cmd/
│   └── supply-api/           # 主程序入口
│       └── main.go
├── internal/
│   ├── audit/                # 审计日志模块
│   │   ├── model/           # 审计事件模型
│   │   ├── service/         # 审计服务
│   │   ├── handler/         # HTTP 处理器
│   │   ├── repository/      # 数据库仓储 (R-09)
│   │   ├── sanitizer/      # 敏感信息脱敏
│   │   └── events/         # 事件定义 (CRED, SECURITY)
│   ├── iam/                 # IAM 模块
│   │   ├── model/          # 角色、权限模型
│   │   ├── service/         # IAM 服务
│   │   ├── handler/         # HTTP 处理器
│   │   ├── middleware/      # 权限中间件
│   │   └── repository/     # 数据库仓储 (R-08)
│   ├── domain/              # 领域模型
│   ├── middleware/           # HTTP 中间件
│   ├── repository/           # 通用数据仓储
│   ├── cache/                # Redis 缓存
│   └── config/               # 配置管理
├── sql/
│   └── postgresql/           # 数据库 DDL 脚本
│       ├── platform_core_schema_v1.sql
│       ├── iam_schema_v1.sql           # IAM 表 (R-07)
│       └── supply_idempotency_record_v1.sql
└── scripts/
    └── migrate.sh            # 数据库迁移脚本
```

## 模块说明

### IAM 模块 (多角色权限)

| 功能 | 说明 |
|------|------|
| 角色管理 | super_admin, org_admin, supply_admin, operator, developer, finops, viewer |
| 权限范围 | 细粒度 scope 权限控制 |
| 角色继承 | 支持角色层级继承 |
| 中间件验证 | ScopeAuth 中间件 |

**文件**:
- `internal/iam/model/` - 角色、权限模型
- `internal/iam/service/` - IAM 服务层
- `internal/iam/middleware/` - 权限验证中间件

### Audit 模块 (审计日志)

| 功能 | 说明 |
|------|------|
| 事件记录 | CRED/AUTH/DATA/SECURITY 事件分类 |
| 幂等性保证 | IdempotencyKey 支持 |
| 敏感信息脱敏 | 自动扫描和掩码 |
| 指标统计 | M-013/M-014/M-015/M-016 |

**文件**:
- `internal/audit/model/` - 审计事件模型
- `internal/audit/service/` - 审计服务
- `internal/audit/handler/` - HTTP API
- `internal/audit/sanitizer/` - 敏感信息脱敏

### Domain 模块

| Store | 说明 |
|-------|------|
| AccountStore | 账户 CRUD |
| PackageStore | 套餐管理 |
| SettlementStore | 结算处理 |
| EarningStore | 收益记录 |

## API 端点

### 审计 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/audit/events | 创建审计事件 |
| GET | /api/v1/audit/events | 查询事件列表 |

### IAM API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/iam/roles | 创建角色 |
| GET | /api/v1/iam/roles | 列出角色 |
| GET | /api/v1/iam/roles/:code | 获取角色详情 |
| PUT | /api/v1/iam/roles/:code | 更新角色 |
| DELETE | /api/v1/iam/roles/:code | 删除角色 |
| POST | /api/v1/iam/roles/:code/scopes | 分配权限 |
| DELETE | /api/v1/iam/roles/:code/scopes/:scope | 移除权限 |

## 配置

配置文件位于 `config/` 目录：

```yaml
# config/config.dev.yaml
database:
  host: localhost
  port: 5432
  user: supply
  password: ""
  database: supply_db
  max_open_conns: 25
  max_idle_conns: 5
  conn_max_lifetime: 5m

redis:
  host: localhost
  port: 6379
  password: ""
  db: 0
```

## 构建和运行

```bash
# 构建
go build -o supply-api ./cmd/supply-api/

# 运行
./supply-api -env=dev

# 测试
go test ./... -count=1
```

## 测试覆盖率

| 模块 | 覆盖率 |
|------|--------|
| audit/events | 73.5% |
| audit/handler | 83.0% |
| audit/model | 95.0% |
| audit/sanitizer | 79.7% |
| audit/service | 75.3% |
| iam/handler | 85.9% |
| iam/middleware | 83.5% |
| iam/model | 62.9% |
| iam/service | 99.0% |

## 数据库迁移

```bash
# 运行迁移
./scripts/migrate.sh -env=dev
```

## 文档

- [实施状态](./docs/plans/2026-04-03-p1-p2-implementation-status-v1.md)
- [设计文档](./docs/)

## License

Proprietary