# 前端工程：页面状态、真实 API 与生活手册设计

前一站：[评论与关系](comments-relations.md) · 接着读：[从零实现](from-zero.md)

## 先知道每个文件

| 文件 | 作用 |
| --- | --- |
| `frontend/index.html` | 文档标题、root 容器和入口脚本 |
| `src/main.tsx` | 创建 React root、加载全局与品牌样式 |
| `src/App.tsx` | 屏幕切换、登录、首页、详情、编辑、个人页、搜索、设置和后台 |
| `src/api.ts` | fetch、token、超时、错误、统一解包、401事件 |
| `src/types.ts` | 请求/响应相关类型 |
| `src/mock.ts` | 仅显式开启原型演示时使用的数据 |
| `src/styles.css` | 原有组件的基础布局 |
| `src/journal.css` | 本次生活手册品牌层和响应式调整 |
| `public/assets` | 默认本地摄影和头像 |
| `vite.config.ts` | React 插件、开发代理、固定本机监听 |

当前采用 App 内屏幕状态，没有新引入路由库。刷新会回到默认首页，token仍恢复登录；它不承诺每篇笔记有可直接分享的独立 URL。未来引入路由应同时处理浏览器后退、刷新、加载权限和404。

## React 的四个概念

组件是返回页面的函数，例如 NoteCard。props 是上层传入的数据和动作；state 是本组件会变化的数据；effect 在挂载或依赖变化后与外部系统同步。`useState([])` 保存笔记，`setNotes` 触发重新渲染；不能直接改数组然后期待页面知道。

`useEffect` 不是“任意代码都放进去”的容器。首页请求依赖页签、页码和登录状态，清理函数让旧请求结果不覆盖已切换页签。React StrictMode 开发时可能额外运行 effect 检查清理，因此网络看到两次初始读取并不一定是业务重复写入。

## 请求封装的真实数据结构

request 设置 Accept、JSON 或 FormData 请求格式，附带 token，15秒AbortController超时，验证响应是 JSON，检查 HTTP 状态与 success，返回业务 data。FormData 不手动写 Content-Type，因为浏览器需要自动加 boundary。

401 清理失效 token 并派发 session-expired，App 切回首页和提示登录。网络错误不会静默返回 demoNotes。发布与修改返回 Note，页面拿真实 ID；资料更新返回 Profile，因此实际头像 URL 替换本地 blob 预览。

## 页面的几个边界

发现推荐、关注、最新使用同一真实搜索入口；关注需要登录，空态给出下一步。搜索区分笔记/用户，筛选枚举统一映射；个人笔记使用 cursor；评论、关系和搜索用页码。用户不能因为一个列表只加载了20条就误以为总共只有20条。

详情点赞和收藏乐观更新，失败回滚。加载详情的 effect 依赖笔记 ID 和登录状态，不能每次按钮改变对象引用就重读旧状态覆盖刚刚的操作。删除和私密后，列表重新读取后端，不能只本地隐藏却让直接请求继续成功。

## 视觉 skill 的应用

参考文件在 `third_party/skills/frontend-design`，来源和许可在[第三方说明](../../third_party/ASSETS.md)。先写[视觉方案](../00-overview/design-plan.md)再实现：蓝色书脊、摄影主导、黄色便签集中表达个性；删除轨道装饰和大面积渐变；标题不靠单词变色制造层次。

桌面4列、平板3/2列、手机2列；小屏首屏重排拼贴；主题入口可横向滚动但整页不溢出。字号、留白、作者行和图片裁切共同决定层级，不能只把按钮换成另一种蓝色就说完成设计。

## 可访问性和安全

所有交互保留键盘焦点，卡片可 Enter/Space 激活，内层按钮事件不误触整张卡。弹窗声明 dialog/aria-modal，Escape关闭；反馈使用 role=status；减少动画媒体查询禁用非必要运动。标题和昵称用 JSX 文本，不直接插入服务端 HTML。图片带 alt，失败头像回本地资源且移除重复 onError 防循环。

## 构建与联调

```powershell
npm.cmd ci --prefix frontend
npm.cmd run build --prefix frontend
```

构建包括 TypeScript 严格检查；依赖的 peer 兼容不等于页面行为正确，仍需浏览器上传、发布、评论与后台检查。截图保存在 `docs/reports/screenshots`；实际通过范围以验证报告为准。
