# 晴天历史 — Qingtian V2 Architecture — 2026-08-21

## 数据层

### Conversation

- 存储位置：`/data/qingtian/conversations/`
- 语义：当前 GPT Action 实际提交的 Conversation snapshot。
- 不保证 snapshot 等同于完整、原始、不可变的 ChatGPT transcript。
- Server 不补齐缺失消息。
- Server 不修改 message content。
- `role` 只允许 `user` 或 `assistant`。
- 客户端没有提供 timestamp 时，Server 不伪造消息时间。
- `updateTodayConversation` 保持 replace-snapshot 语义，不改为 append。

### WorkLog

- 存储位置：`/nas/Qingtian/WorkLog/`
- 语义：明确保存的实际工作事实。
- 当前采用 JSONL append 模式。
- 没有明确实际工作内容时，`worklog/from-text` 不保存为已完成工作。
- WorkLog 是 Daily Summary / Detail 的重要事实来源。

### Daily Records

- 存储位置：`/nas/Qingtian/Records/`
- 每日文件：
  - `YYYY/MM/YYYY-MM-DD.md`
  - `YYYY/MM/YYYY-MM-DD-detail.md`
- Summary / Detail 是基于已确认事实生成的人类可读记录。
- 当前 API 负责今天记录的读取与覆盖写入。
- Server 不使用 LLM 判断 Summary / Detail 的语义正确性。

### History

- Qingtian History：`/nas/Qingtian/Qingtian-History/`
- FRO History：`/nas/Qingtian/FRO-History/`
- History 保存长期架构、决定、完成事项和经过后续验证仍成立的项目事实。
- History 与每日 Records 分离。

## V2 原则

1. Conversation 是 snapshot，不宣称完整 transcript。
2. WorkLog 是实际完成工作的事实记录。
3. Daily Summary / Detail 是事实源的派生记录。
4. Server 负责 deterministic validation，不负责猜测 Conversation 完整性。
5. 不通过 message_count 判断 snapshot 哪个版本“更正确”。
6. 不把 append 与 replace 混用，以避免重复 Conversation。
7. 不在 Conversation message 中伪造 timestamp。
8. 数据层之间保持明确边界，避免 Daily Record 反向伪造 Conversation 或 WorkLog。

## 当前状态

- V1 Audit 已完成。
- Conversation schema hardening 已完成。
- V2 数据架构正式确定。
- 下一阶段：Daily Record deterministic validation 与原子更新设计。

## Git

- `3fc34c5` — `Harden Qingtian conversation snapshot schema`

## Fact Source Policy

- WorkLog 是“实际完成工作”的首要事实来源。
- Conversation 是当前可获得的用户 / Assistant 对话 snapshot。
- 已确认的 NAS 信息只能记录实际验证过的状态。
- Daily Summary / Detail 只能记录上述来源能够支持的事实。
- 无法从当前事实来源确认的内容，不得写成已经完成。
- `updateQingtianRecord` 负责确定性保存已经生成的 Summary / Detail，不负责重新判断事实真伪。
- 当前 V2 不增加独立的 fact/source schema。

## Fact Source Audit — 2026-08-20

- `2026-08-20.jsonl` WorkLog 文件实际存在，但内容只有一个换行符，未包含任何 WorkLog JSON record。
- 最近 24 小时 Docker 日志中未发现 `/qingtian/worklog/from-text` 或 `/qingtian/worklog/today` 请求。
- 因此当前没有服务器端证据证明 2026-08-20 WorkLog 曾成功持久化。
- Conversation 中关于 WorkLog “保存成功”的 Assistant 内容不能单独作为 WorkLog 持久化成功的证明。
- 当前 2026-08-20 Daily Record 不在本次审计中自动修改。
- V2 原则：Action 的成功文字与 Server 实际返回结果、NAS 实际数据必须区分；只有实际验证的持久化结果才能作为事实来源。


## WorkLog Action Verification — 2026-08-21

- `POST /qingtian/worklog/from-text` 已通过本机实际请求验证。
- Payload `{"text":"V2 schema probe","work":""}` 返回 HTTP 200。
- 返回结果为 `status: received`、`saved: false`。
- 因为 `work` 为空，本次请求没有写入 WorkLog。
- 该测试确认 HTTP 200 本身不能证明 WorkLog 已保存。
- WorkLog 持久化成功必须以实际返回 `saved: true` 为依据，并可进一步通过 WorkLog GET 或 NAS 文件验证。


