hoelee/alist-serve-resource
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fd62775fcd7fc717b9b48c1aefd310a7f12395c9
alist-serve-resource/docs/PROJECT_STATE.md
T
hoelee fd62775fcd chore: agent entrypoint + centralized secrets + slimmer handoff doc 
- AGENTS.md: AI session entrypoint (task routing table + iron rules)
- SECRETS.md: single credentials file; distributing the project to
  others = delete this one file
- PROJECT_STATE.md: 190 -> 70 lines, credential quick-ref block removed
  (points to SECRETS.md), incident postmortems kept, pitfall details
  delegated to skill/API_INTEGRATION
2026-08-24 22:05:59 +08:00

6.1 KiB
Raw Blame History

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 概念）—— 已确认
Reference in New Issue View Git Blame Copy Permalink