From 8458cfaae229d20cbaf314a629ce5e8078685682 Mon Sep 17 00:00:00 2001 From: Neo Date: Tue, 5 May 2026 00:20:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(audit):=20Wave=201=20findings=20=E7=AC=AC?= =?UTF-8?q?=E4=BA=8C=E8=BD=AE=E5=8F=8D=E9=A6=88=E8=BF=BD=E5=8A=A0=20(5=20?= =?UTF-8?q?=E9=A1=B9=E6=B7=B1=E5=85=A5=E7=AD=94=E7=96=91)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 回答 Neo 在 01-W1-findings-response.md 上写的 5 个新问题: 1. F1-3 Frozen >1 年 - 本地硬盘 tar.zst 即可, 不必对象存储 2. F2-1 OpenAPI 作用深入浅出 - "厨房菜单 vs 大堂菜单"比喻 + 5 个使用场景 (FastAPI 双层结构 + 28 天 stale 不破坏运行的原因) 3. F2-2 自建 Gitea 优化 - .gitea/workflows/ 替代 GitHub Actions, 默认仍 5 分钟版 (步骤 1+2+5), 启 Actions 可选 4. F3-2 system prompt 计费 - 100% 计入 (Qwen 无 caching 折扣) + 推荐方案 A 全 prompt 入 git 单源 (新增 Wave 5 prompt 治理任务) 5. F3-4 全 API 端点遍历 - ~25-30 端点 / 半天集中改造, 兑现 Wave 0 全览调研价值 (推荐 Wave 5 集中, 不分散) 最终 Wave 总分配: - Wave 1 (进行中): F1-5 - Wave 2 前 (立即): F2-1A 恢复脚本 - Wave 2: F1-1 / F2-1B hook / F3-1 / F3-2A / F3-3 - Wave 4: F1-2 / F1-3 三层归档 / F3-5 - Wave 5: F2-2 tests / F3-4 全 API 沙箱校验 / F3-2B prompt 治理 (新增) 待 Neo 拍板 3 项: - F2-2 是否启 Gitea Actions - F3-2B 全 App prompt 入 git 单源 是否启动 - F3-4 集中 Wave 5 vs 分散 --- .../wave1-findings/01-W1-findings-response.md | 253 ++++++++++++++++++ 1 file changed, 253 insertions(+) diff --git a/docs/_overview/wave1-findings/01-W1-findings-response.md b/docs/_overview/wave1-findings/01-W1-findings-response.md index 21042a8..f4bc76d 100644 --- a/docs/_overview/wave1-findings/01-W1-findings-response.md +++ b/docs/_overview/wave1-findings/01-W1-findings-response.md @@ -50,6 +50,8 @@ tenant-admin 登录: auth.tenant_admins (tenant_admin / site_admin),JWT aud="ten **修正后判定**:**[P1 UX] Wave 4**(数据正确性 Wave,顺手),选 A — 与切 site 行为一致。法律风险表述删除(super_admin 有合法授权)。 +*反馈：选择方案A* + --- ### F1-4 撤销:admin-web 没有 site_admin 登录场景,问题不存在 @@ -109,6 +111,8 @@ tenant-admin 登录: auth.tenant_admins (tenant_admin / site_admin),JWT aud="ten **修正后判定**:**[P1] Wave 4**,选**改良版 D(Hot DB 30 天 + Cold Parquet 按月分区)**。如果你坚持 MD 友好(运维 cat / grep),可以**双写**:Parquet 主存储 + MD 摘要文件(每行 1 句关键字段)用于人眼浏览。 +*反馈：同意你的做法，选择**改良版 D(Hot DB 30 天 + Cold Parquet 按月分区)**。但Frozen(>1 年)使用对象存储，也是放在本地硬盘么？* + --- ## 四、简化方案 @@ -135,6 +139,8 @@ tenant-admin 登录: auth.tenant_admins (tenant_admin / site_admin),JWT aud="ten **修正后判定**:**Wave 5 处理**(主线 5 分钟级动作,跟其他文档收尾合并 1 个 PR)。 +*反馈：我使用自建Gitea服务器，和GitHub没关系啊。再看下方案，进行优化修改。* + --- ## 五、F3-2 实证 — DashScope Qwen3-Max-Preview 计费 @@ -199,6 +205,7 @@ CREATE TABLE biz.cfg_ai_token_price ( 写入策略:Wave 2 第一次种子写入当前价格,后续 DashScope 调价时人工 INSERT 新行(`effective_from = 调价日`,前一行 `effective_to = 调价前一日`)。 +*同意你的调研结果，按这个来。另外，system prompt要不要也计算在内？我是否要更新一版全App的System prompt同步在项目中？* --- ## 六、F3-4 答疑 — "沙箱 4-1 申请 4-5 数据" @@ -236,6 +243,8 @@ WHERE <= app.business_date_now() -- = sandbox_date **修正后判定**:**Wave 5 文档收尾时统一加** + 在 P20 SPEC §3.5 加这条 AC(验收标准)。可在 Wave 1-4 内任何模块改动时顺手加。 +*反馈：这个方式好！友好的交互。但要注意你说说的，所有API数据的端点都要加解析，API和页面，需要全部遍历（之前提过的一个文档全览的一个任务的价值。）让所有页面和功能都适配。* + --- ## 七、F2-1 OpenAPI 历史调研(完成) @@ -260,6 +269,8 @@ WHERE <= app.business_date_now() -- = sandbox_date **修正后判定**:Wave 2 前主线立即执行 A 恢复 + 重抓(零风险),Wave 2-3 加 B 防御。 +*反馈：同意你的建议，吸取教训，建立一些机制，不要让类似事件再发生。另外，我还是不太明白OpenAPI 脚本再本项目中的作用，结合业务，深入浅出的再向我解释下。* + --- ## 八、本次响应后 Wave 重新分配 @@ -292,3 +303,245 @@ WHERE <= app.business_date_now() -- = sandbox_date - [Qwen API Platform](https://qwen.ai/apiplatform) - [Qwen3-Max Review: Open Flagship - TokenMix](https://tokenmix.ai/blog/qwen3-max-review-benchmark-pricing-2026?lang=fr) - [qwen3-max-preview - Portkey](https://portkey.ai/models/dashscope/qwen3-max-preview) + +--- + +## 十、第二轮追加 — Neo 5 个新问题回答 + +### 10.1 F1-3 追问 — Frozen >1 年 用对象存储,**是放在本地硬盘么?** + +**答**:**对**。"对象存储"是技术术语,**不一定是云**,在你项目里**直接本地硬盘即可**。 + +**澄清概念**: + +| 形态 | 定义 | 你项目是否合适 | +|---|---|---| +| 云对象存储 | 阿里云 OSS / 腾讯云 COS / AWS S3 | 不适合(外部依赖 + 要钱) | +| 本地对象存储 | MinIO(开源,本地部署,S3 兼容) | 数据量大时再考虑 | +| **本地文件系统** | `/data/cold/.../frozen/YYYY.tar.zst` | **就用这个最简** | + +**修正后 Frozen 方案**: +- 1 年以上的月份 Parquet 打包成 `frozen/2026.tar.zst`(zstd 压缩,比 gzip 小) +- 放服务器本地硬盘指定目录(如 `/data/cold/ai_run_logs/frozen/`) +- DB index 表记 `frozen_path = '/data/cold/.../2026.tar.zst'`,需要时主线脚本解压查 +- **不必上 MinIO 或 OSS**,直到数据量超过 100GB 再考虑 + +**补充**:这种"本地硬盘冷归档"也是工业常见做法(很多自托管系统都这么干,比如 PostgreSQL WAL 归档)。 + +--- + +### 10.2 F2-1 追问 — OpenAPI 脚本作用 深入浅出 + +**用人话说**:OpenAPI 是后端给前端 / AI 工具 / 测试团队看的"**功能菜单 JSON**",菜单要随后端改动同步更新。 + +**菜单上写什么**: +- 项目有哪些 API(151 个) +- 每个 API 接受什么参数(GET / POST / 必填 / 可选) +- 每个 API 返回什么字段(响应结构) +- 每个 API 的权限要求(super_admin / 任意 admin / 公开) + +**FastAPI 的双层结构**: + +```text +后端运行时 ──→ 自动暴露 GET /openapi.json(实时生成的菜单,永远最新) + ↓ 用 _export_openapi.py 抓 +docs/contracts/openapi/backend-api.json(静态版本,存 git,不启动后端就能查) +``` + +**菜单(backend-api.json)在 NeoZQYY 的 5 个使用场景**: + +| # | 用途 | 当前是否在用 | +|---|---|---| +| 1 | admin-web 前端类型自动生成(openapi-codegen)| **没用**(前端手写 axios)| +| 2 | MCP 工具读 spec(`.mcp.json` 的 `openapi` 配置)→ AI 助手知道项目有哪些 API | **在用**(但 stale 时 AI 不知道新 API)| +| 3 | Swagger UI 渲染(交互式 API 文档页面)| **在用**(后端 `/docs` 路由)| +| 4 | API 变更追踪(diff 新旧 backend-api.json)| 偶尔用 | +| 5 | Wave 1 W1-T7 PRD 撰写自动生成总表 | **本次在用**(发现缺端点)| + +**为什么 28 天没发现 stale**: +- 前端**手写 axios**,不依赖 openapi-codegen 自动生成 → 没"前端自动断"反馈 +- MCP 工具 stale 时 AI 助手只是"不知道某些新 API",不会破坏运行功能 +- Swagger UI 走的是后端运行时 `/openapi.json`,不读 backend-api.json,**也不会受影响** +- **真正会断的是 Wave 1 这种"自动生成 PRD"工作流** — 28 天内没人做这事 + +**菜单与代码的关系比喻**: +- 后端 router 改了 → 相当于厨房新加了一道菜 +- 自动菜单(`/openapi.json`)立刻有这道菜 +- **静态菜单(backend-api.json)需要服务员(脚本)定期把厨房菜单抄到大堂** +- 服务员被误辞退后,大堂菜单 stale 28 天 + +**修复价值**: +- A 恢复脚本 + 重抓:服务员回来了 +- B 加 hook:每次厨房改菜,自动叫服务员 + +--- + +### 10.3 F2-2 追问 — 自建 Gitea,方案优化 + +**修正方案**(对齐 Gitea 自建环境): + +| 步骤 | 动作 | 备注 | +|---|---|---| +| 1 | 删 `.gitignore:71` `tests/` | 不变 | +| 2 | `git add apps/*/tests/` 入仓现有所有测试 | 不变 | +| 3 | (可选)加 `.gitea/workflows/test.yml` Gitea Actions | Gitea 1.20+ 支持 Actions(语法兼容 GitHub Actions),自建 Runner | +| 4 | 不脱敏(Neo 允许)| 不变 | +| 5 | 写审计 | 标"自建 Gitea + 仅本地测,可选 Gitea Actions" | + +**步骤 3 Gitea Actions 是否启用**: +- **启**:Gitea 服务器有富余资源 + 想自动跑测试 + Runner 已配 → 推荐(类似 GitHub Actions 体验) +- **不启**:仅本地跑(Neo 当前前提)→ 跳过这步,5 分钟方案就够 + +**关键差异(对比 GitHub Actions)**: +- 配置文件路径:`.gitea/workflows/*.yml`(不是 `.github/workflows/`) +- 语法 95% 兼容 GitHub Actions +- Runner 在自己服务器(数据不出自己机房,符合 Neo 自建偏好) +- 免费(GitHub Actions 私有仓有 quota,Gitea 自建无限制) + +**修正后判定**:**Wave 5 处理**,默认走 5 分钟版(步骤 1+2+5);如 Neo 需要 CI,Wave 5 末尾追加步骤 3。 + +--- + +### 10.4 F3-2 追问 — system prompt 计费 + 全 App prompt 同步项目 + +#### 问题 A:system prompt 是否计入 token 费用? + +**答**:**100% 计入**。 + +DashScope 计费规则: +- `input_tokens` = system_prompt tokens + 历史消息 tokens + 本次 user 消息 tokens +- 每次调用都会重新算一遍 system prompt(没有"prompt 缓存折扣") + +**示例**: +- system prompt 长 1000 字符(中文)≈ 600 tokens +- 1000 次调用累计 = 60万 input tokens +- 60万 × ¥8.64/1M = **¥5.18**(单 system prompt 部分一年的成本) + +**优化建议**: +- 精简 system prompt(每减 100 字 → 一年省 ~¥1) +- 不要把"几乎不变的业务字典"塞 system prompt(可以塞 user prompt 末尾,某些 model 支持 prompt cache) +- Qwen 系列**没有 prompt caching 折扣**(Anthropic / OpenAI 部分模型有),所以全量计费 + +#### 问题 B:是否要更新一版全 App 的 system prompt 同步在项目中? + +**强烈推荐 A 全 prompt 入 git 作为权威源**。 + +**当前现状**(P2-6 调研发现): +- 8+1 个 APP 的 prompt 一部分在百炼云端控制台,一部分在 git (`apps/backend/app/ai/prompts/app[N]_*_prompt.py`) +- **双源风险**:云端调优后 git 没同步,或 git 改了云端没更新 → 实际运行用的是哪个? + +**3 套方案对比**: + +| 方案 | 描述 | 优 | 劣 | +|---|---|---|---| +| **A 全 prompt 入 git + SDK 显式传**(推荐)| 调用 dashscope SDK 时传 `prompt_template` 用 git 版本,云端控制台 prompt 仅作开发调试用 | git 是唯一权威 + 可 diff / blame | 工作量大,需要把云端现有 prompt 全部导出入 git | +| B 仅 git 备份 + 云端权威 | 每月手工导出云端 prompt 到 git docs | 简单 | 易过期,不可追溯 | +| C 维持现状 | 双源分裂 | 0 改 | 完全不可追溯 | + +**A 实施步骤**: +1. 先做"勘察":列出 8+1 个 APP 哪些 prompt 在云端、哪些在 git +2. 把云端 prompt 全部导出到 `apps/backend/app/ai/prompts/`(每 APP 一文件) +3. SDK 调用改为传 `prompt_template = open(prompt_file).read()` +4. 云端控制台 prompt 标"已废弃,以 git 为准"或直接清空 +5. 写 SPEC `docs/prd/specs/PXX-ai-prompt-governance.md` 约定"git 单源" + +**关联 P2-6 决策**:Neo P2-6 反馈"暂时不改 prompt 我同意,但要记录后续观察的需求,需要跟踪" — 本项 B 是这个跟踪的具体落地。 + +**修正后判定**:**新增 Wave 任务 — Wave 5 prompt 治理**(Wave 5 文档收尾时统一处理,因为不阻塞功能)。 + +--- + +### 10.5 F3-4 追问 — 全 API 端点遍历改造工作 + +**Neo 的关联**: +> 注意你说说的,所有 API 数据的端点都要加解析,API 和页面,需要全部遍历(之前提过的一个文档全览的一个任务的价值。)让所有页面和功能都适配。 + +**完全正确**。这就是 **Wave 0 全览调研的价值兑现**。 + +**覆盖范围估算**(基于 Wave 0 已有矩阵): + +| 来源 | 端点数 | 需加 sandbox 校验子集 | +|---|---|---| +| 02b admin-web 矩阵 | 19 路由 | ~8 个(board / runtime-context / db-viewer / 大部分 admin_ai)| +| 02a 小程序矩阵 | 21 页 → ~25 业务 API | ~15 个(board-finance/customer/coach + performance + customer-records + ...)| +| tenant-admin(未在 Wave 0 矩阵但需补) | ~10 个 | ~5 个 | +| 批 1 PRD 23 端点 | — | 已覆盖部分 | +| **合计** | — | **~25-30 个端点需校验** | + +**实施方式**(集中而非分散): + +```python +# apps/backend/app/services/runtime_context.py +def assert_query_within_sandbox( + site_id: int, + query_dates: list[date], # 用户传入的所有日期参数 +) -> None: + """ + 沙箱模式下校验:用户查询的日期不能超过 sandbox_date。 + 超过则抛 HTTPException(422, "沙箱日期 X,无法查询晚于此日期的数据")。 + """ + ctx = get_runtime_context(site_id) + if ctx.mode != "sandbox": + return # live 模式不校验 + for d in query_dates: + if d > ctx.business_date: + raise HTTPException( + status_code=422, + detail=f"当前为沙箱模式 {ctx.business_date},不能查询晚于此日期的数据(请求 {d})", + ) +``` + +各 service 调用方: + +```python +# 任何接受日期 query 的端点 +@router.get("/board/finance") +async def get_board_finance( + start_date: date, + end_date: date, + user: CurrentUser = Depends(...), +): + assert_query_within_sandbox(user.site_id, [start_date, end_date]) # 1 行 + # 后续业务逻辑不变 +``` + +**总工作量**: +- 1 个 helper 函数(15 分钟) +- ~25-30 处端点各加 1 行调用(每处 2 分钟,合计 1 小时) +- P20 SPEC §3.5 加这条 AC(10 分钟) +- 走查测试每端点 5-10 分钟,合计 ~3-4 小时 +- **总和:半天工作量**(零分散) + +**这正是 Wave 0 全览的回报**:不需要重新摸排哪些端点要改,矩阵已列出。 + +**修正后判定**: +- **集中改造**(不在各 Wave 顺手加)→ **Wave 5 末尾专门做一批**,半天搞定 +- 关联 Wave 0 矩阵作为校核清单(Wave 5 末打钩"30 个端点已覆盖") +- P20 SPEC §3.5 加 AC + §14.4 走查清单加这条 + +--- + +## 十一、本次响应后 Wave 总分配(最终版) + +| Wave | 主题 + 新增 | +|---|---| +| **Wave 1**(进行中) | + F1-5 沙箱 batch-run 接入 runtime_context | +| **Wave 2 前(立即)** | F2-1 恢复 OpenAPI 抓取脚本(从 _DEL/ 拉回 + 重抓 + 入仓)| +| **Wave 2** | F1-1 长事务幂等 + F2-1B 加 hook + F3-1 cache 粒度 + F3-2 SCD2 配置表 + F3-3 audit_log + 二次确认 | +| **Wave 4** | F1-2 切 site 过滤 UX + F1-3 Hot/Cold/Frozen 三层 + F3-5 unified 分页 | +| **Wave 5** | F2-2 tests/ 入仓(Gitea 简版)+ F3-4 全 API 沙箱校验集中改造(半天 + 30 端点)+ **F3-2B prompt 治理(全 prompt 入 git 单源)**(新增)| +| **撤销** | F1-4 | + +## 十二、还需要 Neo 拍板的 3 项 + +| # | 问题 | 我的建议 | +|---|---|---| +| F2-2 | 是否启 Gitea Actions(还是仅本地跑)| 看 Neo 自建 Gitea 是否方便 — 不强求 | +| F3-2B | 全 App prompt 入 git 单源(选 A)是否启动 | **Y**,Wave 5 处理 | +| F3-4 | 集中 Wave 5 改造(半天)vs Wave 1-4 分散加 | **集中 Wave 5**(避免分散遗漏)| + +回答这 3 项,Wave 1 findings 完整收口。F2-1 恢复脚本可以现在就做(零风险 5 分钟)。 + +--- + +> 下一轮 Neo 反馈完成后,主线立即按最终 Wave 分配执行。Wave 1 仅剩 W1-T8 §14 走查 + F1-5 沙箱 batch-run 接入 runtime_context 两项即可收尾。