Skip to content

Commit 208fa1d

Browse files
argszeroargszero
andauthored
docs: revise newcomer gift to daily 1pt/1day for 10 days (v1.4) (#14)
Co-authored-by: argszero <argszero@argszerodeMac-mini.local>
1 parent 711242e commit 208fa1d

1 file changed

Lines changed: 16 additions & 14 deletions

File tree

‎docs/user-stories.md‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# AITokenPool — Product User Stories
22

3+
> **v1.4(2026-08-15)· Newcomer gift mechanism revised(防薅羊毛).** The old "register → 10 gift points valid 1 week" is **replaced** by a **daily gift program**: **1 point per day**(每日 1 点), each day's point **valid for 1 day**(当日有效,过期清零), granted for **10 consecutive natural days** from registration(注册起连续 10 个自然日); the user must **log in / come back each day** to claim that day's point — a missed day's point is **not issued / not accumulated**. Earned & top-up points remain **permanent**; deduction still consumes **expiring (gift) points first**. Anti-abuse: daily 1 pt with 1-day validity makes mass multi-account registration pointless. Updates US-3 / US-22 / US-23 / flow J-1 / edge case E-13; adds **E-14** (daily gift not claimed).
34
> **v1.3(2026-08-14)· Platform Operator role defined(运营者 = 宿主本人).** The operator is the **deployer/owner (宿主本人)** with exactly two duties: **① view platform running overview** (status / users / shared keys / transactions / point flow) and **② top up points for a specific user** (permanent points, with transaction record). Content moderation / violation handling / market regulation are **explicitly excluded** — kept minimal. Adds US-运营1 / US-运营2 (replaces the "规划中 Planned" placeholder).
45
> **v1.2(2026-08-14)· Points model finalized(纯分享经济).** Every registered user receives **10 gift points** valid for **1 week**(新人体验券); points earned from sharing are **permanent**; future top-up points are **permanent**. Consumption deducts **expiring (gift) points first**. Adds US-22/23/24 and edge case E-13 (gift-point expiry).
56
> v1.1(2026-08-14)· Restructured. The document is now organized by **deployment scenario first, then user type** (场景 → 用户类型 → story): `## 公共场景 Public` / `## 企业场景 Enterprise`, each listing its user types with Goals / Pain points / User stories / Key flows. Content from v1.0 is reused, with ownership re-assigned to scenes.
@@ -12,7 +13,7 @@
1213

1314
**One product, two deployment scenarios** (not two feature sets):
1415

15-
- **Public edition(公共版)** — deployed on the public internet. Anyone can register, share idle API keys to earn points, and spend points to consume models shared by others. New registrations receive **10 gift points** (valid for 1 week).
16+
- **Public edition(公共版)** — deployed on the public internet. Anyone can register, share idle API keys to earn points, and spend points to consume models shared by others. New registrations enter the **daily gift program**: **1 gift point per day** (valid for that day only) for **10 consecutive natural days** — see the core mechanism table.
1617
- **Enterprise edition(企业版)** — deployed on an internal network. The administrator (IT) puts purchased keys into the key pool and allocates monthly point quotas to members.
1718

1819
The feature set is **identical**; the difference is *who is motivated to share* (everyone in public; only the admin in enterprise). **Roles are permission differences, not product differences** — the admin additionally sees the Admin view (key pool / members / usage reports / organization), regular users do not.
@@ -22,7 +23,7 @@ The feature set is **identical**; the difference is *who is motivated to share*
2223
| Term | Definition |
2324
|---|---|
2425
| **Point (点)** | The platform's unit of value. **1 USD = 1,000 points.** |
25-
| **Gift points(赠送点数)** | **10 points** granted to every new registered user(新人体验券); **valid for 1 week** from the moment of grant — unused gift points expire / 清零 automatically. |
26+
| **Gift points(赠送点数)** | New-user **daily gift program**: **1 point per day**(每日 1 点)for **10 consecutive natural days** from registration; each day's point is **valid for 1 day**(当日有效,过期清零). The user must **log in / come back that day** to claim it — a missed day's point is **not issued / not accumulated**, and the program ends after day 10. Anti-abuse: daily 1 pt with 1-day validity makes mass multi-account registration pointless(注册多号无意义). |
2627
| **Earned points(收益点数)** | Points earned from sharing keys; **permanent** — no expiry. |
2728
| **Top-up points(充值点数)** | Points obtained from future top-ups; **permanent**(充值功能当前暂不支持,但规则先定). |
2829
| **Deduction order(扣减顺序)** | Consumption deducts **expiring (gift) points first**, then permanent points — expiring points are never wasted and permanent points are never lost to an expiry race. |
@@ -42,7 +43,7 @@ Centralized (方案 A): **the platform hosts keys and executes calls** — the p
4243

4344
## 2. 公共场景 Public Scenario(公共场景)
4445

45-
> **Scene description(场景说明)**: The public edition is deployed on the **public internet** — anyone can register, share idle keys, and consume models with points. **Everyone has sharing motivation** (monetize idle subscription quota), so the sharing marketplace is the core of this scene. Registration is open; roles are determined by the account (the platform operator = 宿主本人, §2.4, with a minimal two-duty role). The feature set is identical to the enterprise edition; only *who shares* differs. **Points model (v1.2): the public edition currently has no top-up channel — new users start with the 10-point gift, and long-term points come from sharing (permanent).**
46+
> **Scene description(场景说明)**: The public edition is deployed on the **public internet** — anyone can register, share idle keys, and consume models with points. **Everyone has sharing motivation** (monetize idle subscription quota), so the sharing marketplace is the core of this scene. Registration is open; roles are determined by the account (the platform operator = 宿主本人, §2.4, with a minimal two-duty role). The feature set is identical to the enterprise edition; only *who shares* differs. **Points model (v1.4): the public edition currently has no top-up channel — new users get the daily gift program (1 pt / day, valid 1 day, for 10 consecutive days), and long-term points come from sharing (permanent).**
4647
4748
### 2.1 用户类型 A — 访客 / 新用户 Visitor / New User(未注册,浏览了解)
4849

@@ -62,7 +63,7 @@ Centralized (方案 A): **the platform hosts keys and executes calls** — the p
6263
- **US-2** As a visitor, I want to see a clear explanation of the points mechanism (1 USD = 1,000 points), so that I can decide whether to join.
6364
- AC: Points explanation visible from the landing/login page; conversion rate stated explicitly.
6465
- **US-3** As a new user, I want to register/login with an email, so that I can start using the platform.
65-
- AC: Single login entry (no public/enterprise choice at login); registration creates an account with **10 gift points valid for 1 week**; role (admin vs. user) is determined by the account.
66+
- AC: Single login entry (no public/enterprise choice at login); registration creates an account enrolled in the **daily gift program (1 pt / day, valid 1 day, for 10 consecutive days)**; role (admin vs. user) is determined by the account.
6667

6768
#### Key Flow(关键流程)— browse → understand → register
6869

@@ -71,11 +72,11 @@ flowchart LR
7172
A[Land on platform] --> B[Browse marketplace without login]
7273
B --> C[Learn points mechanism]
7374
C --> D[Register / login]
74-
D --> E[Account created + 10 gift points valid 1 week]
75+
D --> E[Account created + daily gift program starts: 1 pt / day for 10 days]
7576
```
7677

7778
1. Visitor lands on the login page and browses models/pricing first (US-1, US-2).
78-
2. Registers with email → account with 10 gift points (US-3, US-22); continues into the Regular User flow (J-1).
79+
2. Registers with email → account enrolled in the daily gift program (US-3, US-22); continues into the Regular User flow (J-1).
7980

8081
### 2.2 用户类型 B — 普通用户(消费者)Regular User / Consumer(注册,用点数消费模型)
8182

@@ -90,24 +91,24 @@ flowchart LR
9091
#### User Stories(用户故事)
9192

9293
- **US-4** As a regular user, I want to top up points, so that I can consume models.
93-
- AC: Wallet shows current balance and point sources (gift / earned / top-up); top-up flow is a placeholder (per current prototype: 充值/提现 temporarily unsupported, "即将上线") — the public edition has no top-up channel yet; new users start with the 10-point gift (US-22).
94+
- AC: Wallet shows current balance and point sources (gift / earned / top-up); top-up flow is a placeholder (per current prototype: 充值/提现 temporarily unsupported, "即将上线") — the public edition has no top-up channel yet; new users get the daily gift program (US-22).
9495
- **US-5** As a regular user, I want to search/filter/sort the marketplace, so that I can quickly find the model I need.
9596
- AC: Search by model/provider; filter by provider; sort by input price asc/desc and by context size desc; availability shown.
9697
- **US-6** As a regular user, I want to consume a model with points (chat/API), so that I can use the model without owning an upstream key.
9798
- AC: Selecting an available model opens chat/API entry; consumption deducts points per metered tokens × model price; a "consume" transaction is recorded; insufficient balance blocks the request with a clear message.
9899
- **US-7** As a regular user, I want to view my transactions, so that I can reconcile my spend and earnings.
99100
- AC: Transactions page is the single source of truth for consume/earn/topup/withdraw; tabs (all/consume/earn) + MRT-style table with column sort, column filter, pagination; wallet page links to it.
100-
- **US-22** As a new registered user, I want to receive 10 gift points, so that I can experience model consumption right away.
101-
- AC: Registration immediately grants 10 points(新人体验券); wallet shows the source "gift (赠送)"; unused gift points expire automatically after 1 week.
101+
- **US-22** As a new registered user, I want to receive daily gift points, so that I can experience model consumption right away.
102+
- AC: Registration starts the **daily gift program** — **1 point per day for 10 consecutive natural days**; each day's point is **valid for 1 day**(当天有效,过期清零)and must be claimed by logging in that day (a missed day's point is **not issued / not accumulated**); wallet shows the source "gift (赠送)" with the current day (e.g. "今日赠送 +1 · 连续第 N 天 / 共 10 天").
102103
- **US-23** As a regular user, I want to see the source and validity of my points, so that I can plan my usage.
103-
- AC: Wallet/transactions distinguish **gift / earned / top-up** point sources and their validity (e.g. "赠送 10 · 剩 5 天", "收益 320 · 永久"); consumption deducts expiring (gift) points first.
104+
- AC: Wallet/transactions distinguish **gift / earned / top-up** point sources and their validity (e.g. "赠送 +1 · 有效期至今日", "收益 320 · 永久"); consumption deducts expiring (gift) points first.
104105

105106
#### Key Flow(关键流程)— J-1: register → first consumption
106107

107108
```mermaid
108109
flowchart LR
109110
A[Visitor browses marketplace] --> B[Registers / logs in]
110-
B --> C[Gets 10 gift points valid 1 week]
111+
B --> C[Daily gift program: +1 pt, valid 1 day, for 10 days]
111112
C --> D[Marketplace: search / filter / sort]
112113
D --> E[Pick model - availability ok]
113114
E --> F[Consume: chat or API]
@@ -116,7 +117,7 @@ flowchart LR
116117
```
117118

118119
1. Visitor lands on the login page, browses models and pricing first (US-1, US-2).
119-
2. Registers with email → account receives 10 gift points valid for 1 week (US-3, US-22).
120+
2. Registers with email → account enrolled in the daily gift program — 1 pt / day (valid 1 day) for 10 consecutive days (US-3, US-22).
120121
3. No top-up channel in the public edition yet (US-4 placeholder); starts with gift points.
121122
4. Searches/filters/sorts the marketplace (US-5).
122123
5. Picks an available model and consumes via chat/API (US-6).
@@ -326,7 +327,8 @@ flowchart LR
326327
| E-10 | **Single heavy user draining budget**(单个重度用户耗尽预算) | 【企业】 | Usage reports (by member) surface it; admin can top up/adjust or change department allocation; low-balance alerts help the member self-regulate. |
327328
| E-11 | **Availability flapping**(可用性抖动) | 【公共】 | Marketplace shows `busy` availability for models with no ready key; retry/choose-another guidance; no silent failure. |
328329
| E-12 | **Duplicate / conflicting listings of the same key**(同一 key 重复/冲突上架) | 【公共】 | Platform detects the same upstream key listed twice and warns the sharer; prevents double counting of the same quota. |
329-
| E-13 | **Gift points expired**(赠送点数过期) | 【公共】 | Unused gift points expire 1 week after grant — balance decreases automatically at expiry (清零). Expiry is visible in advance (e.g. "剩 X 天"). Consumption always deducts **expiring (gift) points first**, then permanent points, so gift points are used before they expire and permanent points are never lost. |
330+
| E-13 | **Daily gift point expired**(每日赠送点数过期) | 【公共】 | Each daily gift point is valid **1 day**(当日有效)— unused points expire / 清零 at the end of the day. Expiry is visible (e.g. "有效期至今日"). Consumption always deducts **expiring (gift) points first**, then permanent points, so daily gift points are used before they expire and permanent points are never lost. |
331+
| E-14 | **Daily gift not claimed**(当日赠送未领取) | 【公共】 | The gift program runs for **10 consecutive natural days** from registration, 1 pt per day; if the user does not log in on a day, that day's point is **not issued and not accumulated**(不积累、不补发)— the program still ends after day 10. |
330332

331333
---
332334

@@ -336,7 +338,7 @@ flowchart LR
336338
|---|---|---|
337339
| Pages / navigation | `ui/index.html` (Dashboard / Marketplace / Sharing / Wallet / Transactions / Settings + Admin role view) | Every story maps to a concrete page; Admin view is role-gated, others shared. |
338340
| Points & pricing | `ui/js/data.js` (1 USD = 1,000 pts; model price table; reference price = output price points/1M) | US-2, US-8 use the same rules; no sharer-set pricing. |
339-
| Points validity & deduction order | `docs/user-stories.md` v1.2 (gift 10 pts / 1 week; earned & top-up permanent; deduct gift first) | US-22, US-23, US-24, E-13 consistent; UI mock (`feat/points-model-ui`) shows gift source + remaining days. |
341+
| Points validity & deduction order | `docs/user-stories.md` v1.4 (daily gift 1 pt / 1-day validity / 10 consecutive days; earned & top-up permanent; deduct gift first) | US-22, US-23, US-24, E-13, E-14 consistent; UI mock shows today's gift (+1) with validity and the consecutive-day counter. |
340342
| Key masking & security | `ui/js/data.js`, `ui/README.md` (masked keys, encrypted hosting, delete confirmation) | US-8, US-9, US-21, E-05 consistent. |
341343
| Enterprise semantics | `ui/js/data.js` (key pool statuses, departments, members unassigned) | US-12…US-16, E-03, E-06 consistent. |
342344
| Centralized architecture | `docs/architecture.md` (platform hosts keys, metering engine, ledger) | The whole doc assumes centralized execution; consumption/earnings flow through the platform ledger. |

0 commit comments

Comments
 (0)