create-dwy 0.8.0 → 0.9.1

package/templates/claude-global/rules/dwy-vue-pinia.md

@@ -1,75 +1,88 @@
 ---
-description: Pinia Setup Store 状态管理规范
+description: Pinia Setup Store 状态管理规范（强制 Setup Store、storeToRefs、按业务聚合）
 paths:
+  - "**/store.ts"
   - "**/stores/**/*.ts"
-  - "**/store/**/*.ts"
 ---
 
 # Pinia 状态管理规范
 
-## 四、Pinia 状态管理
+适用于 Vue 3 + Pinia 项目。
 
-### 强制使用 Setup Store
+---
+
+## 一、强制使用 Setup Store
 
 ```typescript
-// ✅ Setup Store（强制）
+// 正例：Setup Store
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
 export const useAuthStore = defineStore('auth', () => {
-  const token = ref<string | null>(localStorage.getItem('token'))
+  const token = ref<string | null>(null)
   const user = ref<UserInfo | null>(null)
 
   const isLoggedIn = computed(() => !!token.value)
 
   async function login(username: string, password: string) {
-    const res = await apiLogin(username, password)
-    token.value = res.data.access_token
-    localStorage.setItem('token', token.value)
+    const res = await apiLogin({ username, password })
+    token.value = res.access_token
   }
 
   function logout() {
     token.value = null
     user.value = null
-    localStorage.removeItem('token')
   }
 
   return { token, user, isLoggedIn, login, logout }
 })
 
-// ❌ Options Store（禁止）
+// 反例：禁止 Options Store
 export const useAuthStore = defineStore('auth', {
   state: () => ({ token: '' }),
-  actions: { login() {} }
+  actions: { login() {} },
 })
 ```
 
-### Store 设计原则
+---
+
+## 二、Store 设计原则
 
 | 原则 | 说明 |
 |------|------|
-| 单一职责 | 一个 store 管理一个业务域（auth、menu、user） |
-| 不直接修改 state | 通过方法修改，不在组件中直接 `store.xxx = yyy` |
-| 异步操作放 store | API 调用封装在 store 方法中 |
-| 解构用 `storeToRefs` | 解构响应式状态必须用 `storeToRefs`，方法直接解构 |
+| 单一职责 | 一个 store 管理一个业务域（auth / menu / users），**禁止**把多个业务塞同一个 store |
+| 不在组件中直接改 state | 必须通过 store 方法修改，**禁止** `store.xxx = yyy` |
+| 异步操作放 store | API 调用封装在 store 方法中，组件不直接调 API（除非纯展示页） |
+| 业务聚合 | store 文件放在对应业务模块目录（`modules/users/store.ts`），**禁止**顶级 `stores/` 把不同业务混放 |
+| 持久化 | 需要持久化的状态走 ekit storage / `useStorage`（具体 API 查 `dwy-ekit` skill），**禁止**直接 `localStorage` |
+| HTTP 调用 | 走全局 ekit `createRequest` 客户端，**禁止**自建 axios 实例 |
+
+---
+
+## 三、storeToRefs 解构
 
 ```typescript
-// ✅ 正确解构
-const store = useReportStore()
-const { report, loading } = storeToRefs(store)
-const { setReport, reset } = store
+import { storeToRefs } from 'pinia'
+
+// 正例：响应式值用 storeToRefs，方法直接解构
+const store = useAuthStore()
+const { token, user, isLoggedIn } = storeToRefs(store)
+const { login, logout } = store
 
-// ❌ 错误解构（丢失响应性）
-const { report, loading } = store
+// 反例：直接解构丢失响应性
+const { token, user } = store
 ```
 
 ---
 
