@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/miaoda/lark-apps-ops/references/lark-apps-plugin-install.md

@@ -0,0 +1,36 @@
+# apps +plugin-install
+
+> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。
+
+安装插件包到项目。运行时命令事实以 `lark-cli apps +plugin-install --help` 为准。
+
+## 何时用
+
+用户要接入 AI 能力或飞书平台能力，需要先安装对应的插件包。安装后才能创建插件实例。具体有哪些可用插件、该选哪个，读取创建的应用仓库 Skill：`.agents/skills/plugin-guide/SKILL.md`。
+
+**插件包 ≠ npm 包**：插件包写入 `actionPlugins`，npm 写入 `dependencies`，两套独立机制。禁止用 `npm install` 代替本命令。
+
+## 命令骨架
+
+- `--name <key>`：插件包 key（从仓库 Skill 的「AI 插件目录」获取）。不传则批量安装 `actionPlugins` 中声明的所有插件。
+- `--version <ver>`：指定版本（如 `1.0.0`）。不传则安装最新版。
+
+在项目根目录下运行（和 npm 一样，无需指定路径）。
+
+## 示例
+
+```bash
+# 安装最新版
+lark-cli apps +plugin-install --name <plugin-key>
+
+# 安装指定版本
+lark-cli apps +plugin-install --name <plugin-key> --version 1.0.0
+
+# 批量安装已声明的所有插件
+lark-cli apps +plugin-install
+```
+
+## 输出契约
+
+- 已安装同版本会跳过（status=already_installed）。
+- 失败时 hint 指示原因（网络/版本不存在/package.json 缺失）。

package/miaoda/lark-apps-ops/references/lark-apps-plugin-list.md

@@ -0,0 +1,23 @@
+# apps +plugin-list
+
+> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。
+
+列出已声明的插件包及安装状态。运行时命令事实以 `lark-cli apps +plugin-list --help` 为准。
+
+## 何时用
+
+查看当前项目声明了哪些插件、是否已安装。`declared_not_installed` 状态表示需要运行 `+plugin-install` 安装。
+
+## 命令骨架
+
+在项目根目录下运行（和 npm 一样，无需指定路径）。
+
+## 示例
+
+```bash
+lark-cli apps +plugin-list --format json
+```
+
+## 输出契约
+
+- `data.plugins[]` 包含 `key`、`version`、`status`（`installed` / `declared_not_installed`）。

package/miaoda/lark-apps-ops/references/lark-apps-plugin-uninstall.md

@@ -0,0 +1,25 @@
+# apps +plugin-uninstall
+
+> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。
+
+卸载插件包。运行时命令事实以 `lark-cli apps +plugin-uninstall --help` 为准。
+
+## 何时用
+
+用户不再需要某个插件能力时，卸载对应的插件包。卸载前应先删除该插件的所有实例。
+
+## 命令骨架
+
+- `--name <key>`：要卸载的插件包 key。
+
+在项目根目录下运行（和 npm 一样，无需指定路径）。
+
+## 示例
+
+```bash
+lark-cli apps +plugin-uninstall --name <plugin-key>
+```
+
+## 输出契约
+
+- 删除 `node_modules/{key}` + 移除 `actionPlugins` 条目。

package/miaoda/lark-apps-ops/references/lark-apps-release-create.md

