draftgo-cli 3.0.1 → 3.0.29

package/README.md

@@ -11,9 +11,9 @@
 
 ## DraftGo Next v3 基线
 
-DraftGo Next 前端基线为 React + Vite + shadcn/ui + Tailwind。draftgo-cli v3 的定位是 DraftGo 工作台 CLI：负责本地运行环境、资源同步、开发检查、push/pull 闭环和 AI 工具 skill 分发。
+DraftGo Next 前端基线为 React + Vite。draftgo-cli v3 的定位是 DraftGo 工作台 CLI：负责本地运行环境、资源同步、开发检查、push/pull 闭环和 AI 工具 skill 分发。
 
-数据库页面仍以 HTML 为核心，`dg-*` 标签是 shadcn/ui 在 DraftGo 页面运行时里的协议表达：AI 看到 `dg-button`、`dg-card`、`dg-form`、`dg-table` 等，必须理解为 shadcn 组件能力，而不是 daisyUI、Bootstrap 或自研组件库。CLI 分发的 skill 已把这条规则写入前端规范。
+数据库页面以 HTML 为核心，默认使用 Tailwind CSS 和页面级 CSS。
 
 已存在的 `draftgo init/update/status/doctor/map/check/connect/local-dev` 保持兼容；首批工作台命令如下：
 
@@ -25,9 +25,12 @@ DraftGo Next 前端基线为 React + Vite + shadcn/ui + Tailwind。draftgo-cli v
 | `draftgo local status` | 查看本地栈容器状态。 |
 | `draftgo dev` | 运行当前项目 `package.json` 中的 `scripts.dev`。 |
 | `draftgo build` | 运行当前项目 `package.json` 中的 `scripts.build`。 |
-| `draftgo check` | 本地资源闭环检查，辅助发现入口绑定、缺文件、重复路由和疑似 mock 风险。 |
+| `draftgo check` | 本地资源闭环检查，辅助发现入口绑定、缺文件、重复路由、疑似 mock 与颜色/主题风险。 |
+| `draftgo verify-ui <url>` | 使用 Playwright 执行单视口 UI smoke check；默认按 Git 变更判断，失败时才截图。 |
+| `draftgo api <keyword>` | 结构化检索内置 OpenAPI，无需让 AI 读取完整规范文件。 |
 | `draftgo pull` | 包装随 skill 分发的 `draftgo_pull.py`，默认 `--all` 拉取资源。 |
 | `draftgo push` | 包装随 skill 分发的 `draftgo_push.py`，推送页面、导航、DB meta 等资源。 |
+| `draftgo deploy` | 显式执行 check → push；支持 `--delivery local|preview|deploy`。 |
 
 ## 安装
 
@@ -55,12 +58,16 @@ draftgo init all                         # 所有支持的工具
 | 命令 | 说明 |
 |---|---|
 | `draftgo init [target]...` | 安装 skill。不传 target 时自动识别；`all` 表示全部。 |
-| `draftgo update [target]...` | 把 CLI 内置 skill 覆盖写到每个已安装或项目中检测到的 AI 工具自己的 skill 目录；保留本地 `config / changelog / lessons / Task` 等运行时数据。**若 npm 上存在更新的 CLI 版本，会先自动升级 CLI 再重跑自己**。 |
+| `draftgo update [target]...` | 把当前 CLI 内置 skill 原子更新到已安装或检测到的 AI 工具目录；发现新版时只提示，不自动修改全局 CLI。 |
+| `draftgo upgrade` | 显式执行全局 CLI 升级，然后使用新版刷新 skill。 |
 | `draftgo uninstall [target]...` | 移除指定 AI 工具的 skill 目录（含入口文件 + 子技能 + scripts）。加 `--purge` 会连 `.draftgo/` 一起删。 |
 | `draftgo status` | 查看当前项目装了哪些 AI 工具入口、skill 版本。 |
 | `draftgo doctor` | 诊断：Python 是否可用、检测到哪些 AI 工具、各入口状态。 |
-| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、外部 API、文档、系统配置、入口引用，帮助 AI 快速进入项目。 |
+| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、文档、系统配置、入口引用，帮助 AI 快速进入项目。 |
 | `draftgo check` | 本地闭环体检：检查 route、入口绑定、文件存在性、重复路由和疑似 mock/伪功能风险。 |
+| `draftgo verify-ui <url>` | 浏览器 smoke check；支持 `--mobile-check auto|always|never` 和失败截图。 |
+| `draftgo api <keyword>` | 查询内置 OpenAPI 端点。 |
+| `draftgo deploy [type] [id...]` | 显式交付；`local` 只检查，`preview` dry-run，`deploy` 推送。 |
 | `draftgo list-targets` | 列出支持的 AI 工具名。 |
 | `draftgo --version` | 打印 CLI 版本。 |
 | `draftgo --help` | 查看帮助。 |
@@ -73,20 +80,23 @@ draftgo init all                         # 所有支持的工具
 - `--purge`：`uninstall` 时连 `.draftgo/`（含 config / 日志 / 本地缓存）一起删。
 - `--output json`：`map/check` 输出机器可读 JSON。
 - `--strict`：`check` 将提醒项也视为失败。
+- `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行，默认 `auto`。
+- `--screenshot on-failure|always|never`：控制 UI 截图，默认仅失败时生成。
+- `--delivery local|preview|deploy`：控制 `deploy` 的交付级别。
 
-可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭自动升级检查（离线、CI 等场景）。
+版本查询结果缓存 24 小时。可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭版本检查（离线、CI 等场景）。
 
 ### 机器可读输出
 
-`draftgo map --output json` 会输出本地资源地图，适合 Agent 在开发前快速读取上下文；覆盖 pages、navigations、db_meta、custom_scripts、aihub、external_apis、docs、doc_categories、system_config、roles 和入口引用。AIHub 条目会包含常用配置摘要：
+`draftgo map --output json` 会输出本地资源地图，适合 Agent 在开发前快速读取上下文；覆盖 pages、navigations、db_meta、custom_scripts、aihub、docs、doc_categories、system_config、roles 和入口引用。AIHub 条目会包含常用配置摘要：
 
 - `type=model`：模型数量、`supports_response_format`、`supports_json_schema`、图片生成诊断摘要。
 - `type=agent`：`mode`、主模型/备用模型、`output_format`、用户选模型配置、工具来源摘要。
 - `type=mcp`：传输协议、已发现工具数量。
 
-外部 API 会摘要 `code/method/path/base_url/tags/status`，文档会摘要 `slug/category/content_file/status`，系统配置只展示 `config_key/category/value_type/is_sensitive/status`，避免把敏感值直接暴露给 Agent 输出。
+文档会摘要 `slug/category/content_file/status`，系统配置只展示 `config_key/category/value_type/is_sensitive/status`，避免把敏感值直接暴露给 Agent 输出。
 
-`draftgo check --output json` 会输出 `{ map, errors, warnings }`，适合 CI 或开发收尾时作为轻量证据。`--strict` 会把 warnings 也视为失败。
+`draftgo check --output json` 会输出 `{ map, errors, warnings, warningDetails }`，其中 `warningDetails` 带规则编号与置信度。`--strict` 会把 warnings 也视为失败。检查会提示明显的硬编码配色风险，要求优先使用系统 `var(--dg-*)` token；自主配色需同时兼容浅色与深色主题。
 
 ## 更新
 
@@ -95,10 +105,16 @@ cd <your-project>
 draftgo update
 ```
 