-## 状态管理规范（跨端共识）
-
-| 平台 | 方案 | 详细规范 |
-|------|------|---------|
-| Vue | Pinia Setup Store | 见 `dwy-vue-pinia.md`（本文件） |
-| Flutter | Riverpod | 见 `flutter-code-style.md` 状态管理章节 |
-
-**跨端共识：**
-- 认证状态全局管理（Vue: `useAuthStore`，Flutter: `authProvider`）
-- 页面级状态就近管理，不上提到全局
-- 缓存策略：列表数据按需刷新，不做客户端持久化缓存（除离线场景）
+## 四、违规检测清单
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| Options Store | `defineStore(id, { state, actions, getters })` | **致命 → STOP** |
+| 组件直接改 state | 组件中 `store.xxx = yyy` 直接赋值 | 高 |
+| 解构丢响应性 | `const { x } = store` 后在模板里用 `x` | 高 |
+| store 跨业务塞功能 | 一个 store 同时管 auth + menu + user 等不相关业务 | 高 |
+| 直接 localStorage | store 中直接 `localStorage.setItem(...)`，未走 ekit storage | 高 |
+| 自建 HTTP 客户端 | store 中 `axios.create()` / `fetch(...)`，未走 ekit `createRequest` | 高 |
+| 顶级 stores 散落 | 顶级 `stores/` 目录把不同业务 store 混放，未按业务聚合 | 高 |

package/templates/claude-global/rules/dwy-vue-testing.md

@@ -1,39 +1,76 @@
 ---
-description: Vitest 单元测试规范
+description: Vue Vitest 测试规范（目录组织、技术栈、AAA 结构、打包隔离）
 paths:
   - "**/*.test.ts"
   - "**/*.spec.ts"
   - "**/tests/**/*.ts"
 ---
 
-# Vitest 单元测试规范
+# Vue Vitest 测试规范
 
-## 十三、测试规范（Vitest）
+适用于 Vue 3 + Vitest + @vue/test-utils + happy-dom 项目。
+
+---
+
+## 一、测试目录组织（强制）
+
+### 核心约束
+
+**测试目录与业务源码（`src/`）并列、独立存放。** 测试文件**禁止**混入 `src/`。
 
 ### 强制规则
-- 使用 **Vitest** 作为测试框架，配合 **@vue/test-utils** + **happy-dom**
-- 测试文件**必须放在项目根目录的 `tests/` 目录**，按模块镜像 `src/` 结构，**禁止**放在 `src/` 内
-- `tsconfig.app.json` 的 `include` **只包含 `src/`**，确保打包不携带测试文件
-- 测试文件命名：`*.test.ts`
 
-### 依赖安装
+- 测试根目录固定为 `tests/`，与 `src/` 平级
+- **禁止**在 `src/` 中放任何 `*.test.ts` / `*.spec.ts` / `__tests__/` 文件
+- 测试目录内部结构**镜像**源码业务聚合结构（见 `dwy-vue-core` rule 第一节）
+- 测试文件命名：`*.test.ts`（vitest 默认发现规则）
+- 测试函数命名：描述行为而非实现
+- `vitest.config.ts` **独立文件**，不与 `vite.config.ts` 合并；显式声明 `test.include`
+- `tsconfig.app.json` 的 `include` **只包含 `src/`**，**禁止**包含 `tests/`，确保打包不携带测试代码
+- 测试相关依赖（`vitest` / `@vue/test-utils` / `happy-dom` 等）放 `devDependencies`，**禁止**进生产依赖
+- 测试文件中通过 `@` 别名导入源码，**禁止**用 `../../../src/` 相对路径回溯
 
-```bash
-pnpm add -D vitest @vue/test-utils happy-dom
+### 标准目录结构（参考）
+
+```
+project/
+├── src/
+│   ├── modules/
+│   │   ├── users/
+│   │   │   ├── api.ts
+│   │   │   ├── store.ts
+│   │   │   ├── views/UserListView.vue
+│   │   │   └── components/UserCard.vue
+│   │   └── orders/
+│   ├── shared/
+│   └── core/
+├── tests/                          # 测试根目录（与 src/ 并列）
+│   ├── modules/
+│   │   ├── users/
+│   │   │   ├── api.test.ts
+│   │   │   ├── store.test.ts
+│   │   │   └── UserCard.test.ts
+│   │   └── orders/
+│   └── shared/
+├── vitest.config.ts
+├── tsconfig.app.json               # include 只含 src/
+└── package.json
 ```
 
-### package.json 脚本
+> 具体目录布局由项目结构决定（单包、monorepo 子包、扁平 `src/views/` 等），AI 自行判断；唯一不变的是"测试目录独立、与源码并列"。
 
-```json
-{
-  "scripts": {
-    "test": "vitest",
-    "test:run": "vitest run"
-  }
-}
+---
+
+## 二、技术栈
+
+- **Vitest** + **@vue/test-utils** + **happy-dom**
+- 测试 API 请求时用 Vitest 内置 mock 或 `msw`，**禁止**真发起网络
+
+```bash
+pnpm add -D vitest @vue/test-utils happy-dom
 ```
 
