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

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

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

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

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

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

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

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

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

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

| 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.