b933f06bdd
- 添加 supply-api/README.md (R-06 文档完善) - 更新 main.go TODO注释标记 DatabaseAuditService 已创建 R-05, R-06 低优先级任务完成。
185 lines
4.8 KiB
Markdown
185 lines
4.8 KiB
Markdown
# 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
|