@@ -0,0 +1,30 @@
+# apps +release-create
+
+为妙搭应用创建发布 release。运行时命令事实以 `lark-cli apps +release-create --help` 为准。
+
+## 何时用
+
+用于把全栈应用的代码分支推进到发布流程。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选：`--branch`；省略时服务端使用默认发布分支。
+- 返回 `release_id` 和 `status`，后续用 `+release-get` 轮询。
+
+## 示例
+
+```bash
+lark-cli apps +release-create --app-id "$app_id"
+lark-cli apps +release-create --app-id "$app_id" --branch sprint/default --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.release_id` 和 `data.status`；`release_id` 是后续 `+release-get` 的入参。
+- `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。
+- `+release-create` 返回 release 只代表发布已发起。只有 `+release-get` 对同一个 `release_id` 返回 `finished` 后，才能说本轮最新版本已部署。
+
+## Agent 规则
+
+`+release-create` 部署的是远端 `sprint/default` 上已 push 的代码，不是本地工作区——本地若有你修改但未推送的改动，需要先 `git add` + `git commit` 并 `git push` 到 `sprint/default`，否则这些改动不会进入这次发布。发布后若 status 是 `publishing`，用 [`+release-get`](lark-apps-release-get.md) 查询。`+release-create` 部署上线属高影响动作——作为别的命令的连带前置时，按 SKILL.md「发布态护栏」先征得用户同意再发布。

package/miaoda/lark-apps-ops/references/lark-apps-release-get.md

@@ -0,0 +1,28 @@
+# apps +release-get
+
+按 release ID 查询单次发布详情。运行时命令事实以 `lark-cli apps +release-get --help` 为准。
+
+## 何时用
+
+用于跟进已知 `release_id` 的发布状态。没有 `release_id` 时先读 [`lark-apps-release-list.md`](lark-apps-release-list.md)，不要让用户手填。
+
+`release_id` 是妙搭发布 ID（`+release-create` 返回），不是飞书审批实例号；查发布进度/失败都在 `apps +release-*` 命令族内完成，不要路由到 lark-approval。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--release-id`。
+- `release_id` 来自 `+release-create` 或 `+release-list`。
+
+## 示例
+
+```bash
+lark-cli apps +release-get --app-id "$app_id" --release-id <release_id>
+```
+
+## 输出契约
+
+- 成功可能直接返回 release 字段，也可能包在 `data.release`；读取 `release_id`、`status`、`created_at`、`updated_at`，以及 `commit_id`（本轮发布对应的 git commit SHA，pretty 输出在其非空时展示一行）。
+- `status=publishing` 继续轮询。此时尚无 `online_url`；不要拿其它链接（如应用主页 / 开发态预览 URL）冒充"本轮发布的访问链接"——只回报 `release_id`、`status`，并说明 `finished` 后才有 `online_url`。
+- `status=finished` 发布成功——**本命令输出已含 `online_url`，直接读取它作为本轮发布的线上访问链接**返回用户。
+- `status=failed` 发布失败——**本命令输出已含 `error_logs`（`step`/`error_log`），直接据此向用户转述关键失败步骤和可行动修复**。
+- 只有当这个 `release_id` 已返回 `finished`，随后读到的 `online_url` 才能被表述为"本轮发布后的访问链接"；未经 `+release-get` 确认 `finished` 的任何旁证都不能证明最新版本已部署。

package/miaoda/lark-apps-ops/references/lark-apps-release-list.md

@@ -0,0 +1,31 @@
+# apps +release-list
+
+分页查询妙搭应用发布历史，最新发布在前。运行时命令事实以 `lark-cli apps +release-list --help` 为准。
+
+## 何时用
+
+用户问"最近发布""历史版本""上次为什么失败"，但没有提供 `release_id` 时使用。拿到候选 release 后再接 `+release-get`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选 `--status`：`publishing` / `finished` / `failed`。
+- 可选 `--page-size`：默认 20，最大 500；总是发送给服务端。
+- 可选 `--page-token`：上一页 cursor。
+
+## 示例
+
+```bash
+lark-cli apps +release-list --app-id "$app_id" --page-size 10
+lark-cli apps +release-list --app-id "$app_id" --status failed
+```
+
+## 输出契约
+
+- 成功读取 `data.releases[]`；关键字段是 `release_id`、`status`、`created_at`、`updated_at`。
+- `release_id` 用于继续查 `+release-get`。
+- 若 `has_more=true`，用 `next_page_token` / `page_token` 翻页。
+
+## Agent 规则
+
+用户限定只看 N 条（"最近 N 条""最新 N 个""只要前 N 条"）时用 `--page-size N`（如"最近一次发布"→ `--page-size 1`），而不是取全量再本地截断。

package/miaoda/lark-apps-ops/references/lark-apps-update.md

