jiapu/docs/superpowers/plans/2026-07-11-pc-endpoint-page-coverage.md

# PC Endpoint Page Coverage 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:** Make every callable operation in `genealogy-pc-openapi.yaml` traceable to a real PC page flow, an automated regression test, and a manual acceptance step.

**Architecture:** `utils/ApiClient.js` remains the sole network contract owner. Page modules in `public/js` own input validation, loading and success/error state; `tests` prove their request and navigation behavior. The coverage matrix distinguishes a complete user flow from an endpoint that is documented but lacks the contract required to expose it safely.

**Tech Stack:** Static HTML, browser JavaScript, Axios, Layui, Node `assert` tests.

## Global Constraints

- Runtime API base URL is owned only by `config.js`: `http://182.61.18.23:8080`.
- Only PC/H5 routes and scenes defined by `genealogy-pc-openapi.yaml` may be requested.
- Registration never persists a token; password and SMS login persist the returned token and navigate to `profile.html`.
- Logout, unauthenticated profile access and account deactivation navigate to `index.html`.
- Every behavior change starts with a failing Node test and ends with focused plus full test verification.
- No page invents a business table name, business ID, CAPTCHA scene or legacy captcha submission field that is not in the PC contract.

## Endpoint Matrix

| Operation | Page owner | Automated test | Manual acceptance order | Status target |
| --- | --- | --- | --- | --- |
| `GET /captcha/require` | `CaptchaPages` on auth forms | `tests/captcha-pages.test.js` | 1-4 | Complete |
| `POST /captcha/challenge` | `CaptchaPages` on auth forms | `tests/captcha-pages.test.js` | 1-4 | Complete |
| `POST /captcha/verify` | `CaptchaPages` on auth forms | `tests/captcha-pages.test.js` | 1-4 | Complete |
| `GET /auth/code` | no safe consumer | `tests/pc-endpoint-coverage.test.js` | blocked | Backend contract required |
| Register, password login, SMS login, SMS code | `register.html`, `login.html` | `tests/auth-pages.test.js`, `tests/api-client.test.js` | 1-3 | Complete |
| Profile read/update | `profile.html`, `profile-data.html` | `tests/profile-pages.test.js` | 4-5 | Complete |
| Password reset | `forgot-password.html` | `tests/auth-pages.test.js` | 6 | Complete |
| Password change, logout, account deactivation | `profile-security.html` | `tests/security-pages.test.js` | 7-9 | Complete |
| Phone change | `profile-security.html` | `tests/security-pages.test.js` | blocked | PC/H5 phone SMS scene required |
| Single upload | profile avatar and existing upload fields | `tests/upload-pages.test.js` | 10 | Complete |
| Resumable init/chunk/complete | same file input for large files | `tests/upload-pages.test.js`, `tests/api-client.test.js` | 11 | Complete |
| File reference bind/release | no safe business entity contract | `tests/pc-endpoint-coverage.test.js` | blocked | PC business table and ID contract required |
| Region children/path/search/detail | profile address picker and region search control | `tests/region-pages.test.js`, `tests/profile-pages.test.js` | 12 | Complete |

## Task 1: Enforce Endpoint Coverage

**Files:**
- Create: `tests/pc-endpoint-coverage.test.js`
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`

**Interfaces:**
- Consumes: the 25 operations declared under `paths` in `genealogy-pc-openapi.yaml`.
- Produces: a test-owned `ENDPOINTS` list that assigns every operation one of `complete` or `blocked` with a page/test owner.

- [ ] **Step 1: Write the failing coverage test**

```js
assert.deepStrictEqual(missingOperations, []);
assert.deepStrictEqual(unownedOperations, []);
assert.deepStrictEqual(unsupportedBlockedOperations, []);
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `node tests\pc-endpoint-coverage.test.js`

Expected: failure listing the endpoint operations without a page/test/blocker owner.

- [ ] **Step 3: Add the explicit 25-operation matrix**

