guzhi/.trae/documents/项目结构整理与架构文档（web目录）.md

工作范围与目标

• 范围：梳理 web 目录（排除 web1），形成结构与架构产物
• 目标：
  • 生成完整项目结构文档（目录树、职责说明、关键路径）
  • 制作技术架构示意图（前端分层、运行时链路、对后端的调用关系）
  • 编写关键模块说明文档（路由、状态、鉴权、HTTP、页面域）
  • 预留接口说明，支撑后续开发接入

技术栈识别

• 框架：Vue 3（web/package.json:37），构建：Vite（web/package.json:43，web/vite.config.js:1）
• 路由：vue-router@4（web/package.json:39）；守卫统一注册（web/src/router/guard/index.js:5-9）
• 状态：Pinia（web/package.json:26，web/src/store/index.js:1-5）
• UI 与样式：Naive UI（web/package.json:25），UnoCSS（web/package.json:30，web/src/main.js:3），全局样式（web/src/styles/global.scss）
• 国际化：vue-i18n（web/package.json:38，web/src/main.js:22，web/i18n/index.js）
• 网络：Axios（web/package.json:20），自建请求封装（web/src/utils/http/index.js:4-18）与拦截器（web/src/utils/http/interceptors.js:23-33,35-59）
• 运行环境：.env.* 配置，开发代理到后端 127.0.0.1:9999 的 /api/v1（web/.env.development:8，web/build/constant.js:19-22，web/vite.config.js:31-35）

项目结构综述

• 顶层关键目录：
  • build/：Vite 定制化（定义、插件、脚本、代理）（web/build/*）
  • i18n/：国际化资源与实例（web/i18n/index.js，web/i18n/messages/*）
  • settings/：主题与全局设置（web/settings/theme.json，web/settings/index.js）
  • public/：静态资源与加载占位（web/public/resource/*）
  • src/：业务主目录（见下）
• src/ 结构与职责：
  • 入口与应用：main.js（应用装配，挂载插件）（web/src/main.js:14-23），App.vue
  • 路由：router/（基本路由、动态路由、守卫、滚动）（web/src/router/index.js:7-18,30-55）
  • 状态：store/（Pinia 注册与模块聚合）（web/src/store/index.js:1-5，web/src/store/modules/index.js:1-4）
  • 组件：components/（通用、表格、查询栏、图标、页面容器）
  • 视图：views/（系统管理、估值评估、交易开票、登录、工作台等域）
  • 工具：utils/（鉴权、存储、HTTP、通用工具）（web/src/utils/*）
  • 指令：directives/（权限等自定义指令）
  • 可复用逻辑：composables/（如 useCRUD）
  • 样式：styles/（Reset、全局样式，UnoCSS 原子类）

核心模块与功能点

• 鉴权与导航：
  • 登录白名单与重定向（web/src/router/guard/auth-guard.js:3-16）
  • 动态路由注入、用户与权限联动（web/src/router/index.js:30-55）
• 状态管理：
  • 用户信息获取、登出流程（web/src/store/modules/user/index.js:37-60）
  • 标签、权限、应用模块聚合（web/src/store/modules/index.js:1-4）
• 网络与错误处理：
  • request 实例与 baseURL 环境绑定（web/src/utils/http/index.js:17-19）
  • 成功码约定 code === 200、统一错误提示（web/src/utils/http/interceptors.js:23-33）
  • 401 处理与自动登出（web/src/utils/http/interceptors.js:45-53）
• 业务域：
  • 系统管理（用户、角色、菜单、部门、审计日志）（web/src/views/system/*，API 汇总：web/src/api/index.js:393-431）
  • 客户端用户管理、开票记录、估值评估（web/src/views/user-management/*，web/src/views/transaction/invoice/*，web/src/views/valuation/*；对应 API：web/src/api/index.js）
• UI 框架与布局：
  • 布局与头部/侧栏/标签页组件（web/src/layout/*）
  • Naive UI 组件与 UnoCSS 原子化样式协同

技术架构示意图

graph TD
  U[用户] --> A[Vue 应用]
  A --> R[Router]
  A --> S[Pinia]
  A --> V[视图与组件]
  V --> UI[Naive UI / UnoCSS]
  A --> I18N[vue-i18n]
  S --> H[HTTP 封装]
  R --> G[路由守卫]
  H --> X[Axios 拦截器]
  X --> B[(后端 API /api/v1)]
  subgraph 构建与运行
    Vite[Vite Dev/Build]
  end
  A --> Vite

文档产出方案

• 目录与位置：在 web/docs/ 下生成 4 个文档，统一中文、层级清晰、可落地
  • 项目结构.md：目录树 + 角色说明 + 入口与关键路径
  • 技术架构.md：架构分层 + 运行链路 + Mermaid 图
  • 关键模块说明.md：路由、状态、HTTP、业务域的职责与协作
  • 接口约定与预留.md：环境、鉴权、响应约定、扩展接入指引
• 文档格式约定：
  • 标题层级：H1 总览，H2 模块，H3 文件与职责；统一术语与中文阐述
  • 代码引用统一用内联反引号与文件定位（如 web/src/router/index.js:30-55）

接口预留说明（用于后续开发）

• 基础约定：
  • baseURL：VITE_BASE_API（默认 /api/v1，web/.env.development:8）
  • 认证头：token（由拦截器自动注入，web/src/utils/http/interceptors.js:11-14）
  • 成功响应：{ code: 200, data, msg }（web/src/utils/http/interceptors.js:23-33）
• 接入方式：在 web/src/api/index.js 中以函数方式声明对应业务端点，统一走 request
• 错误处理：全局弹窗与 401 自动登出链路已就绪（web/src/utils/http/interceptors.js:45-53）

执行步骤

1. 固化目录树与职责说明，输出《项目结构.md》
2. 绘制 Mermaid 架构图并输出《技术架构.md》
3. 编写《关键模块说明.md》，覆盖路由、状态、HTTP、页面域
4. 编写《接口约定与预留.md》，包含新增接口接入模板与约束
5. 交付文档后，等待新需求文档，启动开发

输出验收与规范

• 文档格式：统一中文，标题层级一致，引用路径与行号定位
• 风格一致：术语与代码片段与现有实现保持一致（如 request、useUserStore）
• 可演进：接口文档预留扩展章节，支持后续模块按同规范接入

——请确认以上方案，确认后我将按该方案生成 4 个文档并提交供评审。