85 lines
5.5 KiB
Markdown
85 lines
5.5 KiB
Markdown
# abacus-static-framework — 产品需求文档（PRD）
|
||
|
||
> 行为与范围的**唯一权威**。功能的加/删/改必须先改本文，再动代码与下游文档。
|
||
> 本文回答"做什么 / 给谁 / 为什么"，不回答"怎么实现"（那是 `ARCHITECTURE.md`）。
|
||
|
||
## 1. 产品愿景
|
||
|
||
为 abacus 微服务体系提供**可复用的企业级 Vue 3 前端底座**：业务团队（人 + AI）只需在 `src/subsystem/**` 编写业务页面与接口封装，即可获得统一的菜单框架、权限路由、请求管线（统一响应体/服务别名/token 刷新）与标准 UI 组件，实现跨系统一致的前端体验与低成本复制开发。
|
||
|
||
## 2. 目标用户与典型场景
|
||
|
||
- 用户画像：公司内部业务系统开发团队（前端开发、全栈、AI 辅助开发人员）。
|
||
- 场景 1：作为业务开发，我想在底座上复制 `subsystem` 示例新建一个业务子系统，以便快速产出与既有系统风格一致的页面。
|
||
- 场景 2：作为 AI 助手，我想依据 `docs/coding-standards.md` 把用户给出的界面直接生成前后端代码，以便无需逐条追问技术细节。
|
||
- 场景 3：作为框架负责人，我想保证所有子系统的 UI 组件与交互模式统一，以便降低维护成本与学习成本。
|
||
|
||
## 3. 范围（Scope）
|
||
|
||
### 3.1 MVP 必含（In Scope）
|
||
- 菜单框架与动态路由/权限（后端菜单 → `filterAsyncRoutes` 匹配 → `addRoute`）。
|
||
- 请求管线：统一响应体解包、URL 服务别名映射、token 自动刷新（并发队列）、commonParam 审计头、Excel ArrayBuffer 分支。
|
||
- 标准组件与工具（`framework/components/standard` 10 项、`framework/utils/standard` 5 项）。
|
||
- `src/subsystem` 业务开发模板（sms 示例：api / dynamicRouter / views / extend）。
|
||
- 治理体系：`.project.agents/`（CLAUDE/AGENTS/SELF_CONSTRAINTS/VIBECODING_GUIDE + context 文档）。
|
||
|
||
### 3.2 明确不做（Out of Scope）
|
||
- 不包含具体业务功能（业务只存在于 `src/subsystem/**` 的复制改写）。
|
||
- 不提供单元测试框架与 CI 流水线（人工冒烟验证）。
|
||
- 不维护后端逻辑（后端属 `abacus.springboot.example` 仓库）。
|
||
|
||
## 4. 核心功能定义
|
||
|
||
### 4.1 菜单框架与权限路由（【核心】）
|
||
- **用户故事**：作为业务用户，我想登录后只看到有权限的菜单并直达页面，以便安全高效地工作。
|
||
- **行为**：`permissionStore.generateRoutes` 拉取后端菜单，按 `url === path` 与 `subsystem/router/dynamicRouter.ts` 匹配，过滤后 `router.addRoute`。
|
||
- **边界 / 异常**：菜单数据未注册 → 页面不可见；`public/data/data.js` 的 `currentSubsystem` 决定当前子系统。
|
||
|
||
### 4.2 请求管线（【核心】）
|
||
- **用户故事**：作为业务开发者，我想只写 URL 与参数就能完成带鉴权、带审计的接口调用，以便不重复处理公共逻辑。
|
||
- **行为**：`framework/utils/request.ts` 强制：服务别名映射（`settingsStore.backendServices`）、`status===200` 自动解包 `data`、token 剩余 <10 分钟自动刷新并重放并发请求、自动携带 `commonParam`。
|
||
- **边界 / 异常**：业务异常码首位 9、系统异常码首位 5 统一弹窗提示；ArrayBuffer（Excel）不解包返回整个 response；HTTP 401 跳登录。
|
||
|
||
### 4.3 标准组件与工具（【核心】）
|
||
- **用户故事**：作为业务开发，我想优先使用框架标准件，以便页面风格统一且少写重复代码。
|
||
- **行为**：UI 优先级 standard 组件 > vxe-table（仅表格）> Element Plus > 自研（泛用性高需提交框架负责人）；工具同理。
|
||
- **边界 / 异常**：自研组件不得长期只存在于单个业务内。
|
||
|
||
## 5. 信息架构与导航
|
||
|
||
顶层为菜单框架（一级菜单 → 二级菜单 → `views/<一级>/<二级>/index.vue`）；`dynamicRouter.ts` 是业务路由唯一注册点；子系统编码由 `public/data/data.js` 声明；开发期经 `vite.config.ts server.proxy` 反代后端。
|
||
|
||
## 6. 数据模型（概念级）
|
||
|
||
前端无持久化业务实体；运行时状态：用户登录信息（token/user）、菜单与路由（permissionStore）、服务别名映射（settingsStore.backendServices）、业务域（getCurrentBusinessDomain）。
|
||
|
||
## 7. 非功能性需求
|
||
|
||
- 构建产物直接输出到后端微服务 `resources/html/vue/<应用名>/`，随 `*-bin.zip` 一起发布（动静分离）。
|
||
- 请求超时 50s；上传限制由后端 multipart 控制（50MB）。
|
||
- 框架升级不覆盖 `public`、`vite.config.ts`、`src/subsystem`。
|
||
|
||
## 8. 国际化与文案语气
|
||
|
||
中文为主；用户可见文案使用统一中文，保持简洁、操作导向；禁止硬编码无意义字符串。
|
||
|
||
## 9. 隐私与合规
|
||
|
||
前端不收集个人数据；仅透传后端鉴权与业务域信息（commonParam）；无上报逻辑。
|
||
|
||
## 10. 风险与缓解
|
||
|
||
- **APP_NAME 四处漏配静默失败**：按共享规范 §3 四联检（`bootstrap.yml`/扫描包/URL 首段/outDir）。
|
||
- **框架升级覆盖业务**：升级前备份 `public`、`vite.config.ts`、`src/subsystem`。
|
||
- **自研组件碎片化**：泛用组件必须走框架评审入库。
|
||
|
||
## 11. 发布里程碑（建议，待路线图细化）
|
||
|
||
- M0：治理与规范落地（本次已完成）。
|
||
- M1+：按 `ROADMAP.md` 以第一个业务子系统复制改写验证模板可复制性。
|
||
|
||
## 12. 假设与待澄清项（复核时请逐条回应）
|
||
|
||
- Q1. 是否所有新业务子系统都采用"复制 sms 示例 + 改写"的方式起步？（默认：是）
|
||
- Q2. 是否引入前端单元测试（如 Vitest）？（默认：否，人工冒烟）
|