@@ -0,0 +1,30 @@
+# apps +update
+
+部分更新妙搭应用元信息。运行时命令事实以 `lark-cli apps +update --help` 为准。
+
+## 何时用
+
+只更新应用展示元信息。用户要改代码、发布内容、可见范围或数据库时，不走 `+update`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 至少提供一个：`--name` 或 `--description`。
+- 只发送用户提供的字段，不会清空未提供字段。
+
+## 示例
+
+```bash
+lark-cli apps +update --app-id "$app_id" --name "审批系统"
+lark-cli apps +update --app-id "$app_id" --description "用于部门审批流转"
+lark-cli apps +update --app-id "$app_id" --name "审批系统" --description "用于部门审批流转" --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.app`；响应是完整应用对象，不只是被修改字段。
+- 缺 `--app-id` 或没有提供 `--name` / `--description` 会在本地 validation 失败。
+
+## Agent 规则
+
+更新前复述要变更的字段；用户没有提到的字段不要补默认值。执行后只转述新的名称/描述和 app_id，不需要展开原始响应。

package/miaoda/lark-apps-ops/references/openapi-key.md

@@ -0,0 +1,80 @@
+# apps openapi-key 命令族（开放 API Key）
+
+管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。命令事实以 `lark-cli apps +openapi-key-list --help`（各子命令同理）为准；本文件只记录 Agent 不看就会做错的领域规则。鉴权由沙箱运行环境自动注入（见 SKILL.md「鉴权自动」），命令无需也不要传身份参数。
+
+## 命令路由
+
+| 命令 | 用途 |
+|---|---|
+| `+openapi-key-list` | 列出应用所有 API Key（脱敏） |
+| `+openapi-key-get` | 查看单个 Key 详情（脱敏） |
+| `+openapi-key-create` | 创建新 Key，**原始密钥一次性可见** |
+| `+openapi-key-update` | 改名或改 config（不改 status） |
+| `+openapi-key-enable` | 启用 Key（status→1） |
+| `+openapi-key-disable` | 停用 Key（status→0），**泄露/疑似泄露优先用这个而非 delete** |
+| `+openapi-key-delete` | 永久删除 Key（不可逆，高风险） |
+| `+openapi-key-reset` | 轮换密钥（刷新原始 Key），**一次性可见**（高风险） |
+
+命令均带 `--app-id "$app_id"`（当前沙箱应用），如：
+
+```bash
+lark-cli apps +openapi-key-list --app-id "$app_id"
+```
+
+## 密钥红线（安全关键，务必遵守）
+
+- `create` / `reset` 返回的**原始密钥仅一次性可见**：只在 `data.api_key`（顶层）随本次响应返回一次，同时 stderr 打印一次性提示（大意：此密钥仅显示一次、不被 lark-cli 保存，请立即复制到你自己的密钥管理器）。
+- **绝不**把原始密钥写入 cache / config / recent / debug log / 错误信息，也不要在后续对话里回显完整密钥；只向用户转述一次并提示自行妥善保管。
+- **密钥丢失不能找回**：`list` / `get` 不回显原始密钥。唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。
+
+## 脱敏口径
+
+- `list` / `get` / `update` / `enable` / `disable`：返回结构里 **无** `api_key` 字段，只有 `key_preview`（格式：`****` + 原始密钥末 4 位，如 `****5f4a`）。
+- `create` / `reset`：**仅** 在 `data.api_key`（顶层）返回原始密钥一次（见上「密钥红线」）。
+
+## scope 结构与 CLI 表达
+
+后端 `config.request_scope` 的真实结构（**snake_case**——Lark 开放网关 `/open-apis/` 对外契约约定；`api_key.thrift` 的 camelCase go.tag 是内部表示，OGW 已转成 snake_case）：
+
+```json
+{
+  "allow_all": true,
+  "http_infos": [
+    { "http_method": "GET", "http_path": "/openapi/some-path" }
+  ]
+}
+```
+
+- `allow_all=true`：放开该应用所有 `/openapi/**` 路由；`http_infos` 此时忽略。
+- `allow_all=false`：按 `http_infos` 逐条授权，每条需 `http_method`（大写）+ `http_path`（`/openapi/` 开头）。
+
+CLI 提供三种互斥的 scope 表达方式：
+
+| flag | 用途 | 备注 |
+|---|---|---|
+| `--scope-all` | `allow_all=true`，放开所有路由 | bool flag，显式传 `--scope-all=false` 也算"已设置" |
+| `--scope-api 'METHOD /openapi/path'` | 逐条授权一个路由，可重复 | 路由从应用 `docs/openapi.json` 取 |
+| `--scope '<raw request_scope JSON>'` | 高级逃生口，直传 request_scope JSON（snake_case） | CLI 只校验合法 JSON；`--scope` 与 `--scope-all`/`--scope-api` 互斥 |
+
+### scope 值来源
+
+妙搭应用的 `/openapi/**` 路由定义在应用仓库，并同步维护在 `docs/openapi.json`（`paths` 下每个 `"/openapi/..."` 条目 + HTTP 方法）。要授权哪些路由，读目标应用自己的 `docs/openapi.json`，取 `(method, path)` 对。CLI 本身不提供 API 路由发现功能（P1 规划中）。
+
+## 高风险操作（delete / reset）
+
+`delete` 和 `reset` 是高风险写操作（`high-risk-write`）：缺 `--yes` 会 **exit 10**（`confirmation_required`），须按 SKILL.md 的 exit-10 审批协议先征得用户显式同意再补 `--yes`——**不要**自动补 `--yes`；不确定先 `--dry-run` 查看将执行的 HTTP 请求（不含密钥）。
+
+- **泄露场景**：应优先 `+openapi-key-disable` 立即停用，而非 `+openapi-key-delete`——停用可随时 `+openapi-key-enable` 恢复，delete 不可逆。
+
+## 典型决策场景
+
+| 用户意图 | 正确操作 |
+|---|---|
+| "key 泄露了，先停掉" | `+openapi-key-disable`（不是 delete） |
+| "key 丢了/忘了，再给我一个" | `+openapi-key-reset`（不是 create 新 key；reset 轮换密钥、保留原 key 配置） |
+| "我的 key 密钥是什么" | 解释：list/get 不回显原始密钥，只能用 `+openapi-key-reset` 轮换 |
+| "给应用创建一个有权限限制的 key" | `+openapi-key-create --name ... --scope-api 'GET /openapi/...'`（路由取自应用 `docs/openapi.json`） |
+
+## 不在本 skill 范围
+
+- OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。

