合并最新 master 并解决资源依赖图冲突
同步 mentor 已合入 master 的最新工程改动。 保留资源依赖图决策记录并整合 master 的新增决策。 # Conflicts: # docs/project-memory/shared-memory/decision-log.md
This commit is contained in:
@@ -36,7 +36,7 @@ Prefer the bundled Python helper for runnable examples: `scripts/genarrative_ext
|
||||
| Intent | Method and path | Required fields |
|
||||
| --- | --- | --- |
|
||||
| List/create projects | `GET/POST /api/external/v1/editor/projects` | create: optional `title` |
|
||||
| Save canvas | `PATCH /api/external/v1/editor/projects/{projectId}/canvas` | `viewport`, `layers` |
|
||||
| Save canvas | `PATCH /api/external/v1/editor/projects/{projectId}/canvas` | `viewport`, `layers`, `expectedRevision` |
|
||||
| Upload local media | `POST /api/external/v1/assets/direct-upload-tickets` -> OSS form -> `POST /api/external/v1/assets/objects/confirm` | ticket: `legacyPrefix`, `fileName`; confirm: `objectKey`, `assetKind` |
|
||||
| Read private media | `GET /api/external/v1/assets/read-url` | `objectKey` or `legacyPublicPath` |
|
||||
| Image generation | `POST /api/external/v1/editor/images/generations` | `prompt` |
|
||||
@@ -115,6 +115,8 @@ python3 .codex/skills/genarrative-external-editor-api/scripts/genarrative_extern
|
||||
|
||||
## Request Patterns
|
||||
|
||||
For image and icon generation, the request-body top-level `style` field controls deterministic post-processing and is distinct from `generationInputs.artSpec.style`, which describes visual style for prompting. Pass `style="pixelArt"` in Python or `"style": "pixelArt"` in JSON to enable pixel-art snapping on supported generation types; use `"none"` or omit the field otherwise. Verify compatibility and fallback semantics in `references/api-selection.md`.
|
||||
|
||||
For Python callers, prefer:
|
||||
|
||||
```python
|
||||
@@ -338,7 +340,7 @@ Character image generation (including character redraw through `kind: "character
|
||||
|
||||
- Apply the returned `project` and media snapshots before interpreting optional derivatives: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. When `warning.code` is `postprocess-failed-source-preserved`, the saved provider source image is the authoritative main result. Character output has no transparent derivative; icon spritesheet and UI extraction output have neither a transparent spritesheet nor slices. Display `warning.reason` directly, and do not synthesize missing derivatives or restart generation.
|
||||
- `sliceWarning` is a separate condition used only when transparent spritesheet post-processing succeeded but automatic slicing failed. Keep `sliceWarning.reason` as the original diagnostic and continue using the complete transparent spritesheet; a UI may add context when displaying it, but must not rewrite the stored reason.
|
||||
- The service contract keeps `warning` and `sliceWarning` mutually exclusive. As defensive handling for a malformed response containing both, treat the general `warning` as authoritative and do not misclassify the source-preserved result as a slicing-only warning.
|
||||
- `warning` and `sliceWarning` are mutually exclusive only for `postprocess-failed-source-preserved`, because a failed transparent post-process never reaches slicing. Since 2026-07-29 a general `warning` may also come from image-style normalization (`unsupported-image-style`) or pixel-art snapping, and those can coexist with `sliceWarning` in the same response. Display both reasons; do not drop either one and do not misclassify a source-preserved result as a slicing-only warning.
|
||||
|
||||
For reusable transparent game/UI sheets, do not substitute ordinary image generation merely because it can draw several objects in one image. Use icon spritesheet generation when a stable visual-spec reference and `iconDescriptions` exist; use UI extraction only for an existing annotated UI design. Pass `screenColor: "auto"` unless the art direction requires one of the supported solid chroma colors. A client must verify the returned full sheet really contains transparency before treating it as a transparent spritesheet. If a source-preserved `warning` is present, do not register the opaque provider source as the requested transparent deliverable. When only `sliceWarning` is present, the full transparent sheet remains usable, but no individual slices may be claimed.
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@ Ask a follow-up only when two routes could both be correct and produce different
|
||||
| Load recent project | `GET /api/external/v1/editor/projects/recent` | API Key |
|
||||
| Get/delete project | `GET` or `DELETE /api/external/v1/editor/projects/{projectId}` | `projectId` |
|
||||
| Rename project | `PATCH /api/external/v1/editor/projects/{projectId}/metadata` | `title` |
|
||||
| Save canvas layout | `PATCH /api/external/v1/editor/projects/{projectId}/canvas` | `viewport`, `layers` |
|
||||
| Save canvas layout | `PATCH /api/external/v1/editor/projects/{projectId}/canvas` | `viewport`, `layers`, `expectedRevision` |
|
||||
| Add project resource | `POST /api/external/v1/editor/projects/{projectId}/resources` | `imageSrc`, `width`, `height`, `sourceType` |
|
||||
| Create upload ticket | `POST /api/external/v1/assets/direct-upload-tickets` | `legacyPrefix`, `fileName` |
|
||||
| Confirm uploaded object | `POST /api/external/v1/assets/objects/confirm` | `objectKey`, `assetKind` |
|
||||
@@ -75,15 +75,44 @@ Ask a follow-up only when two routes could both be correct and produce different
|
||||
|
||||
| User intent | Endpoint | Required fields | Common optional fields |
|
||||
| --- | --- | --- | --- |
|
||||
| Generate image/spec/character/UI/publication material | `POST /api/external/v1/editor/images/generations` | `prompt` | `kind`, `model`, `aspectRatio`, `imageSize`, `size`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
|
||||
| Generate image/spec/character/UI/publication material | `POST /api/external/v1/editor/images/generations` | `prompt` | `kind`, `style`, `model`, `aspectRatio`, `imageSize`, `size`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
|
||||
| Edit/redraw image | `POST /api/external/v1/editor/images/edits` | `prompt`, `sourceImageSrc` | `referenceImageSrcs`, `model`, `size`, `projectId`, `assetFolderId`, `assetLabel`, `sourceResourceId`, `targetLayerId`, `canvasCompletion` |
|
||||
| Generate icon spritesheet | `POST /api/external/v1/editor/icon-spritesheets/generations` | `referenceImageSrc`, `iconDescriptions` | `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
|
||||
| Generate icon spritesheet | `POST /api/external/v1/editor/icon-spritesheets/generations` | `referenceImageSrc`, `iconDescriptions` | `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
|
||||
| Extract assets from UI design | `POST /api/external/v1/editor/ui-designs/assets/extractions` | `sourceImageSrc`, `aspectRatio`, `imageSize` | `screenColor`, `model`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `spritesheetLabel`, `canvasCompletion` |
|
||||
| Generate character animation | `POST /api/external/v1/editor/character-animations/generations` | `sourceLayerId`, `sourceImageSrc`, `sourceWidth`, `sourceHeight`, `promptText`, `resolution`, `ratio`, `frameCount`, `durationSeconds`, `model` | `projectId`, `sourceResourceId`, `canvasCompletion`; then create a library asset from the first returned frame |
|
||||
| Generate video | `POST /api/external/v1/editor/videos/generations` | `prompt`, `model`, `aspectRatio`, `durationSeconds`, `resolution`, `mode`, `sound` | `referenceImageSrcs`, `referenceVideoSrcs`, `referenceAudioSrcs`, `webSearchEnabled`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` |
|
||||
| Generate sound effect | `POST /api/external/v1/editor/audios/sound-effects/generations` | `prompt`, `duration` | `model`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
|
||||
| Generate background music | `POST /api/external/v1/editor/audios/background-music/generations` | `gptDescriptionPrompt`, `makeInstrumental` | `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` |
|
||||
|
||||
## Image Post-processing Style
|
||||
|
||||
The request-body top-level `style` field controls deterministic image post-processing. It is separate from `generationInputs.artSpec.style`, which only describes the requested visual language for prompting.
|
||||
|
||||
- Omitted, `null`, an empty string, and `"none"` all disable post-processing without a warning.
|
||||
- `"pixelArt"` enables deterministic pixel-art snapping for ordinary image generation (omit `kind`), `kind: "character"`, and icon spritesheet generation.
|
||||
- Unknown strings, or `"pixelArt"` on unsupported image kinds such as `spec`, `quick-edit`, `ui-design`, or `publication-material`, continue without style processing and return `warning.code: "unsupported-image-style"`.
|
||||
- A non-string JSON value is malformed and returns HTTP `400`. Keep the field extensible; do not treat the current examples as a closed client-side enum.
|
||||
|
||||
Image or character generation with pixel-art snapping:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "生成一个正面站立的像素风冒险者角色",
|
||||
"kind": "character",
|
||||
"style": "pixelArt"
|
||||
}
|
||||
```
|
||||
|
||||
Icon spritesheet generation with pixel-art snapping:
|
||||
|
||||
```json
|
||||
{
|
||||
"referenceImageSrc": "generated-character-drafts/editor/external-editor-references/icon-spec.png",
|
||||
"iconDescriptions": ["木剑", "圆盾", "红色药水"],
|
||||
"style": "pixelArt"
|
||||
}
|
||||
```
|
||||
|
||||
All generation requests should be placed into both the current canvas and its same-name asset-library folder. For endpoints that support `assetLabel`, pass it. For UI extraction, use `spritesheetLabel`. For icon spritesheet, the folder is enough. For character animation, the endpoint does not return `asset`; after success call `POST /api/external/v1/editor/assets` using the first returned frame as `imageSrc`, the session `assetFolderId`, and `assetKind: "character-animation"`.
|
||||
|
||||
## HTTP 2xx Warning Handling
|
||||
@@ -92,7 +121,7 @@ Character image generation (including character redraw through `kind: "character
|
||||
|
||||
- Consume the returned `project` and media snapshots as authoritative: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. `warning.code: "postprocess-failed-source-preserved"` means the saved provider source is the main result. Character output has no transparent derivative, while icon spritesheet and UI extraction have no transparent spritesheet and no slices. Display `warning.reason` directly; do not construct missing assets or retry the provider generation from scratch.
|
||||
- `sliceWarning` is only for a transparent spritesheet that was created successfully but could not be split automatically. Use the complete transparent spritesheet and preserve `sliceWarning.reason` as the original diagnostic; it is not a post-processing/source-preserved warning.
|
||||
- The service contract keeps `warning` and `sliceWarning` mutually exclusive. If a malformed response contains both, prioritize the general `warning` over `sliceWarning` defensively.
|
||||
- `warning` and `sliceWarning` are mutually exclusive only for `postprocess-failed-source-preserved`, because that failure never reaches slicing. A general `warning` produced by image-style normalization (`unsupported-image-style`) or pixel-art snapping can coexist with `sliceWarning`; render both reasons instead of picking one.
|
||||
|
||||
## Reference Image Upload
|
||||
|
||||
|
||||
@@ -270,11 +270,21 @@ class GenarrativeExternalClient:
|
||||
fields[asset_label_field] = normalize_optional_text(asset_label) or "生成素材"
|
||||
return fields
|
||||
|
||||
def save_canvas(self, project_id: str, viewport: dict[str, Any], layers: dict[str, Any]) -> Any:
|
||||
def save_canvas(
|
||||
self,
|
||||
project_id: str,
|
||||
viewport: dict[str, Any],
|
||||
layers: dict[str, Any],
|
||||
expected_revision: int,
|
||||
) -> Any:
|
||||
return self.request_json(
|
||||
"PATCH",
|
||||
f"/api/external/v1/editor/projects/{urllib.parse.quote(project_id, safe='')}/canvas",
|
||||
{"viewport": viewport, "layers": layers},
|
||||
{
|
||||
"viewport": viewport,
|
||||
"layers": layers,
|
||||
"expectedRevision": expected_revision,
|
||||
},
|
||||
)
|
||||
|
||||
def _apply_art_spec(self, fields: dict[str, Any], prompt: str) -> str:
|
||||
|
||||
@@ -6,17 +6,19 @@ import {
|
||||
getAdminFeatureGateConfig,
|
||||
getAdminUserDetail,
|
||||
listAdminRechargeOrders,
|
||||
reconcileAdminUserConsumption,
|
||||
resolveAdminRechargeRefundManualReview,
|
||||
updateAdminAccount,
|
||||
uploadAdminEditorShowcaseCampaignImage,
|
||||
upsertAdminFeatureGateConfig,
|
||||
upsertProfileWalletConfig,
|
||||
} from './adminApiClient';
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () => {
|
||||
test('后台账号创建和更新同时携带 Tab 与独立操作权限', async () => {
|
||||
const fetchMock = vi.fn().mockImplementation(() =>
|
||||
Promise.resolve(
|
||||
new Response(JSON.stringify({ account: { accountId: 'member-1' } }), {
|
||||
@@ -31,11 +33,13 @@ test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () =>
|
||||
displayName: '运营',
|
||||
password: 'secret123',
|
||||
tabPermissions: ['dashboard', 'tracking'],
|
||||
actionPermissions: ['profile-wallet-consumption-reconcile'],
|
||||
enabled: true,
|
||||
});
|
||||
await updateAdminAccount('owner-token', 'member/1', {
|
||||
displayName: '运营二组',
|
||||
tabPermissions: ['tracking'],
|
||||
actionPermissions: [],
|
||||
enabled: false,
|
||||
});
|
||||
|
||||
@@ -44,6 +48,14 @@ test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () =>
|
||||
expect.objectContaining({
|
||||
method: 'POST',
|
||||
headers: expect.objectContaining({ Authorization: 'Bearer owner-token' }),
|
||||
body: JSON.stringify({
|
||||
username: 'operator',
|
||||
displayName: '运营',
|
||||
password: 'secret123',
|
||||
tabPermissions: ['dashboard', 'tracking'],
|
||||
actionPermissions: ['profile-wallet-consumption-reconcile'],
|
||||
enabled: true,
|
||||
}),
|
||||
}),
|
||||
);
|
||||
expect(fetchMock.mock.calls[1]?.[0]).toBe('/admin/api/accounts/member%2F1');
|
||||
@@ -53,12 +65,40 @@ test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () =>
|
||||
body: JSON.stringify({
|
||||
displayName: '运营二组',
|
||||
tabPermissions: ['tracking'],
|
||||
actionPermissions: [],
|
||||
enabled: false,
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('账号配置一次提交初始和每日免费泥点', async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(
|
||||
new Response(JSON.stringify({configId: 'profile_wallet'}), {
|
||||
status: 200,
|
||||
headers: {'content-type': 'application/json'},
|
||||
}),
|
||||
);
|
||||
vi.stubGlobal('fetch', fetchMock);
|
||||
|
||||
await upsertProfileWalletConfig('owner-token', {
|
||||
initialMudPoints: 100,
|
||||
dailyFreePointsPerDay: 35,
|
||||
});
|
||||
|
||||
expect(fetchMock).toHaveBeenCalledWith(
|
||||
'/admin/api/profile/wallet-config',
|
||||
expect.objectContaining({
|
||||
method: 'POST',
|
||||
headers: expect.objectContaining({Authorization: 'Bearer owner-token'}),
|
||||
body: JSON.stringify({
|
||||
initialMudPoints: 100,
|
||||
dailyFreePointsPerDay: 35,
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('灰度配置读写只使用通用 feature-gates 管理接口', async () => {
|
||||
const fetchMock = vi.fn().mockImplementation(() =>
|
||||
Promise.resolve(
|
||||
@@ -238,6 +278,33 @@ test('用户详情只发送实际提供的用户定位字段', async () => {
|
||||
});
|
||||
});
|
||||
|
||||
test('历史花费手动对账使用独立管理员写接口', async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(
|
||||
new Response(
|
||||
JSON.stringify({
|
||||
userId: 'user-1',
|
||||
historicalConsumedPoints: 1300,
|
||||
changed: true,
|
||||
}),
|
||||
{ status: 200 },
|
||||
),
|
||||
);
|
||||
vi.stubGlobal('fetch', fetchMock);
|
||||
|
||||
await reconcileAdminUserConsumption('token-1', { userId: 'user-1' });
|
||||
|
||||
expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
|
||||
'/admin/api/profile/users/reconcile-consumption',
|
||||
);
|
||||
expect(fetchMock.mock.calls[0]?.[1]).toEqual(
|
||||
expect.objectContaining({
|
||||
method: 'POST',
|
||||
headers: expect.objectContaining({ Authorization: 'Bearer token-1' }),
|
||||
body: JSON.stringify({ userId: 'user-1' }),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('退款执行使用独立 execute 管理员路由', async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(
|
||||
new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
|
||||
|
||||
@@ -48,6 +48,8 @@ import type {
|
||||
AdminUpsertProfileRedeemCodeRequest,
|
||||
AdminUpsertProfileTaskConfigRequest,
|
||||
AdminUpsertProfileWalletConfigRequest,
|
||||
AdminUserConsumptionReconcileRequest,
|
||||
AdminUserConsumptionReconcileResponse,
|
||||
AdminUserDetailQuery,
|
||||
AdminUserDetailResponse,
|
||||
AdminWalletRestrictionRequest,
|
||||
@@ -577,6 +579,16 @@ export function getAdminUserDetail(token: string, query: AdminUserDetailQuery) {
|
||||
);
|
||||
}
|
||||
|
||||
export function reconcileAdminUserConsumption(
|
||||
token: string,
|
||||
payload: AdminUserConsumptionReconcileRequest,
|
||||
) {
|
||||
return request<AdminUserConsumptionReconcileResponse>(
|
||||
'/admin/api/profile/users/reconcile-consumption',
|
||||
{ method: 'POST', token, body: payload },
|
||||
);
|
||||
}
|
||||
|
||||
export function previewAdminRechargeRefund(
|
||||
token: string,
|
||||
payload: AdminRechargeRefundPreviewRequest,
|
||||
|
||||
@@ -38,6 +38,7 @@ export interface AdminSessionPayload {
|
||||
roles: string[];
|
||||
accountRole: 'owner' | 'member';
|
||||
tabPermissions: string[];
|
||||
actionPermissions: string[];
|
||||
issuedAt: string;
|
||||
expiresAt: string;
|
||||
}
|
||||
@@ -48,6 +49,7 @@ export interface AdminAccountPayload {
|
||||
displayName: string;
|
||||
accountRole: 'owner' | 'member';
|
||||
tabPermissions: string[];
|
||||
actionPermissions: string[];
|
||||
enabled: boolean;
|
||||
tokenVersion: number;
|
||||
createdBy: string;
|
||||
@@ -65,6 +67,7 @@ export interface AdminCreateAccountRequest {
|
||||
displayName: string;
|
||||
password: string;
|
||||
tabPermissions: string[];
|
||||
actionPermissions: string[];
|
||||
enabled: boolean;
|
||||
}
|
||||
|
||||
@@ -76,6 +79,7 @@ export interface AdminUpdateAccountRequest {
|
||||
displayName: string;
|
||||
password?: string;
|
||||
tabPermissions: string[];
|
||||
actionPermissions: string[];
|
||||
enabled: boolean;
|
||||
}
|
||||
|
||||
@@ -556,6 +560,7 @@ export interface AdminUpsertProfileRechargeProductRequest {
|
||||
|
||||
export interface AdminUpsertProfileWalletConfigRequest {
|
||||
initialMudPoints: number;
|
||||
dailyFreePointsPerDay: number;
|
||||
}
|
||||
|
||||
export interface ProfileRedeemCodeAdminResponse {
|
||||
@@ -657,6 +662,7 @@ export interface ProfileRechargeProductConfigAdminListResponse {
|
||||
export interface ProfileWalletConfigAdminResponse {
|
||||
configId: string;
|
||||
initialMudPoints: number;
|
||||
dailyFreePointsPerDay: number;
|
||||
createdBy: string;
|
||||
createdByDisplayName: string;
|
||||
createdAt: string;
|
||||
@@ -819,10 +825,24 @@ export interface AdminUserDetailResponse {
|
||||
bindingStatus: string;
|
||||
phoneBound: boolean;
|
||||
wechatBound: boolean;
|
||||
historicalConsumedPoints: number;
|
||||
canReconcileConsumption: boolean;
|
||||
wallet: AdminProfileWalletPayload;
|
||||
rechargeOrders: AdminRechargeOrderEntryPayload[];
|
||||
}
|
||||
|
||||
export interface AdminUserConsumptionReconcileRequest {
|
||||
userId: string;
|
||||
}
|
||||
|
||||
export interface AdminUserConsumptionReconcileResponse {
|
||||
userId: string;
|
||||
previousHistoricalConsumedPoints?: number | null;
|
||||
historicalConsumedPoints: number;
|
||||
changed: boolean;
|
||||
reconciledAtMicros: number;
|
||||
}
|
||||
|
||||
export interface AdminRechargeRefundPreviewRequest {
|
||||
orderId: string;
|
||||
refundAmountCents: number;
|
||||
|
||||
@@ -6,6 +6,7 @@ import {beforeEach, expect, test, vi} from 'vitest';
|
||||
|
||||
import {
|
||||
getAdminUserDetail,
|
||||
reconcileAdminUserConsumption,
|
||||
updateAdminWalletRestriction,
|
||||
} from '../api/adminApiClient';
|
||||
import type {
|
||||
@@ -20,6 +21,7 @@ vi.mock('../api/adminApiClient', () => ({
|
||||
),
|
||||
getAdminUserDetail: vi.fn(),
|
||||
isAdminApiError: vi.fn(() => false),
|
||||
reconcileAdminUserConsumption: vi.fn(),
|
||||
updateAdminWalletRestriction: vi.fn(),
|
||||
}));
|
||||
|
||||
@@ -48,6 +50,8 @@ const detail: AdminUserDetailResponse = {
|
||||
bindingStatus: 'bound',
|
||||
phoneBound: true,
|
||||
wechatBound: true,
|
||||
historicalConsumedPoints: 1234,
|
||||
canReconcileConsumption: true,
|
||||
wallet,
|
||||
rechargeOrders: [
|
||||
{
|
||||
@@ -82,6 +86,13 @@ const detail: AdminUserDetailResponse = {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
vi.mocked(getAdminUserDetail).mockResolvedValue(detail);
|
||||
vi.mocked(reconcileAdminUserConsumption).mockResolvedValue({
|
||||
userId: 'user-1',
|
||||
previousHistoricalConsumedPoints: 1234,
|
||||
historicalConsumedPoints: 1300,
|
||||
changed: true,
|
||||
reconciledAtMicros: 1_720_000_000_000_000,
|
||||
});
|
||||
vi.mocked(updateAdminWalletRestriction).mockResolvedValue({wallet});
|
||||
});
|
||||
|
||||
@@ -111,6 +122,8 @@ test('用户查看按钮按内部 ID 查询并展示脱敏资料、余额与退
|
||||
expect(screen.getByText('138****5678')).toBeTruthy();
|
||||
expect(screen.getByText('退款欠账限制')).toBeTruthy();
|
||||
expect(screen.getByText('25', {selector: 'strong'})).toBeTruthy();
|
||||
expect(screen.getByText('历史花费')).toBeTruthy();
|
||||
expect(screen.getByText('1234', {selector: 'strong'})).toBeTruthy();
|
||||
expect(screen.getByText('order-1')).toBeTruthy();
|
||||
|
||||
await user.keyboard('{Escape}');
|
||||
@@ -136,6 +149,50 @@ test('只有陶泥号时按 publicUserCode 查询用户', async () => {
|
||||
});
|
||||
});
|
||||
|
||||
test('历史花费支持手动对账并用权威结果校准展示', async () => {
|
||||
const user = userEvent.setup();
|
||||
render(
|
||||
<AdminUserReferenceButton
|
||||
token="admin-token"
|
||||
userId="user-1"
|
||||
onUnauthorized={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
|
||||
await user.click(screen.getByRole('button', {name: '查看用户信息'}));
|
||||
await screen.findByText('陶泥用户');
|
||||
await user.click(screen.getByRole('button', {name: '手动对账历史花费'}));
|
||||
await user.click(screen.getByRole('button', {name: '确认'}));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(reconcileAdminUserConsumption).toHaveBeenCalledWith('admin-token', {
|
||||
userId: 'user-1',
|
||||
});
|
||||
});
|
||||
expect(await screen.findByText('对账完成，历史花费已校准')).toBeTruthy();
|
||||
expect(screen.getByText('1300', {selector: 'strong'})).toBeTruthy();
|
||||
});
|
||||
|
||||
test('没有独立操作权限时不显示历史花费对账按钮', async () => {
|
||||
vi.mocked(getAdminUserDetail).mockResolvedValue({
|
||||
...detail,
|
||||
canReconcileConsumption: false,
|
||||
});
|
||||
const user = userEvent.setup();
|
||||
render(
|
||||
<AdminUserReferenceButton
|
||||
token="admin-token"
|
||||
userId="user-1"
|
||||
onUnauthorized={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
|
||||
await user.click(screen.getByRole('button', {name: '查看用户信息'}));
|
||||
await screen.findByText('陶泥用户');
|
||||
|
||||
expect(screen.queryByRole('button', {name: '手动对账历史花费'})).toBeNull();
|
||||
});
|
||||
|
||||
test('人工冻结和解除人工冻结分别提交原因且不解除退款欠账限制', async () => {
|
||||
const user = userEvent.setup();
|
||||
const manuallyFrozenWallet: AdminProfileWalletPayload = {
|
||||
|
||||
@@ -6,6 +6,7 @@ import {
|
||||
formatAdminApiError,
|
||||
getAdminUserDetail,
|
||||
isAdminApiError,
|
||||
reconcileAdminUserConsumption,
|
||||
updateAdminWalletRestriction,
|
||||
} from '../api/adminApiClient';
|
||||
import type {
|
||||
@@ -34,6 +35,8 @@ export function AdminUserDetailDialog({
|
||||
const [errorMessage, setErrorMessage] = useState('');
|
||||
const [restrictionReason, setRestrictionReason] = useState('');
|
||||
const [isSavingRestriction, setIsSavingRestriction] = useState(false);
|
||||
const [isReconcilingConsumption, setIsReconcilingConsumption] = useState(false);
|
||||
const [reconcileMessage, setReconcileMessage] = useState('');
|
||||
const closeButtonRef = useRef<HTMLButtonElement | null>(null);
|
||||
const requestVersionRef = useRef(0);
|
||||
const {confirmWrite, confirmDialog, isConfirming} = useAdminWriteConfirm();
|
||||
@@ -60,7 +63,12 @@ export function AdminUserDetailDialog({
|
||||
|
||||
useEffect(() => {
|
||||
const handleKeyDown = (event: KeyboardEvent) => {
|
||||
if (event.key === 'Escape' && !isSavingRestriction && !isConfirming) {
|
||||
if (
|
||||
event.key === 'Escape' &&
|
||||
!isSavingRestriction &&
|
||||
!isReconcilingConsumption &&
|
||||
!isConfirming
|
||||
) {
|
||||
event.preventDefault();
|
||||
onClose();
|
||||
}
|
||||
@@ -69,13 +77,14 @@ export function AdminUserDetailDialog({
|
||||
return () => {
|
||||
window.removeEventListener('keydown', handleKeyDown);
|
||||
};
|
||||
}, [isConfirming, isSavingRestriction, onClose]);
|
||||
}, [isConfirming, isReconcilingConsumption, isSavingRestriction, onClose]);
|
||||
|
||||
async function loadDetail() {
|
||||
const requestVersion = requestVersionRef.current + 1;
|
||||
requestVersionRef.current = requestVersion;
|
||||
setIsLoading(true);
|
||||
setErrorMessage('');
|
||||
setReconcileMessage('');
|
||||
try {
|
||||
const response = await getAdminUserDetail(token, {
|
||||
userId: userId?.trim() || undefined,
|
||||
@@ -144,6 +153,47 @@ export function AdminUserDetailDialog({
|
||||
}
|
||||
}
|
||||
|
||||
async function handleConsumptionReconcile() {
|
||||
if (!detail || isReconcilingConsumption) {
|
||||
return;
|
||||
}
|
||||
const confirmed = await confirmWrite({
|
||||
action: '手动对账历史花费',
|
||||
target: `${detail.displayName || detail.publicUserCode} / ${detail.userId}`,
|
||||
});
|
||||
if (!confirmed) {
|
||||
return;
|
||||
}
|
||||
|
||||
setIsReconcilingConsumption(true);
|
||||
setErrorMessage('');
|
||||
setReconcileMessage('');
|
||||
try {
|
||||
const response = await reconcileAdminUserConsumption(token, {
|
||||
userId: detail.userId,
|
||||
});
|
||||
setDetail((current) =>
|
||||
current
|
||||
? {
|
||||
...current,
|
||||
historicalConsumedPoints: response.historicalConsumedPoints,
|
||||
}
|
||||
: current,
|
||||
);
|
||||
setReconcileMessage(
|
||||
response.changed ? '对账完成，历史花费已校准' : '对账完成，数据一致',
|
||||
);
|
||||
} catch (error: unknown) {
|
||||
if (isAdminApiError(error) && error.status === 401) {
|
||||
onUnauthorized('登录状态已失效');
|
||||
} else {
|
||||
setErrorMessage(formatAdminApiError(error));
|
||||
}
|
||||
} finally {
|
||||
setIsReconcilingConsumption(false);
|
||||
}
|
||||
}
|
||||
|
||||
if (typeof document === 'undefined') {
|
||||
return null;
|
||||
}
|
||||
@@ -158,6 +208,7 @@ export function AdminUserDetailDialog({
|
||||
if (
|
||||
event.target === event.currentTarget &&
|
||||
!isSavingRestriction &&
|
||||
!isReconcilingConsumption &&
|
||||
!isConfirming
|
||||
) {
|
||||
onClose();
|
||||
@@ -174,7 +225,7 @@ export function AdminUserDetailDialog({
|
||||
<button
|
||||
aria-label="刷新用户信息"
|
||||
className="admin-ghost-button"
|
||||
disabled={isLoading}
|
||||
disabled={isLoading || isReconcilingConsumption}
|
||||
title="刷新"
|
||||
type="button"
|
||||
onClick={() => void loadDetail()}
|
||||
@@ -185,7 +236,7 @@ export function AdminUserDetailDialog({
|
||||
ref={closeButtonRef}
|
||||
aria-label="关闭用户详情"
|
||||
className="admin-ghost-button"
|
||||
disabled={isSavingRestriction}
|
||||
disabled={isSavingRestriction || isReconcilingConsumption}
|
||||
title="关闭"
|
||||
type="button"
|
||||
onClick={onClose}
|
||||
@@ -222,7 +273,15 @@ export function AdminUserDetailDialog({
|
||||
{errorMessage}
|
||||
</div>
|
||||
) : null}
|
||||
<WalletSection wallet={detail.wallet} />
|
||||
<WalletSection
|
||||
wallet={detail.wallet}
|
||||
historicalConsumedPoints={detail.historicalConsumedPoints}
|
||||
canReconcileConsumption={detail.canReconcileConsumption}
|
||||
isBusy={isReconcilingConsumption || isSavingRestriction}
|
||||
isReconciling={isReconcilingConsumption}
|
||||
reconcileMessage={reconcileMessage}
|
||||
onReconcile={() => void handleConsumptionReconcile()}
|
||||
/>
|
||||
|
||||
<section className="admin-user-restriction-section">
|
||||
<div className="admin-panel-heading">
|
||||
@@ -251,7 +310,7 @@ export function AdminUserDetailDialog({
|
||||
<span>操作原因</span>
|
||||
<input
|
||||
aria-label="人工冻结操作原因"
|
||||
disabled={isSavingRestriction}
|
||||
disabled={isSavingRestriction || isReconcilingConsumption}
|
||||
value={restrictionReason}
|
||||
onChange={(event) => setRestrictionReason(event.target.value)}
|
||||
/>
|
||||
@@ -262,7 +321,11 @@ export function AdminUserDetailDialog({
|
||||
? 'admin-secondary-button'
|
||||
: 'admin-danger-button'
|
||||
}
|
||||
disabled={isSavingRestriction || !restrictionReason.trim()}
|
||||
disabled={
|
||||
isSavingRestriction ||
|
||||
isReconcilingConsumption ||
|
||||
!restrictionReason.trim()
|
||||
}
|
||||
type="button"
|
||||
onClick={() => void handleRestrictionChange()}
|
||||
>
|
||||
@@ -369,7 +432,23 @@ function UserIdentityHeader({detail}: {detail: AdminUserDetailResponse}) {
|
||||
);
|
||||
}
|
||||
|
||||
function WalletSection({wallet}: {wallet: AdminProfileWalletPayload}) {
|
||||
function WalletSection({
|
||||
wallet,
|
||||
historicalConsumedPoints,
|
||||
canReconcileConsumption,
|
||||
isBusy,
|
||||
isReconciling,
|
||||
reconcileMessage,
|
||||
onReconcile,
|
||||
}: {
|
||||
wallet: AdminProfileWalletPayload;
|
||||
historicalConsumedPoints: number;
|
||||
canReconcileConsumption: boolean;
|
||||
isBusy: boolean;
|
||||
isReconciling: boolean;
|
||||
reconcileMessage: string;
|
||||
onReconcile: () => void;
|
||||
}) {
|
||||
const metrics = [
|
||||
['总余额', wallet.totalBalance],
|
||||
['可消费', wallet.spendableBalance],
|
||||
@@ -378,19 +457,41 @@ function WalletSection({wallet}: {wallet: AdminProfileWalletPayload}) {
|
||||
['会员限时', wallet.membershipLimitedPoints],
|
||||
['退款占用', wallet.heldPoints],
|
||||
['退款欠账', wallet.refundDebtPoints],
|
||||
['历史花费', historicalConsumedPoints],
|
||||
] as const;
|
||||
return (
|
||||
<section className="admin-user-wallet-section">
|
||||
<div className="admin-panel-heading">
|
||||
<h3>钱包</h3>
|
||||
<div className="admin-tag-list">
|
||||
{wallet.manualFrozen ? <span className="admin-tag">人工冻结</span> : null}
|
||||
{wallet.refundDebtFrozen ? (
|
||||
<span className="admin-tag">退款欠账限制</span>
|
||||
<div className="admin-detail-actions">
|
||||
{canReconcileConsumption ? (
|
||||
<button
|
||||
aria-label="手动对账历史花费"
|
||||
className="admin-ghost-button admin-user-wallet-reconcile-button"
|
||||
disabled={isBusy}
|
||||
type="button"
|
||||
onClick={onReconcile}
|
||||
>
|
||||
<RefreshCcw size={15} aria-hidden="true" />
|
||||
<span>{isReconciling ? '对账中' : '手动对账'}</span>
|
||||
</button>
|
||||
) : null}
|
||||
{!wallet.walletFrozen ? <span className="admin-status admin-status-ok">正常</span> : null}
|
||||
<div className="admin-tag-list">
|
||||
{wallet.manualFrozen ? <span className="admin-tag">人工冻结</span> : null}
|
||||
{wallet.refundDebtFrozen ? (
|
||||
<span className="admin-tag">退款欠账限制</span>
|
||||
) : null}
|
||||
{!wallet.walletFrozen ? (
|
||||
<span className="admin-status admin-status-ok">正常</span>
|
||||
) : null}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{reconcileMessage ? (
|
||||
<div className="admin-alert" role="status">
|
||||
{reconcileMessage}
|
||||
</div>
|
||||
) : null}
|
||||
<div className="admin-user-wallet-grid">
|
||||
{metrics.map(([label, value]) => (
|
||||
<div className="admin-recharge-metric" key={label}>
|
||||
|
||||
@@ -17,6 +17,7 @@ interface AdminAccountsPageProps {
|
||||
}
|
||||
|
||||
const assignableRoutes = adminRoutes.filter((route) => !route.ownerOnly);
|
||||
const consumptionReconcilePermission = 'profile-wallet-consumption-reconcile';
|
||||
|
||||
export function AdminAccountsPage({
|
||||
token,
|
||||
@@ -29,6 +30,7 @@ export function AdminAccountsPage({
|
||||
const [password, setPassword] = useState('');
|
||||
const [enabled, setEnabled] = useState(true);
|
||||
const [tabPermissions, setTabPermissions] = useState<string[]>([]);
|
||||
const [actionPermissions, setActionPermissions] = useState<string[]>([]);
|
||||
const [isLoading, setIsLoading] = useState(false);
|
||||
const [isSaving, setIsSaving] = useState(false);
|
||||
const [errorMessage, setErrorMessage] = useState('');
|
||||
@@ -65,6 +67,7 @@ export function AdminAccountsPage({
|
||||
setPassword('');
|
||||
setEnabled(true);
|
||||
setTabPermissions([]);
|
||||
setActionPermissions([]);
|
||||
setErrorMessage('');
|
||||
}
|
||||
|
||||
@@ -75,6 +78,7 @@ export function AdminAccountsPage({
|
||||
setPassword('');
|
||||
setEnabled(account.enabled);
|
||||
setTabPermissions(account.tabPermissions);
|
||||
setActionPermissions(account.actionPermissions ?? []);
|
||||
setErrorMessage('');
|
||||
}
|
||||
|
||||
@@ -127,6 +131,7 @@ export function AdminAccountsPage({
|
||||
displayName: normalizedDisplayName,
|
||||
...(password ? {password} : {}),
|
||||
tabPermissions,
|
||||
actionPermissions,
|
||||
enabled,
|
||||
})
|
||||
: await createAdminAccount(token, {
|
||||
@@ -134,6 +139,7 @@ export function AdminAccountsPage({
|
||||
displayName: normalizedDisplayName,
|
||||
password,
|
||||
tabPermissions,
|
||||
actionPermissions,
|
||||
enabled,
|
||||
});
|
||||
setAccounts((current) => {
|
||||
@@ -289,6 +295,28 @@ export function AdminAccountsPage({
|
||||
</div>
|
||||
</fieldset>
|
||||
|
||||
<fieldset className="admin-permission-fieldset">
|
||||
<legend>独立操作权限</legend>
|
||||
<div className="admin-permission-grid">
|
||||
<label>
|
||||
<input
|
||||
checked={actionPermissions.includes(
|
||||
consumptionReconcilePermission,
|
||||
)}
|
||||
type="checkbox"
|
||||
onChange={(event) =>
|
||||
setActionPermissions(
|
||||
event.target.checked
|
||||
? [consumptionReconcilePermission]
|
||||
: [],
|
||||
)
|
||||
}
|
||||
/>
|
||||
<span>手动对账用户历史花费</span>
|
||||
</label>
|
||||
</div>
|
||||
</fieldset>
|
||||
|
||||
<button
|
||||
className="admin-primary-button"
|
||||
disabled={isSaving}
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
/* @vitest-environment jsdom */
|
||||
|
||||
import {fireEvent, render, screen, waitFor} from '@testing-library/react';
|
||||
import userEvent from '@testing-library/user-event';
|
||||
import {beforeEach, expect, test, vi} from 'vitest';
|
||||
|
||||
import {getProfileWalletConfig, upsertProfileWalletConfig} from '../api/adminApiClient';
|
||||
import type {ProfileWalletConfigAdminResponse} from '../api/adminApiTypes';
|
||||
import {AdminProfileWalletConfigPage} from './AdminProfileWalletConfigPage';
|
||||
|
||||
vi.mock('../api/adminApiClient', () => ({
|
||||
formatAdminApiError: vi.fn((error: unknown) => error instanceof Error ? error.message : '请求失败'),
|
||||
getProfileWalletConfig: vi.fn(),
|
||||
isAdminApiError: vi.fn(() => false),
|
||||
upsertProfileWalletConfig: vi.fn(),
|
||||
}));
|
||||
|
||||
const configResponse: ProfileWalletConfigAdminResponse = {
|
||||
configId: 'profile_wallet', initialMudPoints: 100, dailyFreePointsPerDay: 20,
|
||||
createdBy: 'owner-1', createdByDisplayName: '管理员',
|
||||
createdAt: '2026-07-31T01:00:00Z', updatedBy: 'owner-1',
|
||||
updatedByDisplayName: '管理员', updatedAt: '2026-07-31T01:00:00Z',
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
vi.mocked(getProfileWalletConfig).mockResolvedValue(configResponse);
|
||||
vi.mocked(upsertProfileWalletConfig).mockResolvedValue({...configResponse, initialMudPoints: 120, dailyFreePointsPerDay: 35});
|
||||
});
|
||||
|
||||
test('账号配置页加载并展示每日免费泥点', async () => {
|
||||
render(<AdminProfileWalletConfigPage token="admin-token" result={configResponse} onUnauthorized={vi.fn()} onResultChange={vi.fn()} />);
|
||||
expect((await screen.findByLabelText('每日免费泥点数') as HTMLInputElement).value).toBe('20');
|
||||
expect(getProfileWalletConfig).toHaveBeenCalledWith('admin-token');
|
||||
expect(screen.getByText('每日免费泥点')).toBeTruthy();
|
||||
});
|
||||
|
||||
test('账号配置页一次保存初始和每日免费泥点', async () => {
|
||||
const user = userEvent.setup();
|
||||
const onResultChange = vi.fn();
|
||||
render(<AdminProfileWalletConfigPage token="admin-token" result={configResponse} onUnauthorized={vi.fn()} onResultChange={onResultChange} />);
|
||||
await screen.findByLabelText('每日免费泥点数');
|
||||
fireEvent.change(screen.getByLabelText('账号初始泥点数'), {target: {value: '120'}});
|
||||
fireEvent.change(screen.getByLabelText('每日免费泥点数'), {target: {value: '35'}});
|
||||
await user.click(screen.getByRole('button', {name: '保存'}));
|
||||
expect(screen.getByText('初始 120 泥点，每日免费 35 泥点')).toBeTruthy();
|
||||
await user.click(screen.getByRole('button', {name: '确认'}));
|
||||
await waitFor(() => expect(upsertProfileWalletConfig).toHaveBeenCalledWith('admin-token', {initialMudPoints: 120, dailyFreePointsPerDay: 35}));
|
||||
expect(onResultChange).toHaveBeenLastCalledWith(expect.objectContaining({initialMudPoints: 120, dailyFreePointsPerDay: 35}));
|
||||
});
|
||||
|
||||
test('账号配置页拒绝非正整数每日免费额度', async () => {
|
||||
render(<AdminProfileWalletConfigPage token="admin-token" result={configResponse} onUnauthorized={vi.fn()} onResultChange={vi.fn()} />);
|
||||
const input = await screen.findByLabelText('每日免费泥点数');
|
||||
fireEvent.change(input, {target: {value: '1.5'}});
|
||||
expect((screen.getByRole('button', {name: '保存'}) as HTMLButtonElement).disabled).toBe(true);
|
||||
expect(upsertProfileWalletConfig).not.toHaveBeenCalled();
|
||||
});
|
||||
@@ -23,6 +23,7 @@ export function AdminProfileWalletConfigPage({
|
||||
onResultChange,
|
||||
}: AdminProfileWalletConfigPageProps) {
|
||||
const [initialMudPoints, setInitialMudPoints] = useState('100');
|
||||
const [dailyFreePointsPerDay, setDailyFreePointsPerDay] = useState('20');
|
||||
const [isLoading, setIsLoading] = useState(false);
|
||||
const [isSaving, setIsSaving] = useState(false);
|
||||
const [loadErrorMessage, setLoadErrorMessage] = useState('');
|
||||
@@ -41,6 +42,7 @@ export function AdminProfileWalletConfigPage({
|
||||
const response = await getProfileWalletConfig(token);
|
||||
onResultChange(response);
|
||||
setInitialMudPoints(String(response.initialMudPoints));
|
||||
setDailyFreePointsPerDay(String(response.dailyFreePointsPerDay));
|
||||
} catch (error: unknown) {
|
||||
handlePageError(error, onUnauthorized, setLoadErrorMessage);
|
||||
} finally {
|
||||
@@ -53,6 +55,13 @@ export function AdminProfileWalletConfigPage({
|
||||
if (isSaving) {
|
||||
return;
|
||||
}
|
||||
const normalizedDailyFreePointsPerDay = parsePositiveInteger(
|
||||
dailyFreePointsPerDay,
|
||||
);
|
||||
if (!normalizedDailyFreePointsPerDay) {
|
||||
setErrorMessage('每日免费泥点数必须是大于 0 的整数');
|
||||
return;
|
||||
}
|
||||
|
||||
const normalizedInitialMudPoints = parsePositiveInteger(initialMudPoints);
|
||||
if (!normalizedInitialMudPoints) {
|
||||
@@ -63,7 +72,7 @@ export function AdminProfileWalletConfigPage({
|
||||
setErrorMessage('');
|
||||
const confirmed = await confirmWrite({
|
||||
action: '保存账号配置',
|
||||
target: `${normalizedInitialMudPoints}泥点`,
|
||||
target: `初始 ${normalizedInitialMudPoints} 泥点，每日免费 ${normalizedDailyFreePointsPerDay} 泥点`,
|
||||
});
|
||||
if (!confirmed) {
|
||||
return;
|
||||
@@ -73,9 +82,11 @@ export function AdminProfileWalletConfigPage({
|
||||
try {
|
||||
const response = await upsertProfileWalletConfig(token, {
|
||||
initialMudPoints: normalizedInitialMudPoints,
|
||||
dailyFreePointsPerDay: normalizedDailyFreePointsPerDay,
|
||||
});
|
||||
onResultChange(response);
|
||||
setInitialMudPoints(String(response.initialMudPoints));
|
||||
setDailyFreePointsPerDay(String(response.dailyFreePointsPerDay));
|
||||
} catch (error: unknown) {
|
||||
handlePageError(error, onUnauthorized, setErrorMessage);
|
||||
} finally {
|
||||
@@ -120,6 +131,17 @@ export function AdminProfileWalletConfigPage({
|
||||
/>
|
||||
</label>
|
||||
|
||||
<label className="admin-field">
|
||||
<span>每日免费泥点数</span>
|
||||
<input
|
||||
min={1}
|
||||
step={1}
|
||||
type="number"
|
||||
value={dailyFreePointsPerDay}
|
||||
onChange={(event) => setDailyFreePointsPerDay(event.target.value)}
|
||||
/>
|
||||
</label>
|
||||
|
||||
{errorMessage ? (
|
||||
<div className="admin-alert" role="status">
|
||||
{errorMessage}
|
||||
@@ -128,7 +150,11 @@ export function AdminProfileWalletConfigPage({
|
||||
|
||||
<button
|
||||
className="admin-primary-button"
|
||||
disabled={isSaving || !parsePositiveInteger(initialMudPoints)}
|
||||
disabled={
|
||||
isSaving ||
|
||||
!parsePositiveInteger(initialMudPoints) ||
|
||||
!parsePositiveInteger(dailyFreePointsPerDay)
|
||||
}
|
||||
type="submit"
|
||||
>
|
||||
<Save size={17} aria-hidden="true" />
|
||||
@@ -147,6 +173,10 @@ export function AdminProfileWalletConfigPage({
|
||||
<dt>初始泥点</dt>
|
||||
<dd>{result.initialMudPoints}</dd>
|
||||
</div>
|
||||
<div>
|
||||
<dt>每日免费泥点</dt>
|
||||
<dd>{result.dailyFreePointsPerDay}</dd>
|
||||
</div>
|
||||
<div>
|
||||
<dt>更新人</dt>
|
||||
<dd>{result.updatedByDisplayName || '-'}</dd>
|
||||
@@ -169,6 +199,6 @@ export function AdminProfileWalletConfigPage({
|
||||
}
|
||||
|
||||
function parsePositiveInteger(value: string) {
|
||||
const parsed = Number.parseInt(value, 10);
|
||||
return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
|
||||
const parsed = Number(value);
|
||||
return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
|
||||
}
|
||||
|
||||
@@ -1270,6 +1270,13 @@ button:disabled {
|
||||
background: #f8efe7;
|
||||
}
|
||||
|
||||
.admin-ghost-button.admin-user-wallet-reconcile-button {
|
||||
width: auto;
|
||||
min-width: 92px;
|
||||
padding: 0 10px;
|
||||
gap: 6px;
|
||||
}
|
||||
|
||||
.admin-ghost-button.admin-query-reset-button {
|
||||
width: auto;
|
||||
min-width: 76px;
|
||||
|
||||
@@ -760,9 +760,9 @@ export function App({
|
||||
) => Promise<void>)
|
||||
| null
|
||||
>(null);
|
||||
const executeChatAgentReplyRef = useRef<
|
||||
(prompt: string) => Promise<void>
|
||||
>(async () => undefined);
|
||||
const executeChatAgentReplyRef = useRef<(prompt: string) => Promise<void>>(
|
||||
async () => undefined,
|
||||
);
|
||||
const agentConversationSavingRef = useRef(false);
|
||||
const agentConversationBackgroundBusyRef = useRef(false);
|
||||
const agentConversationLoadVersionRef = useRef(0);
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
export async function readImage(): Promise<never> {
|
||||
throw new Error('native clipboard image is unavailable in root tests');
|
||||
}
|
||||
|
||||
export async function readText(): Promise<string> {
|
||||
return '';
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
export async function openUrl(): Promise<void> {}
|
||||
@@ -9,6 +9,17 @@ if ($genarrative_internal_client) {
|
||||
set $genarrative_maintenance 0;
|
||||
}
|
||||
|
||||
# 维护页自身依赖的品牌图片必须在维护期间保持可读；只放行精确文件，避免扩大公网静态面。
|
||||
location = /branding/taonier-maintenance-page.png {
|
||||
root /srv/genarrative/web;
|
||||
try_files /branding/taonier-maintenance-page.png =404;
|
||||
}
|
||||
|
||||
location = /branding/taonier-product-ip.png {
|
||||
root /srv/genarrative/web;
|
||||
try_files /branding/taonier-product-ip.png =404;
|
||||
}
|
||||
|
||||
location = /maintenance.html {
|
||||
root /var/lib/genarrative/maintenance;
|
||||
try_files /page.html @genarrative_default_maintenance;
|
||||
|
||||
@@ -1761,7 +1761,8 @@
|
||||
"type": "object",
|
||||
"required": [
|
||||
"viewport",
|
||||
"layers"
|
||||
"layers",
|
||||
"expectedRevision"
|
||||
],
|
||||
"properties": {
|
||||
"viewport": {
|
||||
@@ -1778,7 +1779,7 @@
|
||||
"expectedRevision": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"description": "可选的画布 revision CAS；不匹配时返回 409。"
|
||||
"description": "必填的画布 revision CAS；不匹配时返回 409。"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
@@ -2561,6 +2562,21 @@
|
||||
],
|
||||
"description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
|
||||
},
|
||||
"style": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"examples": [
|
||||
"none",
|
||||
"pixelArt"
|
||||
],
|
||||
"description": "可选生成后处理风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理；pixelArt 仅支持普通图片（kind 省略）和 character。未知字符串或不支持该风格的 kind 按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
|
||||
},
|
||||
"size": {
|
||||
"type": "string",
|
||||
"description": "兼容旧 size 入参；未传 aspectRatio/imageSize 时生效。",
|
||||
@@ -2585,7 +2601,7 @@
|
||||
"ui-design",
|
||||
"publication-material"
|
||||
],
|
||||
"default": "spec"
|
||||
"description": "省略时生成普通图片；其它值选择对应的专用生成流程。"
|
||||
},
|
||||
"model": {
|
||||
"type": "string",
|
||||
@@ -2950,6 +2966,7 @@
|
||||
},
|
||||
"iconDescriptions": {
|
||||
"type": "array",
|
||||
"description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。",
|
||||
"minItems": 1,
|
||||
"maxItems": 100,
|
||||
"items": {
|
||||
@@ -2963,6 +2980,21 @@
|
||||
],
|
||||
"description": "纯色抠像背景色。可传画布支持的纯色背景 hex（如 #CFEFFF）指定；传 \"auto\"、null 或省略则由服务端自动决策。"
|
||||
},
|
||||
"style": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"examples": [
|
||||
"none",
|
||||
"pixelArt"
|
||||
],
|
||||
"description": "可选生成后处理风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理；pixelArt 启用图标图集像素规整。未知字符串按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
|
||||
},
|
||||
"model": {
|
||||
"type": "string",
|
||||
"default": "gemini-3.1-flash-image-preview"
|
||||
@@ -3158,7 +3190,7 @@
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string",
|
||||
"description": "自动拆分未完成的稳定原因码。"
|
||||
"description": "自动拆分未完成的稳定原因码，包括原始连通域超限、局部候选拥挤、输出切片超限、处理超时、未识别到素材或切片持久化失败。"
|
||||
},
|
||||
"reason": {
|
||||
"type": "string",
|
||||
@@ -3176,8 +3208,13 @@
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string",
|
||||
"const": "postprocess-failed-source-preserved",
|
||||
"description": "透明背景处理最终失败并保留 provider 原图时的稳定原因码。"
|
||||
"enum": [
|
||||
"postprocess-failed-source-preserved",
|
||||
"dimension-restore-fallback",
|
||||
"unsupported-image-style",
|
||||
"multiple-generation-warnings"
|
||||
],
|
||||
"description": "生成成功但后处理发生非阻断降级时的稳定原因码。"
|
||||
},
|
||||
"reason": {
|
||||
"type": "string",
|
||||
@@ -3212,7 +3249,7 @@
|
||||
},
|
||||
"iconImageSrcs": {
|
||||
"type": "array",
|
||||
"description": "按图集 alpha 连通域拆分并持久化的独立素材列表。",
|
||||
"description": "识别图集中全部有效 alpha 连通域并持久化的独立素材列表，按视觉阅读顺序命名为“素材 N”；数量由图集内容决定，不由 iconDescriptions 数量决定。自动生成与手动拆分图集使用相同识别规则。",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
|
||||
}
|
||||
@@ -3226,7 +3263,7 @@
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。与通用 warning 互斥。"
|
||||
"description": "可信透明图集已成功持久化，但全连通域自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。原始连通域、输出数量或 CPU 预算超限不会产生切片 PUT、资源或画布切片。透明处理、Alpha/尺寸恢复、provider 原图修复性回读或透明图完整解码失败时走 provider 原图 source-only，sliceWarning 为 null。"
|
||||
},
|
||||
"prompt": {
|
||||
"type": "string"
|
||||
@@ -3290,14 +3327,8 @@
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "透明背景处理最终失败、provider 原图作为主结果时返回的非阻断告警。与 sliceWarning 互斥。"
|
||||
"description": "生成成功但风格归一化、尺寸恢复、透明背景处理、Alpha 回贴、provider 原图修复性回读、透明图完整解码或像素规整发生非阻断降级时返回。source-only 降级只返回 provider 原图且不会进入拆分；其它通用告警可以与 sliceWarning 并存。"
|
||||
}
|
||||
},
|
||||
"not": {
|
||||
"required": [
|
||||
"warning",
|
||||
"sliceWarning"
|
||||
]
|
||||
}
|
||||
},
|
||||
"EditorCharacterAnimationGenerationRequest": {
|
||||
|
||||
@@ -25,6 +25,82 @@
|
||||
- 验证方式：图模型与 SVG 定向测试覆盖去重、无效 ID、完整任务环、可见资源自引用闭环、任务流聚合、搜索过滤、选择高亮和拖动几何；AppSurface 覆盖两种边、type 模式卸载和项目切换销毁，并运行 shell typecheck、编码检查与 `git diff --check`。
|
||||
- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
## 2026-07-31 每日免费泥点基础额度纳入后台钱包配置
|
||||
|
||||
- 背景：每日免费泥点已是独立余额桶，但基础发放量仍在运行时固定为 `20`，后台“账号配置”只能维护注册初始泥点，运营调整需要改代码。
|
||||
- 决策：在 `profile_wallet_config` 尾部追加带默认值 `20` 的 `daily_free_points_per_day`，与 `initial_mud_points` 共用 `/admin/api/profile/wallet-config` 和后台账号配置页一次读写。尚未初始化当日额度的用户立即使用最新值；已初始化用户的当日余额不追补、不回收，下一北京时间业务日首次触达时按最新配置重置。跨日退款可继续使当日 `granted_points` 高于基础额度，因此充值中心 `dailyFreeResetPoints` 必须显式投影配置值，不用当日已发放总额反推。
|
||||
- 迁移与边界：旧 SpacetimeDB 表行和旧迁移 JSON 均缺少新字段，自动迁移与 `migration.rs` 导入归一统一补 `20`；新字段只允许正整数。每日任务奖励、扣费桶顺序、退款归因和北京时间日切边界不变。
|
||||
- 影响范围：`module-runtime`、`spacetime-module`、`spacetime-client`、`shared-contracts`、`api-server`、`apps/admin-web`、SpacetimeDB 迁移与生成绑定。
|
||||
- 验证方式：后台页面与 API 定向测试、每日免费日切与迁移定向 Rust 测试、`npm run spacetime:generate -- --rust-only`、`npm run check:spacetime-schema`、`npm run admin-web:typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-31 发布前延期冷备份由独立 systemd 上传并补偿扫描
|
||||
|
||||
- 背景：Jenkins Stdb Publish 的 async 备份先生成 `uploadStatus=deferred` 的本地 tar.gz，再从 EXIT trap 用 `nohup` 启动上传。后台进程仍继承 Jenkins Cookie，作业结束时可被清理；旧 deferred manifest 也没有后续补偿扫描，导致 dev 的本地冷备份持续占满根盘。
|
||||
- 决策：`production-stdb-publish.sh` 只能用具名、`Type=exec`、`--collect` 的 `systemd-run` transient service 启动异步上传，禁止回退 `nohup`。独立服务执行 `database-backup-to-oss.mjs --upload-deferred-dir <backup-dir>`，在同一备份锁内按文件名串行补传同库 `deferred/pending` 归档；目录外路径或 manifest/归档不匹配时失败关闭，缺失归档的历史 manifest 只报告不删除。
|
||||
- 清理边界：只有 archive 上传与 HEAD 验真、manifest sidecar 上传验真、baseline state 写入全部成功后，才按 `GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL` 删除精确的 archive 与 manifest。transient unit 未启动或上传失败时保留归档，由后续 publish 继续补偿；`files-history` timer 仍不负责清理这些 tar.gz。
|
||||
- 影响范围：`scripts/deploy/production-stdb-publish.sh`、`scripts/database-backup-to-oss.mjs`、生产运维门禁和本文档。
|
||||
- 验证方式：`npm run check:database-backup`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；dev 现场还必须确认 transient unit 不在 Jenkins session scope，旧 deferred 归档逐份变为 OSS 已验真对象后被删除，备份锁清空，核心服务与公开接口健康。
|
||||
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-29 图集切片必须受前置容量和有界 CPU 保护
|
||||
|
||||
- 背景：图标与 UI 图集的 alpha 连通域识别会在 async handler 上同步执行；原始连通域合并采用全量两两比较，`64` 个输出限制又晚于排序、裁剪和 PNG 编码。碎块或噪点图会放大 CPU 与内存成本，手动拆分、图标自动拆分和 UI 提取都受影响。另一方面，图标与 UI 的 Alpha 尺寸恢复、provider 原图回读或透明图解码失败此前只记日志，仍会把不可信透明图持久化并拆分。
|
||||
- 决策：`platform-image` 在每次 flood-fill 后累计所有原始连通域（包括随后过滤的噪点）并以 `4096` 为硬上限；合并只通过 `64px` 空间网格查询 `48px` 最大邻域内且满足辅助部件尺寸条件的候选，单网格最多登记 `256` 个组件、单 source 最多保留 `512` 个候选，拥挤时明确返回资源限制错误；调用方把固定 `maxOutputSlices=64` 传入 platform slicer，并在排序、裁剪和 PNG 编码前拒绝超限。三条入口统一走 2 路 semaphore、30 秒本地上界与请求绝对 deadline 共同保护的 `spawn_blocking`，permit 必须由 blocking 闭包持有。自动图标 / UI 超限以空切片和稳定 `sliceWarning` 完成，手动拆分返回 `422`，两者都不得产生任何切片 PUT、资源或画布切片；自动路径已成功的整张图集仍按既有契约保留。
|
||||
- source-only 收口：角色、图标和 UI 共用同一个 provider 原图收口 helper。BgFilter 最终失败、Alpha 比例漂移超过 `5%`、provider 原图修复性回读失败、Alpha 回贴失败或透明图完整解码失败时，只用已保存 provider 原图完成占位，返回 `completed + warning`；图标 / UI 固定 `iconImageSrcs=[]`、`sliceWarning=null`，不写透明图、不拆分。provider 原图本身无法解码时在首次持久化前失败，不再伪造 `512×512` 元数据。
|
||||
- 影响范围：`server-rs/crates/platform-image/src/generated_asset_sheets/`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布图标与 UI 素材生成 / 手动拆分链路；不修改请求 DTO、扣费退款、SpacetimeDB schema 或成功路径多产物布局。
|
||||
- 验证方式：platform-image 覆盖大量独立 `4×4` 块、单像素噪点和 65 个有效输出；api-server 覆盖比例漂移、原图回读失败、截断透明 PNG、共享 source-only helper 无持久化副作用，以及三入口统一 bounded slicer。运行 `cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_project::tests --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-29 像素规整降级必须复用交付尺寸守卫
|
||||
|
||||
- 背景：像素模式接入「角色带背景原图与透明图统一交付尺寸」后，删除了原先像素路径末尾的后置尺寸恢复。但像素规整的 best-effort 降级分支（预算耗尽、回读 provider 原图失败或超时、CPU permit 获取失败、worker 内 deadline、join 异常、worker 超时）都直接返回 BgFilter 原始输出并把尺寸错误置为 `None`，跳过了非像素路径已有的尺寸比对与 alpha 回贴。BgFilter 回图尺寸漂移是已知现象，叠加并发上限 2 导致的 permit 超时后，角色会绕过「改用已保存的同尺寸原图完成画布」的安全降级，角色和图标都可能持久化尺寸漂移的低分辨率透明图。
|
||||
- 决策：像素路径的每一条降级都必须经 `degrade_editor_pixel_art_to_postprocessed_with_dimension_guard` 收口，该守卫复用非像素路径的 `apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original`：先做纯内存尺寸比对，与交付尺寸一致就原样返回且不产生额外 OSS GET；漂移才回读原图重贴 alpha；修复失败如实返回尺寸错误，由调用方按各自既有语义处理。由 provider 原图逐像素合成的 `rgba_source` fallback 尺寸天然正确，不再经守卫。像素路径函数因此需要显式接收交付宽高。
|
||||
- 生效范围（由同日后续决策补齐）：像素路径继续保证不把 BgFilter 原始输出连同 `None` 尺寸错误交回调用方；角色、图标和 UI 拿到尺寸 / Alpha 错误后现已统一走 provider 原图 source-only 收口，不再持久化或拆分尺寸异常、比例异常或不可解码的透明图。
|
||||
- 影响范围：`server-rs/crates/api-server/src/editor_project.rs` 的角色与图标像素规整降级路径；不改变成功路径、OSS PUT 次数、资源类型、画布项或前端契约，OSS GET 仍只在尺寸漂移时发生。
|
||||
- 验证方式：`pixel_art_degrade_paths_guard_postprocessed_delivery_dimensions` 结构断言固定"降级分支不得返回 `(postprocessed, None, …)`"与守卫的委托实现；运行 `cargo test -p api-server editor_project --manifest-path server-rs/Cargo.toml`、`npm run check:rustfmt`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：本文件「2026-07-29 角色带背景原图与透明图统一交付尺寸」与「2026-07-28 图片生成风格使用可扩展字段并以纯内存像素规整首发」。
|
||||
- 补充（同日）：守卫的回读必须分两类处理。已取得 provider 原图的四条降级分支（permit 获取失败、worker 内 deadline、join 异常、worker 超时）改走纯内存守卫 `degrade_editor_pixel_art_with_provider_source`，零额外 GET；尚未取得原图的三条分支（进函数即预算耗尽、第一次回读失败、第一次回读超时）才走会回读的守卫。计数断言固定「回读守卫 3 处、内存守卫 4 处」，防止后续新增分支时误用回读版本。
|
||||
- OSS 回读口径（修正此前「最多增加一次 OSS GET」的措辞）：约束是**不重复读取已经成功取得的对象**，而不是"整个请求至多一次 GET"。仅在尺寸漂移且尚未持有原图时才发起最多一次修复性回读，失败后不再重试；因此第一次回读失败或被像素预算掐断时，允许存在第二次、也是最后一次尝试——第一次超时往往并非 OSS 异常，而是被 30 秒像素预算切断，此时对象通常可正常读取，放弃修复反而会让角色更频繁地退化为原图单产物。
|
||||
- 回读上界：修复性回读必须始终有绝对 deadline。优先取外层 `request_deadline`，但它只在队列 worker 路径上有值——inline HTTP 请求的 `RequestContext` 默认 `external_call_deadline = None`，此时守卫自行以 `Instant::now() + EDITOR_PIXEL_ART_MAX_PROCESSING_DURATION` 重新计时派生上界，不得退化为无界 `download.await`。`apply_editor_postprocessed_alpha_from_persisted_provider_source_or_original` 的可选 `download_deadline` 只对像素守卫传值，非像素路径继续传 `None` 保持既有语义不变。结构断言固定守卫内必须同时出现 `request_deadline.unwrap_or_else(` 与 `EDITOR_PIXEL_ART_MAX_PROCESSING_DURATION`，防止兜底上界被移除后静默退回无界。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-29 角色带背景原图与透明图统一交付尺寸
|
||||
|
||||
- 背景：图片画布已将模型原生回图归一到统一业务像素矩阵，但角色分支为了保留 provider 原生分辨率，先持久化带背景原图，只在扣背后归一透明主图。因此同一个 1K 角色任务会同时给出模型原生大图和长边 `1024` 的透明图。
|
||||
- 决策：角色分支必须在持久化带纯色背景原图和调用 BgFilter 之前，先按统一业务像素矩阵执行一次尺寸归一；该原图和透明派生图始终使用同一实际像素尺寸，1K 的长边为 `1024`。若 provider 回图任意一边小于业务目标或比例偏差过大，仍禁止放大或大幅裁切；此时两张图一同保留 provider 实际尺寸并返回通用 `warning`，不允许只改透明图。BgFilter 回图尺寸漂移时只允许在宽高比偏差不超过 `5%` 时重采样 alpha 蒙版并回贴到该原图；蒙版比例超限、回贴失败或尺寸验证失败时必须改用原图单产物降级，不持久化尺寸或比例不一致的透明图。若尺寸降级和后处理降级同时发生，同一条 `warning.reason` 必须同时保留两个原因。
|
||||
- 影响范围：`server-rs/crates/api-server/src/editor_project.rs` 的角色生成、原图持久化、BgFilter 输入、项目资源尺寸与画布图层 Resolution；不改变前端请求 DTO、扣费、素材类型或多产物布局。
|
||||
- 验证方式：后端定向测试覆盖角色全尺寸矩阵：`nanobanana2` 的 `0.5K / 1K / 2K` 和 `gpt-image-2` 的 `1K / 2K`，每档均覆盖 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`，30 个组合全部构造大于目标尺寸的真实 PNG provider 回图并执行像素恢复，不只校验字符串映射；另覆盖欠尺寸禁止放大、比例超限、BgFilter 错比例 alpha 蒙版拒绝和组合告警。同时从函数调用顺序上固定“尺寸归一 → 持久化带背景原图 → BgFilter”。运行 `cargo test -p api-server editor_project --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-29 图标图集 BgFilter 开启 cross-check
|
||||
|
||||
- 背景：图标 spritesheet 的透明化需要提高主体内部孔洞、轮廓和相邻小图标边缘的交叉校验质量。
|
||||
- 决策：生成图标素材的 BgFilter `background_mode=flat` 请求固定显式传 `cross_check=on`，与角色形象和角色动作逐帧去背一致；UI 设计图素材提取及手动 complex 去背景继续传 `off`。该参数仍属于后端内部供应商策略，不进入前端 DTO 或外部 OpenAPI。
|
||||
- 边界：不修改 BgFilter fallback、Alpha 回贴、默认关闭 despill、图标切片、OSS / 资源 / 画布持久化和任务告警语义。
|
||||
- 验证方式：运行 `cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:rustfmt`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 画布 Agent 工具生命周期统一经 object-safe trait 分派
|
||||
|
||||
- 背景：画布 Agent 八类工具的参数规范化、确认展示、计价与 worker payload、完成结果格式化和媒体投影分别在 `tool_args.rs`、`display_args.rs`、`api.rs`、`reconcile.rs` 重复按工具名分派；新增或调整工具时容易漏改其中一处。
|
||||
- 决策：api-server 以 object-safe `EditorAgentTool: ToolDyn` 取代仅承载计价的 `EditorAgentPricedTool`。trait 的所有动态方法统一接收 `serde_json::Value`；每个具体工具实现自行反序列化为真实 Args / 结果，`validate_args` 与 `format_execute_message` 显式转发到 `platform-editor-agent` 已有强类型实现，再把规范 Args、展示投影、job payload、完成文本或媒体引用擦除回公共类型。`editor_agent_tool(toolName, context)` 绑定当前 `EditorToolContext` 并作为唯一八分支工具名分派；规划、确认和回填不得再维护平行 switch。LLM builder 的工具注册列表保持独立显式维护。
|
||||
- 边界：不改变工具名、LLM schema、OSS 消息文档、`displayArgs`、模型定价、job kind / payload、dedupe key、worker、计费、完成消息或图片 / 视频 / 音频引用契约，不涉及前端、SpacetimeDB schema 或迁移。
|
||||
- 影响范围：`server-rs/crates/api-server/src/editor_agent` 的工具 trait、参数规范化、确认入队与终态回填，以及画布 Agent 专题文档。
|
||||
- 验证方式：覆盖八类 factory 与 dyn validation / pricing / display / job / formatter / media projection 的 api-server 定向测试，运行 `cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:rustfmt`、`npm run check:encoding` 和 `git diff --check`。
|
||||
|
||||
---
|
||||
## 2026-07-28 AI 游戏创作资源画布布局使用本地双模式 CAS sidecar
|
||||
|
||||
- 背景：项目开发工作台当前只在 React 会话内保存同分类资源的一维拖拽顺序，项目切换或客户端重启后重建默认排列；工作台 PRD 虽已给出二维位置字段，但缺少落盘路径、坐标系、Tauri API、CAS、异常与安全边界，仍不足以直接编码。
|
||||
@@ -312,8 +388,8 @@
|
||||
|
||||
## 2026-07-10 画布 Agent 工具确认分离执行参数与展示投影
|
||||
|
||||
- 背景：画布 Agent 已在实际生成前进入 `pending_confirmation`，但 `EditorAgentToolCall.args` 只保存工具私有 JSON，其中图片参数是保护真实 data key 的 SHA-256 opaque ID。前端直接解析 raw args 只能显示内部哈希或图片数量，无法向用户准确展示即将使用的目标图、参考图和完整参数；若直接把图片 URL 或对象塞回 raw args，又会破坏确认执行反序列化和 LLM 不可见真实 data key 的安全边界。
|
||||
- 决策：`EditorAgentToolCall.args` 继续作为确认执行唯一真相，不允许前端改写或回传替代参数；新增必填 `displayArgs` 只读展示投影，内含 `stringArgs`、`imageArgs` 和 `extras.priceMudPoints`。`stringArgs` 承载提示词与规格等用户可见字段，`imageArgs.refs` 承载 `imageId` 及后端解析出的 `objectKey`、`imageSrc`、可选缩略图、标签和尺寸；`extras.priceMudPoints` 由 api-server 在创建待确认消息时使用后端运行时模型定价快照计算，前端只显示“预计消耗 N泥点”，不自行计算或回传价格。api-server 必须按已注册 tool 白名单，从已校验 args 与 OSS 会话文档的附件 / 历史生成结果构建该投影；前端只渲染投影，以 `ResolvedAssetImage` 换签显示图片，不解析 tool 私有 schema、不展示 SHA-256 ID。展示价格不参与确认执行或实际扣费，确认后仍由既有生成 BFF 按后端运行时定价预扣费。删除只重复 `args` 且没有稳定语义的 `EditorAgentToolCall.summary`。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
|
||||
- 背景：画布 Agent 已在实际生成前进入 `pending_confirmation`，但 `EditorAgentToolCall.args` 只保存工具私有的规范参数 JSON，其中图片参数是保护真实 data key 的 SHA-256 opaque ID。前端直接解析 `args` 只能显示内部哈希或图片数量，无法向用户准确展示即将使用的目标图、参考图和完整参数；若直接把图片 URL 或对象塞回 `args`，又会破坏确认执行反序列化和 LLM 不可见真实 data key 的安全边界。
|
||||
- 决策：LLM 返回的原始工具参数只作为 api-server 本次处理的瞬时输入；后端按已注册 ToolArgs 反序列化、补齐默认值、删除未知 / 退役字段、完成工具参数校验并重新序列化后，才把结果写入 `EditorAgentToolCall.args`。校验失败的调用不得持久化为待确认消息。该规范 `args` 是确认执行唯一真相，不允许前端改写或回传替代参数；新增必填 `displayArgs` 只读展示投影，内含 `stringArgs`、`imageArgs` 和 `extras.priceMudPoints`。`stringArgs` 承载提示词与规格等用户可见字段，`imageArgs.refs` 承载规范 `args` 中的 `imageId` 及后端解析出的 `objectKey`、`imageSrc`、可选缩略图、标签和尺寸；`extras.priceMudPoints` 由 api-server 在创建待确认消息时使用后端运行时模型定价快照计算，前端只显示“预计消耗 N泥点”，不自行计算或回传价格。api-server 必须按已注册 tool 白名单，从规范 `args` 与 OSS 会话文档的附件 / 历史生成结果构建该投影；前端只渲染投影，以 `ResolvedAssetImage` 换签显示图片，不解析 tool 私有 schema、不展示 SHA-256 ID。展示价格不参与确认执行或实际扣费，确认后仍由既有生成 BFF 按后端运行时定价预扣费。删除只重复 `args` 且没有稳定语义的 `EditorAgentToolCall.summary`。模块尚未上线，不保留缺少 `displayArgs` 时读取 `args` 的旧消息降级路径。
|
||||
- 影响范围：`shared-contracts` / `packages/shared` 的 `editorAgent` DTO、`api-server/src/editor_agent/api.rs` 的待确认消息构建、画布 Agent 待确认卡、OSS 会话消息文档与相关测试。
|
||||
- 验证方式：`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_agent`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、`npm run test -- src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx src/services/image-editor/editorAgentClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`。
|
||||
@@ -438,7 +514,7 @@
|
||||
## 2026-07-14 后台账号采用 owner 引导账号与一级 Tab 实时授权
|
||||
|
||||
- 背景：后台此前只支持一组环境变量管理员，所有 `/admin/api/*` 共用统一 admin 门禁，无法给运营、审核等人员分配独立账号和页面范围。
|
||||
- 决策：现有 `GENARRATIVE_ADMIN_USERNAME/PASSWORD` 账号固定作为不可编辑 owner；新增 member 独立保存到私有 `admin_account` 表，密码使用 Argon2id 摘要。登录凭据快照与普通账号快照在类型层分离，普通列表、按 ID 查询和写入响应不包含 `password_hash`。Argon2id 在 blocking 任务中运行并由 api-server 有界限流；未知、停用和 owner 错密账号使用 dummy hash 抹平耗时。member 权限粒度固定为后台 18 个一级 Tab，“账号管理”只允许 owner 且不可授予 member。member 每次请求重新读取当前账号并校验启停、`token_version` 和 Tab 权限；权限、密码或启停变化递增版本并立即淘汰旧 JWT。账号不存在返回 `401`，SpacetimeDB 故障保留 `502/503` 而不清理有效 token。前端导航过滤和页面挂载门禁只负责体验，正式授权由 api-server 的 API-to-Tab 矩阵执行，未登记的新后台路由对 member 默认拒绝。后台面向运营展示管理员身份时统一使用 `displayName`；持久审计仍保存稳定 subject，由 api-server 解析显示名称，前端不得暴露账号 ID 或用登录用户名代替。写接口必须在主事务前加载显示名目录，或在主事务后降级解析，不能把已提交写入伪装为失败。
|
||||
- 决策：现有 `GENARRATIVE_ADMIN_USERNAME/PASSWORD` 账号固定作为不可编辑 owner；新增 member 独立保存到私有 `admin_account` 表，密码使用 Argon2id 摘要。登录凭据快照与普通账号快照在类型层分离，普通列表、按 ID 查询和写入响应不包含 `password_hash`。Argon2id 在 blocking 任务中运行并由 api-server 有界限流；未知、停用和 owner 错密账号使用 dummy hash 抹平耗时。member 常规权限粒度固定为后台 15 个一级 Tab，“账号管理”只允许 owner 且不可授予 member；2026-07-24 起，历史花费手动对账作为独立高风险操作权限 `profile-wallet-consumption-reconcile`，不随任意 Tab 自动授予。member 每次请求重新读取当前账号并校验启停、`token_version`、Tab 权限和独立操作权限；任一权限、密码或启停变化递增版本并立即淘汰旧 JWT。账号不存在返回 `401`，SpacetimeDB 故障保留 `502/503` 而不清理有效 token。前端导航和操作按钮过滤只负责体验，正式授权由 api-server 路由权限矩阵执行，未登记的新后台路由对 member 默认拒绝。后台面向运营展示管理员身份时统一使用 `displayName`；持久审计仍保存稳定 subject，由 api-server 解析显示名称，前端不得暴露账号 ID 或用登录用户名代替。写接口必须在主事务前加载显示名目录，或在主事务后降级解析，不能把已提交写入伪装为失败。
|
||||
- 影响范围：`admin_account`、SpacetimeDB typed procedures / client facade、后台 JWT 与 session DTO、`/admin/api/accounts*`、后台路由权限中间件、admin-web 导航和账号管理页。
|
||||
- 验证方式：SpacetimeDB schema / client / API 定向测试、`npm run check:admin-account-procedures` 隔离 procedure smoke、完整路由矩阵测试、admin-web 权限路由与账号 API 测试、owner/member 浏览器 smoke、`npm run check:spacetime-schema`、编码与 diff 门禁。
|
||||
- 关联文档：`docs/technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md`。
|
||||
@@ -447,7 +523,7 @@
|
||||
|
||||
- 背景：图片画布的普通图片、规范、角色、图标图集、UI 设计、宣发素材、视频和音频默认使用“类型 + 数字”命名，用户只能在生成后单独重命名素材，画布图层、项目资源和素材库名称容易不一致。
|
||||
- 决策：主生成状态继续使用可选 `assetLabel`，名称最多 80 个字符并在提交时去除首尾空格；当前生成面板不展示“资源名称”标签和输入框，默认沿用现有自动编号名称，历史状态或内部调用若携带非空名称，仍必须让同一个名称贯穿 `assetLabel`、`canvasCompletion.title`、本地结果图层标题、项目资源和账号素材库，不允许各链路自行生成不同名称。移除名称输入后，角色、图标图集、UI 设计和角色动作等提示词输入恢复统一可见边框。
|
||||
- 派生产物：图标和角色动作后端契约补齐 `assetLabel`。带背景原图、角色动作绿幕预览等具有独立复用价值的中间产物基于主名称追加“（原图）”等后缀；普通图片和图片修改的纯尺寸变换在内存完成后只上传一次，不生成“原始输出”副本。图标切片继续按用户填写的图标描述命名，不继承图集名称覆盖独立素材语义。
|
||||
- 派生产物：图标和角色动作后端契约补齐 `assetLabel`。带背景原图、角色动作绿幕预览等具有独立复用价值的中间产物基于主名称追加“（原图）”等后缀；普通图片和图片修改的纯尺寸变换在内存完成后只上传一次，不生成“原始输出”副本。2026-07-29 起，图标切片不再按用户提示词命名，统一按全连通域视觉顺序命名为 `素材 N`。
|
||||
- 影响范围：图片画布生成状态与面板、提交模型、图标和角色动作请求契约、项目资源 / 素材库持久化和相关编辑器文档。
|
||||
- 验证方式：覆盖生成面板不渲染资源名称输入、提示词边框、空白回退、内部自定义名与长度限制，以及图片 / 图标 / 视频 / 音频 / 角色动作的请求名称、完成快照标题和素材名称一致性；运行前端定向测试、Rust 契约与 API 定向测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
@@ -867,7 +943,9 @@
|
||||
## 2026-06-24 图片画布项目封面使用静态快照资源
|
||||
|
||||
- 背景：项目页和创作主页最近项目曾在卡片中根据项目 `layers + viewport + resources` 临时重建一份迷你画布，视觉上像封面，但它不是持久快照，也会把列表页变成画布布局解释器。
|
||||
- 决策：项目封面图改为画布当前视口栅格化后的静态资源。前端在项目加载后和防抖保存 layout 时生成 320x240 PNG，走私有 OSS / asset object 上传，再创建 `editor_project_resource`，其中 `assetKind="project-cover-snapshot"`、`sourceType="uploaded"`；项目列表和创作主页最近项目只读取最新封面快照资源渲染，没有快照时显示项目占位，不再回退为实时画布组合。
|
||||
- 决策：项目封面图改为画布当前视口栅格化后的静态资源。前端在项目加载后和防抖保存 layout 时生成 320x240 WebP，走私有 OSS / asset object 上传，再创建 `editor_project_resource`，其中 `assetKind="project-cover-snapshot"`、`sourceType="uploaded"`；项目列表和创作主页最近项目只读取最新封面快照资源渲染，没有快照时显示项目占位，不再回退为实时画布组合。
|
||||
- 2026-07-24 补充：封面取景以当前画布工作区的实际尺寸和渲染态 viewport 为准，先绘制工作区背景色，再从视口中心等比放大并裁成 4:3；持久化显示倍率不得直接用于封面渲染。
|
||||
- 2026-07-29 补充：常规编辑仍沿用防抖保存；用户从画布返回项目页时必须取消待执行 timer，以最新权威 revision 立即保存 layout，并等待同一视口封面写入本地缓存和正式项目资源后再导航。当前视口存在图层但全部位于取景外时仍生成纯背景封面，不沿用旧缩略图。
|
||||
- 影响范围：`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`src/components/image-editor/ImageCanvasProjectCoverSnapshotModel.ts`、`src/components/project/ProjectCanvasCover.tsx`、`src/components/project/ProjectGalleryView.tsx`、`src/components/creation-home/CreationLandingView.tsx` 和图片画布数据契约文档。
|
||||
- 验证方式：运行项目页、封面快照模型、图片画布项目持久化和媒体上传相关前端测试，执行 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
|
||||
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
@@ -915,7 +993,7 @@
|
||||
## 2026-06-18 图片画布 UI 设计图提取素材保留图集
|
||||
|
||||
- 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
|
||||
- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。透明背景处理正常成功时，UI 提取把透明 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放 provider 原图和拆分成功的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成在透明背景处理正常成功时把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库和画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分素材从 provider 原图右侧继续排列。拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。2026-07-16 起，透明背景处理最终失败时只把已经持久化的 provider 原图作为唯一主图放入画布，以 `completed + warning` 收口，不创建透明图集，也不继续拆分。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
|
||||
- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。透明背景处理正常成功时，UI 提取把透明 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放 provider 原图和拆分成功的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成在透明背景处理正常成功时把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库和画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分素材从 provider 原图右侧继续排列。拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。2026-07-16 起，透明背景处理最终失败时只把已经持久化的 provider 原图作为唯一主图放入画布，以 `completed + warning` 收口，不创建透明图集，也不继续拆分。2026-07-29 起，图标生成的自动拆分与手动拆分共同识别全图集有效连通域，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，不再以提示词条目数决定切片数量；手动拆分仍保留且不计费。所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
|
||||
- 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。
|
||||
- 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。
|
||||
- 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
|
||||
@@ -4725,8 +4803,7 @@
|
||||
|
||||
- 背景：VectorEngine Apifox `api-349239079` 暴露 OpenAI-compatible `POST /v1/chat/completions`；创意 Agent 和通用 LLM 代理需要统一到 VectorEngine 文本服务，并将默认文本模型切换为 `gpt-5.4-mini`。
|
||||
- 决策：创意 Agent 的 `CREATIVE_AGENT_GPT5_MODEL` 固定为 `gpt-5.4-mini`，协议切到 Chat Completions，不再携带旧 APIMart `official_fallback` 字段；画布 Agent 侧边栏聊天规划请求也复用该模型和 Chat Completions 协议，不再显式使用 `gpt-4o` / Responses。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`。未单独配置 `GENARRATIVE_LLM_API_KEY` 时，api-server 可复用 `VECTOR_ENGINE_API_KEY`；前端 LLM 客户端必须兼容 OpenAI `choices`、api-server raw `{content}` 和项目 envelope `{ok,data:{content}}` 三种非流式响应，以及 OpenAI SSE delta 和 api-server `event: delta` 两种流式响应。
|
||||
- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `toolName` / `resourceId` / `objectKey` 等轻量元数据。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
|
||||
- 决策补充：画布 Agent 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 Agent 规划 prompt 和 function-calling 工具选择约束，不是侧边栏 UI 说明文案。此类请求默认走 `generate_image`，prompt 必须要求规范展板包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等视觉规范元素；角色规范图若是规范展板也走 `generate_image`，只有实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
|
||||
- 决策补充：画布 Agent 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 Agent 规划 prompt 和 function-calling 工具选择约束，不是侧边栏 UI 说明文案。此类请求默认走 `generate-image`，prompt 必须要求规范展板包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等视觉规范元素；角色规范图若是规范展板也走 `generate-image`，只有实际角色立绘才走 `generate-character`，多个图标素材 / 图集才走 `generate-icon-spritesheet`。
|
||||
- 影响范围：`server-rs/crates/platform-agent`、`server-rs/crates/api-server/src/config.rs`、`src/services/llmClient.ts`、`.env.example`、`deploy/env/api-server.env.example`、`scripts/test-ve-llm.mjs`。
|
||||
- 验证方式：`npm run test -- src/services/llmClient.test.ts`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml from_env_reads_non_public_models_and_urls app_state_builds_creative_agent_gpt5_client_from_vector_engine_settings llm_chat_completions editor_agent_llm_request_uses_vector_engine_chat_model`、`cargo test -p platform-agent --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
@@ -4851,7 +4928,7 @@
|
||||
## 2026-07-13 临时维护公告改为 release 外运行态覆盖
|
||||
|
||||
- 背景：一次性停服公告曾直接提交到 `public/maintenance.html`，后续 Web Build 将它持续打入 `web.tar.gz`，每次 Web Deploy 或再次进入维护都会重新显示已经过期的公告。
|
||||
- 决策：`public/maintenance.html` 永久作为无日期、无具体时段的默认维护页，并使用 `public/branding/taonier-maintenance-page.png` 作为品牌视觉；生产 Web 打包必须对最终 `web/maintenance.html` 执行临时文案门禁。临时公告通过 `maintenance-on.sh --page-file <公告HTML>` 原子安装到 `/var/lib/genarrative/maintenance/page.html`，Nginx 与 Pingora 优先读取该运行态文件，缺失时回退 Web 制品默认页。
|
||||
- 决策：`public/maintenance.html` 永久作为无日期、无具体时段的默认维护页，并使用 `public/branding/taonier-maintenance-page.png` 作为品牌视觉；生产 Web 打包必须对最终 `web/maintenance.html` 执行临时文案门禁。临时公告通过 `maintenance-on.sh --page-file <公告HTML>` 原子安装到 `/var/lib/genarrative/maintenance/page.html`，Nginx 与 Pingora 优先读取该运行态文件，缺失时回退 Web 制品默认页。维护期间只精确放行 `/branding/taonier-maintenance-page.png` 与 `/branding/taonier-product-ip.png`，不得扩大到整个品牌或静态资源目录；网关 smoke 必须验证这两个路径仍返回 PNG，同时其它公网页面、API 与后台静态资源继续命中维护门禁。
|
||||
- 生命周期：新维护窗口未提供 `--page-file` 时清理 marker 外残留公告；同一窗口内 Stdb / API 发布重复调用 `maintenance-on.sh` 时保留已安装公告；`maintenance-off.sh` 同时清理 marker 和公告页。Web Deploy 不再拥有临时公告事实源。
|
||||
- 影响范围：默认维护页、维护开关脚本、Nginx snippet、Pingora 配置与 smoke、生产 Web 发布包门禁和生产运维文档。
|
||||
- 验证方式：`npm run check:maintenance-page`、`npm run check:nginx-spa-routes`、`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`。
|
||||
@@ -5654,6 +5731,40 @@
|
||||
- 微信边界：小程序客户端仍只上传 `wechatPhoneCode`；`platform-auth` 必须要求微信成功响应中的 `phoneNumber`、`countryCode` 与 `purePhoneNumber` 均存在且非空，但只使用后两项执行国家码校验和 E.164 构造。腾讯官方仅说明境外 `phoneNumber` 会带区号，并未承诺 E.164 格式，中国号码示例中它与纯号码相同，因此不得校验 `phoneNumber == +{countryCode}{purePhoneNumber}`。微信字段缺失时失败关闭，不能使用普通请求的 `86` 默认值。
|
||||
- 数据边界：认证投影与 SpacetimeDB 的 `phone_number_e164` 保持不变，不新增国家码或纯号码列，也不需要 schema 迁移或 bindings 生成。
|
||||
|
||||
## 2026-07-24 后台用户详情展示历史花费泥点
|
||||
|
||||
- 口径：`historicalConsumedPoints` 表示用户历史总消费，只累计 `profile_wallet_ledger.source_type = asset_operation_consume` 且 `amount_delta < 0` 的绝对值；`asset_operation_refund` 不冲减，充值退款追回、余额重置、赠送和退款 hold 均不计入。
|
||||
- 投影边界：新增 `profile_wallet_consumption_total`，已有投影时消费流水成功落账在同一 SpacetimeDB 事务内按主键 O(1) 原子累加；退款不回减。首次上线在停止业务写入的维护窗口由 owner 调用 `POST /admin/api/profile/users/initialize-consumption-projections`，一次扫描全部权威钱包流水，为每个已有钱包流水的用户建立存量投影，成功后才能恢复流量。维护遗漏或新用户缺行时，首次消费和 runtime service identity 受限的 `admin_get_profile_wallet_detail_and_return` 都可按用户索引兜底重建一次；消费事务重建已包含当前流水，不重复加本次金额。不得用最近 50 条流水列表近似，也不得把全量流水扫描塞进充值订单每行复用的通用钱包快照。
|
||||
- 对账边界：保留管理员显式手动对账。owner 始终可用；member 必须单独持有 `profile-wallet-consumption-reconcile` 独立操作权限，任意 Tab 都不隐式授予。`POST /admin/api/profile/users/reconcile-consumption` 经二次确认后调用 runtime service identity 受限 procedure，扫描该用户全部权威流水、比较并校准投影，记录管理员与对账时间。
|
||||
- 展示边界：现有共享“用户详情”弹窗的钱包区增加“历史花费”，前端只展示 BFF 顶层字段，不自行汇总账单；只有 BFF 返回 `canReconcileConsumption=true` 时展示手动对账按钮。
|
||||
- 验证方式：SpacetimeDB 钱包聚合测试、api-server / admin-web 定向测试、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run admin-web:typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
## 2026-07-28 图片生成风格使用可扩展字段并以纯内存像素规整首发
|
||||
|
||||
- 契约：普通图片 / 角色共用的图片生成请求和图标图集生成请求增加可选字符串 `style`，当前公开合法值为 `none / pixelArt`。省略、`null`、空字符串和 `none` 归一为内部 `None` 且不告警；未知字符串、或在 `spec / quick-edit / ui-design / publication-material` 等不支持的图片 `kind` 上请求 `pixelArt` 时，按 `None` 继续原管线并返回 `unsupported-image-style` 通用告警；非字符串 JSON 返回 `400`。旧队列 payload 缺少字段时兼容为 `None`。
|
||||
- UI 边界：只有普通 `生成图片`、`生成角色形象` 和 `生成图标素材` 显示 `像素艺术` 勾选项；当前选择可进入已有生成器快照和请求 / 队列 payload，但不写入 `generationInputs`、素材元数据或新表。画布 Agent 和其它生成 / 编辑入口不开放该选项。
|
||||
- 处理边界：`PixelArt` 由 `platform-image` 的纯同步、纯内存 Rust 模块执行，不运行 Python、不访问 OSS / 数据库 / 画布。普通图片直接使用 provider 图；角色和图标必须等 BgFilter 成功并把 Alpha 回贴到 provider 原尺寸后，以 provider 平底原图分析网格、以透明 RGBA 图采样。固定参数为分析色数 16、Alpha 覆盖阈值 0.375、像素尺寸自动、相邻边缘峰间距使用线性插值 P30 估算步长、无固定色板、K-means 最大采样 262144；单格 RGB 按 Alpha 加权，输出 Alpha 只为 0 / 255，逻辑低分辨率结果用 nearest 恢复交付尺寸并跳过 Lanczos。2026-07-29 合并「角色带背景原图与透明图统一交付尺寸」后本条修订：像素模式不再豁免提前归一，网格分析源是已按业务像素矩阵 `resize_to_fill`（Lanczos 重采样 + 居中裁切）后的交付尺寸平底图，不再是 provider 原生分辨率图；像素规整在交付尺寸上完成、由 snapper 自行还原回输入尺寸，因此不再执行后置的 nearest 二次恢复。
|
||||
- 执行边界：像素规整 CPU 工作使用进程级最大并发 2；取得并发许可的排队时间与实际处理时间共享最多 30 秒预算，同时不得晚于当前请求 deadline，最终取更早者。输入图片任一边上限为 10000 像素、总像素上限为 8294400；超限、排队超时或处理超时均按 best-effort 非致命降级，不持久化部分结果。
|
||||
- 去背边界：不修改 BgFilter `flat` 参数、`cross_check`、fallback、Alpha 回贴和默认关闭 despill 的现有行为。BgFilter 最终失败时不运行像素规整；像素规整失败按 best-effort 非致命降级，保留进入该步骤前的图片并通过既有通用 `warning` 完成任务，不退款。
|
||||
- 持久化边界：逻辑低分辨率图、像素化前后对比图、预览、诊断和报告一律不持久化；像素模式只替换原本即将上传的最终图片字节。普通图片、角色、图标的 OSS PUT、asset / project resource 和画布 item 数量必须与 `None` 模式完全一致；角色 / 图标最多因复用失败增加一次对已有 provider 对象的 OSS GET，不得增加 PUT、资源类型、画布项、队列类型或 schema 字段。
|
||||
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/openapi/genarrative-external-v1.openapi.json`。
|
||||
|
||||
## 2026-07-28 画布 Agent 的通用 function-calling harness 与画布 prompt 分层
|
||||
|
||||
- 背景：画布 Agent 的 JSON 输出协议、tool schema 注入、memory / hook、轮次保护和“全部工具待确认即结束回合”原先位于 `platform-editor-agent/src/framework`，与规范展板、已有图编辑路由、模型超时和画布工具混在同一 crate；八类工具还重复携带待确认控制话术。旧 `platform-agent` 已随 Creative Agent 退役，不能作为新公共层复活。
|
||||
- 决策：新增无旧玩法依赖的现役 `platform-agent-harness`，只承载业务中立的 function-calling 执行协议；`platform-editor-agent` 通过兼容 re-export 复用该 crate，并继续承载画布 LLM profile、角色 prompt、公共美术工具路由策略、图片上下文和工具实现。无工具场景同样注入 JSON 响应格式；prompt 不再宣称工具并发执行；request 级 system prompt 必须真实进入本轮请求。待确认卡片的对话路由必须使用正向、条件化语义：只在当前意图匹配一条现存 pending 调用时引导用户点击该卡片，该确认 / 取消意图不产生新 tool call；不在 prompt 中写“不得重新发起相同工具调用”一类全局否定句，因为实测证明模型会将其过度泛化为拒绝后续明确的新生成、修改或重做请求。cancelled 调用不再确认，pending 调用不阻塞无关新任务。
|
||||
- 执行与失败决策：prompt 每轮通过 `AgentMemory::begin_staged` 使用与调用方 memory 行为等价、写入隔离的 `StagedAgentMemory` 事务；成功或已有工具活动时显式 `commit()`，直接 drop 表示回滚。无工具活动失败时回滚本轮 staged 增量，已发生工具活动后失败时提交已发生工具事实并追加 terminal error closure。外部 future drop / abort 若发生在工具完成后，提交工具结果与取消闭环；若发生在工具执行中，提交“已启动、结果未知”与取消闭环，后续先 reconcile，不能假装副作用未发生。harness 通过 `PromptRunError { error, partial_outputs }` 显式返回终态错误和失败前输出；结构化工具失败还必须向调用方保留 `ToolFailure.kind/retryable/fatal` 与原始 `output`，不在 harness 内压成单一字符串。api-server 的 18 分钟总 deadline 以 runtime future 下沉到 runner：completion 可被 deadline 终止，工具在开始前检查、开始后等待返回、返回后携带结果收口；禁止外层 timeout drop prompt 或中途取消 effectful tool 后伪造空 partial。
|
||||
- 保留边界：会话幂等、OSS 消息、120 秒前端软提示、20 分钟 transport、18 分钟 handler 总 deadline、1024 tokens、8 分钟 provider attempt、泥点计费、确认入队和 external job 懒回填均不进入公共 harness。SpacetimeDB schema、前端 wire DTO 和侧边栏 UI 不变。
|
||||
- 验证方式：`cargo test -p platform-agent-harness`、`cargo test -p platform-editor-agent`、`cargo test -p api-server editor_agent`、`cargo check -p api-server --locked`、DDD 边界检查、Rustfmt、编码检查和 `git diff --check`。
|
||||
|
||||
## 2026-07-29 图标图集拆分数量只由有效连通域决定
|
||||
|
||||
- 背景：图标素材生成前端曾把单个提示词按换行、逗号、顿号等分隔符解析成描述数组，后端再用数组长度作为期望切片数。这会把“各种敌人头像：骷髅 哥布林 强盗 龙 蝙蝠等”一类自然语言错误地解释为固定数量，并在图集中存在更多有效素材时截断结果。
|
||||
- 决策：画布前端不再从提示词解析素材数量，完整提示词作为 `iconDescriptions` 的唯一数组元素提交以兼容现有请求契约；后端仍允许其它调用方提交多条文本，但数组长度只参与 prompt 组装，绝不作为切片数量或切片命名依据。生成后的自动拆分与手动 `拆分图集` 复用同一套全连通域识别、视觉阅读顺序和 `素材 N` 命名，识别多少个有效素材就拆多少个；手动按钮与 `/api/editor/icon-spritesheets/slices` 路由继续保留。
|
||||
- 失败与限制：两条图标拆分路径共同限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，并在持久化前完成校验。自动拆分仍是 best-effort，失败后保留整张透明图集并返回 `sliceWarning`；手动拆分失败返回接口错误。UI 设计图素材提取继续使用全连通域识别，不受提示词数量影响。
|
||||
- 验证方式：调整既有前端提交、Prompt、连通域切片、上限和响应契约测试，不新增仅用于证明旧解析函数已删除的测试；运行前后端定向测试、类型与 Rust 检查、编码检查和 `git diff --check`。
|
||||
- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/openapi/genarrative-external-v1.openapi.json`。
|
||||
|
||||
## 2026-07-27 Anthropic 与流式统一使用 Provider 原生工具
|
||||
|
||||
- 背景：`platform-llm` 的 Anthropic 分支从未实现工具——请求体没有 `tools` / `tool_choice` 字段，`validate()` 还会以「Anthropic api_kind 暂不支持 function tools」本地拒绝，响应解析只取 `text` block 并硬编码 `tool_calls: Vec::new()`。App 侧因此在 `provider_request_builders.rs` 与 `interaction.rs` 用 `api_kind != Anthropic` 绕开原生工具，改用长提示词描述工具并要求模型输出单个 JSON object，等于让 Anthropic 退回 V1.26 之前的状态。三种协议的流式路径同样恒返回空工具调用，靠「无文本 → EmptyResponse → 非流式重打」兜底；模型若在工具调用前先输出解说文本，该兜底不触发，工具调用会被静默丢弃并把解说当成最终回复。
|
||||
|
||||
@@ -490,6 +490,7 @@ npm run check:native-shells
|
||||
```
|
||||
|
||||
该命令会覆盖 H5 HostBridge 关键测试、微信 / Expo / Tauri 三端桥接层文件结构门禁、完整相对路径文档反查、微信 capability 到真实 WebView / 支付 / 分享页面流程和测试清单的映射门禁、H5 HostBridge 事件订阅双能力门控反查、H5 `navigation.canGoBack` 消费 hook 与直达二级页返回锚点测试、移动端和桌面端单端源码清单门禁、Expo 壳 typecheck / test / EAS build config smoke / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面壳 release `--no-bundle` 构建烟测，以及可分发壳与 H5 HostBridge 真实调用链的临时替身词扫描，确认 Expo managed config、移动端 EAS 原生包构建 profile、移动端 iOS / Android production bundle、打包 H5 资产、Tauri release 入口、H5 页面内导航保留完整原生宿主上下文和 H5 HostBridge 真实调用链没有漂移；扫描范围包含微信小程序壳生产 `.js`、Tauri `Info.plist`、共享 HostBridge 契约、H5 native transport，并自动覆盖已接入真实宿主能力 facade 的 H5 生产调用链文件，但不扫描 Expo export、Tauri `target/`、Cargo / Metro 缓存或 release 构建产物。移动壳配置检查必须反查 EAS 生产 profile、文本 / 文档 / 图片 / 音频导入边界都来自共享 HostBridge 契约。登录与支付外链跳转必须保持在该调用链扫描内，`src/services/authService.ts` 和 `src/services/payment/paymentRedirect.ts` 是必扫文件；`AuthGate` 的登录成功、退出登录、身份边界刷新和登录状态异常重试都必须通过 `app.reloadWebView` 优先路径，并由 `src/components/auth/AuthGate.test.tsx` 进入该门禁。壳源码和配置继续严格禁止 mock / fake / placeholder / stub / TODO / FIXME / 占位 / 模拟 / 伪造 / 未实现 / 临时；H5 业务调用链允许正常表单 `placeholder` 属性、业务占位图文案和真实兼容 / 故障语义中的“未实现”“临时”表述，但仍禁止 mock / fake / stub / TODO / FIXME / 模拟 / 伪造等替身痕迹。
|
||||
根仓 Vitest 加载独立 AI 游戏客户端源码时，不得为了模块解析把 `@tauri-apps/api` 或 `@tauri-apps/plugin-*` 加入根 H5 依赖；根测试只通过 `vitest.config.ts` 的精确别名使用无副作用测试替身，独立客户端的正式 Tauri guest 依赖继续只由 `apps/ai-game-creator-shell/package.json` 与其 lock 管理。隔离 worktree 验收前需分别执行根 `npm ci` 和 `npm ci --prefix apps/ai-game-creator-shell`。
|
||||
反馈页上传凭证在原生壳声明 `file.importImage` 时必须优先走宿主图片导入；移动壳声明 `file.captureImage` 时才显示拍摄凭证入口，并把拍摄图片同样转为 `File` 后复用反馈页原有数量、大小、MIME、data URL 预览和提交 payload 校验。
|
||||
Expo / Tauri 声明 `navigation.openNativePage` 时，只用于现役同源 H5 路由的受控导航和宿主上下文续接；微信小程序不再声明该能力。旧儿童动作 Demo、模板工作台、生成页、结果页和运行态不得作为 HostBridge 导航验收入口。
|
||||
H5 支付链接跳转在原生壳声明 `app.openExternalUrl` 时必须优先走宿主系统浏览器；原生壳未接真实支付 SDK 前不得声明 `payment.request`，也不得把外部 H5 支付跳转伪装成原生支付成功。
|
||||
|
||||
@@ -14,6 +14,38 @@
|
||||
- 关联：相关文件、文档、提交或 Issue
|
||||
```
|
||||
|
||||
## Jenkins 异步备份不能用 nohup 脱离作业
|
||||
|
||||
- 现象：Stdb Publish 成功，上传日志只留下“已获取进程锁 / 上传已有备份 / 目标对象”，没有成功或可捕获错误；本地 tar.gz 和 `uploadStatus=deferred` manifest 每次发布后继续增长。
|
||||
- 原因：`nohup` 只忽略终端 HUP，不会移除 Jenkins/Hudson 进程 Cookie；Job 收尾可清理后台 uploader。原链路只上传当次归档，旧 deferred manifest 没有扫描重试，而 `files-history` timer 只处理 `/stdb` 历史文件。
|
||||
- 处理：发布退出时用独立 `systemd-run --collect --service-type=exec` transient unit 执行 `--upload-deferred-dir`，串行处理同库 deferred/pending 归档。启动前拒绝符号链接和非绝对路径；unit 启动失败必须保留 status、archive 和 manifest。补偿扫描不删除上传未验真的文件，也不扫描目录外路径。
|
||||
- 验证：门禁必须禁止 `nohup`，要求命名 transient unit、`--collect`、`Type=exec` 与失败后保留 status；备份测试覆盖稳定顺序、同库过滤、已上传但未清理的归档收敛、归档缺失报告与路径逃逸拒绝。现场最终核对 backup lock、manifest、transient unit/result、根盘、SpacetimeDB/API/worker/controller/Nginx 和公开端点。
|
||||
- 关联：`scripts/deploy/production-stdb-publish.sh`、`scripts/database-backup-to-oss.mjs`、`scripts/check-production-ops-guardrails.mjs`、`scripts/check-database-backup-to-oss.mjs`。
|
||||
|
||||
## 图集切片上限必须早于合并、裁剪和编码
|
||||
|
||||
- 现象：透明图集含大量独立碎块或噪点时，接口长时间占用 async worker；最终即使报“超过 64 个切片”，此前仍已完成全量两两合并、裁剪和 PNG 编码。
|
||||
- 原因：原始连通域无上限，辅助部件合并全量扫描所有 pair，输出限制只在 platform slicer 返回后由 api-server 检查；UI 提取还绕过了该 wrapper。
|
||||
- 处理：platform slicer 对全部 flood-fill 连通域设置 `4096` 硬上限，用空间网格只查 `48px` 邻域候选；单网格最多 `256` 个组件、单 source 最多 `512` 个候选，避免拥挤网格重新退化为全量 pair。`maxOutputSlices` 与 padding crop 总像素预算在首片 PNG 编码前拒绝。图标自动、手动和 UI 三入口统一在 2 路 CPU semaphore 与 30 秒 / 请求 deadline 保护下 prepare 出共享 RGBA + bounds 计划，不再一次返回最多 64 份 PNG。api-server 只按需编码并用容量 2 的有界管线上传，OSS 连接 / 单请求超时固定为 `10s / 60s`；手动入口在下载最大 32 MiB 来源对象前取得独立内存 admission，同一 admission 覆盖下载、计划与上传生命周期，并在最后一次 HEAD 完成后、数据库调用前释放，排队请求、慢 OSS 或慢数据库都不能绕过内存边界。全部 `PUT + HEAD` 成功后，单个 SpacetimeDB procedure 在一个事务中批量确认对象、创建项目资源 / 账号素材并完成 cohort；resource / asset ID 按 owner + task + 序号稳定派生，重放只复用内容一致的素材，来源资源必须存在且同 owner / project；不在上传失败后留下部分数据库批次，也不在不确定结果重放后复制整批素材。
|
||||
- 验证：覆盖大量独立 `4×4` 块、超过上限的单像素噪点、65 个有效输出和既有高光 / 阴影合并样本；手动超限必须发生在首次持久化前，自动超限不得产生切片 PUT、资源或画布切片。
|
||||
- 关联：`server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs`、`server-rs/crates/api-server/src/editor_project.rs`。
|
||||
|
||||
## Alpha 恢复失败后不能继续持久化原始后处理图
|
||||
|
||||
- 现象：BgFilter 返回比例漂移、损坏或低分辨率图片，provider 原图修复性回读又失败时，图标 / UI 仍可能落库透明图与切片，尺寸元数据甚至回退为 `512×512`。
|
||||
- 原因：Alpha helper 会同时返回原后处理字节和错误；角色调用方会 source-only 早退，图标 / UI 却只写日志后继续。相同尺寸快路径还只读图片 header，没有完整解码。
|
||||
- 处理：角色、图标、UI 共用 provider 原图 source-only helper；比例漂移超过 `5%`、原图回读、Alpha 回贴或透明图完整解码任一失败都立即返回原图、通用 warning、空切片和空 `sliceWarning`，禁止透明图 PUT、派生资源、拆分和透明 / 切片画布层。provider 原图尺寸必须完整解码取得，不得伪造兜底值。
|
||||
- 验证：覆盖错比例 Alpha、缺失 provider 原图、合法 PNG header 但截断正文；结构断言 source-only helper 不含任何透明持久化、切片或多图层完成调用。
|
||||
- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
|
||||
|
||||
## 工具 JSON Schema 的条件约束必须覆盖运行时默认值
|
||||
|
||||
- 现象：LLM 按工具 schema 生成的参数可以通过结构约束，但参数补默认值后被运行时校验拒绝，白白消耗一次工具修复轮次。例如固定 `gpt-image-2` 的 UI 工具仍暴露 `0.5K`，或视频调用省略 `model` 时 schema 允许 `1080p`，运行时却默认成 `seedance2.0-fast` 后拒绝。
|
||||
- 原因：通用枚举 schema 被固定模型工具直接复用；JSON Schema 的 `if` 又用 `required: ["model"]` 排除了字段缺失场景，而 Serde 默认值只在 schema 校验之后生效。description 只能提示 LLM，不能替代 `enum` / `if` / `then` 的结构约束。
|
||||
- 处理：固定模型工具使用与该模型能力一致的专用枚举；可切换模型的图片工具在对象层复用共享 `model + image_size` 条件约束。条件字段有运行时默认值时，省略字段必须落入默认模型对应的 schema 分支：默认 nanobanana2 的图片工具只在显式选择 `gpt-image-2` 时收紧尺寸，所以条件保留 `required: ["model"]`；默认 fast 的视频工具则利用字段缺失时 `properties.model.const` 条件成立的语义，不额外要求 `model` 存在。运行时校验仍保留为最终防线。
|
||||
- 验证：锁定 `generate-ui-design.image_size = ["1K", "2K"]`，三个可切换图片模型的工具都接入共享 `gpt-image-2 -> image_size = ["1K", "2K"]` 条件，以及视频 fast 条件没有内层 `required`、其 `then.resolution = ["480p", "720p"]`；同时保留运行时拒绝 `gpt-image-2 + 0.5K` 与 `seedance2.0-fast + 1080p` 的测试。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/agent/tools/image_generation_options.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/generate_ui_design.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/generate_video.rs`、`docs/【编辑器】画布Agent对话面板-2026-07-03.md`。
|
||||
|
||||
## 重复成功的 agent.message 不能被当成新的 Runtime 进展
|
||||
|
||||
- 现象：专业 Agent 已把一条定向消息写入目标 Session，却在后续 planning 中反复发送相同正文；目标会话看起来没有重复消息，但 Provider 请求持续增长，run 可能长期不返回自身终态回执。
|
||||
@@ -413,7 +445,7 @@
|
||||
|
||||
- 现象：`/api/editor/projects*`、素材库、项目资源或 layout payload 里出现数 MB 的 `data:image/*`、`data:video/*`、`data:audio/*`，刷新恢复变慢，发布入口可能 OOM / 413，素材库缩略图还可能只显示文件名。
|
||||
- 原因：生成、规范图、角色图、图标 / UI spritesheet、音视频或动画帧如果直接把 Data URL / signed URL 写入 `editor_project_resource`、`editor_asset` 或 `editor_canvas.layers_json`，就把媒体本体塞进了项目快照；signed URL 还会过期，素材库也无法稳定换签。
|
||||
- 处理：登录态媒体必须先上传 OSS / asset object，持久化只写 `imageSrc: "/<objectKey>"`、`objectKey`、`assetObjectId`；素材库和图层缩略图都通过 `PlatformMediaFrame -> ResolvedAssetImage` 传 `objectKey` 并调用 `/api/assets/read-url`。layout 序列化和后端保存要递归拒绝 `data:*` / `blob:`；旧行有 `objectKey` 时读出归一成 `/<objectKey>`，没有 `objectKey` 的旧 Data URL 必须走修复上传后回写轻量引用。刷新恢复可先用 session 轻量缓存显示，但缓存不得含内联媒体，也不能在后端快照回来前自动保存。生成扣费、失败退款或 queue 终态后，右上角泥点余额通过 `/profile/dashboard` 回读，不做本地乐观扣减。
|
||||
- 处理：登录态媒体必须先上传 OSS / asset object，持久化只写 `imageSrc: "/<objectKey>"`、`objectKey`、`assetObjectId`；素材库和图层缩略图都通过 `PlatformMediaFrame -> ResolvedAssetImage` 传 `objectKey` 并调用 `/api/assets/read-url`。layout 序列化和后端保存要递归拒绝 `data:*` / `blob:`；旧行有 `objectKey` 时读出归一成 `/<objectKey>`，没有 `objectKey` 的旧 Data URL 必须走修复上传后回写轻量引用。刷新恢复可先用 session 轻量缓存显示，但缓存不得含内联媒体，必须按用户隔离，而且不能在后端快照回来前自动保存。认证状态变化重跑加载 effect 时，要同步用 ref 关闭写门禁并清除 revision、pending save 和 timer；不能只等 `isProjectReady=false` 的下一次 render，否则旧 effect 会先消费 skip 标记，再把公司浏览器的旧缓存无版本 PATCH 到服务端，覆盖另一台设备的新画布布局。现役 Web 与 External layout PATCH 的 `expectedRevision` 都必填，三层门禁分别放在 autosave effect、queue 和真正发送前；session cache 即使带 revision 也只有显示权。异步 project resource 创建必须把未发请求队列按用户 / 项目隔离，并记录发起时已接受的权威快照序号；若资源响应前发生认证重载、409 恢复或生成完成快照替换，只把新资源对应图层合并进当前权威布局，禁止用历史 `snapshotLayers` 整体覆盖。生成扣费、失败退款或 queue 终态后，右上角泥点余额通过 `/profile/dashboard` 回读，不做本地乐观扣减。
|
||||
- 验证：Network 中 `/api/editor/projects*`、`PATCH /api/editor/projects/{id}`、素材库接口不应出现 `data:image` / `data:video` / `data:audio`；素材库和图层面板缩略图都能换签显示；`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/ImageCanvasAssetRowView.test.tsx src/components/common/PlatformMediaFrame.test.tsx src/services/assetReadUrlService.test.ts src/services/image-editor/editorProjectClient.test.ts`，后端跑 `cargo test -p api-server editor_project --manifest-path server-rs/Cargo.toml`。
|
||||
- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`src/components/common/PlatformMediaFrame.tsx`、`src/services/assetReadUrlService.ts`。
|
||||
|
||||
@@ -430,7 +462,9 @@
|
||||
- 现象：画布项目已反复打开、保存或操作，但 `/project` 列表卡片仍只显示“项目”占位，没有封面图。
|
||||
- 原因：项目封面快照需要先在浏览器生成 Blob，再上传 OSS 并创建 `assetKind: "project-cover-snapshot"` 项目资源；本地 dev 或 OSS CORS 异常时，Blob 生成成功但上传失败，服务端不会产生正式封面资源。
|
||||
- 处理：服务端 `project-cover-snapshot` 仍是跨设备正式封面；前端在生成封面 Blob 后立即把 Blob 以项目 ID 写入 IndexedDB，仅作为当前浏览器展示兜底。项目列表读取时优先使用服务端封面资源，其次使用本地 IndexedDB 封面，最后才退回可见画布图层或占位。IndexedDB 兜底不得写入项目快照、不得进入 `editor_project_resource`，也不得替代 OSS / asset object 正式持久化。
|
||||
- 验证：`npm run test -- src/components/project/ProjectCanvasCover.test.ts src/components/project/ProjectGalleryView.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx` 覆盖服务端封面优先、本地缓存兜底、上传失败仍保留本地封面缓存；浏览器 smoke 可在 `/project` 对没有服务端封面的项目写入 `genarrative-editor-project-covers` IndexedDB 记录，刷新后应显示 `blob:` 封面图。
|
||||
- 封面是展示派生物，不是 layout 真相。常规编辑只在项目加载和原有 layout 保存触发点采样当前 `canvasSize`，不监听 ResizeObserver 尺寸变化单独增加保存频率；但用户主动返回项目页时必须先 flush 最新权威 layout，并等待同一视口封面写入 IndexedDB 和正式项目资源后再导航。为避免移动端、窄窗口或首次尺寸尚未稳定时取景过小，以当前视口中心为锚点把取景宽高至少扩大到 `1280x960`；实际值更大时保留更大值。画布存在 drawable 图层但当前取景全部离屏时，要保存纯背景封面，不能因相交列表为空而保留旧缩略图。
|
||||
- 封面生成不要为同一 OSS 对象发起另一套换签缓存维度：图片、序列帧和 poster 分别复用主画布预览的 refresh key，保证封面取得相同 signed URL，由浏览器合并 in-flight 请求或命中 HTTP 缓存。通用素材上传里的 `bypassCache: true` 只用于上传后立即预览；项目封面不消费该 `src`，应在 confirm 后直接使用 object-only 结果创建项目资源。
|
||||
- 验证：`npm run test -- src/components/project/ProjectCanvasCover.test.ts src/components/project/ProjectGalleryView.test.tsx src/components/image-editor/ImageCanvasProjectCoverSnapshotModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx` 覆盖服务端封面优先、本地缓存兜底、上传失败仍保留本地封面缓存、小视口居中扩大到 `1280x960`以及大视口不缩小；浏览器 smoke 可在 `/project` 对没有服务端封面的项目写入 `genarrative-editor-project-covers` IndexedDB 记录，刷新后应显示 `blob:` 封面图。
|
||||
- 关联：`src/services/image-editor/editorProjectCoverCache.ts`、`src/components/project/ProjectGalleryView.tsx`、`src/components/project/ProjectCanvasCover.tsx`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`。
|
||||
|
||||
## 图片画布框选预览要复用源图换签缓存
|
||||
@@ -3776,8 +3810,25 @@
|
||||
- 现象：画布 Agent 已生成有效工具规划，却最终只保存 `ERROR max turns reached: 3`，助手文本和待确认工具卡都消失。
|
||||
- 原因：八类画布工具的 `call()` 只返回待用户确认的规划结果，但 function-calling runner 在成功工具后仍继续请求 LLM，只靠 prompt 要求模型不再重试；模型连续返回工具调用直到上限后，错误结果又丢弃此前累积的输出。
|
||||
- 处理：工具通过框架契约显式声明 `requires_user_confirmation`；当本批全部工具都成功且等待确认时，runner 在处理完整批次后立即返回已有助手文本和工具结果。未知工具、参数错误、hook skip、普通连续工具和不可解析响应仍继续受 `max_turns` 门禁保护。不要用单纯提高轮次上限掩盖终止条件缺失。
|
||||
- 验证：runner 回归测试必须同时覆盖“待确认工具只调用一次 LLM 并成功结束”和“普通连续工具仍会触发 max-turn 门禁”。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/framework/run.rs`、`server-rs/crates/platform-editor-agent/src/framework/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/`。
|
||||
- 验证：runner 回归测试必须同时覆盖“待确认工具只调用一次 LLM 并成功结束”“普通连续工具仍会触发 max-turn 门禁”“多工具按数组顺序执行”“request 级 system prompt 真实进入请求”；公共 prompt 在无工具时仍必须包含 runner 所需的 JSON 响应格式，且不得宣称并发执行。
|
||||
- 关联：`server-rs/crates/platform-agent-harness/src/run.rs`、`server-rs/crates/platform-agent-harness/src/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/`。
|
||||
|
||||
## 待确认工具的 prompt 不能使用全局禁止重发话术
|
||||
|
||||
- 现象：为防止用户在对话中说“确认 / 可以 / 取消”时重复生成待确认卡片，prompt 加入“不得重新发起相同工具调用”后，模型在用户随后明确提出新生成、修改或重做请求时也拒绝调用工具。
|
||||
- 原因：LLM 容易把面向“当前确认 / 取消意图 + 特定 pending 卡片”的限制过度泛化为跨回合、跨意图的全局禁止；单看工具名或参数相似度不能区分“重复确认旧卡片”和“用户明确发起新任务”。
|
||||
- 处理：prompt 只用正向条件句描述当前回合：确认或取消意图确实匹配某条现存 pending 卡片时，引导用户点击该卡片按钮，本条意图不生成新 tool call。不添加全局的“禁止重发相同工具”规则。cancelled 卡片不再处理；用户要求修改、重做或新任务时正常发起新调用，pending 卡片不阻塞无关请求。
|
||||
- 验证：业务 prompt 契约测试要同时锁定“匹配 pending 时引导确认 / 取消按钮”“cancelled 后可发起新调用”和“pending 不阻塞无关新请求”；模型实测必须另外覆盖同工具名的后续新任务，确认不会因过度泛化而拒绝。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/agent/prompt.rs`、`docs/【编辑器】画布Agent对话面板-2026-07-03.md`。
|
||||
|
||||
## Agent 终态失败不能吞掉已发生的工具事实
|
||||
|
||||
- 现象：同一轮 prompt 中前面工具已经成功生成待确认结果，但后续工具、hook、completion 或 `max_turns` 失败后，API 只保存最后一条 `ERROR `，已执行工具和用户本轮语义从会话历史中消失。
|
||||
- 原因：runner 只返回单一 `PromptError`，或者直接向 committed memory 逐步写入，无法区分“尚未发生外部工具事实，整轮可回滚”与“已发生工具事实，只能提交并闭合错误”。工具失败若被压成字符串，调用方还会丢失 `kind`、`retryable`、`fatal` 和原始 `output`。
|
||||
- 处理：用 `PromptRunError { error, partial_outputs }` 保留失败前输出，并将本轮 memory 先写入 staged buffer。无工具活动失败时整体回滚 staged 增量；有成功或失败工具活动时提交已发生事实，并追加 terminal error closure。api-server 按 `partial_outputs` 顺序先持久化成功工具的 `not_completed` 待确认消息，再追加 `ERROR ` 终态消息；`ToolFailed` 保留给调用方做诊断和流程决策，不伪装成成功确认卡。
|
||||
- 取消边界：不能在 prompt future 内对 `agent.memory.take()` 后跨 await 持有，也不能用统一 `VecMemory` staging 绕过自定义 memory 的限长、摘要或脱敏规则。`AgentMemory::begin_staged` 必须产生行为等价、写入隔离的 `StagedAgentMemory`，成功或已有工具活动时显式 `commit()`，直接 drop 才表示回滚。外部 drop 若发生在工具完成后，guard 必须提交结果与取消闭环；若工具仍在执行，至少提交“已启动、结果未知”事实，供后续 reconcile。正式总 deadline 应作为 runner 内部 future 终止 completion；工具开始前检查 deadline，一旦开始则不能中途 drop，必须等待结果后再携带 partial outputs 收口。外层 timeout 只适合作为进程级最后保险，不能承担业务收口。
|
||||
- 验证：至少覆盖“无工具 completion 失败回滚 staged 用户消息”“非 fatal 工具失败对调用方暴露 `kind/retryable/fatal/output`”“成功工具后终态失败保留 partial tool output”“有工具活动时 committed memory 末尾存在 error closure”以及“API 增量中待确认工具位于 terminal `ERROR ` 之前”。
|
||||
- 关联：`server-rs/crates/platform-agent-harness/src/run.rs`、`server-rs/crates/platform-agent-harness/src/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/prompt.rs`、`server-rs/crates/api-server/src/editor_agent/api.rs`。
|
||||
|
||||
## 画布 Agent 的规划请求不能关闭瞬时失败重试
|
||||
|
||||
@@ -3785,7 +3836,7 @@
|
||||
- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `editor_agent_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
|
||||
- 处理：120 秒改为前端软提示阈值：POST 仍 pending 时显示不入库的“仍在处理中，请耐心等待”；provider 明确断开/失败才写正式错误。专用 provider 单 attempt 使用 8 分钟 hard timeout，请求发起阶段读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次且重试退避最多 60 秒。不要只计算单次 complete 的最坏时间：runner 还可因非法 JSON/工具校验失败进入后续轮次，必须从 handler 入口开始计算 18 分钟总 deadline，进入 `agent.prompt(...)` 时扣除会话锁/上下文准备已用时间，为持久化和前端 20 分钟 timeout 留出余量。响应头后的体读取/解析错误按明确失败收口，必须使用真实 attempt 计数；规划、配置和定价错误对用户统一为中文，原始诊断只记后端日志。重试发生在任何生成工具执行前，不会重复提交生成任务或扣费，不要通过提高前端 timeout 或 runner `max_turns` 掩盖 provider 重试缺失。
|
||||
- 验证：`platform-editor-agent` 测试锁定 8 分钟 hard timeout 与中文错误；前端 fake timer 用例锁定 120 秒前只显示思考动画、到点后显示耐心等待、成功/失败后移除；`platform-llm` 回归用例锁定第二次 attempt 成功响应头后的 body timeout 仍报累计 2 次；`api-server` 测试锁定专用 client retry、18 分钟整体 deadline 与中文直达错误。运行态排障按同一 request id 对齐 `platform_llm` failure stage 与 `/messages` 总耗时，并确认仍 pending 的请求不再在 120 秒形成错误气泡。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-editor-agent/src/framework/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-agent-harness/src/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。
|
||||
|
||||
## 前端退役目录不能只靠扫描和 ignore 隔离
|
||||
|
||||
@@ -3858,6 +3909,13 @@
|
||||
- 处理：灰度页只能以 `/admin/api/feature-gates` 为数据源，固定目标列表只登记现役功能；新增或退役业务 target 只修改固定目标注册，不得让通用页面依赖业务列表接口。旧 `creation-entry:*` 目标、接口和页面保持退役。
|
||||
- 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。
|
||||
- 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
|
||||
## 历史钱包消费不能从最近流水或通用订单快照推算
|
||||
|
||||
- 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。
|
||||
- 原因：最近流水会低估历史总额；通用钱包快照又会被订单列表反复构造，把一次按用户聚合放大为 `订单数 × 流水数` 的重复扫描。
|
||||
- 处理：历史花费只累计 `asset_operation_consume` 负向流水绝对值，退款不冲减；通过 `profile_wallet_consumption_total` 在已有投影时按主键 O(1) 累加。首次上线必须在停写维护窗口由 owner 执行全量初始化，为每个已有钱包流水的用户建立投影，不能让所有存量用户的首次正常消费各自扫描历史；维护遗漏或新用户缺行时才在首次消费或详情读取中按用户索引兜底重建一次。手动对账扫描是独立高风险操作，member 必须单独持有 `profile-wallet-consumption-reconcile`，不能因为能打开共享用户详情就自动获得。
|
||||
- 验证：构造消费、退款、充值退款追回和赠送混合流水，断言只累计消费；维护初始化后正常消费只按主键累加；重复详情读取不得重复扫描或重复累计；任意 Tab 权限不能调用手动对账，同时确认充值订单列表的通用钱包快照没有新增历史流水扫描。
|
||||
|
||||
## AI 游戏 game-chat 自动预览不能在调用前消费授权（2026-07-29）
|
||||
|
||||
- 症状：`code-prototype` 首次完成后 `.agent/logs/command.log` 已出现 `permission.confirm preview.start`，但客户端没有 iframe，`.agent/logs/preview.log` 也没有新的 running 记录；后续即使父 run 完成也不再启动。
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -1,12 +1,12 @@
|
||||
# 后台管理多账号与 Tab 访问权限方案
|
||||
|
||||
更新时间：`2026-07-23`
|
||||
更新时间：`2026-07-24`
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
本文定义陶泥儿后台从单一环境变量管理员扩展为“1 个 owner 引导账号 + 多个 member 持久账号”的编码契约，并为每个一级 Tab 建立前后端一致的访问权限。
|
||||
|
||||
本次只增加后台管理员账号与整页访问权限，不引入页面内按钮级、字段级或只读权限。正式实现必须同时完成前端导航过滤和后端 API 鉴权；前端过滤只改善体验，不能作为安全边界。
|
||||
后台权限默认仍以整页 Tab 为粒度；只有会触发权威钱包全量扫描的“手动对账用户历史花费”作为明确例外，使用独立操作权限，不随任何 Tab 自动授予。正式实现必须同时完成前端按钮过滤和后端 API 鉴权；前端过滤只改善体验，不能作为安全边界。
|
||||
|
||||
## 2. 当前基线与目标
|
||||
|
||||
@@ -17,8 +17,8 @@
|
||||
1. 现有环境变量账号升级为 `owner`，仍由部署环境提供，不迁移、不复制到 SpacetimeDB。
|
||||
2. owner 始终拥有全部 15 个业务 Tab 权限，并独占“账号管理”Tab 和账号管理 API。
|
||||
3. owner 可以创建、修改、启停 member；member 保存在 SpacetimeDB 私有表 `admin_account`。
|
||||
4. member 按一级 Tab 分配权限；获得一个 Tab 权限即获得该页面内全部读写能力，页面内部二级 Tab、弹窗和操作区继承一级权限。
|
||||
5. member JWT 每次请求都重新读取当前账号并校验 `enabled`、`token_version` 和实时权限，权限、密码或启停变更应立即让旧 JWT 失效。
|
||||
4. member 按一级 Tab 分配常规权限；获得一个 Tab 权限即获得该页面内常规读写能力。历史花费手动对账必须另行授予 `profile-wallet-consumption-reconcile`，任何 Tab 都不隐式包含。
|
||||
5. member JWT 每次请求都重新读取当前账号并校验 `enabled`、`token_version`、实时 Tab 权限和独立操作权限，权限、密码或启停变更应立即让旧 JWT 失效。
|
||||
|
||||
## 3. 角色与不可变规则
|
||||
|
||||
@@ -26,18 +26,18 @@
|
||||
|
||||
- owner 用户名和密码继续读取 `GENARRATIVE_ADMIN_USERNAME`、`GENARRATIVE_ADMIN_PASSWORD`。
|
||||
- owner 是环境变量构造的虚拟账号，不写入 `admin_account`，不允许通过后台改名、改密、禁用或删除。
|
||||
- owner 始终拥有本文列出的全部 15 个可分配权限，不能在前端取消，也不从数据库加载权限。
|
||||
- “账号管理”是 owner-only 能力。它可以作为新增一级路由 `accounts` / `#accounts` 展示，但 `accounts` 不进入 `ADMIN_TAB_PERMISSIONS`，不能写入 member 的 `permissions_json`。
|
||||
- owner 始终拥有本文列出的全部 15 个 Tab 权限和全部独立操作权限，不能在前端取消，也不从数据库加载权限。
|
||||
- “账号管理”是 owner-only 能力。它可以作为新增一级路由 `accounts` / `#accounts` 展示，但 `accounts` 不进入 `ADMIN_TAB_PERMISSIONS` 或 `ADMIN_ACTION_PERMISSIONS`，不能写入 member 的权限 JSON。
|
||||
- owner 会话返回 `accountRole = "owner"`、`roles = ["admin", "owner"]`；账号管理权限必须根据服务端确认的 `accountRole` 判断，不能只相信前端角色字符串。
|
||||
- owner 配置缺失时，后台整体保持未启用状态；不能依赖数据库中的 member 绕过 owner 引导配置启动后台。
|
||||
|
||||
### 3.2 member
|
||||
|
||||
- member 只来自 `admin_account`，不新增第二套环境变量账号。
|
||||
- member 会话返回 `accountRole = "member"`、`roles = ["admin", "member"]` 和当前实时 `tabPermissions`。
|
||||
- member 会话返回 `accountRole = "member"`、`roles = ["admin", "member"]`、当前实时 `tabPermissions` 和 `actionPermissions`。
|
||||
- member 永远不能访问账号管理页面或账号管理 API，也不能给自己或他人分配 `accounts`。
|
||||
- member 的一个一级 Tab 权限覆盖该页面的查询、创建、修改、启停、退款等全部现有操作，不拆成 `read` / `write`。
|
||||
- 页面内二级 Tab、筛选视图、抽屉、弹窗和共享详情弹窗继承触发它的一级 Tab 权限，不另设 permission id。
|
||||
- member 的一个一级 Tab 权限覆盖该页面的常规查询、创建、修改、启停、退款等操作，不拆成通用 `read` / `write`。
|
||||
- 页面内二级 Tab、筛选视图、抽屉、弹窗和共享详情弹窗默认继承触发它的一级 Tab 权限；历史花费手动对账是唯一独立高风险操作例外，无权限时共享用户详情不展示按钮，直接请求仍由后端返回 403。
|
||||
|
||||
## 4. 权限标识
|
||||
|
||||
@@ -61,9 +61,15 @@
|
||||
| `editor-showcase` | 精选审核 | `#editor-showcase` |
|
||||
| `editor-assets` | 素材查询 | `#editor-assets` |
|
||||
|
||||
权限数组必须去重并按上表顺序规范化后保存。保存时拒绝未知值和 `accounts`；读取旧数据时遇到未知值应忽略并记录告警，绝不能将未知值解释为全权限。空数组合法，表示 member 可以登录但没有业务页面权限。
|
||||
Tab 权限数组必须去重并按上表顺序规范化后保存。保存时拒绝未知值和 `accounts`；读取旧数据时遇到未知值应忽略并记录告警，绝不能将未知值解释为全权限。空数组合法，表示 member 可以登录但没有业务页面权限。
|
||||
|
||||
后续新增一级 Tab 时，必须在同一次改动中更新：
|
||||
`ADMIN_ACTION_PERMISSIONS` 是独立操作权限闭合集合，当前只有：
|
||||
|
||||
| permission id | 操作 | 授权边界 |
|
||||
| --- | --- | --- |
|
||||
| `profile-wallet-consumption-reconcile` | 手动对账用户历史花费 | owner 默认拥有；member 必须在账号管理中单独勾选，不要求同时持有特定 Tab |
|
||||
|
||||
独立操作权限保存在 `action_permissions_json`，响应为 `actionPermissions`；未知值必须拒绝。后续新增一级 Tab 时，必须在同一次改动中更新：
|
||||
|
||||
- shared-contracts 的 `ADMIN_TAB_PERMISSIONS`。
|
||||
- admin-web 的路由定义、权限标签和第一可访问项顺序。
|
||||
@@ -80,13 +86,14 @@
|
||||
| `username` | `String` | `unique`；登录名，创建后不可修改；按 `trim + ASCII lowercase` 规范化 |
|
||||
| `display_name` | `String` | 展示名，去除首尾空白后 1 至 64 字符 |
|
||||
| `password_hash` | `String` | Argon2id PHC 字符串；只在内部登录查询中返回给 api-server，永不进入 HTTP DTO、日志或前端状态 |
|
||||
| `permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 15 个值，空数组为 `[]` |
|
||||
| `tab_permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 15 个值，空数组为 `[]` |
|
||||
| `enabled` | `bool` | 是否允许登录和继续使用现有 JWT |
|
||||
| `token_version` | `u64` | 初始为 `1`；权限、密码或启停状态发生有效变化时加 `1` |
|
||||
| `created_by` | `String` | 创建者后台 subject；当前只能是 owner subject |
|
||||
| `updated_by` | `String` | 最近更新者后台 subject；当前只能是 owner subject |
|
||||
| `created_at` | `Timestamp` | 创建时间，使用 `ctx.timestamp` |
|
||||
| `updated_at` | `Timestamp` | 最近更新时间，使用 `ctx.timestamp` |
|
||||
| `action_permissions_json` | `Option<String>` | 既有表末尾追加；旧行默认 `None` 并按 `[]` 读取，只允许第 4 节独立操作权限 |
|
||||
|
||||
账号规则：
|
||||
|
||||
@@ -94,7 +101,7 @@
|
||||
- owner 用户名属于保留名称。创建 member 时必须同时与当前规范化后的 owner 用户名比较并拒绝冲突，不能只依赖 `admin_account.username` 唯一索引。
|
||||
- 密码明文只存在于登录、创建和改密请求生命周期内；限制为 6 至 128 个字符，并复用 `platform-auth` 的 Argon2id 哈希与校验能力。Argon2id 必须在 blocking 任务中执行，api-server 通过有界信号量限制同时 hash / verify 数量，不得占用 Tokio worker 或无界堆积高成本任务。
|
||||
- 不提供物理删除 API。离职或停用通过 `enabled = false` 完成，以保留 `created_by`、`updated_by` 和账号标识。
|
||||
- `display_name` 单独变化只更新 `updated_by`、`updated_at`，不要求递增 `token_version`；权限、密码、`enabled` 任一有效变化必须在同一事务中递增版本。
|
||||
- `display_name` 单独变化只更新 `updated_by`、`updated_at`，不要求递增 `token_version`；Tab 权限、独立操作权限、密码、`enabled` 任一有效变化必须在同一事务中递增版本。
|
||||
- `u64` 版本到达上限时更新失败关闭，不能回绕。
|
||||
|
||||
## 6. SpacetimeDB 与 facade 边界
|
||||
@@ -158,9 +165,10 @@ owner 优先既保持原账号行为，也防止数据库同名记录遮蔽或
|
||||
```text
|
||||
accountRole: "owner" | "member"
|
||||
tabPermissions: string[]
|
||||
actionPermissions: string[]
|
||||
```
|
||||
|
||||
owner 返回全部 15 个 permission id；member 返回数据库中的实时规范化数组。`GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航。
|
||||
owner 返回全部 15 个 Tab permission id 和全部独立操作权限；member 返回数据库中的两组实时规范化数组。`GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航和操作按钮。
|
||||
|
||||
后台所有面向运营展示的管理员身份统一使用 `displayName`。审计表继续保存稳定 subject，例如 owner subject 或 `admin-account-<uuid>`；api-server 在返回兑换码、邀请码等操作记录时，按 owner 运行态和 `admin_account` 批量解析显示名称，同时兼容历史用户名记录。已无法解析的历史主体统一展示“已停用管理员”，前端不得直接渲染 `operatorUserId`、账号 ID 或登录用户名代替显示名称。对写接口，显示名目录必须在主事务前加载，或在主事务成功后降级为占位文案；不得因二次读取失败把已提交写入伪装成失败。
|
||||
|
||||
@@ -168,14 +176,15 @@ owner 返回全部 15 个 permission id；member 返回数据库中的实时规
|
||||
|
||||
在统一 `require_admin_auth` 之后增加可复用的权限守卫，支持：
|
||||
|
||||
- `require_admin_permission(permission)`：owner 自动通过；member 必须包含该 permission。
|
||||
- `require_any_admin_permission([permission...])`：owner 自动通过；member 至少包含一个，用于共享 API。
|
||||
- `require_admin_tab_permission(permission)`：owner 自动通过；member 必须包含该 Tab permission。
|
||||
- `require_any_admin_tab_permission([permission...])`：owner 自动通过；member 至少包含一个，用于共享读取 API。
|
||||
- `require_admin_action_permission(permission)`：owner 自动通过；member 必须包含该独立操作 permission。
|
||||
- `require_admin_owner`：只接受服务端确认的 owner。
|
||||
|
||||
返回语义统一如下：
|
||||
|
||||
- `401 Unauthorized`：token 缺失、无效、过期，member 不存在、被停用或 `token_version` 过期。
|
||||
- `403 Forbidden`：会话有效但缺少目标 Tab 权限，或 member 请求 owner-only API。
|
||||
- `403 Forbidden`：会话有效但缺少目标 Tab / 独立操作权限，或 member 请求 owner-only API。
|
||||
- 前端收到 `401` 清除本地 token 并回到登录页；收到 `403` 不应伪装成掉线，应刷新 `/me` 权限并跳转到第一可访问项或零权限空态。
|
||||
|
||||
## 9. API-to-Tab 权限矩阵
|
||||
@@ -223,6 +232,8 @@ owner 返回全部 15 个 permission id；member 返回数据库中的实时规
|
||||
| `POST` | `/admin/api/profile/recharge-refunds/register` | `recharge-orders` |
|
||||
| `POST` | `/admin/api/profile/recharge-refunds/manual-review/resolve` | `recharge-orders` |
|
||||
| `GET` | `/admin/api/profile/users/detail` | `tables OR tracking OR recharge-orders OR editor-showcase OR editor-assets` |
|
||||
| `POST` | `/admin/api/profile/users/reconcile-consumption` | 独立操作权限 `profile-wallet-consumption-reconcile` |
|
||||
| `POST` | `/admin/api/profile/users/initialize-consumption-projections` | owner-only 维护窗口操作 |
|
||||
| `POST` | `/admin/api/profile/wallet-restriction` | `recharge-orders` |
|
||||
| `GET` | `/admin/api/accounts` | owner-only |
|
||||
| `POST` | `/admin/api/accounts` | owner-only |
|
||||
@@ -249,6 +260,7 @@ accounts: Array<{
|
||||
username,
|
||||
displayName,
|
||||
tabPermissions,
|
||||
actionPermissions,
|
||||
enabled,
|
||||
tokenVersion,
|
||||
createdBy,
|
||||
@@ -270,6 +282,7 @@ accounts: Array<{
|
||||
displayName: string,
|
||||
password: string,
|
||||
tabPermissions: string[],
|
||||
actionPermissions: string[],
|
||||
enabled?: boolean
|
||||
}
|
||||
```
|
||||
@@ -285,11 +298,12 @@ accounts: Array<{
|
||||
displayName: string,
|
||||
password?: string,
|
||||
tabPermissions: string[],
|
||||
actionPermissions: string[],
|
||||
enabled: boolean
|
||||
}
|
||||
```
|
||||
|
||||
`username` 和 `account_id` 不可修改。更新请求完整提交显示名称、Tab 权限和启停状态；密码省略表示不修改，空字符串密码作为非法参数拒绝。api-server 只在提供新密码时生成新 hash。procedure 比较有效变化，在权限、密码或启停任一变化时只递增一次 `token_version`，并在同一事务写入账号字段、`updated_by`、`updated_at`。响应仍不返回密码或 hash。
|
||||
`username` 和 `account_id` 不可修改。更新请求完整提交显示名称、Tab 权限、独立操作权限和启停状态；密码省略表示不修改，空字符串密码作为非法参数拒绝。api-server 只在提供新密码时生成新 hash。procedure 比较有效变化，在权限、密码或启停任一变化时只递增一次 `token_version`，并在同一事务写入账号字段、`updated_by`、`updated_at`。响应仍不返回密码或 hash。
|
||||
|
||||
## 11. admin-web 行为
|
||||
|
||||
@@ -313,7 +327,7 @@ accounts: Array<{
|
||||
|
||||
### 11.3 账号管理页
|
||||
|
||||
- 权限编辑器展示 15 个明确的 checkbox，每项使用现有 Tab 中文名称；不能展示或提交 `accounts`。
|
||||
- 权限编辑器分为 15 个 Tab checkbox 和独立操作权限区；当前独立区只显示“手动对账用户历史花费”。不能展示或提交 `accounts`。
|
||||
- 创建和编辑使用独立弹窗或抽屉，不在列表下方追加表单。
|
||||
- 编辑时密码字段默认空，空表示请求中省略 `password`；页面永不展示现有密码或 hash。
|
||||
- 停用使用开关并二次确认。保存成功后以 API 返回 account snapshot 更新列表。
|
||||
@@ -323,17 +337,17 @@ accounts: Array<{
|
||||
|
||||
建议按以下边界落地，避免在前端或 `api-server` 重新发明持久化规则：
|
||||
|
||||
- `shared-contracts`：`ADMIN_TAB_PERMISSIONS`、扩展后的 `AdminSessionPayload`、账号管理 request/response DTO。
|
||||
- `shared-contracts`：`ADMIN_TAB_PERMISSIONS`、`ADMIN_ACTION_PERMISSIONS`、扩展后的 `AdminSessionPayload`、账号管理 request/response DTO。
|
||||
- `spacetime-module`：私有表、输入类型、typed procedures、唯一性与版本递增事务。
|
||||
- `spacetime-client`：生成绑定、row mapper、登录查询与账号管理 facade。
|
||||
- `api-server`：owner/member 登录编排、Argon2id、逐请求账号解析、权限 middleware、账号管理 handlers。
|
||||
- `apps/admin-web`：权限感知路由、hash 回落、零权限空态、owner-only 账号管理页。
|
||||
|
||||
不能将 `permissions_json` 的解析与授权只放在前端；不能让 admin-web 直连 SpacetimeDB；不能用进程内 member 列表替代 `admin_account`。
|
||||
不能将 Tab / 独立操作权限 JSON 的解析与授权只放在前端；不能让 admin-web 直连 SpacetimeDB；不能用进程内 member 列表替代 `admin_account`。
|
||||
|
||||
## 13. 迁移、绑定与发布顺序
|
||||
|
||||
`admin_account` 是新增私有表，没有旧数据回填。原环境变量 owner 不入表，因此迁移不创建 owner 行。
|
||||
`admin_account` 已是私有表；本次只在表结构体最后追加带 `None` 默认值的 `action_permissions_json`，旧 member 自动按空独立权限读取。原环境变量 owner 不入表，并始终由 api-server 合成全部权限。
|
||||
|
||||
实现 schema 后必须：
|
||||
|
||||
@@ -380,16 +394,17 @@ spacetime publish <database> \
|
||||
- member 私表不能被普通 SpacetimeDB identity 查询或调用 procedure；只有 runtime service identity 可读写。
|
||||
- 创建重复规范化用户名、owner 保留用户名、未知权限或 `accounts` 权限均失败。
|
||||
- GET/POST/PUT 账号 API 任何响应和日志都不包含明文密码或 `password_hash`。
|
||||
- 权限、密码、启停更新各自会递增 `token_version`；同一次请求修改多项只递增一次；仅改展示名不递增。
|
||||
- Tab 权限、独立操作权限、密码、启停更新各自会递增 `token_version`；同一次请求修改多项只递增一次；仅改展示名不递增。
|
||||
- member 被停用、改密或改权限后，旧 JWT 下一次请求返回 401；重新登录后获得实时权限。
|
||||
- API-to-Tab 矩阵逐路由覆盖 `modules/admin.rs`，每条路由至少测试 owner 成功、具备权限的 member 成功、缺权限 member 返回 403。
|
||||
- 两个共享读取接口分别覆盖每个允许 permission 的成功用例，以及无关 permission 的 403 用例。
|
||||
- owner-only 账号 API 对任意 member 都返回 403，即使其 `permissions_json` 被污染为包含 `accounts`。
|
||||
- 历史花费手动对账对仅持有任意 Tab 的 member 返回 403；只持有独立操作权限时允许调用；全量投影初始化始终 owner-only。
|
||||
- owner-only 账号 API 对任意 member 都返回 403，即使其 Tab 或独立权限 JSON 被污染为包含 `accounts`。
|
||||
|
||||
### 14.2 前端
|
||||
|
||||
- owner 看到 15 个业务 Tab 和账号管理；member 只看到被分配的业务 Tab。
|
||||
- 每个一级 Tab 内的二级 Tab、弹窗和写操作继承一级权限并正常使用，不出现“页面可见但内部 API 403”的错误映射。
|
||||
- 常规二级 Tab、弹窗和写操作继承一级权限；历史花费对账按钮只在用户详情返回 `canReconcileConsumption=true` 时显示。
|
||||
- 直接输入无权限 hash 自动替换为第一可访问项，不短暂挂载无权限页面。
|
||||
- 当前 Tab 权限被 owner 收回后，下一请求触发重新登录；新会话恢复后落到第一可访问项。
|
||||
- 零权限 member 登录后显示空态，不回落 Dashboard、不发送 Dashboard 或其它业务请求，并可正常退出。
|
||||
|
||||
@@ -207,7 +207,7 @@ controller 配置：
|
||||
|
||||
透明背景处理正常成功时，角色形象、图标 spritesheet 和 UI 素材提取的画布都同时放透明主结果与 provider 原图：透明主结果保持生成器 `generatedLayerId` 主锚点，provider 原图作为第二个图层放在其右侧；图标和 UI 实际拆分出的业务素材从 provider 原图右侧继续排列。
|
||||
|
||||
inline 与 external v1 成功响应继续使用结构化 `warning.code/reason`；图标 / UI 的透明图已经成功、只有自动拆分失败时，继续返回结构化 `sliceWarning.code/reason`，其中 `sliceWarning.reason` 保留原始诊断。queue worker 把两类告警归一为有界的 `result_payload_json.warning`：通用 `warning` 优先并原样保留完整 `reason`；只有不存在通用 `warning` 时，才给 `sliceWarning.reason` 添加“图集已生成，但自动拆分未完成：”前缀。任务摘要将该展示就绪的 `reason` 原样提取到 `warning_message`，单 job 状态和刷新后的任务列表 BFF 再以 `warning: string` 返回；Web 必须直接展示，不再补前缀或按 code 推断类型。历史任务保留写入时的 `reason` 快照，摘要 backfill 不按当前格式重新解释或补写前缀。该字符串语义是 worker / BFF / Web 的内部同版本契约，三者必须协调发布，不承诺滚动混部或旧 Web 缓存下的跨版本字符串兼容。
|
||||
inline 与 external v1 成功响应继续使用结构化 `warning.code/reason`；图标 / UI 的透明图已经成功、只有自动拆分失败时，继续返回结构化 `sliceWarning.code/reason`，其中 `sliceWarning.reason` 保留原始诊断。queue worker 把两类告警归一为有界的 `result_payload_json.warning`：只有一条时原样保留完整 `reason`；两条并存时按“通用在前、拆分在后”拼接，`code` 收敛为 `multiple-generation-warnings`（两条 `code` 相同则沿用原 `code`），任何一条都不得被丢弃。`sliceWarning.reason` 无论是否与通用告警并存都由 worker 添加“图集已生成，但自动拆分未完成：”前缀，拼接结果最后统一做长度上界收敛。任务摘要将该展示就绪的 `reason` 原样提取到 `warning_message`，单 job 状态和刷新后的任务列表 BFF 再以 `warning: string` 返回；Web 必须直接展示，不再补前缀或按 code 推断类型。历史任务保留写入时的 `reason` 快照，摘要 backfill 不按当前格式重新解释或补写前缀。该字符串语义是 worker / BFF / Web 的内部同版本契约，三者必须协调发布，不承诺滚动混部或旧 Web 缓存下的跨版本字符串兼容。
|
||||
|
||||
## 验收
|
||||
|
||||
|
||||
@@ -59,7 +59,7 @@
|
||||
- SpacetimeDB schema guard 比较当前工作树与基线提交时，两侧都必须分别读取各自 `Cargo.toml` 的 `lib.path`，再沿 `mod` / `#[path]` 只扫描该快照 crate root 可达的 schema；不得递归扫描整个 `src/`，否则原位保留的旧源码会与现役历史数据壳产生假 accessor 重复。
|
||||
- `module-runtime` 仍是账号、钱包、公共设置、追踪和 feature gate 的现役领域 crate；其混合源码中的 `CreationEntry*`、旧公开作品、旧存档 / 浏览历史 / 游玩统计 DTO、command、mapper 和规则必须以编译条件退出，且不再依赖只为旧创作契约存在的 `shared-contracts`。历史 schema 只继续编译 `RuntimeBrowseHistoryThemeMode` 六个变体和完整保序的 `RuntimeProfileWalletLedgerSourceType` 等持久化 ABI，不保留围绕这些类型的旧业务实现。
|
||||
- 纯模板 crate 和专属运行态 crate 不属于 workspace members、default members 或任何在运 crate 的依赖图；源码目录保持原样。
|
||||
- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。
|
||||
- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。后续抽出的 `platform-agent-harness` 是无旧玩法依赖的通用 JSON function-calling 底座，不得依赖、复用或重新挂回本条退役 crate。
|
||||
- `platform-auth` 不再编译 runtime guest token；`platform-wechat` 不再编译旧生成结果订阅服务，只保留现役认证和支付协议。
|
||||
|
||||
## 验收
|
||||
|
||||
File diff suppressed because one or more lines are too long
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user