# 家谱创建首批 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在约一小时的首批施工中冻结剩余家谱生命周期 PC 请求契约，并把 `profile-create-family.html` 从 pending 预览改成可用的真实创建家谱页面。

**Architecture:** `utils/ApiClient.js` 唯一拥有请求路径和 body 白名单；`public/js/genealogy-entry-pages.js` 扩展家谱创建的纯构造、校验、响应规范化和页面初始化；现有 `region-pages.js` 负责三级地区选项，`upload-pages.js` 负责生成 `coverOssId`。创建成功后只使用响应中的稳定 `genealogyId` 跳转到家谱主页。

**Tech Stack:** 静态 HTML、原生 JavaScript UMD、Axios、Node `node:test`。

## Global Constraints

- 后端 `D:\WorkSpace\Java\Genealogy` 全程只读。
- 只调用 `/genealogy/pc/**`，不调用 APP 或后台管理接口。
- 不允许用户手填家谱 ID、申请 ID、用户 ID 或 OSS ID。
- 每个生产行为必须先有失败测试并实际运行 RED。
- 每个阶段完成后运行聚焦测试并更新 `docs/PC接口对接规划.md`。

---

### Task 1: 冻结家谱生命周期 ApiClient 契约

**Files:**
- Modify: `tests/api-client-contract.test.js`
- Modify: `utils/ApiClient.js`

**Interfaces:**
- Produces:
  - `createGenealogy(body)`
  - `applyToGenealogy(genealogyId, body)`
  - `myGenealogyJoinApplies()`
  - `pendingGenealogyJoinApplies(genealogyId)`
  - `auditGenealogyJoinApply(genealogyId, applyId, body)`
  - `cancelGenealogyJoinApply(applyId)`

- [x] **Step 1: 写失败的路径和 body 白名单测试**

测试固定以下请求：

```js
await client.createGenealogy({
  genealogyName: '汤氏家谱',
  surname: '汤',
  regionCode: '511622',
  coverOssId: '2062179707935264769',
  legacyField: 'drop'
});

await client.applyToGenealogy(genealogyId, {
  applicantName: '申请人',
  phone: '19100000000',
  relationDesc: '族亲',
  applyReason: '申请加入',
  inviterUserId: 'drop-without-safe-source'
});

await client.auditGenealogyJoinApply(genealogyId, applyId, {
  status: '1',
  auditRemark: '资料一致',
  legacyField: 'drop'
});
```

断言：

- 创建请求为 `POST /genealogy/pc/genealogies`，只保留 `genealogyName/surname/regionCode/ancestralHall/originPlace/addressDetail/coverOssId/intro/visibility/joinMode`。
- 加入请求为 `POST /genealogy/pc/genealogies/{genealogyId}/join-applies`，本轮安全 PC 页面只保留 `applicantName/phone/relationDesc/applyReason`，不发送没有安全来源的 `inviterUserId`。
- 我的申请、待审核、审核和撤销使用后端 PC Controller 的完整路径。
- 审核 body 只保留 `status/auditRemark`。
- 所有 path ID 拒绝不安全数字。

- [x] **Step 2: 运行 RED**

Run:

```powershell
node --test --test-name-pattern "genealogy lifecycle" tests/api-client-contract.test.js
```

Expected: FAIL，新方法尚不存在。

- [x] **Step 3: 最小实现方法和白名单**

使用现有 `request()`、`pickDefined()` 和 `toRequiredPathId()`；不增加兼容别名或 APP fallback。

- [x] **Step 4: 运行 GREEN**

Run:

```powershell
node --test tests/api-client-contract.test.js
node --check utils/ApiClient.js
```

Expected: PASS。

---

### Task 2: 家谱创建纯行为

**Files:**
- Modify: `tests/genealogy-entry-pages.test.js`
- Modify: `public/js/genealogy-entry-pages.js`

**Interfaces:**
- Consumes: `createGenealogy(body)`、`genealogyQuota()`
- Produces:
  - `buildGenealogyCreateBody(values)`
  - `validateGenealogyCreateBody(body)`
  - `normalizeCreatedGenealogy(item)`
  - `buildCreatedGenealogyUrl(item)`

- [x] **Step 1: 写失败的创建行为测试**

```js
assert.deepEqual(GenealogyEntryPages.buildGenealogyCreateBody({
  genealogyName: ' 汤氏家谱 ',
  surname: ' 汤 ',
  regionCode: '511622',
  ancestralHall: '',
  coverOssId: '2062179707935264769',
  visibility: '1',
  joinMode: '1',
  manualId: 'drop'
}), {
  genealogyName: '汤氏家谱',
  surname: '汤',
  regionCode: '511622',
  coverOssId: '2062179707935264769',
  visibility: '1',
  joinMode: '1'
});
```

