feat(api): 添加帮助中心反馈系统和VIP服务功能
- 在ApiClient中新增submitFeedback、myFeedback、helpArticles、helpArticleDetail、 siteArticles、promotions、vipPackages、createVipOrder、vipOrders等方法 - 添加帮助文章和站点资讯的参数验证逻辑 - 更新测试文件添加新的API方法测试用例 - 在HTML页面中添加反馈、帮助和VIP服务相关页面的脚本引用 - 更新加入家谱页面为完整的申请流程界面 - 修改资讯详情页面为站点资讯展示页面 - 更新AxiosRequestUtil中认证处理逻辑 - 添加世系树渲染的HTML生成函数用于页面复用 - 更新文档中的API契约说明和页面规划
This commit is contained in:
fizzleaf
@@ -0,0 +1,391 @@
|
||||
# 应用下载页 PC 推广列表 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:** 在 `app.html` 现有推广区域读取并安全展示后端 PC 推广列表，同时保持应用下载页公开可访问。
|
||||
|
||||
**Architecture:** `utils/ApiClient.js` 独占 method/path/query 契约；新建 `public/js/app-promotion-pages.js` 独占 `AppPromotionVo` 规范化、链接安全、区域状态和渲染。页面只提供容器与脚本加载，不复制接口逻辑。
|
||||
|
||||
**Tech Stack:** 原生 JavaScript UMD、HTML/CSS、Node.js `node:test`、现有 `GenealogyApi` / `AxiosRequestUtil`。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 只调用 `GET /genealogy/pc/promotions`，不得调用 APP 或后台管理接口。
|
||||
- 后端控制器实际要求 PC 登录态；请求携带当前 token 和基础 `clientid`。
|
||||
- 页面初始化不发送 `platform`；客户端即使被其它调用方使用，也只允许可选 Query `platform`。
|
||||
- 页面不展示或拼接 `coverOssId`，不允许用户输入业务 ID 或 OSS ID。
|
||||
- `targetUrl` 只允许绝对 HTTP(S) URL；其它值按无链接卡片展示。
|
||||
- 页面本身保持公开；未登录和 401 只改变推广区域，不跳走整个下载页。
|
||||
- 旧 `promotion-pages.js` 不恢复，不保留兼容入口。
|
||||
- 后端项目 `D:\WorkSpace\Java\Genealogy` 只读。
|
||||
- 当前共享 `main` 工作区包含多批未提交改动；本计划不执行 Git stage、commit、merge 或 push。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 冻结 PC 推广客户端契约
|
||||
|
||||
**Files:**
|
||||
- Modify: `tests/api-client-contract.test.js`
|
||||
- Modify: `utils/ApiClient.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: 私有 `request(method, path, options)` 与 `pickDefined(source, allowedFields)`。
|
||||
- Produces: `client.promotions(query?: { platform?: string }): Promise<Array<AppPromotionVo>>`。
|
||||
|
||||
- [ ] **Step 1: 在客户端允许方法集合中加入 `promotions`，并写失败测试**
|
||||
|
||||
测试使用带 `access-token` 的真实客户端边界，传入：
|
||||
|
||||
```js
|
||||
await client.promotions({
|
||||
platform: 'pc',
|
||||
keyword: 'must-drop'
|
||||
});
|
||||
```
|
||||
|
||||
手工断言请求为：
|
||||
|
||||
```js
|
||||
[
|
||||
'get',
|
||||
'/genealogy/pc/promotions',
|
||||
{ platform: 'pc' },
|
||||
'Bearer access-token'
|
||||
]
|
||||
```
|
||||
|
||||
该测试捕获错误 path、错误 method、契约外 Query 被透传或误设 `auth: false`。
|
||||
|
||||
- [ ] **Step 2: 运行客户端测试观察 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/api-client-contract.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，提示 `promotions` 未导出或不是函数。
|
||||
|
||||
- [ ] **Step 3: 添加最小客户端实现**
|
||||
|
||||
在 `helpArticleDetail` 和 VIP 方法附近添加：
|
||||
|
||||
```js
|
||||
promotions: function (query) {
|
||||
return request('GET', '/genealogy/pc/promotions', {
|
||||
query: pickDefined(query, ['platform'])
|
||||
});
|
||||
},
|
||||
```
|
||||
|
||||
不得增加 `auth: false`、默认 `platform` 或旧路径 fallback。
|
||||
|
||||
- [ ] **Step 4: 运行客户端测试观察 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/api-client-contract.test.js
|
||||
```
|
||||
|
||||
Expected: 全部通过。
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 实现推广响应和安全渲染边界
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/app-promotion-pages.test.js`
|
||||
- Create: `public/js/app-promotion-pages.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `GenealogyApi.defaultClient.promotions()`、`getToken()`、`clearToken()`。
|
||||
- Produces:
|
||||
- `normalizeTargetUrl(value): string`
|
||||
- `normalizePromotion(item): PromotionView | null`
|
||||
- `normalizePromotionList(data): PromotionView[]`
|
||||
- `renderPromotionList(data): string`
|
||||
- `renderPromotionLoginRequired(): string`
|
||||
- `loadPromotions(api): Promise<PromotionView[]>`
|
||||
- `isUnauthorized(error): boolean`
|
||||
- `init(): Promise<void>`
|
||||
|
||||
`PromotionView` 的唯一形状：
|
||||
|
||||
```js
|
||||
{
|
||||
promotionId: '2062179707935264769',
|
||||
promotionTitle: '下载移动端',
|
||||
promotionDesc: '随时查看家谱内容',
|
||||
targetUrl: 'https://example.com/download'
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 1: 写完整真实 DTO fixture 和失败测试**
|
||||
|
||||
Fixture 必须包含后端全部 10 个字段：
|
||||
|
||||
```js
|
||||
{
|
||||
promotionId: '2062179707935264769',
|
||||
promotionKey: 'app-download',
|
||||
promotionTitle: '下载移动端',
|
||||
promotionDesc: '随时查看家谱内容',
|
||||
coverOssId: '2062179707935264701',
|
||||
targetUrl: 'https://example.com/download',
|
||||
platform: 'all',
|
||||
sortOrder: 10,
|
||||
status: '0',
|
||||
remark: 'internal-only'
|
||||
}
|
||||
```
|
||||
|
||||
分别覆盖：
|
||||
|
||||
1. 规范化结果只保留 `PromotionView` 四字段；
|
||||
2. 不安全数字长 ID、空标题和 `status=1` 返回 `null`；
|
||||
3. 直接数组正常，`{ rows: [...] }` 和混入非法元素返回空数组；
|
||||
4. `https://`、`http://` 保留，`javascript:`、`data:`、相对路径和空值返回空字符串；
|
||||
5. 渲染转义标题与说明，不出现 `coverOssId`、`promotionKey`、`sortOrder`、`status`、`remark`；
|
||||
6. 合法 URL 使用 `target="_blank"` 和 `rel="noopener noreferrer"`，非法 URL 不生成 `<a>`；
|
||||
7. `loadPromotions(api)` 只调用一次 `api.promotions()`，不传 `platform`；
|
||||
8. `isUnauthorized` 仅把 HTTP/业务 401 视为登录失效，403 为普通错误。
|
||||
|
||||
- [ ] **Step 2: 运行模块测试观察 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/app-promotion-pages.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，提示 `public/js/app-promotion-pages.js` 不存在。
|
||||
|
||||
- [ ] **Step 3: 实现 UMD 模块的纯函数**
|
||||
|
||||
实现稳定 ID：
|
||||
|
||||
```js
|
||||
function normalizeId(value) {
|
||||
if (typeof value === 'number' && !Number.isSafeInteger(value)) return '';
|
||||
var result = String(value == null ? '' : value).trim();
|
||||
return /^[1-9][0-9]*$/.test(result) ? result : '';
|
||||
}
|
||||
```
|
||||
|
||||
实现安全 URL：
|
||||
|
||||
```js
|
||||
function normalizeTargetUrl(value) {
|
||||
var text = String(value == null ? '' : value).trim();
|
||||
var parsed;
|
||||
if (!text) return '';
|
||||
try {
|
||||
parsed = new URL(text);
|
||||
} catch (error) {
|
||||
return '';
|
||||
}
|
||||
return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed.href : '';
|
||||
}
|
||||
```
|
||||
|
||||
`normalizePromotion` 必须要求稳定 `promotionId`、非空 `promotionTitle` 和 `status === '0'`，然后只返回 `PromotionView`。`normalizePromotionList` 必须拒绝非直接数组以及包含任一非法元素的数组。
|
||||
|
||||
- [ ] **Step 4: 实现渲染和读取函数**
|
||||
|
||||
有链接时结构：
|
||||
|
||||
```html
|
||||
<a class="promotion-card" data-promotion-id="..." href="..." target="_blank" rel="noopener noreferrer">
|
||||
<div><h3>...</h3><p>...</p><span>了解详情</span></div>
|
||||
</a>
|
||||
```
|
||||
|
||||
无链接时使用 `<article class="promotion-card">`，不输出 `href`、`target` 或 `rel`。空列表固定返回：
|
||||
|
||||
```html
|
||||
<div class="api-empty">当前暂无应用推广</div>
|
||||
```
|
||||
|
||||
未登录固定返回：
|
||||
|
||||
```html
|
||||
<div class="api-empty">登录后可查看应用推广。<a href="login.html">去登录</a></div>
|
||||
```
|
||||
|
||||
`loadPromotions(api)` 必须执行 `await api.promotions()`，并通过“原数组长度等于规范化后数组长度”确认响应完整。
|
||||
|
||||
- [ ] **Step 5: 实现区域级初始化**
|
||||
|
||||
`init()` 只在 `[data-promotion-page]` 和 `[data-promotion-list]` 同时存在时运行：
|
||||
|
||||
```js
|
||||
if (!api || !api.getToken || !api.getToken()) {
|
||||
list.innerHTML = renderPromotionLoginRequired();
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
有 token 时加载一次。401 调用 `api.clearToken()` 并渲染登录入口；403、网络失败或非法响应渲染“应用推广读取失败，请稍后重试”。不得修改 `root.location`。
|
||||
|
||||
- [ ] **Step 6: 运行模块测试观察 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/app-promotion-pages.test.js tests/api-client-contract.test.js
|
||||
```
|
||||
|
||||
Expected: 全部通过。
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 开放应用下载页推广区域
|
||||
|
||||
**Files:**
|
||||
- Modify: `tests/app-promotion-pages.test.js`
|
||||
- Modify: `tests/pc-scope.test.js`
|
||||
- Modify: `app.html`
|
||||
- Modify only if required by rendered markup: `public/css/app.css`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `window.AppPromotionPages.init()` 的 DOMContentLoaded 自动初始化。
|
||||
- Produces: `app.html` 的真实推广列表入口。
|
||||
|
||||
- [ ] **Step 1: 写页面开放状态失败测试**
|
||||
|
||||
在 `tests/app-promotion-pages.test.js` 读取 `app.html`，断言：
|
||||
|
||||
```js
|
||||
assert.match(page, /data-promotion-page/);
|
||||
assert.match(page, /data-promotion-list/);
|
||||
assert.match(page, /public\/js\/app-promotion-pages\.js/);
|
||||
assert.doesNotMatch(page, /public\/js\/promotion-pages\.js/);
|
||||
assert.doesNotMatch(page, /name="(?:promotionId|coverOssId|platform)"/);
|
||||
```
|
||||
|
||||
在 `tests/pc-scope.test.js` 保留旧 `promotion-pages.js` deny-list，并新增 `app.html` 必须加载 `app-promotion-pages.js` 的断言。
|
||||
|
||||
- [ ] **Step 2: 运行页面测试观察 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/app-promotion-pages.test.js tests/pc-scope.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，提示 `app.html` 尚未加载新脚本。
|
||||
|
||||
- [ ] **Step 3: 修改页面加载脚本**
|
||||
|
||||
在 `page-effects.js` 后加载：
|
||||
|
||||
```html
|
||||
<script src="public/js/app-promotion-pages.js"></script>
|
||||
```
|
||||
|
||||
保留现有 `data-promotion-page`、`data-promotion-list` 和初始加载文案。不得添加筛选器、刷新按钮、示例推广或隐藏 ID 输入。
|
||||
|
||||
- [ ] **Step 4: 仅在需要时补充无图片卡片样式**
|
||||
|
||||
如果 `<a class="promotion-card">` 不能继承卡片文字颜色与块级点击区域，只增加：
|
||||
|
||||
```css
|
||||
.promotion-card {
|
||||
display: block;
|
||||
color: inherit;
|
||||
text-decoration: none;
|
||||
}
|
||||
```
|
||||
|
||||
不得调整首页广告样式或重做应用下载页布局。
|
||||
|
||||
- [ ] **Step 5: 运行页面与模块组合测试观察 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/app-promotion-pages.test.js tests/api-client-contract.test.js tests/pc-scope.test.js tests/public-static-pages.test.js
|
||||
```
|
||||
|
||||
Expected: 全部通过。
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 更新规划并完成验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/PC接口对接规划.md`
|
||||
- Modify: `docs/superpowers/plans/2026-07-29-app-promotions.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: 已实现的 ApiClient、模块、页面和测试证据。
|
||||
- Produces: 阶段 7 第七批契约记录和验收报告。
|
||||
|
||||
- [ ] **Step 1: 在规划中新增推广字段表**
|
||||
|
||||
记录：
|
||||
|
||||
- method/path/内容推广目录；
|
||||
- `platform` 为可选 Query、当前页面省略；
|
||||
- Authorization 与 clientid 为 A；
|
||||
- Body 为空；
|
||||
- `promotionId`、`promotionKey`、`coverOssId`、`platform`、`sortOrder`、`status`、`remark` 为 I；
|
||||
- `promotionTitle`、`promotionDesc`、安全 `targetUrl` 为 R；
|
||||
- YAML `security: []` / 未导出 Query 与后端实际鉴权 / `platform` 的冲突；
|
||||
- 页面初始化、未登录、401、403、空数组、非法响应和真实列表时机。
|
||||
|
||||
- [ ] **Step 2: 运行专项测试**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/app-promotion-pages.test.js tests/api-client-contract.test.js tests/pc-scope.test.js tests/public-static-pages.test.js
|
||||
```
|
||||
|
||||
Expected: 0 failures。
|
||||
|
||||
- [ ] **Step 3: 运行语法和差异检查**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --check public/js/app-promotion-pages.js
|
||||
node --check utils/ApiClient.js
|
||||
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
|
||||
```
|
||||
|
||||
Expected: 两个语法检查 exit 0；`diff --check` 无错误，CRLF warning 可记录但不算失败。
|
||||
|
||||
- [ ] **Step 4: 运行全量测试**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
npm test
|
||||
```
|
||||
|
||||
Expected: 0 failures。
|
||||
|
||||
- [ ] **Step 5: 浏览器验证真实分支**
|
||||
|
||||
只读验证：
|
||||
|
||||
1. 未登录打开 `app.html`，确认下载内容保留、推广区域显示登录入口、未发生推广请求；
|
||||
2. 使用已授权测试账号登录后打开 `app.html`；
|
||||
3. 后端返回空数组时显示“当前暂无应用推广”；有数据时检查标题、说明、安全外链和内部字段隐藏；
|
||||
4. 检查页面控制台；
|
||||
5. 不点击外部推广链接，不创建或修改后端数据；
|
||||
6. 浏览器控制不稳定时停止自动关闭标签页，只报告已取得的验证结果并清理本地临时服务。
|
||||
|
||||
- [ ] **Step 6: 标记计划状态并按阶段格式汇报**
|
||||
|
||||
报告必须包含：
|
||||
|
||||
```text
|
||||
Changed: ApiClient、推广模块、app.html 和规划新增内容。
|
||||
Verified: RED/GREEN、专项、全量和浏览器覆盖数量。
|
||||
Conflicts: YAML 匿名/无 Query 与后端真实鉴权/platform 的差异。
|
||||
Blocked: 缺少封面 URL、platform 枚举或真实推广数据时的剩余联调项。
|
||||
Next: 官网内容或公开家谱接口的下一最小批次。
|
||||
```
|
||||
@@ -0,0 +1,376 @@
|
||||
# 家谱主页 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:** 将 `profile-family-home.html` 从静态预览开放为真实 PC 家谱主页，展示当前家谱概览和世系树预览，并保留已接入业务页入口。
|
||||
|
||||
**Architecture:** `profile-common.js` 继续唯一拥有当前 `genealogyId`；页面只调用已有 `genealogyOverview(genealogyId)` 和 `lineageTree(genealogyId)`。`lineage-pages.js` 继续唯一拥有世系树节点规范化与 HTML 生成，新建 `family-home-pages.js` 只负责概览 DTO、权限显隐、并行读取和页面状态。
|
||||
|
||||
**Tech Stack:** 静态 HTML、原生 JavaScript UMD、Axios、Node `node:test`。
|
||||
|
||||
**Status:** 2026-07-29 已按 Task 1–4 实施；自动化与无家谱真实账号分支已验证，有家谱数据态等待具备真实家谱的账号复核。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 后端 `D:\WorkSpace\Java\Genealogy` 全程只读。
|
||||
- 只使用 PC 接口；不得调用 `/genealogy/dashboard/overview`、APP 或管理后台接口。
|
||||
- `genealogyId` 只能来自 `ProfileUI.getGenealogyId()`，始终按字符串处理。
|
||||
- `GET /genealogy/pc/genealogies/{genealogyId}/overview` 返回 `AppGenealogyVo`，它不是内容统计接口；不得制造文章、相册、视频或活动数量。
|
||||
- 世系树只读调用 `GET /genealogy/pc/genealogies/{genealogyId}/lineage/tree`。
|
||||
- 家谱管理入口仅在响应 `canManage=true` 时显示；内容页自身继续负责更细权限。
|
||||
- PC 没有成员邀请创建/分享接口；主页不得开放“邀请家人”操作。
|
||||
- 本批次没有写接口，不创建、修改或删除任何真实业务数据。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 家谱主页 DTO 与页面契约
|
||||
|
||||
**Files:**
|
||||
- Create: `public/js/family-home-pages.js`
|
||||
- Create: `tests/family-home-pages.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `ProfileUI.getGenealogyId()`、`GenealogyApi.defaultClient`
|
||||
- Produces:
|
||||
- `normalizeFamilyOverview(item, expectedGenealogyId)`
|
||||
- `renderFamilyOverview(overview)`
|
||||
- `shouldShowFamilyManagement(overview)`
|
||||
- `shouldRedirectToLogin(api, error)`
|
||||
|
||||
- [ ] **Step 1: 写失败数据边界测试**
|
||||
|
||||
```js
|
||||
const overview = FamilyHomePages.normalizeFamilyOverview({
|
||||
genealogyId: '2062179707935264769',
|
||||
genealogyNo: 'G20260729001',
|
||||
genealogyName: '叶氏家谱',
|
||||
surname: '叶',
|
||||
ancestralHall: '南阳堂',
|
||||
originPlace: '四川成都',
|
||||
regionFullName: '四川省 成都市',
|
||||
memberCount: 12,
|
||||
personCount: 36,
|
||||
status: '0',
|
||||
canManage: true,
|
||||
canEditContent: true,
|
||||
ownerUserId: 'must-not-render',
|
||||
coverOssId: 'must-not-render'
|
||||
}, '2062179707935264769');
|
||||
|
||||
assert.deepEqual(overview, {
|
||||
genealogyId: '2062179707935264769',
|
||||
genealogyNo: 'G20260729001',
|
||||
genealogyName: '叶氏家谱',
|
||||
surname: '叶',
|
||||
ancestralHall: '南阳堂',
|
||||
originPlace: '四川成都',
|
||||
regionFullName: '四川省 成都市',
|
||||
memberCount: 12,
|
||||
personCount: 36,
|
||||
canManage: true,
|
||||
canEditContent: true
|
||||
});
|
||||
assert.equal(
|
||||
FamilyHomePages.normalizeFamilyOverview(
|
||||
{ genealogyId: Number.MAX_SAFE_INTEGER + 1, genealogyName: '非法', status: '0' },
|
||||
'2062179707935264769'
|
||||
),
|
||||
null
|
||||
);
|
||||
assert.equal(
|
||||
FamilyHomePages.normalizeFamilyOverview(
|
||||
{ genealogyId: '2', genealogyName: '串谱', status: '0' },
|
||||
'2062179707935264769'
|
||||
),
|
||||
null
|
||||
);
|
||||
```
|
||||
|
||||
同时断言：
|
||||
|
||||
- `genealogyName` 为空、`status!='0'`、负数/非安全计数均拒绝；
|
||||
- 渲染转义全部文本，不出现 `ownerUserId`、`coverOssId` 或原始 JSON；
|
||||
- 只有布尔值 `canManage===true` 才开放管理入口；
|
||||
- 401 清理登录态，403 不清理登录态。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run: `node --test tests/family-home-pages.test.js`
|
||||
|
||||
Expected: FAIL，`family-home-pages.js` 不存在。
|
||||
|
||||
- [ ] **Step 3: 最小实现概览规范化**
|
||||
|
||||
```js
|
||||
function normalizeFamilyOverview(item, expectedGenealogyId) {
|
||||
var source = item || {};
|
||||
var genealogyId = normalizeId(source.genealogyId);
|
||||
var expectedId = normalizeId(expectedGenealogyId);
|
||||
var memberCount = normalizeCount(source.memberCount);
|
||||
var personCount = normalizeCount(source.personCount);
|
||||
|
||||
if (!genealogyId || genealogyId !== expectedId ||
|
||||
!text(source.genealogyName) || String(source.status) !== '0' ||
|
||||
memberCount === null || personCount === null) return null;
|
||||
return {
|
||||
genealogyId: genealogyId,
|
||||
genealogyNo: text(source.genealogyNo),
|
||||
genealogyName: text(source.genealogyName),
|
||||
surname: text(source.surname),
|
||||
ancestralHall: text(source.ancestralHall),
|
||||
originPlace: text(source.originPlace),
|
||||
regionFullName: text(source.regionFullName),
|
||||
memberCount: memberCount,
|
||||
personCount: personCount,
|
||||
canManage: source.canManage === true,
|
||||
canEditContent: source.canEditContent === true
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/family-home-pages.test.js
|
||||
node --check public/js/family-home-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 复用世系树唯一渲染 owner
|
||||
|
||||
**Files:**
|
||||
- Modify: `public/js/lineage-pages.js`
|
||||
- Modify: `tests/lineage-pages.test.js`
|
||||
- Modify: `tests/family-home-pages.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `LineagePages.renderLineageTreeHtml(data)`
|
||||
- Consumes: 现有 `normalizeLineagePerson(item)`、`renderTreeNode(item, ancestry)`
|
||||
|
||||
- [ ] **Step 1: 写失败共享渲染测试**
|
||||
|
||||
```js
|
||||
const tree = [{
|
||||
personId: '2062179707935264770',
|
||||
genealogyId: '2062179707935264769',
|
||||
name: '<始祖>',
|
||||
status: '0',
|
||||
spouses: [],
|
||||
children: []
|
||||
}];
|
||||
|
||||
const html = LineagePages.renderLineageTreeHtml(tree);
|
||||
assert.match(html, /<始祖>/);
|
||||
assert.match(html, /data-lineage-person="2062179707935264770"/);
|
||||
assert.doesNotMatch(html, /2062179707935264769/);
|
||||
assert.match(LineagePages.renderLineageTreeHtml([]), /暂无世系树/);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run: `node --test tests/lineage-pages.test.js tests/family-home-pages.test.js`
|
||||
|
||||
Expected: FAIL，`renderLineageTreeHtml` 未导出。
|
||||
|
||||
- [ ] **Step 3: 从现有 `renderTree` 提取纯 HTML owner**
|
||||
|
||||
```js
|
||||
function renderLineageTreeHtml(data) {
|
||||
var nodes = normalizeList(data)
|
||||
.map(function (item) { return renderTreeNode(item, {}); })
|
||||
.filter(Boolean);
|
||||
|
||||
return nodes.length
|
||||
? '<ul class="lineage-tree">' + nodes.join('') + '</ul>'
|
||||
: '<div class="api-empty">暂无世系树</div>';
|
||||
}
|
||||
|
||||
function renderTree(data) {
|
||||
var container = query('[data-lineage-tree]');
|
||||
if (container) container.innerHTML = renderLineageTreeHtml(data);
|
||||
}
|
||||
```
|
||||
|
||||
在 UMD 导出对象加入：
|
||||
|
||||
```js
|
||||
renderLineageTreeHtml: renderLineageTreeHtml
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/lineage-pages.test.js tests/family-home-pages.test.js
|
||||
node --check public/js/lineage-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS，现有世系管理页输出不变。
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 开放真实家谱主页
|
||||
|
||||
**Files:**
|
||||
- Modify: `profile-family-home.html`
|
||||
- Modify: `public/js/family-home-pages.js`
|
||||
- Modify: `tests/family-home-pages.test.js`
|
||||
- Modify: `tests/pending-pages.test.js`
|
||||
- Modify: `tests/stage6-navigation.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes:
|
||||
- `api.genealogyOverview(genealogyId)`
|
||||
- `api.lineageTree(genealogyId)`
|
||||
- `LineagePages.renderLineageTreeHtml(data)`
|
||||
- Produces: `initFamilyHomePage()`、`init()`
|
||||
|
||||
- [ ] **Step 1: 写失败页面测试**
|
||||
|
||||
断言：
|
||||
|
||||
- `profile-family-home.html` 不再包含 `data-feature-status="pending"` 或 `pending-pages.js`；
|
||||
- 加载顺序为 `profile-common.js`、`lineage-pages.js`、`family-home-pages.js`；
|
||||
- 标题、摘要、计数、管理入口、世系预览均有稳定 `data-*` hook；
|
||||
- 硬编码“四川武胜汤氏族”被删除；
|
||||
- “邀请家人”不再是可点击业务入口，并明确提示“PC 暂未开放邀请”；
|
||||
- 谱文、相册、视频、功德、祭祀、世系、动态入口继续携带 `data-genealogy-context-link`；
|
||||
- 初始化只并行调用：
|
||||
|
||||
```js
|
||||
Promise.all([
|
||||
api.genealogyOverview(genealogyId),
|
||||
api.lineageTree(genealogyId)
|
||||
])
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/family-home-pages.test.js tests/pending-pages.test.js tests/stage6-navigation.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，主页仍为 pending 且包含硬编码家谱。
|
||||
|
||||
- [ ] **Step 3: 实现只读初始化流程**
|
||||
|
||||
```js
|
||||
async function initFamilyHomePage() {
|
||||
var api = root.GenealogyApi && root.GenealogyApi.defaultClient;
|
||||
var genealogyId = root.ProfileUI && root.ProfileUI.getGenealogyId();
|
||||
var results;
|
||||
var overview;
|
||||
|
||||
if (!genealogyId) {
|
||||
root.location.replace('profile-families.html?next=profile-family-home.html');
|
||||
return;
|
||||
}
|
||||
try {
|
||||
results = await Promise.all([
|
||||
api.genealogyOverview(genealogyId),
|
||||
api.lineageTree(genealogyId)
|
||||
]);
|
||||
overview = normalizeFamilyOverview(results[0], genealogyId);
|
||||
if (!overview) throw new Error('家谱概览响应无效');
|
||||
renderFamilyOverview(overview);
|
||||
renderManagementAccess(overview.canManage);
|
||||
query('[data-lineage-home-tree]').innerHTML =
|
||||
root.LineagePages.renderLineageTreeHtml(results[1]);
|
||||
} catch (error) {
|
||||
if (shouldRedirectToLogin(api, error)) return redirectToLogin(api);
|
||||
renderFamilyHomeError(error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
页面只展示：
|
||||
|
||||
- 家谱名称、编号、姓氏、堂号、祖籍/地区；
|
||||
- `memberCount`、`personCount`；
|
||||
- 真实世系树及进入完整世系页的链接；
|
||||
- 后端已经接入的内容模块入口。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/family-home-pages.test.js tests/pending-pages.test.js tests/stage6-navigation.test.js
|
||||
node --check public/js/family-home-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 规划记录与完整验收
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/PC接口对接规划.md`
|
||||
- Modify: `docs/superpowers/plans/2026-07-29-family-home.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Task 1–3 的只读家谱主页闭环。
|
||||
|
||||
- [ ] **Step 1: 更新规划字段表**
|
||||
|
||||
新增家谱主页小节，逐字段记录：
|
||||
|
||||
| 字段 | 分类 | 页面用途 |
|
||||
| --- | --- | --- |
|
||||
| `genealogyId` | I/A | 当前上下文、两条请求 path、响应一致性校验 |
|
||||
| `genealogyNo`、`genealogyName`、`surname` | R | 标题和基础信息 |
|
||||
| `ancestralHall`、`originPlace`、`regionFullName` | R | 非空时展示 |
|
||||
| `memberCount`、`personCount` | R | 非负只读计数 |
|
||||
| `canManage`、`canEditContent` | I | 权限显隐，不作为用户输入 |
|
||||
| `ownerUserId`、`coverOssId` | I | 当前主页不展示、不手填 |
|
||||
| `LineagePersonTreeView.spouses/children` | R | 递归世系预览 |
|
||||
|
||||
同时记录：
|
||||
|
||||
- `/overview` 实际是详情别名，不包含内容聚合统计；
|
||||
- `/genealogy/dashboard/overview` 是后台权限接口，不进入 PC 前端；
|
||||
- 成员邀请没有 PC 接口，继续阻断。
|
||||
|
||||
- [ ] **Step 2: 聚焦验证**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/family-home-pages.test.js tests/lineage-pages.test.js tests/pending-pages.test.js tests/stage6-navigation.test.js tests/api-client-contract.test.js
|
||||
node --check public/js/family-home-pages.js
|
||||
node --check public/js/lineage-pages.js
|
||||
```
|
||||
|
||||
Expected: 全部 PASS。
|
||||
|
||||
- [ ] **Step 3: 全量和差异验证**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
npm test
|
||||
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
|
||||
```
|
||||
|
||||
Expected: 0 failed，差异检查无错误。
|
||||
|
||||
- [ ] **Step 4: 浏览器真实只读验证**
|
||||
|
||||
使用真实登录态验证：
|
||||
|
||||
1. 无家谱上下文时只跳转选择页，不发家谱业务请求；
|
||||
2. 有真实家谱时标题、概览计数和世系树来自 PC 响应；
|
||||
3. 普通成员看不到管理按钮，管理者可见；
|
||||
4. 所有入口透传同一 `genealogyId`；
|
||||
5. 空世系、403、404、网络错误都有明确页面状态；
|
||||
6. 控制台无错误；
|
||||
7. 不创建或修改任何真实数据。
|
||||
@@ -0,0 +1,310 @@
|
||||
# 反馈与工单 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 反馈记录形成提交、列表和详情闭环。
|
||||
|
||||
**Architecture:** `utils/ApiClient.js` 唯一拥有 `/genealogy/pc/feedback` 的 GET/POST 契约；新增 UMD 模块 `feedback-pages.js` 负责 DTO 构造、完整 VO 规范化、列表/详情渲染和四类页面初始化。“工单”只是反馈记录的帮助中心展示名称，详情通过 URL 中由列表响应产生的 `feedbackId` 在我的反馈列表中精确匹配。
|
||||
|
||||
**Tech Stack:** 静态 HTML、原生 JavaScript UMD、Axios、Node `node:test`。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 后端 `D:\WorkSpace\Java\Genealogy` 全程只读。
|
||||
- 只调用 `POST /genealogy/pc/feedback` 和 `GET /genealogy/pc/feedback`。
|
||||
- 请求只发送 `feedbackType`、`feedbackContent`、`contactInfo`；不发送 `feedbackTitle`。
|
||||
- `feedbackType` 只允许后端已确认字典值 `advice/bug/complaint/other`；空值省略并由后端默认 `advice`。
|
||||
- `feedbackId` 只能来自提交或列表响应，不提供文本输入。
|
||||
- 页面不展示 `appUserId`、`handlerId`、`appUserPhone`、原始 JSON。
|
||||
- 所有提交防重复；提交成功后必须重读列表并匹配同一 `feedbackId`。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: ApiClient 反馈契约
|
||||
|
||||
**Files:**
|
||||
- Modify: `utils/ApiClient.js`
|
||||
- Modify: `tests/api-client-contract.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `submitFeedback(body)`、`myFeedback()`
|
||||
|
||||
- [ ] **Step 1: 写失败的契约测试**
|
||||
|
||||
增加测试，使用完整请求字面量断言：
|
||||
|
||||
```js
|
||||
await client.submitFeedback({
|
||||
feedbackType: 'bug',
|
||||
feedbackContent: '页面按钮无响应',
|
||||
contactInfo: '19181970173',
|
||||
feedbackTitle: 'must-drop',
|
||||
appUserId: 'must-drop'
|
||||
});
|
||||
await client.myFeedback();
|
||||
|
||||
assert.deepEqual(calls, [
|
||||
{
|
||||
method: 'POST',
|
||||
url: '/genealogy/pc/feedback',
|
||||
body: {
|
||||
feedbackType: 'bug',
|
||||
feedbackContent: '页面按钮无响应',
|
||||
contactInfo: '19181970173'
|
||||
}
|
||||
},
|
||||
{ method: 'GET', url: '/genealogy/pc/feedback' }
|
||||
]);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/api-client-contract.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，`submitFeedback` 或 `myFeedback` 不存在。
|
||||
|
||||
- [ ] **Step 3: 最小实现**
|
||||
|
||||
在 `createClient()` 返回对象中增加：
|
||||
|
||||
```js
|
||||
submitFeedback: function (body) {
|
||||
return request('POST', '/genealogy/pc/feedback', {
|
||||
body: pickDefined(body, ['feedbackType', 'feedbackContent', 'contactInfo'])
|
||||
});
|
||||
},
|
||||
myFeedback: function () {
|
||||
return request('GET', '/genealogy/pc/feedback');
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/api-client-contract.test.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 反馈 DTO、VO、列表和详情边界
|
||||
|
||||
**Files:**
|
||||
- Create: `public/js/feedback-pages.js`
|
||||
- Create: `tests/feedback-pages.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces:
|
||||
- `getFeedbackId(search)`
|
||||
- `buildFeedbackBody(values)`
|
||||
- `validateFeedbackBody(body)`
|
||||
- `normalizeFeedback(item)`
|
||||
- `normalizeFeedbackList(data)`
|
||||
- `findFeedbackById(data, feedbackId)`
|
||||
- `buildFeedbackDetailUrl(feedbackId)`
|
||||
- `renderFeedbackList(data, options)`
|
||||
- `renderFeedbackDetail(item)`
|
||||
|
||||
- [ ] **Step 1: 写失败的纯行为测试**
|
||||
|
||||
用完整 `FeedbackVo` 字面量验证：
|
||||
|
||||
```js
|
||||
assert.deepEqual(FeedbackPages.buildFeedbackBody({
|
||||
feedbackType: ' bug ',
|
||||
feedbackContent: ' 页面按钮无响应 ',
|
||||
contactInfo: ' 19181970173 ',
|
||||
feedbackTitle: 'must-drop',
|
||||
appUserId: 'must-drop'
|
||||
}), {
|
||||
feedbackType: 'bug',
|
||||
feedbackContent: '页面按钮无响应',
|
||||
contactInfo: '19181970173'
|
||||
});
|
||||
```
|
||||
|
||||
同时断言：
|
||||
|
||||
- `feedbackContent` 为空时报错；
|
||||
- 类型只允许 `advice/bug/complaint/other`，空值省略；
|
||||
- 不安全 number ID、空内容、`handleStatus` 非 `0/1/2/3`、`status` 非 `0/1` 的响应拒绝；
|
||||
- 数组包含一个非法元素时整批返回空数组；
|
||||
- 详情只精确匹配同一字符串 `feedbackId`，不存在时不回退第一条；
|
||||
- 列表和详情转义可见文本，不出现内部用户/处理人 ID、账号手机号或原始 JSON；
|
||||
- 详情 URL 使用 `ticket-detail.html?feedbackId=...`。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/feedback-pages.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，模块不存在。
|
||||
|
||||
- [ ] **Step 3: 最小实现纯函数**
|
||||
|
||||
`normalizeFeedback()` 返回且只返回：
|
||||
|
||||
```js
|
||||
{
|
||||
feedbackId,
|
||||
feedbackType,
|
||||
feedbackContent,
|
||||
contactInfo,
|
||||
handleStatus,
|
||||
handleResult,
|
||||
handleTime,
|
||||
status,
|
||||
remark
|
||||
}
|
||||
```
|
||||
|
||||
状态展示固定为：
|
||||
|
||||
```js
|
||||
{ '0': '待处理', '1': '处理中', '2': '已处理', '3': '已关闭' }
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/feedback-pages.test.js
|
||||
node --check public/js/feedback-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 四个页面的真实反馈闭环
|
||||
|
||||
**Files:**
|
||||
- Modify: `profile-feedback.html`
|
||||
- Modify: `submit-ticket.html`
|
||||
- Modify: `my-tickets.html`
|
||||
- Modify: `ticket-detail.html`
|
||||
- Modify: `public/js/feedback-pages.js`
|
||||
- Modify: `tests/feedback-pages.test.js`
|
||||
- Modify: `tests/pending-pages.test.js`
|
||||
- Modify: `tests/public-static-pages.test.js`
|
||||
- Modify: `tests/pc-scope.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `initFeedbackFormPage()`、`initFeedbackListPage()`、`initFeedbackDetailPage()`、`init()`
|
||||
|
||||
- [ ] **Step 1: 写失败的页面行为测试**
|
||||
|
||||
断言四个页面：
|
||||
|
||||
- 不再包含 `data-feature-status="pending"` 或 `pending-pages.js`；
|
||||
- 均加载 `feedback-pages.js` 和 ApiClient 依赖；
|
||||
- 两个提交页只提供 `feedbackType/feedbackContent/contactInfo`，不存在 `feedbackTitle` 或任意业务 ID 输入；
|
||||
- 列表页有 `data-feedback-list` 和刷新按钮；
|
||||
- 详情页只有 `data-feedback-detail`，不提供回复、追问、删除或关闭操作。
|
||||
|
||||
断言脚本提交后调用 `myFeedback()`，必须按提交响应的 `feedbackId` 重读匹配；详情按 URL `feedbackId` 精确匹配。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/feedback-pages.test.js tests/pending-pages.test.js tests/public-static-pages.test.js tests/pc-scope.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，四个页面仍为 pending。
|
||||
|
||||
- [ ] **Step 3: 实现页面初始化**
|
||||
|
||||
提交页：
|
||||
|
||||
1. 构造并校验请求；
|
||||
2. `writePending` 锁和按钮禁用；
|
||||
3. 调用 `submitFeedback(body)`；
|
||||
4. 规范化提交响应；
|
||||
5. 重读 `myFeedback()`，精确找到同一 `feedbackId`；
|
||||
6. 个人反馈页刷新历史列表；工单页进入 `ticket-detail.html?feedbackId=...`。
|
||||
|
||||
列表页读取 `myFeedback()` 并生成详情链接。详情页从 URL 读取 ID、重读列表并精确匹配；未匹配显示“反馈记录不存在或无权查看”。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/feedback-pages.test.js tests/pending-pages.test.js tests/public-static-pages.test.js tests/pc-scope.test.js
|
||||
node --check public/js/feedback-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 导航、规划和收尾验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `help.html`
|
||||
- Modify: `profile-services.html`
|
||||
- Modify: `docs/PC接口对接规划.md`
|
||||
- Modify: `tests/stage6-navigation.test.js`
|
||||
- Modify: `docs/superpowers/plans/2026-07-29-feedback-tickets.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Task 1–3 的真实反馈闭环。
|
||||
|
||||
- [ ] **Step 1: 写失败的导航测试**
|
||||
|
||||
断言：
|
||||
|
||||
- 帮助中心可直接进入提交工单和我的工单；
|
||||
- 服务中心可进入意见反馈；
|
||||
- 所有入口不再被 pending 状态拦截；
|
||||
- 不存在独立 ticket API、反馈标题或手填 `feedbackId` 的入口。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/stage6-navigation.test.js tests/public-static-pages.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，帮助中心尚未开放我的工单入口或旧 pending 断言仍存在。
|
||||
|
||||
- [ ] **Step 3: 更新入口和规划**
|
||||
|
||||
规划记录：
|
||||
|
||||
- `AppFeedbackBody` 三个字段来源与提交时机；
|
||||
- `FeedbackVo` 可见字段、内部隐藏字段和四种处理状态；
|
||||
- 无独立工单 path，四个页面共用反馈记录；
|
||||
- 提交后重读、详情精确匹配、401/403 和隐私边界；
|
||||
- 后端没有用户侧回复、追问、关闭或删除接口，继续阻断。
|
||||
|
||||
- [ ] **Step 4: 聚焦和全量验证**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/feedback-pages.test.js tests/api-client-contract.test.js tests/pending-pages.test.js tests/public-static-pages.test.js tests/pc-scope.test.js tests/stage6-navigation.test.js
|
||||
npm test
|
||||
node --check public/js/feedback-pages.js
|
||||
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
|
||||
```
|
||||
|
||||
Expected: 全部 PASS。
|
||||
|
||||
- [ ] **Step 5: 浏览器只读验证**
|
||||
|
||||
使用真实登录态验证四个页面、我的反馈列表、无记录详情、隐私和控制台错误。未经用户本轮明确授权，不提交真实反馈。
|
||||
@@ -0,0 +1,266 @@
|
||||
# 家谱加入申请与审核 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 页面闭环。
|
||||
|
||||
**Architecture:** `utils/ApiClient.js` 已拥有本批全部 PC path/body。新增 `join-pages.js` 负责可申请家谱选择、申请表单、我的申请和撤销；新增 `join-review-pages.js` 负责当前家谱待审核列表和通过/拒绝。两个 UMD 模块只使用响应中的字符串 ID，写入后重读对应列表。
|
||||
|
||||
**Tech Stack:** 静态 HTML、原生 JavaScript UMD、Axios、Node `node:test`。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 后端 `D:\WorkSpace\Java\Genealogy` 全程只读。
|
||||
- 只调用 `/genealogy/pc/**`。
|
||||
- 家谱 ID 和申请 ID 必须来自 PC 响应或当前家谱上下文，不能手填。
|
||||
- `inviterUserId` 没有安全 PC 来源，不展示、不发送。
|
||||
- 所有写操作防重复，401 清登录态，403 保留登录态。
|
||||
- 每项生产行为先运行失败测试，再最小实现。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 申请数据边界
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/join-pages.test.js`
|
||||
- Create: `public/js/join-pages.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `genealogyOptions(query)`、`applyToGenealogy(genealogyId, body)`、`myGenealogyJoinApplies()`、`cancelGenealogyJoinApply(applyId)`
|
||||
- Produces:
|
||||
- `normalizeJoinGenealogy(item)`
|
||||
- `buildJoinApplyBody(values)`
|
||||
- `validateJoinApplyBody(body)`
|
||||
- `normalizeJoinApply(item)`
|
||||
- `normalizeJoinApplies(data)`
|
||||
- `renderJoinGenealogyOptions(data)`
|
||||
- `renderMyJoinApplies(data)`
|
||||
|
||||
- [ ] **Step 1: 写失败的纯行为测试**
|
||||
|
||||
用完整 `AppGenealogyVo` 和 `GenealogyJoinApplyVo` 字面量验证：
|
||||
|
||||
```js
|
||||
assert.deepEqual(JoinPages.buildJoinApplyBody({
|
||||
applicantName: ' 叶子 ',
|
||||
phone: ' 19181970173 ',
|
||||
relationDesc: ' 族亲 ',
|
||||
applyReason: ' 申请加入 ',
|
||||
inviterUserId: 'must-drop'
|
||||
}), {
|
||||
applicantName: '叶子',
|
||||
phone: '19181970173',
|
||||
relationDesc: '族亲',
|
||||
applyReason: '申请加入'
|
||||
});
|
||||
```
|
||||
|
||||
断言：
|
||||
|
||||
- `applicantName <= 50`、`phone <= 30`、`relationDesc <= 100`、`applyReason <= 500`。
|
||||
- 可申请家谱必须有稳定 `genealogyId/genealogyName/surname`，停用家谱拒绝。
|
||||
- 申请必须有稳定 `applyId/genealogyId` 和 `status`；状态只允许 `0/1/2/3`。
|
||||
- 安全数字长 ID 只接受字符串；不安全 number 拒绝。
|
||||
- 普通用户列表不展示内部用户 ID、邀请人 ID、审核人 ID或原始 JSON。
|
||||
- 只有 `status=0` 渲染撤销按钮。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-pages.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，模块不存在。
|
||||
|
||||
- [ ] **Step 3: 最小实现纯函数**
|
||||
|
||||
所有可见文本使用 `escapeHtml`；响应任一必需字段无效时拒绝该条，数组包含非法元素时整批返回空数组。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-pages.test.js
|
||||
node --check public/js/join-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 申请页面与我的申请
|
||||
|
||||
**Files:**
|
||||
- Modify: `join-genealogy.html`
|
||||
- Modify: `profile-join-family.html`
|
||||
- Modify: `public/js/join-pages.js`
|
||||
- Modify: `tests/join-pages.test.js`
|
||||
- Modify: `tests/pending-pages.test.js`
|
||||
- Modify: `tests/pc-scope.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `initJoinApplyPage()`、`initMyJoinAppliesPage()`
|
||||
|
||||
- [ ] **Step 1: 写失败的页面行为测试**
|
||||
|
||||
断言：
|
||||
|
||||
- 两页均不再 pending，并加载 `join-pages.js`。
|
||||
- `join-genealogy.html` 有关键词搜索、后端家谱选项、申请资料表单；不存在 `genealogyId/inviterUserId/applyId` 文本输入。
|
||||
- `profile-join-family.html` 有我的申请列表和刷新入口；申请 ID 只存在于响应渲染按钮属性。
|
||||
- 页面没有邀请码输入或“分享码”伪语义。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-pages.test.js tests/pending-pages.test.js tests/pc-scope.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，页面仍 pending/缺少真实行为。
|
||||
|
||||
- [ ] **Step 3: 实现申请和撤销**
|
||||
|
||||
`join-genealogy.html`：
|
||||
|
||||
1. 读取 `genealogyOptions({keyword})`。
|
||||
2. 用户只能点击响应卡片选择家谱，内部保存字符串 `genealogyId`。
|
||||
3. 构造并校验申请 body。
|
||||
4. 提交后重读 `myGenealogyJoinApplies()`，必须找到同一响应 `applyId`。
|
||||
5. 跳转 `profile-join-family.html`。
|
||||
|
||||
`profile-join-family.html`：
|
||||
|
||||
1. 读取并渲染我的申请。
|
||||
2. 只有待审核申请显示撤销。
|
||||
3. 二次确认后调用撤销接口并重读列表，确保该申请不再为待审核。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-pages.test.js tests/pending-pages.test.js tests/pc-scope.test.js
|
||||
node --check public/js/join-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 管理员审核
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/join-review-pages.test.js`
|
||||
- Create: `public/js/join-review-pages.js`
|
||||
- Modify: `profile-join-review.html`
|
||||
- Modify: `tests/pending-pages.test.js`
|
||||
- Modify: `tests/pc-scope.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `genealogyDetail(genealogyId)`、`pendingGenealogyJoinApplies(genealogyId)`、`auditGenealogyJoinApply(genealogyId, applyId, body)`
|
||||
- Produces:
|
||||
- `getCurrentGenealogyId(search)`
|
||||
- `buildJoinAuditBody(values)`
|
||||
- `validateJoinAuditBody(body)`
|
||||
- `renderPendingJoinApplies(data, canManage)`
|
||||
- `initJoinReviewPage()`
|
||||
|
||||
- [ ] **Step 1: 写失败的审核行为测试**
|
||||
|
||||
```js
|
||||
assert.deepEqual(JoinReviewPages.buildJoinAuditBody({
|
||||
status: '2',
|
||||
auditRemark: ' 资料不一致 ',
|
||||
applyId: 'must-drop'
|
||||
}), {
|
||||
status: '2',
|
||||
auditRemark: '资料不一致'
|
||||
});
|
||||
```
|
||||
|
||||
断言：
|
||||
|
||||
- `status` 只允许 `1/2`，`auditRemark <= 500`。
|
||||
- 页面只从 URL/`ProfileUI` 读取家谱 ID。
|
||||
- 只有 `genealogyDetail.canManage=true` 显示审核动作。
|
||||
- 待审核列表显示申请人名称、申请手机号、关系和原因，但隐藏内部用户 ID、邀请人/审核人 ID。
|
||||
- 通过和拒绝按钮使用响应中的稳定 `applyId`。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-review-pages.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，模块不存在且页面仍 pending。
|
||||
|
||||
- [ ] **Step 3: 实现审核页面**
|
||||
|
||||
加载当前家谱详情和待审核列表；没有上下文时阻止请求并返回家谱选择入口。点击通过使用 `{status:'1'}`；拒绝要求输入可选审核说明并使用 `{status:'2', auditRemark}`。审核成功后重读待审核列表，确保同一 `applyId` 不再存在。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-review-pages.test.js tests/pending-pages.test.js tests/pc-scope.test.js
|
||||
node --check public/js/join-review-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 导航、规划与验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `profile-families.html`
|
||||
- Modify: `profile-family-admin.html`
|
||||
- Modify: `profile.html`
|
||||
- Modify: `tests/stage6-navigation.test.js`
|
||||
- Modify: `docs/PC接口对接规划.md`
|
||||
- Modify: `docs/superpowers/plans/2026-07-29-genealogy-join-review.md`
|
||||
|
||||
- [ ] **Step 1: 写失败的导航测试**
|
||||
|
||||
断言我的家谱入口可达申请页，家谱管理入口携带上下文进入审核页；不存在指向手填家谱 ID 或邀请码页面的入口。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/stage6-navigation.test.js tests/pending-pages.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，审核导航尚未稳定携带家谱上下文。
|
||||
|
||||
- [ ] **Step 3: 开放导航并更新规划**
|
||||
|
||||
记录申请/审核 DTO、VO、权限、状态、字段来源、写后重读和 `inviterUserId` 阻断。
|
||||
|
||||
- [ ] **Step 4: 聚焦和全量验证**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/join-pages.test.js tests/join-review-pages.test.js tests/api-client-contract.test.js tests/pending-pages.test.js tests/pc-scope.test.js tests/stage6-navigation.test.js
|
||||
npm test
|
||||
node --check public/js/join-pages.js
|
||||
node --check public/js/join-review-pages.js
|
||||
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
|
||||
```
|
||||
|
||||
Expected: 全部 PASS。
|
||||
|
||||
- [ ] **Step 5: 浏览器验证并报告**
|
||||
|
||||
真实账号验证可申请家谱列表、我的申请空状态、无家谱上下文审核分支、隐私和控制台错误。未经用户明确授权，不提交或审核真实申请。
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# 帮助中心 PC 接口对接计划
|
||||
|
||||
目标：把现有 `help.html` 的示例问答替换为后端正式 PC 帮助文章列表和详情，不混入官网文章、推广或家谱业务。
|
||||
|
||||
## 全局约束
|
||||
|
||||
- 只调用 `GET /genealogy/pc/help-articles` 和 `GET /genealogy/pc/help-articles/{helpId}`。
|
||||
- 后端控制器未标记匿名访问，部署环境要求登录；两个接口发送当前 PC token。
|
||||
- `helpCategory` 是唯一 Query 字段；`helpId` 只能来自列表响应。
|
||||
- 展示字段仅为 `helpCategory`、`helpTitle`、`helpContent`、`viewCount`。
|
||||
- `coverOssId`、`sortOrder`、`status`、`remark` 不展示，不允许用户输入 ID。
|
||||
- 正文转义后展示，不执行响应中的 HTML。
|
||||
- 后端项目只读。
|
||||
|
||||
## 任务 1：冻结客户端契约
|
||||
|
||||
- 在 `tests/api-client-contract.test.js` 先增加失败测试。
|
||||
- 在 `utils/ApiClient.js` 增加 `helpArticles(query)` 与 `helpArticleDetail(helpId)`。
|
||||
- 验证 method、path、Query 白名单、登录鉴权和长 ID 字符串。
|
||||
|
||||
## 任务 2：实现帮助文章边界
|
||||
|
||||
- 新增 `tests/help-pages.test.js` 并先观察失败。
|
||||
- 新增 `public/js/help-pages.js`。
|
||||
- 校验完整 `HelpArticleVo` 输入，只向页面返回安全展示字段。
|
||||
- 列表任一元素非法时整批失败；详情必须与请求 ID 一致。
|
||||
- 转义标题、分类和正文。
|
||||
|
||||
## 任务 3：开放帮助中心
|
||||
|
||||
- 先用页面契约测试证明现有示例内容不符合真实接口状态。
|
||||
- 修改 `help.html`，提供加载、空、成功和失败状态。
|
||||
- 展开文章时调用详情接口，不制造编辑、邀请或后台操作。
|
||||
|
||||
## 任务 4：规划与验证
|
||||
|
||||
- 更新 `docs/PC接口对接规划.md` 的字段来源、页面时机与阶段 7 进度。
|
||||
- 运行帮助中心专项测试、全量测试、语法检查和 `diff --check`。
|
||||
- 浏览器验证真实列表/空状态和控制台。
|
||||
@@ -0,0 +1,249 @@
|
||||
# VIP 套餐与订单 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:** 在服务中心开放 VIP 套餐查看、响应选项创建订单和我的订单刷新闭环，不制造支付或取消能力。
|
||||
|
||||
**Architecture:** `utils/ApiClient.js` 唯一拥有 `/genealogy/pc/vip/**` 的三个接口；新增 `vip-pages.js` 规范化套餐、家谱选项和订单，使用响应中的字符串 ID 构造 `AppVipOrderBody`。`profile-services.html` 作为唯一 VIP 页面，只提供套餐选择、可选家谱选择、创建订单和订单刷新。
|
||||
|
||||
**Tech Stack:** 静态 HTML、原生 JavaScript UMD、Axios、Node `node:test`。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 后端 `D:\WorkSpace\Java\Genealogy` 全程只读。
|
||||
- 只调用 `GET /genealogy/pc/vip/packages`、`POST /genealogy/pc/vip/orders`、`GET /genealogy/pc/vip/orders`。
|
||||
- `packageId` 只能来自套餐响应；`genealogyId` 只能来自 `genealogiesMine()` 响应，不提供文本输入。
|
||||
- 页面不提供未经确认的支付方式选择；请求省略 `payType`，由后端默认 `wechat`。
|
||||
- 不显示立即支付、模拟支付成功、取消订单、退款或关闭订单操作。
|
||||
- 创建成功后重读订单列表并精确匹配同一 `orderId`。
|
||||
- 不展示 `appUserId`、用户手机号、内部原始 JSON。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: ApiClient VIP 契约
|
||||
|
||||
**Files:**
|
||||
- Modify: `utils/ApiClient.js`
|
||||
- Modify: `tests/api-client-contract.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `vipPackages()`、`createVipOrder(body)`、`vipOrders()`
|
||||
|
||||
- [ ] **Step 1: 写失败契约测试**
|
||||
|
||||
```js
|
||||
await client.vipPackages();
|
||||
await client.createVipOrder({
|
||||
packageId: '2062179707935264769',
|
||||
genealogyId: '2062179707935264770',
|
||||
payType: 'wechat',
|
||||
appUserId: 'must-drop',
|
||||
payStatus: 'must-drop'
|
||||
});
|
||||
await client.vipOrders();
|
||||
|
||||
assert.deepEqual(calls.map((config) => [config.method, config.url, config.data]), [
|
||||
['get', '/genealogy/pc/vip/packages', undefined],
|
||||
['post', '/genealogy/pc/vip/orders', {
|
||||
packageId: '2062179707935264769',
|
||||
genealogyId: '2062179707935264770',
|
||||
payType: 'wechat'
|
||||
}],
|
||||
['get', '/genealogy/pc/vip/orders', undefined]
|
||||
]);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run: `node --test tests/api-client-contract.test.js`
|
||||
|
||||
Expected: FAIL，VIP 方法不存在。
|
||||
|
||||
- [ ] **Step 3: 最小实现**
|
||||
|
||||
```js
|
||||
vipPackages: function () {
|
||||
return request('GET', '/genealogy/pc/vip/packages');
|
||||
},
|
||||
createVipOrder: function (body) {
|
||||
return request('POST', '/genealogy/pc/vip/orders', {
|
||||
body: pickDefined(body, ['packageId', 'genealogyId', 'payType'])
|
||||
});
|
||||
},
|
||||
vipOrders: function () {
|
||||
return request('GET', '/genealogy/pc/vip/orders');
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run: `node --test tests/api-client-contract.test.js`
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 套餐、家谱选项和订单数据边界
|
||||
|
||||
**Files:**
|
||||
- Create: `public/js/vip-pages.js`
|
||||
- Create: `tests/vip-pages.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces:
|
||||
- `normalizeVipPackage(item)`
|
||||
- `normalizeVipPackages(data)`
|
||||
- `normalizeGenealogyOption(item)`
|
||||
- `buildVipOrderBody(values)`
|
||||
- `validateVipOrderBody(body)`
|
||||
- `normalizeVipOrder(item)`
|
||||
- `normalizeVipOrders(data)`
|
||||
- `renderVipPackages(data, selectedPackageId)`
|
||||
- `renderGenealogyOptions(data)`
|
||||
- `renderVipOrders(data)`
|
||||
|
||||
- [ ] **Step 1: 写失败纯行为测试**
|
||||
|
||||
使用完整 `VipPackageVo`、`VipOrderVo` 字面量断言：
|
||||
|
||||
- 套餐要求稳定字符串 `packageId`、非空名称、`packageType=vip/storage`、`durationUnit=permanent/day/month/year`、非负价格、`status=0`；
|
||||
- 停用套餐和不安全数字长 ID 不渲染；
|
||||
- 家谱选项要求稳定字符串 `genealogyId` 和非空 `genealogyName`；
|
||||
- body 只保留 `packageId/genealogyId/payType`，页面默认构造不包含 `payType`；
|
||||
- 必须选择有效套餐；可选家谱必须是安全字符串 ID；若显式提供 `payType` 只允许已确认 `wechat`；
|
||||
- 订单要求稳定 `orderId/packageId`、订单号、套餐名、非负金额、`payStatus=0/1/2/3`、`status=0/1`；
|
||||
- 渲染不出现用户 ID、手机号、原始 JSON，不出现支付/取消/退款按钮。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run: `node --test tests/vip-pages.test.js`
|
||||
|
||||
Expected: FAIL，模块不存在。
|
||||
|
||||
- [ ] **Step 3: 最小实现纯函数**
|
||||
|
||||
支付状态：
|
||||
|
||||
```js
|
||||
{ '0': '待支付', '1': '已支付', '2': '已关闭', '3': '已退款' }
|
||||
```
|
||||
|
||||
套餐类型：
|
||||
|
||||
```js
|
||||
{ vip: '会员套餐', storage: '存储扩容' }
|
||||
```
|
||||
|
||||
套餐和订单金额保留后端字符串语义，不进行浮点运算。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/vip-pages.test.js
|
||||
node --check public/js/vip-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 服务中心真实 VIP 闭环
|
||||
|
||||
**Files:**
|
||||
- Modify: `profile-services.html`
|
||||
- Modify: `public/js/vip-pages.js`
|
||||
- Modify: `tests/vip-pages.test.js`
|
||||
- Modify: `tests/pending-pages.test.js`
|
||||
- Modify: `tests/pc-scope.test.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `initVipPage()`、`init()`
|
||||
|
||||
- [ ] **Step 1: 写失败页面行为测试**
|
||||
|
||||
断言：
|
||||
|
||||
- 服务中心不再 pending，加载 `vip-pages.js`；
|
||||
- 有套餐列表、只读选中提示、可选家谱下拉、订单表单、刷新订单和订单列表；
|
||||
- 不存在 `packageId/genealogyId/orderId` 文本或数字输入；
|
||||
- 不存在 `payType` 选择器以及支付、取消、退款、模拟成功按钮；
|
||||
- 脚本并行读取套餐、我的家谱和订单；
|
||||
- 创建后重读订单并精确匹配提交响应 `orderId`。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/vip-pages.test.js tests/pending-pages.test.js tests/pc-scope.test.js
|
||||
```
|
||||
|
||||
Expected: FAIL，服务中心仍为 pending 且允许手填 ID。
|
||||
|
||||
- [ ] **Step 3: 实现页面初始化**
|
||||
|
||||
1. 401 跳转登录，403 保留登录态；
|
||||
2. `Promise.all([vipPackages(), genealogiesMine(), vipOrders()])` 读取页面数据；
|
||||
3. 点击套餐卡保存响应中的字符串 `packageId`；
|
||||
4. 家谱下拉只使用 `genealogiesMine()` 选项，空值表示不关联家谱；
|
||||
5. 表单提交使用 `writePending` 锁；
|
||||
6. 创建响应必须规范化；
|
||||
7. 重读 `vipOrders()` 并找到同一 `orderId`；
|
||||
8. 刷新订单列表并展示“订单已创建；当前 PC 暂未开放在线支付”。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/vip-pages.test.js tests/pending-pages.test.js tests/pc-scope.test.js
|
||||
node --check public/js/vip-pages.js
|
||||
```
|
||||
|
||||
Expected: PASS。
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 导航、规划和收尾验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `profile.html`
|
||||
- Modify: `docs/PC接口对接规划.md`
|
||||
- Modify: `tests/stage6-navigation.test.js`
|
||||
- Modify: `docs/superpowers/plans/2026-07-29-vip-packages-orders.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Task 1–3 的 VIP 套餐与订单闭环。
|
||||
|
||||
- [ ] **Step 1: 写失败导航测试**
|
||||
|
||||
断言个人中心服务入口可进入 `profile-services.html`，服务页真实开放并且所有 VIP 业务都留在该唯一 owner 页面。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run: `node --test tests/stage6-navigation.test.js tests/pending-pages.test.js`
|
||||
|
||||
Expected: FAIL，服务页仍 pending 或未加载真实脚本。
|
||||
|
||||
- [ ] **Step 3: 更新规划**
|
||||
|
||||
记录 `AppVipOrderBody`、`VipPackageVo`、`VipOrderVo` 的字段来源、枚举、隐藏字段、写后重读和支付能力阻断；阶段 7 标记 VIP 批次完成。
|
||||
|
||||
- [ ] **Step 4: 聚焦和全量验证**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/vip-pages.test.js tests/api-client-contract.test.js tests/pending-pages.test.js tests/pc-scope.test.js tests/stage6-navigation.test.js
|
||||
npm test
|
||||
node --check public/js/vip-pages.js
|
||||
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
|
||||
```
|
||||
|
||||
Expected: 全部 PASS。
|
||||
|
||||
- [ ] **Step 5: 浏览器只读验证**
|
||||
|
||||
真实登录态验证套餐、家谱下拉、订单空/有数据态、无伪支付动作和控制台错误。未经用户本轮明确授权，不创建真实订单。
|
||||
@@ -0,0 +1,424 @@
|
||||
# 官网资讯 PC 接口对接实施计划
|
||||
|
||||
> **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:** 将 `news.html` 与 `article-detail.html` 接入公开 PC 站点文章列表接口，交付可筛选列表与精确详情闭环。
|
||||
|
||||
**Architecture:** `utils/ApiClient.js` 独占 PC path、公开鉴权标记和 Query 校验；`public/js/site-news-pages.js` 独占 `SiteArticleVo` 规范化、渲染和页面初始化。后端没有单条详情接口，详情页使用 URL 中由列表响应生成的字符串 ID 重读列表并精确匹配。
|
||||
|
||||
**Tech Stack:** 原生 HTML/CSS/JavaScript、现有 Axios 请求层、Node `node:test`。
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- 后端 `D:\WorkSpace\Java\Genealogy` 只读，不得修改。
|
||||
- 只使用 `/genealogy/pc/site/articles`，不得调用 APP、后台管理或家谱谱文 CRUD 接口。
|
||||
- 本批只修改 `news.html` 与 `article-detail.html`，不混改其他静态内容页。
|
||||
- 业务 ID 始终保持字符串，不提供手填 ID 或 OSS ID。
|
||||
- `articleType` 只允许 `news/notice/download`；`limit` 固定为 100 且客户端只允许 1–100 的整数。
|
||||
- 公开请求设置 `auth: false`；其 401/403 不清理既有 token、不跳转登录。
|
||||
- 响应只接受直接 `SiteArticleVo[]`；旧字段、分页对象和任一非法元素均使整批失败。
|
||||
- 所有响应文本 HTML 转义；正文仅保留换行；外链只允许绝对 HTTP/HTTPS。
|
||||
- 当前工作区由用户明确授权直接施工；不得 stage、commit、push 或创建 PR。
|
||||
- 子代理仅用于探索和只读复核；业务代码修改、取舍与最终验证由主代理完成。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 修正公开请求的登录态隔离
|
||||
|
||||
**Files:**
|
||||
- Modify: `tests/request-auth-state.test.js`
|
||||
- Modify: `utils/AxiosRequestUtil.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `createRequester({ getToken, onUnauthorized, axiosInstance })`
|
||||
- Produces: `request(method, path, { auth: false })` 不发送 Authorization，且 HTTP/业务 401 均不调用 `onUnauthorized`
|
||||
|
||||
- [ ] **Step 1: 写失败测试**
|
||||
|
||||
在 `tests/request-auth-state.test.js` 引入 `../utils/AxiosRequestUtil.js`，新增两个真实请求层用例：
|
||||
|
||||
```js
|
||||
test('public HTTP 401 neither sends nor clears the stored login token', async () => {
|
||||
let storedToken = 'access-token';
|
||||
let seenRequest;
|
||||
const requester = AxiosRequestUtil.createRequester({
|
||||
baseUrl: 'https://api.example.test',
|
||||
clientId: 'web-pc',
|
||||
getToken() { return storedToken; },
|
||||
onUnauthorized() { storedToken = ''; },
|
||||
axiosInstance: {
|
||||
request(config) {
|
||||
seenRequest = config;
|
||||
return Promise.reject({
|
||||
message: 'Request failed',
|
||||
response: { status: 401, data: { code: 401, msg: '认证失败' } }
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
await assert.rejects(requester('GET', '/public', { auth: false }));
|
||||
assert.equal(seenRequest.headers.Authorization, undefined);
|
||||
assert.equal(storedToken, 'access-token');
|
||||
});
|
||||
|
||||
test('public business 401 preserves the stored login token', async () => {
|
||||
let storedToken = 'access-token';
|
||||
const requester = AxiosRequestUtil.createRequester({
|
||||
baseUrl: 'https://api.example.test',
|
||||
clientId: 'web-pc',
|
||||
getToken() { return storedToken; },
|
||||
onUnauthorized() { storedToken = ''; },
|
||||
axiosInstance: {
|
||||
request() {
|
||||
return Promise.resolve({
|
||||
data: { code: 401, msg: '认证失败' }
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
await assert.rejects(requester('GET', '/public', { auth: false }));
|
||||
assert.equal(storedToken, 'access-token');
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/request-auth-state.test.js
|
||||
```
|
||||
|
||||
Expected: 新增用例因 `handleUnauthorized` 未区分 `auth: false` 而失败。
|
||||
|
||||
- [ ] **Step 3: 写最小实现**
|
||||
|
||||
在 `utils/AxiosRequestUtil.js` 的单次 `request` 闭包内，使 HTTP catch 与业务解包 catch 只在 `req.auth !== false` 时调用 `handleUnauthorized`：
|
||||
|
||||
```js
|
||||
if (req.auth !== false) handleUnauthorized(status);
|
||||
```
|
||||
|
||||
不得改变默认鉴权请求的现有行为。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/request-auth-state.test.js
|
||||
```
|
||||
|
||||
Expected: 现有默认 401 清 token、403 保留 token，以及新增公开请求用例全部通过。
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 增加 PC 站点文章 ApiClient 契约
|
||||
|
||||
**Files:**
|
||||
- Modify: `tests/api-client-contract.test.js`
|
||||
- Modify: `utils/ApiClient.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `siteArticles(query?: { articleType?: 'news'|'notice'|'download', limit?: number }): Promise<Array>`
|
||||
- Request: `GET /genealogy/pc/site/articles`, `{ auth: false, query }`
|
||||
|
||||
- [ ] **Step 1: 写失败测试**
|
||||
|
||||
在公开方法清单中增加 `siteArticles`，并新增契约用例：
|
||||
|
||||
```js
|
||||
await client.siteArticles({
|
||||
articleType: 'notice',
|
||||
limit: 100,
|
||||
keyword: 'must-drop'
|
||||
});
|
||||
|
||||
assert.deepEqual(seen, {
|
||||
method: 'get',
|
||||
url: '/genealogy/pc/site/articles',
|
||||
params: { articleType: 'notice', limit: 100 },
|
||||
authorization: undefined
|
||||
});
|
||||
|
||||
assert.throws(
|
||||
() => client.siteArticles({ articleType: 'culture', limit: 100 }),
|
||||
/不支持的资讯类型/
|
||||
);
|
||||
assert.throws(
|
||||
() => client.siteArticles({ limit: 101 }),
|
||||
/资讯数量限制/
|
||||
);
|
||||
```
|
||||
|
||||
同时覆盖 `limit` 的 `0`、小数、字符串和负数，确保只接受 1–100 的 Number 整数；省略 `articleType` 时只发送 `{ limit: 100 }`。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/api-client-contract.test.js
|
||||
```
|
||||
|
||||
Expected: `siteArticles` 不存在。
|
||||
|
||||
- [ ] **Step 3: 写最小实现**
|
||||
|
||||
在 `utils/ApiClient.js` 增加 `siteArticles`：
|
||||
|
||||
```js
|
||||
siteArticles: function (query) {
|
||||
var source = query || {};
|
||||
var articleType = source.articleType === undefined || source.articleType === null
|
||||
? ''
|
||||
: String(source.articleType).trim();
|
||||
var limit = source.limit;
|
||||
var params = {};
|
||||
|
||||
if (articleType && ['news', 'notice', 'download'].indexOf(articleType) === -1) {
|
||||
throw new Error('不支持的资讯类型：' + articleType);
|
||||
}
|
||||
if (limit !== undefined &&
|
||||
(typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 100)) {
|
||||
throw new Error('资讯数量限制必须是 1 到 100 的整数');
|
||||
}
|
||||
if (articleType) params.articleType = articleType;
|
||||
if (limit !== undefined) params.limit = limit;
|
||||
return request('GET', '/genealogy/pc/site/articles', {
|
||||
auth: false,
|
||||
query: params
|
||||
});
|
||||
},
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/api-client-contract.test.js tests/request-auth-state.test.js
|
||||
```
|
||||
|
||||
Expected: 全部通过，且公开请求没有 Authorization Header。
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 实现站点资讯页面 owner
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/site-news-pages.test.js`
|
||||
- Create: `public/js/site-news-pages.js`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `GenealogyApi.defaultClient.siteArticles({ articleType?, limit: 100 })`
|
||||
- Produces:
|
||||
- `normalizeArticle(item)`
|
||||
- `normalizeArticleList(data)`
|
||||
- `normalizeArticleType(value)`
|
||||
- `normalizeExternalUrl(value)`
|
||||
- `readArticleId(search)`
|
||||
- `renderArticleList(data)`
|
||||
- `renderArticleDetail(item)`
|
||||
- `loadArticles(api, articleType?)`
|
||||
- `loadArticleDetail(api, articleId)`
|
||||
- `init()`
|
||||
|
||||
- [ ] **Step 1: 写完整 RED 测试**
|
||||
|
||||
创建 `tests/site-news-pages.test.js`，使用完整 `SiteArticleVo` fixture：
|
||||
|
||||
```js
|
||||
{
|
||||
articleId: '2062179707935264769',
|
||||
articleType: 'notice',
|
||||
articleTitle: '平台公告',
|
||||
articleSummary: '公告摘要',
|
||||
articleContent: '第一行\n第二行',
|
||||
coverOssId: '2062179707935264701',
|
||||
externalUrl: 'https://example.com/notice',
|
||||
publishTime: '2026-07-30 09:00:00',
|
||||
sortOrder: 1,
|
||||
status: '0',
|
||||
remark: 'internal-only'
|
||||
}
|
||||
```
|
||||
|
||||
必须覆盖：
|
||||
|
||||
- 安全长 ID 字符串保留；不安全 Number、零、空 ID 拒绝。
|
||||
- `articleType` 只接受 `news/notice/download`。
|
||||
- 标题必填、状态必须为 `0`。
|
||||
- 直接数组全有或全无；`{ rows: [...] }` 拒绝。
|
||||
- 规范化结果不包含 `coverOssId/sortOrder/status/remark`。
|
||||
- 列表 HTML 指向 `article-detail.html?articleId=2062179707935264769`。
|
||||
- 标题、摘要、正文转义；正文换行变为 `<br />`。
|
||||
- 危险、相对和 `data:` 外链不渲染；合法 HTTP/HTTPS 使用 `noopener noreferrer`。
|
||||
- `loadArticles(api, 'notice')` 调用 `{ articleType: 'notice', limit: 100 }`。
|
||||
- `loadArticles(api, '')` 调用 `{ limit: 100 }`。
|
||||
- `loadArticleDetail` 只返回同 ID；未匹配抛出“资讯不存在或已下线”。
|
||||
- 非法详情 ID 在调用 API 前抛出“资讯编号无效”。
|
||||
- `readArticleId('?articleId=...')` 只返回安全字符串。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/site-news-pages.test.js
|
||||
```
|
||||
|
||||
Expected: 模块不存在。
|
||||
|
||||
- [ ] **Step 3: 写 UMD 模块最小实现**
|
||||
|
||||
创建 UMD 模块：Node 环境导出 `module.exports = factory(root)`；浏览器环境挂到 `root.SiteNewsPages`，并在 `DOMContentLoaded` 调用 `root.SiteNewsPages.init()`。关键行为：
|
||||
|
||||
```js
|
||||
async function loadArticles(api, articleType) {
|
||||
var type = normalizeArticleType(articleType);
|
||||
var query = { limit: 100 };
|
||||
var data;
|
||||
var items;
|
||||
|
||||
if (articleType && !type) throw new Error('资讯分类无效');
|
||||
if (type) query.articleType = type;
|
||||
data = await api.siteArticles(query);
|
||||
items = normalizeArticleList(data);
|
||||
if (!Array.isArray(data) || items.length !== data.length) {
|
||||
throw new Error('资讯列表响应无效');
|
||||
}
|
||||
return items;
|
||||
}
|
||||
```
|
||||
|
||||
`init()`：
|
||||
|
||||
- `[data-site-news-page]`：从 `location.search` 读取 `articleType`，加载并渲染 `[data-site-news-list]`。
|
||||
- `[data-site-article-page]`：读取 `articleId`；非法时不发请求；合法时精确重读并渲染 `[data-site-article-detail]`。
|
||||
- 所有失败只更新对应区域和 `[data-site-*-status]`，不跳转、不清 token。
|
||||
|
||||
- [ ] **Step 4: 运行 GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/site-news-pages.test.js tests/api-client-contract.test.js tests/request-auth-state.test.js
|
||||
```
|
||||
|
||||
Expected: 全部通过。
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 接入 HTML、规划并完成验收
|
||||
|
||||
**Files:**
|
||||
- Modify: `news.html`
|
||||
- Modify: `article-detail.html`
|
||||
- Modify: `tests/site-news-pages.test.js`
|
||||
- Modify: `tests/public-static-pages.test.js`
|
||||
- Modify: `tests/pc-scope.test.js`
|
||||
- Modify: `docs/PC接口对接规划.md`
|
||||
|
||||
**Interfaces:**
|
||||
- `news.html`: `[data-site-news-page]`, `[data-site-news-list]`, `[data-site-news-status]`
|
||||
- `article-detail.html`: `[data-site-article-page]`, `[data-site-article-detail]`, `[data-site-article-status]`
|
||||
|
||||
- [ ] **Step 1: 写 HTML 接入 RED 测试**
|
||||
|
||||
断言：
|
||||
|
||||
```js
|
||||
assert.match(newsPage, /data-site-news-page/);
|
||||
assert.match(newsPage, /data-site-news-list/);
|
||||
assert.match(newsPage, /news\.html\?articleType=news/);
|
||||
assert.match(newsPage, /news\.html\?articleType=notice/);
|
||||
assert.match(newsPage, /news\.html\?articleType=download/);
|
||||
assert.match(newsPage, /src="public\/js\/site-news-pages\.js"/);
|
||||
|
||||
assert.match(detailPage, /data-site-article-page/);
|
||||
assert.match(detailPage, /data-site-article-detail/);
|
||||
assert.match(detailPage, /src="public\/js\/site-news-pages\.js"/);
|
||||
assert.doesNotMatch(detailPage, /src="public\/js\/article-pages\.js"/);
|
||||
assert.doesNotMatch(newsPage + detailPage, /name="(?:articleId|coverOssId)"/);
|
||||
```
|
||||
|
||||
更新 `public-static-pages.test.js`，移除旧的固定 `#platform/#culture` 链接断言，改为真实分类入口和详情目标文件断言。
|
||||
|
||||
- [ ] **Step 2: 运行 RED**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --test tests/site-news-pages.test.js tests/public-static-pages.test.js tests/pc-scope.test.js
|
||||
```
|
||||
|
||||
Expected: HTML 尚未加载新模块、旧固定链接断言需迁移。
|
||||
|
||||
- [ ] **Step 3: 修改 HTML**
|
||||
|
||||
`news.html`：
|
||||
|
||||
- `<body data-site-news-page>`
|
||||
- 删除“当前为静态展示”文案和两条硬编码文章。
|
||||
- 列表容器初始化为“资讯内容加载中”。
|
||||
- 分类链接使用规格中的四个固定 URL。
|
||||
- 按顺序加载 `config.js`、`StorageUtil.js`、`axios.js`、`AxiosRequestUtil.js`、`ApiClient.js`、`page-effects.js`、`site-news-pages.js`。
|
||||
|
||||
`article-detail.html`：
|
||||
|
||||
- body 标记改为 `data-site-article-page`，避免与家谱谱文语义混用。
|
||||
- 将 hero 和正文合并到 `data-site-article-detail` 可替换容器。
|
||||
- 增加 `data-site-article-status`。
|
||||
- 加载 `site-news-pages.js`，不加载 `article-pages.js`。
|
||||
|
||||
- [ ] **Step 4: 更新规划**
|
||||
|
||||
在 `docs/PC接口对接规划.md` 第 7 节新增“官网资讯契约”，记录：
|
||||
|
||||
- method/path、公开鉴权、Query 枚举和 limit 范围。
|
||||
- `SiteArticleVo` 11 个字段的 R/I/S/A 分类、SQL 长度和默认值。
|
||||
- 列表直接数组、服务端排序、详情重读匹配。
|
||||
- YAML 只给通用响应且没有导出 `SiteArticleVo` Schema 的差异。
|
||||
- `coverOssId` 文件 URL 和站点文章单条详情接口仍阻断。
|
||||
|
||||
在阶段 7 增加第八批完成说明。
|
||||
|
||||
- [ ] **Step 5: 运行自动化验收**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
node --check public/js/site-news-pages.js
|
||||
node --check utils/ApiClient.js
|
||||
node --check utils/AxiosRequestUtil.js
|
||||
node --test tests/site-news-pages.test.js tests/api-client-contract.test.js tests/request-auth-state.test.js tests/public-static-pages.test.js tests/pc-scope.test.js
|
||||
node --test tests/*.test.js
|
||||
git -c safe.directory=D:/WorkSpace/Web/jiapu diff --check
|
||||
```
|
||||
|
||||
Expected: 所有命令退出码 0。
|
||||
|
||||
- [ ] **Step 6: 浏览器验收**
|
||||
|
||||
启动临时本地静态服务器，验证：
|
||||
|
||||
1. 未登录打开 `news.html`，页面不跳登录。
|
||||
2. 真实列表、分类或空状态正确。
|
||||
3. 有数据时点击一个由响应生成的详情链接，详情 ID 精确匹配；无数据时记录真实空状态。
|
||||
4. 控制台没有业务脚本错误。
|
||||
5. 不点击外部链接。
|
||||
6. 停止服务器并删除临时辅助文件。
|
||||
|
||||
- [ ] **Step 7: 阶段报告**
|
||||
|
||||
按以下格式报告并停下：
|
||||
|
||||
```text
|
||||
Changed: 官网资讯列表、详情、公开请求语义和规划补充。
|
||||
Verified: 专项/全量测试数量及真实浏览器覆盖。
|
||||
Conflicts: YAML 通用响应与后端完整 VO/SQL 的差异。
|
||||
Blocked: 单条详情接口、封面文件 URL、仍无 PC Controller 的 pending 页面。
|
||||
```
|
||||
Reference in New Issue
Block a user