邹方成
cc352d3184
refactor: 优化API路由和响应模型 feat(admin): 添加App用户管理接口 feat(sms): 实现阿里云短信服务集成 feat(email): 添加SMTP邮件发送功能 feat(upload): 支持文件上传接口 feat(rate-limiter): 实现手机号限流器 fix: 修复计算步骤入库问题 docs: 更新API文档和测试计划 chore: 更新依赖和配置
103 lines
6.0 KiB
Markdown
103 lines
6.0 KiB
Markdown
## 工作范围与目标
|
||
- 范围：梳理 `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 原子化样式协同
|
||
|
||
## 技术架构示意图
|
||
```mermaid
|
||
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 个文档并提交供评审。 |