# 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 不明显时写一行；不写解释 WHAT 的注释。

## 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`。