同时断言：

- 缺少谱名、姓氏或地区时返回明确校验错误。
- `visibility` 只允许 `0/1/2`，`joinMode` 只允许 `0/1/2`。
- `coverOssId` 必须是安全字符串 ID；没有文件可省略。
- 额度 `createRemaining <= 0` 时阻止提交。
- 创建响应必须有稳定 `genealogyId`、谱名和姓氏。
- 跳转地址只能由响应 ID 产生：`profile-family-home.html?genealogyId=...`。

- [x] **Step 2: 运行 RED**

Run:

```powershell
node --test tests/genealogy-entry-pages.test.js
```

Expected: FAIL，纯函数不存在。

- [x] **Step 3: 最小实现纯函数**

严格构造 `AppGenealogyCreateBody`，可选空值省略，不读取页面外字段。

- [x] **Step 4: 运行 GREEN**

Run:

```powershell
node --test tests/genealogy-entry-pages.test.js
node --check public/js/genealogy-entry-pages.js
```

Expected: PASS。

---

### Task 3: 开放创建家谱页面

**Files:**
- Modify: `profile-create-family.html`
- Modify: `public/js/genealogy-entry-pages.js`
- Modify: `tests/genealogy-entry-pages.test.js`
- Modify: `tests/pending-pages.test.js`
- Modify: `tests/security-upload-scope.test.js`
- Modify: `tests/pc-scope.test.js`

**Interfaces:**
- Consumes: Task 1 和 Task 2、`RegionPages`、`UploadPages`
- Produces: `initGenealogyCreatePage()`

- [x] **Step 1: 写失败的页面测试**

断言页面：

- 不再包含 `data-feature-status="pending"` 和 `pending-pages.js`。
- 加载 `region-pages.js`、`md5.js`、`upload-pages.js` 和 `genealogy-entry-pages.js`。
- 存在隐藏 `coverOssId` 与文件选择控件，不能手填 OSS ID。
- 不存在 `genealogyId/applyId/inviterUserId` 输入。
- 表单只包含后端创建 DTO 字段和地区选择辅助字段。
- 创建按钮、状态区域和额度区域可由脚本控制。

- [x] **Step 2: 运行 RED**

Run:

```powershell
node --test tests/genealogy-entry-pages.test.js tests/pending-pages.test.js tests/security-upload-scope.test.js tests/pc-scope.test.js
```

Expected: FAIL，页面仍 pending 且缺上传/初始化行为。

- [x] **Step 3: 实现页面初始化和提交**

初始化顺序：

1. 校验登录态。
2. 调用 `genealogyQuota()` 并展示真实额度。
3. `RegionPages` 初始化三级地区。
4. `UploadPages` 通过 `data-upload-target` 把封面上传结果写入隐藏 `coverOssId`。
5. 提交前同步表单、构造并校验 body。
6. 使用 `writePending` 阻止重复提交。
7. 调用 `createGenealogy(body)`。
8. 规范化响应并跳转到真实家谱主页。

401 清登录态；403 保留登录态；业务错误显示在表单状态区域。

- [x] **Step 4: 运行 GREEN**

Run:

```powershell
node --test tests/genealogy-entry-pages.test.js tests/api-client-contract.test.js tests/pending-pages.test.js tests/security-upload-scope.test.js tests/pc-scope.test.js
node --check public/js/genealogy-entry-pages.js
```

Expected: PASS。

---

### Task 4: 首批收口

**Files:**
- Modify: `docs/PC接口对接规划.md`
- Modify: `docs/superpowers/plans/2026-07-29-genealogy-create-first-batch.md`

- [x] **Step 1: 更新契约和阶段状态**

记录 `AppGenealogyCreateBody`、`AppGenealogyVo`、额度、权限、上传派生字段、加入申请 ApiClient 契约及仍未开放的加入 UI。

- [x] **Step 2: 聚焦和全量验证**

Run:

```powershell
node --test tests/api-client-contract.test.js tests/genealogy-entry-pages.test.js tests/pending-pages.test.js tests/security-upload-scope.test.js tests/pc-scope.test.js
npm test
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
```

Expected: 全部 PASS。

- [x] **Step 3: 浏览器验证并报告**

使用真实账号验证创建页登录态、额度、地区加载、无手填 ID、控制台错误和提交前校验。不得为测试消耗真实创建额度；除非用户明确授权，不执行最终创建写操作。