-### vitest.config.ts（独立文件，不写在 vite.config.ts 中）
+### vitest.config.ts
 
 ```typescript
 import { fileURLToPath } from 'node:url'
@@ -43,9 +80,7 @@ import vue from '@vitejs/plugin-vue'
 export default defineConfig({
   plugins: [vue()],
   resolve: {
-    alias: {
-      '@': fileURLToPath(new URL('./src', import.meta.url)),
-    },
+    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
   },
   test: {
     environment: 'happy-dom',
@@ -54,49 +89,79 @@ export default defineConfig({
 })
 ```
 
-### 目录结构与导入
+### tsconfig.app.json
 
+```json
+{
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
+}
 ```
-tests/
-├── utils/format.test.ts        # 测试 src/utils/format.ts
-├── stores/auth.test.ts         # 测试 src/stores/auth.ts
-├── api/client.test.ts          # 测试 src/api/client.ts
-└── router/index.test.ts        # 测试 src/router/index.ts
+
+### package.json 脚本
+
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}
 ```
 
-测试文件中通过 `@` 别名导入源码，**禁止**使用相对路径回溯到 `src/`：
+---
 
-```typescript
-// ✅ 使用 @ 别名
-import { formatBytes } from '@/utils/format'
-import { useAuthStore } from '@/stores/auth'
+## 三、测试编写规范
 
-// ❌ 禁止相对路径回溯
-import { formatBytes } from '../../src/utils/format'
-```
+### 强制规则
 
-### 打包隔离
+- 测试结构遵循 **Arrange-Act-Assert**
+- 一个测试只验证**一个行为**，**禁止**一个 test 函数堆多个不相关断言
+- 断言必须具体（字段值），**禁止**只断言"不报错"
+- 必须覆盖：成功路径、失败路径、边界值
+- 测试中**必须**用 `@` 别名导入源码
 
-`tsconfig.app.json` 的 `include` 只包含 `src/`，确保 `tests/` 不会被 `vue-tsc` 编译和打包：
+```typescript
+// tests/modules/users/store.test.ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import { useAuthStore } from '@/modules/users/store'
 
-```json
-{
-  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
-}
-```
+describe('useAuthStore', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
 
-**禁止**在 `tsconfig.app.json` 中 include `tests/`。
+  it('isLoggedIn 在 token 为 null 时返回 false', () => {
+    // Arrange
+    const store = useAuthStore()
 
-### 禁止的写法
+    // Act + Assert
+    expect(store.isLoggedIn).toBe(false)
+  })
 
+  it('logout 后清空 token 与 user', () => {
+    const store = useAuthStore()
+    store.$patch({ token: 'abc', user: { uuid: 'u1' } as any })
+
+    store.logout()
+
+    expect(store.token).toBeNull()
+    expect(store.user).toBeNull()
+  })
+})
 ```
-# ❌ 测试文件放在 src/ 内
-src/utils/format.test.ts
-src/stores/__tests__/auth.test.ts
-src/components/Button.test.ts
-
-# ✅ 测试文件放在独立 tests/ 目录
-tests/utils/format.test.ts
-tests/stores/auth.test.ts
-tests/components/Button.test.ts
-```
+
+---
+
+## 四、违规检测清单
+
+| 检查项 | 违规模式 | 严重程度 |
+|--------|---------|---------|
+| 测试与源码混放 | 测试文件放 `src/` 内（`src/utils/format.test.ts` / `src/**/__tests__/`） | 高 |
+| 打包污染 | `tsconfig.app.json` 的 `include` 包含 `tests/` | 高 |
+| 相对路径回溯 | 测试中 `import ... from '../../../src/...'` 而非 `@/` 别名 | 中 |
+| 测试目录不规范 | 项目无独立 `tests/` 目录或 `vitest.config.ts` 未显式声明 `include` | 高 |
+| 测试无断言 | 只调用接口不断言响应字段 | 高 |
+| 测试依赖泄漏 | `vitest` / `@vue/test-utils` 等出现在 `dependencies` | 高 |
+| 真发起网络 | 测试中直接调真实后端 API，未 mock | 高 |
+| 测试镜像断裂 | 测试目录结构与 `src/` 业务聚合结构不对应，难以定位 | 中 |

