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:
1 parent
1c2f3ba234
commit
df62c960f0
17 files changed
+1617
-2
No files matched your search
@@ -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
|
||||
Reference in new issue
Block a user