merge sandbox/edd39ac: chg_0007 lite_demo_restore — 补回 lite-react book/shop demo (TypeORM-free, 33+17+16=66 e2e PASS)

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
xstudio agentandClaude Code committed 2026-09-28 17:03:01 +08:00
1 parent 1c2f3ba234
commit df62c960f0
17 files changed
+1617 -2

No files matched your search

+196
View File
@@ -0,0 +1,196 @@
# lite-demo design (chg_0007)
> 补回 ssw-jnpf-lite-react skill 自带的 book / shop demo 模块。
> 适配 dth workspace 的 TypeORM-free 后端栈,与 chg_0006 LMS 同形。
## 1. 背景
`chg_0001` 起骨架时容器内 `~/.claude/skills/` 软链断裂(见
`docs/superpowers/learnings/2026-09-28-dispatch-session.md` §A-1),骨架 agent
没找到 `ssw-jnpf-lite-react` skill,改为手写最小 NestJS,**丢了 book / shop /
dashboard demo 模块**。chg_0006 LMS、chg_0002 experiment 落地后,业务特定形态
有了,但"通用业务模块参考实现"仍然是缺的——
- 新人 `git clone` 跟进本仓库,看不到一个完整的"实体 CRUD + 鉴权 + 软删"
端到端参考实现。
- `HOWTO_MODULE.md` 引用的 demo 用例是 `book` + `shop`,缺失让文档与现实脱节。
- 后续 chg(如 SP-3 课程内容、SP-4 LMS 高级特性)很可能需要"通用业务模块"
形态作为参照。
`chg_0007` 的目标就是把 `book` + `shop` 这两个 MVP 演示模块补回来。
## 3. TypeORM-free 选型理由
skill 自带 backend 用 TypeORM(`@nestjs/typeorm` + `Repository<Book>` +
装饰器实体)。**直接复制粘贴会与 dth 后端栈冲突**:
| 维度 | dth 后端(现状) | skill 原生 |
|---|---|---|
| ORM | pglite + `getDb()` 直查(chg_0006 LMS 模式) | TypeORM + Repository |
| 实体定义 | interface + 静态类型 | `@Entity()` + `@Column()` |
| 鉴权 | `JwtAuthGuard` + `RequireAdmin()`(admin-only CRUD) | 同上 |
| 表名前缀 | `lms_` / `dth_` / `book_shop_` 三套并存 | 单一 `{app_code}_` 前缀 |
| 响应壳 | `{code, msg, data}` ActionResultFilter | 同 |
本仓库 `package.json` 没有 `typeorm` / `@nestjs/typeorm` 依赖,复制装饰器
后会在 `tsc --noEmit` 阶段就挂掉(找不到 `typeorm` 模块)。因此采用与 chg_0006
完全对齐的"getDb() 直查"模式:
```typescript
// src/backend/src/books/book.service.ts
import { getDb } from '../common/pglite/init';
@Injectable()
export class BooksService {
async list(): Promise<BookRow[]> {
const db = getDb();
const { rows } = await db.query<BookRow>(
`SELECT * FROM book_shop_book WHERE f_delete_mark = 0 ORDER BY f_creator_time DESC`,
);
return rows;
}
}
```
**不引入**:`typeorm`, `@nestjs/typeorm`, `@nestjsx/crud`, `class-transformer`
之外的运行时依赖。
## 4. 模块命名(与 HOWTO_MODULE.md §零 一字不差)
```
业务名:图书超市
→ appCode = books
→ 文件夹 = src/backend/src/books/
→ 表名 = book_shop_book # JNPF 表名规则 {appCode}_{Entity_lower}
→ 端点 Entity = Book
→ urlAddress = books/Book
→ 前端 Route = /books/Book
→ 前端视图文件 = Book.tsx
→ 前端 api 文件 = api/book.ts
业务名:超市
→ appCode = books (复用 books appCode,表名前缀仍为 book_shop_)
→ Entity = Product
→ urlAddress = books/Product
→ 前端视图文件 = Product.tsx
→ 前端 api 文件 = api/product.ts
```
注:dth 后端鉴权简化(仅 admin/non-admin 二值,无 RBAC),所有 CRUD 用 admin
token 调通即可;前端菜单按 urlAddress 注册。
## 5. 表设计(`f_*` 前缀 + `f_id varchar(50)` + `f_delete_mark` 软删)
```sql
CREATE TABLE book_shop_book (
f_id VARCHAR(50) PRIMARY KEY,
f_title TEXT NOT NULL,
f_author TEXT,
f_isbn TEXT,
f_category TEXT,
f_price NUMERIC(10,2),
f_stock INTEGER DEFAULT 0,
f_creator_user_id TEXT,
f_creator_time TIMESTAMP NOT NULL DEFAULT NOW(),
f_delete_mark INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE book_shop_product (
f_id VARCHAR(50) PRIMARY KEY,
f_name TEXT NOT NULL,
f_sku TEXT,
f_category TEXT,
f_price NUMERIC(10,2),
f_stock INTEGER DEFAULT 0,
f_creator_user_id TEXT,
f_creator_time TIMESTAMP NOT NULL DEFAULT NOW(),
f_delete_mark INTEGER NOT NULL DEFAULT 0
);
```
`f_delete_mark = 0` 表示未删除;list 查询固定 `WHERE f_delete_mark = 0`;
remove 接口固定 `UPDATE ... SET f_delete_mark = 1`,**不真删**(保留审计
痕迹,符合 JNPF `f_delete_mark` 约定)。
## 6. 端点形态(JNPF 风格,5 个动词 × 2 个 Entity)
```
POST /api/ssw/dth/books/Book/List # 列表
POST /api/ssw/dth/books/Book/Create # 新建
POST /api/ssw/dth/books/Book/Update # 更新
POST /api/ssw/dth/books/Book/Remove # 软删
POST /api/ssw/dth/books/Book/getInfo # 详情(按 body.id)
POST /api/ssw/dth/books/Product/List # 同上五件套
POST /api/ssw/dth/books/Product/Create
POST /api/ssw/dth/books/Product/Update
POST /api/ssw/dth/books/Product/Remove
POST /api/ssw/dth/books/Product/getInfo
```
与 chg_0006 LMS(RESTful 风格 `GET /api/ssw/dth/lms/students`)的差异:
lite-demo 严格遵循 JNPF "动词放 URL" 风格,便于 skill 模板对照;guard 与
envelope 完全一致。
## 7. 与 chg_0006 LMS 一致性说明
| 维度 | chg_0006 LMS | chg_0007 lite-demo |
|---|---|---|
| 后端栈 | NestJS + pglite + `getDb()` | 完全相同 |
| 鉴权 | `JwtAuthGuard` + `@RequireAdmin()` | 完全相同 |
| 响应壳 | `{code, msg, data}` via ActionResultFilter | 完全相同 |
| 软删约定 | `DELETE FROM ...` 真删 | `f_delete_mark = 1` 软删(JNPF 约定) |
| 表前缀 | `lms_*` | `book_shop_*` |
| 端点动词 | RESTful(GET/POST/PUT/DELETE) | JNPF 风格(POST + 动词 URL) |
| 实体形态 | interface(无装饰器) | interface(无装饰器) |
| 种子数据 | 2 students + 2 courses(chg_0006 spec) | 3 books + 3 products(chg_0007 spec) |
唯一的差别是"硬删 vs 软删"——这是 chg_0007 spec §S4 明确要求的 JNPF
约定;spec 已写死,本文档不重新决策。
## 8. 改动文件清单
```
docs/dth/lite-demo/design.md # 本文件
src/backend/src/books/
book.entity.ts interface BookRow + 静态类型
book.service.ts list/create/update/getInfo/remove
book.controller.ts POST 5 个端点 + JwtAuthGuard + RequireAdmin
books.module.ts Module({ providers, controllers })
src/backend/src/shop/
product.entity.ts interface ProductRow
product.service.ts list/create/update/getInfo/remove
product.controller.ts POST 5 个端点
shop.module.ts
src/backend/src/common/pglite/init.ts
# 追加 book_shop_book + book_shop_product 两张表 + 6 行 seed
src/backend/src/app.module.ts
# 追加 imports + modules: [BooksModule, ShopModule]
src/frontend/src/api/book.ts # axios 调用封装
src/frontend/src/api/product.ts
src/frontend/src/views/Book.tsx # 列表 + 新建/编辑表单
src/frontend/src/views/Product.tsx
src/frontend/src/App.tsx # 加 2 条 Route
tests/e2e/dth_lite_demo.test.sh # C1-C8
```
## 9. 不做的清单(与 chg_0007 proposal.md 一致)
- 不复制 skill 的 sys/UserManage/RoleManage/MenuManage(dth 已有简化 auth)
- 不复制 skill 的 typeorm 依赖
- 不动 experiment / LMS / auth(契约红线)
- 不做前端 Dashboard 实时数据
- 不引 typeorm / @nestjs/typeorm / jnpf-* / ssw-* 共享模块
## 10. 风险与回退
- **mount 不可用 / tsc 不通 / pglite init seed 失败** → 立即回退给 host,
不硬改 `tsconfig` 或绕过 gate(openspec §实施步骤约定 3)。
- **pglite 表名冲突** → 已确认 `book_shop_book` / `book_shop_product` 与
LMS(`lms_*`)/ experiment(`dth_*`)不冲突。
- **admin token 鉴权重定向** → JwtAuthGuard + RequireAdmin() 与 chg_0006
完全相同,e2e 已验证。
---
变更锚点:`openspec/changes/chg_0007_lite_demo_restore/{proposal.md,spec.md,tasks.md,testcases.md}`
相关:chg_0006 LMS(TypeORM-free 参考实现)、chg_0005 experiment extend