package/miaoda/miaoda-file/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: miaoda-file
 description: "Use when Agent 需要在对话 / 开发中对应用存储里的文件做一次性操作：上传、下载、列出、删除、清理、查看元数据，或获取下载 / 临时分享链接（如分析数据后上传产物、传素材、灌测试数据、验证上传、清理）。NOT for 应用运行时代码里的文件能力——前端用 client-builtins-file-storage-service、后端用 server-builtins-file-storage-service。触发词：文件上传, 文件下载, 文件列表, 文件删除, 文件清理, 文件查看, 文件元数据, 下载链接, 临时分享链接, miaoda file, 应用存储"
+control-by-feature-ab: true
 ---
 
 # miaoda-file

package/miaoda/miaoda-sql/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: miaoda-sql
-description: Use when creating or modifying Miaoda PostgreSQL tables, running `miaoda db` SQL/schema/data commands, seeding mock data, or handling audit/changelog/migration/recovery. 触发词：miaoda db, SQL, 建表, 改表, 数据库, mock 数据, 示例数据, 数据审计, 变更历史, 数据恢复, PITR, 多环境发布
+description: Use when creating or modifying Miaoda PostgreSQL tables, writing or troubleshooting RLS policies, running `miaoda db` SQL/schema/data commands, seeding mock data, or handling audit/changelog/migration/recovery. 触发词：miaoda db, SQL, 建表, 改表, 数据库, mock 数据, 示例数据, 数据审计, 变更历史, 数据恢复, PITR, 多环境发布, RLS, policy, pgPolicy, 行级权限, SQLSTATE 42501 (permission denied)
+control-by-feature-ab: true
 gate-tools:
   - tool: bash
     when-contains:
@@ -134,6 +135,7 @@ CREATE POLICY "修改本人数据" ON <table>
 | user_profile 表达式索引 / 唯一性 | 索引用三重括号：`CREATE INDEX ... ON t (((owner).user_id))`；表达式唯一性用 `CREATE UNIQUE INDEX`，不要用 `ALTER TABLE ADD CONSTRAINT UNIQUE` |
 | UUID 手写 | 主键用 `DEFAULT gen_random_uuid()`；INSERT 不手写 UUID，外键用子查询取父表 id |
 | MySQL 方言 | 不用 `SHOW TABLES` / `DESCRIBE` / 内联 `COMMENT`；改用 schema 命令和 `COMMENT ON` |
