docs(audit): Wave 1 findings 第二轮反馈追加 (5 项深入答疑)

回答 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 分散

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 <date_column> <= 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 <date_column> <= app.business_date_now()  -- = sandbox_date
 
 **修正后判定**:Wave 2 前主线立即执行 A 恢复 + 重抓(零风险),Wave 2-3 加 B 防御。
 
+*反馈：同意你的建议，吸取教训，建立一些机制，不要让类似事件再发生。另外，我还是不太明白OpenAPI 脚本再本项目中的作用，结合业务，深入浅出的再向我解释下。*
+
 ---
 
 ## 八、本次响应后 Wave 重新分配
@@ -292,3 +303,245 @@ WHERE <date_column> <= 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 两项即可收尾。