package/templates/claude-global/skills/dwy-deploy-audit/references/checks-network.md

@@ -35,7 +35,7 @@
 | `server_tokens` | `off` | medium |
 | `access_log` | 已开启 | **high**(用户特别要求) |
 | `error_log` | 已开启,级别 ≥ warn | high |
-| `client_max_body_size` | 显式配置,业务非上传 ≤ 10m(对齐 dwy-payload-limits) | medium |
+| `client_max_body_size` | 显式配置,业务非上传 ≤ 10m | medium |
 | `limit_req_zone` 已定义 | 至少 1 个 zone（防 CC 攻击 / 暴力请求） | high |
 | `limit_req` 应用到敏感路由 | 登录 / 注册 / 验证码 / 高频 API 必须有 | **critical** |
 | `limit_conn_zone` + `limit_conn` | 限制同 IP 高并发连接 | medium |

package/templates/claude-global/skills/dwy-deploy-audit/scripts/check_nginx.sh

@@ -52,7 +52,7 @@ else
   echo "$NGINX_DUMP" | grep -E "^[[:space:]]*(access_log|error_log)" | head -10
 
   echo ""
-  echo "--- client_max_body_size (对齐 dwy-payload-limits) ---"
+  echo "--- client_max_body_size (业务非上传 ≤ 10m) ---"
   echo "$NGINX_DUMP" | grep -E "^[[:space:]]*client_max_body_size" || echo "[!] 未显式配置 client_max_body_size"
 
   echo ""

package/templates/claude-global/skills/dwy-dolphindb/SKILL.md

@@ -3,12 +3,15 @@ name: dwy-dolphindb
 description: >
   DolphinDB 开发规范与最佳实践审查。当用户要求生成、修改、审查或优化涉及
   DolphinDB 的 Python/SQL 代码、脚本拼接、批量写入、查询优化、连接管理、分区
-  裁剪、数据类型转换、Docker 配置或测试 Mock 时，**必须**使用此 skill。即使
-  用户没有明确提到 "DolphinDB"，但只要代码中出现 dolphindb、run_ddb、
-  loadTable、append!、dropPartition、DBConnectionPool、DDBSession、tickDB、
-  factorDB 等关键字，或涉及 TSDB 分区、时间序列数据库存储、金融 tick 数据/因子
-  数据写入，也要触发此 skill。用于确保代码符合社区版 8GB 内存限制、2 节点集群
-  限制、分区裁剪、输入校验、批量写入 ≤500K 行等硬约束。
+  裁剪、分区方案设计（OLAP/TSDB/PKEY 引擎单分区大小估算、范围/值/哈希分区选型）、
+  STRING/BLOB/SYMBOL 字段长度限制、数据类型转换、Docker 配置或测试 Mock 时，
+  **必须**使用此 skill。即使用户没有明确提到 "DolphinDB"，但只要代码中出现
+  dolphindb、run_ddb、loadTable、append!、dropPartition、DBConnectionPool、
+  DDBSession、tickDB、factorDB、addRangePartitions、newValuePartitionPolicy
+  等关键字，或涉及 TSDB 分区、时间序列数据库存储、金融 tick 数据/因子数据写入，
+  也要触发此 skill。用于确保代码符合社区版 8GB 内存限制、2 节点集群限制、
+  分区裁剪（包括禁止链式比较 `a <= col <= b`）、输入校验、批量写入 ≤500K 行、
+  SYMBOL ≤255 字节、单分区大小落在引擎推荐区间等硬约束。
 ---
 
 # DolphinDB 开发规范 Skill
@@ -39,12 +42,13 @@ description: >
 | 任务类型 | 重点章节 |
 |---|---|
 | 查询脚本编写 | 三（分区裁剪）、八（查询优化） |
-| 批量数据写入 | 二（连接管理）、四（批量写入）、十（数据类型映射） |
+| 建库建表/分区方案设计 | 十二（分区设计原则） |
+| 批量数据写入 | 二（连接管理）、四（批量写入）、十（数据类型映射）、十三（字符串长度限制） |
 | 脚本拼接/动态生成 | 五（脚本语法）、六（输入校验） |
 | 服务层 Python 代码 | 二（连接管理）、六（输入校验）、十（数据类型映射） |
 | Docker/部署配置 | 九（Docker 环境） |
 | 测试代码 | 十一（测试 Mock） |