-就这一条命令。`update` 会自己去 npm 查最新版：
+`update` 会用当前版本刷新 skill，并查询 npm 最新版：
 
-- 如果 CLI 已是最新 → 直接把内置 skill 资源覆盖到每个已安装 AI 工具的 skill 目录
-- 如果 CLI 过时 → 自动执行 `npm install -g draftgo-cli@latest`，然后用新 CLI 重跑一遍 `update`
+- 如果 CLI 已是最新 → 原子替换每个目标的 skill 资源
+- 如果 CLI 过时 → 提示运行 `draftgo upgrade`，本次仍使用当前版本完成刷新
+
+需要升级 CLI 时显式运行：
+
+```bash
+draftgo upgrade
+```
 
 整个过程中，你本地的 `.draftgo/config.json`、`changelog.md`、`lessons/`、`Task/` 等运行时数据都不会被动到。
 
@@ -109,14 +125,31 @@ CLI 随包分发的 DraftGo skill 会同步基座 API 约定。集合写入统
 - 创建：`POST /api/<resource>` 支持单个对象或对象数组。
 - 批量更新：`PATCH /api/<resource>/batch`，请求体为带 `id` 的对象数组。
 - 动态 DB 因为资源带 `type`，批量更新路径是 `PATCH /api/db/{type}/batch`。
+- GET 列表请求不传 `page` / `page_size` 时全量返回且无数量上限；任一分页参数传入时正常分页，缺失项按 `page=1` / `page_size=20` 兜底。
 
 前端资源约定：
 
 - DraftGo 基座内置 SVG 图标库，运行时路径为 `/assets/icons/{name}.svg`。
 - 图标文件统一使用 `kebab-case.svg` 命名；完整映射见 `/assets/icons/manifest.json`。
 - 页面或导航栏需要单色图标时，优先用 CSS mask + `currentColor`，可自动适配深浅主题。
+- html2canvas 1.4.1 已内置，页面需要截图 / 导出图片时优先使用本地路径 `/assets/vendor/html2canvas/html2canvas.min.js`；确需 CDN 时优先使用国内镜像引入。
 
-动态 DB SDK 也提供 `sdk.db.create_many(...)` 与 `sdk.db.update_many(...)`，用于脚本内批量写入。
+Go 自定义服务通过 `ctx.DB.CreateMany(...)` 与 `ctx.DB.UpdateMany(...)` 批量写入动态数据。
+
+自定义服务（Custom Scripts）约定：
+
+- 自定义服务使用 Go：导入内置 `draftgo/sdk`，实现 `Register(app *sdk.App)`，调用 `app.Route`、`app.On` 或 `app.Schedule` 后即可自动注册。服务在独立 Go 子进程中构建和执行；标准库与 `go.mod` 中声明的兼容依赖可用。
+- 本地资源在 `.draftgo/custom_scripts/`；元数据写在 `index.json`，代码文件以每条记录的 `code_file` 为准。推送时 `draftgo_push.py custom_scripts` 只读取 `code_file` 指向的文件。
+- 新服务使用 `mode=mixed`，`Register` 内的 `app.Route`、`app.On`、`app.Schedule` 会自动形成完整触发器清单；旧 `triggers` 字段不参与 Go 注册。
+- `slug=<slug>` 是服务命名空间；`app.Route("GET", "/items", handler)` 映射为 `GET /api/x/<slug>/items`。一个服务可同时注册多个路由、事件和定时任务。
+- Go handler 签名为 `func handler(ctx *sdk.Context) (any, error)`；普通值直接返回，需要状态码或响应头时使用 `ctx.Respond(...)`。
+- 第三方依赖写在同一条 index 元数据的 `go_mod` / `go_sum`；推送后应真实请求无副作用 GET 端点验证，不要只看 `OK script_id=...`。
+- `app.On("user.registered", handler)` 可重复声明；同一服务既能监听多个事件，也能为同一事件注册多个 handler。
+- Route 输入在 `ctx.Input`（`body`、`query_params`、`headers`、`method`、`path_params`）；当前用户用 `ctx.Auth.CurrentUser()` 获取。普通值可直接返回，需要状态码或响应头时用 `ctx.Respond(...)`。
+- 动态数据使用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；完整 Go SDK 见 `specs/custom-services.md`。
+- 管理面按 `scripts:read/create/update/delete/execute` 接入角色 RBAC；获得创建/编辑权限的用户属于可信代码编辑者。调用面仍由每个 route 的 `permission` 与 `config.route_security` 独立控制，管理权限不会绕过调用权限。
+- 服务可用 `config.max_concurrency` / `queue_timeout_ms` 设置并发退避；出站请求使用 `ctx.HTTP`，饱和 Route 返回 HTTP 429。
+- 完整 SDK（users/db/auth/notify/http/cache/config/aihub/log）、各触发类型 ctx、管理 API 和部署限制见 [`resources/skill/specs/custom-services.md`](resources/skill/specs/custom-services.md)。
 
 AIHub Agent 用户选模型约定：
 
@@ -178,7 +211,7 @@ AIHub Agent JSON 输出约定：
 
 ## 产物结构
 