```js
const ENDPOINTS = {
  'GET /captcha/require': { page: 'auth', test: 'captcha-pages', status: 'complete' },
  'GET /auth/code': { status: 'blocked', reason: 'legacy captcha has no PC request field' }
};
```

- [ ] **Step 4: Run the test to verify it passes**

Run: `node tests\pc-endpoint-coverage.test.js`

Expected: `pc-endpoint-coverage tests passed`.

## Task 2: Complete and Test the Auth Journey

**Files:**
- Modify: `public/js/auth-pages.js`
- Modify: `public/js/profile-pages.js`
- Modify: `public/js/security-pages.js`
- Modify: `tests/auth-pages.test.js`
- Modify: `tests/profile-pages.test.js`
- Modify: `tests/security-pages.test.js`

**Interfaces:**
- Consumes: `GenealogyApi.login`, `loginBySms`, `register`, `sendSmsCode`, `resetPassword`, `getProfile`, `updateProfile`, `changePassword`, `deactivateAccount`, and `logout`.
- Produces: consistent form validation, token state and redirect behavior for the acceptance steps 1-9.

- [ ] **Step 1: Write failing redirect and request tests**

```js
assert.strictEqual(loginRoot.location.href, 'profile.html');
assert.strictEqual(registerRoot.location.href, 'login.html');
assert.strictEqual(logoutRoot.location.href, 'index.html');
```

- [ ] **Step 2: Run focused tests to verify failure**

Run: `node tests\auth-pages.test.js; node tests\profile-pages.test.js; node tests\security-pages.test.js`

Expected: a failure naming the missing flow or redirect.

- [ ] **Step 3: Implement only the missing flow branch in its page module**

```js
await api.loginBySms(buildSmsLoginBody(values));
root.location.href = 'profile.html';
```

Use the corresponding documented endpoint method for each form; do not create a second token store or a page-local route string owner.

- [ ] **Step 4: Run focused tests**

Run: `node tests\auth-pages.test.js; node tests\profile-pages.test.js; node tests\security-pages.test.js`

Expected: all three scripts print their pass messages.

## Task 3: Make Region Search, Path and Detail Usable

**Files:**
- Modify: `profile-data.html`
- Modify: `public/js/region-pages.js`
- Modify: `tests/region-pages.test.js`

**Interfaces:**
- Consumes: `regionChildren(parentCode)`, `regionSearch({ keyword })`, `regionPath(regionCode)`, and `regionDetail(regionCode)`.
- Produces: a profile-address picker that can search by name/code, select a result, resolve its path and write province/city/district codes before profile save.

- [ ] **Step 1: Write a failing result-normalization and selected-path test**

```js
assert.deepStrictEqual(RegionPages.buildRegionSelection(result), {
  provinceCode: '510000',
  cityCode: '510100',
  districtCode: '510104'
});
```

- [ ] **Step 2: Run the focused test to verify failure**

Run: `node tests\region-pages.test.js`

Expected: failure because `buildRegionSelection` is not exported.

- [ ] **Step 3: Add the profile search control and selection behavior**

```js
var path = await api.regionPath(regionCode);
var selection = buildRegionSelection(path);
applyRegionSelection(picker, selection);
await api.regionDetail(regionCode);
```

- [ ] **Step 4: Run focused tests**

Run: `node tests\region-pages.test.js; node tests\profile-pages.test.js`

Expected: both scripts print their pass messages.

## Task 4: Complete Single and Resumable File Upload

**Files:**
- Modify: `public/js/upload-pages.js`
- Modify: `utils/ApiClient.js`
- Modify: `tests/upload-pages.test.js`
- Modify: `tests/api-client.test.js`

**Interfaces:**
- Consumes: `uploadFile(file)`, `initResumableUpload(body)`, `uploadChunk(body)`, `completeResumableUpload(body)`.
- Produces: `uploadFileForPage(file, options)` which uses single upload for files at or below the configured threshold and the init/chunk/complete sequence for larger files.