-| 代码审查/CR | 全部，尤其是十二（检查清单） |
+| 代码审查/CR | 全部，尤其是十四（检查清单） |
 
 ### 3. 执行规则审查
 
@@ -72,16 +76,19 @@ description: >
 以下问题会直接导致生产故障或 OOM，必须零容忍：
 
 1. **分区列被函数包裹**（如 `date(trade_date)`）→ 全表扫描 → 8GB OOM
-2. **单次 append 超过 500K 行** → TSDB 报错 `exceeds max limit`
-3. **未校验的外部输入拼接到脚本** → 脚本注入风险
-4. **连接池做 upload + run** → 变量跨连接不可见
-5. **select *** → 传输全部 30+ 列，浪费带宽和内存
-6. **分页使用 `LIMIT x OFFSET y`** → DolphinDB 不支持 OFFSET 关键字
-7. **`asyncio.to_thread(pool.run, script)`** → SDK v3 的 `pool.run()` 已是原生 async，无需包装
+2. **链式比较过滤**（如 `2022.12.01 <= TradeDate <= 2022.12.03`）→ 不触发分区剪枝 → 全表扫描
+3. **单次 append 超过 500K 行** → TSDB 报错 `exceeds max limit`
+4. **未校验的外部输入拼接到脚本** → 脚本注入风险
+5. **连接池做 upload + run** → 变量跨连接不可见
+6. **select *** → 传输全部 30+ 列，浪费带宽和内存
+7. **分页使用 `LIMIT x OFFSET y`** → DolphinDB 不支持 OFFSET 关键字
+8. **`asyncio.to_thread(pool.run, script)`** → SDK v3 的 `pool.run()` 已是原生 async，无需包装
+9. **SYMBOL 列写入未校验长度** → 超 255 字节抛异常，整批写入失败
+10. **建表分区方案过细**（如每天 5000+ 个 0.6MB 小分区）→ 命中 `maxPartitionNumPerQuery=65536` 限制
 
 ### 5. 检查清单应用
 
-如果任务是**代码审查**或**最终确认**，逐条过一遍 `references/dolphindb-rules.md` 第十二章的检查清单（12 项），并给出通过/不通过的明确结论。
+如果任务是**代码审查**或**最终确认**，逐条过一遍 `references/dolphindb-rules.md` 第十四章的检查清单（13 项），并给出通过/不通过的明确结论。
 
 ## 输出要求
 

package/templates/claude-global/skills/dwy-dolphindb/evals/evals.json

@@ -39,6 +39,29 @@
         "输出中明确指出了连接池 upload + run 的问题",
         "输出中为每个问题都提供了修复后的代码片段"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "审查以下 DolphinDB 查询脚本是否能触发分区剪枝，并给出修复后的脚本：\n```sql\nselect * from loadTable(\"dfs://tickDB\", \"snapshots\")\nwhere 2022.12.01 <= TradeDate <= 2022.12.03\n  and order_book_id = \"000001.SZ\"\n```",
+      "expected_output": "审查必须指出：1) `2022.12.01 <= TradeDate <= 2022.12.03` 是链式比较，DolphinDB 不识别两端边界，无法做分区剪枝，会扫描全部分区；2) 给出修复方案：改为 `TradeDate between 2022.12.01 and 2022.12.03` 或拆成 `TradeDate >= 2022.12.01 and TradeDate <= 2022.12.03`；3) 同时指出 select * 浪费带宽，应只取需要的列。",
+      "files": [],
+      "assertions": [
+        "输出中明确指出了链式比较无法触发分区剪枝",
+        "输出中提供了 between ... and ... 或拆分为两个独立条件的修复方案",
+        "输出中提到了 select * 的问题"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "帮我设计一张存储股票 tick 数据的 DolphinDB 分布式表，每天约 5000 万条记录，覆盖国内 5000 只股票，使用 TSDB 引擎。给出分区方案并说明理由。",
+      "expected_output": "方案必须：1) 一级 VALUE 分区按 TradeDate，二级用 HASH 分区按 SecurityID（约 20 桶），而不是 VALUE 分区，避免每天 5000+ 个小分区命中 maxPartitionNumPerQuery=65536 限制；2) 估算单分区大小（每天 3GB / 20 桶 ≈ 150MB，落在 TSDB 推荐区间 400MB~1GB 之下但仍可接受，或调整桶数让单分区更接近 400MB）；3) 提醒分区方案一经确定无法调整；4) 提醒 SYMBOL 列 SecurityID 写入前需校验 ≤255 字节。",
+      "files": [],
+      "assertions": [
+        "方案中二级分区使用 HASH 而非 VALUE",
+        "方案中包含单分区大小估算并参考 TSDB 100MB~1GB 推荐区间",
+        "方案中提到 maxPartitionNumPerQuery=65536 或避免分区数爆炸",
+        "方案中提到 SYMBOL 列长度校验或 ≤255 字节限制"
+      ]
     }
   ]
 }

