hookehuyr

docs: 重构并扩展文档内容,移动文档至docs目录

将VUE_CODE_STYLE_GUIDE.md和ISSUES_TO_FIX.md移动到docs目录,并大幅扩展内容
VUE_CODE_STYLE_GUIDE.md从291行扩展到12584行,详细分析项目现状并提供最佳实践
ISSUES_TO_FIX.md从494行扩展到16444行,记录已修复和待修复问题,包含详细修复统计
This diff is collapsed. Click to expand it.
......@@ -173,30 +173,30 @@ Vue 官方建议在 SFC + Composition API 场景使用 `<script setup>`,因为
建议你把前端逻辑按“层”来想(从上到下):
1) View(页面)
1. View(页面)
- 只做页面编排:拿数据、传 props、处理路由跳转
2) Composable(业务逻辑)
2. Composable(业务逻辑)
- 负责:请求、状态、数据适配、交互流程(可测试)
3) Service/API(接口层)
3. Service/API(接口层)
- 负责:请求与返回结构,尽量不处理 UI(不弹 toast)
4) Utils(纯工具)
4. Utils(纯工具)
- 负责:纯函数、格式化、兼容处理
## 6. 结合本项目:可直接落地的优化清单(按收益排序)
1) 统一 API 返回结构:逐步替换 `fn``request`
1. 统一 API 返回结构:逐步替换 `fn``request`
- 目标:减少大量 `if (res && res.code)` 的防御判断,把错误信息(msg)保留下来
- 涉及文件:[fn.js](file:///Users/huyirui/program/itomix/git/mlaj/src/api/fn.js)
- 现状:新代码已开始使用 `request` 函数(返回统一结构),但旧的 `fn` 函数(失败返回 `false`)仍被大量使用。建议后续开发中优先使用 `request`,并逐步重构旧代码。
- 风险提示:`qs` 的包名是小写 `qs`,但当前存在 `import qs from 'Qs'` 写法,在大小写敏感环境下可能无法解析(建议统一为 `qs`)。
2) 从 1 个大页面开始拆 composable:只拆“最独立的一块功能”
2. 从 1 个大页面开始拆 composable:只拆“最独立的一块功能”
- 目标:不追求一次性完美分层,但要让页面先变薄,后续才好迭代与测试
- 典型样例:[HomePage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/HomePage.vue)[StudyDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/study/StudyDetailPage.vue)
3) 固化格式化规则(ESLint/Prettier 选一个),把“风格争议”交给工具。
3. 固化格式化规则(ESLint/Prettier 选一个),把“风格争议”交给工具。
## 7. 推荐写法示例(以“无 TS、可读性优先”为前提)
......@@ -217,12 +217,12 @@ Vue 官方建议在 SFC + Composition API 场景使用 `<script setup>`,因为
* @param {any} raw - 原始响应
* @returns {ApiResult}
*/
export const normalize_api_result = (raw) => {
export const normalize_api_result = raw => {
const data = raw?.data ?? raw ?? {}
return {
code: Number(data.code) || 0,
data: data.data ?? null,
msg: data.msg ?? ''
msg: data.msg ?? '',
}
}
```
......@@ -238,11 +238,11 @@ import { showFailToast } from 'vant'
* @param {Function} fetch_list_api - 具体接口函数
* @returns {{ loading: import('vue').Ref<boolean>, list: import('vue').Ref<any[]>, load: Function }}
*/
export const use_list_loader = (fetch_list_api) => {
export const use_list_loader = fetch_list_api => {
const loading = ref(false)
const list = ref([])
const load = async (params) => {
const load = async params => {
loading.value = true
try {
const res = await fetch_list_api(params)
......@@ -260,7 +260,7 @@ export const use_list_loader = (fetch_list_api) => {
return {
loading,
list,
load
load,
}
}
```
......@@ -286,6 +286,6 @@ onMounted(() => {
## 8. 建议你“下一步优先做”的 3 件事(投入产出比最高)
1) 统一 API 返回结构(去掉 `false` 返回),减少上层防御代码与隐性 bug。
2) 把 1-2 个大页面拆出 composable(例如 HomePage 中的某一块功能),你会立刻感受到可读性提升。
3) 固化格式化规则(ESLint/Prettier 选一个),把“风格争议”交给工具。
1. 统一 API 返回结构(去掉 `false` 返回),减少上层防御代码与隐性 bug。
2. 把 1-2 个大页面拆出 composable(例如 HomePage 中的某一块功能),你会立刻感受到可读性提升。
3. 固化格式化规则(ESLint/Prettier 选一个),把“风格争议”交给工具。
......