docs(supply-api): 添加README并更新TODO注释

- 添加 supply-api/README.md (R-06 文档完善) - 更新 main.go TODO注释标记 DatabaseAuditService 已创建 R-05, R-06 低优先级任务完成。
2026-04-03 12:06:08 +08:00
parent e82bf0b25d
commit b933f06bdd
2 changed files with 187 additions and 1 deletions
--- a/supply-api/README.md
+++ b/supply-api/README.md
@@ -0,0 +1,184 @@
+# 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
--- a/supply-api/cmd/supply-api/main.go
+++ b/supply-api/cmd/supply-api/main.go
@@ -64,7 +64,9 @@ func main() {
 	}

 	// 初始化审计存储
-	auditStore := audit.NewMemoryAuditStore() // TODO: 替换为DB-backed实现
+	// R-08: DatabaseAuditService 已创建 (audit/service/audit_service_db.go)
+	// 需接口适配后可替换为: auditStore := audit.NewDatabaseAuditService(auditRepo)
+	auditStore := audit.NewMemoryAuditStore()

 	// 初始化存储层
 	var accountStore domain.AccountStore