@seasonkoh/webaz 0.1.25 → 0.1.26

package/dist/pwa/routes/auth-register.js

@@ -1,10 +1,53 @@
-import { dbOne } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
+import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerAuthRegisterRoutes(app, deps) {
     // VALID_REGIONS + INVITE_ROTATION_HANDLES 通过 deps.X 在 handler 内延迟读
     // （server.ts 用 getter 注入；destructure at register-time would trigger TDZ 因为它们在下方 const）
-    const { db, errorRes, INTERNAL_AUDITOR_ID, isAllowedSponsor, resolveInviteCodeRef, generateId, generateSecureKey, generatePermanentCode, deriveHandle, clientIpHash, clientUaHash, pickPreferredSide, joinPowerLeg, inviteRotationLookup, recordSession, broadcastSystemEvent } = deps;
+    const { db, errorRes, INTERNAL_AUDITOR_ID, isAllowedSponsor, resolveInviteCodeRef, generateId, generateSecureKey, generatePermanentCode, deriveHandle, clientIpHash, clientUaHash, pickPreferredSide, joinPowerLeg, inviteRotationLookup, issueCode, findActiveCode, canDeliverCodes, emailDeliveryNotConfigured, recordSession, broadcastSystemEvent } = deps;
+    // CODE_TTL_MIN / MAX_CODE_ATTEMPTS 通过 deps.X 在 handler 内延迟读(它们在 server.ts 是后置 const,
+    // register-time destructure 会触发 TDZ)。
+    const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+    const normEmail = (raw) => String(raw || '').trim().toLowerCase();
+    // IP 级发码限流(5/min)— 防爆破列举邮箱 / 刷验证码
+    const regCodeHits = new Map();
+    // 注册邮箱验证:发码到邮箱(purpose='register',无账号故 user_id='')。
+    // 注册场景需明确告知"邮箱已占用"(无法防枚举,标准取舍),但限流 + captcha 兜底。
+    app.post('/api/register/send-code', async (req, res) => {
+        const email = normEmail(req.body?.email);
+        if (!email || !EMAIL_RE.test(email))
+            return void errorRes(res, 400, 'EMAIL_INVALID', '请填写有效邮箱');
+        if (!canDeliverCodes()) {
+            const u = emailDeliveryNotConfigured();
+            return void res.status(u.status).json({ error: u.error, error_code: u.error_code });
+        }
+        const ip = req.ip || '';
+        if (ip) {
+            const now = Date.now();
+            const rec = regCodeHits.get(ip);
+            if (rec && now - rec.firstAt < 60_000) {
+                rec.count++;
+                if (rec.count > 5)
+                    return void errorRes(res, 429, 'CODE_RATE_LIMITED', '发送过于频繁，请 1 分钟后再试');
+            }
+            else {
+                regCodeHits.set(ip, { count: 1, firstAt: now });
+            }
+            if (regCodeHits.size > 1000) {
+                for (const [k, v] of regCodeHits)
+                    if (now - v.firstAt > 60_000)
+                        regCodeHits.delete(k);
+            }
+        }
+        const dup = await dbOne("SELECT 1 FROM users WHERE lower(email) = ? AND email_verified = 1 AND id NOT IN ('sys_protocol', ?) LIMIT 1", [email, INTERNAL_AUDITOR_ID]);
+        if (dup)
+            return void errorRes(res, 409, 'EMAIL_TAKEN', '该邮箱已注册，请直接登录或用 #recover 找回');
+        const issued = await issueCode('', 'email', email, 'register');
+        if (!issued.ok) {
+            return void res.status(issued.status || 503).json({ error: issued.error || '验证码发送失败，请稍后再试', error_code: issued.error_code || 'EMAIL_DELIVERY_FAILED' });
+        }
+        res.json({ success: true, notice: '验证码已发送至邮箱，请查收（含垃圾箱）', expires_in_min: deps.CODE_TTL_MIN });
+    });
     app.post('/api/register', async (req, res) => {
-        const { name, role, sponsor_id, region, placement_inviter_id, placement_side, turnstile_token } = req.body;
+        const { name, role, sponsor_id, region, placement_inviter_id, turnstile_token } = req.body;
         const validRoles = ['buyer', 'seller'];
         if (!name?.trim())
             return void errorRes(res, 400, 'NAME_REQUIRED', '请填写名称');
@@ -43,6 +86,32 @@ export function registerAuthRegisterRoutes(app, deps) {
         const dup = await dbOne("SELECT 1 FROM users WHERE name = ? AND id NOT IN ('sys_protocol', ?) LIMIT 1", [trimmed, INTERNAL_AUDITOR_ID]);
         if (dup)
             return void errorRes(res, 409, 'NAME_TAKEN', '该名称已被占用，请换一个');
+        // ── 邮箱验证优先注册 ────────────────────────────────────────
+        // PWA 人类路径强制:必须先 /register/send-code 拿验证码,提交时带 email + code,校验通过才建号 + email_verified=1。
+        // 这样每个新 PWA 账号天生有 verified 邮箱 → #recover 永远可用。
+        // agent/MCP 注册走 handleRegister 直插库(自托管 key,不需邮件找回),不经此端点,不受影响。
+        const email = normEmail(req.body?.email);
+        const code = String(req.body?.code || '').trim();
+        if (!email || !code)
+            return void errorRes(res, 400, 'EMAIL_VERIFICATION_REQUIRED', '注册需先验证邮箱:请填写邮箱并输入收到的验证码');
+        if (!EMAIL_RE.test(email))
+            return void errorRes(res, 400, 'EMAIL_INVALID', '邮箱格式不正确');
+        const emailDup = await dbOne("SELECT 1 FROM users WHERE lower(email) = ? AND email_verified = 1 AND id NOT IN ('sys_protocol', ?) LIMIT 1", [email, INTERNAL_AUDITOR_ID]);
+        if (emailDup)
+            return void errorRes(res, 409, 'EMAIL_TAKEN', '该邮箱已注册，请直接登录或用 #recover 找回');
+        // 校验注册验证码(按 email 查,purpose='register')。错码计数,超限作废,均【不建号】。
+        const codeRow = findActiveCode('email', email, 'register');
+        if (!codeRow)
+            return void errorRes(res, 400, 'CODE_EXPIRED', '验证码已过期或未发送，请重新获取');
+        if (String(codeRow.code) !== code) {
+            const attempts = Number(codeRow.attempts || 0) + 1;
+            if (attempts >= deps.MAX_CODE_ATTEMPTS) {
+                await dbRun("UPDATE verification_codes SET attempts = ?, used_at = datetime('now') WHERE id = ?", [attempts, codeRow.id]);
+                return void errorRes(res, 400, 'CODE_TOO_MANY', '错误次数过多，验证码已作废，请重新获取');
+            }
+            await dbRun("UPDATE verification_codes SET attempts = ? WHERE id = ?", [attempts, codeRow.id]);
+            return void errorRes(res, 400, 'CODE_INVALID', `验证码错误（剩余 ${deps.MAX_CODE_ATTEMPTS - attempts} 次）`);
+        }
         const ROLE_WHITELIST = [];
         const requireRef = (await dbOne("SELECT value FROM system_state WHERE key='require_ref_to_register'", []))?.value === '1';
         // 2026-05-30 合规复审:取消 china 豁免——D1b 引入时保留 china 通道是为获客,
@@ -57,15 +126,14 @@ export function registerAuthRegisterRoutes(app, deps) {
         // invite codes ONLY: 6-7 char permanent_code with optional -L/-R side. usr_xxx / @handle / handle are
         // no longer accepted as a registration sponsor (anti-ambiguity; narrows the public invite surface).
         const sponsorRawRef = (sponsor_id && typeof sponsor_id === 'string') ? sponsor_id.trim() : '';
-        let suffixSide = null;
         let resolvedSponsorId = null;
         if (sponsorRawRef) {
             const ref = resolveInviteCodeRef(sponsorRawRef);
             if (!ref) {
-                return void errorRes(res, 400, 'INVALID_SPONSOR_REF', `邀请码无效：${sponsorRawRef.slice(0, 24)}（仅接受 6-7 位永久码，可带 -L/-R；请检查或留空跳过）`);
+                return void errorRes(res, 400, 'INVALID_SPONSOR_REF', `邀请码无效：${sponsorRawRef.slice(0, 24)}（仅接受 6-7 位永久码；请检查或留空跳过）`);
             }
             resolvedSponsorId = ref.userId;
-            suffixSide = ref.side; // -L/-R parsed from the code itself
+            // pre-public: 去左右码 — 邀请码自带的 -L/-R 侧别一律忽略,放置永远自动(见下)
             const sponsor = await dbOne("SELECT id, sponsor_path FROM users WHERE id = ?", [ref.userId]);
             if (!sponsor) {
                 return void errorRes(res, 400, 'INVALID_SPONSOR_REF', `邀请码对应用户不存在：${sponsorRawRef.slice(0, 24)}`);
@@ -95,21 +163,22 @@ export function registerAuthRegisterRoutes(app, deps) {
             return void errorRes(res, 429, 'REGISTER_RATE_LIMITED', '注册过于频繁 — 同一网络每小时最多 5 个新账号，请稍后再试');
         }
         const registerTx = db.transaction(() => {
-            db.prepare(`INSERT INTO users (id, name, role, roles, api_key, sponsor_id, sponsor_path, region, permanent_code, handle)
-                  VALUES (?,?,?,?,?,?,?,?,?,?)`)
-                .run(id, trimmed, role, JSON.stringify([role]), apiKey, sponsorId, sponsorPath, userRegion, permaCode, userHandle);
+            db.prepare(`INSERT INTO users (id, name, role, roles, api_key, sponsor_id, sponsor_path, region, permanent_code, handle, email, email_verified)
+                  VALUES (?,?,?,?,?,?,?,?,?,?,?,1)`)
+                .run(id, trimmed, role, JSON.stringify([role]), apiKey, sponsorId, sponsorPath, userRegion, permaCode, userHandle, email);
+            // 消费注册验证码(单次性)— 与建号同一事务,失败则整体回滚,不留"码已用但没建号"
+            db.prepare("UPDATE verification_codes SET used_at = datetime('now') WHERE id = ?").run(codeRow.id);
             db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?,1000)').run(id);
             db.prepare(`INSERT INTO registration_audit_log (user_id, ip_hash, ua_hash, sponsor_id) VALUES (?,?,?,?)`)
                 .run(id, ipHash, uaHash, sponsorId);
             // placement inviter is invite-code-only too (the sponsor code, or an explicit placement_inviter_id code)
             let effectiveInviter = resolvedSponsorId;
-            let effectiveSide = (placement_side === 'left' || placement_side === 'right') ? placement_side : suffixSide;
+            // pre-public 去左右码:不再接受用户/邀请码指定的左右侧,放置侧别永远由系统自动决定(pickPreferredSide)
+            let effectiveSide = null;
             if (placement_inviter_id) {
                 const p = resolveInviteCodeRef(String(placement_inviter_id));
                 if (p) {
                     effectiveInviter = p.userId;
-                    if (!effectiveSide && p.side)
-                        effectiveSide = p.side;
                 }
             }
             if (effectiveInviter && !effectiveSide) {
@@ -173,6 +242,7 @@ export function registerAuthRegisterRoutes(app, deps) {
             sponsor_id: sponsorId, region: userRegion,
             permanent_code: permaCode,
             handle: userHandle,
+            email, email_verified: true,
             placement: placement ? { inviter_id: effectiveInviter, side: effectiveSide, depth: placement.depth } : null,
             ...(sponsorSkipped ? { sponsor_skipped: sponsorSkipped } : {}),
         });

package/dist/pwa/routes/contribution-identity.js

@@ -3,6 +3,7 @@ import { issueGithubIdentityClaimChallenge, getIssuedChallengeForVerification, }
 import { verifyGithubGistProof } from '../../layer2-business/L2-9-contribution/identity-claim-proof-verifier.js';
 import { claimGithubIdentity } from '../../layer2-business/L2-9-contribution/identity-claim-engine.js';
 import { getMyGithubIdentitySurface } from '../../layer2-business/L2-9-contribution/identity-claim-read.js';
+import { listClaimableGithubIdentityFacts } from '../../layer2-business/L2-9-contribution/identity-claim-discovery.js';
 import { withUncommittedValueBoundary } from '../../layer2-business/L2-9-contribution/contribution-display-envelope.js';
 // ── strict request bodies (unknown/sensitive keys → rejected; nothing trusts a caller field) ──
 const ChallengeBody = z.strictObject({
@@ -144,4 +145,20 @@ export function registerContributionIdentityRoutes(app, deps) {
             return void errorRes(res, 500, 'INTERNAL', '内部错误'); // never leak a stack / query
         }
     });
+    // F10 — claimable-fact discovery (read-only). Same posture as /github/me: auth required, the account
+    // context is ALWAYS the session user (the request query/body are never read — an ?account_id= is ignored), the
+    // engine issues SELECT only (no challenge, no binding write, no accountable_ref change), the response
+    // carries the uncommitted-value boundary, and errors never leak SQL/stack.
+    app.get('/api/contribution-identity/github/claimable', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        try {
+            const surface = await listClaimableGithubIdentityFacts(user.id);
+            res.json(withUncommittedValueBoundary(surface));
+        }
+        catch {
+            return void errorRes(res, 500, 'INTERNAL', '内部错误'); // never leak a stack / query
+        }
+    });
 }

package/dist/pwa/routes/growth.js

@@ -3,7 +3,7 @@ const GROWTH_TASK_CATALOG = [
     // 第 1 关：新手起步
     { id: 'first_purchase', chapter: 1,
         title_zh: '完成首笔购买', title_en: 'Complete first purchase',
-        desc_zh: '解锁分享奖励资格', desc_en: 'Unlocks share-commission eligibility',
+        desc_zh: '完成后可使用分享功能(分享仅作归因 / 参与记录)', desc_en: 'Unlocks the share feature (attribution / participation record only)',
         cta: { label_zh: '去发现', label_en: 'Browse', href: '#buy' },
         evaluate: c => c.completed_orders >= 1 },
     { id: 'default_address', chapter: 1,

package/dist/pwa/routes/orders-action.js

@@ -21,12 +21,14 @@ export function registerOrdersActionRoutes(app, deps) {
             return void res.status(400).json({ error: 'order_ids 必填' });
         if (order_ids.length > 100)
             return void res.status(400).json({ error: '单次最多 100 单' });
-        if (!logistics_company_id)
-            return void res.status(400).json({ error: 'logistics_company_id 必填' });
+        // 自发货(self-fulfill,Phase 1 默认):不传 logistics_company_id → logistics_id 留空,卖家自负后续流转。
+        // 只有传了物流公司时才校验其存在。
         // RFC-016: 纯校验读 → 异步 seam(物流公司是否存在);循环内的逐单 read+write 仍同步(Phase 3 随订单事务迁)
-        const lc = await dbOne("SELECT id FROM users WHERE id = ? AND role = 'logistics'", [logistics_company_id]);
-        if (!lc)
-            return void res.status(400).json({ error: '物流公司不存在' });
+        if (logistics_company_id) {
+            const lc = await dbOne("SELECT id FROM users WHERE id = ? AND role = 'logistics'", [logistics_company_id]);
+            if (!lc)
+                return void res.status(400).json({ error: '物流公司不存在' });
+        }
         const results = [];
         const trackingMap = (tracking_numbers && typeof tracking_numbers === 'object') ? tracking_numbers : {};
         for (const oid of order_ids) {
@@ -44,18 +46,22 @@ export function registerOrdersActionRoutes(app, deps) {
                     results.push({ order_id: oid, status: 'skipped', reason: `状态非 accepted (当前 ${o.status})` });
                     continue;
                 }
-                if (!o.logistics_id) {
+                // 仅当指定了物流公司时才绑定;自发货保持 logistics_id 为空(seller self-fulfill)
+                if (logistics_company_id && !o.logistics_id) {
                     db.prepare("UPDATE orders SET logistics_id = ? WHERE id = ?").run(logistics_company_id, oid);
                 }
                 const tn = trackingMap[oid] ? String(trackingMap[oid]).slice(0, 50) : null;
+                // accepted→shipped 状态机要求 evidence(requiresEvidence)。【始终】写一条文字 evidence,
+                // 否则无单号(尤其自发货默认)会被状态机拒绝 → shipped:0 卡在 accepted。单号可之后补。
+                const evDesc = logistics_company_id
+                    ? (tn ? `批量发货 · 快递单号：${tn} · 物流方 ${logistics_company_id}` : `批量发货，已交付物流公司 ${logistics_company_id}，快递单号待物流揽收后回传`)
+                    : (tn ? `卖家自己发货（批量）· 快递单号：${tn}` : `卖家自己发货（批量·自提自送）—— 由卖家负责揽收/运输/送达，单号可之后补`);
                 const evIds = [];
-                if (tn) {
-                    const eid = generateId('evt');
-                    db.prepare(`INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
-            VALUES (?,?,?,'description',?,?)`).run(eid, oid, user.id, `快递单号：${tn}`, `hash_${Date.now()}`);
-                    evIds.push(eid);
-                }
-                const result = transition(db, oid, 'shipped', user.id, evIds, tn ? `批量发货 · ${tn}` : '批量发货');
+                const eid = generateId('evt');
+                db.prepare(`INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
+          VALUES (?,?,?,'description',?,?)`).run(eid, oid, user.id, evDesc, `hash_${Date.now()}`);
+                evIds.push(eid);
+                const result = transition(db, oid, 'shipped', user.id, evIds, evDesc);
                 if (!result.success) {
                     results.push({ order_id: oid, status: 'skipped', reason: result.error || '状态机拒绝' });
                     continue;

package/dist/pwa/routes/profile-credentials.js

@@ -2,7 +2,7 @@ import { dbOne, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // R
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 export function registerProfileCredentialsRoutes(app, deps) {
     // db 已全量走 RFC-016 异步 seam(dbOne/dbRun),不再直接用 deps.db
-    const { auth, verifyPassword, hashPassword, issueCode, findActiveCode, IS_DEV, MAX_CODE_ATTEMPTS } = deps;
+    const { auth, verifyPassword, hashPassword, issueCode, findActiveCode, MAX_CODE_ATTEMPTS } = deps;
     // 设置 / 修改密码
     app.post('/api/profile/set-password', async (req, res) => {
         const user = auth(req, res);
@@ -65,12 +65,15 @@ export function registerProfileCredentialsRoutes(app, deps) {
         const dup = await dbOne("SELECT 1 FROM users WHERE email = ? AND id != ? LIMIT 1", [target, user.id]);
         if (dup)
             return void res.json({ error: '该邮箱已被其他账户绑定' });
-        const { expires_at, code } = issueCode(user.id, 'email', target, 'bind_email');
+        const issued = await issueCode(user.id, 'email', target, 'bind_email');
+        if (!issued.ok) {
+            return void res.status(issued.status).json({ error: issued.error, error_code: issued.error_code });
+        }
         res.json({
             success: true,
             target_hint: target.replace(/^(.).*(@.*)$/, '$1***$2'),
-            expires_at,
-            ...(IS_DEV ? { dev_code: code } : {}),
+            expires_at: issued.expires_at,
+            ...(issued.provider === 'dev_console' ? { dev_code: issued.code } : {}),
         });
     });
     // 绑定邮箱 — 步骤 2：确认验证码

package/dist/pwa/routes/profile-placement.js

@@ -22,14 +22,14 @@ export function registerProfilePlacementRoutes(app, deps) {
         const user = auth(req, res);
         if (!user)
             return;
-        const { inviter_id, side } = req.body;
+        const { inviter_id } = req.body;
         if (!inviter_id || typeof inviter_id !== 'string')
             return void res.json({ error: '请提供 inviter_id' });
-        // invite-code ONLY: 6-7 位 permanent_code,可带 -L/-R。usr_xxx / @handle / 裸 handle 不再接受 —
-        // 这是二叉树关系绑定入口,必须与收窄后的邀请面一致。
+        // invite-code ONLY: 6-7 位 permanent_code。usr_xxx / @handle / 裸 handle 不再接受 —
+        // 这是积分树关系绑定入口,必须与收窄后的邀请面一致。
         const ref = resolveInviteCodeRef(inviter_id);
         if (!ref)
-            return void res.json({ error: 'inviter 邀请码无效（仅 6-7 位永久码，可带 -L/-R）' });
+            return void res.json({ error: 'inviter 邀请码无效（仅 6-7 位永久码）' });
         const resolvedInviterId = ref.userId;
         if (resolvedInviterId === user.id)
             return void res.json({ error: '不能挂靠到自己' });
@@ -45,9 +45,8 @@ export function registerProfilePlacementRoutes(app, deps) {
         if ((inviter.placement_path || '').split('>').includes(user.id)) {
             return void res.json({ error: '检测到环路（你已是 inviter 的上线）' });
         }
-        // 选边：body side > 邀请码自带的 -L/-R > inviter.placement_pref 自动选
-        const effSide = (side === 'left' || side === 'right') ? side : ref.side;
-        const chosenSide = effSide || pickPreferredSide(inviter.id);
+        // pre-public 去左右码:忽略用户/邀请码指定的左右侧,放置侧别永远由系统自动决定
+        const chosenSide = pickPreferredSide(inviter.id);
         try {
             const placed = joinPowerLeg(inviter.id, chosenSide, user.id);
             res.json({ success: true, inviter_id: inviter.id, side: chosenSide, depth: placed.depth });
@@ -67,6 +66,6 @@ export function registerProfilePlacementRoutes(app, deps) {
         // legacy left/right 已不再支持长期强偏，无声折算为 team_count（agent 兼容期保护）
         const stored = (pref === 'left' || pref === 'right') ? 'team_count' : pref;
         await dbRun("UPDATE users SET placement_pref = ?, updated_at = datetime('now') WHERE id = ?", [stored, user.id]);
-        res.json({ success: true, placement_pref: stored, coerced: stored !== pref ? `${pref} → ${stored}（已统一为长期默认偏好；要单次强偏请使用左/右码）` : undefined });
+        res.json({ success: true, placement_pref: stored, coerced: stored !== pref ? `${pref} → ${stored}（已统一为长期默认偏好）` : undefined });
     });
 }

package/dist/pwa/routes/promoter.js

@@ -90,17 +90,8 @@ export function registerPromoterRoutes(app, deps) {
             next_30_estimate: earnedLast30 + wazLast30,
         };
         const insights = [];
-        const leftPv = Number(myUser?.total_left_pv ?? 0);
-        const rightPv = Number(myUser?.total_right_pv ?? 0);
-        if (leftPv > 0 || rightPv > 0) {
-            const max = Math.max(leftPv, rightPv), min = Math.min(leftPv, rightPv);
-            const ratio = max > 0 ? min / max : 0;
-            const weak = leftPv < rightPv ? '左区' : '右区';
-            if (ratio < 0.5)
-                insights.push({ type: 'weak_leg', level: 'warn', text: `${weak} PV 仅为强腿的 ${(ratio * 100).toFixed(0)}% — 建议主推${weak}，对碰 = min(L,R) × tier_score` });
-            else
-                insights.push({ type: 'balanced', level: 'success', text: `双腿均衡度 ${(ratio * 100).toFixed(0)}% — 对碰节奏健康` });
-        }
+        // pre-public de-MLM:移除弱腿 / pairing / PV-tier 经营建议 —— PV 对碰为 pre-launch、未对用户启用,
+        // 不在用户面 surface 营销主推弱腿 / pairing 公式 / PV-tier 进度等玩法。位置 / PV 仅为参与记录,非收益路径。
         const lastInvite = (await dbOne(`SELECT MAX(created_at) as t FROM users WHERE sponsor_id = ?`, [userId]));
         if (lastInvite.t) {
             const days = Math.floor((Date.now() - new Date(lastInvite.t).getTime()) / 86400_000);
@@ -112,13 +103,8 @@ export function registerPromoterRoutes(app, deps) {
         else if (l1 === 0) {
             insights.push({ type: 'no_team', level: 'info', text: `还没有直推 — 先分享你买过且好评的商品给好友` });
         }
-        const pair = Math.min(leftPv, rightPv);
-        const nextTier = tiers.find(t => t.pv_threshold > pair);
-        if (nextTier && pair > 0 && pair / nextTier.pv_threshold > 0.7) {
-            insights.push({ type: 'near_tier', level: 'success', text: `距离 tier ${nextTier.tier} 仅差 ${(nextTier.pv_threshold - pair).toLocaleString()} PV (+${nextTier.score_per_hit} Score / 次)` });
-        }
         if (!canL1Share && completedOrders === 0) {
-            insights.push({ type: 'unlock', level: 'info', text: `完成首笔购买可解锁分享奖励 — 当前仅可分享 PV 加人扩双轨树` });
+            insights.push({ type: 'share_hint', level: 'info', text: `完成首笔购买后可使用分享功能;分享记录仅作归因 / 参与记录,不构成收益承诺。` });
         }
         if (shareableProducts.length > 0 && grand === 0) {
             insights.push({ type: 'first_share', level: 'info', text: `你有 ${shareableProducts.length} 个可分享商品但暂无成交 — 试着把链接发给身边的人` });

package/dist/pwa/routes/ratings.js

@@ -144,11 +144,17 @@ export function registerRatingsRoutes(app, deps) {
         const user = auth(req, res);
         if (!user)
             return;
-        const r = await dbOne('SELECT seller_id, reply FROM order_ratings WHERE order_id = ?', [req.params.order_id]);
+        const r = await dbOne('SELECT seller_id, reply, hidden_until FROM order_ratings WHERE order_id = ?', [req.params.order_id]);
         if (!r)
             return void res.status(404).json({ error: '该订单暂无评价' });
         if (r.seller_id !== user.id)
             return void res.status(403).json({ error: '仅卖家可回复' });
+        // 双盲铁律:未揭晓前不能回复(回复=已读到评价)。揭晓条件 = 自己也评过买家 OR 盲评期已过。
+        const sellerAlsoRated = !!(await dbOne(`SELECT order_id FROM buyer_ratings WHERE order_id = ?`, [req.params.order_id]));
+        const blindExpired = !!r.hidden_until && new Date(r.hidden_until) < new Date();
+        if (!sellerAlsoRated && !blindExpired) {
+            return void res.status(403).json({ error: '双盲期未结束:请先评价买家，或等盲评期满后再回应', error_code: 'RATING_STILL_BLIND' });
+        }
         if (r.reply)
             return void res.status(400).json({ error: '已回复过，每条评价仅可回复一次' });
         const reply = req.body?.reply ? String(req.body.reply).slice(0, 500) : null;
@@ -201,9 +207,63 @@ export function registerRatingsRoutes(app, deps) {
     `, [req.params.product_id]);
         res.json({ items: rows, agg });
     });
-    // 公开：卖家评价聚合（卖家主页）
+    // 卖家:自己店铺收到的全部评价(含 order_id 便于逐条回复 + 回复/追问状态)。
+    // 与公开聚合 endpoint 分开:authed + 只返回本人的评价 + 暴露 order_id(仅给卖家本人)。
+    // 纯只读,不改任何评价 / 资金逻辑;回复仍走既有 POST /orders/:order_id/rating/reply。
+    // ⚠️ 必须注册在 /api/sellers/:seller_id/ratings 【之前】,否则 'me' 会被 :seller_id 参数路由抢匹配。
+    app.get('/api/sellers/me/ratings', async (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const limit = Math.min(100, Math.max(1, Number(req.query.limit) || 50));
+        // 双盲铁律:卖家看 buyer→seller 评价,必须【自己也评过买家】(buyer_ratings 存在) 或【盲评期已过】(hidden_until 到期)。
+        // 否则只返回遮蔽行(不含 stars/comment/reply),与 GET /orders/:id/rating 的揭晓条件一致 —— 防卖家看了买家评价再反向报复。
+        const rows = await dbAll(`
+      SELECT r.order_id, r.stars, r.comment, r.reply, r.replied_at, r.buyer_followup, r.buyer_followup_at, r.created_at, r.product_id, r.hidden_until,
+             p.title as product_title,
+             u.name as buyer_name, u.handle as buyer_handle,
+             (SELECT 1 FROM buyer_ratings br WHERE br.order_id = r.order_id) AS seller_also_rated
+      FROM order_ratings r
+      JOIN products p ON p.id = r.product_id
+      JOIN users u ON u.id = r.buyer_id
+      WHERE r.seller_id = ?
+      ORDER BY r.created_at DESC LIMIT ?
+    `, [user.id, limit]);
+        const now = Date.now();
+        let unreplied = 0;
+        const items = rows.map(r => {
+            const blindExpired = !!r.hidden_until && new Date(r.hidden_until).getTime() < now;
+            const revealed = !!r.seller_also_rated || blindExpired;
+            if (!revealed) {
+                // 遮蔽:只回最小信息(有评价 + 商品 + 解除条件),绝不泄露分数/评论/回复
+                return { order_id: r.order_id, product_title: r.product_title, created_at: r.created_at, hidden_until: r.hidden_until, masked: true, reveal_reason: 'blind_until_both_or_expire' };
+            }
+            if (!r.reply)
+                unreplied++;
+            return {
+                order_id: r.order_id, stars: r.stars, comment: r.comment, reply: r.reply, replied_at: r.replied_at,
+                buyer_followup: r.buyer_followup, buyer_followup_at: r.buyer_followup_at, created_at: r.created_at,
+                product_id: r.product_id, product_title: r.product_title, buyer_name: r.buyer_name, buyer_handle: r.buyer_handle,
+                masked: false,
+            };
+        });
+        // 聚合双盲铁律:cnt / avg_stars 必须【只算已揭晓评价】,否则盲评期内卖家能从均分反推买家未揭晓评分。
+        // 与公开面同 blindOpen 条件;另回 masked_count(只告知"有多少条遮蔽中",不含分数)。
+        const blindOpen = `(EXISTS (SELECT 1 FROM buyer_ratings br WHERE br.order_id = r.order_id) OR r.hidden_until IS NULL OR datetime(r.hidden_until) <= datetime('now'))`;
+        const agg = await dbOne(`
+      SELECT
+        SUM(CASE WHEN ${blindOpen} THEN 1 ELSE 0 END) as cnt,
+        COALESCE(AVG(CASE WHEN ${blindOpen} THEN stars END), 0) as avg_stars,
+        SUM(CASE WHEN ${blindOpen} THEN 0 ELSE 1 END) as masked_count
+      FROM order_ratings r WHERE r.seller_id = ?`, [user.id]);
+        res.json({ items, agg: { ...(agg || {}), unreplied } });
+    });
+    // 公开：卖家评价聚合（卖家主页）。注册在 /me 之后(见上面注释)。
     app.get('/api/sellers/:seller_id/ratings', async (req, res) => {
         const limit = Math.min(50, Math.max(1, Number(req.query.limit) || 20));
+        // 双盲铁律(公开面):只展示已揭晓的评价 —— 与 GET /products/:id/ratings 同条件。
+        // 揭晓 = 双方都评过(buyer_ratings 存在) OR 无盲评窗口(hidden_until 空) OR 盲评期已过。
+        const blindOpen = `(EXISTS (SELECT 1 FROM buyer_ratings br WHERE br.order_id = r.order_id) OR r.hidden_until IS NULL OR datetime(r.hidden_until) <= datetime('now'))`;
         const rows = await dbAll(`
       SELECT r.stars, r.comment, r.reply, r.replied_at, r.buyer_followup, r.buyer_followup_at, r.created_at, r.product_id,
              p.title as product_title,
@@ -211,10 +271,10 @@ export function registerRatingsRoutes(app, deps) {
       FROM order_ratings r
       JOIN products p ON p.id = r.product_id
       JOIN users u ON u.id = r.buyer_id
-      WHERE r.seller_id = ?
+      WHERE r.seller_id = ? AND ${blindOpen}
       ORDER BY r.created_at DESC LIMIT ?
     `, [req.params.seller_id, limit]);
-        const agg = await dbOne(`SELECT COUNT(*) as cnt, COALESCE(AVG(stars), 0) as avg_stars FROM order_ratings WHERE seller_id = ?`, [req.params.seller_id]);
+        const agg = await dbOne(`SELECT COUNT(*) as cnt, COALESCE(AVG(stars), 0) as avg_stars FROM order_ratings r WHERE r.seller_id = ? AND ${blindOpen}`, [req.params.seller_id]);
         res.json({ items: rows, agg });
     });
 }

package/dist/pwa/routes/recover-key.js

@@ -1,7 +1,15 @@
 import { dbOne, dbAll, dbRun } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam
 export function registerRecoverKeyRoutes(app, deps) {
     // db 已走 RFC-016 异步 seam(dbOne/dbAll/dbRun),不再直接用 deps.db
-    const { internalAuditorId, issueCode, findActiveCode, CODE_TTL_MIN, MAX_CODE_ATTEMPTS } = deps;
+    const { internalAuditorId, issueCode, findActiveCode, canDeliverCodes, emailDeliveryNotConfigured, hashPassword, CODE_TTL_MIN, MAX_CODE_ATTEMPTS } = deps;
+    // 账号标识解析 —— 与 /api/login 一致:@handle / handle(小写)优先,name 兜底。
+    // 找回三步全部复用它,否则用 handle 登录的用户(如 @holden)在找回页按 name 永远查不到、邮件不发。
+    const accountRef = (raw) => {
+        const display = String(raw || '').trim();
+        return { display, handleRef: display.replace(/^@/, '').toLowerCase() };
+    };
+    // (handle = ? OR name = ?) 子句 + 参数,排除 sys/auditor。
+    const ACCOUNT_MATCH = "(lower(coalesce(handle, '')) = ? OR name = ?) AND id NOT IN ('sys_protocol', ?)";
     // IP 级速率（5/min）— 防爆破列举账户
     const recoverKeyHits = new Map();
     app.post('/api/recover-key', async (req, res) => {
@@ -25,10 +33,11 @@ export function registerRecoverKeyRoutes(app, deps) {
         }
         const { name } = req.body;
         if (!name?.trim())
-            return void res.json({ error: '请填写注册时使用的名称' });
-        const rows = await dbAll("SELECT name, role, api_key, email, phone, created_at FROM users WHERE name = ? AND id NOT IN ('sys_protocol', ?)", [name.trim(), internalAuditorId]);
+            return void res.json({ error: '请填写注册时使用的名称或 @用户名' });
+        const { display, handleRef } = accountRef(name);
+        const rows = await dbAll(`SELECT name, role, api_key, email, phone, created_at FROM users WHERE ${ACCOUNT_MATCH}`, [handleRef, display, internalAuditorId]);
         if (rows.length === 0)
-            return void res.json({ error: '未找到该名称的账号' });
+            return void res.json({ error: '未找到该名称 / @用户名的账号' });
         const mask = (s) => s && s.length > 8 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s;
         const maskEmail = (e) => {
             if (!e)
@@ -60,32 +69,53 @@ export function registerRecoverKeyRoutes(app, deps) {
         const { name, email } = req.body;
         if (!name?.trim() || !email?.trim())
             return void res.json({ error: '请填写名称和邮箱' });
+        if (!canDeliverCodes()) {
+            const unavailable = emailDeliveryNotConfigured();
+            return void res.status(unavailable.status).json({ error: unavailable.error, error_code: unavailable.error_code });
+        }
         const target = email.trim().toLowerCase();
-        const user = await dbOne(`
-      SELECT id, name, email FROM users
-      WHERE name = ? AND email = ? AND email_verified = 1
-        AND id NOT IN ('sys_protocol', ?) LIMIT 1
-    `, [name.trim(), target, internalAuditorId]);
-        if (user)
-            issueCode(user.id, 'email', target, 'recover_key');
-        res.json({
+        const genericResponse = {
             success: true,
             notice: '若该名称与邮箱组合存在，验证码已发送至该邮箱',
             expires_in_min: CODE_TTL_MIN,
-        });
+        };
+        const { display, handleRef } = accountRef(name);
+        const user = await dbOne(`
+      SELECT id, name, email FROM users
+      WHERE ${ACCOUNT_MATCH} AND email = ? AND email_verified = 1 LIMIT 1
+    `, [handleRef, display, internalAuditorId, target]);
+        if (user) {
+            const issued = await issueCode(user.id, 'email', target, 'recover_key');
+            if (!issued.ok) {
+                console.warn(`[recover-key] verification email delivery failed: ${issued.error_code}`);
+                return void res.json(genericResponse);
+            }
+        }
+        res.json(genericResponse);
     });
-    // 步骤 2：提交验证码 → 返回完整 api_key
+    // 步骤 2：提交验证码 → 返回完整 api_key,并可选同时重置登录密码(code + new_password)。
+    // 安全等价:本端点本就返回完整 api_key(最高凭证),允许同时重置密码不扩大权限面 —— 验证码已是同等门槛。
     app.post('/api/recover-key/confirm', async (req, res) => {
-        const { name, email, code } = req.body;
+        const { name, email, code, new_password } = req.body;
         if (!name?.trim() || !email?.trim() || !code?.trim())
             return void res.json({ error: '请填写完整信息' });
+        // 可选新密码:格式与 change-password 一致(≥8,≤200)。先校验格式,失败【不消费验证码】,可重试。
+        const wantsPasswordReset = new_password !== undefined && new_password !== null && String(new_password) !== '';
+        if (wantsPasswordReset) {
+            if (String(new_password).length < 8)
+                return void res.json({ error: '新密码至少 8 字符' });
+            if (String(new_password).length > 200)
+                return void res.json({ error: '密码过长（>200 字符）' });
+        }
         const target = email.trim().toLowerCase();
         const row = findActiveCode('email', target, 'recover_key');
         if (!row)
             return void res.json({ error: '验证码已过期或未发送，请重新开始' });
-        const user = await dbOne(`SELECT id, name, api_key FROM users WHERE id = ?`, [row.user_id]);
-        if (!user || user.name !== name.trim())
-            return void res.json({ error: '名称与验证码不匹配' });
+        const user = await dbOne(`SELECT id, name, handle, api_key FROM users WHERE id = ?`, [row.user_id]);
+        const { display, handleRef } = accountRef(name);
+        const refMatches = !!user && (user.name === display || String(user.handle || '').toLowerCase() === handleRef);
+        if (!user || !refMatches)
+            return void res.json({ error: '名称 / @用户名与验证码不匹配' });
         if (String(row.code) !== code.trim()) {
             const attempts = row.attempts + 1;
             if (attempts >= MAX_CODE_ATTEMPTS) {
@@ -96,6 +126,15 @@ export function registerRecoverKeyRoutes(app, deps) {
             return void res.json({ error: `验证码错误（剩余 ${MAX_CODE_ATTEMPTS - attempts} 次）` });
         }
         await dbRun("UPDATE verification_codes SET used_at = datetime('now') WHERE id = ?", [row.id]);
-        res.json({ success: true, api_key: user.api_key, name: user.name });
+        // optional password reset — same credential gate as returning the api_key, so no extra power.
+        let passwordReset = false;
+        if (wantsPasswordReset) {
+            // mirror /profile/set-password: also clear lock state, else a user who forgot + got locked out by
+            // failed attempts stays locked and "new password is correct but can't log in" (auth-login rejects
+            // locked users before verifying the password).
+            await dbRun("UPDATE users SET password_hash = ?, failed_attempts = 0, locked_until = NULL, updated_at = datetime('now') WHERE id = ?", [hashPassword(String(new_password)), user.id]);
+            passwordReset = true;
+        }
+        res.json({ success: true, api_key: user.api_key, name: user.name, ...(passwordReset ? { password_reset: true } : {}) });
     });
 }

package/dist/pwa/routes/referral.js

@@ -60,14 +60,13 @@ export function registerReferralRoutes(app, deps) {
     });
     // RFC-003 #1122: 生成商品分享链接(把 MCP webaz_share_link 的本地计算搬到服务端,
     // 让 MCP NETWORK 模式可代理)。RFC-002 §3.5 valuation-layer gate:需 rewards opt-in。
-    // 与 PWA pickPreferredSide 对齐的 side 选择(team_count | pv_count)。
+    // pre-public 去左右码:不再接受/返回 side,放置侧别由注册时系统自动决定。
     app.get('/api/share-link', async (req, res) => {
         const user = auth(req, res);
         if (!user)
             return;
         const userId = user.id;
         const productId = String(req.query.product_id || '');
-        const sideArg = String(req.query.side || 'auto');
         if (!productId)
             return void res.status(400).json({ error: 'product_id required', error_code: 'PRODUCT_ID_REQUIRED' });
         const optIn = (await dbOne("SELECT rewards_opted_in FROM users WHERE id = ?", [userId]))?.rewards_opted_in ?? 0;
@@ -101,25 +100,7 @@ export function registerReferralRoutes(app, deps) {
         const product = await dbOne("SELECT id, title, price, commission_rate FROM products WHERE id = ? AND status='active'", [productId]);
         if (!product)
             return void res.status(404).json({ error: '商品不存在或已下架', error_code: 'PRODUCT_NOT_FOUND' });
-        let side = 'right';
-        if (sideArg === 'left' || sideArg === 'right') {
-            side = sideArg;
-        }
-        else {
-            const u = await dbOne("SELECT placement_pref, total_left_pv, total_right_pv, left_count, right_count FROM users WHERE id = ?", [userId]);
-            const pref = u?.placement_pref || 'team_count';
-            if (pref === 'pv_count') {
-                const since = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString().slice(0, 19).replace('T', ' ');
-                const w = (await dbOne(`SELECT COALESCE(SUM(consumed_left_pv),0) AS l, COALESCE(SUM(consumed_right_pv),0) AS r
-                              FROM binary_score_records WHERE user_id = ? AND created_at >= ?`, [userId, since]));
-                const leftPv = Number(u?.total_left_pv ?? 0) + Number(w.l);
-                const rightPv = Number(u?.total_right_pv ?? 0) + Number(w.r);
-                side = leftPv <= rightPv ? 'left' : 'right';
-            }
-            else {
-                side = (Number(u?.left_count ?? 0) <= Number(u?.right_count ?? 0)) ? 'left' : 'right';
-            }
-        }
+        // pre-public 去左右码:分享链接不再计算/携带 side(放置侧别由注册时系统自动决定)
         const completed = (await dbOne("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'", [userId])).n;
         const override = (await dbOne("SELECT l1_share_override FROM users WHERE id = ?", [userId]))?.l1_share_override ?? 0;
         const canL1 = override === 1 || (override === 0 && completed > 0);
@@ -128,13 +109,12 @@ export function registerReferralRoutes(app, deps) {
         const refCode = (await dbOne("SELECT permanent_code FROM users WHERE id = ?", [userId]))?.permanent_code || null;
         if (!refCode)
             return void res.status(409).json({ error: '邀请码暂不可用，请刷新或联系支持', error_code: 'PERMANENT_CODE_MISSING' });
-        const link = `/?ref=${refCode}&side=${side}#order-product/${productId}`;
+        const link = `/?ref=${refCode}#order-product/${productId}`;
         res.json({
             product: { id: product.id, title: product.title, price: product.price, commission_rate: rate },
             share_link: link,
             full_url_hint: 'Prepend webaz.xyz (production) to get the absolute URL',
-            side,
-            binary_explanation: `New user via this link → placed in your ${side === 'left' ? '🔵 left' : '🟢 right'} subtree (tail anchor)`,
+            placement_note: 'New user via this link → placement is recorded automatically by the system (no left/right choice).',
             commission_eligibility: canL1
                 ? `You will earn 3-tier commission: L1=${(rate * 0.70 * 100).toFixed(1)}% L2=${(rate * 0.20 * 100).toFixed(1)}% L3=${(rate * 0.10 * 100).toFixed(1)}% of sale price`
                 : 'You are NOT verified yet (need 1 completed purchase). 3-tier commission will be skipped, but points-matching still builds.',