# Project State (Handoff) — 2026-08-24

> 交接文档：压缩/新会话后按此续做。**入口顺序：AGENTS.md → 本文件 → SECRETS.md(凭据)。**
> 本文件只记「状态与下一步」；API 怪癖/坑的唯一权威 = Hermes skill `alist-serve-resource` + `docs/API_INTEGRATION.md`。

## 凭据
全部集中在根目录 **`SECRETS.md`**（唯一凭据文件；把项目给别人 = 删它即可）。
表 ID / workflow ID 不是机密，见 `docs/DATABASE_SCHEMA.md` 与下文。

## 系统现状（2026-08-24 实测）
- 容器全绿：`alist-serve-resource`(healthy) · `nocodb` · `n8n`
- W1–W4 四个 workflow 激活正常（postgres 复核 `activeVersionId` 全对齐）
- **n8n「执行消失」已结案**：容器 env `EXECUTIONS_DATA_SAVE_ON_SUCCESS=none`，成功执行不落库是配置使然，管道健康（详见下方结案记录）
- NocoDB 数据：Products 176 / Resources 171（商品目录健在）；Customers / CustomerProducts / AccessGrants / ReconcileLogs = **0**（旧测试数据已被清空）
- AList 已清理至干净态：仅 guest/hoelee 用户 + guest/admin 角色

## 已完成 ✅（细节见各 DESIGN 文档与 git log）
1. **Phase 1** AList stock v3.63.0 :5244（bridge_hoelee，4 只读挂载；旧 alist :5243 未处理）
2. **Phase 2** NocoDB base `AlistAccess`(`p3lzkresswyowqg`) 8 表（7 业务 + ReconcileLogs）；脚本 `scripts/create_nocodb_schema.py` / `add_reconcilelogs_table.py`
3. **W1** 客户开通 + 5 状态 lifecycle（pending/active/suspended/expired/deleted）— 实测跑通；old/new 字段比对 loop guard + `sync_required` 强制重算 + writeBack 值比对守卫（`test_w1_lifecycle.js` 10 场景全过）
4. **W2** CustomerProduct 权限同步（调共享算法）— 实测跑通
5. **W3** 每 5 分钟 expiry sweep（`W3_DRY_RUN` / `ALIST_AUTO_DISABLE_ON_EXPIRE` 开关）— 实测跑通
6. **共享库** `n8n/shared/effective-grants.js` 单一事实源，构建期内联（`gen_w*.js`），三 workflow 零复制算法；union 语义：CP 派生 ∪ AccessGrants，同 path 取 MAX(expires_at)，expiry 边界 `<= today`
7. **W4** 每日 03:00 全量对账 + ReconcileLogs 审计 — 本地 + 直连生产实测通过（dry-run→repair→复跑幂等；34 项 mock 测试过）；单向同步 NocoDB=SOT，密码不随 repair 推送（方案 C）
8. 文档体系：ARCHITECTURE / PERMISSIONS / ADMIN_GUIDE / DATABASE_SCHEMA / N8N_WORKFLOWS 等；git 已推 Gitea

## 🔴 下一步（按序）
1. **端到端实测（最优先）**：建测试客户走完 W1(provision)→W2(sync)→W3(sweep)。验证看 AList/NocoDB 的实际状态变化，别数 executions 表
2. **补 n8n env 并 rebuild（Portainer stack 144）**：`NOCODB_TABLE_RECONCILELOGS=mktsb7le6fqr2u1` + `NOCODB_FK_RECONCILELOG_CUSTOMER=nc_jitu___Customers_id`（改 env 必须 rebuild，restart 无效）
3. AccessGrants 不物化（保持手工人为授权入口，n8n 永不写）— 已定案
4. 密码保持方案 C（客户可自改 AList 密码 → NocoDB plaintext 失真；不强制回写）
5. 公网域名 `nocodb.hoelee.com` 连通未恢复（DSM 内网端口全正常）— 待查 DNS / 隧道

## 结案记录
- **n8n 执行管道停摆（08-23 报告 → 08-24 结案，误报）**
  - 现象：webhook 全 200 但 executions 表零记录、schedule 无痕迹
  - 根因：`EXECUTIONS_DATA_SAVE_ON_SUCCESS=none` → 成功执行从不落库，只有 error 会记（期间唯一入库记录恰是一条无关备份 workflow 的 error，完全吻合）
  - 时间线：最后 success 记录 08-22 23:00:51Z ≈ 容器重建（08-23 01:21Z Started）前后；激活错位（activeVersionId）已在重建后修复
  - 若要恢复可见性：env 改 `all` / `all-with-logs`（EXECUTIONS_DATA_PRUNE 已配，不会无限涨）
  - 另注：DSM IP 已漂移为 `192.168.137.2`；Windows 直连内网端口（AList 5244 / NocoDB 10380 / n8n 5678）均通

## ⚠️ 坑速览（一行版；详情看 skill `alist-serve-resource` Pitfalls + API_INTEGRATION.md）
- AList：空 role 建用户必 400（先建 role）｜base_path 必须 `/` 否则双重前缀全 403｜delete 用 `?id=`｜裸 token 无 Bearer
- NocoDB：link 查询必须 `(link.Id,eq,N)`｜写 bt 链接要写 FK 列 `nc_jitu___*_id`｜删行 DELETE+body｜v1 列端点已废｜SingleSelect 先建空列再 PATCH
- n8n：Code 节点 `$env` 可用、HTTP 表达式不行（Load Env 模式）｜API 导入节点 id 必须 UUID 且顶层无 pinData｜webhook 节点缺 webhookId 则生产 URL 不注册｜激活真标志=DB 的 activeVersionId｜执行消失假象=SAVE_ON_SUCCESS
- 环境：DSM IP 会漂移（连不上先探测）｜DSM sshd 无 SFTP（POST body 用 stdin pipe 传）

> **Status 语义已定稿**：`pending/active/suspended/expired/deleted`，account-level 整户开关，
> **不进** permission calc。详见 `docs/ARCHITECTURE.md`、`docs/PERMISSIONS.md`、`docs/DATABASE_SCHEMA.md`。

## 项目结构
```
alist-serve-resource/
├── AGENTS.md            ← 🤖 AI 会话入口（任务路由 + 铁律，开工先读）
├── SECRETS.md           ← 🔑 唯一凭据文件（外发 = 删除此文件）
├── docker-compose.yml / .env.example / .gitignore
├── n8n/
│   ├── W1..W4-*.json (生成物，勿手编) · w1..w4-body.js (运行时逻辑源头)
│   ├── shared/effective-grants.js (算法单一事实源) · gen_w1..w4.js + inline_shared.js (构建)
│   ├── test_*.js · SETUP.md · W2/W3/W4-DESIGN.md
├── scripts/  create_nocodb_schema.py · add_reconcilelogs_table.py · live_dry_run_w4.js · healthcheck.sh
└── docs/  API_INTEGRATION · ARCHITECTURE · PERMISSIONS · ADMIN_GUIDE · DATABASE_SCHEMA ·
          N8N_WORKFLOWS · PROJECT_STATE(本文件) · INSTALL · CONFIGURATION · SECURITY ·
          BACKUP_RESTORE · UPGRADE · TROUBLESHOOTING · W4-DESIGN
```

## 待确认的设计点
1. AccessGrants 物化 —— **定案：不物化**（手工人为授权入口，n8n 永不写）
2. 密码失真 —— **定案：方案 C**（不强制回写；W4 repair 不推密码，仅 provision 新建时用）
3. 对账/到期只靠 n8n 定时扫描（AList 无 expiry 概念）—— 已确认