From 5b6eaddc4f2ac4489cbc7a6ab4c6f6d4dc5dbed1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com>
Date: Sun, 13 Sep 2026 16:20:39 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=E8=A1=A5=E6=AD=A3=E5=BC=8F?=
 =?UTF-8?q?=E5=89=8D=E7=AB=AF=E5=8F=A3=E5=BE=84=E4=B8=8E=E6=9C=80=E6=96=B0?=
 =?UTF-8?q?=E6=B5=8B=E8=AF=95=E5=9F=BA=E7=BA=BF=EF=BC=9Bportal.py=20?=
 =?UTF-8?q?=E6=A0=87=E6=B3=A8=E4=B8=BA=E8=B0=83=E8=AF=95=E5=B7=A5=E5=85=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增前端一节：app/static/portal/ 挂载在 /portal/，四套页面，端点表在 common/api-client.js，
  启动用 uvicorn app.main:app（模块级变量是 app 不是 application）
- 测试基线更新为 2026-09-13 实测：mypy 249 文件 0 错 / 单元+契约 1376 passed / 集成 104 passed
- tools/portal.py 文件头标注降级为跨角色联调工具
---
 AGENTS.md       | 25 ++++++++++++++++---------
 tools/portal.py | 13 ++++++++++++-
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index cb906f4..53cb44d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,13 @@
 > 客服/RAG 那条线的个人分支是 **`NL_develop`**（个人分支 → PR 合回 `qyqy_develop`），**不要再用 `6516ccb`**。
 > 它是对"当前状态"最准确的一份，读完它再读下面这些。
 >
+> **🖥️ 前端（2026-09-13 起）**：**正式前端在 `app/static/portal/`**，由 `app/main.py` 挂载，
+> 通过 **`/portal/`** 访问（`/` 会 307 跳到访客首页）。四套页面：`guest/`（访客，公开产品页
+> 暂时用 `common/mock-data.js` 并在页面上标注）、`customer/`（客户）、`employee-console/`（管理员）、
+> `employee-risk/`（风控）。**端点表集中在 `common/api-client.js`**，改接口调用请改那一份。
+> 启动：`python -m uvicorn app.main:app --port 8000`（注意模块级变量是 **`app`**，不是 `application`）。
+> `tools/portal.py`（8101）**只是跨角色联调工具，不是产品前端**，不要再往它加功能。
+>
 > **⚠️ 文档现状（2026-09-11 第二次修订）**：本文件原先声明"已删除 5 份编号文档"，
 > 那条**已作废** —— 经评审，`docs/04`/`06`/`10`/`13`/`99` **全部保留**（架构师明确要求保留：
 > 删除收益为零，而保留成本同样为零）。它们的内容**未被核对过、可能过期**，
@@ -115,16 +122,16 @@
   —— Worker 既要重建画像又要处理投顾问卷，因此**真的被打挂过**（库里 `memory_sync_outbox`
   留下 `last_error='InvalidRequestError'` 的行）。2026-09-12 已修为 re-export，见 `docs/37` §6.2。
   **新增模型前先搜一遍 `__tablename__` 有没有被占用。**
-- 测试基线（**2026-09-12 合并主干 PR #7 + 本线记忆投影链路之后实测**）：
-  `mypy app` → **245 个文件 0 错**；
-  `pytest tests`（全量）→ `2 failed, 1415 passed, 2 skipped`；
-  `pytest tests/integration` → `102 passed, 1 skipped`。
+- 测试基线（**2026-09-13 合并组员前端提交之后实测**）：
+  `mypy app` → **249 个文件 0 错**；
+  `pytest tests/unit tests/contract` → **1376 passed, 2 skipped, 0 failed**；
+  `pytest tests/integration` → **104 passed**；
+  `python tools/audit_schema.py` → **89 张业务表**。
   ⚠️ **用例数会随开发增减，判断健康看"0 failed"而不是看绝对值**。
-  剩下那 2 个失败**都不是代码缺陷**，接手时不要"修"它们：
-  `tests/unit/service/test_offsite_document_recognition_adapter.py` 的 2 个用例 —— **环境相关**：
-  它们断言请求体里是中文原文，而 httpx 会把中文序列化成 `\uXXXX`，字节序列自然不匹配。
-  功能无影响；若要修，正确做法是断言 `json.loads(body)` 后的字段值（字节级断言不该用来测 JSON）。
-- **mypy：`mypy app` → `Success: no issues found in 245 source files`（0 错）。**
+  另：`tests/unit/service/test_offsite_document_recognition_adapter.py` 有 2 个用例在某些环境
+  会失败 —— 它们断言请求体里是中文原文，而 httpx 会把中文序列化成 `\uXXXX`，属**环境相关**，
+  不要"修"实现；真要修应改为断言 `json.loads(body)` 后的字段值。
+- **mypy：`mypy app` → `Success: no issues found in 249 source files`（0 错）。**
   ⚠️ 曾在本机报 184 个错，**已查明是环境版本旧**，与代码质量无关 —— 复现矩阵：
 
   | SQLAlchemy | mypy | 报错数 |
diff --git a/tools/portal.py b/tools/portal.py
index 8a374a4..2f14af6 100644
--- a/tools/portal.py
+++ b/tools/portal.py
@@ -1,4 +1,15 @@
-"""统一登录门户：一个登录入口，按角色分流到不同的工作台。
+"""统一登录门户（**调试/联调工具**，不是产品前端）。
+
+> ⚠️ **定位说明（2026-09-13）**：正式前端已由组员交付并合入主干，位于
+> `app/static/portal/`，通过 **`/portal/`** 访问（访客 / 客户 / 员工 / 风控四套页面；
+> 端点表见 `app/static/portal/common/api-client.js`）。
+> **本文件不是产品的一部分**，它是平台侧保留的**跨角色快速联调工具**：
+> 一个页面里用五个演示账号登录、直接点各模块接口、看原始响应与错误码。
+> 涉及具体页面与交互的工作请改正式前端，不要再往这里加功能。
+
+---
+
+一个登录入口，按角色分流到不同的工作台。
 
 **和 `tools/chat_console.py` 的区别**：那个控制台没有登录、身份写死在命令行里；
 本门户**走真实的 `POST /api/v1/auth/tokens`**，令牌只存活在本进程，浏览器拿不到，