+| 日期列当字符串用 | 按月 / 按天筛选写范围比较 `col >= '2026-08-01' AND col < '2026-09-01'`；date / timestamptz 上 `LIKE '2026-08%'` 报 42883 |
 | 空数组类型不明 | 写 `ARRAY[]::text[]` 或 `'{}'::text[]` |
 | 标量子查询多行 | `VALUES((SELECT ...))` / `SET col=(SELECT ...)` 必须唯一或 `ORDER BY ... LIMIT 1` |
 | 系统表查询 | 常规结构查询用 schema 命令；系统表仅限 reference 中列出的白名单 |
@@ -161,7 +163,9 @@ CREATE POLICY "修改本人数据" ON <table>
 | 关联 | 外键 / 子查询引用的数据必须已存在；UUID 字段不用手写 |
 | 审计列 | `_created_at` / `_updated_at` 可省略；需要归属时显式写 `_created_by` / `_updated_by` |
 
-测试用户：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
+测试用户（**只用于数据库 `user_profile` 列**）：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
+
+> ⚠️ 这些是妙搭数字 user_id，**不是飞书 open_id**。需要 open_id（`ou_` 开头）的场景一律另行解析，禁止直接复用这些数字 ID。
 
 ### `user_id` / `user_profile`
 

package/miaoda/performance-review/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: performance-review
+description: "Fullstack performance audit checklist for the Reviewer agent. Covers frontend rendering, data fetching, memory, loading, backend queries, algorithm complexity, concurrency. 触发词：性能审查, performance review, 性能问题"
+hook: SessionStart
+available-agents:
+  - Reviewer
+---
+
+# Performance Review Checklist
+
+## Frontend Rendering & State
+
+**Reference stability (trace origin):**
+- Dependencies of useEffect/useMemo/useCallback containing object/array refs — trace whether the ref is recreated each render
+- Event listener cleanup referencing the same function instance as addEventListener
+
+**Render path cost:**
+- Inline .filter()/.map()/.sort()/new Set()/new Date() in JSX — should extract to useMemo
+- Large lists (100+ items) without virtualization
+- Large components (500+ lines) where local state changes cause unrelated subtree re-renders
+- Derived data using useState + useEffect instead of useMemo
+
+## Frontend Data Fetching
+
+- List API using getAll without pagination — should use backend pagination
+- Multiple independent requests using serial await — should Promise.all
+- Polling (setInterval + async) without request lock — next request shouldn't fire before previous completes
+- Missing request cancellation on component unmount or parameter change
+
+## Frontend Memory
+
+By frequency of occurrence, focus on top three:
+- setTimeout/setInterval without cleanup in useEffect return
+- addEventListener without matching removeEventListener
+- subscribe without unsubscribe
+
+## Frontend Loading
+
+- Routes not using React.lazy — synchronous import of all pages impacts initial load
+- Large third-party libraries (ECharts, jsPDF, etc.) not dynamically imported
+- Importing from barrel files (index.ts) — import directly from source for tree-shaking
+- **Google Fonts / external CDN must not appear in entry resources**:
+  - Search `index.html` and CSS files (especially `tailwind-theme.css`) for: `fonts.googleapis.com`, `fonts.gstatic.com`, `cdn.jsdelivr.net`, `unpkg.com`, `cdnjs.cloudflare.com`
+  - **Must fix**: delete the `@import url(...)` line in CSS and the `<link rel="preconnect">` / `<link href="...">` tags in HTML; fall back to the system font stack.
+
+## P1 · Data Access Performance
+
+**Core issue**: N+1 queries in loops, findAll without limit.
+
+```typescript
+// BAD: N+1 — 100 orders → 100 queries
+for (const order of orders) { const user = await User.findById(order.userId); }
+// GOOD: batch query + in-memory join
+const users = await User.findAll({ where: { id: userIds } });
+const userMap = new Map(users.map(u => [u.id, u]));
+```
+
+**Checklist**:
+- N+1 queries: per-item DB calls inside loops — use batch or JOIN
+- List endpoints without pagination — will break as data grows
+- OFFSET pagination on large datasets — use cursor pagination (WHERE id > cursor)
+- Multiple independent DB queries running serially — use Promise.all
+- External API calls without timeout
+- WHERE/ORDER BY columns missing indexes — **cross-check with schema definition: for every ORDER BY or WHERE column in service queries, verify a matching index exists in schema.ts**
+- Aggregation done in JS instead of SQL layer — fetch all rows then compute in app is a common anti-pattern
+- **Sorting fields used in list/ranking endpoints must have database indexes — read schema.ts and verify**
+- **Date-range loop expansion in JS (CRITICAL)**: code shaped like `for (let d = new Date(start); d <= end; d.setDate(d.getDate()+1)) for (item of items) ...` is O(N×days). For 1000 records over 90 days = 90,000 ops per request. Must be pushed to SQL using `generate_series(start, end, '1 day') + unnest(array_field) + GROUP BY ... HAVING COUNT(*) > N` — let the database do the date×row cross product
+- **Multiple endpoints sharing the same base data should be merged**: e.g. Dashboard frontend calling 4 separate stats endpoints, each internally re-querying the full teacher table to build a lookup map. Merge into a single overview endpoint that runs the 4 stats in parallel internally and shares one base-data query.
+- **Stats / Dashboard endpoints must have a default time window**: any query that scans the entire fact table for aggregation (`select ... from coursePlan` with no `where`) will degrade as data grows. Add a default `where startDate >= now() - interval '90 day'` (or business-appropriate window) so it can hit `idx_*_start_date`. Without a time window, even with indexes the planner may still seq-scan. If "all history" is required, use a materialized view or pre-aggregated table refreshed on schedule, never a live full-table scan.
+
+| Scenario | Severity |
+|----------|----------|
+| findAll without limit | CRITICAL |
+| N+1 queries | HIGH |
+
+## P2 · Memory Usage
+
+**Core issue**: Large file readFileSync into memory, module-level Map growing without bound.
+
+**Checklist**:
+- Large files must use streams, not readFileSync
+- Module-level collections must have size limits or LRU eviction
+- Must not accumulate full datasets in memory
+
+| Scenario | Severity |
+|----------|----------|
+| readFileSync on user uploads / Map without limit | HIGH |
+
+## P3 · Algorithm Complexity
+
+**Core issue**: Nested loop O(n²) should use Set/Map index; hot-path JSON.parse(JSON.stringify) deep clone.
+
+```typescript
+// BAD: O(n²) nested lookup
+for (const order of orders) {
+  const user = users.find(u => u.id === order.userId); // linear scan per order
+}
+// GOOD: pre-build index
+const userMap = new Map(users.map(u => [u.id, u]));
+for (const order of orders) {
+  const user = userMap.get(order.userId); // O(1) lookup
+}
+```
+
+**Checklist**:
+- No nested loops with linear lookup (O(n²)) — pre-build Map/Set index
+- No unnecessary sort or deep clone on hot paths
+- No ReDoS-vulnerable regular expressions
+
+| Scenario | Severity |
+|----------|----------|
+| O(n²) nested loops / ReDoS | HIGH |
+| Hot-path deep clone | MEDIUM |
+
+## P4 · Concurrency & Backpressure
+
+**Core issue**: Unbounded Promise.all overwhelming downstream; Stream without backpressure handling.
+
+**Checklist**:
+- Large array Promise.all must have concurrency limit (p-limit or chunked batches)
+- Stream pipelines must handle backpressure (use pipeline)
+- Batch operations must be chunked
+
+| Scenario | Severity |
+|----------|----------|
+| Unbounded Promise.all | HIGH |
+| Stream without backpressure | MEDIUM |
+
+## Q1 · Anti-pattern Detection
+
+**Checklist**:
+- No overly long functions (> 60 lines)
+- No deep nesting (> 4 levels)
+- No magic numbers
+- No duplicated code blocks (3+ times)
+
+| Scenario | Severity |
+|----------|----------|
+| Overly long functions / deep nesting | MEDIUM |
+| Magic numbers | LOW |
+
+## On-demand References
+
+For business-type-specific checks (e-commerce, payment, lottery, etc.), see `references/business-analyzer.md`.