- [ ] **Step 1: Write failing upload-strategy tests**

```js
assert.strictEqual(UploadPages.getUploadMode({ size: 1024 }, 4194304), 'single');
assert.strictEqual(UploadPages.getUploadMode({ size: 4194305 }, 4194304), 'resumable');
```

- [ ] **Step 2: Run focused tests to verify failure**

Run: `node tests\upload-pages.test.js; node tests\api-client.test.js`

Expected: failure because `getUploadMode` does not exist.

- [ ] **Step 3: Implement sequential resumable upload**

```js
var init = await api.initResumableUpload(initBody);
for (index = 0; index < chunks.length; index += 1) {
  await api.uploadChunk({ uploadId: init.uploadId, chunkIndex: index, chunkMd5: chunkMd5, file: chunks[index] });
}
return api.completeResumableUpload({ uploadId: init.uploadId, fileMd5: fileMd5, fileSize: file.size });
```

- [ ] **Step 4: Run focused tests**

Run: `node tests\upload-pages.test.js; node tests\api-client.test.js`

Expected: both scripts print their pass messages.

## Task 5: Record and Enforce Backend-Contract Blocks

**Files:**
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`
- Modify: `tests/pc-endpoint-coverage.test.js`

**Interfaces:**
- Consumes: the legacy captcha response, phone SMS scene requirements, and file-reference required business fields from the PC YAML.
- Produces: three named blocked operations with an exact missing backend input and no speculative page request.

- [ ] **Step 1: Assert exact blocker reasons**

```js
assert.strictEqual(ENDPOINTS['GET /auth/code'].reason, 'legacy captcha has no PC request field');
assert.strictEqual(ENDPOINTS['PUT /genealogy/pc/auth/phone'].reason, 'PC/H5 phone SMS scene is not documented');
assert.strictEqual(ENDPOINTS['POST /genealogy/pc/files/reference'].reason, 'PC business table and ID contract is not documented');
```

- [ ] **Step 2: Run the test to verify failure**

Run: `node tests\pc-endpoint-coverage.test.js`

Expected: failure until all three reasons are explicit.

- [ ] **Step 3: Update the tracker without adding a fake request**

```md
| Blocked operation | Missing backend contract | Page behavior |
| --- | --- | --- |
| `GET /auth/code` | legacy code submission field | no page action |
```

- [ ] **Step 4: Run the test to verify it passes**

Run: `node tests\pc-endpoint-coverage.test.js`

Expected: `pc-endpoint-coverage tests passed`.

## Task 6: Final Verification and User Test Script

**Files:**
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`

- [ ] **Step 1: Run syntax checks**

Run: `node --check utils\ApiClient.js`

Run: `node --check public\js\auth-pages.js`

Run: `node --check public\js\region-pages.js`

Run: `node --check public\js\upload-pages.js`

Expected: each command exits with code 0.

- [ ] **Step 2: Run the complete Node suite**

Run: `Get-ChildItem -Path tests -Filter *.test.js | ForEach-Object { & node $_.FullName; if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } }`

Expected: every test file prints its pass message.

- [ ] **Step 3: Check the diff**

Run: `git diff --check`

Expected: exit code 0; CRLF conversion notices are informational only.

- [ ] **Step 4: Record manual acceptance steps**

Record the precise browser order: register, password login, SMS login, profile display/edit, reset password, password change, logout, account deactivation, address search, single upload, resumable upload, then each documented backend blocker.

## Self-Review

- Coverage: Tasks 1-5 assign every documented operation an implementation owner or an explicit backend block; Task 6 provides the requested sequential test script.
- Contract discipline: `ApiClient` remains the only route owner; page modules do not create undocumented paths, scene codes, business tables or identifiers.
- Scope: pages without callable PC paths remain outside implementation; their schemas are not treated as endpoints.