|
|
|
@@ -0,0 +1,278 @@
|
|
|
|
|
# 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.
|
rain