package/templates/claude-global/skills/dwy-dolphindb/references/dolphindb-rules.md

@@ -74,6 +74,26 @@ WHERE trade_date >= 2020.01.01, trade_date < 2020.02.01
 WHERE order_book_id in [`000001.XSHE`000002.XSHE]
 ```
 
+### 范围查询禁止链式过滤
+
+DolphinDB 不识别链式比较的两端边界，无法做分区剪枝。必须用 `between ... and ...` 或拆成两个独立条件。
+
+```sql
+-- ❌ 链式过滤 → 全表扫描（实测扫描 10091 个分区）
+select * from loadTable(dbName, tbName)
+where 2022.12.01 <= TradeDate <= 2022.12.03
+
+-- ✅ between ... and ... → 分区剪枝（实测扫描 90 个分区）
+select * from loadTable(dbName, tbName)
+where TradeDate between 2022.12.01 and 2022.12.03
+
+-- ✅ 拆成两个独立条件 → 分区剪枝
+select * from loadTable(dbName, tbName)
+where TradeDate >= 2022.12.01 and TradeDate <= 2022.12.03
+```
+
+可用 `[HINT_EXPLAIN]` 查看实际扫描的分区数验证：`select [HINT_EXPLAIN] * from ...` 输出中的 `partitions.local` 数量应等于范围内的分区数，而不是全库分区数。
+
 ### tickDB 分区列
 - 第一级：`trade_date`（VALUE 分区，按日）
 - 第二级：`order_book_id`（HASH 分区，20 桶）
@@ -87,6 +107,7 @@ WHERE order_book_id in [`000001.XSHE`000002.XSHE]
 - `date(...)` / `month(...)` / `year(...)` 包裹分区列
 - `WHERE 1=1` 无分区条件（全表扫描）
 - `select * from loadTable(...)` 无 WHERE 子句
+- 链式比较 `a <= col <= b`（必须改为 `between a and b` 或拆成两个独立条件）
 
 ## 四、批量写入
 
@@ -326,11 +347,87 @@ patch("app.services.tick_archive.run_ddb", ...)
 patch("app.services.tick_compute.run_ddb", ...)
 ```
 