## Action Execution Audit — 2026-08-20

- 2026-08-20 Conversation snapshot 中明确记录用户要求调用 `saveWorkLogFromText`。
- 随后的 Assistant message 声称 WorkLog 已成功保存。
- 服务器过去 48 小时访问日志中没有对应的 `/qingtian/worklog/from-text` POST。
- `/nas/Qingtian/WorkLog/2026/08/2026-08-20.jsonl` 实际只有一个换行符，没有 WorkLog JSON record。
- 因此 Conversation 中的 Action 请求文本和 Assistant 成功陈述，均不能单独证明 Action 实际执行或数据已经持久化。
- V2 事实链必须区分：Conversation 中的操作叙述、Server 实际 HTTP 请求/响应、以及最终持久化数据。
- 只有得到 Server 执行证据并验证持久化结果后，才能将 Action 操作视为已完成事实。


## Server Execution Evidence — 2026-08-21

- 最近 24 小时 Qingtian 写入类请求中，仅发现本次本机 `POST /qingtian/worklog/from-text` 测试请求。
- 未发现 `POST /qingtian/update-today`。
- 未发现 `PUT /qingtian/records/{record_date}`。
- 因此 Server access log 可以作为判断 Action 是否实际到达 RemoteOffice API 的独立证据。
- Conversation 中的操作描述不能替代 Server access log。
- Action 的“成功”判断应区分：请求到达、HTTP 响应成功、实际持久化成功三个层次。


## Action Evidence Model — 2026-08-21

- Action 执行证据分为三个层次：
  1. Server 收到对应 HTTP request。
  2. Server 返回明确的业务成功结果。
  3. 通过现有 GET API 或 NAS 文件独立验证实际持久化结果。
- HTTP 200 本身不能单独证明业务操作已经完成。
- Conversation 中的 Assistant 成功陈述不能替代 Server execution evidence。
- API 不强制在写入后立即 reread；需要审计时使用现有 GET API 或直接检查 NAS。
- `append_today_message` 保持 append 语义。
- `updateTodayConversation` 保持 replace-snapshot 语义。
- WorkLog 保持 JSONL append 语义。
- Daily Record 保持今天记录的 deterministic / atomic update 语义。


## Architectural Decision — Request Tracking

- 当前 Qingtian API 不使用 `request_id`、`operation_id`、`correlation_id` 或 `trace_id`。
- V2 当前不新增 request tracking 机制。
- 现有三层 Action Evidence Model 已足够进行当前阶段的执行与持久化验证：
  1. Server 收到 HTTP request。
  2. Server 返回明确的业务成功结果。
  3. GET API 或 NAS 独立验证实际持久化结果。
- 不为追踪而追踪，避免在没有实际需求时增加 API 契约和数据复杂度。
- 如果后续出现重复执行、idempotency、跨服务关联或长期审计需求，再单独设计 request ID / idempotency 机制。


## Functional Verification — 2026-08-21

### WorkLog

- `POST /qingtian/worklog/from-text` returned `saved: true`.
- `GET /qingtian/worklog/today` returned the same test record.
- Direct NAS inspection confirmed the same JSONL record.
- Monthly WorkLog endpoint also returned the 2026-08-21 test record.

### Conversation Snapshot

- `POST /qingtian/update-today` authenticated successfully and returned `status: saved`, `message_count: 2`.
- `GET /qingtian/conversation/today` returned the same two-message snapshot.
- Direct inspection of `/data/qingtian/conversations/2026-08-21.jsonl` confirmed the same two records.

### Daily Record

- `PUT /qingtian/records/2026-08-21` successfully wrote Summary and Detail.
- `GET /qingtian/records/2026-08-21` returned the exact written content.
- Direct NAS inspection confirmed both files contain the expected test content.

### Result

- All three Qingtian V2 write paths passed the three-layer verification model: HTTP write response, independent GET verification, and direct storage verification.
- The records created during this test are explicitly marked as functional verification test data and must not be interpreted as actual completed work.


## Functional Test Artifact Record — 2026-08-21

- WorkLog test: /nas/Qingtian/WorkLog/2026/08/2026-08-21.jsonl
- Conversation test: /data/qingtian/conversations/2026-08-21.jsonl
- Daily Summary test: /nas/Qingtian/Records/2026/08/2026-08-21.md
- Daily Detail test: /nas/Qingtian/Records/2026/08/2026-08-21-detail.md
- These four artifacts are V2 functional verification test data and are not actual completed-work records.