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.
......@@ -94,9 +94,9 @@
推荐方向(渐进):
- 选择一个“单一事实来源”(推荐 Pinia store 或你现在的 context 之一),并定义清晰的数据流:
- store/context 是运行时状态
- localStorage 是持久化镜像(启动时 hydrate,一处写入)
- axios headers 从 store/context 派生(store 更新 -> 同步更新 headers)
- store/context 是运行时状态
- localStorage 是持久化镜像(启动时 hydrate,一处写入)
- axios headers 从 store/context 派生(store 更新 -> 同步更新 headers)
### 3.3 页面体积偏大:建议用 composables “分层”
......@@ -173,30 +173,30 @@ Vue 官方建议在 SFC + Composition API 场景使用 `<script setup>`,因为
建议你把前端逻辑按“层”来想(从上到下):
1) View(页面)
- 只做页面编排:拿数据、传 props、处理路由跳转
2) Composable(业务逻辑)
- 负责:请求、状态、数据适配、交互流程(可测试)
3) Service/API(接口层)
- 负责:请求与返回结构,尽量不处理 UI(不弹 toast)
4) Utils(纯工具)
- 负责:纯函数、格式化、兼容处理
1. View(页面)
- 只做页面编排:拿数据、传 props、处理路由跳转
2. Composable(业务逻辑)
- 负责:请求、状态、数据适配、交互流程(可测试)
3. Service/API(接口层)
- 负责:请求与返回结构,尽量不处理 UI(不弹 toast)
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,13 +217,13 @@ Vue 官方建议在 SFC + Composition API 场景使用 `<script setup>`,因为
* @param {any} raw - 原始响应
* @returns {ApiResult}
*/
export const normalize_api_result = (raw) => {
const data = raw?.data ?? raw ?? {}
return {
code: Number(data.code) || 0,
data: data.data ?? null,
msg: data.msg ?? ''
}
export const normalize_api_result = raw => {
const data = raw?.data ?? raw ?? {}
return {
code: Number(data.code) || 0,
data: data.data ?? null,
msg: data.msg ?? '',
}
}
```
......@@ -238,30 +238,30 @@ 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) => {
const loading = ref(false)
const list = ref([])
const load = async (params) => {
loading.value = true
try {
const res = await fetch_list_api(params)
if (res.code === 1) {
list.value = Array.isArray(res.data?.list) ? res.data.list : []
return true
}
showFailToast(res.msg || '加载失败')
return false
} finally {
loading.value = false
}
export const use_list_loader = fetch_list_api => {
const loading = ref(false)
const list = ref([])
const load = async params => {
loading.value = true
try {
const res = await fetch_list_api(params)
if (res.code === 1) {
list.value = Array.isArray(res.data?.list) ? res.data.list : []
return true
}
showFailToast(res.msg || '加载失败')
return false
} finally {
loading.value = false
}
}
return {
loading,
list,
load
}
return {
loading,
list,
load,
}
}
```
......@@ -279,13 +279,13 @@ useTitle('消息列表')
const { loading, list, load } = use_list_loader(getNewsListAPI)
onMounted(() => {
load({ page: 1, limit: 10 })
load({ page: 1, limit: 10 })
})
</script>
```
## 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 选一个),把“风格争议”交给工具。
......