draftgo-cli 1.0.0 → 1.1.1

package/resources/skill/CLAUDE.md

@@ -1,239 +0,0 @@
-# DraftGo 项目上下文
-
-> 由 draftgo-init 自动生成。重新初始化：`/draftgo init`
-
-## 架构认知（必读）
-
-**DraftGo 不是传统 SPA，是"数据库驱动的页面资产运行时"：**
-- 壳层（Vue 3 + Vite）只负责 runtime 编排，源码在 `frontend/src/core/`
-- 业务页面 HTML 存在数据库 `page.value.html`，运行在 `iframe.srcdoc`
-- 导航栏 HTML 存在数据库 `navigation.html`，由壳层按需加载
-- 页面与壳层通过 `window.parent.App` API 通信
-
-**技术栈：**
-- 后端：FastAPI 0.115.0 + SQLAlchemy 2.0.36 + Pydantic 2.10.0 + MySQL + Redis
-- 前端：Vue 3 + Vite + Tailwind CSS（本地 `/assets/tailwindcss.js`）
-
-## 连接信息
-- 服务器：https://dev.draftgo.cn
-- Token：存储于 `.draftgo/config.json`（已加入 .gitignore）
-
-## 开发规范
-→ 前端页面开发：读取 `.draftgo/rules/frontend.md`
-→ 页面排错指南：读取 `.draftgo/rules/debugging-syntax.md`（页面功能不执行时必读！）
-- 任何开发，必读！
-
-## 开发禁区（违反必报错）
-
-- ❌ 禁止境外 CDN（googleapis/jsdelivr/cdnjs/unpkg）→ ✅ 允许国内镜像（npmmirror.com/staticfile.net）
-- ❌ 禁止 `App()` 写法（App 是对象不是函数）→ ✅ 正确：`const App = window.parent?.App`
-- ❌ 禁止 `const App = () => window.parent?.App` → ✅ 去掉箭头函数
-- ❌ 禁止 `window.location.search` 读参数 → ✅ 用 `window.__DG_ROUTE_CONTEXT__.query`
-- ❌ 禁止 `App?.user?.role` 判断管理员 → `App.user` 不存在！✅ 用 `App.isAdmin` 或 `App.currentUser?.role_code`
-- ❌ 禁止 `navigate('/login')` 退出 → ✅ 用 `window.location.href = '/login'`
-- ❌ 禁止 `window.alert/confirm/prompt` → ✅ 用 `App.toast()` / `App.confirm()` / `App.showModal()`
-  - `App.showSuccess(msg)` 成功提示（绿色 3s）— 推荐用于操作成功反馈
-  - `App.showError(msg)` 错误提示（红色 4s）— 推荐用于失败反馈
-  - `App.showWarning(msg)` 警告提示（黄色 3s）— 推荐用于提醒
-  - `App.showInfo(msg)` 信息提示（蓝色 3s）— 推荐用于中性信息
-  - `App.toast(msg, type)` 通用方法 — type: success/error/warning/info
-  - `App.confirm(msg, title?)` 确认弹窗 — 玻璃蒙层 + 弹跳动画 + ⚠ 图标，双按钮，返回 Promise\<boolean\>
-  - `App.showModal(msg, title?)` 信息模态框 — 玻璃蒙层 + 弹跳动画 + i 图标，单按钮，替代 alert()
-  - `App.showLoading()` / `App.hideLoading()` — 全局 loading 玻璃蒙层，手动开关
-  - 详见 `.draftgo/rules/frontend.md` App API 章节
-- ⚠️ 尽量避免硬编码颜色 → 优先用 `var(--dg-accent)` 等 token 以适配主题切换 
-
-## 主题切换适配
-
-DraftGo 支持多套配色方案 + 亮暗模式，通过 CSS 变量实现。
-
-**概念分层：**
-| 概念 | 存储键 | 取值 |
-|---|---|---|
-| 显示模式 | `dg_theme` | `'light'` \| `'dark'` \| `'system'` |
-| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` |
-
-**内置配色方案：**
-- `dark-gray-white` 深灰白（默认）— 冷调深灰，干净利落
-- `deep-blue-white` 深蓝白 — 专业稳重，企业风
-- `orange-white` 橙白 — 温暖醒目，创意风
-
-**颜色 Token（优先使用）：**
-- `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` — 背景层级
-- `--dg-text-primary` / `--dg-text-secondary` / `--dg-text-muted` — 文字层级
-- `--dg-accent` / `--dg-accent-hover` / `--dg-accent-subtle` — 主题色
-- `--dg-border` / `--dg-success` / `--dg-error` / `--dg-warning` — 功能色
-
-**App API 切换配色：**
-```javascript
-App.setColorScheme('deep-blue-white');              // 切换为预设方案
-App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
-```
-
-**硬编码颜色的场景（允许但需注意）：**
-- 品牌色（如 Logo 固定色）
-- 数据可视化图表（需保证对比度）
-- 第三方组件库强制要求
-
-**硬编码时的要求：**
-- 同时提供亮色/暗色两套值，通过 `[data-theme="dark"]` 选择器切换
-- 确保对比度符合 WCAG AA 标准（文字至少 4.5:1）
-
-## 本地开发流程
-
-**原则：有功能修改就读本地数据，自主决策是否调用 API 完成高质量修改。**
-
-1. **开发时**：读写 `.draftgo/` 本地文件
-   - 查元数据：读 `index.json`
-   - 查/改 HTML：按 `html_file` 字段路径读对应 `.html` 文件
-2. **修改后**：运行同步脚本推送到服务器（见下方"同步命令"）
-3. **同步成功**：本地与服务器数据一致
-
-**本地数据目录：**
-
-| 目录 | 内容 |
-|---|---|
-| pages/ | index.json（无 html）+ 若干 .html |
-| navigations/ | index.json（无 html）+ 若干 .html |
-| roles/ | index.json |
-| users/ | index.json |
-| db_meta/ | index.json |
-| aihub/ | index.json |
-| system_config/ | index.json |
-| iteration/ | YYYY-MM-DD.txt（迭代日志） |
-| error/ | YYYY-MM-DD.txt（错误日志） |
-
-## 数据库 Schema（关键字段）
-
-| 表 | 关键字段 | 说明 |
-|---|---|---|
-| `page` | `id`, `title`, `route`, `permission`, `value` (JSON: `{html: "..."}`) | value.html 存页面完整 HTML |
-| `navigation` | `id`, `code`, `name`, `html`, `order`, `status` | html 字段存导航栏完整 HTML |
-| `user` | `id`, `username`, `email`, `role_id`, `status` | role_id 关联 role 表 |
-| `role` | `id`, `code`, `name`, `permissions` (JSON) | admin 角色拥有所有权限 |
-| `db_meta` | `id`, `type`, `fields` (JSON: `[{name, type, required}]`) | 动态表结构定义 |
-| `db` | `id`, `type`, `data` (JSON), `userid`, `status`, `created_at`, `updated_at` | 动态数据存储（含自动时间戳） |
-| `aihub` | `id`, `name`, `type`, `config` (JSON), `status` | AI 服务配置 |
-| `sys_config` | `config_key`, `config_value`, `value_type`, `category`, `is_sensitive` | 系统配置 KV |
-
-## API 速查与示例
-
-| 模块 | 端点 |
-|---|---|
-| 认证 | POST /api/auth/login, /register, /logout, /refresh, /forgot-password, /reset-password |
-| 微信认证 | POST /api/auth/wechat/mp/oauth, /wechat/mini/login, /wechat/mp/qr/create · GET /wechat/mp/qr/poll |
-| 用户 | GET/PUT /api/users/me · GET/POST /api/users · GET/PUT/DELETE /users/{id} · POST /users/{id}/ban, /unban |
-| 角色 | GET/POST /api/roles · GET/PUT/DELETE /roles/{id} · POST /roles/{id}/assign/{uid} · DELETE /roles/{id}/revoke/{uid} |
-| 页面 | GET/POST /api/pages/ · GET/PUT/DELETE /pages/{id} · POST /pages/{id}/reset-system · GET /pages/by-route · GET /pages/public/{route} |
-| 导航栏 | GET/POST /api/navigations · GET /navigations/{code} · PUT/DELETE /navigations/{id} · POST /navigations/{id}/reset-system |
-| 系统配置 | GET /api/system/config · GET /system/category/{category} · GET/PUT/DELETE /system/{key} · POST /system/ · POST /system/config/ensure |
-| 备份恢复 | GET/POST /api/system/backup · POST /system/restore · POST /system/reset · POST /system/backup/selective · POST /system/restore/selective · GET /system/backup/logs |
-| 通知公告 | GET/POST /api/notices · GET/PUT/DELETE /notices/{id} |
-| 反馈 | GET/POST /api/feedback · GET /feedback/updates · GET/PUT/DELETE /feedback/{id} · DELETE /feedback/batch |
-| 日志 | GET /api/logs · GET /logs/{id} |
-| 智能体 | GET /api/agents · GET /agents/logs · POST /agents/{id}/chat · POST /agents/{id}/preview-chat |
-| 动态DB | GET/POST /api/db/{type} · GET/PUT/DELETE /db/{type}/{id} |
-| DB Meta | GET/POST /api/db-meta · GET /db-meta/{type} · PUT/DELETE /db-meta/{id} |
-| ⚠️ DB Meta 查询 | GET /db-meta/{type} 用 **type**（如 `patient_profile`），不是 id。用 id 查会返回 "元数据不存在"。PUT/DELETE 才用 id。 |
-| AIHub | GET/POST /api/aihub · GET/PUT/DELETE /aihub/{id} · PATCH /aihub/{id}/basic · POST /aihub/{id}/sync · POST /aihub/discover · GET /aihub/types |
-| AI推理 | GET /api/v1/models · POST /v1/chat/completions |
-| 文件上传 | POST /api/upload |
-| 通知测试 | POST /api/system/notifications/test-email, /test-sms · GET /system/notifications/logs |
-
-### 高频 API 示例
-
-**创建页面（需 admin）：**
-```
-POST /api/pages/
-Body: { "title": "新页面", "route": "/new", "permission": "public", "value": {"html": "<html>...</html>"} }
-Response: { "id": 123, "title": "新页面", "route": "/new", ... }
-```
-
-**更新页面 HTML（需 admin）：**
-```
-PUT /api/pages/123
-Body: { "value": {"html": "<html>更新后...</html>"} }
-```
-
-**重置系统页面（需 admin）：**
-```
-POST /api/pages/123/reset-system
-Body: 空
-说明：从 backend/init/pages/ 重新加载该页面
-```
-
-**创建动态数据（普通用户自动绑定 userid）：**
-```
-POST /api/db/patient
-Body: { "data": {"name": "张三", "age": 30} }
-Response: { "id": 456, "type": "patient", "data": {...}, "userid": 当前用户id, "status": 1, "created_at": "2026-01-01T12:00:00", "updated_at": "2026-01-01T12:00:00" }
-```
-
-**查询动态数据（带分页）：**
-```
-GET /api/db/patient?page=1&page_size=20
-Response: { "items": [{ "id": 456, "type": "patient", "data": {...}, "userid": 1, "status": 1, "created_at": "...", "updated_at": "..." }], "total": 100, "page": 1, "page_size": 20 }
-```
-
-## URL 参数读取
-
-页面运行在 `iframe.srcdoc` 中，`window.location.search` 不可靠。框架通过 `<script data-dg-route-bridge>` 注入路由上下文。
-
-```javascript
-// 标准三阶回落（推荐）
-const routeContext =
-  window.__DG_ROUTE_CONTEXT__
-  || window.__DG_GET_ROUTE_CONTEXT__?.()
-  || window.parent?.App?.getCurrentRouteContext?.()
-  || { query: {} };
-const query = routeContext.query || {};
-
-// 使用示例
-// 路由 /doctor/prescription-estimate?patientId=42&visitId=7
-const patientId = query.patientId;  // "42"
-const visitId = query.visitId;      // "7"
-```
-
-禁止：`new URLSearchParams(window.location.search)` — iframe 中取不到壳层 URL。
-
-## 常见问题排查
-
-| 问题 | 排查步骤 |
-|---|---|
-| 同步失败 | 1. 检查 `.draftgo/config.json` token 是否有效<br>2. 检查服务器连接（ping/curl）<br>3. 查看 `.draftgo/error/YYYY-MM-DD.txt` 错误日志 |
-| 页面加载空白 | 1. 检查 `permission` 字段与当前用户角色是否匹配<br>2. 检查路由是否正确（`/api/pages/by-route?route=/xxx`）<br>3. 浏览器控制台查看 JS 错误 |
-| API 返回 401 | Token 过期，前端会自动用 refresh token 刷新，无需手动处理 |
-| API 返回 403 | 权限不足，检查当前用户角色是否有对应权限 |
-| DB Meta GET 返回"元数据不存在" | 你用了 id，应该用 **type**（如 `/api/db-meta/patient_profile`）。PUT/DELETE 才用 id。 |
-| 颜色不生效 | 检查是否用了 `var(--dg-*)` 而非硬编码 hex/rgb |
-| URL 参数读取失败 | 检查是否用了 `window.__DG_ROUTE_CONTEXT__.query` 而非 `window.location.search` |
-| 退出登录后导航栏未更新 | 检查是否用了 `window.location.href = '/login'` 而非 `navigate('/login')` |
-
-## 错误日志规范
-
-**遇到任何开发/运行时错误，必须自动追加到 `.draftgo/error/YYYY-MM-DD.txt`：**
-
-格式：`[HH:MM:SS] [错误类型] 描述`
-
-示例：
-```
-[14:23:45] [同步失败] pages/123 同步到服务器失败：401 Unauthorized
-[14:30:12] [API错误] GET /api/db/patient 返回 500：数据库连接超时
-[15:10:33] [页面错误] admin-users.html 第 42 行：App is not a function
-```
-
-操作流程：
-1. 捕获错误后，获取当前日期和时间
-2. 检查 `.draftgo/error/YYYY-MM-DD.txt` 是否存在
-3. 存在则 Read 后追加新行；不存在则直接 Write
-4. 无需告知用户（静默执行）
-
-## 同步命令
-
-> **禁止用 npx/npm/curl 同步。必须用 Python 脚本：**
-> `python .draftgo/skill/scripts/draftgo_sync.py pages <page_id>`
-> `python .draftgo/skill/scripts/draftgo_sync.py nav <nav_id>`
-
-- `/draftgo sync pages` — 触发 sync skill（不是 CLI 命令）
-- `/draftgo sync nav` — 触发 sync skill（不是 CLI 命令）
-- `/draftgo init` — 触发 init skill（不是 CLI 命令）