# af-vue2-client 维护示例

以下为常见维护场景的步骤示例，按需查阅。需要代码风格、目录或技术栈细节时见 [reference.md](reference.md)。

---

## 示例 1：新增一个页面并配置路由

1. **新建页面目录与组件**（目录 kebab-case，组件 PascalCase）  
   - 在 `src/pages/` 下新建目录，如 `src/pages/demo-list/`。  
   - 新建 `DemoList.vue`，使用组合 API + `<script setup>`，按 [reference.md](reference.md) 的命名与导入顺序。

2. **配置路由**  
   - 静态路由：在 `src/router/index.js` 中增加对应 `path`、`name`、`component`（指向 `pages/demo-list/DemoList.vue`）。  
   - 动态/异步路由：在 `src/router/async/router.map.js` 或对应映射中增加菜单与路由配置。

3. **如需菜单**  
   - 在菜单配置（通常与路由映射或权限配置在一起）中增加该页的菜单项与 path/name 对应。

4. **验证**  
   - `npm run mac-serve` 或 `npm run serve` 启动，访问对应 path，确认页面与路由正常。

---

## 示例 2：提交前做 Lint 检查

1. **本地执行**  
   - 在项目根目录执行：`npm run lint` 或 `yarn lint`。  
   - 若有自动修复，保存后再跑一次直至无报错。

2. **使用技能自带脚本（可选）**  
   - 在项目根执行：`bash .claude/skills/af-vue2-client-maintainer/scripts/lint-check.sh`。  
   - 脚本以 lint 退出码退出：0 表示通过，非 0 表示未通过，需先修完再提交。

3. **发布前**  
   - 按 [reference.md](reference.md) 的发布检查清单，确保「代码检查：yarn lint 无错误通过」已勾选。

---

## 示例 3：发布版本（按 release 流程）

1. 更新 `package.json` 的 `version`。
2. 运行 `yarn lint`（或 `npm run lint`），确保通过。
3. 编辑 `CHANGELOG.md`：新增当前版本小节，写版本号、日期、更新内容；提交人用 `git config user.name`；格式参考已有条目。
4. 运行 `git status`，确认无未提交修改。
5. 提交：  
   `git add ... && git commit -m "发布 x.xx.xx\n\n- 条目1\n- 条目2"`  
   可按需加 emoji（✨🐛⚡🔧📝♻️🎨）。

详见 [reference.md](reference.md) 的「发布检查清单」与项目内 `.cursor/commands/release.md`。

---

## 示例 4：新增或调用一个 API 模块

1. **定义接口**  
   - 在 `src/services/api/` 下新增或修改模块（如 `demo.js`），使用 `apiService` 或项目约定的请求封装发起 HTTP 请求。

2. **在页面/组件中调用**  
   - 在页面中 `import` 该 API 模块，在组合 API 的 `setup` 中调用（如 `onMounted` 或事件处理函数内）。  
   - 数据转换如需统一模型，使用 `DataModel` 或项目约定的转换方式。

3. **错误处理**  
   - 依赖项目已有的 axios 拦截器做统一错误处理；如需页面级提示，使用 Ant Design Vue 的 `message` 或项目约定方式。

4. **联调与验证**  
   - 确认 `vue.config.js` 或对应环境的代理指向正确后端；启动开发服务后调通接口并检查数据与错误提示。

---

## 示例 5：用 X 组件做配置驱动的表单/表格

1. **准备 JSON 配置**  
   - 参考现有使用 XForm、XTable 的页面，准备 `columns`/`formConfig` 等 JSON（字段 key、title、type、rule 等）。

2. **在页面中挂载**  
   - 在页面中引入或使用全局已注册的 XForm、XTable，将配置通过 props 传入；如需数据，从 API 获取后绑定到对应 props。

3. **事件与提交**  
   - 按 X 组件文档或现有用法，监听提交/校验事件，在回调中调用 `apiService` 或具体 API 完成提交；错误用项目统一方式展示。

4. **样式**  
   - 如需覆盖样式，使用 Less，作用域限定在页面或组件内；主题变量从 `src/theme/` 引用。

---

需要更细的代码风格、目录说明或技术栈版本时，见 [reference.md](reference.md)。