-每个 AI 工具拿到的是**完整自包含**的 skill 副本（SKILL.md + 子技能 + rules + scripts），写入它自己的目录。`.draftgo/` 只放运行时数据。
+每个 AI 工具拿到完整的核心说明（SKILL.md + 子技能 + rules + scripts）。大型 OpenAPI 快照只在 `.draftgo/skill-shared/` 保存一份，避免多个工具重复复制；也可直接用 `draftgo api <keyword>` 查询。
 
 ```
 <project>/
@@ -189,6 +222,7 @@ AIHub Agent JSON 输出约定：
 │   ├── Task/                         # 每个开发任务一个 md，含需求 / 设计 / 任务标记
 │   ├── lessons/                      # 开发经验、踩坑记录、基座局限场景
 │   ├── pages/  navigations/  ...     # init 拉取的本地缓存
+│   ├── skill-shared/quickref/api.json # 多 AI 工具共享的 OpenAPI 快照
 │   └── .version                      # CLI 写入：当前已装 skill 的版本
 │
 └── (AI 工具 skill 目录，按需写入；每份都是完整副本)
@@ -202,10 +236,26 @@ AIHub Agent JSON 输出约定：
     .github/prompts/draftgo.prompt.md     +  .github/prompts/draftgo/{...}
 ```
 
+`config.json` 的 `auto_push` 默认是 `false`。AI 在每次完成本地验证后调用 `draftgo auto-push`；仅当你将该值改为 `true` 时，命令才会继续执行 `check → push`。直接执行 `draftgo push` 或 `draftgo deploy` 仍属于显式推送，不受此开关限制。
+
 > 渲染时 SKILL.md 中的 `{{SKILL_DIR}}` / `{{SKILL_SCRIPTS}}` 会被替换成当前 AI 工具自身的目录，确保子技能、rules、scripts 引用永远指向同一个工具的副本。CLI **不会** 改写你的 `AGENTS.md` / `GEMINI.md`。
 
 ---
 
+## v3.0.28 升级要点（同步可靠性）
+
+- 修复导航 pull：列表元数据会逐条获取详情 HTML，避免空内容覆盖本地导航。
+- 指定 ID 的 pull 改为合并索引；请求失败、详情缺失或响应不完整时返回非零，保留本地缓存。
+- `draftgo push` 支持默认全量推送；`deploy --delivery preview` 使用无副作用的 dry-run 预览。
+
+## v3.0.27 升级要点（自动推送与索引恢复）
+
+- 新增 `draftgo auto-push`：始终先运行本地 `check`，仅在 `.draftgo/config.json` 的 `auto_push: true` 时继续推送；关闭时保留验证并返回未推送信息。
+- 支持 `draftgo auto-push --batch`，并行任务也受同一开关约束。
+- 指定资源缺少 `index.json` 条目时，push 会回读云端；资源存在则补齐元数据并继续推送本地文件，资源不存在则提示清理本地孤儿文件。
+
+---
+
 ## v1.2.0 升级要点（高质量开发规范）
 
 CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/dev-workflow.md`），目标是让 AI 在做 DraftGo 项目开发时"小修不拖慢、功能有计划、高风险有门禁、质量靠证据"。
@@ -216,7 +266,7 @@ CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/
 小修：直接定位 → 改 → 轻量证据
 轻功能：范围复述 → 直接做 → 凭证据闭环
 标准功能：轻量确认 → 内部短计划 → 执行闭环
-高风险：完整 Story / 计划 / 验证 / 人工确认
+高风险：完整 Story / 计划 / 验证 / 回读证据
 ```
 
 **新增本地目录**：
@@ -226,7 +276,7 @@ CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/
 - `.draftgo/lessons/` 统一记录开发过程中的阻碍、踩坑、框架运行时问题、基座能力局限和可复用经验。
 - 文件按 `YYYY-MM-DD-主题关键词.md` 命名，便于后续回顾和沉淀为开发规范。
 
-**前端 UI 能力调用**：DraftGo 平台前端默认采用 React + shadcn/ui + Tailwind CSS；数据库 HTML 页面使用 `dg-*` 表达 shadcn 组件能力，`dg-*` 不是自研 UI 协议。若本地 Agent 环境存在 shadcn / 前端 UI 相关 Skills，前端界面开发时优先调用。DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法，并在规范中声明 shadcn/Tailwind 已引入。
+**前端 UI 能力**：DraftGo 平台前端默认采用 React + Tailwind CSS。若本地 Agent 环境存在前端 UI 相关 Skills，前端界面开发时优先调用。DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法。
 
 完整规范见各 AI 工具自身 skill 目录下的 `rules/dev-workflow.md`，例如 `.claude/skills/draftgo/rules/dev-workflow.md`。
 
@@ -399,7 +449,7 @@ now:
 小修：直接定位 → 改 → 轻量证据
 轻功能：范围复述 → 直接做 → 凭证据闭环
 标准功能：轻量确认 → 内部短计划 → 执行闭环