package/miaoda/performance-review/references/business-analyzer.md

@@ -0,0 +1,139 @@
+# Business Analyzer — 业务特性分析参考
+
+> 本文件由主 Skill Stage 1 引用。定义了业务类型识别规则和业务特性检查点映射。
+
+---
+
+## 业务类型识别规则
+
+### 1. 依赖特征映射
+
+通过 package.json 中的依赖组合来推断业务类型。不要只看单个依赖，要看组合：
+
+| 依赖组合 | 推断业务类型 | 置信度 |
+|----------|-------------|--------|
+| stripe/paypal + cart/order 路由 | 电商系统 | 高 |
+| stripe/paypal（无 cart 路由） | 支付/订阅系统 | 中 |
+| socket.io/ws + message/chat 路由 | 即时通讯 | 高 |
+| next + prisma + 大量 CRUD 路由 | CMS / 内容管理 | 中 |
+| bull/bullmq + 任务相关模型 | 任务队列系统 | 中 |
+| multer/sharp + upload 路由 | 文件/媒体管理 | 中 |
+| cron/node-cron + 无前端路由 | 后台定时任务 | 中 |
+
+如果依赖组合无法明确判定，结合路由端点和数据模型综合判断。
+
+### 2. 路由模式识别
+
+```bash
+# 执行这些命令来识别路由模式
+grep -rn "\.get\|\.post\|\.put\|\.delete\|router\." --include="*.ts" --include="*.js" <repoPath>/src/ | head -150
+```
+
+关键路由关键词与业务类型映射：
+
+| 路由关键词 | 业务类型 |
+|-----------|---------|
+| `/product` `/cart` `/order` `/inventory` `/catalog` | 电商 |
+| `/lottery` `/draw` `/prize` `/raffle` `/spin` | 抽奖/活动 |
+| `/pay` `/checkout` `/subscription` `/invoice` `/billing` | 支付 |
+| `/chat` `/message` `/conversation` `/room` `/channel` | 即时通讯 |
+| `/post` `/article` `/page` `/content` `/blog` | CMS/内容管理 |
+| `/task` `/job` `/queue` `/worker` | 任务系统 |
+| `/upload` `/media` `/file` `/image` `/asset` | 文件管理 |
+| `/admin` `/dashboard` `/analytics` `/report` | 后台管理 |
+| `/auth` `/login` `/register` `/user` `/profile` | 用户系统（通常是子模块） |
+
+### 3. 数据模型辅助判定
+
+模型名称是强信号：
+
+| 模型名称 | 指向 |
+|---------|------|
+| Product, Category, Cart, CartItem, Order, OrderItem | 电商 |
+| Prize, LotteryRecord, DrawResult, Winner | 抽奖 |
+| Payment, Transaction, Subscription, Invoice | 支付 |
+| Message, Conversation, ChatRoom, Participant | 即时通讯 |
+| Post, Article, Page, Comment, Tag | CMS |
+
+---
+
+## 业务特性检查点清单
+
+识别出业务类型后，根据以下映射生成检查点。每个检查点有唯一 ID、名称、描述、严重等级和具体检查方法。
+
+### 电商系统检查点
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-EC-001 | 超卖防护 | CRITICAL | 查找库存扣减逻辑，确认是否使用原子操作（如 `UPDATE ... SET stock = stock - 1 WHERE stock > 0`）或 ORM 的 `increment/decrement`。如果是先 `findOne` 再 `save`，且无 `version` 字段或 `FOR UPDATE` 锁，则判定为风险 |
+| BIZ-EC-002 | 订单状态机完整性 | HIGH | 检查订单是否有明确的状态流转（pending→paid→shipped→completed），是否有非法状态跳转的防护 |
+| BIZ-EC-003 | 价格篡改防护 | CRITICAL | 检查下单时价格是否从服务端重新查询，而非信任前端传入的价格 |
+| BIZ-EC-004 | 库存回滚 | HIGH | 支付失败或订单取消时，库存是否有回滚机制 |
+
+### 支付系统检查点
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-PAY-001 | 支付幂等性 | CRITICAL | 在支付创建的 handler 中查找 idempotencyKey / requestId / 幂等标识。Stripe 调用检查是否传了 `idempotencyKey` 参数 |
+| BIZ-PAY-002 | 金额精度 | HIGH | 检查金额计算是否使用整数（分为单位）或 Decimal 库，而非浮点数运算 |
+| BIZ-PAY-003 | Webhook 签名验证 | CRITICAL | 支付回调（如 Stripe webhook）是否验证签名（`stripe.webhooks.constructEvent`），防止伪造回调 |
+| BIZ-PAY-004 | 敏感信息脱敏 | HIGH | 支付相关日志中是否泄露完整卡号、CVV 等信息 |
+
+### 抽奖/活动系统检查点
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-LT-001 | 随机算法安全性 | CRITICAL | 查找抽奖核心逻辑中的随机函数。如果使用 `Math.random()`，判定为 CRITICAL（应使用 `crypto.randomInt()` 或 `crypto.randomBytes()`） |
+| BIZ-LT-002 | 抽奖频率限制 | HIGH | 检查抽奖接口是否有频率限制（rate limiter），防止脚本刷奖 |
+| BIZ-LT-003 | 概率配置可审计 | HIGH | 奖品概率是否有配置化管理和修改日志，而非硬编码 |
+| BIZ-LT-004 | 奖品库存原子扣减 | CRITICAL | 奖品发放是否有库存扣减的原子保障（与超卖防护同理） |
+| BIZ-LT-005 | 抽奖审计日志 | HIGH | 每次抽奖结果是否记录包含 userId、timestamp、奖品、随机种子的审计日志 |
+
+### 即时通讯系统检查点
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-IM-001 | WebSocket 连接数限制 | HIGH | 检查是否限制单用户最大连接数，防止资源耗尽 |
+| BIZ-IM-002 | 心跳与死连接清理 | HIGH | 是否有 ping/pong 心跳机制，是否定时清理未响应连接 |
+| BIZ-IM-003 | 消息大小限制 | MEDIUM | 是否限制单条消息体积（`maxPayload`），防止大消息攻击 |
+| BIZ-IM-004 | 消息持久化 | MEDIUM | 离线消息是否有持久化和补推机制 |
+
+### 高流量场景检查点（适用于所有高并发业务）
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-HT-001 | 连接池配置 | CRITICAL | 数据库连接池是否有显式配置（非默认值）。对于 Prisma 检查 `connection_limit`，对于原生驱动检查 `max` 参数 |
+| BIZ-HT-002 | API 限流 | HIGH | 是否有全局或关键路由级别的 rate limiter（express-rate-limit / 自定义中间件） |
+| BIZ-HT-003 | 缓存 TTL | HIGH | Redis/缓存的 SET 操作是否都设置了过期时间，避免缓存永不失效 |
+| BIZ-HT-004 | 缓存穿透防护 | MEDIUM | 不存在的 key 是否有空值缓存或布隆过滤器防护 |
+
+### 高并发读写检查点
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-CR-001 | 乐观锁/悲观锁 | CRITICAL | 涉及读-修改-写模式的操作（如余额变更、库存扣减）是否有版本号或行锁保护。查找 `findOne` 后紧跟 `save/update` 且无 `version`/`@Version`/`FOR UPDATE` 的模式 |
+| BIZ-CR-002 | 原子操作 | CRITICAL | 数值增减（如 `count += 1` 后 `save()`）是否使用 DB 原子操作（`increment`/`decrement`/`UPDATE SET x = x + 1`） |
+| BIZ-CR-003 | 分布式锁 | HIGH | 跨进程的关键操作是否有分布式锁（如 Redis `SETNX`） |
+
+---
+
+## 扩展口设计
+
+业务检查点是可扩展的。将来新增业务类型时，按以下格式追加到上面的清单中：
+
+```markdown
+### [新业务类型] 检查点
+
+| ID | 检查点 | 严重等级 | 检查方法 |
+|----|--------|---------|---------|
+| BIZ-XX-001 | [检查点名称] | [CRITICAL/HIGH/MEDIUM/LOW] | [具体检查方法描述] |
+```
+
+ID 命名规则：`BIZ-{业务缩写}-{三位序号}`
+
+预留的业务类型（暂未定义检查点，待后续补充）：
+- 金融合规（BIZ-FIN-*）
+- GDPR 数据合规（BIZ-GDPR-*）
+- 多租户隔离（BIZ-MT-*）
+- 搜索引擎（BIZ-SE-*）
+- IoT 数据采集（BIZ-IOT-*）