# 家谱 PC 前端交接

更新日期：2026-09-17

## 项目是什么

这是一个静态 HTML 多页面项目。页面直接加载 CSS 和 JavaScript，没有 React、Vue 或单页应用入口。

官网页面在根目录，例如 `index.html`、`login.html`、`genealogy.html`。登录后的个人中心和家谱功能页面以 `profile-` 开头。

## 主要目录

| 位置 | 用途 |
| --- | --- |
| 根目录 `*.html` | 各页面入口 |
| `public/css/` | 页面样式，`public.css` 是全局样式 |
| `public/js/` | 页面逻辑、公共交互和第三方脚本 |
| `public/images/` | 官网图片素材 |
| `utils/` | 请求、存储、表单和提示工具 |
| `config.js` | 前端接口配置 |
| `scripts/build-minified.mjs` | 构建脚本 |
| `dist/` | 构建产物；当前已清理，需要时重新构建 |

## 已清理内容

本次已删除测试文件、测试截图、临时接口响应、设计审查记录和旧文档。`dist/`、接口快照和 `package.json` 也已清理。仓库不再保留自动化测试，也没有 `npm test` 命令。

后续不要在仓库中保存测试截图、测试账号信息、接口返回样本或重复的过程记录。需要说明验证结果时，写在当前提交或任务交付里即可。

## 请求和登录

接口地址和请求封装在 `utils/ApiClient.js`、`utils/AxiosRequestUtil.js`、`config.js`。

页面不要直接发 Axios 请求，也不要在页面里拼接口地址。新增接口时先在 `ApiClient` 中统一定义，再由页面调用。

登录信息由 `StorageUtil.js` 管理。登录后的请求会携带 Bearer Token；401 会清除登录态并跳转到 `login.html`；403 保留登录态并显示无权限状态。

后端返回的长整型 ID 在浏览器里按字符串处理，避免数字精度丢失。

## 家谱业务规则

家谱业务必须使用真实的 `genealogyId`。没有家谱上下文时，应阻止请求或提示用户选择家谱，不能写死示例 ID。

接口字段、权限和接口是否存在，以 Apifox 的 PC 目录为准。不要从 APP 接口推测 PC 接口，也不要根据旧文件猜字段。

接口还缺少列表、详情或删除能力时，页面应保持禁用或提示状态，不要补造数据把入口打开。

## 常用位置

- 个人中心通用布局和导航：`public/js/profile-common.js`
- 个人中心样式：`public/css/profile.css`、`public/css/profile-module.css`
- 富文本编辑：`public/js/rich-editor.js`、`public/js/wangeditor5/`
- 附件上传：`public/js/attachment-editor.js`、`public/js/upload-pages.js`
- Layui 配置：`public/js/lay-config.js`

改公共样式或公共脚本前，先检查相关 `profile-*.html` 的引用，避免影响其他页面。

## 接手一个功能时

1. 找到页面入口、对应脚本和已有接口调用。
2. 在 Apifox 的 PC 目录确认请求方法、参数、响应字段和权限。
3. 修改请求封装和页面逻辑，保持加载、空数据、失败、无权限和禁用状态完整。
4. JavaScript 改动后执行 `node --check 路径/文件.js`，并在浏览器走通受影响页面。
5. 需要生成发布文件时执行 `node scripts/build-minified.mjs`。当前 `package.json` 已删除；如果后续重新引入 npm 脚本，需要同时恢复并维护对应配置。
6. 提交前执行 `git diff --check`，确认没有格式问题。

工作区可能有未提交修改。不要使用 `git reset --hard` 或 `git checkout --` 覆盖现有文件。