-高风险：Story → 完整确认 → 计划 → 人工确认 / 回读验证
+高风险：Story → 完整确认 → 计划 → 回读验证 / 影响说明
 ```
 
 **注意：** `.draftgo/story.yaml` 不在 `draftgo init` 中创建。它由 AI 在首次开发对话时通过与开发者交流后生成，确保内容有意义而不是空模板。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.1",
+  "version": "3.0.29",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"
@@ -28,11 +28,7 @@
     "gemini",
     "kiro"
   ],
-  "author": {
-    "name": "draftgo",
-    "email": "cabinai@163.com",
-    "url": "https://github.com/draftgo"
-  },
+  "author": "draftgo <cabinai@163.com> (https://github.com/draftgo)",
   "license": "MIT",
   "homepage": "https://github.com/draftgo/draftgo-cli#readme",
   "bugs": {
@@ -43,6 +39,15 @@
     "url": "git+https://github.com/draftgo/draftgo-cli.git"
   },
   "scripts": {
-    "test": "node tests/unit.js"
-  }
+    "test": "node tests/unit.js && node tests/e2e.js",
+    "test:e2e": "node tests/e2e.js"
+  },
+  "dependencies": {
+    "parse5": "6.0.1",
+    "playwright-core": "1.61.1"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "devDependencies": {}
 }

package/resources/skill/SKILL.md

@@ -1,12 +1,40 @@
----
+---
 name: draftgo
 description: Use this skill when the user is developing, maintaining, or debugging a DraftGo-based application. Activates for tasks involving DraftGo pages, navigation, API calls, roles, DB meta, or any DraftGo-specific development work. ALSO activates when user says "推送", "push", "同步", "sync", "推送到云端", "同步到云端", "push to server", "上传页面", "上传导航", "push pages", "push nav", "push db_meta" — route to /draftgo push skill immediately, do NOT attempt manual API calls.
-version: 2.0.0
 ---
 
 # DraftGo 开发助手
 
-> 默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。优先交付真实落地闭环；禁止假数据/静态卡片/伪功能充当完成。若本地 Agent 存在前端 UI Skills，前端开发时优先调用。
+> 默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。优先交付真实落地闭环；禁止假数据/静态卡片/伪功能充当完成；禁止用很大的 `page_size` 冒充全量获取；设计页面开发，强制先读取rules/frontend.md。
+
+## ⚠️ 高权重硬规则：禁止“假获取”/伪全量分页
+
+DraftGo 列表接口的分页语义是硬约定：**只有同时不传 `page` 和 `page_size` 才是全量返回**。只要传了 `page` 或 `page_size` 任意一个参数，就进入分页模式。
+
+- 需要完整候选集、完整配置、完整权限/角色、完整页面/导航、完整文档树、完整 AIHub 资产、完整 DB meta、完整导出/同步数据时，必须不传 `page` / `page_size`。
+- 严禁写 `{ page: 1, page_size: 500 }`、`{ page_size: 9999 }`、`?page_size=500` 这类“拿大页当全量”的假获取。数据量超过上限时一定会漏数据。
+- 只有真实的分页表格、日志列表、搜索结果页、预览卡片、首页公告等明确限量场景，才允许显式传 `page` + `page_size` 或业务 `limit`。
+- 如果既需要全量又担心数据量太大，应改成后端聚合/专门端点/逐页循环并校验 `total`，不要假装一次大分页就是全量。
+- Go 自定义服务通过 `ctx.DB.Query(type, sdk.QueryOptions{...})` 访问动态数据；完整筛选和分页契约见 `specs/custom-services.md`。
+
+## ⚠️ 高权重硬规则：日期/时间分层处理
+
+任何涉及日期、时间、日历、排期、统计区间、日志时间、倒计时、到期时间、创建/更新时间展示或计算的页面、后端、自定义脚本、定时任务和文案生成，必须区分展示层与存储/业务层，避免不同时区用户看到或写入错误日期。
+
+- **展示层按用户时区显示**：面向终端用户展示 `datetime` 时，优先使用用户个人时区/浏览器时区；如果产品要求统一展示平台时间，必须在文案中标明时区。不要硬编码 `Asia/Shanghai` 或默认 UTC 直接展示给全球用户。
+- **存储层和业务规则按系统时区处理**：系统时区配置键为 `system_timezone`，运行时后端以该配置为准；未配置时才回退 `APP_TIMEZONE` / `TZ` / 默认时区。写入、统计、定时任务、账期、活动边界、自然日归属等业务规则优先按系统时区计算。
+- 生成“今天/昨天/本周/本月/到期日/开始结束日期”等相对日期时，必须先判断语义：用户视角的显示用用户时区，平台/业务视角的存储、筛选和统计用系统时区，避免跨时区导致日期早一天或晚一天。
+- 写入或查询 `date` / `datetime` 字段、构造 filters 范围、统计自然日区间时，边界必须按系统时区计算；不要用 UTC 零点、浏览器零点或本机时区零点直接当业务日期边界。
+- 后端代码优先复用统一时区工具；自定义服务和页面脚本若需要当前业务时间，也必须显式考虑系统时区，不要裸用 `new Date()` / `datetime.utcnow()` 作为业务日期依据。
+
+## ⚠️ 使用此 Skill 前必读
+
+1. **每次激活都先完整读此文件（SKILL.md）**。这里承载高频、高代价和跨任务的核心规则，不能只读摘要或凭记忆执行
+2. 根据任务场景查"快速决策树"，找到需要读的文件
+3. 不要凭记忆猜测语法，**遇到陌生 API 必读对应 spec**
+4. 涉及 filters/order_by 查询时，必须先读 `specs/data.md` 的操作符表
+5. 涉及页面、导航、管理端、DB、custom_script、AIHub 时，优先先读对应规则文档，再开始实现；已明确的小修可只读最小必要部分
+
 
 ## 开发前置检查
 
@@ -33,24 +61,61 @@ test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
 
 **第一步：必读** → `{{SKILL_DIR}}/rules/dev-workflow.md`（分级：小修 / 轻功能 / 标准功能 / 高风险）
 
+**页面/业务任务额外默认动作：**
+- 做顶部导航前，通常先读 `.draftgo/navigations/index.json` 与现有导航 HTML；需要新导航时优先复制/复刻一份内置导航再改造，而不是直接破坏内置导航
+- 做导航栏时，通常同时考虑未登录/已登录/管理员三种状态，以及移动端或窄屏下的收起/展开体验；普通用户不显示管理后台入口，管理员额外显示
+- 做管理端侧边栏前，通常先读现有管理侧导航 HTML；业务管理路由优先追加到对应业务域，系统内置路由优先保留，除非用户明确要求且已确认影响范围
+- 做业务模块前，先判断是否需要管理端页面、角色路径地图和同一份真实数据；简单纯展示场景可明确降级
+- 做运营管理功能时，通常按业务域提供专门后台页面并注册到后台侧边栏；`/admin/db` 保留为底层通用数据能力，不默认承担日常运营页面
+- 做新系统 / 新板块 / 新模块前，通常先在 `.draftgo/Task/` 产出轻量 PRD，清点页面清单、功能清单、数据、入口和管理端，再继续开发
+- 修改系统内置页面前，先确认是否真的必要；非必要不触碰系统页，确需修改时说明原因和影响
+- 做首页时，通常按官网介绍、品牌门面和业务入口设计；只有用户需求或产品定位明确“进入即使用”时，才把首页设计成实际工作台
+- 做弹窗、抽屉、下拉选择器和前端动效时，优先读 `rules/frontend.md` 的交互体验规则：弹窗尽量无外层滚动条；所有可展开选择控件（Select / Dropdown / Combobox / Autocomplete / Cascader 等）禁止使用浏览器或操作系统默认的原生 `<select><option>` 展开菜单样式，必须使用自定义弹层菜单或 Ant Design 等组件库的下拉层，确保选项层、hover、selected、disabled、滚动条、边框、阴影、圆角、字号与页面视觉一致；页面体验可合理植入本地 GSAP
+- **按页面目标和改动影响决定多端适配**：面向公众、用户可能从手机访问、已有响应式断点，或本次修改涉及布局/CSS/导航/弹窗时，应考虑窄屏体验；明确的桌面工作台、仅改文案/数据逻辑、后端或脚本任务，不要机械追加移动端验收。需要浏览器证据时优先运行 `draftgo verify-ui <url> --mobile-check auto`，使用单视口 smoke check，默认仅失败时截图；不要为了收尾默认调用 computer use、手动拖动浏览器或遍历多个视口。详见 `rules/frontend.md §移动端与多端适配`
+
 | 任务类型 | 读取 |
 |---|---|
 | 所有开发任务 | `rules/dev-workflow.md` — 分级与执行流程 |
 | 前端页面开发 | `rules/frontend.md` — 前端规范（小修可只读相关段落） |
 | 页面功能不执行 / 报错 | `rules/debugging-syntax.md` — 排错指南（必读） |
-| 标准功能 / 高风险并行任务 | `rules/parallel.md` — 并行协议 |
+| 标准功能 / 高风险 / 多资源任务 | 先判断是否可并行；可并行时读 `rules/parallel.md` — 并行协议 |
 | 不了解项目结构 | 先运行 `draftgo map` |
 | 标准功能 / 高风险 · 意图模糊 | `practices/dev-declaration.md` — 开发声明协议 |
 
+## 并行开发默认策略
+
+标准功能、高风险、多页面、多资源任务开始后，主代理必须先做一次并行可行性判断：
+
+- 如果存在 2 个及以上无依赖任务，且 `resource_lock` 不冲突，读取 `rules/parallel.md` 并按 wave 并行执行
+- 如果任务共享同一页面、导航、schema、侧边栏或核心入口，先串行完成共享基础，再并行下游任务
+- 主代理负责需求判断、依赖图、资源锁、结果合并、验证和最终 push
+- 子代理只执行单个 Task，只修改声明的 `resource_lock`，不 push、不改 Task 文档、不做范围外优化
+- 并行结束后统一写 changelog、统一检查、统一 batch push
+
+优先并行的 DraftGo 任务：多个独立页面、前台页面与后台管理页面、页面与 custom_script、docs/pages/db_meta 中互不依赖的资源。
+
+禁止或谨慎并行：同一 HTML 文件、同一导航或管理侧边栏、共享 DB schema 未定型前的页面开发、需要统一视觉/交互决策的首屏/首页/核心工作台。
+
 ## 快速决策树
 
 ```
 要开发什么？
 ├── 页面 / 导航 / 交互      → 读 rules/frontend.md
 ├── 数据结构 / 动态 DB      → 读 specs/data.md
