4.6 KiB
4.6 KiB
abacus-static-framework — 开发规范（CONVENTIONS）
命名、目录、提交、风格、测试的权威（本仓库视角）。前后端共享约束见工作区
docs/coding-standards.md（../../../../docs/coding-standards.md），本文只写前端特有内容 + 指针，禁止复制 docs/ 正文。
0. 阅读指引
- 适用范围：
src/subsystem/**业务开发（src/framework/**只读）。 - 分工：ARCHITECTURE 管"拆成什么模块"；本文管"怎么命名/写"；共享编码规范、接口契约、AI 生成工作流在
docs/coding-standards.md。
1. 命名
1.1 标识符
- 组件名：PascalCase，且必须与路由
name一致（<script lang="ts">export default { name: 'Xxx' }</script>）。 - 文件/目录：kebab-case（如
operationLog/index.vue）；views 目录按一级/二级菜单名组织。 - API 函数：
getXxx/saveXxx/deleteXxx/exportXxx。 - Pinia store：
use<Xxx>Store。
1.2 模块命名（语义禁区）
- 禁止
Manager/Helper/Util/Common/Misc/Tools这类语义为空的名字；用"动词+名词"（如useTableQueryReload、gridDefaultProps）。
1.3 文件 / 1.4 目录 / 1.5 资产命名
- 文件按主类型命名：页面
index.vue（views 目录内）、API 按 Controller 分api/<服务别名>/<模块>.ts、组合式函数use<Xxx>.ts。 - 目录：
api/<服务别名>/、views/<一级菜单>/<二级菜单>/、router/、extend/；业务自建components/ hooks/ store/ styles/ types/ utils/。 - 资产：图标/图片放
src/assets/或public/（按是否需编译/保持原名选择）。
1.6 字符串与本地化
- 用户可见文案用中文；菜单标题在路由
meta.title与后端菜单保持一致。
2. 代码风格
2.1 排版
- TypeScript / Vue：2 空格缩进；单行 ≤ 120 字符；
<script setup>+ 选项式name。 - 已配置
unplugin-auto-import（vue/vue-router/@vueuse/core + Element Plus resolver）：禁止手动 import 这些自动导入项。
2.2 分层纪律
- 页面组件只消费状态/发请求（经
api/封装），不直接拼 URL、不裸 axios（见共享规范 §4.3/§6）。 - 业务通用逻辑抽
hooks/；跨页面共享状态抽store/；数据模型类型保持薄。
2.3 并发 / 2.4 错误处理
- 并发：请求层已处理 token 刷新并发队列；页面不自行管理并发刷新。
- 错误：由 request.ts 统一弹窗（9xx 业务 / 5xx 系统 / 401/429/503）；页面只需处理成功分支与局部提示。
2.5 注释
- 每个方法/函数必须写一行职责注释（便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。
3. 提交规范
3.1 Commit message 风格
Conventional Commits：type(scope): subject。允许 type：feat / fix / docs / refactor / test / chore。例：feat(sms): 新增操作日志查询页面。
3.2 提交粒度 / 3.3 工作区纪律 / 3.4 分支模型
- 一次提交一个目的；不在脏工作区叠加不相关改动。
- 分支模型：主干 + 短命功能分支（按需，单人开发可直推主干）。
- 本仓库属于工作区单一 git 仓库（
D:\workBuddySpace\member）；纯前端改动 commit 限定本目录，跨项目改动（docs/）单独 commit。
3.5 实施日志
- 规则见
VIBECODING_GUIDE §5：每个可独立验收的部分写.project.agents/log/YYYY-MM-DD-<slug>.md。
4. 测试策略
4.1 框架 / 4.2 必须有测试的模块
- 无自动化测试框架（PRD 决策）；人工冒烟覆盖：列表查询、表单增改、导出、权限路由。
4.3 必须真机/真环境验证
- 涉及后端联动的场景：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移——mock/模拟器不算数。
5. 与上游文档的同步矩阵
| 变更点 | 必须同步更新 |
|---|---|
| 新增/改动页面功能 | PRD.md（功能定义）；共享规范如有涉及先改 docs/coding-standards.md |
| 新增模块/目录/依赖方向 | 本仓库 ARCHITECTURE.md §2+§3 |
| 改 request/gridDefaultProps 等对外签名 | ARCHITECTURE.md §3.2 + docs/coding-standards.md §6 |
| UI/视觉 token | 本仓库 UIUX.md |
6. 不在本文范围（明确划清）
- 模块拆分归
ARCHITECTURE.md；行为/范围归PRD.md；前后端共享约束（接口契约/异常码/分页/APP_NAME）归docs/coding-standards.md；视觉细节归UIUX.md。 - 多租户 SaaS 隔离与前后端协作归
docs/architecture.md §7；编码强制约束归docs/coding-standards.md §9（前端落地见本仓库ARCHITECTURE.md §10）。