create-dwy 0.10.0 → 0.12.0

package/templates/claude-global/skills//345/237/272/347/241/200/345/272/223/dwy-eapi/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: dwy-eapi
+description: "dwyeapi FastAPI 后端基础设施使用指南。涉及以下任何主题，**必须**使用此 skill（即使用户没有明确说 'dwyeapi' / 'eapi'）：FastAPI 项目搭建 / Pydantic Settings 配置 / 异步 SQLAlchemy / Redis 缓存 / JWT 认证 / bcrypt 密码哈希 / 异常体系（AppError / NotFoundError / BusinessError）/ 统一响应信封（ApiResponse / PageData）/ 分页 / 日志（loguru）/ 健康检查 / PII 脱敏 / 时区敏感的时间处理 / 异步任务（ARQ）/ 邮件验证码发送。本 skill 是 @dwydev/eapi 的唯一权威导航来源。"
+eapi_baseline_version: "0.9.0"
+---
+
+# dwyeapi 后端基础设施使用指南
+
+Python 3.11+ FastAPI 基础设施包，全异步。单文件模块设计（每个能力一个 .py），便于直接读源码。
+
+本 skill 索引基于 dwyeapi **0.9.0**。消费方版本可能不同 — 见 [版本兼容规则](#版本兼容规则)。
+
+## 模块清单（13 个）
+
+| 模块 | 用途 |
+|------|------|
+| `config` | Pydantic BaseSettings + 运行环境识别 (is_dev / is_prod / get_environment) |
+| `exceptions` | AppError 异常体系 + FastAPI 全局 handler 注册 |
+| `database` | 异步 SQLAlchemy engine/session 工厂 + Base + TimestampMixin |
+| `dependencies` | FastAPI 依赖注入工厂（如 get_db） |
+| `security` | JWT 令牌 + bcrypt 密码哈希（无状态） |
+| `cache` | 异步 Redis 连接管理（懒单例） |
+| `response` | 统一 API 响应信封 `ApiResponse[T]` + `PageData[T]` |
+| `pagination` | 分页参数 PaginationParams + offset/limit 计算 |
+| `dt` | 中国时区敏感的全局时间工具（替代 datetime.now） |
+| `logger` | loguru 全局日志（按天 + 按大小轮转、stdlib 拦截） |
+| `masking` | PII 数据脱敏（手机/邮箱/身份证/银行卡/姓名/地址/IP/车牌） |
+| `health` | 健康检查路由工厂（只探活、不探依赖） |
+| `tasks` | 异步任务系统（基于 ARQ，需 `pip install dwyeapi[tasks]`） |
+| `providers.email` | 邮件验证码发送（可插拔，默认 Resend，可继承注入腾讯 SES / SMTP 等） |
+
+---
+
+## 查 API 标准动作（核心：每次写 dwyeapi 代码前都做）
+
+dwyeapi 的源码 docstring 写得非常详尽（含设计意图、边界行为、Args/Returns/Raises、典型陷阱）。**本文档不再镜像签名表格** —— 因为表格信息密度低于源码 docstring，且会随版本漂移。需要某个 API 的精确签名/语义时，按下面顺序拿：
+
+### 第一步：定位 dwyeapi 真实版本和安装路径
+
+```bash
+# 拿版本
+pip show dwyeapi | grep -i version
+#  或：python -c "import dwyeapi; print(dwyeapi.__version__)"
+
+# 拿包安装目录
+python -c "import dwyeapi; print(dwyeapi.__file__)"
+# 输出形如 /path/to/.venv/lib/python3.12/site-packages/dwyeapi/__init__.py
+# dirname 后的目录就是 dwyeapi 包根，模块都在里面
+```
+
+### 第二步：读模块源码（按存在性回退）
+
+```
+a. 优先：<site-packages>/dwyeapi/{module}.py
+   —— 下游消费方默认场景。每个模块单文件，含模块级 docstring + 所有公开函数/类的 Args/Returns/Raises
+
+b. 次选：<dwy-shared-root>/backend/src/dwyeapi/{module}.py
+   —— 仅当在 dwy-shared monorepo 内或并列 clone 时可用，内容相同
+
+c. 都拿不到 → 退到本文档下方的 [模块清单](#模块清单13-个)（粗略，仅做导航）
+```
+
+### 第三步：tasks 模块查详细文档
+
+tasks 模块功能丰富（注册 / 提交 / 查询 / 取消 / 进度），单独维护一份完整集成指南：
+
+```
+references/tasks-integration-guide.md
+```
+
+只在用到 tasks 时读，平时不必加载。
+
+### 第四步：冲突时永远信源码
+
+本 SKILL.md 是导航 + 心智模型，**不是 API 真相**。当文档描述与 site-packages 中的 `.py` 不一致：无条件以源码为准。
+
+---
+
+## 版本兼容规则
+
+- 本 skill `eapi_baseline_version: 0.9.0`，模块清单、踩坑提示都基于这个版本
+- 消费方装的是不同版本（更新或更旧）时，**必须**按"查 API 标准动作"流程读 .py，不要默认本文档准确
+- dwyeapi < 0.9.0 可能没有 dt / tasks / providers 模块：先 `ls <site-packages>/dwyeapi/` 确认存在再用
+- 主版本号变更（0.x → 1.x）时，本文档的索引可能完全失效：先 `ls <site-packages>/dwyeapi/` 重建认知
+
+---
+
+## 重要约束与已知陷阱
+
+源码读得出来但容易忽略的"踩坑经验"，写后端代码时遵守：
+
+### 业务层架构（service / router 分层）
+
+- **service 层**抛业务异常（`NotFoundError("用户")` / `BusinessError("余额不足", code="INSUFFICIENT_BALANCE")` 等），不感知 HTTP 概念
+- **router 层**不写 try/except，由 `register_exception_handlers(app)` 统一转成 `ApiResponse` 信封 JSON
+- **禁止**在 service 层抛 `HTTPException` —— 会绕过统一 handler，破坏响应结构一致性
+
+### 时间处理（避免时区 bug）
+
+- 业务时间统一中国时区，**禁止 `datetime.now()`**，统一走 `dwyeapi.dt`
+- `dt.now()` 返回 naive datetime（Asia/Shanghai，用于数据库存储）
+- `dt.utc_now()` 返回 aware UTC datetime（用于 JWT exp 等协议字段）
+- 这两个不能混用：数据库列存 naive 中国时间、JWT exp 存 UTC aware
+
+### 配置
+
+- **没有 `debug` 字段**，所有调试开关统一用 `is_dev()`：避免两个维度（debug + environment）冲突
+- `environment` 默认 `"prod"`（误配置时保守）：生产环境必须显式关闭 docs/redoc/openapi 三个端点（`docs_url="/docs" if is_dev() else None`），否则路由元信息会泄露给攻击者
+- `BaseSettings` 必填三个字段：`database_url` / `redis_url` / `secret_key`（继承时不能给默认值）
+
+### Redis 连接
+
+- `cache.configure(redis_url)` 启动时调用一次（lifespan）；`cache.get_redis()` 首次调用懒建立连接
+- `close_redis()` 可重复调用（安全幂等），lifespan 关闭阶段调用
+- 未 configure 直接 `get_redis()` 会抛 `RuntimeError`
+
+### tasks 模块
+
+- 需要 `pip install dwyeapi[tasks]` 单独装 extra（避免不用任务的项目背 ARQ 依赖）
+- 任务函数签名固定 `async def task(ctx: TaskContext, params: dict)`，第一个参数 ctx 由框架注入
+- 取消机制是协作式：任务函数内必须主动 `await ctx.is_cancelled()` 检查，否则取消信号无效
+- 完整细节读 `references/tasks-integration-guide.md`
+
+### 邮件 Provider
+
+- 内置仅 `resend`。业务用其他通道（腾讯 SES / SMTP / 自建）：继承 `EmailProviderBase` 实现 `_send` → `register_email_provider("name", factory)` → `.env` 设 `EMAIL__PROVIDER=name`
+- 验证码生成 + Redis 存储 + 品牌化模板 由基类全部复用，子类只管"发出去"
+
+### 日志
+
+- `logger.configure()` 启动时调用一次；`logger.close()` 在 lifespan 结束时调用
+- `intercept_stdlib=True`（默认）会把 stdlib logging（uvicorn / SQLAlchemy 等）也接管到统一 sink
+- 多进程部署时必须 `enqueue=True`（默认）——避免日志文件竞争写
+
+### 健康检查
+
+- `create_health_router()` **只**探活、**不**触达 PostgreSQL / Redis 等依赖
+- 理由：健康端点常对公网开放，内置 dependency check 会被攻击者用来 DoS 放大数据库/缓存
+- 需要 readiness 的业务自行实现并限制内网访问
+
+---
+
+## 典型项目接入流程
+
+```python
+# config.py
+from dwyeapi.config import BaseSettings
+
+class Settings(BaseSettings):
+    app_name: str = "My API"
+    service_name: str = "my-api"
+
+settings = Settings()  # 从 .env / 环境变量读 database_url、redis_url、secret_key
+
+# database.py
+from dwyeapi.database import create_async_engine_factory, create_session_factory
+from dwyeapi.dependencies import create_get_db
+from dwyeapi import is_dev
+
+engine = create_async_engine_factory(settings.database_url, echo=is_dev())
+session_factory = create_session_factory(engine)
+get_db = create_get_db(session_factory)
+
+# main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from dwyeapi import cache, logger, is_dev
+from dwyeapi.exceptions import register_exception_handlers
+from dwyeapi.health import create_health_router
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.configure(level="INFO", log_dir="./logs", filename="app")
+    cache.configure(settings.redis_url)
+    yield
+    await cache.close_redis()
+    logger.close()
+
+app = FastAPI(
+    lifespan=lifespan,
+    docs_url="/docs" if is_dev() else None,
+    redoc_url="/redoc" if is_dev() else None,
+    openapi_url="/openapi.json" if is_dev() else None,
+)
+register_exception_handlers(app)
+app.include_router(create_health_router(service_name=settings.service_name, version="1.0.0"))
+```
+
+---
+
+## 响应契约速查（前后端对齐用）
+
+所有接口返回统一信封：
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "success",
+  "data": { ... },
+  "timestamp": 1775625000
+}
+```
+
+- 成功：`code = "SUCCESS"`，`data` 是业务载荷（单体或 `PageData[T]`）
+- 失败：`code` 是业务错误码（如 `NOT_FOUND` / `BUSINESS_ERROR` / `VALIDATION_ERROR` 等），HTTP 状态保持语义（404 就是 404）
+- 校验错误 `VALIDATION_ERROR`：`data.errors: [{field, message}]`，field 含 `body.` / `query.` / `path.` 前缀
+
+构造响应：用 `ApiResponse.ok(data)` 或 `ApiResponse.page(items, total, page, page_size)`，不直接实例化 `ApiResponse`。
+
+错误响应**不要业务代码构造** —— 直接 `raise NotFoundError("用户")`，handler 自动转。
+
+---
+
+## 防腐层硬性约束（写代码前必读）
+
+dwyeapi 把基础设施细节封装在自有 API 后面。业务代码**禁止**直接调下面这些底层 API，违反会导致升级困难、行为不一致：
+
+| 禁止 | 改用 |
+|------|------|
+| `datetime.now()` / `datetime.utcnow()` | `dt.now()` / `dt.utc_now()` |
+| `import logging; logging.getLogger()` | `from dwyeapi import logger; logger.get_logger()` |
+| 手写 `from redis.asyncio import Redis` 全局变量 | `cache.configure()` + `cache.get_redis()` |
+| 手写 JWT encode/decode（含 `import jwt`） | `security.create_token()` / `security.decode_token()` |
+| 直接 `raise HTTPException(404, ...)` | `raise NotFoundError("资源名")` |
+| 自己写 `{"code": ..., "data": ...}` dict 当响应 | `ApiResponse.ok(data)` / `ApiResponse.page(...)` |
+| 自己写 `?page=&page_size=` Query 参数 | `params: PaginationParams = Depends()` |

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: dwy-dolphindb
+description: >
+  DolphinDB 3.0 社区版（2核8G / 1控2节点）开发与审查 skill：写 DolphinDB Script (.dos)、
+  用 Python SDK (dolphindb 3.0.4)、设计 DFS 分区表（TSDB/OLAP 引擎选型）、导入 tick/snapshot/
+  kline 金融数据、优化慢查询、排查 OOM / 卡死作业、Docker 部署。也用于代码审查：检查分区
+  裁剪（链式比较 `a <= col <= b`、函数包裹分区列）、批量写入 ≤500K 行、SYMBOL ≤255 字节、
+  STRING/BLOB 静默截断、输入校验防脚本注入、连接池配置、`pool.run` async/sync 用法。
+  关键字触发：dolphindb, DDB, loadTable, loadTextEx, createPartitionedTable, append!,
+  dropPartition, DBConnectionPool, tableAppender, PartitionedTableAppender,
+  MultithreadedTableWriter, addRangePartitions, newValuePartitionPolicy, TSDB, OLAP,
+  getClusterPerf, getConsoleJobs, level2 行情, tick 数据, 时序数据库, 8848 端口, .dos 脚本.
+---
+
+# DolphinDB 3.0 社区版使用指南
+
+## 当前环境
+
+| 项 | 值 |
+|---|---|
+| 版本 | DolphinDB 3.0 社区版 |
+| 拓扑 | 1 控制节点 + 2 计算/数据节点 |
+| 资源 | 2 核 / 8GB 内存（已分配 3GB），磁盘 33 TB |
+| 端口 | Web/控制 `http://localhost:8848`，集群另含 `192.168.0.107:8848` / `172.17.0.1:8848` 等 |
+| Worker | 4 线程，连接上限 512（当前 15） |
+| Python SDK | `dolphindb==3.0.4` |
+| 场景 | 个人/小团队 + 教学，**单查询内存上限按 2GB 控制**（详见 [[performance-tuning]]）|
+
+## 何时进入哪份 reference
+
+| 你正在做 | 看这里 |
+|---|---|
+| 第一次连 DDB / `import dolphindb` 报错 / 8848 进不去 | [[setup-and-connection]] |
+| 设计 DFS 分区表 / 选 TSDB 还是 OLAP / 给 level2 建表 | [[create-database-table]] |
+| `loadText` 慢 / 想多线程导入 / Python 写 DataFrame 进 DDB | [[data-import]] |
+| 写 SELECT/INSERT/UPDATE/DELETE / `delete` 删一整个分区 | [[crud-operations]] |
+| 合成 K 线 / 算 SOIR 订单失衡 / 截面排名 / 用 `mr` 分布式跑批 | [[sql-batch-compute]] |
+| Python SDK 用法 / `session.run` 高级参数 / 流订阅 / 异步写 / 类型映射 | [[python-api]] |
+| 查询慢 / OOM / 节点卡住 / 内存涨不下来 / 不知道哪个作业在跑 | [[performance-tuning]] |
+| 时间类型踩坑 / DECIMAL 精度 / SYMBOL 长度 / backtick 单行 / 反模式 | [[pitfalls-and-best-practices]] |
+| Docker 部署 / Alpine 镜像坑 / healthcheck / 资源限制 | [[docker-deployment]] |
+| 官方文档链接 / 版本基线 / GitHub 仓库 | [[sources]] |
+
+## 30 秒速查
+
+```dolphindb
+// 连接（Python）
+import dolphindb as ddb
+s = ddb.session()
+s.connect("localhost", 8848, "admin", "123456")
+
+// 看集群健康
+s.run("getClusterPerf()")                       // CPU/内存/磁盘
+s.run("getRecentJobs(20)")                      // 最近 20 个批作业
+s.run("pnodeRun(getConsoleJobs)")               // 所有节点同步作业
+s.run("getSessionMemoryStat()")                 // 当前 session 内存
+
+// 看库表
+s.run("getClusterDFSDatabases()")               // 所有 DFS 库
+s.run("getClusterDFSTables('dfs://xxx')")       // 库下所有表
+s.run("schema(loadTable('dfs://xxx','t'))")     // 表结构
+
+// 杀作业（按 rootJobId）
+s.run("cancelJob(`xxxx)")                       // 异步作业
+s.run("cancelConsoleJob(`xxxx)")                // 同步作业
+```
+
+## 核心原则（社区版 2核8G 必须遵守）
+
+1. **单查询不超 2GB**：8GB 内存 → 系统/缓存 2GB + worker 缓冲 2GB + 单查询预算 ≤ 2GB。先 `count()` 估行数 × 列宽，超了就走分区分批或 `mr`。
+2. **任何 WHERE 必带分区列**：否则全表扫，2 节点直接 OOM。用 `select [HINT_EXPLAIN] ...` 验证是否触发分区剪枝。
+3. **TSDB 排序列别选高基数**：`sortColumns` 不要用主键/唯一列（索引膨胀）；金融场景用 `[SecurityID, TradeTime]`。
+4. **写入用 PartitionedTableAppender + DBConnectionPool**：单连接 + `tableInsert` 慢，4 worker → pool size 3。
+5. **删数据按分区删**：`dropPartition()` 秒级，`delete from` 全表扫慢且占内存。
+
+## 反模式（看到立即停手）
+
+| 反模式 | 后果 | 改成 |
+|---|---|---|
+| `select * from t where 2024.01.01 <= TradeDate <= 2024.01.05` | 链式条件不触发剪枝 → 全表扫 | `where TradeDate between 2024.01.01 and 2024.01.05` |
+| `delete from t where TradeDate=2024.01.01` | 重写整个分区，慢+占内存 | `dropPartition(database(dbName), 2024.01.01, tableName='t')` |
+| 在客户端 `s.run("select * from huge_table")` | 一次拉全部，OOM | `s.run("...", fetchSize=8192)` 分段读 |
+| DECIMAL 列用 FLOAT/DOUBLE | 精度丢失（金融场景禁用） | `DECIMAL32(3)` / `DECIMAL64(6)` |
+| `DATETIME` 存 2038 后的时间 | 32 位 int 溢出 → 显示 1970 | 全用 `TIMESTAMP`（毫秒精度 64 位） |
+| 建表时 `sortColumns` 用 UUID/序列号 | 索引膨胀，TSDB 查询变慢 | 用 `[业务键, 时间列]` 组合 |
+
+**完整反模式清单**（类型陷阱 / SQL 陷阱 / 库表设计 / 写入 / 运维）见 [[pitfalls-and-best-practices]]。
+
+## 审查模式（代码 review / CR 用）
+
+任务是**审查**他人代码时，按以下格式输出：
+
+```
+⚠️ [reference名] 具体问题
+   违规代码：<摘录>
+   修复建议：<可直接替换的代码>
+   原因：<对应 reference 里的依据，一句话>
+
+✅ [reference名] 符合要求 — <简要说明>
+```
+
+### 10 条致命违规（零容忍）
+
+| # | 违规 | 后果 |
+|---|---|---|
+| 1 | 分区列被函数包裹（`date(col)` / `year(col)` / `temporalAdd(col,...)`） | 全表扫 → OOM |
+| 2 | 链式比较 `a <= col <= b` | 不触发剪枝 → 全表扫 |
+| 3 | 单次 `append` > 500K 行 | TSDB 报 `exceeds max limit` |
+| 4 | 未校验外部输入拼到脚本 | 脚本注入 |
+| 5 | 连接池里 upload + run（变量跨连接不可见） | 变量找不到 |
+| 6 | `select *`（30+ 列全传） | 浪费带宽和内存 |
+| 7 | 分页用 `LIMIT x OFFSET y` | DDB 不支持 OFFSET 关键字 |
+| 8 | `asyncio.to_thread(pool.run, script)` | SDK v3 `pool.run` 已是原生 async |
+| 9 | SYMBOL 列写入未校验 ≤255 字节 | 整批写入失败 |
+| 10 | 单分区 < 100MB 且总分区数 > 65536 | 触达 `maxPartitionNumPerQuery` 上限 |
+
+完整审查清单 ↓
+
+## 变更检查清单（写 / 改 DDB 代码前过一遍）
+
+- [ ] WHERE 是否命中分区列？分区列是否被函数包裹（`year()` / `date()` / `temporalAdd()`）？
+- [ ] 范围条件用了 `between ... and ...` 或两个独立条件？没有链式比较 `a <= col <= b`？
+- [ ] 单次 `append` ≤ 500K 行？循环里有 `del + gc.collect()`？
+- [ ] 大文件用 pyarrow `read_table + slice`，不是 `pd.read_feather` 全量加载？
+- [ ] 拼接 DDB 脚本时，外部输入有正则白名单校验？（防注入）
+- [ ] `pool.run()` 用 `await`（原生 async），`Session.run()` 用 `asyncio.to_thread()`？
+- [ ] 连接池大小 ≤ CPU 核数 × 2（社区版 4 worker → pool 3）？
+- [ ] `select` 只取需要的列？没有 `select *`？
+- [ ] 多次聚合查询能否合并为一次？
+- [ ] 多因子横向查询用了 `pivot by`，不是 Python 端 merge？
+- [ ] backtick 列名定义在单行内？
+- [ ] 分页用 `limit offset, count`（**不是** `LIMIT x OFFSET y`）？
+- [ ] 新建库表：单分区估算大小落在引擎区间？总分区数远低于 65536？二级高基数列走 `HASH` 不是 `VALUE`？
+- [ ] 写入 SYMBOL 列前校验 ≤ 255 字节？STRING/BLOB 有长度断言防静默截断？
+- [ ] 删数据用 `dropPartition`，不是 `delete from`？
+- [ ] pandas → DDB：`uint` 是否 `.astype('int64')`？NaN→int 是否 `.fillna(0)`？
+- [ ] Session / Pool 有 `try/finally close()`？
+
+## 必读官方资料
+
+完整源 URL 见 [[sources]]。常用 3 个：
+- 金融入门：https://docs.dolphindb.cn/zh/tutorials/new_users_finance.html
+- 使用须知：https://docs.dolphindb.cn/zh/tutorials/usage_guidelines.html
+- Python SDK：https://docs.dolphindb.cn/zh/pydoc/ （3.0.4）

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/references/create-database-table.md

@@ -0,0 +1,219 @@
+# 建库建表
+
+## 30 秒选型
+
+| 你的数据 | 引擎 | 分区策略 | 排序列 |
+|---|---|---|---|
+| 行情快照 / tick / 逐笔 / level2 | **TSDB** | `VALUE(日期), HASH(SymbolField, N)` | `[SecurityID, TradeTime]` |
+| 分钟/日 K 线 / 因子结果 | **OLAP** | `VALUE(日期)` 或 `RANGE(月份)` | — |
+| 维度信息（股票基础信息表等） | — | 维度表（不分区） | — |
+| 流式行情写入 + 实时查询 | TSDB | 同 tick | 同 tick |
+
+**OLAP vs TSDB**：
+- OLAP = 列存，写入快，**不支持点查/更新**。适合 K 线、因子、批分析。
+- TSDB = 列存 + 索引，**支持 sortKey 排序+索引**，秒级点查。适合 tick/snapshot/逐笔，分区 400MB-1GB。
+- 选错了改不了，整个库 drop 重建。
+
+## 分区策略
+
+| 类型 | 关键字 | 自动扩展 | 适用 |
+|---|---|---|---|
+| VALUE | `VALUE(2024.01.01..2024.12.31)` | ✅ | 日期、状态 |
+| HASH | `HASH([SYMBOL, 50])` | ✅ | 高基数列（股票代码） |
+| RANGE | `RANGE(0 100 200 300)` | ❌ 需 `addRangePartitions` | 数值范围 |
+| LIST | `LIST([['A','B'], ['C']])` | ❌ | 明确分组 |
+| COMPO | `partitioned by VALUE(...), HASH(...)` | 看子分区 | 复合（最多 3 级）|
+
+**分区层级硬限制**：1-3 级。常用 2 级 = `日期 + 股票代码 HASH`。
+
+**分区粒度目标**：单分区压缩后 **TSDB 400MB-1GB / OLAP 100MB-300MB**。粒度太细 → 元数据爆炸；太粗 → 查询不能并行。
+
+**`maxPartitionNumPerQuery` 硬限**：默认 65536。单次查询触达的分区数超过这个值直接报 `The number of partitions relevant to the query is too large`。
+
+### 分区设计反例（**新手最常踩**）
+
+> 股票行情数据（每天 5000 万条），先按 `TradeDate` 值分区，再按 `SecurityID` 二级 VALUE 分区。
+> A 股 5000+ 标的 → **一天 5000 个分区，每个仅 0.6MB**。
+
+后果：
+- 查 14 天 → 70000 分区 → 超 65536 上限报错
+- 单分区 0.6MB 远低于 TSDB 400MB 下限，元数据开销 > 数据本身
+- 列存收益丧失，查询比单级分区还慢
+
+**修复**：二级改 `HASH([SYMBOL, 50])`（固定 50 桶），每天 50 个分区，单分区 60MB（仍偏小但元数据 OK）。
+
+### VALUE 分区自动扩展
+
+```dolphindb
+// 库参数：写入新值时自动建分区
+create database "dfs://xxx"
+    partitioned by VALUE(2024.01.01..2024.01.07)
+    engine='TSDB',
+    newValuePartitionPolicy=add        // 关键：新日期自动建分区，不需预创建
+```
+
+不设 `newValuePartitionPolicy=add` → 写入未预建的日期会报 `partition does not exist`。
+
+### RANGE 分区静默丢弃陷阱
+
+```dolphindb
+// 库参数 allowMissingPartitions 默认 true
+// → 范围外数据【静默丢弃，不报错】！
+create database "dfs://xxx"
+    partitioned by RANGE(2024.01M..2024.12M)
+    // 写 2025 年数据 → 默默丢
+
+// 需要严格性：
+create database "dfs://xxx"
+    partitioned by RANGE(2024.01M..2024.12M),
+    allowMissingPartitions=false       // 越界写入直接报错
+```
+
+RANGE 分区**不会**自动扩展，必须手动 `addRangePartitions(database, futureRanges)`。
+
+### 估算 HASH 桶数
+
+```
+桶数 ≈ (每日数据量 / 期望单分区大小)
+```
+
+A 股 5000+ 股票 + level2 一天 ~80GB → 按日期分区后 80GB / 1GB ≈ 80 桶 → 取 `HASH([SYMBOL, 50])`（保守留 buffer）。
+
+## 建库 DDL
+
+### 行情快照（TSDB + COMPO 分区）
+
+```dolphindb
+// 删库重来（开发期）
+if(existsDatabase("dfs://stock_lv2_snapshot")) {
+    dropDatabase("dfs://stock_lv2_snapshot")
+}
+
+create database "dfs://stock_lv2_snapshot"
+    partitioned by VALUE(2024.01.03..2024.01.04), HASH([SYMBOL, 50]),
+    engine='TSDB'
+    // VALUE 写头 2 天即可，写入新日期会自动扩展；写多了只是元数据占位
+```
+
+**注意**：
+- `VALUE` 用一小段日期初始化即可，会自动扩展，**不要塞几年的空分区**（元数据膨胀）。
+- 删库用 `dropDatabase`，要在 controller 上跑。
+- `engine='TSDB'` 不写默认是 OLAP。
+
+### 分钟 K 线（OLAP + 单级 VALUE）
+
+```dolphindb
+if(existsDatabase("dfs://k_minute_level")) {
+    dropDatabase("dfs://k_minute_level")
+}
+
+create database "dfs://k_minute_level"
+    partitioned by VALUE(2024.01.01..2024.01.31)
+    engine='OLAP'
+```
+
+### 维度表（不分区，跟在某个 DFS 库下）
+
+```dolphindb
+db = database("dfs://stock_lv2_snapshot")
+createDimensionTable(db, "security_info",
+    table(1:0, ["SecurityID","Name","Industry"], [SYMBOL,STRING,SYMBOL])
+)
+```
+
+## 建表 DDL
+
+### TSDB 表（必须 sortColumns）
+
+```dolphindb
+create table "dfs://stock_lv2_snapshot"."snapshot"(
+    TradeDate DATE[comment="交易日期", compress="delta"]
+    TradeTime TIME[comment="交易时间", compress="delta"]
+    SecurityID SYMBOL
+    LastPrice DOUBLE
+    OpenPrice DOUBLE
+    HighPrice DOUBLE
+    LowPrice DOUBLE
+    TotalVolumeTrade LONG
+    OfferPrice DOUBLE[]          // 数组向量：10 档卖价
+    BidPrice DOUBLE[]
+    OfferOrderQty LONG[]
+    BidOrderQty LONG[]
+)
+partitioned by TradeDate, SecurityID,
+sortColumns=["SecurityID","TradeTime"],
+keepDuplicates=ALL
+```
+
+**关键参数**：
+- `partitioned by`：必须和库的 partition 顺序一致。
+- `sortColumns`：**最后一列必须是时间列**，前面是高频查询的过滤列（如 `SecurityID`）。
+- `keepDuplicates`：`ALL`（保留）/`FIRST`/`LAST`，金融 tick 一般 `ALL`。
+- `compress="delta"`：单调递增列（日期、时间、序号）必加，能压缩 80%+。
+- `DOUBLE[]`：数组向量类型，10 档行情用一列搞定（vs 拆 20 列）。
+
+### OLAP 表（轻量，无 sortColumns）
+
+```dolphindb
+create table "dfs://k_minute_level"."k_minute"(
+    securityid SYMBOL
+    tradetime TIMESTAMP
+    open DOUBLE
+    close DOUBLE
+    high DOUBLE
+    low DOUBLE
+    vol INT
+    val DOUBLE
+    vwap DOUBLE
+)
+partitioned by tradetime
+```
+
+## sortColumns 选择规则（TSDB）
+
+✅ 推荐：`[业务键, 时间列]` —— `[SecurityID, TradeTime]`、`[InstrumentID, Timestamp]`
+
+❌ 禁止：
+- 把**唯一键/主键**当 sortColumn（如订单号、UUID）→ 索引膨胀，TSDB 索引文件比数据还大
+- **时间列放第一位** → 同一时刻的不同标的散开，按 SecurityID 查变慢
+
+## 数据类型选择
+
+| 场景 | 类型 | 不要用 |
+|---|---|---|
+| 价格、金额（金融） | `DECIMAL32(3)` / `DECIMAL64(6)` | `FLOAT/DOUBLE`（精度丢失） |
+| 成交量、笔数 | `LONG`（大数）/ `INT`（小数） | — |
+| 股票代码、合约代码 | `SYMBOL` | `STRING`（symbol 列式压缩 + 字典编码更省） |
+| 名称、备注 | `STRING` | — |
+| 日期 | `DATE` | — |
+| 时间戳 | `TIMESTAMP`（毫秒）/`NANOTIMESTAMP`（纳秒） | `DATETIME`（32 位 int，2038 溢出！）|
+| 10 档行情 | `DOUBLE[]` 数组向量 | 拆 20 列（写慢、查慢） |
+
+## ALTER 限制（建表前想清楚）
+
+| 操作 | TSDB | OLAP |
+|---|---|---|
+| 新增列（只能末尾） | ✅ | ✅ |
+| 删列 | ❌ | ✅（非分区列） |
+| 改列名 | ❌ | ✅（非分区列） |
+| 改列类型 | ❌ | ✅（非分区列） |
+| 改列顺序 | ❌ | ❌ |
+| 改分区列 | ❌ | ❌ |
+| 主键/唯一索引 | ❌ | ❌ |
+| 自增列 | ❌ | ❌ |
+
+**结论**：TSDB 表 schema 一旦定下基本不能动。建表前用一周数据 dry-run。
+
+## 元数据查询
+
+```dolphindb
+getClusterDFSDatabases()                       // 所有 DFS 库
+getClusterDFSTables("dfs://stock_lv2_snapshot")// 库下所有表
+getTables(database("dfs://xxx"))               // 同上
+schema(loadTable("dfs://xxx","t"))             // 完整 schema
+getDatabaseDDL("dfs://xxx")                    // 反查建库 SQL
+getDBTableDDL("dfs://xxx","t")                 // 反查建表 SQL
+getTableDiskUsage("dfs://xxx","t")             // 表占用磁盘
+```
+
+跨引用：导入数据 → [[data-import]]，查询 → [[crud-operations]]，反模式 → [[pitfalls-and-best-practices]]。