+├── 定义关联关系 / 级联删除
+│   → 读 specs/data.md §关联关系（ref）
+│   → 需要完整示例时读 specs/db-relations.md
+├── 数据检索 / 使用 filters / order_by
+│   → 先读 specs/data.md §filters操作符
+│   → 再读 quickref/api-endpoints.md 看接口契约
+├── 关联查询 / populate 填充
+│   → 读 specs/data.md §关联查询（populate）
+├── 自定义服务 / custom_script
+│   → 强制先读 specs/custom-services.md（语言、ctx、SDK、权限、运行限制）
+│   → 推送时再读 push/SKILL.md §推送自定义脚本
+│   → 涉及 ctx.DB.Query / filters 时读 specs/data.md §自定义服务内的 ctx.DB.Query
 ├── API 速查               → quickref/api-endpoints.md
 ├── App 方法忘了            → quickref/app-api.md
-├── dg-* 组件用法           → quickref/dg-components.md
 ├── 了解平台架构            → core/architecture.md
 ├── 选择开发方案            → core/modules.md
 └── 查开发禁区             → specs/security.md
@@ -61,15 +126,37 @@ test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
 - 存储于 `.draftgo/config.json`（已加入 .gitignore）
 - 运行 `/draftgo init` 时写入
 
+## 收尾提醒
+
+开发 / 修改 / 修复后默认先完成本地证据，然后运行 `draftgo auto-push [type] [id...]` 作为收尾门。它始终先执行本地检查：当 `.draftgo/config.json` 的 `auto_push` 为 `true` 时自动执行 `check → push`；未设或为 `false` 时输出“已验证、未推送”的提示，不修改云端。用户明确要求 push/同步/部署时，仍可直接运行 `draftgo deploy` 或对应 push；需要预演时用 `draftgo deploy --delivery preview`。
+
 ## 核心原则（硬性）
 
 - **开发分级**：任何任务先读 `rules/dev-workflow.md` 分级，再执行
 - **真实闭环**：不用假数据/伪交互充当完成；无法实现则停止并说明
+- **禁止伪全量分页**：需要全量数据时不传 `page` / `page_size`；不得用 `{ page: 1, page_size: 500 }`、`?page_size=9999` 等“大分页”假装全量。传任意分页参数都会截断为分页窗口，必须按真实全量、真实分页或逐页拉取处理
+- **日期/时间分层**：展示层面向用户时按用户个人时区/浏览器时区显示；存储层、业务规则、统计区间、定时任务和平台相对日期必须优先使用系统配置 `system_timezone`，避免日期不正确
+- **自定义服务注册闭环**：新 Go 服务实现 `Register(app *sdk.App)`；可混合 `app.Route` / `app.On` / `app.Schedule`。旧 `triggers` 字段不参与注册，route 推送后必须真实请求无副作用的 GET 端点验证不是 404
+- **自定义服务代码契约**：新服务使用 `package main` 与 `func handler(ctx *sdk.Context) (any, error)`；route 身份用 `ctx.Auth.CurrentUser()`，完整契约见 `specs/custom-services.md`
+- **自定义服务权限分层**：管理面按角色 `scripts:*` 权限授权可信编辑者；调用面仍按每个 Route 的 `permission` / `route_security` 判断，任何一层都不能替代另一层
+- **自定义服务执行身份**：Route 默认继承调用者身份；含 `user_id` / `actor_user_id` 的事件继承该用户，定时任务与无可解析用户的事件才以系统身份执行。需要管理员权限时，可信服务代码必须逐次显式调用 `draftgo.Admin.*`；该调用本身就是提升声明，会以管理员身份执行并自动写入执行审计。不得在服务源码、`go_mod`、页面或请求中嵌入 SAT。
+- **导航优先复用**：顶部导航、管理端侧边栏优先复刻/改造现有内置导航资源；仅当现有结构无法承载需求时再调整方案
+- **导航状态完整**：导航通常覆盖未登录/已登录/管理员可见性和收起/展开；普通用户不显示管理后台入口，管理员额外显示后台入口
+- **系统页谨慎修改**：登录、设置、权限、用户、系统配置等内置系统页非必要不改；确需修改时先确认影响范围
+- **业务优先考虑管理端**：案例、新闻、产品、订单、预约、资料等可维护业务内容，优先考虑前台 + 管理端 + 同一份真实数据；若明确不需要，可按更轻路径处理
+- **业务后台专页**：运营日常使用的后台能力优先做业务域管理页并注册后台侧边栏；`/admin/db` 仅作为底层通用数据入口，不默认替代业务管理页
+- **首页定位清晰**：首页通常是官网/产品介绍和入口聚合，不默认当实际工作台；用户进入即使用型产品可例外
 - **入口绑定**：新增页面必须绑定导航/首页/菜单至少一处