-## 十二、检查清单
+## 十二、分区设计原则（建表时）
+
+### 单分区合理大小（压缩前）
+
+| 引擎 | 推荐范围 | 说明 |
+|---|---|---|
+| OLAP | 100MB ~ 300MB | 列存按分区粒度加载，过大易 OOM |
+| TSDB / PKEY | 400MB ~ 1GB | 内部还有 LevelFile 二级组织，单分区可大一些 |
+
+分区过小：元数据膨胀、查询时分区数爆炸、命中 `maxPartitionNumPerQuery` 限制（默认 65536）。
+分区过大：单分区加载内存压力大、并行度下降、删除/重写代价高。
+
+### 分区层级与类型
+
+| 维度 | 规则 |
+|---|---|
+| 层级 | 最少 1 级，最多 3 级；分区方案一经确定无法调整，库下所有表共用 |
+| 范围分区 (RANGE) | **只能向后扩展且无法自动扩展**，需手动 `addRangePartitions` |
+| 范围分区越界数据 | `allowMissingPartitions=true`（默认）会**静默丢弃**范围外数据；需要报错改为 `false` |
+| 值分区 (VALUE) | 可自动扩展（需 `newValuePartitionPolicy=add`）；**不宜初始化过多空分区** |
+| 哈希分区 (HASH) | 桶数固定，建库后不可改 |
+
+### 分区方案设计反例
+
+> 股票行情数据（每天 5000 万条记录），先按 `TradeDate` 值分区，再按 `SecurityID` 二级值分区。
+> 假设全是国内股票（约 5000 只），一天分区数就达 5000+。每天数据 3GB，**每个分区只有约 0.6MB**。
+
+后果：
+- 默认 `maxPartitionNumPerQuery=65536`，每天 5000 个分区，**查 14 天就报错**：`The number of partitions relevant to the query is too large`
+- 单分区 0.6MB 远低于 OLAP 100MB / TSDB 400MB 推荐下限，元数据开销远大于数据本身
+- 修复方向：二级分区改用 `HASH(SecurityID, 20)`（按经验固定 20 桶），或合并到日粒度单级分区
+
+### 设计检查项
+
+- [ ] 单分区估算大小是否落在引擎推荐区间？
+- [ ] 总分区数是否远低于单次查询 65536 上限？
+- [ ] 二级是否用了高基数列做 VALUE 分区？（高基数列优先 HASH）
+- [ ] RANGE 分区是否预留了 `addRangePartitions` 的扩展机制？是否需要 `allowMissingPartitions=false`？
+
+## 十三、字符串/BLOB/SYMBOL 长度限制
+
+自 **1.30.23 / 2.00.11** 版本起，分布式表写入对字符串类数据增加了硬性大小限制：
+
+| 类型 | 上限 | 超限行为 |
+|---|---|---|
+| `STRING` | < 64 KB | 静默截断到 65,535 字节（64 KB - 1） |
+| `BLOB` | < 64 MB | 静默截断到 67,108,863 字节（64 MB - 1） |
+| `SYMBOL` | ≤ 255 字节 | **直接抛异常**，写入失败 |
+
+### 强制规则
+
+写入前必须做长度校验，**特别是 SYMBOL 列会让整批写入失败**：
+
+```python
+# ✅ 写入前校验 SYMBOL 列长度
+MAX_SYMBOL_BYTES = 255
+oversize_mask = batch_df["order_book_id"].str.encode("utf-8").str.len() > MAX_SYMBOL_BYTES
+if oversize_mask.any():
+    raise BusinessError(
+        f"SYMBOL 列 order_book_id 有 {oversize_mask.sum()} 行超过 255 字节"
+    )
+```
+
+### 类型选择建议
+
+- 短编码字段（股票代码、因子名）→ `SYMBOL`，但必须保证 ≤ 255 字节
+- 用户可输入的中等长度文本（备注、描述）→ `STRING`，注意 64 KB 截断风险，超长字段做应用层校验
+- 大文本/二进制（JSON、文件）→ `BLOB`，超长会被截断而不是报错，**截断不可逆**，必须在应用层校验长度
+- 中文按 UTF-8 编码，1 字符 ≈ 3 字节，预估时按字节而非字符
+
+### 违规检测
+
+- 写入路径上对 `SYMBOL` 列没有长度校验 → 整批写入可能失败
+- 写入 `STRING`/`BLOB` 时没有长度上限断言 → 数据被静默截断，事后无法恢复
+
+## 十四、检查清单
 
 每次涉及 DolphinDB 的代码变更，必须逐条检查：
 
 - [ ] WHERE 条件是否命中分区列？是否有函数包裹分区列？
+- [ ] 范围条件是否使用 `between ... and ...` 或两个独立条件？是否存在链式比较 `a <= col <= b`？
 - [ ] 批量写入是否 ≤ 500K 行？是否有 `gc.collect()`？
 - [ ] 外部输入是否经过 `validators.py` 校验？
 - [ ] 使用 `run_ddb` 还是 `run_ddb_with_data`？场景是否匹配？
@@ -340,3 +437,5 @@ patch("app.services.tick_compute.run_ddb", ...)
 - [ ] 脚本中 backtick 列名是否在单行内？
 - [ ] 新增 service 文件的 `run_ddb` 导入是否在 conftest.py 中 mock？
 - [ ] 分页查询是否使用 `limit offset, count` 语法？（禁止 `LIMIT x OFFSET y`）
+- [ ] 新建库表时单分区估算大小是否在引擎推荐区间内？总分区数是否远低于 65536？
+- [ ] 写入路径对 `SYMBOL` 列是否有 ≤ 255 字节长度校验？`STRING` / `BLOB` 是否有上限断言以避免静默截断？