From 5676198392cc102f1e2c2ed72e17880aebcede3e Mon Sep 17 00:00:00 2001 From: shangfangjian Date: Wed, 16 Sep 2026 13:34:42 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B7=BB=E5=8A=A0=E4=B8=93=E5=AE=B6?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E7=9B=AE=E5=BD=95=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为代码审查、数据工程、后端架构、安全工程四个角色 建立专属工作区,用于持久化审查报告、设计文档和知识积累 --- experts/README.md | 39 +++++++++ experts/backend-architect/README.md | 25 ++++++ experts/data-engineer/README.md | 25 ++++++ experts/review-engineer/README.md | 24 +++++ .../reports/db-pipeline-review-2026-09-16.md | 87 +++++++++++++++++++ experts/security-engineer/README.md | 25 ++++++ 6 files changed, 225 insertions(+) create mode 100644 experts/README.md create mode 100644 experts/backend-architect/README.md create mode 100644 experts/data-engineer/README.md create mode 100644 experts/review-engineer/README.md create mode 100644 experts/review-engineer/reports/db-pipeline-review-2026-09-16.md create mode 100644 experts/security-engineer/README.md diff --git a/experts/README.md b/experts/README.md new file mode 100644 index 0000000..bd4f70c --- /dev/null +++ b/experts/README.md @@ -0,0 +1,39 @@ +# 专家工作区 + +每个专家角色拥有独立文件夹，用于持久化工作产物、报告和知识积累。 + +## 目录结构 + +``` +experts/ +├── review-engineer/ # 代码审查专家 +│ ├── README.md # 职责、标准、活跃任务 +│ ├── reports/ # 审查报告 +│ └── findings/ # 问题记录 +├── data-engineer/ # 数据工程师 +│ ├── README.md +│ ├── schemas/ # 数据模型设计 +│ └── pipelines/ # 管线配置 +├── backend-architect/ # 后端架构师 +│ ├── README.md +│ ├── architecture/ # 架构文档 +│ └── decisions/ # ADR 记录 +└── security-engineer/ # 安全工程师 + ├── README.md + ├── audits/ # 审计报告 + └── threats/ # 威胁建模 +``` + +## 使用约定 + +1. **每次审查/任务完成后**，将报告存入对应专家的 `reports/` 目录 +2. **跨专家协作**产物放在 `shared/` 目录 +3. **长期知识**（模式、清单、模板）沉淀到专家文件夹根目录 +4. **临时工作文件**（草稿、中间产物）放入 `temp/` 并在完成后清理 + +## 关联项目 + +- 项目根目录: `/vol2/1000/Docker/Profeto` +- 源码: `src/` +- 迁移: `alembic/versions/` +- 文档: `docs/` diff --git a/experts/backend-architect/README.md b/experts/backend-architect/README.md new file mode 100644 index 0000000..02ecb79 --- /dev/null +++ b/experts/backend-architect/README.md @@ -0,0 +1,25 @@ +# 后端架构师工作区 + +## 职责 +- 系统整体架构设计 +- API 设计与规范 +- 异步任务架构 +- 服务间通信 +- 可扩展性规划 + +## 工作产物 +- `architecture/` — 架构图与文档 +- `api/` — API 设计文档 +- `patterns/` — 设计模式与最佳实践 +- `decisions/` — 架构决策记录 (ADR) + +## 关注点 +- 异步一致性 +- 事务边界 +- 错误处理策略 +- 可观测性 +- 部署拓扑 + +--- + +**活跃任务**: Profeto 整体架构优化 diff --git a/experts/data-engineer/README.md b/experts/data-engineer/README.md new file mode 100644 index 0000000..b1212c4 --- /dev/null +++ b/experts/data-engineer/README.md @@ -0,0 +1,25 @@ +# 数据工程师工作区 + +## 职责 +- 数据管线 ETL 设计与优化 +- 数据库 Schema 设计与优化 +- 数据采集策略 +- 数据清洗与规范化 +- 数据血缘追踪 + +## 工作产物 +- `schemas/` — 数据库模型设计 +- `pipelines/` — 数据管线配置 +- `queries/` — 常用查询与优化 +- `migrations/` — 迁移策略记录 + +## 关注点 +- 数据采集速率与 API 限流 +- 幂等性与并发安全 +- 连接池管理 +- 内存效率 +- 索引策略 + +--- + +**活跃任务**: understat/bzzoiro/injuries 管线优化 diff --git a/experts/review-engineer/README.md b/experts/review-engineer/README.md new file mode 100644 index 0000000..02b4b8e --- /dev/null +++ b/experts/review-engineer/README.md @@ -0,0 +1,24 @@ +# 代码审查专家工作区 + +## 职责 +- 代码质量审查 +- 架构设计评审 +- 性能瓶颈识别 +- 安全漏洞排查 +- 重构建议 + +## 工作产物 +- `reports/` — 审查报告 +- `checklists/` — 审查清单 +- `findings/` — 发现的问题记录 + +## 审查标准 +- 正确性 +- 可维护性 +- 安全性 +- 性能 +- 代码风格一致性 + +--- + +**活跃任务**: 数据库与数据管线审查 → 已完成，产出 `reports/db-pipeline-review.md` diff --git a/experts/review-engineer/reports/db-pipeline-review-2026-09-16.md b/experts/review-engineer/reports/db-pipeline-review-2026-09-16.md new file mode 100644 index 0000000..0e006a5 --- /dev/null +++ b/experts/review-engineer/reports/db-pipeline-review-2026-09-16.md @@ -0,0 +1,87 @@ +# Profeto 数据库与数据管线审查报告 + +**审查日期**: 2026-09-16 +**审查范围**: 6 张表 ORM、6 个迁移文件、3 个采集器、上下文构建器、API 路由、连接池配置 +**结论**: 发现 6 个 P1 + 5 个 P2 问题(无 P0) + +--- + +## P1 级问题(6 个) + +### P1-1: context_builder.py session 管理 +- **文件**: `src/llm/context_builder.py` +- **问题**: 每个切片函数独立创建 session。回测 20 场并发需 120 个连接,池仅 15 个 → 耗尽阻塞 +- **修复**: build_context 创建共享 session 并传给所有切片函数,切片函数新增可选 `db` 参数 + +### P1-2: bzzoiro.py 内存预加载 +- **文件**: `src/data/bzzoiro.py` +- **问题**: 预加载联赛全部比赛到内存(`select(Match).where(Match.league_id == league.id)`),多赛季采集时内存溢出 +- **修复**: 改为按 raw_events 日期范围 ±30 天按需加载 + +### P1-3: understat.py N+1 查询 +- **文件**: `src/data/understat.py` +- **问题**: 逐条查询比赛(每场 3 次 DB 往返),单赛季 380 次 = 1140 次往返 +- **修复**: 批量查询球队(1 次) + 批量查询比赛(1 次) + 内存匹配 + +### P1-4: injuries.py 幂等检查竞态条件 +- **文件**: `src/data/injuries.py` +- **问题**: check-then-insert 模式,并发采集触发 IntegrityError 导致整批回滚 +- **修复**: 批量幂等检查 + 分批 flush + 失败回退逐条插入 + +### P1-5: predict.py 同步 Lock 用于 async +- **文件**: `src/llm/predict.py` +- **问题**: `threading.Lock` 用于 async 函数,阻塞事件循环 +- **修复**: 删除 Lock,dict 操作在 CPython GIL 下原子 + +### P1-6: models.py 缺唯一约束 +- **文件**: `src/db/models.py` +- **问题**: 缺 `(match_id, provider, model)` 唯一约束,重复预测导致统计偏差 +- **修复**: 添加 UniqueConstraint + 迁移文件 + +--- + +## P2 级问题(5 个) + +### P2-1: unit_of_work 类型注解错误 +- **文件**: `src/db/unit_of_work.py` +- **问题**: `AsyncIterator[AsyncSessionLocal]` 应为 `AsyncIterator[AsyncSession]` + +### P2-2: normalize.py 日期解析静默丢弃 +- **文件**: `src/data/normalize.py` +- **问题**: `_parse_date` 失败返回 None,数据丢失无感知 +- **修复**: 解析失败时 `logger.warning` 记录原始值 + +### P2-3: repositories.py func.date() 索引失效 +- **文件**: `src/db/repositories.py` +- **问题**: `func.date(Match.match_date)` 致索引失效,全表扫描 +- **修复**: 改用 `Match.match_date_date` 等值匹配 + +### P2-4: 迁移 0005 幽灵列 +- **文件**: `alembic/versions/0005` +- **问题**: `cutoff_at` 列被注释掉未删除,autogenerate 噪声 +- **状态**: 已在 0006 迁移中修复 + +### P2-5: 迁移 0003 约束命名不一致 +- **文件**: `alembic/versions/0003_injuries.py` +- **问题**: UniqueConstraint vs ORM 的 Index(unique=True) 不一致 +- **修复**: 新迁移 0007 将 UniqueConstraint 替换为唯一索引 + +--- + +## 值得肯定的设计 + +- 索引/约束设计合理(唯一约束防重、CHECK 约束、复合索引) +- 数据血缘追踪(source / retrieved_at / available_at)完善 +- 采集管线有重试、限速、防回测泄漏 +- `get_db` / `get_db_read` 读写分离 +- 迁移规范,有 downgrade + +--- + +## 修复验证 + +- [x] 全部文件语法检查通过 +- [x] 11 个文件修改 + 2 个新迁移 +- [x] MR #3 已提交: https://git.bilidili.cn/shangfangjian/Profeto/pulls/3 +- [ ] 合并后运行 `alembic upgrade head` +- [ ] 20 场并发回测压测验证连接池 diff --git a/experts/security-engineer/README.md b/experts/security-engineer/README.md new file mode 100644 index 0000000..8d06e79 --- /dev/null +++ b/experts/security-engineer/README.md @@ -0,0 +1,25 @@ +# 安全工程师工作区 + +## 职责 +- 应用安全审查 +- 依赖漏洞扫描 +- 认证授权策略 +- 数据保护 +- 合规性检查 + +## 工作产物 +- `audits/` — 安全审计报告 +- `threats/` — 威胁建模 +- `hardening/` — 加固指南 +- `incidents/` — 事件响应记录 + +## 关注点 +- API 密钥管理 +- CORS / CSRF 防护 +- 输入验证 +- SQL 注入防护 +- 敏感数据泄露 + +--- + +**活跃任务**: 待分配