-- **dg-* = shadcn**：`dg-*` 是 shadcn 的 HTML 协议表达，不是其他 UI 库
+- **角色路径闭环**：标准功能优先明确前台用户和管理员/运营的访问路径；极小范围改动不必强行补全完整地图
+- **规则先读再写**：页面、导航、DB、custom_script、AIHub 开发前优先读对应规则/规格；范围清晰的小修读最小必要内容即可
+- **验证按影响选择**：静态检查、结构检查和真实数据/API 回读优先；浏览器验证只在改动影响真实页面运行或布局时启用。移动端不是所有页面的固定门禁，computer use 不是默认验收工具
 - **Story 冲突**：发现与 `.draftgo/story.yaml` 冲突必须显式提示，不可静默执行
 - **changelog**：影响可见功能/跨资源/已 push 时写入 `.draftgo/changelog.md`
-
+- **UI 组件库**：DraftGo 已内置 Ant Design 5.29.3 UMD（`window.antd`），使用时须按顺序加载完整依赖链，仅加载同版本 `reset.css`，禁止额外引入 `antd.min.css`；强烈建议跟随 DraftGo 系统主题、弹窗走 `App.confirm/showModal`；详见 `rules/frontend.md §Ant Design 使用规范`
+- **下拉选择器硬规则**：所有“点击后展开选项”的控件都不得呈现系统默认下拉选项样式（如原生 `<select>` 的灰色/白色系统菜单）。只给 `<select>` 改边框、圆角或 `appearance: none` 不算合格，因为展开后的 `<option>` 仍是系统样式。必须改用自定义浮层菜单或 Ant Design `Select` / `Dropdown` / `TreeSelect` / `Cascader` / `DatePicker` 等组件，并完整处理 hover、选中态、禁用态、键盘可达、滚动和移动端适配。
+- **表格分页钉底硬规则**：使用固定高度 flex column 骨架；toolbar `flex-shrink:0`，中间数据区 `flex:1; min-height:0; overflow:auto`，分页栏独立放底部并 `flex-shrink:0; margin-top:auto`。禁止分页随数据内容高度下移，禁止整页滚动替代表格内部滚动。详见 `rules/frontend.md §表格数据区与分页钉底`。
+- **图标优先级**：页面需要图标时，按以下顺序选择：① 优先用内置 SVG 图标库（`/assets/icons/{name}.svg`，约 100+ 个，清单见 `manifest.json`）→ ② 其次用 FontAwesome（`/assets/fontawesome/css/all.min.css`，已内置 6.x 全套）→ ③ 两者都没有合适的，再自行解决（内联 SVG、emoji 或其他方案）
+- 页面开发优先使用内置的UI 组件库，若用户有指定命令/无法满足用户开发需求，可自主处理前端决策。
 ## 本地数据目录
 
 | 目录 | 内容 |
@@ -78,7 +165,6 @@ test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
 | `.draftgo/navigations/` | index.json + .html 文件 |
 | `.draftgo/db_meta/` | index.json（含 schema/permission） |
 | `.draftgo/custom_scripts/` | index.json + 脚本文件 |
-| `.draftgo/external_apis/` | index.json（auth_config 已脱敏） |
 | `.draftgo/aihub/` | index.json |
 | `.draftgo/docs/articles/` | index.json + .md 文件 |
 | `.draftgo/system_config/` | index.json |
@@ -88,17 +174,27 @@ test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
 
 ## 文档索引
 
-| 文档 | 读取时机 |
-|---|---|
-| `core/architecture.md` | 进入陌生项目·理解平台机制（3分钟） |
-| `core/modules.md` | 评估功能可行性·选择开发路径 |
-| `specs/runtime.md` | 处理 token/路由/事件/全局层问题 |
-| `specs/data.md` | 动态 DB·filters·db_meta 操作 |
-| `specs/ui-protocol.md` | dg-* 完整映射表 |
-| `specs/security.md` | 开发禁区速查 |
-| `practices/dev-declaration.md` | 标准功能/高风险任务开始前 |
-| `practices/best-practices.md` | 开发决策·Code Review |
-| `practices/anti-patterns.md` | 检查反模式 |
-| `quickref/app-api.md` | App API 速查 |
-| `quickref/api-endpoints.md` | 后端端点速查 |
-| `quickref/dg-components.md` | dg-* 组件代码示例 |
+| 文档 | 用途 | 优先读的场景 |
+|---|---|---|
+| `core/architecture.md` | 平台机制 | 进入陌生项目·理解平台机制（3分钟） |
+| `core/modules.md` | 功能可行性 | 评估功能可行性·选择开发路径 |
+| `specs/runtime.md` | 运行时机制 | 处理 token/路由/事件/全局层问题 |
+| `specs/data.md` | 动态 DB·filters·db_meta·关联关系 | ✅ 使用 filters 查询<br>✅ 设计 searchable 字段<br>✅ 需要范围/模糊/精确检索<br>✅ 定义关联关系和级联删除<br>✅ 使用 populate 填充关联数据 |
+| `specs/db-relations.md` | DB 关联长示例 | 需要 many-to-one / one-to-many / many-to-many、populate、onDelete 的完整示例 |
+| `specs/custom-services.md` | 自定义服务完整契约 | 编写或调试 Go 服务、handler ctx、SDK、权限、Agent 工具、事件/定时任务 |
+| `specs/security.md` | 开发禁区 | 开发禁区速查 |
+| `practices/dev-declaration.md` | 开发声明 | 标准功能/高风险任务开始前 |
+| `practices/best-practices.md` | 最佳实践 | 开发决策·Code Review |
+| `practices/anti-patterns.md` | 反模式 | 检查反模式 |
+| `quickref/app-api.md` | App API | App API 速查 |
+| `quickref/api-endpoints.md` | 后端端点 | 后端端点速查 |
+
+## 文档读取策略
+
+把规则按“漏读代价”分层，不要默认指望 AI 主动翻到正确文件：
+
+- **高频 + 高代价**：内联到 `SKILL.md`、`rules/dev-workflow.md`、`practices/dev-declaration.md` 这类必经路径
+- **低频 + 明确触发**：保留外链，但必须写清触发条件
+- **低频 + 低代价**：继续保持外链，只在需要时读
+
+结论：如果某条规则一旦漏掉就会直接影响闭环、入口、数据、权限或验证，它就不该只躺在按需阅读文件里。

