From 9769401b103ac0b8e4f7b9d314f065463f454f30 Mon Sep 17 00:00:00 2001
From: rain <rain>
Date: Sat, 11 Jul 2026 09:15:50 +0800
Subject: [PATCH] docs: define auth to profile flow

---
 .../2026-07-11-auth-to-profile-flow-design.md | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-11-auth-to-profile-flow-design.md

diff --git a/docs/superpowers/specs/2026-07-11-auth-to-profile-flow-design.md b/docs/superpowers/specs/2026-07-11-auth-to-profile-flow-design.md
new file mode 100644
index 0000000..3fd9127
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-11-auth-to-profile-flow-design.md
@@ -0,0 +1,47 @@
+# Auth To Profile Flow Design
+
+## Status
+
+Pending written-spec review.
+
+## Goal
+
+Complete the PC journey from registration through login and personal-profile retrieval, with one token owner, deterministic redirects, and a single recorded API base address.
+
+## Endpoint Configuration
+
+`config.js` is the sole runtime owner of the API base address. Both development and production currently use `http://182.61.18.23:8080`. `tests/config.test.js` must assert that value. The PC integration tracker must record the change on 2026-07-11 and label prior test-domain references as historical rather than current configuration.
+
+## Token Contract
+
+`utils/ApiClient.js` owns token persistence under `genealogy_auth_token`.
+
+1. Successful password login and SMS login must receive a nonempty response token, persist it, and then allow navigation to `profile.html`.
+2. A login response without a token is an authentication failure. The login page remains in place and no profile navigation occurs.
+3. Successful registration removes any existing token and navigates to `login.html`. Registration never persists a response token.
+4. A failed registration leaves existing token storage unchanged.
+5. `logout()` clears token storage in a `finally` path, so a failed or expired logout request cannot leave a local session behind.
+
+## Page Flow
+
+1. Registration validates fields, obtains `WEB_H5_REGISTER` captcha proof, posts `/genealogy/pc/auth/register`, clears token through `ApiClient.register()`, and redirects to `login.html`.
+2. Password and SMS login validate fields, obtain `WEB_H5_LOGIN` captcha proof, post their respective login endpoint, persist the returned token through `ApiClient`, and redirect to `profile.html`.
+3. `profile.html` and `profile-data.html` check for a token before requesting `/genealogy/pc/auth/profile`. Without one, they redirect to `index.html` without making the profile request.
+4. A profile-read or profile-update error with HTTP status `401` or business code `401` clears token storage and redirects to `index.html`. Other errors remain on the current page and show the existing error message.
+5. Confirmed logout calls `/genealogy/pc/auth/logout`, clears token regardless of the request outcome, and redirects to `index.html`.
+
+## Ownership
+
+- `config.js`: API base address.
+- `utils/ApiClient.js`: login-token validation, persistence, clearing, and logout cleanup.
+- `public/js/profile-pages.js`: profile-page token guard and unauthorized redirect.
+- `public/js/profile-common.js`: confirmed logout action and redirect.
+- `docs/pc-api-page-integration-tracker-2026-07-09.md`: current address record and end-to-end authentication status.
+
+## Verification
+
+Tests must prove the configured address, registration state, both login token paths, missing-token login rejection, logout cleanup after both success and failure, and profile unauthorized classification. Focused configuration, API-client, profile-page, and authentication tests must pass before the full Node test suite is run.
+
+## Scope
+
+This flow covers registration, password login, SMS login, profile retrieval and update on the two pages that load `/genealogy/pc/auth/profile`, and the existing profile logout action. Password reset, phone change, account deactivation, and profile pages without profile API loading remain outside this change.