diff --git a/.agents/skills/v3-create-crud/SKILL.md b/.agents/skills/v3-create-crud/SKILL.md index a9c6a29..9dc34e6 100644 --- a/.agents/skills/v3-create-crud/SKILL.md +++ b/.agents/skills/v3-create-crud/SKILL.md @@ -3,4 +3,4 @@ name: v3-create-crud description: 调整业务页面与表单 --- -先读根 AGENTS.md，核对后端路由和现有业务调用链。页面放 `web/src/pages//`，私有 API/类型跟随模块；真正跨模块共享才放 common。复用实际 Element Plus 控件和 `http/axios` 的 requestJSON/requestRaw，不预设分页、CRUD、导出或角色能力。失败保留原因，成功后再关闭/刷新，取消确认不得伪装成实际操作成功。按行为测试成功、失败与权限边界。 +先读根 AGENTS.md，核对后端路由和现有业务调用链。页面私有组件、类型和组合函数放 `web/src/pages//`；全部 API 放 `common/apis//{index.ts,type.ts}`。按模板导出独立 `*Api` 函数，用 `request({ url, method, data, params })` 返回完整响应，调用方读取 `.data`；原文/下载按实际语义保留响应。复用 Element Plus 的 Form、Dialog、表单控件和 Table，不预设分页、CRUD、导出或角色能力。失败保留原因，成功后再关闭/刷新，取消确认不得伪装成实际操作成功。按行为测试成功、失败与权限边界。 diff --git a/.agents/skills/v3-upsert-route/SKILL.md b/.agents/skills/v3-upsert-route/SKILL.md index 7a66e56..028e7ed 100644 --- a/.agents/skills/v3-upsert-route/SKILL.md +++ b/.agents/skills/v3-upsert-route/SKILL.md @@ -3,4 +3,4 @@ name: v3-upsert-route description: 调整登录守卫与权限路由 --- -先读根 AGENTS.md、`web/src/router/` 和 `pinia/stores/{user,permission}.ts`。常驻与动态路由按现有实现登记，匿名路由使用 meta.anonymous，真实权限来自 /auth/me，无角色系统。唯一名称、懒加载；核对匿名/初始化/回跳、深链、403、401、注销及换会话，旧结果不能注册新会话路由。 +先读根 AGENTS.md、`web/src/router/` 和 `pinia/stores/{user,permission}.ts`。常驻与动态路由按现有实现登记，匿名路由使用 meta.anonymous，真实权限来自 common/apis/auth 的 /auth/me 响应 data，无角色系统。唯一名称、懒加载；核对匿名/初始化/回跳、深链、403、401、注销及换会话，旧结果不能注册新会话路由。 diff --git a/.agents/skills/v3-upsert-store/SKILL.md b/.agents/skills/v3-upsert-store/SKILL.md index 39c1c95..2a888d0 100644 --- a/.agents/skills/v3-upsert-store/SKILL.md +++ b/.agents/skills/v3-upsert-store/SKILL.md @@ -3,4 +3,4 @@ name: v3-upsert-store description: 调整 Pinia 共享状态 --- -先读根 AGENTS.md 和现有 store。跨页面共享状态放 `web/src/pinia/stores/`，使用 Setup Store；页面表单和工作区临时状态留在模块。setup 外显式传入 pinia，不增加转发函数或重复镜像。认证变更通过 user store 更新会话代号，持久化仅保留已有明确需求。验证旧请求隔离与状态重置。 +先读根 AGENTS.md 和现有 store。跨页面共享状态放 `web/src/pinia/stores/`，使用 Setup Store，状态、动作和保存队列均归 store 实例所有，API 从 common/apis 对应资源导入；页面表单和工作区临时状态留在模块。setup 外显式传入 pinia，不增加转发函数或重复镜像。认证变更通过 user store 更新会话代号，持久化仅保留已有明确需求。验证旧请求隔离与状态重置。 diff --git a/.agents/skills/v3-use-composables/SKILL.md b/.agents/skills/v3-use-composables/SKILL.md index e4f0ce3..0b8150c 100644 --- a/.agents/skills/v3-use-composables/SKILL.md +++ b/.agents/skills/v3-use-composables/SKILL.md @@ -3,4 +3,4 @@ name: v3-use-composables description: 提取或复用业务组合函数 --- -先读根 AGENTS.md 及实际调用方。当前项目没有模板分页、全屏加载等示例组合函数，不凭模板声明调用不存在的能力。页面私有组合函数跟随模块；仅为实际跨模块复用提取 common，不为单次代码建立新层。异步失败明确拒绝，同一错误由负责层展示。 +先读根 AGENTS.md 及实际调用方。当前项目没有模板分页、全屏加载等示例组合函数，不凭模板声明调用不存在的能力。API 请求统一从 common/apis 对应资源导入，组合函数不另造请求封装；页面私有组合函数跟随模块；仅为实际跨模块复用提取 common，不为单次代码建立新层。异步失败明确拒绝，同一错误由负责层展示。 diff --git a/.agents/skills/v3-use-utils/SKILL.md b/.agents/skills/v3-use-utils/SKILL.md index c84f3db..e705e82 100644 --- a/.agents/skills/v3-use-utils/SKILL.md +++ b/.agents/skills/v3-use-utils/SKILL.md @@ -3,4 +3,4 @@ name: v3-use-utils description: 复用公共工具与认证能力 --- -先读根 AGENTS.md 和 `web/src/common/utils/` 的实际实现。命令、路径、通知、PWA 等按已有签名复用；认证 Token 由 user store 维护，不绕过会话与动态路由清理。没有模板示例的角色/日期工具，不引入虚构依赖。页面专用转换留在页面模块，未知外部输入在边界校验。 +先读根 AGENTS.md 和 `web/src/common/utils/` 的实际实现。命令、路径、通知、PWA 等按已有签名复用；认证 Token 由 user store 维护，不绕过会话与动态路由清理。没有模板示例的角色/日期工具，不引入虚构依赖。API 请求只通过 `common/apis//index.ts` 的独立函数与 `http/axios` 的 request；原生资源票据缓存等实际共享工具留在 common/utils。页面专用转换留在页面模块，未知外部输入在边界校验。 diff --git a/AGENTS.md b/AGENTS.md index b7c9322..30fc630 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,8 +79,10 @@ RawMark 是单用户 Markdown 网页笔记编辑器。文件是真源；Go 标 ## 目录与依赖边界 -- `web/src/pages//`：页面入口及模块私有的组件、API、类型、业务状态、编辑器和资源；按实际需要建子目录，不建空目录或转发层。 -- `web/src/common/`：确实跨模块复用的 API、外观与字体、Markdown、高亮、插件 SDK、组件和工具。不得依赖页面私有代码；模块入口可提供明确的 props/emits 契约供应用装配。 +- `web/src/pages//`：页面入口及模块私有的组件、类型、组合函数、业务状态、编辑器和资源；按实际需要建子目录，不建空目录或转发层。 +- `web/src/common/`：统一的资源 API、确实跨模块复用的外观与字体、Markdown、高亮、插件 SDK、组件和工具。不得依赖页面私有代码；模块入口可提供明确的 props/emits 契约供应用装配。 +- 公共组件使用 `web/src/common/components//index.vue`，目录名使用 PascalCase；引用直接指向该入口，不添加转发文件。 +- 全部 API 集中在 `web/src/common/apis//index.ts` 与 `type.ts`，按后端资源命名；`index.ts` 导出独立的 `*Api` 函数，使用 `import type * as Resource from './type'` 与 `request({ url, method, data, params })`，不建立 API 聚合对象、转发层或页面私有请求。请求/响应类型在对应 `type.ts`，普通响应使用全局 `ApiResponseData`，调用方显式读取 `.data`；原文/下载需要响应头时使用 `returnResponse: true` 返回 Axios 原始响应，204 返回 void，事件连接也归对应资源目录。 - `web/src/http/`：Axios、认证头、统一响应与请求错误；`router/`：路由与守卫；`pinia/`：实例及共享认证、权限、设置状态。工作区临时状态不强制放入全局 store。 - `web/types/auto/`：由 Vite 自动导入插件生成；修改源配置并重新构建，不手改声明。业务类型就近定义，测试随模块存放。 - `internal/api/` 定义路由、授权和 HTTP 契约，`internal/auth/` 管理密码与凭据，`internal/store/` 管理应用 SQLite；`internal/vault/` 管理真源文件，搜索索引可重建。`web/*.go` 保留生产嵌入与开发模式边界。 diff --git a/README.md b/README.md index ca85ab7..ec9f6f2 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ go test -tags dev ./web ## 前端结构与接口升级 -前端以 [vue3-starter](https://github.com/eezd/vue3-starter/tree/fd41d62ce3f1c8338a478e0be3e2f31b53b7ea5e) 为结构基线，保留 RawMark 的编辑器、主题与布局；模板许可在 `web/LICENSE`。`web/src/pages/workspace/` 管理笔记、目录、编辑器与图片，`pages/settings/` 管理设置及维护，`pages/login/` 管理初始化与验证码登录；私有 API 和类型跟随模块。实际共享的外观、Markdown、插件 SDK 与 API 位于 `common/`；请求、路由、共享状态分别由 `http/`、`router/`、`pinia/` 管理。唯一前端构建入口为 `web/`，使用 pnpm 锁文件。 +前端以 [vue3-starter](https://github.com/eezd/vue3-starter/tree/fd41d62ce3f1c8338a478e0be3e2f31b53b7ea5e) 为结构基线，保留 RawMark 的编辑器、主题与布局；模板许可在 `web/LICENSE`。`web/src/pages/workspace/` 管理笔记、目录、编辑器与图片，`pages/settings/` 管理设置及维护，`pages/login/` 管理初始化与验证码登录；页面私有组件、类型和组合函数跟随模块。全部资源 API 统一位于 `common/apis//index.ts` 与 `type.ts`，API 函数直接调用 `request({ url, method, data, params })` 并返回完整 `{ code, data, message }`，调用方读取 `.data`；原文及下载用 `returnResponse: true` 保留 Axios 响应和响应头，204 为 void，事件连接也归资源 API。实际共享的外观、Markdown、插件 SDK 位于 `common/`；请求、路由、共享状态分别由 `http/`、`router/`、`pinia/` 管理。唯一前端构建入口为 `web/`，使用 pnpm 锁文件。此次 API 目录与普通页面调整复用已部署的统一后端协议，不新增数据库迁移。 本次协议升级需前后端一起发布，旧页面与旧 Cookie 会话不能继续使用，需要重新登录。升级前备份数据库和旧镜像；启动新程序时沿用现有 SQLite 初始化流程新增 `resource_tickets` 表及过期索引，保留笔记、设置、密码和 API 令牌。生产迁移与部署须另行授权，不手动运行历史清理 SQL。回滚使用配套数据库和旧镜像；新前端不能连接旧后端。