chore: docs

docs/DEPLOYMENT.md

@@ -16,7 +16,7 @@
 | **前端服务 (Node.js)** | `pnpm start` | 提供 React/Next.js 页面服务（在分离部署时使用） | 分离模式必选 |
 | **PostgreSQL** | 关系型主数据库 | 存储用户、系统配置、认证源、任务执行记录等核心数据 | **必选** |
 | **Redis** | 缓存与消息队列中间件 | 存储 Session 会话、临时缓存以及 Asynq 异步任务队列数据 | **必选** |
-| **ClickHouse** | 分析型数据库 | 存储历史数据同步或进行高性能分析 | 可选 |
+| **ClickHouse** | 分析型数据库 | 可选的日志主库；关闭时访问审计由 PostgreSQL/SQLite 承接 | 可选 |
 | **对象存储 (S3)** | 兼容 S3 的云存储/私有云 | 存放用户上传的静态文件、图片等 | 可选 |
 
 ---
@@ -306,7 +306,7 @@ s3:
 - **Scheduler 独占**：**【注意】** 为避免重复触发定时 Cron 任务，`wavelet scheduler` 定时调度器进程**同一时间应仅运行单个活跃实例**（主备高可用可以通过容器平台的单实例保障或 K8s Job 机制来限制实例数为 1）。
 
 #### 5. ClickHouse 高并发同步
-在大数据量、高频支付结算场景下，开启 ClickHouse 以接收系统的历史数据同步，通过定时器把 PostgreSQL 的压力转移到 ClickHouse 列式存储中。
+访问审计等日志表默认写在当前业务主库。数据量大、需要列式扫描时，开启 ClickHouse，再在任务管理运行「切换日志数据库」迁到 ClickHouse（迁移期间冻结写入，源数据不删）。开发约定见 [日志用途表](./LOGSTORE.md)。
 ```yaml
 clickhouse:
   enabled: true

docs/LOGSTORE.md

@@ -0,0 +1,45 @@
+# 日志用途表
+
+Wavelet 的访问审计等日志表不绑死 ClickHouse。`internal/repository/logstore` 按 `log_database` 在 PostgreSQL / SQLite / ClickHouse 之间切换；关闭 ClickHouse 时由当前业务主库承接写入、查询与清理。
+
+逐步落地步骤见 `.agents/skills/logstore/SKILL.md`。本文只约定判定、分层与切换协议。
+
+## 什么算日志表
+
+同时满足才进 logstore：
+
+- 追加写入，几乎不更新单行
+- 按时间查询或聚合，允许按保留天数删除
+- 关闭 ClickHouse 后仍要能写、能查
+- 不参与用户 / 配置 / 任务等事务一致性
+
+用户、系统配置、任务执行、上传元数据走业务主库 `repository`，不要塞进 logstore。
+
+当前已接入：`w_user_access_logs`（管理端 API 访问审计），接口 `UserAccessLogStore`。
+
+## 分层
+
+| 层级 | 路径 | 职责 |
+| :--- | :--- | :--- |
+| 抽象 | `internal/repository/logstore` | 接口 + `Active` / `BuildForMigration`；apps 只面向这里 |
+| CH 实现 | `logstore` 委托 `repository/analytics` | 原生批量与现有查询 |
+| 主库实现 | `logstore` GORM | PostgreSQL 按月分区；SQLite 普通表 |
+| 入队 | `risk_control` + `batchwriter` | `FlushFunc` → `logstore.Active` |
+| 切换 | `logs:db_switch` | 冻结 → 排空 → 复制 → 翻转 |
+| 清理 | `logstore.CleanupExpired` | `system:cleanup` 按库读 `log_retention_days_*` 后 `DeleteBefore` |
+
+`log_database` 只能是「随业务主库」或 `clickhouse`。`log_database` / `log_db_migration` 受保护，管理端不可改。
+
+## 切换协议
+
+1. 校验 `target` 合法且不等于当前库。
+2. 写 `log_db_migration=migrating`，`Drain` 在途队列（不要 `Stop` writer）；写入返回明确错误，不排队。
+3. 清空目标表后按 id 分页复制；PostgreSQL 目标先 `EnsurePartitions`。
+4. 全部成功才翻转 `log_database`；失败清标记，写入继续走源库。
+5. 源数据不删。
+
+不要另起切换协议，也不要在任务或 Handler 里直连 `analyticsrepo` / `db.ChConn`。
+
+## 新增一张日志表
+
+必须同时提供 ClickHouse / PostgreSQL / SQLite 三套 goose，列名一致。接口至少包含 `BatchInsert`、业务查询、`ListForMigration` / `MigrationRange` / `DeleteAll` / `EnsurePartitions`、`DeleteBefore`。`FlushFunc` 调 `logstore.Active`。细节与禁止项见 `logstore` skill。