package/resources/skill/core/architecture.md

@@ -28,27 +28,6 @@ DraftGo **不是传统 SPA**，是「数据库驱动的页面资产运行时」
 
 ---
 
-## dg-* = shadcn（核心认知，最高优先级）
-
-```
-dg-button     →  shadcn <Button>
-dg-card       →  shadcn <Card>
-dg-form       →  shadcn <Form>
-dg-table      →  shadcn <Table>
-dg-dialog     →  shadcn <Dialog>
-dg-sheet      →  shadcn <Sheet>
-dg-tabs       →  shadcn <Tabs>
-dg-dropdown-menu → shadcn <DropdownMenu>
-dg-tooltip    →  shadcn <Tooltip>
-dg-skeleton   →  shadcn <Skeleton>
-```
-
-- `dg-*` = shadcn/ui 的 DraftGo HTML 协议表达，**不是** daisyUI / Bootstrap / 自研库
-- 数据库页面不进入 Vite/React 编译链，所以不能写 TSX；改用对应 `dg-*` 标签
-- 完整映射表见 `{{SKILL_DIR}}/specs/ui-protocol.md`
-
----
-
 ## App 对象是什么（1 分钟）
 
 壳层将能力对象赋值给 `window.App`，页面内通过 `window.parent.App` 访问：
@@ -57,7 +36,8 @@ dg-skeleton   →  shadcn <Skeleton>
 const App = window.parent?.App;
 
 // 请求（自动携带 token）
-await App.get('pages', { page: 1, page_size: 20 });
+await App.get('pages');                         // 全量列表
+await App.get('pages', { page: 1, page_size: 20 }); // 分页列表
 await App.post('db/order', { data: { name: '张三' } });
 
 // 反馈
@@ -84,8 +64,8 @@ App.theme         // 'light' | 'dark'
 | 层 | 技术 |
 |---|---|
 | 后端 | FastAPI 0.115.0 · SQLAlchemy 2.0.36 · Pydantic 2.10.0 · MySQL · Redis |
-| 壳层前端 | React · Vite · shadcn/ui · Tailwind CSS |
-| 数据库页面 | 原生 HTML · `/assets/tailwindcss.js`（运行时）· FontAwesome · GSAP · 内置 SVG 图标库 |
+| 壳层前端 | React · Vite |
+| 数据库页面 | 原生 HTML · `/assets/tailwindcss.js`（运行时）· FontAwesome · GSAP · html2canvas · 内置 SVG 图标库 |
 | CLI | Node.js（draftgo-cli） |
 
 数据库页面**不需要** npm install，也**不进入** React 编译，直接写 HTML + 本地资源路径。

package/resources/skill/core/modules.md

@@ -11,8 +11,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 | 页面 | 数据库 HTML（`page.value.html`） | `.draftgo/pages/` |
 | 导航栏 | 数据库 HTML（`navigation.html`） | `.draftgo/navigations/` |
 | 动态 DB | db_meta 定义 schema + `/api/db/{type}` 操作数据 | `.draftgo/db_meta/` |
-| 自定义服务 | Python/JS/TS/Shell/Go 脚本，支持 route/event/scheduled 三种模式 | `.draftgo/custom_scripts/` |
-| 外部 API | 管理端注册 + 页面调用 `App.callApi(code, ...)` | `.draftgo/external_apis/` |
+| 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | `.draftgo/custom_scripts/` |
 | AIHub | 配置 AI Agent，页面调用 `DraftGoAI.chat/images` | `.draftgo/aihub/` |
 | 文档中心 | Markdown 文章 + 分类树 | `.draftgo/docs/articles/` |
 | 系统配置 | KV 存储，含全局前端层槽位 | `.draftgo/system_config/` |
@@ -40,8 +39,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
   → 图片生成 → AIHub + DraftGoAI.images()
 
 要调用第三方服务？
-  → 纯 HTTP 调用 → 外部 API（管理端注册，App.callApi 调用）
-  → 需要服务端逻辑（定时/事件/加工） → 自定义服务
+  → 自定义服务（用 `ctx.HTTP` 请求；需要时可用 route/event/scheduled 加工）
 
 要展示内容文档？
   → 文档中心（Markdown + 分类树）
