xuanzhi/xuanzhi-service

Fork 0

Files

wdh-home d8acafcdc5 docs: add web agents design spec

2026-04-22 16:23:49 +08:00

6.5 KiB

Raw Blame History

Web AGENTS 入口设计

背景

D:\Code3\wdp\xuanzhi-service\server\AGENTS.md 已经形成了一套清晰的 AI 开发入口模式：用一个顶层文档约束工程规则、架构边界和文档索引，再用 .ai-specs 承载更细的规范文档。

当前 D:\Code3\wdp\xuanzhi-service\web\AGENTS.md 只有标题，尚未形成前端工程入口。web 项目本身已经具备稳定目录结构，包括 src/view、src/components、src/api、src/pinia、src/router、src/utils、src/style 以及 src/plugin/*，因此适合补齐一套与服务端风格一致、但内容面向前端工程的入口文档体系。

目标

为 web 项目建立一份前端工程级 AGENTS.md，作为 AI 和开发者进入源码前的第一入口。
建立 web/.ai-specs 文档骨架，用索引方式承载前端工程规范。
明确当前前端项目的目录职责、联动修改规则和新增代码落点。
将 src/plugin/* 纳入统一工程规范，而不是作为游离目录处理。

非目标

不设计具体业务模块规范。
不定义列表页、表单页、详情页等业务交互模板。
不修改现有 UI/UX 风格，不重构现有目录。
不引入后端式的 Router -> API -> Service -> Model 结构到前端。

设计结论

1. 文档定位

web/AGENTS.md 采用与 server/AGENTS.md 同类的入口定位，但只覆盖前端工程规范。文档承担四类职责：

项目级硬规则。
前端架构和目录职责说明。
改动联动检查规则。
.ai-specs 文档索引。

文档风格保持“短、硬、可判定”，不写成教程，不堆叠背景描述。

2. 前端主链路

web 项目的主链路定义为：

flowchart LR
    Router["router / permission"] --> View
    View --> Components["components / hooks"]
    View --> API
    API --> Request["utils/request.js"]
    Request --> Backend["backend service"]
    Pinia["pinia"] --> View
    Pinia --> Router
    Pinia --> API
    Plugin["plugin/*"] --> View
    Plugin --> API
    Plugin --> Style["style"]

核心边界如下：

src/view：页面级编排与页面状态。
src/components：跨页面复用组件。
src/hooks：跨页面复用组合逻辑。
src/api：接口函数封装。
src/utils/request.js：请求基座，统一 token、loading、错误处理、401 跳转。
src/pinia/modules：跨页面共享状态。
src/router 与 src/permission.js：路由入口、动态路由注册、登录态和菜单进入逻辑。
src/style：全局样式和 Element Plus 覆盖。
src/plugin/*：插件化业务子目录，内部可有自己的 api / view / form，但仍服从主应用工程边界。

3. `AGENTS.md` 建议章节

建议保留与服务端相近的顶层结构：

# AI 开发入口 [!IMPORTANT]
项目级要求
工具使用规则
项目架构
架构关系
项目文档
可复用代码/组件

其中：

“项目级要求”强调 UTF-8、中文为主、先查 .ai-specs 再写代码、禁止全盘搜索、优先复用。
“项目架构”写清前端主链路与目录职责。
“架构关系”写清改动时的联动检查。
“项目文档”只列 .ai-specs 索引，不夹带业务说明。

4. `.ai-specs` 目录设计

本次只建立前端工程文档，不建立业务文档。建议目录如下：

路径	职责
`.ai-specs/coding-specs`	面向日常编码的实现规则
`.ai-specs/sys-specs`	面向整体工程的系统级规则

建议首批文档如下：

路径	用途
`.ai-specs/coding-specs/page-view-component-split.md`	规定 `view / components / hooks` 的边界与新增代码落点
`.ai-specs/coding-specs/api-request-flow.md`	规定 `api` 与 `request.js` 的分层、错误处理和调用约束
`.ai-specs/coding-specs/router-permission-route.md`	规定静态路由、动态路由、白名单和权限链路
`.ai-specs/coding-specs/pinia-store-boundary.md`	规定 store 的职责边界与页面状态分层
`.ai-specs/coding-specs/plugin-module-structure.md`	规定 `plugin/*` 的标准结构与和主应用的关系
`.ai-specs/coding-specs/style-asset-spec.md`	规定 `style`、静态资源、主题覆盖的边界
`.ai-specs/sys-specs/frontend-directory-spec.md`	规定前端工程目录总体结构和推荐新增落点
`.ai-specs/sys-specs/naming-import-path-spec.md`	规定命名、导入别名、组件和 API 命名方式
`.ai-specs/sys-specs/env-build-spec.md`	规定环境变量、Vite 构建配置和脚本修改边界

5. 联动修改规则

web/AGENTS.md 里应明确“改哪里，就必须回查哪里”，至少覆盖以下规则：

改 view：同步检查对应 api、pinia、路由入口、页面标题、keep-alive、权限显示。
改 components：同步检查调用页面、props、events、slots 和样式兼容性。
改 hooks：同步检查调用方是否仍满足生命周期与响应式前提。
改 api：同步检查 request.js 契约、调用页面、store、错误提示和返回值结构。
改 request.js：同步检查 token 注入、loading、401 跳转、上传下载、插件接口兼容性。
改 pinia：同步检查页面初始化、异步路由依赖、缓存和持久化字段。
改 router 或 permission.js：同步检查白名单、动态路由注入、默认首页、菜单跳转和未登录跳转。
改 style：同步检查全局覆盖范围，避免误伤插件页面和其他公共页面。
改 plugin/*：同步检查插件内部 api / view / form 是否自洽，以及是否错误侵入主应用公共层。

6. 落地粒度

本次落地只生成：

web/AGENTS.md
web/.ai-specs/coding-specs/*
web/.ai-specs/sys-specs/*

不生成业务文档，不补充页面交互规范，不额外引入新的工程目录。

验收标准

完成后应满足以下标准：

web/AGENTS.md 能独立说明前端工程规则、目录职责和文档入口。
.ai-specs 中存在足够覆盖当前项目前端工程问题的首批骨架文档。
任意新增页面、组件、接口、store、plugin 模块时，都能先在 AGENTS.md 和 .ai-specs 中定位规则。
文档内容不越界到业务设计，不与 server/AGENTS.md 的定位冲突。

实施顺序

新建 web/.ai-specs 目录与首批规范文档。
改写 web/AGENTS.md，引用并索引这些文档。
逐步在后续开发中按需细化单篇规范，但保持入口文档结构稳定。

6.5 KiB Raw Blame History Unescape Escape