@@ -52,3 +50,15 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 要做后台管理页？
   → 业务页面 + 动态 DB + 角色权限
 ```
+
+## 自定义服务边界
+
+- 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、ctx 和 SDK 契约见 `specs/custom-services.md`。
+- `route`：对外暴露 HTTP 端点，运行时路径为 `/api/x/{slug}/{path}`；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，推送后要真实请求验证。
+- `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
+- `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
+- 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。
+- 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 调用面继续由每个服务的 `permission` / `route_security` 独立控制，不要把两层权限混为一谈。
+- Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
+- 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
+- 脚本内读动态 DB 用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `specs/custom-services.md`。

package/resources/skill/init/SKILL.md

@@ -64,14 +64,13 @@ allowed-tools: Bash(python:*), Bash(find:*), Read
 
 ## 完成提示
 
-将脚本的输出摘要（页面数、导航数、文档数、自定义脚本数、外部 API 数、服务器地址）告知用户，并提示：
+将脚本的输出摘要（页面数、导航数、文档数、自定义脚本数、服务器地址）告知用户，并提示：
 - 下一步：描述要开发的功能，或运行 `/draftgo push` 推送修改
 - 如需刷新数据：运行 `/draftgo pull`（按类型增量拉取）或 `/draftgo pull --all`（全量刷新）
 - 已拉取的资源分布：
   - `.draftgo/pages/`、`.draftgo/navigations/`：页面与导航 HTML
   - `.draftgo/docs/articles/`：文档中心文章正文（Markdown），分类索引在 `.draftgo/doc_categories/index.json`
-  - `.draftgo/custom_scripts/`：自定义脚本代码（按 language 落到 `.py`/`.js` 等），meta 在同目录 `index.json`
-  - `.draftgo/external_apis/index.json`：外部 API 注册（`auth_config` 已脱敏）
+  - `.draftgo/custom_scripts/`：Go 自定义服务代码（`.go`），meta 在同目录 `index.json`
 - 修改这些资源后通过 `/draftgo push <类型>` 推回云端，类型见根 SKILL.md。
 
-> 注意：拉取 `external_apis` / `docs` (admin 列表) / `custom_scripts` 都需要 SAT 具备 admin 权限。若任一项返回 0 条但用户期望应有数据，提醒用户检查 token 角色。
+> 注意：拉取 `docs` (admin 列表) / `custom_scripts` 需要令牌具备对应读取权限（自定义服务为 `scripts:read`，admin 自动通过）。若任一项返回 0 条但用户期望应有数据，提醒用户检查 token 角色权限。

package/resources/skill/practices/anti-patterns.md

@@ -11,6 +11,9 @@ read_when: 开发前检查思路 · Code Review 时
 | 静态卡片充当功能 | 按钮点击无效，数据硬编码 | 默认按真实落地闭环实现；用户说"先看效果"才允许 mock |
 | 只建页面不绑入口 | 页面存在但无法访问 | 创建页面后必须绑定至少一个入口 |
 | 只做前台不做后台 | 展示数据没有维护入口 | 展示可维护内容时主动判断是否需要管理侧页面 |
+| 业务页批量复制工作台模板 | 页面之间只有标题不同，体验同质化 | 按业务差异拆分列表/详情/编辑/管理结构，不要整页复制 |
+| 新导航直接改坏内置导航 | 容易丢失原有路由和配置能力 | 需要新导航时先复制一份内置导航再改 |
+| 新系统不做范围清点就开工 | 页面、功能、数据和管理端边界混乱 | 通常先在 Task 写轻量 PRD，清点页面/功能/数据/入口后再开发 |
 | 伪功能写入 lessons 前不说明 | 用户不知道功能不完整 | 无法实现真实闭环时停止开发，向用户说明阻塞点 |
 
 ---
@@ -20,8 +23,11 @@ read_when: 开发前检查思路 · Code Review 时
 | 反模式 | 问题 |
 |---|---|
 | 在数据库页面写 TSX / React 组件 | 数据库页面不进入 Vite 编译链 |
-| 把 `dg-*` 当 daisyUI / Bootstrap | `dg-*` 是 shadcn 协议，不是别的库 |
 | 在业务页面渲染系统 Header / 导航 | Header 属于壳层，页面渲染会重复 |
+| 无视现有导航直接重做顶部栏/后台侧栏 | 容易丢失现有路由、权限入口和配置能力 |
+| 直接修改系统内置页面承接业务需求 | 容易破坏管理员能力和平台升级兼容性 |
+| 把普通用户也暴露到管理后台入口 | 容易污染前台语境 | 普通用户不显示管理后台，管理员额外显示 |
+| 用 `/admin/db` 承接全部运营功能 | 业务域能力和底层数据能力混在一起 | 业务后台按域拆分，`/admin/db` 只保留通用数据能力 |
 | 修改壳层 `.tsx` 文件来改页面内容 | 页面内容在数据库里，改壳层源码不对 |
 
 ---
@@ -31,10 +37,10 @@ read_when: 开发前检查思路 · Code Review 时
 | 反模式 | 问题 | 正确做法 |
 |---|---|---|
 | 不检查 `res.code` 直接用 `res.data` | 报错时会访问 null | 先 `if (res.code !== 200)` 处理错误 |
-| GET 列表不传分页参数 | 数据超 10000 条后端返回 400 | 始终传 `page` + `page_size` |
+| 大数据表格不传分页参数 | 后端会全量返回，首屏可能慢 | 表格/后台列表显式传 `page` + `page_size` |
 | `GET /db-meta/{id}` 用 id 查 type | 返回"元数据不存在" | 用 type 查：`GET /db-meta/{type}` |
 | 动态 DB POST 时字段平铺到 body 顶层 | 字段被忽略 | 业务字段必须放在 `data: {}` 里 |
-| 在页面里写死 API Key / Bearer | 密钥暴露在前端 | 管理端注册外部 API，用 `App.callApi` 调用 |
+| 在页面里写死 API Key / Bearer | 密钥暴露在前端 | 在 Go 自定义服务中使用 `ctx.HTTP`，页面调用其 route 端点 |
 
 ---
 
@@ -56,6 +62,7 @@ read_when: 开发前检查思路 · Code Review 时
 | 小修也走完整 Story 门 | 拖慢速度，过度流程化 |
 | 发现与 Story 冲突时静默执行 | 覆盖已确认的需求 |
 | 页面改了但没更新导航入口 | 用户找不到新功能 |
+| 开发前完全不读对应规则文档 | 容易误改系统页、误用导航、误写平台语法 |
 | 每次开发都从头读全部规则 | 按任务规模渐进读取，小修只读最小必要规则 |
 
 ---
@@ -66,5 +73,8 @@ read_when: 开发前检查思路 · Code Review 时
 |---|---|
 | 请求完成前页面空白 | 先渲染骨架屏，再异步填数据 |
 | 操作型页面用文档流堆叠 | 分页/操作栏随少量数据上浮 | 
-| 硬编码颜色 | 亮暗切换后颜色异常 |
+| 只按当前主题硬编码颜色 | 亮暗切换后颜色异常，应优先用系统 token，自主配色也要同时覆盖浅色与深色 |
+| 弹窗内容区自带双滚动条 | 体验粗糙、难以操作 | 弹窗/抽屉优先隐藏外层滚动条，只让内容区滚动 |
+| 下拉选择器直接用原生 select / 系统默认下拉样式 | 视觉和交互过于默认，难以和页面风格一致 | 优先做自定义弹层菜单 |
+| 前端完全没有动效层次 | 页面显得僵硬 | 在关键转场、状态变化和层级切换处合理使用 GSAP |
 | 引入境外 CDN | 国内访问慢/超时 |